docs: change layout

Author: WhyAsh5114

.github/copilot-instructions.md

@@ -7,7 +7,7 @@ You are working on a Prisma generator that creates a familiar, type-safe client
 - **Generator-Centric**: Most core logic resides in `packages/generator`. If you need to change client behavior, edit the generator's `fileCreators`.
 - **Sync Flow**: Uses an **Outbox Pattern** on the client and a **Changelog Materialization** on the server.
 - **Ownership Invariants**: Syncability is gated by an ownership DAG. Every syncable record must be traceable to a `rootModel` (e.g., `User`) via `@db.map("ownerId")` or similar ownership fields. Refer to `todo.md` for the 4 core invariants.
-- **Client-Side IDs**: All syncable models **must** use client-generated IDs (`uuid`, `cuid2`). Auto-incrementing IDs are strictly forbidden for syncable data.
+- **Client-Side IDs**: All syncable models **must** use client-generated IDs (`uuid`, `cuid`). Auto-incrementing IDs are strictly forbidden for syncable data.
 
 ## Critical Workflows
 

apps/docs/content/docs/index.mdx apps/docs/content/docs/(index)/index.mdxapps/docs/content/docs/index.mdx renamed to apps/docs/content/docs/(index)/index.mdx

@@ -1,6 +1,7 @@
 {
   "title": "Basics",
-  "icon": "HouseIcon",
-  "pages": ["---Home---", "index", "why-prisma-idb", "quick-start", "---Sync---", "...(sync)"],
+  "description": "Get started with the Prisma IDB client",
+  "icon": "Pyramid",
+  "pages": ["---Home---", "index", "why-prisma-idb", "quick-start"],
   "root": true
 }

apps/docs/content/docs/meta.json apps/docs/content/docs/(index)/meta.jsonapps/docs/content/docs/meta.json renamed to apps/docs/content/docs/(index)/meta.json

@@ -41,15 +41,15 @@ generator prismaIDB {
 
 ```prisma
 model User {
-  id    String  @id @default(cuid2())  // Client-generated IDs required for sync
+  id    String  @id @default(cuid())  // Client-generated IDs required for sync
   name  String
   email String  @unique
   
   todos Todo[]
 }
 
 model Todo {
-  id    String  @id @default(cuid2())
+  id    String  @id @default(cuid())
   title String
   done  Boolean @default(false)
   
@@ -99,7 +99,7 @@ await client.todo.delete({
 
 <Cards>
   <Card title="API Reference" href="/docs/api" />
-  <Card title="Sync Engine" href="/docs/sync-engine" />
+  <Card title="Sync Engine" href="/docs/sync" />
   <Card title="Ownership & Auth" href="/docs/ownership" />
   <Card title="Examples" href="/docs/examples" />
 </Cards>

apps/docs/content/docs/quick-start.mdx …ocs/content/docs/(index)/quick-start.mdxapps/docs/content/docs/quick-start.mdx renamed to apps/docs/content/docs/(index)/quick-start.mdx apps/docs/content/docs/quick-start.mdx renamed to apps/docs/content/docs/(index)/quick-start.mdx

@@ -0,0 +1,3 @@
+{
+  "pages": ["step-1-generator-config", "step-2-changelog-schema", "step-3-push-endpoint", "step-4-pull-endpoint", "step-5-sync-worker"]
+}

apps/docs/content/docs/why-prisma-idb.mdx …/content/docs/(index)/why-prisma-idb.mdxapps/docs/content/docs/why-prisma-idb.mdx renamed to apps/docs/content/docs/(index)/why-prisma-idb.mdx apps/docs/content/docs/why-prisma-idb.mdx renamed to apps/docs/content/docs/(index)/why-prisma-idb.mdx

@@ -0,0 +1,90 @@
+---
+title: "Step 1: Generator Config"
+description: "Configure the Prisma IDB generator for sync"
+icon: Settings
+---
+
+## Step 1: Configure the Generator
+
+Before implementing sync, you need to configure the Prisma IDB generator in your `schema.prisma` file. This tells the generator which models to sync and how to scope the data.
+
+### Configuration Options
+
+Add the generator block to your `prisma/schema.prisma`:
+
+```prisma
+generator prismaIDB {
+  provider = "idb-client-generator"
+  output   = "./prisma-idb"
+  
+  // Enable sync capabilities
+  outboxSync = true
+  
+  // Anchor model for the ownership DAG
+  rootModel  = "User"
+  
+  // Models to exclude from sync (optional)
+  exclude    = ["Session", "Verification", "Account", "ChangeLog"]
+}
+```
+
+### Required Settings
+
+- **`outboxSync = true`**: Enables the bidirectional sync engine. Without this, the generated client will be read-only.
+- **`rootModel`**: The primary entity that acts as the anchor for all other models. This must be a model in your schema that represents the data owner (typically `User`).
+
+### Optional Settings
+
+- **`exclude`**: Array of model names to skip during client generation. Use this for:
+  - Authentication models (`Session`, `Account`, `Verification`)
+  - Changelog models (excluded automatically, but good practice to list explicitly)
+  - Server-only models that shouldn't be synced to clients
+  - Large or temporary tables
+
+### Scoping Rules
+
+The `rootModel` and `exclude` settings work together to define which data gets synced:
+
+- Only the `rootModel` and its descendants (models that reference it, directly or indirectly) are synced
+- Excluded models are never generated in the client
+- The generated client only syncs data relevant to the current user (scoped by `rootModel`)
+
+### Example: Multi-User Blog
+
+```prisma
+model User {
+  id    String @id @default(cuid())
+  email String @unique
+  posts Post[]
+}
+
+model Post {
+  id     String @id @default(cuid())
+  title  String
+  userId String
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+}
+
+generator prismaIDB {
+  provider   = "idb-client-generator"
+  output     = "./prisma-idb"
+  outboxSync = true
+  rootModel  = "User"
+  exclude    = ["ChangeLog", "AuditLog"]
+}
+```
+
+In this setup:
+- `User` is the root model
+- `Post` syncs because it references `User`
+- `AuditLog` is excluded and won't appear in the client
+
+### Next Steps
+
+After configuring the generator, you need to:
+1. Add the `ChangeLog` table to your schema
+2. Implement the push endpoint
+3. Implement the pull endpoint
+4. Initialize the sync worker on the client
+
+Continue to [Step 2: Changelog Schema](./step-2-changelog-schema).

apps/docs/content/docs/(sync)/meta.json

@@ -0,0 +1,81 @@
+---
+title: "Step 2: Changelog Schema"
+description: "Add the Changelog table to your Prisma schema"
+icon: Database
+---
+
+## Step 2: Create the Changelog Table
+
+The changelog table is essential for the sync engine. It tracks all changes made on the server so they can be materialized to clients during pull operations.
+
+### Required Schema
+
+Add the following to your `prisma/schema.prisma`:
+
+```prisma
+model ChangeLog {
+  id            String          @id @default(uuid(7))
+  model         String
+  keyPath       Json
+  operation     ChangeOperation
+  scopeKey      String
+  outboxEventId String          @unique
+
+  @@index([model, id])
+}
+
+enum ChangeOperation {
+  create
+  update
+  delete
+}
+```
+
+### Field Explanations
+
+- **`id`**: Unique identifier using `uuid(7)` for sortable timestamps
+- **`model`**: The name of the model that was modified (e.g., "Post", "Comment")
+- **`keyPath`**: JSON representation of the primary key(s) of the affected record
+- **`operation`**: The type of change—`create`, `update`, or `delete`
+- **`scopeKey`**: The owner identifier (e.g., `userId`) to scope changes per user
+- **`outboxEventId`**: Links to the client's outbox event that triggered this change
+
+### Important Requirements
+
+#### Database-Level Index
+
+The `@@index([model, id])` is crucial for performance:
+- The pull endpoint queries changelogs in order: `WHERE model IN (...) AND id > lastChangelogId`
+- Without this index, pulls on large tables will be slow
+- Make sure to run migrations after adding this table
+
+#### UUID v7 for Natural Ordering
+
+Using `uuid(7)` ensures:
+- Changelog entries are naturally ordered by creation time
+- Cursoring through changes is efficient (no need to sort by timestamp)
+- Clients can request changes since a specific point in time
+
+#### No Manual Deletes
+
+Never manually delete from the `ChangeLog` table. It's the source of truth for what changed on the server.
+
+### Migration
+
+After adding the schema, create a migration:
+
+```bash
+pnpm exec prisma migrate dev --name add_changelog
+```
+
+This will:
+1. Create the `ChangeLog` table in your database
+2. Update your `schema.prisma`
+
+### Next Steps
+
+With the changelog table in place, you can now implement the endpoints that use it:
+1. Push endpoint to accept client mutations
+2. Pull endpoint to send server changes to clients
+
+Continue to [Step 3: Push Endpoint](./step-3-push-endpoint).

apps/docs/content/docs/sync/(implementation)/meta.json

@@ -0,0 +1,134 @@
+---
+title: "Step 3: Push Endpoint"
+description: "Implement the endpoint that accepts and applies client mutations"
+icon: Upload
+---
+
+## Step 3: Create the Push Endpoint
+
+The push endpoint receives mutations from the client (stored in the outbox) and applies them to the server database. The sync worker will automatically send outbox events to this endpoint.
+
+### Endpoint Setup
+
+Create a new API route in your framework (e.g., `routes/api/sync/push/+server.ts` for SvelteKit):
+
+```typescript
+import { applyPush } from "$lib/prisma-idb/server/batch-processor";
+import { outboxEventSchema } from "$lib/prisma-idb/validators";
+import { auth } from "$lib/server/auth";
+import { prisma } from "$lib/server/prisma";
+import z from "zod";
+
+export async function POST({ request }) {
+  // Parse and validate request body
+  let pushRequestBody;
+  try {
+    pushRequestBody = await request.json();
+  } catch {
+    return new Response(JSON.stringify({ error: "Malformed JSON" }), { status: 400 });
+  }
+
+  const parsed = z.object({ events: z.array(outboxEventSchema) }).safeParse({
+    events: pushRequestBody.events,
+  });
+
+  if (!parsed.success) {
+    return new Response(JSON.stringify({ error: "Invalid request", details: parsed.error }), {
+      status: 400,
+    });
+  }
+
+  // Authenticate the request
+  const authResult = await auth.api.getSession({ headers: request.headers });
+  if (!authResult?.user.id) {
+    return new Response(JSON.stringify({ error: "Unauthorized" }), { status: 401 });
+  }
+
+  // Apply the mutations
+  let pushResults;
+  try {
+    pushResults = await applyPush({
+      events: parsed.data.events,
+      scopeKey: authResult.user.id,
+      prisma,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    const status = message.startsWith("Batch size") ? 413 : 500;
+    return new Response(JSON.stringify({ error: message }), {
+      status,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  return new Response(JSON.stringify(pushResults), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+```
+
+### How It Works
+
+1. **Validate Input**: Parse the request as an array of `OutboxEvent` objects
+2. **Authenticate**: Get the user ID from the session/auth context
+3. **Apply Mutations**: Call `applyPush()` with the events
+4. **Return Results**: Each event gets a `PushResult` indicating success or failure
+
+### Key Parameters
+
+#### `applyPush()` Options
+
+- **`events`**: Array of outbox mutations from the client
+- **`scopeKey`**: User ID or function that extracts the owner from each event. This ensures users can only modify their own data.
+- **`prisma`**: Prisma Client instance to access your database
+- **`customValidation`** (optional): Add business logic validation before applying changes
+
+### Error Handling
+
+The endpoint catches two main error types:
+
+- **Batch Size Exceeded** (413): Client sent more than 100 events in one request. The client's sync worker automatically batches events, but this prevents denial-of-service attacks.
+- **Other Errors** (500): Database errors or validation failures. The `PushResult` for each event indicates which ones succeeded and which ones failed (with details for retries).
+
+### Custom Validation (Optional)
+
+For advanced use cases, add custom business logic:
+
+```typescript
+pushResults = await applyPush({
+  events: parsed.data.events,
+  scopeKey: authResult.user.id,
+  prisma,
+  customValidation: async (event) => {
+    // Example: Reject if user isn't a board admin
+    if (event.entityType === "Task") {
+      const board = await prisma.board.findUnique({
+        where: { id: event.payload.boardId },
+        include: { admins: { where: { id: authResult.user.id } } },
+      });
+      if (!board?.admins.length) {
+        return { errorMessage: "Only board admins can create tasks" };
+      }
+    }
+    return { errorMessage: null };
+  },
+});
+```
+
+### Scope Key Enforcement
+
+The `scopeKey` ensures data isolation:
+- For a single-user app: `scopeKey: authResult.user.id`
+- For a multi-tenant app: `scopeKey: (event) => event.payload.tenantId` or similar
+
+The `applyPush` function will:
+1. Validate that the event's ownership chain traces back to the scope key
+2. Reject any mutations that attempt to change a different user's data
+3. Create changelog entries with the correct `scopeKey` for pull operations
+
+### Next Steps
+
+Once the push endpoint is working, implement the complementary pull endpoint to send server changes back to clients.
+
+Continue to [Step 4: Pull Endpoint](./step-4-pull-endpoint).