@nifrajs/web 5.6.0 → 5.8.0

package/src/live-client.ts

@@ -69,6 +69,8 @@ const CONNECTS_BEFORE_POLLING = 3
 const MAX_SPREAD_MS = 5_000
 const PAGE = "page"
 const SID = /^[0-9a-f]{32}$/
+/** The socket id of a seed: the grant the server rendered the page with, bound to no socket yet. */
+const SEED = ""
 
 /**
  * What a live load handed the router, carried in its state beside the data it loaded. A load whose
@@ -124,6 +126,8 @@ interface Frame {
   dirty: Set<string>
   /** Every owner reloads: there is no grant to keep any of them by. */
   whole: boolean
+  /** The frame holds a seed and a socket is open: one load keeping every owner trades it for a grant. */
+  exchange: boolean
   /** The watch generation that installed this frame's grant, once `ready` confirmed it. */
   installed: boolean
   /** Set while a watch carrying this frame's grant waits for its `ready`. */
@@ -247,7 +251,10 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
         if (id !== undefined && page?.dirty.has(`L:${id}`) === false) retain.push(`L:${id}`)
       }
     }
-    const grant = held?.grant !== undefined && held.sid === bound ? held.grant : undefined
+    const grant =
+      held?.grant !== undefined && (held.sid === bound || held.sid === SEED)
+        ? held.grant
+        : undefined
     const res = await send(appUrl(loadPath), {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -323,6 +330,30 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
     }
   }
 
+  /**
+   * The server-rendered page's seed, in the router's initial state: held as the page's load, it is
+   * traded for a socket's grant once one opens. Anything else there is ignored.
+   */
+  const adoptSeed = (state: { readonly routeId: string; readonly live?: unknown }): void => {
+    const value = state.live
+    if (typeof value !== "object" || value === null || issued.has(value)) return
+    const live = envelopeOf(value)
+    if (live?.grant === undefined) return
+    const loaded: Loaded = {
+      routeId: state.routeId,
+      sid: SEED,
+      grant: undefined,
+      tags: new Map(),
+      expiresAt: Number.POSITIVE_INFINITY,
+      ttlMs: Number.POSITIVE_INFINITY,
+      tick: advanceLiveTick(),
+      query: undefined,
+      trailing: false,
+    }
+    settleLoaded(loaded, live)
+    issued.set(value, loaded)
+  }
+
   /** A trailing grant arrived, or will not: the frame holding `loaded` watches or polls from now. */
   const granted = (loaded: Loaded, live: ServerEnvelope | undefined): void => {
     settleLoaded(loaded, live)
@@ -367,6 +398,7 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
       shownAt: now,
       dirty: new Set(),
       whole: false,
+      exchange: false,
       installed: false,
       pending: undefined,
       loading: false,
@@ -416,7 +448,9 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
         !tried.has(`${sid}\n${frame.path}`)
       ) {
         tried.add(`${sid}\n${frame.path}`)
-        frame.whole = true
+        // A seed needs no loader to run: the server keeps every owner and binds a grant to this socket.
+        if (frame.loaded?.sid === SEED) frame.exchange = true
+        else frame.whole = true
         // A new socket is a new chance: no backoff carries over, only the spread it was given.
         frame.failures = 0
         frame.retryAt = welcomeSpread > 0 ? now + Math.random() * welcomeSpread : 0
@@ -450,7 +484,7 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
     const now = Date.now()
     for (const frame of frames) {
       if (frame.loading || wakeOf(frame) > now) continue
-      if (frame.whole || frame.dirty.size > 0) reload(frame, "load")
+      if (frame.whole || frame.exchange || frame.dirty.size > 0) reload(frame, "load")
       else if (watchable(frame)) reload(frame, "renew")
       else reload(frame, "load", true)
       // One load at a time: the router runs it, and its next state runs this again.
@@ -465,7 +499,7 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
    */
   const wakeOf = (frame: Frame): number => {
     let due: number
-    if (frame.whole || frame.dirty.size > 0) due = 0
+    if (frame.whole || frame.exchange || frame.dirty.size > 0) due = 0
     // Its grant trails the holes still loading; it arrives with or without one, and runs this again.
     else if (frame.loaded?.trailing === true) due = Number.POSITIVE_INFINITY
     // A renewal waits for the pending watch's `ready`, which runs this again.
@@ -494,7 +528,9 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
     const state = current.snapshot()
     const page = frame.slot === PAGE
     const whole = frame.whole
-    const held = whole ? undefined : frame.loaded
+    const exchange = frame.exchange
+    // A poll is for fresh data: no change notice reaches the frame, so no owner can be kept.
+    const held = whole || polled ? undefined : frame.loaded
     intent = {
       path: frame.path,
       mode: held === undefined ? "load" : mode,
@@ -511,6 +547,7 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
     }
     frame.loading = true
     frame.whole = false
+    frame.exchange = false
     let running: Promise<void>
     try {
       running = current.invalidate([frame.path])
@@ -527,8 +564,8 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
       }
       if (!ok && !watchable(frame))
         pollFailures.set(frame.path, (pollFailures.get(frame.path) ?? 0) + 1)
-      // Still no grant to keep an owner by: the retry loads the frame whole again.
-      if (whole) frame.whole = true
+      // Still no grant to keep an owner by, or a seed it could not trade: the retry loads it whole.
+      if (whole || exchange) frame.whole = true
       frame.failures++
       // Backs off to five minutes, never further: a frame that gives up shows stale data for good.
       // A change, a visibility change or a new socket tries again at once.
@@ -843,6 +880,7 @@ export function liveClient(options: LiveClientOptions = {}): LiveClient {
     attach(target) {
       router = target
       stopped = false
+      adoptSeed(target.snapshot())
       const unsubscribe = target.subscribe(reconcile)
       unwatchQueries = watchLiveQueries(scheduleMatch)
       globalThis.document?.addEventListener("visibilitychange", onVisible)

package/src/live-redis.ts

@@ -14,6 +14,15 @@
  *     read: (command, args) => reader.send(command, [...args]),
  *   })
  *   const runtime = live({ secret, subject, bus, instances: 4 })
+ *   app.onStop(async () => {
+ *     await runtime.close() // stops the reader first, so closing its connection is no outage
+ *     reader.close()
+ *     shared.close()
+ *   })
+ *
+ * Any client with a raw-command call fits: with ioredis, `(command, args) => redis.call(command,
+ * ...args)`, the reader on a `redis.duplicate()`. A process that only publishes (a worker, another
+ * app) passes `send` alone and hands the bus to `livePublisher`.
  *
  * Every entry also carries a running count, so a reader that fell behind a trim - or lost the
  * connection - reports the gap instead of skipping what it missed.
@@ -26,8 +35,11 @@ export type RedisCommand = (command: string, args: readonly string[]) => Promise
 export interface RedisLiveBusOptions {
   /** Appends and reads the clock; any connection. */
   readonly send: RedisCommand
-  /** Reads the stream. Its own connection: a blocking `XREAD` holds it. */
-  readonly read: RedisCommand
+  /**
+   * Reads the stream. Its own connection: a blocking `XREAD` holds it. Required to subscribe, so for
+   * `live()`; a process that only appends leaves it out.
+   */
+  readonly read?: RedisCommand
   /** The stream; the clock lives at `<key>:clock`. Default `nifra:live`. */
   readonly key?: string
   /** Entries kept, roughly. Default 100,000, the most the live history keeps. */
@@ -89,9 +101,15 @@ export function redisLiveBus(options: RedisLiveBusOptions): LiveBus {
     },
 
     async subscribe(listener) {
+      const read = options.read
+      if (read === undefined) {
+        throw new TypeError(
+          "[nifra/web] live-redis: subscribing needs `read`, a connection of its own; a bus without one only appends",
+        )
+      }
       const start = await position()
       let closed = false
-      void follow(start.seq, start.n, listener, () => closed)
+      void follow(read, start.seq, start.n, listener, () => closed)
       return {
         head: start.seq,
         close: () => {
@@ -102,6 +120,7 @@ export function redisLiveBus(options: RedisLiveBusOptions): LiveBus {
   }
 
   async function follow(
+    read: RedisCommand,
     head: number,
     count: number,
     listener: LiveBusListener,
@@ -116,22 +135,28 @@ export function redisLiveBus(options: RedisLiveBusOptions): LiveBus {
     let down = false
     while (!isClosed()) {
       let entries: Entry[] | undefined
+      let error: unknown
       try {
         const reply = await within(
-          options.read("XREAD", ["BLOCK", blockMs, "COUNT", "1000", "STREAMS", key, cursor]),
+          read("XREAD", ["BLOCK", blockMs, "COUNT", "1000", "STREAMS", key, cursor]),
           readTimeoutMs,
         )
         entries = reply === null || reply === undefined ? [] : entriesOf(reply)
-      } catch {
+        if (entries === undefined)
+          error = new Error("[nifra/web] live-redis: XREAD replied in no known shape")
+      } catch (failure) {
         entries = undefined
+        error = failure
       }
+      // Closed while the read was blocked: closing its connection next is the caller's shutdown.
+      if (isClosed()) return
       if (entries === undefined) {
         // A reply of no known shape counts as a failed read, so it backs off instead of spinning.
         failures++
         // One failed read may be a hiccup; a second in a row is an outage.
         if (failures === 2) {
           down = true
-          listener.down()
+          listener.down(error)
         }
         await wait(RETRY_MS[Math.min(failures - 1, RETRY_MS.length - 1)] ?? 5_000)
         continue

package/src/live.ts

@@ -14,7 +14,7 @@
  * whole app: every hook, middleware, gate and loader sees the target path, exactly as a navigation.
  * Changes reach open pages over one WebSocket per tab, as opaque tags of the keys they watch.
  */
-import { isSameOriginForm, replacedRequestOf } from "@nifrajs/core/server"
+import { isSameOriginForm, jsonLogger, type Logger, replacedRequestOf } from "@nifrajs/core/server"
 import { websocket } from "@nifrajs/core/ws"
 import {
   LIVE_ATTACH,
@@ -26,10 +26,23 @@ import {
   type LiveRuntimeHandle,
 } from "./internal/live-contract.ts"
 import { queryDigester, querySalt } from "./internal/query-digest.ts"
-import { type LiveBus, type LiveBusEvent, type LiveBusInput, memoryBus } from "./live/bus.ts"
+import {
+  type LiveBus,
+  type LiveBusEvent,
+  type LiveBusInput,
+  type LiveBusSubscription,
+  memoryBus,
+} from "./live/bus.ts"
 import { applyEvent, type LiveCore } from "./live/core.ts"
 import { History, keyHasher } from "./live/history.ts"
-import { CLOSE_CAPACITY, LiveHub, type LiveSocket, tagCache, unref } from "./live/hub.ts"
+import {
+  CLOSE_CAPACITY,
+  CLOSE_GOING_AWAY,
+  LiveHub,
+  type LiveSocket,
+  tagCache,
+  unref,
+} from "./live/hub.ts"
 import {
   HUB_APPEND_PATH,
   HUB_AUTHORITY_PATH,
@@ -52,6 +65,7 @@ import {
   MAX_GRANT_CHARS,
   MAX_KEYS_PER_FRAME,
   type OpenedGrant,
+  SEED_SID,
   SID_PATTERN,
   toBase64Url,
 } from "./live/keyring.ts"
@@ -83,7 +97,7 @@ export type {
   LiveChange,
   LiveRevocation,
 } from "./live/bus.ts"
-export { memoryBus, nextSeq } from "./live/bus.ts"
+export { livePublisher, memoryBus, nextSeq } from "./live/bus.ts"
 
 export interface LiveOptions {
   /**
@@ -148,6 +162,38 @@ export interface LiveOptions {
    * one of them, so leave it off when key names hold anything the viewer should not see.
    */
   readonly queryKeys?: boolean
+  /**
+   * Where the runtime reports what it cannot fix by itself: the bus stopping to answer and answering
+   * again, events lost to a trim, an event it could not apply, a publish it did not read back.
+   * Default `jsonLogger()`; `false` reports nothing. {@link Live.status} has the same state to poll.
+   */
+  readonly logger?: Logger | false
+}
+
+/** What one process's live runtime is doing now; counters run from its start. */
+export interface LiveStatus {
+  /** The keyring is derived and the bus read: grants can be issued. */
+  readonly ready: boolean
+  /**
+   * No grant is issued and no socket kept: the bus (or the Workers hub) is unreachable, or the
+   * runtime was closed. Open pages poll meanwhile.
+   */
+  readonly down: boolean
+  /** Since when `down` has held, in epoch ms. */
+  readonly downSince: number | undefined
+  /** Live sockets open in this process. On Workers the hub holds them, so this is 0. */
+  readonly sockets: number
+  /** Live loads running in this process. */
+  readonly loads: number
+  /** Bus events this process applied. */
+  readonly events: number
+  /** `changed` frames this process sent, one per watching socket: each makes a page reload. */
+  readonly notified: number
+  /**
+   * How long after its append the last event was applied here, in ms. The append time comes from the
+   * bus's clock, so skew between hosts shows in it.
+   */
+  readonly lagMs: number | undefined
 }
 
 /** A live runtime: pass it to `createWebApp({ live })`. */
@@ -170,6 +216,14 @@ export interface Live extends LiveRuntimeHandle {
    * runs that owner's loader, which decides again.
    */
   revokeKey(key: string, subject?: string): Promise<void>
+  /** What this process's runtime is doing now: for a readiness check or metrics. */
+  status(): LiveStatus
+  /**
+   * Stop reading the bus and close every live socket (1001); open pages poll until they reach another
+   * process. Call it before closing the bus's connections, so the reader does not count that as an
+   * outage. A publish after it throws. Idempotent.
+   */
+  close(): Promise<void>
 }
 
 const DEFAULT_LOAD_PATH = "/_nifra/live/load"
@@ -185,6 +239,12 @@ const MAX_HOSTS = 32
 const MAX_HOST_CHARS = 32
 const HOST = /^[a-z0-9-]+$/
 const PAGE_FRAME = "page"
+/**
+ * How old a seed may be when its page exchanges it: the time from the render to the socket's welcome.
+ * The exchanged grant keeps owners no loader re-checked, so this bounds how stale that check is.
+ */
+const SEED_MAX_AGE_SECONDS = 60
+const NO_OWNERS: readonly string[] = []
 /** Renewals re-signed without loaders before one runs them all. */
 const MAX_QUIET_RENEWALS = 2
 /** How long a publish waits to read its own event back; the event is in the log either way. */
@@ -235,7 +295,7 @@ const REFUSE_ALL: RevocationCheck = { grantRevoked: () => true, keyRevoked: () =
 type Queued =
   | { readonly kind: "event"; readonly event: LiveBusEvent }
   | { readonly kind: "gap"; readonly head: number }
-  | { readonly kind: "down" }
+  | { readonly kind: "down"; readonly error: unknown }
 
 /** Create the live runtime for one app. */
 export function live(options: LiveOptions): Live {
@@ -269,6 +329,7 @@ export function live(options: LiveOptions): Live {
   const subjectOf = options.subject
   const queryKeys = options.queryKeys === true
   const production = isProduction()
+  const logger = options.logger === false ? undefined : (options.logger ?? jsonLogger())
   if (hubNamespace !== undefined) {
     if (options.bus !== undefined) {
       throw new TypeError("[nifra/web] live: `hub` and `bus` are exclusive; the hub owns the log")
@@ -291,8 +352,22 @@ export function live(options: LiveOptions): Live {
   const waiters: { readonly seq: number; readonly resolve: () => void }[] = []
   /** A publish already found this process behind the bus; the next applied event clears it. */
   let lagging = false
+  let subscription: LiveBusSubscription | undefined
+  let closed = false
+  let closing: Promise<void> | undefined
+  let closedAt = 0
+  let downSince: number | undefined
+  let events = 0
+  let lagMs: number | undefined
 
   const keyring = createKeyring({ secrets, appId, ttl })
+  let keyringReady = false
+  keyring.then(
+    () => {
+      keyringReady = true
+    },
+    () => {},
+  )
   // One cache for the tags a load hands out and the tags this process's sockets join.
   const tags = keyring.then((ring) => tagCache(ring))
   tags.catch(() => {})
@@ -300,14 +375,16 @@ export function live(options: LiveOptions): Live {
     const ring = await keyring
     // On Workers the hub holds the log: this isolate reads nothing.
     if (hubNamespace !== undefined) return new Promise<Core>(() => {})
-    const subscription = await bus.subscribe({
+    const subscribed = await bus.subscribe({
       event: (event) => enqueue({ kind: "event", event }),
       gap: (head) => enqueue({ kind: "gap", head }),
-      down: () => enqueue({ kind: "down" }),
+      down: (error) => enqueue({ kind: "down", error }),
     })
-    seen = subscription.head
-    const history = new History(subscription.head)
-    const revocations = new Revocations(subscription.head, ttl * 1000)
+    subscription = subscribed
+    if (closed) subscribed.close()
+    seen = subscribed.head
+    const history = new History(subscribed.head)
+    const revocations = new Revocations(subscribed.head, ttl * 1000)
     const hub = new LiveHub(
       ring,
       history,
@@ -326,6 +403,7 @@ export function live(options: LiveOptions): Live {
       publishers,
     )
     core = { ring, history, revocations, hub }
+    if (closed) hub.down = true
     void drain()
     return core
   })()
@@ -385,7 +463,11 @@ export function live(options: LiveOptions): Live {
       await hubCall(namespace, ring, HUB_AUTHORITY_PATH, { subjects, keys }),
     )
     // Unreachable: revocations are unknown, so nothing presented is honored and no grant is issued.
-    if (reply === undefined) return { seq: 0, down: true, revocations: REFUSE_ALL }
+    if (reply === undefined) {
+      downSince ??= Date.now()
+      return { seq: 0, down: true, revocations: REFUSE_ALL }
+    }
+    downSince = undefined
     return { seq: reply.seq, down: false, revocations: new RevocationView(reply) }
   }
 
@@ -404,7 +486,7 @@ export function live(options: LiveOptions): Live {
   }
 
   async function drain(): Promise<void> {
-    if (draining || core === undefined) return
+    if (draining || core === undefined || closed) return
     draining = true
     try {
       for (let item = queue.shift(); item !== undefined; item = queue.shift()) {
@@ -417,26 +499,48 @@ export function live(options: LiveOptions): Live {
 
   async function apply(c: Core, item: Queued): Promise<void> {
     if (item.kind === "down") {
+      if (!c.hub.down) {
+        downSince = Date.now()
+        logger?.error(
+          "live bus unreachable: live sockets closed, open pages poll until it answers",
+          {
+            error: messageOf(item.error),
+          },
+        )
+      }
       c.hub.down = true
       c.hub.closeAll(CLOSE_CAPACITY, "unavailable")
       return
     }
-    if (item.kind === "gap") return forgetUntil(c, item.head)
+    if (item.kind === "gap") {
+      if (c.hub.down) {
+        logger?.info("live bus answering again: live sockets resume", {
+          downMs: Date.now() - (downSince ?? Date.now()),
+        })
+      } else logger?.warn("live bus lost events before this process read them: live sockets resync")
+      return forgetUntil(c, item.head)
+    }
     const event = item.event
     // At-least-once delivery: a repeat is already applied.
     if (!Number.isSafeInteger(event.seq) || event.seq <= seen) return
     try {
       await applyEvent(c, event, hash)
+      events++
+      // The seq is the bus clock's microseconds at the append.
+      lagMs = Math.max(0, Date.now() - Math.floor(event.seq / 1000))
       settle(event.seq)
     } catch (err) {
       // An event this process could not apply leaves its history and revocations unknown.
-      console.error("[nifra/web] live: a bus event could not be applied; closing live sockets", err)
+      logger?.error("live bus event could not be applied: live sockets resync", {
+        error: messageOf(err),
+      })
       forgetUntil(c, event.seq)
     }
   }
 
   /** Everything up to `head` is unknown: refuse older grants, report all owners stale, reconnect. */
   function forgetUntil(c: Core, head: number): void {
+    downSince = undefined
     // Never behind what this process applied: loads already issued watermarks up to `seen`.
     const at = Math.max(head, seen)
     c.history.reset(at)
@@ -460,6 +564,7 @@ export function live(options: LiveOptions): Live {
 
   /** Append to the bus, then wait until this process has applied it, at most {@link APPLY_WAIT_MS}. */
   async function append(input: Parameters<LiveBus["append"]>[0]): Promise<void> {
+    if (closed) throw new Error("[nifra/web] live: the runtime is closed; nothing was published")
     if (hubNamespace !== undefined) return appendToHub(hubNamespace, input)
     await started
     const seq = await bus.append(input)
@@ -479,8 +584,9 @@ export function live(options: LiveOptions): Live {
           if (at !== -1) waiters.splice(at, 1)
           if (!lagging) {
             lagging = true
-            console.error(
-              `[nifra/web] live: this process did not read a publish back from the bus within ${APPLY_WAIT_MS} ms; its sockets miss changes until the bus reader recovers`,
+            logger?.error(
+              "live publish not read back from the bus: this process's sockets miss changes until its reader recovers",
+              { waitedMs: APPLY_WAIT_MS },
             )
           }
           resolve()
@@ -572,7 +678,13 @@ export function live(options: LiveOptions): Live {
         const opened = await auth.ring.open(token, now)
         if (opened === undefined) continue
         const claims = opened.claims
-        if (claims.sid !== body.sid || claims.frame !== body.frame) continue
+        // A seed is exchanged by a load of the page it was rendered with, while it is fresh.
+        const seed =
+          claims.sid === SEED_SID &&
+          body.mode === "load" &&
+          claims.path === path &&
+          now / 1000 - claims.iat <= SEED_MAX_AGE_SECONDS
+        if ((!seed && claims.sid !== body.sid) || claims.frame !== body.frame) continue
         // A navigation presents the grant of the page it leaves: only its layouts can carry over, and
         // only where the layout itself would keep its data. A renewal is for the same page.
         if (claims.path !== path && body.mode === "renew") continue
@@ -653,6 +765,24 @@ export function live(options: LiveOptions): Live {
         }
         return undefined
       },
+      seedOf: (req, routeId) => {
+        const c = core
+        // A render never waits on the bus: with no core yet, or none that could vouch, it carries none.
+        if (hubNamespace !== undefined || c === undefined || closed || c.hub.down) return undefined
+        const url = new URL(req.url)
+        const path = canonicalPath(url.pathname + url.search, req.url)
+        if (path === undefined) return undefined
+        const body: LoadBody = {
+          path,
+          sid: SEED_SID,
+          frame: PAGE_FRAME,
+          mode: "load",
+          retain: NO_OWNERS,
+          grants: NO_OWNERS,
+          fill: NO_OWNERS,
+        }
+        return new LoadState(c.ring, false, body, path, seen, undefined, routeId, false)
+      },
       loadOf: (req) => {
         // An app hook after the endpoint may hand on a replacement; the load is its original's.
         let current: Request | undefined = req
@@ -910,10 +1040,41 @@ export function live(options: LiveOptions): Live {
       }
       await append({ type: "revoke", sub: subject ?? null, key })
     },
+    status() {
+      const hub = core?.hub
+      return {
+        ready: hubNamespace === undefined ? hub !== undefined : keyringReady,
+        down: closed || downSince !== undefined || hub?.down === true,
+        downSince: closed ? (downSince ?? closedAt) : downSince,
+        sockets: hub?.size ?? 0,
+        loads: inflight,
+        events,
+        notified: hub?.notified ?? 0,
+        lagMs,
+      }
+    },
+    close() {
+      closing ??= (async () => {
+        closed = true
+        closedAt = Date.now()
+        subscription?.close()
+        const c = core
+        if (c !== undefined) {
+          c.hub.down = true
+          c.hub.closeAll(CLOSE_GOING_AWAY, "closed")
+        }
+        // A publish waiting to read its event back never will now.
+        for (const waiter of waiters.splice(0)) waiter.resolve()
+      })()
+      return closing
+    },
     [LIVE_ATTACH]: attach,
   }
 }
 
+const messageOf = (error: unknown): string | undefined =>
+  error instanceof Error ? error.message : error === undefined ? undefined : String(error)
+
 /**
  * `app.publish`, holding the app weakly: a dev server builds a new app on every edit, and a discarded
  * one must not stay reachable, nor keep being published to, through the runtime. Built out here so

package/src/render-seam.ts

@@ -244,6 +244,8 @@ export const ACTION_GLOBAL = "__NIFRA_ACTION__"
 /** Dynamic-boundary states for hydration; absent when a route declares no boundaries. */
 export const BOUNDARY_GLOBAL = "__NIFRA_BOUNDARIES__"
 export const COMPONENT_GLOBAL = "__NIFRA_COMPONENTS__"
+/** A live app's seed for the page: the client exchanges it for a grant once its socket opens. */
+export const LIVE_GLOBAL = "__NIFRA_LIVE__"
 /** Locale key -> copy chunk URL, in a production build that split copy tables by locale. The name
  * `@nifrajs/i18n/copy` reads. */
 export const COPY_CHUNKS_GLOBAL = "__NIFRA_COPY__"