@nifrajs/web 5.5.1 → 5.7.0

package/src/server-components/build.ts

@@ -139,6 +139,10 @@ export async function serverComponentsConfig(
       if (env.command === "serve") build = `d_${randomBytes(16).toString("hex")}`
       const config: UserConfig = {
         define: {
+          ...publicEnvDefines(
+            options.publicEnvPrefix ?? "PUBLIC_",
+            loadEnv(env.mode, root, options.publicEnvPrefix ?? "PUBLIC_"),
+          ),
           "process.env.NODE_ENV": JSON.stringify(
             env.command === "build" ? "production" : "development",
           ),
@@ -234,7 +238,7 @@ export async function serverComponentsConfig(
     // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The shared compiler guards implement Vite hooks; the shim differs only in optional hook metadata.
     viteAssetUrlGuard(guards) as Plugin,
     // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The shared compiler guards implement Vite hooks; the shim differs only in optional hook metadata.
-    viteZoneGuard(guards) as Plugin,
+    viteZoneGuard({ ...guards, componentReferences: true }) as Plugin,
     ...(options.plugins ?? []),
     proof,
   ]
@@ -255,7 +259,6 @@ export async function serverComponentsConfig(
     // Without it Vite inlines every `VITE_*` value from the app's .env files into client code.
     envPrefix: vitePublicEnvPrefix(options.publicEnvPrefix),
     define: {
-      ...publicEnvDefines(options.publicEnvPrefix ?? "PUBLIC_", process.env),
       "process.env.NIFRA_SSR_BUNDLED": '"1"',
       "globalThis.__NIFRA_EDGE_RUNTIME__": edge ? "true" : "false",
       __NIFRA_COMPONENT_BUILD__: JSON.stringify(build),
@@ -355,7 +358,10 @@ export async function buildServerComponents(
           JSON.stringify({
             adapter: options.adapter,
             target: options.target ?? "bun",
-            env: publicEnvDefines(options.publicEnvPrefix ?? "PUBLIC_", process.env),
+            env: publicEnvDefines(
+              options.publicEnvPrefix ?? "PUBLIC_",
+              loadEnv("production", root, options.publicEnvPrefix ?? "PUBLIC_"),
+            ),
           }),
         )
       for (const [file, hash] of [...modules].sort(([a], [b]) => codeUnitOrder(a, b)))

package/src/server-components/client.ts

@@ -1,3 +1,5 @@
+import { setHoleComponents } from "../internal/hole-runtime.ts"
+import { onPageRelease } from "../internal/page-events.ts"
 import { ServerComponentError } from "./error.ts"
 import { readComponentFrames } from "./frames.ts"
 import {
@@ -9,7 +11,7 @@ import {
 import { registerComponentController, unregisterComponentController } from "./registry.ts"
 import { componentResponseFailure } from "./response.ts"
 import { BoundedComponentTasks } from "./scheduler.ts"
-import { parseComponentState } from "./state.ts"
+import { parseComponentRecord, parseComponentState } from "./state.ts"
 import { readComponentBytes } from "./stream.ts"
 import type { ComponentKey, ComponentRecord, ComponentState, ServerComponent } from "./types.ts"
 import { componentInputKey, componentValue } from "./value.ts"
@@ -64,6 +66,8 @@ interface Mounted {
   abort: AbortController
   root?: ComponentClientRoot
   ready: Promise<void>
+  // Cancels the release a parked instance waits on from its page.
+  unwatch?: (() => void) | undefined
 }
 function sameRecord(a: ComponentRecord, b: ComponentRecord): boolean {
   return (
@@ -90,6 +94,8 @@ export class ComponentController {
   }
   readonly #options: ComponentControllerOptions
   readonly #mounted = new Map<string, Mounted>()
+  // Set aside with a `keepAlive` page while it is hidden; another page may mount the same instances.
+  readonly #parked = new Set<Mounted>()
   // Structural outlet anchors survive logout; their private records and native roots do not.
   readonly #restorable = new Map<string, Element>()
   readonly #teardown = new WeakMap<Element, Promise<void>>()
@@ -122,6 +128,8 @@ export class ComponentController {
   }
   async #mount(host: Element, instance: string, fresh: boolean): Promise<void> {
     await this.#teardown.get(host)
+    // The page that parked it takes it back when it is shown again.
+    if (this.isParked(instance, host)) return
     if (this.#disposed || this.#mounted.has(instance))
       throw new ServerComponentError("component_contract")
     const record = this.state.records.find((record) => record.instance === instance)
@@ -162,6 +170,8 @@ export class ComponentController {
     try {
       await mounted.ready
     } catch (error) {
+      // Parked while it hydrated: it mounts again when its page is shown.
+      if (this.#parked.has(mounted)) return
       if (this.#mounted.get(instance) === mounted) await this.unmount(instance)
       throw error
     }
@@ -439,6 +449,64 @@ export class ComponentController {
       mounted.generation++
     }
   }
+  /**
+   * Set aside the components inside `page`, a `keepAlive` page the router hides: their pending work is
+   * cancelled, and navigation neither updates nor unmounts them until `unpark` takes them back.
+   * `bindComponentRouter` calls it on the page events.
+   */
+  park(page: Node): void {
+    for (const mounted of this.#mounted.values())
+      if (page.contains(mounted.host)) {
+        this.#mounted.delete(mounted.record.instance)
+        this.#parked.add(mounted)
+        mounted.unwatch = onPageRelease(page, () => {
+          void this.#release(mounted).catch(() => this.reportError("component_failed"))
+        })
+        mounted.abort.abort()
+        mounted.abort = new AbortController()
+        mounted.generation++
+      }
+  }
+  /** Take back the components `park` set aside inside `page`, which is shown again. */
+  unpark(page: Node): void {
+    for (const mounted of this.#parked) {
+      if (!page.contains(mounted.host)) continue
+      const id = mounted.record.instance
+      if (this.#mounted.has(id) || this.#disposed) {
+        void this.#release(mounted)
+        continue
+      }
+      this.#parked.delete(mounted)
+      mounted.unwatch?.()
+      if (mounted.root !== undefined) this.#mounted.set(id, mounted)
+      // Hidden while it hydrated, which `park` cancelled: mount it again.
+      else
+        void this.#mount(mounted.host, id, mounted.host.childNodes.length === 0).catch(() =>
+          this.reportError("component_failed"),
+        )
+    }
+  }
+  /**
+   * Whether `instance` at `host` is parked with its hidden page. An outlet whose framework cleans up a
+   * hidden page's effects (React's `<Activity>`) leaves it parked: the page takes it back when shown
+   * again, and releases it when dropped.
+   */
+  isParked(instance: string, host: Element): boolean {
+    for (const mounted of this.#parked)
+      if (mounted.host === host && mounted.record.instance === instance) return true
+    return false
+  }
+  async #release(mounted: Mounted): Promise<void> {
+    if (!this.#parked.delete(mounted)) return
+    mounted.unwatch?.()
+    for (const child of this.#parked)
+      if (mounted.host.contains(child.host)) await this.#release(child)
+    mounted.abort.abort()
+    await mounted.ready.catch(() => {
+      /* A parked hydration was cancelled; nothing of it can commit. */
+    })
+    await mounted.root?.dispose()
+  }
   async adopt(state: ComponentState, ownerUrl?: string): Promise<void> {
     if (ownerUrl !== undefined) this.#ownerUrl = ownerUrl
     if (this.#disposed || state === this.#source) return
@@ -568,7 +636,11 @@ export class ComponentController {
       }
     }
   }
-  async unmount(instance: string): Promise<void> {
+  /** Unmount `instance`; an outlet passes its `host`, which tells a parked page's instance apart. */
+  async unmount(instance: string, host?: Element): Promise<void> {
+    for (const mounted of this.#parked)
+      if (mounted.host === host && mounted.record.instance === instance)
+        return this.#release(mounted)
     this.#restorable.delete(instance)
     await this.#unmount(instance)
   }
@@ -594,7 +666,7 @@ export class ComponentController {
       if (this.#teardown.get(mounted.host) === teardown) this.#teardown.delete(mounted.host)
     }
   }
-  async #clearScope(preserveOutlets = false): Promise<void> {
+  async #clearScope(preserveOutlets = false, keepParked = false): Promise<void> {
     this.#authEpoch++
     if (preserveOutlets) {
       for (const mounted of this.#mounted.values())
@@ -603,7 +675,10 @@ export class ComponentController {
     } else this.#restorable.clear()
     this.#state = { ...this.#state, records: [] }
     this.#source = undefined
-    await Promise.all([...this.#mounted.keys()].map((instance) => this.#unmount(instance)))
+    await Promise.all([
+      ...[...this.#mounted.keys()].map((instance) => this.#unmount(instance)),
+      ...(keepParked ? [] : [...this.#parked].map((mounted) => this.#release(mounted))),
+    ])
   }
   async invalidateScope(): Promise<void> {
     this.#adoption++
@@ -611,7 +686,7 @@ export class ComponentController {
   }
   async navigate(): Promise<void> {
     this.cancelPending()
-    await this.#clearScope()
+    await this.#clearScope(false, !this.#disposed)
   }
   async dispose(): Promise<void> {
     this.#disposed = true
@@ -651,6 +726,15 @@ export function resolveComponentRecord<Input>(
   return matches[0]!
 }
 
+/**
+ * Experimental: how the client islands inside partially prerendered holes that show server
+ * components mount, as the adapter's component client, such as `vueComponentClient({ islands })`;
+ * `undefined` forgets it. Call it in the client entry before the router mounts. Without one such a
+ * hole shows its error slot.
+ */
+export function holeComponents(client: ComponentClientAdapter | undefined): void {
+  setHoleComponents(client === undefined ? undefined : { client, record: parseComponentRecord })
+}
 export { invalidateComponentScope } from "./registry.ts"
 export { bindComponentRouter, refreshAfterComponentMutation } from "./router-integration.ts"
 export { parseComponentState } from "./state.ts"

package/src/server-components/definition.ts

@@ -1,7 +1,8 @@
 import { narrowCapabilityContext } from "@nifrajs/core/capabilities"
 import { validateStandard } from "@nifrajs/core/schema"
 import { outputGuard, runGuard } from "../internal/output-guard.ts"
-import { isControlFlow, isStatusSignal } from "../internal/render-document.ts"
+import { isControlFlow } from "../internal/render-document.ts"
+import { isStatusSignal } from "../internal/status-page.ts"
 import { ServerComponentError } from "./error.ts"
 import { assertComponentSchema, componentValue } from "./schema.ts"
 import type {

package/src/server-components/hole.ts

@@ -0,0 +1,23 @@
+/**
+ * Experimental: a partially prerendered hole whose content is a server component. The hole's loader
+ * returns the component's input; the server runs the component for each visitor and sends its HTML,
+ * and the browser mounts only the client islands inside it. Under the coordinated compiler a browser
+ * import of a `*.component.server` module is an opaque handle, so the component never ships.
+ */
+import { SERVER_HOLE } from "../internal/ppr/contract.ts"
+import type { ServerComponent } from "./types.ts"
+
+/**
+ * A `dynamic` hole's `render`: the hole shows `component`, given the hole loader's output as its
+ * input. The page's app lists the component under `createServerComponents({ holes })` for the route.
+ * The hole cannot be `interactive`; its client islands are.
+ */
+export function serverHole<Input, Props, View>(
+  component: ServerComponent<Input, Props, View>,
+): (data: Input) => never {
+  const render = (): never => {
+    throw new Error("[nifra/web] a server component hole renders on the server only")
+  }
+  Object.defineProperty(render, SERVER_HOLE, { value: component })
+  return Object.freeze(render)
+}

package/src/server-components/html-policy.ts

@@ -35,10 +35,59 @@ const urls = new Set([
   "data",
   "codebase",
 ])
+const IMAGE_HINT = new Set([
+  "rel",
+  "as",
+  "href",
+  "imagesrcset",
+  "imagesizes",
+  "crossorigin",
+  "fetchpriority",
+  "referrerpolicy",
+])
 const fail = (): never => {
   throw new ServerComponentError("component_protocol", 400)
 }
 
+const unsafeUrl = (value: string): boolean =>
+  /^(?:javascript|vbscript|data):/.test(
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: Browsers discard these controls when interpreting URL schemes.
+    value.replace(/[\u0000-\u0020\u007f]/g, "").toLowerCase(),
+  )
+
+const isSpace = (char: string): boolean =>
+  char === " " || char === "\t" || char === "\n" || char === "\f" || char === "\r"
+
+/**
+ * The image candidate URLs of a `srcset`, split as the HTML standard's "parse a srcset attribute"
+ * splits them, so each is the URL a browser would fetch: a URL is a run without whitespace, and its
+ * descriptors end at the first comma outside parentheses.
+ */
+function srcsetUrls(value: string): string[] {
+  const found: string[] = []
+  let at = 0
+  while (at < value.length) {
+    while (at < value.length && (isSpace(value[at] ?? "") || value[at] === ",")) at++
+    const start = at
+    while (at < value.length && !isSpace(value[at] ?? "")) at++
+    const url = value.slice(start, at)
+    if (url === "") break
+    if (url.endsWith(",")) {
+      found.push(url.replace(/,+$/, ""))
+      continue
+    }
+    found.push(url)
+    let inParens = false
+    for (; at < value.length; at++) {
+      const char = value[at]
+      if (char === "(") inParens = true
+      else if (char === ")") inParens = false
+      else if (char === "," && !inParens) break
+    }
+  }
+  return found
+}
+
 function css(value: string): string {
   return (
     value
@@ -66,6 +115,17 @@ export function validateComponentTag(
     const attrs = new Map(
       attributes.map((attribute) => [attribute.name.toLowerCase(), attribute.value]),
     )
+    // React writes an image's preload hint ahead of each `<img>` it renders without a document. Like
+    // every hint here it is cut from the range, so it only has to be a well-formed image hint.
+    if (attrs.get("rel") === "preload" && attrs.get("as") === "image") {
+      if (
+        [...attrs.keys()].some((name) => !IMAGE_HINT.has(name)) ||
+        unsafeUrl(attrs.get("href") ?? "") ||
+        srcsetUrls(attrs.get("imagesrcset") ?? "").some(unsafeUrl)
+      )
+        fail()
+      return
+    }
     if (
       !["preload", "modulepreload"].includes(attrs.get("rel") ?? "") ||
       !assets.has(attrs.get("href") ?? "") ||
@@ -79,10 +139,9 @@ export function validateComponentTag(
   if (forbidden.has(tag.toLowerCase())) fail()
   for (const attribute of attributes) {
     const name = attribute.name.toLowerCase()
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: Browsers discard these controls when interpreting URL schemes.
-    const value = attribute.value.replace(/[\u0000-\u0020\u007f]/g, "").toLowerCase()
-    if (name.startsWith("on") || ["srcdoc", "is", "srcset", "ping"].includes(name)) fail()
-    if (urls.has(name) && /^(?:javascript|vbscript|data):/.test(value)) fail()
+    if (name.startsWith("on") || ["srcdoc", "is", "ping"].includes(name)) fail()
+    if (urls.has(name) && unsafeUrl(attribute.value)) fail()
+    if (name === "srcset" && srcsetUrls(attribute.value).some(unsafeUrl)) fail()
     if (
       name === "style" &&
       /expression\(|@import|(?:javascript|vbscript|data):|-moz-binding|behavior:/.test(

package/src/server-components/html-scan.ts

@@ -0,0 +1,159 @@
+/**
+ * A linear scan of the HTML a component renderer writes, for the validator's common case. It reads
+ * only a subset that parse5's tokenizer reads without a parse error and with the same start tags:
+ * ASCII tag and attribute names, double-quoted values, a few character references and plain
+ * comments. Anything else returns `undefined`, and the tokenizer decides. A differential test holds
+ * the two to the same tags (server-components-html-scan.test.ts).
+ */
+
+export interface ScannedTag {
+  readonly tagName: string
+  readonly attrs: { readonly name: string; readonly value: string }[]
+}
+
+const REFERENCES: ReadonlyArray<readonly [string, string]> = [
+  ["&amp;", "&"],
+  ["&lt;", "<"],
+  ["&gt;", ">"],
+  ["&quot;", '"'],
+  ["&#39;", "'"],
+  ["&#x27;", "'"],
+  ["&nbsp;", "\u00a0"],
+]
+
+const referenceAt = (html: string, at: number): readonly [string, string] | undefined => {
+  for (const reference of REFERENCES) if (html.startsWith(reference[0], at)) return reference
+  return undefined
+}
+
+const isSpace = (code: number): boolean =>
+  code === 0x20 || code === 0x0a || code === 0x09 || code === 0x0c || code === 0x0d
+const isLetter = (code: number): boolean =>
+  (code >= 0x61 && code <= 0x7a) || (code >= 0x41 && code <= 0x5a)
+const isTagCode = (code: number): boolean =>
+  isLetter(code) || (code >= 0x30 && code <= 0x39) || code === 0x2d
+const isAttributeStart = (code: number): boolean => isLetter(code) || code === 0x5f || code === 0x3a
+const isAttributeCode = (code: number): boolean =>
+  isAttributeStart(code) || (code >= 0x30 && code <= 0x39) || code === 0x2d || code === 0x2e
+
+/**
+ * The code units of the character at `at`, or 0 when parse5 reports it (NULL, a control, a
+ * noncharacter, a lone surrogate) or past the end.
+ */
+function unitsAt(html: string, at: number): number {
+  const code = html.charCodeAt(at)
+  if (code >= 0x20 && code < 0x7f) return 1
+  if (code >= 0xd800 && code <= 0xdbff) {
+    const low = html.charCodeAt(at + 1)
+    if (!(low >= 0xdc00 && low <= 0xdfff)) return 0
+    const point = ((code - 0xd800) << 10) + (low - 0xdc00) + 0x10000
+    return (point & 0xfffe) === 0xfffe ? 0 : 2
+  }
+  if (Number.isNaN(code) || (code >= 0xdc00 && code <= 0xdfff)) return 0
+  if (code < 0x20) return isSpace(code) ? 1 : 0
+  if (code <= 0x9f) return 0
+  return (code >= 0xfdd0 && code <= 0xfdef) || code === 0xfffe || code === 0xffff ? 0 : 1
+}
+
+/** Where a start tag whose name begins at `at` ends, with `tags` given its tag, or -1. */
+function scanStartTag(html: string, at: number, tags: ScannedTag[]): number {
+  let end = at
+  while (isTagCode(html.charCodeAt(end))) end++
+  const tagName = html.slice(at, end).toLowerCase()
+  // The validator reads these two as a browser does, which needs the text after them.
+  if (tagName === "title" || tagName === "textarea") return -1
+  let code = html.charCodeAt(end)
+  if (!(isSpace(code) || code === 0x2f || code === 0x3e)) return -1
+  const attrs: { name: string; value: string }[] = []
+  for (;;) {
+    while (isSpace(html.charCodeAt(end))) end++
+    code = html.charCodeAt(end)
+    if (code === 0x3e || (code === 0x2f && html.charCodeAt(end + 1) === 0x3e)) {
+      tags.push({ tagName, attrs })
+      return end + (code === 0x3e ? 1 : 2)
+    }
+    if (!isAttributeStart(code)) return -1
+    const nameStart = end
+    while (isAttributeCode(html.charCodeAt(end))) end++
+    const name = html.slice(nameStart, end).toLowerCase()
+    if (attrs.some((attr) => attr.name === name)) return -1
+    code = html.charCodeAt(end)
+    let value = ""
+    if (code === 0x3d) {
+      if (html.charCodeAt(end + 1) !== 0x22) return -1
+      let from = end + 2
+      end = from
+      for (;;) {
+        code = html.charCodeAt(end)
+        if (code === 0x22) break
+        if (code === 0x26) {
+          const reference = referenceAt(html, end)
+          if (reference === undefined) return -1
+          value += html.slice(from, end) + reference[1]
+          end += reference[0].length
+          from = end
+          continue
+        }
+        // A CR would reach the tokenizer's value as LF.
+        const units = code === 0x0d ? 0 : unitsAt(html, end)
+        if (units === 0) return -1
+        end += units
+      }
+      value += html.slice(from, end)
+      end++
+      code = html.charCodeAt(end)
+      if (!(isSpace(code) || code === 0x2f || code === 0x3e)) return -1
+    } else if (!(isSpace(code) || code === 0x2f || code === 0x3e)) return -1
+    attrs.push({ name, value })
+  }
+}
+
+/** The start tags of `html`, or `undefined` when it leaves the subset this scan reads. */
+export function scanComponentHTML(html: string): ScannedTag[] | undefined {
+  const tags: ScannedTag[] = []
+  let at = 0
+  while (at < html.length) {
+    const code = html.charCodeAt(at)
+    if (code === 0x3c) {
+      const next = html.charCodeAt(at + 1)
+      if (isLetter(next)) {
+        at = scanStartTag(html, at + 1, tags)
+        if (at === -1) return undefined
+      } else if (next === 0x2f) {
+        let end = at + 2
+        if (!isLetter(html.charCodeAt(end))) return undefined
+        while (isTagCode(html.charCodeAt(end))) end++
+        while (isSpace(html.charCodeAt(end))) end++
+        if (html.charCodeAt(end) !== 0x3e) return undefined
+        at = end + 1
+      } else if (html.startsWith("!--", at + 1)) {
+        const from = at + 4
+        if (html.charCodeAt(from) === 0x3e || html.startsWith("->", from)) return undefined
+        const close = html.indexOf("-->", from)
+        if (close === -1) return undefined
+        for (let inner = from; inner < close; ) {
+          const units = unitsAt(html, inner)
+          if (units === 0) return undefined
+          // `<!` can open a nested comment and `--!` a `--!>` ending; both are parse errors.
+          if (
+            html.charCodeAt(inner) === 0x21 &&
+            ((inner > from && html.charCodeAt(inner - 1) === 0x3c) ||
+              (inner - 2 >= from && html.startsWith("--", inner - 2)))
+          )
+            return undefined
+          inner += units
+        }
+        at = close + 3
+      } else return undefined
+    } else if (code === 0x26) {
+      const reference = referenceAt(html, at)
+      if (reference === undefined) return undefined
+      at += reference[0].length
+    } else {
+      const units = unitsAt(html, at)
+      if (units === 0) return undefined
+      at += units
+    }
+  }
+  return tags
+}

package/src/server-components/html.ts

@@ -1,6 +1,7 @@
 import { Tokenizer } from "parse5"
 import { ServerComponentError } from "./error.ts"
 import { validateComponentTag } from "./html-policy.ts"
+import { scanComponentHTML } from "./html-scan.ts"
 import { COMPONENT_LIMITS } from "./protocol.ts"
 
 /**
@@ -19,16 +20,26 @@ function closesAsText(html: string, tag: string, from: number): boolean {
   )
 }
 
+function assertOutputSize(html: string): void {
+  // UTF-8 takes at most three bytes per UTF-16 unit, so only a long string is encoded to measure it.
+  if (
+    html.length * 3 > COMPONENT_LIMITS.outputBytes &&
+    new TextEncoder().encode(html).length > COMPONENT_LIMITS.outputBytes
+  )
+    throw new ServerComponentError("component_limit", 413)
+}
+
 /** Tokenization validates attributes even in SVG/table contexts a document parser may discard. */
 function tokenize(
   html: string,
   assets?: ReadonlySet<string>,
   hints?: Array<{ start: number; end: number }>,
 ): void {
-  if (new TextEncoder().encode(html).length > COMPONENT_LIMITS.outputBytes)
-    throw new ServerComponentError("component_limit", 413)
+  assertOutputSize(html)
   const tokenizer = new Tokenizer(
-    { sourceCodeLocationInfo: true },
+    // Offsets are read only for hints and for `title`/`textarea`, whose names a tokenizer lowercases
+    // from ASCII alone; tracking them costs every other string about a tenth of its check.
+    { sourceCodeLocationInfo: hints !== undefined || /<(?:title|textarea)/i.test(html) },
     {
       onStartTag(token) {
         validateComponentTag(token.tagName, token.attrs, assets)
@@ -63,7 +74,10 @@ function tokenize(
 }
 
 export function validateComponentHTML(html: string, assets?: ReadonlySet<string>): void {
-  tokenize(html, assets)
+  assertOutputSize(html)
+  const tags = scanComponentHTML(html)
+  if (tags === undefined) tokenize(html, assets)
+  else for (const tag of tags) validateComponentTag(tag.tagName, tag.attrs, assets)
 }
 
 /** React may produce resource hints while decoding Flight. They are not owned range nodes. */

package/src/server-components/router-integration.ts

@@ -1,13 +1,27 @@
+import { PAGE_HIDE_EVENT, PAGE_SHOW_EVENT } from "../internal/page-events.ts"
 import type { ClientRouter } from "../router.ts"
 import type { ComponentController } from "./client.ts"
 import { componentControllers } from "./registry.ts"
 
-/** Optional router integration; imported only by opted-in application entries. */
+/**
+ * Optional router integration; imported only by opted-in application entries. The components of a
+ * `keepAlive` page are parked while it is hidden, so navigation leaves them as they are.
+ */
 export function bindComponentRouter(
   router: Pick<ClientRouter, "snapshot" | "subscribe">,
 ): () => void {
   let previous = router.snapshot()
-  return router.subscribe(() => {
+  const onPage = (event: Event): void => {
+    const page = event.target
+    if (page instanceof Node)
+      for (const controller of componentControllers)
+        if (event.type === PAGE_HIDE_EVENT) controller.park(page)
+        else controller.unpark(page)
+  }
+  const target = typeof document === "undefined" ? undefined : document
+  target?.addEventListener(PAGE_HIDE_EVENT, onPage)
+  target?.addEventListener(PAGE_SHOW_EVENT, onPage)
+  const stop = router.subscribe(() => {
     const next = router.snapshot()
     if (next.pending && next.pendingPath !== previous.pendingPath)
       for (const controller of componentControllers) controller.cancelPending()
@@ -25,6 +39,11 @@ export function bindComponentRouter(
     }
     previous = next
   })
+  return () => {
+    stop()
+    target?.removeEventListener(PAGE_HIDE_EVENT, onPage)
+    target?.removeEventListener(PAGE_SHOW_EVENT, onPage)
+  }
 }
 
 /** Refresh only after the existing mutation transport reports success. */