soonspacejs 3.0.0-alpha.6 → 3.0.0-alpha.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soonspacejs",
-  "version": "3.0.0-alpha.6",
+  "version": "3.0.0-alpha.9",
   "homepage": "https://www.xwbuilders.com/soonspacejs/",
   "description": "SoonSpace.js 3.0 alpha",
   "module": "./dist/index.esm.js",

package/types/Cache/ModelBufferCache.d.ts

@@ -0,0 +1,15 @@
+/** Raw HTTP model bytes only. Runtime leases / GPU graphs are never persisted. */
+export declare class ModelBufferCache {
+    private readonly store;
+    private readonly enabled;
+    constructor(store?: LocalForage, enabled?: () => boolean);
+    load(url: string, init: {
+        headers: Headers;
+        credentials: RequestCredentials;
+        signal?: AbortSignal;
+        redirect?: RequestRedirect;
+    }): Promise<ArrayBuffer>;
+    private key;
+    private mutate;
+    clear(): Promise<void>;
+}

package/types/Constants/headers.d.ts

@@ -1 +1,4 @@
-export declare const FileRequestHeaders: {};
+/** Default headers for SDK-owned HTTP(S) resource requests. */
+export declare const RequestHeaders: Record<string, string>;
+/** Backwards-compatible alias. Both names refer to the same mutable object. */
+export declare const FileRequestHeaders: Record<string, string>;

package/types/Entity/EntityCollection.d.ts

@@ -43,6 +43,8 @@ export declare class EntityCollection {
     attach(entity: Entity, object: Object3D): void;
     detach(entity: Entity, object: Object3D): void;
     pick(raycaster: Raycaster): EntityHit[];
+    /** On-demand source surfaces for drawing/projection. These meshes never enter the scene. */
+    pickSurfaces(raycaster: Raycaster): EntityHit[];
     /** Fresh world bounds from committed transforms, including hidden content. */
     getBounds(entity: Entity, options?: {
         includeDescendants?: boolean;

package/types/Entity/ModelResources.d.ts

@@ -1,5 +1,6 @@
 import { BufferGeometry, Material, Matrix4, Texture } from 'three';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { ModelBufferCache } from '../Cache/ModelBufferCache';
 export interface ModelPart {
     /** Omitted for triangle meshes. Basic line segments share the Entity lifecycle. */
     kind?: 'mesh' | 'line-segments';
@@ -63,8 +64,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";

package/types/Loader/TexturePreloader.d.ts

@@ -0,0 +1,44 @@
+import { Object3D, Texture } from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+interface TextureRenderer {
+    initTexture(texture: Texture): void;
+    domElement?: EventTarget;
+    getContext?: () => {
+        isContextLost(): boolean;
+    };
+}
+export declare const texturePreloaderFor: (loader: GLTFLoader) => TexturePreloader | undefined;
+export declare const bindTexturePreloader: (loader: GLTFLoader, queue: TexturePreloader) => void;
+/** Renderer-owned, frame-budgeted preparation for newly decoded GLTF roots. */
+export declare class TexturePreloader {
+    private readonly renderer;
+    private readonly budgetMs;
+    private entries;
+    private jobs;
+    private owners;
+    private frame;
+    private fallback;
+    private frameGeneration;
+    private contextLost;
+    private disposed;
+    readonly stats: {
+        uploads: number;
+        reused: number;
+        cancelled: number;
+        failed: number;
+        frames: number;
+        totalMs: number;
+        maxUploadMs: number;
+        maxFrameMs: number;
+    };
+    constructor(renderer: TextureRenderer, budgetMs?: number);
+    private onContextLost;
+    private onContextRestored;
+    private cancelFrame;
+    prepare(root: Object3D, signal?: AbortSignal, managerSignal?: AbortSignal): Promise<void>;
+    private schedule;
+    private pump;
+    private cancel;
+    dispose(): void;
+}
+export {};

package/types/Loader/request-loaders.d.ts

@@ -0,0 +1,24 @@
+import { CubeTextureLoader, FileLoader, ImageLoader, LoadingManager, TextureLoader } from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+/** Only SDK-owned instances are adapted; resolve before snapshotting the actual request. */
+export declare function configureRequestLoader<T extends {
+    load: any;
+    path: string;
+    requestHeader: any;
+    manager: LoadingManager;
+}>(loader: T): T;
+/** @internal Add parent-local headers only to copies of SDK-adapted handlers. */
+export declare function withRequestHeaders<T extends {
+    requestHeader: any;
+}>(loader: T, parentHeaders?: HeadersInit): T;
+export declare function createFileLoader(manager?: LoadingManager): FileLoader;
+export declare function createImageLoader(manager?: LoadingManager): ImageLoader;
+/** @internal Preserve the historical shared imageLoader FileLoader/Blob transport. */
+export declare function createFileImageLoader(manager?: LoadingManager): ImageLoader;
+export declare function createTextureLoader(manager?: LoadingManager): TextureLoader;
+export declare function createCubeTextureLoader(manager?: LoadingManager): CubeTextureLoader;
+export declare function configureGLTFLoader(loader: GLTFLoader): GLTFLoader;
+export declare function configureDRACOLoader(loader: DRACOLoader): DRACOLoader;
+export declare function configureKTX2Loader(loader: KTX2Loader): KTX2Loader;

package/types/Loader/scoped-gltf.d.ts

@@ -1,12 +1,15 @@
 import { GLTF, GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { ModelBufferCache } from '../Cache/ModelBufferCache';
 interface RequestScope {
     rootURL: string;
     headers: HeadersInit;
     signal?: AbortSignal;
+    bufferCache?: ModelBufferCache;
 }
 /** Each standard GLTFLoader parse constructs its parser synchronously, before any await. */
 export declare function parseScopedGLTF(loader: GLTFLoader, data: ArrayBuffer, path: string, scope: RequestScope): Promise<{
     gltf: GLTF;
     dependencyError?: unknown;
+    prepareTextures: () => Promise<void>;
 }>;
 export {};

package/types/Manager/ModelManage.d.ts

@@ -9,6 +9,7 @@ import { Group, GroupInfo, Model, ModelInfo } from '../Library';
 import { CloneModelInfo } from '../Interface';
 import { ObjectsCache } from '../Cache';
 import { default as DefaultManage } from './DefaultManage';
+import { ModelBufferCache } from '../Cache/ModelBufferCache';
 declare class ModelManage extends DefaultManage {
     readonly viewport: Viewport;
     readonly cache: ObjectsCache;
@@ -24,6 +25,8 @@ declare class ModelManage extends DefaultManage {
      */
     store: typeof localforage;
     cacheStore: typeof localforage;
+    readonly bufferCache: ModelBufferCache;
+    private texturePreloader?;
     loadingManager: LoadingManager;
     gltfLoader: GLTFLoader;
     fbxLoader: FBXLoader;

package/types/Shared/network.d.ts

@@ -1,7 +1,8 @@
-import { ImageLoader, TextureLoader } from 'three';
 import { HDRLoader } from 'three/examples/jsm/loaders/HDRLoader.js';
+export * from './request';
+export { configureRequestLoader, createFileLoader, createImageLoader, createTextureLoader, createCubeTextureLoader, configureGLTFLoader, } from '../Loader/request-loaders';
 export type FileResponseType = 'json' | 'arraybuffer' | 'blob' | 'document' | 'text';
 export declare const fetchFile: <T = any>(url: string, responseType: FileResponseType) => Promise<T>;
-export declare const imageLoader: ImageLoader;
-export declare const textureLoader: TextureLoader;
+export declare const imageLoader: import('three').ImageLoader;
+export declare const textureLoader: import('three').TextureLoader;
 export declare const rgbeLoader: HDRLoader;

package/types/Shared/request.d.ts

@@ -0,0 +1,4 @@
+/** Snapshot defaults and explicit headers. Explicit names win case-insensitively. */
+export declare function getRequestHeaders(input: string | URL | Request, headers?: HeadersInit): Record<string, string>;
+/** Keep the caller's Request/RequestInit semantics and snapshot at dispatch time. */
+export declare function fetchResource(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/types/Viewport/index.d.ts

@@ -127,7 +127,7 @@ declare class Viewport {
         top: number;
     };
     getPositionByOffset(offset: OffsetPoint, z?: number, scalar?: number): Vector3;
-    getIntersects(event: MouseEvent | TouchEvent | OffsetPoint, objects?: Object3D<import('three').Object3DEventMap>[], options?: IntersectsOptions): Intersection<Object3D<import('three').Object3DEventMap>>[];
+    getIntersects(event: MouseEvent | TouchEvent | OffsetPoint, objects?: Object3D | Object3D[], options?: IntersectsOptions): Intersection<Object3D<import('three').Object3DEventMap>>[];
     rayClash(startPoint?: Vector3, dir?: Vector3, objects?: Mesh<import('three').BufferGeometry<import('three').NormalBufferAttributes, import('three').BufferGeometryEventMap>, Material<import('three').MaterialEventMap> | Material<import('three').MaterialEventMap>[], import('three').Object3DEventMap>[]): Intersection<Object3D<import('three').Object3DEventMap>>[];
     clearSignals(): void;
     /**

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';
@@ -1274,6 +1276,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 +1598,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 +1708,8 @@ export declare interface CreateCurveAnimationClipReturn {
  */
 export declare function createEqualChainBones(boneOpts: EqualChainBoneOptions): Bone[];
 
+declare function createFileLoader(manager?: LoadingManager): FileLoader;
+
 /**
  *  创建 查找位置附近的 box 空间范围内的物体
  * @param boxSpace - 描述查找空间的信息对象
@@ -1727,6 +1743,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 +1849,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
@@ -2188,6 +2208,8 @@ export declare class EntityCollection {
     attach(entity: Entity, object: Object3D): void;
     detach(entity: Entity, object: Object3D): void;
     pick(raycaster: Raycaster): EntityHit[];
+    /** On-demand source surfaces for drawing/projection. These meshes never enter the scene. */
+    pickSurfaces(raycaster: Raycaster): EntityHit[];
     /** Fresh world bounds from committed transforms, including hidden content. */
     getBounds(entity: Entity, options?: {
         includeDescendants?: boolean;
@@ -2315,7 +2337,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';
 
@@ -2666,6 +2692,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
@@ -3487,6 +3516,22 @@ 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;
+    constructor(store?: LocalForage, enabled?: () => boolean);
+    load(url: string, init: {
+        headers: Headers;
+        credentials: RequestCredentials;
+        signal?: AbortSignal;
+        redirect?: RequestRedirect;
+    }): Promise<ArrayBuffer>;
+    private key;
+    private mutate;
+    clear(): Promise<void>;
+}
+
 export declare interface ModelEventParams {
     target: Model;
     currentTarget: Mesh;
@@ -3544,6 +3589,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;
@@ -3653,8 +3700,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";
@@ -4212,6 +4260,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;
@@ -4471,11 +4522,19 @@ declare namespace shared {
         cloneDeep,
         cloneMaterials,
         disposeMaterials,
+        configureRequestLoader,
+        createFileLoader,
+        createImageLoader,
+        createTextureLoader,
+        createCubeTextureLoader,
+        configureGLTFLoader,
         FileResponseType,
         fetchFile,
         imageLoader,
         textureLoader,
         rgbeLoader,
+        getRequestHeaders,
+        fetchResource,
         isObjectBehindCamera,
         isObjectOccludeVisible,
         poiNodeOccludeHandler,
@@ -6721,7 +6780,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;
     /**