@backtickjs/hono 0.2.7 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @backtickjs/hono
 
-[Hono](https://hono.dev) routes as [Backtick](https://backtickjs.com) screens: under `backtick()`, `context.render(<Home />)` answers a request with your server components, bundled for the modules the client that asked provides, as Hono's own `jsxRenderer()` answers with HTML. Each route is a screen, and a path on the client is the same path on the server. Hono is a peer dependency: this package is built against Hono 4.13.13, and works with any later 4.x.
+[Hono](https://hono.dev) routes as [Backtick](https://backtickjs.com) screens: under `backtickRenderer()`, `context.render(<Home />)` answers a request with your server components, bundled for the modules the client that asked provides, as Hono's own `jsxRenderer()` answers with HTML. Each route is a screen, and a path on the client is the same path on the server. Hono is a peer dependency: this package is built against Hono 4.13.13, and works with any later 4.x.
 
 ## Install
 
@@ -13,18 +13,54 @@ The [repository's README](https://github.com/backtickjs/backtick#packages) says
 ## Usage
 
 ```tsx
-import { backtick } from "@backtickjs/hono";
+import { cs } from "@backtickjs/core";
+import { backtickApp } from "@backtickjs/hono";
+import { Stack } from "expo-router" with { backtick: "client" };
 import { Hono } from "hono";
 import { Home } from "./Home.js";
 
+// The root layout, around every screen: the navigator.
+const RootLayout = cs`() => <$Stack />`;
+
 const app = new Hono();
 
-app.use(backtick());
+app.use(backtickApp(app, RootLayout));
 app.get("/", (context) => context.render(<Home />));
 
 export default app;
 ```
 
+The Backtick app opens an app from one answer, which `backtickApp(app, RootLayout)` answers: the client code that fetches each screen and keeps it while it shows, around the app's root layout, a client component that draws its navigator, as Hono's `jsxRenderer()` takes the page's. Navigation works as in Next.js. Every route answers with what it draws, and the runtime fetches each as a query keyed by its path. A route with a `_loading` (`/day/_loading`, rendered for the path, so it can use its params) pushes as soon as that's in, at once if it was prefetched, and shows it until the route's answer is in; a navigation to one without holds the current screen until its answer is in, as expo-router's `unstable_useIsNavigating()` says, for a progress bar. Going back shows a screen as it was. `<Link prefetch>` fetches a route's loading state ahead, or its answer, without one. The root layout is the only one: what screens share is a component they draw. A client with a navigator of its own uses `backtickRenderer()` alone.
+
+The runtime gives the app a [TanStack Query](https://tanstack.com/query) client whose query keys are paths: a query of `"/cart/items"` fetches that route, and its answer is what the route renders. For a screen whose parts load on their own, each in its own `Suspense`, and refetch on their own:
+
+```tsx
+import { useQueryClient, useSuspenseQuery } from "@tanstack/react-query" with {
+  backtick: "client",
+};
+
+const Part = cs`(props: { path: string }) =>
+  $useSuspenseQuery({ queryKey: [props.path] }).data as ReactNode`;
+
+const Cart = cs`() => {
+  const queryClient = $useQueryClient();
+  return (
+    <>
+      <$Suspense fallback={<$ActivityIndicator />}>
+        <$Part path="/cart/items" />
+      </$Suspense>
+      <$Button
+        title="Refresh"
+        onPress={() =>
+          queryClient.invalidateQueries({ queryKey: ["/cart/items"] })
+        }
+      />
+    </>
+  );
+}`;
+app.get("/cart", (context) => context.render(cs`<$Cart />`));
+```
+
 The client sends its modules, each at its package's version, in `x-backtick-modules` (in an Expo app, `modulesOf` from `@backtickjs/core` writes them). The answer is the screen's bundle as CommonJS, `text/javascript`, for the client to run with `execRoot`.
 
 A client without a module the screen needs gets a `426`, and any other refusal of the bundler's a `400`, each with `{ name, message }` as JSON: the client can show why. An error your server components throw passes through to Hono.

package/dist/index.d.ts

@@ -1,39 +1,46 @@
-import type { Spliceable, SplicesAs } from "@backtickjs/core";
-import type { MiddlewareHandler } from "hono";
+import type { Client, Spliceable, SplicesAs } from "@backtickjs/core";
+import type { ComponentType } from "react";
+import type { Hono, MiddlewareHandler } from "hono";
+export type { Runtime } from "./runtime.js";
 declare module "hono" {
     interface ContextRenderer {
         <T extends [T] extends [SplicesAs<T>] ? unknown : Spliceable>(input: T): Promise<Response>;
     }
 }
-/** A web app manifest: what the phone uses of an app before and around it. */
-export interface Manifest {
-    name?: string;
-    short_name?: string;
-    icons?: {
-        src: string;
-        sizes?: string;
-        type?: string;
-    }[];
-    theme_color?: string;
-    background_color?: string;
-    display?: "fullscreen" | "standalone" | "minimal-ui" | "browser";
-}
 /**
  * Hono's renderer for Backtick screens: under it, `context.render(input)`
  * answers with `input` bundled for the modules the client sent in
  * `x-backtick-modules`, so each route is a screen.
  *
- *     app.use(backtick());
+ *     app.use(backtickRenderer());
  *     app.get("/", (context) => context.render(<Home />));
  *
  * The status is the context's, so `context.status(404)` makes a not-found
- * screen, and screens are `no-store`: each opens as its latest copy. A client
+ * screen, and screens are `no-store`, kept out of HTTP caches: a reload or
+ * a new open always gets the latest copy. (The Backtick app reuses a screen
+ * it has, in memory, for 30 seconds, as Next.js's router does.) A client
  * without a module the screen needs gets a 426, and any other refusal of the
- * bundler's a 400, each with `{ name, message }`.
+ * bundler's a 400, each with `{ name, message }`. An app the Backtick app
+ * opens uses `backtickApp(app, RootLayout)` instead.
+ */
+export declare function backtickRenderer(): MiddlewareHandler;
+/**
+ * Hono's renderer for an app the Backtick app opens, as `backtickRenderer()`,
+ * which also answers the runtime the Backtick app fetches when it opens
+ * `app`: the client code that fetches, keeps and shows its screens, around
+ * its root layout, a client component that draws its `Stack`.
+ *
+ *     const RootLayout = cs`() => <$Stack />`;
+ *     app.use(backtickApp(app, RootLayout));
+ *     app.get("/", (context) => context.render(<Home />));
  *
- * `manifest` is the app's web app manifest, at `/manifest.webmanifest` and in
- * `x-backtick-manifest` on every screen, so it's as fresh as they are.
+ * Every route answers with what it draws. As in Next.js, a route with a
+ * `_loading` route (`/city/:id/_loading`, rendered for the path, so it can
+ * show the city's name) pushes as soon as that's in, at once if it was
+ * prefetched, and shows it until the route's answer is in; a navigation to
+ * one without holds the current screen until its answer is in. The runtime
+ * asks only for the loading states `app` has routes for. One with a layout
+ * route (a screen has none: what screens share is a component they draw), or
+ * with a loading route written with a trailing slash, doesn't open.
  */
-export declare function backtick(options?: {
-    manifest?: Manifest;
-}): MiddlewareHandler;
+export declare function backtickApp(app: Hono<any, any, any>, RootLayout: Client<ComponentType>): MiddlewareHandler;

package/dist/index.js

@@ -1,57 +1,89 @@
 import { bundler, BundlerError } from "@backtickjs/bundler";
+import { clientRuntime } from "./runtime.js";
 /**
  * Hono's renderer for Backtick screens: under it, `context.render(input)`
  * answers with `input` bundled for the modules the client sent in
  * `x-backtick-modules`, so each route is a screen.
  *
- *     app.use(backtick());
+ *     app.use(backtickRenderer());
  *     app.get("/", (context) => context.render(<Home />));
  *
  * The status is the context's, so `context.status(404)` makes a not-found
- * screen, and screens are `no-store`: each opens as its latest copy. A client
+ * screen, and screens are `no-store`, kept out of HTTP caches: a reload or
+ * a new open always gets the latest copy. (The Backtick app reuses a screen
+ * it has, in memory, for 30 seconds, as Next.js's router does.) A client
  * without a module the screen needs gets a 426, and any other refusal of the
- * bundler's a 400, each with `{ name, message }`.
+ * bundler's a 400, each with `{ name, message }`. An app the Backtick app
+ * opens uses `backtickApp(app, RootLayout)` instead.
+ */
+export function backtickRenderer() {
+    return async (context, next) => {
+        context.setRenderer(async (input) => bundled(context, input));
+        await next();
+    };
+}
+/**
+ * Hono's renderer for an app the Backtick app opens, as `backtickRenderer()`,
+ * which also answers the runtime the Backtick app fetches when it opens
+ * `app`: the client code that fetches, keeps and shows its screens, around
+ * its root layout, a client component that draws its `Stack`.
  *
- * `manifest` is the app's web app manifest, at `/manifest.webmanifest` and in
- * `x-backtick-manifest` on every screen, so it's as fresh as they are.
+ *     const RootLayout = cs`() => <$Stack />`;
+ *     app.use(backtickApp(app, RootLayout));
+ *     app.get("/", (context) => context.render(<Home />));
+ *
+ * Every route answers with what it draws. As in Next.js, a route with a
+ * `_loading` route (`/city/:id/_loading`, rendered for the path, so it can
+ * show the city's name) pushes as soon as that's in, at once if it was
+ * prefetched, and shows it until the route's answer is in; a navigation to
+ * one without holds the current screen until its answer is in. The runtime
+ * asks only for the loading states `app` has routes for. One with a layout
+ * route (a screen has none: what screens share is a component they draw), or
+ * with a loading route written with a trailing slash, doesn't open.
  */
-export function backtick(options = {}) {
-    const { manifest } = options;
-    const json = JSON.stringify(manifest);
+export function backtickApp(app, RootLayout) {
+    const renderer = backtickRenderer();
     return async (context, next) => {
-        if (manifest !== undefined &&
-            context.req.path === "/manifest.webmanifest") {
-            return context.body(json, 200, {
-                "content-type": "application/manifest+json",
-            });
+        if (context.req.method !== "GET" || context.req.path !== runtimePath) {
+            return renderer(context, next);
         }
-        context.setRenderer(async (input) => {
-            let modules;
-            try {
-                modules = JSON.parse(context.req.header("x-backtick-modules") ?? "{}");
-            }
-            catch (error) {
-                const { name, message } = error;
-                return context.json({ name, message: `x-backtick-modules isn't JSON: ${message}` }, 400);
-            }
-            try {
-                const build = await bundler.build({ input, modules });
-                const { code } = build.generate({ format: "cjs" });
-                context.header("content-type", "text/javascript");
-                context.header("cache-control", "no-store");
-                if (manifest !== undefined) {
-                    context.header("x-backtick-manifest", encodeURIComponent(json));
-                }
-                return context.body(code);
-            }
-            catch (error) {
-                if (error instanceof BundlerError) {
-                    return context.json({ name: error.name, message: error.message }, error.name === "ClientVersionMismatch" ? 426 : 400);
-                }
-                throw error;
-            }
-        });
-        await next();
+        const misplaced = app.routes.find(({ path }) => path.endsWith("/_loading/") || /\/_layout\/?$/.test(path));
+        if (misplaced !== undefined) {
+            throw new Error(misplaced.path.endsWith("/_loading/")
+                ? `The app's ${misplaced.path} route ends with a slash: write it ${misplaced.path.slice(0, -1)}.`
+                : `The app's ${misplaced.path} route is a layout, which a screen doesn't have: the root layout is backtickApp(app, RootLayout)'s, and what screens share is a component they draw.`);
+        }
+        // The app's loading states, by pattern.
+        const loadings = app.routes
+            .filter(({ method, path }) => method === "GET" && path.endsWith("/_loading"))
+            .map(({ path }) => path);
+        return bundled(context, clientRuntime(new URL(context.req.url).origin, context.req.header("x-backtick-modules") ?? "{}", RootLayout, [...new Set(loadings)]));
     };
 }
+// Where the Backtick app fetches the runtime it opens an app with.
+const runtimePath = "/.well-known/backtick/runtime";
+// `input` bundled for the modules the client sent, as the answer.
+async function bundled(context, input) {
+    let modules;
+    try {
+        modules = JSON.parse(context.req.header("x-backtick-modules") ?? "{}");
+    }
+    catch (error) {
+        const { name, message } = error;
+        return context.json({ name, message: `x-backtick-modules isn't JSON: ${message}` }, 400);
+    }
+    try {
+        const build = await bundler.build({ input, modules });
+        const { code } = build.generate({ format: "cjs" });
+        context.header("content-type", "text/javascript");
+        context.header("cache-control", "no-store");
+        return context.body(code);
+    }
+    catch (error) {
+        if (error instanceof BundlerError) {
+            return context.json({ name: error.name, message: error.message }, error.name === "ClientVersionMismatch" ? 426 : 400);
+        }
+        throw error;
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAgB,MAAM,qBAAqB,CAAC;AAwB1E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CACtB,UAAmC,EAAE;IAErC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACtC,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC7B,IACE,QAAQ,KAAK,SAAS;YACtB,OAAO,CAAC,GAAG,CAAC,IAAI,KAAK,uBAAuB,EAC5C,CAAC;YACD,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE;gBAC7B,cAAc,EAAE,2BAA2B;aAC5C,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YAClC,IAAI,OAAgB,CAAC;YACrB,IAAI,CAAC;gBACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,oBAAoB,CAAC,IAAI,IAAI,CAAC,CAAC;YACzE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAoB,CAAC;gBAC/C,OAAO,OAAO,CAAC,IAAI,CACjB,EAAE,IAAI,EAAE,OAAO,EAAE,kCAAkC,OAAO,EAAE,EAAE,EAC9D,GAAG,CACJ,CAAC;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;gBACtD,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnD,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;gBAClD,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;gBAC5C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;gBAClE,CAAC;gBACD,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;oBAClC,OAAO,OAAO,CAAC,IAAI,CACjB,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAC5C,KAAK,CAAC,IAAI,KAAK,uBAAuB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CACnD,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,49 @@
+import { type Client } from "@backtickjs/core";
+import { type ComponentType } from "react";
+/**
+ * What the phone runs an app with. A shell checks for a member before using
+ * it, so a later runtime can drop one.
+ */
+export interface Runtime {
+    /**
+     * The app's root layout, given the href on top. A navigation holds the
+     * current screen until the next can show, as navigations are transitions
+     * (`router.setTransitionMode("always")`): a route with a `_loading` once
+     * that's in, at once if it was prefetched; one without, once its page is
+     * in. Suspends until the first screen can show.
+     */
+    Navigator?: ComponentType<{
+        href: string;
+    }>;
+    /**
+     * A route's screen: what it renders, and meanwhile what its `_loading`
+     * renders. One not `active` yet shows nothing.
+     */
+    Screen?: ComponentType<{
+        href: string;
+        active: boolean;
+    }>;
+    /**
+     * Fetches an href's screen again, which stays until the new one is in:
+     * resolves once it's in, either way.
+     */
+    reload?(href: string): Promise<void>;
+    /**
+     * Fetches an href ahead, as Next.js prefetches a link: its loading state,
+     * or, without one, its page. For each `<Link prefetch>`, which the shell
+     * sees as it's prefetched.
+     */
+    prefetch?(href: string): void;
+}
+/**
+ * A route's answer, run. Any bundle is an answer, whatever its status: an
+ * app's not-found screen is one. A refusal ({ name, message }) says why. For
+ * a route that may not exist (`notFoundIsNull`), a 404 is null.
+ */
+export declare const fetchAnswer: Client<unknown>;
+/**
+ * The runtime of an open: for the phone at `origin` with `modules`, around
+ * the app's root layout, with the patterns of its `_loading` routes
+ * (`/city/:id/_loading`), so a screen asks only for those it has.
+ */
+export declare function clientRuntime(origin: string, modules: string, RootLayout: Client<ComponentType>, loadingPatterns: readonly string[]): Client<Runtime>;

package/dist/runtime.js

@@ -0,0 +1,44 @@
+// The phone's half of `backtickApp()`: how an app's screens are fetched,
+// kept and shown, written as client code, which `backtickApp()` sends from
+// `/.well-known/backtick/runtime`.
+import { cs, exec } from "@backtickjs/core";
+const QueryClient = { "@backtickjs": "ClientImport", name: "QueryClient", from: "@tanstack/react-query", version: "5.104.0" };
+const QueryClientProvider = { "@backtickjs": "ClientImport", name: "QueryClientProvider", from: "@tanstack/react-query", version: "5.104.0" };
+const usePrefetchQuery = { "@backtickjs": "ClientImport", name: "usePrefetchQuery", from: "@tanstack/react-query", version: "5.104.0" };
+const useSuspenseQueries = { "@backtickjs": "ClientImport", name: "useSuspenseQueries", from: "@tanstack/react-query", version: "5.104.0" };
+const useSuspenseQuery = { "@backtickjs": "ClientImport", name: "useSuspenseQuery", from: "@tanstack/react-query", version: "5.104.0" };
+const PatternRouter = { "@backtickjs": "ClientImport", name: "PatternRouter", from: "hono/router/pattern-router", version: "4.13.13" };
+const Component = { "@backtickjs": "ClientImport", name: "Component", from: "react", version: "19.3.0" };
+const Suspense = { "@backtickjs": "ClientImport", name: "Suspense", from: "react", version: "19.3.0" };
+const useDeferredValue = { "@backtickjs": "ClientImport", name: "useDeferredValue", from: "react", version: "19.3.0" };
+const $module0 = {
+    id: "2hmayizp567y2:59:27",
+    code: "(module, exports, require) => {\n\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nexports.default = $splice0 => async (url, modules, notFoundIsNull) => {\n    var response = await fetch(url, {\n        headers: {\n            \"x-backtick-modules\": modules\n        }\n    });\n    if (notFoundIsNull && response.status === 404) {\n        return null;\n    }\n    var body = await response.text();\n    if (!(response.headers.get(\"content-type\") ?? \"\").startsWith(\"text/javascript\")) {\n        var reason = body;\n        try {\n            reason = JSON.parse(body).message ?? body;\n        }\n        catch { }\n        throw new Error(\"The screen couldn't be opened (\" + response.status + \"): \" + reason);\n    }\n    return await $splice0()(body);\n};\n}",
+    map: "{\"version\":3,\"file\":\"module.jsx\",\"mappings\":\";;;kBA0D8BA,QAAA,WAC5BC,GAAW,EACXC,OAAe,EACfC,cAAuB;IAEvB,IAAMC,QAAQ,GAAG,MAAMC,KAAK,CAACJ,GAAG,EAAE;QAChCK,OAAO,EAAE;YAAE,oBAAoB,EAAEJ;SAAO;KACzC,CAAC;IACF,IAAIC,cAAc,IAAIC,QAAQ,CAACG,MAAM,KAAK,GAAG,EAAE;QAC7C,OAAO,IAAI;IACb;IACA,IAAMC,IAAI,GAAG,MAAMJ,QAAQ,CAACK,IAAI,EAAE;IAClC,IACE,CAAC,CAACL,QAAQ,CAACE,OAAO,CAACI,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,EAAEC,UAAU,CAAC,iBAAiB,CAAC,EAC3E;QACA,IAAIC,MAAM,GAAGJ,IAAI;QACjB,IAAI;YACFI,MAAM,GAAGC,IAAI,CAACC,KAAK,CAACN,IAAI,CAAC,CAACO,OAAO,IAAIP,IAAI;QAC3C,CAAC;QAAC,MAAM,CAAC;QACT,MAAM,IAAIQ,KAAK,CACb,iCAAiC,GAAGZ,QAAQ,CAACG,MAAM,GAAG,KAAK,GAAGK,MAAM,CACrE;IACH;IACA,OAAQ,MAAMZ,QAAA,EAAK,CAACQ,IAAa,CAAC;AACpC,CAAC\",\"names\":[\"$splice0\",\"url\",\"modules\",\"notFoundIsNull\",\"response\",\"fetch\",\"headers\",\"status\",\"body\",\"text\",\"get\",\"startsWith\",\"reason\",\"JSON\",\"parse\",\"message\",\"Error\"],\"ignoreList\":[],\"sources\":[\"@backtickjs/hono/src/runtime.tsx\"]}",
+    dependencies: [],
+    params: [{ kind: "splice", bindings: [] }],
+    kind: "function"
+};
+const $module1 = {
+    id: "2hmayizp567y2:96:9",
+    code: "(module, exports, require) => {\n\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nconst jsx_runtime_1 = require(\"react/jsx-runtime\");\nexports.default = ($splice0, $splice1, $splice2, $splice3, $splice4, $splice5, $splice6, $splice7, $splice8, $splice9, $splice10, $splice11, $splice12, $splice13, $splice14, $splice15, $splice16, $splice17, $splice18) => {\n    var pageStaleTime = 30000;\n    var loadingStaleTime = 300000;\n    var queryClient = new ($splice0())({\n        defaultOptions: {\n            queries: {\n                queryFn: async (context) => $splice1()($splice2() + context.queryKey[0], $splice3(), false),\n                staleTime: pageStaleTime,\n                structuralSharing: false,\n                retry: false\n            }\n        }\n    });\n    var loadingQueryOptions = path => ({\n        queryKey: [path],\n        staleTime: loadingStaleTime,\n        queryFn: async () => ({\n            value: await $splice4()($splice5() + path, $splice6(), true)\n        })\n    });\n    var loadingRouter = new ($splice7())();\n    for (var pattern of $splice8()) {\n        loadingRouter.add(\"GET\", pattern, true);\n    }\n    var loadingPathOf = href => {\n        var searchStart = href.indexOf(\"?\");\n        var path = searchStart === -1 ? href : href.slice(0, searchStart);\n        var loading = (path === \"/\" ? \"\" : path) + \"/_loading\";\n        return loadingRouter.match(\"GET\", loading)[0].length > 0 ? loading : undefined;\n    };\n    var dropStaleAnswer = (path, startedAt) => {\n        var query = queryClient.getQueryCache().find({\n            queryKey: [path],\n            exact: true\n        });\n        if (query !== undefined && query.getObserversCount() === 0 && query.state.data !== undefined && query.state.dataUpdatedAt < startedAt && query.isStaleByTime(pageStaleTime)) {\n            queryClient.removeQueries({\n                queryKey: [path],\n                exact: true\n            });\n        }\n    };\n    var Page = props => $splice9()({\n        queryKey: [props.href]\n    }).data;\n    var PageWithLoading = props => {\n        var loading = loadingPathOf(props.href);\n        $splice10()({\n            queryKey: [props.href]\n        });\n        var queries = loading === undefined ? [] : [loadingQueryOptions(loading)];\n        var loadingResult = $splice11()({\n            queries\n        })[0];\n        return loadingResult === undefined ? (0, jsx_runtime_1.jsx)(Page, {\n            href: props.href\n        }) : ($Suspense => (0, jsx_runtime_1.jsx)($Suspense, {\n            fallback: loadingResult.data.value,\n            children: (0, jsx_runtime_1.jsx)(Page, {\n                href: props.href\n            })\n        }))($splice12());\n    };\n    var prefetch = href => {\n        var loading = loadingPathOf(href);\n        if (loading === undefined) {\n            void queryClient.query({\n                queryKey: [href]\n            }).catch(() => { });\n            return;\n        }\n        void queryClient.query(loadingQueryOptions(loading)).then(answer => answer.value === null ? queryClient.query({\n            queryKey: [href]\n        }) : undefined).catch(() => { });\n    };\n    var Screen = props => {\n        var href = $splice13()(props.href);\n        return props.active ? ($Suspense => (0, jsx_runtime_1.jsx)($Suspense, {\n            fallback: null,\n            children: (0, jsx_runtime_1.jsx)(PageWithLoading, {\n                href: href\n            })\n        }))($splice14()) : null;\n    };\n    var AwaitQuery = props => {\n        $splice15()({\n            ...props.query,\n            refetchOnMount: false\n        });\n        return null;\n    };\n    var currentNavigation = {\n        href: \"\",\n        startedAt: 0\n    };\n    var NavigationHold = props => {\n        if (currentNavigation.href !== props.href) {\n            currentNavigation = {\n                href: props.href,\n                startedAt: Date.now()\n            };\n        }\n        dropStaleAnswer(props.href, currentNavigation.startedAt);\n        var loading = loadingPathOf(props.href);\n        if (loading !== undefined) {\n            void queryClient.query({\n                queryKey: [props.href]\n            }).catch(() => { });\n            return (0, jsx_runtime_1.jsx)(AwaitQuery, {\n                query: loadingQueryOptions(loading)\n            });\n        }\n        return (0, jsx_runtime_1.jsx)(AwaitQuery, {\n            query: {\n                queryKey: [props.href]\n            }\n        });\n    };\n    class SilentErrorBoundary extends $splice16() {\n        state = {\n            failed: false\n        };\n        static getDerivedStateFromError() {\n            return {\n                failed: true\n            };\n        }\n        render() {\n            return this.state.failed ? null : this.props.children;\n        }\n    }\n    var Navigator = props => ($QueryClientProvider => (0, jsx_runtime_1.jsxs)($QueryClientProvider, {\n        client: queryClient,\n        children: [(0, jsx_runtime_1.jsx)(SilentErrorBoundary, {\n                children: (0, jsx_runtime_1.jsx)(NavigationHold, {\n                    href: props.href\n                })\n            }, props.href), ($RootLayout => (0, jsx_runtime_1.jsx)($RootLayout, {}))($splice18())]\n    }))($splice17());\n    var runtime = {\n        Navigator,\n        Screen,\n        prefetch,\n        reload: async (href) => {\n            var loading = loadingPathOf(href);\n            await Promise.allSettled((loading === undefined ? [href] : [href, loading]).map(path => queryClient.getQueryState([path])?.status === \"error\" ? queryClient.resetQueries({\n                queryKey: [path],\n                exact: true\n            }) : queryClient.refetchQueries({\n                queryKey: [path],\n                exact: true\n            })));\n        }\n    };\n    return runtime;\n};\n}",
+    map: "{\"version\":3,\"file\":\"module.jsx\",\"mappings\":\"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\",\"names\":[\"$splice0\",\"$splice1\",\"$splice2\",\"$splice3\",\"$splice4\",\"$splice5\",\"$splice6\",\"$splice7\",\"$splice8\",\"$splice9\",\"$splice10\",\"$splice11\",\"$splice12\",\"$splice13\",\"$splice14\",\"$splice15\",\"$splice16\",\"$splice17\",\"$splice18\",\"pageStaleTime\",\"loadingStaleTime\",\"queryClient\",\"defaultOptions\",\"queries\",\"queryFn\",\"context\",\"queryKey\",\"staleTime\",\"structuralSharing\",\"retry\",\"loadingQueryOptions\",\"path\",\"value\",\"loadingRouter\",\"pattern\",\"add\",\"loadingPathOf\",\"href\",\"searchStart\",\"indexOf\",\"slice\",\"loading\",\"match\",\"length\",\"undefined\",\"dropStaleAnswer\",\"startedAt\",\"query\",\"getQueryCache\",\"find\",\"exact\",\"getObserversCount\",\"state\",\"data\",\"dataUpdatedAt\",\"isStaleByTime\",\"removeQueries\",\"Page\",\"props\",\"PageWithLoading\",\"loadingResult\",\"_jsx\",\"$Suspense\",\"fallback\",\"children\",\"prefetch\",\"catch\",\"then\",\"answer\",\"Screen\",\"active\",\"AwaitQuery\",\"refetchOnMount\",\"currentNavigation\",\"NavigationHold\",\"Date\",\"now\",\"SilentErrorBoundary\",\"failed\",\"getDerivedStateFromError\",\"render\",\"Navigator\",\"$QueryClientProvider\",\"_jsxs\",\"client\",\"$RootLayout\",\"runtime\",\"reload\",\"Promise\",\"allSettled\",\"map\",\"getQueryState\",\"status\",\"resetQueries\",\"refetchQueries\"],\"ignoreList\":[],\"sources\":[\"@backtickjs/hono/src/runtime.tsx\"]}",
+    dependencies: ["react/jsx-runtime"],
+    params: [{ kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }, { kind: "splice", bindings: [] }],
+    kind: "block"
+};
+/**
+ * A route's answer, run. Any bundle is an answer, whatever its status: an
+ * app's not-found screen is one. A refusal ({ name, message }) says why. For
+ * a route that may not exist (`notFoundIsNull`), a 404 is null.
+ */
+export const fetchAnswer = cs.create($module0, [exec]);
+/**
+ * The runtime of an open: for the phone at `origin` with `modules`, around
+ * the app's root layout, with the patterns of its `_loading` routes
+ * (`/city/:id/_loading`), so a screen asks only for those it has.
+ */
+export function clientRuntime(origin, modules, RootLayout, loadingPatterns) {
+    return cs.create($module1, [QueryClient, fetchAnswer, origin, modules, fetchAnswer, origin, modules, PatternRouter, loadingPatterns, useSuspenseQuery, usePrefetchQuery, useSuspenseQueries, Suspense, useDeferredValue, Suspense, useSuspenseQuery, Component, QueryClientProvider, RootLayout]);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.tsx"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,2EAA2E;AAC3E,mCAAmC;AACnC,OAAO,EAAe,EAAE,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,8BAwBtB,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,OAAe,EACf,UAAiC,EACjC,eAAkC;IAElC,kSAyLG;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtickjs/hono",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Hono routes as Backtick screens: a route's answer is its server components, bundled for the client that asked",
   "keywords": [
     "backtick",
@@ -37,20 +37,36 @@
     "access": "public"
   },
   "dependencies": {
-    "@backtickjs/bundler": "0.2.7",
-    "@backtickjs/core": "0.2.7"
+    "@backtickjs/bundler": "0.3.0",
+    "@backtickjs/core": "0.3.0"
   },
   "peerDependencies": {
     "hono": "^4.13.13"
   },
   "devDependencies": {
+    "@backtickjs/expo": "0.3.0",
+    "@backtickjs/jsx-react": "0.3.0",
+    "@backtickjs/prettier-plugin": "0.3.0",
+    "@backtickjs/tsc": "0.3.0",
+    "@backtickjs/tspatch-plugin": "0.3.0",
+    "@tanstack/react-query": "5.104.0",
+    "@types/react": "19.3.0",
     "hono": "^4.13.13",
     "prettier": "^3.6.2",
+    "react": "19.3.0",
+    "ts-patch": "4.0.1",
     "typescript": "^6.0.3"
   },
+  "backtick": {
+    "plugins": [
+      "@backtickjs/jsx-react/plugin",
+      "@backtickjs/expo/plugin"
+    ]
+  },
   "scripts": {
-    "build": "tsc -b",
-    "dev": "tsc -b --watch",
+    "build": "tspc -b --noCheck --force",
+    "dev": "tspc -b --noCheck --watch",
+    "typecheck": "backtick-tsc -p tsconfig.build.json --noEmit",
     "format": "prettier --write --ignore-unknown .",
     "format:check": "prettier --check --ignore-unknown .",
     "test": "node --test \"test/**/*.test.ts\"",

package/src/index.ts

@@ -1,9 +1,13 @@
 import { bundler, BundlerError, type Modules } from "@backtickjs/bundler";
-import type { Spliceable, SplicesAs } from "@backtickjs/core";
-import type { MiddlewareHandler } from "hono";
+import type { Client, Spliceable, SplicesAs } from "@backtickjs/core";
+import type { ComponentType } from "react";
+import type { Context, Hono, MiddlewareHandler } from "hono";
+import { clientRuntime } from "./runtime.js";
+
+export type { Runtime } from "./runtime.js";
 
 declare module "hono" {
-  // What `context.render` takes under `backtick()`, as
+  // What `context.render` takes under `backtickRenderer()`, as
   // `jsxRenderer()` types its own.
   interface ContextRenderer {
     <T extends [T] extends [SplicesAs<T>] ? unknown : Spliceable>(
@@ -12,76 +16,113 @@ declare module "hono" {
   }
 }
 
-/** A web app manifest: what the phone uses of an app before and around it. */
-export interface Manifest {
-  name?: string;
-  short_name?: string;
-  icons?: { src: string; sizes?: string; type?: string }[];
-  theme_color?: string;
-  background_color?: string;
-  display?: "fullscreen" | "standalone" | "minimal-ui" | "browser";
-}
-
 /**
  * Hono's renderer for Backtick screens: under it, `context.render(input)`
  * answers with `input` bundled for the modules the client sent in
  * `x-backtick-modules`, so each route is a screen.
  *
- *     app.use(backtick());
+ *     app.use(backtickRenderer());
  *     app.get("/", (context) => context.render(<Home />));
  *
  * The status is the context's, so `context.status(404)` makes a not-found
- * screen, and screens are `no-store`: each opens as its latest copy. A client
+ * screen, and screens are `no-store`, kept out of HTTP caches: a reload or
+ * a new open always gets the latest copy. (The Backtick app reuses a screen
+ * it has, in memory, for 30 seconds, as Next.js's router does.) A client
  * without a module the screen needs gets a 426, and any other refusal of the
- * bundler's a 400, each with `{ name, message }`.
+ * bundler's a 400, each with `{ name, message }`. An app the Backtick app
+ * opens uses `backtickApp(app, RootLayout)` instead.
+ */
+export function backtickRenderer(): MiddlewareHandler {
+  return async (context, next) => {
+    context.setRenderer(async (input) => bundled(context, input as Spliceable));
+    await next();
+  };
+}
+
+/**
+ * Hono's renderer for an app the Backtick app opens, as `backtickRenderer()`,
+ * which also answers the runtime the Backtick app fetches when it opens
+ * `app`: the client code that fetches, keeps and shows its screens, around
+ * its root layout, a client component that draws its `Stack`.
  *
- * `manifest` is the app's web app manifest, at `/manifest.webmanifest` and in
- * `x-backtick-manifest` on every screen, so it's as fresh as they are.
+ *     const RootLayout = cs`() => <$Stack />`;
+ *     app.use(backtickApp(app, RootLayout));
+ *     app.get("/", (context) => context.render(<Home />));
+ *
+ * Every route answers with what it draws. As in Next.js, a route with a
+ * `_loading` route (`/city/:id/_loading`, rendered for the path, so it can
+ * show the city's name) pushes as soon as that's in, at once if it was
+ * prefetched, and shows it until the route's answer is in; a navigation to
+ * one without holds the current screen until its answer is in. The runtime
+ * asks only for the loading states `app` has routes for. One with a layout
+ * route (a screen has none: what screens share is a component they draw), or
+ * with a loading route written with a trailing slash, doesn't open.
  */
-export function backtick(
-  options: { manifest?: Manifest } = {},
+export function backtickApp(
+  app: Hono<any, any, any>,
+  RootLayout: Client<ComponentType>,
 ): MiddlewareHandler {
-  const { manifest } = options;
-  const json = JSON.stringify(manifest);
+  const renderer = backtickRenderer();
   return async (context, next) => {
-    if (
-      manifest !== undefined &&
-      context.req.path === "/manifest.webmanifest"
-    ) {
-      return context.body(json, 200, {
-        "content-type": "application/manifest+json",
-      });
+    if (context.req.method !== "GET" || context.req.path !== runtimePath) {
+      return renderer(context, next);
     }
-    context.setRenderer(async (input) => {
-      let modules: Modules;
-      try {
-        modules = JSON.parse(context.req.header("x-backtick-modules") ?? "{}");
-      } catch (error) {
-        const { name, message } = error as SyntaxError;
-        return context.json(
-          { name, message: `x-backtick-modules isn't JSON: ${message}` },
-          400,
-        );
-      }
-      try {
-        const build = await bundler.build({ input, modules });
-        const { code } = build.generate({ format: "cjs" });
-        context.header("content-type", "text/javascript");
-        context.header("cache-control", "no-store");
-        if (manifest !== undefined) {
-          context.header("x-backtick-manifest", encodeURIComponent(json));
-        }
-        return context.body(code);
-      } catch (error) {
-        if (error instanceof BundlerError) {
-          return context.json(
-            { name: error.name, message: error.message },
-            error.name === "ClientVersionMismatch" ? 426 : 400,
-          );
-        }
-        throw error;
-      }
-    });
-    await next();
+    const misplaced = app.routes.find(
+      ({ path }) => path.endsWith("/_loading/") || /\/_layout\/?$/.test(path),
+    );
+    if (misplaced !== undefined) {
+      throw new Error(
+        misplaced.path.endsWith("/_loading/")
+          ? `The app's ${misplaced.path} route ends with a slash: write it ${misplaced.path.slice(0, -1)}.`
+          : `The app's ${misplaced.path} route is a layout, which a screen doesn't have: the root layout is backtickApp(app, RootLayout)'s, and what screens share is a component they draw.`,
+      );
+    }
+    // The app's loading states, by pattern.
+    const loadings = app.routes
+      .filter(
+        ({ method, path }) => method === "GET" && path.endsWith("/_loading"),
+      )
+      .map(({ path }) => path);
+    return bundled(
+      context,
+      clientRuntime(
+        new URL(context.req.url).origin,
+        context.req.header("x-backtick-modules") ?? "{}",
+        RootLayout,
+        [...new Set(loadings)],
+      ),
+    );
   };
 }
+
+// Where the Backtick app fetches the runtime it opens an app with.
+const runtimePath = "/.well-known/backtick/runtime";
+
+// `input` bundled for the modules the client sent, as the answer.
+async function bundled(context: Context, input: Spliceable): Promise<Response> {
+  let modules: Modules;
+  try {
+    modules = JSON.parse(context.req.header("x-backtick-modules") ?? "{}");
+  } catch (error) {
+    const { name, message } = error as SyntaxError;
+    return context.json(
+      { name, message: `x-backtick-modules isn't JSON: ${message}` },
+      400,
+    );
+  }
+  try {
+    const build = await bundler.build({ input, modules });
+    const { code } = build.generate({ format: "cjs" });
+    context.header("content-type", "text/javascript");
+    context.header("cache-control", "no-store");
+    return context.body(code);
+  } catch (error) {
+    if (error instanceof BundlerError) {
+      return context.json(
+        { name: error.name, message: error.message },
+        error.name === "ClientVersionMismatch" ? 426 : 400,
+      );
+    }
+    throw error;
+  }
+}

package/src/runtime.tsx

@@ -0,0 +1,282 @@
+// The phone's half of `backtickApp()`: how an app's screens are fetched,
+// kept and shown, written as client code, which `backtickApp()` sends from
+// `/.well-known/backtick/runtime`.
+import { type Client, cs, exec } from "@backtickjs/core";
+import {
+  QueryClient,
+  QueryClientProvider,
+  usePrefetchQuery,
+  useSuspenseQueries,
+  useSuspenseQuery,
+} from "@tanstack/react-query" with { backtick: "client" };
+import { PatternRouter } from "hono/router/pattern-router" with {
+  backtick: "client",
+};
+import {
+  Component,
+  type ComponentType,
+  type ReactNode,
+  Suspense,
+  useDeferredValue,
+} from "react" with { backtick: "client" };
+
+/**
+ * What the phone runs an app with. A shell checks for a member before using
+ * it, so a later runtime can drop one.
+ */
+export interface Runtime {
+  /**
+   * The app's root layout, given the href on top. A navigation holds the
+   * current screen until the next can show, as navigations are transitions
+   * (`router.setTransitionMode("always")`): a route with a `_loading` once
+   * that's in, at once if it was prefetched; one without, once its page is
+   * in. Suspends until the first screen can show.
+   */
+  Navigator?: ComponentType<{ href: string }>;
+  /**
+   * A route's screen: what it renders, and meanwhile what its `_loading`
+   * renders. One not `active` yet shows nothing.
+   */
+  Screen?: ComponentType<{ href: string; active: boolean }>;
+  /**
+   * Fetches an href's screen again, which stays until the new one is in:
+   * resolves once it's in, either way.
+   */
+  reload?(href: string): Promise<void>;
+  /**
+   * Fetches an href ahead, as Next.js prefetches a link: its loading state,
+   * or, without one, its page. For each `<Link prefetch>`, which the shell
+   * sees as it's prefetched.
+   */
+  prefetch?(href: string): void;
+}
+
+/**
+ * A route's answer, run. Any bundle is an answer, whatever its status: an
+ * app's not-found screen is one. A refusal ({ name, message }) says why. For
+ * a route that may not exist (`notFoundIsNull`), a 404 is null.
+ */
+export const fetchAnswer = cs`async (
+  url: string,
+  modules: string,
+  notFoundIsNull: boolean,
+) => {
+  const response = await fetch(url, {
+    headers: { "x-backtick-modules": modules },
+  });
+  if (notFoundIsNull && response.status === 404) {
+    return null;
+  }
+  const body = await response.text();
+  if (
+    !(response.headers.get("content-type") ?? "").startsWith("text/javascript")
+  ) {
+    let reason = body;
+    try {
+      reason = JSON.parse(body).message ?? body;
+    } catch {}
+    throw new Error(
+      "The screen couldn't be opened (" + response.status + "): " + reason,
+    );
+  }
+  return (await $exec(body as never)) as unknown;
+}`;
+
+/**
+ * The runtime of an open: for the phone at `origin` with `modules`, around
+ * the app's root layout, with the patterns of its `_loading` routes
+ * (`/city/:id/_loading`), so a screen asks only for those it has.
+ */
+export function clientRuntime(
+  origin: string,
+  modules: string,
+  RootLayout: Client<ComponentType>,
+  loadingPatterns: readonly string[],
+): Client<Runtime> {
+  return cs`{
+    // Every answer is a query, keyed by its path: what the route renders. A
+    // screen is its page's, and its loading state's while the page loads.
+    // Each is reused, in memory, as Next.js's router cache does: a page for
+    // 30 seconds, a loading state for 5 minutes. A screen's no-store keeps it
+    // out of HTTP caches, not this one.
+    const pageStaleTime = 30000;
+    const loadingStaleTime = 300000;
+    const queryClient = new $QueryClient({
+      defaultOptions: {
+        queries: {
+          queryFn: async (context: { queryKey: readonly unknown[] }) =>
+            $fetchAnswer(
+              $origin + (context.queryKey[0] as string),
+              $modules,
+              false,
+            ),
+          staleTime: pageStaleTime,
+          structuralSharing: false,
+          retry: false,
+        },
+      },
+    });
+    // A loading state: none if it answers 404, for a param it has none for.
+    const loadingQueryOptions = (path: string) => ({
+      queryKey: [path],
+      staleTime: loadingStaleTime,
+      queryFn: async () => ({
+        value: (await $fetchAnswer(
+          $origin + path,
+          $modules,
+          true,
+        )) as ReactNode,
+      }),
+    });
+    // An href's loading state, if the app has a _loading route for it,
+    // matched by Hono's own router.
+    const loadingRouter = new $PatternRouter<true>();
+    for (const pattern of $loadingPatterns) {
+      loadingRouter.add("GET", pattern, true);
+    }
+    const loadingPathOf = (href: string) => {
+      const searchStart = href.indexOf("?");
+      const path = searchStart === -1 ? href : href.slice(0, searchStart);
+      const loading = (path === "/" ? "" : path) + "/_loading";
+      return loadingRouter.match("GET", loading)[0].length > 0
+        ? loading
+        : undefined;
+    };
+    // A stale answer no screen shows, in before a navigation started, is
+    // dropped as the navigation reads it, so the navigation waits for a fresh
+    // one, as Next.js's does; one a screen still shows, going back to it, is
+    // kept.
+    const dropStaleAnswer = (path: string, startedAt: number) => {
+      const query = queryClient
+        .getQueryCache()
+        .find({ queryKey: [path], exact: true });
+      if (
+        query !== undefined &&
+        query.getObserversCount() === 0 &&
+        query.state.data !== undefined &&
+        query.state.dataUpdatedAt < startedAt &&
+        query.isStaleByTime(pageStaleTime)
+      ) {
+        queryClient.removeQueries({ queryKey: [path], exact: true });
+      }
+    };
+
+    const Page = (props: { href: string }) =>
+      $useSuspenseQuery({ queryKey: [props.href] }).data as ReactNode;
+
+    // A screen as Next.js shows a page: with a loading state, inside a
+    // Suspense showing it; the page fetched meanwhile.
+    const PageWithLoading = (props: { href: string }) => {
+      const loading = loadingPathOf(props.href);
+      $usePrefetchQuery({ queryKey: [props.href] });
+      const queries: ReturnType<typeof loadingQueryOptions>[] =
+        loading === undefined ? [] : [loadingQueryOptions(loading)];
+      const loadingResult = $useSuspenseQueries({ queries })[0];
+      return loadingResult === undefined ? (
+        <Page href={props.href} />
+      ) : (
+        <$Suspense fallback={loadingResult.data.value}>
+          <Page href={props.href} />
+        </$Suspense>
+      );
+    };
+
+    // Fetches an href ahead, as Next.js prefetches: its loading state, or,
+    // without one, its page.
+    const prefetch = (href: string) => {
+      const loading = loadingPathOf(href);
+      if (loading === undefined) {
+        void queryClient.query({ queryKey: [href] }).catch(() => {});
+        return;
+      }
+      void queryClient
+        .query(loadingQueryOptions(loading))
+        .then((answer) =>
+          answer.value === null
+            ? queryClient.query({ queryKey: [href] })
+            : undefined,
+        )
+        .catch(() => {});
+    };
+
+    // An href changed in place (router.setParams) shows once it's in: the
+    // screen stays meanwhile.
+    const Screen = (props: { href: string; active: boolean }) => {
+      const href = $useDeferredValue(props.href);
+      return props.active ? (
+        <$Suspense fallback={null}>
+          <PageWithLoading href={href} />
+        </$Suspense>
+      ) : null;
+    };
+
+    // Suspends until a query is in. One that is, however old, holds nothing:
+    // a stale page was dropped above, and a stale loading state is refreshed
+    // by the screen, as it's only shown until the page is in.
+    const AwaitQuery = (props: { query: { queryKey: string[] } }) => {
+      $useSuspenseQuery({ ...props.query, refetchOnMount: false });
+      return null;
+    };
+    // When the navigation to the href on top started: kept outside React, as
+    // a hold that suspends keeps no state.
+    let currentNavigation = { href: "", startedAt: 0 };
+    // Suspends a navigation's render, above the Stack, until the href's
+    // loading state is in, or, without one, its page. As navigations are
+    // transitions, the screen on top stays. One that fails ends the hold, for
+    // the screen to show why.
+    const NavigationHold = (props: { href: string }) => {
+      if (currentNavigation.href !== props.href) {
+        currentNavigation = { href: props.href, startedAt: Date.now() };
+      }
+      dropStaleAnswer(props.href, currentNavigation.startedAt);
+      // A route with a loading state pushes as soon as its loading state is
+      // in, at once if it was prefetched; its page is fetched meanwhile.
+      const loading = loadingPathOf(props.href);
+      if (loading !== undefined) {
+        void queryClient.query({ queryKey: [props.href] }).catch(() => {});
+        return <AwaitQuery query={loadingQueryOptions(loading)} />;
+      }
+      return <AwaitQuery query={{ queryKey: [props.href] }} />;
+    };
+    class SilentErrorBoundary extends $Component<
+      { children: ReactNode },
+      { failed: boolean }
+    > {
+      state = { failed: false };
+      static getDerivedStateFromError() {
+        return { failed: true };
+      }
+      render() {
+        return this.state.failed ? null : this.props.children;
+      }
+    }
+
+    const Navigator = (props: { href: string }) => (
+      <$QueryClientProvider client={queryClient}>
+        <SilentErrorBoundary key={props.href}>
+          <NavigationHold href={props.href} />
+        </SilentErrorBoundary>
+        <$RootLayout />
+      </$QueryClientProvider>
+    );
+
+    const runtime: Runtime = {
+      Navigator,
+      Screen,
+      prefetch,
+      // Each of its queries again: one that failed, for its screen to wait
+      // for it; the others kept until the new answer is in.
+      reload: async (href) => {
+        const loading = loadingPathOf(href);
+        await Promise.allSettled(
+          (loading === undefined ? [href] : [href, loading]).map((path) =>
+            queryClient.getQueryState([path])?.status === "error"
+              ? queryClient.resetQueries({ queryKey: [path], exact: true })
+              : queryClient.refetchQueries({ queryKey: [path], exact: true }),
+          ),
+        );
+      },
+    };
+    return runtime;
+  }`;
+}