From 4b4643ba7d97ef5f922a069643e10f368d7e8597 Mon Sep 17 00:00:00 2001
From: Minggang Wang <minggangw@gmail.com>
Date: Fri, 12 Jun 2026 14:59:48 +0800
Subject: [PATCH 1/7] [Web runtime] Add SSE subscribe + CORS to HttpTransport

---
 bin/rclnodejs-web.js            |  11 +-
 demo/web/javascript/README.md   |  61 ++++++-
 demo/web/javascript/index.html  | 132 +++++++++++++-
 demo/web/javascript/runtime.mjs |  16 ++
 demo/web/typescript/README.md   |   6 +
 lib/runtime/cli-config.js       |  72 +++++++-
 lib/runtime/transports/http.js  | 302 +++++++++++++++++++++++++++++++-
 test/test-web-cli.js            |  91 ++++++++++
 8 files changed, 675 insertions(+), 16 deletions(-)

diff --git a/bin/rclnodejs-web.js b/bin/rclnodejs-web.js
index bf519b65..9b9d6789 100755
--- a/bin/rclnodejs-web.js
+++ b/bin/rclnodejs-web.js
@@ -91,6 +91,12 @@ const argv = process.argv.slice(2);
           port: cfg.http.port,
           host: cfg.http.host || cfg.host,
           basePath: cfg.http.basePath || cfg.path,
+          sse: cfg.http.sse,
+          sseKeepAliveMs:
+            cfg.http.sseKeepAliveMs != null
+              ? cfg.http.sseKeepAliveMs
+              : undefined,
+          cors: cfg.http.cors,
         })
       );
     }
@@ -118,8 +124,11 @@ const argv = process.argv.slice(2);
       if (httpTransport) {
         const httpHost = displayHost(cfg.http.host || cfg.host);
         const httpBase = cfg.http.basePath || cfg.path;
+        const httpKinds = cfg.http.sse
+          ? 'call/publish + subscribe (SSE)'
+          : 'call/publish only';
         process.stdout.write(
-          `                  also http://${httpHost}:${httpTransport.port}${httpBase} (call/publish only)\n`
+          `                  also http://${httpHost}:${httpTransport.port}${httpBase} (${httpKinds})\n`
         );
       }
     }
diff --git a/demo/web/javascript/README.md b/demo/web/javascript/README.md
index f49446e8..0d98e36f 100644
--- a/demo/web/javascript/README.md
+++ b/demo/web/javascript/README.md
@@ -17,6 +17,7 @@ source /opt/ros/<distro>/setup.bash
 node runtime.mjs
 # rclnodejs/web : ws://localhost:9000/capability
 #               also http://localhost:9001/capability  (call/publish, curl-able)
+#               also http://localhost:9001/capability/subscribe/<name>  (SSE)
 ```
 
 `runtime.mjs` exposes a tiny `/add_two_ints` service + 1 Hz
@@ -65,7 +66,60 @@ curl -sS -X POST http://localhost:9001/capability/call/add_two_ints \
 # => {"sum":"42n"}
 ```
 
-Subscribe stays on WebSocket.
+This demo's `runtime.mjs` also enables SSE (`new HttpTransport({ sse: true })`),
+so `subscribe` is reachable over HTTP as a `text/event-stream` — useful for
+clients that can't hold a WebSocket open:
+
+```bash
+curl -N http://localhost:9001/capability/subscribe/web_demo_tick
+# event: ready
+# data: {"capability":"/web_demo_tick","subId":"sse"}
+#
+# event: message
+# data: {"data":"tick 0 @ 2026-06-12T…"}
+# …one `message` event per published sample, until you ^C
+```
+
+Browser apps should still prefer the WebSocket transport for `subscribe`
+(one connection multiplexes every topic). SSE subscribe targets the
+curl / AI-agent / server-side persona.
+
+The page also has a **native `EventSource` panel** (section 6) that
+subscribes to `/web_demo_tick` over the same SSE endpoint — no SDK, no
+WebSocket, just the browser primitive over plain HTTP. Because the page
+(`:8080`) and the HTTP transport (`:9001`) are different origins, the
+demo's `runtime.mjs` enables CORS (`new HttpTransport({ sse: true, cors:
+true })`) so the cross-origin `EventSource` is allowed. In production,
+pass your site's origin instead of `true`.
+
+### Pair it with the stock publisher example
+
+The EventSource panel's topic box defaults to `/web_demo_tick`, but the
+runtime also exposes `/topic` so you can feed the demo from your own
+node instead of the built-in tick loop. In a third shell, run the
+standard publisher example:
+
+```bash
+source /opt/ros/<distro>/setup.bash
+node ../../../example/topics/publisher/publisher-example.mjs
+# Publishing message: Hello ROS 0
+# Publishing message: Hello ROS 1
+# …
+```
+
+Then set the panel's topic box to `/topic` and click **open
+EventSource** — you'll see that node's `Hello ROS N` messages stream in.
+The same works over `curl`:
+
+```bash
+curl -N http://localhost:9001/capability/subscribe/topic
+# event: message
+# data: {"data":"Hello ROS 0"}
+```
+
+This makes [`publisher-example.mjs`](../../../example/topics/publisher/publisher-example.mjs)
+and the web demo a ready-made publisher/subscriber pair for trying the
+web runtime against your own publishers.
 
 ## Without the bundled `runtime.mjs`
 
@@ -86,3 +140,8 @@ npx -p rclnodejs rclnodejs-web web.json
 ros2 run demo_nodes_cpp add_two_ints_server
 # (and a publisher of std_msgs/String on /web_demo_tick from any source)
 ```
+
+> Note: this demo enables the SSE subscribe endpoint programmatically in
+> `runtime.mjs` via `new HttpTransport({ sse: true, cors: true })`. The
+> `rclnodejs-web` CLI can do the same with `--http-sse` and `--http-cors`
+> (or `"http": { "sse": true, "cors": "*" }` in `web.json`).
diff --git a/demo/web/javascript/index.html b/demo/web/javascript/index.html
index bf5c2f37..83bae264 100644
--- a/demo/web/javascript/index.html
+++ b/demo/web/javascript/index.html
@@ -273,8 +273,12 @@ <h2>5. Same capability, no SDK — just <code>curl</code></h2>
       The HTTP transport is what makes <code>rclnodejs/web</code>
       <em>actually</em> web-native: every <code>call</code> and
       <code>publish</code> in your allow-list is reachable from any HTTP client
-      — curl, Postman, an AI agent… no JavaScript required. Subscribe stays on
-      WebSocket.
+      — curl, Postman, an AI agent… no JavaScript required. With
+      <code>sse: true</code> on the runtime (set in this demo's
+      <code>runtime.mjs</code>), <code>subscribe</code> is also reachable as a
+      Server-Sent Events stream — handy for clients that can't hold a
+      WebSocket open. Browser apps still prefer the WebSocket transport, which
+      multiplexes many topics on one connection.
     </p>
     <pre
       class="code"
@@ -289,11 +293,79 @@ <h2>5. Same capability, no SDK — just <code>curl</code></h2>
   -H <span class="str">'content-type: application/json'</span> \
   -d <span class="str">'{"data":"hi from curl"}'</span>
 
+<span class="com"># subscribe over SSE — streams text/event-stream until you ^C</span>
+<span class="com"># (-N disables curl's buffering so events print as they arrive)</span>
+curl -N http://localhost:9001/capability/subscribe/web_demo_tick
+<span class="com"># event: ready</span>
+<span class="com"># data: {"capability":"/web_demo_tick","subId":"sse"}</span>
+<span class="com">#</span>
+<span class="com"># event: message</span>
+<span class="com"># data: {"data":"tick 0 @ 2026-06-12T…"}</span>
+<span class="com"># …one `message` event per published sample…</span>
+
 <span class="com"># allow-list rejection — returns 404 + structured error body</span>
 curl -sS -X POST http://localhost:9001/capability/call/dangerous \
   -H <span class="str">'content-type: application/json'</span> -d <span class="str">'{}'</span>
 <span class="com"># =&gt; {"ok":false,"error":"capability not exposed: call /dangerous","code":"not_exposed"}</span></pre>
 
+    <h2>
+      6. Native <code>EventSource</code> — SSE subscribe over HTTP
+      <span class="badge">no SDK</span>
+    </h2>
+    <p style="font-size: 0.9em; color: #555">
+      The same SSE stream the <code>curl</code> example above reads is a
+      first-class browser API: <code>EventSource</code>. No SDK, no WebSocket —
+      just a plain HTTP GET the browser keeps open and auto-reconnects. This
+      works cross-origin because the runtime sends CORS headers
+      (<code>new HttpTransport({ sse: true, cors: true })</code>). For
+      multiplexing many topics on one connection, the WebSocket transport in
+      section 2 is still the better fit.
+    </p>
+    <p style="font-size: 0.9em; color: #555">
+      The topic box defaults to <code>/web_demo_tick</code> (the demo's
+      built-in tick loop). It is also wired to <code>/topic</code> so you can
+      feed the demo from the stock publisher example instead — run
+      <code
+        >node ../../../example/topics/publisher/publisher-example.mjs</code
+      >
+      in another shell, set the box to <code>/topic</code>, and watch your own
+      node's messages stream in.
+    </p>
+    <div class="panel">
+      <div class="controls">
+        <div class="row">
+          <input
+            id="sseTopic"
+            type="text"
+            value="/web_demo_tick"
+            spellcheck="false"
+            aria-label="topic to subscribe to"
+          />
+          <button id="sseBtn">open EventSource</button>
+          <button id="sseCloseBtn" disabled>close</button>
+        </div>
+        <div class="log" id="sseLog"></div>
+      </div>
+      <pre
+        class="code"
+      ><span class="com">// No import — EventSource is built into every browser.</span>
+<span class="com">// Swap the topic for '/topic' to pair with publisher-example.mjs.</span>
+<span class="kw">const</span> es = <span class="kw">new</span> EventSource(
+  <span class="str">'http://localhost:9001/capability/subscribe/web_demo_tick'</span>,
+);
+
+es.addEventListener(<span class="str">'ready'</span>, (e) =&gt;
+  console.log(<span class="str">'subscribed:'</span>, JSON.parse(e.data)),
+);
+es.addEventListener(<span class="str">'message'</span>, (e) =&gt; {
+  <span class="kw">const</span> msg = JSON.parse(e.data);
+  console.log(<span class="str">'recv:'</span>, msg.data);
+});
+
+<span class="com">// later — stop receiving:</span>
+es.close();</pre>
+    </div>
+
     <script type="module">
       import { connect } from '/sdk/index.js';
 
@@ -444,6 +516,62 @@ <h2>5. Same capability, no SDK — just <code>curl</code></h2>
           }
         };
 
+        // Native EventSource — independent of the WS/HTTP transport
+        // toggle above. It always talks to the HTTP transport's SSE
+        // endpoint directly, which is exactly the point: no SDK, no
+        // WebSocket, just a browser primitive over plain HTTP (CORS is
+        // enabled on the runtime so this works cross-origin).
+        const sseBtn = document.getElementById('sseBtn');
+        const sseCloseBtn = document.getElementById('sseCloseBtn');
+        const sseTopic = document.getElementById('sseTopic');
+        let es;
+        const closeEs = () => {
+          if (es) {
+            es.close();
+            es = null;
+          }
+          sseBtn.disabled = false;
+          sseCloseBtn.disabled = true;
+          sseTopic.disabled = false;
+        };
+        sseBtn.onclick = () => {
+          closeEs();
+          // Accept '/topic' or 'topic'; the URL path carries the bare name.
+          const name = (sseTopic.value || '/web_demo_tick')
+            .trim()
+            .replace(/^\//, '');
+          const url = `${ENDPOINTS.http}/capability/subscribe/${encodeURIComponent(
+            name
+          )}`;
+          es = new EventSource(url);
+          sseBtn.disabled = true;
+          sseCloseBtn.disabled = false;
+          sseTopic.disabled = true;
+          log('sseLog', `EventSource → ${url}`, 'ok');
+          es.addEventListener('ready', (e) => {
+            const info = JSON.parse(e.data);
+            log('sseLog', `ready (subId=${info.subId})`, 'ok');
+          });
+          es.addEventListener('message', (e) => {
+            log('sseLog', JSON.parse(e.data).data);
+          });
+          es.addEventListener('error', (e) => {
+            // SSE `error` events carry no payload for transport drops;
+            // our runtime only sends a data-bearing `error` event for a
+            // terminal failure (e.g. capability removed).
+            if (e.data) {
+              const err = JSON.parse(e.data);
+              log('sseLog', `error: ${err.error} (${err.code})`, 'err');
+            } else if (es && es.readyState === EventSource.CONNECTING) {
+              log('sseLog', 'connection lost — auto-reconnecting…', 'err');
+            }
+          });
+        };
+        sseCloseBtn.onclick = () => {
+          closeEs();
+          log('sseLog', 'closed', 'ok');
+        };
+
         for (const radio of document.querySelectorAll(
           'input[name="transport"]'
         )) {
diff --git a/demo/web/javascript/runtime.mjs b/demo/web/javascript/runtime.mjs
index 27c5e378..943eb85e 100644
--- a/demo/web/javascript/runtime.mjs
+++ b/demo/web/javascript/runtime.mjs
@@ -101,6 +101,14 @@ const runtime = createRuntime({
     new HttpTransport({
       port: HTTP_PORT,
       host: '::',
+      // Opt-in Server-Sent Events for `subscribe` over plain HTTP:
+      //   GET /capability/subscribe/<name>   (text/event-stream)
+      // Intended for clients that can't hold a WebSocket open (curl,
+      // AI agents, serverless / edge functions). Browser apps should
+      // still prefer the WebSocket transport, which multiplexes many
+      // topics on one connection. Off by default in HttpTransport.
+      sse: true,
+      cors: true,
     }),
   ],
 });
@@ -110,6 +118,11 @@ runtime.expose({
   subscribe: {
     '/web_demo_tick': 'std_msgs/msg/String',
     '/web_demo_chatter': 'std_msgs/msg/String',
+    // Pairs with the stock publisher example so developers can feed the
+    // demo from their own node instead of the built-in tick loop:
+    //   node ../../../example/topics/publisher/publisher-example.mjs
+    // then subscribe to `/topic` from the browser / curl / EventSource.
+    '/topic': 'std_msgs/msg/String',
   },
 });
 await runtime.start();
@@ -127,6 +140,9 @@ console.log(
 console.log(
   `  HTTP      : http://${displayHost('::')}:${HTTP_PORT}/capability  (call / publish, curl-able)`
 );
+console.log(
+  `  HTTP SSE  : http://${displayHost('::')}:${HTTP_PORT}/capability/subscribe/<name>  (subscribe via text/event-stream)`
+);
 console.log();
 console.log(`Exposed capabilities (${total}):`);
 console.log(formatCapabilities(caps));
diff --git a/demo/web/typescript/README.md b/demo/web/typescript/README.md
index a10ae538..7f714cd9 100644
--- a/demo/web/typescript/README.md
+++ b/demo/web/typescript/README.md
@@ -29,6 +29,12 @@ npm run server
 `server.ts` runs the runtime *and* a tiny `/add_two_ints` service +
 1 Hz `/web_demo_tick` publisher so every panel has live data.
 
+> The HTTP transport here serves `call` / `publish` only; `subscribe`
+> uses WebSocket. HTTP `subscribe` over Server-Sent Events is an opt-in
+> (`new HttpTransport({ sse: true })`, or `--http-sse` on the CLI) — see
+> the [JavaScript demo](../javascript/README.md) for a working SSE +
+> `EventSource` example.
+
 **Shell 2 — Vite dev server:**
 
 ```bash
diff --git a/lib/runtime/cli-config.js b/lib/runtime/cli-config.js
index 49ea6e96..03a0356c 100644
--- a/lib/runtime/cli-config.js
+++ b/lib/runtime/cli-config.js
@@ -26,8 +26,17 @@ const DEFAULTS = Object.freeze({
   // Optional HTTP transport for `call`/`publish`. Disabled by default;
   // set `port` (or pass `--http-port` on the CLI) to turn it on.
   // `host` defaults to the same dual-stack address as the WS listener.
-  // `basePath` defaults to `/capability`.
-  http: { port: null, host: null, basePath: null },
+  // `basePath` defaults to `/capability`. `sse` opts `subscribe` into a
+  // Server-Sent Events stream; `cors` controls cross-origin access
+  // (`false` = none, `true` = any origin, string/array = allow-list).
+  http: {
+    port: null,
+    host: null,
+    basePath: null,
+    sse: false,
+    sseKeepAliveMs: null,
+    cors: false,
+  },
   expose: { call: {}, publish: {}, subscribe: {} },
 });
 
@@ -81,6 +90,22 @@ function parseArgv(argv) {
       partial.http.host = eat(a);
     } else if (a === '--http-base-path') {
       partial.http.basePath = eat(a);
+    } else if (a === '--http-sse') {
+      partial.http.sse = true;
+      i++;
+    } else if (a === '--http-sse-keep-alive') {
+      partial.http.sseKeepAliveMs = Number(eat(a));
+    } else if (a === '--http-cors') {
+      // Repeatable. `*` (or `true`) means any origin; otherwise each
+      // value is added to an allow-list. Once any origin is `*`, the
+      // policy stays "any".
+      const v = eat(a);
+      if (v === '*' || v === 'true') {
+        partial.http.cors = true;
+      } else if (partial.http.cors !== true) {
+        if (!Array.isArray(partial.http.cors)) partial.http.cors = [];
+        partial.http.cors.push(v);
+      }
     } else if (a === '--call' || a === '--publish' || a === '--subscribe') {
       const kind = a.slice(2);
       const pair = eat(a);
@@ -181,6 +206,28 @@ function validateConfig(cfg, origin = 'config') {
     ) {
       throw new CliError(`${origin}: "http.basePath" must be a string`);
     }
+    if (cfg.http.sse !== undefined && typeof cfg.http.sse !== 'boolean') {
+      throw new CliError(`${origin}: "http.sse" must be a boolean`);
+    }
+    if (
+      cfg.http.sseKeepAliveMs !== undefined &&
+      cfg.http.sseKeepAliveMs !== null &&
+      !Number.isFinite(cfg.http.sseKeepAliveMs)
+    ) {
+      throw new CliError(`${origin}: "http.sseKeepAliveMs" must be a number`);
+    }
+    if (cfg.http.cors !== undefined && cfg.http.cors !== null) {
+      const c = cfg.http.cors;
+      const ok =
+        typeof c === 'boolean' ||
+        typeof c === 'string' ||
+        (Array.isArray(c) && c.every((v) => typeof v === 'string'));
+      if (!ok) {
+        throw new CliError(
+          `${origin}: "http.cors" must be a boolean, string, or string[]`
+        );
+      }
+    }
   }
   if (cfg.expose !== undefined) {
     if (
@@ -241,7 +288,14 @@ function mergeConfig(...sources) {
       if (src[k] !== undefined) out[k] = src[k];
     }
     if (src.http) {
-      for (const k of ['port', 'host', 'basePath']) {
+      for (const k of [
+        'port',
+        'host',
+        'basePath',
+        'sse',
+        'sseKeepAliveMs',
+        'cors',
+      ]) {
         if (src.http[k] !== undefined && src.http[k] !== null) {
           out.http[k] = src.http[k];
         }
@@ -279,10 +333,14 @@ WebSocket transport (always on):
       --host <addr>           WS bind host             (default ::, dual-stack)
       --path <url>            WS URL path              (default /capability)
 
-HTTP transport (opt-in; for call/publish only):
+HTTP transport (opt-in; for call/publish, and subscribe via SSE):
       --http-port <n>         HTTP listen port         (disabled if omitted)
       --http-host <addr>      HTTP bind host           (default same as --host)
       --http-base-path <p>    HTTP base path           (default /capability)
+      --http-sse              enable GET subscribe over Server-Sent Events
+      --http-sse-keep-alive <ms>  SSE heartbeat interval   (default 15000, 0 off)
+      --http-cors <origin>    allow cross-origin requests; '*' = any origin,
+                              or repeat the flag to build an allow-list
 
 Capabilities:
       --call <name>=<type>    expose a service capability   (repeatable)
@@ -304,13 +362,17 @@ Examples:
   rclnodejs-web --port 9000 --http-port 9001 \\
     --call /add_two_ints=example_interfaces/srv/AddTwoInts
 
+  # Add SSE subscribe + CORS so a browser EventSource can connect:
+  rclnodejs-web --port 9000 --http-port 9001 --http-sse --http-cors '*' \\
+    --subscribe /scan=sensor_msgs/msg/LaserScan
+
   # Or all from a JSON config:
   rclnodejs-web web.json
 
 Config-file shape (every field optional):
   {
     "port": 9000, "host": "::", "path": "/capability",
-    "http": { "port": 9001 },
+    "http": { "port": 9001, "sse": true, "cors": "*" },
     "expose": {
       "call":      { "/add_two_ints": "example_interfaces/srv/AddTwoInts" },
       "publish":   { "/cmd_vel":      "geometry_msgs/msg/Twist" },
diff --git a/lib/runtime/transports/http.js b/lib/runtime/transports/http.js
index 2ceae46c..4062553f 100644
--- a/lib/runtime/transports/http.js
+++ b/lib/runtime/transports/http.js
@@ -173,6 +173,184 @@ class HttpRequestConnection extends Connection {
   }
 }
 
+/**
+ * A long-lived {@link Connection} that streams a single subscription over
+ * Server-Sent Events (`text/event-stream`).
+ *
+ * Unlike {@link HttpRequestConnection} (one request → one reply), this
+ * connection stays open: it drives the dispatcher with exactly one
+ * `subscribe` frame and then relays every `{event:'message'}` delivery to
+ * the client as an SSE `message` event until the client disconnects.
+ *
+ * The dispatcher is unchanged — it sees the same `subscribe` frame and the
+ * same `{event:'message', subId, payload}` deliveries it would send over
+ * WebSocket. This class only reframes them as SSE lines.
+ *
+ * HTTP status semantics are preserved for the *establishment* of the
+ * stream: the `200 text/event-stream` headers are not written until the
+ * dispatcher acknowledges the subscribe (`{ok:true}`). If the subscribe is
+ * rejected (e.g. `not_exposed`), the headers have not been sent yet, so the
+ * failure surfaces as a normal JSON error response with the mapped status
+ * code — exactly like `call`/`publish`.
+ */
+class HttpSseConnection extends Connection {
+  /**
+   * @param {import('http').IncomingMessage} req
+   * @param {import('http').ServerResponse} res
+   * @param {string} capability  ROS name to subscribe to.
+   * @param {object} [options]
+   * @param {number} [options.keepAliveMs=15000]  Heartbeat comment interval.
+   */
+  constructor(req, res, capability, options = {}) {
+    super();
+    this.req = req;
+    this.res = res;
+    this._capability = capability;
+    this._keepAliveMs =
+      options.keepAliveMs != null ? options.keepAliveMs : 15000;
+    this._streaming = false;
+    this._closed = false;
+    this._keepAlive = null;
+    // Fixed subId: an SSE connection carries exactly one subscription.
+    this._subId = 'sse';
+
+    const onClose = () => this._emitCloseOnce();
+    req.on('close', onClose);
+    res.on('close', onClose);
+    res.on('error', (e) => {
+      debug('sse response error: %s', e.message);
+      this._emitCloseOnce();
+    });
+  }
+
+  /**
+   * Kick off dispatch: emit a single `subscribe` frame. The dispatcher
+   * replies synchronously with `{ok:true}` (→ start the stream) or an
+   * error (→ JSON failure response).
+   */
+  begin() {
+    this.emit('message', {
+      id: this._subId,
+      kind: 'subscribe',
+      capability: this._capability,
+    });
+  }
+
+  send(frame) {
+    if (this._closed) return;
+
+    // Subscription delivery — the steady-state case.
+    if (frame.event === 'message') {
+      this._ensureStream();
+      this._writeEvent('message', frame.payload);
+      return;
+    }
+
+    // Subscribe acknowledgement: switch the response into an event stream.
+    if (frame.ok === true) {
+      this._ensureStream();
+      this._writeEvent('ready', {
+        capability: this._capability,
+        subId: this._subId,
+      });
+      return;
+    }
+
+    // Failure path.
+    const code = frame.code || 'internal_error';
+    if (!this._streaming) {
+      // Headers not sent yet — surface as a normal HTTP error.
+      const status = _STATUS_BY_CODE[code] || 500;
+      this._writeError(status, code, frame.error || 'subscribe failed');
+    } else {
+      // Already streaming — emit a terminal SSE error event, then close.
+      this._writeEvent('error', { error: frame.error, code });
+    }
+    this._emitCloseOnce();
+  }
+
+  /** Close the stream; the dispatcher's `cleanup` follows via `'close'`. */
+  // eslint-disable-next-line no-unused-vars
+  close(code, reason) {
+    this._emitCloseOnce();
+  }
+
+  _ensureStream() {
+    if (this._streaming) return;
+    this._streaming = true;
+    this.res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-cache, no-transform',
+      connection: 'keep-alive',
+      // Disable proxy buffering (nginx) so events flush immediately.
+      'x-accel-buffering': 'no',
+    });
+    if (typeof this.res.flushHeaders === 'function') {
+      this.res.flushHeaders();
+    }
+    if (this._keepAliveMs > 0) {
+      this._keepAlive = setInterval(() => {
+        if (this._closed) return;
+        try {
+          this.res.write(': keep-alive\n\n');
+        } catch (e) {
+          debug('sse keep-alive write failed: %s', e.message);
+          this._emitCloseOnce();
+        }
+      }, this._keepAliveMs);
+      // Don't let the heartbeat keep the event loop alive on its own.
+      if (typeof this._keepAlive.unref === 'function') {
+        this._keepAlive.unref();
+      }
+    }
+  }
+
+  _writeEvent(event, data) {
+    if (this._closed) return;
+    const json = JSON.stringify(data ?? null);
+    // Each newline in the payload must become its own `data:` line.
+    let chunk = `event: ${event}\n`;
+    for (const line of json.split('\n')) {
+      chunk += `data: ${line}\n`;
+    }
+    chunk += '\n';
+    try {
+      this.res.write(chunk);
+    } catch (e) {
+      debug('sse write failed: %s', e.message);
+      this._emitCloseOnce();
+    }
+  }
+
+  _writeError(status, code, message) {
+    const body = JSON.stringify({ ok: false, error: message, code });
+    try {
+      this.res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(body),
+      });
+      this.res.end(body);
+    } catch (e) {
+      debug('sse writeError failed: %s', e.message);
+    }
+  }
+
+  _emitCloseOnce() {
+    if (this._closed) return;
+    this._closed = true;
+    if (this._keepAlive) {
+      clearInterval(this._keepAlive);
+      this._keepAlive = null;
+    }
+    try {
+      this.res.end();
+    } catch {
+      /* response may already be finished */
+    }
+    this.emit('close');
+  }
+}
+
 /**
  * HTTP adapter for the Web Runtime.
  *
@@ -181,18 +359,24 @@ class HttpRequestConnection extends Connection {
  *     POST /capability/call/<name>
  *     POST /capability/publish/<name>
  *
- * Subscriptions stay on the WebSocket transport (one HTTP connection
- * per inbound message would burn the browser's per-origin budget).
- * Anything that isn't `POST /capability/call/<name>` or
- * `POST /capability/publish/<name>` returns a 404 / 405 — the adapter
- * does not serve unrelated routes.
+ * When `sse: true`, it additionally exposes `subscribe` as a Server-Sent
+ * Events stream:
+ *
+ *     GET /capability/subscribe/<name>     (text/event-stream)
+ *
+ * SSE subscribe is opt-in and intended for clients that cannot hold a
+ * WebSocket open (curl, AI agents, serverless/edge functions). Browser
+ * apps should keep using the WebSocket transport for `subscribe`, which
+ * multiplexes many topics on one connection. Anything that isn't a
+ * recognised route returns a 404 / 405 — the adapter does not serve
+ * unrelated paths.
  *
  * @example
  *   const runtime = createRuntime({
  *     node,
  *     transports: [
  *       new WebSocketTransport({ port: 9000 }),
- *       new HttpTransport({ port: 9001 }),
+ *       new HttpTransport({ port: 9001, sse: true }),
  *     ],
  *   });
  */
@@ -202,6 +386,20 @@ class HttpTransport extends TransportAdapter {
    * @param {number} [options.port=9001]
    * @param {string} [options.host='::']
    * @param {string} [options.basePath='/capability']
+   * @param {boolean} [options.sse=false]
+   *   Enable `GET /capability/subscribe/<name>` Server-Sent Events
+   *   streaming. Off by default; `subscribe` returns `unsupported_kind`
+   *   unless this is set.
+   * @param {number} [options.sseKeepAliveMs=15000]
+   *   Heartbeat comment interval for SSE streams, in milliseconds. Set to
+   *   `0` to disable heartbeats.
+   * @param {boolean|string|string[]} [options.cors=false]
+   *   Cross-Origin Resource Sharing policy. `false` (default) sends no
+   *   CORS headers. `true` allows any origin (`Access-Control-Allow-Origin:
+   *   *`). A string or array of strings allows only those origins (the
+   *   request's `Origin` is echoed back when it matches). Required for a
+   *   browser on a different origin to `fetch()` / `EventSource()` this
+   *   transport.
    * @param {(req: import('http').IncomingMessage) => boolean} [options.verifyRequest]
    *   Optional auth hook called with the raw request. Return `false` to
    *   reject the request with 401. Mirrors `WebSocketTransport.verifyClient`.
@@ -211,6 +409,10 @@ class HttpTransport extends TransportAdapter {
     this.port = options.port != null ? options.port : 9001;
     this.host = options.host != null ? options.host : '::';
     this.basePath = _normaliseBasePath(options.basePath);
+    this.sse = options.sse === true;
+    this.sseKeepAliveMs =
+      options.sseKeepAliveMs != null ? options.sseKeepAliveMs : 15000;
+    this.cors = _normaliseCors(options.cors);
     this.verifyRequest = options.verifyRequest;
     this._server = null;
     this._onConnection = null;
@@ -259,6 +461,18 @@ class HttpTransport extends TransportAdapter {
   // ---------- internals ----------
 
   _route(req, res) {
+    // Apply CORS headers (if configured) before anything else, so they
+    // appear on every response — JSON replies, 204s, SSE streams, and
+    // errors alike. setHeader persists through later writeHead() calls.
+    this._applyCors(req, res);
+
+    // Preflight: browsers send OPTIONS before a cross-origin POST with a
+    // JSON content-type. Answer it directly (no auth, no body).
+    if (req.method === 'OPTIONS' && this.cors) {
+      res.writeHead(204).end();
+      return;
+    }
+
     if (this.verifyRequest) {
       let allowed;
       try {
@@ -322,10 +536,40 @@ class HttpTransport extends TransportAdapter {
       });
     }
 
+    if (kind === 'subscribe') {
+      if (!this.sse) {
+        return _writeJson(res, 404, {
+          ok: false,
+          error:
+            'subscribe over HTTP is disabled (enable `sse` or use WebSocket)',
+          code: 'unsupported_kind',
+        });
+      }
+      if (req.method !== 'GET') {
+        res.setHeader('allow', 'GET');
+        return _writeJson(res, 405, {
+          ok: false,
+          error: `method not allowed: ${req.method} (use GET for SSE subscribe)`,
+          code: 'method_not_allowed',
+        });
+      }
+      const conn = new HttpSseConnection(req, res, name, {
+        keepAliveMs: this.sseKeepAliveMs,
+      });
+      try {
+        this._onConnection(conn);
+        conn.begin();
+      } catch (e) {
+        debug('onConnection threw: %s', e.stack || e.message);
+        conn.close();
+      }
+      return;
+    }
+
     if (kind !== 'call' && kind !== 'publish') {
       return _writeJson(res, 404, {
         ok: false,
-        error: `unsupported kind over HTTP: ${kind} (use WebSocket for subscribe/action)`,
+        error: `unsupported kind over HTTP: ${kind} (use WebSocket for action)`,
         code: 'unsupported_kind',
       });
     }
@@ -355,6 +599,29 @@ class HttpTransport extends TransportAdapter {
       }
     });
   }
+
+  /**
+   * Set CORS response headers per the configured policy. No-op when
+   * `cors` is disabled. For an allow-list, the request `Origin` is echoed
+   * only when it matches (and `Vary: Origin` is set so caches don't mix
+   * responses across origins).
+   */
+  _applyCors(req, res) {
+    if (!this.cors) return;
+    const allow = this.cors; // true → any; otherwise a Set of origins
+    if (allow === true) {
+      res.setHeader('access-control-allow-origin', '*');
+    } else {
+      const origin = req.headers.origin;
+      res.setHeader('vary', 'Origin');
+      if (origin && allow.has(origin)) {
+        res.setHeader('access-control-allow-origin', origin);
+      }
+    }
+    res.setHeader('access-control-allow-methods', 'GET, POST, OPTIONS');
+    res.setHeader('access-control-allow-headers', 'content-type');
+    res.setHeader('access-control-max-age', '86400');
+  }
 }
 
 function _writeJson(res, status, body) {
@@ -447,4 +714,25 @@ function _normaliseBasePath(value) {
   return p;
 }
 
+/**
+ * Normalise the `cors` option into either `false`, `true` (any origin),
+ * or a `Set<string>` of allowed origins.
+ */
+function _normaliseCors(value) {
+  if (value === undefined || value === null || value === false) return false;
+  if (value === true) return true;
+  if (typeof value === 'string') return new Set([value]);
+  if (Array.isArray(value)) {
+    if (!value.every((v) => typeof v === 'string')) {
+      throw new TypeError(
+        'HttpTransport: cors array must contain only origin strings'
+      );
+    }
+    return new Set(value);
+  }
+  throw new TypeError(
+    `HttpTransport: cors must be a boolean, string, or string[], got ${typeof value}`
+  );
+}
+
 export { HttpTransport };
diff --git a/test/test-web-cli.js b/test/test-web-cli.js
index 15efcdc1..f884d918 100644
--- a/test/test-web-cli.js
+++ b/test/test-web-cli.js
@@ -141,6 +141,46 @@ describe('rclnodejs-web CLI', function () {
       assert.strictEqual(partial.http.host, '127.0.0.1');
       assert.strictEqual(partial.http.basePath, '/cap');
     });
+
+    it('parses --http-sse / --http-sse-keep-alive', function () {
+      const { partial } = parseArgv([
+        '--http-sse',
+        '--http-sse-keep-alive',
+        '30000',
+      ]);
+      assert.strictEqual(partial.http.sse, true);
+      assert.strictEqual(partial.http.sseKeepAliveMs, 30000);
+    });
+
+    it('parses --http-cors * as "any origin"', function () {
+      const { partial } = parseArgv(['--http-cors', '*']);
+      assert.strictEqual(partial.http.cors, true);
+    });
+
+    it('accumulates repeated --http-cors into an allow-list', function () {
+      const { partial } = parseArgv([
+        '--http-cors',
+        'https://a.example',
+        '--http-cors',
+        'https://b.example',
+      ]);
+      assert.deepStrictEqual(partial.http.cors, [
+        'https://a.example',
+        'https://b.example',
+      ]);
+    });
+
+    it('--http-cors * wins over specific origins regardless of order', function () {
+      const { partial } = parseArgv([
+        '--http-cors',
+        'https://a.example',
+        '--http-cors',
+        '*',
+        '--http-cors',
+        'https://b.example',
+      ]);
+      assert.strictEqual(partial.http.cors, true);
+    });
   });
 
   describe('config file loading + validation', function () {
@@ -209,6 +249,42 @@ describe('rclnodejs-web CLI', function () {
       );
     });
 
+    it('accepts http.sse / http.sseKeepAliveMs / http.cors', function () {
+      assert.doesNotThrow(() =>
+        validateConfig({
+          http: { port: 9001, sse: true, sseKeepAliveMs: 0, cors: '*' },
+        })
+      );
+      assert.doesNotThrow(() =>
+        validateConfig({ http: { cors: ['https://a.example'] } })
+      );
+    });
+
+    it('rejects non-boolean http.sse', function () {
+      assert.throws(
+        () => validateConfig({ http: { sse: 'yes' } }),
+        (e) => e instanceof CliError && /http\.sse/.test(e.message)
+      );
+    });
+
+    it('rejects non-number http.sseKeepAliveMs', function () {
+      assert.throws(
+        () => validateConfig({ http: { sseKeepAliveMs: 'soon' } }),
+        (e) => e instanceof CliError && /http\.sseKeepAliveMs/.test(e.message)
+      );
+    });
+
+    it('rejects http.cors of the wrong shape', function () {
+      assert.throws(
+        () => validateConfig({ http: { cors: 42 } }),
+        (e) => e instanceof CliError && /http\.cors/.test(e.message)
+      );
+      assert.throws(
+        () => validateConfig({ http: { cors: [1, 2] } }),
+        (e) => e instanceof CliError && /http\.cors/.test(e.message)
+      );
+    });
+
     it('rejects http with non-number port', function () {
       assert.throws(
         () => validateConfig({ http: { port: 'nine' } }),
@@ -267,6 +343,21 @@ describe('rclnodejs-web CLI', function () {
       const merged = mergeConfig({}, {});
       assert.strictEqual(merged.http.port, null);
     });
+
+    it('http: sse/cors default off, and merge from either source', function () {
+      const base = mergeConfig({}, {});
+      assert.strictEqual(base.http.sse, false);
+      assert.strictEqual(base.http.cors, false);
+      assert.strictEqual(base.http.sseKeepAliveMs, null);
+
+      const merged = mergeConfig(
+        { http: { port: 9001, sse: true, cors: '*' } },
+        { http: { sseKeepAliveMs: 5000 } }
+      );
+      assert.strictEqual(merged.http.sse, true);
+      assert.strictEqual(merged.http.cors, '*');
+      assert.strictEqual(merged.http.sseKeepAliveMs, 5000);
+    });
   });
 
   describe('end-to-end CLI launch', function () {

From fd521af53706cf166bc4368d1e73d76789e45608 Mon Sep 17 00:00:00 2001
From: Minggang Wang <minggangw@gmail.com>
Date: Fri, 12 Jun 2026 15:43:54 +0800
Subject: [PATCH 2/7] Address comments

---
 lib/runtime/index.d.ts         |  3 ++
 lib/runtime/transports/http.js | 50 +++++++++++++++++++---------------
 2 files changed, 31 insertions(+), 22 deletions(-)

diff --git a/lib/runtime/index.d.ts b/lib/runtime/index.d.ts
index bc3c9ea7..85bfbb53 100644
--- a/lib/runtime/index.d.ts
+++ b/lib/runtime/index.d.ts
@@ -108,6 +108,9 @@ export interface HttpTransportOptions {
   port?: number;
   host?: string;
   basePath?: string;
+  sse?: boolean;
+  sseKeepAliveMs?: number;
+  cors?: boolean | string | string[];
   verifyRequest?: (req: import('http').IncomingMessage) => boolean;
 }
 
diff --git a/lib/runtime/transports/http.js b/lib/runtime/transports/http.js
index 4062553f..561d0f32 100644
--- a/lib/runtime/transports/http.js
+++ b/lib/runtime/transports/http.js
@@ -466,8 +466,28 @@ class HttpTransport extends TransportAdapter {
     // errors alike. setHeader persists through later writeHead() calls.
     this._applyCors(req, res);
 
+    let pathname;
+    try {
+      pathname = new URL(req.url || '/', 'http://localhost').pathname;
+    } catch {
+      return _writeJson(res, 400, {
+        ok: false,
+        error: 'invalid request URL',
+        code: 'invalid_url',
+      });
+    }
+
+    if (!pathname.startsWith(this.basePath + '/')) {
+      return _writeJson(res, 404, {
+        ok: false,
+        error: `not a capability route: ${pathname}`,
+        code: 'not_found',
+      });
+    }
+
     // Preflight: browsers send OPTIONS before a cross-origin POST with a
-    // JSON content-type. Answer it directly (no auth, no body).
+    // JSON content-type. Answer it directly (no auth, no body) — but only
+    // for capability routes, so unrelated paths still 404 above.
     if (req.method === 'OPTIONS' && this.cors) {
       res.writeHead(204).end();
       return;
@@ -494,25 +514,6 @@ class HttpTransport extends TransportAdapter {
       }
     }
 
-    let pathname;
-    try {
-      pathname = new URL(req.url || '/', 'http://localhost').pathname;
-    } catch {
-      return _writeJson(res, 400, {
-        ok: false,
-        error: 'invalid request URL',
-        code: 'invalid_url',
-      });
-    }
-
-    if (!pathname.startsWith(this.basePath + '/')) {
-      return _writeJson(res, 404, {
-        ok: false,
-        error: `not a capability route: ${pathname}`,
-        code: 'not_found',
-      });
-    }
-
     const tail = pathname.slice(this.basePath.length + 1); // strip basePath + '/'
     // tail = "<kind>/<rest...>"; first segment is the kind, rest is the
     // ROS name (which itself can contain slashes).
@@ -716,18 +717,23 @@ function _normaliseBasePath(value) {
 
 /**
  * Normalise the `cors` option into either `false`, `true` (any origin),
- * or a `Set<string>` of allowed origins.
+ * or a `Set<string>` of allowed origins. A `"*"` value (or an array that
+ * contains `"*"`) means "any origin" and is treated as `true`, matching
+ * the CLI's `--http-cors *` shorthand.
  */
 function _normaliseCors(value) {
   if (value === undefined || value === null || value === false) return false;
   if (value === true) return true;
-  if (typeof value === 'string') return new Set([value]);
+  if (typeof value === 'string') {
+    return value === '*' ? true : new Set([value]);
+  }
   if (Array.isArray(value)) {
     if (!value.every((v) => typeof v === 'string')) {
       throw new TypeError(
         'HttpTransport: cors array must contain only origin strings'
       );
     }
+    if (value.includes('*')) return true;
     return new Set(value);
   }
   throw new TypeError(

From 3d32d80b3869bb95441574ecf52242b71c86fe24 Mon Sep 17 00:00:00 2001
From: Minggang Wang <minggangw@gmail.com>
Date: Fri, 12 Jun 2026 16:25:31 +0800
Subject: [PATCH 3/7] Address comments

---
 demo/web/javascript/README.md   | 36 ++++++++++++++++-----------------
 demo/web/javascript/index.html  | 36 ++++++++++++++++-----------------
 demo/web/javascript/runtime.mjs | 19 +++++------------
 demo/web/javascript/web.json    |  4 ++--
 4 files changed, 42 insertions(+), 53 deletions(-)

diff --git a/demo/web/javascript/README.md b/demo/web/javascript/README.md
index 0d98e36f..77c33646 100644
--- a/demo/web/javascript/README.md
+++ b/demo/web/javascript/README.md
@@ -20,8 +20,9 @@ node runtime.mjs
 #               also http://localhost:9001/capability/subscribe/<name>  (SSE)
 ```
 
-`runtime.mjs` exposes a tiny `/add_two_ints` service + 1 Hz
-`/web_demo_tick` publisher so every panel has live data.
+`runtime.mjs` exposes a tiny `/add_two_ints` service and the shared
+`/web_demo_chatter` talker/listener topic (publish from one panel,
+receive in the others).
 
 **Shell 2 — static-file server (hosts `index.html` + maps `/sdk/*` to
 the in-repo [`web/`](../../../web/) folder so the page can `import`
@@ -46,7 +47,7 @@ Open <http://localhost:8080/> in any modern browser. Runtime in shell
   const reply = await ros.call('/add_two_ints', { a: '2n', b: '40n' });
   console.log(reply.sum); // '42n'
 
-  await ros.subscribe('/web_demo_tick', (msg) => render(msg.data));
+  await ros.subscribe('/web_demo_chatter', (msg) => render(msg.data));
   await ros.publish('/web_demo_chatter', { data: 'hi' });
 </script>
 ```
@@ -71,12 +72,12 @@ so `subscribe` is reachable over HTTP as a `text/event-stream` — useful for
 clients that can't hold a WebSocket open:
 
 ```bash
-curl -N http://localhost:9001/capability/subscribe/web_demo_tick
+curl -N http://localhost:9001/capability/subscribe/web_demo_chatter
 # event: ready
-# data: {"capability":"/web_demo_tick","subId":"sse"}
+# data: {"capability":"/web_demo_chatter","subId":"sse"}
 #
 # event: message
-# data: {"data":"tick 0 @ 2026-06-12T…"}
+# data: {"data":"hi from curl"}
 # …one `message` event per published sample, until you ^C
 ```
 
@@ -85,7 +86,7 @@ Browser apps should still prefer the WebSocket transport for `subscribe`
 curl / AI-agent / server-side persona.
 
 The page also has a **native `EventSource` panel** (section 6) that
-subscribes to `/web_demo_tick` over the same SSE endpoint — no SDK, no
+subscribes to `/web_demo_chatter` over the same SSE endpoint — no SDK, no
 WebSocket, just the browser primitive over plain HTTP. Because the page
 (`:8080`) and the HTTP transport (`:9001`) are different origins, the
 demo's `runtime.mjs` enables CORS (`new HttpTransport({ sse: true, cors:
@@ -94,10 +95,10 @@ pass your site's origin instead of `true`.
 
 ### Pair it with the stock publisher example
 
-The EventSource panel's topic box defaults to `/web_demo_tick`, but the
-runtime also exposes `/topic` so you can feed the demo from your own
-node instead of the built-in tick loop. In a third shell, run the
-standard publisher example:
+The EventSource panel's topic box defaults to `/web_demo_chatter` (the
+shared demo topic), but the runtime also exposes `/topic` so you can
+feed the demo from your own node. In a third shell, run the standard
+publisher example:
 
 ```bash
 source /opt/ros/<distro>/setup.bash
@@ -124,12 +125,11 @@ web runtime against your own publishers.
 ## Without the bundled `runtime.mjs`
 
 `runtime.mjs` bundles the rclnodejs/web runtime and the demo's sample
-ROS 2 nodes (the `/add_two_ints` service + the `/web_demo_tick`
-publisher) into one process so the demo runs out of the box. In a
-real project you already have those ROS 2 nodes running elsewhere,
-so you only need the runtime. **Replace shell 1's `node runtime.mjs`
-with the CLI** — shell 2 (`node static.mjs`) and the browser code are
-unchanged:
+ROS 2 nodes (the `/add_two_ints` service) into one process so the demo
+runs out of the box. In a real project you already have those ROS 2
+nodes running elsewhere, so you only need the runtime. **Replace shell
+1's `node runtime.mjs` with the CLI** — shell 2 (`node static.mjs`) and
+the browser code are unchanged:
 
 ```bash
 # shell 1 (instead of `node runtime.mjs`); the `-p rclnodejs` tells npx
@@ -138,7 +138,7 @@ npx -p rclnodejs rclnodejs-web web.json
 
 # the publisher / service the demo expects:
 ros2 run demo_nodes_cpp add_two_ints_server
-# (and a publisher of std_msgs/String on /web_demo_tick from any source)
+# (and a publisher of std_msgs/String on /web_demo_chatter from any source)
 ```
 
 > Note: this demo enables the SSE subscribe endpoint programmatically in
diff --git a/demo/web/javascript/index.html b/demo/web/javascript/index.html
index 83bae264..981862d9 100644
--- a/demo/web/javascript/index.html
+++ b/demo/web/javascript/index.html
@@ -193,7 +193,7 @@ <h2>1. Service call — <code>/add_two_ints</code></h2>
 console.log(reply.sum); <span class="com">// '42n'</span></pre>
     </div>
 
-    <h2>2. Topic subscription — <code>/web_demo_tick</code></h2>
+    <h2>2. Topic subscription — <code>/web_demo_chatter</code></h2>
     <div class="panel">
       <div class="controls">
         <div class="row">
@@ -208,8 +208,9 @@ <h2>2. Topic subscription — <code>/web_demo_tick</code></h2>
 
 <span class="kw">const</span> ros = <span class="kw">await</span> connect(<span class="str">'ws://localhost:9000/capability'</span>);
 
-<span class="com">// The server publishes /web_demo_tick once a second.</span>
-<span class="kw">const</span> sub = <span class="kw">await</span> ros.<span class="kw">subscribe</span>(<span class="str">'/web_demo_tick'</span>, (msg) =&gt; {
+<span class="com">// /web_demo_chatter is the shared demo topic — anything panel 3</span>
+<span class="com">// (or curl) publishes to it lands here, since it's the same topic.</span>
+<span class="kw">const</span> sub = <span class="kw">await</span> ros.<span class="kw">subscribe</span>(<span class="str">'/web_demo_chatter'</span>, (msg) =&gt; {
   console.log(<span class="str">'recv:'</span>, msg.data);
 });
 
@@ -295,12 +296,12 @@ <h2>5. Same capability, no SDK — just <code>curl</code></h2>
 
 <span class="com"># subscribe over SSE — streams text/event-stream until you ^C</span>
 <span class="com"># (-N disables curl's buffering so events print as they arrive)</span>
-curl -N http://localhost:9001/capability/subscribe/web_demo_tick
+curl -N http://localhost:9001/capability/subscribe/web_demo_chatter
 <span class="com"># event: ready</span>
-<span class="com"># data: {"capability":"/web_demo_tick","subId":"sse"}</span>
+<span class="com"># data: {"capability":"/web_demo_chatter","subId":"sse"}</span>
 <span class="com">#</span>
 <span class="com"># event: message</span>
-<span class="com"># data: {"data":"tick 0 @ 2026-06-12T…"}</span>
+<span class="com"># data: {"data":"hi from curl"}</span>
 <span class="com"># …one `message` event per published sample…</span>
 
 <span class="com"># allow-list rejection — returns 404 + structured error body</span>
@@ -322,14 +323,11 @@ <h2>
       section 2 is still the better fit.
     </p>
     <p style="font-size: 0.9em; color: #555">
-      The topic box defaults to <code>/web_demo_tick</code> (the demo's
-      built-in tick loop). It is also wired to <code>/topic</code> so you can
-      feed the demo from the stock publisher example instead — run
-      <code
-        >node ../../../example/topics/publisher/publisher-example.mjs</code
-      >
-      in another shell, set the box to <code>/topic</code>, and watch your own
-      node's messages stream in.
+      The topic box defaults to <code>/web_demo_chatter</code> — the same
+      topic panels 2 and 3 use, so a publish from panel 3 streams in here at
+      the same time it reaches the WebSocket subscriber. Point the box at
+      <code>/topic</code> instead to subscribe to an external ROS 2 publisher
+      (see the README's <em>publisher example</em> pairing).
     </p>
     <div class="panel">
       <div class="controls">
@@ -337,7 +335,7 @@ <h2>
           <input
             id="sseTopic"
             type="text"
-            value="/web_demo_tick"
+            value="/web_demo_chatter"
             spellcheck="false"
             aria-label="topic to subscribe to"
           />
@@ -349,9 +347,9 @@ <h2>
       <pre
         class="code"
       ><span class="com">// No import — EventSource is built into every browser.</span>
-<span class="com">// Swap the topic for '/topic' to pair with publisher-example.mjs.</span>
+<span class="com">// '/web_demo_chatter' is the shared demo topic; use '/topic' to pair with publisher-example.mjs.</span>
 <span class="kw">const</span> es = <span class="kw">new</span> EventSource(
-  <span class="str">'http://localhost:9001/capability/subscribe/web_demo_tick'</span>,
+  <span class="str">'http://localhost:9001/capability/subscribe/web_demo_chatter'</span>,
 );
 
 es.addEventListener(<span class="str">'ready'</span>, (e) =&gt;
@@ -472,7 +470,7 @@ <h2>
         subBtn.onclick = async () => {
           if (!ros) return;
           try {
-            tickSub = await ros.subscribe('/web_demo_tick', (msg) =>
+            tickSub = await ros.subscribe('/web_demo_chatter', (msg) =>
               log('tickLog', msg.data)
             );
             subBtn.disabled = true;
@@ -537,7 +535,7 @@ <h2>
         sseBtn.onclick = () => {
           closeEs();
           // Accept '/topic' or 'topic'; the URL path carries the bare name.
-          const name = (sseTopic.value || '/web_demo_tick')
+          const name = (sseTopic.value || '/web_demo_chatter')
             .trim()
             .replace(/^\//, '');
           const url = `${ENDPOINTS.http}/capability/subscribe/${encodeURIComponent(
diff --git a/demo/web/javascript/runtime.mjs b/demo/web/javascript/runtime.mjs
index 943eb85e..8616f82f 100644
--- a/demo/web/javascript/runtime.mjs
+++ b/demo/web/javascript/runtime.mjs
@@ -38,7 +38,7 @@ function displayHost(host) {
 // Render the registry as a small human-readable table:
 //   call       /add_two_ints       example_interfaces/srv/AddTwoInts
 //   publish    /web_demo_chatter   std_msgs/msg/String
-//   subscribe  /web_demo_tick      std_msgs/msg/String
+//   subscribe  /web_demo_chatter   std_msgs/msg/String
 function formatCapabilities(caps) {
   const rows = [];
   for (const verb of ['call', 'publish', 'subscribe']) {
@@ -69,17 +69,6 @@ node.createService(
   }
 );
 
-// A real ROS 2 publisher producing a tick once a second so the
-// browser's subscribe() has something to receive without the user
-// having to publish first.
-const tickPub = node.createPublisher('std_msgs/msg/String', '/web_demo_tick');
-let counter = 0;
-setInterval(() => {
-  tickPub.publish({
-    data: `tick ${counter++} @ ${new Date().toISOString()}`,
-  });
-}, 1000);
-
 rclnodejs.spin(node);
 
 // ---- Layer 2 + 3: capability runtime over WebSocket *and* HTTP -------
@@ -116,10 +105,12 @@ runtime.expose({
   call: { '/add_two_ints': 'example_interfaces/srv/AddTwoInts' },
   publish: { '/web_demo_chatter': 'std_msgs/msg/String' },
   subscribe: {
-    '/web_demo_tick': 'std_msgs/msg/String',
+    // Shared talker/listener topic: panels 2 (WebSocket), 3 (round-trip),
+    // and 6 (SSE) all use it — so a browser publish is visible across
+    // every subscriber at once.
     '/web_demo_chatter': 'std_msgs/msg/String',
     // Pairs with the stock publisher example so developers can feed the
-    // demo from their own node instead of the built-in tick loop:
+    // demo from their own node:
     //   node ../../../example/topics/publisher/publisher-example.mjs
     // then subscribe to `/topic` from the browser / curl / EventSource.
     '/topic': 'std_msgs/msg/String',
diff --git a/demo/web/javascript/web.json b/demo/web/javascript/web.json
index 561f65fc..ff4f0b59 100644
--- a/demo/web/javascript/web.json
+++ b/demo/web/javascript/web.json
@@ -15,8 +15,8 @@
       "/web_demo_chatter": "std_msgs/msg/String"
     },
     "subscribe": {
-      "/web_demo_tick": "std_msgs/msg/String",
-      "/web_demo_chatter": "std_msgs/msg/String"
+      "/web_demo_chatter": "std_msgs/msg/String",
+      "/topic": "std_msgs/msg/String"
     }
   }
 }

From 18eafdae741f1aa0c4ae41cb1847004522806889 Mon Sep 17 00:00:00 2001
From: Minggang Wang <minggangw@gmail.com>
Date: Fri, 12 Jun 2026 17:45:18 +0800
Subject: [PATCH 4/7] Address comments

---
 demo/web/javascript/README.md | 79 +++++++++++++----------------------
 demo/web/typescript/README.md | 24 ++++-------
 2 files changed, 38 insertions(+), 65 deletions(-)

diff --git a/demo/web/javascript/README.md b/demo/web/javascript/README.md
index 77c33646..2a33997a 100644
--- a/demo/web/javascript/README.md
+++ b/demo/web/javascript/README.md
@@ -57,19 +57,18 @@ can flip the SDK between the two without restarting.
 
 ## Same capability, no SDK
 
-Every `call` / `publish` is also reachable as plain HTTP — drive the
-runtime from `curl`, Postman, or an AI agent without any JavaScript:
+Every `call` / `publish` is reachable as plain HTTP — drive the runtime
+from `curl`, Postman, or an AI agent, no JavaScript required:
 
 ```bash
 curl -sS -X POST http://localhost:9001/capability/call/add_two_ints \
-  -H 'content-type: application/json' \
-  -d '{"a":"7n","b":"35n"}'
+  -H 'content-type: application/json' -d '{"a":"7n","b":"35n"}'
 # => {"sum":"42n"}
 ```
 
-This demo's `runtime.mjs` also enables SSE (`new HttpTransport({ sse: true })`),
-so `subscribe` is reachable over HTTP as a `text/event-stream` — useful for
-clients that can't hold a WebSocket open:
+The demo also enables SSE (`new HttpTransport({ sse: true })`), so
+`subscribe` works over HTTP as a `text/event-stream` — handy for clients
+that can't hold a WebSocket open:
 
 ```bash
 curl -N http://localhost:9001/capability/subscribe/web_demo_chatter
@@ -78,70 +77,50 @@ curl -N http://localhost:9001/capability/subscribe/web_demo_chatter
 #
 # event: message
 # data: {"data":"hi from curl"}
-# …one `message` event per published sample, until you ^C
 ```
 
-Browser apps should still prefer the WebSocket transport for `subscribe`
-(one connection multiplexes every topic). SSE subscribe targets the
-curl / AI-agent / server-side persona.
+The page's **native `EventSource` panel** (section 6) reads this same
+stream — no SDK, no WebSocket. It works cross-origin (`:8080` → `:9001`)
+because the demo also enables CORS (`new HttpTransport({ sse: true, cors:
+true })`); in production, pass your site's origin instead of `true`.
 
-The page also has a **native `EventSource` panel** (section 6) that
-subscribes to `/web_demo_chatter` over the same SSE endpoint — no SDK, no
-WebSocket, just the browser primitive over plain HTTP. Because the page
-(`:8080`) and the HTTP transport (`:9001`) are different origins, the
-demo's `runtime.mjs` enables CORS (`new HttpTransport({ sse: true, cors:
-true })`) so the cross-origin `EventSource` is allowed. In production,
-pass your site's origin instead of `true`.
+> For browser apps, prefer the WebSocket transport for `subscribe` — one
+> connection multiplexes every topic. SSE targets the curl / AI-agent /
+> server-side persona.
 
-### Pair it with the stock publisher example
+### Pair it with your own publisher
 
-The EventSource panel's topic box defaults to `/web_demo_chatter` (the
-shared demo topic), but the runtime also exposes `/topic` so you can
-feed the demo from your own node. In a third shell, run the standard
-publisher example:
+The runtime also exposes `/topic`, so you can feed the demo from any ROS 2
+node instead of the in-page publisher. Run the stock publisher example in
+a third shell, then point the EventSource panel (or `curl`) at `/topic`:
 
 ```bash
 source /opt/ros/<distro>/setup.bash
 node ../../../example/topics/publisher/publisher-example.mjs
-# Publishing message: Hello ROS 0
-# Publishing message: Hello ROS 1
-# …
-```
-
-Then set the panel's topic box to `/topic` and click **open
-EventSource** — you'll see that node's `Hello ROS N` messages stream in.
-The same works over `curl`:
+# Publishing message: Hello ROS 0, 1, 2, …
 
-```bash
 curl -N http://localhost:9001/capability/subscribe/topic
 # event: message
 # data: {"data":"Hello ROS 0"}
 ```
 
-This makes [`publisher-example.mjs`](../../../example/topics/publisher/publisher-example.mjs)
-and the web demo a ready-made publisher/subscriber pair for trying the
-web runtime against your own publishers.
-
 ## Without the bundled `runtime.mjs`
 
-`runtime.mjs` bundles the rclnodejs/web runtime and the demo's sample
-ROS 2 nodes (the `/add_two_ints` service) into one process so the demo
-runs out of the box. In a real project you already have those ROS 2
-nodes running elsewhere, so you only need the runtime. **Replace shell
-1's `node runtime.mjs` with the CLI** — shell 2 (`node static.mjs`) and
-the browser code are unchanged:
+`runtime.mjs` bundles the runtime and the demo's sample nodes into one
+process so it runs out of the box. In a real project those nodes already
+run elsewhere, so you only need the runtime — replace shell 1 with the
+CLI (shell 2 and the browser code are unchanged):
 
 ```bash
-# shell 1 (instead of `node runtime.mjs`); the `-p rclnodejs` tells npx
-# the `rclnodejs-web` binary lives inside the `rclnodejs` package:
+# the `-p rclnodejs` tells npx the binary lives in the rclnodejs package:
 npx -p rclnodejs rclnodejs-web web.json
 
-# the publisher / service the demo expects:
+# plus the service the demo expects (and any std_msgs/String publisher
+# on /web_demo_chatter):
 ros2 run demo_nodes_cpp add_two_ints_server
-# (and a publisher of std_msgs/String on /web_demo_chatter from any source)
 ```
 
-> Note: this demo enables the SSE subscribe endpoint programmatically in
-> `runtime.mjs` via `new HttpTransport({ sse: true, cors: true })`. The
-> `rclnodejs-web` CLI can do the same with `--http-sse` and `--http-cors`
-> (or `"http": { "sse": true, "cors": "*" }` in `web.json`).
+> The bundled `runtime.mjs` enables SSE + CORS via
+> `new HttpTransport({ sse: true, cors: true })`. The CLI does the same
+> with `--http-sse` / `--http-cors` (or `"http": { "sse": true, "cors":
+> "*" }` in `web.json`).
diff --git a/demo/web/typescript/README.md b/demo/web/typescript/README.md
index 7f714cd9..696d0fb2 100644
--- a/demo/web/typescript/README.md
+++ b/demo/web/typescript/README.md
@@ -26,8 +26,8 @@ npm run server
 #               also http://localhost:9001/capability
 ```
 
-`server.ts` runs the runtime *and* a tiny `/add_two_ints` service +
-1 Hz `/web_demo_tick` publisher so every panel has live data.
+`server.ts` runs the runtime *plus* a tiny `/add_two_ints` service and a
+1 Hz `/web_demo_tick` publisher, so every panel has live data.
 
 > The HTTP transport here serves `call` / `publish` only; `subscribe`
 > uses WebSocket. HTTP `subscribe` over Server-Sent Events is an opt-in
@@ -44,26 +44,20 @@ npm run dev
 
 ## Without the bundled `server.ts`
 
-`npm run server` is a convenience for this demo — it bundles the
-runtime **and** a tiny `/add_two_ints` service + `/web_demo_tick`
-publisher into one process so the demo works out of the box.
-
-In a real project you already have those ROS 2 nodes running
-elsewhere, so you only need the runtime. **Replace shell 1's
-`npm run server` with the CLI** — shell 2 (`npm run dev`) and
-`src/main.ts` are unchanged:
+`npm run server` bundles the runtime and the demo's sample nodes into one
+process so it runs out of the box. In a real project those nodes already
+run elsewhere, so you only need the runtime — replace shell 1 with the
+CLI (shell 2 and `src/main.ts` are unchanged):
 
 ```bash
-# shell 1 (instead of `npm run server`)
 npx rclnodejs-web web.json
 
-# the publisher / service the demo expects:
+# plus the nodes the demo expects:
 ros2 run demo_nodes_cpp add_two_ints_server
-# (and a publisher of std_msgs/String on /web_demo_tick from any source)
+# (and any std_msgs/String publisher on /web_demo_tick)
 ```
 
-The browser doesn't know or care which option is running — it only
-sees `ws://localhost:9000/capability` either way.
+The browser only sees `ws://localhost:9000/capability` either way.
 
 ## Other npm scripts
 

From adc39185340793ffaa8418ab67a3d14adf1c5ac1 Mon Sep 17 00:00:00 2001
From: Minggang Wang <minggangw@gmail.com>
Date: Mon, 15 Jun 2026 16:41:25 +0800
Subject: [PATCH 5/7] Address comments

---
 demo/web/javascript/index.html | 26 +++++++++++++-------------
 demo/web/javascript/web.json   |  6 ++++--
 2 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/demo/web/javascript/index.html b/demo/web/javascript/index.html
index 981862d9..ea361037 100644
--- a/demo/web/javascript/index.html
+++ b/demo/web/javascript/index.html
@@ -200,7 +200,7 @@ <h2>2. Topic subscription — <code>/web_demo_chatter</code></h2>
           <button id="subBtn">subscribe</button>
           <button id="unsubBtn" disabled>unsubscribe</button>
         </div>
-        <div class="log" id="tickLog"></div>
+        <div class="log" id="subLog"></div>
       </div>
       <pre
         class="code"
@@ -405,14 +405,14 @@ <h2>
       };
 
       let ros;
-      let tickSub;
+      let chatterSub;
 
       async function teardown() {
-        if (tickSub) {
+        if (chatterSub) {
           try {
-            await tickSub.close();
+            await chatterSub.close();
           } catch (_) {}
-          tickSub = null;
+          chatterSub = null;
           document.getElementById('subBtn').disabled = false;
           document.getElementById('unsubBtn').disabled = true;
         }
@@ -470,23 +470,23 @@ <h2>
         subBtn.onclick = async () => {
           if (!ros) return;
           try {
-            tickSub = await ros.subscribe('/web_demo_chatter', (msg) =>
-              log('tickLog', msg.data)
+            chatterSub = await ros.subscribe('/web_demo_chatter', (msg) =>
+              log('subLog', msg.data)
             );
             subBtn.disabled = true;
             unsubBtn.disabled = false;
-            log('tickLog', `subscribed (subId=${tickSub.subId})`, 'ok');
+            log('subLog', `subscribed (subId=${chatterSub.subId})`, 'ok');
           } catch (e) {
-            log('tickLog', `error: ${e.message} (${e.code})`, 'err');
+            log('subLog', `error: ${e.message} (${e.code})`, 'err');
           }
         };
         unsubBtn.onclick = async () => {
-          if (!tickSub) return;
-          await tickSub.close();
-          tickSub = null;
+          if (!chatterSub) return;
+          await chatterSub.close();
+          chatterSub = null;
           unsubBtn.disabled = true;
           subBtn.disabled = false;
-          log('tickLog', 'unsubscribed', 'ok');
+          log('subLog', 'unsubscribed', 'ok');
         };
 
         document.getElementById('pubBtn').onclick = async () => {
diff --git a/demo/web/javascript/web.json b/demo/web/javascript/web.json
index ff4f0b59..61a86daa 100644
--- a/demo/web/javascript/web.json
+++ b/demo/web/javascript/web.json
@@ -4,8 +4,10 @@
   "path": "/capability",
   "node": "rclnodejs_web_demo",
   "http": {
-    "$comment": "HTTP transport for `call` and `publish`. curl-able, AI-agent friendly. Subscribe still uses WebSocket.",
-    "port": 9001
+    "$comment": "HTTP transport for `call` and `publish` (curl-able, AI-agent friendly). `sse` also exposes `subscribe` over Server-Sent Events; `cors: \"*\"` allows any origin so a cross-origin browser EventSource can connect. Matches the bundled runtime.mjs.",
+    "port": 9001,
+    "sse": true,
+    "cors": "*"
   },
   "expose": {
     "call": {

From 8c4a641507ffdecb0544823028763ae29c5e482e Mon Sep 17 00:00:00 2001
From: Minggang Wang <minggangw@gmail.com>
Date: Mon, 15 Jun 2026 17:09:00 +0800
Subject: [PATCH 6/7] Fix build error with vs2026

---
 .../ref-napi/src/ref_napi_bindings.cpp        | 25 ++++++++++++-------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/third_party/ref-napi/src/ref_napi_bindings.cpp b/third_party/ref-napi/src/ref_napi_bindings.cpp
index 63954f33..bc4af20a 100644
--- a/third_party/ref-napi/src/ref_napi_bindings.cpp
+++ b/third_party/ref-napi/src/ref_napi_bindings.cpp
@@ -100,15 +100,22 @@ class PointerBuffer : public ObjectWrap<PointerBuffer> {
 };
 
 Object PointerBuffer::Init(Napi::Env env, Object exports) {
-  Function func =
-      DefineClass(env, "PointerBuffer",
-                  {InstanceMethod("isNull", &PointerBuffer::IsNull),
-                   InstanceMethod("get", &PointerBuffer::Get),
-                   InstanceMethod("address", &PointerBuffer::Address),
-                   InstanceMethod("toString", &PointerBuffer::ToString),
-                   InstanceMethod("copy", &PointerBuffer::Copy),
-                   InstanceMethod("slice", &PointerBuffer::Slice),
-                   InstanceAccessor<&PointerBuffer::Length>("length")});
+  Function func = DefineClass(
+      env, "PointerBuffer",
+      {InstanceMethod("isNull", &PointerBuffer::IsNull),
+       InstanceMethod("get", &PointerBuffer::Get),
+       InstanceMethod("address", &PointerBuffer::Address),
+       InstanceMethod("toString", &PointerBuffer::ToString),
+       InstanceMethod("copy", &PointerBuffer::Copy),
+       InstanceMethod("slice", &PointerBuffer::Slice),
+       // Use the runtime InstanceAccessor(name, getter, setter)
+       // overload rather than the templated
+       // InstanceAccessor<&Fn>() form: the latter's constexpr
+       // member-pointer template argument triggers an MSVC
+       // Internal Compiler Error (C1001) on the VS 2026 (v18)
+       // toolset used by the windows-2025 CI runner. This form
+       // is equivalent and compiles cleanly on every platform.
+       InstanceAccessor("length", &PointerBuffer::Length, nullptr)});
 
   exports.Set("PointerBuffer", func);
   InstanceData* data = InstanceData::Get(env);

From ecc39b16cbc48dfc31a490bcff76e255f24b91ea Mon Sep 17 00:00:00 2001
From: Minggang Wang <minggangw@gmail.com>
Date: Mon, 15 Jun 2026 17:40:40 +0800
Subject: [PATCH 7/7] Address comments

---
 lib/runtime/transports/http.js | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/lib/runtime/transports/http.js b/lib/runtime/transports/http.js
index 561d0f32..4ef7c63d 100644
--- a/lib/runtime/transports/http.js
+++ b/lib/runtime/transports/http.js
@@ -606,6 +606,12 @@ class HttpTransport extends TransportAdapter {
    * `cors` is disabled. For an allow-list, the request `Origin` is echoed
    * only when it matches (and `Vary: Origin` is set so caches don't mix
    * responses across origins).
+   *
+   * `Access-Control-Allow-Headers` reflects the browser's
+   * `Access-Control-Request-Headers` when present, so authenticated or
+   * custom-header requests (`Authorization`, `X-*`, …) pass preflight
+   * rather than being limited to `content-type`. The reflected value is
+   * added to `Vary` to keep caches correct.
    */
   _applyCors(req, res) {
     if (!this.cors) return;
@@ -620,7 +626,15 @@ class HttpTransport extends TransportAdapter {
       }
     }
     res.setHeader('access-control-allow-methods', 'GET, POST, OPTIONS');
-    res.setHeader('access-control-allow-headers', 'content-type');
+    // Echo whatever headers the browser says it will send; fall back to
+    // `content-type` for non-preflight requests that carry no such hint.
+    const requested = req.headers['access-control-request-headers'];
+    if (requested) {
+      res.appendHeader('vary', 'Access-Control-Request-Headers');
+      res.setHeader('access-control-allow-headers', requested);
+    } else {
+      res.setHeader('access-control-allow-headers', 'content-type');
+    }
     res.setHeader('access-control-max-age', '86400');
   }
 }