@vidact/start 0.2.0-beta.6 → 0.2.0-beta.8

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @vidact/start
 
+## 0.2.0-beta.8
+
+### Patch Changes
+
+- Updated dependencies [e480658]
+  - @vidact/runtime@0.2.0-beta.8
+  - @vidact/vite@0.2.0-beta.8
+
+## 0.2.0-beta.7
+
+### Patch Changes
+
+- 5d2dd5d: Preserve destination fragments through successful client navigation and redirects.
+- 977b90f: Retain unchanged Start route owners and update their loader, parameter, URL, and child props during client navigation.
+- d35d98f: Stream the Start document shell before pending application resources and support streaming custom document shells.
+- 8ce4ca8: Separate cached document and client-navigation responses with a Vary header.
+- Updated dependencies [ed60a1c]
+- Updated dependencies [977b90f]
+- Updated dependencies [9581420]
+  - @vidact/runtime@0.2.0-beta.7
+  - @vidact/vite@0.2.0-beta.7
+
 ## 0.2.0-beta.6
 
 ### Patch Changes

package/README.md

@@ -45,8 +45,8 @@ application. Route components must be named functions so the Vidact compiler
 can identify and lower them.
 
 `Link` renders an ordinary anchor during SSR. After hydration, unmodified clicks
-on same-origin Start routes request a server loader snapshot, replace the owned
-route root, and update browser history without loading another document.
+on same-origin Start routes request a server loader snapshot, update the retained
+route chain, and update browser history without loading another document.
 External URLs, downloads, modified clicks, `target` links, hash-only links, and
 links with `reloadDocument` retain native browser behavior. Use `replace` to
 replace the current history entry.
@@ -60,6 +60,21 @@ replace the current history entry.
 `hydrateStart()` returns a `StartClient` whose `navigate()` method provides the
 same behavior for programmatic navigation.
 
-This first navigation contract replaces the owned route root atomically, so
-component-local state in shared layouts resets. Retaining unchanged layout
-owners is a follow-up routing contract.
+Document HTML and client-navigation snapshots share the same route URL. Start
+marks both successful representations with `Vary: x-vidact-start-navigation`,
+so HTTP caches that honor `Vary` keep them separate. Deployments must preserve
+that response header when adding their own caching rules.
+
+The built-in document streams its opening shell as soon as loaders settle. The
+marker-complete application follows after its async resources settle, then the
+snapshot and client script close the document. `renderDocumentShell` customizes
+the strings before and after the application while preserving this behavior.
+The older `renderDocument` callback still receives one `applicationHtml` string
+and therefore buffers the application before returning a response.
+
+Start retains the longest common prefix of component-bearing route entries.
+Those components keep their DOM, local state, refs, and effects while their
+`loaderData`, `params`, `requestUrl`, and `children` props update. The first
+changed route entry and all descendants are staged as a new owned suffix, then
+the previous suffix is disposed. Routes without a component do not establish a
+DOM owner.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;;UA0BiB;WACN,eAAe,WAAW;WAC1B,UAAU;;;;;;WAMV,sBAAsB;WACtB,OAAO;WACP;WACA;WACA;;UAGM;WACN;WACA;;UAGM,oBAAoB;WAC1B,WAAW,aAAa,KAAK,UAAU,yBAAyB;;iBAKrD,aAAa,SAAS,sBAAsB,QAAQ"}
+{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;;UAgCiB;WACN,eAAe,WAAW;WAC1B,UAAU;;;;;;WAMV,sBAAsB;WACtB,OAAO;WACP;WACA;WACA;;UAGM;WACN;WACA;;UAGM,oBAAoB;WAC1B,WAAW,aAAa,KAAK,UAAU,yBAAyB;;iBAyBrD,aAAa,SAAS,sBAAsB,QAAQ"}

package/dist/client.js

@@ -1,10 +1,11 @@
-import { composeRouteMatches, loadRouteMatches, matchRoutes } from "./router.js";
+import { loadRouteMatches, matchRoutes } from "./router.js";
 import { VIDACT_START_NAVIGATION_HEADER, decodeStartSnapshot } from "./snapshot.js";
-import { cloneRenderable, compiledRoot, createCompiledScope } from "@vidact/runtime";
-import { createElement, hydrateRoot } from "@vidact/runtime/hydrate";
+import { binding, cloneRenderable, compiledRoot, createCompiledScope, createCompiledState, createComponentRenderable, source } from "@vidact/runtime";
+import { hydrateRoot } from "@vidact/runtime/hydrate";
 //#region src/client.ts
 const DEFAULT_ROOT_ID = "vidact-start-root";
 const DEFAULT_SNAPSHOT_ID = "vidact-start-snapshot";
+const routeComponentIdentities = /* @__PURE__ */ new WeakMap();
 async function hydrateStart(options) {
 	const snapshot = decodeStartSnapshot(options.snapshot ?? readSnapshot(options.snapshotId ?? DEFAULT_SNAPSHOT_ID));
 	const initialUrl = new URL(snapshot.pathname, window.location.href);
@@ -14,7 +15,8 @@ async function hydrateStart(options) {
 	const loaded = await loadRouteMatches(matches, request, snapshot.loaderData);
 	const host = options.root ?? document.querySelector(`#${CSS.escape(options.rootId ?? DEFAULT_ROOT_ID)}`);
 	if (host === null) throw new Error("Vidact Start hydration root is missing");
-	const root = hydrateRoot(host, createClientApplication(loaded, request.url), { onRecoverableError: options.onRecoverableError ?? ((error) => console.warn("[vidact/start] hydration recovered by re-rendering:", error)) });
+	let application = createClientApplication(loaded, request.url);
+	const root = hydrateRoot(host, application.application, { onRecoverableError: options.onRecoverableError ?? ((error) => console.warn("[vidact/start] hydration recovered by re-rendering:", error)) });
 	const fetchNavigation = options.fetch ?? window.fetch.bind(window);
 	let navigation = 0;
 	let navigationController;
@@ -50,6 +52,7 @@ async function hydrateStart(options) {
 			}
 			const nextSnapshot = decodeStartSnapshot(await response.text());
 			const nextUrl = new URL(nextSnapshot.pathname, target.origin);
+			if (nextUrl.hash === "") nextUrl.hash = target.hash;
 			const snapshotMatches = matchRoutes(options.manifest, nextUrl.pathname);
 			if (snapshotMatches.length === 0) {
 				navigateDocument(target, historyMode === "replace");
@@ -58,7 +61,12 @@ async function hydrateStart(options) {
 			const nextRequest = new Request(nextUrl);
 			const nextLoaded = await loadRouteMatches(snapshotMatches, nextRequest, nextSnapshot.loaderData);
 			if (attempt !== navigation) return false;
-			root.replace(createClientApplication(nextLoaded, nextRequest.url));
+			const nextState = createClientRouteState(nextLoaded, nextRequest.url);
+			if (sharedRouteComponentCount(application.state, nextState) === 0) {
+				const replacement = createClientApplication(nextLoaded, nextRequest.url);
+				root.replace(replacement.application);
+				application = replacement;
+			} else application.update(nextState);
 			updateHistory(nextUrl, historyMode);
 			if (scroll) scrollToLocation(nextUrl);
 			return true;
@@ -97,12 +105,99 @@ async function hydrateStart(options) {
 	};
 }
 function createClientApplication(matches, requestUrl) {
-	return () => {
-		const scope = createCompiledScope();
-		const application = composeRouteMatches(matches, (component, props) => createElement(component, props), requestUrl);
-		return compiledRoot(scope, () => cloneRenderable(application));
+	let currentState = createClientRouteState(matches, requestUrl);
+	let updateState;
+	return {
+		application: () => {
+			const scope = createCompiledScope();
+			const routeSource = source(0);
+			const state = createCompiledState(scope, routeSource, currentState);
+			updateState = (nextState) => {
+				const previousState = currentState;
+				try {
+					state.set(nextState);
+					currentState = nextState;
+				} catch (error) {
+					try {
+						state.set(previousState);
+					} catch {}
+					currentState = previousState;
+					throw error;
+				}
+			};
+			const route = createRetainedRouteRenderable(scope, routeSource, state.get, 0);
+			return compiledRoot(scope, () => cloneRenderable(route));
+		},
+		get state() {
+			return currentState;
+		},
+		update(nextState) {
+			if (updateState === void 0) throw new Error("cannot update a Vidact Start application before it mounts");
+			updateState(nextState);
+		}
+	};
+}
+function createClientRouteState(matches, requestUrl) {
+	return {
+		components: matches.flatMap((match) => {
+			const component = match.definition.options.component;
+			return component === void 0 ? [] : [{
+				component,
+				entry: match.entry,
+				loaderData: match.loaderData,
+				params: match.params
+			}];
+		}),
+		requestUrl
 	};
 }
+function createRetainedRouteRenderable(scope, routeSource, readState, index) {
+	const initial = readState().components[index];
+	if (initial === void 0) return void 0;
+	const identity = routeComponentIdentity(initial.entry, initial.component);
+	let lastProps = routeComponentProps(scope, routeSource, readState, index);
+	const input = binding(scope, routeSource, () => {
+		const current = readState().components[index];
+		if (current === void 0 || routeComponentIdentity(current.entry, current.component) !== identity) return lastProps;
+		lastProps = routeComponentProps(scope, routeSource, readState, index);
+		return lastProps;
+	});
+	return createComponentRenderable(initial.component, input, identity);
+}
+function routeComponentProps(scope, routeSource, readState, index) {
+	const state = readState();
+	const match = state.components[index];
+	return {
+		children: createRetainedRouteRenderable(scope, routeSource, readState, index + 1),
+		loaderData: match.loaderData,
+		params: match.params,
+		requestUrl: state.requestUrl
+	};
+}
+function sharedRouteComponentCount(left, right) {
+	const length = Math.min(left.components.length, right.components.length);
+	let index = 0;
+	while (index < length) {
+		const previous = left.components[index];
+		const next = right.components[index];
+		if (previous.entry !== next.entry || previous.component !== next.component) break;
+		index += 1;
+	}
+	return index;
+}
+function routeComponentIdentity(entry, component) {
+	let componentIdentities = routeComponentIdentities.get(entry);
+	if (componentIdentities === void 0) {
+		componentIdentities = /* @__PURE__ */ new WeakMap();
+		routeComponentIdentities.set(entry, componentIdentities);
+	}
+	let identity = componentIdentities.get(component);
+	if (identity === void 0) {
+		identity = {};
+		componentIdentities.set(component, identity);
+	}
+	return identity;
+}
 function linkForEvent(event) {
 	if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
 	const target = event.target;

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"mappings":"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"}
+{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"mappings":"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"}

package/dist/link-client.js

@@ -1,8 +1,10 @@
 import { anchorProps } from "./link-contract.js";
+import { compiledRoot, createNarrowCompiledScope } from "@vidact/runtime";
 import { createElement } from "@vidact/runtime/hydrate";
 //#region src/link-client.ts
 function Link(props) {
-	return createElement("a", anchorProps(props));
+	const scope = createNarrowCompiledScope();
+	return compiledRoot(scope, () => createElement("a", anchorProps(props)));
 }
 //#endregion
 export { Link };

package/dist/link-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"link-client.js","names":[],"sources":["../src/link-client.ts"],"mappings":";;;AAKA,SAAgB,KAAK,OAAuC;CAC1D,OAAO,cAAc,KAAK,YAAY,KAAK,CAAC;AAC9C"}
+{"version":3,"file":"link-client.js","names":[],"sources":["../src/link-client.ts"],"mappings":";;;;AAKA,SAAgB,KAAK,OAAuC;CAC1D,MAAM,QAAQ,0BAA0B;CACxC,OAAO,aAAa,aAAa,cAAc,KAAK,YAAY,KAAK,CAAC,CAAC;AACzE"}

package/dist/server.d.ts

@@ -7,15 +7,26 @@ interface StartDocumentContext {
   readonly snapshot: string;
   readonly snapshotId: string;
 }
+interface StartDocumentShellContext {
+  readonly clientEntry: string | undefined;
+  readonly rootId: string;
+  readonly snapshot: string;
+  readonly snapshotId: string;
+}
+interface StartDocumentShell {
+  readonly afterApplication: string;
+  readonly beforeApplication: string;
+}
 interface StartHandlerOptions {
   readonly clientEntry?: string;
   readonly manifest: RouteManifest;
   readonly notFound?: (request: Request) => Response | Promise<Response>;
   readonly renderDocument?: (context: StartDocumentContext) => string | Promise<string>;
+  readonly renderDocumentShell?: (context: StartDocumentShellContext) => StartDocumentShell | Promise<StartDocumentShell>;
   readonly rootId?: string;
   readonly snapshotId?: string;
 }
 declare function createStartHandler(options: StartHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion
-export { type StartComponent, StartDocumentContext, StartHandlerOptions, createStartHandler };
+export { type StartComponent, StartDocumentContext, StartDocumentShell, StartDocumentShellContext, StartHandlerOptions, createStartHandler };
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;UAkCiB;WACN;WACA;WACA;WACA;WACA;;UAGM;WACN;WACA,UAAU;WACV,YAAY,SAAS,YAAY,WAAW,QAAQ;WACpD,kBAAkB,SAAS,kCAAkC;WAC7D;WACA;;iBAGK,mBACd,SAAS,uBACP,SAAS,YAAY,QAAQ"}
+{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;UAkCiB;WACN;WACA;WACA;WACA;WACA;;UAGM;WACN;WACA;WACA;WACA;;UAGM;WACN;WACA;;UAGM;WACN;WACA,UAAU;WACV,YAAY,SAAS,YAAY,WAAW,QAAQ;WACpD,kBAAkB,SAAS,kCAAkC;WAC7D,uBACP,SAAS,8BACN,qBAAqB,QAAQ;WACzB;WACA;;iBAGK,mBACd,SAAS,uBACP,SAAS,YAAY,QAAQ"}

package/dist/server.js

@@ -1,5 +1,5 @@
 import { composeRouteMatches, matchRoutes, resolveRouteMatches, routeLoaderData, runRouteLoaders } from "./router.js";
-import { VIDACT_START_PROTOCOL, VIDACT_START_SNAPSHOT_MEDIA_TYPE, encodeStartSnapshot } from "./snapshot.js";
+import { VIDACT_START_NAVIGATION_HEADER, VIDACT_START_PROTOCOL, VIDACT_START_SNAPSHOT_MEDIA_TYPE, encodeStartSnapshot } from "./snapshot.js";
 import { createElement } from "@vidact/runtime/server";
 import { renderToReadableStream } from "@vidact/runtime/framework/server";
 //#region src/server.ts
@@ -15,6 +15,7 @@ function StartApplication({ children }) {
 const DEFAULT_ROOT_ID = "vidact-start-root";
 const DEFAULT_SNAPSHOT_ID = "vidact-start-snapshot";
 function createStartHandler(options) {
+	if (options.renderDocument !== void 0 && options.renderDocumentShell !== void 0) throw new TypeError("renderDocument and renderDocumentShell cannot be used together");
 	const rootId = options.rootId ?? DEFAULT_ROOT_ID;
 	const snapshotId = options.snapshotId ?? DEFAULT_SNAPSHOT_ID;
 	return async (request) => {
@@ -48,20 +49,38 @@ function createStartHandler(options) {
 			pathname: `${url.pathname}${url.search}`,
 			loaderData: routeLoaderData(loaded)
 		}));
-		if (request.headers.get("x-vidact-start-navigation") === "1") return new Response(request.method === "HEAD" ? null : snapshot, { headers: { "content-type": `${VIDACT_START_SNAPSHOT_MEDIA_TYPE}; charset=utf-8` } });
+		if (request.headers.get("x-vidact-start-navigation") === "1") return new Response(request.method === "HEAD" ? null : snapshot, { headers: representationHeaders(`${VIDACT_START_SNAPSHOT_MEDIA_TYPE}; charset=utf-8`) });
+		const headers = representationHeaders("text/html; charset=utf-8");
+		if (request.method === "HEAD") return new Response(null, { headers });
 		const application = composeRouteMatches(loaded, (component, props) => createElement(component, props), request.url);
-		const stream = await renderToReadableStream(() => createElement(StartApplication, { children: application }), { identifierPrefix: "start-" });
-		const documentContext = {
-			applicationHtml: await new Response(stream).text(),
+		const stream = await renderToReadableStream(() => createElement(StartApplication, { children: application }), {
+			identifierPrefix: "start-",
+			signal: request.signal
+		});
+		stream.allReady.catch(() => void 0);
+		const shellContext = {
 			clientEntry: options.clientEntry,
 			rootId,
 			snapshot,
 			snapshotId
 		};
-		const html = options.renderDocument === void 0 ? defaultDocument(documentContext) : await options.renderDocument(documentContext);
-		return new Response(request.method === "HEAD" ? null : html, { headers: { "content-type": "text/html; charset=utf-8" } });
+		if (options.renderDocument !== void 0) {
+			const applicationHtml = await new Response(stream).text();
+			const html = await options.renderDocument({
+				...shellContext,
+				applicationHtml
+			});
+			return new Response(html, { headers });
+		}
+		const shell = options.renderDocumentShell === void 0 ? defaultDocumentShell(shellContext) : validateDocumentShell(await options.renderDocumentShell(shellContext));
+		return new Response(streamDocument(shell, stream), { headers });
 	};
 }
+function representationHeaders(contentType) {
+	const headers = new Headers({ "content-type": contentType });
+	headers.append("vary", VIDACT_START_NAVIGATION_HEADER);
+	return headers;
+}
 function responseForRequest(request, response) {
 	return request.method === "HEAD" ? new Response(null, response) : response;
 }
@@ -93,9 +112,53 @@ function allowedMethods(matches, canRender) {
 function methodRank(method) {
 	return method === "GET" ? 0 : method === "HEAD" ? 1 : 2;
 }
-function defaultDocument(context) {
+function defaultDocumentShell(context) {
 	const clientScript = context.clientEntry === void 0 ? "" : `<script type="module" src="${escapeAttribute(context.clientEntry)}"><\/script>`;
-	return `<!doctype html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"></head><body><div id="${escapeAttribute(context.rootId)}">${context.applicationHtml}</div><script id="${escapeAttribute(context.snapshotId)}" type="application/json">${context.snapshot}<\/script>${clientScript}</body></html>`;
+	return {
+		beforeApplication: `<!doctype html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"></head><body><div id="${escapeAttribute(context.rootId)}">`,
+		afterApplication: `</div><script id="${escapeAttribute(context.snapshotId)}" type="application/json">${context.snapshot}<\/script>${clientScript}</body></html>`
+	};
+}
+function validateDocumentShell(value) {
+	if (typeof value !== "object" || value === null || typeof value.beforeApplication !== "string" || typeof value.afterApplication !== "string") throw new TypeError("renderDocumentShell must return beforeApplication and afterApplication");
+	return value;
+}
+function streamDocument(shell, application) {
+	const encoder = new TextEncoder();
+	const before = encoder.encode(shell.beforeApplication);
+	const after = encoder.encode(shell.afterApplication);
+	const reader = application.getReader();
+	let phase = "before";
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				if (phase === "before") {
+					phase = "application";
+					if (before.length > 0) controller.enqueue(before);
+					return;
+				}
+				if (phase === "application") {
+					const result = await reader.read();
+					if (!result.done) {
+						controller.enqueue(result.value);
+						return;
+					}
+					phase = "after";
+				}
+				if (phase === "after") {
+					phase = "done";
+					if (after.length > 0) controller.enqueue(after);
+					return;
+				}
+				controller.close();
+			} catch (error) {
+				controller.error(error);
+			}
+		},
+		cancel(reason) {
+			return reader.cancel(reason);
+		}
+	});
 }
 function escapeAttribute(value) {
 	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"mappings":"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"}
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vidact/start",
-  "version": "0.2.0-beta.6",
+  "version": "0.2.0-beta.8",
   "description": "Full-stack application framework primitives for Vidact",
   "keywords": [
     "full-stack",
@@ -53,8 +53,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@vidact/runtime": "0.2.0-beta.6",
-    "@vidact/vite": "0.2.0-beta.6"
+    "@vidact/vite": "0.2.0-beta.8",
+    "@vidact/runtime": "0.2.0-beta.8"
   },
   "devDependencies": {
     "@types/node": "24.13.3",

package/src/client.ts

@@ -1,18 +1,24 @@
 import {
+  binding,
   cloneRenderable,
   compiledRoot,
+  createComponentRenderable,
   createCompiledScope,
+  createCompiledState,
+  source,
   type CompiledComponentResult,
+  type CompiledRenderValue,
   type CompiledRoot,
 } from '@vidact/runtime'
-import { createElement, hydrateRoot } from '@vidact/runtime/hydrate'
+import { hydrateRoot } from '@vidact/runtime/hydrate'
 
 import {
-  composeRouteMatches,
   loadRouteMatches,
   matchRoutes,
   type LoadedRouteMatch,
+  type RouteComponentProps,
   type RouteManifest,
+  type RouteManifestEntry,
   type StartComponent,
 } from './router.ts'
 import {
@@ -50,6 +56,26 @@ export interface StartClient extends CompiledRoot {
 
 type HistoryMode = 'none' | 'push' | 'replace'
 
+interface ClientRouteState {
+  readonly components: readonly ClientRouteComponent[]
+  readonly requestUrl: string
+}
+
+interface ClientRouteComponent {
+  readonly component: StartComponent
+  readonly entry: RouteManifestEntry
+  readonly loaderData: LoadedRouteMatch['loaderData']
+  readonly params: LoadedRouteMatch['params']
+}
+
+interface RetainedClientApplication {
+  readonly application: () => CompiledComponentResult
+  readonly state: ClientRouteState
+  readonly update: (state: ClientRouteState) => void
+}
+
+const routeComponentIdentities = new WeakMap<RouteManifestEntry, WeakMap<StartComponent, object>>()
+
 export async function hydrateStart(options: HydrateStartOptions): Promise<StartClient> {
   const snapshot = decodeStartSnapshot(
     options.snapshot ?? readSnapshot(options.snapshotId ?? DEFAULT_SNAPSHOT_ID),
@@ -63,7 +89,8 @@ export async function hydrateStart(options: HydrateStartOptions): Promise<StartC
     options.root ?? document.querySelector(`#${CSS.escape(options.rootId ?? DEFAULT_ROOT_ID)}`)
   if (host === null) throw new Error('Vidact Start hydration root is missing')
 
-  const root = hydrateRoot(host, createClientApplication(loaded, request.url), {
+  let application = createClientApplication(loaded, request.url)
+  const root = hydrateRoot(host, application.application, {
     onRecoverableError:
       options.onRecoverableError ??
       ((error) => console.warn('[vidact/start] hydration recovered by re-rendering:', error)),
@@ -123,6 +150,9 @@ export async function hydrateStart(options: HydrateStartOptions): Promise<StartC
 
       const nextSnapshot = decodeStartSnapshot(await response.text())
       const nextUrl = new URL(nextSnapshot.pathname, target.origin)
+      // Fragments never reach the server request. Preserve the caller's fragment unless
+      // the snapshot explicitly supplies one, including when the server redirects the path.
+      if (nextUrl.hash === '') nextUrl.hash = target.hash
       const snapshotMatches = matchRoutes(options.manifest, nextUrl.pathname)
       if (snapshotMatches.length === 0) {
         navigateDocument(target, historyMode === 'replace')
@@ -136,7 +166,14 @@ export async function hydrateStart(options: HydrateStartOptions): Promise<StartC
       )
       if (attempt !== navigation) return false
 
-      root.replace(createClientApplication(nextLoaded, nextRequest.url))
+      const nextState = createClientRouteState(nextLoaded, nextRequest.url)
+      if (sharedRouteComponentCount(application.state, nextState) === 0) {
+        const replacement = createClientApplication(nextLoaded, nextRequest.url)
+        root.replace(replacement.application)
+        application = replacement
+      } else {
+        application.update(nextState)
+      }
       updateHistory(nextUrl, historyMode)
       if (scroll) scrollToLocation(nextUrl)
       return true
@@ -192,16 +229,124 @@ export async function hydrateStart(options: HydrateStartOptions): Promise<StartC
 function createClientApplication(
   matches: readonly LoadedRouteMatch[],
   requestUrl: string,
-): () => CompiledComponentResult {
-  return () => {
-    const scope = createCompiledScope()
-    const application = composeRouteMatches(
-      matches,
-      (component, props) => createElement(component as never, props),
-      requestUrl,
-    )
-    return compiledRoot(scope, () => cloneRenderable(application))
+): RetainedClientApplication {
+  const initialState = createClientRouteState(matches, requestUrl)
+  let currentState = initialState
+  let updateState: ((state: ClientRouteState) => void) | undefined
+  return {
+    application: () => {
+      const scope = createCompiledScope()
+      const routeSource = source(0)
+      const state = createCompiledState(scope, routeSource, currentState)
+      updateState = (nextState) => {
+        const previousState = currentState
+        try {
+          state.set(nextState)
+          currentState = nextState
+        } catch (error) {
+          try {
+            state.set(previousState)
+          } catch {
+            // Preserve the navigation failure that triggered the rollback.
+          }
+          currentState = previousState
+          throw error
+        }
+      }
+      const route = createRetainedRouteRenderable(scope, routeSource, state.get, 0)
+      return compiledRoot(scope, () => cloneRenderable(route))
+    },
+    get state() {
+      return currentState
+    },
+    update(nextState) {
+      if (updateState === undefined) {
+        throw new Error('cannot update a Vidact Start application before it mounts')
+      }
+      updateState(nextState)
+    },
+  }
+}
+
+function createClientRouteState(
+  matches: readonly LoadedRouteMatch[],
+  requestUrl: string,
+): ClientRouteState {
+  return {
+    components: matches.flatMap((match) => {
+      const component = match.definition.options.component
+      return component === undefined
+        ? []
+        : [{ component, entry: match.entry, loaderData: match.loaderData, params: match.params }]
+    }),
+    requestUrl,
+  }
+}
+
+function createRetainedRouteRenderable(
+  scope: ReturnType<typeof createCompiledScope>,
+  routeSource: ReturnType<typeof source>,
+  readState: () => ClientRouteState,
+  index: number,
+): CompiledRenderValue {
+  const initial = readState().components[index]
+  if (initial === undefined) return undefined
+  const identity = routeComponentIdentity(initial.entry, initial.component)
+  let lastProps = routeComponentProps(scope, routeSource, readState, index)
+  const input = binding(scope, routeSource, () => {
+    const current = readState().components[index]
+    if (
+      current === undefined ||
+      routeComponentIdentity(current.entry, current.component) !== identity
+    ) {
+      return lastProps
+    }
+    lastProps = routeComponentProps(scope, routeSource, readState, index)
+    return lastProps
+  })
+  return createComponentRenderable(initial.component as never, input, identity)
+}
+
+function routeComponentProps(
+  scope: ReturnType<typeof createCompiledScope>,
+  routeSource: ReturnType<typeof source>,
+  readState: () => ClientRouteState,
+  index: number,
+): RouteComponentProps {
+  const state = readState()
+  const match = state.components[index]!
+  return {
+    children: createRetainedRouteRenderable(scope, routeSource, readState, index + 1),
+    loaderData: match.loaderData,
+    params: match.params,
+    requestUrl: state.requestUrl,
+  }
+}
+
+function sharedRouteComponentCount(left: ClientRouteState, right: ClientRouteState): number {
+  const length = Math.min(left.components.length, right.components.length)
+  let index = 0
+  while (index < length) {
+    const previous = left.components[index]!
+    const next = right.components[index]!
+    if (previous.entry !== next.entry || previous.component !== next.component) break
+    index += 1
+  }
+  return index
+}
+
+function routeComponentIdentity(entry: RouteManifestEntry, component: StartComponent): object {
+  let componentIdentities = routeComponentIdentities.get(entry)
+  if (componentIdentities === undefined) {
+    componentIdentities = new WeakMap()
+    routeComponentIdentities.set(entry, componentIdentities)
+  }
+  let identity = componentIdentities.get(component)
+  if (identity === undefined) {
+    identity = {}
+    componentIdentities.set(component, identity)
   }
+  return identity
 }
 
 function linkForEvent(event: MouseEvent): HTMLAnchorElement | undefined {

package/src/link-client.ts

@@ -1,10 +1,11 @@
-import type { CompiledRenderValue } from '@vidact/runtime'
+import { compiledRoot, createNarrowCompiledScope, type CompiledRenderValue } from '@vidact/runtime'
 import { createElement } from '@vidact/runtime/hydrate'
 
 import { anchorProps, type LinkProps } from './link-contract.ts'
 
 export function Link(props: LinkProps): CompiledRenderValue {
-  return createElement('a', anchorProps(props)) as unknown as CompiledRenderValue
+  const scope = createNarrowCompiledScope()
+  return compiledRoot(scope, () => createElement('a', anchorProps(props)))
 }
 
 export type { LinkProps }

package/src/server.ts

@@ -40,11 +40,26 @@ export interface StartDocumentContext {
   readonly snapshotId: string
 }
 
+export interface StartDocumentShellContext {
+  readonly clientEntry: string | undefined
+  readonly rootId: string
+  readonly snapshot: string
+  readonly snapshotId: string
+}
+
+export interface StartDocumentShell {
+  readonly afterApplication: string
+  readonly beforeApplication: string
+}
+
 export interface StartHandlerOptions {
   readonly clientEntry?: string
   readonly manifest: RouteManifest
   readonly notFound?: (request: Request) => Response | Promise<Response>
   readonly renderDocument?: (context: StartDocumentContext) => string | Promise<string>
+  readonly renderDocumentShell?: (
+    context: StartDocumentShellContext,
+  ) => StartDocumentShell | Promise<StartDocumentShell>
   readonly rootId?: string
   readonly snapshotId?: string
 }
@@ -52,6 +67,9 @@ export interface StartHandlerOptions {
 export function createStartHandler(
   options: StartHandlerOptions,
 ): (request: Request) => Promise<Response> {
+  if (options.renderDocument !== undefined && options.renderDocumentShell !== undefined) {
+    throw new TypeError('renderDocument and renderDocumentShell cannot be used together')
+  }
   const rootId = options.rootId ?? DEFAULT_ROOT_ID
   const snapshotId = options.snapshotId ?? DEFAULT_SNAPSHOT_ID
   return async (request) => {
@@ -100,9 +118,11 @@ export function createStartHandler(
     )
     if (request.headers.get(VIDACT_START_NAVIGATION_HEADER) === '1') {
       return new Response(request.method === 'HEAD' ? null : snapshot, {
-        headers: { 'content-type': `${VIDACT_START_SNAPSHOT_MEDIA_TYPE}; charset=utf-8` },
+        headers: representationHeaders(`${VIDACT_START_SNAPSHOT_MEDIA_TYPE}; charset=utf-8`),
       })
     }
+    const headers = representationHeaders('text/html; charset=utf-8')
+    if (request.method === 'HEAD') return new Response(null, { headers })
 
     const application = composeRouteMatches(
       loaded,
@@ -112,26 +132,34 @@ export function createStartHandler(
     ) as ServerChild
     const stream = await renderToReadableStream(
       () => createElement(StartApplication, { children: application }) as ServerChild,
-      { identifierPrefix: 'start-' },
+      { identifierPrefix: 'start-', signal: request.signal },
     )
-    const applicationHtml = await new Response(stream).text()
-    const documentContext = {
-      applicationHtml,
+    void stream.allReady.catch(() => undefined)
+    const shellContext = {
       clientEntry: options.clientEntry,
       rootId,
       snapshot,
       snapshotId,
     }
-    const html =
-      options.renderDocument === undefined
-        ? defaultDocument(documentContext)
-        : await options.renderDocument(documentContext)
-    return new Response(request.method === 'HEAD' ? null : html, {
-      headers: { 'content-type': 'text/html; charset=utf-8' },
-    })
+    if (options.renderDocument !== undefined) {
+      const applicationHtml = await new Response(stream).text()
+      const html = await options.renderDocument({ ...shellContext, applicationHtml })
+      return new Response(html, { headers })
+    }
+    const shell =
+      options.renderDocumentShell === undefined
+        ? defaultDocumentShell(shellContext)
+        : validateDocumentShell(await options.renderDocumentShell(shellContext))
+    return new Response(streamDocument(shell, stream), { headers })
   }
 }
 
+function representationHeaders(contentType: string): Headers {
+  const headers = new Headers({ 'content-type': contentType })
+  headers.append('vary', VIDACT_START_NAVIGATION_HEADER)
+  return headers
+}
+
 function responseForRequest(request: Request, response: Response): Response {
   return request.method === 'HEAD' ? new Response(null, response) : response
 }
@@ -188,12 +216,68 @@ function methodRank(method: string): number {
   return method === 'GET' ? 0 : method === 'HEAD' ? 1 : 2
 }
 
-function defaultDocument(context: StartDocumentContext): string {
+function defaultDocumentShell(context: StartDocumentShellContext): StartDocumentShell {
   const clientScript =
     context.clientEntry === undefined
       ? ''
       : `<script type="module" src="${escapeAttribute(context.clientEntry)}"></script>`
-  return `<!doctype html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"></head><body><div id="${escapeAttribute(context.rootId)}">${context.applicationHtml}</div><script id="${escapeAttribute(context.snapshotId)}" type="application/json">${context.snapshot}</script>${clientScript}</body></html>`
+  return {
+    beforeApplication: `<!doctype html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"></head><body><div id="${escapeAttribute(context.rootId)}">`,
+    afterApplication: `</div><script id="${escapeAttribute(context.snapshotId)}" type="application/json">${context.snapshot}</script>${clientScript}</body></html>`,
+  }
+}
+
+function validateDocumentShell(value: StartDocumentShell): StartDocumentShell {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    typeof value.beforeApplication !== 'string' ||
+    typeof value.afterApplication !== 'string'
+  ) {
+    throw new TypeError('renderDocumentShell must return beforeApplication and afterApplication')
+  }
+  return value
+}
+
+function streamDocument(
+  shell: StartDocumentShell,
+  application: ReadableStream<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+  const before = encoder.encode(shell.beforeApplication)
+  const after = encoder.encode(shell.afterApplication)
+  const reader = application.getReader()
+  let phase: 'after' | 'application' | 'before' | 'done' = 'before'
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        if (phase === 'before') {
+          phase = 'application'
+          if (before.length > 0) controller.enqueue(before)
+          return
+        }
+        if (phase === 'application') {
+          const result = await reader.read()
+          if (!result.done) {
+            controller.enqueue(result.value)
+            return
+          }
+          phase = 'after'
+        }
+        if (phase === 'after') {
+          phase = 'done'
+          if (after.length > 0) controller.enqueue(after)
+          return
+        }
+        controller.close()
+      } catch (error) {
+        controller.error(error)
+      }
+    },
+    cancel(reason) {
+      return reader.cancel(reason)
+    },
+  })
 }
 
 function escapeAttribute(value: string): string {