@metamesh/testkit 0.17.0 → 0.18.0

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":"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"}

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