create-rindle 0.7.9 → 0.7.11

package/README.md

@@ -46,7 +46,8 @@ The generated routes use the current co-located fragment pattern:
 
 - `src/components/*.queries.ts` defines each component's `defineFragment` beside the named
   `defineQuery` that roots it.
-- The home route preloads `roomsQuery()` for SSR, then calls
+- The home route declares `roomsQuery()` through `@rindle/tanstack`'s `rindle.loader`, which seeds
+  SSR and waits for the same live query on client navigation, then calls
   `useRoot(roomsQuery, RoomCardFragment)` to receive opaque room refs.
 - Row components call `useFragment(RoomCardFragment, room)` to open narrow local reads without a
   new server subscription.

package/lib/scaffold.mjs

@@ -84,6 +84,7 @@ export default defineConfig({
       { find: /^rindle-wasm-bin/, replacement: wasmBin },
       { find: /^@rindle\\/client$/, replacement: src("client") },
       { find: /^@rindle\\/react$/, replacement: src("react") },
+      { find: /^@rindle\\/tanstack$/, replacement: src("tanstack") },
       { find: /^@rindle\\/optimistic$/, replacement: src("optimistic") },
       { find: /^@rindle\\/normalized$/, replacement: src("normalized") },
       { find: /^@rindle\\/remote$/, replacement: src("remote") },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rindle",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/templates/minimal/AGENTS.md

@@ -67,6 +67,10 @@ review:
    exact as rows enter and leave.
 7. **Keep `*.queries.ts` modules React-free** — no `.tsx` imports. The browser,
    the API authority, and the SSR loader all import these same modules.
+8. **Declare route reads through `rindle.loader(...)`** (`src/rindle-tanstack.ts`).
+   It owns server preloading, client navigation readiness/cancellation, and
+   blocking stale reloads. Keep `rindle.Provider` at the root; do not recreate
+   the old `useMatches()` merge or a separate `<RindleSSR>` wrapper.
 
 ## File map
 
@@ -77,6 +81,7 @@ review:
 | `shared/app-def.ts` | the shared contract: relationships, query builder, isomorphic mutators |
 | `src/components/*.queries.ts` | named queries + fragments, co-located with their components |
 | `src/rindle-client.ts` | the one-call browser wire-up (`createRindleClient`) |
+| `src/rindle-tanstack.ts` | the shared `rindle.loader` + `rindle.Provider` integration |
 | `server/app-api.ts` | the authority: `registerQueries` + `sharedApiMutators` + server-only policy |
 | `src/routes/api.rindle.*.tsx` | TanStack Start server routes exposing the authority over HTTP |
 | `rindle.ncl` | the one topology (the colocated pair) — `rindle up` runs it locally, `rindle deploy` provisions it |
@@ -86,4 +91,4 @@ review:
 
 Per-page markdown mirrors live at `https://rindle.sh/docs/<slug>.md`. Most
 relevant here: `synced-app-quickstart`, `client`, `api-server`, `schema`,
-`fragments`, `supported-queries-ts`, `change-model`.
+`fragments`, `ssr`, `supported-queries-ts`, `change-model`.

package/templates/minimal/README.md

@@ -10,7 +10,9 @@ Three tiers, same as the Rindle flagship examples:
 
 - **Browser** — a TanStack Start SPA whose data layer *is* Rindle. The wasm IVM engine runs
   in-process: reads resolve locally and instantly, writes apply optimistically and reconcile on
-  confirmation. Views are co-located Relay-style fragments (`src/components/*.queries.ts`).
+  confirmation. `@rindle/tanstack` binds route preloading, client navigation readiness, and the
+  SSR-to-live provider handoff. Views are co-located Relay-style fragments
+  (`src/components/*.queries.ts`).
 - **API authority** (`server/app-api.ts`) — resolves named queries to ASTs, drives the **same
   isomorphic mutators** the browser predicted (their logical ops rendered to SQL), and enforces
   policy: reads are public, writes require an identity, and a `"spam"` name/body
@@ -104,6 +106,7 @@ of `vite build` and never ship to production.
 | `server/app-api.ts` | the authority: query resolution, `sharedApiMutators`, policy (host-agnostic) |
 | `server/rindle-http.ts` | adapts the authority to a Web Request (the Start API routes call it) |
 | `src/routes/api.rindle.*.tsx` | the three API endpoints as Start server routes (the browser's API) |
+| `src/rindle-tanstack.ts` | one route-loader/provider binding for SSR and client navigation |
 | `src/ssr.ts` | first-paint preload — calls the authority in-process |
 | `src/components/*.queries.ts` | co-located queries + fragments |
 | `src/routes/*` | TanStack routes |

package/templates/minimal/package.json

@@ -22,6 +22,7 @@
     "@rindle/client": "latest",
     "@rindle/optimistic": "latest",
     "@rindle/react": "latest",
+    "@rindle/tanstack": "latest",
     "@rindle/wasm": "latest",
     "@tanstack/react-router": "latest",
     "@tanstack/react-start": "latest",

package/templates/minimal/rindle.ncl

@@ -16,7 +16,7 @@
 # backed up; scales 1→N in place); `followers > 1` maps to `read-scaled`. `localRetention = true`
 # maps to `colocated` (one box, both processes, no streaming backup).
 #
-# Every follower count renders a local fleet edge (the Fly-edge stand-in;
+# Every follower count renders a local fleet edge;
 # FOLLOWER-AFFINITY-DESIGN.md §10). `rindle dev` injects the server's unified connection from this
 # file; browser query leases carry the public ws endpoint + placement ticket. Changing
 # `followers = 1` to a wider fleet therefore requires no application configuration change.

package/templates/minimal/src/rindle-client.ts

@@ -47,9 +47,8 @@ export function onRejection(handler: RejectionHandler): () => void {
   };
 }
 
-/** The live optimistic client — assigned once {@link bootClient} resolves. Components import this and
- *  call `app.mutate.*` inside event handlers, by which point boot has completed (the provider in
- *  src/RindleApp.tsx gates the whole tree on it). */
+/** The live optimistic client — assigned once {@link bootClient} resolves. `rindle.Provider` and all
+ *  route loaders share this boot; components use the live binding for `app.mutate.*` event handlers. */
 export let app: RindleApp;
 
 /** Dynamically imports the wasm engine + optimistic glue (so the SSR/prerender shell never evaluates

package/templates/minimal/src/rindle-tanstack.ts

@@ -0,0 +1,20 @@
+// The one TanStack Router/Start binding for this app. Routes declare their Rindle queries through
+// `rindle.loader(...)`; the root mounts `rindle.Provider` to merge SSR slices and hand the seeded
+// store off to this same live browser client after hydration.
+
+import { createRindleTanStack } from "@rindle/tanstack";
+
+import { schema } from "../shared/app-def.ts";
+import { bootClient } from "./rindle-client.ts";
+
+export const rindle = createRindleTanStack({
+  schema,
+  boot: bootClient,
+  preload: async (queries) => {
+    // The adapter only calls preload on the server. Keep the static Vite guard as well so ssr.ts —
+    // which builds the daemon client and reads server env — is eliminated from the browser build.
+    if (!import.meta.env.SSR) return {};
+    const { preloadRindle } = await import("./ssr.ts");
+    return preloadRindle([...queries]);
+  },
+});

package/templates/minimal/src/routes/__root.tsx

@@ -1,19 +1,16 @@
-// The root route: the HTML document + the app frame. Inside the document, <RindleApp> renders the
-// merged SSR seed on the server AND through hydration, then boots the in-browser wasm engine
-// (client-only) and swaps to the live store — the SSR→SPA handoff. <TopBar> + <Toaster> are the
-// persistent chrome around the matched view (`children`).
+// The root route: the HTML document + the app frame. Inside the document, rindle.Provider merges
+// every matched route's SSR seed, renders it on the server AND through hydration, then boots the
+// in-browser wasm engine and swaps to the live store. <TopBar> + <Toaster> are the persistent chrome.
 //
-// Each LEAF route owns its own first-paint preload (its loader returns `{ rindle }`); RootDocument
-// merges every matched route's slice, so a first visit to any route seeds exactly the queries it renders.
+// Each leaf route declares its first-paint/navigation query through rindle.loader(...); the adapter
+// owns server preloading, client readiness, cancellation, and the SSR→SPA handoff.
 
-import { useMemo } from "react";
-import { HeadContent, Outlet, Scripts, createRootRoute, useMatches } from "@tanstack/react-router";
-import type { DehydratedState } from "@rindle/client";
+import { HeadContent, Outlet, Scripts, createRootRoute } from "@tanstack/react-router";
 
-import { RindleApp } from "../RindleApp.tsx";
 import { TopBar } from "../components/TopBar.tsx";
 import { Toaster } from "../components/Toaster.tsx";
 import { DevTools } from "../devtools.tsx";
+import { rindle } from "../rindle-tanstack.ts";
 import appCss from "../styles.css?url";
 
 export const Route = createRootRoute({
@@ -39,31 +36,19 @@ export const Route = createRootRoute({
 });
 
 function RootDocument() {
-  // Merge the dehydrated first-paint cache from EVERY matched route, so a first visit to any route
-  // seeds exactly the queries it renders.
-  const matches = useMatches();
-  const ssrState = useMemo<DehydratedState>(() => {
-    const merged: DehydratedState = {};
-    for (const match of matches) {
-      const slice = (match.loaderData as { rindle?: DehydratedState } | undefined)?.rindle;
-      if (slice) Object.assign(merged, slice);
-    }
-    return merged;
-  }, [matches]);
-
   return (
     <html lang="en">
       <head>
         <HeadContent />
       </head>
       <body>
-        <RindleApp ssrState={ssrState}>
+        <rindle.Provider>
           <TopBar />
           <main className="app-main">
             <Outlet />
           </main>
           <Toaster />
-        </RindleApp>
+        </rindle.Provider>
         {/* Dev-only floating devtools pane (tree-shaken out of production builds). */}
         <DevTools />
         <Scripts />

package/templates/minimal/src/routes/index.tsx

@@ -1,23 +1,17 @@
 // The home view (`/`): the list of rooms, each with a LIVE message count, plus a form to create a
-// room. Its loader seeds the rooms query for first paint (SSR); after hydration the wasm engine owns
-// the live read — post a message in any room and its count here updates with no polling.
+// room. Its Rindle loader seeds the rooms query for first paint and blocks client navigation until
+// the live query is ready — post a message in any room and its count here updates with no polling.
 
 import { createFileRoute } from "@tanstack/react-router";
 import { fragmentKey, useRoot } from "@rindle/react";
-import type { DehydratedState } from "@rindle/client";
 
 import { RoomCardFragment, roomsQuery } from "../components/RoomCard.queries.ts";
 import { RoomCard } from "../components/RoomCard.tsx";
 import { NewRoomForm } from "../components/NewRoomForm.tsx";
+import { rindle } from "../rindle-tanstack.ts";
 
 export const Route = createFileRoute("/")({
-  loader: async (): Promise<{ rindle: DehydratedState }> => {
-    if (!import.meta.env.SSR) return { rindle: {} };
-    // Dynamic import: ssr.ts is server-only (it builds the daemon client), so it must never enter the
-    // client bundle. The static `import.meta.env.SSR` guard + this dynamic import keep it out.
-    const { preloadRindle } = await import("../ssr.ts");
-    return { rindle: await preloadRindle([roomsQuery()]) };
-  },
+  loader: rindle.loader({ query: () => roomsQuery() }),
   component: Home,
 });
 

package/templates/minimal/src/routes/r.$id.tsx

@@ -1,21 +1,17 @@
 // A room view (`/r/:id`): the room's messages oldest-first, each a live row, plus the composer. The
-// single detail query is seeded by the loader for first paint; after hydration the wasm engine owns
-// the live read and every new message streams in.
+// Rindle loader seeds the detail query for first paint and blocks client navigation until it is
+// ready; after hydration the wasm engine owns the live read and every new message streams in.
 
 import { Link, createFileRoute } from "@tanstack/react-router";
 import { fragmentKey, useRoot } from "@rindle/react";
-import type { DehydratedState } from "@rindle/client";
 
 import { roomDetailQuery } from "../components/RoomView.queries.ts";
 import { MessageCard } from "../components/MessageCard.tsx";
 import { Composer } from "../components/Composer.tsx";
+import { rindle } from "../rindle-tanstack.ts";
 
 export const Route = createFileRoute("/r/$id")({
-  loader: async ({ params }): Promise<{ rindle: DehydratedState }> => {
-    if (!import.meta.env.SSR) return { rindle: {} };
-    const { preloadRindle } = await import("../ssr.ts");
-    return { rindle: await preloadRindle([roomDetailQuery(params.id)]) };
-  },
+  loader: rindle.loader({ query: ({ params }) => roomDetailQuery(params.id) }),
   component: RoomView,
 });
 

package/templates/minimal/src/ssr.ts

@@ -3,12 +3,12 @@
 // (server/app-api.ts) — the SAME `createAppApi` factory the /api/rindle server route uses, called
 // IN-PROCESS (no HTTP hop) because SSR and the API now share one server. The authority resolves
 // `(name, args)` → AST itself; the loader never ships a raw AST. It returns the dehydrated snapshot
-// for the HTML, the browser hydrates it (src/RindleApp.tsx) for an instant correct first paint, then
-// the wasm engine boots and the live `subscribe` reconciles.
+// for the HTML, `rindle.Provider` hydrates it for an instant correct first paint, then the wasm engine
+// boots and the live `subscribe` reconciles.
 //
 // This is a STRICTLY server-side module: it builds the daemon client and reads `process.env`, so it is
-// imported ONLY from inside a loader's `import.meta.env.SSR` guard (a dynamic import), keeping it out
-// of the client bundle. It never imports the engine.
+// imported ONLY by src/rindle-tanstack.ts behind an `import.meta.env.SSR` guard, keeping it out of the
+// client bundle. It never imports the engine.
 
 import { createServerStore, type DehydratedState, type OneShotQueryFn, type OneShotResult, type Query } from "@rindle/client";
 import type { ApiContext } from "@rindle/api-server";
@@ -32,8 +32,9 @@ const readInProcess: OneShotQueryFn = async ({ name, args }): Promise<OneShotRes
 };
 
 /** Preload the given NAMED queries through the authority and return the dehydrated first-paint cache to
- *  embed in the HTML. Call from a route loader (server only). `preloadAll` degrades a failed read to no
- *  seed for that query (the live engine fills it in after hydration) rather than breaking the whole page. */
+ *  embed in the HTML. Called by the integration's server-only preload hook. `preloadAll` degrades a
+ *  failed read to no seed for that query (the live engine fills it in after hydration) rather than
+ *  breaking the whole page. */
 export async function preloadRindle(queries: Array<Query<any, any, any>>): Promise<DehydratedState> {
   return createServerStore(schema, { query: readInProcess }).preloadAll(queries, {
     onError: (_query, err) =>

package/templates/minimal/src/RindleApp.tsx

@@ -1,19 +0,0 @@
-// The SSR→SPA store handoff. The handoff itself — seed the render from the SSR snapshot, boot the
-// wasm engine after hydration, swap the store under `useQuery` with no flash — lives in `<RindleSSR>`
-// (@rindle/react). This file just binds THIS app's `schema` + `bootClient` into it, so the route
-// tree keeps rendering `<RindleApp ssrState={…}>` unchanged.
-
-import type { ReactNode } from "react";
-import { RindleSSR } from "@rindle/react";
-import type { DehydratedState } from "@rindle/client";
-
-import { schema } from "../shared/app-def.ts";
-import { bootClient } from "./rindle-client.ts";
-
-export function RindleApp({ ssrState, children }: { ssrState: DehydratedState; children: ReactNode }) {
-  return (
-    <RindleSSR schema={schema} ssrState={ssrState} boot={bootClient}>
-      {children}
-    </RindleSSR>
-  );
-}