redweb-client 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.3.0
+
+- Accept typed socket commands emitted by Redweb's server TSX controls on the page's custom route, reusing existing form feedback and DOM reconciliation. Requires Redweb 0.15.0 for socket-bound pages; ordinary Live HTML remains compatible with Redweb 0.14.0.
+- Add optional `request(..., { responseType })` filtering so intermediate correlated events do not complete a request before its terminal reply. Correlated protocol errors still reject immediately; omitting the option retains existing behavior.
+- Preserve explicitly bound JSON payloads, including `null`, and merge form fields over bound object payloads. Commands retain cancellation, deadlines and no-replay behavior.
+- Rebuild distribution files automatically before packing/publishing, and include these release notes in the package.
+
+Prepared for manual publication. No new runtime dependencies.

package/README.md

@@ -2,17 +2,31 @@
 
 Browser-first WebSocket client for [Redweb](https://redweb.magnisolution.com/). It adds connection lifecycle, typed message subscriptions, request correlation, bounded queuing, opt-in reconnection, and versioned Redweb protocol envelopes without adding runtime dependencies.
 
-## Unreleased lifecycle hardening
+## Connection lifecycle
 
-The development branch fixes connection attempts continuing after a synchronous state observer calls `close()` or `dispose()`. Connection attempts are identified across callback boundaries; a reentrant `connect()` shares an existing attempt, and an explicit replacement is not cleared by an older attempt finishing. Cancelled transport-factory results are closed after their lifecycle listeners are attached. These changes are not yet published in npm version 0.1.0.
+Connection attempts stop when a synchronous state observer calls `close()` or `dispose()`. Attempts are identified across callback boundaries; a reentrant `connect()` shares an existing attempt, and an explicit replacement is not cleared by an older attempt finishing. Cancelled transport-factory results are closed after their lifecycle listeners are attached.
 
 Integration regressions use real WebSocket connections and timers for observer-driven cancellation, upgrade-refusal retries, queued delivery, cancellation without replay, and rejected sends after disposal. Unit tests use isolated transport fixtures and explicitly simulated stale scheduling; integration tests do not mock transports. The complete verification command and its coverage scope are described below.
 
-## Unreleased Live HTML integration
+## Live HTML integration
+
+### Typed socket-page commands (0.3.0)
+
+Version 0.3.0 accepts server-emitted command bindings on
+existing Live HTML controls. It sends the actual `join`/`move` message type on
+the page's custom route and reuses pending/error feedback and DOM reconciliation.
+No application browser module is necessary. Socket-bound pages require Redweb
+0.15.0; the earlier client 0.2.0 does not support these command bindings.
+
+Direct request users may pass `{ responseType: 'redweb:result' }` to wait for a
+specific terminal reply. Intermediate correlated events still reach subscribers
+but do not settle that request. Correlated protocol errors reject immediately.
+Omitting `responseType` preserves existing request behavior. Requests retain their
+deadline/cancellation and no-replay guarantees.
 
 The optional `redweb-client/live-html` entry owns reactive DOM updates, keyed
 reconciliation, delegated actions/forms, feedback and connection status for pages
-rendered by the matching Redweb development branch. The root import stays
+rendered by Redweb. The root import stays
 socket-only. Redweb serves the optional self-contained module and automatically
 calls `mountLivePage()`; ordinary applications need no additional browser glue.
 
@@ -34,22 +48,18 @@ again shares the same owner; a disposed page cannot later reset a submitted draf
 For local development with sibling repositories, run `npm run build` and
 `npm link --ignore-scripts` here, then `npm link redweb-client --no-save --ignore-scripts`
 in Redweb. Rebuild here after source changes; no repacking is needed. The link is
-not saved in either lockfile. Published 0.1.0 does not include this entry; client
-publication and Redweb dependency/lockfile updates remain release prerequisites.
+not saved in either lockfile. The optional entry was introduced in 0.2.0;
+socket-bound page commands and terminal-response filtering are added in 0.3.0.
 
-Redweb's native-browser gate checks the server-side counter, multi-user chat,
-dashboard and forms using real HTTP/WebSockets. Its rendering coverage verifier
-measures all bundled Live HTML modules separately from transport and currently
-covers 426 statements, 262 branches, 64 functions and 351 lines (100% each).
-This is emitted-frontend coverage, not complete original-source/client-package or
-cross-browser certification. Separate V8 measurements are not substituted for
-the complete original-source gate below; the full release gate is not approved.
+Redweb's headed-browser gates check the server-side counter, multi-user chat,
+dashboard, forms and socket-bound multiplayer tutorial using real HTTP/WebSockets.
+These are not cross-browser certification or a guarantee about application security.
 
 From the linked Redweb repository, `npm run verify:client:source-coverage` runs
-all 77 client tests both plain and instrumented, then native browser tests with
+the complete client test inventory both plain and instrumented, then headed browser tests with
 the same original-source coverage maps. Plain browser bundles must match this
 client's `dist` output. It retains separate Node/browser results and currently
-covers all 791 statements, 521 branches, 125 functions and 659 lines (100% each).
+covers all 800 statements, 543 branches, 125 functions and 667 lines (100% each).
 The same gate runs through the default `npm test` command. This metric does not
 replace V8 coverage or independently count every optional-chain short circuit.
 

package/dist/{client-Dq8oKJwh.d.cts → client-D35g1hrL.d.cts}

@@ -60,6 +60,8 @@ interface RedwebClientOptions {
     random?: () => number;
 }
 interface RequestOptions extends ProtocolMetadata {
+    /** Ignore intermediate correlated events; protocol errors still reject immediately. */
+    responseType?: string;
     timeoutMs?: number;
     signal?: AbortSignal;
 }

package/dist/{client-Dq8oKJwh.d.ts → client-D35g1hrL.d.ts}

@@ -60,6 +60,8 @@ interface RedwebClientOptions {
     random?: () => number;
 }
 interface RequestOptions extends ProtocolMetadata {
+    /** Ignore intermediate correlated events; protocol errors still reject immediately. */
+    responseType?: string;
     timeoutMs?: number;
     signal?: AbortSignal;
 }

package/dist/index.cjs

@@ -368,6 +368,9 @@ var RedwebClient = class {
     const requestId = options.requestId ?? this.createRequestId();
     const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
     assertNonNegativeInteger(timeoutMs, "timeoutMs");
+    if (options.responseType !== void 0 && (typeof options.responseType !== "string" || !options.responseType || options.responseType.length > 256)) {
+      return Promise.reject(new TypeError("responseType must be a non-empty string of at most 256 characters."));
+    }
     if (options.signal?.aborted) return Promise.reject(new DOMException("The request was aborted.", "AbortError"));
     if (this.pending.has(requestId)) return Promise.reject(new Error(`A Redweb request with id "${requestId}" is already pending.`));
     return new Promise((resolve, reject) => {
@@ -375,7 +378,7 @@ var RedwebClient = class {
         this.finishPending(requestId);
         reject(new Error(`Redweb request timed out after ${timeoutMs}ms.`));
       }, timeoutMs);
-      const pending = { resolve, reject, timer };
+      const pending = { resolve, reject, timer, responseType: options.responseType };
       if (options.signal) {
         pending.signal = options.signal;
         pending.abort = () => {
@@ -482,7 +485,7 @@ var RedwebClient = class {
     const requestId = message.requestId;
     if (typeof requestId === "string") {
       const pending = this.pending.get(requestId);
-      if (pending) {
+      if (pending && (pending.responseType === void 0 || message.type === pending.responseType || message.type === "error" && "error" in message)) {
         this.finishPending(requestId);
         if (message.type === "error" && "error" in message) pending.reject(new RedwebProtocolError(message));
         else pending.resolve(message);

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { P as ProtocolErrorEnvelope, a as ProtocolMetadata, R as RedwebMessage, b as ProtocolEnvelope } from './client-Dq8oKJwh.cjs';
-export { B as BinaryListener, C as ClientState, c as CloseListener, E as ErrorListener, L as LegacyErrorMessage, M as MessageListener, d as ReconnectOptions, e as RedwebClient, f as RedwebClientOptions, g as RequestOptions, S as SocketEventLike, h as StateListener, W as WaitOptions, i as WebSocketLike } from './client-Dq8oKJwh.cjs';
+import { P as ProtocolErrorEnvelope, a as ProtocolMetadata, R as RedwebMessage, b as ProtocolEnvelope } from './client-D35g1hrL.cjs';
+export { B as BinaryListener, C as ClientState, c as CloseListener, E as ErrorListener, L as LegacyErrorMessage, M as MessageListener, d as ReconnectOptions, e as RedwebClient, f as RedwebClientOptions, g as RequestOptions, S as SocketEventLike, h as StateListener, W as WaitOptions, i as WebSocketLike } from './client-D35g1hrL.cjs';
 
 declare const ERROR_CODES: Readonly<{
     readonly INVALID_MESSAGE: "INVALID_MESSAGE";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as ProtocolErrorEnvelope, a as ProtocolMetadata, R as RedwebMessage, b as ProtocolEnvelope } from './client-Dq8oKJwh.js';
-export { B as BinaryListener, C as ClientState, c as CloseListener, E as ErrorListener, L as LegacyErrorMessage, M as MessageListener, d as ReconnectOptions, e as RedwebClient, f as RedwebClientOptions, g as RequestOptions, S as SocketEventLike, h as StateListener, W as WaitOptions, i as WebSocketLike } from './client-Dq8oKJwh.js';
+import { P as ProtocolErrorEnvelope, a as ProtocolMetadata, R as RedwebMessage, b as ProtocolEnvelope } from './client-D35g1hrL.js';
+export { B as BinaryListener, C as ClientState, c as CloseListener, E as ErrorListener, L as LegacyErrorMessage, M as MessageListener, d as ReconnectOptions, e as RedwebClient, f as RedwebClientOptions, g as RequestOptions, S as SocketEventLike, h as StateListener, W as WaitOptions, i as WebSocketLike } from './client-D35g1hrL.js';
 
 declare const ERROR_CODES: Readonly<{
     readonly INVALID_MESSAGE: "INVALID_MESSAGE";

package/dist/index.js

@@ -336,6 +336,9 @@ var RedwebClient = class {
     const requestId = options.requestId ?? this.createRequestId();
     const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
     assertNonNegativeInteger(timeoutMs, "timeoutMs");
+    if (options.responseType !== void 0 && (typeof options.responseType !== "string" || !options.responseType || options.responseType.length > 256)) {
+      return Promise.reject(new TypeError("responseType must be a non-empty string of at most 256 characters."));
+    }
     if (options.signal?.aborted) return Promise.reject(new DOMException("The request was aborted.", "AbortError"));
     if (this.pending.has(requestId)) return Promise.reject(new Error(`A Redweb request with id "${requestId}" is already pending.`));
     return new Promise((resolve, reject) => {
@@ -343,7 +346,7 @@ var RedwebClient = class {
         this.finishPending(requestId);
         reject(new Error(`Redweb request timed out after ${timeoutMs}ms.`));
       }, timeoutMs);
-      const pending = { resolve, reject, timer };
+      const pending = { resolve, reject, timer, responseType: options.responseType };
       if (options.signal) {
         pending.signal = options.signal;
         pending.abort = () => {
@@ -450,7 +453,7 @@ var RedwebClient = class {
     const requestId = message.requestId;
     if (typeof requestId === "string") {
       const pending = this.pending.get(requestId);
-      if (pending) {
+      if (pending && (pending.responseType === void 0 || message.type === pending.responseType || message.type === "error" && "error" in message)) {
         this.finishPending(requestId);
         if (message.type === "error" && "error" in message) pending.reject(new RedwebProtocolError(message));
         else pending.resolve(message);

package/dist/live-html.cjs

@@ -363,6 +363,9 @@ var RedwebClient = class {
     const requestId = options.requestId ?? this.createRequestId();
     const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
     assertNonNegativeInteger(timeoutMs, "timeoutMs");
+    if (options.responseType !== void 0 && (typeof options.responseType !== "string" || !options.responseType || options.responseType.length > 256)) {
+      return Promise.reject(new TypeError("responseType must be a non-empty string of at most 256 characters."));
+    }
     if (options.signal?.aborted) return Promise.reject(new DOMException("The request was aborted.", "AbortError"));
     if (this.pending.has(requestId)) return Promise.reject(new Error(`A Redweb request with id "${requestId}" is already pending.`));
     return new Promise((resolve, reject) => {
@@ -370,7 +373,7 @@ var RedwebClient = class {
         this.finishPending(requestId);
         reject(new Error(`Redweb request timed out after ${timeoutMs}ms.`));
       }, timeoutMs);
-      const pending = { resolve, reject, timer };
+      const pending = { resolve, reject, timer, responseType: options.responseType };
       if (options.signal) {
         pending.signal = options.signal;
         pending.abort = () => {
@@ -477,7 +480,7 @@ var RedwebClient = class {
     const requestId = message.requestId;
     if (typeof requestId === "string") {
       const pending = this.pending.get(requestId);
-      if (pending) {
+      if (pending && (pending.responseType === void 0 || message.type === pending.responseType || message.type === "error" && "error" in message)) {
         this.finishPending(requestId);
         if (message.type === "error" && "error" in message) pending.reject(new RedwebProtocolError(message));
         else pending.resolve(message);
@@ -768,7 +771,7 @@ var ActionFeedback = class {
 
 // src/live-html/feedback.js
 function createFeedback({ componentOf, report, stateKey, clientNodes, client, listen, active }) {
-  const bindingOf = (source) => JSON.stringify([componentOf(source), source.getAttribute("rw-submit"), source.getAttribute("rw-click")]);
+  const bindingOf = (source) => JSON.stringify([componentOf(source), source.getAttribute("rw-submit"), source.getAttribute("rw-click"), source.getAttribute("data-rw-command")]);
   const revisions = /* @__PURE__ */ new WeakMap();
   const feedbackNodes = /* @__PURE__ */ new WeakMap();
   const feedbackSources = /* @__PURE__ */ new WeakMap();
@@ -855,6 +858,13 @@ function createFeedback({ componentOf, report, stateKey, clientNodes, client, li
   };
   const performAction = (source, payload, completed) => feedback.run(source, () => {
     if (client.state !== "open") throw Object.assign(new Error("Action was not sent while disconnected."), { code: "ACTION_OFFLINE" });
+    const command = source.getAttribute("data-rw-command");
+    if (command !== null) {
+      const binding = JSON.parse(command);
+      if (typeof binding.type !== "string" || !binding.type || binding.type.startsWith("redweb:")) throw new Error("Invalid socket action binding.");
+      const input = payload.args.length ? { ...binding.payload, ...payload.args[0] } : Object.hasOwn(binding, "payload") ? binding.payload : {};
+      return client.request(binding.type, input, { responseType: "redweb:result" });
+    }
     return client.request("redweb:html", payload);
   }).then((success) => {
     if (success && active()) completed?.();

package/dist/live-html.d.cts

@@ -1,4 +1,4 @@
-import { e as RedwebClient } from './client-Dq8oKJwh.cjs';
+import { e as RedwebClient } from './client-D35g1hrL.cjs';
 
 /** One browser document's Live HTML transport and delegated event ownership. */
 interface LivePageConnection {

package/dist/live-html.d.ts

@@ -1,4 +1,4 @@
-import { e as RedwebClient } from './client-Dq8oKJwh.js';
+import { e as RedwebClient } from './client-D35g1hrL.js';
 
 /** One browser document's Live HTML transport and delegated event ownership. */
 interface LivePageConnection {

package/dist/live-html.js

@@ -336,6 +336,9 @@ var RedwebClient = class {
     const requestId = options.requestId ?? this.createRequestId();
     const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
     assertNonNegativeInteger(timeoutMs, "timeoutMs");
+    if (options.responseType !== void 0 && (typeof options.responseType !== "string" || !options.responseType || options.responseType.length > 256)) {
+      return Promise.reject(new TypeError("responseType must be a non-empty string of at most 256 characters."));
+    }
     if (options.signal?.aborted) return Promise.reject(new DOMException("The request was aborted.", "AbortError"));
     if (this.pending.has(requestId)) return Promise.reject(new Error(`A Redweb request with id "${requestId}" is already pending.`));
     return new Promise((resolve, reject) => {
@@ -343,7 +346,7 @@ var RedwebClient = class {
         this.finishPending(requestId);
         reject(new Error(`Redweb request timed out after ${timeoutMs}ms.`));
       }, timeoutMs);
-      const pending = { resolve, reject, timer };
+      const pending = { resolve, reject, timer, responseType: options.responseType };
       if (options.signal) {
         pending.signal = options.signal;
         pending.abort = () => {
@@ -450,7 +453,7 @@ var RedwebClient = class {
     const requestId = message.requestId;
     if (typeof requestId === "string") {
       const pending = this.pending.get(requestId);
-      if (pending) {
+      if (pending && (pending.responseType === void 0 || message.type === pending.responseType || message.type === "error" && "error" in message)) {
         this.finishPending(requestId);
         if (message.type === "error" && "error" in message) pending.reject(new RedwebProtocolError(message));
         else pending.resolve(message);
@@ -741,7 +744,7 @@ var ActionFeedback = class {
 
 // src/live-html/feedback.js
 function createFeedback({ componentOf, report, stateKey, clientNodes, client, listen, active }) {
-  const bindingOf = (source) => JSON.stringify([componentOf(source), source.getAttribute("rw-submit"), source.getAttribute("rw-click")]);
+  const bindingOf = (source) => JSON.stringify([componentOf(source), source.getAttribute("rw-submit"), source.getAttribute("rw-click"), source.getAttribute("data-rw-command")]);
   const revisions = /* @__PURE__ */ new WeakMap();
   const feedbackNodes = /* @__PURE__ */ new WeakMap();
   const feedbackSources = /* @__PURE__ */ new WeakMap();
@@ -828,6 +831,13 @@ function createFeedback({ componentOf, report, stateKey, clientNodes, client, li
   };
   const performAction = (source, payload, completed) => feedback.run(source, () => {
     if (client.state !== "open") throw Object.assign(new Error("Action was not sent while disconnected."), { code: "ACTION_OFFLINE" });
+    const command = source.getAttribute("data-rw-command");
+    if (command !== null) {
+      const binding = JSON.parse(command);
+      if (typeof binding.type !== "string" || !binding.type || binding.type.startsWith("redweb:")) throw new Error("Invalid socket action binding.");
+      const input = payload.args.length ? { ...binding.payload, ...payload.args[0] } : Object.hasOwn(binding, "payload") ? binding.payload : {};
+      return client.request(binding.type, input, { responseType: "redweb:result" });
+    }
     return client.request("redweb:html", payload);
   }).then((success) => {
     if (success && active()) completed?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redweb-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Browser-first WebSocket client for Redweb",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -25,10 +25,12 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,
   "scripts": {
+    "prepack": "npm run build 1>&2",
     "build": "tsup src/index.ts src/live-html.ts --format esm,cjs --dts --clean --splitting false",
     "typecheck": "tsc --noEmit",
     "test": "npm run check",