arcane-os 0.82.0 → 0.83.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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

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.82.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

@@ -2,14 +2,16 @@
  * 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.
+ * 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,...}) requires one current CSS match. fill uses an exact
+ * 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
@@ -57,19 +59,56 @@ export function runAppControl(operation, params = {}) {
         throw error;
     }
 
-    function queryElements(selector) {
+    function queryElements(selector, root = document) {
         if (typeof selector !== 'string') {
             fail('INVALID_ARGUMENT', 'selector must be a CSS selector string.');
         }
-        return Array.from(document.querySelectorAll(selector));
+        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
-            ? (document.documentElement ? [document.documentElement] : [])
-            : queryElements(params.selector);
+            ? (isDocument ? (document.documentElement ? [document.documentElement] : []) : [root])
+            : queryElements(params.selector, root);
         const rootSet = new Set(roots);
-        const elements = Array.from(document.querySelectorAll('*'));
+        const elements = Array.from(root.querySelectorAll('*'));
         const idCounts = new Map();
         const childCounts = new Map();
         const childIndexes = new Map();
@@ -88,7 +127,7 @@ export function runAppControl(operation, params = {}) {
             const index = (childCounts.get(parent) ?? 0) + 1;
             childCounts.set(parent, index);
             childIndexes.set(element, index);
-            if (rootSet.has(element) || scope.has(parent)) {
+            if (rootSet.has(element) || rootSet.has(element.parentNode) || scope.has(parent)) {
                 scope.add(element);
             }
         }
@@ -105,14 +144,16 @@ export function runAppControl(operation, params = {}) {
                 shadowHosts.push(
                     {
                         selector: uniqueSelector(element),
-                        mode: element.shadowRoot.mode
+                        mode: element.shadowRoot.mode,
+                        shadowPath: [...shadowPath, uniqueSelector(element)]
                     }
                 );
             }
         }
 
         return {
-            scope: 'top-level-light-dom',
+            scope: isDocument ? 'top-level-light-dom' : 'open-shadow-root',
+            ...(isDocument ? {} : {shadowPath}),
             title: document.title,
             readyState: document.readyState,
             doctype: document.doctype
@@ -122,16 +163,19 @@ export function runAppControl(operation, params = {}) {
             controls,
             frames,
             shadowHosts,
-            activeElement: document.activeElement
-                ? describeElement(document.activeElement, uniqueSelector(document.activeElement))
+            activeElement: root.activeElement
+                ? describeElement(root.activeElement, uniqueSelector(root.activeElement))
                 : null,
-            scrollingElement: document.scrollingElement
+            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,
@@ -141,7 +185,7 @@ export function runAppControl(operation, params = {}) {
         }
 
         function uniqueSelector(element) {
-            if (!element.isConnected || element.getRootNode() !== document) return null;
+            if (!element.isConnected || element.getRootNode() !== root) return null;
             const path = [];
             let current = element;
             let prefix = '';
@@ -161,7 +205,10 @@ export function runAppControl(operation, params = {}) {
             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';
+                // 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;
@@ -190,7 +237,7 @@ export function runAppControl(operation, params = {}) {
         if (labelledBy) {
             const labels = [];
             for (const id of labelledBy.split(/\s+/u)) {
-                const label = document.getElementById(id);
+                const label = element.getRootNode().getElementById?.(id);
                 if (label) labels.push(label.textContent);
             }
             if (labels.length) return {source: 'aria-labelledby', value: labels.join(' ')};
@@ -274,7 +321,8 @@ export function runAppControl(operation, params = {}) {
     }
 
     function actOnElement() {
-        const targets = queryElements(params.selector);
+        const {root, shadowPath} = selectedRoot();
+        const targets = queryElements(params.selector, root);
         if (targets.length !== 1) {
             fail(
                 'ARCANE_APP_CONTROL_TARGET_COUNT',
@@ -328,6 +376,7 @@ export function runAppControl(operation, params = {}) {
             action,
             method,
             invoked: true,
+            ...(root === document ? {} : {shadowPath}),
             eventsDispatched,
             target: describeElement(target, params.selector)
         };

package/docs/reference/cli.md

@@ -15,6 +15,9 @@ acknowledgement to stderr, then complete result JSON to stdout, or complete erro
 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
 

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.81.0",
+  "sdkVersion": "0.82.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
@@ -24,7 +24,7 @@
       "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."
+      "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",

package/docs/reference/native-app-control.md

@@ -74,9 +74,9 @@ connection or other business result.
 | --- | --- |
 | `connectAppControl({endpoint, signal?, onError?})` | Connect once to the explicit running host. It never launches an app, creates Core, changes a profile or reconnects automatically. |
 | `status(options?)` | Returns app identity, platform/host, current URL, document generation, readiness, window title/state/client dimensions and available operations. Readiness describes the document, not models or application services. |
-| `inspect(parameters={}, options?)` | Optional CSS `selector` selects zero or more roots; omission selects the document. Optional `documentGeneration` selects the expected document. Returns complete HTML/text, live control state and DOM-derived role/name hints. |
+| `inspect(parameters={}, options?)` | Optional `shadowPath` selects an open shadow root. Optional CSS `selector` selects zero or more elements within the selected root; omission selects the whole root. Optional `documentGeneration` selects the expected document. Returns complete HTML/text, live control state and DOM-derived role/name hints. |
 | `capture(parameters={}, options?)` | Returns `{mimeType:'image/png', data, documentGeneration, url}`. `data` contains the complete base64 PNG. Optional `documentGeneration` selects the expected document. |
-| `act(parameters, options?)` | Requires `documentGeneration`, one unambiguous CSS `selector`, and the action fields below. |
+| `act(parameters, options?)` | Requires `documentGeneration`, one unambiguous CSS `selector` within the root selected by optional `shadowPath`, and the action fields below. |
 | `close()` | Closes this caller's connection and cancels its pending requests. It never closes the app or Core. Returns the connection's completion promise. |
 | `closed` | Connection lifetime promise; actual transport failures remain observable. |
 | `endpoint` | The caller-selected local endpoint. |
@@ -90,19 +90,73 @@ is retained in the host diagnostics instead of being represented as delivered.
 
 ## Document operations
 
-Inspection covers the top-level light DOM. Its result contains `scope`, `title`,
+Inspection defaults to the top-level light DOM. Its result contains `scope`, `title`,
 `readyState`, `doctype`, `roots`, `controls`, `frames`, `shadowHosts`,
 `activeElement`, `scrollingElement`, `selection`, `documentGeneration`, and
 `url`. Each root retains its complete `html` and `text`; controls retain their
 attributes and current form, selection, disabled, scrolling and related state.
 Generated CSS selectors are useful for the inspected document; a later DOM edit
 can change their meaning. Application-authored stable selectors are preferable
-when available.
+when available. Component replacement or mutation can make a selector stale
+without changing the native document generation.
+
+### Open shadow roots
+
+`inspect` and `act` accept `shadowPath`, an ordered array of CSS host selectors.
+The first selector resolves inside the top-level document; each later selector
+resolves inside the preceding host's open shadow root. Every host selector must
+match exactly one element. The operation's `selector` then resolves only inside
+the final root. An omitted or empty `shadowPath` retains the ordinary light-DOM
+scope. Selecting a root never recursively enters its nested shadow roots.
+
+```js
+const shadowPath = ['#appearance-panel', 'theme-switcher'];
+const panel = await app.inspect({shadowPath});
+await app.act({
+    documentGeneration: panel.documentGeneration,
+    shadowPath,
+    selector: 'button[data-theme="dark"]',
+    action: 'click'
+});
+```
+
+Shadow inspection returns `scope:'open-shadow-root'` and the selected
+`shadowPath`. Its element selectors are local to that root. With no `selector`,
+`roots` contains one complete root record with `selector:null`, its full
+`innerHTML` as `html`, its full `textContent` as `text`, and `state:null`; a
+ShadowRoot itself is not an element or an action target. With a selector, roots
+retain their element HTML and state. Controls, frames and open-shadow hosts are
+described within this selected tree. Each `shadowHosts` descriptor retains its
+local `selector` and `mode`, and adds the full `shadowPath` needed to inspect
+that host's shadow root, including nested hosts. Pass that path to the next
+inspection; pair selectors from its result with that same path for actions.
+
+`activeElement` comes from the selected root. `scrollingElement` is `null` for a
+shadow-root scope because the root has no document scrolling element; scroll
+actions still target elements. `selection.text`, `title`, `readyState`, `doctype`
+and native URL/generation remain document-level information. Role/name label
+references resolve within the element's own tree. Inspection follows the DOM
+tree, not the composed rendering tree: slot-assigned light-DOM nodes remain in
+their own containing DOM tree and are not duplicated inside the selected shadow
+root.
+
+A missing or ambiguous host produces document error `ARCANE_APP_CONTROL_TARGET_COUNT`
+with the complete path, zero-based `index`, `selector` and match count. Invalid
+path or CSS input reports its actual error before any action. A host without an
+accessible open root produces document error `ARCANE_APP_CONTROL_UNSUPPORTED`
+with the path and failing step. The Windows client rejects these document failures
+with top-level `error.code === 'ARCANE_APP_CONTROL_FAILED'`; the original document
+error, including its `code` and `details`, is available at
+`error.data.find(entry => entry.key === 'documentError').value`.
+Closed roots cannot be discovered, entered, or distinguished from
+absent roots through this API. No closed-root interception is installed.
+Shadow actions add the selected `shadowPath` to their result and retain the
+actual target state after dispatch, including disconnection by the action.
 
 Role/name hints are derived from DOM attributes and labels, not a native
-accessibility-tree computation. Frame documents and shadow-root contents are
-outside this selector scope. Frame elements and open-shadow hosts are described;
-closed shadow roots cannot be discovered. Capture is the current rendered
+accessibility-tree computation. Frame documents and unselected shadow-root
+contents are outside the selected scope. Frame elements and open-shadow hosts
+are described; closed shadow roots cannot be discovered. Capture is the current rendered
 viewport, not an offscreen full-document rendering. Covered and minimized-window
 capture behavior requires execution evidence in the selected environment.
 
@@ -130,13 +184,18 @@ markers are transient document lifecycle state and are not written to saved data
 ```powershell
 arcane app-control status --endpoint '\\.\pipe\arcane-pm-control'
 arcane app-control inspect --endpoint '\\.\pipe\arcane-pm-control' --selector '#pm-content'
+arcane app-control inspect --endpoint '\\.\pipe\arcane-pm-control' --request '.arcane\inspection.json'
 arcane app-control capture --endpoint '\\.\pipe\arcane-pm-control' --output '.arcane\view.png'
 arcane app-control act --endpoint '\\.\pipe\arcane-pm-control' --request '.arcane\action.json'
 ```
 
 The action file is the complete action parameter object, including the actual
-`documentGeneration` returned by the preceding status or inspection. The CLI
-reads that file completely. Paths are relative to the current directory. Capture
+`documentGeneration` returned by the preceding status or inspection. Inspection
+also accepts `--request` for a complete parameter object, such as
+`{"shadowPath":["#appearance-panel","theme-switcher"]}` or the same object with
+`selector` and `documentGeneration`. Inspection's `--request` and `--selector`
+options are mutually exclusive. The CLI reads the selected file completely.
+Paths are relative to the current directory. Capture
 writes the PNG to the explicitly selected file and prints its metadata. The other
 operations print complete JSON. `app-control --help` describes this command's
 options; other Arcane commands retain their existing global output-format option.

package/docs/reference/sdk-api.md

@@ -8903,8 +8903,11 @@ document operations. No application is launched, no desktop window is activated,
 and no automatic reconnect or action retry occurs.
 
 `status(options)` reports current app/window/document readiness.
-`inspect(parameters={},options)` returns complete selected light-DOM HTML/text
-and live control state. `capture(parameters={},options)` returns a full base64 PNG
+`inspect(parameters={},options)` returns complete selected DOM HTML/text
+and live control state. Inspection and actions accept optional `shadowPath`, an
+ordered array of unique CSS host selectors through open shadow roots; their
+`selector` resolves inside the final root. Omission retains top-level light DOM.
+Closed roots remain unavailable. `capture(parameters={},options)` returns a full base64 PNG
 of the rendered viewport. `act(parameters,options)` requires a returned
 `documentGeneration`, one CSS selector, and `click`, `fill`, `select` or `scroll`
 fields. Options preserve the Core client signal/timeout contract. `close()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/cli/app-control.mjs

@@ -5,7 +5,7 @@ import {CoreError, serializeCoreError} from '../../browser-runtime/core/contract
 
 const HELP_TEXT=`Usage:
   arcane app-control status --endpoint <pipe-or-socket>
-  arcane app-control inspect --endpoint <pipe-or-socket> [--selector <css-selector>]
+  arcane app-control inspect --endpoint <pipe-or-socket> [--selector <css-selector> | --request <json-file>]
   arcane app-control capture --endpoint <pipe-or-socket> --output <png-file>
   arcane app-control act --endpoint <pipe-or-socket> --request <json-file>
 
@@ -14,6 +14,8 @@ Capture writes the PNG to --output and prints its metadata. Request and output
 filenames are relative to the current directory. This command does not launch
 an application or change its profile. --output selects the capture filename;
 the other Arcane commands retain their existing output-format option.
+Inspect --request reads the complete parameter object, including shadowPath and
+optional documentGeneration. It cannot be combined with --selector.
 `;
 
 function usage(message) {
@@ -25,7 +27,7 @@ function parseArguments(argv) {
     const [action] = argv;
     const allowed = {
         status: ['endpoint'],
-        inspect: ['endpoint', 'selector'],
+        inspect: ['endpoint', 'selector', 'request'],
         capture: ['endpoint', 'output'],
         act: ['endpoint', 'request']
     }[action];
@@ -47,6 +49,9 @@ function parseArguments(argv) {
     if (!values.endpoint) usage('App control requires --endpoint <pipe-or-socket>.');
     if (action === 'capture' && !values.output) usage('App-control capture requires --output <png-file>.');
     if (action === 'act' && !values.request) usage('App-control act requires --request <json-file>.');
+    if (action === 'inspect' && values.request !== undefined && values.selector !== undefined) {
+        usage('App-control inspect accepts --selector or --request, not both.');
+    }
     return {action, ...values};
 }
 
@@ -71,7 +76,7 @@ export async function runAppControlCli(argv, {cwd = process.cwd(), stdout = proc
         stderr.write(`${JSON.stringify({status: 'running', operation: selection.action,
             endpoint: selection.endpoint})}\n`);
         const signal = controller.signal;
-        const parameters = selection.action === 'act'
+        const parameters = selection.request !== undefined
             ? JSON.parse(await readFile(path.resolve(cwd, selection.request), {encoding: 'utf8', signal}))
             : selection.selector === undefined ? {} : {selector: selection.selector};
         connection = await connectAppControl({endpoint: selection.endpoint, signal, onError: failed});