arcane-os 0.88.1 → 0.89.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.89.0
+
+- Add explicitly selected clone-local author name/email before the first
+  checkout. Existing repositories and omitted settings retain their current
+  identity; Git author settings remain distinct from authenticated accounts.
+- Add an app-owned entry point to the packaged native runtime. Applications
+  can launch their MCP module through that runtime with complete arguments,
+  while ordinary Core startup and app-owned shutdown remain intact.
+- Add native window-state control and Escape app-control support. Use the
+  matching Windows host asset and rebuild consumer artifacts through their
+  existing public SDK workflow.
+- Support opt-in extension-local decision runtime distribution and projected
+  native llama preparation with retained model lifetime and per-host target
+  selection. Model acquisition and application preferences remain with their
+  existing owners; CUDA acquisition requires its applicable dependency approval.
+- Preserve literal Unicode and whitespace in RiskSignalAnalyzer input.
+- Select the corrected portable Windows x64 ONNX 1.30.0 distribution through
+  the matching numeric SDK release. Include its complete native runtime closure
+  and notices in the separate retained runtime asset; keep native speech work
+  outside this release.
+
 ## 0.88.1
 
 - Recover an ordinary workspace-operation lock when its recorded runner is

package/browser-runtime/ai/browser-decisions.mjs

@@ -88,16 +88,43 @@ class BrowserDecisionModel {
             throw new TypeError('store must expose fetchResource().');
         }
         this.#store = store;
+        const local = runtime.local ?? false;
+        if (!is.boolean(local)) throw new TypeError('runtime.local must be a boolean.');
         const moduleUrl = runtime.moduleUrl === undefined
-            ? DEFAULT_RUNTIME_MODULE
+            ? local
+                ? new URL('./decisions-runtime/transformers.min.js', import.meta.url).href
+                : DEFAULT_RUNTIME_MODULE
             : runtime.moduleUrl;
+        const selectedRuntime = {...runtime, moduleUrl: requiredText(moduleUrl, 'runtime.moduleUrl')};
+        if (local) {
+            const base = new URL(import.meta.url);
+            function localExecutableUrl(value, name) {
+                const url = new URL(requiredText(value, name), base);
+                if (url.protocol !== base.protocol || url.host !== base.host) {
+                    throw new TypeError(`${name} must use the decision Worker's local deployment in runtime.local mode.`);
+                }
+                return url.href;
+            }
+            const paths = runtime.wasmPaths ?? './decisions-runtime/';
+            const wasmPaths = is.string(paths)
+                ? {
+                    mjs: new URL('ort-wasm-simd-threaded.asyncify.mjs', new URL(paths, base)).href,
+                    wasm: new URL('ort-wasm-simd-threaded.asyncify.wasm', new URL(paths, base)).href
+                }
+                : paths;
+            selectedRuntime.moduleUrl = localExecutableUrl(moduleUrl, 'runtime.moduleUrl');
+            selectedRuntime.wasmPaths = {
+                mjs: localExecutableUrl(wasmPaths?.mjs, 'runtime.wasmPaths.mjs'),
+                wasm: localExecutableUrl(wasmPaths?.wasm, 'runtime.wasmPaths.wasm')
+            };
+        }
         this.#configuration = {
             family,
             model: requiredText(model, 'model'),
             revision: requiredText(revision, 'revision'),
             device: requiredText(device, 'device'),
             dtype: requiredText(dtype, 'dtype'),
-            runtime: {...runtime, moduleUrl: requiredText(moduleUrl, 'runtime.moduleUrl')}
+            runtime: selectedRuntime
         };
         this.#events = createArcaneEventSource(
             this,
@@ -266,7 +293,7 @@ class BrowserDecisionModel {
             }
             const id = this.#nextId++;
             activation.pending.set(id, activation.load);
-            if (this.#store) {
+            if (this.#store && !this.#configuration.runtime.local) {
                 activation.runtimeController = new AbortController();
                 // Retain the operation before a store progress callback can
                 // synchronously unload this activation.
@@ -315,7 +342,7 @@ class BrowserDecisionModel {
                 );
             } else {
                 worker.postMessage(
-                    {id, op: 'load', payload: this.#configuration, storedResources: false}
+                    {id, op: 'load', payload: this.#configuration, storedResources: this.#store !== null}
                 );
             }
         } catch (error) {

package/browser-runtime/ai/core-local.mjs

@@ -22,17 +22,22 @@ function cancelled(reason) {
  * selects its model; Core owns the running engine and its loaded sessions.
  * Creating this provider neither connects a transport nor installs a runtime.
  */
-export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.cpp'} = {}) {
+export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.cpp', prepareModel} = {}) {
     if (!is.string(id) || !id.trim()) throw new TypeError('The Core AI provider id must be a nonempty string.');
     if (suppliedClient !== undefined && suppliedClient !== null
         && (!is.function(suppliedClient?.invoke) || !is.function(suppliedClient?.events?.on))) {
         throw new TypeError('The Core AI client must expose invoke and events.on.');
     }
+    if (prepareModel !== undefined && prepareModel !== null && !is.function(prepareModel)) {
+        throw new TypeError('Core AI model preparation must be a function.');
+    }
 
     let runtime = null;
     let models = [];
     let selection = null;
     let selectionConnection = null;
+    let acceptedLoad = null;
+    let retainedSelection = null;
     let disposed = false;
     let loading = false;
     let unloading = false;
@@ -75,7 +80,7 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
     }
 
     function status() {
-        const loaded = !disposed && modelReady();
+        const loaded = !disposed && Boolean(acceptedLoad) && modelReady();
         return {
             state: disposed ? 'disposed' : loading ? 'loading' : loaded ? 'ready'
                 : runtime?.error ? 'error' : runtime?.available === true ? 'unloaded' : 'unavailable',
@@ -86,6 +91,7 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
             modelId: selection?.modelId ?? null,
             available: !disposed && runtime?.available === true,
             installed: runtime?.installed === true,
+            execution: runtime?.execution ?? null,
             error: runtime?.error ?? null
         };
     }
@@ -113,6 +119,7 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
         lifecycleRevision += 1;
         loading = false;
         unloading = false;
+        acceptedLoad = null;
         runtime = {installed: false, available: false, state: client ? 'unknown' : 'unavailable', error};
         models = [];
         previous?.unsubscribe?.();
@@ -181,7 +188,9 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
             const starting = !runtime?.error && ['starting', 'loading'].includes(runtime?.state);
             const released = !runtime?.error && runtime?.released === true && runtime.owned === true
                 && runtime.state === 'stopped' && knownModel;
-            if (runtime?.error || (runtime?.available !== true && !starting && !released)) {
+            const preparable = is.function(prepareModel) && runtime?.installed === true && runtime.managed === true
+                && !['closed', 'closing'].includes(runtime.state);
+            if (runtime?.error || (runtime?.available !== true && !starting && !released && !preparable)) {
                 return {
                     available: false,
                     code: 'ARCANE_AI_PROVIDER_UNAVAILABLE',
@@ -189,7 +198,7 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
                     error: runtime?.error ?? null
                 };
             }
-            if (!starting && !knownModel) {
+            if (!starting && !knownModel && !preparable) {
                 return {
                     available: false,
                     code: 'ARCANE_AI_MODEL_UNAVAILABLE',
@@ -206,31 +215,88 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
         }
     }
 
-    async function load({selection: value, signal, progress} = {}) {
+    async function load({selection: value, signal, progress, assetProjectionId, resourcePaths, executionTarget} = {}) {
         const core = requireClient();
         const currentConnection = connection;
         requireSelection(value);
         if (signal?.aborted) throw cancelled(signal.reason);
+        loading?.controller?.abort(cancelled());
         selection = value;
         selectionConnection = currentConnection;
-        const operation = {};
+        acceptedLoad = null;
+        const operation = ownRequest(signal, null, core);
+        let completed = false;
         loading = operation;
         unloading = false;
         lifecycleRevision += 1;
-        try {
-            progress?.({phase: 'loading', modelId: value.modelId});
-            const revision = lifecycleRevision;
-            const current = await invokeOwned(core, 'llama.load', {model: value.modelId}, signal);
-            assertCurrentConnection(currentConnection);
-            if (loading !== operation || selection !== value) throw cancelled();
-            if (lifecycleRevision === revision) acceptRuntime(current);
-            if (!modelReady()) throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Core did not report the selected model loaded and ready.', current?.error);
-            progress?.({phase: 'ready', modelId: value.modelId});
+
+        function assertCurrentLoad() {
             assertCurrentConnection(currentConnection);
+            operation.controller.signal.throwIfAborted();
             if (loading !== operation || selection !== value) throw cancelled();
+        }
+
+        function reportProgress(event) {
+            if (disposed || connection !== currentConnection || operation.controller.signal.aborted
+                || loading !== operation || selection !== value) return;
+            progress?.(event);
+        }
+
+        operation.result = Promise.resolve().then(async function prepareAndLoadModel() {
+            let preparation;
+            let failed = false;
+            let failure;
+            try {
+                assertCurrentLoad();
+                reportProgress({phase: 'loading', modelId: value.modelId});
+                assertCurrentLoad();
+                if (prepareModel) {
+                    preparation = await prepareModel({selection: value, signal: operation.controller.signal, progress: reportProgress});
+                    assertCurrentLoad();
+                }
+                const projectionId = assetProjectionId === undefined ? preparation?.assetProjectionId : assetProjectionId;
+                const paths = resourcePaths === undefined ? preparation?.resourcePaths : resourcePaths;
+                const target = executionTarget === undefined ? preparation?.executionTarget : executionTarget;
+                const parameters = {model: value.modelId};
+                if (projectionId !== undefined) parameters.assetProjectionId = projectionId;
+                if (paths !== undefined) parameters.resourcePaths = paths;
+                if (target !== undefined) parameters.executionTarget = target;
+                const revision = lifecycleRevision;
+                retainedSelection = {selection: value, connection: currentConnection};
+                const current = await core.invoke('llama.load', parameters, {signal: operation.controller.signal});
+                assertCurrentLoad();
+                if (lifecycleRevision === revision) acceptRuntime(current);
+                if (!modelReady()) throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Core did not report the selected model loaded and ready.', current?.error);
+            } catch (error) {
+                failed = true;
+                failure = error;
+            }
+            try {
+                // Core has retained the projection before its load settles.
+                // A cancelled preparation still releases any late result.
+                if (is.function(preparation?.release)) await preparation.release();
+            } catch (error) {
+                if (failed) throw new AggregateError([failure, error], 'Local model loading and preparation release failed.', {cause: failure});
+                throw error;
+            }
+            if (failed) throw failure;
+            assertCurrentLoad();
+            if (!modelReady()) throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Core no longer reports the selected model loaded and ready.', runtime?.error);
+            acceptedLoad = operation;
+            reportProgress({phase: 'ready', modelId: value.modelId});
+            assertCurrentLoad();
+            if (!modelReady()) throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Core no longer reports the selected model loaded and ready.', runtime?.error);
+            completed = true;
             return {authority: authority(value), status: {...status(), state: 'ready', busy: false}};
+        });
+        try {
+            return await operation.result;
         } finally {
-            if (loading === operation) loading = false;
+            operation.release();
+            if (loading === operation) {
+                if (!completed) acceptedLoad = null;
+                loading = false;
+            }
         }
     }
 
@@ -254,7 +320,7 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
         return request;
     }
 
-    function streamRequest(core, parameters, signal) {
+    function streamRequest(core, parameters, signal, assertAcceptedLoad) {
         const request = ownRequest(signal, parameters.model, core);
         const chunks = [];
         const readers = [];
@@ -284,6 +350,7 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
 
         request.result = Promise.resolve().then(function invokeStream() {
             request.controller.signal.throwIfAborted();
+            assertAcceptedLoad();
             return core.invoke('llama.chat', {...parameters, stream: true, streamId}, {signal: request.controller.signal});
         }).then(function streamCompleted(result) {
             if (request.controller.signal.aborted) throw cancelled(request.controller.signal.reason);
@@ -329,9 +396,14 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
         const currentConnection = connection;
         requireSelection(value);
         if (signal?.aborted) throw cancelled(signal.reason);
-        if (loading || unloading || selectionConnection !== connection || selection?.modelId !== value.modelId) {
-            throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Load the selected local model before requesting inference.');
+        const currentLoad = acceptedLoad;
+        function assertAcceptedLoad() {
+            if (loading || unloading || !currentLoad || acceptedLoad !== currentLoad
+                || selectionConnection !== connection || selection?.modelId !== value.modelId) {
+                throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Load the selected local model before requesting inference.');
+            }
         }
+        assertAcceptedLoad();
         const model = payload?.model ?? value.modelId;
         if (!models.some(function knownModel(record) { return record.id === model; })) {
             const revision = lifecycleRevision;
@@ -339,6 +411,7 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
             assertCurrentConnection(currentConnection);
             if (lifecycleRevision === revision) acceptRuntime(current);
         }
+        assertAcceptedLoad();
         if (!models.some(function knownModel(record) { return record.id === model; })) {
             throw localAIError('ARCANE_AI_MODEL_UNAVAILABLE', 'The requested model is unavailable in the local llama.cpp runtime.');
         }
@@ -347,11 +420,12 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
             throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'The requested local runtime or selected model is not ready.');
         }
         const parameters = {model, payload};
-        if (operation === 'stream') return streamRequest(core, parameters, signal);
+        if (operation === 'stream') return streamRequest(core, parameters, signal, assertAcceptedLoad);
         if (operation !== 'chat') throw localAIError('ARCANE_AI_PROVIDER_OPERATION_UNAVAILABLE', 'The local llama.cpp provider supports chat and stream.');
         const pending = ownRequest(signal, model, core);
         pending.result = Promise.resolve().then(function invokeChat() {
             pending.controller.signal.throwIfAborted();
+            assertAcceptedLoad();
             return core.invoke('llama.chat', {...parameters, stream: false}, {signal: pending.controller.signal});
         }).then(function chatCompleted(result) {
             if (pending.controller.signal.aborted) throw cancelled(pending.controller.signal.reason);
@@ -361,16 +435,18 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
     }
 
     async function unload({signal} = {}) {
-        const value = selection;
+        const retained = retainedSelection;
+        const value = retained?.selection;
         const core = requireClient();
         const currentConnection = connection;
         if (signal?.aborted) throw cancelled(signal.reason);
-        if (value && value === selection && selectionConnection !== currentConnection) {
+        if (retained && retained.connection !== currentConnection) {
             throw localAIError('ARCANE_AI_CORE_UNAVAILABLE', 'The selected model belongs to a retired Core connection.');
         }
         if (value) requireSelection(value);
         const operation = {};
         unloading = operation;
+        acceptedLoad = null;
         loading = false;
         lifecycleRevision += 1;
         for (const request of requests) request.controller.abort();
@@ -388,6 +464,7 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
             if (unloading !== operation) throw cancelled();
             selection = null;
             selectionConnection = null;
+            retainedSelection = null;
             unloading = false;
             return status();
         } catch (error) {
@@ -403,10 +480,12 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
     function dispose({signal} = {}) {
         if (disposing) return disposing;
         // The runtime also supplies its configured selection after unload.
-        // Only this provider's retained selection owns a native release.
-        const value = selection;
-        const core = selectionConnection?.client;
+        // Only a dispatched selection owns a native release; preparation alone
+        // must not unload a model owned by another provider.
+        const value = retainedSelection?.selection;
+        const core = retainedSelection?.connection.client;
         disposed = true;
+        acceptedLoad = null;
         loading = false;
         unloading = false;
         lifecycleRevision += 1;
@@ -425,6 +504,7 @@ export function createCoreLocalAIProvider({client: suppliedClient, id = 'llama.c
                 }
                 selection = null;
                 selectionConnection = null;
+                retainedSelection = null;
                 return status();
             }
         ).catch(

package/browser-runtime/ai/decision-runtime.mjs

@@ -221,6 +221,13 @@ export async function loadDecisionRuntime(configuration, report, resourceFetch =
     if (runtime.wasmPaths !== undefined) {
         namespace.env.backends.onnx.wasm.wasmPaths = runtime.wasmPaths;
     }
+    if (runtime.local) {
+        // MV3 executes the packaged module directly. Its upstream cache and
+        // nested WASM workers would otherwise create executable Blob URLs.
+        namespace.env.useWasmCache = false;
+        namespace.env.backends.onnx.wasm.proxy = false;
+        namespace.env.backends.onnx.wasm.numThreads = 1;
+    }
     const {AutoTokenizer, AutoModel, PreTrainedModel, Tensor} = namespace;
     const options = {revision, device, dtype};
     // No progress_callback: upstream 4.3 otherwise performs file-size

package/browser-runtime/ai/decision-worker.mjs

@@ -40,11 +40,17 @@ async function handleDecisionOperation(event) {
     try {
         if (op === 'load') {
             if (event.data.storedResources) {
+                const localExecutables = payload.runtime.local
+                    ? new Set(
+                        [payload.runtime.moduleUrl, payload.runtime.wasmPaths.mjs, payload.runtime.wasmPaths.wasm]
+                    )
+                    : null;
                 // Cover native ONNX support-file fetches as well as env.fetch.
                 // Native module imports remain the browser module loader's job.
                 globalThis.fetch = function fetchDecisionSupport(input, options) {
                     const url = new URL(is.string(input) ? input : input.url ?? input.href, globalThis.location.href);
                     if (url.protocol === 'blob:' || url.protocol === 'data:') return nativeFetch(input, options);
+                    if (localExecutables?.has(url.href)) return nativeFetch(input, options);
                     return resources.fetch(input, options);
                 };
             }
@@ -55,7 +61,9 @@ async function handleDecisionOperation(event) {
                         {id, progress}
                     );
                 },
-                event.data.storedResources ? resources.fetch : null
+                event.data.storedResources
+                    ? payload.runtime.local ? globalThis.fetch : resources.fetch
+                    : null
             );
             globalThis.postMessage(
                 {id, result: {loaded: true}}

package/browser-runtime/core/client.mjs

@@ -647,6 +647,12 @@ export function createCoreFacade(client){
         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: {
+            state(options) {
+                return invoke('window.state', {}, {signal: options?.signal});
+            },
+            setState(selection, options) {
+                return invoke('window.setState', selection, {signal: options?.signal});
+            },
             setTheme(presentation, options) {
                 return invoke(
                     'window.setTheme', presentation,

package/browser-runtime/core/contracts.mjs

@@ -43,6 +43,16 @@ export const CORE_METHOD_CONTRACTS={
         output: '{requestedTarget,resolvedDevice,resolution,reason}',
         meaning: 'Resolve a saved physical identity. Explicit null selects engine-owned automatic resolution; it does not claim a configured or observed device.'
     },
+    'window.state': {
+        input: '{}',
+        output: '{platform,supported,state}',
+        meaning: 'Current requesting native window; state may be normal, maximized, fullscreen, or minimized. No saved preference is read.'
+    },
+    'window.setState': {
+        input: '{state:"normal"|"maximized"|"fullscreen"}',
+        output: '{platform,supported,state}',
+        meaning: 'Apply to the requesting native window and report its resulting state. No persistence, desktop activation, or Core restart.'
+    },
     'window.setTheme': {
         input: '{backgroundColor?,textColor?}: null reset or {red,green,blue,alpha}',
         output: '{platform,supported,applied,unsupported}',

package/docs/reference/ai/browser-decisions.md

@@ -68,14 +68,16 @@ it does not substitute a quantized graph or another model.
 | `revision` | Upstream revision, default `main`; select a stable revision when repeatable model selection is needed. |
 | `device` | Transformers.js backend, default `webgpu`; an explicit supported alternative is caller-owned. No automatic backend fallback. |
 | `dtype` | Exact upstream precision selection; defaults to `fp16` for Laya and `fp32` for Julia. For Laya FP32, supply `dtype: 'fp32'`. Unsupported selections fail at the selected upstream loader rather than being replaced. |
-| `runtime.moduleUrl` | Defaults to the self-contained CDN entry `https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.3.0/dist/transformers.min.js`. The `.web.js` build expects a bundler to resolve its bare ONNX Runtime import and is unsuitable for a native module Worker. An explicit compatible public runtime URL may be supplied. With `store`, the SDK stores and materializes the complete selected entry for that activation. |
-| `runtime.wasmPaths` | Optional upstream ONNX WASM location passed to the selected runtime's public environment API. |
-| `store` | Optional existing SDK DBOPFS model or speech artifact store exposing `fetchResource()`. The store remains outside Worker configuration; the SDK uses it for the runtime entry and bridges the loader's actual resource requests to it. |
+| `runtime.local` | Default `false`. Explicit `true` selects deployment-local executable modules/WASM without executable Blob preparation; see the MV3 section below. |
+| `runtime.moduleUrl` | Defaults to the self-contained CDN entry `https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.3.0/dist/transformers.min.js`, or `./decisions-runtime/transformers.min.js` relative to this SDK module in local mode. The `.web.js` build expects a bundler to resolve its bare ONNX Runtime import and is unsuitable for a native module Worker. Explicit compatible URLs are retained; local mode requires files in the SDK Worker's deployment. With `store` and ordinary non-local mode, the SDK stores and materializes the complete entry for that activation. |
+| `runtime.wasmPaths` | Optional upstream ONNX WASM location passed to the selected runtime's public environment API. Local mode defaults to the matching asyncify module/WASM under `./decisions-runtime/`; it accepts a directory URL or explicit `{mjs, wasm}` URLs resolved relative to this SDK module. |
+| `store` | Optional existing SDK DBOPFS model or speech artifact store exposing `fetchResource()`. It remains outside Worker configuration and owns actual model resources. Ordinary stored mode also owns the runtime entry; local mode loads only the exact selected executable files directly. |
 
 Without `store`, the runtime, tokenizer and weights use normal upstream loading
 and caching. With `store`, the selected loader still owns filenames and model
 selection while model resources persist through that existing SDK store. The
-SDK does not redistribute upstream runtimes or models. Browser
+SDK package does not contain upstream runtimes or models; the explicit local
+materializer below acquires its selected executable distribution. Browser
 network, cross-origin and backend availability still apply. WebGPU needs a
 compatible browser/device context. Unsupported precision or backend errors
 are returned, not replaced with a different model, backend or precision.
@@ -91,6 +93,85 @@ Julia selects `dtype: 'fp32'`, loading root `model.onnx` with the exact
 through the public generic `PreTrainedModel` API, not a text-generation
 pipeline. Existing Wllama, cloud, speech and chat APIs are unchanged.
 
+## Extension-local executables (Manifest V3)
+
+During the application's ordinary SDK materialization, opt into the upstream
+browser distribution through the public Node API:
+
+```js
+import {materializeInstalledSdkRuntime} from 'arcane-os';
+
+await materializeInstalledSdkRuntime({
+    workspaceRoot: process.cwd(),
+    browserDecisions: true
+});
+```
+
+This acquires the official bundled Transformers.js `4.3.0`
+`transformers.min.js`, matching ONNX Runtime
+`1.31.0-dev.20260914-8d85527a0` `ort-wasm-simd-threaded.asyncify.mjs` and
+`ort-wasm-simd-threaded.asyncify.wasm`, plus `TRANSFORMERS-LICENSE` and
+`ONNX-RUNTIME-LICENSE`. The five complete files are staged under
+`arcane/sdk/ai/decisions-runtime/` before replacing the projected runtime.
+Retain the supplied licenses with the distribution. No bundler, Node engine
+dependency tree, model graph or tokenizer is installed by this option.
+Repeat `browserDecisions: true` on each materialization that should retain
+this closure; whole-tree replacement removes files absent from a later selection.
+
+The result's `workspaceRuntime.browserDecisions` contains `directory`,
+`transformersVersion`, `onnxRuntimeVersion` and `files`. The lower-level
+`materializeWorkspaceRuntimeContent()` accepts the same option and returns
+that record directly as `result.browserDecisions`. Omission performs no
+optional network acquisition. The fixed distribution files are acquired
+concurrently, once each per selected materialization. Events
+`workspace.decisions.started` and `workspace.decisions.progress` expose
+`completed`/`total` file counts; each progress event also has `file` and `url`.
+Cancellation and HTTP or observer failure abort/join pending acquisition and
+preserve the prior runtime. An HTTP failure retains the complete response as
+`error.response` (`url`, `status`, `statusText`, `headers`, `content`), including
+inside `AggregateError.errors` when several operations fail.
+
+Load from an extension-owned module script, using the deployed SDK path:
+
+```js
+import {createBrowserDecisionModel} from './arcane/sdk/ai/browser-decisions.mjs';
+
+const decisions = createBrowserDecisionModel({
+    family: 'laya',
+    model: 'onnx-community/laya-typed-decisions-ONNX',
+    dtype: 'fp16',
+    device: 'webgpu',
+    runtime: {local: true},
+    store // The application's existing SDK DBOPFS model store.
+});
+await decisions.load();
+```
+
+For Julia-1, change the family/model to `julia` /
+`SupersonicLabs/Julia-1-ONNX` and select `dtype: 'fp32'`. Model and tokenizer
+data remain upstream resources served through the same store, preserving its
+complete response, persistent cache, progress and cancellation behavior.
+Construction stays lazy. Only the exact configured local executable URLs use
+native fetch/module loading outside that store; other resources, including
+other same-deployment URLs, retain the model resource bridge.
+
+Local mode directly imports the deployment's module and explicit asyncify
+factory, disables the upstream executable WASM cache and proxy, and selects
+one WASM thread to avoid nested executable Blob workers. This leaves
+`device: 'webgpu'` unchanged; it is not a CPU/backend fallback. Compatible
+custom `runtime.moduleUrl` and `runtime.wasmPaths: {mjs, wasm}` selections must
+share the SDK module's protocol and host. Relative selections resolve against
+that module. A `wasmPaths` directory URL selects the same two asyncify filenames.
+
+Use external module scripts in extension pages. Chrome's MV3 extension-page
+CSP permits WebAssembly with `script-src 'self' 'wasm-unsafe-eval'; object-src
+'self'`; executable scripts and Workers remain packaged locally. The extension
+owns the permissions required for its selected upstream model-data endpoints.
+See [Chrome's extension CSP contract](https://developer.chrome.com/docs/extensions/reference/manifest/content-security-policy).
+This source integration does not establish an actual Chrome extension load,
+WebGPU inference, or application acceptance; those outcomes require execution
+in the selected extension environment.
+
 ## Shared DBOPFS model resources
 
 ```js
@@ -111,7 +192,7 @@ await decisions.load();
 
 The same `store` may serve other SDK model clients. The application supplies no
 tokenizer/configuration/graph manifest and performs no file routing. Explicit
-activation first opens `runtime.moduleUrl` through `store.fetchResource()`.
+activation without `runtime.local` first opens `runtime.moduleUrl` through `store.fetchResource()`.
 The SDK materializes the complete stored entry as a JavaScript object URL for
 the dedicated Worker, without rewriting its content. The configured source URL
 is retained for later activations, so they reuse the same stored resource rather
@@ -122,7 +203,8 @@ actual selected tokenizer, configuration, ONNX graph and external-data requests
 to `store.fetchResource(input, options)`. Its competing browser, custom and
 filesystem model caches are disabled only for this explicit stored mode. The
 default upstream ONNX WASM binary and factory preloads use this same hook.
-Native support-file fetches in the dedicated Worker also use the store. The
+Native support-file fetches in the dedicated Worker also use the store, except
+for the exact deployment-local executable selections in local mode. The
 default runtime entry is self-contained. Entry materialization does not rewrite
 dependency imports in custom modules or preserve their original `import.meta.url`
 base. Custom stored entries must work from an object URL; relative imports or
@@ -148,7 +230,7 @@ url}`. `completed` counts closed persistent shards; `total` is `null` until the
 resource finishes. This progress carries no network-size, rate or ETA fields.
 Cancellation aborts the owned fetch and joins reader/writer cleanup before the
 resource owner becomes available to a later request. Interrupted closed shards
-are retained. Each activation owns its runtime object URL and revokes it after
+are retained. Each non-local stored activation owns its runtime object URL and revokes it after
 terminating the Worker on cancellation, failure, unload or disposal. A cancelled
 runtime-entry fetch is joined before its waiting calls settle; a late response
 cannot activate a replacement Worker. Runtime-entry HTTP failures retain the

package/docs/reference/core-client.md

@@ -161,6 +161,65 @@ pre-aborted signal sends no transcription request; an in-flight abort sends
 service owns interruption and release of its actual engine operation.
 Its optional request observer uses the same pre-dispatch correlation contract.
 
+## Current-window state
+
+`Arcane.window.state({signal}?)` reads the native window hosting the calling
+document. `Arcane.window.setState({state}, {signal}?)` selects `normal`,
+`maximized`, or `fullscreen` for that same window. Both use the existing
+request lifetime and return `{platform:'windows', supported:true, state}`.
+The observed `state` can also be `minimized`; minimize remains a native window
+control rather than a selectable state in this operation.
+
+```js
+async function selectObservatoryWindow(state) {
+    const result=await Arcane.window.setState({state});
+    console.log('Observatory window state:',result.state);
+}
+```
+
+Call this operation when the application's own setting or user action selects
+a state. Initial state belongs to the descriptor's optional
+[`native.window.state`](core-native-packaging.md#initial-native-window-size)
+field. Saved Settings, their loading and the choice to persist a state remain
+application-owned; the SDK adds no saved-state store or page-startup barrier.
+
+The Windows host uses ordinary native normal/maximized states. Fullscreen
+removes the window frame and occupies the selected monitor's full bounds,
+including its taskbar area. It retains the preceding normal bounds and frame
+controls for restoration. Selecting normal restores them; selecting maximized
+restores them before maximizing. This is native window fullscreen, separate
+from the browser Fullscreen API. It does not select TopMost, request foreground
+activation, change the profile/origin or restart Core. A minimized fullscreen
+window reports `minimized` until restored or another state is selected.
+
+Visible transitions use a temporary native callback confined to this window's
+UI thread and synchronous operation. It prevents activation of this window and
+focus assignment to it or its descendants, then releases the callback. Other
+windows and ordinary input remain untouched. Hidden initial configuration and
+already-selected states allocate no callback; the application's ordinary first
+show keeps its existing startup behavior. State reads observe the native
+minimized/maximized state, rather than merely echoing the requested selection.
+
+Malformed selections reject with `INVALID_ARGUMENT`; native operation failures
+reject with `ARCANE_WINDOW_STATE_FAILED`. Complete native error/cause fields
+remain available, with `details.requested`, `details.previous` and
+`details.actual` describing the attempted selection and observed state. A
+partial native change is observable rather than rolled back. Cancellation
+suppresses late responses and does not undo a change the host already applied.
+If native callback cleanup fails, it stops preventing activation immediately,
+its handle remains owned, and the failure is returned. Simultaneous mutation and
+cleanup failures retain both original errors. The owning window makes another
+cleanup attempt during its normal close and reports any remaining failure.
+State changes survive document navigation, while each response remains
+correlated to its originating document. There is no state-change event in this
+contract; `state()` reads the current native state when requested.
+
+These methods require the matching Windows host executable. The current macOS,
+Linux and Android hosts have no implementation of these operations; their
+actual unavailable-method errors remain observable. Ordinary browsers have no
+native window transport. The facade supplies no browser or other-host fallback,
+and importing it does not add support to an older native executable.
+
 ## Current-window theme
 
 `Arcane.window.setTheme(presentation, {signal}?)` changes only the window