lit-ui-router-ssr 0.5.0 → 0.7.0

package/README.md

@@ -24,12 +24,17 @@ imports the pre-1.0 renderer or re-derives the incantation.
   on the page carries `defer-hydration` and renders nothing until the client's walk reaches it.
 - **The hydration signature.** A page rendered from a template opens on a JSON data block,
   `<script type="application/json" data-lit-ui-router-ssr>`, naming this package's version, the
-  state the router stood on, and that state's url parameter values. A page `renderShell` returns
-  as a string is written as-is, without one.
-- **The emit loop.** Verdict to file name, redirect to rules line, tally, warnings for paths that
-  matched nothing.
-- **The host rules file.** `_redirects` by default, every generated line paired with and without a
-  trailing slash. No SPA catch-all is ever written: one turns every 404 into a 200.
+  state the router stood on, that state's url parameter values, and the resolved values the
+  `payload` hook supplies. A page `renderShell` returns as a string is written as-is, without one.
+- **The lit render inside the emit loop.** The loop itself — verdict to file name, redirect to
+  rules line, the `_redirects` file, delegating states skipped, tally, warnings for paths that
+  matched nothing — is
+  `prerender` from `ui-router-server/prerender`, which takes any render. This package's `prerender`
+  supplies the lit one and takes the same options, plus `router`, `renderShell`, `document`,
+  `root`, `elementRenderers`, `payload`, `responses` and `origin`. No SPA catch-all is ever written: one
+  turns every 404 into a 200.
+- **Response states after settle.** `responder` runs the handler bound to a response state's name
+  with the resolves its transition landed with.
 - **`<ui-view>` on both sides.** `UiViewRenderer` fills the element's light DOM on the server;
   `lit-ui-router-ssr/client` adopts what it drew.
 
@@ -48,6 +53,9 @@ npm install lit-ui-router-ssr
 the client half, so a bundle takes one or the other, never both. `@lit-labs/ssr-client` is optional:
 install it when you import `lit-ui-router-ssr/client`.
 
+The `lit-ui-router` peer is `^1.19.0`: the server renders a view through the helper `<ui-view>`
+renders through, and the client hands a served class element to the view it wakes.
+
 ## Quick Start
 
 ```typescript
@@ -66,9 +74,13 @@ const result = await prerender({
   document: (body, { path }) => fillShell(titles.get(path), body),
 });
 
-console.log(result.tally); // { shell: 2, redirect: 1, notFound: 0, document: 1 }
+console.log(result.tally); // { shell: 2, redirect: 1, notFound: 0, delegate: 0, document: 1 }
 ```
 
+`result.delegated` lists the paths that matched a delegating state. They get no page and no rules
+line, so route them to your server; on Cloudflare, list them in the Worker's
+`assets.run_worker_first` so the asset layer doesn't answer them first.
+
 `result.pages` lists every artefact in enumeration order, `result.rules` every line the host file
 carries, and `result.warnings` the paths that matched no route and had no projection to fall back
 on. `dryRun: true` plans all of it and writes nothing.
@@ -119,10 +131,59 @@ A page fails to land in four ways, and each rejects rather than hangs:
 `settle()` never calls `router.start()`, which runs once per router: it drives `urlService`
 directly, so a page loop calls it once per path on the same router, started or not.
 
+## Response states
+
+A [response state](https://lit-ui-router.dev/packages/server#response-states) answers with a
+`Response` built from its resolves instead of a page. `responder(router, responses)` settles
+`router` on the verdict's subpath, query included, runs the handler bound to the landed state's
+name with that transition's resolves (inherited ones included) and the request, and returns the
+`Response` as built; a HEAD gets it without its body. A resolve that throws rejects before any
+handler runs. It fits the fetch adapter's `serveResponse`, and `prerender` takes the same handlers
+as `responses`, writing a 2xx body at the path its url spells or a 3xx as a rules line. See
+[response states](https://lit-ui-router.dev/packages/ssr#response-states).
+
+## Adopting the resolves on boot
+
+The `payload` option hands each rendered page's landed transition to a hook, which returns the
+resolve payload to write. `dehydrate` from `ui-router-server/ssr` draws one, and the hook decides what to do with the resolves it leaves out:
+
+```typescript
+import { prerender } from 'lit-ui-router-ssr';
+import { dehydrate } from 'ui-router-server/ssr';
+
+await prerender({
+  // mounts, router, paths, renderShell, …
+  payload: (transition, { path }) => {
+    const { payload, unserializable } = dehydrate(transition);
+
+    for (const { state, token } of unserializable)
+      console.warn(`${path}: ${state}.${token} re-runs on the client`);
+
+    return payload;
+  },
+});
+```
+
+The payload's `resolves` go into the page's hydration signature, beside `version`, `state` and
+`params`, so the one block is the payload. `bootstrap()` seeds the boot transition from it before
+the router starts: each resolve the page was drawn with adopts its value in place of running its
+function. Every other resolve runs as it would without one: a value `dehydrate` left out, a
+`NOWAIT` resolve, every resolve of a boot that lands on another state or other parameters, and
+every resolve of a page whose block carries no `resolves`. Without the hook no page carries
+resolves. What `dehydrate` draws, and which values it leaves out, is in
+[its documentation](https://lit-ui-router.dev/packages/server#handing-resolves-to-the-client).
+
+A value plain JSON can't carry, such as a `Date`, travels through a transporter. Pass the same
+`transport` to `dehydrate` in the hook and to `bootstrap()`: the signature keeps the payload's
+`transported` marks, and `bootstrap()` hands `transport` to `seed`. See
+[values beyond plain JSON](https://lit-ui-router.dev/packages/server#values-beyond-plain-json).
+
 ## The routed view, drawn on the server
 
-`elementRenderers` defaults to `[UiViewRenderer]` — not `@lit-labs/ssr`'s `[LitElementRenderer]`,
-which wraps every custom element in a declarative shadow root it never asked for. `UiViewRenderer`
+`elementRenderers` defaults to `[UiViewRenderer, LightElementRenderer]` — not `@lit-labs/ssr`'s
+`[LitElementRenderer]`, which wraps every custom element in a declarative shadow root it never asked
+for. `LightElementRenderer` answers only for an element that opted in (see
+[Light-DOM elements](#light-dom-elements)). `UiViewRenderer`
 answers for `ui-view`: it registers the view at the address its `name` attribute and enclosing
 `<ui-view>`s spell, takes the `ViewConfig` the registration syncs back, and writes the routed
 component into the element's light DOM between the part markers the element's own `render()`
@@ -130,6 +191,20 @@ hydrates against. An address no state routes gets empty markers. That pair stays
 hydrating the view's surroundings reads it as the `uiViewSlot()` part and stops there; every marker
 between it carries a prefix, so the same walk reads past the view's interior.
 
+The template comes from `lit-ui-router`'s own render helper, the one `<ui-view>`'s `render()` calls,
+so the served markup and the client's first render share one source. A routed `LitElement` class,
+plain or `sticky`, prerenders too: `lit-ui-router` builds the element and assigns its props, and
+`LitElementRenderer` writes it, shadow root included, into the slot `<ui-view>` places a class in.
+At the wake the served view hands that element to `lit-ui-router`, which adopts it instead of
+building its own, so the element the server wrote is the element the client keeps. A class that
+renders into its own light DOM prerenders into it when it uses
+[`LightDomHydrating`](#light-dom-elements), and hydrates those nodes in place. Without it, the class
+is written as its bare element, with no shadow root to hide its render, and renders on the client. A
+class must be on the `customElements` registry to prerender.
+
+The served `<ui-view>` markup is internal to this package and `lit-ui-router` and changes with them.
+Post-processing of prerendered HTML keys on the [hydration signature](#the-client-half) block.
+
 The use site opts in with `uiViewSlot()`, which is what reaches the renderer's light-DOM render and
 commits nothing on the client:
 
@@ -172,8 +247,8 @@ card empty:
 ```
 
 `@lit-labs/ssr` writes a `.prop=${…}` binding as its part marker and nothing else — no attribute, no
-child, no value. Setting the property is an element renderer's job, and `elementRenderers` defaults
-to `[UiViewRenderer]`, which answers for `ui-view` alone. The card has no renderer, so nothing on
+child, no value. Setting the property is an element renderer's job, and the default `elementRenderers`
+answer for `ui-view` and for opted-in light-DOM elements alone. The card has no renderer, so nothing on
 the server sets `post` or runs its `render()`: the card first draws on the client, once hydration
 sets the property, and the served page shows an empty tag where it stands.
 
@@ -233,11 +308,16 @@ shadow root:
 
 ```typescript
 import { LitElementRenderer } from '@lit-labs/ssr';
-import { prerender, UiViewRenderer } from 'lit-ui-router-ssr';
+import {
+  LightElementRenderer,
+  prerender,
+  UiViewRenderer,
+} from 'lit-ui-router-ssr';
 
 await prerender({
   // …
-  elementRenderers: [UiViewRenderer, LitElementRenderer],
+  // The list replaces the default; LightElementRenderer stays ahead of the shadow-root renderer.
+  elementRenderers: [UiViewRenderer, LightElementRenderer, LitElementRenderer],
 });
 ```
 
@@ -270,16 +350,14 @@ registers `<ui-view>`. That entry defines `<ui-router>` from core and `<ui-view>
 `withServedRender(UiView)`. Every value the app takes from the router — `UIRouterLit`, `srefHref`,
 `srefActiveClass`, `srefAriaCurrent` — comes from `lit-ui-router/pure`, which registers nothing;
 the root entry registers the plain `<ui-view>` as a side effect, and imported after this one it
-warns that the tag is already defined. Then the router boots and one call adopts the page:
+warns that the tag is already defined. Then one call boots the router and adopts the page:
 
 ```typescript
 import 'lit-ui-router-ssr/register';
 import { UIRouterLit, srefHref } from 'lit-ui-router/pure';
-import { hydrateRoot } from 'lit-ui-router-ssr/client';
+import { bootstrap } from 'lit-ui-router-ssr/client';
 
-router.start();
-await booted; // the first successful transition
-const release = hydrateRoot(root, page(router));
+await bootstrap(router, root, page(router));
 ```
 
 A `<ui-view>` another class already defined throws, naming both ways out.
@@ -325,29 +403,45 @@ The result still extends core's `UiView`, so an enclosing view adopts it as a pa
 
 ## The client half
 
-`lit-ui-router-ssr/client` is the adopt side — no import side effects. The router boots
-first, and one call adopts the page:
+`lit-ui-router-ssr/client` is the adopt side — no import side effects. One call boots the router
+and adopts the page, or renders it cold, and resolves once the page is live:
 
 ```typescript
-import { hydrateRoot, uiViewSlot } from 'lit-ui-router-ssr/client';
-
-const booted = new Promise<void>((resolve) => {
-  const off = router.transitionService.onSuccess({}, () => {
-    off();
-    resolve();
-  });
-});
-router.start();
-await booted;
+import { bootstrap } from 'lit-ui-router-ssr/client';
 
-const release = hydrateRoot(root, page(router));
-if (!release) render(page(router), root);
+const { outcome } = await bootstrap(router, root, page(router));
 ```
 
-- **The sequence is the contract.** `router.start()`, await its first successful transition, then
-  `hydrateRoot()`. The walk commits `.uiRouter` onto `<ui-router>` and each `<ui-view>` re-seeks the
-  router before its own first render, so every view finds the settled router rather than the
-  placeholder it registered against. Nothing constrains when `lit-ui-router-ssr/register` is imported.
+- **`bootstrap(router, container, value, options?)` owns the boot.** It reads the container's
+  signature, starts the router, waits for the boot transition to land — following redirects to the
+  one that succeeds — then runs `hydrateRoot()`. The walk commits `.uiRouter` onto `<ui-router>` and
+  each `<ui-view>` re-seeks the router before its own first render, so every view finds the settled
+  router rather than the placeholder it registered against. The call waits for every awake
+  `<ui-view>`, nested ones included, to finish updating, then releases the adopter. It resolves with
+  `outcome` — `adopted` or `cold` — and `signature` (`BootstrapSignature`): `matched` when the boot
+  landed on the state and url parameters the signature names, `elsewhere` when the document carried
+  a signature and the boot landed somewhere else or landed no transition, and `absent` when it
+  carried none. Nothing constrains when `lit-ui-router-ssr/register` is imported.
+- **The cold path is the same call.** A container with nothing to adopt is emptied and `value`
+  rendered into it before the router starts. A boot transition that fails, a url that starts none,
+  and a root `hydrate()` that throws over a mutated document all empty the container and render
+  `value` cold too, and the call resolves with the cause in `error` rather than rejecting.
+- **The boot decides mismatches once.** A boot that lands where the document was drawn adopts every
+  view, and a view that still mismatches warns in development: the two halves render that template
+  differently. A boot that lands elsewhere — one static document served for a family of urls, or a
+  redirect — adopts the views that match and renders the rest cold without a warning each. A view
+  whose state, or whose url parameters (its own and inherited), differ from the drawn ones renders
+  cold. Once the page is live, a boot into another state warns once in development, naming both
+  states and how many views rendered cold; a boot into other url parameters of the drawn state is
+  silent.
+- **The boot transition is seeded.** The payload the signature carries is handed to `seed()` from
+  `ui-router-server/ssr/client` before the router starts, so the boot transition adopts the
+  resolved values the prerender drew in place of running their resolve functions.
+  `options.payload` takes its place when given.
+- **`hydrateRoot()` is the step underneath.** An app that owns its own boot calls
+  `seed(router, readResolvePayload(root))` and `router.start()`, awaits the first successful
+  transition, then `hydrateRoot(root, page(router))`, and renders `page(router)` itself when that
+  returns `false`.
 - **The signature decides first.** `hydrateRoot()` reads the container's hydration signature before
   it touches the document, and returns `false` over an emptied container when there is none — a
   cold client render, a dev server, a page from an earlier `prerender()`, a string `renderShell` —
@@ -368,7 +462,9 @@ if (!release) render(page(router), root);
   before that update stays asleep, holding its nodes, until it is attached again. The walk pins the
   adopter to every served view it passes, so that view is adopted on its return even once the root
   provider is released. A view the walk never reached drops those nodes, renders cold, and warns in
-  development.
+  development. A deferred element no walk reaches — one the render wrote no marker for — wakes
+  with the adoption of the view that holds it, after that view's hydrate, or with the root walk when
+  no view holds it.
 - **The prefix is the protocol, and both halves are here.** `UiViewRenderer` writes a plain outer
   part pair around each view's routed markup and prefixes every marker between them; `hydrate()`
   reads past a prefixed comment, so the walk hydrating a view's surroundings stops at that pair. The
@@ -392,11 +488,67 @@ if (!release) render(page(router), root);
   (`uiViewAdoptEventName`), bubbling and composed, with `detail.outcome` one of `adopted` — its
   served nodes are the live ones — `fell-back` — a mismatch or a lost pair, with `detail.error`
   carrying the cause — or `none`, nothing to adopt. It fires once per view, parent first, in
-  production as in development. `hydrateRoot()`'s `onAdopt(view, outcome, error)` option receives
+  production as in development. The `onAdopt(view, outcome, error)` option of `bootstrap()` and `hydrateRoot()` receives
   the same reports for every view its walk reaches, a view the pin adopts after the release included.
 - **A mutated document throws.** `hydrateRoot()` rethrows what `hydrate()` threw, over a container it
   first empties. The caller renders into it.
 
+### Light-DOM elements
+
+A consumer's own `LitElement` that renders into its light DOM opts in to the same sleep-then-adopt
+cycle with `LightDomHydrating(Base)` from `lit-ui-router-ssr/client`. `LightElementRenderer` from
+`lit-ui-router-ssr`, one of `prerender()`'s default renderers, draws it on the server, and
+`lightSlot()` marks the hole at the use site:
+
+```typescript
+import { html, LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { LightDomHydrating, lightSlot } from 'lit-ui-router-ssr/client';
+
+export class AppCard extends LightDomHydrating(LitElement) {
+  @property() label = '';
+
+  render() {
+    return html`<p>${this.label}</p>`;
+  }
+}
+
+export const card = (label: string) =>
+  html`<app-card .label=${label}>${lightSlot()}</app-card>`;
+```
+
+- **Each class opts in.** The mixin stamps a `Symbol.for` brand on the class it returns, and the
+  renderer matches that brand, so a subclass stays opted in, the base class does not, and a second
+  copy of this package recognises it. An element that did not opt in is served empty and renders
+  cold.
+- **The server writes `render()` into the light DOM.** `LightElementRenderer` extends
+  `@lit-labs/ssr`'s `LitElementRenderer`: it builds the element, sets its attributes and properties,
+  runs `willUpdate`, and writes the render where a shadow root would go, prefixing its markers as
+  `UiViewRenderer` prefixes a view's. Custom elements inside it, `<ui-view>` included, render too.
+  An explicit `elementRenderers` replaces the default, so keep it in that list, ahead of any
+  `LitElementRenderer`: the first renderer that matches a class wins. A render that awaits is not
+  served.
+- **`lightSlot()` is the hole.** It is `uiViewSlot()` under a name that does not read as a view: the
+  server reaches the renderer through it, and on the client it wakes the element when the
+  enclosing walk reaches it, parent first, and pins the adopter to it.
+- **The element wakes through the adopter.** It sleeps under `defer-hydration`, which `prerender()`
+  writes on every custom element, and its first update requests `adoptUiViewContext`. The adopter
+  hydrates `render()` against the served nodes in place, then wakes the elements inside it. A view's
+  reveal stops at a light-DOM element and the element's stops at a view or another light-DOM
+  element, so each interior waits for its own wake. With no adopter, the element drops the served
+  nodes and renders cold, warning in development.
+- **It reports through its own event.** Each opted-in element dispatches `light-dom:adopt`
+  (`lightDomAdoptEventName`) with the same `detail` as `ui-view:adopt`. `onAdopt`, and the count of
+  views `bootstrap()` rendered cold, report views only.
+- **A mismatch falls back.** A hydrate that throws drops the element's served nodes, and it renders
+  cold, warning in development; its surroundings keep theirs.
+- **An author child with bindings of its own falls back every time.** A child the use site writes
+  beside `lightSlot()` keeps its markers ahead of the element's pair, and the element's hydrate
+  meets them first. Static author children are kept, ahead of the render, as they are in a
+  `<ui-view>`.
+- **`static styles` do not apply.** A light-DOM element has no shadow root to adopt them into; it
+  takes the document's styles.
+
 ### How this compares
 
 Two axes separate the hydration models in circulation: where the code that wakes the markup comes
@@ -419,6 +571,46 @@ the grid entirely.
 
 The [guide](https://lit-ui-router.dev/packages/ssr#how-this-compares) carries the longer discussion.
 
+## Measuring the round trip
+
+`lit-ui-router-ssr/testing` counts how many of the server's elements survive the boot. It imports
+nothing — no lit, no router — and runs anywhere there is a DOM. `stampServed(root)` takes every
+element under `root`, open shadow roots included, before the client boots; `countRetained(stamp)`
+returns `{ served, retained, removed, added }` after it. A hydrated page keeps `removed` at 0. A view
+the client rendered over counts its served elements as removed and its new ones as added; an element
+a component draws in `firstUpdated`, or the shadow `<slot>` each `<ui-router>` renders, counts only
+as added.
+
+```ts
+import { countRetained, stampServed } from 'lit-ui-router-ssr/testing';
+
+const stamp = stampServed(container); // after the prerender is parsed in, before bootstrap()
+await bootstrap(router, container, page(router));
+expect(countRetained(stamp)).toMatchObject({ removed: 0 });
+```
+
+In a browser the stamp and the count must run in the page. Each helper is self-contained, so its
+source text is valid page script. In Playwright, an init script stamps the body when parsing ends,
+before module scripts run:
+
+```ts
+import { countRetained, stampServed } from 'lit-ui-router-ssr/testing';
+
+await page.addInitScript(`
+  const stampServed = ${stampServed};
+  window.countRetained = ${countRetained};
+  document.addEventListener('readystatechange', () => {
+    if (document.readyState === 'interactive') window.servedStamp = stampServed(document.body);
+  });
+`);
+await page.goto('/sheet/7B/');
+await page.waitForFunction(() => !document.querySelector('[defer-hydration]'));
+
+expect(await page.evaluate('countRetained(servedStamp)')).toMatchObject({
+  removed: 0,
+});
+```
+
 ## Documentation
 
 - [Guide](https://lit-ui-router.dev/packages/ssr)

package/dist/client.d.ts

@@ -1,22 +1,26 @@
 import { renderLight } from "@lit-labs/ssr-client/directives/render-light.js";
 import type { RenderOptions } from "lit";
+import type { UIRouterLit } from "lit-ui-router/pure";
+import type { ResolvePayload, SeedOptions } from "ui-router-server/ssr/client";
 import type { HydrationSignature } from "./signature.js";
 export { adoptUiViewContext, type AdoptableView, type AdoptUiViewContext, type AdoptUiViewContextKey } from "./adopt-context.js";
 export { isServedViewClass, type ServedUiView, type ServedUiViewConstructor, servedViewBrand, withServedRender } from "./served-view.js";
+export { LightDomHydrating, type LightDomHydratingConstructor, type LightDomHydratingElement, type LitElementConstructor } from "./light-dom.js";
 export type { HydrationSignature } from "./signature.js";
 /**
 * What a served `<ui-view>`'s wake came to.
 *
 * - `adopted`: the element hydrated its served nodes, and they are the live ones.
 * - `fell-back`: the served pair did not match the render the client booted
-*   into, or was lost; the view dropped the served interior and rendered cold.
+*   into, was drawn for another state or other url parameters, or was lost;
+*   the view dropped the served interior and rendered cold.
 * - `none`: nothing to adopt — an empty served pair, the address no state
 *   routed, or a view the document served no markers for.
 */
 export type AdoptOutcome = "adopted" | "fell-back" | "none";
 /**
 * The name of the event a served `<ui-view>` dispatches once its wake's
-* outcome is known, in the `ui-view:` house style of the served markers.
+* outcome is known.
 */
 export declare const uiViewAdoptEventName: "ui-view:adopt";
 /**
@@ -25,7 +29,7 @@ export declare const uiViewAdoptEventName: "ui-view:adopt";
 export interface UiViewAdoptDetail {
 	/** What the wake came to. */
 	readonly outcome: AdoptOutcome;
-	/** What `hydrate()` threw, or why the pair was lost; present only on `fell-back`. */
+	/** What `hydrate()` threw, or why the view did not adopt; present only on `fell-back`. */
 	readonly error?: unknown;
 }
 /**
@@ -34,6 +38,14 @@ export interface UiViewAdoptDetail {
 */
 export type UiViewAdoptEvent = CustomEvent<UiViewAdoptDetail>;
 /**
+* The event a light-DOM hydrating element dispatches from itself at its wake,
+* once its outcome is known. It carries the same detail as {@link
+* uiViewAdoptEventName}, and it does not reach `onAdopt`, which reports views.
+*/
+export declare const lightDomAdoptEventName: "light-dom:adopt";
+/** A light-DOM hydrating element's hydration outcome. */
+export type LightDomAdoptEvent = CustomEvent<UiViewAdoptDetail>;
+/**
 * Receives each served view's outcome, as {@link HydrateRootOptions.onAdopt}.
 */
 export type AdoptReporter = (view: Element, outcome: AdoptOutcome, error?: unknown) => void;
@@ -53,6 +65,8 @@ declare global {
 	interface HTMLElementEventMap {
 		/** A served `<ui-view>`'s hydration outcome; see {@link UiViewAdoptEvent}. */
 		"ui-view:adopt": UiViewAdoptEvent;
+		/** A light-DOM hydrating element's hydration outcome; see {@link LightDomAdoptEvent}. */
+		"light-dom:adopt": LightDomAdoptEvent;
 	}
 }
 /**
@@ -77,6 +91,21 @@ declare global {
 */
 export declare const uiViewSlot: typeof renderLight;
 /**
+* The hole a `LightDomHydrating` element fills, written at the use site: the
+* {@link uiViewSlot} directive under a name that does not read as a view.
+*
+* On the server it reaches `LightElementRenderer`'s `renderLight()`, so the
+* element's own render goes where the template puts it. On the client it wakes
+* the element when the enclosing walk reaches it, parent first, and pins the
+* adopter to it.
+*
+* @example
+* ```ts
+* html`<app-card .title=${title}>${lightSlot()}</app-card>`;
+* ```
+*/
+export declare const lightSlot: typeof renderLight;
+/**
 * Reads the hydration signature `prerender()` wrote ahead of the render a
 * container holds: the version of this package that drew the document, and
 * the state and parameter values it was drawn for.
@@ -97,7 +126,7 @@ export declare const uiViewSlot: typeof renderLight;
 *
 * await booted;
 * const { state } = readHydrationSignature(root) ?? {};
-* const drawnForBoot = state === router.globals.current.name;
+* const bootedWhereDrawn = state === router.globals.current.name;
 * const release = hydrateRoot(root, page(router));
 * ```
 *
@@ -107,6 +136,30 @@ export declare const uiViewSlot: typeof renderLight;
 */
 export declare function readHydrationSignature(container: ParentNode): HydrationSignature | null;
 /**
+* Reads the resolve payload `prerender()` wrote into the container's
+* {@link readHydrationSignature | hydration signature}: the state and url
+* parameters the document was drawn for, and the values its resolves settled
+* on, keyed by state name, then by resolve token.
+*
+* {@link bootstrap} reads it on its own. A boot that calls {@link hydrateRoot}
+* directly hands it to `seed` from `ui-router-server/ssr/client` before the
+* router starts.
+*
+* @example
+* ```ts
+* import { readResolvePayload } from 'lit-ui-router-ssr/client';
+* import { seed } from 'ui-router-server/ssr/client';
+*
+* seed(router, readResolvePayload(root));
+* router.start();
+* ```
+*
+* @param container - the element the server's markup was written into
+* @returns the payload, or `undefined` when the container holds no signature,
+* one from another release line of this package, or one without `resolves`
+*/
+export declare function readResolvePayload(container: ParentNode): ResolvePayload | undefined;
+/**
 * Adopts a server-rendered container, and the `<ui-view>`s that wake under it.
 *
 * The container's {@link readHydrationSignature | hydration signature} is read
@@ -132,7 +185,9 @@ export declare function readHydrationSignature(container: ParentNode): Hydration
 * outside `container`, or one whose attribute the app cleared itself after the
 * release — is answered by nobody: core drops its held nodes and warns in
 * development. An element the render deferred and wrote no marker for is woken
-* once the walk has finished, since nothing in the walk reaches it.
+* once the walk has finished, since nothing in the walk reaches it — except
+* one inside a `<ui-view>`, which wakes once that view has hydrated its own
+* render, so a routed element never wakes ahead of the view that routes it.
 *
 * The provider answers synchronously and stops immediate propagation, so an
 * outer provider never answers the same request twice. It outlives this call,
@@ -150,11 +205,12 @@ export declare function readHydrationSignature(container: ParentNode): Hydration
 * A `hydrate()` that throws is rethrown, over a container emptied the same
 * way. The caller renders into it.
 *
-* The boot is the router first: `router.start()`, await its first successful
-* transition, then this call. The walk commits `.uiRouter` onto `<ui-router>`
-* and each woken `<ui-view>` re-seeks the router before its own first render,
-* so the views find the settled router rather than the placeholder they
-* registered against. Nothing constrains when `lit-ui-router-ssr/register` is
+* {@link bootstrap} runs the whole boot around this call. Called directly, the
+* boot is the router first: `seed` the router with {@link readResolvePayload},
+* `router.start()`, await its first successful transition, then this call.
+* The walk commits `.uiRouter` onto `<ui-router>` and each woken `<ui-view>`
+* re-seeks the router before its own first render, so the views find the
+* settled router rather than the placeholder they registered against. Nothing constrains when `lit-ui-router-ssr/register` is
 * imported.
 *
 * @example
@@ -172,4 +228,105 @@ export declare function readHydrationSignature(container: ParentNode): Hydration
 * @returns the function that releases the provider, or `false`, over an emptied container, when there is nothing to adopt — no signature, as on a cold client render or a dev server, one from another release line, or one no render marker follows
 */
 export declare function hydrateRoot(container: HTMLElement, value: unknown, options?: HydrateRootOptions): false | (() => void);
+/** What {@link bootstrap} came to, once the page is live. */
+export type BootstrapOutcome = "adopted" | "cold";
+/**
+* How a boot compares with the {@link readHydrationSignature | hydration
+* signature} the document carried.
+*
+* - `matched`: the boot transition landed on the state and url parameters the
+*   signature names.
+* - `elsewhere`: the document carried a signature, and the boot landed on
+*   another state or other parameters — a redirect, or a static host serving
+*   one document for a family of urls. A signed document whose boot landed no
+*   transition reports this too, beside `outcome: 'cold'` and its `error`.
+* - `absent`: the document carried no signature.
+*
+* A signature from another release line, or one no render marker follows, is
+* still compared, though the container renders cold.
+*/
+export type BootstrapSignature = "matched" | "elsewhere" | "absent";
+/** What {@link bootstrap} resolves with. */
+export interface BootstrapResult {
+	/**
+	* `adopted`: the served document was hydrated, and each served view reported
+	* its own {@link AdoptOutcome}. `cold`: the container was emptied and the
+	* template rendered into it.
+	*/
+	readonly outcome: BootstrapOutcome;
+	/** How the boot compares with the document's hydration signature; see {@link BootstrapSignature}. */
+	readonly signature: BootstrapSignature;
+	/**
+	* The boot transition's `Rejection`, or what the root `hydrate()` threw;
+	* present only on a cold boot that one of them caused.
+	*/
+	readonly error?: unknown;
+}
+/**
+* {@link bootstrap}'s options: {@link HydrateRootOptions}, plus the boot
+* transition's seed and the `transport` handed to `seed` with it.
+*/
+export interface BootstrapOptions extends HydrateRootOptions, SeedOptions {
+	/**
+	* Resolved values the document was drawn with, handed to `seed` from
+	* `ui-router-server/ssr/client` before the router starts, so the boot
+	* transition adopts them in place of running their resolve functions. It
+	* takes the place of the payload the container's signature carries.
+	*/
+	readonly payload?: ResolvePayload;
+}
+/**
+* Boots `router` into the page `container` holds, and resolves once that page
+* is live.
+*
+* It owns the whole client boot. The boot transition is seeded first, with
+* `options.payload` when given, and otherwise with the resolves the
+* container's signature carries ({@link readResolvePayload}): each resolve the
+* document was drawn with adopts its value in place of running its function,
+* and every other resolve runs as it would without a payload. The
+* container's {@link readHydrationSignature | signature} is read before
+* anything else touches the document; a container {@link
+* hydrateRoot} would not adopt — no signature, another release line, stripped
+* markers — is emptied and `value` rendered into it at once, and the router
+* then starts. Otherwise the router starts, the call waits for the boot
+* transition to land, following redirects to the one that succeeds, and then
+* hydrates the container with `value`.
+*
+* The boot decides once what the page does:
+*
+* - The boot lands where the signature says the document was drawn: every
+*   served view adopts, and a view that still mismatches warns in development,
+*   since that is a template the two halves render differently.
+* - The boot lands elsewhere — a static host serving one document for a
+*   family of urls, or a redirect: the views that match adopt, and the views
+*   that differ render cold without a warning of their own. A view whose
+*   state, or whose url parameters, its own and inherited, differ from the
+*   drawn ones renders cold. Once the page is live, a boot into another state
+*   warns once in development, naming both states and how many views rendered
+*   cold; a boot into other url parameters of the drawn state is silent.
+* - The boot fails, or the url starts no transition: the container is emptied
+*   and `value` rendered cold. The root `hydrate()` throwing, as over a
+*   mutated document, does the same. The call resolves rather than rejects.
+*
+* Every served view still reports its own {@link AdoptOutcome}, as a {@link
+* UiViewAdoptEvent} and to `options.onAdopt`. The call waits for each awake
+* `<ui-view>` to finish updating, nested views included, then releases the
+* adopter `hydrateRoot()` provided; a view the app detached keeps its pin.
+*
+* @example
+* ```ts
+* import { bootstrap } from 'lit-ui-router-ssr/client';
+*
+* const { outcome } = await bootstrap(router, root, page(router));
+* ```
+*
+* @param router - the client router, its states registered and not yet started
+* @param container - the element the server's markup was written into, or an empty one
+* @param value - the same template the server rendered, with every `<ui-view>` hole empty
+* @param options - lit render options, `onAdopt`, and the boot transition's `payload` and `transport`
+* @returns what the boot came to, once every awake view has updated
+* @throws what `router.start()` throws, as on a router already started
+* @throws the `TypeError` `seed` throws on a payload with no `resolves`, before the router starts
+*/
+export declare function bootstrap(router: UIRouterLit, container: HTMLElement, value: unknown, options?: BootstrapOptions): Promise<BootstrapResult>;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","mappings":"AAOA,SAAS,mBAAmB;AAI5B,cAAyB,qBAAqB;AAW9C,cAAc,0BAA0B;AAExC,SACE,yBACK,oBACA,yBACA,6BACA;AAEP,SACE,wBACK,mBACA,yBACL,iBACA,wBACK;AAEP,cAAc,0BAA0B;;;;;;;;;;AAcxC,YAAY,eAAe,YAAY,cAAc;;;;;AAMrD,OAAO,cAAM,sBAAuB;;;;AAKpC,iBAAiB,kBAAkB;;UAExB,SAAS;;UAET;AACX;;;;;AAMA,YAAY,mBAAmB,YAAY;;;;AAK3C,YAAY,iBACV,MAAM,SACN,SAAS,cAET;;;;;AAOF,iBAAiB,2BAA2B,cAAc;;;;;;CAMxD,UAAU;AACZ;eAEe;WACH,oBAAoB;;EAE5B,iBAAiB;CACnB;AACF;;;;;;;;;;;;;;;;;;;;;AAgEA,OAAO,cAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmVhC,OAAO,iBAAS,uBACd,WAAW,aACV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4IH,OAAO,iBAAS,YACd,WAAW,aAEX,gBACA,UAAS,qBACR","names":[],"ignoreList":[],"sources":["../src/client.ts"]}
+{"version":3,"file":"client.d.ts","mappings":"AAQA,SAAS,mBAAmB;AAK5B,cAAyB,qBAAqB;AAM9C,cAAc,mBAAmB;AAEjC,cAAc,gBAAgB,mBAAmB;AAYjD,cAAc,0BAA0B;AAExC,SACE,yBACK,oBACA,yBACA,6BACA;AAEP,SACE,wBACK,mBACA,yBACL,iBACA,wBACK;AAEP,SACE,wBACK,mCACA,+BACA,6BACA;AAEP,cAAc,0BAA0B;;;;;;;;;;;AAexC,YAAY,eAAe,YAAY,cAAc;;;;;AAMrD,OAAO,cAAM,sBAAuB;;;;AAKpC,iBAAiB,kBAAkB;;UAExB,SAAS;;UAET;AACX;;;;;AAMA,YAAY,mBAAmB,YAAY;;;;;;AAO3C,OAAO,cAAM,wBAAyB;;AAGtC,YAAY,qBAAqB,YAAY;;;;AAK7C,YAAY,iBACV,MAAM,SACN,SAAS,cAET;;;;;AAOF,iBAAiB,2BAA2B,cAAc;;;;;;CAMxD,UAAU;AACZ;eAEe;WACH,oBAAoB;;EAE5B,iBAAiB;;EAEjB,mBAAmB;CACrB;AACF;;;;;;;;;;;;;;;;;;;;;AAgEA,OAAO,cAAM,mBAAmB;;;;;;;;;;;;;;;AAgBhC,OAAO,cAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgZ/B,OAAO,iBAAS,uBACd,WAAW,aACV;;;;;;;;;;;;;;;;;;;;;;;;AA6BH,OAAO,iBAAS,mBACd,WAAW,aACV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2JH,OAAO,iBAAS,YACd,WAAW,aAEX,gBACA,UAAS,qBACR;;AAsCH,YAAY,mBAAmB,YAAY;;;;;;;;;;;;;;;;AAiB3C,YAAY,qBAAqB,YAAY,cAAc;;AAG3D,iBAAiB,gBAAgB;;;;;;UAMtB,SAAS;;UAET,WAAW;;;;;UAKX;AACX;;;;;AAMA,iBAAiB,yBAAyB,oBAAoB,YAAY;;;;;;;UAO/D,UAAU;AACrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6LA,OAAO,iBAAe,UACpB,QAAQ,aACR,WAAW,aAEX,gBACA,UAAS,mBACR,QAAQ","names":[],"ignoreList":[],"sources":["../src/client.ts"]}