@jxsuite/server 2.2.7 → 4.0.0

package/src/refactor/refs.ts

@@ -16,9 +16,11 @@
  *
  * The visitor seam is what stops the read side from being a second, drifting copy of the key list.
  * A new reference-bearing key added below is a key the usage count sees on the same commit.
+ *
+ * @docs studio/projects/pages-layouts-components
  */
 
-import { classifyRef, rewriteRef } from "./paths.ts";
+import { classifyRef, looksLikeFileRef, rewriteRef } from "./paths.ts";
 import type { RemapCtx } from "./paths.ts";
 
 /** A single reference rewrite, for the rename report. */
@@ -37,7 +39,8 @@ export interface RewriteResult {
  * One visit of a reference-bearing string.
  *
  * @param value — the raw authored reference, exactly as written.
- * @param refType — which key carried it (`$ref`, `$layout`, `attr`, `imports`, `$elements`, `url`).
+ * @param refType — which key carried it (`$ref`, `$layout`, `attr`, `imports`, `$elements`, `url`,
+ *   or `path` for a value matched by shape rather than by key name).
  * @param rootRelativeBare — whether a bare value resolves against the project root (`$layout`).
  * @returns A replacement string to write back, or `null` to leave the document untouched.
  */
@@ -50,6 +53,17 @@ export type RefVisitor = (
 /** Matches `url(...)` targets inside a CSS string value, capturing the optional quote. */
 const URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
 
+/**
+ * Keys whose string values are PROSE, and are therefore never offered to the shape fallback.
+ *
+ * A page that writes "see layouts/base.json" in its body text names a file without referencing it,
+ * and rewriting that sentence during a rename would be vandalism. Almost every such string is
+ * already excluded by the whitespace test in `looksLikeFileRef`; these two keys are where a
+ * single-token one is plausible, and a whole-repo survey of file-shaped string values found
+ * non-reference hits under no other key.
+ */
+const PROSE_KEYS = new Set(["textContent", "innerHTML"]);
+
 /** Offer a scalar string reference under `key` to the visitor, writing back any replacement. */
 function visitScalar(
   container: Record<string, unknown>,
@@ -189,8 +203,42 @@ export function walkDocRefs(node: unknown, visit: RefVisitor): void {
         walkStyle(value, visit);
         break;
       }
+      /*
+       * Everything else, by SHAPE.
+       *
+       * The cases above are the keys that carry a reference BY NAME, and for years that list was
+       * taken to be the whole of it. It is not: the commonest media reference in a real project is
+       * a schema-typed component prop (`$props.bg`, `attributes["props.image"]`), and beside it sit
+       * a content entry's frontmatter (`cover:`), a prop schema's `default`, `project.json`'s
+       * `defaults.layout`, `poster`, `srcset` and `$head` meta `content`. Measured across the
+       * committed starters, 73 of 101 files under `public/` were used and reported zero.
+       *
+       * Naming those keys one at a time would be the same mistake with a longer list — the next
+       * extension to define a media-typed prop would reopen it. So an unrecognised string is
+       * offered whenever it is SHAPED like a file, and precision stays where it already was: the
+       * caller's resolve-and-compare gate, which only counts a value that resolves to the exact
+       * file in question.
+       */
       default: {
-        walkDocRefs(value, visit);
+        if (typeof value === "string") {
+          if (!PROSE_KEYS.has(key) && looksLikeFileRef(value)) {
+            visitScalar(obj, key, "path", visit, false);
+          }
+        } else if (Array.isArray(value)) {
+          const arr = value as unknown[];
+          for (let i = 0; i < arr.length; i += 1) {
+            const item = arr[i];
+            if (typeof item === "string") {
+              if (!PROSE_KEYS.has(key) && looksLikeFileRef(item)) {
+                visitIndexed(arr, i, "path", visit);
+              }
+            } else {
+              walkDocRefs(item, visit);
+            }
+          }
+        } else {
+          walkDocRefs(value, visit);
+        }
       }
     }
   }

package/src/refactor/scan.ts

@@ -22,10 +22,30 @@ export interface LoadedDoc {
 
 const isJsonPath = (p: string) => p.endsWith(".json");
 
-/** Skip vendored / build / agent directories (mirrors the component-discovery filter). */
+/**
+ * Skip vendored / build / agent directories (mirrors the component-discovery filter), and generated
+ * schema artifacts.
+ *
+ * Every committed `*.schema.json` in a project is a build output — `bun run schema:generate-all`
+ * composes the `project.schema.json` / `document.schema.json` pair into each project root — and the
+ * generators embed live `examples` blocks. `project.core.schema.json`'s `$head` example carries
+ * `/favicon.svg`, and the per-project entry schema enumerates the project's own layouts, so a sweep
+ * that reads them makes every project report its own schema as a referrer of its favicon and its
+ * base layout. Those are not references anyone authored, and nobody should be told a rename will
+ * break one.
+ *
+ * The stale-schema problem a skipped file leaves behind already has an owner: `bun run
+ * schema:verify` catches it and `schema:sync` regenerates it. A rewrite here would be a second
+ * writer on a generated file.
+ */
 export function skipScanPath(match: string): boolean {
   const f = fwd(match);
-  return match.includes("node_modules") || f.includes("dist/") || f.includes(".claude/");
+  return (
+    match.includes("node_modules") ||
+    f.includes("dist/") ||
+    f.includes(".claude/") ||
+    f.endsWith(".schema.json")
+  );
 }
 
 /** Build the recursive glob covering JSON plus every registered document/content extension. */

package/src/server.ts

@@ -421,6 +421,7 @@ export async function createDevServer(options: {
 
         const res = await handleStudioApi(req, url, absRoot, activeProjectRoot, {
           allowedRoots,
+          onFileMoved: (absPath) => collabRegistry.handleExternalChange(absPath),
           onProjectCreated: (created) => createdRoots.push(created),
         });
         if (res) {

package/src/sse.ts

@@ -0,0 +1,126 @@
+/**
+ * The live-reload stream contract, in one place.
+ *
+ * Two surfaces speak it — the dev server's `/__reload` ({@link ./watch.ts}) and the live preview
+ * origin's own channel ({@link ./live-preview.ts}) — and what they share is not "an SSE endpoint"
+ * but a specific reading of the HTML Standard's EventSource contract that took a defect report to
+ * arrive at (specs/server.md §3.1). Re-deriving it per surface is how one of them ends up with a
+ * reconnect that silently never fires.
+ *
+ * The two halves that are easy to omit and expensive to omit:
+ *
+ * - **`retry:`** sets the reconnection time. The default is user-agent defined and is measured in
+ *   seconds; during a server restart that is long enough to watch a save do nothing. 500 ms is
+ *   loopback, so the reconnect costs nothing and lands inside the restart.
+ * - **`Last-Event-ID`** is how the browser says "I was here before", and it is the ONLY way the
+ *   server can tell a reconnection from a first connection. A reconnecting client gets exactly one
+ *   reload and no replay; a first connection gets none at all, because reloading a page that just
+ *   loaded is a reload loop.
+ *
+ * A hub broadcasts to every client it holds. Membership is the socket's whole lifetime — added on
+ * open, dropped on cancel — so a broadcast after a tab closes reaches nobody rather than throwing.
+ */
+
+/**
+ * Reconnection time advertised on the stream, in milliseconds (HTML Standard, `retry:`).
+ *
+ * Both endpoints are on loopback, so a reconnect costs nothing and half a second lands inside a
+ * typical restart.
+ */
+export const RECONNECT_MS = 500;
+
+/** How often a comment frame is sent to keep an idle connection from being reaped. */
+const HEARTBEAT_MS = 15_000;
+
+/** A broadcast hub for one stream. */
+export interface SseHub {
+  /** Send the default (unnamed) `reload` message, stamped with the next `id:`. */
+  broadcast: () => void;
+  /**
+   * Send a _named_ event.
+   *
+   * A consumer wired as `onmessage` sees only the unnamed message, so a named event reaches a
+   * listener that asked for it without triggering everyone else's reload. That is what lets the
+   * studio shell subscribe to `fs` on the same connection the preview reloads on.
+   */
+  broadcastEvent: (event: string, payload: unknown) => void;
+  /** Open the stream. Pass the request so `Last-Event-ID` can be read. */
+  handleSSE: (request?: Request) => Response;
+  /** How many clients are connected right now. */
+  clientCount: () => number;
+}
+
+/** Create a hub. Nothing is shared between hubs — a project's clients are its own. */
+export function createSseHub(): SseHub {
+  const clients = new Set<(msg: string) => void>();
+  const encoder = new TextEncoder();
+
+  /*
+   * Monotonic reload counter, sent as the SSE `id:` of every reload frame.
+   *
+   * Its only job is to arm the browser: a stream that has never sent an `id:` makes the client omit
+   * `Last-Event-ID` on reconnect, and then the server cannot tell a first connection from a
+   * reconnection. **Nothing is buffered against it and nothing is replayed.** A reconnecting client
+   * gets exactly one reload, because the page it is holding was built before the disconnect and a
+   * full reload subsumes every event it missed — one is as correct as a hundred and finishes
+   * sooner. Do not "complete" this into a replay buffer; there is no per-event state to replay.
+   */
+  let lastEventId = 0;
+
+  function broadcast() {
+    lastEventId += 1;
+    const frame = `id: ${lastEventId}\ndata: reload\n\n`;
+    for (const send of clients) {
+      send(frame);
+    }
+  }
+
+  function broadcastEvent(event: string, payload: unknown) {
+    const frame = `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;
+    for (const send of clients) {
+      send(frame);
+    }
+  }
+
+  function handleSSE(request?: Request) {
+    const resuming = (request?.headers.get("Last-Event-ID") ?? "") !== "";
+    let send: ((msg: string) => void) | undefined;
+    const stream = new ReadableStream({
+      cancel() {
+        if (send) {
+          clients.delete(send);
+        }
+      },
+      start(c) {
+        send = (msg: string) => {
+          try {
+            c.enqueue(encoder.encode(msg));
+          } catch {}
+        };
+        clients.add(send);
+        // The retry interval is a stream-level field, so it is set once, before any event.
+        send(`retry: ${RECONNECT_MS}\n\n`);
+        if (resuming) {
+          lastEventId += 1;
+          send(`id: ${lastEventId}\ndata: reload\n\n`);
+        }
+        const hb = setInterval(() => {
+          try {
+            c.enqueue(encoder.encode(": heartbeat\n\n"));
+          } catch {
+            clearInterval(hb);
+          }
+        }, HEARTBEAT_MS);
+      },
+    });
+    return new Response(stream, {
+      headers: {
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "Content-Type": "text/event-stream",
+      },
+    });
+  }
+
+  return { broadcast, broadcastEvent, clientCount: () => clients.size, handleSSE };
+}

package/src/studio-api.ts

@@ -22,13 +22,19 @@ import { readBundledProjectSchemas } from "@jxsuite/compiler/schema-command";
 import { handleDataApi } from "./data-api.ts";
 import { containedPath } from "./net-guard.ts";
 import { startSitePreview } from "./site-preview.ts";
+import {
+  clearLivePreviewOverlay,
+  navigateLivePreview,
+  setLivePreviewOverlay,
+  startLivePreview,
+} from "./live-preview.ts";
 import { applyRename } from "./refactor/apply.ts";
 import { findReferences } from "./refactor/find-refs.ts";
 import {
   bunExecutable,
   dependenciesNeedInstall,
   installDependencies,
-  outdatedPackages,
+  packageVersions,
   setPackageVersions,
 } from "./packages.ts";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
@@ -288,6 +294,17 @@ export interface StudioApiOptions {
    * unreachable by the very request that made it.
    */
   onProjectCreated?: (projectRoot: string) => void;
+  /**
+   * Tell the collaboration registry a path changed underneath it — the same hook the file watcher
+   * uses (`server.ts`), handed to the one mutation the watcher cannot describe.
+   *
+   * A rename MOVES a file, and a live room is keyed by the old path. Without this the room survives
+   * the move holding pre-rename content, and `stop()`'s graceful-shutdown flush writes it back —
+   * RECREATING the file the rename deleted. `pendingPersist` receives a path on the room's seed
+   * transaction, so a clean editor does not protect against it either. Passing the OLD absolute
+   * path lets the registry reset that room, which deletes it and makes the later flush a no-op.
+   */
+  onFileMoved?: (absPath: string) => void;
 }
 
 /**
@@ -323,6 +340,23 @@ function conflictingPaths(output: string): string[] {
   return [...paths];
 }
 
+/**
+ * Order a directory listing so two identical requests answer identically.
+ *
+ * `readdir` and `Bun.Glob.scan` both answer in FILESYSTEM order, which is not an order at all: it
+ * varies with the directory's internal layout and therefore with the history of writes to it. That
+ * reached the screenshots as a picture that changed on its own — `blog-grid.png` photographs a
+ * content collection, `content-source.ts` inserts rows in listing order (deliberately, so a
+ * concurrent read cannot decide it), and the listing underneath was unsorted. The collection's
+ * three posts swapped places between runs and rewrote the image 15 times in ten days.
+ *
+ * Codepoint order, not `localeCompare`: the comparison has to answer the same on a maintainer's
+ * machine and in the capture container, and a locale-aware collation does not promise that.
+ */
+function byPathOrder<T extends { path: string }>(entries: T[]): T[] {
+  return entries.toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
 export async function handleStudioApi(
   req: Request,
   url: URL,
@@ -701,7 +735,7 @@ export async function handleStudioApi(
             }
           } catch {}
         }
-        return Response.json(files);
+        return Response.json(byPathOrder(files));
       }
 
       const entries = await readdir(absDir, { withFileTypes: true });
@@ -720,7 +754,7 @@ export async function handleStudioApi(
           type: entry.isDirectory() ? "directory" : "file",
         });
       }
-      return Response.json(files);
+      return Response.json(byPathOrder(files));
     } catch (error) {
       return problem("internalError", errorMessage(error));
     }
@@ -889,6 +923,76 @@ export async function handleStudioApi(
     }
   }
 
+  /**
+   * Preview the site LIVE — the working tree browsable at real routes, with no build on the path.
+   *
+   * The sibling of `/__studio/build` and the one Open in Browser reaches first. What it answers
+   * with is not compiler output: `@jxsuite/site` composes each page on demand and
+   * `@jxsuite/runtime` assembles it in the reader's browser, so what opens is the tree as it stands
+   * — the author's unsaved edits included, because Studio publishes those as an overlay this origin
+   * reads first.
+   *
+   * `reused` is the second answer and the caller must honour it. A tab already holding this
+   * project's reload stream is retargeted in place, and opening another would give the author two
+   * tabs on one project — which is the thing the retarget exists to prevent.
+   */
+  if (path === "/__studio/preview" && req.method === "POST") {
+    const dir = activeProjectRoot ?? root;
+    if (!existsSync(resolve(dir, "project.json"))) {
+      return problem("invalidRequest", "Not a site project");
+    }
+    let body: { route?: string };
+    try {
+      body = (await req.json()) as { route?: string };
+    } catch {
+      return problem("invalidRequest", "Invalid JSON body");
+    }
+    try {
+      const preview = await startLivePreview(dir);
+      const reused = body.route ? await navigateLivePreview(dir, body.route) : false;
+      return Response.json({
+        errors: preview.errors,
+        /* A live preview writes nothing, so there are no files to count. The field is part of the
+           shared shape and saying zero is the honest answer rather than an omission. */
+        files: 0,
+        mode: "live",
+        reused,
+        routes: preview.routes,
+        url: preview.origin,
+      });
+    } catch (error) {
+      return problem("internalError", errorMessage(error));
+    }
+  }
+
+  /**
+   * The unsaved bytes a live preview reads before the disk.
+   *
+   * POST publishes one document, DELETE retracts one or all of them. Studio owns the lifecycle — it
+   * knows which documents are dirty and when a save, a close or a discard ends that — so this route
+   * stores what it is told and decides nothing.
+   */
+  if (path === "/__studio/preview/overlay") {
+    const dir = activeProjectRoot ?? root;
+    let body: { path?: string; contents?: string };
+    try {
+      body = (await req.json()) as { path?: string; contents?: string };
+    } catch {
+      return problem("invalidRequest", "Invalid JSON body");
+    }
+    if (req.method === "POST") {
+      if (typeof body.path !== "string" || typeof body.contents !== "string") {
+        return problem("invalidRequest", "Missing path or contents");
+      }
+      setLivePreviewOverlay(dir, body.path, body.contents);
+      return new Response(null, { status: 204 });
+    }
+    if (req.method === "DELETE") {
+      clearLivePreviewOverlay(dir, typeof body.path === "string" ? body.path : undefined);
+      return new Response(null, { status: 204 });
+    }
+  }
+
   // ─── Package management ──────────────────────────────────────────────────────
 
   // List CEM-bearing npm packages
@@ -1046,12 +1150,12 @@ export async function handleStudioApi(
     return Response.json({ needsInstall: dependenciesNeedInstall(scanRoot) });
   }
 
-  // Dependencies with a newer version available
-  if (path === "/__studio/packages/outdated" && req.method === "GET") {
+  // The newest published version of each dependency (whether or not it is behind)
+  if (path === "/__studio/packages/versions" && req.method === "GET") {
     try {
       const dir = url.searchParams.get("dir") || activeProjectRoot || root;
       const scanRoot = isAbsolute(dir) ? dir : resolve(root, dir);
-      return Response.json(await outdatedPackages(scanRoot));
+      return Response.json(await packageVersions(scanRoot));
     } catch (error) {
       return problem("internalError", errorMessage(error));
     }
@@ -1193,6 +1297,9 @@ export async function handleStudioApi(
     } catch (error) {
       return problem("internalError", errorMessage(error));
     }
+    // Immediately, and before the refactor pass: a room still keyed to the old path would be
+    // Flushed back onto disk at shutdown, recreating the file this rename just moved.
+    opts.onFileMoved?.(absFrom);
     // Refactor pass: rewrite path references project-wide and, for a component, auto-rename its tag.
     // The move already succeeded, so a refactor failure is reported but never fails the rename.
     const scanRoot = activeProjectRoot ?? root;
@@ -1201,29 +1308,42 @@ export async function handleStudioApi(
       const report = await applyRename({ absFrom, absTo, registry, root: scanRoot });
       return Response.json(report);
     } catch (error) {
+      /* Project-relative, like the report this stands in for. The route takes its `from`/`to` in
+         server space and answers in project space; emitting two spaces from one route is what
+         made the sibling `references` route's own confusion survive review (issue 239). */
       return Response.json({
         error: errorMessage(error),
-        from: fwd(relative(root, absFrom)),
+        from: fwd(relative(scanRoot, absFrom)),
         ok: true,
-        to: fwd(relative(root, absTo)),
+        to: fwd(relative(scanRoot, absTo)),
       });
     }
   }
 
   // Where a file / component tag is used (the read side of the rename refactor's walker)
   if (path === "/__studio/references" && req.method === "GET") {
-    const target = url.searchParams.get("path");
+    let target = url.searchParams.get("path");
     const tag = url.searchParams.get("tag");
     if (!target && !tag) {
       return problem("invalidRequest", "Missing path or tag");
     }
     const scanRoot = activeProjectRoot ?? root;
     if (target) {
+      /* Server-root-relative in (like every sibling route, and like the adapter's `serverPath()`
+         sends), project-relative out. The sweep runs in the project's space, so the target has to
+         be re-expressed into it: resolving against `scanRoot` directly doubles the prefix, and a
+         doubled prefix names a file that does not exist — which reads as a confident zero (issue 239). */
+      const abs = resolve(root, target);
       try {
-        assertAccessible(resolve(scanRoot, target), root, activeProjectRoot);
+        assertAccessible(abs, root, activeProjectRoot);
       } catch (error) {
         return new Response(errorMessage(error), { status: 400 });
       }
+      const inProject = fwd(relative(scanRoot, abs));
+      if (inProject === "" || inProject.startsWith("../") || isAbsolute(inProject)) {
+        return problem("invalidRequest", "path is outside the active project");
+      }
+      target = inProject;
     }
     try {
       const registry = await getFormatRegistry(scanRoot);

package/src/watch.ts

@@ -5,6 +5,7 @@ import { relative } from "node:path";
 import { rebuild } from "./build.ts";
 import { coalesceFsEvents, toFsEvent } from "./refactor/fs-events.ts";
 import { createWatchIgnore } from "./watch-policy.ts";
+import { createSseHub } from "./sse.ts";
 import { invalidateReferenceCache } from "./refactor/find-refs.ts";
 import type { BuildEntry } from "./types.ts";
 import type { FsEventPayload } from "./refactor/fs-events.ts";
@@ -51,14 +52,14 @@ function shouldIgnore(pathname: string, ignore: string[]) {
 
 export { shouldIgnore };
 
-/**
- * Reconnection time advertised on the stream, in milliseconds (HTML Standard, `retry:`).
- *
- * The default is user-agent defined and measured in seconds, which on a dev server restart is long
- * enough for a save to look like it did nothing. Both endpoints are on loopback, so a reconnect
- * costs nothing and half a second lands inside a typical restart.
+/*
+ * The stream itself lives in `sse.ts`, shared with the live preview origin's channel — the reading
+ * of the EventSource contract it encodes (`retry:`, the `id:` that arms `Last-Event-ID`, one reload
+ * on resume and none on a first connection) is specified once, in specs/server.md §3.1, and having
+ * two of it is how one of them silently stops reconnecting. Re-exported here because `RECONNECT_MS`
+ * is part of what this module's consumers already read.
  */
-export const RECONNECT_MS = 500;
+export { RECONNECT_MS } from "./sse.ts";
 
 export const SSE_SCRIPT = `\n<script>new EventSource('/__reload').onmessage=()=>location.reload()</script>`;
 
@@ -102,96 +103,7 @@ export function createWatcher(
   const reloadOnAnyChange = opts.reloadOnAnyChange ?? false;
   const { preReload } = opts;
 
-  const clients = new Set<(msg: string) => void>();
-  const encoder = new TextEncoder();
-
-  /*
-   * Monotonic reload counter, sent as the SSE `id:` of every reload frame.
-   *
-   * Its only job is to arm the browser: a stream that has never sent an `id:` makes the client omit
-   * `Last-Event-ID` on reconnect, and then the server cannot tell a first connection from a
-   * reconnection. **Nothing is buffered against it and nothing is replayed.** A reconnecting client
-   * gets exactly one reload, because the page it is holding was built before the disconnect and a
-   * full reload subsumes every event it missed — one is as correct as a hundred and finishes
-   * sooner. Do not "complete" this into a replay buffer; there is no per-event state to replay.
-   */
-  let lastEventId = 0;
-
-  function broadcast() {
-    lastEventId += 1;
-    const frame = `id: ${lastEventId}\ndata: reload\n\n`;
-    for (const send of clients) {
-      send(frame);
-    }
-  }
-
-  /**
-   * Send a _named_ SSE event. The preview iframe only listens to the default (unnamed) `onmessage`,
-   * so named events (e.g. "fs") reach the studio shell without triggering a preview reload.
-   */
-  function broadcastEvent(event: string, payload: unknown) {
-    const frame = `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;
-    for (const send of clients) {
-      send(frame);
-    }
-  }
-
-  /**
-   * Open the live-reload stream.
-   *
-   * Two halves of the HTML Standard's EventSource contract that were missing, and are the whole of
-   * `gap:sse-reconnect`:
-   *
-   * - **`retry:`** sets the reconnection time. The default is user-agent defined and is measured in
-   *   seconds; during a dev-server restart that is long enough to watch a save do nothing. 500ms is
-   *   loopback, so the reconnect costs nothing and lands inside the restart.
-   * - **`Last-Event-ID`** is how the browser says "I was here before". It gets **one** reload and no
-   *   replay — see the note on `lastEventId`. A dev server has no event log and needs none: the
-   *   reload is idempotent and total.
-   *
-   * @param {Request} [request] - The stream request; read only for its `Last-Event-ID`
-   * @returns {Response}
-   */
-  function handleSSE(request?: Request) {
-    const resuming = (request?.headers.get("Last-Event-ID") ?? "") !== "";
-    /** @type {((msg: string) => void) | undefined} */
-    let send: ((msg: string) => void) | undefined;
-    const stream = new ReadableStream({
-      cancel() {
-        if (send) {
-          clients.delete(send);
-        }
-      },
-      start(c) {
-        send = (msg: string) => {
-          try {
-            c.enqueue(encoder.encode(msg));
-          } catch {}
-        };
-        clients.add(send);
-        // The retry interval is a stream-level field, so it is set once, before any event.
-        send(`retry: ${RECONNECT_MS}\n\n`);
-        if (resuming) {
-          lastEventId += 1;
-          send(`id: ${lastEventId}\ndata: reload\n\n`);
-        }
-        const hb = setInterval(() => {
-          try {
-            c.enqueue(encoder.encode(": heartbeat\n\n"));
-          } catch {
-            clearInterval(hb);
-          }
-        }, 15_000);
-      },
-    });
-    return new Response(stream, {
-      headers: {
-        "Cache-Control": "no-cache",
-        Connection: "keep-alive",
-        "Content-Type": "text/event-stream",
-      },
-    });
-  }
+  const { broadcast, broadcastEvent, handleSSE } = createSseHub();
 
   let timer: ReturnType<typeof setTimeout> | null = null;
   let fsTimer: ReturnType<typeof setTimeout> | null = null;