@beeson-group/tycho 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/AUTHORS +7 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +14 -0
  4. package/README.md +38 -0
  5. package/THIRD_PARTY_NOTICES.md +68 -0
  6. package/dist/tycho.esm.js +515 -261
  7. package/dist/tycho.js +515 -261
  8. package/dist/types/container.d.ts +64 -0
  9. package/dist/types/errors.d.ts +10 -0
  10. package/dist/types/evaluate/clock.d.ts +30 -0
  11. package/dist/types/evaluate/frames.d.ts +63 -0
  12. package/dist/types/evaluate/index.d.ts +14 -0
  13. package/dist/types/evaluate/layers.d.ts +47 -0
  14. package/dist/types/evaluate/resolve.d.ts +39 -0
  15. package/dist/types/evaluate/sets.d.ts +49 -0
  16. package/dist/types/evaluate/types.d.ts +36 -0
  17. package/dist/types/index.d.ts +22 -0
  18. package/dist/types/runtime/colormaps.d.ts +10 -0
  19. package/dist/types/runtime/colors.d.ts +94 -0
  20. package/dist/types/runtime/element.d.ts +224 -0
  21. package/dist/types/runtime/export.d.ts +119 -0
  22. package/dist/types/runtime/geometry.d.ts +214 -0
  23. package/dist/types/runtime/icons.d.ts +56 -0
  24. package/dist/types/runtime/layout.d.ts +34 -0
  25. package/dist/types/runtime/overlay.d.ts +33 -0
  26. package/dist/types/runtime/readouts.d.ts +129 -0
  27. package/dist/types/runtime/renderer.d.ts +303 -0
  28. package/dist/types/runtime/state.d.ts +106 -0
  29. package/dist/types/runtime/tiles.d.ts +33 -0
  30. package/dist/types/scene.d.ts +37 -0
  31. package/dist/types/scene.gen.d.ts +440 -0
  32. package/dist/types/validate.d.ts +9 -0
  33. package/package.json +63 -35
  34. package/src/colormaps.ts +0 -42
  35. package/src/container.ts +0 -126
  36. package/src/element.ts +0 -1034
  37. package/src/frames.ts +0 -204
  38. package/src/index.ts +0 -14
  39. package/src/layout.ts +0 -82
  40. package/src/viewer.ts +0 -864
@@ -0,0 +1,33 @@
1
+ /**
2
+ * What a panel shows over its drawing, as data: its text labels and its colorbars. The renderer
3
+ * computes them, the element writes them as DOM, and the video export draws them on a canvas.
4
+ */
5
+ /**
6
+ * A text label over a panel, centered vertically on (x, y) in CSS pixels from the panel's corner.
7
+ * Its start sits at (x, y) by default, and its center or its end with `align` set to 'center' or
8
+ * 'end'. A rotated label reads upward, turned a quarter turn about (x, y).
9
+ */
10
+ export interface PanelLabel {
11
+ text: string;
12
+ x: number;
13
+ y: number;
14
+ align?: 'start' | 'center' | 'end';
15
+ rotate?: boolean;
16
+ /** Marks a tick number of the axes or the grid, or an axis title, and is left undefined for a body label or an axis tip. */
17
+ kind?: 'tick' | 'title';
18
+ }
19
+ /** What a panel's overlay shows for a colormapped layer. */
20
+ export interface Colorbar {
21
+ label: string;
22
+ gradient: string;
23
+ /** The same colors as stops from 0 at the low end to 1 at the high end, for a canvas. */
24
+ stops: [number, string][];
25
+ lo: number;
26
+ hi: number;
27
+ /** Where the highlighted or single member sits on the bar, in [0, 1], for a parameter colormap. */
28
+ marker: number | null;
29
+ /** The part of the bar a highlight's kernel lights, 1.5 kernel widths either side of the marker, in [0, 1]. */
30
+ band: [number, number] | null;
31
+ }
32
+ /** The bars of a panel with the identical ones merged, keeping the first marker and band any of them has. */
33
+ export declare function mergeColorbars(bars: readonly Colorbar[]): Colorbar[];
@@ -0,0 +1,129 @@
1
+ import { type PanelScope } from '../evaluate/resolve.js';
2
+ import type { SetCache } from '../evaluate/sets.js';
3
+ import type { Clock, Control, Readout, Scene, SetQuery, State, View } from '../scene.js';
4
+ import { type GeometryCache } from './geometry.js';
5
+ /**
6
+ * A number for a readout. With `digits`, it is written to `digits` significant digits with trailing
7
+ * zeros kept. Otherwise an integer is written as it is, and any other number to six significant
8
+ * digits with trailing zeros dropped. An exponent is written as `e` and the exponent, and a minus sign as U+2212.
9
+ */
10
+ export declare function formatNumber(x: number, digits?: number): string;
11
+ /** The slider's stops, which are the distinct parameter values of the matched track sets in increasing order (section 2.9). */
12
+ export declare function sliderStops(scope: PanelScope, sets: SetCache, control: Extract<Control, {
13
+ kind: 'slider';
14
+ }>): number[];
15
+ /** The index of the stop nearest a value, the lowest index winning a tie, or -1 when `stops` is empty. */
16
+ export declare function nearestStop(stops: readonly number[], value: number): number;
17
+ /** Seconds one lap of the clock lasts at speed 1, whatever its steps. */
18
+ export declare const LAP_SECONDS = 8;
19
+ /** The seconds that one loop of the clock lasts at speed 1, which are LAP_SECONDS for each of its laps (rule C6). */
20
+ export declare function loopSeconds(clock: Clock): number;
21
+ /**
22
+ * The loop position, in frame indices and unwrapped, `time` after a playback showed frame index
23
+ * `start`, with `perSecond` units of time to the second. A loop of `steps` lasts `seconds / speed`
24
+ * seconds. Live playback counts milliseconds and a video export its frames, and one division of
25
+ * exact products keeps a position that should be an integer exact.
26
+ */
27
+ export declare function loopPosition(start: number, time: number, perSecond: number, steps: number, speed: number, seconds: number): number;
28
+ /** The frame index at a loop position, i.e. its integer part wrapped into [0, steps). */
29
+ export declare function positionIndex(x: number, steps: number): number;
30
+ /** The progress q in [0, 1) at a loop position, which lies between two frame indices while playing. */
31
+ export declare function positionProgress(x: number, steps: number): number;
32
+ /** The panel, the state, and the frame index through which a readout reads. A caption without a panel does not read anything. */
33
+ export interface ReadoutContext {
34
+ scene: Scene;
35
+ geometry: GeometryCache;
36
+ state: State;
37
+ /** The panel whose driver and values the readout reads. */
38
+ panel: string;
39
+ frameIndex: number;
40
+ /** The progress at which the channel parts read, between two frame indices while playing. It defaults to frameIndex / steps. */
41
+ progress?: number;
42
+ }
43
+ type Part = Readout['parts'][number];
44
+ /** The text of a readout. A part that the driver cannot give, because its query does not match any set, reads as a dash. */
45
+ export declare function readoutText(ctx: ReadoutContext, parts: readonly Part[]): string;
46
+ /** The text of each part of a readout, one per part, or an empty list when the panel is missing. */
47
+ export declare function readoutPieces(ctx: ReadoutContext, parts: readonly Part[]): string[];
48
+ /** One stat tile of a readout: its label, the index of its value part, and its unit. */
49
+ export interface ReadoutTile {
50
+ label: string;
51
+ part: number;
52
+ unit: string;
53
+ /** The least width of the value in ch, for a value that changes during playback (a channel or the clock), so that it does not move its neighbors. */
54
+ width: number | null;
55
+ }
56
+ /**
57
+ * A readout as stat tiles, or null when its text does not split. Parts are flat text, hence the
58
+ * split is a heuristic. A value's label is the text after the last comma before it, less a
59
+ * trailing "=" or ":", and its unit is the text after it up to the next comma. It fails when a
60
+ * label is empty, when the text between two values does not have a comma to split at, or when any
61
+ * text would be left over. Attribute parts, which are scene constants, go last.
62
+ */
63
+ export declare function readoutTiles(parts: readonly Part[]): ReadoutTile[] | null;
64
+ /** How a second of playback went: draws presented, late ones, and the display's refresh interval. */
65
+ export interface FrameReport {
66
+ /** Draws presented in the last second. */
67
+ drawn: number;
68
+ /** Draws that came more than half a refresh interval after the one they should have followed. */
69
+ late: number;
70
+ /** The estimated refresh interval of the display in milliseconds. */
71
+ refresh: number;
72
+ }
73
+ /**
74
+ * Counts the draws presented in the last second, as the Playback group shows it. An average of
75
+ * intervals hides a dropped refresh among smooth ones. The meter therefore keeps the presentation
76
+ * times themselves. The refresh interval is estimated as the shortest interval that recurs, taken as the
77
+ * 10th percentile of the window, and a draw is late when its interval exceeds the refresh interval by half.
78
+ */
79
+ export declare class FrameMeter {
80
+ private readonly times;
81
+ reset(): void;
82
+ /** Records a draw presented at `now`, in milliseconds, and forgets those over a second old. */
83
+ note(now: number): void;
84
+ /** The report of the last second, or null until a full second of draws has been seen since the last reset or after a stall. */
85
+ report(now: number): FrameReport | null;
86
+ }
87
+ /** The Playback group's frame rate, which shows the draws in the last second, or dashes while paused or before a second has passed. */
88
+ export declare function fpsText(report: FrameReport | null): string;
89
+ /** The tooltip behind the frame rate. */
90
+ export declare function fpsTitle(report: FrameReport | null): string;
91
+ export type KeyAction = {
92
+ kind: 'toggle';
93
+ } | {
94
+ kind: 'step';
95
+ by: number;
96
+ } | {
97
+ kind: 'seek';
98
+ frame: number;
99
+ } | {
100
+ kind: 'fit';
101
+ } | {
102
+ kind: 'slider';
103
+ by: number;
104
+ };
105
+ /**
106
+ * The action of a key, following common video players. Space or k plays and pauses. The left and right
107
+ * arrows, or "," and ".", step one frame and pause, and ten with Shift. Home or 0 goes to frame 0, and a
108
+ * digit from 1 to 9 goes to as many tenths of the loop. The key f fits every panel. The up and down arrows
109
+ * step the first scene-scoped slider by one stop, or by ten with Shift.
110
+ */
111
+ export declare function keyAction(key: string, shift: boolean, steps: number): KeyAction | null;
112
+ /** Whether a focused form control takes `key` itself, given the tag name and the `type` of the control. */
113
+ export declare function controlUsesKey(tag: string, type: string, key: string): boolean;
114
+ /** The scene-scoped selector that dragging a colorbar sets, with the label of its control and the track sets that its stops come from. */
115
+ export interface ColorbarLink {
116
+ variable: string;
117
+ label: string;
118
+ domain: SetQuery;
119
+ }
120
+ /**
121
+ * The selector that a colorbar of `view` sets. It is found from the bar's label, through a track
122
+ * layer colored by a parameter whose label the bar carries and a scene-scoped selector by nearest over the
123
+ * same parameter. The stops come from the selector's slider domain, else from the layer's sets.
124
+ * The result is null when a matching layer or a matching selector does not exist.
125
+ */
126
+ export declare function colorbarLink(scene: Scene, view: View, barLabel: string): ColorbarLink | null;
127
+ /** The index of the stop nearest the value at `t` in [0, 1] along a bar from `lo` to `hi`, or -1 when `stops` is empty. */
128
+ export declare function stopAt(stops: readonly number[], lo: number, hi: number, t: number): number;
129
+ export {};
@@ -0,0 +1,303 @@
1
+ /**
2
+ * One WebGL renderer for the whole stage. Every panel is a scissor rectangle of the one canvas,
3
+ * with a camera and a three.js scene per panel, and one redraw draws them all. A frame is a
4
+ * function of the state snapshot, the frame index, the stage size, and the pixel scale, plus
5
+ * whatever the user did to a camera after it was fitted.
6
+ *
7
+ * A track layer draws from the static buffers of geometry.ts, one pass per lap (rule C6 of
8
+ * spec/tycho-scene.md). Its shader compares each segment's two readings with the revealed range of
9
+ * its track. Each range is read from a small float texture with one texel per track, so that the
10
+ * reveals `none`, `grow`, and `trail` differ only in this range (rules L1, L2 and C6). The ranges
11
+ * are per track rather than uniforms because in `value` mode every track has a separate reading
12
+ * (rule C2). A second texel per track holds the opacity a highlight's kernel gives it. A line of
13
+ * width 1 is a GL line. A wider one is a quad per segment, offset in screen space by half the width
14
+ * in CSS pixels on each side, and along a trail the width and the opacity taper from the head to
15
+ * the tail. The CPU draws the pieces at the ends of the range, the heads (rule L3), and the bodies
16
+ * and their trails (rule L4) with the evaluator's functions. Under a plane camera the axes and the
17
+ * grid follow the visible rectangle and give their tick numbers and titles as panel labels.
18
+ */
19
+ import * as THREE from 'three';
20
+ import { type PanelScope } from '../evaluate/resolve.js';
21
+ import type { SetData } from '../evaluate/sets.js';
22
+ import type { BodyLayer, Camera, ColorSpec, MarkLayer, Scene, State, TrackLayer, View } from '../scene.js';
23
+ import { type Theme } from './colors.js';
24
+ import { GeometryCache } from './geometry.js';
25
+ import { type Colorbar, type PanelLabel } from './overlay.js';
26
+ /** Width of the gutter between two panels, in CSS pixels. */
27
+ export declare const GUTTER = 6;
28
+ /** A pleasant round step near `range / target`, which is 1, 2 or 5 times a power of ten. */
29
+ export declare function niceStep(range: number, target?: number): number;
30
+ /** Arrays and GPU buffers built once and shared by every geometry that draws them, kept for the renderer's life. */
31
+ export declare class Shared {
32
+ private readonly cache;
33
+ get<T>(key: string, make: () => T): T;
34
+ }
35
+ interface DrawContext {
36
+ scene: Scene;
37
+ geometry: GeometryCache;
38
+ shared: Shared;
39
+ theme: Theme;
40
+ disc: THREE.Texture;
41
+ }
42
+ export interface TrackPlan {
43
+ kind: 'track';
44
+ index: number;
45
+ layer: TrackLayer;
46
+ set: SetData | null;
47
+ /** The members of rule V3, in increasing order. */
48
+ members: number[];
49
+ /** The highlighted member, when the highlight's selector resolves to one of the members. */
50
+ highlight: number | null;
51
+ /** The track that the highlight's selector resolves to in the set, a member or not, which is the center of its kernel. */
52
+ selected: number | null;
53
+ /** The clock channel the layer reads, or null when it does not take a reading. */
54
+ channel: string | null;
55
+ /** The layer's color, where a colormap keyed on a choice is resolved to the colormap that the panel's value of the choice maps to (section 2.7). */
56
+ color: ColorSpec | undefined;
57
+ }
58
+ export interface BodyPlan {
59
+ kind: 'body';
60
+ index: number;
61
+ layer: BodyLayer;
62
+ }
63
+ export interface MarkPlan {
64
+ kind: 'axes' | 'grid';
65
+ index: number;
66
+ layer: MarkLayer;
67
+ }
68
+ export type LayerPlan = TrackPlan | BodyPlan | MarkPlan;
69
+ export interface PanelPlan {
70
+ viewId: string;
71
+ view: View;
72
+ display: string;
73
+ scope: PanelScope;
74
+ driver: {
75
+ set: SetData;
76
+ track: number;
77
+ } | null;
78
+ layers: LayerPlan[];
79
+ }
80
+ /** A layer's color with a colormap keyed on a choice (section 2.7) resolved by the panel's value of the choice (rule V1). */
81
+ export declare function resolveColor(scope: PanelScope, spec: ColorSpec | undefined): ColorSpec | undefined;
82
+ /** What a panel of a state draws: its display frame, its driver, and its visible layers resolved. */
83
+ export declare function planPanel(scene: Scene, geometry: GeometryCache, state: State, pid: string): PanelPlan;
84
+ /** What the camera fit depends on: the view, the display frame, the driver's track set, and the track sets of the track layers. */
85
+ export declare function contentKey(plan: PanelPlan): string;
86
+ type Box6 = [number, number, number, number, number, number];
87
+ /**
88
+ * The box a panel's camera fits, which holds every member of every track layer, whole, in every lap
89
+ * from 0 to the top, in the display frame. It is given as minimum then maximum x, y, z, and is null
90
+ * when the track layers do not draw anything.
91
+ */
92
+ export declare function fitBox(plan: PanelPlan, geometry: GeometryCache): Box6 | null;
93
+ /**
94
+ * An orthographic fit, given as the center of the box and half the view's height, for a viewport whose
95
+ * width over height is `aspect`. One world unit is as long across the screen as up it, and a tenth of
96
+ * margin is added.
97
+ */
98
+ export declare function orthoFit(box: THREE.Box3, cam: Camera, aspect: number): {
99
+ center: THREE.Vector3;
100
+ halfHeight: number;
101
+ };
102
+ /** The opacity of a member at parameter distance `d` from the center of a highlight's kernel (section 2.7). */
103
+ export declare function kernelOpacity(floor: number, kernel: {
104
+ width: number;
105
+ opacity: number;
106
+ }, extent: number, d: number): number;
107
+ /** The part of the display plane a plane camera shows, and the steps of its ticks. */
108
+ export interface PlaneView {
109
+ /** The visible rectangle along the camera's right and up axes, in display-frame units. */
110
+ x0: number;
111
+ x1: number;
112
+ y0: number;
113
+ y1: number;
114
+ /** The panel's size in CSS pixels. */
115
+ w: number;
116
+ h: number;
117
+ stepX: number;
118
+ stepY: number;
119
+ }
120
+ /** What an orthographic camera under a plane camera shows, with a tick about every 110 pixels across and 70 up. */
121
+ export declare function planeView(camera: THREE.OrthographicCamera, cam: Camera & {
122
+ kind: 'plane';
123
+ }, w: number, h: number): PlaneView;
124
+ /**
125
+ * The labels of a plane view. Tick numbers run along the bottom and the left edges, clear of the corners.
126
+ * The two axis titles sit at the bottom center and the left center, the second reading upward, each in a
127
+ * separate row outside the tick numbers. The tick row is centered 28 px above the bottom edge and the x
128
+ * title 10 px above it. The y title sits 10 px from the left edge, and the y tick column is right-aligned
129
+ * clear of it at its widest number. A panel too short or too narrow for a title keeps its ticks.
130
+ */
131
+ export declare function planeLabels(v: PlaneView, ticks: boolean, titles: [string, string] | null): PanelLabel[];
132
+ interface Draw {
133
+ readonly key: string;
134
+ readonly group: THREE.Group;
135
+ extend(box: THREE.Box3): void;
136
+ resize?(w: number, h: number): void;
137
+ dispose(): void;
138
+ }
139
+ export declare class TrackDraw implements Draw {
140
+ readonly key: string;
141
+ readonly group: THREE.Group<THREE.Object3DEventMap>;
142
+ private readonly src;
143
+ private readonly layer;
144
+ private readonly set;
145
+ private readonly geo;
146
+ private readonly clocks;
147
+ private readonly spec;
148
+ private readonly color;
149
+ private readonly width;
150
+ private readonly hiWidth;
151
+ private readonly opacity;
152
+ private readonly hiOpacity;
153
+ /** Along a trail, the loop readings over which the taper falls, else 0, and the width and opacity it falls to. */
154
+ private readonly fraction;
155
+ private readonly taperWidth;
156
+ private readonly taperOpacity;
157
+ private readonly kernel;
158
+ private readonly ranges;
159
+ private readonly alphas;
160
+ private readonly resolution;
161
+ private readonly uniforms;
162
+ private readonly baseHolder;
163
+ private readonly hiHolder;
164
+ /** The passes built so far, by lap and kind, each built the first time its lap shows anything. */
165
+ private readonly passes;
166
+ private readonly pieces;
167
+ private heads;
168
+ private readonly headSize;
169
+ private readonly headColor;
170
+ private members;
171
+ private highlight;
172
+ private selected;
173
+ private baseWhat;
174
+ private skip;
175
+ private filled;
176
+ constructor(ctx: DrawContext, plan: TrackPlan & {
177
+ set: SetData;
178
+ }, display: string, key: string);
179
+ /** Room for `n` heads in the heads' buffers. */
180
+ private growHeads;
181
+ resize(w: number, h: number): void;
182
+ /** The color of a vertex of track `t`, which is the layer's color or a blend of the colors of two samples. */
183
+ private colorAt;
184
+ /** Each track's opacity under the highlight's kernel, around the selected track's parameter value. */
185
+ private fillKernel;
186
+ private showPass;
187
+ private pass;
188
+ /** Shows the passes of the laps that draw a segment, building the ones not built yet, and hides the others. */
189
+ private syncPasses;
190
+ /** True when the layer does not take a reading, so that what it draws changes only with its members, its highlight, and its selection. */
191
+ get isStatic(): boolean;
192
+ /** Returns whether the picture changed through new members, a new highlight or selection, or a first fill. */
193
+ update(plan: TrackPlan, scene: Scene, q: number): boolean;
194
+ extend(): void;
195
+ /** The colorbar of a colormapped layer, with the highlighted or single member marked on it, and the kernel's band. */
196
+ colorbar(): Colorbar | null;
197
+ dispose(): void;
198
+ }
199
+ /**
200
+ * Whether a camera's world or projection matrix differs from `seen`, which then holds both. The test
201
+ * covers any pan, zoom, rotation, fit, or change of aspect, however the camera was moved.
202
+ */
203
+ export declare function cameraMoved(camera: THREE.Camera, seen: Float64Array): boolean;
204
+ export declare class StageRenderer {
205
+ readonly canvas: HTMLCanvasElement;
206
+ /** Called when the user moves a camera, so that the page redraws. */
207
+ onChange: () => void;
208
+ private readonly gl;
209
+ private readonly ctx;
210
+ private readonly panels;
211
+ private lastState;
212
+ private size;
213
+ private readonly background;
214
+ /**
215
+ * Draws each panel's bottom run of layers that do not take a reading once, and copies it back every
216
+ * frame. When it is off, every layer is drawn every frame, as the reference the cache is compared with.
217
+ */
218
+ cacheStatic: boolean;
219
+ /**
220
+ * Draws an underlay without antialiasing when it was drawn again less than DRAG_MS before, as
221
+ * every frame of a slider or camera drag does, and with antialiasing REFINE_MS after the drag stops.
222
+ * It is off for a video export, whose frames must all be finished.
223
+ */
224
+ coarseDrags: boolean;
225
+ private refineTimer;
226
+ private readonly blit;
227
+ /** Every panel's static layers, each panel in a separate region at the same pixels as on the canvas. */
228
+ private underlay;
229
+ /**
230
+ * Where a panel's static layers are drawn with antialiasing before they are copied into the
231
+ * underlay, as large as the largest panel. Reading the antialiased canvas back instead gives, in
232
+ * Chrome, the right pixels only for the last panel drawn in a frame, and stale pixels for the others.
233
+ */
234
+ private scratch;
235
+ private readonly viewport;
236
+ private readonly buffer;
237
+ private readonly region;
238
+ private readonly corner;
239
+ /**
240
+ * The option `preserveDrawingBuffer` is set for a canvas that is read back after the frame, as in a
241
+ * video export. It is left off for a page, which spares the compositor a copy of the canvas every frame.
242
+ */
243
+ constructor(canvas: HTMLCanvasElement, scene: Scene, geometry: GeometryCache, options?: {
244
+ preserveDrawingBuffer?: boolean;
245
+ cacheStatic?: boolean;
246
+ coarseDrags?: boolean;
247
+ theme?: Theme;
248
+ });
249
+ /** Draws with `theme` from the next frame on. The cameras stay, and the next plan rebuilds only the draws that take a color from the theme. */
250
+ setTheme(theme: Theme): void;
251
+ private panel;
252
+ /** Gives a panel the element its camera controls listen on and its labels are written into, or takes it away. */
253
+ bind(pid: string, element: HTMLElement | null): void;
254
+ /** Fits a panel's camera to what it draws at the next frame, forgetting how the user moved the camera. */
255
+ refit(pid: string): void;
256
+ refitAll(): void;
257
+ private makeControls;
258
+ private setCamera;
259
+ /**
260
+ * Draws a panel's static layers into the viewport just set, copied back from the underlay, which
261
+ * is drawn again first when anything they depend on changed.
262
+ */
263
+ private drawStatic;
264
+ /** Draws a panel's static layers straight into its region of `target`, which is not multisampled. */
265
+ private drawCoarse;
266
+ /** Draws every coarse underlay again with antialiasing once REFINE_MS pass without a coarse one. */
267
+ private scheduleRefine;
268
+ /**
269
+ * Draws a panel's static layers with antialiasing into the scratch target, which three resolves
270
+ * after the draw, and copies them into the panel's region `r` of `target`.
271
+ */
272
+ private drawFine;
273
+ private disposePanel;
274
+ /** Re-resolves a panel against a new state, rebuilding only the draws whose inputs changed. */
275
+ private replan;
276
+ /** Updates a panel's draws for progress `q`. */
277
+ private advance;
278
+ /** Fits the camera to every track layer's members (fitBox), or to the bodies when the track layers do not draw anything. */
279
+ private fit;
280
+ /** Keeps one world unit the same length across and up the screen in an orthographic view. */
281
+ private aspect;
282
+ /** What a plane camera shows now, and the marks that follow it laid out across it. */
283
+ private follow;
284
+ /**
285
+ * Draws every panel of `state` at progress `q` in [0, 1) on a stage of `width` by `height` CSS
286
+ * pixels. A frame index i sits at q = i / steps, and playback draws between two of them. Returns the
287
+ * message of every panel that could not be drawn.
288
+ */
289
+ renderAt(state: State, q: number, width: number, height: number, pixelRatio: number): Map<string, string>;
290
+ /**
291
+ * The labels of a panel at the last frame, in CSS pixels from the panel's corner. They are the tick
292
+ * numbers and axis titles of a plane camera, the axis titles at the tips of axes laid out from the
293
+ * box, and the body labels beside their discs.
294
+ */
295
+ private labelItems;
296
+ /** The labels a panel shows at the last frame, for a page or a video frame to write as text. */
297
+ labels(pid: string): PanelLabel[];
298
+ /** The colorbars a panel shows, the identical ones merged. */
299
+ colorbars(pid: string): Colorbar[];
300
+ private placeLabels;
301
+ dispose(): void;
302
+ }
303
+ export {};
@@ -0,0 +1,106 @@
1
+ import { type Layout, type PanelState, type Scene, type State, type VariableValue } from '../scene.js';
2
+ import { type DropZone } from './layout.js';
3
+ /** Which of the snapshot, the frame index, and the playing flag changed. */
4
+ export type Change = 'state' | 'frame' | 'playing';
5
+ export type Listener = (change: Change) => void;
6
+ /** A dictionary without a prototype, so that an id like "__proto__" is an own key. */
7
+ export declare function dict<T>(): Record<string, T>;
8
+ export declare class Store {
9
+ private snap;
10
+ private index;
11
+ private play;
12
+ private readonly steps;
13
+ private readonly listeners;
14
+ constructor(state: State, steps: number);
15
+ get state(): State;
16
+ /** The frame index, kept in [0, steps), since the indices i and i + steps are the same frame (section 2.6). */
17
+ get frame(): number;
18
+ get playing(): boolean;
19
+ subscribe(listener: Listener): () => void;
20
+ private emit;
21
+ set(next: State): void;
22
+ update(f: (s: State) => State): void;
23
+ setFrame(i: number): void;
24
+ setPlaying(on: boolean): void;
25
+ }
26
+ /**
27
+ * Sets a variable in the panel when the variable is panel-scoped, and in the scene otherwise
28
+ * (rule V1). A value that does not fit the variable leaves the state as it is.
29
+ */
30
+ export declare function withVariable(scene: Scene, state: State, id: string, value: VariableValue, panel?: string): State;
31
+ export declare function withChannel(state: State, channel: string): State;
32
+ export declare function withPanel(state: State, id: string, panel: PanelState): State;
33
+ export declare function withLayout(state: State, layout: Layout): State;
34
+ /** Removes a panel and its layout leaf, collapsing its split. The last panel stays. */
35
+ export declare function withoutPanel(state: State, id: string): State;
36
+ /** A panel id of the form p1, p2, and so on that the state does not use yet. */
37
+ export declare function newPanelId(state: State): string;
38
+ /** The layout with two leaves exchanged. */
39
+ export declare function swapLeaves(node: Layout, a: string, b: string): Layout;
40
+ /** What can be dropped on a panel: a view, a value of a panel-scoped choice, or another panel. */
41
+ export type DropPayload = {
42
+ kind: 'view';
43
+ view: string;
44
+ } | {
45
+ kind: 'value';
46
+ variable: string;
47
+ value: string;
48
+ } | {
49
+ kind: 'panel';
50
+ id: string;
51
+ };
52
+ /**
53
+ * The state after a drop on panel `target`. On an edge, a view or a value makes a new panel
54
+ * there, which takes the target's view and panel values and then the dropped one, and a panel
55
+ * moves there. On the center, a view or a value changes the target, and a panel swaps places
56
+ * with it. A new panel is not made once the state has `maxPanels` panels.
57
+ */
58
+ export declare function withDrop(scene: Scene, state: State, target: string, zone: DropZone, payload: DropPayload, maxPanels?: number): State;
59
+ /**
60
+ * The state after adding a panel with `payload` where there is most room. The largest panel by
61
+ * area is split along its longer side, below it when `tall` returns true (taller than wide) and
62
+ * to its right otherwise. A new panel is not made once the state has `maxPanels` panels.
63
+ */
64
+ export declare function withAdd(scene: Scene, state: State, payload: Exclude<DropPayload, {
65
+ kind: 'panel';
66
+ }>, maxPanels: number, tall: (id: string) => boolean): State;
67
+ /** Where a chip's menu puts a panel, either where there is most room or where a drop on a panel would. */
68
+ export type Placement = {
69
+ kind: 'add';
70
+ } | {
71
+ kind: 'drop';
72
+ target: string;
73
+ zone: DropZone;
74
+ };
75
+ export interface MenuItem {
76
+ label: string;
77
+ placement: Placement;
78
+ disabled: boolean;
79
+ /** The item opens a new group of the menu. */
80
+ group: boolean;
81
+ }
82
+ /**
83
+ * The menu of a chip in the Add panel group, which offers from the keyboard what dragging does. It
84
+ * lists Add panel, then for each panel in layout order Split it right, Split it below, and Replace
85
+ * it. The function `name` gives a panel's name, which is numbered where two panels share one. An
86
+ * item that would add a panel beyond `maxPanels` is disabled.
87
+ */
88
+ export declare function chipMenu(state: State, name: (id: string) => string, maxPanels: number): MenuItem[];
89
+ /** The state after a chip's menu item: `withAdd` or `withDrop` with the chip's payload. */
90
+ export declare function withPlacement(scene: Scene, state: State, placement: Placement, payload: Exclude<DropPayload, {
91
+ kind: 'panel';
92
+ }>, maxPanels: number, tall: (id: string) => boolean): State;
93
+ /** The 32-bit FNV-1a hash (Fowler-Noll-Vo) of the UTF-8 bytes of `text`, as eight hex digits. */
94
+ export declare function fnv1a(text: string): string;
95
+ /** The key under which a stored state is kept, built from a hash of scene.tys and its length (section 2.8). */
96
+ export declare function storageKey(sceneText: string): string;
97
+ /**
98
+ * Repairs a stored state against a scene, as described in section 2.8. A panel whose view the
99
+ * scene lacks is dropped together with its layout leaf, and a value that does not fit its
100
+ * variable is dropped, as is a panel value of a scene-scoped variable. The repair falls back to
101
+ * `initial` once every panel is dropped or when the clock channel is unknown. Beyond section 2.8,
102
+ * it also drops values that are never read (undeclared ids, and a scene value of a panel-scoped variable),
103
+ * a panel that the layout does not show or whose id is not an identifier, and a repeated leaf. It falls
104
+ * back to `initial` as well on input that is not a state at all. It is pure and does not modify `stored`.
105
+ */
106
+ export declare function repair(scene: Scene, stored: unknown): State;
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Where the panels of a layout tree sit on a stage. The placement is a pure function of the tree
3
+ * and the stage rectangle, and both the page and the renderer use it, so that a frame does not
4
+ * depend on how the browser lays out the page.
5
+ */
6
+ import type { Layout } from '../scene.js';
7
+ export interface Rect {
8
+ x: number;
9
+ y: number;
10
+ w: number;
11
+ h: number;
12
+ }
13
+ /** One split's gutter: its rectangle, the rectangle of the whole split, and the path to the split. */
14
+ export interface Gutter {
15
+ path: string;
16
+ dir: 'row' | 'col';
17
+ rect: Rect;
18
+ outer: Rect;
19
+ }
20
+ export interface Tiles {
21
+ panels: Map<string, Rect>;
22
+ gutters: Gutter[];
23
+ }
24
+ /**
25
+ * Tiles `rect` by the layout. A split gives `ratio` of its extent less the gutter to `a`, in
26
+ * whole pixels, and the rest to `b`. A gutter's path is the string of letters a and b
27
+ * that leads from the root to the split.
28
+ */
29
+ export declare function tile(layout: Layout, rect: Rect, gutter: number): Tiles;
30
+ /** The layout with the ratio of the split at `path` replaced. */
31
+ export declare function withRatio(layout: Layout, path: string, ratio: number): Layout;
32
+ /** The ratio of a split for a pointer at (x, y), in the split's rectangle less its gutter, kept in [0.1, 0.9]. */
33
+ export declare function ratioAt(g: Gutter, x: number, y: number, gutter: number): number;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Scene types. Every structural type comes from scene.gen.ts, which is generated from
3
+ * spec/scene.schema.json, and the types therefore cannot drift apart from the schema. The aliases below
4
+ * only name parts that the generator, web/scripts/gen-types.mjs, leaves anonymous.
5
+ */
6
+ import type { Layer, State, TrackSet, Variable } from './scene.gen.js';
7
+ export type * from './scene.gen.js';
8
+ export type ChannelDef = NonNullable<NonNullable<TrackSet['channels']>[string]>;
9
+ export type ParameterDef = NonNullable<NonNullable<TrackSet['parameters']>[string]>;
10
+ export type TrackLayer = Extract<Layer, {
11
+ kind: 'track';
12
+ }>;
13
+ export type BodyLayer = Extract<Layer, {
14
+ kind: 'body';
15
+ }>;
16
+ export type MarkLayer = Extract<Layer, {
17
+ kind: 'axes' | 'grid';
18
+ }>;
19
+ export type Selector = Extract<Variable, {
20
+ kind: 'selector';
21
+ }>;
22
+ export type Choice = Extract<Variable, {
23
+ kind: 'choice';
24
+ }>;
25
+ export type Toggle = Extract<Variable, {
26
+ kind: 'toggle';
27
+ }>;
28
+ export type PanelState = NonNullable<State['panels'][string]>;
29
+ export type VariableValue = number | string | boolean;
30
+ /** The scene format version this reader implements. */
31
+ export declare const SCENE_MAJOR = 0;
32
+ export declare const SCENE_MINOR = 2;
33
+ /** Features from `requires` that this reader implements. Version 0.2 of the format does not include any feature of section 4. */
34
+ export declare const SUPPORTED_FEATURES: ReadonlySet<string>;
35
+ export declare const TOP_LEVEL_KEYS: ReadonlySet<string>;
36
+ export declare const ID_PATTERN: RegExp;
37
+ export declare const INDEX_CHANNEL = "@index";