@nifrajs/web 5.5.1 → 5.7.0

package/src/manifest.ts

@@ -12,7 +12,14 @@ import {
   paramConstraint,
 } from "@nifrajs/core/pattern"
 import type { CookieOptions, ResponseResult, StandardSchemaV1 } from "@nifrajs/core/server"
-import type { BoundaryDescriptor, BoundaryRegistration } from "./boundary.ts"
+import type {
+  BoundaryDescriptor,
+  BoundaryRegistration,
+  BoundaryRequestCtx,
+  SharedHoleCtx,
+  ShellCtx,
+  StaticCtx,
+} from "./boundary.ts"
 import { guardChannel, outputGuard } from "./internal/output-guard.ts"
 import type { RevalidateTags } from "./isr.ts"
 
@@ -60,6 +67,12 @@ export interface LoaderContext {
   readonly search: Record<string, unknown>
   /** Response headers and cookies for this page request. */
   readonly set: LoaderResponseControls
+  /**
+   * Declare what this loader's data depends on, as keys in the cache-tag charset. In a live load
+   * (`createWebApp({ live })`) the page reloads this data when one of them changes; elsewhere it does
+   * nothing. Keys count only when the loader resolves, and must be declared before it does.
+   */
+  readonly live: (...keys: string[]) => void
 }
 
 /** A route's optional data loader: params/request in, data out. */
@@ -157,10 +170,23 @@ export type ClientAction = (
   args: ClientActionArgs,
 ) => ClientActionResult | undefined | Promise<ClientActionResult | undefined>
 
+/** A page's `keepAlive` export as an object. */
+export interface KeepAliveOptions {
+  /** Reload the page's data when it is shown again (default `true`). A page marked stale while it was
+   * hidden reloads anyway. */
+  readonly revalidate?: boolean
+  /** Longest the page may stay hidden before it is dropped, in milliseconds (default 10 minutes). */
+  readonly maxAge?: number
+}
+
 /** Client hooks populated by the generated route entry after a route chunk loads. */
 export interface ClientRouteHooks {
   readonly clientLoader?: ClientLoader
   readonly clientAction?: ClientAction
+  /** The page's `shareData` export: `false` gives every reload of it fresh data. */
+  readonly shareData?: boolean
+  /** The page's `keepAlive` export: the page stays mounted after a visitor leaves it. */
+  readonly keepAlive?: true | KeepAliveOptions
   /** Neutral boundary descriptors needed for soft-navigation interception. A boundary's loader lives in
    * the route's backend half, so the browser never learns whether one exists. */
   readonly boundaries?: ReadonlyArray<Omit<BoundaryDescriptor, "hasLoad">>
@@ -354,6 +380,19 @@ export interface RouteModule {
   readonly loaderOutput?: StandardSchemaV1
   /** Backend half only: the schema of what {@link action} sends back, held to the same rule. */
   readonly actionOutput?: StandardSchemaV1
+  /**
+   * Experimental, backend half only: the loader of a partially prerendered page's shared shell. It
+   * receives no request, so its output is the same for every visitor and the shell is cached.
+   */
+  readonly shellLoader?: (ctx: ShellCtx) => unknown
+  /** Experimental, backend half only: the schema of what {@link shellLoader} returns. */
+  readonly shellOutput?: StandardSchemaV1
+  /**
+   * Experimental, backend half only: query parameters that select a different shell, each with its
+   * closed set of values (`{ search: { color: ["red", "blue"] } }`). Any other parameter, or a value
+   * outside its set, builds the default shell; holes still read the whole query.
+   */
+  readonly shellVariations?: ShellVariations
   /** Optional client-only loader. It runs after hydration and on client navigations. */
   readonly clientLoader?: ClientLoader
   /** Optional client-only submit wrapper. The server action remains mandatory for mutations. */
@@ -374,6 +413,25 @@ export interface RouteModule {
    * Any other key change revalidates as usual - so omitting a data-affecting key here can never serve
    * stale data, it only forgoes the optimization. Client-only: the server always renders fresh. */
   readonly searchClientKeys?: readonly string[]
+  /**
+   * `false` gives every client reload of this page (an action's revalidation, `invalidate()`, a live
+   * refresh) fresh data. By default a reload keeps the identity of the parts of `data` and the layouts'
+   * data that it did not change, so an unchanged row keeps its DOM and component state, and a renderer
+   * that memoizes on identity skips it. Not every unchanged row, though: an array whose first 32
+   * elements all changed is taken whole, later unchanged elements included, so code that needs a row's
+   * identity must not count on it. Opt out for a page whose code compares `data` against its value
+   * from before the reload, or whose rows re-render whatever their identity, which then pay the
+   * comparison for nothing. Client-only.
+   */
+  readonly shareData?: boolean
+  /**
+   * Keep this page mounted after the visitor leaves it, so back and forward show it again as it was
+   * left: its component state, form fields, inner scroll offsets and focus. At most three pages are
+   * kept per tab, each for at most 10 minutes; a kept page is shown again only by a back or forward to
+   * its own history entry, and its data reloads in place. A sign-in or sign-out drops every kept page.
+   * Client-only.
+   */
+  readonly keepAlive?: true | KeepAliveOptions
   readonly meta?: MetaInput
   /**
    * Opt this route out of nifra's full-document client hydration. The server still renders the full
@@ -454,8 +512,58 @@ export interface BoundaryLoaderEntry {
   readonly load: NonNullable<BoundaryRegistration["load"]>
   /** The boundary data's output schema. Required whenever `load` returns data. */
   readonly output?: StandardSchemaV1
+  /**
+   * A `shared` boundary's freshness in seconds, required for one and refused for any other: an older
+   * entry is served while one rebuild runs. Write the entry inline, so the build can find it.
+   */
+  readonly revalidate?: number
+  /** A `shared` boundary's tags, as a route's `revalidateTags`: purging one drops its entries. */
+  readonly revalidateTags?: RevalidateTags
 }
 
+type DeclaredBoundaryOf<Frontend> = Frontend extends {
+  readonly boundaries: readonly (infer Declared)[]
+}
+  ? Declared
+  : never
+type BoundaryNameOf<Declared> = Declared extends { readonly name: infer Name extends string }
+  ? Name
+  : never
+// A hole needs an entry unless the page gives it a `load` of its own.
+type HoleNameOf<Declared> = Declared extends { readonly load: (...args: never[]) => unknown }
+  ? never
+  : Declared extends { readonly mode: "dynamic" | "shared" }
+    ? BoundaryNameOf<Declared>
+    : never
+type LoaderEntryOf<Declared> = Declared extends { readonly mode: "shared" }
+  ? Omit<BoundaryLoaderEntry, "load" | "revalidate"> & {
+      readonly load: (ctx: SharedHoleCtx) => unknown
+      readonly revalidate: number
+    }
+  : Omit<BoundaryLoaderEntry, "load" | "revalidate" | "revalidateTags"> & {
+      readonly load: (
+        ctx: Declared extends { readonly mode: "static" } ? StaticCtx : BoundaryRequestCtx,
+      ) => unknown
+    }
+
+/**
+ * The `boundaryLoaders` a backend half may export, from the module types of both halves: an entry
+ * names a boundary the page declares, and a route with a `shellLoader` needs one for each hole.
+ * Unchecked when TypeScript cannot read the page (`.svelte`, `.vue`) or its boundary names are not
+ * literal types, which `as const` on each boundary gives.
+ */
+export type BoundaryLoadersOf<Frontend, Backend> = unknown extends Frontend
+  ? Readonly<Record<string, BoundaryLoaderEntry>>
+  : string extends BoundaryNameOf<DeclaredBoundaryOf<Frontend>>
+    ? Readonly<Record<string, BoundaryLoaderEntry>>
+    : {
+        readonly [Declared in DeclaredBoundaryOf<Frontend> as BoundaryNameOf<Declared>]?: LoaderEntryOf<Declared>
+      } & (Backend extends { readonly shellLoader: unknown }
+        ? {
+            readonly [Declared in DeclaredBoundaryOf<Frontend> as HoleNameOf<Declared>]: LoaderEntryOf<Declared>
+          }
+        : unknown)
+
 /** A layout (or `_404`/`_error`) entry: its source file (for client codegen) + a lazy loader.
  *
  * A `_layout.tsx` may export `meta` (static {@link Meta} or a function of the loader data + params,
@@ -506,6 +614,9 @@ export interface RouteEntry {
   readonly loadingIds?: readonly string[]
   /** The frontend half: the file the browser bundle imports. */
   readonly file: string
+  /** Set when the frontend half exports `keepAlive` (found by a scan of its source): its page renders
+   * inside the slot wrappers a kept page needs, on the server and in the browser. */
+  readonly keepAlive?: true
   /** The backend half (`x.backend.ts`), when the route has one. Server-only. */
   readonly backend?: string
   /** Both halves, merged and checked. */
@@ -629,12 +740,101 @@ export const FRONTEND_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "HydrateFallback",
   "searchSchema",
   "searchClientKeys",
+  "shareData",
+  "keepAlive",
   "clientLoader",
   "clientAction",
   "boundaries",
   "ssr",
 ])
 
+/** Query parameters that select a shell variant, each with its closed set of values. */
+export interface ShellVariations {
+  readonly search?: Readonly<Record<string, readonly string[]>>
+}
+
+const VARIATION_NAME = /^[A-Za-z0-9_.-]{1,64}$/
+const MAX_VARIATION_KEYS = 8
+const MAX_VARIATION_VALUES = 32
+const MAX_VARIATION_VALUE_LENGTH = 128
+
+/** A closed, small set, so no client can mint unbounded shell keys. */
+function assertShellVariations(backend: string, value: unknown): void {
+  const fail = (why: string): never => {
+    throw routeError(`"${backend}" exports shellVariations ${why}`)
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    fail("that is not an object")
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: checked just above to be a non-null object that is not an array.
+  const record = value as Readonly<Record<string, unknown>>
+  for (const key of Object.keys(record))
+    if (key !== "search") fail(`with "${key}"; only "search" is read`)
+  const search = record.search
+  if (search === undefined) return
+  if (typeof search !== "object" || search === null || Array.isArray(search))
+    fail("whose search is not an object of value lists")
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: checked just above to be a non-null object that is not an array.
+  const entries = Object.entries(search as Readonly<Record<string, unknown>>)
+  if (entries.length > MAX_VARIATION_KEYS) fail(`with more than ${MAX_VARIATION_KEYS} parameters`)
+  for (const [name, values] of entries) {
+    if (!VARIATION_NAME.test(name))
+      fail(`with a parameter name "${name}" outside ${VARIATION_NAME.source}`)
+    if (!Array.isArray(values) || values.length === 0 || values.length > MAX_VARIATION_VALUES)
+      fail(`whose "${name}" is not a list of 1 to ${MAX_VARIATION_VALUES} values`)
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: checked just above to be an array.
+    const list = values as readonly unknown[]
+    if (
+      new Set(list).size !== list.length ||
+      list.some(
+        (item) =>
+          typeof item !== "string" || item.length === 0 || item.length > MAX_VARIATION_VALUE_LENGTH,
+      )
+    )
+      fail(
+        `whose "${name}" values are not distinct strings of 1 to ${MAX_VARIATION_VALUE_LENGTH} characters`,
+      )
+  }
+}
+
+// A year: past it, an entry may as well never refresh.
+const MAX_SHARED_REVALIDATE_SECONDS = 365 * 24 * 60 * 60
+
+/** A `shared` boundary's entry carries its own freshness; any other boundary's carries none. */
+function assertSharedEntry(
+  backend: string,
+  name: string,
+  shared: boolean,
+  entry: { readonly revalidate?: unknown; readonly revalidateTags?: unknown },
+): void {
+  const key = `boundaryLoaders["${name}"]`
+  if (!shared) {
+    if (entry.revalidate !== undefined || entry.revalidateTags !== undefined) {
+      throw routeError(
+        `${key} in "${backend}" has revalidate or revalidateTags, which only a shared boundary's entry takes`,
+      )
+    }
+    return
+  }
+  const { revalidate, revalidateTags } = entry
+  if (
+    typeof revalidate !== "number" ||
+    !Number.isInteger(revalidate) ||
+    revalidate < 1 ||
+    revalidate > MAX_SHARED_REVALIDATE_SECONDS
+  ) {
+    throw routeError(
+      `${key} in "${backend}" is for a shared boundary, so it needs revalidate: a whole number of seconds from 1 to ${MAX_SHARED_REVALIDATE_SECONDS}`,
+    )
+  }
+  if (
+    revalidateTags !== undefined &&
+    typeof revalidateTags !== "function" &&
+    !(Array.isArray(revalidateTags) && revalidateTags.every((tag) => typeof tag === "string"))
+  ) {
+    throw routeError(`${key}.revalidateTags in "${backend}" must be a list of tags or a function`)
+  }
+}
+
 /** Exports only the server or the build reads. They live in the route's `x.backend.ts`. */
 export const BACKEND_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "loader",
@@ -652,6 +852,9 @@ export const BACKEND_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "gate",
   "shouldRevalidate",
   "allowedOrigins",
+  "shellLoader",
+  "shellOutput",
+  "shellVariations",
 ])
 
 const routeError = (message: string): Error => new Error(`[nifra/web] ${message}`)
@@ -719,6 +922,12 @@ export function mergeRouteHalves(
   const cached = mergedHalves.get(front)
   if (cached !== undefined && cached.back === back) return cached.module
   assertFrontendHalf(file, front as unknown as Readonly<Record<string, unknown>>)
+  const shared = front.boundaries?.find((boundary) => boundary.mode === "shared")
+  if (shared !== undefined && back?.shellLoader === undefined) {
+    throw routeError(
+      `boundary "${shared.name}" in "${file}" is shared, which only a partially prerendered page has: its backend half must export shellLoader`,
+    )
+  }
   if (back === undefined || backend === undefined) {
     mergedHalves.set(front, { back, module: front })
     return front
@@ -731,12 +940,30 @@ export function mergeRouteHalves(
     action,
     loaderOutput,
     actionOutput,
+    shellLoader,
+    shellOutput,
     ...server
   } = back
-  const guarded: { loader?: unknown; action?: unknown } = {}
+  if (shellLoader !== undefined && loader !== undefined) {
+    throw routeError(
+      `"${backend}" exports both shellLoader and loader. A partially prerendered page's per-visitor data comes from its dynamic boundaries' loaders`,
+    )
+  }
+  if (server.shellVariations !== undefined) {
+    if (shellLoader === undefined)
+      throw routeError(`"${backend}" exports shellVariations but no shellLoader for them to vary`)
+    assertShellVariations(backend, server.shellVariations)
+  }
+  if (shellLoader !== undefined && server.prerender === true) {
+    throw routeError(
+      `"${backend}" exports shellLoader with prerender = true. A page with no per-visitor part needs no shellLoader`,
+    )
+  }
+  const guarded: { loader?: unknown; action?: unknown; shellLoader?: unknown } = {}
   for (const [name, fn, schema, schemaName] of [
     ["loader", loader, loaderOutput, "loaderOutput"],
     ["action", action, actionOutput, "actionOutput"],
+    ["shellLoader", shellLoader, shellOutput, "shellOutput"],
   ] as const) {
     if (fn === undefined) {
       if (schema !== undefined) {
@@ -759,11 +986,20 @@ export function mergeRouteHalves(
       throw routeError(`"${backend}" exports boundaryLoaders that is not an object of loaders`)
     }
     const loaders = boundaryLoaders as Readonly<
-      Record<string, { readonly load?: unknown; readonly output?: unknown }>
+      Record<
+        string,
+        {
+          readonly load?: unknown
+          readonly output?: unknown
+          readonly revalidate?: unknown
+          readonly revalidateTags?: unknown
+        }
+      >
     >
-    const declared = new Set((front.boundaries ?? []).map((boundary) => boundary.name))
+    const declared = new Map((front.boundaries ?? []).map((boundary) => [boundary.name, boundary]))
     for (const [name, entry] of Object.entries(loaders)) {
-      if (!declared.has(name)) {
+      const boundary = declared.get(name)
+      if (boundary === undefined) {
         throw routeError(
           `"${backend}" has boundaryLoaders["${name}"], but "${file}" declares no boundary named "${name}"`,
         )
@@ -771,6 +1007,7 @@ export function mergeRouteHalves(
       if (typeof entry?.load !== "function") {
         throw routeError(`boundaryLoaders["${name}"].load in "${backend}" must be a function`)
       }
+      assertSharedEntry(backend, name, boundary.mode === "shared", entry)
     }
     boundaries = front.boundaries?.map((boundary) => {
       const entry = loaders[boundary.name]
@@ -784,7 +1021,16 @@ export function mergeRouteHalves(
             : outputGuard(entry.output, `"${backend}"`, `${key}.output`),
         missing: `${key}.output in "${backend}"`,
       })
-      return { ...boundary, load } as BoundaryRegistration
+      const merged =
+        boundary.mode === "shared"
+          ? {
+              ...boundary,
+              load,
+              revalidate: entry.revalidate,
+              revalidateTags: entry.revalidateTags,
+            }
+          : { ...boundary, load }
+      return merged as BoundaryRegistration
     })
   }
   const module = {
@@ -1024,6 +1270,25 @@ const ancestorDirs = (file: string): string[] => {
   return dirs
 }
 
+/** Options for {@link buildManifest}. */
+export interface BuildManifestOptions {
+  /** Route files (as in `files`) whose frontend half exports `keepAlive`: see {@link exportsKeepAlive}. */
+  readonly keepAlive?: readonly string[]
+}
+
+// A declaration or an export list naming `keepAlive`, at the start of a line: a comment or a string
+// that mentions one does not start a line with `export`.
+const KEEP_ALIVE_EXPORT =
+  /^[ \t]*export[ \t]+(?:const|let|var)[ \t]+keepAlive\b|^[ \t]*export[ \t]*\{[^}]*\bkeepAlive\b[^}]*\}/m
+
+/**
+ * Whether a route file's source exports `keepAlive`, read without running it: the server and the
+ * client build both need the answer for every route, before any route module has loaded. A `.svelte`
+ * or `.vue` file exports it from its module script the same way. An export the scan cannot see (an
+ * `export *`) keeps nothing.
+ */
+export const exportsKeepAlive = (source: string): boolean => KEEP_ALIVE_EXPORT.test(source)
+
 /**
  * Build a manifest from route file paths (relative to the routes dir) + an `importer` that
  * turns a path into a lazy module loader. Pure - no fs. Throws at boot (the loud-and-early
@@ -1036,7 +1301,9 @@ const ancestorDirs = (file: string): string[] => {
 export function buildManifest(
   files: readonly string[],
   importer: (file: string) => () => Promise<RouteModule>,
+  options: BuildManifestOptions = {},
 ): Manifest {
+  const keepAliveFiles = new Set(options.keepAlive)
   const layoutDirs = new Set<string>()
   const layouts: Record<string, LayoutEntry> = {}
   const errorDirs = new Set<string>()
@@ -1202,6 +1469,7 @@ export function buildManifest(
         ...(notFoundIds.length > 0 ? { notFoundIds } : {}),
         ...(loadingIds.length > 0 ? { loadingIds } : {}),
         file,
+        ...(keepAliveFiles.has(file) ? { keepAlive: true } : {}),
         ...(backend === undefined ? {} : { backend }),
         load,
       })

package/src/navigation.ts

@@ -126,15 +126,27 @@ export type BrowserNavigate = (to: string | number, options?: NavigateOptions) =
 // teardown). Module-scoped: one app per page; absent on the server and before hydration.
 let browserNavigate: BrowserNavigate | undefined
 let browserRouter: ClientRouter | undefined
+let browserCloseBoundary: ((name: string) => void) | undefined
 
-/** Register (or clear, with `undefined`) the browser navigate and its router - called by
- * `installHistory`. Not for app use. */
+/** Register (or clear, with `undefined`) the browser navigate, its router and its boundary close -
+ * called by `installHistory`. Not for app use. */
 export function setBrowserNavigate(
   navigate: BrowserNavigate | undefined,
   router?: ClientRouter,
+  close?: (name: string) => void,
 ): void {
   browserNavigate = navigate
   browserRouter = router
+  browserCloseBoundary = close
+}
+
+/**
+ * Close the intercept boundary `name` and return to the page underneath it: back through the history
+ * entries the boundary added when the page's entry is there, otherwise by replacing the boundary's URL
+ * with the page's. A no-op on the server, before hydration, and when `name` holds no target.
+ */
+export function closeBoundary(name: string): void {
+  browserCloseBoundary?.(name)
 }
 
 /** The mounted client router, or `undefined` on the server / before `installHistory` has run. */

package/src/plugins/vite-zone-guard.ts

@@ -33,6 +33,12 @@ export interface ViteZoneGuardOptions {
   readonly generatedFiles?: readonly string[]
   /** The public-env prefix browser code may read (default `"PUBLIC_"`). */
   readonly publicEnvPrefix?: string
+  /**
+   * The coordinated compiler runs in this build and replaces each plain browser import of a
+   * `*.component.server.*` file with the component's reference, so such an import may resolve. Its
+   * file is still refused if it is ever loaded into the browser build.
+   */
+  readonly componentReferences?: boolean
 }
 
 /** Zones whose code runs in a browser, so may read only public environment variables. */
@@ -223,10 +229,17 @@ export function viteZoneGuard(options: ViteZoneGuardOptions): ViteZoneGuardPlugi
       if (!isClient(this, resolveOptions?.ssr)) return null
       const importerFile = withoutQuery(importer)
       if (!isAbsolute(importerFile)) return null
+      // The compiler replaces a plain import of a component with its reference; a query form such as
+      // `?raw` would ship the file itself.
+      const referenced = options.componentReferences === true && withoutQuery(source) === source
+      const denial = (classification: Classification, specifier?: string) =>
+        referenced && classification.zone === "component"
+          ? undefined
+          : browserDenial(classification, specifier)
       if (source.startsWith(".")) {
         const target = resolve(dirname(importerFile), withoutQuery(source))
         if (isFile(target)) {
-          const reason = browserDenial(classifier.classify(target))
+          const reason = denial(classifier.classify(target))
           if (reason !== undefined) refuse(this, target, reason, importerFile)
         }
         return null
@@ -240,7 +253,7 @@ export function viteZoneGuard(options: ViteZoneGuardOptions): ViteZoneGuardPlugi
       const resolved = await this.resolve(source, importer, { ...resolveOptions, skipSelf: true })
       const target = resolved === null || resolved.external ? undefined : withoutQuery(resolved.id)
       if (target !== undefined && isAbsolute(target) && isFile(target)) {
-        const reason = browserDenial(classifier.classify(target, source), source)
+        const reason = denial(classifier.classify(target, source), source)
         if (reason !== undefined) refuse(this, target, reason, importerFile)
       }
       return null

package/src/ppr.ts

@@ -0,0 +1,153 @@
+/**
+ * `@nifrajs/web/ppr` - experimental and unstable: partial prerendering.
+ *
+ * A route whose backend half exports `shellLoader` streams a shell shared by every visitor, then each
+ * `dynamic` boundary as it settles. Turn it on with `createWebApp({ experimental: { ppr:
+ * partialPrerendering({ shellChecks }) } })`, where `shellChecks` is the record `compileShells` returns
+ * for this deployment; a route left out of it renders whole. `pprShells(app)` reaches the shell cache,
+ * for `createInvalidator`'s `dataCaches` and for metrics. The server lives in this module, so an app
+ * that never imports it ships none of it. Backend-only: a browser build that reaches this module fails.
+ */
+import "@nifrajs/web/backend-only"
+import type { SharedHoleCtx, ShellCtx } from "./boundary.ts"
+import type { ShellCheckRecord } from "./internal/ppr/compile-shell.ts"
+import {
+  PPR_SERVER,
+  PPR_SETUP,
+  type PprServer,
+  type PprServerStats,
+  type PprSetup,
+} from "./internal/ppr/contract.ts"
+import { createPprIntegration } from "./internal/ppr/integration.ts"
+import { type PprOptions, resolvePprOptions } from "./internal/ppr/options.ts"
+import { isStoreSecret, MIN_STORE_SECRET_LENGTH } from "./internal/store-signature.ts"
+import type { CacheStore } from "./isr.ts"
+
+export {
+  type CanaryCarrier,
+  checkShellCanaries,
+  type ShellCanaryFinding,
+  type ShellCanaryOptions,
+} from "./internal/ppr/canary.ts"
+export {
+  type CompileShellsOptions,
+  compileShells,
+  ShellCheckError,
+  type ShellCheckRecord,
+} from "./internal/ppr/compile-shell.ts"
+export { PPR_DEFAULTS, type PprOptions } from "./internal/ppr/options.ts"
+export type { PprSetup, SharedHoleCtx, ShellCtx }
+
+export interface PprConfig {
+  /** From `compileShells` for this deployment; `"unchecked-development"` is refused in production. */
+  readonly shellChecks: ShellCheckRecord | "unchecked-development"
+  /** Overrides for the defaults in `PPR_DEFAULTS`. */
+  readonly options?: PprOptions
+  /**
+   * The deployment's public origin, such as `https://shop.example`, given to `shellLoader` and to the
+   * shell's `meta` as `origin`. Without it both get `""`: a shell is shared, so no visitor's Host
+   * header may supply it.
+   */
+  readonly origin?: string
+  /**
+   * A store the app's processes share, such as `new KVCacheStore(env.SHELLS)`, behind each process's
+   * own shells and shared hole frames: a process that has not built one reads it from here. Needs
+   * `storeSecret` and checked shells. A route whose tags the store cannot drop keeps its entries
+   * in-process.
+   */
+  readonly store?: CacheStore
+  /**
+   * Signs every entry written to `store`, so a store other services can write cannot hand visitors
+   * a page this app did not build. At least 32 characters, the same in every process.
+   */
+  readonly storeSecret?: string
+  /**
+   * The platform's name for this deployment, such as a commit or a version id. Shells are already
+   * kept apart by the client build and by each route's checked shell code; this adds to that.
+   */
+  readonly deployment?: string
+}
+
+/** `value` is exactly an http(s) origin: a scheme, a host and an optional port, nothing after. */
+function isOrigin(value: string): boolean {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    return false
+  }
+  return (url.protocol === "https:" || url.protocol === "http:") && url.origin === value
+}
+
+/**
+ * Experimental: partial prerendering for `createWebApp({ experimental: { ppr } })`. Options are
+ * checked here, at startup; each app the value is given to gets its own shell cache.
+ */
+export function partialPrerendering(config: PprConfig): PprSetup {
+  const options = resolvePprOptions(config.options)
+  const { origin, shellChecks, store, storeSecret, deployment } = config
+  if (origin !== undefined && !isOrigin(origin)) {
+    throw new TypeError(
+      `[nifra/web] experimental.ppr.origin must be an http(s) origin such as "https://shop.example", with no path; got ${JSON.stringify(origin)}`,
+    )
+  }
+  if (deployment !== undefined && (typeof deployment !== "string" || deployment === "")) {
+    throw new TypeError("[nifra/web] experimental.ppr.deployment must be a non-empty string")
+  }
+  if (store !== undefined) {
+    if (shellChecks === "unchecked-development") {
+      throw new TypeError(
+        "[nifra/web] experimental.ppr.store needs the build's shell check records: an unchecked shell is never shared",
+      )
+    }
+    if (!isStoreSecret(storeSecret)) {
+      throw new TypeError(
+        `[nifra/web] experimental.ppr.store needs storeSecret, at least ${MIN_STORE_SECRET_LENGTH} characters, to sign the shells it shares`,
+      )
+    }
+  }
+  return {
+    [PPR_SETUP]: (environment) =>
+      createPprIntegration(options, shellChecks, origin, environment, {
+        store,
+        storeSecret,
+        deployment,
+      }),
+  }
+}
+
+/** Types a backend half's `shellLoader` from its context; returns it unchanged. */
+export const defineShellLoader = <Data>(
+  loader: (ctx: ShellCtx) => Data | Promise<Data>,
+): ((ctx: ShellCtx) => Data | Promise<Data>) => loader
+
+/** Admission, shedding and unsent-byte counters of one app's partially prerendered responses. */
+export type PprStats = PprServerStats
+
+/** One app's shell cache. */
+export interface PprShells {
+  /**
+   * Drop every shell and shared hole frame whose `revalidateTags` listed `tag`, here and in the
+   * shared store; a build of either running now is not kept.
+   */
+  invalidateTag(tag: string): Promise<void>
+  stats(): PprStats
+}
+
+const isPprServer = (value: unknown): value is PprServer =>
+  typeof value === "object" && value !== null && "invalidateTag" in value && "stats" in value
+
+/**
+ * The shell cache of an app made with `experimental.ppr`. Pass it in `createInvalidator`'s
+ * `dataCaches` so a purge by tag also drops the shells built from the purged data.
+ */
+export function pprShells(app: object): PprShells {
+  const server: unknown = Reflect.get(app, PPR_SERVER)
+  if (!isPprServer(server)) {
+    throw new TypeError("[nifra/web/ppr] pprShells: this app was created without experimental.ppr")
+  }
+  return {
+    invalidateTag: (tag) => server.invalidateTag(tag),
+    stats: () => server.stats(),
+  }
+}