soonspacejs 3.0.0-alpha.1 → 3.0.0-alpha.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soonspacejs",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.10",
   "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

@@ -1,4 +1,4 @@
-import { Box3, Matrix4, Object3D, Raycaster, Scene } from 'three';
+import { Box3, Matrix4, Object3D, Raycaster, Scene, BufferGeometry } from 'three';
 import { Entity, EntityChange, EntityOptions } from './Entity';
 import { EntityHit } from './EntityRenderer';
 import { ModelResources, ModelLease, ModelLoadOptions } from './ModelResources';
@@ -19,6 +19,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;
@@ -42,6 +43,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;
@@ -49,12 +55,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;

package/types/Entity/EntityRenderer.d.ts

@@ -1,4 +1,4 @@
-import { Box3, Group, Matrix4, Raycaster, Intersection } from 'three';
+import { Box3, BufferGeometry, Group, Matrix4, Raycaster, Intersection } from 'three';
 import { Entity } from './Entity';
 import { RegisteredPart } from './ModelResources';
 import { TransparentSideVariants } from './TransparentSideVariants';
@@ -25,13 +25,19 @@ export declare class EntityRenderer {
     private dirtyGroups;
     private policyDirty;
     private bounds;
+    private sourceGeometries;
+    private geometryRefs;
     private enabled;
     private batchedEnabled;
     private rebuilds;
+    private sourceParts;
+    private sourceMeshes;
+    private batchCounts;
     private selection;
     private selectionDirty;
     private highlights;
     private highlightMaterial;
+    private highlightLineMaterial;
     constructor(sideVariants?: Pick<TransparentSideVariants, "register" | "unregister"> | undefined);
     add(input: EntityRenderInput): void;
     remove(entity: Entity): void;
@@ -44,15 +50,24 @@ export declare class EntityRenderer {
     private assignGroup;
     private rebuildGroup;
     private createBatch;
+    private createLineBatch;
+    private updateLineBatch;
+    private sortLineBatch;
     private updateBatch;
-    pick(raycaster: Raycaster): EntityHit[];
+    /** Live geometry membership is updated only when model parts are added/removed. */
+    getSourceGeometries(): ReadonlySet<BufferGeometry>;
+    pick(raycaster: Raycaster, surfaces?: boolean): EntityHit[];
     getBounds(entity: Entity): Box3;
     getStats(): {
+        sourceParts: number;
+        renderObjects: number;
+        rebuilds: number;
         instancedBatches: number;
         batchedBatches: number;
         independentObjects: number;
-        rebuilds: number;
+        lineBatches: number;
     };
+    private countBatch;
     private clearBatches;
     dispose(): void;
 }

package/types/Entity/ModelResources.d.ts

@@ -1,6 +1,10 @@
 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';
+    pickable?: boolean;
     geometry: BufferGeometry;
     material: Material | MaterialLease;
     matrix: Matrix4;
@@ -60,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/Entity/StaticModelPool.d.ts

@@ -0,0 +1,28 @@
+import { Object3D } from 'three';
+import { ModelLease, ModelResources } from './ModelResources';
+export interface StaticModelSnapshot {
+    object: Object3D;
+    model?: ModelLease;
+    empty?: boolean;
+    release: () => void;
+}
+export 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;
+}

package/types/Entity/index.d.ts

@@ -1,4 +1,6 @@
 export { Entity, } from './Entity';
+export { StaticModelPool, } from './StaticModelPool';
+export type { StaticModelSnapshot, StaticModelExtraction, } from './StaticModelPool';
 export type { EntityOptions, EntityChange, } from './Entity';
 export { EntityCollection, } from './EntityCollection';
 export { ModelResources, ResourceLease, ModelResourceUnsupportedError, } from './ModelResources';

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/EventHandler.d.ts

@@ -7,7 +7,10 @@ declare class EventHandler {
     /**
      * PC
      */
-    private mouseDownTimes;
+    private mouseClickGroup;
+    private mouseDownGroup;
+    private pendingMouseClicks;
+    private disposed;
     private mouseDownEvent;
     private container;
     private options;
@@ -30,6 +33,7 @@ declare class EventHandler {
     private handleMouseDown;
     private handleMouseMove;
     private handleMouseUp;
+    private cancelPendingMouseClicks;
     private handleDblClick;
     private handleMouseWheel;
     private handleTouchStart;

package/types/Viewport/Info.d.ts

@@ -6,6 +6,7 @@ declare class Info {
     container: HTMLDivElement;
     private renderStateFrame;
     private disposed;
+    private cleanups;
     state: {
         objects: number;
         meshes: number;

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/Viewport/render-info-change.d.ts

@@ -0,0 +1,5 @@
+import { Object3D } from 'three';
+export declare function getRenderInfoSourceMeshes(object: Object3D): number | undefined;
+export declare function setRenderInfoSourceMeshes(object: Object3D, count: number): void;
+export declare function observeRenderInfoChange(object: Object3D, listener: () => void): () => void;
+export declare function notifyRenderInfoChange(object: Object3D): 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
@@ -2164,6 +2184,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 +2208,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 +2220,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 +2290,10 @@ declare class EventHandler {
     /**
      * PC
      */
-    private mouseDownTimes;
+    private mouseClickGroup;
+    private mouseDownGroup;
+    private pendingMouseClicks;
+    private disposed;
     private mouseDownEvent;
     private container;
     private options;
@@ -2281,6 +2316,7 @@ declare class EventHandler {
     private handleMouseDown;
     private handleMouseMove;
     private handleMouseUp;
+    private cancelPendingMouseClicks;
     private handleDblClick;
     private handleMouseWheel;
     private handleTouchStart;
@@ -2308,7 +2344,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 +2699,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 +3104,7 @@ declare class Info {
     container: HTMLDivElement;
     private renderStateFrame;
     private disposed;
+    private cleanups;
     state: {
         objects: number;
         meshes: number;
@@ -3479,6 +3523,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;
@@ -3536,6 +3596,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 +3679,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 +3707,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 +4267,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 +4529,19 @@ declare namespace shared {
         cloneDeep,
         cloneMaterials,
         disposeMaterials,
+        configureRequestLoader,
+        createFileLoader,
+        createImageLoader,
+        createTextureLoader,
+        createCubeTextureLoader,
+        configureGLTFLoader,
         FileResponseType,
         fetchFile,
         imageLoader,
         textureLoader,
         rgbeLoader,
+        getRequestHeaders,
+        fetchResource,
         isObjectBehindCamera,
         isObjectOccludeVisible,
         poiNodeOccludeHandler,
@@ -6108,6 +6185,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 +6787,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;
     /**