arcane-os 0.81.0 → 0.82.0

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

@@ -0,0 +1,147 @@
+# Native application control
+
+`connectAppControl` from `arcane-os/core/app-control` connects to one explicitly
+selected running application window. The Windows WebView2 host provides document
+inspection, a PNG of its rendered viewport, and targeted DOM actions through its
+own local named pipe. The application keeps its existing Core child, profile,
+origin and window lifecycle. These operations do not activate the desktop window
+or send global keyboard or pointer input.
+
+The Node client uses the SDK's existing `arcane/1` framing and local pipe/socket
+transport on Windows, Linux and macOS. The native window adapter described here
+is Windows WebView2; macOS, Linux and Android hosts do not yet expose these
+operations. An installed generic browser tool does not automatically discover
+this endpoint. A caller must use this public client or CLI explicitly.
+
+## Select the running instance
+
+Add an explicit endpoint to the application's existing native launch context:
+
+```json
+{
+  "native": {
+    "launchContext": {
+      "appControl": {
+        "endpoint": "\\\\.\\pipe\\arcane-pm-control"
+      }
+    }
+  }
+}
+```
+
+The same `appControl` record can be supplied in the launch JSON already selected
+by `--arcane-launch-config`. That record is merged by the existing launcher; it
+does not select a different profile or Core topology. Omission starts the usual
+application without a control listener. Each simultaneous application instance
+needs its own endpoint. An occupied endpoint reports the actual startup failure;
+the host does not silently attach to another window or choose another name.
+
+Use a matching published Windows host asset when assembling the application.
+The host producer generates `arcane-app-control.js` from the canonical standalone
+DOM operation function and includes it beside `Arcane.exe`. Direct C# composition
+uses `ArcaneHostOptions.ApplicationId`, `AppControlEndpoint`, and
+`AppControlSource` with the same generated source. Ordinary composition leaves
+the two control options unset.
+
+## Public client
+
+```js
+import {connectAppControl} from 'arcane-os/core/app-control';
+
+const app = await connectAppControl({
+    endpoint: String.raw`\\.\pipe\arcane-pm-control`
+});
+try {
+    const page = await app.inspect();
+    await app.act({
+        documentGeneration: page.documentGeneration,
+        selector: 'a[data-route="connections"]',
+        action: 'click'
+    });
+    const contents = await app.inspect({selector: '#pm-content'});
+    console.log(contents);
+} finally {
+    await app.close();
+}
+```
+
+This example selects an existing navigation link. Its returned action result
+describes the immediate DOM operation. Inspect the resulting page to establish
+the application outcome; a click alone does not establish an asynchronous save,
+connection or other business result.
+
+| Member | Contract |
+| --- | --- |
+| `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. |
+| `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. |
+| `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. |
+
+Each operation's separate `options` uses the existing Core client request
+contract, including `signal` and `timeoutMs`. Connection cancellation closes only
+that connection. Cancellation before UI dispatch prevents execution. Once a
+script or capture has been dispatched, cancellation cannot reverse its effects;
+the host still observes its completion. A disconnected caller's completed result
+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`,
+`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.
+
+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
+viewport, not an offscreen full-document rendering. Covered and minimized-window
+capture behavior requires execution evidence in the selected environment.
+
+| Action | Parameters and immediate behavior |
+| --- | --- |
+| `click` | Calls the uniquely selected element's DOM `click()` method. |
+| `fill` | Exact string `value` replaces an input, textarea or contenteditable value; input/change events are dispatched. Read-only, disabled and non-text input controls report their actual unsupported state. |
+| `select` | Exact `value` string or `values` string array selects native `<select>` options and dispatches input/change. Multiple values require a multiple-select control. |
+| `scroll` | Absolute numeric `left`, `top`, or both in CSS pixels; the omitted axis retains its position. Returns the resulting scroll state, including browser clamping. |
+
+DOM actions use programmatic, untrusted events. They do not supply physical user
+activation for browser features that require it. Results describe the actual
+immediate state, including browser value sanitization; input is not silently
+rewritten by the SDK.
+
+The host publishes a new generation when an actual replacement document becomes
+ready. A creation-time document marker is also checked inside the executing
+script so a queued action cannot run against a successor page. During navigation,
+operations report that the document is not ready. A change during completion
+reports the actual result with that failure; actions are never retried. These
+markers are transient document lifecycle state and are not written to saved data.
+
+## CLI
+
+```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 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
+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.
+
+Pipe startup, framing, document, image and output-file errors remain observable.
+Host shutdown stops new control work and observes accepted operations alongside
+the existing Core drain. It does not wait for desktop input or leave an
+independent controller process running.

package/docs/reference/runtime-components.md

@@ -372,6 +372,26 @@ reach developer diagnostics and a concise recovery status stays outside the
 transcript. Destruction cancels pending preparation, while an already requested
 print retains its snapshot through `afterprint`.
 
+Markdown images with local `arcane-media:` references saved through
+[`MarkdownMedia`](runtime-modules.md#markdownmediajs) display automatically in
+new messages, live response chunks, final responses, and restored history.
+Chat resolves references through the existing application-scoped DBOPFS owner
+while preserving the complete original Markdown, model payloads, saved history,
+image descriptions, and ordinary image URLs. Text appears immediately; local
+image reads and decoding proceed independently without delaying streaming or
+session readiness. Failed images retain complete developer diagnostics and show
+a concise message beside that card; successful sibling images remain visible.
+
+Each rendered card owns its display URLs. Re-rendering, history replacement,
+transient-message removal, and destruction cancel obsolete display work and
+release those URLs without deleting stored images. Back/Forward Cache retains
+the existing component lifecycle. Explicit `print()` awaits the current images;
+native Print reports images that are still loading or failed instead of claiming
+they are ready. A requested print snapshot retains its image URLs across later
+message changes or component destruction until `afterprint` releases them.
+Applications continue to own image-record names, associations, and cleanup;
+Chat introduces no renderer callback or additional storage API.
+
 Before any session binding begins, callback-mode `sessionStatus` follows the
 selected sticky LLM role and the existing application-owned `modelName` label
 (or the selected model ID). Assigning `modelName` refreshes that status even

package/docs/reference/sdk-api.md

@@ -58,6 +58,7 @@ runtime layouts.
 | `arcane-os/core/development` | App-service composition and document-owned Core transport during source development, independently of local AI. |
 | `arcane-os/core/stdio` | Framed Node stdio transport with graceful runtime drain. |
 | `arcane-os/core/host` | Node-only reusable Core host lifecycle, app-selected native launch defaults and shared native location resolution. |
+| `arcane-os/core/app-control` | Explicit connection to an existing native window for background document inspection, capture and DOM actions. |
 | `arcane-os/codex/app-server` | Explicit native Codex App Server session, complete live turns, server requests and recovery. |
 | `arcane-os/mcp/stdio` | Node MCP STDIO server for app-owned tools and static resources. |
 | `arcane-os/core/repositories` | Native persistent ArcaneData paths, connected working repositories and scoped non-secret Git identity configuration. |
@@ -428,6 +429,7 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `startCoreHost()` | function | `arcane-os/core/host` | Native Core host composition | Node with readable input and writable output streams |
 | `startSharedCoreHost()` | function | `arcane-os/core/host` | Shared Core host | Node local IPC on Windows, Linux and macOS |
 | `connectSharedCoreHost()` | function | `arcane-os/core/host` | Shared Core host | Node local IPC and optional explicit headless startup |
+| `connectAppControl()` | function | `arcane-os/core/app-control` | Native application control | Node local IPC; current window adapter is Windows WebView2 |
 | `runSharedCoreHost()` | function | `arcane-os/core/host` | Shared Core host | Node headless entry and optional parent startup IPC |
 | `startSharedCoreBridge()` | function | `arcane-os/core/host` | Shared Core host | Node readable/writable streams and local IPC |
 | `readCoreLaunchContext()` | function | `arcane-os/core/host` | Native Core host composition | Node; combines packaged defaults, host state and explicitly selected launch JSON |
@@ -8886,6 +8888,31 @@ try {
 }
 ```
 
+## connectAppControl()
+
+```text
+connectAppControl({endpoint,signal,onError}={})
+```
+
+Connects once to the explicit running native window and resolves
+`{endpoint,closed,status,inspect,capture,act,close}`. The Windows host selects its
+own listener through `native.launchContext.appControl.endpoint` and preserves the
+existing Core child, origin, profile and application lifetime. The client uses
+portable Node local IPC; other native host adapters do not yet implement these
+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
+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()`
+cancels this connection's requests and returns `closed`, without closing the app.
+Document changes and actual errors remain observable; a dispatched action is
+not reversed by later cancellation. Full parameter/result, CLI and platform
+contracts are in [native application control](native-app-control.md).
+
 ## runSharedCoreHost()
 
 Accepts the same options as `startSharedCoreHost(options)` and adds the headless

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.81.0",
+  "version": "0.82.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -62,6 +62,7 @@
     "./core/development": "./src/core/development.mjs",
     "./core/stdio": "./src/core/stdio.mjs",
     "./core/host": "./src/core/host.mjs",
+    "./core/app-control": "./src/core/app-control.mjs",
     "./codex/app-server": "./src/codex/app-server.mjs",
     "./mcp/stdio": "./src/mcp/stdio-server.mjs",
     "./core/repositories": "./src/core/repositories.mjs",

package/runtime/arcane/components/chat.html

@@ -886,6 +886,7 @@
     const aiActivationButton=shadowRoot.querySelector('#ai_activation_button');
     const [
         {default:MD},
+        {hydrateMarkdownMedia},
         {default:FileEntity},
         {ConversationSubmissionBarrier,requireConversationTimeboxDelivery},
         {requestAIRuntimeIntent,subscribeAIRuntimeState},
@@ -893,6 +894,7 @@
         {getBrowserDeviceClass}
     ]=await Promise.all([
         import('../modules/MD.js'),
+        import('../modules/MarkdownMedia.js'),
         import('../entities/File.js'),
         import('../modules/ConversationTimebox.js'),
         import('../modules/AIRuntimeState.js'),
@@ -946,15 +948,19 @@
     let destroyed=false;
     let recognitionDraft=null;
     let writingRecognitionDraft=false;
+    const transcriptMedia=new Map();
+    let printMediaRetains=null;
     const printViewPromise=import('../modules/PrintView.js').then(
         function registerChatPrint({createPrintView}){
             if(destroyed) return null;
             return createPrintView({
                 host,
-                content:function chatPrintContent(){return chatOutput;},
+                content:renderedChatPrintContent,
                 title:function chatPrintTitle(){return host.printTitle||'Conversation';},
                 active:function chatPrintActive(){return !destroyed&&chatOutput.children.length>0;},
                 signal:aiRuntimeStateAbortController.signal,
+                retain:retainChatPrintMedia,
+                prepare:prepareChatPrintMedia,
                 onError:reportChatPrintFailure
             });
         }
@@ -1190,6 +1196,7 @@
             for(const item of record.removedNodes) {
                 if(item.localName === 'li' && item.parentElement !== chatOutput) {
                     transcriptResizeObserver?.unobserve(item);
+                    releaseTranscriptMessageMedia(item);
                 }
             }
             for(const item of record.addedNodes) {
@@ -1427,14 +1434,72 @@
         return entry;
     }
 
+    function renderTranscriptMarkdown(target,content){
+        if(destroyed) return null;
+        const template=target.ownerDocument.createElement('template');
+        template.innerHTML=new MD(content).rendered;
+        const pending=[...template.content.querySelectorAll('img')].some(
+            function localChatImage(image){
+                return image.getAttribute('src')?.startsWith('arcane-media:');
+            }
+        );
+        // Remove local-reference src values while detached; text renders now,
+        // and the shared media owner observes independent storage and decoding.
+        const handle=hydrateMarkdownMedia(template.content,{
+            signal:aiRuntimeStateAbortController.signal
+        });
+        releaseTranscriptMarkdown(target);
+        const media={handle,pending,error:null,status:null,ready:null};
+        transcriptMedia.set(target,media);
+        if(printMediaRetains){
+            printMediaRetains.add(handle.retain());
+        }
+        target.raw=content;
+        target.replaceChildren(template.content);
+        media.ready=handle.ready.then(function transcriptImagesReady(){
+            media.pending=false;
+        },function transcriptImagesFailed(error){
+            media.pending=false;
+            media.error=error;
+            if(destroyed||transcriptMedia.get(target)!==media) return;
+            arcaneLogging.error('Unable to display saved Chat images.',error);
+            const status=target.ownerDocument.createElement('p');
+            status.className='message_media_status';
+            status.setAttribute('role','status');
+            status.textContent='Some saved images could not be displayed.';
+            media.status=status;
+            target.after(status);
+            scrollTranscriptToBottom();
+        });
+        return media;
+    }
+
+    function releaseTranscriptMarkdown(target){
+        const media=transcriptMedia.get(target);
+        if(!media) return;
+        transcriptMedia.delete(target);
+        media.status?.remove();
+        media.handle.destroy();
+    }
+
+    function releaseTranscriptMessageMedia(item){
+        const markdown=item?.querySelector('.markdown');
+        if(markdown) releaseTranscriptMarkdown(markdown);
+    }
+
+    function removeTranscriptMessage(item){
+        if(!item) return;
+        releaseTranscriptMessageMedia(item);
+        item.remove();
+    }
+
     function setTranscriptMessageContent(item,content,timestamp){
         if(!is.string(content)){
             throw new TypeError('Chat session message content must be a string.');
         }
         item.querySelector('.thinking')?.remove();
         const markdown=item.querySelector('.markdown');
-        markdown.raw=content;
-        markdown.innerHTML=new MD(content).rendered;
+        renderTranscriptMarkdown(markdown,content);
         if(timestamp!==undefined){
             item.querySelector('.message_timestamp')?.replaceWith(
                 transcriptTime(timestamp)
@@ -1495,12 +1560,11 @@
         header.append(heading);
         const markdown=chatOutput.ownerDocument.createElement('div');
         markdown.className='markdown';
-        markdown.raw=content;
-        markdown.innerHTML=new MD(content).rendered;
         item.append(header,markdown,transcriptTime(timestamp));
         for(const call of normalizeVisibleToolCalls(toolCalls)){
             appendVisibleToolCall(item,call);
         }
+        renderTranscriptMarkdown(markdown,content);
         return item;
     }
 
@@ -1642,6 +1706,9 @@
         setPendingStructuralToolCalls(
             actionable?[...restoredPendingToolCalls.values()]:[]
         );
+        for(const item of chatOutput.children){
+            releaseTranscriptMessageMedia(item);
+        }
         chatOutput.replaceChildren(fragment);
         transcriptFollowing = true;
         transcriptScrollTop = chatOutput.scrollTop;
@@ -3034,9 +3101,7 @@
             thinkingHTML.remove();
         }
         
-        target.raw ? target.raw+=text : target.raw=text;
-
-        target.innerHTML=new MD(target.raw).rendered;
+        renderTranscriptMarkdown(target,target.raw?target.raw+text:text);
         
         scrollTranscriptToBottom();
     }
@@ -3393,8 +3458,7 @@
         message.querySelector('.thinking')?.remove();
         const markdown=message.querySelector('.markdown');
         const text=visibleErrorMessage(error,'The AI request failed.');
-        markdown.raw=text;
-        markdown.innerHTML=new MD(text).rendered;
+        renderTranscriptMarkdown(markdown,text);
         scrollTranscriptToBottom();
         return true;
     }
@@ -3421,8 +3485,8 @@
         const response=[...chatOutput.children].find(
             candidate=>candidate.id===`message-${messageId}`
         )||null;
-        response?.remove();
-        for(const request of requestMessages) request.remove();
+        removeTranscriptMessage(response);
+        for(const request of requestMessages) removeTranscriptMessage(request);
         const existing=textArea.value;
         if(existing!==text){
             textArea.value=existing
@@ -3500,7 +3564,7 @@
         function removeTransientSessionCards(){
             if(retainTurn||!transientCards.length) return;
             // The submitter supplies only nodes created for this submission.
-            for(const card of transientCards) card.remove();
+            for(const card of transientCards) removeTranscriptMessage(card);
             transientCards.length=0;
             scrollTranscriptToBottom();
         }
@@ -3675,9 +3739,9 @@
                     const response=[...chatOutput.children].find(
                         candidate=>candidate.id===`message-${messageId}`
                     )||null;
-                    response?.remove();
+                    removeTranscriptMessage(response);
                     for(const requestMessage of requestMessages){
-                        requestMessage.remove();
+                        removeTranscriptMessage(requestMessage);
                     }
                     scrollTranscriptToBottom();
                 }else if(retainTurn){
@@ -3692,7 +3756,7 @@
                 arcaneLogging.error('Arcane chat request failed.',error);
                 if(sessionRequestMessages.every(message=>message.role==='tool')){
                     for(const requestMessage of requestMessages){
-                        requestMessage.remove();
+                        removeTranscriptMessage(requestMessage);
                     }
                 }
                 if(retainTurn) renderSessionMessageFailure(messageId,error);
@@ -4136,11 +4200,64 @@
         return message;
     }
 
+    function renderedChatPrintContent(){
+        for(const media of transcriptMedia.values()){
+            if(media.pending){
+                const error=new Error('Saved images are still loading. Print again when they finish.');
+                error.code='ARCANE_MARKDOWN_MEDIA_PENDING';
+                throw error;
+            }
+            if(media.error) throw media.error;
+        }
+        return chatOutput;
+    }
+
+    function retainChatPrintMedia(){
+        renderedChatPrintContent();
+        const releases=new Set();
+        for(const media of transcriptMedia.values()){
+            releases.add(media.handle.retain());
+        }
+        printMediaRetains=releases;
+        return function releaseChatPrintMedia(){
+            if(printMediaRetains===releases){
+                printMediaRetains=null;
+            }
+            for(const release of releases) release();
+            releases.clear();
+        };
+    }
+
+    async function prepareChatPrintMedia(signal){
+        let cancel;
+        const cancelled=new Promise(function waitForChatPrintCancellation(resolve){cancel=resolve;});
+        signal?.addEventListener('abort',cancel,{once:true});
+        try{
+            while(!destroyed&&!signal?.aborted){
+                const selected=[...transcriptMedia];
+                await Promise.race([
+                    Promise.all(selected.map(function readyChatMedia([,media]){return media.ready;})),
+                    cancelled
+                ]);
+                if(destroyed||signal?.aborted) return false;
+                if(selected.length!==transcriptMedia.size||selected.some(
+                    function replacedChatMedia([target,media]){return transcriptMedia.get(target)!==media;}
+                )) continue;
+                renderedChatPrintContent();
+                return true;
+            }
+            return false;
+        }finally{
+            signal?.removeEventListener('abort',cancel);
+        }
+    }
+
     async function print(){
         if(destroyed) return false;
         try{
             const view=await printViewPromise;
-            return destroyed||!view?false:await view.print();
+            if(destroyed||!view||!await prepareChatPrintMedia()) return false;
+            return await view.print();
         }catch(error){
             reportChatPrintFailure(error);
             throw error;
@@ -4150,7 +4267,9 @@
     function reportChatPrintFailure(error){
         arcaneLogging.error('Unable to print the conversation.',error);
         if(!destroyed){
-            setSessionStatus('error','Unable to open print preview. Please try again.');
+            setSessionStatus('error',error?.code==='ARCANE_MARKDOWN_MEDIA_PENDING'
+                ?'Saved images are still loading. Print again when they finish.'
+                :'Unable to open print preview. Please try again.');
         }
     }
 
@@ -4235,6 +4354,9 @@
             ownership.abort(destroyReason);
         }
         aiRuntimeStateAbortController.abort(destroyReason);
+        for(const target of transcriptMedia.keys()){
+            releaseTranscriptMarkdown(target);
+        }
         aiActivationController.destroy();
         window.removeEventListener('pagehide',handlePageHide);
         window.removeEventListener('pageshow',handlePageShow);

package/src/cli/app-control.mjs

@@ -0,0 +1,106 @@
+import {readFile, writeFile} from 'node:fs/promises';
+import path from 'node:path';
+import {connectAppControl} from '../core/app-control.mjs';
+import {CoreError, serializeCoreError} from '../../browser-runtime/core/contracts.mjs';
+
+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 capture --endpoint <pipe-or-socket> --output <png-file>
+  arcane app-control act --endpoint <pipe-or-socket> --request <json-file>
+
+Connects to the selected running native window. Results are complete JSON.
+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.
+`;
+
+function usage(message) {
+    throw new CoreError({code: 'APP_CONTROL_USAGE', message, exitCode: 2});
+}
+
+function parseArguments(argv) {
+    if (!argv.length || argv.includes('--help') || argv.includes('-h')) return {help: true};
+    const [action] = argv;
+    const allowed = {
+        status: ['endpoint'],
+        inspect: ['endpoint', 'selector'],
+        capture: ['endpoint', 'output'],
+        act: ['endpoint', 'request']
+    }[action];
+    if (!Array.isArray(allowed)) usage('Expected app-control status, inspect, capture, or act.');
+    const values = {};
+    for (let index = 1; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const equal = argument.indexOf('=');
+        const option = equal === -1 ? argument : argument.slice(0, equal);
+        if (!option.startsWith('--') || !allowed.includes(option.slice(2))) {
+            usage(`Unexpected argument for app-control ${action}: ${argument}`);
+        }
+        const value = equal === -1 ? argv[++index] : argument.slice(equal + 1);
+        if (value === undefined || value === '' || (equal === -1 && value.startsWith('--'))) {
+            usage(`${option} requires a value.`);
+        }
+        values[option.slice(2)] = value;
+    }
+    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>.');
+    return {action, ...values};
+}
+
+/** This command owns its filename option before the general output-mode parser. */
+export async function runAppControlCli(argv, {cwd = process.cwd(), stdout = process.stdout,
+    stderr = process.stderr, controller = new AbortController()} = {}) {
+    let connection;
+    let result;
+    const failures = [];
+    function failed(error) {
+        if (!failures.includes(error)) failures.push(error);
+    }
+    function interrupted() { controller.abort(new Error('Interrupted')); }
+    process.once('SIGINT', interrupted);
+    process.once('SIGTERM', interrupted);
+    try {
+        const selection = parseArguments(argv);
+        if (selection.help) {
+            stdout.write(HELP_TEXT);
+            return 0;
+        }
+        stderr.write(`${JSON.stringify({status: 'running', operation: selection.action,
+            endpoint: selection.endpoint})}\n`);
+        const signal = controller.signal;
+        const parameters = selection.action === 'act'
+            ? 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});
+        if (selection.action === 'status') result = await connection.status({signal});
+        else if (selection.action === 'inspect') result = await connection.inspect(parameters, {signal});
+        else if (selection.action === 'act') result = await connection.act(parameters, {signal});
+        else {
+            result = await connection.capture(parameters, {signal});
+            const output = path.resolve(cwd, selection.output);
+            await writeFile(output, Buffer.from(result.data, 'base64'), {signal});
+            const {data, ...metadata} = result;
+            result = {...metadata, output};
+        }
+    } catch (error) {
+        failed(error);
+    } finally {
+        if (connection) {
+            try { await connection.close(); } catch (error) { failed(error); }
+        }
+        process.removeListener('SIGINT', interrupted);
+        process.removeListener('SIGTERM', interrupted);
+    }
+    if (failures.length) {
+        const error = failures.length === 1 ? failures[0]
+            : new AggregateError(failures, 'App control completed with errors.');
+        stderr.write(`${JSON.stringify({...(result === undefined ? {} : {result}),
+            error: serializeCoreError(error)}, null, 2)}\n`);
+        return controller.signal.aborted ? 130 : error.exitCode ?? 1;
+    }
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+}

package/src/cli/main.mjs

@@ -6,6 +6,7 @@ import {ArcaneError,ERROR_CODES,normalizeError} from '../errors.mjs';
 import {CLI_NAME,SDK_NAME,SDK_VERSION,OUTPUT_MODES} from '../constants.mjs';
 import {loadArcaneNativeProvider} from '../native-provider-loader.mjs';
 import {APP_BUNDLE_EXTENSION} from '../release-bundle.mjs';
+import {runAppControlCli} from './app-control.mjs';
 
 const is = new Is(false);
 
@@ -82,6 +83,7 @@ Usage:
   ${CLI_NAME} run [--target <target>] [--app <id>] [--cert <pem>] [--key <pem>] [--port 8000] [--http-port 0] [--arcane-root <directory>] [--output-root <directory>] [--format <format>] [--signing <mode>]
   ${CLI_NAME} update-check
   ${CLI_NAME} targets
+  ${CLI_NAME} app-control status|inspect|capture|act --endpoint <pipe-or-socket> [--help]
   ${CLI_NAME} repo status|pull|push
   ${CLI_NAME} mail key set [profile] [--secret-stdin]
   ${CLI_NAME} mail key status [profile]
@@ -942,6 +944,9 @@ export async function runCli(argv=process.argv.slice(2),{
     loadNativeProvider=loadArcaneNativeProvider,
     controller=new AbortController()
 }={}){
+    if(argv[0]==='app-control'){
+        return runAppControlCli(argv.slice(1),{cwd,stdout,stderr,controller});
+    }
     let reporter;
     let command='help';
     const onSignal=()=>controller.abort(new Error('Interrupted'));