@metamesh/modeling 0.17.0 → 0.19.0

package/dist/api/engine.d.ts

@@ -1,12 +1,12 @@
-import type { TriangleMesh } from "@metamesh/modeling/geometry";
+import type { ImmutableTriangleMesh } 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 +28,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 +44,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 +54,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,95 +84,108 @@ 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 {
-  /** Parameter keys read outside computed callbacks, affecting structure or ordinary code. */
+  /** Parameter keys read outside memo functions, affecting structure or ordinary code. */
   readonly modelParameters: readonly string[];
   /** Direct dependencies recorded by successfully evaluated computations. */
   readonly computations: readonly {
-    /** Session-local computation identity. */
+    /** Revision-local diagnostic memo identity; it is not a cache key. */
     readonly id: string;
     /** Direct top-level parameter reads. */
     readonly parameters: readonly string[];
-    /** Direct computed-reader dependencies. */
+    /** Known object-value dependencies between memo calls; scalar origins are not observable. */
     readonly computations: readonly string[];
   }[];
-  /** Part reader roots and known transitive parameter dependencies. */
+  /** Known memo origins of part geometry and placement, and their parameter dependencies. */
   readonly parts: readonly {
     /** Stable semantic output part identity. */
     readonly id: string;
-    /** Computed readers supplied as geometry or placement roots. */
+    /** Memo calls known to contribute object values to geometry or placement. */
     readonly computations: readonly string[];
     /** Known transitive parameter dependencies through these roots. */
     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.
- */
-export interface ExportMeshPart extends TriangleMesh {
-  /** 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.
- */
-export interface Export3mfOptions {
-  /** Optional bounded geometric solid checks on captured buffers; defaults to indexed topology validation. */
-  readonly meshValidation?: "topology" | "solid";
-  /** Document display name; defaults to MetaMesh model. */
-  readonly name?: string;
-}
 /** Kernel asset initialization. Networking and Worker ownership remain with the host. */
 export interface ModelEngineOptions {
   /** Fixed kernel WASM asset URL; defaults to the package asset. Browser hosts supply their emitted URL. */
@@ -164,18 +200,13 @@ 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.
@@ -184,20 +215,12 @@ export declare function validateModel<P, S>(
  * ```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);
  * ```
  */
 export declare function createModelEngine(

package/dist/api/export-3mf.d.ts

@@ -0,0 +1,2 @@
+export { export3mf, write3mf } from "./export.js";
+export type { ExportDiagnostic, ExportFormat, ExportGeometry, ExportLimits, ExportMaterial, ExportOptions, ExportPart, ExportReport, ExportedFile, ExportSink, Export3mfOptions } from "./export.js";

package/dist/api/export-glb.d.ts

@@ -0,0 +1,2 @@
+export { exportGlb, writeGlb } from "./export.js";
+export type { ExportDiagnostic, ExportFormat, ExportGeometry, ExportLimits, ExportMaterial, ExportOptions, ExportPart, ExportReport, ExportedFile, ExportSink, ExportGlbOptions } from "./export.js";

package/dist/api/export-stl.d.ts

@@ -0,0 +1,2 @@
+export { exportStl, writeStl } from "./export.js";
+export type { ExportDiagnostic, ExportFormat, ExportGeometry, ExportLimits, ExportMaterial, ExportOptions, ExportPart, ExportReport, ExportedFile, ExportSink, ExportStlOptions } from "./export.js";

package/dist/api/export.d.ts

@@ -0,0 +1,160 @@
+import type {
+  ImmutableBuffer,
+  TriangleMeshInput,
+  Transform3Data,
+} from "@metamesh/modeling/geometry";
+
+/** Local millimetre, Z-up indexed geometry; optional unit normals describe display shading only. */
+export type ExportGeometry = TriangleMeshInput & {
+  /** One finite unit XYZ normal per position; omitted normals are derived for GLB. */
+  readonly normals?: Float32Array | ImmutableBuffer<Float32Array>;
+};
+/** A semantic part referencing reusable local geometry, with placement and appearance kept separate. */
+export interface ExportPart {
+  /** Unique canonical lowercase kebab-case identity, at most 64 characters. */
+  readonly id: string;
+  /** Local geometry; engine results and decoded Worker parts are accepted directly. */
+  readonly geometry: ExportGeometry;
+  /** Proper rigid row-major local-to-world matrix; translations are millimetres. Defaults to identity. */
+  readonly transform?: Transform3Data;
+  /** Six-digit sRGB display color; overrides the assigned material's suggested display color. */
+  readonly color?: string;
+  /** Stable print material identity from options.materials; never inferred from display color. */
+  readonly materialId?: string;
+}
+/** Portable print material intent. Equal display colors do not merge different identities. */
+export interface ExportMaterial {
+  /** Unique canonical lowercase kebab-case identity, preserved by 3MF as the base-material name. */
+  readonly id: string;
+  /** Suggested six-digit sRGB display color; does not select filament, extruder, or physical tray. */
+  readonly color: string;
+}
+/** Supported completed-mesh file formats. */
+export type ExportFormat = "3mf" | "stl" | "glb";
+/** Independent trusted export ceilings; output limits also apply to streaming writers. */
+export interface ExportLimits {
+  /** Maximum selected semantic parts. */
+  readonly maxParts: number;
+  /** Maximum aggregate input vertices across selected instances. */
+  readonly maxVertices: number;
+  /** Maximum aggregate input triangles across selected instances. */
+  readonly maxTriangles: number;
+  /** Maximum captured unique numeric buffer-view bytes, including authored normals. */
+  readonly maxBytes: number;
+  /** Maximum encoded file bytes; defaults to 512 MiB. */
+  readonly maxOutputBytes: number;
+}
+/** Shared serialization policy; hosts own scheduling, filenames, and delivery. */
+export interface ExportOptions {
+  /** Display name, one through 1024 valid XML characters; defaults to MetaMesh model. */
+  readonly name?: string;
+  /** Explicit export ceilings, independent of engine/session configuration. */
+  readonly limits?: Partial<ExportLimits>;
+  /** Topology validation by default; solid additionally checks bounded intersections and shell nesting. */
+  readonly meshValidation?: "topology" | "solid";
+  /** Portable material identities referenced by parts. No slicer or device mapping is implied. */
+  readonly materials?: readonly ExportMaterial[];
+  /** Cancellation checked between bounded writing tasks; browser hosts should schedule CPU work in a Worker. */
+  readonly signal?: AbortSignal;
+}
+/** 3MF serialization of closed manufacturing meshes in millimetres; colored output uses the standard Materials extension. */
+export type Export3mfOptions = ExportOptions;
+/** Binary STL serialization in millimetres; open triangle surfaces are permitted by default. */
+export type ExportStlOptions = ExportOptions;
+/** Uncompressed glTF 2.0 binary serialization; converts millimetres/Z-up to metres/Y-up. */
+export interface ExportGlbOptions extends ExportOptions {
+  /** Normal smoothing threshold in degrees from zero through 180; defaults to 20. Authored normals take precedence. */
+  readonly creaseAngle?: number;
+}
+/** Expected information loss imposed by the selected file format. */
+export interface ExportDiagnostic {
+  /** Stable category; human-readable wording is not an API contract. */
+  readonly code:
+    | "APPEARANCE_DROPPED"
+    | "MATERIAL_ASSIGNMENTS_DROPPED"
+    | "PART_NAMES_DROPPED";
+  /** Description of the information the selected format cannot preserve. */
+  readonly message: string;
+  /** Affected semantic part identities, in input order. */
+  readonly partIds: readonly string[];
+}
+/** Completed writer metadata; successful completion means the sink accepted every chunk. */
+export interface ExportReport {
+  /** Registered file media type. */
+  readonly mediaType: string;
+  /** File extension without a leading dot. */
+  readonly extension: ExportFormat;
+  /** Expected format losses; invalid input and failed delivery reject instead. */
+  readonly diagnostics: readonly ExportDiagnostic[];
+  /** Encoded bytes delivered to the sink. */
+  readonly byteLength: number;
+}
+/** Owned file bytes and format metadata, usable in both Node and browsers. */
+export interface ExportedFile extends ExportReport {
+  /** Fresh mutable bytes; never aliases the input snapshot. */
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+/** Receives owned chunks in order. Writers await each call for backpressure; the host closes its destination. */
+export type ExportSink = (chunk: Uint8Array) => void | Promise<void>;
+
+/** Default standalone export policy: 64 parts, one million vertices, two million triangles, 96 MiB input, 512 MiB output. */
+export declare const defaultExportLimits: ExportLimits;
+
+/**
+ * Serializes a captured model as binary STL in millimetres and Z-up coordinates.
+ * Placement is baked into triangles. Diagnostics describe dropped names, appearance and materials.
+ * Mutable input is captured before the first await; no engine or renderer is needed.
+ */
+export declare function exportStl(
+  parts: readonly ExportPart[],
+  options?: ExportStlOptions,
+): Promise<ExportedFile>;
+/**
+ * Writes owned binary STL chunks to a sink, awaiting backpressure after each bounded chunk.
+ * The host owns sink completion and recovery after failure. Honors cancellation and output limits.
+ */
+export declare function writeStl(
+  parts: readonly ExportPart[],
+  sink: ExportSink,
+  options?: ExportStlOptions,
+): Promise<ExportReport>;
+
+/**
+ * Writes 3MF with local mesh reuse, semantic parts, rigid placement, and standard color groups.
+ * Colored output requires the Materials extension. Explicit material IDs remain distinct base-material
+ * names, combined with appearance through multiproperties; display colors never select filament.
+ * Captures mutable inputs before awaiting and awaits each owned output chunk for backpressure.
+ * The host owns destination closing and cleanup of partial output after rejection.
+ */
+export declare function write3mf(
+  parts: readonly ExportPart[],
+  sink: ExportSink,
+  options?: Export3mfOptions,
+): Promise<ExportReport>;
+/** Serializes selected completed meshes as an owned 3MF file without initializing an engine. */
+export declare function export3mf(
+  parts: readonly ExportPart[],
+  options?: Export3mfOptions,
+): Promise<ExportedFile>;
+
+/**
+ * Serializes captured local meshes as uncompressed glTF 2.0 binary, in metres and Y-up.
+ * Preserves named parts, placement, shared geometry and display appearance. Authored normals take
+ * precedence over crease-aware shading; no engine, renderer or optional compression codec is loaded.
+ */
+export declare function exportGlb(
+  parts: readonly ExportPart[],
+  options?: ExportGlbOptions,
+): Promise<ExportedFile>;
+/**
+ * Writes owned GLB chunks with backpressure, cancellation and explicit output limits.
+ * Plans accessor and container lengths before writing, then emits bounded binary chunks.
+ * Hosts own sink completion, scheduling and recovery after a partially written failure.
+ */
+export declare function writeGlb(
+  parts: readonly ExportPart[],
+  sink: ExportSink,
+  options?: ExportGlbOptions,
+): Promise<ExportReport>;
+
+/** Runtime-independent completed-mesh export. All input coordinates are millimetres, right-handed, and Z-up. @packageDocumentation */