@rsc-kit/core 0.24.3 → 0.26.0

package/dist/js/Changes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * What a rendered region is live on, handed to the tab's watcher.
+ *
+ * Renders nothing. Rendered by `RefreshOn` beside the region it describes,
+ * so it arrives in the same payload - with the page, and again with the
+ * region each time it is refreshed, carrying the versions that render saw.
+ */
+export declare function Changes({ target, names, }: {
+    target: string;
+    names: Record<string, [number, string]>;
+}): null;

package/dist/js/Changes.js

@@ -0,0 +1,19 @@
+"use client";
+import { useEffect } from "react";
+import { register } from "./changesStore";
+/**
+ * What a rendered region is live on, handed to the tab's watcher.
+ *
+ * Renders nothing. Rendered by `RefreshOn` beside the region it describes,
+ * so it arrives in the same payload - with the page, and again with the
+ * region each time it is refreshed, carrying the versions that render saw.
+ */
+export function Changes({ target, names, }) {
+    const key = JSON.stringify(names);
+    useEffect(() => register({
+        target,
+        names: JSON.parse(key),
+    }), [target, key]);
+    return null;
+}
+//# sourceMappingURL=Changes.js.map

package/dist/js/Changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Changes.js","sourceRoot":"","sources":["../../src/js/Changes.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,EACtB,MAAM,EACN,KAAK,GAIN;IACC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAElC,SAAS,CACP,GAAG,EAAE,CACH,QAAQ,CAAC;QACP,MAAM;QACN,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqC;KAC3D,CAAC,EACJ,CAAC,MAAM,EAAE,GAAG,CAAC,CACd,CAAC;IAEF,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["\"use client\";\n\nimport { useEffect } from \"react\";\nimport { register } from \"./changesStore\";\n\n/**\n * What a rendered region is live on, handed to the tab's watcher.\n *\n * Renders nothing. Rendered by `RefreshOn` beside the region it describes,\n * so it arrives in the same payload - with the page, and again with the\n * region each time it is refreshed, carrying the versions that render saw.\n */\nexport function Changes({\n  target,\n  names,\n}: {\n  target: string;\n  names: Record<string, [number, string]>;\n}) {\n  const key = JSON.stringify(names);\n\n  useEffect(\n    () =>\n      register({\n        target,\n        names: JSON.parse(key) as Record<string, [number, string]>,\n      }),\n    [target, key],\n  );\n\n  return null;\n}\n"]}

package/dist/js/changesStore.d.ts

@@ -0,0 +1,9 @@
+/** The names a region is live on, as the server rendered them: version at render and signature. */
+export interface Registration {
+    target: string;
+    names: Record<string, [version: number, signature: string]>;
+}
+/** Register what a rendered region is live on; the returned function forgets it. */
+export declare function register(entry: Registration): () => void;
+/** For tests. */
+export declare function resetChanges(): void;

package/dist/js/changesStore.js

@@ -0,0 +1,145 @@
+// The tab's side of live sections: what the page is showing, on one stream.
+//
+// Every section or page rendered with `live` registers its names here, with
+// the version each was at and its signature. The union is what the stream
+// watches; a version that moved refreshes exactly the regions live on that
+// name, through the same refresh() a page calls itself. One stream per tab
+// however many regions, reopened only when the set of names changes, closed
+// while the tab is hidden and caught up when it is seen again.
+import { refresh } from "./router";
+const CHANGES_PATH = "/_rsc/changes";
+const registrations = new Set();
+let source = null;
+let openedWith = "";
+let settle;
+let retry;
+let failures = 0;
+let listening = false;
+/** Register what a rendered region is live on; the returned function forgets it. */
+export function register(entry) {
+    registrations.add(entry);
+    schedule();
+    return () => {
+        registrations.delete(entry);
+        schedule();
+    };
+}
+function listen() {
+    if (listening || typeof document === "undefined")
+        return;
+    listening = true;
+    document.addEventListener("visibilitychange", () => document.hidden ? close() : schedule());
+    window.addEventListener("online", schedule);
+}
+/** Many regions register in one commit; one reconcile serves them all. */
+function schedule() {
+    listen();
+    clearTimeout(settle);
+    settle = setTimeout(reconcile, 20);
+}
+/** Every name any region is live on, at the lowest version held - the one furthest behind decides. */
+function union() {
+    const held = new Map();
+    for (const { names } of registrations) {
+        for (const [name, [version, signature]] of Object.entries(names)) {
+            const seen = held.get(name);
+            if (!seen || version < seen[0])
+                held.set(name, [version, signature]);
+        }
+    }
+    return [...held]
+        .map(([name, [version, signature]]) => [
+        name,
+        version,
+        signature,
+    ])
+        .sort((a, b) => (a[0] < b[0] ? -1 : 1));
+}
+function reconcile() {
+    const entries = union();
+    if (entries.length === 0 ||
+        (typeof document !== "undefined" && document.hidden) ||
+        typeof EventSource === "undefined") {
+        close();
+        return;
+    }
+    const key = JSON.stringify(entries);
+    // Something changed: a region came or went, or one re-rendered at a new
+    // version. Either way the set is new, and a failed stream gets a fresh try.
+    if (key !== openedWith)
+        failures = 0;
+    if (source && key === openedWith)
+        return;
+    open(key, entries);
+}
+function open(key, entries) {
+    close();
+    openedWith = key;
+    const stream = new EventSource(CHANGES_PATH + "?w=" + encodeURIComponent(JSON.stringify(entries)));
+    source = stream;
+    stream.onopen = () => {
+        failures = 0;
+    };
+    stream.onmessage = (event) => {
+        let moved;
+        try {
+            moved = JSON.parse(event.data);
+        }
+        catch {
+            return;
+        }
+        if (typeof moved.name === "string" && typeof moved.version === "number")
+            apply(moved.name, moved.version);
+    };
+    stream.onerror = () => {
+        // CONNECTING: the browser is retrying a dropped connection itself. CLOSED:
+        // an error answer - a 403 for names signed by another deploy, a 502 - and
+        // only a new stream comes back. Three in a row and the page is left alone
+        // until something re-renders and registers afresh.
+        if (stream.readyState !== EventSource.CLOSED)
+            return;
+        stream.close();
+        if (source === stream)
+            source = null;
+        if (++failures > 3)
+            return;
+        retry = setTimeout(() => open(openedWith, entries), Math.min(30_000, 1000 * 2 ** (failures - 1)));
+    };
+}
+function close() {
+    clearTimeout(retry);
+    source?.close();
+    source = null;
+    openedWith = "";
+}
+let pending = null;
+/** A version moved: every region live on the name at another version refreshes, once per tick. */
+function apply(name, version) {
+    for (const entry of registrations) {
+        const held = entry.names[name];
+        if (!held || held[0] === version)
+            continue;
+        held[0] = version;
+        (pending ??= new Set()).add(entry.target);
+    }
+    if (!pending)
+        return;
+    queueMicrotask(() => {
+        const targets = pending;
+        pending = null;
+        if (!targets)
+            return;
+        // The page re-renders its sections with it, so refreshing both is twice.
+        const run = targets.has("page") ? ["page"] : [...targets];
+        for (const target of run)
+            void refresh(target).catch(() => { });
+    });
+}
+/** For tests. */
+export function resetChanges() {
+    registrations.clear();
+    close();
+    failures = 0;
+    pending = null;
+}
+//# sourceMappingURL=changesStore.js.map

package/dist/js/changesStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changesStore.js","sourceRoot":"","sources":["../../src/js/changesStore.ts"],"names":[],"mappings":"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","sourcesContent":["// The tab's side of live sections: what the page is showing, on one stream.\n//\n// Every section or page rendered with `live` registers its names here, with\n// the version each was at and its signature. The union is what the stream\n// watches; a version that moved refreshes exactly the regions live on that\n// name, through the same refresh() a page calls itself. One stream per tab\n// however many regions, reopened only when the set of names changes, closed\n// while the tab is hidden and caught up when it is seen again.\n\nimport { refresh } from \"./router\";\n\n/** The names a region is live on, as the server rendered them: version at render and signature. */\nexport interface Registration {\n  target: string;\n  names: Record<string, [version: number, signature: string]>;\n}\n\nconst CHANGES_PATH = \"/_rsc/changes\";\n\nconst registrations = new Set<Registration>();\n\nlet source: EventSource | null = null;\nlet openedWith = \"\";\nlet settle: ReturnType<typeof setTimeout> | undefined;\nlet retry: ReturnType<typeof setTimeout> | undefined;\nlet failures = 0;\nlet listening = false;\n\n/** Register what a rendered region is live on; the returned function forgets it. */\nexport function register(entry: Registration): () => void {\n  registrations.add(entry);\n  schedule();\n\n  return () => {\n    registrations.delete(entry);\n    schedule();\n  };\n}\n\nfunction listen(): void {\n  if (listening || typeof document === \"undefined\") return;\n\n  listening = true;\n  document.addEventListener(\"visibilitychange\", () =>\n    document.hidden ? close() : schedule(),\n  );\n  window.addEventListener(\"online\", schedule);\n}\n\n/** Many regions register in one commit; one reconcile serves them all. */\nfunction schedule(): void {\n  listen();\n  clearTimeout(settle);\n  settle = setTimeout(reconcile, 20);\n}\n\n/** Every name any region is live on, at the lowest version held - the one furthest behind decides. */\nfunction union(): [string, number, string][] {\n  const held = new Map<string, [number, string]>();\n\n  for (const { names } of registrations) {\n    for (const [name, [version, signature]] of Object.entries(names)) {\n      const seen = held.get(name);\n\n      if (!seen || version < seen[0]) held.set(name, [version, signature]);\n    }\n  }\n\n  return [...held]\n    .map(([name, [version, signature]]): [string, number, string] => [\n      name,\n      version,\n      signature,\n    ])\n    .sort((a, b) => (a[0] < b[0] ? -1 : 1));\n}\n\nfunction reconcile(): void {\n  const entries = union();\n\n  if (\n    entries.length === 0 ||\n    (typeof document !== \"undefined\" && document.hidden) ||\n    typeof EventSource === \"undefined\"\n  ) {\n    close();\n\n    return;\n  }\n\n  const key = JSON.stringify(entries);\n\n  // Something changed: a region came or went, or one re-rendered at a new\n  // version. Either way the set is new, and a failed stream gets a fresh try.\n  if (key !== openedWith) failures = 0;\n  if (source && key === openedWith) return;\n\n  open(key, entries);\n}\n\nfunction open(key: string, entries: [string, number, string][]): void {\n  close();\n  openedWith = key;\n\n  const stream = new EventSource(\n    CHANGES_PATH + \"?w=\" + encodeURIComponent(JSON.stringify(entries)),\n  );\n\n  source = stream;\n\n  stream.onopen = () => {\n    failures = 0;\n  };\n\n  stream.onmessage = (event: MessageEvent) => {\n    let moved: { name?: unknown; version?: unknown };\n\n    try {\n      moved = JSON.parse(event.data as string) as {\n        name?: unknown;\n        version?: unknown;\n      };\n    } catch {\n      return;\n    }\n\n    if (typeof moved.name === \"string\" && typeof moved.version === \"number\")\n      apply(moved.name, moved.version);\n  };\n\n  stream.onerror = () => {\n    // CONNECTING: the browser is retrying a dropped connection itself. CLOSED:\n    // an error answer - a 403 for names signed by another deploy, a 502 - and\n    // only a new stream comes back. Three in a row and the page is left alone\n    // until something re-renders and registers afresh.\n    if (stream.readyState !== EventSource.CLOSED) return;\n\n    stream.close();\n    if (source === stream) source = null;\n    if (++failures > 3) return;\n\n    retry = setTimeout(\n      () => open(openedWith, entries),\n      Math.min(30_000, 1000 * 2 ** (failures - 1)),\n    );\n  };\n}\n\nfunction close(): void {\n  clearTimeout(retry);\n  source?.close();\n  source = null;\n  openedWith = \"\";\n}\n\nlet pending: Set<string> | null = null;\n\n/** A version moved: every region live on the name at another version refreshes, once per tick. */\nfunction apply(name: string, version: number): void {\n  for (const entry of registrations) {\n    const held = entry.names[name];\n\n    if (!held || held[0] === version) continue;\n\n    held[0] = version;\n    (pending ??= new Set()).add(entry.target);\n  }\n\n  if (!pending) return;\n\n  queueMicrotask(() => {\n    const targets = pending;\n\n    pending = null;\n    if (!targets) return;\n\n    // The page re-renders its sections with it, so refreshing both is twice.\n    const run = targets.has(\"page\") ? [\"page\"] : [...targets];\n\n    for (const target of run) void refresh(target as never).catch(() => {});\n  });\n}\n\n/** For tests. */\nexport function resetChanges(): void {\n  registrations.clear();\n  close();\n  failures = 0;\n  pending = null;\n}\n"]}

package/dist/js/refreshOn.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+/** What a section or page refreshes on: names, or a function of its props that makes them. */
+export type RefreshOnList<P> = string[] | ((props: P) => string[] | Promise<string[]>);
+/**
+ * The names a region refreshes on, read for this render and signed for the tab.
+ *
+ * A server component, rendered beside the region: it works out the names
+ * from the props, asks the source what version each is at, and hands them to
+ * the client as `Changes`. Under its own Suspense boundary, so the ask never
+ * holds up the region's paint - the data is what the visitor is waiting on,
+ * not the version numbers behind it.
+ *
+ * Renders nothing when the source cannot answer - a backend that is down
+ * for this one call. The region still renders; it just does not refresh on
+ * its names until the next time it is rendered.
+ */
+export declare function RefreshOn<P>({ target, refreshOn, props, }: {
+    target: string;
+    refreshOn: RefreshOnList<P>;
+    props: P;
+}): ReactNode;

package/dist/js/refreshOn.js

@@ -0,0 +1,53 @@
+import { Suspense, createElement } from "react";
+import { currentPageProps } from "../request";
+import { sign, versionSource } from "../changed";
+import { Changes } from "./Changes";
+/**
+ * The names a region refreshes on, read for this render and signed for the tab.
+ *
+ * A server component, rendered beside the region: it works out the names
+ * from the props, asks the source what version each is at, and hands them to
+ * the client as `Changes`. Under its own Suspense boundary, so the ask never
+ * holds up the region's paint - the data is what the visitor is waiting on,
+ * not the version numbers behind it.
+ *
+ * Renders nothing when the source cannot answer - a backend that is down
+ * for this one call. The region still renders; it just does not refresh on
+ * its names until the next time it is rendered.
+ */
+export function RefreshOn({ target, refreshOn, props, }) {
+    return createElement(Suspense, { fallback: null }, createElement(Resolve, { target, refreshOn, props }));
+}
+const warned = new Set();
+/**
+ * Never throws. An error here would become an error row inside the region's
+ * payload, and the browser decodes that as the region failing - a blank
+ * document for a version lookup that did not go through. Said once per
+ * region instead, and the region renders without refreshing on anything.
+ */
+async function Resolve({ target, refreshOn, props, }) {
+    try {
+        // The page's params and searchParams, under whatever the page passed: a
+        // section rendered by its page is given nothing, and alone is given these.
+        const input = { ...currentPageProps(), ...props };
+        const named = typeof refreshOn === "function" ? await refreshOn(input) : refreshOn;
+        const unique = [...new Set(named)].filter((name) => typeof name === "string" && name !== "");
+        if (unique.length === 0)
+            return null;
+        // -1 is a version nothing is at, so every name comes back with its current version.
+        const versions = await versionSource().changed(Object.fromEntries(unique.map((name) => [name, -1])), 0);
+        const signed = {};
+        for (const name of unique)
+            signed[name] = [versions[name] ?? 0, await sign(name)];
+        return createElement(Changes, { target, names: signed });
+    }
+    catch (error) {
+        if (!warned.has(target)) {
+            warned.add(target);
+            console.warn(`[rsc-kit] what ${JSON.stringify(target)} refreshes on could not be read, so it will not: ` +
+                (error instanceof Error ? error.message : String(error)));
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=refreshOn.js.map

package/dist/js/refreshOn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshOn.js","sourceRoot":"","sources":["../../src/js/refreshOn.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAI,EAC3B,MAAM,EACN,SAAS,EACT,KAAK,GAKN;IACC,OAAO,aAAa,CAClB,QAAQ,EACR,EAAE,QAAQ,EAAE,IAAI,EAAE,EAClB,aAAa,CAAC,OAAgB,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAC9D,CAAC;AACJ,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;AAEjC;;;;;GAKG;AACH,KAAK,UAAU,OAAO,CAAI,EACxB,MAAM,EACN,SAAS,EACT,KAAK,GAKN;IACC,IAAI,CAAC;QACH,wEAAwE;QACxE,2EAA2E;QAC3E,MAAM,KAAK,GAAG,EAAE,GAAG,gBAAgB,EAAE,EAAE,GAAI,KAAgB,EAAO,CAAC;QACnE,MAAM,KAAK,GACT,OAAO,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACvE,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CACvC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,CAClD,CAAC;QAEF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAErC,oFAAoF;QACpF,MAAM,QAAQ,GAAG,MAAM,aAAa,EAAE,CAAC,OAAO,CAC5C,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EACpD,CAAC,CACF,CAAC;QACF,MAAM,MAAM,GAA+B,EAAE,CAAC;QAE9C,KAAK,MAAM,IAAI,IAAI,MAAM;YACvB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAEzD,OAAO,aAAa,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACnB,OAAO,CAAC,IAAI,CACV,kBAAkB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,mDAAmD;gBACzF,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC3D,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["import { Suspense, createElement } from \"react\";\nimport type { ReactNode } from \"react\";\nimport { currentPageProps } from \"../request\";\nimport { sign, versionSource } from \"../changed\";\nimport type { SignedName } from \"../changed\";\nimport { Changes } from \"./Changes\";\n\n/** What a section or page refreshes on: names, or a function of its props that makes them. */\nexport type RefreshOnList<P> =\n  string[] | ((props: P) => string[] | Promise<string[]>);\n\n/**\n * The names a region refreshes on, read for this render and signed for the tab.\n *\n * A server component, rendered beside the region: it works out the names\n * from the props, asks the source what version each is at, and hands them to\n * the client as `Changes`. Under its own Suspense boundary, so the ask never\n * holds up the region's paint - the data is what the visitor is waiting on,\n * not the version numbers behind it.\n *\n * Renders nothing when the source cannot answer - a backend that is down\n * for this one call. The region still renders; it just does not refresh on\n * its names until the next time it is rendered.\n */\nexport function RefreshOn<P>({\n  target,\n  refreshOn,\n  props,\n}: {\n  target: string;\n  refreshOn: RefreshOnList<P>;\n  props: P;\n}): ReactNode {\n  return createElement(\n    Suspense,\n    { fallback: null },\n    createElement(Resolve as never, { target, refreshOn, props }),\n  );\n}\n\nconst warned = new Set<string>();\n\n/**\n * Never throws. An error here would become an error row inside the region's\n * payload, and the browser decodes that as the region failing - a blank\n * document for a version lookup that did not go through. Said once per\n * region instead, and the region renders without refreshing on anything.\n */\nasync function Resolve<P>({\n  target,\n  refreshOn,\n  props,\n}: {\n  target: string;\n  refreshOn: RefreshOnList<P>;\n  props: P;\n}): Promise<ReactNode> {\n  try {\n    // The page's params and searchParams, under whatever the page passed: a\n    // section rendered by its page is given nothing, and alone is given these.\n    const input = { ...currentPageProps(), ...(props as object) } as P;\n    const named =\n      typeof refreshOn === \"function\" ? await refreshOn(input) : refreshOn;\n    const unique = [...new Set(named)].filter(\n      (name) => typeof name === \"string\" && name !== \"\",\n    );\n\n    if (unique.length === 0) return null;\n\n    // -1 is a version nothing is at, so every name comes back with its current version.\n    const versions = await versionSource().changed(\n      Object.fromEntries(unique.map((name) => [name, -1])),\n      0,\n    );\n    const signed: Record<string, SignedName> = {};\n\n    for (const name of unique)\n      signed[name] = [versions[name] ?? 0, await sign(name)];\n\n    return createElement(Changes, { target, names: signed });\n  } catch (error) {\n    if (!warned.has(target)) {\n      warned.add(target);\n      console.warn(\n        `[rsc-kit] what ${JSON.stringify(target)} refreshes on could not be read, so it will not: ` +\n          (error instanceof Error ? error.message : String(error)),\n      );\n    }\n\n    return null;\n  }\n}\n"]}

package/dist/js/section.d.ts

@@ -1,5 +1,14 @@
 import type { ComponentType } from "react";
-export declare function section<P extends Record<string, unknown>>(name: string, Component: ComponentType<P>): ComponentType<P>;
+import type { RefreshOnList } from "./refreshOn";
+export interface SectionOptions<P> {
+    /**
+     * What this section refreshes on: names for the data it shows, or a
+     * function of the section's props - the page's params and searchParams -
+     * that makes them. When one is said to have changed, the section refreshes.
+     */
+    refreshOn?: RefreshOnList<P>;
+}
+export declare function section<P extends Record<string, unknown>>(name: string, Component: ComponentType<P>, options?: SectionOptions<P>): ComponentType<P>;
 /**
  * The component inside a section module, without its boundary.
  *

package/dist/js/section.js

@@ -1,5 +1,6 @@
-import { createElement } from "react";
+import { Fragment, createElement } from "react";
 import { SlotBoundary } from "./SlotBoundary";
+import { RefreshOn } from "./refreshOn";
 /**
  * Mark a region of a page as separately refreshable.
  *
@@ -14,6 +15,13 @@ import { SlotBoundary } from "./SlotBoundary";
  * can address: `Rsc::revalidate('orders')` re-renders this and nothing else,
  * and the answer replaces it in place.
  *
+ * With `refreshOn`, it also says what it depends on, and refreshes itself when
+ * that changes - from a webhook, a job, another visitor - with nothing polling:
+ *
+ *     export default section('repos', Repos, {
+ *       refreshOn: ({ params }) => [`team:${params.team}:repos`],
+ *     })
+ *
  * The name has to be unique within the page. It does not have to be unique in
  * the app: the component is carried on the wrapper it returns, so the server
  * resolves a section through the module the route declares rather than by
@@ -22,17 +30,25 @@ import { SlotBoundary } from "./SlotBoundary";
  */
 /** Where the unwrapped component hangs off the wrapper section() returns. */
 const INNER = Symbol.for('@rsc-kit/core.section-component');
-export function section(name, Component) {
+export function section(name, Component, options = {}) {
+    const { refreshOn } = options;
+    // The names render inside the boundary, with the component, so a refresh -
+    // which renders the inside alone - carries the versions it saw.
+    const Inner = refreshOn
+        ? function RefreshOnSection(props) {
+            return createElement(Fragment, null, createElement(RefreshOn, { key: 'refreshOn', target: name, refreshOn, props }), createElement(Component, { key: 'section', ...props }));
+        }
+        : Component;
     // The boundary wraps the component here rather than at the call site, so a
     // page renders a section exactly like anything else.
     function Section(props) {
         // createElement cannot line its overloads up with a component generic
         // over its own props. The call is the ordinary one.
-        return createElement(SlotBoundary, { name }, createElement(Component, props));
+        return createElement(SlotBoundary, { name }, createElement(Inner, props));
     }
     Section.displayName = `Section(${name})`;
     // Reached through the route's own module, never through a shared map.
-    Section[INNER] = Component;
+    Section[INNER] = Inner;
     return Section;
 }
 /**

package/dist/js/section.js.map

@@ -1 +1 @@
-{"version":3,"file":"section.js","sourceRoot":"","sources":["../../src/js/section.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,6EAA6E;AAC7E,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AAE5D,MAAM,UAAU,OAAO,CACrB,IAAY,EACZ,SAA2B;IAE3B,2EAA2E;IAC3E,qDAAqD;IACrD,SAAS,OAAO,CAAC,KAAQ;QACvB,sEAAsE;QACtE,oDAAoD;QACpD,OAAO,aAAa,CAClB,YAA+C,EAC/C,EAAE,IAAI,EAAE,EACR,aAAa,CAAC,SAAiC,EAAE,KAAc,CAAC,CACjE,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,WAAW,GAAG,WAAW,IAAI,GAAG,CAAC;IACzC,sEAAsE;IACrE,OAA8C,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAEnE,OAAO,OAA2B,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAiB;IAEjB,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAErD,OAAQ,QAA+C,CAAC,KAAK,CAEhD,CAAC;AAChB,CAAC","sourcesContent":["import { createElement } from \"react\";\nimport type { ComponentType, ReactNode } from \"react\";\nimport { SlotBoundary } from \"./SlotBoundary\";\n\n/**\n * Mark a region of a page as separately refreshable.\n *\n * Deliberately not a client module. The boundary it wraps things in is one,\n * but the things it wraps are server components — an async component that\n * fetches its own data. Marking this file \"use client\" would turn every one of\n * them into a client reference, which async components cannot be.\n *\n *     export default section('orders', async function Orders() { ... })\n *\n * The page renders it like any component. What it buys is a name the server\n * can address: `Rsc::revalidate('orders')` re-renders this and nothing else,\n * and the answer replaces it in place.\n *\n * The name has to be unique within the page. It does not have to be unique in\n * the app: the component is carried on the wrapper it returns, so the server\n * resolves a section through the module the route declares rather than by\n * looking the name up in a registry every section in the app also writes to.\n * Two pages may both call theirs 'stats'.\n */\n\n/** Where the unwrapped component hangs off the wrapper section() returns. */\nconst INNER = Symbol.for('@rsc-kit/core.section-component');\n\nexport function section<P extends Record<string, unknown>>(\n  name: string,\n  Component: ComponentType<P>,\n): ComponentType<P> {\n  // The boundary wraps the component here rather than at the call site, so a\n  // page renders a section exactly like anything else.\n  function Section(props: P): ReactNode {\n    // createElement cannot line its overloads up with a component generic\n    // over its own props. The call is the ordinary one.\n    return createElement(\n      SlotBoundary as ComponentType<{ name: string }>,\n      { name },\n      createElement(Component as ComponentType<never>, props as never),\n    );\n  }\n\n  Section.displayName = `Section(${name})`;\n  // Reached through the route's own module, never through a shared map.\n  (Section as unknown as Record<symbol, unknown>)[INNER] = Component;\n\n  return Section as ComponentType<P>;\n}\n\n/**\n * The component inside a section module, without its boundary.\n *\n * Revalidation renders this rather than the wrapper: the client swaps what is\n * inside the boundary, so returning the wrapper would nest a new boundary\n * inside the old one on every refresh.\n *\n * Takes the module's own export rather than a name. A name-keyed registry is\n * written to by every section in the app at bundle load — the generated entry\n * imports them all eagerly — so a lookup by name reached any page's region from\n * any url, bounded only by whatever guard happened to sit on the url asked for.\n */\nexport function sectionComponent(\n  exported: unknown,\n): ComponentType<Record<string, unknown>> | undefined {\n  if (typeof exported !== 'function') return undefined;\n\n  return (exported as unknown as Record<symbol, unknown>)[INNER] as\n    | ComponentType<Record<string, unknown>>\n    | undefined;\n}\n"]}
+{"version":3,"file":"section.js","sourceRoot":"","sources":["../../src/js/section.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,6EAA6E;AAC7E,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AAW5D,MAAM,UAAU,OAAO,CACrB,IAAY,EACZ,SAA2B,EAC3B,OAAO,GAAsB,EAAE;IAE/B,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAE9B,2EAA2E;IAC3E,gEAAgE;IAChE,MAAM,KAAK,GAAqB,SAAS;QACvC,CAAC,CAAC,SAAS,gBAAgB,CAAC,KAAQ;YAChC,OAAO,aAAa,CAClB,QAAQ,EACR,IAAI,EACJ,aAAa,CAAC,SAAiC,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAW,CAAC,EAC/G,aAAa,CAAC,SAAiC,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,GAAI,KAAgB,EAAW,CAAC,CACpG,CAAC;QACJ,CAAC;QACH,CAAC,CAAC,SAAS,CAAC;IAEd,2EAA2E;IAC3E,qDAAqD;IACrD,SAAS,OAAO,CAAC,KAAQ;QACvB,sEAAsE;QACtE,oDAAoD;QACpD,OAAO,aAAa,CAClB,YAA+C,EAC/C,EAAE,IAAI,EAAE,EACR,aAAa,CAAC,KAA6B,EAAE,KAAc,CAAC,CAC7D,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,WAAW,GAAG,WAAW,IAAI,GAAG,CAAC;IACzC,sEAAsE;IACrE,OAA8C,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;IAE/D,OAAO,OAA2B,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAiB;IAEjB,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAErD,OAAQ,QAA+C,CAAC,KAAK,CAEhD,CAAC;AAChB,CAAC","sourcesContent":["import { Fragment, createElement } from \"react\";\nimport type { ComponentType, ReactNode } from \"react\";\nimport { SlotBoundary } from \"./SlotBoundary\";\nimport { RefreshOn } from \"./refreshOn\";\nimport type { RefreshOnList } from \"./refreshOn\";\n\n/**\n * Mark a region of a page as separately refreshable.\n *\n * Deliberately not a client module. The boundary it wraps things in is one,\n * but the things it wraps are server components — an async component that\n * fetches its own data. Marking this file \"use client\" would turn every one of\n * them into a client reference, which async components cannot be.\n *\n *     export default section('orders', async function Orders() { ... })\n *\n * The page renders it like any component. What it buys is a name the server\n * can address: `Rsc::revalidate('orders')` re-renders this and nothing else,\n * and the answer replaces it in place.\n *\n * With `refreshOn`, it also says what it depends on, and refreshes itself when\n * that changes - from a webhook, a job, another visitor - with nothing polling:\n *\n *     export default section('repos', Repos, {\n *       refreshOn: ({ params }) => [`team:${params.team}:repos`],\n *     })\n *\n * The name has to be unique within the page. It does not have to be unique in\n * the app: the component is carried on the wrapper it returns, so the server\n * resolves a section through the module the route declares rather than by\n * looking the name up in a registry every section in the app also writes to.\n * Two pages may both call theirs 'stats'.\n */\n\n/** Where the unwrapped component hangs off the wrapper section() returns. */\nconst INNER = Symbol.for('@rsc-kit/core.section-component');\n\nexport interface SectionOptions<P> {\n  /**\n   * What this section refreshes on: names for the data it shows, or a\n   * function of the section's props - the page's params and searchParams -\n   * that makes them. When one is said to have changed, the section refreshes.\n   */\n  refreshOn?: RefreshOnList<P>;\n}\n\nexport function section<P extends Record<string, unknown>>(\n  name: string,\n  Component: ComponentType<P>,\n  options: SectionOptions<P> = {},\n): ComponentType<P> {\n  const { refreshOn } = options;\n\n  // The names render inside the boundary, with the component, so a refresh -\n  // which renders the inside alone - carries the versions it saw.\n  const Inner: ComponentType<P> = refreshOn\n    ? function RefreshOnSection(props: P): ReactNode {\n        return createElement(\n          Fragment,\n          null,\n          createElement(RefreshOn as ComponentType<never>, { key: 'refreshOn', target: name, refreshOn, props } as never),\n          createElement(Component as ComponentType<never>, { key: 'section', ...(props as object) } as never),\n        );\n      }\n    : Component;\n\n  // The boundary wraps the component here rather than at the call site, so a\n  // page renders a section exactly like anything else.\n  function Section(props: P): ReactNode {\n    // createElement cannot line its overloads up with a component generic\n    // over its own props. The call is the ordinary one.\n    return createElement(\n      SlotBoundary as ComponentType<{ name: string }>,\n      { name },\n      createElement(Inner as ComponentType<never>, props as never),\n    );\n  }\n\n  Section.displayName = `Section(${name})`;\n  // Reached through the route's own module, never through a shared map.\n  (Section as unknown as Record<symbol, unknown>)[INNER] = Inner;\n\n  return Section as ComponentType<P>;\n}\n\n/**\n * The component inside a section module, without its boundary.\n *\n * Revalidation renders this rather than the wrapper: the client swaps what is\n * inside the boundary, so returning the wrapper would nest a new boundary\n * inside the old one on every refresh.\n *\n * Takes the module's own export rather than a name. A name-keyed registry is\n * written to by every section in the app at bundle load — the generated entry\n * imports them all eagerly — so a lookup by name reached any page's region from\n * any url, bounded only by whatever guard happened to sit on the url asked for.\n */\nexport function sectionComponent(\n  exported: unknown,\n): ComponentType<Record<string, unknown>> | undefined {\n  if (typeof exported !== 'function') return undefined;\n\n  return (exported as unknown as Record<symbol, unknown>)[INNER] as\n    | ComponentType<Record<string, unknown>>\n    | undefined;\n}\n"]}

package/dist/js/useEvents.d.ts

@@ -1,14 +1,16 @@
+import type { MessageOf, NamedMessageOf } from "../events.js";
+import type { EventsAt, EventsUrl } from "../routes.js";
 export type EventsStatus = "connecting" | "open" | "closed";
-export interface EventsOptions<T> {
+export interface EventsOptions<T, E extends string | undefined = string | undefined> {
     /** Off, and nothing connects. For a stream that waits on an id. */
     enabled?: boolean;
     /** Listen to one named event rather than the unnamed stream. */
-    event?: string;
+    event?: E;
     /** Every message, as it arrives. */
     onMessage?: (message: T) => void;
     /**
-     * The connection failed or dropped. EventSource reconnects on its own, so
-     * this is for a notice, not a retry; `status` says whether it gave up.
+     * The connection failed or dropped. The hook reconnects on its own, so
+     * this is for a notice, not a retry.
      */
     onError?: (error: Event) => void;
     /** How many messages `all` keeps. Default 100; 0 keeps none. */
@@ -22,4 +24,8 @@ export interface EventsState<T> {
     /** Close the stream for good; the hook will not reconnect. */
     close: () => void;
 }
-export declare function useEvents<T = unknown>(url: string, options?: EventsOptions<T>): EventsState<T>;
+/** What the hook receives from `Y`'s yields: the unnamed messages, or those named `E`. */
+type Received<Y, E> = unknown extends Y ? unknown : E extends string ? NamedMessageOf<Y, E> : MessageOf<Y>;
+export declare function useEvents<const U extends EventsUrl, const E extends string | undefined = undefined>(url: U, options?: EventsOptions<Received<EventsAt<U>, E>, E>): EventsState<Received<EventsAt<U>, E>>;
+export declare function useEvents<T>(url: EventsUrl, options?: EventsOptions<T>): EventsState<T>;
+export {};

package/dist/js/useEvents.js

@@ -4,14 +4,27 @@
  *
  *     const { latest, status } = useEvents(`/api/orders/${id}/events`)
  *
+ * A message is typed from the route: the build records what each `events()`
+ * route yields, so `latest` is what the generator sends, and a route that
+ * changes it fails the typecheck here rather than in the browser. Another
+ * site's stream, or one written without `events()`, is `unknown`; name its
+ * type with `useEvents<Message>(url)`.
+ *
  * Subscribes in an effect, so it is safe in a component that also renders on
- * the server. The browser's EventSource reconnects on its own and resumes
- * with Last-Event-ID when the route yielded ids; `status` says where it is.
+ * the server. The browser's EventSource reconnects on its own after a dropped
+ * connection and resumes with Last-Event-ID when the route yielded ids. What
+ * it does not survive is an error answer - a 502 while a deploy restarts, a
+ * proxy's timeout page - after which it closes for good; the hook opens a new
+ * one, backing off from a second to thirty, and at once when the browser comes
+ * back online. `status` says where it is; `close()` stops it.
+ *
  * `onMessage` is for a store that already holds the value - TanStack's
  * setQueryData, SWR's mutate, a setState - and `latest` for when the hook is
  * the store.
  */
 import { useEffect, useEffectEvent, useRef, useState } from "react";
+/** The longest wait between attempts after the browser gave up. */
+const MAX_BACKOFF_MS = 30_000;
 export function useEvents(url, options = {}) {
     const { enabled = true, event, keep = 100 } = options;
     // Effect Events: the connection is opened once per url, and the handlers
@@ -24,16 +37,17 @@ export function useEvents(url, options = {}) {
     const [all, setAll] = useState([]);
     const [status, setStatus] = useState(enabled ? "connecting" : "closed");
     const [error, setError] = useState(null);
-    const source = useRef(null);
+    // Ends this url's connection and any retry waiting to open the next one.
+    const stop = useRef(null);
     useEffect(() => {
         if (!enabled || typeof EventSource === "undefined") {
             setStatus("closed");
             return;
         }
-        const es = new EventSource(url);
-        source.current = es;
-        setStatus("connecting");
-        setError(null);
+        let es = null;
+        let retry;
+        let failures = 0;
+        let stopped = false;
         const receive = (e) => {
             let message;
             try {
@@ -49,20 +63,55 @@ export function useEvents(url, options = {}) {
                     : [...prev, message]);
             onMessage(message);
         };
-        es.onopen = () => setStatus("open");
-        es.onerror = (e) => {
-            setError(e);
-            onError(e);
-            // EventSource reconnects on its own; CLOSED means it gave up.
-            setStatus(es.readyState === EventSource.CLOSED ? "closed" : "connecting");
+        const connect = () => {
+            clearTimeout(retry);
+            retry = undefined;
+            const source = new EventSource(url);
+            es = source;
+            setStatus("connecting");
+            source.onopen = () => {
+                failures = 0;
+                setError(null);
+                setStatus("open");
+            };
+            source.onerror = (e) => {
+                setError(e);
+                onError(e);
+                // Still CONNECTING: the browser is retrying a dropped connection
+                // itself. CLOSED: it gave up, and only a new EventSource comes back.
+                if (source.readyState !== EventSource.CLOSED) {
+                    setStatus("connecting");
+                    return;
+                }
+                source.close();
+                if (stopped)
+                    return;
+                setStatus("connecting");
+                retry = setTimeout(connect, Math.min(MAX_BACKOFF_MS, 1000 * 2 ** failures++));
+            };
+            if (event)
+                source.addEventListener(event, receive);
+            else
+                source.onmessage = receive;
+        };
+        // Back online: try now rather than at the end of the backoff.
+        const online = () => {
+            if (!stopped && retry !== undefined)
+                connect();
+        };
+        connect();
+        window.addEventListener("online", online);
+        const end = () => {
+            stopped = true;
+            clearTimeout(retry);
+            es?.close();
+            window.removeEventListener("online", online);
         };
-        if (event)
-            es.addEventListener(event, receive);
-        else
-            es.onmessage = receive;
+        stop.current = end;
         return () => {
-            es.close();
-            source.current = null;
+            end();
+            if (stop.current === end)
+                stop.current = null;
         };
     }, [url, enabled, event, keep]);
     return {
@@ -71,8 +120,8 @@ export function useEvents(url, options = {}) {
         status,
         error,
         close: () => {
-            source.current?.close();
-            source.current = null;
+            stop.current?.();
+            stop.current = null;
             setStatus("closed");
         },
     };

package/dist/js/useEvents.js.map

@@ -1 +1 @@
-{"version":3,"file":"useEvents.js","sourceRoot":"","sources":["../../src/js/useEvents.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AA6BpE,MAAM,UAAU,SAAS,CACvB,GAAW,EACX,OAAO,GAAqB,EAAE;IAE9B,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC;IACtD,yEAAyE;IACzE,oEAAoE;IACpE,qEAAqE;IACrE,kCAAkC;IAClC,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,OAAU,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/E,MAAM,OAAO,GAAG,cAAc,CAAC,CAAC,KAAY,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAE3E,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAW,IAAI,CAAC,CAAC;IACrD,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAM,EAAE,CAAC,CAAC;IACxC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAClC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAClC,CAAC;IACF,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,MAAM,CAAqB,IAAI,CAAC,CAAC;IAEhD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO,IAAI,OAAO,WAAW,KAAK,WAAW,EAAE,CAAC;YACnD,SAAS,CAAC,QAAQ,CAAC,CAAC;YAEpB,OAAO;QACT,CAAC;QAED,MAAM,EAAE,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC;QAEhC,MAAM,CAAC,OAAO,GAAG,EAAE,CAAC;QACpB,SAAS,CAAC,YAAY,CAAC,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,MAAM,OAAO,GAAG,CAAC,CAAe,EAAE,EAAE;YAClC,IAAI,OAAU,CAAC;YAEf,IAAI,CAAC;gBACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAM,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,GAAG,CAAC,CAAC,IAAS,CAAC;YACxB,CAAC;YAED,SAAS,CAAC,OAAO,CAAC,CAAC;YACnB,IAAI,IAAI,GAAG,CAAC;gBACV,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,CAAC,MAAM,IAAI,IAAI;oBACjB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;oBAC7B,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CACvB,CAAC;YACJ,SAAS,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC,CAAC;QAEF,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACpC,EAAE,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,EAAE;YACjB,QAAQ,CAAC,CAAC,CAAC,CAAC;YACZ,OAAO,CAAC,CAAC,CAAC,CAAC;YACX,8DAA8D;YAC9D,SAAS,CAAC,EAAE,CAAC,UAAU,KAAK,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QAC5E,CAAC,CAAC;QAEF,IAAI,KAAK;YAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAwB,CAAC,CAAC;;YAC3D,EAAE,CAAC,SAAS,GAAG,OAAO,CAAC;QAE5B,OAAO,GAAG,EAAE;YACV,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAEhC,OAAO;QACL,MAAM;QACN,GAAG;QACH,MAAM;QACN,KAAK;QACL,KAAK,EAAE,GAAG,EAAE;YACV,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;YACxB,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;YACtB,SAAS,CAAC,QAAQ,CAAC,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\n/**\n * A stream of server-sent events, as state.\n *\n *     const { latest, status } = useEvents(`/api/orders/${id}/events`)\n *\n * Subscribes in an effect, so it is safe in a component that also renders on\n * the server. The browser's EventSource reconnects on its own and resumes\n * with Last-Event-ID when the route yielded ids; `status` says where it is.\n * `onMessage` is for a store that already holds the value - TanStack's\n * setQueryData, SWR's mutate, a setState - and `latest` for when the hook is\n * the store.\n */\n\nimport { useEffect, useEffectEvent, useRef, useState } from \"react\";\n\nexport type EventsStatus = \"connecting\" | \"open\" | \"closed\";\n\nexport interface EventsOptions<T> {\n  /** Off, and nothing connects. For a stream that waits on an id. */\n  enabled?: boolean;\n  /** Listen to one named event rather than the unnamed stream. */\n  event?: string;\n  /** Every message, as it arrives. */\n  onMessage?: (message: T) => void;\n  /**\n   * The connection failed or dropped. EventSource reconnects on its own, so\n   * this is for a notice, not a retry; `status` says whether it gave up.\n   */\n  onError?: (error: Event) => void;\n  /** How many messages `all` keeps. Default 100; 0 keeps none. */\n  keep?: number;\n}\n\nexport interface EventsState<T> {\n  latest: T | null;\n  all: T[];\n  status: EventsStatus;\n  error: Event | null;\n  /** Close the stream for good; the hook will not reconnect. */\n  close: () => void;\n}\n\nexport function useEvents<T = unknown>(\n  url: string,\n  options: EventsOptions<T> = {},\n): EventsState<T> {\n  const { enabled = true, event, keep = 100 } = options;\n  // Effect Events: the connection is opened once per url, and the handlers\n  // it calls see the callbacks of the latest render without being the\n  // effect's dependencies - which would reopen the connection on every\n  // render that passed a new arrow.\n  const onMessage = useEffectEvent((message: T) => options.onMessage?.(message));\n  const onError = useEffectEvent((event: Event) => options.onError?.(event));\n\n  const [latest, setLatest] = useState<T | null>(null);\n  const [all, setAll] = useState<T[]>([]);\n  const [status, setStatus] = useState<EventsStatus>(\n    enabled ? \"connecting\" : \"closed\",\n  );\n  const [error, setError] = useState<Event | null>(null);\n  const source = useRef<EventSource | null>(null);\n\n  useEffect(() => {\n    if (!enabled || typeof EventSource === \"undefined\") {\n      setStatus(\"closed\");\n\n      return;\n    }\n\n    const es = new EventSource(url);\n\n    source.current = es;\n    setStatus(\"connecting\");\n    setError(null);\n\n    const receive = (e: MessageEvent) => {\n      let message: T;\n\n      try {\n        message = JSON.parse(e.data) as T;\n      } catch {\n        message = e.data as T;\n      }\n\n      setLatest(message);\n      if (keep > 0)\n        setAll((prev) =>\n          prev.length >= keep\n            ? [...prev.slice(1), message]\n            : [...prev, message],\n        );\n      onMessage(message);\n    };\n\n    es.onopen = () => setStatus(\"open\");\n    es.onerror = (e) => {\n      setError(e);\n      onError(e);\n      // EventSource reconnects on its own; CLOSED means it gave up.\n      setStatus(es.readyState === EventSource.CLOSED ? \"closed\" : \"connecting\");\n    };\n\n    if (event) es.addEventListener(event, receive as EventListener);\n    else es.onmessage = receive;\n\n    return () => {\n      es.close();\n      source.current = null;\n    };\n  }, [url, enabled, event, keep]);\n\n  return {\n    latest,\n    all,\n    status,\n    error,\n    close: () => {\n      source.current?.close();\n      source.current = null;\n      setStatus(\"closed\");\n    },\n  };\n}\n"]}
+{"version":3,"file":"useEvents.js","sourceRoot":"","sources":["../../src/js/useEvents.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\n/**\n * A stream of server-sent events, as state.\n *\n *     const { latest, status } = useEvents(`/api/orders/${id}/events`)\n *\n * A message is typed from the route: the build records what each `events()`\n * route yields, so `latest` is what the generator sends, and a route that\n * changes it fails the typecheck here rather than in the browser. Another\n * site's stream, or one written without `events()`, is `unknown`; name its\n * type with `useEvents<Message>(url)`.\n *\n * Subscribes in an effect, so it is safe in a component that also renders on\n * the server. The browser's EventSource reconnects on its own after a dropped\n * connection and resumes with Last-Event-ID when the route yielded ids. What\n * it does not survive is an error answer - a 502 while a deploy restarts, a\n * proxy's timeout page - after which it closes for good; the hook opens a new\n * one, backing off from a second to thirty, and at once when the browser comes\n * back online. `status` says where it is; `close()` stops it.\n *\n * `onMessage` is for a store that already holds the value - TanStack's\n * setQueryData, SWR's mutate, a setState - and `latest` for when the hook is\n * the store.\n */\n\nimport { useEffect, useEffectEvent, useRef, useState } from \"react\";\nimport type { MessageOf, NamedMessageOf } from \"../events.js\";\nimport type { EventsAt, EventsUrl } from \"../routes.js\";\n\nexport type EventsStatus = \"connecting\" | \"open\" | \"closed\";\n\nexport interface EventsOptions<T, E extends string | undefined = string | undefined> {\n  /** Off, and nothing connects. For a stream that waits on an id. */\n  enabled?: boolean;\n  /** Listen to one named event rather than the unnamed stream. */\n  event?: E;\n  /** Every message, as it arrives. */\n  onMessage?: (message: T) => void;\n  /**\n   * The connection failed or dropped. The hook reconnects on its own, so\n   * this is for a notice, not a retry.\n   */\n  onError?: (error: Event) => void;\n  /** How many messages `all` keeps. Default 100; 0 keeps none. */\n  keep?: number;\n}\n\nexport interface EventsState<T> {\n  latest: T | null;\n  all: T[];\n  status: EventsStatus;\n  error: Event | null;\n  /** Close the stream for good; the hook will not reconnect. */\n  close: () => void;\n}\n\n/** What the hook receives from `Y`'s yields: the unnamed messages, or those named `E`. */\ntype Received<Y, E> = unknown extends Y\n  ? unknown\n  : E extends string\n    ? NamedMessageOf<Y, E>\n    : MessageOf<Y>;\n\n/** The longest wait between attempts after the browser gave up. */\nconst MAX_BACKOFF_MS = 30_000;\n\nexport function useEvents<const U extends EventsUrl, const E extends string | undefined = undefined>(\n  url: U,\n  options?: EventsOptions<Received<EventsAt<U>, E>, E>,\n): EventsState<Received<EventsAt<U>, E>>;\nexport function useEvents<T>(url: EventsUrl, options?: EventsOptions<T>): EventsState<T>;\nexport function useEvents<T>(\n  url: string,\n  options: EventsOptions<T> = {},\n): EventsState<T> {\n  const { enabled = true, event, keep = 100 } = options;\n  // Effect Events: the connection is opened once per url, and the handlers\n  // it calls see the callbacks of the latest render without being the\n  // effect's dependencies - which would reopen the connection on every\n  // render that passed a new arrow.\n  const onMessage = useEffectEvent((message: T) => options.onMessage?.(message));\n  const onError = useEffectEvent((event: Event) => options.onError?.(event));\n\n  const [latest, setLatest] = useState<T | null>(null);\n  const [all, setAll] = useState<T[]>([]);\n  const [status, setStatus] = useState<EventsStatus>(\n    enabled ? \"connecting\" : \"closed\",\n  );\n  const [error, setError] = useState<Event | null>(null);\n  // Ends this url's connection and any retry waiting to open the next one.\n  const stop = useRef<(() => void) | null>(null);\n\n  useEffect(() => {\n    if (!enabled || typeof EventSource === \"undefined\") {\n      setStatus(\"closed\");\n\n      return;\n    }\n\n    let es: EventSource | null = null;\n    let retry: ReturnType<typeof setTimeout> | undefined;\n    let failures = 0;\n    let stopped = false;\n\n    const receive = (e: MessageEvent) => {\n      let message: T;\n\n      try {\n        message = JSON.parse(e.data) as T;\n      } catch {\n        message = e.data as T;\n      }\n\n      setLatest(message);\n      if (keep > 0)\n        setAll((prev) =>\n          prev.length >= keep\n            ? [...prev.slice(1), message]\n            : [...prev, message],\n        );\n      onMessage(message);\n    };\n\n    const connect = () => {\n      clearTimeout(retry);\n      retry = undefined;\n\n      const source = new EventSource(url);\n\n      es = source;\n      setStatus(\"connecting\");\n\n      source.onopen = () => {\n        failures = 0;\n        setError(null);\n        setStatus(\"open\");\n      };\n      source.onerror = (e) => {\n        setError(e);\n        onError(e);\n\n        // Still CONNECTING: the browser is retrying a dropped connection\n        // itself. CLOSED: it gave up, and only a new EventSource comes back.\n        if (source.readyState !== EventSource.CLOSED) {\n          setStatus(\"connecting\");\n\n          return;\n        }\n\n        source.close();\n        if (stopped) return;\n\n        setStatus(\"connecting\");\n        retry = setTimeout(connect, Math.min(MAX_BACKOFF_MS, 1000 * 2 ** failures++));\n      };\n\n      if (event) source.addEventListener(event, receive as EventListener);\n      else source.onmessage = receive;\n    };\n\n    // Back online: try now rather than at the end of the backoff.\n    const online = () => {\n      if (!stopped && retry !== undefined) connect();\n    };\n\n    connect();\n    window.addEventListener(\"online\", online);\n\n    const end = () => {\n      stopped = true;\n      clearTimeout(retry);\n      es?.close();\n      window.removeEventListener(\"online\", online);\n    };\n\n    stop.current = end;\n\n    return () => {\n      end();\n      if (stop.current === end) stop.current = null;\n    };\n  }, [url, enabled, event, keep]);\n\n  return {\n    latest,\n    all,\n    status,\n    error,\n    close: () => {\n      stop.current?.();\n      stop.current = null;\n      setStatus(\"closed\");\n    },\n  };\n}\n"]}

package/dist/request.d.ts

@@ -234,3 +234,14 @@ export declare function requestReadWhere(): string[];
  * asked for.
  */
 export declare function searchParams(): Promise<URLSearchParams>;
+/**
+ * The props the page is being rendered with, for whatever renders inside it.
+ *
+ * A section is rendered by its page with whatever the page passed, which is
+ * usually nothing, and alone - on a refresh - with the page's own props. Its
+ * refreshOn is a function of the page's params either way, so the engine notes
+ * them here and the section reads them back, whichever way it was rendered.
+ */
+export declare function notePageProps(props: Record<string, unknown>): void;
+/** The page's props as noted by the engine; empty outside a page render. */
+export declare function currentPageProps(): Record<string, unknown>;