@ai-gui/plugin-bigscreen 0.36.3 → 0.37.0

package/dist/index.d.cts

@@ -79,7 +79,92 @@ interface GlobePanel extends PanelBase {
   }>;
   rotate?: boolean;
 }
-type Panel = KpiPanel | GaugePanel | RankPanel | ChartPanel | Chart3dPanel | GlobePanel;
+/** One swim-lane of a timeline: a source, an outlet, a system — whatever the rows stand for. */
+interface TimelineLane {
+  id: string;
+  /** The name written down the left. At most 40 characters. */
+  name: string;
+  /** The lane's colour, as a hex string. Default: from the palette, by lane order. */
+  color?: string;
+}
+/** One point on a timeline. `id` is only needed for a lane an item is linked from or to. */
+interface TimelineItem {
+  id?: string;
+  /** The `id` of the lane the point sits on. */
+  lane: string;
+  /** When it happened, as ISO 8601. */
+  at: string;
+  /** The one line beside the point. At most 120 characters. */
+  label: string;
+  /** What the tooltip adds. At most 400 characters. */
+  detail?: string;
+  /** Opened on click, unless the host took the click. `http` or `https` only. */
+  url?: string;
+  /** How big the point is drawn, relative to the other points. */
+  value?: number;
+}
+/**
+ * A line drawn between two points.
+ *
+ * `contradicts` is the one this panel exists for: two claims that cannot both be true, drawn in
+ * the palette's danger red across the lanes that made them.
+ */
+interface TimelineLink {
+  from: string;
+  to: string;
+  /** Default `follows`. */
+  kind?: "contradicts" | "follows" | "same";
+}
+/** Lanes down the side, time across, one point per thing that happened, links between them. */
+interface TimelinePanel extends PanelBase {
+  kind: "timeline";
+  lanes: TimelineLane[];
+  items: TimelineItem[];
+  links?: TimelineLink[];
+  /** The window drawn, as ISO 8601. Default: the items' own range with 5% on each side. */
+  from?: string;
+  to?: string;
+}
+/** One entity in a knowledge graph. */
+interface Graph3dNode {
+  id: string;
+  /** At most 80 characters. */
+  name: string;
+  /** What kind of thing it is; the colour follows from this. At most 32 characters. */
+  type?: string;
+  /** How big it is drawn. Default: its degree. */
+  value?: number;
+}
+/** One typed edge. Both ends must be node ids. */
+interface Graph3dEdge {
+  from: string;
+  to: string;
+  /** At most 32 characters. */
+  type?: string;
+}
+/**
+ * Entities and typed edges as a knowledge graph.
+ *
+ * `orbit`, the default, is a real three-dimensional model: the entities are laid out in space by
+ * a spring-electrical simulation and the camera turns around them. `flat` is echarts-gl's own
+ * `graphGL` — force-atlas2 on the GPU, drawn on a plane with an orthographic camera — which draws
+ * more nodes at once and is the mode to reach for when a graph is big enough that the third
+ * dimension costs more than it shows.
+ */
+interface Graph3dPanel extends PanelBase {
+  kind: "graph3d";
+  nodes: Graph3dNode[];
+  edges: Graph3dEdge[];
+  /** Type name to hex colour, overriding the palette's own assignment. At most 32 entries. */
+  types?: Record<string, string>;
+  /** The id of the node to highlight and always label. */
+  focus?: string;
+  /** How it is drawn: a turning 3D model, or the flat GPU layout. Default "orbit". */
+  mode?: "orbit" | "flat";
+  /** Whether the graph moves at all — settling, and turning. Default true. */
+  rotate?: boolean;
+}
+type Panel = KpiPanel | GaugePanel | RankPanel | ChartPanel | Chart3dPanel | GlobePanel | TimelinePanel | Graph3dPanel;
 type PanelKind = Panel["kind"];
 interface ScreenDefinition {
   title?: string;
@@ -91,6 +176,82 @@ interface ScreenDefinition {
   columns: number;
   panels: Panel[];
 }
+/**
+ * The bit of GeoJSON a globe needs: WGS84 rings, in longitude/latitude order.
+ *
+ * Deliberately not the whole of RFC 7946. Only the two polygon geometries are drawn, and
+ * everything else on a feature is ignored, so a host can hand over `world-atlas` straight out of
+ * `topojson-client` without a type assertion and without this package taking a GeoJSON
+ * dependency.
+ */
+type GlobeGeometry = {
+  type: "Polygon";
+  coordinates: number[][][];
+} | {
+  type: "MultiPolygon";
+  coordinates: number[][][][];
+} | {
+  type: string;
+  coordinates?: unknown;
+};
+interface GlobeFeatureCollection {
+  type: "FeatureCollection";
+  features: Array<{
+    type?: string;
+    geometry?: GlobeGeometry | null;
+    properties?: Record<string, unknown> | null;
+  }>;
+}
+/**
+ * What the host wants the planet to look like.
+ *
+ * The fence says where the events are; this says what they are drawn on, and it is host
+ * configuration rather than a panel field on purpose: a texture is a URL, and a URL a model
+ * wrote is a request a page would be making on the model's say-so.
+ *
+ * Precedence is `baseTexture`, then `countries`, then the painted graticule the plugin has
+ * always drawn — so a host that sets none of this gets exactly the globe it got before.
+ */
+interface GlobeSkin {
+  /** An equirectangular (2:1) day texture, as a URL or a data URL the host serves itself. */
+  baseTexture?: string;
+  /** An equirectangular height map, for bump shading. Optional. */
+  heightTexture?: string;
+  /** Country outlines to rasterise onto a 2:1 canvas when there is no `baseTexture`. */
+  countries?: GlobeFeatureCollection;
+  /** Fill for land. Default: from the palette. */
+  land?: string;
+  /** Fill for sea. Default: from the palette. */
+  ocean?: string;
+  /** Stroke for country borders. Default: from the palette. */
+  border?: string;
+  /** How the sphere is lit. Default "lambert" once a skin is given. */
+  shading?: "color" | "lambert" | "realistic";
+  /** The glow around the rim. Default true. */
+  atmosphere?: boolean;
+  /**
+   * The sun.
+   *
+   * `time` is what echarts-gl puts the main light at, so the terminator falls where the sun
+   * actually is; the default is now.
+   */
+  light?: {
+    intensity?: number;
+    time?: Date | string;
+  };
+}
+/**
+ * What the host wants to happen when a reader clicks something.
+ *
+ * A timeline item carries a `url`, and without a handler the plugin opens it in a new tab. A host
+ * that has its own idea of what a claim is — a drawer, a route, a second panel — passes
+ * `onItemClick` and takes the click instead, `url` and all. There is no default for a graph node:
+ * a node is not a link, so a host that wants a click to mean something has to say so.
+ */
+interface BigscreenEvents {
+  onItemClick?: (item: TimelineItem) => void;
+  onNodeClick?: (node: Graph3dNode) => void;
+}
 interface BigscreenOptions {
   /** Refuse a screen with more panels than this. Default 24. */
   maxPanels?: number;
@@ -100,6 +261,10 @@ interface BigscreenOptions {
   animate?: boolean;
   /** Host override for the palette; a screen's own `theme` wins when set in the fence. */
   theme?: ScreenTheme;
+  /** Host override for what a globe panel's planet looks like. Unset draws the graticule. */
+  globe?: GlobeSkin;
+  /** What a click on a timeline item or a graph node does. */
+  events?: BigscreenEvents;
 }
 interface BigscreenError {
   code: "invalid-json" | "invalid-definition" | "too-large";
@@ -129,6 +294,31 @@ declare function bigscreenPromptSpec(locale?: string): string;
 
 //#endregion
 //#region src/parse.d.ts
+/**
+ * Every limit the parser enforces, named.
+ *
+ * Exported because a limit the parser checks and nothing states is a trap: the prompt spec has to
+ * name the same numbers, and a host building a fence of its own needs to know where the cliff is.
+ * Overrunning any of them voids the whole block, so they are all deliberately generous — generous
+ * enough that the biggest of them are not reachable under the default 64 KiB source cap: five
+ * thousand edges is around a hundred kilobytes of JSON, so a host that really wants a graph that
+ * size has to raise `maxSourceBytes` as well.
+ */
+declare const MAX_POINTS = 5000;
+declare const MAX_ITEMS = 50;
+declare const MAX_ARCS = 300;
+declare const MAX_LANES = 24;
+declare const MAX_TIMELINE_ITEMS = 500;
+declare const MAX_LINKS = 500;
+declare const MAX_NODES = 2000;
+declare const MAX_EDGES = 5000;
+declare const MAX_TYPES = 32;
+declare const MAX_LANE_NAME = 40;
+declare const MAX_ITEM_LABEL = 120;
+declare const MAX_ITEM_DETAIL = 400;
+declare const MAX_URL = 400;
+declare const MAX_NODE_NAME = 80;
+declare const MAX_TYPE_NAME = 32;
 /** Validate one `bigscreen` fence, or explain why it cannot be shown. */
 declare function parseBigscreen(source: string, options?: {
   maxPanels?: number;
@@ -182,10 +372,447 @@ declare function chart3dOption(panel: Chart3dPanel, c: Palette, animate: boolean
  *
  * ECharts' globe wants a texture, and the usual one is an image fetched from somewhere — which a
  * page must not do on a model's say-so. So the texture is painted here: a deep sphere with a
- * graticule, which is what a data wall's globe looks like anyway. Arcs get a moving trail.
+ * graticule, which is what a data wall's globe looks like anyway. A host that wants a real earth
+ * says so in `BigscreenOptions.globe` and `earth.ts` takes over; this stays the fallback.
+ */
+declare function globeTexture(c: Palette, theme: "dark" | "light"): string | undefined;
+/**
+ * The sphere itself, with and without a host-supplied earth.
+ *
+ * Without one, everything below the `skin` branch is the globe this plugin has always drawn: a
+ * flat-lit ball with a graticule on it, every point labelled. A wire grid needs no sun — there is
+ * nothing on it a shadow would tell you about — and `shading: "color"` with the light turned down
+ * is what keeps it evenly readable while it turns.
+ *
+ * With one, the ball is a planet: lambert (or the host's choice) so the terminator falls where the
+ * sun actually is, an atmosphere at the rim, and labels only on the points worth reading from
+ * across a room. `postEffect` stays off — bloom and depth of field on one of six panels is a
+ * frame budget spent on the wrong thing.
  */
+declare function globeOption(panel: GlobePanel, c: Palette, animate: boolean, texture: string | undefined, skin?: GlobeSkin): EChartsCoreOption;
 
-declare function globeOption(panel: GlobePanel, c: Palette, animate: boolean, texture: string | undefined): EChartsCoreOption;
+//#endregion
+//#region src/earth.d.ts
+/** The three colours a painted world is made of, defaulted from the screen's palette. */
+interface EarthColours {
+  ocean: string;
+  land: string;
+  border: string;
+}
+declare function earthColours(c: Palette, theme: ScreenTheme, skin?: GlobeSkin): EarthColours;
+/**
+ * Rasterise a world onto a 2:1 canvas and hand it over as a data URL.
+ *
+ * A data URL rather than the canvas element: that is the path echarts-gl treats as an image to
+ * decode, and it involves no request. A canvas element handed to `baseTexture` is a white ball.
+ *
+ * Rings are filled even-odd so that a country drawn as an outer ring plus holes — Lesotho inside
+ * South Africa, the lakes inside Canada — comes out with the holes in it whichever way round the
+ * source wound them.
+ */
+declare function countriesTexture(countries: GlobeFeatureCollection, colours: EarthColours): string | undefined;
+/**
+ * The texture a globe panel wears, by the host's precedence.
+ *
+ * `baseTexture` wins because a host that has a photograph has already decided; `countries` is
+ * next because outlines a host bundled are still the host's map; and with neither there is the
+ * graticule, which is what this plugin has always drawn and what every consumer that never heard
+ * of a `globe` option keeps getting.
+ */
+declare function earthTexture(c: Palette, theme: ScreenTheme, skin?: GlobeSkin): string | undefined;
+
+//#endregion
+//#region src/timeline.d.ts
+/**
+ * A timeline of claims, one lane per source.
+ *
+ * The panel exists for the line nobody else draws: two outlets said things that cannot both be
+ * true, and the red segment between their two points is the whole point of the picture. So the
+ * lanes stay in the order they were given (a reader compares row against row, and a chart that
+ * reorders them silently answers a different question), time runs across, and every claim is one
+ * point that can be clicked back to the page it came from.
+ *
+ * Pure: the option is a function of the panel and the palette, so it can be tested without a
+ * canvas and so the same claims draw the same picture on every screen.
+ */
+/** How many claims carry a written label; the rest are on the tooltip. */
+declare const TIMELINE_LABELS = 12;
+/**
+ * The window drawn, in epoch milliseconds.
+ *
+ * The panel's own `from` and `to` win where they are given. Otherwise it is the claims' own range
+ * with 5% on each side, because a point exactly on the axis reads as clipped rather than as first.
+ * A single claim has no range to take a fraction of, so it gets an hour either way — enough for
+ * the point to sit somewhere rather than in the middle of nothing.
+ */
+declare function timelineWindow(panel: TimelinePanel): [number, number];
+/**
+ * Which claims have room for a label, as indexes into `panel.items`.
+ *
+ * A label is drawn beside its point, on its own lane, so what decides whether it can be read is
+ * the empty time on either side of it within that lane — not how important the claim is and not
+ * what order it was written in. Twelve labels on a wall panel is about where a reader stops
+ * reading them anyway, and the rest are one hover away.
+ */
+declare function spacedItems(panel: TimelinePanel, max?: number): Set<number>;
+/**
+ * How tall a timeline of this many lanes has to be.
+ *
+ * 320 is the default panel, and it holds a handful of lanes comfortably. Past that the lanes get
+ * a floor of 28 pixels each: below that the points of two neighbouring outlets touch, and a
+ * contradiction drawn between them stops being a line between two rows.
+ */
+declare function timelineHeight(lanes: number): number;
+declare function timelineOption(panel: TimelinePanel, c: Palette, animate: boolean): EChartsCoreOption;
+
+//#endregion
+//#region src/graph3d.d.ts
+/**
+ * The vocabulary every knowledge graph panel is drawn in, and the flat mode's own option.
+ *
+ * A type's colour, a node's degree, the legend in the corner and the tooltip are the same in both
+ * modes and live here. `orbit.ts` — the default — turns the entities into a model in space;
+ * `graph3dOption` below is `flat`, echarts-gl's `graphGL`: force-atlas2 on the GPU, drawn on a
+ * plane with an orthographic camera. It draws more nodes at once than the model does, which is
+ * the reason it is still here.
+ *
+ * Pure: the option is a function of the panel and the palette.
+ */
+/** How many entities carry a written label. The rest are one hover away. */
+declare const GRAPH_LABELS = 20;
+/**
+ * How the layout is run.
+ *
+ * `steps` is iterations per frame and `maxSteps` is where the layout stops. Settling takes
+ * `maxSteps / steps` frames — 125 of them, a shade over two seconds at sixty frames a second,
+ * which is long enough to watch a graph of five hundred entities pull itself apart and short
+ * enough that nobody waits for it. When nothing is meant to move, the same thousand iterations
+ * are spent four frames deep and the reader gets the settled graph instead of the settling.
+ *
+ * (echarts-gl 2.x bounds the layout with `maxSteps`; there is no convergence threshold to set.)
+ */
+declare const GRAPH_SETTLE_STEPS = 8;
+declare const GRAPH_MAX_STEPS = 1000;
+/** How many types the corner legend lists before it would start covering the graph. */
+declare const GRAPH_LEGEND_ROWS = 12;
+/**
+ * The colour of a type.
+ *
+ * Hashed rather than handed out in order of appearance, because two graph panels on one wall must
+ * colour `outlet` the same way, and the order the types happen to appear in is different in each
+ * of them. A hash means two types can land on the same colour, which is what the legend in the
+ * corner is for; a panel that cares says so in `types`.
+ *
+ * Only the first seven series colours are in the ring. The eighth is a second cyan a shade off
+ * the accent, and two types a reader cannot tell apart is worse than two types sharing a colour
+ * the legend admits to sharing.
+ *
+ * A node with no type gets the muted colour: it is not a category, so it does not get one of the
+ * colours the categories are being told apart by.
+ */
+declare function typeColour(type: string | undefined, c: Palette, overrides?: Record<string, string>): string;
+/** How many edges touch each node. Both ends count, so a self-edge counts twice. */
+declare function degrees(panel: Graph3dPanel): Map<string, number>;
+interface GraphLegendEntry {
+  label: string;
+  colour: string;
+  shape: "node" | "edge";
+}
+/**
+ * The key drawn in the panel's corner: every type that appears, once, in its own colour.
+ *
+ * Nodes first, then edges, each in the order it first appears — which is the order the model
+ * wrote them in, and therefore the order it was thinking in. An untyped graph gets no legend at
+ * all rather than an empty box.
+ */
+declare function graphLegend(panel: Graph3dPanel, c: Palette): GraphLegendEntry[];
+/**
+ * What an entity or an edge says on hover, in both modes.
+ *
+ * Escaped by hand: ECharts renders a formatter's return as HTML and every name here was written
+ * by a model. An edge is told apart by `dataType` in the flat series and by carrying its own
+ * `coords` in the orbit one, which is the only thing the two series disagree about.
+ */
+declare function graphTooltip(params: {
+  dataType?: string;
+  data?: unknown;
+}): string;
+/**
+ * The `flat` mode: `graphGL`, laid out by force-atlas2 on the GPU.
+ *
+ * Unchanged since it was written, byte for byte, and pinned by a test that says so — a panel that
+ * asked for this mode asked for exactly this picture. The 3D model is `graphOrbitOption`, which
+ * takes positions rather than computing them, because it is stepped in front of the reader.
+ */
+declare function graph3dOption(panel: Graph3dPanel, c: Palette, animate: boolean): EChartsCoreOption;
+
+//#endregion
+//#region src/layout3d.d.ts
+/**
+ * A spring–electrical layout in three dimensions.
+ *
+ * Fruchterman–Reingold's forces, one dimension further: every pair of entities pushes apart with
+ * `k²/d`, every edge pulls its ends together with `d²/k`, a weak spring holds the whole thing to
+ * the origin, and a falling temperature caps how far a node may move in one step so the graph
+ * cools into a shape instead of oscillating around one.
+ *
+ * Written here rather than taken from a dependency for two reasons. The panel needs positions in
+ * three dimensions and echarts-gl's own layouts are two-dimensional; and the layout has to be
+ * *steppable* — a few steps per animation frame — so the reader watches the graph pull itself
+ * apart rather than being handed a settled picture. A library that runs to convergence behind a
+ * promise cannot do that.
+ *
+ * Deterministic on purpose: the starting positions are a hash of the node ids on a sphere, so the
+ * same knowledge graph draws the same picture twice running, and a screenshot test means
+ * something. Nothing here calls `Math.random`.
+ *
+ * Complexity is O(n²) per step, which is why `layoutSteps` spends fewer steps on a bigger graph.
+ */
+/** The distance an edge settles at: the unit everything else here is measured in. */
+declare const LAYOUT_SPRING = 1;
+/**
+ * The pull to the origin, per unit of distance from it.
+ *
+ * Without it a knowledge graph with two unconnected components is unbounded: nothing attracts
+ * them to each other, the repulsion between them is never opposed, and one of them leaves the
+ * panel and keeps going.
+ */
+declare const LAYOUT_GRAVITY = 0.08;
+/**
+ * FNV-1a.
+ *
+ * The one hash in this package: the same function that decides a type's colour decides where a
+ * node starts, so both are a function of the name and of nothing else.
+ */
+declare function hash(value: string): number;
+declare function layoutSteps(n: number): number;
+/**
+ * How many steps are spent per animation frame while the graph settles in front of the reader.
+ *
+ * Small enough to leave the frame time for drawing, and large enough that a six-entity graph —
+ * which is given three hundred steps — is finished in well under a second rather than in five.
+ * At a few hundred entities a single step already costs most of a frame, so it drops to one and
+ * the graph settles at whatever pace the machine can manage.
+ */
+declare function layoutChunk(n: number): number;
+/**
+ * The radius a graph of `n` entities settles inside, which is also where it is started.
+ *
+ * A cube root, not a square root. Inside a ball of charge the repulsion at radius `r` comes only
+ * from what is enclosed — `n(r/R)³` of it, over `r²` — so balancing it against a gravity of `g·r`
+ * gives `R = k·∛(n/g)`. Guessing `sqrt` instead put a two-thousand-entity graph's starting sphere
+ * five times too wide, and the first half of its forty steps went on collapsing rather than on
+ * laying anything out.
+ */
+declare function layoutRadius(n: number): number;
+type Vec3 = readonly [number, number, number];
+/**
+ * Where every node starts, as `[x, y, z]` per node in the order the ids were given.
+ *
+ * A node the caller remembers keeps exactly the position it had, which is what stops a graph that
+ * gained three entities from reshuffling the twenty that were already there. Everything else is
+ * placed on a sphere by the hash of its id — a Fibonacci-like spiral from two independent hashes,
+ * so ids that are one character apart do not end up next to each other — scaled to the cloud the
+ * remembered nodes already occupy, or to the graph's own settling radius when there is nothing to
+ * remember.
+ */
+declare function seedPositions(ids: readonly string[], seed?: ReadonlyMap<string, Vec3>): Float32Array;
+interface Layout {
+  /** Run `count` more steps, or one. Steps past `steps` do nothing. */
+  step(count?: number): void;
+  /**
+   * The current positions, as `[x, y, z]` per node in the order the nodes were given.
+   *
+   * The live buffer, not a copy: the render loop reads it every frame and must not allocate.
+   * A caller keeping the positions past the next `step` has to copy them itself.
+   */
+  positions(): Float32Array;
+  /** Whether the layout has spent all its steps. */
+  readonly done: boolean;
+  /** How many steps it will spend in total. */
+  readonly steps: number;
+  /** How many it has spent. */
+  readonly taken: number;
+}
+/**
+ * A layout over `nodes` and `edges`, ready to be stepped.
+ *
+ * `seed` is the positions the same graph settled into last time, by node id; the ids it does not
+ * mention are placed by their hash. An edge naming a node that is not there is skipped rather
+ * than refused — the parser has already rejected those, and a layout is not the place to raise.
+ */
+declare function createLayout(nodes: readonly Graph3dNode[], edges: readonly Graph3dEdge[], seed?: ReadonlyMap<string, Vec3>): Layout;
+
+//#endregion
+//#region src/orbit.d.ts
+/**
+ * The knowledge graph as a model you look at, rather than a picture you look down on.
+ *
+ * `layout3d.ts` puts the entities in space; this puts a camera in there with them. A `grid3D`
+ * holds the coordinate system, a `scatter3D` draws the entities and a `line3D` draws the edges,
+ * and the box the three of them share is deliberately invisible: a knowledge graph has no axes
+ * to read, and the only thing an axis would add is furniture.
+ *
+ * Pure: the option is a function of the panel, the palette and the positions. The positions come
+ * from outside because the layout is stepped — the mount loop hands the same builder a slightly
+ * different set of coordinates every frame while the graph settles.
+ */
+/**
+ * The half-width of the space the graph is drawn in, in the box's own units.
+ *
+ * Everything about the camera — the distance it sits at, how big a node reads at that distance —
+ * is a constant, so the graph has to be scaled to it rather than the other way round. The layout
+ * works in units of its own spring length and a graph of two thousand is naturally four times
+ * wider than a graph of six; `orbitScale` divides that difference out, and this is what is left.
+ */
+declare const ORBIT_EXTENT = 50;
+/** The cube the coordinate system is drawn in. Equal on all three sides, or the shape is a lie. */
+declare const ORBIT_BOX = 140;
+/**
+ * The camera: how far out it sits, how fast it goes round, and the field of view it does it with.
+ *
+ * The distance is not a matter of taste. The graph is fitted to the box, so its furthest entity
+ * sits half a box from the middle — and as the camera turns, that entity comes round to the near
+ * side, where the perspective divide is over a distance of `ORBIT_DISTANCE - ORBIT_BOX / 2`
+ * rather than `ORBIT_DISTANCE`. A camera framed for the middle therefore crops the graph twice a
+ * revolution, which is exactly what it did at 180: an entity and its edge walked off the bottom
+ * of the panel and back. So the distance is set from the near face, with room left over for the
+ * labels, which stick out further than the entities they belong to.
+ *
+ * echarts-gl's grid3D camera has a vertical field of view of 50 degrees and is not configurable
+ * through `viewControl`, so it is written down here rather than passed.
+ */
+declare const ORBIT_FOV = 50;
+declare const ORBIT_DISTANCE = 260;
+/** Where the layout has to be moved to, and what it has to be multiplied by, to fill the box. */
+interface OrbitFrame {
+  centre: [number, number, number];
+  scale: number;
+}
+/**
+ * The graph's own bounding box, as the transform that puts it in the middle of the panel.
+ *
+ * Its box, not its bounding sphere, and its centre, not the origin. A settled graph is rarely a
+ * ball: the eight-entity example comes out about 72 units wide, 26 tall and 40 deep, centred six
+ * units left of where it started. Scaling that by its largest radius left it filling a fifth of
+ * the panel and sitting off to one side — correct, and unreadable. Fitting the longest of the
+ * three spans instead fills the frame in whichever direction the graph is actually long, and
+ * because every other span is shorter by definition, nothing lands outside the box.
+ */
+declare function orbitFrame(positions: Float32Array): OrbitFrame;
+/** One entity, as `scatter3D` reads it. */
+interface OrbitNode {
+  id: string;
+  name: string;
+  /** `[x, y, z, size]`: the first three place it, the fourth is what `symbolSize` reads. */
+  value: [number, number, number, number];
+  itemStyle: {
+    color: string;
+    opacity: number;
+  };
+  /** Whether the name is written beside it. The rest are one hover away. */
+  labelled: boolean;
+  /** Carried for the tooltip and the host's click; `type` is taken by ECharts. */
+  nodeType: string | undefined;
+  degree: number;
+  node: Graph3dNode;
+}
+/**
+ * One vertex of the single polyline every edge is drawn on.
+ *
+ * echarts-gl has no series that draws many separate lines in a `grid3D`: `lines3D` lays out only
+ * on a globe, a geo3D or a mapbox, and on a cartesian3D it throws for want of a layout. `line3D`
+ * does work there, but it is one polyline through every point it is given — so the edges are
+ * strung together into one, and the joins between them are made to disappear by giving both their
+ * ends an opacity of zero. Four vertices per edge: the start twice and the end twice, transparent
+ * on the outside and the edge's own colour on the inside.
+ *
+ *     A(0) -> A(c) -> B(c) -> B(0) -> A'(0) -> A'(c) -> ...
+ *             \_____________/                  the edge          \__ the join, transparent at
+ *                                                                    both ends and so invisible
+ *
+ * The doubled points are what the shader's own `position == positionPrev` branch is for, so they
+ * cost two degenerate quads and no artefacts.
+ *
+ * `lineStyle`, not `itemStyle`: `line3D` declares `visualStyleAccessPath: "lineStyle"`, so a
+ * colour written under `itemStyle` is read by nothing and every edge quietly comes out in the
+ * series' one colour — with the joins between them drawn in it too, which turns a knowledge graph
+ * into a ball of wool.
+ */
+interface OrbitEdgePoint {
+  value: [number, number, number];
+  lineStyle: {
+    color: string;
+    opacity: number;
+  };
+}
+/** How many vertices one edge contributes to that polyline. */
+declare const EDGE_VERTICES = 4;
+interface OrbitData {
+  nodes: OrbitNode[];
+  edges: OrbitEdgePoint[];
+}
+/**
+ * The two series' data, from the panel and wherever the layout has got to.
+ *
+ * Built as one thing because the edges have to agree with the nodes: an edge is drawn between two
+ * points, not between two ids, so a frame that moved the nodes and left the edges behind would
+ * detach every line from both its ends.
+ */
+declare function graphOrbitData(panel: Graph3dPanel, c: Palette, positions: Float32Array): OrbitData;
+/**
+ * The whole scene.
+ *
+ * `animate` is the host's word and `panel.rotate` is the fence's; either one saying no stops the
+ * camera. ECharts' own animation is off throughout — on each series as well as at the root,
+ * because echarts-gl's vertex animation asks the *series* whether it may animate and does not
+ * fall back to the screen's answer. While the graph settles this option's data is replaced every
+ * frame, and an animated transition would spend that frame interpolating towards positions the
+ * next frame has already superseded.
+ */
+declare function graphOrbitOption(panel: Graph3dPanel, c: Palette, animate: boolean, positions: Float32Array): EChartsCoreOption;
+
+//#endregion
+//#region src/positions.d.ts
+/**
+ * Where each graph settled last time it was drawn.
+ *
+ * A streamed answer re-renders the same fence as the model writes it: a graph of twenty entities
+ * becomes the same graph of twenty-three, and the reconciler tears the panel down and mounts a
+ * new one. Without a memory the new layout starts from the hash again, every node lands somewhere
+ * else, and the reader — who was reading it — watches the picture they had just understood
+ * dissolve because three names arrived.
+ *
+ * So the positions are kept by node id, under a key that deliberately does *not* depend on the
+ * node set: the ids that are still there resume exactly where they were, and only the new ones
+ * have to find a place. It is module-level state, which is what makes it survive the remount; it
+ * is bounded so a long conversation full of graphs cannot grow it without limit, and it is
+ * forgettable so tests do not leak into each other.
+ */
+/** How many graphs are remembered at once. Beyond this the least recently used one is dropped. */
+declare const REMEMBERED_GRAPHS = 8;
+/**
+ * What identifies a graph across a re-render.
+ *
+ * The title, because that is the one thing a model rewriting its own fence keeps stable while the
+ * entities underneath it change. A panel with no title falls back to its first entity, which is
+ * the next most stable thing there is — a graph usually keeps the entity it was drawn around.
+ * The prefix keeps a panel titled `kyiv` from colliding with an untitled one whose first node is
+ * `kyiv`.
+ */
+declare function graphKey(panel: Graph3dPanel): string;
+/** The positions this graph settled into last time, by node id, or nothing. */
+declare function recallPositions(key: string): ReadonlyMap<string, Vec3> | undefined;
+/**
+ * Remember where a graph settled.
+ *
+ * The positions are copied out of the buffer rather than kept by reference: `Layout.positions()`
+ * hands back the live array, and a layout that is still running would otherwise have this
+ * remember whatever it became several frames later.
+ */
+declare function rememberPositions(key: string, ids: readonly string[], positions: Float32Array): void;
+/** Drop every remembered graph. For tests, and for a host tearing a page down. */
+declare function forgetPositions(): void;
 
 //#endregion
 //#region src/index.d.ts
@@ -202,4 +829,4 @@ declare const bigscreenCss: string;
 declare function bigscreen(options?: BigscreenOptions): AIGuiPlugin;
 
 //#endregion
-export { BigscreenError, BigscreenOptions, BigscreenResult, Chart3dPanel, ChartPanel, GaugePanel, GlobePanel, KpiPanel, Panel, PanelKind, RankPanel, ScreenDefinition, ScreenTheme, bigscreen, bigscreenCss, bigscreenPromptSpec, chart3dOption, chartOption, formatNumber, gaugeColour, gaugeOption, globeOption, palette, parseBigscreen, withAlpha };
+export { BigscreenError, BigscreenEvents, BigscreenOptions, BigscreenResult, Chart3dPanel, ChartPanel, EDGE_VERTICES, EarthColours, GRAPH_LABELS, GRAPH_LEGEND_ROWS, GRAPH_MAX_STEPS, GRAPH_SETTLE_STEPS, GaugePanel, GlobeFeatureCollection, GlobeGeometry, GlobePanel, GlobeSkin, Graph3dEdge, Graph3dNode, Graph3dPanel, GraphLegendEntry, KpiPanel, LAYOUT_GRAVITY, LAYOUT_SPRING, Layout, MAX_ARCS, MAX_EDGES, MAX_ITEMS, MAX_ITEM_DETAIL, MAX_ITEM_LABEL, MAX_LANES, MAX_LANE_NAME, MAX_LINKS, MAX_NODES, MAX_NODE_NAME, MAX_POINTS, MAX_TIMELINE_ITEMS, MAX_TYPES, MAX_TYPE_NAME, MAX_URL, ORBIT_BOX, ORBIT_DISTANCE, ORBIT_EXTENT, ORBIT_FOV, OrbitData, OrbitEdgePoint, OrbitFrame, OrbitNode, Panel, PanelKind, REMEMBERED_GRAPHS, RankPanel, ScreenDefinition, ScreenTheme, TIMELINE_LABELS, TimelineItem, TimelineLane, TimelineLink, TimelinePanel, Vec3, bigscreen, bigscreenCss, bigscreenPromptSpec, chart3dOption, chartOption, countriesTexture, createLayout, degrees, earthColours, earthTexture, forgetPositions, formatNumber, gaugeColour, gaugeOption, globeOption, globeTexture, graph3dOption, graphKey, graphLegend, graphOrbitData, graphOrbitOption, graphTooltip, hash, layoutChunk, layoutRadius, layoutSteps, orbitFrame, palette, parseBigscreen, recallPositions, rememberPositions, seedPositions, spacedItems, timelineHeight, timelineOption, timelineWindow, typeColour, withAlpha };