@metamesh/generator-sdk 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @metamesh/generator-sdk
 
+## 0.11.0
+
+### Minor Changes
+
+- b5da778: Replace prepare/build with typed generation programs, optional computed values and authoritative
+  part placement. Add isolated session caches and deferred geometry with explicit snapshot ownership.
+  Expose immutable fluent Solid and Section methods for transforms, subtraction, finishing, and
+  Section-to-Solid construction, replacing the corresponding standalone operations and public
+  context facade. Generator packages require format 4 and runtime 4; previous executable contracts are unsupported.
+
+### Patch Changes
+
+- d69836c: Update the Generator SDK's runtime validation dependency to Zod 4.6.7.
+- bfb7a63: Keep computed dependencies correct after conditional removal and re-registration, and prevent
+  caught evaluation failures from returning earlier cached values. Reduce immutable data copying,
+  centralize geometry finalization, and validate newly delivered resources once while preserving
+  per-revision part and aggregate resource checks.
+
+  Replace transparent cached typed arrays with explicit immutableBuffer and immutableMesh capture
+  helpers. Cached numeric data exposes length, at(), and copy(); uncaptured typed arrays in computed
+  results or bindings now reject. Snapshot and Worker output buffers remain ordinary typed arrays.
+
+## 0.10.0
+
+### Minor Changes
+
+- 0eea1b4: Add one optional static `ui.hint` string per parameter with strict metadata validation. Short, essential instructions appear inline; descriptions provide supplementary help from the question-mark button. Control visibility remains conditional. Hints are part of the format 3/runtime 3 baseline.
+- 9d7052c: Separate parameter values from local UI metadata, add strict parameter-document diagnostics and a generated JSON Schema, and rename the side-profile and contour APIs. Generator packages and modules now require format 3 and runtime 3.0.0.
+- cf597bd: Add optional `ui.row` metadata for two adjacent number inputs, choice dropdowns, or text controls within a parameter group. Shared rows are part of the format 3/runtime 3 baseline.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -1,43 +1,30 @@
 # `@metamesh/generator-sdk`
 
-Runtime-neutral contracts and helpers for Generators, hosts, and workers.
+Turn a parametric model into a MetaMesh Generator. Define its controls once, infer parameter
+types, and use the same validation contract for forms, saved values, and execution.
 
 > **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
 > same minor line. Stable support requires an explicit `1.0.0` review.
 
-Install a published release from npm:
-
 ```bash
 pnpm add @metamesh/generator-sdk
 ```
 
-The root provides lightweight authoring contracts and helpers with explicit TypeScript interfaces.
-It has no Zod, modeling, renderer, browser, or Worker dependencies.
-Use the supported subpaths for host responsibilities:
-
-| Entry         | Responsibility                                                                  |
-| ------------- | ------------------------------------------------------------------------------- |
-| Root          | Definitions, presets, preparation/module authoring, parameter and service types |
-| `/parameters` | Defaults, normalization, strict codecs, schema issues                           |
-| `/runtime`    | Evaluated module parsing, execution, mesh DTO parsing, Worker envelopes         |
-| `/packages`   | Package, catalog and installation trust parsing                                 |
-| `/fonts`      | Standalone font selection contract                                              |
-
-Definitions remain callback-free and serializable. Preparation/build state is local to execution;
-Studio owns persistence and the Modeling engine owns modeling and manufacturing finalization.
-
-## Parameter definitions
+| Import        | Use it for                                                 |
+| ------------- | ---------------------------------------------------------- |
+| Package root  | Definitions, presets, and module authoring                 |
+| `/parameters` | Defaults, recovering saved values, and strict codecs       |
+| `/runtime`    | Module execution, generated mesh data, and Worker messages |
+| `/packages`   | Package, catalog, and installation parsing                 |
+| `/fonts`      | Font selection values                                      |
 
-Parameters use a `type` discriminant: `number`, `slider`, `boolean`, `select`, `choice-set`, `color`,
-`text`, `font`, `svg`, `profile`, `cross-section`, or homogeneous `array`. Sliders require `min`, `max`, and `step`;
-numbers may omit them. Visibility uses serializable `ConditionExpression` values with `all`, `any`,
-`not`, equality/inequality, numeric comparisons, and choice-set membership (`contains`).
+## Define controls
 
-Define controls once, then normalize saved values or strictly parse boundary values:
+A definition is serializable metadata. Capture its literal IDs and options to derive exact
+parameter types:
 
 ```ts
 import { defineGenerator, type GeneratorParams } from "@metamesh/generator-sdk";
-import { createParamCodec, prepareParameters } from "@metamesh/generator-sdk/parameters";
 
 const definition = defineGenerator({
   id: "sleeve",
@@ -50,334 +37,82 @@ const definition = defineGenerator({
   ],
 });
 type Parameters = GeneratorParams<typeof definition>;
-
-const persistedValues: Readonly<Record<string, unknown>> = { outerDiameter: 24 };
-const { parameters, validation } = prepareParameters(definition, persistedValues);
-const workerValues: unknown = { outerDiameter: 24, boreDiameter: 10 };
-const strictParameters = createParamCodec(definition).parse(workerValues);
 ```
 
-Normalization drops unknown keys, restores missing or invalid values from declared defaults,
-clamps numbers, and returns a fresh frozen map. Strict codecs reject missing, unknown, invalid, or
-noncanonical values and return cloned frozen structured values. `prepareParameters()` normalizes
-once and returns the map with schema issues. Execution aggregates Generator preparation issues
-separately. Definitions accept only
-canonical types. SVG values are strings limited to 256 KiB each and 512 KiB per normalized Project.
-The same byte limits apply to defaults and presets. Definition parsing rejects defaults that exceed
-the aggregate Project budget; preset parsing uses each declared control's limits, so an SVG value
-may exceed the separate 64 Ki-character text limit.
-
-```ts
-import { EMPTY_SVG_PARAMETER_DEFAULT } from "@metamesh/generator-sdk/parameters";
+For saved values, `/parameters` provides `normalizeParameters`: it drops unknown keys, restores
+missing or invalid values from defaults, and clamps numbers. At a trust boundary,
+`createParamCodec(definition)` rejects missing, unknown, invalid, or noncanonical values instead.
+Both return fresh frozen parameter maps.
 
-const profile = {
-  id: "profile",
-  label: "Profile",
-  type: "svg",
-  default: EMPTY_SVG_PARAMETER_DEFAULT,
-} as const;
-```
+Parameter types describe saved values. Optional local `ui` metadata owns group/row membership,
+hints, visibility, editing increments, and physical editor scale bindings. Number inputs and
+sliders both use `type: "number"`; sliders declare `ui.control: "slider"`, bounds, and `ui.step`.
+Fixed choices use `choice`; geometric values use `side-profile` and `contour`.
 
-### Choice sets and arrays
+The `/packages` entry point validates the editable `{ groups, parameters }` document with
+`safeParseParameterDefinitionDocument`, returning structured issue paths and codes. Complete
+Generator and package parsing uses the same rules. The package also ships
+`@metamesh/generator-sdk/parameters.schema.json` for offline editor completion and structural
+validation; the SDK additionally checks references, defaults, and cross-field invariants.
 
-Choice sets have uniquely valued options and a default selection array. `minSelections` and
-`maxSelections` optionally bound its size. Normalization orders valid selections by option
-declaration; duplicate or invalid selections recover to the canonical default. `{ param: "outputs", contains: "nut" }`
-must reference a choice set and one of its declared options.
+## Generate a model
 
-Array definitions declare `items.type` as `number` or `string`. They may constrain `minItems` and
-`maxItems`; number items may also declare `min`, `max`, `step`, and `unit`. Array-valued controls are
-cloned at normalization and persistence boundaries. Conditions may compare scalar controls or test
-`choice-set` membership; arbitrary arrays cannot be condition operands.
+A Generator exports one format-4 default envelope containing its definition-bound program:
 
 ```ts
-const points = {
-  id: "points",
-  label: "Point sizes",
-  type: "array",
-  default: [4, 8],
-  minItems: 1,
-  items: { type: "number", min: 0, unit: "mm" },
-} as const;
-```
-
-Groups are ordered sections with stable IDs, user-facing labels, optional descriptions, and an
-optional `collapsed` default. Parameters without a group render in Studio's General section.
-
-### Fonts and text
-
-Font parameters use a `FontSelection` default with immutable `faceId`, SHA-256 `revision`, and
-integer `weight`. Structural validation does not require the font to be available locally. Valid
-unavailable references survive codecs, presets, and persistence. Studio prepares declared fonts before the Generator's `prepare(parameters, services)` callback.
-`services.text.layout(text, { font, fontSize })` returns exact vector paths and measurements in
-millimetres. Keep that layout in the preparation value when checks and construction both need it.
-Imported `textSection(layout)` consumes it during build. No ambient font provider is bound.
-
-Text layout can use `baseline: { kind: "arc", radius, centerAngleDegrees, direction }` for a single circular line. Radius is in millimetres, the angle is counterclockwise from +X (default 90°), and direction defaults to clockwise. Alignment defaults to center for arcs; use clockwise at 90° for upright top text or counterclockwise at 270° for upright bottom text. Glyphs and attached marks rotate without distortion. Arc layout requires baseline vertical alignment and less than one full revolution; Generator preparation owns lettering size and face-fit checks. Packages using circular text require runtime `2.1.0` or newer.
-
-### Validation and bounds
-
-`GeneratorDefinition` is callback-free, JSON-safe metadata for forms, manifests, persistence, and
-normalization. `defineGenerator()` preserves literal IDs/options; `GeneratorParams` and
-`GeneratorIssue` derive exact parameter types and issue IDs from that definition. Use
-`definePresets(definition, presets)` to require complete definition-derived preset values.
-
-Per-field constraints belong in the definition. Cross-parameter, warning, manufacturing and geometry
-constraints belong in `prepare`, alongside the dimensions and samples that `build` will consume.
-A successful result is `{ ok: true, value, issues }`; an invalid result is `{ ok: false, issues }`.
-Successful preparation may contain warnings but no errors. Invalid preparation requires an error,
-and prevents build and native shape construction.
-
-Numeric parameters and numeric array items may declare `integer: true`. Their defaults and supplied
-bounds must be integers. Strict codecs reject fractions; saved fractions recover to the declared
-default. Numeric array recovery replaces the invalid array with its default. `step` only describes
-the control increment and does not imply integer values.
-
-Schema editors receive only the definition and never rewrite validators. Manifests remain
-callback-free. Preparation receives normalized, frozen parameters; malformed issue output is a
-runtime error. Combined validation retains at most 100 issues, prioritizing errors over warnings
-and preserving retained order. The reporting limit cannot hide a blocking error.
-
-Issues may include an optional stable `code` and `path` relative to the parameter value, such as
-`{ code: "minimum", path: [2] }` for an array item or
-`{ code: "invalid", path: ["segments", 0, "control1", "height"] }` for a profile control.
-`ParameterIssueCode` defines the supported categories: `invalid`, `missing`, `type`, `unknown`,
-`minimum`, `maximum`, `integer`, `choice`, `duplicate`, `length`, `bytes`, and `structure`.
-Schema validation supplies codes and nested locations; strict decoder paths start with the
-parameter ID. Authored issues retain their optional metadata through preparation and transfer.
-Issue parsing clones and freezes paths, bounds them to 32 segments, accepts non-negative safe
-integer indices and non-empty field names of at most 120 characters, and never evaluates accessors.
-Both fields are optional; issues always retain their required severity and message.
-
-Use `getDefaultParameters(definition)` for a fresh frozen defaults map. IDs are bounded safe keys.
-Package manifests, definitions, descriptors, conditions, and nested parameter objects reject unknown fields.
-Definitions are bounded to 64 groups and 256 parameters, arrays to 1,024 items, options to 512,
-presets to 256, and condition composition to 8 levels with 32 children per node.
-`validateGeneratorPresets()` from `/packages` applies the same strict metadata and list bounds as
-manifest parsing before checking complete canonical parameter maps. Testkit and bundled registries
-use that shared validator.
-
-### Editable side profiles
-
-A `profile` declares an open side outline as a versioned `ProfileValue`. Start/end anchors carry
-normalized `radius` and upward `height` coordinates, plus editing `mode` (`auto`, `smooth`, or
-`corner`). Segments are `line` or `cubic`, with cubic `control1` and `control2` points. Coordinates
-define the shape; hosts must resolve automatic tangents into those control points.
-
-```ts
-const sideProfile = {
-  id: "sideProfile",
-  label: "Side profile",
-  type: "profile",
-  radiusScale: { parameterId: "diameter", factor: 0.5 },
-  heightScale: { parameterId: "height", factor: 1 },
-  default: {
-    version: 1,
-    start: { radius: 0.4, height: 0, mode: "corner" },
-    segments: [
-      {
-        type: "cubic",
-        control1: { radius: 0.4, height: 0.35 },
-        control2: { radius: 1, height: 0.75 },
-        end: { radius: 0.6, height: 1, mode: "auto" },
-      },
-    ],
-  },
-} as const;
-```
-
-Every coordinate is finite and lies in `[0, 1]`. The start height is `0`, the last height is `1`,
-and anchor heights increase strictly. Cubic control heights satisfy
-`start.height <= control1.height <= control2.height <= end.height`, keeping the curve upward.
-A profile has 1–31 segments. It has no SVG markup, sampled polygon, arbitrary closed paths, or
-holes; the Generator owns physical scaling, mounting features, closure, and manufacturing checks.
-
-Optional `radiusScale` and `heightScale` bindings describe physical measurements for host controls:
-each references a declared `number` or `slider` in millimetres with a positive default and explicit
-positive minimum, multiplied by a positive finite `factor`. Bindings do not transform saved profile
-values; Generators consume the same normalized outline when resolving their dimensions. Omitting
-bindings leaves the editor in normalized coordinates.
-
-`isProfileValue()` strictly checks the complete bounded shape without evaluating getters.
-`cloneProfileValue()` returns a fresh deeply frozen value, and `profileValuesEqual()` compares both
-shape and editing intent. Normalization, strict codecs, defaults, and presets clone every nested
-profile object. Invalid saved profiles recover to the declared default; strict boundaries reject
-them. Profiles cannot be condition operands. All executable packages use format `2` and runtime major `2`.
-
-### Editable cross sections
-
-A `cross-section` declares one closed planar contour as a versioned `CrossSectionValue`.
-It uses normalized `x` and upward `y` coordinates in `[0, 1]`, with `corner` or `smooth` anchor
-modes and explicit `line` or `cubic` segments. Cubic controls retain the authored geometry;
-editing modes never change it during execution. The final segment's end repeats the start's
-coordinates and mode so the seam is one editable point.
-
-```ts
-const crossSection = {
-  id: "crossSection",
-  label: "Cross section",
-  type: "cross-section",
-  widthScale: { parameterId: "width", factor: 1 },
-  heightScale: { parameterId: "height", factor: 1 },
-  default: {
-    version: 1,
-    start: { x: 0, y: 0, mode: "corner" },
-    segments: [
-      { type: "line", end: { x: 1, y: 0, mode: "corner" } },
-      { type: "line", end: { x: 1, y: 1, mode: "corner" } },
-      { type: "line", end: { x: 0, y: 1, mode: "corner" } },
-      { type: "line", end: { x: 0, y: 0, mode: "corner" } },
-    ],
-  },
-} as const;
-```
-
-Contours have 2–32 segments and can travel in any direction. They have no holes or multiple loops.
-Structural validity establishes bounded serializable data and explicit closure; the Generator
-owns physical scaling, nonzero area, intersections, winding, and operation-specific geometry checks.
-Optional `widthScale` and `heightScale` use the same positive millimetre references as side profiles.
-They describe the coordinate envelope and never transform saved values; omitting them leaves
-normalized coordinates.
-
-`isCrossSectionValue()`, `cloneCrossSectionValue()`, and `crossSectionValuesEqual()` apply the same
-accessor-safe validation, deep cloning/freezing, and shape/editing equality guarantees as profiles.
-Defaults, normalization, codecs, presets, and Worker parameter maps preserve those values.
-Invalid saved data recovers to the declared default; strict boundaries reject it. Cross sections
-cannot be condition operands. Packages declaring them require minimum runtime `2.2.0`; manifest
-parsing rejects lower declared minima. Side profiles retain their existing representation and
-compatibility.
-
-### Curve resolution
-
-A `number` or `slider` may declare `role: "curve-resolution"` to identify the model's maximum
-sampled curve deviation in millimetres. Hosts may present this input in a dedicated curve fidelity
-control. It remains an ordinary Generator parameter with the same saved values, presets,
-normalization, validation, and manufacturing exports.
-
-```ts
-const curveDeviation = {
-  id: "curveDeviation",
-  label: "Curve deviation",
-  type: "number",
-  role: "curve-resolution",
-  unit: "mm",
-  default: 0.05,
-  min: 0.01,
-  max: 0.2,
-  step: 0.005,
-} as const;
-```
-
-Multiple controls may have this role. Each requires `unit: "mm"`, a positive `default`, and an
-explicit positive `min`; numeric bounds and step rules still apply. Lower values request closer
-approximation through the Generator's `GeometryResolution` policy; exact counts remain available
-for matched topology. Hosts show authored labels in definition order and edit the saved parameters
-used by both preview and manufacturing. Generators determine affected curves and parts; Studio
-does not infer overrides from mesh IDs. Requests beyond complexity limits must fail explicitly.
-
-## Compiled module and output boundary
-
-`defineGeneratorModule()` creates the five-field format-2 surface. Preparation resolves the model
-once; build receives that exact value. Imported modeling helpers bind to the host's synchronous build:
-
-```ts
-import { defineGeneratorModule, definePreparation, prepared } from "@metamesh/generator-sdk";
-import { tube } from "@metamesh/modeling";
-
-const prepareSleeve = definePreparation(definition, (parameters, { invalid }) => {
-  if (parameters.boreDiameter >= parameters.outerDiameter)
-    return invalid("boreDiameter", "The bore must be smaller than the outside diameter.");
-  return prepared({
-    outerRadius: parameters.outerDiameter / 2,
-    innerRadius: parameters.boreDiameter / 2,
-  });
-});
-const runtime = defineGeneratorModule({
-  definition,
-  prepare: prepareSleeve,
-  build: (dimensions) => tube({ ...dimensions, height: 20 }),
+import { defineGeneratorModule, type GeneratorParams } from "@metamesh/generator-sdk";
+import { generate, tube } from "@metamesh/modeling";
+
+const model = generate<GeneratorParams<typeof definition>>(({ params, assert, part }) => {
+  assert(
+    params.boreDiameter < params.outerDiameter,
+    "The bore must be smaller than the outside diameter.",
+    { parameterId: "boreDiameter" }
+  );
+  return [
+    part(
+      "body",
+      tube({
+        outerRadius: params.outerDiameter / 2,
+        innerRadius: params.boreDiameter / 2,
+        height: 20,
+      })
+    ),
+  ];
 });
-
-export const { formatVersion, generatorId, version, prepare, build } = runtime;
+export default defineGeneratorModule({ definition, generate: model });
 ```
 
-`definePreparation(definition, callback)` infers readonly parameter values, prepared data and
-`PreparationServices<typeof definition>`. Its second callback argument retains `services.text`
-and adds `invalid(parameterId, message)` and `invalid(issue)`, with allowed IDs checked directly at
-each argument. Destructure `{ invalid }` or call `services.invalid(...)`. A warning alone cannot
-produce failed preparation.
-
-The helper returns a preparation wrapper that accepts parameters and optional host `GeneratorServices`.
-Omitting services uses `UNPREPARED_GENERATOR_SERVICES` for parameter-only probes; requesting
-text through that provider fails explicitly. Hosts pass their prepared services.
-It adds the scoped helper for each callback invocation, preserving the exact callback result and
-prepared value without traversal or freezing. The callback itself is not returned unchanged.
-`prepared(value)` remains the successful-value helper. Standalone global `invalid` accepts literal
-IDs or existing error issues; the host checks their IDs against the definition at the runtime
-boundary.
-
-The root helper has no decoder or Modeling runtime dependency. Modeling owns `ModelingContext`
-and `BuildOutput`; SDK context/output generics preserve author typing without importing them.
-Prepared values are opaque local data: the SDK does not traverse, clone, serialize or freeze them.
-Preparation must not acquire live modeling resources. Prepared values are never persisted,
-transferred to the UI, or reused between requests.
-
-Hosts import `parseGeneratorModule`, `prepareGenerator` and `executeGenerator` from `/runtime`.
-The parser requires exactly the five exports above and matching manifest identity. Evaluated
-preparation captures an opaque value in a one-use build closure; there is no raw prepared-value
-invocation lane. Callback results must be synchronous. The host checks the own-data preparation
-wrapper and bounded structured issues while leaving the value opaque.
-
-Studio's authored source surface accepts `build` and optional `prepare`. Its compiler supplies
-identity and `prepareIdentity(definition)` when preparation is omitted, then passes the resulting
-five-field module through this same parser and executor. Compiled packages always include `prepare`.
-
-`prepareGenerator` normalizes once and either returns `invalid` or a prepared result containing
-`build(context)`. Use that closure inside `engine.build()` so one engine owns modeling, mesh
-validation, limits, measurements and cleanup. `executeGenerator` accepts a context directly and
-returns abstract build output; it does not finalize geometry. Hosts preparing asynchronous services
-first may supply their `/parameters` `PreparedParameters` result as `parameterState` to reuse it.
-
-`parseGeneratedParts(parts, limits)` strictly checks the final transferable DTO. The host supplies
-its complete limits; the SDK does not own a duplicate default resource policy. Canonical parts have
-unique IDs, Float32 positions, Uint32 indices and optional six-digit colors. Normals belong to
-viewport presentation. Geometric/manufacturing validation belongs to the shared engine.
-
-Package format `1`, runtime major `1`, retired `validate/generate` module exports and extra exports
-reject explicitly. No compatibility adapter or preparation cache remains.
-
-Packages using the current modeling operations and Section overloads, `holeCutter()`, or optional
-issue `code`/`path` metadata must declare minimum runtime `2.1.0`. Package format and execution
-protocol major remain `2`. The manifest minimum must cover the host capabilities the package uses.
-
-## Worker boundary
+The host normalizes parameters and resolves assets before synchronous generation. Modeling owns
+optional computed caches, deferred recipes, sessions and immutable snapshots; the SDK stays
+renderer-neutral and imports no engine. The [generation contract](https://github.com/JasonKoolman/metamesh/blob/main/docs/model-generation.md)
+owns dependencies, assertions, placement and lifecycle. `/runtime` strictly checks the new default
+envelope and maps engine diagnostics to definition-owned issues. Unsupported package formats are
+rejected before executable bytes are evaluated.
 
-Worker requests/responses are `/runtime` contracts containing structured data and transferable
-arrays, never live modeling handles. Validation issues are normal outcomes; callback, Worker and
-exporter exceptions use error envelopes. Finalized previews carry revision identity, bounds,
-warnings and optional statistics. Manufacturing exports serialize the requested finalized revision,
-including appearance overrides, without running preparation/build again.
+For incremental Worker deliveries, `/runtime` provides `GeneratedPartsDecoder`. It validates new
+geometry buffers once and hydrates later resource references, while checking part metadata and
+aggregate limits on every delivery. The receiving host keeps admitted buffers immutable and
+attached, and calls `clear()` when replacing the delivery source.
 
-Successful generation envelopes include `sentAt`, the sender's high-resolution epoch milliseconds
-captured immediately before transfer. Hosts use `/runtime` `parseGenerationSentAt()` to reject
-missing, inherited, accessor, or nonfinite timestamps before measuring transfer latency. Worker
-clock construction and receiver timings belong to the host.
+## Documentation
 
-`ModelTimings.prepareMs` measures Generator preparation; `viewportPrepareMs` measures host viewport
-preparation. `firstDrawMs` starts when viewport preparation ends and measures elapsed time through
-every part's first draw submission, including render scheduling and buffer upload. Viewport fields
-are optional until the host records completion. First draw does not measure GPU completion.
-`totalMs` is request-to-completion elapsed time, including scheduling between stages, rather than
-the sum of stage timings. Studio reports request-to-delivery time until viewport completion.
+Read the [parameters guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx)
+for controls and validation, or [local authoring](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/create/author-locally.mdx)
+for the current Generator workflow. The public documentation site is planned for `metamesh.studio/docs`.
 
-`MeshTopologyMode` is host policy rather than a Generator parameter. Both compiled and authored
-models use the same engine finalization and limits. Studio's runtime contract owns request lifecycle,
-revision retention and export recovery.
+Exact SDK contracts live with their code:
 
-## Development
+- [Parameter definitions](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/parameter-contracts.ts),
+  [side profiles](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/side-profiles.ts), and
+  [contours](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/contours.ts).
+- [Authoring helpers](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/authoring.ts),
+  [module contract](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/generator-module.ts), and
+  [runtime execution](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/execute-generator.ts).
 
-Keep this package independent of React, Zustand, Three.js, Manifold, DOM, and Web Worker APIs.
-The [workspace instructions](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/AGENTS.md) own contract review and required checks.
+For maintainers, the [package contract](https://github.com/JasonKoolman/metamesh/blob/main/docs/generator-packages.md)
+owns compatibility and trust; [workspace instructions](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/AGENTS.md)
+own contract review and required checks.
 
 ## License
 

package/dist/authoring.d.ts

@@ -1,57 +1,6 @@
-import type { GeneratorDefinition, GeneratorIssue, GeneratorParams, GeneratorPreset, ParameterIssue } from "./contracts.js";
-import type { Preparation } from "./generator-module.js";
-import { type GeneratorServices } from "./generator-services.js";
+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;
-/** Successful worker-local preparation. The value is never cloned or inspected. */
-export declare function prepared<P>(value: P): {
-    readonly ok: true;
-    readonly value: P;
-    readonly issues: readonly [];
-};
-/** Failed preparation attributed to a literal parameter ID or an existing error issue. */
-export declare function invalid<const Id extends string>(parameterId: Id, message: string): {
-    readonly ok: false;
-    readonly issues: readonly [
-        {
-            readonly severity: "error";
-            readonly parameterId: Id;
-            readonly message: string;
-        }
-    ];
-};
-export declare function invalid<const Issue extends ParameterIssue & {
-    readonly severity: "error";
-}>(issue: Issue): {
-    readonly ok: false;
-    readonly issues: readonly [Issue];
-};
-/** Definition-bound error reporting plus the host's unchanged text service. */
-export interface PreparationServices<D extends GeneratorDefinition> extends GeneratorServices {
-    /** Reports one error using a declared parameter ID or an existing definition-bound issue. */
-    readonly invalid: {
-        <const Id extends D["parameters"][number]["id"]>(parameterId: Id, message: string): {
-            readonly ok: false;
-            readonly issues: readonly [
-                {
-                    readonly severity: "error";
-                    readonly parameterId: Id;
-                    readonly message: string;
-                }
-            ];
-        };
-        <const Issue extends GeneratorIssue<D> & {
-            readonly severity: "error";
-        }>(issue: Issue): {
-            readonly ok: false;
-            readonly issues: readonly [Issue];
-        };
-    };
-}
-/** Wraps preparation with definition-bound services while preserving its exact result and value. */
-export declare function definePreparation<const D extends GeneratorDefinition, Result extends Preparation<NoInfer<D>, unknown>>(_definition: D, callback: (parameters: GeneratorParams<NoInfer<D>>, services: PreparationServices<NoInfer<D>>) => Result): (parameters: GeneratorParams<D>, services?: GeneratorServices) => Result;
-/** Parameter-only preparation is useful for models with no derived dimensions. */
-export declare function prepareIdentity<const D extends GeneratorDefinition>(_definition: D): (parameters: GeneratorParams<D>) => ReturnType<typeof prepared<GeneratorParams<D>>>;
 //# 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":"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"}
+{"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"}

package/dist/authoring.js

@@ -1,4 +1,3 @@
-import { UNPREPARED_GENERATOR_SERVICES } from "./generator-services.js";
 /** Captures literal IDs and options; the host validates serializable metadata. */
 export function defineGenerator(definition) {
     return definition;
@@ -7,27 +6,4 @@ export function defineGenerator(definition) {
 export function definePresets(_definition, presets) {
     return presets;
 }
-/** Successful worker-local preparation. The value is never cloned or inspected. */
-export function prepared(value) {
-    return { ok: true, value, issues: [] };
-}
-export function invalid(issueOrId, message) {
-    if (typeof issueOrId === "string") {
-        if (typeof message !== "string")
-            throw new TypeError("Invalid preparation needs an error message.");
-        return { ok: false, issues: [{ severity: "error", parameterId: issueOrId, message }] };
-    }
-    if (issueOrId === null || typeof issueOrId !== "object" || issueOrId.severity !== "error")
-        throw new TypeError("Invalid preparation requires an error issue.");
-    return { ok: false, issues: [issueOrId] };
-}
-/** Wraps preparation with definition-bound services while preserving its exact result and value. */
-export function definePreparation(_definition, callback) {
-    return (parameters, services = UNPREPARED_GENERATOR_SERVICES) => callback(parameters, { ...services, invalid });
-}
-/** Parameter-only preparation is useful for models with no derived dimensions. */
-export function prepareIdentity(_definition) {
-    void _definition;
-    return prepared;
-}
 //# sourceMappingURL=authoring.js.map

package/dist/authoring.js.map

@@ -1 +1 @@
-{"version":3,"file":"authoring.js","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,6BAA6B,EAA0B,MAAM,yBAAyB,CAAC;AAEhG,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;AAED,mFAAmF;AACnF,MAAM,UAAU,QAAQ,CAAI,KAAQ;IAKlC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACzC,CAAC;AAkBD,MAAM,UAAU,OAAO,CACrB,SAAqE,EACrE,OAAgB;IAKhB,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,IAAI,OAAO,OAAO,KAAK,QAAQ;YAC7B,MAAM,IAAI,SAAS,CAAC,6CAA6C,CAAC,CAAC;QACrE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IACzF,CAAC;IACD,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,QAAQ,KAAK,OAAO;QACvF,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;IACtE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC;AAC5C,CAAC;AAwBD,oGAAoG;AACpG,MAAM,UAAU,iBAAiB,CAI/B,WAAc,EACd,QAGW;IAEX,OAAO,CAAC,UAAU,EAAE,QAAQ,GAAG,6BAA6B,EAAE,EAAE,CAC9D,QAAQ,CAAC,UAAU,EAAE,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAC7B,WAAc;IAEd,KAAK,WAAW,CAAC;IACjB,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"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"}

package/dist/contours.d.ts

@@ -0,0 +1,36 @@
+import { type CurveValueProblem } from "./curve-data.js";
+/** Maximum number of straight or cubic segments in an editable closed cross section. */
+export declare const MAX_CONTOUR_SEGMENTS = 32;
+/** Normalized planar coordinates, with X rightward and Y upward, in the unit square. */
+export interface ContourPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** Editing intent accompanies the explicit curve controls; no tangent is inferred at runtime. */
+export interface ContourAnchor extends ContourPoint {
+    readonly mode: "smooth" | "corner";
+}
+export type ContourSegment = {
+    readonly type: "line";
+    readonly end: ContourAnchor;
+} | {
+    readonly type: "cubic";
+    readonly control1: ContourPoint;
+    readonly control2: ContourPoint;
+    readonly end: ContourAnchor;
+};
+/** One explicitly closed planar contour. Generators own physical scaling and topology checks. */
+export interface ContourValue {
+    readonly version: 1;
+    readonly start: ContourAnchor;
+    readonly segments: readonly ContourSegment[];
+}
+/** Internal diagnostics share the accessor-safe reader used by predicates and cloning. */
+export declare function contourValueProblem(value: unknown): CurveValueProblem | undefined;
+/** Checks portable data and explicit closure without evaluating getters or inspecting topology. */
+export declare function isContourValue(value: unknown): value is ContourValue;
+/** Returns a fresh, deeply frozen closed contour, including its editing intent. */
+export declare function cloneContourValue(value: ContourValue): ContourValue;
+/** Compares the serialized shape and editing intent rather than object identity. */
+export declare function contourValuesEqual(previous: ContourValue, next: ContourValue): boolean;
+//# sourceMappingURL=contours.d.ts.map