@metamesh/testkit 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,204 @@
 # @metamesh/testkit
 
+## 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
+
+## 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

package/README.md

@@ -1,146 +1,157 @@
 # `@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.
+Check that your MetaMesh models produce the geometry you expect. Run models and Generators with
+the production engine, check their measurements, and test definitions and presets with your
+preferred 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, with Testkit as 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):
+The assertions work without a test framework and don't register globals. Testkit has no compiler,
+renderer, or browser dependency. Use the [CLI](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/README.md)
+to check source files, save captured runs, or render images.
 
-```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 {
-  await runner.withModel(getDefaultParameters(definition), async (model) => {
-    await expectValidParts(model.parts);
-  });
-} finally {
-  runner.dispose();
-}
-```
-
-`withModel` normalizes values, prepares services, and runs the persistent session. It awaits the
-callback, returns its result, and disposes the snapshot even when assertions throw or reject.
-Schema or generation assertion failures throw `GenerationError` with their structured diagnostics.
-Unexpected execution and malformed-output errors retain their original failures. The runner's
-session and caches remain reusable until `runner.dispose()`.
+## Test a model
 
-For a plain model program, import `withModel` from Testkit:
+Build a plate, check its volume and shell count, then check that its meshes reconstruct correctly:
 
 ```ts
-import { box, generate } from "@metamesh/modeling";
-import { expectValidParts, withModel } from "@metamesh/testkit";
+import { box } from "@metamesh/modeling";
+import { assertMeshMeasurements, assertValidParts, runModel } from "@metamesh/testkit";
 
-const model = generate<{ width: number }>(({ params, part }) =>
-  part("plate", box({ size: [params.width, 20, 4] }))
+const result = await runModel<{ width: number }>(
+  ({ params, part }) => part("plate", box({ size: [params.width, 20, 4] })),
+  { width: 30 }
 );
-await withModel(model, { width: 30 }, async (snapshot) => {
-  await expectValidParts(snapshot.parts);
-});
-```
-
-The plain-model helper also disposes its temporary session. Its optional fourth argument accepts
-session policy, prepared `services`, and a test-owned `engine`; declared services are required.
-It passes model parameters directly without Generator normalization and never disposes the engine.
-Previously obtained parts remain usable after snapshot disposal; returning parts does not eagerly
-copy their buffers.
-
-Snapshot parts include session-specific geometry resource identities. Compare manufacturing
-fields such as world positions, indices, measurements, IDs and colors for equality across runs.
-Each positions or indices read copies its buffer; capture the buffer once before a dense loop.
-
-Use `runner.execute` for explicit snapshot ownership or invalid-result assertions. It returns
-`invalid` for schema or generation assertion errors. Dispose successful 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.
-
-Compare physical measurements with explicit tolerances. For a 30 × 20 × 4 mm box mesh:
-
-```ts
-import { expectMeshMeasurements } from "@metamesh/testkit";
-
-expectMeshMeasurements(
-  mesh,
-  { signedVolume: 30 * 20 * 4, connectedComponentCount: 1 },
+assertMeshMeasurements(
+  result.part("plate"),
+  { signedVolume: 2400, shellCount: 1 },
   { signedVolume: 0.05 }
 );
+await assertValidParts(result.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.
+`runModel` returns immutable parts, measurements, diagnostics, and dependencies. Results need no
+cleanup. Use `result.part(id)` to find a required part by its ID, or iterate over `result.parts`.
 
-## Font fixtures
+Always await `assertValidParts(parts)`. It checks the world-space buffers for closed topology,
+then reconstructs each part from its local geometry and rigid transform and compares the positions
+and indices exactly. It resolves to the same parts or rejects on failure. Pass an engine as the
+second argument to reuse one you own; otherwise, the shared test engine initializes when needed.
 
-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.
+You can pass an existing Modeling program: `await runModel(program, parameters)` uses the same
+program and parameter types as `engine.run`. For a small test, pass a synchronous callback
+directly. Without parameters, no type argument or wrapper is needed:
+`await runModel(({ part }) => part("cube", box({ size: 2 })))`.
+Parameters keep 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)` for exact content
+comparisons. 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 `contentMatchers` 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 Generator, import its definition and default runtime, then call
+`runModel({ definition, runtime }, parameters)`. This validates the inputs and prepares services
+before generation. Omit parameters or pass `undefined` to use defaults. Supplied inputs use the
+definition's inferred types and must form a complete canonical map.
+
+To change one value, spread `getDefaultParameters(definition)` and apply your override. The runner
+doesn't merge defaults into supplied values. Use SDK `normalizeParameters` when recovering saved
+values. Plain model parameters pass through directly.
+
+Import the actual Generator entry point in integration tests so they exercise its input handling
+and model together. Direct callbacks are useful for testing construction helpers 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. Its `run` method
+returns a generated result or a structured validation failure. Call `runner.run(record)` to test
+unknown keys, missing fields, or wrong value types. Use `check` to test 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.
+
+### Check cache reuse
+
+For models using `memo`, 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 for unchanged inputs. Keep pure helpers stable and pass changing values
+as arguments; pass the current params/context to track fields read inside the helper.
+Verification has bounded comparison work. For outputs it can't compare, use `{ cache: false }`
+on a separate runner and compare the resulting geometry. Neither check proves arbitrary JavaScript pure.
+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.                      |
+
+For a Generator with Font parameters, supply `prepareServices` to prepare its font services 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"}