arcane-os 0.84.0 → 0.86.0

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

@@ -1,17 +1,59 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.83.0",
+  "sdkVersion": "0.85.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 303,
+  "memberCount": 306,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "core-model-observation:createModelObservationService",
+      "name": "createModelObservationService",
+      "displayName": "createModelObservationService()",
+      "kind": "function",
+      "signature": "createModelObservationService({runtime,localAI=null,image=null,decisions=null}={})",
+      "entrypoints": ["arcane-os/core/model-observation"],
+      "primaryImport": "arcane-os/core/model-observation",
+      "group": "Existing model observation",
+      "summary": "Observes an existing Core runtime and supplied actual native model service owners without creating or starting them.",
+      "availability": "Node with an existing Core runtime and optional existing native model services",
+      "protocol": "arcane/1 model.observation current, watch, renderer.attach and renderer.publish methods",
+      "normalization": "Returns name:model-observation, current(), dispose() and four methods. Complete current snapshots retain core, optional native localAI/image/decisions and request-owned renderer attachments. Missing owners are null; watch diagnostics defaults false and explicit true exposes complete live failed response frames for supplied native method keys without retained failure history. Actual clientRequestId identifies acknowledgements; coreRequestId keys renderer lifetime. Disposal cancels only observation requests/subscriptions, never models or the supplied runtime. No getService, readiness barrier, model creation, inference, polling or fabricated operation identities."
+    },
+    {
+      "id": "ai-model-observation:attachModelObservation",
+      "name": "attachModelObservation",
+      "displayName": "attachModelObservation()",
+      "kind": "function",
+      "signature": "attachModelObservation({client,aiRuntimeState=null,imageRuntime=null,decisionModel=null,modelController=null,signal,onError}={})",
+      "entrypoints": ["arcane-os/ai/model-observation"],
+      "primaryImport": "arcane-os/ai/model-observation",
+      "group": "Existing model observation",
+      "summary": "Attaches the application's existing renderer model owners through its existing Core client.",
+      "availability": "JavaScript with an existing Core client and optional existing renderer owners",
+      "protocol": "Request-owned model.observation.renderer attachment and complete snapshot publication",
+      "normalization": "Returns ready, closed, current() and close(). Ready acknowledges actual attachmentRequestId/coreRequestId; subscriptions publish complete current owner snapshots and reread after acknowledgement. Existing Core serialization encodes owner Error fields at the JSON boundary without changing other fields. Abort, page retirement, exact installed-client retirement, transport failure or explicit close retires only observation RPCs/subscriptions and leaves models/client owned by the caller. Normal cancellation closes cleanly; pre-acknowledgement cancellation rejects ready. Other failures reject public promises and reach onError or complete console diagnostics. No automatic reattachment, owner creation, model work or page-render barrier."
+    },
+    {
+      "id": "ai-model-observation:subscribeModelObservation",
+      "name": "subscribeModelObservation",
+      "displayName": "subscribeModelObservation()",
+      "kind": "function",
+      "signature": "subscribeModelObservation({client,signal,onState,onDiagnostic,onError}={})",
+      "entrypoints": ["arcane-os/ai/model-observation"],
+      "primaryImport": "arcane-os/ai/model-observation",
+      "group": "Existing model observation",
+      "summary": "Subscribes to complete existing model-owner snapshots and explicitly selected live Core diagnostics.",
+      "availability": "JavaScript with an existing Core client and composed observation service",
+      "protocol": "Request-owned model.observation.watch with targeted state and optional error events",
+      "normalization": "Requires onState; returns ready, closed, current() and close(). Ready resolves the first current snapshot; onDiagnostic explicitly selects diagnostics:true and receives complete correlated live failed Core response frames, without recovered history or inferred model IDs. Closing, abort, page/client retirement and transport failures retire only observation work. Normal cancellation closes cleanly; other errors reach onError and reject public promises. Callback errors close the observation while callback promises remain caller-owned. No model refresh, inference, polling, host launch, endpoint discovery, reconnect or saved conversation content."
+    },
     {
       "id": "core-app-control:connectAppControl",
       "name": "connectAppControl",
@@ -4374,7 +4416,7 @@
       "summary": "Creates an app-neutral Core dispatcher with explicit services, request lifetimes, events and graceful drain.",
       "availability": "Node on Windows, Linux and macOS native hosts; Android requires its host adaptation",
       "protocol": "arcane/1 dispatcher and service lifecycle",
-      "normalization": "Starts services independently; runtime.getService(name) and context.getService(name) return the same registered object after only its shared startup, without a renderer or global barrier. Lookup is readiness, not a lifetime lease; new lookups reject during shutdown. runtime.handle(frame,{contextRequestId}) optionally sets handler requestId while coreRequestId remains frame.id; omitted metadata exposes both equal. Internal IDs continue to own cancellation/state/event envelopes and payloads remain unchanged. Preserves complete results/errors, cancels request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order. Missing dispatch retains METHOD_NOT_ALLOWED with exact method/namespace and core-namespace-unavailable or core-method-unavailable; named services, registered methods and built-in namespaces establish presence. Handler/startup/permission errors remain unchanged."
+      "normalization": "Starts services independently; runtime.getService(name) and context.getService(name) return the same registered object after only its shared startup, without a renderer or global barrier. Lookup is readiness, not a lifetime lease; new lookups reject during shutdown. runtime.handle(frame,{contextRequestId,contextClientRequestId}) sets requestId=contextRequestId??frame.id, clientRequestId=contextClientRequestId??contextRequestId??frame.id and coreRequestId=frame.id; omitted metadata exposes all three equal. Transports always supply the actual client ID separately, preserving the owning shared-host internal requestId contract. Internal IDs continue to own cancellation/state/event envelopes and payloads remain unchanged. Preserves complete results/errors, cancels request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order. Missing dispatch retains METHOD_NOT_ALLOWED with exact method/namespace and core-namespace-unavailable or core-method-unavailable; named services, registered methods and built-in namespaces establish presence. Handler/startup/permission errors remain unchanged."
     },
     {
       "id": "core-stdio:encodeCoreFrame",
@@ -4416,7 +4458,7 @@
       "summary": "Attaches an existing Core runtime to framed input and output with concurrent dispatch and graceful shutdown.",
       "availability": "Node with readable input and writable output streams",
       "protocol": "Content-Length framed arcane/1 stdio",
-      "normalization": "Returns {runtime,closed,close}; scopes responses/request events, cancellation and current-state replay to its connection, preserving original service-facing requestId and complete payloads while routing unique internal IDs. Preserves queued output order, reports parser and stream failures, drains accepted runtime work on EOF and never exits the host or ends caller-owned output"
+      "normalization": "Returns {runtime,closed,close}; scopes responses/request events, cancellation and current-state replay to its connection, preserving original service-facing requestId/clientRequestId and complete payloads while coreRequestId identifies unique internal dispatch. Preserves queued output order, reports parser and stream failures, drains accepted runtime work on EOF and never exits the host or ends caller-owned output"
     },
     {
       "id": "native-portable-provider:createPortableNativeProvider",
@@ -4430,7 +4472,7 @@
       "summary": "Creates the SDK-owned provider that assembles one selected app and explicit services into a portable Core payload.",
       "availability": "Node; produces a portable payload rather than an executable host",
       "protocol": "arcane-native-builder/1 portable provider",
-      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; optional appDescriptor.native.window carries positive integral logical client width/height and optional resizable into manifest.window with omitted fields preserved; reports executable:false and never substitutes for an unavailable platform host"
+      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; optional appDescriptor.native.window carries positive integral logical client width/height and optional resizable into manifest.window with omitted fields preserved. Generated coreListener opt-in composes one passive model-observation service from the existing host.runtime and actual services exposing localai.status/image.status/decisions.status before listener binding, with absent owners null and renderer attachment separate. Ordinary stdio and sharedHost/headless behavior remains unchanged; no model creation, getService or readiness barrier. Reports executable:false and never substitutes for an unavailable platform host"
     },
     {
       "id": "native-portable-provider:arcaneNativeBuilderProvider",
@@ -4640,7 +4682,7 @@
       "summary": "Attaches local IPC to an existing window-owned Core runtime without changing its services or lifetime.",
       "availability": "Node named pipes on Windows and Unix-domain sockets on Linux/macOS; Android requires its host adaptation",
       "protocol": "arcane/1 over local IPC with per-connection correlation, cancellation and current-state replay",
-      "normalization": "Returns {endpoint,closed,close}; never constructs, starts or closes the supplied runtime. Explicit close flushes queued output and disconnects its clients while accepted service work remains runtime-owned. Runtime shutdown retains the endpoint through service drain then closes the listener. Preserves parameters/results/event data, original handler requestId and internal coreRequestId; no host shutdown RPC. Bind errors reject startup; transport errors reach onError and terminal errors reject closed. Native launchContext.coreListener:{endpoint} selects the existing stdio branch; no sharedHost/headless selection or inferred endpoint."
+      "normalization": "Returns {endpoint,closed,close}; never constructs, starts or closes the supplied runtime or registers services. Explicit close flushes queued output and disconnects its clients while accepted service work remains runtime-owned. Runtime shutdown retains the endpoint through service drain then closes the listener. Preserves parameters/results/event data, original handler requestId/clientRequestId and internal coreRequestId; no host shutdown RPC. Bind errors reject startup; transport errors reach onError and terminal errors reject closed. Native launchContext.coreListener:{endpoint} selects the existing stdio branch and its existing-instance observation composition; no sharedHost/headless selection or inferred endpoint."
     },
     {
       "id": "core-host:startSharedCoreHost",
@@ -4654,7 +4696,7 @@
       "summary": "Claims an app-selected local endpoint before composing one shared Core runtime.",
       "availability": "Node named pipes on Windows and Unix-domain sockets on Linux/macOS; Android requires its host adaptation",
       "protocol": "arcane/1 over local IPC with per-connection request correlation and current-state replay",
-      "normalization": "Returns {runtime,endpoint,closed,close}; configure(runtime,{signal}) registers independently started services after the endpoint claim. Close joins composition, accepted service work, disposal and queued frames before releasing the endpoint. Complete transport/startup/shutdown errors remain observable; an occupied endpoint never invokes the factory"
+      "normalization": "Returns {runtime,endpoint,closed,close}; configure(runtime,{signal}) registers independently started services after the endpoint claim. Preserves internal handler requestId/coreRequestId and the existing matching data.requestId adapter mapping while additive clientRequestId exposes the actual client ID independently. Other payload fields remain unchanged. Close joins composition, accepted service work, disposal and queued frames before releasing the endpoint. Complete transport/startup/shutdown errors remain observable; an occupied endpoint never invokes the factory"
     },
     {
       "id": "core-host:connectSharedCoreHost",

package/docs/reference/model-observation.md

@@ -0,0 +1,220 @@
+# Existing model observation
+
+Model observation reads the existing renderer and Core owners selected by the
+application. It exposes their current lifecycle, progress, retained errors and
+actual operation identities to an explicitly selected developer observer.
+Model loading, inference, selection, cancellation and saved application state
+remain with those owners. Observation creates no model, accessor or Core runtime.
+
+## Compose the existing Core
+
+```js
+import {createModelObservationService} from 'arcane-os/core/model-observation';
+
+const observation = createModelObservationService({
+    runtime: host.runtime,
+    localAI: existingLocalAIService,
+    image: existingImageService,
+    decisions: existingDecisionService
+});
+host.runtime.registerService(observation);
+```
+
+`host` and the three services in this example are the application's existing
+instances. `localAI`, `image` and `decisions` are optional and default to `null`.
+Supply their actual service definitions, including `current()` and `methods`.
+The constructor neither looks up nor starts a service. Registration can follow
+`startCoreHost()` on its returned runtime, before opening an additional listener;
+it requires no model readiness barrier.
+
+The service is named `model-observation` and exposes `current()`, `dispose()` and
+the fixed Core methods below. `dispose()` retires only its observation requests
+and subscriptions. The host continues to own the Core and model services.
+
+An external local caller can connect through the explicitly selected
+[`startCoreListener`](core-shared-host.md) endpoint on that same runtime.
+For a packaged window, `native.launchContext.coreListener: {endpoint}` selects
+that same-runtime listener. Before binding it, the generated Core entry registers
+`model-observation` with the actual existing `services` definitions that expose
+`localai.status`, `image.status` and `decisions.status`; absent owners are `null`.
+The observer reuses those model-service owners and creates no accessor or model.
+The application supplies its renderer attachment separately.
+The observation module does not discover endpoints, launch a host, reconnect,
+change a profile, or create a second runtime. Native DOM inspection and actions
+retain their separate [app-control contract](native-app-control.md).
+
+## Attach existing renderer owners
+
+```js
+import * as aiRuntimeState from 'arcane-os/ai-runtime-state';
+import {attachModelObservation} from 'arcane-os/ai/model-observation';
+
+const attachment = attachModelObservation({
+    client: existingCoreClient,
+    aiRuntimeState,
+    imageRuntime: existingImageAccessor,
+    decisionModel: existingBrowserDecisionModel,
+    modelController: existingModelController,
+    signal: pageLifetime.signal,
+    onError: function reportObservationFailure(error) {
+        developerDiagnostics.report(error);
+    }
+});
+await attachment.ready;
+```
+
+Each optional owner defaults to `null`. Pass the instances already used by the
+application. Creating another image accessor would describe that new accessor's
+requests rather than the existing work. The supported owner methods are:
+
+| Input | Read | Subscribe |
+|---|---|---|
+| `aiRuntimeState` | `getAIRuntimeState()` | `subscribeAIRuntimeState()` |
+| `imageRuntime` | `current()` | `subscribe()` |
+| `decisionModel` | `status()` | `subscribe()` |
+| `modelController` | `status()` | `on('statechange')`, `on('progress')` |
+
+The attachment returns `{ready, closed, current, close}`. `ready` resolves with
+`{attachmentRequestId, coreRequestId}` after Core acknowledges the attachment.
+`current()` returns the latest complete renderer snapshot read by this
+attachment, or `null` when it was cancelled before reading. Subscriptions begin
+after acknowledgement; the attachment then reads and publishes current state
+again to cover changes during that handshake.
+
+Caller abort, `pagehide`, retirement of the exact installed Core client,
+transport failure, or `close()` removes the observation subscriptions and
+cancels only this attachment's observation RPCs. A supplied client remains
+caller-owned. The attachment never follows a replacement client or automatically
+reattaches. Native document retirement also cancels its long-lived Core request.
+Core then removes the renderer record; late publication to that retired
+attachment fails honestly. Detachment does not unload or cancel a model.
+
+`close()` returns `closed`, which settles after the attachment's observation
+RPC promises settle locally. It does not claim that a remote model or host has
+closed. Transport and observation errors remain available through `onError`
+and the rejected public promises. With `onError` omitted they reach the developer
+console. Normal cancellation, including cancellation initiated by the existing
+client or native document owner, closes observation without a model error. When
+cancellation precedes acknowledgement, `ready` rejects with the cancellation
+while `closed` resolves after the observation RPCs settle.
+
+## Read or subscribe from an existing client
+
+```js
+import {subscribeModelObservation} from 'arcane-os/ai/model-observation';
+
+const current = await client.invoke('model.observation.current', {}, {signal});
+const observation = subscribeModelObservation({
+    client,
+    signal,
+    onState: function showRetainedOwners(snapshot) {
+        developerDiagnostics.show(snapshot);
+    },
+    onDiagnostic: function showModelFailure(record) {
+        developerDiagnostics.report(record);
+    },
+    onError: function showObservationFailure(error) {
+        developerDiagnostics.report(error);
+    }
+});
+await observation.ready;
+```
+
+`onState` is required. The returned `{ready, closed, current, close}` has the same
+observation-only lifecycle as the renderer attachment. `ready` resolves with
+the first current-state replay; `current()` holds the latest complete snapshot,
+initially `null`. `onDiagnostic` explicitly selects live correlated Core model
+failure frames. Omitting it requests state observation only. Callback failures
+close that observation and reach `onError`; callback promises remain
+caller-owned and may await `close()` without becoming its completion barrier.
+
+Every snapshot is:
+
+```js
+{
+    core: existingCoreRuntime.current(),
+    native: {localAI, image, decisions},
+    renderers: [{attachmentRequestId, coreRequestId, owners: {
+        aiRuntimeState, imageRuntime, decisionModel, modelController
+    }}]
+}
+```
+
+The values represent complete supplied-owner snapshots. Absent optional owners
+are `null`; absent renderer attachments produce an empty array. Core state also
+contains its real active observation requests, identified by their actual
+methods, alongside other active requests. Observation does not relabel them as
+model work. Snapshots are current observations of independent owners, rather
+than an atomic transaction across all owners.
+
+## Fixed transport and correlation
+
+| Method/event | Contract |
+|---|---|
+| `model.observation.current` | Empty parameters; returns the current snapshot without model refresh or readiness waits. |
+| `model.observation.watch` | `{diagnostics:false}` by default; remains pending until cancellation. |
+| `model.observation.state` | Targeted watch event `{watchRequestId,snapshot}`; the first event acknowledges the watch and replays current state. |
+| `model.observation.error` | Targeted diagnostic `{watchRequestId,source:'core',method,frame}` preserving the complete original failed response frame. |
+| `model.observation.renderer.attach` | `{snapshot}`; remains pending to own the renderer publication lifetime. |
+| `model.observation.renderer.attached` | Targeted acknowledgement `{attachmentRequestId,coreRequestId}`. |
+| `model.observation.renderer.publish` | `{attachmentRequestId,coreRequestId,snapshot}`; replaces that attachment's current snapshot and returns both attachment identities. |
+
+Both helpers register listeners before invoking. Existing
+[`client.invoke`](core-client.md) supplies `onRequest({requestId})` before send;
+long-lived observation requests use `timeoutMs:0`. Their acknowledgement is a
+targeted request event, while the invocation promise remains pending.
+
+`attachmentRequestId` and `watchRequestId` are the actual client-visible Core
+request identities supplied by service context `clientRequestId`.
+`coreRequestId` is the actual internal Core frame identity;
+renderer attachments are keyed by that value so clients with identical local
+request IDs cannot collide. The renderer echoes both values when publishing.
+`snapshot.core.activeRequests[].id` and diagnostic `frame.id` use internal Core
+identities. They can differ from client-visible IDs under connection routing.
+None of these observation/transport IDs is a model-operation ID.
+
+Core supplies both metadata fields for direct runtime calls, stdio connections,
+`startCoreListener()` connections and the existing `startSharedCoreHost()` path.
+Each connection preserves the original incoming request ID as `clientRequestId`
+independently of its established `requestId` mapping. Direct calls use the
+incoming frame ID for both identities. Observation requires these actual
+context fields; it does not infer them from `requestId` or rewrite event
+payloads to manufacture correlation.
+
+The exact `methods` keys on the supplied native service definitions select the
+Core operations whose live failures can be observed. The observer tracks their
+actual active request IDs while a watch exists. Core publishes request removal
+before emitting its response; the observer retains that correlation until the
+response arrives, then removes it. Removing the final watcher releases frame
+observation and remaining transient correlation. It retains no failure history.
+
+## Evidence and lifecycle limits
+
+- AIRuntimeState exposes its existing llm/stt/tts records, including the reported
+  operation ID. Its retained errors contain only code/message. Concurrent role
+  work is not a complete request enumeration in this snapshot.
+- The existing image accessor exposes its own active method, stream ID, status
+  and progress records. Its retained error is preserved; that error has no
+  reliable explicit stream association. Constructor-only diagnostic callbacks
+  cannot be retroactively attached through this API.
+- Browser and native decision snapshots retain their existing errors and active
+  request counts. A count does not supply missing per-evaluation IDs.
+- ModelController status exposes its existing state/progress and code/message
+  error. Its load/unload event IDs are not retained by `status()`, and are not
+  presented as inference IDs or reconstructed history here.
+- Core supplies its real active request identities and complete live failed
+  response frames. A watch cannot recover responses that settled before it
+  observed them. Retained owner errors remain available in current snapshots.
+
+Renderer `Error` values in owner error fields use the existing Core error
+serializer at the JSON boundary; other owner fields remain unchanged. A value
+the selected transport cannot encode fails through the observation error path
+rather than being replaced with shortened or invented content. Observation
+does not alter model inputs, outputs, prompts or their persistence policy.
+
+The shared JavaScript contract is portable wherever the existing Core client
+and supplied owners are available. Endpoint and native-host availability belong
+to their documented adapters. Developer observation remains separate from
+ordinary user status, app-owned stage/avatar association and actual model
+execution verification. This capability does not establish that an inference
+failure has been corrected.

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

@@ -2,9 +2,9 @@
 
 `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
+inspection, a PNG of its rendered viewport, targeted DOM actions, fixed keys and
+Normal-window client resizing 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
@@ -77,29 +77,45 @@ connection or other business result.
 | `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` within the root selected by optional `shadowPath`, and the action fields below. |
+| `key(parameters, options?)` | Requires `documentGeneration` and `key:'Tab'`, `'Enter'`, or `'Space'`. Optional `shiftKey:true` is supported only for Tab. Sends one ordered press/release pair to the selected WebView's current focus. |
+| `resize(parameters, options?)` | Requires positive integral native client `width` and `height` supported by WinForms. Optional `documentGeneration` selects the expected document. Resizes only a Normal window and returns immediate previous/actual client dimensions plus the subsequently observed CSS viewport. |
 | `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.
+that connection. Cancellation before UI dispatch prevents execution; keys also
+check cancellation after waiting for the keyboard owner and immediately before
+the press. Once a script, capture, key press or resize has been dispatched,
+cancellation cannot reverse its effects. The host observes its actual completion,
+including the owned key release. The caller receives its ordinary abort result;
+the complete later response is retained in host diagnostics for a cancelled
+request or closed connection instead of being represented as delivered.
 
 ## Document operations
 
 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
+`activeElement`, `scrollingElement`, `selection`, `viewport`, `documentHasFocus`,
+`focusPath`, `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. Component replacement or mutation can make a selector stale
 without changing the native document generation.
 
+`viewport` contains the top-level document's `innerWidth` and `innerHeight` as
+CSS-pixel `width`/`height`, plus its current `devicePixelRatio`.
+`documentHasFocus` records `document.hasFocus()`. `focusPath` describes the
+top-level active element followed by each active element in accessible open
+shadow roots along that focus branch. These records retain complete attributes,
+DOM-derived names and control state, with `selector:null`; they are observations,
+not selector targets. Reading a focused body or host's name can traverse its
+complete text subtree. The path stops at a frame element or closed shadow host;
+it does not enter frame documents or closed roots.
+
 ### Open shadow roots
 
 `inspect` and `act` accept `shadowPath`, an ordered array of CSS host selectors.
@@ -134,7 +150,10 @@ 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
+and native URL/generation remain document-level information. The added
+`viewport`, `documentHasFocus` and `focusPath` also always describe the top-level
+document: the focus path can enter open roots outside the selected inspection
+root. The selected root's `activeElement` remains separate. 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
@@ -155,9 +174,10 @@ 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 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
+contents are outside the selected HTML/control scope; the document-level focus
+path separately describes its active open-shadow branch. 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 |
@@ -174,11 +194,101 @@ 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,
+script so a queued DOM 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.
 
+## Fixed keys
+
+```js
+const page = await app.inspect();
+const moved = await app.key({documentGeneration: page.documentGeneration, key: 'Tab'});
+console.log(moved.previous.focusPath, moved.actual.focusPath);
+await app.key({documentGeneration: moved.documentGeneration, key: 'Tab', shiftKey: true});
+await app.key({documentGeneration: moved.documentGeneration, key: 'Enter'});
+```
+
+Keys use the selected WebView's current focus. No selector, shadow path, frame
+selection, focus assignment or desktop activation is performed. Tab and
+Shift+Tab use a fixed Tab `rawKeyDown`/`keyUp` pair, with the Shift modifier on
+both events for Shift+Tab. Enter and Space use `keyDown` with their corresponding
+text, followed by `keyUp`, preserving browser default actions and application
+`preventDefault` handling. Shift+Tab does not send a separate Shift key pair.
+The API exposes these fixed keys, not an arbitrary protocol method or script.
+
+The result contains `key`, `shiftKey`, `previous` and `actual` document views,
+`press`, `release`, `documentGeneration` and `url`. Each view contains the same
+`viewport`, `documentHasFocus` and `focusPath` described above. Each key phase
+records its fixed `parameters`, `attempted`, `completed`, and the complete
+protocol `response` when returned. Dispatch completion describes the native
+command, not application handler completion or a successful business action.
+Inspect the resulting page to establish the application outcome.
+
+Accepted key pairs share one keyboard owner so another key request cannot
+interleave between press and release. Other independent control operations keep
+their existing scheduling. The host awaits each native phase in order. Once
+the press is attempted, the host observes that task and attempts the matching
+release on the same WebView even after cancellation, navigation or press
+failure. Release can itself activate Space. A failed or ambiguous press is
+never replayed.
+
+Generation checks occur before dispatch and after completion; the native input
+command has no atomic document binding. Navigation or focus changes can occur
+between the checks and phases, and Tab intentionally changes focus before its
+release. A detected document change is reported with the actual attempted and
+completed phases. Dispatch, release or later observation failures retain the
+complete partial result at `error.data.find(entry => entry.key === 'result').value`
+under `ARCANE_APP_CONTROL_FAILED`. Original exceptions remain in `cause`; if
+both native phases fail, both errors are also retained in the aggregate and
+their respective phase records. An unavailable `actual` view is omitted rather
+than inferred.
+
+## Resize and restore a Normal window
+
+```js
+const resized = await app.resize({width: 1200, height: 800});
+try {
+    console.log(resized.previous, resized.actual, resized.viewport);
+    console.log(await app.inspect({selector: '#pm-content'}));
+} finally {
+    await app.resize({width: resized.previous.width, height: resized.previous.height});
+}
+```
+
+`width` and `height` select the native WinForms client dimensions, in the same
+units returned by `status().window`. They are not CSS viewport dimensions.
+The host changes only `ClientSize`; it does not assign window state, position,
+restore bounds, activation or WebView zoom, and it preserves the profile and
+origin. Read `viewport` for the resulting CSS dimensions instead of assuming a
+particular DPI or zoom conversion.
+
+Immediately before the UI-thread mutation, the host checks the actual
+`WindowState` and records `previous:{title,state,width,height}`. It records
+`actual` in the same shape immediately after the native setter, then observes
+the CSS `viewport` asynchronously. The result also contains `requested`,
+`resizeAttempted`, `resizeCompleted`, `documentGeneration` and `url`.
+Platform constraints may make actual dimensions differ from requested ones.
+Other input or concurrent resize requests can change the window between the
+native snapshot and the document observation; these records are not an atomic
+native/CSS snapshot. Completion does not establish that asynchronous application
+resize handlers have settled.
+
+Maximized or minimized windows return `ARCANE_APP_CONTROL_FAILED` before any
+size mutation, with `reason:'unsupported-window-state'`,
+`supportedWindowState:'Normal'` and the complete current `window` in the error's
+`data` entries. The host never automatically restores, maximizes or minimizes a
+window to satisfy this request. Invalid dimensions return `INVALID_ARGUMENT`.
+The same state rule applies to explicit restoration.
+
+Restore using the actual `previous.width` and `previous.height` from the
+operation being reversed, never a historical status snapshot or CSS viewport
+dimensions. Restoration is an explicit second request; cancellation does not
+resize the window back. If a dispatched resize or its later observation fails,
+the complete partial `result` remains in the error's `data`, including the
+recorded previous dimensions, actual dimensions and attempted/completed flags.
+Use that actual record when deciding whether and how to restore.
+
 ## CLI
 
 ```powershell
@@ -187,14 +297,20 @@ arcane app-control inspect --endpoint '\\.\pipe\arcane-pm-control' --selector '#
 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'
+arcane app-control key --endpoint '\\.\pipe\arcane-pm-control' --request '.arcane\key.json'
+arcane app-control resize --endpoint '\\.\pipe\arcane-pm-control' --request '.arcane\resize.json'
 ```
 
-The action file is the complete action parameter object, including the actual
+The action or key file is the complete parameter object, including the actual
 `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.
+options are mutually exclusive. A key file can contain
+`{"documentGeneration":3,"key":"Tab","shiftKey":true}`, using the observed
+generation. A resize file contains native dimensions such as
+`{"width":1200,"height":800}`. Each requires `--request`; the CLI reads the
+selected file completely and forwards the parsed parameter object unchanged.
 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