@metamesh/generator-sdk 0.16.0 → 0.18.0

package/dist/docs/guides/package.md

@@ -1,28 +1,35 @@
 # `@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.
+Define typed controls, presets, and portable contracts for MetaMesh Generators. Use one definition
+for the editing interface, saved parameter values, and model execution.
 
 > **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:
+
 ```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.
+
+The SDK can also be used alone for definitions, parameter handling, and package validation.
+Only its optional `/modeling` adapter imports the Modeling runtime.
 
 ## Define controls
 
-A definition describes the Generator and its editable parameters. Literal IDs and options give
-you exact parameter types:
+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:
 
 ```ts
-import { defineGenerator, type GeneratorParams } from "@metamesh/generator-sdk";
+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,30 +41,11 @@ export const definition = defineGenerator({
     { id: "boreDiameter", label: "Bore diameter", type: "number", default: 10, min: 1 },
   ],
 });
-type Parameters = GeneratorParams<typeof definition>;
-```
-
-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. Assertions describe relationships
-between controls; the module helper binds the program to its definition:
-
-```ts
-import { defineGeneratorModule } from "@metamesh/generator-sdk";
-import { generate, tube } from "@metamesh/modeling";
-
-const model = generate<Parameters>(({ params, assert, part }) => {
-  assert(
-    params.boreDiameter < params.outerDiameter,
-    "The bore must be smaller than the outside diameter.",
-    { parameterId: "boreDiameter" }
-  );
+export default defineGeneratorModel(definition, ({ params, assert, part }) => {
+  assert(params.boreDiameter < params.outerDiameter, "The bore must fit inside the sleeve.", {
+    parameterId: "boreDiameter",
+  });
   return part(
     "body",
     tube({
@@ -67,54 +55,95 @@ const model = generate<Parameters>(({ params, assert, part }) => {
     })
   );
 });
-export default defineGeneratorModule({ definition, generate: model });
 ```
 
-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.
-
-## Work with saved values
-
-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.
-
-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.
+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.
+
+## Generator capabilities
+
+| 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.                   |
+
+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.
+
+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)
+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`.
+
+`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.
 
 ## 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                  |
+| 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,8 +84,8 @@ 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
 limits.
@@ -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
@@ -276,14 +276,14 @@ XY `Contour` without a duplicated seam, rejecting invalid sampled topology and e
 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,9 +382,9 @@ 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: reading a computed value evaluates it when needed, 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`
+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
 separate preparation callback.
 
@@ -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.