devflare 1.0.0-next.1 → 1.0.0-next.11

package/README.md

@@ -2,101 +2,42 @@
 
 **Build Cloudflare Workers like an application, not a pile of glue.**
 
-Devflare is a developer-first toolkit for Cloudflare Workers that sits on top of Miniflare and Wrangler-compatible config.
+Devflare is a developer-first layer on top of Cloudflare Workers, Miniflare, Bun, Vite, and Wrangler-compatible config.
 
 It gives you:
 
-- a clean file structure
 - typed config with `defineConfig()`
-- easier local development
-- great testing ergonomics
+- convention-friendly worker surfaces
+- local orchestration for multi-surface Worker apps
 - first-class Durable Object and multi-worker workflows
-- browser rendering support in local development
-- Vite and SvelteKit integration when your app grows up
+- test helpers that mirror real handler surfaces
+- worker-safe runtime helpers under `devflare/runtime`
+- optional Vite and SvelteKit integration when your package actually uses them
 
 Miniflare gives you a local runtime.
 
 Devflare turns that runtime into a **coherent development system**.
 
----
-
-## Why Devflare?
-
-Cloudflare development gets messy fast.
-
-You start with one Worker, then suddenly you have:
-
-- HTTP routes
-- queues
-- scheduled jobs
-- email handlers
-- Durable Objects
-- service bindings
-- framework output
-- test setup that no longer resembles runtime
-
-Devflare keeps those responsibilities isolated and composable.
-
-Instead of one giant worker file, you get a structure like this:
-
-```text
-.
-├── devflare.config.ts
-├── env.d.ts
-├── src/
-│   ├── fetch.ts
-│   ├── queue.ts
-│   ├── scheduled.ts
-│   ├── email.ts
-│   ├── routes/
-│   ├── do.counter.ts
-│   ├── ep.admin.ts
-│   └── transport.ts
-└── tests/
-    └── worker.test.ts
-```
-
-That structure is one of Devflare’s biggest strengths: **separate responsibilities, fewer surprises**.
-
----
-
-## What makes it different from plain Miniflare?
-
-Devflare does not replace Miniflare.
-
-It **extends** it.
-
-Miniflare gives you local execution.
-Devflare adds the developer workflow around it:
-
-- convention-first file discovery
-- config compilation to Wrangler-compatible output
-- unified test helpers for `fetch`, `queue`, `scheduled`, `email`, and `tail`
-- typed cross-worker references with `ref()`
-- local orchestration for multi-surface Worker apps
-- browser rendering support in local development
-- framework-aware integration for Vite and SvelteKit
-
-In short:
-
-> Devflare helps you build Cloudflare systems with clear boundaries and smooth local development.
+For the deeper public contract, caveats, and current feature boundaries, see [`LLM.md`](./LLM.md).
 
 ---
 
 ## Install
 
-For a typical project, install Devflare and Wrangler as dev dependencies:
+For a worker-only project, Devflare works fine with just the Worker toolchain:
 
 ```bash
-bun add -d devflare wrangler
+bun add -d devflare wrangler @cloudflare/workers-types
 ```
 
-If you are using Vite integration, also install the Vite plugin dependencies:
+If the current package also uses Vite, add Vite and the Cloudflare Vite plugin too:
 
 ```bash
-bun add -d vite @cloudflare/vite-plugin
+bun add -d devflare wrangler @cloudflare/workers-types vite @cloudflare/vite-plugin
 ```
 
+A local `vite.config.*` opts that package into Vite-backed flows. Without one, Devflare stays in worker-only mode.
+
 ---
 
 ## Quick start
@@ -108,7 +49,11 @@ bun add -d vite @cloudflare/vite-plugin
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'hello-worker'
+	name: 'hello-worker',
+	compatibilityDate: '2026-03-17',
+	files: {
+		fetch: 'src/fetch.ts'
+	}
 })
 ```
 
@@ -116,8 +61,15 @@ export default defineConfig({
 
 ```ts
 // src/fetch.ts
-export default async function fetch(): Promise<Response> {
-	return new Response('Hello from Devflare')
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function fetch({ request }: FetchEvent): Promise<Response> {
+	const url = new URL(request.url)
+	return new Response(
+		url.pathname === '/'
+			? 'Hello from Devflare'
+			: `Hello from Devflare: ${url.pathname}`
+	)
 }
 ```
 
@@ -127,7 +79,7 @@ export default async function fetch(): Promise<Response> {
 bunx --bun devflare types
 ```
 
-This creates `env.d.ts` so your bindings and entrypoints stay typed.
+This generates `env.d.ts` so bindings, secrets, and discovered entrypoints stay typed.
 
 ### 4. Start development
 
@@ -157,477 +109,348 @@ describe('hello-worker', () => {
 
 ---
 
-## The Devflare way to structure an app
-
-Devflare works best when each concern lives in its own file.
+## Package entrypoints
 
-### Common files
+Use subpaths intentionally.
 
-| File | Purpose |
+| Import | Use for |
 |---|---|
-| `src/fetch.ts` | HTTP requests |
-| `src/queue.ts` | queue consumers |
-| `src/scheduled.ts` | cron handlers |
-| `src/email.ts` | email handlers |
-| `src/routes/**` | file-based routing |
-| `do.*.ts` | Durable Objects |
-| `ep.*.ts` | named WorkerEntrypoints |
-| `wf.*.ts` | workflows |
-| `src/transport.ts` | custom serialization across boundaries |
-
-This is more than style.
+| `devflare` | main package entrypoint: config helpers, `ref()`, unified `env`, bridge helpers, CLI helpers, decorators |
+| `devflare/runtime` | worker-safe runtime helpers like `env`, `ctx`, `event`, `locals`, event types/getters, middleware helpers |
+| `devflare/test` | `createTestContext`, `cf.*`, mock helpers, bridge test context, skip helpers |
+| `devflare/vite` | Vite integration |
+| `devflare/sveltekit` | SvelteKit integration |
+| `devflare/cloudflare` | Cloudflare account/auth/usage/limits/preferences helpers |
+| `devflare/decorators` | decorators only |
 
-It is how Devflare helps you keep local development, testing, and runtime behavior aligned.
+### Runtime import rule of thumb
 
----
-
-## Example config
+- use `import { env } from 'devflare/runtime'` for **strict request-scoped runtime access**
+- use `import { env } from 'devflare'` when you want the **unified proxy** that can fall back to test or bridge context outside a live request
 
-```ts
-import { defineConfig } from 'devflare'
-
-export default defineConfig({
-	name: 'my-app',
-	files: {
-		routes: {
-			dir: 'src/routes',
-			prefix: '/api'
-		}
-	},
-	bindings: {
-		kv: {
-			CACHE: 'cache-kv-id'
-		},
-		d1: {
-			DB: 'db-id'
-		},
-		durableObjects: {
-			COUNTER: 'Counter'
-		},
-		queues: {
-			producers: {
-				TASK_QUEUE: 'task-queue'
-			}
-		},
-		browser: {
-			binding: 'BROWSER'
-		}
-	},
-	triggers: {
-		crons: ['0 */6 * * *']
-	}
-})
-```
+The reduced worker-safe main entry for `devflare` is selected through the package `browser` export condition. `devflare/runtime` is the direct worker-safe runtime subpath.
 
 ---
 
-## Routing without the giant switch statement
+## Event-first handlers
 
-As your HTTP surface grows, you do not need to keep stuffing logic into `fetch.ts`.
+Fresh Devflare code should be event-first:
 
-Use file-based routing instead:
+- `fetch(event: FetchEvent)`
+- `queue(event: QueueEvent)`
+- `scheduled(event: ScheduledEvent)`
+- `email(event: EmailEvent)`
+- Durable Object lifecycle handlers with their matching event types
 
-```ts
-import { defineConfig } from 'devflare'
+Devflare stores the active event in `AsyncLocalStorage`, and Devflare-managed entrypoints establish that context for you before your handler runs. That includes generated worker wrappers, the local dev server, and `createTestContext()` helper surfaces.
 
-export default defineConfig({
-	name: 'my-api',
-	files: {
-		routes: {
-			dir: 'src/routes',
-			prefix: '/api'
-		}
-	}
-})
-```
+Helpers deeper in the same call trail can recover the current surface with getters like:
 
-This lets your app grow naturally while keeping each endpoint focused and easy to maintain.
+- `getFetchEvent()`
+- `getQueueEvent()`
+- `getScheduledEvent()`
+- `getEmailEvent()`
+- `getDurableObjectFetchEvent()`
 
----
+Every getter also exposes `.safe()`, which returns `null` instead of throwing.
 
-## Queues without extra glue
+In normal app code you should not need to call `runWithEventContext()` or `runWithContext()` yourself.
 
-Devflare gives queues a natural place in your app:
+---
 
-- produce messages from `fetch` or other handlers
-- consume them in `src/queue.ts`
-- test them with `cf.queue`
+## HTTP structure that matches the runtime today
 
-```ts
-// devflare.config.ts
-import { defineConfig } from 'devflare'
+The built-in HTTP story now has **two cooperating layers**:
 
-export default defineConfig({
-	name: 'tasks-app',
-	bindings: {
-		queues: {
-			producers: {
-				TASK_QUEUE: 'task-queue'
-			},
-			consumers: [
-				{
-					queue: 'task-queue',
-					maxBatchSize: 10,
-					maxRetries: 3
-				}
-			]
-		},
-		kv: {
-			RESULTS: 'results-kv-id'
-		}
-	}
-})
-```
+1. an optional global fetch module at `src/fetch.ts`
+2. a built-in file router rooted at `src/routes/**`
 
-```ts
-// src/fetch.ts
-import { env } from 'devflare'
+Use `src/fetch.ts` for request-wide middleware and whole-app HTTP concerns.
+Use `src/routes/**` for leaf handlers.
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
+### Request-wide middleware
 
-	if (url.pathname === '/tasks') {
-		const task = {
-			id: crypto.randomUUID(),
-			type: 'resize-image'
-		}
+Use `sequence(...)` with a single exported primary fetch entry:
 
-		await env.TASK_QUEUE.send(task)
-		return Response.json({ queued: true, task })
+```ts
+import { sequence } from 'devflare/runtime'
+import type { FetchEvent, ResolveFetch } from 'devflare/runtime'
+
+async function corsHandle(event: FetchEvent, resolve: ResolveFetch): Promise<Response> {
+	if (event.request.method === 'OPTIONS') {
+		return new Response(null, {
+			headers: {
+				'Access-Control-Allow-Origin': '*',
+				'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+				'Access-Control-Allow-Headers': 'Content-Type, Authorization'
+			}
+		})
 	}
 
-	return new Response('Not found', { status: 404 })
+	const response = await resolve(event)
+	const next = new Response(response.body, response)
+	next.headers.set('Access-Control-Allow-Origin', '*')
+	return next
 }
-```
-
-```ts
-// src/queue.ts
-import type { MessageBatch } from '@cloudflare/workers-types'
 
-type Task = {
-	id: string
-	type: string
+async function appFetch({ request }: FetchEvent): Promise<Response> {
+	return Response.json({ path: new URL(request.url).pathname })
 }
 
-export default async function queue(
-	batch: MessageBatch<Task>,
-	env: DevflareEnv
-): Promise<void> {
-	for (const message of batch.messages) {
-		try {
-			await env.RESULTS.put(
-				`result:${message.body.id}`,
-				JSON.stringify({ status: 'completed', type: message.body.type })
-			)
-			message.ack()
-		} catch {
-			message.retry()
-		}
-	}
-}
+export const handle = sequence(corsHandle, appFetch)
 ```
 
----
+Important rules:
 
-## Email
+- `fetch` and `handle` are two names for the same primary HTTP entry
+- export **one** of them from a given module, never both
+- if `src/fetch.ts` exports same-module `GET()` / `POST()` handlers, those run before file routes for matching methods
+- for route-tree apps, keep `src/fetch.ts` focused on request-wide middleware and put leaf handlers in `src/routes/**`
 
-Devflare supports two sides of email: **receiving** incoming messages and **sending** outgoing ones.
+### File router
 
-### Receiving email
+`src/routes/**` is now a real built-in router.
 
-Export an `email` function from `src/email.ts`. Devflare wires it as the worker's incoming email handler automatically.
+By default, Devflare discovers `src/routes/**` automatically when that directory exists.
 
-```ts
-// src/email.ts
-import { env } from 'devflare'
-import type { ForwardableEmailMessage } from '@cloudflare/workers-types'
-
-export async function email(message: ForwardableEmailMessage): Promise<void> {
-	const id = crypto.randomUUID()
-
-	// Log the email to KV for later inspection
-	await env.EMAIL_LOG.put(
-		`email:${id}`,
-		JSON.stringify({
-			from: message.from,
-			to: message.to,
-			receivedAt: new Date().toISOString()
-		})
-	)
+You can customize or disable it with `files.routes`:
 
-	// Forward to an admin address
-	await message.forward(env.FORWARD_ADDRESS)
+```ts
+export default {
+	name: 'api-worker',
+	files: {
+		fetch: 'src/fetch.ts',
+		routes: {
+			dir: 'src/routes',
+			prefix: '/api'
+		}
+	}
 }
 ```
 
-You can also auto-reply with `message.reply(replyMessage)` — useful for sending confirmation receipts.
+- `files.routes.dir` changes the route root
+- `files.routes.prefix` mounts the route tree under a fixed prefix
+- `files.routes: false` disables automatic route discovery entirely
 
-### Sending email
+Route conventions:
 
-To send outgoing email, declare a `sendEmail` binding. Each key becomes an `env` property of type `SendEmail`.
+- `src/routes/index.ts` → `/`
+- `src/routes/users/index.ts` → `/users`
+- `src/routes/users/[id].ts` → `/users/:id`
+- `src/routes/blog/[...slug].ts` → `/blog/*` with `params.slug = 'a/b'`
+- `src/routes/docs/[[...slug]].ts` → optional catch-all, including `/docs`
+- files or directories that start with `_` are ignored so you can keep route-local helpers nearby
 
-The value is a config object that accepts an optional `destinationAddress`. When set, every email sent through that binding goes to that address. When omitted (`{}`), you specify the recipient at send time.
+Route module exports use the same fetch-module rules as `src/fetch.ts`:
 
-```ts
-// devflare.config.ts
-import { defineConfig } from 'devflare'
+- `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `ALL`
+- route-local `fetch(event)` / `handle(event, resolve)` if you want per-route middleware
+- `HEAD` falls back to `GET` when no explicit `HEAD` export exists
 
-export default defineConfig({
-	name: 'support-mail',
-	bindings: {
-		kv: {
-			EMAIL_LOG: 'email-log-kv-id'
-		},
-		sendEmail: {
-			// Locked to a specific recipient — every send goes to admin
-			ADMIN_EMAIL: { destinationAddress: 'admin@example.com' },
-
-			// Open — you choose the recipient per message
-			EMAIL: {}
-		}
-	}
-})
+Route params are available on `event.params`.
+
+```ts
+// src/routes/users/[id].ts
+export async function GET(event): Promise<Response> {
+	return Response.json({ id: event.params.id })
+}
 ```
 
-This generates two typed bindings on `env`:
+### Resolution order
 
-- `env.ADMIN_EMAIL` — always delivers to `admin@example.com`
-- `env.EMAIL` — you provide the destination when composing the message
+When a request comes in, Devflare resolves HTTP in this order:
 
-### Testing email
+1. create the initial fetch event and populate `event.params` from the matched file route, if any
+2. run the primary `src/fetch.ts` `fetch` / `handle` export if present
+3. inside `resolve(event)`, try same-module method handlers from `src/fetch.ts`
+4. if no same-module handler matched, dispatch to the matched route module from `src/routes/**`
+5. return `404 Not Found` if nothing matched
 
-Import the `email` helper from `devflare/test` to send test messages to your running dev server:
+That means global middleware can see `event.params`, while route files remain the main leaf-handler story.
+
+For example:
 
 ```ts
-import { email } from 'devflare/test'
+// src/fetch.ts
+import { sequence } from 'devflare/runtime'
 
-const response = await email.send({
-	from: 'sender@example.com',
-	to: 'recipient@example.com',
-	subject: 'Hello from devflare',
-	body: 'This is a test email.'
+export const handle = sequence(async (event, resolve) => {
+	const response = await resolve(event)
+	const next = new Response(response.body, response)
+	next.headers.set('x-user-id', event.params.id ?? 'none')
+	return next
 })
-
-expect(response.ok).toBe(true)
 ```
 
 ---
 
-## Durable Objects and multi-worker setups
+## Config highlights
 
-Devflare makes advanced Worker architecture feel much less dramatic.
+Devflare looks for these config filenames:
 
-### Local Durable Objects
+- `devflare.config.ts`
+- `devflare.config.mts`
+- `devflare.config.js`
+- `devflare.config.mjs`
 
-```ts
-bindings: {
-	durableObjects: {
-		COUNTER: 'Counter'
-	}
-}
-```
-
-Place the class in a `do.*.ts` file and Devflare handles the discovery flow.
+The most important top-level keys are:
 
-### Write a Durable Object and call it from `fetch`
+- `name`
+- `accountId`
+- `compatibilityDate`
+- `compatibilityFlags`
+- `files`
+- `bindings`
+- `triggers`
+- `vars`
+- `secrets`
+- `routes`
+- `wsRoutes`
+- `assets`
+- `limits`
+- `observability`
+- `migrations`
+- `rolldown`
+- `vite`
+- `env`
+- `wrangler.passthrough`
 
-This is the most common pattern:
+### `vars` vs `secrets`
 
-```ts
-// devflare.config.ts
-import { defineConfig } from 'devflare'
-
-export default defineConfig({
-	name: 'sessions-app',
-	bindings: {
-		durableObjects: {
-			SESSION: 'SessionStore'
-		}
-	}
-})
-```
+Keep these separate:
 
-```ts
-// src/do.session.ts
-import { DurableObject } from 'cloudflare:workers'
+- `vars` are **string-valued config bindings** that compile into generated Wrangler config
+- `secrets` are **declarations of expected runtime secret bindings**
 
-export class SessionStore extends DurableObject<DevflareEnv> {
-	private data = new Map<string, string>()
+`loadConfig()` does **not** do dotenv loading by itself.
 
-	getValue(key: string): string | null {
-		return this.data.get(key) ?? null
-	}
+When you run the CLI under Bun, Bun may already have loaded `.env` values into `process.env` before your config executes.
 
-	setValue(key: string, value: string): void {
-		this.data.set(key, value)
-	}
+Important boundary:
 
-	clearAll(): void {
-		this.data.clear()
-	}
-}
-```
+- `.env*` files are config/build-time inputs only insofar as the surrounding host tool has already populated `process.env`
+- Devflare does **not** currently provide a first-class `.dev.vars*` loader for worker-only dev mode or `createTestContext()`
+- example files like `.env.example` and `.dev.vars.example` are a team convention, not a Devflare feature
 
-```ts
-// src/fetch.ts
-import { env } from 'devflare'
+Practical convention:
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
-	const sessionId = url.searchParams.get('session') ?? 'default'
+- use `.env.example` for config-time/build-time variables read from `process.env`
+- use `.dev.vars.example` only if your project intentionally relies on upstream `.dev.vars` local-runtime workflows
 
-	const id = env.SESSION.idFromName(sessionId)
-	const session = env.SESSION.get(id)
+### `config.env`
 
-	if (url.pathname === '/set') {
-		const key = url.searchParams.get('key') ?? 'name'
-		const value = url.searchParams.get('value') ?? 'Arthur'
-		await session.setValue(key, value)
-		return Response.json({ ok: true })
-	}
+`config.env` is a Devflare merge layer, not a raw Wrangler env mirror.
 
-	if (url.pathname === '/get') {
-		const key = url.searchParams.get('key') ?? 'name'
-		const value = await session.getValue(key)
-		return Response.json({ value })
-	}
+When you select `--env name`, Devflare merges `config.env[name]` into the base config before compiling.
 
-	if (url.pathname === '/clear') {
-		await session.clearAll()
-		return Response.json({ ok: true })
-	}
+### Native config vs Wrangler coverage
 
-	return new Response('Not found', { status: 404 })
-}
-```
+Devflare natively models the Worker config it actively composes around:
 
-The flow is simple:
+- handler/file surfaces
+- core bindings and service composition
+- routes, assets, migrations, observability, and limits
+- Vite and Rolldown metadata
+- environment overlays
 
-1. bind the Durable Object in `devflare.config.ts`
-2. implement the class in a `do.*.ts` file
-3. get a stub with `env.SESSION.get(env.SESSION.idFromName(...))`
-4. call your methods from `fetch`
+It does **not** try to re-model every Wrangler key as a first-class Devflare schema field.
+For unsupported Wrangler options, use `wrangler.passthrough`.
 
-### Cross-worker references
+Current compile order is:
 
-Use `ref()` when one worker depends on another worker or its entrypoints/DO bindings:
+1. Devflare compiles native config into Wrangler-compatible output
+2. `wrangler.passthrough` is shallow-merged on top
+3. if the same key exists in both places, the passthrough value wins
 
 ```ts
-import { defineConfig, ref } from 'devflare'
-
-const authWorker = ref(() => import('../auth/devflare.config'))
-
 export default defineConfig({
-	name: 'gateway',
-	bindings: {
-		services: {
-			AUTH: authWorker.worker
+	name: 'advanced-worker',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	wrangler: {
+		passthrough: {
+			placement: {
+				mode: 'smart'
+			}
 		}
 	}
 })
 ```
 
-Typed relationships, less duplication, fewer paper cuts.
+Special case: `wrangler.passthrough.main` tells higher-level `build`, `deploy`, and `devflare/vite` flows to stop generating a composed `.devflare/worker-entrypoints/main.ts` and use your explicit main entry instead.
 
 ---
 
-## Transport for custom types, without manual serialization
+## Bindings
 
-Sometimes your Worker or Durable Object wants to return a real class instance, not just plain JSON.
+Devflare natively models:
 
-That is what `src/transport.ts` is for.
-
-You define how to encode and decode a custom type **once**, and Devflare applies it for you across supported boundaries.
-
-```ts
-// src/DoubleableNumber.ts
-export class DoubleableNumber {
-	value: number
+- KV
+- D1
+- R2
+- Durable Objects
+- Queues
+- Services
+- AI
+- Vectorize
+- Hyperdrive
+- Browser Rendering
+- Analytics Engine
+- `sendEmail`
 
-	constructor(n: number) {
-		this.value = n
-	}
+### Caveats worth knowing up front
 
-	get double() {
-		return this.value * 2
-	}
-}
-```
+- KV, D1, R2, Durable Objects, queues, and the core test/runtime flow are the strongest surfaces
+- AI and Vectorize are remote-oriented bindings
+- named service entrypoints are modeled at the Devflare layer, but validate generated deployment output if they are critical to your app
+- `sendEmail` is modeled through config compilation, generated env types, and local runtime/test flows
+- R2 bindings are real in local dev/test/runtime flows, but Devflare does **not** publish a stable browser-facing local bucket URL contract; browser-visible local asset flows should go through your Worker routes
 
-```ts
-// src/transport.ts
-import { DoubleableNumber } from './DoubleableNumber'
+For R2 delivery strategy guidance, see [`R2.md`](./R2.md).
 
-export const transport = {
-	DoubleableNumber: {
-		encode: (v: unknown) => v instanceof DoubleableNumber && v.value,
-		decode: (v: number) => new DoubleableNumber(v)
-	}
-}
-```
-
-```ts
-// src/do.counter.ts
-import { DoubleableNumber } from './DoubleableNumber'
-
-export class Counter {
-	private count = 0
-
-	increment(n: number = 1): DoubleableNumber {
-		this.count += n
-		return new DoubleableNumber(this.count)
-	}
-}
-```
+---
 
-```ts
-// tests/counter.test.ts
-import { beforeAll, afterAll, expect, test } from 'bun:test'
-import { createTestContext } from 'devflare/test'
-import { env } from 'devflare'
-import { DoubleableNumber } from '../src/DoubleableNumber'
+## Dev, build, deploy, Vite, and Rolldown
 
-beforeAll(() => createTestContext())
-afterAll(() => env.dispose())
+Devflare is worker-only first.
 
-test('transport restores my custom type', async () => {
-	const id = env.COUNTER.idFromName('main')
-	const counter = env.COUNTER.get(id)
-	const result = await counter.increment(2)
+### Mode selection
 
-	expect(result).toBeInstanceOf(DoubleableNumber)
-	expect(result.double).toBe(4)
-})
-```
+- a local `vite.config.*` opts the current package into **Vite-backed** flows
+- Vite-related dependencies without a local config do **not** switch the package into Vite mode
+- without a local `vite.config.*`, `dev`, `build`, and `deploy` stay in **worker-only** mode
 
-The important bit: **you do not manually encode before returning or manually decode after receiving**.
+### Mental model
 
-Devflare handles the transport step so the developer works with the real type again.
+Vite and Rolldown both matter here, but they do different jobs:
 
----
+- **Vite** is the optional outer app/framework host. Devflare only enters Vite-backed mode when the current package has a local `vite.config.*`, and then Devflare plugs Worker-aware config, auxiliary DO workers, and Cloudflare/Vite interop into that pipeline.
+- **Rolldown** is the inner builder Devflare uses when Devflare itself needs to transform Worker code into runnable bundles. Today that matters most in the Durable Object path and its watch/rebuild loop.
 
-## Testing that feels like the real app
+Short version:
 
-Devflare ships a clean testing API through `devflare/test`.
+- no local `vite.config.*` → no Vite process; Devflare stays worker-only
+- `.svelte` imported by a Durable Object → that compilation belongs to the Rolldown plugin pipeline, not to the main Vite app build
+- generated `.devflare/worker-entrypoints/main.ts` is separate Devflare glue that composes worker surfaces when needed
 
-### Integration-style tests
+### Current behavior that matters
 
-Use `createTestContext()` for real local behavior backed by Devflare’s Miniflare orchestration.
+- worker-only `dev` is a real first-class path
+- `build` and `deploy` skip Vite when the current package has no local `vite.config.*`
+- higher-level `build`, `deploy`, and `devflare/vite` flows currently synthesize `.devflare/worker-entrypoints/main.ts` whenever a fetch, route tree, queue, scheduled, or email surface is discovered
+- `wrangler.passthrough.main` disables that composed-entry generation path
+- Rolldown currently matters most in the Durable Object bundler path, including unified dev flows where Vite hosts the app but Rolldown still rebuilds DO worker code
 
-### Mock-style tests
+For the full contract-level explanation and a concrete Rolldown + Svelte example, see [`LLM.md`](./LLM.md).
 
-Use:
+---
 
-- `createMockTestContext()`
-- `withTestContext()`
-- `createMockKV()`
-- `createMockD1()`
-- `createMockR2()`
-- `createMockQueue()`
+## Testing
 
-### Unified handler helpers
+Use `devflare/test`.
 
-You can test each surface directly:
+The high-level entrypoint is `createTestContext()`, and the unified helper surface is `cf`:
 
 - `cf.worker`
 - `cf.queue`
@@ -635,56 +458,52 @@ You can test each surface directly:
 - `cf.email`
 - `cf.tail`
 
-That consistency is a huge quality-of-life improvement.
+### `createTestContext()` autodiscovery
 
----
+If you omit the config path, `createTestContext()` walks upward from the calling test file and looks for the nearest supported config filename:
 
-## Browser rendering, locally
+- `devflare.config.ts`
+- `devflare.config.mts`
+- `devflare.config.js`
+- `devflare.config.mjs`
 
-Browser rendering is a perfect example of Devflare adding capability above raw Miniflare.
+It also auto-detects conventional `src/fetch.ts`, `src/queue.ts`, `src/scheduled.ts`, `src/email.ts`, built-in `src/routes/**`, and `src/tail.ts` when they are present.
 
-With Devflare, browser rendering becomes part of the same local development story as the rest of your Worker bindings.
+### Important current testing truth
 
-That means you can build richer Worker applications without stitching together a separate custom local browser setup by hand.
-
----
-
-## Framework support
-
-### `devflare/vite`
-
-Use this when you want:
-
-- config compilation during dev and build
-- worker-aware transforms
-- auxiliary Durable Object worker generation
-- websocket-aware local development
-
-### `devflare/sveltekit`
-
-Use this when your project needs:
-
-- a Devflare-aware platform layer
-- smooth SvelteKit + Worker binding integration
-- local development that still behaves like a coherent Worker system
+- `cf.worker.fetch()` returns when the handler resolves and does **not** eagerly wait for all `waitUntil()` work
+- `cf.worker.fetch()` and the shorthand helpers dispatch through both `src/fetch.ts` and built-in `src/routes/**` file routes when present
+- `cf.queue.trigger()` and `cf.scheduled.trigger()` do wait for queued background work before they return
+- `cf.tail.trigger()` is exported, and `createTestContext()` auto-detects `src/tail.ts` when present; there is still no public `files.tail` config key
+- `cf.email.send()` invokes the configured email handler in `createTestContext()`-backed tests and otherwise falls back to the local email endpoint; for ingress-fidelity-sensitive flows, validate with a higher-level integration test
+- remote mode is mainly about AI and Vectorize, not “make every binding remote”
 
 ---
 
 ## CLI
 
-Devflare includes a CLI for the full development loop.
-
-```text
-devflare init
-devflare dev
-devflare build
-devflare deploy
-devflare types
-devflare doctor
-devflare remote
-```
-
-Most projects will mainly use:
+| Command | What it does |
+|---|---|
+| `devflare init` | scaffold a project using `src/fetch.ts` and explicit `files.fetch` |
+| `devflare dev` | start the worker-only dev server, enabling Vite only when the current package has a local `vite.config.*` |
+| `devflare build` | resolve config, generate `wrangler.jsonc`, and run `vite build` only for Vite-backed packages |
+| `devflare deploy` | build and deploy with Wrangler |
+| `devflare types` | generate `env.d.ts` |
+| `devflare doctor` | check project configuration and generated artifacts |
+| `devflare account` | inspect accounts, resources, usage, and limits |
+| `devflare ai` | show Workers AI model pricing info |
+| `devflare remote` | manage remote test mode |
+
+Useful flags:
+
+- `build --env <name>`
+- `deploy --env <name>`
+- `deploy --dry-run`
+- `types --output <path>`
+- `doctor --config <path>`
+- `account --account <id>`
+
+Recommended invocation style:
 
 ```bash
 bunx --bun devflare dev
@@ -694,44 +513,22 @@ bunx --bun devflare build
 
 ---
 
-## A good starter layout
-
-```text
-.
-├── devflare.config.ts
-├── env.d.ts
-├── src/
-│   ├── fetch.ts
-│   ├── routes/
-│   ├── queue.ts
-│   ├── scheduled.ts
-│   ├── email.ts
-│   ├── do.counter.ts
-│   ├── ep.admin.ts
-│   └── transport.ts
-└── tests/
-    └── worker.test.ts
-```
-
-Not every project needs every file.
+## Generated artifacts
 
-But if you follow this shape, Devflare will feel very natural.
-
----
+Treat these as generated output, not source of truth:
 
-## When to use Devflare
+- `.devflare/`
+- `env.d.ts`
+- generated `wrangler.jsonc`
 
-Devflare is especially nice when you want:
+The source of truth is still:
 
-- Cloudflare Workers with clean project structure
-- Durable Object-heavy apps
-- multi-worker systems with service bindings
-- local-first development with realistic tests
-- browser rendering in your local workflow
-- Vite or SvelteKit apps that still want a clean Worker model
+- `devflare.config.ts`
+- your source files under `src/`
+- your tests
 
 ---
 
 ## In one sentence
 
-**Devflare helps you build Cloudflare Workers with clearer structure, better local tooling, and a development experience that scales with your app.**
+**Devflare helps you build Cloudflare Workers with clearer structure, better local tooling, and a development workflow that stays coherent as the app grows.**