npm - @pylonsync/create-pylon - Versions diffs - 0.3.266 → 0.3.268 - Mend

@pylonsync/create-pylon 0.3.266 → 0.3.268

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (102) hide show

package/bin/create-pylon.js +77 -14
package/package.json +1 -1
package/templates/b2b/AGENTS.md +61 -0
package/templates/b2b/README.md +62 -0
package/templates/b2b/app/auth-form.tsx +142 -0
package/templates/b2b/app/dashboard/dashboard-client.tsx +192 -0
package/templates/b2b/app/dashboard/page.tsx +63 -0
package/templates/b2b/app/error.tsx +43 -0
package/templates/b2b/app/globals.css +139 -0
package/templates/b2b/app/layout.tsx +71 -0
package/templates/b2b/app/login/page.tsx +47 -0
package/templates/b2b/app/not-found.tsx +29 -0
package/templates/b2b/app/page.tsx +114 -0
package/templates/b2b/app/robots.ts +12 -0
package/templates/b2b/app/signup/page.tsx +44 -0
package/templates/b2b/app/sitemap.ts +27 -0
package/templates/b2b/app.ts +179 -0
package/templates/b2b/components/ui/button.tsx +56 -0
package/templates/b2b/components/ui/card.tsx +90 -0
package/templates/b2b/components.json +20 -0
package/templates/b2b/functions/_keep.ts +13 -0
package/templates/b2b/gitignore +10 -0
package/templates/b2b/lib/utils.ts +10 -0
package/templates/b2b/package.json +33 -0
package/templates/b2b/tsconfig.json +18 -0
package/templates/barebones/AGENTS.md +61 -0
package/templates/barebones/README.md +45 -0
package/templates/barebones/app/error.tsx +43 -0
package/templates/barebones/app/globals.css +139 -0
package/templates/barebones/app/items-client.tsx +96 -0
package/templates/barebones/app/layout.tsx +27 -0
package/templates/barebones/app/not-found.tsx +29 -0
package/templates/barebones/app/page.tsx +28 -0
package/templates/barebones/app/robots.ts +12 -0
package/templates/barebones/app/sitemap.ts +27 -0
package/templates/barebones/app.ts +55 -0
package/templates/barebones/components/ui/button.tsx +56 -0
package/templates/barebones/components/ui/card.tsx +90 -0
package/templates/barebones/components.json +20 -0
package/templates/barebones/functions/_keep.ts +13 -0
package/templates/barebones/gitignore +10 -0
package/templates/barebones/lib/utils.ts +10 -0
package/templates/barebones/package.json +33 -0
package/templates/barebones/tsconfig.json +18 -0
package/templates/chat/AGENTS.md +61 -0
package/templates/chat/README.md +51 -0
package/templates/chat/app/chat-client.tsx +113 -0
package/templates/chat/app/error.tsx +43 -0
package/templates/chat/app/globals.css +139 -0
package/templates/chat/app/layout.tsx +25 -0
package/templates/chat/app/not-found.tsx +29 -0
package/templates/chat/app/page.tsx +26 -0
package/templates/chat/app/robots.ts +12 -0
package/templates/chat/app/sitemap.ts +27 -0
package/templates/chat/app.ts +59 -0
package/templates/chat/components/ui/button.tsx +56 -0
package/templates/chat/components/ui/card.tsx +90 -0
package/templates/chat/components.json +20 -0
package/templates/chat/functions/_keep.ts +13 -0
package/templates/chat/gitignore +10 -0
package/templates/chat/lib/utils.ts +10 -0
package/templates/chat/package.json +33 -0
package/templates/chat/tsconfig.json +18 -0
package/templates/consumer/AGENTS.md +61 -0
package/templates/consumer/README.md +52 -0
package/templates/consumer/app/error.tsx +43 -0
package/templates/consumer/app/feed-client.tsx +154 -0
package/templates/consumer/app/globals.css +139 -0
package/templates/consumer/app/layout.tsx +27 -0
package/templates/consumer/app/not-found.tsx +29 -0
package/templates/consumer/app/page.tsx +27 -0
package/templates/consumer/app/robots.ts +12 -0
package/templates/consumer/app/sitemap.ts +27 -0
package/templates/consumer/app.ts +89 -0
package/templates/consumer/components/ui/button.tsx +56 -0
package/templates/consumer/components/ui/card.tsx +90 -0
package/templates/consumer/components.json +20 -0
package/templates/consumer/functions/_keep.ts +13 -0
package/templates/consumer/gitignore +10 -0
package/templates/consumer/lib/utils.ts +10 -0
package/templates/consumer/package.json +33 -0
package/templates/consumer/tsconfig.json +18 -0
package/templates/ssr/app.ts +3 -0
package/templates/todo/AGENTS.md +61 -0
package/templates/todo/README.md +59 -0
package/templates/todo/app/error.tsx +43 -0
package/templates/todo/app/globals.css +139 -0
package/templates/todo/app/layout.tsx +31 -0
package/templates/todo/app/not-found.tsx +29 -0
package/templates/todo/app/page.tsx +37 -0
package/templates/todo/app/robots.ts +12 -0
package/templates/todo/app/sitemap.ts +27 -0
package/templates/todo/app/todo-app.tsx +133 -0
package/templates/todo/app.ts +72 -0
package/templates/todo/components/ui/button.tsx +56 -0
package/templates/todo/components/ui/card.tsx +90 -0
package/templates/todo/components.json +20 -0
package/templates/todo/functions/_keep.ts +13 -0
package/templates/todo/gitignore +10 -0
package/templates/todo/lib/utils.ts +10 -0
package/templates/todo/package.json +33 -0
package/templates/todo/tsconfig.json +18 -0

package/templates/consumer/app/layout.tsx ADDED Viewed

@@ -0,0 +1,27 @@
+import React from "react";
+interface LayoutProps {
+  children: React.ReactNode;
+}
+// The root layout wraps every page: a header and a centered column. The page
+// renders server-side first, then the feed hydrates into a live view.
+export default function RootLayout({ children }: LayoutProps) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>__APP_NAME__</title>
+      </head>
+      <body className="min-h-screen bg-background text-foreground antialiased">
+        <header className="sticky top-0 z-10 border-b bg-background/80 backdrop-blur">
+          <div className="mx-auto max-w-lg px-4 py-3 text-sm font-semibold tracking-tight">
+            __APP_NAME__
+          </div>
+        </header>
+        <main className="mx-auto max-w-lg px-4 py-8">{children}</main>
+      </body>
+    </html>
+  );
+}

package/templates/consumer/app/not-found.tsx ADDED Viewed

@@ -0,0 +1,29 @@
+import React from "react";
+import { Link, useRouter, type NotFoundProps } from "@pylonsync/react";
+import { Button } from "@/components/ui/button";
+// `app/not-found.tsx` → rendered at HTTP 404 for any unmatched URL (and when
+// a page calls `response.notFound()`). It's HYDRATED, so it's interactive:
+// the buttons below use the client router. Not-found boundaries receive the
+// standard page props (and, matching Next, no `reset`).
+export default function NotFound(_props: NotFoundProps) {
+  const router = useRouter();
+  return (
+    <div className="space-y-6">
+      <section>
+        <h1 className="text-2xl font-semibold tracking-tight">404</h1>
+        <p className="mt-2 text-muted-foreground">
+          We couldn&apos;t find that page.
+        </p>
+      </section>
+      <div className="flex items-center gap-3">
+        <Button onClick={() => router.back()} variant="outline">
+          ← Go back
+        </Button>
+        <Button asChild>
+          <Link href="/">Home</Link>
+        </Button>
+      </div>
+    </div>
+  );
+}

package/templates/consumer/app/page.tsx ADDED Viewed

@@ -0,0 +1,27 @@
+import React from "react";
+import { type Metadata } from "@pylonsync/react";
+import { Feed } from "./feed-client";
+export const metadata: Metadata = {
+  title: "__APP_NAME__ — a live social feed on Pylon",
+  description:
+    "A public feed with optimistic posts and likes, server-rendered over one Pylon backend. One binary, one port. Open two tabs and watch it sync.",
+};
+// `app/page.tsx` → `/`. The intro is server-rendered; `<Feed>` is a client
+// island that mints a guest session and runs the live query + optimistic
+// posts/likes in the browser.
+export default function IndexPage() {
+  return (
+    <div>
+      <header className="mb-6">
+        <h1 className="text-2xl font-semibold tracking-tight">Feed</h1>
+        <p className="mt-1 text-sm text-muted-foreground">
+          Post something — it appears instantly and syncs to every tab. Likes
+          are live too.
+        </p>
+      </header>
+      <Feed />
+    </div>
+  );
+}

package/templates/consumer/app/robots.ts ADDED Viewed

@@ -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/consumer/app/sitemap.ts ADDED Viewed

@@ -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/consumer/app.ts ADDED Viewed

@@ -0,0 +1,89 @@
+import {
+  entity,
+  field,
+  policy,
+  auth,
+  buildManifest,
+  discoverAppRoutes,
+} from "@pylonsync/sdk";
+// A post in the public feed. `authorId: field.owner()` stamps the signed-in
+// (guest) user's id server-side, so an optimistic `db.insert("Post", { text })`
+// can't forge authorship. The feed itself is public-read (everyone sees every
+// post) — that's intentional for a social feed, NOT the insecure wide-open
+// default; writes are still owner-only.
+const Post = entity(
+  "Post",
+  {
+    authorId: field.string().owner(),
+    text: field.string(),
+    createdAt: field.datetime().defaultNow(),
+  },
+  { indexes: [{ name: "by_created", fields: ["createdAt"], unique: false }] },
+);
+// A like is a join row (one per user per post). To toggle a like the client
+// inserts or deletes this row; the like count for a post is just how many
+// Like rows point at it. `userId: field.owner()` keeps a like attributable to
+// exactly one user.
+const Like = entity(
+  "Like",
+  {
+    userId: field.string().owner(),
+    postId: field.string(),
+    createdAt: field.datetime().defaultNow(),
+  },
+  {
+    indexes: [
+      { name: "by_post", fields: ["postId"], unique: false },
+      // One like per user per post — the unique index makes a double-like a
+      // no-op at the storage layer.
+      { name: "by_user_post", fields: ["userId", "postId"], unique: true },
+    ],
+  },
+);
+// Posts + likes are public-read so the feed and its counts render for
+// everyone; writes are gated to the owner. An entity with no policy is denied
+// to clients by default, so these allow-lists are what make the feed work.
+// `allowInsert` is `auth.userId != null`, not `== data.authorId`: the owner
+// field is stamped by field.owner() *after* the policy check, so it's null at
+// insert-time. The stamp still guarantees the new row is owned by the caller,
+// and read/update/delete enforce ownership on the persisted row.
+const postPolicy = policy({
+  name: "post_feed",
+  entity: "Post",
+  allowRead: "true",
+  allowInsert: "auth.userId != null",
+  allowUpdate: "auth.userId == data.authorId",
+  allowDelete: "auth.userId == data.authorId",
+});
+const likePolicy = policy({
+  name: "like_access",
+  entity: "Like",
+  allowRead: "true",
+  allowInsert: "auth.userId != null",
+  allowUpdate: "false",
+  allowDelete: "auth.userId == data.userId",
+});
+// `pylon dev` serves the SSR feed and the API from one port. Guest sessions
+// (via `<EnsureGuest>` on the page) let every visitor post + like with no
+// login. Natural next steps: a `Profile` entity (displayName/avatar keyed by
+// userId) to show names instead of ids, and a `Follow` join entity
+// (followerId/followedId) to scope the feed to people you follow.
+const manifest = buildManifest({
+  name: "__APP_NAME__",
+  version: "0.1.0",
+  entities: [Post, Like],
+  queries: [],
+  actions: [],
+  policies: [postPolicy, likePolicy],
+  auth: auth(),
+  routes: await discoverAppRoutes(),
+});
+console.log(JSON.stringify(manifest, null, 2));
+export default manifest;

package/templates/consumer/components/ui/button.tsx ADDED Viewed

@@ -0,0 +1,56 @@
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-white hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    );
+  },
+);
+Button.displayName = "Button";
+export { Button, buttonVariants };

package/templates/consumer/components/ui/card.tsx ADDED Viewed

@@ -0,0 +1,90 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+function Card({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card"
+      className={cn(
+        "rounded-xl border bg-card text-card-foreground shadow-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+function CardHeader({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn("flex flex-col space-y-1.5 p-6", className)}
+      {...props}
+    />
+  );
+}
+function CardTitle({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn("font-semibold leading-none tracking-tight", className)}
+      {...props}
+    />
+  );
+}
+function CardDescription({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+function CardContent({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("p-6 pt-0", className)}
+      {...props}
+    />
+  );
+}
+function CardFooter({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn("flex items-center p-6 pt-0", className)}
+      {...props}
+    />
+  );
+}
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardDescription,
+  CardContent,
+};

package/templates/consumer/components.json ADDED Viewed

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "zinc",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/templates/consumer/functions/_keep.ts ADDED Viewed

@@ -0,0 +1,13 @@
+// Server functions go here. Each file in this directory that exports a
+// query() or action() becomes a typed RPC endpoint, callable from your
+// pages and client with full type inference. Delete this placeholder when
+// you add your first one.
+//
+// Example (functions/notes.ts):
+//
+//   import { query } from "@pylonsync/functions";
+//
+//   export const listNotes = query(async (ctx) => {
+//     return ctx.db.list("Note");
+//   });
+export {};

package/templates/consumer/gitignore ADDED Viewed

@@ -0,0 +1,10 @@
+node_modules/
+.pylon/
+pylon.manifest.json
+pylon.client.ts
+web/dist/
+*.db
+*.db-*
+.env
+.env.local
+.DS_Store

package/templates/consumer/lib/utils.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+// `cn` — the shadcn class merger. clsx resolves conditional/array class
+// inputs; tailwind-merge then dedupes conflicting Tailwind utilities so
+// the last one wins (e.g. `cn("px-2", "px-4")` → "px-4"). Every shadcn
+// component routes its className through this.
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/consumer/package.json ADDED Viewed

@@ -0,0 +1,33 @@
+{
+  "name": "__APP_NAME_KEBAB__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pylon dev",
+    "deploy": "pylon deploy",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@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",
+    "@tailwindcss/cli": "^4.3.0",
+    "tw-animate-css": "^1.2.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.5.0",
+    "lucide-react": "^0.460.0",
+    "@radix-ui/react-slot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/consumer/tsconfig.json ADDED Viewed

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": ["ES2022", "DOM"],
+    "types": ["react", "react-dom"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["app.ts", "app/**/*", "components/**/*", "lib/**/*"]
+}

package/templates/ssr/app.ts CHANGED Viewed

@@ -18,6 +18,9 @@ const User = entity(
     email: field.string(),
     displayName: field.string().optional(),
     passwordHash: field.string().serverOnly().optional(),
+    // The framework's /api/auth/password/register stamps a generated avatar
+    // color here, so the User entity must declare it.
+    avatarColor: field.string().optional(),
     createdAt: field.datetime().defaultNow(),
   },
   { indexes: [{ name: "by_email", fields: ["email"], unique: true }] },

package/templates/todo/AGENTS.md ADDED Viewed

@@ -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/todo/README.md ADDED Viewed

@@ -0,0 +1,59 @@
+# __APP_NAME__
+A full-stack [Pylon](https://pylonsync.com) todo app — a server-rendered page
+and a live, optimistic, per-user todo list over a synced database, all served
+from one binary on one port. No Next.js, no separate API server.
+## Develop
+```bash
+__RUN_DEV__
+```
+Open http://localhost:4321. Add a todo — it appears instantly (optimistic) and
+syncs; open a second tab to watch writes arrive live. Edit any file under
+`app/` and save — the page reloads instantly.
+## Layout
+```
+app.ts              data model + manifest (entities, policies, auth, routes)
+app/page.tsx        "/" — the server-rendered page (heading + intro)
+app/todo-app.tsx    client island: guest session + live, optimistic todo list
+app/layout.tsx      root layout wrapping every page
+app/globals.css     Tailwind entrypoint (compiled by Pylon)
+functions/          server functions (query/action) — typed RPC, if you need them
+```
+## How it works
+No login wall: `app/todo-app.tsx` wraps the list in `<EnsureGuest>`, which
+POSTs `/api/auth/guest` on first load so every visitor implicitly becomes their
+own user. Todos are private per browser — the `todo_access` policy in `app.ts`
+gates every read and write to the owner, and `userId: field.owner()` stamps the
+session's id server-side so the optimistic `db.insert("Todo", { title })` can't
+be spoofed. `db.useQuery("Todo")` is a live subscription; `db.insert` /
+`db.update` / `db.delete` are optimistic.
+To require real accounts instead, enable email/password (built in, against a
+`User` entity) and swap `<EnsureGuest>` for `<SignedIn>` / `<SignedOut>` from
+`@pylonsync/client`.
+## Add a route
+Drop a file at `app/about/page.tsx` and visit `/about`. Pages receive
+`{ url, params, searchParams, auth, response, serverData }` from the SSR
+runtime — all typed via `PageProps` from `@pylonsync/react`.
+## Add data
+Edit `app.ts`. Every `entity()` becomes a synced table with a REST + realtime
+API and a typed client — no migrations, no resolvers.
+## Deploy
+```bash
+pylon deploy
+```
+Docs: https://docs.pylonsync.com

package/templates/todo/app/error.tsx ADDED Viewed

@@ -0,0 +1,43 @@
+import React from "react";
+import { type ErrorBoundaryProps } from "@pylonsync/react";
+import { Button } from "@/components/ui/button";
+// `app/error.tsx` → the error boundary for this segment. It catches a throw
+// in any page/layout below it and renders at HTTP 500. It's HYDRATED, so
+// this is a real interactive client component: `reset()` re-attempts the
+// route, and useState/onClick work. The thrown error reaches the client as
+// `{ message, digest }` only — the stack stays in the dev overlay
+// (PYLON_DEV_MODE) and the server logs, never in the page.
+export default function Error({ error, reset }: ErrorBoundaryProps) {
+  const [tries, setTries] = React.useState(0);
+  return (
+    <div className="space-y-6">
+      <section>
+        <h1 className="text-2xl font-semibold tracking-tight">
+          Something went wrong
+        </h1>
+        <p className="mt-2 text-muted-foreground">{error.message}</p>
+        {error.digest ? (
+          <p className="mt-1 text-xs text-muted-foreground/70">
+            Reference: <code>{error.digest}</code>
+          </p>
+        ) : null}
+      </section>
+      <div className="flex items-center gap-3">
+        <Button
+          onClick={() => {
+            setTries((n) => n + 1);
+            reset();
+          }}
+        >
+          Try again
+        </Button>
+        {tries > 0 ? (
+          <span className="text-sm text-muted-foreground">
+            Retried {tries} {tries === 1 ? "time" : "times"}
+          </span>
+        ) : null}
+      </div>
+    </div>
+  );
+}