@metamesh/generator-sdk 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,163 @@
 # @metamesh/generator-sdk
 
+## 0.18.0
+
+### Minor Changes
+
+- 2eea694: Consolidate model authoring, execution, and testing around fluent shapes and durable immutable
+  results. Upgrade all four packages together; these Preview API changes have no compatibility
+  aliases. Rebuild compiled Generators for module format 5 and Modeling runtime major 11. Older
+  module formats and incompatible runtime versions are rejected before execution.
+
+  ### Modeling imports and operations
+
+  | Previous API                                                                                            | 0.18 API                                                                                                  |
+  | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+  | `body.subtract([cutter])` for a single operand                                                          | `body.subtract(cutter)`; fluent `union`, `intersect`, and `subtract` accept one shape or a readonly array |
+  | `compose(shapes)`                                                                                       | `union(shapes)`                                                                                           |
+  | Free shape inspection, emptiness, component, and anchor queries                                         | `shape.inspect()`, `shape.isEmpty()`, `shape.components()`, and `shape.anchor(name)`                      |
+  | Free Solid distance/segment queries and splitting functions                                             | `solid.distance(other)`, `solid.castSegment(...)`, `solid.split(cutter)`, and `solid.splitByPlane(plane)` |
+  | `solid.toTriangleMesh()`                                                                                | `solid.toMesh()`                                                                                          |
+  | Named `mesh` import from `/geometry`, or standalone triangle-mesh functions                             | `import * as mesh from "@metamesh/modeling/geometry/mesh"`                                                |
+  | Standalone `immutableMesh(...)`                                                                         | `mesh.immutable(...)`                                                                                     |
+  | `helicalThreadRidgeMesh`, `helicalThreadSolidMesh`, and `preflightHelicalThreadSolidMesh`               | `mesh.threadRidge`, `mesh.threadSolid`, and `mesh.preflightThreadSolid`                                   |
+  | `HelicalThreadRidgeMeshOptions`, `HelicalThreadSolidMeshOptions`, and `HelicalThreadSolidMeshPreflight` | `ThreadRidgeOptions`, `ThreadSolidOptions`, and `ThreadSolidPreflight`, exported from the mesh module     |
+  | Mesh `connectedComponentCount`                                                                          | `shellCount`; native inspection `componentCount` still counts material components                         |
+  | Inspection extrema on the inspection result                                                             | Immutable `inspection.bounds.min` and `inspection.bounds.max`                                             |
+  | `starContour(outerRadius, points, innerRadius, limits)`                                                 | `starContour({ outerRadius, innerRadius, points, limits })`                                               |
+
+  Free `union(shapes)` and `intersect(shapes)` remain for collections of peers and reject empty
+  collections. Fluent Boolean methods with an empty array return the receiver.
+
+  Use `section.extrude(options)` in fluent modeling, `extrude(profile, options)` for generic
+  `Section | CorrespondingProfile` inputs, and `mesh.extrude(contour, options)` for pure triangle
+  buffers. The same fluent/generic distinction applies to revolution and sweeping. Pure extrusion
+  uses `ExtrudeMeshOptions` and rejects `ends`; use Section extrusion for native end treatments.
+  Construction, transforms, and splitting remain deferred recipes; observations and `toMesh()`
+  require active model execution.
+
+  Point-loop and arbitrary Section lofts default to direct correspondence when the method is
+  omitted; known primitive landmarks remain preserved. Dimension inputs accept fluent vectors.
+  Tube sizing accepts complete inner/outer radius or diameter pairs. Both star factories require
+  an explicit inner radius and support degree rotation; use `innerRadius: outerRadius / 2` to retain
+  the contour helper's former default.
+
+  Rod and internal-cutter `bevelBottom`, `bevelTop`, and `bevelSize` become `bevel`. The shared
+  `Bevel` contract accepts a nonnegative size, `"auto"`, or a readonly `[bottom, top]` pair; zero
+  disables an end and omission preserves factory defaults. Complete-thread mesh builders use the
+  same contract, with thread termination under `ends`. Nuts replace bevel selection, `chamferSize`,
+  and `flushBuildPlateBottom` with independent `innerBevel` and `outerBevel`. For a flat outside
+  bottom that retains its inner opening bevel, use `outerBevel: [0, "auto"]`. Nut preflight exposes
+  resolved inner/outer pairs and checks face walls pairwise; each end's reservation and automatic
+  sizing are resolved independently, including internal-cutter axial extension.
+
+  Primitive contours and their points are immutable and can be explicit `computed` dependencies.
+  Copy the outer array and any points before editing. Geometry errors are available from the
+  Modeling root; operation option/result types are exported beside their owning operations.
+  Topology analysis with `includeTopology: true`, finalized parts, and local geometry resources
+  include required `shellCount` and `edgeCount`. Bounds construction options describe inputs only;
+  existing fluent bounds remain accepted.
+
+  ### Part placement and result ownership
+
+  Replace `part(id, { geometry, position, rotation })` with
+  `part(id, { geometry, transform })`. The optional transform accepts a fluent `transform3()` value,
+  a row-major 16-number matrix, or a computed reader; omission means identity. Pattern and
+  attachment matrices pass directly to `part()`. Only rigid placement is supported: scale, shear,
+  reflection, perspective, and non-finite values are rejected. Geometry-only and geometry-or-options
+  union inputs remain accepted without casts.
+
+  Use `PartDeclaration` for authored parts. Replace `ModelSnapshot` / `FinalizedModel` with
+  `ModelResult`, and `SnapshotPart` / `FinalizedPart` with `ModelPart`. `engine.run()`, `session.run()`,
+  and Testkit's `runModel()` return durable immutable results. Dispose sessions and runners to release their
+  caches; completed results remain valid and need no disposal. `model.part(id)` returns a required
+  semantic part or throws with available IDs; `model.parts` preserves output order.
+
+  Finalized buffers expose stable, iterable `ImmutableBuffer` values. Use `.copy()` for mutable
+  storage. A `ModelPart`'s top-level positions and indices are already in world space; apply its
+  immutable `transform` only to the reusable local buffers under `geometry`. Worker deliveries also
+  nest local resources under `geometry`. Host integrations use `ModelDeliveryEncoder`,
+  `PartDeliveryDecoder`, and `toWorldMeshes` for owned transfer and manufacturing output.
+  Replace `engine.export3mf(...)` with standalone `export3mf(parts, options)` from `/engine`, which
+  accepts completed meshes with explicit resource limits, independently of engine initialization.
+
+  Statistics rename `volumeMm3` → `signedVolume`, `finalizationMs` → `finalizeMs`, and
+  `generationMs` → `generateMs`; `buildMs` measures declarations.
+  `ModelResult.stats.byteCount` means bytes occupied by finalized world-space position and index buffers,
+  counting shared buffers once. Worker statistics preserve engine `generateMs`; host elapsed time
+  is `timings.totalMs`, with `paramsMs` for parameter work. Other host timing stages are optional:
+  an omitted stage is unmeasured.
+
+  Model parameter roots must be object maps. Captured parameters and computed results expose
+  deeply readonly `ImmutableValue<T>` views; supported mutable caller input is still accepted and
+  recaptured on every revision, including mutable children inside frozen objects. Deeply immutable
+  data retains identity reuse. Assertions and warnings accept bounded immutable nested `path`
+  metadata. Replace `validateModel` with `checkModel` and session/runner `.validate()` with `.check()`.
+  These check declarations and reached assertions without finalizing geometry; unexpected execution
+  failures still throw.
+
+  ### Generator SDK and Testkit
+
+  | Previous API                                                               | 0.18 API                                                                                                                |
+  | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+  | Nested compiled Generator module                                           | Flat format-5 model program; bind an existing program with `defineGeneratorModule({ definition, program })`             |
+  | `isGeneratorModule(value)`                                                 | `parseGeneratorModule(value, definition)`                                                                               |
+  | `executeGenerator({ ..., parsedParameters })`                              | `executeGenerator({ ..., parameters })`; current-definition validation always runs                                      |
+  | Callback-scoped `withModel`, `ModelTestOptions`, or `runner.withModel`     | `await runModel(programOrCallback, ...)` for one-off results; explicit sessions or Generator runners for repeated edits |
+  | Generator test `runner.execute(...)`                                       | `runner.run(...)`, returning `GeneratorTestResult`                                                                      |
+  | `expectSerializableDefinition`                                             | `assertValidDefinition`                                                                                                 |
+  | `expectValidDefaults`, `expectValidPresets`, and `expectValidParts`        | `assertValidDefaults`, `assertValidPresets`, and `assertValidParts`                                                     |
+  | `expectMeshMeasurements`                                                   | `assertMeshMeasurements`                                                                                                |
+  | `canonicalizeParameters(definition, parameters)` from `/parameters`        | `canonicalizeParameters(parameters)` from `/runtime`                                                                    |
+  | `GeneratedPartsDecoder`, `parseGeneratedParts`, and `GeneratedPartsLimits` | `PartDeliveryDecoder`, `parseModelParts`, and `PartDeliveryLimits`                                                      |
+  | `GeneratedPart` and `GeneratedModel`                                       | `ModelPartData` and `ModelData`                                                                                         |
+  | `GeneratedPartDelivery` and `GeneratedModelDelivery`                       | `PartDelivery` and `ModelDelivery`                                                                                      |
+
+  Testkit `runModel` accepts existing `ModelProgram` values and synchronous inline callbacks;
+  typed callbacks use `runModel<Parameters, Services>`. Its definition-bound Generator overload
+  validates inputs and prepares services. The SDK Modeling adapter adds definition-inferred
+  `GeneratorModel` and `parseGeneratorModel`. Ordinary model tests preserve definition-inferred
+  input types. Reusable Generator runners accept physical generation policy plus `cache` and
+  `verifyCache` for edit sequences; dispose the runner after use.
+
+  Generator execution and ordinary tests strictly require complete canonical parameter maps.
+  Use the parameter codec for strict input and `normalizeParameters` for forgiving recovery;
+  replace `prepareParameters`, `validateParameters`, and `PreparedParameters` with
+  `createParamCodec(definition).parse(...)` or `.safeParse(...)`. Schema adapters remain private.
+  Codec failures provide structured issues without a substitute parameter map. For deliberate
+  malformed-input assertion probes, replace `runner.validate(parameters, { normalize: false })`
+  with `runner.check(parameters, { validateInput: false })`.
+  Defaults are selected only by omission or `undefined` where supported; a `null` parameter map is
+  rejected. Parameterless model calls can omit the empty map. Definition and preset helpers catch
+  nested key typos and validate immediately while retaining literal inference.
+
+  `assertValidParts` checks the supplied world-space buffers, closed topology, and exact agreement
+  with local geometry under `transform`; it no longer hides corrupted output by reconstructing it.
+  Always await `assertValidParts(parts, engine)` (or omit the engine): failures reject, and supplying
+  an engine changes resource reuse only.
+  `assertValidDefinition` also checks the canonical JSON round trip. New `assertEqualBuffer` and
+  `assertEqualMesh` compare exact ordered contents without copying; equivalent shapes with different
+  triangulations can differ. `ContentMismatchError` identifies the first differing element or
+  length, while malformed input and reader failures retain their errors. Optional `contentMatchers`
+  support `expect.extend`, including negation, without a test-framework dependency.
+
+  ### CLI and package requirements
+
+  Rename the type-only CLI command `metamesh check` to `metamesh typecheck`; no alias is retained.
+  Node authoring APIs and Modeling/Testkit declaration-check methods retain their names. Generator
+  runs use `overrides` / `--overrides`, merged with defaults before strict parsing; standalone models
+  use `params` / `--params`. Supplying the other entry kind's input option is rejected.
+
+  Captured runs use format 2 with transform-only placement. The bundled capture renderer resolves
+  from the installed CLI package so published installations can render captures.
+  Public packages require Node.js 24 or newer, ESM imports, and TypeScript 6.0 or newer with strict
+  checking for TypeScript consumers.
+
+### Patch Changes
+
+- Updated dependencies [2eea694]
+  - @metamesh/modeling@0.18.0
+
 ## 0.17.0
 
 ### Minor Changes

package/README.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 } from "@metamesh/generator-sdk";
+import { defineGeneratorModel } from "@metamesh/generator-sdk/modeling";
+import { tube } from "@metamesh/modeling";
 
 export const definition = defineGenerator({
   id: "sleeve",
@@ -34,29 +41,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 +57,93 @@ 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.
-
-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.
-
-## 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                  |
-| `@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/authoring.d.ts

@@ -1,6 +1,13 @@
-import type { GeneratorDefinition, GeneratorPreset } from "./contracts.js";
-/** Captures literal IDs and options; the host validates serializable metadata. */
-export declare function defineGenerator<const D extends GeneratorDefinition>(definition: D): D;
-/** Contextually types complete presets from the same definition as the controls. */
-export declare function definePresets<const D extends GeneratorDefinition, const Presets extends readonly GeneratorPreset<NoInfer<D>>[]>(_definition: D, presets: Presets): Presets;
+import type { GeneratorPreset } from "./parameters/contracts.js";
+import type { GeneratorDefinition, ParameterDefinition } from "./parameters/definitions.js";
+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. */
+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. */
+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":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAE3E,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,KAAK,CAAC,CAAC,SAAS,mBAAmB,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,CAErF;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAC3B,KAAK,CAAC,CAAC,SAAS,mBAAmB,EACnC,KAAK,CAAC,OAAO,SAAS,SAAS,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAC5D,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAE3C"}
+{"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"}

package/dist/authoring.js

@@ -1,9 +1,13 @@
-/** Captures literal IDs and options; the host validates serializable metadata. */
+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. */
 export function defineGenerator(definition) {
+    parseGeneratorDefinition(definition);
     return definition;
 }
-/** Contextually types complete presets from the same definition as the controls. */
-export function definePresets(_definition, presets) {
+/** Validates complete, canonical preset values and metadata while preserving the supplied array and literal types. */
+export function definePresets(definition, presets) {
+    validateGeneratorPresets(definition, presets);
     return presets;
 }
 //# sourceMappingURL=authoring.js.map

package/dist/authoring.js.map

@@ -1 +1 @@
-{"version":3,"file":"authoring.js","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAsC,UAAa;IAChF,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,aAAa,CAG3B,WAAc,EAAE,OAAgB;IAChC,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,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"}

package/dist/docs/guides/authoring.md

@@ -13,7 +13,7 @@ const { width, depth, height, holeDiameter, addHole } = params;
   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.
@@ -26,8 +26,8 @@ Describe what someone should be able to change: the overall size, a fit, an opti
 which parts to produce. Expose those decisions as controls. Keep implementation details in the
 source unless changing them serves a clear purpose.
 
-For a plate with an optional hole, Width and Hole diameter express design decisions. The cylinder's
-segment count usually does not need equal prominence.
+For a plate with an optional hole, Width and Hole diameter describe changes someone will want to
+make. The cylinder's segment count usually doesn't need equal prominence.
 
 Open **Parameter actions → Edit controls**, or **MetaMesh menu → Current project → Edit controls**.
 Group related controls into sections, put the most common decisions first, and choose
@@ -88,9 +88,9 @@ For the plate above, test these decisions separately:
 
 ## Keep related parts understandable
 
-Use stable, descriptive part IDs for related outputs, such as a lid and container, so readers can
-identify them during inspection and export as dimensions change. The [part contract](https://metamesh.studio/docs/develop/code-project-contract#parts-and-placement) describes the
-supported output shape.
+Give related outputs stable, descriptive part IDs, such as a lid and container, so someone can
+identify them during inspection and export as dimensions change. The [parts guide](https://metamesh.studio/docs/develop/code-project-contract#parts-and-placement)
+shows how to return them from your code.
 
 Inspect each output and check the exported model in its intended downstream tool. A valid solid
 alone does not establish a suitable fit or printable wall thickness. Follow the
@@ -99,9 +99,9 @@ alone does not establish a suitable fit or printable wall thickness. Follow the
 ## Use the same design in a local module
 
 These control-design principles also apply to a Generator authored in a local TypeScript project.
-Use `@metamesh/generator-sdk` for its serializable definition and module envelope, and
+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 cannot be copied into a local Node module.
+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
 module with the CLI, inspect dimensions and named parts, and render the captured result. Add