@korajs/cli 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/index.d.cts

@@ -59,6 +59,63 @@ declare class DevServerError extends KoraError {
     constructor(binary: string, searchPath: string);
 }
 
+/**
+ * Writes an AGENTS.md into an existing project so AI coding agents follow Kora
+ * conventions. Refuses to overwrite an existing file unless `--force` is passed.
+ */
+declare const agentsCommand: citty.CommandDef<{
+    force: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    framework: {
+        type: "string";
+        description: string;
+    };
+}>;
+
+/**
+ * Canonical AGENTS.md generator.
+ *
+ * `kora agents-md` writes this file into an existing project so AI coding agents
+ * (and humans) build Kora apps correctly instead of drifting to fetch calls,
+ * hand-written types, and loading spinners. New projects scaffolded with
+ * `create-kora-app` already ship an AGENTS.md; this command covers the manual
+ * setup path and lets existing projects regenerate the guidance on demand.
+ */
+/** UI framework whose bindings section the generated AGENTS.md documents. */
+type AgentsFramework = 'react' | 'vue' | 'svelte';
+/** All supported frameworks, for validation and help text. */
+declare const AGENTS_FRAMEWORKS: readonly AgentsFramework[];
+/**
+ * Narrows an arbitrary string to a supported {@link AgentsFramework}.
+ *
+ * @param value - Candidate framework identifier
+ * @returns `true` when `value` is one of the supported frameworks
+ */
+declare function isAgentsFramework(value: string): value is AgentsFramework;
+/**
+ * Detects the UI framework from a project's package manifest by looking for the
+ * matching `@korajs/*` binding package in dependencies or devDependencies.
+ *
+ * @param manifest - Parsed `package.json` contents
+ * @returns The detected framework, or `null` when no binding package is present
+ */
+declare function detectFrameworkFromManifest(manifest: unknown): AgentsFramework | null;
+/**
+ * Renders the full AGENTS.md document for the given framework.
+ *
+ * The body (golden rules, data API cheat sheet, conflict handling, sync notes,
+ * commands) is framework-agnostic; only the bindings section changes. File paths
+ * are described as conventions so the guidance is correct for both scaffolded and
+ * manually configured projects.
+ *
+ * @param framework - UI framework whose bindings to document
+ * @returns The complete AGENTS.md file contents, terminated with a trailing newline
+ */
+declare function generateAgentsMd(framework: AgentsFramework): string;
+
 /**
  * Generates TypeScript interfaces from a SchemaDefinition.
  * For each collection, produces three interfaces:
@@ -692,4 +749,4 @@ interface SyncProviderPresetOptions {
  */
 declare function applySyncProviderPreset(options: SyncProviderPresetOptions): Promise<void>;
 
-export { type AuthOption, type BuildArtifacts, ClackPromptClient, CliError, type ClientBuildOptions, type ClientBuildResult, type ContextAwareDeployAdapter, type CreateFlags, type CreatePreferences, DEPLOY_PLATFORMS, type DatabaseOption, type DatabaseProviderOption, type DeployAdapter, type DeployPlatform, type DeployResult, type DeployState, type DeployStateCreateInput, type DeployStatePatch, type DeploymentStatus, DevServerError, type DockerfileOptions, FlyAdapter, type FlyAdapterContext, type FlyAdapterOptions, type FlyCommandResult, type FlyCommandRunner, type FlyTomlOptions, type FrameworkOption, InvalidProjectError, type LogLine, type LogOptions, NodeFlyCommandRunner, NodeRailwayCommandRunner, PACKAGE_MANAGERS, type PackageManager, type PreferenceResolutionResult, PreferenceStore, type ProjectConfig, ProjectExistsError, type ProjectNameValidationResult, PromptCancelledError, type PromptClient, type ProvisionResult, RailwayAdapter, type RailwayAdapterContext, type RailwayAdapterOptions, type RailwayCommandResult, type RailwayCommandRunner, type RailwayJsonOptions, ReadlinePromptClient, SchemaNotFoundError, type SelectOption, type ServerBundleOptions, type ServerBundleResult, StubDeployAdapter, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, type TemplateSelectionInput, applySyncProviderPreset, buildClient, bundleServer, createDeployAdapter, createPromptClient, deployCommand, determineTemplateFromSelections, generateDeployPackageJson, generateDockerIgnore, generateDockerfile, generateFlyToml, generateRailwayJson, generateTypes, getCreatePreferencesOrDefault, getDefaultCreatePreferences, isAuthValue, isDatabaseProviderValue, isDatabaseValue, isDeployPlatform, isFrameworkValue, readDeployState, resetDeployState, resolveCreatePreferencesFlow, resolveDeployDirectory, resolveDeployStatePath, saveResolvedPreferences, shouldSavePreferences, updateDeployState, validateProjectName, writeDeployState, writeDockerIgnoreArtifact, writeDockerfileArtifact, writeFlyTomlArtifact, writeRailwayJsonArtifact };
+export { AGENTS_FRAMEWORKS, type AgentsFramework, type AuthOption, type BuildArtifacts, ClackPromptClient, CliError, type ClientBuildOptions, type ClientBuildResult, type ContextAwareDeployAdapter, type CreateFlags, type CreatePreferences, DEPLOY_PLATFORMS, type DatabaseOption, type DatabaseProviderOption, type DeployAdapter, type DeployPlatform, type DeployResult, type DeployState, type DeployStateCreateInput, type DeployStatePatch, type DeploymentStatus, DevServerError, type DockerfileOptions, FlyAdapter, type FlyAdapterContext, type FlyAdapterOptions, type FlyCommandResult, type FlyCommandRunner, type FlyTomlOptions, type FrameworkOption, InvalidProjectError, type LogLine, type LogOptions, NodeFlyCommandRunner, NodeRailwayCommandRunner, PACKAGE_MANAGERS, type PackageManager, type PreferenceResolutionResult, PreferenceStore, type ProjectConfig, ProjectExistsError, type ProjectNameValidationResult, PromptCancelledError, type PromptClient, type ProvisionResult, RailwayAdapter, type RailwayAdapterContext, type RailwayAdapterOptions, type RailwayCommandResult, type RailwayCommandRunner, type RailwayJsonOptions, ReadlinePromptClient, SchemaNotFoundError, type SelectOption, type ServerBundleOptions, type ServerBundleResult, StubDeployAdapter, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, type TemplateSelectionInput, agentsCommand, applySyncProviderPreset, buildClient, bundleServer, createDeployAdapter, createPromptClient, deployCommand, detectFrameworkFromManifest, determineTemplateFromSelections, generateAgentsMd, generateDeployPackageJson, generateDockerIgnore, generateDockerfile, generateFlyToml, generateRailwayJson, generateTypes, getCreatePreferencesOrDefault, getDefaultCreatePreferences, isAgentsFramework, isAuthValue, isDatabaseProviderValue, isDatabaseValue, isDeployPlatform, isFrameworkValue, readDeployState, resetDeployState, resolveCreatePreferencesFlow, resolveDeployDirectory, resolveDeployStatePath, saveResolvedPreferences, shouldSavePreferences, updateDeployState, validateProjectName, writeDeployState, writeDockerIgnoreArtifact, writeDockerfileArtifact, writeFlyTomlArtifact, writeRailwayJsonArtifact };

package/dist/index.d.ts

@@ -59,6 +59,63 @@ declare class DevServerError extends KoraError {
     constructor(binary: string, searchPath: string);
 }
 
+/**
+ * Writes an AGENTS.md into an existing project so AI coding agents follow Kora
+ * conventions. Refuses to overwrite an existing file unless `--force` is passed.
+ */
+declare const agentsCommand: citty.CommandDef<{
+    force: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    framework: {
+        type: "string";
+        description: string;
+    };
+}>;
+
+/**
+ * Canonical AGENTS.md generator.
+ *
+ * `kora agents-md` writes this file into an existing project so AI coding agents
+ * (and humans) build Kora apps correctly instead of drifting to fetch calls,
+ * hand-written types, and loading spinners. New projects scaffolded with
+ * `create-kora-app` already ship an AGENTS.md; this command covers the manual
+ * setup path and lets existing projects regenerate the guidance on demand.
+ */
+/** UI framework whose bindings section the generated AGENTS.md documents. */
+type AgentsFramework = 'react' | 'vue' | 'svelte';
+/** All supported frameworks, for validation and help text. */
+declare const AGENTS_FRAMEWORKS: readonly AgentsFramework[];
+/**
+ * Narrows an arbitrary string to a supported {@link AgentsFramework}.
+ *
+ * @param value - Candidate framework identifier
+ * @returns `true` when `value` is one of the supported frameworks
+ */
+declare function isAgentsFramework(value: string): value is AgentsFramework;
+/**
+ * Detects the UI framework from a project's package manifest by looking for the
+ * matching `@korajs/*` binding package in dependencies or devDependencies.
+ *
+ * @param manifest - Parsed `package.json` contents
+ * @returns The detected framework, or `null` when no binding package is present
+ */
+declare function detectFrameworkFromManifest(manifest: unknown): AgentsFramework | null;
+/**
+ * Renders the full AGENTS.md document for the given framework.
+ *
+ * The body (golden rules, data API cheat sheet, conflict handling, sync notes,
+ * commands) is framework-agnostic; only the bindings section changes. File paths
+ * are described as conventions so the guidance is correct for both scaffolded and
+ * manually configured projects.
+ *
+ * @param framework - UI framework whose bindings to document
+ * @returns The complete AGENTS.md file contents, terminated with a trailing newline
+ */
+declare function generateAgentsMd(framework: AgentsFramework): string;
+
 /**
  * Generates TypeScript interfaces from a SchemaDefinition.
  * For each collection, produces three interfaces:
@@ -692,4 +749,4 @@ interface SyncProviderPresetOptions {
  */
 declare function applySyncProviderPreset(options: SyncProviderPresetOptions): Promise<void>;
 
-export { type AuthOption, type BuildArtifacts, ClackPromptClient, CliError, type ClientBuildOptions, type ClientBuildResult, type ContextAwareDeployAdapter, type CreateFlags, type CreatePreferences, DEPLOY_PLATFORMS, type DatabaseOption, type DatabaseProviderOption, type DeployAdapter, type DeployPlatform, type DeployResult, type DeployState, type DeployStateCreateInput, type DeployStatePatch, type DeploymentStatus, DevServerError, type DockerfileOptions, FlyAdapter, type FlyAdapterContext, type FlyAdapterOptions, type FlyCommandResult, type FlyCommandRunner, type FlyTomlOptions, type FrameworkOption, InvalidProjectError, type LogLine, type LogOptions, NodeFlyCommandRunner, NodeRailwayCommandRunner, PACKAGE_MANAGERS, type PackageManager, type PreferenceResolutionResult, PreferenceStore, type ProjectConfig, ProjectExistsError, type ProjectNameValidationResult, PromptCancelledError, type PromptClient, type ProvisionResult, RailwayAdapter, type RailwayAdapterContext, type RailwayAdapterOptions, type RailwayCommandResult, type RailwayCommandRunner, type RailwayJsonOptions, ReadlinePromptClient, SchemaNotFoundError, type SelectOption, type ServerBundleOptions, type ServerBundleResult, StubDeployAdapter, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, type TemplateSelectionInput, applySyncProviderPreset, buildClient, bundleServer, createDeployAdapter, createPromptClient, deployCommand, determineTemplateFromSelections, generateDeployPackageJson, generateDockerIgnore, generateDockerfile, generateFlyToml, generateRailwayJson, generateTypes, getCreatePreferencesOrDefault, getDefaultCreatePreferences, isAuthValue, isDatabaseProviderValue, isDatabaseValue, isDeployPlatform, isFrameworkValue, readDeployState, resetDeployState, resolveCreatePreferencesFlow, resolveDeployDirectory, resolveDeployStatePath, saveResolvedPreferences, shouldSavePreferences, updateDeployState, validateProjectName, writeDeployState, writeDockerIgnoreArtifact, writeDockerfileArtifact, writeFlyTomlArtifact, writeRailwayJsonArtifact };
+export { AGENTS_FRAMEWORKS, type AgentsFramework, type AuthOption, type BuildArtifacts, ClackPromptClient, CliError, type ClientBuildOptions, type ClientBuildResult, type ContextAwareDeployAdapter, type CreateFlags, type CreatePreferences, DEPLOY_PLATFORMS, type DatabaseOption, type DatabaseProviderOption, type DeployAdapter, type DeployPlatform, type DeployResult, type DeployState, type DeployStateCreateInput, type DeployStatePatch, type DeploymentStatus, DevServerError, type DockerfileOptions, FlyAdapter, type FlyAdapterContext, type FlyAdapterOptions, type FlyCommandResult, type FlyCommandRunner, type FlyTomlOptions, type FrameworkOption, InvalidProjectError, type LogLine, type LogOptions, NodeFlyCommandRunner, NodeRailwayCommandRunner, PACKAGE_MANAGERS, type PackageManager, type PreferenceResolutionResult, PreferenceStore, type ProjectConfig, ProjectExistsError, type ProjectNameValidationResult, PromptCancelledError, type PromptClient, type ProvisionResult, RailwayAdapter, type RailwayAdapterContext, type RailwayAdapterOptions, type RailwayCommandResult, type RailwayCommandRunner, type RailwayJsonOptions, ReadlinePromptClient, SchemaNotFoundError, type SelectOption, type ServerBundleOptions, type ServerBundleResult, StubDeployAdapter, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, type TemplateSelectionInput, agentsCommand, applySyncProviderPreset, buildClient, bundleServer, createDeployAdapter, createPromptClient, deployCommand, detectFrameworkFromManifest, determineTemplateFromSelections, generateAgentsMd, generateDeployPackageJson, generateDockerIgnore, generateDockerfile, generateFlyToml, generateRailwayJson, generateTypes, getCreatePreferencesOrDefault, getDefaultCreatePreferences, isAgentsFramework, isAuthValue, isDatabaseProviderValue, isDatabaseValue, isDeployPlatform, isFrameworkValue, readDeployState, resetDeployState, resolveCreatePreferencesFlow, resolveDeployDirectory, resolveDeployStatePath, saveResolvedPreferences, shouldSavePreferences, updateDeployState, validateProjectName, writeDeployState, writeDockerIgnoreArtifact, writeDockerfileArtifact, writeFlyTomlArtifact, writeRailwayJsonArtifact };

package/dist/index.js

@@ -1,21 +1,26 @@
 #!/usr/bin/env node
 import {
+  AGENTS_FRAMEWORKS,
   DEPLOY_PLATFORMS,
   FlyAdapter,
   NodeFlyCommandRunner,
   NodeRailwayCommandRunner,
   RailwayAdapter,
   StubDeployAdapter,
+  agentsCommand,
   buildClient,
   bundleServer,
   createDeployAdapter,
   deployCommand,
+  detectFrameworkFromManifest,
+  generateAgentsMd,
   generateDeployPackageJson,
   generateDockerIgnore,
   generateDockerfile,
   generateFlyToml,
   generateRailwayJson,
   generateTypes,
+  isAgentsFramework,
   isDeployPlatform,
   readDeployState,
   resetDeployState,
@@ -27,7 +32,7 @@ import {
   writeDockerfileArtifact,
   writeFlyTomlArtifact,
   writeRailwayJsonArtifact
-} from "./chunk-EOWLAAIV.js";
+} from "./chunk-4IKCHRJ6.js";
 import {
   ClackPromptClient,
   CliError,
@@ -54,9 +59,10 @@ import {
   saveResolvedPreferences,
   shouldSavePreferences,
   validateProjectName
-} from "./chunk-B5YS4STN.js";
+} from "./chunk-G2PBYMMA.js";
 import "./chunk-5NI2FEQL.js";
 export {
+  AGENTS_FRAMEWORKS,
   ClackPromptClient,
   CliError,
   DEPLOY_PLATFORMS,
@@ -75,13 +81,16 @@ export {
   StubDeployAdapter,
   TEMPLATES,
   TEMPLATE_INFO,
+  agentsCommand,
   applySyncProviderPreset,
   buildClient,
   bundleServer,
   createDeployAdapter,
   createPromptClient,
   deployCommand,
+  detectFrameworkFromManifest,
   determineTemplateFromSelections,
+  generateAgentsMd,
   generateDeployPackageJson,
   generateDockerIgnore,
   generateDockerfile,
@@ -90,6 +99,7 @@ export {
   generateTypes,
   getCreatePreferencesOrDefault,
   getDefaultCreatePreferences,
+  isAgentsFramework,
   isAuthValue,
   isDatabaseProviderValue,
   isDatabaseValue,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korajs/cli",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.10",
   "description": "Kora.js CLI tooling and project scaffolding",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -37,7 +37,7 @@
     "conf": "^15.1.0",
     "esbuild": "^0.28.0",
     "validate-npm-package-name": "^7.0.2",
-    "@korajs/core": "1.0.0-beta.1"
+    "@korajs/core": "1.0.0-beta.10"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
@@ -47,12 +47,12 @@
     "tsup": "^8.3.6",
     "typescript": "^5.7.3",
     "vitest": "^3.0.4",
-    "@korajs/store": "1.0.0-beta.1",
-    "@korajs/server": "1.0.0-beta.1",
-    "@korajs/merge": "1.0.0-beta.1",
-    "korajs": "1.0.0-beta.1",
-    "@korajs/sync": "1.0.0-beta.1",
-    "@korajs/test": "1.0.0-beta.1"
+    "@korajs/server": "1.0.0-beta.10",
+    "@korajs/store": "1.0.0-beta.10",
+    "@korajs/sync": "1.0.0-beta.10",
+    "@korajs/merge": "1.0.0-beta.10",
+    "@korajs/test": "1.0.0-beta.10",
+    "korajs": "1.0.0-beta.10"
   },
   "license": "MIT",
   "scripts": {

package/templates/react-basic/README.md.hbs

@@ -47,7 +47,7 @@ To enable real-time sync across devices, update `src/main.tsx`:
 const app = createApp({
   schema,
   sync: {
-    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001',
+    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001/kora-sync',
   },
   // ...
 })

package/templates/react-basic/src/main.tsx

@@ -12,7 +12,7 @@ const app = createApp({
 	store: {
 		workerUrl: koraWorkerUrl,
 	},
-	devtools: true,
+	devtools: import.meta.env.DEV,
 })
 
 createRoot(document.getElementById('root')!).render(

package/templates/react-basic/src/vite-env.d.ts

@@ -1,4 +1,5 @@
 interface ImportMetaEnv {
+	readonly DEV: boolean
 	readonly VITE_SYNC_URL?: string
 }
 

package/templates/react-basic/vite.config.ts

@@ -6,23 +6,26 @@ import { defineConfig } from 'vite'
 
 /**
  * Adds Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers
- * required for SharedArrayBuffer. Without these headers, OPFS SAH Pool VFS
- * cannot be used and SQLite WASM falls back to in-memory storage (no persistence).
+ * enabling SharedArrayBuffer where browsers support it while keeping common
+ * third-party embeds such as YouTube and Vimeo usable. Kora falls back to
+ * durable IndexedDB storage when SharedArrayBuffer is unavailable.
  */
 function crossOriginIsolation(): Plugin {
+	const embedderPolicy = process.env.KORA_COEP_POLICY || 'credentialless'
+
 	return {
 		name: 'cross-origin-isolation',
 		configureServer(server) {
 			server.middlewares.use((_req, res, next) => {
 				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				next()
 			})
 		},
 		configurePreviewServer(server) {
 			server.middlewares.use((_req, res, next) => {
 				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				next()
 			})
 		},

package/templates/react-sync/README.md.hbs

@@ -11,7 +11,7 @@ npm run dev
 This starts both the Vite dev server and the Kora sync server.
 
 - **App**: http://localhost:5173
-- **Sync server**: ws://localhost:3001
+- **Sync server**: ws://localhost:3001/kora-sync
 
 ## Project Structure
 
@@ -40,11 +40,12 @@ writes, and `useTodos.ts` is the React binding that exposes todo data and action
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `VITE_SYNC_URL` | `ws://localhost:3001` | WebSocket URL for the sync server |
+| `VITE_SYNC_URL` | `ws://localhost:3001/kora-sync` | WebSocket URL for the sync endpoint |
 | `VITE_AUTH_URL` | current origin | HTTP URL for `/auth/*` routes |
 | `PORT` | `3001` | Sync server port |
-| `KORA_SERVER_DB` | `./kora-server.db` | SQLite file used by the sync server when `DATABASE_URL` is empty |
-| `KORA_AUTH_DB` | `./kora-auth.db` | SQLite file used by OAuth state and linked identities when `DATABASE_URL` is empty |
+| `KORA_SERVER_DB` | `./.kora/kora-server.db` | SQLite file used by the sync server when `DATABASE_URL` is empty |
+| `KORA_AUTH_DB` | `./.kora/kora-auth.db` | SQLite file used by OAuth state and linked identities when `DATABASE_URL` is empty |
+| `KORA_COEP_POLICY` | `credentialless` | Dev/preview Cross-Origin-Embedder-Policy. Use `require-corp` only when every embedded resource opts in. |
 | `DATABASE_URL` | (none) | PostgreSQL connection string for production sync server deployments |
 | `KORA_SYNC_PATH` | `/kora-sync` | WebSocket path exposed by the sync server |
 | `KORA_AUTH_SECRET` | (none) | Enables built-in `/auth/*` routes and authenticated sync when set |
@@ -94,7 +95,7 @@ The client and sync server must be deployed separately:
 Set `VITE_SYNC_URL` to your deployed sync server URL when building:
 
 ```bash
-VITE_SYNC_URL=wss://your-server.example.com npm run build
+VITE_SYNC_URL=wss://your-server.example.com/kora-sync npm run build
 ```
 
 ## Learn More

package/templates/react-sync/server.ts

@@ -1,3 +1,4 @@
+import { existsSync, readFileSync } from 'node:fs'
 import {
 	type CreateKoraAuthServerOptions,
 	createKoraAuthServer,
@@ -12,6 +13,45 @@ import {
 } from '@korajs/server'
 import schema from './src/schema'
 
+loadLocalEnv()
+
+function loadLocalEnv(mode = process.env.NODE_ENV || 'development') {
+	const existingKeys = new Set(Object.keys(process.env))
+	for (const file of ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`]) {
+		if (!existsSync(file)) continue
+		for (const [key, value] of Object.entries(parseEnvFile(readFileSync(file, 'utf8')))) {
+			if (!existingKeys.has(key)) {
+				process.env[key] = value
+			}
+		}
+	}
+}
+
+function parseEnvFile(contents: string): Record<string, string> {
+	const env: Record<string, string> = {}
+	for (const rawLine of contents.split(/\r?\n/)) {
+		const line = rawLine.trim()
+		if (!line || line.startsWith('#')) continue
+		const normalized = line.startsWith('export ') ? line.slice('export '.length).trim() : line
+		const equalsIndex = normalized.indexOf('=')
+		if (equalsIndex <= 0) continue
+		const key = normalized.slice(0, equalsIndex).trim()
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue
+		env[key] = parseEnvValue(normalized.slice(equalsIndex + 1).trim())
+	}
+	return env
+}
+
+function parseEnvValue(value: string): string {
+	const quote = value[0]
+	if ((quote === '"' || quote === "'") && value[value.length - 1] === quote) {
+		const inner = value.slice(1, -1)
+		return quote === '"' ? inner.replace(/\\n/g, '\n').replace(/\\r/g, '\r') : inner
+	}
+	const commentIndex = value.search(/\s#/)
+	return (commentIndex >= 0 ? value.slice(0, commentIndex) : value).trim()
+}
+
 async function createStore() {
 	if (process.env.DATABASE_URL) {
 		return createPostgresServerStore({
@@ -20,7 +60,7 @@ async function createStore() {
 	}
 
 	return createSqliteServerStore({
-		filename: process.env.KORA_SERVER_DB || './kora-server.db',
+		filename: process.env.KORA_SERVER_DB || './.kora/kora-server.db',
 	})
 }
 
@@ -36,7 +76,10 @@ async function start() {
 		staticDir: './dist',
 		syncPath,
 		httpRoutes: auth ? [{ path: '/auth', handle: auth.handleRequest }] : undefined,
-		syncOptions: auth ? { auth: auth.auth } : undefined,
+		syncOptions: {
+			schemaVersion: schema.version,
+			...(auth ? { auth: auth.auth } : {}),
+		},
 		operationalAuth: {
 			adminToken: process.env.KORA_ADMIN_TOKEN,
 			metricsToken: process.env.KORA_METRICS_TOKEN,
@@ -72,7 +115,7 @@ async function createOAuthConfig(): Promise<CreateKoraAuthServerOptions['oauth']
 	const oauthStores = process.env.DATABASE_URL
 		? await createPostgresOAuthStores({ connectionString: process.env.DATABASE_URL })
 		: await createSqliteOAuthStores({
-				filename: process.env.KORA_AUTH_DB || './kora-auth.db',
+				filename: process.env.KORA_AUTH_DB || './.kora/kora-auth.db',
 			})
 
 	return {

package/templates/react-sync/src/main.tsx

@@ -26,7 +26,7 @@ const app = createApp({
 	store: {
 		workerUrl: koraWorkerUrl,
 	},
-	devtools: true,
+	devtools: import.meta.env.DEV,
 })
 
 // Connect to sync server once the app is ready

package/templates/react-sync/src/vite-env.d.ts

@@ -1,4 +1,5 @@
 interface ImportMetaEnv {
+	readonly DEV: boolean
 	readonly VITE_SYNC_URL?: string
 }
 

package/templates/react-sync/vite.config.ts

@@ -6,23 +6,26 @@ import { defineConfig } from 'vite'
 
 /**
  * Adds Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers
- * required for SharedArrayBuffer. Without these headers, OPFS SAH Pool VFS
- * cannot be used and SQLite WASM falls back to in-memory storage (no persistence).
+ * enabling SharedArrayBuffer where browsers support it while keeping common
+ * third-party embeds such as YouTube and Vimeo usable. Kora falls back to
+ * durable IndexedDB storage when SharedArrayBuffer is unavailable.
  */
 function crossOriginIsolation(): Plugin {
+	const embedderPolicy = process.env.KORA_COEP_POLICY || 'credentialless'
+
 	return {
 		name: 'cross-origin-isolation',
 		configureServer(server) {
 			server.middlewares.use((_req, res, next) => {
 				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				next()
 			})
 		},
 		configurePreviewServer(server) {
 			server.middlewares.use((_req, res, next) => {
 				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				next()
 			})
 		},
@@ -81,12 +84,19 @@ export default defineConfig({
 	},
 	server: {
 		allowedHosts: true,
+		watch: {
+			ignored: ['**/.kora/**', '**/kora/generated/**', '**/*.db', '**/*.db-shm', '**/*.db-wal'],
+		},
 		proxy: {
 			'/kora-sync': {
 				target: 'ws://localhost:3001',
 				ws: true,
 				rewriteWsOrigin: true,
 			},
+			'/auth': {
+				target: 'http://localhost:3001',
+				changeOrigin: true,
+			},
 		},
 	},
 })

package/templates/react-tailwind/README.md.hbs

@@ -47,7 +47,7 @@ To enable real-time sync across devices, update `src/main.tsx`:
 const app = createApp({
   schema,
   sync: {
-    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001',
+    url: import.meta.env.VITE_SYNC_URL || 'ws://localhost:3001/kora-sync',
   },
   // ...
 })

package/templates/react-tailwind/src/main.tsx

@@ -12,7 +12,7 @@ const app = createApp({
 	store: {
 		workerUrl: koraWorkerUrl,
 	},
-	devtools: true,
+	devtools: import.meta.env.DEV,
 })
 
 createRoot(document.getElementById('root')!).render(

package/templates/react-tailwind/src/vite-env.d.ts

@@ -1,4 +1,5 @@
 interface ImportMetaEnv {
+	readonly DEV: boolean
 	readonly VITE_SYNC_URL?: string
 }
 

package/templates/react-tailwind/vite.config.ts

@@ -7,23 +7,26 @@ import { defineConfig } from 'vite'
 
 /**
  * Adds Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers
- * required for SharedArrayBuffer. Without these headers, OPFS SAH Pool VFS
- * cannot be used and SQLite WASM falls back to in-memory storage (no persistence).
+ * enabling SharedArrayBuffer where browsers support it while keeping common
+ * third-party embeds such as YouTube and Vimeo usable. Kora falls back to
+ * durable IndexedDB storage when SharedArrayBuffer is unavailable.
  */
 function crossOriginIsolation(): Plugin {
+	const embedderPolicy = process.env.KORA_COEP_POLICY || 'credentialless'
+
 	return {
 		name: 'cross-origin-isolation',
 		configureServer(server) {
 			server.middlewares.use((_req, res, next) => {
 				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				next()
 			})
 		},
 		configurePreviewServer(server) {
 			server.middlewares.use((_req, res, next) => {
 				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-				res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
 				next()
 			})
 		},

package/templates/react-tailwind-sync/README.md.hbs

@@ -11,7 +11,7 @@ npm run dev
 This starts both the Vite dev server and the Kora sync server.
 
 - **App**: http://localhost:5173
-- **Sync server**: ws://localhost:3001
+- **Sync server**: ws://localhost:3001/kora-sync
 
 ## Project Structure
 
@@ -40,11 +40,12 @@ writes, and `useTodos.ts` is the React binding that exposes todo data and action
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `VITE_SYNC_URL` | `ws://localhost:3001` | WebSocket URL for the sync server |
+| `VITE_SYNC_URL` | `ws://localhost:3001/kora-sync` | WebSocket URL for the sync endpoint |
 | `VITE_AUTH_URL` | current origin | HTTP URL for `/auth/*` routes |
 | `PORT` | `3001` | Sync server port |
-| `KORA_SERVER_DB` | `./kora-server.db` | SQLite file used by the sync server when `DATABASE_URL` is empty |
-| `KORA_AUTH_DB` | `./kora-auth.db` | SQLite file used by OAuth state and linked identities when `DATABASE_URL` is empty |
+| `KORA_SERVER_DB` | `./.kora/kora-server.db` | SQLite file used by the sync server when `DATABASE_URL` is empty |
+| `KORA_AUTH_DB` | `./.kora/kora-auth.db` | SQLite file used by OAuth state and linked identities when `DATABASE_URL` is empty |
+| `KORA_COEP_POLICY` | `credentialless` | Dev/preview Cross-Origin-Embedder-Policy. Use `require-corp` only when every embedded resource opts in. |
 | `DATABASE_URL` | (none) | PostgreSQL connection string for production sync server deployments |
 | `KORA_SYNC_PATH` | `/kora-sync` | WebSocket path exposed by the sync server |
 | `KORA_AUTH_SECRET` | (none) | Enables built-in `/auth/*` routes and authenticated sync when set |
@@ -94,7 +95,7 @@ The client and sync server must be deployed separately:
 Set `VITE_SYNC_URL` to your deployed sync server URL when building:
 
 ```bash
-VITE_SYNC_URL=wss://your-server.example.com npm run build
+VITE_SYNC_URL=wss://your-server.example.com/kora-sync npm run build
 ```
 
 ## Learn More