@xeplr/ui-canvas 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xeplr
+
+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

@@ -0,0 +1,198 @@
+# @xeplr/ui-canvas
+
+**One free-placement canvas for every builder.** Drag, resize, alignment guides, snapping, marquee select and edges — in a single React package, so a dashboard designer, a workflow editor, a join diagram and a form builder all feel like the same product.
+
+(The package name on npm is `@xeplr/ui-canvas` — the GitHub repo and folder are named `xeplr-ui-canvas`.)
+
+## Why
+
+Every builder ends up writing its own canvas: mousedown, window listeners, apply the delta, clean up. Then one of them gets snapping, another gets a marquee, a third draws bezier edges, and none of them agree on what a drag feels like.
+
+This package is the superset. It has every capability once, and each builder switches on the ones it needs:
+
+| Builder | drag | resize | guides & snap | marquee & groups | edges |
+|---|:-:|:-:|:-:|:-:|:-:|
+| Dashboard / page designer | ✓ | ✓ | ✓ | ✓ | |
+| Workflow / flow editor | ✓ | | ✓ | | ✓ |
+| Join diagram (column ports) | ✓ | | ✓ | | ✓ |
+| Form / UI builder | ✓ | ✓ | ✓ | ✓ | |
+
+## Install
+
+```sh
+npm i @xeplr/ui-canvas
+```
+
+Peer dependency: `react ^18 || ^19`. No other runtime dependencies.
+
+## Quick start — boxes you can move and resize
+
+```jsx
+import { useState } from 'react'
+import { XeplrCanvas } from '@xeplr/ui-canvas'
+
+export function Board() {
+  const [items, setItems] = useState([
+    { id: 'sales', x: 40, y: 40, w: 320, h: 200 },
+    { id: 'orders', x: 400, y: 40, w: 320, h: 200 }
+  ])
+
+  return (
+    <XeplrCanvas
+      style={{ height: 600 }}
+      items={items}
+      features={{ resize: true, marquee: true }}
+      onItemChange={(id, patch) =>
+        setItems((all) => all.map((it) => (it.id === id ? { ...it, ...patch } : it)))
+      }
+      renderItem={(item, { selected }) => <div className="card">{item.id}</div>}
+    />
+  )
+}
+```
+
+## Quick start — nodes joined by edges
+
+```jsx
+<XeplrCanvas
+  items={steps}                                  // [{ id, x, y, w, h }]
+  edges={[
+    { id: 'a-b', from: 'fetch', to: 'transform' },
+    { id: 'b-c', from: 'transform', to: 'load', variant: 'dashed' },
+    { id: 'c-end', from: 'load', toOffset: { x: 130, y: 0 }, done: true }
+  ]}
+  onItemChange={(id, { x, y }) => moveStep(id, x, y)}
+  onItemClick={(id) => openStep(id)}             // a press that never became a drag
+  renderItem={(step, { selected }) => <StepCard step={step} selected={selected} />}
+  renderEdgeLabel={(edge, { to }) =>
+    edge.done ? <span className="pill" style={{ position: 'absolute', left: to.x, top: to.y }}>Done</span> : null
+  }
+/>
+```
+
+Edges follow their node **while** it is being dragged, not only after the drop.
+
+## What you get
+
+- **Drag without re-renders.** A drag writes a CSS transform straight onto the moving element, one frame at a time. React hears about the new position exactly once, on drop — so a board of 300 items stays smooth.
+- **Alignment guides.** An edge or centre that comes within 6px of another item's edge or centre snaps to it, and a guide line shows why it jumped. When nothing is close, it falls back to a 10px grid. Hold **Alt** to place freely.
+- **Resize from eight handles**, with snapping on the edge being dragged and a per-item minimum size (`minSizeFor`).
+- **Marquee select** that takes everything it *touches*, not only what it encloses — so it also reaches items hidden under others. Ctrl/Cmd/Shift adds to the selection.
+- **Groups.** Items sharing a `groupId` select and move as one.
+- **Edges.** Bezier curves with arrowheads, dashed variant, labels, stubs to non-item targets (`toOffset`), and port anchors inside an item (`getAnchor`).
+- **Pixel or fractional units.** `units="fraction"` stores `x`/`w` as fractions of the width and `y`/`h` as fractions of the visible height, so a layout made on a large screen still reads on a laptop.
+- **Fails loudly.** A missing `renderItem`, or an item with no id or a duplicate id, throws a clear error instead of rendering a board that half works.
+
+## `<XeplrCanvas>` props
+
+| prop | type | default | notes |
+|---|---|---|---|
+| `items` | `Array<{ id, x, y, w, h, z?, groupId? }>` | required | `z` sets paint order |
+| `renderItem` | `(item, { selected }) => ReactNode` | required | the item's content; the canvas positions it |
+| `units` | `'px' \| 'fraction'` | `'px'` | see above |
+| `features` | `{ drag, resize, snap, grid, marquee }` | `{ drag: true, resize: false, snap: true, grid: 10, marquee: false }` | merged over the defaults |
+| `onItemChange` | `(id, patch) => void` | — | once per item, on drop, in the item's own units |
+| `onItemClick` | `(id, event) => void` | — | a press that moved less than 4px |
+| `onRaise` | `(id) => void` | — | when an item is grabbed — e.g. `bringToFront` |
+| `selection` | `Array<id> \| Set<id>` | — | controlled selection; omit to let the canvas own it |
+| `onSelectionChange` | `(Set<id>) => void` | — | |
+| `minSizeFor` | `(item) => { minWidth, minHeight }` | 48 × 28 | per-item resize floor |
+| `edges` | `Array<Edge>` | `[]` | see below |
+| `getAnchor` | `(item, port, 'from' \| 'to', rect) => { x, y }` | right / left middle | for edges that attach to ports |
+| `renderEdgeLabel` | `(edge, { from, to, mid }) => ReactNode` | — | absolutely position it yourself |
+| `edgeMinOffset` | number | `60` | minimum sideways reach of a curve |
+| `padding` | `number \| { x, y }` | `80` | room beyond the furthest item (px units) |
+| `minWidth`, `minHeight` | number | `0` | smallest the canvas gets |
+| `underlay`, `overlay` | ReactNode | — | extra layers under the edges / over everything |
+| `className`, `style` | | — | on the scrolling wrapper |
+
+### Edge
+
+| field | notes |
+|---|---|
+| `id` | required |
+| `from` | item id |
+| `to` *or* `toOffset` | item id, or `{ x, y }` relative to where the edge leaves |
+| `fromPort`, `toPort` | passed to `getAnchor` |
+| `fromSide`, `toSide` | `'left' \| 'right' \| 'top' \| 'bottom'` when not using `getAnchor` |
+| `variant` | `'dashed'` |
+| `className` | extra class on the path |
+| `arrow` | `false` to hide the arrowhead |
+
+Anything else you put on an edge comes back to you in `renderEdgeLabel`.
+
+## Three ways to use it
+
+Like every `@xeplr/ui-*` package, it is split into model, controller and design, so you take as much as you want:
+
+1. **Ready-made** — `<XeplrCanvas>` as above.
+2. **Your own design** — the hooks, with your own markup. Use this when your builder already has a selection model of its own.
+
+   ```jsx
+   import { useCanvasDrag, useMarquee, useCanvasSize, DragGuides, MarqueeBox, ResizeHandles } from '@xeplr/ui-canvas'
+
+   const drag = useCanvasDrag({ items, units: 'fraction', canvas, rootRef, onUpdate })
+   // on an item:   <div data-canvas-item-id={item.id} onMouseDown={(e) => drag.startDrag(e, [item.id])}>
+   // on a handle:  <ResizeHandles onStart={(e, handle) => drag.startResize(e, item.id, handle)} />
+   // in the canvas: <DragGuides store={drag.guideStore} />
+   ```
+
+3. **Geometry only** — no React at all, runs in Node:
+
+   ```js
+   import { moveRect, resizeRect, hits, toFraction } from '@xeplr/ui-canvas/geometry'
+   import { bezierPath, anchorOf } from '@xeplr/ui-canvas/edges'
+   ```
+
+## Styling
+
+Everything is namespaced `.xeplr-canvas-*`, and colours come from the xeplr theme variables with fallbacks: `--xeplr-accent` for guides, handles and the marquee, and `--xeplr-border-strong` for edges. Set those variables to restyle, or override the classes:
+
+| class | what |
+|---|---|
+| `.xeplr-canvas` / `.xeplr-canvas-inner` | scrolling wrapper / sized canvas |
+| `.xeplr-canvas-item` (`.is-selected`) | the positioned box around each item |
+| `.xeplr-canvas-edge` (`--dashed`), `.xeplr-canvas-edge-arrow` | edges |
+| `.xeplr-canvas-guide-x` / `-y` | alignment guides |
+| `.xeplr-canvas-handle-{nw,n,ne,w,e,sw,s,se}` | resize handles |
+| `.xeplr-canvas-marquee` | the selection band |
+
+## Exports
+
+- **Component:** `XeplrCanvas`
+- **Hooks:** `useCanvasController`, `useCanvasDrag`, `useMarquee`, `useCanvasSize`
+- **Designs:** `CanvasSample`, `DragGuides`, `MarqueeBox`, `ResizeHandles`, `EdgeLayer`
+- **Geometry:** `moveRect`, `resizeRect`, `rectOf`, `pixelRect`, `canvasBounds`, `bringToFront`, `inStackOrder`, `toFraction`, `toPixels`, `hits`, `overlaps`, `RESIZE_HANDLES`, `GRID`, `SNAP_TOLERANCE`, `MIN_WIDTH`, `MIN_HEIGHT`, `DEFAULT_SIZE`, `DEFAULT_FRACTION`
+- **Edges:** `bezierPath`, `anchorOf`, `midpoint`, `edgeEnds`
+- **Other:** `createFrameStore`, `validateCanvasProps`, `DEFAULT_FEATURES`, `ITEM_ID_ATTR`, `SWEEPING_CLASS`
+
+## Files
+
+```
+src/
+  index.js                 ─ public exports
+  pages.jsx                ─ XeplrCanvas (controller + design)
+  geometry.js              ─ move, resize, snap, stack, fractions, hit-testing
+  edges.js                 ─ anchors and bezier paths
+  frameStore.js            ─ per-frame store the overlays subscribe to
+  validateCanvas.js        ─ loud failure on a mis-wired canvas
+  useCanvasController.js   ─ features, selection, groups
+  useCanvasDrag.js         ─ drag and resize pointer lifecycle
+  useMarquee.js            ─ marquee select
+  useCanvasSize.js         ─ measured canvas size
+  designs/
+    CanvasSample.jsx · EdgeLayer.jsx · DragGuides.jsx · MarqueeBox.jsx · ResizeHandles.jsx
+    canvas.css
+```
+
+## Tests
+
+```sh
+npm test
+```
+
+Geometry, snapping, resize limits, fractions, marquee hits and edge paths are covered by plain Node scripts, with no test framework.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@xeplr/ui-canvas",
+  "version": "1.0.1",
+  "description": "One free-placement canvas for every xeplr builder: drag, resize, alignment guides, snapping, marquee select and edges — React controller hooks, pure geometry and a ready-made <XeplrCanvas>",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./geometry": "./src/geometry.js",
+    "./edges": "./src/edges.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "for f in test/*.test.js; do node \"$f\" || exit 1; done"
+  },
+  "keywords": [
+    "canvas",
+    "drag",
+    "resize",
+    "snapping",
+    "alignment-guides",
+    "marquee",
+    "flow-editor",
+    "react",
+    "builder",
+    "xeplr"
+  ],
+  "author": "xeplr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeplr/xeplr-ui-canvas"
+  },
+  "homepage": "https://github.com/Xeplr/xeplr-ui-canvas#readme",
+  "bugs": {
+    "url": "https://github.com/Xeplr/xeplr-ui-canvas/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}

package/src/designs/CanvasSample.jsx

@@ -0,0 +1,71 @@
+import DragGuides from './DragGuides.jsx'
+import MarqueeBox from './MarqueeBox.jsx'
+import ResizeHandles from './ResizeHandles.jsx'
+import EdgeLayer from './EdgeLayer.jsx'
+import { ITEM_ID_ATTR } from '../useCanvasDrag.js'
+
+// The ready-made canvas design. Presentation only — everything arrives from
+// useCanvasController plus the caller's render props.
+//
+// Layers, bottom to top: underlay, edges, items, guides and marquee, overlay.
+// Edges sit UNDER items so a line never crosses the box it enters.
+export default function CanvasSample({
+  ctrl, renderItem, getAnchor, renderEdgeLabel, edgeMinOffset,
+  underlay, overlay, className, style
+}) {
+  const { features, selected, rectById } = ctrl
+  const soleSelection = selected.size === 1
+
+  return (
+    <div
+      ref={ctrl.measureRef}
+      className={'xeplr-canvas' + (className ? ' ' + className : '')}
+      style={style}
+    >
+      <div
+        ref={ctrl.rootRef}
+        className="xeplr-canvas-inner"
+        style={{ width: ctrl.size.width, height: ctrl.size.height }}
+        onMouseDown={ctrl.onCanvasMouseDown}
+      >
+        {underlay}
+
+        {ctrl.edges.length > 0 && (
+          <EdgeLayer
+            edges={ctrl.edges}
+            rectById={rectById}
+            itemById={ctrl.itemById}
+            store={ctrl.guideStore}
+            getAnchor={getAnchor}
+            renderEdgeLabel={renderEdgeLabel}
+            minOffset={edgeMinOffset}
+          />
+        )}
+
+        {ctrl.stacked.map((item) => {
+          const rect = rectById[item.id]
+          const isSelected = selected.has(item.id)
+          return (
+            <div
+              key={item.id}
+              {...{ [ITEM_ID_ATTR]: item.id }}
+              className={'xeplr-canvas-item' + (isSelected ? ' is-selected' : '')}
+              style={{ left: rect.x, top: rect.y, width: rect.w, height: rect.h, zIndex: (item.z || 0) + 1 }}
+              onMouseDown={(e) => ctrl.onItemMouseDown(e, item.id)}
+            >
+              {renderItem(item, { selected: isSelected })}
+              {features.resize && isSelected && soleSelection && (
+                <ResizeHandles onStart={(e, handle) => ctrl.onResizeStart(e, item.id, handle)} />
+              )}
+            </div>
+          )
+        })}
+
+        {features.snap && <DragGuides store={ctrl.guideStore} />}
+        {features.marquee && <MarqueeBox store={ctrl.marqueeStore} />}
+
+        {overlay}
+      </div>
+    </div>
+  )
+}

package/src/designs/DragGuides.jsx

@@ -0,0 +1,18 @@
+import { useSyncExternalStore } from 'react'
+
+// The alignment guides drawn while a drag is snapping.
+//
+// ITS OWN COMPONENT, subscribed to the drag store directly, because this is
+// the one thing on the canvas that has to change on every frame of a drag.
+// Held in a page's state instead, each frame re-rendered the page and every
+// item under it. Here, a frame re-renders exactly this.
+export default function DragGuides({ store }) {
+  const frame = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot)
+  return frame.guides.map((g, i) => (
+    <div
+      key={i}
+      className={`xeplr-canvas-guide xeplr-canvas-guide-${g.axis}`}
+      style={g.axis === 'x' ? { left: g.at } : { top: g.at }}
+    />
+  ))
+}

package/src/designs/EdgeLayer.jsx

@@ -0,0 +1,62 @@
+import { Fragment, useId, useMemo, useSyncExternalStore } from 'react'
+import { bezierPath, edgeEnds, midpoint } from '../edges.js'
+
+// The lines between items.
+//
+// Subscribed to the drag store, like the guides, so an edge FOLLOWS its item
+// while it is dragged — the item itself is moved by a transform React never
+// hears about until the drop, so an edge drawn only from React state would be
+// left behind pointing at where the item used to be.
+//
+// Edge shape: { id, from, to | toOffset, fromPort?, toPort?, fromSide?,
+// toSide?, variant?: 'dashed', className?, arrow?: false, ... } — anything
+// else on it is the caller's, handed back to renderEdgeLabel.
+export default function EdgeLayer({ edges, rectById, itemById, store, getAnchor, renderEdgeLabel, minOffset }) {
+  const frame = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot)
+  const markerId = 'xeplr-canvas-arrow-' + useId().replace(/:/g, '')
+
+  // Committed rects, overlaid with whatever is moving this frame.
+  const live = useMemo(() => {
+    if (!frame.patches) return rectById
+    const next = { ...rectById }
+    frame.patches.forEach((p) => {
+      if (next[p.id]) next[p.id] = { ...next[p.id], ...p }
+    })
+    return next
+  }, [rectById, frame.patches])
+
+  const drawn = edges
+    .map((edge) => {
+      const ends = edgeEnds(edge, live, itemById, getAnchor)
+      return ends ? { edge, ...ends } : null
+    })
+    .filter(Boolean)
+
+  return (
+    <>
+      <svg className="xeplr-canvas-edges" width="100%" height="100%">
+        <defs>
+          <marker id={markerId} markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto">
+            <path className="xeplr-canvas-edge-arrow" d="M0,0 L8,4 L0,8 z" />
+          </marker>
+        </defs>
+        {drawn.map(({ edge, from, to }) => (
+          <path
+            key={edge.id}
+            className={
+              'xeplr-canvas-edge' +
+              (edge.variant ? ' xeplr-canvas-edge--' + edge.variant : '') +
+              (edge.className ? ' ' + edge.className : '')
+            }
+            d={bezierPath(from, to, { minOffset, fromDir: edge.fromDir, toDir: edge.toDir })}
+            markerEnd={edge.arrow === false ? undefined : `url(#${markerId})`}
+          />
+        ))}
+      </svg>
+      {renderEdgeLabel && drawn.map(({ edge, from, to }) => {
+        const label = renderEdgeLabel(edge, { from, to, mid: midpoint(from, to) })
+        return label ? <Fragment key={edge.id}>{label}</Fragment> : null
+      })}
+    </>
+  )
+}

package/src/designs/MarqueeBox.jsx

@@ -0,0 +1,10 @@
+import { useSyncExternalStore } from 'react'
+
+// The band itself. Its own leaf on the same bargain as DragGuides: one frame
+// re-renders this and nothing else on the canvas.
+export default function MarqueeBox({ store }) {
+  const frame = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot)
+  if (!frame.rect) return null
+  const { x, y, w, h } = frame.rect
+  return <div className="xeplr-canvas-marquee" style={{ left: x, top: y, width: w, height: h }} />
+}

package/src/designs/ResizeHandles.jsx

@@ -0,0 +1,15 @@
+import { RESIZE_HANDLES } from '../geometry.js'
+
+// The eight grab points on a selected item. Rendered INSIDE the item's own
+// positioned element, so they move with it during a drag for free.
+//
+// `onStart(event, handleKey)` — hand it to useCanvasDrag's startResize.
+export default function ResizeHandles({ onStart }) {
+  return RESIZE_HANDLES.map((h) => (
+    <span
+      key={h.key}
+      className={`xeplr-canvas-handle xeplr-canvas-handle-${h.key}`}
+      onMouseDown={(e) => onStart(e, h.key)}
+    />
+  ))
+}

package/src/designs/canvas.css

@@ -0,0 +1,50 @@
+/* @xeplr/ui-canvas — the shared canvas.
+   Colours come from the xeplr theme variables, with fallbacks, so a builder
+   restyles by theme rather than by overriding these. */
+
+.xeplr-canvas { position: relative; overflow: auto; }
+.xeplr-canvas-inner { position: relative; min-width: 100%; min-height: 100%; }
+.xeplr-canvas-item { position: absolute; box-sizing: border-box; }
+
+/* ── Edges ────────────────────────────────────────────────────────────── */
+.xeplr-canvas-edges { position: absolute; top: 0; left: 0; pointer-events: none; overflow: visible; }
+.xeplr-canvas-edge { fill: none; stroke: var(--xeplr-border-strong, #cfcec4); stroke-width: 2; }
+.xeplr-canvas-edge--dashed { stroke-dasharray: 6 5; }
+.xeplr-canvas-edge-arrow { fill: var(--xeplr-border-strong, #cfcec4); }
+
+/* ── Alignment guides ─────────────────────────────────────────────────
+   Drawn only while a drag is snapping to them. Without these an item
+   jumping four pixels looks like a bug rather than an alignment. */
+.xeplr-canvas-guide { position: absolute; z-index: 9000; pointer-events: none; background: var(--xeplr-accent, #4f5fd6); }
+.xeplr-canvas-guide-x { top: 0; bottom: 0; width: 1px; }
+.xeplr-canvas-guide-y { left: 0; right: 0; height: 1px; }
+
+/* ── Resize handles ───────────────────────────────────────────────────── */
+.xeplr-canvas-handle {
+  position: absolute; width: 9px; height: 9px; z-index: 10;
+  background: var(--xeplr-surface, #fff);
+  border: 1px solid var(--xeplr-accent, #4f5fd6);
+  border-radius: 2px;
+}
+.xeplr-canvas-handle-nw { left: -5px; top: -5px; cursor: nwse-resize; }
+.xeplr-canvas-handle-n { left: calc(50% - 4px); top: -5px; cursor: ns-resize; }
+.xeplr-canvas-handle-ne { right: -5px; top: -5px; cursor: nesw-resize; }
+.xeplr-canvas-handle-w { left: -5px; top: calc(50% - 4px); cursor: ew-resize; }
+.xeplr-canvas-handle-e { right: -5px; top: calc(50% - 4px); cursor: ew-resize; }
+.xeplr-canvas-handle-sw { left: -5px; bottom: -5px; cursor: nesw-resize; }
+.xeplr-canvas-handle-s { left: calc(50% - 4px); bottom: -5px; cursor: ns-resize; }
+.xeplr-canvas-handle-se { right: -5px; bottom: -5px; cursor: nwse-resize; }
+
+/* THE MARQUEE BAND. pointer-events:none so the sweep it is drawing cannot be
+   interrupted by the thing drawing it. Above the items, below the alignment
+   guides — a guide that appears mid-sweep is still the more important mark. */
+.xeplr-canvas-marquee {
+  position: absolute; z-index: 8800; pointer-events: none;
+  border: 1px solid var(--xeplr-accent, #4f5fd6);
+  background: color-mix(in srgb, var(--xeplr-accent, #4f5fd6) 12%, transparent);
+}
+
+/* While a marquee is being swept. Text inside an item — a table's cells, a
+   label — is part of its rendering, not something the canvas selects, and a
+   drag across it must not leave a trail of highlighted rows behind. */
+body.xeplr-canvas-sweeping, body.xeplr-canvas-sweeping * { user-select: none; -webkit-user-select: none; }

package/src/designs/index.js

@@ -0,0 +1,7 @@
+import './canvas.css'
+
+export { default as CanvasSample } from './CanvasSample.jsx'
+export { default as DragGuides } from './DragGuides.jsx'
+export { default as MarqueeBox } from './MarqueeBox.jsx'
+export { default as ResizeHandles } from './ResizeHandles.jsx'
+export { default as EdgeLayer } from './EdgeLayer.jsx'

package/src/edges.js

@@ -0,0 +1,73 @@
+// Edges — the lines between items on a canvas that links things (workflow
+// transitions, dataset joins). Pure: points in, SVG path data out.
+//
+// The workflow and dataset canvases each drew their own near-identical
+// bezier; this is the one both use now.
+
+/** The middle of one side of a rect — where an edge leaves or arrives. */
+export function anchorOf(rect, side) {
+  switch (side) {
+    case 'left': return { x: rect.x, y: rect.y + rect.h / 2 }
+    case 'top': return { x: rect.x + rect.w / 2, y: rect.y }
+    case 'bottom': return { x: rect.x + rect.w / 2, y: rect.y + rect.h }
+    case 'right':
+    default: return { x: rect.x + rect.w, y: rect.y + rect.h / 2 }
+  }
+}
+
+/**
+ * A horizontal S-curve from `from` to `to`.
+ *
+ * The control points reach out sideways by half the horizontal gap, but never
+ * less than `minOffset` — two boxes stacked almost vertically would otherwise
+ * be joined by a straight line that runs through both of them.
+ *
+ * `fromDir` / `toDir` (+1 right, -1 left) say which way the line leaves and
+ * arrives. The defaults are the usual left-to-right flow; a join between two
+ * right-hand ports passes fromDir 1, toDir 1 to loop back round.
+ */
+export function bezierPath(from, to, opts) {
+  const minOffset = opts?.minOffset ?? 60
+  const fromDir = opts?.fromDir ?? 1
+  const toDir = opts?.toDir ?? -1
+  const dx = Math.max(minOffset, Math.abs(to.x - from.x) / 2)
+  return 'M ' + from.x + ' ' + from.y +
+    ' C ' + (from.x + fromDir * dx) + ' ' + from.y +
+    ', ' + (to.x + toDir * dx) + ' ' + to.y +
+    ', ' + to.x + ' ' + to.y
+}
+
+/** Where a label on an edge sits. */
+export function midpoint(from, to) {
+  return { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 }
+}
+
+/**
+ * The two ends of one edge, in pixels.
+ *
+ * `edge.to` is an item id; `edge.toOffset` instead ends the edge at a point
+ * relative to where it leaves — for a target that is not an item, like the
+ * workflow's Success/Failed pills. Relative, so it follows its item while it
+ * is dragged.
+ *
+ * @param rectById  id → pixel rect (live positions during a drag)
+ * @param getAnchor optional (item, port, end, rect) → { x, y }, for canvases
+ *                  whose edges attach to ports inside an item (column dots)
+ * @returns {{ from, to }|null} null when either end is not on the canvas
+ */
+export function edgeEnds(edge, rectById, itemById, getAnchor) {
+  const fromRect = rectById[edge.from]
+  if (!fromRect) return null
+  const from = getAnchor
+    ? getAnchor(itemById[edge.from], edge.fromPort, 'from', fromRect)
+    : anchorOf(fromRect, edge.fromSide || 'right')
+  if (edge.toOffset) {
+    return { from, to: { x: from.x + (edge.toOffset.x || 0), y: from.y + (edge.toOffset.y || 0) } }
+  }
+  const toRect = rectById[edge.to]
+  if (!toRect) return null
+  const to = getAnchor
+    ? getAnchor(itemById[edge.to], edge.toPort, 'to', toRect)
+    : anchorOf(toRect, edge.toSide || 'left')
+  return { from, to }
+}

package/src/frameStore.js

@@ -0,0 +1,26 @@
+// A tiny external store for per-frame gesture state — guides, the marquee
+// band, live drag positions.
+//
+// The whole point is that NOTHING ELSE RE-RENDERS during a gesture. Held in a
+// page's state, every frame of a drag re-rendered the page and every card on
+// it, sixty times a second, to move two thin lines. Published here, only the
+// overlay leaves that subscribe (useSyncExternalStore) re-render.
+//
+// A new snapshot object per publish, because useSyncExternalStore compares by
+// identity.
+
+export function createFrameStore(initial) {
+  let snapshot = initial
+  const subs = new Set()
+  return {
+    subscribe(cb) {
+      subs.add(cb)
+      return () => { subs.delete(cb) }
+    },
+    getSnapshot() { return snapshot },
+    publish(next) {
+      snapshot = next
+      subs.forEach((cb) => cb())
+    }
+  }
+}