@pylonsync/create-pylon 0.3.274 → 0.3.275

package/templates/creator/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md — working in a Pylon project
+
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+
+## Directory conventions
+
+**Unified SSR app:**
+- `app.ts` — data model + manifest (`entity()` + `field.*`, queries/actions/policies, `routes: await discoverAppRoutes()`). Ends with `console.log(JSON.stringify(manifest))`.
+- `app/` — file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. `app/layout.tsx` is the shell; `app/error.tsx` / `app/not-found.tsx` are boundaries.
+- `app/globals.css` — Tailwind v4 entrypoint (auto-compiled and injected).
+- `functions/` — server functions, one per file, `default`-exported.
+- `.pylon/` — local dev state (sqlite, jobs, sessions, uploads). Created by `pylon dev`. Do not commit.
+
+**Monorepo app:** backend is `apps/api/` (entry `apps/api/schema.ts`, handlers in `apps/api/functions/`); frontend in `apps/web/`. `pylon.manifest.json` / `pylon.client.ts` are generated — do not hand-edit.
+
+## The core authoring loop
+
+1. **Define an entity** — `entity("Thing", { name: field.string(), done: field.boolean().default(false) })`. Modifiers: `.optional()`, `.unique()`, `.readonly()` (settable on insert, rejected on client update — use for `authorId`/`orgId`), `.serverOnly()` (never in HTTP responses), `.encrypted()` (AEAD at rest, needs `PYLON_ENCRYPTION_KEY`), `.crdt("text")` (collaborative).
+2. **Write a policy** — `policy({ entity: "Thing", allowRead, allowInsert, allowUpdate, allowDelete })` with CEL-like expressions over `auth.*` / `data.*` (e.g. `"auth.userId == data.authorId"`). **Omitted actions DENY by default.** Wide-open dev policies (`allow*: "true"`) are flagged by `pylon lint` — tighten before shipping.
+3. **Author a function** in `functions/<name>.ts` — `query` (read-only), `mutation` (transactional read+write), or `action` (external I/O, no direct `ctx.db`). Import `{ query, mutation, action, v }` from `@pylonsync/functions`. `auth` defaults to `"user"` (secure-by-default); set `"public"` explicitly for unauthenticated access. Use `ctx.db.*`, `ctx.auth.userId`, `ctx.error(code, msg)`.
+4. **Read it on the client** — `db.useQuery("Thing")` (live, re-renders on any write) or `db.useQueryOne("Thing", id)`. Call functions with `db.fn(name, args)` / `callFn`. On SSR pages, read via `use(serverData.list("Thing"))` inside `<Suspense>`.
+
+## Key gotchas
+
+- **Policies deny by default; server functions BYPASS them.** Direct client CRUD (`/api/entities/*`) and sync are policy-checked. Functions run with full DB access — enforce trust with `ctx.auth` checks inside the handler, not policies.
+- **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 `/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.
+- **Dynamic + catch-all routes follow Next conventions.** `app/blog/[slug]/page.tsx` → `params.slug`. `app/docs/[...path]/page.tsx` is a catch-all (matches `/docs/a/b/c`; `params.path === "a/b/c"` — `.split("/")` for segments). `app/shop/[[...filters]]/page.tsx` is an optional catch-all (also matches the bare `/shop`, with `params.filters === ""`). A catch-all must be the last segment; static beats dynamic beats catch-all on overlap.
+- **`serverData` (SSR) is READ-ONLY.** No write methods; the runtime rejects write frames (`SSR_WRITE_FORBIDDEN`). Mutations belong in actions/functions, never in a page render.
+- **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` / `<Suspense>`. The HTTP head commits when the shell is ready — status/headers/cookies set from a suspended subtree are lost, and `redirect`/`notFound` thrown below a Suspense boundary are swallowed.
+- **`ctx.llm` and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db` — use `ctx.runQuery` / `ctx.runMutation`.
+- **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
+- **There is no `ctx.files` or `defineWorkflow`/`defineJob`.** Files go through `<FileUpload>` + `/api/files/*`; deferred execution is `ctx.scheduler.runAfter/runAt/cancel`.
+
+## Use the CLI — don't guess
+
+| Need | Command |
+|---|---|
+| Run the app (SSR + API, hot reload, one port `:4321`) | `pylon dev` (or `npm run dev`) |
+| Regenerate manifest + typed client | `pylon codegen` (Swift client: `pylon codegen client --target swift`) |
+| Validate / diff / push schema | `pylon schema check` \| `diff` \| `push` |
+| Migrations | `pylon migrate create <name>` \| `plan` \| `apply` |
+| Lint policies (PYL001–PYL004) | `pylon lint --strict` |
+| Tests | `pylon test` |
+| Adversarial security probe | `pylon test:security` |
+| Inspect cloud request logs (agent-safe) | `pylon logs --json --limit 50` |
+| Inspect data / entities | `pylon data entities` \| `pylon data list <Entity>` |
+| Call a function | `pylon fn <name> key=value` |
+| Health snapshot | `pylon status` |
+| Build for prod | `pylon build` |
+| Deploy (Pylon Cloud by default) | `pylon deploy` |
+| Look up an error code | `pylon explain <CODE>` |
+
+`--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
+
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.

package/templates/creator/README.md

@@ -0,0 +1,67 @@
+# __APP_NAME__
+
+A personal-brand / creator site built with [Pylon](https://pylonsync.com) — a
+server-rendered landing page with a **live newsletter subscriber counter** and a
+private owner dashboard, all from one binary on one port. No Next.js, no
+separate API server.
+
+The realtime point: the subscriber count ticks up for everyone with the page
+open the instant someone subscribes.
+
+## Develop
+
+```bash
+__RUN_DEV__
+```
+
+Open http://localhost:4321. Then **open a second tab**, subscribe in one, and
+watch the counter increment in the other — with no refresh.
+
+## How the realtime works
+
+- `functions/subscribe.ts` — a public **mutation** that validates, lowercases,
+  and dedupes the email, inserts one `Subscriber` row, and bumps a public,
+  PII-free `SubscriberCount` row.
+- `app/newsletter-signup.tsx` subscribes to `SubscriberCount` with
+  `db.useQuery`, so the live count syncs to every open tab. No polling.
+
+## Privacy — read this
+
+The `Subscriber` entity holds reader emails (PII), so its policy in `app.ts`
+**denies every client read and write**. The public page only ever reads the
+aggregate `SubscriberCount` (a bare integer); the full list — with emails —
+comes back only through `subscriberStats`, gated to the owner server-side.
+
+## The owner dashboard
+
+`/dashboard` shows total subscribers, a growth chart, a searchable list, and CSV
+export — updating live as people subscribe.
+
+Set `PYLON_OWNER_EMAIL` in `.env` (see `.env.example`) to the email you'll sign
+in with, then create that account at `/login`.
+
+## Rebrand it
+
+Everything lives in **`lib/site.config.ts`** — your name, colors, bio,
+offerings, testimonials, newsletter copy, links. Edit that one file (or have a
+generator produce it) and the whole page re-themes.
+
+## Layout
+
+```
+app.ts                       Subscriber + SubscriberCount + User + policies
+lib/site.config.ts           ALL copy + brand + offerings + newsletter (edit this)
+functions/subscribe.ts       public mutation: validate + dedupe + count
+functions/subscriberStats.ts owner-only query: subscribers + emails
+app/page.tsx                 the landing page (server-rendered)
+app/newsletter-signup.tsx    client island: signup form + live counter
+app/dashboard/               owner dashboard (auth-gated, live)
+```
+
+## Deploy
+
+```bash
+pylon deploy
+```
+
+Docs: https://docs.pylonsync.com

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

@@ -0,0 +1,129 @@
+"use client";
+
+import React, { useState } from "react";
+import {
+  passwordLogin,
+  passwordRegister,
+  persistSession,
+  ApiError,
+} from "@pylonsync/client";
+
+// The owner's email/password form — one form, two modes. It calls the built-in
+// auth API directly (`passwordLogin` / `passwordRegister` POST to
+// `/api/auth/password/*`), then `persistSession` writes the freshly-minted
+// token to local storage so the sync engine + `callFn` authenticate AS THE
+// OWNER on the next load. This step matters here specifically: the landing page
+// mints an anonymous guest session (for the live counter), and without
+// persisting the real session that stale guest token would shadow the owner's
+// — so the owner-only `subscriberStats` call would come back as a guest and get
+// rejected. We then do a full navigation to /dashboard so the SSR runtime
+// re-resolves auth from the HttpOnly cookie and renders server-side.
+//
+// A newsletter is single-tenant: there's no public subscriber funnel, just the owner
+// creating their one account. Whoever signs in only sees data if their email
+// matches PYLON_OWNER_EMAIL — enforced by the subscriberStats function.
+export function AuthForm() {
+  const [mode, setMode] = useState<"login" | "subscriber">("login");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = 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 {
+      const session =
+        mode === "login"
+          ? await passwordLogin({ email, password })
+          : await passwordRegister({ email, password });
+      // Make this session authoritative, replacing any anonymous guest token.
+      persistSession(session);
+      window.location.assign("/dashboard");
+    } catch (err) {
+      setError(messageFor(err));
+      setPending(false);
+    }
+  }
+
+  return (
+    <div className="space-y-5">
+      <form onSubmit={onSubmit} className="space-y-4">
+        <label className="block">
+          <span className="mb-1.5 block text-[13px] font-medium text-zinc-700">Email</span>
+          <input
+            type="email"
+            value={email}
+            onChange={(e) => setEmail(e.target.value)}
+            required
+            autoComplete="email"
+            placeholder="you@yourbusiness.com"
+            className="h-10 w-full rounded-lg border border-zinc-300 bg-white px-3 text-sm text-zinc-900 outline-none transition placeholder:text-zinc-400 focus:border-brand focus:ring-2 focus:ring-brand/20"
+          />
+        </label>
+        <label className="block">
+          <span className="mb-1.5 block text-[13px] font-medium text-zinc-700">Password</span>
+          <input
+            type="password"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            required
+            autoComplete={mode === "login" ? "current-password" : "new-password"}
+            placeholder={mode === "login" ? "Your password" : "At least 10 characters"}
+            className="h-10 w-full rounded-lg border border-zinc-300 bg-white px-3 text-sm text-zinc-900 outline-none transition placeholder:text-zinc-400 focus:border-brand focus:ring-2 focus:ring-brand/20"
+          />
+        </label>
+        {error ? (
+          <p className="rounded-lg border border-red-200 bg-red-50 px-3 py-2 text-[13px] leading-snug text-red-700">
+            {error}
+          </p>
+        ) : null}
+        <button
+          type="submit"
+          disabled={pending}
+          className="inline-flex h-10 w-full items-center justify-center rounded-lg bg-zinc-900 text-sm font-medium text-white transition-colors hover:bg-zinc-700 disabled:opacity-60"
+        >
+          {pending ? "…" : mode === "login" ? "Sign in" : "Create account"}
+        </button>
+      </form>
+
+      <p className="text-center text-[13px] text-zinc-500">
+        {mode === "login" ? "First time here?" : "Already have an account?"}{" "}
+        <button
+          type="button"
+          onClick={() => {
+            setMode(mode === "login" ? "subscriber" : "login");
+            setError(null);
+          }}
+          className="font-medium text-zinc-900 underline underline-offset-2"
+        >
+          {mode === "login" ? "Create the owner account" : "Sign in"}
+        </button>
+      </p>
+    </div>
+  );
+}
+
+// Map the framework's auth error codes to friendly copy. `ApiError` carries a
+// stable `.code` 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 registered — sign in instead.";
+      case "WEAK_PASSWORD":
+        return "Pick a longer password — at least 10 characters.";
+      case "PWNED_PASSWORD":
+        return "That password has appeared in a known data breach. Choose a different one.";
+      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/creator/app/dashboard/dashboard-client.tsx

@@ -0,0 +1,297 @@
+"use client";
+
+import React, { useEffect, useMemo, useState } from "react";
+import { db, callFn } from "@pylonsync/react";
+import { useAuth } from "@pylonsync/client";
+import type { SubscriberStatsData, SubscriberStatsResult, SubscriberRow } from "@/lib/stats";
+
+// The owner's live dashboard. Liveness rides the SAME public aggregate the
+// landing page uses: `db.useQuery("SubscriberCount")` re-renders the instant the
+// count changes (cross-tab, via the replica). The emails themselves never sync
+// — they come from the owner-gated `subscriberStats` function, (re)fetched on
+// mount and whenever the live count ticks. So the total, chart, and list all
+// stay live, but PII only ever travels through the gated call.
+export function SubscriberDashboard({ userEmail }: { userEmail: string }) {
+  const { data: statRows } = db.useQuery<{ id: string; count: number }>("SubscriberCount");
+  const liveCount = statRows.length > 0 ? statRows[0].count : 0;
+
+  const [data, setData] = useState<SubscriberStatsData | null>(null);
+  const [denied, setDenied] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    callFn<SubscriberStatsResult>("subscriberStats", {})
+      .then((r) => {
+        if (cancelled) return;
+        // The owner gate (PYLON_OWNER_EMAIL) lives in the function; a non-owner
+        // comes back as `{ authorized: false }` (with no data) → locked card.
+        if (!r.authorized) {
+          setDenied(true);
+        } else {
+          setData(r);
+          setError(null);
+          setDenied(false);
+        }
+      })
+      .catch((e) => {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      cancelled = true;
+    };
+    // Re-fetch whenever a new subscriber moves the live count.
+  }, [liveCount]);
+
+  if (denied) return <OwnerOnly email={userEmail} />;
+  if (error) {
+    return (
+      <div className="rounded-xl border border-red-200 bg-red-50 px-5 py-4 text-sm text-red-700">
+        {error}
+      </div>
+    );
+  }
+  if (!data) return <Skeleton />;
+
+  return (
+    <div className="space-y-8">
+      <div>
+        <h1 className="text-xl font-semibold tracking-tight">Subscribers</h1>
+        <p className="mt-1 text-sm text-zinc-500">
+          Live — new subscribers appear here the moment they sign up.
+        </p>
+      </div>
+
+      <div className="grid gap-4 sm:grid-cols-3">
+        <Stat label="Total subscribers" value={data.total} />
+        <Stat label="Last 7 days" value={data.last7} />
+        <Stat label="Today" value={data.today} />
+      </div>
+
+      <TrendChart daily={data.daily} />
+
+      <SubscriberTable subscribers={data.subscribers} />
+    </div>
+  );
+}
+
+function Stat({ label, value }: { label: string; value: number }) {
+  return (
+    <div className="rounded-xl border border-zinc-200 bg-white p-4">
+      <div className="text-[11px] font-medium uppercase tracking-wide text-zinc-400">
+        {label}
+      </div>
+      <div className="mt-1 text-2xl font-semibold tabular-nums text-zinc-900">
+        {value.toLocaleString()}
+      </div>
+    </div>
+  );
+}
+
+/* ----------------------------- trend chart ---------------------------- */
+
+function TrendChart({ daily }: { daily: { date: string; count: number }[] }) {
+  const max = Math.max(1, ...daily.map((d) => d.count));
+  return (
+    <div className="rounded-xl border border-zinc-200 bg-white p-5">
+      <div className="flex items-center justify-between">
+        <h2 className="text-sm font-semibold text-zinc-900">Last 30 days</h2>
+        <span className="text-[12px] text-zinc-400">
+          peak {max.toLocaleString()}/day
+        </span>
+      </div>
+      {/* Each column is a FULL-HEIGHT flex cell (h-full) that bottom-aligns its
+          bar — so the bar's percentage height resolves against the 7rem track,
+          not an auto-height parent (which would collapse it to nothing). */}
+      <div className="mt-4 flex h-28 items-end gap-1">
+        {daily.map((d) => (
+          <div
+            key={d.date}
+            className="group relative flex h-full flex-1 flex-col justify-end"
+          >
+            <div
+              className="w-full rounded-t bg-brand/80 transition-colors group-hover:bg-brand"
+              style={{ height: `${Math.max(2, (d.count / max) * 100)}%` }}
+            />
+            {/* Tooltip on hover — date + count. */}
+            <div className="pointer-events-none absolute bottom-full left-1/2 z-10 mb-1 hidden -translate-x-1/2 whitespace-nowrap rounded bg-zinc-900 px-2 py-1 text-[11px] text-white group-hover:block">
+              {fmtDay(d.date)} · {d.count}
+            </div>
+          </div>
+        ))}
+      </div>
+      <div className="mt-2 flex justify-between text-[11px] text-zinc-400">
+        <span>{fmtDay(daily[0]?.date)}</span>
+        <span>{fmtDay(daily[daily.length - 1]?.date)}</span>
+      </div>
+    </div>
+  );
+}
+
+/* ----------------------------- subscriber list ---------------------------- */
+
+function SubscriberTable({ subscribers }: { subscribers: SubscriberRow[] }) {
+  const [q, setQ] = useState("");
+  const filtered = useMemo(() => {
+    const needle = q.trim().toLowerCase();
+    if (!needle) return subscribers;
+    return subscribers.filter((s) => s.email.toLowerCase().includes(needle));
+  }, [q, subscribers]);
+
+  return (
+    <div className="rounded-xl border border-zinc-200 bg-white">
+      <div className="flex flex-col gap-3 border-b border-zinc-100 p-4 sm:flex-row sm:items-center sm:justify-between">
+        <h2 className="text-sm font-semibold text-zinc-900">
+          Subscribers{" "}
+          <span className="font-normal text-zinc-400">
+            ({filtered.length.toLocaleString()})
+          </span>
+        </h2>
+        <div className="flex items-center gap-2">
+          <input
+            value={q}
+            onChange={(e) => setQ(e.target.value)}
+            placeholder="Search email…"
+            aria-label="Search subscribers"
+            className="h-9 w-44 rounded-md border border-zinc-300 bg-white px-3 text-sm outline-none transition placeholder:text-zinc-400 focus:border-brand focus:ring-2 focus:ring-brand/20"
+          />
+          <button
+            type="button"
+            onClick={() => exportCsv(subscribers)}
+            disabled={subscribers.length === 0}
+            className="inline-flex h-9 items-center rounded-md border border-zinc-300 px-3 text-[13px] font-medium text-zinc-700 transition-colors hover:bg-zinc-50 disabled:opacity-40"
+          >
+            Export CSV
+          </button>
+        </div>
+      </div>
+
+      {filtered.length === 0 ? (
+        <p className="p-8 text-center text-sm text-zinc-500">
+          {subscribers.length === 0
+            ? "No subscribers yet. Share your landing page and watch them roll in — live."
+            : "No emails match your search."}
+        </p>
+      ) : (
+        <ul className="divide-y divide-zinc-100">
+          {filtered.map((s) => (
+            <li key={s.id} className="flex items-center justify-between gap-3 px-4 py-2.5">
+              <span className="truncate text-sm text-zinc-800">{s.email}</span>
+              <span className="shrink-0 text-[12px] text-zinc-400">
+                {fmtDateTime(s.createdAt)}
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+/* --------------------------- owner-only gate -------------------------- */
+
+// Shown to a signed-in user the `subscriberStats` function refused (not the
+// configured owner, or no PYLON_OWNER_EMAIL set). Fails closed — no subscriber data
+// is fetched or shown.
+function OwnerOnly({ email }: { email: string }) {
+  return (
+    <div className="rounded-xl border border-dashed border-zinc-300 px-6 py-12 text-center">
+      <h1 className="text-lg font-semibold">This dashboard is owner-only</h1>
+      <p className="mx-auto mt-2 max-w-md text-sm text-zinc-500">
+        You&apos;re signed in as{" "}
+        <span className="font-medium text-zinc-700">{email || "this account"}</span>.
+        A newsletter is single-tenant — only the owner can see the subscribers. Set{" "}
+        <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[12px]">
+          PYLON_OWNER_EMAIL={email || "you@yourbusiness.com"}
+        </code>{" "}
+        in your{" "}
+        <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[12px]">.env</code>,
+        restart, and reload — or sign in with the owner account.
+      </p>
+    </div>
+  );
+}
+
+/* ----------------------------- user menu ------------------------------ */
+
+export function UserMenu({ email }: { email: string }) {
+  const { signOut } = useAuth();
+  const initial = (email.trim()[0] || "?").toUpperCase();
+  async function onSignOut() {
+    await signOut();
+    window.location.assign("/");
+  }
+  return (
+    <details className="group relative">
+      <summary className="flex size-8 cursor-pointer select-none list-none items-center justify-center rounded-full bg-zinc-900 text-[12px] font-semibold text-white marker:hidden [&::-webkit-details-marker]:hidden">
+        {initial}
+      </summary>
+      <div className="absolute right-0 top-full z-40 mt-2 w-56 overflow-hidden rounded-xl border border-zinc-200 bg-white py-1 shadow-[0_16px_48px_-16px_rgba(0,0,0,0.25)]">
+        <div className="border-b border-zinc-100 px-3 py-2">
+          <div className="truncate text-[13px] font-medium text-zinc-900">
+            {email || "Signed in"}
+          </div>
+        </div>
+        <button
+          type="button"
+          onClick={onSignOut}
+          className="flex w-full items-center px-3 py-2 text-left text-[13px] text-zinc-700 transition-colors hover:bg-zinc-50"
+        >
+          Sign out
+        </button>
+      </div>
+    </details>
+  );
+}
+
+/* ------------------------------ helpers ------------------------------- */
+
+function Skeleton() {
+  return (
+    <div className="space-y-8">
+      <div className="h-6 w-32 animate-pulse rounded bg-zinc-100" />
+      <div className="grid gap-4 sm:grid-cols-3">
+        {[0, 1, 2].map((i) => (
+          <div key={i} className="h-20 animate-pulse rounded-xl bg-zinc-100" />
+        ))}
+      </div>
+      <div className="h-44 animate-pulse rounded-xl bg-zinc-100" />
+      <div className="h-64 animate-pulse rounded-xl bg-zinc-100" />
+    </div>
+  );
+}
+
+function exportCsv(subscribers: SubscriberRow[]) {
+  const cell = (v: string) =>
+    /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+  const rows = [
+    "email,joined_at",
+    ...subscribers.map((s) => `${cell(s.email)},${cell(s.createdAt)}`),
+  ];
+  const blob = new Blob([rows.join("\n")], { type: "text/csv;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = `newsletter-${new Date().toISOString().slice(0, 10)}.csv`;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+}
+
+function fmtDay(iso?: string) {
+  if (!iso) return "";
+  const d = new Date(iso + "T00:00:00Z");
+  return d.toLocaleDateString(undefined, { month: "short", day: "numeric" });
+}
+
+function fmtDateTime(iso: string) {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return "";
+  return new Date(t).toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+}

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

@@ -0,0 +1,70 @@
+import React, { use } from "react";
+import { Link, type Metadata, type PageProps } from "@pylonsync/react";
+import { siteConfig } from "@/lib/site.config";
+import { UserMenu, SubscriberDashboard } from "./dashboard-client";
+
+export const metadata: Metadata = {
+  title: `Dashboard — ${siteConfig.brand.name}`,
+  robots: "noindex",
+};
+
+// `app/dashboard/page.tsx` → `/dashboard`. Server-side auth gate only — any
+// signed-in user can load the shell. The OWNER gate (a newsletter is
+// single-tenant: only PYLON_OWNER_EMAIL may see the subscribers) lives in the
+// `subscriberStats` function, which checks `ctx.env.PYLON_OWNER_EMAIL` — the
+// authoritative server env. Non-owners get a clean "owner-only" card from the
+// client when that call is denied. (Env-based config is read in the function,
+// not here: an SSR page render can't reliably read arbitrary `process.env`.)
+export default function DashboardPage({ auth, response, serverData }: PageProps) {
+  // Anonymous visitors and guest sessions (guest_… ids) get bounced to login —
+  // the dashboard is for the real, signed-in owner only.
+  if (!auth.user_id || auth.user_id.startsWith("guest_")) {
+    response.redirect("/login");
+    return null;
+  }
+
+  // The User self-read policy lets the signed-in user read their own row → the
+  // email shown in the account menu (and on the owner-only card).
+  const me = use(serverData.get<{ email?: string }>("User", auth.user_id));
+  const email = me?.email ?? "";
+
+  return (
+    <Shell email={email}>
+      <SubscriberDashboard userEmail={email} />
+    </Shell>
+  );
+}
+
+// Dashboard chrome: a slim top bar with the logo, a link back to the public
+// site, and the account menu (a client island for sign-out).
+function Shell({ email, children }: { email: string; children: React.ReactNode }) {
+  const { brand } = siteConfig;
+  return (
+    <div className="flex min-h-screen flex-col bg-white text-zinc-900">
+      <header className="border-b border-zinc-200">
+        <div className="mx-auto flex h-14 max-w-4xl items-center justify-between px-6">
+          <div className="flex items-center gap-2">
+            <span className="flex size-6 items-center justify-center rounded-[7px] bg-zinc-900 text-[13px] font-bold text-white">
+              {brand.letter}
+            </span>
+            <span className="text-[15px] font-semibold tracking-tight">
+              {brand.name} <span className="text-zinc-400">/ newsletter</span>
+            </span>
+          </div>
+          <div className="flex items-center gap-4">
+            <Link
+              href="/"
+              className="text-[13px] text-zinc-500 transition-colors hover:text-zinc-900"
+            >
+              View site ↗
+            </Link>
+            <UserMenu email={email} />
+          </div>
+        </div>
+      </header>
+      <main className="flex-1">
+        <div className="mx-auto max-w-4xl px-6 py-8">{children}</div>
+      </main>
+    </div>
+  );
+}

package/templates/creator/app/error.tsx

@@ -0,0 +1,26 @@
+import React from "react";
+import { type ErrorBoundaryProps } from "@pylonsync/react";
+
+// `app/error.tsx` → the error boundary for this segment. Hydrated + interactive:
+// `reset()` re-attempts the route. The thrown error reaches the client as
+// `{ message, digest }` only — the stack stays in the dev overlay / server logs.
+export default function Error({ error, reset }: ErrorBoundaryProps) {
+  return (
+    <div className="mx-auto flex min-h-[60vh] max-w-3xl flex-col items-center justify-center px-6 text-center">
+      <h1 className="text-2xl font-semibold tracking-tight">Something went wrong</h1>
+      <p className="mt-2 text-zinc-500">{error.message}</p>
+      {error.digest ? (
+        <p className="mt-1 text-xs text-zinc-400">
+          Reference: <code>{error.digest}</code>
+        </p>
+      ) : null}
+      <button
+        type="button"
+        onClick={reset}
+        className="mt-6 inline-flex h-10 items-center rounded-full bg-zinc-900 px-5 text-sm font-medium text-white transition-colors hover:bg-zinc-700"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}