@metamesh/modeling 0.10.0 → 0.12.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 (36) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/README.md +70 -17
  3. package/dist/api/engine.d.ts +105 -8
  4. package/dist/api/index.d.ts +755 -771
  5. package/dist/engine/construction-operations.js +3 -1
  6. package/dist/engine/deferred-context.js +182 -0
  7. package/dist/engine/execution.js +38 -4
  8. package/dist/engine/finalization.js +65 -133
  9. package/dist/engine/geometry-recipes.js +12 -0
  10. package/dist/engine/immutable-generation-data.js +216 -0
  11. package/dist/engine/index.js +57 -35
  12. package/dist/engine/kernel/manifold.wasm +0 -0
  13. package/dist/engine/model-dependencies.js +46 -0
  14. package/dist/engine/model-summary.js +43 -0
  15. package/dist/engine/native/ownership.js +11 -5
  16. package/dist/engine/placement.js +24 -0
  17. package/dist/engine/recipe-realization.js +119 -0
  18. package/dist/engine/session-graph.js +447 -0
  19. package/dist/engine/session-native.js +90 -0
  20. package/dist/engine/session-snapshot.js +153 -0
  21. package/dist/engine/session.js +184 -0
  22. package/dist/engine/shape-anchors.js +5 -0
  23. package/dist/geometry/mesh-centroid.js +7 -6
  24. package/dist/geometry/mesh-planar.js +11 -10
  25. package/dist/geometry/mesh-quality.js +15 -14
  26. package/dist/geometry/mesh-signature.js +8 -7
  27. package/dist/geometry/mesh-solid.js +10 -4
  28. package/dist/geometry/mesh.js +36 -31
  29. package/dist/index.js +2 -0
  30. package/dist/model/execution-binding.js +5 -5
  31. package/dist/model/generation.js +27 -0
  32. package/dist/model/immutable-buffer.js +111 -0
  33. package/dist/model/modeling-context.js +1 -0
  34. package/dist/model/operations.js +521 -160
  35. package/dist/model/shape-handles.js +44 -0
  36. package/package.json +4 -4
@@ -11,8 +11,16 @@ declare interface AcmeThreadProfileSpec extends ThreadProfileBaseSpec {
11
11
  readonly depth?: number;
12
12
  }
13
13
 
14
- /** Reads one immutable named anchor from a shape in the active build. */
15
- export declare const anchor: ModelingContext["anchor"];
14
+ /**
15
+ * Reads a copied, immutable named anchor from this exact active generation.
16
+ *
17
+ * @example Read the top datum
18
+ * ```ts
19
+ * const plate = box({ size: [30, 20, 6] });
20
+ * anchor(plate, "top"); // position [0, 0, 3], direction [0, 0, 1]
21
+ * ```
22
+ */
23
+ export declare function anchor(shape: Solid | Section, name: string): Anchor3;
16
24
 
17
25
  /**
18
26
  * An attachment pose on a solid or assembly.
@@ -29,9 +37,6 @@ export declare interface Anchor3 {
29
37
  readonly up: Vec3;
30
38
  }
31
39
 
32
- /** Host-bound attach operation. Valid only during a synchronous build. */
33
- export declare const attach: ModelingContext["attach"];
34
-
35
40
  /**
36
41
  * Degree-based anchor attachment controls for a scoped solid.
37
42
  */
@@ -46,8 +51,15 @@ export declare interface AttachOptions {
46
51
  readonly tolerance?: GeometryToleranceOptions;
47
52
  }
48
53
 
49
- /** Host-bound box operation. Valid only during a synchronous build. */
50
- export declare const box: ModelingContext["box"];
54
+ /**
55
+ * Axis-aligned box with uniform or disjoint named edge/group treatments.
56
+ *
57
+ * @example Rounded box
58
+ * ```ts
59
+ * box({ size: [30, 20, 8], treatment: { kind: "round", radius: 2 } });
60
+ * ```
61
+ */
62
+ export declare function box(options: BoxOptions): Solid;
51
63
 
52
64
  /** Box edges use +Z top, +Y front and +X right; vertical names list front/back first. */
53
65
  export declare type BoxEdge = "top-front" | "top-back" | "top-left" | "top-right" | "bottom-front" | "bottom-back" | "bottom-left" | "bottom-right" | "front-left" | "front-right" | "back-left" | "back-right";
@@ -75,9 +87,6 @@ export declare interface BoxOptions extends PrimitivePlacement {
75
87
  readonly treatment?: EdgeTreatment | BoxEdgeTreatments;
76
88
  }
77
89
 
78
- /** A bare solid receives the semantic part ID `model`. Explicit parts preserve their IDs. */
79
- export declare type BuildOutput = Solid | readonly ModelPart[];
80
-
81
90
  /** Axial side carrying the near-normal pressure flank of a buttress thread. */
82
91
  declare type ButtressPressureFlankSide = "negative" | "positive";
83
92
 
@@ -108,8 +117,15 @@ export declare interface ChamferedEdgeTreatment {
108
117
  readonly distance: number | readonly [first: number, second: number];
109
118
  }
110
119
 
111
- /** Host-bound circle operation. Valid only during a synchronous build. */
112
- export declare const circle: ModelingContext["circle"];
120
+ /**
121
+ * Centered circular section.
122
+ *
123
+ * @example Size to polygon faces
124
+ * ```ts
125
+ * circle({ diameter: 12, sizing: "face" });
126
+ * ```
127
+ */
128
+ export declare function circle(options: CircleOptions): Section;
113
129
 
114
130
  /**
115
131
  * Circular profile dimensions with exactly one radius or diameter and explicit sampling.
@@ -148,11 +164,41 @@ export declare interface CircularPrimitiveOptions {
148
164
  readonly resolution?: GeometryResolution;
149
165
  }
150
166
 
151
- /** Host-bound components operation. Valid only during a synchronous build. */
152
- export declare const components: ModelingContext["components"];
167
+ /**
168
+ * Separates a solid's disconnected surface shells into same-session solid handles.
169
+ *
170
+ * For solids without enclosed cavities, these shells are the disconnected material islands.
171
+ * Enclosed cavities produce separate inward shells with negative signed volume; these cannot
172
+ * be finalized alone as manufacturing parts. This does not cut connected geometry.
173
+ *
174
+ * @example Move disconnected pieces independently
175
+ * ```ts
176
+ * const islands = union([box({ size: 8 }), box({ size: 8 }).translate([12, 0, 0])]);
177
+ * const pieces = components(islands);
178
+ * // Component order is unspecified; the index only sets a display height here.
179
+ * union(pieces.map((piece, index) => piece.translate([0, 0, index * 6])));
180
+ * ```
181
+ */
182
+ export declare function components(solid: Solid): readonly Solid[];
183
+
184
+ /** Separates filled 2D islands into sections, retaining each island's holes; empty gives []. */
185
+ export declare function components(section: Section): readonly Section[];
153
186
 
154
- /** Host-bound compose operation. Valid only during a synchronous build. */
155
- export declare const compose: ModelingContext["compose"];
187
+ /** Combines disjoint components without resolving overlap. */
188
+ export declare function compose(solids: readonly Solid[]): Solid;
189
+
190
+ /** A lazy session-owned reader. Calling it tracks its output in the current computation. */
191
+ export declare interface Computed<T> {
192
+ /** Compile-time ownership brand; readers are created by the engine's context helper. */
193
+ readonly [computedBrand]: "Computed";
194
+ /** Reads immutable data or a deferred recipe; evaluation is synchronous and cached. */
195
+ (): T;
196
+ }
197
+
198
+ declare const computedBrand: unique symbol;
199
+
200
+ /** A value supplied immediately or by a lazy computed reader. */
201
+ export declare type ComputedValue<T> = T | Computed<T>;
156
202
 
157
203
  /** One sampled component retaining contour identities and logical point correspondence. */
158
204
  export declare interface CorrespondingComponent {
@@ -197,8 +243,20 @@ declare interface CustomThreadProfileSpec extends ThreadProfileBaseSpec {
197
243
  readonly points: readonly Vec2[];
198
244
  }
199
245
 
200
- /** Host-bound cylinder operation. Valid only during a synchronous build. */
201
- export declare const cylinder: ModelingContext["cylinder"];
246
+ /**
247
+ * +Z cylinder or frustum. Face sizing compensates polygon faceting.
248
+ *
249
+ * @example Cylinder
250
+ * ```ts
251
+ * cylinder({ height: 20, radius: 10 });
252
+ * ```
253
+ *
254
+ * @example Cone
255
+ * ```ts
256
+ * cylinder({ height: 20, radius: [10, 0] });
257
+ * ```
258
+ */
259
+ export declare function cylinder(options: CylinderOptions): Solid;
202
260
 
203
261
  /**
204
262
  * Dimensions, placement, independent end finishing, and tessellation for a Z-axis cylinder or frustum.
@@ -225,16 +283,43 @@ export declare type CylinderOptions = CircularPrimitiveOptions & RadialSizingOpt
225
283
  readonly radius?: never;
226
284
  });
227
285
 
228
- /** Measures the minimum separation between two nonempty solids in millimetres. */
229
- export declare const distance: ModelingContext["distance"];
286
+ /** Typed parameter association for an assertion or warning. */
287
+ export declare interface DiagnosticOptions<P> {
288
+ /** Existing top-level parameter key. */
289
+ readonly parameterId?: Extract<keyof P, string> | undefined;
290
+ }
291
+
292
+ /**
293
+ * Measures the minimum separation between two nonempty solids in millimetres.
294
+ *
295
+ * Uses actual geometry, not bounding-box separation or distance between object origins.
296
+ * Contact or overlapping material returns zero, including one solid inside another.
297
+ * The kernel's search range is managed internally; the result is not capped at a caller limit.
298
+ * Empty, expired or foreign-build handles reject. Results follow native numeric precision.
299
+ *
300
+ * @example Measure the gap between two blocks
301
+ * ```ts
302
+ * const left = box({ size: 10 });
303
+ * const right = box({ size: 10 }).translate([13, 0, 0]);
304
+ * const gap = distance(left, right); // 3 mm
305
+ * ```
306
+ */
307
+ export declare function distance(solid: Solid, other: Solid): number;
230
308
 
231
309
  /**
232
310
  * Uniform finishing vocabulary shared by applicable solid edges and profile corners.
233
311
  */
234
312
  export declare type EdgeTreatment = ChamferedEdgeTreatment | RoundedEdgeTreatment | SmoothEdgeTreatment | ProfiledEdgeTreatment;
235
313
 
236
- /** Host-bound ellipse operation. Valid only during a synchronous build. */
237
- export declare const ellipse: ModelingContext["ellipse"];
314
+ /**
315
+ * Centered elliptical section.
316
+ *
317
+ * @example Ellipse by full dimensions
318
+ * ```ts
319
+ * ellipse({ size: [30, 20] });
320
+ * ```
321
+ */
322
+ export declare function ellipse(options: EllipseOptions): Section;
238
323
 
239
324
  /**
240
325
  * Ellipse dimensions with exactly one XY radii or full-size tuple and explicit sampling.
@@ -266,8 +351,20 @@ export declare interface EndTreatments {
266
351
  readonly top?: EdgeTreatment;
267
352
  }
268
353
 
269
- /** Host-bound extrude operation. Valid only during a synchronous build. */
270
- export declare const extrude: ModelingContext["extrude"];
354
+ /**
355
+ * Extrudes explicit corresponding contours along +Z with degree twist and top scaling.
356
+ * Filled Sections use `section.extrude(options)`.
357
+ *
358
+ * @example Extrude
359
+ * ```ts
360
+ * import { extrude, matchProfiles } from "@metamesh/modeling";
361
+ * import { rectangleProfile } from "@metamesh/modeling/geometry";
362
+ *
363
+ * const [profile] = matchProfiles([rectangleProfile({ size: [30, 20] })]);
364
+ * extrude(profile!, { height: 8 });
365
+ * ```
366
+ */
367
+ export declare function extrude(shape: CorrespondingProfile, options: ExtrudeOptions): Solid;
271
368
 
272
369
  /**
273
370
  * Dimensions and sampling shared by native and pure +Z extrusion.
@@ -342,8 +439,74 @@ export declare interface Frame3 {
342
439
  readonly zAxis: Vec3;
343
440
  }
344
441
 
345
- /** Host-bound fromRegion operation. Valid only during a synchronous build. */
346
- export declare const fromRegion: ModelingContext["fromRegion"];
442
+ /** Imports explicit region topology once. */
443
+ export declare function fromRegion(region: Region2): Section;
444
+
445
+ /**
446
+ * Defines a typed model without executing it. Use `computed` only for work worth reusing.
447
+ *
448
+ * @example A simple model
449
+ * ```ts
450
+ * const model = generate<{ height: number }>(({ params, part, assert }) => {
451
+ * assert(params.height > 0, "Height must be positive.");
452
+ * return [part("body", box({ size: [10, 10, params.height] }))];
453
+ * });
454
+ * ```
455
+ */
456
+ export declare function generate<P, S = Record<never, never>>(callback: GenerateCallback<P, S>): ModelProgram<P, S>;
457
+
458
+ /** Pure synchronous generation callback; caches are an optional performance optimization. */
459
+ export declare type GenerateCallback<P, S = Record<never, never>> = (context: GenerateContext<P, S>) => readonly GeneratedPart[];
460
+
461
+ /** The sole synchronous authoring context, supplied independently of Studio. */
462
+ export declare interface GenerateContext<P, S = Record<never, never>> {
463
+ /** Frozen ordinary parameter values; synchronous top-level reads are tracked. */
464
+ readonly params: Readonly<P>;
465
+ /** Host-prepared readonly synchronous capabilities, fixed for the session. */
466
+ readonly services: Readonly<S>;
467
+ /**
468
+ * Registers a lazy pure calculation and automatically tracks parameter and computed-reader reads.
469
+ * Optional dependencies add changing outer captures; entries compare with Object.is. Objects and
470
+ * arrays must be deeply immutable. An empty list still tracks reads inside the callback.
471
+ */
472
+ readonly computed: <T>(id: string, callback: () => T, dependencies?: readonly unknown[]) => Computed<T>;
473
+ /** Declares a semantic part with identity placement, or explicit placement and appearance. */
474
+ readonly part: {
475
+ (id: string, geometry: ComputedValue<PartGeometry>): GeneratedPart;
476
+ (id: string, options: PartOptions): GeneratedPart;
477
+ };
478
+ /** Immediately aborts on false; geometry observations in the condition run first. */
479
+ readonly assert: {
480
+ (condition: false, message: string, options?: DiagnosticOptions<P>): never;
481
+ (condition: boolean, message: string, options?: DiagnosticOptions<P>): void;
482
+ };
483
+ /** Records a nonblocking issue; call only in the outer generation callback. */
484
+ readonly warn: (message: string, options?: DiagnosticOptions<P>) => void;
485
+ }
486
+
487
+ /** One declared output part. Construct with the context's `part` helper. */
488
+ export declare interface GeneratedPart extends PartOptions {
489
+ /** Unique canonical lowercase hyphen-separated identity, at most 64 characters. */
490
+ readonly id: string;
491
+ }
492
+
493
+ /** Structured user-facing issue associated with the attempted revision. */
494
+ export declare interface GenerationDiagnostic {
495
+ /** An error aborts generation; a warning allows generation to continue. */
496
+ readonly severity: "error" | "warning";
497
+ /** Human-readable corrective guidance. */
498
+ readonly message: string;
499
+ /** Optional control identity, validated against the supplied parameters. */
500
+ readonly parameterId?: string | undefined;
501
+ }
502
+
503
+ /** A user-correctable assertion failure. Successful computation caches never retain failures. */
504
+ export declare class GenerationError extends Error {
505
+ /** Issues reached in normal JavaScript order, ending with the first failed assertion. */
506
+ readonly diagnostics: readonly GenerationDiagnostic[];
507
+ /** Captures immutable diagnostics; unexpected author errors retain their original type. */
508
+ constructor(diagnostics: readonly GenerationDiagnostic[]);
509
+ }
347
510
 
348
511
  /**
349
512
  * Tessellation policy for sampled geometry measured in millimetres.
@@ -383,8 +546,15 @@ export declare interface GeometryToleranceOptions {
383
546
  readonly relative?: number;
384
547
  }
385
548
 
386
- /** Host-bound gridPattern operation. Valid only during a synchronous build. */
387
- export declare const gridPattern: ModelingContext["gridPattern"];
549
+ /**
550
+ * XY or XYZ copies, optionally centered or placed in an explicit frame.
551
+ *
552
+ * @example Centered XY grid
553
+ * ```ts
554
+ * gridPattern(box({ size: 4 }), { count: [3, 2], spacing: [10, 10], center: true });
555
+ * ```
556
+ */
557
+ export declare function gridPattern(source: PatternSource, options: GridPatternOptions): readonly Solid[];
388
558
 
389
559
  /**
390
560
  * XY or XYZ grid with X varying fastest. The first item starts at the local origin.
@@ -406,8 +576,19 @@ export declare type GridPatternOptions = {
406
576
  readonly spacing: Vec3;
407
577
  });
408
578
 
409
- /** Constructs a closed rectilinear heightfield during the active synchronous build. */
410
- export declare const heightfield: ModelingContext["heightfield"];
579
+ /**
580
+ * Closed rectilinear top above a flat base, with uniform or explicit XY coordinates.
581
+ * Samples each grid height once; center-error triangulation also samples each cell centre.
582
+ *
583
+ * @example Heightfield
584
+ * ```ts
585
+ * heightfield({
586
+ * size: [30, 20], segments: [24, 16],
587
+ * height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
588
+ * });
589
+ * ```
590
+ */
591
+ export declare function heightfield(options: HeightfieldOptions): Solid;
411
592
 
412
593
  /**
413
594
  * A closed rectilinear heightfield above a flat base, with uniform or explicit XY samples in millimetres.
@@ -497,10 +678,22 @@ export declare interface HelicalThreadSolidMeshPreflight {
497
678
  readonly estimatedTriangles: number;
498
679
  }
499
680
 
500
- /** Host-bound hull operation. Valid only during a synchronous build. */
501
- export declare const hull: ModelingContext["hull"];
681
+ /**
682
+ * Convex hull of points or solids.
683
+ *
684
+ * @example Hull
685
+ * ```ts
686
+ * const left = sphere({ radius: 5 }).translate([-10, 0, 0]);
687
+ * const right = sphere({ radius: 5 }).translate([10, 0, 0]);
688
+ * hull({ solids: [left, right] });
689
+ * ```
690
+ */
691
+ export declare function hull(options: HullOptions): Solid;
692
+
693
+ /** Convex filled XY hull of finite points or same-session sections. */
694
+ export declare function hull(options: SectionHullOptions): Section;
502
695
 
503
- /** Hull inputs are either finite points or same-build solids. */
696
+ /** Hull inputs are either finite points or same-session solids. */
504
697
  export declare type HullOptions = {
505
698
  /** Finite millimetre XYZ points to include in the convex hull. */
506
699
  readonly points: readonly Vec3[];
@@ -513,8 +706,60 @@ export declare type HullOptions = {
513
706
  readonly points?: never;
514
707
  };
515
708
 
516
- /** Host-bound implicit operation. Valid only during a synchronous build. */
517
- export declare const implicit: ModelingContext["implicit"];
709
+ /** Owned immutable numeric data. Use copy() to obtain mutable storage for numerical work. */
710
+ export declare interface ImmutableBuffer<T extends NumericArray> {
711
+ /** Opaque element-storage brand; construct buffers with immutableBuffer(). */
712
+ readonly [immutableBufferBrand]: T;
713
+ /** Number of numeric elements, independent of their byte width. */
714
+ readonly length: number;
715
+ /** Reads an integer offset; negative offsets count from the end. Invalid offsets return undefined. */
716
+ at(this: void, index: number): number | undefined;
717
+ /** Returns a fresh mutable array of the original numeric type; never exposes cached storage. */
718
+ copy(this: void): T;
719
+ }
720
+
721
+ /**
722
+ * Copies numeric data once into private storage. This pure helper needs no active generation.
723
+ * @example
724
+ * ```ts
725
+ * import { immutableBuffer } from "@metamesh/modeling";
726
+ * const heights = immutableBuffer(new Float32Array([2, 4, 6]));
727
+ * const count = heights.length;
728
+ * const first = heights.at(0);
729
+ * const editable = heights.copy();
730
+ * editable[0] = 8; // heights still contains 2, 4, 6.
731
+ * ```
732
+ */
733
+ export declare function immutableBuffer<T extends NumericArray>(source: T): ImmutableBuffer<T>;
734
+
735
+ declare const immutableBufferBrand: unique symbol;
736
+
737
+ /**
738
+ * Copies mesh buffers into immutable data; geometric validation still occurs when modeling or finalizing.
739
+ * @example
740
+ * ```ts
741
+ * import { generate, immutableMesh } from "@metamesh/modeling";
742
+ * import { heightfieldMesh } from "@metamesh/modeling/geometry";
743
+ * const model = generate(({ computed, part }) => {
744
+ * const surface = computed("surface", () => immutableMesh(heightfieldMesh({
745
+ * size: [10, 10], segments: [8, 8], height: () => 2,
746
+ * })));
747
+ * return [part("surface", surface)];
748
+ * });
749
+ * ```
750
+ */
751
+ export declare function immutableMesh(mesh: TriangleMesh): ImmutableTriangleMesh;
752
+
753
+ /** Immutable local XYZ positions and triangle indices, suitable for a computed value or part. */
754
+ export declare interface ImmutableTriangleMesh {
755
+ /** Packed XYZ coordinates in millimetres. */
756
+ readonly positions: ImmutableBuffer<Float32Array>;
757
+ /** Zero-based vertex indices, three per triangle. */
758
+ readonly indices: ImmutableBuffer<Uint32Array>;
759
+ }
760
+
761
+ /** Bounded positive-inside implicit field constructor. */
762
+ export declare function implicit(options: ImplicitOptions): Solid;
518
763
 
519
764
  /** Positive-inside sampling, bounded to 4M native BCC grid slots and 8M field calls. */
520
765
  export declare interface ImplicitOptions {
@@ -530,14 +775,42 @@ export declare interface ImplicitOptions {
530
775
  readonly tolerance?: number;
531
776
  }
532
777
 
533
- /** Host-bound inspectSection operation. Valid only during a synchronous build. */
534
- export declare const inspectSection: ModelingContext["inspectSection"];
778
+ /**
779
+ * Copies lightweight section measurements.
780
+ *
781
+ * @example Check filled area
782
+ * ```ts
783
+ * const facts = inspectSection(rectangle({ size: [20, 10] }));
784
+ * facts.area; // 200 mm²
785
+ * ```
786
+ */
787
+ export declare function inspectSection(section: Section): SectionInspection;
535
788
 
536
- /** Host-bound inspectSolid operation. Valid only during a synchronous build. */
537
- export declare const inspectSolid: ModelingContext["inspectSolid"];
789
+ /**
790
+ * Reads immutable native facts once per solid; temporary components are owned by the build.
791
+ *
792
+ * @example Check dimensions and volume
793
+ * ```ts
794
+ * const facts = inspectSolid(box({ size: [30, 20, 6] }));
795
+ * facts.volume; // 3600 mm³
796
+ * ```
797
+ */
798
+ export declare function inspectSolid(solid: Solid): SolidInspection;
538
799
 
539
- /** Host-bound internalThreadCutter operation. Valid only during a synchronous build. */
540
- export declare const internalThreadCutter: ModelingContext["internalThreadCutter"];
800
+ /**
801
+ * Compensated internal threaded cutter.
802
+ *
803
+ * @example Internal thread
804
+ * ```ts
805
+ * import { cylinder, internalThreadCutter } from "@metamesh/modeling";
806
+ * import { createThreadProfile } from "@metamesh/modeling/geometry";
807
+ * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
808
+ * const body = cylinder({ diameter: 20, height: 12, center: false });
809
+ * const cutter = internalThreadCutter({ nominalMajorDiameter: 12, length: 12, profile });
810
+ * body.subtract([cutter]);
811
+ * ```
812
+ */
813
+ export declare function internalThreadCutter(options: InternalThreadCutterOptions): Solid;
541
814
 
542
815
  /** Options for a compensated internal-thread subtraction tool along +Z. */
543
816
  export declare interface InternalThreadCutterOptions extends Omit<HelicalThreadRidgeMeshOptions, "majorDiameter">, ThreadBevelOptions {
@@ -547,14 +820,44 @@ export declare interface InternalThreadCutterOptions extends Omit<HelicalThreadR
547
820
  readonly nominalMajorDiameter: number;
548
821
  }
549
822
 
550
- /** Host-bound intersect operation. Valid only during a synchronous build. */
551
- export declare const intersect: ModelingContext["intersect"];
823
+ /**
824
+ * Robust intersection.
825
+ *
826
+ * @example Intersect
827
+ * ```ts
828
+ * intersect([box({ size: 20 }), sphere({ radius: 12 })]);
829
+ * ```
830
+ */
831
+ export declare function intersect(solids: readonly Solid[]): Solid;
552
832
 
553
- /** Tests a solid or filled section in the active build, including expected empty Boolean results. */
554
- export declare const isEmpty: ModelingContext["isEmpty"];
833
+ /** Native filled section intersection; dimensions cannot be mixed. */
834
+ export declare function intersect(sections: readonly Section[]): Section;
835
+
836
+ /**
837
+ * Checks whether a same-session solid or filled section contains no geometry.
838
+ *
839
+ * Accepts a 3D Solid or 2D Section handle, not a finalized model or raw triangle mesh.
840
+ * Useful after a Boolean operation whose inputs may not overlap; no mesh is extracted.
841
+ *
842
+ * @example Check a missed intersection
843
+ * ```ts
844
+ * const body = box({ size: 10 });
845
+ * const distant = box({ size: 10 }).translate([30, 0, 0]);
846
+ * const empty = intersect([body, distant]);
847
+ * const missed = isEmpty(empty); // true
848
+ * ```
849
+ */
850
+ export declare function isEmpty(shape: Solid | Section): boolean;
555
851
 
556
- /** Host-bound linearPattern operation. Valid only during a synchronous build. */
557
- export declare const linearPattern: ModelingContext["linearPattern"];
852
+ /**
853
+ * Repeats one solid along a normalized direction.
854
+ *
855
+ * @example Three copies along X
856
+ * ```ts
857
+ * linearPattern(box({ size: 4 }), { count: 3, spacing: 10 });
858
+ * ```
859
+ */
860
+ export declare function linearPattern(source: PatternSource, options: LinearPatternOptions): readonly Solid[];
558
861
 
559
862
  /**
560
863
  * Equal linear intervals determined by exactly two of count, spacing and total length.
@@ -585,8 +888,21 @@ export declare type LinearPatternOptions = {
585
888
  readonly count?: never;
586
889
  });
587
890
 
588
- /** Host-bound loft operation. Valid only during a synchronous build. */
589
- export declare const loft: ModelingContext["loft"];
891
+ /**
892
+ * Lofts primitive Sections at z heights or frames; arbitrary Sections and loops require an explicit correspondence method.
893
+ *
894
+ * @example Loft
895
+ * ```ts
896
+ * loft([
897
+ * { profile: circle({ diameter: 16 }), z: 0 },
898
+ * { profile: rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } }), z: 30 },
899
+ * ]);
900
+ * ```
901
+ */
902
+ export declare function loft(stations: readonly LoftStation[], options?: LoftOptions): Solid;
903
+
904
+ /** Lofts explicit corresponding contours, including holes and collapsed logical slots. */
905
+ export declare function loft(stations: readonly CorrespondingProfileStation[], options?: LoftOptions): Solid;
590
906
 
591
907
  /**
592
908
  * Associates ordered loft contours without inferring component identities or repairing topology.
@@ -652,8 +968,8 @@ export declare type LoftStation = LoftPlacement & {
652
968
  */
653
969
  export declare type Loop2 = readonly Vec2[];
654
970
 
655
- /** Matches an explicit profile family using the current build's physical resolution. */
656
- export declare const matchProfiles: ModelingContext["matchProfiles"];
971
+ /** Explicit family matching on a shared physical span grid using session or operation resolution. */
972
+ export declare function matchProfiles(profiles: readonly Profile[], options?: MatchProfilesOptions): readonly CorrespondingProfile[];
657
973
 
658
974
  /** Explicit family sampling settings; omitted values use physical package defaults. */
659
975
  export declare interface MatchProfilesOptions {
@@ -673,615 +989,8 @@ export declare interface MeshBounds {
673
989
  readonly max: Vec3;
674
990
  }
675
991
 
676
- /** Named direct mesh part. Input is copied, validated, and bounded by the host. */
677
- export declare interface MeshPart {
678
- /** Stable canonical lowercase identity; unique within the containing topology or output. */
679
- readonly id: string;
680
- /** Optional six-digit hex RGB display color. */
681
- readonly color?: string;
682
- /** Direct manufacturing mesh; mutually exclusive with a solid handle. */
683
- readonly mesh: TriangleMesh;
684
- /** Same-build solid handle; mutually exclusive with a direct mesh. */
685
- readonly solid?: never;
686
- }
687
-
688
- /** Host-bound minkowskiSum operation. Valid only during a synchronous build. */
689
- export declare const minkowskiSum: ModelingContext["minkowskiSum"];
690
-
691
- /** Host-bound mirror operation. Valid only during a synchronous build. */
692
- export declare const mirror: ModelingContext["mirror"];
693
-
694
- /** The sole modeling facade used by compiled and authored generators.
695
- * Methods are bound to the host execution and can be destructured safely. Angles are degrees;
696
- * lengths are millimetres. Handles cannot outlive this build or cross into a different build.
697
- */
698
- export declare interface ModelingContext {
699
- /** Derives a context with explicit physical sampling defaults in the same execution. */
700
- withResolution(this: void, resolution: GeometryResolution): ModelingContext;
701
- /**
702
- * Axis-aligned box with uniform or disjoint named edge/group treatments.
703
- *
704
- * @example Rounded box
705
- * ```ts
706
- * box({ size: [30, 20, 8], treatment: { kind: "round", radius: 2 } });
707
- * ```
708
- */
709
- box(this: void, options: BoxOptions): Solid;
710
- /**
711
- * +Z cylinder or frustum. Face sizing compensates polygon faceting.
712
- *
713
- * @example Cylinder
714
- * ```ts
715
- * cylinder({ height: 20, radius: 10 });
716
- * ```
717
- *
718
- * @example Cone
719
- * ```ts
720
- * cylinder({ height: 20, radius: [10, 0] });
721
- * ```
722
- */
723
- cylinder(this: void, options: CylinderOptions): Solid;
724
- /**
725
- * Hollow +Z tube.
726
- *
727
- * @example Tube
728
- * ```ts
729
- * tube({ height: 20, outerRadius: 10, innerRadius: 6 });
730
- * ```
731
- */
732
- tube(this: void, options: TubeOptions): Solid;
733
- /**
734
- * Origin-centered sphere.
735
- *
736
- * @example Sphere
737
- * ```ts
738
- * sphere({ diameter: 20 });
739
- * ```
740
- */
741
- sphere(this: void, options: SphereOptions): Solid;
742
- /**
743
- * Torus around +Z.
744
- *
745
- * @example Torus
746
- * ```ts
747
- * torus({ majorRadius: 12, minorRadius: 3 });
748
- * ```
749
- */
750
- torus(this: void, options: TorusOptions): Solid;
751
- /**
752
- * Robust union.
753
- *
754
- * @example Union
755
- * ```ts
756
- * const block = box({ size: 20 });
757
- * const cap = translate(sphere({ radius: 10 }), [0, 0, 10]);
758
- * union([block, cap]);
759
- * ```
760
- */
761
- union(this: void, solids: readonly Solid[]): Solid;
762
- /** Native filled section union; dimensions cannot be mixed. */
763
- union(this: void, sections: readonly Section[]): Section;
764
- /**
765
- * Robust difference; an empty cutter array preserves the source.
766
- *
767
- * @example Subtract
768
- * ```ts
769
- * const plate = box({ size: [30, 20, 6] });
770
- * // Extend the cutter beyond both faces.
771
- * const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
772
- * subtract(plate, [bore]);
773
- * ```
774
- */
775
- subtract(this: void, solid: Solid, cutters: readonly Solid[]): Solid;
776
- /** Native section difference; an empty cutter array preserves the source. */
777
- subtract(this: void, section: Section, cutters: readonly Section[]): Section;
778
- /**
779
- * Robust intersection.
780
- *
781
- * @example Intersect
782
- * ```ts
783
- * intersect([box({ size: 20 }), sphere({ radius: 12 })]);
784
- * ```
785
- */
786
- intersect(this: void, solids: readonly Solid[]): Solid;
787
- /** Native filled section intersection; dimensions cannot be mixed. */
788
- intersect(this: void, sections: readonly Section[]): Section;
789
- /**
790
- * Splits a solid into [inside the cutter, outside the cutter].
791
- *
792
- * The first result is the intersection; the second is the subtraction. The cutter itself
793
- * is not returned. Either result may be empty or contain multiple disconnected components.
794
- *
795
- * @example Keep the plug and the surrounding body
796
- * ```ts
797
- * const body = box({ size: [30, 20, 8] });
798
- * const cutter = cylinder({ height: 10, diameter: 8 });
799
- * const [plug, remainder] = split(body, cutter);
800
- * // Move the plug beside the body to show both results.
801
- * union([translate(plug, [0, -20, 0]), remainder]);
802
- * ```
803
- */
804
- split(this: void, solid: Solid, cutter: Solid): readonly [Solid, Solid];
805
- /**
806
- * Splits a solid into [positive-normal side, negative side] at a world-space plane.
807
- *
808
- * The nonzero normal is normalized; offset is the signed distance from the origin in
809
- * millimetres, defaulting to zero. Both cut faces are closed. Select either tuple result
810
- * to retain one side; either result may be empty.
811
- *
812
- * @example Separate two halves at X = 0
813
- * ```ts
814
- * const body = box({ size: [30, 20, 8] });
815
- * const [right, left] = splitByPlane(body, { normal: [1, 0, 0] });
816
- * // The gap is only for display; the cut itself removes no material.
817
- * union([translate(right, [4, 0, 0]), translate(left, [-4, 0, 0])]);
818
- * ```
819
- *
820
- * @example Keep only the positive half
821
- * ```ts
822
- * const [right] = splitByPlane(box({ size: [30, 20, 8] }), { normal: [1, 0, 0] });
823
- * right;
824
- * ```
825
- */
826
- splitByPlane(this: void, solid: Solid, plane: PlaneOptions): readonly [Solid, Solid];
827
- /** Combines disjoint components without resolving overlap. */
828
- compose(this: void, solids: readonly Solid[]): Solid;
829
- /**
830
- * Convex hull of points or solids.
831
- *
832
- * @example Hull
833
- * ```ts
834
- * const left = translate(sphere({ radius: 5 }), [-10, 0, 0]);
835
- * const right = translate(sphere({ radius: 5 }), [10, 0, 0]);
836
- * hull({ solids: [left, right] });
837
- * ```
838
- */
839
- hull(this: void, options: HullOptions): Solid;
840
- /** Convex filled XY hull of finite points or same-build sections. */
841
- hull(this: void, options: SectionHullOptions): Section;
842
- /** Three-dimensional Minkowski sum. */
843
- minkowskiSum(this: void, a: Solid, b: Solid): Solid;
844
- /**
845
- * Imports a bounded closed indexed mesh.
846
- *
847
- * @example Mesh import
848
- * ```ts
849
- * import { solidFromMesh } from "@metamesh/modeling";
850
- * import { extrudeMesh, rectangleLoop } from "@metamesh/modeling/geometry";
851
- *
852
- * const mesh = extrudeMesh(rectangleLoop({ size: [20, 12] }), { height: 6 });
853
- * solidFromMesh(mesh);
854
- * ```
855
- */
856
- solidFromMesh(this: void, mesh: TriangleMesh): Solid;
857
- /** Copies a handle to manufacturing mesh buffers. */
858
- toTriangleMesh(this: void, solid: Solid): TriangleMesh;
859
- /** Translation preserving dimensionality. */
860
- translate(this: void, section: Section, offset: Vec2): Section;
861
- /**
862
- * Translation preserving dimensionality.
863
- *
864
- * @example Translate
865
- * ```ts
866
- * translate(box({ size: [12, 8, 4] }), [15, 0, 0]);
867
- * ```
868
- */
869
- translate(this: void, solid: Solid, offset: Vec3): Solid;
870
- /** Degree rotation; scalar XY rotation or XYZ solid Euler angles. */
871
- rotate(this: void, section: Section, degrees: number): Section;
872
- /**
873
- * Degree rotation; scalar XY rotation or XYZ solid Euler angles.
874
- *
875
- * @example Rotate
876
- * ```ts
877
- * rotate(box({ size: [20, 10, 6] }), [0, 0, 30]);
878
- * ```
879
- */
880
- rotate(this: void, solid: Solid, degrees: Vec3): Solid;
881
- /**
882
- * Nonsingular scaling about the origin.
883
- */
884
- scale(this: void, section: Section, factors: number | Vec2): Section;
885
- /**
886
- * Nonsingular scaling about the origin.
887
- *
888
- * @example Scale
889
- * ```ts
890
- * scale(sphere({ radius: 8 }), [2, 1, 1]);
891
- * ```
892
- */
893
- scale(this: void, solid: Solid, factors: number | Vec3): Solid;
894
- /** Reflection across an origin line/plane. */
895
- mirror(this: void, section: Section, normal: Vec2): Section;
896
- /**
897
- * Reflection across an origin line/plane.
898
- *
899
- * @example Mirror
900
- * ```ts
901
- * const block = translate(box({ size: [12, 8, 4] }), [10, 0, 0]);
902
- * mirror(block, [1, 0, 0]);
903
- * ```
904
- */
905
- mirror(this: void, solid: Solid, normal: Vec3): Solid;
906
- /** Row-major affine transform preserving dimensionality. */
907
- transform(this: void, section: Section, matrix: Transform2): Section;
908
- /** Row-major affine transform preserving dimensionality. */
909
- transform(this: void, solid: Solid, matrix: Transform3): Solid;
910
- /**
911
- * Reads a copied, immutable named anchor from this exact active build.
912
- *
913
- * @example Read the top datum
914
- * ```ts
915
- * const plate = box({ size: [30, 20, 6] });
916
- * anchor(plate, "top"); // position [0, 0, 3], direction [0, 0, 1]
917
- * ```
918
- */
919
- anchor(this: void, shape: Solid | Section, name: string): Anchor3;
920
- /**
921
- * Returns a new same-build handle with copied named anchors; existing names may be replaced.
922
- */
923
- withAnchors<T extends Solid | Section>(this: void, shape: T, anchors: Readonly<Record<string, Anchor3>>): T;
924
- /**
925
- * Places an explicit or named source anchor against an explicit target anchor.
926
- *
927
- * @example Anchor attachment
928
- * ```ts
929
- * const plate = box({ size: [30, 20, 6] });
930
- * const pin = cylinder({ height: 12, radius: 3 });
931
- * attach(pin, "bottom", anchor(plate, "top"), { gap: 1 });
932
- * ```
933
- */
934
- attach(this: void, solid: Solid, source: Anchor3 | string, target: Anchor3, options?: AttachOptions): Solid;
935
- /**
936
- * Creates a native filled section without an intermediate Region2 conversion.
937
- */
938
- sectionFromContours(this: void, contours: readonly Loop2[], options?: SectionFromContoursOptions): Section;
939
- /** Imports explicit region topology once. */
940
- fromRegion(this: void, region: Region2): Section;
941
- /** Explicit copied topology inspection; not needed for section operations. */
942
- toRegion(this: void, section: Section): Region2;
943
- /**
944
- * Filled rectangular section with uniform or independently treated corners.
945
- *
946
- * @example Round the corners
947
- * ```ts
948
- * rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
949
- * ```
950
- */
951
- rectangle(this: void, options: RectangleOptions): Section;
952
- /**
953
- * Centered circular section.
954
- *
955
- * @example Size to polygon faces
956
- * ```ts
957
- * circle({ diameter: 12, sizing: "face" });
958
- * ```
959
- */
960
- circle(this: void, options: CircleOptions): Section;
961
- /**
962
- * Centered elliptical section.
963
- *
964
- * @example Ellipse by full dimensions
965
- * ```ts
966
- * ellipse({ size: [30, 20] });
967
- * ```
968
- */
969
- ellipse(this: void, options: EllipseOptions): Section;
970
- /**
971
- * Regular polygon with a vertex on +X.
972
- *
973
- * @example Hexagonal section
974
- * ```ts
975
- * regularPolygon({ radius: 10, sides: 6, sizing: "face" });
976
- * ```
977
- */
978
- regularPolygon(this: void, options: RegularPolygonOptions): Section;
979
- /**
980
- * Alternating outer/inner star vertices.
981
- *
982
- * @example Five-point section
983
- * ```ts
984
- * star({ outerRadius: 12, innerRadius: 6, points: 5 });
985
- * ```
986
- */
987
- star(this: void, options: StarOptions): Section;
988
- /**
989
- * Native millimetre offset preserving holes.
990
- *
991
- * @example Add a 2 mm margin
992
- * ```ts
993
- * const outline = rectangle({ size: [20, 12] });
994
- * offset(outline, 2, { join: "round" });
995
- * ```
996
- */
997
- offset(this: void, section: Section, distance: number, options?: RegionOffsetOptions): Section;
998
- /**
999
- * Extrudes along +Z with degree twist and top scaling.
1000
- *
1001
- * @example Extrude
1002
- * ```ts
1003
- * const outline = rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
1004
- * extrude(outline, { height: 8 });
1005
- * ```
1006
- */
1007
- extrude(this: void, shape: ModelingShape, options: ExtrudeOptions): Solid;
1008
- /**
1009
- * Revolves a filled radial/Z shape around +Z, with caps for partial sweeps.
1010
- *
1011
- * @example Revolve
1012
- * ```ts
1013
- * // Contour coordinates are [radius, Z].
1014
- * const profile = sectionFromContours([[[8, 0], [12, 0], [12, 16], [8, 16]]]);
1015
- * revolve(profile, { revolveDegrees: 270 });
1016
- * ```
1017
- */
1018
- revolve(this: void, shape: ModelingShape, options?: RevolveOptions): Solid;
1019
- /** Filled XY projection. */
1020
- projectSection(this: void, solid: Solid): Section;
1021
- /** Horizontal filled slice. */
1022
- sliceSection(this: void, solid: Solid, z: number): Section;
1023
- /**
1024
- * Lofts primitive Sections at z heights or frames; arbitrary Sections and loops require an explicit correspondence method.
1025
- *
1026
- * @example Loft
1027
- * ```ts
1028
- * loft([
1029
- * { profile: circle({ diameter: 16 }), z: 0 },
1030
- * { profile: rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } }), z: 30 },
1031
- * ]);
1032
- * ```
1033
- */
1034
- loft(this: void, stations: readonly LoftStation[], options?: LoftOptions): Solid;
1035
- /** Lofts explicit corresponding contours, including holes and collapsed logical slots. */
1036
- loft(this: void, stations: readonly CorrespondingProfileStation[], options?: LoftOptions): Solid;
1037
- /** Explicit family matching on a shared physical span grid using context resolution. */
1038
- matchProfiles(this: void, profiles: readonly Profile[], options?: MatchProfilesOptions): readonly CorrespondingProfile[];
1039
- /**
1040
- * Sweeps filled or explicitly corresponding contours using the selected frame policy.
1041
- *
1042
- * @example Sweep
1043
- * ```ts
1044
- * const profile = rectangle({ size: [6, 3], treatment: { kind: "round", radius: 1 } });
1045
- * sweep(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
1046
- * orientation: { kind: "transport", initialNormal: [0, 1, 0] },
1047
- * });
1048
- * ```
1049
- */
1050
- sweep(this: void, shape: ModelingShape, path: readonly Vec3[], options?: SweepOptions): Solid;
1051
- /**
1052
- * Copies lightweight section measurements.
1053
- *
1054
- * @example Check filled area
1055
- * ```ts
1056
- * const facts = inspectSection(rectangle({ size: [20, 10] }));
1057
- * facts.area; // 200 mm²
1058
- * ```
1059
- */
1060
- inspectSection(this: void, section: Section): SectionInspection;
1061
- /**
1062
- * Reads immutable native facts once per solid; temporary components are owned by the build.
1063
- *
1064
- * @example Check dimensions and volume
1065
- * ```ts
1066
- * const facts = inspectSolid(box({ size: [30, 20, 6] }));
1067
- * facts.volume; // 3600 mm³
1068
- * ```
1069
- */
1070
- inspectSolid(this: void, solid: Solid): SolidInspection;
1071
- /**
1072
- * Checks whether a same-build solid or filled section contains no geometry.
1073
- *
1074
- * Accepts a 3D Solid or 2D Section handle, not a finalized model or raw triangle mesh.
1075
- * Useful after a Boolean operation whose inputs may not overlap; no mesh is extracted.
1076
- *
1077
- * @example Check a missed intersection
1078
- * ```ts
1079
- * const body = box({ size: 10 });
1080
- * const distant = translate(box({ size: 10 }), [30, 0, 0]);
1081
- * const empty = intersect([body, distant]);
1082
- * const missed = isEmpty(empty); // true
1083
- * ```
1084
- */
1085
- isEmpty(this: void, shape: Solid | Section): boolean;
1086
- /**
1087
- * Measures the minimum separation between two nonempty solids in millimetres.
1088
- *
1089
- * Uses actual geometry, not bounding-box separation or distance between object origins.
1090
- * Contact or overlapping material returns zero, including one solid inside another.
1091
- * The kernel's search range is managed internally; the result is not capped at a caller limit.
1092
- * Empty, expired or foreign-build handles reject. Results follow native numeric precision.
1093
- *
1094
- * @example Measure the gap between two blocks
1095
- * ```ts
1096
- * const left = box({ size: 10 });
1097
- * const right = translate(box({ size: 10 }), [13, 0, 0]);
1098
- * const gap = distance(left, right); // 3 mm
1099
- * ```
1100
- */
1101
- distance(this: void, solid: Solid, other: Solid): number;
1102
- /** Copies intersections along the finite directed origin-to-endpoint segment. */
1103
- rayCast(this: void, solid: Solid, origin: Vec3, endpoint: Vec3): readonly SolidRayHit[];
1104
- /**
1105
- * Separates a solid's disconnected surface shells into same-build solid handles.
1106
- *
1107
- * For solids without enclosed cavities, these shells are the disconnected material islands.
1108
- * Enclosed cavities produce separate inward shells with negative signed volume; these cannot
1109
- * be finalized alone as manufacturing parts. This does not cut connected geometry.
1110
- *
1111
- * @example Move disconnected pieces independently
1112
- * ```ts
1113
- * const islands = union([box({ size: 8 }), translate(box({ size: 8 }), [12, 0, 0])]);
1114
- * const pieces = components(islands);
1115
- * // Component order is unspecified; the index only sets a display height here.
1116
- * union(pieces.map((piece, index) => translate(piece, [0, 0, index * 6])));
1117
- * ```
1118
- */
1119
- components(this: void, solid: Solid): readonly Solid[];
1120
- /** Separates filled 2D islands into sections, retaining each island's holes; empty gives []. */
1121
- components(this: void, section: Section): readonly Section[];
1122
- /**
1123
- * Simplifies a solid using an explicit positive millimetre tolerance.
1124
- *
1125
- * Removes redundant vertices while keeping surfaces within the greater of this tolerance
1126
- * and the solid's existing native tolerance. Choose it from the detail you can afford to lose.
1127
- */
1128
- simplify(this: void, solid: Solid, tolerance: number): Solid;
1129
- /**
1130
- * Simplifies filled 2D contours using an explicit positive millimetre tolerance.
1131
- *
1132
- * Useful for dense imported outlines before extrusion. This changes the outline rather
1133
- * than selecting a lower rendering quality; fine features may be removed.
1134
- *
1135
- * @example Clean a dense outline before extrusion
1136
- * ```ts
1137
- * const outline = circle({ diameter: 20, segments: 256 });
1138
- * const cleaned = simplify(outline, 0.05); // 0.05 mm cleanup tolerance
1139
- * const body = extrude(cleaned, { height: 3 });
1140
- * ```
1141
- */
1142
- simplify(this: void, section: Section, tolerance: number): Section;
1143
- /** Bounded positive-inside implicit field constructor. */
1144
- implicit(this: void, options: ImplicitOptions): Solid;
1145
- /** Replaces native tolerance on an immutable copy; zero selects the kernel minimum. */
1146
- setTolerance(this: void, solid: Solid, tolerance: number): Solid;
1147
- /**
1148
- * Closed rectilinear top above a flat base, with uniform or explicit XY coordinates.
1149
- * Samples each grid height once; center-error triangulation also samples each cell centre.
1150
- *
1151
- * @example Heightfield
1152
- * ```ts
1153
- * heightfield({
1154
- * size: [30, 20], segments: [24, 16],
1155
- * height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
1156
- * });
1157
- * ```
1158
- */
1159
- heightfield(this: void, options: HeightfieldOptions): Solid;
1160
- /**
1161
- * Repeats one solid along a normalized direction.
1162
- *
1163
- * @example Three copies along X
1164
- * ```ts
1165
- * linearPattern(box({ size: 4 }), { count: 3, spacing: 10 });
1166
- * ```
1167
- */
1168
- linearPattern(this: void, source: PatternSource, options: LinearPatternOptions): readonly Solid[];
1169
- /**
1170
- * Repeats one solid about an axis.
1171
- *
1172
- * @example Six copies around Z
1173
- * ```ts
1174
- * const pin = translate(cylinder({ height: 6, radius: 2 }), [12, 0, 0]);
1175
- * radialPattern(pin, { count: 6, axis: [0, 0, 1], angleDegrees: 60 });
1176
- * ```
1177
- */
1178
- radialPattern(this: void, source: PatternSource, options: RadialPatternOptions): readonly Solid[];
1179
- /**
1180
- * XY or XYZ copies, optionally centered or placed in an explicit frame.
1181
- *
1182
- * @example Centered XY grid
1183
- * ```ts
1184
- * gridPattern(box({ size: 4 }), { count: [3, 2], spacing: [10, 10], center: true });
1185
- * ```
1186
- */
1187
- gridPattern(this: void, source: PatternSource, options: GridPatternOptions): readonly Solid[];
1188
- /**
1189
- * Physical arc-length copies along a sampled path, with optional tangent orientation.
1190
- *
1191
- * @example Copies along a bent path
1192
- * ```ts
1193
- * pathPattern(box({ size: 4 }), [[0, 0, 0], [20, 0, 0], [20, 20, 0]], { count: 5 });
1194
- * ```
1195
- */
1196
- pathPattern(this: void, source: PatternSource, path: readonly Vec3[], options: PathPatternOptions): readonly Solid[];
1197
- /** Helical ridge mesh construction. */
1198
- threadRidge(this: void, options: ThreadRidgeOptions): Solid;
1199
- /**
1200
- * Compensated external threaded rod.
1201
- *
1202
- * @example Threaded rod
1203
- * ```ts
1204
- * import { threadedRod } from "@metamesh/modeling";
1205
- * import { createThreadProfile } from "@metamesh/modeling/geometry";
1206
- *
1207
- * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
1208
- * threadedRod({ nominalMajorDiameter: 12, length: 24, profile, fit: "normal" });
1209
- * ```
1210
- */
1211
- threadedRod(this: void, options: ThreadedRodOptions): Solid;
1212
- /**
1213
- * Compensated internal threaded cutter.
1214
- *
1215
- * @example Internal thread
1216
- * ```ts
1217
- * import { cylinder, internalThreadCutter, subtract } from "@metamesh/modeling";
1218
- * import { createThreadProfile } from "@metamesh/modeling/geometry";
1219
- *
1220
- * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
1221
- * const body = cylinder({ diameter: 20, height: 12, center: false });
1222
- * const cutter = internalThreadCutter({ nominalMajorDiameter: 12, length: 12, profile });
1223
- * subtract(body, [cutter]);
1224
- * ```
1225
- */
1226
- internalThreadCutter(this: void, options: InternalThreadCutterOptions): Solid;
1227
- /**
1228
- * Compensated threaded nut.
1229
- *
1230
- * @example Threaded nut
1231
- * ```ts
1232
- * import { threadedNut } from "@metamesh/modeling";
1233
- * import { createThreadProfile } from "@metamesh/modeling/geometry";
1234
- *
1235
- * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
1236
- * threadedNut({ nominalMajorDiameter: 12, thickness: 8, width: 20, shape: "hex", profile, fit: "normal" });
1237
- * ```
1238
- */
1239
- threadedNut(this: void, options: ThreadedNutOptions): Solid;
1240
- /** Allocation-free external-thread facts. */
1241
- preflightThreadedRod(this: void, options: ThreadedRodOptions): HelicalThreadSolidMeshPreflight;
1242
- /** Allocation-free internal-thread facts. */
1243
- preflightInternalThreadCutter(this: void, options: InternalThreadCutterOptions): HelicalThreadSolidMeshPreflight;
1244
- /** Allocation-free nut/cutter facts. */
1245
- preflightThreadedNut(this: void, options: ThreadedNutOptions): ThreadedNutPreflight;
1246
- /**
1247
- * Consumes a previously prepared layout; never shapes or fetches a font.
1248
- *
1249
- * @example Use a prepared text layout
1250
- * ```ts
1251
- * // Prepare the exact font and layout before entering build.
1252
- * function labelSection(layout: VectorTextLayout) {
1253
- * return textSection(layout);
1254
- * }
1255
- * ```
1256
- */
1257
- textSection(this: void, layout: VectorTextLayout, options?: TextSectionOptions): Section;
1258
- /**
1259
- * Imports bounded painted SVG document geometry.
1260
- *
1261
- * @example Import a physical SVG rectangle
1262
- * ```ts
1263
- * svgSection(
1264
- * '<svg xmlns="http://www.w3.org/2000/svg" width="30mm" height="20mm" viewBox="0 0 30 20"><rect width="30" height="20"/></svg>',
1265
- * { origin: "center" },
1266
- * );
1267
- * ```
1268
- */
1269
- svgSection(this: void, svg: string, options?: SvgSectionOptions): Section;
1270
- /**
1271
- * Imports bounded filled SVG path data.
1272
- *
1273
- * @example Fill an SVG path in millimetres
1274
- * ```ts
1275
- * svgPathSection("M0 0H20V12H0Z", { origin: "center", scale: 1 });
1276
- * ```
1277
- */
1278
- svgPathSection(this: void, path: string, options?: SvgPathSectionOptions): Section;
1279
- }
1280
-
1281
- /**
1282
- * Returns bound local operations, optionally with derived resolution, without changing imported operations.
1283
- */
1284
- export declare function modelingFunctions(resolution?: GeometryResolution): ModelingContext;
992
+ /** Three-dimensional Minkowski sum. */
993
+ export declare function minkowskiSum(a: Solid, b: Solid): Solid;
1285
994
 
1286
995
  /** Aggregate manufacturing output ceilings selected by a trusted host. */
1287
996
  export declare interface ModelingLimits extends GeometrySamplingLimits {
@@ -1295,14 +1004,31 @@ export declare interface ModelingLimits extends GeometrySamplingLimits {
1295
1004
  readonly maxBytes: number;
1296
1005
  }
1297
1006
 
1298
- /** A native filled shape or sampled profile with explicit contour identities. */
1299
- export declare type ModelingShape = Section | CorrespondingProfile;
1007
+ /** Stateless portable program descriptor. Execution and caches belong to an engine session. */
1008
+ export declare interface ModelProgram<P, S = Record<never, never>> {
1009
+ /** Exact generation protocol discriminator. */
1010
+ readonly kind: "metamesh-model";
1011
+ /** Typed synchronous declaration callback. */
1012
+ readonly generate: GenerateCallback<P, S>;
1013
+ }
1300
1014
 
1301
- /** Named manufacturing output containing exactly one solid or direct mesh. */
1302
- export declare type ModelPart = SolidPart | MeshPart;
1015
+ /** Numeric storage supported by immutable generation buffers. */
1016
+ export declare type NumericArray = Float32Array | Float64Array | Uint32Array | Uint8Array | Int32Array;
1303
1017
 
1304
- /** Host-bound offset operation. Valid only during a synchronous build. */
1305
- export declare const offset: ModelingContext["offset"];
1018
+ /** Manufacturing geometry; filled sections are intermediate construction values. */
1019
+ export declare type PartGeometry = Solid | TriangleMesh | ImmutableTriangleMesh;
1020
+
1021
+ /** Appearance and rigid placement of a finished local manufacturing part. */
1022
+ export declare interface PartOptions {
1023
+ /** Local geometry or a lazy reader; native objects never cross a revision. */
1024
+ readonly geometry: ComputedValue<PartGeometry>;
1025
+ /** XYZ translation in millimetres, applied after rotation; defaults to zero. */
1026
+ readonly position?: ComputedValue<Vec3>;
1027
+ /** Fixed global X, Y, Z rotations in degrees; defaults to zero. */
1028
+ readonly rotation?: ComputedValue<Vec3>;
1029
+ /** Optional six-digit hexadecimal semantic part color. */
1030
+ readonly color?: string;
1031
+ }
1306
1032
 
1307
1033
  /**
1308
1034
  * Supplies a profile-X orientation guide for each original normalized sweep station.
@@ -1313,8 +1039,15 @@ export declare const offset: ModelingContext["offset"];
1313
1039
  */
1314
1040
  export declare type PathNormalGuide = (point: Vec3, index: number) => Vec3;
1315
1041
 
1316
- /** Host-bound pathPattern operation. Valid only during a synchronous build. */
1317
- export declare const pathPattern: ModelingContext["pathPattern"];
1042
+ /**
1043
+ * Physical arc-length copies along a sampled path, with optional tangent orientation.
1044
+ *
1045
+ * @example Copies along a bent path
1046
+ * ```ts
1047
+ * pathPattern(box({ size: 4 }), [[0, 0, 0], [20, 0, 0], [20, 20, 0]], { count: 5 });
1048
+ * ```
1049
+ */
1050
+ export declare function pathPattern(source: PatternSource, path: readonly Vec3[], options: PathPatternOptions): readonly Solid[];
1318
1051
 
1319
1052
  /** Equal physical arc-length placements along an open or implicitly closed sampled path. */
1320
1053
  export declare interface PathPatternOptions {
@@ -1327,7 +1060,7 @@ export declare interface PathPatternOptions {
1327
1060
  }
1328
1061
 
1329
1062
  /**
1330
- * One same-build shape, or a synchronous factory called once per copy in index order.
1063
+ * One same-session shape, or a synchronous factory called once per copy in index order.
1331
1064
  */
1332
1065
  export declare type PatternSource = Solid | ((index: number) => Solid);
1333
1066
 
@@ -1353,14 +1086,14 @@ export declare interface Polygon2 {
1353
1086
  readonly outer: Loop2;
1354
1087
  }
1355
1088
 
1356
- /** Host-bound preflightInternalThreadCutter operation. Valid only during a synchronous build. */
1357
- export declare const preflightInternalThreadCutter: ModelingContext["preflightInternalThreadCutter"];
1089
+ /** Allocation-free internal-thread facts. */
1090
+ export declare function preflightInternalThreadCutter(options: InternalThreadCutterOptions): HelicalThreadSolidMeshPreflight;
1358
1091
 
1359
- /** Host-bound preflightThreadedNut operation. Valid only during a synchronous build. */
1360
- export declare const preflightThreadedNut: ModelingContext["preflightThreadedNut"];
1092
+ /** Allocation-free nut/cutter facts. */
1093
+ export declare function preflightThreadedNut(options: ThreadedNutOptions): ThreadedNutPreflight;
1361
1094
 
1362
- /** Host-bound preflightThreadedRod operation. Valid only during a synchronous build. */
1363
- export declare const preflightThreadedRod: ModelingContext["preflightThreadedRod"];
1095
+ /** Allocation-free external-thread facts. */
1096
+ export declare function preflightThreadedRod(options: ThreadedRodOptions): HelicalThreadSolidMeshPreflight;
1364
1097
 
1365
1098
  /** Placement shared by solid and filled-section factories. */
1366
1099
  export declare interface PrimitivePlacement {
@@ -1480,11 +1213,16 @@ export declare type ProfileSpan2 = {
1480
1213
  readonly end: Vec2;
1481
1214
  });
1482
1215
 
1483
- /** Host-bound projectSection operation. Valid only during a synchronous build. */
1484
- export declare const projectSection: ModelingContext["projectSection"];
1485
-
1486
- /** Host-bound radialPattern operation. Valid only during a synchronous build. */
1487
- export declare const radialPattern: ModelingContext["radialPattern"];
1216
+ /**
1217
+ * Repeats one solid about an axis.
1218
+ *
1219
+ * @example Six copies around Z
1220
+ * ```ts
1221
+ * const pin = cylinder({ height: 6, radius: 2 }).translate([12, 0, 0]);
1222
+ * radialPattern(pin, { count: 6, axis: [0, 0, 1], angleDegrees: 60 });
1223
+ * ```
1224
+ */
1225
+ export declare function radialPattern(source: PatternSource, options: RadialPatternOptions): readonly Solid[];
1488
1226
 
1489
1227
  /**
1490
1228
  * Options for repeating one solid around an axis through a center point.
@@ -1515,11 +1253,18 @@ export declare interface RadialSizingOptions {
1515
1253
  readonly sizing?: RadialSizing;
1516
1254
  }
1517
1255
 
1518
- /** Copies intersections along a finite directed ray segment during the active build. */
1519
- export declare const rayCast: ModelingContext["rayCast"];
1256
+ /** Copies intersections along the finite directed origin-to-endpoint segment. */
1257
+ export declare function rayCast(solid: Solid, origin: Vec3, endpoint: Vec3): readonly SolidRayHit[];
1520
1258
 
1521
- /** Host-bound rectangle operation. Valid only during a synchronous build. */
1522
- export declare const rectangle: ModelingContext["rectangle"];
1259
+ /**
1260
+ * Filled rectangular section with uniform or independently treated corners.
1261
+ *
1262
+ * @example Round the corners
1263
+ * ```ts
1264
+ * rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
1265
+ * ```
1266
+ */
1267
+ export declare function rectangle(options: RectangleOptions): Section;
1523
1268
 
1524
1269
  /** A rectangle corner, including an explicitly untreated corner in a treatment tuple. */
1525
1270
  export declare type RectangleCornerTreatment = EdgeTreatment | {
@@ -1573,8 +1318,15 @@ export declare interface RegionOffsetOptions {
1573
1318
  readonly resolution?: GeometryResolution;
1574
1319
  }
1575
1320
 
1576
- /** Host-bound regularPolygon operation. Valid only during a synchronous build. */
1577
- export declare const regularPolygon: ModelingContext["regularPolygon"];
1321
+ /**
1322
+ * Regular polygon with a vertex on +X.
1323
+ *
1324
+ * @example Hexagonal section
1325
+ * ```ts
1326
+ * regularPolygon({ radius: 10, sides: 6, sizing: "face" });
1327
+ * ```
1328
+ */
1329
+ export declare function regularPolygon(options: RegularPolygonOptions): Section;
1578
1330
 
1579
1331
  /**
1580
1332
  * Regular polygon dimensions, radial convention and degree rotation.
@@ -1588,8 +1340,21 @@ export declare type RegularPolygonOptions = RadialSizingOptions & PrimitivePlace
1588
1340
  readonly rotationDegrees?: number;
1589
1341
  };
1590
1342
 
1591
- /** Host-bound revolve operation. Valid only during a synchronous build. */
1592
- export declare const revolve: ModelingContext["revolve"];
1343
+ /**
1344
+ * Revolves explicit corresponding radial/Z contours around +Z, with caps for partial sweeps.
1345
+ * Filled Sections use `section.revolve(options)`.
1346
+ *
1347
+ * @example Revolve
1348
+ * ```ts
1349
+ * import { matchProfiles, revolve } from "@metamesh/modeling";
1350
+ * import { rectangleProfile } from "@metamesh/modeling/geometry";
1351
+ *
1352
+ * // Contour coordinates are [radius, Z].
1353
+ * const [profile] = matchProfiles([rectangleProfile({ size: [4, 16], center: false })]);
1354
+ * revolve(profile!, { revolveDegrees: 270 });
1355
+ * ```
1356
+ */
1357
+ export declare function revolve(shape: CorrespondingProfile, options?: RevolveOptions): Solid;
1593
1358
 
1594
1359
  /**
1595
1360
  * Circumferential sampling and degree sweep shared by pure and filled revolution.
@@ -1606,9 +1371,6 @@ export declare interface RevolveOptions extends CircularPrimitiveOptions {
1606
1371
  readonly limits?: Partial<ModelingLimits>;
1607
1372
  }
1608
1373
 
1609
- /** Host-bound rotate operation. Valid only during a synchronous build. */
1610
- export declare const rotate: ModelingContext["rotate"];
1611
-
1612
1374
  /**
1613
1375
  * A circular edge or corner roundover with explicit physical sampling.
1614
1376
  */
@@ -1619,19 +1381,72 @@ export declare interface RoundedEdgeTreatment extends CircularPrimitiveOptions {
1619
1381
  readonly radius: number;
1620
1382
  }
1621
1383
 
1622
- /** Host-bound scale operation. Valid only during a synchronous build. */
1623
- export declare const scale: ModelingContext["scale"];
1624
-
1625
- /** Immutable native filled XY section belonging to exactly one synchronous engine build. */
1384
+ /**
1385
+ * Immutable deferred filled XY section recipe belonging to exactly one model session.
1386
+ * Methods run during synchronous generation and preserve their receiver.
1387
+ * Distances use millimetres; rotations are counterclockwise degrees about the origin.
1388
+ * Construction uses the session resolution unless the operation supplies explicit options.
1389
+ *
1390
+ * @example Extrude an outline with a border
1391
+ * ```ts
1392
+ * const body = rectangle({ size: [20, 12] })
1393
+ * .subtract([rectangle({ size: [16, 8] })])
1394
+ * .offset(0.5)
1395
+ * .extrude({ height: 4 });
1396
+ * ```
1397
+ */
1626
1398
  export declare interface Section {
1627
- /** Compile-time ownership brand for a same-build section. */
1399
+ /** Compile-time ownership brand for a same-session section. */
1628
1400
  readonly [sectionBrand]: "Section";
1401
+ /** Translates XY coordinates in millimetres. */
1402
+ translate(this: Section, offset: Vec2): Section;
1403
+ /** Rotates counterclockwise about the origin by a scalar angle in degrees. */
1404
+ rotate(this: Section, degrees: number): Section;
1405
+ /**
1406
+ * Nonsingular scaling about the origin.
1407
+ */
1408
+ scale(this: Section, factors: number | Vec2): Section;
1409
+ /** Reflection across an origin line/plane. */
1410
+ mirror(this: Section, normal: Vec2): Section;
1411
+ /** Row-major affine transform preserving dimensionality. */
1412
+ transform(this: Section, matrix: Transform2): Section;
1413
+ /** Native section difference; an empty cutter array preserves the source. */
1414
+ subtract(this: Section, cutters: readonly Section[]): Section;
1415
+ /**
1416
+ * Simplifies filled 2D contours using an explicit positive millimetre tolerance.
1417
+ *
1418
+ * Useful for dense imported outlines before extrusion. This changes the outline rather
1419
+ * than selecting a lower rendering quality; fine features may be removed.
1420
+ */
1421
+ simplify(this: Section, tolerance: number): Section;
1422
+ /**
1423
+ * Returns a new same-session handle with copied named anchors; existing names may be replaced.
1424
+ */
1425
+ withAnchors(this: Section, anchors: Readonly<Record<string, Anchor3>>): Section;
1426
+ /**
1427
+ * Native millimetre offset preserving holes.
1428
+ */
1429
+ offset(this: Section, distance: number, options?: RegionOffsetOptions): Section;
1430
+ /**
1431
+ * Extrudes along +Z with degree twist and top scaling.
1432
+ */
1433
+ extrude(this: Section, options: ExtrudeOptions): Solid;
1434
+ /**
1435
+ * Revolves a filled radial/Z shape around +Z, with caps for partial sweeps.
1436
+ */
1437
+ revolve(this: Section, options?: RevolveOptions): Solid;
1438
+ /**
1439
+ * Sweeps this filled section using the selected frame policy and degree twist.
1440
+ */
1441
+ sweep(this: Section, path: readonly Vec3[], options?: SweepOptions): Solid;
1629
1442
  }
1630
1443
 
1631
1444
  declare const sectionBrand: unique symbol;
1632
1445
 
1633
- /** Host-bound sectionFromContours operation. Valid only during a synchronous build. */
1634
- export declare const sectionFromContours: ModelingContext["sectionFromContours"];
1446
+ /**
1447
+ * Creates a native filled section without an intermediate Region2 conversion.
1448
+ */
1449
+ export declare function sectionFromContours(contours: readonly Loop2[], options?: SectionFromContoursOptions): Section;
1635
1450
 
1636
1451
  /**
1637
1452
  * Filled-contour resolution. Closing vertices are implicit.
@@ -1641,14 +1456,14 @@ export declare interface SectionFromContoursOptions {
1641
1456
  readonly fillRule?: "nonzero" | "evenodd";
1642
1457
  }
1643
1458
 
1644
- /** Planar convex hull inputs are finite XY points or same-build filled sections. */
1459
+ /** Planar convex hull inputs are finite XY points or same-session filled sections. */
1645
1460
  export declare type SectionHullOptions = {
1646
1461
  /** At least three finite millimetre XY points spanning positive area. */
1647
1462
  readonly points: readonly Vec2[];
1648
1463
  /** Point input excludes section input. */
1649
1464
  readonly sections?: never;
1650
1465
  } | {
1651
- /** One through 1000 same-build sections to include in the convex hull. */
1466
+ /** One through 1000 same-session sections to include in the convex hull. */
1652
1467
  readonly sections: readonly Section[];
1653
1468
  /** Section input excludes point input. */
1654
1469
  readonly points?: never;
@@ -1656,7 +1471,7 @@ export declare type SectionHullOptions = {
1656
1471
 
1657
1472
  /**
1658
1473
  * Immutable native filled section facts in millimetres and square millimetres.
1659
- * Repeated inspections of the same native shape share these facts within one build.
1474
+ * Repeated inspections of the same native shape share these facts within one revision.
1660
1475
  */
1661
1476
  export declare interface SectionInspection {
1662
1477
  /** Whether this filled section has no area or boundary. */
@@ -1675,15 +1490,6 @@ export declare interface SectionInspection {
1675
1490
  readonly vertices: number;
1676
1491
  }
1677
1492
 
1678
- /** Returns an immutable copy with the explicit native millimetre tolerance. */
1679
- export declare const setTolerance: ModelingContext["setTolerance"];
1680
-
1681
- /** Host-bound simplify operation. Valid only during a synchronous build. */
1682
- export declare const simplify: ModelingContext["simplify"];
1683
-
1684
- /** Host-bound sliceSection operation. Valid only during a synchronous build. */
1685
- export declare const sliceSection: ModelingContext["sliceSection"];
1686
-
1687
1493
  /** A cubic corner transition with zero curvature at its straight tangent joins. */
1688
1494
  export declare interface SmoothEdgeTreatment {
1689
1495
  /** Selects continuous-curvature cubic rounding, rather than a circular radius. */
@@ -1698,20 +1504,85 @@ export declare interface SmoothEdgeTreatment {
1698
1504
  readonly limits?: Partial<GeometrySamplingLimits>;
1699
1505
  }
1700
1506
 
1701
- /** Immutable solid handle belonging to exactly one synchronous engine build. */
1507
+ /**
1508
+ * Immutable deferred solid recipe belonging to exactly one model session.
1509
+ * Methods run during synchronous generation, preserve their receiver, and use millimetres and degrees.
1510
+ * A no-op may reuse the receiver; final part placement belongs in `part` options.
1511
+ *
1512
+ * @example Shape a body with a through bore
1513
+ * ```ts
1514
+ * const body = box({ size: [30, 20, 6] })
1515
+ * .subtract([cylinder({ height: 8, radius: 3 })])
1516
+ * .rotate([0, 0, 45]);
1517
+ * ```
1518
+ */
1702
1519
  export declare interface Solid {
1703
- /** Compile-time ownership brand for a same-build solid. */
1520
+ /** Compile-time ownership brand for a same-session solid. */
1704
1521
  readonly [solidBrand]: "Solid";
1522
+ /**
1523
+ * Translates XYZ coordinates in millimetres.
1524
+ */
1525
+ translate(this: Solid, offset: Vec3): Solid;
1526
+ /**
1527
+ * Rotates about the origin using XYZ Euler angles in degrees.
1528
+ */
1529
+ rotate(this: Solid, degrees: Vec3): Solid;
1530
+ /**
1531
+ * Nonsingular scaling about the origin.
1532
+ */
1533
+ scale(this: Solid, factors: number | Vec3): Solid;
1534
+ /**
1535
+ * Reflection across an origin line/plane.
1536
+ */
1537
+ mirror(this: Solid, normal: Vec3): Solid;
1538
+ /** Row-major affine transform preserving dimensionality. */
1539
+ transform(this: Solid, matrix: Transform3): Solid;
1540
+ /**
1541
+ * Robust difference; an empty cutter array preserves the source.
1542
+ */
1543
+ subtract(this: Solid, cutters: readonly Solid[]): Solid;
1544
+ /**
1545
+ * Simplifies a solid using an explicit positive millimetre tolerance.
1546
+ *
1547
+ * Removes redundant vertices while keeping surfaces within the greater of this tolerance
1548
+ * and the solid's existing native tolerance. Choose it from the detail you can afford to lose.
1549
+ */
1550
+ simplify(this: Solid, tolerance: number): Solid;
1551
+ /**
1552
+ * Returns a new same-session handle with copied named anchors; existing names may be replaced.
1553
+ */
1554
+ withAnchors(this: Solid, anchors: Readonly<Record<string, Anchor3>>): Solid;
1555
+ /**
1556
+ * Places an explicit or named source anchor against an explicit target anchor.
1557
+ */
1558
+ attach(this: Solid, source: Anchor3 | string, target: Anchor3, options?: AttachOptions): Solid;
1559
+ /** Replaces native tolerance on an immutable copy; zero selects the kernel minimum. */
1560
+ setTolerance(this: Solid, tolerance: number): Solid;
1561
+ /** Projects this solid into a filled XY section. */
1562
+ projectSection(this: Solid): Section;
1563
+ /** Takes a filled horizontal slice at Z millimetres. */
1564
+ sliceSection(this: Solid, z: number): Section;
1705
1565
  }
1706
1566
 
1707
1567
  declare const solidBrand: unique symbol;
1708
1568
 
1709
- /** Host-bound solidFromMesh operation. Valid only during a synchronous build. */
1710
- export declare const solidFromMesh: ModelingContext["solidFromMesh"];
1569
+ /**
1570
+ * Imports a bounded closed indexed mesh.
1571
+ *
1572
+ * @example Mesh import
1573
+ * ```ts
1574
+ * import { solidFromMesh } from "@metamesh/modeling";
1575
+ * import { extrudeMesh, rectangleLoop } from "@metamesh/modeling/geometry";
1576
+ *
1577
+ * const mesh = extrudeMesh(rectangleLoop({ size: [20, 12] }), { height: 6 });
1578
+ * solidFromMesh(mesh);
1579
+ * ```
1580
+ */
1581
+ export declare function solidFromMesh(mesh: TriangleMesh | ImmutableTriangleMesh): Solid;
1711
1582
 
1712
1583
  /**
1713
1584
  * Immutable solid bounds, emptiness, component count, volume, surface area and native tolerance.
1714
- * Repeated inspections of the same native shape share these facts within one build.
1585
+ * Repeated inspections of the same native shape share these facts within one revision.
1715
1586
  */
1716
1587
  export declare interface SolidInspection {
1717
1588
  /** Whether this native solid contains no material. */
@@ -1730,18 +1601,6 @@ export declare interface SolidInspection {
1730
1601
  readonly tolerance: number;
1731
1602
  }
1732
1603
 
1733
- /** Named same-build solid manufacturing part. */
1734
- export declare interface SolidPart {
1735
- /** Stable canonical lowercase identity; unique within the containing topology or output. */
1736
- readonly id: string;
1737
- /** Optional six-digit hex RGB display color. */
1738
- readonly color?: string;
1739
- /** Same-build solid handle; mutually exclusive with a direct mesh. */
1740
- readonly solid: Solid;
1741
- /** Direct manufacturing mesh; mutually exclusive with a solid handle. */
1742
- readonly mesh?: never;
1743
- }
1744
-
1745
1604
  /** Copied surface intersection from a finite directed segment. Distance is in millimetres. */
1746
1605
  export declare interface SolidRayHit {
1747
1606
  /** Copied numeric native face identity. */
@@ -1754,8 +1613,15 @@ export declare interface SolidRayHit {
1754
1613
  readonly normal: Vec3;
1755
1614
  }
1756
1615
 
1757
- /** Host-bound sphere operation. Valid only during a synchronous build. */
1758
- export declare const sphere: ModelingContext["sphere"];
1616
+ /**
1617
+ * Origin-centered sphere.
1618
+ *
1619
+ * @example Sphere
1620
+ * ```ts
1621
+ * sphere({ diameter: 20 });
1622
+ * ```
1623
+ */
1624
+ export declare function sphere(options: SphereOptions): Solid;
1759
1625
 
1760
1626
  /**
1761
1627
  * Exactly one radius or diameter, placement, and tessellation for an origin-centered sphere.
@@ -1772,11 +1638,45 @@ export declare type SphereOptions = CircularPrimitiveOptions & PrimitivePlacemen
1772
1638
  readonly radius?: never;
1773
1639
  });
1774
1640
 
1775
- /** Returns intersection and difference with a same-build cutter, including empty results. */
1776
- export declare const split: ModelingContext["split"];
1641
+ /**
1642
+ * Splits a solid into [inside the cutter, outside the cutter].
1643
+ *
1644
+ * The first result is the intersection; the second is the subtraction. The cutter itself
1645
+ * is not returned. Either result may be empty or contain multiple disconnected components.
1646
+ *
1647
+ * @example Keep the plug and the surrounding body
1648
+ * ```ts
1649
+ * const body = box({ size: [30, 20, 8] });
1650
+ * const cutter = cylinder({ height: 10, diameter: 8 });
1651
+ * const [plug, remainder] = split(body, cutter);
1652
+ * // Move the plug beside the body to show both results.
1653
+ * union([plug.translate([0, -20, 0]), remainder]);
1654
+ * ```
1655
+ */
1656
+ export declare function split(solid: Solid, cutter: Solid): readonly [Solid, Solid];
1777
1657
 
1778
- /** Splits a solid into the normal-side and opposite-side halves of a world-space plane. */
1779
- export declare const splitByPlane: ModelingContext["splitByPlane"];
1658
+ /**
1659
+ * Splits a solid into [positive-normal side, negative side] at a world-space plane.
1660
+ *
1661
+ * The nonzero normal is normalized; offset is the signed distance from the origin in
1662
+ * millimetres, defaulting to zero. Both cut faces are closed. Select either tuple result
1663
+ * to retain one side; either result may be empty.
1664
+ *
1665
+ * @example Separate two halves at X = 0
1666
+ * ```ts
1667
+ * const body = box({ size: [30, 20, 8] });
1668
+ * const [right, left] = splitByPlane(body, { normal: [1, 0, 0] });
1669
+ * // The gap is only for display; the cut itself removes no material.
1670
+ * union([right.translate([4, 0, 0]), left.translate([-4, 0, 0])]);
1671
+ * ```
1672
+ *
1673
+ * @example Keep only the positive half
1674
+ * ```ts
1675
+ * const [right] = splitByPlane(box({ size: [30, 20, 8] }), { normal: [1, 0, 0] });
1676
+ * right;
1677
+ * ```
1678
+ */
1679
+ export declare function splitByPlane(solid: Solid, plane: PlaneOptions): readonly [Solid, Solid];
1780
1680
 
1781
1681
  /** Square profile with equal crest and root widths. */
1782
1682
  declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
@@ -1789,8 +1689,15 @@ declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
1789
1689
  readonly depth?: number;
1790
1690
  }
1791
1691
 
1792
- /** Host-bound star operation. Valid only during a synchronous build. */
1793
- export declare const star: ModelingContext["star"];
1692
+ /**
1693
+ * Alternating outer/inner star vertices.
1694
+ *
1695
+ * @example Five-point section
1696
+ * ```ts
1697
+ * star({ outerRadius: 12, innerRadius: 6, points: 5 });
1698
+ * ```
1699
+ */
1700
+ export declare function star(options: StarOptions): Section;
1794
1701
 
1795
1702
  /**
1796
1703
  * Alternating outer and inner vertices, centered on the XY origin.
@@ -1808,14 +1715,18 @@ export declare interface StarOptions extends PrimitivePlacement {
1808
1715
  readonly rotationDegrees?: number;
1809
1716
  }
1810
1717
 
1811
- /** Host-bound subtract operation. Valid only during a synchronous build. */
1812
- export declare const subtract: ModelingContext["subtract"];
1813
-
1814
1718
  /** Placement of painted SVG geometry after SVG Y-axis inversion. */
1815
1719
  export declare type SvgOrigin = "center" | "document";
1816
1720
 
1817
- /** Host-bound svgPathSection operation. Valid only during a synchronous build. */
1818
- export declare const svgPathSection: ModelingContext["svgPathSection"];
1721
+ /**
1722
+ * Imports bounded filled SVG path data.
1723
+ *
1724
+ * @example Fill an SVG path in millimetres
1725
+ * ```ts
1726
+ * svgPathSection("M0 0H20V12H0Z", { origin: "center", scale: 1 });
1727
+ * ```
1728
+ */
1729
+ export declare function svgPathSection(path: string, options?: SvgPathSectionOptions): Section;
1819
1730
 
1820
1731
  /** Bounded filled SVG path sampling. Path scale converts user units to millimetres. */
1821
1732
  export declare interface SvgPathSectionOptions {
@@ -1831,8 +1742,18 @@ export declare interface SvgPathSectionOptions {
1831
1742
  readonly scale?: number;
1832
1743
  }
1833
1744
 
1834
- /** Host-bound svgSection operation. Valid only during a synchronous build. */
1835
- export declare const svgSection: ModelingContext["svgSection"];
1745
+ /**
1746
+ * Imports bounded painted SVG document geometry.
1747
+ *
1748
+ * @example Import a physical SVG rectangle
1749
+ * ```ts
1750
+ * svgSection(
1751
+ * '<svg xmlns="http://www.w3.org/2000/svg" width="30mm" height="20mm" viewBox="0 0 30 20"><rect width="30" height="20"/></svg>',
1752
+ * { origin: "center" },
1753
+ * );
1754
+ * ```
1755
+ */
1756
+ export declare function svgSection(svg: string, options?: SvgSectionOptions): Section;
1836
1757
 
1837
1758
  /**
1838
1759
  * Bounded SVG document sampling. Center origin uses the final painted bounds.
@@ -1848,8 +1769,22 @@ export declare interface SvgSectionOptions {
1848
1769
  readonly origin?: SvgOrigin;
1849
1770
  }
1850
1771
 
1851
- /** Host-bound sweep operation. Valid only during a synchronous build. */
1852
- export declare const sweep: ModelingContext["sweep"];
1772
+ /**
1773
+ * Sweeps explicit corresponding contours using the selected frame policy.
1774
+ * Filled Sections use `section.sweep(path, options)`.
1775
+ *
1776
+ * @example Sweep
1777
+ * ```ts
1778
+ * import { matchProfiles, sweep } from "@metamesh/modeling";
1779
+ * import { rectangleProfile } from "@metamesh/modeling/geometry";
1780
+ *
1781
+ * const [profile] = matchProfiles([rectangleProfile({ size: [6, 3] })]);
1782
+ * sweep(profile!, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
1783
+ * orientation: { kind: "transport", initialNormal: [0, 1, 0] },
1784
+ * });
1785
+ * ```
1786
+ */
1787
+ export declare function sweep(shape: CorrespondingProfile, path: readonly Vec3[], options?: SweepOptions): Solid;
1853
1788
 
1854
1789
  /**
1855
1790
  * Controls shared by pure mesh construction and filled modeling sweeps.
@@ -1896,8 +1831,18 @@ export declare type SweepOrientation = {
1896
1831
  readonly kind: "frenet";
1897
1832
  };
1898
1833
 
1899
- /** Host-bound textSection operation. Valid only during a synchronous build. */
1900
- export declare const textSection: ModelingContext["textSection"];
1834
+ /**
1835
+ * Consumes a previously prepared layout; never shapes or fetches a font.
1836
+ *
1837
+ * @example Use a prepared text layout
1838
+ * ```ts
1839
+ * // Prepare the exact font and layout before entering build.
1840
+ * function labelSection(layout: VectorTextLayout) {
1841
+ * return textSection(layout);
1842
+ * }
1843
+ * ```
1844
+ */
1845
+ export declare function textSection(layout: VectorTextLayout, options?: TextSectionOptions): Section;
1901
1846
 
1902
1847
  /**
1903
1848
  * Physical curve sampling applied to already prepared vector text.
@@ -1922,8 +1867,19 @@ declare interface ThreadBevelOptions {
1922
1867
  readonly bevelTop?: boolean;
1923
1868
  }
1924
1869
 
1925
- /** Host-bound threadedNut operation. Valid only during a synchronous build. */
1926
- export declare const threadedNut: ModelingContext["threadedNut"];
1870
+ /**
1871
+ * Compensated threaded nut.
1872
+ *
1873
+ * @example Threaded nut
1874
+ * ```ts
1875
+ * import { threadedNut } from "@metamesh/modeling";
1876
+ * import { createThreadProfile } from "@metamesh/modeling/geometry";
1877
+ *
1878
+ * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
1879
+ * threadedNut({ nominalMajorDiameter: 12, thickness: 8, width: 20, shape: "hex", profile, fit: "normal" });
1880
+ * ```
1881
+ */
1882
+ export declare function threadedNut(options: ThreadedNutOptions): Solid;
1927
1883
 
1928
1884
  /** Nut-edge bevel selection. */
1929
1885
  export declare type ThreadedNutBevel = "automatic" | "both" | "inside" | "none" | "outside";
@@ -1971,8 +1927,19 @@ export declare interface ThreadedNutPreflight {
1971
1927
  */
1972
1928
  export declare type ThreadedNutShape = "hex" | "round" | "square";
1973
1929
 
1974
- /** Host-bound threadedRod operation. Valid only during a synchronous build. */
1975
- export declare const threadedRod: ModelingContext["threadedRod"];
1930
+ /**
1931
+ * Compensated external threaded rod.
1932
+ *
1933
+ * @example Threaded rod
1934
+ * ```ts
1935
+ * import { threadedRod } from "@metamesh/modeling";
1936
+ * import { createThreadProfile } from "@metamesh/modeling/geometry";
1937
+ *
1938
+ * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
1939
+ * threadedRod({ nominalMajorDiameter: 12, length: 24, profile, fit: "normal" });
1940
+ * ```
1941
+ */
1942
+ export declare function threadedRod(options: ThreadedRodOptions): Solid;
1976
1943
 
1977
1944
  /**
1978
1945
  * Options for a compensated external threaded rod along +Z.
@@ -2066,17 +2033,24 @@ declare interface ThreadProfileBaseSpec {
2066
2033
  */
2067
2034
  declare type ThreadProfileSpec = AcmeThreadProfileSpec | ButtressThreadProfileSpec | CustomThreadProfileSpec | SquareThreadProfileSpec | TrapezoidalThreadProfileSpec | TriangularThreadProfileSpec;
2068
2035
 
2069
- /** Host-bound threadRidge operation. Valid only during a synchronous build. */
2070
- export declare const threadRidge: ModelingContext["threadRidge"];
2036
+ /** Helical ridge mesh construction. */
2037
+ export declare function threadRidge(options: ThreadRidgeOptions): Solid;
2071
2038
 
2072
2039
  /** Parameters for a helical ridge before solid construction. */
2073
2040
  export declare type ThreadRidgeOptions = HelicalThreadRidgeMeshOptions;
2074
2041
 
2075
- /** Host-bound toRegion operation. Valid only during a synchronous build. */
2076
- export declare const toRegion: ModelingContext["toRegion"];
2042
+ /** Explicit copied topology inspection; not needed for section operations. */
2043
+ export declare function toRegion(section: Section): Region2;
2077
2044
 
2078
- /** Host-bound torus operation. Valid only during a synchronous build. */
2079
- export declare const torus: ModelingContext["torus"];
2045
+ /**
2046
+ * Torus around +Z.
2047
+ *
2048
+ * @example Torus
2049
+ * ```ts
2050
+ * torus({ majorRadius: 12, minorRadius: 3 });
2051
+ * ```
2052
+ */
2053
+ export declare function torus(options: TorusOptions): Solid;
2080
2054
 
2081
2055
  /**
2082
2056
  * Dimensions and independent ring/profile tessellation for a torus around the Z axis.
@@ -2096,11 +2070,8 @@ export declare interface TorusOptions extends PrimitivePlacement {
2096
2070
  readonly resolution?: GeometryResolution;
2097
2071
  }
2098
2072
 
2099
- /** Host-bound toTriangleMesh operation. Valid only during a synchronous build. */
2100
- export declare const toTriangleMesh: ModelingContext["toTriangleMesh"];
2101
-
2102
- /** Host-bound transform operation. Valid only during a synchronous build. */
2103
- export declare const transform: ModelingContext["transform"];
2073
+ /** Copies a handle to manufacturing mesh buffers. */
2074
+ export declare function toTriangleMesh(solid: Solid): TriangleMesh;
2104
2075
 
2105
2076
  /** Row-major affine XY matrix. Translation occupies m02/m12; final row is [0, 0, 1]. */
2106
2077
  export declare type Transform2 = readonly [
@@ -2140,9 +2111,6 @@ m32: number,
2140
2111
  m33: number
2141
2112
  ];
2142
2113
 
2143
- /** Host-bound translate operation. Valid only during a synchronous build. */
2144
- export declare const translate: ModelingContext["translate"];
2145
-
2146
2114
  /** Trapezoidal thread profile with a configurable included angle. */
2147
2115
  declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
2148
2116
  /** Selects the trapezoidal profile family. */
@@ -2213,8 +2181,15 @@ declare interface TriangularThreadProfileSpec extends ThreadProfileBaseSpec {
2213
2181
  readonly rootFlatRatio?: number;
2214
2182
  }
2215
2183
 
2216
- /** Host-bound tube operation. Valid only during a synchronous build. */
2217
- export declare const tube: ModelingContext["tube"];
2184
+ /**
2185
+ * Hollow +Z tube.
2186
+ *
2187
+ * @example Tube
2188
+ * ```ts
2189
+ * tube({ height: 20, outerRadius: 10, innerRadius: 6 });
2190
+ * ```
2191
+ */
2192
+ export declare function tube(options: TubeOptions): Solid;
2218
2193
 
2219
2194
  /**
2220
2195
  * Dimensions, placement, and tessellation for a hollow Z-axis tube.
@@ -2233,8 +2208,20 @@ export declare interface TubeOptions extends CircularPrimitiveOptions, Primitive
2233
2208
  readonly outerRadius: number;
2234
2209
  }
2235
2210
 
2236
- /** Host-bound union operation. Valid only during a synchronous build. */
2237
- export declare const union: ModelingContext["union"];
2211
+ /**
2212
+ * Robust union.
2213
+ *
2214
+ * @example Union
2215
+ * ```ts
2216
+ * const block = box({ size: 20 });
2217
+ * const cap = sphere({ radius: 10 }).translate([0, 0, 10]);
2218
+ * union([block, cap]);
2219
+ * ```
2220
+ */
2221
+ export declare function union(solids: readonly Solid[]): Solid;
2222
+
2223
+ /** Native filled section union; dimensions cannot be mixed. */
2224
+ export declare function union(sections: readonly Section[]): Section;
2238
2225
 
2239
2226
  /** A two-dimensional Cartesian vector or point. */
2240
2227
  export declare type Vec2 = readonly [x: number, y: number];
@@ -2278,7 +2265,4 @@ export declare interface VectorTextMetrics {
2278
2265
  readonly lineCount: number;
2279
2266
  }
2280
2267
 
2281
- /** Returns a new same-build shape handle with explicit copied named anchors. */
2282
- export declare const withAnchors: ModelingContext["withAnchors"];
2283
-
2284
2268
  export { }