arcane-os 0.43.0 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.45.0
+
+- Add public MarkdownMedia save, read, reference parsing and hydration helpers.
+  Store complete image records in application-owned DBOPFS tables outside raw
+  Markdown, with stable references and application-selected filenames. Preserve
+  JSONL/NDJSON singleton records across cold reads and backup restoration.
+- Hydrate local images independently in shared Markdown views while preserving
+  raw Markdown, external URLs, source maps and saving. Observe cancellation and
+  individual failures without removing successful sibling images. Retain print
+  resources through afterprint; explicit PrintView preparation awaits local
+  media while native beforeprint remains synchronous.
+- Apply no-retention semantics to entity-wide persistence choices as well as
+  request persist:false: complete input and response remain available to the
+  active operation, then stay outside retained transcript, recurring model
+  context, DBOPFS and memory extraction. Capture the accepted choice before
+  rendering waits and preserve original pending calls after temporary tool
+  continuations. Existing retained turns and saved history remain untouched;
+  structural sanitization applies to new durable writes only, without migration.
+- Keep image model selection, credentials, storage selection and app orchestration
+  application-owned. No model/provider/default changes are introduced.
+
+## 0.44.0
+
+- Add stateless `generateImages` through `arcane-os/ai/twin-cloud` with
+  caller-selected FAL Flux Schnell or Stable Diffusion 3.5 Large. Preserve
+  complete prompts and provider parameters, and return every image as a Blob
+  in provider order with declared media metadata.
+- Expose semantic progress and complete diagnostic callbacks, asynchronous
+  job polling, and cancellation across credentials, callbacks, requests,
+  response bodies and media downloads. Submit a paid generation request once;
+  never automatically replay an ambiguous submission.
+- Keep image model selection, credentials, display and storage with the
+  application. No global model default, saved-history migration, durable media
+  storage or change to existing chat and speech behavior is introduced.
+
 ## 0.43.0
 
 - Add reusable rendered printing through `createPrintView`, preserving the

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.43.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.45.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/browser-runtime/ai/twin-cloud.mjs

@@ -105,6 +105,240 @@ export function normalizeAIRequestAbort(error){
     return normalized;
 }
 
+/** Stateless image generation; model selection and provider parameters belong to the caller. */
+export async function generateImages({
+    model,
+    prompt,
+    parameters = {},
+    twinKey,
+    getApiKey,
+    signal = null,
+    id = Date.now(),
+    onRequest = function observeImageRequest(){},
+    onResponse = function observeImageResponse(){},
+    onProgress = function observeImageProgress(){}
+} = {}) {
+    if (signal?.aborted) throw normalizeAIRequestAbort(signal.reason);
+    const asynchronous = model === 'fal-ai/flux/schnell';
+    if (!asynchronous && model !== 'stable-diffusion-3.5-large') {
+        const error = new TypeError('TWiN generateImages requires a supported explicit image model.');
+        error.code = 'ARCANE_AI_IMAGE_MODEL_UNSUPPORTED';
+        throw error;
+    }
+    if (!is.string(prompt)) throw new TypeError('TWiN generateImages requires a prompt string.');
+    if (!parameters || !is.object(parameters) || is.array(parameters)) {
+        throw new TypeError('Image parameters must be an object of additional provider fields.');
+    }
+    if (Object.hasOwn(parameters, 'prompt') || (!asynchronous && Object.hasOwn(parameters, 'model'))) {
+        throw new TypeError('Supply the image prompt and model through their named arguments.');
+    }
+    const destination = asynchronous
+        ? 'https://inference.do-ai.run/v1/async-invoke'
+        : 'https://inference.do-ai.run/v1/images/generations';
+    const request = asynchronous
+        ? {model_id: model, input: {...parameters, prompt}}
+        : {...parameters, model, prompt};
+    // Observe the complete request without allowing a later callback to rewrite its payload.
+    const body = JSON.stringify(request);
+    const outputFormat = parameters.output_format;
+    const controller = new AbortController();
+    const operationSignal = controller.signal;
+    function cancelImageRequest() {controller.abort(signal.reason);}
+    signal?.addEventListener('abort', cancelImageRequest, {once: true});
+    if (signal?.aborted) cancelImageRequest();
+
+    function progress(stage, requestId) {
+        return settleImageOperation(
+            function publishImageProgress() {
+                return onProgress({stage, model, id, ...(requestId === undefined ? {} : {requestId})});
+            },
+            operationSignal
+        );
+    }
+
+    async function inference(url, options) {
+        const response = await settleImageOperation(
+            function requestImageInference() {return fetch(url, {...options, credentials: 'omit', signal: operationSignal});},
+            operationSignal
+        );
+        const result = await settleImageOperation(
+            function readImageInference() {
+                if (response.ok || response.headers.get('content-type')?.includes('application/json')) {
+                    return response.json();
+                }
+                return response.text();
+            },
+            operationSignal
+        );
+        if (!response.ok) throw result;
+        const retryAfter = response.headers.get('retry-after');
+        const seconds = retryAfter?.trim() ? Number(retryAfter) : NaN;
+        const date = retryAfter?.trim() ? Date.parse(retryAfter) : NaN;
+        const delay = is.finite(seconds) && seconds >= 0 ? seconds * 1000
+            : is.finite(date) ? Math.max(0, date - Date.now()) : 1000;
+        return {result, delay};
+    }
+
+    try {
+        await progress('credentials');
+        const key = twinKey === undefined && is.function(getApiKey)
+            ? await settleImageOperation(getApiKey, operationSignal) : twinKey;
+        if (!is.string(key) || !key) {
+            const error = new Error('AI provider is not configured.');
+            error.code = 'AI_PROVIDER_NOT_CONFIGURED';
+            throw error;
+        }
+        const headers = {'Content-Type': 'application/json', Authorization: `Bearer ${key}`};
+        await settleImageOperation(
+            function observeImageSubmission() {
+                return onRequest(request, id, {operation: 'images', transport: 'http', destination});
+            },
+            operationSignal
+        );
+        await progress('requesting');
+        // A lost POST response can represent an accepted paid job. Never replay it.
+        let response = await inference(destination, {method: 'POST', headers, body});
+        let result = response.result;
+        if (asynchronous) {
+            const requestId = result?.request_id;
+            while (result?.status === 'QUEUED' || result?.status === 'IN_PROGRESS') {
+                if (!is.string(requestId) || !requestId) {
+                    throw imageResultError('Image generation returned a pending job without a request_id.', result);
+                }
+                await progress(result.status === 'QUEUED' ? 'queued' : 'generating', requestId);
+                await waitForImageStatus(response.delay, operationSignal);
+                response = await inference(
+                    `${destination}/${encodeURIComponent(requestId)}/status`,
+                    {method: 'GET', headers}
+                );
+                result = response.result;
+            }
+            if (result?.status === 'FAILED') {
+                throw imageResultError('TWiN Cloud image generation failed.', result);
+            }
+            if (result?.status !== 'COMPLETED' && result?.status !== 'COMPLETE') {
+                throw imageResultError('TWiN Cloud returned an unsupported image job status.', result);
+            }
+            if (!is.array(result.output?.images)) {
+                if (!is.string(requestId) || !requestId) {
+                    throw imageResultError('Image generation returned no result or request_id.', result);
+                }
+                response = await inference(`${destination}/${encodeURIComponent(requestId)}`, {method: 'GET', headers});
+                result = response.result;
+                if (result?.status !== 'COMPLETED' && result?.status !== 'COMPLETE') {
+                    throw imageResultError('TWiN Cloud image generation did not return a completed result.', result);
+                }
+            }
+        }
+        const returnedImages = asynchronous ? result?.output?.images : result?.data;
+        if (!is.array(returnedImages)) {
+            throw imageResultError('TWiN Cloud returned no image collection.', result);
+        }
+        const images = returnedImages.map(function retainImageDescriptor(image) {return {...image};});
+        const format = result.output_format ?? outputFormat;
+        const requestId = asynchronous ? result.request_id : undefined;
+        await settleImageOperation(
+            function observeImageResult() {return onResponse(result, id, false);},
+            operationSignal
+        );
+        await progress('downloading', requestId);
+        const completed = await Promise.all(images.map(async function materializeImage(image) {
+            let blob;
+            const mediaType = image.content_type
+                ?? ({png: 'image/png', jpeg: 'image/jpeg', jpg: 'image/jpeg', webp: 'image/webp'}[format])
+                ?? 'application/octet-stream';
+            if (is.string(image.b64_json)) {
+                blob = await settleImageOperation(function decodeImageBase64() {
+                    return new Blob([Uint8Array.from(atob(image.b64_json), function imageCode(character) {
+                        return character.charCodeAt(0);
+                    })], {type: mediaType});
+                }, operationSignal);
+            } else if (is.string(image.url) && image.url) {
+                // Media URLs have their own delivery authority. Never forward the inference key.
+                const download = await settleImageOperation(function downloadGeneratedImage() {
+                    return fetch(image.url, {credentials: 'omit', signal: operationSignal});
+                }, operationSignal);
+                if (!download.ok) {
+                    throw await settleImageOperation(function readImageDownloadError() {
+                        return download.headers.get('content-type')?.includes('application/json')
+                            ? download.json() : download.text();
+                    }, operationSignal);
+                }
+                blob = await settleImageOperation(function readGeneratedImage() {return download.blob();}, operationSignal);
+                if (!blob.type) blob = new Blob([blob], {type: mediaType});
+            } else {
+                throw imageResultError('TWiN Cloud returned an image without data or a URL.', image);
+            }
+            return {
+                blob,
+                mediaType: blob.type || mediaType,
+                ...(image.width === undefined ? {} : {width: image.width}),
+                ...(image.height === undefined ? {} : {height: image.height})
+            };
+        }));
+        await progress('complete', requestId);
+        if (operationSignal.aborted) throw normalizeAIRequestAbort(operationSignal.reason);
+        return {images: completed};
+    } catch (error) {
+        if (isAIRequestAbort(error, operationSignal)) throw normalizeAIRequestAbort(error);
+        throw error;
+    } finally {
+        signal?.removeEventListener('abort', cancelImageRequest);
+        controller.abort('Image operation settled.');
+    }
+}
+
+function imageResultError(message, result) {
+    const error = new Error(message, {cause: result});
+    error.code = 'ARCANE_AI_INVALID_PROVIDER_RESULT';
+    return error;
+}
+
+/** Abort a wait even when a credential, callback, or host Fetch ignores the signal. */
+function settleImageOperation(operation, signal) {
+    return new Promise(function settleCloudImageOperation(resolve, reject) {
+        let settled = false;
+        function finish(error, value, failed) {
+            if (settled) return;
+            settled = true;
+            signal.removeEventListener('abort', cancelled);
+            if (failed) reject(error);
+            else resolve(value);
+        }
+        function cancelled() {finish(normalizeAIRequestAbort(signal.reason), undefined, true);}
+        signal.addEventListener('abort', cancelled, {once: true});
+        if (signal.aborted) {
+            cancelled();
+            return;
+        }
+        try {
+            Promise.resolve(operation()).then(
+                function accepted(value) {finish(undefined, value, false);},
+                function rejected(error) {finish(error, undefined, true);}
+            );
+        } catch (error) {
+            finish(error, undefined, true);
+        }
+    });
+}
+
+async function waitForImageStatus(delay, signal) {
+    let remaining = delay;
+    do {
+        // Split only at the host timer range; retain the provider's entire delay.
+        const milliseconds = Math.min(remaining, 2147483647);
+        let timer;
+        try {
+            await settleImageOperation(function waitForImagePoll() {
+                return new Promise(function scheduleImagePoll(finish) {timer = setTimeout(finish, milliseconds);});
+            }, signal);
+        } finally {
+            clearTimeout(timer);
+        }
+        remaining -= milliseconds;
+    } while (remaining > 0);
+}
+
 export function structuredOutputFormat(value = false){
     if(value === false || value === null || value === undefined){
         return null;

package/docs/reference/ai/twin-cloud.md

@@ -136,6 +136,130 @@ options; they do not add a key, model, browser state, or retained conversation.
 Retry warnings and observer failures use the shared console logger and preserve
 the complete original error.
 
+## Generate images with an application-selected model
+
+`generateImages` is a separate stateless operation on the same public import.
+The application owns the selected model, labels, prompt, provider parameters,
+credential source, display, and any saved image. It does not instantiate the
+browser AI singleton or change chat, speech, model preferences, or history.
+
+```javascript
+import {generateImages} from 'arcane-os/ai/twin-cloud';
+
+const controller = new AbortController();
+const {images} = await generateImages({
+    model: 'stable-diffusion-3.5-large',
+    prompt: 'A moon-powered toaster launches croissants over purple craters.',
+    parameters: {n: 2, size: '1024x1024', output_format: 'png'},
+    getApiKey: applicationRuntime.getTwinKey,
+    signal: controller.signal,
+    onProgress({stage}) {
+        console.log(stage);
+    }
+});
+
+for (const image of images) {
+    await applicationRuntime.saveGeneratedImage(image.blob, image.mediaType);
+}
+```
+
+`applicationRuntime.getTwinKey` and `saveGeneratedImage` are caller-owned
+functions in this example, not SDK APIs. Pass the credential function with any
+required receiver already bound. Use `twinKey` instead when the application
+already has its key. `getApiKey()` may return a key or a promise and is called
+only when `twinKey` is `undefined`. An explicitly supplied empty key fails with
+`AI_PROVIDER_NOT_CONFIGURED`; it does not select another credential source.
+The example's model and parameters are application choices, not SDK defaults.
+
+```javascript
+generateImages({
+    model,
+    prompt,
+    parameters,
+    twinKey,
+    getApiKey,
+    signal,
+    id,
+    onRequest,
+    onResponse,
+    onProgress
+})
+// Promise<{images: [{blob, mediaType, width?, height?}]}>
+```
+
+`parameters` defaults to `{}`, `signal` to `null`, and `id` to `Date.now()`.
+All diagnostic and progress callbacks are optional.
+
+The SDK owns the route for these exact supported identifiers:
+
+| Explicit model | Submission and result |
+| --- | --- |
+| `fal-ai/flux/schnell` | POST `/v1/async-invoke` with `{model_id:model,input:{...parameters,prompt}}`; pending jobs use GET `/v1/async-invoke/{request_id}/status`, then GET `/v1/async-invoke/{request_id}` when the completed status lacks `output.images`. |
+| `stable-diffusion-3.5-large` | POST `/v1/images/generations` with `{...parameters,model,prompt}`; images come from the completed response's `data` array. |
+
+Both routes use `https://inference.do-ai.run`. Missing or unsupported model
+identifiers reject with `ARCANE_AI_IMAGE_MODEL_UNSUPPORTED`; there is no SDK
+image model default. The prompt must be a string and is sent unchanged,
+including whitespace. `parameters` is an object of additional provider fields;
+the SDK neither supplies nor changes image counts, dimensions, quality, seeds,
+or output limits. Supply the prompt only through `prompt`, and the synchronous
+model only through `model`; duplicate reserved fields in `parameters` throw
+`TypeError` instead of silently replacing one input. Provider-supported
+parameter names and values remain that selected model's contract.
+
+Every returned image is materialized in provider order. Base64 image data
+becomes a `Blob`; returned URLs are fetched concurrently without an inference
+Authorization header or browser credentials. The output's `mediaType` uses the
+downloaded Blob's declared type, provider `content_type`, or a declared
+`output_format` of `png`, `jpeg`/`jpg`, or `webp`. With no declared type or known
+format, it is `application/octet-stream`; the SDK does not guess dimensions or
+image metadata. `width` and `height` are included only when the provider supplies
+them. The SDK saves nothing and creates no object URLs; the caller owns any
+storage and the lifetime of display URLs it creates.
+
+`onRequest(request,id,metadata)` runs once before submission with the complete
+provider request. Metadata is `{operation:'images',transport:'http',destination}`.
+`onResponse(response,id,false)` runs once with the complete final provider JSON
+after successful generation and before image materialization. Intermediate
+poll replies do not call it. These are explicit diagnostic callbacks: keep raw
+protocol outside ordinary user status and durable chat history. Credentials are
+transport-only and are absent from these payloads. The request and image
+descriptors are captured before their diagnostic callbacks so observer edits do
+not rewrite the operation's content.
+
+`onProgress({stage,model,id,requestId?})` reports semantic stages: `credentials`,
+`requesting`, `queued`, `generating`, `downloading`, and `complete`. Pending
+stages can repeat; immediately completed jobs skip them. Async job stages
+include `requestId` when present. Progress contains no image data or protocol
+body. All three callbacks may return a promise; their settlement is awaited
+and their failure rejects the operation. `onResponse` means generation returned
+a final result, not that media downloads have finished. The resolved promise
+delivers all materialized images; a failed download rejects instead of returning
+an incomplete collection.
+
+The image operation submits once and performs no automatic retry, including
+after a network loss, HTTP `429`, body-read failure, or callback failure. A lost
+POST response may correspond to an accepted paid job. This image-specific rule
+does not alter chat or speech retry behavior. While a FAL job is `QUEUED` or
+`IN_PROGRESS`, polling uses the provider's `Retry-After` delay when supplied,
+otherwise one second. Completed jobs accept `COMPLETED` and the guide's
+`COMPLETE` spelling. Failed or unusable job results reject with
+`ARCANE_AI_INVALID_PROVIDER_RESULT` and the complete result in `error.cause`.
+HTTP failures throw their complete parsed JSON or text body; transport,
+decoding, and callback failures remain their original errors.
+
+Calling `controller.abort()` cancels local credential/callback waits, requests,
+body reads, polling timers, and downloads. It rejects with
+`ARCANE_AI_REQUEST_ABORTED` and ignores later settlement from an operation that
+does not honor the signal. A callback already running remains caller-owned;
+the SDK invokes no subsequent callbacks after cancellation. Local cancellation
+does not claim to cancel a remote paid job. Dispose the controller with the
+owning page or operation; no global startup wait is required.
+
+The route and response contracts follow DigitalOcean's official
+[FAL inference guide](https://docs.digitalocean.com/products/inference/how-to/use-fal-models/)
+and [multimodal inference guide](https://docs.digitalocean.com/products/inference/how-to/use-multimodal-inference/).
+
 ## Existing browser AI interface
 
 The following browser example uses the same managed imports as the

package/docs/reference/runtime-components.md

@@ -426,7 +426,8 @@ history stores each tool's required user-facing message as an ordinary
 call envelope or ID and therefore does not recreate a pending executable call
 after reload. `submitToolResult()` and `submitToolResults()` accept `status` as
 the public result term; `disposition` remains an accepted input spelling.
-When a submitted turn uses `persist:false`, Chat may show its cards while that
+When a submitted turn uses `persist:false`, or its session's Chat entity has
+`persist=false`, Chat may show its cards while that
 one operation is active, then removes them when the operation settles; neither
 the input nor response remains in the retained transcript or model context.
 This cleanup also applies to failed, cancelled, detached, or replaced-session
@@ -437,6 +438,15 @@ operation's nodes so a completion listener can start another turn safely.
 Submission code passes those card references directly when it creates them;
 reusing an operation identifier never selects earlier conversation cards for
 cleanup or timestamp updates.
+The session's terminal `retained` boolean reports its actual commit decision;
+Chat uses that decision instead of retroactively interpreting a flag changed
+for a later request. A completion listener cannot erase an earlier settled
+turn by changing the next operation's retention setting.
+Chat carries a submission's no-retention choice into its copied session request
+before any rendering wait, so re-enabling the entity before dispatch cannot
+retain that temporary input. Existing falsy entity settings retain their
+no-retention meaning; a compatible custom session without a Chat entity keeps
+its existing default behavior.
 Persistent-turn recovery and existing saved history remain unchanged.
 
 For streaming sessions, every provisional structural card and the terminal
@@ -926,6 +936,16 @@ Native PDF and inaccessible embedded viewers require their own print command.
 was produced. Closed, destroyed, or unavailable previews return `false`;
 preparation failures reject and the visible control reports a concise failure.
 
+Markdown previews resolve saved `arcane-media:` images through
+[`MarkdownMedia.js`](runtime-modules.md#markdownmediajs) before connecting IMG
+nodes. Text appears while independent image reads finish; failures leave the
+complete text and successful images visible with a concise recovery status.
+Explicit printing waits for local reads and decoding. Native Print reports
+pending media because it cannot await them. Closing or replacing a preview
+cancels display readiness without waiting for storage; URLs already retained
+by a requested print remain until `afterprint`. Original Markdown and ordinary
+external image URLs remain unchanged.
+
 `await close()` cancels pending presentation work and closes delete, file, and
 directory dialogs in that order. A settled preview keeps its rendered content,
 media, and printing available until the file dialog actually closes; refusing
@@ -1054,7 +1074,16 @@ Events: `markdown-document-ready`, `markdown-document-state`,
 `markdown-document-empty`, `markdown-document-error`, and
 `markdown-document-navigate`.
 
-Shared dependencies: [`MD.js`](runtime-modules.md#mdjs).
+Saved local image references use
+[`MarkdownMedia.js`](runtime-modules.md#markdownmediajs). Text rendering and
+the existing rendered event do not wait for image reads. The optional
+`labels.mediaError` supplies concise visible failure text while complete
+diagnostics remain in the developer console; successful images and document
+text remain visible. Replacing, clearing, failing, or destroying the document
+releases its display resources without deleting stored media. Markdown source
+and ordinary external image URLs remain unchanged.
+
+Shared dependencies: [`MD.js`](runtime-modules.md#mdjs), [`MarkdownMedia.js`](runtime-modules.md#markdownmediajs).
 
 ### Availability and normalization
 
@@ -1104,6 +1133,16 @@ when the browser dialog was requested. Completion of physical printing or PDF
 saving is not observable through this method. See
 [`PrintView.js`](runtime-modules.md#printviewjs).
 
+Saved `arcane-media:` image references are hydrated through
+[`MarkdownMedia.js`](runtime-modules.md#markdownmediajs) in detached rendered
+nodes. Source text, edit selection, source-map comments, ordinary image URLs,
+and the existing save flow remain unchanged. Image status has its own
+idle-hidden `media-status` part, separate from save status. Explicit printing
+waits for the current image reads/decoding, follows a replacement preview, and
+rechecks readiness before capture. Native Print reports still-pending media
+synchronously; it cannot wait or cancel the native dialog. Print-owned URLs
+outlive a changed or destroyed editor until `afterprint`.
+
 `configure({fit:true,followPreview:true})` opts into the two independent
 behaviors. Both options default to `false`; omitted options retain their
 previous values during reconfiguration, and explicit `false` disables either.
@@ -1140,7 +1179,7 @@ lists, quotes, and tables follow their block, while invisible source positions
 use a nearby available rendered block rather than exact glyph geometry.
 
 Public CSS parts are `editor`, `title`, `toolbar`, `input`, `preview`,
-`actions`, `status`, `print-action`, and `save-action`. Applications can make the title
+`actions`, `status`, `media-status`, `print-action`, and `save-action`. Applications can make the title
 borderless and compact through `::part(title)` while retaining its native
 editing behavior and visible keyboard focus. These parts are styling hooks,
 not slots or replacement controls.

package/docs/reference/runtime-modules.md

@@ -96,6 +96,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`Mail.js`](#mailjs) | esm | Builds complete reports and prefers the native mail capability with an explicit HTTP transport fallback. | Browser/native hybrid + cloud | Mail inputs/results normalized; transport failures mixed. |
 | [`MailOutbox.mjs`](#mailoutboxmjs) | esm | Persists complete mail reports before delivery and normalizes idempotent enqueue, retry, reconciliation, and invalid-record maintenance. | Browser/native WebView or compatible injected host | Complete records, full work, cancellation, and lifecycle states normalized; storage, lock, and delivery failures coded. |
 | [`MailTransport.mjs`](#mailtransportmjs) | esm | Sends one complete mail report to a normalized HTTP(S) endpoint. | Browser/server with fetch + cloud | Normalized endpoint and transport errors; remote detail preserved. |
+| [`MarkdownMedia.js`](#markdownmediajs) | esm | Saves local Markdown images separately and resolves their stable references in rendered views. | Browser / supported native WebView | Complete image records, concurrent display reads, cancellation, and print-owned URL lifetime. |
 | [`MarkdownSpeech.js`](#markdownspeechjs) | esm | Removes repeated Markdown formatting marks from streamed narration. | Cross-host | Speech-only filtering; single marks and ordinary punctuation remain literal. |
 | [`Marked.min.js`](#markedminjs) | esm | Vendored Marked 18.0.5 Markdown lexer, parser, renderer, extension, and walk-token API. | Cross-host vendor module | Vendor-native Marked contract. |
 | [`MD.js`](#mdjs) | esm | Renders complete Markdown with Marked and optionally maps source blocks to rendered comment anchors. | Browser / native WebView | Complete raw and rendered Marked values; opt-in original-source offsets; parse errors vendor-native. |
@@ -2794,6 +2795,73 @@ import * as module from '/arcane/modules/Marked.min.js';
 console.log(Object.keys(module));
 ```
 
+## MarkdownMedia.js
+
+### Overview
+
+Stores complete images in the application's existing DBOPFS database while
+Markdown contains only a short, stable `arcane-media:` reference. Rendering
+resolves those local references into temporary display URLs. Importing the
+module starts no storage, network, provider, or rendering operation.
+
+### Public surface
+
+Public package import: `arcane-os/modules/MarkdownMedia.js`.
+
+- `await saveMarkdownMedia({blob,tableName='markdown-media',fileName})` writes
+  `{mediaType,dataUrl}` as a JSON-compatible record and returns
+  `{reference,tableName,fileName,mediaType}` only after the write completes.
+  The default filename is a new UUID followed by `.json`. There is no abort
+  option: accepted storage writes settle through the storage owner.
+- `parseMarkdownMediaReference(reference)` returns `{tableName,fileName}` for
+  a local reference, or `null` for an ordinary URL. Malformed local addresses
+  report their actual parsing error.
+- `await readMarkdownMedia(reference)` returns the complete `Blob`, using
+  only local storage and data-URL decoding; stored strings are never fetched
+  as network addresses.
+- `hydrateMarkdownMedia(root,{signal}={})` returns `{ready,destroy,retain}`
+  immediately. It includes an IMG root and descendant IMG elements, removes
+  local-reference `src` values synchronously, starts independent reads
+  together, and assigns owned object URLs. `ready` includes image decoding.
+  Use a detached fragment before connecting those images to the document.
+
+Hydration preserves Markdown source, image descriptions, ordinary URLs, and
+surrounding content. Failed reads or decodes reject `ready` with an
+`AggregateError` whose complete `failures` array contains
+`{image,reference,reason}`; successful sibling images remain visible.
+
+`destroy()` or abort settles display readiness promptly, prevents late display,
+and releases owned URLs. An already-started storage read remains observed and
+settles independently. `retain()` returns an idempotent release callback for
+printing; retained URLs survive destruction of the original view until every
+print owner releases them. Destruction never deletes stored images.
+
+Applications own record names, entry association, cleanup policy, and which
+records their existing JSON backup/export includes. Reusing the same filename
+supports an application-selected save-only retry without another generation
+request. The helper performs no existing-data migration.
+
+### Availability and normalization
+
+Browser or native WebView with the existing app-scoped DBOPFS owner, Blob,
+FileReader, object URLs, and IMG decoding. Encoding, storage, missing-record,
+parsing, and decoding errors remain observable. No Core capability is selected.
+
+### Example
+
+```javascript
+import {saveMarkdownMedia} from 'arcane-os/modules/MarkdownMedia.js';
+
+const mural = new Blob([
+    '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="80"><text x="10" y="45">Octopus parking only</text></svg>'
+], {type:'image/svg+xml'});
+const {reference} = await saveMarkdownMedia({blob:mural});
+editor.insertMarkdown(`![Octopus parking only](${reference})`);
+```
+
+Here `editor` is the ready shared Markdown Editor. Its normal change/save flow
+still owns saving the Markdown; this operation saves the image record.
+
 ## MD.js
 
 ### Overview
@@ -3071,6 +3139,9 @@ assistant content in configured model context and ChatEntity/DBOPFS history.
 That assistant-only opening survives reload and empty-chat maintenance without
 a fabricated user turn. A second opening rejects as `AI_CHAT_OPENING_EXISTS`;
 an unavailable durable ChatEntity rejects as `AI_CHAT_PERSISTENCE_UNAVAILABLE`.
+If retention is disabled while the opening is being prepared, that same error
+rolls back the opening before its append; it does not leave hidden model context.
+An opening write already accepted by DBOPFS still completes normally.
 
 `send()` accepts either
 `{message:{content,role:'user'|'tool',tool_call_id?,message?,name?,status?,persist},...}`
@@ -3086,6 +3157,20 @@ the retained transcript, memory extraction, or DBOPFS. A nonpersistent response
 therefore does not open a retained structural-tool continuation. A retained
 structural tool result must use the persistence choice captured by its matching
 assistant tool call.
+An explicitly nonretained tool-result continuation uses its matching pending
+call only for that operation, then rolls back without settling or changing the
+retained call. A later retained continuation can still settle it normally.
+
+The entity-wide `session.chatEntity.persist=false` applies the same no-retention
+rule to new turns and direct entity additions; it is not a disk-only switch.
+The session captures that setting when it accepts a request and observes it
+again before accepting a durable append. Changing it later cannot bring back
+discarded inputs or responses. A write already accepted by DBOPFS finishes
+normally; toggling the setting does not undo that write or rewrite saved data.
+Completed `send()` and `stream()` responses include a session-owned `retained`
+boolean outside `message` and the provider payload, identifying whether the
+turn entered recurring history. Existing retained and stored records remain
+untouched: this boundary applies to new additions and performs no migration.
 
 `history()` returns provider-safe configured model context, including the
 system prompt and every complete ordinary visible committed turn. Only a
@@ -3263,11 +3348,16 @@ print-only surface expands scrollable content without editing the live screen.
 
 ### Public surface
 
-Named `createPrintView({host,content,title,active,priority=0,signal,onError,retain})`
+Named `createPrintView({host,content,title,active,priority=0,signal,onError,retain,prepare})`
 returns `{print,destroy}`. `host` is a connected element; synchronous callbacks
 return the rendered content node, string title, and whether the view is active.
 Optional `retain()` returns a resource-release callback. It keeps owned media
 available until preparation is cancelled or the browser emits `afterprint`.
+Optional `prepare(signal)` may await view-owned readiness during an explicit
+print request. After it settles, current content and title are read again
+synchronously immediately before capture. A view whose content changes during
+preparation must keep its owned media retained and reject a still-pending
+snapshot through its synchronous `content()` callback.
 
 `await print()` selects that view, waits for accessible HTML frame, image, and
 font readiness, and requests the browser print dialog. It returns `false` when
@@ -3281,6 +3371,8 @@ on ties. File preview uses priority `1`; editor uses `0`. Native `beforeprint`
 is synchronous: it snapshots currently rendered content, cannot await a newly
 loading resource, and cannot cancel the browser's dialog. `onError(error)` or
 the developer console receives complete preparation failures.
+Native printing never invokes the asynchronous `prepare` callback; prepared
+views still receive the synchronous content/title read at capture.
 
 `destroy()` unregisters the view and cancels pending preparation. Once the
 dialog has been requested, its snapshot and retained media remain until