@powerhousedao/builder-tools 6.2.0-dev.2 → 6.2.0-dev.21

package/dist/index.mjs

@@ -1,8 +1,9 @@
 import { createRequire } from "node:module";
-import { exec, execSync } from "node:child_process";
-import fs, { existsSync, readFileSync, realpathSync } from "node:fs";
+import { exec, execSync, spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import fs, { createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path, { dirname, join, resolve } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
-import path, { join, resolve } from "node:path";
 import { cwd } from "node:process";
 import { DEFAULT_CONNECT_CONFIG, buildRuntimeConfig, deepMerge, loadConnectEnv, normalizeBasePath, phConnectRuntimeConfigSchema, powerhousePackageSchema, setConnectEnv } from "@powerhousedao/shared/connect";
 import { getConfig } from "@powerhousedao/config/node";
@@ -10,12 +11,462 @@ import tailwind from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
 import { createLogger, esmExternalRequirePlugin, loadEnv, searchForWorkspaceRoot } from "vite";
 import { createHtmlPlugin } from "vite-plugin-html";
+import MagicString from "magic-string";
 //#region connect-utils/constants.ts
 const EXTERNAL_PACKAGES_IMPORT = "PH:EXTERNAL_PACKAGES";
 const IMPORT_SCRIPT_FILE = "external-packages.js";
 const LOCAL_PACKAGE_ID = "ph:local-package";
 const PH_DIR_NAME = ".ph";
 //#endregion
+//#region connect-utils/externalize-vendor.ts
+/**
+* Prebuild the heavy, stable Connect dependencies into a static ESM "vendor"
+* bundle so the dev server never runs (or holds) the dependency optimizer /
+* module graph for them.
+*
+* The reactor-project preview dev-optimizes a large UI graph (Connect itself,
+* design-system, document-engineering, reactor-browser, …) every session —
+* ~1–2 GB resident — even though those libs don't change; only the project's
+* editors do. This module builds them ONCE with `vite build` (in a throwaway
+* subprocess that exits, freeing the build's peak memory): `vite build` handles
+* CSS/asset imports, web workers, and WASM (Connect's in-browser PGlite ships
+* all three), and a multi-entry build with `preserveEntrySignatures: 'strict'`
+* dedupes shared code into shared chunks. Entries for CJS deps re-export the
+* module's named API explicitly (so `import { createRoot }` works); ESM deps
+* use `export *`. The build runs under `base = VENDOR_URL_PREFIX` so emitted
+* asset URLs (`new URL(…, import.meta.url)` for .wasm/.data/workers) resolve to
+* the dev middleware, not the SPA root.
+*
+* The React family stays EXTERNAL (see `VENDOR_EXTERNAL`); `esmExternalRequirePlugin`
+* owns that externalization and rewrites CJS `require("react")` → import. Vendor
+* chunks keep bare React imports, which the dev import map resolves to Vite's
+* pre-bundled React (`devReactImportmapPlugin`) — one React instance across the
+* vendor, the project's editors, and CDN-loaded editors.
+*
+* `devReactImportmapPlugin` consumes the result: it externalizes these
+* specifiers in the long-lived dev server, points the page import map at the
+* vendor URLs, and serves the bundle. With Connect vendored, the dev server only
+* processes the project's own `main` + local package; HMR for them is unaffected.
+*/
+/**
+* The stable Connect libraries worth prebuilding. The React family is NOT here —
+* it's externalized from the build (see `VENDOR_EXTERNAL`) so the vendor shares
+* the dev server's single React instance via the import map.
+*/
+const DEFAULT_VENDOR_INCLUDE = [
+	"@powerhousedao/connect",
+	"document-model",
+	"zod",
+	"@powerhousedao/design-system/connect",
+	"@powerhousedao/reactor-browser",
+	"@powerhousedao/document-engineering"
+];
+/**
+* React-family specifiers kept external to the vendor build. The vendor's chunks
+* emit bare imports for these; `devReactImportmapPlugin`'s import map resolves
+* them to Vite's pre-bundled React, so there is exactly one React instance.
+*/
+const VENDOR_EXTERNAL = [
+	"react",
+	"react-dom",
+	"react-dom/client",
+	"react/jsx-runtime",
+	"react/jsx-dev-runtime",
+	"ph-bundled-packages-virtual"
+];
+/** URL prefix the vendor bundle is served under by the dev middleware. */
+const VENDOR_URL_PREFIX = "/__vendor__/";
+/**
+* Build the prebuilt vendor (once, in a throwaway subprocess) and return its dir
+* + import map. Idempotent: reuses a cached vendor built for the same dep set.
+* Returns null on any failure (caller falls back to a normal dev server).
+*/
+async function prebuildConnectVendor(options) {
+	const include = expandIncludeSubpaths(options.dirname, options.include ?? DEFAULT_VENDOR_INCLUDE);
+	const external = options.external ?? VENDOR_EXTERNAL;
+	const vendorDir = options.vendorDir ?? join(options.dirname, "node_modules/.ph-vendor");
+	const importMapPath = join(vendorDir, "import-map.json");
+	const versionDigest = resolveVersionDigest(options.dirname, [...include, ...external]);
+	try {
+		const hit = readCacheHit(importMapPath, include, external, versionDigest);
+		if (hit) return {
+			vendorDir,
+			imports: hit
+		};
+		const lockDir = `${vendorDir}.lock`;
+		const lock = acquireLock(lockDir);
+		if (!lock) {
+			const imports = await waitForCacheHit(importMapPath, include, external, versionDigest, lockDir);
+			return imports ? {
+				vendorDir,
+				imports
+			} : null;
+		}
+		try {
+			const raced = readCacheHit(importMapPath, include, external, versionDigest);
+			if (raced) return {
+				vendorDir,
+				imports: raced
+			};
+			const imports = await buildVendorAtomic(options.dirname, vendorDir, include, external, versionDigest);
+			return imports ? {
+				vendorDir,
+				imports
+			} : null;
+		} finally {
+			releaseLock(lock);
+		}
+	} catch (err) {
+		if (options.errorRef) options.errorRef.message = err instanceof Error ? err.message : String(err);
+		return null;
+	}
+}
+function readCacheHit(importMapPath, include, external, versionDigest) {
+	if (!existsSync(importMapPath)) return null;
+	try {
+		const cached = JSON.parse(readFileSync(importMapPath, "utf8"));
+		if (sameSet(cached.include, include) && sameSet(cached.external, external) && cached.versionDigest === versionDigest) return cached.imports;
+	} catch {}
+	return null;
+}
+function resolveVersionDigest(dirname, specs) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const spec of specs) {
+		const { pkg } = parsePkg(spec);
+		if (seen.has(pkg)) continue;
+		let version = "missing";
+		try {
+			const pkgRoot = realpathSync(join(dirname, "node_modules", pkg));
+			const meta = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
+			version = String(meta.version ?? "unknown");
+		} catch {}
+		seen.set(pkg, version);
+	}
+	const h = createHash("sha256");
+	const workerHash = createHash("sha256").update(VENDOR_BUILD_WORKER).digest("hex");
+	h.update(`worker:${workerHash}\n`);
+	for (const pkg of [...seen.keys()].sort()) h.update(`${pkg}@${seen.get(pkg)}\n`);
+	return h.digest("hex").slice(0, 16);
+}
+function sameSet(a, b) {
+	if (!a || a.length !== b.length) return false;
+	const s = new Set(a);
+	return b.every((x) => s.has(x));
+}
+const LOCK_STALE_MS = 5 * 6e4;
+const LOCK_HEARTBEAT_MS = 6e4;
+const ownerFile = (lockDir) => join(lockDir, "owner");
+function lockIsStale(lockDir) {
+	try {
+		return Date.now() - statSync(ownerFile(lockDir)).mtimeMs > LOCK_STALE_MS;
+	} catch {
+		return false;
+	}
+}
+function acquireLock(lockDir) {
+	let made = false;
+	try {
+		mkdirSync(lockDir);
+		made = true;
+	} catch {
+		if (lockIsStale(lockDir)) try {
+			rmSync(lockDir, {
+				recursive: true,
+				force: true
+			});
+			mkdirSync(lockDir);
+			made = true;
+		} catch {}
+	}
+	if (!made) return null;
+	const token = `${process.pid}-${randomUUID()}`;
+	writeFileSync(ownerFile(lockDir), token);
+	const timer = setInterval(() => {
+		try {
+			if (readFileSync(ownerFile(lockDir), "utf8") === token) writeFileSync(ownerFile(lockDir), token);
+			else clearInterval(timer);
+		} catch {
+			clearInterval(timer);
+		}
+	}, LOCK_HEARTBEAT_MS);
+	timer.unref();
+	return {
+		dir: lockDir,
+		token,
+		timer
+	};
+}
+function releaseLock(lock) {
+	clearInterval(lock.timer);
+	try {
+		if (readFileSync(ownerFile(lock.dir), "utf8") === lock.token) rmSync(lock.dir, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
+}
+async function waitForCacheHit(importMapPath, include, external, versionDigest, lockDir) {
+	const deadline = Date.now() + LOCK_STALE_MS;
+	while (Date.now() < deadline) {
+		const hit = readCacheHit(importMapPath, include, external, versionDigest);
+		if (hit) return hit;
+		if (!existsSync(lockDir)) return readCacheHit(importMapPath, include, external, versionDigest);
+		await new Promise((r) => setTimeout(r, 250));
+	}
+	return null;
+}
+function importTarget(value) {
+	if (typeof value === "string") return value;
+	if (!value || typeof value !== "object") return null;
+	const o = value;
+	for (const c of [
+		"browser",
+		"import",
+		"module",
+		"default"
+	]) if (c in o) {
+		const t = importTarget(o[c]);
+		if (t) return t;
+	}
+	return null;
+}
+function parsePkg(spec) {
+	if (spec.startsWith("@")) {
+		const parts = spec.split("/");
+		return {
+			pkg: parts.slice(0, 2).join("/"),
+			sub: parts.slice(2).join("/")
+		};
+	}
+	const i = spec.indexOf("/");
+	return i === -1 ? {
+		pkg: spec,
+		sub: ""
+	} : {
+		pkg: spec.slice(0, i),
+		sub: spec.slice(i + 1)
+	};
+}
+/**
+* Connect imports the heavy libs by subpath too (e.g.
+* `@powerhousedao/design-system/connect/toast`, `zod/v4/core`). Those bare
+* imports need their own import-map entry, so expand each listed spec to its
+* package's concrete (non-wildcard, JS) subpath exports that share the spec's
+* prefix. Unresolvable / CSS / JSON targets are skipped. Failures leave the
+* original spec untouched.
+*/
+function expandIncludeSubpaths(dirname, include) {
+	const out = new Set(include);
+	for (const spec of include) {
+		const { pkg, sub } = parsePkg(spec);
+		let exp;
+		let pkgRoot;
+		try {
+			pkgRoot = realpathSync(join(dirname, "node_modules", pkg));
+			exp = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8")).exports;
+		} catch {
+			continue;
+		}
+		if (!exp || typeof exp !== "object") continue;
+		const expMap = exp;
+		const prefixKey = sub ? `./${sub}` : ".";
+		for (const key of Object.keys(expMap)) {
+			if (key.includes("*") || key === "./package.json") continue;
+			if (/\.(css|json|scss)$/.test(key)) continue;
+			if (!(prefixKey === "." ? key === "." || key.startsWith("./") : key === prefixKey || key.startsWith(`${prefixKey}/`))) continue;
+			const target = importTarget(expMap[key]);
+			if (!target || /\.(css|json|scss)$/.test(target)) continue;
+			if (!existsSync(join(pkgRoot, target))) continue;
+			out.add(key === "." ? pkg : pkg + key.slice(1));
+		}
+	}
+	return [...out];
+}
+/**
+* Build the vendor into a unique temp dir, then atomically swap it into place,
+* so a concurrent reader never sees a partial bundle or import-map.json. Runs
+* the build in a throwaway subprocess (its peak memory is reclaimed on exit);
+* the parent augments the import map with the version digest and does the swap.
+* Returns the published import map, or null on failure.
+*/
+async function buildVendorAtomic(dirname$1, vendorDir, include, external, versionDigest) {
+	const parent = dirname(vendorDir);
+	mkdirSync(parent, { recursive: true });
+	const tmpDir = mkdtempSync(join(parent, ".ph-vendor.tmp-"));
+	try {
+		const { ok, stderr } = await runBuildWorker(dirname$1, tmpDir, include, external);
+		const tmpMap = join(tmpDir, "import-map.json");
+		if (!ok || !existsSync(tmpMap)) {
+			const detail = stderr.trim();
+			throw new Error(`vendor build failed${detail ? `:\n${detail}` : " (no output captured)"}`);
+		}
+		const meta = JSON.parse(readFileSync(tmpMap, "utf8"));
+		meta.versionDigest = versionDigest;
+		writeFileSync(tmpMap, JSON.stringify(meta, null, 2));
+		const oldDir = `${vendorDir}.old-${process.pid}-${Date.now()}`;
+		if (existsSync(vendorDir)) renameSync(vendorDir, oldDir);
+		renameSync(tmpDir, vendorDir);
+		rmSync(oldDir, {
+			recursive: true,
+			force: true
+		});
+		return meta.imports;
+	} catch (err) {
+		rmSync(tmpDir, {
+			recursive: true,
+			force: true
+		});
+		throw err;
+	}
+}
+/**
+* Spawn a throwaway worker that generates one entry per specifier (CJS deps get
+* explicit named re-exports, ESM deps `export *`), `vite build`s them into the
+* given out dir, and writes the import map. Captures stdout/stderr so a failure
+* is debuggable; the normal path stays quiet.
+*/
+function runBuildWorker(dirname, outDir, include, external) {
+	const workerPath = join(outDir, "build-worker.mjs");
+	writeFileSync(workerPath, VENDOR_BUILD_WORKER);
+	return new Promise((resolve) => {
+		const child = spawn(process.execPath, [
+			workerPath,
+			dirname,
+			outDir,
+			JSON.stringify(include),
+			VENDOR_URL_PREFIX,
+			JSON.stringify(external)
+		], {
+			cwd: dirname,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stderr = "";
+		child.stdout.on("data", (d) => {
+			stderr += String(d);
+		});
+		child.stderr.on("data", (d) => {
+			stderr += String(d);
+		});
+		child.on("exit", (code) => resolve({
+			ok: code === 0,
+			stderr
+		}));
+		child.on("error", (e) => resolve({
+			ok: false,
+			stderr: String(e)
+		}));
+	});
+}
+/**
+* The vendor build worker, written to disk and run as a subprocess. Self-contained
+* (only Node + the project's `vite`). argv: dirname, vendorDir, includeJSON, urlPrefix.
+*/
+const VENDOR_BUILD_WORKER = `
+import { createRequire } from 'node:module';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const [dirname, vendorDir, includeJSON, urlPrefix, externalJSON] = process.argv.slice(2);
+const include = JSON.parse(includeJSON);
+const external = JSON.parse(externalJSON ?? '[]');
+const externalSet = new Set(external);
+const reqProj = createRequire(join(dirname, 'noop.js'));
+const { build, esmExternalRequirePlugin } = await import(reqProj.resolve('vite'));
+const srcDir = join(vendorDir, '.entries');
+mkdirSync(srcDir, { recursive: true });
+const entryName = (spec) => spec.replace(/[^\\w]+/g, '_');
+const RESERVED = new Set('enum void null function in instanceof typeof new delete do if else return switch case break continue for while this true false class const let var default export import extends super with yield debugger finally throw try catch await implements interface package private protected public static eval arguments'.split(' '));
+const input = {};
+for (const spec of include) {
+  const name = entryName(spec);
+  let src;
+  try {
+    // Import the bare spec (not reqProj.resolve(spec)) so Node picks the same
+    // import/browser-condition module the build resolves — resolving first can
+    // pick a CJS sibling whose default-export shape differs from the ESM build.
+    const ns = await import(spec);
+    // Only fall back to re-exporting from default when the module exposes NO
+    // top-level named exports (a true CJS-interop module). If it does (e.g. zod
+    // exposes \`z\`), \`export *\` captures them; destructuring default would miss
+    // top-level names that aren't keys of the default object.
+    const named = Object.keys(ns).filter((k) => k !== 'default');
+    const cjs = named.length === 0 && ns.default && typeof ns.default === 'object';
+    if (cjs) {
+      const names = Object.keys(ns.default).filter((k) => k !== 'default' && k !== '__esModule' && /^[A-Za-z_$][\\w$]*$/.test(k));
+      const plain = names.filter((n) => !RESERVED.has(n));
+      const reserved = names.filter((n) => RESERVED.has(n));
+      src = 'import d from ' + JSON.stringify(spec) + ';\\nexport default d;\\n'
+        + (plain.length ? 'export const { ' + plain.join(', ') + ' } = d;\\n' : '');
+      // reserved words are invalid as const-binding names but valid as export
+      // aliases (export { x as enum }).
+      reserved.forEach((n, i) => {
+        src += 'const __r' + i + ' = d[' + JSON.stringify(n) + '];\\nexport { __r' + i + ' as ' + n + ' };\\n';
+      });
+    } else {
+      src = 'export * from ' + JSON.stringify(spec) + ';\\n'
+        + (('default' in ns) ? 'export { default } from ' + JSON.stringify(spec) + ';\\n' : '');
+    }
+  } catch {
+    src = 'export * from ' + JSON.stringify(spec) + ';\\n';
+  }
+  const file = join(srcDir, name + '.js');
+  writeFileSync(file, src);
+  input[name] = file;
+}
+// Prefer the bundler's browser-condition-aware resolution; fall back to resolving
+// from the worker (real install path) only for Rolldown's realpath-anchoring bug.
+const phResolveCache = new Map();
+const phVendorResolve = {
+  name: 'ph-vendor-resolve', enforce: 'pre',
+  async resolveId(source, importer, options) {
+    if (externalSet.has(source)) return null;
+    if (source[0] === '\\0' || source[0] === '.' || isAbsolute(source)) return null;
+    if (source.startsWith('node:') || source.startsWith('data:')) return null;
+    let viaBundler = null;
+    try { viaBundler = await this.resolve(source, importer, { ...options, skipSelf: true }); } catch {}
+    if (viaBundler) return viaBundler;
+    if (phResolveCache.has(source)) return phResolveCache.get(source);
+    let resolved = null;
+    try { resolved = fileURLToPath(import.meta.resolve(source)); } catch {}
+    phResolveCache.set(source, resolved);
+    return resolved;
+  },
+};
+await build({
+  root: dirname, configFile: false, logLevel: 'error',
+  // Emit asset URLs (pglite .wasm/.data, workers via \`new URL(..., import.meta.url)\`)
+  // under the vendor prefix so they resolve to the middleware, not the SPA root.
+  base: urlPrefix,
+  define: { 'process.env.NODE_ENV': '"development"' },
+  // phVendorResolve runs first (pre) so bare specifiers resolve from the worker,
+  // not the importing module's realpath. esmExternalRequirePlugin then OWNS
+  // externalization of \`external\` (react family + dev virtuals): it marks them
+  // external AND rewrites CJS require("react") to import (Rolldown keeps bare
+  // require() for external ids, which fails in the browser). It must be the sole
+  // externalizer — also listing them in rollupOptions.external prevents the
+  // require() rewrite (see vite-config.ts).
+  plugins: [phVendorResolve, esmExternalRequirePlugin({ external })],
+  // pglite (and any worker dep) ships web workers; emit them as ES-module asset
+  // chunks into the vendor so the middleware can serve them.
+  worker: { format: 'es' },
+  build: {
+    outDir: vendorDir, emptyOutDir: false, minify: false, target: 'esnext', cssCodeSplit: true,
+    rollupOptions: {
+      input, preserveEntrySignatures: 'strict',
+      output: { format: 'es', entryFileNames: '[name].js', chunkFileNames: 'chunks/[name]-[hash].js', assetFileNames: 'assets/[name]-[hash][extname]' },
+    },
+  },
+});
+rmSync(srcDir, { recursive: true, force: true });
+const imports = {};
+for (const spec of include) imports[spec] = urlPrefix + entryName(spec) + '.js';
+writeFileSync(join(vendorDir, 'import-map.json'), JSON.stringify({ include, external, imports }, null, 2));
+`;
+//#endregion
 //#region connect-utils/helpers.ts
 const DEFAULT_CONNECT_OUTDIR = ".ph/connect-build/dist/";
 function resolveViteConfigPath(options) {
@@ -246,6 +697,54 @@ const runtimeConfigSchema = {
 		connect: phConnectRuntimeConfigSchema
 	}
 };
+const RESOLVED_VIRTUAL_ID = "\0virtual:ph-bundled-packages-virtual";
+const BUNDLED_PACKAGES_DEV_URL = "@id/" + RESOLVED_VIRTUAL_ID.replace("\0", "__x00__");
+function readBundledPackageVersion(projectRoot, name) {
+	try {
+		const raw = fs.readFileSync(path.join(projectRoot, "node_modules", name, "package.json"), "utf-8");
+		const pkg = JSON.parse(raw);
+		return typeof pkg.version === "string" ? pkg.version : void 0;
+	} catch {
+		return;
+	}
+}
+function makeRegisterModule(packages, projectRoot) {
+	if (packages.length === 0) return "export default () => {};\n";
+	const imports = [];
+	const calls = [];
+	packages.forEach((name, i) => {
+		const moduleName = `pkg${i}`;
+		const version = readBundledPackageVersion(projectRoot, name);
+		imports.push(`import * as ${moduleName} from ${JSON.stringify(name)};`);
+		imports.push(`import ${JSON.stringify(`${name}/style.css`)};`);
+		calls.push(`  pm.addLocalPackage(${JSON.stringify(name)}, ${moduleName}, ${JSON.stringify(version)});`);
+	});
+	return `${imports.join("\n")}\n\nexport default function register(pm) {\n${calls.join("\n")}\n};\n`;
+}
+/**
+* Emits a virtual module `ph-bundled-packages-virtual` whose default export
+* is a `register(packageManager)` function. When called at runtime (from
+* Connect's bootstrap), it registers each bundled package with the package
+* manager the same way Common/Vetra are registered — meaning they work
+* offline without the registry being reachable.
+*
+* When the list is empty, the module exports a no-op function so Connect's
+* bootstrap code can always import it unconditionally.
+*/
+function phBundledPackagesPlugin(options) {
+	const projectRoot = options.projectRoot ?? process.cwd();
+	const moduleSource = makeRegisterModule(options.packages, projectRoot);
+	return {
+		name: "vite-plugin-ph-bundled-packages",
+		enforce: "pre",
+		resolveId(id) {
+			if (id === "ph-bundled-packages-virtual") return RESOLVED_VIRTUAL_ID;
+		},
+		load(id) {
+			if (id === "\0virtual:ph-bundled-packages-virtual") return moduleSource;
+		}
+	};
+}
 //#endregion
 //#region connect-utils/vite-plugins/dev-external-react.ts
 const REACT_DEPS = [
@@ -257,9 +756,36 @@ const REACT_DEPS = [
 ];
 const SHIM_PATH = "__ph/dev-react-shim/";
 const VITE_DEPS_PATH = "node_modules/.vite/deps";
+const VENDOR_MIME = {
+	".css": "text/css",
+	".map": "application/json",
+	".json": "application/json",
+	".wasm": "application/wasm",
+	".data": "application/octet-stream",
+	".woff2": "font/woff2",
+	".woff": "font/woff",
+	".ttf": "font/ttf",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp"
+};
+const VENDOR_MODE = process.env.PH_CONNECT_EXTERNALIZE_VENDOR === "1";
+const VENDOR_EXTRA = (process.env.PH_CONNECT_VENDOR_EXTRA ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+const HEAVY_LIBS = [...DEFAULT_VENDOR_INCLUDE, ...VENDOR_EXTRA];
 function withBase(base, p) {
 	return `${base}${p}`.replace(/\/{2,}/g, "/");
 }
+function externalizePlugin(externals) {
+	try {
+		const mod = createRequire(import.meta.url)("vite-plugin-externalize-dependencies");
+		return (mod.default ?? mod)({ externals });
+	} catch {
+		return;
+	}
+}
 /**
 * Dev-only sibling of `esmExternalRequirePlugin`. The build path externalizes
 * React via Rolldown so an importmap hands the same React instance to both
@@ -268,7 +794,7 @@ function withBase(base, p) {
 * export — so a CDN editor that does `import { lazy } from "react"` would
 * fail with "no named export 'lazy'".
 *
-* This plugin:
+* This plugin owns the page import map. It always:
 *   1. Forces React into `optimizeDeps.include` so the optimizer always knows
 *      about it.
 *   2. Serves a shim per React module at a stable URL. Each shim imports
@@ -276,14 +802,46 @@ function withBase(base, p) {
 *      and re-exports React's named members so editors importing
 *      `{ lazy }`, `{ jsx }`, etc. work.
 *   3. Rewrites the page importmap to point at those shim URLs.
+*
+* When PH_CONNECT_EXTERNALIZE_VENDOR=1 it additionally prebuilds the heavy
+* stable libs (design-system, reactor-browser, …) into a static vendor bundle,
+* externalizes them from the dev server, serves the bundle, and adds them to
+* the SAME import map. The vendor's React imports stay bare → resolve through
+* the React shims above → one React instance across Connect, the vendor, and
+* CDN editors.
 */
-function devReactImportmapPlugin() {
+async function devReactImportmapPlugin(projectRoot = process.cwd()) {
 	let namedExports = /* @__PURE__ */ new Map();
 	let base = "/";
-	return {
+	let vendor = null;
+	if (VENDOR_MODE) {
+		const errorRef = {};
+		vendor = await prebuildConnectVendor({
+			dirname: projectRoot,
+			include: HEAVY_LIBS,
+			errorRef
+		});
+		if (!vendor) {
+			const detail = errorRef.message ? `: ${errorRef.message}` : "";
+			console.warn(`[connect] PH_CONNECT_EXTERNALIZE_VENDOR set but vendor prebuild failed; falling back to dep-optimizing the heavy libs${detail}`);
+		}
+	}
+	const ext = vendor ? externalizePlugin([(id) => id in vendor.imports]) : void 0;
+	if (vendor && !ext) console.warn("[connect] PH_CONNECT_EXTERNALIZE_VENDOR set and vendor prebuilt, but vite-plugin-externalize-dependencies is not installed; falling back to dep-optimizing the heavy libs (install it to enable the vendor)");
+	const vendorActive = !!(vendor && ext);
+	const main = {
 		name: "ph-dev-react-importmap",
 		apply: "serve",
-		config: () => ({ optimizeDeps: { include: REACT_DEPS } }),
+		config(cfg) {
+			cfg.optimizeDeps ??= {};
+			const include = new Set(cfg.optimizeDeps.include ?? []);
+			REACT_DEPS.forEach((d) => include.add(d));
+			if (vendorActive) {
+				HEAVY_LIBS.forEach((d) => include.delete(d));
+				cfg.optimizeDeps.exclude = [...new Set([...cfg.optimizeDeps.exclude ?? [], ...HEAVY_LIBS])];
+			}
+			cfg.optimizeDeps.include = [...include];
+		},
 		configResolved(config) {
 			base = config.base;
 		},
@@ -297,6 +855,26 @@ function devReactImportmapPlugin() {
 					return [id, []];
 				}
 			}));
+			if (vendorActive) {
+				const vendorDir = vendor.vendorDir;
+				server.middlewares.use(VENDOR_URL_PREFIX, (req, res, next) => {
+					const name = (req.url ?? "").split("?")[0].replace(/^\/+/, "");
+					const file = path.join(vendorDir, name);
+					const rel = path.relative(vendorDir, file);
+					if (!name || rel.startsWith("..") || path.isAbsolute(rel)) return next();
+					const stream = createReadStream(file);
+					stream.on("error", () => {
+						if (!res.headersSent) next();
+					});
+					stream.once("open", () => {
+						const ext = file.slice(file.lastIndexOf("."));
+						res.setHeader("Content-Type", VENDOR_MIME[ext] ?? "text/javascript");
+						const hashed = name.startsWith("chunks/") || name.startsWith("assets/");
+						res.setHeader("Cache-Control", hashed ? "public, max-age=31536000, immutable" : "no-cache");
+						stream.pipe(res);
+					});
+				});
+			}
 			const shimPrefixes = [withBase(base, SHIM_PATH), `/${SHIM_PATH}`];
 			server.middlewares.use((req, res, next) => {
 				const prefix = shimPrefixes.find((p) => req.url?.startsWith(p));
@@ -324,10 +902,103 @@ function devReactImportmapPlugin() {
 				if (!browserHash) return;
 				const shimPrefix = withBase(base, SHIM_PATH);
 				const imports = Object.fromEntries(REACT_DEPS.map((id) => [id, `${shimPrefix}${id}.js?v=${browserHash}`]));
+				if (vendorActive) {
+					Object.assign(imports, vendor.imports);
+					if (vendor.imports["@powerhousedao/connect"]) imports["ph-bundled-packages-virtual"] = withBase(base, BUNDLED_PACKAGES_DEV_URL);
+				}
 				return html.replace(/<script type="importmap">[\s\S]*?<\/script>/, `<script type="importmap">${JSON.stringify({ imports }, null, 2)}<\/script>`);
 			}
 		}
 	};
+	return vendorActive ? [ext, main] : main;
+}
+//#endregion
+//#region connect-utils/vite-plugins/dynamic-base.ts
+/**
+* Placeholder base used when Connect is built in dynamic-base mode. The Vite
+* `base` option is set to this token; this plugin rewrites it in the emitted
+* output so the effective base is resolved at serve time from a global instead
+* of being baked at build time.
+*
+* Trailing slash matches `normalizeBasePath` output, so the token sits in the
+* same syntactic position as a concrete base would.
+*/
+const DYNAMIC_BASE_PLACEHOLDER = "/__PH_DYNAMIC_BASE__/";
+/**
+* Global the runtime (ph-clint proxy) must set before the entry bundle loads.
+* Value is the normalized deploy base, e.g. "/myagent/" or "/". The JS rewrite
+* below resolves all asset / lazy-chunk / BASE_URL references against it.
+*/
+const RUNTIME_GLOBAL = "globalThis.__PH_DYNAMIC_BASE__";
+const BASE_EXPR = `(${RUNTIME_GLOBAL}||"/")`;
+/**
+* Worker scope has its own global object; the proxy injects the runtime global
+* into the main-thread `<head>` only, so a worker chunk's rewritten references
+* would fall back to "/" and fetch siblings (pglite .data/.wasm) without the
+* deploy prefix. Prepended to worker chunks, this defines the global in worker
+* scope from the worker's own script URL: the worker loads from
+* `<base>assets/<name>-<hash>.js`, so stripping `assets/<file>` off
+* `self.location.pathname` yields the same trailing-slash base the main thread
+* holds ("/myagent/" or "/").
+*/
+const WORKER_PRELUDE = `${RUNTIME_GLOBAL}=self.location.pathname.replace(/assets\\/[^/]*$/,"");\n`;
+const PLACEHOLDER_LITERAL = new RegExp(`(["'\`])${escapeForRegExp(DYNAMIC_BASE_PLACEHOLDER)}((?:(?!\\1)[^$])*)\\1`, "g");
+/**
+* Rewrites the placeholder base in emitted JS chunks to a runtime expression so
+* one built `dist/connect` serves under any subpath. Rolldown-native: per-match
+* MagicString edits in `renderChunk`, no AST splicing (the SWC byte-offset
+* splicing in vite-plugin-dynamic-base corrupts Rolldown chunks). Each edited
+* chunk returns a hires sourcemap that the bundler composes into the chunk's
+* map chain, so the emitted `.map` files track the rewrite (and the worker
+* prelude's line shift).
+*
+* What gets rewritten in JS, all of which emit the base as a quoted string
+* literal beginning with the placeholder:
+*   - asset URLs (`new URL("/__PH_DYNAMIC_BASE__/assets/x.png", ...)`)
+*   - dynamic-import / lazy-chunk preload URLs
+*   - the inlined `import.meta.env.BASE_URL` (drives Connect's router basename
+*     and BASE_URL-relative fetches such as `${BASE_URL}ph-packages.json`)
+*
+* A literal `"/__PH_DYNAMIC_BASE__/foo"` becomes `((globalThis.__PH_DYNAMIC_BASE__||"/")+"foo")`;
+* a bare `"/__PH_DYNAMIC_BASE__/"` (the BASE_URL value) becomes `(globalThis.__PH_DYNAMIC_BASE__||"/")`.
+*
+* HTML is left untouched: the entry `<script>`/`<link>` tags keep the literal
+* placeholder so the proxy substitutes it with the concrete base at serve time
+* (the same proxy also sets the runtime global for the JS rewrite). See the
+* plugin's module doc / report for the exact serve-time contract.
+*
+* CSS `url(...)` references resolve relative to the stylesheet's own URL, so
+* they need no rewrite once the stylesheet itself is loaded from the right
+* prefix (which the HTML substitution handles).
+*/
+function connectDynamicBasePlugin(options = {}) {
+	return {
+		name: "ph-connect-dynamic-base",
+		enforce: "post",
+		renderChunk(code, chunk) {
+			if (!code.includes("/__PH_DYNAMIC_BASE__/")) return null;
+			const s = new MagicString(code);
+			for (const match of code.matchAll(PLACEHOLDER_LITERAL)) {
+				const rest = match[2];
+				s.overwrite(match.index, match.index + match[0].length, rest.length === 0 ? BASE_EXPR : `(${BASE_EXPR}+${JSON.stringify(rest)})`);
+			}
+			if (options.forWorker) {
+				s.prepend(WORKER_PRELUDE);
+				this.info(`dynamic-base: worker prelude prepended to ${chunk.fileName}`);
+			}
+			if (!s.hasChanged()) return null;
+			return {
+				code: s.toString(),
+				map: s.generateMap({ hires: true })
+			};
+		},
+		generateBundle(_options, bundle) {
+			for (const file of Object.values(bundle)) if ((file.type === "chunk" ? file.code : file.fileName.endsWith(".css") && typeof file.source === "string" ? file.source : void 0)?.includes("/__PH_DYNAMIC_BASE__/")) this.error(`dynamic-base: unrewritten placeholder ${DYNAMIC_BASE_PLACEHOLDER} remains in ${file.fileName}`);
+		}
+	};
+}
+function escapeForRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //#endregion
 //#region connect-utils/vite-plugins/favicon.ts
@@ -365,56 +1036,6 @@ function connectFaviconPlugin() {
 	};
 }
 //#endregion
-//#region connect-utils/vite-plugins/ph-bundled-packages.ts
-const VIRTUAL_ID = "ph-bundled-packages-virtual";
-const RESOLVED_VIRTUAL_ID = "\0virtual:" + VIRTUAL_ID;
-function readBundledPackageVersion(projectRoot, name) {
-	try {
-		const raw = fs.readFileSync(path.join(projectRoot, "node_modules", name, "package.json"), "utf-8");
-		const pkg = JSON.parse(raw);
-		return typeof pkg.version === "string" ? pkg.version : void 0;
-	} catch {
-		return;
-	}
-}
-function makeRegisterModule(packages, projectRoot) {
-	if (packages.length === 0) return "export default () => {};\n";
-	const imports = [];
-	const calls = [];
-	packages.forEach((name, i) => {
-		const moduleName = `pkg${i}`;
-		const version = readBundledPackageVersion(projectRoot, name);
-		imports.push(`import * as ${moduleName} from ${JSON.stringify(name)};`);
-		imports.push(`import ${JSON.stringify(`${name}/style.css`)};`);
-		calls.push(`  pm.addLocalPackage(${JSON.stringify(name)}, ${moduleName}, ${JSON.stringify(version)});`);
-	});
-	return `${imports.join("\n")}\n\nexport default function register(pm) {\n${calls.join("\n")}\n};\n`;
-}
-/**
-* Emits a virtual module `ph-bundled-packages-virtual` whose default export
-* is a `register(packageManager)` function. When called at runtime (from
-* Connect's bootstrap), it registers each bundled package with the package
-* manager the same way Common/Vetra are registered — meaning they work
-* offline without the registry being reachable.
-*
-* When the list is empty, the module exports a no-op function so Connect's
-* bootstrap code can always import it unconditionally.
-*/
-function phBundledPackagesPlugin(options) {
-	const projectRoot = options.projectRoot ?? process.cwd();
-	const moduleSource = makeRegisterModule(options.packages, projectRoot);
-	return {
-		name: "vite-plugin-ph-bundled-packages",
-		enforce: "pre",
-		resolveId(id) {
-			if (id === VIRTUAL_ID) return RESOLVED_VIRTUAL_ID;
-		},
-		load(id) {
-			if (id === RESOLVED_VIRTUAL_ID) return moduleSource;
-		}
-	};
-}
-//#endregion
 //#region connect-utils/vite-plugins/ph-config.ts
 function readProjectPackageInfo(projectRoot) {
 	if (!projectRoot) return null;
@@ -670,7 +1291,7 @@ function getConnectBaseViteConfig(options) {
 	return {
 		configFile: false,
 		mode,
-		base: connectBasePath ? normalizeBasePath(connectBasePath) : void 0,
+		base: options.dynamicBase ? DYNAMIC_BASE_PLACEHOLDER : connectBasePath ? normalizeBasePath(connectBasePath) : void 0,
 		server: {
 			watch: { ignored: ["**/backup-documents/**", "**/.ph/**"] },
 			fs: { allow: [searchForWorkspaceRoot(options.dirname), ...linkedRoots] }
@@ -704,16 +1325,20 @@ function getConnectBaseViteConfig(options) {
 				packages: localPackagesFromConfig,
 				projectRoot: options.dirname
 			}),
-			devReactImportmapPlugin(),
+			devReactImportmapPlugin(options.dirname),
 			...plugins,
 			esmExternalRequirePlugin({ external: reactExternal }),
-			connectFaviconPlugin()
+			connectFaviconPlugin(),
+			...options.dynamicBase ? [connectDynamicBasePlugin()] : []
 		],
-		worker: { format: "es" },
+		worker: {
+			format: "es",
+			...options.dynamicBase ? { plugins: () => [connectDynamicBasePlugin({ forWorker: true })] } : {}
+		},
 		build: { sourcemap: true }
 	};
 }
 //#endregion
-export { DEFAULT_CONNECT_OUTDIR, EXTERNAL_PACKAGES_IMPORT, IMPORT_SCRIPT_FILE, LOCAL_PACKAGE_ID, PH_DIR_NAME, RUNTIME_CONFIG_SCHEMA_ID, RUNTIME_CONFIG_SCHEMA_URL, appendToHtmlHead, backupIndexHtml, copyConnect, ensureNodeVersion, getConnectBaseViteConfig, getConnectHtmlTags, makeImportScriptFromPackages, phConfigPlugin, prependToHtmlHead, readJsonFile, removeBase64EnvValues, resolveConnectBundle, resolveConnectPackageJson, resolveConnectPublicDir, resolvePackage, resolveViteConfigPath, runShellScriptPlugin, runTsc, runtimeConfigSchema, stripVersionFromPackage };
+export { DEFAULT_CONNECT_OUTDIR, DEFAULT_VENDOR_INCLUDE, DYNAMIC_BASE_PLACEHOLDER, EXTERNAL_PACKAGES_IMPORT, IMPORT_SCRIPT_FILE, LOCAL_PACKAGE_ID, PH_DIR_NAME, RUNTIME_CONFIG_SCHEMA_ID, RUNTIME_CONFIG_SCHEMA_URL, VENDOR_EXTERNAL, VENDOR_URL_PREFIX, appendToHtmlHead, backupIndexHtml, connectDynamicBasePlugin, copyConnect, ensureNodeVersion, getConnectBaseViteConfig, getConnectHtmlTags, makeImportScriptFromPackages, phConfigPlugin, prebuildConnectVendor, prependToHtmlHead, readJsonFile, removeBase64EnvValues, resolveConnectBundle, resolveConnectPackageJson, resolveConnectPublicDir, resolvePackage, resolveViteConfigPath, runShellScriptPlugin, runTsc, runtimeConfigSchema, stripVersionFromPackage };
 
 //# sourceMappingURL=index.mjs.map