@metamesh/generator-sdk 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @metamesh/generator-sdk
 
+## 0.7.0
+
+### Minor Changes
+
+- b1b97b9: Replace `ModelTimings.renderUploadMs` with optional `viewportPrepareMs` and `firstDrawMs` to
+  distinguish viewport preparation from the elapsed time to first draw submission. Consumers must
+  read the new fields; the combined metric is removed.
+
+## 0.6.0
+
+### Minor Changes
+
+- Replace format-1 validation/generation with exact format-2 prepare/build modules targeting runtime 2.0.0. Add opaque one-use preparation capture, lean authoring and host subpaths, integer numeric declarations, and canonical manufacturing output without normals.
+
 ## 0.5.2
 
 ### Patch Changes

package/README.md

@@ -1,51 +1,43 @@
 # `@metamesh/generator-sdk`
 
-Portable contracts and helpers shared by Studio, built-in generators, and workers.
+Runtime-neutral contracts and helpers for Generators, hosts, and workers.
 
-> **Preview:** `0.x` releases may contain breaking changes in a minor release. Patch releases are
-> intended to remain compatible within the same minor line. A stable support commitment begins only
-> after an explicit `1.0.0` review.
+> **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 the public package from npm:
+Install a published release from npm:
 
 ```bash
 pnpm add @metamesh/generator-sdk
 ```
 
-The package root exposes the Generator API. Use `@metamesh/generator-sdk/fonts` for only
-`FontSelection` and `isFontSelection`, without loading Generator services or Zod. Both exports
-remain available from the root.
+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:
 
-The package owns parameter/group definitions, serializable conditions, default derivation and
-normalization, structured validation, runtime envelopes, normalized generated-model results, and
-serializable catalog/package/install contracts. Project persistence belongs to Studio;
-release-state transitions belong to trusted database/tooling boundaries.
+| 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                                              |
 
-The optional `Export3mfRequest.partColors` map carries Project color overrides keyed by semantic
-part ID. Studio validates and applies it during export; it does not enter Generator parameters or
-change package generation contracts. Omitted overrides preserve generated colors.
-
-Zod is the only runtime dependency. The [public entry point](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/index.ts) owns exact exports;
-strict schemas own accepted boundary data. Hosts own package delivery and execution.
+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
 
-Definitions use the `type` discriminant with `number`, `slider`, `boolean`, `select`, `choice-set`,
-`color`, `text`, `font`, `svg`, `profile`, and homogeneous `array` variants. A `slider` requires `min`, `max`, and
-`step`, while a `number` may omit any of those constraints. Visibility uses serializable
-`ConditionExpression` values; `evaluateCondition` supports `all`, `any`, `not`,
-equality/inequality, numeric comparisons, and `choice-set` membership through `contains`.
+Parameters use a `type` discriminant: `number`, `slider`, `boolean`, `select`, `choice-set`, `color`,
+`text`, `font`, `svg`, `profile`, 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 once, then normalize saved values or strictly parse boundary values:
 
 ```ts
-import {
-  createParamCodec,
-  defineGenerator,
-  EMPTY_SVG_PARAMETER_DEFAULT,
-  prepareParameters,
-  type GeneratorParams,
-} from "@metamesh/generator-sdk";
+import { defineGenerator, type GeneratorParams } from "@metamesh/generator-sdk";
+import { createParamCodec, prepareParameters } from "@metamesh/generator-sdk/parameters";
 
 const definition = defineGenerator({
   id: "sleeve",
@@ -65,14 +57,16 @@ const workerValues: unknown = { outerDiameter: 24, boreDiameter: 10 };
 const strictParameters = createParamCodec(definition).parse(workerValues);
 ```
 
-Normalization drops unknown parameter-value keys, fills missing or invalid values from each
-parameter's declared `default`, clamps numbers, and returns a fresh frozen map. Strict codecs instead
-reject missing, unknown, invalid, or noncanonical values and return cloned frozen structured values.
-`prepareParameters()` normalizes once and returns that same canonical map with the combined schema
-and Generator-owned validation result. Definitions accept only canonical parameter types. SVG runtime values remain
-standard strings and are limited to 256 KiB each and 512 KiB per normalized project.
+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.
 
 ```ts
+import { EMPTY_SVG_PARAMETER_DEFAULT } from "@metamesh/generator-sdk/parameters";
+
 const profile = {
   id: "profile",
   label: "Profile",
@@ -81,11 +75,12 @@ const profile = {
 } as const;
 ```
 
-Choice-set definitions use fixed, uniquely valued options and a default array of selected option
-values. Optional `minSelections` and `maxSelections` bound the selection count. Normalized values
-are unique and use option declaration order; invalid values fall back to the canonical default.
-`{ param: "outputs", contains: "nut" }` may reference only a `choice-set` and one of its declared
-option values.
+### Choice sets and arrays
+
+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.
 
 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
@@ -106,58 +101,49 @@ const points = {
 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 the
-declared fonts before executable validation and generation. It supplies `GeneratorServices` as the
-second validator argument and third generation argument. `services.text.layout(text, { font,
-fontSize })` returns positioned vector curves and matching metrics in millimetres. Geometry's
-`withTextFonts(services.text, callback)` binds these services for `textContours()` and
-`textMetrics()` in compiled code. The SDK and Geometry keep their small structural text contracts
-compatible without importing each other's runtime. Font parameters and prepared text services require
-runtime `1.2.0` or later. Package format remains 1.
-
-`GeneratorDefinition` is callback-free, JSON-safe metadata used by forms, manifests, persistence,
-and normalization. Its `min`, `max`, options, and other field constraints are portable
-data. `defineGenerator()` preserves literal IDs and select options so `GeneratorParams`,
-`GeneratorParamId`, `GeneratorIssue`, validators, defaults, and presets derive from the definition.
-Keep derived-value, cross-parameter, warning, and geometry checks in a separate TypeScript
-validator:
-
-```ts
-import { defineValidator } from "@metamesh/generator-sdk";
+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.
 
-export const validate = defineValidator(definition, (parameters) => {
-  return parameters.outerDiameter - parameters.boreDiameter < 2
-    ? [{ severity: "error", parameterId: "boreDiameter", message: "Leave at least a 1 mm wall." }]
-    : [];
-});
-```
+### Validation and bounds
 
-`defineValidator()` preserves the callback's signature. Pass a parameter-only validator directly
-to `prepareParameters()` or `validateParameters()`. For a validator that needs runtime services,
-bind the prepared services explicitly: `(parameters) => validate(parameters, services)`. Use
+`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.
 
-Schema editors only receive `definition`; they never serialize, parse, or rewrite validators.
-Downloaded manifests remain callback-free and do not define a validation rules language. Runtime
-validation receives normalized, frozen values. Its issue array is strictly checked and bounded;
-malformed output is a runtime error rather than a user-facing validation result.
-Combined validation retains at most 100 issues, prioritizing errors over warnings while preserving
-the retained issues' original order. Reaching the reporting limit cannot hide a blocking error.
+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.
 
-Use `getDefaultParameters(definition)` to derive a fresh frozen defaults map. IDs are bounded safe keys; package
-manifests, definitions, descriptors, conditions, and nested parameter objects reject unknown fields.
+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.
+
+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.
 
 ### Editable side profiles
 
-A `profile` declares an open side outline as a versioned `ProfileValue`. Its start and each segment
-end are anchors with normalized `radius` and upward `height` coordinates, plus `mode` (`auto`,
-`smooth`, or `corner`) to retain editing intent. A segment is either `line` or `cubic`; cubic
-segments carry explicit `control1` and `control2` points. Explicit coordinates always define the
-shape; hosts must write resolved tangents into the controls when editing automatic points.
+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 = {
@@ -197,8 +183,7 @@ bindings leaves the editor in normalized coordinates.
 `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. Profile parameters require runtime `1.3.0` or later;
-package format remains `1`.
+them. Profiles cannot be condition operands. All executable packages use format `2` and runtime major `2`.
 
 ### Curve resolution
 
@@ -221,88 +206,107 @@ const curveDeviation = {
 } as const;
 ```
 
-Multiple controls per definition may have this role. Each requires `unit: "mm"`, a positive `default`,
-and an explicit positive `min`; existing numeric bounds and step rules still apply. Lower values
-request closer curve approximation. The Generator consumes the value in its physical
-`GeometryResolution` policy and retains local exact counts where topology requires them. Hosts
-edit the saved parameters directly and present their authored labels in definition order; preview
-and manufacturing use the same values. The Generator decides which curves or parts each parameter
-affects, including shared curves across several parts. Studio does not infer part overrides from
-mesh IDs. Resolution requests exceeding model complexity
-limits must fail explicitly instead of silently coarsening geometry.
-
-Packages declaring this role require runtime `1.3.0` or later and retain package format `1` and the
-existing five module exports. Definitions without the role retain their existing behavior.
+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()` assembles and freezes the exact five-field format-1 runtime surface from
-a typed definition, validator, and generator without coupling the SDK to a modeling library:
+`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
-const runtime = defineGeneratorModule<typeof definition, ModelingContext>({
+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,
-  validate,
-  generate,
+  prepare: prepareSleeve,
+  build: (dimensions) => tube({ ...dimensions, height: 20 }),
 });
 
-export const { formatVersion, generate, generatorId, validate, version } = runtime;
+export const { formatVersion, generatorId, version, prepare, build } = runtime;
 ```
 
-The author helper accepts definition-derived canonical parameters and adds neither runtime checking
-nor a parameter decoder. This keeps self-contained releases small and lets a host reuse the exact
-frozen map produced by `prepareParameters()`.
-`parseGeneratorModule(namespace, definition)` is the corresponding host-side boundary for evaluated
-packages: it requires exactly those five exports, verifies identity against the authoritative
-definition, wraps callbacks to enforce synchronous array results, and returns two frozen lanes. Use `canonical`
-only with host-prepared parameters; use `strict` for raw boundary values that must pass the host's
-codec. Extra exports fail closed.
-
-Hosts always invoke modules with `validate(parameters, services)` and
-`generate(parameters, context, services)`. Font-free hosts pass `UNPREPARED_GENERATOR_SERVICES`;
-font-dependent hosts prepare and pass the selected fonts before executable validation. Author
-callbacks may omit arguments they do not use.
-
-Generators with expensive SVG import, font layout, encoding, or dimension resolution may use
-`definePreparedGeneratorModule({ definition, prepare, generate })`. `prepare(parameters, services)`
-returns `{ ok: true, value, issues }` or `{ ok: false, issues }`, with definition-derived structured
-issues. Successful results may contain warnings but no errors; invalid results require an error.
-The model callback receives `generate(parameters, context, services, preparedValue)`. The returned
-module still exports exactly the same five fields and uses the unchanged host call signatures.
-
-Preparation accepts finite scalar data, plain objects, and arrays, which the helper checks and
-freezes. It rejects functions, accessors, cycles, promises, class instances, typed arrays, and live
-WASM objects, with traversal bounded to 1,000,000 values and 64 levels.
-
-The helper may reuse one successful validation result for the next generation when the exact
-deeply frozen parameters and frozen services/provider objects match. Different or mutable objects
-and direct generation prepare afresh; later calls and failures clear the retained result. Generators
-still own geometry complexity limits. See the [helper source](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/prepared-generator-module.ts) for
-the reuse checks.
-
-Call `parseGeneratedParts()` on executable output before downstream mesh work. It accepts only
-non-empty dense arrays of own data values containing uniquely identified parts backed by transferable `Float32Array` and
-`Uint32Array` storage, checks finite coordinates and valid indices, normalizes six-digit hex colors
-to lowercase, and enforces aggregate part, vertex, triangle, and backing-buffer byte limits. Closed-solid,
-manufacturing, and reconstruction checks remain Geometry or Generator responsibilities.
-
-Hosts should use `executeGenerator()` as the single synchronous execution seam. It normalizes raw
-values, runs schema and Generator validation, parses generated output, and returns either an explicit
-`invalid` result or a `generated` result. Hosts that prepare asynchronous services first can pass the
-`PreparedParameters` result to `executePreparedGenerator()`; malformed executable output remains a
-thrown runtime failure.
+`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.
 
 ## Worker boundary
 
-`ValidateRequest`, `GenerateRequest`, `Export3mfRequest`, and the `WorkerResponse` union carry
-monotonic request IDs. Validation errors are structured normal results; only actual worker,
-validator, generator, or exporter exceptions use error envelopes. `GeneratedModel` contains only
-structured data and transferable typed arrays—never live Manifold objects. A model can contain
-multiple `GeneratedPart` entries and includes bounds, warnings, and optional statistics. Studio
-supplies export filenames and the `MeshTopologyMode` selected in device preferences; generators supply semantic part
-IDs and colors. `original` preserves the generated final triangles, while `optimized` permits
-Studio's bounded planar-only topology pass after generation. This runtime choice is not a Generator
-parameter, package field, or persisted Project contract.
+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.
+
+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.
+
+`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.
+
+`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.
 
 ## Development
 

package/dist/authoring.d.ts

@@ -0,0 +1,57 @@
+import type { GeneratorDefinition, GeneratorIssue, GeneratorParams, GeneratorPreset, ParameterIssue } from "./contracts.js";
+import type { Preparation } from "./generator-module.js";
+import { type GeneratorServices } from "./generator-services.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

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"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"}

package/dist/authoring.js

@@ -0,0 +1,33 @@
+import { UNPREPARED_GENERATOR_SERVICES } from "./generator-services.js";
+/** Captures literal IDs and options; the host validates serializable metadata. */
+export function defineGenerator(definition) {
+    return definition;
+}
+/** Contextually types complete presets from the same definition as the controls. */
+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

@@ -0,0 +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"}