@agent-native/core 0.4.1 → 0.4.2

package/dist/vite/dev-api-server.js

@@ -0,0 +1,148 @@
+import path from "path";
+import fs from "fs";
+import { createApp, createRouter, toNodeListener } from "h3";
+/**
+ * Map a Nitro-style route file path to { method, route }.
+ *
+ * Examples:
+ *   api/emails/index.get.ts      → GET  /api/emails
+ *   api/emails/[id].get.ts       → GET  /api/emails/:id
+ *   api/emails/[id]/star.patch.ts→ PATCH /api/emails/:id/star
+ *   api/events.get.ts            → GET  /api/events
+ */
+function parseRouteFile(relPath) {
+    // Strip .ts extension
+    const withoutExt = relPath.replace(/\.ts$/, "");
+    // Extract HTTP method from the last segment (e.g. "status.get" → method="get")
+    const dotIdx = withoutExt.lastIndexOf(".");
+    if (dotIdx === -1)
+        return null;
+    const method = withoutExt.slice(dotIdx + 1).toLowerCase();
+    const validMethods = ["get", "post", "put", "patch", "delete", "options"];
+    if (!validMethods.includes(method))
+        return null;
+    let routePath = withoutExt.slice(0, dotIdx);
+    // Replace [param] with :param
+    routePath = routePath.replace(/\[([^\]]+)\]/g, ":$1");
+    // Remove trailing /index
+    routePath = routePath.replace(/\/index$/, "");
+    // Ensure leading slash
+    if (!routePath.startsWith("/"))
+        routePath = "/" + routePath;
+    return { method, route: routePath };
+}
+/**
+ * Recursively discover all .ts files under a directory.
+ */
+function discoverFiles(dir, prefix = "") {
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            files.push(...discoverFiles(path.join(dir, entry.name), rel));
+        }
+        else if (entry.name.endsWith(".ts")) {
+            files.push(rel);
+        }
+    }
+    return files;
+}
+/**
+ * Load all API routes and server plugins, return an H3 listener.
+ */
+async function buildApiListener(server, cwd) {
+    const apiDir = path.join(cwd, "server/routes/api");
+    const pluginsDir = path.join(cwd, "server/plugins");
+    const app = createApp();
+    const router = createRouter();
+    app.use(router);
+    // Discover and register API route files
+    const routeFiles = discoverFiles(apiDir, "api");
+    let registered = 0;
+    for (const relFile of routeFiles) {
+        const parsed = parseRouteFile(relFile);
+        if (!parsed)
+            continue;
+        const absPath = path.join(cwd, "server/routes", relFile);
+        try {
+            const mod = await server.ssrLoadModule(`/${path.relative(cwd, absPath)}`);
+            const handler = mod.default;
+            if (typeof handler !== "function")
+                continue;
+            const routerMethod = router[parsed.method];
+            if (typeof routerMethod === "function") {
+                routerMethod.call(router, parsed.route, handler);
+                registered++;
+            }
+        }
+        catch (e) {
+            console.warn(`[dev-api-server] Failed to load route ${relFile}:`, e.message);
+        }
+    }
+    // Run server plugins (auth, file-sync, etc.)
+    if (fs.existsSync(pluginsDir)) {
+        const pluginFiles = fs
+            .readdirSync(pluginsDir)
+            .filter((f) => f.endsWith(".ts"))
+            .sort();
+        for (const file of pluginFiles) {
+            try {
+                const absPath = path.join(pluginsDir, file);
+                const mod = await server.ssrLoadModule(`/${path.relative(cwd, absPath)}`);
+                const plugin = mod.default;
+                if (typeof plugin === "function") {
+                    await plugin({ h3App: app });
+                }
+            }
+            catch (e) {
+                console.warn(`[dev-api-server] Failed to load plugin ${file}:`, e.message);
+            }
+        }
+    }
+    console.log(`[dev-api-server] ${registered} API routes registered`);
+    return toNodeListener(app);
+}
+/**
+ * Vite plugin that serves H3 API routes from server/routes/api/ during dev.
+ *
+ * This replaces the disabled Nitro Vite plugin for dev-mode API route serving.
+ * It scans the file-based routes, imports them, and mounts them on an H3 app
+ * that handles /api/* requests before React Router's SSR handler.
+ */
+export function devApiServer() {
+    return {
+        name: "agent-native-dev-api-server",
+        apply: "serve",
+        configureServer(server) {
+            const cwd = server.config.root || process.cwd();
+            const apiDir = path.join(cwd, "server/routes/api");
+            // Skip if no API routes directory exists
+            if (!fs.existsSync(apiDir))
+                return;
+            // Lazily initialize the H3 listener on first /api/ request.
+            // This avoids blocking server startup and ensures ssrLoadModule is ready.
+            let listenerPromise = null;
+            // Add middleware DIRECTLY (not via return) so it runs BEFORE
+            // Vite's internal middleware and React Router's SSR handler.
+            server.middlewares.use((req, res, next) => {
+                if (!req.url?.startsWith("/api/")) {
+                    return next();
+                }
+                if (!listenerPromise) {
+                    listenerPromise = buildApiListener(server, cwd);
+                }
+                listenerPromise
+                    .then((listener) => listener(req, res))
+                    .catch((err) => {
+                    console.error("[dev-api-server] Error handling request:", err);
+                    res.statusCode = 500;
+                    res.end(JSON.stringify({ error: "Internal server error" }));
+                });
+            });
+        },
+    };
+}
+//# sourceMappingURL=dev-api-server.js.map

package/dist/vite/dev-api-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-api-server.js","sourceRoot":"","sources":["../../src/vite/dev-api-server.ts"],"names":[],"mappings":"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"}

package/dist/vite/index.d.ts

@@ -1,4 +1,3 @@
-export { defineConfig, type ClientConfigOptions } from "./client.js";
-export { defineServerConfig, type ServerConfigOptions } from "./server.js";
-export { expressPlugin, type ExpressPluginOptions } from "./express-plugin.js";
+export { defineConfig, type ClientConfigOptions, type NitroOptions, } from "./client.js";
+export { devApiServer } from "./dev-api-server.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/vite/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/vite/index.js

@@ -1,4 +1,3 @@
-export { defineConfig } from "./client.js";
-export { defineServerConfig } from "./server.js";
-export { expressPlugin } from "./express-plugin.js";
+export { defineConfig, } from "./client.js";
+export { devApiServer } from "./dev-api-server.js";
 //# sourceMappingURL=index.js.map

package/dist/vite/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA4B,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAA4B,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAGb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -19,14 +19,17 @@
     },
     "./vite": "./dist/vite/index.js",
     "./server": "./dist/server/index.js",
+    "./db": "./dist/db/index.js",
     "./client": "./dist/client/index.js",
     "./shared": "./dist/shared/index.js",
     "./scripts": "./dist/scripts/index.js",
     "./adapters/sync": "./dist/adapters/sync/index.js",
+    "./adapters/drizzle": "./dist/adapters/drizzle/index.js",
     "./adapters/firestore": "./dist/adapters/firestore/index.js",
     "./adapters/supabase": "./dist/adapters/supabase/index.js",
-    "./adapters/neon": "./dist/adapters/neon/index.js",
+    "./adapters/convex": "./dist/adapters/convex/index.js",
     "./adapters/cli": "./dist/adapters/cli/index.js",
+    "./router": "./dist/router/index.js",
     "./a2a": "./dist/a2a/index.js",
     "./tailwind": "./dist/tailwind.preset.js",
     "./tsconfig.base.json": "./tsconfig.base.json"
@@ -46,23 +49,31 @@
     "release": "npm version patch && npm publish --access public"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.80.0",
+    "@react-router/dev": "^7.13.1",
+    "@react-router/fs-routes": "^7.13.1",
+    "better-sqlite3": "^12.8.0",
     "chokidar": "^4.0.0",
     "clsx": "^2.1.1",
     "dotenv": "^17.2.1",
+    "drizzle-orm": "^0.38.0",
+    "h3": "^1.14.0",
     "minimatch": "^10.0.0",
+    "nitro": "^3.0.0",
+    "p-limit": "^7.3.0",
+    "react-router": "^7.13.1",
     "tailwind-merge": "^2.6.0"
   },
   "peerDependencies": {
     "@supabase/supabase-js": ">=2",
-    "@neondatabase/serverless": ">=0.9",
     "@tanstack/react-query": ">=5",
     "@vitejs/plugin-react-swc": ">=4",
     "autoprefixer": ">=10",
-    "cors": ">=2",
-    "express": ">=5",
+    "convex": ">=1",
     "postcss": ">=8",
     "react": ">=18",
     "react-dom": ">=18",
+    "react-router": ">=7",
     "tailwindcss": ">=3",
     "tailwindcss-animate": ">=1",
     "typescript": ">=5",
@@ -84,13 +95,10 @@
     "postcss": {
       "optional": true
     },
-    "cors": {
-      "optional": true
-    },
-    "express": {
+    "@vitejs/plugin-react-swc": {
       "optional": true
     },
-    "@vitejs/plugin-react-swc": {
+    "react-router": {
       "optional": true
     },
     "vite": {
@@ -99,25 +107,26 @@
     "@supabase/supabase-js": {
       "optional": true
     },
-    "@neondatabase/serverless": {
+    "convex": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@react-router/dev": "^7.13.1",
+    "@react-router/fs-routes": "^7.13.1",
+    "@supabase/supabase-js": "^2.49.0",
     "@tanstack/react-query": "^5.84.2",
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.3",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
     "@types/node": "^24.2.1",
     "@types/react": "^18.3.23",
     "@vitejs/plugin-react-swc": "^4.0.0",
     "autoprefixer": "^10.4.21",
-    "cors": "^2.8.5",
-    "express": "^5.1.0",
-    "@neondatabase/serverless": "^1.0.0",
-    "@supabase/supabase-js": "^2.49.0",
+    "express": "^5.2.1",
     "firebase-admin": "^13.0.0",
     "postcss": "^8.5.6",
     "react": "^18.3.1",
+    "react-router": "^7.13.1",
     "tailwindcss": "^3.4.17",
     "tailwindcss-animate": "^1.0.7",
     "typescript": "^5.9.2",

package/src/templates/default/AGENTS.md

@@ -12,28 +12,46 @@ This is an **@agent-native/core** application — the AI agent and UI share stat
 4. **Bidirectional SSE events** — The file watcher keeps the UI in sync when the agent modifies files.
 5. **Agent can update code** — The agent can modify this app's source code directly.
 
-### Directory Structure
-
-```
-client/          # React frontend (Vite SPA)
-  App.tsx        # Entry point
-  components/    # UI components
-  hooks/         # React hooks
-  lib/           # Utilities (cn, etc)
+### Authentication
 
-server/          # Express backend
-  index.ts       # createAppServer() — routes + middleware
-  node-build.ts  # Production entry point
+Auth is automatic and environment-driven. The `server/plugins/auth.ts` plugin calls `autoMountAuth(app)` at startup.
 
-shared/          # Isomorphic code (imported by both client & server)
+- **Dev mode**: Auth is bypassed. `getSession()` returns `{ email: "local@localhost" }`. Zero friction.
+- **Production** (`ACCESS_TOKEN` set): Auth middleware auto-mounts. Login page for unauthenticated visitors.
+- **Production** (no token, no `AUTH_DISABLED=true`): Server refuses to start.
 
-scripts/         # Agent-callable scripts
-  run.ts         # Script dispatcher
-  *.ts           # Individual scripts (pnpm script <name>)
+Use `getSession(event)` server-side and `useSession()` client-side. See [docs/auth.md](docs/auth.md).
 
-data/            # App data files (watched by SSE)
+### Directory Structure
 
-.agents/skills/  # Agent skills — detailed guidance for each rule
+```
+client/                # React frontend
+  root.tsx             # HTML shell + global providers
+  entry.client.tsx     # Client hydration entry
+  routes.ts            # Route config — flatRoutes()
+  routes/              # File-based page routes (auto-discovered)
+    _index.tsx         # / (home page)
+  components/          # UI components
+  hooks/               # React hooks
+  lib/                 # Utilities (cn, etc)
+
+server/                # Nitro API server
+  routes/
+    api/               # File-based API routes (auto-discovered)
+    [...page].get.ts   # SSR catch-all (delegates to React Router)
+  plugins/             # Server plugins (startup logic)
+  lib/                 # Shared server modules
+
+shared/                # Isomorphic code (imported by both client & server)
+
+scripts/               # Agent-callable scripts
+  run.ts               # Script dispatcher
+  *.ts                 # Individual scripts (pnpm script <name>)
+
+data/                  # App data files (watched by SSE)
+
+react-router.config.ts # React Router framework config
+.agents/skills/        # Agent skills — detailed guidance for each rule
 ```
 
 ## Learnings & Preferences
@@ -64,10 +82,79 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 The **`frontend-design`** skill (sourced from [Anthropic's skills library](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)) enforces distinctive, production-grade aesthetics — committing to a clear visual direction and avoiding generic patterns like purple gradients, overused fonts, and cookie-cutter layouts.
 
+### Framework Basics
+
+**SSR-first framework, CSR-by-default content:** This app uses React Router v7 framework mode with `ssr: true`. But virtually every route renders only an SSR shell (loading spinner + meta tags). All real data fetching and rendering happens on the client via React Query hooks. Server-side data fetching is the exception — only used for public pages that need SEO/og tags.
+
+**Adding a page:**
+Create a file in `client/routes/`. The filename determines the URL path:
+
+```
+client/routes/_index.tsx              → /
+client/routes/settings.tsx            → /settings
+client/routes/inbox.tsx               → /inbox
+client/routes/inbox.$threadId.tsx     → /inbox/:threadId
+client/routes/$id.tsx                 → /:id (dynamic param)
+```
+
+Each route file exports a default component, optional `meta()`, and optional `HydrateFallback()`:
+
+```tsx
+import MyPage from "@/pages/MyPage";
+
+export function meta() {
+  return [{ title: "My Page" }];
+}
+
+export function HydrateFallback() {
+  return (
+    <div className="flex items-center justify-center h-screen">
+      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-foreground" />
+    </div>
+  );
+}
+
+export default function MyPageRoute() {
+  return <MyPage />;
+}
+```
+
+**Do NOT fetch data server-side** in route loaders unless the page genuinely needs SEO content or og tags based on dynamic data. The standard pattern is: SSR renders a loading spinner, client hydrates, React Query hooks fetch from `/api/*`.
+
 ### Key Patterns
 
 **Adding an API route:**
-Edit `server/index.ts`, add your route to `createAppServer()`.
+Create a file in `server/routes/api/`. The filename determines the URL path and HTTP method:
+
+```
+server/routes/api/items/index.get.ts    → GET  /api/items
+server/routes/api/items/[id].get.ts     → GET  /api/items/:id
+server/routes/api/items/[id].patch.ts   → PATCH /api/items/:id
+```
+
+Each file exports a default `defineEventHandler`.
+
+**Adding a server plugin:**
+Startup logic (file watcher, file sync, auth) lives in `server/plugins/`. Use `defineNitroPlugin` from core:
+
+```ts
+import { defineNitroPlugin } from "@agent-native/core";
+
+export default defineNitroPlugin(async (nitroApp) => {
+  // Runs once at server startup
+});
+```
+
+**Key imports from `@agent-native/core`:**
+
+| Import                                       | Purpose                                           |
+| -------------------------------------------- | ------------------------------------------------- |
+| `defineNitroPlugin`                          | Define a server plugin (re-exported from Nitro)   |
+| `createFileWatcher`                          | Watch data directory for changes                  |
+| `createSSEHandler`                           | Create SSE endpoint for real-time updates         |
+| `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)          |
+| `sendToAgentChat`                            | Send messages to agent from UI (client-side)      |
+| `agentChat`                                  | Send messages to agent from scripts (server-side) |
 
 **Adding a script:**
 Create `scripts/my-script.ts` exporting `default async function(args: string[])`.
@@ -91,11 +178,50 @@ import { agentChat } from "@agent-native/core";
 agentChat.submit("Generate something");
 ```
 
+### File Sync (Multi-User Collaboration)
+
+File sync is **opt-in** — enabled when `FILE_SYNC_ENABLED=true` is set in `.env`.
+
+**Environment variables:**
+
+| Variable                         | Required      | Description                                          |
+| -------------------------------- | ------------- | ---------------------------------------------------- |
+| `FILE_SYNC_ENABLED`              | No            | Set to `"true"` to enable sync                       |
+| `FILE_SYNC_BACKEND`              | When enabled  | `"firestore"`, `"supabase"`, or `"convex"`           |
+| `SUPABASE_URL`                   | For Supabase  | Project URL                                          |
+| `SUPABASE_PUBLISHABLE_KEY`       | For Supabase  | Publishable key (or legacy `SUPABASE_ANON_KEY`)      |
+| `GOOGLE_APPLICATION_CREDENTIALS` | For Firestore | Path to service account JSON                         |
+| `CONVEX_URL`                     | For Convex    | Deployment URL from `npx convex dev` (must be HTTPS) |
+
+**How sync works:**
+
+- `createFileSync()` factory in `server/plugins/file-sync.ts` reads env vars and initializes sync
+- Files matching `sync-config.json` patterns are synced to/from the remote database
+- Sync events flow through SSE (`source: "sync"`) alongside file change events
+- Conflicts produce `.conflict` sidecar files and notify the agent
+
+**Checking sync status:**
+
+- Read `data/.sync-status.json` for current sync state (connected, conflicts, retry queue)
+- Read `data/.sync-failures.json` for permanently failed sync operations
+
+**Handling conflicts:**
+
+- When `application-state/sync-conflict.json` appears, a sync conflict needs resolution
+- Read the `.conflict` file alongside the original to understand both versions
+- Edit the original file to resolve, then delete the `.conflict` file
+
+**Scratch files (not synced):**
+
+- Prefix temporary files with `_tmp-` (e.g., `data/_tmp-scratch.json`) to exclude from sync
+
 ### Tech Stack
 
-- **Framework:** @agent-native/core
+- **Framework:** @agent-native/core + React Router v7 (framework mode)
 - **Frontend:** React 18, Vite, TailwindCSS, shadcn/ui
-- **Backend:** Express 5
+- **Routing:** File-based via `flatRoutes()` — SSR shell + client rendering
+- **Backend:** Nitro (via @agent-native/core) — file-based API routing, server plugins, deploy-anywhere presets
 - **State:** File-based (SSE for real-time updates)
-- **Build:** `pnpm build` (client SPA + server bundle)
-- **Dev:** `pnpm dev` (Vite dev server with Express middleware)
+- **Build:** `pnpm build` (React Router build — client + SSR + Nitro server)
+- **Dev:** `pnpm dev` (Vite dev server with both React Router + Nitro plugins)
+- **Start:** `node .output/server/index.mjs` (production)

package/src/templates/default/_gitignore

@@ -1,4 +1,7 @@
-# Logs
+# React Router generated types
+.react-router/
+
+# Logs
 logs
 *.log
 npm-debug.log*
@@ -25,9 +28,10 @@ dist-ssr
 .env.*
 !.env.example
 
-# Data
-data/uploads/
-data/settings.json
+# Data
+data/uploads/
+data/settings.json
+data/.sessions.json
 
 # Learnings (personal preferences and memory — use learnings.defaults.md for tracked defaults)
-learnings.md
+learnings.md

package/src/templates/default/client/entry.client.tsx

@@ -0,0 +1,4 @@
+import { hydrateRoot } from "react-dom/client";
+import { HydratedRouter } from "react-router/dom";
+
+hydrateRoot(document, <HydratedRouter />);

package/src/templates/default/client/entry.server.tsx

@@ -0,0 +1,55 @@
+import type { AppLoadContext, EntryContext } from "react-router";
+import { ServerRouter } from "react-router";
+import ReactDOMServer from "react-dom/server.browser";
+const { renderToReadableStream } = ReactDOMServer;
+import { isbot } from "isbot";
+
+export const streamTimeout = 5_000;
+
+export default async function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  routerContext: EntryContext,
+  _loadContext: AppLoadContext,
+) {
+  if (request.method.toUpperCase() === "HEAD") {
+    return new Response(null, {
+      status: responseStatusCode,
+      headers: responseHeaders,
+    });
+  }
+
+  const userAgent = request.headers.get("user-agent");
+  const waitForAll = (userAgent && isbot(userAgent)) || routerContext.isSpaMode;
+
+  const abortController = new AbortController();
+  const timeoutId = setTimeout(() => abortController.abort(), streamTimeout);
+
+  try {
+    const body = await renderToReadableStream(
+      <ServerRouter context={routerContext} url={request.url} />,
+      {
+        signal: abortController.signal,
+        onError(error: unknown) {
+          if (!abortController.signal.aborted) {
+            responseStatusCode = 500;
+            console.error(error);
+          }
+        },
+      },
+    );
+
+    if (waitForAll) {
+      await body.allReady;
+    }
+
+    responseHeaders.set("Content-Type", "text/html");
+    return new Response(body, {
+      headers: responseHeaders,
+      status: responseStatusCode,
+    });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/templates/default/client/root.tsx

@@ -0,0 +1,82 @@
+import {
+  Links,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+  isRouteErrorResponse,
+} from "react-router";
+import { useState } from "react";
+import {
+  QueryClient,
+  QueryClientProvider,
+  useQueryClient,
+} from "@tanstack/react-query";
+import { useFileWatcher } from "@agent-native/core";
+import "./global.css";
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className="dark">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+function FileWatcher({ children }: { children: React.ReactNode }) {
+  const qc = useQueryClient();
+  useFileWatcher({ queryClient: qc, queryKeys: ["files"] });
+  return <>{children}</>;
+}
+
+export default function Root() {
+  const [queryClient] = useState(() => new QueryClient());
+  return (
+    <QueryClientProvider client={queryClient}>
+      <FileWatcher>
+        <Outlet />
+      </FileWatcher>
+    </QueryClientProvider>
+  );
+}
+
+export function ErrorBoundary({ error }: { error: unknown }) {
+  let message = "Oops!";
+  let details = "An unexpected error occurred.";
+  let stack: string | undefined;
+
+  if (isRouteErrorResponse(error)) {
+    message = error.status === 404 ? "404" : "Error";
+    details =
+      error.status === 404
+        ? "The requested page could not be found."
+        : error.statusText || details;
+  } else if (import.meta.env.DEV && error instanceof Error) {
+    details = error.message;
+    stack = error.stack;
+  }
+
+  return (
+    <main className="flex items-center justify-center min-h-screen p-4">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold mb-2">{message}</h1>
+        <p className="text-muted-foreground">{details}</p>
+        {stack && (
+          <pre className="mt-4 text-left text-xs overflow-auto max-w-lg mx-auto p-4 bg-muted rounded">
+            <code>{stack}</code>
+          </pre>
+        )}
+      </div>
+    </main>
+  );
+}