soonspacejs 3.0.0-alpha.1 → 3.0.0-alpha.11

package/types/index.d.ts

@@ -14,6 +14,7 @@ import { Camera } from 'three';
 import { CanvasTexture } from 'three';
 import { ColorRepresentation } from 'three';
 import { CubeTexture } from 'three';
+import { CubeTextureLoader } from 'three';
 import { Curve } from 'three';
 import type { CurvePath } from 'three';
 import { DataTexture } from 'three';
@@ -29,6 +30,7 @@ import type { EulerOrder } from 'three';
 import { Event as Event_2 } from 'three';
 import { EventDispatcher } from 'three';
 import { EventListener as EventListener_2 } from 'three';
+import { FileLoader } from 'three';
 import { GLTFExporterOptions } from 'three/examples/jsm/exporters/GLTFExporter.js';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { GridHelper } from 'three';
@@ -1140,6 +1142,11 @@ declare class Bvh {
     dispose(): void;
 }
 
+declare interface CacheOptions {
+    maxEntryBytes?: number;
+    onDiagnostic?: (event: ModelCacheDiagnostic) => void;
+}
+
 declare const calculateScaleFactor: (point3: Vector3, radiusPx: number, camera: Camera, size: Vector2) => number;
 
 declare class CameraManager {
@@ -1274,6 +1281,16 @@ export declare type ClonePoiInfo = Omit<PoiInfo, 'url' | 'type'>;
  */
 declare function computeTargetByRotation(position: IVector3, rotation: Rotation, scalar?: number): Vector3;
 
+declare function configureGLTFLoader(loader: GLTFLoader): GLTFLoader;
+
+/** Only SDK-owned instances are adapted; resolve before snapshotting the actual request. */
+declare function configureRequestLoader<T extends {
+    load: any;
+    path: string;
+    requestHeader: any;
+    manager: LoadingManager;
+}>(loader: T): T;
+
 /**
  * 以等分链的方式配置几何体的顶点权重
  * @param options - 选项
@@ -1586,6 +1603,8 @@ export declare interface CreateChainSkinnedMeshForMeshOptions_Base {
     skeleton: Skeleton;
 }
 
+declare function createCubeTextureLoader(manager?: LoadingManager): CubeTextureLoader;
+
 export declare function createCurveAnimationClip(options: CreateCurveAnimationClipByCurveOptions): CreateCurveAnimationClipReturn;
 
 export declare function createCurveAnimationClip(options: CreateCurveAnimationClipByPolylineOptions): CreateCurveAnimationClipReturn;
@@ -1694,6 +1713,8 @@ export declare interface CreateCurveAnimationClipReturn {
  */
 export declare function createEqualChainBones(boneOpts: EqualChainBoneOptions): Bone[];
 
+declare function createFileLoader(manager?: LoadingManager): FileLoader;
+
 /**
  *  创建 查找位置附近的 box 空间范围内的物体
  * @param boxSpace - 描述查找空间的信息对象
@@ -1727,6 +1748,8 @@ export declare function createFindObjectsNearPath(points: Vector3[], radius: num
  */
 export declare function createGuiAnimationController(action: AnimationAction): GuiAnimationController;
 
+declare function createImageLoader(manager?: LoadingManager): ImageLoader;
+
 /**
  * createKeyframeTracksOfCurveAnimationByPolyline 的选项
  */
@@ -1831,6 +1854,8 @@ export declare function createPlaneMatrix(points: Vector3[]): Matrix3;
 
 export declare function createTexture(image: string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, cache?: boolean, textureCache?: Map<string, Texture>): Texture<unknown, TextureEventMap>;
 
+declare function createTextureLoader(manager?: LoadingManager): TextureLoader;
+
 /**
  * 创建 uv 变换矩阵
  * @remarks
@@ -2164,6 +2189,7 @@ export declare class EntityCollection {
     private pendingModels;
     private selected;
     private selectionDirty;
+    private selectionHighlight;
     constructor(scene: Scene, requestRender: () => void, models: ModelResources, sideVariants?: Pick<TransparentSideVariants, 'register' | 'unregister'>);
     get roots(): readonly Entity[];
     getById(id: string): Entity | undefined;
@@ -2187,6 +2213,11 @@ export declare class EntityCollection {
     attach(entity: Entity, object: Object3D): void;
     detach(entity: Entity, object: Object3D): void;
     pick(raycaster: Raycaster): EntityHit[];
+    private pickAttachments;
+    /** On-demand source surfaces for drawing/projection. These meshes never enter the scene. */
+    pickSurfaces(raycaster: Raycaster): EntityHit[];
+    /** Explicit BVH preparation snapshots current parts; later loads need another preparation. */
+    getSourceGeometries(): ReadonlySet<BufferGeometry>;
     /** Fresh world bounds from committed transforms, including hidden content. */
     getBounds(entity: Entity, options?: {
         includeDescendants?: boolean;
@@ -2194,12 +2225,18 @@ export declare class EntityCollection {
     getStats(): {
         updatedEntities: number;
         entities: number;
+        sourceParts: number;
+        renderObjects: number;
+        rebuilds: number;
         instancedBatches: number;
         batchedBatches: number;
         independentObjects: number;
-        rebuilds: number;
+        lineBatches: number;
     };
-    setSelection(entities: readonly Entity[]): void;
+    /** Selection identity is retained even when the optional visual overlay is disabled. */
+    setSelection(entities: readonly Entity[], options?: {
+        highlight?: boolean;
+    }): void;
     getSelection(): readonly Entity[];
     setInstancingEnabled(enabled: boolean): void;
     setBatchedEnabled(enabled: boolean): void;
@@ -2258,7 +2295,10 @@ declare class EventHandler {
     /**
      * PC
      */
-    private mouseDownTimes;
+    private mouseClickGroup;
+    private mouseDownGroup;
+    private pendingMouseClicks;
+    private disposed;
     private mouseDownEvent;
     private container;
     private options;
@@ -2281,6 +2321,7 @@ declare class EventHandler {
     private handleMouseDown;
     private handleMouseMove;
     private handleMouseUp;
+    private cancelPendingMouseClicks;
     private handleDblClick;
     private handleMouseWheel;
     private handleTouchStart;
@@ -2308,7 +2349,11 @@ declare class FBXLoader extends Loader<any, string> {
 
 declare const fetchFile: <T = any>(url: string, responseType: FileResponseType) => Promise<T>;
 
-export declare const FileRequestHeaders: {};
+/** Keep the caller's Request/RequestInit semantics and snapshot at dispatch time. */
+declare function fetchResource(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+
+/** Backwards-compatible alias. Both names refer to the same mutable object. */
+export declare const FileRequestHeaders: Record<string, string>;
 
 declare type FileResponseType = 'json' | 'arraybuffer' | 'blob' | 'document' | 'text';
 
@@ -2659,6 +2704,9 @@ export declare function getPolygonGeometryInfo(points: Vector3[]): {
     position: Vector3;
 };
 
+/** Snapshot defaults and explicit headers. Explicit names win case-insensitively. */
+declare function getRequestHeaders(input: string | URL | Request, headers?: HeadersInit): Record<string, string>;
+
 /**
  * 获取根骨骼
  * @remarks
@@ -3061,6 +3109,7 @@ declare class Info {
     container: HTMLDivElement;
     private renderStateFrame;
     private disposed;
+    private cleanups;
     state: {
         objects: number;
         meshes: number;
@@ -3479,6 +3528,37 @@ export declare interface ModelAnimationFindFunc {
     (animation: AnimationClip, index: number, animations: AnimationClip[]): boolean;
 }
 
+/** Raw HTTP model bytes only. Runtime leases / GPU graphs are never persisted. */
+declare class ModelBufferCache {
+    private readonly store;
+    private readonly enabled;
+    private readonly options;
+    private warned;
+    constructor(store?: LocalForage, enabled?: () => boolean, options?: () => CacheOptions);
+    private maximumEntryBytes;
+    private withinLimit;
+    private diagnose;
+    load(url: string, init: {
+        headers: Headers;
+        credentials: RequestCredentials;
+        signal?: AbortSignal;
+        redirect?: RequestRedirect;
+    }): Promise<ArrayBuffer>;
+    private key;
+    private mutate;
+    clear(): Promise<void>;
+}
+
+/** Cache diagnostics never contain resource URLs, headers or exception messages. */
+export declare interface ModelCacheDiagnostic {
+    key: string;
+    operation: 'read' | 'write' | 'skip';
+    reason: 'storage-error' | 'invalid-entry' | 'entry-too-large';
+    bytes?: number;
+    maxEntryBytes: number;
+    errorName?: string;
+}
+
 export declare interface ModelEventParams {
     target: Model;
     currentTarget: Mesh;
@@ -3536,6 +3616,8 @@ declare class ModelManage extends DefaultManage {
      */
     store: typeof default_2;
     cacheStore: typeof default_2;
+    readonly bufferCache: ModelBufferCache;
+    private texturePreloader?;
     loadingManager: LoadingManager;
     gltfLoader: GLTFLoader;
     fbxLoader: FBXLoader;
@@ -3617,6 +3699,9 @@ declare class ModelManage extends DefaultManage {
 }
 
 export declare interface ModelPart {
+    /** Omitted for triangle meshes. Basic line segments share the Entity lifecycle. */
+    kind?: 'mesh' | 'line-segments';
+    pickable?: boolean;
     geometry: BufferGeometry;
     material: Material | MaterialLease;
     matrix: Matrix4;
@@ -3642,8 +3727,9 @@ export declare class ModelResources {
     private pending;
     private urls;
     private gltfLoader;
+    private bufferCache;
     /** Borrow a host-configured loader; its decoder workers remain host-owned. */
-    setGLTFLoader(loader: GLTFLoader): void;
+    setGLTFLoader(loader: GLTFLoader, bufferCache?: ModelBufferCache): void;
     readonly materials: {
         register: (material: Material, options: {
             ownership: "transfer";
@@ -4201,6 +4287,9 @@ declare class RendererManager {
  */
 export declare function renderLoop(frameFun: (time: DOMHighResTimeStamp) => void): () => void;
 
+/** Default headers for SDK-owned HTTP(S) resource requests. */
+export declare const RequestHeaders: Record<string, string>;
+
 export declare class ResourceLease<T> {
     readonly registry: ModelResources;
     private record;
@@ -4460,11 +4549,19 @@ declare namespace shared {
         cloneDeep,
         cloneMaterials,
         disposeMaterials,
+        configureRequestLoader,
+        createFileLoader,
+        createImageLoader,
+        createTextureLoader,
+        createCubeTextureLoader,
+        configureGLTFLoader,
         FileResponseType,
         fetchFile,
         imageLoader,
         textureLoader,
         rgbeLoader,
+        getRequestHeaders,
+        fetchResource,
         isObjectBehindCamera,
         isObjectOccludeVisible,
         poiNodeOccludeHandler,
@@ -4499,6 +4596,8 @@ export declare interface SignalsState {
     backgroundChanged: Signal;
     beforeRender: Signal;
     sceneRendered: Signal;
+    /** Dispatches ModelCacheDiagnostic when persistent model caching fails or skips a size limit. */
+    modelCacheDiagnostic: Signal;
     tweenUpdate: Signal;
     hover: Signal;
     click: Signal;
@@ -6108,6 +6207,35 @@ export declare interface State {
     };
 }
 
+export declare interface StaticModelExtraction extends StaticModelSnapshot {
+    restore: () => void;
+}
+
+/** Load-session cache. It owns snapshots, never resources borrowed from procedural factories. */
+export declare class StaticModelPool {
+    private resources;
+    private options;
+    private materials;
+    private models;
+    private disposed;
+    constructor(resources: ModelResources, options?: {
+        pickableLines?: boolean;
+        ignoreRootVisibility?: boolean;
+    });
+    extract(root: Object3D): StaticModelExtraction;
+    /** Copy an immutable render snapshot without retaining/moving the source tree.
+     * The returned native remainder is owned by the snapshot, never the factory. */
+    snapshot(root: Object3D): StaticModelSnapshot;
+    dispose(): void;
+}
+
+export declare interface StaticModelSnapshot {
+    object: Object3D;
+    model?: ModelLease;
+    empty?: boolean;
+    release: () => void;
+}
+
 export declare interface StrokeSelectOptions extends BaseSelectOptions {
     isOpacityShow?: boolean;
     edgeColor?: IColor;
@@ -6681,7 +6809,7 @@ declare class Viewport {
         top: number;
     };
     getPositionByOffset(offset: OffsetPoint, z?: number, scalar?: number): Vector3;
-    getIntersects(event: MouseEvent | TouchEvent | OffsetPoint, objects?: Object3D<Object3DEventMap>[], options?: IntersectsOptions): Intersection<Object3D<Object3DEventMap>>[];
+    getIntersects(event: MouseEvent | TouchEvent | OffsetPoint, objects?: Object3D | Object3D[], options?: IntersectsOptions): Intersection<Object3D<Object3DEventMap>>[];
     rayClash(startPoint?: Vector3, dir?: Vector3, objects?: Mesh<BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap>, Material<MaterialEventMap> | Material<MaterialEventMap>[], Object3DEventMap>[]): Intersection<Object3D<Object3DEventMap>>[];
     clearSignals(): void;
     /**
@@ -6722,6 +6850,8 @@ export declare interface ViewportOptions {
     closeInfoLog?: boolean;
     closeWarnLog?: boolean;
     useIndexedDB?: boolean;
+    /** Maximum bytes per persistent model resource; default 1 GiB, zero disables persistence. */
+    modelCacheMaxEntryBytes?: number;
 }
 
 export declare interface ViewportState {