@deepseek-ai/dsh-experimental-webworker-runtime 0.2.1-rc.5 → 0.2.2-alpha.3

package/lib/index.js

@@ -1,4 +1,6 @@
 import { parse } from "acorn";
+import { analyze } from "eslint-scope";
+import { KEYS } from "eslint-visitor-keys";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -878,9 +880,11 @@ const MODULE_PROXIES = {
 	"dns/promises": "./node/builtin_modules/mock/dns/promises.ts",
 	"node:net": "./node/builtin_modules/mock/net.ts",
 	"node:stream": "./node/builtin_modules/implemented/stream.ts",
+	"node:string_decoder": "./node/builtin_modules/implemented/string_decoder.ts",
 	"node:stream/promises": "./node/builtin_modules/implemented/stream/promises.ts",
 	"stream/promises": "./node/builtin_modules/implemented/stream/promises.ts",
 	"node:vm": "./node/builtin_modules/mock/vm.ts",
+	"node:repl": "./node/builtin_modules/mock/repl.ts",
 	"node:worker_threads": "./node/builtin_modules/mock/worker_threads.ts",
 	"node:sqlite": "./node/builtin_modules/mock/sqlite.ts",
 	"@deepseek-ai/libreoffice-kit": "./node/external_packages/libreoffice-kit.ts",
@@ -892,6 +896,7 @@ const MODULE_PROXIES = {
 	"got": "./node/external_packages/got.ts",
 	"@vscode/ripgrep": "./node/external_packages/ripgrep.ts",
 	"@earendil-works/pi-ai": "./node/external_packages/pi-ai.ts",
+	"@earendil-works/pi-coding-agent": "./node/external_packages/pi-coding-agent.ts",
 	"node-addon-require-builtin": "./node/external_packages/node-addon-require-builtin.ts",
 	"ws": "./node/external_packages/ws.ts"
 };
@@ -908,6 +913,7 @@ const MODULE_PROXY_PREFIXES = { "@earendil-works/pi-ai/": "./node/external_packa
 /** Package or subpath specifiers served from the worker bundle instead of the VFS. */
 const REPLACED_EXTERNAL_PACKAGES = [
 	"@earendil-works/pi-ai",
+	"@earendil-works/pi-coding-agent",
 	"@vscode/ripgrep",
 	"@deepseek-ai/libreoffice-kit",
 	"@deepseek-ai/node-addon-system/flock",
@@ -1052,6 +1058,14 @@ function createSyntheticExchange(frame, sink) {
 * so **line numbers survive**: a stack frame in a transformed module points at
 * the same line as the built artifact it came from.
 *
+* Named and default imports stay live: every reference reads the required
+* module object when it runs (`__dsh$m1["x"]`), never a copy taken at the
+* import statement, so a module in an import cycle sees a binding once the
+* exporting module has initialized it, as ES modules do. Scope analysis tells
+* those references apart from same-named locals that shadow them; it runs only
+* for a module that declares or assigns an import's name somewhere, because
+* elsewhere every read of the name is the import.
+*
 * The image packer is this transform's only caller: it lowers every JavaScript
 * entry it packs and records `LOWERING_VERSION` in the image manifest, so the
 * worker wraps those bodies without carrying a compiler of its own.
@@ -1059,7 +1073,7 @@ function createSyntheticExchange(frame, sink) {
 */
 const HELPER_SOURCE = {
 	def: "const __dsh$def=(t,k,get)=>Object.defineProperty(t,k,{enumerable:true,configurable:true,get});",
-	default: "const __dsh$default=(m)=>(m&&m.__esModule?m.default:m);",
+	default: "const __dsh$default=(m)=>(m&&m.__esModule&&Object.prototype.hasOwnProperty.call(m,\"default\")?m.default:m);",
 	ns: "const __dsh$ns=(m)=>(m&&m.__esModule?m:Object.assign({},m,{default:m}));",
 	exportAll: "const __dsh$exportAll=(t,m)=>{for(const k of Object.keys(m))if(k!==\"default\"&&!(k in t))__dsh$def(t,k,()=>m[k]);};",
 	dynImport: "const __dsh$dynImport=(s)=>Promise.resolve().then(()=>__dsh$ns(require(s)));"
@@ -1076,6 +1090,8 @@ function countNewlines(text) {
 	for (let index = text.indexOf("\n"); index >= 0; index = text.indexOf("\n", index + 1)) count += 1;
 	return count;
 }
+/** Prefix of the identifiers this transform emits; a module declaring one would capture them. */
+const RESERVED_PREFIX = "__dsh$";
 var Transformer = class {
 	path;
 	edits = [];
@@ -1088,6 +1104,18 @@ var Transformer = class {
 	moduleRequests = /* @__PURE__ */ new Set();
 	metaResolveRequests = /* @__PURE__ */ new Set();
 	createRequireBindings = /* @__PURE__ */ new Set();
+	/** Module temporary per import declaration with specifiers, assigned before traversal. */
+	importModules = /* @__PURE__ */ new Map();
+	/** Named and default imports by local name. */
+	importedBindings = /* @__PURE__ */ new Map();
+	/** Read-position identifiers spelling an import's name, rewritten after traversal. */
+	importCandidates = [];
+	/**
+	* Set when an import name (or the reserved prefix) is declared or assigned.
+	* Only then can a candidate be a shadowing local, so only then does scope
+	* analysis decide which candidates read the import.
+	*/
+	scopeAnalysisNeeded = false;
 	constructor(source, path) {
 		this.path = path;
 		this.source = source.startsWith("#!") ? `//${source.slice(2)}` : source;
@@ -1160,29 +1188,69 @@ var Transformer = class {
 		if (Array.isArray(node.attributes) && node.attributes.length > 0) this.fail("import attributes are not supported", node.start);
 		const source = node.source;
 		const request = `require(${this.literal(source)})`;
-		const specifiers = node.specifiers;
-		if (specifiers.length === 0) {
+		const held = this.importModules.get(node);
+		if (held === void 0) {
 			this.replace(node.start, node.end, `${request};`);
 			return;
 		}
-		const held = this.moduleTemp();
 		const lines = [`const ${held}=${request};`];
-		for (const specifier of specifiers) {
-			const local = specifier.local.name;
-			if (specifier.type === "ImportDefaultSpecifier") {
-				lines.push(`const ${local}=${this.helper("default")}(${held});`);
-				continue;
-			}
-			if (specifier.type === "ImportNamespaceSpecifier") {
-				lines.push(`const ${local}=${this.helper("ns")}(${held});`);
-				continue;
-			}
-			const imported = specifier.imported;
-			const name = imported.type === "Identifier" ? imported.name : imported.value;
-			lines.push(`const ${local}=${held}[${JSON.stringify(name)}];`);
-		}
+		for (const specifier of node.specifiers) if (specifier.type === "ImportNamespaceSpecifier") lines.push(`const ${nameOf(specifier.local)}=${this.helper("ns")}(${held});`);
 		this.replace(node.start, node.end, lines.join(""));
 	}
+	/**
+	* The expression that reads an import when the reference runs. The default
+	* form is parenthesized so it stays one operand in any position, including
+	* `new` callees and member objects.
+	*/
+	importAccess(binding) {
+		return binding.kind === "default" ? `(${this.helper("default")}(${binding.held}))` : `${binding.held}[${JSON.stringify(binding.imported)}]`;
+	}
+	/** @returns How a local export reads its binding: imports through their module object. */
+	bindingAccess(local) {
+		const imported = this.importedBindings.get(local);
+		return imported === void 0 ? local : this.importAccess(imported);
+	}
+	/**
+	* Record an identifier that spells an import's name in a read position, and
+	* flag one in a declaration or assignment position (or one using the
+	* reserved prefix there), which makes scope analysis decide the candidates.
+	* @param node - The identifier.
+	* @param parent - Its parent node.
+	* @param key - The parent property holding it.
+	* @param statementStart - Start of the enclosing expression statement when that statement sits in a statement list.
+	*/
+	identifier(node, parent, key, statementStart) {
+		if (parent === void 0 || this.importedBindings.size === 0) return;
+		const name = node.name;
+		const binding = this.importedBindings.get(name);
+		if (binding === void 0 && !name.startsWith(RESERVED_PREFIX)) return;
+		if (isBindingPosition(parent, key)) {
+			this.scopeAnalysisNeeded = true;
+			return;
+		}
+		if (binding !== void 0 && isReadPosition(parent, key)) this.importCandidates.push({
+			node,
+			parent,
+			key,
+			statementStart,
+			binding
+		});
+	}
+	/** Flag a declared or assigned name that could shadow an import or capture an emitted temporary. */
+	bindingOccurrence(name) {
+		if (this.importedBindings.size === 0) return;
+		if (this.importedBindings.has(name) || name.startsWith(RESERVED_PREFIX)) this.scopeAnalysisNeeded = true;
+	}
+	/** Rewrite one identifier that reads an import. */
+	importReference({ node, parent, key, statementStart, binding }) {
+		const access = this.importAccess(binding);
+		if (parent.type === "Property" && parent.shorthand === true) {
+			this.replace(node.start, node.end, `${nameOf(node)}:${access}`);
+			return;
+		}
+		const text = (parent.type === "CallExpression" && key === "callee" || parent.type === "TaggedTemplateExpression" && key === "tag") && binding.kind === "named" ? `(0,${access})` : access;
+		this.replace(node.start, node.end, text.startsWith("(") && node.start === statementStart ? `;${text}` : text);
+	}
 	exportNamed(node) {
 		this.moduleSyntax = true;
 		const declaration = node.declaration;
@@ -1295,16 +1363,25 @@ var Transformer = class {
 			`finally{if(!${exhausted})${ALS}.resume(await ${ALS}.pause(${ALS}.close(${iterator})))}}`
 		].join(""));
 	}
-	visit(node, context) {
+	visit(node, context, parent, key) {
 		if (node === null || typeof node !== "object") return;
 		if (Array.isArray(node)) {
-			for (const child of node) this.visit(child, context);
+			for (const child of node) this.visit(child, context, parent, key);
 			return;
 		}
 		const record = node;
 		if (typeof record.type !== "string") return;
 		let next = context;
 		switch (record.type) {
+			case "Identifier":
+				this.identifier(record, parent, key, context.statementStart);
+				break;
+			case "ObjectPattern":
+				for (const property of record.properties) {
+					const value = property.value;
+					if (value?.type === "Identifier") this.bindingOccurrence(value.name);
+				}
+				break;
 			case "ImportDeclaration":
 				this.importDeclaration(record);
 				break;
@@ -1328,6 +1405,7 @@ var Transformer = class {
 			case "CallExpression": {
 				const callee = record.callee;
 				const callArguments = record.arguments;
+				if (callee.type === "Identifier" && callee.name === "eval" && record.optional !== true && this.importedBindings.size > 0) this.fail("direct eval cannot see imports once they are read through their module", record.start);
 				if (this.isRequireCall(callee, context.moduleScope) && callArguments.length === 1 && typeof callArguments[0]?.value === "string") this.moduleRequests.add(callArguments[0].value);
 				if (callee.type === "MemberExpression") {
 					const object = callee.object;
@@ -1388,11 +1466,12 @@ var Transformer = class {
 		}
 		if (record.type === "ExpressionStatement") next = {
 			...next,
-			statement: record
+			statement: record,
+			statementStart: inStatementList(parent, key) ? record.start : void 0
 		};
-		for (const [key, value] of Object.entries(record)) {
-			if (key === "type" || key === "start" || key === "end") continue;
-			this.visit(value, next);
+		for (const [childKey, value] of Object.entries(record)) {
+			if (childKey === "type" || childKey === "start" || childKey === "end") continue;
+			this.visit(value, next, record, childKey);
 		}
 	}
 	isCreateRequireCall(node) {
@@ -1415,10 +1494,73 @@ var Transformer = class {
 			const source = statement.source;
 			if (source.value !== "node:module" && source.value !== "module") continue;
 			for (const specifier of statement.specifiers) {
-				if (specifier.type !== "ImportSpecifier" || nameOf(specifier.imported) !== "createRequire") continue;
-				this.createRequireBindings.add(nameOf(specifier.local));
+				if (specifier.type !== "ImportSpecifier" || specifierName(specifier.imported) !== "createRequire") continue;
+				this.createRequireBindings.add(specifier.local.name);
+			}
+		}
+	}
+	/**
+	* Give every import declaration its module temporary and record its named and
+	* default bindings before traversal, because references may precede the
+	* declaration in source order.
+	*/
+	indexImports(program) {
+		for (const statement of program.body) {
+			if (statement.type !== "ImportDeclaration" || statement.specifiers.length === 0) continue;
+			const held = this.moduleTemp();
+			this.importModules.set(statement, held);
+			for (const specifier of statement.specifiers) if (specifier.type === "ImportDefaultSpecifier") this.importedBindings.set(specifier.local.name, {
+				held,
+				kind: "default",
+				imported: "default"
+			});
+			else if (specifier.type === "ImportSpecifier") this.importedBindings.set(specifier.local.name, {
+				held,
+				kind: "named",
+				imported: specifierName(specifier.imported)
+			});
+		}
+	}
+	/**
+	* Decide with scope analysis which candidates read an import.
+	*
+	* Refuses an assignment to an import, which live reads cannot express, and a
+	* declaration using the reserved prefix, which would capture an emitted
+	* module temporary. Direct `eval` is refused during traversal.
+	* @param program - The parsed module, which gains node ranges here.
+	* @returns The identifier nodes that read a named or default import.
+	*/
+	resolveImportReads(program) {
+		assignRanges(program);
+		const manager = analyze(program, {
+			ecmaVersion: 2022,
+			sourceType: "module",
+			childVisitorKeys: KEYS
+		});
+		for (const scope of manager.scopes) for (const variable of scope.variables) {
+			const definition = variable.defs[0];
+			if (definition === void 0 || !variable.name.startsWith(RESERVED_PREFIX)) continue;
+			this.fail(`${variable.name} uses the transform's reserved ${RESERVED_PREFIX} prefix`, this.rangeStart(definition.name));
+		}
+		const reads = /* @__PURE__ */ new Set();
+		const moduleScope = manager.scopes.find((scope) => scope.type === "module");
+		for (const variable of moduleScope?.variables ?? []) {
+			if (!this.importedBindings.has(variable.name) || variable.defs[0]?.type !== "ImportBinding") continue;
+			for (const reference of variable.references) {
+				if (reference.isWrite()) this.fail(`the import ${variable.name} cannot be assigned`, this.rangeStart(reference.identifier));
+				reads.add(reference.identifier);
 			}
 		}
+		return reads;
+	}
+	/**
+	* @param node - A node scope analysis reports.
+	* @returns Its source offset; `assignRanges` gave every node a range.
+	*/
+	rangeStart(node) {
+		const start = node.range?.[0];
+		if (start === void 0) this.fail("scope analysis reported a node without a source range", 0);
+		return start;
 	}
 	run() {
 		if (this.source.includes(`${ALS}.pause(`) || this.source.includes("__als$")) this.fail("the module is already lowered; check the image manifest wiring", 0);
@@ -1433,17 +1575,21 @@ var Transformer = class {
 			this.fail(`parse failed: ${reason.message}`, 0);
 		}
 		this.indexCreateRequireImports(program);
+		this.indexImports(program);
 		this.visit(program, {
 			asyncGenerator: false,
 			functionDepth: 0,
 			moduleScope: true
 		});
+		const reads = this.scopeAnalysisNeeded ? this.resolveImportReads(program) : void 0;
+		for (const candidate of this.importCandidates) if (reads === void 0 || reads.has(candidate.node)) this.importReference(candidate);
 		if (this.edits.length === 0 && !this.moduleSyntax) return this.source;
 		const prologue = [];
 		if (this.moduleSyntax) prologue.push("\"use strict\";Object.defineProperty(exports,\"__esModule\",{value:true});");
+		const getters = this.bindings.map(({ exported, local }) => `__dsh$def(exports,${JSON.stringify(exported)},()=>${this.bindingAccess(local)});`);
 		if (this.bindings.length > 0) this.helper("def");
 		for (const [name, source] of Object.entries(HELPER_SOURCE)) if (this.helpers.has(name)) prologue.push(source);
-		for (const { exported, local } of this.bindings) prologue.push(`__dsh$def(exports,${JSON.stringify(exported)},()=>${local});`);
+		prologue.push(...getters);
 		const sorted = [...this.edits].sort((left, right) => left.start - right.start || left.end - right.end);
 		const render = (from, to) => {
 			let cursor = from;
@@ -1472,6 +1618,96 @@ var Transformer = class {
 function nameOf(node) {
 	return node.type === "Identifier" ? node.name : String(node.value);
 }
+/** @returns The name an import or export specifier spells, as an identifier or a string literal. */
+function specifierName(node) {
+	return node.type === "Identifier" ? node.name : String(node.value);
+}
+/**
+* Give every node the `range` that eslint-scope reads. The parse leaves ranges
+* out because only modules that need scope analysis use them.
+* @param node - A node or node array of the parsed module.
+*/
+function assignRanges(node) {
+	if (node === null || typeof node !== "object") return;
+	if (Array.isArray(node)) {
+		for (const child of node) assignRanges(child);
+		return;
+	}
+	const record = node;
+	if (typeof record.type !== "string") return;
+	record.range = [record.start, record.end];
+	for (const value of Object.values(record)) assignRanges(value);
+}
+/**
+* ESTree positions where an identifier names a declared or assigned binding.
+* Property values inside an object pattern are checked at the pattern.
+*
+* Together with the ObjectPattern check, this must recognize every ESTree
+* declaration and assignment form: a missed form lets a shadowing local skip
+* scope analysis and be rewritten as an import read. A parser upgrade that adds
+* a binding form must extend this list and the shadowing cases in
+* `transform-imports.spec.ts`.
+* @param parent - Parent of the identifier.
+* @param key - The parent property holding it.
+* @returns Whether the identifier declares or assigns a binding.
+*/
+function isBindingPosition(parent, key) {
+	switch (parent.type) {
+		case "VariableDeclarator": return key === "id";
+		case "FunctionDeclaration":
+		case "FunctionExpression":
+		case "ArrowFunctionExpression": return key === "id" || key === "params";
+		case "ClassDeclaration":
+		case "ClassExpression": return key === "id";
+		case "CatchClause": return key === "param";
+		case "ArrayPattern":
+		case "RestElement":
+		case "UpdateExpression": return true;
+		case "AssignmentPattern":
+		case "AssignmentExpression":
+		case "ForInStatement":
+		case "ForOfStatement": return key === "left";
+		default: return false;
+	}
+}
+/**
+* ESTree positions where an identifier, outside a binding position, reads a
+* binding rather than naming a property, label, specifier, or meta property.
+* Positions not listed read a binding, so the binding positions must be ruled
+* out first (`isBindingPosition`).
+* @param parent - Parent of the identifier.
+* @param key - The parent property holding it.
+* @returns Whether the identifier reads a binding.
+*/
+function isReadPosition(parent, key) {
+	switch (parent.type) {
+		case "MemberExpression": return key !== "property" || parent.computed === true;
+		case "Property":
+		case "MethodDefinition":
+		case "PropertyDefinition": return key !== "key" || parent.computed === true;
+		case "LabeledStatement":
+		case "BreakStatement":
+		case "ContinueStatement":
+		case "ImportSpecifier":
+		case "ImportDefaultSpecifier":
+		case "ImportNamespaceSpecifier":
+		case "ExportSpecifier":
+		case "ExportAllDeclaration":
+		case "MetaProperty": return false;
+		default: return true;
+	}
+}
+/**
+* @param parent - Parent of a statement.
+* @param key - The parent property holding it.
+* @returns Whether the statement sits in a statement list, where it can follow
+* a statement that ends without a semicolon.
+*/
+function inStatementList(parent, key) {
+	if (parent === void 0) return false;
+	if (parent.type === "SwitchCase") return key === "consequent";
+	return key === "body" && (parent.type === "Program" || parent.type === "BlockStatement" || parent.type === "StaticBlock");
+}
 /** Every binding an exported declaration introduces, including patterns. */
 function declaredBindings(declaration, fail) {
 	if (declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") {
@@ -1564,6 +1800,8 @@ function lowerModuleSource(options) {
 *
 * - `GET /__boot__` answers from tunnel glue, never from the host API surface,
 *   because the page needs the boot payload before its Cordis tree exists.
+*   `GET /__assets__` answers the same way with every package asset of the
+*   image, which the page maps before any Client bundle runs.
 * - Privileged `/api` methods take that same direct entry. The method set is not
 *   restated here: a 401 or 403 from the route lane is retried on the direct
 *   lane because the page owns the worker and needs no network authentication.
@@ -1965,6 +2203,10 @@ var TunnelServer = class {
 				this.serveBoot(frame, sink);
 				return;
 			}
+			if (path === "/__assets__") {
+				this.servePackageAssets(frame, sink);
+				return;
+			}
 			if (path.startsWith(`/api/`)) {
 				await this.serveApi(frame, routed, path, sink);
 				return;
@@ -2030,6 +2272,24 @@ var TunnelServer = class {
 		}
 		buffered.flushTo(sink);
 	}
+	servePackageAssets(frame, sink) {
+		if (this.seams === void 0) throw new Error("webworker tunnel: package assets requested before the host tree is serving");
+		if (frame.method !== "GET") {
+			sink.end({
+				status: 405,
+				headers: { allow: "GET" }
+			});
+			return;
+		}
+		sink.end({
+			status: 200,
+			headers: {
+				"content-type": "application/x-tar",
+				"cache-control": "no-store"
+			},
+			body: this.seams.packageAssets()
+		});
+	}
 	serveBoot(frame, sink) {
 		if (this.seams === void 0) throw new Error("webworker tunnel: boot payload requested before the host tree is serving");
 		if (frame.method !== "GET") {
@@ -2144,7 +2404,7 @@ const EXEC_PATH = "/dsh/bin/node";
 /** Node release whose internal-module members `node-addon-require-builtin` follows in the Worker. */
 const NODE_VERSION = "24.18.0";
 /**
-* Publish `globalThis.process`.
+* Publish `globalThis.process` and Node's `global` alias for the worker lifetime.
 *
 * `versions.node` names the Node release the Worker's `node-addon-require-builtin` internals follow, so Cordis's
 * `ModuleLoader.fromInternal()` reaches them the way it reaches Node's; `execArgv` stays empty, without
@@ -2213,6 +2473,7 @@ function installProcessGlobal(options) {
 			console.warn(`webworker process: exit(${String(code ?? 0)}) requested; the worker keeps running`);
 		}
 	};
+	globalThis.global = globalThis;
 	globalThis.process = shim;
 	return shim;
 }
@@ -3597,6 +3858,50 @@ function requireActiveVfs() {
 	return active;
 }
 //#endregion
+//#region src/package-assets.ts
+/**
+* Package assets for the preview page. A Client bundle names each image as a
+* document-relative reference, `plugins/<package>/assets/<path>`, and resolves
+* it through the module loader's synchronous `require.asset`. The page of the
+* Worker preview cannot request such a URL itself, so the Worker hands it every
+* asset the image holds in one archive and the page maps each reference to a
+* Blob URL before any bundle runs.
+* @module @deepseek-ai/dsh-experimental-webworker-runtime/src/package-assets
+*/
+/** Entries of one directory. */
+function entriesOf(vfs, directory) {
+	return vfs.readdirSync(directory, { withFileTypes: true });
+}
+/** Files under one directory, as `/`-separated paths relative to it. */
+function filesBelow(vfs, directory, prefix = "") {
+	return entriesOf(vfs, directory).flatMap((entry) => entry.isDirectory() ? filesBelow(vfs, join(directory, entry.name), `${prefix}${entry.name}/`) : entry.isFile() ? [`${prefix}${entry.name}`] : []);
+}
+/** Installed package directories under `node_modules`, scoped ones included. */
+function packageDirectories(vfs, modules) {
+	if (!vfs.existsSync(modules)) return [];
+	return entriesOf(vfs, modules).filter((entry) => entry.isDirectory()).flatMap((entry) => entry.name.startsWith("@") ? entriesOf(vfs, join(modules, entry.name)).filter((scoped) => scoped.isDirectory()).map((scoped) => join(modules, entry.name, scoped.name)) : [join(modules, entry.name)]);
+}
+/**
+* Archive every file a package of the image publishes through `"./assets/*": "./lib/assets/*"`.
+* @param vfs - Mounted image filesystem.
+* @param root - Image root holding `node_modules`.
+* @returns An uncompressed tar whose entries are named `plugins/<package>/assets/<path>` with the path unencoded,
+* so every name fits the ustar limits the base image already met.
+*/
+function packPackageAssets(vfs, root) {
+	const files = {};
+	for (const directory of packageDirectories(vfs, join(root, "node_modules"))) {
+		const manifestPath = join(directory, "package.json");
+		if (!vfs.existsSync(manifestPath)) continue;
+		const manifest = JSON.parse(vfs.readFileSync(manifestPath, "utf8"));
+		if (typeof manifest.name !== "string" || manifest.exports?.["./assets/*"] !== "./lib/assets/*") continue;
+		const assets = join(directory, "lib", "assets");
+		if (!vfs.existsSync(assets)) continue;
+		for (const path of filesBelow(vfs, assets)) files[`plugins/${manifest.name}/assets/${path}`] = vfs.readFileSync(join(assets, path));
+	}
+	return packTar(files);
+}
+//#endregion
 //#region src/image-manifest.ts
 /**
 * The base image's manifest: what the packer records about one image and what
@@ -3769,7 +4074,8 @@ function createWorkerHost(options) {
 			const peer = connection.browserPeer;
 			tunnel.serve({
 				directFetch: (request) => handler.fetch(request, peer),
-				bootPayload: () => readBootPayload(ctx),
+				bootPayload: () => readBootPayload(ctx, peer),
+				packageAssets: () => packPackageAssets(mounted, root),
 				openStream: (endpoint, payload, uplink, signal) => typertGateway.wireStream.open(endpoint, payload, uplink, peer, signal),
 				streamFailure: typertGateway.wireStream.failure
 			});
@@ -3911,12 +4217,13 @@ function prepareProfile(appBoot, vfs, manifest, root, env) {
 * from the in-process webserver service, never from the API surface, because
 * the page has no Cordis tree yet.
 * @param ctx - Booted host context.
+* @param peer - the browser Peer the page speaks for.
 * @returns Boot payload for `GET /__boot__`.
 */
-function readBootPayload(ctx) {
+function readBootPayload(ctx, peer) {
 	const webServer = ctx.get("webServer");
 	if (webServer === void 0) throw new Error("webworker host: no webServer service, so the page cannot receive its boot injections");
-	return { injections: webServer.collectIndexInjections() };
+	return { injections: webServer.collectIndexInjections(peer) };
 }
 //#endregion
 //#region src/fixture-manifest.ts

package/lib/types/client/client.d.ts

@@ -72,6 +72,11 @@ export declare class WorkerTunnel {
      * @returns The payload the page applies before the client tree loads.
      */
     bootPayload(): Promise<BootPayload>;
+    /**
+     * Read every package asset of the image and map each reference to a Blob URL.
+     * @returns The synchronous resolver the module system calls for `require.asset`.
+     */
+    packageAssets(): Promise<(reference: string) => string>;
     /**
      * `loadBundle` seam: take one client bundle through the tunnel and execute it
      * as a classic script, exactly like the shell's same-origin `<script src>`.

package/lib/types/node/builtin_modules/implemented/async_hooks.d.ts

@@ -51,7 +51,7 @@ export declare class AsyncLocalStorage<T> {
     /**
      * Copy every live instance's current store. Not part of the Node face: this is
      * the shim's own mechanism, kept in the class so the overlay stays private.
-     * @returns the snapshot, or undefined when no instance has a store.
+     * @returns the snapshot, or undefined when no instance has a store or explicit context.
      */
     static captureContext(): AsyncContextSnapshot | undefined;
     /**
@@ -90,8 +90,8 @@ export type AsyncContextSnapshot = readonly CapturedStore[];
 export type AmbientSnapshot = readonly CapturedStore[];
 /**
  * Copy every live instance's current store.
- * @returns the snapshot, or undefined when no instance has a store (the hook
- * layer then wraps nothing and callbacks inherit the stack top).
+ * @returns the snapshot, or undefined when no instance has a store or explicit
+ * context (the hook layer then wraps nothing and callbacks inherit the stack top).
  */
 export declare function captureAsyncContext(): AsyncContextSnapshot | undefined;
 /**

package/lib/types/node/builtin_modules/implemented/buffer.d.ts

@@ -2,6 +2,13 @@
  * `node:buffer` for the worker, backed by the `buffer` npm package (feross), and
  * the matching `globalThis.Buffer` install. Node code treats Buffer as ambient,
  * so the global must exist before any host module evaluates.
+ *
+ * Loading this module replaces `Buffer.from`, `Buffer.prototype.toString`, and
+ * `toLocaleString` on the package's class, so every Buffer user in the Worker,
+ * including bundled third-party code, gets the same conversions. Whole-buffer
+ * UTF-8 conversions use `TextEncoder` and `TextDecoder` with Node's U+FFFD
+ * replacement and BOM retention; other encodings and ranged `toString` calls
+ * keep the package's implementation.
  */
 import { Buffer, kMaxLength } from 'buffer';
 export { Buffer, kMaxLength };

package/lib/types/node/builtin_modules/implemented/string_decoder.d.ts

@@ -0,0 +1,12 @@
+/** Node string decoding backed by the maintained npm implementation used by readable-stream. */
+import '../../../string-decoder-types.ts';
+import { StringDecoder } from 'string_decoder/';
+export { StringDecoder };
+/** CommonJS interop marker consumed by the worker module loader. */
+export declare const __esModule = true;
+/** CommonJS-compatible namespace for default imports. */
+declare const _default: {
+    StringDecoder: typeof StringDecoder;
+};
+export default _default;
+//# sourceMappingURL=string_decoder.d.ts.map

package/lib/types/node/builtin_modules/mock/repl.d.ts

@@ -0,0 +1,10 @@
+/** REPL construction is unavailable in the browser worker. */
+export declare const start: typeof import('node:repl').start;
+/** CommonJS interop marker consumed by the Worker module loader. */
+export declare const __esModule = true;
+/** CommonJS export for the REPL member used by the Node PTC evaluator. */
+declare const _default: {
+    start: typeof import("repl").start;
+};
+export default _default;
+//# sourceMappingURL=repl.d.ts.map