@nifrajs/web 5.5.1 → 5.6.0

package/src/internal/island-list.ts

@@ -0,0 +1,92 @@
+import { effect, untrack } from "./island-signals.ts"
+
+/** The node surface `bindList` uses; an `Element` has it. */
+export interface ListNode {
+  remove(): void
+}
+
+/** The container surface `bindList` uses; an `Element` has it. */
+export interface ListContainer<E extends ListNode> {
+  replaceChildren(...nodes: E[]): void
+  insertBefore(node: E, before: E | null): unknown
+}
+
+/** How `bindList` turns items into keyed DOM. */
+export interface BindListOptions<T, E extends ListNode = HTMLElement> {
+  /** Stable and unique per item - never the array index, or a removal reuses the wrong node. */
+  key(item: T): string | number
+  create(item: T): E
+  /** Brings a node in line with its item: runs after `create` and on every later change. */
+  update?(el: E, item: T): void
+}
+
+/**
+ * Render a list signal (or any getter) into `container` with keyed reconciliation. A surviving item
+ * keeps its node, so focus, selection and input state survive a reorder. A render with no earlier
+ * nodes replaces the container's children; later renders move only the nodes outside the longest
+ * run already in order. `key`, `create` and `update` run untracked: a signal they read does not
+ * re-render the list. Returns the disposer; inside an island the binding also stops on unmount.
+ */
+export function bindList<T, E extends ListNode = HTMLElement>(
+  source: () => readonly T[],
+  // A DOM container's generic methods would drive E to `ListNode`; the row type comes from `create`.
+  container: ListContainer<NoInfer<E>>,
+  options: BindListOptions<T, E>,
+): () => void {
+  let nodes = new Map<string | number, E>()
+  // Each node's position in the last render; empty until a render leaves nodes to keep.
+  let at = new Map<E, number>()
+  return effect(() => {
+    const items = source()
+    untrack(() => {
+      const next = new Map<string | number, E>()
+      for (const item of items) {
+        const key = options.key(item)
+        if (next.has(key)) console.warn("[nifra/islands] bindList: duplicate key skipped", key)
+        else {
+          const el = nodes.get(key) ?? options.create(item)
+          options.update?.(el, item)
+          next.set(key, el)
+        }
+      }
+      const els = [...next.values()]
+      if (at.size === 0) container.replaceChildren(...els)
+      else {
+        for (const [key, el] of nodes) if (!next.has(key)) el.remove()
+        const stays = inOrder(els.map((el) => at.get(el) ?? -1))
+        let anchor: E | null = null
+        for (let i = els.length - 1; i >= 0; i--) {
+          const el = els[i]
+          if (el === undefined) continue
+          if (!stays.has(i)) container.insertBefore(el, anchor)
+          anchor = el
+        }
+      }
+      at = new Map(els.map((el, i) => [el, i]))
+      nodes = next
+    })
+  })
+}
+
+// The indexes of `old` (each node's previous position, -1 for a new node) on a longest increasing
+// run: those nodes already sit in order, and every other node is moved.
+function inOrder(old: readonly number[]): Set<number> {
+  // tails[n] is the index ending the best run of length n + 1; back links each run.
+  const tails: number[] = []
+  const back: number[] = []
+  old.forEach((o, i) => {
+    if (o < 0) return
+    let lo = 0
+    let hi = tails.length
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1
+      if ((old[tails[mid] ?? 0] ?? 0) < o) lo = mid + 1
+      else hi = mid
+    }
+    back[i] = tails[lo - 1] ?? -1
+    tails[lo] = i
+  })
+  const stays = new Set<number>()
+  for (let i = tails.at(-1) ?? -1; i >= 0; i = back[i] ?? -1) stays.add(i)
+  return stays
+}

package/src/internal/island-mount.ts

@@ -0,0 +1,68 @@
+import {
+  type IslandStrategy,
+  MAX_MEDIA_QUERY_LENGTH,
+  scheduleTrigger,
+} from "@nifrajs/island-trigger"
+import type { IslandCleanup, IslandEnhancer } from "../islands.ts"
+import { owned } from "./island-owner.ts"
+
+function readProps(el: HTMLElement): unknown {
+  const raw = el.dataset.islandProps
+  if (raw === undefined || raw === "") return undefined
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+}
+
+/** Own one host so removing a subtree can stop its islands without disturbing retained siblings. */
+export function mountIsland(
+  el: HTMLElement,
+  enhancers: Readonly<Record<string, IslandEnhancer<never>>>,
+): IslandCleanup | undefined {
+  const id = el.dataset.island
+  if (id === undefined || el.dataset.islandMounted !== undefined) return undefined
+  const enhancer = Object.hasOwn(enhancers, id) ? enhancers[id] : undefined
+  if (enhancer === undefined) return undefined
+  const strategyAttr = el.dataset.islandStrategy
+  const media = el.dataset.islandMedia
+  const strategy: IslandStrategy | undefined =
+    strategyAttr === "idle" || strategyAttr === "visible" || strategyAttr === "load"
+      ? strategyAttr
+      : strategyAttr === "media" &&
+          media !== undefined &&
+          media.length > 0 &&
+          media.length <= MAX_MEDIA_QUERY_LENGTH
+        ? { media }
+        : strategyAttr === undefined
+          ? "load"
+          : undefined
+  // Invalid markers must stay inert, including untrusted oversized media queries.
+  if (strategy === undefined) return undefined
+  const disposers: Array<() => void> = []
+  el.dataset.islandMounted = ""
+  disposers.push(() => {
+    delete el.dataset.islandMounted
+  })
+  const props = readProps(el)
+  const run = (): void => {
+    try {
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: enhancer props are the authored SSR contract, as in defineIsland
+      const cleanup = owned(disposers, () => enhancer(el, props as never))
+      if (typeof cleanup === "function") disposers.push(cleanup)
+    } catch (err) {
+      console.error(`[nifra/islands] enhancer "${id}" failed:`, err)
+    }
+  }
+  disposers.push(scheduleTrigger(strategy, run, { target: el }))
+  return () => {
+    for (const dispose of disposers.splice(0)) {
+      try {
+        dispose()
+      } catch {
+        // Best-effort teardown: one failing cleanup must not block the rest.
+      }
+    }
+  }
+}

package/src/internal/island-owner.ts

@@ -0,0 +1,20 @@
+// The disposer list of the island whose enhancer is running, so every effect, computed, list binding
+// and resource it creates stops when the island unmounts. A separate module so an imperative-only
+// island bundle carries no signal code.
+let owner: Array<() => void> | undefined
+
+/** Run `fn` with every disposer it registers pushed onto `kids`. */
+export function owned<T>(kids: Array<() => void>, fn: () => T): T {
+  const prev = owner
+  owner = kids
+  try {
+    return fn()
+  } finally {
+    owner = prev
+  }
+}
+
+/** Register `stop` with the running island, if any. Outside an enhancer it stays the caller's. */
+export function adopt(stop: () => void): void {
+  owner?.push(stop)
+}

package/src/internal/island-resource.ts

@@ -0,0 +1,76 @@
+import { adopt } from "./island-owner.ts"
+import { effect, signal, untrack } from "./island-signals.ts"
+
+/** An async value's state. `status` narrows `value` and `error`, so no branch can be skipped. */
+export type ResourceState<T> =
+  | { readonly status: "pending"; readonly value: undefined; readonly error: undefined }
+  | { readonly status: "ready"; readonly value: T; readonly error: undefined }
+  | { readonly status: "error"; readonly value: undefined; readonly error: unknown }
+
+/** Call it to read the current state (tracking, like a signal). */
+export type Resource<T> = {
+  (): ResourceState<T>
+  /** Fetch the current key again; once disposed, nothing. */
+  refetch(): void
+  /** Stop refetching and abort the request in flight; its result is dropped. */
+  dispose(): void
+}
+
+const PENDING = { status: "pending", value: undefined, error: undefined } as const
+
+/**
+ * An async value keyed by `source`. `source` runs tracked, so a write to any signal it reads starts a
+ * new fetch; `fetcher` runs untracked with that key, so nothing it reads (before or after an `await`)
+ * is a dependency. A newer fetch aborts the older one and only the newest result lands. Inside an
+ * island, unmounting disposes it: the request in flight is aborted and its late result dropped.
+ */
+export function resource<K, T>(
+  source: () => K,
+  fetcher: (key: K, abort: AbortSignal) => Promise<T>,
+): Resource<T> {
+  const state = signal<ResourceState<T>>(PENDING)
+  let generation = 0
+  let live = true
+  let controller: AbortController | undefined
+  let key: K
+  const run = (): void => {
+    const mine = ++generation
+    controller?.abort()
+    const active = new AbortController()
+    controller = active
+    state.set(PENDING)
+    let pending: Promise<T>
+    try {
+      pending = fetcher(key, active.signal)
+    } catch (error) {
+      pending = Promise.reject(error)
+    }
+    pending.then(
+      (value) => {
+        if (mine === generation) state.set({ status: "ready", value, error: undefined })
+      },
+      (error) => {
+        // A superseded or aborted fetch is not an error the reader should see.
+        if (mine === generation && !active.signal.aborted)
+          state.set({ status: "error", value: undefined, error })
+      },
+    )
+  }
+  const stop = effect(() => {
+    key = source()
+    untrack(run)
+  })
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: `refetch` and `dispose` are assigned below
+  const read = (() => state()) as Resource<T>
+  read.refetch = () => {
+    if (live) untrack(run)
+  }
+  read.dispose = () => {
+    live = false
+    stop()
+    generation++
+    controller?.abort()
+  }
+  adopt(read.dispose)
+  return read
+}

package/src/internal/island-signals.ts

@@ -0,0 +1,249 @@
+/**
+ * Fine-grained signals - the reactive core of `@nifrajs/web/islands`. Pull-based auto-tracking with
+ * per-run re-tracking (a branch switch drops the stale branch's subscriptions), `Object.is`
+ * equality skips, and an explicit synchronous {@link batch} that coalesces effect re-runs.
+ *
+ * Deliberately tiny and synchronous: a write recomputes the computeds it feeds at once and runs its
+ * effects before `set` returns, each once, after every computed has settled - predictable for
+ * island-scale code (a counter, a filter drawer), and the whole core stays well under a kilobyte.
+ * This is NOT a general app framework - just island-scale reactivity.
+ */
+
+import { adopt } from "./island-owner.ts"
+
+interface EffectNode {
+  run: () => void
+  /** Each source's reader set, mapped to the run (`v`) that last read it. */
+  readonly deps: Map<Set<EffectNode>, number>
+  v: number
+  /** Sources read so far in this run. */
+  n: number
+  /** Running now: a write during the run requeues it only for a source this run already read. */
+  r?: boolean
+  /** Set on a computed's node: it recomputes on the write instead of queueing. */
+  readonly c?: boolean | undefined
+  /** Queued for the current flush. */
+  q?: boolean
+}
+
+let currentEffect: EffectNode | undefined
+
+/** Run `fn` without subscribing the running effect or computed to the signals it reads. */
+export function untrack<T>(fn: () => T): T {
+  const prev = currentEffect
+  currentEffect = undefined
+  try {
+    return fn()
+  } finally {
+    currentEffect = prev
+  }
+}
+
+let batchDepth = 0
+const queue: EffectNode[] = []
+
+/** A readable/writable reactive value: call it to read (tracking), `.set` to write. */
+export type Signal<T> = {
+  (): T
+  set(next: T | ((prev: T) => T)): void
+}
+
+/**
+ * Batch writes: effects triggered inside `fn` run ONCE after it returns, deduplicated - so
+ * `setA(); setB()` updates the DOM once, not twice. Re-entrant; an effect re-queued during the
+ * flush runs in the same flush.
+ */
+export function batch<T>(fn: () => T): T {
+  batchDepth++
+  try {
+    return fn()
+  } finally {
+    flush()
+  }
+}
+
+// Closes one batch level; the outermost runs the queue.
+function flush(): void {
+  let i = 0
+  try {
+    // The flush still counts as a batch: a write an effect makes here queues, so none runs twice.
+    while (batchDepth === 1 && i < queue.length) {
+      const next = queue[i++]
+      if (next?.q) {
+        next.q = false
+        next.run()
+      }
+    }
+  } finally {
+    // A throwing effect leaves the rest queued for the next flush.
+    if (i === queue.length) queue.length = 0
+    else queue.splice(0, i)
+    batchDepth--
+  }
+}
+
+// Each plain signal's reader set, so `watch` can subscribe without tracking.
+const readers = new WeakMap<object, Set<EffectNode>>()
+
+/** Create a signal. Reads inside an {@link effect} (or {@link computed}) subscribe automatically. */
+export function signal<T>(initial: T): Signal<T> {
+  const subs = new Set<EffectNode>()
+  const s = readable(initial, subs)
+  readers.set(s, subs)
+  return s
+}
+
+/**
+ * Call `fn` with `source`'s value now and after each change, queued and batched like an effect but
+ * subscribed once instead of tracking reads. Any other getter (a computed, a derived function) is
+ * tracked as an effect. Either way `fn` runs untracked. Internal to the binding walker, whose bindings each read one named signal,
+ * and to `bindList`; not exported from `@nifrajs/web/islands`.
+ */
+export function watch<T>(source: () => T, fn: (value: T) => void): () => void {
+  const subs = readers.get(source)
+  if (!subs)
+    return effect(() => {
+      const value = source()
+      untrack(() => fn(value))
+    })
+  const e: EffectNode = {
+    deps: new Map([[subs, 0]]),
+    v: 0,
+    n: 1,
+    run: () => {
+      const prev = currentEffect
+      currentEffect = undefined
+      try {
+        fn(source())
+      } finally {
+        currentEffect = prev
+      }
+    },
+  }
+  const stop = (): void => {
+    subs.delete(e)
+    e.q = false
+  }
+  subs.add(e)
+  adopt(stop)
+  batch(e.run)
+  return stop
+}
+
+// A signal whose readers are `subs`, so a computed can see whether anything still reads it.
+function readable<T>(initial: T, subs: Set<EffectNode>): Signal<T> {
+  let value = initial
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: `set` is assigned below, before the signal is returned
+  const read = (() => {
+    const e = currentEffect
+    if (e) {
+      const seen = e.deps.get(subs)
+      if (seen !== e.v) {
+        if (seen === undefined) subs.add(e)
+        e.deps.set(subs, e.v)
+        e.n++
+      }
+    }
+    return value
+  }) as Signal<T>
+  read.set = (next) => {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a function passed to `set` is always the updater form
+    const resolved = typeof next === "function" ? (next as (prev: T) => T)(value) : next
+    if (Object.is(resolved, value)) return
+    value = resolved
+    // Snapshot: an effect created while this write flushes must not run in it.
+    batchDepth++
+    try {
+      for (const e of [...subs]) {
+        // A running effect is requeued only by a source its current run has already read.
+        if (e.r && e.deps.get(subs) !== e.v) continue
+        if (e.c) e.run()
+        else if (!e.q) {
+          e.q = true
+          queue.push(e)
+        }
+      }
+    } finally {
+      flush()
+    }
+  }
+  return read
+}
+
+/** A derived value: call it to read (tracking), `.dispose()` to stop recomputing it. */
+export type Computed<T> = {
+  (): T
+  dispose(): void
+}
+
+/**
+ * Derived value, cached into a signal and computed on first read. While an effect (or another
+ * computed) reads it, it recomputes when its tracked inputs change. Once nothing reads it, the next
+ * input change stops it instead of recomputing, so a dropped computed costs nothing; reading it
+ * again starts it afresh. `dispose()` stops it at once.
+ */
+export function computed<T>(fn: () => T): Computed<T> {
+  const subs = new Set<EffectNode>()
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the first read computes it before returning
+  const out = readable<T>(undefined as T, subs)
+  let stop: (() => void) | undefined
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: `dispose` is assigned below
+  const read = (() => {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the implementation takes the computed flag its public overload hides
+    stop ??= (effect as (fn: () => void, c: boolean) => () => void)(() => {
+      if (!stop || subs.size) out.set(fn())
+      else read.dispose()
+    }, true)
+    return out()
+  }) as Computed<T>
+  read.dispose = () => {
+    stop?.()
+    stop = undefined
+  }
+  return read
+}
+
+/**
+ * Run `fn` now and again whenever any signal it read changes. Returns a disposer. Dependencies
+ * re-track on every run, so conditional reads subscribe to exactly the live branch. Every run,
+ * the first included, finishes before the effects its writes trigger run, itself among them.
+ */
+export function effect(fn: () => void): () => void
+export function effect(fn: () => void, c?: boolean): () => void {
+  const stop = (): void => {
+    for (const subs of e.deps.keys()) subs.delete(e)
+    e.deps.clear()
+    e.q = false
+  }
+  const e: EffectNode = {
+    c,
+    deps: new Map(),
+    v: 0,
+    n: 0,
+    // Subscriptions persist across runs; a source this run did not read is dropped afterwards.
+    run: () => {
+      ++e.v
+      e.n = 0
+      e.q = false
+      e.r = true
+      const prev = currentEffect
+      currentEffect = e
+      try {
+        fn()
+      } finally {
+        currentEffect = prev
+        e.r = false
+        if (e.n < e.deps.size)
+          for (const [subs, seen] of e.deps)
+            if (seen !== e.v) {
+              subs.delete(e)
+              e.deps.delete(subs)
+            }
+      }
+    },
+  }
+  adopt(stop)
+  // Batched, so a write in the first run cannot re-enter it before it finishes.
+  batch(e.run)
+  return stop
+}

package/src/internal/keep-alive-table.ts

@@ -0,0 +1,72 @@
+/**
+ * Where the slot wrappers of kept pages go, decided once from the route table so that the server's
+ * markup and every client render agree: a wrapper that appeared or vanished with what is kept would
+ * remount the page inside it, and one the server did not render fails hydration.
+ */
+import type { Manifest } from "../manifest.ts"
+
+/** What the server and the browser both read to place the slot wrappers. */
+export interface KeepAliveTable {
+  /** Routes whose page renders inside the slot wrappers: the build found a `keepAlive` export. */
+  readonly routes: readonly string[]
+  /** Layouts rendered inside the slot wrappers, because another chain the browser can render shares
+   * the layouts above one of them and not that one: a kept page then sits there beside the page on
+   * screen. A layout every chain shares is never wrapped. */
+  readonly layouts: readonly string[]
+}
+
+const sharesAbove = (a: readonly string[], b: readonly string[], depth: number): boolean => {
+  for (let i = 0; i < depth; i++) if (a[i] !== b[i]) return false
+  return true
+}
+
+/** The table for `manifest`, or `undefined` when no route keeps its page alive. */
+export function keepAliveTable(manifest: Manifest): KeepAliveTable | undefined {
+  const kept = manifest.routes.filter((route) => route.keepAlive === true)
+  if (kept.length === 0) return undefined
+  // Every layout chain the browser renders: each route's, a root status page's (inside the root
+  // layout unless the page opts out, which only its module says), and a `_loading` page's, which takes
+  // the layouts the two pages of a navigation share, so any prefix of a route under it.
+  const chains: (readonly string[])[] = manifest.routes.map((route) => route.layoutIds)
+  if (manifest.notFound !== undefined || Object.keys(manifest.statusPages ?? {}).length > 0) {
+    chains.push(manifest.layouts._layout === undefined ? [] : ["_layout"])
+  }
+  for (const [id, loading] of Object.entries(manifest.loadings ?? {})) {
+    for (const route of manifest.routes) {
+      if (!route.loadingIds?.includes(id)) continue
+      for (let n = loading.layoutIds.length; n <= route.layoutIds.length; n++) {
+        chains.push(route.layoutIds.slice(0, n))
+      }
+    }
+  }
+  const layouts = new Set<string>()
+  for (const route of kept) {
+    route.layoutIds.forEach((layout, depth) => {
+      if (layouts.has(layout)) return
+      if (
+        chains.some(
+          (chain) => chain[depth] !== layout && sharesAbove(chain, route.layoutIds, depth),
+        )
+      )
+        layouts.add(layout)
+    })
+  }
+  return { routes: [...new Set(kept.map((route) => route.id))], layouts: [...layouts] }
+}
+
+/**
+ * The chain indices to render inside slot wrappers for a chain of `layoutIds` and then the page of
+ * `routeId`: each wrapped layout, and the page when its route keeps alive.
+ */
+export function slotDepths(
+  table: KeepAliveTable,
+  layoutIds: readonly string[],
+  routeId: string | undefined,
+): readonly number[] {
+  const depths: number[] = []
+  layoutIds.forEach((layout, depth) => {
+    if (table.layouts.includes(layout)) depths.push(depth)
+  })
+  if (routeId !== undefined && table.routes.includes(routeId)) depths.push(layoutIds.length)
+  return depths
+}

package/src/internal/live-contract.ts

@@ -0,0 +1,106 @@
+/**
+ * The seam between page execution and a configured live runtime (`@nifrajs/web/live`): types and one
+ * symbol. An app without `live` imports nothing from the live module itself.
+ */
+import type { IdentityPlugin, WebSocketHandler } from "@nifrajs/core/server"
+import type { LoaderContext } from "../manifest.ts"
+import type { LiveClientEntry } from "./codegen.ts"
+
+/** What `createWebApp` tells the runtime about its routes. */
+export interface LiveRouteMatch {
+  readonly routeId: string
+  readonly layoutIds: readonly string[]
+}
+
+/** The app the live socket registers on. */
+export interface LiveHostApp {
+  use(plugin: IdentityPlugin): unknown
+  ws<Data>(path: string, handler: WebSocketHandler<Data>): unknown
+  publish(topic: string, data: string): void
+}
+
+export interface LiveAttachInput {
+  /** The route a canonical `pathname + search` renders, or `null`. */
+  readonly matchRoute: (path: string) => LiveRouteMatch | null
+  readonly app: LiveHostApp
+}
+
+export interface LiveAttachment {
+  /** Admission and dispatch for the live load endpoint; `undefined` for every other request. */
+  readonly onRequest: (req: Request) => Promise<Request | Response> | undefined
+  /** The live load a page request belongs to, or `undefined` for every request that is not one. */
+  readonly loadOf: (req: Request) => LiveLoad | undefined
+}
+
+/** One live load, from the page handler's side. */
+export interface LiveLoad {
+  /** The route the endpoint mapped the retain list against. */
+  readonly routeId: string
+  /** `undefined` when admitted; else the 503 to answer with. An admitted load is released once. */
+  admit(): Response | undefined
+  /** Release the admission slot once the response is complete: at once, or when its stream ends. */
+  settle(response: Response): Response
+  release(): void
+  /**
+   * After middleware: resolve the viewer's subject. `false` when the presented grant's retention no
+   * longer applies (another subject), so every owner loads fresh.
+   */
+  bind(ctx: LoaderContext): Promise<boolean>
+  /** Skip the page loader: the page owner is retained. Read after {@link bind}. */
+  readonly retainPage: boolean
+  /** `ctx.live` for one owner. */
+  collector(owner: string): (...keys: string[]) => void
+  /** Close an owner's collector once its loader has settled. */
+  seal(owner: string): void
+  /** The envelope's `live` member, built after every loader settled without a throw or status. */
+  finish(input: LiveFinish): Promise<LiveEnvelope>
+}
+
+export interface LiveFinish {
+  /** Owners whose loaders ran and resolved. */
+  readonly fresh: readonly string[]
+  /** Owners whose loaders were skipped: their keys come from the presented grant. */
+  readonly retained: readonly string[]
+  readonly ctx: LoaderContext
+}
+
+export interface LiveEnvelope {
+  /**
+   * Opaque and stable per viewer, one per listed secret, newest first. A load sharing none with the
+   * last one is another user, so client caches are cleared; a rotation always leaves one in common.
+   */
+  readonly subjects: readonly string[]
+  /** Absent when no grant could be issued; the client then polls. */
+  readonly grant?: string
+  /** Wire tag to the frame's owners that watch its key. */
+  readonly tags?: Readonly<Record<string, readonly string[]>>
+  /** The page loader did not run: the client keeps its page data. */
+  readonly page?: "retained"
+  /** Seconds the grant stays valid from now; the client renews a minute before. */
+  readonly ttl?: number
+  /** For query hooks: with `queryKeys`, and in development so the page can warn. */
+  readonly query?: LiveQueryKeys
+}
+
+export interface LiveQueryKeys {
+  /** Fresh per load; absent when `queryKeys` is off. */
+  readonly salt?: string
+  /** Wire tag to its key's digest under `salt`. */
+  readonly keys?: Readonly<Record<string, string>>
+  /** The app runs in development: the page warns about query keys no grant holds. */
+  readonly dev?: true
+}
+
+/** The owner a hole of a partially prerendered page is in its page's live frame. */
+export const holeOwner = (hole: string, routeId: string): string => `B:${hole}:${routeId}`
+
+/** `createWebApp` reads the runtime through this symbol, so it is not public API on the object. */
+export const LIVE_ATTACH: unique symbol = Symbol.for("nifra.web.live.attach")
+
+export interface LiveRuntimeHandle {
+  readonly [LIVE_ATTACH]: (input: LiveAttachInput) => LiveAttachment
+  /** The client entry's `live` option for this runtime: the endpoints it serves, where not the default. */
+  readonly clientEntry: LiveClientEntry
+  /** Announce changed keys; resolves once this process applied the change. */
+  publish(...keys: string[]): Promise<void>
+}