@metamesh/generator-sdk 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @metamesh/generator-sdk
 
+## 0.14.0
+
+### Minor Changes
+
+- be565ad: Add native `stroke()` sections and pure `closestPointOnPath()` queries. Correct face-sized
+  circular sampling and odd-pinion internal gear motion. Native stroke uses the current runtime
+  contract so older hosts reject packages requiring the new operation before execution.
+
+## 0.13.0
+
+### Minor Changes
+
+- 2ebe03f: Ship exact-version offline documentation and a development-only authoring CLI for semantic
+  checking, generation, captured geometry inspection, and explicit Chromium previews. Use exact
+  package versions in documentation metadata and reject unsupported authoring artifact formats.
+  Provide generated command help and strict per-command argument validation, and enforce semantic
+  checking even when the consumer's TypeScript configuration disables it.
+
+  Publish lightweight model and Generator testing helpers as `@metamesh/testkit`. Move the
+  `metamesh` executable and Node authoring API into `@metamesh/cli`, which owns compiler, bundler,
+  renderer, and browser dependencies. Remove the former package name and authoring entry from
+  Testkit without compatibility aliases.
+
+- 7e1b75d: Simplify modeling authoring with `polygon` construction, shared bounds and vector text fitting,
+  Section patterns, pure pattern transforms, and explicit profile closure and part layout helpers.
+  Zero-sized round, chamfer, and smooth treatments preserve untreated geometry.
+
+  Replace the public geometry vocabulary with `Vector2`, `Vector3`, `Contour`, `Polygon`, and
+  `Region`, and use canonical `Bounds2` and `Bounds3` throughout. Remove retired constructor and
+  type names. Bundles require runtime major 5 and the generation realm uses protocol 5; older
+  runtime packages reject before execution. The package envelope remains format 4.
+
 ## 0.12.0
 
 No changes in this release.

package/README.md

@@ -1,32 +1,30 @@
 # `@metamesh/generator-sdk`
 
-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.
+Turn a parametric model into a MetaMesh Generator. Define controls once, infer their TypeScript
+types, and use the same parameter contract for forms, saved values, and execution.
 
 > **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.
+> same minor line.
+
+## Installation
 
 ```bash
 pnpm add @metamesh/generator-sdk
 ```
 
-| 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                                      |
+The SDK is renderer-neutral. To build geometry in the example below, also install
+[`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/packages/modeling/README.md).
+Keep installed MetaMesh packages on the same exact release.
 
 ## Define controls
 
-A definition is serializable metadata. Capture its literal IDs and options to derive exact
-parameter types:
+A definition describes the Generator and its editable parameters. Literal IDs and options give
+you exact parameter types:
 
 ```ts
 import { defineGenerator, type GeneratorParams } from "@metamesh/generator-sdk";
 
-const definition = defineGenerator({
+export const definition = defineGenerator({
   id: "sleeve",
   version: "0.1.0",
   title: "Sleeve",
@@ -39,81 +37,85 @@ const definition = defineGenerator({
 type Parameters = GeneratorParams<typeof definition>;
 ```
 
-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.
-
-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`.
-
-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.
+Definitions are serializable. Optional `ui` metadata describes grouping, visibility, hints, and
+editing increments. Number inputs and sliders share `type: "number"`; sliders add
+`ui.control: "slider"`, bounds, and `ui.step`. See the
+[parameter guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx)
+for the full set of controls.
 
 ## Generate a model
 
-A Generator exports one format-4 default envelope containing its definition-bound program:
+Add a synchronous generation program to the same module. Assertions describe relationships
+between controls; the module helper binds the program to its definition:
 
 ```ts
-import { defineGeneratorModule, type GeneratorParams } from "@metamesh/generator-sdk";
+import { defineGeneratorModule } from "@metamesh/generator-sdk";
 import { generate, tube } from "@metamesh/modeling";
 
-const model = generate<GeneratorParams<typeof definition>>(({ params, assert, part }) => {
+const model = generate<Parameters>(({ 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,
-      })
-    ),
-  ];
+  return part(
+    "body",
+    tube({
+      outerRadius: params.outerDiameter / 2,
+      innerRadius: params.boreDiameter / 2,
+      height: 20,
+    })
+  );
 });
 export default defineGeneratorModule({ definition, generate: model });
 ```
 
-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.
+Return a single `part(...)` or a readonly array of parts. The host normalizes parameters and prepares
+assets before generation. Modeling manages geometry, sessions, and snapshots; the SDK provides
+portable definitions, module envelopes, and validated runtime messages. Unsupported package formats
+reject before executable bytes are evaluated.
 
-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.
+## Work with saved values
 
-## Documentation
+Use `normalizeParameters` from `/parameters` to recover saved values: it drops unknown keys,
+restores missing or invalid values from defaults, and clamps numbers. At a trust boundary, use
+`createParamCodec(definition)` to reject incomplete, unknown, invalid, or noncanonical values.
+Both return fresh frozen parameter maps.
+
+For definition editors, `/packages` provides `safeParseParameterDefinitionDocument` and structured
+issue paths. The included `@metamesh/generator-sdk/parameters.schema.json` supports offline
+completion; SDK validation also checks references, defaults, and cross-field rules.
+
+## API entry points
 
-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`.
+| Import                               | Use it for                                       |
+| ------------------------------------ | ------------------------------------------------ |
+| `@metamesh/generator-sdk`            | Definitions, presets, and module authoring       |
+| `@metamesh/generator-sdk/parameters` | Defaults, saved values, and strict codecs        |
+| `@metamesh/generator-sdk/runtime`    | Module execution, mesh data, and Worker messages |
+| `@metamesh/generator-sdk/packages`   | Package, catalog, and installation parsing       |
+| `@metamesh/generator-sdk/fonts`      | Immutable font selection values                  |
+
+Incremental Worker hosts can use `GeneratedPartsDecoder` from `/runtime` to hydrate validated
+geometry resources while checking part metadata and aggregate limits on every delivery. Keep
+admitted buffers immutable and attached; call `clear()` when replacing the delivery source.
+
+## Documentation
 
-Exact SDK contracts live with their code:
+Resolve `@metamesh/generator-sdk/docs/manifest.json` from your project for exact-version Markdown
+guides and annotated declaration references. Document paths are relative to that manifest.
+With [`@metamesh/cli`](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/README.md)
+installed, `pnpm exec metamesh docs search "parameters"` searches the local index;
+`pnpm exec metamesh docs show sdk/guide/generator-modules` reads this package's authoring guide.
 
-- [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).
+- [Parameters and validation](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx) — controls, defaults, and diagnostics.
+- [Local authoring](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/create/author-locally.mdx) — the current Generator workflow.
+- [API source](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/index.ts) — exports, types, and implementation references.
 
-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.
+Until the public documentation site launches, use these repository guides or
+[run the docs locally](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/README.md#local-use).
+For package development, see [Contributing](https://github.com/JasonKoolman/metamesh/blob/main/CONTRIBUTING.md).
 
 ## License
 
-Apache-2.0. The complete terms are included in `LICENSE`.
+[Apache-2.0](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/LICENSE).

package/dist/contracts.d.ts

@@ -66,10 +66,10 @@ export interface GeneratorPreset<D extends GeneratorDefinition = GeneratorDefini
     readonly description?: string | undefined;
     readonly parameterValues: GeneratorParams<D>;
 }
-export type Vec3 = readonly [number, number, number];
+export type Vector3 = readonly [number, number, number];
 export interface ModelBounds {
-    readonly min: Vec3;
-    readonly max: Vec3;
+    readonly min: Vector3;
+    readonly max: Vector3;
 }
 export interface ModelStats {
     readonly triangles?: number | undefined;
@@ -104,8 +104,8 @@ export interface GeneratedPart {
     readonly geometryId: string;
     readonly geometryRevision: number;
     /** Authoritative translation in mm and fixed global X, Y, Z rotations in degrees. */
-    readonly position: Vec3;
-    readonly rotation: Vec3;
+    readonly position: Vector3;
+    readonly rotation: Vector3;
     readonly id: string;
     readonly positions: Float32Array;
     readonly indices: Uint32Array;

package/dist/contracts.d.ts.map

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

package/dist/docs/guides/authoring.md

@@ -0,0 +1,127 @@
+# Design reusable controls
+
+Make a code Project useful to someone else with clear inputs, tested defaults, focused validation, and portable files.
+
+Turn a working authored Project into a model someone can adjust without reading its source.
+If you need a working model first, follow [Build your first code Project](https://metamesh.studio/docs/develop/code-projects).
+
+
+
+```ts
+const { width, depth, height, holeDiameter, addHole } = params;
+  const body = box({ size: [width, depth, height] });
+  if (!addHole) return [part("body", body)];
+  // Two extra millimetres clear the centered body's top and bottom faces.
+  const bore = cylinder({ height: height + 2, diameter: holeDiameter, sizing: "face" });
+  return [part("body", body.subtract([bore]))];
+```
+
+A plate is a useful starting example: its controls describe the finished size and an optional hole, while the source handles construction.
+
+
+
+## Choose the decisions to expose
+
+Describe what someone should be able to change: the overall size, a fit, an optional feature, or
+which parts to produce. Expose those decisions as controls. Keep implementation details in the
+source unless changing them serves a clear purpose.
+
+For a plate with an optional hole, Width and Hole diameter express design decisions. The cylinder's
+segment count usually does not need equal prominence.
+
+Open **Parameter actions → Edit controls**, or **MetaMesh menu → Current project → Edit controls**.
+Group related controls into sections, put the most common decisions first, and choose
+**Apply & return** to use the updated definition. See
+[Define parameters and validation](parameters.md#choose-the-right-control)
+for supported control types and their configuration.
+
+## Make labels and units unambiguous
+
+Use labels that describe the finished model, such as **Outer Diameter**, rather than a variable
+name like `d2`. Add a short description when a measurement could have more than one interpretation:
+for example, whether Length includes an end cap.
+
+Show units for dimensional controls. MetaMesh model dimensions use millimetres; explain any
+conversion your source performs so the displayed input and exported size agree. Use a step that
+matches the decision: whole numbers for a count, or an appropriate increment for a dimension.
+
+Keep control IDs stable as you refine labels. IDs connect controls to source values and validation
+messages; a clearer label should not require a different identifier.
+
+## Choose defaults that demonstrate the model
+
+Choose representative defaults that produce a useful, recognizable result without validation
+errors and show the important features without requiring several edits.
+
+Try the model from the parameter panel with the code editor closed. Confirm that:
+
+- the first controls lead to the most useful variations;
+- changing a value produces the result its label suggests;
+- optional features reveal their relevant controls; and
+- resetting values restores the intended starting model.
+
+Use [conditional visibility](parameters.md#reveal-a-control-only-when-it-applies)
+to keep optional settings out of the way until they matter.
+
+## Explain constraints where they matter
+
+Set field limits for a single value's supported range. Add cross-field validation when a valid
+range depends on another control, such as a hole that must fit inside a plate.
+
+A helpful message identifies the problem and gives a next action: "Reduce Hole diameter or increase
+Width" is more useful than "Invalid parameters." Associate the message with the relevant control.
+Use an error for unsupported combinations and a warning for a trade-off the person can choose to
+accept. The [validation guide](parameters.md#add-cross-field-validation-in-typescript)
+explains the implementation with examples.
+
+Test more than the default combination. Check the smallest and largest supported dimensions,
+optional features, and any choice or list combinations. After an error, confirm that the suggested
+correction produces a current model again.
+
+For the plate above, test these decisions separately:
+
+| Variation                         | What to verify                                                                |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| Turn Add hole off                 | The plate becomes solid and hides Hole diameter.                              |
+| Change Width and Depth            | The body follows the controls; the hole stays in its intended position.       |
+| Make the hole wider than the body | The message identifies Hole diameter and explains which dimensions to change. |
+| Restore valid values              | A new successful preview replaces the retained older model.                   |
+| Reset all                         | The demonstrated starting configuration returns without errors.               |
+
+## Keep related parts understandable
+
+Use named parts when one set of controls produces related outputs, such as a lid and its container.
+Give them stable, descriptive IDs so inspection and export remain understandable as dimensions
+change. The [part contract](https://metamesh.studio/docs/develop/code-project-contract#parts-and-placement) describes the
+supported output shape.
+
+Inspect each output and check the exported model in its intended downstream tool. A valid solid
+alone does not establish a suitable fit or printable wall thickness. Follow the
+[export guide](https://metamesh.studio/docs/use/export-3mf) for format capabilities and verification steps.
+
+## Use the same design in a local module
+
+These control-design principles also apply to a Generator authored in a local TypeScript project.
+Use `@metamesh/generator-sdk` for its serializable definition and module envelope, and
+`@metamesh/modeling` for generation. Studio's virtual `@metamesh/project` import is specific to
+Studio and cannot be copied into a local Node module.
+
+Follow [local authoring](https://metamesh.studio/docs/develop/agent-authoring#generator-entries) to check and run the
+module with the CLI, inspect dimensions and named parts, and render the captured result. Add
+[Testkit checks](https://metamesh.studio/docs/develop/agent-authoring#test-models) when you need repeatable assertions for
+defaults, presets, supported bounds, or validation recovery. Keep those tests in your project's
+test runner; the CLI owns compilation and capture tools.
+
+## Keep a portable copy
+
+Save the authored Project as a `.metamesh.json` file, then
+[import the Project file](https://metamesh.studio/docs/use/projects-and-offline#save-and-import-an-authored-project) to check its source,
+controls, and values. Keep the file in storage you control; browser storage is local to the device
+and profile.
+
+A saved Project is not a published catalog Generator. Check
+[publishing availability](https://metamesh.studio/docs/create/publishing-status) if you intend to distribute through
+MetaMesh.
+
+- [Define parameters and validation](parameters.md)
+- [Save and protect your work](https://metamesh.studio/docs/use/projects-and-offline)

package/dist/docs/guides/package.md

@@ -0,0 +1,121 @@
+# `@metamesh/generator-sdk`
+
+Turn a parametric model into a MetaMesh Generator. Define controls once, infer their TypeScript
+types, and use the same parameter contract for forms, saved values, and execution.
+
+> **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
+> same minor line.
+
+## Installation
+
+```bash
+pnpm add @metamesh/generator-sdk
+```
+
+The SDK is renderer-neutral. To build geometry in the example below, also install
+[`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/packages/modeling/README.md).
+Keep installed MetaMesh packages on the same exact release.
+
+## Define controls
+
+A definition describes the Generator and its editable parameters. Literal IDs and options give
+you exact parameter types:
+
+```ts
+import { defineGenerator, type GeneratorParams } from "@metamesh/generator-sdk";
+
+export const definition = defineGenerator({
+  id: "sleeve",
+  version: "0.1.0",
+  title: "Sleeve",
+  groups: [],
+  parameters: [
+    { id: "outerDiameter", label: "Outer diameter", type: "number", default: 20, min: 4 },
+    { id: "boreDiameter", label: "Bore diameter", type: "number", default: 10, min: 1 },
+  ],
+});
+type Parameters = GeneratorParams<typeof definition>;
+```
+
+Definitions are serializable. Optional `ui` metadata describes grouping, visibility, hints, and
+editing increments. Number inputs and sliders share `type: "number"`; sliders add
+`ui.control: "slider"`, bounds, and `ui.step`. See the
+[parameter guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx)
+for the full set of controls.
+
+## Generate a model
+
+Add a synchronous generation program to the same module. Assertions describe relationships
+between controls; the module helper binds the program to its definition:
+
+```ts
+import { defineGeneratorModule } from "@metamesh/generator-sdk";
+import { generate, tube } from "@metamesh/modeling";
+
+const model = generate<Parameters>(({ 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 default defineGeneratorModule({ definition, generate: model });
+```
+
+Return a single `part(...)` or a readonly array of parts. The host normalizes parameters and prepares
+assets before generation. Modeling manages geometry, sessions, and snapshots; the SDK provides
+portable definitions, module envelopes, and validated runtime messages. Unsupported package formats
+reject before executable bytes are evaluated.
+
+## Work with saved values
+
+Use `normalizeParameters` from `/parameters` to recover saved values: it drops unknown keys,
+restores missing or invalid values from defaults, and clamps numbers. At a trust boundary, use
+`createParamCodec(definition)` to reject incomplete, unknown, invalid, or noncanonical values.
+Both return fresh frozen parameter maps.
+
+For definition editors, `/packages` provides `safeParseParameterDefinitionDocument` and structured
+issue paths. The included `@metamesh/generator-sdk/parameters.schema.json` supports offline
+completion; SDK validation also checks references, defaults, and cross-field rules.
+
+## API entry points
+
+| Import                               | Use it for                                       |
+| ------------------------------------ | ------------------------------------------------ |
+| `@metamesh/generator-sdk`            | Definitions, presets, and module authoring       |
+| `@metamesh/generator-sdk/parameters` | Defaults, saved values, and strict codecs        |
+| `@metamesh/generator-sdk/runtime`    | Module execution, mesh data, and Worker messages |
+| `@metamesh/generator-sdk/packages`   | Package, catalog, and installation parsing       |
+| `@metamesh/generator-sdk/fonts`      | Immutable font selection values                  |
+
+Incremental Worker hosts can use `GeneratedPartsDecoder` from `/runtime` to hydrate validated
+geometry resources while checking part metadata and aggregate limits on every delivery. Keep
+admitted buffers immutable and attached; call `clear()` when replacing the delivery source.
+
+## Documentation
+
+Resolve `@metamesh/generator-sdk/docs/manifest.json` from your project for exact-version Markdown
+guides and annotated declaration references. Document paths are relative to that manifest.
+With [`@metamesh/cli`](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/README.md)
+installed, `pnpm exec metamesh docs search "parameters"` searches the local index;
+`pnpm exec metamesh docs show sdk/guide/generator-modules` reads this package's authoring guide.
+
+- [Parameters and validation](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/parameters-and-validation.mdx) — controls, defaults, and diagnostics.
+- [Local authoring](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/create/author-locally.mdx) — the current Generator workflow.
+- [API source](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/src/index.ts) — exports, types, and implementation references.
+
+Until the public documentation site launches, use these repository guides or
+[run the docs locally](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/README.md#local-use).
+For package development, see [Contributing](https://github.com/JasonKoolman/metamesh/blob/main/CONTRIBUTING.md).
+
+## License
+
+[Apache-2.0](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/LICENSE).