arcane-os 0.59.1 → 0.61.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.61.0
+
+- Add retained local image generation through Core, with public native runtime,
+  Core service and browser accessor entrypoints. Applications keep ownership of
+  prompts, styles, saved images and associations.
+- Select the approved stable-diffusion.cpp runtime and Stable Diffusion 1.4
+  checkpoint through existing local-AI configuration. Runtime installation and
+  model storage/preparation remain separate; model setup uses the existing
+  DBOPFS model store and a retained Core working-file projection.
+- Preserve complete prompts and PNG results, synchronous transient Thinking
+  acknowledgement, observable model state and progress, actual cancellation
+  joining, and native context/file cleanup. Preparation does not block page
+  rendering or unrelated Core services.
+- Expose model-assets preparation and service entrypoints alongside image
+  generation. Native contexts retain working files until actual unload; the
+  browser accessor closes only its own requests and subscriptions.
+- Built-in distributions select CPU on Windows and Linux and the same upstream
+  Metal/CPU archive on macOS. Windows CUDA preparation remains separate pending
+  work; publication does not claim GPU-first Windows or PM execution.
+- Keep optional engine/binding acquisition in the selected application's
+  existing installer workflow. No engine binaries or model checkpoint are added
+  to the npm package, and its declared dependency tree is unchanged.
+
+## 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

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.1` SDK contract. Development applications declare
+This checkout defines the `0.61.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-image.mjs

@@ -0,0 +1,360 @@
+import Is from '../dependencies/strong-type/index.js';
+import {getInstalledCoreClient} from '../core/client.mjs';
+import {CoreError, serializeCoreError} from '../core/contracts.mjs';
+import {createArcaneEventSource} from '../event-manager.mjs';
+
+const is = new Is(false);
+
+function unavailable(message) {
+    return new CoreError(
+        {code: 'ARCANE_IMAGE_CORE_UNAVAILABLE', message}
+    );
+}
+
+/** Decode the complete JSON transport representation without retaining it. */
+function decodeImage(image) {
+    const {data, encoding, ...metadata} = image;
+    if (encoding !== 'base64') {
+        throw new TypeError('Core image results require base64 transport encoding.');
+    }
+    const decoded = Uint8Array.from(
+        globalThis.atob(data),
+        function decodeImageCharacter(character) {
+            return character.charCodeAt(0);
+        }
+    );
+    const blob = new Blob(
+        [decoded],
+        {type: metadata.mediaType}
+    );
+    return {...metadata, blob};
+}
+
+/** Browser access to the selected native image service; no result persistence. */
+export function createCoreImageRuntime(
+    {client = getInstalledCoreClient(), signal, onEvent} = {}
+) {
+    const owner = {};
+    const events = createArcaneEventSource(
+        owner,
+        {source: 'core-image', eventTypes: ['image.state']}
+    );
+    const lifetime = new AbortController();
+    const lifetimeSignal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+    const pending = new Set();
+    let state = {
+        id: 'stable-diffusion.cpp',
+        installed: false,
+        available: false,
+        selectedModel: null,
+        loaded: false,
+        state: client ? 'unknown' : 'unavailable',
+        backend: null,
+        devices: [],
+        resources: {},
+        progress: null,
+        error: null,
+        models: []
+    };
+    let revision = 0;
+    let closed = false;
+    let closing;
+
+    function current() {
+        const requests = [...pending].map(
+            function requestState(request) {
+                return {
+                    method: request.method,
+                    streamId: request.streamId,
+                    status: request.status,
+                    progress: request.progress
+                };
+            }
+        );
+        return {
+            ...state,
+            requests,
+            status: !closed && requests.some(
+                function generationPending(request) {
+                    return request.status === 'Thinking';
+                }
+            ) ? 'Thinking' : null,
+            busy: pending.size > 0,
+            closed
+        };
+    }
+
+    function reportObserverFailure(error) {
+        globalThis.console?.error('Core image observer failed.', error);
+    }
+
+    function notifyListener(listener, value) {
+        const result = listener(value);
+        if (result && is.function(result.then)) {
+            // Observers own their callback lifetimes and may await close().
+            Promise.resolve(result).catch(reportObserverFailure);
+        }
+    }
+
+    function observe(callback, value) {
+        if (!is.function(callback)) {
+            return;
+        }
+        try {
+            notifyListener(callback, value);
+        } catch (error) {
+            reportObserverFailure(error);
+        }
+    }
+
+    function publish() {
+        const snapshot = current();
+        events.dispatch('image.state', snapshot);
+        if (snapshot.closed === closed) {
+            observe(
+                onEvent,
+                {type: 'image.state', data: snapshot}
+            );
+        }
+        return snapshot;
+    }
+
+    function accept(value) {
+        if (closed) {
+            return;
+        }
+        state = value;
+        revision += 1;
+        publish();
+    }
+
+    const unsubscribe = client?.events.on('image.state', accept)
+        ?? function noCoreSubscription() {};
+
+    function invoke(method, parameters, {signal: requestSignal, onProgress} = {}) {
+        if (closed) {
+            throw unavailable('The Core image accessor is closed.');
+        }
+        if (!client) {
+            throw unavailable('Local image generation requires an available Core connection.');
+        }
+        const operationSignal = requestSignal
+            ? AbortSignal.any([requestSignal, lifetimeSignal]) : lifetimeSignal;
+        operationSignal.throwIfAborted();
+        const request = {
+            method,
+            revision,
+            streamId: parameters.streamId,
+            status: method === 'image.generate' ? 'Thinking' : null,
+            progress: null,
+            task: null
+        };
+        let stopProgress;
+        if (request.streamId) {
+            stopProgress = client.events.on(
+                'image.progress',
+                function imageProgress(value) {
+                    if (closed || operationSignal.aborted || value.streamId !== request.streamId) {
+                        return;
+                    }
+                    request.progress = value.progress;
+                    publish();
+                    if (closed || operationSignal.aborted) {
+                        return;
+                    }
+                    observe(onProgress, value.progress);
+                    if (closed || operationSignal.aborted) {
+                        return;
+                    }
+                    observe(
+                        onEvent,
+                        {type: 'image.progress', data: value}
+                    );
+                }
+            );
+        }
+        request.task = Promise.resolve().then(
+            async function executeImageRequest() {
+                operationSignal.throwIfAborted();
+                observe(
+                    onEvent,
+                    {type: 'image.request', data: {method, parameters}}
+                );
+                operationSignal.throwIfAborted();
+                const result = await client.invoke(
+                    method,
+                    parameters,
+                    {signal: operationSignal, timeoutMs: 0}
+                );
+                operationSignal.throwIfAborted();
+                if (method === 'image.generate') {
+                    const images = result.images.map(decodeImage);
+                    operationSignal.throwIfAborted();
+                    const decoded = {...result, images};
+                    observe(
+                        onEvent,
+                        {type: 'image.result', data: decoded}
+                    );
+                    operationSignal.throwIfAborted();
+                    return decoded;
+                }
+                return result;
+            }
+        ).catch(
+            function imageRequestFailed(error) {
+                if (!closed && !operationSignal.aborted) {
+                    if (method !== 'image.status' || revision === request.revision) {
+                        state = {...state, error: serializeCoreError(error)};
+                    }
+                    observe(
+                        onEvent,
+                        {type: 'image.error', data: {method, error: serializeCoreError(error)}}
+                    );
+                }
+                throw error;
+            }
+        ).finally(
+            function releaseImageRequest() {
+                stopProgress?.();
+                pending.delete(request);
+                if (!closed) {
+                    publish();
+                }
+            }
+        );
+        pending.add(request);
+        // Acknowledgement precedes transport, preparation, model loading and inference.
+        publish();
+        return request.task;
+    }
+
+    async function inspect({signal: requestSignal} = {}) {
+        const before = revision;
+        try {
+            const result = await invoke(
+                'image.status',
+                {},
+                {signal: requestSignal}
+            );
+            if (!closed && revision === before) {
+                accept(result);
+            }
+            return current();
+        } catch (error) {
+            if (!closed && !requestSignal?.aborted && revision === before) {
+                accept(
+                    {...state, available: false, state: 'unavailable', error: serializeCoreError(error)}
+                );
+            }
+            throw error;
+        }
+    }
+
+    async function load({model, context, assetProjectionId, resourcePaths, signal: requestSignal} = {}) {
+        const before = revision;
+        const result = await invoke(
+            'image.load',
+            {model, context, assetProjectionId, resourcePaths},
+            {signal: requestSignal}
+        );
+        if (!closed && revision === before) {
+            accept(result);
+        }
+        return result;
+    }
+
+    function generate(
+        {model, prompt, parameters, assetProjectionId, resourcePaths, signal: requestSignal, onProgress} = {}
+    ) {
+        const streamId = client?.uuid?.() ?? globalThis.crypto.randomUUID();
+        return invoke(
+            'image.generate',
+            {model, prompt, parameters, streamId, assetProjectionId, resourcePaths},
+            {signal: requestSignal, onProgress}
+        );
+    }
+
+    async function unload({signal: requestSignal} = {}) {
+        const before = revision;
+        const result = await invoke(
+            'image.unload',
+            {},
+            {signal: requestSignal}
+        );
+        if (!closed && revision === before) {
+            accept(result);
+        }
+        return result;
+    }
+
+    function subscribe(listener, {replay = true, signal: subscriptionSignal} = {}) {
+        if (!is.function(listener)) {
+            throw new TypeError('An image state listener must be a function.');
+        }
+        if (closed) {
+            if (replay && !subscriptionSignal?.aborted) {
+                notifyListener(listener, current());
+            }
+            return function closedSubscription() {};
+        }
+        const stop = events.on(
+            'image.state',
+            function imageStateChanged(event) {
+                notifyListener(listener, event.detail);
+            },
+            {signal: subscriptionSignal}
+        );
+        try {
+            if (replay && !subscriptionSignal?.aborted) {
+                notifyListener(listener, current());
+            }
+        } catch (error) {
+            stop();
+            throw error;
+        }
+        return stop;
+    }
+
+    function close() {
+        if (closing) {
+            return closing;
+        }
+        closed = true;
+        closing = Promise.resolve().then(
+            async function closeImageAccessor() {
+                await Promise.allSettled(
+                    [...pending].map(
+                        function requestCompletion(request) {
+                            return request.task;
+                        }
+                    )
+                );
+            }
+        );
+        lifetime.abort();
+        lifetimeSignal.removeEventListener('abort', close);
+        unsubscribe();
+        state = {...state, available: false, state: 'closed'};
+        publish();
+        events.dispose();
+        return closing;
+    }
+
+    lifetimeSignal.addEventListener(
+        'abort',
+        close,
+        {once: true}
+    );
+    if (lifetimeSignal.aborted) {
+        close();
+    } else if (client) {
+        // Subscribe before the snapshot request so a later lifecycle event wins.
+        inspect().catch(
+            function initialImageStateUnavailable(error) {
+                globalThis.console?.error('Core image initial state unavailable.', error);
+            }
+        );
+    }
+
+    return {load, generate, unload, inspect, current, subscribe, close};
+}

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

@@ -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/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 |

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,7 +105,7 @@ 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.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. |
@@ -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`. |