arcane-os 0.81.0 → 0.83.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.83.0
+
+- Add optional `shadowPath` to native app-control inspection and actions. Follow
+  an explicit ordered path through open shadow hosts, then inspect complete
+  content or operate a selector within that root. Nested host records expose
+  their full paths; omitted or empty paths preserve existing light-DOM calls.
+- Accept a complete inspection JSON object through `arcane app-control inspect
+  --request`, including shadow paths and document generation. Existing selector,
+  action, capture and connection lifecycle behavior remains unchanged.
+- Publish the matching Windows helper with the native host archive. Closed
+  shadow roots and frame documents remain outside this capability. Preserve
+  Core, profiles, full payloads and existing dependencies. Package verification
+  is separate from actual built-application acceptance.
+
+## 0.82.0
+
+- Add `connectAppControl` from `arcane-os/core/app-control` and the
+  `arcane app-control` CLI for an explicitly selected running Windows WebView2
+  application. Inspect complete document content and live controls, capture the
+  rendered viewport, and perform targeted click, fill, select and scroll actions
+  without activating the desktop window or injecting global input. Preserve the
+  application's existing Core, profile and lifecycle; closing the client closes
+  only its connection. The matching Windows host archive includes the generated
+  DOM operation source. Other native host adapters remain unavailable.
+- Render stored `arcane-media:` images in shared Chat through MarkdownMedia,
+  including restored history, live chunks and final responses. Preserve complete
+  original Markdown and immediate text rendering. Release obsolete display URLs
+  on replacement, removal and destruction; retain requested print snapshots
+  through `afterprint` and await current images for explicit printing.
+- Keep dependencies, saved-data formats, model and speech routing unchanged.
+  Package verification and host compilation do not establish actual built-app,
+  Core/profile, covered-window capture or model behavior.
+
 ## 0.81.0
 
 - Add per-activation native decision `family`, `model`, `revision`, and `dtype`

package/README.md

@@ -2,6 +2,11 @@
 
 # Arcane OS SDK
 
+[![Check](https://github.com/TheWizardNexus/arcane-os-sdk/actions/workflows/check.yml/badge.svg?branch=main)](https://github.com/TheWizardNexus/arcane-os-sdk/actions/workflows/check.yml?query=branch%3Amain)
+[![npm version](https://img.shields.io/npm/v/arcane-os.svg)](https://www.npmjs.com/package/arcane-os)
+[![npm downloads](https://img.shields.io/npm/dm/arcane-os.svg)](https://www.npmjs.com/package/arcane-os)
+[![license](https://img.shields.io/github/license/TheWizardNexus/arcane-os-sdk.svg)](LICENSE)
+
 <p align="center">
   <strong>Build, test, package, and manage Arcane applications inside or outside Arcane OS.</strong><br>
   Keep proprietary source in its own repository while using the same headless workflow for apps and shared runtime work in the Arcane checkout.
@@ -20,7 +25,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.81.0` SDK contract. Development applications declare
+This checkout defines the `0.83.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

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

@@ -0,0 +1,488 @@
+/**
+ * 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?,shadowPath?}) reads the top-level light DOM or the open
+ * shadow root selected by an ordered array of unique host selectors. Omission
+ * of selector selects that whole root; a CSS selector may select any number of
+ * elements within it. HTML, textContent, attributes and live control state are
+ * returned completely. Frame documents and unselected shadow-root contents stay
+ * outside this scope. Closed shadow roots cannot be discovered or entered.
+ * domRole/domName are DOM-derived hints, not an accessibility-tree computation.
+ *
+ * act({action,selector,shadowPath?,...}) requires one current CSS match in the
+ * selected root. 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, root = document) {
+        if (typeof selector !== 'string') {
+            fail('INVALID_ARGUMENT', 'selector must be a CSS selector string.');
+        }
+        return Array.from(root.querySelectorAll(selector));
+    }
+
+    function selectedRoot() {
+        const shadowPath = params.shadowPath === undefined ? [] : params.shadowPath;
+        if (!Array.isArray(shadowPath)) {
+            fail('INVALID_ARGUMENT', 'shadowPath must be an array of CSS host selectors.');
+        }
+        let root = document;
+        for (let index = 0; index < shadowPath.length; index += 1) {
+            const selector = shadowPath[index];
+            let hosts;
+            try {
+                hosts = queryElements(selector, root);
+            } catch (error) {
+                error.details = {shadowPath, index, selector};
+                throw error;
+            }
+            if (hosts.length !== 1) {
+                fail(
+                    'ARCANE_APP_CONTROL_TARGET_COUNT',
+                    'Each shadowPath selector requires exactly one matching host.',
+                    {shadowPath, index, selector, matches: hosts.length}
+                );
+            }
+            const shadowRoot = hosts[0].shadowRoot;
+            if (!shadowRoot) {
+                fail(
+                    'ARCANE_APP_CONTROL_UNSUPPORTED',
+                    'The selected host has no accessible open shadow root. Closed and absent roots cannot be distinguished.',
+                    {shadowPath, index, selector}
+                );
+            }
+            root = shadowRoot;
+        }
+        return {root, shadowPath};
+    }
+
+    function inspectDocument() {
+        const {root, shadowPath} = selectedRoot();
+        const isDocument = root === document;
+        const roots = params.selector === undefined
+            ? (isDocument ? (document.documentElement ? [document.documentElement] : []) : [root])
+            : queryElements(params.selector, root);
+        const rootSet = new Set(roots);
+        const elements = Array.from(root.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) || rootSet.has(element.parentNode) || 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,
+                        shadowPath: [...shadowPath, uniqueSelector(element)]
+                    }
+                );
+            }
+        }
+
+        return {
+            scope: isDocument ? 'top-level-light-dom' : 'open-shadow-root',
+            ...(isDocument ? {} : {shadowPath}),
+            title: document.title,
+            readyState: document.readyState,
+            doctype: document.doctype
+                ? new XMLSerializer().serializeToString(document.doctype)
+                : null,
+            roots: roots.map(describeRoot),
+            controls,
+            frames,
+            shadowHosts,
+            activeElement: root.activeElement
+                ? describeElement(root.activeElement, uniqueSelector(root.activeElement))
+                : null,
+            scrollingElement: isDocument && document.scrollingElement
+                ? uniqueSelector(document.scrollingElement)
+                : null,
+            selection: {text: document.getSelection()?.toString() ?? ''}
+        };
+
+        function describeRoot(element) {
+            if (element === root && !isDocument) {
+                return {selector: null, html: root.innerHTML, text: root.textContent, state: null};
+            }
+            return {
+                selector: uniqueSelector(element),
+                html: element.outerHTML,
+                text: element.textContent,
+                state: readState(element)
+            };
+        }
+
+        function uniqueSelector(element) {
+            if (!element.isConnected || element.getRootNode() !== root) 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)})`;
+                // A ShadowRoot is not an element matched by :root or :scope.
+                // The parent exclusion anchors its top-level child in this tree.
+                prefix = prefix ? `${prefix} > ${segment}`
+                    : isDocument ? ':root' : `${segment}:not(* > *)`;
+                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 = element.getRootNode().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 {root, shadowPath} = selectedRoot();
+        const targets = queryElements(params.selector, root);
+        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,
+            ...(root === document ? {} : {shadowPath}),
+            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/cli.md

@@ -9,6 +9,16 @@ 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.
+Inspection accepts either `--selector` or `--request <json-file>`; the latter
+reads the complete inspection object, including an explicit `shadowPath` through
+open shadow roots. Actions continue to use `--request` for their complete object.
+
 ## Command inventory
 
 | Command | Scope and result |
@@ -31,6 +41,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 +80,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

@@ -602,6 +602,11 @@ 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.80.0",
+  "sdkVersion": "0.82.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 DOM HTML/text and live control state with DOM-derived role/name hints. Optional shadowPath on inspect and act is an ordered array of unique CSS host selectors through open shadow roots; selector resolves in the final root, with omitted/empty paths retaining top-level light DOM. Whole-shadow-root inspection returns complete innerHTML/textContent with null selector/state; nested shadow-host descriptors provide their full path. Frames remain descriptors and closed roots are unavailable. 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. CLI inspection accepts either --selector or a complete --request JSON object. See native-app-control.md for complete result fields, CLI and platform scope."
+    },
     {
       "id": "local-ai-execution-devices:createExecutionDeviceCatalog",
       "name": "createExecutionDeviceCatalog",

package/docs/reference/inventory/runtime-components.json

@@ -194,13 +194,14 @@
       "slots": [],
       "dependencies": [
         "MD.js",
+        "MarkdownMedia.js",
         "File.js",
         "ConversationTimebox.js",
         "AIRuntimeState.js"
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Default completed-transcription submit or opt-in transcriptionMode=draft, complete appendDraft text with preserved existing selection, native interim-range ownership, and rendered conversation print/printTitle are normalized. No-retention submissions stay outside transcript, recurring context, memory, and DBOPFS. UI/runtime state, honest model progress, complete timestamped transcript including ui_hidden stored records, exact saved nonblank assistant display names with AI fallback rather than current-name inference, live session name capture with host.aiName display fallback, user-facing structural arguments.message, nonblank all-ID tool-result restoration, collapsed complete raw inspection, ordered parallel-call replay validation, per-choice streamed/terminal complete-envelope correlation, complete nonstructural stream rendering, automatic repeated-formatting-mark removal from only the outbound speech-input copy while displayed and stored Markdown stays exact, generic visible failure outcomes with complete console diagnostics, atomic executed/declined/cancelled/not-executed result batches with one continuation, plural pending-call reload recovery, reentrant terminal-event ownership, and BFCache-preserving page lifecycle are normalized; destroy aborts observation and returns true once/false thereafter; AI/storage/media behavior remains mixed"
+      "normalization": "Default completed-transcription submit or opt-in transcriptionMode=draft, complete appendDraft text with preserved existing selection, native interim-range ownership, and rendered conversation print/printTitle are normalized. Local MarkdownMedia images hydrate independently in restored, new, streamed and final content without changing original Markdown or delaying text. Per-render ownership releases obsolete display URLs on replacement, removal and destruction; requested print snapshots retain them through afterprint, while explicit print awaits current image readiness. No-retention submissions stay outside transcript, recurring context, memory, and DBOPFS. UI/runtime state, honest model progress, complete timestamped transcript including ui_hidden stored records, exact saved nonblank assistant display names with AI fallback rather than current-name inference, live session name capture with host.aiName display fallback, user-facing structural arguments.message, nonblank all-ID tool-result restoration, collapsed complete raw inspection, ordered parallel-call replay validation, per-choice streamed/terminal complete-envelope correlation, complete nonstructural stream rendering, automatic repeated-formatting-mark removal from only the outbound speech-input copy while displayed and stored Markdown stays exact, generic visible failure outcomes with complete console diagnostics, atomic executed/declined/cancelled/not-executed result batches with one continuation, plural pending-call reload recovery, reentrant terminal-event ownership, and BFCache-preserving page lifecycle are normalized; destroy aborts observation and returns true once/false thereafter; AI/storage/media behavior remains mixed"
     },
     {
       "file": "runtime/arcane/components/conversation-view.html",