arcane-os 0.59.1 → 0.60.0

package/docs/reference/local-image-editing.md

@@ -0,0 +1,79 @@
+# Local image edit inputs
+
+The SDK input decoder prepares a PNG raster for the shared native image
+runtime. Decoding does not load a model or perform inference. The runtime owns
+model selection, supported editing operations, native calls and their complete
+results. Applications retain the original image and decide whether to save a
+newly generated result.
+
+## Decoder contract
+
+`src/local-ai/image-editing.mjs` exports the internal worker function
+`decodeImage({data, mediaType, signal})`.
+
+| Field | Contract |
+| --- | --- |
+| `data` | Complete encoded PNG in a `Uint8Array`; a Node `Buffer` is also accepted. Only the supplied view is read. |
+| `mediaType` | `image/png`, an empty string, or omitted. The PNG signature is read from the actual input. Other declared formats report unsupported input. |
+| `signal` | Optional `AbortSignal` belonging to the image request. |
+
+The promise returns `{width, height, channel, data}`. Dimensions come from the
+source raster; `channel` is `3` for RGB or `4` for RGBA. Returned `data` is a
+separate contiguous `Uint8Array` containing interleaved samples, with pixels
+ordered left to right and rows ordered top to bottom. The native request owner
+retains this allocation until the native operation actually completes,
+including after a cancellation request.
+
+Input decoding accepts static, non-interlaced, 8-bit RGB and RGBA PNGs, all
+five PNG row filters, and image data spread across multiple `IDAT` chunks.
+RGB transparent-color information is represented as RGBA. An optional suggested
+palette on an RGB or RGBA image does not change its color type.
+
+Indexed-color, grayscale, 16-bit, interlaced and animated PNGs currently report
+unsupported input. JPEG and WebP are also unsupported by this decoder. The
+decoder does not silently convert those formats or select one animation frame.
+
+The original encoded image is copied for the operation and never modified or
+detached. Decoding preserves stored color samples and straight alpha, including
+RGB values underneath transparent pixels. It does not composite onto a chosen
+background, rotate pixels from metadata, apply a color-profile conversion,
+resize, crop or create a file. Metadata remains in the original image; the
+native raster record contains pixels and dimensions only.
+
+## Execution and cancellation
+
+Invoke the decoder inside the shared image runtime's existing worker.
+Inflation uses asynchronous Node zlib. Row reconstruction yields between
+scanlines so the worker can receive cancellation. An abort during inflation is
+observed after that native operation settles; it does not claim instant
+interruption. A cancelled decode returns no raster for inference.
+
+`ARCANE_IMAGE_INPUT_UNSUPPORTED` describes an unavailable input format or
+encoding. `ARCANE_IMAGE_DECODE_FAILED` describes unreadable PNG structure or
+scanlines. Node zlib failures retain their complete original errors, and
+cancellation retains the owning signal's reason or Node `AbortError`. A decode
+failure never returns partial imagery or substitutes a different image.
+
+## Editing semantics at the native owner
+
+Whole-image img2img uses an initial image, prompt and strength. Masked editing
+adds a separate mask; instruction/reference editing uses a model that supports
+reference conditioning. These are distinct operations and must be advertised
+only when the selected model and native path implement them. Ordinary img2img
+does not require LoRA training. The candidate engine documents this directly
+with its base SD1.4 model in the
+[tagged img2img example](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/docs/sd.md#img2img-example).
+
+Source dimensions are decoder output, not an implicit request to change the
+generation dimensions. The model owner documents its actual canvas adaptation
+and reports actual output dimensions. In the candidate engine, temporary
+initial images use model preprocessing while caller images remain unchanged;
+even `mode=none` does not suppress all later model adaptation. See the
+[native preprocessing contract](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/docs/image_preprocessing.md).
+
+An RGB-only model such as the selected SD1.4 candidate consumes the stored RGB
+and does not preserve alpha. The SDK must not silently choose a compositing
+background or claim that passing RGBA preserves its displayed appearance.
+Strength zero is also not an exact-copy operation: native img2img still uses
+the model's encode, sampling and decode path. These model behaviors are
+separate from the decoder preserving the original input.

package/docs/reference/model-assets.md

@@ -0,0 +1,144 @@
+# Native working files from stored model assets
+
+The selected `0.60.0` package contains the model-assets helpers as internal
+preparation. The public imports and Core registration shown below belong to
+the pending local-image integration and are unavailable through `0.60.0`.
+These examples document that integration's intended public contract.
+
+`prepareCoreModelAssets()` streams complete browser `File` or `Blob` members
+through the existing Core connection into native working files. DBOPFS keeps
+the authoritative originals. The helper performs no model download and changes
+neither stored content nor the model format.
+
+Use complete members returned by `createDbopfsModelStore().ensure()` or files
+read from the application's existing DBOPFS owner. The browser model store
+already assembles persisted Range parts into one logical Blob per upstream
+member. Preserve that member order and the original relative filenames,
+including companion files required by a model.
+
+## Browser preparation
+
+```javascript
+import {prepareCoreModelAssets} from 'arcane-os/ai/core-model-assets';
+import {createCoreImageRuntime} from 'arcane-os/ai/core-image';
+
+const stored = await modelStore.ensure(selectedSource, {signal});
+const projection = await prepareCoreModelAssets({
+    client,
+    workingDirectory: selectedWorkingDirectory,
+    members: [{path: 'sd-v1-4.ckpt', file: stored.files[0]}],
+    signal,
+    onProgress: renderPreparationProgress
+});
+const image = createCoreImageRuntime({client});
+try {
+    await image.load({
+        model: 'sd14',
+        assetProjectionId: projection.id,
+        resourcePaths: {model: 'sd-v1-4.ckpt'},
+        signal
+    });
+} finally {
+    // Native loading takes its own retain handle before using these files.
+    await projection.release();
+}
+const result = await image.generate({
+    model: 'sd14',
+    prompt: 'A dignified raccoon who has been put in charge of the moon.',
+    signal
+});
+// Display or save the complete returned image through the application owner.
+await image.unload();
+```
+
+This example assumes that the application selected the `sd14` model and its
+complete checkpoint source. Model choice, download approval, prompts, output
+storage and the selected working directory remain application-owned.
+
+`prepareCoreModelAssets({client,workingDirectory,members,signal,onProgress})`
+requires an available Core connection exposing the model-assets service.
+`client` defaults to the installed Core client. Every member is
+`{path,file}`, where `path` is its relative filename or companion-file path and
+`file` is the complete stored Blob or File. Relative working-directory paths
+resolve from the native service's `appRoot`; an application may explicitly
+select an absolute working directory.
+
+The result contains `id`, `directory`, ordered
+`members: [{path,nativePath}]`, and an idempotent asynchronous `release()`.
+The operation creates a unique child directory under the selected working
+directory. Member paths identify files inside that child directory. Original
+DBOPFS files remain untouched.
+
+Each incoming Blob stream chunk is encoded only for the existing JSON Core
+transport. The helper waits for the corresponding native write before reading
+the next chunk of that member. Independent members transfer concurrently;
+the complete member set is returned only after every write and file close
+finishes. There is no complete-model transport buffer or application content
+limit. Progress reports actual preparation phases and member paths.
+
+Cancellation stops active readers and requests. Failure joins the participating
+transfers and requests native cleanup; that cleanup joins actual file writes
+before removing the projection. Cleanup uses its own uncancelled operation so
+an already-aborted preparation signal cannot skip it. Original failures and
+cleanup failures remain observable.
+
+## Native ownership
+
+```javascript
+import {createModelAssetService} from 'arcane-os/core/model-assets';
+
+const modelAssets = createModelAssetService({appRoot});
+// Register this same service with Core and pass it to the native engine owner.
+const use = modelAssets.retain(projectionId);
+try {
+    // Load and use the complete files from use.members.
+    await ownNativeModelLifetime(use.members);
+} finally {
+    // ownNativeModelLifetime must join actual model release before returning.
+    await use.release();
+}
+```
+
+`createModelAssetService({appRoot})` returns a Core service with `current()`,
+`retain(id)` and `dispose()`. `retain()` accepts only a completed projection
+and returns `{id,directory,members,release}`. A native engine takes this handle
+before loading and releases it after actual unload, failed-load cleanup or
+worker exit. A rejected inference/load promise alone does not establish native
+release. Multiple contexts can retain one prepared set, and repeated inference
+on a retained context reuses its files.
+
+The browser's `projection.release()` relinquishes preparation ownership. It
+does not delete files retained by a native engine. Deletion follows the final
+native release and removes only that operation's working directory. Core closes
+independent services concurrently, so the model-assets service waits for all
+native retain handles during disposal instead of assuming service order.
+Owners must release their handles after joining their actual engine lifetime.
+
+Closing a browser accessor does not by itself establish native unload.
+Explicitly release unused prepared projections. Core disposal also releases
+preparation ownership and cleans up after retained engine uses end.
+
+`current()` returns `{closing,projections}`. Each projection reports its `id`,
+`directory`, `state`, ordered `members`, `preparationOwned`, number of native
+`uses`, and `error`. Core emits `modelAssets.state` for lifecycle changes.
+
+## Core transport operations
+
+| Method | Parameters | Result |
+| --- | --- | --- |
+| `modelAssets.open` | `{id,workingDirectory,members:[{path}]}` | Preparing projection and native member paths |
+| `modelAssets.write` | `{id,memberIndex,contentBase64}` | `{id,memberIndex,written:true}` after the native write |
+| `modelAssets.complete` | `{id}` | Ready projection after all files close |
+| `modelAssets.release` | `{id}` | Released preparation ownership; native uses may retain the files |
+| `modelAssets.status` | `{}` | Current projection lifecycle records |
+
+The browser helper owns this transport sequence. Correlation IDs identify
+operations; they are unrelated to content identity. Original model files remain
+separate and complete. A retry creates a new working projection from the stored
+assets; it does not redownload them or replace the authoritative DBOPFS record.
+
+The implementation uses browser streams, the existing portable Core JSON
+transport and Node filesystem operations. Native paths and cleanup follow the
+host's Windows, Linux or macOS filesystem behavior. Android requires its host's
+Core/filesystem adaptation. These are source-level platform contracts, not a
+claim of execution on every target.

package/docs/reference/runtime-modules.md

@@ -387,8 +387,12 @@ existing `audioFormat` when the catalog does not declare response formats. When
 the selected model declares `speech.responseFormats`, that setting is used only when supported; if
 the setting is the instance's `opus` default and the model rejects it, the catalog's
 `speech.defaultResponseFormat` is used, while any other unsupported setting is
-rejected. It propagates the caller-owned signal and returns a playable `Blob`;
-it does not independently choose a provider, cloud fallback, model, runtime, or
+rejected. It propagates the caller-owned signal and returns a playable `Blob`.
+The native `LOCAL_SPEACH` route forwards that signal separately from its
+synthesis payload to `Arcane.speech.synthesize(request, {signal})`; Core aborts
+are normalized to `AbortError` with `ARCANE_AI_REQUEST_ABORTED`. Actual engine
+interruption belongs to the registered service. It does not independently
+choose a provider, cloud fallback, model, runtime, or
 voice policy for the application. Every call removes repeated same formatting
 marks from a cloned outbound input before delegation; the caller's payload stays
 unchanged. The third `preparation` argument is reserved for SDK-internal
@@ -529,8 +533,11 @@ operation boundary, generation, and stable reason. Muting, explicit
 cancellation, permission waiting, and superseded generations do not emit a
 failure. The operation event does not rewrite provider readiness; the consuming
 Chat/Speech surface owns its visible mute and recovery state.
-`fetchSTT(audioFile,signal)` propagates the caller-owned signal;
-provider routes accept a `Blob` or `File` directly and leave media decoding,
+`fetchSTT(audioFile,signal)` propagates the caller-owned signal, including the
+native `Arcane.speech.transcribe(request, {signal})` route. The native signal
+remains separate from the complete audio request; Core aborts are normalized
+to `AbortError` with `ARCANE_AI_REQUEST_ABORTED`.
+Provider routes accept a `Blob` or `File` directly and leave media decoding,
 PCM normalization, and WAV construction to the selected shared provider;
 delivery suppression is guaranteed after abort, while underlying provider-stop
 claims remain limited to that provider's cancellation contract.
@@ -4168,7 +4175,9 @@ creating a profile or migrating saved data.
 Exact exports: `arcaneThemeReady`, `bootstrapArcaneTheme`, `default`, and
 `disposeArcaneThemeBootstrap`.
 
-`disposeArcaneThemeBootstrap()` removes both bootstrap-owned subscriptions.
+`disposeArcaneThemeBootstrap()` removes bootstrap-owned subscriptions,
+native-window theme observers and listeners, and cancels its pending window
+request.
 The cache is a presentation hint, not the authority for preferences or user
 data. Preference loading and User readiness independently reconcile it; cache
 failures are logged without blocking the page.
@@ -4178,6 +4187,29 @@ does not establish restoration before the first paint. Use the classic
 [ThemePresentation head entry](#themepresentationjs) before CSS for that early
 restoration. Neither entry imports User or starts its storage lifecycle.
 
+When a native host exposes `Arcane.window.setTheme`, the shared bootstrap
+samples the app body's inherited `--background` and `--text-color`. It resolves
+CSS variables, named colors, HSL and other browser-supported color forms through
+computed style. Modern color spaces use the browser's sRGB canvas conversion;
+the resolved alpha is retained separately, including translucency close to one.
+Authored styles remain unchanged. Missing semantic properties are omitted.
+
+One listener on the shared `arcane-theme-change` owner, root/body presentation
+attribute observers, stylesheet-load events and device-color-scheme changes
+schedule samples. Identical channel values do not issue another request.
+Initial sampling and preference/profile reconciliation run independently of
+rendering and native completion. Page hide cancels the pending renderer wait;
+page restoration samples again. Print presentation is excluded. The host keeps
+its last accepted colors across navigation until the next document changes
+them. No additional theme bus, polling, storage or system-appearance mutation is
+introduced by this forwarding path.
+
+Ordinary browsers and facades without the window method install no native
+sampler. An older host's unavailable-method response is recorded once in
+developer diagnostics and stops that sampler; genuine bridge failures retain
+their complete diagnostics. See the [current-window contract](core-client.md#current-window-theme)
+for per-field results, cancellation and actual adapter availability.
+
 ### Availability and normalization
 
 **Browser/native hybrid.** Theme state normalized; storage/native errors mixed. Transport: ThemeManager + Arcane.events. [Deep protocol details](protocols.md).

package/docs/reference/sdk-api.md

@@ -6924,13 +6924,17 @@ Import it from `arcane-os/core/client`. The result includes `runtime`, `events`,
 `Error` and the existing `ai`, `environment`, `mail`, `speech`, `localAI`,
 `ollama`, application, platform, storage and other host namespaces.
 
-`facade.speech.synthesize(request, {signal})` accepts an optional `AbortSignal`
-through the same correlated request lifetime. The complete request and existing
-180,000 ms timeout remain unchanged. A pre-aborted signal sends no synthesis
+`facade.speech.synthesize(request, {signal})` and
+`facade.speech.transcribe(request, {signal})` accept an optional `AbortSignal`
+through the same correlated request lifetime. Each complete request and existing
+180,000 ms timeout remain unchanged. A pre-aborted signal sends no speech
 request; an in-flight abort emits that request's `request.cancel`, rejects with
 `ARCANE_REQUEST_ABORTED` and leaves unrelated requests active. Late responses
-cannot settle the cancelled request. Actual native synthesis interruption belongs
-to the registered service and engine; this facade supplies no engine.
+cannot settle the cancelled request. Actual native synthesis or transcription
+interruption belongs to the registered service and engine; this facade supplies
+no engine. The native routes of `AI.fetchTTS(payload, signal)` and
+`AI.fetchSTT(audio, signal)` forward their signals through these calls and
+normalize cancellation to `AbortError` with `ARCANE_AI_REQUEST_ABORTED`.
 
 ### Availability and normalization
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.59.1",
+  "version": "0.60.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -107,8 +107,8 @@
   "scripts": {
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
-    "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-host.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/native-windows-icon.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-host.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/runtime/arcane/modules/ThemeBootstrap.js

@@ -3,11 +3,12 @@ const is=new Is(false);
 
 import { arcaneLogging } from 'arcane-os/logging';
 import {applyUserSkin,loadAndApplyTheme} from './ThemeManager.js';
-import {createArcaneEventSource} from 'arcane-os/event-manager';
+import {arcaneEvents,createArcaneEventSource} from 'arcane-os/event-manager';
 
 const sharedKey='arcaneThemeReady';
 const listenerKey='arcaneThemeAppearanceListener';
 const userListenerKey='arcaneThemeUserListener';
+const windowListenerKey='arcaneThemeWindowListener';
 const THEME_BOOTSTRAP_EVENT_OWNER={};
 let themeBootstrapOperationSequence=0;
 const themeBootstrapEvents=createArcaneEventSource(
@@ -99,11 +100,222 @@ function installUserSkinListener(){
     applyReadyUserSkin();
 }
 
+function installWindowThemeListener(ready){
+    const host=globalThis.Arcane;
+    const document=globalThis.document;
+    if(globalThis[windowListenerKey]||!host?.runtime?.current?.().native
+        ||!is.function(host?.window?.setTheme)||!document?.documentElement) return;
+
+    let active=true;
+    let suspended=false;
+    let scheduled=false;
+    let lastPresentation=null;
+    let pending=null;
+    let observedBody=null;
+    let canvasContext=null;
+    const root=document.documentElement;
+    const scheme=globalThis.matchMedia('(prefers-color-scheme: dark)');
+    const print=globalThis.matchMedia('print');
+    const probe=document.createElement('span');
+    probe.style.setProperty('display','none','important');
+
+    function report(error){
+        arcaneLogging.warn('[Arcane theme] Unable to update the native window colors.',error);
+    }
+    function colorRecord(resolved){
+        // Read the browser's resolved color, not an authored CSS grammar. Keep
+        // its alpha separately so raster conversion cannot round translucency away.
+        const rgb=resolved.match(/^rgba?\(([^)]+)\)$/u);
+        if(rgb){
+            const values=rgb[1].split(/[\s,/]+/u).filter(Boolean).map(Number);
+            if((values.length===3||values.length===4)&&values.every(Number.isFinite)){
+                return {red:values[0],green:values[1],blue:values[2],alpha:values[3]??1};
+            }
+        }
+        const alphaMatch=resolved.match(/\/\s*(none|[-+\d.eE]+%?)\s*\)$/u);
+        const alphaValue=alphaMatch?.[1];
+        const alpha=alphaValue===undefined?1:alphaValue==='none'?0:
+            Number.parseFloat(alphaValue)/(alphaValue.endsWith('%')?100:1);
+        if(!Number.isFinite(alpha)||(resolved.includes('/')&&!alphaMatch)){
+            throw new TypeError(`Unable to read the resolved CSS color: ${resolved}`);
+        }
+        const opaque=alphaMatch?resolved.replace(/\/[^/]*\)$/u,'/ 1)'):resolved;
+        if(!canvasContext){
+            const canvas=document.createElement('canvas');
+            canvas.width=1;
+            canvas.height=1;
+            canvasContext=canvas.getContext(
+                '2d',
+                {colorSpace:'srgb'}
+            );
+            if(!canvasContext) throw new Error('The browser cannot convert the resolved color to sRGB.');
+        }
+        // An unsupported fillStyle assignment leaves the old value intact.
+        // Two different starting values distinguish rejection from a valid black.
+        canvasContext.fillStyle='#000000';
+        canvasContext.fillStyle=opaque;
+        const accepted=canvasContext.fillStyle;
+        canvasContext.fillStyle='#ffffff';
+        canvasContext.fillStyle=opaque;
+        if(canvasContext.fillStyle!==accepted){
+            throw new TypeError(`The browser canvas cannot convert the resolved CSS color: ${resolved}`);
+        }
+        canvasContext.clearRect(0,0,1,1);
+        canvasContext.fillRect(0,0,1,1);
+        const [red,green,blue]=canvasContext.getImageData(0,0,1,1).data;
+        return {red,green,blue,alpha};
+    }
+    function readPresentation(){
+        const target=document.body;
+        if(!target) return {};
+        const styles=globalThis.getComputedStyle(target);
+        const presentation={};
+        target.appendChild(probe);
+        try {
+            const properties=[
+                ['backgroundColor','--background'],
+                ['textColor','--text-color']
+            ];
+            for(const [field,property] of properties){
+                const authored=styles.getPropertyValue(property);
+                if(!authored.trim()) continue;
+                if(!globalThis.CSS.supports('color',authored)){
+                    report(
+                        new TypeError(`The app theme ${property} is not a supported CSS color: ${authored}`)
+                    );
+                    continue;
+                }
+                // Use the target's resolved value: registered properties may
+                // deliberately not inherit into this child resolution element.
+                probe.style.setProperty('color',authored,'important');
+                try {
+                    const resolved=globalThis.getComputedStyle(probe).color;
+                    presentation[field]=colorRecord(resolved);
+                } catch (error) {
+                    report(error);
+                }
+            }
+        } finally {
+            probe.remove();
+        }
+        return presentation;
+    }
+    function samePresentation(next){
+        return lastPresentation&&['backgroundColor','textColor'].every(
+            function sameColor(field){
+                const before=lastPresentation[field];
+                const after=next[field];
+                if(before===after) return true;
+                if(!before||!after) return false;
+                return ['red','green','blue','alpha'].every(
+                    function sameChannel(channel){
+                        return before[channel]===after[channel];
+                    }
+                );
+            }
+        );
+    }
+    function observeElements(){
+        if(observedBody===document.body) return;
+        observer.disconnect();
+        observer.observe(
+            root,
+            {attributes:true,childList:true,attributeFilter:['class','style','data-color-scheme','data-user-skin','data-arcane-skin']}
+        );
+        observedBody=document.body;
+        if(observedBody) observer.observe(
+            observedBody,
+            {attributes:true,attributeFilter:['class','style']}
+        );
+    }
+    function sample(){
+        scheduled=false;
+        if(!active||suspended||print.matches) return;
+        observeElements();
+        const presentation=readPresentation();
+        if(!Object.keys(presentation).length||samePresentation(presentation)) return;
+        lastPresentation=presentation;
+        pending?.abort();
+        const controller=new AbortController();
+        pending=controller;
+        try {
+            const operation=host.window.setTheme(
+                presentation,
+                {signal:controller.signal}
+            );
+            Promise.resolve(operation).catch(
+                function reportWindowFailure(error){
+                    if(error?.code==='ARCANE_REQUEST_ABORTED'||(controller.signal.aborted&&error?.name==='AbortError')) return;
+                    report(error);
+                    if(error?.code==='METHOD_NOT_ALLOWED') dispose();
+                }
+            ).finally(
+                function finishWindowUpdate(){
+                    if(pending===controller) pending=null;
+                }
+            );
+        } catch (error) {
+            if(pending===controller) pending=null;
+            report(error);
+        }
+    }
+    function schedule(){
+        if(!active||suspended||scheduled) return;
+        scheduled=true;
+        Promise.resolve().then(sample).catch(report);
+    }
+    function stylesheetLoaded(event){
+        if(event.target?.tagName==='LINK'&&event.target.relList?.contains('stylesheet')) schedule();
+    }
+    function hide(){
+        suspended=true;
+        pending?.abort();
+    }
+    function show(){
+        suspended=false;
+        lastPresentation=null;
+        schedule();
+    }
+    function dispose(){
+        if(!active) return false;
+        active=false;
+        pending?.abort();
+        observer.disconnect();
+        unsubscribe();
+        scheme.removeEventListener('change',schedule);
+        print.removeEventListener('change',schedule);
+        document.removeEventListener('DOMContentLoaded',schedule);
+        document.removeEventListener('load',stylesheetLoaded,true);
+        globalThis.removeEventListener('pagehide',hide);
+        globalThis.removeEventListener('pageshow',show);
+        canvasContext=null;
+        if(globalThis[windowListenerKey]===dispose) delete globalThis[windowListenerKey];
+        return true;
+    }
+    const observer=new globalThis.MutationObserver(schedule);
+    const unsubscribe=arcaneEvents.subscribe('arcane-theme-change',schedule);
+    observer.observe(
+        root,
+        {attributes:true,childList:true,attributeFilter:['class','style','data-color-scheme','data-user-skin','data-arcane-skin']}
+    );
+    observeElements();
+    scheme.addEventListener('change',schedule);
+    print.addEventListener('change',schedule);
+    document.addEventListener('DOMContentLoaded',schedule);
+    document.addEventListener('load',stylesheetLoaded,true);
+    globalThis.addEventListener('pagehide',hide);
+    globalThis.addEventListener('pageshow',show);
+    globalThis[windowListenerKey]=dispose;
+    schedule();
+    Promise.resolve(ready).then(schedule).catch(report);
+}
+
 export function bootstrapArcaneTheme(options={}){
     const useSharedPromise=Object.keys(options).length===0;
     if(useSharedPromise&&globalThis[sharedKey]){
         installAppearanceListener(globalThis[sharedKey]);
         installUserSkinListener();
+        installWindowThemeListener(globalThis[sharedKey]);
         return globalThis[sharedKey];
     }
 
@@ -116,6 +328,7 @@ export function bootstrapArcaneTheme(options={}){
     if(useSharedPromise){
         installAppearanceListener(ready);
         installUserSkinListener();
+        installWindowThemeListener(ready);
     }
     return ready;
 }
@@ -123,9 +336,11 @@ export function bootstrapArcaneTheme(options={}){
 export function disposeArcaneThemeBootstrap(){
     const dispose=globalThis[listenerKey];
     const disposeUser=globalThis[userListenerKey];
+    const disposeWindow=globalThis[windowListenerKey];
     const appearanceDisposed=is.function(dispose)?dispose():false;
     const userDisposed=is.function(disposeUser)?disposeUser():false;
-    return appearanceDisposed||userDisposed;
+    const windowDisposed=is.function(disposeWindow)?disposeWindow():false;
+    return appearanceDisposed||userDisposed||windowDisposed;
 }
 
 export const arcaneThemeReady=bootstrapArcaneTheme();