arcane-os 0.56.0 → 0.58.0

package/browser-runtime/core/client.mjs

@@ -14,6 +14,7 @@ export function createCoreClient({
     eventOwnerReady,
     autoConnect=true,
     replayRuntimeState=false,
+    webKitDocumentLifecycle=false,
     onError=error=>global.console?.error('Arcane Core client failed.',error)
 }={}){
     const pending=new Map();
@@ -29,6 +30,7 @@ export function createCoreClient({
     let eventOwnerFailure=null;
     let transportFailure=null;
     let transportFailureReported=false;
+    let webKitDocument=null;
 
     function report(error){
         if(error===transportFailure){
@@ -67,8 +69,13 @@ export function createCoreClient({
         report(eventOwnerFailure);
     });
 
-    function emit(event,data){
-        withEvents(()=>source.dispatch(CORE_EVENT,{event,data}));
+    function acceptsNativeDelivery(activation){
+        return !closed&&(!webKitDocument||webKitDocument.current(activation));
+    }
+    function emit(event,data,activation=webKitDocument?.activation){
+        withEvents(function deliverEvent(){
+            if(acceptsNativeDelivery(activation))source.dispatch(CORE_EVENT,{event,data});
+        });
     }
     function complete(event,data){
         if(completedEvents.has(event))return false;
@@ -110,13 +117,23 @@ export function createCoreClient({
             if(typeof listener!=='function')throw new TypeError('Arcane event listener must be a function.');
             if(!completedEvents.has(event))return events.once(event,listener);
             const value=completedEvents.get(event);
+            const activation=webKitDocument?.activation;
             let active=!closed;
-            Promise.resolve().then(function replayReadyEvent(){
-                if(!active||closed)return;
+            let dispose=null;
+            function deliverReadyEvent(ready){
+                if(!active)return;
                 active=false;
-                try{listener(value);}catch(error){report(error);}
+                dispose?.();
+                try{listener(ready);}catch(error){report(error);}
+            }
+            // A ready-state subscription survives a retirement that happens
+            // before its queued replay, just like an ordinary registration.
+            if(webKitDocument)dispose=events.once(event,deliverReadyEvent);
+            Promise.resolve().then(function replayReadyEvent(){
+                if(!active||!acceptsNativeDelivery(activation))return;
+                deliverReadyEvent(value);
             });
-            return function unsubscribe(){active=false;};
+            return function unsubscribe(){active=false;dispose?.();};
         },
         completed(event){return CORE_READY_EVENTS.includes(event)&&completedEvents.has(event);}
     };
@@ -131,8 +148,8 @@ export function createCoreClient({
         else request.resolve(result);
         return true;
     }
-    function receive(input){
-        if(closed)return false;
+    function receive(input,activation){
+        if(!acceptsNativeDelivery(activation))return false;
         let message=input;
         if(typeof message==='string'){
             try{message=JSON.parse(message);}
@@ -149,7 +166,9 @@ export function createCoreClient({
         // Final responses follow earlier event deliveries, including while a
         // classic host is connecting the shared SDK event owner. A stream's
         // completion must not remove its subscription before its chunks arrive.
-        withEvents(()=>settle(message.id,message.ok?null:new CoreError(message.error),message.result));
+        withEvents(function deliverResponse(){
+            if(acceptsNativeDelivery(activation))settle(message.id,message.ok?null:new CoreError(message.error),message.result);
+        });
         return true;
     }
     function installCallback(name,value){
@@ -182,6 +201,107 @@ export function createCoreClient({
         catch(error){record.reject(error);}
         return true;
     }
+    function createWebKitDocumentTransport(webkit) {
+        let activation = null;
+        let active = false;
+        let registration = null;
+        function current(candidate) {
+            return !closed && active && candidate === activation;
+        }
+        function inactive() {
+            return new CoreError(
+                {code: 'ARCANE_WEBKIT_DOCUMENT_INACTIVE', message: 'This document activation no longer owns the native connection.'}
+            );
+        }
+        async function post(record) {
+            parseAcknowledgement(
+                await webkit.postMessage(record), {required: true}
+            );
+        }
+        function activate(restored = false) {
+            if (closed || active) return;
+            activation = uuid();
+            active = true;
+            const candidate = activation;
+            // Only transport ingress waits for native attachment. Rendering and
+            // the synchronous facade remain independent of this acknowledgement.
+            registration = Promise.resolve().then(
+                function announceDocument() {
+                    if (!current(candidate)) throw inactive();
+                    return post(
+                        {type: 'activate', activation: candidate}
+                    );
+                }
+            );
+            complete(
+                'transport.ready', {protocol: CORE_PROTOCOL, transport: 'webkitgtk'}
+            );
+            registration.then(
+                function replayDocumentState() {
+                    if (current(candidate) && (restored || replayRuntimeState)) {
+                        sendControl(
+                            {protocol: CORE_PROTOCOL, type: 'control', control: 'runtime.replay'}
+                        );
+                    }
+                }
+            ).catch(report);
+        }
+        function retire() {
+            if (!active) return false;
+            const candidate = activation;
+            // Invalidate delivery synchronously, including callbacks queued in
+            // WebKit or waiting for the shared event owner. Subscriptions live
+            // with this document and remain registered across restoration.
+            active = false;
+            completedEvents.clear();
+            for (const [id, request] of pending) settle(id, aborted(request.method));
+            const json = JSON.stringify(
+                {protocol: CORE_PROTOCOL, type: 'control', control: 'requests.cancelAll'}
+            );
+            post(
+                {type: 'retire', activation: candidate, json}
+            ).catch(report);
+            return true;
+        }
+        function restoredDocument(event) {
+            if (event.persisted) activate(true);
+        }
+        if (typeof global.addEventListener === 'function') {
+            global.addEventListener(
+                'pageshow', restoredDocument, {capture: true}
+            );
+            cleanups.push(
+                function removeDocumentRestoration() {
+                    global.removeEventListener(
+                        'pageshow', restoredDocument, {capture: true}
+                    );
+                }
+            );
+        }
+        cleanups.push(
+            function releaseDocument() { active = false; }
+        );
+        installCallback('__arcaneWebKitDocumentCurrent', current);
+        webKitDocument = {current, activate, retire, get activation() { return active ? activation : null; }};
+        return {
+            name: 'webkitgtk',
+            async send(frame) {
+                const candidate = activation;
+                if (!current(candidate)) throw inactive();
+                const json = JSON.stringify(frame);
+                await registration;
+                // A page may retire while native attachment is pending. It
+                // must never submit its queued request after that retirement.
+                if (!current(candidate)) throw inactive();
+                // Abort, timeout or cancelAll may also end a request while
+                // this activation remains live. Unsent work stays cancelled.
+                if (frame.type === 'request' && !pending.has(frame.id)) return;
+                await post(
+                    {type: 'frame', activation: candidate, json}
+                );
+            }
+        };
+    }
     function chooseTransport(){
         const webview=global.chrome?.webview;
         if(webview?.hostObjects){
@@ -204,6 +324,12 @@ export function createCoreClient({
         const webkit=global.webkit?.messageHandlers?.arcane;
         if(typeof global.__arcaneWebKitPostMessage==='function'||webkit){
             installCallback('__arcaneReceive',receive);
+            if(webKitDocumentLifecycle){
+                if(typeof webkit?.postMessage!=='function'){
+                    throw new CoreError({code:'ARCANE_TRANSPORT_INVALID',message:'WebKit document lifecycle requires the arcane message handler with replies.'});
+                }
+                return createWebKitDocumentTransport(webkit);
+            }
             installCallback('__arcaneWebKitAcknowledge',acknowledge);
             return {name:'webkitgtk',async send(frame){
                 const serialized=JSON.stringify(frame);
@@ -293,8 +419,9 @@ export function createCoreClient({
             throw error;
         }
         if(closed)throw transportFailure??new CoreError({code:'ARCANE_CLIENT_CLOSED',message:'The Core client is closed.'});
+        if(webKitDocument)webKitDocument.activate();
         complete('transport.ready',{protocol:CORE_PROTOCOL,transport:transport.name});
-        if(replayRuntimeState&&!closed)sendControl({protocol:CORE_PROTOCOL,type:'control',control:'runtime.replay'});
+        if(replayRuntimeState&&!closed&&!webKitDocument)sendControl({protocol:CORE_PROTOCOL,type:'control',control:'runtime.replay'});
         // A native callback may close the client synchronously during replay.
         if(closed)throw transportFailure??new CoreError({code:'ARCANE_CLIENT_CLOSED',message:'The Core client is closed.'});
         return transport;
@@ -305,7 +432,7 @@ export function createCoreClient({
                 :typeof global.__arcaneWebKitPostMessage==='function'||global.webkit?.messageHandlers?.arcane?'webkitgtk'
                     :typeof global.arcaneAndroid?.postMessage==='function'?'android-webview'
                         :global.__ARCANE_DEV_HTTP__?'development-http':'standalone');
-        return {connected:transport!==null&&!closed,transport:name,
+        return {connected:transport!==null&&!closed&&(!webKitDocument||webKitDocument.activation!==null),transport:name,
             native:['webview2','webkitgtk','android-webview'].includes(name),
             managedLocalAI:['webview2','webkitgtk'].includes(name)};
     }
@@ -389,18 +516,23 @@ export function createCoreClient({
     function close(){
         if(closed)return false;
         closed=true;
-        cancelAll();
+        if(webKitDocument)webKitDocument.retire();
+        else cancelAll();
         disposeTransport(new CoreError({code:'ARCANE_CLIENT_CLOSED',message:'The Core client is closed.'}));
         return true;
     }
+    function documentHidden(){
+        if(webKitDocument)webKitDocument.retire();
+        else cancelAll();
+    }
     if(typeof global.addEventListener==='function'){
-        global.addEventListener('pagehide',cancelAll,{capture:true});
-        cleanups.push(()=>global.removeEventListener('pagehide',cancelAll,{capture:true}));
+        global.addEventListener('pagehide',documentHidden,{capture:true});
+        cleanups.push(()=>global.removeEventListener('pagehide',documentHidden,{capture:true}));
     }
     if(autoConnect){
         try{connect();}catch(error){if(error.code!=='ARCANE_TRANSPORT_UNAVAILABLE')report(error);}
     }
-    return {protocol:CORE_PROTOCOL,Error:CoreError,invoke,receive,connect,close,failTransport,cancelAll,events,eventsReady,runtime:{current:runtimeSnapshot},uuid};
+    return {protocol:CORE_PROTOCOL,Error:CoreError,invoke,receive,connect,close,failTransport,cancelAll,acceptsNativeDelivery,events,eventsReady,runtime:{current:runtimeSnapshot},uuid};
 }
 
 /** Existing namespace call shapes; method implementations remain host-owned. */
@@ -512,7 +644,10 @@ export function installCoreClient(global=globalThis,options={}){
     const previous=global.__arcaneReceive;
     global.__arcaneReceive=client.receive;
     const previousFailure=global.__arcaneTransportFailed;
-    function nativeTransportFailed(error){return client.failTransport(error);}
+    function nativeTransportFailed(error,activation){
+        if(!client.acceptsNativeDelivery(activation))return false;
+        return client.failTransport(error);
+    }
     global.__arcaneTransportFailed=nativeTransportFailed;
     const close=client.close;
     const failTransport=client.failTransport;

package/docs/architecture.md

@@ -191,13 +191,16 @@ redirect listener, defaulting to an OS-assigned port. Existing raw `tls` inputs
 retain their native HTTPS transport under the SDK, as described by the module's
 advanced TLS extension guidance; all content uses its public serving methods.
 
-Explicit `arcane dev --http` or source API `http:true` selects the module's
+Explicit `arcane dev --http` or API `http:true` selects the module's
 single HTTP listener on `port`. It skips certificate resolution and serves the
 same selected source mappings, generated PWA routes, and conditional responses.
+In API packaged mode, it serves the complete selected packaged web root and
+its declared application start URL instead of source mappings.
 No HTTPS listener or redirect is started in this mode. Listener readiness,
 failure, cancellation and shutdown retain the same operation owner; reported
 URLs use the actual HTTP protocol and bound port. Browser secure-context
-requirements remain browser-owned. Packaged previews retain HTTPS.
+requirements remain browser-owned. Source and packaged modes retain HTTPS
+when `http:true` is not selected; a certificate error never switches transport.
 
 Development is an intentionally fast feedback loop. Keep each increment small
 and independently understandable so its effect has one clear cause and a

package/docs/platform-targets.md

@@ -16,10 +16,15 @@ toolchain, platform, architecture, format, signing mode, declared dependency
 releases, and destination. Verification is a separate operation only when the
 user explicitly selects it for the release artifact.
 
-The portable target pairs with the installed SDK provider by default. An explicit
-`--arcane-root` retains fixed-provider selection from an Arcane OS checkout;
-Windows, Linux and Android executable targets still require that override and
-their platform toolchains. Every native request also requires
+The portable, Windows x64 and macOS targets pair with installed SDK providers by
+default. Windows uses the numeric SDK release's precompiled WebView2/SEA host.
+macOS source composition selects that version's architecture-specific AppKit,
+WebKit and bundled Node host asset; actual asset publication and Mac execution
+are separate release evidence, not implied by the target registry.
+An explicit `--arcane-root` retains fixed-provider selection for the registered
+portable, Windows, Linux and Android checkout targets. macOS uses the installed
+SDK provider and has no checkout override. Linux and Android still require that
+override and their platform toolchains. Every native request also requires
 the canonical app descriptor to declare the exact target selected on the
 command line. The SDK package does not silently search for a toolchain, infer a
 descriptor target, embed the Arcane machine bundle, or substitute browser
@@ -35,8 +40,8 @@ npm exec -- arcane native-doctor --target portable
 npm exec -- arcane build --target portable
 
 # In an app scaffolded with --target windows-x64:
-npm exec -- arcane build --target windows-x64 --arcane-root "../Arcane OS"
-npm exec -- arcane run --target windows-x64 --arcane-root "../Arcane OS"
+npm exec -- arcane build --target windows-x64
+npm exec -- arcane run --target windows-x64
 
 # In an app scaffolded with --target linux-x64:
 npm exec -- arcane build --target linux-x64 --arcane-root "../Arcane OS"
@@ -62,7 +67,7 @@ from its installed npm dependency. After `npm install`, run
 browser maps are present. The initial scaffold reports that map as pending while
 the SDK dependency is absent. The scaffold includes the raster icon required
 by the current native platform. Use the
-matching scaffold target (`portable`, `windows-x64`, `linux-x64`, `linux-arm64`,
+matching scaffold target (`portable`, `windows-x64`, `macos-arm64`, `macos-x64`, `linux-x64`, `linux-arm64`,
 or `android-arm64`) before running the corresponding command.
 
 `native-prepare` remains a standalone diagnostic. The normal build recipe omits
@@ -72,7 +77,8 @@ The portable output is an app-scoped payload directory with complete selected
 app and dependency files, a generated Core entry and classic client source.
 It is not an executable and has no direct run operation. Explicit service
 composition uses `createPortableNativeProvider({services:[{module,options}]})`;
-the default adds no OS or application services. See
+the default uses an explicit descriptor service selection when supplied and
+does not discover or copy OS product services. See
 [Core native packaging](reference/core-native-packaging.md).
 The external workspace defaults to `build/portable/`. Integrated Arcane work
 must name an `--output-root` outside that checkout. Explicit checkout providers
@@ -89,19 +95,30 @@ for the complete compatibility and breaking-change rule.
 |---|---|---|
 | `browser` | `directory` | Available |
 | `portable` | `portable` directory | SDK package provider by default; explicit checkout override retained; not executable |
-| `windows-x64` | `exe` bundle | Available with explicit `--arcane-root`; unsigned local development only |
+| `windows-x64` | `exe` bundle | SDK package provider and matching precompiled release host by default; explicit checkout override retained |
+| `macos-arm64` | `.app` bundle | SDK provider source; needs a matching selected or published Apple silicon host asset |
+| `macos-x64` | `.app` bundle | SDK provider source; needs a matching selected or published Intel host asset |
 | `linux-x64` | `deb` | Available with explicit `--arcane-root`; unsigned local development only |
 | `linux-arm64` | `deb` | Available with explicit `--arcane-root` on a compatible native ARM64 toolchain; unsigned local development only |
 | `android-arm64` | `apk` | Available with explicit `--arcane-root`; development-signed, architecture-neutral, and physical/native ARM64 for run |
 
 macOS can consume browser applications and portable JavaScript capabilities
-within their declared runtimes. The current target registry has no macOS native
-package adapter, and the portable CLI request currently selects only Windows
-or Linux. macOS native packaging and Android host adaptation remain incomplete;
-the SDK portable payload does not supply executable hosts. A source-development
+within their declared runtimes. The native target registry includes separate
+Apple silicon and Intel `.app` compositions; portable CLI requests also accept
+macOS. A Mac provider preserves the complete portable payload under its bundle's
+Resources directory and composes the SDK host separately. A source-development
 native wrapper is also not an exposed `arcane dev` target. Native `run` uses the
 selected packaged application through its paired provider.
 
+The package includes macOS `ArcaneCoreProcess`, `ArcaneHost` and launcher source
+for explicit child launch, framed pipes, document lifecycle and graceful drain.
+The SDK provider composes them with an explicitly selected Darwin Node runtime.
+Source availability is not evidence of Mac compilation or execution. See the
+[macOS composition boundary](reference/core-native-packaging.md#macos-application-composition).
+Windows app assembly needs the normal Node/npm toolchain and `tar`, not a C#
+compiler. Its generated executable uses bundled Node and requires .NET Framework
+4.6.2 or later plus WebView2 Runtime on the destination Windows x64 machine.
+
 Every native target accepts one selected app release and its complete bundled
 dependency closure through the provider boundary. The providers retain the
 toolchain state required for build and, where supported, launch; app source and

package/docs/reference/README.md

@@ -52,7 +52,9 @@ alone does not make bare module names resolve in a browser.
 | Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
 | Connect a browser to one Core transport | [Core browser client](core-client.md) |
 | 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) |
 | Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
+| Build a Windows executable without an OS checkout | [Windows executable packaging](core-native-packaging.md#windows-executable) |
 | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
 | Use provider-neutral AI lifecycle, chat, speech, persistence, or document context | [Normalized AI](#normalized-ai) |
 | Choose a normalized typed browser decision surface | [Browser typed decisions](ai/browser-decisions.md) |
@@ -79,9 +81,11 @@ This repository contains explicitly versioned surfaces with different owners:
 
 Browser modules and reusable Core client/runtime/lifecycle source belong to the
 SDK. The portable provider uses this installed package by default and assembles
-an app payload with explicitly selected services; it supplies no executable
-platform host. Explicit Arcane OS provider overrides and integrated shared
-checks remain available. Arcane OS retains its product composition and policy.
+an app payload with explicitly selected services; portable itself supplies no
+executable host. The Windows provider pairs that payload with the installed
+SDK version's precompiled WebView2/SEA release asset. Explicit Arcane OS provider
+overrides and integrated shared checks remain available. Arcane OS retains its
+product composition and policy.
 The historical Core reference snapshot describes a separate host contract;
 matching a protocol name or assembling a payload alone does not establish that
 a composed host supplies every required method or service.
@@ -111,6 +115,35 @@ The [changelog](../../CHANGELOG.md) records changes by version; the
 identify the corresponding published package source. A newer website does not
 change the version installed in your application.
 
+### Generate the selected reference site
+
+The existing `node tools/build-reference-site.mjs --write` command reads the
+live checkout. For release documentation while disjoint source work continues,
+select the reviewed documentation commit explicitly:
+
+```sh
+node tools/build-reference-site.mjs --write --source-ref <documentation-commit>
+```
+
+The same option is accepted by `createReferenceSite({sourceRef})` and
+`writeReferenceSite({sourceRef})`. It reads the selected commit's package
+version, complete reference documents and inventories, inventory-selected
+runtime sources, and authored site inputs directly from Git in memory. It
+creates no checkout or export and leaves source drafts untouched. Rendering
+uses the current canonical generator and its authored semantic contracts;
+select a documentation commit whose contracts match the published package.
+Generated output still belongs to the canonical `site/` tree and requires its
+usual coordinated output ownership. Generation does not publish hosted Pages.
+
+For a selected release whose documentation correction lands after unrelated
+source, `createReferenceSite({inputs})` and `writeReferenceSite({inputs})` accept
+one explicit input owner with `readText(relativePath)` and
+`listFiles(relativeDirectory)`. It is shared with the contract extractor. Keep
+package/runtime reads and document discovery on the release commit, and overlay
+only reviewed documentation records from the correction commit. In particular,
+preserve the selected inventory's member set instead of importing later public
+APIs. Omitted `inputs` preserves the live or `sourceRef` behavior above.
+
 ### Historical 0.3.4 publication record
 
 The following records describe that earlier release only. They do not identify
@@ -181,6 +214,8 @@ Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
 | Offer explicit selected-model start/cancel UI | [`chat.html`](runtime-components.md#chathtml), [`speech.html`](runtime-components.md#speechhtml), and [`voice-transcription.html`](runtime-components.md#voice-transcriptionhtml) | Browser/native WebView components; user activation emits a cancelable request before any LLM or STT load intent, and recording stays disabled without sticky ready STT. |
 | Use Core-normalized chat | [`globalThis.Arcane.ai`](core/arcane-ai-contracts.md) | Native/Core only when separately admitted. |
 | Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebAssembly and OPFS/DBOPFS; explicit CPU selection or WebGPU with full offload and no automatic CPU fallback. |
+| Run application-selected native llama.cpp/Ollama chat | [`arcane-os/ai/core-local`, `arcane-os/core/local-ai`](local-ai.md) | Explicit Core connection and selected native runtimes; installation, availability and loaded-model readiness remain distinct. |
+| Run a local ONNX graph with named tensors | [`arcane-os/local-ai/onnx`, `arcane-os/ai/core-onnx`](local-ai.md#native-onnx-sessions) | Retained native workers; browser access requires an available Core ONNX service. |
 | Run caller-selected Whisper/Kokoro locally | [`arcane-os/ai/browser-speech`](ai/browser-speech.md) | Browser with DBOPFS, Web Locks, Workers and selected upstream sources; automatic WebNN NPU, WebGPU, then WASM loading, or an explicit backend. |
 | Use native browser recognition/voices or selected cloud TTS | [Speech provider choices](ai/browser-speech.md) | Native APIs depend on the browser and may use remote services; cloud TTS requires the application key and endpoint access. |
 | Send complete chat, System One or image requests without retained history | [`arcane-os/ai/twin-cloud`](ai/twin-cloud.md) | Node or browser with Fetch and explicit model/credentials; image results contain every returned image as a Blob. |

package/docs/reference/availability-and-normalization.md

@@ -58,12 +58,12 @@ false when a probe throws; SDK branching continues through its owning error path
 policy, package-owned model policy, platform support, and dependency readiness
 are independent checks.
 
-The current executable host/target matrix covers Microsoft NT, Linux, and
-Android where listed. This SDK exposes no macOS executable target, native
-bridge, artifact, or run contract; WebKitGTK availability must not be
-generalized to macOS. The reusable Node Core runtime, framed stdio transport,
-host composition, and portable payload can be used by a separately composed
-macOS host, but they do not supply that native platform host or bridge.
+Windows x64 has an SDK-owned precompiled WebView2/SEA host; Linux and Android
+retain their explicit checkout providers where listed. The SDK also includes
+macOS Foundation process-adapter source, separately from an executable target,
+renderer bridge, artifact or run command. A composed macOS host may combine that
+source with the reusable Node Core runtime, stdio transport and portable payload.
+Source availability does not establish macOS compilation or execution.
 
 ## Capability-first matrix
 
@@ -89,6 +89,9 @@ macOS host, but they do not supply that native platform host or bridge.
 | Connect browser code to an existing Core transport | `arcane-os/core/client` and `arcane-os/core/contracts` | **Browser / native WebView** with an admitted transport; explicit development HTTP remains opt-in | The reusable client owns `arcane/1` correlation, readiness, cancellation, events, facades, and complete native error fidelity. It supplies no service, policy, or host process. |
 | Compose native Core services and framed stdio hosting | `arcane-os/core/runtime`, `arcane-os/core/stdio`, and `arcane-os/core/host` | **Node** on Windows, Linux, or macOS; the composing native host supplies its process and bridge | The SDK owns reusable dispatch, per-service lifecycle, request/service work ownership, cooperative cancellation, drain, and stdio framing. Product identity, policy, privileges, models, storage, and services remain host-owned. |
 | Assemble a portable Core payload from the installed SDK | `arcane-os/native/portable-provider` | **Node**; portable platform selection is currently Windows or Linux, while separately composed hosts may use the payload | The provider copies the selected app, dependencies, installed SDK runtime, Core client/runtime, and explicit service composition into a non-executable directory. It uses no `arcaneRoot` by default and does not prove host behavior or supply a platform bridge. |
+| Assemble and run a Windows executable | [`arcane-os/native/windows-provider`](core-native-packaging.md#windows-executable) | **Node** for assembly; Windows x64, .NET Framework 4.6.2+ and WebView2 for execution | Uses the installed SDK version's precompiled release asset and explicit app services. Complete diagnostics and accepted service work drain on run cancellation; no OS checkout or application-side native compiler is required. |
+| Use application-selected llama.cpp/Ollama through Core | [`arcane-os/core/local-ai`, `arcane-os/ai/core-local`](local-ai.md) | **Node** native service; **Browser / native WebView** provider through an explicit Core connection | Independent runtime/model lifecycle, complete streaming and cancellation. Official runtime preparation follows explicit app requirements; model selection and business policy stay app-owned. |
+| Run native ONNX tensors | [`arcane-os/local-ai/onnx`, `arcane-os/ai/core-onnx`](local-ai.md#native-onnx-sessions) | **Node** Windows/Linux/macOS x64/arm64; **Browser / native WebView** through available Core | Explicit graph loading, retained workers and complete tensor outputs. Android requires host adaptation. Native calls can delay worker termination; cleanup observes actual exit. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
 | Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Rejected Fetch and HTTP 529 share three retries after 3000 ms; HTTP 429 overload retains unlimited three-second retries. Optional `onRetry` reports waiting/requesting phases without blocking recovery. Shared structured-output mapping and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |

package/docs/reference/cli.md

@@ -49,6 +49,7 @@ meaning and cardinality rules:
 | `--app` | app id or label | Workspace/app operations except shared scope and `verify-bundle`; optional diagnostic label for `mail serve`. |
 | `--apps-root` | `.` or `apps` | `new`, `init`; standalone setup defaults to the repository root. |
 | `--sdk-runtime-source` | SDK checkout directory | `dev` only; maps live SDK source through the selected browser destinations for that server process. |
+| `--local-ai` | comma-separated runtime IDs | `dev` only; adds `llama.cpp`, `ollama` and/or `onnx` requirements to application configuration and prepares missing runtimes alongside serving. See [local AI through Core](local-ai.md). |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
 | `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTPS with HTTP/2 at `0.0.0.0:4433` and accepts an explicit bind host. |
 | `--http-port` | integer 0–65535 | Browser `dev`/`run` HTTP redirect listener; defaults to `0`, which selects an available port. |
@@ -366,9 +367,16 @@ An explicit live-source SDK mapping follows the selected browser destinations
 while reading canonical SDK source; it never replaces installed files.
 
 ```text
-arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>]
+arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>] [--local-ai llama.cpp,ollama,onnx]
 ```
 
+`--local-ai` saves the selected requirements in `native.localAI`, or in
+`arcane-package.json.localAI` for a package-only app. Later development runs
+reuse them. Available services and executables are reused; missing runtimes
+are installed inside the application while serving starts independently.
+Applications choose their model files and optional browser Core connection.
+See [local AI through Core](local-ai.md) for configuration and native bundling.
+
 ### Lifecycle
 
 Startup refreshes the selected authored `arcane-app.json` projection into
@@ -398,7 +406,7 @@ device, since `localhost` refers to that device and `0.0.0.0` is a bind address.
 Network URLs come from one interface snapshot at startup and do not establish
 remote reachability through the machine's firewall or network.
 
-HTTPS is the default for development and required for packaged browser previews.
+HTTPS is the default for development and packaged browser previews.
 The published `node-http-server` 10.0.0 integration negotiates HTTP/2 or HTTP/1.1
 on the same HTTPS port using the configured PEM pair. Source routes, generated
 PWA resources, and conditional responses use the same serving pipeline.
@@ -440,6 +448,10 @@ close the owned HTTP listener and settle the same lifecycle.
 `--key`, or `--http-port` is a usage error. Omitting it preserves HTTPS;
 certificate errors never select HTTP automatically.
 
+The public `startDevServer()` API also accepts `http:true` in packaged mode;
+this does not add a CLI preview command or change `dev` into packaged serving.
+See [the API contract](sdk-api.md#startdevserver).
+
 A LAN HTTP origin does not receive the browser's localhost secure-context
 exception. For Chrome development, Chromium documents
 `chrome://flags/#unsafely-treat-insecure-origin-as-secure` with the exact HTTP
@@ -692,10 +704,10 @@ npm exec -- arcane verify-bundle dist/hello-world-1.0.0.arcane-app.tar.gz
 
 ### Overview
 
-Loads the SDK package provider for portable by default, or the fixed provider
-from an explicitly selected Arcane OS checkout. It diagnoses the selected
-provider prerequisites without building an app. Executable targets still
-require `--arcane-root` and their platform toolchains.
+Loads the SDK package provider for `portable` or `windows-x64` by default, or
+the fixed provider from an explicitly selected Arcane OS checkout. It diagnoses
+selected prerequisites without building an app. Windows uses the matching
+precompiled SDK host; Linux and Android retain their checkout/toolchain routes.
 
 ```text
 arcane native-doctor --target <native-target> [--arcane-root <directory>]
@@ -711,8 +723,7 @@ is unavailable; it never returns a browser package as a substitute.
 
 ```bash
 npm exec -- arcane native-doctor \
-  --target windows-x64 \
-  --arcane-root "../Arcane OS"
+  --target windows-x64
 ```
 
 ## `arcane native-prepare`
@@ -754,6 +765,9 @@ The output remains target-specific inside the common plan contract.
 Portable uses the SDK package without an OS checkout, copies complete selected
 app/dependency payloads and generates the Core entry/classic client source.
 It adds no executable platform host or automatically discovered app services.
+Windows x64 uses the SDK package provider and its matching precompiled release
+asset without an OS checkout or application-side native compilation. See
+[Windows requirements and artifact layout](core-native-packaging.md#windows-executable).
 An explicit `--arcane-root` continues to select the checkout provider.
 Integrated builds retain an output root outside the OS checkout; only an
 explicit checkout provider must share the workspace root.
@@ -767,7 +781,6 @@ rather than returning a fictional native artifact plan.
 ```bash
 npm exec -- arcane build \
   --target windows-x64 \
-  --arcane-root "../Arcane OS" \
   --output-root "../arcane-native-output"
 ```
 
@@ -808,6 +821,13 @@ Android providers expose supported paired native run paths. Portable output is
 a directory and intentionally cannot run. Android run requires one
 connected physical/native ARM64 device for the current target.
 
+`windows-x64` uses the package provider by default, launches `Arcane.exe`, and
+streams complete diagnostics. Its cancellation closes input and waits for the
+window/Core's accepted work to drain; it does not force-kill that host after a
+timer. WebView2 Runtime and .NET Framework 4.6.2 or later must be available on
+the Windows execution machine. Linux/Android retain their explicit provider
+requirements. Build/launch completion does not prove application domain behavior.
+
 ### Example
 
 ```bash