soonspacejs 3.0.0-alpha.10 → 3.0.0-alpha.11

package/package.json

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

package/types/Cache/ModelBufferCache.d.ts

@@ -1,8 +1,18 @@
+import { ModelCacheDiagnostic } from '../Interface/modelCache';
+interface CacheOptions {
+    maxEntryBytes?: number;
+    onDiagnostic?: (event: ModelCacheDiagnostic) => void;
+}
 /** 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);
+    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;
@@ -13,3 +23,4 @@ export declare class ModelBufferCache {
     private mutate;
     clear(): Promise<void>;
 }
+export {};

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,9 @@
+/** 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;
+}

package/types/Interface/signals.d.ts

@@ -6,6 +6,8 @@ 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;

package/types/Interface/viewport.d.ts

@@ -102,6 +102,8 @@ interface ViewportOptions {
     closeInfoLog?: boolean;
     closeWarnLog?: boolean;
     useIndexedDB?: boolean;
+    /** Maximum bytes per persistent model resource; default 1 GiB, zero disables persistence. */
+    modelCacheMaxEntryBytes?: number;
 }
 interface ViewportState {
     useFreq: number;

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,7 +3532,12 @@ export declare interface ModelAnimationFindFunc {
 declare class ModelBufferCache {
     private readonly store;
     private readonly enabled;
-    constructor(store?: LocalForage, enabled?: () => boolean);
+    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;
@@ -3539,6 +3549,16 @@ declare class ModelBufferCache {
     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;
@@ -4576,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;
@@ -6828,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 {