@vibesdotdev/applets 0.0.0-stage → 1.0.0-rc.3

package/dist/cli/commands/serve.command.impl.js

@@ -0,0 +1,1105 @@
+/**
+ * `vibes applet serve` implementation — ONE local web server for every applet.
+ *
+ * Single-origin by design: one local port (applets config `serveHostname` /
+ * `servePort`, default 127.0.0.1:5190) serves an index at `/`, each
+ * applet host page at `/applet/{id}/`, compiled entries, transpiled project
+ * sources, the handed file set, and every module the applet reaches. A
+ * second invocation probes the health endpoint first and REUSES a running
+ * server instead of multiplying ports. Wire bodies are schema-validated
+ * (serve.schemas.ts) — schema-first, not stringly-typed.
+ *
+ * Module serving mirrors the filesystem: a resolved file is served at
+ * `/@fs/<absolute path>`, so relative imports inside any package resolve in
+ * the browser exactly as they do on disk. Bare specifiers are resolved with
+ * the module system (exports maps and conditions), never by regex on the
+ * package name; `.svelte` compiles and `.ts` transpiles at request time.
+ *
+ * Runtime-first: the workspace root resolves through the runtime, and every
+ * response is served from disk at request time — new or edited applet
+ * projects appear without restarting the server.
+ */
+import { createCLIActionLifetime } from '@vibesdotdev/cli/providers';
+import { writeStdoutLine } from '@vibesdotdev/cli/output';
+import * as z from 'zod/v4';
+import { requireRuntimeCwd, CaughtFailureSchema, isCapabilityError, CapabilityError } from '@vibesdotdev/kernel';
+import { APPLET_SERVE_HOST_KIND } from '@vibesdotdev/kernel/kinds/applet-serve-host.kind';
+import { getLogger } from '@vibesdotdev/logging';
+import { statChecked } from '@vibesdotdev/filesystem';
+import { getRuntimePath } from '@vibesdotdev/paths';
+import { APPLET_SVELTE_RUNTIME_PROP, mediaTypeFor, readAppletLocalProject, resolveAppletCompanion } from '@vibesdotdev/applets';
+import { appletProjectsDir, digestContents, listAppletProjectIds, readAppletProjectEntries, resolveAppletProjectHost, resolveAppletWorkspaceRoot } from "../project-files.js";
+import { serveHealthSchema, servedAppletSchema, servedAppletFilesSchema } from "./serve.schemas.js";
+import { collectServedStyleContents, compileServedStylesheet, prepareServedSvelte } from "./serve-stylesheet.js";
+import { answerServedAppletSurface } from "./serve-surface.js";
+import { createServedAppletRpc } from "./served-applet-rpc.js";
+import { compile, compileModule } from 'svelte/compiler';
+import { loadAppletsConfig } from "../../config/load.js";
+const HEALTH_PATH = '/__vibes/applets/serve/health';
+const FS_PREFIX = '/@fs';
+const JSON_HEADERS = { 'content-type': 'application/json', 'cache-control': 'no-store' };
+const JS_HEADERS = { 'content-type': 'text/javascript', 'cache-control': 'no-store' };
+const CSS_HEADERS = { 'content-type': 'text/css', 'cache-control': 'no-store' };
+const HTML_HEADERS = { 'content-type': 'text/html', 'cache-control': 'no-store' };
+/** Both separators to one, so URL paths and containment checks are host-independent. */
+function toPosix(path) {
+    return path.replaceAll('\\', '/');
+}
+/** The host-canonical path, or null when nothing is there. Existence is asked
+ *  through the checked-stat outcome, not caught from a refusal, so only a
+ *  confirmed absence answers null and every other failure surfaces. This is
+ *  the HOST's own view: installed packages and this package's own sources
+ *  routinely live outside the served workspace, which the workspace view
+ *  refuses. Project content never uses this one. */
+/** The nearest directory at or above `file` that holds a package.json, or null. */
+async function packageRootOf(host, file) {
+    let dir = host.paths.dirname(file);
+    while (true) {
+        const manifest = await statChecked(host.hostFiles, host.paths.join(dir, 'package.json'));
+        if (manifest.found && manifest.stat.kind !== 'directory')
+            return dir;
+        const parent = host.paths.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+async function realpathOrNullHost(host, path) {
+    const checked = await statChecked(host.hostFiles, path);
+    if (!checked.found)
+        return null;
+    return (await host.hostFiles.realpath?.(path)) ?? path;
+}
+/** A host answer as text: an unencoded read is bytes; a text read passes through. */
+function textOf(contents) {
+    return contents instanceof Uint8Array ? new TextDecoder().decode(contents) : contents;
+}
+/** A host read as a `Response` body: text passes through; bytes copy into an ArrayBuffer-backed view. */
+function asBody(contents) {
+    if (!(contents instanceof Uint8Array))
+        return contents;
+    const copy = new Uint8Array(contents.length);
+    copy.set(contents);
+    return copy;
+}
+/** A file's bytes, or null when the path is absent or is not a regular file. */
+async function readFileOrNull(host, path) {
+    const checked = await statChecked(host.files, path);
+    if (!checked.found || checked.stat.kind !== 'file')
+        return null;
+    return host.files.readFile(path);
+}
+/** `readFileOrNull` through the HOST's own view, for installed-package bytes.
+ *  Project companions stay on the workspace view (`readFileOrNull`). */
+async function readFileOrNullHost(host, path) {
+    const checked = await statChecked(host.hostFiles, path);
+    if (!checked.found || checked.stat.kind !== 'file')
+        return null;
+    return host.hostFiles.readFile(path);
+}
+/**
+ * Whether a `--root` is absolute without asking the path kind first: POSIX
+ * `/x`, or a Windows drive/UNC root. The capture-free order matters — a
+ * RELATIVE root must fail closed on a host with no captured cwd before any
+ * other kind is consulted.
+ */
+function looksAbsolute(root) {
+    return root.startsWith('/') || root.startsWith('\\\\') || /^[A-Za-z]:[\\/]/.test(root);
+}
+/**
+ * An explicit `--root` wins (a managed process names its workspace; a relative
+ * one resolves against where the command ran). Otherwise the runtime's bound
+ * workspace answers, so an unbound host fails `workspace-unbound` before any
+ * filesystem kind is asked for.
+ */
+async function resolveRootOption(runtime, root) {
+    const cwd = looksAbsolute(root) ? undefined : requireRuntimeCwd(runtime);
+    const paths = await getRuntimePath(runtime);
+    return cwd === undefined ? paths.resolve(root) : paths.resolve(cwd, root);
+}
+/** Modules a plain page cannot resolve, answered with the browser truth:
+ *  `esm-env` selects its build by export condition, and the kit's `/svelte`
+ *  barrel carries a few SvelteKit-bound components that import the `$app`
+ *  and `$env` virtuals. Outside SvelteKit those are inert stand-ins. */
+const shimSpecifierSchema = z.enum(['esm-env', '$app/state', '$app/navigation', '$env/dynamic/public', '$env/dynamic/private']);
+const SHIMS = {
+    'esm-env': 'export const BROWSER = true;\nexport const DEV = true;\nexport const NODE = false;\n',
+    '$app/state': [
+        'export const page = { url: new URL(location.href), params: {}, route: { id: null }, status: 200, error: null, data: {}, form: null, state: {} };',
+        'export const navigating = { from: null, to: null, type: null, willUnload: false, delta: null, complete: Promise.resolve() };',
+        'export const updated = { current: false, check: async () => false };'
+    ].join('\n') + '\n',
+    '$app/navigation': [
+        'export const goto = async (url) => { location.href = String(url); };',
+        'export const invalidate = async () => {}; export const invalidateAll = async () => {};',
+        'export const preloadData = async () => ({ type: "loaded", status: 200, data: {} }); export const preloadCode = async () => {};',
+        'export const beforeNavigate = () => {}; export const afterNavigate = () => {}; export const onNavigate = () => {};',
+        'export const pushState = () => {}; export const replaceState = () => {}; export const disableScrollHandling = () => {};'
+    ].join('\n') + '\n',
+    '$env/dynamic/public': 'export const env = {};\n',
+    '$env/dynamic/private': 'export const env = {};\n'
+};
+const SHIM_PREFIX = '/@shim/';
+/**
+ * A stylesheet a module imports (`import 'pkg/style.css'`, `import './x.css'`): the page cannot load
+ * CSS as a module, so the import is rewritten to this prefix plus the sheet's own URL, which answers a
+ * module that adds the sheet once as a `<link>`.
+ */
+const CSS_MODULE_PREFIX = '/@css-module';
+/** A `?raw` import (Vite's convention, kept in built packages): the file's text as a module's default export. */
+const RAW_MODULE_PREFIX = '/@raw-module';
+/** A `?worker` import (Vite's convention, kept in built packages): a `Worker` constructor for the resolved module. */
+const WORKER_MODULE_PREFIX = '/@worker-module';
+function cssModule(sheetUrl) {
+    const href = JSON.stringify(sheetUrl);
+    return `if (!document.querySelector(\`link[data-applet-css=\${JSON.stringify(${href})}]\`)) {\n\tconst link = document.createElement('link');\n\tlink.rel = 'stylesheet';\n\tlink.href = ${href};\n\tlink.dataset.appletCss = ${href};\n\tdocument.head.appendChild(link);\n}\nexport {};\n`;
+}
+function workerModule(workerUrl) {
+    const href = JSON.stringify(workerUrl);
+    return `export default class ServedModuleWorker extends Worker {\n\tconstructor(options) {\n\t\tsuper(${href}, { type: 'module', name: options?.name, credentials: options?.credentials });\n\t}\n}\n`;
+}
+function shimUrl(specifier) {
+    return SHIM_PREFIX + encodeURIComponent(specifier) + '.js';
+}
+/** Export conditions a plain browser page satisfies, most specific first. */
+const BROWSER_CONDITIONS = ['browser', 'svelte', 'import', 'module', 'default'];
+const STYLESHEET_CONDITIONS = ['style', ...BROWSER_CONDITIONS];
+const exportEntrySchema = z.union([
+    z.string(),
+    z.array(z.lazy(() => exportEntrySchema)),
+    z.record(z.string(), z.lazy(() => exportEntrySchema).optional())
+]);
+const exportsMapSchema = z.record(z.string(), exportEntrySchema);
+const packageJsonSchema = z.looseObject({
+    exports: z.unknown().optional(),
+    module: z.string().optional(),
+    browser: z.unknown().optional(),
+    main: z.string().optional()
+});
+function isExportString(entry) {
+    return typeof entry === 'string';
+}
+/**
+ * Walk an exports map entry to its relative files for the given conditions,
+ * most preferred first. A published package can name a condition target it
+ * does not ship (Kit's `style` points at `src/`, which only `dist/` publishes),
+ * so the caller takes the first candidate that exists rather than the first
+ * condition that matches.
+ */
+function exportCandidates(entry, conditions = BROWSER_CONDITIONS) {
+    if (entry === undefined)
+        return [];
+    if (isExportString(entry))
+        return [entry];
+    if (Array.isArray(entry))
+        return entry.flatMap((item) => exportCandidates(item, conditions));
+    return conditions.flatMap((condition) => (condition in entry ? exportCandidates(entry[condition], conditions) : []));
+}
+function splitSpecifier(specifier) {
+    const parts = specifier.split('/');
+    const name = specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+    const subpath = specifier.slice(name.length); // '' or '/x/y'
+    return { name, subpath };
+}
+async function findPackageRoot(host, name, fromDir) {
+    let dir = fromDir;
+    while (true) {
+        const candidate = host.paths.join(dir, 'node_modules', name);
+        // `node_modules/<name>` is host-owned and routinely sits outside the
+        // workspace, so this walk reads the host's own filesystem, not the
+        // workspace-rooted view, which would refuse the whole subtree.
+        if (await host.hostFiles.exists(host.paths.join(candidate, 'package.json')))
+            return candidate;
+        const parent = host.paths.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+const PackageNameSchema = z.looseObject({ name: z.string().optional() });
+/**
+ * The package a directory sits in, when that package is `name` (a package importing its own name,
+ * as Node resolves a self-reference): the served kit checkout imports `@vibesdotdev/kit/...` with
+ * no `node_modules` link to itself, and must still resolve through its own exports map.
+ */
+async function selfPackageRoot(host, name, fromDir) {
+    let dir = fromDir;
+    while (true) {
+        const manifest = host.paths.join(dir, 'package.json');
+        if (await host.hostFiles.exists(manifest)) {
+            const parsed = PackageNameSchema.safeParse(JSON.parse(textOf(await host.hostFiles.readFile(manifest, 'utf8'))));
+            return parsed.success && parsed.data.name === name ? dir : null;
+        }
+        const parent = host.paths.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Resolve a bare specifier for a browser: the package's exports map under
+ * browser conditions first (so `svelte` yields the client build, not the
+ * server one), then the module system's own answer as the fallback.
+ */
+async function resolveForBrowser(host, specifier, fromDir, fallback, conditions = BROWSER_CONDITIONS) {
+    const { name, subpath } = splitSpecifier(specifier);
+    const root = (await findPackageRoot(host, name, fromDir)) ?? (await selfPackageRoot(host, name, fromDir));
+    if (root) {
+        // `findPackageRoot` saw this package.json; a read or parse failure is a
+        // broken install and surfaces rather than resolving as if it had no exports.
+        const pkg = packageJsonSchema.parse(JSON.parse(textOf(await host.hostFiles.readFile(host.paths.join(root, 'package.json'), 'utf8'))));
+        const parsedMap = exportsMapSchema.safeParse(pkg.exports);
+        if (parsedMap.success) {
+            const map = parsedMap.data;
+            const key = '.' + subpath;
+            const candidates = exportCandidates(map[key], conditions);
+            if (candidates.length === 0) {
+                // One-level `*` patterns, e.g. "./components/*": "./dist/components/*"
+                for (const [pattern, target] of Object.entries(map)) {
+                    const star = pattern.indexOf('*');
+                    if (star < 0)
+                        continue;
+                    const head = pattern.slice(0, star), tail = pattern.slice(star + 1);
+                    if (key.startsWith(head) && key.endsWith(tail) && key.length >= head.length + tail.length) {
+                        const filled = key.slice(head.length, key.length - tail.length);
+                        const picked = exportCandidates(target, conditions);
+                        if (picked.length > 0) {
+                            candidates.push(...picked.map((rel) => rel.replace('*', filled)));
+                            break;
+                        }
+                    }
+                }
+            }
+            for (const rel of candidates) {
+                const abs = host.paths.resolve(root, rel);
+                if (await host.hostFiles.exists(abs))
+                    return (await realpathOrNullHost(host, abs)) ?? abs;
+            }
+        }
+        else if (!subpath) {
+            const rel = z.string().safeParse(pkg.browser).data ?? pkg.module ?? pkg.main;
+            if (rel) {
+                const abs = host.paths.resolve(root, rel);
+                if (await host.hostFiles.exists(abs))
+                    return (await realpathOrNullHost(host, abs)) ?? abs;
+            }
+        }
+    }
+    const fallen = fallback(specifier, fromDir);
+    if (!fallen)
+        return null;
+    // Real paths only: a symlinked package must resolve its own dependencies
+    // from where it actually lives, not from where it was linked.
+    if (!(await host.hostFiles.exists(fallen)))
+        return fallen;
+    return (await realpathOrNullHost(host, fallen)) ?? fallen;
+}
+/** A relative specifier a browser cannot follow (no extension, or a
+ *  directory) is pinned to the file it means on disk. */
+async function completeRelative(host, specifier, fromDir) {
+    const abs = host.paths.resolve(fromDir, specifier);
+    const exact = await statChecked(host.hostFiles, abs);
+    if (host.paths.extname(abs) && exact.found && exact.stat.kind !== 'directory')
+        return null; // already exact
+    // TypeScript sources import their siblings by the `.js` name they compile to (`./utils.js` for utils.ts).
+    if (abs.endsWith('.js') && !exact.found) {
+        const typed = await statChecked(host.hostFiles, abs.replace(/\.js$/, '.ts'));
+        if (typed.found && typed.stat.kind !== 'directory')
+            return specifier.replace(/\.js$/, '.ts');
+    }
+    const candidates = [
+        abs + '.js',
+        abs + '.ts',
+        abs + '.svelte',
+        host.paths.join(abs, 'index.js'),
+        host.paths.join(abs, 'index.ts')
+    ];
+    for (const candidate of candidates) {
+        const checked = await statChecked(host.hostFiles, candidate);
+        if (checked.found && checked.stat.kind !== 'directory') {
+            const rel = specifier.endsWith('/') ? specifier.slice(0, -1) : specifier;
+            return rel + toPosix(candidate.slice(abs.length));
+        }
+    }
+    return null;
+}
+function toFsUrl(absolutePath) {
+    return FS_PREFIX + absolutePath.split(/[\\/]/).map(encodeURIComponent).join('/');
+}
+function fromFsUrl(host, path) {
+    if (!path.startsWith(FS_PREFIX + '/'))
+        return null;
+    return host.paths.resolve(path.slice(FS_PREFIX.length).split('/').map(decodeURIComponent).join('/'));
+}
+function isRelative(specifier) {
+    return specifier.startsWith('./') || specifier.startsWith('../') || specifier.startsWith('/');
+}
+function replaceSpecifier(code, specifier, target) {
+    return code.split(`'${specifier}'`).join(`'${target}'`).split(`"${specifier}"`).join(`"${target}"`);
+}
+/**
+ * The URL one resolved companion is served at.
+ *
+ * Compiled modules get a `.js` suffix on their SOURCE path (so `x.svelte` is
+ * `x.svelte.js`, a rune `x.svelte.ts` is `x.svelte.ts.js`, a rune `x.svelte.js`
+ * is `x.svelte.js.js`), which keeps every source unambiguous under one route
+ * table. TypeScript is compiled to `x.js`, the convention the route already had.
+ * Everything else — css, md, images — is served at its own path as bytes.
+ */
+function companionTarget(projectId, path) {
+    if (path.endsWith('.svelte.ts') || path.endsWith('.svelte.js') || path.endsWith('.svelte')) {
+        return `/applet/${projectId}/${path}.js`;
+    }
+    if (path.endsWith('.ts'))
+        return `/applet/${projectId}/${path.slice(0, -3)}.js`;
+    return `/applet/${projectId}/${path}`;
+}
+/** Rewrite every specifier in a served module to a URL this server answers. */
+export async function rewriteModule(code, ctx) {
+    for (const specifier of ctx.tools.scan(code)) {
+        let target = null;
+        if (specifier.endsWith('?raw') && isRelative(specifier) && !ctx.project) {
+            // A vendor module's raw text import: the file beside it, served as a string module.
+            code = replaceSpecifier(code, specifier, RAW_MODULE_PREFIX + toFsUrl(ctx.host.paths.resolve(ctx.fromDirs[0], specifier.slice(0, -'?raw'.length))));
+            continue;
+        }
+        if (specifier.endsWith('?worker') && !ctx.project) {
+            // A vendor module's web-worker constructor import: resolve the underlying worker script and wrap it.
+            const bare = specifier.slice(0, -'?worker'.length);
+            let workerTarget = null;
+            if (isRelative(bare)) {
+                const completed = (await completeRelative(ctx.host, bare, ctx.fromDirs[0])) ?? bare;
+                workerTarget = toFsUrl(ctx.host.paths.resolve(ctx.fromDirs[0], completed));
+            }
+            else {
+                for (const dir of ctx.fromDirs) {
+                    const abs = await resolveForBrowser(ctx.host, bare, dir, ctx.tools.resolve);
+                    if (abs) {
+                        await ctx.admitResolved?.(abs);
+                        workerTarget = toFsUrl(abs);
+                        break;
+                    }
+                }
+            }
+            if (workerTarget) {
+                code = replaceSpecifier(code, specifier, WORKER_MODULE_PREFIX + workerTarget);
+                continue;
+            }
+        }
+        if (isRelative(specifier)) {
+            if (ctx.project) {
+                // A2b: companions resolve RELATIVE to the importing file, through the
+                // same pure resolver every host uses — extensionless names complete,
+                // nested `../` paths work, and binary media is served as bytes.
+                const resolved = resolveAppletCompanion({
+                    importer: ctx.project.importer,
+                    specifier,
+                    files: ctx.project.files
+                });
+                if (!resolved.ok)
+                    continue;
+                target = companionTarget(ctx.project.id, resolved.path);
+            }
+            else {
+                // Vendor modules: the URL mirrors the disk, so relative imports
+                // resolve as they do on disk — once they name an actual file.
+                target = await completeRelative(ctx.host, specifier, ctx.fromDirs[0]);
+                if (!target)
+                    continue;
+            }
+        }
+        else if (shimSpecifierSchema.safeParse(specifier).success) {
+            target = shimUrl(specifier);
+        }
+        else if (specifier === '@vibesdotdev/applets/messages') {
+            target = '/applets/messages.js';
+        }
+        else {
+            for (const dir of ctx.fromDirs) {
+                const abs = await resolveForBrowser(ctx.host, specifier, dir, ctx.tools.resolve);
+                if (abs) {
+                    await ctx.admitResolved?.(abs);
+                    target = toFsUrl(abs);
+                    break;
+                }
+            }
+            if (!target)
+                continue; // leave it; the browser reports the unresolved specifier by name
+        }
+        // A stylesheet import becomes the module that links it.
+        if (target.endsWith('.css'))
+            target = CSS_MODULE_PREFIX + target;
+        code = replaceSpecifier(code, specifier, target);
+    }
+    // The selected local host resolves browser build constants with its native compiler.
+    return ctx.tools.transpile(code);
+}
+function indexHostPage() {
+    return `<!doctype html>
+<html><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/>
+<title>Local applets</title>
+<link rel="stylesheet" href="/kit/styles.css"/>
+<style>html,body{margin:0;height:100%;background:#0d1117;color:#e6edf3}</style>
+</head><body><div id="app"></div>
+<script type="module">
+	const health = await fetch('/__vibes/applets/serve/health').then(r => r.json());
+	const { mount } = await import('/serve/index.js');
+	mount(document.getElementById('app'), { applets: health.applets });
+</script>
+</body></html>`;
+}
+/**
+ * One applet's page. The applet mounts with its root surface as the `vibes`
+ * prop (the delivery contract in `browser-runtime.ts`); it used to mount with
+ * empty props, so a local applet had no runtime surface at all.
+ */
+export function hostPage(id, surfaceClientUrl) {
+    return `<!doctype html>
+<html><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/>
+<title>Applet — ${id}</title>
+<link rel="stylesheet" href="/kit/styles.css?project=${id}"/><style>html,body{margin:0;height:100%;background:#0d1117}#app{height:100vh}</style>
+</head><body><div id="runtime-status" role="status"></div><button id="runtime-reconnect" type="button" hidden>Reconnect runtime</button><p id="runtime-failure" role="alert" hidden></p><p id="runtime-cleanup-failure" role="alert" hidden></p><div id="app"></div>
+<script type="module">
+	const status = document.getElementById('runtime-status');
+	const retry = document.getElementById('runtime-reconnect');
+	const failure = document.getElementById('runtime-failure');
+	const cleanupFailure = document.getElementById('runtime-cleanup-failure');
+	let connection;
+	let mounted;
+	let pending;
+	let releasing;
+	let disposed = false;
+	function report(error, target = failure) {
+		const message = error instanceof Error ? error.message : String(error);
+		const detail = target === cleanupFailure ? 'Previous runtime connection cleanup: ' + message : message;
+		target.textContent = [target.textContent, detail].filter(Boolean).join('\\n');
+		target.hidden = false;
+	}
+	function release() {
+		if (releasing) return releasing;
+		const previousMount = mounted;
+		const previousConnection = connection;
+		mounted = undefined;
+		connection = undefined;
+		releasing = Promise.allSettled([
+			(async () => { if (previousMount !== undefined) await unmount(previousMount); })(),
+			(async () => { await previousConnection?.close(); })()
+		]).then(results => {
+			for (const result of results) if (result.status === 'rejected') report(result.reason, cleanupFailure);
+		}).finally(() => { releasing = undefined; });
+		return releasing;
+	}
+	async function connect() {
+		if (pending || disposed) return pending;
+		pending = Promise.resolve().then(async () => {
+			retry.disabled = true;
+			failure.hidden = true;
+			failure.textContent = '';
+			status.textContent = 'Connecting to the runtime.';
+			await release();
+			if (disposed) return;
+			const opened = await openServedApplet({ projectId: '${id}', origin: location.origin, fetch: (url, init) => fetch(url, init) });
+			if (disposed) { await opened.close(); return; }
+			connection = opened;
+			const props = readAppletLocation(AppletPresentationSchema.parse({ id: '${id}', title: '${id}' }), undefined, new URL(location.href));
+			mounted = mount(document.getElementById('app'), { ...props, ${APPLET_SVELTE_RUNTIME_PROP}: opened.surface });
+			status.textContent = '';
+			retry.hidden = true;
+			void opened.closed.then(() => {
+				if (connection !== opened || disposed) return;
+				const released = release();
+				status.textContent = 'Runtime connection closed. Reconnect to read the recorded work.';
+				retry.hidden = false;
+				return released;
+			}).catch(error => report(error, cleanupFailure));
+			window.dispatchEvent(new MessageEvent('message', { data: { type: 'files', files: files.files } }));
+		}).catch(async error => {
+			await release();
+			report(error);
+			status.textContent = 'Runtime connection unavailable.';
+			retry.hidden = false;
+		}).finally(() => { retry.disabled = false; pending = undefined; });
+		return pending;
+	}
+	window.addEventListener('pagehide', () => {
+		disposed = true;
+		void (async () => { await pending; await release(); })().catch(report);
+	}, { once: true });
+	const files = await fetch('/applet/${id}/files').then(r => r.json());
+	const { openServedApplet, readAppletLocation, AppletPresentationSchema } = await import('${surfaceClientUrl}');
+	const { mount, unmount } = await import('/applet/${id}/applet.js');
+	retry.addEventListener('click', connect);
+	await connect();
+</script>
+</body></html>`;
+}
+/** Svelte compiles a component to `export default function <Name>()`. Hosts
+ *  need mount(element, props); expose Svelte's mount under that shape. */
+function withMountAdapter(code, svelteUrl) {
+    const defaultExport = /export default function ([A-Za-z_$][\w$]*)/.exec(code);
+    if (!defaultExport)
+        return code;
+    return (code +
+        `\nimport { mount as __svelte_mount, unmount as __svelte_unmount } from '${svelteUrl}';\n` +
+        'export function mount(target, props = {}) {\n' +
+        `\treturn __svelte_mount(${defaultExport[1]}, { target, props });\n` +
+        '}\n' +
+        'export function unmount(instance) { return __svelte_unmount(instance); }\n');
+}
+/** Load one project from disk and compile its entry for the browser. */
+export async function loadProject(workspaceRoot, id, ctx, svelteUrl) {
+    let entries;
+    const projectRead = await (async () => {
+        try {
+            return { ok: true, entries: await readAppletProjectEntries(workspaceRoot, id, ctx.host) };
+        }
+        catch (error) {
+            return { ok: false, error };
+        }
+    })();
+    if (!projectRead.ok) {
+        // No such project: 404 at the route layer. An unreadable one surfaces,
+        // and so does a failure no schema can read — the original, never a
+        // parse error about it.
+        const parsed = CaughtFailureSchema.safeParse(projectRead.error);
+        const failure = parsed.success ? parsed.data : null;
+        if (failure && isCapabilityError(failure) && failure.reason === 'applet-project-not-found')
+            return null;
+        throw projectRead.error;
+    }
+    entries = projectRead.entries;
+    const result = await readAppletLocalProject({ id, entries, digest: digestContents });
+    if (!result.ok)
+        return null;
+    const project = result.project;
+    const files = project.files.map((file) => file.path);
+    const filename = ctx.host.paths.join(appletProjectsDir(workspaceRoot, ctx.host), id, project.entry);
+    const prepared = await prepareServedSvelte(project.sources[project.entry], {
+        path: filename, base: ctx.host.paths.dirname(filename)
+    }, ctx.tools.compileStyle);
+    const compiled = compile(prepared, {
+        filename: project.entry,
+        generate: 'client',
+        css: 'injected'
+    });
+    const code = withMountAdapter(await rewriteModule(compiled.js.code, {
+        ...ctx,
+        project: { id, sources: project.sources, files, importer: project.entry }
+    }), svelteUrl);
+    return { id, entry: project.entry, sources: project.sources, files, compiledEntry: code };
+}
+/**
+ * One companion route for one loaded project — the body of the applet-scoped
+ * module and asset routes.
+ *
+ * A2b: companions resolve relative to the importing file. Compiled modules are
+ * addressed by their SOURCE path plus a `.js` suffix, so `x.svelte`, rune
+ * `x.svelte.ts` and rune `x.svelte.js` never collide under one route table.
+ * Everything else — css, md, svg, images — is served as BYTES with its declared
+ * media type. Returns null when no branch matches; the caller answers 404.
+ *
+ * Exported so a test can drive the REAL route pipeline without a socket.
+ */
+export async function serveAppletCompanion(input) {
+    const { workspaceRoot, id, project, rest, tools, host, resolveDirs, admitResolved } = input;
+    const projectCtx = (importer) => ({
+        tools,
+        host,
+        fromDirs: resolveDirs,
+        admitResolved,
+        project: { id, sources: project.sources, files: project.files, importer }
+    });
+    if (rest.endsWith('.svelte.ts.js')) {
+        // A rune module written in TypeScript: transpile, then the module compiler.
+        const source = rest.slice(0, -3);
+        if (source in project.sources) {
+            const js = tools.transpile(project.sources[source]);
+            const compiled = compileModule(js, { filename: source, generate: 'client' });
+            return new Response(await rewriteModule(compiled.js.code, projectCtx(source)), { headers: JS_HEADERS });
+        }
+    }
+    else if (rest.endsWith('.svelte.js.js')) {
+        // A rune module already in JavaScript.
+        const source = rest.slice(0, -3);
+        if (source in project.sources) {
+            const compiled = compileModule(project.sources[source], { filename: source, generate: 'client' });
+            return new Response(await rewriteModule(compiled.js.code, projectCtx(source)), { headers: JS_HEADERS });
+        }
+    }
+    else if (rest.endsWith('.svelte.js')) {
+        // A companion component of the project, compiled for the browser.
+        const svelteFile = rest.slice(0, -3);
+        if (svelteFile in project.sources) {
+            const filename = host.paths.join(appletProjectsDir(workspaceRoot, host), id, svelteFile);
+            const prepared = await prepareServedSvelte(project.sources[svelteFile], {
+                path: filename, base: host.paths.dirname(filename)
+            }, tools.compileStyle);
+            const compiled = compile(prepared, {
+                filename: svelteFile,
+                generate: 'client',
+                css: 'injected'
+            });
+            return new Response(await rewriteModule(compiled.js.code, projectCtx(svelteFile)), { headers: JS_HEADERS });
+        }
+    }
+    else if (rest.endsWith('.js')) {
+        // A project TypeScript source, transpiled for the browser; else a project
+        // JavaScript source served through the same rewriter.
+        const srcPath = rest.replace(/\.js$/, '.ts');
+        if (srcPath in project.sources) {
+            return new Response(await rewriteModule(tools.transpile(project.sources[srcPath]), projectCtx(srcPath)), {
+                headers: JS_HEADERS
+            });
+        }
+        if (rest in project.sources) {
+            return new Response(await rewriteModule(project.sources[rest], projectCtx(rest)), { headers: JS_HEADERS });
+        }
+    }
+    else {
+        // A companion of any other type — css, md, svg, images: served as BYTES
+        // with its declared media type, straight from the project.
+        const mediaType = mediaTypeFor(rest);
+        if (mediaType !== undefined && project.files.includes(rest)) {
+            const full = host.paths.join(appletProjectsDir(workspaceRoot, host), id, ...rest.split('/'));
+            // A file removed since the listing is a confirmed absence (404); any other read failure is rethrown.
+            const read = await readFileOrNull(host, full);
+            if (read === null)
+                return new Response('Not found', { status: 404 });
+            return new Response(asBody(read), {
+                headers: { 'content-type': mediaType, 'cache-control': 'no-store' }
+            });
+        }
+    }
+    return null;
+}
+/**
+ * A package's installed root, walked through the HOST's own filesystem and
+ * path kinds — never `require.resolve`, whose answer belongs to whichever
+ * context (a compiled bundle, a linked checkout) happened to call it.
+ */
+async function resolvePackageRoot(host, roots, name) {
+    for (const dir of roots) {
+        const found = await findPackageRoot(host, name, dir);
+        if (found)
+            return (await realpathOrNullHost(host, found)) ?? found;
+    }
+    throw new CapabilityError(`Package "${name}" is not installed in this workspace.`, 'UNAVAILABLE', {
+        reason: 'applet-package-unavailable',
+        details: { package: name },
+        retryable: false
+    });
+}
+/**
+ * Everything `run` must resolve before it can listen: the kit, the svelte
+ * runtime, the optional animation sheet, and this package's own served
+ * sources. Exported so a test can drive the REAL startup resolution without
+ * a socket.
+ */
+export async function resolveServePackageRoots(input) {
+    const { host, runtime, tools, workspaceRoot, packageDir, packageSourcePath, surfaceClientPath } = input;
+    // The kit the workspace links (its source checkout, when present) wins over
+    // the copy pinned by this package: local serve exists to iterate on what
+    // is being built, and the pinned copy is the fallback for a plain install.
+    const kitPath = (await findPackageRoot(host, '@vibesdotdev/kit', workspaceRoot)) ??
+        (await resolvePackageRoot(host, [workspaceRoot, packageDir], '@vibesdotdev/kit'));
+    const kitRoot = (await realpathOrNullHost(host, kitPath)) ?? kitPath;
+    const resolveDirs = [kitRoot, packageDir, workspaceRoot];
+    const svelteEntry = await resolveForBrowser(host, 'svelte', kitRoot, tools.resolve);
+    if (!svelteEntry)
+        throw new CapabilityError('Svelte runtime not found in the workspace node_modules.', 'UNAVAILABLE', {
+            reason: 'applet-package-unavailable',
+            details: { package: 'svelte' },
+            retryable: false
+        });
+    const svelteUrl = toFsUrl(svelteEntry);
+    // The kit owns where its stylesheet builds to; its exports map names it.
+    const kitStylesheet = await resolveForBrowser(host, '@vibesdotdev/kit/styles.css', kitRoot, tools.resolve, STYLESHEET_CONDITIONS);
+    // Optional: without it the kit sheet drops the import. Absence is asked, not
+    // caught — findPackageRoot answers null when the package is not installed,
+    // so the one default below rests on a declared fact, not a swallowed refusal.
+    const twAnimatePath = (await findPackageRoot(host, 'tw-animate-css', workspaceRoot)) ??
+        (await findPackageRoot(host, 'tw-animate-css', packageDir));
+    const twAnimateRoot = twAnimatePath === null ? null : ((await realpathOrNullHost(host, twAnimatePath)) ?? twAnimatePath);
+    if (twAnimateRoot === null) {
+        getLogger('applets:serve', runtime).debug('optional package not installed; the kit sheet drops the import', {
+            package: 'tw-animate-css'
+        });
+    }
+    const packageSourceDir = (await realpathOrNullHost(host, packageSourcePath)) ?? packageSourcePath;
+    const surfaceClientUrl = toFsUrl((await realpathOrNullHost(host, surfaceClientPath)) ?? surfaceClientPath);
+    return { kitRoot, kitStylesheet, resolveDirs, svelteEntry, svelteUrl, twAnimateRoot, packageSourceDir, surfaceClientUrl };
+}
+export async function run(runtime, id, options = {}) {
+    const workspaceRoot = options.root
+        ? await resolveRootOption(runtime, options.root)
+        : await resolveAppletWorkspaceRoot(runtime);
+    const host = await resolveAppletProjectHost(runtime);
+    const appletsSettings = await loadAppletsConfig(runtime);
+    const hostname = appletsSettings.serveHostname;
+    const port = options.port ?? appletsSettings.servePort;
+    const base = `http://${hostname}:${port}`;
+    // Reuse probe: if our server already runs here, attach instead of multiply.
+    // Only an unreachable port means "not running"; a server that answers our
+    // health path with another shape is reported by the schema parse.
+    let probe = null;
+    const probeOutcome = await (async () => {
+        try {
+            return { ok: true, response: await fetch(base + HEALTH_PATH, { signal: AbortSignal.timeout(1500) }) };
+        }
+        catch (error) {
+            return { ok: false, error };
+        }
+    })();
+    if (probeOutcome.ok) {
+        probe = probeOutcome.response;
+    }
+    else {
+        // Refused or silent: nothing serves here yet. Any other failure surfaces.
+        const probeError = z.object({ code: z.string().optional(), name: z.string().optional() }).safeParse(probeOutcome.error);
+        const failure = probeError.success ? probeError.data : {};
+        if (failure.code !== 'ConnectionRefused' &&
+            failure.code !== 'ECONNREFUSED' &&
+            failure.name !== 'TimeoutError') {
+            throw probeOutcome.error;
+        }
+        getLogger('applets:serve', runtime).debug('no server on this port yet; starting one', { base });
+    }
+    if (probe?.ok) {
+        const health = serveHealthSchema.parse(await probe.json());
+        await writeStdoutLine(runtime, `Applet server already running at ${base} (${health.applets.length} applet(s)).`);
+        await writeStdoutLine(runtime, id ? `Open ${base}/applet/${id}/` : `Open ${base}/`);
+        return;
+    }
+    // The host bindings (serve + transpiler + resolver) resolve from the
+    // runtime's `applet/serve-host` kind: no implementation id and no Bun
+    // global at this call site. A host without the bindings fails typed
+    // (`NOT_FOUND` `not-registered`) instead of crashing on a missing global.
+    const serveHost = await runtime.query(APPLET_SERVE_HOST_KIND).enabled().firstOrThrow();
+    const tools = {
+        scan: serveHost.scanModuleSpecifiers,
+        resolve: (specifier, fromDir) => serveHost.resolveModuleSpecifier(specifier, fromDir, runtime),
+        transpile: serveHost.transpileTypeScriptSource,
+        compileStyle: entry => compileServedStylesheet(serveHost, { entry, sources: [], loadStylesheet })
+    };
+    // Files may only be served from the workspace or an installed package.
+    // This package's own sources are served too: the page imports the applet's
+    // surface client from here, wherever the CLI runs this package from.
+    const modulePath = host.paths.fileURLToPath(import.meta.url);
+    const hereDir = host.paths.dirname(modulePath);
+    const moduleExtension = host.paths.extname(modulePath);
+    const { kitRoot, kitStylesheet, resolveDirs, svelteUrl, twAnimateRoot, packageSourceDir, surfaceClientUrl } = await resolveServePackageRoots({
+        host,
+        runtime,
+        tools,
+        workspaceRoot,
+        packageDir: hereDir,
+        packageSourcePath: host.paths.fileURLToPath(new URL('../../', import.meta.url)),
+        surfaceClientPath: host.paths.fileURLToPath(new URL('./served-applet-browser' + moduleExtension, import.meta.url))
+    });
+    const workspacePosix = toPosix(workspaceRoot);
+    const appletRpc = createServedAppletRpc({ runtime, workspaceRoot });
+    const packagePosix = toPosix(packageSourceDir);
+    // Package roots a bare specifier resolved into, by real path. Installed
+    // packages already pass the `node_modules` check; workspace-linked ones
+    // resolve through their link to a real path that would otherwise refuse.
+    const admittedPackageRoots = new Set();
+    async function admitResolved(absolutePath) {
+        const root = await packageRootOf(host, (await realpathOrNullHost(host, absolutePath)) ?? absolutePath);
+        if (root)
+            admittedPackageRoots.add(toPosix(root));
+    }
+    const allowed = (absolutePath) => {
+        const candidate = toPosix(absolutePath);
+        return (candidate.startsWith(workspacePosix + '/') ||
+            candidate.startsWith(packagePosix + '/') ||
+            candidate.startsWith(toPosix(kitRoot) + '/') ||
+            candidate.includes('/node_modules/') ||
+            [...admittedPackageRoots].some(root => candidate.startsWith(root + '/')));
+    };
+    async function loadStylesheet(id, base) {
+        const resolved = isRelative(id)
+            ? host.paths.resolve(base, id)
+            : await resolveForBrowser(host, id, base, tools.resolve, STYLESHEET_CONDITIONS);
+        const path = resolved === null ? null : await realpathOrNullHost(host, resolved);
+        if (path === null) {
+            throw new CapabilityError('An imported applet stylesheet is unavailable.', 'UNAVAILABLE', {
+                reason: 'applet-stylesheet-import-unavailable', details: { id }
+            });
+        }
+        if (!allowed(path)) {
+            throw new CapabilityError('An imported stylesheet is outside the admitted module roots.', 'PERMISSION_DENIED', {
+                reason: 'applet-stylesheet-import-denied'
+            });
+        }
+        return { path, base: host.paths.dirname(path), content: textOf(await host.hostFiles.readFile(path, 'utf8')) };
+    }
+    // Actual text identity also catches edits that preserve size or timestamp granularity.
+    const moduleCache = new Map();
+    async function serveModule(requestedPath) {
+        const absolutePath = await realpathOrNullHost(host, requestedPath);
+        if (!absolutePath)
+            return new Response('Not found', { status: 404 });
+        const info = await statChecked(host.hostFiles, absolutePath);
+        if (!info.found || info.stat.kind !== 'file')
+            return new Response('Not found', { status: 404 });
+        const ext = host.paths.extname(absolutePath);
+        if (ext === '.css')
+            return new Response(asBody(await host.hostFiles.readFile(absolutePath)), { headers: CSS_HEADERS });
+        if (ext === '.json')
+            return new Response(asBody(await host.hostFiles.readFile(absolutePath)), { headers: JSON_HEADERS });
+        const original = textOf(await host.hostFiles.readFile(absolutePath, 'utf8'));
+        const source = ext === '.svelte'
+            ? await prepareServedSvelte(original, { path: absolutePath, base: host.paths.dirname(absolutePath) }, tools.compileStyle)
+            : original;
+        const cached = moduleCache.get(absolutePath);
+        if (cached && cached.source === source)
+            return new Response(cached.code, { headers: JS_HEADERS });
+        const ctx = { tools, host, fromDirs: [host.paths.dirname(absolutePath), ...resolveDirs], admitResolved };
+        let code;
+        const runeModule = /\.svelte\.(js|ts|mjs|mts)$/.test(absolutePath);
+        if (ext === '.svelte') {
+            code = await rewriteModule(compile(source, { filename: absolutePath, generate: 'client', css: 'injected' }).js.code, ctx);
+        }
+        else if (runeModule) {
+            // `.svelte.js` / `.svelte.ts` rune modules need the module compiler,
+            // not a plain transpile — `$state` outside a component is an error.
+            const js = ext === '.ts' || ext === '.mts' ? tools.transpile(source) : source;
+            code = await rewriteModule(compileModule(js, { filename: absolutePath, generate: 'client' }).js.code, ctx);
+        }
+        else if (ext === '.ts' || ext === '.mts') {
+            code = await rewriteModule(tools.transpile(source), ctx);
+        }
+        else if (ext === '.js' || ext === '.mjs') {
+            code = await rewriteModule(source, ctx);
+        }
+        else {
+            return new Response(asBody(await host.hostFiles.readFile(absolutePath)), { headers: { 'cache-control': 'no-store' } });
+        }
+        moduleCache.set(absolutePath, { source, code });
+        return new Response(code, { headers: JS_HEADERS });
+    }
+    async function serveStylesheet(projectId) {
+        const sheet = kitStylesheet === null ? null : await readFileOrNullHost(host, kitStylesheet);
+        if (sheet === null || kitStylesheet === null)
+            return new Response('Not found', { status: 404 });
+        const project = projectId === null ? null : await loadProject(workspaceRoot, projectId, { tools, host, fromDirs: resolveDirs, admitResolved }, svelteUrl);
+        if (projectId !== null && project === null)
+            return new Response('Not found', { status: 404 });
+        const entry = project === null ? '/serve/index.js' : `/applet/${project.id}/applet.js`;
+        const sources = await collectServedStyleContents({
+            entry,
+            scan: tools.scan,
+            async load(url) {
+                let response = null;
+                const diskPath = fromFsUrl(host, url);
+                if (diskPath) {
+                    const real = await realpathOrNullHost(host, diskPath);
+                    if (real === null || (!allowed(real) && !allowed(diskPath))) {
+                        throw new CapabilityError('A stylesheet source is outside the admitted module graph.', 'PERMISSION_DENIED', { reason: 'applet-style-source-denied' });
+                    }
+                    if (real.endsWith('.css') || real.endsWith('.json'))
+                        return null;
+                    response = await serveModule(real);
+                }
+                else if (project && url === entry) {
+                    return project.compiledEntry;
+                }
+                else if (project && url.startsWith(`/applet/${project.id}/`)) {
+                    response = await serveAppletCompanion({ workspaceRoot, id: project.id, project, rest: url.slice(`/applet/${project.id}/`.length), tools, host, resolveDirs, admitResolved });
+                }
+                else if (url === '/serve/index.js') {
+                    response = await serveModule(host.paths.fileURLToPath(new URL('../../svelte/serve-index.svelte', import.meta.url)));
+                }
+                else if (url === '/applets/messages.js') {
+                    response = await serveModule(host.paths.fileURLToPath(new URL('../../schemas/applet-messages' + moduleExtension, import.meta.url)));
+                }
+                // Shims, raw resources and stylesheet-link modules contain no utility sources.
+                if (response === null)
+                    return null;
+                if (!response.ok)
+                    throw new CapabilityError('An admitted stylesheet module could not be read.', 'UNAVAILABLE', { reason: 'applet-style-source-unavailable', details: { url, status: response.status } });
+                if (response.headers.get('content-type')?.split(';')[0] !== JS_HEADERS['content-type'])
+                    return null;
+                return response.text();
+            }
+        });
+        let content = textOf(sheet);
+        if (twAnimateRoot === null)
+            content = content.replace(/@import\s+['"]tw-animate-css['"];?/, '');
+        const css = await compileServedStylesheet(serveHost, {
+            entry: { path: kitStylesheet, base: host.paths.dirname(kitStylesheet), content: `@import 'tailwindcss';\n${content}` },
+            sources,
+            loadStylesheet
+        });
+        return new Response(css, { headers: CSS_HEADERS });
+    }
+    const server = serveHost.startAppletServeHost({
+        port,
+        hostname,
+        fetch: async (request) => {
+            const url = new URL(request.url);
+            const path = url.pathname;
+            // Health / registry — the reuse probe and the machine surface.
+            if (path === HEALTH_PATH) {
+                const ids = await listAppletProjectIds(workspaceRoot, host);
+                const applets = await Promise.all(ids.map(async (pid) => ({ id: pid, entry: 'Applet.svelte' })));
+                const health = { ok: true, root: workspaceRoot, applets };
+                return new Response(JSON.stringify(serveHealthSchema.parse(health)), { headers: JSON_HEADERS });
+            }
+            // ---- Modules: the filesystem mirror ----
+            if (path.startsWith(RAW_MODULE_PREFIX + '/')) {
+                const rawPath = fromFsUrl(host, path.slice(RAW_MODULE_PREFIX.length));
+                const real = rawPath ? await realpathOrNullHost(host, rawPath) : null;
+                if (!rawPath || !real)
+                    return new Response('Not found', { status: 404 });
+                if (!allowed(real) && !allowed(rawPath))
+                    return new Response('Forbidden', { status: 403 });
+                const text = textOf(await host.hostFiles.readFile(real, 'utf8'));
+                return new Response(`export default ${JSON.stringify(text)};\n`, { headers: JS_HEADERS });
+            }
+            if (path.startsWith(WORKER_MODULE_PREFIX + '/')) {
+                const workerPath = fromFsUrl(host, path.slice(WORKER_MODULE_PREFIX.length));
+                const real = workerPath ? await realpathOrNullHost(host, workerPath) : null;
+                if (!workerPath || !real)
+                    return new Response('Not found', { status: 404 });
+                if (!allowed(real) && !allowed(workerPath))
+                    return new Response('Forbidden', { status: 403 });
+                return new Response(workerModule(toFsUrl(real)), { headers: JS_HEADERS });
+            }
+            if (path.startsWith(CSS_MODULE_PREFIX + '/') && path.endsWith('.css')) {
+                return new Response(cssModule(path.slice(CSS_MODULE_PREFIX.length)), { headers: JS_HEADERS });
+            }
+            if (path.startsWith(SHIM_PREFIX) && path.endsWith('.js')) {
+                const specifier = shimSpecifierSchema.safeParse(decodeURIComponent(path.slice(SHIM_PREFIX.length, -3)));
+                if (specifier.success)
+                    return new Response(SHIMS[specifier.data], { headers: JS_HEADERS });
+                return new Response('Not found', { status: 404 });
+            }
+            const fsPath = fromFsUrl(host, path);
+            if (fsPath) {
+                const real = await realpathOrNullHost(host, fsPath);
+                if (!real)
+                    return new Response('Not found', { status: 404 });
+                if (!allowed(real) && !allowed(fsPath))
+                    return new Response('Forbidden', { status: 403 });
+                return serveModule(real);
+            }
+            // ---- Kit stylesheet and the sheets it imports ----
+            if (path === '/kit/styles.css') {
+                const project = url.searchParams.get('project');
+                return serveStylesheet(project === null ? null : servedAppletSchema.shape.id.parse(project));
+            }
+            if (path.startsWith('/kit/styles/') && path.endsWith('.css')) {
+                const name = path.slice('/kit/styles/'.length);
+                if (name.includes('..'))
+                    return new Response('Not found', { status: 404 });
+                // The sheets the kit stylesheet imports sit beside it (`./styles/<name>`).
+                const sheet = kitStylesheet === null ? null : await readFileOrNullHost(host, host.paths.join(host.paths.dirname(kitStylesheet), 'styles', name));
+                if (sheet === null)
+                    return new Response('Not found', { status: 404 });
+                return new Response(asBody(sheet), { headers: CSS_HEADERS });
+            }
+            // ---- Shared message schemas, compiled through the same pipeline ----
+            if (path === '/applets/messages.js') {
+                const abs = host.paths.fileURLToPath(new URL('../../schemas/applet-messages' + moduleExtension, import.meta.url));
+                return serveModule(abs);
+            }
+            // Chrome: the kit-composed index, compiled through the same pipeline.
+            if (path === '/serve/index.js') {
+                const abs = host.paths.fileURLToPath(new URL('../../svelte/serve-index.svelte', import.meta.url));
+                const response = await serveModule(abs);
+                if (!response.ok)
+                    return response;
+                return new Response(withMountAdapter(await response.text(), svelteUrl), { headers: JS_HEADERS });
+            }
+            // Index — kit-composed chrome, rescan per request.
+            if (path === '/') {
+                return new Response(indexHostPage(), { headers: HTML_HEADERS });
+            }
+            // Applet-scoped routes.
+            const m = /^\/applet\/([a-z0-9-]+)(?:\/(.*))?$/.exec(path);
+            if (m) {
+                const id = m[1];
+                const rest = m[2] ?? '';
+                if (rest.startsWith('rpc/'))
+                    return appletRpc.handle(id, request);
+                // The applet's root surface: answered from the project's manifest
+                // alone, so it never compiles the entry.
+                if (rest === 'surface') {
+                    return answerServedAppletSurface({ runtime, workspaceRoot, projectId: id, request });
+                }
+                const project = await loadProject(workspaceRoot, id, { tools, host, fromDirs: resolveDirs, admitResolved }, svelteUrl);
+                if (!project) {
+                    return new Response(JSON.stringify({ error: `No applet "${id}"` }), { status: 404, headers: JSON_HEADERS });
+                }
+                if (rest === '') {
+                    return new Response(hostPage(id, surfaceClientUrl), { headers: HTML_HEADERS });
+                }
+                if (rest === 'applet.js') {
+                    return new Response(project.compiledEntry, { headers: JS_HEADERS });
+                }
+                if (rest === 'files') {
+                    const body = {
+                        id,
+                        entry: project.entry,
+                        files: Object.entries(project.sources).map(([p, contents]) => ({ path: p, contents }))
+                    };
+                    return new Response(JSON.stringify(servedAppletFilesSchema.parse(body)), { headers: JSON_HEADERS });
+                }
+                const companion = await serveAppletCompanion({
+                    workspaceRoot,
+                    id,
+                    project,
+                    rest,
+                    tools,
+                    host,
+                    resolveDirs,
+                    admitResolved
+                });
+                if (companion)
+                    return companion;
+                return new Response(JSON.stringify({ error: 'Not found' }), { status: 404, headers: JSON_HEADERS });
+            }
+            return new Response('Not found', { status: 404 });
+        }
+    });
+    const ids = await listAppletProjectIds(workspaceRoot, host);
+    await writeStdoutLine(runtime, `Applet server serving ${ids.length} project(s) at ${base} (Ctrl+C to stop)`);
+    if (id) {
+        if (!ids.includes(id))
+            await writeStdoutLine(runtime, `(no project "${id}" yet — it will appear once created under .vibes/applets)`);
+        await writeStdoutLine(runtime, `Open ${base}/applet/${id}/`);
+    }
+    else {
+        await writeStdoutLine(runtime, `Open ${base}/`);
+    }
+    // The command owns the server's lifetime: it stays pending until a signal
+    // asks it to stop, so the CLI host never auto-exits underneath Bun.serve.
+    const lifetime = await createCLIActionLifetime(runtime, async () => {
+        await Promise.all([
+            Promise.resolve().then(() => {
+                try {
+                    server.stop();
+                }
+                finally {
+                    moduleCache.clear();
+                }
+            }),
+            appletRpc.close()
+        ]);
+    });
+    lifetime.bindProcessSignals();
+    await lifetime.wait();
+}
+const serveArgsSchema = z.object({ id: z.string().min(1).optional() }).passthrough();
+const serveOptionsSchema = z.object({ port: z.number().optional(), root: z.string().min(1).optional() }).passthrough();
+export async function execute(args, options, context) {
+    const parsedArgs = serveArgsSchema.safeParse(args);
+    const parsedOptions = serveOptionsSchema.safeParse(options);
+    const id = parsedArgs.success ? parsedArgs.data.id : undefined;
+    const port = parsedOptions.success ? parsedOptions.data.port : undefined;
+    const root = parsedOptions.success ? parsedOptions.data.root : undefined;
+    await run(context.runtime, id, { port, root });
+}
+export default { execute };
+//# sourceMappingURL=serve.command.impl.js.map