@foldkit/vite-plugin 0.26.0 → 0.26.1-canary.085b787da0a5

package/README.md

@@ -65,6 +65,54 @@ With this set, the dev server converts HTML page requests to Web `Request` value
 
 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.
 
+## Server-rendered documents
+
+With `ssr.build`, the client input is a script and the server entry produces the complete HTML document. Configure the script beside the server entry:
+
+```typescript
+foldkit({
+  ssr: {
+    clientEntry: '/src/entry.ts',
+    serverEntry: '/src/entry.server.ts',
+    build: true,
+  },
+})
+```
+
+Import CSS from the client script. Export `renderDocument` alongside `renderPage` in the server entry:
+
+```typescript
+export const renderDocument = Server.renderDocument
+```
+
+`Server.renderDocument(application, assets, options)` assembles the document with the application's title, language, direction, canonical URL, and Open Graph URL. `assets` contains the emitted `entryScript`, ordered `stylesheets`, and `modulePreloads`. The plugin collects static imports and their CSS, leaves lazy imports to Vite's runtime, and supplies the same assets to request-time rendering and prerendering. The default document includes UTF-8 and viewport metadata. Wrap the helper to set a default `lang` or add trusted author-owned `head` markup, such as a favicon. Never interpolate unescaped request data into `head`.
+
+The client build starts from a script rather than HTML. `index.html` appears in the client output only when prerendering generates `/`. The build refuses an existing root document copied from `publicDir`, emitted by another plugin, or left by an earlier build when `emptyOutDir` is disabled. Remove the source `index.html` when migrating an SSR build, move its stylesheet links into client imports, and move document tags into `renderDocument`. Build-time `transformIndexHtml` hooks do not run with a script input. In development, Vite transforms the rendered document for HMR and dev HTML hooks. `containerId` belongs only to a template-based custom host and cannot be combined with `clientEntry`.
+
+Use a root-relative `clientEntry`, such as `/src/entry.ts`, and an absolute-path or full-URL Vite `base`. Relative bases (`''` and `'./'`) are rejected because their asset URLs would resolve differently on nested routes. `modulePreload` configuration and absolute `experimental.renderBuiltUrl` results apply to the generated document; relative and runtime `renderBuiltUrl` results are rejected.
+
+The standalone build plugin takes `foldkitBuild(serverEntry, { clientEntry, ...options })`. Omitting `clientEntry` and `ssr.build` selects the template-based development host for a custom build pipeline. Hosts that own an HTML template can use the lower-level `injectIntoTemplate`, `toResponse`, and `handleRequest(request, { template, renderPage })` APIs.
+
+## Foldkit package resolution
+
+Each module graph must load one Foldkit copy. The plugin configures Vite for that:
+
+- `resolve.dedupe` lists `foldkit`, `@foldkit/ui`, and `@foldkit/devtools`, each only when it resolves from the application root.
+- In server builds and in every server environment of the dev server, the plugin bundles those three packages, plus every installed package whose `dependencies` or `peerDependencies` include `foldkit` or an `@foldkit/*` package, such as `@foldkit/markdown`. The plugin lists them in `resolve.noExternal`, which Vite applies to every environment, and in `ssr.noExternal`. In a Node server environment of the dev server, these packages run through Vite's module runner instead of Node's own import. An explicit `ssr.external` or `resolve.external` entry still keeps a package external.
+- The plugin finds these packages by crawling from the application's `package.json`. It follows the application's `dependencies` and `devDependencies`, then the `dependencies` of each package it bundles, plus the `devDependencies` of a bundled package that is a private workspace package.
+- The plugin excludes `foldkit` from dependency pre-bundling in every environment, so the build id transform runs on it. It also pre-bundles the Effect entries Foldkit imports in every environment whose optimizer is enabled, for example a Cloudflare Worker environment, so Foldkit and the application share one Effect instance. Applications need no `optimizeDeps` settings for Foldkit.
+
+A package the crawl does not reach stays external. For example: a peer the application does not declare, or a package reached only through a package that does not depend on Foldkit. Such a package loads a second Foldkit copy from `node_modules` at runtime. Declare it in the application's `package.json`, or add it to `resolve.noExternal`, which Vite applies to every environment:
+
+```typescript
+export default defineConfig({
+  plugins: [foldkit()],
+  resolve: { noExternal: ['foldkit-component-library'] },
+})
+```
+
+Vitest copies each environment's `resolve.noExternal` into `server.deps.inline`. A Vitest config that includes `foldkit()` therefore also inlines the crawled packages in tests.
+
 ## Completed build metadata
 
 Deployment tools that run Vite in process can read `foldkit:build` through Vite's standard plugin `api` field. Await the full application build before reading:

package/dist/build.d.ts

@@ -15,25 +15,15 @@ export type FoldkitPrerenderOptions = Readonly<{
      * from `Request.url`, in which case it should match the published origin.
      */
     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<{
+    /** Root-relative browser script entry resolved by Vite, such as `'/src/entry.ts'`. Import stylesheets from this module. */
+    clientEntry: 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.
@@ -134,8 +124,9 @@ export declare const renderTargetFor: (clientDirectory: string, path: string, or
  *
  * Vite builds both environments, so a deployment target that runs `vite build`
  * gets the browser and server bundles. The `fetch` handler and generated pages
- * use the HTML emitted by the browser build, but the unrendered template is not
- * published with the assets. The server bundle's default export is `{ fetch }`.
+ * use the server entry's `renderDocument` export with the emitted browser assets.
+ * The browser build has a script input and emits no HTML until prerendering.
+ * The server bundle's default export is `{ fetch }`.
  */
-export declare const foldkitBuild: (serverEntry: string, options?: FoldkitBuildOptions) => Plugin<FoldkitBuildApi>;
+export declare const foldkitBuild: (serverEntry: string, options: FoldkitBuildOptions) => Plugin<FoldkitBuildApi>;
 //# 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,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAI/B,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;;;;;OAKG;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;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;IAEH;;;;OAIG;;IAEH,+EAA+E;;IAE/E,2DAA2D;;IAE3D,6EAA6E;;EAE7E,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE,iFAAiF;AACjF,eAAO,MAAM,oBAAoB;IAC/B,+CAA+C;;IAE/C,kDAAkD;;IAElD,iDAAiD;;IAEjD,kDAAkD;;IAElD,0DAA0D;;QAtC1D;;;;WAIG;;QAEH;;;;WAIG;;QAEH,+EAA+E;;QAE/E,2DAA2D;;QAE3D,6EAA6E;;;EAwB7E,CAAA;AAEF,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,aAAa,EAAE,OAAO,uBAAuB,CAAA;IAC7C;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;CAC7C,CAAC,CAAA;AAcF,eAAO,MAAM,YAAY,SACjB,MAAM,aACD,MAAM,YACR,OAAO,QAAQ,KACvB,MAQF,CAAA;AAyFD,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;AAsFD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,gBACV,MAAM,YACV,mBAAmB,KAC3B,MAAM,CAAC,eAAe,CAqPxB,CAAA"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,MAAM,EAAE,MAAM,QAAQ,CAAA;AAS1C,OAAO,QAA8B,MAAM,WAAW,CAAA;AAEtD,OAAO,KAAK,EAGV,MAAM,EAGP,MAAM,MAAM,CAAA;AAEb,mEAAmE;AACnE,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAC,CAAA;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,2HAA2H;IAC3H,WAAW,EAAE,MAAM,CAAA;IACnB,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,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,0BAA0B,CAAA;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;IAEH;;;;OAIG;;IAEH,+EAA+E;;IAE/E,2DAA2D;;IAE3D,6EAA6E;;EAE7E,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE,iFAAiF;AACjF,eAAO,MAAM,oBAAoB;IAC/B,+CAA+C;;IAE/C,kDAAkD;;IAElD,iDAAiD;;IAEjD,kDAAkD;;IAElD,0DAA0D;;QAtC1D;;;;WAIG;;QAEH;;;;WAIG;;QAEH,+EAA+E;;QAE/E,2DAA2D;;QAE3D,6EAA6E;;;EAwB7E,CAAA;AAEF,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,aAAa,EAAE,OAAO,uBAAuB,CAAA;IAC7C;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;CAC7C,CAAC,CAAA;AAcF,eAAO,MAAM,YAAY,SACjB,MAAM,aACD,MAAM,YACR,OAAO,QAAQ,KACvB,MAQF,CAAA;AA6FD,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;AAqLD;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,gBACV,MAAM,WACV,mBAAmB,KAC3B,MAAM,CAAC,eAAe,CAwSxB,CAAA"}

package/dist/build.js

@@ -1,6 +1,7 @@
-import { Schema } from 'effect';
-import { randomUUID } from 'node:crypto';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { Predicate, Schema } from 'effect';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 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. */
@@ -64,12 +65,15 @@ export const manifestPath = (root, directory, pathApi = nodePath) => {
     return related.split(pathApi.sep).join('/');
 };
 const MANIFEST_FILE_NAME = 'foldkit.build.json';
-const TEMPLATE_FILE_NAME = 'index.html';
 const DEFAULT_CLIENT_OUT_DIR = 'dist/client';
 const DEFAULT_SERVER_OUT_DIR = 'dist/server';
 const DEFAULT_PRERENDER_ORIGIN = 'http://localhost';
 const FETCH_CHUNK_NAME = 'fetch';
 const RESOLVED_FETCH_MODULE_ID = `\0${FOLDKIT_FETCH_MODULE_ID}`;
+const CLIENT_MODULE_ID = 'virtual:foldkit/client';
+const RESOLVED_CLIENT_MODULE_ID = `\0${CLIENT_MODULE_ID}`;
+const CLIENT_CHUNK_NAME = 'app';
+const VITE_CONSOLIDATED_CSS_ORIGINAL_NAME = 'style.css';
 // 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
@@ -168,39 +172,104 @@ const prerenderOptionsFrom = (prerender) => {
     }
     return prerender === true ? {} : prerender;
 };
-const fetchModuleSource = (serverEntry, template, containerId) => {
-    const containerLiteral = containerId === undefined ? 'undefined' : JSON.stringify(containerId);
+const documentHash = (document) => createHash('sha256').update(document).digest('hex');
+const collectDocumentAssets = (outputs, config) => {
+    const entryFile = serverEntryFile(outputs, CLIENT_CHUNK_NAME);
+    const chunks = new Map(outputs.flatMap(output => output.type === 'chunk' ? [[output.fileName, output]] : []));
+    const visited = new Set();
+    const stylesheets = new Set();
+    const modulePreloads = new Set();
+    const visit = (fileName) => {
+        if (visited.has(fileName)) {
+            return;
+        }
+        visited.add(fileName);
+        const chunk = chunks.get(fileName);
+        if (chunk === undefined) {
+            return;
+        }
+        for (const imported of chunk.imports) {
+            visit(imported);
+        }
+        for (const stylesheet of chunk.viteMetadata?.importedCss ?? []) {
+            stylesheets.add(stylesheet);
+        }
+        if (fileName !== entryFile) {
+            modulePreloads.add(fileName);
+        }
+    };
+    visit(entryFile);
+    if (!config.build.cssCodeSplit) {
+        for (const output of outputs) {
+            if (output.type === 'asset' &&
+                output.originalFileNames.includes(VITE_CONSOLIDATED_CSS_ORIGINAL_NAME)) {
+                stylesheets.add(output.fileName);
+            }
+        }
+    }
+    const { modulePreload } = config.build;
+    const preloadFiles = modulePreload === false
+        ? []
+        : (modulePreload.resolveDependencies?.(entryFile, [...modulePreloads], {
+            hostId: 'index.html',
+            hostType: 'html',
+        }) ?? [...modulePreloads]);
+    const assetUrl = (fileName) => {
+        if (/^([a-z]+:)?\/\//.test(fileName)) {
+            return fileName;
+        }
+        const builtUrl = config.experimental.renderBuiltUrl?.(fileName, {
+            hostId: 'index.html',
+            hostType: 'html',
+            type: 'asset',
+            ssr: false,
+        });
+        if (Predicate.isString(builtUrl)) {
+            if (!builtUrl.startsWith('/') && !/^https?:\/\//.test(builtUrl)) {
+                throw new Error('[foldkit] renderBuiltUrl must return an absolute URL or root-relative URL for document assets.');
+            }
+            return builtUrl;
+        }
+        if (builtUrl?.runtime !== undefined || builtUrl?.relative === true) {
+            throw new Error('[foldkit] document assets cannot use runtime or relative renderBuiltUrl results.');
+        }
+        return `${config.base}${encodeURI(fileName).replace(/[?#]/g, encodeURIComponent)}`;
+    };
+    return Object.freeze({
+        entryScript: assetUrl(entryFile),
+        stylesheets: Object.freeze([...stylesheets].map(assetUrl)),
+        modulePreloads: Object.freeze(preloadFiles.map(assetUrl)),
+    });
+};
+const fetchModuleSource = (serverEntry, assets) => {
     // 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 { renderDocument } from ${JSON.stringify(serverEntry)}`,
         `import * as server from ${JSON.stringify(serverEntry)}`,
         `export * from ${JSON.stringify(serverEntry)}`,
-        `const template = ${JSON.stringify(template)}`,
-        `const containerId = ${containerLiteral}`,
+        `const assets = ${JSON.stringify(assets)}`,
+        `Object.freeze(assets.stylesheets)`,
+        `Object.freeze(assets.modulePreloads)`,
+        `Object.freeze(assets)`,
         `export default {`,
         `  fetch(request) {`,
         `    return handleRequest(request, {`,
         `      renderPage: server.renderPage,`,
-        `      template,`,
-        `      containerId,`,
+        `      renderDocument: application => renderDocument(application, assets),`,
         `    })`,
         `  },`,
         `}`,
         ``,
     ].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 ${TEMPLATE_FILE_NAME}, so the fetch handler has no template to render into. Build the "client" environment before "ssr", and give the client an HTML entry.`);
+const assetsForFetchModule = (assets) => {
+    if (assets === undefined) {
+        throw new Error('[foldkit] the browser build has not emitted its script entry. Build the "client" environment before "ssr" so the document can reference the emitted assets.');
     }
-    return capturedTemplate;
+    return assets;
 };
 /**
  * Builds a Web `fetch` handler alongside the browser build, and generates
@@ -208,21 +277,21 @@ const templateForFetchModule = (capturedTemplate) => {
  *
  * Vite builds both environments, so a deployment target that runs `vite build`
  * gets the browser and server bundles. The `fetch` handler and generated pages
- * use the HTML emitted by the browser build, but the unrendered template is not
- * published with the assets. The server bundle's default export is `{ fetch }`.
+ * use the server entry's `renderDocument` export with the emitted browser assets.
+ * The browser build has a script input and emits no HTML until prerendering.
+ * The server bundle's default export is `{ fetch }`.
  */
-export const foldkitBuild = (serverEntry, options = {}) => {
+export const foldkitBuild = (serverEntry, options) => {
     const state = {};
     let metadata;
     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
     // exactly those terms. Nothing here is imported when prerendering is off.
-    const generatePages = async (builder, template, clientDirectory, serverDirectory, entryFileName) => {
+    const generatePages = async (builder, clientDirectory, serverDirectory, entryFileName) => {
         if (prerender === undefined) {
             return [];
         }
@@ -242,15 +311,19 @@ export const foldkitBuild = (serverEntry, options = {}) => {
         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');
+        if (!Predicate.isFunction(entry.renderDocument)) {
+            throw new Error(`[foldkit] "${entryFileName}" exports no renderDocument function.`);
+        }
+        const assets = assetsForFetchModule(state.assets);
         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 });
+            const html = entry.renderDocument(renderedApplication(path, result), assets);
             await mkdir(dirname(file), { recursive: true });
             await writeFile(file, html);
+            if (path === '/') {
+                state.prerenderedRootHash = documentHash(html);
+            }
             builder.config.logger.info(`  generated ${path}`);
         }
         return paths;
@@ -264,15 +337,16 @@ export const foldkitBuild = (serverEntry, options = {}) => {
         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 ${TEMPLATE_FILE_NAME} to generate pages from. Prerendering needs an HTML entry.`);
-            }
-            return state.template;
-        };
-        const prerendered = await generatePages(builder, template, clientDirectory, serverDirectory, state.serverEntryFile);
+        const rootDocumentPath = resolve(clientDirectory, 'index.html');
+        if (existsSync(rootDocumentPath) &&
+            documentHash(await readFile(rootDocumentPath, 'utf8')) !==
+                state.prerenderedRootHash) {
+            throw new Error('[foldkit] the browser output contains index.html before prerendering. Remove it from publicDir or the plugin that emits it, and clear stale output when emptyOutDir is disabled. Only prerendering may generate the root document in an ssr.build output.');
+        }
+        const prerendered = await generatePages(builder, clientDirectory, serverDirectory, state.serverEntryFile);
+        if (!prerendered.includes('/') && existsSync(rootDocumentPath)) {
+            throw new Error('[foldkit] index.html remains in the browser output, but this build did not prerender "/". Clear the previous root document before building without it.');
+        }
         const manifest = FoldkitBuildManifest.make({
             schemaVersion: MANIFEST_SCHEMA_VERSION,
             client: manifestPath(builder.config.root, clientDirectory),
@@ -311,9 +385,17 @@ export const foldkitBuild = (serverEntry, options = {}) => {
             order: 'pre',
             handler() {
                 if (this.environment.name === 'client') {
-                    delete state.template;
+                    delete state.assets;
                     delete state.serverEntryFile;
                     metadata = undefined;
+                    const { input } = this.environment.config.build.rolldownOptions;
+                    const inputs = Predicate.isString(input)
+                        ? [input]
+                        : Object.values(input ?? {});
+                    if (!inputs.includes(CLIENT_MODULE_ID) ||
+                        inputs.some(entry => /\.html(?:[?#]|$)/.test(entry))) {
+                        throw new Error('[foldkit] ssr.build owns the browser script input. Configure ssr.clientEntry instead of an HTML input or a replacement client input.');
+                    }
                 }
                 else if (this.environment.name === 'ssr') {
                     delete state.serverEntryFile;
@@ -322,20 +404,27 @@ export const foldkitBuild = (serverEntry, options = {}) => {
             },
         },
         resolveId(id) {
+            if (id === CLIENT_MODULE_ID) {
+                return RESOLVED_CLIENT_MODULE_ID;
+            }
             if (id === FOLDKIT_FETCH_MODULE_ID) {
                 return RESOLVED_FETCH_MODULE_ID;
             }
             return undefined;
         },
         load(id) {
+            if (id === RESOLVED_CLIENT_MODULE_ID) {
+                const { modulePreload } = this.environment.config.build;
+                const polyfill = modulePreload !== false && modulePreload.polyfill
+                    ? "import 'vite/modulepreload-polyfill'\n"
+                    : '';
+                return `${polyfill}import ${JSON.stringify(options.clientEntry)}\n`;
+            }
             if (id !== RESOLVED_FETCH_MODULE_ID) {
                 return;
             }
-            const template = templateForFetchModule(state.template);
-            return fetchModuleSource(serverEntry, template, containerId);
+            return fetchModuleSource(serverEntry, assetsForFetchModule(state.assets));
         },
-        // NOTE: `order: 'post'` because Vite's own HTML plugin emits `index.html`
-        // from a `generateBundle` of its own; post is guaranteed to run after it.
         generateBundle: {
             order: 'post',
             handler(_options, bundle) {
@@ -346,17 +435,15 @@ export const foldkitBuild = (serverEntry, options = {}) => {
                 if (this.environment.name !== 'client') {
                     return;
                 }
-                const html = bundle[TEMPLATE_FILE_NAME];
-                if (html === undefined || html.type !== 'asset') {
-                    return;
-                }
-                state.template = String(html.source);
-                delete bundle[TEMPLATE_FILE_NAME];
+                state.assets = collectDocumentAssets(Object.values(bundle), this.environment.config);
             },
         },
         config: userConfig => {
             const client = {
-                build: { outDir: clientOutDir },
+                build: {
+                    outDir: clientOutDir,
+                    rolldownOptions: { input: { [CLIENT_CHUNK_NAME]: CLIENT_MODULE_ID } },
+                },
             };
             const ssr = {
                 build: {
@@ -387,6 +474,16 @@ export const foldkitBuild = (serverEntry, options = {}) => {
                 }
                 : { environments: { client, ssr } };
         },
+        configResolved(config) {
+            if (config.base === '' || config.base === './') {
+                throw new Error('[foldkit] ssr.build requires an absolute URL or root-relative base, such as "/" or "/app/". A relative base cannot locate browser assets consistently across server-rendered routes.');
+            }
+            if (!options.clientEntry?.startsWith('/') ||
+                options.clientEntry.startsWith('//') ||
+                /\.html(?:[?#]|$)/.test(options.clientEntry)) {
+                throw new Error("[foldkit] ssr.build requires clientEntry to name a browser script. Move stylesheet imports into that script and document markup into the server entry's renderDocument export.");
+            }
+        },
         // 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

package/dist/devToolsOverlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"devToolsOverlay.d.ts","sourceRoot":"","sources":["../src/devToolsOverlay.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAsJlC;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,YAC7B,OAAO,GAAG,OAAO,QACpB,MAAM,KACX,OAQF,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,QAAO,MA+DxC,CAAA"}
+{"version":3,"file":"devToolsOverlay.d.ts","sourceRoot":"","sources":["../src/devToolsOverlay.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAoIlC;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,YAC7B,OAAO,GAAG,OAAO,QACpB,MAAM,KACX,OAQF,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,QAAO,MAmExC,CAAA"}

package/dist/devToolsOverlay.js

@@ -1,26 +1,12 @@
-import { Array, Option, Record, Schema } from 'effect';
+import { Option, Record, Schema } from 'effect';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 const DEV_TOOLS_PACKAGE_NAME = '@foldkit/devtools';
-const FOLDKIT_PACKAGE_NAME = 'foldkit';
 const DEV_TOOLS_VITE_EXPORT = './vite';
 const DEV_TOOLS_OVERLAY_MODULE_ID = 'virtual:foldkit-devtools-overlay';
 const RESOLVED_DEV_TOOLS_OVERLAY_MODULE_ID = `\0${DEV_TOOLS_OVERLAY_MODULE_ID}`;
 const DEV_TOOLS_VITE_IMPORT_SPECIFIER = `${DEV_TOOLS_PACKAGE_NAME}${DEV_TOOLS_VITE_EXPORT.slice(1)}`;
 const DEV_TOOLS_HOST_IMPORT_SPECIFIER = 'foldkit/devtools-host';
-// NOTE: Vite's dependency scan cannot discover this virtual module's imports.
-// Declaring registry-installed imports before the first request avoids a
-// mid-session reoptimization and page reload.
-const DEV_TOOLS_OVERLAY_IMPORTS = [
-    {
-        specifier: DEV_TOOLS_VITE_IMPORT_SPECIFIER,
-        packageName: DEV_TOOLS_PACKAGE_NAME,
-    },
-    {
-        specifier: DEV_TOOLS_HOST_IMPORT_SPECIFIER,
-        packageName: FOLDKIT_PACKAGE_NAME,
-    },
-];
 const DEV_TOOLS_OVERLAY_MODULE_SOURCE = `
 import { overlay } from '${DEV_TOOLS_VITE_IMPORT_SPECIFIER}'
 import { __setDevToolsOverlay } from '${DEV_TOOLS_HOST_IMPORT_SPECIFIER}'
@@ -79,8 +65,7 @@ const resolvePackageDirectory = Option.liftThrowable((packageJsonPath) => realpa
 // NOTE: Vite serves linked packages from source rather than pre-bundling them.
 // A registry-installed package has a real path under `node_modules`, while a
 // workspace link resolves to its source checkout; force-including a link would
-// cache its current source and hide edits. Each owner is checked independently
-// because one package may be linked while the other is installed.
+// cache its current source and hide edits.
 const isPackageResolvedIntoNodeModules = (root, packageName) => findInstalledPackageJsonPath(root, packageName).pipe(Option.flatMap(resolvePackageDirectory), Option.exists(packageDirectory => packageDirectory.split(sep).includes('node_modules')));
 const isDevToolsProductionDependency = (root) => findApplicationPackageJsonPath(root).pipe(Option.flatMap(packageJsonPath => readPackageJson(decodeApplicationPackageJson, packageJsonPath)), Option.flatMapNullishOr(packageJson => packageJson.dependencies), Option.exists(Record.has(DEV_TOOLS_PACKAGE_NAME)));
 /**
@@ -111,11 +96,19 @@ export const devToolsOverlayPlugin = () => {
                 !shouldInjectDevToolsOverlay(environment.command, root)) {
                 return undefined;
             }
-            const include = DEV_TOOLS_OVERLAY_IMPORTS.filter(({ packageName }) => isPackageResolvedIntoNodeModules(root, packageName)).map(({ specifier }) => specifier);
-            return Array.match(include, {
-                onEmpty: () => undefined,
-                onNonEmpty: () => ({ optimizeDeps: { include } }),
-            });
+            // NOTE: Vite's dependency scan cannot discover the virtual module's
+            // imports, so a registry-installed `@foldkit/devtools/vite` is declared
+            // before the first request to avoid a mid-session reoptimization and page
+            // reload. `foldkit/devtools-host` is deliberately not declared. The plugin
+            // excludes `foldkit` and serves it from source. Vite resolves a
+            // force-included specifier to its pre-bundle before consulting `exclude`.
+            // That would give the overlay its own copy of the DevTools config.
+            if (isPackageResolvedIntoNodeModules(root, DEV_TOOLS_PACKAGE_NAME)) {
+                return { optimizeDeps: { include: [DEV_TOOLS_VITE_IMPORT_SPECIFIER] } };
+            }
+            else {
+                return undefined;
+            }
         },
         configResolved: config => {
             isInjectionEnabled = shouldInjectDevToolsOverlay(config.command, config.root);

package/dist/foldkitPackages.d.ts

@@ -1,12 +1,17 @@
+import { type UserConfig } from 'vite';
 /** Tests whether an import refers to a package that must share Foldkit's
  * runtime instance.
  *
  * @internal
  */
 export declare const isFoldkitSingletonPackageSpecifier: (specifier: string) => boolean;
-/** Resolves the installed packages that must share Foldkit's runtime instance.
+/** Finds the installed packages an application's server render must bundle
+ * and the Foldkit packages Vite must deduplicate.
  *
  * @internal
  */
-export declare const resolveInstalledFoldkitPackages: (root: string) => Array<string>;
+export declare const crawlFoldkitPackages: (root: string, isBuild: boolean, viteUserConfig: UserConfig) => Promise<Readonly<{
+    dedupe: Array<string>;
+    noExternal: Array<string>;
+}>>;
 //# sourceMappingURL=foldkitPackages.d.ts.map

package/dist/foldkitPackages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"foldkitPackages.d.ts","sourceRoot":"","sources":["../src/foldkitPackages.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,cAClC,MAAM,KAChB,OAKA,CAAA;AAEH;;;GAGG;AACH,eAAO,MAAM,+BAA+B,SACpC,MAAM,KACX,KAAK,CAAC,MAAM,CAmBd,CAAA"}
+{"version":3,"file":"foldkitPackages.d.ts","sourceRoot":"","sources":["../src/foldkitPackages.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,UAAU,EAA0B,MAAM,MAAM,CAAA;AAS9D;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,cAClC,MAAM,KAChB,OAKA,CAAA;AA8CH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,SACzB,MAAM,WACH,OAAO,kBACA,UAAU,KACzB,OAAO,CAAC,QAAQ,CAAC;IAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAoCxE,CAAA"}

package/dist/foldkitPackages.js

@@ -1,6 +1,8 @@
-import { Array, Predicate } from 'effect';
-import { createRequire } from 'node:module';
+import { Array, Option, Record, Schema, pipe } from 'effect';
+import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { searchForWorkspaceRoot } from 'vite';
+import { crawlFrameworkPkgs, findDepPkgJsonPath } from 'vitefu';
 const FOLDKIT_SINGLETON_PACKAGES = [
     'foldkit',
     '@foldkit/ui',
@@ -12,26 +14,55 @@ const FOLDKIT_SINGLETON_PACKAGES = [
  * @internal
  */
 export const isFoldkitSingletonPackageSpecifier = (specifier) => Array.some(FOLDKIT_SINGLETON_PACKAGES, packageName => specifier === packageName || specifier.startsWith(`${packageName}/`));
-/** Resolves the installed packages that must share Foldkit's runtime instance.
+const isFoldkitPackageName = (name) => name === 'foldkit' || name.startsWith('@foldkit/');
+const decodeDependencyRecord = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Unknown));
+const dependencyNames = (field) => Option.match(decodeDependencyRecord(field), {
+    onNone: () => [],
+    onSome: Record.keys,
+});
+const dependsOnFoldkit = (packageJson) => pipe([packageJson['dependencies'], packageJson['peerDependencies']], Array.flatMap(dependencyNames), Array.some(isFoldkitPackageName));
+const toRealPath = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+};
+const toCrawlRoot = (root, isPreservingSymlinks) => {
+    const absoluteRoot = resolve(root);
+    // NOTE: The crawl and the dedupe lookup must start from the root Vite
+    // resolves from: the path as given under resolve.preserveSymlinks, and its
+    // realpath otherwise. Any other root makes them walk a different directory
+    // chain than Vite's resolver.
+    if (isPreservingSymlinks) {
+        return absoluteRoot;
+    }
+    return toRealPath(absoluteRoot);
+};
+/** Finds the installed packages an application's server render must bundle
+ * and the Foldkit packages Vite must deduplicate.
  *
  * @internal
  */
-export const resolveInstalledFoldkitPackages = (root) => {
-    // NOTE: Vite can supply a relative root before it resolves the config, while
-    // createRequire requires an absolute path.
-    const requireFromRoot = createRequire(resolve(root, 'noop.js'));
-    return Array.filter(FOLDKIT_SINGLETON_PACKAGES, packageName => {
-        try {
-            requireFromRoot.resolve(packageName);
-            return true;
-        }
-        catch (error) {
-            // NOTE: optional ESM-only packages can throw
-            // ERR_PACKAGE_PATH_NOT_EXPORTED even when installed. Only
-            // MODULE_NOT_FOUND proves this consumer does not have the package.
-            return !(error instanceof Error &&
-                Predicate.hasProperty(error, 'code') &&
-                error.code === 'MODULE_NOT_FOUND');
-        }
+export const crawlFoldkitPackages = async (root, isBuild, viteUserConfig) => {
+    const crawlRoot = toCrawlRoot(root, viteUserConfig.resolve?.preserveSymlinks ?? false);
+    // NOTE: vitefu realpaths each dependency's package.json before comparing it
+    // with workspaceRoot, including when Vite preserves symlinks. The workspace
+    // boundary must use the same form so private workspace packages are found.
+    const workspaceRoot = toRealPath(searchForWorkspaceRoot(crawlRoot));
+    const crawl = await crawlFrameworkPkgs({
+        root: crawlRoot,
+        workspaceRoot,
+        isBuild,
+        viteUserConfig,
+        isSemiFrameworkPkgByJson: dependsOnFoldkit,
     });
+    const noExternal = Array.dedupe([
+        ...FOLDKIT_SINGLETON_PACKAGES,
+        ...crawl.ssr.noExternal,
+    ]);
+    const maybeResolvableSingletons = await Promise.all(Array.map(FOLDKIT_SINGLETON_PACKAGES, async (packageName) => pipe(await findDepPkgJsonPath(packageName, crawlRoot), Option.fromUndefinedOr, Option.as(packageName))));
+    const dedupe = Array.getSomes(maybeResolvableSingletons);
+    return { dedupe, noExternal };
 };

package/dist/index.d.ts

@@ -25,7 +25,10 @@ export type FoldkitPluginOptions = Readonly<{
      * `ssr.serverEntry`. When `undefined` (the default), the dev server
      * serves the client entry only.
      */
-    ssr?: Omit<FoldkitSsrOptions, 'buildId' | 'quietStandDown'> & Readonly<{
+    ssr?: Omit<FoldkitSsrOptions, 'buildId' | 'quietStandDown' | 'clientEntry' | 'containerId'> & (Readonly<{
+        /** Root-relative browser script for the server entry's code-rendered document. */
+        clientEntry: string;
+        containerId?: never;
         /**
          * Build a Web `fetch` handler alongside the browser build, and generate
          * static HTML from the server entry, inside this project's own
@@ -35,8 +38,13 @@ export type FoldkitPluginOptions = Readonly<{
          *
          * When this is absent, `vite build` builds the browser bundle only.
          */
-        build?: boolean | FoldkitBuildOptions;
-    }>;
+        build?: boolean | Omit<FoldkitBuildOptions, 'clientEntry'>;
+    }> | Readonly<{
+        /** Use a custom template-based development and build pipeline. */
+        clientEntry?: never;
+        containerId?: string;
+        build?: false;
+    }>);
     /**
      * An explicit identity for the deployment this build belongs to. Foldkit
      * normally generates an opaque identity when one Vite app build coordinates

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAEV,MAAM,EAIP,MAAM,MAAM,CAAA;AAOb,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,YAAY,CAAA;AAKnE,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,oBAAoB,EACpB,KAAK,eAAe,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;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAChC;;;;;;;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;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AAs6BF,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CAuHxE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAGV,MAAM,EAIP,MAAM,MAAM,CAAA;AAOb,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,YAAY,CAAA;AAKnE,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,oBAAoB,EACpB,KAAK,eAAe,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;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAChC;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,IAAI,CACR,iBAAiB,EACjB,SAAS,GAAG,gBAAgB,GAAG,aAAa,GAAG,aAAa,CAC7D,GACC,CACI,QAAQ,CAAC;QACP,kFAAkF;QAClF,WAAW,EAAE,MAAM,CAAA;QACnB,WAAW,CAAC,EAAE,KAAK,CAAA;QACnB;;;;;;;;WAQG;QACH,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,mBAAmB,EAAE,aAAa,CAAC,CAAA;KAC3D,CAAC,GACF,QAAQ,CAAC;QACP,kEAAkE;QAClE,WAAW,CAAC,EAAE,KAAK,CAAA;QACnB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,KAAK,CAAC,EAAE,KAAK,CAAA;KACd,CAAC,CACL,CAAA;IACH;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AAg6BF,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CA+IxE,CAAA"}

package/dist/index.js

@@ -10,7 +10,7 @@ import * as NodePath from '@effect/platform-node/NodePath';
 import { foldkitBuild } from './build.js';
 import { foldkitBuildToken } from './buildToken.js';
 import { devToolsOverlayPlugin } from './devToolsOverlay.js';
-import { resolveInstalledFoldkitPackages } from './foldkitPackages.js';
+import { crawlFoldkitPackages } from './foldkitPackages.js';
 import { publishRelayRecord, retireRelayRecord } from './relayRegistry.js';
 import { foldkitSsr } from './ssr.js';
 import { foldkitViewIdentity } from './viewIdentity.js';
@@ -18,16 +18,15 @@ export { brandDistDirectory } from './brandDist.js';
 export { FOLDKIT_FETCH_MODULE_ID, FoldkitBuildManifest, FoldkitBuildMetadata, 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`
-// imports and pre-bundles only those exports into a single `effect.js`
-// blob. It does not follow imports through workspace/node_modules
-// packages, so any `effect` namespace foldkit's compiled dist references
-// that the consumer does not mention by name is missing from the blob
-// and crashes at runtime in dev. The list below covers every top-level
-// namespace foldkit imports from bare `'effect'`. Over-inclusion is
-// harmless; under-inclusion is the bug. Kept in sync with foldkit's
-// source by `scripts/check-effect-prebundle.ts` (runs in `pnpm check`).
-const FORCE_INCLUDED_EFFECT_NAMESPACES = [
+// NOTE: Vite does not scan imports through `foldkit` because the plugin
+// excludes the package from optimization in every environment. A consumer can
+// import only Effect subpaths while Foldkit's compiled distribution imports the
+// bare barrel, so include both the barrel and every top-level namespace Foldkit
+// imports. This keeps them in one optimized dependency graph. Over-inclusion is
+// harmless; under-inclusion is the bug. `scripts/check-effect-prebundle.ts`
+// keeps the entries in sync with Foldkit's source and runs in `pnpm check`.
+const FORCE_INCLUDED_EFFECT_ENTRIES = [
+    'effect',
     'effect/Array',
     'effect/Boolean',
     'effect/Cause',
@@ -55,6 +54,7 @@ const FORCE_INCLUDED_EFFECT_NAMESPACES = [
     'effect/PubSub',
     'effect/Queue',
     'effect/Record',
+    'effect/Redacted',
     'effect/Ref',
     'effect/Result',
     'effect/Runtime',
@@ -70,6 +70,16 @@ const FORCE_INCLUDED_EFFECT_NAMESPACES = [
     'effect/SubscriptionRef',
     'effect/Types',
 ];
+// NOTE: Adding includes to an environment whose optimizer is otherwise disabled
+// turns on Vite's explicit optimizer, which would pre-bundle Effect in Vite's
+// default Node `ssr` environment.
+const shouldForceEffectEntries = (name, config) => {
+    const consumer = config.consumer ?? (name === 'client' ? 'client' : 'server');
+    const isClientEnvironment = consumer === 'client';
+    const isDiscoveryEnabled = config.optimizeDeps?.noDiscovery === false;
+    const isExplicitOptimizationEnabled = Array.isArrayNonEmpty(config.optimizeDeps?.include ?? []);
+    return (isClientEnvironment || isDiscoveryEnabled || isExplicitOptimizationEnabled);
+};
 const Event = Data.taggedEnum();
 const makeState = Effect.gen(function* () {
     const preservedModels = yield* Ref.make(HashMap.empty());
@@ -474,27 +484,6 @@ 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) {
-        return options;
-    }
-    const withContainer = { ...options, containerId };
-    if (options.prerender === undefined) {
-        return withContainer;
-    }
-    const prerender = options.prerender === true ? {} : options.prerender;
-    if (prerender === false) {
-        return withContainer;
-    }
-    return {
-        ...withContainer,
-        prerender: { containerId, ...prerender },
-    };
-};
 const relayRegistryLayer = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer, NodeCrypto.layer);
 export const foldkit = (options = {}) => {
     // NOTE: During a Vite restart, old and new servers overlap. Separate queues
@@ -513,11 +502,15 @@ export const foldkit = (options = {}) => {
     const reloadPlugin = {
         name: 'foldkit',
         apply: 'serve',
-        config: () => ({
-            optimizeDeps: {
-                include: [...FORCE_INCLUDED_EFFECT_NAMESPACES],
-            },
-        }),
+        // NOTE: The `post` order runs this hook after every default-order
+        // `configEnvironment` hook, so the predicate sees discovery or includes
+        // that another plugin turns on there.
+        configEnvironment: {
+            order: 'post',
+            handler: (name, config) => shouldForceEffectEntries(name, config)
+                ? { optimizeDeps: { include: [...FORCE_INCLUDED_EFFECT_ENTRIES] } }
+                : undefined,
+        },
         configureServer: server => {
             const events = Effect.runSync(Queue.unbounded());
             // NOTE: The default ConfigProvider snapshots the environment. Create a
@@ -544,27 +537,30 @@ export const foldkit = (options = {}) => {
     };
     const resolutionPlugin = {
         name: 'foldkit:resolution',
-        config: userConfig => {
-            const singletonPackages = resolveInstalledFoldkitPackages(userConfig.root ?? process.cwd());
+        config: async (userConfig, { command }) => {
+            const foldkitPackages = await crawlFoldkitPackages(userConfig.root ?? process.cwd(), command === 'build', userConfig);
             return {
-                optimizeDeps: {
-                    exclude: ['foldkit'],
-                },
                 resolve: {
-                    dedupe: singletonPackages,
+                    dedupe: foldkitPackages.dedupe,
+                    noExternal: foldkitPackages.noExternal,
                 },
                 ssr: {
-                    noExternal: singletonPackages,
+                    noExternal: foldkitPackages.noExternal,
                 },
                 environments: {
                     ssr: {
                         resolve: {
-                            noExternal: singletonPackages,
+                            noExternal: foldkitPackages.noExternal,
                         },
                     },
                 },
             };
         },
+        configEnvironment: () => ({
+            optimizeDeps: {
+                exclude: ['foldkit'],
+            },
+        }),
     };
     const shared = [
         resolutionPlugin,
@@ -577,6 +573,9 @@ export const foldkit = (options = {}) => {
         return shared;
     }
     const { build, ...ssr } = options.ssr;
+    if (ssr.clientEntry !== undefined && ssr.containerId !== undefined) {
+        throw new Error('[foldkit] containerId belongs to an HTML template. A clientEntry build takes its complete document from renderDocument instead.');
+    }
     const servePages = foldkitSsr({
         ...ssr,
         ...(options.buildId === undefined ? {} : { buildId: options.buildId }),
@@ -585,9 +584,15 @@ export const foldkit = (options = {}) => {
     if (build === undefined || build === false) {
         return [...shared, servePages];
     }
+    if (ssr.clientEntry === undefined) {
+        throw new Error('[foldkit] ssr.build requires ssr.clientEntry to name the browser script and the server entry to export renderDocument.');
+    }
     return [
         ...shared,
         servePages,
-        foldkitBuild(ssr.serverEntry, withContainerId(build, ssr.containerId)),
+        foldkitBuild(ssr.serverEntry, {
+            ...(build === true ? {} : build),
+            clientEntry: ssr.clientEntry,
+        }),
     ];
 };

package/dist/ssr.d.ts

@@ -8,6 +8,12 @@ export type FoldkitSsrOptions = Readonly<{
      * `Promise<EntryResult>`.
      */
     serverEntry: string;
+    /**
+     * Root-relative browser script entry for a code-rendered document. The server entry must
+     * also export `renderDocument(application, assets)`. When absent, the dev
+     * host uses `index.html` for a custom template-based build pipeline.
+     */
+    clientEntry?: string;
     /**
      * The `id` of the empty container element in `index.html` the rendered
      * markup replaces. Defaults to `'root'`.

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;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC,CAAA;AAosBF;;;;;;;;;;;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;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;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;AA6tBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,YAAa,iBAAiB,KAAG,MAyGvD,CAAA"}

package/dist/ssr.js

@@ -132,19 +132,32 @@ const renderDecision = (nodeRequest, requestUrl) => {
 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)));
+    if (result._tag === 'Responded') {
+        return result.response;
+    }
+    if (options.clientEntry !== undefined) {
+        if (!('renderDocument' in loadedModule) ||
+            !Predicate.isFunction(loadedModule.renderDocument)) {
+            return yield* Effect.die(new Error(`[foldkit] '${options.serverEntry}' must export renderDocument(application, assets) when clientEntry is configured.`));
+        }
+        const assets = Server.DocumentAssets.make({
+            entryScript: options.clientEntry,
+            stylesheets: [],
+            modulePreloads: [],
+        });
+        const document = loadedModule.renderDocument(result.application, assets);
+        const transformed = yield* Effect.promise(() => server.transformIndexHtml(pathname, document, route));
+        return Server.toResponse(() => transformed, result);
+    }
+    const rawTemplate = yield* Effect.promise(() => readFile(resolve(server.config.root, 'index.html'), 'utf-8'));
+    // NOTE: Vite resolves template-relative URLs against the first argument;
+    // the template-based host's index lives at the root for nested page requests.
+    const template = yield* Effect.promise(() => server.transformIndexHtml('/index.html', rawTemplate, route));
     return Server.toResponse(template, result, options.containerId === undefined
         ? {}
         : { containerId: options.containerId });
@@ -461,9 +474,32 @@ const renderMiddleware = (server, options, requestUrls, stateByRequest) => (node
  * responses. Server entry edits take effect without a restart.
  */
 export const foldkitSsr = (options) => {
+    let isDevelopmentHost = false;
     return {
         name: 'foldkit-ssr',
-        config: (_config, { command, isPreview }) => {
+        configResolved(config) {
+            if (!isDevelopmentHost || options.clientEntry === undefined) {
+                return;
+            }
+            if (!options.clientEntry.startsWith('/') ||
+                options.clientEntry.startsWith('//') ||
+                /\.html(?:[?#]|$)/.test(options.clientEntry)) {
+                throw new Error('[foldkit] clientEntry must be a root-relative browser script URL, such as "/src/entry.ts".');
+            }
+            if (options.containerId !== undefined) {
+                throw new Error('[foldkit] containerId is only used by the template-based dev host. A code-rendered document owns its application placement.');
+            }
+            if (config.base === '' || config.base === './') {
+                throw new Error('[foldkit] code-rendered documents require an absolute URL or root-relative base so browser assets resolve consistently on nested routes.');
+            }
+        },
+        config: (config, { command, isPreview }) => {
+            isDevelopmentHost = command === 'serve' && isPreview !== true;
+            if (isDevelopmentHost &&
+                options.clientEntry !== undefined &&
+                (config.base === '' || config.base === './')) {
+                throw new Error('[foldkit] code-rendered documents require an absolute URL or root-relative base so browser assets resolve consistently on nested routes.');
+            }
             const buildId = buildIdForCommand(command, options.buildId);
             return {
                 // NOTE: `vite preview` also resolves with command 'serve', but it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.26.0",
+  "version": "0.26.1-canary.085b787da0a5",
   "description": "Vite plugin for Foldkit with state-preserving live reload",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,13 +17,14 @@
   ],
   "peerDependencies": {
     "effect": "4.0.0",
-    "foldkit": ">=0.165.0",
+    "foldkit": "0.166.0-canary.085b787da0a5",
     "vite": "^8.0.0"
   },
   "dependencies": {
     "@effect/platform-node": "4.0.0",
     "@effect/platform-node-shared": "4.0.0",
     "magic-string": "^1.4.2",
+    "vitefu": "^1.1.3",
     "ws": "^8.21.3"
   },
   "devDependencies": {
@@ -37,7 +38,7 @@
     "vite": "^8.3.1",
     "vite-host": "npm:vite@8.2.1",
     "vitest": "^4.1.11",
-    "foldkit": "0.165.0"
+    "foldkit": "0.166.0-canary.085b787da0a5"
   },
   "keywords": [
     "vite",