arcane-os 0.86.0 → 0.87.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.87.0
+
+- Add `createDocumentAcquisitionService` through
+  `arcane-os/core/document-acquisition` and `acquireCoreDocument` through
+  `arcane-os/document-acquisition`. Applications can acquire selected HTTP(S)
+  documents through their existing native Core without depending on browser
+  cross-origin access.
+- Preserve complete response bodies, requested and final URLs, response
+  metadata and ordered redirect evidence. An optional application-owned
+  destination predicate runs before each native request; domain selection and
+  document interpretation remain application policy.
+- Correlate semantic progress and cancellation with the existing Core request,
+  preserve complete error evidence, and return browser bodies as `Blob`
+  objects. Native service disposal cancels and joins its owned operations.
+  No dependency or compiled native host change is required.
+
+## 0.86.1
+
+- Include the existing public `arcane-os/ai/model-observation` export in
+  generated browser import maps. Both managed application maps and standalone
+  document maps resolve the same published browser module, including direct
+  installed-package URLs and nested documents.
+- Consumers adopt the published package and run their normal import-map
+  generation before rebuilding or serving their application. No manual map
+  edits, alternate imports or new native host build are required. The matching
+  Windows and Whisper runtime assets are unchanged from 0.86.0.
+
 ## 0.86.0
 
 - Add fixed `Tab`, `Shift+Tab`, `Enter` and `Space` key operations to

package/README.md

@@ -25,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.86.0` SDK contract. Development applications declare
+This checkout defines the `0.87.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/contracts.mjs

@@ -19,6 +19,7 @@ export const CORE_METHOD_CONTRACTS={
     'capabilities.list':{input:'empty-object',output:'{app,grants,methods}'},
     'platform.status':{input:'empty-object-v1',output:'platform-status-v1'},
     'network.status':{input:'empty-object-v1',output:'network-status-v1',meaning:'A non-loopback interface is present; this is not proof of Internet reachability.'},
+    'documents.acquire':{input:'{url}',output:'document-acquisition-result-v1',meaning:'Complete HTTP(S) GET response and redirects; native application owns any optional destination predicate. Request-scoped documents.progress events.'},
     'apps.list':{input:'empty-object-v1',output:'application-catalog-v1'},
     'apps.launch':{input:'application-launch-v1',output:'application-launch-result-v1',meaning:'Host acceptance, not application readiness.'},
     'external.open':{input:'external-open-v1',output:'external-open-result-v1',meaning:'Host acceptance, not confirmation of a user action.'},

package/browser-runtime/document-acquisition.mjs

@@ -0,0 +1,112 @@
+import Is from './dependencies/strong-type/index.js';
+import {getInstalledCoreClient} from './core/client.mjs';
+import {CoreError, serializeCoreError} from './core/contracts.mjs';
+
+const is = new Is(false);
+
+/** Acquires one complete document through the application's installed native service. */
+export async function acquireCoreDocument({url, client = getInstalledCoreClient(), signal, onProgress} = {}) {
+    if (!is.function(client?.invoke) || !is.function(client?.events?.on)) {
+        throw new CoreError({
+            code: 'DOCUMENT_ACQUISITION_CORE_UNAVAILABLE',
+            message: 'Document acquisition requires an available native Core connection.'
+        });
+    }
+    if (!is.string(url) || url === '') {
+        throw new TypeError('Document acquisition url must be a nonempty string.');
+    }
+    if (onProgress !== undefined && !is.function(onProgress)) {
+        throw new TypeError('Document acquisition onProgress must be a function.');
+    }
+    const controller = new AbortController();
+    const operationSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    operationSignal.throwIfAborted();
+    const observers = new Set();
+    let requestId;
+    let active = true;
+    const observerErrors = [];
+
+    function retainObserverFailure(error) {
+        observerErrors.push(error);
+        controller.abort(error);
+    }
+
+    const unsubscribe = client.events.on('documents.progress', function documentProgress(progress) {
+        if (!active || operationSignal.aborted || !requestId || progress.requestId !== requestId || !onProgress) return;
+        let observation;
+        try { observation = Promise.resolve(onProgress(progress)); }
+        catch (error) { retainObserverFailure(error); return; }
+        observers.add(observation);
+        function observed() { observers.delete(observation); }
+        observation.then(observed, function failed(error) {
+            observed();
+            retainObserverFailure(error);
+        });
+    });
+
+    let result;
+    let failed = false;
+    let failure;
+    try {
+        result = await client.invoke('documents.acquire', {url}, {
+            signal: operationSignal, timeoutMs: 0,
+            onRequest(request) { requestId = request.requestId; }
+        });
+    } catch (error) {
+        failed = true;
+        failure = error;
+    } finally {
+        active = false;
+        try { unsubscribe(); } catch (error) { observerErrors.push(error); }
+        await Promise.allSettled([...observers]);
+    }
+    if (failed) failure = decodeFailure(failure);
+    let document;
+    if (!failed) {
+        const {redirects, ...response} = result;
+        document = {...decodeResponse(response), redirects: redirects.map(decodeResponse)};
+    }
+    if (observerErrors.length) {
+        const error = !failed && observerErrors.length === 1
+            ? new CoreError({...serializeCoreError(observerErrors[0]), cause: observerErrors[0]})
+            : new AggregateError(
+                failed ? [failure, ...observerErrors] : observerErrors,
+                'Document acquisition progress observers failed.',
+                failed ? {cause: failure} : undefined
+            );
+        if (document) {
+            const {requestedUrl, finalUrl, redirects, ...response} = document;
+            error.documentAcquisition = {requestedUrl, requestUrl: finalUrl, redirects, response};
+        } else if (failure?.documentAcquisition) {
+            error.documentAcquisition = failure.documentAcquisition;
+        }
+        throw error;
+    }
+    if (failed) throw failure;
+    operationSignal.throwIfAborted();
+    return document;
+}
+
+function decodeFailure(error) {
+    if (!error?.documentAcquisition) return error;
+    const {response, redirects, ...metadata} = error.documentAcquisition;
+    return new CoreError({
+        ...serializeCoreError(error),
+        documentAcquisition: {
+            ...metadata,
+            redirects: redirects.map(decodeResponse),
+            ...(response ? {response: decodeResponse(response)} : {})
+        }
+    });
+}
+
+function decodeResponse(response) {
+    const {body, ...metadata} = response;
+    if (body.encoding !== 'base64') {
+        throw new TypeError(`Unsupported document transport encoding ${body.encoding}.`);
+    }
+    const content = Uint8Array.from(globalThis.atob(body.data), function decodeCharacter(character) {
+        return character.charCodeAt(0);
+    });
+    return {...metadata, body: new Blob([content], {type: metadata.mediaType ?? ''})};
+}

package/docs/reference/document-acquisition.md

@@ -0,0 +1,159 @@
+# Native document acquisition
+
+`acquireCoreDocument` from `arcane-os/document-acquisition` retrieves one
+HTTP(S) document through the application's selected native Core service.
+`createDocumentAcquisitionService` from `arcane-os/core/document-acquisition`
+owns the reusable native acquisition. It performs a GET, follows redirects
+manually, and retains the complete response bodies without parsing or rewriting
+the document. Applications own source selection, document interpretation,
+enumeration, storage, and any destination predicate.
+
+## Application composition
+
+Select an application-owned native factory through the existing
+[`native.services` composition](core-native-packaging.md#explicit-application-services).
+Include its source through the application's `package.nativeResources` as
+described there. The factory runs in the native Core process; its options are
+JSON data, while its predicate is an ordinary locally imported function.
+Functions are never serialized through Core RPC.
+
+```js
+// native/documents.mjs, owned by the application
+import {createDocumentAcquisitionService} from 'arcane-os/core/document-acquisition';
+
+export default function createDocuments() {
+    return createDocumentAcquisitionService();
+}
+```
+
+```json
+{
+    "native": {
+        "services": [{"module": "native/documents.mjs"}]
+    }
+}
+```
+
+The ordinary service works without a predicate. When an application selects a
+destination restriction, its native factory supplies
+`createDocumentAcquisitionService({destinationPredicate})`. The SDK awaits
+`destinationPredicate(destinationUrl, {requestedUrl, previousUrl, signal})`
+before **every** HTTP(S) request, including the first URL and each redirect.
+Return `true` to request that destination. Any other return value declines it
+with `DOCUMENT_DESTINATION_DECLINED`. A thrown or rejected error remains the
+acquisition error's original `cause`. The predicate receives the resolved URL
+string, the caller's original URL string, the prior response URL or `null`, and
+the operation's signal. It stays local to the application's native process.
+
+An asynchronous predicate must finish or honor its signal so native shutdown
+can join it. There is no automatic retry or redirect-count limit. The caller
+can cancel its operation, including a repeating redirect chain. Redirects
+with statuses 301, 302, 303, 307, and 308 follow their `Location`, resolved
+against the response URL. A response without a redirect destination is returned
+as received. The service performs GET on each destination; it does not submit
+forms or add application credentials.
+
+## Browser API
+
+```js
+import {acquireCoreDocument} from 'arcane-os/document-acquisition';
+
+const cancellation = new AbortController();
+const document = await acquireCoreDocument({
+    url: selectedDocumentUrl,
+    signal: cancellation.signal,
+    onProgress(progress) {
+        status.textContent = progress.phase;
+    }
+});
+
+// The original entity content is available even for an HTTP error response.
+const completeContent = document.body; // Blob
+const receivedSuccessfully = document.ok;
+```
+
+The options are `{url, client?, signal?, onProgress?}`. `client` defaults to the
+installed Core client. The helper invokes `documents.acquire` with `{url}`;
+callbacks and the signal stay local. It uses existing request cancellation and
+`documents.progress` subscriptions, with no extra event bus or transport.
+There is no implicit request timeout. The caller owns any selected deadline
+through its signal.
+
+The native service must be selected by the application. An absent Core client
+reports `DOCUMENT_ACQUISITION_CORE_UNAVAILABLE`; an installed Core without the
+service returns its existing unavailable-method error. Browser-only preview
+does not acquire native capability and does not silently switch to browser
+Fetch. Portable Windows, Linux, and macOS applications use their existing Core
+transport; Android requires its host to provide this same native service.
+
+The result contains:
+
+| Field | Meaning |
+| --- | --- |
+| `requestedUrl` | Caller-supplied URL string, retained unchanged. |
+| `finalUrl` / `url` | Final response URL reported by Fetch. |
+| `status`, `statusText`, `ok` | Actual Fetch response status fields. `ok:false` is returned with its body, not replaced by a generic error. |
+| `headers` | All entries exposed by the Fetch `Headers` object, represented as `[name, value]` pairs. |
+| `mediaType` | Complete `Content-Type` field value exposed by Fetch, or `null`. |
+| `body` | Complete entity content as a `Blob` in the browser and a `Uint8Array` in native calls. |
+| `complete` | `true` after the response body reaches its end. |
+| `redirects` | Ordered preceding response records, each with `url`, status fields, headers, media type, body, and completion state. |
+
+The content is the response entity supplied by Fetch, including Fetch's normal
+content-decoding behavior. It is not a capture of compressed network framing.
+Likewise, headers reflect Fetch's casing and combination behavior; the SDK does
+not invent original wire casing or unavailable header distinctions. Document
+content is never converted to text, normalized, summarized, or wrapped in
+instructions. Query and progress metadata remain outside the content.
+
+## Progress, cancellation, and errors
+
+Progress records contain `phase`, `completed`, `total:1`, `unit:'documents'`,
+`requestedUrl`, and the current `url`. Browser records additionally contain
+the originating `requestId`. Phases are `accepted`, `destination`, `request`,
+`response`, `redirect`, and `complete`. The completed count becomes one only
+after the final response has been fully acquired, including an HTTP error
+response. Status fields, not acquisition progress, establish HTTP success.
+Progress does not measure content and carries no document body.
+
+The browser helper filters request-correlated events and removes its listener
+on every settlement. Synchronous or asynchronous progress callbacks are
+observed; all accepted callback promises settle before the helper settles.
+A callback failure cancels the request and remains observable. Simultaneous
+operation and callback failures are retained in an `AggregateError`.
+If a callback or subscription cleanup fails after the complete response has
+arrived, that response remains in the error's `documentAcquisition` evidence;
+the original callback failure remains its `cause` or an aggregated error.
+Callbacks must finish or honor the application's cancellation signal.
+
+Native acquisition errors retain the original thrown value as `cause` and
+include `documentAcquisition: {requestedUrl, requestUrl, redirects, response?}`.
+Every acquired redirect body is retained. If reading a response fails, its
+available original content is retained with `complete:false`; that record is
+explicitly incomplete. Cleanup failures remain observable alongside the
+original error. On errors delivered through Core, the browser helper restores
+the response and redirect bodies as Blobs and retains the native error record.
+
+An abort uses the existing Core client's immediate local rejection and sends
+request cancellation to the native owner. That local cancellation does not
+wait for a native error record or return its response evidence. The native
+owner cancels and joins its active response reader. Independent acquisitions
+remain concurrent, and cancelling one request leaves sibling requests active.
+Service `dispose()` aborts and joins all of that service's active operations.
+
+## Native calls and transport
+
+The synchronous factory accepts `{destinationPredicate?, signal?}` and returns
+the existing Core service definition plus
+`acquire({url, signal?, onProgress?})` and idempotent asynchronous `dispose()`.
+Direct native results and error evidence contain `Uint8Array` bodies (Node
+Buffers implement that interface). The optional factory signal controls the
+service lifetime; a per-call signal controls only that acquisition.
+
+At the JSON RPC boundary only, each body becomes
+`{encoding:'base64', data:'...'}`. One final response carries the complete result
+and ordered redirect records. The browser decodes those transport fields into
+Blobs. This path buffers complete response bodies; phase events are not a
+body stream and do not supply streaming backpressure. Existing Core lifecycle,
+request routing, and connection-close cancellation retain ownership of the
+operation through native settlement.

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

@@ -1,17 +1,45 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.85.0",
+  "sdkVersion": "0.86.1",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 306,
+  "memberCount": 308,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "core-document-acquisition:createDocumentAcquisitionService",
+      "name": "createDocumentAcquisitionService",
+      "displayName": "createDocumentAcquisitionService()",
+      "kind": "function",
+      "signature": "createDocumentAcquisitionService({destinationPredicate,signal}={})",
+      "entrypoints": ["arcane-os/core/document-acquisition"],
+      "primaryImport": "arcane-os/core/document-acquisition",
+      "group": "Native document acquisition",
+      "summary": "Acquires complete HTTP(S) documents in the native Core process with application-owned destination selection before every request.",
+      "availability": "Node Core on Windows, Linux and macOS; Android requires the same service through its host adaptation",
+      "protocol": "arcane/1 documents.acquire and request-correlated documents.progress; selected through the existing application-native service factory contract",
+      "normalization": "Returns name:documents, methods, acquire({url,signal,onProgress}) and idempotent asynchronous dispose(). GET follows 301/302/303/307/308 manually, awaiting the optional native destinationPredicate(url,{requestedUrl,previousUrl,signal}) before every request; only true proceeds. Omission leaves ordinary acquisition functional. Results retain requestedUrl, finalUrl/url, actual Fetch status/statusText/ok, all exposed header entries, mediaType, complete Uint8Array body and ordered complete redirect records, including non-2xx bodies. Fetch entity decoding is distinct from compressed wire framing. Errors retain their cause and complete available response evidence, with interrupted bodies marked complete:false. Independent jobs remain concurrent; cancellation stops the selected job and dispose aborts and joins all owned work. Progress is phase/document-count information, never content measurement. Base64 is used only at JSON transport; no parsing, text transformation, storage, automatic retry or application domain policy. See document-acquisition.md for composition, fields and lifecycle."
+    },
+    {
+      "id": "document-acquisition:acquireCoreDocument",
+      "name": "acquireCoreDocument",
+      "displayName": "acquireCoreDocument()",
+      "kind": "function",
+      "signature": "async acquireCoreDocument({url,client=getInstalledCoreClient(),signal,onProgress}={})",
+      "entrypoints": ["arcane-os/document-acquisition"],
+      "primaryImport": "arcane-os/document-acquisition",
+      "group": "Native document acquisition",
+      "summary": "Retrieves a complete selected document as a Blob through the application's existing native Core connection.",
+      "availability": "JavaScript with an existing Core client and explicitly composed documents service; no browser-only Fetch fallback",
+      "protocol": "documents.acquire({url}) with existing cancellation and correlated documents.progress subscriptions",
+      "normalization": "Preserves complete native response metadata and ordered redirect evidence, decoding only transport base64 into Blobs. The installed Core client is the default; unavailable Core reports DOCUMENT_ACQUISITION_CORE_UNAVAILABLE and a missing service uses the existing Core method error. The native application owns the optional destination predicate; no function crosses RPC. onProgress receives complete phase/document-count records plus requestId; accepted synchronous/asynchronous callbacks are observed and joined on settlement, listener cleanup always runs, and simultaneous operation/callback failures remain observable. The caller signal owns cancellation and any deadline; timeoutMs is disabled for the acquisition. Existing Core cancellation rejects locally and sends native cancellation without waiting for a native error evidence response. Complete bodies are buffered for one final RPC response; progress events are not streaming body backpressure. See document-acquisition.md for public usage and errors."
+    },
     {
       "id": "core-model-observation:createModelObservationService",
       "name": "createModelObservationService",
@@ -63,10 +91,10 @@
       "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.",
+      "summary": "Connects to one explicit running native window for background document inspection, viewport capture, targeted DOM actions, fixed keys and Normal-window client resizing.",
       "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."
+      "protocol": "arcane/1 app.control.status, app.control.inspect, app.control.capture, app.control.act, app.control.key and app.control.resize over the existing framed local connection. The window host selects native.launchContext.appControl.endpoint and preserves its existing Core child, origin, profile and lifetime; assembly requires a matching published Windows host asset.",
+      "normalization": "Returns endpoint, closed, status(options), inspect(parameters={},options), capture(parameters={},options), act(parameters,options), key(parameters,options), resize(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, plus top-level viewport CSS dimensions/devicePixelRatio, documentHasFocus and focusPath through the active open-shadow branch; focus records are observations with null selectors, separate from the selected root's activeElement. 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. Key requires documentGeneration and Tab, Enter or Space; shiftKey:true is supported only for Tab. One keyboard owner keeps each press/release pair ordered at the selected WebView's current focus. An attempted press owns a matching release even after cancellation, navigation or failure; no failed or ambiguous press is replayed. Generation checks bracket native input without atomic document binding. Resize accepts positive integral native client width/height supported by WinForms and optional documentGeneration, changes only a Normal window's ClientSize, and returns immediate previous/actual native dimensions plus the later observed CSS viewport. Native and CSS snapshots are not atomic; platform constraints may change actual dimensions. Restoration is an explicit resize using the operation's previous native dimensions; unsupported window states fail before mutation. The native document marker prevents queued DOM actions crossing replacement; cancellation before dispatch prevents execution while dispatched work is observed through completion without retry or reversal, including owned key release. Partial results remain in actual errors and complete later responses remain in host diagnostics after cancellation or disconnection. Dispatch completion does not establish application handler completion or a successful business action. 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; act, key and resize forward their complete --request parameter objects. See native-app-control.md for complete result fields, CLI and platform scope."
     },
     {
       "id": "local-ai-execution-devices:createExecutionDeviceCatalog",

package/docs/reference/model-observation.md

@@ -45,6 +45,13 @@ retain their separate [app-control contract](native-app-control.md).
 
 ## Attach existing renderer owners
 
+SDK 0.86.1 adds the public `arcane-os/ai/model-observation` export to normal
+generated browser import maps. Development applications keep `arcane-os` on
+`latest`; after updating through their existing dependency workflow, run
+`arcane import-map` before building or serving. The mapping uses the same
+published browser module and changes no observation runtime behavior. Regenerate
+through the public command rather than editing map entries by hand.
+
 ```js
 import * as aiRuntimeState from 'arcane-os/ai-runtime-state';
 import {attachModelObservation} from 'arcane-os/ai/model-observation';

package/docs/reference/sdk-api.md

@@ -9076,7 +9076,7 @@ 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
+`{endpoint,closed,status,inspect,capture,act,key,resize,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
@@ -9088,14 +9088,49 @@ and no automatic reconnect or action retry occurs.
 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
+Closed roots remain unavailable. Inspection also returns top-level `viewport`
+CSS-pixel width/height and `devicePixelRatio`, `documentHasFocus`, and `focusPath`
+through the active open-shadow branch. These focus records have null selectors
+and remain separate from the selected root's `activeElement`; frames and closed
+roots end the path. `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).
+fields.
+
+`key(parameters,options)` requires the observed `documentGeneration` and
+`key:'Tab'`, `'Enter'` or `'Space'`; `shiftKey:true` is supported only for Tab.
+It sends a fixed ordered press/release pair to the selected WebView's current
+focus, without selecting an element or activating the desktop window. Accepted
+pairs share one keyboard owner. Once a press is attempted, its matching release
+is attempted on the same WebView even after cancellation, navigation or failure;
+a failed or ambiguous press is never replayed. Results retain previous/actual
+document views and complete attempted/completed phase records. Generation checks
+bracket native input rather than atomically binding it to a document, so focus
+or navigation can change between phases.
+
+`resize(parameters,options)` accepts positive integral native client `width`
+and `height` supported by WinForms, plus optional `documentGeneration`. It changes
+only `ClientSize` while the actual window is `Normal`; maximized or minimized
+windows fail before size mutation. Results retain immediate `previous`/`actual`
+native dimensions, requested dimensions, attempted/completed flags and a later
+observed CSS `viewport`. Platform constraints can change actual dimensions;
+native and CSS observations are not an atomic snapshot. Restore explicitly with
+the same operation's `previous.width` and `previous.height`, not CSS dimensions
+or a historical status snapshot. Cancellation does not restore the window.
+
+Options preserve the Core client signal/timeout contract. Cancellation before
+dispatch prevents execution; dispatched work and owned key release remain
+observed through completion. Actual errors retain complete partial results;
+responses completed after cancellation or disconnection remain in host
+diagnostics. `close()` cancels this connection's requests and returns `closed`,
+without closing the app. Document changes and actual errors remain observable.
+Dispatch completion does not establish application handler completion or a
+successful business action; inspect the resulting built application to establish
+that outcome. Assembly requires a matching published Windows host asset.
+
+The CLI provides `app-control key` and `app-control resize`, each forwarding the
+complete parsed `--request` object. Full parameter/result, error, cancellation,
+CLI and platform contracts are in [native application control](native-app-control.md).
 
 ## runSharedCoreHost()
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.86.0",
+  "version": "0.87.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -19,6 +19,7 @@
     "./entities/*": "./runtime/arcane/entities/*",
     "./logging": "./browser-runtime/logging.mjs",
     "./browser-device": "./browser-runtime/browser-device.mjs",
+    "./document-acquisition": "./browser-runtime/document-acquisition.mjs",
     "./pwa": "./browser-runtime/pwa.mjs",
     "./preference-store": "./runtime/arcane/modules/PreferenceStore.js",
     "./ai": "./runtime/arcane/modules/AI.js",
@@ -69,6 +70,7 @@
     "./core/repositories": "./src/core/repositories.mjs",
     "./core/packaged-web": "./src/core/services/packaged-web.mjs",
     "./core/preferences": "./src/core/services/preferences.mjs",
+    "./core/document-acquisition": "./src/core/services/document-acquisition.mjs",
     "./core/diarization": "./src/diarization/service.mjs",
     "./core/local-ai": "./src/core/services/local-ai.mjs",
     "./core/execution-devices": "./src/core/services/execution-devices.mjs",
@@ -128,7 +130,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/native-windows-icon.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-kokoro-complete-input.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/execution-devices.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-kokoro-complete-input.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/document-acquisition.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/execution-devices.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/ai-audio-output.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/src/core/services/document-acquisition.mjs

@@ -0,0 +1,221 @@
+import {Buffer} from 'node:buffer';
+import Is from 'strong-type';
+import {CoreError, serializeCoreError} from '../../../browser-runtime/core/contracts.mjs';
+
+const is = new Is(false);
+const redirectStatuses = new Set([301, 302, 303, 307, 308]);
+
+/** The application supplies its optional destination decision in this native process. */
+export function createDocumentAcquisitionService({destinationPredicate, signal} = {}) {
+    if (destinationPredicate !== undefined && !is.function(destinationPredicate)) {
+        throw new TypeError('Document acquisition destinationPredicate must be a function.');
+    }
+    const lifetime = new AbortController();
+    const lifetimeSignal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+    const jobs = new Set();
+    let closing;
+
+    function acquire({url, signal: requestSignal, onProgress} = {}) {
+        if (!is.string(url) || url === '') {
+            throw new TypeError('Document acquisition url must be a nonempty string.');
+        }
+        if (onProgress !== undefined && !is.function(onProgress)) {
+            throw new TypeError('Document acquisition onProgress must be a function.');
+        }
+        const operationSignal = requestSignal
+            ? AbortSignal.any([lifetimeSignal, requestSignal]) : lifetimeSignal;
+        const evidence = {requestedUrl: url, requestUrl: url, redirects: []};
+
+        async function progress(phase, completed = 0) {
+            operationSignal.throwIfAborted();
+            await onProgress?.({
+                phase, completed, total: 1, unit: 'documents',
+                requestedUrl: url, url: evidence.requestUrl
+            });
+            operationSignal.throwIfAborted();
+        }
+
+        const task = Promise.resolve().then(async function acquireDocument() {
+            try {
+                await progress('accepted');
+                let destination = new URL(url);
+                while (true) {
+                    evidence.requestUrl = destination.href;
+                    if (destination.protocol !== 'http:' && destination.protocol !== 'https:') {
+                        throw new TypeError('Document acquisition requires an HTTP or HTTPS URL.');
+                    }
+                    await progress('destination');
+                    if (destinationPredicate !== undefined) {
+                        const accepted = await destinationPredicate(destination.href, {
+                            requestedUrl: url,
+                            previousUrl: evidence.redirects.at(-1)?.url ?? null,
+                            signal: operationSignal
+                        });
+                        operationSignal.throwIfAborted();
+                        if (accepted !== true) {
+                            throw new CoreError({
+                                code: 'DOCUMENT_DESTINATION_DECLINED',
+                                message: `The application declined document destination ${destination.href}.`
+                            });
+                        }
+                    }
+                    await progress('request');
+                    // Manual redirects keep the application decision ahead of every request.
+                    const response = await fetch(destination.href, {
+                        method: 'GET', redirect: 'manual', signal: operationSignal
+                    });
+                    const record = {
+                        url: response.url,
+                        status: response.status,
+                        statusText: response.statusText,
+                        ok: response.ok,
+                        headers: Array.from(response.headers.entries()),
+                        mediaType: response.headers.get('content-type'),
+                        body: new Uint8Array(),
+                        complete: false
+                    };
+                    evidence.response = record;
+                    await readResponse(response, record, operationSignal, function reading() {
+                        return progress('response');
+                    });
+                    const location = response.headers.get('location');
+                    if (redirectStatuses.has(record.status) && location !== null) {
+                        evidence.redirects.push(record);
+                        delete evidence.response;
+                        await progress('redirect');
+                        destination = new URL(location, response.url || destination.href);
+                        continue;
+                    }
+                    const result = {
+                        requestedUrl: url, finalUrl: response.url,
+                        ...record, redirects: evidence.redirects
+                    };
+                    await progress('complete', 1);
+                    return result;
+                }
+            } catch (cause) {
+                // Retain the original error as cause, including complete native properties.
+                throw new CoreError({
+                    ...serializeCoreError(cause), cause,
+                    documentAcquisition: evidence
+                });
+            }
+        });
+        jobs.add(task);
+        function settled() { jobs.delete(task); }
+        task.then(settled, settled);
+        return task;
+    }
+
+    async function acquireThroughCore(parameters, request) {
+        try {
+            const result = await acquire({
+                url: parameters.url,
+                signal: request.signal,
+                onProgress(progress) {
+                    request.emit('documents.progress', {
+                        requestId: request.clientRequestId ?? request.requestId,
+                        ...progress
+                    });
+                }
+            });
+            return encodeResult(result);
+        } catch (error) {
+            if (!error.documentAcquisition) throw error;
+            throw new CoreError({
+                ...serializeCoreError(error),
+                documentAcquisition: encodeEvidence(error.documentAcquisition)
+            });
+        }
+    }
+
+    function dispose() {
+        closing ??= Promise.resolve().then(async function closeAcquisitionService() {
+            lifetime.abort(new CoreError({
+                code: 'DOCUMENT_ACQUISITION_CLOSED',
+                message: 'The document acquisition service is closing.'
+            }));
+            await Promise.allSettled([...jobs]);
+        });
+        return closing;
+    }
+
+    return {
+        name: 'documents',
+        methods: {'documents.acquire': acquireThroughCore},
+        acquire,
+        dispose
+    };
+}
+
+async function readResponse(response, record, signal, onReading) {
+    const chunks = [];
+    const cleanupErrors = [];
+    let reader;
+    let cancellation;
+    let failed = false;
+    let failure;
+
+    function cancelReader(reason) {
+        if (!reader || cancellation) return;
+        cancellation = Promise.resolve().then(function cancelResponseBody() {
+            return reader.cancel(reason);
+        }).catch(function retainCleanupError(error) { cleanupErrors.push(error); });
+    }
+    function aborted() { cancelReader(signal.reason); }
+
+    try {
+        reader = response.body?.getReader();
+        signal.addEventListener('abort', aborted, {once: true});
+        if (signal.aborted) aborted();
+        await onReading();
+        while (reader) {
+            signal.throwIfAborted();
+            const {done, value} = await reader.read();
+            if (value !== undefined) chunks.push(Buffer.from(value));
+            if (done) {
+                signal.throwIfAborted();
+                break;
+            }
+        }
+        signal.throwIfAborted();
+        record.complete = true;
+    } catch (error) {
+        failed = true;
+        failure = error;
+        cancelReader(error);
+    } finally {
+        signal.removeEventListener('abort', aborted);
+        if (cancellation) await cancellation;
+        try { reader?.releaseLock(); } catch (error) { cleanupErrors.push(error); }
+        record.body = Buffer.concat(chunks);
+    }
+    if (cleanupErrors.length) {
+        throw new AggregateError(
+            failed ? [failure, ...cleanupErrors] : cleanupErrors,
+            'Document response cleanup failed.',
+            failed ? {cause: failure} : undefined
+        );
+    }
+    if (failed) throw failure;
+}
+
+function encodeResponse(record) {
+    const {body, ...metadata} = record;
+    // Encoding belongs only to the existing JSON Core transport.
+    return {...metadata, body: {encoding: 'base64', data: Buffer.from(body).toString('base64')}};
+}
+
+function encodeResult(result) {
+    const {redirects, ...response} = result;
+    return {...encodeResponse(response), redirects: redirects.map(encodeResponse)};
+}
+
+function encodeEvidence(evidence) {
+    const {response, redirects, ...metadata} = evidence;
+    return {
+        ...metadata,
+        redirects: redirects.map(encodeResponse),
+        ...(response ? {response: encodeResponse(response)} : {})
+    };
+}

package/src/import-map.mjs

@@ -44,6 +44,7 @@ const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/websocket-client','sdk/websocket-client.mjs'],
     ['arcane-os/core/client','sdk/core/client.mjs'],
     ['arcane-os/core/contracts','sdk/core/contracts.mjs'],
+    ['arcane-os/document-acquisition','sdk/document-acquisition.mjs'],
     ['arcane-os/logging','sdk/logging.mjs'],
     ['arcane-os/browser-device','sdk/browser-device.mjs'],
     ['arcane-os/pwa','sdk/pwa.mjs'],
@@ -53,6 +54,7 @@ const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/ai/core-onnx','sdk/ai/core-onnx.mjs'],
     ['arcane-os/ai/core-image','sdk/ai/core-image.mjs'],
     ['arcane-os/ai/core-model-assets','sdk/ai/core-model-assets.mjs'],
+    ['arcane-os/ai/model-observation','sdk/ai/model-observation.mjs'],
     ['arcane-os/ai/browser-decisions','sdk/ai/browser-decisions.mjs'],
     ['arcane-os/ai/tool-text-stream','sdk/ai/tool-text-stream.mjs'],
     ['arcane-os/ai/twin-cloud','sdk/ai/twin-cloud.mjs'],