@rasamjs/tools 0.0.0-stage → 0.2.0

package/src/snapping/overlay.ts

@@ -0,0 +1,186 @@
+import { Matrix } from '@rasamjs/core';
+import type { Point, Svg } from '@rasamjs/core';
+import type { Guide } from './guides.js';
+
+const namespace = 'http://www.w3.org/2000/svg';
+const guidePoint = (guide: Guide, value: number): Point =>
+  guide.axis === 'x' ? { x: guide.position, y: value } : { x: value, y: guide.position };
+
+/** Native SVG outside the managed drawing; geometry is projected through client pixels. */
+export class GuideOverlay {
+  private readonly element: SVGSVGElement;
+  private readonly lines: SVGLineElement[];
+  private readonly marks: SVGPathElement;
+  private readonly gaps: SVGPathElement;
+  private readonly view: Window;
+  private pending: number | null = null;
+  private read: (() => readonly Guide[]) | null = null;
+
+  constructor(
+    private readonly drawing: Svg,
+    stroke: string,
+    gapStroke = stroke,
+  ) {
+    const document = drawing.el.ownerDocument;
+    this.view = document.defaultView!;
+    let outer = drawing.el;
+    while (outer.ownerSVGElement) outer = outer.ownerSVGElement;
+    if (!outer.parentElement) throw new TypeError('Guides need a mounted drawing container');
+    this.element = document.createElementNS(namespace, 'svg');
+    for (const [key, value] of Object.entries({
+      class: 'rasam-snapping',
+      width: '100%',
+      height: '100%',
+      'aria-hidden': 'true',
+      focusable: 'false',
+      fill: 'none',
+      stroke,
+    }))
+      this.element.setAttribute(key, value);
+    Object.assign(this.element.style, {
+      position: 'absolute',
+      inset: '0',
+      overflow: 'visible',
+      pointerEvents: 'none',
+      display: 'none',
+    });
+    this.lines = ['x', 'y'].map((axis) => {
+      const line = this.create('line');
+      line.setAttribute('data-axis', axis);
+      return line;
+    });
+    this.marks = this.create('path');
+    this.gaps = this.create('path');
+    this.gaps.setAttribute('data-gaps', '');
+    this.gaps.setAttribute('stroke', gapStroke);
+    outer.parentElement.append(this.element);
+    this.view.addEventListener('scroll', this.schedule, true);
+    this.view.addEventListener('resize', this.schedule);
+  }
+
+  private create<Tag extends 'line' | 'path'>(tag: Tag): SVGElementTagNameMap[Tag] {
+    const element = this.element.ownerDocument.createElementNS(namespace, tag);
+    element.setAttribute('stroke-width', '1');
+    element.setAttribute('vector-effect', 'non-scaling-stroke');
+    this.element.append(element);
+    return element;
+  }
+
+  show(read: () => readonly Guide[]): void {
+    this.read = read;
+    this.schedule();
+  }
+  private readonly schedule = (): void => {
+    if (this.read && this.pending === null)
+      this.pending = this.view.requestAnimationFrame(() => {
+        this.pending = null;
+        this.update();
+      });
+  };
+
+  update(): void {
+    if (this.pending !== null) this.view.cancelAnimationFrame(this.pending);
+    this.pending = null;
+    const guides = this.read?.() ?? [];
+    if (!guides.length || !this.element.isConnected) {
+      this.element.style.display = 'none';
+      return;
+    }
+    this.element.style.display = '';
+    const screen = this.element.getScreenCTM?.();
+    const inverse =
+      screen && new Matrix(screen.a, screen.b, screen.c, screen.d, screen.e, screen.f).inverse();
+    if (!inverse) {
+      this.element.style.display = 'none';
+      return;
+    }
+    const marks: string[] = [];
+    for (const [index, axis] of (['x', 'y'] as const).entries()) {
+      const line = this.lines[index],
+        guide = guides.find((guide) => !guide.gap && guide.axis === axis);
+      line.style.display = guide ? '' : 'none';
+      if (!guide) continue;
+      const point = (value: number) => guidePoint(guide, value);
+      const a = this.drawing.toClient(point(guide.from)),
+        b = this.drawing.toClient(point(guide.to)),
+        next = this.drawing.toClient(point(guide.from + 1));
+      if (!a || !b || !next) {
+        this.element.style.display = 'none';
+        return;
+      }
+      const length = Math.hypot(next.x - a.x, next.y - a.y);
+      if (!length) {
+        line.style.display = 'none';
+        continue;
+      }
+      const pad = { x: (8 * (next.x - a.x)) / length, y: (8 * (next.y - a.y)) / length };
+      const start = inverse.apply({ x: a.x - pad.x, y: a.y - pad.y }),
+        end = inverse.apply({ x: b.x + pad.x, y: b.y + pad.y });
+      for (const [name, value] of Object.entries({
+        x1: start.x,
+        y1: start.y,
+        x2: end.x,
+        y2: end.y,
+      }))
+        line.setAttribute(name, String(value));
+      for (const value of guide.marks) {
+        const client = this.drawing.toClient(point(value));
+        if (!client) continue;
+        for (const [a, b] of [
+          [-3, 3],
+          [3, -3],
+        ]) {
+          const start = inverse.apply({ x: client.x - 3, y: client.y + a }),
+            end = inverse.apply({ x: client.x + 3, y: client.y + b });
+          marks.push(`M${start.x},${start.y}L${end.x},${end.y}`);
+        }
+      }
+    }
+    this.marks.setAttribute('d', marks.join(''));
+    this.gaps.setAttribute(
+      'd',
+      guides
+        .filter((guide) => guide.gap)
+        .map((guide) => this.gapPath(guide, inverse))
+        .join(''),
+    );
+  }
+
+  private gapPath(guide: Guide, inverse: Matrix): string {
+    const a = this.drawing.toClient(guidePoint(guide, guide.from));
+    const b = this.drawing.toClient(guidePoint(guide, guide.to));
+    if (!a || !b) return '';
+    const length = Math.hypot(b.x - a.x, b.y - a.y);
+    if (!length) return '';
+    const cap = { x: (3 * (b.y - a.y)) / length, y: (3 * (b.x - a.x)) / length };
+    const segment = (from: Point, to: Point) => {
+      const start = inverse.apply(from),
+        end = inverse.apply(to);
+      return `M${start.x},${start.y}L${end.x},${end.y}`;
+    };
+    return (
+      segment(a, b) +
+      [a, b]
+        .map((point) =>
+          segment(
+            { x: point.x + cap.x, y: point.y - cap.y },
+            { x: point.x - cap.x, y: point.y + cap.y },
+          ),
+        )
+        .join('')
+    );
+  }
+
+  clear(): void {
+    if (this.pending !== null) this.view.cancelAnimationFrame(this.pending);
+    this.pending = null;
+    this.read = null;
+    this.element.style.display = 'none';
+  }
+  destroy(): void {
+    this.clear();
+    this.element.remove();
+    this.view.removeEventListener('scroll', this.schedule, true);
+    this.view.removeEventListener('resize', this.schedule);
+  }
+}

package/src/snapping/session.ts

@@ -0,0 +1,116 @@
+import type { Point } from '@rasamjs/core';
+import type { Features, Match, Targets } from './lines.js';
+import { prefer, snapAxis } from './lines.js';
+import type { Spacing } from './spacing.js';
+import type { ResolvedOptions } from './options.js';
+import { assertPoint } from './options.js';
+import type { SnapSession } from './types.js';
+
+interface Mapping {
+  fromClient(point: Point): Point | null;
+  toClient(point: Point): Point | null;
+}
+interface SessionConfig {
+  readonly start: Point;
+  readonly features: Features;
+  readonly targets: Targets;
+  readonly mapping: Mapping;
+  readonly options: ResolvedOptions;
+  readonly isEnabled: () => boolean;
+  readonly onEnd: () => void;
+  readonly onSnap?: (matches: readonly (Match | null)[], point: Point | null) => void;
+  readonly spacing?: Spacing | null;
+}
+
+/** Unit-frame anchors can map to either root axis after a quarter turn or reflection. */
+export function resizeLines(corners: readonly Point[], anchor: Point): Features | null {
+  if (corners.length !== 4) return null;
+  const [a, b, c, d] = corners;
+  const u = { x: b.x - a.x, y: b.y - a.y },
+    v = { x: d.x - a.x, y: d.y - a.y };
+  const epsilon = 1e-7 * Math.max(Math.abs(u.x), Math.abs(u.y), Math.abs(v.x), Math.abs(v.y));
+  const horizontal = (edge: Point) => Math.abs(edge.x) > 1e-7 * Math.hypot(edge.x, edge.y);
+  const vertical = (edge: Point) => Math.abs(edge.y) > 1e-7 * Math.hypot(edge.x, edge.y);
+  if (
+    [u, v].some((edge) => horizontal(edge) && vertical(edge)) ||
+    (horizontal(u) && horizontal(v)) ||
+    (vertical(u) && vertical(v)) ||
+    Math.abs(c.x - b.x - d.x + a.x) > epsilon ||
+    Math.abs(c.y - b.y - d.y + a.y) > epsilon
+  )
+    return null;
+  const point = {
+    x: a.x + u.x * anchor.x + v.x * anchor.y,
+    y: a.y + u.y * anchor.x + v.y * anchor.y,
+  };
+  const x = (anchor.x !== 0.5 && horizontal(u)) || (anchor.y !== 0.5 && horizontal(v));
+  const y = (anchor.x !== 0.5 && vertical(u)) || (anchor.y !== 0.5 && vertical(v));
+  return x || y
+    ? { x: x ? [{ value: point.x, edge: true }] : [], y: y ? [{ value: point.y, edge: true }] : [] }
+    : null;
+}
+
+function clientScale(mapping: Mapping): Point | null {
+  const origin = mapping.toClient({ x: 0, y: 0 }),
+    x = mapping.toClient({ x: 1, y: 0 }),
+    y = mapping.toClient({ x: 0, y: 1 });
+  if (!origin || !x || !y) return null;
+  const scale = {
+    x: Math.hypot(x.x - origin.x, x.y - origin.y),
+    y: Math.hypot(y.x - origin.x, y.y - origin.y),
+  };
+  return Number.isFinite(scale.x) && Number.isFinite(scale.y) && scale.x > 0 && scale.y > 0
+    ? scale
+    : null;
+}
+
+function correctedClient(client: Point, config: SessionConfig, centered?: boolean): Point {
+  assertPoint(client, 'Client pointer');
+  const point = config.mapping.fromClient(client),
+    scale = point && clientScale(config.mapping);
+  if (!point || !scale || !Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+    config.onSnap?.([], null);
+    return client;
+  }
+  const offset = { x: point.x - config.start.x, y: point.y - config.start.y };
+  const correction = (axis: 'x' | 'y') => {
+    const tolerance = config.options.tolerance / scale[axis];
+    const alignment = snapAxis({
+      moving: config.features[axis],
+      targets: config.options.shapes ? config.targets[axis] : [],
+      offset: offset[axis],
+      tolerance,
+      grid: config.options.grid && {
+        size: config.options.grid.size,
+        origin: config.options.grid.origin[axis],
+      },
+    });
+    const spacing = config.spacing?.({ axis, offset, tolerance, centered });
+    return spacing ? prefer(alignment, spacing) : alignment;
+  };
+  const x = correction('x'),
+    y = correction('y');
+  const corrected = { x: point.x + (x?.delta ?? 0), y: point.y + (y?.delta ?? 0) };
+  const result = x?.delta || y?.delta ? config.mapping.toClient(corrected) : client;
+  config.onSnap?.(result ? [x, y] : [], result ? corrected : null);
+  return result ?? client;
+}
+
+export function createSession(config: SessionConfig): SnapSession {
+  let ended = false;
+  return {
+    snap(client, modifiers) {
+      if (ended) return client;
+      if (!config.isEnabled() || (modifiers.ignore && config.options.modifier !== 'none')) {
+        config.onSnap?.([], null);
+        return client;
+      }
+      return correctedClient(client, config, modifiers.centered);
+    },
+    end() {
+      if (ended) return;
+      ended = true;
+      config.onEnd();
+    },
+  };
+}

package/src/snapping/snapper.ts

@@ -0,0 +1,147 @@
+import type { Box, Point, Svg } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+import { boxLines, targetLines } from './lines.js';
+import type { Features } from './lines.js';
+import { assertPoint, resolveOptions } from './options.js';
+import type { ResolvedOptions } from './options.js';
+import { createSession, resizeLines } from './session.js';
+import { measureTargets, movingBox, validateNodes } from './targets.js';
+import type { SnapperOptions, SnapRequest, SnapSession } from './types.js';
+import { guideReader } from './guides.js';
+import { GuideOverlay } from './overlay.js';
+import { createSpacing } from './spacing.js';
+
+/** Owns snapping state for one mounted drawing. */
+export class Snapper {
+  private enabledState = true;
+  private readonly overlay: GuideOverlay;
+  private readonly stopDisposal: () => void;
+  private readonly options: ResolvedOptions;
+  private active: SnapSession | null = null;
+  private sessionVersion = 0;
+  private disposed = false;
+
+  constructor(
+    private readonly drawing: Svg,
+    options: SnapperOptions = {},
+  ) {
+    if (
+      !Guards.isTransformable(drawing) ||
+      drawing.isDestroyed ||
+      drawing.el.localName !== 'svg' ||
+      !drawing.el.isConnected ||
+      !drawing.el.ownerDocument.defaultView
+    )
+      throw new TypeError('Snapper needs a live, mounted rasam SVG drawing');
+    this.options = resolveOptions(options);
+    this.overlay = new GuideOverlay(drawing, this.options.stroke, this.options.gapStroke);
+    this.stopDisposal = drawing.onDispose(() => this.destroy());
+  }
+
+  get isDestroyed(): boolean {
+    return this.disposed;
+  }
+
+  get enabled(): boolean {
+    return this.enabledState;
+  }
+  set enabled(value: boolean) {
+    if (typeof value !== 'boolean') throw new TypeError('enabled must be a boolean');
+    this.enabledState = value;
+    if (!value) this.overlay.clear();
+  }
+
+  update(): this {
+    if (!this.disposed) this.overlay.update();
+    return this;
+  }
+
+  begin(request: SnapRequest): SnapSession | null {
+    const version = ++this.sessionVersion;
+    this.active?.end();
+    if (this.disposed || !this.enabled) return null;
+    if (!request || !['move', 'resize', 'point'].includes(request.kind))
+      throw new TypeError('Unknown snap request kind');
+    assertPoint(request.client, 'Start pointer');
+    if (request.kind !== 'point') validateNodes(request.nodes, this.drawing);
+    const start = this.drawing.fromClient(request.client);
+    if (!start) return null;
+    const geometry = this.geometry(request, start);
+    if (!geometry) return null;
+    const nodes = Object.freeze(request.kind === 'point' ? [] : [...new Set(request.nodes)]);
+    const targets = targetLines(
+      this.options.shapes || this.options.spacing
+        ? measureTargets(this.drawing, nodes, this.options)
+        : [],
+    );
+    if (version !== this.sessionVersion || this.disposed || !this.enabled) return null;
+    const spacing = this.options.spacing
+      ? createSpacing({
+          ...geometry,
+          targets: targets.boxes,
+          kind: request.kind,
+          centered: request.kind === 'resize' && request.centered,
+        })
+      : null;
+    if (
+      !this.options.grid &&
+      !(this.options.shapes && (targets.x.length || targets.y.length)) &&
+      !spacing
+    )
+      return null;
+    const read = guideReader(this.drawing, request, targets.boxes);
+    this.active = createSession({
+      start: { x: start.x, y: start.y },
+      features: geometry.features,
+      spacing,
+      targets,
+      mapping: this.drawing,
+      options: this.options,
+      isEnabled: () => this.enabled && !this.disposed,
+      onEnd: () => {
+        this.active = null;
+        this.overlay.clear();
+      },
+      onSnap: (matches, point) => {
+        if (version !== this.sessionVersion || this.disposed) return;
+        if (!point || !matches.some((match) => match)) this.overlay.clear();
+        else this.overlay.show(() => read(matches, point));
+      },
+    });
+    return this.active;
+  }
+
+  private geometry(request: SnapRequest, start: Point): { box: Box; features: Features } | null {
+    const box =
+      request.kind === 'point'
+        ? { ...start, width: 0, height: 0 }
+        : movingBox(request.nodes, this.drawing);
+    if (!box) return null;
+    if (request.kind !== 'resize') return { box, features: boxLines(box) };
+    if (
+      !request.anchor ||
+      ![0, 0.5, 1].includes(request.anchor.x) ||
+      ![0, 0.5, 1].includes(request.anchor.y) ||
+      (request.anchor.x === 0.5 && request.anchor.y === 0.5)
+    )
+      throw new TypeError('Resize snapping needs a unit-frame edge or corner anchor');
+    if (!Array.isArray(request.corners) || request.corners.length !== 4)
+      throw new TypeError('Resize snapping needs four frame corners');
+    const corners = request.corners.map((point) => {
+      assertPoint(point, 'Frame corner');
+      return this.drawing.fromClient(point);
+    });
+    const features = corners.every((point) => point !== null)
+      ? resizeLines(corners as Point[], request.anchor)
+      : null;
+    return features ? { box, features } : null;
+  }
+
+  destroy(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.active?.end();
+    this.overlay.destroy();
+    this.stopDisposal();
+  }
+}

package/src/snapping/spacing.ts

@@ -0,0 +1,157 @@
+import type { Box, Point } from '@rasamjs/core';
+import type { Features, Match } from './lines.js';
+import { lowerBound } from './lines.js';
+
+type Axis = 'x' | 'y';
+type Side = 'before' | 'after';
+const extent = { x: 'width', y: 'height' } as const;
+const end = (box: Box, axis: Axis) => box[axis] + box[extent[axis]];
+const across = (axis: Axis): Axis => (axis === 'x' ? 'y' : 'x');
+const overlaps = (a: Box, b: Box, axis: Axis) => a[axis] <= end(b, axis) && b[axis] <= end(a, axis);
+const middle = (a: Box, b: Box, axis: Axis) =>
+  (Math.max(a[axis], b[axis]) + Math.min(end(a, axis), end(b, axis))) / 2;
+
+export interface Gap {
+  readonly from: number;
+  readonly to: number;
+  readonly at: number;
+  readonly moving?: 'from' | 'to';
+  readonly neighbor?: number;
+}
+interface Setup {
+  readonly box: Box;
+  readonly targets: readonly Box[];
+  readonly features: Features;
+  readonly kind: 'move' | 'resize' | 'point';
+  readonly centered?: boolean;
+}
+export type Spacing = (request: {
+  readonly axis: Axis;
+  readonly offset: Point;
+  readonly tolerance: number;
+  readonly centered?: boolean;
+}) => Match | null;
+
+/**
+ * Only gaps after the furthest preceding overlapping box are unobstructed. Boxes that
+ * contain the next box on this axis are backgrounds, not obstructions.
+ */
+function referenceGaps(targets: readonly Box[], axis: Axis): Gap[] {
+  const gaps: Gap[] = [];
+  // Far edges ascending; equal edges scan the earliest document target first.
+  const ordered = targets
+    .map((box, order) => ({ box, order, value: end(box, axis) }))
+    .sort((a, b) => a.value - b.value || b.order - a.order);
+  for (const next of targets)
+    for (let index = lowerBound(ordered, end(next, axis)) - 1; index >= 0; index--) {
+      const previous = ordered[index];
+      if (previous.box[axis] >= next[axis] || !overlaps(previous.box, next, across(axis))) continue;
+      if (previous.value < next[axis])
+        gaps.push({
+          from: previous.value,
+          to: next[axis],
+          at: middle(previous.box, next, across(axis)),
+        });
+      break;
+    }
+  return gaps;
+}
+
+function projectedBox(setup: Setup, offset: Point, centered = setup.centered): Box {
+  const box = { ...setup.box };
+  for (const axis of ['x', 'y'] as const) {
+    if (setup.kind !== 'resize') {
+      box[axis] += offset[axis];
+      continue;
+    }
+    const feature = setup.features[axis][0];
+    if (!feature) continue;
+    const start = setup.box[axis],
+      finish = end(setup.box, axis);
+    const fixed =
+      Math.abs(feature.value - start) < Math.abs(feature.value - finish) ? finish : start;
+    const opposite = fixed - (centered ? offset[axis] : 0),
+      active = feature.value + offset[axis];
+    box[axis] = Math.min(active, opposite);
+    box[extent[axis]] = Math.abs(active - opposite);
+  }
+  return box;
+}
+
+/** Targets that contain the box on this axis (backgrounds, panels) are not neighbors. */
+function neighbors(box: Box, targets: readonly Box[], axis: Axis): [number, number] {
+  let left = -1,
+    right = -1;
+  targets.forEach((target, index) => {
+    if (!overlaps(box, target, across(axis))) return;
+    const before = target[axis] <= box[axis],
+      after = end(target, axis) >= end(box, axis);
+    if (before && after) return;
+    if (before && (left < 0 || end(target, axis) > end(targets[left], axis))) left = index;
+    if (after && (right < 0 || target[axis] < targets[right][axis])) right = index;
+  });
+  return [left, right];
+}
+
+/** Snapshot once; pointer queries scan cached boxes/gaps without any DOM reads. */
+export function createSpacing(input: Setup): Spacing | null {
+  const setup = {
+    ...input,
+    box: { ...input.box },
+    targets: input.targets.map((box) => ({ ...box })),
+  };
+  const references = { x: referenceGaps(setup.targets, 'x'), y: referenceGaps(setup.targets, 'y') };
+  if (!references.x.length && !references.y.length) return null;
+  return ({ axis, offset, tolerance, centered = setup.centered }) => {
+    const resizing = setup.kind === 'resize',
+      feature = setup.features[axis][0];
+    if (resizing && !feature) return null;
+    const box = projectedBox(setup, offset, centered),
+      [left, right] = neighbors(box, setup.targets, axis);
+    const active = feature && feature.value + offset[axis];
+    const dragged: Side = resizing && active! > box[axis] ? 'after' : 'before';
+    let best: Match | null = null;
+    const mark = (next: Box, side: Side): Gap => {
+      const index = side === 'before' ? left : right,
+        neighbor = setup.targets[index];
+      return {
+        from: side === 'before' ? end(neighbor, axis) : end(next, axis),
+        to: side === 'before' ? next[axis] : neighbor[axis],
+        at: middle(next, neighbor, across(axis)),
+        moving: side === 'before' ? 'to' : 'from',
+        neighbor: index,
+      };
+    };
+    const offer = (delta: number, side: Side, reference?: Gap) => {
+      if (Math.abs(delta) > tolerance || (best && Math.abs(delta) >= Math.abs(best.delta))) return;
+      const next = projectedBox(setup, { ...offset, [axis]: offset[axis] + delta }, centered);
+      const target = side === 'before' ? next[axis] : end(next, axis);
+      if (resizing && Math.abs(active! + delta - target) > 1e-7) return;
+      const gaps = reference
+        ? [reference, mark(next, side)]
+        : [mark(next, 'before'), mark(next, 'after')];
+      const length = gaps[0].to - gaps[0].from;
+      if (
+        length <= 0 ||
+        gaps.some((gap) => Math.abs(gap.to - gap.from - length) > 1e-7 * Math.max(1, length))
+      )
+        return;
+      best = { delta, target, order: side === 'before' ? left : right, grid: false, gaps };
+    };
+    if (left >= 0 && right >= 0 && left !== right) {
+      const before = box[axis] - end(setup.targets[left], axis),
+        after = setup.targets[right][axis] - end(box, axis);
+      let delta = (after - before) / 2;
+      if (resizing) delta = centered ? 0 : after - before;
+      offer(delta, dragged);
+    }
+    for (const reference of references[axis]) {
+      const length = reference.to - reference.from;
+      if (left >= 0 && (!resizing || dragged === 'before'))
+        offer(end(setup.targets[left], axis) + length - box[axis], 'before', reference);
+      if (right >= 0 && (!resizing || dragged === 'after'))
+        offer(setup.targets[right][axis] - length - end(box, axis), 'after', reference);
+    }
+    return best;
+  };
+}

package/src/snapping/targets.ts

@@ -0,0 +1,88 @@
+import type { AnyNode, Box, Svg } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+import { boundsIn } from '@rasamjs/core/viewport';
+import type { ResolvedOptions } from './options.js';
+
+export function validateNodes(nodes: readonly AnyNode[], drawing: Svg): void {
+  if (!Array.isArray(nodes)) throw new TypeError('Snap nodes must be an array');
+  for (const node of nodes)
+    if (
+      !Guards.isTransformable(node) ||
+      node.isDestroyed ||
+      node === drawing ||
+      node.context !== drawing.context ||
+      !drawing.el.contains(node.el)
+    )
+      throw new TypeError('Snap nodes must be live shapes inside this drawing');
+}
+
+export function movingBox(nodes: readonly AnyNode[], drawing: Svg): Box | null {
+  let left = Infinity,
+    top = Infinity,
+    right = -Infinity,
+    bottom = -Infinity;
+  for (const node of nodes) {
+    const bounds = boundsIn(node, drawing);
+    if (bounds.status === 'unavailable') return null;
+    if (!('box' in bounds)) continue;
+    const box = bounds.box;
+    left = Math.min(left, box.x);
+    top = Math.min(top, box.y);
+    right = Math.max(right, box.x + box.width);
+    bottom = Math.max(bottom, box.y + box.height);
+  }
+  return left === Infinity ? null : { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+function visible(node: AnyNode): boolean {
+  const view = node.el.ownerDocument.defaultView!;
+  const visibility = view.getComputedStyle(node.el).visibility;
+  if (visibility === 'hidden' || visibility === 'collapse') return false;
+  for (let element: Element | null = node.el; element; element = element.parentElement)
+    if (view.getComputedStyle(element).display === 'none') return false;
+  return true;
+}
+
+export function targetNodes(
+  drawing: Svg,
+  nodes: readonly AnyNode[],
+  options: ResolvedOptions,
+): AnyNode[] {
+  const candidates = options.targets
+    ? options.targets(nodes)
+    : nodes.length
+      ? nodes.flatMap((node) => node.parent?.children ?? [])
+      : drawing.children;
+  const eligible = new Set<AnyNode>();
+  for (const node of candidates) {
+    if (
+      !Guards.isTransformable(node) ||
+      node.isDestroyed ||
+      node.context !== drawing.context ||
+      !drawing.el.contains(node.el) ||
+      nodes.some((selected) => node.el.contains(selected.el) || selected.el.contains(node.el)) ||
+      !visible(node)
+    )
+      continue;
+    eligible.add(node);
+  }
+  // All eligible nodes are attached to the same document; bit 4 means FOLLOWING.
+  const ordered = [...eligible].sort((a, b) =>
+    a === b ? 0 : a.el.compareDocumentPosition(b.el) & 4 ? -1 : 1,
+  );
+  return ordered;
+}
+
+export function measureTargets(
+  drawing: Svg,
+  nodes: readonly AnyNode[],
+  options: ResolvedOptions,
+): Box[] {
+  const boxes: Box[] = [];
+  const ordered = targetNodes(drawing, nodes, options);
+  for (const node of ordered) {
+    const bounds = boundsIn(node, drawing);
+    if ('box' in bounds) boxes.push(bounds.box);
+  }
+  return boxes;
+}