@metamesh/modeling 0.17.0 → 0.19.0

package/dist/docs/reference/engine/ModelRunOptions.md

@@ -0,0 +1,110 @@
+# ModelRunOptions
+
+Generation policy and prepared synchronous capabilities for one host execution.
+
+## Extends
+
+- [`GenerationOptions`](GenerationOptions.md)
+
+## Extended by
+
+- [`SessionOptions`](SessionOptions.md)
+
+## Type Parameters
+
+### S
+
+`S` = `Record`\<`never`, `never`\>
+
+## Properties
+
+### meshValidation?
+
+
+
+`readonly` `optional` **meshValidation?**: `"topology"` \| `"solid"`
+
+
+
+Optional bounded intersection and nested-shell checks; defaults to indexed topology validation.
+
+#### Inherited from
+
+[`GenerationOptions`](GenerationOptions.md).[`meshValidation`](GenerationOptions.md#meshvalidation)
+
+***
+
+### limits?
+
+
+
+`readonly` `optional` **limits?**: `Partial`\<[`ModelingLimits`](../geometry/ModelingLimits.md)\>
+
+
+
+Per-build limits, no larger than the configured engine ceilings.
+
+#### Inherited from
+
+[`GenerationOptions`](GenerationOptions.md).[`limits`](GenerationOptions.md#limits)
+
+***
+
+### resolution?
+
+
+
+`readonly` `optional` **resolution?**: [`GeometryResolution`](../geometry/GeometryResolution.md)
+
+
+
+Physical sampling defaults; operation options and exact counts override these.
+
+#### Inherited from
+
+[`GenerationOptions`](GenerationOptions.md).[`resolution`](GenerationOptions.md#resolution)
+
+***
+
+### meshTopologyMode?
+
+
+
+`readonly` `optional` **meshTopologyMode?**: `"original"` \| `"optimized"`
+
+
+
+Optional bounded planar cleanup; unsupported candidates preserve the original part.
+
+#### Inherited from
+
+[`GenerationOptions`](GenerationOptions.md).[`meshTopologyMode`](GenerationOptions.md#meshtopologymode)
+
+***
+
+### services?
+
+
+
+`readonly` `optional` **services?**: `S`
+
+
+
+Host-owned synchronous capabilities, required when declared by the program. The original
+environment is retained; its behavior and assets must remain deterministic and fixed for
+this session. Equivalent function wrappers do not constitute an asset revision.
+
+
+## Related APIs
+
+- [GenerationOptions](GenerationOptions.md)
+- [ModelingLimits](../geometry/ModelingLimits.md)
+- [SessionOptions](SessionOptions.md)
+
+## Supported imports
+
+```ts
+import type { ModelRunOptions } from "@metamesh/modeling/engine";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/engine/ModelSession.md

@@ -1,12 +1,12 @@
 # ModelSession
 
-Stateful execution owner; a failed revision cannot change previously returned snapshots.
+Stateful execution owner; a failed revision cannot change previously returned results.
 
 ## Type Parameters
 
 ### P
 
-`P`
+`P` *extends* `object`
 
 ## Methods
 
@@ -14,41 +14,41 @@ Stateful execution owner; a failed revision cannot change previously returned sn
 
 
 
-**run**(`params`: `Readonly`\<`P`\>): [`ModelSnapshot`](ModelSnapshot.md)
+**run**(...`args`: `Record`\<`never`, `never`\> *extends* `P` ? \[`parameters?`: `Readonly`\<`P`\>\] : \[`parameters`: `Readonly`\<`P`\>\]): [`ModelResult`](ModelResult.md)
 
 
 
-Generates an atomic manufacturing snapshot or throws; parameters are copied and frozen.
+Generates durable immutable data or throws; parameters are copied and frozen. Empty parameters may be omitted.
 
 #### Parameters
 
-<a id="params"></a>
+<a id="args"></a>
 
-**`params`** · `Readonly`\<`P`\> · Required
+**`...args`** · `Record`\<`never`, `never`\> *extends* `P` ? \[`parameters?`: `Readonly`\<`P`\>\] : \[`parameters`: `Readonly`\<`P`\>\] · Required
 
 
 
 #### Returns
 
-[`ModelSnapshot`](ModelSnapshot.md)
+[`ModelResult`](ModelResult.md)
 
 ***
 
-### validate()
+### check()
 
 
 
-**validate**(`params`: `Readonly`\<`P`\>): readonly [`GenerationDiagnostic`](../model/GenerationDiagnostic.md)[]
+**check**(...`args`: `Record`\<`never`, `never`\> *extends* `P` ? \[`parameters?`: `Readonly`\<`P`\>\] : \[`parameters`: `Readonly`\<`P`\>\]): readonly [`GenerationDiagnostic`](../model/GenerationDiagnostic.md)[]
 
 
 
-Runs declaration and reached assertions without realizing returned parts.
+Returns reached assertion errors and warnings without finalizing returned geometry; unexpected errors throw.
 
 #### Parameters
 
-<a id="params-1"></a>
+<a id="args-1"></a>
 
-**`params`** · `Readonly`\<`P`\> · Required
+**`...args`** · `Record`\<`never`, `never`\> *extends* `P` ? \[`parameters?`: `Readonly`\<`P`\>\] : \[`parameters`: `Readonly`\<`P`\>\] · Required
 
 
 
@@ -66,7 +66,7 @@ readonly [`GenerationDiagnostic`](../model/GenerationDiagnostic.md)[]
 
 
 
-Clears optional caches without invalidating captured snapshots.
+Clears optional caches without invalidating returned results.
 
 #### Returns
 
@@ -82,7 +82,7 @@ Clears optional caches without invalidating captured snapshots.
 
 
 
-Releases session ownership; idempotent, captured snapshots remain usable.
+Releases session ownership; idempotent, returned results remain usable.
 
 #### Returns
 
@@ -91,6 +91,12 @@ Releases session ownership; idempotent, captured snapshots remain usable.
 
 ## Related APIs
 
-- [ModelSnapshot](ModelSnapshot.md)
+- [ModelResult](ModelResult.md)
 
-Package: `@metamesh/modeling@0.17.0`.
+## Supported imports
+
+```ts
+import type { ModelSession } from "@metamesh/modeling/engine";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/engine/SessionOptions.md

@@ -1,10 +1,10 @@
 # SessionOptions
 
-Fixed generation policy and deterministic host capabilities for one model session.
+Fixed generation policy and reusable computation caches for one model session.
 
 ## Extends
 
-- [`GenerationOptions`](GenerationOptions.md)
+- [`ModelRunOptions`](ModelRunOptions.md)\<`S`\>
 
 ## Type Parameters
 
@@ -26,7 +26,7 @@ Optional bounded intersection and nested-shell checks; defaults to indexed topol
 
 #### Inherited from
 
-[`GenerationOptions`](GenerationOptions.md).[`meshValidation`](GenerationOptions.md#meshvalidation)
+[`ModelRunOptions`](ModelRunOptions.md).[`meshValidation`](ModelRunOptions.md#meshvalidation)
 
 ***
 
@@ -34,7 +34,7 @@ Optional bounded intersection and nested-shell checks; defaults to indexed topol
 
 
 
-`readonly` `optional` **limits?**: `Partial`\<[`ModelingLimits`](../model/ModelingLimits.md)\>
+`readonly` `optional` **limits?**: `Partial`\<[`ModelingLimits`](../geometry/ModelingLimits.md)\>
 
 
 
@@ -42,7 +42,7 @@ Per-build limits, no larger than the configured engine ceilings.
 
 #### Inherited from
 
-[`GenerationOptions`](GenerationOptions.md).[`limits`](GenerationOptions.md#limits)
+[`ModelRunOptions`](ModelRunOptions.md).[`limits`](ModelRunOptions.md#limits)
 
 ***
 
@@ -50,7 +50,7 @@ Per-build limits, no larger than the configured engine ceilings.
 
 
 
-`readonly` `optional` **resolution?**: [`GeometryResolution`](../model/GeometryResolution.md)
+`readonly` `optional` **resolution?**: [`GeometryResolution`](../geometry/GeometryResolution.md)
 
 
 
@@ -58,7 +58,7 @@ Physical sampling defaults; operation options and exact counts override these.
 
 #### Inherited from
 
-[`GenerationOptions`](GenerationOptions.md).[`resolution`](GenerationOptions.md#resolution)
+[`ModelRunOptions`](ModelRunOptions.md).[`resolution`](ModelRunOptions.md#resolution)
 
 ***
 
@@ -74,7 +74,7 @@ Optional bounded planar cleanup; unsupported candidates preserve the original pa
 
 #### Inherited from
 
-[`GenerationOptions`](GenerationOptions.md).[`meshTopologyMode`](GenerationOptions.md#meshtopologymode)
+[`ModelRunOptions`](ModelRunOptions.md).[`meshTopologyMode`](ModelRunOptions.md#meshtopologymode)
 
 ***
 
@@ -90,6 +90,10 @@ Host-owned synchronous capabilities, required when declared by the program. The
 environment is retained; its behavior and assets must remain deterministic and fixed for
 this session. Equivalent function wrappers do not constitute an asset revision.
 
+#### Inherited from
+
+[`ModelRunOptions`](ModelRunOptions.md).[`services`](ModelRunOptions.md#services)
+
 ***
 
 ### cache?
@@ -118,6 +122,13 @@ Unsupported closures or large results fail explicitly; this cannot prove arbitra
 
 ## Related APIs
 
-- [GenerationOptions](GenerationOptions.md)
+- [ModelingLimits](../geometry/ModelingLimits.md)
+- [ModelRunOptions](ModelRunOptions.md)
+
+## Supported imports
+
+```ts
+import type { SessionOptions } from "@metamesh/modeling/engine";
+```
 
-Package: `@metamesh/modeling@0.17.0`.
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/engine/categories/host-lifecycle.md

@@ -1,36 +1,41 @@
 # Host lifecycle
 
-Initialize, configure, finalize, and export through one engine.
+Run models and manage reusable session caches and native resources.
 
-Create one engine in Node or a Worker, then create isolated sessions from `generate()` programs. `run()` is synchronous; native allocations start on demand and are always disposed.
+Create one engine in Node or a Worker, then keep sessions when edits should reuse memoized geometry.
 
-- **Snapshots:** parts contain reusable local geometry and authoritative world-space output. Captured snapshots remain valid after session disposal; dispose each when finished.
-- **Sessions:** disposal releases caches. Trusted resource ceilings apply even on cache hits.
-- **Validation:** `validateModel` checks declarations without a kernel. Geometry observations require `session.validate()`.
-- **Cache checks:** `verifyCache` is an optional bounded development probe; it does not prove arbitrary JavaScript dependencies.
+- **Results:** `engine.run` and `session.run` return the same durable immutable `ModelResult`. Results remain usable after later runs, cache clearing and session disposal.
+- **Sessions:** dispose sessions to release caches and native resources. Resource ceilings apply even on cache hits.
+- **Check:** `checkModel` checks declarations and reached assertions without a kernel. `session.check` also permits geometry observations. Neither finalizes returned shapes; a successful check does not establish geometric validity.
+- **Cache checks:** `verifyCache` is a bounded development probe; it does not prove arbitrary JavaScript dependencies.
 
 ## Functions
 
 | API | Summary |
 | --- | --- |
 | [createModelEngine](../createModelEngine.md) | Initializes one host kernel and returns a lifecycle-safe engine. No generator initializes WASM. |
-| [validateModel](../validateModel.md) | Runs declaration and immediate assertions without initializing a kernel or finalizing parts. Geometry observations require an initialized session's `validate` method instead. |
+| [checkModel](../checkModel.md) | Runs declaration and immediate assertions without initializing a kernel or finalizing parts. Returns reached assertion errors and warnings; unexpected execution failures throw. Returned geometry is not realized or validated. Geometry observations require an initialized session's `check` method instead. |
 
 ## Interfaces
 
 | API | Summary |
 | --- | --- |
 | [GenerationOptions](../GenerationOptions.md) | Execution settings supplied by the host, independently of generator metadata. |
-| [Export3mfOptions](../Export3mfOptions.md) | Completed-snapshot serialization settings; filename selection belongs to the host. |
-| [ExportMeshPart](../ExportMeshPart.md) | Manufacturing buffers accepted by the snapshot exporter. |
 | [ModelEngine](../ModelEngine.md) | Host engine. No native values or manually disposable handles are exposed. |
 | [ModelEngineOptions](../ModelEngineOptions.md) | Kernel asset initialization. Networking and Worker ownership remain with the host. |
-| [GeometryResource](../GeometryResource.md) | Validated local geometry resource; accessors return owned buffer copies. |
+| [GeometryResource](../GeometryResource.md) | Validated local geometry resource with stable immutable numeric storage. |
 | [ModelDependencies](../ModelDependencies.md) | Known dependencies for inspection; plain JavaScript bindings do not reveal their parameter origin. |
-| [ModelSession](../ModelSession.md) | Stateful execution owner; a failed revision cannot change previously returned snapshots. |
-| [ModelSnapshot](../ModelSnapshot.md) | Captured immutable revision; disposal never changes another snapshot or an in-flight export. |
-| [SessionOptions](../SessionOptions.md) | Fixed generation policy and deterministic host capabilities for one model session. |
-| [SnapshotPart](../SnapshotPart.md) | A world-space manufacturing part plus its reusable local renderer resource. |
+| [ModelSession](../ModelSession.md) | Stateful execution owner; a failed revision cannot change previously returned results. |
+| [SessionOptions](../SessionOptions.md) | Fixed generation policy and reusable computation caches for one model session. |
+| [ModelPart](../ModelPart.md) | A world-space manufacturing part plus its reusable local renderer resource. Top-level positions and indices already include transform; do not apply it again. Only geometry contains unplaced local buffers. |
+| [ModelResult](../ModelResult.md) | Durable immutable generation data, independent of session lifetime. |
+| [ModelRunOptions](../ModelRunOptions.md) | Generation policy and prepared synchronous capabilities for one host execution. |
+
+## Type aliases
+
+| API | Summary |
+| --- | --- |
+| [ModelRunArguments](../ModelRunArguments.md) | Fixed argument positions; infer parameters from the program, allow empty maps to be omitted, and require declared services. |
 
 ## Values
 
@@ -39,4 +44,4 @@ Create one engine in Node or a Worker, then create isolated sessions from `gener
 | [defaultModelingLimits](../defaultModelingLimits.md) | Default host resource ceilings for parts, vertices, triangles, and transferable bytes. |
 | [modelingWasmUrl](../modelingWasmUrl.md) | URL of the package's pinned WASM asset; browser bundlers may replace it with their emitted URL. |
 
-Package: `@metamesh/modeling@0.17.0`.
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/engine/checkModel.md

@@ -0,0 +1,49 @@
+# checkModel
+
+Runs declaration and immediate assertions without initializing a kernel or finalizing parts. Returns reached assertion errors and warnings; unexpected execution failures throw. Returned geometry is not realized or validated. Geometry observations require an initialized session's `check` method instead.
+
+**checkModel**\<`P` *extends* `object`, `S`\>(`program`: [`ModelProgram`](../model/ModelProgram.md)\<`P`, `S`\>, ...`args`: [`ModelRunArguments`](ModelRunArguments.md)\<`P`, `S`, [`SessionOptions`](SessionOptions.md)\<`S`\>\>): readonly [`GenerationDiagnostic`](../model/GenerationDiagnostic.md)[]
+
+
+
+## Type Parameters
+
+### P
+
+`P` *extends* `object`
+
+### S
+
+`S`
+
+## Parameters
+
+<a id="program"></a>
+
+**`program`** · [`ModelProgram`](../model/ModelProgram.md)\<`P`, `S`\> · Required
+
+
+
+<a id="args"></a>
+
+**`...args`** · [`ModelRunArguments`](ModelRunArguments.md)\<`P`, `S`, [`SessionOptions`](SessionOptions.md)\<`S`\>\> · Required
+
+
+
+## Returns
+
+readonly [`GenerationDiagnostic`](../model/GenerationDiagnostic.md)[]
+
+
+## Related APIs
+
+- [ModelRunArguments](ModelRunArguments.md)
+- [SessionOptions](SessionOptions.md)
+
+## Supported imports
+
+```ts
+import { checkModel } from "@metamesh/modeling/engine";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/engine/createModelEngine.md

@@ -11,20 +11,12 @@ Initializes one host kernel and returns a lifecycle-safe engine. No generator in
 ```ts
 import { box, generate } from "@metamesh/modeling";
 import { createModelEngine } from "@metamesh/modeling/engine";
+import { export3mf } from "@metamesh/modeling/export";
 
 const engine = await createModelEngine();
 const model = generate<Record<never, never>>(({ part }) => [part("body", box({ size: [30, 20, 8] }))]);
-const session = engine.createSession(model);
-try {
-  const snapshot = session.run({});
-  try {
-    await engine.export3mf(snapshot.parts);
-  } finally {
-    snapshot.dispose();
-  }
-} finally {
-  session.dispose();
-}
+const result = engine.run(model);
+await export3mf(result.parts);
 ```
 
 ## Parameters
@@ -37,7 +29,7 @@ try {
 
   Fixed kernel WASM asset URL; defaults to the package asset. Browser hosts supply their emitted URL.
 
-- [`limits`](ModelEngineOptions.md#limits) · `Partial`\<[`ModelingLimits`](../model/ModelingLimits.md)\> · Optional
+- [`limits`](ModelEngineOptions.md#limits) · `Partial`\<[`ModelingLimits`](../geometry/ModelingLimits.md)\> · Optional
 
   Trusted application ceilings. Builds may lower them; generators receive no engine.
 
@@ -53,4 +45,10 @@ try {
 - [ModelEngine](ModelEngine.md)
 - [ModelEngineOptions](ModelEngineOptions.md)
 
-Package: `@metamesh/modeling@0.17.0`.
+## Supported imports
+
+```ts
+import { createModelEngine } from "@metamesh/modeling/engine";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/engine/defaultModelingLimits.md

@@ -2,6 +2,19 @@
 
 Default host resource ceilings for parts, vertices, triangles, and transferable bytes.
 
-`const` **defaultModelingLimits**: `Readonly`\<[`ModelingLimits`](../model/ModelingLimits.md)\>
+`const` **defaultModelingLimits**: `Readonly`\<[`ModelingLimits`](../geometry/ModelingLimits.md)\>
 
-Package: `@metamesh/modeling@0.17.0`.
+
+
+
+## Related APIs
+
+- [ModelingLimits](../geometry/ModelingLimits.md)
+
+## Supported imports
+
+```ts
+import { defaultModelingLimits } from "@metamesh/modeling/engine";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/engine/modelingWasmUrl.md

@@ -4,4 +4,10 @@ URL of the package's pinned WASM asset; browser bundlers may replace it with the
 
 `const` **modelingWasmUrl**: `string`
 
-Package: `@metamesh/modeling@0.17.0`.
+## Supported imports
+
+```ts
+import { modelingWasmUrl } from "@metamesh/modeling/engine";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/engine.md

@@ -1,29 +1,22 @@
 # Engine API
 
-Initialize one host engine, run synchronous models, finalize bounded manufacturing snapshots, and export selected parts.
+Initialize one host engine, run synchronous models, and finalize bounded manufacturing snapshots.
 
-Import host initialization from `@metamesh/modeling/engine`. One engine creates isolated model sessions, finalizes bounded manufacturing snapshots, and disposes native allocations on every exit.
+Use `@metamesh/modeling/engine` to run models. Both one-shot and session runs return durable immutable results without disposal. Sessions own reusable caches and native resources.
 
 ```ts
 import { box, generate } from "@metamesh/modeling";
 import { createModelEngine } from "@metamesh/modeling/engine";
 const engine = await createModelEngine();
-const model = generate<Record<never, never>>(({ part }) => [part("body", box({ size: 20 }))]);
-const session = engine.createSession(model);
-const snapshot = session.run({});
-const bytes = await engine.export3mf(snapshot.parts, { name: "Block" });
-snapshot.dispose();
-session.dispose();
+const model = generate(({ part }) => part("body", box({ size: 20 })));
+const result = engine.run(model);
+console.log(result.bounds);
 ```
 
-Node resolves installed WASM automatically. Browser hosts may supply an emitted URL through `wasmUrl`.
-
-Generation is synchronous and cannot nest in one realm. Exports capture finalized world geometry before awaiting; they never rerun the program.
-
-Hosts own Workers, revisions, appearance, persistence, and delivery.
+Node finds installed WASM automatically. Browser hosts may supply an emitted URL through `wasmUrl`. Generation is synchronous and cannot nest in the same realm. Your application owns Workers, revisions, appearance, persistence and delivery.
 
 ## Categories
 
-- [Host lifecycle](engine/categories/host-lifecycle.md) — Initialize, configure, finalize, and export through one engine.
+- [Host lifecycle](engine/categories/host-lifecycle.md) — Run models and manage reusable session caches and native resources.
 
-Package: `@metamesh/modeling@0.17.0`.
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/export/Export3mfOptions.md

@@ -0,0 +1,24 @@
+# Export3mfOptions
+
+3MF serialization of closed manufacturing meshes in millimetres; colored output uses the standard Materials extension.
+
+**Export3mfOptions** = [`ExportOptions`](ExportOptions.md)
+
+
+
+
+## Related APIs
+
+- [ExportOptions](ExportOptions.md)
+
+## Supported imports
+
+```ts
+import type { Export3mfOptions } from "@metamesh/modeling/export";
+```
+
+```ts
+import type { Export3mfOptions } from "@metamesh/modeling/export/3mf";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/export/ExportDiagnostic.md

@@ -0,0 +1,59 @@
+# ExportDiagnostic
+
+Expected information loss imposed by the selected file format.
+
+## Properties
+
+### code
+
+
+
+`readonly` **code**: `"APPEARANCE_DROPPED"` \| `"MATERIAL_ASSIGNMENTS_DROPPED"` \| `"PART_NAMES_DROPPED"`
+
+
+
+Stable category; human-readable wording is not an API contract.
+
+***
+
+### message
+
+
+
+`readonly` **message**: `string`
+
+
+
+Description of the information the selected format cannot preserve.
+
+***
+
+### partIds
+
+
+
+`readonly` **partIds**: readonly `string`[]
+
+
+
+Affected semantic part identities, in input order.
+
+## Supported imports
+
+```ts
+import type { ExportDiagnostic } from "@metamesh/modeling/export";
+```
+
+```ts
+import type { ExportDiagnostic } from "@metamesh/modeling/export/stl";
+```
+
+```ts
+import type { ExportDiagnostic } from "@metamesh/modeling/export/3mf";
+```
+
+```ts
+import type { ExportDiagnostic } from "@metamesh/modeling/export/glb";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/export/ExportFormat.md

@@ -0,0 +1,25 @@
+# ExportFormat
+
+Supported completed-mesh file formats.
+
+**ExportFormat** = `"3mf"` \| `"stl"` \| `"glb"`
+
+## Supported imports
+
+```ts
+import type { ExportFormat } from "@metamesh/modeling/export";
+```
+
+```ts
+import type { ExportFormat } from "@metamesh/modeling/export/stl";
+```
+
+```ts
+import type { ExportFormat } from "@metamesh/modeling/export/3mf";
+```
+
+```ts
+import type { ExportFormat } from "@metamesh/modeling/export/glb";
+```
+
+Package: `@metamesh/modeling@0.19.0`.