@rasamjs/tools 0.0.0-stage → 0.2.0

package/API.md

@@ -0,0 +1,308 @@
+# Tools API
+
+## Snapping entry
+
+```ts
+import { Snapper } from '@rasamjs/tools/snapping';
+import type { SnapperOptions, SnapRequest, SnapSession } from '@rasamjs/tools/snapping';
+
+declare class Snapper {
+  constructor(drawing: Svg, options?: SnapperOptions);
+  enabled: boolean;
+  readonly isDestroyed: boolean;
+  begin(request: SnapRequest): SnapSession | null;
+  update(): this;
+  destroy(): void;
+}
+```
+
+`Svg`, `Point` and `AnyNode` come from `@rasamjs/core`. The constructor needs a live,
+mounted rasam SVG drawing with an owning window. Invalid drawings or options fail
+before registering disposal callbacks. Construction and sessions leave managed SVG
+content unchanged; applications use the returned pointer to perform their own edits.
+
+## Options
+
+| Option                                                      | Default  | Meaning                                                                                                                                    |
+| ----------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tolerance: number`                                         | `6`      | Nonnegative, finite client pixels, converted independently for the current root x/y mapping on each `snap()` call.                         |
+| `shapes: boolean`                                           | `true`   | Enable alignment to target edges and centers.                                                                                              |
+| `spacing: boolean`                                          | `true`   | Equalize gaps to two neighbors or match an existing positive gap. Independent of `shapes`.                                                 |
+| `grid: number \| { size: number; origin?: Point } \| null`  | `null`   | Positive, finite size in drawing units. Origin defaults to `{ x: 0, y: 0 }` and is copied. Only moving edges or points snap to grid lines. |
+| `targets: (nodes: readonly AnyNode[]) => Iterable<AnyNode>` | Siblings | Replaces the default target list; called once per `begin()` when shapes or spacing are enabled.                                            |
+| `modifier: 'ctrl' \| 'none'`                                | `'ctrl'` | Whether the caller's `ignore` flag temporarily disables snapping.                                                                          |
+| `style: { stroke?: string; gapStroke?: string }`            | `#f00`   | Nonempty SVG strokes. `stroke` colors alignment; `gapStroke` colors gap markers and defaults to `stroke`.                                  |
+
+Default targets combine siblings from every moving node's parent, deduplicated in
+document order. Selected nodes, their descendants and ancestor containers are excluded.
+Detached, destroyed, foreign, CSS-hidden, empty and unavailable targets are skipped.
+Point requests default to drawing children and pass `[]` to `targets`.
+
+`begin()` snapshots target boxes and moving features in drawing units. Removing or
+moving a target afterward does not change the active session. Shape candidates win
+equal-distance grid ties. Shape ties use document order even when a custom callback
+returns nodes in another order. Each root axis snaps independently.
+
+## Requests and sessions
+
+```ts
+type SnapRequest =
+  | { readonly kind: 'point'; readonly client: Point }
+  | {
+      readonly kind: 'move' | 'resize';
+      readonly nodes: readonly AnyNode[];
+      readonly client: Point;
+      readonly corners: readonly Point[];
+      readonly anchor?: Point;
+      readonly centered?: boolean;
+    };
+
+interface SnapSession {
+  snap(client: Point, modifiers: { readonly ignore: boolean; readonly centered?: boolean }): Point;
+  end(): void;
+}
+```
+
+`client` is the initial pointer in client pixels. Move requests snap the union of the
+nodes' root-space axis-aligned boxes. Pointer offsets from shape edges are preserved.
+The `corners` field may be empty for moves. Point requests snap a single root-space
+point without a box.
+
+Resize requests need four client-space frame corners in local clockwise order:
+top-left, top-right, bottom-right, bottom-left. `anchor` is an edge or corner of the
+unit frame, using `0`, `0.5` and `1`, with both coordinates at `0.5` disallowed. Only
+dragged axes snap. Quarter turns and reflections are supported; arbitrarily rotated,
+skewed or fully degenerate frames return `null`. An axis-aligned flat frame can still
+snap its nondegenerate axis. The alignment test uses relative floating point tolerance.
+The active-edge correction is the same for centered resizing; the caller applies its
+centered, ratio and minimum-size constraints after receiving the corrected pointer.
+Pass the resolved current policy as `modifiers.centered` if it can change mid-session.
+Omitting it uses the initial request's `centered` value. Transformer 0.3.0 forwards the
+current policy on every sample, including stationary Alt changes.
+
+No eligible targets and no grid, empty moving geometry, unavailable mappings, disabled
+snapping or a destroyed owner yield `null`. Invalid request kinds, node membership,
+pointer coordinates, resize corners or anchors throw `TypeError`.
+
+Call `snap(client, { ignore: event.ctrlKey || event.metaKey })` for the decided Ctrl/Cmd
+override. `modifier: 'none'` disregards `ignore`. Pan and zoom may change during a
+session: the current client mapping and per-axis tolerance are read on every call.
+Unavailable mappings return the original client point. Inputs are never mutated.
+
+## Lifecycle
+
+`enabled` starts at `true`. Disabling it makes an active session return the original
+pointer; re-enabling it resumes the session. A new `begin()` ends the previous session.
+`end()` is idempotent, and ended sessions return their input unchanged. Starting no
+replacement session also ends the previous one. Custom target callbacks that destroy
+the owner or begin another session cannot install a stale outer session.
+
+`isDestroyed` starts at `false`. `destroy()` ends the active session, marks the owner
+destroyed and removes the drawing-disposal subscription. It can be repeated safely.
+It leaves the drawing and other snappers usable. Drawing disposal destroys its
+snappers automatically. Changing `enabled` cannot revive a destroyed instance.
+
+The original `/snapping` entry's only runtime export is `Snapper`; `SnapperOptions`, `SnapRequest` and `SnapSession`
+are type exports. Imports are safe without a document. There is no package root export,
+and internal module subpaths are blocked.
+
+## Equal spacing
+
+Spacing is enabled independently of shape alignment. Disable both `shapes` and `spacing`
+for a grid-only tool. Target boxes and reference gaps are snapshotted once at `begin()`;
+pointer samples use cached numbers without measuring target DOM geometry again.
+
+Neighbors must overlap the proposed moving box on the perpendicular axis (touching
+boundaries and the zero-size point case count). Each axis uses its closest surrounding
+target edges. Targets that contain the moving box on an axis, such as a background or
+panel behind it, are not neighbors on that axis; partially overlapping targets still
+block. A move can center the box between two neighbors or put an edge one
+reference-gap length before/after a neighbor. Reference gaps are positive gaps after
+the furthest preceding target that overlaps the next target perpendicularly; overlapping
+targets do not create a gap. Targets that contain the next target on that axis are
+backgrounds and neither create nor block its gap. Reference gaps may come from another row or column.
+
+Resize correction changes only the dragged edge, including after a flip. An ordinary
+resize can equalize its two neighboring gaps or match a reference gap at that edge.
+Centered resizing can match a reference at the dragged edge; already-equal opposing
+gaps are marked with zero correction because changing size cannot fix an off-center
+frame. Other transformer constraints keep their existing priority.
+
+The closest correction within the current client-pixel tolerance wins. Exact-distance
+ties prefer shape alignment, then grid, then spacing. Spacing ties prefer the
+two-neighbor result, then reference gaps in snapshot document order. Gap markers are
+shown only when all accepted gaps still match within half a client pixel and the
+moving geometry still overlaps its neighbor perpendicularly.
+
+Gap discovery sorts cached far edges once and stops at the nearest eligible preceding
+edge for each target. Its worst case is still quadratic in target
+count. Each pointer query scans cached neighbors and reference gaps (linear), with no
+target DOM reads. Applications can narrow `targets` or disable spacing for large scenes.
+
+## Guides
+
+Guides live in a separate native SVG beside the outer drawing SVG. They stay out of
+managed drawing content, exports, queries and history. The overlay ignores pointer
+events and accessibility navigation. Its default red lines use a fixed one-client-pixel
+stroke; cross marks remain six client pixels wide. `style.stroke` changes their color.
+
+Each snapped axis spans the moving box and its snapshotted target box, with eight
+client pixels of padding and a cross at each box's perpendicular center. Grid and
+point alignment guides use the moving geometry only; this overlay does not draw a grid.
+Applications draw their own grid; the example uses a CSS background that follows the camera.
+Equal gaps use two dimension lines with fixed six-client-pixel perpendicular end caps;
+`gapStroke` defaults to the alignment stroke. Their endpoint positions follow the
+accepted moving box and the snapshotted target edges.
+
+Pointer samples coalesce into one animation-frame draw. For shape requests the draw
+reads accepted geometry after the caller applies the corrected pointer. An axis is
+shown only if its accepted feature lies within half a client pixel of the target.
+This hides misleading guides when ratio, minimum-size or other constraints reject
+alignment. Resize guides follow the dragged anchor, including reflected groups.
+
+`update()` redraws immediately and returns the snapper, so it fits the viewport's
+`overlays` list alongside the transformer. Call it after changing the camera or layout
+yourself. Page and ancestor scrolls and window resizes schedule redraws automatically.
+It is safe after destruction. Disabling snapping, bypassing it, ending a session or
+destroying the owner clears pending paint and hides guides immediately. Destruction
+also removes the overlay and its window listeners.
+
+```ts
+const snapper = new Snapper(drawing);
+const transformer = new Transformer(drawing, { snap: snapper });
+const viewport = new Viewport(drawing, { overlays: [transformer, snapper] });
+```
+
+## Transformer connection
+
+```ts
+import { Transformer } from '@rasamjs/transformer';
+const transformer = new Transformer(drawing, { snap: new Snapper(drawing, { grid: 10 }) });
+```
+
+The bridge is structural: transformer imports no tools runtime. Pointer acquisition
+starts one session for a move or eligible resize; finish, Escape, cancellation, detach
+and destruction end it. With the original `Snapper`, keyboard, rotation and pivot
+gestures do not acquire sessions.
+Ctrl/Cmd is forwarded on pointer samples and re-evaluated when held or released while
+stationary. Existing ratio, minimum-size, `boundBox` and commit-precision rules can
+alter the final alignment after pointer correction.
+
+## Advanced snapping entry
+
+`@rasamjs/tools/snapping/advanced` exports `AdvancedSnapper` and the types
+`AdvancedSnapperOptions`, `AdvancedSnapRequest`, `RotationSnapRequest`,
+`RotationSnapSession` and `RulerGuide`. It implements the transformer's optional
+`rotatedResize`, `keyboard` and `rotate()` capabilities while retaining the original
+constructor, `begin`, `enabled`, `isDestroyed`, `update` and `destroy` lifecycle.
+Existing `Snapper` and custom providers keep their original behavior.
+
+Additional options:
+
+| Option                               | Default | Contract                                                                                                 |
+| ------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------- |
+| `guides: () => Iterable<RulerGuide>` | None    | Snapshot `{ axis: 'x' \| 'y', position: number }` in root drawing units at session start.                |
+| `curves: boolean`                    | `true`  | Snap to path, line, polyline, polygon, circle and ellipse contours. Independent of `shapes`.             |
+| `curveResolution: number`            | `0.25`  | Positive finite sampling interval in initial client pixels, capped at 8,192 segments per subpath.        |
+| `angleTolerance: number`             | `5`     | Positive finite degrees for matching another target's root-space x-axis orientation, modulo 180 degrees. |
+| `keyboard: boolean`                  | `true`  | Opt the provider into transformer keyboard move/resize sessions.                                         |
+
+Resize correction follows the dragged anchor. An oblique side handle stays on its
+one-dimensional frame axis; a corner can correct both root axes. Skew, reflection
+and nonuniform parent transforms are supported. The transformer's ratio, centered,
+minimum-size and bound-box constraints still take priority; positional guides verify
+the accepted geometry before rendering.
+
+`rotate({ nodes, client, corners, pivot })` returns a `RotationSnapSession` or `null`.
+`pivot` and `corners` are client coordinates. Angles and target transforms are
+snapshotted at session start; pointer radius is preserved. `angleSnapped` reports
+whether the most recent pointer sample matched another target. Radius is preserved
+in the gesture's parent coordinate system. A matched target
+wins over the transformer's fixed angle stops; explicit Shift rotation steps retain
+priority. Ctrl/Cmd bypass and `enabled: false` apply to rotation too.
+
+Point requests may include `nodes` to exclude the edited path or other moving
+geometry. Requests may include `keyboard: true`; keyboard sessions reject a snap
+that would hold the edit at its origin or push it backward. Raw keyboard motion
+accumulates independently of corrections so held arrows can leave an existing stop.
+
+Curve targets are sampled from detached copies once per session and queried as pure
+client-space segments. Separate `M` subpaths are never connected. Sampling is
+approximate: very long contours hit the segment cap, and zooming after the snapshot
+can change the screen-space approximation error. Use a smaller `curveResolution`
+when appropriate or restrict `targets` in large scenes. Target edits do not change
+an active snapshot. Invalid/unavailable native geometry is skipped.
+
+## Grid overlay
+
+`@rasamjs/tools/grid` exports `GridOverlay` and `GridOptions`.
+
+```ts
+const grid = new GridOverlay(drawing, {
+  size: 10,
+  origin: { x: 0, y: 0 },
+  stroke: '#d9dee8',
+});
+grid.enabled = false;
+grid.update();
+grid.destroy();
+```
+
+`size` is positive and finite; `origin` is copied and must be finite. Grid lines follow
+the current root mapping, including pan, zoom and CSS transforms. At extreme zoom-out
+the renderer coarsens visible lines to powers-of-two multiples of `size` to keep the
+path bounded; snapping still uses the configured grid size. It is an editor underlay,
+with no managed nodes, exports or undo entries. `isDestroyed` is read-only.
+
+## Ruler guides
+
+`@rasamjs/tools/rulers` exports `RulerGuides`, `RulerOptions` and `NamedGuide`.
+
+```ts
+const rulers = new RulerGuides(drawing, { onChange: (guides) => saveGuides(guides) });
+const id = rulers.add('x', 100);
+rulers.move(id, 120);
+rulers.remove(id);
+rulers.clear();
+```
+
+`guides` is a frozen snapshot of `{ id, axis, position }`. Pass
+`guides: () => rulers.guides` to `AdvancedSnapper`. The left ruler creates vertical
+(`x`) guides; the top ruler creates horizontal (`y`) guides. Drag an existing guide
+to move it. Release over a ruler or outside the host to remove it; double-click also
+removes it. Escape, blur, pointer cancellation and capture loss restore the previous
+guide or discard a new one. Focused guide lines support Arrow keys (Shift: 10 units)
+and Delete/Backspace. Enter/Space on a ruler creates a guide at the current view center.
+Guides are application state, independent of model history. `update`, `isDestroyed`
+and `destroy` follow the overlay lifecycle; mutation methods reject a destroyed owner.
+
+## Drawing and path editing
+
+`@rasamjs/tools/drawing` exports `DrawTool` and `PathEditor`, plus their option,
+handle and adapter types. Their `snapper` option is a structural `PointSnapper`:
+
+```ts
+interface PointSnapper {
+  begin(request: { kind: 'point'; client: Point; nodes?: readonly AnyNode[] }): SnapSession | null;
+}
+```
+
+`DrawTool(drawing, { snapper, kind, paint?, onCreate? })` supports `rect`, `ellipse`,
+`line` and `path`. A path drag creates an editable two-anchor path. The enabled tool
+owns a transparent native pointer layer. Drawing previews remain outside the model;
+release creates one managed shape in one neutral change group. Cancellation creates
+no shape and no undo entry. Programmatic `begin(client, ignore?)`, `move(client,
+ignore?)` and `end(cancelled?)` use client coordinates and the same snapping rules.
+`end()` returns the created node or `null`. Set `enabled: false` to return pointer
+ownership to selection/transformer. `onCreate` runs after the committed edit.
+Active previews follow camera changes without adding temporary model nodes.
+
+`PathEditor(drawing, { snapper, stroke? }).attach(node)` accepts a live `Path`,
+`Polyline` or `Polygon` in this drawing. `attach(null)` disconnects it. `handles`
+returns anchors and Bezier controls with their command/coordinate indexes; arcs
+expose their endpoints. Native handles use pointer capture, keep geometry in local
+units under parent transforms, and exclude the edited node from snapping targets.
+`begin(handleIndex)`, `move(client, ignore?)`, and `end(cancelled?)` expose the same
+editing lifecycle to integrations. Each gesture is one undo step; cancellation
+restores the original attribute representation exactly. `update`, `isDestroyed`
+and `destroy` release all observers, listeners and ownership.

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 0.2.0 (unreleased)
+
+- Add the optional advanced snapping entry: oblique resize anchors, target-relative
+  rotation, contour/segment targets, ruler targets and keyboard nudges.
+- Add camera-aware grid and draggable ruler overlays, snapped drawing tools and
+  path/Bezier point editing with grouped undo and cancellation.
+- Keep the original snapping entry within its existing 6 KiB budget.
+
+## 0.1.0 — 2026-10-31
+
+- Add a 1,000-target drag benchmark in all three engines (`bench:drag`, run by the
+  release gate) that reports drag-start, snap-call and frame times without a hardware
+  threshold, and checks guides, the corrected move and exact undo.
+- Rebuild the example with toggles for snapping, shapes, grid and spacing, and an
+  application-drawn grid that follows the viewport camera.
+- Add default equal-spacing snapping for moves, dragged resize edges and points:
+  equalize two neighboring gaps or match a positive snapshotted gap.
+- Skip targets that contain the moving box or a gap's next target on that axis, so a
+  background or panel sibling no longer disables spacing for the shapes above it.
+- Keep spacing independent of shape alignment, preserve alignment/grid ties and
+  recheck accepted gap lengths and perpendicular overlap before drawing markers.
+- Add `spacing` and `style.gapStroke`, with fixed six-client-pixel gap end caps.
+- Accept optional current `centered` snap metadata so live Alt changes retain correct
+  spacing; callers that omit it keep the initial request policy.
+- Validate real single/group moves and resizes, exact undo, zoom, target snapshots,
+  modifier bypass, opt-out and disposal in all three browser engines.
+- Add a separate red SVG guide overlay, fixed one-pixel strokes, six-pixel cross marks,
+  optional `style.stroke` and viewport-compatible `update()`.
+- Draw once per animation frame from accepted geometry, suppress constrained alignment,
+  and clear pending guides on bypass, disable, cancellation, replacement and disposal.
+- Cover guide alignment through zoom, scrolling, camera changes, transformed containers
+  and the real viewport overlay list in Chromium, Firefox and WebKit.
+- Connect the snapping example to the transformer's structural `snap` option, and
+  validate real single/group drags, modifiers, exact undo, cancellation and error cleanup.
+- Extend the packed consumer to typecheck the real tools/transformer bridge after
+  validating tools independently with its core-only runtime peer.
+- Add Phase 2 engine sessions for moves, dragged resize axes and points, with shape
+  alignment, optional grid snapping and document-order tie rules.
+- Snapshot root-space targets once; convert the six-pixel tolerance through the current
+  client mapping per axis, including mid-session pan and zoom.
+- Add custom and multi-parent sibling targets, hidden-target filtering, temporary
+  Ctrl/Cmd override and safe session replacement/destruction.
+- Add the private `@rasamjs/tools` package with the `./snapping` entry only.
+- Add `Snapper` construction, the `enabled` flag and idempotent destruction, including
+  automatic cleanup when the drawing is destroyed.
+- Add lifecycle tests, the development example, declaration contracts and package gates.
+- Reserve port 4179 for tools browser tests. The owner-approved gzip budget is 6 KiB
+  with core external, increased from the initial 4 KiB cap during Phase 4.
+
+Equal spacing is a later phase. Publication requires separate
+authorization.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rasam contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @rasamjs/tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Opt-in editing tools for rasam drawings. The first entry is `@rasamjs/tools/snapping`;
+the package has no main entry yet. Its only runtime peer is `@rasamjs/core` `^0.1.0`.
+
+## Snapping
+
+While a shape is moved or resized, its edges and centers line up with other shapes,
+its edges land on an optional grid, and its gaps match its neighbors. Red guides and
+gap markers show what it snapped to. Holding Ctrl (Cmd on macOS) bypasses snapping
+while held.
+
+```ts
+import { SVG } from '@rasamjs/core';
+import { Transformer } from '@rasamjs/transformer';
+import { Snapper } from '@rasamjs/tools/snapping';
+
+const drawing = SVG(document.querySelector<HTMLElement>('#drawing')!, {
+  width: 600,
+  height: 400,
+});
+const snapper = new Snapper(drawing, { grid: 10 });
+const transformer = new Transformer(drawing, { snap: snapper });
+
+snapper.enabled = false; // a toolbar toggle
+snapper.enabled = true;
+```
+
+The transformer takes any structural `snap` provider and never imports this package.
+Snapping runs during pointer moves and resizes of frames that are axis-aligned in
+drawing space. Keyboard nudges, rotation and pivot edits keep their existing behavior.
+Ratio, minimum-size, `boundBox` and commit-precision rules keep priority over snapping,
+and guides only show alignments the accepted geometry still has.
+
+### Targets
+
+Targets default to the moving nodes' siblings, combined across parents in document
+order. Moving subtrees, their ancestor containers, hidden nodes and unavailable bounds
+are skipped. `targets(nodes)` replaces the list, for example to limit snapping to an
+artboard or skip locked layers. Targets are measured once per drag, in drawing units.
+
+The tolerance is six client pixels by default and follows the current zoom, so snapping
+feels the same at every zoom level and keeps working when the view changes mid-drag.
+Shape lines win equal-distance ties with the grid, and the grid wins ties with spacing.
+
+### Grid
+
+The grid is off by default. `grid: 10` or `grid: { size: 10, origin: { x: 5, y: 5 } }`
+snaps edges, not centers, to grid lines in drawing units. The snapper does not draw the
+grid; applications draw their own, as the example does with a CSS background.
+
+### Equal spacing
+
+Spacing is on by default and independent of `shapes`. A move can center a shape between
+two neighbors, or put it one existing gap away from a neighbor; existing gaps may come
+from another row or column. Neighbors must overlap the shape on the other axis.
+Backgrounds and panels that contain the shape are not neighbors, while partial overlaps
+block a gap. Resizing corrects only the dragged edge. `spacing: false` turns it off;
+turn off both `shapes` and `spacing` for grid-only snapping.
+
+### Guides
+
+Guides and gap markers live in their own SVG overlay beside the drawing, so they never
+appear in exports, queries or history. Strokes stay one client pixel wide at every zoom.
+`style: { stroke, gapStroke }` sets their colors (default `#f00`). The overlay redraws
+once per animation frame while dragging; `snapper.update()` redraws it immediately.
+With a viewport, list the snapper beside the transformer:
+
+```ts
+import { Viewport } from '@rasamjs/viewport';
+const viewport = new Viewport(drawing, { overlays: [transformer, snapper] });
+```
+
+### Lifecycle
+
+Construct the snapper with a live, mounted rasam SVG drawing. It starts enabled. Options
+are fixed at construction; to change them, destroy the snapper and create another
+behind a small provider object, as the example does. Destroying the drawing destroys its
+snappers. `destroy()` ends an active drag session, removes the overlay and can be
+repeated safely.
+
+### Other tools
+
+Drawing tools and the path editor can snap single points with the same engine:
+
+```ts
+const client = drawing.toClient({ x: 8, y: 8 })!;
+const session = snapper.begin({ kind: 'point', client });
+const corrected = session?.snap(client, { ignore: false }) ?? client;
+session?.end();
+```
+
+`session.snap(client, { ignore: ctrlKey || metaKey })` implements the bypass;
+`modifier: 'none'` ignores that flag.
+
+## Example
+
+Run `npm run dev -w @rasamjs/tools` and open [the snapping example](examples/snapping.html).
+It combines selection, transformer, viewport and snapper, with toggles for snapping,
+shapes, grid and spacing. The server uses port **4179** and refuses an occupied port.
+
+See [API.md](API.md), [RELEASING.md](RELEASING.md) and [CHANGELOG.md](CHANGELOG.md).
+
+## Complete editor snapping
+
+The optional `@rasamjs/tools/snapping/advanced` entry adds oblique resize handles,
+matching other shapes' rotation angles, curve/segment targets, ruler guides and
+keyboard nudges. The original `/snapping` entry retains its 6 KiB budget and behavior.
+
+```ts
+import { AdvancedSnapper } from '@rasamjs/tools/snapping/advanced';
+import { GridOverlay } from '@rasamjs/tools/grid';
+import { RulerGuides } from '@rasamjs/tools/rulers';
+import { DrawTool, PathEditor } from '@rasamjs/tools/drawing';
+
+const rulers = new RulerGuides(drawing);
+const grid = new GridOverlay(drawing, { size: 10 });
+const snapper = new AdvancedSnapper(drawing, {
+  grid: 10,
+  guides: () => rulers.guides,
+  curves: true,
+});
+const transformer = new Transformer(drawing, { snap: snapper });
+const draw = new DrawTool(drawing, { kind: 'rect', snapper });
+draw.enabled = false; // Enable while the rectangle tool is selected.
+const pathEditor = new PathEditor(drawing, { snapper });
+pathEditor.attach(drawing.path({ d: 'M 10 10 Q 80 100 160 10' }));
+```
+
+Use a positioned, isolated host (`position: relative; isolation: isolate`) for these
+native overlays. Include `grid`, `rulers`, `snapper` and `pathEditor` in the viewport's
+`overlays` list, or call their `update()` methods after outside mapping changes.
+All overlays stay outside SVG exports and history. Every tool owns its listeners,
+observers and pointer capture and cleans them up on destruction of the drawing.
+
+Run the [complete editor example](examples/advanced.html) with
+`npm run dev -w @rasamjs/tools`, then open
+`http://127.0.0.1:4179/examples/advanced.html`. It demonstrates all seven additions,
+selection, camera controls, undo/redo and editable Bezier controls.

package/RELEASING.md

@@ -0,0 +1,88 @@
+# Releasing tools
+
+The package remains private. Its initial candidate is `@rasamjs/tools@0.1.0`, with
+`@rasamjs/core@^0.1.0` as its only runtime peer. History, selection, transformer and viewport
+are development dependencies for the example and tests.
+
+The snapping entry has a **6 KiB (6,144 bytes) gzip** budget with all core entry points
+external. The owner approved increasing Phase 1's 4 KiB cap during Phase 4 on 2026-10-31
+after guide rendering measured 4,544 gzip bytes, leaving room for Phase 5 spacing.
+There is no root entry or root bundle budget. Optional entries have separate
+caps: advanced snapping 9 KiB, grid 2.5 KiB, rulers 4 KiB and drawing/path editing
+5 KiB. All core entry points stay external; no optional entry may acquire runtime
+selection, transformer, viewport or history dependencies.
+
+```sh
+npm run build
+npm run release:check -w @rasamjs/tools
+npm run release:check
+```
+
+The tools package gate checks formatting, typechecking, lifecycle unit and browser
+tests, build output, exported declarations, documentation links, the packed consumer
+and bundle size, then runs the drag benchmark. Browser tests use port **4179** in
+Chromium, Firefox and WebKit; the benchmark uses **4189**. Both refuse to reuse an
+existing server. Coordinate these ports before running the gate.
+
+## Drag benchmark
+
+`npm run bench:drag -w @rasamjs/tools` moves one shape with the transformer over 1,000
+targets: a background sibling and 999 small rectangles in rows, with shapes, a 10-unit
+grid and spacing enabled. It times 11 direct `begin()` calls (target measurement, line
+sorting and gap discovery), reporting the first, cold call apart from the 10 warm ones.
+It then sends 600 synthetic pointer moves during native mouse capture in burst and
+paced modes, and writes [drag-benchmark.json](reports/drag-benchmark.json); CI uploads
+it as `tools-drag-benchmark`. Timings are observations with no hardware threshold. The
+run fails unless each drag opens one session, snaps once per applied frame, shows
+guides and hides them on release, follows the corrected pointer exactly, records one
+undo step and undoes to the exact original markup.
+
+Run the full workspace gate before merging when its other package ports are available.
+Do not run it alongside another session's gate. Earlier local port-coordination deferrals are resolved. A passing tools gate alone
+does not replace the full workspace check.
+The shared runner registers tools after its development dependencies and rechecks source
+fingerprints after every package gate.
+
+Build the package and review its emitted declarations before updating the API contract:
+
+```sh
+npm run api:update -w @rasamjs/tools
+npm run api:check -w @rasamjs/tools
+```
+
+The packed consumer installs only core and tools, typechecks through default `dist`
+resolution, verifies document-free imports and source maps, and rejects the package
+root and internal subpaths. Development packages must not become runtime requirements.
+Reports in `reports/` record the reviewed API, size and candidate readiness. The release
+gate builds a candidate tarball; it does not publish it.
+
+Phase 2 adds the engine and options. Its unit suite covers pure box/line/session math
+without a DOM, plus drawing adapters and lifecycle. Browser tests verify engine calls
+through zoomed and panned roots, nested rotations/viewports, multi-parent selections,
+resize eligibility, hidden targets and modifiers. Phase 3 adds the approved transformer
+bridge, real single/group mouse drags, exact undo/cancellation and provider cleanup.
+The packed consumer first verifies tools independently, then installs the transformer
+tarball to typecheck the real structural bridge.
+Phase 4 adds guide rendering and accepted-geometry checks, animation-frame coalescing,
+window listener cleanup, the `update()`/`style.stroke` public API and viewport overlay
+wiring. Browser tests cover fixed pixel dimensions, multiple zoom levels, page scroll,
+mid-drag camera changes, transformed containers and constraint rejection.
+Phase 5 adds the DOM-free spacing engine, accepted gap-marker geometry, independent
+`spacing`/`shapes` flags and `style.gapStroke`. Discovery sorts cached far edges once
+and stops at each target's nearest eligible preceding edge, with quadratic worst-case
+behavior; targets containing a box are backgrounds, not neighbors or obstructions.
+Pointer queries scan cached boxes/gaps. Tests cover both equal-neighbor and existing-gap
+patterns, backgrounds, dragged/centered resize, tie rules, scale-dependent tolerance,
+real undo and fixed-pixel markers. The 6 KiB cap remains unchanged.
+Phase 6 adds the drag benchmark and the example's shape, grid and spacing toggles,
+with an application-drawn grid. It changes no runtime source.
+
+## Advanced editor checks
+
+The advanced editor example is tested with real ruler, drawing, resize, rotation and
+path-handle gestures in Chromium, Firefox and WebKit. Cases cover contour projection,
+separate path subpaths, self exclusion, keyboard progress, grouped undo, cancellation,
+grid camera updates, export isolation and destruction. Unit tests cover the affine
+resize constraint, guide snapshots, rotation radius, provider opt-ins and raw keyboard
+accumulation. Packed consumers import all optional entries without a document and
+compile a real advanced provider through the transformer's structural protocol.

package/dist/advanced/context.d.ts

@@ -0,0 +1,15 @@
+import type { Svg } from '@rasamjs/core';
+import type { ResolvedOptions } from '../snapping/options.js';
+import type { GuideOverlay } from '../snapping/overlay.js';
+import type { AdvancedSnapperOptions } from './types.js';
+export interface SessionContext<Request> {
+    readonly drawing: Svg;
+    readonly options: ResolvedOptions;
+    readonly advanced: AdvancedSnapperOptions;
+    readonly overlay: GuideOverlay;
+    readonly request: Request;
+    readonly isEnabled: () => boolean;
+    readonly isCurrent: () => boolean;
+    readonly onEnd: () => void;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/advanced/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/advanced/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,cAAc,CAAC,OAAO;IACrC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B"}

package/dist/advanced/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/advanced/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/advanced/context.ts"],"names":[],"mappings":""}

package/dist/advanced/curves.d.ts

@@ -0,0 +1,5 @@
+import type { AnyNode, Svg } from '@rasamjs/core';
+import type { Segment } from './geometry.js';
+/** Detached geometry is sampled once: target edits never change an active session. */
+export declare function curveSegments(drawing: Svg, nodes: readonly AnyNode[], resolution: number): Segment[];
+//# sourceMappingURL=curves.d.ts.map

package/dist/advanced/curves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"curves.d.ts","sourceRoot":"","sources":["../../src/advanced/curves.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAe,MAAM,eAAe,CAAC;AAG/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAgB7C,sFAAsF;AACtF,wBAAgB,aAAa,CAC3B,OAAO,EAAE,GAAG,EACZ,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,UAAU,EAAE,MAAM,GACjB,OAAO,EAAE,CAuCX"}