@metamesh/modeling 0.16.0 → 0.18.0

package/dist/api/engine.d.ts

@@ -1,12 +1,13 @@
-import type { TriangleMesh } from "@metamesh/modeling/geometry";
+import type { ImmutableTriangleMesh } from "@metamesh/modeling/geometry";
+import type { TriangleMeshInput } from "@metamesh/modeling/geometry";
 import type {
-  FinalizedModel,
-  FinalizedPart,
+  Bounds3Data,
   GenerationDiagnostic,
   GeometryResolution,
   ModelingLimits,
   ModelProgram,
-  Vector3Data,
+  Transform3Data,
+  TriangleMeshTopologyAnalysis,
 } from "@metamesh/modeling";
 /** Default host resource ceilings for parts, vertices, triangles, and transferable bytes. */
 declare const defaultModelingLimits: Readonly<ModelingLimits>;
@@ -28,8 +29,13 @@ export interface GenerationOptions {
 export interface ModelEngine {
   /** Immutable resource ceilings selected when this engine was initialized. */
   readonly limits: ModelingLimits;
+  /** Runs once with isolated ownership and returns durable immutable data; no disposal is required. */
+  run<P extends object, S>(
+    program: ModelProgram<P, S>,
+    ...args: ModelRunArguments<P, S>
+  ): ModelResult;
   /** Creates isolated caches; prepared service capabilities remain fixed for its lifetime. */
-  createSession<P, S>(
+  createSession<P extends object, S>(
     program: ModelProgram<P, S>,
     ...options: keyof S extends never
       ? [options?: SessionOptions<S>]
@@ -39,14 +45,9 @@ export interface ModelEngine {
           },
         ]
   ): ModelSession<P>;
-  /** Serializes already finalized mesh parts; never prepares or builds a generator again. */
-  export3mf(
-    parts: readonly ExportMeshPart[],
-    options?: Export3mfOptions,
-  ): Promise<ArrayBuffer>;
 }
-/** Fixed generation policy and deterministic host capabilities for one model session. */
-export interface SessionOptions<
+/** Generation policy and prepared synchronous capabilities for one host execution. */
+export interface ModelRunOptions<
   S = Record<never, never>,
 > extends GenerationOptions {
   /** Host-owned synchronous capabilities, required when declared by the program. The original
@@ -54,6 +55,29 @@ export interface SessionOptions<
    * this session. Equivalent function wrappers do not constitute an asset revision.
    */
   readonly services?: S;
+}
+/** Fixed argument positions; infer parameters from the program, allow empty maps to be omitted, and require declared services. */
+export type ModelRunArguments<
+  P extends object,
+  S,
+  Options extends ModelRunOptions<S> = ModelRunOptions<S>,
+> = keyof S extends never
+  ? Record<never, never> extends P
+    ? [parameters?: NoInfer<Readonly<P>>, options?: Options]
+    : [parameters: NoInfer<Readonly<P>>, options?: Options]
+  : [
+      parameters:
+        | NoInfer<Readonly<P>>
+        | (Record<never, never> extends P ? undefined : never),
+      options: Options & {
+        /** Prepared synchronous capabilities required by this program. */
+        readonly services: S;
+      },
+    ];
+/** Fixed generation policy and reusable computation caches for one model session. */
+export interface SessionOptions<
+  S = Record<never, never>,
+> extends ModelRunOptions<S> {
   /** Enables reuse; defaults to true. Set false for uncached output equivalence checks. */
   readonly cache?: boolean;
   /** Development-only cache-hit probe: reruns pure callbacks and compares bounded data/recipes.
@@ -61,42 +85,65 @@ export interface SessionOptions<
    */
   readonly verifyCache?: boolean;
 }
-/** Validated local geometry resource; accessors return owned buffer copies. */
-export interface GeometryResource extends TriangleMesh {
+/** Validated local geometry resource with stable immutable numeric storage. */
+export interface GeometryResource extends ImmutableTriangleMesh {
   /** Session-scoped immutable resource identity, stable while geometry is reused. */
   readonly id: string;
   /** Immutable resource revision; a new resource receives a new identity. */
   readonly revision: number;
-  /** Facts for the exact local manufacturing buffers. */
-  readonly measurements: FinalizedPart["measurements"];
+  /** Facts and indexed topology counts for the exact local manufacturing buffers. */
+  readonly measurements: TriangleMeshTopologyAnalysis;
 }
 /**
  * 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.
  *
- * Each `positions` or `indices` read returns an owned buffer copy; retain that copy when
- * traversing the mesh. Measurements and placement are immutable data and do not copy on access.
+ * Buffer properties are stable immutable values. Use copy() explicitly for mutable storage.
  */
-export interface SnapshotPart extends FinalizedPart {
+export interface ModelPart extends ImmutableTriangleMesh {
+  /** Stable semantic identity. */
+  readonly id: string;
+  /** Optional six-digit hexadecimal display color. */
+  readonly color?: string;
+  /** Facts and indexed topology counts measured from these world-space manufacturing buffers. */
+  readonly measurements: TriangleMeshTopologyAnalysis;
   /** Validated geometry in local coordinates, independent of placement and appearance. */
   readonly geometry: GeometryResource;
-  /** XYZ translation in millimetres after rotation. */
-  readonly position: Vector3Data;
-  /** Fixed global X, then Y, then Z rotation in degrees. */
-  readonly rotation: Vector3Data;
+  /** Immutable rigid local-to-world row-major 4x4 matrix; translation uses millimetres. */
+  readonly transform: Transform3Data;
 }
-/** Captured immutable revision; disposal never changes another snapshot or an in-flight export. */
-export interface ModelSnapshot extends FinalizedModel {
+/** Durable immutable generation data, independent of session lifetime. */
+export interface ModelResult {
+  /** Exact axis-aligned world bounds in millimetres. */
+  readonly bounds: Bounds3Data;
+  /** Aggregate manufacturing facts in millimetres and engine execution timings in milliseconds. */
+  readonly stats: {
+    /** Declared output instances, including repeated geometry. */
+    readonly partCount: number;
+    /** Aggregate position-buffer vertices across instances. */
+    readonly vertexCount: number;
+    /** Aggregate indexed triangles across instances. */
+    readonly triangleCount: number;
+    /** Signed enclosed volume in cubic millimetres. */
+    readonly signedVolume: number;
+    /** Bytes occupied by finalized world-space position and index buffers, counting shared buffers once. */
+    readonly byteCount: number;
+    /** Synchronous declaration duration in milliseconds. */
+    readonly buildMs: number;
+    /** Validation and finalization duration in milliseconds. */
+    readonly finalizeMs: number;
+    /** Total elapsed generation duration including cleanup, in milliseconds. */
+    readonly generateMs: number;
+  };
   /** Ordered world-space parts, each referring to reusable local geometry. */
-  readonly parts: readonly SnapshotPart[];
+  readonly parts: readonly ModelPart[];
+  /** Returns the part with this exact semantic ID; throws with available IDs when missing. */
+  part(id: string): ModelPart;
   /** Nonblocking diagnostics emitted for this revision. */
   readonly diagnostics: readonly GenerationDiagnostic[];
   /** Known dependency graph; outer reads remain conservative model-wide dependencies. */
   readonly dependencies: ModelDependencies;
-  /**
-   * Releases this snapshot's geometry references and invalidates its parts, bounds and stats accessors.
-   * Idempotent. Diagnostics, dependencies and previously obtained parts remain usable.
-   */
-  dispose(): void;
 }
 /** Known dependencies for inspection; plain JavaScript bindings do not reveal their parameter origin. */
 export interface ModelDependencies {
@@ -121,30 +168,40 @@ export interface ModelDependencies {
     readonly parameters: readonly string[];
   }[];
 }
-/** Stateful execution owner; a failed revision cannot change previously returned snapshots. */
-export interface ModelSession<P> {
-  /** Generates an atomic manufacturing snapshot or throws; parameters are copied and frozen. */
-  run(params: Readonly<P>): ModelSnapshot;
-  /** Runs declaration and reached assertions without realizing returned parts. */
-  validate(params: Readonly<P>): readonly GenerationDiagnostic[];
-  /** Clears optional caches without invalidating captured snapshots. */
+/** Stateful execution owner; a failed revision cannot change previously returned results. */
+export interface ModelSession<P extends object> {
+  /** Generates durable immutable data or throws; parameters are copied and frozen. Empty parameters may be omitted. */
+  run(
+    ...args: Record<never, never> extends P
+      ? [parameters?: Readonly<P>]
+      : [parameters: Readonly<P>]
+  ): ModelResult;
+  /** Returns reached assertion errors and warnings without finalizing returned geometry; unexpected errors throw. */
+  check(
+    ...args: Record<never, never> extends P
+      ? [parameters?: Readonly<P>]
+      : [parameters: Readonly<P>]
+  ): readonly GenerationDiagnostic[];
+  /** Clears optional caches without invalidating returned results. */
   clearCache(): void;
-  /** Releases session ownership; idempotent, captured snapshots remain usable. */
+  /** Releases session ownership; idempotent, returned results remain usable. */
   dispose(): void;
 }
 /**
- * Manufacturing buffers accepted by the snapshot exporter.
+ * Manufacturing buffers accepted by the standalone mesh exporter.
  */
-export interface ExportMeshPart extends TriangleMesh {
+export type ExportMeshPart = TriangleMeshInput & {
   /** Stable canonical lowercase identity; unique within the containing topology or output. */
   readonly id: string;
   /** Optional six-digit hex RGB display color. */
   readonly color?: string;
-}
+};
 /**
- * Completed-snapshot serialization settings; filename selection belongs to the host.
+ * Completed-mesh serialization settings; filename selection belongs to the host.
  */
 export interface Export3mfOptions {
+  /** Trusted export allocation and aggregate output ceilings; omitted fields use package defaults. */
+  readonly limits?: Partial<ModelingLimits>;
   /** Optional bounded geometric solid checks on captured buffers; defaults to indexed topology validation. */
   readonly meshValidation?: "topology" | "solid";
   /** Document display name; defaults to MetaMesh model. */
@@ -158,24 +215,39 @@ export interface ModelEngineOptions {
   readonly limits?: Partial<ModelingLimits>;
 }
 
+/**
+ * Serializes captured manufacturing meshes as millimetre 3MF without initializing an engine.
+ * Captures input arrays and options before awaiting; later mutations, runs and session cleanup
+ * cannot change the exported geometry. Trusted limits default to the package output ceilings.
+ *
+ * @example Export a pure mesh without an engine
+ * ```ts
+ * import { export3mf } from "@metamesh/modeling/engine";
+ * import * as mesh from "@metamesh/modeling/geometry/mesh";
+ * import { rectangleContour } from "@metamesh/modeling/geometry";
+ * const plate = mesh.extrude(rectangleContour({ size: [30, 20] }), { height: 6 });
+ * const bytes = await export3mf([{ id: "plate", ...plate }], { name: "Plate" });
+ * ```
+ */
+export declare function export3mf(
+  parts: readonly ExportMeshPart[],
+  options?: Export3mfOptions,
+): Promise<ArrayBuffer>;
+
 export { defaultModelingLimits };
+
 /** URL of the package's pinned WASM asset; browser bundlers may replace it with their emitted URL. */
 export declare const modelingWasmUrl: string;
 
 /**
  * Runs declaration and immediate assertions without initializing a kernel or finalizing parts.
- * Geometry observations require an initialized session's `validate` method instead.
+ * 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.
  */
-export declare function validateModel<P, S>(
+export declare function checkModel<P extends object, S>(
   program: ModelProgram<P, S>,
-  params: Readonly<P>,
-  ...settings: keyof S extends never
-    ? [options?: SessionOptions<S>]
-    : [
-        options: SessionOptions<S> & {
-          readonly services: S;
-        },
-      ]
+  ...args: ModelRunArguments<P, S, SessionOptions<S>>
 ): readonly GenerationDiagnostic[];
 /**
  * Initializes one host kernel and returns a lifecycle-safe engine. No generator initializes WASM.
@@ -183,21 +255,12 @@ export declare function validateModel<P, S>(
  * @example Build a box in a host application
  * ```ts
  * import { box, generate } from "@metamesh/modeling";
- * import { createModelEngine } from "@metamesh/modeling/engine";
+ * import { createModelEngine, export3mf } from "@metamesh/modeling/engine";
  *
  * 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);
  * ```
  */
 export declare function createModelEngine(