arcane-os 0.57.0 → 0.59.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.59.0
+
+- Reconcile marked generated PWA references when a root application's PWA is
+  disabled. Add explicit `importMap({retireGeneratedPwa:true})` retirement for
+  the caller-confirmed generated root manifest reference and four standard PWA
+  output files. Ordinary disabled refresh preserves unmarked references and
+  files; authored content, unselected pages and browser storage remain intact.
+- Forward the native host's selected state directory to Core service factories
+  as a launch-context default. Every explicit launch JSON field takes precedence
+  unchanged. Windows launcher source now supplies the same separate argument;
+  using that launcher correction requires the matching rebuilt host archive.
+- Forward optional `Arcane.speech.synthesize(request, {signal})` cancellation
+  through the existing request lifetime, preserving complete payloads and the
+  180,000 ms default. Actual engine interruption remains service-owned; no new
+  speech engine, runtime dependency or data migration is introduced.
+
+## 0.58.0
+
+- Add native ONNX sessions through `arcane-os/local-ai/onnx` and browser Core
+  access through `arcane-os/ai/core-onnx`. Explicit runtime selection uses the
+  upstream Node runtime distribution, retained per-session workers, complete
+  tensor transport, authoritative loaded state and owned cancellation/exit.
+  Apps select their graphs, feeds and processing; no model is chosen or fetched.
+- Add native Nemotron diarization runtime preparation, helper build and Core
+  integration. Preserve complete framed input/output, independent streams,
+  cancellation and process drain. Runtime/model selection remains explicit.
+- Add the reusable Core preferences service and Git text snapshots, preserving
+  complete caller data and existing application-owned storage and repository
+  choices. Extend raw process I/O without changing existing UTF-8 defaults.
+- Add shared WebKit document lifecycle and macOS native host composition source,
+  portable target contracts, and explicit packaged HTTP serving through the
+  existing HTTP server. Default HTTPS and ordinary browser behavior remain.
+  macOS executable build and platform acceptance remain separately pending.
+- No automatic runtime/model installation, application default switch or saved
+  data migration is introduced. Native host archive delivery is separate from
+  npm publication; this release does not claim an available Windows/Mac archive.
+
 ## 0.57.0
 
 - Add local model chat through explicit llama.cpp/Ollama runtime requirements,

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.57.0` SDK contract. Development applications declare
+This checkout defines the `0.59.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;
@@ -131,7 +131,7 @@ each device. Keep these local files ignored by Git. The same certificate pair
 works for any selected app in that workspace. The command reports missing TLS
 files instead of starting an HTTP listener.
 
-HTTPS is the default for development and required for packaged browser previews.
+HTTPS is the default for development and packaged browser previews.
 Plain `npm run dev` binds to localhost with the same workspace certificate pair.
 An explicit `--host` overrides the bind address, and `--port` selects the HTTPS port.
 The paired HTTP listener returns 308 redirects and uses an OS-assigned port
@@ -152,6 +152,10 @@ This selects one HTTP content listener and prints HTTP network URLs. It reads
 no certificate pair and serves the same application and generated PWA routes.
 PWA and storage availability still depend on the browser's secure-context
 rules; see [HTTP development](docs/reference/cli.md#explicit-http-development).
+API callers may also explicitly select `http:true` with `mode:'packaged'` to
+serve the selected packaged web root through the same listener owner. See
+[`startDevServer()`](docs/reference/sdk-api.md#startdevserver) for readiness,
+start-URL and shutdown behavior.
 
 Open the URL printed by the server. The generated page owns its import map and
 Arcane theme; its application module is `modules/App.js` at the repository root.

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

@@ -0,0 +1,96 @@
+import {getInstalledCoreClient} from '../core/client.mjs';
+import {createArcaneEventSource} from '../event-manager.mjs';
+import {encodeTensorMap, decodeTensorMap, encodeTensorFetches} from './onnx-tensors.mjs';
+
+function unavailable(message) {
+    const error = new Error(message);
+    error.code = 'ARCANE_ONNX_CORE_UNAVAILABLE';
+    return error;
+}
+
+/** Optional system ONNX access. Construction neither connects nor installs. */
+export function createCoreONNXRuntime({client = getInstalledCoreClient()} = {}) {
+    const owner = {};
+    const events = createArcaneEventSource(owner, {source: 'core-onnx', eventTypes: ['onnx.state']});
+    const lifetime = new AbortController();
+    const pending = new Set();
+    let state = {id: 'onnx', installed: false, available: false, state: 'unknown', models: []};
+    let revision = 0;
+    let closed = false;
+
+    function current() { return {...state, busy: pending.size > 0, closed}; }
+    function publish() { events.dispatch('onnx.state', current()); }
+    function accept(value) {
+        state = value ?? {id: 'onnx', installed: false, available: false, state: 'unavailable', models: []};
+        revision += 1;
+        publish();
+    }
+
+    const unsubscribe = client?.events.on('localai.state', function localStateChanged(snapshot) {
+        if (!closed) accept(snapshot?.runtimes?.find(function onnxRuntime(runtime) { return runtime.id === 'onnx'; }));
+    }) ?? function noCoreSubscription() {};
+
+    async function invoke(method, parameters, {signal, timeoutMs = 0} = {}) {
+        if (closed) throw unavailable('The Core ONNX accessor is closed.');
+        if (!client) throw unavailable('Local ONNX requires an available Core connection.');
+        const request = {};
+        const operationSignal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+        operationSignal.throwIfAborted();
+        pending.add(request);
+        publish();
+        try {
+            return await client.invoke(method, parameters, {signal: operationSignal, timeoutMs});
+        } finally {
+            pending.delete(request);
+            if (!closed) publish();
+        }
+    }
+
+    async function inspect(options) {
+        const before = revision;
+        try {
+            const result = await invoke('onnx.status', {}, options);
+            if (!closed && revision === before) accept(result);
+            return current();
+        } catch (error) {
+            if (!closed && !options?.signal?.aborted && revision === before) {
+                accept({...state, available: false, state: 'unavailable', error});
+            }
+            throw error;
+        }
+    }
+
+    async function load({id, model, sessionOptions, signal, timeoutMs} = {}) {
+        return invoke('onnx.load', {id, model, sessionOptions}, {signal, timeoutMs});
+    }
+
+    async function run({id, feeds, fetches, runOptions, signal, timeoutMs} = {}) {
+        const result = await invoke('onnx.run', {
+            id, feeds: encodeTensorMap(feeds),
+            fetches: encodeTensorFetches(fetches), runOptions
+        }, {signal, timeoutMs});
+        return decodeTensorMap(result);
+    }
+
+    function unload({id, signal, timeoutMs} = {}) {
+        return invoke('onnx.unload', {id}, {signal, timeoutMs});
+    }
+
+    function subscribe(listener) {
+        const stop = events.on('onnx.state', function changed(event) { listener(event.detail); });
+        try { listener(current()); } catch (error) { stop(); throw error; }
+        return stop;
+    }
+
+    function close() {
+        if (closed) return;
+        closed = true;
+        lifetime.abort();
+        unsubscribe();
+        state = {...state, available: false, state: 'closed'};
+        publish();
+        events.dispose();
+    }
+
+    return {load, run, unload, inspect, current, subscribe, close};
+}

package/browser-runtime/ai/onnx-tensors.mjs

@@ -0,0 +1,85 @@
+import Is from '../dependencies/strong-type/index.js';
+
+const is = new Is(false);
+const typedArrays = {
+    Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array,
+    Int32Array, Uint32Array, Float32Array, Float64Array,
+    BigInt64Array, BigUint64Array, Float16Array: globalThis.Float16Array
+};
+
+/** Tensor framing belongs at JSON transport boundaries, outside inference. */
+export function encodeTensorMap(tensors) {
+    if (tensors === undefined || tensors === null) return tensors;
+    return Object.fromEntries(Object.entries(tensors).map(function encodeEntry([name, tensor]) {
+        return [name, tensor === null ? null : {
+            type: tensor.type, dims: tensor.dims, data: encodeTensorData(tensor.data)
+        }];
+    }));
+}
+
+export function decodeTensorMap(tensors) {
+    if (tensors === undefined || tensors === null) return tensors;
+    return Object.fromEntries(Object.entries(tensors).map(function decodeEntry([name, tensor]) {
+        return [name, tensor === null ? null : {
+            type: tensor.type, dims: tensor.dims, data: decodeTensorData(tensor.data)
+        }];
+    }));
+}
+
+export function encodeTensorFetches(fetches) {
+    return is.array(fetches) ? fetches : encodeTensorMap(fetches);
+}
+
+export function decodeTensorFetches(fetches) {
+    return is.array(fetches) ? fetches : decodeTensorMap(fetches);
+}
+
+function encodeTensorData(data) {
+    if (is.typedArray(data)) {
+        const arrayType = Object.prototype.toString.call(data).slice(8, -1);
+        const content = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        return {encoding: 'base64', arrayType, content: encodeBase64(content)};
+    }
+    if (is.array(data)) return data.map(encodeScalar);
+    return data;
+}
+
+function decodeTensorData(data) {
+    if (data?.encoding === 'base64') {
+        const Constructor = typedArrays[data.arrayType];
+        if (!is.function(Constructor)) {
+            throw new TypeError(`Tensor data representation ${data.arrayType} is unavailable in this runtime.`);
+        }
+        const content = decodeBase64(data.content);
+        return new Constructor(content.buffer);
+    }
+    if (is.array(data)) return data.map(decodeScalar);
+    return data;
+}
+
+function encodeScalar(value) {
+    if (is.bigint(value)) return {encoding: 'bigint', value: String(value)};
+    if (is.negativeZero(value)) return {encoding: 'number', value: '-0'};
+    if (is.number(value) && !is.finite(value)) return {encoding: 'number', value: String(value)};
+    return value;
+}
+
+function decodeScalar(value) {
+    if (value?.encoding === 'bigint') return BigInt(value.value);
+    if (value?.encoding === 'number') return Number(value.value);
+    return value;
+}
+
+function encodeBase64(content) {
+    if (is.function(content.toBase64)) return content.toBase64();
+    let binary = '';
+    for (const value of content) binary += String.fromCharCode(value);
+    return btoa(binary);
+}
+
+function decodeBase64(content) {
+    if (is.function(Uint8Array.fromBase64)) return Uint8Array.fromBase64(content);
+    return Uint8Array.from(atob(content), function characterCode(character) {
+        return character.charCodeAt(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. */
@@ -436,7 +568,7 @@ export function createCoreFacade(client){
             remove:name=>invoke('environment.delete',{name})},
         mail:{send:request=>invoke('mail.send',request??{},{timeoutMs:450000})},
         speech:{status:()=>invoke('speech.status',{},{timeoutMs:10000}),
-            synthesize:request=>invoke('speech.synthesize',request??{},{timeoutMs:180000}),
+            synthesize:(request,options)=>invoke('speech.synthesize',request??{},{timeoutMs:180000,signal:options?.signal}),
             transcribe:request=>invoke('speech.transcribe',request??{},{timeoutMs:180000})},
         localAI:{status:()=>invoke('localai.status',{},{timeoutMs:15000}),
             ensurePlatform:()=>invoke('localai.platform.ensure',{},long),recover:request=>invoke('localai.services.recover',request??{},long),
@@ -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