@junejs/server 0.0.17 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -30,19 +30,18 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@junejs/core": "0.0.17",
-    "@junejs/db": "0.0.17",
+    "@junejs/core": "0.0.19",
+    "@junejs/db": "0.0.19",
     "marked": "^18.0.5",
     "rolldown": "^1.1.0",
-    "postcss": "^8.4.0",
-    "postcss-modules": "^6.0.0",
     "lightningcss": "^1.27.0"
   },
   "peerDependencies": {
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "pg": "^8.0.0",
-    "mysql2": "^3.0.0"
+    "mysql2": "^3.0.0",
+    "@libsql/client": "^0.14.0 || ^0.15.0 || ^0.16.0 || ^0.17.0"
   },
   "peerDependenciesMeta": {
     "pg": {
@@ -50,6 +49,9 @@
     },
     "mysql2": {
       "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
     }
   },
   "repository": {
@@ -57,6 +59,7 @@
     "url": "https://github.com/junebuild/june"
   },
   "devDependencies": {
+    "@libsql/client": "^0.17.3",
     "@types/pg": "^8.20.0",
     "mysql2": "^3.22.5",
     "pg": "^8.21.0"

package/src/adapter.ts

@@ -143,14 +143,14 @@ export function workers(opts?: { name?: string; domain?: string }): JuneAdapter
 // deprecated the Edge Functions *product* and officially recommends the Node
 // runtime for performance + reliability, and Fluid compute (in-function
 // concurrency) closed the cold-start gap edge used to win on. Node also lifts
-// edge's limits (no 1–4MB code cap, full API) and is the substrate a future
-// HTTP/TCP db backend (Neon/Turso) needs. `vercel({ runtime: "edge" })` still
+// edge's limits (no 1–4MB code cap, full API). `vercel({ runtime: "edge" })` still
 // emits an Edge Function for latency-critical global cases — the runtime is not
 // removed, just discouraged. BOTH run the SAME bundle; only the .func packaging
 // (.vc-config.json + the export shape) differs.
 //
-// No db yet (D1 is Cloudflare-only) — declaring one still fails fast; the Node
-// runtime makes a real backend possible but it isn't wired here.
+// db: turso() works (libsql over HTTPS — the build bundles the web client, the
+// request opens it from env → ambient `import { db }`). sqlite()/d1() are
+// Cloudflare-only (a D1 binding); validate() rejects them with that guidance.
 //
 // Routing: only the hashed framework assets (/_june/*) are served statically by
 // the CDN (their exact-path URLs match June's scheme); every page + projection
@@ -176,12 +176,15 @@ export function vercel(opts?: { runtime?: "node" | "edge"; regions?: string[] })
     // and runs on workerd AND Node alike. Mirrors workers()'s shape.
     conditions: ["edge-light", "edge", "import", "default"],
 
-    validate({ plan }) {
-      if (plan.db) {
+    validate({ config }) {
+      // turso() is libsql over HTTPS — it runs on Vercel (the build bundles the web
+      // client; the request opens it from env → ambient `import { db }`). sqlite()/
+      // d1() need a D1 binding, which is Cloudflare-only.
+      const kind = config.resources?.db?.kind;
+      if (kind && kind !== "turso") {
         throw new Error(
-          "vercel(): the Vercel adapter has no db backend yet (D1 is Cloudflare-only).\n" +
-            "  Remove the `db` resource from june.config.ts, or deploy to Workers.\n" +
-            "  An HTTP-driver db (Neon/Turso) for Vercel is planned.",
+          `vercel(): the '${kind}' db isn't supported on Vercel (D1 is Cloudflare-only).\n` +
+            "  Use turso() (libsql over HTTPS) for a Vercel db, or deploy to Workers.",
         );
       }
     },

package/src/build.ts

@@ -378,12 +378,25 @@ export async function juneBuild(
     kv: !!resourcesCfg?.kv,
     blob: !!resourcesCfg?.blob,
   };
-  if (hasResources) {
+  // Two SQLite-dialect defaults, picked by the declared db's kind:
+  //   turso()         → libsql over HTTPS, connected from env (TURSO_*) via the
+  //                     bundled web client. Open the declared factory directly so it
+  //                     feeds the ambient `import { db }` scope (re-emitted by kind,
+  //                     not imported from the app config, to avoid the host barrel).
+  //   sqlite()/d1()   → a D1 binding from env (env.DB), via bindWorkerResources.
+  // (kv/blob on a turso deploy aren't wired yet — db-only.)
+  const tursoDb = resourcesCfg?.db?.kind === "turso";
+  if (tursoDb) {
+    imports.push(`import { turso } from "@junejs/server/db";`);
+    imports.push(`import { memoizeResources } from "@junejs/server/resources";`);
+  } else if (hasResources) {
     imports.push(`import { bindWorkerResources } from "@junejs/server/resources";`);
   }
-  const resourcesField = hasResources
-    ? `\n  resources: bindWorkerResources(${JSON.stringify(resourceFlags)}),`
-    : "";
+  const resourcesField = tursoDb
+    ? `\n  resources: memoizeResources({ db: turso() }),`
+    : hasResources
+      ? `\n  resources: bindWorkerResources(${JSON.stringify(resourceFlags)}),`
+      : "";
 
   // Opt-in Tier-3 data layer: import its installDataLayer from the declared module
   // and call it at worker boot — the prod twin of the dev host's dataLayer.install()
@@ -521,10 +534,12 @@ ${adapterEntry.wrap("pipeline")}
     ? (JSON.parse(await Bun.file(pkgPath).text()) as { name?: string }).name
     : undefined;
   const defaultName = (pkgName ?? basename(appRoot)).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
-  // A declared `db` → a D1 binding named DB (the name bindWorkerResources reads).
-  const plan: ResourcePlan = resourcesCfg?.db
-    ? { db: { binding: "DB", databaseName: `${defaultName}-db` } }
-    : {};
+  // A declared D1-backed db (sqlite/d1) → a D1 binding named DB (the name
+  // bindWorkerResources reads). turso() connects from env, not a binding — no plan.
+  const plan: ResourcePlan =
+    resourcesCfg?.db && resourcesCfg.db.kind !== "turso"
+      ? { db: { binding: "DB", databaseName: `${defaultName}-db` } }
+      : {};
   await adapter.emit({ appRoot, outDir, hasAssets, linkHeader, config: fullConfig, plan, defaultName });
   if (plan.db) {
     console.log(

package/src/css-modules.ts

@@ -3,22 +3,21 @@
 //
 // The hard constraint: the scoped names must be byte-identical in dev SSR
 // (un-bundled import), the worker build, and the client build (hydration must
-// match SSR). We guarantee that by NEVER deriving the name from a bundler
-// internal — `scopedName(stableKey, class)` is a pure hash of an app-relative
-// path + the class. One main-thread pass globs + transforms every .module.css
-// into a maps dict; the Bun plugin / Node loader / rolldown plugin are then dumb
-// lookups into it, and the served/emitted CSS comes from the SAME pass — so the
-// JS maps and the CSS agree by construction.
+// match SSR). One main-thread pass globs + transforms every .module.css into a
+// maps dict; the Bun plugin / Node loader / rolldown plugin are then dumb lookups
+// into it, and the served/emitted CSS comes from the SAME pass — so the JS maps
+// and the CSS agree by construction. Names stay machine-independent because the
+// transform is keyed on an APP-RELATIVE path (stableKey), not an absolute one.
 //
-// Transforms go through postcss-modules, so the full CSS-Modules surface works:
-// local scoping (the default), `:global(...)`, and cross-file `composes`. The one
-// thing we override is generateScopedName — it's our deterministic hash, not a
-// bundler internal, which is what makes dev/build/client/Node agree.
+// Engine: Lightning CSS (Rust) — local scoping (default), `:global(...)`, and
+// cross-file `composes`. Unlike postcss-modules, Lightning resolves `composes` by
+// REFERENCE (it records the composed scoped name; it does NOT inline the rule), so
+// a class composed across N files lands ONCE in the sheet with no dedup pass.
+// Lightning is imported lazily and only runs at build/dev time, so it never enters
+// the worker graph.
 
-import { createHash } from "node:crypto";
 import { readFile, readdir } from "node:fs/promises";
-import { join, relative, sep } from "node:path";
-import type { AcceptedPlugin, ChildNode } from "postcss";
+import { dirname, join, relative, resolve as resolvePath, sep } from "node:path";
 
 export const MODULE_STYLES_URL = "/_june/modules.css";
 
@@ -29,35 +28,89 @@ export function stableKey(appRoot: string, file: string): string {
   return relative(appRoot, file).split(sep).join("/");
 }
 
-function scopedName(key: string, cls: string): string {
-  const h = createHash("sha256").update(`${key}|${cls}`).digest("hex").slice(0, 8);
-  return `${cls}_${h}`;
+// One `composes` entry, as Lightning reports it: a class in this file (local, already
+// scoped), a global class (unscoped, applied as-is), or a class in another module
+// file (dependency — resolved against that file's exports).
+type Compose =
+  | { type: "local"; name: string }
+  | { type: "global"; name: string }
+  | { type: "dependency"; name: string; specifier: string };
+type ModuleExports = Record<string, { name: string; composes: Compose[] }>;
+type Transformed = { css: string; exports: ModuleExports };
+
+// Lightning-transform ONE file: deterministic scoped CSS + its exports. Cross-file
+// `composes` come back as unresolved `dependency` refs — the caller resolves them.
+async function transformOne(file: string, appRoot: string): Promise<Transformed> {
+  const { transform } = await import("lightningcss");
+  const { code, exports } = transform({
+    // The STABLE app-relative path drives Lightning's [hash], so names are
+    // machine-independent and identical across dev / worker build / client build.
+    filename: stableKey(appRoot, file),
+    code: Buffer.from(await readFile(file, "utf8")),
+    cssModules: { pattern: "[local]_[hash]" },
+  });
+  return { css: code.toString(), exports: (exports ?? {}) as ModuleExports };
+}
+
+// Transform `entry` and (recursively) every file it composes from, into `all`.
+async function transformGraph(
+  entry: string,
+  appRoot: string,
+  all: Record<string, Transformed> = {},
+): Promise<Record<string, Transformed>> {
+  if (all[entry]) return all;
+  const t = await transformOne(entry, appRoot);
+  all[entry] = t;
+  for (const exp of Object.values(t.exports)) {
+    for (const c of exp.composes) {
+      if (c.type === "dependency") {
+        await transformGraph(resolvePath(dirname(entry), c.specifier), appRoot, all);
+      }
+    }
+  }
+  return all;
+}
+
+// The space-joined scoped class string for one local name, following composes:
+//   local → already scoped · global → as-is · dependency → the target file's name.
+function resolveName(
+  file: string,
+  local: string,
+  all: Record<string, ModuleExports>,
+  seen = new Set<string>(),
+): string {
+  const exp = all[file]?.[local];
+  if (!exp) return local; // not a module class (shouldn't happen) → pass through
+  const parts = [exp.name];
+  for (const c of exp.composes) {
+    if (c.type === "dependency") {
+      const target = resolvePath(dirname(file), c.specifier);
+      const k = `${target}::${c.name}`;
+      if (seen.has(k)) continue; // guard against circular composes
+      seen.add(k);
+      parts.push(resolveName(target, c.name, all, seen));
+    } else {
+      parts.push(c.name); // local (already scoped) or global (unscoped)
+    }
+  }
+  return parts.join(" ");
 }
 
-// Transform one .module.css via postcss-modules — correct scoping, `:global`,
-// `composes` (cross-file), and url()/string safety — but with OUR deterministic
-// generateScopedName, so dev SSR / worker build / client build / Node all produce
-// identical names. postcss is imported lazily and only runs at build/dev time, so
-// it never enters the worker graph.
+const exportsOnly = (all: Record<string, Transformed>): Record<string, ModuleExports> =>
+  Object.fromEntries(Object.entries(all).map(([f, t]) => [f, t.exports]));
+
+// Transform one .module.css (+ its composes deps) → its class map and scoped CSS.
+// The CSS is THIS file's rules only; composed rules live in their own files (and so
+// appear once in the combined sheet), never inlined here.
 export async function transformCssModule(
   file: string,
   appRoot: string,
 ): Promise<{ map: Record<string, string>; css: string }> {
-  const postcss = (await import("postcss")).default;
-  const postcssModules = (await import("postcss-modules")).default as (opts: {
-    generateScopedName(name: string, filename: string): string;
-    getJSON(file: string, json: Record<string, string>): void;
-  }) => AcceptedPlugin;
-  let map: Record<string, string> = {};
-  const result = await postcss([
-    postcssModules({
-      generateScopedName: (name, filename) => scopedName(stableKey(appRoot, filename), name),
-      getJSON: (_f, json) => {
-        map = json;
-      },
-    }),
-  ]).process(await readFile(file, "utf8"), { from: file });
-  return { map, css: result.css };
+  const all = await transformGraph(file, appRoot);
+  const exports = exportsOnly(all);
+  const map: Record<string, string> = {};
+  for (const local of Object.keys(all[file]!.exports)) map[local] = resolveName(file, local, exports);
+  return { map, css: all[file]!.css };
 }
 
 // The JS a .module.css import resolves to.
@@ -85,50 +138,33 @@ async function findModuleCss(dir: string): Promise<string[]> {
   return out.sort();
 }
 
-// Drop byte-identical top-level rules. postcss-modules has no module graph, so
-// `composes: x from "./y"` INLINES y's rule into this file's output — and we also
-// emit y directly, so a composed rule lands N+1 times. Vite never duplicates
-// (composes is a graph edge there); we get the same one-copy result by deduping.
-//
-// Two safety points:
-//  - Exact-string match only. Our scoped names are deterministic, so the copies
-//    are byte-identical; we never collapse two genuinely different rules.
-//  - Keep the LAST occurrence, not the first. With :global, two files can write
-//    the same raw selector with different bodies, so the cascade can interleave
-//    (red, blue, red). The winner is the last declaration; dropping the EARLIER
-//    identical copies leaves the last one in place, so the computed result is
-//    unchanged. Keeping the first instead would change which rule wins.
-async function dedupeRules(css: string): Promise<string> {
-  const postcss = (await import("postcss")).default;
-  const root = postcss.parse(css);
-  const last = new Map<string, ChildNode>();
-  root.each((node) => {
-    if (node.type === "rule" || node.type === "atrule") last.set(node.toString(), node);
-  });
-  root.each((node) => {
-    if ((node.type === "rule" || node.type === "atrule") && last.get(node.toString()) !== node) {
-      node.remove();
-    }
-  });
-  return root.toString();
-}
-
 // One pass over app/**/*.module.css → the per-file class maps AND the combined
 // scoped stylesheet. null css when there are none. Deterministic, so the maps the
-// loaders hand out match the CSS that's served/emitted.
+// loaders hand out match the CSS that's served/emitted. composes are references
+// (not inlined), so each rule appears once — no dedup pass.
 export async function buildModuleCss(
   appDir: string,
   appRoot: string,
 ): Promise<{ maps: ModuleMaps; css: string | null }> {
   const files = await findModuleCss(appDir);
+  if (!files.length) return { maps: {}, css: null };
+
+  const all: Record<string, Transformed> = {};
+  for (const file of files) await transformGraph(file, appRoot, all); // picks up out-of-glob deps too
+  const exports = exportsOnly(all);
+
   const maps: ModuleMaps = {};
-  const parts: string[] = [];
   for (const file of files) {
-    const { map, css } = await transformCssModule(file, appRoot);
-    maps[file] = map;
-    parts.push(css);
+    maps[file] = {};
+    for (const local of Object.keys(all[file]!.exports)) maps[file][local] = resolveName(file, local, exports);
   }
-  return { maps, css: parts.length ? await dedupeRules(parts.join("\n")) : null };
+  // Emit each transformed file's CSS once (sorted), so a composed rule — which lives
+  // in its own file — appears exactly once in the combined sheet.
+  const css = Object.keys(all)
+    .sort()
+    .map((f) => all[f]!.css)
+    .join("\n");
+  return { maps, css };
 }
 
 // --- the three dumb interception points (all lookups into `maps`) ------------

package/src/db.ts

@@ -1,35 +1,38 @@
 // `db` resource adapters — implementations of the @junejs/core JuneDb contract.
 // Declared in june.config.ts (`resources.db: sqlite(...)` / `d1(...)`), opened
-// by the host, injected onto RouteContext as `ctx.db`. The framework depends on
-// the JuneDb contract; these adapters (and Juno on top) are swappable.
+// by the host and made ambient (`import { db } from "@junejs/db"`, via
+// runInScope — NOT on ctx). The framework depends on the JuneDb contract; these
+// adapters (and Juno on top) are swappable.
 //
-// sqlite() is host-coupled (node:fs + ./host) and DEV-only. The edge-safe d1()
-// adapter lives in ./d1 so the generated worker can import it without dragging
-// this module's host imports into the workerd bundle; it is re-exported here so
-// `@junejs/server/db` stays the one place both db adapters are named.
-
-import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+// This module is HOST-FREE so the generated worker can import it (e.g. `turso`)
+// without dragging node:fs / the dev host into the bundle (reminder #4). The two
+// host-coupled adapters keep their host touch out of the static graph:
+//   - d1()    lives in ./d1 (edge-safe; env binding).
+//   - sqlite() is DEV-only and imports node:fs + ./host LAZILY, inside open().
+// All five (sqlite/d1/postgres/mysql/turso) are named from this one place.
 
 import type { DbFactory } from "@junejs/core/resources";
 
-import { host } from "./host";
-
 export { d1, type D1Database } from "./d1";
 export { postgres, pgJuneDb, type PgClientLike } from "./postgres-driver";
 export { mysql, mysqlJuneDb, type MysqlConnLike } from "./mysql-driver";
+export { turso, libsqlJuneDb, type LibsqlClientLike } from "./turso-driver";
 
 // Local SQLite — the zero-config dev default. A persistent FILE, not :memory:,
 // on purpose: `june dev` restarts the process on every save (the watch
 // supervisor), so an in-memory default would evaporate your dev data at each
 // edit. A file also makes the dev db inspectable with the sqlite3 every
 // machine already has (`sqlite3 .june/dev.sqlite`). Pass ":memory:" explicitly
-// for ephemerality.
+// for ephemerality. node:fs + ./host are imported lazily so this module stays
+// host-free (sqlite() only runs in dev, where the imports resolve).
 export function sqlite(opts: { path?: string } = {}): DbFactory {
   const path = opts.path ?? ".june/dev.sqlite";
   return {
     kind: "sqlite",
-    open: () => {
+    open: async () => {
+      const { mkdirSync } = await import("node:fs");
+      const { dirname } = await import("node:path");
+      const { host } = await import("./host");
       if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
       return host.openDb(path);
     },

package/src/host.ts

@@ -49,7 +49,7 @@ export interface JuneHost {
   // this with the in-isolate dual-graph loader; the seam stays for the fallback.
   spawnModule(entry: string, args: string[], opts: { conditions?: string[] }): SpawnedModule;
   // Open a LOCAL SQLite database — the internal primitive the `sqlite()` db
-  // adapter builds on (docs/data-layer-boundary.md: openDb is demoted from the
+  // adapter builds on (docs/data-layer.md: openDb is demoted from the
   // user-facing API to a host primitive; apps declare `resources.db` instead).
   openDb(path: string): Promise<JuneDb>;
 }

package/src/index.ts

@@ -11,7 +11,7 @@ export {
   type AdapterEmitContext,
 } from "./adapter";
 export { host, type JuneHost, type JuneDb, type RunResult, type ServeHandle, type SpawnedModule } from "./host";
-export { sqlite, d1, postgres, mysql, type D1Database } from "./db";
+export { sqlite, d1, postgres, mysql, turso, type D1Database } from "./db";
 export { memoryKv, redisKv } from "./kv";
 export { localBlob, r2, type R2Bucket } from "./blob";
 export {

package/src/kv.ts

@@ -1,4 +1,4 @@
-// `kv` resource adapters. The kv resource IS the cache (docs/data-layer-boundary
+// `kv` resource adapters. The kv resource IS the cache (docs/data-layer
 // .md: "reframe cache as the kv resource — it already is one"): these wrap
 // @junejs/core/cache's CacheStore (memory / redis) as the simpler JuneKv contract,
 // so there is ONE key-value system, surfaced both as cache() and as ambient kv.

package/src/resources.ts

@@ -1,7 +1,9 @@
 // Resource resolution — open the handles declared in june.config.ts `resources`
-// and hand them to the pipeline, which injects them onto RouteContext (ctx.db /
-// ctx.kv / ctx.blob). A resource not declared is never opened (and, for static
-// apps, tree-shaken out — the build freeze knows which routes touch resources).
+// and hand them to the pipeline, which runs each request inside runInScope() so
+// they resolve AMBIENTLY (`import { db } from "@junejs/db"`). ctx never carries
+// them — ctx is identity-only (see route.ts). A resource not declared is never
+// opened (and, for static apps, tree-shaken out — the build freeze knows which
+// routes touch resources).
 
 import type { ResourceConfig, Resources } from "@junejs/core/resources";
 
@@ -48,7 +50,7 @@ export type ResourceFlags = { db?: boolean; kv?: boolean; blob?: boolean };
 // from env (env.DB → D1) — the prod half of "sqlite dev → D1 prod, one
 // declaration": the same `resources: { db: sqlite() }` runs on D1 at the edge,
 // because D1 *is* SQLite (same SQL, same Juno tables). No env binding → the
-// handle is absent and the route degrades (ctx.db undefined), never a crash.
+// handle is absent and the route degrades (ambient `db` unavailable), never a crash.
 // Memoized per isolate (env is stable across requests in a workerd isolate).
 //
 // env is typed `unknown` (it arrives untyped from the runtime) and narrowed to

package/src/turso-driver.ts

@@ -0,0 +1,96 @@
+// Turso / libsql `db` adapter — implements the @junejs/core JuneDb contract over
+// @libsql/client. Turso speaks libsql (SQLite over an HTTPS endpoint), so it tags
+// itself `dialect: "sqlite"`: Juno compiles the exact same `?`-placeholder SQLite
+// SQL it uses for the local sqlite() adapter, and the connection is a plain URL +
+// token (no TCP socket, no platform binding) — so it runs on the Vercel Node
+// runtime, on edge, and anywhere with fetch. `@libsql/client` is dynamically
+// imported: a peer the app installs only when it declares turso(); the host never
+// hard-depends on it. Host-free (no node:* / ./host) so it can enter a worker
+// bundle, unlike sqlite().
+
+import type { DbFactory, JuneDb, RunResult } from "@junejs/core/resources";
+
+// The slice of @libsql/client's Client we depend on — so libsqlJuneDb is
+// unit-testable with a fake (no network).
+export interface LibsqlResultSet {
+  rows: unknown[];
+  rowsAffected: number;
+  lastInsertRowid?: bigint | number;
+}
+export interface LibsqlClientLike {
+  execute(stmt: { sql: string; args?: unknown[] } | string): Promise<LibsqlResultSet>;
+  executeMultiple?(sql: string): Promise<void>;
+  close(): void | Promise<void>;
+}
+
+// Wrap a libsql client as a JuneDb. Exported (not just the factory) so the mapping
+// — rows, first-row, RunResult, transaction ordering — is testable offline.
+export function libsqlJuneDb(client: LibsqlClientLike): JuneDb {
+  const self: JuneDb = {
+    dialect: "sqlite", // libsql IS sqlite — same SQL + Juno tables as sqlite()/d1()
+    async query<T>(sql: string, params: unknown[] = []) {
+      return (await client.execute({ sql, args: params })).rows as T[];
+    },
+    async get<T>(sql: string, params: unknown[] = []) {
+      return ((await client.execute({ sql, args: params })).rows[0] ?? undefined) as T | undefined;
+    },
+    async run(sql: string, params: unknown[] = []): Promise<RunResult> {
+      const r = await client.execute({ sql, args: params });
+      // libsql returns lastInsertRowid as a bigint; RunResult is number-ish.
+      return { changes: r.rowsAffected ?? 0, lastInsertRowid: Number(r.lastInsertRowid ?? 0) };
+    },
+    async exec(sql: string) {
+      // DDL / migrations are multi-statement; executeMultiple splits on `;`.
+      if (client.executeMultiple) await client.executeMultiple(sql);
+      else await client.execute(sql);
+    },
+    async transaction<T>(fn: (tx: JuneDb) => Promise<T>) {
+      // Test/dev grade, matching postgres()/mysql(): BEGIN/COMMIT on the one
+      // client. (For strict isolation over HTTP, libsql's interactive
+      // client.transaction() is the upgrade path.)
+      await client.execute("BEGIN");
+      try {
+        const out = await fn(self);
+        await client.execute("COMMIT");
+        return out;
+      } catch (e) {
+        await client.execute("ROLLBACK");
+        throw e;
+      }
+    },
+    async close() {
+      await client.close();
+    },
+  };
+  return self;
+}
+
+// `turso({ url, authToken })` — declared in june.config.ts, or omit both to read
+// the standard TURSO_DATABASE_URL / TURSO_AUTH_TOKEN env vars at open() time
+// (NOT at construction — so the build can evaluate the config without the secrets
+// present, and the deployed function reads them from its own environment).
+export function turso(opts: { url?: string; authToken?: string } = {}): DbFactory {
+  return {
+    kind: "turso",
+    open: async () => {
+      const url = opts.url ?? readEnv("TURSO_DATABASE_URL");
+      const authToken = opts.authToken ?? readEnv("TURSO_AUTH_TOKEN");
+      if (!url) {
+        throw new Error(
+          "turso(): no database url — pass { url } or set TURSO_DATABASE_URL in the environment.",
+        );
+      }
+      // The pure-fetch web client: works in dev (Bun) AND bundles into the one
+      // deployed function (the node client would pull native bindings). Turso is
+      // remote (libsql:// over HTTPS), which is exactly what the web client speaks.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const mod = (await import("@libsql/client/web")) as any;
+      const createClient = (mod.default ?? mod).createClient;
+      return libsqlJuneDb(createClient({ url, authToken }));
+    },
+  };
+}
+
+function readEnv(name: string): string | undefined {
+  return typeof process !== "undefined" && process.env ? process.env[name] : undefined;
+}