@metamesh/modeling 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @metamesh/modeling
 
+## 0.7.0
+
+### Patch Changes
+
+- b1b97b9: Reduce large-mesh finalization time and topology-analysis allocations without changing geometry, validation, or export output.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -4,7 +4,9 @@ Standalone geometry foundations and a modeling engine for Node applications, bro
 
 > **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the same minor line. Stable support requires an explicit `1.0.0` review.
 
-Applications initialize one engine and build models with imported functions. Generator hosts provide that same execution scope; generators do not initialize WASM or dispose native values. No SDK or Testkit is required to use Modeling.
+Applications initialize one engine and build models with imported functions. Generator hosts supply
+the same execution scope and own WASM initialization and native cleanup. Modeling requires no SDK
+or Testkit.
 
 ## API discovery and ownership
 
@@ -15,7 +17,10 @@ Applications initialize one engine and build models with imported functions. Gen
 | `@metamesh/modeling/engine`   | Host initialization, scoped modeling, finalization, resource limits, and snapshot export    |
 | `@metamesh/modeling/text`     | Optional font-byte preparation and synchronous vector layout                                |
 
-These four entrypoints are the complete workspace and published API. Pure helpers cannot import the engine, native kernel, browser APIs, Studio, or Generators. Fontkit and WOFF2 decoding remain optional peers used only by `/text`. Hosts own acquisition, worker lifecycle, and loading. API reports define supported symbols; consumer fixtures verify published use.
+These four entry points are the complete workspace and published API. Pure helpers cannot import
+the engine, native kernel, browser APIs, Studio, or Generators. Fontkit and WOFF2 decoding are optional
+peers used only by `/text`. Hosts own acquisition, worker lifecycle, and loading. API reports define
+supported symbols; consumer fixtures verify published use.
 
 ## Modeling and lifecycle
 
@@ -51,11 +56,36 @@ const engine = await createModelEngine({ locateFile: () => modelingWasmUrl });
 const snapshot = engine.build(() => box({ size: [10, 20, 30] }));
 ```
 
-Imported functions and explicitly supplied `ModelingContext` methods execute the same operations. Imports contain no kernel initialization. The host binds the active context through a versioned symbol shared across bundles, then clears it in `finally`. Calls outside `build` throw. Builds are synchronous and cannot nest, including across different engines in one JavaScript realm; asynchronous preparation belongs before `build`. Separate Workers have independent execution scopes. An engine also rejects builds or exports while its asynchronous exporter is busy.
-
-`Solid` and `Section` are opaque immutable handles belonging to one synchronous build. Sections are native filled XY shapes, including holes and disconnected components. `union`, `subtract`, and `intersect` accept either Solid or Section operands and reject mixed dimensions. Offsets and Boolean operations retain native sections; `fromRegion` and `toRegion` are explicit conversion boundaries. Repeated sweeps and loft stations extract each Section once per execution; `toRegion` returns fresh immutable snapshots. Handles cannot cross builds or survive disposal. All native values dispose in reverse construction order from `finally`, including on failure. Installed bundles call host-owned methods, avoiding package-local native class or module identity.
-
-Builds return a bare solid (part ID `model`) or named `{ id, solid, color? }` / `{ id, mesh, color? }` descriptors. IDs are unique lowercase kebab-case strings of at most 64 characters; colors are six-digit hex RGB. Direct meshes are copied and checked for finite, nondegenerate, oriented closed topology and kernel reconstructability without copying them back from the kernel. Native extraction preserves one bounded retry for collapsed Float32 stitches. Descriptors for the same Solid share one extraction, copied manufacturing buffers, and immutable facts. Public `toTriangleMesh` inspection returns independent copies; mutable mesh inputs are captured and validated afresh for every build. Finalized parts retain shared bounds, counts, signed volume, area, and topology facts. Render normals remain outside manufacturing data.
+Imported functions and `ModelingContext` methods execute the same operations. Imports do not
+initialize the kernel. The host binds the active context through a versioned symbol shared across
+bundles, then clears it in `finally`. Calls outside `build` throw.
+
+Builds are synchronous and cannot nest, including across engines in one JavaScript realm.
+Hosts finish asynchronous loading and service preparation before `build`; separate Workers have
+independent execution scopes.
+An engine rejects builds or exports while its asynchronous exporter is busy.
+
+`Solid` and `Section` are opaque immutable handles belonging to one synchronous build. Sections are
+native filled XY shapes, including holes and disconnected components. `union`, `subtract`, and
+`intersect` accept either Solid or Section operands and reject mixed dimensions. Offsets and Booleans
+retain native sections; `fromRegion` and `toRegion` are explicit conversion boundaries. Repeated
+sweeps and loft stations extract each Section once per execution; `toRegion` returns fresh immutable
+snapshots.
+
+Handles cannot cross builds or survive disposal. All native values dispose in reverse construction
+order from `finally`, including on failure. Installed bundles call host-owned methods, avoiding
+package-local native class or module identity.
+
+Builds return a bare solid (part ID `model`) or named `{ id, solid, color? }` / `{ id, mesh, color? }`
+descriptors. IDs are unique lowercase kebab-case strings of at most 64 characters; colors are
+six-digit hex RGB. Direct meshes are copied and checked for finite, nondegenerate, oriented closed
+topology and kernel reconstructability without copying them back from the kernel. Native extraction
+allows one bounded retry for collapsed Float32 stitches.
+
+Descriptors for the same Solid share one extraction, copied manufacturing buffers, and immutable
+facts. `toTriangleMesh` inspection returns independent copies; mutable mesh inputs are captured and
+validated afresh for every build. Finalized parts retain shared bounds, counts, signed volume, area,
+and topology facts. Render normals remain outside manufacturing data.
 
 Default limits are 64 parts, 1,000,000 vertices, 2,000,000 triangles, and 96 MiB of unique backing storage. Trusted applications may configure higher or lower ceilings through `createModelEngine({ limits })`. Per-build limits may only lower those configured ceilings, and snapshot export uses them too. Generator hosts own ceilings; generators receive no engine. Predictable allocations preflight safe-integer counts. Algorithm-specific numeric limits remain documented by their operations. Complexity fails explicitly instead of reducing fidelity.
 
@@ -74,7 +104,7 @@ work limits remain fixed operation safeguards.
 
 ## Resolution and conventions
 
-Primitive and pure loop factories share named options. These conventions apply across the applicable operations:
+Primitive and pure loop factories share named options and these conventions:
 
 | Concept       | Convention                                                                                                                                                                                                                            |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -143,26 +173,48 @@ Boolean and other geometry construction results require deliberate definitions r
 inheriting anchors that may no longer describe their surfaces. Custom rigid frames remain useful;
 pure `boxAnchor3` and `cylinderAnchor3` calculate dimension-based frames without a native shape.
 
-`GeometryResolution` defaults to 0.05 mm maximum chord error and 16–512 segments per complete circle. Precedence is exact local segments, operation resolution, context-derived resolution, then engine defaults. `model.withResolution(policy)` and imported `modelingFunctions(policy)` return a local method set for the same build. Destructure those methods to apply the local policy; other imported operations retain the original build policy. There is no global resolution or font state. Exact counts express deliberate faceting or fixed correspondence; adaptive curves retain physical deviation and edge-length constraints.
+`GeometryResolution` defaults to 0.05 mm maximum chord error and 16–512 segments per complete circle.
+Precedence is exact local segments, operation resolution, context-derived resolution, then engine
+defaults. Exact counts express deliberate faceting or fixed correspondence; adaptive curves retain
+physical deviation and edge-length constraints.
+
+`model.withResolution(policy)` and imported `modelingFunctions(policy)` return a local method set
+for the same build. Destructure those methods to apply the local policy; other imports retain the
+original build policy. There is no global resolution or font state.
 
 Revolution `segments` describes a complete circle; partial revolutions scale that count to the
 angular span and round up. Native filled revolutions need at least three intervals: adaptive
 sampling refines to that minimum, while exact counts below it fail explicitly. Pure `revolveMesh`
 supports one interval.
 
-`resamplePolyline2` and `resamplePolyline3` share physical sampling options and return immutable points with directed unit tangents. Open paths retain both endpoints; `closed: true` includes the closing edge and omits a repeated seam vertex. Exact closed counts require at least three segments. `regularPolygonLoop({ radius, sides, rotationDegrees, sizing })` creates a centered CCW point loop with an implicit seam. Shared `RadialSizing` is `"vertex"` by default or `"face"` to compensate polygon faceting so the requested radius reaches the faces; `CylinderOptions` owns that same sizing option.
+`resamplePolyline2` and `resamplePolyline3` share physical sampling options and return immutable
+points with directed unit tangents. Open paths retain both endpoints; `closed: true` includes the
+closing edge and omits a repeated seam vertex. Exact closed counts require at least three segments.
+
+`regularPolygonLoop({ radius, sides, rotationDegrees, sizing })` creates a centered CCW point loop
+with an implicit seam. `RadialSizing` defaults to `"vertex"`; `"face"` compensates polygon faceting
+so the requested radius reaches the faces. `CylinderOptions` uses the same sizing option.
 
 `normalizeLoop2`, `normalizePolygon2`, and `normalizeRegion2` return immutable geometry and may reuse internally validated results. External objects are validated even when frozen. Mutable mesh buffers are analyzed freshly at external boundaries; engine facts are reused inside their owner.
 
 ## Profiles and mechanical construction
 
-`sampleOpenProfile` samples upward radius/height line and cubic chains. Consumers own closure and product constraints. Point factories such as `circleLoop` and `rectangleLoop` return ordered loops; `Profile` owns identified components, contours and landmarks, and `CorrespondingProfile` retains their shared sampled slots. `rectangle`, `rectangleLoop` and `rectangleProfile` share `size`, `center` and `treatment` options. Use the root primitive for ordinary modeling; pure loop/profile construction serves custom data and explicit correspondence. Native filled sections do not promise stable vertex ordering.
+`sampleOpenProfile` samples upward radius/height line and cubic chains. Consumers own closure and
+product constraints. `circleLoop`, `rectangleLoop`, and other point factories return ordered loops.
+`Profile` owns identified components, contours, and landmarks; `CorrespondingProfile` retains their
+shared sampled slots.
+
+`rectangle`, `rectangleLoop`, and `rectangleProfile` share `size`, `center`, and `treatment` options.
+Use root primitives for ordinary modeling and pure loops/profiles for custom data and explicit
+correspondence. Native filled sections do not promise stable vertex ordering.
 
 For a closed planar XYZ path, map the canonical loop with
 `rectangleLoop(options).map(([x, y]) => [x, y, 0] as const)`. Before sampling, cap its
 `limits.maxProfilePoints` at the smaller selected profile and path point ceilings. This keeps
 path allocation bounded and preserves all corner tangent endpoints and the implicit seam.
 
+### Extrusion and sweep
+
 `extrude(shape, { height, ... })`, `revolve(shape, options)` and `sweep(shape, path, options)` accept a filled Section or CorrespondingProfile, including holes and disconnected components. Open sweeps have watertight end caps; `closed: true` joins the path back to its beginning. Sweep options share degree twist, positive uniform or XY scale, and an XY scale pair per normalized path station. Closed scales interpolate along the implicit closing edge. A rotational symmetry seam uses `seamProfileOffset`, a counterclockwise logical point advance that reverses for clockwise hole contours; every contour must geometrically match the total twist. Incompatible seams fail explicitly.
 
 Adaptive extrusion sampling bounds the entire side triangles, including the interaction between
@@ -194,6 +246,8 @@ policies. For a planar closed path whose profile X should stay vertical, request
 `orientation: { kind: "transport", initialNormal: [0, 0, 1] }`. Closed policies use cyclic tangents
 and the same first frame on their closing gap.
 
+### Loft correspondence
+
 `loft(stations, options)` accepts a `profile` and exactly one horizontal `z` height or explicit
 right-handed `frame` per station. Stations stay in input order. Ordinary primitives keep the
 simple case at the root entry point:
@@ -213,7 +267,7 @@ With omitted `correspondence`, compatible rectangle stations, circle/ellipse rin
 regular polygons and equal-pointed stars use their retained authored landmarks. Rectangle corners
 can change among square, round and chamfer treatments, including collapsed or saturated rounds.
 Circle/ellipse and rectangle stations also share those quadrant/corner landmarks: a circular
-inlet becomes a rounded rectangle directly, without an authored saturated-square workaround.
+inlet can become a rounded rectangle directly.
 Exact circular counts for this mixed family must divide by four; other deliberately faceted counts
 need an explicit geometric method. Adaptive counts align upward within the selected ceilings.
 XY affine transforms preserve these identities; this semantic path requires consistent handedness.
@@ -250,6 +304,13 @@ then next-only advances. Its objective sums connection lengths with the closing
 No tangent/supporting-plane association is exposed: general concave and spatial stations do not
 provide the convexity contract that such a method needs.
 
+Identified `ProfileSpan2` supports lines, arcs, and cubic Béziers with `start`, `control1`, `control2`,
+and `end`. Cubics reuse the curve evaluator and physical subdivision policy, selecting one uniform
+parameter grid for corresponding spans. Fully collapsed spans retain logical slots without moving
+endpoints. Sampled contours and components use `CorrespondingContour` and `CorrespondingComponent`.
+Pass the complete family to `matchProfiles` with optional `limits.maxProfilePoints`; its default is
+100,000 points per profile, while a separate one-million-slot family work bound remains in force.
+
 For precise custom correspondence, prepare `matchProfiles` over explicit `Profile` specifications.
 It chooses the maximum physical interval count for each paired span across the family, including
 span-local `resolution`; identified line, arc and cubic kinds may change while IDs, order and
@@ -265,6 +326,8 @@ and the complete grid at one million logical slots. Simple-loop cap triangulatio
 eight-million-comparison work ceiling. Complexity rejects instead of reducing fidelity
 or substituting another method. Pure counterparts also include `sweepMesh`, `extrudeMesh` and `revolveMesh`.
 
+### Patterns and bounded surfaces
+
 `linearPattern(shape, { count, length })` determines equal intervals from exactly two of `count`,
 signed `spacing`, and signed total `length`; its direction defaults to +X. Length and spacing must
 fit a whole interval count. `gridPattern(shape, { count: [3, 2], spacing: [10, 8] })` supports XY
@@ -279,13 +342,6 @@ 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.
 
-Identified `ProfileSpan2` supports lines, arcs, and cubic Béziers with `start`, `control1`, `control2`,
-and `end`. Cubics reuse the curve evaluator and physical subdivision policy, selecting one uniform
-parameter grid for corresponding spans. Fully collapsed spans retain logical slots without moving
-endpoints. Sampled contours and components use `CorrespondingContour` and `CorrespondingComponent`.
-Pass the complete family to `matchProfiles` with optional `limits.maxProfilePoints`; its default is
-100,000 points per profile, while a separate one-million-slot family work bound remains in force.
-
 `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.
 
 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.
@@ -304,7 +360,13 @@ 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.
 
-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. Models above 200,000 triangles skip optimization; unsupported or failed candidates preserve their original part. Equal shared mesh views reuse one optimized candidate. The selected buffers must still fit all execution ceilings; optimization that would exceed them preserves the original model. This is local connectivity cleanup, not general remeshing. Source buffers never change in place.
+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.
+
+Models above 200,000 triangles skip optimization. Unsupported or failed candidates retain their
+original part, as do models whose optimized buffers would exceed an execution ceiling. Equal shared
+mesh views reuse one optimized candidate.
 
 ## Quality gates
 

package/dist/api/engine.d.ts

@@ -13,7 +13,9 @@ export interface BuildOptions {
     /** Optional bounded planar cleanup; unsupported candidates preserve the original part. */
     readonly meshTopologyMode?: "original" | "optimized";
 }
-/** Host engine. No native values or manually disposable handles are exposed. */
+/**
+ * Host engine. No native values or manually disposable handles are exposed.
+ */
 export interface ModelEngine {
     /** Immutable resource ceilings selected when this engine was initialized. */
     readonly limits: ModelingLimits;
@@ -22,14 +24,18 @@ export interface ModelEngine {
     /** Serializes already finalized mesh parts; never prepares or builds a generator again. */
     export3mf(parts: readonly ExportMeshPart[], options?: Export3mfOptions): Promise<ArrayBuffer>;
 }
-/** Manufacturing buffers accepted by the snapshot exporter. */
+/**
+ * Manufacturing buffers accepted by the snapshot exporter.
+ */
 export interface ExportMeshPart extends TriangleMesh {
     /** Stable canonical lowercase identity; unique within the containing topology or output. */
     readonly id: string;
     /** Optional six-digit hex RGB display color. */
     readonly color?: string;
 }
-/** Completed-snapshot serialization settings; filename selection belongs to the host. */
+/**
+ * Completed-snapshot serialization settings; filename selection belongs to the host.
+ */
 export interface Export3mfOptions {
     /** Document display name; defaults to MetaMesh model. */
     readonly name?: string;
@@ -49,6 +55,17 @@ export { defaultModelingLimits };
 /** URL of the package's pinned WASM asset; browser bundlers may replace it with their emitted URL. */
 export declare const modelingWasmUrl: string;
 
-/** Initializes one host kernel and returns a lifecycle-safe engine. No generator initializes WASM. */
+/**
+ * Initializes one host kernel and returns a lifecycle-safe engine. No generator initializes WASM.
+ *
+ * @example Build a box in a host application
+ * ```ts
+ * import { box } from "@metamesh/modeling";
+ * import { createModelEngine } from "@metamesh/modeling/engine";
+ *
+ * const engine = await createModelEngine();
+ * const snapshot = engine.build(() => box({ size: [30, 20, 8] }));
+ * ```
+ */
 export declare function createModelEngine(options?: ModelEngineOptions): Promise<ModelEngine>;
 export type { BuildOutput, FinalizedModel, FinalizedPart, ModelingContext, ModelingLimits, GeometryResolution, GeometrySamplingLimits, };