@peter.prib/renderengine 0.2.5 → 0.2.7

package/src/workspace/storage/BackupFolder.js

@@ -0,0 +1,145 @@
+/**
+ * BackupFolder — where backups go: a folder chosen once (the File System
+ * Access API, in Chrome and Edge, from file:// too) and remembered (its handle
+ * in a KeyValueStore), else the browser's download folder. Choose a folder that
+ * OneDrive, Google Drive or Dropbox syncs and the backups reach the cloud with
+ * no sign-in in the page. After au-accounts-app's backups.
+ *
+ * Each backup is written twice: stamped with the date and time to the second
+ * (`name-20261015-093012.ext`), so they gather as a history and none is
+ * overwritten, and (unless `keepUnstamped` is off) under its plain name,
+ * refreshed each time, for anything that expects one fixed name. Permission to
+ * write is checked at the time of writing, the only moment a browser grants it;
+ * refused, or failing, the backup goes to downloads instead. A short log says
+ * when each was taken and where it went.
+ */
+export class BackupFolder {
+    static HANDLE_KEY = 'backup:folder';
+    static LOG_KEY = 'backup:log';
+    static LOG_MAX = 20;
+    static DOWNLOADS = 'browser download folder';
+
+    /**
+     * @param {Object} options
+     * @param {KeyValueStore} options.store - Remembers the folder and the log
+     * @param {Window} [options.window] - For showDirectoryPicker
+     * @param {(name: string, data: string|Uint8Array, mimeType: string) => void} options.download - The fallback
+     * @param {boolean} [options.keepUnstamped] - Also write each under its plain name
+     */
+    constructor({ store, window: win = globalThis, download, keepUnstamped = true }) {
+        this.store = store;
+        this.win = win;
+        this.download = download;
+        this.keepUnstamped = keepUnstamped;
+        /** The chosen folder (a FileSystemDirectoryHandle), or null. */
+        this.dir = null;
+    }
+
+    /** Whether this browser lets a page write to a folder it chooses. */
+    get supported() {
+        return typeof this.win?.showDirectoryPicker === 'function';
+    }
+
+    /** Where backups go now, as precisely as a page can say (a folder's name, never its path). */
+    get location() {
+        return this.dir ? `folder "${this.dir.name}"` : BackupFolder.DOWNLOADS;
+    }
+
+    /** The folder chosen in an earlier session, if the store kept it. */
+    async restore() {
+        if (!this.supported) return null;
+        try {
+            const handle = await this.store.get(BackupFolder.HANDLE_KEY);
+            if (handle?.kind === 'directory') this.dir = handle;
+        } catch { /* a handle this browser will not read back: downloads still work */ }
+        return this.dir;
+    }
+
+    /** Ask for a folder (a user's click); resolves to it, or null when cancelled or unsupported. */
+    async choose() {
+        if (!this.supported) return null;
+        try {
+            this.dir = await this.win.showDirectoryPicker({ id: 'renderengine-backups', mode: 'readwrite' });
+        } catch (err) {
+            if (err?.name === 'AbortError') return null;
+            throw err;
+        }
+        try { await this.store.set(BackupFolder.HANDLE_KEY, this.dir); } catch { /* chosen for this page only */ }
+        return this.dir;
+    }
+
+    /** Back up to downloads from now on. */
+    async forget() {
+        this.dir = null;
+        await this.store.delete(BackupFolder.HANDLE_KEY);
+    }
+
+    /** `name.ext` stamped with the date and time to the second: `name-20261015-093012.ext`. */
+    static stamped(fileName, at = new Date()) {
+        const two = (n) => String(n).padStart(2, '0');
+        const stamp = `${at.getFullYear()}${two(at.getMonth() + 1)}${two(at.getDate())}-${two(at.getHours())}${two(at.getMinutes())}${two(at.getSeconds())}`;
+        const dot = fileName.lastIndexOf('.');
+        return dot > 0 ? `${fileName.slice(0, dot)}-${stamp}${fileName.slice(dot)}` : `${fileName}-${stamp}`;
+    }
+
+    /** Whether the folder may be written now (asking, which needs a user's click). @private */
+    async _writable() {
+        if (!this.dir) return false;
+        try {
+            const opts = { mode: 'readwrite' };
+            if (await this.dir.queryPermission?.(opts) === 'granted') return true;
+            return await this.dir.requestPermission?.(opts) === 'granted';
+        } catch { return false; }
+    }
+
+    /** @private */
+    async _write(name, data) {
+        const file = await this.dir.getFileHandle(name, { create: true });
+        const writable = await file.createWritable();
+        await writable.write(data);
+        await writable.close();
+    }
+
+    /**
+     * Back up some files: into the folder (stamped, and plain), else to downloads
+     * (stamped). Resolves to where they went and their names; the log records it.
+     * @param {Array<{name: string, data: string|Uint8Array, mimeType?: string}>} files
+     * @param {Date} [at]
+     * @returns {Promise<{location: string, names: string[]}>}
+     */
+    async backUp(files, at = new Date()) {
+        const names = files.map(f => BackupFolder.stamped(f.name, at));
+        let location = BackupFolder.DOWNLOADS;
+        if (this.dir && await this._writable()) {
+            try {
+                for (const [i, f] of files.entries()) {
+                    await this._write(names[i], f.data);
+                    if (this.keepUnstamped) { try { await this._write(f.name, f.data); } catch { /* the stamped one is written */ } }
+                }
+                location = this.location;
+            } catch { location = BackupFolder.DOWNLOADS; }
+        }
+        if (location === BackupFolder.DOWNLOADS) {
+            files.forEach((f, i) => this.download(names[i], f.data, f.mimeType ?? 'application/octet-stream'));
+        }
+        await this._log({ at: at.toISOString(), location, names, bytes: files.reduce((n, f) => n + (f.data?.length ?? 0), 0) });
+        return { location, names };
+    }
+
+    /** The backups taken, newest first. */
+    async log() {
+        return (await this.store.get(BackupFolder.LOG_KEY)) ?? [];
+    }
+
+    /** Days since the last backup, or null when there has been none. */
+    async daysSinceLast(now = new Date()) {
+        const [last] = await this.log();
+        return last ? (now - new Date(last.at)) / 86400000 : null;
+    }
+
+    /** @private */
+    async _log(record) {
+        const log = [record, ...(await this.log())].slice(0, BackupFolder.LOG_MAX);
+        await this.store.set(BackupFolder.LOG_KEY, log);
+    }
+}

package/src/workspace/storage/KeyValueStore.js

@@ -0,0 +1,92 @@
+/**
+ * KeyValueStore — values kept by key, asynchronously, that outlive the page:
+ * the base of where the workbench keeps models and remembers its backup
+ * folder. `IndexedDbStore` keeps them in the browser (any structured-clone
+ * value: text, bytes, a folder handle); `MemoryStore` for tests and for a
+ * browser that has no storage (a private window), where nothing outlives
+ * the page.
+ */
+export class KeyValueStore {
+    constructor() {
+        if (new.target === KeyValueStore) throw new TypeError('KeyValueStore is abstract — subclass it');
+    }
+
+    /** The value under `key`, or undefined. @abstract */
+    async get(key) { throw new Error(`${this.constructor.name} must implement get()`); }
+
+    /** Keep `value` under `key`. @abstract */
+    async set(key, value) { throw new Error(`${this.constructor.name} must implement set()`); }
+
+    /** Forget `key`. @abstract */
+    async delete(key) { throw new Error(`${this.constructor.name} must implement delete()`); }
+
+    /** Every key (that starts with `prefix`). @abstract */
+    async keys(prefix = '') { throw new Error(`${this.constructor.name} must implement keys()`); }
+
+    /** Whether values outlive the page. */
+    get lasting() { return true; }
+}
+
+/** Values in memory only: gone with the page. */
+export class MemoryStore extends KeyValueStore {
+    constructor() {
+        super();
+        this.values = new Map();
+    }
+
+    async get(key) { return this.values.get(key); }
+    async set(key, value) { this.values.set(key, value); }
+    async delete(key) { this.values.delete(key); }
+    async keys(prefix = '') { return [...this.values.keys()].filter(k => k.startsWith(prefix)); }
+    get lasting() { return false; }
+}
+
+/**
+ * Values in the browser's IndexedDB: one database, one object store, keyed by
+ * string. Far larger than localStorage allows, and it keeps bytes and file
+ * handles as they are. `IndexedDbStore.open(name)` falls back to a MemoryStore
+ * where the browser has no IndexedDB (or refuses it).
+ */
+export class IndexedDbStore extends KeyValueStore {
+    /** @param {IDBDatabase} db @param {string} storeName */
+    constructor(db, storeName) {
+        super();
+        this.db = db;
+        this.storeName = storeName;
+    }
+
+    /**
+     * Open (making it the first time) a database of one object store.
+     * @param {string} name
+     * @param {{indexedDB?: IDBFactory, storeName?: string}} [options]
+     * @returns {Promise<KeyValueStore>} an IndexedDbStore, else a MemoryStore
+     */
+    static open(name, { indexedDB = globalThis.indexedDB, storeName = 'values' } = {}) {
+        if (!indexedDB) return Promise.resolve(new MemoryStore());
+        return new Promise((resolve) => {
+            let req;
+            try { req = indexedDB.open(name, 1); } catch { resolve(new MemoryStore()); return; }
+            req.onupgradeneeded = () => { if (!req.result.objectStoreNames.contains(storeName)) req.result.createObjectStore(storeName); };
+            req.onsuccess = () => resolve(new IndexedDbStore(req.result, storeName));
+            req.onerror = () => resolve(new MemoryStore());
+        });
+    }
+
+    /** Run one request in a transaction; resolves to its result. @private */
+    _request(mode, make) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction(this.storeName, mode);
+            const req = make(tx.objectStore(this.storeName));
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+    }
+
+    get(key) { return this._request('readonly', s => s.get(key)); }
+    async set(key, value) { await this._request('readwrite', s => s.put(value, key)); }
+    async delete(key) { await this._request('readwrite', s => s.delete(key)); }
+    async keys(prefix = '') {
+        const all = await this._request('readonly', s => s.getAllKeys());
+        return all.map(String).filter(k => k.startsWith(prefix));
+    }
+}

package/src/workspace/storage/ModelLibrary.js

@@ -0,0 +1,65 @@
+/**
+ * ModelLibrary — the models kept in this browser (a KeyValueStore), so work
+ * outlives the page without saving a file: each in its editor's own file
+ * format (`data`: text or bytes, as the format exports it), with its name,
+ * when it was kept, the file it was last opened from or saved to, the kind of
+ * editor that kept it (`editorType`: pages of different editors share the
+ * browser's store, and each reads only its own), and whether it was open when
+ * the page closed (`open`), to reopen it.
+ */
+export class ModelLibrary {
+    /** The key prefix of a kept model. */
+    static PREFIX = 'model:';
+
+    /** @param {KeyValueStore} store */
+    constructor(store) {
+        this.store = store;
+    }
+
+    /** A new id for a model to keep. */
+    static newId() {
+        return `m${Date.now().toString(36)}${Math.random().toString(36).slice(2, 7)}`;
+    }
+
+    /**
+     * Keep a model (an entry with the same id is replaced).
+     * @param {{id: string, name: string, format: string, data: string|Uint8Array, fileName?: string|null, editorType?: string, open?: boolean}} entry
+     *   `format`: its ModelFileFormat's label; `editorType`: the editor part type that kept it
+     */
+    async keep(entry) {
+        if (!entry?.id) throw new TypeError('A kept model needs an id');
+        const kept = { open: true, fileName: null, ...entry, keptAt: new Date().toISOString() };
+        await this.store.set(ModelLibrary.PREFIX + entry.id, kept);
+        return kept;
+    }
+
+    /** A kept model, data and all, or null. */
+    async load(id) {
+        return (await this.store.get(ModelLibrary.PREFIX + id)) ?? null;
+    }
+
+    /** What is kept, newest first: each entry without its data (`size` instead). */
+    async list() {
+        const keys = await this.store.keys(ModelLibrary.PREFIX);
+        const entries = (await Promise.all(keys.map(k => this.store.get(k)))).filter(Boolean);
+        return entries
+            .map(({ data, ...meta }) => ({ ...meta, size: data?.length ?? 0 }))
+            .sort((a, b) => String(b.keptAt).localeCompare(String(a.keptAt)));
+    }
+
+    /** The ones open when the page last closed, oldest first (their tab order). */
+    async openOnes() {
+        return (await this.list()).filter(e => e.open).reverse();
+    }
+
+    /** Mark a kept model open or not (its tab closed: kept, not reopened next time). */
+    async setOpen(id, open) {
+        const entry = await this.load(id);
+        if (entry) await this.store.set(ModelLibrary.PREFIX + id, { ...entry, open: !!open });
+    }
+
+    /** Forget a kept model. */
+    async remove(id) {
+        await this.store.delete(ModelLibrary.PREFIX + id);
+    }
+}