@foldkit/vite-plugin 0.14.0 → 0.16.0

package/README.md

@@ -30,7 +30,7 @@ export default defineConfig({
 
 Foldkit's differ tracks two independent kinds of identity: user keys, which match siblings in dynamic lists, and a framework-managed identity, which decides whether a matched position is still the same thing. When the producing view function changes, the differ replaces the node instead of patching it, so DOM state cannot bleed across an identity change. Branches rendered inline by one view function share that function's identity and patch in place, exactly as same-type elements do in React; extracting the branches into named view functions makes them identity boundaries.
 
-This plugin supplies that identity. At build time, in dev and production alike, it wraps every function return in your application modules with a branding call that stamps returned vnodes with the function's id (module path plus function name), set-if-absent. Identity therefore attaches at view-function boundaries, and any branching syntax behaves the same: if/else, ternaries, Effect Match, switch statements, and pattern-matching libraries are all equivalent, because identity belongs to the function that produced the subtree, not to the branch that selected it.
+This plugin supplies that identity. At build time, in dev and production alike, it wraps every function return in your application modules with a branding call that stamps returned vnodes with the function's id (module path plus function name), set-if-absent. The identity is nothing else: it ships in the client bundle, so anything derived from the module's contents would be a published check against those contents. Identity therefore attaches at view-function boundaries, and any branching syntax behaves the same: if/else, ternaries, Effect Match, switch statements, and pattern-matching libraries are all equivalent, because identity belongs to the function that produced the subtree, not to the branch that selected it.
 
 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.
 
@@ -53,6 +53,45 @@ 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.
 
+## Server rendering dev host
+
+Pass `ssr` with the path to your server entry to render page requests through it during development:
+
+```typescript
+plugins: [foldkit({ ssr: { serverEntry: '/src/entry.server.ts' } })]
+```
+
+With this set, the dev server converts HTML page requests to Web `Request` values, passes them to the entry's `renderPage`, and serves the returned `Response`. The request URL retains Vite's configured `base` prefix and the browser's query string. Vite continues to serve the client entry, HMR, and assets, and the server entry runs through Vite's module graph, so edits to it apply without a restart. The client side of the handoff needs no plugin configuration: a server-rendered application's client entry calls `Runtime.hydrate` instead of `Runtime.run`. Hydration adopts matching DOM, rebuilds mismatched subtrees, and refuses an invalid or cross-deployment handoff. The option shapes only the dev server; production hosts import the built server entry themselves. See the [Server Rendering documentation](https://foldkit.dev/core/server-rendering) for the full contract.
+
+Vite retains ownership of configured proxy routes before Foldkit handles application requests. Vite's `server.cors` option applies to Vite-owned source modules, assets, and HMR. It does not add headers to application responses or answer their preflights. Preflight ownership follows `Access-Control-Request-Method`, so a preflight for an application `POST` reaches `renderPage` even when its path looks like an asset. An `OPTIONS` request without both `Origin` and `Access-Control-Request-Method` is not a preflight and also reaches `renderPage`. Define application CORS in `renderPage`, where development and the deployed host share one policy. Vite's `allowedHosts` check runs before proxy and application handling, including `OPTIONS` and methods the Web `Request` API cannot represent.
+
+## Build id
+
+A server-rendered build carries an id naming the deployment it came from. `renderToString` stamps it on the rendered root and `Runtime.hydrate` compares it before accessing the Flags payload text or adopting DOM, so a page served by an earlier deployment is refused rather than reconciled against a client that no longer means the same thing by it. Startup stops, and the page is contained: the document's body is marked `inert`, and a nondismissable modal shield covers its controls and existing top-layer content without closing author-owned dialogs. Nothing is moved, so no custom element reconnects and no frame reloads. This boundary blocks native page interaction; it is not a script or global-event sandbox. A client already running in an open tab is not rechecked when a deployment lands: the comparison happens when a client boots against a page.
+
+The plugin compiles the id into application code as `import.meta.env.FOLDKIT_BUILD_ID`, from its `buildId` option or from the `FOLDKIT_BUILD_ID` environment variable:
+
+```typescript
+plugins: [foldkit({ buildId: process.env.DEPLOYMENT_SHA })]
+```
+
+The entries pass it explicitly, because Vite externalizes an installed dependency from a server build, where a compile-time define never reaches the framework itself:
+
+```typescript
+// src/entry.server.ts
+Server.renderToString(config, {
+  flags,
+  buildId: import.meta.env.FOLDKIT_BUILD_ID,
+})
+
+// src/entry.ts
+Runtime.hydrate(application, { buildId: import.meta.env.FOLDKIT_BUILD_ID })
+```
+
+Nothing is derived from the project. Use a value the deployment already has, such as a commit, a release tag, or a container digest. Three rules govern it: the id is published in the HTML every visitor receives, so it must never contain a secret; it must identify one deployment, so two deployments can never share one; and the same value must reach the client build and the server build, which run as separate commands. A hydratable render given no id fails with `MissingBuildId`. Only a build takes the id from the deployment. The dev server compiles a fixed one because one live source session supplies both transforms and has no deployment identity to derive.
+
+The standalone `foldkitSsr({ serverEntry, buildId })` export compiles the same define for its server entry. When it runs in development without an explicit value, it uses the fixed development id too. The aggregate `foldkit({ buildId, ssr })` plugin passes its top-level value through automatically.
+
 ## 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.

package/dist/buildToken.d.ts

@@ -0,0 +1,26 @@
+import type { Plugin } from 'vite';
+/** The build id this build was given, from the plugin option or
+ *  `FOLDKIT_BUILD_ID`, or `undefined` when the deployment supplied neither.
+ *
+ * @internal Exported for tests.
+ */
+export declare const resolveBuildId: (configured?: string) => string | undefined;
+/** The value `import.meta.env.FOLDKIT_BUILD_ID` compiles to, or `undefined`
+ *  when a build was given no id and must refuse to render a hydratable page.
+ *
+ * @internal Exported for tests.
+ */
+export declare const buildIdForCommand: (command: "build" | "serve", configured?: string) => string | undefined;
+/**
+ * Compiles the deployment's build id into application code as
+ * `import.meta.env.FOLDKIT_BUILD_ID`, for the client entry and the server entry
+ * to hand to `Runtime.hydrate` and `renderToString`.
+ *
+ * A build takes the id from the `buildId` option or `FOLDKIT_BUILD_ID` and
+ * compiles nothing when it was given neither, so a hydratable render fails with
+ * `MissingBuildId` rather than serving a page hydration cannot place.
+ * Development serves a fixed id instead because one live source session
+ * supplies both transforms and has no deployment identity to derive.
+ */
+export declare const foldkitBuildToken: (buildId?: string) => Plugin;
+//# sourceMappingURL=buildToken.d.ts.map

package/dist/buildToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildToken.d.ts","sourceRoot":"","sources":["../src/buildToken.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAqClC;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,MAAM,KAAG,MAAM,GAAG,SAQ7D,CAAA;AAcD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,SAAS,OAAO,GAAG,OAAO,EAC1B,aAAa,MAAM,KAClB,MAAM,GAAG,SAMX,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,MAYnD,CAAA"}

package/dist/buildToken.js

@@ -0,0 +1,94 @@
+// The build id names the deployment a page came from. The server stamps it on
+// the rendered root, the client carries it, and hydration refuses a page whose
+// id is not its own before it adopts any DOM.
+//
+// Per-view identities cannot answer that question. They move when the view they
+// name changes, but what a view renders also depends on the constants it
+// imports, the configuration it reads, the dependencies it calls, and the
+// arguments its caller passes. A component whose own source is untouched renders
+// something different when its caller changes, and its identity is the one that
+// wins on the element, so a stale page's `<input name="email">` can otherwise be
+// adopted for a new build's `<input name="ssn">`, carrying what a visitor typed
+// into a field that submits under a different name.
+//
+// The id is supplied by the deployment rather than derived from the project.
+// Deriving it was tried and does not hold: a digest of the files under the Vite
+// root misses shared modules from elsewhere in a monorepo, untracked inputs, and
+// environment-derived configuration, so two deployments that render differently
+// can share an id; it moves when a build writes output the next build reads, so
+// one deployment can produce two ids; and hashing whatever files happen to sit
+// in the project turns a value published in HTML into an oracle for the secrets
+// among them. A value the deployment already has (a commit, a release tag, a
+// container digest) has none of those problems.
+//
+// This plugin only compiles the id into application code. Foldkit itself is an
+// ordinary dependency that Vite externalizes from a server build, where a
+// compile-time define never reaches it, so the id is handed to `renderToString`
+// and `Runtime.hydrate` explicitly rather than read from inside the framework.
+//
+// Development is compiled an id too. The dev SSR host renders through
+// `renderToString` like any other, and a hydratable render refuses to run
+// without one, so leaving development unnamed would fail every dev page
+// request.
+const BUILD_ID_ENVIRONMENT_VARIABLE = 'FOLDKIT_BUILD_ID';
+/** The build id this build was given, from the plugin option or
+ *  `FOLDKIT_BUILD_ID`, or `undefined` when the deployment supplied neither.
+ *
+ * @internal Exported for tests.
+ */
+export const resolveBuildId = (configured) => {
+    if (configured !== undefined && configured !== '') {
+        return configured;
+    }
+    const fromEnvironment = process.env[BUILD_ID_ENVIRONMENT_VARIABLE];
+    return fromEnvironment !== undefined && fromEnvironment !== ''
+        ? fromEnvironment
+        : undefined;
+};
+// The id development serves. Development is the one place a constant is right:
+// one live source session supplies both the server and client transforms rather
+// than producing independently deployable artifacts. A value that moved would
+// only make the dev server disagree with the tab already open against it. A
+// hydratable render still requires an id, so development has to be given one
+// rather than left without.
+//
+// It is exactly wrong for a build, which is why a build with no id is refused
+// rather than defaulted: two deployments sharing an id is the case the id
+// exists to catch.
+const DEVELOPMENT_BUILD_ID = 'development';
+/** The value `import.meta.env.FOLDKIT_BUILD_ID` compiles to, or `undefined`
+ *  when a build was given no id and must refuse to render a hydratable page.
+ *
+ * @internal Exported for tests.
+ */
+export const buildIdForCommand = (command, configured) => {
+    const resolved = resolveBuildId(configured);
+    if (resolved !== undefined) {
+        return resolved;
+    }
+    return command === 'serve' ? DEVELOPMENT_BUILD_ID : undefined;
+};
+/**
+ * Compiles the deployment's build id into application code as
+ * `import.meta.env.FOLDKIT_BUILD_ID`, for the client entry and the server entry
+ * to hand to `Runtime.hydrate` and `renderToString`.
+ *
+ * A build takes the id from the `buildId` option or `FOLDKIT_BUILD_ID` and
+ * compiles nothing when it was given neither, so a hydratable render fails with
+ * `MissingBuildId` rather than serving a page hydration cannot place.
+ * Development serves a fixed id instead because one live source session
+ * supplies both transforms and has no deployment identity to derive.
+ */
+export const foldkitBuildToken = (buildId) => ({
+    name: 'foldkit:build-token',
+    config: (_config, { command }) => {
+        const resolved = buildIdForCommand(command, buildId);
+        return resolved === undefined
+            ? {}
+            : {
+                define: {
+                    'import.meta.env.FOLDKIT_BUILD_ID': JSON.stringify(resolved),
+                },
+            };
+    },
+});

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import type { Plugin } from 'vite';
+import { type FoldkitSsrOptions } from './ssr.js';
 export { type BrandDistResult, brandDistDirectory } from './brandDist.js';
+export { type FoldkitSsrOptions, foldkitSsr } from './ssr.js';
 export { type ViewIdentityTransformResult, foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 /** Options for the `foldkit` Vite plugin. */
 export type FoldkitPluginOptions = Readonly<{
@@ -10,6 +12,27 @@ export type FoldkitPluginOptions = Readonly<{
      * the Foldkit DevTools MCP server.
      */
     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.
+     */
+    ssr?: Omit<FoldkitSsrOptions, 'buildId'>;
+    /**
+     * The deployment this build belongs to, compiled into application code as
+     * `import.meta.env.FOLDKIT_BUILD_ID` for the entries to pass to
+     * `renderToString` and `Runtime.hydrate`. Hydration compares it against the id
+     * the server stamped and refuses a page from another deployment rather than
+     * adopting it: startup stops and the page is contained, with the document's
+     * body marked `inert`.
+     *
+     * Defaults to the `FOLDKIT_BUILD_ID` environment variable. Use a value the
+     * deployment already has, such as a commit or a release tag, and give the
+     * client build and the server build the same one. It is published in the
+     * page, so it must not be a secret.
+     */
+    buildId?: string;
 }>;
 /**
  * Foldkit's Vite plugin set: the view-identity branding transform and

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;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;AAilBF;;;;;;GAMG;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;AAKb,OAAO,EAAE,KAAK,iBAAiB,EAAc,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,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,CAAA;IACxC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AAilBF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,UAAS,oBAAyB,KAAG,KAAK,CAAC,MAAM,CA+ExE,CAAA"}

package/dist/index.js

@@ -4,9 +4,12 @@ import { PreserveModelMessage, RequestModelMessage, RestoreModelMessage, } from
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
+import { foldkitBuildToken } from './buildToken.js';
 import { devToolsOverlayPlugin } from './devToolsOverlay.js';
+import { foldkitSsr } from './ssr.js';
 import { foldkitViewIdentity } from './viewIdentity.js';
 export { brandDistDirectory } from './brandDist.js';
+export { foldkitSsr } from './ssr.js';
 export { foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 // NOTE: Vite's dep optimizer scans the consumer's source for `effect`
 // imports and pre-bundles only those exports into a single `effect.js`
@@ -374,5 +377,23 @@ export const foldkit = (options = {}) => {
             return [];
         },
     };
-    return [foldkitViewIdentity(), devToolsOverlayPlugin(), hmrPlugin];
+    return options.ssr === undefined
+        ? [
+            foldkitBuildToken(options.buildId),
+            foldkitViewIdentity(),
+            devToolsOverlayPlugin(),
+            hmrPlugin,
+        ]
+        : [
+            foldkitBuildToken(options.buildId),
+            foldkitViewIdentity(),
+            devToolsOverlayPlugin(),
+            hmrPlugin,
+            foldkitSsr({
+                ...options.ssr,
+                ...(options.buildId === undefined
+                    ? {}
+                    : { buildId: options.buildId }),
+            }),
+        ];
 };

package/dist/ssr.d.ts

@@ -0,0 +1,53 @@
+import type { Plugin } from 'vite';
+/** Options for serving server-rendered pages from the Vite dev server. */
+export type FoldkitSsrOptions = Readonly<{
+    /**
+     * Module path of the server entry, resolved by Vite (e.g.
+     * `'/src/entry.server.ts'`). The module must export a `renderPage`
+     * function taking a Web `Request` and returning a
+     * `Promise<EntryResult>`.
+     */
+    serverEntry: string;
+    /**
+     * The `id` of the empty container element in `index.html` the rendered
+     * markup replaces. Defaults to `'root'`.
+     */
+    containerId?: string;
+    /**
+     * The origin the entry sees as `Request.url`, such as
+     * `'https://app.example'`. Defaults to the origin the dev server itself
+     * resolved from its own configuration.
+     *
+     * The origin is deployment configuration rather than something a request
+     * carries. A client chooses its own `Host` header, and Vite accepts IP
+     * literals and (with `allowedHosts`) arbitrary names, so deriving the origin
+     * from the request would let the client pick the redirects, canonical URLs,
+     * and cookie domains an entry builds from `Request.url`. Set this when the
+     * dev server sits behind a proxy or TLS terminator that serves a different
+     * public origin.
+     */
+    origin?: string;
+    /**
+     * The deployment id compiled into a server entry when `foldkitSsr` is used
+     * as a standalone plugin. It defaults to `FOLDKIT_BUILD_ID`, or to the fixed
+     * development id in serve mode. The aggregate `foldkit` plugin supplies its
+     * top-level `buildId` here automatically.
+     *
+     * The value is public in rendered HTML, so it must not be a secret.
+     */
+    buildId?: string;
+}>;
+/**
+ * Serves server-rendered pages from the Vite dev server.
+ *
+ * Vite retains ownership of configured proxies, source modules, HMR, and
+ * assets. Requests that fall through load the server entry through Vite's SSR
+ * module loader, call its `renderPage` with a Web `Request`, and send the
+ * resulting Web `Response`. Vite's host validation applies before either
+ * owner. Foldkit then validates and normalizes the request target before Vite
+ * or the server entry can resolve it. Vite's CORS option applies only to
+ * Vite-owned responses, while the server entry owns CORS for application
+ * responses. Server entry edits take effect without a restart.
+ */
+export declare const foldkitSsr: (options: FoldkitSsrOptions) => Plugin;
+//# sourceMappingURL=ssr.d.ts.map

package/dist/ssr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../src/ssr.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAW,MAAM,EAA+B,MAAM,MAAM,CAAA;AAIxE,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;AA4rBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,iBAAiB,KAAG,MA4CvD,CAAA"}

package/dist/ssr.js

@@ -0,0 +1,490 @@
+import { Array, Effect, Predicate } from 'effect';
+import * as Server from 'foldkit/experimental/server';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { buildIdForCommand } from './buildToken.js';
+const isEntryModule = (loadedModule) => Predicate.isObject(loadedModule) &&
+    Predicate.hasProperty(loadedModule, 'renderPage') &&
+    Predicate.isFunction(loadedModule.renderPage);
+// The origin the dev server serves, taken from the plugin option when the
+// deployment sets one and otherwise from the server's own resolved
+// configuration. The request never contributes: `Host` is a value the client
+// writes, and Vite accepts IP literals by default and any name at all under
+// `allowedHosts`, so a request could otherwise name the origin the entry builds
+// redirects and canonical URLs from.
+const DEV_SERVER_FALLBACK_ORIGIN = 'http://localhost';
+const configuredOrigin = (server, options) => {
+    if (options.origin !== undefined) {
+        return options.origin;
+    }
+    const [resolvedUrl] = server.resolvedUrls?.local ?? [];
+    if (resolvedUrl !== undefined) {
+        // Vite prints these with a trailing slash; `new URL` normalizes either form
+        // and `origin` drops the path, so both are safe to read here.
+        try {
+            return new URL(resolvedUrl).origin;
+        }
+        catch {
+            return DEV_SERVER_FALLBACK_ORIGIN;
+        }
+    }
+    const { https, port } = server.config.server;
+    const scheme = https === undefined ? 'http' : 'https';
+    return port === undefined
+        ? DEV_SERVER_FALLBACK_ORIGIN
+        : `${scheme}://localhost:${port}`;
+};
+const toWebRequest = (requestUrl, nodeRequest) => {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(nodeRequest.headers)) {
+        if (Predicate.isString(value)) {
+            headers.set(name, value);
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                headers.append(name, item);
+            }
+        }
+    }
+    const method = nodeRequest.method ?? 'GET';
+    const requestInit = { headers, method };
+    if (method !== 'GET' && method !== 'HEAD') {
+        // NOTE: Node and the DOM library declare structurally different
+        // ReadableStream interfaces even though Node's `Readable.toWeb` returns
+        // the Web stream implementation that `Request` consumes at runtime.
+        requestInit.body = Readable.toWeb(nodeRequest);
+        requestInit.duplex = 'half';
+    }
+    return new Request(requestUrl, requestInit);
+};
+const originalRequestTargetOf = (nodeRequest) => nodeRequest.originalUrl ?? nodeRequest.url ?? '/';
+const requestTargetOf = (nodeRequest) => nodeRequest.url ?? nodeRequest.originalUrl ?? '/';
+// The request target resolved against the configured origin, or `undefined`
+// when it names a different one (an absolute-form target, or a network-path
+// reference such as `//elsewhere.example/page`). The dev host refuses those
+// rather than handing the entry an origin the client chose, which is what a
+// generated production host does too.
+const resolvedRequestUrl = (server, options, nodeRequest) => Server.resolveRequestUrl(originalRequestTargetOf(nodeRequest), configuredOrigin(server, options)) === undefined
+    ? undefined
+    : Server.resolveRequestUrl(requestTargetOf(nodeRequest), configuredOrigin(server, options));
+const prepareRequestTarget = (server, options, requestUrls, nodeRequest) => {
+    const requestUrl = requestUrls.get(nodeRequest) ??
+        resolvedRequestUrl(server, options, nodeRequest);
+    if (requestUrl === undefined) {
+        return undefined;
+    }
+    requestUrls.set(nodeRequest, requestUrl);
+    const resolved = new URL(requestUrl);
+    nodeRequest.url = `${resolved.pathname}${resolved.search}`;
+    return requestUrl;
+};
+const requestTargetMiddleware = (server, options, requestUrls, render) => (nodeRequest, nodeResponse, next) => {
+    const requestUrl = prepareRequestTarget(server, options, requestUrls, nodeRequest);
+    if (requestUrl === undefined) {
+        nodeResponse.statusCode = 400;
+        nodeResponse.end();
+        return;
+    }
+    if (nodeRequest.method === 'OPTIONS') {
+        const proxy = server.config.server.proxy;
+        if (isProxyRequest(nodeRequest, proxy) ||
+            shouldViteCorsAnswerPreflight(nodeRequest, proxy, server.config.base)) {
+            next();
+            return;
+        }
+        render(nodeRequest, nodeResponse, next);
+        return;
+    }
+    next();
+};
+const renderDecision = (nodeRequest, requestUrl) => {
+    const method = nodeRequest.method ?? 'GET';
+    if (method === 'GET' || method === 'HEAD') {
+        if (Server.resolvesToIndexHtml(requestUrl)) {
+            return 'Render';
+        }
+        // A request Vite did not serve and that names an asset is a miss, not a
+        // navigation. Browsers fetch scripts and stylesheets with `Accept: */*`, so
+        // without this a stale hashed asset would be answered with the app shell at
+        // 200 and read as a blank page instead of the 404 it is.
+        const fetchDestination = nodeRequest.headers['sec-fetch-dest'];
+        const classification = Server.classifyRequest(requestUrl, Predicate.isString(fetchDestination) ? fetchDestination : undefined);
+        if (classification === 'PathAsset') {
+            return 'RefusedPathAsset';
+        }
+        if (classification === 'DestinationAsset') {
+            return 'RefusedDestinationAsset';
+        }
+        const accept = nodeRequest.headers.accept;
+        return Server.acceptsHtml(Predicate.isString(accept) ? accept : undefined)
+            ? 'RenderNegotiated'
+            : 'RefusedNegotiated';
+    }
+    return 'Render';
+};
+const renderRequest = (server, options, nodeRequest, requestUrl) => Effect.gen(function* () {
+    const { pathname, search } = new URL(requestUrl);
+    const route = `${pathname}${search}`;
+    const rawTemplate = yield* Effect.promise(() => readFile(resolve(server.config.root, 'index.html'), 'utf-8'));
+    // NOTE: the first argument tells Vite where the HTML lives, and Vite
+    // resolves the template's relative URLs (such as a `./src/entry.ts`
+    // script) against it. The template always lives at the site root, so
+    // that argument must stay `/index.html` no matter which route is being
+    // rendered. The third argument, named `originalUrl` in Vite's signature,
+    // carries the route actually being requested.
+    const template = yield* Effect.promise(() => server.transformIndexHtml('/index.html', rawTemplate, route));
+    const loadedModule = yield* Effect.promise(() => server.ssrLoadModule(options.serverEntry));
+    if (!isEntryModule(loadedModule)) {
+        return yield* Effect.die(new Error(`[foldkit] '${options.serverEntry}' does not export a renderPage function, so the dev server cannot render pages.`));
+    }
+    const result = yield* Effect.promise(() => loadedModule.renderPage(toWebRequest(requestUrl, nodeRequest)));
+    return Server.toResponse(template, result, options.containerId === undefined
+        ? {}
+        : { containerId: options.containerId });
+});
+const varyHeaderValue = (value) => {
+    if (Array.isArray(value)) {
+        return value.join(', ');
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    return undefined;
+};
+// NOTE: every outcome a static miss negotiates declares both headers the
+// negotiation read. Declaring only Accept would let a shared cache store the
+// rendered page from a document request and serve it to a later script request
+// carrying the same Accept, which never reaches the asset classification, and
+// the reverse for the 404.
+// Every field name in `incoming`, folded into `existing`. The application's own
+// Vary is a list, and `Server.varyWith` merges one name at a time.
+const mergeVary = (existing, incoming) => incoming
+    .split(',')
+    .map(token => token.trim())
+    .filter(token => token !== '')
+    .reduce((merged, fieldName) => Server.varyWith(merged, fieldName), existing ?? '');
+const isHeaderList = (value) => typeof value === 'object';
+const cloneHeaderValue = (value) => isHeaderList(value) ? [...value] : value;
+const responseHeaders = (nodeResponse) => Object.fromEntries(Object.entries(nodeResponse.getHeaders()).map(([name, value]) => [
+    name,
+    cloneHeaderValue(value),
+]));
+const isSameHeaderValue = (left, right) => {
+    if (isHeaderList(left) && isHeaderList(right)) {
+        return (left.length === right.length &&
+            left.every((value, index) => value === right.at(index)));
+    }
+    return left === right;
+};
+const headerMutations = (before, after) => Object.keys(after)
+    .filter(name => !isSameHeaderValue(before[name], after[name]))
+    .map(name => ({ name, before: before[name], after: after[name] }));
+const varyFields = (value) => {
+    if (typeof value === 'string') {
+        return value.split(',').map(fieldName => fieldName.trim());
+    }
+    if (isHeaderList(value)) {
+        return value.flatMap(item => item.split(',').map(fieldName => fieldName.trim()));
+    }
+    return [];
+};
+const restoreVary = (nodeResponse, mutation) => {
+    const fieldsBeforeCors = new Set(varyFields(mutation.before).map(fieldName => fieldName.toLowerCase()));
+    const fieldsAddedByCors = new Set(varyFields(mutation.after)
+        .filter(fieldName => !fieldsBeforeCors.has(fieldName.toLowerCase()))
+        .map(fieldName => fieldName.toLowerCase()));
+    const remainingFields = varyFields(nodeResponse.getHeader(mutation.name)).filter(fieldName => !fieldsAddedByCors.has(fieldName.toLowerCase()));
+    if (Array.isArrayEmpty(remainingFields)) {
+        nodeResponse.removeHeader(mutation.name);
+    }
+    else {
+        nodeResponse.setHeader(mutation.name, remainingFields.join(', '));
+    }
+};
+const restoreResponseHeaders = (nodeResponse, mutations, headersWrittenAfterCors) => {
+    for (const mutation of mutations) {
+        if (headersWrittenAfterCors.has(mutation.name.toLowerCase())) {
+            continue;
+        }
+        const current = cloneHeaderValue(nodeResponse.getHeader(mutation.name));
+        if (mutation.name.toLowerCase() === 'vary') {
+            restoreVary(nodeResponse, mutation);
+        }
+        else if (isSameHeaderValue(current, mutation.after)) {
+            if (mutation.before === undefined) {
+                nodeResponse.removeHeader(mutation.name);
+            }
+            else {
+                nodeResponse.setHeader(mutation.name, mutation.before);
+            }
+        }
+    }
+};
+const trackHeaderWrites = (nodeResponse) => {
+    const names = new Set();
+    const setHeader = nodeResponse.setHeader;
+    const appendHeader = nodeResponse.appendHeader;
+    const removeHeader = nodeResponse.removeHeader;
+    nodeResponse.setHeader = function (name, value) {
+        names.add(String(name).toLowerCase());
+        return Reflect.apply(setHeader, this, [name, value]);
+    };
+    nodeResponse.appendHeader = function (name, value) {
+        names.add(String(name).toLowerCase());
+        return Reflect.apply(appendHeader, this, [name, value]);
+    };
+    nodeResponse.removeHeader = function (name) {
+        names.add(String(name).toLowerCase());
+        return Reflect.apply(removeHeader, this, [name]);
+    };
+    return {
+        names,
+        stop: () => {
+            nodeResponse.setHeader = setHeader;
+            nodeResponse.appendHeader = appendHeader;
+            nodeResponse.removeHeader = removeHeader;
+        },
+    };
+};
+const isProxyRequest = (nodeRequest, proxy) => {
+    const requestUrl = nodeRequest.url;
+    if (requestUrl === undefined || proxy === undefined) {
+        return false;
+    }
+    return Object.entries(proxy).some(([context, proxyOptions]) => {
+        if (proxyOptions === undefined) {
+            return false;
+        }
+        return context.startsWith('^')
+            ? new RegExp(context).test(requestUrl)
+            : requestUrl.startsWith(context);
+    });
+};
+const VITE_SOURCE_EXTENSIONS = new Set([
+    'astro',
+    'cts',
+    'jsx',
+    'mdx',
+    'mts',
+    'svelte',
+    'ts',
+    'tsx',
+    'vue',
+]);
+const hasViteSourceExtension = (path) => {
+    const lastSegment = path.slice(path.lastIndexOf('/') + 1);
+    const separator = lastSegment.lastIndexOf('.');
+    return (separator >= 0 &&
+        VITE_SOURCE_EXTENSIONS.has(lastSegment.slice(separator + 1).toLowerCase()));
+};
+const shouldViteCorsAnswerPreflight = (nodeRequest, proxy, base) => {
+    if (isProxyRequest(nodeRequest, proxy)) {
+        return false;
+    }
+    const requestedMethod = nodeRequest.headers['access-control-request-method'];
+    const requestOrigin = nodeRequest.headers.origin;
+    if (!Predicate.isString(requestedMethod) ||
+        !Predicate.isString(requestOrigin) ||
+        requestOrigin === '') {
+        return false;
+    }
+    const normalizedMethod = requestedMethod.toUpperCase();
+    if (normalizedMethod !== 'GET' && normalizedMethod !== 'HEAD') {
+        return false;
+    }
+    const requestTarget = requestTargetOf(nodeRequest);
+    const path = new URL(requestTarget, DEV_SERVER_FALLBACK_ORIGIN).pathname;
+    const vitePath = base !== '/' && path.startsWith(base) ? `/${path.slice(base.length)}` : path;
+    if (vitePath.startsWith('/@') ||
+        vitePath.startsWith('/__vite') ||
+        vitePath.startsWith('/node_modules/') ||
+        hasViteSourceExtension(vitePath)) {
+        return true;
+    }
+    const fetchDestination = nodeRequest.headers['sec-fetch-dest'];
+    return (Server.classifyRequest(requestTarget, Predicate.isString(fetchDestination) ? fetchDestination : undefined) !== 'Page');
+};
+const wrapViteCors = (server, options, requestUrls, stateByRequest) => {
+    if (server.config.server.cors === false) {
+        return;
+    }
+    const corsLayer = server.middlewares.stack.find(layer => Predicate.isFunction(layer.handle) &&
+        layer.handle.name.startsWith('corsMiddleware'));
+    if (corsLayer === undefined || !Predicate.isFunction(corsLayer.handle)) {
+        throw new Error('[foldkit] Could not find Vite\u2019s CORS middleware at the expected ' +
+            'ownership boundary. This Vite version is not compatible with ' +
+            '@foldkit/vite-plugin.');
+    }
+    const viteCors = corsLayer.handle;
+    const wrappedCors = (nodeRequest, nodeResponse, next) => {
+        if (prepareRequestTarget(server, options, requestUrls, nodeRequest) ===
+            undefined) {
+            nodeResponse.statusCode = 400;
+            nodeResponse.end();
+            return;
+        }
+        if (nodeRequest.method === 'OPTIONS' &&
+            !shouldViteCorsAnswerPreflight(nodeRequest, server.config.server.proxy, server.config.base)) {
+            next();
+            return;
+        }
+        const before = responseHeaders(nodeResponse);
+        Reflect.apply(viteCors, undefined, [
+            nodeRequest,
+            nodeResponse,
+            (error) => {
+                stateByRequest.set(nodeRequest, {
+                    mutations: headerMutations(before, responseHeaders(nodeResponse)),
+                    tracking: trackHeaderWrites(nodeResponse),
+                });
+                next(error);
+            },
+        ]);
+    };
+    corsLayer.handle = wrappedCors;
+};
+const setNegotiatedVary = (nodeResponse) => {
+    const existing = varyHeaderValue(nodeResponse.getHeader('vary'));
+    nodeResponse.setHeader('vary', Server.varyWith(Server.varyWithAccept(existing), 'Sec-Fetch-Dest'));
+};
+const sendWebResponse = async (webResponse, nodeRequest, nodeResponse, isNegotiated) => {
+    nodeResponse.statusCode = webResponse.status;
+    if (webResponse.statusText !== '') {
+        nodeResponse.statusMessage = webResponse.statusText;
+    }
+    const getSetCookie = Predicate.hasProperty(webResponse.headers, 'getSetCookie')
+        ? webResponse.headers.getSetCookie
+        : undefined;
+    const setCookieHeaders = Predicate.isFunction(getSetCookie)
+        ? getSetCookie.call(webResponse.headers)
+        : [];
+    for (const [name, value] of webResponse.headers) {
+        if (name === 'vary') {
+            // NOTE: merged rather than set. Middleware that ran before the entry may
+            // already have declared a field, and a plain setHeader here would replace
+            // it when the application declares its own Vary.
+            nodeResponse.setHeader('vary', mergeVary(varyHeaderValue(nodeResponse.getHeader('vary')), value));
+        }
+        else if (name !== 'set-cookie' || Array.isArrayEmpty(setCookieHeaders)) {
+            nodeResponse.setHeader(name, value);
+        }
+    }
+    if (Array.isArrayNonEmpty(setCookieHeaders)) {
+        nodeResponse.setHeader('set-cookie', setCookieHeaders);
+    }
+    if (isNegotiated) {
+        // Merge into whatever Vary already sits on the node response, including
+        // the application's own fields, so declaring these does not drop it.
+        setNegotiatedVary(nodeResponse);
+    }
+    if (nodeRequest.method === 'HEAD' || webResponse.body === null) {
+        nodeResponse.end();
+    }
+    else {
+        const body = new Uint8Array(await webResponse.arrayBuffer());
+        nodeResponse.end(body);
+    }
+};
+// The handler that turns an application-owned request into a response. OPTIONS
+// reaches it at the host boundary. Other methods reach it after Vite's modules
+// and assets have had an opportunity to answer.
+const renderMiddleware = (server, options, requestUrls, stateByRequest) => (nodeRequest, nodeResponse, next) => {
+    const corsState = stateByRequest.get(nodeRequest);
+    stateByRequest.delete(nodeRequest);
+    corsState?.tracking.stop();
+    restoreResponseHeaders(nodeResponse, corsState?.mutations ?? [], corsState?.tracking.names ?? new Set());
+    const requestUrl = requestUrls.get(nodeRequest) ??
+        resolvedRequestUrl(server, options, nodeRequest);
+    requestUrls.delete(nodeRequest);
+    if (requestUrl === undefined) {
+        // The target names an origin other than the one being served, so there is
+        // no request to render: answering it would hand the entry a client-chosen
+        // origin to build redirects and canonical URLs from.
+        nodeResponse.statusCode = 400;
+        nodeResponse.end();
+        return;
+    }
+    const method = nodeRequest.method ?? 'GET';
+    if (Server.isHostSettledMethod(method)) {
+        nodeResponse.statusCode = Server.HOST_METHOD_ANSWERS.refusedStatus;
+        nodeResponse.setHeader('allow', Server.HOST_METHOD_ANSWERS.allow);
+        nodeResponse.end();
+        return;
+    }
+    const decision = renderDecision(nodeRequest, requestUrl);
+    if (decision === 'RefusedPathAsset') {
+        // The path names an asset whatever the request headers say, so this
+        // refusal is the same for every client and needs no Vary.
+        nodeResponse.statusCode = 404;
+        nodeResponse.end();
+        return;
+    }
+    if (decision === 'RefusedDestinationAsset') {
+        nodeResponse.statusCode = 404;
+        setNegotiatedVary(nodeResponse);
+        nodeResponse.end();
+        return;
+    }
+    if (decision === 'RefusedNegotiated') {
+        nodeResponse.statusCode = 404;
+        setNegotiatedVary(nodeResponse);
+        nodeResponse.end();
+        return;
+    }
+    const isNegotiated = decision === 'RenderNegotiated';
+    void Effect.runPromise(renderRequest(server, options, nodeRequest, requestUrl))
+        .then(response => sendWebResponse(response, nodeRequest, nodeResponse, isNegotiated))
+        .catch((error) => {
+        if (error instanceof Error) {
+            server.ssrFixStacktrace(error);
+        }
+        next(error);
+    });
+};
+/**
+ * Serves server-rendered pages from the Vite dev server.
+ *
+ * Vite retains ownership of configured proxies, source modules, HMR, and
+ * assets. Requests that fall through load the server entry through Vite's SSR
+ * module loader, call its `renderPage` with a Web `Request`, and send the
+ * resulting Web `Response`. Vite's host validation applies before either
+ * owner. Foldkit then validates and normalizes the request target before Vite
+ * or the server entry can resolve it. Vite's CORS option applies only to
+ * Vite-owned responses, while the server entry owns CORS for application
+ * responses. Server entry edits take effect without a restart.
+ */
+export const foldkitSsr = (options) => {
+    return {
+        name: 'foldkit-ssr',
+        config: (_config, { command, isPreview }) => {
+            const buildId = buildIdForCommand(command, options.buildId);
+            return {
+                // NOTE: `vite preview` also resolves with command 'serve', but it
+                // serves built output and never runs configureServer. Setting custom
+                // there would strip preview's HTML middleware. A build still needs the
+                // define below even though only a dev server needs this app type.
+                ...(command === 'serve' && isPreview !== true
+                    ? { appType: 'custom' }
+                    : {}),
+                ...(buildId === undefined
+                    ? {}
+                    : {
+                        define: {
+                            'import.meta.env.FOLDKIT_BUILD_ID': JSON.stringify(buildId),
+                        },
+                    }),
+            };
+        },
+        configureServer: server => {
+            const requestUrls = new WeakMap();
+            const stateByRequest = new WeakMap();
+            const render = renderMiddleware(server, options, requestUrls, stateByRequest);
+            server.middlewares.use(requestTargetMiddleware(server, options, requestUrls, render));
+            wrapViteCors(server, options, requestUrls, stateByRequest);
+            return () => {
+                server.middlewares.use(render);
+            };
+        },
+    };
+};

package/dist/viewIdentity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewIdentity.d.ts","sourceRoot":"","sources":["../src/viewIdentity.ts"],"names":[],"mappings":"AAAA,OAAoB,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAI1D,OAAO,EAAE,KAAK,MAAM,EAAY,MAAM,MAAM,CAAA;AAwZ5C,iFAAiF;AACjF,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,SAAS,CAAA;CACf,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,IAAI,MAAM,EACV,MAAM,MAAM,EACZ,UAAU,QAAQ,CAAC;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,KACtD,2BAA2B,GAAG,IAyChC,CAAA;AA8DD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,QAAO,MA0CtC,CAAA"}
+{"version":3,"file":"viewIdentity.d.ts","sourceRoot":"","sources":["../src/viewIdentity.ts"],"names":[],"mappings":"AAAA,OAAoB,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAI1D,OAAO,EAAE,KAAK,MAAM,EAAY,MAAM,MAAM,CAAA;AA6a5C,iFAAiF;AACjF,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,SAAS,CAAA;CACf,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,IAAI,MAAM,EACV,MAAM,MAAM,EACZ,UAAU,QAAQ,CAAC;IACjB,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC,CAAC,KACD,2BAA2B,GAAG,IAyChC,CAAA;AA8DD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,QAAO,MA0CtC,CAAA"}

package/dist/viewIdentity.js

@@ -176,6 +176,27 @@ const rawFunctionName = (functionNode, parentByNode) => {
     }
     return ANONYMOUS_FUNCTION_NAME;
 };
+// NOTE: a view identity names a source position, and a source position outlives
+// the code that occupied it. Hydration compares identities to decide whether the
+// server DOM and the client's first render describe the same logical element, so
+// an identity that stays the same while the function's body changes tells it two
+// different views are the same one: a stale page's `<input name="email">` is
+// adopted by a new build's `<input name="ssn">`, and the value the visitor typed
+// before hydration is carried into a field that means something else and submits
+// under a new name. That is what the deployment's build id answers: it is
+// compared before hydration reads anything the page carries, so a page from a
+// build whose views mean something else is refused as a whole.
+//
+// An identity carries no digest of the module's source, and must not. Mixing
+// one in would make a changed view rebuild its own subtree, which is the reason
+// to want it, but the identity is emitted into the client bundle every visitor
+// downloads, and a truncated hash of a whole source file is a check against that
+// file's contents. A build that tree-shakes a low-entropy server-only value out
+// of the client (a PIN behind `import.meta.env.SSR`) would still ship a digest
+// of the source that contained it, and the value could be recovered by hashing
+// candidates until one matched. The build id costs nothing to compare and
+// reveals nothing about the source. `check:packed-ssr-consumer` asserts the
+// absence against a real built bundle.
 const assignFunctionIds = (functionNodes, parentByNode, modulePath) => {
     const functionIds = new Map();
     const occurrenceCountsByName = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Vite plugin for Foldkit hot module reloading with state preservation",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "peerDependencies": {
     "effect": "4.0.0-rc.109",
-    "foldkit": "^0",
+    "foldkit": ">=0.148.0",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "dependencies": {
@@ -32,8 +32,9 @@
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",
+    "vite7": "npm:vite@^7.0.0",
     "vitest": "^4.1.9",
-    "foldkit": "0.146.0"
+    "foldkit": "0.148.0"
   },
   "keywords": [
     "vite",
@@ -53,7 +54,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.19.0"
   },
   "scripts": {
     "clean": "rimraf dist *.tsbuildinfo",