u-space 0.0.29 → 0.0.31

package/dist/src/viewers/Viewer.d.ts

@@ -11,6 +11,7 @@ type ViewerRendererOptions = ConstructorParameters<typeof WebGPURenderer>['0'];
 export interface ViewerOptions {
     el: HTMLElement;
     rendererOptions?: ViewerRendererOptions;
+    pixelRatio?: number;
 }
 export interface ScreenshotOptions {
     width?: number;
@@ -64,11 +65,12 @@ declare class Viewer extends EventDispatcher<ViewerEventMap> {
     cssRenderer: CSSRenderer;
     frameCount: number;
     frameloop: 'always' | 'demand';
-    constructor({ el, rendererOptions }: ViewerOptions);
+    constructor({ el, rendererOptions, pixelRatio }: ViewerOptions);
     onWindowResize: () => void;
     init(): Promise<void>;
     setCamera(camera: PerspectiveCamera | OrthographicCamera): void;
     setCameraByType(type: 'perspective' | 'orthographic'): void;
+    invalidate(frame?: number): void;
     render(frame?: number): Promise<void>;
     private animate;
     private _initRenderer;

package/dist/src/viewers/renderInvalidation.d.ts

@@ -0,0 +1,2 @@
+declare function coalesceRenderFrames(pendingFrames: number, requestedFrames?: number): number;
+export { coalesceRenderFrames };

package/dist/src/worker/FrameTimingWindow.d.ts

@@ -0,0 +1,16 @@
+import type { WorkerFrameTimingStats } from './protocol';
+export interface FrameTimingWindowOptions {
+    windowMs?: number;
+    idleResetMs?: number;
+    missedFrameThresholdMs?: number;
+}
+export declare class FrameTimingWindow {
+    #private;
+    readonly windowMs: number;
+    readonly idleResetMs: number;
+    readonly missedFrameThresholdMs: number;
+    constructor(options?: FrameTimingWindowOptions);
+    add(duration: number, now?: number): WorkerFrameTimingStats;
+    snapshot(now?: number): WorkerFrameTimingStats;
+    reset(): void;
+}

package/dist/src/worker/OffscreenViewerHost.d.ts

@@ -0,0 +1,20 @@
+import type { SerializedDomEvent } from './protocol';
+export interface OffscreenViewerHostOptions {
+    el: HTMLElement;
+    worker: Worker;
+    canvas?: HTMLCanvasElement;
+    pixelRatio?: number;
+    terminateWorkerOnDispose?: boolean;
+}
+export declare function serializeDomEvent(event: Event): SerializedDomEvent;
+export declare class OffscreenViewerHost extends EventTarget {
+    #private;
+    readonly el: HTMLElement;
+    readonly worker: Worker;
+    readonly canvas: HTMLCanvasElement;
+    constructor(options: OffscreenViewerHostOptions);
+    static isSupported(): boolean;
+    init(): Promise<void>;
+    request<T = unknown>(command: string, payload?: unknown): Promise<T>;
+    dispose(): void;
+}

package/dist/src/worker/WorkerDomTarget.d.ts

@@ -0,0 +1,44 @@
+import type { SerializedDomEvent, WorkerCanvasSize } from './protocol';
+export type WorkerDomTarget = OffscreenCanvas & HTMLElement;
+declare class WorkerDomEvent {
+    readonly type: string;
+    readonly timeStamp: number;
+    readonly target: WorkerDomTarget;
+    readonly currentTarget: WorkerDomTarget;
+    readonly cancelable = true;
+    readonly bubbles = true;
+    defaultPrevented: boolean;
+    cancelBubble: boolean;
+    immediatePropagationStopped: boolean;
+    pointerId: number;
+    pointerType: string;
+    button: number;
+    buttons: number;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    movementX: number;
+    movementY: number;
+    clientX: number;
+    clientY: number;
+    offsetX: number;
+    offsetY: number;
+    pageX: number;
+    pageY: number;
+    screenX: number;
+    screenY: number;
+    deltaX: number;
+    deltaY: number;
+    deltaZ: number;
+    deltaMode: number;
+    constructor(data: SerializedDomEvent, target: WorkerDomTarget);
+    preventDefault(): void;
+    stopPropagation(): void;
+    stopImmediatePropagation(): void;
+    composedPath(): WorkerDomTarget[];
+}
+export declare function createWorkerDomTarget(canvas: OffscreenCanvas, initialSize: WorkerCanvasSize): WorkerDomTarget;
+export declare function resizeWorkerDomTarget(target: WorkerDomTarget, size: WorkerCanvasSize): void;
+export declare function dispatchWorkerDomEvent(target: WorkerDomTarget, data: SerializedDomEvent): WorkerDomEvent;
+export {};

package/dist/src/worker/createWorkerViewer.d.ts

@@ -0,0 +1,18 @@
+import { Viewer } from '../viewers/Viewer';
+export type WorkerViewerCommand = (payload: unknown) => unknown | Promise<unknown>;
+export type WorkerViewerDispose = () => void | Promise<void>;
+export interface WorkerViewerRuntime {
+    readonly viewer: Viewer;
+    readonly canvas: OffscreenCanvas;
+    status(message: string): void;
+    emit(type: string, detail?: unknown): void;
+    registerCommand(name: string, command: WorkerViewerCommand): () => void;
+    onDispose(dispose: WorkerViewerDispose): () => void;
+    ready(detail?: unknown): void;
+}
+/**
+ * Creates a u-space Viewer after the main thread transfers an OffscreenCanvas.
+ * Call this at module top level; the message listener is installed synchronously
+ * before the returned promise waits for the host initialization message.
+ */
+export declare function createWorkerViewer(): Promise<WorkerViewerRuntime>;

package/dist/src/worker/decodeGltfModel.d.ts

@@ -0,0 +1,10 @@
+import { type DecodedGltfModelPacket, type ModelDecodeRequestOptions } from './modelDecodeProtocol';
+export interface ModelDecodeResourceHandle {
+    url: string;
+    complete(error?: unknown): void;
+}
+export interface ModelDecodeResourceResolver {
+    resolve(url: string, signal: AbortSignal): Promise<ModelDecodeResourceHandle>;
+}
+export declare function decodeGltfModelPacket(url: string, source: ArrayBuffer, options?: ModelDecodeRequestOptions, signal?: AbortSignal, resourceResolver?: ModelDecodeResourceResolver): Promise<DecodedGltfModelPacket>;
+export declare function loadGltfModelPacket(url: string, options?: ModelDecodeRequestOptions, signal?: AbortSignal, resourceResolver?: ModelDecodeResourceResolver): Promise<DecodedGltfModelPacket>;

package/dist/src/worker/getTransferables.d.ts

@@ -0,0 +1 @@
+export declare function getTransferables(value: unknown): Transferable[];

package/dist/src/worker/index.d.ts

@@ -0,0 +1,3 @@
+export * from './protocol';
+export * from './OffscreenViewerHost';
+export * from './getTransferables';

package/dist/src/worker/installWorkerImageLoader.d.ts

@@ -0,0 +1,8 @@
+export { clampWorkerImageDimensions, createWorkerImageBitmap } from './workerImageUtils';
+/**
+ * Makes Three.js TextureLoader/CubeTextureLoader usable in a Worker by loading
+ * images with fetch() and createImageBitmap() instead of document.createElement('img').
+ * Images larger than WebGPU's portable 8192px limit are downscaled before
+ * decoding so they cannot invalidate the device's texture bindings.
+ */
+export declare function installWorkerImageLoader(): void;

package/dist/src/worker/model-decoder.d.ts

@@ -0,0 +1,13 @@
+import { type ModelDecodeWorkerRequest, type ModelDecodeWorkerResponse } from './modelDecodeProtocol';
+export * from './modelDecodeProtocol';
+interface DecodeWorkerScope {
+    addEventListener(type: 'message', listener: (event: MessageEvent<ModelDecodeWorkerRequest>) => void): void;
+    postMessage(message: ModelDecodeWorkerResponse, transfer?: Transferable[]): void;
+    close(): void;
+}
+/**
+ * Installs a serial, acknowledged static glTF/SBMX decoder in the current
+ * dedicated Worker. Only one decoded packet may be in flight at a time so a
+ * large scene cannot fill the render Worker's message queue with model data.
+ */
+export declare function installModelDecodeWorker(scope?: DecodeWorkerScope): void;

package/dist/src/worker/modelDecodeProtocol.d.ts

@@ -0,0 +1,205 @@
+export declare const MODEL_DECODE_PROTOCOL_VERSION: 3;
+export interface SerializedModelDecodeError {
+    message: string;
+    name?: string;
+    stack?: string;
+}
+export interface ModelDecodeRequestOptions {
+    persistent?: boolean;
+    headers?: Record<string, string>;
+    credentials?: RequestCredentials;
+    /** Original absolute model URL used to resolve relative glTF dependencies. */
+    resourceBaseUrl?: string;
+}
+export interface GltfBufferDefinition {
+    byteLength: number;
+    uri?: string;
+    name?: string;
+}
+export interface GltfBufferViewDefinition {
+    buffer: number;
+    byteOffset?: number;
+    byteLength: number;
+    byteStride?: number;
+    target?: number;
+    name?: string;
+    extensions?: Record<string, unknown>;
+}
+export interface GltfAccessorDefinition {
+    bufferView?: number;
+    byteOffset?: number;
+    componentType: number;
+    normalized?: boolean;
+    count: number;
+    type: string;
+    min?: number[];
+    max?: number[];
+    sparse?: unknown;
+    name?: string;
+}
+export interface GltfTextureInfo {
+    index: number;
+    texCoord?: number;
+    scale?: number;
+    strength?: number;
+    extensions?: Record<string, unknown>;
+}
+export interface GltfMaterialDefinition {
+    name?: string;
+    pbrMetallicRoughness?: {
+        baseColorFactor?: number[];
+        baseColorTexture?: GltfTextureInfo;
+        metallicFactor?: number;
+        roughnessFactor?: number;
+        metallicRoughnessTexture?: GltfTextureInfo;
+    };
+    normalTexture?: GltfTextureInfo;
+    occlusionTexture?: GltfTextureInfo;
+    emissiveTexture?: GltfTextureInfo;
+    emissiveFactor?: number[];
+    alphaMode?: 'OPAQUE' | 'MASK' | 'BLEND';
+    alphaCutoff?: number;
+    doubleSided?: boolean;
+    extras?: unknown;
+    extensions?: Record<string, unknown>;
+}
+export interface GltfPrimitiveDefinition {
+    attributes: Record<string, number>;
+    indices?: number;
+    material?: number;
+    mode?: number;
+    targets?: unknown[];
+    extensions?: Record<string, unknown>;
+}
+export interface GltfMeshDefinition {
+    name?: string;
+    primitives: GltfPrimitiveDefinition[];
+    extras?: unknown;
+}
+export interface GltfNodeDefinition {
+    name?: string;
+    mesh?: number;
+    camera?: number;
+    children?: number[];
+    matrix?: number[];
+    translation?: number[];
+    rotation?: number[];
+    scale?: number[];
+    weights?: number[];
+    skin?: number;
+    extras?: unknown;
+    extensions?: Record<string, unknown>;
+}
+export interface GltfSceneDefinition {
+    name?: string;
+    nodes?: number[];
+    extras?: unknown;
+}
+export interface GltfImageDefinition {
+    name?: string;
+    uri?: string;
+    mimeType?: string;
+    bufferView?: number;
+}
+export interface GltfSamplerDefinition {
+    name?: string;
+    magFilter?: number;
+    minFilter?: number;
+    wrapS?: number;
+    wrapT?: number;
+}
+export interface GltfTextureDefinition {
+    name?: string;
+    sampler?: number;
+    source?: number;
+    extensions?: Record<string, unknown>;
+}
+export interface GltfDocument {
+    asset: {
+        version: string;
+        generator?: string;
+    };
+    scene?: number;
+    scenes?: GltfSceneDefinition[];
+    nodes?: GltfNodeDefinition[];
+    meshes?: GltfMeshDefinition[];
+    accessors?: GltfAccessorDefinition[];
+    bufferViews?: GltfBufferViewDefinition[];
+    buffers?: GltfBufferDefinition[];
+    materials?: GltfMaterialDefinition[];
+    textures?: GltfTextureDefinition[];
+    samplers?: GltfSamplerDefinition[];
+    images?: GltfImageDefinition[];
+    animations?: unknown[];
+    skins?: unknown[];
+    cameras?: unknown[];
+    extensionsUsed?: string[];
+    extensionsRequired?: string[];
+    extensions?: Record<string, unknown>;
+}
+export interface DecodedGltfModelPacket {
+    protocolVersion: typeof MODEL_DECODE_PROTOCOL_VERSION;
+    kind: 'gltf-static';
+    url: string;
+    document: GltfDocument;
+    buffers: ArrayBuffer[];
+    images: ImageBitmap[];
+    /** Stable content identities used to preserve material batching across models. */
+    imageKeys: string[];
+}
+/**
+ * Validates the parts of the glTF node graph that would otherwise make
+ * recursive Object3D reconstruction unsafe. glTF nodes form a forest: a node
+ * cannot be repeated under one parent, have multiple parents, or form cycles.
+ */
+export declare function validateDecodedGltfNodeGraph(document: GltfDocument): void;
+export type ModelDecodeWorkerRequest = {
+    type: 'decode';
+    id: number;
+    url: string;
+    options: ModelDecodeRequestOptions;
+} | {
+    type: 'cancel';
+    id: number;
+} | {
+    type: 'ack';
+    id: number;
+} | {
+    type: 'resource-resolved';
+    id: number;
+    resourceId: number;
+    url?: string;
+    error?: SerializedModelDecodeError;
+} | {
+    type: 'dispose';
+};
+export type ModelDecodeWorkerResponse = {
+    type: 'decoded';
+    id: number;
+    packet: DecodedGltfModelPacket;
+} | {
+    type: 'unsupported';
+    id: number;
+    reason: string;
+} | {
+    type: 'error';
+    id: number;
+    error: SerializedModelDecodeError;
+} | {
+    type: 'resolve-resource';
+    id: number;
+    resourceId: number;
+    url: string;
+} | {
+    type: 'resource-complete';
+    id: number;
+    resourceId: number;
+    ok: boolean;
+    error?: SerializedModelDecodeError;
+} | {
+    type: 'disposed';
+};
+export declare class UnsupportedModelDecodeError extends Error {
+    name: string;
+    constructor(message: string);
+}

package/dist/src/worker/protocol.d.ts

@@ -0,0 +1,102 @@
+export interface WorkerCanvasSize {
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    pixelRatio: number;
+}
+export interface SerializedDomEvent {
+    type: string;
+    pointerId?: number;
+    pointerType?: string;
+    button?: number;
+    buttons?: number;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+    movementX?: number;
+    movementY?: number;
+    clientX?: number;
+    clientY?: number;
+    offsetX?: number;
+    offsetY?: number;
+    pageX?: number;
+    pageY?: number;
+    screenX?: number;
+    screenY?: number;
+    deltaX?: number;
+    deltaY?: number;
+    deltaZ?: number;
+    deltaMode?: number;
+}
+export interface WorkerRendererStats {
+    drawCalls: number;
+    frameCalls: number;
+    triangles: number;
+    points: number;
+    lines: number;
+    /** Rolling average frame interval in milliseconds. */
+    frameTime: number;
+    frameTiming: WorkerFrameTimingStats;
+}
+export interface WorkerFrameTimingStats {
+    /** Number of actively rendered frames in the rolling window. */
+    samples: number;
+    fps: number;
+    average: number;
+    p95: number;
+    max: number;
+    /** Percentage of samples above the 25 ms budget. */
+    missedFramePercent: number;
+}
+export interface WorkerErrorData {
+    message: string;
+    name?: string;
+    stack?: string;
+}
+export type HostToWorkerMessage = {
+    type: 'init';
+    canvas: OffscreenCanvas;
+    size: WorkerCanvasSize;
+} | {
+    type: 'resize';
+    size: WorkerCanvasSize;
+} | {
+    type: 'dom-event';
+    event: SerializedDomEvent;
+} | {
+    type: 'request';
+    id: number;
+    command: string;
+    payload?: unknown;
+} | {
+    type: 'dispose';
+};
+export type WorkerToHostMessage = {
+    type: 'initialized';
+} | {
+    type: 'ready';
+    detail?: unknown;
+} | {
+    type: 'status';
+    message: string;
+} | {
+    type: 'stats';
+    stats: WorkerRendererStats;
+} | {
+    type: 'event';
+    eventType: string;
+    detail?: unknown;
+} | {
+    type: 'response';
+    id: number;
+    result?: unknown;
+    error?: WorkerErrorData;
+} | {
+    type: 'error';
+    error: WorkerErrorData;
+} | {
+    type: 'disposed';
+};
+export declare function serializeError(error: unknown): WorkerErrorData;

package/dist/src/worker/runtime.d.ts

@@ -0,0 +1,2 @@
+export * from './protocol';
+export * from './createWorkerViewer';

package/dist/src/worker/workerImageUtils.d.ts

@@ -0,0 +1,8 @@
+interface ImageDimensions {
+    width: number;
+    height: number;
+}
+export declare const MAX_WORKER_TEXTURE_DIMENSION_2D = 8192;
+export declare function clampWorkerImageDimensions(width: number, height: number, maxDimension?: number): ImageDimensions | null;
+export declare function createWorkerImageBitmap(blob: Blob, options?: ImageBitmapOptions): Promise<ImageBitmap>;
+export {};

package/dist/worker/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("../protocol-IUAzx0lk.cjs"),u=require("../getTransferables-C97JPUVf.cjs"),n=["click","dblclick","contextmenu","pointerdown","pointerup","pointermove","pointercancel","wheel"];function a(i){const e=i,t=i,s=i;return{type:i.type,pointerId:t.pointerId,pointerType:t.pointerType,button:e.button,buttons:e.buttons,altKey:e.altKey,ctrlKey:e.ctrlKey,metaKey:e.metaKey,shiftKey:e.shiftKey,movementX:e.movementX,movementY:e.movementY,clientX:e.clientX,clientY:e.clientY,offsetX:e.offsetX,offsetY:e.offsetY,pageX:e.pageX,pageY:e.pageY,screenX:e.screenX,screenY:e.screenY,deltaX:s.deltaX,deltaY:s.deltaY,deltaZ:s.deltaZ,deltaMode:s.deltaMode}}function o(i){const e=new Error(i.message);return e.name=i.name??"WorkerError",i.stack&&(e.stack=i.stack),e}class r extends EventTarget{el;worker;canvas;#u;#f;#r=null;#i=new Map;#b=0;#t=!1;#e=!1;#n=null;#o=null;#a=null;#h=new Map;#s=0;#p=0;constructor(e){super(),this.el=e.el,this.worker=e.worker,this.canvas=e.canvas??document.createElement("canvas"),this.#u=e.pixelRatio,this.#f=e.terminateWorkerOnDispose??!0,this.canvas.style.width="100%",this.canvas.style.height="100%",this.canvas.style.display="block",this.canvas.style.touchAction="none",this.canvas.parentElement||this.el.appendChild(this.canvas)}static isSupported(){return typeof Worker<"u"&&typeof OffscreenCanvas<"u"&&typeof HTMLCanvasElement<"u"&&"transferControlToOffscreen"in HTMLCanvasElement.prototype}init(){if(this.#n)return this.#n;if(this.#e)return Promise.reject(new Error("OffscreenViewerHost has been disposed."));if(!r.isSupported())return Promise.reject(new Error("This browser does not support transferring a canvas to a Worker."));this.#n=new Promise((e,t)=>{this.#o=e,this.#a=t}),this.worker.addEventListener("message",this.#y),this.worker.addEventListener("error",this.#g),this.#z(),this.#T();try{const e=this.canvas.transferControlToOffscreen(),t={type:"init",canvas:e,size:this.#v()};this.worker.postMessage(t,[e])}catch(e){const t=e instanceof Error?e:new Error(String(e));this.#d(t),this.#l()}return this.#n}request(e,t){if(this.#e)return Promise.reject(new Error("OffscreenViewerHost has been disposed."));if(!this.#t)return Promise.reject(new Error("The Worker viewer has not initialized yet."));const s=++this.#b,h={type:"request",id:s,command:e,payload:t};return this.worker.postMessage(h),new Promise((c,l)=>{this.#i.set(s,{resolve:d=>c(d),reject:l})})}dispose(){const e=new Error("OffscreenViewerHost has been disposed.");if(!this.#d(e))return;const t={type:"dispose"};this.worker.postMessage(t),this.#p=window.setTimeout(this.#l,1e3)}#z(){for(const e of n)this.canvas.addEventListener(e,this.#m,{passive:e!=="wheel"&&e!=="contextmenu"})}#M(){for(const e of n)this.canvas.removeEventListener(e,this.#m)}#T(){this.#r=new ResizeObserver(this.#c),this.#r.observe(this.el),window.addEventListener("resize",this.#c)}#v(){const e=this.canvas.getBoundingClientRect();return{width:Math.max(1,e.width||this.el.clientWidth),height:Math.max(1,e.height||this.el.clientHeight),top:e.top,left:e.left,pixelRatio:this.#u??Math.min(window.devicePixelRatio,1.5)}}#c=()=>{if(!this.#t||this.#e)return;const e={type:"resize",size:this.#v()};this.worker.postMessage(e)};#m=e=>{(e.type==="wheel"||e.type==="contextmenu")&&e.preventDefault();const t=e;if(e.type==="pointerdown")try{this.canvas.setPointerCapture(t.pointerId)}catch{}if(e.type==="pointerup"||e.type==="pointercancel"){this.#w();try{this.canvas.hasPointerCapture(t.pointerId)&&this.canvas.releasePointerCapture(t.pointerId)}catch{}}const s=a(e);if(e.type==="pointermove"){this.#h.set(s.pointerId??-1,s),this.#s||(this.#s=requestAnimationFrame(this.#w));return}this.#E(s)};#w=()=>{this.#s=0;for(const e of this.#h.values())this.#E(e);this.#h.clear()};#E(e){if(!this.#t||this.#e)return;const t={type:"dom-event",event:e};this.worker.postMessage(t)}#y=e=>{const t=e.data;if(!(this.#e&&t.type!=="error"&&t.type!=="disposed"))switch(t.type){case"initialized":if(this.#e)break;this.#t=!0,this.#o?.(),this.#o=null,this.#a=null,this.#c(),this.dispatchEvent(new Event("initialized"));break;case"ready":this.dispatchEvent(new CustomEvent("ready",{detail:t.detail}));break;case"status":this.dispatchEvent(new CustomEvent("status",{detail:t.message}));break;case"stats":this.dispatchEvent(new CustomEvent("stats",{detail:t.stats}));break;case"event":this.dispatchEvent(new CustomEvent(t.eventType,{detail:t.detail}));break;case"response":{const s=this.#i.get(t.id);if(!s)break;this.#i.delete(t.id),t.error?s.reject(o(t.error)):s.resolve(t.result);break}case"error":{const s=o(t.error);this.#t||this.#k(s),this.dispatchEvent(new CustomEvent("error",{detail:s}));break}case"disposed":this.#d(new Error("The Worker viewer has been disposed.")),this.dispatchEvent(new Event("disposed")),this.#l();break}};#g=e=>{const t=e.error instanceof Error?e.error:new Error(e.message);this.#d(t),this.dispatchEvent(new CustomEvent("error",{detail:t})),this.#l()};#l=()=>{window.clearTimeout(this.#p),this.#p=0,this.worker.removeEventListener("message",this.#y),this.worker.removeEventListener("error",this.#g),this.#f&&this.worker.terminate()};#d(e){if(this.#e)return!1;this.#e=!0,this.#s&&cancelAnimationFrame(this.#s),this.#s=0,this.#h.clear(),this.#r?.disconnect(),this.#r=null,window.removeEventListener("resize",this.#c),this.#M(),this.#t||this.#k(e);for(const t of this.#i.values())t.reject(e);return this.#i.clear(),this.canvas.remove(),!0}#k(e){this.#a?.(e),this.#o=null,this.#a=null}}exports.serializeError=p.serializeError;exports.getTransferables=u.getTransferables;exports.OffscreenViewerHost=r;exports.serializeDomEvent=a;