@metamesh/testkit 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,196 @@
 # @metamesh/testkit
 
+## 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
+
+## 0.17.0
+
+### Minor Changes
+
+- Add `defineGeneratorModel(definition, callback)` through the optional
+  `@metamesh/generator-sdk/modeling` adapter. It infers controls, synchronous services, and diagnostic
+  parameter IDs while leaving the SDK root independent of the Modeling runtime.
+
+  Add `runner.withModel(parameters, callback)` and Testkit's `withModel(program, parameters, callback,
+options?)` for scoped assertions. Both await synchronous or asynchronous callbacks and release
+  their snapshot in `finally`; the plain-model helper also releases its temporary session.
+  Generator validation failures throw the existing structured `GenerationError` diagnostics.
+
+  Migration tip: replace private definition-plus-`generate` wrappers with the SDK adapter, and use
+  scoped callbacks instead of repeated successful-result narrowing and snapshot disposal. Keep
+  `runner.execute` and direct engine sessions for tests that inspect invalid results, cache behavior,
+  or explicit snapshot ownership. Prepared services are required for plain models that declare them.
+
+  Scoped callbacks retain snapshot parts without eagerly copying their buffers. For cross-run
+  geometry comparisons, select manufacturing fields rather than transient geometry resource IDs.
+  Capture `positions` and `indices` once before dense traversal: each accessor read returns a copy.
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies [d0cc194]
+- Updated dependencies
+- Updated dependencies
+  - @metamesh/modeling@0.17.0
+  - @metamesh/generator-sdk@0.17.0
+
 ## 0.16.0
 
 ### Minor Changes

package/README.md

@@ -1,120 +1,154 @@
 # `@metamesh/testkit`
 
-Test MetaMesh models and Generators with the same generation engine used by their hosts. Check definitions,
-presets, mesh validity, and physical measurements with any test runner.
+Test MetaMesh models and Generators with their production engine. Check definitions, presets,
+geometry, and physical measurements with any test runner.
 
 > **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
 > same minor line.
 
 ## Installation
 
-Install the same exact SDK, Modeling, and Testkit release. Testkit is a development dependency:
+Install matching SDK, Modeling, and Testkit releases. Testkit is a development dependency:
 
 ```bash
 pnpm add @metamesh/generator-sdk @metamesh/modeling
 pnpm add -D @metamesh/testkit
 ```
 
-## Execute models in tests
+The package publishes ES modules only. Use Node.js 24 or newer. TypeScript consumers need
+TypeScript 6.0 or newer, `strict` checking, and `NodeNext` or `Bundler` module resolution.
 
-Given a Generator module exporting its `definition` and default runtime, such as the
-[SDK example](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/README.md#define-controls):
+Testkit has no test-framework, compiler, renderer, or browser dependency. For source checking,
+captured runs, or images, use [CLI](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/README.md).
 
-```ts
-import { getDefaultParameters } from "@metamesh/generator-sdk/parameters";
-import { createGeneratorTestRunner, expectValidParts } from "@metamesh/testkit";
-
-import runtime, { definition } from "./generator.js";
-
-const runner = createGeneratorTestRunner(definition, runtime);
-try {
-  const result = await runner.execute(getDefaultParameters(definition));
-  if (result.type !== "generated") throw new Error("Expected valid Generator output.");
-  try {
-    await expectValidParts(result.model.parts);
-  } finally {
-    result.model.dispose();
-  }
-} finally {
-  runner.dispose();
-}
-```
-
-`execute` normalizes values, prepares services, and runs a persistent session. Schema and assertion
-errors return `invalid`; unexpected execution or malformed-output errors reject. Dispose returned
-snapshots separately from the runner; captured snapshots remain valid after runner disposal.
-
-Use `runner.validate(parameters, { normalize: false })` to probe deliberately invalid typed values
-without finalizing parts. It checks declarations and reached assertions; observing geometry can
-still initialize the engine. Creating a runner alone loads no engine or assets. Pass `options.engine`
-to reuse a test-owned engine and `options.limits` to lower host ceilings.
-
-## Assertions
-
-Helpers throw on failure without depending on your test framework:
-
-| Helper                         | Checks                                                             |
-| ------------------------------ | ------------------------------------------------------------------ |
-| `expectSerializableDefinition` | Strict parsing and a canonical JSON round trip                     |
-| `expectValidDefaults`          | Strict parameter decoding and agreement with definition defaults   |
-| `expectValidPresets`           | Serializable preset metadata; use the runner for domain assertions |
-| `expectValidParts`             | Strict part metadata, closed topology, and native reconstruction   |
-| `expectMeshMeasurements`       | Bounds, area, signed volume, and connected-component count         |
-
-`expectValidParts(parts, engine)` is synchronous and uses that engine's limits. Without an engine,
-it returns a promise using the shared test engine and default limits. It also accepts finalized
-parts, stripping measurement facts before strict validation; other unknown fields reject.
-Snapshot inputs retain shared local mesh buffers and rigid placements in the returned parts.
+## Test a model
 
-Compare physical measurements with explicit tolerances. For a 30 × 20 × 4 mm box mesh:
+Build a plate, check its volume and shell count, then verify native reconstruction:
 
 ```ts
-import { expectMeshMeasurements } from "@metamesh/testkit";
+import { box } from "@metamesh/modeling";
+import { assertMeshMeasurements, assertValidParts, runModel } from "@metamesh/testkit";
 
-expectMeshMeasurements(
-  mesh,
-  { signedVolume: 30 * 20 * 4, connectedComponentCount: 1 },
+const model = await runModel<{ width: number }>(
+  ({ params, part }) => part("plate", box({ size: [params.width, 20, 4] })),
+  { width: 30 }
+);
+
+assertMeshMeasurements(
+  model.part("plate"),
+  { signedVolume: 2400, shellCount: 1 },
   { signedVolume: 0.05 }
 );
+await assertValidParts(model.parts);
 ```
 
-Bounds use mm, area mm², and volume mm³. Tolerances are absolute and default to zero; component
-counts are exact. Measurements check closed oriented topology without a native engine. Matching
-measurements alone do not establish geometric equivalence or exclude self-intersections; use
-`expectValidParts` for native reconstruction.
-
-## Font fixtures
-
-Supply `prepareServices` in runner options for models with fonts. It receives the definition and
-current parameters, and can return services synchronously or asynchronously. Missing fixtures or
-service failures reject before generation. A different services object starts a fresh session;
-return the same immutable object when capabilities are unchanged to retain computation caches.
+Helpers report failures without registering global assertions. `runModel` returns durable,
+immutable parts, measurements, diagnostics, and dependencies; the result needs no cleanup.
+Use `model.part(id)` for a required semantic part or `model.parts` for iteration and export.
+
+Always await `assertValidParts(parts, engine)`: it resolves to the same parts or rejects on failure.
+A supplied engine is reused; omission lazily initializes the shared test engine.
+It checks the supplied world-space buffers for closed topology, then requires their positions and
+indices to exactly match local geometry reconstructed with the declared rigid transform.
+A valid local mesh cannot conceal corrupted or inconsistent world-space output.
+
+Pass an existing Modeling program directly: `await runModel(program, parameters)` uses the same
+program and parameter types as `engine.run`. A synchronous generation callback is also accepted;
+without parameters, no type argument or wrapper is needed:
+`await runModel(({ part }) => part("cube", box({ size: 2 })))`.
+Parameters retain the program or callback's declared type; use
+`GenerateCallback<Parameters, Services>` for a reusable callback or supply
+`runModel<Parameters, Services>` inline. Options stay in the third argument; use `undefined` for
+omitted parameters when supplying an engine, limits, or prepared services.
 
-`prepareFontTestServices` from `/fonts` checks immutable font revisions and prepares services from
-checked-in bytes. Install Modeling's optional `fontkit` peer, plus `woff2-encoder` for WOFF2 fixtures.
-Tests need no font downloads or browser cache; retain the fixtures' licenses.
+## Assertions
 
-For local JSON fixture descriptors, `loadFontFixtureServices` from
-`@metamesh/testkit/font-fixtures` returns the runner's `prepareServices` adapter. Descriptor paths
-resolve beside the JSON file, and every file's SHA-256 must match its declared selection revision.
-`loadFontFixtures` additionally returns the verified selections. These loaders are Node-only;
-use `/fonts` when the host already supplies the bytes.
+| Helper                   | Checks                                                         |
+| ------------------------ | -------------------------------------------------------------- |
+| `assertValidDefinition`  | Strict parsing and a canonical JSON round trip.                |
+| `assertValidDefaults`    | Strict decoding and agreement with definition defaults.        |
+| `assertValidPresets`     | Complete, normalized preset metadata.                          |
+| `assertValidParts`       | Part metadata, closed topology, and native reconstruction.     |
+| `assertMeshMeasurements` | Bounds, surface area, signed volume, and surface shell count.  |
+| `assertEqualBuffer`      | Exact ordered numeric buffer contents without copying storage. |
+| `assertEqualMesh`        | Exact positions and indices, independently of mesh metadata.   |
+
+`assertValidDefinition` requires strict SDK parsing and a canonical JSON round trip; it does not
+execute the Generator. Check model assertions and domain constraints through the Generator runner.
+
+Measurement tolerances are absolute: millimetres for bounds, mm² for area, and mm³ for volume.
+They default to zero; shell counts are exact. Matching measurements do not prove geometric
+equivalence or rule out self-intersections. Use native reconstruction checks alongside them.
+
+Use `assertEqualBuffer(actual, expected)` or `assertEqualMesh(actual, expected)` directly without a
+test framework. They read `length` and `at(index)` without copying storage and throw
+`ContentMismatchError` with the first differing index or length. Malformed representations throw
+`TypeError`; reader failures propagate. Numeric equality uses `Object.is`: `NaN` equals `NaN` and
+signed zero differs. Mesh comparisons ignore metadata and require identical position and index
+contents. Geometrically equivalent meshes with different triangulation or ordering can fail.
+
+Register the thin optional adapters with your runner's `expect.extend(contentMatchers)` to use
+`toEqualBuffer` and `toEqualMesh`, including `.not`. Only `ContentMismatchError` becomes a failed
+matcher result; invalid inputs and unexpected errors still throw. Follow your runner's
+[matcher extension guidance](https://vitest.dev/guide/extending-matchers) for TypeScript declarations.
+
+## Test Generators and repeated edits
+
+For a module exporting its definition and default runtime, pass
+`runModel({ definition, runtime }, parameters)`. Omit parameters or pass `undefined` to use defaults;
+all other supplied Generator inputs have the definition's inferred types and must form a complete
+canonical map. Use `runner.run(record)` to test unknown keys, missing fields, or wrong value types.
+For one changed value, spread
+`getDefaultParameters(definition)` and then apply the override; the runner does not merge defaults. The overload strictly parses inputs and prepares
+services. Use SDK `normalizeParameters` explicitly when recovering saved values. Plain model
+parameters pass through directly.
+
+Generator integration tests should import the actual entry point instead of repeating its input
+resolution and builder wiring. Use a direct callback for isolated construction or mesh reconstruction.
+For a deliberate schema bypass, `runModel(runtime, parameters, { services })` executes
+the Generator's model behavior without claiming those values pass its parameter schema.
+See the [SDK example](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/README.md#define-controls).
+
+Use `createGeneratorTestRunner(definition, runtime)` for repeated parameter cases or cache tests.
+Its `run` method returns a generated result or structured validation failure. `check` probes
+declarations and reached assertions without finalizing parts; geometry observations can still
+require the engine. Dispose the runner in `finally`; returned results remain usable.
+Use `check(parameters, { validateInput: false })` only to probe model assertions with deliberately
+invalid typed values, bypassing the parameter schema.
+
+For models using `computed`, include repeated-edit tests with `{ verifyCache: true }` on the runner.
+Change geometry inputs and placement inputs independently. Verification reruns cached calculations
+and rejects changed results without tracked dependencies, including accidentally captured destructured
+parameters. Read parameters inside the computation or list changing outer values in its dependency
+array. Verification is a bounded development probe; unsupported captures or large results can
+require comparison with `{ cache: false }` on a separate runner. It cannot prove arbitrary JavaScript.
+Keep prepared service identity stable for unchanged assets; replacing services creates a new session
+and prevents testing cache reuse. Isolated `runModel` calls do not verify repeated-edit correctness.
+
+For plain models, use `engine.createSession(program, options)` for repeated edits or cache tests
+and dispose the session in `finally`. Session results remain usable after later runs and disposal.
+Both `runModel` and Generator runners can reuse a test-owned engine and lower its resource ceilings.
+They accept the same physical `resolution`, `meshValidation`, and `meshTopologyMode` policy.
+
+## Fonts and entry points
+
+| Import                            | Responsibility                                                                 |
+| --------------------------------- | ------------------------------------------------------------------------------ |
+| `@metamesh/testkit`               | Model execution, Generator runners, assertions, and optional content matchers. |
+| `@metamesh/testkit/fonts`         | Prepared font services from supplied fixture bytes.                            |
+| `@metamesh/testkit/font-fixtures` | Node-only JSON fixture loading with SHA-256 verification.                      |
+
+Font-dependent Generators receive a `prepareServices` callback before generation. Tests use
+checked-in bytes without CDN access; retain their licenses. Font preparation needs Modeling's
+optional `fontkit` peer, plus `woff2-encoder` for WOFF2 fixtures.
 
 ## Documentation
 
-Resolve `@metamesh/testkit/docs/manifest.json` for this installed version's Markdown
-reference and testing guidance. Testkit has no compiler, bundler, renderer, or browser dependencies.
-It shares the Modeling engine and Generator SDK contracts rather than duplicating runtime rules.
-
-For source checking, captured runs, documentation lookup, and images, install
-[`@metamesh/cli`](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/README.md).
-Its executable is `metamesh`; reusable Node authoring functions live in `@metamesh/cli/authoring`.
-
-- [Generator SDK](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/README.md) — definitions, parameter values, and module authoring.
-- [Modeling](https://github.com/JasonKoolman/metamesh/blob/main/packages/modeling/README.md) — geometry, sessions, and snapshots.
-- [API source](https://github.com/JasonKoolman/metamesh/blob/main/packages/testkit/src/index.ts) — runner and assertion exports; [font helpers](https://github.com/JasonKoolman/metamesh/blob/main/packages/testkit/src/fonts.ts) live in `/fonts`.
-
-For package development, see [Contributing](https://github.com/JasonKoolman/metamesh/blob/main/CONTRIBUTING.md).
+Resolve `@metamesh/testkit/docs/manifest.json` for exact-version Markdown guidance and annotated
+API references. With CLI installed, read `pnpm exec metamesh docs show testkit/guide/testing`.
+See [Modeling](https://github.com/JasonKoolman/metamesh/blob/main/packages/modeling/README.md)
+for geometry and [Contributing](https://github.com/JasonKoolman/metamesh/blob/main/CONTRIBUTING.md)
+for package development.
 
 ## License
 

package/dist/assertions.d.ts

@@ -1,20 +1,13 @@
 import type { GeneratorDefinition, GeneratorParams, GeneratorPreset } from "@metamesh/generator-sdk";
-import { type GeneratedPart } from "@metamesh/generator-sdk/runtime";
-import { type FinalizedPart } from "@metamesh/modeling";
-import type { ModelEngine } from "@metamesh/modeling/engine";
-/** Throws unless a definition already has the canonical package-serializable representation. */
-export declare function expectSerializableDefinition(definition: GeneratorDefinition): void;
+import type { ModelEngine, ModelPart } from "@metamesh/modeling/engine";
+/** Strictly parses a definition and requires its JSON round trip to retain the canonical package representation. */
+export declare function assertValidDefinition(definition: GeneratorDefinition): void;
 /** Throws unless defaults strictly decode and equal the defaults derived from the definition. */
-export declare function expectValidDefaults<const D extends GeneratorDefinition>(definition: D, defaults: GeneratorParams<D>): void;
+export declare function assertValidDefaults<const D extends GeneratorDefinition>(definition: D, defaults: GeneratorParams<D>): void;
 /** Checks preset metadata. Validate domain assertions through the generation test runner. */
-export declare function expectValidPresets<const D extends GeneratorDefinition>(definition: D, presets: readonly GeneratorPreset<D>[]): void;
-/**
- * Checks finalized parts without measurement facts, retaining shared snapshot resources and placement.
- * Runs mesh reconstruction/finalization synchronously using the supplied engine.
+export declare function assertValidPresets<const D extends GeneratorDefinition>(definition: D, presets: readonly GeneratorPreset<D>[]): void;
+/** Validates supplied world meshes and their exact agreement with reconstructed local geometry and placement.
+ * Resolves to the same parts or rejects on failure. A supplied engine is reused; otherwise the shared engine initializes lazily.
  */
-export declare function expectValidParts(value: readonly FinalizedPart[], engine: ModelEngine): readonly GeneratedPart[];
-/** Strictly checks unknown wire data and reconstructs its meshes using the supplied engine. */
-export declare function expectValidParts(value: unknown, engine: ModelEngine): readonly GeneratedPart[];
-/** Initializes the shared test engine lazily, then applies the same wire and mesh checks. */
-export declare function expectValidParts(value: unknown): Promise<readonly GeneratedPart[]>;
+export declare function assertValidParts(parts: readonly ModelPart[], engine?: ModelEngine): Promise<readonly ModelPart[]>;
 //# sourceMappingURL=assertions.d.ts.map

package/dist/assertions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EACf,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAC1F,OAAO,EAAY,KAAK,aAAa,EAAqB,MAAM,oBAAoB,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AA4B7D,gGAAgG;AAChG,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAUlF;AAED,iGAAiG;AACjG,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,CAAC,SAAS,mBAAmB,EACrE,UAAU,EAAE,CAAC,EACb,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,IAAI,CAQN;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,mBAAmB,EACpE,UAAU,EAAE,CAAC,EACb,OAAO,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,GACrC,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,MAAM,EAAE,WAAW,GAClB,SAAS,aAAa,EAAE,CAAC;AAE5B,+FAA+F;AAC/F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,aAAa,EAAE,CAAC;AAEhG,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC"}
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EACf,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAOjC,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AA2BxE,oHAAoH;AACpH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAU3E;AACD,iGAAiG;AACjG,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,CAAC,SAAS,mBAAmB,EACrE,UAAU,EAAE,CAAC,EACb,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,IAAI,CAQN;AACD,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,mBAAmB,EACpE,UAAU,EAAE,CAAC,EACb,OAAO,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,GACrC,IAAI,CAEN;AACD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CA6B/B"}

package/dist/assertions.js

@@ -1,8 +1,9 @@
 import { parseGeneratorDefinition, validateGeneratorPresets, } from "@metamesh/generator-sdk/packages";
 import { createParamCodec, getDefaultParameters } from "@metamesh/generator-sdk/parameters";
-import { parseGeneratedParts } from "@metamesh/generator-sdk/runtime";
 import { generate } from "@metamesh/modeling";
-import { getTestEngine } from "./engine.js";
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+import { assertEqualMesh } from "./content-assertions.js";
+import { getTestEngine } from "./test-engine.js";
 function stringify(value, label) {
     try {
         const serialized = JSON.stringify(value);
@@ -26,8 +27,8 @@ function sortJson(value) {
 function stableStringify(value, label) {
     return stringify(sortJson(value), label);
 }
-/** Throws unless a definition already has the canonical package-serializable representation. */
-export function expectSerializableDefinition(definition) {
+/** Strictly parses a definition and requires its JSON round trip to retain the canonical package representation. */
+export function assertValidDefinition(definition) {
     parseGeneratorDefinition(definition);
     const decoded = JSON.parse(stringify(definition, "Generator definition"));
     const parsed = parseGeneratorDefinition(decoded);
@@ -37,7 +38,7 @@ export function expectSerializableDefinition(definition) {
     }
 }
 /** Throws unless defaults strictly decode and equal the defaults derived from the definition. */
-export function expectValidDefaults(definition, defaults) {
+export function assertValidDefaults(definition, defaults) {
     const parsed = createParamCodec(definition).parse(defaults);
     if (stableStringify(parsed, "Generator defaults") !==
         stableStringify(getDefaultParameters(definition), "Derived Generator defaults")) {
@@ -45,74 +46,27 @@ export function expectValidDefaults(definition, defaults) {
     }
 }
 /** Checks preset metadata. Validate domain assertions through the generation test runner. */
-export function expectValidPresets(definition, presets) {
+export function assertValidPresets(definition, presets) {
     validateGeneratorPresets(definition, presets);
 }
-export function expectValidParts(value, engine) {
-    if (engine === undefined)
-        return getTestEngine().then((host) => expectValidParts(value, host));
-    const meshes = new WeakMap();
-    const wireValue = Array.isArray(value)
-        ? value.map((part, index) => {
-            if (typeof part !== "object" || part === null || !Object.hasOwn(part, "measurements"))
-                return part;
-            const prototype = Object.getPrototypeOf(part);
-            if (prototype !== null && prototype !== Object.prototype)
-                return part;
-            const descriptors = Object.getOwnPropertyDescriptors(part);
-            if (Object.keys(descriptors).some((key) => ![
-                "id",
-                "positions",
-                "indices",
-                "color",
-                "measurements",
-                "geometry",
-                "position",
-                "rotation",
-            ].includes(key)))
-                return part;
-            const resource = descriptors["geometry"];
-            if (resource !== undefined && !("value" in resource))
-                return part;
-            const geometry = resource?.value;
-            const source = typeof geometry === "object" && geometry !== null
-                ? geometry
-                : part;
-            // Snapshot getters return copies. Read each local resource once to retain shared storage.
-            let mesh = meshes.get(source);
-            if (mesh === undefined) {
-                mesh = { positions: source.positions, indices: source.indices };
-                meshes.set(source, mesh);
-            }
-            descriptors["positions"] = { value: mesh.positions, enumerable: true };
-            descriptors["indices"] = { value: mesh.indices, enumerable: true };
-            if (source === part) {
-                delete descriptors["position"];
-                delete descriptors["rotation"];
-            }
-            delete descriptors["measurements"];
-            delete descriptors["geometry"];
-            return Object.defineProperties({
-                geometryId: `assertion-${index}`,
-                geometryRevision: 0,
-                position: [0, 0, 0],
-                rotation: [0, 0, 0],
-            }, descriptors);
-        })
-        : value;
-    const parts = parseGeneratedParts(wireValue, engine.limits);
-    const session = engine.createSession(generate(({ part }) => parts.map((mesh) => part(mesh.id, {
-        geometry: mesh,
-        position: mesh.position,
-        rotation: mesh.rotation,
-        ...(mesh.color === undefined ? {} : { color: mesh.color }),
-    }))));
-    try {
-        session.run({}).dispose();
-    }
-    finally {
-        session.dispose();
+/** Validates supplied world meshes and their exact agreement with reconstructed local geometry and placement.
+ * Resolves to the same parts or rejects on failure. A supplied engine is reused; otherwise the shared engine initializes lazily.
+ */
+export async function assertValidParts(parts, engine) {
+    const host = engine ?? (await getTestEngine());
+    for (const part of parts) {
+        const unknown = Reflect.ownKeys(part).find((key) => typeof key !== "string" ||
+            !["id", "positions", "indices", "color", "measurements", "geometry", "transform"].includes(key));
+        if (unknown !== undefined)
+            throw new TypeError('Model part contains unknown field "' + String(unknown) + '".');
+        mesh.validate(part, { requireClosed: true });
     }
+    const reconstructed = host.run(generate(({ part }) => parts.map((value) => part(value.id, {
+        geometry: value.geometry,
+        transform: value.transform,
+        ...(value.color === undefined ? {} : { color: value.color }),
+    }))), undefined, { meshTopologyMode: "original" });
+    parts.forEach((part, index) => assertEqualMesh(part, reconstructed.parts[index]));
     return parts;
 }
 //# sourceMappingURL=assertions.js.map