rayzee 9.0.0 → 9.1.0

package/src/Storage/StorageOps.js

@@ -0,0 +1,137 @@
+/**
+ * The write side of storage, run where sync access handles exist: inside StorageWorker, or
+ * inline when the caller is itself a worker (or a test with a fake root).
+ */
+export class StorageOps {
+
+	constructor( root ) {
+
+		this._root = root;
+		this._writers = new Map();
+		this._nextId = 1;
+
+	}
+
+	async _dir( path, create ) {
+
+		let dir = await this._root;
+		for ( const part of path ) dir = await dir.getDirectoryHandle( part, { create } );
+		return dir;
+
+	}
+
+	async openWriter( { path, name, truncate = true, length } ) {
+
+		const dir = await this._dir( path, true );
+		const handle = await ( await dir.getFileHandle( name, { create: true } ) ).createSyncAccessHandle();
+		if ( truncate ) handle.truncate( 0 );
+		else if ( length !== undefined && handle.getSize() > length ) handle.truncate( length );
+		const id = this._nextId ++;
+		this._writers.set( id, { handle, end: handle.getSize() } );
+		return { id };
+
+	}
+
+	write( { id, buffer, byteOffset = 0, byteLength, at } ) {
+
+		const writer = this._writers.get( id );
+		if ( ! writer ) throw new Error( `storage: writer ${id} is not open` );
+
+		const view = new Uint8Array( buffer, byteOffset, byteLength ?? buffer.byteLength - byteOffset );
+		const position = at ?? writer.end;
+		let written = 0;
+		while ( written < view.length ) {
+
+			const n = writer.handle.write( view.subarray( written ), { at: position + written } );
+			if ( n <= 0 ) throw new Error( 'storage: write made no progress' );
+			written += n;
+
+		}
+
+		writer.end = Math.max( writer.end, position + view.length );
+		return { bytes: view.length };
+
+	}
+
+	closeWriter( { id, abort = false } ) {
+
+		const writer = this._writers.get( id );
+		if ( ! writer ) return { size: 0 };
+		this._writers.delete( id );
+
+		try {
+
+			if ( ! abort ) writer.handle.flush();
+			return { size: writer.handle.getSize() };
+
+		} finally {
+
+			writer.handle.close();
+
+		}
+
+	}
+
+	async writeFile( { path, name, buffer, byteOffset = 0, byteLength } ) {
+
+		const { id } = await this.openWriter( { path, name } );
+		try {
+
+			this.write( { id, buffer, byteOffset, byteLength } );
+			return this.closeWriter( { id } );
+
+		} catch ( error ) {
+
+			this.closeWriter( { id, abort: true } );
+			throw error;
+
+		}
+
+	}
+
+	async readRange( { path, name, offset = 0, length } ) {
+
+		const fileHandle = await ( await this._dir( path, false ) ).getFileHandle( name );
+
+		let handle = null;
+		try {
+
+			handle = await fileHandle.createSyncAccessHandle();
+
+		} catch ( error ) {
+
+			if ( error.name !== 'NoModificationAllowedError' ) throw error;
+
+		}
+
+		if ( ! handle ) {
+
+			const file = await fileHandle.getFile();
+			const end = length === undefined ? file.size : offset + length;
+			return { buffer: await file.slice( offset, end ).arrayBuffer() };
+
+		}
+
+		try {
+
+			const size = handle.getSize();
+			const n = Math.max( 0, Math.min( length ?? size - offset, size - offset ) );
+			const buffer = new ArrayBuffer( n );
+			handle.read( buffer, { at: offset } );
+			return { buffer };
+
+		} finally {
+
+			handle.close();
+
+		}
+
+	}
+
+	dispose() {
+
+		for ( const id of [ ...this._writers.keys() ] ) this.closeWriter( { id, abort: true } );
+
+	}
+
+}

package/src/Storage/StorageWorker.js

@@ -0,0 +1,37 @@
+import { StorageOps } from './StorageOps.js';
+
+let ops = null;
+
+async function rootFor( namespace, root ) {
+
+	if ( root ) return root;
+	const top = await navigator.storage.getDirectory();
+	return top.getDirectoryHandle( namespace, { create: true } );
+
+}
+
+self.onmessage = async ( { data } ) => {
+
+	const { id, op, args } = data;
+
+	try {
+
+		if ( op === 'init' ) {
+
+			ops = new StorageOps( rootFor( args.namespace, args.root ) );
+			postMessage( { id, result: {} } );
+			return;
+
+		}
+
+		const result = await ops[ op ]( args );
+		const transfer = result?.buffer instanceof ArrayBuffer ? [ result.buffer ] : [];
+		postMessage( { id, result }, transfer );
+
+	} catch ( error ) {
+
+		postMessage( { id, error: { name: error.name, message: error.message } } );
+
+	}
+
+};

package/src/Storage/events.js

@@ -0,0 +1,29 @@
+/** Minimal addEventListener/dispatchEvent, so the storage core runs in workers without three.js. */
+export class Emitter {
+
+	constructor() {
+
+		this._handlers = new Map();
+
+	}
+
+	addEventListener( type, handler ) {
+
+		if ( ! this._handlers.has( type ) ) this._handlers.set( type, new Set() );
+		this._handlers.get( type ).add( handler );
+
+	}
+
+	removeEventListener( type, handler ) {
+
+		this._handlers.get( type )?.delete( handler );
+
+	}
+
+	dispatchEvent( event ) {
+
+		for ( const handler of [ ...( this._handlers.get( event.type ) ?? [] ) ] ) handler.call( this, event );
+
+	}
+
+}

package/src/Storage/identity.js

@@ -0,0 +1,77 @@
+const encoder = new TextEncoder();
+
+const HEAD_BYTES = 1 << 20;
+const TAIL_BYTES = 1 << 20;
+const PROBE_BYTES = 64 << 10;
+const PROBES = 14;
+
+function hex( bytes ) {
+
+	let out = '';
+	for ( const b of bytes ) out += b.toString( 16 ).padStart( 2, '0' );
+	return out;
+
+}
+
+export async function sha256Hex( data ) {
+
+	const bytes = typeof data === 'string' ? encoder.encode( data ) : data;
+	return hex( new Uint8Array( await crypto.subtle.digest( 'SHA-256', bytes ) ) );
+
+}
+
+export async function entryIdFor( key ) {
+
+	return ( await sha256Hex( key ) ).slice( 0, 32 );
+
+}
+
+/**
+ * SHA-256 over the head, tail and 14 evenly spaced probes of a Blob — ~3 MB read whatever its
+ * size. WebCrypto cannot stream, so a full hash of a multi-GB file would need it all in memory.
+ */
+export async function sampleHash( blob ) {
+
+	if ( blob.size <= HEAD_BYTES + TAIL_BYTES + PROBES * PROBE_BYTES ) {
+
+		return sha256Hex( new Uint8Array( await blob.arrayBuffer() ) );
+
+	}
+
+	const parts = [ blob.slice( 0, HEAD_BYTES ) ];
+	const span = blob.size - HEAD_BYTES - TAIL_BYTES - PROBE_BYTES;
+	for ( let i = 0; i < PROBES; i ++ ) {
+
+		const at = HEAD_BYTES + Math.floor( span * ( i + 0.5 ) / PROBES );
+		parts.push( blob.slice( at, at + PROBE_BYTES ) );
+
+	}
+
+	parts.push( blob.slice( blob.size - TAIL_BYTES ) );
+	return sha256Hex( new Uint8Array( await new Blob( parts ).arrayBuffer() ) );
+
+}
+
+/** @returns {Promise<{name: string, size: number, lastModified: number, sample: string}>} */
+export async function fileIdentity( file ) {
+
+	return {
+		name: file.name ?? '',
+		size: file.size,
+		lastModified: file.lastModified ?? 0,
+		sample: await sampleHash( file ),
+	};
+
+}
+
+export function identityKey( identity ) {
+
+	return `file:${identity.name}|${identity.size}|${identity.lastModified}|${identity.sample}`;
+
+}
+
+export function sameIdentity( a, b ) {
+
+	return !! a && !! b && a.size === b.size && a.sample === b.sample && a.name === b.name;
+
+}

package/src/Storage/index.js

@@ -0,0 +1,9 @@
+export {
+	StorageManager, StorageArea, StorageEntry, EntryWriter, STORAGE_KIND, ENGINE_AREAS, openInlineStorage,
+} from './StorageManager.js';
+export { openStorage, acquireSharedStorage } from './openStorage.js';
+export { sharedStorage } from './shared.js';
+export { fileIdentity, identityKey, sameIdentity, sampleHash, sha256Hex } from './identity.js';
+export { DownloadCache, DOWNLOAD_POLICY, fetchFile, nameFromUrl, cachedObjectURL, sharedDownloads } from './DownloadCache.js';
+export { acquireLock, heldLockNames } from './locks.js';
+export { SpillStore } from './SpillStore.js';

package/src/Storage/inlineTransport.js

@@ -0,0 +1,24 @@
+import { StorageOps } from './StorageOps.js';
+
+/** Writes on this thread through sync access handles: a worker's own storage, or tests with a fake root. */
+export class InlineTransport {
+
+	constructor( root ) {
+
+		this._ops = new StorageOps( root );
+
+	}
+
+	async call( op, args ) {
+
+		return this._ops[ op ]( args );
+
+	}
+
+	dispose() {
+
+		this._ops.dispose();
+
+	}
+
+}

package/src/Storage/locks.js

@@ -0,0 +1,99 @@
+const local = new Map();
+
+function tryGrant( state, mode ) {
+
+	if ( state.exclusive ) return false;
+	if ( mode === 'exclusive' && state.shared > 0 ) return false;
+	if ( mode === 'exclusive' ) state.exclusive = true;
+	else state.shared ++;
+	return true;
+
+}
+
+function localAcquire( name, mode, ifAvailable ) {
+
+	let state = local.get( name );
+	if ( ! state ) {
+
+		state = { shared: 0, exclusive: false, queue: [] };
+		local.set( name, state );
+
+	}
+
+	const release = once( () => {
+
+		if ( mode === 'exclusive' ) state.exclusive = false;
+		else state.shared --;
+
+		while ( state.queue.length && tryGrant( state, state.queue[ 0 ].mode ) ) state.queue.shift().grant();
+		if ( ! state.exclusive && state.shared === 0 && state.queue.length === 0 ) local.delete( name );
+
+	} );
+
+	if ( state.queue.length === 0 && tryGrant( state, mode ) ) return Promise.resolve( release );
+
+	if ( ifAvailable ) {
+
+		if ( ! state.exclusive && state.shared === 0 && state.queue.length === 0 ) local.delete( name );
+		return Promise.resolve( null );
+
+	}
+
+	return new Promise( ( resolve ) => state.queue.push( { mode, grant: () => resolve( release ) } ) );
+
+}
+
+function once( fn ) {
+
+	let done = false;
+	return () => {
+
+		if ( done ) return;
+		done = true;
+		fn();
+
+	};
+
+}
+
+const webLocks = () => ( typeof navigator !== 'undefined' && navigator.locks?.request ? navigator.locks : null );
+
+/**
+ * Holds a Web Lock until the returned function is called; resolves null when `ifAvailable` and taken.
+ * Falls back to an in-process lock where Web Locks are missing (Node).
+ * @returns {Promise<?function(): void>}
+ */
+export function acquireLock( name, { mode = 'exclusive', ifAvailable = false } = {} ) {
+
+	const locks = webLocks();
+	if ( ! locks ) return localAcquire( name, mode, ifAvailable );
+
+	return new Promise( ( resolve, reject ) => {
+
+		locks.request( name, { mode, ifAvailable }, ( lock ) => {
+
+			if ( ! lock ) {
+
+				resolve( null );
+				return undefined;
+
+			}
+
+			return new Promise( ( done ) => resolve( once( done ) ) );
+
+		} ).catch( reject );
+
+	} );
+
+}
+
+/** @returns {Promise<Set<string>>} names of locks currently held by any tab of this origin */
+export async function heldLockNames() {
+
+	const locks = webLocks();
+	if ( ! locks ) return new Set( local.keys() );
+
+	const { held = [] } = await locks.query();
+	return new Set( held.map( ( lock ) => lock.name ) );
+
+}

package/src/Storage/openStorage.js

@@ -0,0 +1,87 @@
+import { StorageManager, openInlineStorage } from './StorageManager.js';
+import { WorkerTransport, inWorkerContext } from './transport.js';
+import { sharedByNamespace } from './shared.js';
+
+async function namespaceRoot( namespace ) {
+
+	const storage = typeof navigator !== 'undefined' ? navigator.storage : null;
+	if ( ! storage?.getDirectory ) return { root: null, reason: 'this browser has no origin private file system' };
+
+	try {
+
+		const top = await storage.getDirectory();
+		return { root: await top.getDirectoryHandle( namespace, { create: true } ) };
+
+	} catch ( error ) {
+
+		return { root: null, reason: `${error.name}: ${error.message}` };
+
+	}
+
+}
+
+/**
+ * Opens storage for a namespace (`cacheNamespace`). Resolves `{ storage: null, reason }` where the
+ * browser offers none — private windows, old browsers, Node without a fake.
+ * @param {Object} [options]
+ * @param {string} options.namespace
+ * @param {FileSystemDirectoryHandle} [options.root] - use this directory instead of the OPFS one
+ * @param {'auto'|'inline'|'worker'} [options.transport] - 'inline' writes on this thread (needs sync handles here)
+ * @returns {Promise<{storage: ?StorageManager, reason?: string}>}
+ */
+export async function openStorage( { namespace, root = null, transport = 'auto' } = {} ) {
+
+	const resolved = root ? { root } : await namespaceRoot( namespace );
+	if ( ! resolved.root ) return { storage: null, reason: resolved.reason };
+
+	const inline = transport === 'inline' || ( transport === 'auto' && ( inWorkerContext() || typeof Worker === 'undefined' ) );
+	if ( inline ) return { storage: openInlineStorage( { namespace, root: resolved.root } ) };
+
+	const channel = new WorkerTransport( { namespace, root } );
+	const storage = new StorageManager( { root: resolved.root, transport: channel, namespace } );
+	storage.sweep().catch( () => {} );
+	return { storage };
+
+}
+
+/**
+ * One manager per namespace per page, shared by every app on it; the last `release()` disposes it.
+ * @returns {Promise<{storage: ?StorageManager, reason?: string, release: function(): void}>}
+ */
+export async function acquireSharedStorage( namespace ) {
+
+	let slot = sharedByNamespace.get( namespace );
+	if ( ! slot ) {
+
+		slot = { refs: 0, opened: openStorage( { namespace } ) };
+		sharedByNamespace.set( namespace, slot );
+
+	}
+
+	slot.refs ++;
+	const { storage, reason } = await slot.opened;
+	slot.storage = storage;
+
+	let released = false;
+	const release = () => {
+
+		if ( released ) return;
+		released = true;
+		slot.refs --;
+		if ( slot.refs > 0 ) return;
+		if ( sharedByNamespace.get( namespace ) === slot ) sharedByNamespace.delete( namespace );
+		storage?.dispose();
+
+	};
+
+	if ( ! storage ) {
+
+		release();
+		return { storage: null, reason, release: () => {} };
+
+	}
+
+	return { storage, release };
+
+}
+

package/src/Storage/sceneCachePolicy.js

@@ -0,0 +1,12 @@
+/** A scene is stored only when rebuilding it took at least this long (decision D6). */
+export const SCENE_CACHE_MIN_BUILD_MS = 10_000;
+
+// File.slice reads measured 1.7–2.2 GB/s in Chrome (phase 0); kept conservative.
+const READ_BYTES_PER_MS = 1.5e6;
+
+/** Worth storing: the build was slow, and reading it back would take under a third as long. */
+export function worthStoring( buildMs, bytes, minBuildMs = SCENE_CACHE_MIN_BUILD_MS ) {
+
+	return buildMs >= minBuildMs && bytes / READ_BYTES_PER_MS < buildMs / 3;
+
+}

package/src/Storage/shared.js

@@ -0,0 +1,9 @@
+/** Per-namespace managers opened on this page, shared by every app on it. */
+export const sharedByNamespace = new Map();
+
+/** The storage an app on this page opened for `namespace`, or null — for code that holds no app. */
+export function sharedStorage( namespace ) {
+
+	return sharedByNamespace.get( namespace )?.storage ?? null;
+
+}

package/src/Storage/transport.js

@@ -0,0 +1,62 @@
+import StorageWorker from './StorageWorker.js?worker&inline';
+
+function toError( { name, message } ) {
+
+	const error = new Error( message );
+	error.name = name;
+	return error;
+
+}
+
+export class WorkerTransport {
+
+	constructor( { namespace, root = null } ) {
+
+		this._worker = new StorageWorker();
+		this._pending = new Map();
+		this._nextId = 0;
+
+		this._worker.onmessage = ( { data } ) => {
+
+			const request = this._pending.get( data.id );
+			if ( ! request ) return;
+			this._pending.delete( data.id );
+			if ( data.error ) request.reject( toError( data.error ) );
+			else request.resolve( data.result );
+
+		};
+
+		this._ready = this.call( 'init', { namespace, root } );
+
+	}
+
+	call( op, args, transfer = [] ) {
+
+		if ( ! this._worker ) return Promise.reject( new Error( 'storage: transport disposed' ) );
+
+		return new Promise( ( resolve, reject ) => {
+
+			const id = this._nextId ++;
+			this._pending.set( id, { resolve, reject } );
+			this._worker.postMessage( { id, op, args }, transfer );
+
+		} );
+
+	}
+
+	dispose() {
+
+		this._worker?.terminate();
+		this._worker = null;
+		for ( const { reject } of this._pending.values() ) reject( new Error( 'storage: transport disposed' ) );
+		this._pending.clear();
+
+	}
+
+}
+
+export function inWorkerContext() {
+
+	return typeof WorkerGlobalScope !== 'undefined' && globalThis instanceof WorkerGlobalScope; // eslint-disable-line no-undef
+
+}