soonspacejs 3.0.0-alpha.10 → 3.0.0-alpha.12

package/package.json

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

package/types/Cache/DecodedImageOwnership.d.ts

@@ -0,0 +1,6 @@
+import { Texture } from 'three';
+/** Only fresh pixels decoded by the parsed-model cache enter this registry. */
+export declare function ownDecodedImage(image: ImageBitmap): () => void;
+export declare function assertDecodedTextureAlive(texture: Texture): void;
+/** Capture the current pixels so later texture mutation cannot release another image. */
+export declare function retainDecodedTexture(texture: Texture): () => void;

package/types/Cache/ModelBufferCache.d.ts

@@ -1,15 +1,37 @@
+import { ModelCacheDiagnostic } from '../Interface/modelCache';
+interface CacheOptions {
+    maxEntryBytes?: number;
+    onDiagnostic?: (event: ModelCacheDiagnostic) => void;
+}
+export interface ModelBufferResult {
+    buffer: ArrayBuffer;
+    /** Hashed request identity; never a URL or credential. */
+    cacheKey: string | null;
+    cacheable: boolean;
+    forbidPersistence: boolean;
+    isCurrent: () => boolean;
+}
+type RequestInit = {
+    headers: Headers;
+    credentials: RequestCredentials;
+    signal?: AbortSignal;
+    redirect?: RequestRedirect;
+};
 /** 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 readonly options;
+    private warned;
+    constructor(store?: LocalForage, enabled?: () => boolean, options?: () => CacheOptions);
+    private maximumEntryBytes;
+    private withinLimit;
+    private diagnose;
+    load(url: string, init: RequestInit): Promise<ArrayBuffer>;
+    loadWithMetadata(url: string, init: RequestInit): Promise<ModelBufferResult>;
+    private loadBytes;
     private key;
     private mutate;
     clear(): Promise<void>;
 }
+export {};

package/types/Cache/ParsedModelCache.d.ts

@@ -0,0 +1,81 @@
+import { ModelBufferResult } from './ModelBufferCache';
+import { ParsedModelSnapshot } from './ParsedModelCodec';
+import { ParsedCacheLimits, ParsedCacheMetadata, ParsedCacheStore } from './ParsedModelStore';
+import { ParsedModelCacheDiagnostic } from '../Interface/modelCache';
+export interface ParsedModelCacheOptions {
+    enabled?: boolean;
+    maxBytes?: number;
+    maxEntryBytes?: number;
+    maxEntries?: number;
+    onDiagnostic?: (event: ParsedModelCacheDiagnostic) => void;
+}
+export interface ParsedCacheIdentity {
+    key: string;
+    rootKey: string;
+    version: string;
+}
+interface RootState {
+    latest: symbol;
+    refs: number;
+}
+interface Coordinator {
+    epoch: number;
+    roots: Map<string, RootState>;
+    scopes: Set<ParsedCacheScope>;
+    limitsKey?: string;
+    pruning?: Promise<unknown>;
+}
+export declare class ParsedCacheScope {
+    private coordinator;
+    private root;
+    private identity;
+    private release;
+    readonly controller: AbortController;
+    readonly token: symbol;
+    readonly epoch: number;
+    storageEpoch?: number;
+    sourceCurrent: () => boolean;
+    entry?: ParsedCacheMetadata;
+    private finished;
+    private parentAbort;
+    constructor(coordinator: Coordinator, root: RootState, identity: string, release: () => void, parent?: AbortSignal);
+    get signal(): AbortSignal;
+    isCurrent(): boolean;
+    assertCurrent(): void;
+    invalidate(): void;
+    finish(): void;
+}
+/** Coordinates live requests; the storage adapter owns atomic byte/count/LRU limits. */
+export declare class ParsedModelCache {
+    private options;
+    private store;
+    private coordinator;
+    private scopes;
+    private warned;
+    private disposed;
+    readonly stats: {
+        hits: number;
+        misses: number;
+        writes: number;
+        evictions: number;
+        errors: number;
+        skipped: number;
+        bytes: number;
+        entries: number;
+    };
+    constructor(options?: () => ParsedModelCacheOptions, store?: ParsedCacheStore);
+    get limits(): ParsedCacheLimits;
+    get enabled(): boolean;
+    begin(identity: string, parent?: AbortSignal): ParsedCacheScope;
+    private diagnostic;
+    private enforceLimits;
+    identify(scope: ParsedCacheScope, source: ModelBufferResult, profile: string): Promise<ParsedCacheIdentity | null>;
+    assertAvailable(scope: ParsedCacheScope, bytes: number): void;
+    read(scope: ParsedCacheScope, identity: ParsedCacheIdentity): Promise<ParsedModelSnapshot | null>;
+    discard(scope: ParsedCacheScope, identity: ParsedCacheIdentity): Promise<void>;
+    write(scope: ParsedCacheScope, identity: ParsedCacheIdentity, snapshot: ParsedModelSnapshot): Promise<void>;
+    clear(): Promise<void>;
+    dispose(): void;
+}
+export declare const clearParsedModelCache: () => Promise<void>;
+export {};

package/types/Cache/ParsedModelCodec.d.ts

@@ -0,0 +1,102 @@
+import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { RegisteredPart } from '../Entity/ModelResources';
+import * as THREE from 'three';
+declare const arrays: {
+    Float32Array: Float32ArrayConstructor;
+    Float64Array: Float64ArrayConstructor;
+    Uint32Array: Uint32ArrayConstructor;
+    Uint16Array: Uint16ArrayConstructor;
+    Uint8Array: Uint8ArrayConstructor;
+    Uint8ClampedArray: Uint8ClampedArrayConstructor;
+    Int32Array: Int32ArrayConstructor;
+    Int16Array: Int16ArrayConstructor;
+    Int8Array: Int8ArrayConstructor;
+};
+declare const materialTypes: {
+    MeshBasicMaterial: typeof THREE.MeshBasicMaterial;
+    MeshStandardMaterial: typeof THREE.MeshStandardMaterial;
+    MeshPhysicalMaterial: typeof THREE.MeshPhysicalMaterial;
+};
+type MaterialType = keyof typeof materialTypes;
+interface AttributeData {
+    buffer: number;
+    type: keyof typeof arrays;
+    itemSize: number;
+    normalized: boolean;
+    name: string;
+    stride?: number;
+    offset?: number;
+    interleavedId?: number;
+    float16: boolean;
+    gpuType?: number;
+    usage: number;
+}
+interface GeometryData {
+    attributes: Record<string, number>;
+    index: number | null;
+    groups: {
+        start: number;
+        count: number;
+        materialIndex?: number;
+    }[];
+    drawRange: {
+        start: number;
+        count: number;
+    };
+    box: number[][] | null;
+    sphere: [number[], number] | null;
+}
+interface MaterialData {
+    type: MaterialType;
+    json: Record<string, any>;
+    colors: Record<string, number[]>;
+    vectors: Record<string, number[]>;
+    values: Record<string, number | boolean>;
+}
+interface TextureData {
+    json: Record<string, any>;
+    matrix: number[];
+    matrixAutoUpdate: boolean;
+}
+type PartData = Omit<RegisteredPart, 'geometry' | 'material' | 'matrix'> & {
+    geometry: number;
+    material: number;
+    matrix: number[];
+};
+export interface ParsedModelSnapshot {
+    schema: 2;
+    three: string;
+    bytes: number;
+    parts: PartData[];
+    buffers: Blob[];
+    attributes: AttributeData[];
+    geometries: GeometryData[];
+    materials: MaterialData[];
+    textures: TextureData[];
+    images: {
+        uuid: string;
+        blob: Blob;
+        width: number;
+        height: number;
+    }[];
+    bitmapOptions: ImageBitmapOptions;
+}
+export interface ParsedCodecOptions {
+    signal?: AbortSignal;
+    assertCurrent?: () => void;
+    maxBytes?: number;
+    decodeImage?: (blob: Blob, options: ImageBitmapOptions, signal: AbortSignal) => Promise<ImageBitmap>;
+}
+export interface HydratedParsedModel {
+    parts: RegisteredPart[];
+    /** Call only after ModelResources has retained every resource. */
+    transfer(): void;
+    dispose(): void;
+}
+/** Logical payload size, including a bounded JSON metadata estimate, not physical disk usage. */
+export declare function parsedSnapshotBytes(snapshot: ParsedModelSnapshot): number;
+/** No runtime objects or decoded pixels enter persistent storage. */
+export declare function packParsedModel(gltf: GLTF, parts: readonly RegisteredPart[], options?: ParsedCodecOptions): Promise<ParsedModelSnapshot | null>;
+export declare function validateParsedModel(value: unknown, maximum?: number): asserts value is ParsedModelSnapshot;
+export declare function hydrateParsedModel(snapshot: ParsedModelSnapshot, options?: ParsedCodecOptions): Promise<HydratedParsedModel>;
+export {};

package/types/Cache/ParsedModelStore.d.ts

@@ -0,0 +1,58 @@
+import { ParsedModelSnapshot } from './ParsedModelCodec';
+export interface ParsedCacheLimits {
+    maxBytes: number;
+    maxEntryBytes: number;
+    maxEntries: number;
+}
+export interface ParsedCacheMetadata {
+    key: string;
+    rootKey: string;
+    version: string;
+    bytes: number;
+    lastUsed: number;
+    writeId: string;
+}
+export interface ParsedCacheRead {
+    epoch: number;
+    entry?: {
+        metadata: ParsedCacheMetadata;
+        snapshot: ParsedModelSnapshot;
+    };
+}
+export interface ParsedCacheWrite {
+    stored: boolean;
+    evicted: number;
+    bytes: number;
+    entries: number;
+}
+export interface ParsedCacheStore {
+    read(key: string, version: string, signal?: AbortSignal): Promise<ParsedCacheRead>;
+    write(metadata: ParsedCacheMetadata, snapshot: ParsedModelSnapshot, epoch: number, limits: ParsedCacheLimits, guard: () => boolean, signal?: AbortSignal): Promise<ParsedCacheWrite>;
+    remove(key: string, writeId: string, guard: () => boolean): Promise<void>;
+    invalidateRoot(rootKey: string, guard: () => boolean): Promise<void>;
+    prune(limits: ParsedCacheLimits): Promise<ParsedCacheWrite>;
+    touch(metadata: ParsedCacheMetadata): void;
+    clear(): Promise<void>;
+    onClear(listener: () => void): () => void;
+}
+/** Payload and LRU metadata are committed/evicted in the same native transaction. */
+export declare class IndexedParsedModelStore implements ParsedCacheStore {
+    readonly name: string;
+    private database?;
+    private channel?;
+    private listeners;
+    private touches;
+    private touchTimer?;
+    constructor(name?: string);
+    private open;
+    private transaction;
+    read(key: string, version: string, signal?: AbortSignal): Promise<ParsedCacheRead>;
+    write(metadata: ParsedCacheMetadata, snapshot: ParsedModelSnapshot, epoch: number, limits: ParsedCacheLimits, guard: () => boolean, signal?: AbortSignal): Promise<ParsedCacheWrite>;
+    remove(key: string, writeId: string, guard: () => boolean): Promise<void>;
+    invalidateRoot(rootKey: string, guard: () => boolean): Promise<void>;
+    prune(limits: ParsedCacheLimits): Promise<ParsedCacheWrite>;
+    touch(metadata: ParsedCacheMetadata): void;
+    clear(): Promise<void>;
+    onClear(listener: () => void): () => void;
+}
+export declare const parsedModelStore: IndexedParsedModelStore;

package/types/Cache/parsed-cancellation.d.ts

@@ -0,0 +1,5 @@
+export declare function parsedAbortError(): DOMException;
+export declare function checkParsedSignal(signal?: AbortSignal): void;
+/** Races cancellation without leaving rejection handlers or abort listeners behind. */
+export declare function parsedAbortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function parsedParallel<T, R>(values: readonly T[], work: (value: T, index: number) => Promise<R>, check: () => void, concurrency?: number): Promise<R[]>;

package/types/Entity/ModelResources.d.ts

@@ -1,6 +1,7 @@
 import { BufferGeometry, Material, Matrix4, Texture } from 'three';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { ModelBufferCache } from '../Cache/ModelBufferCache';
+import { ParsedModelCacheOptions } from '../Cache/ParsedModelCache';
 export interface ModelPart {
     /** Omitted for triangle meshes. Basic line segments share the Entity lifecycle. */
     kind?: 'mesh' | 'line-segments';
@@ -29,6 +30,7 @@ interface ResourceRecord<T> {
     dead: boolean;
     gpu: Set<BufferGeometry | Material | Texture>;
     dependencies: Set<ResourceRecord<Material>>;
+    imageReleases: Set<() => void>;
 }
 export declare class ResourceLease<T> {
     readonly registry: ModelResources;
@@ -65,8 +67,12 @@ export declare class ModelResources {
     private urls;
     private gltfLoader;
     private bufferCache;
+    private parsedCacheOptions;
+    private parsedCache;
     /** Borrow a host-configured loader; its decoder workers remain host-owned. */
-    setGLTFLoader(loader: GLTFLoader, bufferCache?: ModelBufferCache): void;
+    setGLTFLoader(loader: GLTFLoader, bufferCache?: ModelBufferCache, parsedOptions?: () => ParsedModelCacheOptions & {
+        profile?: string;
+    }): void;
     readonly materials: {
         register: (material: Material, options: {
             ownership: "transfer";

package/types/Interface/index.d.ts

@@ -11,3 +11,4 @@ export * from './sbmCache';
 export * from './sbmXmlToJson';
 export * from './gmlToJson';
 export * from './poiMesh';
+export * from './modelCache';

package/types/Interface/modelCache.d.ts

@@ -0,0 +1,20 @@
+/** Cache diagnostics never contain resource URLs, headers or exception messages. */
+export interface ModelCacheDiagnostic {
+    key: string;
+    operation: 'read' | 'write' | 'skip';
+    reason: 'storage-error' | 'invalid-entry' | 'entry-too-large';
+    bytes?: number;
+    maxEntryBytes: number;
+    errorName?: string;
+}
+/** Parsed-cache evidence is bounded and contains no URLs, headers or exception text. */
+export interface ParsedModelCacheDiagnostic {
+    key: string;
+    operation: 'read' | 'write' | 'skip' | 'evict' | 'clear';
+    reason: 'storage-error' | 'invalid-entry' | 'entry-too-large' | 'capacity';
+    maxBytes: number;
+    maxEntryBytes: number;
+    maxEntries: number;
+    bytes?: number;
+    errorName?: string;
+}

package/types/Interface/signals.d.ts

@@ -6,6 +6,10 @@ interface SignalsState {
     backgroundChanged: Signal;
     beforeRender: Signal;
     sceneRendered: Signal;
+    /** Dispatches ModelCacheDiagnostic when persistent model caching fails or skips a size limit. */
+    modelCacheDiagnostic: Signal;
+    /** Dispatches redacted ParsedModelCacheDiagnostic for storage/capacity failures. */
+    parsedModelCacheDiagnostic: Signal;
     tweenUpdate: Signal;
     hover: Signal;
     click: Signal;

package/types/Interface/viewport.d.ts

@@ -102,6 +102,16 @@ interface ViewportOptions {
     closeInfoLog?: boolean;
     closeWarnLog?: boolean;
     useIndexedDB?: boolean;
+    /** Maximum bytes per persistent model resource; default 1 GiB, zero disables persistence. */
+    modelCacheMaxEntryBytes?: number;
+    /** Cache decoded static Entity model resources when useIndexedDB is enabled; default true. */
+    useParsedModelCache?: boolean;
+    /** Parsed cache logical total budget; default 512 MiB. Zero disables and trims this cache. */
+    parsedModelCacheMaxBytes?: number;
+    /** Maximum logical parsed resource size; default 256 MiB. */
+    parsedModelCacheMaxEntryBytes?: number;
+    /** Maximum persistent parsed resources; default 256. */
+    parsedModelCacheMaxEntries?: number;
 }
 interface ViewportState {
     useFreq: number;

package/types/Loader/ParsedLoaderPolicy.d.ts

@@ -0,0 +1,6 @@
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+/** Called during SDK construction, before host code can customize its loader. */
+export declare function parsedLoaderPolicy(loader: GLTFLoader): {
+    eligible: () => boolean;
+    profile: () => string;
+};

package/types/Loader/TexturePreloader.d.ts

@@ -36,6 +36,7 @@ export declare class TexturePreloader {
     private onContextRestored;
     private cancelFrame;
     prepare(root: Object3D, signal?: AbortSignal, managerSignal?: AbortSignal): Promise<void>;
+    prepareMaterials(materials: Iterable<unknown>, signal?: AbortSignal, managerSignal?: AbortSignal): Promise<void>;
     private schedule;
     private pump;
     private cancel;

package/types/index.d.ts

@@ -1142,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 {
@@ -3527,18 +3532,39 @@ export declare interface ModelAnimationFindFunc {
 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 readonly options;
+    private warned;
+    constructor(store?: LocalForage, enabled?: () => boolean, options?: () => CacheOptions);
+    private maximumEntryBytes;
+    private withinLimit;
+    private diagnose;
+    load(url: string, init: RequestInit_2): Promise<ArrayBuffer>;
+    loadWithMetadata(url: string, init: RequestInit_2): Promise<ModelBufferResult>;
+    private loadBytes;
     private key;
     private mutate;
     clear(): Promise<void>;
 }
 
+declare interface ModelBufferResult {
+    buffer: ArrayBuffer;
+    /** Hashed request identity; never a URL or credential. */
+    cacheKey: string | null;
+    cacheable: boolean;
+    forbidPersistence: boolean;
+    isCurrent: () => boolean;
+}
+
+/** 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;
@@ -3708,8 +3734,12 @@ export declare class ModelResources {
     private urls;
     private gltfLoader;
     private bufferCache;
+    private parsedCacheOptions;
+    private parsedCache;
     /** Borrow a host-configured loader; its decoder workers remain host-owned. */
-    setGLTFLoader(loader: GLTFLoader, bufferCache?: ModelBufferCache): void;
+    setGLTFLoader(loader: GLTFLoader, bufferCache?: ModelBufferCache, parsedOptions?: () => ParsedModelCacheOptions & {
+        profile?: string;
+    }): void;
     readonly materials: {
         register: (material: Material, options: {
             ownership: "transfer";
@@ -3853,6 +3883,26 @@ export declare type OrbitControlsProperties = Required<Omit<OrbitControlsOptions
 
 export declare type OrbitControlsType = 'orbit';
 
+/** Parsed-cache evidence is bounded and contains no URLs, headers or exception text. */
+export declare interface ParsedModelCacheDiagnostic {
+    key: string;
+    operation: 'read' | 'write' | 'skip' | 'evict' | 'clear';
+    reason: 'storage-error' | 'invalid-entry' | 'entry-too-large' | 'capacity';
+    maxBytes: number;
+    maxEntryBytes: number;
+    maxEntries: number;
+    bytes?: number;
+    errorName?: string;
+}
+
+declare interface ParsedModelCacheOptions {
+    enabled?: boolean;
+    maxBytes?: number;
+    maxEntryBytes?: number;
+    maxEntries?: number;
+    onDiagnostic?: (event: ParsedModelCacheDiagnostic) => void;
+}
+
 declare const parseFilePath: (url: string) => string;
 
 /**
@@ -4270,6 +4320,13 @@ export declare function renderLoop(frameFun: (time: DOMHighResTimeStamp) => void
 /** Default headers for SDK-owned HTTP(S) resource requests. */
 export declare const RequestHeaders: Record<string, string>;
 
+declare type RequestInit_2 = {
+    headers: Headers;
+    credentials: RequestCredentials;
+    signal?: AbortSignal;
+    redirect?: RequestRedirect;
+};
+
 export declare class ResourceLease<T> {
     readonly registry: ModelResources;
     private record;
@@ -4288,6 +4345,7 @@ declare interface ResourceRecord<T> {
     dead: boolean;
     gpu: Set<BufferGeometry | Material | Texture>;
     dependencies: Set<ResourceRecord<Material>>;
+    imageReleases: Set<() => void>;
 }
 
 declare const rgbeLoader: HDRLoader;
@@ -4576,6 +4634,10 @@ export declare interface SignalsState {
     backgroundChanged: Signal;
     beforeRender: Signal;
     sceneRendered: Signal;
+    /** Dispatches ModelCacheDiagnostic when persistent model caching fails or skips a size limit. */
+    modelCacheDiagnostic: Signal;
+    /** Dispatches redacted ParsedModelCacheDiagnostic for storage/capacity failures. */
+    parsedModelCacheDiagnostic: Signal;
     tweenUpdate: Signal;
     hover: Signal;
     click: Signal;
@@ -6828,6 +6890,16 @@ export declare interface ViewportOptions {
     closeInfoLog?: boolean;
     closeWarnLog?: boolean;
     useIndexedDB?: boolean;
+    /** Maximum bytes per persistent model resource; default 1 GiB, zero disables persistence. */
+    modelCacheMaxEntryBytes?: number;
+    /** Cache decoded static Entity model resources when useIndexedDB is enabled; default true. */
+    useParsedModelCache?: boolean;
+    /** Parsed cache logical total budget; default 512 MiB. Zero disables and trims this cache. */
+    parsedModelCacheMaxBytes?: number;
+    /** Maximum logical parsed resource size; default 256 MiB. */
+    parsedModelCacheMaxEntryBytes?: number;
+    /** Maximum persistent parsed resources; default 256. */
+    parsedModelCacheMaxEntries?: number;
 }
 
 export declare interface ViewportState {