arcane-os 0.34.2 → 0.36.0

package/runtime/arcane/modules/DBOPFS.js

@@ -1049,165 +1049,194 @@ class DBOPFS {
     }
 
     /**
-     * Downloads the entire database as a compressed PNG backup.
+     * Creates a PNG backup without downloading or writing database records.
+     * JSON is deflated and framed with the existing little-endian payload
+     * length, then encoded in RGB channels with opaque alpha for restoration.
      *
-     * The database is streamed as JSON, compressed using gzip via
-     * CompressionStream, and encoded into RGBA pixels inside a PNG.
-     *
-     * Each pixel stores 4 bytes of payload data.
-     * The first 4 bytes store the gzip byte length header.
-     *
-     * Output example:
-     *
-     *     DBOPFS-backup-2026-03-10-13-45-12.png
-     *
-     * @param {string} name
-     * Base name used for the generated backup filename.
-     *
-     * @returns {Promise<void>}
+     * @param {Object} options
+     * @param {string[]} [options.tableNames] Saved tables; omitted selects all.
+     * @param {Object<string,Object<string,*>>} [options.additionalTables]
+     * Caller-owned tables. Each replaces the matching saved table in this
+     * export only. Values must be JSON-serializable; no storage write occurs.
+     * @param {AbortSignal} [options.signal]
+     * Stops further preparation and prevents a subsequent download. Browser
+     * file reads and canvas encoding already in progress cannot be interrupted.
+     * @returns {Promise<Blob>} An image/png Blob in the existing backup format.
      */
-    async downloadCompressedPNG(name='DBOPFS-backup'){
-        if(!('CompressionStream' in window)){
-            throw new Error('CompressionStream not supported.')
+    async createCompressedPNG({tableNames, additionalTables = {}, signal} = {}) {
+        signal?.throwIfAborted();
+        if (!('CompressionStream' in window)) {
+            throw new Error('CompressionStream not supported.');
         }
 
-        const encoder=new TextEncoder()
-        await this.getTableNames(true)
-
-        const tableNames=Object.keys(this.#tableHandles)
-
-        const jsonStream=new ReadableStream({
-            start:async controller=>{
-                controller.enqueue(encoder.encode('{'))
+        await this.readyPromise;
+        signal?.throwIfAborted();
+        await this.getTableNames(true);
+        signal?.throwIfAborted();
 
-                for(let t=0;t<tableNames.length;t++){
-                    const tableName=tableNames[t]
-                    const table=await this.getTableHandle(tableName)
-
-                    if(t>0){
-                        controller.enqueue(encoder.encode(','))
-                    }
-
-                    controller.enqueue(
-                        encoder.encode(`${JSON.stringify(tableName)}:{`)
-                    )
-
-                    let first=true
+        function logicalTableName(name) {
+            return tableNameForDirectory(directoryNameForTable(name));
+        }
 
-                    for await(const [fileName]of table.entries()){
-                        const value=await this.get(tableName,fileName)
+        const selectedNames = new Set(
+            (tableNames === undefined ? Object.keys(this.#tableHandles) : tableNames)
+                .map(logicalTableName)
+        );
+        const suppliedTables = new Map();
+        for (const [name, records] of Object.entries(additionalTables)) {
+            const tableName = logicalTableName(name);
+            selectedNames.add(tableName);
+            suppliedTables.set(tableName, records);
+        }
 
-                        if(!first){
-                            controller.enqueue(encoder.encode(','))
-                        }
+        const database = this;
+        const encoder = new TextEncoder();
 
-                        first=false
+        async function* tableRecords(tableName) {
+            if (suppliedTables.has(tableName)) {
+                yield* Object.entries(suppliedTables.get(tableName));
+                return;
+            }
 
-                        const json=`${JSON.stringify(fileName)}:${JSON.stringify(value)}`
+            const table = database.#tableHandles[tableName];
+            if (!table) return;
+            for await (const [fileName] of table.entries()) {
+                signal?.throwIfAborted();
+                const value = await database.get(tableName, fileName);
+                signal?.throwIfAborted();
+                yield [fileName, value];
+            }
+        }
 
-                        controller.enqueue(encoder.encode(json))
+        async function* encodeDatabase() {
+            yield encoder.encode('{');
+            let firstTable = true;
+            for (const tableName of selectedNames) {
+                signal?.throwIfAborted();
+                if (!firstTable) yield encoder.encode(',');
+                firstTable = false;
+                yield encoder.encode(`${JSON.stringify(tableName)}:{`);
+
+                let firstRecord = true;
+                for await (const [fileName, value] of tableRecords(tableName)) {
+                    signal?.throwIfAborted();
+                    if (!firstRecord) yield encoder.encode(',');
+                    firstRecord = false;
+                    const serialized = JSON.stringify(value);
+                    if (serialized === undefined) {
+                        throw new TypeError(`PNG record ${tableName}/${fileName} is not JSON-serializable.`);
                     }
-
-                    controller.enqueue(encoder.encode('}'))
+                    yield encoder.encode(`${JSON.stringify(fileName)}:${serialized}`);
                 }
-
-                controller.enqueue(encoder.encode('}'))
-                controller.close()
-            }
-        })
-
-        const gzipStream=jsonStream.pipeThrough(
-            new CompressionStream('deflate')
-        )
-
-        const reader=gzipStream.getReader()
-
-        const chunks=[]
-        let totalLength=0
-
-        while(true){
-            const {done,value}=await reader.read()
-
-            if(done){
-                break
+                yield encoder.encode('}');
             }
-
-            chunks.push(value)
-            totalLength+=value.length
+            yield encoder.encode('}');
         }
 
-        const gzipBytes=new Uint8Array(totalLength)
-
-        let offset=0
-        for(const chunk of chunks){
-            gzipBytes.set(chunk,offset)
-            offset+=chunk.length
+        const encoded = encodeDatabase();
+        const jsonStream = new ReadableStream(
+            {
+                async pull(controller) {
+                    signal?.throwIfAborted();
+                    const {done, value} = await encoded.next();
+                    if (done) controller.close();
+                    else controller.enqueue(value);
+                },
+                async cancel() {
+                    await encoded.return();
+                }
+            }
+        );
+        const compressedStream = jsonStream.pipeThrough(
+            new CompressionStream('deflate'),
+            {signal}
+        );
+        const reader = compressedStream.getReader();
+        const chunks = [];
+        let totalLength = 0;
+        try {
+            while (true) {
+                const {done, value} = await reader.read();
+                signal?.throwIfAborted();
+                if (done) break;
+                chunks.push(value);
+                totalLength += value.length;
+            }
+        } finally {
+            reader.releaseLock();
         }
 
-        const payload=new Uint8Array(totalLength+4)
-
-        const view=new DataView(payload.buffer)
-        view.setUint32(0,totalLength,true)
-
-        payload.set(gzipBytes,4)
-
-        const size=Math.ceil(Math.sqrt(payload.length/3))
-
-        const totalPixels=size*size
-
-        if(totalPixels*3 < payload.length){
-            throw new Error('PNG canvas too small for payload.')
+        // Length and channel offsets belong only to the existing PNG format.
+        const payload = new Uint8Array(totalLength + 4);
+        const view = new DataView(payload.buffer);
+        view.setUint32(0, totalLength, true);
+        let offset = 4;
+        for (const chunk of chunks) {
+            payload.set(chunk, offset);
+            offset += chunk.length;
         }
 
-        const canvas=document.createElement('canvas')
-        canvas.width=size
-        canvas.height=size
-
-        const ctx=canvas.getContext('2d')
-
-        if(!ctx){
-            throw new Error('Canvas 2D context unavailable.')
+        const size = Math.ceil(Math.sqrt(payload.length / 3));
+        const canvas = document.createElement('canvas');
+        canvas.width = size;
+        canvas.height = size;
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+            throw new Error('Canvas 2D context unavailable.');
         }
 
-        const imgData=ctx.createImageData(size,size)
-        imgData.data.fill(0);
-        
-        let p=0;
-
-        for(let i=0;i<imgData.data.length;i+=4){
-
-            imgData.data[i]   = payload[p]   ?? 0;
-            imgData.data[i+1] = payload[p+1] ?? 0;
-            imgData.data[i+2] = payload[p+2] ?? 0;
-            imgData.data[i+3] = 255;
-
-            p+=3;
+        const imgData = ctx.createImageData(size, size);
+        let position = 0;
+        for (let index = 0; index < imgData.data.length; index += 4) {
+            imgData.data[index] = payload[position] ?? 0;
+            imgData.data[index + 1] = payload[position + 1] ?? 0;
+            imgData.data[index + 2] = payload[position + 2] ?? 0;
+            imgData.data[index + 3] = 255;
+            position += 3;
         }
+        ctx.putImageData(imgData, 0, 0);
 
-        ctx.putImageData(imgData,0,0)
-
-        const blob=await new Promise(resolve=>canvas.toBlob(resolve,'image/png'))
-
-        if(!blob){
-            throw new Error('PNG export failed.')
+        const blob = await new Promise(
+            function encodeBackupPNG(resolve) {
+                canvas.toBlob(resolve, 'image/png');
+            }
+        );
+        signal?.throwIfAborted();
+        if (!blob) {
+            throw new Error('PNG export failed.');
         }
+        return blob;
+    }
 
-        const stamp=new Date()
+    /**
+     * Downloads one PNG backup using the same options as createCompressedPNG.
+     * Existing one-argument callers still export the whole database.
+     * @param {string} name Base filename; an ISO timestamp is appended.
+     * @param {Object} options PNG table selection and optional signal.
+     * @returns {Promise<void>}
+     */
+    async downloadCompressedPNG(name = 'DBOPFS-backup', options = {}) {
+        const blob = await this.createCompressedPNG(options);
+        options.signal?.throwIfAborted();
+        const stamp = new Date()
             .toISOString()
-            .slice(0,19)
-            .replace(/[:T]/g,'-')
-
-        const url=URL.createObjectURL(blob)
-
-        const a=document.createElement('a')
-        a.href=url
-        a.download=`${name}-${stamp}.png`
-
-        document.body.appendChild(a)
-        a.click()
-        a.remove()
-
-        URL.revokeObjectURL(url)
+            .slice(0, 19)
+            .replace(/[:T]/g, '-');
+
+        const url = URL.createObjectURL(blob);
+
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = `${name}-${stamp}.png`;
+
+        try {
+            document.body.appendChild(a);
+            options.signal?.throwIfAborted();
+            a.click();
+        } finally {
+            a.remove();
+            URL.revokeObjectURL(url);
+        }
     }
 
     /**
@@ -1229,30 +1258,39 @@ class DBOPFS {
      *
      * @param {File|Blob} file
      * PNG backup file generated by DBOPFS.
+     * @param {Object} options
+     * @param {function(Object): Object|Promise<Object>} [options.selectTables]
+     * Receives the complete decoded table/file map once, before writes. Only
+     * its returned map is restored; the application owns selection/projection.
      *
      * @returns {Promise<void>}
-     * Resolves once the database restore process is complete.
+     * Resolves after every write succeeds. Rejected writes are collected after
+     * all table batches settle and reported in an AggregateError with the
+     * original reasons and table/file associations; successful writes remain.
      */
-    async restoreFromPNG(file){
+    async restoreFromPNG(file, {selectTables} = {}) {
         const img=await createImageBitmap(
             file,
             {premultiplyAlpha:'none'}
         )
 
-        const canvas=document.createElement('canvas')
-        canvas.width=img.width
-        canvas.height=img.height
+        let data;
+        try {
+            const canvas = document.createElement('canvas');
+            canvas.width = img.width;
+            canvas.height = img.height;
 
-        const ctx=canvas.getContext('2d')
+            const ctx = canvas.getContext('2d');
+            if (!ctx) {
+                throw new Error('Canvas 2D context unavailable.');
+            }
 
-        if(!ctx){
-            throw new Error('Canvas 2D context unavailable.')
+            ctx.drawImage(img, 0, 0);
+            data = ctx.getImageData(0, 0, img.width, img.height).data;
+        } finally {
+            img.close();
         }
 
-        ctx.drawImage(img,0,0)
-
-        const data=ctx.getImageData(0,0,img.width,img.height).data
-
         if(data.length < 4){
             throw new Error('Invalid PNG backup.')
         }
@@ -1283,12 +1321,38 @@ class DBOPFS {
 
         const json=await new Response(stream).text()
 
-        const db=JSON.parse(json)
+        const decodedTables = JSON.parse(json);
+        const db = selectTables === undefined
+            ? decodedTables
+            : await selectTables(decodedTables);
 
         const tables=Object.keys(db)
 
-        for(const table of tables){
-            await this.setMany(table,db[table])
+        const failures = [];
+        for (const tableName of tables) {
+            const fileNames = Object.keys(db[tableName]);
+            const results = await this.setMany(tableName, db[tableName]);
+            for (const [index, result] of results.entries()) {
+                if (result.status === 'rejected') {
+                    failures.push(
+                        {tableName, fileName: fileNames[index], reason: result.reason}
+                    );
+                }
+            }
+        }
+
+        if (failures.length > 0) {
+            const error = new AggregateError(
+                failures.map(
+                    function restoreWriteReason(failure) {
+                        return failure.reason;
+                    }
+                ),
+                'PNG restore could not save every record.'
+            );
+            error.code = 'DBOPFS_RESTORE_WRITE_FAILED';
+            error.failures = failures;
+            throw error;
         }
     }
 }

package/runtime/arcane/modules/VoiceCaptureWorklet.js

@@ -0,0 +1,194 @@
+// AudioWorklet is a native isolated realm: this processor has no app imports.
+// Its silent output keeps capture driven by the audio clock without feedback.
+class ArcaneVoiceCaptureProcessor extends AudioWorkletProcessor {
+    #preRoll;
+    #preRollLength = 0;
+    #preRollOffset = 0;
+    #quietFrames;
+    #chunkFrames;
+    #activityThreshold;
+    #active = false;
+    #hasActivity = false;
+    #quietCount = 0;
+    #sampleCount = 0;
+    #sequence = 0;
+    #buffer = null;
+    #view = null;
+    #stopped = false;
+
+    constructor(options) {
+        super();
+        const configuration = options.processorOptions;
+        this.#preRoll = new Float32Array(
+            Math.round(configuration.preRollMs * sampleRate / 1000)
+        );
+        this.#quietFrames = Math.max(1, Math.round(configuration.quietMs * sampleRate / 1000));
+        this.#chunkFrames = Math.max(1, Math.round(configuration.chunkMs * sampleRate / 1000));
+        this.#activityThreshold = configuration.activityThreshold;
+        this.port.onmessage = this.#receiveControl.bind(this);
+    }
+
+    #receiveControl(event) {
+        if (this.#stopped || event.data.type !== 'stop') return;
+        this.#stopped = true;
+        try {
+            this.#emit('stop');
+            this.#release();
+            this.port.postMessage(
+                {type: 'stopped'}
+            );
+        } catch (error) {
+            this.#fail(error);
+        }
+    }
+
+    process(inputs, outputs) {
+        if (this.#stopped) return false;
+        for (const output of outputs) {
+            for (const channel of output) channel.fill(0);
+        }
+        const samples = inputs[0]?.[0];
+        if (!samples) return true;
+        try {
+            for (const sample of samples) this.#capture(sample);
+        } catch (error) {
+            this.#fail(error);
+        }
+        return !this.#stopped;
+    }
+
+    #capture(sample) {
+        const activity = Math.abs(sample) > this.#activityThreshold;
+        if (!this.#active) {
+            if (!activity) {
+                this.#retainPreRoll(sample);
+                return;
+            }
+            this.#active = true;
+            this.#beginSegment();
+            const oldest = this.#preRoll.length
+                ? (this.#preRollOffset - this.#preRollLength + this.#preRoll.length) % this.#preRoll.length
+                : 0;
+            for (let index = 0; index < this.#preRollLength; index += 1) {
+                this.#append(this.#preRoll[(oldest + index) % this.#preRoll.length]);
+            }
+            this.#preRollLength = 0;
+            this.#preRollOffset = 0;
+        } else if (!this.#buffer) {
+            this.#beginSegment();
+        }
+
+        this.#append(sample);
+        this.#hasActivity = this.#hasActivity || activity;
+        this.#quietCount = activity ? 0 : this.#quietCount + 1;
+        if (this.#quietCount >= this.#quietFrames) {
+            this.#emit('pause');
+            this.#active = false;
+            this.#quietCount = 0;
+        } else if (this.#sampleCount >= this.#chunkFrames && this.#hasActivity) {
+            // Continue at the next sample. Emitted audio never enters pre-roll.
+            this.#emit('periodic');
+        }
+    }
+
+    #retainPreRoll(sample) {
+        if (!this.#preRoll.length) return;
+        this.#preRoll[this.#preRollOffset] = sample;
+        this.#preRollOffset = (this.#preRollOffset + 1) % this.#preRoll.length;
+        this.#preRollLength = Math.min(this.#preRollLength + 1, this.#preRoll.length);
+    }
+
+    #beginSegment() {
+        // Preserve all requested pre-roll even when it exceeds chunkMs. After a
+        // periodic boundary, retain quiet audio until activity or the pause so
+        // a silence-only continuation never produces a clip.
+        const frames = Math.max(this.#chunkFrames, this.#quietFrames + 1, this.#preRollLength + 1);
+        this.#buffer = new ArrayBuffer(56 + frames * 4);
+        this.#view = new DataView(this.#buffer);
+        this.#sampleCount = 0;
+        this.#hasActivity = false;
+    }
+
+    #append(sample) {
+        // WAV framing owns little-endian Float32 encoding; sample values are
+        // unchanged, without integer quantization or amplitude clamping.
+        this.#view.setFloat32(56 + this.#sampleCount * 4, sample, true);
+        this.#sampleCount += 1;
+    }
+
+    #emit(reason) {
+        if (!this.#hasActivity || !this.#sampleCount) {
+            this.#buffer = null;
+            this.#view = null;
+            this.#sampleCount = 0;
+            return;
+        }
+        const dataLength = this.#sampleCount * 4;
+        // This is the RIFF transport field's representable range, not a
+        // capture-duration policy. The caller can select a shorter chunk.
+        if (dataLength > 0xffffffff - 48) {
+            throw new RangeError('This segment cannot be represented by RIFF/WAVE; select a shorter chunk duration.');
+        }
+        this.#writeText(0, 'RIFF');
+        this.#view.setUint32(4, 48 + dataLength, true);
+        this.#writeText(8, 'WAVE');
+        this.#writeText(12, 'fmt ');
+        this.#view.setUint32(16, 16, true);
+        this.#view.setUint16(20, 3, true);
+        this.#view.setUint16(22, 1, true);
+        this.#view.setUint32(24, sampleRate, true);
+        this.#view.setUint32(28, sampleRate * 4, true);
+        this.#view.setUint16(32, 4, true);
+        this.#view.setUint16(34, 32, true);
+        this.#writeText(36, 'fact');
+        this.#view.setUint32(40, 4, true);
+        this.#view.setUint32(44, this.#sampleCount, true);
+        this.#writeText(48, 'data');
+        this.#view.setUint32(52, dataLength, true);
+        const audio = this.#sampleCount === (this.#buffer.byteLength - 56) / 4
+            ? this.#buffer
+            : this.#buffer.slice(0, 56 + dataLength);
+        this.#sequence += 1;
+        this.port.postMessage(
+            {
+                type: 'segment',
+                audio,
+                sampleRate,
+                sequence: this.#sequence,
+                reason,
+                durationMs: this.#sampleCount * 1000 / sampleRate
+            },
+            [audio]
+        );
+        this.#buffer = null;
+        this.#view = null;
+        this.#sampleCount = 0;
+        this.#hasActivity = false;
+    }
+
+    #writeText(offset, text) {
+        for (let index = 0; index < text.length; index += 1) {
+            this.#view.setUint8(offset + index, text.charCodeAt(index));
+        }
+    }
+
+    #fail(error) {
+        this.#stopped = true;
+        this.#release();
+        this.port.postMessage(
+            {type: 'error', error}
+        );
+    }
+
+    #release() {
+        this.#buffer = null;
+        this.#view = null;
+        this.#preRoll = new Float32Array(0);
+        this.#preRollLength = 0;
+        this.#sampleCount = 0;
+        this.#hasActivity = false;
+        this.#active = false;
+    }
+}
+
+registerProcessor('arcane-continuous-voice-capture', ArcaneVoiceCaptureProcessor);