soonspacejs 3.0.0-alpha.0 → 3.0.0-alpha.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soonspacejs",
-  "version": "3.0.0-alpha.0",
+  "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,7 +1,8 @@
-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';
+import { TransparentSideVariants } from './TransparentSideVariants';
 export declare class EntityCollection {
     private scene;
     private requestRender;
@@ -18,7 +19,8 @@ export declare class EntityCollection {
     private pendingModels;
     private selected;
     private selectionDirty;
-    constructor(scene: Scene, requestRender: () => void, models: ModelResources);
+    private selectionHighlight;
+    constructor(scene: Scene, requestRender: () => void, models: ModelResources, sideVariants?: Pick<TransparentSideVariants, 'register' | 'unregister'>);
     get roots(): readonly Entity[];
     getById(id: string): Entity | undefined;
     parentOf(entity: Entity): Entity | null;
@@ -41,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;
@@ -48,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,6 +1,7 @@
-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';
 export interface EntityRenderInput {
     entity: Entity;
     parts: readonly RegisteredPart[];
@@ -14,6 +15,7 @@ export interface EntityHit extends Intersection {
     attachment?: boolean;
 }
 export declare class EntityRenderer {
+    private readonly sideVariants?;
     readonly root: Group<import('three').Object3DEventMap>;
     private entries;
     private batches;
@@ -23,14 +25,20 @@ 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;
-    constructor();
+    private highlightLineMaterial;
+    constructor(sideVariants?: Pick<TransparentSideVariants, "register" | "unregister"> | undefined);
     add(input: EntityRenderInput): void;
     remove(entity: Entity): void;
     setEnabled(enabled: boolean): void;
@@ -42,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/TransparentSideVariants.d.ts

@@ -0,0 +1,27 @@
+import { Mesh, WebGLRenderer } from 'three';
+/** Reuse immutable side-specific programs for Entity-owned Standard materials.
+ * Only reuse materials with at least two registered supported users. Registration
+ * count is not visible draw count: a hidden/culled second user still enables reuse.
+ * Three still chooses each object's two passes and the complete render-list order.
+ */
+export declare class TransparentSideVariants {
+    private readonly renderer;
+    private readonly objects;
+    private readonly records;
+    private sequence;
+    private epoch;
+    private enabled;
+    private disposed;
+    private readonly render;
+    private readonly direct;
+    private readonly wrappedRender;
+    private readonly wrappedDirect;
+    constructor(renderer: WebGLRenderer);
+    private supported;
+    register(mesh: Mesh): void;
+    unregister(mesh: Mesh): void;
+    private sync;
+    setEnabled(enabled: boolean): void;
+    private release;
+    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

@@ -38,6 +38,7 @@ declare class Viewport {
     rendererCSS3D: CSS3DRenderer;
     readonly models: ModelResources;
     readonly entities: EntityCollection;
+    private readonly transparentSideVariants;
     pmremGenerator: PMREMGenerator;
     info: Info;
     stats: Stats;
@@ -126,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;