arcane-os 0.80.0 → 0.82.0

package/browser-runtime/core/app-control.mjs

@@ -0,0 +1,439 @@
+/**
+ * Runs inside the existing app document. The native host serializes this named
+ * function with toString(), so all helpers must remain inside its lexical scope.
+ *
+ * inspect({selector?}) reads the top-level light DOM. Omission selects the whole
+ * document; a CSS selector may select any number of roots. HTML, textContent,
+ * attributes and live control state are returned completely. Frame documents
+ * and shadow-root contents are outside this CSS scope; frame elements and open
+ * shadow hosts are identified only. Closed shadow roots cannot be discovered.
+ * domRole/domName are DOM-derived hints, not an accessibility-tree computation.
+ *
+ * act({action,selector,...}) requires one current CSS match. fill uses an exact
+ * string value; select uses either value:string or values:string[]. scroll uses
+ * absolute left/top CSS-pixel offsets, preserving any omitted axis. Actions use
+ * DOM APIs and untrusted events without focus or desktop input. Results describe
+ * immediate DOM state, including any browser value sanitization or scroll
+ * clamping, not completion of asynchronous application work.
+ *
+ * The native host owns document-generation checks, scheduling and cancellation.
+ * This function retains no state, retries no action and returns a JSON envelope
+ * because ExecuteScriptAsync otherwise loses uncaught JavaScript exceptions.
+ */
+export function runAppControl(operation, params = {}) {
+    let actionAttempted = false;
+    const eventsDispatched = [];
+
+    try {
+        if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+            fail('INVALID_ARGUMENT', 'App-control parameters must be an object.');
+        }
+        if (operation === 'inspect') {
+            return {ok: true, result: inspectDocument()};
+        }
+        if (operation === 'act') {
+            return {ok: true, result: actOnElement()};
+        }
+        fail('INVALID_ARGUMENT', 'Expected the inspect or act operation.');
+    } catch (error) {
+        return {
+            ok: false,
+            error: {
+                name: error?.name ?? 'Error',
+                message: error?.message ?? String(error),
+                stack: error?.stack ?? null,
+                code: error?.code ?? 'ARCANE_APP_CONTROL_FAILED',
+                details: error?.details ?? null,
+                actionAttempted,
+                eventsDispatched
+            }
+        };
+    }
+
+    function fail(code, message, details = null) {
+        const error = new Error(message);
+        error.code = code;
+        error.details = details;
+        throw error;
+    }
+
+    function queryElements(selector) {
+        if (typeof selector !== 'string') {
+            fail('INVALID_ARGUMENT', 'selector must be a CSS selector string.');
+        }
+        return Array.from(document.querySelectorAll(selector));
+    }
+
+    function inspectDocument() {
+        const roots = params.selector === undefined
+            ? (document.documentElement ? [document.documentElement] : [])
+            : queryElements(params.selector);
+        const rootSet = new Set(roots);
+        const elements = Array.from(document.querySelectorAll('*'));
+        const idCounts = new Map();
+        const childCounts = new Map();
+        const childIndexes = new Map();
+        const scope = new Set();
+        const selectors = new Map();
+        const controls = [];
+        const frames = [];
+        const shadowHosts = [];
+
+        // One traversal establishes selector paths and scope for all records.
+        for (const element of elements) {
+            if (element.id) {
+                idCounts.set(element.id, (idCounts.get(element.id) ?? 0) + 1);
+            }
+            const parent = element.parentElement;
+            const index = (childCounts.get(parent) ?? 0) + 1;
+            childCounts.set(parent, index);
+            childIndexes.set(element, index);
+            if (rootSet.has(element) || scope.has(parent)) {
+                scope.add(element);
+            }
+        }
+
+        for (const element of elements) {
+            if (!scope.has(element)) continue;
+            if (element.matches('input,textarea,select,button,option,optgroup,fieldset,output,progress,meter,details,summary,a[href],area[href],audio,video,[contenteditable],[role],[tabindex]')) {
+                controls.push(describeElement(element, uniqueSelector(element)));
+            }
+            if (element.localName === 'iframe' || element.localName === 'frame') {
+                frames.push(describeElement(element, uniqueSelector(element)));
+            }
+            if (element.shadowRoot) {
+                shadowHosts.push(
+                    {
+                        selector: uniqueSelector(element),
+                        mode: element.shadowRoot.mode
+                    }
+                );
+            }
+        }
+
+        return {
+            scope: 'top-level-light-dom',
+            title: document.title,
+            readyState: document.readyState,
+            doctype: document.doctype
+                ? new XMLSerializer().serializeToString(document.doctype)
+                : null,
+            roots: roots.map(describeRoot),
+            controls,
+            frames,
+            shadowHosts,
+            activeElement: document.activeElement
+                ? describeElement(document.activeElement, uniqueSelector(document.activeElement))
+                : null,
+            scrollingElement: document.scrollingElement
+                ? uniqueSelector(document.scrollingElement)
+                : null,
+            selection: {text: document.getSelection()?.toString() ?? ''}
+        };
+
+        function describeRoot(element) {
+            return {
+                selector: uniqueSelector(element),
+                html: element.outerHTML,
+                text: element.textContent,
+                state: readState(element)
+            };
+        }
+
+        function uniqueSelector(element) {
+            if (!element.isConnected || element.getRootNode() !== document) return null;
+            const path = [];
+            let current = element;
+            let prefix = '';
+            while (current) {
+                if (selectors.has(current)) {
+                    prefix = selectors.get(current);
+                    break;
+                }
+                if (current.id && !current.id.includes('\0') && idCounts.get(current.id) === 1) {
+                    prefix = `#${CSS.escape(current.id)}`;
+                    selectors.set(current, prefix);
+                    break;
+                }
+                path.push(current);
+                current = current.parentElement;
+            }
+            for (let index = path.length - 1; index >= 0; index -= 1) {
+                const part = path[index];
+                const segment = `*:nth-child(${childIndexes.get(part)})`;
+                prefix = prefix ? `${prefix} > ${segment}` : ':root';
+                selectors.set(part, prefix);
+            }
+            return prefix;
+        }
+    }
+
+    function describeElement(element, selector) {
+        const attributeEntries = [];
+        for (const attribute of element.attributes) {
+            attributeEntries.push(
+                [attribute.name, attribute.value]
+            );
+        }
+        return {
+            selector,
+            tagName: element.localName,
+            attributes: Object.fromEntries(attributeEntries),
+            domRole: element.getAttribute('role'),
+            domName: readDOMName(element),
+            state: readState(element)
+        };
+    }
+
+    function readDOMName(element) {
+        const labelledBy = element.getAttribute('aria-labelledby');
+        if (labelledBy) {
+            const labels = [];
+            for (const id of labelledBy.split(/\s+/u)) {
+                const label = document.getElementById(id);
+                if (label) labels.push(label.textContent);
+            }
+            if (labels.length) return {source: 'aria-labelledby', value: labels.join(' ')};
+        }
+        if (element.hasAttribute('aria-label')) {
+            return {source: 'aria-label', value: element.getAttribute('aria-label')};
+        }
+        if (element.labels?.length) {
+            const labels = [];
+            for (const label of element.labels) labels.push(label.textContent);
+            return {source: 'labels', value: labels.join(' ')};
+        }
+        if (element.hasAttribute('alt')) {
+            return {source: 'alt', value: element.getAttribute('alt')};
+        }
+        if (element.localName === 'input' && ['button', 'submit', 'reset'].includes(element.type)) {
+            return {source: 'value', value: element.value};
+        }
+        return {source: 'textContent', value: element.textContent};
+    }
+
+    function readState(element) {
+        const state = {
+            connected: element.isConnected,
+            contentEditable: element.isContentEditable === true,
+            effectivelyDisabled: element.matches(':disabled'),
+            scrollLeft: element.scrollLeft,
+            scrollTop: element.scrollTop,
+            scrollWidth: element.scrollWidth,
+            scrollHeight: element.scrollHeight,
+            clientWidth: element.clientWidth,
+            clientHeight: element.clientHeight
+        };
+        for (const field of [
+            'value', 'type', 'checked', 'indeterminate', 'disabled', 'readOnly',
+            'required', 'multiple', 'selected', 'selectedIndex', 'hidden', 'open',
+            'tabIndex', 'selectionStart', 'selectionEnd', 'selectionDirection',
+            'willValidate', 'validationMessage', 'paused', 'ended', 'currentTime',
+            'muted', 'volume', 'playbackRate'
+        ]) {
+            const value = element[field];
+            if (value === null || ['string', 'boolean', 'number'].includes(typeof value)) {
+                state[field] = value;
+            }
+        }
+        if (element.isContentEditable) state.editableText = element.textContent;
+        if (element.validity) {
+            state.validity = {};
+            for (const field of [
+                'badInput', 'customError', 'patternMismatch', 'rangeOverflow',
+                'rangeUnderflow', 'stepMismatch', 'tooLong', 'tooShort',
+                'typeMismatch', 'valid', 'valueMissing'
+            ]) {
+                state.validity[field] = element.validity[field];
+            }
+        }
+        if (element.localName === 'select') {
+            state.options = [];
+            for (const option of element.options) {
+                state.options.push(
+                    {
+                        value: option.value,
+                        text: option.text,
+                        label: option.label,
+                        selected: option.selected,
+                        disabled: option.disabled,
+                        effectivelyDisabled: option.matches(':disabled')
+                    }
+                );
+            }
+        }
+        if (element.localName === 'input' && element.type === 'file') {
+            state.files = [];
+            for (const file of element.files) {
+                state.files.push(
+                    {name: file.name, type: file.type, lastModified: file.lastModified}
+                );
+            }
+        }
+        return state;
+    }
+
+    function actOnElement() {
+        const targets = queryElements(params.selector);
+        if (targets.length !== 1) {
+            fail(
+                'ARCANE_APP_CONTROL_TARGET_COUNT',
+                'An action requires exactly one matching element.',
+                {matches: targets.length}
+            );
+        }
+        const target = targets[0];
+        const action = params.action;
+        if (!['click', 'fill', 'select', 'scroll'].includes(action)) {
+            fail('INVALID_ARGUMENT', 'Expected a click, fill, select or scroll action.');
+        }
+        if (action !== 'scroll' && target.matches(':disabled')) {
+            fail('ARCANE_APP_CONTROL_DISABLED', 'The selected control is disabled.');
+        }
+
+        let method;
+        if (action === 'click') {
+            if (typeof target.click !== 'function') {
+                fail('ARCANE_APP_CONTROL_UNSUPPORTED', 'The selected element does not provide a DOM click method.');
+            }
+            actionAttempted = true;
+            target.click();
+            method = 'click';
+        } else if (action === 'fill') {
+            fillElement(target);
+            method = 'fill';
+        } else if (action === 'select') {
+            selectOptions(target);
+            method = 'select';
+        } else {
+            if (params.left === undefined && params.top === undefined) {
+                fail('INVALID_ARGUMENT', 'scroll requires left, top or both absolute offsets.');
+            }
+            for (const field of ['left', 'top']) {
+                if (params[field] !== undefined && (typeof params[field] !== 'number' || !Number.isFinite(params[field]))) {
+                    fail('INVALID_ARGUMENT', `${field} must be a finite number.`);
+                }
+            }
+            actionAttempted = true;
+            target.scrollTo(
+                {
+                    left: params.left === undefined ? target.scrollLeft : params.left,
+                    top: params.top === undefined ? target.scrollTop : params.top,
+                    behavior: 'instant'
+                }
+            );
+            method = 'scrollTo';
+        }
+        return {
+            action,
+            method,
+            invoked: true,
+            eventsDispatched,
+            target: describeElement(target, params.selector)
+        };
+    }
+
+    function fillElement(target) {
+        if (typeof params.value !== 'string') {
+            fail('INVALID_ARGUMENT', 'fill requires an exact string value.');
+        }
+        if (target.readOnly) fail('ARCANE_APP_CONTROL_READ_ONLY', 'The selected control is read-only.');
+        let prototype;
+        if (target.localName === 'textarea') {
+            prototype = HTMLTextAreaElement.prototype;
+        } else if (target.localName === 'input') {
+            if (['file', 'checkbox', 'radio', 'button', 'submit', 'reset', 'image'].includes(target.type)) {
+                fail('ARCANE_APP_CONTROL_UNSUPPORTED', 'The selected input type does not support filling text.');
+            }
+            prototype = HTMLInputElement.prototype;
+        } else if (!target.isContentEditable) {
+            fail('ARCANE_APP_CONTROL_UNSUPPORTED', 'fill requires an input, textarea or contenteditable element.');
+        }
+
+        actionAttempted = true;
+        if (prototype) {
+            Object.getOwnPropertyDescriptor(prototype, 'value').set.call(target, params.value);
+        } else {
+            Object.getOwnPropertyDescriptor(Node.prototype, 'textContent').set.call(target, params.value);
+        }
+        dispatchInputAndChange(target, params.value, true);
+    }
+
+    function selectOptions(target) {
+        if (target.localName !== 'select') {
+            fail('ARCANE_APP_CONTROL_UNSUPPORTED', 'select requires a native select element.');
+        }
+        if ((params.value === undefined) === (params.values === undefined)) {
+            fail('INVALID_ARGUMENT', 'select requires either value or values.');
+        }
+        const values = params.values === undefined ? [params.value] : params.values;
+        if (!Array.isArray(values)) fail('INVALID_ARGUMENT', 'values must be an array of exact strings.');
+        for (const value of values) {
+            if (typeof value !== 'string') fail('INVALID_ARGUMENT', 'Every selected value must be an exact string.');
+        }
+        if (!target.multiple && values.length > 1) {
+            fail('INVALID_ARGUMENT', 'A single-select control accepts at most one selected value.');
+        }
+        const optionsByValue = new Map();
+        for (const option of target.options) {
+            if (!optionsByValue.has(option.value)) {
+                optionsByValue.set(
+                    option.value,
+                    []
+                );
+            }
+            optionsByValue.get(option.value).push(option);
+        }
+        const selectedOptions = new Set();
+        for (const value of values) {
+            const options = optionsByValue.get(value);
+            if (!options) {
+                fail(
+                    'ARCANE_APP_CONTROL_OPTION_MISSING',
+                    'No option has the requested value.',
+                    {value}
+                );
+            }
+            for (const option of options) {
+                if (option.matches(':disabled')) {
+                    fail(
+                        'ARCANE_APP_CONTROL_DISABLED',
+                        'A requested option is disabled.',
+                        {value}
+                    );
+                }
+                selectedOptions.add(option);
+                if (!target.multiple) break;
+            }
+        }
+        actionAttempted = true;
+        const setter = Object.getOwnPropertyDescriptor(HTMLOptionElement.prototype, 'selected').set;
+        for (const option of target.options) {
+            setter.call(option, selectedOptions.has(option));
+        }
+        if (selectedOptions.size === 0) {
+            Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'selectedIndex').set.call(target, -1);
+        }
+        dispatchInputAndChange(target, null, false);
+    }
+
+    function dispatchInputAndChange(target, data, textInput) {
+        const input = textInput
+            ? new InputEvent(
+                'input',
+                {bubbles: true, composed: true, inputType: 'insertReplacementText', data}
+            )
+            : new Event(
+                'input',
+                {bubbles: true, composed: true}
+            );
+        target.dispatchEvent(input);
+        eventsDispatched.push('input');
+        const change = new Event(
+            'change',
+            {bubbles: true}
+        );
+        target.dispatchEvent(change);
+        eventsDispatched.push('change');
+    }
+}

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

@@ -1116,6 +1116,17 @@ prepared playback without invoking `finishTTS()` or `streamTTS()`. Unmuted
 completion keeps its ordinary speech flush. Explicit calls to either public
 speech method retain their existing behavior.
 
+For a text-only request, pass `speech:false` to the object-form
+`ai.streamRequest({messages, speech:false, onChunk, signal})`. Its completion,
+failure, and cancellation leave buffered speech, prepared playback, and native
+playback alone. The option controls only the request's automatic speech
+finalization and stopping; it is not sent to the language provider and does not
+mute or unload TTS. Explicit speech calls made by your callbacks still run with
+their ordinary behavior. Omitted `speech` or `speech:true` preserves the
+automatic lifecycle above, and positional `streamMessage(...)` is unchanged.
+Explicit `streamTTS()`, `finishTTS()`, and global `stopAudio()` keep their existing
+scope.
+
 ## Automatic speech-input formatting cleanup
 
 The shared streaming, audio-file, and `SpeechPlayback` paths remove repeated

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

@@ -115,13 +115,17 @@ The controller emits `statechange` and `progress` through
 current mutable status snapshot. Provider states are `unloaded`, `loading`, `ready`,
 `unloading`, and `error`.
 
-Browser-WASM model loads report `cache-check`, `download`, and `initialize`
-phases. Download records preserve the ordered model-file fields `completed`,
+Browser-WASM model loads report `cache-check`, `load`, `download`, and `initialize`
+phases. Cache-read and download records preserve the ordered model-file fields `completed`,
 `total`, and `unit:'files'`. Their ordered `members` records contain each file's
 `name`, committed-part `completed`, `total`, and `unit:'shards'`. A streaming
 response has `total:null` until its end is observed; completion then supplies
-the actual committed-part count. Previously complete members identify
-`state:'cached'`. `activeTransfers` is the current transfer-worker count,
+the actual committed-part count. Reading saved parts reports `phase:'load'`,
+`cached:true`, and the known saved-part total before the first read and after
+each part is opened. An existing HTTP Range plan likewise supplies its actual
+shard total. Previously complete members identify `state:'cached'`; their
+per-member records remain cache reads even if another member is downloading.
+A fully cached activation emits no download phase. `activeTransfers` is the current transfer-worker count,
 `transferLimit` is the selected concurrency, and `transferMode` identifies
 `probing`, `files`, `ranges`, or `single`. No byte progress, rate, or estimated
 completion time is produced. Closed-part and lifecycle changes publish promptly;
@@ -136,7 +140,7 @@ These messages do not change the runtime's log level or replace its complete
 diagnostic output.
 
 Initialization has `total:null` and omits `completed` and `unit`, so its progress
-bar is indeterminate. Downloaded-file completion is not activation completion.
+bar is indeterminate. Cached or downloaded file completion is not activation completion.
 The metadata tensor count and GPU layer assignment are descriptive only:
 upstream reports assigned layers before model-weight loading has finished.
 The pinned runtime does not expose a measured overall initialization fraction
@@ -658,10 +662,13 @@ contains `kind`, `tableName`, `downloadConcurrency`, the original `adapter`,
 and `ready`, `install`, `ensure`, `remove`, and `fetchResource`. `ensure()` preserves the complete
 ordered model set and reports whether it was cached or installed.
 `install(source,{signal,onProgress})` and
-`ensure(source,{signal,onProgress,offline})` publish `cache-check` and
-`download` records using ordered file counts and per-member closed-part progress
+`ensure(source,{signal,onProgress,offline})` publish `cache-check`, cache-reading
+`load`, and actual network `download` records using ordered file counts and per-member closed-part progress
 when `onProgress` is supplied. Each member reports `completed`, `total`, and
-`unit:'shards'`; streaming totals remain `null` until completion. Records retain
+`unit:'shards'`; streaming totals remain `null` until completion. Cache reads
+publish the known stored-part plan from zero through each opened part, with
+`cached:true`; the existing Range plan supplies known totals during resume.
+No model length is converted into product progress. Records retain
 `activeTransfers`, `transferLimit`, and `transferMode`, with prompt part/lifecycle
 updates and an existing 250 ms heartbeat. They contain no transfer rate or ETA.
 Multi-file sources use up to that many concurrent member workers
@@ -693,8 +700,12 @@ loaders share this owner for actual configuration, tokenizer, graph,
 external-data and support-file requests. Complete successful GET resources may
 be reused. Cancellation joins reader/writer cleanup and preserves closed parts
 for supported HTTP resume; a full response restarts that resource without
-duplicating its saved prefix. Resource progress uses `unit:'shards'` with
-`total:null` until completion. Independent resource requests remain concurrent.
+duplicating its saved prefix. Resource progress uses `unit:'shards'`. A network
+response without a known shard plan retains `total:null` until completion;
+opening a saved complete or partial resource reports `phase:'load'`,
+`cached:true`, and the known number of stored parts before and during the read.
+The resource URL accompanies every update. These counts describe resource
+preparation, never engine activation. Independent resource requests remain concurrent.
 
 ### Availability and normalization
 

package/docs/reference/cli.md

@@ -9,6 +9,13 @@ work, emits progress or heartbeat records, observes cancellation where safe,
 and exits nonzero on failure. Machine output is defined by
 `arcane-cli-events/1`.
 
+`app-control` is the dedicated native-window client described in
+[native application control](native-app-control.md). It writes a running JSON
+acknowledgement to stderr, then complete result JSON to stdout, or complete error
+JSON to stderr and a nonzero exit. Capture writes its image to the explicit
+`--output` filename and returns metadata. Its options are scoped to that command;
+the general output-format parser below applies to the other commands.
+
 ## Command inventory
 
 | Command | Scope and result |
@@ -31,6 +38,7 @@ and exits nonzero on failure. Machine output is defined by
 | `arcane run` | Serves an existing browser release, or packages, plans, builds, and launches one paired native artifact. |
 | `arcane update-check` | Performs one explicit, read-only npm dist-tag query for the installed SDK version. |
 | `arcane targets` | Lists target ids, declared status, formats, architectures, signing profiles, methods, and pairing reason. |
+| `arcane app-control status\|inspect\|capture\|act` | Connects to an explicit running native window endpoint for document inspection, viewport capture or targeted DOM actions. |
 | `arcane repo status\|pull\|push` | Runs one selected repository operation for the current app workspace. |
 | `arcane mail key set\|status\|delete` | Manages one server-only Resend API-key profile in `.arcane.env.json`. |
 | `arcane mail send` | Performs one explicit, idempotency-keyed Resend attempt from a complete JSON report on redirected stdin. |
@@ -69,7 +77,7 @@ meaning and cardinality rules:
 | `--allow-to` | optional comma-separated addresses | `mail serve` |
 | `--report-key` | nonempty string | `mail send`; caller-owned stable Resend idempotency key, forwarded unchanged |
 | `--request-timeout` | optional integer from 1 through 2147483647 milliseconds | `mail send`, `mail serve` |
-| `--output` | `human`, `json`, `ndjson` | Every invocation; the final occurrence wins. |
+| `--output` | `human`, `json`, `ndjson` | General toolchain invocations; the final occurrence wins. `app-control capture` instead uses its command-specific output filename. |
 | `--git` | flag | `new` |
 | `--skip-tests` | flag | `check --scope app` |
 | `--dry-run` | flag | `package`; parser-supported on `build` with the boundary below |

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

@@ -592,7 +592,21 @@ before the window closes; complete engineering errors go to the supplied
 diagnostic/error callbacks. Callbacks must not synchronously wait for the
 window's lifetime promises.
 
+A WebView2 `BrowserProcessExited` failure retains its complete diagnostic,
+fails a pending `Ready`, and begins the existing Core drain and window close.
+It does not wait for a user to close a blank window or invoke document callbacks
+and script cleanup in the closed browser. The launcher reports the failure
+after that drain. Main-renderer exits and Core-only transport failures retain
+their existing handling. This terminal-flow correction does not identify or
+prevent the underlying browser-process exit, restart the application, or change
+its profile and saved data.
+
 `ArcaneLauncher.cs` supplies the executable entry point for that composition.
+An explicit `native.launchContext.appControl.endpoint` enables the current
+Windows window's background document-control listener. The public client and
+CLI inspect, capture and act on that existing WebView without selecting a desktop
+window or changing its Core/profile. See [native application control](native-app-control.md)
+for launch configuration, document generations, cancellation and platform scope.
 `tools/build-core-windows-host.mjs` builds the selected SDK host output from the
 approved WebView2 package, existing .NET Framework compiler and selected Node
 SEA output. It retains complete compiler diagnostics and produces a fresh

package/docs/reference/inventory/package-api.json

@@ -1,17 +1,31 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.79.0",
+  "sdkVersion": "0.81.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 301,
+  "memberCount": 302,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "core-app-control:connectAppControl",
+      "name": "connectAppControl",
+      "displayName": "connectAppControl()",
+      "kind": "function",
+      "signature": "connectAppControl({endpoint,signal,onError}={})",
+      "entrypoints": ["arcane-os/core/app-control"],
+      "primaryImport": "arcane-os/core/app-control",
+      "group": "Native application control",
+      "summary": "Connects to one explicit running native window for background document inspection, viewport capture and targeted DOM actions.",
+      "availability": "Node local IPC on Windows, Linux and macOS; the current window adapter is Windows WebView2, with other native adapters unavailable",
+      "protocol": "arcane/1 app.control.status, app.control.inspect, app.control.capture and app.control.act over the existing framed local connection. The window host selects native.launchContext.appControl.endpoint and preserves its existing Core child, origin, profile and lifetime.",
+      "normalization": "Returns endpoint, closed, status(options), inspect(parameters={},options), capture(parameters={},options), act(parameters,options), and close(). Parameters pass unchanged; per-operation options preserve Core signal/timeout behavior. Status reports actual app/window/document readiness. Inspect returns complete selected top-level light-DOM HTML/text and live control state with DOM-derived role/name hints; frames and open shadow hosts are descriptors only. Capture returns mimeType image/png, complete base64 data, documentGeneration and URL for the rendered viewport. Act requires documentGeneration and one CSS selector with click, exact-string fill, exact-value select or absolute-offset scroll. The native document marker prevents queued actions crossing replacement; cancellation before dispatch prevents execution while dispatched work is observed through completion without retry or reversal. close() cancels only this connection, never the application or Core. No launch, automatic reconnect, desktop activation, global input or public arbitrary evaluator. See native-app-control.md for complete result fields, CLI and platform scope."
+    },
     {
       "id": "local-ai-execution-devices:createExecutionDeviceCatalog",
       "name": "createExecutionDeviceCatalog",
@@ -45,14 +59,14 @@
       "name": "createNativeDecisionModel",
       "displayName": "createNativeDecisionModel()",
       "kind": "function",
-      "signature": "createNativeDecisionModel({onnx,modelAssets,workingDirectory,paths,assetProjectionId,resourcePaths,model='onnx-community/laya-typed-decisions-ONNX',revision='main',dtype='fp32',sessionOptions,executionPreference='gpu',executionTarget,signal}={})",
+      "signature": "createNativeDecisionModel({onnx,modelAssets,workingDirectory,paths,assetProjectionId,resourcePaths,family='laya',model='onnx-community/laya-typed-decisions-ONNX',revision='main',dtype='fp32',sessionOptions,executionPreference='gpu',executionTarget,signal}={})",
       "entrypoints": ["arcane-os/local-ai/decisions"],
       "primaryImport": "arcane-os/local-ai/decisions",
       "group": "Native typed decisions",
-      "summary": "Explicit native Laya FP32 option scoring through an existing ONNX owner and a tokenizer Worker.",
+      "summary": "Explicit native Laya FP32/FP16 or Julia FP32 option scoring through an existing ONNX owner and a tokenizer Worker.",
       "availability": "Node on Windows/Linux/macOS with selected ONNX Runtime and model files; Android needs host adaptation",
-      "protocol": "Shared browser/native decision encoding with native named tensor results",
-      "normalization": "Returns load/evaluate/classify/current/status/subscribe/unload/dispose; preserves complete separate state/question/options/type and original rows, raw scores and every graph output. load({assetProjectionId,resourcePaths,executionTarget,signal}) retains omitted or undefined source, mapping and target fields from the latest selection, initially the factory configuration. A supplied ready projection takes precedence over configured paths and upstream settings; the existing modelAssets owner retains it directly without upstream preparation or fetching. resourcePaths maps model, tokenizer and tokenizerConfig to exact projection member.path values; complete companion files remain at their original relative paths. Missing projections or mapped members report their actual failure. assetProjectionId:null returns to configured paths or existing upstream preparation when no paths were configured. Separately, executionTarget:null requests automatic resolution, while {deviceId} forwards the saved physical selection to the existing ONNX owner. With no target selection, GPU preference still attempts advertised providers then CPU and explicit session providers retain precedence. Equal source, complete mapping and target selections share activation; a changed selection cancels the earlier request and joins its actual ONNX/tokenizer cleanup before replacement. Incoming projection use is retained before retiring the previous activation; caller preparation ownership is independent, and native files remain retained through actual ONNX and tokenizer Worker exit. Unload ends native use; loading again after all ownership is released requires a fresh projection. pendingActivation reports the requested replacement and projected source/mapping separately; current().execution remains the complete ONNX load record, with requested/resolved/configured/observed target diagnostics in current().execution.execution. Configuration alone does not prove physical execution. Cancellation retires the shared activation. No preference writes, chat history or duplicate inference engine."
+      "protocol": "Shared browser/native decision encoding with native named tensor results. Factory and each load accept family/model/revision/dtype; omission or undefined retains the selected value. Laya FP32 defaults remain. Laya FP16 selects onnx/model_fp16.onnx and onnx/model_fp16.onnx_data; Julia FP32 selects model.onnx and model.onnx.data, with its own tokenizer files. Complete new-family selection and matching files are caller-owned. All model fields participate in activation equality; top-level metadata stays attributable to the retiring activation while pendingActivation records its requested successor. Decoder preserves raw probabilities, every original row and every actual output without inventing Julia action logits.",
+      "normalization": "Returns load/evaluate/classify/current/status/subscribe/unload/dispose; preserves complete separate state/question/options/type and original rows, raw scores and every graph output. load({family,model,revision,dtype,assetProjectionId,resourcePaths,executionTarget,signal}) retains omitted or undefined family, model, revision, dtype, source, mapping and target fields from the latest selection, initially the factory configuration. A supplied ready projection takes precedence over configured paths and upstream settings; the existing modelAssets owner retains it directly without upstream preparation or fetching. resourcePaths maps model, tokenizer and tokenizerConfig to exact projection member.path values; complete companion files remain at their original relative paths. Missing projections or mapped members report their actual failure. assetProjectionId:null returns to configured paths or existing upstream preparation when no paths were configured. Separately, executionTarget:null requests automatic resolution, while {deviceId} forwards the saved physical selection to the existing ONNX owner. With no target selection, GPU preference still attempts advertised providers then CPU and explicit session providers retain precedence. Equal family, model, revision, dtype, source, complete mapping and target selections share activation; a changed selection cancels the earlier request and joins its actual ONNX/tokenizer cleanup before replacement. Incoming projection use is retained before retiring the previous activation; caller preparation ownership is independent, and native files remain retained through actual ONNX and tokenizer Worker exit. Unload ends native use; loading again after all ownership is released requires a fresh projection. pendingActivation reports the requested replacement and projected source/mapping separately; current().execution remains the complete ONNX load record, with requested/resolved/configured/observed target diagnostics in current().execution.execution. Configuration alone does not prove physical execution. Cancellation retires the shared activation. No preference writes, chat history or duplicate inference engine."
     },
     {
       "id": "core-decisions:createNativeDecisionService",
@@ -63,10 +77,10 @@
       "entrypoints": ["arcane-os/core/decisions"],
       "primaryImport": "arcane-os/core/decisions",
       "group": "Native typed decisions",
-      "summary": "Renderer-independent native Laya service reusing the registered local-AI and model-assets owners.",
+      "summary": "Renderer-independent native Laya/Julia service reusing the registered local-AI and model-assets owners.",
       "availability": "Node Core with selected native ONNX and model files",
-      "protocol": "arcane/1 decisions.status/load/evaluate/unload and decisions.state",
-      "normalization": "Registration starts no model or tokenizer. Explicit load obtains dependency-ready same-process owners and reacquires getONNXRuntime after recovery. Factory configuration accepts assetProjectionId, resourcePaths and executionTarget; direct load({assetProjectionId,resourcePaths,executionTarget,signal}) and Core decisions.load({assetProjectionId,resourcePaths,executionTarget}) preserve omitted/undefined selections, with the Core request signal forwarded separately. resourcePaths maps model, tokenizer and tokenizerConfig to exact ready projection member.path values; complete companion members retain their relative paths. Supplied projections take precedence over configured paths/upstream settings, are retained through the existing model-assets owner, and never invoke upstream preparation or fetching; unavailable projections or mapped members fail directly. assetProjectionId:null returns to configured paths or existing upstream preparation, independently of executionTarget:null requesting automatic device selection. Equal source, complete mapping and target selections coalesce; changed selections cancel pending work and join the prior model's disposal before replacement. Incoming retained ownership protects projection files while the previous activation retires; caller preparation ownership remains independent, and native use retains files through actual ONNX/tokenizer exit. pendingActivation includes a projected source/mapping separately from the full activation execution record and its nested execution diagnostics. Native load/evaluate/classify/current/subscribe/unload/dispose preserve complete results; RPC uses the existing tensor codec. Unload has accepted service lifetime; host shutdown cancels request-lifetime load/evaluation."
+      "protocol": "arcane/1 decisions.status/load/evaluate/unload and decisions.state. Factory, direct load and decisions.load accept family/model/revision/dtype with the direct model's exact variant, omission and replacement semantics. The service persists across explicit model changes; top-level activation metadata and pendingActivation distinguish the retiring and requested selections.",
+      "normalization": "Registration starts no model or tokenizer. Explicit load obtains dependency-ready same-process owners and reacquires getONNXRuntime after recovery. Factory configuration accepts family, model, revision, dtype, assetProjectionId, resourcePaths and executionTarget; direct load({family,model,revision,dtype,assetProjectionId,resourcePaths,executionTarget,signal}) and Core decisions.load({family,model,revision,dtype,assetProjectionId,resourcePaths,executionTarget}) preserve omitted/undefined selections, with the Core request signal forwarded separately. resourcePaths maps model, tokenizer and tokenizerConfig to exact ready projection member.path values; complete companion members retain their relative paths. Supplied projections take precedence over configured paths/upstream settings, are retained through the existing model-assets owner, and never invoke upstream preparation or fetching; unavailable projections or mapped members fail directly. assetProjectionId:null returns to configured paths or existing upstream preparation, independently of executionTarget:null requesting automatic device selection. Equal family, model, revision, dtype, source, complete mapping and target selections coalesce; changed selections cancel pending work and join the prior model's disposal before replacement. Incoming retained ownership protects projection files while the previous activation retires; caller preparation ownership remains independent, and native use retains files through actual ONNX/tokenizer exit. pendingActivation includes a projected source/mapping separately from the full activation execution record and its nested execution diagnostics. Native load/evaluate/classify/current/subscribe/unload/dispose preserve complete results; RPC uses the existing tensor codec. Unload has accepted service lifetime; host shutdown cancels request-lifetime load/evaluation."
     },
     {
       "id": "core-decisions:default",