@metamesh/modeling 0.13.0 → 0.14.0

package/dist/api/index.d.ts

@@ -1,4 +1,4 @@
-/** Imported modeling operations and opaque host-owned contracts. @packageDocumentation */
+/** Immutable modeling recipes and math values; the host owns geometry evaluation. @packageDocumentation */
 
 /** ACME 29-degree included-angle profile. */
 declare interface AcmeThreadProfileSpec extends ThreadProfileBaseSpec {
@@ -30,11 +30,11 @@ export declare function anchor(shape: Solid | Section, name: string): Anchor3;
  */
 export declare interface Anchor3 {
   /** Unit outward normal used as the anchor's local +Z direction. */
-  readonly direction: Vector3;
+  readonly direction: Vector3Tuple;
   /** World-space attachment position. */
-  readonly position: Vector3;
+  readonly position: Vector3Tuple;
   /** Roll guide projected into the plane perpendicular to `direction`. */
-  readonly up: Vector3;
+  readonly up: Vector3Tuple;
 }
 
 /**
@@ -54,17 +54,17 @@ export declare interface AttachOptions {
 /** Axis-aligned bounds in two-dimensional model space. */
 export declare interface Bounds2 {
   /** Inclusive maximum X/Y coordinates. */
-  readonly max: Vector2;
+  readonly max: Vector2Tuple;
   /** Inclusive minimum X/Y coordinates. */
-  readonly min: Vector2;
+  readonly min: Vector2Tuple;
 }
 
 /** Axis-aligned bounds in three-dimensional model space. */
 export declare interface Bounds3 {
   /** Inclusive maximum X/Y/Z coordinates. */
-  readonly max: Vector3;
+  readonly max: Vector3Tuple;
   /** Inclusive minimum X/Y/Z coordinates. */
-  readonly min: Vector3;
+  readonly min: Vector3Tuple;
 }
 
 /**
@@ -112,7 +112,7 @@ export declare interface BoxOptions extends PrimitivePlacement {
    */
   readonly center?: boolean;
   /** Positive uniform size or explicit `[X, Y, Z]` extents in millimetres. */
-  readonly size: number | Vector3;
+  readonly size: number | Vector3Tuple;
   /** Uniform treatment or independent disjoint nominal edge/group treatments. */
   readonly treatment?: EdgeTreatment | BoxEdgeTreatments;
 }
@@ -200,11 +200,13 @@ export declare interface CircularPrimitiveOptions {
 }
 
 /**
- * Separates a solid's disconnected surface shells into same-session solid handles.
+ * Observes a solid's disconnected surface shells as session-restricted solid selections.
  *
  * For solids without enclosed cavities, these shells are the disconnected material islands.
  * Enclosed cavities produce separate inward shells with negative signed volume; these cannot
  * be finalized alone as manufacturing parts. This does not cut connected geometry.
+ * Selection order and cardinality depend on evaluated topology. Results and recipes using them
+ * can only be evaluated in this session; composition itself requires no engine.
  *
  * @example Move disconnected pieces independently
  * ```ts
@@ -216,7 +218,10 @@ export declare interface CircularPrimitiveOptions {
  */
 export declare function components(solid: Solid): readonly Solid[];
 
-/** Separates filled 2D islands into sections, retaining each island's holes; empty gives []. */
+/**
+ * Observes filled 2D islands, retaining each island's holes; empty gives [].
+ * Selections and recipes using them can only be evaluated in this session.
+ */
 export declare function components(section: Section): readonly Section[];
 
 /** Combines disjoint components without resolving overlap. */
@@ -241,7 +246,7 @@ export declare type ComputedValue<T> = T | Computed<T>;
  * Polygon exteriors are counter-clockwise and holes are clockwise. Algorithms
  * may reject duplicate adjacent points or fewer than three effective vertices.
  */
-export declare type Contour = readonly Vector2[];
+export declare type Contour = readonly Vector2Tuple[];
 
 /** One sampled component retaining contour identities and logical point correspondence. */
 export declare interface CorrespondingComponent {
@@ -283,7 +288,7 @@ declare interface CustomThreadProfileSpec extends ThreadProfileBaseSpec {
    * Open path spanning exactly `[-pitch/2, pitch/2]`, with both endpoints on the minor envelope,
    * one connected ridge, one contiguous crest, and radial zero at the major envelope.
    */
-  readonly points: readonly Vector2[];
+  readonly points: readonly Vector2Tuple[];
 }
 
 /**
@@ -343,7 +348,7 @@ export declare interface DiagnosticOptions<P> {
  * Uses actual geometry, not bounding-box separation or distance between object origins.
  * Contact or overlapping material returns zero, including one solid inside another.
  * The kernel's search range is managed internally; the result is not capped at a caller limit.
- * Empty, expired or foreign-build handles reject. Results follow native numeric precision.
+ * Empty geometry and component selections from another session reject. Results follow native numeric precision.
  *
  * @example Measure the gap between two blocks
  * ```ts
@@ -380,13 +385,13 @@ export declare type EllipseContourOptions = CircularPrimitiveOptions &
   (
     | {
         /** Positive XY radii in millimetres; mutually exclusive with size. */
-        readonly radius: Vector2;
+        readonly radius: Vector2Tuple;
         /** Full XY extents are unavailable when radius is supplied. */
         readonly size?: never;
       }
     | {
         /** Positive full XY extents in millimetres; mutually exclusive with radius. */
-        readonly size: Vector2;
+        readonly size: Vector2Tuple;
         /** XY radii are unavailable when size is supplied. */
         readonly radius?: never;
       }
@@ -447,7 +452,7 @@ declare interface ExtrusionSamplingOptions {
   /** Operation-level physical policy over the nearest model scope. */
   readonly resolution?: GeometryResolution;
   /** Finite uniform or XY scale of the top profile; defaults to one. */
-  readonly scaleTop?: number | Vector2;
+  readonly scaleTop?: number | Vector2Tuple;
   /** Finite rotation of the top profile about +Z, in degrees; defaults to zero. */
   readonly twistDegrees?: number;
 }
@@ -490,18 +495,15 @@ export declare interface FinalizedPart extends TriangleMesh {
 /** A right-handed orthonormal coordinate frame expressed in world coordinates. */
 export declare interface Frame3 {
   /** World-space origin of the local frame. */
-  readonly origin: Vector3;
+  readonly origin: Vector3Tuple;
   /** Unit vector defining the local +X axis. */
-  readonly xAxis: Vector3;
+  readonly xAxis: Vector3Tuple;
   /** Unit vector defining the local +Y axis. */
-  readonly yAxis: Vector3;
+  readonly yAxis: Vector3Tuple;
   /** Unit vector defining the local +Z axis. */
-  readonly zAxis: Vector3;
+  readonly zAxis: Vector3Tuple;
 }
 
-/** Imports explicit region topology once. */
-export declare function fromRegion(region: Region): Section;
-
 /**
  * Defines a typed model without executing it. Use `computed` only for work worth reusing.
  *
@@ -644,21 +646,22 @@ export declare type GridPatternOptions = {
 } & (
   | {
       /** Positive integer counts on X and Y. */
-      readonly count: Vector2;
+      readonly count: Vector2Tuple;
       /** Signed millimetres between adjacent copies on X and Y. */
-      readonly spacing: Vector2;
+      readonly spacing: Vector2Tuple;
     }
   | {
       /** Positive integer counts on X, Y and Z. */
-      readonly count: Vector3;
+      readonly count: Vector3Tuple;
       /** Signed millimetres between adjacent copies on X, Y and Z. */
-      readonly spacing: Vector3;
+      readonly spacing: Vector3Tuple;
     }
 );
 
 /**
  * Closed rectilinear top above a flat base, with uniform or explicit XY coordinates.
  * Samples each grid height once; center-error triangulation also samples each cell centre.
+ * The retained callback must capture independent immutable inputs, not live session readers or parameters.
  *
  * @example Heightfield
  * ```ts
@@ -681,7 +684,7 @@ export declare function heightfield(options: HeightfieldOptions): Solid;
  */
 export declare type HeightfieldOptions = {
   /** Absolute top Z at the supplied XY point. Every sample must be above baseZ. */
-  readonly height: (point: Vector2) => number;
+  readonly height: (point: Vector2Tuple) => number;
   /** Flat bottom Z. Defaults to zero. */
   readonly baseZ?: number;
   /**
@@ -694,11 +697,11 @@ export declare type HeightfieldOptions = {
 } & (
   | {
       /** Positive XY footprint for uniform sampling. */
-      readonly size: Vector2;
+      readonly size: Vector2Tuple;
       /** Exact positive integer X/Y interval counts. */
       readonly segments: readonly [x: number, y: number];
       /** Lower-left footprint XY. Omitted centers the footprint on XY. */
-      readonly origin?: Vector2;
+      readonly origin?: Vector2Tuple;
       /** Explicit coordinates cannot be combined with uniform sampling. */
       readonly coordinates?: never;
     }
@@ -773,19 +776,19 @@ export declare interface HelicalThreadSolidMeshPreflight {
  */
 export declare function hull(options: HullOptions): Solid;
 
-/** Convex filled XY hull of finite points or same-session sections. */
+/** Convex filled XY hull of finite points or filled section recipes. */
 export declare function hull(options: SectionHullOptions): Section;
 
-/** Hull inputs are either finite points or same-session solids. */
+/** Hull inputs are either finite points or solid recipes. */
 export declare type HullOptions =
   | {
       /** Finite millimetre XYZ points to include in the convex hull. */
-      readonly points: readonly Vector3[];
+      readonly points: readonly Vector3Tuple[];
       /** Point input excludes solid input. */
       readonly solids?: never;
     }
   | {
-      /** Same-build solids to include in the convex hull. */
+      /** Solid recipes to include in the convex hull. */
       readonly solids: readonly Solid[];
       /** Solid input excludes point input. */
       readonly points?: never;
@@ -847,13 +850,16 @@ export declare interface ImmutableTriangleMesh {
   readonly indices: ImmutableBuffer<Uint32Array>;
 }
 
-/** Bounded positive-inside implicit field constructor. */
+/**
+ * Bounded positive-inside implicit field constructor.
+ * The retained callback must capture independent immutable inputs, not live session readers or parameters.
+ */
 export declare function implicit(options: ImplicitOptions): Solid;
 
 /** Positive-inside sampling, bounded to 4M native BCC grid slots and 8M field calls. */
 export declare interface ImplicitOptions {
   /** Positive-inside scalar field evaluated at finite XYZ points. */
-  readonly field: (point: Vector3) => number;
+  readonly field: (point: Vector3Tuple) => number;
   /** Axis-aligned XYZ bounds in millimetres. */
   readonly bounds: Bounds3;
   /** Positive sampling edge length in millimetres. */
@@ -928,7 +934,7 @@ export declare function intersect(solids: readonly Solid[]): Solid;
 export declare function intersect(sections: readonly Section[]): Section;
 
 /**
- * Checks whether a same-session solid or filled section contains no geometry.
+ * Checks whether a solid or filled section contains no geometry during host execution.
  *
  * Accepts a 3D Solid or 2D Section handle, not a finalized model or raw triangle mesh.
  * Useful after a Boolean operation whose inputs may not overlap; no mesh is extracted.
@@ -967,7 +973,7 @@ export declare function linearPattern(
  */
 export declare type LinearPatternOptions = {
   /** Direction of repetition; magnitude is ignored. Defaults to +X. */
-  readonly direction?: Vector3;
+  readonly direction?: Vector3Tuple;
 } & (
   | {
       /** Positive copy count, including the original. */
@@ -1072,7 +1078,7 @@ export declare type LoftPlacement =
  * A Section or point loop at an explicit height or frame.
  */
 export declare type LoftStation = LoftPlacement & {
-  /** Same-build filled Section or ordered XY boundary point data. */
+  /** Filled Section recipe or ordered XY boundary point data. */
   readonly profile: Section | Contour;
 };
 
@@ -1124,14 +1130,17 @@ export declare type PartGeometry = Solid | TriangleMesh | ImmutableTriangleMesh;
 export declare interface PartOptions {
   /** Local geometry or a lazy reader; native objects never cross a revision. */
   readonly geometry: ComputedValue<PartGeometry>;
-  /** XYZ translation in millimetres, applied after rotation; defaults to zero. */
-  readonly position?: ComputedValue<Vector3>;
-  /** Fixed global X, Y, Z rotations in degrees; defaults to zero. */
-  readonly rotation?: ComputedValue<Vector3>;
+  /** XYZ vector or tuple translation in millimetres, applied after rotation; defaults to zero. */
+  readonly position?: ComputedValue<Vector3Input>;
+  /** XYZ vector or tuple of fixed global X, Y, Z rotations in degrees; defaults to zero. */
+  readonly rotation?: ComputedValue<Vector3Input>;
   /** Optional six-digit hexadecimal semantic part color. */
   readonly color?: string;
 }
 
+/** An ordered, open sequence of two-dimensional points. */
+export declare type Path2 = readonly Vector2Tuple[];
+
 /**
  * Supplies a profile-X orientation guide for each original normalized sweep station.
  *
@@ -1140,9 +1149,9 @@ export declare interface PartOptions {
  * @returns A finite guide vector that is not parallel to the local path tangent.
  */
 export declare type PathNormalGuide = (
-  point: Vector3,
+  point: Vector3Tuple,
   index: number,
-) => Vector3;
+) => Vector3Tuple;
 
 /**
  * Physical arc-length copies along a sampled path, with optional tangent orientation.
@@ -1154,7 +1163,7 @@ export declare type PathNormalGuide = (
  */
 export declare function pathPattern(
   source: PatternSource,
-  path: readonly Vector3[],
+  path: readonly Vector3Tuple[],
   options: PathPatternOptions,
 ): readonly Solid[];
 
@@ -1164,7 +1173,7 @@ export declare function pathPattern(
  */
 export declare function pathPattern(
   source: PatternSource<Section>,
-  path: readonly Vector3[],
+  path: readonly Vector3Tuple[],
   options: PathPatternOptions,
 ): readonly Section[];
 
@@ -1179,19 +1188,43 @@ export declare interface PathPatternOptions {
 }
 
 /**
- * One same-session shape, or a synchronous factory called once per copy in index order.
+ * One immutable shape, or a synchronous factory called once per copy in index order.
  */
 export declare type PatternSource<T extends Solid | Section = Solid> =
   T | ((index: number) => T);
 
+/** A fixed XY point in world coordinates; omitted pivots use the coordinate origin. */
+export declare interface Pivot2Options {
+  /** World-space point left fixed by rotation or scaling. */
+  readonly pivot?: Vector2Input;
+}
+
+/** A fixed XYZ point in world coordinates; omitted pivots use the coordinate origin. */
+export declare interface Pivot3Options {
+  /** World-space point left fixed by rotation or scaling. */
+  readonly pivot?: Vector3Input;
+}
+
 /** A world-space cutting plane, retaining the half-space in the normal's direction. */
 export declare interface PlaneOptions {
   /** Finite nonzero plane normal; magnitude does not affect the plane. */
-  readonly normal: Vector3;
+  readonly normal: Vector3Tuple;
   /** Signed millimetre distance from the origin along the unit normal. Defaults to zero. */
   readonly offset?: number;
 }
 
+/**
+ * Fills one closed millimetre XY outline, explicit outer/hole topology, or compound contours.
+ * Closing edges are implicit. Compound contours use nonzero fill unless selected otherwise.
+ * Explicit topology must be simple and disjoint; compound winding may resolve overlaps.
+ *
+ * @example Extrude a triangular plate
+ * ```ts
+ * polygon([[0, 0], [20, 0], [10, 12]]).extrude({ height: 3 });
+ * ```
+ */
+export declare function polygon(input: Contour | PolygonOptions): Section;
+
 /**
  * One bounded two-dimensional polygon.
  *
@@ -1199,25 +1232,13 @@ export declare interface PlaneOptions {
  * their duplicated closing point. Holes must lie inside `outer` and must not
  * intersect each other or the exterior.
  */
-export declare interface Polygon {
+export declare interface PolygonData {
   /** Clockwise interior boundaries, each omitting its duplicated closing point. */
   readonly holes: readonly Contour[];
   /** Counter-clockwise exterior boundary, omitting its duplicated closing point. */
   readonly outer: Contour;
 }
 
-/**
- * Fills one closed millimetre XY outline, explicit outer/hole topology, or compound contours.
- * Closing edges are implicit. Compound contours use nonzero fill unless selected otherwise.
- * Explicit topology must be simple and disjoint; compound winding may resolve overlaps.
- *
- * @example Extrude a triangular plate
- * ```ts
- * polygon([[0, 0], [20, 0], [10, 12]]).extrude({ height: 3 });
- * ```
- */
-export declare function polygon(input: Contour | PolygonOptions): Section;
-
 /** Explicit polygon topology or compound contours; all closing edges are implicit. */
 export declare type PolygonOptions =
   | {
@@ -1229,6 +1250,8 @@ export declare type PolygonOptions =
       readonly contours?: never;
       /** Explicit topology determines fill without a winding rule. */
       readonly fillRule?: never;
+      /** Explicit topology excludes serialized multi-polygon data. */
+      readonly polygons?: never;
     }
   | {
       /** Compound boundaries; may overlap or contain holes according to the fill rule. */
@@ -1239,6 +1262,20 @@ export declare type PolygonOptions =
       readonly outer?: never;
       /** Compound contours determine their own holes. */
       readonly holes?: never;
+      /** Compound fill excludes serialized multi-polygon data. */
+      readonly polygons?: never;
+    }
+  | {
+      /** Explicit filled polygons for serialization and interchange; an empty array is empty. */
+      readonly polygons: RegionData;
+      /** Serialized topology excludes a standalone outer contour. */
+      readonly outer?: never;
+      /** Each serialized polygon owns its own holes. */
+      readonly holes?: never;
+      /** Serialized topology excludes compound contours. */
+      readonly contours?: never;
+      /** Serialized polygons define fill explicitly. */
+      readonly fillRule?: never;
     };
 
 /** Allocation-free internal-thread facts. */
@@ -1332,7 +1369,7 @@ export declare interface ProfiledEdgeTreatment {
    * First coordinates decrease and second coordinates increase. Cylinder/extrusion ends use
    * cap inset first, side setback second; planar corners use incoming then outgoing edges.
    */
-  readonly profile: readonly Vector2[];
+  readonly profile: readonly Vector2Tuple[];
 }
 
 /** An identified line, circular arc, or cubic Bézier between corresponding landmarks. */
@@ -1348,15 +1385,15 @@ export declare type ProfileSpan2 = {
       /** Selects a straight span. */
       readonly kind: "line";
       /** Start point in millimetres. */
-      readonly start: Vector2;
+      readonly start: Vector2Tuple;
       /** End point in millimetres. */
-      readonly end: Vector2;
+      readonly end: Vector2Tuple;
     }
   | {
       /** Selects the geometric curve or span family. */
       readonly kind: "arc";
       /** Center point in millimetres. */
-      readonly center: Vector2;
+      readonly center: Vector2Tuple;
       /** Circular radius in millimetres. */
       readonly radius: number;
       /** Initial counterclockwise angle in degrees. */
@@ -1368,13 +1405,13 @@ export declare type ProfileSpan2 = {
       /** Selects a cubic Bézier span with the same coordinates as CubicBezierCurve2. */
       readonly kind: "cubic";
       /** Start point in millimetres. */
-      readonly start: Vector2;
+      readonly start: Vector2Tuple;
       /** First control point in millimetres. */
-      readonly control1: Vector2;
+      readonly control1: Vector2Tuple;
       /** Second control point in millimetres. */
-      readonly control2: Vector2;
+      readonly control2: Vector2Tuple;
       /** End point in millimetres. */
-      readonly end: Vector2;
+      readonly end: Vector2Tuple;
     }
 );
 
@@ -1405,16 +1442,14 @@ export declare interface RadialPatternOptions {
   /** Number of solids to return, including the original. */
   readonly count: number;
   /** Axis of the right-handed rotation. Its magnitude is ignored. */
-  readonly axis: Vector3;
+  readonly axis: Vector3Tuple;
   /** Signed rotation from one copy to the next, in degrees. */
   readonly angleDegrees: number;
   /** Rotation center in world coordinates. Defaults to the origin. */
-  readonly center?: Vector3;
+  readonly center?: Vector3Tuple;
 }
 
-/**
- * Radial dimensions refer to polygon vertices or compensate faceting to meet polygon faces.
- */
+/** Radial dimensions refer to polygon vertices or compensate faceting to meet polygon faces. */
 export declare type RadialSizing = "vertex" | "face";
 
 /**
@@ -1430,8 +1465,8 @@ export declare interface RadialSizingOptions {
 /** Copies intersections along the finite directed origin-to-endpoint segment. */
 export declare function rayCast(
   solid: Solid,
-  origin: Vector3,
-  endpoint: Vector3,
+  origin: Vector3Tuple,
+  endpoint: Vector3Tuple,
 ): readonly SolidRayHit[];
 
 /**
@@ -1449,7 +1484,7 @@ export declare function rectangle(options: RectangleOptions): Section;
  */
 export declare interface RectangleContourOptions {
   /** Positive uniform size or explicit XY extents in millimetres. */
-  readonly size: number | Vector2;
+  readonly size: number | Vector2Tuple;
   /** Center on XY; otherwise the minimum corner is the origin. Defaults to true. */
   readonly center?: boolean;
   /** Uniform treatment or four corner treatments. Exact round segments describe a complete circle and must divide by four. */
@@ -1481,22 +1516,7 @@ export declare interface RectangleOptions
   extends RectangleContourOptions, PrimitivePlacement {}
 
 /** A two-dimensional region represented by disjoint filled polygons. */
-export declare type Region = readonly Polygon[];
-
-/** Clipper2 join styles accepted by robust region offsets. */
-export declare type RegionOffsetJoin = "miter" | "round" | "square";
-
-/** Options controlling robust Clipper2 region offsets. */
-export declare interface RegionOffsetOptions {
-  /** Number of segments per full circle for round joins. */
-  readonly circularSegments?: number;
-  /** Corner treatment; defaults to `round`. */
-  readonly join?: RegionOffsetJoin;
-  /** Maximum miter extension in offset-distance multiples; at least two. */
-  readonly miterLimit?: number;
-  /** Operation-level physical tessellation policy over the active model-wide policy. */
-  readonly resolution?: GeometryResolution;
-}
+export declare type RegionData = readonly PolygonData[];
 
 /**
  * Regular polygon with a vertex on +X.
@@ -1566,10 +1586,12 @@ export declare interface RoundedEdgeTreatment extends CircularPrimitiveOptions {
 }
 
 /**
- * Immutable deferred filled XY section recipe belonging to exactly one model session.
- * Methods run during synchronous generation and preserve their receiver.
- * Distances use millimetres; rotations are counterclockwise degrees about the origin.
- * Construction uses the session resolution unless the operation supplies explicit options.
+ * Immutable deferred filled XY section recipe. Construction and composition require no engine.
+ * Ordinary recipes may be reused across sessions regardless of where constructed.
+ * Observed components and recipes using them can only be evaluated in their originating session.
+ * Methods leave the source unchanged; observations require a synchronous model execution.
+ * Distances use millimetres; rotations use counterclockwise degrees.
+ * Explicit resolution settings are captured; unspecified settings inherit the evaluating host's defaults.
  *
  * @example Extrude an outline with a border
  * ```ts
@@ -1580,20 +1602,30 @@ export declare interface RoundedEdgeTreatment extends CircularPrimitiveOptions {
  * ```
  */
 export declare interface Section {
-  /** Compile-time ownership brand for a same-session section. */
+  /** Compile-time identity brand for an immutable filled section recipe. */
   readonly [sectionBrand]: "Section";
   /** Translates XY coordinates in millimetres. */
-  translate(this: Section, offset: Vector2): Section;
-  /** Rotates counterclockwise about the origin by a scalar angle in degrees. */
-  rotate(this: Section, degrees: number): Section;
+  translate(this: Section, offset: Vector2Input): Section;
   /**
-   * Nonsingular scaling about the origin.
+   * Rotates counterclockwise in degrees.
+   * `options.pivot` is a fixed world-space point; omission uses the coordinate origin.
    */
-  scale(this: Section, factors: number | Vector2): Section;
+  rotate(this: Section, degrees: number, options?: Pivot2Options): Section;
+  /**
+   * Uniform or per-axis nonsingular scaling; negative factors reflect geometry.
+   * `options.pivot` is a fixed world-space point; omission uses the coordinate origin.
+   */
+  scale(
+    this: Section,
+    factors: number | Vector2Input,
+    options?: Pivot2Options,
+  ): Section;
   /** Reflection across an origin line/plane. */
-  mirror(this: Section, normal: Vector2): Section;
-  /** Row-major affine transform preserving dimensionality. */
-  transform(this: Section, matrix: Transform2): Section;
+  mirror(this: Section, normal: Vector2Input): Section;
+  /** Applies a reusable XY placement or canonical row-major matrix. */
+  transform(this: Section, placement: Transform2Input): Section;
+  /** Copies canonical filled polygons for interchange; requires an active model execution. */
+  toRegionData(this: Section): RegionData;
   /** Native section difference; an empty cutter array preserves the source. */
   subtract(this: Section, cutters: readonly Section[]): Section;
   /**
@@ -1604,7 +1636,7 @@ export declare interface Section {
    */
   simplify(this: Section, tolerance: number): Section;
   /**
-   * Returns a new same-session handle with copied named anchors; existing names may be replaced.
+   * Returns a new recipe with copied named anchors; existing names may be replaced.
    */
   withAnchors(
     this: Section,
@@ -1616,7 +1648,7 @@ export declare interface Section {
   offset(
     this: Section,
     distance: number,
-    options?: RegionOffsetOptions,
+    options?: SectionOffsetOptions,
   ): Section;
   /**
    * Extrudes along +Z with degree twist and top scaling.
@@ -1629,21 +1661,25 @@ export declare interface Section {
   /**
    * Sweeps this filled section using the selected frame policy and degree twist.
    */
-  sweep(this: Section, path: readonly Vector3[], options?: SweepOptions): Solid;
+  sweep(
+    this: Section,
+    path: readonly Vector3Tuple[],
+    options?: SweepOptions,
+  ): Solid;
 }
 
 declare const sectionBrand: unique symbol;
 
-/** Planar convex hull inputs are finite XY points or same-session filled sections. */
+/** Planar convex hull inputs are finite XY points or filled section recipes. */
 export declare type SectionHullOptions =
   | {
       /** At least three finite millimetre XY points spanning positive area. */
-      readonly points: readonly Vector2[];
+      readonly points: readonly Vector2Tuple[];
       /** Point input excludes section input. */
       readonly sections?: never;
     }
   | {
-      /** One through 1000 same-session sections to include in the convex hull. */
+      /** One through 1000 filled section recipes to include in the convex hull. */
       readonly sections: readonly Section[];
       /** Section input excludes point input. */
       readonly points?: never;
@@ -1661,15 +1697,30 @@ export declare interface SectionInspection {
   /** Number of extracted outer and hole contours. */
   readonly contours: number;
   /** Inclusive maximum coordinates in millimetres. */
-  readonly max: Vector2;
+  readonly max: Vector2Tuple;
   /** Inclusive minimum coordinates in millimetres. */
-  readonly min: Vector2;
+  readonly min: Vector2Tuple;
   /** Number of disconnected filled section components. */
   readonly parts: number;
   /** Number of native section vertices. */
   readonly vertices: number;
 }
 
+/** Clipper2 join styles accepted by robust region offsets. */
+export declare type SectionOffsetJoin = "miter" | "round" | "square";
+
+/** Options controlling robust Clipper2 region offsets. */
+export declare interface SectionOffsetOptions {
+  /** Number of segments per full circle for round joins. */
+  readonly circularSegments?: number;
+  /** Corner treatment; defaults to `round`. */
+  readonly join?: SectionOffsetJoin;
+  /** Maximum miter extension in offset-distance multiples; at least two. */
+  readonly miterLimit?: number;
+  /** Operation-level physical tessellation policy over the active model-wide policy. */
+  readonly resolution?: GeometryResolution;
+}
+
 /** A cubic corner transition with zero curvature at its straight tangent joins. */
 export declare interface SmoothEdgeTreatment {
   /** Selects continuous-curvature cubic rounding, rather than a circular radius. */
@@ -1685,8 +1736,11 @@ export declare interface SmoothEdgeTreatment {
 }
 
 /**
- * Immutable deferred solid recipe belonging to exactly one model session.
- * Methods run during synchronous generation, preserve their receiver, and use millimetres and degrees.
+ * Immutable deferred solid recipe. Construction and composition require no engine.
+ * Ordinary recipes may be reused across sessions regardless of where constructed.
+ * Explicit resolution settings are captured; unspecified settings inherit the evaluating host's defaults.
+ * Observed components and recipes using them can only be evaluated in their originating session.
+ * Methods leave the source unchanged and use millimetres and degrees.
  * A no-op may reuse the receiver; final part placement belongs in `part` options.
  *
  * @example Shape a body with a through bore
@@ -1697,26 +1751,32 @@ export declare interface SmoothEdgeTreatment {
  * ```
  */
 export declare interface Solid {
-  /** Compile-time ownership brand for a same-session solid. */
+  /** Compile-time identity brand for an immutable solid recipe. */
   readonly [solidBrand]: "Solid";
   /**
    * Translates XYZ coordinates in millimetres.
    */
-  translate(this: Solid, offset: Vector3): Solid;
+  translate(this: Solid, offset: Vector3Input): Solid;
   /**
-   * Rotates about the origin using XYZ Euler angles in degrees.
+   * Rotates about global X, then Y, then Z in degrees.
+   * `options.pivot` is a fixed world-space point; omission uses the coordinate origin.
    */
-  rotate(this: Solid, degrees: Vector3): Solid;
+  rotate(this: Solid, degrees: Vector3Input, options?: Pivot3Options): Solid;
   /**
-   * Nonsingular scaling about the origin.
+   * Uniform or per-axis nonsingular scaling; negative factors reflect geometry.
+   * `options.pivot` is a fixed world-space point; omission uses the coordinate origin.
    */
-  scale(this: Solid, factors: number | Vector3): Solid;
+  scale(
+    this: Solid,
+    factors: number | Vector3Input,
+    options?: Pivot3Options,
+  ): Solid;
   /**
    * Reflection across an origin line/plane.
    */
-  mirror(this: Solid, normal: Vector3): Solid;
-  /** Row-major affine transform preserving dimensionality. */
-  transform(this: Solid, matrix: Transform3): Solid;
+  mirror(this: Solid, normal: Vector3Input): Solid;
+  /** Applies a reusable XYZ placement or canonical row-major matrix. */
+  transform(this: Solid, placement: Transform3Input): Solid;
   /**
    * Robust difference; an empty cutter array preserves the source.
    */
@@ -1729,7 +1789,7 @@ export declare interface Solid {
    */
   simplify(this: Solid, tolerance: number): Solid;
   /**
-   * Returns a new same-session handle with copied named anchors; existing names may be replaced.
+   * Returns a new recipe with copied named anchors; existing names may be replaced.
    */
   withAnchors(this: Solid, anchors: Readonly<Record<string, Anchor3>>): Solid;
   /**
@@ -1775,9 +1835,9 @@ export declare interface SolidInspection {
   /** Whether this native solid contains no material. */
   readonly isEmpty: boolean;
   /** Inclusive maximum coordinates in millimetres. */
-  readonly max: Vector3;
+  readonly max: Vector3Tuple;
   /** Inclusive minimum coordinates in millimetres. */
-  readonly min: Vector3;
+  readonly min: Vector3Tuple;
   /** Number of connected surface shells; inward cavity shells count separately. */
   readonly parts: number;
   /** Enclosed native solid volume in cubic millimetres. */
@@ -1795,9 +1855,9 @@ export declare interface SolidRayHit {
   /** Distance from the ray origin in millimetres. */
   readonly distance: number;
   /** Intersection position in millimetres. */
-  readonly position: Vector3;
+  readonly position: Vector3Tuple;
   /** Outward unit surface normal at the intersection. */
-  readonly normal: Vector3;
+  readonly normal: Vector3Tuple;
 }
 
 /**
@@ -1913,6 +1973,42 @@ export declare interface StarOptions extends PrimitivePlacement {
   readonly rotationDegrees?: number;
 }
 
+/**
+ * Creates a centered-width native Section along a sampled XY path.
+ *
+ * Shares caps, joins and physical sampling with Geometry's strokePathRegion. Native union
+ * resolves overlapping stroke primitives. Session resolution and resource ceilings apply;
+ * closed paths omit the duplicated seam. Returns an immutable deferred recipe.
+ *
+ * @example Extrude a rounded track
+ * ```ts
+ * stroke([[0, 0], [20, 0], [20, 10]], { width: 3, join: "round", cap: "round" }).extrude({ height: 2 });
+ * ```
+ */
+export declare function stroke(path: Path2, options: StrokeOptions): Section;
+
+/** Physical stroke and topology controls shared by pure regions and native Sections. */
+export declare interface StrokeOptions {
+  /** Explicit path, circular and expanded-profile allocation ceilings. */
+  readonly limits?: Partial<GeometrySamplingLimits>;
+  /** Treat the path as a closed non-duplicated loop. Default: `false`. */
+  readonly closed?: boolean;
+  /** End-cap treatment for an open path. Ignored for closed paths. Default: `butt`. */
+  readonly cap?: StrokePathCap;
+  /** Corner treatment; miters exceeding SVG's default limit of 4 become bevels. Default: `miter`. */
+  readonly join?: StrokePathJoin;
+  /** Physical tessellation policy for round caps and joins. */
+  readonly resolution?: GeometryResolution;
+  /** Positive total stroke width in millimetres, centered on the sampled path. */
+  readonly width: number;
+}
+
+/** End-cap treatment for an open stroked path. */
+export declare type StrokePathCap = "butt" | "round" | "square";
+
+/** Join treatment where adjacent stroked path segments meet. */
+export declare type StrokePathJoin = "bevel" | "miter" | "round";
+
 /** Placement of painted SVG geometry after SVG Y-axis inversion. */
 export declare type SvgOrigin = "center" | "document";
 
@@ -1990,7 +2086,7 @@ export declare interface SvgSectionOptions {
  */
 export declare function sweep(
   shape: CorrespondingProfile,
-  path: readonly Vector3[],
+  path: readonly Vector3Tuple[],
   options?: SweepOptions,
 ): Solid;
 
@@ -2011,7 +2107,7 @@ export declare interface SweepOptions {
   /** Twist advances by physical path length (default), or normalized authored station position, including a closed seam gap. */
   readonly twistBy?: "length" | "stations";
   /** Positive uniform/XY scale, or one XY pair per path station. Defaults to one. */
-  readonly scale?: number | Vector2 | readonly Vector2[];
+  readonly scale?: number | Vector2Tuple | readonly Vector2Tuple[];
   /** Corresponding point-index advance at a rotationally equivalent closed seam. */
   readonly seamProfileOffset?: number;
 }
@@ -2024,13 +2120,13 @@ export declare type SweepOrientation =
       /** Minimizes frame rotation by parallel transport. */
       readonly kind: "transport";
       /** Initial profile +X guide, projected perpendicular to the first tangent. */
-      readonly initialNormal?: Vector3;
+      readonly initialNormal?: Vector3Tuple;
     }
   | {
       /** Projects one fixed world-space normal at every path station. */
       readonly kind: "fixed-normal";
       /** Directed profile +X guide; must not be parallel to any local tangent. */
-      readonly normal: Vector3;
+      readonly normal: Vector3Tuple;
     }
   | {
       /** Uses an explicitly directed normal callback at each original normalized station. */
@@ -2237,7 +2333,7 @@ export declare interface ThreadProfile {
   /** Adjacent axial thread spacing in millimetres. */
   readonly pitch: number;
   /** Immutable open `[axial, radial]` path spanning one pitch. */
-  readonly points: readonly Vector2[];
+  readonly points: readonly Vector2Tuple[];
   /** Axial width of the flat at the minor envelope. */
   readonly rootFlatWidth: number;
 }
@@ -2267,9 +2363,6 @@ export declare function threadRidge(options: ThreadRidgeOptions): Solid;
 /** Parameters for a helical ridge before solid construction. */
 export declare type ThreadRidgeOptions = HelicalThreadRidgeMeshOptions;
 
-/** Explicit copied topology inspection; not needed for section operations. */
-export declare function toRegion(section: Section): Region;
-
 /**
  * Torus around +Z.
  *
@@ -2301,8 +2394,51 @@ export declare interface TorusOptions extends PrimitivePlacement {
 /** Copies a handle to manufacturing mesh buffers. */
 export declare function toTriangleMesh(solid: Solid): TriangleMesh;
 
-/** Row-major affine XY matrix. Translation occupies m02/m12; final row is [0, 0, 1]. */
-export declare type Transform2 = readonly [
+/** Immutable reusable XY placement. Methods apply in written order; angles are degrees. */
+export declare interface Transform2 {
+  /** Applies a translation in model units after this placement. */
+  translate(offset: Vector2Input): Transform2;
+  /** Rotates counterclockwise in degrees about an optional world-space pivot (default origin). */
+  rotate(degrees: number, options?: Pivot2Options): Transform2;
+  /** Scales about an optional world-space pivot; finite nonzero factors may reflect. */
+  scale(factors: number | Vector2Input, options?: Pivot2Options): Transform2;
+  /** Applies this placement first, then `next`; neither operand is mutated. */
+  andThen(next: Transform2Input): Transform2;
+  /** Returns the inverse; singular and numerically unstable transforms throw GeometryError. */
+  inverse(): Transform2;
+  /** Transforms a finite point, including translation. Returns a fresh immutable vector. */
+  applyPoint(point: Vector2Input): Vector2;
+  /** Transforms a finite direction, excluding translation and retaining scale. This is not a normal transform. */
+  applyDirection(direction: Vector2Input): Vector2;
+  /** Applies the inverse transpose and normalizes. Ignores translation; rejects zero normals. */
+  applyNormal(normal: Vector2Input): Vector2;
+  /** Returns the frozen canonical row-major 3x3 matrix for interchange. */
+  toMatrix(): Transform2Matrix;
+  /** Embeds this placement in XYZ, leaving Z unchanged, for solids and 3D paths. */
+  to3D(): Transform3;
+}
+
+/**
+ * Creates an immutable XY transform, identity by default. Matrices are copied and validated.
+ * Pass it directly to Section.transform() and planar data helpers; to3D() explicitly crosses into XYZ.
+ * Zero scales and singular matrices throw GeometryError; negative scales reflect.
+ *
+ * @example
+ * ```ts
+ * const placement = transform2().rotate(90).translate([10, 0]);
+ * placement.applyPoint([1, 0]).toArray(); // approximately [10, 1]
+ * ```
+ */
+export declare function transform2(matrix?: Transform2Matrix): Transform2;
+
+/** An immutable XY transform or its canonical row-major matrix for interchange. */
+export declare type Transform2Input = Transform2 | Transform2Matrix;
+
+/**
+ * A row-major affine 3x3 XY matrix applied to column vectors.
+ * Translation occupies indices 2 and 5; the final row is `[0, 0, 1]`.
+ */
+export declare type Transform2Matrix = readonly [
   m00: number,
   m01: number,
   m02: number,
@@ -2314,13 +2450,60 @@ export declare type Transform2 = readonly [
   m22: number,
 ];
 
+/** Immutable reusable XYZ placement. Methods apply in written order; angles are degrees. */
+export declare interface Transform3 {
+  /** Applies a translation in model units after this placement. */
+  translate(offset: Vector3Input): Transform3;
+  /** Rotates about global X, then Y, then Z in degrees, about an optional world-space pivot. */
+  rotate(degrees: Vector3Input, options?: Pivot3Options): Transform3;
+  /** Rotates right-handed in degrees about a nonzero axis and optional world-space pivot. */
+  rotateAxis(
+    axis: Vector3Input,
+    degrees: number,
+    options?: Pivot3Options,
+  ): Transform3;
+  /** Scales about an optional world-space pivot; finite nonzero factors may reflect. */
+  scale(factors: number | Vector3Input, options?: Pivot3Options): Transform3;
+  /** Applies this placement first, then `next`; equivalent to composeTransform3(next, current). */
+  andThen(next: Transform3Input): Transform3;
+  /** Returns the inverse; singular and numerically unstable transforms throw GeometryError. */
+  inverse(): Transform3;
+  /** Transforms a finite point, including translation. Returns a fresh immutable vector. */
+  applyPoint(point: Vector3Input): Vector3;
+  /** Transforms a finite direction, excluding translation and retaining scale. This is not a normal transform. */
+  applyDirection(direction: Vector3Input): Vector3;
+  /** Applies the inverse transpose and normalizes. Ignores translation; rejects zero normals. */
+  applyNormal(normal: Vector3Input): Vector3;
+  /** Returns the frozen canonical row-major 4x4 matrix for interchange. */
+  toMatrix(): Transform3Matrix;
+  /** Restricts to XY; throws GeometryError for a plane change or singular XY restriction. */
+  to2D(): Transform2;
+}
+
+/**
+ * Creates an immutable XYZ transform, identity by default. Matrices are copied and validated.
+ * Calls apply in written order; rotations use degrees and pivots use current world coordinates.
+ * Zero scales, singular matrices, nonfinite inputs and zero rotation axes throw GeometryError.
+ * Use frameTransform3(frame) as the input for existing orthonormal frame placement.
+ *
+ * @example
+ * ```ts
+ * const placement = transform3().rotate([0, 0, 90]).translate([10, 0, 0]);
+ * placement.applyPoint([1, 0, 0]).toArray(); // approximately [10, 1, 0]
+ * ```
+ */
+export declare function transform3(matrix?: Transform3Matrix): Transform3;
+
+/** An immutable XYZ transform or its canonical row-major matrix for interchange. */
+export declare type Transform3Input = Transform3 | Transform3Matrix;
+
 /**
  * A row-major affine 4x4 matrix applied to column vectors.
  *
  * Translation occupies indices 3, 7, and 11. The final row must be
  * `[0, 0, 0, 1]` within the active geometry tolerance.
  */
-export declare type Transform3 = readonly [
+export declare type Transform3Matrix = readonly [
   m00: number,
   m01: number,
   m02: number,
@@ -2452,11 +2635,97 @@ export declare function union(solids: readonly Solid[]): Solid;
 /** Native filled section union; dimensions cannot be mixed. */
 export declare function union(sections: readonly Section[]): Section;
 
+/** Immutable XY arithmetic; vector operations return new values and measurements return numbers. */
+export declare interface Vector2 {
+  /** X coordinate in the vector's coordinate units. */
+  readonly x: number;
+  /** Y coordinate in the vector's coordinate units. */
+  readonly y: number;
+  /** Adds another vector component-wise. */
+  add(other: Vector2Input): Vector2;
+  /** Subtracts another vector component-wise. */
+  subtract(other: Vector2Input): Vector2;
+  /** Multiplies by a finite dimensionless scalar. */
+  scale(factor: number): Vector2;
+  /** Returns a unit vector; rejects length at or below finite nonnegative `epsilon` (default `1e-12`). */
+  normalize(epsilon?: number): Vector2;
+  /** Interpolates toward another vector by finite dimensionless `t`; extrapolation is allowed. */
+  lerp(other: Vector2Input, t: number): Vector2;
+  /** Returns the scalar dot product. */
+  dot(other: Vector2Input): number;
+  /** Returns the signed scalar cross product; positive means the other vector is counterclockwise. */
+  cross(other: Vector2Input): number;
+  /** Returns Euclidean length in the vector's coordinate units. */
+  length(): number;
+  /** Returns Euclidean distance to another vector in the same coordinate units. */
+  distance(other: Vector2Input): number;
+  /** Returns this value's frozen readonly tuple for interchange; repeated calls do not allocate. */
+  toArray(): Vector2Tuple;
+}
+
+/**
+ * Creates immutable XY arithmetic from a finite tuple or vector, snapshotting the coordinates.
+ * Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
+ * and overflow throw `NON_FINITE_VALUE` GeometryError.
+ * Use transform2().applyDirection(value) for rotations and nonuniform scaling.
+ */
+export declare function vector2(input: Vector2Input): Vector2;
+
+/** An XY tuple or immutable fluent vector accepted by vector operations. */
+export declare type Vector2Input = Vector2Tuple | Vector2;
+
 /** A two-dimensional Cartesian vector or point. */
-export declare type Vector2 = readonly [x: number, y: number];
+export declare type Vector2Tuple = readonly [x: number, y: number];
+
+/** Immutable XYZ arithmetic; vector operations return new values and measurements return numbers. */
+export declare interface Vector3 {
+  /** X coordinate in the vector's coordinate units. */
+  readonly x: number;
+  /** Y coordinate in the vector's coordinate units. */
+  readonly y: number;
+  /** Z coordinate in the vector's coordinate units. */
+  readonly z: number;
+  /** Adds another vector component-wise. */
+  add(other: Vector3Input): Vector3;
+  /** Subtracts another vector component-wise. */
+  subtract(other: Vector3Input): Vector3;
+  /** Multiplies by a finite dimensionless scalar. */
+  scale(factor: number): Vector3;
+  /** Returns a unit vector; rejects length at or below finite nonnegative `epsilon` (default `1e-12`). */
+  normalize(epsilon?: number): Vector3;
+  /** Interpolates toward another vector by finite dimensionless `t`; extrapolation is allowed. */
+  lerp(other: Vector3Input, t: number): Vector3;
+  /** Returns the scalar dot product. */
+  dot(other: Vector3Input): number;
+  /** Returns the right-handed cross product as a new vector. */
+  cross(other: Vector3Input): Vector3;
+  /** Returns Euclidean length in the vector's coordinate units. */
+  length(): number;
+  /** Returns Euclidean distance to another vector in the same coordinate units. */
+  distance(other: Vector3Input): number;
+  /** Returns this value's frozen readonly tuple for interchange; repeated calls do not allocate. */
+  toArray(): Vector3Tuple;
+}
+
+/**
+ * Creates immutable XYZ arithmetic from a finite tuple or vector, snapshotting the coordinates.
+ * Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
+ * and overflow throw `NON_FINITE_VALUE` GeometryError.
+ * Use transform3().applyDirection(value) for rotations and nonuniform scaling.
+ *
+ * @example
+ * ```ts
+ * const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+ * const alignment = direction.dot([0, 0, 1]);
+ * ```
+ */
+export declare function vector3(input: Vector3Input): Vector3;
+
+/** An XYZ tuple or immutable fluent vector accepted by vector operations. */
+export declare type Vector3Input = Vector3Tuple | Vector3;
 
 /** A three-dimensional Cartesian vector or point. */
-export declare type Vector3 = readonly [x: number, y: number, z: number];
+export declare type Vector3Tuple = readonly [x: number, y: number, z: number];
 
 /**
  * Immutable vector layout with no browser, font parser, or kernel ownership.