@metamesh/testkit 0.0.0-bootstrap.0 → 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,225 @@
+# @metamesh/testkit
+
+## 0.13.0
+
+### Minor Changes
+
+- 2ebe03f: Ship exact-version offline documentation and a development-only authoring CLI for semantic
+  checking, generation, captured geometry inspection, and explicit Chromium previews. Use exact
+  package versions in documentation metadata and reject unsupported authoring artifact formats.
+  Provide generated command help and strict per-command argument validation, and enforce semantic
+  checking even when the consumer's TypeScript configuration disables it.
+
+  Publish lightweight model and Generator testing helpers as `@metamesh/testkit`. Move the
+  `metamesh` executable and Node authoring API into `@metamesh/cli`, which owns compiler, bundler,
+  renderer, and browser dependencies. Remove the former package name and authoring entry from
+  Testkit without compatibility aliases.
+
+- 7e1b75d: Simplify modeling authoring with `polygon` construction, shared bounds and vector text fitting,
+  Section patterns, pure pattern transforms, and explicit profile closure and part layout helpers.
+  Zero-sized round, chamfer, and smooth treatments preserve untreated geometry.
+
+  Replace the public geometry vocabulary with `Vector2`, `Vector3`, `Contour`, `Polygon`, and
+  `Region`, and use canonical `Bounds2` and `Bounds3` throughout. Remove retired constructor and
+  type names. Bundles require runtime major 5 and the generation realm uses protocol 5; older
+  runtime packages reject before execution. The package envelope remains format 4.
+
+### Patch Changes
+
+- Updated dependencies [2ebe03f]
+- Updated dependencies [7e1b75d]
+- Updated dependencies [3139981]
+  - @metamesh/modeling@0.13.0
+  - @metamesh/generator-sdk@0.13.0
+
+## 0.12.0
+
+### Patch Changes
+
+- Updated dependencies [45d2617]
+  - @metamesh/modeling@0.12.0
+  - @metamesh/generator-sdk@0.12.0
+
+## 0.11.0
+
+### Minor Changes
+
+- b5da778: Replace prepare/build with typed generation programs, optional computed values and authoritative
+  part placement. Add isolated session caches and deferred geometry with explicit snapshot ownership.
+  Expose immutable fluent Solid and Section methods for transforms, subtraction, finishing, and
+  Section-to-Solid construction, replacing the corresponding standalone operations and public
+  context facade. Generator packages require format 4 and runtime 4; previous executable contracts are unsupported.
+
+### Patch Changes
+
+- 88f5336: Correct immutable cache comparisons, recapture mutable mesh inputs on every run, and preserve
+  session ownership during concurrent Testkit operations. Reject unsupported hidden data fields
+  instead of silently dropping them, and reuse native operation contexts during recipe evaluation.
+- Updated dependencies [88f5336]
+- Updated dependencies [6c90e9d]
+- Updated dependencies [b5da778]
+- Updated dependencies [60c458f]
+- Updated dependencies [d69836c]
+- Updated dependencies [bfb7a63]
+- Updated dependencies [a1f5aba]
+- Updated dependencies [d4ffce7]
+  - @metamesh/modeling@0.11.0
+  - @metamesh/generator-sdk@0.11.0
+
+## 0.10.0
+
+### Minor Changes
+
+- 9d7052c: Separate parameter values from local UI metadata, add strict parameter-document diagnostics and a generated JSON Schema, and rename the side-profile and contour APIs. Generator packages and modules now require format 3 and runtime 3.0.0.
+
+### Patch Changes
+
+- Updated dependencies [0eea1b4]
+- Updated dependencies [9d7052c]
+- Updated dependencies [cf597bd]
+  - @metamesh/generator-sdk@0.10.0
+  - @metamesh/modeling@0.10.0
+
+## 0.9.0
+
+### Patch Changes
+
+- Updated dependencies [e405876]
+- Updated dependencies [e405876]
+  - @metamesh/generator-sdk@0.9.0
+  - @metamesh/modeling@0.9.0
+
+## 0.8.0
+
+### Minor Changes
+
+- bf1abe4: Add circular baselines to prepared vector text and Generator text services. Shaped glyphs and attached marks rotate rigidly around a millimetre radius, preserving kerning, ligatures, exact curve bounds and logical advances. Circular text is limited to one line, baseline vertical alignment, less than one revolution, and outlines that stay clear of the circle's center axis.
+- bf1abe4: Complete solid splitting, plane clipping, Section hull/component/simplification operations, minimum-distance
+  queries and inspection facts. Add optional bounded geometric solid
+  validation at build/export boundaries and a pure uniform-density volume centroid helper.
+  Reuse immutable native inspection facts within a build and fresh owned topology analysis during
+  solid validation; share checks for identical buffer ranges without trusting mutable external facts.
+
+  Unify SVG default/preset limits and strict preset metadata checks. Preserve structured validation
+  codes and nested paths, add physical mesh assertions, and require runtime 2.1 for the current host
+  surface and issue metadata.
+
+### Patch Changes
+
+- Updated dependencies [bf1abe4]
+- Updated dependencies [bf1abe4]
+- Updated dependencies [bf1abe4]
+- Updated dependencies [bf1abe4]
+- Updated dependencies [bf1abe4]
+  - @metamesh/modeling@0.8.0
+  - @metamesh/generator-sdk@0.8.0
+
+## 0.7.0
+
+### Patch Changes
+
+- Updated dependencies [b1b97b9]
+- Updated dependencies [b1b97b9]
+  - @metamesh/modeling@0.7.0
+  - @metamesh/generator-sdk@0.7.0
+
+## 0.6.0
+
+### Minor Changes
+
+- Run prepare/build through the shared Modeling engine. Remove direct native-kernel and generate bypass APIs; add direct preparation probes, finalized-model execution, and synchronous mesh assertions for an explicit engine.
+
+## 0.5.2
+
+### Patch Changes
+
+- Updated dependencies [02a1692]
+  - @metamesh/generator-sdk@0.5.2
+  - @metamesh/geometry@0.5.2
+
+## 0.5.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @metamesh/generator-sdk@0.5.1
+  - @metamesh/geometry@0.5.1
+
+## 0.5.0
+
+### Minor Changes
+
+- 0dc29c2: Add the portable numeric `curve-resolution` parameter role for model-owned physical curve
+  tolerance, with strict millimetre units, positive bounds, and one role per definition. Require
+  runtime 1.3.0 or later for packages declaring the role. Geometry and
+  Testkit follow the coordinated fixed Preview package release.
+
+### Patch Changes
+
+- Updated dependencies [0dc29c2]
+- Updated dependencies [0dc29c2]
+  - @metamesh/generator-sdk@0.5.0
+  - @metamesh/geometry@0.5.0
+
+## 0.4.0
+
+### Minor Changes
+
+- ad3bb49: Strengthen generator geometry with correct concave sweep caps, bounded region aggregation,
+  consistent finite input checks, protected copied-mesh scope exits, and shared primitive/extrusion
+  sampling. Add scoped hull, Minkowski sum, projection, slicing, and region revolution.
+
+  Compiled `MeshPart` now exposes `{ id, positions, indices, color? }`, directly compatible with SDK
+  `GeneratedPart`. Pass explicit `{ degrees }` or `{ radians }` to `rotationTransform3`, and rounded
+  rectangle sampling options as `{ segmentsPerCorner }` or `{ resolution }`.
+
+  Add `definePreparedGeneratorModule` for bounded, one-use validation/generation preparation while
+  preserving the five format-1 module exports. Authored `/v1` keeps its existing signatures and shares
+  the pure validation and sampling implementation with compiled modeling.
+
+### Patch Changes
+
+- Updated dependencies [ad3bb49]
+  - @metamesh/geometry@0.4.0
+  - @metamesh/generator-sdk@0.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- e87357e: Add direct catalog-font text geometry and matching metrics through prepared synchronous font
+  scopes. Share vector layout with SVG outlining, use natural font line spacing by default, and
+  make whitespace measurable. Nonzero tracking disables optional ligatures to match browser text.
+  Compiled Generators can receive font services during validation as well as generation; packages
+  declaring font parameters require runtime 1.2.0. Text geometry requires an exact font selection;
+  host text services expose shared vector layout. Browser editing uses prepared vector measurements.
+  Compiled module calls require explicit execution services for validation and generation.
+
+  Use the shared transform functions for both 2D sections and 3D solids. Reuse core-validated immutable
+  loops, polygons, and regions when winding and tolerance policies match, avoiding repeated topology
+  validation without changing tessellation or accepting unvalidated caller geometry.
+
+### Patch Changes
+
+- Updated dependencies [e87357e]
+  - @metamesh/geometry@0.3.0
+  - @metamesh/generator-sdk@0.3.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 8b4e918: Add immutable font selections, font parameters and prepared text services, the optional Geometry
+  text engine, and reproducible font test services.
+
+### Patch Changes
+
+- Updated dependencies [8b4e918]
+  - @metamesh/generator-sdk@0.2.0
+  - @metamesh/geometry@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public Preview release of the Generator contract assertions.

package/README.md

@@ -1,6 +1,113 @@
-# @metamesh/testkit
+# `@metamesh/testkit`
 
-This inert prerelease enrolls the npm package name for trusted publishing.
-It contains no executable code, dependencies, or public exports.
-Publish enrollment only with the explicit bootstrap dist-tag; the intended
-MetaMesh release is prepared and reviewed separately.
+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 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
+
+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.
+
+## 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/assertions.d.ts

@@ -0,0 +1,20 @@
+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;
+/** 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;
+/** 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 engine parts after omitting measurement facts from their strict wire DTOs.
+ * Runs mesh reconstruction/finalization synchronously using the supplied engine.
+ */
+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[]>;
+//# sourceMappingURL=assertions.d.ts.map

package/dist/assertions.d.ts.map

@@ -0,0 +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,EAAE,MAAM,oBAAoB,CAAC;AAClE,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"}

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,113 @@
+# `@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 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
+
+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.
+
+## 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).