@weasel-js/diagram 1.11.0 → 1.11.1

package/README.md

@@ -81,6 +81,440 @@ node — so a decision's second exit can leave by its top or its bottom,
 wherever its wire goes. `portSitesOf` resolves every place; anything else that
 shows a port, the connect affordance included, shows it at `at`.
 
+### Connecting to a shape's body
+
+An edge may end on a shape rather than on one of its ports. `DiagramView` takes
+it with `connectBodies`; on a bare canvas, set `bodies` on the connect action
+and add the connector tool, which starts an edge from whatever shape the press
+lands on.
+
+```tsx
+<DiagramView specs={specs} onConnect={add} connectBodies />
+
+const participants = useMemo(() => sceneParticipants(scene), [scene]);
+const connector = useConnectorTool({ participants });
+```
+
+An end is a `ConnectEnd`: a port, or a body (`isBodyEnd` tells them apart). A
+data edge ended on a body has no `fromPort` or `toPort`.
+
+### Reconnecting an edge end
+
+Set `onReconnect` and a selected edge shows a handle at each end. Dragging one
+onto another port, or with `connectBodies` onto a shape, reports the move and
+changes nothing; update the data edge to keep it.
+
+```tsx
+<DiagramView
+  specs={specs}
+  onReconnect={({ edge, end, node, port }) => setEdges((all) => all.map((e) => edgeIdOf(e) !== edge ? e
+    : end === 'from' ? { ...e, from: node, fromPort: port } : { ...e, to: node, toPort: port }))}
+  connectBodies
+/>
+```
+
+`edge` is `edgeIdOf` the data edge, so give edges an `id` when you want it to
+survive a reorder.
+
+### Editing a route
+
+A selected edge shows handles along its route as well as at its ends.
+
+| Router | Handles | Drag | Double-click |
+|---|---|---|---|
+| `straight`, `bezier` | a dot on each waypoint; a smaller hollow dot in the middle of each leg | a dot moves its waypoint; a hollow dot inserts one there | a dot removes its waypoint |
+| `orthogonal` | a bar in the middle of each segment | slides the segment across its axis; a segment touching a port gets a jog, so the port end stays square | straightens a jog away, when a neighbor touching no port can slide into line |
+| `avoid` | a bar in the middle of each segment | slides the segment and pins only it: its two ends become waypoints, and the router keeps the rest | unpins it, dropping the waypoints at its ends |
+
+A dragged handle snaps through the canvas's snap session: into line with the
+stops beside it and with a port's axis within 6 screen pixels (`snapPx`), and to
+whatever else the canvas snaps to, such as a grid, with the readout drawing each
+alignment. It leaves out the canvas's `'path-snap'` default, so a bend never
+catches a shape's corner anchors, and the edge being edited offers nothing to
+itself. A neighbor or port within reach claims its axis, and a grid fills the
+other. Ctrl suspends snapping, Shift holds a dragged bend to the axes and
+diagonals, and a segment always slides across its own axis. Escape cancels.
+A double-click that would remove nothing falls through, to label editing say.
+
+`DiagramView` takes `onEditRoute`, which reports the edge's new waypoints and
+changes nothing: store them as the data edge's `waypoints` and clear its
+`routed`. On a bare canvas, `diagramWaypoints` returns the handle layer to
+register — after the port layer and before the edge-end layer — and the
+contribution to pass as `ambient`, which also carries the `diagram.resetRoute`
+command that clears the selected edges' waypoints. The default commit writes
+the scene in one undo entry, and the route is the author's from then on, so
+layout leaves it alone.
+
+```tsx
+<DiagramView
+  specs={specs}
+  onEditRoute={({ edge, waypoints }) => setEdges((all) => all.map((e) => edgeIdOf(e) !== edge ? e
+    : { ...e, waypoints, routed: undefined }))}
+/>
+
+const route = useMemo(() => diagramWaypoints({ participants, selected }), [participants, selected]);
+```
+
+An orthogonal segment drag writes every bend of the new route as a waypoint,
+since the router recomputes elbows between stops. The math is exported on its
+own: `routeHandles`, `dragVertex`, `insertWaypoint`, `removeWaypoint`,
+`dragSegment`, `removeSegment`, `pinSegment`, `unpinSegment`, and `simplifyStops`.
+
+Waypoints ride along with a move that carries both of an edge's ends by the
+same offset: `waypointFollower(scene)` is a transform follower, added to the
+canvas with core's `useTransformFollower`. An edge with one end moved keeps its
+waypoints where they are.
+
+### Routing around shapes
+
+The `avoid` router draws connectors around shapes: orthogonal, with few bends,
+10 world units clear of every shape, and parallel runs spread 8 apart. Routes
+are computed when the scene is edited and stored on the edge as
+`diagram.route`, the bends between its ends, so a saved file draws them with no
+router running and undo restores them exactly. A stored route that no longer
+fits its ends, after something that did not reroute moved one, draws as
+`orthogonal` instead.
+
+`useAvoidRouting(scene)`, mounted as a child of `<SceneCanvas>`, reroutes what
+each edit disturbed — a move, an insert onto a route, a delete, a paste, a
+panel edit — in that edit's own undo entry, and while a shape is dragged it
+reroutes the connectors near it each frame, through the waypoints a
+`waypointFollower` registered before it carried. Installing it reroutes nothing.
+`installAvoidRouting(scene)` does the same for a host without React, and hands
+back the drag's transform follower. Its scene edit pass runs at
+`DIAGRAM_PASS_ORDER.avoid`; a pass of your own that should see the routes it
+wrote takes a higher `order`.
+
+```tsx
+function Routing({ scene }) {
+  useAvoidRouting(scene);
+  return null;
+}
+
+<SceneCanvas scene={scene} /* … */>
+  <Routing scene={scene} />
+</SceneCanvas>
+```
+
+What a connector routes around:
+
+| Thing | In the way when |
+|---|---|
+| A shape | always, beyond the stubs where a connector leaves or meets it |
+| A container, pool, or group box | neither end is inside it |
+| A lane's body | never |
+| A lane's or pool's header | always |
+| An edge label | always, except to its own connector, 4 world units clear |
+
+Authored waypoints are stops the route passes in order. Layout names an
+`avoid` connector's ports and writes it no waypoints. `diagram.router.avoid`,
+`.orthogonal`, `.straight`, and `.bezier` (`SET_ROUTER_ACTION_IDS`, carried by
+`diagramWaypoints`) set the selected connectors' router; leaving `avoid` drops
+the stored route.
+
+A data-backed `DiagramView` takes `router="avoid"`: it routes every edge of
+each new `specs` around the shapes, holding one router across them so each
+reroutes only what changed, and never reports a route. `createSpecRouter` is
+that step on its own. The search itself, `createAvoidRouter`, reads plain boxes
+and ports and is in `@weasel-js/diagram/layout`.
+
+### Line jumps
+
+While the document value `HOPS_DOC_KEY` (`'diagram:hops'`) holds `{ size }`,
+wherever two connectors cross, the one later in render order bows over the other
+in a half circle of radius `size`. Hops are on or off for the whole document.
+A hop bulges toward −y on a horizontal run and −x on a vertical one, whichever
+way the connector travels, and to the left of travel on a diagonal. A crossing
+within `2 × size` of either connector's ends or within `size` of a bend makes no
+hop, nor does a collinear overlap; hops closer than `2 × size` merge into one
+longer hop. A connector split across pages takes no part: its stubs are too
+short to hold a hop clear of their ends, and the run between them is not drawn.
+
+Each connector stores its hops as `diagram.hops`, `{ at, over, r }` in world
+units, so a saved file draws them with no pass running. `edgeDerivePath` draws
+only the hops that still lie on the route, so one left behind by an edit that
+did not recompute never draws.
+
+`useHops(scene)`, mounted as a child of `<SceneCanvas>` after `useAvoidRouting`,
+recomputes the hops each edit disturbed in that edit's own undo entry, and
+setting or clearing the value recomputes or clears every connector in the entry
+that sets it. While a drag is in progress, the connectors it moves and those
+hopping over them draw without hops; the release puts them back.
+`installHops(scene)` does the same without React. Its pass runs at
+`DIAGRAM_PASS_ORDER.hops`, after routing.
+
+`diagram.hops` (`SET_HOPS_ACTION_ID`, carried by `diagramWaypoints`) toggles the
+value, at radius 5 (`DEFAULT_HOP_SIZE`). A data-backed `DiagramView` takes
+`hops={radius}`, applied after `router`; `createSpecHops` is that step on its
+own. `edgeHops`, which finds the hops over plain polylines, is in
+`@weasel-js/diagram/layout`.
+
+### Edge labels
+
+`onEditLabel` reports a double-click on an edge. `edgeLabelSpec` builds the
+label node that rides the edge's route, and `editEdgeLabelAction` creates one
+or edits the existing one in place.
+
+```tsx
+<DiagramView specs={specs} onEditLabel={(edge) => startEditing(edge)} />
+
+const spec = edgeLabelSpec(edgeId, 'yes', { layer: 'diagram' });
+```
+
+`labelSize` is the box a label's text takes. Both routes size with it, so a
+label built from data and one the action creates come out the same size.
+
+### Labels that dodge
+
+After any edit, a label that would sit on a shape, on another label, or across
+another connector slides along its own connector, or flips to the other side of
+it, to the nearest clear spot. It tries its preferred station first, then up to
+four stations either way, a label width and 8 apart, each on both sides of the
+line, and keeps the cheapest: area over shapes counts most, then area over
+other labels, then connectors it covers, then how far it moved. Labels move in
+id order, each an obstacle for the next, so the answer is always the same.
+
+The station placement chose is stored on the trait as `placed` (`at`, a
+fraction of the route's length, and `offset`), read before `at` and
+`offset`, which stay the author's preference; a label goes back to its
+preference once that spot is clear. `dodge: false` keeps a label where its
+author put it. Under `layered`, the room layout left a label is its preference,
+so a laid-out diagram's labels stay put unless something covers them.
+
+`useLabelPlacement(scene)` places what each edit may have covered or uncovered
+in that edit's own undo entry, and sizes a label to the text an edit gives it.
+Labels hold still while a shape is dragged and settle on release.
+`installLabelPlacement(scene)` does the same without React. Its edit pass runs
+at `DIAGRAM_PASS_ORDER.labels`, after routing: connectors route around labels as
+they stand, then labels move off the new routes, one round each per edit.
+
+```tsx
+useAvoidRouting(scene);
+useLabelPlacement(scene);
+```
+
+A data-backed `DiagramView` takes `labels="dodge"`, placed after any
+`router`, and never reports a placement; `createSpecLabelPlacer` is that step
+on its own. The arithmetic, `placeLabels`, reads plain boxes and routes and is
+in `@weasel-js/diagram/layout`.
+
+### Connectors between pages
+
+On a scene with pages (core's `core:pages` document value), a connector whose
+two shapes sit on different pages draws nothing across the gap. Each end draws
+a stub `OFF_PAGE_STUB` (24) world units out of its shape, ending at a tag that
+reads the other page's name and a reference letter, such as "Page 2 · A". The
+start stub ends in the connector's end marker, so it reads as leaving the page.
+A shape in the gap between pages belongs to none, and its connectors stay
+whole.
+
+A data-backed diagram takes the same pages as `DiagramData.pages` (core's
+`Page`s), placed by `layoutPages` with `pageLayout`; `diagramPages(data)` gives
+them in world space. `diagramScene` splits each connector between pages and
+adds its two tags, lettered in the order the data lists the edges. An edge to a
+group or a container splits by that box's page, not a member's.
+`dataOffPage(edges, pages, boxOf, look)` is the same step over plain boxes.
+
+`useOffPageMarkers(scene)` splits and joins connectors as edits move their
+ends or change the pages, in that edit's own undo entry; installing it
+recomputes nothing. `installOffPageMarkers(scene)` does the same without React.
+Its pass runs at `DIAGRAM_PASS_ORDER.offPage`, before routing, so the `avoid`
+router skips a split connector and routes it again in the entry that joins it.
+A split connector shows no route handles and keeps its waypoints for when it
+joins.
+
+```tsx
+function Markers({ scene }) {
+  useOffPageMarkers(scene);
+  return null;
+}
+
+const offPage = diagramOffPage();
+<SceneCanvas scene={scene} ambient={[offPage.contribution]} /* … */>
+  <Markers scene={scene} />
+</SceneCanvas>
+```
+
+| Surface | What it is |
+|---|---|
+| `DiagramEdge.offPage` | `{ ref, from, to }`: the reference and the two ends' page ids, written by the pass |
+| `offPageSplits`, `nextOffPageRef` | which connectors split, as arithmetic on page rects and end boxes; refs run A…Z, AA… and stay while a split does |
+| `offPageTagSpec`, `offPageTagOf` | a tag: a text node with a background, id `<edge>/offpage-<end>`, that stations itself past its stub |
+| `offPageOps` | the pass's ops for named connectors, or `'all'`, for a document saved before it had markers |
+| `diagramOffPage`, `createFollowOffPageAction` | a double-click on a tag selects the far shape and fits the view to its page; `follow` replaces that |
+| `offPageTargetOf` | where a tag leads: the far shape and its page |
+
+Tags take the theme's label color and face on its page color, and applying a
+theme recolors them. A host whose text editing opens on any text node should
+leave tags out: the pass owns their text.
+
+To save one page as an SVG document or a PNG image, cut to the page with its
+stubs and tags, use `exportPageSvg` and `exportPagePng` from
+`@weasel-js/diagram-formats`.
+
+### Overlays and hover
+
+`overlays` holds DOM against a node, a group or an edge, and places it again
+after every paint, so it follows pans, zooms, resizes and layout. A side
+placement uses geom's `placeRect` inside the view, flipping to the far side
+when the near one has no room; the default centers it on the target. An
+edge's place is the midpoint along its route.
+
+```tsx
+<DiagramView
+  specs={specs}
+  pickEdges
+  onHover={setHovered}
+  overlays={[
+    ...(hoveredEdge ? [{ target: hoveredEdge, content: <button onClick={insert}>+</button> }] : []),
+    ...(picked ? [{ target: picked, placement: { side: 'right', align: 'start' }, offset: 8, content: <Card /> }] : []),
+  ]}
+/>
+```
+
+`onHover` reports the node, group or edge under the pointer, and `null` when
+there is none or the pointer leaves the canvas, which it also does when the
+pointer moves onto an overlay. Edges answer only with `pickEdges`. For DOM
+the view does not hold, `rectOf(id)` on the ref gives a target's client rect
+and `subscribeFrame` says when to read it again.
+
+### Reordering a group's members
+
+A group with `reorder: 'x' | 'y'` lets `onReorder` drag any of its members
+along that axis; a member that is a group carries everything inside it. The
+other members slide into the places they would take, and the release reports
+the new order without moving anything. With a member picked, Alt and an arrow
+key steps it one place. `layered` keeps a reorderable group's members in the
+order given across every rank, so writing the order back is all it takes.
+
+```tsx
+const data = { nodes, edges, groups: [...rows, { id: 'layers', members: order, reorder: 'y' }] };
+<DiagramView specs={diagramScene(data)} onReorder={({ order }) => setOrder(order)} />
+```
+
+### Stencils
+
+A `DiagramStencil` is a palette entry: an id, a label, an outline and a default
+size. `FLOWCHART_STENCILS` has the basic flowchart symbols. `useStencilInsert`
+makes the canvas's `insert` dep build them, and `useStencilTool` gives each a
+tool that places one on a drag. A click places nothing; to place one at a
+point, call the `insert` dep's `commit` with a zero-size box there and the
+stencil's kind, and the body comes out at the stencil's size.
+
+```tsx
+useStencilInsert(FLOWCHART_STENCILS, { layer: 'diagram' });
+const decision = useStencilTool(FLOWCHART_STENCILS[1]);
+```
+
+A drop from your own palette goes through the canvas's `ingestion` handlers:
+a handler gets the drop's world point as `ctx.point` and calls
+`ctx.insert.commit`. Elsewhere, `SceneCanvasApi.clientToWorld` turns a client
+point into a world one. `useStencilInsert` hands any kind that is not a stencil's to
+the `insert` dep it displaced, so core's rect, ellipse and text tools keep working.
+
+### Containers and pools
+
+A container is a titled box that holds other shapes; a pool is a header and a
+stack of lanes, each holding shapes. Both are core `ContainerNode`s carrying a
+`container` trait (`diagramContainerOf`): a role of `container`, `pool`, or
+`lane`, and a header. A region's title is a text child named
+`<id>/title`, so double-clicking a header renames it.
+
+| What the user does | What happens |
+|---|---|
+| drags a shape into a container's body or a lane | the shape becomes its member, in the move's undo entry |
+| drags a member out | it leaves, to the top level or the container under the drop |
+| drags a container | its members, and the waypoints of connectors between them, go with it |
+| resizes a container | its members stay where they are |
+| deletes a container | its members go with it; Release members keeps them |
+| drags a lane by its header | the lanes reorder, members and all |
+| drags the boundary after a lane | that lane resizes and the pool grows or shrinks with it |
+| clicks the button past the end of a pool | a lane is added at the end |
+
+`CONTAINER_STENCILS` offers Container, Pool (rows), and Pool (columns); pass it
+as `useStencilInsert`'s `containers` and give each a `stencilTool`. Their glyphs
+are in the `diagram` icon namespace, whose table is `@weasel-js/diagram/icons`;
+an app without the icons build plugin registers it beside the kit's. A stencil
+drawn inside a container or a lane becomes its member (`diagramDropParentAt`).
+`containerBuild` returns the ops on their own, and `addLane` and
+`releaseMembers` are the edits as functions.
+
+What a region admits is the `canDropInto` dep's call, and `diagramCanDropInto(scene)`
+is the one for a diagram: containers and lanes take shapes and containers, a
+pool takes only lanes, and a stencil body, an edge, or a label takes nothing.
+`diagramContainers` returns the lane layer to register and the contribution to
+pass as `ambient`, which carries the boundary drag (`diagram.resizeLane`), the
+add-lane click (`diagram.addLane`), and the `diagram.releaseMembers` command.
+The two lane gestures take a swappable commit.
+
+```tsx
+useStencilInsert(FLOWCHART_STENCILS, { containers: CONTAINER_STENCILS });
+useDepSource('canDropInto', () => diagramCanDropInto(scene));
+const containers = useMemo(() => diagramContainers({ scene, selected }), [scene, selected]);
+```
+
+The layouts register by key through `withDiagramRegistry`, so a saved scene
+finds them again: `diagram:container`, `diagram:pool-rows`,
+`diagram:pool-columns`, `diagram:lane-rows`, and `diagram:lane-columns`.
+`diagramContainerLayout` places members freely under a header, and
+`laneStackLayout` stacks a pool's lanes in the order they sit; a pool's size
+along the stack is the sum of its lanes. Lanes take no connectors, and
+connectors stay at the top level, drawn above every container. `diagramScene`
+builds them from data too (see "From data").
+
+### Themes
+
+A `DiagramTheme` is a document's colors and face: a style per role (`DIAGRAM_ROLES`: Default,
+Accent, Muted, Positive, Warning, Negative), the connector and label colors, the container and
+lane looks, the page color, a font, and a `series` of colors for things it cannot name ahead,
+such as a look's value types. `DIAGRAM_THEMES` ships `paper`, `night`, `blueprint`, `pastel`, and
+`mono`; `diagramThemeFromTokens(read)` builds one from a host's resolved `--wzl-*` values.
+
+A theme writes literal colors into the scene, so whatever draws or exports the scene needs no
+theme. A shape or connector names its role in its trait's `style`, and lists the colors its
+author set by hand in `ownStyle`; a theme leaves those. A theme whose font size differs from the
+one the scene was in moves every text by the step between them, keeping a title or label's offset
+from the body size, except text whose owner lists `'size'` in `ownFont`. A body whose text changes
+size is laid out again in the same undo entry: it grows to what its rows need, never shrinks, and a
+body the author made larger keeps its size. A body built from text rows alone records how it
+stacks them (`DiagramNode.body`, each row's text node carrying `bodyRow`), which is what
+`relayoutBodies(scene, ids, measure)` reads back. `rendererMeasure` measures a row as the kit's
+text renderer lays it out, from the registered font, for a host whose bodies should hold their
+text exactly.
+
+```ts
+applyDiagramTheme(scene, DIAGRAM_THEMES.blueprint);          // one undo entry, saved as `diagram:theme`
+setDiagramStyle(scene, selection.get(), 'warning');          // name a role, and recolor in it
+setDiagramColor(scene, selection.get(), 'fill', '#ffcc00');  // by hand: survives the next theme
+setDiagramFontSize(scene, selection.get(), 16);              // by hand, recorded in `ownFont`
+const theme = diagramThemeOf(scene, DIAGRAM_THEMES.paper);   // the scene's theme, or a fallback
+```
+
+`themeWrites(scene, theme)` is the pure half: the new `data` for every node the theme recolors.
+New shapes and connectors take the theme from whatever inserts them: pass `roleStyle(theme)` and
+`themeFont(theme)` to `useStencilInsert`, `themeEdgeStroke(theme)` as a connect action's
+`edgeStroke`, and `themeLabelStyle(theme)` and `theme.label.fill` to `editEdgeLabelAction`.
+`diagramScene` takes `theme` too, drawing each `DataNode` in its `style` role, and the effect
+looks take one in their options (default `night`, which draws them as they always were).
+
+A theme is edited as a value: each edit returns a new theme, so a shipped one is never changed.
+`editableTheme(theme)` is where an editor starts: a shipped theme forked as "<name> (edited)", a
+custom one as it is. A custom theme lives in the document's `diagram:theme` value and travels
+between documents as a `.weasel-theme.json` file.
+
+```ts
+let theme = editableTheme(diagramThemeOf(scene));
+theme = setThemeValue(theme, ['roles', 'accent', 'fill'], '#ff8800');  // also edge, lane, page, font, series…
+theme = addThemeRole(theme, 'Critical').theme;                         // in the default role's colors
+theme = removeThemeRole(theme, 'muted');                               // its shapes fall to the default role
+applyDiagramTheme(scene, theme, 'Edit theme', { coalesceKey: 'theme:roles.accent.fill' });
+const file = themeToJson(theme);                                       // and back: parseDiagramTheme(file)
+```
+
+Applies made under one `coalesceKey` with nothing between fold into one undo entry, so a color
+dragged undoes in one step; `scene.history.seal()` ends the run. `parseDiagramTheme` answers
+`{ theme }` or `{ errors }`, each error naming the bad value by its path.
+
 ### Laying it out
 
 `layered`, `tree`, `force` and `chain` are plain functions of the graph. Each
@@ -184,7 +618,15 @@ label row each. A `slot` row is reserved space, `height` tall and, with a
 `width`, that wide and centered; one with an `id` becomes a scene node of that
 name, `<node>/<id>`, drawn as an empty frame until you fill it by changing its
 data — with `{ image: { src } }`, say. An edge can name `fromPort`/`toPort`, its own `router`,
-`waypoints` and `labelPlacement`.
+`waypoints`, `labelPlacement`, and a theme role in `style`.
+
+A node, an edge, a container, or a lane can carry `colors` of its own: a node's `fill`, `stroke`,
+and `text`, an edge's `stroke`, `label`, `width`, `dash`, and markers. `diagramScene` draws them
+over the theme and lists the colors in the trait's `ownStyle`, so a later theme change leaves
+them, as it leaves a color set by hand. `dataNodeStyle`, `dataEdgeStyle`, and `dataRegionStyle`
+give the style an item is drawn in, for a writer that needs it without drawing; where a style gives
+no width, `NODE_STROKE_WIDTH`, `LANE_STROKE_WIDTH`, and `EDGE_STROKE_WIDTH` are what is drawn. `layer` puts every
+spec on a layer other than `'main'`.
 
 `outline` is `'rect'`, `'diamond'`, `'stadium'`, `'parallelogram'`,
 `'trapezoid'` (a demultiplexer: tall at the right, short at the left),
@@ -253,6 +695,37 @@ stage. A scene built
 any other way joins in with a node whose trait carries `group` and whose
 `dependsOn` lists its members.
 
+`containers` draws the containers and pools of "Containers and pools" from data:
+
+```tsx
+diagramScene({ nodes, edges, containers: [
+  { id: 'review', role: 'container', label: 'Review', members: ['draft', 'check'] },
+  { id: 'teams', role: 'pool', label: 'Teams', box: { x: 0, y: 400, width: 600, height: 240 }, pinned: true,
+    lanes: [{ id: 'ops', label: 'Ops', members: ['deploy'] }, { id: 'qa', label: 'QA', size: 80 }] },
+] });
+```
+
+Each region is a scene container and its members are its children, so a
+region's id shares the node id namespace, and so does each lane's. A member
+already claimed by an earlier region, a pool, and a claim that would put a
+container inside itself are ignored. A node is in a group or in a region, never
+both: a region is its scene parent, and a group would draw a second box around
+it that the region's does not hold, so `diagramScene` throws on a node that
+`groups` and `containers` both name. A container with a `box` is laid out as
+one node of that size, and its members ride along with it, keeping where they
+stand in it; a member with no `at` is seeded inside its body, in rows. A
+container with no `box` is laid out as a group, and its box fits its members.
+A pool always has a box: 600 across and 120 along per lane when it gives none
+(`DEFAULT_POOL_ACROSS`, `DEFAULT_LANE_SIZE`). Its lanes stack along `axis`
+(`'y'`, rows, by default) at their `size`, and lanes giving none share what
+the pool's box leaves. An edge with an end inside a boxed region ranks against
+the outermost one holding it, and keeps none of layout's route. `pinned`
+leaves a box where it is. Under `theme`, a region naming a `style` role takes
+that role's colors; otherwise a container takes the theme's `container`, a
+pool its `lane.header`, and lanes the `lane.bodies` in turn; titles are set in
+the diagram's face, the theme's when `font` is unset. `router="avoid"`
+routes around a region neither end is inside, and around every header.
+
 Text is sized from character counts unless `measure` is given, so layout runs
 without a canvas. The layout defaults to `layered`, picked by name or passed as
 any `LayoutFn`; `layoutOptions` merge over `order: 'barycenter'`, and
@@ -286,10 +759,44 @@ would make it yours, which layout never moves. A run that only rewrote routes
 calls `onMove` with no moves.
 `onMove` hears only what changes after the view is built. Where the build's own
 layout put things, `diagramLayoutOf(specs)` reads off the specs, in the same
-shape (`{ moves, routes }`): every node not pinned, and every edge whose route
-or ports layout wrote. Store them the same way and the next `diagramScene`
+shape (`{ moves, routes, containers }`): every node not pinned, every edge whose route
+or ports layout wrote, and a `box` edit for every container and pool not pinned
+whose box is its own. Store them the same way and the next `diagramScene`
 leaves those nodes where they stand and lays out only the new ones, which keeps
 a diagram still while its data is edited.
+`onResize` gives a selected node resize handles (`diagramResizable`, so none on
+an edge, an edge label, a lane, or a group's box). The box resizes live under
+the drag; on release the view reports `{ id, x, y, width, height }` for each
+resized node and draws the new box only once the specs do. Store it as the
+node's `width`, `height`, and `at`, with `pinned: true`. The size is a minimum,
+so a box dragged smaller than its rows grows back to them. Core's
+`createResizeAction({ commit })` is what reports: it hands the release poses to
+`commit` in place of writing them.
+
+```tsx
+<DiagramView
+  specs={specs}
+  onResize={(resizes) => setNodes((ns) => withBoxes(ns, resizes))}
+/>
+```
+
+`onEditContainer` edits containers and pools the way chart mode does, and
+reports each edit without keeping it (`ContainerEdit`):
+
+| The user | Reported |
+|---|---|
+| drags a shape into a container or a lane, or out | `onMove`, the move carrying `parent`: the region's id, or `null` for the top level |
+| drags a container or pool, or resizes it by a handle | `{ kind: 'box', id, box }`, with `parent` when a drop changed its region; what it carried goes to `onMove` |
+| drags a lane's boundary | `{ kind: 'lanes', pool, lanes }`, every lane with its size; the shapes in the lanes after it go to `onMove` |
+| drags a lane by its header to another place | `{ kind: 'lanes', pool, lanes }` in the new order |
+| clicks a pool's add-lane button | `{ kind: 'lanes', pool, lanes }` ending in a new lane, its id minted by the view |
+| double-clicks a header | `{ kind: 'title', id }`, for the host to edit the label |
+| runs Release members (`diagram.releaseMembers`) | `{ kind: 'release', id }` |
+
+Move ids between `members` lists on a move's `parent`, and store a `box` as the
+region's `box` with `pinned: true`. `onDelete` reports a deleted region with
+everything inside it. The view lets shapes drop only into containers and
+lanes, and lanes only into pools (`diagramCanDropInto`).
 `view.current.layout('layered')` re-runs a layout animated from where the
 nodes stand; `'force'` relaxes live. Either way the routes ease with the nodes,
 through the ports the run will commit.
@@ -419,7 +926,9 @@ about. A `switch` symbol is drawn thrown to its first exit, and a run whose
 `taken` is the second throws it there. `EffectChart` fades the port dots of a
 stage the run never reached as well; `paintRun` alone cannot, since the port
 layer draws them outside the scene. A decision a look does not draw has nowhere
-to show its cost.
+to show its cost. A stage whose entry has an `error` shows it where its cost
+would go, in the problem color, and a run's `at` names a stage to outline,
+as a run taken a step at a time does.
 
 A run never lays the chart out again or refits it: `paintRun(pipeline, specs,
 run)` edits the specs the look already built, data only, and `DiagramView`
@@ -606,6 +1115,189 @@ const column: EffectLook = (pipeline) => {
 };
 ```
 
+#### Editing a pipeline
+
+`EffectEditor` is `EffectChart` with the node-graph look made editable: drag a
+stage to move it, drag it into or out of a group (below), drag from an output to an input to wire them, press Delete to
+remove the selection, drag an end of a selected wire to move it, and drag the
+handles along a selected wire to route it (`EffectDoc.routes`, set with
+`setWireRoute`). It keeps no
+document state. Every edit comes back through `onChange` as the next `EffectDoc` with a
+name for an undo entry, and shows once `doc` follows.
+
+```tsx
+import { EffectEditor, type EffectEditorApi } from '@weasel-js/diagram/effect';
+
+const api = useRef<EffectEditorApi>(null);
+
+<EffectEditor ref={api} doc={doc} onChange={(next, label) => commit(next, label)} />;
+
+api.current?.addStage({ type: 'gate', title: 'Gate', inputs, outputs });
+```
+
+An `EffectStageType` carries the ports and typed params a new stage starts
+with. `setParam`, `addWire`, `removeStages` and the rest of the edit model are
+plain functions from one `EffectDoc` to the next, and `canWire` asks an
+`EffectPipeline` whether two ports may be wired, for driving the edits yourself.
+
+`look` picks the drawing: `'nodeGraph'` (default), `'rack'`, or `'lanes'`, with
+that look's `options`. Connecting, reconnecting, and deleting work the same in
+all three. Rack and lanes place every stage themselves, so under them a stage
+does not move freely. Instead a stage on the main line drags along it: an
+insertion bar marks the gap it would land in, drawn in the problem color where
+the wiring cannot take it, and releasing it there reports `'Reorder'`. Under
+lanes, dragging a lane's label up or down reports `'Reorder lanes'`.
+
+A selected wire's route handles work under every look, and report
+`'Edit route'`. Under rack and lanes the route goes in `EffectDoc.lookRoutes`,
+by look and then by wire, with the points of the wire's two ports as they were
+drawn (`setLookRoute(doc, look, wire, waypoints, ends)`). These looks move
+stages on every reorder or added stage, so a route is drawn only while both
+ports are still at those points; once one moves, the look routes the wire
+again. Reset route, or `setLookRoute` with no waypoints, gives the wire back to
+the look. `applyLookRoutes(specs, doc, look, built)` draws the routes that
+hold over a look's specs, and `wireEnds(specs, edge)` reads a drawn wire's
+port points. A reorder drops the routes of the wires it rewires or removes,
+and removing a wire or a stage drops that wire's routes.
+
+```tsx
+<EffectEditor doc={doc} onChange={commit} look="rack" />
+```
+
+The order is the wiring, so a reorder rewires the pipeline:
+`moveInChain(doc, stage, to)` takes the stage's main input and output wires
+off, wires its old neighbors to each other, and wires it into gap `to` of
+`mainChain`. Side wires, control wires, and params stay with it. It returns
+`null` where a new wire would join unlike types. Lane order is
+`EffectDoc.laneOrder`, which `setLaneOrder` writes and the editor hands to
+`lanes` over `options.lanes`. Rack's `chain` option is not offered here, since a
+given chain could disagree with the wiring.
+
+The drag itself is general: `createReorderAction` (in `@weasel-js/diagram`)
+carries one item of any drawn sequence along its axis, and the item lands in
+the gap nearest its middle. Give it `slots`, the items and gaps that
+`sequenceSlots(axis, items)` builds from their boxes, and a `commit` that hears
+`{ id, from, to, order }`. `show: 'bar'` (the default) draws the insertion bar;
+`show: 'slide'` slides the other items into the places they would take instead,
+moving each item's `carries` as pose overrides, which is how `onReorder` shows a
+group's members. `reorderContribution` packs the action and its binding to pass
+as `ambient`.
+
+`EffectEditor` takes a `run` too, drawn as `EffectChart` draws one.
+
+##### Groups
+
+Under `nodeGraph` each `EffectGroup` is a titled box, drawn as a `DiagramData`
+container. Drag a stage into or out of it to change what it holds, drag the
+box to carry the stages and groups inside it with the routes of the wires
+between them (`'Move'`), drag a picked box's handles to resize it
+(`'Resize group'`), and double-click its title to rename it in a field held
+over the title (`'Rename group'`). A resized box is kept in
+`EffectDoc.groupBoxes`, by group id; a group with no box fits its members.
+Under `rack` and `lanes` groups draw as boxes around their members, and
+membership does not drag. A drag's moves and box edits come in as separate
+reports, so the editor gathers them and reports one edit once the drag is done
+reporting, a microtask later.
+
+`selectedGroup` and `onSelectGroup` are the group pick, beside `selected` and
+`onSelect`, under every look. The ref's `group(ids)` and `ungroup(id)` report
+`'Group'` and `'Ungroup'`, and `renameGroup(id)` opens the title field. The
+edits are plain functions too:
+
+| Function | What it does |
+| --- | --- |
+| `groupStages(doc, ids, label?)` | A new group, id from `nextGroupId`, holding `ids`; nested inside the group they all share, else at the top level. |
+| `ungroup(doc, id)` | Its members go to its parent group, in its place. |
+| `renameGroup(doc, id, label)` | An empty label removes it. |
+| `moveToGroup(doc, ids, group \| null)` | Into a group, or out to the top level. A group left empty goes too unless it has a box. |
+| `setGroupBox(doc, id, box \| null)` | `null` has it fit its members again. |
+| `moveGroup(doc, id, offset)` | Its stages' places, its box and the boxes inside it, and its inner wires' routes, by one offset. |
+
+`removeStages` drops a group it leaves empty, with its box.
+
+#### Running a pipeline
+
+A run can be made as well as drawn. An `EffectEvaluator` evaluates one stage:
+it is handed `{ stage, inputs, params, sources, time, signal }` and returns
+`{ outputs, taken? }`, sync or async, with a value per output by port id. An
+`EffectValueKind` says how a run shows (`show`), previews (`preview`), and frees
+(`dispose`) the values of one value type. Both are keyed: evaluators by stage
+`type`, kinds by value type.
+
+```tsx
+import {
+  IMAGE_STAGE_TYPES, imageEvaluators, imageValueKinds, testCard, runPipeline, useEffectRunner,
+} from '@weasel-js/diagram/effect';
+
+const once = await runPipeline(pipeline, {
+  evaluators: imageEvaluators, kinds: imageValueKinds, sources: { image: testCard(256) }, time: 0,
+});
+
+// In a component: Run, Step, and Play, with the run to draw.
+const { run, playing, runner } = useEffectRunner({ pipeline, evaluators: imageEvaluators, kinds: imageValueKinds, sources });
+<EffectEditor doc={doc} onChange={commit} run={run} options={{ showValues: true, showPreviews: true }} />;
+runner.step();
+```
+
+`runPipeline` evaluates the stages in `runOrder(pipeline)`: topologically over
+data and control wires alike, stable by stage order, leaving out the stages on a
+cycle, which never run. A stage with inputs none of which a value reaches is
+skipped, so a decision's untaken branch stays faded. A bypassed stage passes its
+first input of each output's type through. An evaluator that throws sets the
+stage's `error`, and what it feeds is left unreached. Each stage's `cost` is the
+time its evaluator took. Every value the run made is disposed before it
+resolves, but never a source; the previews in the run are yours to close.
+`createPass` takes the same run a stage at a time. A stage with no outputs, such
+as a sink, shows and previews what reached its inputs instead, so the end of a
+pipeline shows the finished result; `shownPorts(stage)` says which ports a look
+keeps value rows and preview slots for.
+
+`createEffectRunner` keeps one pipeline running: `run()`, `step()` (the next
+stage, as the run's `at`, and back to the first after the last), `play()`,
+`pause()`, `reset()`, and `setPipeline`, `setSources`, and `setOptions` for the
+next run to follow. While playing, `advance(seconds)` moves its clock on and
+starts a run unless one is still going. It owns the previews of its runs:
+`drawn(run)` says a run is on screen, and closes the previews of every older run
+it does not show. `useEffectRunner` makes one for the life of a component,
+advances it from `useVisibleRaf` while playing, so time spent hidden is not
+counted, and calls `drawn` after each render.
+
+`IMAGE_STAGE_TYPES` is a palette of image stages (Source, Blur, Composite, Mask,
+Oscillator, Decision, and Out), and `imageEvaluators` runs them on
+`OffscreenCanvas` 2D, an image or mask being an `ImageBitmap`. A source puts out
+`sources.image`; blur uses the canvas `filter`; composite blends by
+`globalCompositeOperation`; mask keeps what lies under the mask's opaque
+pixels; an oscillator puts out `sin(2π·rate·t)`; and a decision chooses by its
+`split`, or else its first output while the tested number is above 0. A stage
+missing an input it needs fails, naming it. `imageValueKinds` shows an image by
+its size and a number to three places. `testCard(size)` draws an image to start
+from.
+
+#### Live audio
+
+`@weasel-js/diagram/effect-audio` plays an audio pipeline through a patchable
+`@weasel-js/audio` graph, which is an optional peer dependency: install it to
+use this subpath. It exports `AUDIO_STAGE_TYPES` (the palette),
+`audioStageNodes` (the graph node each stage builds), `createLiveAudioRunner`
+with the `useLiveAudioRunner` hook (or `useFollowAudioRunner`, for a runner
+the caller makes and owns), `livePlan` and `diffPlans` (the pipeline turned
+into graph patches), and `drawScope` and `drawSpectrum` for the stages' `out`
+previews.
+
+```ts
+import { createAudioEngine } from '@weasel-js/audio';
+import { createLiveAudioRunner } from '@weasel-js/diagram/effect-audio';
+
+const engine = createAudioEngine();
+// pipeline: an EffectPipeline, such as the `pipeline` of an EffectEditor's doc
+const runner = createLiveAudioRunner({ engine, pipeline });
+await runner.play();
+runner.setPipeline(edited); // patches the playing graph; a delay keeps its tail
+```
+
+A param that is a level (a gain, a delay's `mix`) is written to the running
+node; one that is a setting (a wave, a file) replaces the node.
+
 ## Design notes
 
 Decisions the code cannot explain on its own.