arcane-os 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.53.0
+
+- Add `acceptWebSocket` through `arcane-os/websocket` and the Node root export.
+  Accept a caller-selected native HTTP/1.1 Upgrade and exchange complete text
+  and binary messages with fragmentation, Ping/Pong, ordered writable
+  backpressure, close/abort handling and observable connection settlement.
+  Buffered Upgrade input reaches synchronously registered listeners in order.
+- Preserve valid text, leading Unicode markers and binary view boundaries.
+  Text that cannot be represented exactly as UTF-8 reports an explicit error
+  before transmission or a close-state change. Browser clients use native
+  `WebSocket`; existing HTTP/TLS listeners, routes and application messages
+  remain caller-owned.
+- No third-party WebSocket runtime, client sharing, reconnect, application
+  envelope, storage, HTTP/2 extended CONNECT or extension negotiation is added.
+  Existing SDK behavior and dependencies remain unchanged. Ordinary consumers
+  update through their public package workflow; optional server integration
+  belongs to the consuming application.
+
+## 0.52.1
+
+- Preserve an authored host `index.html` at `/` independently of application
+  entry and offline selection. Root import-map/PWA generation no longer aliases
+  that public homepage to the app entry. Existing app-only roots retain their
+  launcher behavior; excluded homepage content and assets stay outside the
+  application's managed documents and offline inventory.
+- Source development follows root-file creation/removal without a descriptor
+  edit, serves an unselected host root unchanged, and avoids stale conditional
+  responses when generated aliases change within one HTTP second. Ordinary
+  selected routes, startup entry, manifest identity and worker lifecycle remain
+  unchanged.
+- Packaged authored roots carry optional generated `app.rootDocument` metadata
+  so preview serves them at `/`; older and app-only packages retain their
+  existing redirects and queries. Worker directory navigation uses only indexes
+  already selected in its current offline inventory, with exact-query priority.
+  No dependency, configuration option, saved-data migration or cache reset is
+  introduced. Consumers regenerate their normal public SDK outputs after update.
+
 ## 0.52.0
 
 - Add optional `package.documents` to select managed application HTML separately

package/README.md

@@ -20,7 +20,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.52.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.53.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/architecture.md

@@ -145,6 +145,19 @@ one metadata task; unchanged files reuse their parsed selection. Shared runtime
 requests do not wait for that refresh. Full offline inventories are enumerated
 only for worker/offline-manifest requests, with separate state for each selected
 app snapshot so an older inventory cannot overwrite newer generated metadata.
+
+Authored host-root `index.html` presence is refreshed independently of descriptor
+edits. Development serves that host index at `/` instead of redirecting to the
+app entry and suppresses the root PWA alias. An index outside the selected app
+mapping uses an unchanged exact-root response; `/index.html` and other resource
+URLs retain their existing selection rules. A selected index keeps its existing
+document classification. This broadens no app or offline inventory and adds no
+managed maps or bootstrap. With no host index, the app-entry redirect remains.
+A worker serves a directory's cached index body only when that index is already
+in its current offline selection; otherwise the host owns the unchanged request.
+The selected app launch and installation identity remain independent of this
+host-root navigation.
+
 Changed resource requests return the complete current saved source without
 packaging, copying files into `dist`, or restarting the server. Conditional
 requests for unchanged resources return `304`. Enabled PWAs check on page load
@@ -253,9 +266,12 @@ separate. See the [complete output contract](reference/protocols.md#app-selected
 
 Packaging keeps standalone app files at the release root and places an explicitly
 nested app beneath `apps/<id>/`. It preserves every shared route destination.
-When selected content supplies no root `index.html`, the SDK generates one that
-opens the selected app entry. Authored document bases, app URLs, relative module
-imports and shared runtime paths therefore resolve through the same layout in
+A selected authored output-root `index.html` is preserved and suppresses the
+deployment-root PWA navigation alias. When selected content supplies no root
+index, the SDK generates a launcher and retains the selected app-entry alias;
+an excluded source-host index does not alter that package result. Authored
+document bases, app URLs, relative module imports and shared runtime paths
+therefore resolve through the same layout in
 source development and packaged delivery. Packaging consumes the saved source
 and managed import maps; use `arcane import-map` to refresh those maps, or the
 ordinary `arcane dev` startup that performs that refresh.
@@ -266,6 +282,13 @@ entry, or `./apps/hello-world/index.html` for a nested app. Its complete `files`
 inventory follows the selected layout and includes the root `index.html`.
 Packaged browser serving opens `app.start`; a previously generated flat release without `app.start` retains
 its `app.entry` launch path.
+Only selected records supplying an authored output-root index add the optional
+generated `app.rootDocument: "./index.html"` release field. Preview serves that
+document at `/` without inferring ownership from HTML content. When the field is
+absent, older releases and generated-launcher packages retain their existing
+`302` root redirect to `app.start` or the older `app.entry` fallback, preserving
+the request query. This release fact adds no app configuration or API option and
+does not change `app.start`.
 
 The authored schema-2 descriptor is canonical for new apps and projects an
 exact schema-1 `arcane-package.json` for current consumers. Existing Arcane

package/docs/reference/cli.md

@@ -245,6 +245,12 @@ files remain unchanged. The same layout applies to `arcane dev` and
 `arcane package`. Generated and offline app files are committed; GitHub Actions
 consume those committed files. See [root generated output](pwa.md#root-generated-output).
 
+An existing authored source-host `index.html` suppresses the generated `/`
+navigation alias even when the page is outside the application or offline
+selection. It is not automatically added to either inventory or given managed
+maps or PWA bootstrap. The selected app entry and installation identity remain
+unchanged; see [authored host roots](pwa.md#authored-host-root-and-app-entry).
+
 The supported physical layout preserves its route count and ordered include
 list. External and modern integrated physical routes require `components`, `css`,
 `dependencies`, `entities`, `img`, `modules`, and `sdk`; a physical workspace
@@ -373,6 +379,16 @@ not package the app or produce `dist` output. With PWA enabled, the server
 generates the installation and offline manifests directly; see
 [PWA development and versioning](pwa.md#development-and-hosting).
 
+The startup URL remains the selected app entry. At `/`, the server serves an
+existing authored host-root `index.html` and suppresses the app-entry redirect
+and PWA alias. A root outside the selected app mapping is served unchanged only
+through this exact-root route; `/index.html` and other resource URLs retain their
+existing selection rules. A selected root follows its existing document
+classification. Root presence does not expand either inventory or cause
+bootstrap injection. With no host index, the app-entry redirect remains.
+Root-file creation or removal is reflected in subsequent root-navigation and
+generated-PWA requests without a restart or a descriptor edit.
+
 The command reports acceptance before bind/start work, emits the final URL,
 owns the server until cancellation, and restores failure to the process exit.
 The default host is `127.0.0.1`. `--public` selects `0.0.0.0` (all IPv4
@@ -550,8 +566,11 @@ defaulting to `dist/<id>/`, and preserves the prior output until the replacement
 is complete. It consumes saved source and managed
 import maps, keeps standalone app files at the output root, and retains the
 configured shared route destinations. Explicit multi-app workspaces retain
-their selected app beneath `apps/<id>/`. When selected shared content supplies no root
-`index.html`, the SDK generates one that opens the selected app entry.
+their selected app beneath `apps/<id>/`. A selected authored output-root
+`index.html` is preserved and suppresses the deployment-root PWA navigation
+alias. When selected content supplies no root index, the SDK generates a launcher
+and retains the app-entry alias. An excluded source-host root does not change
+that package selection.
 Source document bases and resource URLs therefore retain their development
 layout. Packaging does not run tests or checks automatically.
 
@@ -584,6 +603,10 @@ The result includes the release root, manifest, and complete selected inventory.
 the package launch URL in `app.start`: `./index.html` for a root app with that
 entry, or `./apps/hello-world/index.html` for a nested app. The complete file
 inventory follows the selected layout and includes the root `index.html`.
+Only selected records supplying an authored output-root index add
+`app.rootDocument: "./index.html"`. This optional generated release fact selects
+root-document serving in preview; it is not an app configuration or CLI option
+and does not change `app.start`.
 `--dry-run` plans the package without refreshing source, running tests, or
 replacing output.
 
@@ -749,6 +772,11 @@ For `--target browser`, starts the existing release in the app's configured
 does not package, rebuild, test, check, or verify that release automatically.
 It opens the release manifest's `app.start` URL. Older flat releases without
 that field continue to open their `app.entry` path.
+Requests to `/` serve the explicit `app.rootDocument` when that generated
+release field is present. With no field, including older releases and app-only
+packages with a generated launcher, `/` retains its `302` redirect to
+`app.start` or the older `app.entry` fallback, preserving the request query.
+Preview does not infer root ownership from HTML content.
 The preview always uses HTTPS with the workspace certificate pair. Supply
 `--cert <file> --key <file>` together to use another pair; see
 [development HTTPS setup](#development-https-setup).

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

@@ -6,12 +6,26 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 223,
+  "memberCount": 224,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "root:acceptWebSocket",
+      "name": "acceptWebSocket",
+      "displayName": "acceptWebSocket()",
+      "kind": "function",
+      "signature": "acceptWebSocket({request,socket,head,protocol,signal})",
+      "entrypoints": ["arcane-os", "arcane-os/websocket"],
+      "primaryImport": "arcane-os/websocket",
+      "group": "WebSocket protocol",
+      "summary": "Accept one caller-selected HTTP/1.1 Upgrade and exchange complete native WebSocket messages.",
+      "availability": "Node; interoperates with browser native WebSocket clients",
+      "protocol": "RFC6455 version 13, without extensions or HTTP/2 extended CONNECT",
+      "normalization": "Native EventTarget message/error/close events and owned send/close promises; no application envelopes or storage"
+    },
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
       "name": "APP_BUNDLE_DESCRIPTOR_NAME",

package/docs/reference/protocols.md

@@ -251,15 +251,34 @@ The declared application ID remains unchanged. `appsRoot: "apps"` continues
 to discover `apps/<id>` and supports the existing integrated and multi-app
 layouts. Entries and include/exclude paths remain relative to the application.
 
-Root HTML uses `<base href="./">`; nested navigable documents use their actual
-depth back to the workspace. Managed bare imports remain the public interface;
-their targets follow the selected npm routes. `arcane import-map` generates
-enabled static PWA records at the app root, so normal static hosting needs no
+SDK-managed root HTML uses `<base href="./">`; nested navigable documents use
+their actual depth back to the workspace. Managed bare imports remain the
+public interface; their targets follow the selected npm routes. `arcane import-map`
+generates enabled static PWA records at the app root, so normal static hosting needs no
 SDK request handler or runtime copy. Managed refresh, development serving,
 inspection, dry run and packaging add no nested `apps/<id>/` navigation pages,
 redirects, or duplicate PWA worker/inventory files. There is no output-retention
 switch for those retired records.
 
+An authored source-host `index.html` suppresses the root app-entry redirect and
+generated PWA navigation alias even when that file is outside the application's
+include or offline selection. Development serves that host index at `/`. An
+index outside the selected app mapping uses an unchanged exact-root response;
+`/index.html` and other resource URLs retain their existing selection rules.
+A selected index follows the existing document classification. Root presence
+adds no page, assets, managed maps, or PWA bootstrap to the application. With no
+host index, development retains the app-entry redirect. In a package, only a
+selected authored output-root index suppresses the alias; an absent or excluded
+root retains the generated launcher and app-entry alias. Selected records that
+supply an authored output-root index add the optional generated release field
+`app.rootDocument: "./index.html"`. Preview serves that document at `/`; absence
+retains the existing `302` to `app.start` or the older `app.entry` fallback with
+the request query preserved. This is a release fact, not an app setting or HTML
+content inference, and `app.start` remains unchanged. The worker can answer a
+directory navigation from an index only when that index already belongs to its
+current offline selection and has a cached response; otherwise the unchanged
+request remains host-owned. See [authored host roots](pwa.md#authored-host-root-and-app-entry).
+
 Application identity, stored data, the existing default installation ID and an
 authored `pwa.manifest.id` remain unchanged. Authored resources continue to
 follow the app's include/exclude selection; generation does not delete existing

package/docs/reference/pwa.md

@@ -102,6 +102,38 @@ committed files rather than generating them. Actual multi-app workspaces keep
 their explicit `appsRoot: "apps"` layout. This source/package contract does not
 establish any particular installed application's browser lifecycle.
 
+### Authored host root and app entry
+
+An authored `index.html` at the source host root keeps `/` separate from the
+selected application entry. Root import-map generation and development PWA
+generation omit the `/`-to-entry navigation alias whenever that file exists,
+including when it is outside `package.include` or the offline selection.
+Development serving answers `/` with that host index. An index outside the app's
+selected source mapping is served unchanged through this exact-root route;
+`/index.html` and other resource URLs retain their existing selection rules.
+A selected index follows its existing managed-document classification. Root
+presence alone adds no page or assets to the application or offline inventory
+and adds no managed maps or PWA bootstrap. The host owns a root response outside
+the worker's selected offline resources. With no host index, development retains
+its app-entry redirect.
+
+Packaging considers the selected output instead of unrelated source-host files.
+A selected authored output-root `index.html` is preserved and suppresses the
+deployment-root navigation alias. When selected content supplies no output-root
+index, the package retains its generated launcher and app-entry alias. An
+authored source root excluded from the package does not replace that launcher.
+Only when selected records supply an authored output-root index does packaging
+write `app.rootDocument: "./index.html"` in `ARCANE_APP_RELEASE.json`.
+Packaged preview uses that generated field to serve the authored document at
+`/`; it does not inspect HTML to infer root ownership. Without the field,
+including older releases and generated-launcher packages, preview retains its
+`302` redirect to `app.start` (or the older `app.entry` fallback), preserving the
+request query. The startup URL remains the selected app launch URL.
+
+This behavior requires no new setting. The application entry, default install
+start URL, manifest identity and scope, worker registration scope, cache
+identity, and saved application data keep their existing contracts.
+
 ### Offline resource selection
 
 `offline.include` and `offline.exclude` select literal paths or directory
@@ -304,8 +336,10 @@ therefore matters even when an offline cache exists. Updating files in place
 while installation fetches them is not an atomic release snapshot; the host owns
 consistent deployment of the selected output.
 
-An offline navigation alias redirects to its selected entry page, preserving the
-document URL used to resolve relative modules and styles.
+Where an app-entry navigation alias remains, it redirects to the selected entry
+page, preserving the document URL used to resolve relative modules and styles.
+An authored host root suppresses that alias as described above; merely retaining
+an old cached root resource does not add it to the current offline selection.
 
 For a same-origin navigation to a selected static `.html` or `.htm` document,
 the worker can reuse that document's cached body while leaving the complete
@@ -319,6 +353,14 @@ document. This does not change query matching for assets, API calls, ordinary
 fetch requests, unselected documents or other origins. Cache refresh and the
 Update prompt keep their existing lifecycle.
 
+For a same-origin directory navigation without an app-entry alias, the worker
+can likewise reuse that directory's `index.html` body only when the index is
+already in the current offline selection and has a retained cached response.
+The directory URL and its query remain unchanged, including beneath a deployment
+subpath. An exact query-specific selected resource takes precedence. Otherwise,
+the original request passes to the host unchanged. This adds no page or asset to
+the inventory and does not save a host response over the selected index.
+
 Browser storage eviction can remove an offline cache. A missing release cache
 entry falls back to the network, so offline availability still depends on the
 browser retaining the selected resources.

package/docs/reference/sdk-api.md

@@ -41,6 +41,7 @@ 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 connection lifecycle. Browser clients use native `WebSocket`. |
 | `arcane-os/testing` | Isolated test registration and execution. |
 | `arcane-os/targets` | Target adapters and dispatch. |
 | `arcane-os/native` | Native plan and builder protocol. |
@@ -130,6 +131,7 @@ 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 |
 | `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 |
@@ -882,7 +884,14 @@ generates one that opens the selected app page. The result
 contains `outputRoot`, `manifest`, and the complete `files` inventory.
 `manifest.app.entry` stays app-relative, while `manifest.app.start`
 is the package launch URL, such as `./index.html` for a root app or
-`./apps/hello-world/index.html` for a nested app. Release
+`./apps/hello-world/index.html` for a nested app. Only when selected records
+supply an authored output-root index does the release add
+`manifest.app.rootDocument: "./index.html"`. Preview serves that explicit
+document at `/`; without the field, older releases and generated-launcher
+packages retain the `302` redirect to `app.start` or the older `app.entry`
+fallback with the request query preserved. This generated release fact adds no
+app configuration or API option, changes no `app.start`, and requires no HTML
+content inference. Release
 schema `1`, kind `arcane-app-release`, and packager identity
 `arcane-app-packager-v1` remain unchanged. A dry run returns the planned output
 and file inventory without writing source or output.
@@ -3746,6 +3755,154 @@ async function useselectApp(...arguments_) {
 }
 ```
 
+## 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.
+
+Browser clients use native `WebSocket` directly. 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -12,6 +12,7 @@
     ".": "./src/index.mjs",
     "./toolchain": "./src/toolchain.mjs",
     "./events": "./src/events.mjs",
+    "./websocket": "./src/websocket.mjs",
     "./event-manager": "./src/event-manager.mjs",
     "./modules/*": "./runtime/arcane/modules/*",
     "./entities/*": "./runtime/arcane/entities/*",
@@ -86,7 +87,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/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-speech-providers.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/dbopfs-document-library.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/file-preview.test.mjs test/import-map.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/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/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-speech-providers.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/dbopfs-document-library.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/file-preview.test.mjs test/import-map.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/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.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-plan.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/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.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",