arcane-os 0.42.2 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 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
+  complete rendered content, title, styles and prepared image/font resources.
+  Explicit print requests await preparation; native printing uses the active
+  view. Resources remain owned through `afterprint`.
+- Add Markdown editor `print()` and `insertMarkdown(text)` and file-manager
+  `printPreview()`. Insertion replaces the current selection through the
+  ordinary full-content change lifecycle; printing does not save the document.
+- Add reusable history/file-manager `close()` with child-first closure and
+  pending-open cancellation. Refused or failed closure preserves the settled
+  visible preview, media and printing until its dialog actually closes.
+  Preserve modal focus restoration and existing saved records without migration.
+
 ## 0.42.2
 
 - Stop generating SDK cache suffixes in import maps, materialized runtime,

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.42.2` SDK contract. Applications pin one exact npm
+This checkout defines the `0.44.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

@@ -67,17 +67,17 @@ appropriate.
 | [`conversation-view.html`](#conversation-viewhtml) | Provider-neutral conversation display, advisory actions, composer, busy state, and status. | `setConversation()`<br>`setBusy()`<br>`setStatus()`<br>`clearComposer()`<br>`destroy()` | `conversation-view-ready`<br>`communication-send`<br>`communication-advisory-action` | DOM-normalized |
 | [`dashboard-config.html`](#dashboard-confightml) | Selects which normalized chart definitions are visible on a dashboard. | `configure()`<br>`setDefinitions()`<br>`setVisibility()`<br>`getChartOptions()`<br>`getEffectiveVisibility()`<br>`open()`<br>`close()`<br>`destroy()` | `dashboard-config-ready`<br>`dashboard-config-opened`<br>`dashboard-config-closed`<br>`dashboard-config-change` | Fully normalized definitions and visibility |
 | [`data-maintenance.html`](#data-maintenancehtml) | Runs destructive cleanup of empty chats and memories inside the current app data scope. | `open()`<br>`destroy()` | `data-maintenance-ready`<br>`data-maintenance-complete` | Normalized counts; DBOPFS failures mixed |
-| [`data-view.html`](#data-viewhtml) | Opens a modal file view and forwards application-owned preview and directory-filter callbacks. | `beforeOpen()`<br>`open()`<br>`destroy()` | `data-view-ready` | DOM-native result; preview/filter configuration reaches the child before loading |
+| [`data-view.html`](#data-viewhtml) | Opens a modal file view and forwards application-owned preview and directory-filter callbacks. | `beforeOpen()`<br>`open()`<br>`close()`<br>`printPreview()`<br>`destroy()` | `data-view-ready` | DOM-native result; preview/filter configuration reaches the child before loading |
 | [`directory-picker.html`](#directory-pickerhtml) | Presents the provider-owned OS directory chooser with change/cancel/error states. | `configure()`<br>`focus()`<br>`select()`<br>`destroy()` | `directory-picker-ready`<br>`directory-picker-change`<br>`directory-picker-cancel`<br>`directory-picker-error` | Complete plain-text paths and native selection/error |
 | [`document-inspector.html`](#document-inspectorhtml) | Inspects PDF, text, or source documents and records review state. | `loadDocument()`<br>`selectView()`<br>`markSaved()`<br>`destroy()` | `document-inspector-ready`<br>`document-review-change` | Document state normalized; browser document APIs mixed |
 | [`file-drop.html`](#file-drophtml) | Acquires complete file selections by drag/drop or picker and presents busy, progress, error, and cleared state. | `configure()`<br>`openPicker()`<br>`clear()`<br>`setBusy()`<br>`setError()`<br>`setProgress()`<br>`destroy()` | `file-drop-ready`<br>`file-drop-selected`<br>`file-drop-progress`<br>`file-drop-state`<br>`file-drop-error` | Complete selections preserved; browser File/drop errors mixed |
 | [`file-inspector.html`](#file-inspectorhtml) | Displays file metadata, preview, busy/error state, and caller-defined actions. | `configure()`<br>`show()`<br>`clear()`<br>`setActions()`<br>`setBusy()`<br>`setError()`<br>`setPreview()`<br>`destroy()` | `file-inspector-ready`<br>`file-inspector-action`<br>`file-inspector-change`<br>`file-inspector-cleared`<br>`file-inspector-error` | State normalized; preview/provider behavior mixed |
-| [`file-manager.html`](#file-managerhtml) | Browses app-scoped files, filters directories before reads, and renders application-described previews. | `setProvider()`<br>`loadAll()`<br>`setFilter()`<br>`setDirectoryFilter()`<br>`select()`<br>`clearSelection()`<br>`destroy()` | `file-manager-ready`<br>`file-manager-select`<br>`file-manager-open`<br>`file-manager-action` | Selection/filter state, neutral preview descriptors, cancellation, and media cleanup normalized; storage/provider behavior mixed |
+| [`file-manager.html`](#file-managerhtml) | Browses app-scoped files, filters directories before reads, and renders application-described previews. | `setProvider()`<br>`loadAll()`<br>`setFilter()`<br>`setDirectoryFilter()`<br>`select()`<br>`clearSelection()`<br>`close()`<br>`printPreview()`<br>`destroy()` | `file-manager-ready`<br>`file-manager-select`<br>`file-manager-open`<br>`file-manager-action` | Selection/filter state, neutral preview descriptors, cancellation, and media cleanup normalized; storage/provider behavior mixed |
 | [`header.html`](#headerhtml) | Shared title bar with history, reload, online marker, presentation labels, and 988 link. | None | No component-specific event | Browser/platform-native behavior; no component-ready contract |
 | [`integration-settings.html`](#integration-settingshtml) | Edits non-secret communication service configuration and service actions. | `configure()`<br>`getValues()`<br>`setStatus()`<br>`destroy()` | `integration-settings-ready`<br>`integration-settings-save`<br>`integration-settings-close`<br>`integration-action` | Normalized non-secret values |
 | [`local-ai-status.html`](#local-ai-statushtml) | Presents local-AI standby, failure, recovery, guidance, retry, and dismissal states. | `configure()`<br>`begin()`<br>`present()`<br>`destroy()`<br>`hidden` | `local-ai-status-ready`<br>`local-ai-status-dismissed`<br>`local-ai-retry` | Fully normalized LocalAIReadiness report |
 | [`markdown-document.html`](#markdown-documenthtml) | Renders and navigates a complete Markdown document with focusable fragments. | `configure()`<br>`load()`<br>`render()`<br>`clear()`<br>`fail()`<br>`focus()`<br>`focusFragment()`<br>`destroy()` | `markdown-document-ready`<br>`markdown-document-state`<br>`markdown-document-loading`<br>`markdown-document-rendered`<br>`markdown-document-empty`<br>`markdown-document-error`<br>`markdown-document-navigate` | Complete Markdown/state normalized; malformed input and Marked/DOM failures remain visible |
-| [`markdown-editor.html`](#markdown-editorhtml) | Configurable Markdown authoring with optional bounded input/preview panes and edit-position following. | `configure()`<br>`focus()`<br>`clear()`<br>`saveEntry()`<br>`destroy()` | `markdown-editor-ready`<br>`markdown-editor-change`<br>`markdown-editor-saved` | Editor values, opt-in fit layout, and preview following normalized; injected save result mixed |
+| [`markdown-editor.html`](#markdown-editorhtml) | Configurable Markdown authoring with optional bounded input/preview panes, edit-position following, and rendered printing. | `configure()`<br>`focus()`<br>`clear()`<br>`insertMarkdown()`<br>`saveEntry()`<br>`print()`<br>`destroy()` | `markdown-editor-ready`<br>`markdown-editor-change`<br>`markdown-editor-saved` | Editor values, opt-in fit layout, and preview following normalized; injected save result mixed |
 | [`media-embed.html`](#media-embedhtml) | Loads a parsed YouTube video or playlist embed with ordinary hosting by default, optional privacy enhancement, and an external-platform action. | `configure()`<br>`load()`<br>`destroy()` | `media-embed-ready`<br>`media-load`<br>`media-error`<br>`media-open-platform` | URL/error normalized; iframe/platform behavior native |
 | [`modal.html`](#modalhtml) | Generic modal with population, configurable user dismissal, actions, and concurrent task execution. | `configure()`<br>`populate()`<br>`open()`<br>`close()`<br>`runTasks()`<br>`destroy()`<br>`running`<br>`opened` | `modal-ready`<br>`modal-opened`<br>`modal-closed`<br>`modal-action` | Modal state normalized; injected task results mixed |
 | [`output-panel.html`](#output-panelhtml) | Presents status, output, body, coverage, actions, pending, error, and cleared states. | `configure()`<br>`setOutput()`<br>`setBody()`<br>`setCoverage()`<br>`setActions()`<br>`setPending()`<br>`setStatus()`<br>`setError()`<br>`clear()`<br>`destroy()` | `output-panel-ready`<br>`output-panel-state`<br>`output-panel-change`<br>`output-panel-action`<br>`output-panel-error`<br>`output-panel-cleared` | DOM-normalized |
@@ -663,7 +663,7 @@ own record mappings through the same preview callbacks as the standalone
 
 ### Public surface
 
-Methods/properties: `beforeOpen()`, `open()`, `destroy()`.
+Methods/properties: `beforeOpen()`, `open()`, `close()`, `printPreview()`, `destroy()`.
 
 Assign `previewDescriptor`, `previewTransform`, and `directoryFilter` on the
 host before opening. The component forwards those callbacks, comma-separated
@@ -673,6 +673,20 @@ before the child's first load. Reopening refreshes those values before
 `beforeOpen()` is awaited before this configuration is consumed. `data-dirs`
 selects the initial directories; `data-layout` defaults to `files`.
 
+`await close()` invalidates pending opens, closes the child's dialogs before the
+parent, and returns `true` only after closure. It returns `false` when destroyed
+or a child/parent cannot close; complete errors reach shared diagnostics. It is
+reusable: a later `open()` reloads the existing child. Repeated closes share the
+pending closure. `destroy()` remains terminal.
+
+An application that loads a history selection into an editor must synchronously
+call `preventDefault()` on the existing cancelable `file-manager-open` event
+before awaiting its own save/load work. That application owns record selection,
+autosave, title, and editor focus; call `close()` after loading and restore focus
+after it resolves `true`. No record-loading policy is added to the SDK.
+`printPreview()` forwards to the currently open child preview and returns
+`false` when no such preview is available.
+
 Events: `data-view-ready`.
 
 Shared dependencies: [`WaitForComponent.js`](runtime-modules.md#waitforcomponentjs).
@@ -821,7 +835,7 @@ and `destroy()` cleanup, without delaying unrelated component startup.
 ### Public surface
 
 Methods/properties: `setProvider()`, `loadAll()`, `setFilter()`,
-`setDirectoryFilter()`, `select()`, `clearSelection()`, `destroy()`,
+`setDirectoryFilter()`, `select()`, `clearSelection()`, `close()`, `printPreview()`, `destroy()`,
 `previewDescriptor`, `previewTransform`, `directoryFilter`.
 
 Assign `directoryFilter(entry, context)` before the first load, or call
@@ -879,8 +893,9 @@ component does not automatically read every related media variant.
 
 Closing the preview, opening another file, or destroying the manager aborts
 the preview signal, ignores late descriptor/loader results, stops owned audio,
-removes iframe `srcdoc`, and revokes every owned object URL, including those
-in nested collections.
+removes iframe `srcdoc`, and releases owned object URLs, including those in
+nested collections. An active print snapshot retains its URLs until the
+browser's `afterprint` event, even when the preview closes meanwhile.
 Applications should observe the supplied signal in their asynchronous reads.
 Descriptor and file-open failures show `Unable to open this file.` in the
 current modal and send the original error to the shared logger.
@@ -900,6 +915,26 @@ of the original `File`.
 The larger file-preview dialog reuses `--modal-width`, `--modal-max-height`,
 and `--modal-padding`; applications can override those existing modal values.
 
+The preview's **Print** button and `await printPreview()` print its current
+rendered content with the file title. Native browser Print selects the open
+preview ahead of the editor. Printing uses the shared
+[`PrintView.js`](runtime-modules.md#printviewjs) owner; accessible HTML frames
+are copied from their current rendered document, never substituted with source
+text. Explicit printing waits for images/fonts and HTML frame readiness.
+Native PDF and inaccessible embedded viewers require their own print command.
+`true` means the browser print dialog was requested, not that paper or a PDF
+was produced. Closed, destroyed, or unavailable previews return `false`;
+preparation failures reject and the visible control reports a concise failure.
+
+`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
+or failing to close leaves the still-visible preview usable. Actual file-dialog
+closure releases its preview resources. The method returns `false` on
+refused/failed closure or after destruction. The manager stays
+reusable; a later opening can use it again. Already accepted upload/deletion
+writes complete through the storage owner without reopening closed dialogs.
+
 Events: `file-manager-ready`, `file-manager-select`, `file-manager-open`, `file-manager-action`.
 
 Shared dependencies: [`DBOPFS.js`](runtime-modules.md#dbopfsjs), [`File.js`](runtime-entities.md#filejs), [`MD.js`](runtime-modules.md#mdjs), [`WaitForComponent.js`](runtime-modules.md#waitforcomponentjs).
@@ -1048,8 +1083,26 @@ inside an application-supplied bounded area.
 
 ### Public surface
 
-Methods/properties: `configure()`, `focus()`, `clear()`, `saveEntry()`,
-`destroy()`, `value`, `entryTitle`, `options`.
+Methods/properties: `configure()`, `focus()`, `clear()`, `insertMarkdown(text)`,
+`saveEntry()`, `print()`, `destroy()`, `value`, `entryTitle`, `options`.
+
+`insertMarkdown(text)` replaces the current source selection with the exact
+supplied string, places the caret after it, and emits the ordinary change
+event. It preserves the source viewport and normal preview/save lifecycle.
+It returns `false` when read-only or destroyed and throws `TypeError` for a
+non-string. The application owns the inserted Markdown and any related data.
+
+The visible **Print** control and `await print()` print the complete rendered
+Markdown with `entryTitle`, independently of saving. Native browser Print uses
+that same registered view unless an open file preview takes precedence.
+The SDK copies current rendered DOM/styles into a temporary print-only view,
+leaving the editor's source, controls, and screen layout in place. Explicit
+printing waits for resource readiness; native `beforeprint` is synchronous
+and uses the currently rendered content. `print()` returns `false` when the
+view is unavailable, rejects preparation failures, and returns `true` only
+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).
 
 `configure({fit:true,followPreview:true})` opts into the two independent
 behaviors. Both options default to `false`; omitted options retain their
@@ -1087,7 +1140,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`, and `save-action`. Applications can make the title
+`actions`, `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

@@ -109,6 +109,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`PersistentAIChatSession.js`](#persistentaichatsessionjs) | esm | Adds explicit retained-history/memory policy to complete configured chat without changing DBOPFS or ChatEntity semantics. | Browser / native WebView with DBOPFS and configured chat | Retained context commits atomically; `persist:false` turns are one-operation-only. |
 | [`PreferenceStore.js`](#preferencestorejs) | esm | Loads and updates schema-defined app preferences through native storage with a narrow browser fallback. | Browser/native hybrid | Complete ordinary values remain mutable; setAll uses one optional atomic adapter batch for every selected value when advertised, otherwise performs complete ordered serial writes, and only exact unsupported native capability changes future operations to the browser fallback. |
 | [`PreparedSpeech.js`](#preparedspeechjs) | esm | Owns detached ordered preparation, semantic audio reuse, and per-caller cancellation behind AI.prepareTTS. | Browser / native WebView with injected synthesis and optional DBOPFS | Complete original inputs, ordered audio metadata, durable reuse, and observable preparation results. |
+| [`PrintView.js`](#printviewjs) | esm | Prints current rendered content and title through one document-owned print lifecycle. | Browser / supported native WebView print implementation | Complete rendered snapshot, preparation cancellation, resource lifetime, and honest request result. |
 | [`QRCode.min.js`](#qrcodeminjs) | classic-script | Vendored QRCode generator for DOM, canvas, SVG, and image output. | Browser vendor script | Vendor-native. |
 | [`Questionnaire.js`](#questionnairejs) | esm | Evaluates whether a one-time questionnaire prompt is due without performing the prompt. | Cross-host | Normalized conservative boolean. |
 | [`RecordLinkIndex.js`](#recordlinkindexjs) | esm | Parses record links and builds their normalized index. | Cross-host | Fully normalized. |
@@ -3251,6 +3252,69 @@ import {prepareSpeech} from '/arcane/modules/PreparedSpeech.js';
 console.log(typeof prepareSpeech); // function
 ```
 
+## PrintView.js
+
+### Overview
+
+Shared rendered-print owner used by Markdown Editor and File Manager. It
+captures the current DOM and computed styles, including accessible rendered
+HTML frames, complete text, selected images, and the current title. A temporary
+print-only surface expands scrollable content without editing the live screen.
+
+### Public surface
+
+Named `createPrintView({host,content,title,active,priority=0,signal,onError,retain})`
+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`.
+
+`await print()` selects that view, waits for accessible HTML frame, image, and
+font readiness, and requests the browser print dialog. It returns `false` when
+the view is unavailable or preparation is cancelled, returns `true` for a dialog
+request, and rejects preparation errors. It cannot confirm physical printing
+or PDF saving. Overlapping print sessions on the same document reject.
+
+One native `beforeprint`/`afterprint` registration serves each document. Native
+Print chooses the highest-priority visible active view, most recently registered
+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.
+
+`destroy()` unregisters the view and cancels pending preparation. Once the
+dialog has been requested, its snapshot and retained media remain until
+`afterprint`. Import alone creates no listener, provider, storage, or print job.
+
+Exact exports: `createPrintView`.
+
+### Availability and normalization
+
+**Browser and native WebViews with a print implementation.** Requires DOM,
+CSSOM, FontFace/Image readiness, and browser print events. No Core capability.
+Cross-origin/inaccessible frames, native PDF frames, and object/embed viewers
+must use their owning viewer's print command; the helper does not replace their
+content with raw source or claim an unrendered document was printed. Font
+sources in embedded documents must be accessible for snapshot preparation.
+
+### Example
+
+```javascript
+import {createPrintView} from '/arcane/modules/PrintView.js';
+
+const ledger = document.querySelector('#moon-library-ledger');
+const printing = createPrintView({
+    host:ledger,
+    content:() => ledger,
+    title:() => 'Books overdue on the Moon',
+    active:() => true
+});
+document.querySelector('#print-ledger').onclick = async function printLedger(){
+    try { await printing.print(); }
+    catch(error) { console.error('Unable to print the ledger:', error); }
+};
+```
+
 ## QRCode.min.js
 
 ### Overview