@pylonsync/create-pylon 0.3.264 → 0.3.265

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.264",
+  "version": "0.3.265",
   "description": "Scaffold a new Pylon app — realtime backend + web/mobile/expo frontends in one command. Run via `npm create @pylonsync/pylon@latest`.",
   "publishConfig": {
     "access": "public"

package/templates/ssr/AGENTS.md

@@ -26,7 +26,7 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 - **Type page props from the SDK, don't hand-roll them.** `import type { PageProps, Metadata } from "@pylonsync/react"`. Every page/layout gets `{ url, params, searchParams, auth, response, serverData }`; `PageProps<{ slug: string }>` types a `[slug]` route's params. Request headers/cookies are intentionally NOT on `PageProps` — they're server-only and stripped from hydration, so reading them in the render would mismatch.
 - **Anonymous output caching is opt-in + earned.** `export const revalidate = 60` (seconds) on a page makes it CDN-cacheable (`public, s-maxage=60`) — but ONLY if the render is auth-INDEPENDENT: it must NOT read `props.auth` (reading it at all opts out, even for anonymous), set no cookie, and the app must not run strict per-caller policies (`PYLON_STRICT_FN_POLICIES`). `export const dynamic = "force-static"` caches until the next deploy; `"force-dynamic"` never caches. Fail-closed: without the opt-in (or if any condition fails) the page is `no-cache`. A page that reads `auth` or sets a cookie is never shared. The SAME earned render is also kept in an **origin disk cache** (`.pylon/.cache/ssr`): a cookie-less GET with no query string is served straight off disk for the TTL — skipping the render entirely — then re-rendered live when stale. The disk cache is namespaced per deploy (wiped on each new build) and OFF in `pylon dev` (so an edit is never masked by a stale entry); invalidation is by the `revalidate` TTL or the next deploy.
 - **No-JS forms use `route.ts` + `<Form>`.** Drop `app/.../route.ts` exporting `export const POST: RouteHandler = async ({ form, db, response, auth }) => { await db.insert("X", {...}); response.redirect("/x?ok=1"); }` (303 POST-redirect-GET by default). Render `<Form action="/x">` (from @pylonsync/react) with plain `<input name=...>` — works with JS off (native POST→handler→redirect) and is enhanced to no-reload when JS is on. The handler's `db` is read+write (mutation trust model — gate on `auth`); CSRF is automatic (Origin gate + SameSite=Lax). Multipart/file uploads aren't supported yet — use urlencoded forms + `/api/files`.
-- **`loading.tsx` streams a skeleton while the page's data resolves.** Drop `app/.../loading.tsx` (default export, page props) and the nearest one becomes a route-level Suspense fallback: Pylon flushes the shell + skeleton immediately, then reveals the real page when its top-level `use(serverData…)` resolves (no blank page). It only shows when the PAGE suspends — a page that wraps its own `<Suspense>` around a child (like `/notes`) handles that itself. The skeleton is SERVER-ONLY: don't read `serverData` in it. A page with no `loading.tsx` is buffered (unchanged).
+- **`loading.tsx` streams a skeleton while the page's data resolves.** Drop `app/.../loading.tsx` (default export, page props) and the nearest one becomes a route-level Suspense fallback: Pylon flushes the shell + skeleton immediately, then reveals the real page when its top-level `use(serverData…)` resolves (no blank page). It only shows when the PAGE suspends — a page that wraps its own `<Suspense>` around a child (like `/dashboard` in this template) handles that itself. The skeleton is SERVER-ONLY: don't read `serverData` in it. A page with no `loading.tsx` is buffered (unchanged).
 - **`export const streaming = true` streams a page's OWN inner `<Suspense>` boundaries.** Without it (and without a `loading.tsx`), a page is BUFFERED — the whole document, including suspended children, resolves before the first byte. Opt in and the shell + each inner `<Suspense>` fallback flush immediately, then each boundary's real content streams in as its data resolves (multi-boundary progressive streaming). It's opt-in because it changes the response timing contract: a streaming render commits its HTTP head BEFORE suspended subtrees finish, so (a) it's never CDN/disk cacheable — don't combine with `export const revalidate`; (b) `response.setStatus/setCookie/redirect/notFound` only take effect from the SYNCHRONOUS shell render — a call from inside a suspended subtree is dropped (the runtime logs a loud warning naming what was lost); (c) a `throw` from a deep `<Suspense>` child resolves via its nearest `error.tsx` at HTTP 200, not a 5xx. Hydration is clean for any number of boundaries (the data blob ships before hydration runs). Type the config with `import type { RouteSegmentConfig } from "@pylonsync/react"`.
 - **`error.tsx` / `not-found.tsx` boundaries are HYDRATED (interactive).** `app/.../error.tsx` catches a throw below it (HTTP 500) and receives `{ error: { message, digest }, reset }` (`import type { ErrorBoundaryProps }`) — `reset()` re-attempts the route; the stack NEVER reaches the client (dev overlay + logs only). `app/.../not-found.tsx` renders at 404 (also for `response.notFound()`) and gets the page props (`NotFoundProps`), no `reset`. Both run useState/onClick/hooks.
 - **Client navigation hooks live in @pylonsync/react.** `useRouter()` → `{ push, replace, back, forward, refresh, prefetch }`; `useSearchParams()` → reactive `URLSearchParams`; `usePathname()` → reactive pathname. The hooks are CLIENT-reactive — during SSR they return defaults (empty params / "/"); for server-side URL values read the `url` / `searchParams` page props.

package/templates/ssr/README.md

@@ -1,8 +1,8 @@
 # __APP_NAME__
 
-A full-stack [Pylon](https://pylonsync.com) app — server-rendered React,
-file-based routes, a synced database, and a typed client, served from one
-binary on one port. No Next.js, no separate API server.
+A full-stack [Pylon](https://pylonsync.com) app — a server-rendered homepage,
+email/password auth, and a live client dashboard over a synced database, all
+served from one binary on one port. No Next.js, no separate API server.
 
 ## Develop
 
@@ -10,23 +10,37 @@ binary on one port. No Next.js, no separate API server.
 __RUN_DEV__
 ```
 
-Open http://localhost:4321. Edit any file under `app/` and save — the page
-reloads instantly.
+Open http://localhost:4321. Sign up, and your notes dashboard updates live
+(open a second tab to watch writes sync). Edit any file under `app/` and save —
+the page reloads instantly.
 
 ## Layout
 
 ```
-app.ts            your data model + manifest (entities, functions, policies, routes)
-app/              file-based SSR routes — app/page.tsx is "/", app/counter/page.tsx is "/counter"
-app/layout.tsx    the root layout wrapping every page (receives url + auth)
-app/globals.css   Tailwind entrypoint (compiled by Pylon)
-functions/        server functions (query/action) — typed RPC, auto-exposed
+app.ts                 data model + manifest (entities, policies, auth, routes)
+app/page.tsx           "/" — the server-rendered, auth-aware homepage
+app/login,signup/      email/password forms (POST /api/auth/password/*)
+app/dashboard/         "/dashboard" — authed; server-gated, live notes + sign out
+app/auth-form.tsx      shared client island for the login/signup forms
+app/layout.tsx         root layout wrapping every page (auth-aware nav)
+app/globals.css        Tailwind entrypoint (compiled by Pylon)
+functions/             server functions (query/mutation/action) — typed RPC
 ```
 
+## How auth works
+
+Email/password is built in. `/login` and `/signup` call
+`/api/auth/password/*`; on success the server sets an **HttpOnly session
+cookie** (no token in JS-readable storage). `/dashboard` reads `auth` during
+the server render and redirects anonymous visitors to `/login` — a real 3xx
+before any HTML, so there's no flash and it works with JS off. The sync engine
+authenticates with the same cookie.
+
 ## Add a route
 
 Drop a file at `app/about/page.tsx` and visit `/about`. Pages receive
-`{ url, auth, searchParams }` from the SSR runtime.
+`{ url, params, searchParams, auth, response, serverData }` from the SSR
+runtime — all typed via `PageProps` from `@pylonsync/react`.
 
 ## Add data
 

package/templates/ssr/app/auth-form.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+import React, { useState } from "react";
+import { passwordLogin, passwordRegister, ApiError } from "@pylonsync/client";
+import { Button } from "@/components/ui/button";
+
+// The email/password form, shared by /login and /signup. It calls the built-in
+// auth API directly — `passwordLogin` / `passwordRegister` (from
+// @pylonsync/client) POST to `/api/auth/password/*`.
+//
+// On success the server sets an HttpOnly session cookie on the response. We do
+// a full navigation to /dashboard rather than a client transition: the fresh
+// page load hands that cookie to the SSR runtime (which resolves auth and
+// renders the dashboard server-side) and to the sync engine (which
+// authenticates with the same cookie via `credentials: include`). Because the
+// cookie is HttpOnly it can never be read by JavaScript, so there is no
+// session token sitting in `localStorage` for an XSS to lift. (Cross-origin or
+// native clients, which can't rely on the cookie, use the token-based path via
+// `persistSession` instead — not needed here, same origin.)
+export function AuthForm({ mode }: { mode: "login" | "signup" }) {
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [displayName, setDisplayName] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    setPending(true);
+    try {
+      if (mode === "login") {
+        await passwordLogin({ email, password });
+      } else {
+        await passwordRegister({
+          email,
+          password,
+          displayName: displayName.trim() || undefined,
+        });
+      }
+      // Full navigation: the SSR dashboard re-renders with the new cookie.
+      window.location.assign("/dashboard");
+    } catch (err) {
+      setError(messageFor(err));
+      setPending(false); // keep the form up to retry (success navigates away)
+    }
+  }
+
+  return (
+    <form onSubmit={onSubmit} className="space-y-4">
+      {mode === "signup" ? (
+        <Field
+          label="Name"
+          value={displayName}
+          onChange={setDisplayName}
+          autoComplete="name"
+          placeholder="optional"
+        />
+      ) : null}
+      <Field
+        label="Email"
+        type="email"
+        value={email}
+        onChange={setEmail}
+        required
+        autoComplete="email"
+        placeholder="you@example.com"
+      />
+      <Field
+        label="Password"
+        type="password"
+        value={password}
+        onChange={setPassword}
+        required
+        autoComplete={mode === "login" ? "current-password" : "new-password"}
+        placeholder={mode === "signup" ? "at least 8 characters" : undefined}
+      />
+      {error ? (
+        <p className="rounded-md border border-red-600/30 bg-red-600/10 px-3 py-2 text-sm text-red-700">
+          {error}
+        </p>
+      ) : null}
+      <Button type="submit" disabled={pending} className="w-full">
+        {pending ? "…" : mode === "login" ? "Sign in" : "Create account"}
+      </Button>
+    </form>
+  );
+}
+
+function Field({
+  label,
+  value,
+  onChange,
+  type = "text",
+  required,
+  autoComplete,
+  placeholder,
+}: {
+  label: string;
+  value: string;
+  onChange: (v: string) => void;
+  type?: string;
+  required?: boolean;
+  autoComplete?: string;
+  placeholder?: string;
+}) {
+  return (
+    <label className="block space-y-1.5">
+      <span className="text-sm font-medium">{label}</span>
+      <input
+        type={type}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        required={required}
+        autoComplete={autoComplete}
+        placeholder={placeholder}
+        className="flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm outline-none focus-visible:ring-1 focus-visible:ring-ring"
+      />
+    </label>
+  );
+}
+
+// Map the framework's auth error codes to friendly copy. `ApiError` carries a
+// stable `.code` (and `.status`) so you branch on the code, not the message.
+function messageFor(err: unknown): string {
+  if (err instanceof ApiError) {
+    switch (err.code) {
+      case "INVALID_CREDENTIALS":
+        return "Wrong email or password.";
+      case "USER_EXISTS":
+        return "That email is already in use — sign in instead.";
+      case "WEAK_PASSWORD":
+        return "Pick a stronger password (at least 8 characters).";
+      case "RATE_LIMITED":
+        return "Too many attempts — try again in a minute.";
+      default:
+        return err.message;
+    }
+  }
+  if (err instanceof Error) return err.message;
+  return "Something went wrong. Try again.";
+}

package/templates/ssr/app/dashboard/dashboard-client.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+import React, { useState } from "react";
+import { db } from "@pylonsync/react";
+import { useAuth } from "@pylonsync/client";
+import { Button } from "@/components/ui/button";
+
+export interface Note {
+  id: string;
+  body: string;
+  done: boolean;
+}
+
+// The interactive dashboard. `db.useQuery` is a LIVE subscription — it
+// re-renders the instant a Note is added or toggled, in this tab or another.
+// `db.insert` / `db.update` / `db.delete` are OPTIMISTIC: they apply to the
+// local store immediately (zero-latency UI) and sync in the background,
+// rolling back automatically if a policy rejects the write.
+//
+// `initial` are the rows the server rendered into the HTML (see page.tsx).
+// We show them on the first paint — before the local store has hydrated — so
+// there's no empty flash, then hand off to the live data. Server-rendered for
+// the first byte, local-first realtime after.
+export function Dashboard({ initial }: { initial: Note[] }) {
+  const { signOut } = useAuth();
+  const [body, setBody] = useState("");
+  const { data: live, loading } = db.useQuery<Note>("Note");
+  const notes = !loading || live.length > 0 ? live : initial;
+
+  async function addNote(e: React.FormEvent) {
+    e.preventDefault();
+    const text = body.trim();
+    if (!text) return;
+    setBody("");
+    // We don't send ownerId — `field.owner()` stamps it from the session
+    // server-side and rejects any forged value, so this optimistic insert is
+    // safe.
+    await db.insert("Note", { body: text, done: false });
+  }
+
+  async function onSignOut() {
+    // Clears the server session (DELETE /api/auth/session → the cookie is
+    // cleared), then we land back on the public homepage.
+    await signOut();
+    window.location.assign("/");
+  }
+
+  return (
+    <div className="space-y-5">
+      <div className="flex items-center justify-end">
+        <Button variant="ghost" size="sm" onClick={onSignOut}>
+          Sign out
+        </Button>
+      </div>
+
+      <form onSubmit={addNote} className="flex items-center gap-2">
+        <input
+          value={body}
+          onChange={(e) => setBody(e.target.value)}
+          placeholder="Write a note…"
+          aria-label="Note"
+          className="flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        />
+        <Button type="submit">Add</Button>
+      </form>
+
+      {notes.length === 0 ? (
+        <p className="text-sm text-muted-foreground">
+          No notes yet — add one above. It appears instantly (optimistic) and
+          syncs; open this page in a second tab to watch it arrive live.
+        </p>
+      ) : (
+        <ul className="space-y-2">
+          {notes.map((note) => (
+            <li
+              key={note.id}
+              className="flex items-center gap-3 rounded-md border px-3 py-2 text-sm"
+            >
+              <button
+                type="button"
+                aria-label={note.done ? "Mark not done" : "Mark done"}
+                onClick={() =>
+                  db.update("Note", note.id, { done: !note.done })
+                }
+                className={
+                  note.done
+                    ? "text-emerald-600"
+                    : "text-muted-foreground/50 hover:text-muted-foreground"
+                }
+              >
+                {note.done ? "✓" : "○"}
+              </button>
+              <span
+                className={
+                  note.done
+                    ? "flex-1 line-through text-muted-foreground"
+                    : "flex-1"
+                }
+              >
+                {note.body}
+              </span>
+              <button
+                type="button"
+                aria-label="Delete note"
+                onClick={() => db.delete("Note", note.id)}
+                className="text-muted-foreground/40 hover:text-red-600"
+              >
+                ✕
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/templates/ssr/app/dashboard/page.tsx

@@ -0,0 +1,70 @@
+import React, { Suspense, use } from "react";
+import {
+  type Metadata,
+  type PageProps,
+  type ServerData,
+} from "@pylonsync/react";
+import { Dashboard, type Note } from "./dashboard-client";
+
+export const metadata: Metadata = {
+  title: "Dashboard — __APP_NAME__",
+  robots: "noindex",
+};
+
+interface User {
+  id: string;
+  email: string;
+  displayName?: string;
+}
+
+// Reads the signed-in user + their notes DURING the server render. The reads
+// run through the same policy gate as a client query, so they're owner-scoped
+// (User: only your row; Note: only your notes) — see the policies in app.ts.
+// React 19 `use()` suspends until they resolve on the server, so the HTML
+// arrives with your notes already in it (no empty flash); then the <Dashboard>
+// island hydrates and takes over live.
+function DashboardBody({
+  serverData,
+  userId,
+}: {
+  serverData: ServerData;
+  userId: string;
+}) {
+  const user = use(serverData.get<User>("User", userId));
+  const notes = use(serverData.list<Note>("Note"));
+  return (
+    <>
+      <p className="text-sm text-muted-foreground">
+        Signed in as{" "}
+        <span className="font-medium text-foreground">
+          {user?.displayName || user?.email || "you"}
+        </span>
+        .
+      </p>
+      <Dashboard initial={notes} />
+    </>
+  );
+}
+
+// `app/dashboard/page.tsx` → `/dashboard`.
+export default function DashboardPage({
+  auth,
+  response,
+  serverData,
+}: PageProps) {
+  // Server-side auth gate: anonymous requests get a 307 to /login before any
+  // HTML. The redirect MUST fire here in the synchronous shell render — not
+  // inside the <Suspense> below — or React swallows it. No flash of the
+  // dashboard, works with JS disabled.
+  if (!auth.user_id) response.redirect("/login");
+  return (
+    <div className="space-y-6">
+      <h1 className="text-2xl font-semibold tracking-tight">Your notes</h1>
+      <Suspense
+        fallback={<p className="text-sm text-muted-foreground">Loading…</p>}
+      >
+        <DashboardBody serverData={serverData} userId={auth.user_id!} />
+      </Suspense>
+    </div>
+  );
+}

package/templates/ssr/app/layout.tsx

@@ -2,18 +2,18 @@ import React from "react";
 import { Link, type PageAuth } from "@pylonsync/react";
 
 // A layout receives the page props plus `children`. `auth.user_id` is null
-// for anonymous visitors — wire a sign-in flow with @pylonsync/client when
-// you're ready; for now this just shows the session state. The `PageAuth`
-// type is exported from @pylonsync/react so you never hand-roll it.
+// for anonymous visitors and the signed-in user's id otherwise — resolved
+// server-side from the session cookie, before any HTML is sent, so the nav
+// renders the right links on the first byte (no flash, no client fetch). The
+// `PageAuth` type is exported from @pylonsync/react so you never hand-roll it.
 interface LayoutProps {
   children: React.ReactNode;
   url: string;
   auth: PageAuth;
 }
 
-// The root layout wraps every page. It receives `url` and `auth` from the
-// SSR runtime on every render — server-side, before the HTML is sent.
-export default function RootLayout({ children, url, auth }: LayoutProps) {
+// The root layout wraps every page.
+export default function RootLayout({ children, auth }: LayoutProps) {
   const signedIn = Boolean(auth?.user_id);
   // Add `className="dark"` to this <html> to flip every shadcn token to its
   // dark value. The classes below use semantic tokens (bg-background,
@@ -41,18 +41,23 @@ export default function RootLayout({ children, url, auth }: LayoutProps) {
               <Link href="/" className="hover:text-foreground">
                 Home
               </Link>
-              <Link href="/counter" className="hover:text-foreground">
-                Counter
-              </Link>
-              <Link href="/notes" className="hover:text-foreground">
-                Notes
-              </Link>
-              <span
-                className={signedIn ? "text-emerald-600" : "text-muted-foreground/60"}
-                title={url}
-              >
-                {signedIn ? `· ${auth.user_id}` : "· anon"}
-              </span>
+              {signedIn ? (
+                <Link href="/dashboard" className="hover:text-foreground">
+                  Dashboard
+                </Link>
+              ) : (
+                <>
+                  <Link href="/login" className="hover:text-foreground">
+                    Sign in
+                  </Link>
+                  <Link
+                    href="/signup"
+                    className="rounded-md bg-primary px-3 py-1.5 font-medium text-primary-foreground hover:opacity-90"
+                  >
+                    Sign up
+                  </Link>
+                </>
+              )}
             </nav>
           </div>
         </header>

package/templates/ssr/app/login/page.tsx

@@ -0,0 +1,47 @@
+import React from "react";
+import { Link, type Metadata, type PageProps } from "@pylonsync/react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { AuthForm } from "../auth-form";
+
+export const metadata: Metadata = {
+  title: "Sign in — __APP_NAME__",
+  // Auth pages shouldn't be indexed.
+  robots: "noindex",
+};
+
+// `app/login/page.tsx` → `/login`. A server-rendered shell around the
+// client-side <AuthForm> island.
+export default function LoginPage({ auth, response }: PageProps) {
+  // Already signed in? Skip the form. `response.redirect` runs in the
+  // synchronous shell render, so it's a real 307 before any HTML is sent
+  // (no flash, works with JS disabled).
+  if (auth.user_id) response.redirect("/dashboard");
+  return (
+    <div className="mx-auto max-w-sm">
+      <Card>
+        <CardHeader>
+          <CardTitle>Sign in</CardTitle>
+          <CardDescription>Welcome back.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <AuthForm mode="login" />
+          <p className="text-center text-sm text-muted-foreground">
+            No account?{" "}
+            <Link
+              href="/signup"
+              className="font-medium text-foreground hover:underline"
+            >
+              Create one
+            </Link>
+          </p>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/templates/ssr/app/page.tsx

@@ -16,83 +16,99 @@ import {
 export const metadata: Metadata = {
   title: "__APP_NAME__ — full-stack Pylon app",
   description:
-    "Server-rendered React, file-based routes, a synced database, and a typed client — one binary, one port.",
+    "A server-rendered homepage, email/password auth, and a live client dashboard over one synced backend — one binary, one port.",
 };
 
-// `app/page.tsx` → `/`. Every page receives `PageProps` from the SSR
-// runtime: `{ url, params, searchParams, auth, response, serverData }` —
-// the type is exported from @pylonsync/react, no hand-rolled interface.
-// This renders to HTML on the server; the per-route chunk hydrates it in
-// the browser so interactive pages (see /counter) just work. shadcn/ui is
-// pre-wired — `Button`/`Card` resolve through the `@/` alias; add more with
-// `npx shadcn@latest add <component>`.
-export default function IndexPage({ url }: PageProps) {
+// `app/page.tsx` → `/`. This page is server-rendered: view source and the copy
+// is in the HTML, not fetched later — good for SEO and first paint. It reads
+// `auth` (resolved from the session cookie during the render) to show the
+// right call to action. Every page receives `PageProps` from the SSR runtime:
+// `{ url, params, searchParams, auth, response, serverData }` — typed, no
+// hand-rolled interface.
+export default function IndexPage({ auth }: PageProps) {
+  const signedIn = Boolean(auth.user_id);
   return (
-    <div className="space-y-8">
-      <section>
-        <h1 className="text-3xl font-semibold tracking-tight">__APP_NAME__</h1>
-        <p className="mt-2 text-muted-foreground">
-          A full-stack Pylon app. Server-rendered React, file-based routes,
-          a synced database, and a typed client — served from one binary on
-          one port. No Next.js, no separate API server. Styled with Tailwind
-          v4 and shadcn/ui out of the box.
+    <div className="space-y-12">
+      <section className="space-y-5">
+        <span className="inline-flex items-center rounded-full border px-3 py-1 text-xs font-medium text-muted-foreground">
+          Server-rendered · authenticated · synced · one port
+        </span>
+        <h1 className="text-4xl font-semibold tracking-tight">
+          Full-stack apps, one binary.
+        </h1>
+        <p className="max-w-xl text-lg text-muted-foreground">
+          This homepage is server-rendered React. Sign in and your dashboard
+          becomes a live, local-first view over the same Pylon backend — writes
+          appear instantly and sync across tabs. No Next.js, no separate API
+          server, no realtime sidecar.
         </p>
+        <div className="flex flex-wrap items-center gap-3">
+          {signedIn ? (
+            <Button asChild>
+              <Link href="/dashboard">Go to your dashboard →</Link>
+            </Button>
+          ) : (
+            <>
+              <Button asChild>
+                <Link href="/signup">Get started</Link>
+              </Button>
+              <Button asChild variant="outline">
+                <Link href="/login">Sign in</Link>
+              </Button>
+            </>
+          )}
+        </div>
       </section>
 
-      <Card>
-        <CardHeader>
-          <CardTitle>Next steps</CardTitle>
-          <CardDescription>
-            Everything below is already wired — just edit the files.
-          </CardDescription>
-        </CardHeader>
-        <CardContent>
-          <ul className="space-y-2 text-sm text-foreground/80">
-            <li>
-              Add a route: drop a file at{" "}
-              <code className="rounded bg-muted px-1">app/about/page.tsx</code>{" "}
-              and visit <code className="rounded bg-muted px-1">/about</code>.
-            </li>
-            <li>
-              Add data: edit{" "}
-              <code className="rounded bg-muted px-1">app.ts</code> — every{" "}
-              <code className="rounded bg-muted px-1">entity()</code> gets a
-              REST + realtime API and a typed client automatically.
-            </li>
-            <li>
-              Add a component:{" "}
-              <code className="rounded bg-muted px-1">
-                npx shadcn@latest add dialog
-              </code>{" "}
-              drops it into{" "}
-              <code className="rounded bg-muted px-1">components/ui</code>.
-            </li>
-          </ul>
-        </CardContent>
-      </Card>
-
-      <div className="flex flex-wrap items-center gap-3">
-        <Button asChild>
-          <Link href="/counter">See hydration in action →</Link>
-        </Button>
-        <Button asChild variant="outline">
-          <Link href="/notes">Server data in the render →</Link>
-        </Button>
-        <Button asChild variant="ghost">
-          <a
-            href="https://docs.pylon.dev"
-            target="_blank"
-            rel="noreferrer noopener"
-          >
-            Read the docs
-          </a>
-        </Button>
-      </div>
+      <section className="grid gap-4 sm:grid-cols-3">
+        <Feature title="Server-rendered">
+          File-based routes under <Code>app/</Code>. Pages render to HTML on the
+          server with <Code>metadata</Code> in <Code>{"<head>"}</Code>, then
+          hydrate. Drop <Code>app/about/page.tsx</Code> to add{" "}
+          <Code>/about</Code>.
+        </Feature>
+        <Feature title="Auth included">
+          Email/password is built in. <Code>/login</Code> and{" "}
+          <Code>/signup</Code> hit <Code>/api/auth/password/*</Code>; the server
+          sets an HttpOnly session cookie. <Code>/dashboard</Code> gates on it
+          server-side.
+        </Feature>
+        <Feature title="Synced database">
+          Every <Code>entity()</Code> in <Code>app.ts</Code> gets a REST +
+          realtime API and a typed client. <Code>db.useQuery</Code> is live;{" "}
+          <Code>db.insert</Code> is optimistic.
+        </Feature>
+      </section>
 
       <p className="text-xs text-muted-foreground">
-        You're at <code>{url}</code>. Edit{" "}
-        <code>app/page.tsx</code> and save — the page reloads instantly.
+        Edit <Code>app/page.tsx</Code> and save — the page reloads instantly.
+        The data model and access policies live in <Code>app.ts</Code>.
       </p>
     </div>
   );
 }
+
+function Feature({
+  title,
+  children,
+}: {
+  title: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="text-base">{title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <CardDescription className="text-sm leading-relaxed">
+          {children}
+        </CardDescription>
+      </CardContent>
+    </Card>
+  );
+}
+
+function Code({ children }: { children: React.ReactNode }) {
+  return <code className="rounded bg-muted px-1 text-xs">{children}</code>;
+}

package/templates/ssr/app/robots.ts

@@ -0,0 +1,12 @@
+import type { Robots } from "@pylonsync/react";
+
+// app/robots.ts → served at /robots.txt. The default export may also be async.
+const SITE = process.env.SITE_URL ?? "http://localhost:4321";
+
+export default function robots(): Robots {
+  return {
+    // Keep the authenticated app and the API out of the index.
+    rules: { userAgent: "*", allow: "/", disallow: ["/dashboard", "/api/"] },
+    sitemap: `${SITE}/sitemap.xml`,
+  };
+}

package/templates/ssr/app/signup/page.tsx

@@ -0,0 +1,44 @@
+import React from "react";
+import { Link, type Metadata, type PageProps } from "@pylonsync/react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { AuthForm } from "../auth-form";
+
+export const metadata: Metadata = {
+  title: "Create your account — __APP_NAME__",
+  robots: "noindex",
+};
+
+// `app/signup/page.tsx` → `/signup`. Same shell as /login, register mode.
+export default function SignupPage({ auth, response }: PageProps) {
+  if (auth.user_id) response.redirect("/dashboard");
+  return (
+    <div className="mx-auto max-w-sm">
+      <Card>
+        <CardHeader>
+          <CardTitle>Create your account</CardTitle>
+          <CardDescription>
+            Email + password. No credit card, no email verification step in dev.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <AuthForm mode="signup" />
+          <p className="text-center text-sm text-muted-foreground">
+            Already have an account?{" "}
+            <Link
+              href="/login"
+              className="font-medium text-foreground hover:underline"
+            >
+              Sign in
+            </Link>
+          </p>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/templates/ssr/app/sitemap.ts

@@ -0,0 +1,27 @@
+import type { Sitemap } from "@pylonsync/react";
+
+// app/sitemap.ts → served at /sitemap.xml. The default export can be async, so
+// it can enumerate dynamic pages from your database. Point SITE_URL at your
+// domain in production.
+const SITE = process.env.SITE_URL ?? "http://localhost:4321";
+
+export default async function sitemap(): Promise<Sitemap> {
+  // Only public pages belong here — /dashboard is private (and noindex), so
+  // it's intentionally left out.
+  const staticRoutes: Sitemap = [
+    { url: `${SITE}/`, changeFrequency: "weekly", priority: 1 },
+    { url: `${SITE}/login`, changeFrequency: "yearly", priority: 0.3 },
+    { url: `${SITE}/signup`, changeFrequency: "yearly", priority: 0.5 },
+  ];
+
+  // The export is async, so you can enumerate dynamic pages from a DB read:
+  //
+  //   const posts = await fetchPublishedPosts();
+  //   const postRoutes: Sitemap = posts.map((p) => ({
+  //     url: `${SITE}/blog/${p.slug}`,
+  //     lastModified: p.updatedAt,
+  //   }));
+  //   return [...staticRoutes, ...postRoutes];
+
+  return staticRoutes;
+}

package/templates/ssr/app.ts

@@ -1,28 +1,87 @@
-import { buildManifest, discoverAppRoutes, entity, field } from "@pylonsync/sdk";
+import {
+  entity,
+  field,
+  policy,
+  auth,
+  buildManifest,
+  discoverAppRoutes,
+} from "@pylonsync/sdk";
 
-// Your data model. Every `entity()` becomes a synced table with a REST +
-// realtime API and a typed client — no migrations to write, no resolvers
-// to wire. Add fields here and they show up everywhere.
-const Note = entity("Note", {
-  body: field.string(),
-  done: field.boolean().default(false),
+// Accounts. Email/password auth is built in: POST /api/auth/password/register
+// hashes the password and writes this row; /api/auth/password/login mints a
+// session and sets an HttpOnly cookie. The framework treats the entity named
+// "User" as the account table — `passwordHash` is server-only and never
+// serialized to a client.
+const User = entity(
+  "User",
+  {
+    email: field.string(),
+    displayName: field.string().optional(),
+    passwordHash: field.string().serverOnly().optional(),
+    createdAt: field.datetime().defaultNow(),
+  },
+  { indexes: [{ name: "by_email", fields: ["email"], unique: true }] },
+);
+
+// A note that belongs to one user. `ownerId: field.owner()` is the key move:
+// the framework stamps the signed-in user's id server-side on insert and
+// rejects any forged value — so the dashboard can do a plain, optimistic
+// `db.insert("Note", { body })` (the row shows instantly, no round-trip) while
+// the owner stays unspoofable. No createNote function to write.
+const Note = entity(
+  "Note",
+  {
+    ownerId: field.string().owner(),
+    body: field.string(),
+    done: field.boolean().default(false),
+    createdAt: field.datetime().defaultNow(),
+  },
+  { indexes: [{ name: "by_owner", fields: ["ownerId"], unique: false }] },
+);
+
+// Notes are private — every read and write is gated to the owner. An entity
+// with NO policy is denied to clients by default, so this is exactly what
+// makes the dashboard's live query + optimistic writes work, and only for
+// your own rows. `auth.userId` is the session user; `data.ownerId` is the row.
+const notePolicy = policy({
+  name: "note_access",
+  entity: "Note",
+  allowRead: "auth.userId == data.ownerId",
+  allowInsert: "auth.userId != null",
+  allowUpdate: "auth.userId == data.ownerId",
+  allowDelete: "auth.userId == data.ownerId",
+});
+
+// User rows are read-only to clients, and only your own (so the dashboard can
+// read your display name). The auth subsystem owns writes — registration and
+// login go through /api/auth/password/*, never the entity API.
+const userPolicy = policy({
+  name: "user_access",
+  entity: "User",
+  allowRead: "auth.userId == data.id",
+  allowInsert: "false",
+  allowUpdate: "false",
+  allowDelete: "false",
 });
 
-// The manifest is your whole app in one object: data, server functions,
-// access policies, and the file-based routes under `app/`. `pylon dev`
-// reads this, serves the SSR frontend and the API from one port, and
-// regenerates a typed client on every change.
-//
-// File-based routing: `discoverAppRoutes()` walks `app/**/page.tsx` and
-// emits one route per page. Drop `app/about/page.tsx` to add `/about` —
-// no route table to maintain.
+// The manifest is your whole app in one object: data, policies, and the
+// file-based routes under `app/`. `pylon dev` reads this, serves the SSR
+// frontend and the API from one port, and regenerates a typed client on
+// every change.
 const manifest = buildManifest({
   name: "__APP_NAME__",
   version: "0.1.0",
-  entities: [Note],
+  entities: [User, Note],
   queries: [],
   actions: [],
-  policies: [],
+  policies: [userPolicy, notePolicy],
+  // Email/password is on by default against the User entity above. `auth()`
+  // is the knob for session lifetime, exposed fields, orgs, and trusted
+  // origins — `auth({ session: { expiresIn: 60 * 60 * 24 * 7 } })` for a
+  // 7-day session, etc.
+  auth: auth(),
+  // File-based routing: `discoverAppRoutes()` walks `app/**/page.tsx` and
+  // emits one route per page. Drop `app/about/page.tsx` to add `/about`.
   routes: await discoverAppRoutes(),
 });
 

package/templates/ssr/package.json

@@ -12,6 +12,7 @@
     "@pylonsync/react": "^__PYLON_VERSION__",
     "@pylonsync/sdk": "^__PYLON_VERSION__",
     "@pylonsync/functions": "^__PYLON_VERSION__",
+    "@pylonsync/client": "^__PYLON_VERSION__",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tailwindcss": "^4.3.0",

package/templates/ssr/app/counter/page.tsx

@@ -1,54 +0,0 @@
-import React from "react";
-import type { PageProps } from "@pylonsync/react";
-import { Button } from "@/components/ui/button";
-
-// `app/counter/page.tsx` → `/counter`. This page is server-rendered AND
-// interactive: the HTML arrives with the initial count already in it (try
-// /counter?start=10), then the per-route chunk hydrates and useState takes
-// over. No client/server split to manage — it's one component. The buttons
-// are shadcn/ui `Button`s, hydrated in place.
-export default function CounterPage({ searchParams }: PageProps) {
-  const start = Number(searchParams.start ?? "0") || 0;
-  const [count, setCount] = React.useState(start);
-  return (
-    <div className="space-y-6">
-      <h1 className="text-2xl font-semibold tracking-tight">Counter</h1>
-      <p className="text-muted-foreground">
-        Rendered on the server, hydrated in the browser. The buttons work
-        because the page's JS chunk hydrated this exact markup.
-      </p>
-      <div className="flex items-center gap-4">
-        <Button
-          variant="outline"
-          size="icon"
-          onClick={() => setCount((c) => c - 1)}
-          aria-label="Decrement"
-        >
-          −
-        </Button>
-        <span className="min-w-12 text-center text-2xl font-semibold tabular-nums">
-          {count}
-        </span>
-        <Button
-          variant="outline"
-          size="icon"
-          onClick={() => setCount((c) => c + 1)}
-          aria-label="Increment"
-        >
-          +
-        </Button>
-      </div>
-      <p className="text-xs text-muted-foreground">
-        Initial value comes from <code>?start=</code> — search params flow
-        through SSR. Try{" "}
-        <a
-          href="/counter?start=10"
-          className="text-primary underline-offset-4 hover:underline"
-        >
-          /counter?start=10
-        </a>
-        .
-      </p>
-    </div>
-  );
-}

package/templates/ssr/app/notes/page.tsx

@@ -1,153 +0,0 @@
-import React, { Suspense, use } from "react";
-import {
-  Form,
-  type Metadata,
-  type PageProps,
-  type ServerData,
-} from "@pylonsync/react";
-import { Button } from "@/components/ui/button";
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from "@/components/ui/card";
-
-// SEO metadata for `/notes`. (`generateMetadata(props)` is the dynamic
-// form when the title depends on params — e.g. a `[slug]` route.)
-export const metadata: Metadata = {
-  title: "Notes — __APP_NAME__",
-  description:
-    "A list of notes read from the database during the server render — no client fetch, no loading flash.",
-};
-
-// Progressive streaming opt-in (#278). With this, the page shell — heading,
-// blurb, the <Form> — flushes to the browser IMMEDIATELY, and the inner
-// <Suspense> around <NotesList> streams in its "Loading notes…" fallback,
-// then swaps in the real rows when serverData resolves. Without it, the whole
-// page (including the notes) is buffered and arrives in one shot. Streaming
-// pages are never CDN/disk-cached (the head commits before the data resolves),
-// so don't combine it with `export const revalidate`.
-export const streaming = true;
-
-// The `Note` entity from app.ts. Type your rows however you like; the
-// shape is whatever your entity declares.
-interface Note {
-  id: string;
-  body: string;
-  done: boolean;
-}
-
-// This component reads the database DURING the render. `serverData.list`
-// returns a promise; React 19 `use()` suspends the subtree until it
-// resolves on the server, then the HTML streams with the rows already in
-// it — no `useEffect`, no client round-trip, no loading flash on first
-// paint. The resolved value is replayed into the hydration payload, so the
-// browser renders the exact same markup. Reads run through the same policy
-// gate as a query function's `ctx.db`; writes are rejected.
-function NotesList({ serverData }: { serverData: ServerData }) {
-  const notes = use(serverData.list<Note>("Note"));
-
-  if (notes.length === 0) {
-    return (
-      <p className="text-sm text-muted-foreground">
-        No notes yet. Create one through the auto-generated API:{" "}
-        <code className="rounded bg-muted px-1">
-          curl -X POST localhost:8787/api/entities/Note -d
-          '{"{"}"body":"hello"{"}"}'
-        </code>{" "}
-        then refresh.
-      </p>
-    );
-  }
-
-  return (
-    <ul className="space-y-2">
-      {notes.map((note) => (
-        <li
-          key={note.id}
-          className="flex items-center gap-3 rounded-md border px-3 py-2 text-sm"
-        >
-          <span
-            aria-hidden
-            className={
-              note.done
-                ? "text-emerald-600"
-                : "text-muted-foreground/50"
-            }
-          >
-            {note.done ? "✓" : "○"}
-          </span>
-          <span className={note.done ? "line-through text-muted-foreground" : ""}>
-            {note.body}
-          </span>
-        </li>
-      ))}
-    </ul>
-  );
-}
-
-// `app/notes/page.tsx` → `/notes`. The page destructures `serverData` out
-// of its `PageProps` and hands it to the suspending child. (The same props
-// carry `response` for status/redirect/cookies and `params`/`searchParams`
-// for the URL — all typed, all from @pylonsync/react.)
-export default function NotesPage({ serverData, searchParams }: PageProps) {
-  return (
-    <div className="space-y-6">
-      <section>
-        <h1 className="text-2xl font-semibold tracking-tight">Notes</h1>
-        <p className="mt-2 text-muted-foreground">
-          These rows are read from the database <em>during the server
-          render</em> with <code>serverData</code> + React&apos;s{" "}
-          <code>use()</code>. The HTML arrives with the data in it — view
-          source and you&apos;ll see the notes in the markup, not an empty
-          shell that fetches later.
-        </p>
-      </section>
-
-      {/* No-JS form (#276). Posts to app/notes/route.ts, which creates a Note
-          and 303-redirects back here. Works with JS disabled; the runtime
-          enhances it (no full reload) when JS is on. */}
-      {searchParams.created ? (
-        <p className="rounded-md border border-emerald-600/30 bg-emerald-600/10 px-3 py-2 text-sm text-emerald-700">
-          Note added.
-        </p>
-      ) : null}
-      {searchParams.error ? (
-        <p className="rounded-md border border-red-600/30 bg-red-600/10 px-3 py-2 text-sm text-red-700">
-          {searchParams.error}
-        </p>
-      ) : null}
-      <Form action="/notes" className="flex items-center gap-2">
-        <input
-          name="body"
-          placeholder="Write a note…"
-          aria-label="Note"
-          className="flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm outline-none focus-visible:ring-1 focus-visible:ring-ring"
-        />
-        <Button type="submit">Add</Button>
-      </Form>
-
-      <Card>
-        <CardHeader>
-          <CardTitle>From the database</CardTitle>
-          <CardDescription>
-            Server-rendered, then hydrated. Edit{" "}
-            <code className="rounded bg-muted px-1">app.ts</code> to change
-            the <code className="rounded bg-muted px-1">Note</code> shape.
-          </CardDescription>
-        </CardHeader>
-        <CardContent>
-          <Suspense
-            fallback={
-              <p className="text-sm text-muted-foreground">Loading notes…</p>
-            }
-          >
-            <NotesList serverData={serverData} />
-          </Suspense>
-        </CardContent>
-      </Card>
-    </div>
-  );
-}

package/templates/ssr/app/notes/route.ts

@@ -1,21 +0,0 @@
-import { type RouteHandler } from "@pylonsync/react";
-
-// `app/notes/route.ts` → handles POST /notes (the same path the page lives at).
-// A `<Form action="/notes">` posts here; we create a Note, then 303-redirect
-// back to /notes (POST-redirect-GET) so a no-JS browser re-renders with the new
-// note. Validation errors round-trip through a query param. With JS, the
-// runtime intercepts the submit + swaps the page in without a full reload —
-// same handler, no extra code.
-//
-// CSRF is automatic: Pylon's Origin gate rejects cross-site POSTs before this
-// runs, and the session cookie is SameSite=Lax. Writes here use the normal
-// function trust model — gate sensitive actions on `auth` inside the handler.
-export const POST: RouteHandler = async ({ form, db, response }) => {
-  const body = (form.get("body") ?? "").trim();
-  if (!body) {
-    response.redirect("/notes?error=" + encodeURIComponent("Note can't be empty"));
-    return;
-  }
-  await db.insert("Note", { body });
-  response.redirect("/notes?created=1");
-};