@lunora/vite 1.0.0-alpha.2 → 1.0.0-alpha.200

package/dist/index.d.mts

@@ -1,176 +1,230 @@
 import { CodegenOptions } from '@lunora/codegen';
 import errorOverlayPlugin from '@visulima/vite-overlay';
 import { Plugin } from 'vite';
-import { FrameworkDetection, DetectedFramework, materializeRemoteWranglerConfig, readProjectRemotePreference } from '@lunora/config';
+import { FrameworkDetection, DetectedFramework, readProjectRemotePreference } from '@lunora/config';
 export { type DetectedFramework, type FrameworkClass, type FrameworkDetection, detectFramework } from '@lunora/config';
+import { materializeRemoteWranglerConfig } from '@lunora/config/cloudflare';
+export { type ReconcileCronsResult as ReconcileResult, reconcileWranglerCrons } from '@lunora/config/cloudflare';
 import { AddressInfo } from 'node:net';
 /** Options forwarded to `@cloudflare/vite-plugin`'s cloudflare plugin. */
 type CloudflarePluginOptions = Record<string, unknown>;
 /**
-* Options forwarded to `@visulima/vite-overlay`'s error-overlay plugin. Derived
-* from the plugin's own factory signature so it tracks the real shape
-* (`forwardConsole`, `forwardedConsoleMethods`, `reactPluginName`,
-* `solutionFinders`, `showBallonButton`, `vuePluginName`, …).
-*/
+ * Options forwarded to `@visulima/vite-overlay`'s error-overlay plugin. Derived
+ * from the plugin's own factory signature so it tracks the real shape
+ * (`forwardConsole`, `forwardedConsoleMethods`, `reactPluginName`,
+ * `solutionFinders`, `showBallonButton`, `vuePluginName`, …).
+ */
 type OverlayPluginOptions = NonNullable<Parameters<typeof errorOverlayPlugin>[0]>;
+/**
+ * Shard Durable Object configuration for the AUTO-COMPOSED class-A worker.
+ *
+ * A class-A app (TanStack Start, vinext, React Router, SolidStart) has no
+ * hand-written worker entry — that is what makes it class A — so it never calls
+ * the generated `defineApp()` builder and never reaches `createShardDO(config)`.
+ * The composed entry emitted `createShardDO()` bare, which left `cdc` and the
+ * whole reactive query cache unreachable for every class-A template no matter
+ * what the app wanted. `vite.config.ts` is the one place such an app configures
+ * Lunora, so it is where these land — the same route
+ * {@link LunoraPluginOptions.allowUnauthenticatedShardAccess} already takes into
+ * the same emitted entry.
+ *
+ * Deliberately only the PLAIN-DATA half of the generated `ShardDOConfig`. The
+ * rest of that type is `(env) => …` factories (`scheduler`, `storage`,
+ * `vectors`, …) which cannot be written in a config object and which a class-A
+ * app reaches by writing its own entry instead.
+ *
+ * Ignored for class B/C: those pass their config to `createShardDO` directly (or
+ * through `defineApp`), and an explicit argument there is unaffected by this.
+ */
+interface LunoraShardConfig {
+  /** Opt into change-data-capture: every write records a post-image to `__cdc_log`. Backs streaming export, replay-PITR, and shard-local `defineShape` replication. Off by default. */
+  cdc?: boolean;
+  /** Ceiling on the join keys one relation-crossing `where` predicate may pre-resolve via semijoin before failing closed. Omit for the engine default. */
+  maxRelationKeys?: number;
+  /**
+   * Enable the per-shard reactive query cache: `true` for the defaults, or an
+   * options object to tune the caps. Query results are memoized by
+   * `(functionPath, args, identity)` and invalidated by the ctx-db write hooks
+   * before the subscription broadcast, so a subscriber never observes a
+   * pre-write value. Omitted (or `false`) keeps every dispatch re-running its
+   * handler.
+   */
+  reactiveCache?: boolean | {
+    maxBytes?: number;
+    maxEntries?: number;
+  };
+  /** Resolution policy for a relation-crossing `where` whose child is co-located in this shard: `"auto"` (cost-based, the engine default), `"always"` (inline correlated EXISTS) or `"never"` (universal semijoin). All three return identical rows. */
+  relationExistsPushDown?: "always" | "auto" | "never";
+}
 interface LunoraPluginOptions {
   /**
-  * Which machine-readable API spec(s) codegen emits into `_generated/`.
-  * `"openapi"` (default) writes `openapi.json` (OpenAPI 3.1; RPC + REST),
-  * `"openrpc"` writes `openrpc.json` (OpenRPC 1.x; RPC-only), `"both"` writes
-  * both, and `"none"` writes neither. Forwarded to `runCodegen({ apiSpec })`;
-  * the value set is derived from `CodegenOptions` so it can't drift.
-  */
+   * Allow a client-named NON-default shard / cross-shard fan-out WITHOUT an
+   * `authorizeShard`/`authorizeFanOut` callback. The auto-composed class-A worker
+   * (`virtual:lunora/worker`) default-denies such access (403 `FORBIDDEN_SHARD`);
+   * set this `true` to opt into open access — only safe when every table is
+   * protected by per-row RLS. A production sharded app should configure
+   * `authorizeShard` instead (via a hand-written class-B worker). Defaults to `false`.
+   */
+  allowUnauthenticatedShardAccess?: boolean;
+  /**
+   * Which machine-readable API spec(s) codegen emits into `_generated/`.
+   * `"openapi"` (default) writes `openapi.json` (OpenAPI 3.1; RPC + REST),
+   * `"openrpc"` writes `openrpc.json` (OpenRPC 1.x; RPC-only), `"both"` writes
+   * both, and `"none"` writes neither. Forwarded to `runCodegen({ apiSpec })`;
+   * the value set is derived from `CodegenOptions` so it can't drift.
+   */
   apiSpec?: CodegenOptions["apiSpec"];
   /** Pass through to `@cloudflare/vite-plugin`. Pass `false` to opt out. Defaults to `true`. */
   cloudflare?: boolean | CloudflarePluginOptions;
-  /** Directory name (relative to `projectRoot`) where generated files are written. Defaults to `"lunora/_generated"`. */
-  generatedDir?: string;
   /**
-  * Inject `@visulima/vite-overlay` for runtime errors (dev only). Pass
-  * `false` to opt out, or an options object to forward to the overlay.
-  * Defaults to `true`.
-  */
+   * Inject `@visulima/vite-overlay` for runtime errors (dev only). Pass
+   * `false` to opt out, or an options object to forward to the overlay.
+   * Defaults to `true`.
+   */
   overlay?: boolean | OverlayPluginOptions;
   /** Project root containing the `lunora/` directory. Defaults to `process.cwd()`. */
   projectRoot?: string;
   /** Directory name (relative to `projectRoot`) containing `schema.ts` and function files. Defaults to `"lunora"`. */
   schemaDir?: string;
+  /**
+   * Shard DO configuration baked into the auto-composed class-A worker entry —
+   * see {@link LunoraShardConfig}. The ONLY way a class-A app can set `cdc` or
+   * enable the reactive query cache, since it has no worker entry to call
+   * `createShardDO(config)` from. Ignored for class B/C. Defaults to `{}`
+   * (byte-identical composed output).
+   */
+  shard?: LunoraShardConfig;
   /** Serve the Lunora studio at `/__lunora` during dev. Pass `false` to opt out. Defaults to `true`. */
   studio?: boolean;
+  /**
+   * Deploy target the emitted `ctx.*` surface is tailored to. Defaults to
+   * `"target"` in `lunora.json`, then `"cloudflare"` — so an existing project
+   * emits byte-identical output.
+   *
+   * Set it here only to override the project config for one build — keeping
+   * this and `lunora deploy` on the same target is what the shared resolution
+   * in `@lunora/config` exists to guarantee.
+   */
+  target?: string;
   /** Validate that `wrangler.jsonc` declares the bindings the schema implies. Defaults to `true`. */
   validateWrangler?: boolean;
 }
 /** Resolved options after merging defaults. */
 interface ResolvedLunoraPluginOptions {
+  allowUnauthenticatedShardAccess: boolean;
   apiSpec: NonNullable<CodegenOptions["apiSpec"]>;
   cloudflare: false | CloudflarePluginOptions;
+  /**
+   * Where codegen writes `_generated/*`, always `<schemaDir>/_generated`.
+   *
+   * NOT a user option: codegen hardcodes that path (`run-codegen` joins
+   * `lunoraDirectory` with `"_generated"`), so a settable override was a no-op
+   * everywhere except `frameworkComposePlugin`, which uses it as the composed
+   * class-A worker's import base — where a non-default value pointed the
+   * emitted imports at a directory nothing writes and broke class-A dev and
+   * build. Derived, so the import base cannot disagree with the emitter.
+   */
   generatedDir: string;
   overlay: false | OverlayPluginOptions;
   projectRoot: string;
   schemaDir: string;
+  shard: LunoraShardConfig;
   studio: boolean;
+  target: string;
   validateWrangler: boolean;
 }
 /**
-* The plugins `lunora()` returns. A mutable `Plugin[]` (not `ReadonlyArray`) so
-* it slots directly into Vite's `plugins` — which recursively flattens nested
-* plugin arrays — without a spread: `plugins: [lunora()]`.
-*/
+ * The plugins `lunora()` returns. A mutable `Plugin[]` (not `ReadonlyArray`) so
+ * it slots directly into Vite's `plugins` — which recursively flattens nested
+ * plugin arrays — without a spread: `plugins: [lunora()]`.
+ */
 type LunoraPlugins = Plugin[];
 /**
-* Vite plugin that runs `@lunora/codegen` on startup and on file changes
-* inside the lunora schema directory.
-*/
+ * Vite plugin that runs `@lunora/codegen` on startup and on file changes
+ * inside the lunora schema directory.
+ */
 declare const codegenPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
-interface ReconcileResult {
-  /** `true` when `wrangler.jsonc` was rewritten. */
-  changed: boolean;
-  /** Human-readable reason when reconciliation was skipped (for logging). */
-  reason?: string;
-  /** Resolved wrangler path, or `undefined` when none was found. */
-  wranglerPath?: string;
-}
 /**
-* Reconcile the codegen-derived cron schedules into the project's
-* `wrangler.jsonc` `triggers.crons` array, preserving comments and formatting
-* via `jsonc-parser`'s structural edits.
-*
-* When `triggers.crons` already matches `cronTriggers`, nothing is written (so
-* we don't churn the file or trip the dev server's file watcher). When the
-* project declares no crons, a stale non-empty array is cleared so removed
-* crons stop firing.
-*
-* This intentionally writes the SAME `triggers.crons` shape the
-* `@lunora/config` validator accepts, so the wrangler validator never fights
-* the generated value.
-*/
-declare const reconcileWranglerCrons: (projectRoot: string, cronTriggers: ReadonlyArray<string>) => ReconcileResult;
+ * Dev-only plugin that tails the local dev containers' own stdout/stderr in the
+ * Vite terminal.
+ *
+ * `@cloudflare/vite-plugin` builds and runs each declared container locally via
+ * Docker (image `cloudflare-dev/<class>:<id>`) but only forwards the *worker's*
+ * console — the container process's own output is otherwise invisible. This
+ * plugin attaches to those Docker log streams (via `@lunora/config`'s
+ * `streamContainerLogs`, which lazy-loads `dockerode`) and prints each line
+ * through Vite's logger, branded and tagged `container:<name>`.
+ *
+ * A no-op when the project declares no containers (the common case): discovery
+ * returns an empty list, so `dockerode` is never imported and no Docker work
+ * starts. Set `LUNORA_CONTAINER_LOGS=0` to opt out. A missing/stopped Docker
+ * engine degrades to a single warning rather than breaking dev.
+ */
+declare const containerLogsPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
+/** Vite plugin (serve-only) that writes the dev-server state record on listen and clears it on close. */
+declare const devStatePlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
-* Dev-only Vite plugin that offers to scaffold `.dev.vars` before the worker
-* boots. `@cloudflare/vite-plugin` loads `.dev.vars` into the worker's `env`,
-* but the file is gitignored — so a fresh clone has none and the worker throws
-* on the first required secret (e.g. `AUTH_SECRET is required`). When a
-* `.dev.vars.example` exists, we prompt to generate `.dev.vars` from it with
-* secrets auto-filled. Identical behaviour to `lunora dev` — both call
-* `ensureDevVariables` from `@lunora/config`.
-*
-* Runs in `configResolved` (awaited by Vite) so it completes before the
-* Cloudflare plugin reads the file. Non-interactive runs decline silently.
-*/
+ * Dev-only Vite plugin that prepares `.dev.vars` before the worker boots.
+ * `@cloudflare/vite-plugin` loads `.dev.vars` into the worker's `env`, but the
+ * file is gitignored — so a fresh clone has none and the worker throws on the
+ * first required secret (e.g. `AUTH_SECRET is required`). Three steps, the first
+ * two shared with `lunora dev` via `@lunora/config`.
+ *
+ * First, {@link ensureDevVariables}: when a `.dev.vars.example` exists, prompt
+ * to generate `.dev.vars` from it with secrets auto-filled. Second,
+ * {@link fillDevSecrets}: fill any empty/placeholder secret already in
+ * `.dev.vars` that Lunora can mint locally (a `lunora add`-scaffolded project
+ * writes secrets blank) and ensure `LUNORA_ADMIN_TOKEN` is present + generated —
+ * so the worker boots with working secrets and the Studio authenticates without
+ * its login gate. No prompt: it only generates locally-derivable values and
+ * never overwrites a real one. Third, {@link ensureDevWorkerEnv}.
+ *
+ * Runs in `configResolved` (awaited by Vite) so it completes before the
+ * Cloudflare plugin reads the file. Non-interactive runs decline silently.
+ * Skipped under `vite preview`, which resolves with `command: "serve"` and so
+ * runs `apply: "serve"` plugins too — previewing a built app must not prompt to
+ * scaffold, or write, a dev secrets file.
+ */
 declare const devVariablesPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
-* Worker env var the dev tooling sets so the Lunora runtime recognises a
-* development deployment (`@lunora/do`'s `isDevEnvironment`) and therefore
-* streams every RPC dispatch summary to the terminal by default — the
-* `lunora dev` CLI sets the same var via `wrangler dev --var`.
-*
-* It is injected ONLY during `vite` serve, never a production `vite build`, so
-* it can never leak into a deployed worker. A `WORKER_ENV` the user already
-* declares (in `wrangler.jsonc` `[vars]` or `.dev.vars`) takes precedence, so
-* this only fills the gap when none is set.
-*/
-declare const DEV_WORKER_ENV_VAR = "WORKER_ENV";
-declare const DEV_WORKER_ENV_VALUE = "development";
-/** The structural slice of `@cloudflare/vite-plugin`'s worker config we read/write. */
-/**
-* Wrap the cloudflare-plugin options so the dev worker's `vars` gain a
-* `WORKER_ENV` of `development` when — and only when — `isServe()` reports a
-* `vite` serve. Any `config` customizer the caller already supplied is
-* preserved and applied first; an existing `WORKER_ENV` wins, so a user
-* override is never clobbered.
-*/
-declare const withDevWorkerEnv: (options: CloudflarePluginOptions, isServe: () => boolean) => CloudflarePluginOptions;
-/**
-* A Vite plugin that captures the resolved command (`serve` vs `build`) so
-* {@link withDevWorkerEnv} injects the dev var only during `vite`, plus an
-* `isServe` probe sharing the same closure. `enforce: "pre"` so the command is
-* captured before the cloudflare plugin resolves its worker config.
-*/
-declare const createCommandProbe: () => {
-  isServe: () => boolean;
-  plugin: Plugin;
-};
-/**
-* Mutable, plugin-shared context. The `lunora()` factory creates one instance
-* and threads it through every Lunora sub-plugin, so detection runs once and
-* downstream plugins (codegen, composition, the dev hint) read the same result
-* without re-scanning `package.json`. PLAN4 §2.4.
-*/
+ * Mutable, plugin-shared context. The `lunora()` factory creates one instance
+ * and threads it through every Lunora sub-plugin, so detection runs once and
+ * downstream plugins (codegen, composition, the dev hint) read the same result
+ * without re-scanning `package.json`. PLAN4 §2.4.
+ */
 interface LunoraPluginContext {
   /** The detected framework + class, populated during `config` / `configResolved`. `undefined` until detection runs. */
   framework?: FrameworkDetection;
 }
-/** Create an empty shared context object for one `lunora()` invocation. */
 /**
-* The virtual module id the Lunora plugin resolves to a generated, class-A
-* worker entry. A class-A template points its wrangler `main` at this id (or
-* re-exports it from a one-line `src/server.ts`) and never hand-writes
-* `createWorker({ httpRouter })` — the plugin composes the framework's SSR
-* handler under `composeWorker`'s `httpRouter` seam for it.
-*
-* Exposed publicly so `@lunora/cli`'s build/deploy path and the templates can
-* reference the same constant rather than re-typing the literal.
-*/
+ * The virtual module id the Lunora plugin resolves to a generated, class-A
+ * worker entry. A class-A template points its wrangler `main` at this id (or
+ * re-exports it from a one-line `src/server.ts`) and never hand-writes
+ * `createWorker({ httpRouter })` — the plugin composes the framework's SSR
+ * handler under `composeWorker`'s `httpRouter` seam for it.
+ *
+ * Exposed publicly so `@lunora/cli`'s build/deploy path and the templates can
+ * reference the same constant rather than re-typing the literal.
+ */
 declare const LUNORA_WORKER_VIRTUAL_ID: string;
 /**
-* Per-class-A-framework wiring the generated worker entry needs: how to obtain
-* the framework's SSR handler as a `composeWorker`-compatible `httpRouter`.
-*
-* `imports` is the full import statement(s) the generated entry needs (each
-* framework controls its own import shape — a namespace import, or a named one);
-* `handler` is a JS expression (evaluated in the generated module's scope, where
-* `imports`' symbols are in scope) that yields an `HttpRouterLike`
-* (`{ fetch(request, env?, ctx?) }`). Both are data — not codegen branches — so
-* the set of supported class-A frameworks is one readable table and adding a
-* framework is a pure data edit.
-*
-* Honesty note: these handler expressions encode each framework's *documented*
-* Cloudflare SSR-handler shape — the same expressions the hand-wired template
-* entries use today (React Router's `createRequestHandler` over its virtual
-* server build; SolidStart's `cloudflare-module` handler; TanStack Start's
-* server entry). The plugin just emits them so the developer doesn't.
-*/
+ * Per-class-A-framework wiring the generated worker entry needs: how to obtain
+ * the framework's SSR handler as a `composeWorker`-compatible `httpRouter`.
+ *
+ * `imports` is the full import statement(s) the generated entry needs (each
+ * framework controls its own import shape — a namespace import, or a named one);
+ * `handler` is a JS expression (evaluated in the generated module's scope, where
+ * `imports`' symbols are in scope) that yields an `HttpRouterLike`
+ * (`{ fetch(request, env?, ctx?) }`). Both are data — not codegen branches — so
+ * the set of supported class-A frameworks is one readable table and adding a
+ * framework is a pure data edit.
+ *
+ * Honesty note: these handler expressions encode each framework's *documented*
+ * Cloudflare SSR-handler shape — the same expressions the hand-wired template
+ * entries use today (React Router's `createRequestHandler` over its virtual
+ * server build; SolidStart's `cloudflare-module` handler; TanStack Start's
+ * server entry). The plugin just emits them so the developer doesn't.
+ */
 interface ClassAWiring {
   /** JS expression yielding the `httpRouter` ({ fetch }), referencing symbols brought in by `imports`. */
   handler: string;
@@ -179,62 +233,105 @@ interface ClassAWiring {
 }
 declare const CLASS_A_WIRING: Readonly<Partial<Record<DetectedFramework, ClassAWiring>>>;
 /**
-* Whether the detected framework is one the plugin can auto-compose. Only
-* class-A frameworks with a known SSR-handler wiring qualify; everything else
-* (class B/C, `none`) falls back to the existing flow.
-*/
+ * Whether the detected framework is one the plugin can auto-compose. Only
+ * class-A frameworks with a known SSR-handler wiring qualify; everything else
+ * (class B/C, `none`) falls back to the existing flow.
+ */
 declare const isAutoComposable: (context: LunoraPluginContext) => boolean;
 /**
-* Build the source of the virtual class-A worker entry. Pure (no fs / no Vite),
-* so the emitted composition is unit-testable in isolation.
-*
-* The emitted module imports the framework SSR handler + the project's
-* generated artifacts (functions registry, OpenAPI doc, `createShardDO`) and
-* composes them through `composeWorker` — reserved `/_lunora/*` paths route to
-* Lunora, everything else falls through to the framework SSR handler. The
-* `generatedImportBase` MUST be an absolute filesystem path to the `_generated`
-* directory. Virtual modules have no real filesystem path, so relative specifiers
-* like `./lunora/_generated/functions` cannot be resolved by Vite/rolldown from a
-* virtual module id. Absolute paths are resolved correctly in all environments
-* (Vite 8 + rolldown 1.x confirmed).
-*/
-declare const buildWorkerEntrySource: (framework: DetectedFramework, generatedImportBase: string, hasContainers?: boolean) => string;
+ * The `_generated/` modules whose exported classes wrangler validates a
+ * `class_name` against: container Durable Objects, workflow entrypoints, and
+ * agent (workflow) entrypoints — the same three kinds `reconcile-bindings`
+ * writes into `wrangler.jsonc`. The composed entry star-re-exports each module
+ * the project actually has.
+ */
+declare const GENERATED_CLASS_MODULES: readonly ["agents", "containers", "workflows"];
+/** One {@link GENERATED_CLASS_MODULES} entry. */
+type GeneratedClassModule = (typeof GENERATED_CLASS_MODULES)[number];
+/**
+ * Build the source of the virtual class-A worker entry. Pure (no fs / no Vite),
+ * so the emitted composition is unit-testable in isolation.
+ *
+ * The emitted module imports the framework SSR handler + the project's
+ * generated artifacts (functions registry, OpenAPI doc, `createShardDO`) and
+ * composes them through `composeWorker` — reserved `/_lunora/*` paths route to
+ * Lunora, everything else falls through to the framework SSR handler. The
+ * `generatedImportBase` MUST be an absolute filesystem path to the `_generated`
+ * directory. Virtual modules have no real filesystem path, so relative specifiers
+ * like `./lunora/_generated/functions` cannot be resolved by Vite/rolldown from a
+ * virtual module id. Absolute paths are resolved correctly in all environments
+ * (Vite 8 + rolldown 1.x confirmed).
+ */
+declare const buildWorkerEntrySource: (framework: DetectedFramework, generatedImportBase: string, classModules?: ReadonlyArray<GeneratedClassModule>, useUmbrella?: boolean, allowUnauthenticatedShardAccess?: boolean, shard?: LunoraShardConfig) => string;
 /**
-* Vite plugin that auto-composes a detected class-A meta-framework's SSR
-* handler with Lunora into one Cloudflare Worker (PLAN4 §2.4 / §3 class-A row).
-*
-* Mechanism: it resolves the {@link LUNORA_WORKER_VIRTUAL_ID} virtual module to
-* a generated worker entry that wires the framework SSR handler under
-* `composeWorker`'s `httpRouter` seam — so the developer never writes
-* `createWorker({ httpRouter })`. The composed worker is an ordinary module
-* entry, so it HMRs under `@cloudflare/vite-plugin` exactly like a hand-written
-* one (PLAN4 M5 risk #5): the virtual entry only imports the framework handler
-* and the generated artifacts, both of which the framework's plugin + codegen
-* already make HMR-aware.
-*
-* Safety: it is a strict no-op unless `context.framework.class === "A"` with a
-* known wiring. For class-C (SPA) projects and undetected frameworks it
-* resolves/loads nothing. `cloudflare: false` does NOT disable the virtual
-* entry — it only means "don't add the Cloudflare Vite plugin a second time"
-* (the user supplied it themselves); the composed worker must still be
-* resolvable so the user-supplied CF plugin can find the wrangler `main`.
-*/
+ * Vite plugin that auto-composes a detected class-A meta-framework's SSR
+ * handler with Lunora into one Cloudflare Worker (PLAN4 §2.4 / §3 class-A row).
+ *
+ * Mechanism: it resolves the {@link LUNORA_WORKER_VIRTUAL_ID} virtual module to
+ * a generated worker entry that wires the framework SSR handler under
+ * `composeWorker`'s `httpRouter` seam — so the developer never writes
+ * `createWorker({ httpRouter })`. The composed worker is an ordinary module
+ * entry, so it HMRs under `@cloudflare/vite-plugin` exactly like a hand-written
+ * one (PLAN4 M5 risk #5): the virtual entry only imports the framework handler
+ * and the generated artifacts, both of which the framework's plugin + codegen
+ * already make HMR-aware.
+ *
+ * Safety: it is a strict no-op unless `context.framework.class === "A"` with a
+ * known wiring. For class-C (SPA) projects and undetected frameworks it
+ * resolves/loads nothing. `cloudflare: false` does NOT disable the virtual
+ * entry — it only means "don't add the Cloudflare Vite plugin a second time"
+ * (the user supplied it themselves); the composed worker must still be
+ * resolvable so the user-supplied CF plugin can find the wrangler `main`. The
+ * vinext template depends on exactly that, so making this plugin honour the
+ * option would break it.
+ */
 declare const frameworkComposePlugin: (options: ResolvedLunoraPluginOptions, context: LunoraPluginContext) => Plugin;
 /**
-* Vite plugin (serve-only) that formats Lunora worker logs in the terminal.
-* Patches `process.stdout`/`process.stderr` once the dev server is configured
-* and restores them when it closes.
-*/
+ * The custom HMR event the Lunora Vite plugin sends on the client environment's
+ * hot channel after a successful codegen run, in place of the old blanket
+ * browser `full-reload`. The generated `api`/`server` modules are just
+ * `FunctionReference` metadata, so Vite's granular module HMR re-imports the
+ * changed `_generated/*` in place; this event is a non-destructive nudge that
+ * lets open WebSocket subscriptions, optimistic state, the offline queue, and
+ * form state survive a schema save.
+ *
+ * Kept in its own module (a single source of truth) so the codegen plugin —
+ * whose sole export is the plugin factory — can reference it without becoming a
+ * mixed default+named module, and so any future client-side listener can agree
+ * on the exact string.
+ *
+ * There is no first-party client listener yet: `@lunora/client` / `@lunora/react`
+ * ship as pre-bundled, side-effect-free dependencies where `import.meta.hot` is
+ * `undefined` at runtime (Vite's dep optimizer), so a listener there would be
+ * dead (and tree-shaken) code. A future app-local or codegen-emitted listener
+ * can import this constant to re-validate active queries over the live socket.
+ */
+declare const LUNORA_API_UPDATED_EVENT = "lunora:api-updated";
+/**
+ * Vite plugin (serve-only) that formats Lunora worker logs in the terminal.
+ * Patches `process.stdout`/`process.stderr` fresh for each dev-server generation
+ * and restores them when that server closes.
+ */
 declare const logStreamPlugin: () => Plugin;
+/**
+ * Warnings for one proxy table. Pure + exported so the behavior is unit-testable
+ * without booting a dev server.
+ */
+declare const checkLunoraProxy: (proxy: Record<string, unknown> | undefined, label: string) => string[];
+/**
+ * Warn when a dev/preview proxy routes `/_lunora/*` without `ws: true` (or with an
+ * origin-rewriting `changeOrigin`). See the module docs.
+ */
+declare const proxyCheckPlugin: () => Plugin;
 /** The decision a {@link planViteRemoteBindings} call returns. */
 interface ViteRemotePlan {
   /** Idempotent disposer for the temp config; always present + safe to call. */
   cleanup: () => void;
   /**
-  * Absolute path to the materialized temp wrangler config to hand the
-  * cloudflare plugin's `configPath`, or `undefined` when remote mode is off
-  * or nothing was materialized (no eligible binding, no wrangler file, …).
-  */
+   * Absolute path to the materialized temp wrangler config to hand the
+   * cloudflare plugin's `configPath`, or `undefined` when remote mode is off
+   * or nothing was materialized (no eligible binding, no wrangler file, …).
+   */
   configPath?: string;
   /** Whether remote mode was requested for this dev session. */
   enabled: boolean;
@@ -253,122 +350,211 @@ interface PlanViteRemoteOptions {
   remoteEnv?: string;
 }
 /**
-* Decide whether the Vite dev worker uses remote bindings and, if so,
-* materialize the temp config. Pure decision + a single fs write via the
-* injected materializer; returns a `cleanup` for the dev server's close hook.
-*
-* There is no `--remote` flag on the Vite path (Vite has no Lunora CLI flags),
-* so the precedence reduces to `LUNORA_REMOTE` env > `lunora.json` `remote`.
-*/
+ * Decide whether the Vite dev worker uses remote bindings and, if so,
+ * materialize the temp config. Pure decision + a single fs write via the
+ * injected materializer; returns a `cleanup` for the dev server's close hook.
+ *
+ * There is no `--remote` flag on the Vite path (Vite has no Lunora CLI flags),
+ * so the precedence reduces to `LUNORA_REMOTE` env > `lunora.json` `remote`.
+ *
+ * Call this from a `config` hook, never at plugin-factory time — see
+ * {@link remoteBindingsPlugin} for the two defects that timing caused.
+ */
 declare const planViteRemoteBindings: (options: PlanViteRemoteOptions) => ViteRemotePlan;
 /**
-* Wrap the cloudflare-plugin options so the dev worker loads the materialized
-* remote temp config (via `configPath`) when — and only when — remote mode is
-* on AND it's a `vite` serve. A `configPath` the caller already set wins (their
-* explicit choice), and during a production build nothing is injected, so the
-* deployed worker is never affected.
-*
-* Returns the wrapped options plus the plan, so `index.ts` can register the
-* cleanup on a close hook. Materialization happens lazily inside the `configPath`
-* resolution path: it's only meaningful during serve, but computing it eagerly
-* is harmless (the materializer is a no-op when disabled) and keeps the wiring
-* simple — the plan is computed once here.
-*/
-declare const withRemoteBindings: (options: CloudflarePluginOptions, isServe: () => boolean, plan: ViteRemotePlan) => CloudflarePluginOptions;
+ * Wrap the cloudflare-plugin options so the dev worker loads the materialized
+ * remote temp config (via `configPath`) when — and only when — remote mode is
+ * on and a temp config was materialized. A `configPath` the caller already set
+ * wins (their explicit choice).
+ *
+ * Pure decision only — the serve-vs-build gate lives in
+ * {@link remoteBindingsPlugin}'s `config` hook, because the resolved Vite
+ * `command` is unknown at plugin-factory time. An eager serve check there would
+ * always read `command` as undefined and strip `configPath`.
+ */
+declare const withRemoteBindings: (options: CloudflarePluginOptions, plan: ViteRemotePlan) => CloudflarePluginOptions;
+/**
+ * A `enforce: "pre"` plugin that materializes the remote temp wrangler config
+ * and injects it into the cloudflare plugin's `configPath` — but only on a
+ * `vite` serve, never a production build (so the deployed worker is never
+ * affected) — then disposes the temp file when the dev server tears down.
+ *
+ * Both halves are deferred into the `config` hook, and each deferral closes a
+ * defect of its own.
+ *
+ * The command check: at plugin-factory time Vite has not yet resolved `serve`
+ * vs `build`, so it has to run here. An eager factory-time check always read
+ * `command` as undefined and stripped `configPath`, so remote bindings never
+ * activated on `vite dev` at all.
+ *
+ * The materialization: the temp config is a COPY of `wrangler.jsonc`, and
+ * Lunora provisions the bindings the project's code implies from
+ * `bindingsProvisionPlugin`'s own `config` hook — earlier in this same phase,
+ * since both are `enforce: "pre"` and that plugin is registered first. (It is a
+ * plugin of its own, registered unconditionally, precisely so this copy is not a
+ * binding short whenever `validateWrangler` is off — `wranglerValidatorPlugin`
+ * only validates, and is registered after this one.) Copying
+ * the file at factory time therefore snapshotted it BEFORE that write, and the
+ * dev worker booted against a config missing the binding Lunora had just added:
+ * a `vite dev` that logged `inferred bindings → AI (Workers AI)`, passed
+ * validation, and served a worker with no `env.AI`. That is the remote twin of
+ * the local defect the reconcile's move into `config` fixed.
+ *
+ * The injection mutates the SAME options object handed to `cloudflare()` in
+ * place — the cloudflare plugin reads `pluginConfig.configPath` lazily inside
+ * its own `config` hook, which runs after this `enforce: "pre"` one, so the
+ * injection takes effect.
+ *
+ * The disposer reads the CURRENT plan rather than a factory-time capture,
+ * because no plan exists until `config` has run.
+ *
+ * When remote mode was requested but nothing materialized (no eligible binding,
+ * no wrangler file, …), the plan's `reason` is logged so the degradation isn't
+ * silent.
+ *
+ * `options` is `undefined` on the BYO path (`cloudflare: false`), where the
+ * project constructs `cloudflare()` itself and Lunora has no options object to
+ * inject into: the materialized path is printed with what to do with it, rather
+ * than leaving `LUNORA_REMOTE` looking like it took effect.
+ */
+declare const remoteBindingsPlugin: (options: CloudflarePluginOptions | undefined, planOptions: PlanViteRemoteOptions) => Plugin;
 /**
-* A tiny Vite plugin that runs the remote temp-config disposer when the dev
-* server tears down (`buildEnd` fires on close in serve; `closeBundle` covers
-* the build/close path). Idempotent cleanup means firing on both is safe.
-*/
-declare const remoteBindingsCleanupPlugin: (cleanup: () => void) => Plugin;
+ * A `@visulima/vite-overlay` solution finder. Derived from the overlay's own
+ * options type so the shape can't drift from the installed package. The overlay
+ * runs every finder it's given (custom finders first, then its built-ins),
+ * sorted by `priority` descending, and shows the first non-`undefined` result.
+ *
+ * Note: this type (and {@link Solution}) is re-exported from `@lunora/vite` and
+ * intentionally tracks the installed `@visulima/vite-overlay` — if a future
+ * overlay release changes the finder contract, that surfaces here as a compile
+ * error rather than a silent drift.
+ */
+type SolutionFinder = NonNullable<OverlayPluginOptions["solutionFinders"]>[number];
+/** What a finder may return: a Markdown-rendered `{ header?, body }`, or `undefined` to defer. */
+type Solution = NonNullable<Awaited<ReturnType<SolutionFinder["handle"]>>>;
+/**
+ * Lunora's solution finder for the dev error overlay. A single finder that
+ * delegates to `@lunora/codegen`'s shared rule table (the same table the
+ * standalone `lunora dev` CLI prints to the terminal) and returns the first
+ * match — so one `priority` slot covers every Lunora rule and the overlay's
+ * built-in finders still run for anything we don't recognize (we return
+ * `undefined`).
+ *
+ * Priority is high so a Lunora-specific hint wins over the overlay's generic
+ * finder for the same error; a user's own finder can still outrank it with a
+ * higher `priority`.
+ */
+declare const lunoraSolutionFinder: SolutionFinder;
+/** The finders Lunora injects into the overlay by default. */
+declare const lunoraSolutionFinders: ReadonlyArray<SolutionFinder>;
 /** Dev-server path the studio SPA is served from. */
 declare const STUDIO_PATH = "/__lunora";
-/** Static asset routes the studio document references. */
-
 /**
-* Build the user-facing studio URL from the dev server's resolved address.
-* Pure so it can be unit-tested without a live server. Prefers Vite's own
-* `resolvedUrls.local` (honours `host` / `base` / https); falls back to the raw
-* socket address, bracketing IPv6 and normalising the wildcard host.
-*/
+ * Build the user-facing studio URL from the dev server's resolved address.
+ * Pure so it can be unit-tested without a live server. Prefers Vite's own
+ * `resolvedUrls.local` (honours `host` / `base` / https); falls back to the raw
+ * socket address, bracketing IPv6 and normalising the wildcard host.
+ */
 declare const buildStudioUrl: (input: {
   address?: AddressInfo | string;
   base?: string;
   resolvedLocal?: string;
 }) => string;
 /**
-* Vite plugin that serves the composed Lunora studio at
-* {@link STUDIO_PATH} during dev and prints its URL once the server is
-* listening. Dev-only (`apply: "serve"`); it adds nothing to production builds.
-*
-* Because `lunora dev` spawns Vite, this makes the studio available on
-* `lunora dev` and on a plain `vite` with no per-project files. The studio
-* is served as a prebuilt static bundle, independent of the host app.
-*/
-declare const studioPlugin: () => Plugin;
+ * Vite plugin that serves the composed Lunora studio at
+ * {@link STUDIO_PATH} during dev and prints its URL once the server is
+ * listening. Dev-only (`apply: "serve"`); it adds nothing to production builds.
+ *
+ * Because `lunora dev` spawns Vite, this makes the studio available on
+ * `lunora dev` and on a plain `vite` with no per-project files. The studio
+ * is served as a prebuilt static bundle, independent of the host app.
+ */
+declare const studioPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
-* When a module under `lunora/` throws while the Worker entry is first
-* evaluated, `@cloudflare/vite-plugin` surfaces the failure from deep inside
-* its `runner-worker` running in `workerd`. The real error crosses a workerd
-* RPC boundary on the way out, which drops the user-code stack frames — so all
-* the dev server sees is a bare, file-less message like:
-*
-* ```
-* TypeError: Cannot read properties of undefined (reading 'string')
-*     at runInRunnerObject (workers/runner-worker/index.js:107:3)
-*     at getWorkerEntryExportTypes (workers/runner-worker/index.js:246:24)
-* ```
-*
-* The classic cause is a **circular import**: a `lunora/` query/mutation/action
-* module runs `mutation({ args: { x: v.string() } })` at the top level while the
-* module it imported `v`/`query`/`mutation` from is still mid-initialization, so
-* those bindings read as `undefined`. The message names a validator method
-* (`'string'`, `'id'`, …) but never the file.
-*
-* We can't recover the dropped frames at this layer, but we can recognise the
-* shape of the failure and append an actionable hint pointing at the likely
-* cause — turning a dead-end stack into something a user can act on.
-*/
+ * When a module under `lunora/` throws while the Worker entry is first
+ * evaluated, `@cloudflare/vite-plugin` surfaces the failure from deep inside
+ * its `runner-worker` running in `workerd`. The real error crosses a workerd
+ * RPC boundary on the way out, which drops the user-code stack frames — so all
+ * the dev server sees is a bare, file-less message like:
+ *
+ * ```
+ * TypeError: Cannot read properties of undefined (reading 'string')
+ *     at runInRunnerObject (workers/runner-worker/index.js:107:3)
+ *     at getWorkerEntryExportTypes (workers/runner-worker/index.js:246:24)
+ * ```
+ *
+ * The classic cause is a **circular import**: a `lunora/` query/mutation/action
+ * module runs `mutation({ args: { x: v.string() } })` at the top level while the
+ * module it imported `v`/`query`/`mutation` from is still mid-initialization, so
+ * those bindings read as `undefined`. The message names a validator method
+ * (`'string'`, `'id'`, …) but never the file.
+ *
+ * We can't recover the dropped frames at this layer, but we can recognise the
+ * shape of the failure and append an actionable hint pointing at the likely
+ * cause — turning a dead-end stack into something a user can act on.
+ */
 declare const WORKER_STARTUP_HINT: string;
 /**
-* True when `error` looks like a Worker-entry evaluation failure routed through
-* `@cloudflare/vite-plugin`'s runner worker (the stack references the runner
-* worker / export-types probe). Kept narrow so we only annotate this specific
-* class of dev-startup error.
-*/
+ * True when `error` looks like a Worker-entry evaluation failure routed through
+ * `@cloudflare/vite-plugin`'s runner worker (the stack references the runner
+ * worker / export-types probe). Kept narrow so we only annotate this specific
+ * class of dev-startup error.
+ */
 declare const isWorkerEntryEvalError: (error: unknown) => boolean;
 /**
-* Append {@link WORKER_STARTUP_HINT} to a recognised Worker-entry eval error
-* (idempotently). Any other value is returned untouched.
-*/
+ * Append {@link WORKER_STARTUP_HINT} to a recognised Worker-entry eval error
+ * (idempotently). Any other value is returned untouched.
+ */
 declare const augmentWorkerStartupError: (error: unknown) => unknown;
 /**
-* Wrap the startup hooks of `@cloudflare/vite-plugin`'s plugins so a Worker-entry
-* evaluation failure carries the Lunora hint. Returns a new array; the input
-* plugins are shallow-cloned (never mutated in place) so re-using the cloudflare
-* plugin instances elsewhere stays safe.
-*/
+ * Wrap the startup hooks of `@cloudflare/vite-plugin`'s plugins so a Worker-entry
+ * evaluation failure carries the Lunora hint. Returns a new array; the input
+ * plugins are shallow-cloned (never mutated in place) so re-using the cloudflare
+ * plugin instances elsewhere stays safe.
+ */
 declare const withWorkerStartupHint: (plugins: ReadonlyArray<Plugin>) => Plugin[];
 /**
-* Vite plugin that validates the project's `wrangler.jsonc` against the
-* bindings implied by `lunora/schema.ts`. Throws (Vite renders nicely) on
-* missing requirements during `configResolved`. Delegates the parsing /
-* validation logic to `@lunora/config` so the rules stay in lockstep with
-* the CLI (`lunora deploy`).
-*/
+ * Vite plugin that validates the project's `wrangler.jsonc` against the
+ * bindings implied by `lunora/schema.ts`. Throws (Vite renders nicely) on
+ * missing requirements during `configResolved`. Delegates the parsing /
+ * validation logic to `@lunora/config` so the rules stay in lockstep with
+ * the CLI (`lunora deploy`).
+ *
+ * Provisioning runs BEFORE this, in `bindingsProvisionPlugin`'s `config` hook,
+ * which is the order `lunora dev` uses (infer → reconcile, no validation pass):
+ * the bindings this check requires are the ones Lunora writes itself, so
+ * validating first killed the dev server the first time a project declared a
+ * `.global()` table or a container. That plugin is registered unconditionally and
+ * ahead of this one — the write is not optional the way the check is, and it must
+ * land in `config` to reach the worker at all (see its docblock).
+ *
+ * Skipped under `vite preview`, which resolves with `command: "serve"` and so
+ * runs `apply: "serve"` plugins: previewing a built app must not probe Docker.
+ */
 declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
-* Lunora Vite plugin. Returns a flat array of Vite plugins that:
-*
-* 1. Run `@lunora/codegen` on startup + on schema file changes.
-* 2. Validate the project's `wrangler.jsonc` against the schema's implied bindings.
-* 3. Inject `@visulima/vite-overlay` for runtime error overlays (unless `overlay: false`).
-* 4. Include `@cloudflare/vite-plugin` so users get one-import setup (unless `cloudflare: false`).
-*
-* `@cloudflare/vite-plugin` and `@visulima/vite-overlay` are direct dependencies,
-* so they're imported statically — opt out per-feature via the options rather
-* than relying on whether they're installed.
-*/
+ * Resolve the `overlay` toggle into the overlay plugin's options — or `false` to
+ * skip it. Lunora's solution finders are **prepended** so they run before the
+ * overlay's built-ins; a user's own finders are appended and can still win per
+ * error via a strictly higher `priority` (equal priority keeps Lunora first,
+ * since the overlay sorts stably). Lunora also forwards both `error` AND `warn`
+ * console calls by default (the overlay's own default is `["error"]` only) so
+ * Lunora's branded `warn` advisories surface in the browser too — the user can
+ * override `forwardedConsoleMethods`.
+ */
+declare const resolveOverlayOption: (overlay: LunoraPluginOptions["overlay"]) => false | OverlayPluginOptions;
+/**
+ * Lunora Vite plugin. Returns a flat array of Vite plugins that:
+ *
+ * 1. Run `@lunora/codegen` on startup + on schema file changes.
+ * 2. Validate the project's `wrangler.jsonc` against the schema's implied bindings.
+ * 3. Inject `@visulima/vite-overlay` for runtime error overlays (unless `overlay: false`).
+ * 4. Include `@cloudflare/vite-plugin` so users get one-import setup (unless `cloudflare: false`).
+ *
+ * `@cloudflare/vite-plugin` and `@visulima/vite-overlay` are direct dependencies,
+ * so they're imported statically — opt out per-feature via the options rather
+ * than relying on whether they're installed.
+ */
 declare const lunora: (options?: LunoraPluginOptions) => LunoraPlugins;
-declare const VERSION = "0.0.0";
-export { CLASS_A_WIRING, type ClassAWiring, type CloudflarePluginOptions, DEV_WORKER_ENV_VALUE, DEV_WORKER_ENV_VAR, LUNORA_WORKER_VIRTUAL_ID, type LunoraPluginOptions, type LunoraPlugins, type OverlayPluginOptions, type PlanViteRemoteOptions, type ReconcileResult, type ResolvedLunoraPluginOptions, STUDIO_PATH, VERSION, type ViteRemotePlan, WORKER_STARTUP_HINT, augmentWorkerStartupError, buildStudioUrl, buildWorkerEntrySource, codegenPlugin, createCommandProbe, devVariablesPlugin, frameworkComposePlugin, isAutoComposable, isWorkerEntryEvalError, logStreamPlugin, lunora, planViteRemoteBindings, reconcileWranglerCrons, remoteBindingsCleanupPlugin, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };
+declare const VERSION: string;
+export { CLASS_A_WIRING, type ClassAWiring, type CloudflarePluginOptions, GENERATED_CLASS_MODULES, type GeneratedClassModule, LUNORA_API_UPDATED_EVENT, LUNORA_WORKER_VIRTUAL_ID, type LunoraPluginOptions, type LunoraPlugins, type LunoraShardConfig, type OverlayPluginOptions, type PlanViteRemoteOptions, type ResolvedLunoraPluginOptions, STUDIO_PATH, type Solution, type SolutionFinder, VERSION, type ViteRemotePlan, WORKER_STARTUP_HINT, augmentWorkerStartupError, buildStudioUrl, buildWorkerEntrySource, checkLunoraProxy, codegenPlugin, containerLogsPlugin, devStatePlugin, devVariablesPlugin, frameworkComposePlugin, isAutoComposable, isWorkerEntryEvalError, logStreamPlugin, lunora, lunoraSolutionFinder, lunoraSolutionFinders, planViteRemoteBindings, proxyCheckPlugin, remoteBindingsPlugin, resolveOverlayOption, studioPlugin, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };