@metamesh/modeling 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @metamesh/modeling
 
+## 0.8.0
+
+### Minor Changes
+
+- bf1abe4: Add circular baselines to prepared vector text and Generator text services. Shaped glyphs and attached marks rotate rigidly around a millimetre radius, preserving kerning, ligatures, exact curve bounds and logical advances. Circular text is limited to one line, baseline vertical alignment, less than one revolution, and outlines that stay clear of the circle's center axis.
+- bf1abe4: Complete solid splitting, plane clipping, Section hull/component/simplification operations, minimum-distance
+  queries and inspection facts. Add optional bounded geometric solid
+  validation at build/export boundaries and a pure uniform-density volume centroid helper.
+  Reuse immutable native inspection facts within a build and fresh owned topology analysis during
+  solid validation; share checks for identical buffer ranges without trusting mutable external facts.
+
+  Unify SVG default/preset limits and strict preset metadata checks. Preserve structured validation
+  codes and nested paths, add physical mesh assertions, and require runtime 2.1 for the current host
+  surface and issue metadata.
+
+- bf1abe4: Add explicit uneven XY coordinates and optional shorter-edge or centre-error diagonal selection to heightfield and heightfieldMesh. Preserve uniform-grid sampling and fixed triangulation by default, with unchanged mesh allocation counts and strict Float32 coordinate checks.
+
+  Reject out-of-range section miter limits and inherited names in mechanical standards and thread-fit lookups. Avoid copying section polygons when only their count is needed.
+
+### Patch Changes
+
+- bf1abe4: Reject cap triangulation workloads that cannot fit the comparison budget before ear clipping, preserving the existing work ceiling and input vertices.
+- bf1abe4: Detect triangle crossings when an edge endpoint lies within the solid-validation tolerance, and avoid redundant topology analysis during solid validation.
+
 ## 0.7.0
 
 ### Patch Changes

package/README.md

@@ -102,6 +102,16 @@ work limits remain fixed operation safeguards.
 
 `engine.export3mf` consumes selected finalized buffers without preparation or generation. Its lazy ZIP/XML serializer preserves exact selected vertices, triangle indices, semantic part names, and optional RGB display colors without a native or glTF conversion. Hosts own revisions, appearance overrides, filenames, delivery, and persistence.
 
+Build and 3MF export accept `meshValidation: "solid"` for bounded geometric validation in addition
+to their default indexed topology checks. This rejects intersecting/touching separate shells and
+incorrectly oriented nested boundaries while preserving inward cavity shells. Checks apply to each
+part independently; separate semantic parts may intentionally overlap. It uses the same pure
+`validateSolidMesh` capability described below. Finalization reuses fresh topology facts for its
+privately owned selected buffers; export captures mutable input before fresh analysis. Within one
+operation, identical buffer ranges share checks. No caller-supplied or cross-operation facts are
+trusted. Its additional work and failure ceilings are explicit;
+the default `"topology"` mode retains the existing large-model workflow.
+
 ## Resolution and conventions
 
 Primitive and pure loop factories share named options and these conventions:
@@ -323,8 +333,10 @@ All loft routes share `LoftOptions`. Pure `loftMesh` requires an explicit method
 closed simple-loop mesh without an engine. Selected sampling/output budgets apply before expanded
 grids and mesh buffers; fixed aggregate safeguards bound correspondence at eight million comparisons
 and the complete grid at one million logical slots. Simple-loop cap triangulation also has an
-eight-million-comparison work ceiling. Complexity rejects instead of reducing fidelity
-or substituting another method. Pure counterparts also include `sweepMesh`, `extrudeMesh` and `revolveMesh`.
+eight-million-comparison work ceiling. Caps whose minimum comparison count exceeds that ceiling
+reject before ear clipping; other caps retain the running work check. Complexity rejects instead of
+reducing fidelity or substituting another method. Pure counterparts also include `sweepMesh`,
+`extrudeMesh` and `revolveMesh`.
 
 ### Patterns and bounded surfaces
 
@@ -342,16 +354,64 @@ algorithm ceiling and selected output budgets reject before predictable native c
 varying factories are checked cumulatively before each transform. Path input and placement counts
 also obey `maxPathPoints`. Copies use the shared transform and lifetime checks.
 
-`heightfieldMesh` and the modeling `heightfield` create a closed grid surface with explicit XY size, segment counts, and base Z. Heights are absolute Z values strictly above the base. Allocation is checked before sampling, and the height callback runs once per grid point.
+`heightfield` returns a Solid for transforms and booleans; `heightfieldMesh` returns the same
+closed construction as pure indexed data. Supply `size`, `segments`, and optional `origin` for a
+uniform grid, or `coordinates: { x, y }` for absolute, unevenly spaced XY samples. Explicit axes
+must increase strictly and remain distinct in Float32. This lets callers refine narrow borders
+without remapping mesh vertices. Heights remain absolute Z values strictly above `baseZ` (default
+zero); sampling never rescales the field.
+
+`triangulation` defaults to `"fixed"`, preserving the lower-left to upper-right diagonal.
+`"min-edge"` chooses the shorter 3D diagonal without extra sampling. `"center-error"` samples the
+physical cell centre once and chooses the diagonal whose interpolated height is closer there.
+Ties retain the fixed diagonal. Every policy uses two top triangles per cell and the same closed
+walls and flat base; centre agreement does not guarantee accuracy elsewhere. Allocation and
+coordinate precision are checked before height callbacks. Each grid point is sampled once, with
+one additional callback per cell for `"center-error"`.
+
+```ts
+heightfield({
+  coordinates: { x: [-15, -14.5, 0, 14.5, 15], y: [-10, -9.5, 0, 9.5, 10] },
+  triangulation: "min-edge",
+  height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
+});
+```
 
 Pure mechanical modules own thread profiles, sampling, printable fit, meshes, and allocation-free `preflightThreadedRod`, `preflightInternalThreadCutter`, and `preflightThreadedNut`. Engine methods own native construction. `pitch` is adjacent axial spacing; `lead = pitch × starts` is advance per turn. Internal cutters extend beyond requested faces and compensate faceting while preserving end treatments. Printable modeling forms are not certified thread classes or structural ratings.
 
+`split(solid, cutter)` returns intersection followed by subtraction as two same-build handles.
+`splitByPlane(solid, { normal, offset })` returns the positive-normal side followed by the negative
+side. Destructure `[positive]` or `[, negative]` to retain just one side. The nonzero normal is
+normalized and `offset` is the signed distance from the world origin in millimetres (default zero).
+Empty results are valid handles
+for `isEmpty`, inspection and further operations, but cannot be finalized as manufacturing parts.
+
+`hull` accepts Solid inputs/XYZ points or Section inputs/XY points. `components` and `simplify`
+also preserve either dimension. Solid components are disconnected surface shells: inward cavity
+shells count separately in `inspectSolid().parts` and cannot be finalized alone. Section components
+are filled islands that retain their holes. `inspectSolid` includes surface area, native tolerance and emptiness;
+`inspectSection` includes emptiness. Both return immutable native facts shared by repeated
+inspections of the same shape within one build, including aliases and derived resolution contexts.
+Transforms, Booleans and tolerance changes have their own facts. The execution clears these caches
+on disposal; retained facts contain no live native values.
+
+`distance(a, b)` measures the minimum separation between two nonempty solids in millimetres.
+It returns zero for contact or overlapping material. The kernel's search range is managed internally;
+there is no caller-supplied distance cutoff. Queries use native geometry and precision without
+extracting a triangle mesh; empty, expired and foreign-build handles reject.
+
+Installed Generators using these added host operations or Section overloads declare minimum runtime
+2.1.0. Imported operations require the current host context; package metadata declares the runtime
+capabilities the Generator uses.
+
 `implicit` samples a finite positive-inside field within explicit bounds and grid spacing. Grid allocations and field evaluations are bounded. `components` returns same-build handles. `simplify` requires explicit millimetre tolerance and preserves native original-surface cleanup semantics.
 
 ## Prepared text and SVG
 
 Preparation shapes text once with the host's exact font service and retains immutable `VectorTextLayout`. Imported `textSection(layout, options)` consumes vector paths directly, without font shaping, fetching, or ambient providers. Paths and metrics use Y-up millimetres and a baseline origin. Empty layouts are measurable but cannot create sections. Font preparation remains optional and outside synchronous builds.
 
+`baseline: { kind: "arc", radius }` places one line on a circle centered at the XY origin, in millimetres. Alignment defaults to `"center"` at `centerAngleDegrees` (90° from +X by default); `"left"` and `"right"` place the logical start and end at that datum. Direction defaults to `"clockwise"`, giving upright top lettering at 90°; `"counterclockwise"` at 270° gives upright bottom lettering. Shaped glyphs and attached zero-advance marks rotate rigidly, preserving their proportions, kerning and ligatures. Exact ink bounds describe the placed curves; `logicalWidth` and `advance[0]` retain the unwrapped arc length including spaces. Radius must be positive and at most 10000 mm. Arcs require baseline vertical alignment and reject multiline text, logical spans of a full revolution, and glyph outlines crossing the circle's center axis. Adjacent glyph collision and fit within a particular face remain consumer policy.
+
 Install `fontkit` to use `prepareVectorFont` from `/text`, and `woff2-encoder` when decoding WOFF2. These optional peers are loaded only when preparing fonts. `sampleTextContours` from `/geometry` and `textSection` share bounded path sampling and need no font dependencies for an already prepared layout.
 
 `svgSection` imports bounded painted SVG documents; `svgPathSection` imports filled path data. Y-down coordinates convert to Y-up; nonzero/even-odd filling preserves counters. Sampling applies after transforms and unit conversion. Basic shapes, groups, affine transforms, physical units, viewBox, fills, and strokes are supported. Text must be outlined. External resources, scripts, clipping, masks, filters, and unsupported content fail contextually. Pure parsers are shared with validation and the vector editor.
@@ -360,6 +420,19 @@ Install `fontkit` to use `prepareVectorFont` from `/text`, and `woff2-encoder` w
 
 `analyzeTriangleMesh` validates and supplies bounds, counts, area, and signed volume in one traversal, with optional edge/component facts. Measurements, bounds, and signatures are independent immutable snapshots; external mutable buffers are inspected freshly on each call. Closed-edge checks require two oppositely wound faces per edge; they do not detect every geometric self-intersection. `createTriangleMeshSignature` adds quantized bounds, volume, topology, and a regression fingerprint, not a cryptographic digest.
 
+Pure `validateSolidMesh(mesh, options)` adds spatial triangle tests, a single closed incident fan at
+every vertex, and shell containment/orientation checks, including cavity boundaries and islands.
+It never repairs or changes input buffers.
+Floating-point contacts within the selected `tolerance` reject conservatively; this is not an exact
+predicate or a manufacturing certification. Its fixed ceilings are 200,000 triangles and 2,000,000
+spatial/containment tests. `maximumTests` may lower the work ceiling. Exhaustion throws
+`COMPLEXITY_LIMIT` and never returns an unchecked result. All position vertices must be referenced.
+
+`computeTriangleMeshCentroid(mesh)` returns an immutable uniform-density volume centroid in
+millimetres for consistently oriented closed geometry, accounting for inward cavity shells.
+It checks indexed closure and positive aggregate volume; use solid validation first for untrusted
+geometric shell arrangements.
+
 The optional `meshTopologyMode: "optimized"` build setting runs bounded planar edge flips for either
 execution lane. It preserves vertices, boundaries, winding, closure, reconstructability, area, and
 volume. This is local connectivity cleanup, not general remeshing; source buffers never change in place.

package/dist/api/engine.d.ts

@@ -6,6 +6,8 @@ declare const defaultModelingLimits: Readonly<ModelingLimits>;
 
 /** Execution settings supplied by the host, independently of generator metadata. */
 export interface BuildOptions {
+    /** Optional bounded intersection and nested-shell checks; defaults to indexed topology validation. */
+    readonly meshValidation?: "topology" | "solid";
     /** Per-build limits, no larger than the configured engine ceilings. */
     readonly limits?: Partial<ModelingLimits>;
     /** Physical sampling defaults; model-derived contexts and exact counts override these. */
@@ -37,6 +39,8 @@ export interface ExportMeshPart extends TriangleMesh {
  * Completed-snapshot serialization settings; filename selection belongs to the host.
  */
 export interface Export3mfOptions {
+    /** Optional bounded geometric solid checks on captured buffers; defaults to indexed topology validation. */
+    readonly meshValidation?: "topology" | "solid";
     /** Document display name; defaults to MetaMesh model. */
     readonly name?: string;
 }

package/dist/api/geometry.d.ts

@@ -425,6 +425,17 @@ export declare interface ArcCurve3 {
   */
  export declare const computeParallelTransportFrames: (path: readonly Vec3[], initialNormal?: Vec3, normalGuide?: PathNormalGuide, limits?: Partial<GeometrySamplingLimits>) => readonly PathFrame[];
 
+ /**
+  * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
+  * Coordinates are millimetres. Indexed closure and positive aggregate volume are required; callers
+  * may use validateSolidMesh first when geometric intersections and shell orientation are untrusted.
+  * Fresh mutable input is inspected on every call, and buffers are never changed.
+  *
+  * @param mesh - Consistently oriented closed mesh with positive enclosed volume.
+  * @returns A fresh immutable XYZ volume centroid.
+  */
+ export declare function computeTriangleMeshCentroid(mesh: TriangleMesh): Vec3;
+
  /** One sampled component retaining contour identities and logical point correspondence. */
  export declare interface CorrespondingComponent {
      /** Stable canonical lowercase identity; unique within the containing topology or output. */
@@ -983,9 +994,10 @@ export declare interface ArcCurve3 {
      export declare function getMetricFastenerStandard(size: MetricFastenerSize): MetricFastenerStandard;
 
      /**
-      * Builds a closed indexed solid from a regularly sampled top, matched boundary walls, and flat base.
-      * Heights are evaluated once per grid point after allocation preflight. Physical XY sizes and all
-      * output coordinates must fit Float32 storage. Shared wall vertices prevent cracks at the base.
+      * Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base.
+      * Heights run once per grid point after preflight; center-error adds one evaluation per cell.
+      * Top winding is +Z, the base is -Z, and sides face outward. Coordinates and heights must fit
+      * Float32 storage. Explicit axes are captured before sampling; shared wall vertices prevent cracks.
       *
       * @example Sample a closed wavy mesh
       * ```ts
@@ -1000,23 +1012,58 @@ export declare interface ArcCurve3 {
      /** Trusted output ceilings for pure construction; omitted fields use engine defaults. */
      export declare type HeightfieldMeshLimits = Partial<Pick<ModelingLimits, "maxVertices" | "maxTriangles" | "maxBytes">>;
 
-     /** A regularly sampled, closed heightfield above a flat base, in millimetres. */
-     export declare interface HeightfieldOptions {
-         /** Positive XY footprint. */
-         readonly size: Vec2;
-         /** Exact positive integer X/Y interval counts. */
-         readonly segments: readonly [x: number, y: number];
+     /**
+      * A closed rectilinear heightfield above a flat base, with uniform or explicit XY samples in millimetres.
+      *
+      * Uniform sampling requires positive `size: [width, depth]` and positive integer `segments: [x, y]`.
+      * Optional `origin` sets the lower-left XY corner; omitting it centres the footprint on XY.
+      * Alternatively, supply `coordinates: { x, y }` with at least two strictly increasing finite
+      * absolute samples per axis, distinct in Float32. This infers the footprint and interval counts;
+      * `size`, `segments`, and `origin` cannot be combined with explicit coordinates.
+      */
+     export declare type HeightfieldOptions = {
          /** Absolute top Z at the supplied XY point. Every sample must be above baseZ. */
          readonly height: (point: Vec2) => number;
          /** Flat bottom Z. Defaults to zero. */
          readonly baseZ?: number;
+         /**
+          * Top-cell diagonal policy. Defaults to fixed (lower-left to upper-right).
+          * min-edge selects the shorter 3D diagonal; center-error selects the diagonal whose endpoint
+          * average is closest to one extra height sample at the physical cell centre. Ties use fixed.
+          * All policies retain two triangles per cell; neither estimates error elsewhere in the cell.
+          */
+         readonly triangulation?: "fixed" | "min-edge" | "center-error";
+     } & ({
+         /** Positive XY footprint for uniform sampling. */
+         readonly size: Vec2;
+         /** 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?: Vec2;
-     }
-
-     /** Predictable regular-grid allocation facts; this does not evaluate the height callback. */
+         /** Explicit coordinates cannot be combined with uniform sampling. */
+         readonly coordinates?: never;
+     } | {
+         /**
+          * Absolute XY coordinates, each with at least two strictly increasing finite values that
+          * remain distinct in Float32. Uneven spacing permits caller-owned local refinement.
+          */
+         readonly coordinates: {
+             /** Absolute X samples in ascending order. */
+             readonly x: readonly number[];
+             /** Absolute Y samples in ascending order. */
+             readonly y: readonly number[];
+         };
+         /** The footprint is inferred from explicit coordinates. */
+         readonly size?: never;
+         /** Interval counts are inferred from explicit coordinates. */
+         readonly segments?: never;
+         /** Explicit coordinates already include their origin. */
+         readonly origin?: never;
+     });
+
+     /** Predictable rectilinear-grid allocation facts; this does not evaluate the height callback. */
      export declare interface HeightfieldPreflight {
-         /** Number of grid points and height callback evaluations. */
+         /** Number of top grid points; center-error also evaluates one height per cell. */
          readonly sampleCount: number;
          /** Number of allocated XYZ vertices. */
          readonly vertexCount: number;
@@ -1591,7 +1638,7 @@ export declare interface ArcCurve3 {
           readonly closed?: boolean;
       }
 
-      /** Checks regular-grid dimensions and bounds allocation before evaluating any height samples. */
+      /** Checks grid dimensions, coordinate precision, and allocation bounds before evaluating heights. */
       export declare function preflightHeightfield(options: HeightfieldOptions, limits?: HeightfieldMeshLimits): HeightfieldPreflight;
 
       /**
@@ -2345,6 +2392,14 @@ export declare interface ArcCurve3 {
                readonly limits?: Partial<GeometrySamplingLimits>;
            }
 
+           /** Bounded floating-point intersection and shell-orientation validation settings. */
+           export declare interface SolidMeshValidationOptions {
+               /** Work ceiling for spatial comparisons and containment tests; defaults to 2,000,000 and may only lower it. */
+               readonly maximumTests?: number;
+               /** Distance comparison policy in millimetres; near contacts reject conservatively. */
+               readonly tolerance?: GeometryToleranceOptions;
+           }
+
            /**
             * Exactly one radius or diameter, placement, and tessellation for an origin-centered sphere.
             */
@@ -3044,6 +3099,22 @@ export declare interface ArcCurve3 {
                readonly outerRadius: number;
            }
 
+           /**
+            * Checks closed indexed topology, triangle intersections, and alternating nested shell orientation.
+            * Outward exterior shells and inward cavity shells are accepted. Separate shells must not touch,
+            * intersect, or overlap as material. Indexed neighbours may share their own vertex or edge.
+            *
+            * Uses bounded floating-point tests, not exact predicates or repair. Contacts within the selected
+            * tolerance reject conservatively. At most 200,000 triangles and 2,000,000 spatial/containment tests
+            * are supported; exhausting a ceiling throws COMPLEXITY_LIMIT rather than claiming validity.
+            * Input buffers are freshly inspected and never modified; units are millimetres.
+            *
+            * @param mesh - Closed triangle mesh to inspect.
+            * @param options - Optional lower work ceiling and numeric comparison policy.
+            * @returns The original mesh after every requested check succeeds.
+            */
+           export declare function validateSolidMesh(mesh: TriangleMesh, options?: SolidMeshValidationOptions): TriangleMesh;
+
            /**
             * Validates that a transform is finite, affine, and non-singular.
             *
@@ -3075,6 +3146,18 @@ export declare interface ArcCurve3 {
              /** A three-dimensional Cartesian vector or point. */
              export declare type Vec3 = readonly [x: number, y: number, z: number];
 
+             /** A circular baseline centered at the XY origin, with rigid shaped glyph groups. */
+             export declare interface VectorTextArcBaseline {
+                 /** Selects a circular baseline; glyph outlines rotate without bending or stretching. */
+                 readonly kind: "arc";
+                 /** Baseline radius in millimetres, greater than zero and at most 10000. */
+                 readonly radius: number;
+                 /** Alignment datum in degrees counterclockwise from +X; defaults to 90. */
+                 readonly centerAngleDegrees?: number;
+                 /** Reading direction around the circle; defaults to clockwise. */
+                 readonly direction?: "clockwise" | "counterclockwise";
+             }
+
              /** Exact curve bounds in millimetres; positive Y points upward. */
              export declare interface VectorTextBounds {
                  /** Minimum X and Y of visible outlines, including accents, descenders, and overhangs. */
@@ -3094,14 +3177,16 @@ export declare interface ArcCurve3 {
              }
 
              /**
-              * Horizontal multiline text, bounded to 512 UTF-16 units and 16 lines without wrapping.
+              * Text bounded to 512 UTF-16 units: horizontal lines or one circular line without wrapping.
               */
              export declare interface VectorTextLayoutOptions extends VectorTextOptions {
-                 /** Place each line's advance at the origin; defaults to left. Ink overhang is preserved. */
+                 /** Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left. */
                  readonly align?: "left" | "center" | "right";
+                 /** Omitted uses horizontal lines. Arcs require one line and baseline vertical alignment. */
+                 readonly baseline?: VectorTextArcBaseline;
                  /** Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics. */
                  readonly lineHeight?: number;
-                 /** Place the first baseline or the complete ink bounds at Y=0; defaults to baseline. */
+                 /** Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline. */
                  readonly verticalAlign?: "baseline" | "top" | "center" | "bottom";
              }
 
@@ -3109,9 +3194,9 @@ export declare interface ArcCurve3 {
              export declare interface VectorTextMetrics {
                  /** Visible curve bounds after alignment, or null when the text has no ink. */
                  readonly bounds: VectorTextBounds | null;
-                 /** Unaligned pen displacement: final line advance and negative baseline displacement, in mm. */
+                 /** Unaligned logical advance and negative baseline displacement in mm; arcs retain [arc length, 0]. */
                  readonly advance: readonly [number, number];
-                 /** Maximum line advance in millimetres, including spaces; distinct from visible ink width. */
+                 /** Maximum logical line advance in millimetres, including spaces; arc length on circular baselines. */
                  readonly logicalWidth: number;
                  /** Selected font's ascender distance above a baseline in millimetres, independent of the text. */
                  readonly ascent: number;