create-rindle 0.1.6 → 0.3.1

package/README.md

@@ -22,7 +22,8 @@ pnpm dev
 A minimal but real three-tier Rindle app (a tiny forum-of-rooms with **live message counts**):
 
 - **Browser** — a TanStack Start SPA whose data layer is Rindle's in-process wasm IVM engine: local
-  instant reads, optimistic writes, live `subscribe`, and a dev-only Rindle devtools pane.
+  instant reads, optimistic writes, fragment-rooted `useRoot` reads, and a dev-only Rindle devtools
+  pane.
 - **API server** — the authority: named-query resolution, authoritative SQL mutators, and policy (a
   `"spam"` rejection demo shows the optimistic snap-back + toast).
 - **Daemon** (`rindled`) — owns the SQLite data + live incremental views, streamed to subscribers.
@@ -34,6 +35,19 @@ the dev loop), so the TypeScript can't drift from the DDL.
 The prebuilt `rindle` + `rindled` binaries come from `@rindle/cli` (per-platform, installed as a dev
 dependency) — **no Rust toolchain required**.
 
+## Fragment flow in the template
+
+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
+  `useRoot(roomsQuery, RoomCardFragment)` to receive opaque room refs.
+- Row components call `useFragment(RoomCardFragment, room)` to open narrow local reads without a
+  new server subscription.
+- The room detail route calls `useRoot(roomDetailQuery, id)` when the route itself owns the root
+  fields and passes child message refs down with `fragmentKey(ref)` list keys.
+
 ## Usage
 
 ```

package/package.json

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

package/templates/minimal/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md — working on __PROJECT_NAME__
+
+Guidance for coding agents (and new humans). This is a **Rindle** app — an
+incremental-view-maintenance (IVM) engine keeps every registered query's result
+exact on each write instead of re-running it. Three tiers: a TanStack Start SPA
+running the wasm engine in-process, an API authority, and the `rindled` daemon
+that owns the SQLite data. The correctness contract everywhere is
+**view-after-write == fresh-query**.
+
+Rindle docs are served as raw markdown for LLMs: index at
+<https://rindle.sh/llms.txt>, the whole app track in one file at
+<https://rindle.sh/llms-app.txt>.
+
+## Commands
+
+- `pnpm dev` — the only command you need: boots `rindled` (prebuilt binary from
+  `@rindle/cli`, no Rust toolchain), applies `migrations/*.sql`, regenerates
+  `shared/schema.gen.ts`, seeds, and starts Vite (the app + the `/api/rindle`
+  server routes). Re-applies/regenerates on every `migrations/` change.
+- `pnpm typecheck` — regenerates the route tree, then `tsc --noEmit`.
+- `pnpm migrate` / `pnpm seed` — one-shot apply / seed against the running daemon.
+
+## Rules that keep the app correct
+
+Break one of these and the app goes subtly wrong. Treat violations as bugs in
+review:
+
+1. **SQL is the source of truth.** Change the schema by **adding** a
+   `migrations/*.sql` file (additive DDL: `CREATE TABLE` / `ADD COLUMN` /
+   `CREATE INDEX`; every table a single primary key). **Never hand-edit
+   `shared/schema.gen.ts`** — it is generated from the live daemon and
+   overwritten on the next migration.
+2. **Predicted mutators are deterministic and replayable**
+   (`shared/app-def.ts`): no `Date.now()`, no `Math.random()`, no I/O — they
+   re-run on every rebase. Generate ids and timestamps at the callsite and pass
+   them in as args.
+3. **Every mutator has two halves under one name**: the client's *predicted*
+   mutator in `shared/app-def.ts` and the server's *authoritative* SQL twin in
+   `server/app-api.ts`. Add or change them together. Only `(name, args)` ever
+   crosses the wire — validate args hard on the server; `throw` to hard-reject
+   (the optimistic write snaps back on its own; write no rollback code).
+4. **Remote subscriptions must be named.** Define queries with `defineQuery` in
+   `src/components/*.queries.ts` and register them in `server/app-api.ts`. An
+   ad-hoc `store.query.…` builder resolves **locally only** — it never opens a
+   server subscription.
+5. **The daemon token is server-only.** It gates the private control plane
+   (`:7600`) and must never reach the browser; the browser holds only the
+   lease-gated public WebSocket (`:7601`).
+6. **Subscribe to windows, not whole tables** — order + `limit`, and ratchet
+   `limit` up for "load more". The engine keeps the window (and any `countAs`)
+   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.
+
+## File map
+
+| Path | What it is |
+| --- | --- |
+| `migrations/*.sql` | the real schema — the only place DDL lives |
+| `shared/schema.gen.ts` | **generated** table schema — do not edit |
+| `shared/app-def.ts` | the shared contract: relationships, query builder, predicted mutators |
+| `src/components/*.queries.ts` | named queries + fragments, co-located with their components |
+| `src/rindle-client.ts` | the one-call browser wire-up (`createRindleClient`) |
+| `server/app-api.ts` | the authority: `registerQueries` + authoritative SQL mutators + policy |
+| `src/routes/api.rindle.*.tsx` | TanStack Start server routes exposing the authority over HTTP |
+| `server/dev.ts` | dev orchestration (`rindle up` + seed + Vite) |
+| `src/ssr.ts` | SSR preload of the same named queries for first paint |
+
+## Reading more
+
+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`.

package/templates/minimal/src/components/MessageCard.tsx

@@ -8,6 +8,8 @@ import { formatDateTime } from "../lib/format.ts";
 
 export function MessageCard({ message }: { message: MessageCardRef }) {
   const data = useFragment(MessageCardFragment, message);
+  if (!data) return null;
+
   return (
     <article className="app-message">
       <div className="app-message-head">

package/templates/minimal/src/components/RoomCard.tsx

@@ -9,6 +9,8 @@ import type { RoomCardRef } from "./RoomCard.queries.ts";
 
 export function RoomCard({ room }: { room: RoomCardRef }) {
   const data = useFragment(RoomCardFragment, room);
+  if (!data) return null;
+
   return (
     <li className="app-room">
       <Link to="/r/$id" params={{ id: data.id }} className="app-room-link">

package/templates/minimal/src/components/RoomView.queries.ts

@@ -13,7 +13,9 @@ import { MessageCardFragment } from "./MessageCard.queries.ts";
 export const RoomDetailFragment = defineFragment(room, (r) =>
   r
     .select("id", "name", "createdAt")
-    .sub("messages", rels.roomMessages, (m) => m.include(MessageCardFragment).orderBy("createdAt", "asc").orderBy("id", "asc")),
+    .sub("messages", rels.roomMessages, MessageCardFragment, (m) =>
+      m.orderBy("createdAt", "asc").orderBy("id", "asc")
+    ),
 );
 export type RoomDetailRef = FragmentRef<typeof RoomDetailFragment>;
 

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

@@ -70,6 +70,10 @@ async function bootClientInner() {
     },
     // 7601 = the daemon's PUBLIC ws port (7600 is the HTTP control plane).
     daemon: { wsUrl: import.meta.env.VITE_DAEMON_WS ?? "ws://127.0.0.1:7601" },
+    // `dev.resetOnMutationGap` postdates the published @rindle/optimistic (0.2.0); the spread-cast
+    // keeps this scaffold typechecking against the registry package — older clients ignore the key,
+    // newer ones honor it. Inline the option (and drop the cast) once a release includes it.
+    ...({ dev: { resetOnMutationGap: import.meta.env.DEV } } as object),
     onRejected: (envelope, reason) => rejectionHandler(envelope, reason),
   });
 }

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

@@ -2,12 +2,11 @@
 // 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.
 
-import { useMemo } from "react";
 import { createFileRoute } from "@tanstack/react-router";
-import { useQuery, useQueryStatus } from "@rindle/react";
+import { fragmentKey, useRoot } from "@rindle/react";
 import type { DehydratedState } from "@rindle/client";
 
-import { roomsQuery } from "../components/RoomCard.queries.ts";
+import { RoomCardFragment, roomsQuery } from "../components/RoomCard.queries.ts";
 import { RoomCard } from "../components/RoomCard.tsx";
 import { NewRoomForm } from "../components/NewRoomForm.tsx";
 
@@ -23,9 +22,7 @@ export const Route = createFileRoute("/")({
 });
 
 function Home() {
-  const query = useMemo(() => roomsQuery(), []);
-  const rooms = useQuery(query);
-  const status = useQueryStatus(query);
+  const [rooms, { status }] = useRoot(roomsQuery, RoomCardFragment);
   const loading = status !== "complete" && rooms.length === 0;
 
   return (
@@ -42,7 +39,7 @@ function Home() {
       ) : (
         <ul className="app-rooms">
           {rooms.map((room) => (
-            <RoomCard key={room.id} room={room} />
+            <RoomCard key={fragmentKey(room)} room={room} />
           ))}
         </ul>
       )}

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

@@ -2,9 +2,8 @@
 // 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.
 
-import { useMemo } from "react";
 import { Link, createFileRoute } from "@tanstack/react-router";
-import { useQuery, useQueryStatus } from "@rindle/react";
+import { fragmentKey, useRoot } from "@rindle/react";
 import type { DehydratedState } from "@rindle/client";
 
 import { roomDetailQuery } from "../components/RoomView.queries.ts";
@@ -22,9 +21,7 @@ export const Route = createFileRoute("/r/$id")({
 
 function RoomView() {
   const { id } = Route.useParams();
-  const query = useMemo(() => roomDetailQuery(id), [id]);
-  const room = useQuery(query);
-  const status = useQueryStatus(query);
+  const [room, { status }] = useRoot(roomDetailQuery, id);
 
   if (!room) {
     return (
@@ -50,7 +47,7 @@ function RoomView() {
         {messages.length === 0 ? (
           <p className="app-empty">No messages yet — say something below.</p>
         ) : (
-          messages.map((message) => <MessageCard key={message.id} message={message} />)
+          messages.map((message) => <MessageCard key={fragmentKey(message)} message={message} />)
         )}
       </div>