@nifrajs/web 5.6.0 → 5.7.0

package/src/internal/render-document.ts

@@ -34,6 +34,7 @@ import {
   DATA_GLOBAL,
   HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
+  LIVE_GLOBAL,
   LOCALES_GLOBAL,
   ROOT_ATTRIBUTE,
   ROUTE_GLOBAL,
@@ -45,6 +46,7 @@ import { isStaticMeta, mergeHeads } from "./head-merge.ts"
 import { reportDeferredRejection } from "./request-abort.ts"
 import { PRE_HYDRATION_GUARD } from "./runtime-contract.ts"
 import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./script-types.ts"
+import type { HeadersLike } from "./status-page.ts"
 
 const TEXT_ENCODER = new TextEncoder()
 
@@ -108,6 +110,11 @@ export interface RenderPageOptions {
   /** An action's data return (POST only) - surfaced to the page as `actionData` + serialized
    * for the client so post-POST hydration matches. Omit on GETs. */
   readonly actionData?: unknown
+  /**
+   * A live runtime's seed for this page (`createWebApp({ live })` sets it): handed to the client
+   * entry, which exchanges it for a grant instead of loading the page again.
+   */
+  readonly live?: unknown
   /**
    * URL of the built client entry (loaded as a module script).
    *
@@ -416,6 +423,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     options.serverComponents === undefined
       ? ""
       : `,"__NIFRA_COMPONENTS__":${serializeData(options.serverComponents)}`
+  const liveTail =
+    options.live === undefined ? "" : `,"${LIVE_GLOBAL}":${serializeData(options.live)}`
   const deferredRuntime =
     allDeferred.length > 0 ? `<script${nonceAttr}>${DEFERRED_RUNTIME}</script>` : ""
   // The regex only injects the CSP nonce into the (constant) hydration head; with no nonce it's a
@@ -528,7 +537,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // Tail - the page-state handover + the client module. Module scripts defer (run after parse), so
   // the handover + every streamed deferred resolution are in the document before the entry hydrates.
   const tailHtml = hydrate
-    ? `${slot.tailPre}${serializeData(forClient)}${action}${layoutTail}${boundaryTail}${componentTail}${slot.tailPost}`
+    ? `${slot.tailPre}${serializeData(forClient)}${action}${layoutTail}${boundaryTail}${componentTail}${liveTail}${slot.tailPost}`
     : (slot.tailPost as string)
   const headers: Record<string, string> = { "content-type": "text/html; charset=utf-8" }
   if (locale !== undefined) headers["content-language"] = lang
@@ -941,24 +950,6 @@ export function redirect(location: string, options: RedirectOptions = {}): Respo
   })
 }
 
-/**
- * Brand marking a `Response` as a **terminal-status signal** rather than a response to serve verbatim.
- *
- * A loader that throws a bare `Response` has always been passed straight through - that is how
- * `throw redirect(...)` works, and apps rely on it. So "render the `_404` boundary at 404" cannot be
- * expressed by throwing a plain `Response`: the framework would have no way to tell it apart from a
- * hand-rolled body the app wants served exactly as written. The brand is that distinction, and
- * checking it *before* the pass-through is what keeps every existing throw working unchanged.
- *
- * `Symbol.for` matches `RESPONSE_RESULT` above: a registry symbol survives two copies of this module,
- * which a `unique symbol` would not - and a duplicate-install turning a 404 into a raw 404 body would
- * be a maddening bug to trace.
- */
-/** Derived from the `Headers` constructor rather than the DOM lib's `HeadersInit`: `@nifrajs/web`
- * is consumed from DOM-free programs (the root tsconfig runs `types: ["bun"]`), and naming the DOM
- * type here would break their build. Same workaround as `SSEInit.headers` in core. */
-export type HeadersLike = ConstructorParameters<typeof Headers>[0]
-
 /**
  * The signatures a **duplicate module instance** produces during SSR, across engines.
  *
@@ -1061,8 +1052,6 @@ export const layoutErrorId = (err: unknown): string | undefined =>
     ? ((err as Record<symbol, unknown>)[LAYOUT_ERROR_ID] as string | undefined)
     : undefined
 
-export const STATUS_SIGNAL = Symbol.for("nifra.web.status-signal")
-
 /** Reason phrases for the plain-text fallback, used only when the app authored no `_<status>` and no
  * `_404` page. Deliberately not exhaustive - anything unlisted falls back to "Error", which is more
  * useful than shipping a table of every RFC status for a body almost nobody will see. */
@@ -1077,77 +1066,6 @@ export const STATUS_TEXT: Readonly<Record<number, string>> = {
   500: "Internal Server Error",
 }
 
-export interface StatusSignal extends Response {
-  readonly [STATUS_SIGNAL]: { readonly status: number; readonly headers?: HeadersLike }
-}
-
-export function isStatusSignal(value: unknown): value is StatusSignal {
-  return value instanceof Response && STATUS_SIGNAL in value
-}
-
-function statusSignal(status: number, options: StatusPageOptions): never {
-  if (!Number.isInteger(status) || status < 400 || status > 599) {
-    throw new Error(
-      `[nifra/web] statusPage(${JSON.stringify(status)}) must be an integer 4xx or 5xx status. Use redirect() for 3xx, and return data for a successful render.`,
-    )
-  }
-  const response = new Response(null, { status })
-  // Non-enumerable so the brand never lands in a structured clone or a JSON log of the response.
-  Object.defineProperty(response, STATUS_SIGNAL, {
-    value: { status, ...(options.headers !== undefined ? { headers: options.headers } : {}) },
-    enumerable: false,
-  })
-  throw response
-}
-
-/** Options shared by {@link notFound}, {@link gone}, and {@link statusPage}. */
-export interface StatusPageOptions {
-  /**
-   * Extra headers for the rendered response - `cache-control` above all.
-   *
-   * The defaults differ by status for a reason: a 404 may be a race with publication, so it wants a
-   * short TTL, while a 410 is a promise that the URL is permanently gone and can be cached hard.
-   * Getting this wrong is the difference between a crawler dropping a dead URL and re-fetching it
-   * for weeks.
-   */
-  readonly headers?: HeadersLike
-}
-
-/**
- * Render the nearest `_404` page at status **404**. `throw` it from a loader when the record does not
- * exist.
- *
- * This is the fix for the soft 404: a matched route whose loader finds nothing has otherwise no way to
- * answer 404, so the path of least resistance is to return empty data and render "not found" inside a
- * **200**. That looks correct in a browser and is invisible in review, which is why it ships and stays
- * shipped - while search engines penalise it and keep the dead URL indexed.
- *
- * Returns `never`: these throw, so a loader narrows without a redundant `return`, and the type states
- * the thing the "loaders `throw` redirect, actions `return` it" rule already trips people on.
- */
-export function notFound(options: StatusPageOptions = {}): never {
-  return statusSignal(404, options)
-}
-
-/**
- * Render a terminal page at status **410 Gone**. `throw` it from a loader for a record that existed and
- * was deliberately removed - a withdrawn listing, a deleted post.
- *
- * 410 is not a pedantic 404: it tells a crawler to **drop** the URL rather than re-fetch it for weeks
- * on the assumption the 404 was transient. Uses `_410.tsx` if the app has one, otherwise `_404`.
- */
-export function gone(options: StatusPageOptions = {}): never {
-  return statusSignal(410, options)
-}
-
-/**
- * Render a terminal page at any 4xx/5xx status - the escape hatch behind {@link notFound} and
- * {@link gone} (402, 451, …). Uses `_<status>.tsx` if present, otherwise `_404`.
- */
-export function statusPage(status: number, options: StatusPageOptions = {}): never {
-  return statusSignal(status, options)
-}
-
 /** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
  * shape (not a class) so `@nifrajs/client`'s `ActionData` can unwrap it structurally without importing
  * from `@nifrajs/web`. `createWebApp` strips the wrapper - the client receives `data` as the body and

package/src/internal/status-page.ts

@@ -0,0 +1,95 @@
+/**
+ * The terminal-status helpers and their brand, free of server imports: `@nifrajs/web/client` re-exports
+ * them for route helpers the browser also loads, which the root entry would drag `node:crypto` into.
+ */
+
+/** Derived from the `Headers` constructor rather than the DOM lib's `HeadersInit`: `@nifrajs/web`
+ * is consumed from DOM-free programs (the root tsconfig runs `types: ["bun"]`), and naming the DOM
+ * type here would break their build. Same workaround as `SSEInit.headers` in core. */
+export type HeadersLike = ConstructorParameters<typeof Headers>[0]
+
+/**
+ * Brand marking a `Response` as a **terminal-status signal** rather than a response to serve verbatim.
+ *
+ * A loader that throws a bare `Response` has always been passed straight through - that is how
+ * `throw redirect(...)` works, and apps rely on it. So "render the `_404` boundary at 404" cannot be
+ * expressed by throwing a plain `Response`: the framework would have no way to tell it apart from a
+ * hand-rolled body the app wants served exactly as written. The brand is that distinction, and
+ * checking it *before* the pass-through is what keeps every existing throw working unchanged.
+ *
+ * `Symbol.for` matches core's `RESPONSE_RESULT`: a registry symbol survives two copies of this module,
+ * which a `unique symbol` would not - and a duplicate-install turning a 404 into a raw 404 body would
+ * be a maddening bug to trace.
+ */
+export const STATUS_SIGNAL = Symbol.for("nifra.web.status-signal")
+
+export interface StatusSignal extends Response {
+  readonly [STATUS_SIGNAL]: { readonly status: number; readonly headers?: HeadersLike }
+}
+
+export function isStatusSignal(value: unknown): value is StatusSignal {
+  return value instanceof Response && STATUS_SIGNAL in value
+}
+
+function statusSignal(status: number, options: StatusPageOptions): never {
+  if (!Number.isInteger(status) || status < 400 || status > 599) {
+    throw new Error(
+      `[nifra/web] statusPage(${JSON.stringify(status)}) must be an integer 4xx or 5xx status. Use redirect() for 3xx, and return data for a successful render.`,
+    )
+  }
+  const response = new Response(null, { status })
+  // Non-enumerable so the brand never lands in a structured clone or a JSON log of the response.
+  Object.defineProperty(response, STATUS_SIGNAL, {
+    value: { status, ...(options.headers !== undefined ? { headers: options.headers } : {}) },
+    enumerable: false,
+  })
+  throw response
+}
+
+/** Options shared by {@link notFound}, {@link gone}, and {@link statusPage}. */
+export interface StatusPageOptions {
+  /**
+   * Extra headers for the rendered response - `cache-control` above all.
+   *
+   * The defaults differ by status for a reason: a 404 may be a race with publication, so it wants a
+   * short TTL, while a 410 is a promise that the URL is permanently gone and can be cached hard.
+   * Getting this wrong is the difference between a crawler dropping a dead URL and re-fetching it
+   * for weeks.
+   */
+  readonly headers?: HeadersLike
+}
+
+/**
+ * Render the nearest `_404` page at status **404**. `throw` it from a loader when the record does not
+ * exist.
+ *
+ * This is the fix for the soft 404: a matched route whose loader finds nothing has otherwise no way to
+ * answer 404, so the path of least resistance is to return empty data and render "not found" inside a
+ * **200**. That looks correct in a browser and is invisible in review, which is why it ships and stays
+ * shipped - while search engines penalise it and keep the dead URL indexed.
+ *
+ * Returns `never`: these throw, so a loader narrows without a redundant `return`, and the type states
+ * the thing the "loaders `throw` redirect, actions `return` it" rule already trips people on.
+ */
+export function notFound(options: StatusPageOptions = {}): never {
+  return statusSignal(404, options)
+}
+
+/**
+ * Render a terminal page at status **410 Gone**. `throw` it from a loader for a record that existed and
+ * was deliberately removed - a withdrawn listing, a deleted post.
+ *
+ * 410 is not a pedantic 404: it tells a crawler to **drop** the URL rather than re-fetch it for weeks
+ * on the assumption the 404 was transient. Uses `_410.tsx` if the app has one, otherwise `_404`.
+ */
+export function gone(options: StatusPageOptions = {}): never {
+  return statusSignal(410, options)
+}
+
+/**
+ * Render a terminal page at any 4xx/5xx status - the escape hatch behind {@link notFound} and
+ * {@link gone} (402, 451, …). Uses `_<status>.tsx` if present, otherwise `_404`.
+ */
+export function statusPage(status: number, options: StatusPageOptions = {}): never {
+  return statusSignal(status, options)
+}

package/src/internal/web-app.ts

@@ -299,8 +299,9 @@ export interface CreateWebAppOptions<Env = unknown> {
   /**
    * Which cookies say who is signed in, for an app with a `keepAlive` route. A response that changes
    * or deletes one rotates the readable identity epoch cookie, and every tab drops the pages it kept
-   * for the previous visitor. The session cookies of `@nifrajs/auth`, Better Auth and Auth.js count
-   * under their default names; name any other in `identityCookies`. Development reports, once per
+   * for the previous visitor. The session cookies of `@nifrajs/auth` and Auth.js count under their
+   * default names, Better Auth's under any `cookiePrefix`; name any other in `identityCookies`. An app
+   * run by `nifra dev` and `nifra build` exports this from `backend/framework.ts`. Development reports, once per
    * name, an `HttpOnly` cookie that changes and is in neither list (`NIFRA_KEEPALIVE_IDENTITY_COOKIE`).
    */
   readonly keepAlive?: KeepAliveServerOptions
@@ -654,6 +655,7 @@ export function createWebApp<Env = unknown>(
     ...(ppr === undefined ? {} : { ppr }),
     invalidate,
     liveLoadOf: liveAttachment?.loadOf,
+    liveSeedOf: liveAttachment?.seedOf,
   })
   if (ppr !== undefined) {
     Object.defineProperty(app, PPR_SERVER, { value: ppr.server })

package/src/keep-alive.ts

@@ -106,6 +106,7 @@ interface Kept {
   readonly page: KeptPage
   readonly index: number
   readonly epoch: string
+  readonly identity: number
   readonly sources: Sources
   readonly hiddenAt: number
   readonly maxAge: number
@@ -118,6 +119,7 @@ interface Active {
   readonly index: number
   readonly settled: RouterState
   readonly epoch: string
+  readonly identity: number
   readonly sources: Sources
 }
 
@@ -281,6 +283,8 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
     const wrappedFetchers = new Map<string, Fetcher>()
     let keptPages: readonly KeptPage[] | undefined
     let lastEpoch = readEpoch()
+    // Explicit identity signals also cover bearer auth, where the cookie never changes.
+    let identity = 0
 
     const first = readEntry()
     const initial = inner.snapshot()
@@ -294,10 +298,13 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
       index: first.index,
       settled: initial,
       epoch: lastEpoch,
+      identity,
       sources: sourcesOf(initial),
     }
     stampEntry(active.instance)
-    if (typeof process !== "undefined" && process.env.NODE_ENV !== "production")
+    // Browser-only code reads `process.env.NODE_ENV` bare: every bundler replaces it, but none replaces
+    // `typeof process`, and a browser has no `process`, so that guard turned these off in Vite dev.
+    if (process.env.NODE_ENV !== "production")
       Reflect.set(globalThis, KEPT_PAGES_GLOBAL, {
         pages: () => describeKept(records.values()),
       })
@@ -385,8 +392,15 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
       dropKept("identity")
     }
 
-    const keep = ({ instance, index, settled: state, epoch, sources }: Active): void => {
-      if (!keepable(state) || epoch !== readEpoch()) return
+    const keep = ({
+      instance,
+      index,
+      settled: state,
+      epoch,
+      identity: loadedIdentity,
+      sources,
+    }: Active): void => {
+      if (!keepable(state) || epoch !== readEpoch() || loadedIdentity !== identity) return
       const setting = keepAliveOf(state.routeId)
       const settings = typeof setting === "object" ? setting : {}
       records.delete(instance)
@@ -394,6 +408,7 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
         page: { instance, state },
         index,
         epoch,
+        identity: loadedIdentity,
         sources,
         hiddenAt: now(),
         maxAge: settings.maxAge ?? KEEP_ALIVE_MAX_AGE_MS,
@@ -404,8 +419,13 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
       if (records.size > max) drop([...records.keys()].slice(0, records.size - max), "lru")
     }
 
+    let loading: { readonly identity: number; readonly epoch: string } | undefined
+
     const settle = (next: RouterState): void => {
       const entry = readEntry()
+      const loadedIdentity = loading?.identity ?? identity
+      const loadedEpoch = loading?.epoch ?? readEpoch()
+      loading = undefined
       if (sameInstance(active.settled, next)) {
         // Data the router did not load again is still the data it was loaded with.
         const same = next.data === active.settled.data
@@ -413,7 +433,8 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
           instance: active.instance,
           index: entry.index,
           settled: next,
-          epoch: same ? active.epoch : readEpoch(),
+          epoch: same ? active.epoch : loadedEpoch,
+          identity: same ? active.identity : loadedIdentity,
           sources: same ? active.sources : sourcesOf(next),
         }
       } else {
@@ -437,7 +458,8 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
           instance: reuse ?? newInstance(),
           index: entry.index,
           settled: next,
-          epoch: readEpoch(),
+          epoch: loadedEpoch,
+          identity: loadedIdentity,
           sources: sourcesOf(next),
         }
       }
@@ -488,7 +510,10 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
             instance: active.instance,
             index: active.index,
             settled: next,
-            epoch: restore.reload ? readEpoch() : active.epoch,
+            // The epoch and identity the restore started under: a reload's response, or the kept
+            // response a failed reload falls back to, never belongs to a visitor who arrived since.
+            epoch: active.epoch,
+            identity: active.identity,
             // A reload that failed shows the kept data, from the kept sources.
             sources: sourcesOf(next) ?? active.sources,
           }
@@ -504,6 +529,8 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
         settle(next)
         return
       }
+      // A response belongs to the identity that started its load, not the visitor at arrival.
+      loading ??= { identity, epoch: readEpoch() }
       shown = next
       flags = undefined
       leaving = next.routeId !== active.settled.routeId && !leftGone && keepable(active.settled)
@@ -511,13 +538,21 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
     })
 
     const restore = (path: string, instance: string, record: Kept): Promise<void> => {
+      loading = undefined
       const entry = readEntry()
       records.delete(instance)
       keptPages = undefined
       if (!leftGone) keep(active)
       const kept = record.page.state
       const { sources } = record
-      active = { instance, index: entry.index, settled: kept, epoch: record.epoch, sources }
+      active = {
+        instance,
+        index: entry.index,
+        settled: kept,
+        epoch: record.epoch,
+        identity: record.identity,
+        sources,
+      }
       fresh.clear()
       // Data a client loader built is shown again only from what it was built from.
       const unsourced =
@@ -572,6 +607,7 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
           return restore(path, instance, record)
       }
       endRestore()
+      loading = { identity, epoch: readEpoch() }
       return inner.navigate(path)
     }
 
@@ -594,6 +630,7 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
       typeof BroadcastChannel === "undefined" ? undefined : new BroadcastChannel(IDENTITY_CHANNEL)
     const identityDrop = (): void => {
       lastEpoch = readEpoch()
+      identity++
       dropKept("identity")
     }
     channel?.addEventListener("message", identityDrop)
@@ -629,9 +666,14 @@ export function keepAliveClient(options: KeepAliveClientOptions): KeepAliveClien
       invalidate: (paths) => {
         markStale(paths)
         // At once when nothing is restoring: the live client names its load around this call.
-        return restoring === undefined
-          ? inner.invalidate(paths)
-          : afterRestore().then(() => inner.invalidate(paths))
+        const invalidate = (): Promise<void> => {
+          const capture = { identity, epoch: readEpoch() }
+          loading = capture
+          return inner.invalidate(paths).finally(() => {
+            if (loading === capture) loading = undefined
+          })
+        }
+        return restoring === undefined ? invalidate() : afterRestore().then(invalidate)
       },
       prefetch: (path) => inner.prefetch(path),
       fetcher: (key) => {
@@ -1104,8 +1146,7 @@ export function createSlotParking(): SlotParking {
         ref = (element) => {
           if (element === null) return
           slotOf(key).page = element
-          if (typeof process !== "undefined" && process.env.NODE_ENV !== "production")
-            noteKeptView(key, () => [element])
+          if (process.env.NODE_ENV !== "production") noteKeptView(key, () => [element])
         }
         pageRefs.set(key, ref)
       }
@@ -1162,8 +1203,7 @@ export function createSlotParking(): SlotParking {
         slot.focus = undefined
         if (!slot.shown && !slot.checked) {
           slot.checked = true
-          if (typeof process !== "undefined" && process.env.NODE_ENV !== "production")
-            checkSlotCss(slot.entry, page)
+          if (process.env.NODE_ENV !== "production") checkSlotCss(slot.entry, page)
         }
         slot.shown = true
       }
@@ -1174,8 +1214,7 @@ export function createSlotParking(): SlotParking {
         slots.delete(key)
         entryRefs.delete(key)
         pageRefs.delete(key)
-        if (typeof process !== "undefined" && process.env.NODE_ENV !== "production")
-          noteKeptView(key, undefined)
+        if (process.env.NODE_ENV !== "production") noteKeptView(key, undefined)
       }
     },
   }

package/src/live/bus.ts

@@ -7,6 +7,8 @@
  * keeps counting upward, and an entry's age can be read off its seq.
  */
 
+import { KEY_PATTERN } from "./keyring.ts"
+
 /** Something a loader declared with `ctx.live` changed. */
 export interface LiveChange {
   readonly type: "change"
@@ -35,8 +37,11 @@ export interface LiveBusListener {
    * unknown, and delivery resumes with the events after it.
    */
   gap(head: number): void
-  /** The bus is unreachable; the next {@link gap} reports where delivery resumes. */
-  down(): void
+  /**
+   * The bus is unreachable; the next {@link gap} reports where delivery resumes. `error` is what the
+   * last read failed with, when the bus knows.
+   */
+  down(error?: unknown): void
 }
 
 export interface LiveBusSubscription {
@@ -75,3 +80,25 @@ export function memoryBus(): LiveBus {
     },
   }
 }
+
+/**
+ * Publish changes from a process that serves no live pages: a worker, or another app whose writes
+ * change what the pages show. Give it the bus the serving processes read; each applies the change as
+ * if it had published it. It needs no grant secret, and reads nothing from the bus.
+ *
+ * ```ts
+ * const publish = livePublisher(redisLiveBus({ send: (command, args) => redis.call(command, ...args) }))
+ * await publish(`org:${orgId}:usage`)
+ * ```
+ */
+export function livePublisher(bus: Pick<LiveBus, "append">): (...keys: string[]) => Promise<void> {
+  return async (...keys) => {
+    for (const key of keys) {
+      if (typeof key !== "string" || !KEY_PATTERN.test(key)) {
+        throw new TypeError("[nifra/web] livePublisher takes keys in the ctx.live() charset")
+      }
+    }
+    if (keys.length === 0) return
+    await bus.append({ type: "change", keys: [...new Set(keys)] })
+  }
+}

package/src/live/hub.ts

@@ -18,6 +18,8 @@ export const CLOSE_REVOKED = 4403
 export const CLOSE_SCOPE = 4409
 export const CLOSE_CAPACITY = 1013
 export const CLOSE_PROTOCOL = 1008
+/** The runtime closed: reconnect, most likely to another process. */
+export const CLOSE_GOING_AWAY = 1001
 /** Nothing to watch: a tab with no tag to hear about reconnects only once it has one. */
 export const CLOSE_UNWATCHED = 1000
 
@@ -119,6 +121,8 @@ interface Pending {
 export class LiveHub {
   /** Bus unreachable: no watch is accepted and no socket kept. */
   down = false
+  /** `changed` frames sent, one per subscribed socket: each makes a page reload. */
+  notified = 0
   private readonly sockets = new Set<NifraWebSocket<LiveSocket>>()
   /** Local subscribers per tag: the intern table, and the input to `spread`. */
   private readonly members = new Map<string, number>()
@@ -416,6 +420,7 @@ export class LiveHub {
     for (const tag of tags) {
       const subscribers = this.members.get(tag)
       if (subscribers === undefined) continue
+      this.notified += subscribers
       const frame = JSON.stringify({ t: "changed", tag, spread: this.spread(subscribers) })
       for (const publish of this.publishers) publish(this.topic(tag), frame)
     }

package/src/live/keyring.ts

@@ -18,6 +18,11 @@ export const MAX_KEYS_PER_FRAME = 64
 /** The cache-tag charset: a letter, then up to 127 of `A-Z a-z 0-9 . _ : / -`. */
 export const KEY_PATTERN = /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/
 export const SID_PATTERN = /^[0-9a-f]{32}$/
+/**
+ * The socket id of a seed: the grant a server-rendered page carries before it has a socket. No socket
+ * has it, so no watch accepts a seed; the load endpoint exchanges one for a grant bound to a socket.
+ */
+export const SEED_SID = ""
 
 const KID_BYTES = 16
 const NONCE_BYTES = 12
@@ -309,7 +314,7 @@ function validClaims(
   if (!isRecord(value)) return false
   const { v, sid, sub, path, frame, owners, s, r, iat, exp, aud } = value
   if (v !== 1 || aud !== appId) return false
-  if (typeof sid !== "string" || !SID_PATTERN.test(sid)) return false
+  if (typeof sid !== "string" || (sid !== SEED_SID && !SID_PATTERN.test(sid))) return false
   if (sub !== null && typeof sub !== "string") return false
   if (typeof path !== "string" || typeof frame !== "string") return false
   if (!isCount(s) || !isCount(r) || !isInteger(iat) || !isInteger(exp)) return false