partforge 0.146.4 → 0.149.0

package/types/gltf.d.ts

@@ -0,0 +1,40 @@
+// partforge/gltf — the cached-preview writer. Worker-safe: no three.js, no DOM.
+
+import type { SubPartDefinition } from "./part.js";
+
+/** The slice of a part `encodePreviewGlb` reads; any `PartDefinition` satisfies it, so does a plain object. */
+export interface PreviewPart {
+  parts?: Record<string, { display?: SubPartDisplay }>;
+  meta?: { background?: number; environment?: string };
+}
+
+type SubPartDisplay = NonNullable<SubPartDefinition["display"]>;
+
+/** One sub-part's posed display mesh — the shape the viewer, the worker's `meshes` reply and `buildView` hold. */
+export interface PreviewMesh {
+  /** The sub-part key; names the glTF node, mesh and material. */
+  name: string;
+  /** xyz triples in millimetres, Z-up, already posed. */
+  positions: Float32Array;
+  normals?: Float32Array | null;
+  /** Absent for a non-indexed soup (Manifold); OCCT sends indices. */
+  indices?: Uint32Array | null;
+  triangles?: number;
+  /** Ignored: feature edges are not encoded in this version. */
+  edges?: Float32Array | null;
+}
+
+export interface EncodePreviewInput {
+  /** At least one; a zero-length mesh gets no node. */
+  meshes: PreviewMesh[];
+  /** Read for `parts[name].display` (materials) and `meta.background` / `meta.environment`. */
+  part?: PreviewPart | null;
+  /** The view these meshes show; names the scene and lands in the file's extras as `partforgeView`. */
+  view?: string | null;
+}
+
+/** Bumped whenever the encoder writes different bytes for the same input. */
+export const PREVIEW_ENCODER_VERSION: number;
+
+/** Encode one view's posed meshes as a welded, quantized, meshopt-compressed GLB (Y-up, millimetres). Deterministic. */
+export function encodePreviewGlb(input: EncodePreviewInput): Promise<Uint8Array>;

package/types/index.d.ts

@@ -243,6 +243,17 @@ export interface MountOptions {
    * dropped, never fatal.
    */
   viewerState?: ViewerState | null;
+  /**
+   * A cached preview GLB (from `partforge/gltf`'s `encodePreviewGlb`, or a previous
+   * runtime's `exportPreview()`) drawn before the worker is ready and replaced in
+   * place, sub-part by sub-part, by the first live build — the camera is kept.
+   * Only a file for the view the viewer opens on is drawn, and only meshes named
+   * for that view's sub-parts; a file for another view, or one that will not
+   * decode, is logged once and ignored. A file written without a view (no `view`
+   * given to `encodePreviewGlb`) is drawn on sub-part name match alone, for any view.
+   * Carries no edge lines.
+   */
+  preview?: Uint8Array | ArrayBuffer | null;
   /**
    * A previous mount's `runtime.getPanelState()`: the transient state of the
    * part's custom controls (a selected tile), keyed by param. Same remount
@@ -613,6 +624,22 @@ export interface PartRuntime {
    * view-cube click, Reframe, or an animation cue).
    */
   getViewerState(): ViewerState;
+  /**
+   * True while the `preview` GLB is on screen: from the moment it decodes until a
+   * build delivers the whole view (a build error leaves it on). Picking, hover
+   * labels, measure, sketch and cutaway wait meanwhile; orbit, zoom, pan, the view
+   * cube, the view style and the rail work. Read it from the runtime each time —
+   * a copy of the handle freezes it.
+   */
+  readonly previewActive: boolean;
+  /**
+   * The view on screen as a preview GLB (`partforge/gltf`'s format), every
+   * sub-part posed exactly as drawn — what a later `mount({ preview })` shows
+   * before its kernel boots. Rejects while `previewActive`, before the view is
+   * fully built at the current params (a pending rebuild counts), for a `view`
+   * other than the one on screen, and after `dispose()`.
+   */
+  exportPreview(opts?: { view?: string }): Promise<Uint8Array>;
   /** Every custom control's non-empty transient state, keyed by param. Hand back as `panelState`. */
   getPanelState(): PanelState;
   /** What custom controls reported failing this mount, in order. */
@@ -698,6 +725,52 @@ export interface PartRuntime {
 /** Mount a full parametric-part app from a `PartDefinition`. */
 export function mount(part: PartDefinition, options: MountOptions): PartRuntime;
 
+/** Options for `mountPreview`. */
+export interface MountPreviewOptions {
+  /** A GLB from `partforge/gltf`'s `encodePreviewGlb`, or a runtime's `exportPreview()`. */
+  glb: Uint8Array | ArrayBuffer;
+  /** Optional viewer buttons, wired as `mount()` wires them; `#viewbar` inside the container is found by id. */
+  elements?: { chrome?: { reframe?: HTMLElement | null; theme?: HTMLElement | null } };
+  /** A previous runtime's `getViewerState()`; `cutaway` is ignored (a preview has no live solid). */
+  viewerState?: ViewerState | null;
+}
+
+/** The handle `mountPreview()` returns. Every method is safe before `ready` settles. */
+export interface PreviewRuntime {
+  /** Resolves once the GLB is drawn; rejects when it will not decode or holds no meshes. */
+  ready: Promise<void>;
+  /** Full teardown. Idempotent. */
+  dispose(): void;
+  /** The view the file was written for (`null` until drawn, or when the file names none). */
+  getView(): string | null;
+  /** Camera, projection, render mode and environment; `cutaway` is always `null`. */
+  getViewerState(): ViewerState;
+  /** Apply a state (camera, projection, render mode, environment) now, or once drawn. */
+  setViewerState(state: ViewerState | null): void;
+  /** Park/unpark the viewer, as `PartRuntime.setActive`. */
+  setActive(active: boolean): void;
+  /** WebGL context loss. Returns an unsubscribe. */
+  onContextLost(listener: () => void): () => void;
+  /** Accepted and ignored — there is no rail. */
+  setHostPane(pane: HostPane): void;
+  /** Accepted and ignored — there is no rail. */
+  setRailLayout(layout: HostRailLayout): void;
+  renderMode: {
+    get(): RenderMode;
+    set(mode: RenderMode): Promise<RenderMode>;
+    onChange(cb: (e: RenderModeEvent) => void): () => void;
+  };
+  environment: {
+    get(): string;
+    set(id: string): Promise<string>;
+    onChange(cb: (id: string) => void): () => void;
+    list(): Array<{ id: string; label: string }>;
+  };
+}
+
+/** A kernel-free viewer for a cached preview GLB: the viewer, view cube, view style and theme — no part, no worker, no rail. */
+export function mountPreview(container: HTMLElement, options: MountPreviewOptions): PreviewRuntime;
+
 /** Every format `exportParts` can write in this version (`runtime.listExportFormats()` returns copies). */
 export const EXPORT_FORMATS: ReadonlyArray<ExportFormatInfo>;
 
@@ -729,3 +802,10 @@ export function viewSubParts(
   params: Record<string, ParamValue>,
 ): string[];
 
+/**
+ * The view `mount()` opens on: a view flagged `default: true`, else the one
+ * placing the most sub-parts at the part's defaults (ties keep declaration
+ * order). `null` for a part with no views. Exported so a host building a part
+ * outside the viewer — a cached preview — opens the same view.
+ */
+export function resolveDefaultView(part: PartDefinition): string | null;

package/types/testing.d.ts

@@ -869,3 +869,6 @@ export function annotationRay(
 ): AnnotationRay;
 /** Intersect a ray with a plane; null on parallel / behind-origin misses. */
 export function rayPlane(ray: AnnotationRay, plane: PlaneSpec): RayPlaneHit | null;
+
+/** The view `mount()` opens on (see the main entry's declaration). */
+export function resolveDefaultView(part: PartDefinition): string | null;