@reekon-tools/boldr-cad 0.1.0 → 1.0.0

package/src/render/linkTile.ts

@@ -0,0 +1,297 @@
+import { LINK_PIN_PX, LINK_TILE_PX } from '../model/links';
+import { noteLook } from '../model/markup';
+import type { LinkInfo, Note } from '../model/types';
+import type { DrawCtx } from './ctx';
+import { strokeMarkup } from './markup';
+import { smoothRectPath } from './squircle';
+import { FONT, TH } from './theme';
+import { cvs, leaderPath, linkBox, linkThumb, type ImageLike, type LinkBox, type Xform } from './view';
+
+/*
+  A link's tile on the plan: a square card for one of the job's files (a photo's picture edge to edge; anything else's
+  picture, or an icon for its kind, above its name) or measurements (its value and name), and its leader — a line in the markup's look from the card's edge to
+  what it points at. The card is laid out once at LINK_TILE_PX and scaled to its size on the drawing, so its shapes and
+  text are the same at every step of a pinch (kept, on a device). Small on the screen it shows less: its picture or
+  icon alone, then a pin of a fixed size. Where it is on the screen (and its handles) is view.ts's, and picking it
+  hit.ts's.
+*/
+
+export interface LinkDrawOpts {
+  selected: boolean;
+  alpha: number;
+  /** what the host says it is now (none yet: what it was when linked) */
+  info?: LinkInfo;
+}
+
+/** Draw tile `n` and its leader. */
+export function drawLink(c: DrawCtx, T: Xform, n: Note, o: LinkDrawOpts): void {
+  const b = linkBox(T, n), lp = leaderPath(T, n, b);
+  c.save();
+  c.globalAlpha = o.alpha;
+  // (under the card, which covers where it starts)
+  if (lp) strokeMarkup(c, lp, noteLook(n), o.selected ? 'rgba(255,173,0,.45)' : undefined);
+  if (b.lod === 'pin') drawPin(c, b, n, o);
+  else drawCard(c, b, n, o);
+  c.restore();
+}
+
+/**
+ * A line `px` wide on the screen, in the layout of a card at scale `k` — in steps, four to each doubling of the zoom
+ * (within a fifth of `px`): a pinch draws with the same few paints, on a device, not a new one at every step.
+ */
+const screenW = (px: number, k: number): number => Math.pow(2, Math.round(Math.log2(px / k) * 4) / 4);
+
+/** The layout's side, and its rounding; how wide a selected tile's ring is outside its edge (pt). */
+const L = LINK_TILE_PX, R = 12, SELECT_W = 3;
+
+/** A rounded rectangle's path, one shape for each size (as draw.ts's rr: kept by an engine that can). */
+function rr(c: DrawCtx, x: number, y: number, w: number, h: number, r: number): void {
+  if (c.shape) c.shape('rr ' + w + ' ' + h + ' ' + r, x, y, (cc, X, Y) => smoothRectPath(cc, X, Y, w, h, r));
+  else smoothRectPath(c, x, y, w, h, r);
+}
+
+/** The kind of thing a tile is for, as its icon shows it. */
+type Glyph = 'photo' | 'pdf' | 'document' | 'note' | 'calculator' | 'label' | 'drawing' | 'tape' | 'removed';
+const glyphOf = (n: Note, info?: LinkInfo): Glyph => {
+  if (info?.exists === false) return 'removed';
+  if (n.link!.kind === 'measurement') return 'tape';
+  const t = info?.fileType ?? n.link!.fileType;
+  return t === 'photo' || t === 'pdf' || t === 'note' || t === 'calculator' || t === 'label' || t === 'drawing' ? t : 'document';
+};
+
+function drawCard(c: DrawCtx, b: LinkBox, n: Note, o: LinkDrawOpts): void {
+  const k = b.k, t = n.link!, info = o.info, gone = info?.exists === false, glyph = glyphOf(n, info);
+  c.save();
+  c.translate(b.x, b.y);
+  c.scale(k, k);
+  rr(c, 0, 0, L, L, R);
+  // selected: a yellow ring round the card's edge, the same 3 pt at any size — stroked twice as wide on the card's own
+  // outline before it's filled, so the card covers the inside half (and no new shape is made as it zooms)
+  if (o.selected) { c.lineWidth = screenW(2 * SELECT_W, k); c.strokeStyle = TH.yellow; c.stroke(); }
+  c.fillStyle = gone ? TH.chip : TH.badge; c.fill();
+  if (!o.selected) { c.lineWidth = screenW(1, k); c.strokeStyle = TH.badgeline; c.stroke(); }
+  // (its picture asked for only near the screen: a drawing can link more than are kept)
+  const near = b.x < cvs.W * 2 && b.y < cvs.H * 2 && b.x + b.s > -cvs.W && b.y + b.s > -cvs.H;
+  const pic = near && !gone && t.kind === 'file' && info?.thumbUrl ? linkThumb(info.thumbUrl) : null, shown = pic && pic.complete && pic.naturalWidth > 0;
+  // a photo is its picture, edge to edge — it says what it is (until it's loaded: its icon and name, as any file)
+  const photo = shown && glyph === 'photo';
+  if (photo) cover(c, pic, 0, 0, L, L, R);
+  else if (b.lod === 'compact') {
+    // the picture or the icon alone
+    if (shown) cover(c, pic, 6, 6, L - 12, L - 12, R - 4);
+    else drawGlyph(c, glyph, L / 2, L / 2, 46, TH.ink2);
+  } else if (t.kind === 'measurement' && !gone) {
+    // its value, and its name
+    drawGlyph(c, 'tape', 18, 17, 18, TH.ink2);
+    const value = info?.text ?? t.text ?? '—';
+    c.font = '700 18px ' + FONT; c.fillStyle = TH.blue; c.textAlign = 'center'; c.textBaseline = 'middle';
+    c.fillText(fit(c, value, L - 12), L / 2, 46);
+    drawName(c, k, info?.name ?? t.name ?? 'Measurement', 75, L - 14, TH.ink2, false);
+  } else if (gone) {
+    // the removed mark, and what it was
+    drawGlyph(c, glyph, L / 2, 30, 28, TH.ink2);
+    c.font = '700 11px ' + FONT; c.fillStyle = TH.ink2; c.textAlign = 'center'; c.textBaseline = 'middle';
+    c.fillText('Removed', L / 2, 58);
+    drawName(c, k, t.name ?? (t.kind === 'file' ? 'File' : 'Measurement'), 79, L - 12, TH.ink2, false);
+  } else {
+    // its picture or icon above, its name below
+    if (shown) cover(c, pic, 6, 6, L - 12, 62, R - 4);
+    else {
+      const a = c.globalAlpha;
+      rr(c, 6, 6, L - 12, 62, R - 4);
+      c.fillStyle = TH.chip; c.globalAlpha = a * 0.5; c.fill(); c.globalAlpha = a;
+      drawGlyph(c, glyph, L / 2, 37, 34, TH.ink2);
+    }
+    drawName(c, k, info?.name ?? t.name ?? 'File', 81, L - 12, TH.ink, true);
+  }
+  c.restore();
+}
+
+/** Far out, a tile is a pin: a small fixed-size card with its icon. */
+function drawPin(c: DrawCtx, b: LinkBox, n: Note, o: LinkDrawOpts): void {
+  const s = LINK_PIN_PX;
+  rr(c, b.cx - s / 2, b.cy - s / 2, s, s, 6);
+  // (selected: ringed round its edge, as a card is)
+  if (o.selected) { c.lineWidth = 2 * SELECT_W; c.strokeStyle = TH.yellow; c.stroke(); }
+  c.fillStyle = o.info?.exists === false ? TH.chip : TH.badge; c.fill();
+  if (!o.selected) { c.lineWidth = 1; c.strokeStyle = TH.badgeline; c.stroke(); }
+  drawGlyph(c, glyphOf(n, o.info), b.cx, b.cy, 14, TH.ink2);
+}
+
+/** A picture filling the rounded rectangle x, y, w, h (its middle shown, its sides cut off). */
+function cover(c: DrawCtx, im: ImageLike, x: number, y: number, w: number, h: number, r: number): void {
+  const iw = im.naturalWidth, ih = im.naturalHeight || 1, k = Math.max(w / iw, h / ih), dw = iw * k, dh = ih * k;
+  c.save();
+  rr(c, x, y, w, h, r);
+  c.clip();
+  c.drawImage(im, x + (w - dw) / 2, y + (h - dh) / 2, dw, dh);
+  c.restore();
+}
+
+/*
+  A name grows with its card until it's NAME_MAX_PX on the screen; past that it stays that size, and the card, wider on
+  the screen as it's zoomed in, shows more of it — in the end all of it: on two even lines once two show the whole of it
+  (the strip under a picture always has the room by then), and on one once one does. Each name is measured once, at
+  each of its two sizes: laying it out again at another width, every step of a pinch, measures nothing.
+*/
+const NAME_PX = 11, NAME_MAX_PX = 14, NAME_LINE = 1.25;
+
+/** A name's prefixes' widths at a font (w[i]: its first i characters), and an ellipsis's. */
+const prefixes = new Map<string, { w: number[]; ell: number }>();
+function widthsOf(c: DrawCtx, text: string): { w: number[]; ell: number } {
+  const key = c.font + '|' + text;
+  let p = prefixes.get(key);
+  if (p) return p;
+  const w = [0];
+  for (let i = 1; i <= text.length; i++) w.push(c.measureText(text.slice(0, i)).width);
+  p = { w, ell: c.measureText('…').width };
+  if (prefixes.size > 1000) prefixes.clear();
+  prefixes.set(key, p);
+  return p;
+}
+
+/** The most of `text` that fits `maxW` at the current font: all of it, or its start and an ellipsis. */
+export function fitName(c: DrawCtx, text: string, maxW: number): string {
+  const { w, ell } = widthsOf(c, text), n = text.length;
+  if (w[n] <= maxW) return text;
+  let lo = 0, hi = n;
+  while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (w[mid] + ell <= maxW) lo = mid; else hi = mid - 1; }
+  return text.slice(0, lo).trimEnd() + '…';
+}
+
+/**
+ * Where a name breaks onto two lines: at the space nearest half its width (with none, after the _ - . or / nearest it;
+ * with none of those, halfway across), so the two are even — and the same however wide its tile, so zooming never
+ * moves the break. `width`: the wider of the two lines.
+ */
+const splits = new Map<string, { cut: number; next: number; width: number }>();
+function splitOf(c: DrawCtx, text: string): { cut: number; next: number; width: number } {
+  const key = c.font + '|' + text;
+  let sp = splits.get(key);
+  if (sp) return sp;
+  const { w } = widthsOf(c, text), n = text.length, total = w[n];
+  sp = { cut: 0, next: 0, width: Infinity };
+  for (let i = 1; i < n - 1; i++) {
+    if (text[i] !== ' ') continue;
+    const width = Math.max(w[i], total - w[i + 1]);
+    if (width < sp.width) sp = { cut: i, next: i + 1, width };
+  }
+  // (no space, as a file's name often has none: after a _ - . or /, which stays on the first line)
+  if (!sp.cut) for (let i = 2; i < n - 1; i++) {
+    if (!'_-./'.includes(text[i - 1])) continue;
+    const width = Math.max(w[i], total - w[i]);
+    if (width < sp.width) sp = { cut: i, next: i, width };
+  }
+  if (!sp.cut) {
+    let i = 1;
+    while (i < n - 1 && w[i] < total / 2) i++;
+    sp = { cut: i, next: i, width: Math.max(w[i], total - w[i]) };
+  }
+  if (splits.size > 1000) splits.clear();
+  splits.set(key, sp);
+  return sp;
+}
+
+/** All of `text` on two lines `maxW` wide, evenly (see splitOf); null if one line takes it, or two can't. */
+export function twoLines(c: DrawCtx, text: string, maxW: number): [string, string] | null {
+  const n = text.length;
+  if (n < 2 || widthsOf(c, text).w[n] <= maxW) return null;
+  const sp = splitOf(c, text);
+  return sp.width <= maxW ? [text.slice(0, sp.cut).trimEnd(), text.slice(sp.next).trimStart()] : null;
+}
+
+/**
+ * A name on card `k` (its scale from the layout), centred on `y` and at most `maxW` wide in the layout: the layout's
+ * size until that's NAME_MAX_PX on the screen; past it, that size on the screen (drawn at the screen's own scale, so one
+ * font does), showing more of the name as the card grows — and with `wrap`, on two lines once two show all of it.
+ */
+function drawName(c: DrawCtx, k: number, text: string, y: number, maxW: number, color: string, wrap: boolean): void {
+  c.fillStyle = color; c.textAlign = 'center'; c.textBaseline = 'middle';
+  if (NAME_PX * k <= NAME_MAX_PX) {
+    c.font = '600 ' + NAME_PX + 'px ' + FONT;
+    c.fillText(fitName(c, text, maxW), L / 2, y);
+    return;
+  }
+  c.save();
+  c.scale(1 / k, 1 / k);
+  c.font = '600 ' + NAME_MAX_PX + 'px ' + FONT;
+  const W = maxW * k, x = (L / 2) * k, one = fitName(c, text, W);
+  const two = wrap && one !== text ? twoLines(c, text, W) : null;
+  if (two) {
+    // (centred in the strip under the picture: from 68 to the card's foot)
+    const h = NAME_MAX_PX * NAME_LINE, mid = 82 * k;
+    c.fillText(two[0], x, mid - h / 2);
+    c.fillText(two[1], x, mid + h / 2);
+  } else c.fillText(one, x, y * k);
+  c.restore();
+}
+
+/** Names cut to fit, by font, width and text: measured once, not every frame. */
+const fitted = new Map<string, string>();
+function fit(c: DrawCtx, text: string, maxW: number): string {
+  const key = c.font + '|' + maxW + '|' + text;
+  let out = fitted.get(key);
+  if (out != null) return out;
+  out = text;
+  if (c.measureText(text).width > maxW) {
+    let lo = 0, hi = text.length;
+    while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (c.measureText(text.slice(0, mid) + '…').width <= maxW) lo = mid; else hi = mid - 1; }
+    out = text.slice(0, lo).trimEnd() + '…';
+  }
+  if (fitted.size > 1000) fitted.clear();
+  fitted.set(key, out);
+  return out;
+}
+
+/** A glyph's parts on a 24-unit square: what's stroked (dashed, then solid), what's filled, and a word. */
+interface GlyphDraw { dashed?: (c: DrawCtx) => void; stroke?: (c: DrawCtx) => void; fill?: (c: DrawCtx) => void; text?: string }
+
+const page = (c: DrawCtx, fold: boolean) => {
+  c.moveTo(6, 3); c.lineTo(fold ? 14 : 18, 3);
+  if (fold) c.lineTo(18, 7);
+  c.lineTo(18, 21); c.lineTo(6, 21); c.closePath();
+  if (fold) { c.moveTo(14, 3); c.lineTo(14, 7); c.lineTo(18, 7); }
+};
+const rules = (c: DrawCtx, ys: number[]) => { for (const y of ys) { c.moveTo(9, y); c.lineTo(15, y); } };
+const dots = (c: DrawCtx, at: [number, number][], r: number) => { for (const [x, y] of at) { c.moveTo(x + r, y); c.arc(x, y, r, 0, Math.PI * 2); } };
+
+const GLYPHS: Record<Glyph, GlyphDraw> = {
+  photo: {
+    stroke: c => { c.roundRect(3, 5, 18, 14, 2); c.moveTo(5, 17); c.lineTo(10, 11); c.lineTo(13, 14); c.lineTo(15, 12); c.lineTo(19, 17); },
+    fill: c => dots(c, [[16, 9]], 1.6),
+  },
+  pdf: { stroke: c => page(c, true), text: 'PDF' },
+  note: { stroke: c => { page(c, false); rules(c, [8, 12, 16]); } },
+  calculator: {
+    stroke: c => { c.roundRect(5, 3, 14, 18, 2); c.moveTo(8, 7); c.lineTo(16, 7); },
+    fill: c => dots(c, [11.5, 15, 18.5].flatMap(y => [8.5, 12, 15.5].map(x => [x, y] as [number, number])), 0.9),
+  },
+  label: {
+    stroke: c => { c.moveTo(4, 8); c.lineTo(14, 8); c.lineTo(20, 12); c.lineTo(14, 16); c.lineTo(4, 16); c.closePath(); },
+    fill: c => dots(c, [[14, 12]], 1.2),
+  },
+  drawing: { stroke: c => { page(c, false); c.moveTo(9, 17); c.lineTo(15.5, 8.5); } },
+  tape: { stroke: c => { c.roundRect(2.5, 8, 19, 8, 1.5); for (const x of [6, 9, 12, 15, 18]) { c.moveTo(x, 8); c.lineTo(x, x === 12 ? 12.5 : 11); } } },
+  removed: { dashed: c => page(c, false), stroke: c => { c.moveTo(4, 20); c.lineTo(20, 4); } },
+  document: { stroke: c => { page(c, true); rules(c, [12, 16]); } },
+};
+
+/** A glyph part's path: kept as a shape where the engine can (a tile's icon is drawn every frame, the same each time). */
+function part(c: DrawCtx, key: string, draw: (c: DrawCtx) => void): void {
+  if (c.shape) c.shape(key, 0, 0, cc => draw(cc));
+  else { c.beginPath(); draw(c); }
+}
+
+/** An icon for kind `g`, `size` across, centred on cx, cy (paths: the canvas can't draw the chrome's SVG icons). */
+function drawGlyph(c: DrawCtx, g: Glyph, cx: number, cy: number, size: number, color: string): void {
+  const u = size / 24, d = GLYPHS[g];
+  c.save();
+  c.translate(cx - size / 2, cy - size / 2);
+  c.scale(u, u);
+  c.strokeStyle = color; c.fillStyle = color; c.lineWidth = 1.8; c.lineCap = 'round'; c.lineJoin = 'round';
+  if (d.dashed) { c.setLineDash([2.2, 2]); part(c, 'glyph- ' + g, d.dashed); c.stroke(); c.setLineDash([]); }
+  if (d.stroke) { part(c, 'glyph| ' + g, d.stroke); c.stroke(); }
+  if (d.fill) { part(c, 'glyph. ' + g, d.fill); c.fill(); }
+  if (d.text) { c.font = '700 6px ' + FONT; c.textAlign = 'center'; c.textBaseline = 'middle'; c.fillText(d.text, 12, 15); }
+  c.restore();
+}

package/src/render/markup.ts

@@ -0,0 +1,91 @@
+import { dashFor, type NoteLook } from '../model/markup';
+import { smoothSpans } from '../model/smooth';
+import type { DrawCtx } from './ctx';
+
+type P = [number, number];
+
+/** An arrowhead's length for a stroke width (screen pixels). */
+const headLen = (w: number): number => Math.max(12, w * 3.2);
+
+/** The unit direction an end points along, taken from far enough back that a pen stroke's jitter doesn't swing it. */
+function endDir(pts: P[], h: number): P {
+  const tip = pts[pts.length - 1];
+  for (let i = pts.length - 2; i >= 0; i--) {
+    const dx = tip[0] - pts[i][0], dy = tip[1] - pts[i][1], d = Math.hypot(dx, dy);
+    if (d >= h || i === 0) return d > 1e-9 ? [dx / d, dy / d] : [1, 0];
+  }
+  return [1, 0];
+}
+
+/** The path stopped short of its last point by `back` (the arrowhead covers the rest). */
+function trimEnd(pts: P[], dir: P, back: number): P[] {
+  const tip = pts[pts.length - 1], stop: P = [tip[0] - dir[0] * back, tip[1] - dir[1] * back];
+  const kept = pts.slice(0, -1).filter((p, i) => i === 0 || Math.hypot(p[0] - tip[0], p[1] - tip[1]) > back);
+  return [...kept, stop];
+}
+
+/** A stroke's path: a curve through its points (model/smooth.ts), not straight from one to the next — or a line, from end to end. */
+function trace(c: DrawCtx, pts: P[]): void {
+  c.beginPath(); c.moveTo(pts[0][0], pts[0][1]);
+  if (pts.length < 3) { c.lineTo(pts[1][0], pts[1][1]); return; }
+  for (const [a, b, e] of smoothSpans(pts)) c.bezierCurveTo(a[0], a[1], b[0], b[1], e[0], e[1]);
+}
+
+/**
+ * Stroke an open piece of markup (screen points) in its look: width, dashes, and each end's finish (round, flat or an
+ * arrowhead). `halo`: a wider stroke under it in that color (the selection glow).
+ */
+export function strokeMarkup(c: DrawCtx, pts: P[], look: NoteLook, halo?: string): void {
+  if (pts.length < 2) return;
+  const w = look.width, h = headLen(w);
+  let path = pts;
+  const ends: { tip: P; dir: P; cap: NoteLook['endCap'] }[] = [];
+  for (const which of ['end', 'start'] as const) {
+    const seq = which === 'end' ? path : path.slice().reverse();
+    const cap = which === 'end' ? look.endCap : look.startCap, dir = endDir(seq, h), tip = seq[seq.length - 1];
+    ends.push({ tip, dir, cap });
+    if (cap === 'arrow') {
+      const t = trimEnd(seq, dir, h * 0.6);
+      path = which === 'end' ? t : t.reverse();
+    }
+  }
+  c.save();
+  c.lineJoin = 'round';
+  if (halo) {
+    c.save(); c.lineWidth = w + 6; c.lineCap = 'round'; c.strokeStyle = halo;
+    trace(c, pts); c.stroke();
+    c.restore();
+  }
+  c.strokeStyle = look.color; c.fillStyle = look.color; c.lineWidth = w;
+  // dots are zero-length dashes, so they need round caps; otherwise the ends are drawn on their own below
+  c.lineCap = look.style === 'dot' ? 'round' : 'butt';
+  c.setLineDash(dashFor(look.style, w));
+  trace(c, path); c.stroke();
+  c.setLineDash([]);
+  for (const { tip, dir, cap } of ends) {
+    if (cap === 'arrow') {
+      const bx = tip[0] - dir[0] * h, by = tip[1] - dir[1] * h, half = h * 0.48;
+      c.beginPath(); c.moveTo(tip[0], tip[1]);
+      c.lineTo(bx - dir[1] * half, by + dir[0] * half);
+      c.lineTo(bx + dir[1] * half, by - dir[0] * half);
+      c.closePath(); c.fill();
+    } else if (cap === 'round' && look.style !== 'dot') {
+      c.beginPath(); c.arc(tip[0], tip[1], w / 2, 0, Math.PI * 2); c.fill();
+    }
+  }
+  c.restore();
+}
+
+/** Stroke a closed shape's outline (screen points) in its look: width and dashes, its corners rounded. `halo` as above. */
+export function strokeOutline(c: DrawCtx, pts: P[], look: NoteLook, halo?: string): void {
+  if (pts.length < 2) return;
+  const path = () => { c.beginPath(); pts.forEach(([x, y], i) => (i ? c.lineTo(x, y) : c.moveTo(x, y))); c.closePath(); };
+  c.save();
+  c.lineJoin = 'round';
+  if (halo) { c.save(); c.lineWidth = look.width + 6; c.strokeStyle = halo; path(); c.stroke(); c.restore(); }
+  c.strokeStyle = look.color; c.lineWidth = look.width;
+  c.lineCap = look.style === 'dot' ? 'round' : 'butt';
+  c.setLineDash(dashFor(look.style, look.width));
+  path(); c.stroke();
+  c.restore();
+}

package/src/render/navigate.ts

@@ -0,0 +1,114 @@
+/*
+  Pan and zoom by fingers, as plain functions with no imports: on a device they run on the UI thread (each is a
+  worklet — the 'worklet' line is how Reanimated's Babel plugin knows to copy it there; anywhere else it's an unused
+  string), so a pinch moves the drawing at the screen's own rate, whatever the JavaScript thread is doing. view.ts
+  pans and zooms the same way for the browser's wheel and drags.
+*/
+
+/** The view: zoom (screen px per inch) and the world point at the middle of the screen. */
+export interface NavView { s: number; cx: number; cy: number }
+
+/** The fingers: their middle, how far apart the first two are (0 for one finger), and how many there are. */
+export interface Pinch { x: number; y: number; d: number; n: number }
+
+/** The furthest out and in the view zooms. */
+export const ZOOM_MIN = 0.04, ZOOM_MAX = 400;
+
+/** Where the fingers are as a pinch: the first two's middle and spread, or one finger's position. */
+export function pinchOf(pts: { x: number; y: number }[]): Pinch | null {
+  'worklet';
+  if (pts.length >= 2) {
+    const a = pts[0], b = pts[1];
+    return { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2, d: Math.hypot(a.x - b.x, a.y - b.y), n: pts.length };
+  }
+  if (pts.length === 1) return { x: pts[0].x, y: pts[0].y, d: 0, n: 1 };
+  return null;
+}
+
+/**
+ * The view after the fingers went from `last` to `now` on a W × H screen: moved with the fingers' middle, then zoomed
+ * about it by how much further apart they are (two or more fingers) — so what's under the fingers stays under them.
+ */
+export function navStep(v: NavView, last: Pinch, now: Pinch, W: number, H: number): NavView {
+  'worklet';
+  const s0 = v.s;
+  let cx = v.cx - (now.x - last.x) / s0, cy = v.cy + (now.y - last.y) / s0, s = s0;
+  if (now.n >= 2 && last.d > 0 && now.d > 0) {
+    // the world point under the fingers' middle, which the zoom keeps there
+    const wx = (now.x - (W / 2 - cx * s0)) / s0, wy = (H / 2 + cy * s0 - now.y) / s0;
+    s = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, (s0 * now.d) / last.d));
+    cx = wx - (now.x - W / 2) / s;
+    cy = wy + (now.y - H / 2) / s;
+  }
+  return { s, cx, cy };
+}
+
+/**
+ * How to move and scale a picture drawn at one view (its zoom `s` and screen offset `ox`, `oy` — see view.ts Xform)
+ * so it sits where view `to` puts it on a W × H screen: scale by k about the screen's corner, then move by tx, ty.
+ */
+export function shiftTo(s: number, ox: number, oy: number, to: NavView, W: number, H: number): { k: number; tx: number; ty: number } {
+  'worklet';
+  const k = to.s / s;
+  return { k, tx: W / 2 - to.cx * to.s - ox * k, ty: H / 2 + to.cy * to.s - oy * k };
+}
+
+/** The view as the fingers left it (on a device's UI thread); `seq` counts their moves. */
+export interface UiView extends NavView { seq: number }
+
+/** What the drawing on screen was drawn at: its view, the latest of the fingers' views it includes, the screen size. */
+export interface DrawnAt { view: NavView; seq: number; W: number; H: number }
+
+/** The fingers on the screen and what they're doing: navigating or not, where they were last, whether a pen has been seen. */
+export interface NavState { fingers: Record<number, { x: number; y: number }>; navigating: boolean; last: Pinch | null; pen: boolean }
+
+export const NAV_DOWN = 0, NAV_MOVE = 1, NAV_UP = 2, NAV_CANCEL = 3;
+
+/**
+ * One touch event, as the UI thread sees it: the fingers after it, and the view (moved if `moved`). Fingers navigate —
+ * pan, and zoom about their middle — once two are down, or any one once a pen has been seen or when the drawing is
+ * view only (editor/gestures.ts decides the same on its side), until the last one lifts. A pen or a mouse never
+ * navigates. `type` is NAV_DOWN… ; `allIds`, every pointer still down (on a down event: a finger that went without
+ * a word, a lost touch-up, is dropped so it can't hold a gesture open).
+ */
+export function navTouch(
+  st: NavState, type: number, kind: string, changed: { id: number; x: number; y: number }[], allIds: number[] | null,
+  readOnly: boolean, view: UiView, drawn: DrawnAt | null,
+): { st: NavState; view: UiView; moved: boolean } {
+  'worklet';
+  const pen = st.pen || kind === 'pen';
+  if (kind !== 'touch') return { st: { ...st, pen }, view, moved: false };
+  const fingers: Record<number, { x: number; y: number }> = {};
+  for (const k in st.fingers) {
+    const id = Number(k);
+    if (type !== NAV_DOWN || !allIds || allIds.includes(id)) fingers[id] = st.fingers[id];
+  }
+  for (const t of changed) {
+    if (type === NAV_UP || type === NAV_CANCEL) delete fingers[t.id];
+    else fingers[t.id] = { x: t.x, y: t.y };
+  }
+  const pts = Object.keys(fingers).map(k => fingers[Number(k)]);
+  if (!pts.length) return { st: { fingers, navigating: false, last: null, pen }, view, moved: false };
+  let navigating = st.navigating, v = view;
+  if (!navigating) {
+    if (pts.length < 2 && !(type === NAV_DOWN && (pen || readOnly))) return { st: { fingers, navigating: false, last: null, pen }, view, moved: false };
+    navigating = true;
+    // start from the view the drawing on screen was drawn at, unless the fingers' own is newer
+    if (drawn && v.seq <= drawn.seq) v = { s: drawn.view.s, cx: drawn.view.cx, cy: drawn.view.cy, seq: drawn.seq };
+  }
+  const now = pinchOf(pts), was = st.last, next = { fingers, navigating, last: now, pen };
+  // a finger came or went: carry on from here, no jump
+  if (type !== NAV_MOVE || !now || !was || was.n !== now.n || !drawn) return { st: next, view: v, moved: false };
+  const to = navStep(v, was, now, drawn.W, drawn.H);
+  return { st: next, view: { s: to.s, cx: to.cx, cy: to.cy, seq: v.seq + 1 }, moved: true };
+}
+
+/**
+ * How to carry the drawing on screen — drawn at transform (s, ox, oy) — to the fingers' view: null when it already
+ * shows it (the fingers haven't moved the view since it was drawn).
+ */
+export function carryTo(drawn: { s: number; ox: number; oy: number; W: number; H: number; seq: number }, view: UiView): { k: number; tx: number; ty: number } | null {
+  'worklet';
+  if (view.seq <= drawn.seq) return null;
+  return shiftTo(drawn.s, drawn.ox, drawn.oy, view, drawn.W, drawn.H);
+}