@foldkit/vite-plugin 0.23.0 → 0.24.0-canary.4187988d5940

package/README.md

@@ -65,6 +65,52 @@ 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.
 
+## 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:
+
+```typescript
+import type { FoldkitBuildApi } from '@foldkit/vite-plugin'
+import { createBuilder } from 'vite'
+
+const builder = await createBuilder()
+await builder.buildApp()
+
+const plugin = builder.config.plugins.find(
+  plugin => plugin.name === 'foldkit:build',
+)
+
+if (plugin !== undefined) {
+  const api: FoldkitBuildApi | undefined = plugin.api
+
+  if (typeof api?.getBuildMetadata !== 'function') {
+    throw new Error('This Foldkit version does not expose build metadata')
+  }
+
+  const metadata = api.getBuildMetadata()
+  console.log(metadata.serverEntry)
+  console.log(metadata.manifest.prerendered)
+}
+```
+
+`FoldkitBuildApi` preserves `serverEntry` (the configured source entry) and `fetchModuleId` (the virtual fetch module). Its `getBuildMetadata()` method returns `FoldkitBuildMetadata`, exported as a Schema and inferred type:
+
+| Field             | Meaning                                                 |
+| ----------------- | ------------------------------------------------------- |
+| `root`            | Absolute resolved application root                      |
+| `clientDirectory` | Absolute resolved client output directory               |
+| `serverDirectory` | Absolute resolved server output directory               |
+| `serverEntry`     | Absolute path to the emitted fetch handler              |
+| `manifest`        | The version-1 data also written to `foldkit.build.json` |
+
+The snapshot, manifest, and prerendered route array are frozen. The data can be serialized to another process. The manifest keeps its portable relative POSIX paths; the outer path fields describe the local build machine. Output paths reflect the resolved Vite environments, including overrides made by a host plugin.
+
+A client-only build has no `foldkit:build` plugin. A present plugin without the accessor needs a Foldkit upgrade. The accessor throws before Foldkit finalizes, while another client or server build is running, or after its build fails. Always await `builder.buildApp()` successfully: another plugin can fail after Foldkit has finalized. An environment's `writeBundle` and another plugin's post-order `buildApp` hook do not establish this completion boundary.
+
+Create a fresh Foldkit plugin set for each independent builder. The build plugin uses Vite's `sharedDuringBuild` to share captures across its environments. Concurrent builders must not reuse the same plugin object. This API does not add watch-mode support.
+
+Prerendered pages and `foldkit.build.json` are finalized after the environment bundles. A separate deployment process that consumes an existing build can continue reading the disk manifest. An integration that runs the build in a child process can read the API there and transfer the serialized metadata in its child result.
+
 ## Build id
 
 The build id does not make hydration correct. It makes hydration refuse when it would otherwise be incorrect.
@@ -73,34 +119,31 @@ Server-rendered HTML carries the deployment id, and the client bundle carries it
 
 Nothing moves, so no custom element reconnects and no frame reloads. The containment blocks native page interaction; it is not a script or global-event sandbox. A client already running in an open tab is not rechecked when a deployment lands because the comparison happens only when a client boots against a page.
 
-The plugin compiles the id into application code as `import.meta.env.FOLDKIT_BUILD_ID`, from its `buildId` option or from the `FOLDKIT_BUILD_ID` environment variable:
+When one Vite app build produces the client and server artifacts, the plugin generates an opaque id and compiles it into Foldkit in both. The entries need no build-id wiring:
 
 ```typescript
-plugins: [foldkit({ buildId: process.env.DEPLOYMENT_SHA })]
+// src/entry.server.ts
+Server.renderToString(config, { flags })
+
+// src/entry.ts
+Runtime.hydrate(application)
 ```
 
-The entries pass it explicitly, because Vite externalizes an installed dependency from a server build, where a compile-time define never reaches the framework itself:
+Use the `buildId` option or `FOLDKIT_BUILD_ID` as an explicit override when client and server build in separate jobs, or when the id should name a deployment in another system:
 
 ```typescript
-// src/entry.server.ts
-Server.renderToString(config, {
-  flags,
-  buildId: import.meta.env.FOLDKIT_BUILD_ID,
-})
-
-// src/entry.ts
-Runtime.hydrate(application, { buildId: import.meta.env.FOLDKIT_BUILD_ID })
+plugins: [foldkit({ buildId: process.env.DEPLOYMENT_ID })]
 ```
 
-Use a public value the deployment already has, such as a commit, release tag, or container digest. Three things have to be true:
+Three things have to be true:
 
 - The id appears in the HTML every visitor receives, so it must never contain a secret.
 - Two deployments must never share an id.
-- The same value must reach the client and server builds, which run as separate commands.
+- Separate build jobs must receive the same explicit override.
 
-A hydratable render given no id fails with `MissingBuildId`. Only a build takes the id from the deployment. The dev server compiles a fixed one because one live source session supplies both transforms and has no deployment identity to derive.
+A hydratable render with neither a compiled nor explicit id fails with `MissingBuildId`. The dev server generates an opaque id for its own client and server transforms.
 
-The standalone `foldkitSsr({ serverEntry, buildId })` export compiles the same define for its server entry. When it runs in development without an explicit value, it uses the fixed development id too. The aggregate `foldkit({ buildId, ssr })` plugin passes its top-level value through automatically.
+The standalone `foldkitSsr({ serverEntry, buildId })` export retains explicit build-id support for separately orchestrated integrations. The aggregate `foldkit({ ssr })` plugin owns the automatic path.
 
 ## DevTools overlay
 
@@ -110,13 +153,23 @@ To include the overlay in production, list `@foldkit/devtools` in regular `depen
 
 ## DevTools MCP relay
 
-Pass `devToolsMcpPort` to enable the relay that exposes your running Foldkit app to AI agents via the [`@foldkit/devtools-mcp`](https://www.npmjs.com/package/@foldkit/devtools-mcp) MCP server:
+During development, the plugin starts a WebSocket relay for the [`@foldkit/devtools-mcp`](https://www.npmjs.com/package/@foldkit/devtools-mcp) server. Through the relay, an AI agent can inspect a running Foldkit app and dispatch Messages.
+
+By default, the relay uses the dev server's listener at `/__foldkit/devtools-mcp`. The plugin publishes its address to a registry private to your user, and the MCP server finds it by project. You do not need to coordinate a port between them. The registry lives under `XDG_RUNTIME_DIR` when that is set, or under the operating system's temporary directory. `FOLDKIT_DEVTOOLS_RELAY_DIRECTORY` selects another directory.
+
+The relay follows Vite's `server.host` setting. If you expose the dev server with `--host`, a client still needs the random token in the published address to inspect a Model or dispatch a Message. The plugin will not publish that token into a registry directory owned by another user or readable by other users. It reports the problem in the console.
+
+In middleware mode, the relay uses a free loopback port because there is no HTTP server to share. It also uses a free loopback port for HTTPS dev servers, whose self-signed certificates the MCP server cannot verify. The plugin publishes these addresses for discovery in the same way.
+
+To use a fixed port, set `devToolsMcpPort` in your Vite config:
 
 ```typescript
 plugins: [foldkit({ devToolsMcpPort: 9988 })]
 ```
 
-When set, the plugin opens a separate WebSocket server on the given port. The MCP server connects to it and forwards typed `Request` and `Response` frames between AI agents and your Runtime. Without `devToolsMcpPort` (the default), the relay is not started and the plugin behaves exactly as before.
+Set `FOLDKIT_DEVTOOLS_MCP_PORT` to the same value for the MCP server. A fixed port opens a separate socket on every interface and does not require a token. Use this setting on platforms where directory ownership cannot be verified, including Windows, because the plugin cannot publish a relay address there.
+
+`devToolsMcpPort: false` disables the relay. The relay does not start during Vitest runs or in production builds.
 
 See the [DevTools MCP documentation](https://foldkit.dev/ai/mcp) for setup, the available tools, and how dispatch validation works.
 

package/dist/build.d.ts

@@ -9,9 +9,10 @@ export type FoldkitPrerenderOptions = Readonly<{
      */
     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.
+     * The origin used for `Request.url` while generating, such as
+     * `'https://app.example'`. This option does not set canonical or Open Graph
+     * metadata. It affects those fields only when the server entry derives them
+     * from `Request.url`, in which case it should match the published origin.
      */
     origin?: string;
     /**
@@ -42,15 +43,11 @@ export type FoldkitBuildOptions = Readonly<{
 /** Vite module id of the fetch handler Foldkit emits as the server entry. */
 export declare const FOLDKIT_FETCH_MODULE_ID = "virtual:foldkit/fetch";
 /**
- * What the build produced, written beside the server bundle for whatever
- * deploys it.
+ * What an `ssr.build` build produced, written beside the server bundle.
  *
- * 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.
+ * An SSR host serves generated paths as files and sends requests without a
+ * matching file to the server entry. A static-only SSG host serves the files
+ * and leaves other paths as misses.
  */
 export declare const FoldkitBuildManifest: Schema.Struct<{
     /**
@@ -71,28 +68,61 @@ export declare const FoldkitBuildManifest: Schema.Struct<{
     readonly serverEntry: Schema.String;
     /** Every path this build generated a page for, in the order it generated. */
     readonly prerendered: Schema.$Array<Schema.String>;
-    /**
-     * How a request-time host should run the server entry. Always `'fetch'`:
-     * the entry is a Web `fetch` handler, not a Node process.
-     */
-    readonly host: Schema.optional<Schema.Literals<readonly ["fetch"]>>;
 }>;
 /**
- * What the build produced, written beside the server bundle for whatever
- * deploys it.
+ * The decoded shape of `foldkit.build.json`.
  *
- * 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.
+ * A deployment host decodes the manifest before using it. The Schema rejects
+ * unknown versions rather than letting the host read missing fields.
  */
 export type FoldkitBuildManifest = typeof FoldkitBuildManifest.Type;
+/** Completed application build data for an in-process deployment integration. */
+export declare const FoldkitBuildMetadata: Schema.Struct<{
+    /** Absolute resolved Vite application root. */
+    readonly root: Schema.String;
+    /** Absolute resolved browser output directory. */
+    readonly clientDirectory: Schema.String;
+    /** Absolute resolved server output directory. */
+    readonly serverDirectory: Schema.String;
+    /** Absolute path to the emitted fetch handler. */
+    readonly serverEntry: Schema.String;
+    /** Portable data also written to `foldkit.build.json`. */
+    readonly manifest: Schema.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: Schema.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: Schema.String;
+        /** Where the server build was written, on the same terms as {@link client}. */
+        readonly server: Schema.String;
+        /** The server build's entry file, relative to `server`. */
+        readonly serverEntry: Schema.String;
+        /** Every path this build generated a page for, in the order it generated. */
+        readonly prerendered: Schema.$Array<Schema.String>;
+    }>;
+}>;
+/** The serializable, frozen snapshot of a completed Foldkit build. */
+export type FoldkitBuildMetadata = typeof FoldkitBuildMetadata.Type;
+/** The `foldkit:build` plugin's public integration API. */
+export type FoldkitBuildApi = Readonly<{
+    /** Configured application source entry. */
+    serverEntry: string;
+    /** Virtual module used to bundle the fetch handler. */
+    fetchModuleId: typeof FOLDKIT_FETCH_MODULE_ID;
+    /**
+     * Read after a successful `await builder.buildApp()`. Throws before Foldkit
+     * finalizes or after another client or server build starts. Later plugin failures
+     * still require callers to await the full build successfully.
+     */
+    getBuildMetadata: () => FoldkitBuildMetadata;
+}>;
 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;
@@ -102,11 +132,10 @@ export declare const renderTargetFor: (clientDirectory: string, path: string, or
  * Builds a Web `fetch` handler alongside the browser build, and generates
  * static HTML from the server entry, inside one `vite build`.
  *
- * Vite drives both environments and every host plugin composes with them, so a
- * deployment target that runs `vite build` gets the whole application rather
- * than the browser half. The generated pages take their template from the
- * browser build's own output, so generating twice over one build produces the
- * same pages. The server bundle's default export is `{ fetch }`.
+ * 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 }`.
  */
-export declare const foldkitBuild: (serverEntry: string, options?: FoldkitBuildOptions) => Plugin;
+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,EAAS,MAAM,EAAE,MAAM,QAAQ,CAAA;AAGtC,OAAO,QAA8B,MAAM,WAAW,CAAA;AAEtD,OAAO,KAAK,EAGV,MAAM,EAEP,MAAM,MAAM,CAAA;AAEb,mEAAmE;AACnE,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAA;CAC9C,CAAC,CAAA;AAEF,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,0BAA0B,CAAA;AAE9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;IAEH;;;;OAIG;;IAEH,+EAA+E;;IAE/E,2DAA2D;;IAE3D,6EAA6E;;IAE7E;;;OAGG;;EAEH,CAAA;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAcnE,eAAO,MAAM,YAAY,SACjB,MAAM,aACD,MAAM,YACR,OAAO,QAAQ,KACvB,MAQF,CAAA;AAwFD,eAAO,MAAM,eAAe,oBACT,MAAM,QACjB,MAAM,UACJ,MAAM,YACL,OAAO,QAAQ,KACvB,QAAQ,CAAC;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA0CrC,CAAA;AA4GD;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,gBACV,MAAM,YACV,mBAAmB,KAC3B,MAoOF,CAAA"}
+{"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"}

package/dist/build.js

@@ -1,19 +1,16 @@
-import { Array, Schema } from 'effect';
+import { Schema } from 'effect';
+import { randomUUID } from 'node:crypto';
 import { mkdir, 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. */
 export const FOLDKIT_FETCH_MODULE_ID = 'virtual:foldkit/fetch';
 /**
- * What the build produced, written beside the server bundle for whatever
- * deploys it.
+ * What an `ssr.build` build produced, written beside the server bundle.
  *
- * 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.
+ * An SSR host serves generated paths as files and sends requests without a
+ * matching file to the server entry. A static-only SSG host serves the files
+ * and leaves other paths as misses.
  */
 export const FoldkitBuildManifest = Schema.Struct({
     /**
@@ -34,11 +31,19 @@ export const FoldkitBuildManifest = Schema.Struct({
     serverEntry: Schema.String,
     /** Every path this build generated a page for, in the order it generated. */
     prerendered: Schema.Array(Schema.String),
-    /**
-     * How a request-time host should run the server entry. Always `'fetch'`:
-     * the entry is a Web `fetch` handler, not a Node process.
-     */
-    host: Schema.optional(Schema.Literals(['fetch'])),
+});
+/** Completed application build data for an in-process deployment integration. */
+export const FoldkitBuildMetadata = Schema.Struct({
+    /** Absolute resolved Vite application root. */
+    root: Schema.String,
+    /** Absolute resolved browser output directory. */
+    clientDirectory: Schema.String,
+    /** Absolute resolved server output directory. */
+    serverDirectory: Schema.String,
+    /** Absolute path to the emitted fetch handler. */
+    serverEntry: Schema.String,
+    /** Portable data also written to `foldkit.build.json`. */
+    manifest: FoldkitBuildManifest,
 });
 const MANIFEST_SCHEMA_VERSION = 1;
 // Relative and POSIX so the manifest describes a layout rather than this
@@ -59,6 +64,7 @@ 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';
@@ -162,26 +168,6 @@ const prerenderOptionsFrom = (prerender) => {
     }
     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;
-})();
 const fetchModuleSource = (serverEntry, template, containerId) => {
     const containerLiteral = containerId === undefined ? 'undefined' : JSON.stringify(containerId);
     // NOTE: `export *` re-exports whatever the application entry actually names,
@@ -212,7 +198,7 @@ const fetchModuleSource = (serverEntry, template, containerId) => {
 // page which cannot hydrate, from a build that reported success.
 const templateForFetchModule = (capturedTemplate) => {
     if (capturedTemplate === undefined) {
-        throw new Error('[foldkit] the browser build has not emitted index.html, so the fetch handler has no template to render into. Build the "client" environment before "ssr", and give the client an HTML entry.');
+        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.`);
     }
     return capturedTemplate;
 };
@@ -220,13 +206,14 @@ const templateForFetchModule = (capturedTemplate) => {
  * Builds a Web `fetch` handler alongside the browser build, and generates
  * static HTML from the server entry, inside one `vite build`.
  *
- * Vite drives both environments and every host plugin composes with them, so a
- * deployment target that runs `vite build` gets the whole application rather
- * than the browser half. The generated pages take their template from the
- * browser build's own output, so generating twice over one build produces the
- * same pages. The server bundle's default export is `{ fetch }`.
+ * 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 }`.
  */
 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);
@@ -235,18 +222,19 @@ export const foldkitBuild = (serverEntry, options = {}) => {
     // 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) => {
+    const generatePages = async (builder, template, clientDirectory, 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);
+        const entryUrl = pathToFileURL(entryFile);
+        entryUrl.searchParams.set('foldkit-build', randomUUID());
+        const entry = await import(entryUrl.href);
         if (typeof entry.renderPage !== 'function') {
             throw new Error(`[foldkit] "${entryFileName}" exports no renderPage function, so there is nothing to generate pages with.`);
         }
@@ -267,39 +255,12 @@ export const foldkitBuild = (serverEntry, options = {}) => {
         }
         return paths;
     };
-    const writeManifest = async (builder, serverDirectory, entryFileName, prerendered) => {
-        const manifest = Schema.encodeSync(FoldkitBuildManifest)({
-            schemaVersion: MANIFEST_SCHEMA_VERSION,
-            client: manifestPath(builder.config.root, clientOutDir),
-            server: manifestPath(builder.config.root, serverOutDir),
-            serverEntry: entryFileName,
-            prerendered,
-            host: 'fetch',
-        });
-        await writeFile(resolve(serverDirectory, MANIFEST_FILE_NAME), `${JSON.stringify(manifest, undefined, 2)}\n`);
-        builder.config.logger.info(`  wrote ${MANIFEST_FILE_NAME}`);
-    };
-    // 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, serverEntry].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);
+        metadata = undefined;
+        const client = environmentNamed(builder, 'client');
+        const server = environmentNamed(builder, 'ssr');
+        const clientDirectory = resolve(client.config.root, client.config.build.outDir);
+        const serverDirectory = resolve(server.config.root, server.config.build.outDir);
         if (state.serverEntryFile === undefined) {
             throw new Error('[foldkit] the server environment produced no entry chunk, so there is nothing to deploy or generate from.');
         }
@@ -307,20 +268,58 @@ export const foldkitBuild = (serverEntry, options = {}) => {
         // 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.');
+                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, serverDirectory, state.serverEntryFile);
-        await writeManifest(builder, serverDirectory, state.serverEntryFile, prerendered);
+        const prerendered = await generatePages(builder, template, clientDirectory, serverDirectory, state.serverEntryFile);
+        const manifest = FoldkitBuildManifest.make({
+            schemaVersion: MANIFEST_SCHEMA_VERSION,
+            client: manifestPath(builder.config.root, clientDirectory),
+            server: manifestPath(builder.config.root, serverDirectory),
+            serverEntry: state.serverEntryFile,
+            prerendered: [...prerendered],
+        });
+        await writeFile(resolve(serverDirectory, MANIFEST_FILE_NAME), `${JSON.stringify(Schema.encodeSync(FoldkitBuildManifest)(manifest), undefined, 2)}\n`);
+        builder.config.logger.info(`  wrote ${MANIFEST_FILE_NAME}`);
+        const completedMetadata = FoldkitBuildMetadata.make({
+            root: builder.config.root,
+            clientDirectory,
+            serverDirectory,
+            serverEntry: resolve(serverDirectory, state.serverEntryFile),
+            manifest,
+        });
+        Object.freeze(completedMetadata.manifest.prerendered);
+        Object.freeze(completedMetadata.manifest);
+        metadata = Object.freeze(completedMetadata);
     };
     return {
         name: 'foldkit:build',
         apply: 'build',
+        sharedDuringBuild: true,
         api: {
-            host: 'fetch',
             serverEntry,
             fetchModuleId: FOLDKIT_FETCH_MODULE_ID,
+            getBuildMetadata: () => {
+                if (metadata === undefined) {
+                    throw new Error('[foldkit] build metadata is not available. Read it after a successful builder.buildApp().');
+                }
+                return metadata;
+            },
+        },
+        buildStart: {
+            order: 'pre',
+            handler() {
+                if (this.environment.name === 'client') {
+                    delete state.template;
+                    delete state.serverEntryFile;
+                    metadata = undefined;
+                }
+                else if (this.environment.name === 'ssr') {
+                    delete state.serverEntryFile;
+                    metadata = undefined;
+                }
+            },
         },
         resolveId(id) {
             if (id === FOLDKIT_FETCH_MODULE_ID) {
@@ -332,27 +331,28 @@ export const foldkitBuild = (serverEntry, options = {}) => {
             if (id !== RESOLVED_FETCH_MODULE_ID) {
                 return;
             }
-            const state = captured(this.environment.config.root);
             const template = templateForFetchModule(state.template);
             return fetchModuleSource(serverEntry, template, containerId);
         },
-        // NOTE: `writeBundle` rather than `generateBundle`: Vite's own HTML plugin
-        // emits `index.html` from a `generateBundle` hook of its own, and hook
-        // order between plugins decides whether that asset exists yet. By
-        // `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);
+        // 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) {
+                if (this.environment.name === 'ssr') {
+                    state.serverEntryFile = serverEntryFile(Object.values(bundle), FETCH_CHUNK_NAME);
+                    return;
                 }
-                return;
-            }
-            if (this.environment.name === 'ssr') {
-                state.serverEntryFile = serverEntryFile(outputs, FETCH_CHUNK_NAME);
-            }
+                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];
+            },
         },
         config: userConfig => {
             const client = {

package/dist/buildToken.d.ts

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

package/dist/buildToken.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildToken.d.ts","sourceRoot":"","sources":["../src/buildToken.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAqClC;;;;GAIG;AACH,eAAO,MAAM,cAAc,gBAAiB,MAAM,KAAG,MAAM,GAAG,SAQ7D,CAAA;AAcD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,YACnB,OAAO,GAAG,OAAO,eACb,MAAM,KAClB,MAAM,GAAG,SAMX,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,aAAc,MAAM,KAAG,MAYnD,CAAA"}
+{"version":3,"file":"buildToken.d.ts","sourceRoot":"","sources":["../src/buildToken.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAA+B,MAAM,MAAM,CAAA;AAoC/D;;;;GAIG;AACH,eAAO,MAAM,cAAc,gBAAiB,MAAM,KAAG,MAAM,GAAG,SAQ7D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,YACnB,OAAO,GAAG,OAAO,eACb,MAAM,KAClB,MAAM,GAAG,SAMX,CAAA;AA0ID;;;GAGG;AACH,eAAO,MAAM,iBAAiB,aAClB,MAAM,wCAEf,KAAK,CAAC,MAAM,CA+Dd,CAAA"}