@react-x11/components 0.9.0 → 0.11.0

package/dist/flow/node.d.ts

@@ -2,12 +2,34 @@ import { Node } from 'react-x11/node';
 import type { A11ySceneAction, A11ySceneItem } from 'react-x11/node';
 import type { Context2D } from 'react-x11/node';
 import type { KeyboardEvent, MouseEvent, WheelEvent } from 'react-x11';
-import type { FitViewOptions, FlowNode, FlowNodeType, FlowRect, FlowInstance, HandleSpec, Viewport, XYPosition } from './types.js';
+import type { PainterOptions } from './draw.js';
+import type { FlowScene } from './scene.js';
+import type { FitViewOptions, FlowBodyBudget, FlowNode, FlowNodeType, FlowRect, FlowInstance, HandleSpec, Viewport, XYPosition } from './types.js';
 /** Registration key, `kind` and JSX tag, one string — react-x11 rejects a
  * node whose `kind` is not the name it was registered under, because `kind`
  * is what paint order, the test queries and the DEV style assertion all
  * match on. */
 export declare const ELEMENT = "flowgraph";
+/** A canvas `<Flow>` paints a panel on: a core node, asked to repaint its
+ *  own box. */
+interface PanelCanvas {
+    invalidate(layout: boolean, damage: unknown, reason: string): void;
+    /** Where a claim of the canvas lands: its box and core's damage slop,
+     *  device pixels. */
+    paintBounds?(): FlowRect;
+    /** Its box, device pixels. */
+    readonly abs?: FlowRect;
+}
+/**
+ * The pane's time: what a pan is stamped with, and what the dashes' march
+ * reads to decide it has held still. A test holds it (test/flow.test.ts):
+ * a runner that spends longer than the dashes' wait over one step of a pan
+ * lets them march in the middle of it — as they should — and a test of the
+ * pan cannot tell that from a march it should not have made.
+ */
+export declare const flowClock: {
+    now: () => number;
+};
 type AnyNode = FlowNode<unknown>;
 type AnyType = FlowNodeType<unknown>;
 /** A node, resolved: its size and its handle specs, both of which only
@@ -56,21 +78,146 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
      * when the app applies the changes it is being sent. Cleared on release,
      * which is also how a refused drag snaps back. */
     private _dragTo;
+    /** Whether the pane's edges are stroked a pen at a time (`EDGE_BATCH`):
+     *  chosen by a pass over the whole pane, and followed by every pass over
+     *  part of it until the next. */
+    private _batch;
     /** The box a resize is currently making, for the same reason. */
     private _resizeTo;
-    /** What was last handed to `onNodeBodies`, so the React half is told only
-     * when something actually moved. */
-    private _bodiesKey;
+    /** The bodies last sent, re-sent as the same array when only the origin
+     *  moved, and that origin — and each one by id, reused as the same object
+     *  when nothing about it changed, so the React half re-renders the card
+     *  that moved and not the ones beside it. */
+    private _bodies;
+    private _bodiesById;
+    private _bodiesOrigin;
+    /** Bodies held back while the zoom moves (`_holdBodies`): whether they
+     *  are, the zoom last seen, the timer that brings them back and when the
+     *  last held step was. */
+    private _bodiesHeld;
+    private _seenZoom;
+    private _bodiesRest;
+    private _bodiesAt;
+    /** Mounted cards `<Flow>` shows, painted in the bodies' layer — which
+     *  the 2D pane then leaves out (`setShownBodies`, `_cardInLayer`). */
+    private _shownBodies;
+    /** The canvases `<Flow>` paints the minimap and controls on, over the
+     *  bodies — while there are any, the graph leaves the panels out. */
+    private _panelCanvases;
+    /** The fit the minimap on screen was painted with: every pass over it
+     *  since its corner was last claimed whole resolved the same one. Set by
+     *  the pass that paints it (`_sceneInput`), read by what a move claims
+     *  there (`_miniMapMoves`). */
+    private _miniMapShown;
+    private _panelsKey;
+    /** The budget's model (`_holdBodies`, `_frameTick`): what a body adds to a
+     *  zoom step, what a step costs with none re-scaled, the last frame's
+     *  time, and what the step awaiting its frame did. */
+    private _bodyStepMs;
+    private _baseStepMs;
+    private _lastFrameAt;
+    private _zoomStep;
     private _dashPhase;
+    /** The box the bodies are laid out in, which a 2D pan carries. */
+    private _bodiesLayer;
+    /** When a pan last asked to blit — the dash timer waits for it. */
+    private _blittedPanAt;
+    /** When the view last moved, and when the dash timer last came round,
+     *  ticking or not: a 2D pan's dashes wait for a view that held still. */
+    private _viewMovedAt;
+    private _tickAt;
+    /** When the dash timer last marched, and what a 2D frame has cost lately
+     *  — the paint, and the server's answer to the frame before it; a running
+     *  mean, ms: what a tick waits on. */
+    private _marchedAt;
+    private _tickCost;
     private _animTimer;
     /** Inside `paint`, where an invalidation would only schedule a redraw of
      * the frame being drawn. */
     private _painting;
+    /** Routes that survived the last frame — see {@link SceneCache}. */
+    private readonly _sceneCache;
+    /** Asks the GL surface for a frame, while one is drawing this pane. */
+    private _glRequest;
+    /**
+     * Bumped by every repaint this element asks for that is *not* a pure pan
+     * — which is how the GL surface knows the graph it holds on the GPU is
+     * still the graph, and a frame is only a new offset. Errs one way on
+     * purpose: anything it cannot see is covered by the rest of the key
+     * (`glFrame`), and a rebuild too many costs a frame's packing, where one
+     * too few draws the wrong graph.
+     */
+    private _worldVersion;
+    /**
+     * The same for the nodes a drag is moving under GL, which are lifted out
+     * of the world for as long as it moves them (`_lifted`): a step changes
+     * them and nothing else, so it moves this and the world stays on the GPU.
+     * Rebuilding the world was the whole of a drag step's cost — 5-7 ms of
+     * scene and packing a step at 2,000 nodes, for one card.
+     */
+    private _liftVersion;
+    /** The lifted ids, for the drag gesture they were made for, and a count
+     *  of every change to them — the world's key, since the world is built
+     *  without them. */
+    private _liftSet;
+    private _liftFor;
+    private _liftGen;
+    /** Whether a marching edge is in the world, or in the lifted layer. */
+    private _worldAnimated;
+    private _liftedAnimated;
+    /** The last nodes commit changed lifted nodes and nothing else. */
+    private _liftOnly;
+    /** The overscan the GL world was culled to, in its own pinned
+     *  coordinates, and the key it was built under. */
+    private _worldCull;
+    private _worldCullId;
+    private _worldZoom;
+    /** When the zoom last moved, whether that move continued a stream of
+     *  them — a gesture, where one alone is a jump — and the timer that asks
+     *  for the frame that rebuilds the GL world once the stream stops. */
+    private _zoomAt;
+    private _zoomStream;
+    /** When the frame that drew the latest zoom step began, and when it last
+     *  finished a pass: an animation's next step follows the frame that drew
+     *  its last, however long that frame took (`_applyViewport`). */
+    private _zoomFrameAt;
+    private _zoomDrawnAt;
+    private _zoomRest;
+    /** A 2D paint drew labels scaled mid-zoom, and owes them at their own
+     *  sizes once it rests. */
+    private _textApproximated;
+    /**
+     * Mid-zoom on the 2D renderer: the graph and its ground as the gesture
+     * drew them once, on a surface of their own, composited scaled for every
+     * step after — the GL renderer's world drawn scaled, in a bitmap. A step
+     * used to stroke every edge, fill every card and lay the grid again, 20 ms
+     * of Direct2D a step over the stress lattice, for a picture the next step
+     * moved off. Dropped when the zoom rests, which paints it all again
+     * exactly, and whenever the graph itself changes.
+     */
+    private _zoomShot;
+    /** What the last `GRAPH_PAINTS_KEPT` whole paints of the graph cost, ms,
+     *  newest last: the steps of a zoom painted live and the pictures painted
+     *  for zooms, the two passes that say what a step would cost live — and
+     *  not a zoom's first step, which sets every label at its size once and
+     *  says what the steps after it will not. Whether a zoom is worth a
+     *  picture (`ZOOM_SHOT_WORTH_MS`); empty until a zoom has painted, so the
+     *  first one starts live. */
+    private _graphPaints;
+    /** A 2D drag's pictures (`_liftShotFor`), and the gesture that is not to
+     *  have any: one whose view moved under it, where a picture a step would
+     *  cost two full paints a step. */
+    private _liftShot;
+    private _liftShotRefused;
     /** Inside a live input dispatch — what makes a body emission `sync`.
      * Motion and the wheel run at continuous priority, whose React updates
      * can trail the pane's own painting by frames; an emission made under
      * this flag asks the receiver to commit before the dispatch returns. */
     private _gestureSync;
+    /** Inside a call through `FlowInstance` (`fromHandle`) — an application's
+     * handler, timer or animation loop moving the viewport. Its emissions ask
+     * to commit inline too. */
+    private _handleSync;
     /** The scene has been offered to assistive tech at least once — items
      * only exist once layout has placed them, which no commit marks. */
     private _sceneAnnounced;
@@ -96,7 +243,19 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
     private _themeString;
     private _textOptions;
     private _measure;
+    /** The same shaping, both dimensions: what a scene's label chips are
+     *  sized from. `_measure` answers a width because `measureNode` only ever
+     *  wanted one. */
+    private _measureBox;
+    /**
+     * The palette, resolved once for the theme and the `palette` prop it was
+     * resolved from. Every text measured asks for it (`_textOptions`), and
+     * resolving it tints the accent and reads the background's lightness out
+     * of a colour string: a 2D pan's passes measured their labels with a
+     * fresh one each. The theme object is replaced when it changes.
+     */
     private _palette;
+    private _paletteHeld;
     /**
      * Rebuild the node index when — and only when — one of its inputs changed
      * identity. Sizes come out of the font stack, so the face is an input too:
@@ -149,10 +308,16 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
      */
     private _nodeDamage;
     private _rebuildNodes;
+    /** The paint order: by `zIndex`, a selected node over the rest of its
+     *  layer, and declaration order breaking ties. */
+    private _sortOrder;
     private _rebuildEdges;
     /** who touches whom — what a moved node's damage has to include */
     private _rebuildAdjacency;
     private _viewport;
+    /** The viewport with the pane's window origin folded in — what every
+     *  graph-to-window conversion shared with `./scene.ts` takes. */
+    private _screenViewport;
     /**
      * Device pixels per logical pixel — the display scale this pane's window
      * resolved to (react-x11's docs/scale.md): `1` on an ordinary display,
@@ -181,6 +346,24 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
      * for goes through here; the full ones pass `abs`, which is device
      * already. */
     private _claim;
+    /** Whether the pane draws the minimap itself. On a canvas of its own —
+     *  under mounted bodies — it is `invalidate`'s to repaint. */
+    private _drawsMiniMap;
+    /**
+     * What moving or resizing `moves` changed in the minimap's corner, where
+     * the pane draws it: each node's place there before and after, while the
+     * fit is the one on screen — the graph's bounds with the viewport's,
+     * which put every node where it is there — and the whole corner when it
+     * is not, since every node moves in it then. A drag of one node among
+     * 2,000 claimed the corner on every step, and every such pass built and
+     * filled all 2,000 again, where it builds what it reaches now
+     * (`buildMiniMap`). Asked against the fit on screen rather than the one
+     * before the change, a step works the fit out once, and not at all when
+     * nothing moved on screen.
+     */
+    private _miniMapMoves;
+    /** A gesture's step, claimed in the minimap: `_miniMapMoves`. */
+    private _claimMiniMapMoves;
     /**
      * The pane proper: `abs` inset by border and padding, off core's own
      * resolved layout (react-x11#254) — so a `<Flow style={{ borderWidth: 1,
@@ -206,6 +389,38 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
      * resizable, because eight dots on every node is a graph nobody can
      * read. */
     private _grips;
+    /**
+     * One entry as `./scene.ts` takes it: the live gesture state resolved
+     * away, so everything past this point is pure. A drag's position and a
+     * resize's box are already in `rect`, and `grips` is already filtered by
+     * whatever the handles took.
+     *
+     * Built per call rather than cached: `rectOf` is what keeps a drag in step
+     * with the commit that has not landed yet, and a cache here is a cache of
+     * last frame's positions.
+     */
+    /** Whether a React body is mounted over this node — which is what makes
+     * its card draw a title bar rather than a centred label, and what
+     * `_emitBodies` reports a box for. */
+    private _mounted;
+    /**
+     * The frame being painted: each node's scene source, and the two lists a
+     * 2D pass builds its scene from. A frame paints its damage as several
+     * passes — a pan's strips, its pinned furniture, the corners of a rounded
+     * pane — and the scene cache culls the graph to the screen once for all
+     * of them (`SceneCache.edgesOnScreen`), keyed on these very lists, so
+     * every pass has to be handed the same ones. The passes run one after
+     * another in a single task, so a microtask queued by the first forgets
+     * the frame after the last — the same reasoning as `_reportFrame`.
+     */
+    private _frame;
+    private _paintedFrame;
+    private _sourceOf;
+    /** A 2D pass's node lists, the same arrays for every pass of a frame. */
+    private _frameLists;
+    private _source;
+    /** Not through `_source`: a source carries its grips, and `_grips` asks
+     *  where the handles are — the pair would recur. */
     private _handlesOf;
     /**
      * A node's box on screen, **on whole device pixels**.
@@ -233,28 +448,43 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
      * the shift exposed — which `paintDamage()` then hands to `paint`, so the
      * existing culling draws the sliver and nothing else.
      *
-     * The furniture — minimap, zoom controls — is pinned to the pane while
-     * its pixels would ride the blit, so its bands are carved out of the
-     * region that shifts and claimed as ordinary damage. The blit gate tests
-     * foreign claims against the *rect* (react-x11#309/#310), so a claim
-     * sitting edge to edge with it leaves the frame a blit: the middle of
-     * the pane is copied, the strips repaint with the new viewport, and the
-     * panels repaint in place.
+     * The furniture — minimap, zoom controls — stays put while the graph
+     * moves, so it is handed over as `pinned` (react-x11#682, 2.22): the
+     * whole pane is copied, and core repaints each panel and the image of
+     * it the copy dragged along, with the strips the shift exposed.
+     *
+     * Mounted node bodies ride it. They are laid out in one box beside the
+     * pane, which a pan moves by exactly the pan, so their pixels move with
+     * the pane's: the box goes to `scrollContents` as a rider
+     * (react-x11#671), its commit claims nothing, and what it leaves or
+     * reaches outside the rect is all it costs. `<Flow>` clips it to the pane for that. A body entering or
+     * leaving the pane, or changing as it goes, claims inside the rect and
+     * declines that frame's blit; the next one blits again.
      *
      * Still a full repaint when:
      *  - the zoom moved (scaling is not a blit) or the shift is fractional on
      *    the device grid — every real pan gesture is whole device pixels;
-     *  - mounted node bodies exist: they are core-owned siblings whose
-     *    gesture-time commits claim *inside* the rect every step, which
-     *    declines the blit anyway — bailing early skips the churn;
-     *  - the furniture bands would eat the pane (a tiny pane, or panels on
-     *    both the top and the bottom of a short one).
+     *  - bodies are mounted and `<Flow>` has not handed their box over;
+     *  - the pane is too small to be worth it; and core falls back itself
+     *    when the repairs would repaint most of it.
      */
     private _blitPan;
     /** Zoom about a point that must not move — the pointer under a wheel, the
      * pane's centre for a keyboard zoom. */
     private _zoomAbout;
     private _fit;
+    /**
+     * `fn`, as a call through the handle. A programmatic pan — an animation
+     * loop stepping `setViewport` — moves the pane at once and the bodies'
+     * box through React, and on React's schedule the box caught up with the
+     * pane in jumps: several steps' worth in one commit, landing in a frame
+     * whose blit shifted by one. A rider that moves by more than the blit is
+     * a layout move, so that frame repainted the pane whole — a fifth of the
+     * frames of a pan over mounted bodies (`_blitPan`). Marked like a
+     * gesture's, the emission commits before the call returns, and the box
+     * moves by exactly the pan in the frame that blits it.
+     */
+    fromHandle<T>(fn: () => T): T;
     getViewport(): Viewport;
     setViewport(viewport: Partial<Viewport>): void;
     zoomIn(step?: number): void;
@@ -296,11 +526,14 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
      * the square root of the gap (see `paths.ts`) — `8` where the shoulder
      * uses `6.25`, so the bound is generous rather than tight.
      */
+    /** The coarse box with the label's plate in it: what an edge that
+     *  changes has to claim, where its route alone would leave a plate's
+     *  ends. */
+    private _edgeInkBox;
     private _edgeCoarseBox;
     /** The drawn handle, in screen pixels. Capped as well as floored: a dot
      * that scaled all the way up would be a saucer at 2.5×, and the thing it
      * marks — a point on the border — does not get bigger. */
-    private _handleRadius;
     private _connectable;
     private _draggable;
     /** Pick the handle an edge attaches to: the one it names, else the only
@@ -310,7 +543,6 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
      * Null when either end is missing — an edge to a node that was removed is
      * a normal state during an edit, not an error. */
     private _edgeGeometry;
-    private _centre;
     private _corner;
     private _controlsOptions;
     private _controlButtons;
@@ -319,13 +551,22 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
      * is no minimap or nothing to put in it. */
     private _miniMap;
     private _miniToGraph;
-    private _miniToScreen;
     defaultMouseDown(ev: MouseEvent): void;
     defaultMouseDrag(ev: MouseEvent): void;
     private _dragDispatch;
     defaultMouseUp(ev: MouseEvent): void;
     defaultContextMenu(ev: MouseEvent): void;
     private _clickNode;
+    /**
+     * The nodes a drag is moving, once it has moved them: lifted out of the
+     * rest of the graph for the rest of the gesture. Under GL the world is
+     * built without them and they are a layer of their own (`glFrame`), so
+     * each step packs them and their edges and leaves the world on the GPU;
+     * in 2D the rest is two pictures a step copies from (`_liftShotFor`).
+     * Null otherwise — and under GL the change back is a change of the
+     * world's key, which rebuilds it with them in.
+     */
+    private _lifted;
     private _dragStep;
     /** The box a resize is making, reported as it goes. A grip that moves the
      * top or the left edge moves the node too, so both changes go out — an
@@ -336,6 +577,28 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
      * the damage it has to claim, so the two cannot disagree. */
     private _connectionPath;
     private _validConnection;
+    /**
+     * What one step of a box selection changes on screen: a band round each
+     * side of the box that moved, across the whole of both boxes. That covers
+     * the outline where it was and where it is, and the tint where one box
+     * lies over the graph and the other does not; a side that held still —
+     * the two the gesture is anchored by — changed only where a moving side
+     * shortened or lengthened it, which that side's band covers. Claiming the
+     * box round both repainted everything under the selection, every node and
+     * edge in it, on every step: 21 ms of a step on the stress example's
+     * fan-out, which is what made a sweep lag the pointer.
+     *
+     * The bands are cut on the device grid so that none of them overlaps
+     * another: core merges overlapping damage into the box round it, which is
+     * the whole selection again — and a pass over a translucent tint must not
+     * paint it twice. Claimed past this element's own `invalidate`, whose one
+     * job here would be to repaint the minimap and the controls on their
+     * canvases, and a box selection moves nothing on either.
+     *
+     * Under GL the box is the overlay's, drawn every frame: a step is a frame
+     * and not a change to the world, which a claim would have rebuilt.
+     */
+    private _claimSelectStep;
     private _selectBox;
     /** Wheel: zoom about the pointer, or pan when zooming is off. The seam
      * runs it after the app's own `onWheel` and not at all if that vetoed;
@@ -382,79 +645,365 @@ export declare class FlowGraphNode extends Node implements FlowInstance {
     private _stopAnimation;
     paint(ctx: Context2D): void;
     /**
-     * Where every mounted node body belongs, relative to the pane's own
-     * top-left. Sent only when the list changed, so a repaint that moved
-     * nothing does not re-render React — but a pan does, once per frame,
-     * which is the cost `render` is documented to carry.
+     * Everything `buildScene` reads, gathered from the element once.
+     *
+     * The two node lists differ on purpose: `nodes` is the paint order with a
+     * dragged node lifted to the top, and `all` is every node, because the
+     * minimap summarises the graph rather than the pass.
+     */
+    invalidate(layout?: boolean, damage?: Parameters<Node['invalidate']>[1], reason?: string): void;
+    /** A 2D frame's cost so far, while its flush is still painting passes. */
+    private _frameCost;
+    /**
+     * One `onFrame` per window flush, however many damage passes it painted.
+     * The window paints its passes one after another in a single task, so a
+     * microtask queued by the first runs after the last — and reports the
+     * frame whole, which is what a frame rate counts.
+     */
+    private _reportFrame;
+    private get _gl();
+    /** What the GL renderer's label atlas sets strings with: this pane's app,
+     *  for its staging surface, and the options its 2D painter measures with
+     *  — so a label is cut and placed the same on both renderers. Null where
+     *  there is no text engine to ask. */
+    glText(): {
+        app: unknown;
+        options: PainterOptions;
+    } | null;
+    /**
+     * The GL surface's hook: how it asks for frames. Set while a surface draws
+     * this pane, cleared when it goes — and until it is set the pane draws
+     * itself, so a surface that is still loading shows the 2D graph rather
+     * than an empty box.
+     */
+    setGlRequest(request: (() => void) | null): void;
+    /**
+     * One GL frame's worth of scene, in the two layers the renderer keeps
+     * apart (`./gl/renderer.ts`): the **world**, rebuilt only when it changed
+     * since the key the surface last drew, and the **overlay**, every frame.
+     *
+     * The world is built at a pinned origin and culled to an *overscan* — the
+     * view grown by a pane in every direction — so a pan inside it changes
+     * nothing but `offset`. When the view leaves the overscan, or the zoom
+     * moves, the overscan is re-centred and the world rebuilt; at every other
+     * frame of a pan the world comes back `null` and the renderer draws the
+     * buffers already on the GPU.
+     *
+     * A zoom *gesture* is drawn the same way: while the zoom keeps moving,
+     * each step draws the world on the GPU magnified by `zoom` — the view's
+     * zoom over the one it was built at — and the world is rebuilt at the
+     * zoom the gesture stopped at, `GL_ZOOM_REST_MS` after its last step.
+     * Rebuilding every step was the whole of a zoom's cost: a scene built,
+     * packed and uploaded per step, 19 ms of it on a 300-node graph, where a
+     * pan step is a uniform. What a magnified world gets wrong until then is
+     * what a zoom does not scale linearly — a label's raster, the hairlines
+     * with a floor of a pixel, the detail that appears past a zoom — which is
+     * what every map does during a pinch. A single jump — a control's button,
+     * `fitView`, `setViewport` — is not a stream and rebuilds at once, and so
+     * does a step that would magnify one build by more than `GL_ZOOM_SPAN`
+     * or show more of the graph than the overscan holds.
+     *
+     * The key is everything the world is a function of that this element can
+     * name: its version (every repaint but a view change moves it), the
+     * overscan, the zoom it was built at, and the palette and face — the two
+     * a theme change moves, which core announces to the window rather than
+     * to this element.
+     *
+     * Everything a 2D paint does around its drawing happens here too: the
+     * pending fit, the dash timer, the first scene announcement, the bodies.
+     */
+    glFrame(lastKey: string | null, lastLifted?: string | null): {
+        world: FlowScene | null;
+        key: string;
+        lifted: FlowScene | null | undefined;
+        liftedKey: string | null;
+        offset: XYPosition;
+        zoom: number;
+        overlay: FlowScene;
+        phase: number;
+        moving: boolean;
+    } | null;
+    /** The frame that rebuilds the GL world once a zoom gesture stops — asked
+     *  for `GL_ZOOM_REST_MS` after its last step, however many steps the
+     *  timer outlived. */
+    private _restZoom;
+    /** A whole paint of the graph took `ms` (`_graphPaints`). */
+    private _noteGraphPaint;
+    /** The median of the graph's last whole paints — the lower of the two
+     *  middle ones for an even count — or zero before the first. */
+    private _graphPaintMs;
+    /** Whether a pass over `clip` painted the whole pane — what a zoom step
+     *  paints, and the only pass whose cost says what one would. */
+    /** Whether a pass (`paintDamage()`, device pixels) repaints every pixel
+     *  of the pane, unlike {@link _wholePane}'s nine tenths. */
+    private _coversPane;
+    private _wholePane;
+    /**
+     * The graph painted once onto a surface of its own for the zoom gesture
+     * under way — made at the gesture's first step that finds none — or null
+     * where there is no surface to paint on.
+     */
+    private _zoomShotFor;
+    /** Where the gesture's picture lands at the viewport of the moment, in
+     *  the pane's logical pixels: a world point drawn at `w·z₀ + v₀` is at
+     *  `w·z + v`, so the picture is scaled by `z / z₀` about the pane's corner
+     *  and moved by `v − v₀·z/z₀`. */
+    private _shotRect;
+    private _compositeShot;
+    /**
+     * The pane this pass reaches that the gesture's picture does not: nothing
+     * while zooming in about a point in the pane, a ring round it zooming out,
+     * a side after a pan. Up to four bands — above, below, and either side
+     * between them — each reaching a pixel under the picture's edge, which
+     * its filtering leaves half there.
+     */
+    private _uncovered;
+    private _dropZoomShot;
+    /**
+     * The pictures a 2D drag copies from — made on the first pass of the
+     * gesture that has its nodes lifted, and kept while the graph under them
+     * and the view hold still. A drag step repainted the box round the moved
+     * node and every edge on it, and an edge is as long as it is: the stress
+     * lattice sends its last rows' edges back to its first nodes, so dragging
+     * one repainted the window a step, every card and edge in it, at 46-57
+     * fps on Cocoa. Cutting the damage finer did not help — core merges a
+     * frame's rects down to four, and a long diagonal's pieces merge back to
+     * most of the pane. Copying what did not move is what does.
+     *
+     * Null where there is no offscreen surface, and for a gesture whose view
+     * moved while it held pictures: it paints live from then on, rather than
+     * paint the graph twice a step.
+     */
+    private _liftShotFor;
+    /**
+     * One of a drag's pictures, copied into this pass's rect of the pane —
+     * the whole pane on a full pass. The ground's picture is opaque and is
+     * *copied*, which the server does as a copy rather than a blend (`copy`
+     * is XRender's `Src`, and a memcpy on Cocoa); the cards' picture is
+     * blended in only where a card is (`only`). On XQuartz the two blends of
+     * the step's box — as big as the moved node's longest edge — were most
+     * of what a drag cost the server.
+     */
+    private _compositeLift;
+    /** A rect of the pane, logical pixels, drawn from the same rect of a
+     *  picture of it — on whole device pixels, so nothing is resampled. */
+    private _copyShotRect;
+    private _dropLiftShot;
+    /** Whether a zoom gesture is moving: a stream of zoom steps, the last of
+     *  them under `GL_ZOOM_REST_MS` ago. A single step — a button, `fitView`,
+     *  an app's `setViewport` — is not one. */
+    private _zoomMoving;
+    /** Whether this pass's damage reaches the minimap's corner at all —
+     *  answered from the panel's box alone, without resolving the map. */
+    private _miniMapReached;
+    /** The minimap's panel, in logical window pixels, or null without one. */
+    private _miniMapCorner;
+    /**
+     * Everything `buildScene` reads, for one of three uses:
+     *
+     * - `'all'` — the 2D renderer's pass: the pane as it is, culled to this
+     *   pass's damage.
+     * - `{ world }` — the GL graph: built at a **pinned origin** (the viewport's
+     *   translation and the pane's origin both left out, so a pan does not
+     *   change a vertex) and culled to the overscan `world` rather than the
+     *   pane, with none of the pane's furniture.
+     * - `'overlay'` — the GL furniture: the pane's background, grid, selection,
+     *   minimap and controls, and no graph at all.
+     */
+    /**
+     * The order nodes are drawn in, bottom to top: `zIndex`, then selection,
+     * then declaration (`_order`), with a node being dragged lifted over all
+     * of them. The one order both halves of a node follow — its card in the
+     * scene, its mounted body in `_emitBodies` — so a body is stacked over
+     * the bodies of the cards under its own, and under the ones above.
+     */
+    private _paintOrder;
+    private _sceneInput;
+    /**
+     * Where every mounted node body belongs, and where the graph's origin is.
+     *
+     * The two are sent apart because they change apart. A body's rect is
+     * relative to the **graph's origin on screen** — its position times the
+     * zoom — which a pan does not move; the origin is the viewport's
+     * translation, which is all a pan moves. So a pan re-sends the *same*
+     * bodies array with a new origin, `<Flow>` moves the one box they are
+     * laid out in, and React re-renders none of them: the per-step commit of
+     * every mounted body's position is what held a pan over 48 of them to 57
+     * frames a second. A drag, a zoom, a selection or a body entering the pane
+     * sends a new array, as before.
      */
     private _emitBodies;
-    /** The grid, drawn only inside `region` — the pass's damage on a partial
-     * repaint, the pane on a full one. Alignment stays anchored to the
-     * viewport origin, so the region never changes where a dot falls. */
-    private _paintGrid;
+    /**
+     * Whether mounted bodies sit this zoom out.
+     *
+     * A zoom changes every body's scale, and a scale is not a transform: each
+     * body is styled, laid out, its text shaped and its pixels painted again,
+     * at the new size, per step. That is about a millisecond a body on this
+     * class of machine — 42 bodies held a zoom to 15 frames a second where
+     * the graph alone costs 13 ms a step. So each step of a zoom *gesture*
+     * predicts what re-scaling the bodies on screen would add, and when that
+     * is over `BODY_BUDGET_MS` they sit the gesture out: still mounted — no
+     * state is lost — but hidden (`display: 'none'`) and untouched, while the
+     * cards, their labels and the edges carry it. Once the zoom has held still
+     * for
+     * `BODY_ZOOM_REST_MS` they come back, laid out once at the new scale. A
+     * handful of bodies fits the budget and zooms live.
+     *
+     * The prediction is bodies × what one costs, measured from the pane's own
+     * frames (`_frameTick`) — so a slower machine holds sooner. Once held, a
+     * gesture stays held until it rests: bodies blinking in and out as the
+     * count crosses the line would be worse than either.
+     *
+     * Only a stream counts: a gesture's steps — the wheel, a pinch, the keys
+     * (`_gestureSync`) — or an animation's, `setViewport` a frame at a time,
+     * each zoom under `GL_ZOOM_REST_MS` after the one before (`_zoomStream`,
+     * the rule the zoom's picture and its scaled labels already follow). A
+     * single programmatic jump — `fitView`, `setViewport`, a control's button
+     * — applies at once, so an app that sets the viewport and reads the result
+     * sees it; the pane never animates a viewport of its own. An animation
+     * that stepped every body at every frame held a zoom over the stress
+     * example's charts to 10 frames a second.
+     */
+    private _holdBodies;
+    /** Bring the held bodies back once the zoom has held still for
+     *  `BODY_ZOOM_REST_MS` — judged on the pane's clock, like the zoom's own
+     *  rest (`_restZoom`): a timer that comes due while steps are still
+     *  arriving waits out what is left of the rest instead. */
+    private _restBodies;
+    /**
+     * What the bodies' rest is counted from: the last step of the zoom, or
+     * the frame that drew it where that came later. A step the window has not
+     * drawn yet is a zoom still moving — the frame is late, not the gesture
+     * over — and counted from the step alone, a frame a server took half a
+     * second to answer brought the bodies back between two steps of one
+     * animation, whose next frame re-scaled all of them and was late in turn.
+     * Past `BODY_REST_CAP_MS` without that frame they come back anyway: a
+     * surface that stopped drawing must not keep them out for good.
+     */
+    private _restFrom;
+    /**
+     * Paint one mounted node's card — fill, border, header, handles, grips —
+     * into `ctx`, a `<canvas>` in the bodies' layer (`<Flow>`), exactly as the
+     * scene paints it. `ctx` is at the canvas's origin, `abs` its place in
+     * the window in device pixels.
+     *
+     * Why the card is painted twice: the bodies share one layer over every
+     * card — over the GL surface, or beside the 2D pane — so a body could not
+     * go under a card that was over its own. It painted over that card's
+     * header, border and handles: a selected node's outline hidden behind the
+     * body of the node under it. A card painted in the bodies' layer, just
+     * under its own body, is stacked with it in the cards' paint order, and
+     * covers the card the graph drew for it.
+     */
+    paintCard(id: string, ctx: unknown, abs: XYPosition): void;
+    /**
+     * Whether a card is the bodies' layer's to draw and not the pane's: on
+     * the 2D renderer, shown there and the bodies not held out of a zoom.
+     *
+     * **Never under GL.** The layer and the GL frame reach the screen by two
+     * paths — the layer is the surface's overlay, painted and presented with
+     * the window's frame, and a GL frame is swapped on the surface's own
+     * turn — and this element cannot order them. So a card left to the layer
+     * was, on some path, a card nobody drew: edges crossing the empty place
+     * where it should be. The first paint of a scene of charts did that until
+     * the layer had painted; a GL frame landing between a zoom's hold and the
+     * commit that hid the bodies did it; and on macOS a wheel notch did it,
+     * painting the overlay inside its own dispatch 20–25 ms before the GL
+     * frame it asked for — a frame of bare edges at the start of every zoom
+     * that held the bodies. Each was fixed by ordering one more path.
+     *
+     * The world draws every card instead, mounted or not, and the layer only
+     * ever adds to it: its card and body land on the world's copy of that
+     * card. Whatever order the two paths take, the worst the screen can show
+     * is a body a frame early or late, over a card that is there. What it
+     * costs is a few dozen cards more in a world build, drawn under their
+     * copies. The 2D pane is painted in the same pass as the layer, in one
+     * frame, and it leaves them out.
+     */
+    private _cardInLayer;
+    /**
+     * The cards `<Flow>` has on screen in the bodies' layer (`paintCard`),
+     * which the 2D pane then leaves out. Told after the commit that shows
+     * them, so no 2D frame lacks both; told the empty set while bodies are
+     * held out of a zoom, when their cards are the pane's again. Under GL it
+     * changes nothing drawn: the world draws every card (`_cardInLayer`).
+     */
+    setShownBodies(ids: ReadonlySet<string>): void;
+    /**
+     * The canvases `<Flow>` paints the minimap and controls on, over its
+     * bodies (`paintPanels`): the bodies' layer is over the graph, so panels
+     * the graph drew went under any card that reached them. While there are
+     * any the graph leaves the panels out, and every change to the pane asks
+     * them to repaint. Presses still land on the pane: the canvases take
+     * none.
+     */
+    /** The panel canvases the minimap is painted on — the ones whose box
+     *  reaches its corner. */
+    private _miniMapCanvases;
+    /**
+     * The box `<Flow>` lays the node bodies out in, beside this pane, under
+     * the 2D renderer — null under GL, and with no bodies to lay out. A pan
+     * hands it to `scrollContents` as a rider: its pixels move with the
+     * pane's.
+     */
+    setBodiesLayer(layer: unknown): void;
+    setPanelCanvases(canvases: readonly PanelCanvas[]): void;
+    /** Where the minimap and the controls are, relative to the pane's
+     *  top-left, logical — with a pixel round for their borders. */
+    panelRects(): FlowRect[];
+    /** Paint the minimap and the controls into `ctx`, a canvas whose place in
+     *  the window, in device pixels, is `abs` — as the scene paints them. */
+    paintPanels(ctx: unknown, abs: FlowRect): void;
+    /** Tell `<Flow>` where the panels are when that changed (`onPanels`). */
+    private _emitPanels;
+    /** `adaptive` as a number of milliseconds: `Infinity` never holds. */
+    private _budgetMs;
+    /** Where the mounted bodies stand against the budget — reported with
+     *  every frame (`FlowFrameStats.bodies`). */
+    bodyBudget(): FlowBodyBudget;
+    /**
+     * A frame was drawn: time the zoom step it carried, into the model
+     * `_holdBodies` predicts from. A step with no body re-scaled is the
+     * baseline; one that re-scaled some says what each cost over it. Passes
+     * a millisecond or two apart are one frame (the 2D renderer paints a
+     * frame's damage as several), and a gap long enough to be the user
+     * pausing is not a step at all.
+     */
+    private _frameTick;
     /**
      * The grid as one repeating fill (ntk#263): a step-sized tile drawn once,
      * a `createPattern('repeat')` over it, and one composite for the whole
-     * region — where the runs path pays a region-sized coverage mask.
+     * region — where the runs path in `./paint.ts` pays a region-sized
+     * coverage mask.
      *
-     * Two decisions with reasons:
+     * Handed to `paintScene` as its grid painter, and answering **false** when
+     * it does not apply, so the universal path takes over. Two decisions with
+     * reasons:
      *
      * - **Integral device steps only.** The tile is a pixmap, so its size is
-     *   whole pixels; at a fractional step the pattern would drift against
-     *   the graph's own coordinates — against `snapToGrid`, against node
-     *   positions — by a fraction per tile, and a grid that slides under the
-     *   content it grids is worse than a slower exact one.
+     *   whole pixels; at a fractional step the pattern would drift against the
+     *   graph's own coordinates — against `snapToGrid`, against node positions
+     *   — by a fraction per tile, and a grid that slides under the content it
+     *   grids is worse than a slower exact one.
      * - **The phase lives in the tile, not in a picture transform.** An
      *   untransformed repeat is anchored to the window origin, so the grid's
      *   alignment is baked in by drawing the mark at `origin mod tile` — and
      *   re-baking when the origin moves. A `setTransform` translate says the
      *   same thing in one request, but a *transformed* repeat forfeits the
-     *   server's untransformed fast path — on the in-process test server
-     *   that was ~180 ms a frame of per-pixel arithmetic, and re-rendering a
-     *   24px tile is a handful of requests on any server.
+     *   server's untransformed fast path — on the in-process test server that
+     *   was ~180 ms a frame of per-pixel arithmetic, and re-rendering a 24px
+     *   tile is a handful of requests on any server.
+     *
+     * An arrow property rather than a method: it is passed as a value, and a
+     * method would arrive with no `this`.
      */
-    private _paintGridPattern;
+    private _grid;
     private _makeGridSurface;
     /** Draw one grid cell with the mark at the phase point, wrapped — a mark
      * near an edge is drawn again a tile over, so the seam never cuts it.
      * Device pixels throughout: `unit` is how many of them a graph unit is. */
     private _renderGridTile;
     private _dropGridTile;
-    /** Draws every visible edge; answers whether any of them is animated, so
-     * the caller knows whether to keep a timer alive. */
-    private _paintEdges;
-    /** An arrowhead's three or four points, added to the pile for its colour
-     * rather than drawn — see {@link StrokeBuckets} for why. */
-    private _collectMarker;
-    private _paintNodes;
-    private _paintNode;
-    private _mounted;
-    private _paintGrips;
-    /** The built-in node: a card with a label, an optional second line and an
-     * optional accent stripe down its leading edge. */
-    /** The card itself: one rounded box, and the accent stripe if it has one.
-     * With a `batch` the box joins the pile for its appearance instead of
-     * being drawn on its own. */
-    private _paintCardShape;
-    /** The label and its second line — the half of a card that has to come
-     * after every card when they are batched. */
-    private _paintCardInk;
-    /**
-     * Handles are drawn one disc at a time, and that is the measured answer
-     * rather than the obvious one.
-     *
-     * Batching them into a single path halved the requests and made the frame
-     * *slower*: a path's mask is its bounding box, so forty dots scattered
-     * across the pane rasterize to a paneful of mask — three quarters of a
-     * megabyte — where forty small ones cost a kilobyte each. Batching pays
-     * for the edges because an edge already spans that box; it does not pay
-     * for anything small and scattered.
-     */
-    private _paintHandles;
-    private _paintConnection;
-    private _paintSelectionBox;
-    private _paintMiniMap;
-    private _paintControls;
 }
 export {};
 //# sourceMappingURL=node.d.ts.map