@foldkit/vite-plugin 0.24.0-canary.eb11872b6977 → 0.24.0-canary.ff73466cfc55

package/README.md

@@ -119,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
 

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;AAG/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,CAmPxB,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,4 +1,5 @@
 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';
@@ -231,7 +232,9 @@ export const foldkitBuild = (serverEntry, options = {}) => {
         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.`);
         }

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"}

package/dist/buildToken.js

@@ -1,38 +1,28 @@
+import MagicString from 'magic-string';
+import { randomUUID } from 'node:crypto';
+import { isFoldkitSingletonPackageSpecifier } from './foldkitPackages.js';
 // The build id names the deployment a page came from. The server stamps it on
 // the rendered root, the client carries it, and hydration refuses a page whose
 // id is not its own before it adopts any DOM.
 //
-// Per-view identities cannot answer that question. They move when the view they
-// name changes, but what a view renders also depends on the constants it
-// imports, the configuration it reads, the dependencies it calls, and the
-// arguments its caller passes. A component whose own source is untouched renders
-// something different when its caller changes, and its identity is the one that
-// wins on the element, so a stale page's `<input name="email">` can otherwise be
-// adopted for a new build's `<input name="ssn">`, carrying what a visitor typed
-// into a field that submits under a different name.
+// The aggregate plugin generates one opaque id when a Vite app build contains
+// both the client and ssr environments. The id lives on the ViteBuilder's
+// ResolvedConfig object, so concurrent builders cannot overwrite one another
+// and a later builder in the same process gets a fresh value. Separately
+// invoked builds have no shared session and must receive an explicit value.
 //
-// The id is supplied by the deployment rather than derived from the project.
-// Deriving it was tried and does not hold: a digest of the files under the Vite
-// root misses shared modules from elsewhere in a monorepo, untracked inputs, and
-// environment-derived configuration, so two deployments that render differently
-// can share an id; it moves when a build writes output the next build reads, so
-// one deployment can produce two ids; and hashing whatever files happen to sit
-// in the project turns a value published in HTML into an oracle for the secrets
-// among them. A value the deployment already has (a commit, a release tag, a
-// container digest) has none of those problems.
-//
-// This plugin only compiles the id into application code. Foldkit itself is an
-// ordinary dependency that Vite externalizes from a server build, where a
-// compile-time define never reaches it, so the id is handed to `renderToString`
-// and `Runtime.hydrate` explicitly rather than read from inside the framework.
-//
-// Development is compiled an id too. The dev SSR host renders through
-// `renderToString` like any other, and a hydratable render refuses to run
-// without one, so leaving development unnamed would fail every dev page
-// request.
+// Foldkit's own build-token module contains a placeholder call. This transform
+// replaces that call in both artifacts, which lets Runtime.hydrate and
+// renderToString consume the value without application forwarding. Installed
+// Foldkit must therefore participate in the server build; the aggregate plugin
+// configures that boundary and the post-build check refuses an artifact that
+// still imports Foldkit externally.
 const BUILD_ID_ENVIRONMENT_VARIABLE = 'FOLDKIT_BUILD_ID';
-/** The build id this build was given, from the plugin option or
- *  `FOLDKIT_BUILD_ID`, or `undefined` when the deployment supplied neither.
+const FRAMEWORK_BUILD_ID_PLACEHOLDER = 'foldkitBuildIdPlaceholder()';
+const buildIdentitySessions = new WeakMap();
+const developmentBuildIds = new WeakMap();
+/** The build id explicitly supplied through plugin configuration or the
+ *  environment, or `undefined` when neither supplied a nonempty value.
  *
  * @internal Exported for tests.
  */
@@ -45,19 +35,7 @@ export const resolveBuildId = (configured) => {
         ? fromEnvironment
         : undefined;
 };
-// The id development serves. Development is the one place a constant is right:
-// one live source session supplies both the server and client transforms rather
-// than producing independently deployable artifacts. A value that moved would
-// only make the dev server disagree with the tab already open against it. A
-// hydratable render still requires an id, so development has to be given one
-// rather than left without.
-//
-// It is exactly wrong for a build, which is why a build with no id is refused
-// rather than defaulted: two deployments sharing an id is the case the id
-// exists to catch.
-const DEVELOPMENT_BUILD_ID = 'development';
-/** The value `import.meta.env.FOLDKIT_BUILD_ID` compiles to, or `undefined`
- *  when a build was given no id and must refuse to render a hydratable page.
+/** The id a standalone plugin compiles for one Vite command.
  *
  * @internal Exported for tests.
  */
@@ -66,29 +44,140 @@ export const buildIdForCommand = (command, configured) => {
     if (resolved !== undefined) {
         return resolved;
     }
-    return command === 'serve' ? DEVELOPMENT_BUILD_ID : undefined;
+    return command === 'serve' ? 'development' : undefined;
+};
+const hasCoordinatedArtifacts = (builder) => builder.environments['client'] !== undefined &&
+    builder.environments['ssr'] !== undefined;
+const beginBuildIdentity = (builder, configuredBuildId, verifyFrameworkIdentity) => {
+    const isCoordinated = hasCoordinatedArtifacts(builder);
+    const buildId = configuredBuildId ?? (isCoordinated ? randomUUID() : undefined);
+    const session = {
+        buildId,
+        externalizedEnvironments: new Set(),
+        verifyFrameworkIdentity,
+    };
+    buildIdentitySessions.set(builder.config, session);
+    for (const environment of Object.values(builder.environments)) {
+        buildIdentitySessions.set(environment.config, session);
+        buildIdentitySessions.set(environment.getTopLevelConfig(), session);
+    }
+};
+const buildIdForConfig = (config, configuredBuildId) => {
+    if (config.command === 'build') {
+        return buildIdentitySessions.get(config)?.buildId ?? configuredBuildId;
+    }
+    const existing = developmentBuildIds.get(config);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const fresh = configuredBuildId ?? randomUUID();
+    developmentBuildIds.set(config, fresh);
+    return fresh;
+};
+const replaceAll = (source, code, search, replacement) => {
+    let didReplace = false;
+    let fromIndex = 0;
+    while (fromIndex < code.length) {
+        const index = code.indexOf(search, fromIndex);
+        if (index === -1) {
+            return didReplace;
+        }
+        source.overwrite(index, index + search.length, replacement);
+        didReplace = true;
+        fromIndex = index + search.length;
+    }
+    return didReplace;
 };
-/**
- * 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`.
+const isFoldkitBuildTokenModule = (id) => {
+    const fileName = (id.split('?', 1)[0] ?? '').replaceAll('\\', '/');
+    return (fileName.endsWith('/foldkit/src/buildToken.ts') ||
+        fileName.endsWith('/foldkit/dist/buildToken.js'));
+};
+const hasExternalFoldkitSingletonImport = (imports, dynamicImports) => [...imports, ...dynamicImports].some(isFoldkitSingletonPackageSpecifier);
+const transformBuildIdentity = (code, id, config, configuredBuildId) => {
+    if (!isFoldkitBuildTokenModule(id) ||
+        !code.includes(FRAMEWORK_BUILD_ID_PLACEHOLDER)) {
+        return undefined;
+    }
+    const buildId = buildIdForConfig(config, configuredBuildId);
+    const replacement = buildId === undefined ? 'undefined' : JSON.stringify(buildId);
+    const transformed = new MagicString(code);
+    const transformedFramework = replaceAll(transformed, code, FRAMEWORK_BUILD_ID_PLACEHOLDER, replacement);
+    if (!transformedFramework) {
+        return undefined;
+    }
+    return {
+        code: transformed.toString(),
+        map: transformed.generateMap({ hires: 'boundary', source: id }),
+    };
+};
+const verifyBuildIdentity = (builder) => {
+    const session = buildIdentitySessions.get(builder.config);
+    if (session === undefined || !session.verifyFrameworkIdentity) {
+        return;
+    }
+    const externalized = [...session.externalizedEnvironments];
+    if (externalized.length === 0) {
+        return;
+    }
+    throw new Error('[foldkit] A Foldkit singleton package was externalized from the ' +
+        `${externalized.join(' and ')} ` +
+        `${externalized.length === 1 ? 'artifact' : 'artifacts'}, so it can ` +
+        'load a framework copy whose hydration build identity was not compiled. ' +
+        'Remove Foldkit packages from explicit SSR or Rolldown externalization ' +
+        'settings and let @foldkit/vite-plugin bundle them.');
+};
+/** 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 const foldkitBuildToken = (buildId) => ({
-    name: 'foldkit:build-token',
-    config: (_config, { command }) => {
-        const resolved = buildIdForCommand(command, buildId);
-        return resolved === undefined
-            ? {}
-            : {
-                define: {
-                    'import.meta.env.FOLDKIT_BUILD_ID': JSON.stringify(resolved),
+export const foldkitBuildToken = (buildId, verifyFrameworkIdentity = true) => {
+    const configuredBuildId = resolveBuildId(buildId);
+    return [
+        {
+            name: 'foldkit:build-token',
+            enforce: 'pre',
+            sharedDuringBuild: true,
+            config: (_config, { command }) => {
+                const legacyBuildId = configuredBuildId ?? (command === 'serve' ? 'development' : undefined);
+                return legacyBuildId === undefined
+                    ? {}
+                    : {
+                        define: {
+                            'import.meta.env.FOLDKIT_BUILD_ID': JSON.stringify(legacyBuildId),
+                        },
+                    };
+            },
+            buildApp: {
+                order: 'pre',
+                async handler(builder) {
+                    beginBuildIdentity(builder, configuredBuildId, verifyFrameworkIdentity);
                 },
-            };
-    },
-});
+            },
+            transform(code, id) {
+                const config = this.environment.getTopLevelConfig();
+                return transformBuildIdentity(code, id, config, configuredBuildId);
+            },
+            generateBundle(_options, bundle) {
+                const isExternalized = Object.values(bundle).some(output => output.type === 'chunk' &&
+                    hasExternalFoldkitSingletonImport(output.imports, output.dynamicImports));
+                if (!isExternalized) {
+                    return;
+                }
+                buildIdentitySessions
+                    .get(this.environment.getTopLevelConfig())
+                    ?.externalizedEnvironments.add(this.environment.name);
+            },
+        },
+        {
+            name: 'foldkit:verify-build-token',
+            sharedDuringBuild: true,
+            buildApp: {
+                order: 'post',
+                async handler(builder) {
+                    verifyBuildIdentity(builder);
+                },
+            },
+        },
+    ];
+};

package/dist/foldkitPackages.d.ts

@@ -0,0 +1,12 @@
+/** 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.
+ *
+ * @internal
+ */
+export declare const resolveInstalledFoldkitPackages: (root: string) => Array<string>;
+//# sourceMappingURL=foldkitPackages.d.ts.map

package/dist/foldkitPackages.d.ts.map

@@ -0,0 +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"}

package/dist/foldkitPackages.js

@@ -0,0 +1,37 @@
+import { Array, Predicate } from 'effect';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+const FOLDKIT_SINGLETON_PACKAGES = [
+    'foldkit',
+    '@foldkit/ui',
+    '@foldkit/devtools',
+];
+/** Tests whether an import refers to a package that must share Foldkit's
+ * runtime instance.
+ *
+ * @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.
+ *
+ * @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');
+        }
+    });
+};

package/dist/index.d.ts

@@ -38,25 +38,21 @@ export type FoldkitPluginOptions = Readonly<{
         build?: boolean | FoldkitBuildOptions;
     }>;
     /**
-     * The deployment this build belongs to, compiled into application code as
-     * `import.meta.env.FOLDKIT_BUILD_ID` for the entries to pass to
-     * `renderToString` and `Runtime.hydrate`. Hydration compares it against the id
-     * the server stamped and refuses a page from another deployment rather than
-     * adopting it: startup stops and the page is contained, with the document's
-     * body marked `inert`.
+     * An explicit identity for the deployment this build belongs to. Foldkit
+     * normally generates an opaque identity when one Vite app build coordinates
+     * the client and server artifacts, then compiles it into the framework in
+     * both. Hydration compares that value against the id the server stamped and
+     * refuses a page from another deployment before adopting its DOM.
      *
-     * Defaults to the `FOLDKIT_BUILD_ID` environment variable. Use a value the
-     * deployment already has, such as a commit or a release tag, and give the
-     * client build and the server build the same one. It is published in the
-     * page, so it must not be a secret.
+     * Set this when the client and server are built separately, or when the id
+     * should name a deployment in another system. The `FOLDKIT_BUILD_ID`
+     * environment variable supplies the same override when this option is
+     * absent. Give every artifact the same value. It is published in the page,
+     * so it must not be a secret.
      *
-     * Whatever supplies it has to answer with the same value every time it is
-     * asked, because Vite reads a config file once per environment it builds. A
-     * config that computes a fresh value on each read — `randomUUID()`, a
-     * timestamp — gives the browser bundle and the server bundle different ids
-     * within one build, and every page of that deployment is then refused at
-     * hydration. Read it from the environment, or store a generated fallback
-     * back into the environment so later reads resolve the same id.
+     * Reusing an override across deployments makes stale pages appear current.
+     * Use a value that changes whenever the deployment's rendering inputs can
+     * change.
      */
     buildId?: string;
 }>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAEV,MAAM,EAIP,MAAM,MAAM,CAAA;AAOb,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,YAAY,CAAA;AAInE,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;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AAw8BF,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CA+FxE,CAAA"}
+{"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"}

package/dist/index.js

@@ -3,8 +3,6 @@ import { Event as DevToolsEvent, EventFrame, RELAY_RECORD_VERSION, RequestFrame,
 import { PreserveModelMessage, RequestModelMessage, RestoreModelMessage, } from 'foldkit/model-preservation';
 import { timingSafeEqual } from 'node:crypto';
 import { createServer as createHttpServer, } from 'node:http';
-import { createRequire } from 'node:module';
-import { resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
 import * as NodeCrypto from '@effect/platform-node/NodeCrypto';
 import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem';
@@ -12,6 +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 { publishRelayRecord, retireRelayRecord } from './relayRegistry.js';
 import { foldkitSsr } from './ssr.js';
 import { foldkitViewIdentity } from './viewIdentity.js';
@@ -71,37 +70,6 @@ const FORCE_INCLUDED_EFFECT_NAMESPACES = [
     'effect/SubscriptionRef',
     'effect/Types',
 ];
-// NOTE: a duplicate `foldkit` instance is its own hazard. If a bundler
-// resolves `foldkit` (or a foldkit-consuming package like `@foldkit/ui`) to
-// more than one copy, the copies get distinct Schema and tagged-message
-// identities (decode and tag matching fail across the boundary) and separate
-// module-level singleton state. `resolve.dedupe` (below) collapses every
-// installed Foldkit package to one resolved copy.
-const FOLDKIT_SINGLETON_PACKAGES = [
-    'foldkit',
-    '@foldkit/ui',
-    '@foldkit/devtools',
-];
-// NOTE: `@foldkit/ui` and `@foldkit/devtools` are optional, so dedupe only
-// the ones the consumer installed. An installed ESM package resolves to
-// ERR_PACKAGE_PATH_NOT_EXPORTED rather than succeeding, so a missing package
-// is signalled only by MODULE_NOT_FOUND.
-const resolveInstalledFoldkitPackages = (root) => {
-    // NOTE: `root` (Vite's `config.root`) can be relative at config-hook time,
-    // and createRequire requires an absolute path; `resolve` normalizes it.
-    const requireFromRoot = createRequire(resolve(root, 'noop.js'));
-    return Array.filter(FOLDKIT_SINGLETON_PACKAGES, packageName => {
-        try {
-            requireFromRoot.resolve(packageName);
-            return true;
-        }
-        catch (error) {
-            return !(error instanceof Error &&
-                Predicate.hasProperty(error, 'code') &&
-                error.code === 'MODULE_NOT_FOUND');
-        }
-    });
-};
 const Event = Data.taggedEnum();
 const makeState = Effect.gen(function* () {
     const preservedModels = yield* Ref.make(HashMap.empty());
@@ -545,13 +513,10 @@ export const foldkit = (options = {}) => {
     const reloadPlugin = {
         name: 'foldkit',
         apply: 'serve',
-        config: userConfig => ({
+        config: () => ({
             optimizeDeps: {
                 include: [...FORCE_INCLUDED_EFFECT_NAMESPACES],
             },
-            resolve: {
-                dedupe: resolveInstalledFoldkitPackages(userConfig.root ?? process.cwd()),
-            },
         }),
         configureServer: server => {
             const events = Effect.runSync(Queue.unbounded());
@@ -577,8 +542,33 @@ export const foldkit = (options = {}) => {
             return [];
         },
     };
+    const resolutionPlugin = {
+        name: 'foldkit:resolution',
+        config: userConfig => {
+            const singletonPackages = resolveInstalledFoldkitPackages(userConfig.root ?? process.cwd());
+            return {
+                optimizeDeps: {
+                    exclude: ['foldkit'],
+                },
+                resolve: {
+                    dedupe: singletonPackages,
+                },
+                ssr: {
+                    noExternal: singletonPackages,
+                },
+                environments: {
+                    ssr: {
+                        resolve: {
+                            noExternal: singletonPackages,
+                        },
+                    },
+                },
+            };
+        },
+    };
     const shared = [
-        foldkitBuildToken(options.buildId),
+        resolutionPlugin,
+        ...foldkitBuildToken(options.buildId),
         foldkitViewIdentity(),
         devToolsOverlayPlugin(),
         reloadPlugin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.24.0-canary.eb11872b6977",
+  "version": "0.24.0-canary.ff73466cfc55",
   "description": "Vite plugin for Foldkit with state-preserving live reload",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,27 +16,28 @@
     "dist"
   ],
   "peerDependencies": {
-    "effect": "4.0.0-rc.116",
-    "foldkit": "0.163.0-canary.eb11872b6977",
+    "effect": "4.0.0-rc.117",
+    "foldkit": "0.163.0-canary.ff73466cfc55",
     "vite": "^8.0.0"
   },
   "dependencies": {
-    "@effect/platform-node": "4.0.0-rc.116",
-    "magic-string": "^1.2.3",
+    "@effect/platform-node": "4.0.0-rc.117",
+    "@effect/platform-node-shared": "4.0.0-rc.117",
+    "magic-string": "^1.4.2",
     "ws": "^8.21.3"
   },
   "devDependencies": {
-    "@types/node": "^26.4.0",
+    "@types/node": "26.4.0",
     "@types/ws": "^8.18.1",
     "@vitejs/plugin-basic-ssl": "^2.3.0",
-    "effect": "4.0.0-rc.116",
-    "happy-dom": "^20.11.13",
+    "effect": "4.0.0-rc.117",
+    "happy-dom": "^20.14.5",
     "rimraf": "^6.1.3",
     "typescript": "^7.0.2",
-    "vite": "^8.2.2",
+    "vite": "^8.3.1",
     "vite-host": "npm:vite@8.2.1",
     "vitest": "^4.1.11",
-    "foldkit": "0.163.0-canary.eb11872b6977"
+    "foldkit": "0.163.0-canary.ff73466cfc55"
   },
   "keywords": [
     "vite",