arcane-os 0.59.0 → 0.60.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.60.0
+
+- Add `Arcane.window.setTheme(presentation, {signal})` for the current native
+  window. Optional sRGB RGBA background/text colors, null resets and omitted
+  fields retain their explicit semantics; results distinguish accepted and
+  unsupported fields. This does not change system-wide appearance.
+- Forward application-computed theme colors without blocking rendering.
+  Observe existing theme and page lifecycles, cancel superseded requests, and
+  preserve ordinary browser behavior and native window controls.
+- Apply app-owned Windows icons to the window/taskbar and copied executable.
+  Portable Node assembly handles PNG/ICO resources without an application
+  compiler, preserving source images and other executable resources. Other
+  formats retain assembly with an explicit unsupported-branding diagnostic.
+- Windows caption/text colors use the host's supported per-window DWM
+  attributes. Using the new Windows behavior requires the matching host asset;
+  platform acceptance is reported rather than inferred from a request.
+- Include completed internal PNG-decoding and stored-model working-file
+  preparation primitives. Image-service registration and engine integration
+  remain separate work; this release does not claim app-ready image generation.
+
+## 0.59.1
+
+- Forward the existing AI synthesis signal into native Core synthesis and
+  preserve the established AI cancellation error contract.
+- Carry `AI.fetchSTT(audio, signal)` cancellation through
+  `Arcane.speech.transcribe(request, {signal})` into the existing Core request
+  lifetime. Preserve complete requests and results, one-argument facade calls,
+  unrelated errors and the 180-second timeout. Actual inference interruption
+  and resource release remain with the selected speech service.
+- No speech engine, model, runtime dependency, default-provider switch or data
+  migration is introduced.
+
 ## 0.59.0
 
 - Reconcile marked generated PWA references when a root application's PWA is

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.59.0` SDK contract. Development applications declare
+This checkout defines the `0.60.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/browser-runtime/ai/core-model-assets.mjs

@@ -0,0 +1,152 @@
+import Is from '../dependencies/strong-type/index.js';
+import {getInstalledCoreClient} from '../core/client.mjs';
+
+const is = new Is(false);
+
+/** Projects complete caller-owned assets through Core without changing their store. */
+export async function prepareCoreModelAssets({
+    client = getInstalledCoreClient(), workingDirectory, members, signal, onProgress
+} = {}) {
+    if (!is.function(client?.invoke) || !is.function(client?.uuid)) {
+        const error = new Error('Native model assets require an available Core connection.');
+        error.code = 'ARCANE_MODEL_ASSETS_CORE_UNAVAILABLE';
+        throw error;
+    }
+    if (!is.string(workingDirectory) || workingDirectory === '') {
+        throw new TypeError('Model asset workingDirectory must be a nonempty string.');
+    }
+    if (!is.array(members) || members.length === 0) {
+        throw new TypeError('Model assets require at least one complete file.');
+    }
+    for (const member of members) {
+        if (!is.string(member?.path) || member.path === '' || !is.function(member?.file?.stream)) {
+            throw new TypeError('Each model asset requires a path and a complete Blob or File.');
+        }
+    }
+    if (onProgress !== undefined && !is.function(onProgress)) {
+        throw new TypeError('Model asset onProgress must be a function.');
+    }
+
+    const controller = new AbortController();
+    const operationSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    operationSignal.throwIfAborted();
+    const id = client.uuid();
+    const cleanupErrors = [];
+    let completed = 0;
+    let openingStarted = false;
+    let failed = false;
+    let failure;
+    let releaseTask;
+
+    function retainFailure(error) {
+        if (failed) return;
+        failed = true;
+        failure = error;
+        controller.abort(error);
+    }
+
+    function progress(phase, memberIndex) {
+        operationSignal.throwIfAborted();
+        onProgress?.({
+            phase, completed, total: members.length, unit: 'files',
+            ...(memberIndex === undefined ? {} : {memberIndex, path: members[memberIndex].path})
+        });
+    }
+
+    function release() {
+        releaseTask ??= Promise.resolve().then(function releaseNativeProjection() {
+            return client.invoke('modelAssets.release', {id}, {timeoutMs: 0});
+        });
+        return releaseTask;
+    }
+
+    async function transferMember(member, memberIndex) {
+        let reader;
+        let cancellation;
+
+        function cancelReader() {
+            if (!reader || cancellation) return;
+            cancellation = Promise.resolve().then(function cancelMemberStream() {
+                return reader.cancel(operationSignal.reason);
+            }).catch(function retainReaderCleanupFailure(error) {
+                cleanupErrors.push(error);
+            });
+        }
+
+        try {
+            operationSignal.throwIfAborted();
+            reader = member.file.stream().getReader();
+            operationSignal.addEventListener('abort', cancelReader, {once: true});
+            if (operationSignal.aborted) cancelReader();
+            progress('write', memberIndex);
+            while (true) {
+                operationSignal.throwIfAborted();
+                const {done, value} = await reader.read();
+                operationSignal.throwIfAborted();
+                if (done) break;
+                // Base64 belongs only to the existing JSON transport boundary.
+                const contentBase64 = encodeChunk(value);
+                await client.invoke('modelAssets.write', {id, memberIndex, contentBase64}, {
+                    signal: operationSignal, timeoutMs: 0
+                });
+                progress('write', memberIndex);
+            }
+            completed += 1;
+            progress('write', memberIndex);
+        } catch (error) {
+            retainFailure(error);
+            throw error;
+        } finally {
+            operationSignal.removeEventListener('abort', cancelReader);
+            if (operationSignal.aborted) cancelReader();
+            if (cancellation) await cancellation;
+            try { reader?.releaseLock(); } catch (error) {
+                if (failed) cleanupErrors.push(error);
+                else retainFailure(error);
+            }
+        }
+    }
+
+    try {
+        progress('open');
+        openingStarted = true;
+        await client.invoke('modelAssets.open', {
+            id, workingDirectory,
+            members: members.map(function describeMember(member) { return {path: member.path}; })
+        }, {signal: operationSignal, timeoutMs: 0});
+        operationSignal.throwIfAborted();
+        const results = await Promise.allSettled(members.map(transferMember));
+        for (const result of results) {
+            if (result.status === 'rejected') retainFailure(result.reason);
+        }
+        if (failed) throw failure;
+        if (cleanupErrors.length) {
+            throw new AggregateError(cleanupErrors.splice(0), 'Model asset streams could not be released.');
+        }
+        progress('complete');
+        const projection = await client.invoke('modelAssets.complete', {id}, {
+            signal: operationSignal, timeoutMs: 0
+        });
+        progress('ready');
+        operationSignal.throwIfAborted();
+        // The caller releases ownership after native consumers retain this projection.
+        return {id, directory: projection.directory, members: projection.members, release};
+    } catch (error) {
+        retainFailure(error);
+        if (openingStarted) {
+            try { await release(); } catch (cleanupError) { cleanupErrors.push(cleanupError); }
+        }
+        if (cleanupErrors.length) {
+            throw new AggregateError([failure, ...cleanupErrors],
+                'Model asset preparation and cleanup failed.', {cause: failure});
+        }
+        throw failure;
+    }
+}
+
+function encodeChunk(content) {
+    if (is.function(content.toBase64)) return content.toBase64();
+    let binary = '';
+    for (const value of content) binary += String.fromCharCode(value);
+    return btoa(binary);
+}

package/browser-runtime/core/client.mjs

@@ -569,7 +569,7 @@ export function createCoreFacade(client){
         mail:{send:request=>invoke('mail.send',request??{},{timeoutMs:450000})},
         speech:{status:()=>invoke('speech.status',{},{timeoutMs:10000}),
             synthesize:(request,options)=>invoke('speech.synthesize',request??{},{timeoutMs:180000,signal:options?.signal}),
-            transcribe:request=>invoke('speech.transcribe',request??{},{timeoutMs:180000})},
+            transcribe:(request,options)=>invoke('speech.transcribe',request??{},{timeoutMs:180000,signal:options?.signal})},
         localAI:{status:()=>invoke('localai.status',{},{timeoutMs:15000}),
             ensurePlatform:()=>invoke('localai.platform.ensure',{},long),recover:request=>invoke('localai.services.recover',request??{},long),
             setParallelRequests:request=>invoke('localai.parallel.requests.set',request??{},long),
@@ -616,6 +616,14 @@ export function createCoreFacade(client){
         storage:{list:()=>invoke('storage.list'),get:key=>invoke('storage.get',{key}),set:(key,value)=>invoke('storage.set',{key,value}),delete:key=>invoke('storage.delete',{key})},
         preferences:{list:()=>invoke('preferences.list'),get:key=>invoke('preferences.get',{key}),set:(key,value)=>invoke('preferences.set',{key,value}),
             setMany:entries=>invoke('preferences.setMany',{entries}),delete:key=>invoke('preferences.delete',{key})},
+        window: {
+            setTheme(presentation, options) {
+                return invoke(
+                    'window.setTheme', presentation,
+                    {signal: options?.signal}
+                );
+            }
+        },
         appearance:{current:()=>invoke('appearance.current'),apply:appearance=>invoke('appearance.apply',appearance??{})},session:{logout:()=>invoke('session.logout')},
         provisioning:{plan:usernames=>invoke('provisioning.plan',{usernames:Array.isArray(usernames)?usernames:[usernames].filter(Boolean)})},
         diagnostics:{recentErrors:()=>invoke('diagnostics.recent'),get:diagnosticId=>invoke('diagnostics.get',{diagnosticId})},

package/browser-runtime/core/contracts.mjs

@@ -32,6 +32,11 @@ export const CORE_METHOD_CONTRACTS={
     'preferences.set':{input:'{key,value}',output:'{key,value}'},
     'preferences.setMany':{input:'{entries}',output:'preference-batch-result'},
     'preferences.delete':{input:'{key}',output:'{key,deleted}'},
+    'window.setTheme': {
+        input: '{backgroundColor?,textColor?}: null reset or {red,green,blue,alpha}',
+        output: '{platform,supported,applied,unsupported}',
+        meaning: 'Current host window only. Omitted colors stay unchanged; applied records platform-accepted values, not measured pixels or an atomic operation.'
+    },
     'terminal.start':{input:'terminal-start-v1',output:'terminal-session-v1'},
     'terminal.list':{input:'empty-object-v1',output:'terminal-list-v1'},
     'terminal.write':{input:'terminal-write-v1',output:'terminal-write-result-v1'},

package/docs/reference/README.md

@@ -42,6 +42,7 @@ alone does not make bare module names resolve in a browser.
 | Inspect complete AI and speech calls using the shared developer-mode preference | [Shared logger](sdk-api.md#arcanelogging) and [speech developer diagnostics](ai/browser-speech.md#developer-diagnostics) |
 | Use the `arcane` command | [CLI reference](cli.md) |
 | Install an app and cache selected resources offline | [Progressive web applications](pwa.md) |
+| Disable source PWA generation or explicitly retire confirmed generated output | [Source PWA retirement](pwa.md#disable-source-pwa-generation-and-retire-generated-output) |
 | Generate named browser imports or inspect the selected physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
 | Connect an application through the shared WebSocket transport | [Shared WebSocket clients](websocket-client.md) |
 | Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |
@@ -51,12 +52,14 @@ alone does not make bare module names resolve in a browser.
 | Submit complete speech parts immediately and play them in order | [`SpeechPlayback`](runtime-modules.md#speechplaybackjs) and the [basic browser example](ai/browser-speech.md#play-a-complete-array-with-speechplayback) |
 | Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
 | Connect a browser to one Core transport | [Core browser client](core-client.md) |
+| Cancel one Core speech synthesis request without changing its payload | [Speech request lifetime](core-client.md#events-and-request-lifetime) and [Core facade](sdk-api.md#createcorefacade) |
 | Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
 | Run application-selected llama.cpp, Ollama or ONNX through Core | [Local AI through Core](local-ai.md) |
 | Retain a Nemotron model and diarize caller-fed audio streams | [Native speaker diarization](diarization.md) |
 | Persist application-selected preferences through Core | [Core preferences service](core-preferences.md) |
 | Read complete selected Git text without changing a checkout | [Git text snapshots](git-text-snapshot.md) |
 | Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
+| Pass host-selected state defaults and unchanged explicit launch values to services | [Launch-time locations](core-native-packaging.md#launch-time-locations) |
 | Build a Windows executable without an OS checkout | [Windows executable packaging](core-native-packaging.md#windows-executable) |
 | Compose a Mac application with an architecture-matched host | [macOS application composition](core-native-packaging.md#macos-application-composition) |
 | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |

package/docs/reference/core/arcane-ai-contracts.md

@@ -542,7 +542,7 @@ validate the speech health response.
 
 ### Speech synthesis request
 
-`Arcane.speech.synthesize(request)` accepts the portable
+`Arcane.speech.synthesize(request, options?)` accepts the portable
 `SpeechSynthesisRequest` fields below. Supply the documented primitive types and
 lowercase values; do not rely on host-specific coercion or empty-string
 defaulting.
@@ -555,6 +555,22 @@ defaulting.
 | `responseFormat` | `"opus" \| "wav"` | No | Default `"opus"` | Audio format. |
 | `speed` | `number` | No | Default `1`; 0.5-2 inclusive | Speaking speed. |
 
+### Speech synthesis controls
+
+The optional second argument is `SpeechSynthesisControls`:
+
+| Field | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `signal` | `AbortSignal` | No | No caller signal | Cancels this request through Core, separately from the complete synthesis payload. The registered service owns actual engine interruption. |
+
+Existing one-argument calls retain their behavior and the 180-second timeout.
+A pre-aborted signal dispatches no request. An in-flight abort sends
+`request.cancel`, rejects with `ARCANE_REQUEST_ABORTED` and suppresses late
+responses while unrelated requests continue. Other controls properties are
+unused and do not enter the payload. `AI.fetchTTS(payload, signal)` forwards
+the signal into this native call and reports cancellation as `AbortError` with
+`ARCANE_AI_REQUEST_ABORTED`.
+
 ### Speech synthesis result
 
 | Field | Type | Required | Constraints / default | Description |
@@ -564,7 +580,7 @@ defaulting.
 
 ### Speech transcription request
 
-`Arcane.speech.transcribe(request)` accepts an exact
+`Arcane.speech.transcribe(request, options?)` accepts an exact
 `SpeechTranscriptionRequest`.
 
 | Field | Type | Required | Constraints / default | Description |
@@ -573,6 +589,19 @@ defaulting.
 | `mimeType` | `string` | No | Default `"audio/webm"`; base type must be `audio/webm` | Media type; codec parameters may follow. |
 | `model` | `string` | No | Default `"whisper-small"`; `whisper(?:[._-][a-z0-9]+)*` | Whisper identifier. The fixed service rejects unsupported variants. |
 
+### Speech transcription controls
+
+The optional second argument is `SpeechTranscriptionControls`:
+
+| Field | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `signal` | `AbortSignal` | No | No caller signal | Cancels this request through Core. The facade forwards it separately from the complete audio request; the registered service owns actual engine interruption. |
+
+Existing one-argument calls retain their behavior. The facade's request timeout
+remains 180 seconds. A pre-aborted signal dispatches no request, and an
+in-flight abort cancels the request and suppresses late responses. Other
+properties of this controls record are unused; they do not enter the payload.
+
 ### Speech transcription result
 
 | Field | Type | Required | Constraints / default | Description |

package/docs/reference/core/arcane-api.md

@@ -48,6 +48,7 @@ This inventory covers every enumerable, non-method member exposed directly or th
 | `Arcane.filesystem` | Namespace | Native filesystem selection operations. |
 | `Arcane.storage` | Namespace | App-scoped native key/value storage. |
 | `Arcane.preferences` | Namespace | App-scoped preference reads and atomic writes. |
+| `Arcane.window` | Namespace | SDK host window presentation for the calling document; adapter availability is independent of the OS-user appearance service. |
 | `Arcane.appearance` | Namespace | Native appearance state and application. |
 | `Arcane.session` | Namespace | Current Arcane session lifecycle. |
 | `Arcane.provisioning` | Namespace | Provisioning-plan operations. |
@@ -104,8 +105,8 @@ directly.
 | `Arcane.localAI.recover(request)` | `request`: [`LocalAIRecoveryRequest`](arcane-ai-contracts.md#local-ai-recovery-request) | [`Promise<LocalAIRecoveryResult>`](arcane-ai-contracts.md#local-ai-recovery-result) | Requests one privileged, exclusive, start-existing-service-only recovery of selected Arcane-managed local services. Requires `ai.inference` and explicit application admission. |
 | `Arcane.localAI.setParallelRequests(request)` | `request`: [`LocalAIParallelRequestsRequest`](arcane-ai-contracts.md#local-ai-parallel-request-configuration) | [`Promise<LocalAIParallelRequestsResult>`](arcane-ai-contracts.md#local-ai-parallel-request-configuration) | Solves one app-owned verified model/context's maximum directly from native model and memory/resource evidence without a product ceiling, clamps a positive request to that result (`0` requests the maximum), and changes the machine-wide managed Ollama setting only when needed. A tentative change uses one fresh stopped-service snapshot before the final value is written, then Core ensures, loads, and confirms the exact model. A restart unloads resident models. Automatic mutation currently requires the dedicated `ai.runtime.manage` capability on Microsoft NT desktop Core and operating-system authorization; Linux returns administrator-managed systemd guidance, and Android user-managed loopback sessions do not invoke it. |
 | `Arcane.speech.status()` | None | [`Promise<SpeechStatus>`](arcane-ai-contracts.md#speech-status) | Reads bounded, independent Kokoro and Whisper readiness through Core or an admitted Android native host. Requires `ai.inference`. |
-| `Arcane.speech.synthesize(request)` | `request`: [`SpeechSynthesisRequest`](arcane-ai-contracts.md#speech-synthesis-request) | [`Promise<SpeechSynthesisResult>`](arcane-ai-contracts.md#speech-synthesis-result) | Synthesizes bounded local speech through the native host and fixed loopback runtime. Requires `ai.inference`. |
-| `Arcane.speech.transcribe(request)` | `request`: [`SpeechTranscriptionRequest`](arcane-ai-contracts.md#speech-transcription-request) | [`Promise<SpeechTranscriptionResult>`](arcane-ai-contracts.md#speech-transcription-result) | Sends bounded canonical base64 bytes labeled `audio/webm` to local Whisper through the native host. The bridge validates encoding, label, and bounds; the fixed service parses the media container. Requires `ai.inference`. |
+| `Arcane.speech.synthesize(request, options?)` | `request`: [`SpeechSynthesisRequest`](arcane-ai-contracts.md#speech-synthesis-request); `options?`: [`SpeechSynthesisControls`](arcane-ai-contracts.md#speech-synthesis-controls) | [`Promise<SpeechSynthesisResult>`](arcane-ai-contracts.md#speech-synthesis-result) | Sends the complete request to the selected native synthesis service; optional cancellation reaches Core's request lifetime. The registered host service owns audio generation and actual engine interruption. |
+| `Arcane.speech.transcribe(request, options?)` | `request`: [`SpeechTranscriptionRequest`](arcane-ai-contracts.md#speech-transcription-request); `options?`: [`SpeechTranscriptionControls`](arcane-ai-contracts.md#speech-transcription-controls) | [`Promise<SpeechTranscriptionResult>`](arcane-ai-contracts.md#speech-transcription-result) | Sends the complete request to the selected native transcription service; optional cancellation reaches Core's request lifetime. The registered host service owns media decoding and actual engine interruption. |
 | `Arcane.ollama.version()` | None | [`Promise<OllamaVersionResponse>`](arcane-ai-contracts.md#ollama-provider-responses) | Gets the managed Ollama version for Settings, Terminal, and Shell diagnostics. |
 | `Arcane.ollama.models()` | None | [`Promise<OllamaModelsResponse>`](arcane-ai-contracts.md#ollama-provider-responses) | Lists the raw provider inventory envelope; it is not the application admission catalog. |
 | `Arcane.ollama.list()` | None | [`Promise<OllamaModelsResponse>`](arcane-ai-contracts.md#ollama-provider-responses) | Alias of the raw `models()` inventory. |
@@ -438,6 +439,16 @@ The canonical authority registry in `machine_bundles/arcane-os-machine-bundle/sr
 
 ## Filesystem, storage, preferences, and appearance
 
+The SDK's additive `Arcane.window.setTheme(presentation, {signal}?)` controls
+the current host window's `backgroundColor` and `textColor`, with per-field
+accepted/unsupported results. See the [window contract](../core-client.md#current-window-theme)
+for numeric RGBA, reset, cancellation, navigation and platform availability.
+It does not call the OS-user `appearance.apply` service described below.
+
+| SDK window method | Parameters | Return | Description |
+|---|---|---|---|
+| `Arcane.window.setTheme(presentation, options?)` | Optional `backgroundColor`/`textColor`: `{red,green,blue,alpha}` or `null`; `options.signal?` | `Promise<{platform,supported,applied,unsupported}>` | Applies supported colors only to the caller's native window, preserving omitted fields. Uses ordinary request cancellation and reports actual per-field acceptance. See the linked contract for adapter availability. |
+
 | Method | Parameters | Return | Description |
 |---|---|---|---|
 | `Arcane.filesystem.selectDirectory(options?)` | `options?`: `{title?, initialPath?}`; title up to 200 plain-text characters; initial path must be an existing absolute directory | `Promise<{cancelled:boolean, path:string\|null}>` | Opens the native directory picker after a user action. It returns one canonical existing directory or explicit cancellation; it does not enumerate or grant access to directory contents. Requires `filesystem.directory.select`. |

package/docs/reference/core/reference/arcane-api/ai-and-ollama.md

@@ -646,7 +646,7 @@ console.info({
 
 ### Overview
 
-`Arcane.speech.synthesize(request)` converts bounded text to local speech. Use
+`Arcane.speech.synthesize(request, options?)` converts bounded text to local speech. Use
 it only after checking synthesis readiness, and create an audio URL from the
 returned bytes without logging the base64 payload.
 
@@ -683,27 +683,36 @@ owned active operation before retrying.
 ### Streaming, cancellation, and events
 
 Synthesis returns one complete audio result and emits no method event. The
-wrapper timeout is 180 seconds, no signal is exposed, and timeout or page
-teardown does not promise cancellation of Core or Android speech work.
+wrapper timeout remains 180 seconds. Optional `{signal}` controls the Core
+request lifetime separately from the complete synthesis payload. Pre-abort
+sends no request; in-flight abort sends `request.cancel`, rejects with
+`ARCANE_REQUEST_ABORTED` and suppresses late responses. Unrelated requests
+continue. The registered native service owns actual synthesis interruption and
+resource release; the facade supplies no engine. `AI.fetchTTS(payload, signal)`
+forwards its signal through this call and normalizes cancellation to
+`AbortError` with `ARCANE_AI_REQUEST_ABORTED`.
 
 ### Example
 
 ```javascript
-const result = await globalThis.Arcane.speech.synthesize({
-    input: 'Your local speech service is ready.',
-    voice: 'af_heart',
-    responseFormat: 'opus',
-    speed: 1
-});
-
-console.info(result.contentType, result.audioBase64.length);
+async function synthesizeMoonEncore(input, signal) {
+    return globalThis.Arcane.speech.synthesize(
+        {
+            input,
+            voice: 'af_heart',
+            responseFormat: 'opus',
+            speed: 1
+        },
+        {signal}
+    );
+}
 ```
 
 ## Arcane.speech.transcribe()
 
 ### Overview
 
-`Arcane.speech.transcribe(request)` sends bounded caller-supplied audio bytes,
+`Arcane.speech.transcribe(request, options?)` sends bounded caller-supplied audio bytes,
 labeled as WebM, to the fixed local transcription service. Use it after local
 capture permission and recording have succeeded; the method itself does not
 capture audio or grant microphone permission.
@@ -739,18 +748,21 @@ work after `ANDROID_SPEECH_QUEUE_FULL`.
 ### Streaming, cancellation, and events
 
 Transcription resolves one complete text result and emits no method event. The
-wrapper timeout is 180 seconds and no signal is exposed. Core and Android do
-not promise cancellation when the renderer stops waiting.
+wrapper timeout remains 180 seconds. Optional `{signal}` controls the Core
+request lifetime separately from the complete audio payload. Pre-abort sends
+no request; in-flight abort cancels that request and suppresses late responses.
+The registered native service owns actual inference interruption and resource
+release. `AI.fetchSTT(audio, signal)` forwards its signal through this call.
 
 ### Example
 
 ```javascript
-async function transcribeRecordedWebM(audioBase64) {
+async function transcribeRecordedWebM(audioBase64, signal) {
     const result = await globalThis.Arcane.speech.transcribe({
         audioBase64: audioBase64,
         mimeType: 'audio/webm',
         model: 'whisper-small'
-    });
+    }, {signal});
     return result.text;
 }
 ```

package/docs/reference/core/reference/arcane-api/namespaces.md

@@ -1038,6 +1038,20 @@ const canReadPreferences = access.methods.includes('preferences.list');
 console.log('Preference inventory admitted:', canReadPreferences);
 ```
 
+## Arcane.window
+
+The SDK client exposes `Arcane.window.setTheme(presentation, {signal}?)` for
+the window hosting the calling document. The optional `backgroundColor` and
+`textColor` accept numeric RGBA records or `null` for platform-default reset.
+The host reports each applied or unsupported field independently. Rendering
+and browser theme changes continue without waiting for this request.
+
+Shared ThemeBootstrap forwards the app's computed semantic colors through
+this method when a native host is present. It does not change OS-user
+appearance. See the [current-window contract](../../../core-client.md#current-window-theme)
+for complete usage, accepted channel values, cancellation and current adapter
+availability. A facade method alone does not establish host support.
+
 ## Arcane.appearance
 
 ### Overview

package/docs/reference/core-client.md

@@ -83,6 +83,80 @@ the 180,000 ms timeout and pass the complete request unchanged. A pre-aborted
 signal sends no synthesis request; an in-flight abort sends `request.cancel`
 and suppresses late responses. Actual synthesis interruption depends on the
 registered speech service and its engine; the facade supplies no speech engine.
+`AI.fetchTTS(payload, signal)` carries its caller-owned signal into this native
+call and normalizes cancellation to `AbortError` with
+`ARCANE_AI_REQUEST_ABORTED`, preserving the original error as its cause.
+
+`Arcane.speech.transcribe(request, {signal})` forwards cancellation through the
+same request lifetime and retains its 180,000 ms timeout and complete request.
+`AI.fetchSTT(audio, signal)` carries that signal into the native call. A
+pre-aborted signal sends no transcription request; an in-flight abort sends
+`request.cancel` and suppresses late responses. The registered transcription
+service owns interruption and release of its actual engine operation.
+
+## Current-window theme
+
+`Arcane.window.setTheme(presentation, {signal}?)` changes only the window
+hosting the calling document. It uses the existing `window.setTheme` request
+and response correlation; it neither calls `appearance.apply` nor changes the
+operating-system user's appearance. The complete presentation object reaches
+the host unchanged.
+
+Each optional `backgroundColor` and `textColor` is either `null` to restore the
+platform default or `{red, green, blue, alpha}`. All four channels are numbers:
+finite sRGB red/green/blue from 0 through 255 and alpha from 0 through 1.
+Omitting a field leaves its current value unchanged. There is no scheme field.
+
+```js
+const host=globalThis.Arcane;
+if(host?.runtime?.current().native&&host.window?.setTheme){
+    host.window.setTheme(
+        {
+            backgroundColor:{red:29,green:22,blue:19,alpha:1},
+            textColor:{red:248,green:239,blue:229,alpha:1}
+        }
+    ).then(
+        function reportWindowColors(result){
+            console.log('Moon observatory window colors:',result);
+        }
+    ).catch(
+        function reportWindowFailure(error){
+            console.error('Window color update failed.',error);
+        }
+    );
+}
+// Page rendering continues independently of the host request.
+```
+
+The result is `{platform, supported, applied, unsupported}`. `applied` contains
+only requested fields the platform accepted in this call, including `null`
+for an accepted default reset. `unsupported` lists requested fields the adapter
+cannot apply. `supported` is true when at least one field was applied. These
+are accepted settings, not measured pixels, and the operation is not atomic.
+Malformed arguments reject with `INVALID_ARGUMENT`; native API failures reject
+with `ARCANE_WINDOW_THEME_FAILED`, preserving the native error and
+`details.applied`/`details.unsupported` for earlier results in this call.
+
+The Windows host maps background/text to DWM caption/text attributes supported
+on Windows 11 build 22000 and later, retaining normal system window controls.
+It rounds RGB channels to the nearest integer, with midpoint values rounded
+up, and returns those actual accepted values. Translucent colors remain
+unsupported without changing the existing field. Older Windows reports those
+fields unsupported. This contract makes no promise about caption-button colors.
+The current macOS and Linux hosts have no implementation of this method;
+their ordinary unavailable-method response remains observable. A new facade
+alone does not add the operation to an older native executable. Use the
+matching published host artifact for the selected SDK version.
+
+Cancellation uses the normal request lifetime and suppresses late responses;
+it does not roll back a setting the host already accepted. Window settings
+survive document navigation until a subsequent document changes them or the
+window closes. Responses belong to their originating document.
+
+The shared [ThemeBootstrap](runtime-modules.md#themebootstrapjs) automatically
+forwards the app's computed `--background` and `--text-color` in native hosts.
+Applications using that owner need no duplicate theme listener. Ordinary
+browsers keep their CSS presentation without making a native request.
 
 ## Events and request lifetime
 

package/docs/reference/core-native-packaging.md

@@ -303,6 +303,70 @@ observes complete diagnostics and exit. Cancelling that operation closes its
 input, allowing the window and accepted Core service work to drain without a
 forced process termination.
 
+### Application icon and window colors
+
+`appDescriptor.native.icon` selects the application's existing app-relative
+image. Windows assembly converts PNG images, including a 512-pixel source,
+into a derived `runtime/arcane-app.ico` with 16, 32, 48 and 256-pixel images.
+Aspect ratio and transparency are preserved. An ICO selection keeps its
+authored image set. The original application asset remains unchanged.
+
+The provider embeds the selected images in the copied `Arcane.exe` and records
+`manifest.host.icon` and `manifest.host.executableIcon:true`. It replaces the
+executable's main icon group while preserving other groups, languages, resources
+and file content. Conversion uses Node standard capabilities on every assembly
+platform; it adds no application compiler, image library or Windows-only build
+step. The selected host cache and Core executable remain unchanged.
+
+JPEG/JPG, WebP and other existing descriptor formats retain ordinary assembly.
+They currently report `native.icon.unsupported` through the builder's `onEvent`
+callback, as does a selected executable whose PE layout cannot accommodate the
+derived icon. The event identifies the app, icon, target, code and complete
+message; `manifest.host.executableIcon:false` reports that the executable keeps
+its prior icon. `host.icon` then points to the original selected image. This is
+an explicit unsupported branding result, not a claim that a generic icon was
+replaced. Unreadable files and malformed supported image data report their
+ordinary filesystem or image-parser error.
+
+The matching Windows launcher reads `host.icon` and loads it independently of
+Core and page startup. ICO and standard Windows image codecs supply the window
+and taskbar icon; JPEG/JPG can therefore work at runtime even while executable
+embedding is unsupported. WebP is outside the host's standard image codecs;
+runtime support is not promised. A runtime icon error preserves ordinary startup
+and reaches complete developer diagnostics as `ARCANE_WINDOW_ICON_UNAVAILABLE`.
+Hosts built before this option was introduced do not read the new icon field.
+
+`Arcane.window.setTheme(presentation,{signal}?)` changes only the requesting
+native window's chrome. The shared ThemeBootstrap supplies computed application
+background and text colors without delaying application CSS or rendering.
+Direct callers may supply `backgroundColor` and `textColor`, each either
+`{red,green,blue,alpha}` or `null` to restore the platform default. RGB channels
+are finite numbers from 0 through 255 and alpha is from 0 through 1. Omitted
+fields remain unchanged. The complete presentation follows the existing Core
+request transport; the window host handles `window.setTheme` before forwarding
+other methods to Core. No system appearance setting changes.
+
+Windows 11 build 22000 and later support titlebar background and text colors
+through DWM. The normal titlebar and window controls remain in place. DWM accepts
+opaque colors, so alpha values other than exactly 1 report that field as
+unsupported. RGB values round to the nearest integer, with midpoint values
+rounded upward. Older Windows versions report the requested fields unsupported.
+
+The result is `{platform:'windows',supported,applied,unsupported}`. `applied`
+contains only fields accepted during that call, including rounded channels or
+`null` for a successful default reset. `supported` is true when at least one
+field applied; `unsupported` lists requested fields the platform could not
+apply. These results report platform acceptance rather than measured pixels.
+An invalid argument uses `INVALID_ARGUMENT`; a platform API failure uses
+`ARCANE_WINDOW_THEME_FAILED`, preserving complete native details and any
+earlier changes in `error.details.applied` and `error.details.unsupported`.
+The call is not atomic across fields. Existing request cancellation and document
+lifetime semantics remain in effect; an already accepted native color change
+is not rolled back by later cancellation. See [the Core client](core-client.md)
+for the facade and browser behavior.
+
+### Launch configuration
+
 For explicit user-selected workspace/state locations, launch:
 
 ```sh
@@ -331,8 +395,8 @@ exit. It does not kill the child on an ordinary close.
 `ArcaneHost.cs` composes that process with a WebView2 window through
 `ArcaneHost.Run(options,onDiagnostic,onError)` or `ArcaneHostForm`. Options
 select the app root/start path, stable virtual HTTPS origin, profile directory,
-title, canonical classic-client source and Core process inputs. The form exposes
-`Ready`, `Completion` and `CloseAsync()`. Page navigation, transport connection,
+title, optional `IconPath`, canonical classic-client source and Core process
+inputs. The form exposes `Ready`, `Completion` and `CloseAsync()`. Page navigation, transport connection,
 Core readiness and service readiness are separate states. Accepted work drains
 before the window closes; complete engineering errors go to the supplied
 diagnostic/error callbacks. Callbacks must not synchronously wait for the