@metamesh/generator-sdk 0.11.0 → 0.13.0

package/dist/docs/guides/parameters.md

@@ -0,0 +1,429 @@
+# Define parameters and validation
+
+Define model controls, side profiles, closed cross sections, fonts, conditional visibility, and cross-field validation for an authored Project.
+
+A reusable code Project exposes meaningful design decisions through controls. Studio stores the
+control definition as JSON-safe Project data, types `params` through the imported `generate`
+helper, and runs executable cross-field validation from `model.ts`.
+
+The JSON document contains required `groups` and `parameters` arrays. A parameter's `type`,
+default, units, bounds, and choices describe its value. Its optional `ui` object describes
+presentation: group, shared row, hint, visibility, editing increment, and physical editor bindings.
+Number and Slider both use `type: "number"`; a Slider also declares `ui.control: "slider"`.
+Options use `type: "choice"`, Side profile uses `type: "side-profile"`, and a closed outline uses
+`type: "contour"`. Changing a numeric widget does not change its saved value or valid range.
+
+JSON editing provides field completion, help, and inline validation. Reference completion suggests
+declared groups, parameters, and choice values. Errors prevent applying the draft; returning to
+Visual requires fixing or discarding invalid JSON.
+For other editors, the SDK ships `@metamesh/generator-sdk/parameters.schema.json`; the SDK parser
+also checks cross-field rules that JSON Schema cannot express.
+
+## Open the control editor
+
+In an authored Project, open the parameter panel's **Parameter actions** menu and choose
+**Edit controls**. The same action is available in the **MetaMesh menu → Current project** group.
+The Model controls editor's **Visual** and **JSON** views edit the same draft. Choose
+**Apply & return** to commit it and return to the model.
+
+1. Add a section for one coherent decision, such as **Size** or **Outputs**.
+2. Add a control, give it a stable ID, a plain-language label, and a useful default.
+3. Add units and field limits where they carry real meaning.
+4. Try the selected control in its preview, then apply the draft and check the generated
+   `params` completion in `model.ts`.
+
+Preview values are temporary; they do not change the default or the Project's current values.
+
+Use labels to name the decision and descriptions for supplementary help. Defaults should produce a useful model immediately;
+minimum and maximum values should describe the supported input range rather than compensate for a
+missing cross-field rule.
+
+## Separate help from essential instructions
+
+Keep `description` for explanations, terminology, and examples. Studio shows it on demand when the
+user hovers, focuses, or taps the question-mark help button. Clicking the label focuses the input;
+hovering it does not open help.
+Use one optional static `ui.hint` for a short, essential instruction shown inline whenever the
+control is visible. Omit it when the label is enough. Put guidance covering multiple modes in
+`description`; hints have no conditions. Errors, warnings, and explanations for unavailable
+controls remain visible too.
+
+In **Visual**, edit **Hint (optional)** as ordinary text. **Visual**, **JSON**, and the live preview
+use the same string field. Clearing it omits the hint when applying the definition. For example,
+a socket-only Diameter control can include:
+
+```json
+{
+  "description": "The dimension before fit allowance.",
+  "ui": { "hint": "Measure the mating part's outside diameter." }
+}
+```
+
+For a control shared by socket and spigot modes, omit the hint and explain both measurements in
+its description: measure the mating part's outside diameter for a socket or the opening's inside
+diameter for a spigot. Add this metadata to the existing control object. Keep hints short and
+avoid repeating labels, units, or descriptions. A declared hint must be non-empty and at most
+4,096 characters. Generator packages use format `4` and runtime major `5`.
+
+## Choose the right control
+
+| Studio control           | Use it for                                                      |
+| ------------------------ | --------------------------------------------------------------- |
+| Number or Slider         | Dimensions, counts, and bounded continuous values               |
+| Toggle                   | A feature that is either enabled or disabled                    |
+| Options                  | Exactly one value from a fixed supported set                    |
+| Multiple choice          | A supported subset of fixed options, such as named outputs      |
+| Color                    | An exact six-digit sRGB preview or part color                   |
+| Text                     | Wording or another string consumed by the model                 |
+| Font                     | An exact catalog face and weight for generated text             |
+| SVG                      | Editable vector artwork consumed as an SVG string               |
+| Side profile             | An editable side outline for a handle, knob, or revolved shape  |
+| Cross section            | One closed XY outline for extrusion or a swept section          |
+| Number List or Text List | An ordered sequence the user may add, remove, edit, and reorder |
+
+A Slider requires `min`, `max`, and a positive `ui.step`. Multiple choice may require a minimum or maximum
+selection count. List controls can bound their item count; number-list items can also have their own
+unit, limits, and `items.ui.step`.
+
+A Font value is a structured selection, not a family-name string. Pass the whole value in
+`services.text.layout(text, { font, fontSize })` inside generation, then pass its layout to
+`textSection(layout)`. Studio loads declared fonts before generation. See the
+[text recipe](https://metamesh.studio/docs/develop/geometry-recipes#text-from-a-font-parameter) for the setup and offline
+limits.
+
+## Show controls side by side
+
+Use shared rows for related dimensions, short choices, or text values. In **Visual**, select a
+Number, Options, or Text control and set **Placement** to **Beside previous**. **Own row** is the
+default. Two adjacent controls in the same section can share a row, including mixed types.
+
+In **JSON**, give the controls the same `ui.row` identifier:
+
+```json
+[
+  {
+    "id": "width",
+    "label": "Width",
+    "type": "number",
+    "default": 100,
+    "unit": "mm",
+    "ui": {
+      "row": "size"
+    }
+  },
+  {
+    "id": "height",
+    "label": "Height",
+    "type": "number",
+    "default": 80,
+    "unit": "mm",
+    "ui": {
+      "row": "size"
+    }
+  }
+]
+```
+
+These entries belong in the definition's `parameters` array. Row identifiers are local to each
+section, and controls in a row must remain adjacent within that section. Omit `ui.row` for an ordinary
+full-width control. Shared rows support number inputs, `choice`, and `text`; sliders and other control types use
+their own rows. Prefer full width for long option names or text values.
+
+Shared fields have equal widths and compact labels. They stack when the panel is too
+narrow, and hidden fields leave space for the remaining row members. Each field keeps its own
+value, units, validation, and history; `params.width` and `params.height` remain
+separate numbers.
+
+## Define an editable side profile
+
+Add a **Side profile** control when the model needs an outer silhouette. Its **Edit side profile** action
+opens guided points with automatic smoothing, Bézier handles, straight/curved segments,
+and numeric editing. Select a segment directly; double-click it to insert a point at that location.
+Choosing **Curve** reveals handles while retaining the existing shape until a handle moves.
+The Model controls editor uses the same editor for the default outline.
+**Apply profile** changes only the draft being edited; choose **Apply & return** to commit the
+control definition.
+
+The value on `params` is a readonly `SideProfileValue`, with a start anchor and line or cubic
+segments. It contains normalized radius/height coordinates rather than SVG markup or sampled
+vertices. Its parameter type is `side-profile`. This is a complete control you can add in **JSON**:
+
+```json
+{
+  "id": "sideProfile",
+  "type": "side-profile",
+  "label": "Side profile",
+  "default": {
+    "version": 1,
+    "start": {
+      "radius": 0.4,
+      "height": 0,
+      "mode": "auto"
+    },
+    "segments": [
+      {
+        "type": "cubic",
+        "control1": {
+          "radius": 0.4,
+          "height": 0.35
+        },
+        "control2": {
+          "radius": 1,
+          "height": 0.75
+        },
+        "end": {
+          "radius": 0.6,
+          "height": 1,
+          "mode": "auto"
+        }
+      }
+    ]
+  }
+}
+```
+
+Coordinates lie between `0` and `1`. The first height is `0`, the last is `1`, and points progress
+upward. Cubic controls also progress upward between their endpoints. A profile supports up to 32
+points. **Auto** computes tangents when points change; **Smooth** links their directions;
+**Corner** lets handles move independently. Explicit control coordinates define the saved shape.
+
+In **Physical dimensions (optional)**, link the radius and height to existing Number or Slider
+controls with unit `mm`, a positive default, and a positive minimum. A radius factor of `0.5` uses
+half a diameter control. The corresponding JSON fields are `ui.radiusScale` and `ui.heightScale`, each
+with `parameterId` and a positive `factor`. These bindings set editor measurements; your source
+still applies the same physical scales when modeling. The envelope describes the available size:
+an outline reaching half the radius envelope produces half its diameter. The editor also shows
+the actual maximum diameter.
+
+Use [`sampleSideProfile()`](https://metamesh.studio/docs/reference/geometry/sampleSideProfile) to convert
+`params.sideProfile` to an open `[radius, height]` polyline, supplying the physical radius
+and height scales. Your model then closes the outline and uses
+[`section.revolve()`](https://metamesh.studio/docs/reference/model/Section#revolve) on a filled Section to create the solid. Keep the mounting connection,
+minimum walls, bore clearance, and other manufacturing rules in generation.
+The side profile supports one upward open silhouette, with fixed bottom/top heights and strictly
+increasing interior heights. Use a [Cross section](#define-an-editable-cross-section) for a closed
+planar outline; holes and imported artwork remain separate modeling choices.
+
+## Define an editable cross section
+
+Add a **Cross section** control for one closed XY outline. **Edit cross section** lets the user
+select points and segments, edit coordinates, and shape explicit Bézier handles. The default uses
+the same editor. **Corner** leaves handles independent; **Smooth** links their directions.
+
+`params` receives a readonly `ContourValue`. Every `x` and upward `y` coordinate,
+including cubic controls, lies in `[0, 1]`. It has 2–32 line or cubic segments. The final endpoint
+repeats the start's coordinates and mode, so the seam remains one editable point. This unscaled
+square control can be added in **JSON**:
+
+```json
+{
+  "id": "crossSection",
+  "type": "contour",
+  "label": "Cross section",
+  "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"
+        }
+      }
+    ]
+  }
+}
+```
+
+Link **Width** and **Height** in **Physical dimensions (optional)** to positive `mm` Number or
+Slider controls with explicit positive minima. JSON uses `ui.widthScale` and `ui.heightScale`, each
+with a `parameterId` and positive `factor`, such as `{ "parameterId": "width", "factor": 1 }`.
+Bindings describe the coordinate envelope; they never rescale the saved value. Without them,
+the editor displays percentages.
+
+Inside generation or a computed value, pass `params.crossSection` to
+[`sampleContour()`](https://metamesh.studio/docs/reference/geometry/sampleContour) with physical `widthScale`,
+`heightScale`, and a millimetre resolution policy. It returns an immutable counterclockwise
+XY `Contour` without a duplicated seam, rejecting invalid sampled topology and exhausted budgets.
+Reuse that contour in generation, create a filled Section with
+[`polygon(contour)`](https://metamesh.studio/docs/reference/model/polygon), and use
+[`section.extrude()`](https://metamesh.studio/docs/reference/model/Section#extrude) or [`section.sweep()`](https://metamesh.studio/docs/reference/model/Section#sweep) for the solid.
+The Generator owns extrusion depth, the sweep path, fit, walls, and manufacturing rules.
+Data validation checks the bounded structure and closure; it does not establish those geometric
+requirements. This control contains one contour without holes or multiple loops.
+
+Side-profile and cross-section edits stay local until **Apply**. Workspace editors check the
+current draft with Generator declaration and reached assertions before applying it; errors block Apply and warnings
+remain visible. Failed checks offer **Retry draft check**. Editing a control default changes its
+definition draft, so check the current model after **Apply & return**.
+
+<a id="expose-curve-resolution-in-the-viewport"></a>
+
+## Expose Curve resolution in Parameters
+
+In **JSON**, add `"role": "curve-resolution"` to a Number or Slider control to group it under
+**Parameters → Curve resolution**. Use millimetres, a positive default, and an explicit positive minimum:
+
+```json
+{
+  "id": "curveResolution",
+  "type": "number",
+  "label": "Maximum curve deviation",
+  "role": "curve-resolution",
+  "unit": "mm",
+  "default": 0.05,
+  "min": 0.01,
+  "max": 0.1,
+  "ui": {
+    "step": 0.01
+  }
+}
+```
+
+The control remains a saved parameter on `params`. Your source must apply it to geometry,
+for example by passing `resolution: { maxChordError: params.curveResolution }` to each
+affected primitive or Section operation. Share that ordinary options value where several curves
+use the same policy. The declaration alone
+does not change sampling. Keep supported limits and any feature-specific sampling in your model.
+
+Studio groups these fields under **Curve resolution** in Parameters, including the mobile sheet
+where draft validation errors can be corrected. The chosen value affects preview and export through
+the same generation path. Visual editing
+preserves the role; duplicating the control creates an ordinary numeric control. A Project may
+declare multiple Curve resolution controls, shown together in definition order.
+For example, declare separate **Coil path** and **Wire cross-section** values and pass each to the
+appropriate sampler. Your Generator decides which curves or parts each value affects; Studio saves
+the values without assigning them to parts automatically.
+
+## Reveal a control only when it applies
+
+Use **JSON** for advanced metadata such as `ui.visibleWhen`. The Visual view preserves supported
+metadata it does not expose. Add the condition to the existing control object in the `parameters`
+array; this example shows Hole diameter only while Add hole is enabled:
+
+```json
+{
+  "id": "holeDiameter",
+  "type": "number",
+  "label": "Hole diameter",
+  "default": 12,
+  "min": 1,
+  "max": 28,
+  "unit": "mm",
+  "ui": {
+    "visibleWhen": {
+      "param": "addHole",
+      "eq": true
+    },
+    "step": 0.5
+  }
+}
+```
+
+Use `eq` or `ne` for scalar comparisons, `gt`, `gte`, `lt`, or `lte` for numbers, and `contains`
+for Multiple choice membership. Combine conditions with `all`, `any`, or `not`. Font, Side profile, Cross section,
+Number List, and Text List values cannot be the referenced value in a condition.
+
+The JSON root accepts only `groups` and `parameters`. Project identity, title, and version are
+managed separately by Studio.
+
+Visibility is presentation, not data deletion. Source still receives the control's normalized value.
+Generation decides whether it matters in the current mode; assertions and geometry follow that choice.
+
+## Add cross-field validation in TypeScript
+
+The generation callback receives normalized readonly parameters. Put a cheap assertion before
+geometry when a combination cannot produce a supported model:
+
+
+
+```ts
+assert(
+    !params.addHole || params.holeDiameter < Math.min(params.width, params.depth),
+    "Hole diameter must be smaller than the body width and depth.",
+    { parameterId: "holeDiameter" }
+  );
+```
+
+
+
+`assert(condition, message, { parameterId? })` stops on the first false condition. The parameter ID
+is checked against your controls and tells the user where to make a correction. Successful assertions
+return normally. For a valid result with a meaningful caution, use a warning in the outer callback:
+
+```ts
+assert(params.wall > 0, "Wall thickness must be positive.", { parameterId: "wall" });
+if (params.wall < 1) warn("This wall may be difficult to print.", { parameterId: "wall" });
+```
+
+A zero wall stops generation; a 0.5 mm wall generates with a warning. A failed edit leaves the last
+valid preview and its export available. Warnings allow a current model to generate and export.
+
+Checks run in JavaScript order. Reading a computed value evaluates it when necessary, and a
+geometry observation must realize its input first. This also applies to draft validation: it runs
+declaration and reached assertions, without finalizing the returned parts. It does not prove full
+geometric validity. Keep exact layouts and shared dimensions in optional `computed` values so
+unrelated edits do not repeat expensive work. There is no separate preparation callback.
+
+## Test the definition as a contract
+
+Before relying on a Project, check:
+
+- defaults generate a useful model with no error;
+- each numeric minimum and maximum produces the intended boundary result;
+- hidden controls become visible under the right condition;
+- essential hints stay inline, while supplementary help is available by keyboard and tap;
+- every fixed-choice and allowed multiple-choice combination behaves intentionally;
+- empty, minimum, and maximum list lengths are handled;
+- edited side profiles and cross sections affect the solid and keep required clearances and walls;
+- cross-field errors identify the control the user should change;
+- warnings still generate and export the expected current model; and
+- resetting controls returns to the documented defaults.
+
+The Model controls editor checks the definition when you apply it and keeps invalid drafts open
+with errors to correct. After **Apply & return**, Studio uses the updated definition for controls,
+normalization, persistence, and the typed generation context. It then validates the current values
+with `model.ts`; check the workspace for source or cross-field errors before exporting.
+
+
+
+**Keep executable rules in model.ts**
+
+JSON mode defines serializable controls and visibility. Derived calculations, geometry checks, and
+  cross-field messages belong in `generate`; do not invent a second executable rules language inside
+  the Project definition.
+
+
+
+- [Read the source contract](https://metamesh.studio/docs/develop/code-project-contract)
+- [See the user experience](https://metamesh.studio/docs/use/parameters)