@metamesh/modeling 0.19.0 → 0.20.0

package/dist/api/export.d.ts

@@ -1,38 +1,79 @@
 import type {
   ImmutableBuffer,
-  TriangleMeshInput,
+  NumericArray,
   Transform3Data,
 } from "@metamesh/modeling/geometry";
+import type {
+  ImmutableTriangleMesh,
+  TriangleMesh,
+  TriangleMeshInput,
+} from "@metamesh/modeling/geometry/mesh";
+/** Runtime-independent completed-mesh export. All input coordinates are millimetres, right-handed, and Z-up. @packageDocumentation */
+
+/** Default standalone export policy: 64 parts, one million vertices, two million triangles, 96 MiB input, 512 MiB output. */
+export declare const defaultExportLimits: ExportLimits;
+
+/**
+ * Serializes selected completed meshes as an owned 3MF file without initializing an engine.
+ *
+ * @param parts - Closed, outward-wound parts in output order, with local geometry in millimetres.
+ */
+export declare function export3mf(
+  parts: readonly ExportPart[],
+  options?: Export3mfOptions,
+): Promise<ExportedFile>;
+
+/** 3MF serialization of closed manufacturing meshes in millimetres; colored output uses the standard Materials extension. */
+export declare type Export3mfOptions = ExportOptions;
+
+/** Expected information loss imposed by the selected file format. */
+export declare 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[];
+}
+
+/** Owned file bytes and format metadata, usable in both Node and browsers. */
+export declare interface ExportedFile extends ExportReport {
+  /** Fresh mutable bytes; never aliases the input snapshot. */
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+
+/** Supported completed-mesh file formats. */
+export declare type ExportFormat = "3mf" | "stl" | "glb";
 
 /** Local millimetre, Z-up indexed geometry; optional unit normals describe display shading only. */
-export type ExportGeometry = TriangleMeshInput & {
+export declare 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;
+
+/**
+ * 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.
+ *
+ * @param parts - Parts in output order, with local geometry in millimetres and Z-up.
+ */
+export declare function exportGlb(
+  parts: readonly ExportPart[],
+  options?: ExportGlbOptions,
+): Promise<ExportedFile>;
+
+/** Uncompressed glTF 2.0 binary serialization; converts millimetres/Z-up to metres/Y-up. */
+export declare interface ExportGlbOptions extends ExportOptions {
+  /** Normal smoothing threshold in degrees from zero through 180; defaults to 20. Authored normals take precedence. */
+  readonly creaseAngle?: number;
 }
-/** 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 {
+export declare interface ExportLimits {
   /** Maximum selected semantic parts. */
   readonly maxParts: number;
   /** Maximum aggregate input vertices across selected instances. */
@@ -44,8 +85,17 @@ export interface ExportLimits {
   /** Maximum encoded file bytes; defaults to 512 MiB. */
   readonly maxOutputBytes: number;
 }
+
+/** Portable print material intent. Equal display colors do not merge different identities. */
+export declare 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;
+}
+
 /** Shared serialization policy; hosts own scheduling, filenames, and delivery. */
-export interface ExportOptions {
+export declare 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. */
@@ -57,29 +107,23 @@ export interface ExportOptions {
   /** 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[];
+
+/** A semantic part referencing reusable local geometry, with placement and appearance kept separate. */
+export declare 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;
 }
+
 /** Completed writer metadata; successful completion means the sink accepted every chunk. */
-export interface ExportReport {
+export declare interface ExportReport {
   /** Registered file media type. */
   readonly mediaType: string;
   /** File extension without a leading dot. */
@@ -89,35 +133,30 @@ export interface ExportReport {
   /** 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;
+/**
+ * Receives chunks in order. Writers await each call; the host closes its destination.
+ *
+ * @param chunk - Bytes the sink owns and may retain or transfer.
+ */
+export declare type ExportSink = (chunk: Uint8Array) => void | Promise<void>;
 
 /**
  * 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.
+ *
+ * @param parts - Parts in output order, with local geometry in millimetres.
  */
 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>;
+
+/** Binary STL serialization in millimetres; open triangle surfaces are permitted by default. */
+export declare type ExportStlOptions = ExportOptions;
+
+declare const immutableBufferBrand: unique symbol;
 
 /**
  * Writes 3MF with local mesh reuse, semantic parts, rigid placement, and standard color groups.
@@ -125,31 +164,23 @@ export declare function writeStl(
  * 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.
+ *
+ * @param parts - Closed, outward-wound parts in output order.
+ * @param sink - Receives each chunk; return a promise to pause writing.
  */
 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.
+ *
+ * @param parts - Parts in output order; mutable geometry is copied before writing.
+ * @param sink - Receives each chunk; return a promise to pause writing.
  */
 export declare function writeGlb(
   parts: readonly ExportPart[],
@@ -157,4 +188,17 @@ export declare function writeGlb(
   options?: ExportGlbOptions,
 ): Promise<ExportReport>;
 
-/** Runtime-independent completed-mesh export. All input coordinates are millimetres, right-handed, and Z-up. @packageDocumentation */
+/**
+ * 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.
+ *
+ * @param parts - Parts in output order; mutable geometry is copied before writing.
+ * @param sink - Receives each chunk; return a promise to pause writing.
+ */
+export declare function writeStl(
+  parts: readonly ExportPart[],
+  sink: ExportSink,
+  options?: ExportStlOptions,
+): Promise<ExportReport>;
+
+export {};