arcane-os 0.52.1 → 0.53.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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

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.1` 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/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/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 |
@@ -3753,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.1",
+  "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",

package/src/index.mjs

@@ -146,6 +146,7 @@ export {
 export {materializeInstalledSdkRuntime} from './installed-sdk-runtime.mjs';
 export {startDevServer} from './dev-server.mjs';
 export {startSourceExampleServer} from './source-server.mjs';
+export {acceptWebSocket} from './websocket.mjs';
 export {
     NATIVE_BUILD_PLAN_PROTOCOL,
     NATIVE_BUILDER_PROTOCOL,

package/src/websocket.mjs

@@ -0,0 +1,479 @@
+import {createHash} from 'node:crypto';
+import Is from 'strong-type';
+
+const is=new Is(false);
+const OPEN=1;
+const CLOSING=2;
+const CLOSED=3;
+const TOKEN=/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u;
+
+function protocolError(code,message,details={}){
+    const error=new Error(message);
+    error.code=`ARCANE_WEBSOCKET_${code}`;
+    return Object.assign(error,details);
+}
+
+function handshake(request,protocol){
+    const headers=request?.headers??{};
+    function tokens(value){
+        return is.string(value)?value.split(',').map(function trimToken(token){
+            return token.trim();
+        }):[];
+    }
+    function hasToken(value,expected){
+        return tokens(value).some(function matchesToken(token){
+            return token.toLowerCase()===expected;
+        });
+    }
+    function invalid(message){
+        return protocolError('HANDSHAKE_INVALID',message,{statusCode:400,headers:{}});
+    }
+    if(request?.method!=='GET'
+        ||request.httpVersionMajor!==1||request.httpVersionMinor<1
+        ||!is.string(headers.host)||!headers.host.trim()
+        ||!hasToken(headers.upgrade,'websocket')
+        ||!hasToken(headers.connection,'upgrade')){
+        throw invalid('WebSocket requires an HTTP/1.1 GET Upgrade request with Host.');
+    }
+    if(headers['sec-websocket-version']!=='13'){
+        throw protocolError('VERSION_UNSUPPORTED','WebSocket version 13 is required.',{
+            statusCode:426,
+            headers:{'Sec-WebSocket-Version':'13'}
+        });
+    }
+    const key=headers['sec-websocket-key'];
+    // The key syntax and SHA-1 accept value are required HTTP Upgrade framing,
+    // not a content identity, admission receipt, or application security policy.
+    if(!is.string(key)||!/^[A-Za-z0-9+/]{22}==$/u.test(key)
+        ||Buffer.from(key,'base64').length!==16){
+        throw invalid('Sec-WebSocket-Key must encode the RFC6455 handshake nonce.');
+    }
+    const offered=tokens(headers['sec-websocket-protocol']);
+    if(offered.some(function invalidToken(token){return !TOKEN.test(token);})
+        ||new Set(offered).size!==offered.length){
+        throw invalid('Sec-WebSocket-Protocol must contain distinct protocol tokens.');
+    }
+    if(!is.string(protocol)||(protocol!==''&&(!TOKEN.test(protocol)||!offered.includes(protocol)))){
+        throw invalid('The selected WebSocket protocol must be offered by the client.');
+    }
+    const accept=createHash('sha1')
+        .update(key+'258EAFA5-E914-47DA-95CA-C5AB0DC85B11')
+        .digest('base64');
+    return Buffer.from([
+        'HTTP/1.1 101 Switching Protocols',
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        `Sec-WebSocket-Accept: ${accept}`,
+        ...(protocol?[`Sec-WebSocket-Protocol: ${protocol}`]:[]),
+        '',
+        ''
+    ].join('\r\n'));
+}
+
+function binaryData(data){
+    if(data instanceof ArrayBuffer)return Buffer.from(data);
+    if(ArrayBuffer.isView(data))return Buffer.from(data.buffer,data.byteOffset,data.byteLength);
+    throw new TypeError('WebSocket data must be text, an ArrayBuffer, or an ArrayBuffer view.');
+}
+
+function framePacket(opcode,payload){
+    // Length fields belong only to the wire format. No product payload limit is imposed.
+    const length=payload.length;
+    const header=Buffer.alloc(length<126?2:length<=65535?4:10);
+    header[0]=0x80|opcode;
+    if(length<126)header[1]=length;
+    else if(length<=65535){
+        header[1]=126;
+        header.writeUInt16BE(length,2);
+    }else{
+        header[1]=127;
+        header.writeBigUInt64BE(BigInt(length),2);
+    }
+    // Snapshot the selected view at submission. Queued callers may reuse their input.
+    return Buffer.concat([header,payload]);
+}
+
+function validCloseCode(code){
+    return is.integer(code)&&(
+        (code>=1000&&code<=1014&&![1004,1005,1006].includes(code))
+        ||(code>=3000&&code<=4999)
+    );
+}
+
+function encodeText(text){
+    if(!text.isWellFormed()){
+        throw protocolError('TEXT_INVALID','WebSocket UTF-8 cannot represent an unpaired UTF-16 surrogate.');
+    }
+    return Buffer.from(text);
+}
+
+function closePayload(code,reason){
+    if(!validCloseCode(code))throw new RangeError('Invalid WebSocket close status code.');
+    if(!is.string(reason))throw new TypeError('WebSocket close reason must be text.');
+    const text=encodeText(reason);
+    // RFC6455 control frames permit 125 octets, including the two-octet status.
+    if(text.length>123)throw new RangeError('WebSocket close reason exceeds its protocol frame.');
+    const payload=Buffer.alloc(2+text.length);
+    payload.writeUInt16BE(code);
+    text.copy(payload,2);
+    return payload;
+}
+
+function abortError(reason){
+    const error=protocolError('ABORTED','WebSocket connection was aborted.',{cause:reason});
+    error.name='AbortError';
+    return error;
+}
+
+/** Accept one caller-selected HTTP/1.1 Upgrade. Owns no listener, route or storage. */
+export function acceptWebSocket({request,socket,head=Buffer.alloc(0),protocol='',signal}={}){
+    if(signal!=null&&(!is.function(signal.addEventListener)||!is.function(signal.removeEventListener))){
+        throw new TypeError('WebSocket signal must provide the AbortSignal event interface.');
+    }
+    if(signal?.aborted)throw abortError(signal.reason);
+    const response=handshake(request,protocol);
+    for(const method of ['on','off','pause','resume','write','end','destroy']){
+        if(!is.function(socket?.[method]))throw new TypeError(`Upgrade socket requires ${method}().`);
+    }
+    if(socket.destroyed||socket.readableEncoding){
+        throw new TypeError('Upgrade socket must be open and retain binary transport data.');
+    }
+    let initial=Buffer.from(binaryData(head));
+    const connection=new EventTarget();
+    let state=OPEN;
+    let started=false;
+    let failure=null;
+    let ending=false;
+    let failedProtocol=false;
+    let peerClose=null;
+    let closeQueued=false;
+    let closeWritten=false;
+    let activeWrite=null;
+    let incomingFrame=null;
+    let messageOpcode=0;
+    let messageParts=[];
+    const pendingInput=[];
+    const writes=[];
+    const header=Buffer.alloc(14);
+    let headerUsed=0;
+    let headerNeeded=2;
+    let settleClosed;
+    const closed=new Promise(function retainCloseSettlement(resolve){settleClosed=resolve;});
+
+    function closedError(){
+        return failure??protocolError('CONNECTION_CLOSED','WebSocket connection is closing or closed.');
+    }
+
+    function reportError(error){
+        if(failure)return;
+        failure=error;
+        connection.dispatchEvent(new CustomEvent('error',{detail:error}));
+    }
+
+    function rejectQueued(error,dataOnly=false){
+        for(const entry of writes.splice(0)){
+            if(dataOnly&&entry.kind!=='data')writes.push(entry);
+            else entry.reject(error);
+        }
+    }
+
+    function disposeInput(){
+        initial=null;
+        pendingInput.length=0;
+        messageParts=[];
+        incomingFrame=null;
+        messageOpcode=0;
+        headerUsed=0;
+    }
+
+    function finish(){
+        if(state===CLOSED)return;
+        state=CLOSED;
+        activeWrite?.finish(closedError());
+        rejectQueued(closedError());
+        disposeInput();
+        socket.off('data',receive);
+        socket.off('end',onEnd);
+        socket.off('error',onError);
+        socket.off('close',onClose);
+        signal?.removeEventListener('abort',onAbort);
+        const detail={
+            code:peerClose?.code??1006,
+            reason:peerClose?.reason??'',
+            wasClean:Boolean(peerClose&&closeWritten&&!failure),
+            error:failure
+        };
+        settleClosed(detail);
+        connection.dispatchEvent(new CustomEvent('close',{detail}));
+    }
+
+    function terminate(reason){
+        if(state===CLOSED)return closed;
+        state=CLOSING;
+        if(reason!==undefined)reportError(reason instanceof Error?reason:new Error('WebSocket terminated.',{cause:reason}));
+        activeWrite?.finish(closedError());
+        rejectQueued(closedError());
+        disposeInput();
+        // Keep the error/close observers installed until the actual stream closes.
+        socket.destroy();
+        return closed;
+    }
+
+    function onError(error){terminate(error);}
+    function onAbort(){terminate(abortError(signal.reason));}
+    function onClose(){finish();}
+    function onEnd(){
+        if(peerClose&&closeQueued){
+            if(closeWritten)endTransport();
+        }else{
+            terminate(protocolError('CONNECTION_CLOSED','WebSocket transport ended without a close exchange.'));
+        }
+    }
+
+    function endTransport(){
+        if(ending||state===CLOSED)return;
+        ending=true;
+        try{socket.end(function transportFlushed(){socket.destroy();});}
+        catch(error){terminate(error);}
+    }
+
+    function pumpWrites(){
+        if(!started||activeWrite||state===CLOSED||socket.destroyed||ending)return;
+        const entry=writes.shift();
+        if(!entry)return;
+        let callbackDone=false;
+        let drained=false;
+        let returned=false;
+        let settled=false;
+        function finishWrite(error){
+            if(settled)return;
+            if(!error&&(!callbackDone||!drained||!returned))return;
+            settled=true;
+            socket.off('drain',onDrain);
+            activeWrite=null;
+            if(error)entry.reject(error);
+            else entry.resolve();
+            queueMicrotask(pumpWrites);
+        }
+        function onDrain(){drained=true;finishWrite();}
+        function onWritten(error){
+            if(error){
+                finishWrite(error);
+                terminate(error);
+                return;
+            }
+            callbackDone=true;
+            finishWrite();
+        }
+        activeWrite={finish:finishWrite};
+        socket.on('drain',onDrain);
+        try{
+            // false means already accepted: await drain, never resubmit this packet.
+            if(socket.write(entry.packet,onWritten))drained=true;
+            returned=true;
+            finishWrite();
+        }catch(error){
+            finishWrite(error);
+            terminate(error);
+        }
+    }
+
+    function enqueue(packet,kind='data'){
+        const promise=new Promise(function retainWriteSettlement(resolve,reject){
+            writes.push({packet,kind,resolve,reject});
+        });
+        pumpWrites();
+        return promise;
+    }
+
+    function send(data){
+        if(state!==OPEN)return Promise.reject(closedError());
+        try{
+            const text=is.string(data);
+            return enqueue(framePacket(text?1:2,text?encodeText(data):binaryData(data)));
+        }catch(error){return Promise.reject(error);}
+    }
+
+    function queueClose(payload){
+        if(closeQueued)return;
+        closeQueued=true;
+        enqueue(framePacket(8,payload),'close').then(function closeSent(){
+            closeWritten=true;
+            if(peerClose||failedProtocol)endTransport();
+        },function closeSendFailed(error){terminate(error);});
+    }
+
+    function close(code=1000,reason=''){
+        if(state!==OPEN)return closed;
+        const payload=closePayload(code,reason);
+        state=CLOSING;
+        queueClose(payload);
+        return closed;
+    }
+
+    function failProtocol(error){
+        if(failedProtocol||state===CLOSED)return;
+        failedProtocol=true;
+        state=CLOSING;
+        socket.pause();
+        disposeInput();
+        reportError(error);
+        rejectQueued(error,true);
+        // A packet already accepted by write must finish before a close frame.
+        if(!closeQueued){
+            queueClose(closePayload(error.closeCode??1011,''));
+        }else if(closeWritten){endTransport();}
+    }
+
+    function invalidFrame(message){
+        throw protocolError('PROTOCOL_INVALID',message,{closeCode:1002});
+    }
+
+    function decodeText(payload){
+        try{
+            return new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(payload);
+        }catch(cause){
+            throw protocolError('TEXT_INVALID','WebSocket text is not valid UTF-8.',{closeCode:1007,cause});
+        }
+    }
+
+    function validateBaseHeader(){
+        const opcode=header[0]&15;
+        const final=Boolean(header[0]&128);
+        const control=opcode>=8;
+        const encodedLength=header[1]&127;
+        if(header[0]&112)invalidFrame('WebSocket extensions were not negotiated.');
+        if(!(header[1]&128))invalidFrame('Client WebSocket frames must be masked.');
+        if(![0,1,2,8,9,10].includes(opcode))invalidFrame('Unknown WebSocket opcode.');
+        if(control&&(!final||encodedLength>125))invalidFrame('Invalid WebSocket control frame.');
+        if(!control){
+            if(opcode===0&&!messageOpcode)invalidFrame('Unexpected WebSocket continuation.');
+            if(opcode!==0&&messageOpcode)invalidFrame('Interleaved WebSocket messages.');
+        }
+    }
+
+    function beginFrame(){
+        const opcode=header[0]&15;
+        const final=Boolean(header[0]&128);
+        const control=opcode>=8;
+        const encodedLength=header[1]&127;
+        let length=BigInt(encodedLength);
+        if(encodedLength===126){
+            length=BigInt(header.readUInt16BE(2));
+            if(length<126n)invalidFrame('Nonminimal WebSocket length encoding.');
+        }else if(encodedLength===127){
+            length=header.readBigUInt64BE(2);
+            if(length<65536n||length>>63n)invalidFrame('Invalid WebSocket extended length.');
+        }
+        if(!control){
+            if(opcode!==0)messageOpcode=opcode;
+        }
+        incomingFrame={
+            opcode,final,control,remaining:length,
+            mask:Buffer.from(header.subarray(headerNeeded-4,headerNeeded)),
+            maskIndex:0,parts:[]
+        };
+        headerUsed=0;
+        headerNeeded=2;
+    }
+
+    function completeFrame(){
+        const frame=incomingFrame;
+        incomingFrame=null;
+        if(frame.control){
+            const payload=Buffer.concat(frame.parts);
+            if(frame.opcode===8){
+                if(payload.length===1)invalidFrame('Incomplete WebSocket close status.');
+                const code=payload.length?payload.readUInt16BE(0):1005;
+                if(payload.length&&!validCloseCode(code))invalidFrame('Invalid WebSocket close status.');
+                const reason=payload.length?decodeText(payload.subarray(2)):'';
+                peerClose={code,reason};
+                state=CLOSING;
+                rejectQueued(closedError(),true);
+                if(!closeQueued){
+                    queueClose(payload);
+                }
+                if(closeWritten)endTransport();
+            }else if(frame.opcode===9&&!peerClose){
+                enqueue(framePacket(10,payload),'control').catch(function pongFailed(error){terminate(error);});
+            }
+        }else if(frame.final){
+            const opcode=messageOpcode;
+            const parts=messageParts;
+            messageParts=[];
+            messageOpcode=0;
+            if(state===OPEN){
+                const payload=Buffer.concat(parts);
+                const data=opcode===1?decodeText(payload):new Uint8Array(payload.buffer,payload.byteOffset,payload.length);
+                connection.dispatchEvent(new MessageEvent('message',{data}));
+            }
+        }
+    }
+
+    function consume(chunk){
+        let offset=0;
+        while(offset<chunk.length&&!failedProtocol&&state!==CLOSED&&!socket.destroyed&&!peerClose){
+            if(!incomingFrame){
+                const count=Math.min(headerNeeded-headerUsed,chunk.length-offset);
+                chunk.copy(header,headerUsed,offset,offset+count);
+                offset+=count;
+                headerUsed+=count;
+                if(headerUsed<headerNeeded)continue;
+                if(headerNeeded===2){
+                    validateBaseHeader();
+                    const encodedLength=header[1]&127;
+                    headerNeeded=2+(encodedLength===126?2:encodedLength===127?8:0)+4;
+                    continue;
+                }
+                beginFrame();
+            }
+            const frame=incomingFrame;
+            const available=chunk.length-offset;
+            const count=frame.remaining<BigInt(available)?Number(frame.remaining):available;
+            if(count){
+                const payload=Buffer.allocUnsafe(count);
+                for(let index=0;index<count;index++){
+                    payload[index]=chunk[offset+index]^frame.mask[frame.maskIndex];
+                    frame.maskIndex=(frame.maskIndex+1)&3;
+                }
+                offset+=count;
+                frame.remaining-=BigInt(count);
+                if(frame.control)frame.parts.push(payload);
+                else if(state===OPEN)messageParts.push(payload);
+            }
+            if(frame.remaining===0n)completeFrame();
+        }
+    }
+
+    function receive(chunk){
+        if(failedProtocol||state===CLOSED||socket.destroyed||peerClose)return;
+        if(!started){pendingInput.push(chunk);return;}
+        try{consume(chunk);}
+        catch(error){failProtocol(error);}
+    }
+
+    Object.defineProperties(connection,{
+        readyState:{get:function readState(){return state;},enumerable:true},
+        protocol:{value:protocol,enumerable:true},
+        closed:{value:closed,enumerable:true}
+    });
+    Object.assign(connection,{send,close,terminate});
+    socket.pause();
+    socket.on('data',receive);
+    socket.on('end',onEnd);
+    socket.on('error',onError);
+    socket.on('close',onClose);
+    signal?.addEventListener('abort',onAbort,{once:true});
+    enqueue(response,'handshake').catch(function handshakeWriteFailed(error){terminate(error);});
+    queueMicrotask(function startConnection(){
+        started=true;
+        if(signal?.aborted){onAbort();return;}
+        if(state===CLOSED||socket.destroyed)return;
+        pumpWrites();
+        receive(initial);
+        initial=null;
+        for(const chunk of pendingInput.splice(0))receive(chunk);
+        if(!failedProtocol&&!peerClose&&state!==CLOSED&&!socket.destroyed)socket.resume();
+    });
+    return connection;
+}