@weasel-js/guides 1.10.1 → 1.11.1

package/README.md

@@ -1,13 +1,13 @@
 # @weasel-js/guides
 
-Placement aids for weasel: a visible grid and snapping to it, guide lines and
-alignment to sibling edges, and the layout strategies a container arranges its
-children with.
-
-Everything here plugs into a seam `@weasel-js/core` already has. A snap
-strategy is a `SnapStrategy`, the select tool's `snap` option takes one, and
-core's `snap()` turns one into a move behavior. The move, resize and insert
-behaviors go in the actions' `behaviors` lists. The grid and guide overlays are
+Placement aids for weasel: a visible grid, ruler guides, the snap sources that
+snap to them and to sibling edges and gaps, and the layout strategies a
+container arranges its children with.
+
+Everything here plugs into a seam `@weasel-js/core` already has. A snap source
+goes in `<SceneCanvas snap={{ sources }}>` or a preset's `snapSources`, and
+competes with every other source under core's one ranking rule; see
+[Snapping](https://github.com/orochi235/weasel/blob/main/docs/snapping.md). The grid and guide overlays are
 `RenderLayer`s for a canvas layer slot, and a layout strategy implements core's
 `LayoutStrategy`.
 
@@ -26,34 +26,42 @@ npm install @weasel-js/guides
 A grid you can see and snap to:
 
 ```tsx
-import { SceneCanvas, type RectPose } from '@weasel-js/core';
-import { createGridLayer, gridSnapStrategy } from '@weasel-js/guides';
+import { SceneCanvas } from '@weasel-js/core';
+import { createGridLayer, gridSnapSource } from '@weasel-js/guides';
 
 const grid = createGridLayer({ spacing: 20, bounds: () => ({ x: 0, y: 0, width: 800, height: 600 }) });
+const snap = { sources: [gridSnapSource({ spacing: 20 })] };
 
 <SceneCanvas
   /* … */
-  selectTool={{ snap: gridSnapStrategy<RectPose>(20) }}
+  snap={snap}
   layers={{ grid: { layer: grid } }}
 />;
 ```
 
-`snapToGrid` and `snapToGuides` exist for move, resize and insert, and each
-has the shape its action expects, so they are imported from a per-action
-subpath:
-
-```ts
-import { snapToGrid } from '@weasel-js/guides/move';
-import { snapToGrid, pointSnapToGrid } from '@weasel-js/guides/resize';
-import { snapToGrid } from '@weasel-js/guides/insert';
-```
+The grid source snaps every snapping gesture — move, resize, insert, the pen —
+and, being a fallback, gives way on any axis a real target in reach claims.
 
 | Area | Exports |
 |---|---|
-| Grid | `createGridLayer`, `createCellHighlightLayer`, `useGridCellHover`, `gridSnapStrategy`, `pointToGridCell`, `pointSnapToGrid`, `roundToCell` |
-| Guides | `useGuides`, `createGuidesLayer`, `guideSnapStrategy`, `deriveAlignmentGuides`, `matchAlignment`, `alignMoveBehavior`, `alignResizeBehavior`, `alignInsertBehavior` |
+| Grid | `createGridLayer`, `createCellHighlightLayer`, `useGridCellHover`, `pointToGridCell`, `roundToCell` |
+| Guides | `useGuides`, `createGuidesLayer`, `deriveAlignmentGuides`, `matchSpacing`, `measureGaps`, `siblingBounds`, `worldBoundsOf`, `worldUnionOf` |
+| Snap sources | `gridSnapSource`, `guideSnapSource`, `alignmentSnapSource`, `spacingSnapSource`, for `<SceneCanvas snap={{ sources }}>` or a preset's `snapSources` |
+| Spacing hints | `createSpacingHintsPreset` (below), `distanceReadout`, `measureDistances` |
 | Layout | `freeform`, `tileGrid`, `snapPoint`, `slots` (with the `rowSlots`, `gridSlots`, and `ringSlots` arrangements), `pack`, `quadtree`, `perContainer` for a strategy that keeps state, and the drop-target pickers `none`, `nearest`, `nearestWithin`, `containedThenNearest`, `cellAt` |
 
+Spacing hints are one `<SceneCanvas features>` preset: its snap sources move
+the selection to the spacing between its siblings (and, with `align`, to their
+edges and centers), the canvas's snap readout marks the equal gaps, and holding
+Alt over a shape measures its distance from the selection. It lives in
+`src/spacingHints/`.
+
+```tsx
+const spacingHints = useMemo(() => createSpacingHintsPreset({ color: '#e0397f' }), []);
+
+<SceneCanvas /* … */ features={['draw', spacingHints]} />;
+```
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,7 +1,5 @@
 import { RefObject } from 'react';
-import { ViewTransform, PlaneValue, PlaneUnits, CommandStroke, RenderLayer, CommandFill, SnapStrategy, DebugSink, OriginProjection, ModifierState, Bounds, PlaneMap, PoseDescriptor, InsertBehavior, MoveBehavior, BoundsConstraint, LayoutSnap, LayoutStrategy, LayoutContainer, Vec2, ContainerBounds, LayoutChild } from '@weasel-js/core';
-export { p as pointSnapToGrid } from './pointSnapToGrid-BaVEjV23.js';
-import { G as Guide, S as SpacingGap } from './types-DRSPiXfk.js';
+import { ViewTransform, PlaneValue, PlaneUnits, View, Dims, CommandStroke, RenderLayer, CommandFill, UnitScope, PerAxis, Bounds, PlaneMap, PoseDescriptor, Scene, NodeId, SnapSource, SceneNode, SurfaceContribution, FeaturePreset, LayoutSnap, LayoutStrategy, LayoutContainer, Vec2, ContainerBounds, LayoutChild } from '@weasel-js/core';
 import { Rect } from '@weasel-js/geom';
 
 /** Round `value` to the nearest multiple of `cellSize`. Returns 0 when the result would be -0. */
@@ -79,8 +77,13 @@ interface GridLayerOpts {
     spacing: PlaneValue;
     /** Optional unit system for resolving tagged `spacing` values. */
     unitSystem?: PlaneUnits;
-    /** Bounds of the area to cover, in world units. */
-    bounds: () => {
+    /**
+     * The area to cover, in world units, read every paint with that paint's
+     * view and canvas size. Lines start at its own `x`/`y`. Omitted, the grid
+     * covers whatever the canvas shows, with its lines on world multiples of
+     * `spacing` so they stay put as the view pans.
+     */
+    bounds?: (view: View, dims: Dims) => {
         x: number;
         y: number;
         width: number;
@@ -128,28 +131,10 @@ interface CellHighlightLayerOpts {
 /** Build a `RenderLayer` that fills a single grid cell — typically a snap-target preview. */
 declare function createCellHighlightLayer(opts: CellHighlightLayerOpts): RenderLayer<unknown>;
 
-/** Snap-strategy that rounds the pose's origin to the nearest multiple of
- *  `spacing` (resolved through `unitSystem`). Either may be per axis —
- *  `{ x, y }` — for a grid whose axes have different pitches or units. For
- *  non-rect TPose pass an `OriginProjection` so the strategy knows how to
- *  read/write the origin. */
-declare function gridSnapStrategy<TPose>(spacing: PlaneValue, unitSystem?: PlaneUnits): SnapStrategy<TPose>;
-/** As above, additionally reporting each candidate to a debug sink. */
-declare function gridSnapStrategy<TPose>(spacing: PlaneValue, opts: {
-    unitSystem?: PlaneUnits;
-    debug?: DebugSink;
-}): SnapStrategy<TPose>;
-/** As above, for a `TPose` that is not a rect: `origin` tells the strategy how
- *  to read and write the pose's origin. */
-declare function gridSnapStrategy<TPose>(spacing: PlaneValue, opts: {
-    unitSystem?: PlaneUnits;
-    origin: OriginProjection<TPose>;
-    debug?: DebugSink;
-}): SnapStrategy<TPose>;
 /**
  * The integer cell `{col, row}` that contains `point`. Pair with
  * `createCellHighlightLayer` (its `getCell` callback) to draw a snap-target
- * preview that uses the same spacing as `gridSnapStrategy`.
+ * preview that uses the same spacing as `gridSnapSource`.
  */
 declare function pointToGridCell(point: {
     x: number;
@@ -162,12 +147,67 @@ declare function pointToGridCell(point: {
     row: number;
 };
 
+/** How a grid reads the unit scopes a scene's containers declare
+ *  (`ContainerNode.units`). */
+interface GridScopes {
+    /** The scene's outermost scope, as `sceneUnitScopes` is handed it. The grid's
+     *  `spacing` is read in its system, in place of `unitSystem`. */
+    root: UnitScope;
+    /** The pitch inside a container's scope, written in that scope's units.
+     *  Default: the grid's `spacing`, read there, so a bare 10 is ten of its
+     *  base units. */
+    spacing?: (scope: UnitScope) => PlaneValue;
+}
+/**
+ * A grid's pitch on each axis, in world units, where `chain` (outermost
+ * first, rooted at `scopes.root`) encloses it: `spacing` in the root, and
+ * `scopes.spacing` of the innermost scope inside a container's.
+ */
+declare function scopedGridPitch(spacing: PlaneValue, scopes: GridScopes, chain: readonly UnitScope[]): PerAxis<number>;
+
+/**
+ * Guide — a horizontal or vertical world-space line used as a snap target
+ * and an optional rendered overlay.
+ *
+ * `axis === 'x'` means a vertical line at world `x = offset` (snaps the X
+ * coordinate); `axis === 'y'` means a horizontal line at world `y = offset`
+ * (snaps the Y coordinate). This matches "the X axis snaps along X."
+ */
+interface Guide {
+    /** Stable, caller-supplied id. Used by removeGuide and as a render key. */
+    id: string;
+    /** Which world axis this guide constrains. */
+    axis: 'x' | 'y';
+    /** World-space offset along the constrained axis. */
+    offset: number;
+    /** The stretch of the line worth drawing, in world units on the other
+     *  axis: an `'x'` guide's y range. Derived alignment guides carry the
+     *  extent of the boxes that produced them. Absent, the line has no extent
+     *  of its own and `createGuidesLayer` draws it across the canvas. */
+    span?: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * SpacingGap — one measured gap between two boxes, drawn as an equal-spacing
+ * marker. `axis === 'x'` is a horizontal gap from world `x = min` to
+ * `x = max`, drawn at `y = at`; `axis === 'y'` is the vertical counterpart.
+ */
+interface SpacingGap {
+    axis: 'x' | 'y';
+    min: number;
+    max: number;
+    /** World position on the other axis the marker is drawn at. */
+    at: number;
+}
+
 /** Return shape for `useGuides`. */
 interface UseGuidesReturn {
     /** Live list (state). Re-renders when guides change. */
     guides: Guide[];
     /** Stable getter; reads the latest list without forcing a re-render.
-     *  Pass to `guideSnapStrategy` and `createGuidesLayer`. */
+     *  Pass to `guideSnapSource` and `createGuidesLayer`. */
     getGuides: () => Guide[];
     /** Add a guide. If a guide with the same id already exists it is replaced. */
     addGuide: (guide: Guide) => void;
@@ -178,7 +218,7 @@ interface UseGuidesReturn {
 }
 /**
  * In-memory guide storage. Holds a list of horizontal/vertical world-space
- * lines that callers can pass to `guideSnapStrategy` (snap behavior) and
+ * lines that callers can pass to `guideSnapSource` (snap source) and
  * `createGuidesLayer` (render layer).
  *
  * v1 is intentionally minimal: no undo integration, no persistence, no
@@ -195,7 +235,7 @@ declare function useGuides(initial?: Guide[]): UseGuidesReturn;
  * (`SpacingGap`) as ticked segments labeled with their size.
  *
  * Guides are not scene objects; they live outside the scene and are managed
- * via `useGuides`. Pair with `guideSnapStrategy` (snap behavior) to keep
+ * via `useGuides`. Pair with `guideSnapSource` (snap source) to keep
  * the visual guide and the snap target in lockstep.
  */
 
@@ -203,8 +243,8 @@ declare function useGuides(initial?: Guide[]): UseGuidesReturn;
 interface GuidesLayerOpts {
     /** Stable getter for the live guide list — typically `useGuides().getGuides`. */
     getGuides: () => readonly Guide[];
-    /** Stable getter for the equal-spacing gaps to draw — typically what an
-     *  alignment behavior's `setActiveGaps` last published. */
+    /** Stable getter for the equal-spacing gaps to draw, such as
+     *  `matchSpacing`'s. */
     getGaps?: () => readonly SpacingGap[];
     /** `'span'` (default) draws a guide that carries a `span` as a segment over
      *  it; `'full'` draws every guide across the whole canvas. */
@@ -234,18 +274,6 @@ interface GuidesLayerOpts {
  *  space, projected from world coordinates via the active view. */
 declare function createGuidesLayer(opts: GuidesLayerOpts): RenderLayer<unknown>;
 
-/** Which feature of a box to test against candidates, per axis.
- *  'min' = left/top edge, 'center' = centerline, 'max' = right/bottom edge. */
-type AlignAnchor = 'min' | 'center' | 'max';
-/** The correction an alignment match asks for: the translation that lands the
- *  dragged bounds on the matched guides, and the guides themselves so they can
- *  be drawn. */
-interface AlignMatchResult {
-    dx: number;
-    dy: number;
-    activeX: Guide | null;
-    activeY: Guide | null;
-}
 /** Which edges of a box move on one axis during a spacing match: `'both'`
  *  for a translate, `'min'`/`'max'` for a resize dragging that edge. */
 type SpacingEdge = 'both' | 'min' | 'max';
@@ -272,74 +300,22 @@ interface DeriveAlignmentGuidesOptions<TPose = Bounds> {
     edges?: boolean;
     /** Emit centerX (x) and centerY (y) guides. Default true. */
     centers?: boolean;
-    /** How to read each target. Pass the same descriptor `alignMoveBehavior`
-     *  gets, or the two sides disagree. Default `AUTO_POSE_DESCRIPTOR`. */
+    /** How to read each target. Default `AUTO_POSE_DESCRIPTOR`. */
     poseDescriptor?: PoseDescriptor<TPose>;
 }
-/** Common options shared by the three alignment behavior factories.
- *
- *  Everything crossing this interface is in the camera's world, whatever
- *  layer the gesture edits: the candidate lines and spacing boxes handed in,
- *  and the lines and gaps published, which a layer the camera draws shows.
- *  A gesture on a `parallax` layer carries them into its plane to match. */
-interface AlignmentBehaviorBase {
-    /** Live candidate lines — consumer derives from current siblings + page.
-     *  A sibling on a parallax layer goes through `deriveAlignmentGuides`'
-     *  `planeOf`, or its lines land where its plane's numbers say, not where
-     *  it is drawn. */
-    getCandidates: () => readonly Guide[];
-    /** Publish the currently-matched line(s). Called every onMove; cleared
-     *  (`[]`) on a miss and on onEnd. */
-    setActiveGuides: (guides: readonly Guide[]) => void;
-    /** Tolerance in screen px, read through the gesture's view. Default 6. */
-    tolerance?: number;
-    /** Modifier key that bypasses snapping while held. */
-    bypassKey?: keyof ModifierState;
-    /** Boxes to measure gaps between for equal-spacing snaps (`matchSpacing`):
-     *  the siblings' visual bounds, without the dragged ones. Omit to snap to
-     *  alignment lines only. On each axis the nearer of the two snaps wins.
-     *  Move and unrotated resize use it; insert does not. */
-    getSpacingTargets?: () => readonly Bounds[];
-    /** Publish the equal-gap markers. Called with the guides; cleared (`[]`) on
-     *  a miss and on onEnd. */
-    setActiveGaps?: (gaps: readonly SpacingGap[]) => void;
-}
 
 /** Derive candidate alignment lines from a set of sibling poses plus an
  *  optional page box. Each box contributes up to 3 guides per axis: the two
  *  edges and the center. Overlapping offsets collapse to one candidate, whose
  *  `span` covers every box that produced it.
- *  Poses go through the same descriptor `alignMoveBehavior` matches with, so
- *  a rotated sibling advertises its ink edges rather than its stored box.
+ *  Poses go through `opts.poseDescriptor`, so a rotated sibling advertises
+ *  its ink edges rather than its stored box.
+ *  The moving selection is measured with its stroke (`drawnBoundsOf`), so
+ *  pass each sibling's `drawnAABBOf` box as its target for the two to agree.
  *  The lines are in the camera's world: a sibling on a parallax layer needs
  *  `planeOf` to say which plane its pose is in. */
 declare function deriveAlignmentGuides<TPose = Bounds>(targets: readonly TPose[], opts?: DeriveAlignmentGuidesOptions<TPose>): Guide[];
 
-/** Move/insert test all three features per axis. */
-declare const MOVE_ANCHORS: {
-    x: readonly AlignAnchor[];
-    y: readonly AlignAnchor[];
-};
-/**
- * Match a moving box's selected edge/center features against candidate guide
- * lines. Returns the per-axis snap delta and the matched candidate line(s).
- * The two axes resolve independently; on each axis the closest in-tolerance
- * (feature, candidate) pair wins. A matched guide that carries a `span` comes
- * back with it stretched to cover the snapped box, so the drawn segment runs
- * from the aligned siblings to the box being dragged.
- *
- * `worldTolerance` is per axis because a screen-pixel tolerance is not one
- * world distance under non-uniform zoom. Pass the same number twice for a
- * world-space tolerance.
- */
-declare function matchAlignment(bounds: Bounds, candidates: readonly Guide[], worldTolerance: {
-    x: number;
-    y: number;
-}, anchors: {
-    x: readonly AlignAnchor[];
-    y: readonly AlignAnchor[];
-}): AlignMatchResult;
-
 /**
  * The visible gaps between neighboring boxes along `axis`: for `'x'`, each box
  * and the nearest box to its right that shares some of its vertical range, as
@@ -368,64 +344,173 @@ declare function matchSpacing(bounds: Bounds, targets: readonly Bounds[], worldT
     y: SpacingEdge | null;
 }): SpacingMatchResult;
 
-/** Options for move and resize — adds the pose descriptor for non-rect poses. */
-interface AlignMoveArgs<TPose> extends AlignmentBehaviorBase {
-    poseDescriptor?: PoseDescriptor<TPose>;
-}
-/** Move behavior: snap the dragged selection's union box (edges + center) to
- *  candidates, shaping the proposed translate. The gesture applies the
- *  transform uniformly to every dragged id, so the selection shifts together
- *  and stays rigid. Single-select is the degenerate one-box union. Publishes
- *  the matched line(s); clears on miss, end and cancel. */
-declare function alignMoveBehavior<TPose>(given: AlignMoveArgs<TPose>): MoveBehavior<TPose>;
-/** Insert behavior: snap the live `current` point to candidates (treating it
- *  as a zero-size box). Publishes the matched line(s). */
-declare function alignInsertBehavior<TPose>(given: AlignmentBehaviorBase): InsertBehavior<TPose>;
-/** Resize constraint: snap the corner(s) the drag moves, as drawn, to
- *  candidates; the pinned corner stays fixed. On an unrotated pose that is
- *  the moving edge(s). On a rotated one the node's own axes set how the
- *  corner can travel: a corner handle snaps each world axis, an edge handle
- *  slides its edge until the nearer of its two corners meets a line.
- *  `poseDescriptor` reads the origin pose's box and rotation, and must match
- *  the resize action's. Publishes the matched line(s). */
-declare function alignResizeBehavior<TPose extends Bounds>(given: AlignMoveArgs<TPose>): BoundsConstraint<TPose>;
-
-/** Default snap tolerance (screen pixels). */
-declare const DEFAULT_GUIDE_TOLERANCE_PX = 6;
-/** Options for `guideSnapStrategy`. */
-interface GuideSnapOptions<TPose> {
-    /**
-     * Tolerance in screen pixels, divided by the gesture view's scale so the
-     * trigger zone stays the same on screen at every zoom. Defaults to
-     * `DEFAULT_GUIDE_TOLERANCE_PX`.
-     */
-    tolerance?: number;
-    /**
-     * Projection used when `TPose` doesn't expose `{x, y}` directly (Path,
-     * polygon, etc.) — same contract as `gridSnapStrategy`. Defaults to the
-     * rect-pose identity projection.
-     */
-    origin?: OriginProjection<TPose>;
+/** Options shared by the scene readers below. */
+interface SceneBoundsOptions {
+    /** How to read a pose's box. Pass the canvas's, so these agree with what it
+     *  draws. Default `AUTO_POSE_DESCRIPTOR`. */
+    poseDescriptor?: PoseDescriptor<unknown>;
 }
+/** The world box each id is drawn in, rotation included, skipping ids the
+ *  scene no longer holds. Read through the scene's composition. */
+declare function worldBoundsOf(scene: Scene<unknown, string, unknown>, ids: Iterable<NodeId>, opts?: SceneBoundsOptions): Bounds[];
+/** The union of `ids`' world boxes, or null when none is in the scene. */
+declare function worldUnionOf(scene: Scene<unknown, string, unknown>, ids: Iterable<NodeId>, opts?: SceneBoundsOptions): Bounds | null;
 /**
- * Snap-strategy that snaps the pose's origin to the nearest guide line on
- * each axis when within tolerance. Each axis is considered independently:
- * a vertical guide (`axis: 'x'`) constrains X, a horizontal guide
- * (`axis: 'y'`) constrains Y. When multiple guides are within range on the
- * same axis, the closest wins.
- *
- * Pair with `useGuides` for storage and `createGuidesLayer` for rendering.
- * Combining with `gridSnapStrategy` is left to the consumer.
+ * The world boxes of `ids`' siblings ({@link siblingIds}). What an
+ * equal-spacing snap measures gaps between while `ids` move.
  */
-declare function guideSnapStrategy<TPose extends {
+declare function siblingBounds(scene: Scene<unknown, string, unknown>, ids: readonly NodeId[], opts?: SceneBoundsOptions): Bounds[];
+
+type Point = {
     x: number;
     y: number;
-}>(getGuides: () => readonly Guide[], options?: Omit<GuideSnapOptions<TPose>, 'origin'>): SnapStrategy<TPose>;
-/** As above, for a `TPose` that is not a rect: `origin` tells the strategy how
- *  to read and write the pose's origin. */
-declare function guideSnapStrategy<TPose>(getGuides: () => readonly Guide[], options: GuideSnapOptions<TPose> & {
-    origin: OriginProjection<TPose>;
-}): SnapStrategy<TPose>;
+};
+/** Options for `gridSnapSource`. */
+interface GridSnapSourceOptions {
+    /** The grid's pitch, or one per axis, in `unitSystem`'s units. */
+    spacing: PlaneValue;
+    /** A point the lattice passes through. Default `(0, 0)`. */
+    origin?: Point;
+    unitSystem?: PlaneUnits;
+    /** Read the unit scope the subject sits in: a node inside a millimeter
+     *  sub-assembly snaps on that scope's pitch. The subject's scope is the one
+     *  all its nodes share; for a gesture with none, the scope of the
+     *  container it draws into (`SnapCollect.parent`), else the root. */
+    scopes?: GridScopes;
+}
+/**
+ * A grid as snap targets: for each origin or pointer probe, the grid line on
+ * either side of it on each axis. Its reach is unlimited and it is a
+ * fallback, so it holds every axis no target claims and never displaces one.
+ * Its lines are the camera's, carried into the plane a gesture runs in.
+ */
+declare function gridSnapSource(opts: GridSnapSourceOptions): SnapSource;
+
+/**
+ * Ruler guides as snap targets: each guide within reach of an origin or
+ * pointer probe is a line it may land on. Reads `getGuides` every frame, so
+ * a guide added mid-drag counts at once.
+ */
+declare function guideSnapSource(getGuides: () => readonly Guide[]): SnapSource;
+
+/** Which nodes may be targets; one that fails offers no lines or gaps. */
+type TargetFilter = (node: SceneNode<unknown, string, unknown>) => boolean;
+
+/** Options for `alignmentSnapSource`. */
+interface AlignmentSnapSourceOptions {
+    /** A page box whose edges and center are lines too, in the camera's world. */
+    page?: Bounds | (() => Bounds | null | undefined);
+    /** The lines to align to, in place of the edges and centers of the
+     *  subject's siblings (of the scene's top-level nodes, for a point gesture). */
+    getCandidates?: () => readonly Guide[];
+    /** Which nodes offer lines. Narrows the default siblings; not `getCandidates`. */
+    filter?: TargetFilter;
+    /** The color of the lines it marks. Default: the readout layer's. */
+    color?: string;
+    /** Overrides the canvas's reach for these targets, in screen px. */
+    reachPx?: number;
+}
+/**
+ * The edges and centers of the subject's siblings, and optionally a page, as
+ * snap targets: each is a line a box or pointer probe may land on. A move's
+ * left, center and right (top, center, bottom) all try every line, as Figma's
+ * smart guides do. When the result meets a line, its mark runs from the
+ * subject's box to the farthest sibling on that line.
+ */
+declare function alignmentSnapSource(opts?: AlignmentSnapSourceOptions): SnapSource;
+
+/** Options for `spacingSnapSource`. */
+interface SpacingSnapSourceOptions {
+    /** The boxes to measure gaps between, in place of the subject's siblings. */
+    getTargets?: () => readonly Bounds[];
+    /** Which nodes offer gaps. Narrows the default siblings; not `getTargets`. */
+    filter?: TargetFilter;
+    /** The color of the gaps it marks. Default: the readout layer's. */
+    color?: string;
+    /** Overrides the canvas's reach for these targets, in screen px. */
+    reachPx?: number;
+}
+/**
+ * Equal spacing as snap targets, Figma's: on each axis, the positions of the
+ * subject's box that make its gap to a neighbor equal one already between
+ * two siblings, or center it between its two neighbors. A resize moves only
+ * the edges it drags. When the result meets one, it marks every gap of that
+ * size, the box's own included.
+ */
+declare function spacingSnapSource(opts?: SpacingSnapSourceOptions): SnapSource;
+
+/** The distances `measureDistances` found, ready for `createGuidesLayer`:
+ *  `gaps` as its `getGaps`, `leaders` as its `getGuides`. */
+interface DistanceReadout {
+    /** One measured distance per gap, labeled with its length when drawn. */
+    gaps: SpacingGap[];
+    /** Where a gap runs past the target, the line from the gap's end along the
+     *  target's edge to the target, so the number reads as reaching it. */
+    leaders: Guide[];
+}
+/**
+ * The distances between two boxes, on each axis where they separate: for
+ * `from` left of `to`, the gap from `from`'s right edge to `to`'s left. A gap
+ * is drawn through the range the boxes share on the other axis, or through
+ * `from`'s center when they share none, with a leader to `to`. When one box
+ * holds the other on an axis and they overlap on the other, the inner box's
+ * distances to the outer's two edges on that axis instead. An axis where the
+ * boxes partly overlap, or meet flush, has no distance.
+ */
+declare function measureDistances(from: Bounds, to: Bounds): DistanceReadout;
+
+/** Options for `distanceReadout`. */
+interface DistanceReadoutOptions {
+    /** The key held to show the readout. Default `'alt'`. */
+    modifier?: 'alt' | 'ctrl' | 'meta' | 'shift';
+    /** The color of the marks it writes. Default: the readout layer's. */
+    color?: string;
+    /** Contribution id, and the prefix of its action's. Default `'distanceReadout'`. */
+    id?: string;
+}
+/** What `distanceReadout` returns: a surface contribution, plus a read of
+ *  what it is showing. */
+interface DistanceReadoutContribution extends SurfaceContribution {
+    /** The distances on screen now; empty while hidden. */
+    read(): DistanceReadout;
+}
+/**
+ * Distance readouts on hover: while `modifier` is held over a shape, the
+ * distances from the selection's box to that shape's, on each axis where they
+ * separate, measured by `measureDistances` and drawn as labeled gaps. Pass it
+ * in `<SceneCanvas ambient>`. It runs on `hover` bindings, so it claims no
+ * input, and it reads the canvas's `selection`, `scene`, `nodeAtPoint`,
+ * `poseDescriptor`, and `snapReadout` deps. A press hides it.
+ */
+declare function distanceReadout(opts?: DistanceReadoutOptions): DistanceReadoutContribution;
+
+/** Options for `createSpacingHintsPreset`. */
+interface SpacingHintsOptions {
+    /** Preset id. Default `'spacingHints'`. */
+    id?: string;
+    /** Snap a move so its gap to a neighbor equals one already between its
+     *  siblings, and mark the equal gaps. Default true. */
+    spacing?: boolean;
+    /** Snap to the siblings' edges and centers too, and mark the line met.
+     *  Default false. */
+    align?: boolean;
+    /** Snap distance in screen px. Default the canvas's reach. */
+    tolerance?: number;
+    /** Which nodes the snap sources take as siblings to line up or space against. */
+    filter?: TargetFilter;
+    /** The Alt-hover distance readout, configured, or `false` for none. Default
+     *  on, with the preset's `color`. */
+    readout?: false | Omit<DistanceReadoutOptions, 'color'>;
+    /** The color of the marks and the readout. */
+    color?: string;
+}
+/**
+ * Spacing hints as one `<SceneCanvas features>` preset: snap sources for
+ * equal spacing between siblings and, if asked, alignment to their edges
+ * and centers, whose marks the canvas's snap readout draws; and holding Alt
+ * over a shape measures its distance from the selection.
+ */
+declare function createSpacingHintsPreset(opts?: SpacingHintsOptions): FeaturePreset;
 
 /** Snap policy that never picks a target — every drop is rejected, which is
  *  what a free-form container wants. */
@@ -756,4 +841,4 @@ interface Sequencer<TPose> {
  */
 declare function sequenceLayout<TPose>(seq: Sequencer<TPose>): LayoutStrategy<TPose>;
 
-export { type AlignAnchor, type AlignMatchResult, type AlignMoveArgs, type AlignmentBehaviorBase, type Arrangement, type CellHighlightLayerOpts, DEFAULT_GUIDE_TOLERANCE_PX, type DeriveAlignmentGuidesOptions, type FreeformOptions, type GridLayerOpts, type GridSlotsOptions, Guide, type GuideSnapOptions, type GuidesLayerOpts, MOVE_ANCHORS, type PackOptions, type PackOverflow, type PerContainerOptions, type PerContainerStrategy, type QuadtreeCell, type QuadtreeOptions, type QuadtreeStrategy, type RingSlotsOptions, type RowSlotsOptions, type Sequencer, type Slot, type SlotsOptions, type SnapPattern, type SnapPointOptions, type SpacingEdge, SpacingGap, type SpacingMatchResult, type TileGridOptions, type TileGridOverflow, type UseGridCellHoverOptions, type UseGridCellHoverReturn, type UseGuidesReturn, alignInsertBehavior, alignMoveBehavior, alignResizeBehavior, cellAt, containedThenNearest, createCellHighlightLayer, createGridLayer, createGuidesLayer, deriveAlignmentGuides, freeform, gridSlots, gridSnapStrategy, guideSnapStrategy, matchAlignment, matchSpacing, measureGaps, nearest, nearestWithin, none, pack, perContainer, pointToGridCell, quadtree, ringSlots, roundToCell, rowSlots, sequenceLayout, slots, snapPoint, tileGrid, useGridCellHover, useGuides };
+export { type AlignmentSnapSourceOptions, type Arrangement, type CellHighlightLayerOpts, type DeriveAlignmentGuidesOptions, type DistanceReadout, type DistanceReadoutContribution, type DistanceReadoutOptions, type FreeformOptions, type GridLayerOpts, type GridScopes, type GridSlotsOptions, type GridSnapSourceOptions, type Guide, type GuidesLayerOpts, type PackOptions, type PackOverflow, type PerContainerOptions, type PerContainerStrategy, type QuadtreeCell, type QuadtreeOptions, type QuadtreeStrategy, type RingSlotsOptions, type RowSlotsOptions, type SceneBoundsOptions, type Sequencer, type Slot, type SlotsOptions, type SnapPattern, type SnapPointOptions, type SpacingEdge, type SpacingGap, type SpacingHintsOptions, type SpacingMatchResult, type SpacingSnapSourceOptions, type TargetFilter, type TileGridOptions, type TileGridOverflow, type UseGridCellHoverOptions, type UseGridCellHoverReturn, type UseGuidesReturn, alignmentSnapSource, cellAt, containedThenNearest, createCellHighlightLayer, createGridLayer, createGuidesLayer, createSpacingHintsPreset, deriveAlignmentGuides, distanceReadout, freeform, gridSlots, gridSnapSource, guideSnapSource, matchSpacing, measureDistances, measureGaps, nearest, nearestWithin, none, pack, perContainer, pointToGridCell, quadtree, ringSlots, roundToCell, rowSlots, scopedGridPitch, sequenceLayout, siblingBounds, slots, snapPoint, spacingSnapSource, tileGrid, useGridCellHover, useGuides, worldBoundsOf, worldUnionOf };