@metamesh/generator-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @metamesh/generator-sdk
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public Preview release of the Generator SDK contract.

package/LICENSE

@@ -0,0 +1,200 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice.
+
+   Copyright 2026 MetaMesh
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,187 @@
+# `@metamesh/generator-sdk`
+
+Portable contracts and helpers shared by Studio, built-in generators, 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.
+
+Install the public package from npm:
+
+```bash
+pnpm add @metamesh/generator-sdk
+```
+
+The package root is the only supported import path.
+
+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.
+
+Zod is its only runtime dependency and is used at untrusted package-data boundaries. The package
+root owns exact exports and its strict schemas own accepted shapes. Generator package delivery
+remains a separate host responsibility.
+
+## Parameter definitions
+
+Definitions use the `type` discriminant with `number`, `slider`, `boolean`, `select`, `choice-set`,
+`color`, `text`, `svg`, 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`.
+
+Given a Generator `definition` and untrusted `persistedValues`:
+
+```ts
+import {
+  createParamCodec,
+  decodeParameterState,
+  defineGenerator,
+  EMPTY_SVG_PARAMETER_DEFAULT,
+  encodeParameterState,
+  prepareParameters,
+  type GeneratorParams,
+} from "@metamesh/generator-sdk";
+
+const definition = defineGenerator({/* serializable definition */});
+type Parameters = GeneratorParams<typeof definition>;
+
+const { parameters, validation } = prepareParameters(definition, persistedValues);
+const strictParameters = createParamCodec(definition).parse(workerValues);
+const query = encodeParameterState(definition, parameters);
+const restored = decodeParameterState(definition, query);
+```
+
+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 arrays.
+`prepareParameters()` normalizes once and returns that same canonical map with the combined schema
+and Generator-owned validation result. Definitions accept only canonical parameter types. URL
+state is versioned and only includes known non-default values.
+Malformed, obsolete, or invalid URL values safely fall back to defaults. SVG runtime values remain
+standard strings, are limited to 256 KiB each and 512 KiB per normalized project, and are omitted
+from parameter URLs. URL scalars overlay a host-supplied persisted base so device-local SVG values
+are never erased by a shared URL.
+
+```ts
+const profile = {
+  id: "profile",
+  label: "Profile",
+  type: "svg",
+  default: EMPTY_SVG_PARAMETER_DEFAULT,
+} 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.
+
+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, and URL state encodes them as deterministic
+JSON without changing scalar URL encoding. Conditions may compare scalar controls or test
+`choice-set` membership; arbitrary arrays cannot be condition operands.
+
+```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.
+
+`GeneratorDefinition` is callback-free, JSON-safe metadata used by forms, manifests, persistence,
+normalization, and URL state. 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";
+
+export const validate = defineValidator(definition, (parameters) => {
+  return parameters.outerDiameter - parameters.boreDiameter < 2
+    ? [{ severity: "error", parameterId: "boreDiameter", message: "Leave at least a 1 mm wall." }]
+    : [];
+});
+```
+
+Pass the validator to `prepareParameters()` or `validateParameters()`. 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.
+
+Definitions do not contain a second defaults map. Use `getDefaultParameters(definition)`
+to derive a fresh frozen value map from parameter definitions. 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. Strict rejection
+is intentional so obsolete or pathological package shapes cannot be mistaken for the current
+contract.
+
+## 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:
+
+```ts
+const runtime = defineGeneratorModule<typeof definition, ModelingContext>({
+  definition,
+  validate,
+  generate,
+});
+
+export const { formatVersion, generate, generatorId, validate, version } = 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.
+
+Call `parseGeneratedParts()` on executable output before downstream mesh work. It accepts only
+non-empty arrays of 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.
+
+## 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 session-local `MeshTopologyMode`; 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.
+
+## Constraints
+
+- No React, Zustand, Three.js, Manifold, DOM, or Web Worker dependencies.
+- Public data crossing a worker or persistence boundary must be serializable, except explicitly
+  transferable typed-array buffers.
+- Conditions are data expressions, not callbacks.
+- Validation returns structured issues rather than UI-ready strings or thrown user errors.
+
+## License
+
+Apache-2.0. The complete terms are included in `LICENSE`.

package/dist/conditions.d.ts

@@ -0,0 +1,35 @@
+import type { ParameterValues, ScalarParameterValue } from "./contracts.js";
+export type ConditionExpression = {
+    readonly all: readonly ConditionExpression[];
+} | {
+    readonly any: readonly ConditionExpression[];
+} | {
+    readonly not: ConditionExpression;
+} | {
+    readonly param: string;
+    readonly eq: ScalarParameterValue;
+} | {
+    readonly param: string;
+    readonly ne: ScalarParameterValue;
+} | {
+    readonly param: string;
+    readonly contains: string;
+} | {
+    readonly param: string;
+    readonly gt: number;
+} | {
+    readonly param: string;
+    readonly gte: number;
+} | {
+    readonly param: string;
+    readonly lt: number;
+} | {
+    readonly param: string;
+    readonly lte: number;
+};
+/**
+ * Evaluates a serializable visibility condition. A comparison against a
+ * missing parameter is always false, including `ne`.
+ */
+export declare function evaluateCondition(condition: ConditionExpression, parameters: ParameterValues): boolean;
+//# sourceMappingURL=conditions.d.ts.map

package/dist/conditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE5E,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,mBAAmB,EAAE,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,mBAAmB,EAAE,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,GACrC;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,oBAAoB,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,oBAAoB,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,mBAAmB,EAC9B,UAAU,EAAE,eAAe,GAC1B,OAAO,CAgDT"}

package/dist/conditions.js

@@ -0,0 +1,42 @@
+/**
+ * Evaluates a serializable visibility condition. A comparison against a
+ * missing parameter is always false, including `ne`.
+ */
+export function evaluateCondition(condition, parameters) {
+    if ("all" in condition) {
+        return condition.all.every((child) => evaluateCondition(child, parameters));
+    }
+    if ("any" in condition) {
+        return condition.any.some((child) => evaluateCondition(child, parameters));
+    }
+    if ("not" in condition) {
+        return !evaluateCondition(condition.not, parameters);
+    }
+    if (!Object.hasOwn(parameters, condition.param)) {
+        return false;
+    }
+    const value = parameters[condition.param];
+    if ("eq" in condition) {
+        return Object.is(value, condition.eq);
+    }
+    if ("ne" in condition) {
+        return !Object.is(value, condition.ne);
+    }
+    if ("contains" in condition) {
+        return Array.isArray(value) && value.includes(condition.contains);
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return false;
+    }
+    if ("gt" in condition) {
+        return value > condition.gt;
+    }
+    if ("gte" in condition) {
+        return value >= condition.gte;
+    }
+    if ("lt" in condition) {
+        return value < condition.lt;
+    }
+    return value <= condition.lte;
+}
+//# sourceMappingURL=conditions.js.map

package/dist/conditions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.js","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAA8B,EAC9B,UAA2B;IAE3B,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;QACvB,OAAO,CAAC,iBAAiB,CAAC,SAAS,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACvD,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAE1C,IAAI,IAAI,IAAI,SAAS,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,IAAI,IAAI,SAAS,EAAE,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,UAAU,IAAI,SAAS,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACpE,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,IAAI,IAAI,SAAS,EAAE,CAAC;QACtB,OAAO,KAAK,GAAG,SAAS,CAAC,EAAE,CAAC;IAC9B,CAAC;IAED,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;QACvB,OAAO,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC;IAChC,CAAC;IAED,IAAI,IAAI,IAAI,SAAS,EAAE,CAAC;QACtB,OAAO,KAAK,GAAG,SAAS,CAAC,EAAE,CAAC;IAC9B,CAAC;IAED,OAAO,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC;AAChC,CAAC"}

package/dist/contracts.d.ts

@@ -0,0 +1,160 @@
+import type { ParameterGroup, GeneratorDefinition as ParsedGeneratorDefinition } from "./generator-package/schemas/definition.schema.js";
+import type { ArrayParameterDefinition, BooleanParameterDefinition, ChoiceSetParameterDefinition, ColorParameterDefinition, NumberArrayItemDefinition, NumberArrayParameterDefinition, NumberParameterDefinition, NumericParameterDefinition, ParameterDefinition, SelectOption, SelectParameterDefinition, SliderParameterDefinition, StringArrayItemDefinition, StringArrayParameterDefinition, SvgParameterDefinition, TextParameterDefinition } from "./generator-package/schemas/parameter.schema.js";
+import type { GeneratorRuntimeReference } from "./generator-packages.js";
+export type { ArrayParameterDefinition, BooleanParameterDefinition, ChoiceSetParameterDefinition, ColorParameterDefinition, NumberArrayItemDefinition, NumberArrayParameterDefinition, NumberParameterDefinition, NumericParameterDefinition, ParameterDefinition, ParameterGroup, SelectOption, SelectParameterDefinition, StringArrayItemDefinition, StringArrayParameterDefinition, SvgParameterDefinition, SliderParameterDefinition, TextParameterDefinition, };
+export type ScalarParameterValue = number | boolean | string;
+export type ParameterValue = ScalarParameterValue | readonly number[] | readonly string[];
+export type ParameterValues = Readonly<Record<string, ParameterValue>>;
+type ParameterValueFor<Parameter extends ParameterDefinition> = Parameter extends {
+    readonly type: "number" | "slider";
+} ? number : Parameter extends {
+    readonly type: "boolean";
+} ? boolean : Parameter extends {
+    readonly type: "select";
+    readonly options: readonly {
+        readonly value: infer Value extends string;
+    }[];
+} ? Value : Parameter extends {
+    readonly type: "choice-set";
+    readonly options: readonly {
+        readonly value: infer Value extends string;
+    }[];
+} ? readonly Value[] : Parameter extends {
+    readonly type: "array";
+    readonly items: infer Items;
+} ? Items extends {
+    readonly type: "number";
+} ? readonly number[] : readonly string[] : string;
+/** Exact normalized parameter values derived from a Generator definition. */
+export type GeneratorParams<D extends GeneratorDefinition> = {
+    readonly [Parameter in D["parameters"][number] as Parameter["id"]]: ParameterValueFor<Parameter>;
+};
+/** The declared parameter ID union for a Generator definition. */
+export type GeneratorParamId<D extends GeneratorDefinition> = Extract<D["parameters"][number]["id"], string>;
+export type BaseParameterDefinition = Pick<NumericParameterDefinition, "id" | "label" | "description" | "group" | "unit" | "visibleWhen">;
+export type ParameterIssueSeverity = "error" | "warning";
+export interface ParameterIssue {
+    readonly severity: ParameterIssueSeverity;
+    readonly parameterId?: string;
+    readonly message: string;
+}
+/** A validation issue whose optional parameter ID is tied to one definition. */
+export type GeneratorIssue<D extends GeneratorDefinition = GeneratorDefinition> = Omit<ParameterIssue, "parameterId"> & {
+    readonly parameterId?: GeneratorParamId<D>;
+};
+export interface ParameterValidationResult {
+    readonly isValid: boolean;
+    readonly issues: readonly ParameterIssue[];
+    readonly errors: readonly ParameterIssue[];
+    readonly warnings: readonly ParameterIssue[];
+}
+/**
+ * JSON-safe generator identity and parameter metadata.
+ *
+ * This is the contract used by forms, persistence, URL state, and package
+ * manifests. Basic per-field constraints belong here; executable validation
+ * deliberately does not.
+ */
+export type GeneratorDefinition = ParsedGeneratorDefinition;
+/** Executable, generator-owned cross-parameter and geometry validation. */
+export type GeneratorValidator<D extends GeneratorDefinition = GeneratorDefinition> = (parameters: GeneratorParams<D>) => readonly GeneratorIssue<D>[];
+export type Vec3 = readonly [number, number, number];
+export interface ModelBounds {
+    readonly min: Vec3;
+    readonly max: Vec3;
+}
+export interface ModelStats {
+    readonly triangles?: number;
+    readonly vertices?: number;
+    readonly generationMs?: number;
+    readonly volumeMm3?: number;
+}
+/** Selects whether Studio preserves or locally improves final planar triangle connectivity. */
+export type MeshTopologyMode = "original" | "optimized";
+export interface GeneratedPart {
+    readonly id: string;
+    readonly positions: Float32Array;
+    readonly indices: Uint32Array;
+    readonly normals?: Float32Array;
+    readonly color?: string;
+}
+export interface GeneratedModel {
+    readonly requestId: number;
+    readonly parts: readonly GeneratedPart[];
+    readonly bounds: ModelBounds;
+    readonly stats?: ModelStats;
+    readonly warnings: readonly ParameterIssue[];
+}
+export interface GenerateRequest {
+    readonly type: "generate";
+    readonly requestId: number;
+    readonly generatorId: string;
+    readonly meshTopologyMode: MeshTopologyMode;
+    readonly runtime: GeneratorRuntimeReference;
+    readonly parameters: ParameterValues;
+}
+export interface ValidateRequest {
+    readonly type: "validate";
+    readonly requestId: number;
+    readonly generatorId: string;
+    readonly runtime: GeneratorRuntimeReference;
+    readonly parameters: ParameterValues;
+}
+export interface Export3mfRequest {
+    readonly type: "export-3mf";
+    readonly requestId: number;
+    readonly generatorId: string;
+    readonly filename: string;
+    readonly meshTopologyMode: MeshTopologyMode;
+    readonly runtime: GeneratorRuntimeReference;
+    readonly parameters: ParameterValues;
+}
+export interface ValidationSuccess {
+    readonly type: "validation-success";
+    readonly requestId: number;
+    readonly validation: ParameterValidationResult;
+}
+export interface GenerationSuccess {
+    readonly type: "generation-success";
+    readonly requestId: number;
+    readonly model: GeneratedModel;
+}
+export interface GenerationInvalid {
+    readonly type: "generation-invalid";
+    readonly requestId: number;
+    readonly validation: ParameterValidationResult;
+}
+export interface ExportedFile {
+    readonly bytes: ArrayBuffer;
+    readonly filename: string;
+    readonly mimeType: "model/3mf";
+}
+export interface ExportSuccess {
+    readonly type: "export-success";
+    readonly requestId: number;
+    readonly file: ExportedFile;
+}
+export interface RuntimeError {
+    readonly code: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly recoverable?: boolean;
+}
+export interface GenerationError {
+    readonly type: "generation-error";
+    readonly requestId: number;
+    readonly error: RuntimeError;
+}
+export interface ExportError {
+    readonly type: "export-error";
+    readonly requestId: number;
+    readonly error: RuntimeError;
+}
+export interface ValidationError {
+    readonly type: "validation-error";
+    readonly requestId: number;
+    readonly error: RuntimeError;
+}
+export type WorkerRequest = ValidateRequest | GenerateRequest | Export3mfRequest;
+export type WorkerResponse = ValidationSuccess | GenerationSuccess | GenerationInvalid | ExportSuccess | ValidationError | GenerationError | ExportError;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

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

package/dist/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":""}