@mocanvas/sync 1.0.0 → 4.0.0

package/README.md

@@ -1,9 +1,11 @@
 # @mocanvas/sync
 
 Multiplayer for a mocanvas store: document changes travel as record diffs,
-cursors and selections travel as presence records.
+cursors and selections travel as presence records. Conflicting edits are merged
+field by field by a small CRDT (`src/crdt.ts`), so two people editing different
+properties of one shape both keep their work and every replica converges.
 
-Part of [mocanvas](https://github.com/SYMBIO/mocanvas).
+Part of mocanvas; the canvas itself is `@mocanvas/mocanvas`.
 
 ## Install
 
@@ -53,51 +55,159 @@ Every message is one JSON object on the wire.
 | message    | fields                       | meaning                                              |
 | ---------- | ---------------------------- | ---------------------------------------------------- |
 | `hello`    | `clientId`, `version`        | I joined. Established peers answer with a `snapshot`. |
-| `snapshot` | `records`                    | Every document-scope record as the sender sees them.  |
-| `diff`     | `clientId`, `seq`, `diff`    | One squashed `RecordsDiff` of document records.       |
+| `snapshot` | `records`, `state`           | Every document record, plus the sender's CRDT stamps. |
+| `diff`     | `clientId`, `seq`, `diff`    | One squashed store diff, stamped field by field.      |
 | `presence` | `clientId`, `record`         | The sender's `instance_presence` record.              |
 | `bye`      | `clientId`                   | I am leaving; drop my presence.                       |
 
+`encodeMessage` stamps `version: PROTOCOL_VERSION` (currently 3) onto every
+message. `decodeMessage` returns `null` for anything malformed and a synthetic
+`{ type: "unsupported", version }` for a message from another protocol version,
+so a peer on a different build is reported through `onError` rather than
+half-parsed. Nothing on the wire can crash this client.
+
 - Outgoing diffs come from `store.listen(cb, { source: "user", scope: "document" })`,
   so nothing applied from a peer is ever echoed back and nothing in `session`
-  or `presence` scope is persisted into the document stream.
-- Incoming diffs are applied inside
-  `store.mergeRemoteChanges(() => store.applyDiff(diff))`, which marks them
-  `source: "remote"`: they do not enter the local undo stack and do not
-  re-broadcast.
-- A newcomer applies the first `snapshot` it is offered and ignores the rest.
-  Answering a `hello` makes a peer "established", so a snapshot meant for
-  someone else can never overwrite its work.
+  or `presence` scope is persisted into the document stream. Each one is
+  stamped by the CRDT before it goes out, whether or not the transport is up.
+- Incoming messages are merged field by field and only the fields that won are
+  applied, inside `store.mergeRemoteChanges(() => store.applyDiff(winning))`,
+  which marks them `source: "remote"`: they do not enter the local undo stack
+  and do not re-broadcast.
+- A replica with **no stamps at all** — a tab that has just loaded and has not
+  been edited — takes the first `snapshot` it is offered whole, records and
+  stamps together, and sends nothing before that. One stamp is enough to make
+  it merge instead: a replica with work of its own never has that work replaced
+  by a peer's body.
+- Local changes are stamped by the store listener, which is wired up when the
+  client is built and stays wired until `dispose()`. An edit made before
+  `connect()`, or after `disconnect()`, is therefore stamped **when it happens**
+  and goes out on the next connection. It is not silently unstamped work that
+  would lose to every stamped write in the room.
+- On a reconnect the client re-sends `hello` and its own snapshot, so work done
+  while the transport was down flows both ways.
+- If the store rewrites a merged record — a validator clamping a value, a side
+  effect touching another record — that rewrite is stamped as a local write and
+  broadcast. Otherwise it would exist on one replica only, since changes made
+  inside `mergeRemoteChanges` are reported as `remote` and never leave.
 - Presence records are derived from the editor's camera,
   `inputs.currentPagePoint` and selection, throttled to at most 30 Hz, and
   re-sent on a heartbeat. A collaborator is dropped on `bye` or after 10s of
   silence.
-- `decodeMessage` returns `null` for anything malformed, so a peer running a
-  different version cannot crash this one. `PROTOCOL_VERSION` is checked on
-  `hello`.
-
-## Conflict policy: last writer wins, per record
 
-There is no operational transform and no CRDT here. Diffs are applied in
-arrival order and the last write to a record id is the one that survives.
+## Conflict policy: a CRDT over the record fields
+
+Every leaf field of every record is its own last-writer-wins register. A local
+change carries one Lamport stamp — `{ lamport, client }` — and a field is
+overwritten only when the incoming stamp is greater than the one already held
+for that exact path. Equal `lamport` values are broken by comparing the client
+ids, so the comparison is a total order and both sides of a race reach the same
+answer from the same pair. Paths are dotted: `x`, `props.w`, `meta.notes.title`.
+
+A stamp covers a **subtree**, not just a leaf. Writing `meta` — setting it, or
+deleting the key — dominates `meta.a`: a claim loses to any stamp at or above
+its own path, and a write that drops a subtree keeps the descendants stamped
+later than itself. Comparing `meta` and `meta.a` as unrelated registers is how
+"delete the key" racing "edit the key's child" ends up different on each side.
+
+The result is that merging is **idempotent** — the same message twice changes
+nothing the second time — and **commutative**: two messages in either order
+reach the same state, because the outcome per path is the maximum stamp and a
+maximum does not care about arrival order. Replicas converge no matter how the
+transport reorders or duplicates messages. `src/fuzz.test.ts` is the evidence:
+a seeded generator builds random schedules of creates, nested edits, deletes,
+re-creates, reordered, duplicated and dropped messages, disconnects, reconnects
+and snapshot joins over an in-memory network, then quiesces and demands that
+every replica's document be byte-identical under a key-sorted serialisation.
 
 What that means in practice:
 
-- Two people dragging **different** shapes is always fine.
-- Two people dragging the **same** shape converge on whoever sent last; the
-  other person's drag is discarded, not merged.
-- Concurrent edits to **different fields of the same record** (one person
-  moves a shape while another recolours it) lose one of the two changes: a
-  record is replaced wholesale, not merged field by field.
-- A delete racing an update can resurrect the record: the update carries the
-  full record and is applied after the removal.
-- Peers that were offline while others edited rejoin with `hello` and take a
-  peer's snapshot, so anything they changed offline is overwritten.
-
-This is enough for cursors-and-shapes collaboration on a small trusted room.
-Anything needing real convergence guarantees wants a server-authoritative log
-or a CRDT under `applyDiff`; the transport and message types here do not have
-to change for that.
+- Two people dragging **different** shapes: fine, as before.
+- Two people editing **different fields of the same shape** — one moves it while
+  the other recolours it — now keep both edits. This is the case the old
+  per-record policy lost.
+- Two people editing the **same** field pick the same winner on every replica.
+  The loser's value is gone; there is no merging inside a single value.
+- **Creating** the same record id on two peers merges field by field, exactly
+  like an edit.
+- **Deleting** leaves a stamped tombstone rather than a hole, so an older edit
+  arriving late cannot resurrect the record. A delete beats a concurrent edit
+  only when its stamp is the greater one; an edit with a greater stamp keeps
+  the record alive.
+- **A record kept alive by an edit that outranks a delete comes back whole.**
+  The tombstone takes the provenance of every field it outranks, so the fields
+  written *before* the delete have nothing left to settle them and each replica
+  would otherwise keep whatever leftover it happened to hold. The replica that
+  keeps the record re-claims its whole body under a fresh stamp and sends it,
+  and that body — not a leftover — is what every replica ends up with.
+- Peers that were offline while others edited keep their work: on reconnect the
+  two sides exchange state and merge both ways. That holds for a client that
+  was `disconnect()`ed as much as for one whose socket dropped.
+
+### What is one register, and what that costs
+
+- **Arrays are opaque.** `props.points`, `selectedShapeIds` and every other
+  array is one register holding the whole array, not one register per element.
+  Two concurrent edits to one array pick a winner instead of merging. Splitting
+  an array into per-element registers needs element identity, which the record
+  data does not carry, and would produce interleaved nonsense — a half-merged
+  draw stroke is worse than one of the two strokes.
+- **The fractional `index` is one register too.** A concurrent reorder of the
+  same shape therefore lands on one of the two orders deterministically rather
+  than merging them. Two people reordering *different* shapes is fine: those
+  are different records.
+- **An object is recursed into**, so `meta.a` and `meta.b` are separate
+  registers, but an empty object is itself a leaf. Two replicas that each add a
+  different key to one object agree on the keys and their values; the order the
+  keys sit in the JSON may differ, and object key order is not part of the value.
+  Tests compare documents key-sorted for that reason, and only for that reason.
+- **A record body is one register of its own.** A put carries `base`: the stamp
+  its whole record was the sender's current view as of. A receiver that has no
+  stamp at all for some path — because it never saw the record created, only an
+  edit to one of its fields — takes that path from the body carrying the
+  greatest `base`, so two such receivers cannot settle on different bodies.
+
+### Tombstones are bounded
+
+A tombstone for a record that is gone is kept for one hour, and at most 5000 of
+them are kept at once (`tombstoneMaxAgeMs`, `tombstoneLimit` on
+`createSyncClient`); the oldest go first. Once a tombstone has been collected,
+an edit older than it has nothing left to lose against and **resurrects the
+record**. The bound is therefore a statement about how long a peer may be
+partitioned: within it, deletes are safe against arbitrarily late messages;
+past it, a straggler's edit can bring a deleted record back. Live records keep
+their field stamps for as long as the document holds them.
+
+### What it is not, and what it does not promise
+
+There is still no operational transform, no server-authoritative log, and no
+character-level text merge: concurrent edits to one text field pick a winner
+rather than interleaving. The store remains the source of truth — the CRDT owns
+stamps, never values — so nothing here needs Yjs or Automerge, and adding one
+would mean replacing the store rather than sitting under it.
+
+Four limits are real, and none of them is a bug to be fixed later:
+
+- **Two writes to one field cannot both survive.** The register holds one value
+  and the greater stamp takes it. Same for the interior of an array or a string:
+  there is no identity inside a value to merge along.
+- **A message that is never delivered is not merged.** A put carries stamps for
+  the paths it claims, not for the whole record, so a replica that missed a
+  record's creation and then sees an edit to one field adopts the rest of that
+  body without provenance. It is repaired by the next snapshot exchange, which
+  every `hello`, `connect` and reconnect triggers, from any peer that does hold
+  those stamps. Between the loss and that exchange, it can be stale.
+- **A replica that has never connected starts its clock at zero.** Its offline
+  edits are stamped when they happen, so they are real writes and its own new
+  records always survive; but an edit to a field the room has already written
+  several times can sort below what is there. A replica that has been in the
+  room and comes back has observed the room's clock and does not have this
+  problem, which is the case the offline requirement is about.
+- **A side effect that is not a function of its inputs cannot converge.** Store
+  rewrites are stamped and broadcast (see the protocol notes above), so one that
+  rewrites the same way everywhere settles in a single round: peers apply a
+  value they already hold and produce nothing further. One that rewrites
+  differently on each replica has no fixed point, here or in any other design.
 
 ## Transports
 
@@ -139,4 +249,23 @@ pnpm --filter @mocanvas/sync test
 
 ## License
 
-MIT
+**Source-available, not open source.** Free to use for:
+
+- personal, non-commercial projects;
+- non-profit organisations;
+- development, evaluation, testing and staging — including inside a for-profit
+  company, so you can try it and build against it before committing;
+- teaching and academic research.
+
+**Shipping it in a commercial product, service or website needs a written
+agreement with us.** That includes anything sold, anything that earns revenue
+directly or through advertising, and internal tools running a for-profit
+business.
+
+To arrange one, or if you are unsure which side of the line you are on, write to
+**mocanvas@symbio.agency** — we would rather answer the question than have you
+guess.
+
+The full terms are in `LICENSE`, shipped in this package. Versions released
+earlier under MIT stay available under MIT, on the terms they were released
+with.

package/UI.md

@@ -0,0 +1,256 @@
+# The default UI
+
+`<Mocanvas />` ships a small, opinionated interface: a toolbar, a zoom bar, a
+style panel, an optional statistics chip, and the chrome the editor draws on the
+canvas itself. All of it is optional and all of it is themeable from CSS.
+
+Source lives in `packages/mocanvas/src/ui/`:
+
+| File | What it holds |
+| --- | --- |
+| `DefaultUi.tsx` | The toolbar, the zoom bar, the stats chip, and the `DefaultUi` wrapper |
+| `StylePanel.tsx` | The style panel and `getStylePanelSections`, the rule for which rows appear |
+| `icons.tsx` | The whole icon set, plus the geo icons generated from canvas geometry |
+| `overlays.tsx` | The shared tooltip and popover layers, and `placeNear` |
+| `ui.css` | Every design token and every rule |
+| `useKeyboardShortcuts.ts` | The default key bindings |
+
+## Design tokens
+
+Tokens are declared on `.mocanvas` (the editor container), on `.mocanvas-panel`,
+and on `.mocanvas-layer` (the floating tooltip and popover, which sit outside the
+panels in the DOM). Override any of them on `.mocanvas`, on a wrapper, or on a
+single panel.
+
+### Surfaces and colour
+
+| Token | Light | Dark | Used for |
+| --- | --- | --- | --- |
+| `--mocanvas-ui-panel` | `#ffffff` | `#1b1d22` | Panel, popover and picker background |
+| `--mocanvas-ui-panel-border` | `#d6d9e0` | `#3c404a` | Panel hairline, dividers, group separators |
+| `--mocanvas-ui-control` | `rgba(16,24,40,.06)` | `rgba(255,255,255,.08)` | Recessed background of a segmented button |
+| `--mocanvas-ui-text` | `#16181d` | `#eceef3` | Icon and label colour |
+| `--mocanvas-ui-muted` | `#5c6070` | `#a4a9b4` | Row labels, stats text |
+| `--mocanvas-ui-accent` | `#2563eb` | `#6ea8fe` | Selected control, focus ring |
+| `--mocanvas-ui-accent-fg` | `#ffffff` | `#0e1116` | Icon on an accent fill |
+| `--mocanvas-ui-accent-soft` | 12% accent | 18% accent | Hover on a segmented button, open disclosure |
+| `--mocanvas-ui-hover` | 6% ink | 9% white | Hover on a bare button |
+| `--mocanvas-ui-active` | 13% ink | 18% white | Pointer-down on a bare button |
+| `--mocanvas-ui-shadow` | — | — | Panel elevation |
+| `--mocanvas-ui-tip-bg` / `-fg` / `-muted` | — | — | Tooltip pill, its label, its shortcut |
+
+Every text-on-background pair is at or above 4.5:1 in both palettes. Measured on
+the shipped values, the tightest are `accent` on a segmented control (4.58 light,
+5.54 dark) and `muted` on the panel (6.25 light, 7.16 dark). Disabled controls
+render at 35% opacity, which WCAG exempts.
+
+### Metrics
+
+| Token | Value | Meaning |
+| --- | --- | --- |
+| `--mocanvas-ui-btn` | `40px` | Every hit target — buttons, swatches, popover cells |
+| `--mocanvas-ui-icon` | `20px` | Icon size inside a button |
+| `--mocanvas-ui-gap` | `2px` | Gap between adjacent controls |
+| `--mocanvas-ui-pad` | `4px` | Padding of a bar |
+| `--mocanvas-ui-pad-lg` | `10px` | Padding of the style panel, gap between its groups |
+| `--mocanvas-ui-inset` | `12px` | Distance from a panel to the viewport edge |
+| `--mocanvas-ui-radius` / `-sm` | `12px` / `8px` | Panel radius / control radius |
+| `--mocanvas-ui-dock` | `300px` | Width the bottom-left and bottom-right docks reserve beside the centred toolbar |
+| `--mocanvas-ui-bottom-dock` | `62px` (`124px` under 1290px) | Height the bottom edge occupies; the style panel stops above it |
+| `--mocanvas-ui-font` / `-mono` | system stacks | Panel type / stats chip |
+
+`--mocanvas-ui-dock` is the mechanism that keeps the three bottom panels apart:
+the toolbar is centred on the viewport but may not grow into the reservation, so
+it wraps rather than collide. Shrink it if your zoom bar is narrower than the
+default one.
+
+### Canvas chrome
+
+These are read by the editor's indicator layer (`Canvas.tsx`), not by the panels,
+so they apply even with `hideUi`. They are deliberately **not** redefined for the
+dark UI: the canvas keeps its own background, which does not follow
+`prefers-color-scheme`.
+
+| Token | Value | Used for |
+| --- | --- | --- |
+| `--mocanvas-selection` | `#2f6fe4` | Selection and hover outlines, handle strokes, brush border |
+| `--mocanvas-selection-fg` | `#ffffff` | Fill behind a solid handle |
+| `--mocanvas-brush-fill` | 12% selection | Brush rectangle interior |
+| `--mocanvas-snap` | `#cf3fe0` | Snap lines and their end markers |
+
+The two stroke colours clear 3:1 against a light canvas (`#f9fafb`: 4.45 and
+3.69) and against a dark one (`#1b1d22`: 3.63 and 4.37). If you render a dark
+canvas, swap `--mocanvas-selection-fg` for a dark value so handles stay filled
+with the canvas colour rather than white.
+
+Handles are drawn at 9px (corners), 6px (shape handles) and 5.5px (rotate) in
+screen space, with a 1.5px stroke. Their hit radius is a separate editor
+constant, `HANDLE_HIT_RADIUS` in `packages/editor/src/editor/selectionHandles.ts`.
+
+## Icon grid rules
+
+Icons are original artwork on a 24×24 viewBox, painted with `currentColor`.
+
+- **Grid.** 24×24. Ink, stroke included, stays inside it.
+- **Weight.** Stroke 1.75, round caps and joins. Only texture marks deviate and
+  say so at the call site: the fill hatching (1.25), the dotted rule (2.6 with a
+  zero-length dash, so the caps draw the dots), the mono rails (1.4).
+- **Centring.** Ink is optically centred on (12, 12), within half a grid unit.
+  The only exceptions are semantic: `valign-top` and `valign-bottom` sit high and
+  low on purpose.
+- **Extent.** The longest ink dimension lands between 16 and 18.25 units — about
+  17.75 for a full-bleed form — so no icon reads heavier than its neighbour. The
+  `size-*` ramp is exempt: its whole job is to differ in size.
+- **Distinctness.** No two icons may draw the same artwork; `icons.test.tsx`
+  enforces this. It is why the handwriting font is a script `a` rather than a
+  fourth capital A, and why `oval` gets a wider box than `ellipse`.
+- **Geo icons** are generated from `getGeoGeometry`, the same code the canvas
+  draws with, so a toolbar button always matches the shape it creates. Each kind
+  is fitted into the box `getGeoIconBox(kind)` returns: square at `GEO_BOX` (16)
+  by default, and flatter or narrower for kinds whose name implies a proportion
+  (`rectangle`, `oval`, the four arrows). The longest side is always `GEO_BOX`.
+
+Render one with `<Icon name="select" size={20} />`. `size` sets the SVG's
+attributes; buttons additionally take their icon size from `--mocanvas-ui-icon`,
+so inline marks like the "mixed" badge keep the size they ask for.
+
+## Overriding the UI
+
+### Turn it off
+
+```tsx
+<Mocanvas hideUi />
+```
+
+This drops the toolbar, zoom bar, style panel and stats chip. `ui.css` still
+loads, so the canvas chrome tokens above keep working. Default keyboard
+shortcuts are wired by `<Mocanvas />` itself and are unaffected; call
+`useKeyboardShortcuts(editor)` yourself if you build on `<Canvas />` directly.
+
+### Replace the canvas chrome
+
+```tsx
+<Mocanvas components={{ Indicators: MyIndicators, Brush: MyBrush, Background: MyGrid }} />
+```
+
+`components` is forwarded to `<Canvas />`. `Indicators` draws selection and hover
+outlines and handles, `Brush` the marquee, `Background` a layer behind the canvas.
+Each receives `{ editor }` and renders into the SVG overlay (`Background` into a
+plain DOM layer). Omit one to keep the default.
+
+### Rebuild the panels
+
+Compose your own from the exported parts:
+
+```tsx
+import { Mocanvas, Toolbar, ZoomBar, StylePanel, UiTooltip, Icon } from "mocanvas"
+
+<Mocanvas hideUi>
+  <Toolbar />
+  <MyOwnInspector />
+  <UiTooltip />
+</Mocanvas>
+```
+
+`Toolbar`, `ZoomBar`, `StylePanel`, `DebugStats`, `Popover`, `UiTooltip`, `Icon`
+and `TOOLBAR_GROUPS` are all exported. Children of `<Mocanvas>` render above the
+canvas inside the editor container, so the tokens apply to them too.
+
+### Restyle it
+
+```css
+.mocanvas {
+  --mocanvas-ui-accent: #12b886;
+  --mocanvas-ui-radius: 6px;
+  --mocanvas-ui-btn: 44px;
+  --mocanvas-selection: #12b886;
+}
+```
+
+## The panels
+
+### Toolbar — bottom centre
+
+Tools in four groups separated by dividers: select and hand; draw and eraser; the
+five common geo kinds plus a disclosure for the other fifteen; text, note, and
+whichever of arrow, line and frame the app registered. Entries whose tool is not
+registered disappear, so a cut-down `tools` prop yields a cut-down bar. The
+active tool is `aria-pressed`; a geo button is pressed only when its own kind is
+active. The disclosure opens a 5-column popover of the remaining kinds and is
+itself marked pressed when one of them is active. The bar is centred on the
+viewport, wraps to more rows rather than growing into the docks, and moves to a
+row of its own below 1290px.
+
+### Zoom bar — bottom left
+
+Zoom out, the current percentage (a button that resets to 100%), zoom in, zoom to
+fit, then a divider and undo/redo. Undo and redo are `disabled` when there is
+nothing to undo or redo, at 35% opacity and without a tooltip.
+
+### Style panel — top right
+
+Appears when the selection carries at least one style, or when a drawing tool is
+active with nothing selected. Rows are grouped, and separated by a hairline:
+
+1. **Shape** — the geo kind, as one button showing the current shape that opens a
+   20-cell popover.
+2. **Colour** — the stroke colour, and the label colour when the selection can
+   carry one; twelve swatches each, six to a row.
+3. **Stroke and fill** — Fill, Dash and Size, four choices each.
+4. **Text** — Font, then horizontal and vertical alignment sharing one row.
+5. **Opacity** — a slider; only with a selection, since it edits shapes rather
+   than a style.
+
+Which rows appear is decided by `getStylePanelSections(editor)`, which reads
+`editor.getSharedStyles()` for a selection and
+`editor.getStylePropsForType(toolId)` otherwise. A selection of two lines
+therefore shows Colour, Dash and Size and nothing else. A row whose selected
+shapes disagree shows a dashed "mixed" badge beside its label. The panel scrolls
+when it is taller than the space above the bottom dock, with a fade and a shadow
+at whichever edge has more content behind it. Below 560px it spans the width and
+is capped at 42% of the height.
+
+### Statistics chip — bottom right
+
+Shape counts, drawn versus culled, and milliseconds per frame. Toggled with
+`⌥D`, or with the `showStats` prop. It moves above the zoom bar below 560px.
+
+### Tooltip and popover
+
+Both are single, `position: fixed`, viewport-clamped layers (`overlays.tsx`).
+A tooltip labels any element with `data-tooltip`, adding `data-shortcut` in a
+muted weight; it appears after a 500ms rest, immediately on keyboard focus, sits
+above its control so it never covers it, and flips below when there is no room.
+`placeNear` does the arithmetic and is unit-tested. Popovers dismiss on outside
+pointer-down and on Escape, which also returns focus to the button.
+
+## States
+
+| State | Bare button | Segmented button | Swatch |
+| --- | --- | --- | --- |
+| Rest | transparent | `--mocanvas-ui-control` | transparent |
+| Hover | `--mocanvas-ui-hover` | `--mocanvas-ui-accent-soft` | `--mocanvas-ui-hover` |
+| Pointer down | `--mocanvas-ui-active`, scaled 0.94 | as hover, scaled 0.94 | scaled 0.92 |
+| Selected | accent fill, accent-fg icon | accent fill, accent-fg icon | double ring in accent |
+| Selected + hover | accent fill plus an inset ring | same | same |
+| Focus (keyboard) | 2px accent outline, 2px offset | same | same |
+| Disabled | 35% opacity, no tooltip, default cursor | — | — |
+
+The focus ring is offset by 2px so a ring of panel colour separates it from an
+accent-filled button; without that gap, focus would be invisible on the active
+tool. `prefers-reduced-motion` removes every transition.
+
+## Pointer targets
+
+Selection handles use a 24x24 px pointer target (`HANDLE_HIT_RADIUS = 12` in
+`packages/editor/src/editor/selectionHandles.ts`), which is the WCAG 2.2
+minimum. Two rules keep that from swallowing small shapes:
+
+- Edge handles (top, right, bottom, left) only appear once that edge is at
+  least `4 * HANDLE_HIT_RADIUS` long on screen; below that the two corners
+  already cover the whole edge.
+- On a selection smaller than six handles across, `getHandleHitRadius` scales
+  the target down (never below 4 px) so the shape's interior stays draggable.
+
+Both measure the *screen-space* edge lengths of the transformed corners, so a
+rotated selection behaves the same as an upright one.