@metamesh/testkit 0.0.0-stage → 0.14.0

package/dist/assertions.js

@@ -0,0 +1,103 @@
+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";
+function stringify(value, label) {
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined)
+            throw new TypeError(`${label} is not JSON-serializable.`);
+        return serialized;
+    }
+    catch (cause) {
+        throw new TypeError(`${label} is not JSON-serializable.`, { cause });
+    }
+}
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortJson);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, sortJson(entry)]));
+}
+function stableStringify(value, label) {
+    return stringify(sortJson(value), label);
+}
+/** Throws unless a definition already has the canonical package-serializable representation. */
+export function expectSerializableDefinition(definition) {
+    parseGeneratorDefinition(definition);
+    const decoded = JSON.parse(stringify(definition, "Generator definition"));
+    const parsed = parseGeneratorDefinition(decoded);
+    if (stableStringify(parsed, "Parsed Generator definition") !==
+        stableStringify(decoded, "Generator definition")) {
+        throw new TypeError("Generator definition must already use its canonical serialized form.");
+    }
+}
+/** Throws unless defaults strictly decode and equal the defaults derived from the definition. */
+export function expectValidDefaults(definition, defaults) {
+    const parsed = createParamCodec(definition).parse(defaults);
+    if (stableStringify(parsed, "Generator defaults") !==
+        stableStringify(getDefaultParameters(definition), "Derived Generator defaults")) {
+        throw new TypeError("Generator defaults do not match their definition.");
+    }
+}
+/** Checks preset metadata. Validate domain assertions through the generation test runner. */
+export function expectValidPresets(definition, presets) {
+    validateGeneratorPresets(definition, presets);
+}
+export function expectValidParts(value, engine) {
+    if (engine === undefined)
+        return getTestEngine().then((host) => expectValidParts(value, host));
+    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;
+            // Captured engine snapshots expose owned buffer copies through accessors.
+            descriptors["positions"] = { value: part.positions, enumerable: true };
+            descriptors["indices"] = { value: part.indices, enumerable: true };
+            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();
+    }
+    return parts;
+}
+//# sourceMappingURL=assertions.js.map

package/dist/assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.js","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"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"}

package/dist/docs/guides/package.md

@@ -0,0 +1,119 @@
+# `@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.
+
+> **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:
+
+```bash
+pnpm add @metamesh/generator-sdk @metamesh/modeling
+pnpm add -D @metamesh/testkit
+```
+
+## Execute models in tests
+
+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):
+
+```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.
+
+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 },
+  { signedVolume: 0.05 }
+);
+```
+
+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.
+
+`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.
+
+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.
+
+## 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).
+
+## License
+
+[Apache-2.0](https://github.com/JasonKoolman/metamesh/blob/main/packages/testkit/LICENSE).

package/dist/docs/manifest.json

@@ -0,0 +1,259 @@
+{
+  "formatVersion": 1,
+  "packageName": "@metamesh/testkit",
+  "packageVersion": "0.14.0",
+  "documents": [
+    {
+      "id": "testkit/guide/testing",
+      "title": "Test models and Generators",
+      "summary": "Runner-neutral MetaMesh model and Generator testing helpers, assertions, and local font fixtures.",
+      "path": "guides/package.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "guide",
+        "installation",
+        "testkit"
+      ]
+    },
+    {
+      "id": "testkit/reference/font-fixtures/LoadedFontFixtures",
+      "title": "LoadedFontFixtures",
+      "summary": "Byte-verified local font selections and a reusable Generator service-preparation adapter.",
+      "path": "reference/font-fixtures/LoadedFontFixtures.md",
+      "importPath": "@metamesh/testkit/font-fixtures",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "font-fixtures",
+        "LoadedFontFixtures"
+      ]
+    },
+    {
+      "id": "testkit/reference/font-fixtures/loadFontFixtures",
+      "title": "loadFontFixtures",
+      "summary": "Node-only local descriptor loader. Paths resolve beside the descriptor; bytes never come from a catalog.",
+      "path": "reference/font-fixtures/loadFontFixtures.md",
+      "importPath": "@metamesh/testkit/font-fixtures",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "font-fixtures",
+        "loadFontFixtures"
+      ]
+    },
+    {
+      "id": "testkit/reference/font-fixtures/loadFontFixtureServices",
+      "title": "loadFontFixtureServices",
+      "summary": "Fixture provider matching createGeneratorTestRunner's asynchronous service boundary.",
+      "path": "reference/font-fixtures/loadFontFixtureServices.md",
+      "importPath": "@metamesh/testkit/font-fixtures",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "font-fixtures",
+        "loadFontFixtureServices"
+      ]
+    },
+    {
+      "id": "testkit/reference/fonts/FontTestFixture",
+      "title": "FontTestFixture",
+      "summary": "A checked-in immutable font fixture; no catalog or network is used by the test harness.",
+      "path": "reference/fonts/FontTestFixture.md",
+      "importPath": "@metamesh/testkit/fonts",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "fonts",
+        "FontTestFixture"
+      ]
+    },
+    {
+      "id": "testkit/reference/fonts/prepareFontTestServices",
+      "title": "prepareFontTestServices",
+      "summary": "Prepares the same synchronous text service used by Studio, from reproducible fixture bytes.",
+      "path": "reference/fonts/prepareFontTestServices.md",
+      "importPath": "@metamesh/testkit/fonts",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "fonts",
+        "prepareFontTestServices"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/createGeneratorTestRunner",
+      "title": "createGeneratorTestRunner",
+      "summary": "Creates a lazy runner for one generation program without loading assets or an engine.",
+      "path": "reference/index/createGeneratorTestRunner.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "createGeneratorTestRunner"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/expectMeshMeasurements",
+      "title": "expectMeshMeasurements",
+      "summary": "Analyzes current buffers, requires closed oriented edge topology, and checks selected physical facts with explicit absolute tolerances. Returns fresh measurements without initializing an engine. These facts do not prove geometric equivalence or absence of self-intersections.",
+      "path": "reference/index/expectMeshMeasurements.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "expectMeshMeasurements"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/expectSerializableDefinition",
+      "title": "expectSerializableDefinition",
+      "summary": "Throws unless a definition already has the canonical package-serializable representation.",
+      "path": "reference/index/expectSerializableDefinition.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "expectSerializableDefinition"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/expectValidDefaults",
+      "title": "expectValidDefaults",
+      "summary": "Throws unless defaults strictly decode and equal the defaults derived from the definition.",
+      "path": "reference/index/expectValidDefaults.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "expectValidDefaults"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/expectValidParts",
+      "title": "expectValidParts",
+      "summary": "Checks finalized engine parts after omitting measurement facts from their strict wire DTOs. Runs mesh reconstruction/finalization synchronously using the supplied engine. Strictly checks unknown wire data and reconstructs its meshes using the supplied engine. Initializes the shared test engine lazily, then applies the same wire and mesh checks.",
+      "path": "reference/index/expectValidParts.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "expectValidParts"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/expectValidPresets",
+      "title": "expectValidPresets",
+      "summary": "Checks preset metadata. Validate domain assertions through the generation test runner.",
+      "path": "reference/index/expectValidPresets.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "expectValidPresets"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/GeneratorTestExecution",
+      "title": "GeneratorTestExecution",
+      "summary": "Parameter or assertion failure, or a generated snapshot owned separately from its runner.",
+      "path": "reference/index/GeneratorTestExecution.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "GeneratorTestExecution"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/GeneratorTestRunner",
+      "title": "GeneratorTestRunner",
+      "summary": "A lazy reusable Generator test session; dispose the runner and every returned snapshot separately.",
+      "path": "reference/index/GeneratorTestRunner.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "GeneratorTestRunner"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/GeneratorTestRunnerOptions",
+      "title": "GeneratorTestRunnerOptions",
+      "summary": "Fixed host resources and optional asynchronous asset preparation.",
+      "path": "reference/index/GeneratorTestRunnerOptions.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "GeneratorTestRunnerOptions"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/getTestEngine",
+      "title": "getTestEngine",
+      "summary": "Returns the shared test engine, initializing it only on first request. Runner construction does not call this function.",
+      "path": "reference/index/getTestEngine.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "getTestEngine"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/MeshMeasurementExpectation",
+      "title": "MeshMeasurementExpectation",
+      "summary": "Physical expectations for a closed mesh; omitted facts are not asserted.",
+      "path": "reference/index/MeshMeasurementExpectation.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "MeshMeasurementExpectation"
+      ]
+    },
+    {
+      "id": "testkit/reference/index/MeshMeasurementTolerances",
+      "title": "MeshMeasurementTolerances",
+      "summary": "Absolute nonnegative comparison allowances; each omitted tolerance defaults to zero.",
+      "path": "reference/index/MeshMeasurementTolerances.md",
+      "importPath": "@metamesh/testkit",
+      "availability": "Local Node testing",
+      "canonical": "https://metamesh.studio/docs/develop/agent-authoring#test-models",
+      "keywords": [
+        "reference",
+        "index",
+        "MeshMeasurementTolerances"
+      ]
+    }
+  ]
+}

package/dist/docs/reference/font-fixtures/LoadedFontFixtures.md

@@ -0,0 +1,13 @@
+# LoadedFontFixtures
+
+Byte-verified local font selections and a reusable Generator service-preparation adapter.
+
+Import from `@metamesh/testkit/font-fixtures` (@metamesh/testkit@0.14.0).
+
+```ts
+/** Byte-verified local font selections and a reusable Generator service-preparation adapter. */
+export interface LoadedFontFixtures {
+    readonly selections: readonly FontSelection[];
+    readonly prepareServices: (definition: GeneratorDefinition, parameters: Readonly<Record<string, unknown>>) => Promise<GeneratorServices>;
+}
+```

package/dist/docs/reference/font-fixtures/loadFontFixtureServices.md

@@ -0,0 +1,10 @@
+# loadFontFixtureServices
+
+Fixture provider matching createGeneratorTestRunner's asynchronous service boundary.
+
+Import from `@metamesh/testkit/font-fixtures` (@metamesh/testkit@0.14.0).
+
+```ts
+/** Fixture provider matching createGeneratorTestRunner's asynchronous service boundary. */
+export declare function loadFontFixtureServices(filename: string): Promise<LoadedFontFixtures["prepareServices"]>;
+```

package/dist/docs/reference/font-fixtures/loadFontFixtures.md

@@ -0,0 +1,10 @@
+# loadFontFixtures
+
+Node-only local descriptor loader. Paths resolve beside the descriptor; bytes never come from a catalog.
+
+Import from `@metamesh/testkit/font-fixtures` (@metamesh/testkit@0.14.0).
+
+```ts
+/** Node-only local descriptor loader. Paths resolve beside the descriptor; bytes never come from a catalog. */
+export declare function loadFontFixtures(filename: string): Promise<LoadedFontFixtures>;
+```

package/dist/docs/reference/fonts/FontTestFixture.md

@@ -0,0 +1,17 @@
+# FontTestFixture
+
+A checked-in immutable font fixture; no catalog or network is used by the test harness.
+
+Import from `@metamesh/testkit/fonts` (@metamesh/testkit@0.14.0).
+
+```ts
+/** A checked-in immutable font fixture; no catalog or network is used by the test harness. */
+export interface FontTestFixture {
+    /** Font face, weight and SHA-256 revision to resolve from these bytes. */
+    readonly selection: FontSelection;
+    /** Complete checked-in font file; its digest must match selection.revision. */
+    readonly bytes: Uint8Array<ArrayBuffer>;
+    /** Weight represented by a static face; omit for variable fonts. */
+    readonly staticWeight?: number;
+}
+```

package/dist/docs/reference/fonts/prepareFontTestServices.md

@@ -0,0 +1,10 @@
+# prepareFontTestServices
+
+Prepares the same synchronous text service used by Studio, from reproducible fixture bytes.
+
+Import from `@metamesh/testkit/fonts` (@metamesh/testkit@0.14.0).
+
+```ts
+/** Prepares the same synchronous text service used by Studio, from reproducible fixture bytes. */
+export declare function prepareFontTestServices(fixtures: readonly FontTestFixture[]): Promise<GeneratorServices>;
+```

package/dist/docs/reference/index/GeneratorTestExecution.md

@@ -0,0 +1,19 @@
+# GeneratorTestExecution
+
+Parameter or assertion failure, or a generated snapshot owned separately from its runner.
+
+Import from `@metamesh/testkit` (@metamesh/testkit@0.14.0).
+
+```ts
+/** Parameter or assertion failure, or a generated snapshot owned separately from its runner. */
+export type GeneratorTestExecution<D extends GeneratorDefinition> = {
+    readonly type: "invalid";
+    readonly parameters: GeneratorParams<D>;
+    readonly validation: ParameterValidationResult;
+} | {
+    readonly type: "generated";
+    readonly parameters: GeneratorParams<D>;
+    readonly validation: ParameterValidationResult;
+    readonly model: ModelSnapshot;
+};
+```

package/dist/docs/reference/index/GeneratorTestRunner.md

@@ -0,0 +1,19 @@
+# GeneratorTestRunner
+
+A lazy reusable Generator test session; dispose the runner and every returned snapshot separately.
+
+Import from `@metamesh/testkit` (@metamesh/testkit@0.14.0).
+
+```ts
+/** A lazy reusable Generator test session; dispose the runner and every returned snapshot separately. */
+export interface GeneratorTestRunner<D extends GeneratorDefinition> {
+    /** Checks declarations and assertions only. Set `normalize: false` to probe deliberately invalid typed values. */
+    readonly validate: (parameters: GeneratorParams<D>, options?: {
+        readonly normalize?: boolean;
+    }) => Promise<ParameterValidationResult>;
+    /** Normalizes once, prepares assets, and executes the same persistent session used by production hosts. */
+    readonly execute: (parameters: Readonly<Record<string, unknown>>) => Promise<GeneratorTestExecution<D>>;
+    /** Releases runner caches; separately owned snapshots remain valid. */
+    readonly dispose: () => void;
+}
+```

package/dist/docs/reference/index/GeneratorTestRunnerOptions.md

@@ -0,0 +1,14 @@
+# GeneratorTestRunnerOptions
+
+Fixed host resources and optional asynchronous asset preparation.
+
+Import from `@metamesh/testkit` (@metamesh/testkit@0.14.0).
+
+```ts
+/** Fixed host resources and optional asynchronous asset preparation. */
+export interface GeneratorTestRunnerOptions<D extends GeneratorDefinition> {
+    readonly prepareServices?: (definition: D, parameters: GeneratorParams<D>) => GeneratorServices | Promise<GeneratorServices>;
+    readonly engine?: ModelEngine;
+    readonly limits?: Partial<ModelingLimits>;
+}
+```

package/dist/docs/reference/index/MeshMeasurementExpectation.md

@@ -0,0 +1,19 @@
+# MeshMeasurementExpectation
+
+Physical expectations for a closed mesh; omitted facts are not asserted.
+
+Import from `@metamesh/testkit` (@metamesh/testkit@0.14.0).
+
+```ts
+/** Physical expectations for a closed mesh; omitted facts are not asserted. */
+export interface MeshMeasurementExpectation {
+    /** Axis-aligned XYZ bounds in millimetres. */
+    readonly bounds?: Bounds3;
+    /** Oriented enclosed volume in cubic millimetres; outward winding is positive. */
+    readonly signedVolume?: number;
+    /** Sum of triangle areas in square millimetres. */
+    readonly surfaceArea?: number;
+    /** Exact number of components connected by indexed mesh edges. */
+    readonly connectedComponentCount?: number;
+}
+```

package/dist/docs/reference/index/MeshMeasurementTolerances.md

@@ -0,0 +1,17 @@
+# MeshMeasurementTolerances
+
+Absolute nonnegative comparison allowances; each omitted tolerance defaults to zero.
+
+Import from `@metamesh/testkit` (@metamesh/testkit@0.14.0).
+
+```ts
+/** Absolute nonnegative comparison allowances; each omitted tolerance defaults to zero. */
+export interface MeshMeasurementTolerances {
+    /** Allowance for each minimum/maximum XYZ coordinate in millimetres. */
+    readonly bounds?: number;
+    /** Allowance for signed volume in cubic millimetres. */
+    readonly signedVolume?: number;
+    /** Allowance for surface area in square millimetres. */
+    readonly surfaceArea?: number;
+}
+```