@metamesh/generator-sdk 0.17.0 → 0.19.0

package/dist/docs/guides/package.md

@@ -1,28 +1,38 @@
 # `@metamesh/generator-sdk`
 
-Turn a parametric model into a MetaMesh Generator. Define controls once, infer their TypeScript
-types, and use the same parameter contract for forms, saved values, and 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
 
+Install matching SDK and Modeling releases to build the Generator below:
+
 ```bash
-pnpm add @metamesh/generator-sdk
+pnpm add @metamesh/generator-sdk @metamesh/modeling
 ```
 
-The SDK is renderer-neutral. To build geometry in the example below, also install
-[`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/packages/modeling/README.md).
-Keep installed MetaMesh packages on the same exact release.
+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.
+Browser hosts need an ES2023-compatible runtime; the SDK's data contracts require no WebAssembly.
+
+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 definition describes the Generator and its editable parameters. Literal IDs and options give
-you exact parameter types:
+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";
+import { defineGeneratorModel } from "@metamesh/generator-sdk/modeling";
+import { tube } from "@metamesh/modeling";
 
 export const definition = defineGenerator({
   id: "sleeve",
@@ -34,29 +44,11 @@ export const definition = defineGenerator({
     { id: "boreDiameter", label: "Bore diameter", type: "number", default: 10, min: 1 },
   ],
 });
-```
-
-Definitions are serializable. Optional `ui` metadata describes grouping, visibility, hints, and
-editing increments. Number inputs and sliders share `type: "number"`; sliders add
-`ui.control: "slider"`, bounds, and `ui.step`. See the
-[parameter guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx)
-for the full set of controls.
-
-## Generate a model
-
-Add a synchronous generation program to the same module. The Modeling adapter infers controls,
-prepared services, and diagnostic parameter IDs from the definition:
-
-```ts
-import { defineGeneratorModel } from "@metamesh/generator-sdk/modeling";
-import { tube } from "@metamesh/modeling";
 
 export default defineGeneratorModel(definition, ({ params, assert, part }) => {
-  assert(
-    params.boreDiameter < params.outerDiameter,
-    "The bore must be smaller than the outside diameter.",
-    { parameterId: "boreDiameter" }
-  );
+  assert(params.boreDiameter < params.outerDiameter, "The bore must fit inside the sleeve.", {
+    parameterId: "boreDiameter",
+  });
   return part(
     "body",
     tube({
@@ -68,55 +60,99 @@ export default defineGeneratorModel(definition, ({ params, assert, part }) => {
 });
 ```
 
-Return a single `part(...)` or a readonly array of parts. The host normalizes parameters and prepares
-assets before generation. Modeling manages geometry, sessions, and snapshots; the SDK provides
-portable definitions, module envelopes, and validated runtime messages. Unsupported package formats
-reject before executable bytes are evaluated.
+`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
 
-The optional `/modeling` adapter imports Modeling's program helper; other SDK entry points remain
-independent of its runtime. Use `defineGeneratorModule` when binding an existing model program.
+| Area                   | Capabilities                                                                                                     |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Parameter values       | Numbers, booleans, choices and choice sets, text, colors, arrays, fonts, SVG, side profiles, and cross-sections. |
+| Editing metadata       | Labels, units, groups, descriptions, inline hints, sliders, paired controls, and conditional visibility.         |
+| 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.                   |
 
-## Work with saved values
+Conditional visibility changes which controls appear. Hidden values remain saved and still
+require validation. Put constraints between parameters in the model's assertions.
 
-Use `normalizeParameters` from `/parameters` to recover saved values: it drops unknown keys,
-restores missing or invalid values from defaults, and clamps numbers. At a trust boundary, use
-`createParamCodec(definition)` to reject incomplete, unknown, invalid, or noncanonical values.
-Both return fresh frozen parameter maps.
+## Validate definitions and values
 
-For definition editors, `/packages` provides `safeParseParameterDefinitionDocument` and structured
-issue paths. The included `@metamesh/generator-sdk/parameters.schema.json` supports offline
-completion; SDK validation also checks references, defaults, and cross-field rules.
+`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. 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 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 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
 
-| Import                               | Use it for                                       |
-| ------------------------------------ | ------------------------------------------------ |
-| `@metamesh/generator-sdk`            | Definitions, presets, and module authoring       |
-| `@metamesh/generator-sdk/parameters` | Defaults, saved values, and strict codecs        |
-| `@metamesh/generator-sdk/runtime`    | Module execution, mesh data, and Worker messages |
-| `@metamesh/generator-sdk/packages`   | Package, catalog, and installation parsing       |
-| `@metamesh/generator-sdk/fonts`      | Immutable font selection values                  |
-| `@metamesh/generator-sdk/modeling`   | Definition-inferred Modeling programs            |
+| Import                               | Responsibility                                                      |
+| ------------------------------------ | ------------------------------------------------------------------- |
+| `@metamesh/generator-sdk`            | Definitions, presets, inferred types, and module authoring.         |
+| `@metamesh/generator-sdk/modeling`   | Definition-inferred Modeling programs.                              |
+| `@metamesh/generator-sdk/parameters` | Defaults, saved values, normalization, and strict codecs.           |
+| `@metamesh/generator-sdk/runtime`    | Execution, generated geometry, and Worker protocols.                |
+| `@metamesh/generator-sdk/packages`   | Package, catalog, installation, and definition-document validation. |
+| `@metamesh/generator-sdk/fonts`      | Immutable font selection values.                                    |
 
-Incremental Worker hosts can use `GeneratedPartsDecoder` from `/runtime` to hydrate validated
-geometry resources while checking part metadata and aggregate limits on every delivery. Keep
-admitted buffers immutable and attached; call `clear()` when replacing the delivery source.
+`@metamesh/generator-sdk/parameters.schema.json` supports offline definition editing. The SDK
+validates references, defaults, and cross-field rules in addition to the structural schema.
 
 ## Documentation
 
-Resolve `@metamesh/generator-sdk/docs/manifest.json` from your project for exact-version Markdown
-guides and annotated declaration references. Document paths are relative to that manifest.
-With [`@metamesh/cli`](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/README.md)
-installed, `pnpm exec metamesh docs search "parameters"` searches the local index;
-`pnpm exec metamesh docs show sdk/guide/generator-modules` reads this package's authoring guide.
+Resolve `@metamesh/generator-sdk/docs/manifest.json` for exact-version Markdown guides and annotated
+API references. With [CLI](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/README.md) installed:
 
-- [Parameters and validation](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx) — controls, defaults, and diagnostics.
-- [Local authoring](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/create/author-locally.mdx) — the current Generator workflow.
-- [API source](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/index.ts) — exports, types, and implementation references.
+```bash
+pnpm exec metamesh docs search "parameters"
+pnpm exec metamesh docs show sdk/guide/generator-modules
+```
 
-Until the public documentation site launches, use these repository guides or
-[run the docs locally](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/README.md#local-use).
-For package development, see [Contributing](https://github.com/JasonKoolman/metamesh/blob/main/CONTRIBUTING.md).
+See [local authoring](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/create/author-locally.mdx)
+for the complete workflow and [Contributing](https://github.com/JasonKoolman/metamesh/blob/main/CONTRIBUTING.md)
+for package development.
 
 ## License
 

package/dist/docs/guides/parameters.md

@@ -2,16 +2,16 @@
 
 Define typed controls, editable profiles, conditional visibility, and validation for an authored Studio Project.
 
-Define controls so readers can adjust a model without editing its source. Studio stores the
-definition as JSON-safe Project data, infers `params` through `generate`, and runs cross-field
-validation in `model.ts`.
+Give someone a useful set of controls, and they can adjust your model without editing its source.
+Studio saves the definition as JSON-safe Project data and infers the type of `params` through
+`generate`. You check relationships between controls in `model.ts`.
 
 The JSON document contains required `groups` and `parameters` arrays. A parameter's `type`,
 default, units, bounds, and choices describe its value. Its optional `ui` object describes
 presentation: group, shared row, hint, visibility, editing increment, and physical editor bindings.
 Number and Slider both use `type: "number"`; a Slider also declares `ui.control: "slider"`.
 Options use `type: "choice"`, Side profile uses `type: "side-profile"`, and a closed outline uses
-`type: "contour"`. Changing a numeric widget does not change its saved value or valid range.
+`type: "contour"`. Switching between Number and Slider doesn't change the saved value or valid range.
 
 JSON editing offers field completion, help, and inline validation, including references to declared
 groups, parameters, and choice values. Fix or discard invalid JSON before applying it or returning
@@ -23,19 +23,19 @@ also checks rules that JSON Schema cannot express.
 In an authored Project, open the parameter panel's **Parameter actions** menu and choose
 **Edit controls**. The same action is available in the **MetaMesh menu → Current project** group.
 The Model controls editor's **Visual** and **JSON** views edit the same draft. Choose
-**Apply & return** to commit it and return to the model.
+**Apply & return** to save the definition and return to the model.
 
 1. Add a section for one coherent decision, such as **Size** or **Outputs**.
 2. Add a control, give it a stable ID, a plain-language label, and a useful default.
-3. Add units and field limits where they carry real meaning.
+3. Add units and limits that reflect what the model supports.
 4. Try the selected control in its preview, then apply the draft and check the generated
    `params` completion in `model.ts`.
 
 Preview values are temporary; they do not change the default or the Project's current values.
 
 Use labels to name the decision and descriptions for more detail. Defaults should produce a useful
-model immediately. Use minimum and maximum values for supported field ranges and cross-field
-rules for constraints between controls.
+model immediately. Set minimum and maximum values for each field's supported range, then check
+relationships between controls in your source.
 
 ## Separate help from essential instructions
 
@@ -48,7 +48,7 @@ label is enough. Hints are static and appear whenever the control is visible; pu
 multiple modes in `description`. Errors, warnings, and reasons a control is unavailable stay visible.
 
 In **Visual**, edit **Hint (optional)** as ordinary text. **Visual**, **JSON**, and the live preview
-use the same string field. Clearing it omits the hint when applying the definition. For example,
+use the same string field. Clear it to remove the hint when you apply the definition. For example,
 a socket-only Diameter control can include:
 
 ```json
@@ -84,10 +84,10 @@ A Slider requires `min`, `max`, and a positive `ui.step`. Multiple choice can li
 selections. Lists can limit their item count; number-list items can also declare units, limits,
 and `items.ui.step`.
 
-A Font value is a structured selection, not a family-name string. Pass the whole value in
-`services.text.layout(text, { font, fontSize })` inside generation, then pass its layout to
+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
@@ -138,8 +138,8 @@ Add a **Side profile** control when the model needs an outer silhouette. Its **E
 opens guided points with automatic smoothing, Bézier handles, straight/curved segments,
 and numeric editing. Select a segment directly; double-click it to insert a point at that location.
 Choosing **Curve** reveals handles while retaining the existing shape until a handle moves.
-The Model controls editor uses the same editor for the default outline.
-**Apply profile** changes only the draft being edited; choose **Apply & return** to commit the
+You'll use the same editor to set the default outline in Model controls.
+**Apply profile** changes only the draft being edited; choose **Apply & return** to save the
 control definition.
 
 The value on `params` is a readonly `SideProfileValue`, with a start anchor and line or cubic
@@ -189,8 +189,8 @@ In **Physical dimensions (optional)**, link the radius and height to existing Nu
 controls with unit `mm`, a positive default, and a positive minimum. A radius factor of `0.5` uses
 half a diameter control. The corresponding JSON fields are `ui.radiusScale` and `ui.heightScale`, each
 with `parameterId` and a positive `factor`. These bindings set editor measurements; your source
-still applies the same physical scales when modeling. The envelope describes the available size:
-an outline reaching half the radius envelope produces half its diameter. The editor also shows
+still applies the same physical scales when modeling. They describe the available size:
+an outline reaching half the available radius produces half the diameter. The editor also shows
 the actual maximum diameter.
 
 Use [`sampleSideProfile()`](https://metamesh.studio/docs/reference/geometry/sampleSideProfile) to convert
@@ -269,21 +269,21 @@ 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.
 Reuse that contour in generation, create a filled Section with
 [`polygon(contour)`](https://metamesh.studio/docs/reference/model/polygon), and use
 [`section.extrude()`](https://metamesh.studio/docs/reference/model/Section#extrude) or [`section.sweep()`](https://metamesh.studio/docs/reference/model/Section#sweep) for the solid.
-The Generator owns extrusion depth, the sweep path, fit, walls, and manufacturing rules.
-Data validation checks the bounded structure and closure; it does not establish those geometric
+Your Generator decides extrusion depth, the sweep path, fit, walls, and manufacturing rules.
+Data validation checks the bounded structure and closure; it doesn't establish those geometric
 requirements. This control contains one contour without holes or multiple loops.
 
 Side-profile and cross-section edits stay local until **Apply**. Workspace editors check the
-current draft with Generator declaration and reached assertions before applying it; errors block Apply and warnings
-remain visible. Failed checks offer **Retry draft check**. Editing a control default changes its
-definition draft, so check the current model after **Apply & return**.
+current draft by running the Generator declaration and any assertions it reaches; errors block Apply
+and warnings remain visible. Failed checks offer **Retry draft check**. Editing a control default
+changes its definition draft, so check the current model after **Apply & return**.
 
 <a id="expose-curve-resolution-in-the-viewport"></a>
 
@@ -352,13 +352,13 @@ reference Font, Side profile, Cross section, Number List, or Text List values.
 The JSON root accepts only `groups` and `parameters`. Project identity, title, and version are
 managed separately by Studio.
 
-Visibility is presentation, not data deletion. Source still receives the control's normalized value.
-Generation decides whether it matters in the current mode; assertions and geometry follow that choice.
+Hiding a control keeps its saved value, and source still receives the normalized value. Your
+generation code decides whether to use it in the current mode, including in assertions and geometry.
 
 ## Add cross-field validation in TypeScript
 
-The generation callback receives normalized readonly parameters. Put a cheap assertion before
-geometry when a combination cannot produce a supported model:
+The generation callback receives normalized readonly parameters. If a combination can't produce a
+supported model, put a cheap assertion before geometry to stop the work early:
 
 
 
@@ -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 observing
+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 does not 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
@@ -404,9 +404,9 @@ Before relying on a Project, check:
 - resetting controls returns to the documented defaults.
 
 The Model controls editor checks the definition when you apply it and keeps invalid drafts open
-with errors to correct. After **Apply & return**, Studio uses the updated definition for controls,
-normalization, persistence, and the typed generation context. It then validates the current values
-with `model.ts`; check the workspace for source or cross-field errors before exporting.
+so you can fix the errors. After **Apply & return**, Studio uses the updated definition to build
+controls, normalize and save values, and type the generation context. It then validates the current
+values with `model.ts`; check the workspace for source or cross-field errors before exporting.