@omrips/viewstl 2.0.0-rc.4 → 2.0.0-rc.6

package/build/{v2/viewstl.d.cts → viewstl.d.cts}

@@ -88,17 +88,71 @@ export interface SceneExportResult {
 }
 export interface AnimationTrack extends Transform {
   msec?: number;
+  /** Continuous accumulation; applies to delta only. */
   loop?: boolean;
 }
 export interface Animation {
   delta?: AnimationTrack;
   exact?: AnimationTrack;
 }
+export interface AnimationPlaybackState {
+  status: "idle" | "running" | "paused" | "stopped" | "completed";
+  elapsed_ms: number;
+  /** Temporarily suspended by a hidden document or lost graphics context. */
+  suspended: boolean;
+  tracks: Array<{
+    mode: "delta" | "exact";
+    msec: number;
+    loop: boolean;
+    progress: number;
+  }>;
+}
+export type AnimationStateReason =
+  | "started"
+  | "restored"
+  | "replaced"
+  | "paused"
+  | "resumed"
+  | "completed"
+  | "stopped"
+  | "manual"
+  | "removed"
+  | "clean"
+  | "error";
+/** Serialized scene playback. Normally created by get_vsj/export_scene. */
+export interface SavedAnimationState {
+  version: 1;
+  elapsed_ms: number;
+  paused: boolean;
+  origin: Required<Omit<Transform, "scale">>;
+  center: [number, number, number];
+}
 export interface GeometryData {
   positions: Float32Array | number[];
   colors?: Float32Array | number[] | null;
 }
+export interface ModelSize {
+  version: 1;
+  baseline_mm: [number, number, number];
+  unit_factor?: number;
+  file_units: Units;
+  editable: boolean;
+  dimensions_mm: [number, number, number];
+}
+export interface CameraBookmark {
+  name: string;
+  camera: CameraState;
+}
+export interface ModelMeasurements {
+  area_mm2: number;
+  volume_mm3: number | null;
+  volume_valid: boolean;
+  volume_reason: string;
+}
 export interface ModelOptions extends Transform {
+  /** Display label; filename remains the source reference for VSJ. */
+  display_name?: string;
+  size_state?: Omit<ModelSize, "dimensions_mm">;
   id?: number;
   filename?: string;
   /** Retrieve a public URL through the explicitly configured same-origin relay. */
@@ -116,6 +170,7 @@ export interface ModelOptions extends Transform {
   view_edges?: boolean;
   units?: Units;
   animation?: Animation | null;
+  animation_state?: SavedAnimationState | null;
 }
 export type ModelClick = (
   id: number | null,
@@ -173,6 +228,15 @@ export interface ViewerOptions {
   on_model_drop?: (filename: string) => void;
   on_model_mouseclick?: ModelClick;
   on_model_mousedown?: ModelClick;
+  animation_state_callback?: (
+    id: number,
+    state: AnimationPlaybackState,
+    reason: AnimationStateReason,
+  ) => void;
+  animation_complete_callback?: (
+    id: number,
+    state: AnimationPlaybackState,
+  ) => void;
 }
 export interface ModelInfo {
   name: string;
@@ -204,6 +268,8 @@ export interface Scene {
   auto_rotate: boolean;
   mouse_zoom: boolean;
   auto_resize: boolean;
+  camera_bookmarks?: CameraBookmark[];
+  display_units?: Units;
   center_models: boolean;
   grid?: boolean;
   infinite_grid?: { spacing: number; height: number };
@@ -281,6 +347,31 @@ export class StlViewer {
   set_camera_state(state: Partial<CameraState>): void;
   set_camera(x?: number, y?: number, z?: number): void;
   get_model_info(id: number): ModelInfo | null;
+  get_model_info(
+    id: number,
+    options: { measurements: false },
+  ): (Omit<ModelInfo, "area" | "volume"> & { area: null; volume: null }) | null;
+  get_model_size(id: number): ModelSize;
+  /** Multiplicative XYZ factors about the world-space center. Throws on invalid input. */
+  resize_model(id: number, factors: [number, number, number]): ModelSize;
+  set_file_units(id: number, units: Units): ModelSize;
+  reset_model_size(id: number): ModelSize;
+  duplicate_model(id: number): number;
+  display_units: Units;
+  set_display_units(units: Units): void;
+  set_camera_view(
+    name: "front" | "back" | "left" | "right" | "top" | "bottom" | "isometric",
+  ): void;
+  get_camera_bookmarks(): CameraBookmark[];
+  set_camera_bookmarks(bookmarks: CameraBookmark[]): void;
+  measure_model(
+    id: number,
+    options?: {
+      signal?: AbortSignal;
+      max_time_ms?: number;
+      on_progress?: (progress: { phase: string; elapsed_ms: number }) => void;
+    },
+  ): Promise<ModelMeasurements>;
   get_model_data(id: number): GeometryData | null;
   get_model_mesh(id: number): unknown;
   get_stl_bin(id: number): ArrayBuffer | null;
@@ -328,11 +419,17 @@ export class StlViewer {
   download_vsb(filename?: string): Promise<void | null>;
   load_vsb(source: string | File | Blob): void;
   animate_model(id: number, animation: Animation | null): void;
+  pause_model_animation(id: number): void;
+  resume_model_animation(id: number): void;
+  get_model_animation_state(id: number): AnimationPlaybackState | null;
   get_image_blob(type?: string): Promise<Blob>;
 }
 export default StlViewer;
 
 export interface ViewstlAppOptions {
+  /** Composed with the app's own playback controls and reduced-motion policy. */
+  animation_state_callback?: ViewerOptions["animation_state_callback"];
+  animation_complete_callback?: ViewerOptions["animation_complete_callback"];
   url_import_endpoint?: string;
   worker_url?: string | URL;
   worker_factory?: () => Worker;
@@ -357,6 +454,7 @@ export interface ViewstlAppState {
     /** Euler XYZ angles in degrees, about the model's own center. */
     rotation: Vector3;
     color: string | null;
+    animation: AnimationPlaybackState;
   }>;
 }
 export interface ViewstlApp {

package/build/{v2/viewstl.d.ts → viewstl.d.ts}

@@ -88,17 +88,71 @@ export interface SceneExportResult {
 }
 export interface AnimationTrack extends Transform {
   msec?: number;
+  /** Continuous accumulation; applies to delta only. */
   loop?: boolean;
 }
 export interface Animation {
   delta?: AnimationTrack;
   exact?: AnimationTrack;
 }
+export interface AnimationPlaybackState {
+  status: "idle" | "running" | "paused" | "stopped" | "completed";
+  elapsed_ms: number;
+  /** Temporarily suspended by a hidden document or lost graphics context. */
+  suspended: boolean;
+  tracks: Array<{
+    mode: "delta" | "exact";
+    msec: number;
+    loop: boolean;
+    progress: number;
+  }>;
+}
+export type AnimationStateReason =
+  | "started"
+  | "restored"
+  | "replaced"
+  | "paused"
+  | "resumed"
+  | "completed"
+  | "stopped"
+  | "manual"
+  | "removed"
+  | "clean"
+  | "error";
+/** Serialized scene playback. Normally created by get_vsj/export_scene. */
+export interface SavedAnimationState {
+  version: 1;
+  elapsed_ms: number;
+  paused: boolean;
+  origin: Required<Omit<Transform, "scale">>;
+  center: [number, number, number];
+}
 export interface GeometryData {
   positions: Float32Array | number[];
   colors?: Float32Array | number[] | null;
 }
+export interface ModelSize {
+  version: 1;
+  baseline_mm: [number, number, number];
+  unit_factor?: number;
+  file_units: Units;
+  editable: boolean;
+  dimensions_mm: [number, number, number];
+}
+export interface CameraBookmark {
+  name: string;
+  camera: CameraState;
+}
+export interface ModelMeasurements {
+  area_mm2: number;
+  volume_mm3: number | null;
+  volume_valid: boolean;
+  volume_reason: string;
+}
 export interface ModelOptions extends Transform {
+  /** Display label; filename remains the source reference for VSJ. */
+  display_name?: string;
+  size_state?: Omit<ModelSize, "dimensions_mm">;
   id?: number;
   filename?: string;
   /** Retrieve a public URL through the explicitly configured same-origin relay. */
@@ -116,6 +170,7 @@ export interface ModelOptions extends Transform {
   view_edges?: boolean;
   units?: Units;
   animation?: Animation | null;
+  animation_state?: SavedAnimationState | null;
 }
 export type ModelClick = (
   id: number | null,
@@ -173,6 +228,15 @@ export interface ViewerOptions {
   on_model_drop?: (filename: string) => void;
   on_model_mouseclick?: ModelClick;
   on_model_mousedown?: ModelClick;
+  animation_state_callback?: (
+    id: number,
+    state: AnimationPlaybackState,
+    reason: AnimationStateReason,
+  ) => void;
+  animation_complete_callback?: (
+    id: number,
+    state: AnimationPlaybackState,
+  ) => void;
 }
 export interface ModelInfo {
   name: string;
@@ -204,6 +268,8 @@ export interface Scene {
   auto_rotate: boolean;
   mouse_zoom: boolean;
   auto_resize: boolean;
+  camera_bookmarks?: CameraBookmark[];
+  display_units?: Units;
   center_models: boolean;
   grid?: boolean;
   infinite_grid?: { spacing: number; height: number };
@@ -281,6 +347,31 @@ export class StlViewer {
   set_camera_state(state: Partial<CameraState>): void;
   set_camera(x?: number, y?: number, z?: number): void;
   get_model_info(id: number): ModelInfo | null;
+  get_model_info(
+    id: number,
+    options: { measurements: false },
+  ): (Omit<ModelInfo, "area" | "volume"> & { area: null; volume: null }) | null;
+  get_model_size(id: number): ModelSize;
+  /** Multiplicative XYZ factors about the world-space center. Throws on invalid input. */
+  resize_model(id: number, factors: [number, number, number]): ModelSize;
+  set_file_units(id: number, units: Units): ModelSize;
+  reset_model_size(id: number): ModelSize;
+  duplicate_model(id: number): number;
+  display_units: Units;
+  set_display_units(units: Units): void;
+  set_camera_view(
+    name: "front" | "back" | "left" | "right" | "top" | "bottom" | "isometric",
+  ): void;
+  get_camera_bookmarks(): CameraBookmark[];
+  set_camera_bookmarks(bookmarks: CameraBookmark[]): void;
+  measure_model(
+    id: number,
+    options?: {
+      signal?: AbortSignal;
+      max_time_ms?: number;
+      on_progress?: (progress: { phase: string; elapsed_ms: number }) => void;
+    },
+  ): Promise<ModelMeasurements>;
   get_model_data(id: number): GeometryData | null;
   get_model_mesh(id: number): unknown;
   get_stl_bin(id: number): ArrayBuffer | null;
@@ -328,11 +419,17 @@ export class StlViewer {
   download_vsb(filename?: string): Promise<void | null>;
   load_vsb(source: string | File | Blob): void;
   animate_model(id: number, animation: Animation | null): void;
+  pause_model_animation(id: number): void;
+  resume_model_animation(id: number): void;
+  get_model_animation_state(id: number): AnimationPlaybackState | null;
   get_image_blob(type?: string): Promise<Blob>;
 }
 export default StlViewer;
 
 export interface ViewstlAppOptions {
+  /** Composed with the app's own playback controls and reduced-motion policy. */
+  animation_state_callback?: ViewerOptions["animation_state_callback"];
+  animation_complete_callback?: ViewerOptions["animation_complete_callback"];
   url_import_endpoint?: string;
   worker_url?: string | URL;
   worker_factory?: () => Worker;
@@ -357,6 +454,7 @@ export interface ViewstlAppState {
     /** Euler XYZ angles in degrees, about the model's own center. */
     rotation: Vector3;
     color: string | null;
+    animation: AnimationPlaybackState;
   }>;
 }
 export interface ViewstlApp {