arcane-os 0.43.0 → 0.45.0

package/runtime/arcane/modules/MarkdownMedia.js

@@ -0,0 +1,211 @@
+import Is from 'strong-type';
+
+const is = new Is(false);
+const referencePrefix = 'arcane-media:';
+
+/** Return the local record address, or null for an ordinary image URL. */
+export function parseMarkdownMediaReference(reference) {
+    if (!is.string(reference) || !reference.startsWith(referencePrefix)) {
+        return null;
+    }
+    const address = reference.substring(referencePrefix.length);
+    const separator = address.indexOf('/');
+    if (separator < 0) {
+        throw new TypeError('A Markdown media reference needs a table and filename.');
+    }
+    return {
+        tableName: decodeURIComponent(address.substring(0, separator)),
+        fileName: decodeURIComponent(address.substring(separator + 1))
+    };
+}
+
+/**
+ * Save a complete image in the app's existing DBOPFS database. The returned
+ * reference belongs in Markdown; the JSON-compatible record belongs in its
+ * separate table so the existing database backup can include it unchanged.
+ * Applications own filename reuse, entry association, and export selection.
+ * The promise settles the durable write; this operation has no abort option.
+ */
+export async function saveMarkdownMedia({
+    blob,
+    tableName = 'markdown-media',
+    fileName = `${crypto.randomUUID()}.json`
+}) {
+    const reference = `${referencePrefix}${encodeURIComponent(tableName)}/${encodeURIComponent(fileName)}`;
+    const encoding = new Promise(function encodeImage(resolve, reject) {
+        const reader = new FileReader();
+        reader.onload = function imageEncoded() {
+            resolve(reader.result);
+        };
+        reader.onerror = function imageEncodingFailed() {
+            reject(reader.error || new Error('Image encoding failed.'));
+        };
+        reader.onabort = function imageEncodingAborted() {
+            reject(new DOMException('Image encoding was aborted.', 'AbortError'));
+        };
+        reader.readAsDataURL(blob);
+    });
+    const [dataUrl, {default: DBOPFS}] = await Promise.all([
+        encoding,
+        import('./DBOPFS.js')
+    ]);
+    const mediaType = blob.type || 'application/octet-stream';
+    await new DBOPFS().set(tableName, fileName, {mediaType, dataUrl});
+    return {
+        reference,
+        tableName,
+        fileName,
+        mediaType
+    };
+}
+
+/** Read the complete local image for display or application-owned export. */
+export async function readMarkdownMedia(reference) {
+    const address = parseMarkdownMediaReference(reference);
+    if (!address) {
+        throw new TypeError('Expected an arcane-media: reference.');
+    }
+    const {default: DBOPFS} = await import('./DBOPFS.js');
+    const stored = await new DBOPFS().get(address.tableName, address.fileName);
+    if (stored === null || stored === undefined) {
+        throw new DOMException(`Markdown image was not found: ${reference}`, 'NotFoundError');
+    }
+    // DBOPFS parses JSONL/NDJSON as record arrays; restoring a parsed backup can
+    // wrap its one record again. Never choose one image from multiple records.
+    let record = is.string(stored) ? JSON.parse(stored) : stored;
+    while (is.array(record) && record.length === 1) record = record[0];
+    const encoded = /^data:[^,]*;base64,([\s\S]*)$/u.exec(record?.dataUrl);
+    if (!encoded) {
+        throw new TypeError(`Markdown image has an unreadable data URL: ${reference}`);
+    }
+    // Decode locally; a stored string is never passed to Fetch or a network API.
+    const decoded = atob(encoded[1]);
+    const content = Uint8Array.from(decoded, function imageCharacter(character) {
+        return character.charCodeAt(0);
+    });
+    return new Blob([content], {type: record.mediaType});
+}
+
+/**
+ * Resolve only local Markdown IMG references beneath a rendered root (including
+ * an IMG root). Markdown source and ordinary URLs are never changed. Independent
+ * reads start together; ready waits for decoding or display cancellation.
+ * Failures reject with AggregateError.failures [{image, reference, reason}];
+ * successful siblings remain visible until their owner is destroyed.
+ *
+ * destroy() prevents late assignments and releases owned object URLs. A print
+ * owner calls retain() before copying the rendered DOM and releases its returned
+ * idempotent callback after printing, allowing URLs to outlive the source view.
+ * Abort promptly rejects display readiness. An already-started DBOPFS read
+ * remains observed and settles independently; its late result is not displayed.
+ */
+export function hydrateMarkdownMedia(root, {signal} = {}) {
+    const images = [...root.querySelectorAll('img')];
+    if (root.localName === 'img') images.unshift(root);
+    const owned = [];
+    const displayCancellations = new Set();
+    let destroyed = false;
+    let retainers = 0;
+    let destructionReason;
+
+    function releaseURLs() {
+        if (!destroyed || retainers > 0) return;
+        for (const {image, url} of owned) {
+            if (image.getAttribute('src') === url) image.removeAttribute('src');
+            URL.revokeObjectURL(url);
+        }
+        owned.length = 0;
+    }
+
+    function destroy() {
+        if (destroyed) return;
+        destroyed = true;
+        destructionReason = signal?.aborted
+            ? signal.reason
+            : new DOMException('Markdown media display was destroyed.', 'AbortError');
+        signal?.removeEventListener('abort', destroy);
+        for (const cancel of displayCancellations) cancel();
+        displayCancellations.clear();
+        releaseURLs();
+    }
+
+    function retain() {
+        if (destroyed) throw destructionReason;
+        retainers += 1;
+        let released = false;
+        return function releaseMarkdownMedia() {
+            if (released) return;
+            released = true;
+            retainers -= 1;
+            releaseURLs();
+        };
+    }
+
+    function waitForDisplay(operation) {
+        return new Promise(function observeDisplayOperation(resolve, reject) {
+            let settled = false;
+            function settle(callback, value) {
+                if (settled) return;
+                settled = true;
+                displayCancellations.delete(cancelDisplay);
+                callback(value);
+            }
+            function cancelDisplay() {
+                settle(reject, destructionReason);
+            }
+            displayCancellations.add(cancelDisplay);
+            // Both outcomes remain observed after display cancellation; this
+            // wait does not claim to cancel the underlying storage or decode.
+            Promise.resolve(operation).then(
+                function displayOperationFinished(value) {settle(resolve, value);},
+                function displayOperationFailed(error) {settle(reject, error);}
+            );
+            if (destroyed) cancelDisplay();
+        });
+    }
+
+    async function loadImage(image, reference) {
+        if (destroyed) throw destructionReason;
+        const blob = await waitForDisplay(readMarkdownMedia(reference));
+        if (destroyed) throw destructionReason;
+        const url = URL.createObjectURL(blob);
+        owned.push({image, url});
+        image.setAttribute('src', url);
+        await waitForDisplay(image.decode());
+        if (destroyed) throw destructionReason;
+    }
+
+    signal?.addEventListener('abort', destroy, {once: true});
+    if (signal?.aborted) destroy();
+    const pending = [];
+    for (const image of images) {
+        const reference = image.getAttribute('src');
+        if (!is.string(reference) || !reference.startsWith(referencePrefix)) continue;
+        // Remove the custom scheme before the first asynchronous storage wait.
+        if (!destroyed) image.removeAttribute('src');
+        pending.push({image, reference, operation: loadImage(image, reference)});
+    }
+    const ready = Promise.allSettled(pending.map(function imageOperation(item) {
+        return item.operation;
+    })).then(function imagesSettled(results) {
+        const failures = [];
+        for (const [index, result] of results.entries()) {
+            if (result.status === 'rejected') {
+                failures.push({
+                    image: pending[index].image,
+                    reference: pending[index].reference,
+                    reason: result.reason
+                });
+            }
+        }
+        if (failures.length > 0) {
+            const error = new AggregateError(failures.map(function imageFailure(failure) {
+                return failure.reason;
+            }), 'Some local Markdown images could not be displayed.');
+            error.failures = failures;
+            throw error;
+        }
+        if (destroyed) throw destructionReason;
+    });
+    return {ready, destroy, retain};
+}

package/runtime/arcane/modules/PersistentAIChatSession.js

@@ -556,6 +556,7 @@ class PersistentAIChatSession{
     /** Persists one model-authored opening while retaining none of its bootstrap request. */
     async open(input){
         const settings=normalizeOpening(input);
+        const retainOpening=this.#entity.persist===true;
         const name=this.aiName;
         if(this.#pending){
             throw coded(new Error('A chat request is already active for this session.'),'AI_CHAT_BUSY');
@@ -565,7 +566,7 @@ class PersistentAIChatSession{
         try{
             await this.ready();
             if(this.#historyError)throw this.#historyError;
-            if(this.#entity.persist!==true){
+            if(!retainOpening||this.#entity.persist!==true){
                 throw coded(
                     new Error('The model-authored chat opening requires durable chat persistence.'),
                     'AI_CHAT_PERSISTENCE_UNAVAILABLE',
@@ -576,6 +577,15 @@ class PersistentAIChatSession{
                 settings.message,
                 {request:settings.request,signal:settings.signal},
             );
+            if(this.#entity.persist!==true){
+                throw coded(
+                    new Error(
+                        'The model-authored chat opening requires durable chat persistence.',
+                        {cause:prepared.response},
+                    ),
+                    'AI_CHAT_PERSISTENCE_UNAVAILABLE',
+                );
+            }
             await this.#entity.addAIMessage(
                 prepared.response.message.content,
                 {extractMemory:false,persist:true,name},
@@ -597,6 +607,7 @@ class PersistentAIChatSession{
 
     async #requestTurn(input,streamHandlers=null){
         const settings=normalizeSend(input);
+        const retainTurn=settings.messagePersist&&Boolean(this.#entity.persist);
         const name=this.aiName;
         if(this.#pending){
             throw coded(new Error('A chat request is already active for this session.'),'AI_CHAT_BUSY');
@@ -621,7 +632,7 @@ class PersistentAIChatSession{
                     if(persistence===undefined||submittedIds.has(message.tool_call_id)){
                         throw coded(new TypeError('A tool message has no unique pending structural tool call.'),'AI_CHAT_INVALID_TOOL_MESSAGE');
                     }
-                    if(persistence!==settings.messagePersist){
+                    if(retainTurn&&persistence!==settings.messagePersist){
                         throw coded(
                             new TypeError('A tool result must use the persistence of its assistant tool call.'),
                             'AI_CHAT_INCOHERENT_PERSISTENCE',
@@ -674,10 +685,10 @@ class PersistentAIChatSession{
                     );
                 }
             }
-            if(!settings.messagePersist){
+            if(!retainTurn||!this.#entity.persist){
                 prepared.rollback();
                 prepared=null;
-                return assistantDisplayResponse(result,name);
+                return {...assistantDisplayResponse(result,name),retained:false};
             }
             await this.#entity.addTurn({
                 assistantMessage:result.message,
@@ -706,10 +717,13 @@ class PersistentAIChatSession{
             }
             const transcript=this.#entity.transcript;
             const assistantRecord=transcript.at(-1);
-            return assistantDisplayResponse(
-                committed,name,
-                assistantRecord?.role==='assistant'?assistantRecord.timestamp:undefined,
-            );
+            return {
+                ...assistantDisplayResponse(
+                    committed,name,
+                    assistantRecord?.role==='assistant'?assistantRecord.timestamp:undefined,
+                ),
+                retained:true,
+            };
         }catch(error){
             prepared?.rollback();
             throw error;

package/runtime/arcane/modules/PrintView.js

@@ -5,8 +5,9 @@ const registries=new WeakMap();
 let fontSequence=0;
 
 /**
- * Print current rendered DOM. Callbacks are synchronous; retain() may return a
- * resource release function. print() reports a browser request, never an output.
+ * Print current rendered DOM. prepare(signal) may await explicit-print readiness;
+ * other callbacks are synchronous. retain() may return a resource release function.
+ * print() reports a browser request, never an output.
  * Native beforeprint cannot await readiness or cancel the browser's dialog.
  */
 export function createPrintView({
@@ -17,7 +18,8 @@ export function createPrintView({
     priority=0,
     signal,
     onError,
-    retain
+    retain,
+    prepare
 }){
     if(!host?.ownerDocument||!is.function(content)||!is.function(title)
         ||!is.function(active)||!is.finite(priority)){
@@ -27,8 +29,11 @@ export function createPrintView({
         ||(retain!==undefined&&!is.function(retain))){
         throw new TypeError('Print error and resource-retention callbacks must be functions.');
     }
+    if(prepare!==undefined&&!is.function(prepare)){
+        throw new TypeError('A print preparation callback must be a function.');
+    }
     const registry=documentRegistry(host.ownerDocument);
-    const view={host,content,title,active,priority,onError,retain,destroyed:false,pending:null};
+    const view={host,content,title,active,priority,onError,retain,prepare,destroyed:false,pending:null};
     registry.views.add(view);
     signal?.addEventListener('abort',destroy,{once:true});
     if(signal?.aborted){
@@ -98,6 +103,10 @@ function documentRegistry(document){
             }
             const session=registry.session||startSession(registry,view);
             if(!session.stage){
+                if(view.prepare){
+                    session.content=readContent(view);
+                    session.title=readTitle(view);
+                }
                 capture(registry,session);
             }
             session.requested=true;
@@ -153,14 +162,8 @@ function startSession(registry,view){
         if(session.release&&!is.function(session.release)){
             throw new TypeError('A print resource-retention callback must return a release function.');
         }
-        session.content=view.content();
-        if(!session.content||!is.function(session.content.cloneNode)){
-            throw new TypeError('Print content must be a rendered DOM Node.');
-        }
-        session.title=view.title();
-        if(!is.string(session.title)){
-            throw new TypeError('A print title must be a string.');
-        }
+        session.content=readContent(view);
+        session.title=readTitle(view);
         return session;
     }catch(error){
         finishSession(registry,session);
@@ -168,6 +171,22 @@ function startSession(registry,view){
     }
 }
 
+function readContent(view){
+    const content=view.content();
+    if(!content||!is.function(content.cloneNode)){
+        throw new TypeError('Print content must be a rendered DOM Node.');
+    }
+    return content;
+}
+
+function readTitle(view){
+    const title=view.title();
+    if(!is.string(title)){
+        throw new TypeError('A print title must be a string.');
+    }
+    return title;
+}
+
 async function printRendered(registry,view){
     if(registry.session){
         throw new Error('A rendered print request is already being prepared or displayed.');
@@ -186,6 +205,23 @@ async function printRendered(registry,view){
             finishSession(registry,session);
             return false;
         }
+        if(view.prepare){
+            await abortable(view.prepare(signal),signal);
+            if(session.error){
+                throw session.error;
+            }
+            if(session.requested){
+                return true;
+            }
+            if(signal.aborted||!available(view)){
+                finishSession(registry,session);
+                return false;
+            }
+            // Read and capture together: a changing view can reject pending
+            // content synchronously without an unobserved readiness gap.
+            session.content=readContent(view);
+            session.title=readTitle(view);
+        }
         capture(registry,session);
         const images=Array.from(session.stage.shadowRoot.querySelectorAll('img'));
         await Promise.all(images.map(function readyImage(image){
@@ -224,6 +260,9 @@ async function printRendered(registry,view){
         if(cancelled){
             return false;
         }
+        if(view.prepare&&session.error){
+            throw session.error;
+        }
         throw error;
     }
 }