@foldkit/vite-plugin 0.19.0-canary.f656c022545d → 0.20.0

package/dist/build.d.ts

@@ -0,0 +1,109 @@
+import { Schema as S } from 'effect';
+import nodePath from 'node:path';
+import type { Plugin } from 'vite';
+/** How a build materializes the URLs a server entry can render. */
+export type FoldkitPrerenderOptions = Readonly<{
+    /**
+     * The paths to generate. Defaults to the `prerenderPaths` the server entry
+     * exports, so the application names its own static routes.
+     */
+    paths?: ReadonlyArray<string>;
+    /**
+     * The origin the entry sees as `Request.url` while generating, such as
+     * `'https://app.example'`. It reaches canonical URLs and Open Graph URLs, so
+     * a deployment that publishes those should set the origin it publishes.
+     */
+    origin?: string;
+    /**
+     * The `id` of the placeholder element in `index.html` the rendered markup
+     * replaces. Defaults to `'root'`, and the aggregate plugin passes whatever
+     * `ssr.containerId` names, so a renamed container is renamed once.
+     */
+    containerId?: string;
+}>;
+/** 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;
+    /**
+     * Generate static HTML for a set of URLs after both builds. `true` takes the
+     * paths from the entry's `prerenderPaths` export.
+     */
+    prerender?: boolean | FoldkitPrerenderOptions;
+}>;
+/**
+ * What the build produced, written beside the server bundle for whatever
+ * deploys it.
+ *
+ * A host has to decide what the asset layer does with a request that matches no
+ * file, and that answer follows from the build rather than from taste: an
+ * application with generated pages and no others wants a miss to stay a miss,
+ * one with a server wants a miss to reach it, and one with neither wants the
+ * template. Reading it here is how a deployment target gets that right without
+ * asking its user to configure it twice.
+ */
+export declare const FoldkitBuildManifest: S.Struct<{
+    /**
+     * The shape of this document. A consumer decodes before reading and refuses
+     * a version it does not know, so a manifest written by a newer Foldkit is a
+     * clear refusal rather than a field silently read as undefined.
+     */
+    readonly schemaVersion: S.Literals<readonly [1]>;
+    /**
+     * Where the browser build was written, as a POSIX path relative to the Vite
+     * root. Relative and normalized so a manifest survives being moved with the
+     * build it describes.
+     */
+    readonly client: S.String;
+    /** Where the server build was written, on the same terms as {@link client}. */
+    readonly server: S.String;
+    /** The server build's entry file, relative to `server`. */
+    readonly serverEntry: S.String;
+    /** Every path this build generated a page for, in the order it generated. */
+    readonly prerendered: S.$Array<S.String>;
+}>;
+/**
+ * What the build produced, written beside the server bundle for whatever
+ * deploys it.
+ *
+ * A host has to decide what the asset layer does with a request that matches no
+ * file, and that answer follows from the build rather than from taste: an
+ * application with generated pages and no others wants a miss to stay a miss,
+ * one with a server wants a miss to reach it, and one with neither wants the
+ * template. Reading it here is how a deployment target gets that right without
+ * asking its user to configure it twice.
+ *
+ * It is a file on disk that something else writes the next time it builds, so a
+ * consumer decodes it with this Schema and fails closed rather than trusting
+ * the shape it happens to find.
+ */
+export type FoldkitBuildManifest = typeof FoldkitBuildManifest.Type;
+export declare const manifestPath: (root: string, directory: string, pathApi?: typeof nodePath) => string;
+export declare const renderTargetFor: (clientDirectory: string, path: string, origin: string, pathApi?: typeof nodePath) => Readonly<{
+    url: URL;
+    file: string;
+}>;
+/**
+ * Builds the server entry alongside the browser build, and generates static
+ * HTML from it, 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.
+ */
+export declare const foldkitBuild: (serverEntry: string, options?: FoldkitBuildOptions) => Plugin;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,IAAI,CAAC,EAAE,MAAM,QAAQ,CAAA;AAG3C,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"}

package/dist/build.js

@@ -0,0 +1,338 @@
+import { Array, Schema as S } from 'effect';
+import { mkdir, writeFile } from 'node:fs/promises';
+import nodePath, { basename, dirname, extname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * What the build produced, written beside the server bundle for whatever
+ * deploys it.
+ *
+ * A host has to decide what the asset layer does with a request that matches no
+ * file, and that answer follows from the build rather than from taste: an
+ * application with generated pages and no others wants a miss to stay a miss,
+ * one with a server wants a miss to reach it, and one with neither wants the
+ * template. Reading it here is how a deployment target gets that right without
+ * asking its user to configure it twice.
+ */
+export const FoldkitBuildManifest = S.Struct({
+    /**
+     * The shape of this document. A consumer decodes before reading and refuses
+     * a version it does not know, so a manifest written by a newer Foldkit is a
+     * clear refusal rather than a field silently read as undefined.
+     */
+    schemaVersion: S.Literals([1]),
+    /**
+     * Where the browser build was written, as a POSIX path relative to the Vite
+     * root. Relative and normalized so a manifest survives being moved with the
+     * build it describes.
+     */
+    client: S.String,
+    /** Where the server build was written, on the same terms as {@link client}. */
+    server: S.String,
+    /** The server build's entry file, relative to `server`. */
+    serverEntry: S.String,
+    /** Every path this build generated a page for, in the order it generated. */
+    prerendered: S.Array(S.String),
+});
+const MANIFEST_SCHEMA_VERSION = 1;
+// Relative and POSIX so the manifest describes a layout rather than this
+// machine: an absolute `clientOutDir` would otherwise be published verbatim and
+// break the moment the build is copied anywhere else.
+//
+// On Windows, `path.relative` across drives has no relative answer and returns
+// the absolute destination, which is exactly the machine-specific path the
+// manifest must not carry. Refused rather than recorded. `pathApi` exists so a
+// test can run the Windows rules anywhere.
+//
+// @internal Exported for tests.
+export const manifestPath = (root, directory, pathApi = nodePath) => {
+    const related = pathApi.relative(root, pathApi.resolve(root, directory));
+    if (pathApi.isAbsolute(related)) {
+        throw new Error(`[foldkit] cannot record "${directory}" in the manifest: it has no path relative to the Vite root at "${root}". Keep the output directories on the root's volume.`);
+    }
+    return related.split(pathApi.sep).join('/');
+};
+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));
+// 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
+// whatever this returns, which runs that module's top-level code in the build
+// process. Taking the first entry chunk would execute an unrelated module that
+// happens to sort first, so the chunk is matched to the entry the build was
+// given and anything else is refused.
+const serverEntryFile = (outputs, entryName) => {
+    const entries = outputs.filter(file => file.type === 'chunk' && file.isEntry);
+    const named = entries.filter(file => file.name === entryName);
+    if (named.length === 1 && named[0] !== undefined) {
+        return named[0].fileName;
+    }
+    if (named.length > 1) {
+        throw new Error(`[foldkit] the server build emitted more than one entry chunk named "${entryName}": ${named
+            .map(file => file.fileName)
+            .join(', ')}. Prerendering cannot choose between them.`);
+    }
+    throw new Error(`[foldkit] the server build emitted no entry chunk named "${entryName}"${entries.length === 0
+        ? '.'
+        : `; it emitted ${entries.map(file => file.name).join(', ')}.`}`);
+};
+const environmentNamed = (builder, name) => {
+    const environment = builder.environments[name];
+    if (environment === undefined) {
+        throw new Error(`[foldkit] the build declares no "${name}" environment to build.`);
+    }
+    return environment;
+};
+// The validated render target: the URL the entry receives and the file its
+// page is written to, from one resolution — returned together so the request
+// can never be built from anything the validation did not see. Rendering runs
+// application code with the build's privileges and may fetch from
+// `Request.url`, so validation is the trust boundary and has to come first: a
+// protocol-relative path like `//169.254.169.254/x` resolves to that host, and
+// handing it to the entry before refusing it would let invalid path data
+// trigger side effects on the way to the error.
+//
+// A path reaches here from application code and may come from data, so it is
+// treated as a URL rather than as a filesystem path: `path.slice(1)` is a
+// relative path on POSIX but not on Windows, where `/C:/outside` is
+// drive-absolute and `/D:outside` is drive-relative, and either escapes the
+// build output. The segments are taken from the parsed URL, rejected if any
+// still carries a separator or a dot-segment after decoding, and the resolved
+// file is required to sit under the client directory.
+//
+// `pathApi` is the platform's `path` by default and the parameter exists so a
+// test can run the Windows rules anywhere.
+export const renderTargetFor = (clientDirectory, path, origin, pathApi = nodePath) => {
+    const url = new URL(path, origin);
+    if (url.origin !== new URL(origin).origin || url.pathname !== path) {
+        throw new Error(`[foldkit] cannot generate the non-normalized same-origin path "${path}".`);
+    }
+    const segments = url.pathname.split('/').filter(segment => segment !== '');
+    for (const segment of segments) {
+        const decoded = decodeURIComponent(segment);
+        const isTraversal = decoded === '.' || decoded === '..';
+        const carriesSeparator = decoded.includes('/') ||
+            decoded.includes('\\') ||
+            decoded.includes('\u0000');
+        // A colon cannot appear in a Windows path segment, and a bare `C:` is a
+        // drive designator rather than a directory: `path.win32.resolve` re-anchors
+        // the rest of the path onto that drive's current directory.
+        const namesADrive = decoded.includes(':');
+        if (isTraversal || carriesSeparator || namesADrive) {
+            throw new Error(`[foldkit] cannot generate "${path}": the segment "${segment}" does not name a single directory.`);
+        }
+    }
+    const file = pathApi.resolve(clientDirectory, ...segments.map(segment => decodeURIComponent(segment)), 'index.html');
+    const root = pathApi.resolve(clientDirectory);
+    const isContained = file === pathApi.join(root, 'index.html') ||
+        file.startsWith(root.endsWith(pathApi.sep) ? root : `${root}${pathApi.sep}`);
+    if (!isContained) {
+        throw new Error(`[foldkit] cannot generate "${path}": it resolves to "${file}", outside the browser build at "${root}".`);
+    }
+    return { url, file };
+};
+// A static file is a body plus whatever headers its host adds, so a result that
+// carries a redirect, a status, or headers of its own cannot be written to one.
+// Refusing here keeps a redirect from being published as an ordinary page.
+const renderedApplication = (path, result) => {
+    if (result._tag === 'Responded') {
+        throw new Error(`[foldkit] cannot write the complete Response returned while generating "${path}" to a static HTML file.`);
+    }
+    if (result.status !== undefined && result.status !== 200) {
+        throw new Error(`[foldkit] cannot preserve status ${result.status} while generating "${path}" as a static HTML file.`);
+    }
+    if (result.headers !== undefined) {
+        throw new Error(`[foldkit] cannot preserve response headers while generating "${path}" as a static HTML file.`);
+    }
+    return result.application;
+};
+const prerenderOptionsFrom = (prerender) => {
+    if (prerender === false) {
+        return undefined;
+    }
+    return prerender === true ? {} : prerender;
+};
+// Keyed by Vite root plus the output layout, so concurrent builds of different
+// projects in one process never read each other's output.
+//
+// NOTE: the registry hangs off a global symbol rather than module scope. Vite
+// re-bundles a config file for each environment it resolves, and every bundle
+// is a fresh copy of this module with its own module scope, so what the client
+// build recorded would be invisible to the instance that finalizes. The symbol
+// is one registry for the process no matter how many copies of this module it
+// loads.
+const CAPTURES = Symbol.for('foldkit/vite-plugin:build-captures');
+const captures = (() => {
+    const registry = globalThis;
+    const existing = registry[CAPTURES];
+    if (existing instanceof Map) {
+        return existing;
+    }
+    const fresh = new Map();
+    registry[CAPTURES] = fresh;
+    return fresh;
+})();
+/**
+ * Builds the server entry alongside the browser build, and generates static
+ * HTML from it, 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.
+ */
+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);
+    // 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
+    // exactly those terms. Nothing here is imported when prerendering is off.
+    const generatePages = async (builder, template, serverDirectory, entryFileName) => {
+        if (prerender === undefined) {
+            return [];
+        }
+        const origin = prerender.origin ?? DEFAULT_PRERENDER_ORIGIN;
+        const clientDirectory = resolve(builder.config.root, clientOutDir);
+        const entryFile = resolve(serverDirectory, entryFileName);
+        const contained = resolve(serverDirectory);
+        if (!entryFile.startsWith(`${contained}${nodePath.sep}`)) {
+            throw new Error(`[foldkit] the server entry "${entryFileName}" resolves outside the server build at "${contained}".`);
+        }
+        const entry = await import(pathToFileURL(entryFile).href);
+        if (typeof entry.renderPage !== 'function') {
+            throw new Error(`[foldkit] "${entryFileName}" exports no renderPage function, so there is nothing to generate pages with.`);
+        }
+        const paths = prerender.paths ?? entry.prerenderPaths;
+        if (paths === undefined) {
+            throw new Error(`[foldkit] cannot generate pages: "${entry}" exports no prerenderPaths and the build configured no paths.`);
+        }
+        const { injectIntoTemplate } = await import('foldkit/experimental/server');
+        for (const path of paths) {
+            const { url, file } = renderTargetFor(clientDirectory, path, origin);
+            const result = await entry.renderPage(new Request(url));
+            const html = injectIntoTemplate(template(), renderedApplication(path, result), prerender.containerId === undefined
+                ? undefined
+                : { containerId: prerender.containerId });
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(file, html);
+            builder.config.logger.info(`  generated ${path}`);
+        }
+        return paths;
+    };
+    const writeManifest = async (builder, serverDirectory, entryFileName, prerendered) => {
+        const manifest = S.encodeSync(FoldkitBuildManifest)({
+            schemaVersion: MANIFEST_SCHEMA_VERSION,
+            client: manifestPath(builder.config.root, clientOutDir),
+            server: manifestPath(builder.config.root, serverOutDir),
+            serverEntry: entryFileName,
+            prerendered,
+        });
+        await writeFile(resolve(serverDirectory, MANIFEST_FILE_NAME), `${JSON.stringify(manifest, undefined, 2)}\n`);
+        builder.config.logger.info(`  wrote ${MANIFEST_FILE_NAME}`);
+    };
+    // What each environment emitted, recorded as it is emitted.
+    //
+    // Vite resolves the config once per environment unless `sharedConfigBuild` is
+    // on, so the plugin that finalizes is not necessarily the instance that saw a
+    // given environment build. Keying the record by the output layout it
+    // 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 captured = (root) => {
+        const existing = captures.get(`${root}\u0000${key}`);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const fresh = {};
+        captures.set(`${root}\u0000${key}`, fresh);
+        return fresh;
+    };
+    const finalize = async (builder) => {
+        const state = captured(builder.config.root);
+        const serverDirectory = resolve(builder.config.root, serverOutDir);
+        if (state.serverEntryFile === undefined) {
+            throw new Error('[foldkit] the server environment produced no entry chunk, so there is nothing to deploy or generate from.');
+        }
+        // Read only when a page is actually generated: a build that generates
+        // nothing has no use for an HTML entry and must not require one.
+        const template = () => {
+            if (state.template === undefined) {
+                throw new Error('[foldkit] the browser build emitted no index.html to generate pages from. Prerendering needs an HTML entry.');
+            }
+            return state.template;
+        };
+        const prerendered = await generatePages(builder, template, serverDirectory, state.serverEntryFile);
+        await writeManifest(builder, serverDirectory, state.serverEntryFile, prerendered);
+    };
+    return {
+        name: 'foldkit:build',
+        apply: 'build',
+        // 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
+        // `writeBundle` the bundle is whatever the environment actually produced.
+        writeBundle(_options, bundle) {
+            const state = captured(this.environment.config.root);
+            const outputs = Object.values(bundle);
+            if (this.environment.name === 'client') {
+                const html = Array.findFirst(outputs, file => file.type === 'asset' && file.fileName === 'index.html');
+                if (html._tag === 'Some' && html.value.type === 'asset') {
+                    state.template = String(html.value.source);
+                }
+                return;
+            }
+            if (this.environment.name === 'ssr') {
+                state.serverEntryFile = serverEntryFile(outputs, serverChunkName(entry));
+            }
+        },
+        config: userConfig => {
+            const client = {
+                build: { outDir: clientOutDir },
+            };
+            const ssr = {
+                build: {
+                    ssr: true,
+                    outDir: serverOutDir,
+                    rollupOptions: { input: { [serverChunkName(entry)]: entry } },
+                },
+            };
+            // NOTE: a host framework that orchestrates its own environments owns
+            // the order they build in, and Vite's config merge keeps exactly one
+            // `builder.buildApp` — whichever config hook ran last. The default
+            // orchestrator is only offered when nothing else claimed the slot, and
+            // finalization deliberately does not live here: wrapping the host's
+            // orchestrator only works when Foldkit's config hook runs after the
+            // host's, so a project that lists the plugins the other way around
+            // would build and silently never finalize.
+            return userConfig.builder?.buildApp === undefined
+                ? {
+                    environments: { client, ssr },
+                    builder: {
+                        buildApp: async (builder) => {
+                            await builder.build(environmentNamed(builder, 'client'));
+                            await builder.build(environmentNamed(builder, 'ssr'));
+                        },
+                    },
+                }
+                : { environments: { client, ssr } };
+        },
+        // The composable finalization point. `order: 'post'` runs this after the
+        // config-level orchestrator — the host's, or the default above — no matter
+        // where this plugin sits in the plugin list, which a wrapped
+        // `builder.buildApp` could not guarantee.
+        buildApp: {
+            order: 'post',
+            handler: finalize,
+        },
+    };
+};

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 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 { type FoldkitSsrOptions, foldkitSsr } from './ssr.js';
 export { type ViewIdentityTransformResult, foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 /** Options for the `foldkit` Vite plugin. */
@@ -18,7 +20,17 @@ export type FoldkitPluginOptions = Readonly<{
      * `renderPage` from the module at `ssr.serverEntry`. When `undefined` (the
      * default), the dev server serves the client entry only.
      */
-    ssr?: Omit<FoldkitSsrOptions, 'buildId'>;
+    ssr?: Omit<FoldkitSsrOptions, 'buildId'> & 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.
+         *
+         * When this is absent, `vite build` builds the browser bundle only and
+         * the server build is a separate command the deployment runs itself.
+         */
+        build?: boolean | FoldkitBuildOptions;
+    }>;
     /**
      * The deployment this build belongs to, compiled into application code as
      * `import.meta.env.FOLDKIT_BUILD_ID` for the entries to pass to
@@ -31,15 +43,16 @@ export type FoldkitPluginOptions = Readonly<{
      * 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.
+     *
+     * Whatever supplies it has to answer with the same value every time it is
+     * asked, because Vite reads a config file once per environment it builds. A
+     * config that computes a fresh value on each read — `randomUUID()`, a
+     * timestamp — gives the browser bundle and the server bundle different ids
+     * within one build, and every page of that deployment is then refused at
+     * hydration. Read it from the environment, or store a generated fallback
+     * back into the environment so later reads resolve the same id.
      */
     buildId?: string;
 }>;
-/**
- * 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":"AAmCA,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;AAklBF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CA+ExE,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,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;AA4mBF,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CAsFxE,CAAA"}

package/dist/index.js

@@ -1,14 +1,16 @@
 import { Array, Console, Data, Duration, Effect, Exit, Fiber, HashMap, HashSet, Match as M, Option, Predicate, Queue, Ref, Schema as S, Schedule, Stream, pipe, } from 'effect';
-import { EventFrame, RequestFrame, Response, ResponseFrame, } from 'foldkit/devtools-protocol';
+import { Event as DevToolsEvent, EventFrame, RequestFrame, Response, ResponseFrame, } from 'foldkit/devtools-protocol';
 import { PreserveModelMessage, RequestModelMessage, RestoreModelMessage, } from 'foldkit/hmr-protocol';
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
+import { foldkitBuild } from './build.js';
 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 { 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`
@@ -142,10 +144,10 @@ const handleRequestModelReceived = (server, state, payload) => Exit.match(S.deco
 const handleHotUpdateFired = (state) => Ref.update(state.preservedModels, current => HashMap.map(current, entry => ({ ...entry, isHmrReload: true })));
 const handleBrowserEventFrameReceived = (state, data, client) => Exit.match(S.decodeUnknownExit(EventFrame)(data), {
     onFailure: error => Console.warn('[foldkit:devTools] failed to decode browser event frame', error),
-    onSuccess: frame => M.value(frame.event).pipe(M.tagsExhaustive({
+    onSuccess: frame => DevToolsEvent.match(frame.event, {
         EventConnected: event => handleConnectedEvent(state, event, client),
         EventDisconnected: event => handleDisconnectedEvent(state, event),
-    })),
+    }),
 });
 const handleConnectedEvent = (state, event, client) => Effect.gen(function* () {
     yield* Ref.update(state.connectedRuntimes, HashMap.set(event.runtime.connectionId, event.runtime));
@@ -330,6 +332,23 @@ const main = (server, events, options) => Effect.gen(function* () {
  * an array; Vite flattens nested plugin arrays, so `plugins: [foldkit()]`
  * keeps working.
  */
+// The container is named once, on `ssr`, and reaches both the dev host and the
+// build from there. A `build.prerender` that names its own wins, so a project
+// that needs them to differ still can.
+const withContainerId = (build, containerId) => {
+    const options = build === true ? {} : build;
+    if (containerId === undefined || options.prerender === undefined) {
+        return options;
+    }
+    const prerender = options.prerender === true ? {} : options.prerender;
+    if (prerender === false) {
+        return options;
+    }
+    return {
+        ...options,
+        prerender: { containerId, ...prerender },
+    };
+};
 export const foldkit = (options = {}) => {
     const events = Effect.runSync(Queue.unbounded());
     // NOTE: One plugin instance can serve more than one dev server, and on
@@ -378,23 +397,26 @@ export const foldkit = (options = {}) => {
             return [];
         },
     };
-    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 }),
-            }),
-        ];
+    const shared = [
+        foldkitBuildToken(options.buildId),
+        foldkitViewIdentity(),
+        devToolsOverlayPlugin(),
+        hmrPlugin,
+    ];
+    if (options.ssr === undefined) {
+        return shared;
+    }
+    const { build, ...ssr } = options.ssr;
+    const servePages = foldkitSsr({
+        ...ssr,
+        ...(options.buildId === undefined ? {} : { buildId: options.buildId }),
+    });
+    if (build === undefined || build === false) {
+        return [...shared, servePages];
+    }
+    return [
+        ...shared,
+        servePages,
+        foldkitBuild(ssr.serverEntry, withContainerId(build, ssr.containerId)),
+    ];
 };

package/dist/ssr.d.ts.map

@@ -1 +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;AA2rBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,YAAa,iBAAiB,KAAG,MA4CvD,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;CACjB,CAAC,CAAA;AAusBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,YAAa,iBAAiB,KAAG,MAgEvD,CAAA"}

package/dist/ssr.js

@@ -4,6 +4,16 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { Readable } from 'node:stream';
 import { buildIdForCommand } from './buildToken.js';
+// Whether an environment can evaluate modules in this process, which is what
+// loading the server entry needs. Vite's own `isRunnableDevEnvironment` is an
+// `instanceof` check against the `RunnableDevEnvironment` class of whichever
+// copy of Vite the caller imported — and a plugin supporting a range of majors
+// is not always imported by the copy that created the server, so that check
+// reports a perfectly runnable environment as not runnable. The lazily
+// constructed `runner` accessor is the shape every major agrees on, and `in`
+// reads the descriptor rather than invoking the getter, so probing costs
+// nothing.
+const isRunnable = (environment) => 'runner' in environment;
 const isEntryModule = (loadedModule) => Predicate.isObject(loadedModule) &&
     Predicate.hasProperty(loadedModule, 'renderPage') &&
     Predicate.isFunction(loadedModule.renderPage);
@@ -477,6 +487,23 @@ export const foldkitSsr = (options) => {
             };
         },
         configureServer: server => {
+            // Rendering here loads the server entry through the `ssr` environment's
+            // module runner, which only a runnable environment has. A host plugin
+            // that backs that environment with its own runtime — workerd, under a
+            // Workers plugin — leaves it non-runnable, and that host is already the
+            // one serving pages: its entry imports `renderPage` and answers the
+            // request itself. Standing down hands those requests to it. Rendering
+            // them here instead would run the application in Node, without the
+            // 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.');
+                return;
+            }
             const requestUrls = new WeakMap();
             const stateByRequest = new WeakMap();
             const render = renderMiddleware(server, options, requestUrls, stateByRequest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.19.0-canary.f656c022545d",
+  "version": "0.20.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.112",
-    "foldkit": "0.154.0-canary.f656c022545d",
+    "foldkit": ">=0.153.0",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "dependencies": {
@@ -28,13 +28,13 @@
     "@types/node": "^26.4.0",
     "@types/ws": "^8.18.1",
     "effect": "4.0.0-rc.112",
-    "happy-dom": "^20.11.8",
+    "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.154.0-canary.f656c022545d"
+    "foldkit": "0.155.0"
   },
   "keywords": [
     "vite",