@metamesh/generator-sdk 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @metamesh/generator-sdk
 
+## 0.20.0
+
+### Minor Changes
+
+- fe33c89: Give modeling operations, pure geometry values, numerical kernels, and mechanical calculations distinct public entry points. Import fluent values from `/geometry`, tuple and matrix kernels from `/geometry/math`, and mechanical calculations from `/geometry/mechanical`. Remove root geometry factory re-exports and ambient `matchProfiles` and thread-preflight wrappers; pure preparation accepts explicit resolution and limits exposed by the generation context.
+
+  Bounds extrema and pattern/attachment placements return fluent values. Construct anchors with one options object, project fluent vectors onto planes, and multiply raw matrices with `multiplyTransform3(left, right)`. Remove retired exports and update the SDK, CLI, Studio authoring environment, and consumers without compatibility aliases.
+
+- 5654590: Give every public declaration exactly one import path. Shared types remain available from their owning module; consuming entries reference those types without re-exporting them. Import all export writers from `@metamesh/modeling/export`; remove the format subpaths. Import SDK font selections from `/fonts` and Generator presets from the SDK root. Remove alternate import metadata and enforce unique source and published declaration ownership without compatibility aliases.
+- 6455ccf: Support chamfered ends on twisted extrusions, measuring normal-section setbacks on the finished
+  helical walls and preserving corner and hole correspondence. Ordinary extrusions retain their
+  native fast path. Enabled twisted end treatments support chamfers; other treatments and taper
+  with ends remain unsupported.
+
+  Breaking: replace extrusion `scaleTop` with `scale` and `divisions` with positive `slices`, counting
+  longitudinal intervals. Loft `slices` also counts intervals per supplied gap. End treatments add
+  required rings to the extrusion's requested grid. Open sweep scalar and XY `scale` now taper from
+  one to the final scale by path length; station arrays retain explicit scale control. Scale in the
+  profile's local axes before twisting, and refine untwisted sweep deformation by physical resolution.
+
+  Compiled Generators require execution protocol and runtime major 13. Rebuild packages for the new
+  binding; package format 5 is unchanged.
+
+### Patch Changes
+
+- Updated dependencies [fe33c89]
+- Updated dependencies [d5dd213]
+- Updated dependencies [ae34a4f]
+- Updated dependencies [d5dd213]
+- Updated dependencies [52e4e07]
+- Updated dependencies [5654590]
+- Updated dependencies [382d312]
+- Updated dependencies [6455ccf]
+  - @metamesh/modeling@0.20.0
+
+## 0.19.0
+
+### Minor Changes
+
+- c9de510: Extend straight extrusion end finishing to concave outlines, holes, and disconnected regions.
+  Add independent-solid `join` with a feature datum and a smooth (default) or straight width/height
+  transition against validated planar, angled, and curved sampled support patches. Both profiles use
+  the same support, collar, and whole-volume containment proofs.
+
+  Breaking: compiled Generators require Modeling runtime major 12. Rebuild packages for the new
+  host contract; old compiled runtimes are rejected. Joining preserves the supplied operands and
+  does not promise a circular fillet radius or perform automatic placement.
+
+  Replace named lazy `computed` readers with eager `memo(fn, ...args)` values. Stable pure helpers
+  reuse immutable arguments and tracked current params/context reads, with bounded recent histories
+  and native geometry retention. Update Studio diagnostics to warn about fresh function identities.
+  All authored and compiled callers must use the new API; there is no compatibility surface.
+
+- de3d234: Add runtime-neutral STL, 3MF, and GLB export under `@metamesh/modeling/export`, with isolated
+  format entry points and backpressure-aware streaming writers. All formats consume captured local
+  geometry, placement, and appearance, with independent limits, cancellation, and structured
+  information-loss diagnostics. Standard 3MF color groups carry appearance, while base materials
+  and multiproperties retain explicit material identities independently of RGB values. These
+  properties do not assign slicer filaments or physical device trays. Add `mesh.render()` for
+  shared crease-aware display buffers that preserve exact triangle coordinates.
+
+  Breaking: remove `export3mf` and export types from `/engine`, remove SDK export request protocols
+  and `toWorldMeshes`, and return owned `Uint8Array` bytes with format metadata from the shared
+  exporters. Studio uses one export worker for every format. CLI captures use format version 3;
+  replace `run --export-3mf` with `metamesh export RUN_DIRECTORY --format 3mf --output model.3mf`.
+  Captured-run export also supports STL and GLB without rerunning source. No legacy export paths
+  or capture readers are retained.
+
+### Patch Changes
+
+- Updated dependencies [c9de510]
+- Updated dependencies [de3d234]
+  - @metamesh/modeling@0.19.0
+
 ## 0.18.0
 
 ### Minor Changes

package/README.md

@@ -1,14 +1,15 @@
 # `@metamesh/generator-sdk`
 
-Define typed controls, presets, and portable contracts for MetaMesh Generators. Use one definition
-for the editing interface, saved parameter values, and model execution.
+Turn a parametric model into a reusable MetaMesh Generator. Define its controls and presets once,
+then use that definition to infer parameter types, validate saved values, and connect the model
+to an editing interface.
 
 > **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
 > same minor line.
 
 ## Installation
 
-For the modeling example below, install matching SDK and Modeling releases:
+Install matching SDK and Modeling releases to build the Generator below:
 
 ```bash
 pnpm add @metamesh/generator-sdk @metamesh/modeling
@@ -18,13 +19,15 @@ The package publishes ES modules only. Use Node.js 24 or newer. TypeScript consu
 TypeScript 6.0 or newer, `strict` checking, and `NodeNext` or `Bundler` module resolution.
 Browser hosts need an ES2023-compatible runtime; the SDK's data contracts require no WebAssembly.
 
-The SDK can also be used alone for definitions, parameter handling, and package validation.
-Only its optional `/modeling` adapter imports the Modeling runtime.
+You can also use the SDK on its own for definitions, parameter handling, and package validation.
+The optional `/modeling` adapter connects it to Modeling; your application supplies the interface
+and execution host.
 
 ## Define controls
 
-A Generator combines serializable metadata with a synchronous model program. This module defines
-a sleeve, infers its parameter types, and checks the relationship between its diameters:
+A Generator combines a definition with a synchronous model program. This example makes a sleeve
+with two diameter controls. Parameter types come from the definition, and an assertion checks
+that the bore fits inside the outer wall:
 
 ```ts
 import { defineGenerator } from "@metamesh/generator-sdk";
@@ -57,21 +60,16 @@ export default defineGeneratorModel(definition, ({ params, assert, part }) => {
 });
 ```
 
-The adapter binds the definition to the model and produces a Generator module. Use
-`defineGeneratorModule({ definition, program })` to bind an existing program. A Generator runtime
-is itself a Modeling program: engines and direct model tests execute `runtime`.
-Format 5 carries the callback and identity in one object; nested
-format-4 runtimes are unsupported. Hosts normalize parameters, prepare assets,
-and execute the model; they own the forms, viewing, persistence, and export.
-Add named, complete starting values with `definePresets(definition, presets)`.
-
-`defineGenerator` validates structural and semantic metadata immediately; `definePresets` validates
-preset metadata and complete canonical parameter values. Invalid input throws
-`GeneratorPackageValidationError` at declaration. Both helpers retain the supplied object or array
-and its inferred literal types. Inline parameter, editor, choice, and preset objects receive
-TypeScript excess-property checks. Structural typing can hide extra fields in variables or generic
-factories; runtime validation checks those fields too. These helpers validate metadata and values,
-not model geometry or cross-parameter assertions.
+`defineGeneratorModel` binds the definition to the model and infers its parameters and services.
+If you already have a program, use `defineGeneratorModule({ definition, program })`. The resulting
+runtime is a Modeling program that an engine or model test can execute directly.
+Add named starting configurations with `definePresets(definition, presets)`; each preset supplies
+a complete parameter map.
+
+Definitions and presets contain serializable data, without callbacks. Hosts normalize parameters,
+prepare assets, and execute the model. They also own forms, viewing, persistence, and export.
+Generator modules use format 5, which carries the callback and identity in one object;
+nested format-4 runtimes are unsupported.
 
 ## Generator capabilities
 
@@ -82,43 +80,57 @@ not model geometry or cross-parameter assertions.
 | Parameters and presets | Inferred TypeScript types, defaults, recovering normalization, strict codecs, and complete serializable presets. |
 | Host integration       | Validated package manifests, module execution, Worker messages, and incremental mesh delivery.                   |
 
-Definitions and presets contain data, not callbacks. Conditional visibility changes the editing
-interface; hidden values remain saved and still require validation. Cross-parameter constraints
-belong in the model's assertions.
+Conditional visibility changes which controls appear. Hidden values remain saved and still
+require validation. Put constraints between parameters in the model's assertions.
+
+## Validate definitions and values
+
+`defineGenerator` checks the definition as soon as you declare it. `definePresets` checks preset
+metadata and complete canonical values. Invalid declarations throw
+`GeneratorPackageValidationError`. These helpers retain the supplied object or array and its
+inferred literal types; they don't execute geometry or model assertions.
+
+Inline parameter, editor, choice, and preset objects receive TypeScript excess-property checks.
+Runtime validation also catches extra fields that structural typing can hide in variables or
+generic factories.
 
 Use `normalizeParameters` to recover saved values: it drops unknown keys, restores defaults, and
-clamps numbers. At strict boundaries, `createParamCodec(definition)` rejects incomplete, unknown, invalid, or
-noncanonical values. The [parameter guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx)
+clamps numbers. Use `createParamCodec(definition)` when inputs must already be complete and
+canonical; it rejects missing or unknown fields and invalid values. The
+[parameter guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx)
 covers controls, conditions, and validation.
 
-Use the codec's `parse()` to throw on invalid input, or `safeParse()` for a discriminated result.
-Failure produces issues without substitute parameters. Codec issues use the shared `ParameterIssue`
-shape: `parameterId` names the control, and an optional `path` is relative to that control's value.
-Hosts can pass the issues directly to `aggregateParameterIssues`.
+Use the codec's `parse()` to throw on invalid input, or `safeParse()` for a result you can check
+without catching an exception. A failed parse reports issues without substitute parameters. Each `ParameterIssue` names
+a control with `parameterId`; an optional `path` addresses a field within that control's value.
+Hosts can pass these issues directly to `aggregateParameterIssues`.
+
+## Execute and deliver a model
 
 `executeGenerator` always validates its single `parameters` map against the current definition.
-Hosts may validate before loading assets, but execution does not accept a prior parse result as a
-validation bypass. Modeling hosts use `parseGeneratorModel(value, definition)` from `/modeling`
-to validate an unknown module and infer its executable `GeneratorModel<typeof definition>` type.
-Pass the default export itself for local entries that also export their definition; packaged
-namespaces contain only the default export. The runtime-neutral `parseGeneratorModule` remains
-available from `/runtime`. Invalid envelopes throw `TypeError`. Package validation exposes MetaMesh
-issues and errors, keeping its schema-library adapters private.
-
-Worker model statistics use `signedVolume` in mm³. `generateMs` measures the engine run;
-`timings.totalMs` measures the host workflow and includes stages outside the engine.
-`byteCount` counts finalized world-space position and index buffer bytes, counting shared buffers
-once; it does not measure the local buffers transferred by a Worker.
-Timing stages are optional; hosts report the phases they actually measure. The parameter-processing
-stage is `paramsMs` and finalization is `finalizeMs`.
-
-For Worker hosts, `/modeling` supplies `ModelDeliveryEncoder` and `toWorldMeshes`; `/runtime`
-supplies `PartDeliveryDecoder`. Transfers carry local buffers under `geometry`, with placement
-beside them. Decode resource references before application use and convert to world meshes before
-export. Receiving hosts own the buffers and keep them immutable and attached.
+Hosts can validate before loading assets, but execution still checks the supplied values.
+Modeling hosts use `parseGeneratorModel(value, definition)` from `/modeling` to validate a loaded
+module and infer its executable `GeneratorModel<typeof definition>` type. Pass the default export
+itself for local entries that also export their definition; packaged namespaces contain only the
+default export. Use `parseGeneratorModule` from `/runtime` when you don't need the Modeling adapter.
+Invalid module envelopes throw `TypeError`; package validation reports MetaMesh issues and errors.
+
+For Worker hosts, `/modeling` supplies `ModelDeliveryEncoder`; `/runtime` supplies `PartDeliveryDecoder`.
+Transfers carry local buffers under `geometry`, with placement beside them. Decode resource
+references before application use or export. Receiving hosts own the buffers and keep them immutable
+and attached.
+
+Model statistics use `signedVolume` in mm³. `generateMs` measures the engine run;
+`timings.totalMs` covers the host workflow, including stages outside the engine. Hosts report only
+the timing stages they measure, using `paramsMs` for parameter processing and `finalizeMs` for
+finalization. `byteCount` counts finalized world-space position and index buffer bytes, counting
+shared buffers once; it doesn't measure the local buffers transferred by a Worker.
 
 ## API entry points
 
+Each public type and function has one import path. Import `FontSelection` and `isFontSelection`
+from `/fonts`, and `GeneratorPreset` from the package root.
+
 | Import                               | Responsibility                                                      |
 | ------------------------------------ | ------------------------------------------------------------------- |
 | `@metamesh/generator-sdk`            | Definitions, presets, inferred types, and module authoring.         |

package/dist/authoring.d.ts

@@ -3,11 +3,20 @@ import type { GeneratorDefinition, ParameterDefinition } from "./parameters/defi
 type DefinitionParameters<P extends readonly ParameterDefinition[]> = readonly ParameterDefinition[] | {
     readonly [Index in keyof P]: ParameterDefinition;
 };
-/** Validates metadata while preserving its identity and literal control types. Invalid definitions throw. */
+/**
+ * Validates Generator metadata while preserving literal control types; invalid definitions throw.
+ *
+ * @param definition - Serializable controls and metadata; returned unchanged after validation.
+ */
 export declare function defineGenerator<const D extends GeneratorDefinition>(definition: D & Omit<GeneratorDefinition, "parameters"> & {
     readonly parameters: DefinitionParameters<NoInfer<D["parameters"]>>;
 }): D;
-/** Validates complete, canonical preset values and metadata while preserving the supplied array and literal types. */
+/**
+ * Validates preset metadata and complete canonical values while preserving literal types.
+ *
+ * @param definition - Definition whose complete parameter map each preset must supply.
+ * @param presets - Preset values and metadata; returned without copying.
+ */
 export declare function definePresets<const D extends GeneratorDefinition, const Presets extends readonly GeneratorPreset<NoInfer<D>>[]>(definition: D, presets: Presets & readonly GeneratorPreset<NoInfer<D>>[]): Presets;
 export {};
 //# sourceMappingURL=authoring.d.ts.map

package/dist/authoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAK5F,KAAK,oBAAoB,CAAC,CAAC,SAAS,SAAS,mBAAmB,EAAE,IAChE,SAAS,mBAAmB,EAAE,GAAG;IAAE,QAAQ,EAAE,KAAK,IAAI,MAAM,CAAC,GAAG,mBAAmB;CAAE,CAAC;AAExF,6GAA6G;AAC7G,wBAAgB,eAAe,CAAC,KAAK,CAAC,CAAC,SAAS,mBAAmB,EACjE,UAAU,EAAE,CAAC,GACX,IAAI,CAAC,mBAAmB,EAAE,YAAY,CAAC,GAAG;IACxC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CACrE,GACF,CAAC,CAGH;AAED,sHAAsH;AACtH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,CAAC,SAAS,mBAAmB,EACnC,KAAK,CAAC,OAAO,SAAS,SAAS,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAC5D,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAGnF"}
+{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAK5F,KAAK,oBAAoB,CAAC,CAAC,SAAS,SAAS,mBAAmB,EAAE,IAChE,SAAS,mBAAmB,EAAE,GAAG;IAAE,QAAQ,EAAE,KAAK,IAAI,MAAM,CAAC,GAAG,mBAAmB;CAAE,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,CAAC,SAAS,mBAAmB,EACjE,UAAU,EAAE,CAAC,GACX,IAAI,CAAC,mBAAmB,EAAE,YAAY,CAAC,GAAG;IACxC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CACrE,GACF,CAAC,CAGH;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,CAAC,SAAS,mBAAmB,EACnC,KAAK,CAAC,OAAO,SAAS,SAAS,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAC5D,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAGnF"}

package/dist/authoring.js

@@ -1,11 +1,20 @@
 import { validateGeneratorPresets } from "./generator-package/validate-manifest.js";
 import { parseGeneratorDefinition } from "./validation/parse-definition.js";
-/** Validates metadata while preserving its identity and literal control types. Invalid definitions throw. */
+/**
+ * Validates Generator metadata while preserving literal control types; invalid definitions throw.
+ *
+ * @param definition - Serializable controls and metadata; returned unchanged after validation.
+ */
 export function defineGenerator(definition) {
     parseGeneratorDefinition(definition);
     return definition;
 }
-/** Validates complete, canonical preset values and metadata while preserving the supplied array and literal types. */
+/**
+ * Validates preset metadata and complete canonical values while preserving literal types.
+ *
+ * @param definition - Definition whose complete parameter map each preset must supply.
+ * @param presets - Preset values and metadata; returned without copying.
+ */
 export function definePresets(definition, presets) {
     validateGeneratorPresets(definition, presets);
     return presets;

package/dist/authoring.js.map

@@ -1 +1 @@
-{"version":3,"file":"authoring.js","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAGpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAO5E,6GAA6G;AAC7G,MAAM,UAAU,eAAe,CAC7B,UAGG;IAEH,wBAAwB,CAAC,UAAU,CAAC,CAAC;IACrC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,aAAa,CAG3B,UAAa,EAAE,OAAyD;IACxE,wBAAwB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"authoring.js","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAGpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAO5E;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,UAGG;IAEH,wBAAwB,CAAC,UAAU,CAAC,CAAC;IACrC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAG3B,UAAa,EAAE,OAAyD;IACxE,wBAAwB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/docs/guides/authoring.md

@@ -10,10 +10,10 @@ If you need a working model first, follow [Build your first code Project](https:
 ```ts
 const { width, depth, height, holeDiameter, addHole } = params;
   const body = box({ size: [width, depth, height] });
-  if (!addHole) return [part("body", body)];
+  if (!addHole) return part("body", body);
   // Two extra millimetres clear the centered body's top and bottom faces.
   const bore = cylinder({ height: height + 2, diameter: holeDiameter, sizing: "face" });
-  return [part("body", body.subtract(bore))];
+  return part("body", body.subtract(bore));
 ```
 
 A plate is a useful starting example: its controls describe the finished size and an optional hole, while the source handles construction.
@@ -103,9 +103,9 @@ Use `@metamesh/generator-sdk` to define its controls and Generator module, and
 `@metamesh/modeling` for generation. Studio's virtual `@metamesh/project` import is specific to
 Studio and can't be copied into a local Node module.
 
-Follow [local authoring](https://metamesh.studio/docs/develop/agent-authoring#generator-entries) to check and run the
+Follow [local authoring](https://metamesh.studio/docs/develop/cli#generator-entries) to check and run the
 module with the CLI, inspect dimensions and named parts, and render the captured result. Add
-[Testkit checks](https://metamesh.studio/docs/develop/agent-authoring#test-models) when you need repeatable assertions for
+[Testkit checks](https://metamesh.studio/docs/develop/cli#test-models) when you need repeatable assertions for
 defaults, presets, supported bounds, or validation recovery. Keep those tests in your project's
 test runner; the CLI owns compilation and capture tools.
 

package/dist/docs/guides/package.md

@@ -1,14 +1,15 @@
 # `@metamesh/generator-sdk`
 
-Define typed controls, presets, and portable contracts for MetaMesh Generators. Use one definition
-for the editing interface, saved parameter values, and model execution.
+Turn a parametric model into a reusable MetaMesh Generator. Define its controls and presets once,
+then use that definition to infer parameter types, validate saved values, and connect the model
+to an editing interface.
 
 > **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
 > same minor line.
 
 ## Installation
 
-For the modeling example below, install matching SDK and Modeling releases:
+Install matching SDK and Modeling releases to build the Generator below:
 
 ```bash
 pnpm add @metamesh/generator-sdk @metamesh/modeling
@@ -18,13 +19,15 @@ The package publishes ES modules only. Use Node.js 24 or newer. TypeScript consu
 TypeScript 6.0 or newer, `strict` checking, and `NodeNext` or `Bundler` module resolution.
 Browser hosts need an ES2023-compatible runtime; the SDK's data contracts require no WebAssembly.
 
-The SDK can also be used alone for definitions, parameter handling, and package validation.
-Only its optional `/modeling` adapter imports the Modeling runtime.
+You can also use the SDK on its own for definitions, parameter handling, and package validation.
+The optional `/modeling` adapter connects it to Modeling; your application supplies the interface
+and execution host.
 
 ## Define controls
 
-A Generator combines serializable metadata with a synchronous model program. This module defines
-a sleeve, infers its parameter types, and checks the relationship between its diameters:
+A Generator combines a definition with a synchronous model program. This example makes a sleeve
+with two diameter controls. Parameter types come from the definition, and an assertion checks
+that the bore fits inside the outer wall:
 
 ```ts
 import { defineGenerator } from "@metamesh/generator-sdk";
@@ -57,21 +60,16 @@ export default defineGeneratorModel(definition, ({ params, assert, part }) => {
 });
 ```
 
-The adapter binds the definition to the model and produces a Generator module. Use
-`defineGeneratorModule({ definition, program })` to bind an existing program. A Generator runtime
-is itself a Modeling program: engines and direct model tests execute `runtime`.
-Format 5 carries the callback and identity in one object; nested
-format-4 runtimes are unsupported. Hosts normalize parameters, prepare assets,
-and execute the model; they own the forms, viewing, persistence, and export.
-Add named, complete starting values with `definePresets(definition, presets)`.
-
-`defineGenerator` validates structural and semantic metadata immediately; `definePresets` validates
-preset metadata and complete canonical parameter values. Invalid input throws
-`GeneratorPackageValidationError` at declaration. Both helpers retain the supplied object or array
-and its inferred literal types. Inline parameter, editor, choice, and preset objects receive
-TypeScript excess-property checks. Structural typing can hide extra fields in variables or generic
-factories; runtime validation checks those fields too. These helpers validate metadata and values,
-not model geometry or cross-parameter assertions.
+`defineGeneratorModel` binds the definition to the model and infers its parameters and services.
+If you already have a program, use `defineGeneratorModule({ definition, program })`. The resulting
+runtime is a Modeling program that an engine or model test can execute directly.
+Add named starting configurations with `definePresets(definition, presets)`; each preset supplies
+a complete parameter map.
+
+Definitions and presets contain serializable data, without callbacks. Hosts normalize parameters,
+prepare assets, and execute the model. They also own forms, viewing, persistence, and export.
+Generator modules use format 5, which carries the callback and identity in one object;
+nested format-4 runtimes are unsupported.
 
 ## Generator capabilities
 
@@ -82,43 +80,57 @@ not model geometry or cross-parameter assertions.
 | Parameters and presets | Inferred TypeScript types, defaults, recovering normalization, strict codecs, and complete serializable presets. |
 | Host integration       | Validated package manifests, module execution, Worker messages, and incremental mesh delivery.                   |
 
-Definitions and presets contain data, not callbacks. Conditional visibility changes the editing
-interface; hidden values remain saved and still require validation. Cross-parameter constraints
-belong in the model's assertions.
+Conditional visibility changes which controls appear. Hidden values remain saved and still
+require validation. Put constraints between parameters in the model's assertions.
+
+## Validate definitions and values
+
+`defineGenerator` checks the definition as soon as you declare it. `definePresets` checks preset
+metadata and complete canonical values. Invalid declarations throw
+`GeneratorPackageValidationError`. These helpers retain the supplied object or array and its
+inferred literal types; they don't execute geometry or model assertions.
+
+Inline parameter, editor, choice, and preset objects receive TypeScript excess-property checks.
+Runtime validation also catches extra fields that structural typing can hide in variables or
+generic factories.
 
 Use `normalizeParameters` to recover saved values: it drops unknown keys, restores defaults, and
-clamps numbers. At strict boundaries, `createParamCodec(definition)` rejects incomplete, unknown, invalid, or
-noncanonical values. The [parameter guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx)
+clamps numbers. Use `createParamCodec(definition)` when inputs must already be complete and
+canonical; it rejects missing or unknown fields and invalid values. The
+[parameter guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx)
 covers controls, conditions, and validation.
 
-Use the codec's `parse()` to throw on invalid input, or `safeParse()` for a discriminated result.
-Failure produces issues without substitute parameters. Codec issues use the shared `ParameterIssue`
-shape: `parameterId` names the control, and an optional `path` is relative to that control's value.
-Hosts can pass the issues directly to `aggregateParameterIssues`.
+Use the codec's `parse()` to throw on invalid input, or `safeParse()` for a result you can check
+without catching an exception. A failed parse reports issues without substitute parameters. Each `ParameterIssue` names
+a control with `parameterId`; an optional `path` addresses a field within that control's value.
+Hosts can pass these issues directly to `aggregateParameterIssues`.
+
+## Execute and deliver a model
 
 `executeGenerator` always validates its single `parameters` map against the current definition.
-Hosts may validate before loading assets, but execution does not accept a prior parse result as a
-validation bypass. Modeling hosts use `parseGeneratorModel(value, definition)` from `/modeling`
-to validate an unknown module and infer its executable `GeneratorModel<typeof definition>` type.
-Pass the default export itself for local entries that also export their definition; packaged
-namespaces contain only the default export. The runtime-neutral `parseGeneratorModule` remains
-available from `/runtime`. Invalid envelopes throw `TypeError`. Package validation exposes MetaMesh
-issues and errors, keeping its schema-library adapters private.
-
-Worker model statistics use `signedVolume` in mm³. `generateMs` measures the engine run;
-`timings.totalMs` measures the host workflow and includes stages outside the engine.
-`byteCount` counts finalized world-space position and index buffer bytes, counting shared buffers
-once; it does not measure the local buffers transferred by a Worker.
-Timing stages are optional; hosts report the phases they actually measure. The parameter-processing
-stage is `paramsMs` and finalization is `finalizeMs`.
-
-For Worker hosts, `/modeling` supplies `ModelDeliveryEncoder` and `toWorldMeshes`; `/runtime`
-supplies `PartDeliveryDecoder`. Transfers carry local buffers under `geometry`, with placement
-beside them. Decode resource references before application use and convert to world meshes before
-export. Receiving hosts own the buffers and keep them immutable and attached.
+Hosts can validate before loading assets, but execution still checks the supplied values.
+Modeling hosts use `parseGeneratorModel(value, definition)` from `/modeling` to validate a loaded
+module and infer its executable `GeneratorModel<typeof definition>` type. Pass the default export
+itself for local entries that also export their definition; packaged namespaces contain only the
+default export. Use `parseGeneratorModule` from `/runtime` when you don't need the Modeling adapter.
+Invalid module envelopes throw `TypeError`; package validation reports MetaMesh issues and errors.
+
+For Worker hosts, `/modeling` supplies `ModelDeliveryEncoder`; `/runtime` supplies `PartDeliveryDecoder`.
+Transfers carry local buffers under `geometry`, with placement beside them. Decode resource
+references before application use or export. Receiving hosts own the buffers and keep them immutable
+and attached.
+
+Model statistics use `signedVolume` in mm³. `generateMs` measures the engine run;
+`timings.totalMs` covers the host workflow, including stages outside the engine. Hosts report only
+the timing stages they measure, using `paramsMs` for parameter processing and `finalizeMs` for
+finalization. `byteCount` counts finalized world-space position and index buffer bytes, counting
+shared buffers once; it doesn't measure the local buffers transferred by a Worker.
 
 ## API entry points
 
+Each public type and function has one import path. Import `FontSelection` and `isFontSelection`
+from `/fonts`, and `GeneratorPreset` from the package root.
+
 | Import                               | Responsibility                                                      |
 | ------------------------------------ | ------------------------------------------------------------------- |
 | `@metamesh/generator-sdk`            | Definitions, presets, inferred types, and module authoring.         |

package/dist/docs/guides/parameters.md

@@ -87,7 +87,7 @@ and `items.ui.step`.
 A Font value contains the selected face and weight. Pass the whole value, rather than a family-name
 string, in `services.text.layout(text, { font, fontSize })` inside generation, then pass its layout to
 `textSection(layout)`. Studio loads declared fonts before generation. See the
-[text recipe](https://metamesh.studio/docs/develop/geometry-recipes#text-from-a-font-parameter) for the setup and offline
+[text recipe](https://metamesh.studio/docs/develop/svg-and-text#text-from-a-font-parameter) for the setup and offline
 limits.
 
 ## Show controls side by side
@@ -269,7 +269,7 @@ with a `parameterId` and positive `factor`, such as `{ "parameterId": "width", "
 Bindings describe the coordinate envelope; they never rescale the saved value. Without them,
 the editor displays percentages.
 
-Inside generation or a computed value, pass `params.crossSection` to
+Inside generation or a memo helper, pass `params.crossSection` to
 [`sampleContour()`](https://metamesh.studio/docs/reference/geometry/sampleContour) with physical `widthScale`,
 `heightScale`, and a millimetre resolution policy. It returns an immutable counterclockwise
 XY `Contour` without a duplicated seam, rejecting invalid sampled topology and exhausted budgets.
@@ -382,10 +382,10 @@ than your model's recommended minimum. A zero wall stops generation; a 0.5 mm wa
 with a warning. Choose that minimum for the model and manufacturing process. A failed edit leaves
 the last valid preview and its export available. Warnings allow a current model to generate and export.
 
-Checks follow JavaScript order: reading a computed value evaluates it when needed, and measuring
+Checks follow JavaScript order: `memo` calls run their helper on a cache miss, and measuring
 geometry evaluates its input first. Draft validation checks declarations and reached assertions
-without finalizing parts; it doesn't prove full geometric validity. Use optional `computed`
-values to reuse expensive layouts or shared calculations across unrelated edits. There is no
+without finalizing parts; it doesn't prove full geometric validity. Use optional `memo`
+calls to reuse expensive layouts or shared calculations across unrelated edits. There is no
 separate preparation callback.
 
 ## Test the definition as a contract
@@ -410,11 +410,10 @@ values with `model.ts`; check the workspace for source or cross-field errors bef
 
 
 
-**Keep executable rules in model.ts**
+**Controls describe; TypeScript decides**
 
-JSON mode defines serializable controls and visibility. Derived calculations, geometry checks, and
-  cross-field messages belong in `generate`; do not invent a second executable rules language inside
-  the Project definition.
+The definition declares inputs and visibility. Put derived values, geometry checks, and rules
+  between parameters in `generate`. Use `assert` or `warn` to identify the control to fix.