@weasel-js/labkit 1.6.1 → 1.7.1

package/src/annotations/frac.ts

@@ -1,13 +1,17 @@
+import {
+  type Box,
+  boundsOfCoords,
+  boxContainsBox,
+  boxContainsPoint,
+  type Rect,
+} from '@weasel-js/geom';
 import type { FracPoint, FracRect } from './types';
 
 /** A mark's box in its target's world: CSS pixels at zoom 1. Matches weasel's
  *  default `RectPose`, which is what the scene stores. */
-export interface WorldRect {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
+export type WorldRect = Rect;
+
+const boxOfFrac = (f: FracRect): Box => [f.x, f.y, f.x + f.w, f.y + f.h];
 
 /** Where a fraction lands on a content box of this size. */
 export function fracToWorld(f: FracRect, content: { w: number; h: number }): WorldRect {
@@ -46,22 +50,46 @@ export function roundFrac(f: FracRect): FracRect {
 /** Whether `pt` falls in `box`, widened by `tol` on every side so a hairline
  *  mark stays reachable. */
 export function fracContains(box: FracRect, pt: FracPoint, tol = 0): boolean {
-  return (
-    pt.x >= box.x - tol &&
-    pt.x <= box.x + box.w + tol &&
-    pt.y >= box.y - tol &&
-    pt.y <= box.y + box.h + tol
-  );
+  const [x0, y0, x1, y1] = boxOfFrac(box);
+  return boxContainsPoint([x0 - tol, y0 - tol, x1 + tol, y1 + tol], pt.x, pt.y);
 }
 
 /** Whether `outer` wholly encloses `inner`. A marquee takes what it encloses,
  *  not what it grazes — brushing selection is a different gesture, and this
  *  answers false for two rects that merely overlap. */
 export function fracEncloses(outer: FracRect, inner: FracRect): boolean {
-  return (
-    inner.x >= outer.x &&
-    inner.y >= outer.y &&
-    inner.x + inner.w <= outer.x + outer.w &&
-    inner.y + inner.h <= outer.y + outer.h
-  );
+  return boxContainsBox(boxOfFrac(outer), boxOfFrac(inner));
+}
+
+/** The smallest box holding every point — zero-size for a single one, and
+ *  `null` for none. */
+export function boundsOf(points: readonly FracPoint[]): FracRect | null {
+  const b = boundsOfCoords(points.flatMap((p) => [p.x, p.y]));
+  return b && { x: b[0], y: b[1], w: b[2] - b[0], h: b[3] - b[1] };
+}
+
+/** Points restated as fractions of `box` itself, so they move and stretch with
+ *  it. Unit-agnostic: `points` and `box` only have to share one. A box with no
+ *  width or height puts every point on its edge along that axis. */
+export function toShape(points: readonly FracPoint[], box: FracRect): FracPoint[] {
+  return points.map((p) => ({
+    x: box.w === 0 ? 0 : (p.x - box.x) / box.w,
+    y: box.h === 0 ? 0 : (p.y - box.y) / box.h,
+  }));
 }
+
+/** `toShape`'s inverse: a shape placed in `box`, in `box`'s units. */
+export function fromShape(shape: readonly FracPoint[], box: FracRect): FracPoint[] {
+  return shape.map((s) => ({ x: box.x + s.x * box.w, y: box.y + s.y * box.h }));
+}
+
+/** A world rect as the `{ x, y, w, h }` the shape helpers take. */
+export const boxOf = (r: WorldRect): FracRect => ({ x: r.x, y: r.y, w: r.width, h: r.height });
+
+const roundPoint = (p: FracPoint): FracPoint => ({
+  x: Math.round(p.x * DP) / DP,
+  y: Math.round(p.y * DP) / DP,
+});
+
+/** `roundFrac` for points. */
+export const roundPoints = (pts: readonly FracPoint[]): FracPoint[] => pts.map(roundPoint);

package/src/annotations/index.ts

@@ -23,6 +23,7 @@ export type {
   AnnotationMeaning,
   AnnotationPatch,
   AnnotationQuery,
+  AnnotationSelectionMode,
   AnnotationStatus,
   AnnotationsApi,
   AnnotationsCapability,

package/src/annotations/paint.test.ts

@@ -1,9 +1,11 @@
-import { describe, expect, it } from 'vitest';
-import { markCommands } from './paint';
+import { registerNodeShape, type SceneNode, shapeCoversPoint } from '@weasel-js/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { WorldRect } from './frac';
+import { markCommands, POINT_MARK_SHAPE } from './paint';
 import type { AnnotationData, AnnotationKind, FracPoint } from './types';
 
-const CONTENT = { w: 200, h: 100 };
 const POSE = { x: 20, y: 10, width: 60, height: 40 };
+const AT_50: WorldRect = { x: 50, y: 50, width: 0, height: 0 };
 
 function mark(kind: AnnotationKind, extra: Partial<AnnotationData> = {}) {
   return { pose: POSE, data: { target: 't', kind, ...extra } as AnnotationData };
@@ -17,20 +19,21 @@ function anchors(cmds: ReturnType<typeof markCommands>): number[] {
   return p.coords ? [...p.coords] : [];
 }
 
+/** In fractions of `POSE`: (35, 10) and (80, 30) in world. */
 const ENDS: readonly FracPoint[] = [
-  { x: 0.1, y: 0.2 },
-  { x: 0.6, y: 0.9 },
+  { x: 0.25, y: 0 },
+  { x: 1, y: 0.5 },
 ];
 
 describe('markCommands', () => {
   it('draws a rect at the pose', () => {
-    const [cmd] = markCommands(mark('rect'), CONTENT);
+    const [cmd] = markCommands(mark('rect'));
     expect(cmd).toMatchObject({ kind: 'path', path: { kind: 'rect', ...POSE } });
     expect((cmd as { fill?: unknown }).fill).toBeUndefined();
   });
 
   it('draws an ellipse inscribed in the pose', () => {
-    const pts = anchors(markCommands(mark('ellipse'), CONTENT));
+    const pts = anchors(markCommands(mark('ellipse')));
     const xs = pts.filter((_, i) => i % 2 === 0);
     const ys = pts.filter((_, i) => i % 2 === 1);
     expect(Math.min(...xs)).toBeCloseTo(POSE.x, 4);
@@ -39,32 +42,16 @@ describe('markCommands', () => {
     expect(Math.max(...ys)).toBeCloseTo(POSE.y + POSE.height, 4);
   });
 
-  it('runs a line between its two stored ends, converted to world', () => {
-    expect(anchors(markCommands(mark('line', { points: ENDS }), CONTENT))).toEqual([
-      0.1 * 200,
-      0.2 * 100,
-      0.6 * 200,
-      0.9 * 100,
-    ]);
+  it('runs a line between its two stored ends, placed in the pose', () => {
+    expect(anchors(markCommands(mark('line', { shape: ENDS })))).toEqual([35, 10, 80, 30]);
   });
 
-  it('makes an arrow the same line, plus the head as its own command', () => {
-    const cmds = markCommands(mark('arrow', { points: ENDS }), CONTENT);
+  it('makes an arrow the same line, carrying an end marker', () => {
+    const cmds = markCommands(mark('arrow', { shape: ENDS }));
+    expect(cmds).toHaveLength(1);
     const stroke = (cmds[0] as { stroke?: { markerEnd?: unknown } }).stroke;
     expect(stroke?.markerEnd).toBe('arrow');
-    expect(anchors([cmds[0]])).toEqual([0.1 * 200, 0.2 * 100, 0.6 * 200, 0.9 * 100]);
-
-    // The head has to be geometry, not just a field: `markerEnd` alone is
-    // inert outside the kit's own node painter, which is what shipped an
-    // arrow with no head.
-    expect(cmds).toHaveLength(2);
-    const head = anchors([cmds[1]]);
-    expect(head.length).toBeGreaterThan(0);
-    // Its vertex is the line's far end — computed, not eyeballed.
-    const near = (v: number, t: number) => Math.abs(v - t) < 1;
-    const xs = head.filter((_, i) => i % 2 === 0);
-    const ys = head.filter((_, i) => i % 2 === 1);
-    expect(xs.some((x, i) => near(x, 120) && near(ys[i] as number, 90))).toBe(true);
+    expect(anchors(cmds)).toEqual([35, 10, 80, 30]);
   });
 
   it('threads a freehand stroke through every point', () => {
@@ -73,15 +60,13 @@ describe('markCommands', () => {
       { x: 0.5, y: 0.5 },
       { x: 1, y: 0 },
     ];
-    expect(anchors(markCommands(mark('stroke', { points: pts }), CONTENT))).toEqual([
-      0, 0, 100, 50, 200, 0,
-    ]);
+    expect(anchors(markCommands(mark('stroke', { shape: pts })))).toEqual([20, 10, 50, 30, 80, 10]);
   });
 
-  it('falls back to the pose diagonal when a points kind has no points', () => {
-    // A stored mark from a writer that dropped `points` must still draw
+  it('falls back to the pose diagonal when a vertex kind has no shape', () => {
+    // A stored mark from a writer that dropped `shape` must still draw
     // something at the right place, not vanish.
-    expect(anchors(markCommands(mark('line'), CONTENT))).toEqual([
+    expect(anchors(markCommands(mark('line')))).toEqual([
       POSE.x,
       POSE.y,
       POSE.x + POSE.width,
@@ -90,18 +75,18 @@ describe('markCommands', () => {
   });
 
   it('draws text at the pose, carrying the title', () => {
-    const [cmd] = markCommands(mark('text', { title: 'missing edge' }), CONTENT);
+    const [cmd] = markCommands(mark('text', { title: 'missing edge' }));
     expect(cmd).toMatchObject({ kind: 'text', x: POSE.x, y: POSE.y });
     const runs = (cmd as { runs: { text: string }[] }).runs;
     expect(runs.map((r) => r.text).join('')).toBe('missing edge');
   });
 
   it('draws an untitled text mark as nothing rather than an empty run', () => {
-    expect(markCommands(mark('text'), CONTENT)).toEqual([]);
+    expect(markCommands(mark('text'))).toEqual([]);
   });
 
-  it('draws a point as a small unfilled ring centered on its one stored point', () => {
-    const cmds = markCommands(mark('point', { points: [{ x: 0.25, y: 0.5 }] }), CONTENT);
+  it('draws a point as a small unfilled ring centered on its position', () => {
+    const cmds = markCommands({ pose: AT_50, data: { target: 't', kind: 'point' } });
     expect(cmds).toHaveLength(1);
     expect((cmds[0] as { fill?: unknown }).fill).toBeUndefined();
     const pts = anchors(cmds);
@@ -115,9 +100,56 @@ describe('markCommands', () => {
   });
 });
 
+describe('a point mark at different zooms', () => {
+  const POINT = { pose: AT_50, data: { target: 't', kind: 'point' } as AnnotationData };
+  const radiusAt = (zoom: number) => {
+    const xs = anchors(markCommands(POINT, {}, { x: zoom, y: zoom })).filter((_, i) => i % 2 === 0);
+    return (Math.max(...xs) - Math.min(...xs)) / 2;
+  };
+
+  it('sizes the ring in screen pixels, so its world radius scales inversely with zoom', () => {
+    expect(radiusAt(2)).toBeCloseTo(2, 4);
+    expect(radiusAt(4)).toBeCloseTo(1, 4);
+  });
+
+  it('keeps the ring round on screen under a non-uniform scale', () => {
+    const pts = anchors(markCommands(POINT, {}, { x: 2, y: 4 }));
+    const xs = pts.filter((_, i) => i % 2 === 0);
+    const ys = pts.filter((_, i) => i % 2 === 1);
+    expect((Math.max(...xs) - Math.min(...xs)) * 2).toBeCloseTo(
+      (Math.max(...ys) - Math.min(...ys)) * 4,
+      4,
+    );
+  });
+});
+
+describe('picking a point mark', () => {
+  let dispose: () => void = () => {};
+  beforeEach(() => {
+    dispose = registerNodeShape(POINT_MARK_SHAPE, { priority: 'high' });
+  });
+  afterEach(() => dispose());
+
+  const pose: WorldRect = { x: 50, y: 50, width: 0, height: 0 };
+  const node = {
+    id: 'p',
+    kind: 'leaf',
+    layer: 'marks',
+    pose,
+    data: { target: 't', kind: 'point' },
+  } as unknown as SceneNode<AnnotationData, 'marks', WorldRect>;
+
+  // Ring radius 4px plus half the 2px outline: the ring's outer edge is 5px out.
+  it.each([1, 4])('reaches the ring it draws and no further, at zoom %i', (zoom) => {
+    const at = (px: number) => shapeCoversPoint(node, pose, 50 + px / zoom, 50, { scale: zoom });
+    expect(at(4.9)).toBe(true);
+    expect(at(5.5)).toBe(false);
+  });
+});
+
 describe('markCommands styling', () => {
   it('takes a status color over the default', () => {
-    const [cmd] = markCommands(mark('rect'), CONTENT, { color: '#30a46c' });
+    const [cmd] = markCommands(mark('rect'), { color: '#30a46c' });
     expect((cmd as { stroke?: { paint?: { color?: string } } }).stroke?.paint?.color).toBe(
       '#30a46c',
     );
@@ -125,21 +157,19 @@ describe('markCommands styling', () => {
 
   it('dashes a stale mark rather than hiding it', () => {
     // A stale mark still describes something; dropping it would lose it.
-    const [fresh] = markCommands(mark('rect'), CONTENT);
-    const [stale] = markCommands(mark('rect'), CONTENT, { stale: true });
+    const [fresh] = markCommands(mark('rect'));
+    const [stale] = markCommands(mark('rect'), { stale: true });
     expect((fresh as { stroke?: { dash?: number[] } }).stroke?.dash).toBeUndefined();
     expect((stale as { stroke?: { dash?: number[] } }).stroke?.dash).toEqual([6, 4]);
   });
 
   it('dashes a stale point ring like any other mark', () => {
-    const [ring] = markCommands(mark('point', { points: [{ x: 0.25, y: 0.5 }] }), CONTENT, {
-      stale: true,
-    });
+    const [ring] = markCommands(mark('point'), { stale: true });
     expect((ring as { stroke?: { dash?: number[] } }).stroke?.dash).toEqual([6, 4]);
   });
 
   it("colors a text mark's glyphs too, not only the outlines", () => {
-    const [cmd] = markCommands(mark('text', { title: 'x' }), CONTENT, { color: '#30a46c' });
+    const [cmd] = markCommands(mark('text', { title: 'x' }), { color: '#30a46c' });
     const runs = (cmd as { runs: { fill?: { color?: string } }[] }).runs;
     expect(runs[0]?.fill?.color).toBe('#30a46c');
   });

package/src/annotations/paint.ts

@@ -1,23 +1,28 @@
-import type { DrawCommand, Path, Stroke } from '@weasel-js/core';
+import type { DrawCommand, NodeShapeEntry, Path, Stroke, View } from '@weasel-js/core';
 import {
   ellipsePath,
+  HANDLE_BASE_PX,
   linePath,
-  markerDrawCommands,
+  meanScale,
   PathBuilder,
+  pxExtent,
   rectPath,
   textCommand,
 } from '@weasel-js/core';
-import type { WorldRect } from './frac';
-import type { AnnotationData, FracPoint } from './types';
+import { boxOf, fromShape, type WorldRect } from './frac';
+import type { AnnotationData } from './types';
 
 /** One loud color, not a themed one: a mark sits over the instrument's own
  *  picture and has to be legible against whatever that picture is. */
 const MARK_COLOR = '#e5484d';
-/** World units, so a mark thickens with the picture it annotates — and so the
- *  marker geometry can be resolved here, which needs a resolved width. */
+/** World units, so a mark thickens with the picture it annotates. */
 const MARK_WIDTH = 2;
 const TEXT_SIZE = 14;
-const POINT_RADIUS = 4;
+const STALE_DASH = [6, 4];
+/** Screen pixels: a point marks a place rather than a region of the picture,
+ *  so it holds its size like a selection handle. */
+const POINT_RADIUS_PX = HANDLE_BASE_PX / 2;
+const UNIT_SCALE: View['scale'] = { x: 1, y: 1 };
 
 /** The subset of a mark's scene node this needs: where it is, and what it is. */
 export interface PaintableMark {
@@ -36,16 +41,11 @@ export interface MarkStyle {
   stale?: boolean;
 }
 
-const toWorld = (p: FracPoint, content: { w: number; h: number }) => ({
-  x: p.x * content.w,
-  y: p.y * content.h,
-});
-
-/** A mark's stored vertices in world units, or the pose's diagonal — a stored
- *  mark whose `points` did not survive still has to draw somewhere. */
-function vertices(m: PaintableMark, content: { w: number; h: number }): { x: number; y: number }[] {
-  const stored = m.data.points;
-  if (stored && stored.length >= 2) return stored.map((p) => toWorld(p, content));
+/** A mark's stored vertices placed in its pose, or the pose's diagonal — a
+ *  stored mark whose `shape` did not survive still has to draw somewhere. */
+function vertices(m: PaintableMark): { x: number; y: number }[] {
+  const stored = m.data.shape;
+  if (stored && stored.length >= 2) return fromShape(stored, boxOf(m.pose));
   const { x, y, width, height } = m.pose;
   return [
     { x, y },
@@ -65,14 +65,18 @@ function polyline(points: { x: number; y: number }[]): Path {
 /**
  * What one mark draws, in its target's world.
  *
- * Pure: a node and the target's content box in, draw commands out. Geometry
- * that a bounding box cannot describe — a line's ends, a stroke's path — comes
- * from `data.points`, which is in fractions like the bounds.
+ * Pure: a node in, draw commands out, in its target's world. Geometry that a
+ * bounding box cannot describe — a line's ends, a stroke's path — comes from
+ * `data.shape`, placed in the pose.
+ *
+ * `scale` is the view's, world to screen. Only a point reads it — its ring is
+ * sized in screen pixels — and the default draws that ring as though a world
+ * unit were a pixel.
  */
 export function markCommands(
   m: PaintableMark,
-  content: { w: number; h: number },
   style: MarkStyle = {},
+  scale: View['scale'] = UNIT_SCALE,
 ): DrawCommand[] {
   const color = style.color ?? MARK_COLOR;
   const stroke: Stroke = {
@@ -80,7 +84,7 @@ export function markCommands(
     width: MARK_WIDTH,
     cap: 'round',
     join: 'round',
-    ...(style.stale ? { dash: [6, 4] } : {}),
+    ...(style.stale ? { dash: STALE_DASH } : {}),
   };
 
   switch (m.data.kind) {
@@ -91,34 +95,32 @@ export function markCommands(
     case 'ellipse':
       return [{ kind: 'path', path: ellipsePath(m.pose), stroke }];
     case 'line': {
-      const [a, b] = vertices(m, content);
+      const [a, b] = vertices(m);
       return [{ kind: 'path', path: linePath(a, b), stroke }];
     }
     case 'arrow': {
-      const [a, b] = vertices(m, content);
+      const [a, b] = vertices(m);
       // The spec's arrow: a line carrying an end marker, not its own geometry.
-      // Markers are separate commands — a stroke's `markerEnd` is inert unless
-      // something turns it into geometry, and only the kit's own node painter
-      // does that, for the nodes it owns.
-      const marked: Stroke = { ...stroke, markerEnd: 'arrow' };
-      const path = linePath(a, b);
-      return [
-        { kind: 'path', path, stroke: marked },
-        ...markerDrawCommands(path, marked, MARK_WIDTH, undefined),
-      ];
+      return [{ kind: 'path', path: linePath(a, b), stroke: { ...stroke, markerEnd: 'arrow' } }];
     }
     case 'stroke':
-      return [{ kind: 'path', path: polyline(vertices(m, content)), stroke }];
+      return [{ kind: 'path', path: polyline(vertices(m)), stroke }];
     case 'point': {
-      const stored = m.data.points?.[0];
-      const c = stored ? toWorld(stored, content) : { x: m.pose.x, y: m.pose.y };
-      const ring = {
-        x: c.x - POINT_RADIUS,
-        y: c.y - POINT_RADIUS,
-        width: 2 * POINT_RADIUS,
-        height: 2 * POINT_RADIUS,
-      };
-      return [{ kind: 'path', path: ellipsePath(ring), stroke }];
+      const c = { x: m.pose.x, y: m.pose.y };
+      const r = pxExtent(POINT_RADIUS_PX, scale);
+      const ring = { x: c.x - r.x, y: c.y - r.y, width: 2 * r.x, height: 2 * r.y };
+      const px = 1 / meanScale(scale);
+      return [
+        {
+          kind: 'path',
+          path: ellipsePath(ring),
+          stroke: {
+            ...stroke,
+            width: MARK_WIDTH * px,
+            ...(stroke.dash ? { dash: stroke.dash.map((d) => d * px) } : {}),
+          },
+        },
+      ];
     }
     case 'text': {
       const text = m.data.title;
@@ -140,3 +142,23 @@ export function markCommands(
     }
   }
 }
+
+/**
+ * What picking reads for a point mark: its pose is zero-size, so without this
+ * the pointer slop alone decides how close counts, whatever the ring's size.
+ * Registered by the overlay, which is the one place marks are picked.
+ */
+export const POINT_MARK_SHAPE: NodeShapeEntry<AnnotationData, WorldRect> = {
+  id: 'labkit:point-mark',
+  matches: (node) =>
+    node.layer === 'marks' && node.data?.kind === 'point' && typeof node.data.target === 'string',
+  // The overlay paints through its own draw callback. This is for a scene
+  // drawn without one.
+  paint: (node, pose) => markCommands({ pose, data: node.data }),
+  silhouette: (_node, pose) => rectPath(pose.x, pose.y, 0, 0),
+  // Filled, so a click inside the ring lands on it as it would on a handle.
+  ink: (_node, _pose, ctx) => {
+    const s = ctx?.scale ?? 1;
+    return { filled: true, outset: (POINT_RADIUS_PX + MARK_WIDTH / 2) / s, inset: 0 };
+  },
+};