@doki-land/davinci 0.0.0-stage → 0.0.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.
@@ -0,0 +1,1203 @@
1
+ // Generated by dts-bundle-generator v9.5.1
2
+
3
+ /** 2D point / vector (x, y). */
4
+ export interface Point2D {
5
+ readonly x: number;
6
+ readonly y: number;
7
+ }
8
+ /** 3D point / vector (x, y, z). */
9
+ export interface Point3D {
10
+ readonly x: number;
11
+ readonly y: number;
12
+ readonly z: number;
13
+ }
14
+ /** Affine 2D transform matrix (3x3, column-major compact form).
15
+ *
16
+ * ```text
17
+ * | a c tx |
18
+ * | b d ty |
19
+ * | 0 0 1 |
20
+ * ```
21
+ *
22
+ * Standard affine transforms (translate, scale, rotate, skew) compose via
23
+ * {@link multiplyTransform}.
24
+ */
25
+ export interface Affine2D {
26
+ readonly a: number;
27
+ readonly b: number;
28
+ readonly c: number;
29
+ readonly d: number;
30
+ readonly tx: number;
31
+ readonly ty: number;
32
+ }
33
+ /** Identity affine (no-op). */
34
+ export declare const IDENTITY_AFFINE: Affine2D;
35
+ /** Compose two affine transforms: result = b ∘ a (apply a, then b). */
36
+ export declare function multiplyTransform(a: Affine2D, b: Affine2D): Affine2D;
37
+ /** Translate by (dx, dy). */
38
+ export declare function translate(dx: number, dy: number): Affine2D;
39
+ /** Scale by (sx, sy) around origin. */
40
+ export declare function scale(sx: number, sy: number): Affine2D;
41
+ /** Rotate by radians around origin. */
42
+ export declare function rotate(angle: number): Affine2D;
43
+ /** Apply affine transform to a point. */
44
+ export declare function applyTransform(p: Point2D, t: Affine2D): Point2D;
45
+ /** A segment of a path — one of the SVG/Cubic-like command primitives. */
46
+ export type PathCommand = {
47
+ readonly kind: "move";
48
+ readonly to: Point2D;
49
+ } | {
50
+ readonly kind: "line";
51
+ readonly to: Point2D;
52
+ } | {
53
+ readonly kind: "cubic";
54
+ readonly cp1: Point2D;
55
+ readonly cp2: Point2D;
56
+ readonly to: Point2D;
57
+ } | {
58
+ readonly kind: "quadratic";
59
+ readonly cp: Point2D;
60
+ readonly to: Point2D;
61
+ } | {
62
+ readonly kind: "arc";
63
+ readonly rx: number;
64
+ readonly ry: number;
65
+ readonly xRot: number;
66
+ readonly largeArc: boolean;
67
+ readonly sweep: boolean;
68
+ readonly to: Point2D;
69
+ } | {
70
+ readonly kind: "close";
71
+ };
72
+ /** A simple path = sequence of commands, optionally closed. */
73
+ export interface Path {
74
+ readonly commands: ReadonlyArray<PathCommand>;
75
+ }
76
+ declare function moveTo$1(x: number, y: number): PathCommand;
77
+ export declare function lineTo(x: number, y: number): PathCommand;
78
+ export declare function closePath(): PathCommand;
79
+ /** Canonical sRGB color with alpha (0–1 each). */
80
+ export interface RGBA {
81
+ readonly r: number;
82
+ readonly g: number;
83
+ readonly b: number;
84
+ readonly a: number;
85
+ }
86
+ /** Construct from 0–255 integer channels. */
87
+ export declare function rgba8(r: number, g: number, b: number, a?: number): RGBA;
88
+ /** Construct opaque from 0–255 integer channels. */
89
+ export declare function rgb8(r: number, g: number, b: number): RGBA;
90
+ /** Parse `#rgb`, `#rrggbb`, `#rrggbbaa` hex strings. */
91
+ export declare function fromHex(hex: string): RGBA;
92
+ /** Serialize to `#rrggbb` (alpha 1) or `#rrggbbaa`. */
93
+ export declare function toHex(c: RGBA): string;
94
+ /** Opaque black. */
95
+ export declare const BLACK: RGBA;
96
+ /** Opaque white. */
97
+ export declare const WHITE: RGBA;
98
+ /** Fully transparent. */
99
+ export declare const TRANSPARENT: RGBA;
100
+ /** A font family + size + weight/style descriptor (platform-neutral). */
101
+ export interface FontSpec {
102
+ readonly family: string;
103
+ readonly sizePx: number;
104
+ readonly weight?: number;
105
+ readonly italic?: boolean;
106
+ }
107
+ /** Measured text metrics from a text layout engine (platform-provided). */
108
+ interface TextMetrics$1 {
109
+ /** Line box width in CSS pixels. */
110
+ readonly width: number;
111
+ /** Line box height (includes line-gap). */
112
+ readonly height: number;
113
+ /** Distance from baseline to top of em-square. */
114
+ readonly ascent: number;
115
+ /** Distance from baseline to bottom of em-square. */
116
+ readonly descent: number;
117
+ /** Line gap between lines. */
118
+ readonly lineGap: number;
119
+ }
120
+ /** A text node content — display text + font + alignment. */
121
+ export interface TextRun {
122
+ readonly text: string;
123
+ readonly font: FontSpec;
124
+ /** Horizontal anchor on the anchor point. Default "start". */
125
+ readonly hAlign?: "start" | "center" | "end";
126
+ /** Vertical anchor on the anchor point. Default "alphabetic". */
127
+ readonly vAlign?: "alphabetic" | "top" | "middle" | "bottom";
128
+ }
129
+ /** Axis-aligned rectangle (x, y is top-left, w/h non-negative). */
130
+ export interface Rect {
131
+ readonly x: number;
132
+ readonly y: number;
133
+ readonly w: number;
134
+ readonly h: number;
135
+ }
136
+ /** Semantic alias — used by Scene packages for clarity. */
137
+ export type BoundsRect = Rect;
138
+ /** Rect from two corner points. */
139
+ export declare function rectFromPoints(a: {
140
+ readonly x: number;
141
+ readonly y: number;
142
+ }, b: {
143
+ readonly x: number;
144
+ readonly y: number;
145
+ }): Rect;
146
+ /** Rect with explicit center and size. */
147
+ export declare function rectFromCenter(cx: number, cy: number, w: number, h: number): Rect;
148
+ /** Union of two rects (minimal rect containing both). Empty rects are skipped. */
149
+ export declare function union(a: Rect, b: Rect): Rect;
150
+ /** True if point (px, py) is inside rect. */
151
+ export declare function contains(r: Rect, px: number, py: number): boolean;
152
+ /** True if two rects intersect (touching edges counts as intersecting). */
153
+ export declare function intersects(a: Rect, b: Rect): boolean;
154
+ /** Apply a translate offset to a rect. */
155
+ export declare function offset(r: Rect, dx: number, dy: number): Rect;
156
+ export type DiagnosticSeverity = "info" | "warning" | "error";
157
+ /** A single diagnostic item. No reliance on VMZ protocol types. */
158
+ export interface Diagnostic {
159
+ readonly severity: DiagnosticSeverity;
160
+ /** Stable identifier like `davinci.diagram.unsupported`. */
161
+ readonly code: string;
162
+ /** Human-readable message in English. Localization is host-scope. */
163
+ readonly message: string;
164
+ /** Optional source reference (domain, node id, field path, etc.). */
165
+ readonly source?: string;
166
+ }
167
+ /** Immutable diagnostic set — used as output of compile/layout. */
168
+ export interface DiagnosticSet {
169
+ readonly items: ReadonlyArray<Diagnostic>;
170
+ }
171
+ /** Empty diagnostic set. */
172
+ export declare const EMPTY_DIAGNOSTICS: DiagnosticSet;
173
+ /** Convenience factory. */
174
+ export declare function diag(severity: DiagnosticSeverity, code: string, message: string, source?: string): Diagnostic;
175
+ /** The only scene contract version this build emits and accepts. */
176
+ export declare const SCENE_VERSION = "/v0";
177
+ export type SceneVersion = typeof SCENE_VERSION;
178
+ /** Contract guard used by `resolve` and `renderSvg` at their boundaries. */
179
+ export declare function assertSceneVersion(version: string, stage: string): void;
180
+ /** A stable identifier assigned by the domain (chart, diagram, ...). */
181
+ export type StableId = string;
182
+ /** High-level semantic role — used for hit-test targets and host binding. */
183
+ export type SemanticRole = "chart.mark" | "chart.axis" | "chart.grid" | "chart.legend" | "diagram.node" | "diagram.edge" | "diagram.label" | "diagram.cluster" | "diagram.port" | "text" | "image" | "decorative" | "group";
184
+ /** Source reference — back-link to the domain object that produced this node.
185
+ * Opaque to Scene; used by host for provenance / edit / export links. */
186
+ export interface SourceRef {
187
+ /** Domain identifier ("chart", "diagram", ...). */
188
+ readonly domain: string;
189
+ /** Optional path within the domain (field name, row index, node id, ...). */
190
+ readonly path?: ReadonlyArray<string | number>;
191
+ }
192
+ /** Hit region — optional explicit target for hit-testing (overrides geometry bounds). */
193
+ export type HitRegion = {
194
+ readonly rect: Rect;
195
+ } | {
196
+ /** Annular sector for pie / donut slices: angle in radians, 0 =
197
+ * +x axis, positive clockwise (screen coordinates, y down). */
198
+ readonly sector: {
199
+ readonly cx: number;
200
+ readonly cy: number;
201
+ readonly rOuter: number;
202
+ readonly rInner: number;
203
+ readonly a0: number;
204
+ readonly a1: number;
205
+ };
206
+ } | {
207
+ /** Polyline vertices in scene order, each with its stable row key —
208
+ * lets a host snap to the nearest real data point on a line or
209
+ * area path instead of interpolating between pixels. */
210
+ readonly polyline: {
211
+ readonly points: ReadonlyArray<Point2D>;
212
+ readonly keys: ReadonlyArray<string>;
213
+ };
214
+ } | {
215
+ /** Closed filled polygon (funnel segments, sankey link ribbons,
216
+ * ridgeline ribbons): the host hit-tests with ray casting inside
217
+ * and falls back to edge distance outside, and anchors tooltips at
218
+ * the polygon centroid. */
219
+ readonly polygon: {
220
+ readonly points: ReadonlyArray<Point2D>;
221
+ };
222
+ };
223
+ export interface BaseSemantic {
224
+ /** Stable identity — MUST be unique within one Scene. */
225
+ readonly id: StableId;
226
+ /** What this node IS (semantic tag, not style). */
227
+ readonly role: SemanticRole;
228
+ /** Optional back-link to domain source. */
229
+ readonly source?: SourceRef;
230
+ /** Optional hit region override. */
231
+ readonly hitRegion?: HitRegion;
232
+ }
233
+ export interface SemanticTransform {
234
+ /** Local transform (will be composed with parent during resolve). */
235
+ readonly transform?: Affine2D;
236
+ /** Optional local clip rect (intersected with parent clip during resolve). */
237
+ readonly clip?: Rect;
238
+ }
239
+ export interface Stroke {
240
+ readonly color?: RGBA;
241
+ readonly width?: number;
242
+ readonly dash?: ReadonlyArray<number>;
243
+ }
244
+ export interface Fill {
245
+ readonly color?: RGBA;
246
+ }
247
+ /** A group node — container only; carries transform/clip and children. */
248
+ export interface SemanticGroup extends BaseSemantic, SemanticTransform {
249
+ readonly kind: "group";
250
+ readonly children: ReadonlyArray<SemanticNode>;
251
+ }
252
+ /** A path shape (SVG/Cubic-style command sequence). */
253
+ export interface SemanticPath extends BaseSemantic, SemanticTransform {
254
+ readonly kind: "path";
255
+ readonly path: Path;
256
+ readonly stroke?: Stroke;
257
+ readonly fill?: Fill;
258
+ }
259
+ /** An axis-aligned rectangle. */
260
+ export interface SemanticRect extends BaseSemantic, SemanticTransform {
261
+ readonly kind: "rect";
262
+ readonly x: number;
263
+ readonly y: number;
264
+ readonly w: number;
265
+ readonly h: number;
266
+ readonly rx?: number;
267
+ readonly ry?: number;
268
+ readonly stroke?: Stroke;
269
+ readonly fill?: Fill;
270
+ }
271
+ /** An ellipse defined by center + radii. */
272
+ export interface SemanticEllipse extends BaseSemantic, SemanticTransform {
273
+ readonly kind: "ellipse";
274
+ readonly cx: number;
275
+ readonly cy: number;
276
+ readonly rx: number;
277
+ readonly ry: number;
278
+ readonly stroke?: Stroke;
279
+ readonly fill?: Fill;
280
+ }
281
+ /** An image — referenced by URL / resource id; NOT raw pixels. */
282
+ export interface SemanticImage extends BaseSemantic, SemanticTransform {
283
+ readonly kind: "image";
284
+ readonly resourceRef: string;
285
+ readonly x: number;
286
+ readonly y: number;
287
+ readonly w: number;
288
+ readonly h: number;
289
+ }
290
+ /** A text node — string + font spec. Host provides actual metrics. */
291
+ export interface SemanticText extends BaseSemantic, SemanticTransform {
292
+ readonly kind: "text";
293
+ readonly text: string;
294
+ readonly font: FontSpec;
295
+ /** Anchor point (where transform-origin of the text block lives). */
296
+ readonly anchor?: Point2D;
297
+ readonly color?: RGBA;
298
+ }
299
+ /** Marker — a reusable symbol placed at points (e.g., line endpoints, scatter glyphs). */
300
+ export interface SemanticMarker extends BaseSemantic, SemanticTransform {
301
+ readonly kind: "marker";
302
+ readonly markerId: string;
303
+ /** Positions to place copies of this marker. */
304
+ readonly positions: ReadonlyArray<Point2D>;
305
+ readonly angle?: number;
306
+ }
307
+ export type SemanticShape = SemanticPath | SemanticRect | SemanticEllipse | SemanticImage | SemanticText | SemanticMarker;
308
+ export type SemanticNode = SemanticGroup | SemanticShape;
309
+ /** The root of a semantic scene. Always a group. */
310
+ export interface SemanticScene {
311
+ /** Contract namespace this scene was built under (`/v0` before 1.0.0). */
312
+ readonly version: SceneVersion;
313
+ readonly root: SemanticGroup;
314
+ }
315
+ /** Final stroke style (resolved). */
316
+ export interface DisplayStroke {
317
+ readonly color: RGBA;
318
+ readonly width: number;
319
+ readonly dash?: ReadonlyArray<number>;
320
+ }
321
+ /** Final fill style (resolved). */
322
+ export interface DisplayFill {
323
+ readonly color: RGBA;
324
+ }
325
+ /** A resolved node — everything is final; no upstream semantics leak through. */
326
+ export interface DisplayNodeBase {
327
+ /** Fully composed transform (local * parent chain). */
328
+ readonly worldTransform: Affine2D;
329
+ /** Inherited-and-intersected clip rect (if any). */
330
+ readonly worldClip?: BoundsRect;
331
+ /** Final axis-aligned bounds in world space. */
332
+ readonly bounds: BoundsRect;
333
+ /** Stable domain id — present only when the host resolved with
334
+ * `preserveNodeIds`, so interactive hosts can bind DOM elements back to
335
+ * semantic identity. Renderers never depend on it. */
336
+ readonly id?: string;
337
+ }
338
+ export interface DisplayGroup extends DisplayNodeBase {
339
+ readonly kind: "group";
340
+ readonly children: ReadonlyArray<DisplayNode>;
341
+ }
342
+ export interface DisplayPath extends DisplayNodeBase {
343
+ readonly kind: "path";
344
+ readonly path: Path;
345
+ readonly stroke?: DisplayStroke;
346
+ readonly fill?: DisplayFill;
347
+ }
348
+ export interface DisplayRect extends DisplayNodeBase {
349
+ readonly kind: "rect";
350
+ readonly x: number;
351
+ readonly y: number;
352
+ readonly w: number;
353
+ readonly h: number;
354
+ readonly rx: number;
355
+ readonly ry: number;
356
+ readonly stroke?: DisplayStroke;
357
+ readonly fill?: DisplayFill;
358
+ }
359
+ export interface DisplayEllipse extends DisplayNodeBase {
360
+ readonly kind: "ellipse";
361
+ readonly cx: number;
362
+ readonly cy: number;
363
+ readonly rx: number;
364
+ readonly ry: number;
365
+ readonly stroke?: DisplayStroke;
366
+ readonly fill?: DisplayFill;
367
+ }
368
+ export interface DisplayImage extends DisplayNodeBase {
369
+ readonly kind: "image";
370
+ readonly resourceRef: string;
371
+ readonly x: number;
372
+ readonly y: number;
373
+ readonly w: number;
374
+ readonly h: number;
375
+ }
376
+ export interface DisplayText extends DisplayNodeBase {
377
+ readonly kind: "text";
378
+ readonly text: string;
379
+ /** CSS font string — host-formatted from FontSpec. */
380
+ readonly fontCss: string;
381
+ readonly anchor: {
382
+ x: number;
383
+ y: number;
384
+ };
385
+ readonly color: RGBA;
386
+ }
387
+ export type DisplayNode = DisplayGroup | DisplayPath | DisplayRect | DisplayEllipse | DisplayImage | DisplayText;
388
+ /** The root of a display scene. Always a group. */
389
+ export interface DisplayScene {
390
+ /** Contract namespace this scene was resolved under (`/v0` before 1.0.0). */
391
+ readonly version: SceneVersion;
392
+ readonly root: DisplayGroup;
393
+ /** Optional background color. */
394
+ readonly background?: RGBA;
395
+ /** Logical canvas dimensions. */
396
+ readonly width: number;
397
+ readonly height: number;
398
+ }
399
+ /** Validate a SemanticScene against the scene contract. An empty result means
400
+ * the scene is conformant. */
401
+ export declare function validateScene(scene: SemanticScene): ReadonlyArray<Diagnostic>;
402
+ /** Resolve options — currently minimal; host extensions may add font metrics
403
+ * providers or resource loaders in future. */
404
+ export interface ResolveOptions {
405
+ /** Logical canvas width for the root display scene. */
406
+ width?: number;
407
+ /** Logical canvas height for the root display scene. */
408
+ height?: number;
409
+ /** Keep the semantic stable id on each display node. Off by default so
410
+ * the display scene stays domain-free; interactive hosts opt in to bind
411
+ * rendered DOM elements back to semantic identity (hit highlight,
412
+ * selection). */
413
+ preserveNodeIds?: boolean;
414
+ }
415
+ /** Estimate a text block's size without a font measurement provider.
416
+ * This is a deterministic approximation that marks the current limitation,
417
+ * not real metrics: browser font metrics are only available after
418
+ * `document.fonts.ready`, so a host needing tight bounds must re-measure
419
+ * there instead of trusting these numbers.
420
+ * Width = widest line's summed glyph advances (wide CJK glyphs 1 em,
421
+ * half-width glyphs 0.6 em), height = line count × size × 1.2. */
422
+ export declare function estimateTextSize(text: string, sizePx: number): {
423
+ width: number;
424
+ height: number;
425
+ };
426
+ /** Truncate `text` so its estimated width fits `maxWidth`, appending `…` when
427
+ * characters were dropped. The longest prefix that still fits is kept; when
428
+ * even the ellipsis does not fit, the result is empty. Truncation and bounds
429
+ * share one advance model, so they can never disagree. */
430
+ export declare function truncateToWidth(text: string, maxWidth: number, sizePx: number): string;
431
+ /** Resolve a SemanticScene into a DisplayScene.
432
+ *
433
+ * The returned DisplayScene is fully resolved: every transform is composed,
434
+ * every clip is inherited, every bounds is final. Domain semantics (id,
435
+ * source ref, role) are intentionally stripped — use SemanticScene for
436
+ * provenance/debug/hit-test target lookup. */
437
+ export declare function resolve(scene: SemanticScene, opts?: ResolveOptions): DisplayScene;
438
+ /** Render options for the SVG target. */
439
+ export interface RenderSvgOptions {
440
+ /** Prefix prepended to every generated resource id (`clip-…`).
441
+ * Hosts embedding several scenes in one document must pass an
442
+ * instance-unique prefix so ids never collide across charts.
443
+ * The default is empty, keeping ids local to a standalone document. */
444
+ readonly resourceIdPrefix?: string;
445
+ }
446
+ /** Resolve the resource-id prefix for one rendered scene.
447
+ *
448
+ * Contract: the prefix must be regenerated deterministically from the
449
+ * declarative inputs of the component, never from a per-process counter —
450
+ * SSR and client hydration of the same inputs then agree on every id. When
451
+ * the host needs absolute uniqueness (several identical scenes in one
452
+ * document), it passes an explicit prefix; `renderSvg` still validates the
453
+ * safe-token shape at the boundary. */
454
+ export declare function resolveResourceIdPrefix(family: string, identity: unknown, explicit?: string | null): string;
455
+ /** Serialize a resolved DisplayScene to an SVG document string. */
456
+ export declare function renderSvg(scene: DisplayScene, options?: RenderSvgOptions): string;
457
+ /** The minimal 2D surface `renderCanvas` needs — structurally compatible
458
+ * with `CanvasRenderingContext2D`, trivially stubbable for tests. */
459
+ export interface Canvas2DLike {
460
+ fillStyle: unknown;
461
+ strokeStyle: unknown;
462
+ lineWidth: number;
463
+ font: string;
464
+ textAlign: string;
465
+ textBaseline: string;
466
+ save(): void;
467
+ restore(): void;
468
+ transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
469
+ beginPath(): void;
470
+ closePath(): void;
471
+ moveTo(x: number, y: number): void;
472
+ lineTo(x: number, y: number): void;
473
+ quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
474
+ bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
475
+ ellipse(cx: number, cy: number, rx: number, ry: number, rotation: number, start: number, end: number, anticlockwise?: boolean): void;
476
+ rect(x: number, y: number, w: number, h: number): void;
477
+ clip(): void;
478
+ fill(): void;
479
+ fillRect(x: number, y: number, w: number, h: number): void;
480
+ stroke(): void;
481
+ fillText(text: string, x: number, y: number): void;
482
+ setLineDash(segments: number[]): void;
483
+ }
484
+ /** Render a resolved DisplayScene onto a 2D context. The context owns the
485
+ * pixel backing store (the caller sets canvas width/height and any DPR
486
+ * transform); this function paints in scene coordinates. */
487
+ export declare function renderCanvas(scene: DisplayScene, ctx: Canvas2DLike): void;
488
+ /** Selection — stable ids of selected nodes. */
489
+ export interface SelectionState {
490
+ readonly nodeIds: ReadonlySet<string>;
491
+ }
492
+ /** Viewport transform — pan + zoom. */
493
+ export interface ViewportState {
494
+ /** Scale factor (1 = 100%). */
495
+ readonly scale: number;
496
+ /** Translation offset in logical pixels. */
497
+ readonly tx: number;
498
+ readonly ty: number;
499
+ }
500
+ /** Brush / filter rectangle (optional). */
501
+ export interface BrushState {
502
+ readonly active: boolean;
503
+ readonly rect?: {
504
+ x: number;
505
+ y: number;
506
+ w: number;
507
+ h: number;
508
+ };
509
+ }
510
+ /** Playback / animation state (time in seconds). */
511
+ export interface TimeState {
512
+ /** Current elapsed time in seconds. */
513
+ readonly now: number;
514
+ /** Paused state. */
515
+ readonly paused: boolean;
516
+ }
517
+ /** Container dimensions — set by host on resize. */
518
+ export interface ContainerState {
519
+ readonly w: number;
520
+ readonly h: number;
521
+ }
522
+ /** Unified runtime state bag. Flat for reducer ergonomics. */
523
+ export interface RuntimeState {
524
+ /** Currently hovered node id (or null). */
525
+ readonly hoveredId: string | null;
526
+ /** Currently focused node id (or null). */
527
+ readonly focusedId: string | null;
528
+ /** Currently pressed node id (or null). */
529
+ readonly pressedId: string | null;
530
+ /** Disabled node ids. */
531
+ readonly disabledIds: ReadonlySet<string>;
532
+ readonly selection: SelectionState;
533
+ readonly viewport: ViewportState;
534
+ readonly brush: BrushState;
535
+ readonly time: TimeState;
536
+ readonly container: ContainerState;
537
+ }
538
+ /** Default initial runtime state. */
539
+ export declare function initialState(w: number, h: number): RuntimeState;
540
+ /** Pointer button. */
541
+ export type PointerButton = "primary" | "secondary" | "tertiary";
542
+ /** Normalized pointer event — single origin, no DOM. */
543
+ export interface NormalizedPointerEvent {
544
+ readonly kind: "pointer";
545
+ readonly type: "down" | "up" | "move" | "enter" | "leave";
546
+ readonly x: number;
547
+ readonly y: number;
548
+ readonly button?: PointerButton;
549
+ readonly shift?: boolean;
550
+ readonly alt?: boolean;
551
+ readonly ctrl?: boolean;
552
+ }
553
+ /** Normalized keyboard event. */
554
+ export interface NormalizedKeyboardEvent {
555
+ readonly kind: "keyboard";
556
+ readonly type: "down" | "up";
557
+ readonly key: string;
558
+ readonly shift?: boolean;
559
+ readonly alt?: boolean;
560
+ readonly ctrl?: boolean;
561
+ }
562
+ export type NormalizedEvent = NormalizedPointerEvent | NormalizedKeyboardEvent;
563
+ /** Abstract Action (user intent, NOT raw event). */
564
+ export type Action = {
565
+ readonly kind: "hover";
566
+ readonly nodeId: string | null;
567
+ } | {
568
+ readonly kind: "select-toggle";
569
+ readonly nodeId: string;
570
+ readonly additive?: boolean;
571
+ } | {
572
+ readonly kind: "selection-set";
573
+ readonly nodeIds: readonly string[];
574
+ } | {
575
+ readonly kind: "clear-selection";
576
+ } | {
577
+ readonly kind: "viewport-pan";
578
+ readonly dx: number;
579
+ readonly dy: number;
580
+ } | {
581
+ readonly kind: "viewport-zoom";
582
+ readonly delta: number;
583
+ } | {
584
+ readonly kind: "container-resize";
585
+ readonly w: number;
586
+ readonly h: number;
587
+ } | {
588
+ readonly kind: "time-set";
589
+ readonly now: number;
590
+ } | {
591
+ readonly kind: "time-toggle-pause";
592
+ };
593
+ /** Reducer — pure, returns new state. */
594
+ export declare function reduce(state: RuntimeState, action: Action): RuntimeState;
595
+ /** Dispatch a pointer event — hit test target → produce Action.
596
+ * Host provides hitTest function (overload point for domain-specific targetting). */
597
+ export declare function dispatchPointer(state: RuntimeState, ev: NormalizedPointerEvent, hitTest: (x: number, y: number) => string | null): Action | null;
598
+ /** Invalidation category. */
599
+ export type InvalidationCategory = "overlay" | "style" | "viewport" | "measurement" | "layout" | "data" | "motion";
600
+ /** A set of nodes grouped by invalidation category. */
601
+ export interface InvalidationSet {
602
+ /** Categories to re-run. */
603
+ readonly categories: ReadonlySet<InvalidationCategory>;
604
+ /** Optional explicit node ids (if empty, category applies to all nodes). */
605
+ readonly nodeIds?: ReadonlySet<string>;
606
+ }
607
+ /** Empty invalidation set — nothing to recompile. */
608
+ export declare const EMPTY_INVALIDATION: InvalidationSet;
609
+ /** Union two invalidation sets. */
610
+ export declare function unionInvalidation(a: InvalidationSet, b: InvalidationSet): InvalidationSet;
611
+ /** Derive invalidation from an action. */
612
+ export declare function deriveInvalidation(action: Action): InvalidationSet;
613
+ /** A matched pair across two scenes. */
614
+ export interface SceneMatch {
615
+ readonly id: string;
616
+ readonly from: DisplayNode | null;
617
+ readonly to: DisplayNode | null;
618
+ }
619
+ /** Match nodes between two scenes by node id (stable identity). */
620
+ export declare function matchScenes(prev: DisplayScene | null, next: DisplayScene): ReadonlyArray<SceneMatch>;
621
+ /** Easing function — t ∈ [0, 1] → t ∈ [0, 1]. */
622
+ export type EasingFn = (t: number) => number;
623
+ /** Preset easing names. */
624
+ export type EasingPreset = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out";
625
+ /** Animatable property. */
626
+ export type AnimatableProp = "x" | "y" | "w" | "h" | "cx" | "cy" | "rx" | "ry" | "opacity" | "color" | "transform";
627
+ /** One property animation segment. */
628
+ export interface PropertyAnim {
629
+ readonly prop: AnimatableProp;
630
+ readonly from: number | RGBA;
631
+ readonly to: number | RGBA;
632
+ readonly durationMs: number;
633
+ readonly easing: EasingPreset | EasingFn;
634
+ }
635
+ /** A full transition plan for one node id. */
636
+ export interface TransitionPlan {
637
+ readonly id: string;
638
+ readonly kind: "enter" | "exit" | "update" | "no-op";
639
+ /** Total duration ms (0 if enter with no from). */
640
+ readonly durationMs: number;
641
+ readonly properties: ReadonlyArray<PropertyAnim>;
642
+ }
643
+ /** Build transition plans from scene match results. */
644
+ export declare function planTransition(from: DisplayNode | null, to: DisplayNode | null, id: string): TransitionPlan;
645
+ /** Interruption — a running transition can be cancelled and replaced. */
646
+ export interface InterruptConfig {
647
+ /** When true, cancels the old transition immediately. */
648
+ readonly cancel: boolean;
649
+ /** When true, starts the new transition from the current rendered state. */
650
+ readonly fromCurrentFrame: boolean;
651
+ }
652
+ /** A running timeline — tracks elapsed time and transition plans. */
653
+ export interface Timeline {
654
+ readonly plans: ReadonlyArray<TransitionPlan>;
655
+ /** Start time (monotonic seconds). */
656
+ readonly startedAt: number;
657
+ /** Whether the timeline has ended. */
658
+ readonly done: boolean;
659
+ }
660
+ /** Create a timeline from a set of transition plans. */
661
+ export declare function createTimeline(plans: ReadonlyArray<TransitionPlan>, startedAt?: number): Timeline;
662
+ /** Sample the timeline at a given time. Returns per-node progress values ∈ [0, 1]. */
663
+ export declare function sample(timeline: Timeline, timeSec: number): ReadonlyMap<string, number>;
664
+ /** Default interruption — cancel and start from current frame. */
665
+ export declare const DEFAULT_INTERRUPT: InterruptConfig;
666
+ /** Semantic kind of a data field. */
667
+ export type FieldSemantic = "nominal" | "ordinal" | "quantitative" | "temporal" | "unknown";
668
+ /** A column in the snapshot — typed array with semantic hint. */
669
+ export interface DataColumn {
670
+ readonly name: string;
671
+ readonly semantic: FieldSemantic;
672
+ readonly values: ReadonlyArray<number | string | boolean | null>;
673
+ }
674
+ /** Columnar snapshot. All columns share the same row count. */
675
+ export interface DataSnapshot {
676
+ readonly columns: ReadonlyArray<DataColumn>;
677
+ /** Row count (derived from first column). */
678
+ readonly rowCount: number;
679
+ }
680
+ /** Build a DataSnapshot from rows of key-value objects. */
681
+ export declare function fromRows(rows: ReadonlyArray<Record<string, unknown>>): DataSnapshot;
682
+ /** Get a column by name. */
683
+ export declare function column(snap: DataSnapshot, name: string): DataColumn | undefined;
684
+ /** Scale family. */
685
+ export type ScaleKind = "linear" | "band" | "point" | "log" | "quantile";
686
+ /** Continuous domain → continuous range. */
687
+ export interface LinearScale {
688
+ readonly kind: "linear";
689
+ readonly domain: [
690
+ number,
691
+ number
692
+ ];
693
+ readonly range: [
694
+ number,
695
+ number
696
+ ];
697
+ /** Clip to range when true (default true). */
698
+ readonly clamp?: boolean;
699
+ }
700
+ /** Discrete domain → continuous range with padding. */
701
+ export interface BandScale {
702
+ readonly kind: "band";
703
+ readonly domain: ReadonlyArray<string>;
704
+ readonly range: [
705
+ number,
706
+ number
707
+ ];
708
+ readonly padding?: number;
709
+ }
710
+ /** Like band but points are center-aligned (no bandwidth). */
711
+ export interface PointScale {
712
+ readonly kind: "point";
713
+ readonly domain: ReadonlyArray<string>;
714
+ readonly range: [
715
+ number,
716
+ number
717
+ ];
718
+ readonly padding?: number;
719
+ }
720
+ /** Logarithmic continuous domain → continuous range. */
721
+ export interface LogScale {
722
+ readonly kind: "log";
723
+ readonly domain: [
724
+ number,
725
+ number
726
+ ];
727
+ readonly range: [
728
+ number,
729
+ number
730
+ ];
731
+ readonly base?: number;
732
+ }
733
+ /** Quantile — maps sorted quantitative domain values to discrete thresholds. */
734
+ export interface QuantileScale {
735
+ readonly kind: "quantile";
736
+ readonly domain: ReadonlyArray<number>;
737
+ readonly range: ReadonlyArray<number>;
738
+ }
739
+ export type Scale = LinearScale | BandScale | PointScale | LogScale | QuantileScale;
740
+ export declare function apply(s: Scale, value: number | string): number;
741
+ /** Bandwidth for band scales (0 for others). */
742
+ export declare function bandwidth(s: Scale): number;
743
+ /** 4–6 evenly spaced "nice" values covering the domain (single value when
744
+ * flat). Tick placement is derived from the domain, never from a hardcoded
745
+ * list, so axes stay honest when data changes. */
746
+ export declare function niceLinearTicks(domain: [
747
+ number,
748
+ number
749
+ ]): {
750
+ values: number[];
751
+ decimals: number;
752
+ };
753
+ /** Minimal-decimal label for a tick value — trailing zeros dropped, never
754
+ * `-0`, never a floating point tail. */
755
+ export declare function formatTickLabel(value: number, decimals: number): string;
756
+ export type AggregateKind = "count" | "sum" | "mean" | "min" | "max" | "median";
757
+ /** Type-7 quantile (R / numpy default): h = 1 + (n-1)p, linear interpolation
758
+ * between the bracketing order statistics. `sorted` must be ascending. */
759
+ export declare function quantile(sorted: ReadonlyArray<number>, p: number): number;
760
+ /** Five-number summary for one boxplot group. Whiskers are the most extreme
761
+ * points inside the 1.5·IQR fences; anything beyond is an outlier. */
762
+ export interface BoxStats {
763
+ readonly low: number;
764
+ readonly q1: number;
765
+ readonly median: number;
766
+ readonly q3: number;
767
+ readonly high: number;
768
+ readonly n: number;
769
+ readonly outliers: ReadonlyArray<number>;
770
+ }
771
+ export declare function boxStats(values: ReadonlyArray<number | string | boolean | null>): BoxStats | null;
772
+ /** One histogram bin — half-open [x0, x1) except the last bin, which is
773
+ * closed so the maximum value lands inside a real bin. */
774
+ export interface HistogramBin {
775
+ readonly x0: number;
776
+ readonly x1: number;
777
+ readonly count: number;
778
+ }
779
+ export interface HistogramResult {
780
+ readonly bins: ReadonlyArray<HistogramBin>;
781
+ readonly binWidth: number;
782
+ }
783
+ /** Bin finite values into equal-width bins. The width targets the
784
+ * Freedman–Diaconis rule, falls back to sqrt(n), and is snapped to a nice
785
+ * 1/2/5·10^k step so axis ticks stay honest. Edges align to bin-width
786
+ * multiples. Flat data collapses into a single bin. */
787
+ export declare function binValues(values: ReadonlyArray<number | string | boolean | null>, maxBins?: number): HistogramResult;
788
+ /** Silverman's rule-of-thumb bandwidth for Gaussian KDE: 0.9·min(σ, IQR/1.34)·n^(−1/5).
789
+ * Degenerate spreads fall back to range/20 so the kernel never collapses. */
790
+ export declare function silvermanBandwidth(values: ReadonlyArray<number | string | boolean | null>): number;
791
+ /** Gaussian kernel density estimate on a shared grid. The area under the
792
+ * returned curve integrates to 1 (up to grid resolution). */
793
+ export declare function kde(values: ReadonlyArray<number | string | boolean | null>, grid: ReadonlyArray<number>, bandwidth: number): number[];
794
+ /** Competition ranking ("1224"): ties share the minimum rank, rank 1 is the
795
+ * largest value. Non-finite values get no rank. */
796
+ export declare function rankDescending(values: ReadonlyArray<number>): Map<number, number>;
797
+ /** Compute aggregate over a numeric column. Only finite numbers are usable —
798
+ * nulls, non-numeric cells and ±Infinity / NaN are skipped, matching how
799
+ * `compile` reads quantitative columns, so every result stays finite. */
800
+ export declare function aggregate(values: ReadonlyArray<number | string | boolean | null>, kind: AggregateKind): number;
801
+ /** Mark kind (geometric primitive family). Only marks with real scene
802
+ * geometry are listed — an authoring surface can never name a mark the
803
+ * engine would silently drop. */
804
+ export type MarkKind = "point" | "line" | "rect" | "bar" | "circle" | "area" | "pie" | "radar" | "heatmap" | "candlestick" | "boxplot" | "histogram" | "waterfall" | "funnel" | "gauge" | "sankey" | "treemap" | "ridgeline" | "bump" | "slope" | "rose" | "radial-bar" | "bullet" | "violin" | "streamgraph" | "mosaic" | "calendar" | "sunburst" | "dumbbell" | "lollipop" | "strip" | "beeswarm" | "gantt" | "tree" | "force" | "parallel" | "hexbin" | "contour" | "chord" | "geo";
805
+ /** Encoding channel — how a data field maps to a visual property. */
806
+ export interface EncodingChannel {
807
+ /** Field name in DataSnapshot. */
808
+ readonly field: string;
809
+ /** Visual channel: x, y, color, size, shape, opacity, text... */
810
+ readonly channel: string;
811
+ }
812
+ /** Chart authoring spec (Vega-Lite-lite). */
813
+ export interface ChartSpec {
814
+ readonly mark: MarkKind;
815
+ readonly encoding: ReadonlyArray<EncodingChannel>;
816
+ /** Optional explicit scale overrides. */
817
+ readonly scales?: ReadonlyMap<string, Scale>;
818
+ /** Facet field (optional — the scene builder lays out one small-multiple
819
+ * panel per facet value, sharing scales across panels). */
820
+ readonly facetField?: string;
821
+ /** How grouped (series) marks share the x slot. `undefined` is the
822
+ * natural per-mark default: `bar`/`rect` dodge side by side, everything
823
+ * else overlaps. `stack` accumulates positive and negative values
824
+ * separately from the zero baseline (bars and areas only). `percent`
825
+ * normalizes each x slot's stack into a shared 0–100 percent domain
826
+ * (bars and areas only, negative values are dropped with a warning). */
827
+ readonly seriesLayout?: "overlap" | "stack" | "dodge" | "percent";
828
+ /** Pie only: inner radius as a fraction of the outer radius (0 = pie,
829
+ * 0.55–0.75 reads as a donut). */
830
+ readonly innerRadiusRatio?: number;
831
+ /** Field whose value names each row. Marks carry this key as identity, so
832
+ * re-sorting or filtering rows never renumbers them. Without `keyField`
833
+ * keys are positional (`"0"`, `"1"`, …) and only stable while the row
834
+ * order is. */
835
+ readonly keyField?: string;
836
+ /** Treemap only: field naming each row's parent id (`keyField` names the
837
+ * row's own id). Rows whose parent is absent or unknown hang at the
838
+ * root level with a warning. */
839
+ readonly parentField?: string;
840
+ /** Treemap only: how many levels get their own rect. The document root
841
+ * (or, when drilled, the drill root's direct children) is level 1.
842
+ * Omitted means every level is drawn. */
843
+ readonly treemapDepth?: number;
844
+ /** Treemap only: rects smaller than this many px² are omitted instead of
845
+ * painted as invisible slivers. Defaults to 4 px² and always keeps the
846
+ * largest item of a level, so a level never vanishes entirely. */
847
+ readonly treemapMinArea?: number;
848
+ /** Treemap only: id of the node rendered as the root — the drill-down
849
+ * surface. An unknown id raises a diagnostic and the chart stays at the
850
+ * document root. */
851
+ readonly treemapRoot?: string;
852
+ /** Gauge only: the [min, max] the sweep spans; defaults to [0, 100]. */
853
+ readonly valueDomain?: readonly [
854
+ number,
855
+ number
856
+ ];
857
+ /** Sparkline mode: strip axes, grid and legend for tiny inline charts. */
858
+ readonly spark?: boolean;
859
+ /** Tree only: layout variant. `tidy` (default) packs parents over their
860
+ * children; `dendrogram` aligns every leaf on the deepest column;
861
+ * `radial` maps depth to radius and leaf order to angle. */
862
+ readonly treeLayout?: "tidy" | "dendrogram" | "radial";
863
+ /** Parallel coordinates only: ordered quantitative fields, one axis per
864
+ * entry. This is the multi-axis authoring surface — encodings only carry
865
+ * the optional `color` series. */
866
+ readonly dimensions?: ReadonlyArray<string>;
867
+ /** Geo choropleth only: basemap resource id (registered by the host) and
868
+ * the projection to fit it with. */
869
+ readonly geo?: {
870
+ readonly map: string;
871
+ readonly projection: "mercator" | "equirectangular" | "albers";
872
+ };
873
+ }
874
+ /** Series (grouping) domain resolved once by `compile`. */
875
+ export interface SeriesDomain {
876
+ /** Encoding field that groups marks, or null when ungrouped. */
877
+ readonly field: string | null;
878
+ /** Group values in first-appearance order — legend and palette share it. */
879
+ readonly categories: ReadonlyArray<string>;
880
+ }
881
+ /** One resolved mark instance in the plan — will become one Scene node. */
882
+ export interface PlanMark {
883
+ /** Row index in the resolved data. */
884
+ readonly rowIndex: number;
885
+ /** Stable row identity — `keyField` value, or the row index as a string.
886
+ * Duplicated keys are disambiguated with a `~rowIndex` suffix and
887
+ * reported as `davinci.chart.duplicate-key`. */
888
+ readonly key: string;
889
+ /** Series group this row belongs to (stringified), null when ungrouped. */
890
+ readonly series: string | null;
891
+ /** Encoded channel values (scale-applied). */
892
+ readonly channels: ReadonlyMap<string, number | string>;
893
+ /** Stacked layout only: the data-unit baseline this mark starts from
894
+ * (cumulative sum of same-sign values below it in its x slot). */
895
+ readonly stackBase?: number;
896
+ }
897
+ /** Full compile plan — scene builder consumes this. */
898
+ export interface ChartCompilePlan {
899
+ readonly spec: ChartSpec;
900
+ readonly resolvedData: DataSnapshot;
901
+ readonly scales: ReadonlyMap<string, Scale>;
902
+ readonly marks: ReadonlyArray<PlanMark>;
903
+ /** Resolved grouping domain — the scene never re-reads the series column. */
904
+ readonly series: SeriesDomain;
905
+ /** Statistic snapshot produced at compile time (histogram bins, boxplot
906
+ * five-number summaries, ridgeline density grid). Marks of stat-driven
907
+ * kinds index into THIS snapshot; `null` for marks that position raw
908
+ * rows. The scene and hosts read it as data, never recompute it. */
909
+ readonly stat: DataSnapshot | null;
910
+ /** Data problems found while compiling — row-level, never fatal to the host. */
911
+ readonly diagnostics: DiagnosticSet;
912
+ }
913
+ /** Resolve the effective series layout. `undefined` is the natural per-mark
914
+ * default: grouped bars dodge, everything else overlaps. */
915
+ export declare function resolveSeriesLayout(spec: ChartSpec, hasSeries: boolean): "overlap" | "stack" | "dodge" | "percent";
916
+ /** Compile a ChartSpec against a DataSnapshot. */
917
+ export declare function compile(spec: ChartSpec, data: DataSnapshot): ChartCompilePlan;
918
+ /** Presentation tokens `buildScene` consumes. */
919
+ export interface ChartTheme {
920
+ /** Categorical palette for grouped marks. The index of a series follows
921
+ * its position in `ChartCompilePlan.series.categories` (first-appearance
922
+ * order) and wraps around, so every series is visually distinct up to
923
+ * the palette length. */
924
+ readonly seriesPalette: ReadonlyArray<RGBA>;
925
+ /** Fill for ungrouped marks (no series / color / group encoding). */
926
+ readonly markFill: RGBA;
927
+ /** Optional caller-supplied category → color map (treemap groups and
928
+ * categorical marks keyed by a `color` field). Categories missing from
929
+ * the map fall back to `seriesPalette`, indexed by sorted category order
930
+ * so reordering rows never recolors a node. */
931
+ readonly categoryColors?: ReadonlyMap<string, RGBA>;
932
+ /** Axis baseline and tick stroke. */
933
+ readonly axisStroke: RGBA;
934
+ readonly axisStrokeWidth: number;
935
+ /** Grid line stroke — lighter than the axis so data stays on top of the
936
+ * visual hierarchy. `null` disables grid emission. */
937
+ readonly gridStroke: RGBA | null;
938
+ readonly gridStrokeWidth: number;
939
+ /** Tick and legend label color. */
940
+ readonly labelColor: RGBA;
941
+ /** Tick label font — also drives padding and truncation widths. */
942
+ readonly labelFont: FontSpec;
943
+ /** Legend label font. */
944
+ readonly legendFont: FontSpec;
945
+ /** Stroke painted around point marks so overlapping glyphs stay
946
+ * separable; usually the plot background color. `null` disables it. */
947
+ readonly pointStroke: RGBA | null;
948
+ /** Opacity of the area-mark fill (the stroke keeps full strength). */
949
+ readonly areaFillOpacity: number;
950
+ /** Sequential ramp for value→color marks (heatmap): ≥2 stops, sampled at
951
+ * t ∈ [0, 1] from the data minimum to the maximum. */
952
+ readonly heatmapRamp: ReadonlyArray<RGBA>;
953
+ /** Rising fill for candlestick bodies and waterfall positive deltas. */
954
+ readonly upColor: RGBA;
955
+ /** Falling fill for candlestick bodies and waterfall negative deltas. */
956
+ readonly downColor: RGBA;
957
+ /** Unfilled track ring / sweep color for gauge and radial-bar marks. */
958
+ readonly trackColor: RGBA;
959
+ /** Qualitative band tints for bullet charts, poor → good. */
960
+ readonly rangeTints: readonly [
961
+ RGBA,
962
+ RGBA,
963
+ RGBA
964
+ ];
965
+ /** Opacity of sankey link ribbons (nodes stay at full strength). */
966
+ readonly sankeyLinkOpacity: number;
967
+ }
968
+ /** The reference light theme — VMZ brand blue anchors the categorical
969
+ * palette, grids stay quieter than axes, and axes stay quieter than data. */
970
+ export declare const DEFAULT_CHART_THEME: ChartTheme;
971
+ /** Dark theme — same palette roles with lifted brightness and quiet chrome. */
972
+ export declare const DARK_CHART_THEME: ChartTheme;
973
+ /** Plot padding in logical pixels. */
974
+ export interface ScenePadding {
975
+ readonly top: number;
976
+ readonly right: number;
977
+ readonly bottom: number;
978
+ readonly left: number;
979
+ }
980
+ /** Viewport the scene is laid out into. */
981
+ export interface ChartViewport {
982
+ readonly width: number;
983
+ readonly height: number;
984
+ /** Uniform padding or per-side override. */
985
+ readonly padding?: number | Partial<ScenePadding>;
986
+ }
987
+ /** Options for the scene build. */
988
+ export interface ChartSceneOptions {
989
+ /** Presentation tokens; defaults to `DEFAULT_CHART_THEME`. */
990
+ readonly theme?: ChartTheme;
991
+ }
992
+ /** Build a SemanticScene from a ChartCompilePlan and a pixel viewport. */
993
+ export declare function buildScene(plan: ChartCompilePlan, viewport: ChartViewport, options?: ChartSceneOptions): SemanticScene;
994
+ /** GeoJSON feature shape the geo mark projects. */
995
+ export interface GeoFeature {
996
+ readonly type: "Feature";
997
+ readonly properties: {
998
+ readonly name: string;
999
+ readonly iso_a3: string;
1000
+ };
1001
+ readonly geometry: {
1002
+ readonly type: "Polygon";
1003
+ readonly coordinates: ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>;
1004
+ } | {
1005
+ readonly type: "MultiPolygon";
1006
+ readonly coordinates: ReadonlyArray<ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>>;
1007
+ };
1008
+ }
1009
+ export interface GeoFeatureCollection {
1010
+ readonly type: "FeatureCollection";
1011
+ readonly features: ReadonlyArray<GeoFeature>;
1012
+ }
1013
+ /** Register a basemap under an id (host side, at startup / build time). */
1014
+ export declare function registerGeoMap(id: string, map: GeoFeatureCollection): void;
1015
+ /** Look a basemap up by id; undefined when the host never registered it. */
1016
+ export declare function geoMapById(id: string): GeoFeatureCollection | undefined;
1017
+ /** Diagram kind hints the layout engine. */
1018
+ export type DiagramKind = "flowchart" | "sequence" | "class" | "graph" | "custom";
1019
+ /** Direction hint for flowchart layouts. */
1020
+ export type FlowDirection = "LR" | "RL" | "TB" | "BT";
1021
+ /** Port anchor on a node — edge attaches here. */
1022
+ export interface PortSpec {
1023
+ readonly id: string;
1024
+ /** Side of the node (approximate; layout may adjust). */
1025
+ readonly side: "top" | "bottom" | "left" | "right";
1026
+ /** Optional label text. */
1027
+ readonly label?: string;
1028
+ /** Offset from center in pixels (layout-adjusted during resolve). */
1029
+ readonly offsetX?: number;
1030
+ readonly offsetY?: number;
1031
+ }
1032
+ /** A node in the diagram graph. */
1033
+ export interface DiagramNodeSpec {
1034
+ readonly id: string;
1035
+ /** Text shown inside the node. */
1036
+ readonly label?: string;
1037
+ /** Optional initial size hint (in layout units). Overridden by layout. */
1038
+ readonly sizeHint?: {
1039
+ w: number;
1040
+ h: number;
1041
+ };
1042
+ /** Optional initial position hint (absolute coords). Layout may ignore. */
1043
+ readonly positionHint?: {
1044
+ x: number;
1045
+ y: number;
1046
+ };
1047
+ /** Side-specific ports. */
1048
+ readonly ports?: ReadonlyArray<PortSpec>;
1049
+ /** Sub-type hint (shape/style for flowchart nodes like diamond, rounded). */
1050
+ readonly nodeKind?: "rect" | "diamond" | "circle" | "ellipse" | "hexagon" | "subgraph" | "custom";
1051
+ }
1052
+ /** An edge connects two ports (or node centers if ports absent). */
1053
+ export interface DiagramEdgeSpec {
1054
+ readonly id: string;
1055
+ readonly fromNode: string;
1056
+ readonly fromPort?: string;
1057
+ readonly toNode: string;
1058
+ readonly toPort?: string;
1059
+ /** Edge label text (optional). */
1060
+ readonly label?: string;
1061
+ /** Style hint: "solid" | "dashed" | "dotted" | "thick" | "arrow" | "bidirectional" | "no-arrow". */
1062
+ readonly edgeKind?: "solid" | "dashed" | "dotted" | "thick" | "arrow" | "bidirectional" | "no-arrow";
1063
+ }
1064
+ /** A cluster groups nodes for visual enclosure (e.g., flowchart subgraph). */
1065
+ export interface DiagramClusterSpec {
1066
+ readonly id: string;
1067
+ readonly label?: string;
1068
+ readonly nodeIds: ReadonlyArray<string>;
1069
+ }
1070
+ /** A layout constraint (soft hint — layout engine may ignore). */
1071
+ export type DiagramConstraint = {
1072
+ readonly kind: "ordering";
1073
+ readonly before: string;
1074
+ readonly after: string;
1075
+ } | {
1076
+ readonly kind: "same-layer";
1077
+ readonly nodeIds: ReadonlyArray<string>;
1078
+ } | {
1079
+ readonly kind: "separation";
1080
+ readonly nodeA: string;
1081
+ readonly nodeB: string;
1082
+ readonly minGap: number;
1083
+ };
1084
+ /** Full diagram domain input. */
1085
+ export interface DiagramSpec {
1086
+ readonly kind: DiagramKind;
1087
+ readonly direction?: FlowDirection;
1088
+ readonly nodes: ReadonlyArray<DiagramNodeSpec>;
1089
+ readonly edges: ReadonlyArray<DiagramEdgeSpec>;
1090
+ readonly clusters?: ReadonlyArray<DiagramClusterSpec>;
1091
+ readonly constraints?: ReadonlyArray<DiagramConstraint>;
1092
+ }
1093
+ /** Compute bounds of a DiagramSpec based on position hints and size hints.
1094
+ * Returns empty rect if no hints are present (caller should use layout output). */
1095
+ export declare function specBounds(spec: DiagramSpec): BoundsRect;
1096
+ /** A placed node from layout. */
1097
+ export interface LayoutedNode {
1098
+ readonly id: string;
1099
+ /** Final bounds (after layout). */
1100
+ readonly bounds: BoundsRect;
1101
+ /** Optional layer index (layered layouts only). */
1102
+ readonly layer?: number;
1103
+ /** Optional column index within layer. */
1104
+ readonly column?: number;
1105
+ /** Optional port anchor points on node boundary. */
1106
+ readonly portAnchors?: ReadonlyMap<string, {
1107
+ x: number;
1108
+ y: number;
1109
+ }>;
1110
+ }
1111
+ /** A routed edge from layout — not a raw SVG path; just the control points. */
1112
+ export interface RoutedEdge {
1113
+ readonly id: string;
1114
+ readonly from: {
1115
+ x: number;
1116
+ y: number;
1117
+ };
1118
+ readonly to: {
1119
+ x: number;
1120
+ y: number;
1121
+ };
1122
+ /** Optional intermediate control points (for orthogonal or bezier routes). */
1123
+ readonly route: ReadonlyArray<{
1124
+ x: number;
1125
+ y: number;
1126
+ }>;
1127
+ }
1128
+ /** Full layout plan — scene builder consumes this. */
1129
+ export interface DiagramLayoutPlan {
1130
+ readonly nodes: ReadonlyArray<LayoutedNode>;
1131
+ readonly edges: ReadonlyArray<RoutedEdge>;
1132
+ readonly clusters: ReadonlyArray<{
1133
+ id: string;
1134
+ bounds: BoundsRect;
1135
+ }>;
1136
+ /** Overall canvas bounds. */
1137
+ readonly canvasBounds: BoundsRect;
1138
+ readonly diagnostics: DiagnosticSet;
1139
+ }
1140
+ /** Compute a simple left-to-right layered layout for flowcharts.
1141
+ * Places nodes by topological order and ranks edges backward.
1142
+ * Not optimal — produces a workable plan for basic graphs. */
1143
+ export declare function simpleLayout(spec: DiagramSpec): DiagramLayoutPlan;
1144
+ /** Presentation tokens the diagram scene builder consumes. */
1145
+ export interface DiagramTheme {
1146
+ /** Node body fill. */
1147
+ readonly nodeFill: RGBA;
1148
+ /** Node outline. */
1149
+ readonly nodeStroke: RGBA;
1150
+ readonly nodeStrokeWidth: number;
1151
+ /** Node corner radius in px. */
1152
+ readonly nodeRadius: number;
1153
+ /** Node label color and font. */
1154
+ readonly nodeLabelColor: RGBA;
1155
+ readonly nodeLabelFont: FontSpec;
1156
+ /** Edge stroke. */
1157
+ readonly edgeStroke: RGBA;
1158
+ readonly edgeStrokeWidth: number;
1159
+ /** Edge label color and font. */
1160
+ readonly edgeLabelColor: RGBA;
1161
+ readonly edgeLabelFont: FontSpec;
1162
+ /** Halo painted behind edge labels so the routed line never strikes
1163
+ * through the text. */
1164
+ readonly labelHalo: RGBA;
1165
+ }
1166
+ /** Reference light theme. */
1167
+ export declare const DEFAULT_DIAGRAM_THEME: DiagramTheme;
1168
+ /** Dark theme — quiet chrome, lifted label contrast. */
1169
+ export declare const DARK_DIAGRAM_THEME: DiagramTheme;
1170
+ /** Options for the diagram scene build. */
1171
+ export interface DiagramSceneOptions {
1172
+ /** Presentation tokens; defaults to `DEFAULT_DIAGRAM_THEME`. */
1173
+ readonly theme?: DiagramTheme;
1174
+ }
1175
+ /** Build a SemanticScene from a DiagramSpec + DiagramLayoutPlan. */
1176
+ declare function buildScene$1(spec: DiagramSpec, plan: DiagramLayoutPlan, options?: DiagramSceneOptions): SemanticScene;
1177
+ /** Raw Mermaid source block — host provides fence contents. */
1178
+ export interface MermaidBlock {
1179
+ readonly language: "mermaid";
1180
+ /** The fence body as raw text. */
1181
+ readonly source: string;
1182
+ /** Optional id from `%%{init: { ... }}%%` or front-matter. */
1183
+ readonly id?: string;
1184
+ }
1185
+ /** Parse a Mermaid block into a DiagramSpec.
1186
+ * Returns `undefined` + diagnostics if parsing fails.
1187
+ *
1188
+ * Currently accepts only manually-constructed specs. Full Mermaid
1189
+ * parsing is host-scope. */
1190
+ export declare function parseMermaid(_block: MermaidBlock): {
1191
+ spec?: DiagramSpec;
1192
+ diagnostics: DiagnosticSet;
1193
+ };
1194
+ /** Convenience wrapper for manually built specs (for tests / future importers). */
1195
+ export declare function fromSpec(spec: DiagramSpec): DiagramSpec;
1196
+
1197
+ export {
1198
+ TextMetrics$1 as TextMetrics,
1199
+ buildScene$1 as buildDiagramScene,
1200
+ moveTo$1 as moveTo,
1201
+ };
1202
+
1203
+ export {};