@metamesh/cli 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,206 @@
 # @metamesh/cli
 
+## 0.19.0
+
+### Minor Changes
+
+- c9de510: Extend straight extrusion end finishing to concave outlines, holes, and disconnected regions.
+  Add independent-solid `join` with a feature datum and a smooth (default) or straight width/height
+  transition against validated planar, angled, and curved sampled support patches. Both profiles use
+  the same support, collar, and whole-volume containment proofs.
+
+  Breaking: compiled Generators require Modeling runtime major 12. Rebuild packages for the new
+  host contract; old compiled runtimes are rejected. Joining preserves the supplied operands and
+  does not promise a circular fillet radius or perform automatic placement.
+
+  Replace named lazy `computed` readers with eager `memo(fn, ...args)` values. Stable pure helpers
+  reuse immutable arguments and tracked current params/context reads, with bounded recent histories
+  and native geometry retention. Update Studio diagnostics to warn about fresh function identities.
+  All authored and compiled callers must use the new API; there is no compatibility surface.
+
+- de3d234: Add runtime-neutral STL, 3MF, and GLB export under `@metamesh/modeling/export`, with isolated
+  format entry points and backpressure-aware streaming writers. All formats consume captured local
+  geometry, placement, and appearance, with independent limits, cancellation, and structured
+  information-loss diagnostics. Standard 3MF color groups carry appearance, while base materials
+  and multiproperties retain explicit material identities independently of RGB values. These
+  properties do not assign slicer filaments or physical device trays. Add `mesh.render()` for
+  shared crease-aware display buffers that preserve exact triangle coordinates.
+
+  Breaking: remove `export3mf` and export types from `/engine`, remove SDK export request protocols
+  and `toWorldMeshes`, and return owned `Uint8Array` bytes with format metadata from the shared
+  exporters. Studio uses one export worker for every format. CLI captures use format version 3;
+  replace `run --export-3mf` with `metamesh export RUN_DIRECTORY --format 3mf --output model.3mf`.
+  Captured-run export also supports STL and GLB without rerunning source. No legacy export paths
+  or capture readers are retained.
+
+### Patch Changes
+
+- Updated dependencies [c9de510]
+- Updated dependencies [de3d234]
+  - @metamesh/modeling@0.19.0
+  - @metamesh/generator-sdk@0.19.0
+  - @metamesh/testkit@0.19.0
+
+## 0.18.0
+
+### Minor Changes
+
+- 2eea694: Consolidate model authoring, execution, and testing around fluent shapes and durable immutable
+  results. Upgrade all four packages together; these Preview API changes have no compatibility
+  aliases. Rebuild compiled Generators for module format 5 and Modeling runtime major 11. Older
+  module formats and incompatible runtime versions are rejected before execution.
+
+  ### Modeling imports and operations
+
+  | Previous API                                                                                            | 0.18 API                                                                                                  |
+  | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+  | `body.subtract([cutter])` for a single operand                                                          | `body.subtract(cutter)`; fluent `union`, `intersect`, and `subtract` accept one shape or a readonly array |
+  | `compose(shapes)`                                                                                       | `union(shapes)`                                                                                           |
+  | Free shape inspection, emptiness, component, and anchor queries                                         | `shape.inspect()`, `shape.isEmpty()`, `shape.components()`, and `shape.anchor(name)`                      |
+  | Free Solid distance/segment queries and splitting functions                                             | `solid.distance(other)`, `solid.castSegment(...)`, `solid.split(cutter)`, and `solid.splitByPlane(plane)` |
+  | `solid.toTriangleMesh()`                                                                                | `solid.toMesh()`                                                                                          |
+  | Named `mesh` import from `/geometry`, or standalone triangle-mesh functions                             | `import * as mesh from "@metamesh/modeling/geometry/mesh"`                                                |
+  | Standalone `immutableMesh(...)`                                                                         | `mesh.immutable(...)`                                                                                     |
+  | `helicalThreadRidgeMesh`, `helicalThreadSolidMesh`, and `preflightHelicalThreadSolidMesh`               | `mesh.threadRidge`, `mesh.threadSolid`, and `mesh.preflightThreadSolid`                                   |
+  | `HelicalThreadRidgeMeshOptions`, `HelicalThreadSolidMeshOptions`, and `HelicalThreadSolidMeshPreflight` | `ThreadRidgeOptions`, `ThreadSolidOptions`, and `ThreadSolidPreflight`, exported from the mesh module     |
+  | Mesh `connectedComponentCount`                                                                          | `shellCount`; native inspection `componentCount` still counts material components                         |
+  | Inspection extrema on the inspection result                                                             | Immutable `inspection.bounds.min` and `inspection.bounds.max`                                             |
+  | `starContour(outerRadius, points, innerRadius, limits)`                                                 | `starContour({ outerRadius, innerRadius, points, limits })`                                               |
+
+  Free `union(shapes)` and `intersect(shapes)` remain for collections of peers and reject empty
+  collections. Fluent Boolean methods with an empty array return the receiver.
+
+  Use `section.extrude(options)` in fluent modeling, `extrude(profile, options)` for generic
+  `Section | CorrespondingProfile` inputs, and `mesh.extrude(contour, options)` for pure triangle
+  buffers. The same fluent/generic distinction applies to revolution and sweeping. Pure extrusion
+  uses `ExtrudeMeshOptions` and rejects `ends`; use Section extrusion for native end treatments.
+  Construction, transforms, and splitting remain deferred recipes; observations and `toMesh()`
+  require active model execution.
+
+  Point-loop and arbitrary Section lofts default to direct correspondence when the method is
+  omitted; known primitive landmarks remain preserved. Dimension inputs accept fluent vectors.
+  Tube sizing accepts complete inner/outer radius or diameter pairs. Both star factories require
+  an explicit inner radius and support degree rotation; use `innerRadius: outerRadius / 2` to retain
+  the contour helper's former default.
+
+  Rod and internal-cutter `bevelBottom`, `bevelTop`, and `bevelSize` become `bevel`. The shared
+  `Bevel` contract accepts a nonnegative size, `"auto"`, or a readonly `[bottom, top]` pair; zero
+  disables an end and omission preserves factory defaults. Complete-thread mesh builders use the
+  same contract, with thread termination under `ends`. Nuts replace bevel selection, `chamferSize`,
+  and `flushBuildPlateBottom` with independent `innerBevel` and `outerBevel`. For a flat outside
+  bottom that retains its inner opening bevel, use `outerBevel: [0, "auto"]`. Nut preflight exposes
+  resolved inner/outer pairs and checks face walls pairwise; each end's reservation and automatic
+  sizing are resolved independently, including internal-cutter axial extension.
+
+  Primitive contours and their points are immutable and can be explicit `computed` dependencies.
+  Copy the outer array and any points before editing. Geometry errors are available from the
+  Modeling root; operation option/result types are exported beside their owning operations.
+  Topology analysis with `includeTopology: true`, finalized parts, and local geometry resources
+  include required `shellCount` and `edgeCount`. Bounds construction options describe inputs only;
+  existing fluent bounds remain accepted.
+
+  ### Part placement and result ownership
+
+  Replace `part(id, { geometry, position, rotation })` with
+  `part(id, { geometry, transform })`. The optional transform accepts a fluent `transform3()` value,
+  a row-major 16-number matrix, or a computed reader; omission means identity. Pattern and
+  attachment matrices pass directly to `part()`. Only rigid placement is supported: scale, shear,
+  reflection, perspective, and non-finite values are rejected. Geometry-only and geometry-or-options
+  union inputs remain accepted without casts.
+
+  Use `PartDeclaration` for authored parts. Replace `ModelSnapshot` / `FinalizedModel` with
+  `ModelResult`, and `SnapshotPart` / `FinalizedPart` with `ModelPart`. `engine.run()`, `session.run()`,
+  and Testkit's `runModel()` return durable immutable results. Dispose sessions and runners to release their
+  caches; completed results remain valid and need no disposal. `model.part(id)` returns a required
+  semantic part or throws with available IDs; `model.parts` preserves output order.
+
+  Finalized buffers expose stable, iterable `ImmutableBuffer` values. Use `.copy()` for mutable
+  storage. A `ModelPart`'s top-level positions and indices are already in world space; apply its
+  immutable `transform` only to the reusable local buffers under `geometry`. Worker deliveries also
+  nest local resources under `geometry`. Host integrations use `ModelDeliveryEncoder`,
+  `PartDeliveryDecoder`, and `toWorldMeshes` for owned transfer and manufacturing output.
+  Replace `engine.export3mf(...)` with standalone `export3mf(parts, options)` from `/engine`, which
+  accepts completed meshes with explicit resource limits, independently of engine initialization.
+
+  Statistics rename `volumeMm3` → `signedVolume`, `finalizationMs` → `finalizeMs`, and
+  `generationMs` → `generateMs`; `buildMs` measures declarations.
+  `ModelResult.stats.byteCount` means bytes occupied by finalized world-space position and index buffers,
+  counting shared buffers once. Worker statistics preserve engine `generateMs`; host elapsed time
+  is `timings.totalMs`, with `paramsMs` for parameter work. Other host timing stages are optional:
+  an omitted stage is unmeasured.
+
+  Model parameter roots must be object maps. Captured parameters and computed results expose
+  deeply readonly `ImmutableValue<T>` views; supported mutable caller input is still accepted and
+  recaptured on every revision, including mutable children inside frozen objects. Deeply immutable
+  data retains identity reuse. Assertions and warnings accept bounded immutable nested `path`
+  metadata. Replace `validateModel` with `checkModel` and session/runner `.validate()` with `.check()`.
+  These check declarations and reached assertions without finalizing geometry; unexpected execution
+  failures still throw.
+
+  ### Generator SDK and Testkit
+
+  | Previous API                                                               | 0.18 API                                                                                                                |
+  | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+  | Nested compiled Generator module                                           | Flat format-5 model program; bind an existing program with `defineGeneratorModule({ definition, program })`             |
+  | `isGeneratorModule(value)`                                                 | `parseGeneratorModule(value, definition)`                                                                               |
+  | `executeGenerator({ ..., parsedParameters })`                              | `executeGenerator({ ..., parameters })`; current-definition validation always runs                                      |
+  | Callback-scoped `withModel`, `ModelTestOptions`, or `runner.withModel`     | `await runModel(programOrCallback, ...)` for one-off results; explicit sessions or Generator runners for repeated edits |
+  | Generator test `runner.execute(...)`                                       | `runner.run(...)`, returning `GeneratorTestResult`                                                                      |
+  | `expectSerializableDefinition`                                             | `assertValidDefinition`                                                                                                 |
+  | `expectValidDefaults`, `expectValidPresets`, and `expectValidParts`        | `assertValidDefaults`, `assertValidPresets`, and `assertValidParts`                                                     |
+  | `expectMeshMeasurements`                                                   | `assertMeshMeasurements`                                                                                                |
+  | `canonicalizeParameters(definition, parameters)` from `/parameters`        | `canonicalizeParameters(parameters)` from `/runtime`                                                                    |
+  | `GeneratedPartsDecoder`, `parseGeneratedParts`, and `GeneratedPartsLimits` | `PartDeliveryDecoder`, `parseModelParts`, and `PartDeliveryLimits`                                                      |
+  | `GeneratedPart` and `GeneratedModel`                                       | `ModelPartData` and `ModelData`                                                                                         |
+  | `GeneratedPartDelivery` and `GeneratedModelDelivery`                       | `PartDelivery` and `ModelDelivery`                                                                                      |
+
+  Testkit `runModel` accepts existing `ModelProgram` values and synchronous inline callbacks;
+  typed callbacks use `runModel<Parameters, Services>`. Its definition-bound Generator overload
+  validates inputs and prepares services. The SDK Modeling adapter adds definition-inferred
+  `GeneratorModel` and `parseGeneratorModel`. Ordinary model tests preserve definition-inferred
+  input types. Reusable Generator runners accept physical generation policy plus `cache` and
+  `verifyCache` for edit sequences; dispose the runner after use.
+
+  Generator execution and ordinary tests strictly require complete canonical parameter maps.
+  Use the parameter codec for strict input and `normalizeParameters` for forgiving recovery;
+  replace `prepareParameters`, `validateParameters`, and `PreparedParameters` with
+  `createParamCodec(definition).parse(...)` or `.safeParse(...)`. Schema adapters remain private.
+  Codec failures provide structured issues without a substitute parameter map. For deliberate
+  malformed-input assertion probes, replace `runner.validate(parameters, { normalize: false })`
+  with `runner.check(parameters, { validateInput: false })`.
+  Defaults are selected only by omission or `undefined` where supported; a `null` parameter map is
+  rejected. Parameterless model calls can omit the empty map. Definition and preset helpers catch
+  nested key typos and validate immediately while retaining literal inference.
+
+  `assertValidParts` checks the supplied world-space buffers, closed topology, and exact agreement
+  with local geometry under `transform`; it no longer hides corrupted output by reconstructing it.
+  Always await `assertValidParts(parts, engine)` (or omit the engine): failures reject, and supplying
+  an engine changes resource reuse only.
+  `assertValidDefinition` also checks the canonical JSON round trip. New `assertEqualBuffer` and
+  `assertEqualMesh` compare exact ordered contents without copying; equivalent shapes with different
+  triangulations can differ. `ContentMismatchError` identifies the first differing element or
+  length, while malformed input and reader failures retain their errors. Optional `contentMatchers`
+  support `expect.extend`, including negation, without a test-framework dependency.
+
+  ### CLI and package requirements
+
+  Rename the type-only CLI command `metamesh check` to `metamesh typecheck`; no alias is retained.
+  Node authoring APIs and Modeling/Testkit declaration-check methods retain their names. Generator
+  runs use `overrides` / `--overrides`, merged with defaults before strict parsing; standalone models
+  use `params` / `--params`. Supplying the other entry kind's input option is rejected.
+
+  Captured runs use format 2 with transform-only placement. The bundled capture renderer resolves
+  from the installed CLI package so published installations can render captures.
+  Public packages require Node.js 24 or newer, ESM imports, and TypeScript 6.0 or newer with strict
+  checking for TypeScript consumers.
+
+### Patch Changes
+
+- Updated dependencies [2eea694]
+  - @metamesh/modeling@0.18.0
+  - @metamesh/generator-sdk@0.18.0
+  - @metamesh/testkit@0.18.0
+
 ## 0.17.0
 
 ### Patch Changes

package/README.md

@@ -1,71 +1,107 @@
 # `@metamesh/cli`
 
-Check, execute, inspect, and render trusted local MetaMesh source. The `metamesh` executable and
-Node-only `/authoring` functions use the production engine and version-matched installed documentation.
+Check and run MetaMesh models from your terminal. Save generated geometry, inspect its dimensions,
+and render previews from the same result. The `metamesh` command also reads documentation for
+your installed packages, and its tools are available through a Node.js API.
 
 > **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
 > same minor line.
 
 ## Installation
 
-Install the same exact release of each MetaMesh package in the project where you author models:
+Install matching Modeling and CLI releases in your authoring project:
 
 ```bash
 pnpm add @metamesh/modeling
 pnpm add -D @metamesh/cli
 ```
 
-Add `@metamesh/generator-sdk` when your source defines Generators. Add `@metamesh/testkit` as a
-development dependency when importing testing helpers. CLI internally reuses Testkit font fixtures
-and its SDK contracts; neither package needs to be directly declared for standalone model authoring.
-The compiler, bundler, Three renderer, and Playwright belong to CLI; Testkit does not install them.
-Chromium is installed separately and never downloaded by checking or generation.
+The executable and Node API require Node.js 24 or newer. The API publishes ES modules only.
+TypeScript source and API consumers need TypeScript 6.0 or newer with `strict` checking and
+`NodeNext` or `Bundler` module resolution. The CLI includes its source-checking compiler.
+
+Add the [Generator SDK](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/README.md)
+to author Generators, or [Testkit](https://github.com/JasonKoolman/metamesh/blob/main/packages/testkit/README.md)
+to import testing helpers directly. Standalone models need neither as a direct dependency.
+Only rendering needs Chromium; checking, generation, and inspection work without a browser.
 
 ## Local workflow
 
+Save this plate with a through hole as `model.ts`:
+
+```ts
+import { box, cylinder, generate } from "@metamesh/modeling";
+
+export default generate(({ part }) => {
+  const plate = box({ size: [30, 20, 6] });
+  const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
+  return part("plate", plate.subtract(bore));
+});
+```
+
+From the same project, discover the installed packages, check the source, and capture a run:
+
 ```bash
 pnpm exec metamesh environment --json
+pnpm exec metamesh docs search "sweep"
 pnpm exec metamesh docs show modeling/guide/concepts
-pnpm exec metamesh docs search "extrude"
-pnpm exec metamesh docs show TOPIC_ID
-pnpm exec metamesh check model.ts --kind model
+pnpm exec metamesh typecheck model.ts --kind model
 pnpm exec metamesh run model.ts --kind model
 pnpm exec metamesh inspect RUN_DIRECTORY
+pnpm exec metamesh export RUN_DIRECTORY --format 3mf --output plate.3mf
+```
+
+Replace `RUN_DIRECTORY` with the path reported by `run`. Export that capture as 3MF, STL, or GLB.
+Commands resolve packages and paths from the current project; use `--project PATH`
+to select another. `environment` reports package versions, local documentation, and the supported
+authoring protocol. Version mismatches fail before generation.
+
+Local model entries default-export a `ModelProgram` created with Modeling's `generate` helper.
+For Generators, use `--kind generator` with a named `definition` export and a default Generator
+module. Local entries import from the installed packages; Studio's virtual `@metamesh/project`
+module is unavailable here.
+
+Use `--params values.json` for a standalone model's complete input map, or
+`--overrides values.json` for a Generator. Generator overrides merge with defaults and undergo
+strict validation. Standalone model parameters pass through directly. The Node API uses the
+matching `params` and `overrides` fields, selected by `kind`.
+
+## Authoring tools
+
+| Command                     | Purpose                                                                    |
+| --------------------------- | -------------------------------------------------------------------------- |
+| `environment`               | Discover project-local packages, capabilities, and documentation.          |
+| `docs search` / `docs show` | Find and read exact-version guides and API references offline.             |
+| `typecheck`                 | Check TypeScript and entry-point export types without executing the model. |
+| `run`                       | Check and execute source, then capture geometry and diagnostics.           |
+| `export`                    | Save a capture as STL, 3MF, or GLB.                                        |
+| `inspect`                   | Read captured parts, bounds, measurements, and diagnostics.                |
+| `render`                    | Create standard views from a capture.                                      |
+| `setup`                     | Print skill installation and project-instruction guidance.                 |
+
+`run` executes source in a disposable child process with a 30-second default deadline and saves
+attempts under `.metamesh/runs`. Each capture records the source identity, effective parameters,
+and geometry hashes. `inspect`, `export`, and `render` validate the saved buffers and read that same result
+without rerunning the source.
+
+Source runs with your account's permissions. The child process is not a security sandbox; run
+source you trust. Use `--json` for structured stdout; author logs are bounded and sent to stderr.
+Exit codes are 0 for success, 1 for source or generation failure, and 2 for invocation, environment,
+artifact, or tooling failure. Each command's `--help` lists its options and limits.
+
+## Render a capture
+
+Install the CLI's pinned Chromium version, then choose views of the captured model:
+
+```bash
 pnpm exec metamesh browser install
 pnpm exec metamesh render RUN_DIRECTORY --views isometric,front,top,right
 ```
 
-`environment` reports `authoringProtocolVersion: 1`, installed package versions, capabilities,
-and documentation manifest paths. Mixed package versions or stale documentation fail before
-generation. Commands resolve packages and relative paths from the current project; pass
-`--project PATH` to select another project explicitly. `TOPIC_ID` comes from documentation search;
-`RUN_DIRECTORY` comes from a successful run.
-
-The concepts guide starts with a compact construction map. Search matches distinct words in
-titles, guide headings, keywords, and summaries. Exact titles, topic IDs, and import paths take
-priority; equally complete intent matches favor guides over reference entries.
-
-`run` includes semantic TypeScript checking and executes in a disposable child process with a
-30-second default deadline. It saves each attempt beneath `.metamesh/runs` with source identity,
-parameters, diagnostics, measurements, and hashed geometry buffers. `inspect` and `render` validate
-those captured buffers without importing the original source. Use `--json` for one structured stdout
-result; bounded author logs go to stderr. Exit codes are 0 for success, 1 for source or generation
-failure, and 2 for invocation, environment, artifact, or tooling failure. This executes trusted local
-code and is not a security sandbox.
-
-For Generators, use `--kind generator`. Entries named-export `definition` and default-export the
-Generator module envelope. Defaults merge with `--params parameters.json`, then strict validation
-rejects unknown or invalid overrides. Standalone model entries default-export a `ModelProgram` and
-receive no injected services. Both support normal local imports and installed dependencies; Studio's
-virtual `@metamesh/project` module is unavailable.
-
-Use `--help` on each command for parameters, fonts, resource limits, export, and image options.
-`metamesh setup` prints installation guidance for `metamesh-developer` from the canonical
-`metamesh-studio/metamesh-skills` repository and a project-instruction suggestion without modifying
-files. Its printed GitHub installation command becomes usable when that repository is published;
-the skill supplies the workflow, while installed package documentation supplies exact API facts.
-
-## Programmatic API and documentation
+Rendering supports PNG and lossless WebP, transparent backgrounds, and standard orthographic views.
+Checking and generation never download a browser.
+
+## Node API and agent workflows
 
 ```ts
 import { inspectCapturedRun, runAuthoringSource } from "@metamesh/cli/authoring";
@@ -76,16 +112,22 @@ if (result.success) {
 }
 ```
 
-Resolve `@metamesh/cli/docs/manifest.json` for the installed Markdown reference, or run
-`pnpm exec metamesh docs show cli/guide/agent-authoring` for the complete authoring workflow.
-The [authoring guide source](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/agent-authoring.mdx)
-also covers local font fixtures, artifacts, rendering, and agent integration. Until the public
-documentation site launches, use installed documentation, repository sources, or
-[run the docs locally](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/README.md#local-use).
+`@metamesh/cli/authoring` also exposes environment discovery, documentation lookup, source checking,
+export, and rendering.
+
+For coding agents, `metamesh setup` prints skill installation and project-instruction guidance
+without changing files. The portable `metamesh-developer` skill describes the authoring workflow
+and uses installed package documentation for API details.
+Install a reviewed skill snapshot from the canonical `metamesh-studio/metamesh-skills` repository
+or its local checkout when public installation is unavailable.
+
+## Documentation
 
-The reusable authoring functions and command implementation stay in this package; geometry and
-Generator contracts retain their existing owners. Testing assertions and font-fixture adapters
-remain in Testkit.
+Resolve `@metamesh/cli/docs/manifest.json` for exact-version Markdown guidance and API references,
+or run `pnpm exec metamesh docs show cli/guide/agent-authoring`. The
+[authoring guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/agent-authoring.mdx)
+covers entry contracts, parameters, fonts, captures, and rendering. See
+[Contributing](https://github.com/JasonKoolman/metamesh/blob/main/CONTRIBUTING.md) for package development.
 
 ## License
 

package/dist/authoring/artifacts.d.ts

@@ -1,8 +1,8 @@
-import type { ModelSnapshot } from "@metamesh/modeling/engine";
+import { type ModelResult } from "@metamesh/modeling/engine";
 import type { CapturedPart, CapturedRun, CapturedRunManifest } from "./types.js";
 export declare function sha256(value: Uint8Array | string): string;
 export declare function writeAtomicJson(file: string, value: unknown): Promise<void>;
-export declare function captureSnapshot(directory: string, snapshot: ModelSnapshot, metadata: Omit<CapturedRunManifest, "resources" | "parts" | "bounds" | "stats" | "diagnostics" | "dependencies" | "export3mf">, export3mf?: ArrayBuffer): Promise<CapturedRunManifest>;
+export declare function captureSnapshot(directory: string, snapshot: ModelResult, metadata: Omit<CapturedRunManifest, "resources" | "parts" | "bounds" | "stats" | "diagnostics" | "dependencies">): Promise<CapturedRunManifest>;
 /** Reads only immutable captured files. It never imports or executes original author source. */
 export declare function readCapturedRun(directory: string): Promise<CapturedRun>;
 /**

package/dist/authoring/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/authoring/artifacts.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAa/D,OAAO,KAAK,EAGV,YAAY,EAEZ,WAAW,EACX,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAIjF;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,IAAI,CACZ,mBAAmB,EACnB,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,GAAG,cAAc,GAAG,WAAW,CAC1F,EACD,SAAS,CAAC,EAAE,WAAW,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAqD9B;AAiQD,gGAAgG;AAChG,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAsF7E;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC,CAWpF"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/authoring/artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAYnC,OAAO,KAAK,EAGV,YAAY,EAEZ,WAAW,EACX,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAIjF;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,WAAW,EACrB,QAAQ,EAAE,IAAI,CACZ,mBAAmB,EACnB,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,GAAG,cAAc,CAC5E,GACA,OAAO,CAAC,mBAAmB,CAAC,CAsD9B;AAyQD,gGAAgG;AAChG,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA+E7E;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC,CAWpF"}

package/dist/authoring/artifacts.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { defaultModelingLimits } from "@metamesh/modeling/engine";
-import { analyzeTriangleMesh, composeTransform3, eulerTransform3, transformTriangleMesh, translationTransform3, } from "@metamesh/modeling/geometry";
+import { defaultModelingLimits, } from "@metamesh/modeling/engine";
+import { IDENTITY_TRANSFORM3, validateRigidTransform3, } from "@metamesh/modeling/geometry";
+import * as mesh from "@metamesh/modeling/geometry/mesh";
 import { authoringPackageNames, confinedFile } from "./environment.js";
 import { AuthoringError, isRecord } from "./errors.js";
 export function sha256(value) {
@@ -13,37 +14,41 @@ export async function writeAtomicJson(file, value) {
     await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx" });
     await rename(temporary, file);
 }
-export async function captureSnapshot(directory, snapshot, metadata, export3mf) {
+export async function captureSnapshot(directory, snapshot, metadata) {
     await mkdir(join(directory, "geometry"), { recursive: true });
     const resources = [];
     const parts = [];
     const seen = new Map();
+    const capturedResources = new Map();
     const store = async (path, bytes) => {
         await writeFile(join(directory, path), bytes, { flag: "wx" });
         return { path, bytes: bytes.byteLength, sha256: sha256(bytes) };
     };
     for (const part of snapshot.parts) {
-        const positions = part.geometry.positions;
-        const indices = part.geometry.indices;
-        const positionBytes = new Uint8Array(positions.buffer, positions.byteOffset, positions.byteLength);
-        const indexBytes = new Uint8Array(indices.buffer, indices.byteOffset, indices.byteLength);
-        const key = `${sha256(positionBytes)}:${sha256(indexBytes)}`;
-        let resourceId = seen.get(key);
+        let resourceId = capturedResources.get(part.geometry);
         if (resourceId === undefined) {
-            resourceId = `geometry-${resources.length}`;
-            seen.set(key, resourceId);
-            resources.push({
-                id: resourceId,
-                positions: await store(`geometry/${resourceId}.positions.f32`, positionBytes),
-                indices: await store(`geometry/${resourceId}.indices.u32`, indexBytes),
-                measurements: part.geometry.measurements,
-            });
+            const positions = part.geometry.positions.copy();
+            const indices = part.geometry.indices.copy();
+            const positionBytes = new Uint8Array(positions.buffer, positions.byteOffset, positions.byteLength);
+            const indexBytes = new Uint8Array(indices.buffer, indices.byteOffset, indices.byteLength);
+            const key = `${sha256(positionBytes)}:${sha256(indexBytes)}`;
+            resourceId = seen.get(key);
+            if (resourceId === undefined) {
+                resourceId = `geometry-${resources.length}`;
+                seen.set(key, resourceId);
+                resources.push({
+                    id: resourceId,
+                    positions: await store(`geometry/${resourceId}.positions.f32`, positionBytes),
+                    indices: await store(`geometry/${resourceId}.indices.u32`, indexBytes),
+                    measurements: part.geometry.measurements,
+                });
+            }
+            capturedResources.set(part.geometry, resourceId);
         }
         parts.push({
             id: part.id,
             resourceId,
-            position: part.position,
-            rotation: part.rotation,
+            transform: part.transform,
             measurements: part.measurements,
             ...(part.color === undefined ? {} : { color: part.color }),
         });
@@ -56,9 +61,6 @@ export async function captureSnapshot(directory, snapshot, metadata, export3mf)
         dependencies: snapshot.dependencies,
         resources,
         parts,
-        ...(export3mf === undefined
-            ? {}
-            : { export3mf: await store("model.3mf", new Uint8Array(export3mf)) }),
     };
     await writeAtomicJson(join(directory, "manifest.json"), manifest);
     return manifest;
@@ -69,6 +71,16 @@ function invalid(message) {
 const vector = (value) => Array.isArray(value) &&
     value.length === 3 &&
     value.every((number) => typeof number === "number" && Number.isFinite(number));
+function rigidTransform(value) {
+    try {
+        validateRigidTransform3(value);
+        const matrix = value;
+        return matrix[12] === 0 && matrix[13] === 0 && matrix[14] === 0 && matrix[15] === 1;
+    }
+    catch {
+        return false;
+    }
+}
 const bounds = (value) => isRecord(value) &&
     vector(value.min) &&
     vector(value.max) &&
@@ -111,8 +123,7 @@ function measurements(value) {
         ["signedVolume", "surfaceArea"].every((key) => typeof value[key] === "number" && Number.isFinite(value[key])) &&
         positiveInteger(value.triangleCount) &&
         positiveInteger(value.vertexCount) &&
-        (value.connectedComponentCount === undefined ||
-            positiveInteger(value.connectedComponentCount)) &&
+        (value.shellCount === undefined || positiveInteger(value.shellCount)) &&
         (value.edgeCount === undefined || positiveInteger(value.edgeCount)));
 }
 function sameBounds(actual, recorded) {
@@ -124,7 +135,7 @@ function sameMeasurements(actual, recorded) {
         actual.triangleCount === recorded.triangleCount &&
         actual.signedVolume === recorded.signedVolume &&
         actual.surfaceArea === recorded.surfaceArea &&
-        actual.connectedComponentCount === recorded.connectedComponentCount &&
+        actual.shellCount === recorded.shellCount &&
         actual.edgeCount === recorded.edgeCount &&
         sameBounds(actual.bounds, recorded.bounds));
 }
@@ -134,7 +145,7 @@ function manifestFrom(value) {
     const limits = policy !== undefined && isRecord(policy.limits) ? policy.limits : undefined;
     const dependencies = isRecord(value) && isRecord(value.dependencies) ? value.dependencies : undefined;
     if (!isRecord(value) ||
-        value.formatVersion !== 1 ||
+        value.formatVersion !== 3 ||
         value.status !== "complete" ||
         !identifier(value.runId) ||
         typeof value.createdAt !== "string" ||
@@ -189,14 +200,14 @@ function manifestFrom(value) {
             "partCount",
             "vertexCount",
             "triangleCount",
-            "volumeMm3",
+            "signedVolume",
             "byteCount",
             "buildMs",
-            "finalizationMs",
-            "generationMs",
+            "finalizeMs",
+            "generateMs",
         ].every((key) => typeof stats?.[key] === "number" && Number.isFinite(stats[key])) ||
         !["partCount", "vertexCount", "triangleCount", "byteCount"].every((key) => positiveInteger(stats?.[key])) ||
-        !["buildMs", "finalizationMs", "generationMs"].every((key) => typeof stats?.[key] === "number" && stats[key] >= 0) ||
+        !["buildMs", "finalizeMs", "generateMs"].every((key) => typeof stats?.[key] === "number" && stats[key] >= 0) ||
         dependencies === undefined ||
         !strings(dependencies.modelParameters) ||
         !Array.isArray(dependencies.computations) ||
@@ -215,8 +226,7 @@ function manifestFrom(value) {
         value.parts.length === 0 ||
         stats?.partCount !== value.parts.length ||
         value.parts.length > limits.maxParts ||
-        value.resources.length > limits.maxParts ||
-        (value.export3mf !== undefined && !bufferDescriptor(value.export3mf)))
+        value.resources.length > limits.maxParts)
         invalid("Unsupported, incomplete, or malformed captured-run manifest.");
     const ids = new Set();
     for (const resource of value.resources) {
@@ -236,8 +246,9 @@ function manifestFrom(value) {
             partIds.has(part.id) ||
             typeof part.resourceId !== "string" ||
             !ids.has(part.resourceId) ||
-            !vector(part.position) ||
-            !vector(part.rotation) ||
+            !rigidTransform(part.transform) ||
+            Object.hasOwn(part, "position") ||
+            Object.hasOwn(part, "rotation") ||
             !measurements(part.measurements) ||
             (part.color !== undefined &&
                 (typeof part.color !== "string" || !/^#[a-f0-9]{6}$/i.test(part.color))))
@@ -288,7 +299,7 @@ export async function readCapturedRun(directory) {
                 positions: new Float32Array(positions.buffer),
                 indices: new Uint32Array(indices.buffer),
             };
-            const facts = analyzeTriangleMesh(geometry, { requireClosed: true, includeTopology: true });
+            const facts = mesh.analyze(geometry, { requireClosed: true, includeTopology: true });
             if (!sameMeasurements(facts, resource.measurements))
                 invalid(`Captured measurements do not match geometry ${resource.id}.`);
             resources.set(resource.id, { geometry, facts });
@@ -302,9 +313,12 @@ export async function readCapturedRun(directory) {
         };
         for (const part of manifest.parts) {
             const resource = resources.get(part.resourceId);
-            const facts = [...part.position, ...part.rotation].every((number) => number === 0)
+            const facts = part.transform.every((number, index) => number === IDENTITY_TRANSFORM3[index])
                 ? resource.facts
-                : analyzeTriangleMesh(transformTriangleMesh(resource.geometry, composeTransform3(translationTransform3(part.position), eulerTransform3(part.rotation))), { requireClosed: true, includeTopology: true });
+                : mesh.analyze(mesh.transform(resource.geometry, part.transform), {
+                    requireClosed: true,
+                    includeTopology: true,
+                });
             if (!sameMeasurements(facts, part.measurements))
                 invalid(`Captured placement measurements do not match part ${part.id}.`);
             vertices += facts.vertexCount;
@@ -317,15 +331,13 @@ export async function readCapturedRun(directory) {
         }
         if (vertices !== manifest.stats.vertexCount ||
             triangles !== manifest.stats.triangleCount ||
-            volume !== manifest.stats.volumeMm3 ||
+            volume !== manifest.stats.signedVolume ||
             manifest.stats.byteCount < totalBytes ||
             manifest.stats.byteCount > manifest.policy.limits.maxBytes ||
             vertices > manifest.policy.limits.maxVertices ||
             triangles > manifest.policy.limits.maxTriangles ||
             !sameBounds(aggregateBounds, manifest.bounds))
             invalid("Captured aggregate facts do not match finalized part geometry.");
-        if (manifest.export3mf !== undefined)
-            await readBuffer(root, manifest.export3mf);
         return {
             directory: root,
             manifest,