arcane-os 0.52.1 → 0.54.0

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

@@ -8,9 +8,9 @@
     "sdkVersion": "0.51.1",
     "protocol": "arcane/1"
   },
-  "artifactCount": 92,
-  "javascriptArtifactCount": 90,
-  "esmExportCount": 372,
+  "artifactCount": 93,
+  "javascriptArtifactCount": 91,
+  "esmExportCount": 373,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -719,12 +719,25 @@
       "exports": [
         "default"
       ],
-      "summary": "Defines the same-origin `<html-import>` loader with open shadow root, inline script execution, and readiness/error events.",
+      "summary": "Defines the same-origin `<html-import>` loader with open shadow root, inline or packaged external script execution, and readiness/error events.",
       "availability": "Browser / native WebView",
       "protocol": "Same-origin fetch + DOM",
       "normalization": "Public error detail normalized; fetch/DOM failure preserved.",
       "surface": "default `HTMLImport`; registers `html-import`; `connectedCallback()` and `ready`."
     },
+    {
+      "file": "runtime/arcane/modules/HTMLImportScript.js",
+      "name": "HTMLImportScript.js",
+      "kind": "esm",
+      "exports": [
+        "createHTMLImportScript"
+      ],
+      "summary": "Renders the complete classic-script host wrapper shared by HTMLImport and native-module packaging.",
+      "availability": "Cross-host",
+      "protocol": "In-process only",
+      "normalization": "Complete source retained with a terminating newline before the wrapper closes.",
+      "surface": "`createHTMLImportScript(source)` returns the script text without executing it."
+    },
     {
       "file": "runtime/arcane/modules/InMemoryCommunicationProvider.js",
       "name": "InMemoryCommunicationProvider.js",

package/docs/reference/protocols.md

@@ -174,6 +174,69 @@ output must remain separate; a conflicting native assembly fails before it
 packages any app. App launch paths, resource URLs, and enabled PWA
 representations retain their package-relative layout.
 
+## Native-module package output
+
+The public `packageApp` operation accepts `moduleFormat:'native'`. Omission, or
+`'import-map'`, retains ordinary browser output. Optional operation-level
+`outputDirectory` overrides only this invocation's destination; `verifyApp`
+accepts that same override. Configuration, source layout, app identity, storage
+scope and previously generated sibling outputs remain unchanged.
+
+The native transformation runs in the selected package stage after application
+adapter work, before the final inventory and any enabled PWA artifacts. It uses
+the existing selected document/runtime records and shared lexical/HTML owners.
+Each selected document supplies its saved maps and authored base. Native mode
+uses the static layout with map declarations before executable scripts; it does
+not reproduce late-map insertion or its already-resolved-module timing rules.
+Exact keys, longest matching prefixes and most-specific importer scopes resolve to package
+URLs, including URL aliases used by direct installed-SDK layouts. Static
+imports, re-exports, string-literal dynamic imports and string-literal
+`import.meta.resolve()` become native relative references. Query strings and
+fragments retain their meaning. Equivalent graphs share output modules;
+documents whose maps resolve differently receive distinct context files beside
+the original module, including when their graphs contain cycles.
+
+Selected document import-map elements are consumed in the output only.
+Executable inline document scripts move into complete external files while
+their script elements retain position, type and effective scheduling. The
+packager removes ineffective `async`/`defer` attributes only from formerly inline
+classic scripts, whose external form otherwise would activate those attributes.
+Module scripts and already-external document scripts retain their attributes.
+Imported component scripts use one canonical classic wrapper, with an explicit
+`data-arcane-packaged-script` marker consumed by `HTMLImport`. That path loads
+the external script directly and retains per-instance host binding, ordered
+asynchronous completion, cancellation, teardown and ready/error events. Ordinary
+browser components keep their existing inline path. Application documents not
+selected for document processing remain unchanged unless they are explicitly
+loaded as components.
+
+The selected payload is preserved in full, including runtime files, assets,
+workers and licenses. Graph processing follows each document's executable and
+resource references, including literal URLs to selected shared component HTML.
+It does not assign an unused shared file to another document's map. Unreferenced
+selected files retain their complete content. Referenced scripts, component HTML
+and stylesheets are processed at their existing owners; resource URLs are rebased
+for deployment under a directory such as `app/`. The operation adds generated scripts to the
+complete release inventory. It does not bundle, prune, minify or rewrite
+application prose, data or saved history. The existing stage replacement
+preserves prior output if packaging fails or is cancelled.
+
+This is a static module/script packaging capability, not a replacement browser
+or a runtime import-map interpreter. Computed import expressions remain authored;
+applications supply native-resolvable URLs for runtime-selected imports. It
+does not convert event-handler attributes, dynamically evaluated source, or
+provider-created executable blobs. An inline document script beneath an authored
+remote effective base cannot address a package-local generated file; native mode
+reports that incompatible transformation and preserves the original output.
+Already-external scripts retain their remote-base behavior. Remote modules/providers
+and WebAssembly still depend on their actual host capabilities. Resolving package references is
+distinct from executing the complete application on Chromium or another host.
+
+For an extension, select `browserPwa:false` for that artifact and place the
+complete SDK-produced app beneath the app-owned extension root. The application
+owns its manifest, toolbar/background launcher and permissions. Ordinary browser
+PWA configuration and generated browser output remain independently available.
+
 ## Installed-package browser routes
 
 An external application can serve and package its installed SDK directly,
@@ -413,7 +476,7 @@ renaming any preceding entry changes the physical contract.
 
 The map derives its complete entries from the selected runtime graph;
 application source imports do not select a fixed entry count. The operation
-result reports `imports`, `documentCount`, and `excludedModules`; reached-file
+result reports `imports`, optional dependency `scopes`, `documentCount`, and `excludedModules`; reached-file
 traversal remains internal. The
 managed graph exposes `arcane-os/event-manager`, `arcane-os/ai/browser-wasm`,
 `arcane-os/ai/browser-speech`, `arcane-os/preference-store`, and
@@ -425,6 +488,8 @@ The focused physical targets remain stable when their bindings are reached:
 | Browser specifier | Physical target |
 | --- | --- |
 | `arcane-os/event-manager` | `./arcane/sdk/event-manager.mjs` |
+| `arcane-os/websocket-client` | `./arcane/sdk/websocket-client.mjs` |
+| `ws-share` | `./arcane/sdk/dependencies/ws-share/WS.js` |
 | `arcane-os/ai/browser-wasm` | `./arcane/sdk/ai/browser-wasm.mjs` |
 | `arcane-os/ai/browser-speech` | `./arcane/sdk/ai/browser-speech.mjs` |
 | `arcane-os/speech-text` | `./arcane/sdk/speech-text.mjs` |
@@ -434,6 +499,16 @@ The focused physical targets remain stable when their bindings are reached:
 | `strong-type` | `./arcane/dependencies/strong-type/index.js` |
 | `./node_modules/strong-type/index.js` | `./arcane/dependencies/strong-type/index.js` |
 
+When the selected runtime contains event-pubsub's own dependency projection,
+the `./arcane/sdk/dependencies/event-pubsub/` scope maps `strong-type` to
+`./arcane/sdk/dependencies/event-pubsub/dependencies/strong-type/index.js`.
+This keeps its published 2.0.0 selection separate from the global SDK 2.0.1
+binding. Scope keys and targets follow installed-package and document-base
+translation together. Older inventories without that nested projection retain
+their existing map shape. Internal managed test contexts accept and preserve
+optional `scopes` alongside `imports`; their loader selects the most-specific
+matching importer scope before the global map.
+
 Direct installed routes translate these targets to their actual npm destinations,
 including aliases. There is no `arcane-os` package-root mapping or catch-all
 `arcane/` prefix. Classic scripts, workers, stylesheets, and other

package/docs/reference/runtime-modules.md

@@ -98,7 +98,8 @@ own asynchronous work, cancellation, and backpressure.
 | [`DocumentNavigation.js`](#documentnavigationjs) | esm | Binds document navigation, filtering, history, current-item reveal, and load initialization. | Browser / native WebView | Normalized filter/navigation state; DOM effects preserved. |
 | [`Errors.js`](#errorsjs) | esm | Normalizes global errors/rejections, assigns occurrence identifiers, persists a complete ledger, and performs complete delivery. | Browser / native WebView hybrid | Incident records normalized; storage/mail failures isolated. |
 | [`GifEncoder.js`](#gifencoderjs) | esm | Encodes indexed frames into a complete animated GIF using palette mapping and LZW. | Cross-host | Normalized complete binary output. |
-| [`HTMLImport.js`](#htmlimportjs) | esm | Defines the same-origin `<html-import>` loader with open shadow root, inline script execution, and readiness/error events. | Browser / native WebView | Public error detail normalized; fetch/DOM failure preserved. |
+| [`HTMLImport.js`](#htmlimportjs) | esm | Defines the same-origin `<html-import>` loader with open shadow root, inline or packaged external script execution, and readiness/error events. | Browser / native WebView | Public error detail normalized; fetch/DOM failure preserved. |
+| [`HTMLImportScript.js`](#htmlimportscriptjs) | esm | Renders the complete classic-script host wrapper shared by HTMLImport and native-module packaging. | Cross-host | Complete source retained with a terminating newline before the wrapper closes. |
 | [`InMemoryCommunicationProvider.js`](#inmemorycommunicationproviderjs) | esm | Implements deterministic in-memory thread/message/send behavior for demos and tests. | Cross-host | Normalized communication entities. |
 | [`IsolatedModelQuestionRunner.js`](#isolatedmodelquestionrunnerjs) | esm | Inspects one selected model and runs one isolated question while preserving the complete answer. | Native bridge or injected provider | Normalized model/result and coded errors. |
 | [`LocalAIReadiness.js`](#localaireadinessjs) | esm | Derives selected AI requirements and returns a complete readiness/recovery report across browser, desktop, and Android modes. | Browser/native hybrid | Fully normalized report and stable error codes; browsers never probe Ollama. |
@@ -2500,7 +2501,7 @@ console.log(Object.keys(module));
 
 ### Overview
 
-Defines the same-origin `<html-import>` loader with open shadow root, inline script execution, and readiness/error events.
+Defines the same-origin `<html-import>` loader with open shadow root, inline or packaged external script execution, and readiness/error events.
 
 ### Public surface
 
@@ -2520,6 +2521,14 @@ Local component resources use stable URLs. The loader removes retired SDK-owned
 including caller-owned `v` fields, and fragments remain intact. External resource
 URLs retain their complete query. Ordinary HTTP conditional caching is unchanged.
 
+Native-module packages mark component scripts with `data-arcane-packaged-script`
+and an external `src`. The loader executes those files through a real classic
+script element instead of fetching their text for inline execution. Each host
+receives its own invocation, `this` binding, ordered initialization, readiness
+and error events, cancellation, and imported `destroy()` restoration. Independent
+component hosts remain concurrent. Ordinary unmarked components retain their
+existing inline/fetched-script path.
+
 Exact exports: `default`.
 
 ### Availability and normalization
@@ -2534,6 +2543,40 @@ import * as module from '/arcane/modules/HTMLImport.js';
 console.log(Object.keys(module));
 ```
 
+## HTMLImportScript.js
+
+### Overview
+
+Renders the complete classic-script host wrapper shared by HTMLImport and
+native-module packaging. Rendering returns source text; it does not execute it
+or access the DOM.
+
+### Public surface
+
+`createHTMLImportScript(source)` returns the complete source inside the loader's
+async host-bound initializer. A newline separates the authored ending from the
+wrapper closure, including when the body ends in a line comment. At execution,
+the wrapper uses the current script's host token and the HTMLImport-owned
+registry, then exposes the initializer promise to that host's loader.
+
+Exact exports: `createHTMLImportScript`.
+
+### Availability and normalization
+
+**Cross-host.** Complete source retained with a terminating newline before the
+wrapper closes. Transport: In-process only. [Deep protocol details](protocols.md).
+
+### Example
+
+```javascript
+import {createHTMLImportScript} from 'arcane-os/modules/HTMLImportScript.js';
+
+const source=createHTMLImportScript('this.textContent="The moon burglar arrived.";');
+```
+
+Application packaging normally calls `packageApp({moduleFormat:'native', ...})`
+instead of assembling or executing component wrappers itself.
+
 ## InMemoryCommunicationProvider.js
 
 ### Overview

package/docs/reference/sdk-api.md

@@ -2,9 +2,10 @@
 
 The npm package exposes a Node.js ESM control plane, the portable
 `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`,
-`arcane-os/preference-store`, `arcane-os/speech-playback`,
+`arcane-os/preference-store`, `arcane-os/speech-playback`, `arcane-os/websocket-client`,
 `arcane-os/speech-text`, `arcane-os/ai/tool-text-stream`, `arcane-os/ai/twin-cloud`, and `arcane-os/browser-device` entrypoints, and the browser-only
-`arcane-os/pwa` and `arcane-os/ai/browser-wasm` entrypoints. The
+`arcane-os/pwa`, `arcane-os/ai/browser-wasm`, and
+`arcane-os/ai/browser-decisions` entrypoints. The
 `arcane-os/ai/browser-speech` entrypoint includes local and native browser
 providers plus a cloud TTS adapter usable in Node with Fetch and Blob.
 The `arcane-os/modules/<filename>` and `arcane-os/entities/<filename>` paths
@@ -41,6 +42,8 @@ runtime layouts.
 | `arcane-os` | Complete high-level SDK surface. |
 | `arcane-os/toolchain` | Headless application operations. |
 | `arcane-os/events` | CLI/event reporter. |
+| `arcane-os/websocket` | Node HTTP/1.1 WebSocket Upgrade, complete messages and accepted connection lifecycle. |
+| `arcane-os/websocket-client` | Shared native client `WS`, one managed-connection observer and current connection snapshots through published ws-share. |
 | `arcane-os/testing` | Isolated test registration and execution. |
 | `arcane-os/targets` | Target adapters and dispatch. |
 | `arcane-os/native` | Native plan and builder protocol. |
@@ -73,6 +76,7 @@ runtime layouts.
 | `arcane-os/browser-device` | Synchronous mobile or desktop identity hints for application-owned settings. |
 | `arcane-os/pwa` | Nonblocking PWA registration, worker updates, native installation state and a dismissible installation component. |
 | `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, complete DBOPFS model storage, streaming, cancellation, and structural tool-call results. |
+| `arcane-os/ai/browser-decisions` | Explicit-load Laya FP16 and Julia-1 FP32 typed decisions through the shared Transformers.js Worker owner. |
 | `arcane-os/ai/tool-text-stream` | Shared selected tool-argument text observer for provider integration. |
 | `arcane-os/ai/twin-cloud` | Stateless chat, System One state/questions and image generation with explicit key/model, complete results and operation-specific retry/cancellation. |
 | `arcane-os/ai/browser-speech` | Caller-selected Whisper/Kokoro, native browser recognition/synthesis, cloud TTS, upstream assets, role lifecycle and cancellation. |
@@ -130,6 +134,9 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 
 | Member | Kind | Import | Group | Availability |
 | --- | --- | --- | --- | --- |
+| `acceptWebSocket()` | function | `arcane-os`, `arcane-os/websocket` | WebSocket protocol | Node; browser-native client interoperability |
+| `WS` | class | `arcane-os`, `arcane-os/websocket-client` | Shared WebSocket clients | Node and native-WebSocket browser hosts |
+| `createBrowserDecisionModel()` | function | `arcane-os/ai/browser-decisions` | Browser typed decisions | Browser module Workers and the caller-selected inference backend |
 | `fetchRequest()` | function | `arcane-os/ai/twin-cloud` | TWiN Cloud requests | Node and Browser; remote HTTPS provider |
 | `fetchSystemOneRequest()` | function | `arcane-os/ai/twin-cloud` | TWiN Cloud state-and-questions requests | Node and Browser; remote HTTPS provider |
 | `generateImages()` | function | `arcane-os/ai/twin-cloud` | TWiN Cloud image generation | Node and Browser with Fetch and Blob; remote HTTPS provider |
@@ -866,6 +873,42 @@ The package preserves the complete selected content, applying the documented
 asset-version and enabled browser-PWA transformations to resource references.
 Malformed configuration or descriptors fail while preserving the prior output.
 
+`moduleFormat` defaults to `'import-map'`, preserving the ordinary browser
+package. Select `'native'` to resolve saved document import maps into native
+module URLs in the package stage and emit executable inline scripts as external
+files. Static imports, re-exports, string-literal dynamic imports and
+string-literal `import.meta.resolve()` retain exact/prefix/scoped mappings.
+Imported HTML components use the shared `HTMLImport` externally executable
+script path, retaining their host binding and asynchronous lifecycle. No
+application-owned module loader is needed. Source HTML, saved data and the
+ordinary browser output remain unchanged. See
+[native-module package output](protocols.md#native-module-package-output)
+for resource handling and the static transformation boundary.
+
+An operation may override `outputDirectory` without changing the saved app
+configuration. For example, package a complete application beneath an
+application-owned extension manifest and launcher:
+
+```javascript
+const release = await packageApp({
+    workspaceRoot,
+    appId: 'moon-dashboard',
+    outputDirectory: 'dist/extension/app',
+    moduleFormat: 'native',
+    browserPwa: false
+});
+```
+
+The override uses the same workspace-relative destination and staged replacement
+rules as the saved field. It replaces only `dist/extension/app`, leaving its
+extension-root siblings and an existing browser output intact. `browserPwa:false`
+omits generated PWA artifacts for this invocation; it does not change the app's
+saved PWA configuration. The app owns extension metadata, permissions and toolbar
+launch behavior. This API builds the application directory, not an extension
+manifest or an operating-system launcher. Native-mode dry runs report selected
+input files; generated script/context files are included in the completed
+package's full returned inventory.
+
 The app's optional schema-1 `outputDirectory` selects the final
 workspace-relative destination. For example, `"ai"` emits directly into
 `<workspace>/ai`; omission retains `dist/<app-id>`. The selected directory is
@@ -1149,11 +1192,14 @@ Authenticates one existing browser app release through the low-level packager AP
 ### Signature and result
 
 ```text
-async verifyApp({workspaceRoot, appId, signal, onEvent})
+async verifyApp({workspaceRoot, appId, outputDirectory, signal, onEvent})
 ```
 
 Import it from `arcane-os` or `arcane-os/packager`. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.
 
+Optional `outputDirectory` selects the same workspace-relative override accepted
+by `packageApp`, without changing the app's saved destination.
+
 ### Availability and normalization
 
 **Node.** Normalized SDK validation with complete canonical archive and release content. Deep protocol: [SDK packager and deterministic bundle contract](protocols.md).
@@ -1302,14 +1348,16 @@ The resolved result contains:
     runtimeRoot,
     documentPaths,
     documentCount,
-    documents: [{path, filePath, imports}],
+    documents: [{path, filePath, imports, scopes?}],
     committed: true
 }
 ```
 
 `documentPaths` and each `filePath` are absolute filesystem paths. Each `path`
-is relative to `documentRoot`; `imports` is the complete map rendered for that
-document. The operation inventories the runtime once, builds the shared map
+is relative to `documentRoot`; `imports` contains the global bindings rendered
+for that document. Optional `scopes` contains dependency-specific bindings;
+scope URLs and their targets are rebased with the same document base as global
+imports. The operation inventories the runtime once, builds the shared map
 once, and reads the selected documents with up to four concurrent readers.
 It renders every document before writing any of them, then writes in selected
 order. `committed: true` means all selected writes completed; the batch is not
@@ -3753,6 +3801,171 @@ async function useselectApp(...arguments_) {
 }
 ```
 
+## WS
+
+Import `WS` as the default or named binding from `arcane-os/websocket-client`,
+or as a named binding from the Node root `arcane-os`. `new WS(uri,protocols?)`
+returns the exact native socket from published ws-share, sharing a connecting
+or open socket for the same exact URI string and ordered protocol list.
+`await WS.observe()` exposes one event-pubsub observer with
+`created`/`open`/`error`/`close` lifecycle records; `WS.getConnections()` returns
+current managed-connection snapshots. Each physical connection has its own ID,
+including replacements at the same address.
+
+The [shared-client guide](websocket-client.md) covers complete record fields,
+subscribe-then-snapshot ordering, listener cleanup, shared close ownership,
+native per-socket behavior and the per-loaded-module/realm boundary. This
+client entry does not change the server-side `acceptWebSocket` contract.
+
+## acceptWebSocket()
+
+### Overview
+
+Accepts one caller-selected RFC6455 HTTP/1.1 Upgrade using Node's native
+duplex stream. The caller owns HTTP routing, TLS, listeners, application
+messages and shutdown. Use the raw `server` returned by `startDevServer`, or
+the public `.server` / `.secureServer` of `node-http-server`. There is no
+listener creation, default port, application envelope, message persistence,
+client sharing, reconnect loop or third-party WebSocket runtime.
+
+Clients may use native `WebSocket` directly or the separate shared
+[`WS` client](websocket-client.md). Node's global `WebSocket` is also a client,
+not a server. This server adapter supports version 13 over an
+HTTP/1.1 `upgrade` event, including HTTP/1.1 negotiated on an HTTPS listener.
+It does not implement HTTP/2 extended CONNECT or negotiate extensions such as
+compression. TLS setup remains with the existing server owner.
+
+### Signature, modes, and result
+
+```text
+acceptWebSocket({request,socket,head,protocol,signal})
+```
+
+Import from `arcane-os/websocket` or `arcane-os`. Supply the exact `request`,
+`socket` and `head` from the selected Node `upgrade` event. Do not substitute
+`request.socket` for that event's stream. `head` defaults to an empty buffer.
+Optional `protocol` is one exact client-offered token; the default empty string
+selects no subprotocol. A browser that offers subprotocols expects one to be
+selected. Optional `signal` owns this connection's lifetime.
+
+The synchronous result is a native `EventTarget` with:
+
+| Member | Contract |
+| --- | --- |
+| `readyState` | `1` open, `2` closing, `3` closed. Acceptance queues the handshake before any messages. |
+| `protocol` | Selected subprotocol, or the empty string. |
+| `send(data)` | `Promise<void>` for a complete string, `ArrayBuffer`, or view. A view sends only its selected region. Input is snapshotted at submission; writes stay in submission order. The promise waits for the native write callback and any required drain; it is not a peer/application acknowledgement. |
+| `close(code=1000,reason='')` | Starts the close handshake after already accepted sends; returns `closed`. Repeated calls return the same promise. A peer Close rejects unsent application messages and retains the close reply. |
+| `terminate(reason?)` | Destroys only this connection's stream immediately, rejects pending sends and returns `closed`. An optional reason is reported as an error. |
+| `closed` | Resolves once the stream closes to `{code,reason,wasClean,error}`. It never rejects. Code/reason come from the peer Close; without one, code is `1006`. An empty peer Close reports `1005`. `wasClean` requires both close frames and no recorded failure. |
+
+Register listeners synchronously after acceptance. The handshake write and
+initial `head` processing begin in a microtask so those listeners receive
+buffered messages. `head` is processed once, before later stream chunks.
+
+| Native event | Payload |
+| --- | --- |
+| `message` | `MessageEvent.data`: complete text as a string, or complete binary as `Uint8Array`. Fragment boundaries never replace message boundaries. |
+| `error` | `CustomEvent.detail`: the complete original transport Error or coded protocol/abort Error. |
+| `close` | `CustomEvent.detail`: the same result as `closed`. |
+
+These are transport-local native events, not an application bus or retained
+event history. Native `EventTarget` owns listener exceptions; an async listener
+must observe its own promises. Listen for errors or inspect `closed.error`.
+Ping receives a matching Pong internally; Pong is not an application message.
+Text decoding preserves a leading U+FEFF and validates UTF-8 across the complete
+fragmented message. Binary data is never interpreted or wrapped as JSON.
+
+### Errors and cancellation
+
+Before changing the socket, an invalid handshake throws
+`ARCANE_WEBSOCKET_HANDSHAKE_INVALID` with `statusCode:400,headers:{}`;
+an unsupported WebSocket version throws `ARCANE_WEBSOCKET_VERSION_UNSUPPORTED`
+with `statusCode:426` and `headers:{'Sec-WebSocket-Version':'13'}`. The host
+owns sending that HTTP response and ending the rejected stream. Invalid socket,
+data or close arguments report `TypeError` / `RangeError`; a failed `send`
+rejects its promise without changing the payload.
+An unpaired UTF-16 surrogate cannot be represented as UTF-8: sending such text
+rejects with `ARCANE_WEBSOCKET_TEXT_INVALID`, and using it as a close reason
+throws that error before changing connection state. Valid strings remain exact.
+
+After acceptance, invalid framing reports `ARCANE_WEBSOCKET_PROTOCOL_INVALID`
+and close status `1002`; invalid text reports `ARCANE_WEBSOCKET_TEXT_INVALID`
+and `1007`. Complete platform errors remain observable. Framing lengths,
+masking, the handshake's SHA-1 accept calculation and control-frame bounds are
+RFC transport requirements only. There are no application message limits,
+byte progress, content identities, or optional security controls.
+
+A pre-aborted signal throws before taking ownership. Later abort destroys the
+stream with an `AbortError` coded `ARCANE_WEBSOCKET_ABORTED`, preserving the
+signal reason as its cause. Closing rejects new sends with
+`ARCANE_WEBSOCKET_CONNECTION_CLOSED` (or the existing failure).
+No timer silently terminates a slow close handshake; use the caller's signal or
+`terminate()` when that owner decides to stop. Server listener closure alone,
+including Node `closeAllConnections()`, does not own upgraded sockets. Track
+connections or provide a shared lifetime signal, then await their `closed`
+promises separately. None of this changes chat storage or `persist:false`.
+
+### Example
+
+This example attaches to an already-owned listener and returns a separate
+connection cleanup function. Its route and echo policy belong to the caller.
+Call it with `publicServer.server`, `publicServer.secureServer`, or an SDK
+development server's returned `server`; it creates no additional HTTP server.
+
+```javascript
+import {acceptWebSocket} from 'arcane-os/websocket';
+
+function attachEcho(server,signal){
+    const connections=new Set();
+    function upgrade(request,socket,head){
+        if(request.url!=='/socket'){
+            socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n');
+            return;
+        }
+        let connection;
+        try{connection=acceptWebSocket({request,socket,head,signal});}
+        catch(error){
+            console.error(error);
+            const status=error.statusCode??400;
+            const version=status===426?'Sec-WebSocket-Version: 13\r\n':'';
+            socket.end(`HTTP/1.1 ${status} Upgrade rejected\r\n${version}Connection: close\r\n\r\n`);
+            return;
+        }
+        connections.add(connection);
+        connection.addEventListener('error',function failed(event){console.error(event.detail);});
+        connection.addEventListener('message',function echo(event){
+            connection.send(event.data).catch(function sendFailed(error){console.error(error);});
+        });
+        connection.addEventListener('close',function remove(){connections.delete(connection);});
+    }
+    server.on('upgrade',upgrade);
+    return async function detach(){
+        server.off('upgrade',upgrade);
+        await Promise.all([...connections].map(function stop(connection){return connection.terminate();}));
+    };
+}
+
+// In browser code, after the host has selected its ws: or wss: URL:
+function connectEcho(url){
+    const client=new WebSocket(url);
+    client.addEventListener('open',function greet(){client.send('The moon needs a coffee break.');});
+    client.addEventListener('message',function received(event){console.log(event.data);});
+    return client;
+}
+```
+
+Protocol references: [RFC6455](https://www.rfc-editor.org/rfc/rfc6455.html),
+[Node upgrade event](https://nodejs.org/api/http.html#event-upgrade), and
+[native browser WebSocket](https://websockets.spec.whatwg.org/).
+Work is connection-local and linear in actual framing/content. Input is
+assembled once per complete message; advertised lengths do not preallocate
+payloads. Outbound framing snapshots each submitted message and uses native
+writable backpressure. Callers await `send` when producing a sustained stream.
+There is no history scan, app loop, diagnostic payload store or automatic retry.
+The authored `test/websocket.test.mjs` fixtures cover this boundary; source
+inspection is distinct from executing them or verifying a browser deployment.
+
 ## startDevServer()
 
 ### Overview
@@ -6669,6 +6882,67 @@ See the [mounting contract](pwa.md#mountpwainstallprompt) and
 [component reference](runtime-components.md#pwa-installhtml). The browser owns
 native installation eligibility and URL-bar promotion.
 
+## createBrowserDecisionModel()
+
+### Overview
+
+Creates an explicitly loaded browser model for Laya typed decisions in FP16 or
+Julia-1 in FP32. The shared Worker owns Transformers.js loading, full-input
+encoding, batched inference, complete results, cancellation and resource lifetime.
+Applications own model selection, questions, option meanings and decision policy.
+Existing chat and speech providers are unchanged.
+
+### Signature and result
+
+```js
+import {createBrowserDecisionModel} from 'arcane-os/ai/browser-decisions';
+
+const decisions = createBrowserDecisionModel(
+    {
+        family: 'laya',
+        model: 'onnx-community/laya-typed-decisions-ONNX',
+        device: 'webgpu'
+    }
+);
+```
+
+Construction starts no model download. The returned client exposes
+`load({signal})`, `evaluate(rows, {signal})`, `status()`,
+`subscribe(listener, {emitCurrent: true, signal})`, `unload()` and `dispose()`.
+Each row contains its complete `state`, `question`, string `options`, and
+optional `type` (`choice`, `score`, or `noul`). `evaluate()` returns
+`{decisions, outputs}` with all graph outputs and raw, unrounded probabilities.
+See the [complete browser decision contract](ai/browser-decisions.md) for
+precision, tokenization, output meanings, lifecycle and model limitations.
+
+### Availability and normalization
+
+Browser module Workers plus the selected Transformers.js backend are required
+on explicit use. Import and construction do not activate a model. Laya fixes
+`dtype: 'fp16'`; Julia fixes `dtype: 'fp32'`; there is no precision fallback.
+Cancellation terminates that client's Worker and rejects its in-flight work.
+No decisions are inserted into chat history or durable storage.
+
+### Example
+
+```js
+runButton.addEventListener(
+    'click',
+    async function askTeaRobot() {
+        const result = await decisions.evaluate(
+            [
+                {
+                    state: 'The dragon is asleep. The tea robot has a very loud kettle.',
+                    question: 'Should the robot boil tea now?',
+                    options: ['Wait quietly', 'Boil the kettle']
+                }
+            ]
+        );
+        output.textContent = result.decisions[0].value;
+    }
+);
+```
+
 ## createBrowserWasmLlmProvider()
 
 ### Overview