@lunora/vite 1.0.0-alpha.19 → 1.0.0-alpha.20

package/README.md

@@ -80,6 +80,21 @@ lunora({
 
 `lunora()` returns a flat `Plugin[]`; Vite flattens nested plugin arrays, so `plugins: [lunora()]` works without spreading.
 
+### Error overlay
+
+The overlay surfaces dev-time failures in the browser. Lunora ships **solution finders** that turn the common ones — missing/invalid `defineSchema`, reserved or duplicate table names, a bad `.jurisdiction(...)`, a non-literal `unique`, a binding that isn't re-exported by your worker entry, and runtime unique-constraint / optimistic-concurrency conflicts — into an actionable fix hint right in the overlay.
+
+`overlay` also accepts an options object forwarded to [`@visulima/vite-overlay`](https://www.npmjs.com/package/@visulima/vite-overlay), so you can add your own finders alongside Lunora's:
+
+```ts
+lunora({
+    overlay: {
+        // your finders run alongside Lunora's; either side can win per error via `priority`
+        solutionFinders: [myCustomFinder],
+    },
+});
+```
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/vite)**.
 
 ## Related

package/dist/index.d.mts

@@ -305,6 +305,35 @@ declare const withRemoteBindings: (options: CloudflarePluginOptions, isServe: ()
 * 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. */
@@ -382,6 +411,17 @@ declare const withWorkerStartupHint: (plugins: ReadonlyArray<Plugin>) => Plugin[
 */
 declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
+* 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.
@@ -395,4 +435,4 @@ declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) =>
 */
 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, containerLogsPlugin, createCommandProbe, devVariablesPlugin, frameworkComposePlugin, isAutoComposable, isWorkerEntryEvalError, logStreamPlugin, lunora, planViteRemoteBindings, reconcileWranglerCrons, remoteBindingsCleanupPlugin, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };
+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, type Solution, type SolutionFinder, VERSION, type ViteRemotePlan, WORKER_STARTUP_HINT, augmentWorkerStartupError, buildStudioUrl, buildWorkerEntrySource, codegenPlugin, containerLogsPlugin, createCommandProbe, devVariablesPlugin, frameworkComposePlugin, isAutoComposable, isWorkerEntryEvalError, logStreamPlugin, lunora, lunoraSolutionFinder, lunoraSolutionFinders, planViteRemoteBindings, reconcileWranglerCrons, remoteBindingsCleanupPlugin, resolveOverlayOption, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };

package/dist/index.d.ts

@@ -305,6 +305,35 @@ declare const withRemoteBindings: (options: CloudflarePluginOptions, isServe: ()
 * 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. */
@@ -382,6 +411,17 @@ declare const withWorkerStartupHint: (plugins: ReadonlyArray<Plugin>) => Plugin[
 */
 declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
+* 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.
@@ -395,4 +435,4 @@ declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) =>
 */
 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, containerLogsPlugin, createCommandProbe, devVariablesPlugin, frameworkComposePlugin, isAutoComposable, isWorkerEntryEvalError, logStreamPlugin, lunora, planViteRemoteBindings, reconcileWranglerCrons, remoteBindingsCleanupPlugin, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };
+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, type Solution, type SolutionFinder, VERSION, type ViteRemotePlan, WORKER_STARTUP_HINT, augmentWorkerStartupError, buildStudioUrl, buildWorkerEntrySource, codegenPlugin, containerLogsPlugin, createCommandProbe, devVariablesPlugin, frameworkComposePlugin, isAutoComposable, isWorkerEntryEvalError, logStreamPlugin, lunora, lunoraSolutionFinder, lunoraSolutionFinders, planViteRemoteBindings, reconcileWranglerCrons, remoteBindingsCleanupPlugin, resolveOverlayOption, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };

package/dist/index.mjs

@@ -12,6 +12,8 @@ import { frameworkComposePlugin } from './packem_shared/CLASS_A_WIRING-DpX_WcOK.
 export { CLASS_A_WIRING, LUNORA_WORKER_VIRTUAL_ID, buildWorkerEntrySource, isAutoComposable } from './packem_shared/CLASS_A_WIRING-DpX_WcOK.mjs';
 import logStreamPlugin from './packem_shared/logStreamPlugin-CqvZ17kd.mjs';
 import { planViteRemoteBindings, remoteBindingsCleanupPlugin, withRemoteBindings } from './packem_shared/planViteRemoteBindings-QN5ncUS1.mjs';
+import { lunoraSolutionFinders } from './packem_shared/lunoraSolutionFinder-BKEAiUJP.mjs';
+export { lunoraSolutionFinder } from './packem_shared/lunoraSolutionFinder-BKEAiUJP.mjs';
 import { studioPlugin } from './packem_shared/STUDIO_PATH-5ppCdBHa.mjs';
 export { STUDIO_PATH, buildStudioUrl } from './packem_shared/STUDIO_PATH-5ppCdBHa.mjs';
 import { withWorkerStartupHint } from './packem_shared/WORKER_STARTUP_HINT-DhsXUW8k.mjs';
@@ -82,6 +84,19 @@ const frameworkDetectPlugin = (options, context) => {
   };
 };
 
+const resolveOverlayOption = (overlay) => {
+  if (overlay === false) {
+    return false;
+  }
+  const userOverlay = overlay === true || overlay === void 0 ? {} : overlay;
+  return {
+    ...userOverlay,
+    // After the spread + nullish-coalesce so an explicit `undefined` from the
+    // user doesn't erase Lunora's default (the spread would otherwise win).
+    forwardedConsoleMethods: userOverlay.forwardedConsoleMethods ?? ["error", "warn"],
+    solutionFinders: [...lunoraSolutionFinders, ...userOverlay.solutionFinders ?? []]
+  };
+};
 const resolveOptions = (options) => {
   const input = options ?? {};
   const schemaDirectory = input.schemaDir ?? "lunora";
@@ -93,21 +108,12 @@ const resolveOptions = (options) => {
   } else {
     cloudflareOption = input.cloudflare;
   }
-  const overlayDefaults = { forwardedConsoleMethods: ["error", "warn"] };
-  let overlayOption;
-  if (input.overlay === false) {
-    overlayOption = false;
-  } else if (input.overlay === true || input.overlay === void 0) {
-    overlayOption = { ...overlayDefaults };
-  } else {
-    overlayOption = { ...overlayDefaults, ...input.overlay };
-  }
   return {
     apiSpec: input.apiSpec ?? "openapi",
     cloudflare: cloudflareOption,
     studio: input.studio ?? true,
     generatedDir: input.generatedDir ?? `${schemaDirectory}/_generated`,
-    overlay: overlayOption,
+    overlay: resolveOverlayOption(input.overlay),
     projectRoot: input.projectRoot ?? process.cwd(),
     schemaDir: schemaDirectory,
     validateWrangler: input.validateWrangler ?? true
@@ -154,4 +160,4 @@ const lunora = (options) => {
 };
 const VERSION = "0.0.0";
 
-export { VERSION, codegenPlugin, containerLogsPlugin, createCommandProbe, devVariablesPlugin, frameworkComposePlugin, logStreamPlugin, lunora, planViteRemoteBindings, remoteBindingsCleanupPlugin, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };
+export { VERSION, codegenPlugin, containerLogsPlugin, createCommandProbe, devVariablesPlugin, frameworkComposePlugin, logStreamPlugin, lunora, lunoraSolutionFinders, planViteRemoteBindings, remoteBindingsCleanupPlugin, resolveOverlayOption, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };

package/dist/packem_shared/lunoraSolutionFinder-BKEAiUJP.mjs

@@ -0,0 +1,17 @@
+import { findLunoraSolution } from '@lunora/codegen';
+
+const lunoraSolutionFinder = {
+  // Synchronous body wrapped in `Promise.resolve` rather than `async`: the
+  // overlay's `handle` contract is promise-returning, but `require-await` is on
+  // for src and there's nothing to await here.
+  handle: (error) => {
+    const message = typeof error.message === "string" ? error.message : "";
+    const solution = findLunoraSolution(message);
+    return Promise.resolve(solution ? { body: solution.body, header: solution.header } : void 0);
+  },
+  name: "lunora",
+  priority: 100
+};
+const lunoraSolutionFinders = [lunoraSolutionFinder];
+
+export { lunoraSolutionFinder, lunoraSolutionFinders };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/vite",
-  "version": "1.0.0-alpha.19",
+  "version": "1.0.0-alpha.20",
   "description": "The Lunora Vite plugin: codegen, type sync, wrangler validation, and an error overlay over @cloudflare/vite-plugin",
   "keywords": [
     "cloudflare",
@@ -46,8 +46,8 @@
   },
   "dependencies": {
     "@cloudflare/vite-plugin": "1.42.0",
-    "@lunora/codegen": "1.0.0-alpha.12",
-    "@lunora/config": "1.0.0-alpha.19",
+    "@lunora/codegen": "1.0.0-alpha.13",
+    "@lunora/config": "1.0.0-alpha.20",
     "@visulima/vite-overlay": "2.0.0-alpha.35",
     "jsonc-parser": "^3.3.1",
     "ts-morph": "^28.0.0"