@foldkit/vite-plugin 0.20.2 → 0.21.0-canary.51d0d002f20c

package/README.md

@@ -1,6 +1,6 @@
 # @foldkit/vite-plugin
 
-Vite plugin for Foldkit: view identity branding for the differ, plus hot module reloading with Model preservation.
+Vite plugin for Foldkit: view identity branding for the differ, plus state-preserving live reload.
 
 ## Installation
 
@@ -34,7 +34,7 @@ This plugin supplies that identity. At build time, in dev and production alike,
 
 Foldkit core modules are never instrumented, and functions that never return vnodes are wrapped inertly. Builds without this plugin fall back to positional matching plus keys, where branch points need hand-written keys.
 
-## Hot module reloading
+## State-preserving live reload
 
 When you save a file during development, the plugin:
 
@@ -51,7 +51,7 @@ The plugin uses Vite's WebSocket connection to communicate between the dev serve
 - **On file change**: The browser sends the current Model to the Vite server for preservation.
 - **On reload**: The browser requests the preserved Model from the server and initializes the Foldkit Runtime with it.
 
-The Model survives hot reloads but clears on a manual browser refresh, so a refresh still resets the application.
+The Model survives development reloads but clears on a manual browser refresh, so a refresh still resets the application.
 
 ## Server rendering dev host
 

package/dist/build.d.ts

@@ -23,26 +23,24 @@ export type FoldkitPrerenderOptions = Readonly<{
 }>;
 /** How `vite build` builds a server entry and what it generates from it. */
 export type FoldkitBuildOptions = Readonly<{
-    /**
-     * The module the server build starts from. Defaults to the `serverEntry`
-     * itself, which is what a generated site wants. Point it at a host module
-     * when the deployment serves requests through one, such as an HTTP server or
-     * a Worker that imports the entry and calls `renderPage`.
-     *
-     * A build that also generates pages needs `renderPage` and, unless the paths
-     * are configured here, `prerenderPaths` on whichever module this names.
-     */
-    entry?: string;
     /** Where the browser build is written. */
     clientOutDir?: string;
     /** Where the server build is written. */
     serverOutDir?: string;
+    /**
+     * The `id` of the empty container in `index.html` the fetch handler
+     * replaces. Defaults to `'root'`. The aggregate plugin copies
+     * `ssr.containerId` here.
+     */
+    containerId?: string;
     /**
      * Generate static HTML for a set of URLs after both builds. `true` takes the
      * paths from the entry's `prerenderPaths` export.
      */
     prerender?: boolean | FoldkitPrerenderOptions;
 }>;
+/** Vite module id of the fetch handler Foldkit emits as the server entry. */
+export declare const FOLDKIT_FETCH_MODULE_ID = "virtual:foldkit/fetch";
 /**
  * What the build produced, written beside the server bundle for whatever
  * deploys it.
@@ -73,6 +71,11 @@ export declare const FoldkitBuildManifest: Schema.Struct<{
     readonly serverEntry: Schema.String;
     /** Every path this build generated a page for, in the order it generated. */
     readonly prerendered: Schema.$Array<Schema.String>;
+    /**
+     * How a request-time host should run the server entry. Always `'fetch'`:
+     * the entry is a Web `fetch` handler, not a Node process.
+     */
+    readonly host: Schema.optional<Schema.Literals<readonly ["fetch"]>>;
 }>;
 /**
  * What the build produced, written beside the server bundle for whatever
@@ -96,14 +99,14 @@ export declare const renderTargetFor: (clientDirectory: string, path: string, or
     file: string;
 }>;
 /**
- * Builds the server entry alongside the browser build, and generates static
- * HTML from it, inside one `vite build`.
+ * Builds a Web `fetch` handler alongside the browser build, and generates
+ * static HTML from the server entry, inside one `vite build`.
  *
  * Vite drives both environments and every host plugin composes with them, so a
  * deployment target that runs `vite build` gets the whole application rather
  * than the browser half. The generated pages take their template from the
  * browser build's own output, so generating twice over one build produces the
- * same pages.
+ * same pages. The server bundle's default export is `{ fetch }`.
  */
 export declare const foldkitBuild: (serverEntry: string, options?: FoldkitBuildOptions) => Plugin;
 //# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAE,MAAM,QAAQ,CAAA;AAGtC,OAAO,QAAiD,MAAM,WAAW,CAAA;AAEzE,OAAO,KAAK,EAGV,MAAM,EAEP,MAAM,MAAM,CAAA;AAEb,mEAAmE;AACnE,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAA;CAC9C,CAAC,CAAA;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;IAEH;;;;OAIG;;IAEH,+EAA+E;;IAE/E,2DAA2D;;IAE3D,6EAA6E;;EAE7E,CAAA;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAcnE,eAAO,MAAM,YAAY,SACjB,MAAM,aACD,MAAM,YACR,OAAO,QAAQ,KACvB,MAQF,CAAA;AA2FD,eAAO,MAAM,eAAe,oBACT,MAAM,QACjB,MAAM,UACJ,MAAM,YACL,OAAO,QAAQ,KACvB,QAAQ,CAAC;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA0CrC,CAAA;AA+DD;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,gBACV,MAAM,YACV,mBAAmB,KAC3B,MA8MF,CAAA"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAE,MAAM,QAAQ,CAAA;AAGtC,OAAO,QAA8B,MAAM,WAAW,CAAA;AAEtD,OAAO,KAAK,EAGV,MAAM,EAEP,MAAM,MAAM,CAAA;AAEb,mEAAmE;AACnE,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAA;CAC9C,CAAC,CAAA;AAEF,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,0BAA0B,CAAA;AAE9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;IAEH;;;;OAIG;;IAEH,+EAA+E;;IAE/E,2DAA2D;;IAE3D,6EAA6E;;IAE7E;;;OAGG;;EAEH,CAAA;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAcnE,eAAO,MAAM,YAAY,SACjB,MAAM,aACD,MAAM,YACR,OAAO,QAAQ,KACvB,MAQF,CAAA;AAwFD,eAAO,MAAM,eAAe,oBACT,MAAM,QACjB,MAAM,UACJ,MAAM,YACL,OAAO,QAAQ,KACvB,QAAQ,CAAC;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA0CrC,CAAA;AA4GD;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,gBACV,MAAM,YACV,mBAAmB,KAC3B,MAoOF,CAAA"}

package/dist/build.js

@@ -1,7 +1,9 @@
 import { Array, Schema } from 'effect';
 import { mkdir, writeFile } from 'node:fs/promises';
-import nodePath, { basename, dirname, extname, resolve } from 'node:path';
+import nodePath, { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+/** Vite module id of the fetch handler Foldkit emits as the server entry. */
+export const FOLDKIT_FETCH_MODULE_ID = 'virtual:foldkit/fetch';
 /**
  * What the build produced, written beside the server bundle for whatever
  * deploys it.
@@ -32,6 +34,11 @@ export const FoldkitBuildManifest = Schema.Struct({
     serverEntry: Schema.String,
     /** Every path this build generated a page for, in the order it generated. */
     prerendered: Schema.Array(Schema.String),
+    /**
+     * How a request-time host should run the server entry. Always `'fetch'`:
+     * the entry is a Web `fetch` handler, not a Node process.
+     */
+    host: Schema.optional(Schema.Literals(['fetch'])),
 });
 const MANIFEST_SCHEMA_VERSION = 1;
 // Relative and POSIX so the manifest describes a layout rather than this
@@ -55,10 +62,8 @@ const MANIFEST_FILE_NAME = 'foldkit.build.json';
 const DEFAULT_CLIENT_OUT_DIR = 'dist/client';
 const DEFAULT_SERVER_OUT_DIR = 'dist/server';
 const DEFAULT_PRERENDER_ORIGIN = 'http://localhost';
-// The chunk is named after the module it builds, which is what
-// `vite build --ssr <file>` writes, so a host that starts `dist/server/main.js`
-// keeps starting the same file.
-const serverChunkName = (entry) => basename(entry, extname(entry));
+const FETCH_CHUNK_NAME = 'fetch';
+const RESOLVED_FETCH_MODULE_ID = `\0${FOLDKIT_FETCH_MODULE_ID}`;
 // The chunk built from the configured entry, by name rather than by position.
 //
 // An SSR environment can carry more than one input, and prerendering imports
@@ -177,21 +182,55 @@ const captures = (() => {
     registry[CAPTURES] = fresh;
     return fresh;
 })();
+const fetchModuleSource = (serverEntry, template, containerId) => {
+    const containerLiteral = containerId === undefined ? 'undefined' : JSON.stringify(containerId);
+    // NOTE: `export *` re-exports whatever the application entry actually names,
+    // so a missing `prerenderPaths` is absent rather than a Vite undefined-import
+    // warning.
+    return `${[
+        `import { handleRequest } from 'foldkit/experimental/server'`,
+        `import * as server from ${JSON.stringify(serverEntry)}`,
+        `export * from ${JSON.stringify(serverEntry)}`,
+        `const template = ${JSON.stringify(template)}`,
+        `const containerId = ${containerLiteral}`,
+        `export default {`,
+        `  fetch(request) {`,
+        `    return handleRequest(request, {`,
+        `      renderPage: server.renderPage,`,
+        `      template,`,
+        `      containerId,`,
+        `    })`,
+        `  },`,
+        `}`,
+        ``,
+    ].join('\n')}`;
+};
+// The template is what the browser build emitted in this same `vite build`,
+// never a file on disk: `dist/client/index.html` could only be the previous
+// build's shell with its old asset hashes, and the source `index.html` still
+// names `/src/entry.ts`. Either would bundle into a handler that serves a
+// page which cannot hydrate, from a build that reported success.
+const templateForFetchModule = (capturedTemplate) => {
+    if (capturedTemplate === undefined) {
+        throw new Error('[foldkit] the browser build has not emitted index.html, so the fetch handler has no template to render into. Build the "client" environment before "ssr", and give the client an HTML entry.');
+    }
+    return capturedTemplate;
+};
 /**
- * Builds the server entry alongside the browser build, and generates static
- * HTML from it, inside one `vite build`.
+ * Builds a Web `fetch` handler alongside the browser build, and generates
+ * static HTML from the server entry, inside one `vite build`.
  *
  * Vite drives both environments and every host plugin composes with them, so a
  * deployment target that runs `vite build` gets the whole application rather
  * than the browser half. The generated pages take their template from the
  * browser build's own output, so generating twice over one build produces the
- * same pages.
+ * same pages. The server bundle's default export is `{ fetch }`.
  */
 export const foldkitBuild = (serverEntry, options = {}) => {
-    const entry = options.entry ?? serverEntry;
     const clientOutDir = options.clientOutDir ?? DEFAULT_CLIENT_OUT_DIR;
     const serverOutDir = options.serverOutDir ?? DEFAULT_SERVER_OUT_DIR;
     const prerender = prerenderOptionsFrom(options.prerender ?? false);
+    const containerId = prerender?.containerId ?? options.containerId;
     // Prerendering imports the server bundle and runs it in the build process,
     // with the build's own privileges. That module is the application's own code
     // and its dependencies, built from the configured entry, and is trusted on
@@ -235,6 +274,7 @@ export const foldkitBuild = (serverEntry, options = {}) => {
             server: manifestPath(builder.config.root, serverOutDir),
             serverEntry: entryFileName,
             prerendered,
+            host: 'fetch',
         });
         await writeFile(resolve(serverDirectory, MANIFEST_FILE_NAME), `${JSON.stringify(manifest, undefined, 2)}\n`);
         builder.config.logger.info(`  wrote ${MANIFEST_FILE_NAME}`);
@@ -247,7 +287,7 @@ export const foldkitBuild = (serverEntry, options = {}) => {
     // describes is what lets the finalizing instance read what the others
     // emitted, and what lets finalization work whether this plugin orchestrates
     // the environments or a host does.
-    const key = [clientOutDir, serverOutDir, entry].join('\u0000');
+    const key = [clientOutDir, serverOutDir, serverEntry].join('\u0000');
     const captured = (root) => {
         const existing = captures.get(`${root}\u0000${key}`);
         if (existing !== undefined) {
@@ -277,6 +317,25 @@ export const foldkitBuild = (serverEntry, options = {}) => {
     return {
         name: 'foldkit:build',
         apply: 'build',
+        api: {
+            host: 'fetch',
+            serverEntry,
+            fetchModuleId: FOLDKIT_FETCH_MODULE_ID,
+        },
+        resolveId(id) {
+            if (id === FOLDKIT_FETCH_MODULE_ID) {
+                return RESOLVED_FETCH_MODULE_ID;
+            }
+            return undefined;
+        },
+        load(id) {
+            if (id !== RESOLVED_FETCH_MODULE_ID) {
+                return;
+            }
+            const state = captured(this.environment.config.root);
+            const template = templateForFetchModule(state.template);
+            return fetchModuleSource(serverEntry, template, containerId);
+        },
         // NOTE: `writeBundle` rather than `generateBundle`: Vite's own HTML plugin
         // emits `index.html` from a `generateBundle` hook of its own, and hook
         // order between plugins decides whether that asset exists yet. By
@@ -292,7 +351,7 @@ export const foldkitBuild = (serverEntry, options = {}) => {
                 return;
             }
             if (this.environment.name === 'ssr') {
-                state.serverEntryFile = serverEntryFile(outputs, serverChunkName(entry));
+                state.serverEntryFile = serverEntryFile(outputs, FETCH_CHUNK_NAME);
             }
         },
         config: userConfig => {
@@ -303,7 +362,9 @@ export const foldkitBuild = (serverEntry, options = {}) => {
                 build: {
                     ssr: true,
                     outDir: serverOutDir,
-                    rollupOptions: { input: { [serverChunkName(entry)]: entry } },
+                    rollupOptions: {
+                        input: { [FETCH_CHUNK_NAME]: FOLDKIT_FETCH_MODULE_ID },
+                    },
                 },
             };
             // NOTE: a host framework that orchestrates its own environments owns

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { Plugin } from 'vite';
 import { type FoldkitBuildOptions } from './build.js';
 import { type FoldkitSsrOptions } from './ssr.js';
 export { type BrandDistResult, brandDistDirectory } from './brandDist.js';
-export { FoldkitBuildManifest, type FoldkitBuildOptions, type FoldkitPrerenderOptions, foldkitBuild, } from './build.js';
+export { FOLDKIT_FETCH_MODULE_ID, FoldkitBuildManifest, type FoldkitBuildOptions, type FoldkitPrerenderOptions, foldkitBuild, } from './build.js';
 export { type FoldkitSsrOptions, foldkitSsr } from './ssr.js';
 export { type ViewIdentityTransformResult, foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 /** Options for the `foldkit` Vite plugin. */
@@ -15,19 +15,22 @@ export type FoldkitPluginOptions = Readonly<{
      */
     devToolsMcpPort?: number;
     /**
-     * Serve server-rendered pages from the Vite dev server. When set, `vite`
-     * passes HTML navigations that fall through Vite, plus non-GET requests, to
-     * `renderPage` from the module at `ssr.serverEntry`. When `undefined` (the
-     * default), the dev server serves the client entry only.
+     * Serve server-rendered pages from the Vite dev server, and, with
+     * `ssr.build`, emit a Web `fetch` handler as the server bundle. When
+     * set, `vite` passes HTML navigations that fall through Vite, plus
+     * non-GET requests, to `renderPage` from the module at
+     * `ssr.serverEntry`. When `undefined` (the default), the dev server
+     * serves the client entry only.
      */
-    ssr?: Omit<FoldkitSsrOptions, 'buildId'> & Readonly<{
+    ssr?: Omit<FoldkitSsrOptions, 'buildId' | 'quietStandDown'> & Readonly<{
         /**
-         * Build the server entry alongside the browser build, and generate static
-         * HTML from it, inside this project's own `vite build`. `true` builds it
-         * with the default output directories and generates nothing.
+         * Build a Web `fetch` handler alongside the browser build, and generate
+         * static HTML from the server entry, inside this project's own
+         * `vite build`. The handler is the server bundle: Node and Workers
+         * both run it. `true` builds it with the default output directories
+         * and generates nothing.
          *
-         * When this is absent, `vite build` builds the browser bundle only and
-         * the server build is a separate command the deployment runs itself.
+         * When this is absent, `vite build` builds the browser bundle only.
          */
         build?: boolean | FoldkitBuildOptions;
     }>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EACV,MAAM,EAIP,MAAM,MAAM,CAAA;AAGb,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,YAAY,CAAA;AAGnE,OAAO,EAAE,KAAK,iBAAiB,EAAc,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EACL,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC7D,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;IACxB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,CAAC,GACtC,QAAQ,CAAC;QACP;;;;;;;WAOG;QACH,KAAK,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAA;KACtC,CAAC,CAAA;IACJ;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AA+mBF,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CAsFxE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EACV,MAAM,EAIP,MAAM,MAAM,CAAA;AAGb,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,YAAY,CAAA;AAGnE,OAAO,EAAE,KAAK,iBAAiB,EAAc,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC7D,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;IACxB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,gBAAgB,CAAC,GACzD,QAAQ,CAAC;QACP;;;;;;;;WAQG;QACH,KAAK,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAA;KACtC,CAAC,CAAA;IACJ;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AAonBF,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CAuFxE,CAAA"}

package/dist/index.js

@@ -1,6 +1,6 @@
 import { Array, Console, Data, Duration, Effect, Exit, Fiber, HashMap, HashSet, Match, Option, Predicate, Queue, Ref, Schedule, Schema, Stream, pipe, } from 'effect';
 import { Event as DevToolsEvent, EventFrame, RequestFrame, Response, ResponseFrame, } from 'foldkit/devtools-protocol';
-import { PreserveModelMessage, RequestModelMessage, RestoreModelMessage, } from 'foldkit/hmr-protocol';
+import { PreserveModelMessage, RequestModelMessage, RestoreModelMessage, } from 'foldkit/model-preservation';
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
@@ -10,7 +10,7 @@ import { devToolsOverlayPlugin } from './devToolsOverlay.js';
 import { foldkitSsr } from './ssr.js';
 import { foldkitViewIdentity } from './viewIdentity.js';
 export { brandDistDirectory } from './brandDist.js';
-export { FoldkitBuildManifest, foldkitBuild, } from './build.js';
+export { FOLDKIT_FETCH_MODULE_ID, FoldkitBuildManifest, foldkitBuild, } from './build.js';
 export { foldkitSsr } from './ssr.js';
 export { foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 // NOTE: Vite's dep optimizer scans the consumer's source for `effect`
@@ -41,6 +41,7 @@ const FORCE_INCLUDED_EFFECT_NAMESPACES = [
     'effect/HashMap',
     'effect/HashSet',
     'effect/Layer',
+    'effect/Logger',
     'effect/Match',
     'effect/Number',
     'effect/Option',
@@ -114,26 +115,26 @@ const makeState = Effect.gen(function* () {
 const encodeResponseFrameJson = Schema.encodeUnknownSync(Schema.fromJsonString(ResponseFrame));
 // HANDLERS
 const handlePreserveModelReceived = (state, payload) => Exit.match(Schema.decodeUnknownExit(PreserveModelMessage)(payload), {
-    onFailure: error => Console.warn('[foldkit:hmr] failed to decode preserve-model payload', error),
-    onSuccess: ({ id, model, isHmrReload }) => Ref.update(state.preservedModels, current => {
-        const existingFlag = Option.exists(HashMap.get(current, id), ({ isHmrReload }) => isHmrReload);
+    onFailure: error => Console.warn('[foldkit:preserve] failed to decode preserve-model payload', error),
+    onSuccess: ({ id, model, isReloadFlush }) => Ref.update(state.preservedModels, current => {
+        const existingFlag = Option.exists(HashMap.get(current, id), ({ isReloadFlush }) => isReloadFlush);
         const entry = {
             model,
-            isHmrReload: isHmrReload === true || existingFlag,
+            isReloadFlush: isReloadFlush === true || existingFlag,
         };
         return HashMap.set(current, id, entry);
     }),
 });
 const handleRequestModelReceived = (server, state, payload) => Exit.match(Schema.decodeUnknownExit(RequestModelMessage)(payload), {
-    onFailure: error => Console.warn('[foldkit:hmr] failed to decode request-model payload', error),
+    onFailure: error => Console.warn('[foldkit:preserve] failed to decode request-model payload', error),
     onSuccess: ({ id }) => Effect.gen(function* () {
         const current = yield* Ref.get(state.preservedModels);
         const sendRestore = (model) => Effect.sync(() => server.ws.send('foldkit:restore-model', Schema.encodeUnknownSync(RestoreModelMessage)(RestoreModelMessage.make({ id, model }))));
         yield* Option.match(HashMap.get(current, id), {
             onNone: () => sendRestore(undefined),
             onSome: entry => {
-                if (entry.isHmrReload) {
-                    const served = { ...entry, isHmrReload: false };
+                if (entry.isReloadFlush) {
+                    const served = { ...entry, isReloadFlush: false };
                     return Ref.update(state.preservedModels, HashMap.set(id, served)).pipe(Effect.flatMap(() => sendRestore(entry.model)));
                 }
                 return Ref.update(state.preservedModels, HashMap.remove(id)).pipe(Effect.flatMap(() => sendRestore(undefined)));
@@ -141,7 +142,7 @@ const handleRequestModelReceived = (server, state, payload) => Exit.match(Schema
         });
     }),
 });
-const handleHotUpdateFired = (state) => Ref.update(state.preservedModels, current => HashMap.map(current, entry => ({ ...entry, isHmrReload: true })));
+const handleHotUpdateFired = (state) => Ref.update(state.preservedModels, current => HashMap.map(current, entry => ({ ...entry, isReloadFlush: true })));
 const handleBrowserEventFrameReceived = (state, data, client) => Exit.match(Schema.decodeUnknownExit(EventFrame)(data), {
     onFailure: error => Console.warn('[foldkit:devTools] failed to decode browser event frame', error),
     onSuccess: frame => DevToolsEvent.match(frame.event, {
@@ -315,7 +316,7 @@ const main = (server, events, options) => Effect.gen(function* () {
     };
     yield* registerViteWsHandlers(server, state, enqueue);
     // NOTE: Forked rather than awaited because binding the relay can retry for
-    // seconds. The HMR bridge is independent of the relay, and the runtime
+    // seconds. Model preservation is independent of the relay, and the runtime
     // gives up on its boot-time model request in well under a second, so
     // sequencing the dispatch loop behind the bind would cost model
     // preservation whenever the port is contended.
@@ -327,8 +328,8 @@ const main = (server, events, options) => Effect.gen(function* () {
 // PLUGIN ENTRY
 /**
  * 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
+ * DevTools overlay injection (dev and build), plus Model preservation across
+ * reloads and the optional DevTools MCP relay (dev only). Returned as
  * an array; Vite flattens nested plugin arrays, so `plugins: [foldkit()]`
  * keeps working.
  */
@@ -337,15 +338,19 @@ const main = (server, events, options) => Effect.gen(function* () {
 // that needs them to differ still can.
 const withContainerId = (build, containerId) => {
     const options = build === true ? {} : build;
-    if (containerId === undefined || options.prerender === undefined) {
+    if (containerId === undefined) {
         return options;
     }
+    const withContainer = { ...options, containerId };
+    if (options.prerender === undefined) {
+        return withContainer;
+    }
     const prerender = options.prerender === true ? {} : options.prerender;
     if (prerender === false) {
-        return options;
+        return withContainer;
     }
     return {
-        ...options,
+        ...withContainer,
         prerender: { containerId, ...prerender },
     };
 };
@@ -366,8 +371,8 @@ export const foldkit = (options = {}) => {
             return Fiber.interrupt(fiber);
         }
     });
-    const hmrPlugin = {
-        name: 'foldkit-hmr',
+    const reloadPlugin = {
+        name: 'foldkit',
         apply: 'serve',
         config: userConfig => ({
             optimizeDeps: {
@@ -401,7 +406,7 @@ export const foldkit = (options = {}) => {
         foldkitBuildToken(options.buildId),
         foldkitViewIdentity(),
         devToolsOverlayPlugin(),
-        hmrPlugin,
+        reloadPlugin,
     ];
     if (options.ssr === undefined) {
         return shared;
@@ -410,6 +415,7 @@ export const foldkit = (options = {}) => {
     const servePages = foldkitSsr({
         ...ssr,
         ...(options.buildId === undefined ? {} : { buildId: options.buildId }),
+        quietStandDown: build !== undefined && build !== false,
     });
     if (build === undefined || build === false) {
         return [...shared, servePages];

package/dist/ssr.d.ts

@@ -36,6 +36,12 @@ export type FoldkitSsrOptions = Readonly<{
      * The value is public in rendered HTML, so it must not be a secret.
      */
     buildId?: string;
+    /**
+     * Skip the stand-down warning when the `ssr` environment is not runnable.
+     * The aggregate plugin sets this when `ssr.build` is on, because production
+     * still needs `serverEntry` and the host is supposed to serve.
+     */
+    quietStandDown?: boolean;
 }>;
 /**
  * Serves server-rendered pages from the Vite dev server.

package/dist/ssr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../src/ssr.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAGV,MAAM,EAGP,MAAM,MAAM,CAAA;AAIb,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AAwsBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,YAAa,iBAAiB,KAAG,MAgEvD,CAAA"}
+{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../src/ssr.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAGV,MAAM,EAGP,MAAM,MAAM,CAAA;AAIb,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC,CAAA;AAwsBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,YAAa,iBAAiB,KAAG,MAgEvD,CAAA"}

package/dist/ssr.js

@@ -497,11 +497,11 @@ export const foldkitSsr = (options) => {
             // bindings the deployed entry holds, while the deployment it is standing
             // in for renders in workerd.
             if (!isRunnable(server.environments.ssr)) {
-                server.config.logger.warn('[foldkit] the "ssr" environment is not runnable, so another plugin owns' +
-                    ' server-side execution. Dev-time server rendering is off and page' +
-                    ' requests fall through to that host, which renders through the same' +
-                    ' server entry. Remove `ssr.serverEntry` from the foldkit plugin to' +
-                    ' silence this.');
+                if (options.quietStandDown !== true) {
+                    server.config.logger.warn('[foldkit] the "ssr" environment is not runnable, so another plugin owns' +
+                        " server-side execution. Dev-time rendering through Foldkit's Vite" +
+                        ' middleware is off; page requests go to that host.');
+                }
                 return;
             }
             const requestUrls = new WeakMap();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.20.2",
-  "description": "Vite plugin for Foldkit hot module reloading with state preservation",
+  "version": "0.21.0-canary.51d0d002f20c",
+  "description": "Vite plugin for Foldkit with state-preserving live reload",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,8 +16,8 @@
     "dist"
   ],
   "peerDependencies": {
-    "effect": "4.0.0-rc.112",
-    "foldkit": ">=0.153.0",
+    "effect": "4.0.0-rc.115",
+    "foldkit": "0.159.0-canary.51d0d002f20c",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "dependencies": {
@@ -27,21 +27,21 @@
   "devDependencies": {
     "@types/node": "^26.4.0",
     "@types/ws": "^8.18.1",
-    "effect": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.115",
     "happy-dom": "^20.11.13",
     "rimraf": "^6.1.3",
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vite7": "npm:vite@^7.3.6",
     "vitest": "^4.1.11",
-    "foldkit": "0.158.2"
+    "foldkit": "0.159.0-canary.51d0d002f20c"
   },
   "keywords": [
     "vite",
     "vite-plugin",
     "foldkit",
-    "hmr",
-    "hot-reload"
+    "live-reload",
+    "state-preservation"
   ],
   "author": "Devin Jameson",
   "license": "MIT",