@indispec/fs-compat 0.0.0-stage → 0.1.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.
package/src/index.d.ts ADDED
@@ -0,0 +1,746 @@
1
+ /**
2
+ * Typed facade for the vendored FeatureScript engine.
3
+ *
4
+ * The implementation under `src/engine/` is JavaScript (ported verbatim from the
5
+ * featurescript-studio engine); these declarations are the contract IndiSpec code
6
+ * imports. Keep them in sync when an engine export is added or reshaped.
7
+ */
8
+
9
+ /** A 3D point or direction in millimetres. */
10
+ export type Vec3 = [number, number, number];
11
+ /** A 2D sketch-space point in millimetres. */
12
+ export type Vec2 = [number, number];
13
+
14
+ /** A FeatureScript runtime error carrying source position when known. */
15
+ export class FsError extends Error {
16
+ /** 1-based line, when the parser/interpreter knew it. */
17
+ line: number | null;
18
+ /** 1-based column, when known. */
19
+ col: number | null;
20
+ constructor(message: string, line?: number | null, col?: number | null, source?: string | null);
21
+ }
22
+
23
+ /** A sketch plane: world origin plus orthonormal u/v (in-plane) and n (normal). */
24
+ export class Plane {
25
+ readonly o: Vec3;
26
+ readonly u: Vec3;
27
+ readonly v: Vec3;
28
+ readonly n: Vec3;
29
+ constructor(origin: Vec3, u: Vec3, n: Vec3);
30
+ /** World point(s) -> plane coordinates (u, v, w). */
31
+ toLocal(P: Vec3 | Vec3[]): Vec3 | Vec3[];
32
+ /** Plane coordinates -> world point(s). */
33
+ toWorld(L: Vec3 | Vec3[]): Vec3 | Vec3[];
34
+ }
35
+
36
+ /** A rigid transform: 3x3 row-major rotation + translation (mm). */
37
+ export class Xf {
38
+ readonly m: number[][];
39
+ readonly t: Vec3;
40
+ constructor(m?: number[][], t?: Vec3);
41
+ apply(P: Vec3 | Vec3[]): Vec3 | Vec3[];
42
+ applyDir(V: Vec3 | Vec3[]): Vec3 | Vec3[];
43
+ inverse(): Xf;
44
+ compose(o: Xf): Xf;
45
+ }
46
+
47
+ /** 2D profile types carried by the recorded geometry tree. */
48
+ export class Circle2 {
49
+ readonly c: Vec2;
50
+ readonly r: number;
51
+ constructor(c: Vec2, r: number);
52
+ bbox(): [Vec2, Vec2];
53
+ }
54
+
55
+ export class Rect2 {
56
+ readonly lo: Vec2;
57
+ readonly hi: Vec2;
58
+ constructor(lo: Vec2, hi: Vec2);
59
+ bbox(): [Vec2, Vec2];
60
+ }
61
+
62
+ export class Poly2 {
63
+ readonly pts: Vec2[];
64
+ constructor(pts: Vec2[]);
65
+ bbox(): [Vec2, Vec2];
66
+ }
67
+
68
+ export type Profile2 = Circle2 | Rect2 | Poly2;
69
+
70
+ /** Base of the recorded CSG node tree; every node can report an analytic bbox. */
71
+ export class Node {
72
+ bbox(): [Vec3, Vec3];
73
+ }
74
+
75
+ /** Axis-aligned block between two corners, in world millimetres. */
76
+ export class Box extends Node {
77
+ readonly lo: Vec3;
78
+ readonly hi: Vec3;
79
+ constructor(lo: Vec3, hi: Vec3);
80
+ }
81
+
82
+ /** Extrude a union of 2D profiles along the plane normal, from w0 to w1. */
83
+ export class Prism extends Node {
84
+ readonly plane: Plane;
85
+ readonly profiles: Profile2[];
86
+ readonly w0: number;
87
+ readonly w1: number;
88
+ constructor(plane: Plane, profiles: Profile2[], w0: number, w1: number);
89
+ }
90
+
91
+ /** Surface of revolution: a (radius, height) profile spun about an axis. */
92
+ export class Revolve extends Node {
93
+ readonly plane: Plane;
94
+ readonly axisO: Vec3;
95
+ readonly axisD: Vec3;
96
+ /** The profile expressed in the axis' (radius, height) frame. */
97
+ readonly poly: Circle2 | Poly2;
98
+ readonly angle: number;
99
+ constructor(plane: Plane, profile: Profile2, axisO: Vec3, axisD: Vec3, angle?: number);
100
+ }
101
+
102
+ /** Boolean union of two nodes. */
103
+ export class Union extends Node {
104
+ readonly a: Node;
105
+ readonly b: Node;
106
+ constructor(a: Node, b: Node);
107
+ }
108
+
109
+ /** Boolean subtraction (`a - b`). */
110
+ export class Diff extends Node {
111
+ readonly a: Node;
112
+ readonly b: Node;
113
+ constructor(a: Node, b: Node);
114
+ }
115
+
116
+ /** Boolean intersection of two nodes. */
117
+ export class Isect extends Node {
118
+ readonly a: Node;
119
+ readonly b: Node;
120
+ constructor(a: Node, b: Node);
121
+ }
122
+
123
+ /** A rigid transform applied to a node. */
124
+ export class Moved extends Node {
125
+ readonly node: Node;
126
+ readonly xf: Xf;
127
+ constructor(node: Node, xf: Xf);
128
+ }
129
+
130
+ /** A fillet on a body's edges (translated by the exact kernel, not the SDF path). */
131
+ export class Fillet extends Node {
132
+ readonly node: Node;
133
+ /** Fillet radius in millimetres. */
134
+ readonly radius: number;
135
+ /** World direction of the edges to fillet, or null for every edge. */
136
+ readonly direction: Vec3 | null;
137
+ constructor(node: Node, radius: number, direction?: Vec3 | null);
138
+ }
139
+
140
+ /** A loft through two or more sketch profiles (translated by the exact kernel, not the SDF path). */
141
+ export class Loft extends Node {
142
+ /** Sections in loft order; each carries the sketch plane and its single closed profile. */
143
+ readonly sections: Array<{ plane: Plane; profiles: Profile2[] }>;
144
+ constructor(sections: Array<{ plane: Plane; profiles: Profile2[] }>);
145
+ }
146
+
147
+ /** A sweep of a profile along a path (translated by the exact kernel, not the SDF path). */
148
+ export class Sweep extends Node {
149
+ /** Closed section profile. */
150
+ readonly profile: Profile2;
151
+ /** Plane carrying the profile. */
152
+ readonly plane: Plane;
153
+ /** Path points in the path plane's coordinates (a closed loop). */
154
+ readonly path: Array<[number, number]>;
155
+ /** Plane carrying the path. */
156
+ readonly pathPlane: Plane;
157
+ constructor(profile: Profile2, plane: Plane, path: Array<[number, number]>, pathPlane: Plane);
158
+ }
159
+
160
+ /** A shell (hollowed solid) on a body (translated by the exact kernel, not the SDF path). */
161
+ export class Shell extends Node {
162
+ readonly node: Node;
163
+ /** Wall thickness in millimetres. */
164
+ readonly thickness: number;
165
+ /** Planar face group removed to open the shell (`top`, `bottom`, `x` or `y`). */
166
+ readonly opening: string;
167
+ constructor(node: Node, thickness: number, opening?: string);
168
+ }
169
+
170
+ /** A chamfer on a body's edges (translated by the exact kernel, not the SDF path). */
171
+ export class Chamfer extends Node {
172
+ readonly node: Node;
173
+ /** Chamfer distance in millimetres. */
174
+ readonly distance: number;
175
+ /** World direction of the edges to chamfer, or null for every edge. */
176
+ readonly direction: Vec3 | null;
177
+ constructor(node: Node, distance: number, direction?: Vec3 | null);
178
+ }
179
+
180
+ /**
181
+ * Extrude a planar face of an existing body (translated by the exact kernel, not the SDF path).
182
+ *
183
+ * The face is addressed by a **geometric anchor** — a world point on it plus its outward normal —
184
+ * because B-rep face ids only hold within one evaluation: the exact backend re-resolves the anchor
185
+ * on every evaluation and refuses one that no longer lies on a planar face. `w0`/`w1` are signed
186
+ * distances along the resolved outward normal, so an inward extrude is a negative window.
187
+ */
188
+ export class FaceExtrude extends Node {
189
+ /** Body whose face is extruded (a recorded node reference, evaluated on demand). */
190
+ readonly node: Node;
191
+ /** World anchor point on the face, in millimetres. */
192
+ readonly point: Vec3;
193
+ /** Outward unit normal of the face at the anchor. */
194
+ readonly normal: Vec3;
195
+ /** Start offset along the outward normal (mm). */
196
+ readonly w0: number;
197
+ /** End offset along the outward normal (mm). */
198
+ readonly w1: number;
199
+ constructor(node: Node, point: Vec3, normal: Vec3, w0: number, w1: number);
200
+ }
201
+
202
+ /** A named, coloured body. `alive` is toggled by delete/boolean operations. */
203
+ export class Solid {
204
+ node: Node;
205
+ name: string | null;
206
+ color: unknown;
207
+ alive: boolean;
208
+ kind: string;
209
+ constructor(node: Node, name?: string | null, color?: unknown, kind?: string);
210
+ bbox(): [Vec3, Vec3];
211
+ }
212
+
213
+ /** The evaluated document scene: alive bodies plus the operation registry. */
214
+ export class Scene {
215
+ readonly solids: Solid[];
216
+ readonly sketches: Record<string, unknown>;
217
+ readonly registry: Record<string, Solid[]>;
218
+ readonly notes: string[];
219
+ add(solid: Solid): Solid;
220
+ alive(includeRef?: boolean): Solid[];
221
+ bbox(includeRef?: boolean): [Vec3, Vec3];
222
+ }
223
+
224
+ /** A source file supplied as an include/library to the evaluator. */
225
+ export interface FsSource {
226
+ /** Display name used in diagnostics. */
227
+ name?: string;
228
+ /** FeatureScript source text. */
229
+ source: string;
230
+ }
231
+
232
+ /** A custom feature discovered in the module. */
233
+ export interface FsFeature {
234
+ /** Feature name (`defineFeature(...)`). */
235
+ name: string;
236
+ /** Parameter defaults, insertion-ordered. */
237
+ defaults: Map<string, unknown>;
238
+ /** 1-based declaration line. */
239
+ line: number;
240
+ }
241
+
242
+ /** The interpreter state after a feature has run. */
243
+ export interface FsInterp {
244
+ /** Mutable evaluation context (`Context`). */
245
+ context: unknown;
246
+ /** The scene the feature built. */
247
+ scene: Scene;
248
+ /** Features defined in the module. */
249
+ features: Map<string, FsFeature>;
250
+ moduleEnv?: unknown;
251
+ globalEnv?: unknown;
252
+ /** Non-fatal notes raised by the program (reportFeature*, warnings). */
253
+ notes: string[];
254
+ }
255
+
256
+ /** Options accepted by {@link runFeature}. */
257
+ export interface RunFeatureOptions {
258
+ verbose?: boolean;
259
+ includes?: FsSource[] | null;
260
+ sourceName?: string;
261
+ /** Record the feature-history trace (default false). */
262
+ trace?: boolean;
263
+ /** Stop evaluation after this many recorded features (a rollback view). */
264
+ stopAfter?: number | null;
265
+ }
266
+
267
+ /** Result of {@link runFeature}. */
268
+ export interface RunFeatureResult {
269
+ interp: FsInterp;
270
+ feature: FsFeature;
271
+ definition: Map<string, unknown>;
272
+ /** Feature-history entries in execution order (empty unless `trace` was requested). */
273
+ trace: TraceEntry[];
274
+ /** True when evaluation stopped early at `stopAfter` (rollback view). */
275
+ rolledBack: boolean;
276
+ }
277
+
278
+ /** Parse a module into an AST (plain objects; see engine/parse.js). */
279
+ export function parse(source: string, sourceName?: string): unknown[];
280
+
281
+ /** Paste library sources in front of a module (the engine has no real `import`). */
282
+ export function applyIncludes(source: string, includes?: FsSource[] | null): string;
283
+
284
+ /** Run a module and call one of its custom features. */
285
+ export function runFeature(
286
+ source: string,
287
+ featureName?: string | null,
288
+ overrides?: Map<string, unknown> | null,
289
+ options?: RunFeatureOptions,
290
+ ): RunFeatureResult;
291
+
292
+ /**
293
+ * Parse `name=value` override texts into the interpreter's Map form.
294
+ *
295
+ * Values are parsed with the engine's value grammar, so `plateLen=124mm` becomes a length quantity.
296
+ * The engine has no import/preprocessor, so project value bindings reach a model through these
297
+ * overrides rather than through rewritten source (docs/VALUE-REFS.md).
298
+ */
299
+ export function parseOverrides(pairs?: readonly string[] | null): Map<string, unknown>;
300
+
301
+ /** The interpreter class (advanced use; prefer {@link runFeature}). */
302
+ export const Interp: new (sourceName?: string, verbose?: boolean) => FsInterp & {
303
+ run(stmts: unknown[]): void;
304
+ };
305
+
306
+ /** Legacy SDF sampler for parity checks only; never used by the kernel path. */
307
+ export function sdfAt(node: Node, p: Vec3): number;
308
+
309
+ /**
310
+ * One face of a sketch's planar arrangement: an outer boundary loop plus the loops directly inside
311
+ * it.
312
+ *
313
+ * Nested contours bound several faces (a ring and the disc inside it) and **overlapping contours
314
+ * split each other**, so two overlapping rectangles are three faces — each rectangle alone and their
315
+ * overlap — with any contour nested in a cell becoming that cell's hole. A face bounded by a whole
316
+ * untouched contour keeps its analytic `Circle2`/`Rect2` profile; geometry cut by an overlap is a
317
+ * sampled `Poly2` loop.
318
+ */
319
+ export interface SketchRegion {
320
+ /** Outer boundary profile (a `Circle2`, `Rect2`, or a sampled `Poly2` loop). */
321
+ outer: unknown;
322
+ /** Inner-loop profiles (the contours nested in the face, or an overlapping contour's cut-out). */
323
+ holes: unknown[];
324
+ /** Nesting depth of the outer boundary (0 = outermost). */
325
+ depth: number;
326
+ }
327
+
328
+ /** Sketch-topology helpers (see engine/regions.js). */
329
+ export const chainContours: (...args: any[]) => any;
330
+ export const nestProfiles: (...args: any[]) => any;
331
+ export const sketchRegions: (profiles: readonly unknown[]) => SketchRegion[];
332
+ export const regionArea: (region: SketchRegion) => number;
333
+ export const regionPolygon: (region: SketchRegion) => { outer: number[][]; holes: number[][][] };
334
+ export const regionContains: (region: SketchRegion, point: readonly number[]) => boolean;
335
+ export const regionInteriorPoint: (region: SketchRegion) => [number, number];
336
+ export const arcPoints: (...args: any[]) => any;
337
+ export const profilePolygon: (...args: any[]) => any;
338
+ export const profileContains: (...args: any[]) => any;
339
+ export const profileSample: (...args: any[]) => any;
340
+ export const toCCW: (points: number[][]) => number[][];
341
+ export const polygonArea: (points: number[][]) => number;
342
+ export const pointInPolygon: (point: number[], points: number[][]) => boolean;
343
+ export const interiorPoint: (points: number[][]) => [number, number];
344
+ export const JOIN_TOL: number;
345
+ export const ARC_CHORD_TOL: number;
346
+
347
+ /** Unit helpers and the value model (see engine/values.js). */
348
+ export const Q: any;
349
+ export const LEN: any;
350
+ export const ANG: any;
351
+ export const ONE: any;
352
+ export const Vec: any;
353
+ export const Id: any;
354
+ export const Color: any;
355
+ export const asQ: (...args: any[]) => any;
356
+ export const num: (...args: any[]) => any;
357
+ export const vec3mm: (...args: any[]) => any;
358
+ export const vec2mm: (...args: any[]) => any;
359
+ export const rotationMatrix: (...args: any[]) => any;
360
+
361
+ /** Lexer/parser internals. */
362
+ export const tokenize: (...args: any[]) => any;
363
+ export const KEYWORDS: any;
364
+ export const OPERATORS: any;
365
+
366
+ /** Remaining interpreter exports used by advanced tooling. */
367
+ export const Env: any;
368
+ export const Context: any;
369
+ export const Feature: any;
370
+ export const Sel: any;
371
+ export const Sketch: any;
372
+ export const Line: any;
373
+ export const parseValue: (...args: any[]) => any;
374
+ export const fmtG: (...args: any[]) => any;
375
+ export const fsStr: (...args: any[]) => any;
376
+
377
+ // ---------------------------------------------------------------------------
378
+ // Feature history (src/engine/trace.js, src/engine/project.js) and assemblies
379
+ // (src/engine/assembly.js). The history is derived per evaluation — never
380
+ // persisted — and is what the CAD editors' tree/history panes render.
381
+ // ---------------------------------------------------------------------------
382
+
383
+ /** A source location range in one file. `end` is exclusive. */
384
+ export interface SourceSpan {
385
+ /** Absolute character offset of the first token. */
386
+ start: number;
387
+ /** Absolute character offset after the last token. */
388
+ end: number;
389
+ /** 1-based line of `start`. */
390
+ line: number;
391
+ /** Source name (module, library or document path). */
392
+ file?: string;
393
+ }
394
+
395
+ /** A call frame in the program stack that led to a feature invocation. */
396
+ export interface FeatureFrame {
397
+ /** Name of the called function (`annZ`, `cylZ`, …). */
398
+ callee: string;
399
+ /** Runtime id passed to the callee, when it took one. */
400
+ id: string | null;
401
+ /** Span of the call expression. */
402
+ span: SourceSpan;
403
+ }
404
+
405
+ /** History class of a recorded invocation. */
406
+ export type FeatureKind =
407
+ | 'sketch' | 'op' | 'modifier' | 'property' | 'report' | 'instance' | 'import' | 'feature';
408
+
409
+ /** One recorded feature invocation (the flat execution log). */
410
+ export interface TraceEntry {
411
+ /** Monotonic sequence number (execution order). */
412
+ seq: number;
413
+ /** Builtin/host operation name, e.g. `opExtrude`. */
414
+ op: string;
415
+ /** History class. */
416
+ kind: FeatureKind;
417
+ /** Full runtime id path, or null when the call had no id. */
418
+ id: string | null;
419
+ /** `id` split into segments. */
420
+ path: string[];
421
+ /** Span of the call expression. */
422
+ span: SourceSpan;
423
+ /** Program stack frames (outermost first). */
424
+ frames: FeatureFrame[];
425
+ /** Serialised definition map snapshot, or null. */
426
+ definition: Record<string, unknown> | null;
427
+ /** Bodies created by this invocation. */
428
+ produced: number;
429
+ /** Live body count after the invocation. */
430
+ bodies: number;
431
+ }
432
+
433
+ /** Provenance of a projected row when it is generated rather than authored directly. */
434
+ export type GeneratedBy = 'loop' | 'repeat' | 'helper';
435
+
436
+ /** One field of a feature's definition, as the editor can display/edit it. */
437
+ export interface FeatureField {
438
+ /** Definition key (`endDepth`, `entities`, …). */
439
+ key: string;
440
+ /** 1-based source line of the value. */
441
+ line: number | null;
442
+ /** Source text of the value. */
443
+ value: string;
444
+ /** Classified value kind (`number`, `quantity`, `reference`, `call`, …). */
445
+ valueKind: string;
446
+ /** Span of the literal an edit replaces, or null when the value is computed. */
447
+ literal: { start: number; end: number } | null;
448
+ /** Whether a parameter edit can write this field back to source. */
449
+ editable: boolean;
450
+ }
451
+
452
+ /** A row of the feature-history tree rendered by a CAD editor. */
453
+ export interface FeatureRow {
454
+ /** Anchor identity (runtime id path, or `entry:<seq>`). */
455
+ id: string;
456
+ /** Execution sequence number. */
457
+ seq: number;
458
+ /** History class. */
459
+ kind: FeatureKind | 'feature';
460
+ /** Display label of the class. */
461
+ kindLabel: string;
462
+ /** Raw operation name (null on wrapper rows). */
463
+ op: string | null;
464
+ /** Display title (`Extrude`, `Boolean`, …). */
465
+ title: string;
466
+ /** Authored name — the last id path segment. */
467
+ name: string | null;
468
+ /** The helper invocation that owns this operation, when there is one. */
469
+ owner: string | null;
470
+ /** Id path segments. */
471
+ path: string[];
472
+ /** 1-based source line. */
473
+ line: number | null;
474
+ /** Span of the call expression. */
475
+ span: { start: number; end: number } | null;
476
+ /** Whole-statement span for reorder/suppress patches. */
477
+ statement: { start: number; end: number } | null;
478
+ /** Helper call frames that produced this row. */
479
+ frames: FeatureFrame[];
480
+ /** Provenance when generated rather than a unique authored call. */
481
+ generatedBy: GeneratedBy | null;
482
+ /** Bodies created by this row. */
483
+ produced: number;
484
+ /** Live bodies after this row (rollback position). */
485
+ bodies: number;
486
+ /** Definition fields. */
487
+ fields: FeatureField[];
488
+ /** Child rows (grouped granularity). */
489
+ children: FeatureRow[];
490
+ /** True when at least one field is writable. */
491
+ editable: boolean;
492
+ /** True when the row has a statement a structural patch can replace. */
493
+ structural: boolean;
494
+ /** True when the row may be moved within the program. */
495
+ reorderable: boolean;
496
+ /** Present on wrapper rows. */
497
+ grouped?: boolean;
498
+ }
499
+
500
+ /** Options for {@link projectFeatureList}. */
501
+ export interface ProjectFeatureListOptions {
502
+ /** Parsed module (needed for fields and statement spans). */
503
+ ast?: unknown[] | null;
504
+ /** Source text the spans index into. */
505
+ source?: string;
506
+ /** Group by authored feature (default) or show every op. */
507
+ granularity?: 'feature' | 'op';
508
+ /** Include `reportFeature*` notes as rows. */
509
+ includeReports?: boolean;
510
+ /** Include sketch creation as rows. */
511
+ includeSketches?: boolean;
512
+ }
513
+
514
+ /** A projected assembly instance row. */
515
+ export interface AssemblyRow {
516
+ id: string | null;
517
+ seq: number;
518
+ kind: 'instance';
519
+ kindLabel: string;
520
+ title: string;
521
+ name: string | null;
522
+ part: { name: string; page: string | null; hash: string | null };
523
+ translate: [number, number, number];
524
+ rotation: number[][];
525
+ fields: Array<{ key: string; value: string; editable: false }>;
526
+ }
527
+
528
+ /** A reference to a part document, pinned by content hash when available. */
529
+ export class PartRef {
530
+ constructor(name: string, options?: { page?: string | null; hash?: string | null });
531
+ name: string;
532
+ page: string | null;
533
+ hash: string | null;
534
+ }
535
+
536
+ /** A surface material (base colour + metallic/roughness) authored on an instance. */
537
+ export interface InstanceMaterial {
538
+ /** Base colour, RGB in 0..1. */
539
+ color: [number, number, number];
540
+ /** Metalness in 0..1. */
541
+ metallic: number;
542
+ /** Roughness in 0..1 (1 = matte). */
543
+ roughness: number;
544
+ }
545
+
546
+ /** One placed instance of an assembly. */
547
+ export class AssemblyInstance {
548
+ seq: number;
549
+ id: string | null;
550
+ path: string[];
551
+ name: string;
552
+ part: PartRef;
553
+ xf: { m: number[][]; t: [number, number, number] };
554
+ material: InstanceMaterial | null;
555
+ definition: Record<string, unknown>;
556
+ }
557
+
558
+ /** An inline pipe run (straight tube between two world points, millimetres). */
559
+ export interface PipeRun {
560
+ /** Runtime id path. */
561
+ id: string | null;
562
+ /** Display name, when the program sets one. */
563
+ name: string | null;
564
+ /** Start port centre (mm). */
565
+ start: [number, number, number];
566
+ /** End port centre (mm). */
567
+ end: [number, number, number];
568
+ /** Outer radius (mm). */
569
+ outerRadiusMm: number;
570
+ /** Inner radius (mm); 0 = solid rod. */
571
+ innerRadiusMm: number;
572
+ }
573
+
574
+ /** Geographic footprint of a terrain grid (WGS-84 degrees) — lets a viewport drape imagery. */
575
+ export interface TerrainSite {
576
+ /** West edge longitude (degrees). */
577
+ west: number;
578
+ /** South edge latitude (degrees). */
579
+ south: number;
580
+ /** East edge longitude (degrees). */
581
+ east: number;
582
+ /** North edge latitude (degrees). */
583
+ north: number;
584
+ }
585
+
586
+ /** An inline terrain mesh (a DEM heightfield; heights in metres, extents in millimetres). */
587
+ export interface Terrain {
588
+ /** Runtime id path. */
589
+ id: string | null;
590
+ /** Display name, when the program sets one. */
591
+ name: string | null;
592
+ /** Elevation samples in metres, row-major. */
593
+ heights: number[];
594
+ /** Grid width in samples. */
595
+ columns: number;
596
+ /** Grid height in samples. */
597
+ rows: number;
598
+ /** Ground x extent (mm). */
599
+ extentXmm: number;
600
+ /** Ground y extent (mm). */
601
+ extentYmm: number;
602
+ /** Horizontal offset (mm), set by the move gizmo. */
603
+ originXmm: number;
604
+ /** Horizontal offset (mm), set by the move gizmo. */
605
+ originYmm: number;
606
+ /** Vertical offset (mm). */
607
+ originZmm: number;
608
+ /** Geographic footprint recorded by the map picker, or null for a plain solid. */
609
+ site: TerrainSite | null;
610
+ }
611
+
612
+ /** The recorded composition for one assembly evaluation. */
613
+ export class AssemblyScene {
614
+ instances: AssemblyInstance[];
615
+ pipes: PipeRun[];
616
+ terrains: Terrain[];
617
+ notes: string[];
618
+ add(init: { id: unknown; definition: unknown }): AssemblyInstance;
619
+ addPipe(init: { id: unknown; definition: unknown }): PipeRun;
620
+ addTerrain(init: { id: unknown; definition: unknown }): Terrain;
621
+ count(): number;
622
+ pipeCount(): number;
623
+ terrainCount(): number;
624
+ setMaterial(key: string, material: InstanceMaterial): boolean;
625
+ toJSON(): Array<{
626
+ seq: number;
627
+ id: string | null;
628
+ path: string[];
629
+ name: string;
630
+ part: { name: string; page: string | null; hash: string | null };
631
+ xf: { m: number[][]; t: [number, number, number] };
632
+ material: InstanceMaterial | null;
633
+ definition: Record<string, unknown>;
634
+ }>;
635
+ pipesToJSON(): Array<{
636
+ seq: number;
637
+ id: string | null;
638
+ name: string | null;
639
+ start: [number, number, number];
640
+ end: [number, number, number];
641
+ outerRadiusMm: number;
642
+ innerRadiusMm: number;
643
+ }>;
644
+ terrainsToJSON(): Array<{
645
+ seq: number;
646
+ id: string | null;
647
+ name: string | null;
648
+ heights: number[];
649
+ columns: number;
650
+ rows: number;
651
+ extentXmm: number;
652
+ extentYmm: number;
653
+ originXmm: number;
654
+ originYmm: number;
655
+ originZmm: number;
656
+ site: TerrainSite | null;
657
+ }>;
658
+ }
659
+
660
+ /** Read an `instanceMaterial` definition map into a material value. */
661
+ export function materialFromValue(value: unknown): InstanceMaterial;
662
+
663
+ /** Read a `pipe` definition map into an inline pipe run. */
664
+ export function pipeFromValue(value: unknown): {
665
+ start: [number, number, number];
666
+ end: [number, number, number];
667
+ outerRadiusMm: number;
668
+ innerRadiusMm: number;
669
+ name: string | null;
670
+ };
671
+
672
+ /** Read a `terrain` definition map into an inline terrain mesh. */
673
+ export function terrainFromValue(value: unknown): {
674
+ heights: number[];
675
+ columns: number;
676
+ rows: number;
677
+ extentXmm: number;
678
+ extentYmm: number;
679
+ originXmm: number;
680
+ originYmm: number;
681
+ originZmm: number;
682
+ site: TerrainSite | null;
683
+ name: string | null;
684
+ };
685
+
686
+ /** Result of {@link runAssembly}. */
687
+ export interface RunAssemblyResult {
688
+ interp: FsInterp;
689
+ scene: AssemblyScene;
690
+ /** Feature-history entries in execution order. */
691
+ trace: TraceEntry[];
692
+ /** Non-fatal notes raised by the program. */
693
+ notes: string[];
694
+ }
695
+
696
+ /**
697
+ * Run an assembly document: ordinary FeatureScript plus the `instance`/`part` host ops.
698
+ *
699
+ * @param source Assembly program text.
700
+ * @param options Includes, source name and trace toggle.
701
+ * @returns Recorded instances, trace and notes.
702
+ */
703
+ export function runAssembly(
704
+ source: string,
705
+ options?: { includes?: FsSource[] | null; sourceName?: string; trace?: boolean },
706
+ ): RunAssemblyResult;
707
+
708
+ /** Project the flat trace into the feature-history tree. */
709
+ export function projectFeatureList(
710
+ trace: readonly TraceEntry[],
711
+ options?: ProjectFeatureListOptions,
712
+ ): FeatureRow[];
713
+
714
+ /** Project recorded assembly instances into rows. */
715
+ export function projectAssemblyList(instances: readonly unknown[]): AssemblyRow[];
716
+
717
+ /** Quantity roll-up for an assembly: one line per referenced part. */
718
+ export function assemblyBom(
719
+ instances: readonly unknown[],
720
+ ): Array<{ part: string; hash: string | null; count: number; pages: string[] }>;
721
+
722
+ /** Render a projected tree as indented plain text (CLI, logs, tests). */
723
+ export function formatFeatureTree(rows: readonly FeatureRow[], options?: { fields?: boolean }): string;
724
+
725
+ /** Humanise an operation name for the history tree. */
726
+ export function humanizeOp(op: string): string;
727
+
728
+ /** Classify a builtin call into a feature-history kind (null when not a feature). */
729
+ export function classifyBuiltin(name: string): FeatureKind | null;
730
+
731
+ /** Convert a FeatureScript runtime value into a JSON-safe display value. */
732
+ export function serializeValue(value: unknown, depth?: number): unknown;
733
+
734
+ /** Span of an AST node, falling back to a line-only span. */
735
+ export function spanOf(node: unknown, file?: string): SourceSpan;
736
+
737
+ /** Records the feature history of one evaluation. */
738
+ export class Tracer {
739
+ constructor(options?: { file?: string });
740
+ entries: TraceEntry[];
741
+ frames: FeatureFrame[];
742
+ pushFrame(frame: FeatureFrame): void;
743
+ popFrame(): void;
744
+ record(entry: Partial<TraceEntry>): TraceEntry;
745
+ toJSON(): TraceEntry[];
746
+ }