@foldkit/vite-plugin 0.11.2 → 0.12.0

package/README.md

@@ -53,6 +53,12 @@ The plugin uses Vite's WebSocket connection to communicate between the dev serve
 
 Model is preserved across hot reloads but cleared on manual browser refreshes, giving you control over when to reset your app.
 
+## DevTools overlay
+
+When `@foldkit/devtools` is installed as a development dependency, the plugin mounts its overlay automatically during development and leaves it out of production builds. No application import or `devTools.overlay` field is needed.
+
+To include the overlay in production, list `@foldkit/devtools` in regular `dependencies` and set `devTools.show` to `'Always'`. Dependency placement controls whether Vite includes the overlay, and `show` controls whether the Foldkit runtime mounts it.
+
 ## DevTools MCP relay
 
 Pass `devToolsMcpPort` to enable the relay that exposes your running Foldkit app to AI agents via the [`@foldkit/devtools-mcp`](https://www.npmjs.com/package/@foldkit/devtools-mcp) MCP server:

package/dist/devToolsOverlay.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from 'vite';
+/**
+ * Determines whether the Vite integration should include the DevTools overlay.
+ * Development serves it whenever the package is installed. Production builds
+ * additionally require it in regular `dependencies`, which is the opt-in that
+ * keeps a development dependency out of the shipped bundle.
+ */
+export declare const shouldInjectDevToolsOverlay: (command: "serve" | "build", root: string) => boolean;
+/** Creates the Vite plugin that registers the appropriate DevTools overlay. */
+export declare const devToolsOverlayPlugin: () => Plugin;
+//# sourceMappingURL=devToolsOverlay.d.ts.map

package/dist/devToolsOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devToolsOverlay.d.ts","sourceRoot":"","sources":["../src/devToolsOverlay.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAmGlC;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GACtC,SAAS,OAAO,GAAG,OAAO,EAC1B,MAAM,MAAM,KACX,OAQF,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,QAAO,MA6CxC,CAAA"}

package/dist/devToolsOverlay.js

@@ -0,0 +1,122 @@
+import { Option, Record, Schema as S } from 'effect';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const DEV_TOOLS_PACKAGE_NAME = '@foldkit/devtools';
+const DEV_TOOLS_VITE_EXPORT = './vite';
+const DEV_TOOLS_OVERLAY_MODULE_ID = 'virtual:foldkit-devtools-overlay';
+const RESOLVED_DEV_TOOLS_OVERLAY_MODULE_ID = `\0${DEV_TOOLS_OVERLAY_MODULE_ID}`;
+const DEV_TOOLS_OVERLAY_MODULE_SOURCE = `
+import { overlay } from '@foldkit/devtools/vite'
+import { __setDevToolsOverlay } from 'foldkit/devtools-host'
+
+__setDevToolsOverlay(overlay)
+`;
+const ApplicationPackageJson = S.Struct({
+    dependencies: S.optional(S.Record(S.String, S.String)),
+});
+const DevToolsPackageJson = S.Struct({
+    exports: S.optional(S.Record(S.String, S.Unknown)),
+});
+const decodeApplicationPackageJson = S.decodeUnknownSync(ApplicationPackageJson);
+const decodeDevToolsPackageJson = S.decodeUnknownSync(DevToolsPackageJson);
+const readPackageJson = (decode, packageJsonPath) => {
+    try {
+        return Option.some(decode(JSON.parse(readFileSync(packageJsonPath, 'utf8'))));
+    }
+    catch {
+        return Option.none();
+    }
+};
+const findDirectoryUpward = (directory, isMatch) => {
+    if (isMatch(directory)) {
+        return Option.some(directory);
+    }
+    else {
+        const parent = dirname(directory);
+        if (parent === directory) {
+            return Option.none();
+        }
+        else {
+            return findDirectoryUpward(parent, isMatch);
+        }
+    }
+};
+// NOTE: `require.resolve` is not usable here. `@foldkit/devtools` is ESM-only
+// and declares no `require` condition, so resolution throws even when the
+// package is installed, and `resolve.paths` appends this module's own lookup
+// chain, which under pnpm includes the hoisted virtual store. Both would make
+// the answer depend on something other than what the application installed.
+const devToolsPackageJsonPath = (directory) => join(directory, 'node_modules', DEV_TOOLS_PACKAGE_NAME, 'package.json');
+const findDevToolsPackageJsonPath = (root) => findDirectoryUpward(resolve(root), directory => existsSync(devToolsPackageJsonPath(directory))).pipe(Option.map(devToolsPackageJsonPath));
+// NOTE: the virtual module imports `@foldkit/devtools/vite` statically, so an
+// installed copy that predates that export point would fail the build rather
+// than quietly skip the overlay. Injecting only when the export exists lets
+// the two packages be upgraded in either order.
+const hasDevToolsViteExport = (root) => findDevToolsPackageJsonPath(root).pipe(Option.flatMap(packageJsonPath => readPackageJson(decodeDevToolsPackageJson, packageJsonPath)), Option.flatMapNullishOr(packageJson => packageJson.exports), Option.exists(Record.has(DEV_TOOLS_VITE_EXPORT)));
+// NOTE: Vite's `root` is where `index.html` lives, which is not always the
+// package directory (an app may serve from a subdirectory). Walking up to the
+// nearest manifest keeps dependency placement meaningful for those layouts.
+const applicationPackageJsonPath = (directory) => join(directory, 'package.json');
+const findApplicationPackageJsonPath = (root) => findDirectoryUpward(resolve(root), directory => existsSync(applicationPackageJsonPath(directory))).pipe(Option.map(applicationPackageJsonPath));
+const isDevToolsProductionDependency = (root) => findApplicationPackageJsonPath(root).pipe(Option.flatMap(packageJsonPath => readPackageJson(decodeApplicationPackageJson, packageJsonPath)), Option.flatMapNullishOr(packageJson => packageJson.dependencies), Option.exists(Record.has(DEV_TOOLS_PACKAGE_NAME)));
+/**
+ * Determines whether the Vite integration should include the DevTools overlay.
+ * Development serves it whenever the package is installed. Production builds
+ * additionally require it in regular `dependencies`, which is the opt-in that
+ * keeps a development dependency out of the shipped bundle.
+ */
+export const shouldInjectDevToolsOverlay = (command, root) => {
+    if (!hasDevToolsViteExport(root)) {
+        return false;
+    }
+    else if (command === 'serve') {
+        return true;
+    }
+    else {
+        return isDevToolsProductionDependency(root);
+    }
+};
+/** Creates the Vite plugin that registers the appropriate DevTools overlay. */
+export const devToolsOverlayPlugin = () => {
+    let isInjectionEnabled = false;
+    return {
+        name: 'foldkit:devtools-overlay',
+        configResolved: config => {
+            isInjectionEnabled = shouldInjectDevToolsOverlay(config.command, config.root);
+        },
+        resolveId: id => {
+            if (id === DEV_TOOLS_OVERLAY_MODULE_ID) {
+                return RESOLVED_DEV_TOOLS_OVERLAY_MODULE_ID;
+            }
+            else {
+                return undefined;
+            }
+        },
+        load: id => {
+            if (id === RESOLVED_DEV_TOOLS_OVERLAY_MODULE_ID) {
+                return DEV_TOOLS_OVERLAY_MODULE_SOURCE;
+            }
+            else {
+                return undefined;
+            }
+        },
+        transformIndexHtml: {
+            order: 'pre',
+            handler: () => {
+                if (!isInjectionEnabled) {
+                    return;
+                }
+                return [
+                    {
+                        tag: 'script',
+                        attrs: {
+                            type: 'module',
+                        },
+                        children: `import '${DEV_TOOLS_OVERLAY_MODULE_ID}'`,
+                        injectTo: 'head-prepend',
+                    },
+                ];
+            },
+        },
+    };
+};

package/dist/index.d.ts

@@ -12,10 +12,11 @@ export type FoldkitPluginOptions = Readonly<{
     devToolsMcpPort?: number;
 }>;
 /**
- * Foldkit's Vite plugin set: the view-identity branding transform (dev and
- * build) plus the HMR bridge with state preservation and the optional
- * DevTools MCP relay (dev only). Returned as an array; Vite flattens nested
- * plugin arrays, so `plugins: [foldkit()]` keeps working.
+ * Foldkit's Vite plugin set: the view-identity branding transform and
+ * DevTools overlay injection (dev and build), plus the HMR bridge with state
+ * preservation and the optional DevTools MCP relay (dev only). Returned as
+ * an array; Vite flattens nested plugin arrays, so `plugins: [foldkit()]`
+ * keeps working.
  */
 export declare const foldkit: (options?: FoldkitPluginOptions) => Array<Plugin>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EACV,MAAM,EAIP,MAAM,MAAM,CAAA;AAKb,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EACL,KAAK,2BAA2B,EAChC,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAC,CAAA;AA+kBF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,UAAS,oBAAyB,KAAG,KAAK,CAAC,MAAM,CA6DxE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EACV,MAAM,EAIP,MAAM,MAAM,CAAA;AAMb,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EACL,KAAK,2BAA2B,EAChC,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAC,CAAA;AAglBF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,UAAS,oBAAyB,KAAG,KAAK,CAAC,MAAM,CA6DxE,CAAA"}

package/dist/index.js

@@ -4,6 +4,7 @@ import { PreserveModelMessage, RequestModelMessage, RestoreModelMessage, } from
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
+import { devToolsOverlayPlugin } from './devToolsOverlay.js';
 import { foldkitViewIdentity } from './viewIdentity.js';
 export { brandDistDirectory } from './brandDist.js';
 export { foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
@@ -18,6 +19,7 @@ export { foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 // source by `scripts/check-effect-prebundle.ts` (runs in `pnpm check`).
 const FORCE_INCLUDED_EFFECT_NAMESPACES = [
     'effect/Array',
+    'effect/Boolean',
     'effect/Cause',
     'effect/Clock',
     'effect/Context',
@@ -317,10 +319,11 @@ const main = (server, events, options) => Effect.gen(function* () {
 });
 // PLUGIN ENTRY
 /**
- * Foldkit's Vite plugin set: the view-identity branding transform (dev and
- * build) plus the HMR bridge with state preservation and the optional
- * DevTools MCP relay (dev only). Returned as an array; Vite flattens nested
- * plugin arrays, so `plugins: [foldkit()]` keeps working.
+ * Foldkit's Vite plugin set: the view-identity branding transform and
+ * DevTools overlay injection (dev and build), plus the HMR bridge with state
+ * preservation and the optional DevTools MCP relay (dev only). Returned as
+ * an array; Vite flattens nested plugin arrays, so `plugins: [foldkit()]`
+ * keeps working.
  */
 export const foldkit = (options = {}) => {
     const events = Effect.runSync(Queue.unbounded());
@@ -370,5 +373,5 @@ export const foldkit = (options = {}) => {
             return [];
         },
     };
-    return [foldkitViewIdentity(), hmrPlugin];
+    return [foldkitViewIdentity(), devToolsOverlayPlugin(), hmrPlugin];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Vite plugin for Foldkit hot module reloading with state preservation",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "effect": "4.0.0-beta.102",
+    "effect": "4.0.0-beta.103",
     "foldkit": "^0",
     "vite": "^7.0.0 || ^8.0.0"
   },
@@ -27,13 +27,13 @@
   "devDependencies": {
     "@types/node": "^25.9.3",
     "@types/ws": "^8.18.1",
-    "effect": "4.0.0-beta.102",
+    "effect": "4.0.0-beta.103",
     "happy-dom": "^20.10.4",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.9",
-    "foldkit": "0.133.0"
+    "foldkit": "0.139.0"
   },
   "keywords": [
     "vite",