@metamesh/testkit 0.17.0 → 0.19.0

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

package/dist/assertions.js.map

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

package/dist/content-assertions.d.ts

@@ -0,0 +1,28 @@
+/** Numeric contents readable without copying their storage, including immutable model buffers. */
+export interface BufferContent {
+    readonly length: number;
+    at(index: number): number | undefined;
+}
+/** Ordered manufacturing geometry; placement, appearance and resource identities are separate. */
+export interface MeshContent {
+    readonly positions: BufferContent;
+    readonly indices: BufferContent;
+}
+/** A difference in valid buffer contents, distinct from malformed inputs or reader failures. */
+export declare class ContentMismatchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Asserts exact ordered numeric contents through length and at(index), without copying storage.
+ * Uses Object.is regardless of storage type: NaN equals NaN; signed zero differs.
+ * Throws ContentMismatchError for the first difference, TypeError for malformed inputs, and
+ * preserves reader failures. This assertion does not establish valid manufacturing geometry.
+ */
+export declare function assertEqualBuffer(actual: BufferContent, expected: BufferContent): void;
+/**
+ * Asserts identical positions and indices with buffer-specific mismatch diagnostics.
+ * Ignores metadata. Geometrically equivalent meshes with different triangulation or ordering can fail.
+ * Shares assertEqualBuffer's numeric equality, validation and error behavior without copying storage.
+ */
+export declare function assertEqualMesh(actual: MeshContent, expected: MeshContent): void;
+//# sourceMappingURL=content-assertions.d.ts.map

package/dist/content-assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-assertions.d.ts","sourceRoot":"","sources":["../src/content-assertions.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAED,gGAAgG;AAChG,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AA8DD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAMtF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAKhF"}

package/dist/content-assertions.js

@@ -0,0 +1,75 @@
+/** A difference in valid buffer contents, distinct from malformed inputs or reader failures. */
+export class ContentMismatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ContentMismatchError";
+    }
+}
+function buffer(value, label) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !("length" in value) ||
+        typeof value.length !== "number" ||
+        !Number.isSafeInteger(value.length) ||
+        value.length < 0 ||
+        !("at" in value) ||
+        typeof value.at !== "function") {
+        throw new TypeError(`${label} must provide a nonnegative integer length and at(index).`);
+    }
+    return value;
+}
+function numberAt(value, index, label) {
+    const element = value.at(index);
+    if (typeof element !== "number") {
+        throw new TypeError(`${label}.at(${index}) must return a number within its length.`);
+    }
+    return element;
+}
+function display(value) {
+    return Object.is(value, -0) ? "-0" : String(value);
+}
+function assertBufferContents(actual, expected, label) {
+    if (actual.length !== expected.length) {
+        throw new ContentMismatchError(`${label} length: expected ${expected.length}, received ${actual.length}.`);
+    }
+    for (let index = 0; index < actual.length; index += 1) {
+        const received = numberAt(actual, index, `Received ${label}`);
+        const wanted = numberAt(expected, index, `Expected ${label}`);
+        if (!Object.is(received, wanted)) {
+            throw new ContentMismatchError(`${label} differs at index ${index}: expected ${display(wanted)}, received ${display(received)} (length ${actual.length}).`);
+        }
+    }
+}
+function mesh(value, label) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !("positions" in value) ||
+        !("indices" in value)) {
+        throw new TypeError(`${label} must provide positions and indices buffers.`);
+    }
+    return {
+        positions: buffer(value.positions, `${label} positions`),
+        indices: buffer(value.indices, `${label} indices`),
+    };
+}
+/**
+ * Asserts exact ordered numeric contents through length and at(index), without copying storage.
+ * Uses Object.is regardless of storage type: NaN equals NaN; signed zero differs.
+ * Throws ContentMismatchError for the first difference, TypeError for malformed inputs, and
+ * preserves reader failures. This assertion does not establish valid manufacturing geometry.
+ */
+export function assertEqualBuffer(actual, expected) {
+    assertBufferContents(buffer(actual, "Received buffer"), buffer(expected, "Expected buffer"), "Buffer");
+}
+/**
+ * Asserts identical positions and indices with buffer-specific mismatch diagnostics.
+ * Ignores metadata. Geometrically equivalent meshes with different triangulation or ordering can fail.
+ * Shares assertEqualBuffer's numeric equality, validation and error behavior without copying storage.
+ */
+export function assertEqualMesh(actual, expected) {
+    const received = mesh(actual, "Received mesh");
+    const wanted = mesh(expected, "Expected mesh");
+    assertBufferContents(received.positions, wanted.positions, "Mesh position buffer");
+    assertBufferContents(received.indices, wanted.indices, "Mesh index buffer");
+}
+//# sourceMappingURL=content-assertions.js.map

package/dist/content-assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-assertions.js","sourceRoot":"","sources":["../src/content-assertions.ts"],"names":[],"mappings":"AAYA,gGAAgG;AAChG,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,SAAS,MAAM,CAAC,KAAc,EAAE,KAAa;IAC3C,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC;QACpB,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAChC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC;QACnC,KAAK,CAAC,MAAM,GAAG,CAAC;QAChB,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC;QAChB,OAAO,KAAK,CAAC,EAAE,KAAK,UAAU,EAC9B,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,2DAA2D,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,KAAsB,CAAC;AAChC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAoB,EAAE,KAAa,EAAE,KAAa;IAClE,MAAM,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,OAAO,KAAK,2CAA2C,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,OAAO,CAAC,KAAa;IAC5B,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,oBAAoB,CAAC,MAAqB,EAAE,QAAuB,EAAE,KAAa;IACzF,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,oBAAoB,CAC5B,GAAG,KAAK,qBAAqB,QAAQ,CAAC,MAAM,cAAc,MAAM,CAAC,MAAM,GAAG,CAC3E,CAAC;IACJ,CAAC;IACD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,KAAK,EAAE,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,YAAY,KAAK,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,oBAAoB,CAC5B,GAAG,KAAK,qBAAqB,KAAK,cAAc,OAAO,CAAC,MAAM,CAAC,cAAc,OAAO,CAAC,QAAQ,CAAC,YAAY,MAAM,CAAC,MAAM,IAAI,CAC5H,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,IAAI,CAAC,KAAc,EAAE,KAAa;IACzC,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,CAAC,CAAC,WAAW,IAAI,KAAK,CAAC;QACvB,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,EACrB,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,8CAA8C,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,KAAK,YAAY,CAAC;QACxD,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,KAAK,UAAU,CAAC;KACnD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAqB,EAAE,QAAuB;IAC9E,oBAAoB,CAClB,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACjC,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC,EACnC,QAAQ,CACT,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB,EAAE,QAAqB;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC/C,oBAAoB,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,sBAAsB,CAAC,CAAC;IACnF,oBAAoB,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;AAC9E,CAAC"}

package/dist/content-matchers.d.ts

@@ -0,0 +1,12 @@
+import { type BufferContent, type MeshContent } from "./content-assertions.js";
+interface ContentMatcherResult {
+    readonly pass: boolean;
+    readonly message: () => string;
+}
+/** Optional expect.extend adapters; only content mismatches become failed matcher results. */
+export declare const contentMatchers: {
+    toEqualBuffer(received: BufferContent, expected: BufferContent): ContentMatcherResult;
+    toEqualMesh(received: MeshContent, expected: MeshContent): ContentMatcherResult;
+};
+export {};
+//# sourceMappingURL=content-matchers.d.ts.map

package/dist/content-matchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-matchers.d.ts","sourceRoot":"","sources":["../src/content-matchers.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AAEjC,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC;CAChC;AAYD,8FAA8F;AAC9F,eAAO,MAAM,eAAe;4BACF,aAAa,YAAY,aAAa,GAAG,oBAAoB;0BAM/D,WAAW,YAAY,WAAW,GAAG,oBAAoB;CAMhF,CAAC"}

package/dist/content-matchers.js

@@ -0,0 +1,22 @@
+import { assertEqualBuffer, assertEqualMesh, ContentMismatchError, } from "./content-assertions.js";
+function match(assertion, equalMessage) {
+    try {
+        assertion();
+        return { pass: true, message: () => equalMessage };
+    }
+    catch (error) {
+        if (!(error instanceof ContentMismatchError))
+            throw error;
+        return { pass: false, message: () => error.message };
+    }
+}
+/** Optional expect.extend adapters; only content mismatches become failed matcher results. */
+export const contentMatchers = {
+    toEqualBuffer(received, expected) {
+        return match(() => assertEqualBuffer(received, expected), "Expected buffer contents to differ, but they match.");
+    },
+    toEqualMesh(received, expected) {
+        return match(() => assertEqualMesh(received, expected), "Expected mesh contents to differ, but they match.");
+    },
+};
+//# sourceMappingURL=content-matchers.js.map

package/dist/content-matchers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-matchers.js","sourceRoot":"","sources":["../src/content-matchers.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GAGrB,MAAM,yBAAyB,CAAC;AAOjC,SAAS,KAAK,CAAC,SAAqB,EAAE,YAAoB;IACxD,IAAI,CAAC;QACH,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY,EAAE,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,oBAAoB,CAAC;YAAE,MAAM,KAAK,CAAC;QAC1D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IACvD,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,aAAa,CAAC,QAAuB,EAAE,QAAuB;QAC5D,OAAO,KAAK,CACV,GAAG,EAAE,CAAC,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAC3C,qDAAqD,CACtD,CAAC;IACJ,CAAC;IACD,WAAW,CAAC,QAAqB,EAAE,QAAqB;QACtD,OAAO,KAAK,CACV,GAAG,EAAE,CAAC,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACzC,mDAAmD,CACpD,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/docs/guides/package.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