@crossworks/app-build 0.232.9 → 0.232.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/app-build",
-  "version": "0.232.9",
+  "version": "0.232.11",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -14,7 +14,7 @@
     "lucide-react": "^1.25.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "@mantle/share-ui": "npm:@crossworks/share-ui@0.232.9"
+    "@mantle/share-ui": "npm:@crossworks/share-ui@0.232.11"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

package/src/build-runtime.ts

@@ -108,6 +108,18 @@ function runtimePlugin(): esbuild.Plugin {
 export type RuntimeManifest = {
   /** specifier (as imported in app code) → hashed URL under `/app-runtime/`. */
   imports: Record<string, string>;
+  /** specifier → the export names that module actually provides ('default'
+   *  included when it has one). Taken from esbuild's metafile, so it is the
+   *  build's own account of the module rather than a parse of its output.
+   *
+   *  This exists so `buildApp` can REJECT an app that imports a name the
+   *  runtime does not export. Left unchecked, such an app builds and publishes
+   *  clean and then fails in the browser as a module-level SyntaxError — which
+   *  no ErrorBoundary can catch (linking precedes evaluation), so the app never
+   *  signals ready and the user waits out the sandbox watchdog for a generic
+   *  "couldn't load" with no cause. One `import host from '@host'` (the export
+   *  is named, not default) cost exactly that in the field. */
+  exports: Record<string, string[]>;
   builtAt: string;
   esbuildVersion: string;
 };
@@ -139,10 +151,10 @@ export async function buildRuntime(
     entryNames: '[name]-[hash]',
     chunkNames: 'chunk-[hash]',
     write: true,
+    metafile: true,
     logLevel: 'silent',
     plugins: [runtimePlugin()],
   });
-  void result;
 
   // Map each requested entry name → its hashed output file. esbuild names entry
   // outputs `<out>-<hash>.js`; the hash is alnum (no dashes), so the file for an
@@ -157,15 +169,29 @@ export async function buildRuntime(
     )!;
   }
 
+  // esbuild keys metafile outputs by path relative to cwd, not by basename.
+  const exportsByFile = new Map<string, string[]>();
+  for (const [outPath, meta] of Object.entries(result.metafile.outputs)) {
+    exportsByFile.set(path.basename(outPath), meta.exports ?? []);
+  }
+
   const imports: Record<string, string> = {};
+  const exports: Record<string, string[]> = {};
   for (const [specifier, name] of Object.entries(RUNTIME_SPECIFIERS)) {
     const file = nameToFile[name];
     if (!file) throw new Error(`runtime build produced no output for entry '${name}'`);
     imports[specifier] = urlPrefix + file;
+    const names = exportsByFile.get(file);
+    // A missing export list would silently disable the import check for this
+    // specifier — fail the runtime build instead, where it is one loud error at
+    // deploy time rather than a guard that quietly stopped guarding.
+    if (!names) throw new Error(`runtime build produced no metafile entry for '${file}'`);
+    exports[specifier] = names;
   }
 
   const manifest: RuntimeManifest = {
     imports,
+    exports,
     builtAt: new Date().toISOString(),
     esbuildVersion: esbuild.version,
   };

package/src/build.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { buildApp, type AppSource } from './index';
+import { RUNTIME_EXPORTS_FIXTURE as RT } from './runtime-exports.fixture';
 
 /** A minimal valid app: one entry file exporting a default component. */
 function app(files: Record<string, string>, entry = 'App.tsx'): AppSource {
@@ -10,7 +11,7 @@ const TRIVIAL = 'export default function App() {\n  return <div>hi</div>;\n}\n';
 
 describe('buildApp — happy path', () => {
   it('bundles a trivial app into self-mounting ESM', async () => {
-    const res = await buildApp(app({ 'App.tsx': TRIVIAL }));
+    const res = await buildApp(app({ 'App.tsx': TRIVIAL }), { runtimeExports: RT });
     expect(res.ok).toBe(true);
     expect(typeof res.code).toBe('string');
     expect(res.code!.length).toBeGreaterThan(0);
@@ -19,7 +20,7 @@ describe('buildApp — happy path', () => {
   });
 
   it('externalizes React + @host (resolved via the shared runtime import map)', async () => {
-    const res = await buildApp(app({ 'App.tsx': TRIVIAL }));
+    const res = await buildApp(app({ 'App.tsx': TRIVIAL }), { runtimeExports: RT });
     expect(res.ok).toBe(true);
     // React (here the automatic-JSX runtime) and the host bridge are NOT
     // bundled — they remain bare imports the iframe's import map resolves to the
@@ -43,7 +44,7 @@ describe('buildApp — happy path', () => {
         '  return <Button>{n}</Button>;\n' +
         '}\n',
     });
-    const res = await buildApp(src);
+    const res = await buildApp(src, { runtimeExports: RT });
     expect(res.ok).toBe(true);
     expect(res.errors).toEqual([]);
   });
@@ -55,7 +56,7 @@ describe('buildApp — happy path', () => {
       'lib/util.ts': "export { greet } from './greet';\n",
       'lib/greet/index.ts': "export function greet() { return 'hi'; }\n",
     });
-    const res = await buildApp(src);
+    const res = await buildApp(src, { runtimeExports: RT });
     expect(res.ok).toBe(true);
   });
 });
@@ -66,7 +67,7 @@ describe('buildApp — the import allowlist (security boundary)', () => {
       'App.tsx':
         "import _ from 'lodash';\nexport default function App() { return <div>{String(_)}</div>; }\n",
     });
-    const res = await buildApp(src);
+    const res = await buildApp(src, { runtimeExports: RT });
     expect(res.ok).toBe(false);
     expect(res.errors.some((e) => /not allowed in a mini app|lodash/i.test(e.text))).toBe(true);
   });
@@ -76,7 +77,7 @@ describe('buildApp — the import allowlist (security boundary)', () => {
       'App.tsx':
         "import fs from 'node:fs';\nexport default function App() { return <div>{String(fs)}</div>; }\n",
     });
-    const res = await buildApp(src);
+    const res = await buildApp(src, { runtimeExports: RT });
     expect(res.ok).toBe(false);
   });
 
@@ -85,7 +86,7 @@ describe('buildApp — the import allowlist (security boundary)', () => {
       'App.tsx':
         "import x from '@/components/ui/table';\nexport default function App() { return <div>{String(x)}</div>; }\n",
     });
-    const res = await buildApp(src);
+    const res = await buildApp(src, { runtimeExports: RT });
     expect(res.ok).toBe(false);
     expect(res.errors.some((e) => /Unknown import/i.test(e.text))).toBe(true);
   });
@@ -93,7 +94,7 @@ describe('buildApp — the import allowlist (security boundary)', () => {
 
 describe('buildApp — error reporting', () => {
   it('fails when the entry file is missing from the tree', async () => {
-    const res = await buildApp(app({ 'Other.tsx': TRIVIAL }, 'App.tsx'));
+    const res = await buildApp(app({ 'Other.tsx': TRIVIAL }, 'App.tsx'), { runtimeExports: RT });
     expect(res.ok).toBe(false);
     expect(res.errors[0]?.text).toMatch(/not found/i);
   });
@@ -103,7 +104,7 @@ describe('buildApp — error reporting', () => {
       'App.tsx':
         "import { x } from './missing';\nexport default function App() { return <div>{x}</div>; }\n",
     });
-    const res = await buildApp(src);
+    const res = await buildApp(src, { runtimeExports: RT });
     expect(res.ok).toBe(false);
     expect(res.errors.some((e) => /Cannot resolve/i.test(e.text))).toBe(true);
   });
@@ -112,7 +113,7 @@ describe('buildApp — error reporting', () => {
     const src = app({
       'App.tsx': 'export default function App() { return <div>oops</div> // missing brace\n',
     });
-    const res = await buildApp(src);
+    const res = await buildApp(src, { runtimeExports: RT });
     expect(res.ok).toBe(false);
     expect(res.errors.length).toBeGreaterThan(0);
     expect(res.errors.some((e) => e.location !== null)).toBe(true);
@@ -129,7 +130,7 @@ describe('lintToolRefs — undeclared host.tools.call', () => {
         '  return <button onClick={go}>go</button>;\n' +
         '}\n',
     });
-    const res = await buildApp(src, { declaredToolSlugs: [] });
+    const res = await buildApp(src, { declaredToolSlugs: [], runtimeExports: RT });
     expect(res.ok).toBe(true); // warning-only: the build still succeeds
     expect(res.warnings.some((w) => /openweather_geocode/.test(w.text))).toBe(true);
     const w = res.warnings.find((w) => /openweather_geocode/.test(w.text));
@@ -146,7 +147,7 @@ describe('lintToolRefs — undeclared host.tools.call', () => {
         '  return <div>ok</div>;\n' +
         '}\n',
     });
-    const res = await buildApp(src, { declaredToolSlugs: ['weather_now'] });
+    const res = await buildApp(src, { declaredToolSlugs: ['weather_now'], runtimeExports: RT });
     expect(res.ok).toBe(true);
     expect(res.warnings.some((w) => /weather_now/.test(w.text))).toBe(false);
   });
@@ -160,7 +161,7 @@ describe('lintToolRefs — undeclared host.tools.call', () => {
         '  return <div>ok</div>;\n' +
         '}\n',
     });
-    const res = await buildApp(src);
+    const res = await buildApp(src, { runtimeExports: RT });
     expect(res.warnings.some((w) => /isn't in the app's declared tools/.test(w.text))).toBe(false);
   });
 
@@ -174,7 +175,7 @@ describe('lintToolRefs — undeclared host.tools.call', () => {
         '  return <div>ok</div>;\n' +
         '}\n',
     });
-    const res = await buildApp(src, { declaredToolSlugs: [] });
+    const res = await buildApp(src, { declaredToolSlugs: [], runtimeExports: RT });
     expect(res.ok).toBe(true);
     expect(res.warnings.length).toBe(0);
   });

package/src/css.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { buildApp, type AppSource } from './index';
+import { RUNTIME_EXPORTS_FIXTURE as RT } from './runtime-exports.fixture';
 
 function app(files: Record<string, string>, entry = 'App.tsx'): AppSource {
   return { entry, files };
@@ -18,6 +19,7 @@ describe('buildApp — per-app CSS', () => {
 }
 `,
       }),
+      { runtimeExports: RT },
     );
     expect(res.ok).toBe(true);
     expect(res.css).toBeTruthy();
@@ -41,6 +43,7 @@ describe('buildApp — per-app CSS', () => {
 export default function App() { return <Card>x</Card>; }
 `,
       }),
+      { runtimeExports: RT },
     );
     expect(res.ok).toBe(true);
     // rounded-xl comes from the kit Card source, not the app source.
@@ -48,7 +51,9 @@ export default function App() { return <Card>x</Card>; }
   });
 
   it('a failed JS build produces no css', async () => {
-    const res = await buildApp(app({ 'App.tsx': 'export default function App( {' }));
+    const res = await buildApp(app({ 'App.tsx': 'export default function App( {' }), {
+      runtimeExports: RT,
+    });
     expect(res.ok).toBe(false);
     expect(res.css).toBeUndefined();
   });

package/src/index.ts

@@ -207,13 +207,113 @@ export function lintToolRefs(source: AppSource, declaredSlugs: string[]): BuildM
   return out;
 }
 
+/** `import <what> from "<spec>"` — captures the clause and the specifier.
+ *  Covers the three ESM shapes esbuild leaves external: default, namespace,
+ *  and named (including a default+named combination). */
+const IMPORT_RE = /import\s+([^'";]+?)\s+from\s*['"]([^'"]+)['"]/g;
+
+/** Split an import clause into the names it binds FROM the module.
+ *  `Foo`               → default
+ *  `* as ns`           → namespace (binds nothing by name; nothing to check)
+ *  `{ a, b as c }`     → a, b
+ *  `Foo, { a }`        → default, a
+ *  Returns the names as the MODULE must provide them, not the local aliases. */
+function importedNames(clause: string): { names: string[]; namespace: boolean } {
+  const names: string[] = [];
+  let namespace = false;
+  const braced = clause.match(/\{([^}]*)\}/);
+  const head = clause
+    .slice(0, braced ? clause.indexOf('{') : undefined)
+    .replace(/,\s*$/, '')
+    .trim();
+  if (head) {
+    if (/^\*\s+as\s+/.test(head)) namespace = true;
+    else if (/^[A-Za-z_$][\w$]*$/.test(head)) names.push('default');
+  }
+  if (braced) {
+    for (const part of braced[1]!.split(',')) {
+      const name = (part.split(/\s+as\s+/)[0] ?? '').trim();
+      if (name) names.push(name);
+    }
+  }
+  return { names, namespace };
+}
+
+/**
+ * Static lint: every import of a SHARED RUNTIME specifier must name something
+ * that specifier actually exports.
+ *
+ * These specifiers are external — esbuild leaves them as bare imports for the
+ * sandbox's import map to resolve, so it never checks their shape, and a wrong
+ * name survives into a clean, publishable build. The browser then rejects the
+ * module while LINKING, before any code runs: no ErrorBoundary can catch it
+ * (there is nothing to render yet) and the app never signals ready, so the
+ * sandbox can only time out with a generic failure. `import host from '@host'`
+ * — where the export is named, not default — cost exactly that in the field:
+ * a green build, then a twenty-second spinner and "couldn't load the app".
+ *
+ * Errors, not warnings: the app is guaranteed not to run.
+ *
+ * Local/relative imports are the bundler's business and are skipped, as is a
+ * namespace import (`* as ns`), which binds no names and cannot mismatch.
+ */
+export function lintRuntimeImports(
+  source: AppSource,
+  runtimeExports: Record<string, string[]>,
+): BuildMessage[] {
+  const out: BuildMessage[] = [];
+  for (const [file, text] of Object.entries(source.files)) {
+    IMPORT_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = IMPORT_RE.exec(text)) !== null) {
+      const spec = m[2]!;
+      if (spec.startsWith('.') || spec.startsWith('/')) continue;
+      const available = runtimeExports[spec];
+      if (!available) continue; // not a shared-runtime specifier; esbuild will rule on it
+      const { names, namespace } = importedNames(m[1]!);
+      if (namespace) continue;
+      const have = new Set(available);
+      for (const name of names) {
+        if (have.has(name)) continue;
+        const pre = text.slice(0, m.index);
+        const line = pre.length - pre.replace(/\n/g, '').length + 1; // 1-based
+        const column = m.index - (pre.lastIndexOf('\n') + 1); // 0-based within line
+        const hint =
+          name === 'default'
+            ? `'${spec}' has no default export. Use a named import, e.g. import { ${available[0]} } from '${spec}'.`
+            : `'${spec}' does not export '${name}'.`;
+        out.push({
+          text: `${hint} It exports: ${available.join(', ')}. Left as-is the app builds but fails to load in the browser, with no error the app can catch.`,
+          location: { file, line, column },
+        });
+      }
+    }
+  }
+  return out;
+}
+
 /** Bundle an app's source tree into one self-mounting ESM module. When
  *  `declaredToolSlugs` is supplied, undeclared `host.tools.call` slugs are
  *  appended to the build's warnings (see lintToolRefs). */
+export { loadRuntimeExports } from './runtime-exports';
+
 export async function buildApp(
   source: AppSource,
-  opts: { declaredToolSlugs?: string[] } = {},
+  opts: {
+    declaredToolSlugs?: string[];
+    /** The shared runtime's export map (`loadRuntimeExports()` in production).
+     *  REQUIRED so the import check below cannot be skipped by forgetting it —
+     *  an app that fails this check cannot run at all, so silently omitting the
+     *  check would ship a guaranteed-broken app. */
+    runtimeExports: Record<string, string[]>;
+  },
 ): Promise<BuildResult> {
+  // Runtime-import mismatches are fatal and cheap to detect, so they short
+  // circuit ahead of esbuild: no point compiling an app that cannot link.
+  const importErrors = lintRuntimeImports(source, opts.runtimeExports);
+  if (importErrors.length) {
+    return { ok: false, errors: importErrors, warnings: [], esbuildVersion: ESBUILD_VERSION };
+  }
   const toolWarnings = opts.declaredToolSlugs ? lintToolRefs(source, opts.declaredToolSlugs) : [];
   const withToolWarnings = (r: BuildResult): BuildResult =>
     toolWarnings.length ? { ...r, warnings: [...r.warnings, ...toolWarnings] } : r;

package/src/runtime-exports.drift.test.ts

@@ -0,0 +1,44 @@
+/**
+ * The import check is only as good as the export map it checks against.
+ * Production reads the GENERATED manifest, so it is always accurate; the tests
+ * use a hand-written fixture, which is not. This builds the real runtime and
+ * asserts the two agree, so a runtime change that the fixture misses fails
+ * here instead of quietly letting every other test pass against a shape that
+ * no longer exists.
+ */
+import { describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { buildRuntime } from './build-runtime';
+import { RUNTIME_EXPORTS_FIXTURE } from './runtime-exports.fixture';
+
+describe('RUNTIME_EXPORTS_FIXTURE', () => {
+  it('matches what buildRuntime actually emits', async () => {
+    const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mantle-rt-'));
+    try {
+      const manifest = await buildRuntime(outDir, '/app-runtime/');
+
+      // Same specifiers on both sides.
+      expect(Object.keys(RUNTIME_EXPORTS_FIXTURE).sort()).toEqual(
+        Object.keys(manifest.exports).sort(),
+      );
+
+      for (const [spec, fixture] of Object.entries(RUNTIME_EXPORTS_FIXTURE)) {
+        const real = new Set(manifest.exports[spec]);
+        // The fixture may list a SUBSET of a big surface (react has hundreds of
+        // exports) — what it must never do is claim a name the runtime lacks,
+        // because that is what would let a broken import pass the check.
+        for (const name of fixture) {
+          expect(real, `${spec} should export ${name}`).toContain(name);
+        }
+      }
+
+      // The specifier the field bug hit: assert its exact shape, since the
+      // whole check turns on '@host' having no default export.
+      expect(manifest.exports['@host']).toEqual(['__mount', 'host']);
+    } finally {
+      fs.rmSync(outDir, { recursive: true, force: true });
+    }
+  }, 120_000);
+});

package/src/runtime-exports.fixture.ts

@@ -0,0 +1,31 @@
+/**
+ * The shared runtime's export map as a TEST fixture. Production never uses
+ * this — `loadRuntimeExports()` reads the generated manifest, so the real
+ * check always describes the runtime that is actually deployed. This exists so
+ * tests can call `buildApp` without building the whole runtime first.
+ *
+ * `runtime-exports.drift.test.ts` builds the real runtime and asserts this
+ * matches, so a fixture that falls behind fails loudly instead of quietly
+ * letting tests pass against a runtime shape that no longer exists.
+ */
+export const RUNTIME_EXPORTS_FIXTURE: Record<string, string[]> = {
+  react: ['default', 'useState', 'useEffect', 'useRef', 'useCallback', 'useMemo'],
+  'react-dom': ['default'],
+  'react-dom/client': ['createRoot', 'hydrateRoot', 'version'],
+  'react/jsx-runtime': ['Fragment', 'jsx', 'jsxs'],
+  '@/lib/utils': ['cn'],
+  '@/components/ui/button': ['Button'],
+  '@/components/ui/card': [
+    'Card',
+    'CardContent',
+    'CardDescription',
+    'CardFooter',
+    'CardHeader',
+    'CardTitle',
+  ],
+  '@/components/ui/input': ['Input'],
+  '@/components/ui/label': ['Label'],
+  '@/components/ui/badge': ['Badge'],
+  '@/components/ui/separator': ['Separator'],
+  '@host': ['__mount', 'host'],
+};

package/src/runtime-exports.test.ts

@@ -0,0 +1,94 @@
+/**
+ * The manifest lookup must not depend on the working directory. app_build runs
+ * from BOTH server/web (Next) and server/mcp (the agent's MCP server); a bare
+ * cwd-relative path works in the first and resolves to nothing in the second,
+ * which took every agent-driven build down with ENOENT until it was fixed.
+ */
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadRuntimeExports, manifestCandidates } from './runtime-exports';
+
+const ENV = 'MANTLE_APP_RUNTIME_MANIFEST';
+let saved: string | undefined;
+
+beforeEach(() => {
+  saved = process.env[ENV];
+});
+afterEach(() => {
+  if (saved === undefined) delete process.env[ENV];
+  else process.env[ENV] = saved;
+});
+
+describe('manifestCandidates', () => {
+  it('includes a package-relative path that does not depend on cwd', () => {
+    delete process.env[ENV];
+    const [pkgRelative] = manifestCandidates();
+    expect(path.isAbsolute(pkgRelative!)).toBe(true);
+    expect(pkgRelative).toContain(path.join('server', 'web', 'public', 'app-runtime'));
+  });
+
+  it('puts an explicit override ahead of everything else', () => {
+    process.env[ENV] = '/tmp/somewhere/manifest.json';
+    expect(manifestCandidates()[0]).toBe('/tmp/somewhere/manifest.json');
+  });
+
+  it('still offers the cwd convention as a fallback', () => {
+    delete process.env[ENV];
+    expect(manifestCandidates()).toContain(path.resolve('public/app-runtime/manifest.json'));
+  });
+});
+
+describe('loadRuntimeExports', () => {
+  it('reads the exports map from the override path', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mantle-mf-'));
+    const file = path.join(dir, 'manifest.json');
+    fs.writeFileSync(file, JSON.stringify({ imports: {}, exports: { '@host': ['host'] } }));
+    process.env[ENV] = file;
+    try {
+      await expect(loadRuntimeExports()).resolves.toEqual({ '@host': ['host'] });
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('throws and names every path it tried when nothing is found', async () => {
+    // Candidates are injected: the real list always resolves inside this repo,
+    // so the not-found path cannot be reached through the environment alone.
+    const missing = [
+      path.join(os.tmpdir(), 'nope-a', 'manifest.json'),
+      path.join(os.tmpdir(), 'nope-b', 'manifest.json'),
+    ];
+    await expect(loadRuntimeExports(missing)).rejects.toThrow(/manifest not found[\s\S]*Tried:/);
+    for (const m of missing) {
+      await expect(loadRuntimeExports(missing)).rejects.toThrow(m);
+    }
+  });
+
+  it('does not fall through to another candidate when one is present but broken', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mantle-mf-'));
+    const broken = path.join(dir, 'manifest.json');
+    fs.writeFileSync(broken, JSON.stringify({ imports: {} }));
+    const good = path.join(dir, 'good.json');
+    fs.writeFileSync(good, JSON.stringify({ exports: { '@host': ['host'] } }));
+    try {
+      // A stale copy further down the list must never win over a broken one.
+      await expect(loadRuntimeExports([broken, good])).rejects.toThrow(/no 'exports' map/);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('refuses a manifest that exists but carries no exports map', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mantle-mf-'));
+    const file = path.join(dir, 'manifest.json');
+    fs.writeFileSync(file, JSON.stringify({ imports: { react: '/x.js' } }));
+    process.env[ENV] = file;
+    try {
+      await expect(loadRuntimeExports()).rejects.toThrow(/no 'exports' map/);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/runtime-exports.ts

@@ -0,0 +1,87 @@
+/**
+ * Load the shared runtime's export map — what `/app-runtime/manifest.json`
+ * recorded about each specifier during `buildRuntime`.
+ *
+ * `buildApp` needs this to reject an app that imports a name the runtime does
+ * not provide. Reading the GENERATED manifest (rather than re-deriving the
+ * names here) keeps one source of truth: the check can only ever describe the
+ * runtime that is actually deployed alongside it.
+ *
+ * Resolution deliberately does NOT trust the working directory. The manifest is
+ * generated into server/web/public, and server/web's cwd is what
+ * `server/web/lib/app-frame.ts` relies on — but app_build also runs from the
+ * MCP server, whose cwd is server/mcp, and a bare relative path there resolves
+ * to nothing. That cost a live build outage: every agent-driven app_build
+ * failed with ENOENT until the lookup stopped assuming one caller. So the
+ * package locates the manifest relative to ITSELF first (the repo and the image
+ * share the same layout), falls back to the cwd convention for anything that
+ * relocates it, and takes an explicit env override ahead of both.
+ *
+ * A missing or malformed manifest THROWS, naming every path it tried. It must
+ * never degrade to "no exports known": an empty map would flag every import as
+ * invalid, and an optional one would silently stop guarding.
+ */
+import { readFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** In order of trust: explicit override, package-relative, cwd convention. */
+export function manifestCandidates(): string[] {
+  const override = process.env.MANTLE_APP_RUNTIME_MANIFEST;
+  return [
+    ...(override ? [override] : []),
+    // packages/app-build/src → <root>/server/web/public/app-runtime/manifest.json
+    path.resolve(HERE, '../../../server/web/public/app-runtime/manifest.json'),
+    path.resolve('public/app-runtime/manifest.json'),
+  ];
+}
+
+/** Keyed by the candidate list rather than a single flag: the paths are stable
+ *  in production (so this is still one read per process), and a changed
+ *  override naturally re-resolves instead of serving another location's
+ *  answer. */
+const cache = new Map<string, Promise<Record<string, string[]>>>();
+
+export function loadRuntimeExports(
+  /** Injectable for tests only — production always uses the real candidates.
+   *  A test cannot isolate the not-found path otherwise, because the
+   *  package-relative candidate resolves inside the repo itself. */
+  candidates: string[] = manifestCandidates(),
+): Promise<Record<string, string[]>> {
+  const key = candidates.join('\u0000');
+  let cached = cache.get(key);
+  if (!cached) {
+    cached = (async () => {
+      const tried: string[] = [];
+      for (const candidate of candidates) {
+        tried.push(candidate);
+        let raw: string;
+        try {
+          raw = await readFile(candidate, 'utf8');
+        } catch {
+          continue; // not here; try the next location
+        }
+        // Present but unusable is a hard error — never fall through to another
+        // candidate, or a stale copy elsewhere could silently win.
+        const m = JSON.parse(raw) as { exports?: Record<string, string[]> };
+        if (!m.exports || Object.keys(m.exports).length === 0) {
+          throw new Error(
+            `${candidate} has no 'exports' map — regenerate it with the app-runtime build`,
+          );
+        }
+        return m.exports;
+      }
+      throw new Error(
+        `app-runtime manifest not found. Tried:\n  ${tried.join('\n  ')}\n` +
+          'Generate it with the app-runtime build, or set MANTLE_APP_RUNTIME_MANIFEST.',
+      );
+    })().catch((e: unknown) => {
+      cache.delete(key); // let the next call retry rather than pinning the failure
+      throw e;
+    });
+    cache.set(key, cached);
+  }
+  return cached;
+}

package/src/runtime-imports.test.ts

@@ -0,0 +1,101 @@
+/**
+ * The runtime specifiers are external, so esbuild never checks their shape and
+ * a wrong import name survives into a green, publishable build. The browser
+ * then rejects the module while LINKING — before any code runs, so nothing the
+ * app can install (ErrorBoundary included) ever sees it, and the sandbox can
+ * only time out with a generic failure. These tests pin the check that turns
+ * that class of bug into a build error.
+ */
+import { describe, expect, it } from 'vitest';
+import { buildApp, lintRuntimeImports } from './index';
+import { RUNTIME_EXPORTS_FIXTURE as RT } from './runtime-exports.fixture';
+
+const src = (files: Record<string, string>) => ({ entry: 'App.tsx', files });
+
+describe('lintRuntimeImports', () => {
+  it('catches the field bug: a default import of a named-only module', () => {
+    const msgs = lintRuntimeImports(src({ 'lib/store.ts': "import host from '@host';\n" }), RT);
+    expect(msgs).toHaveLength(1);
+    expect(msgs[0]!.text).toContain("'@host' has no default export");
+    // The message has to carry the fix, not just the complaint.
+    expect(msgs[0]!.text).toContain("import { __mount } from '@host'");
+    expect(msgs[0]!.text).toContain('__mount, host');
+    expect(msgs[0]!.location).toEqual({ file: 'lib/store.ts', line: 1, column: 0 });
+  });
+
+  it('accepts the correct named import', () => {
+    expect(lintRuntimeImports(src({ 'a.ts': "import { host } from '@host';\n" }), RT)).toEqual([]);
+  });
+
+  it('catches a named import the module does not export', () => {
+    const msgs = lintRuntimeImports(src({ 'a.ts': "import { nope } from '@host';\n" }), RT);
+    expect(msgs).toHaveLength(1);
+    expect(msgs[0]!.text).toContain("'@host' does not export 'nope'");
+  });
+
+  it('checks the module name, not the local alias', () => {
+    expect(lintRuntimeImports(src({ 'a.ts': "import { host as h } from '@host';\n" }), RT)).toEqual(
+      [],
+    );
+    expect(
+      lintRuntimeImports(src({ 'a.ts': "import { nope as host } from '@host';\n" }), RT),
+    ).toHaveLength(1);
+  });
+
+  it('allows a default import where the module really has one', () => {
+    expect(lintRuntimeImports(src({ 'a.ts': "import React from 'react';\n" }), RT)).toEqual([]);
+  });
+
+  it('reports the right line in a multi-line file', () => {
+    const text = "// header\nimport { cn } from '@/lib/utils';\nimport bad from '@host';\n";
+    const msgs = lintRuntimeImports(src({ 'a.ts': text }), RT);
+    expect(msgs).toHaveLength(1);
+    expect(msgs[0]!.location?.line).toBe(3);
+  });
+
+  it('ignores relative imports and unknown packages — esbuild rules on those', () => {
+    const text = "import x from './local';\nimport y from 'some-npm-pkg';\n";
+    expect(lintRuntimeImports(src({ 'a.ts': text }), RT)).toEqual([]);
+  });
+
+  it('ignores a namespace import, which binds no names to mismatch', () => {
+    expect(lintRuntimeImports(src({ 'a.ts': "import * as h from '@host';\n" }), RT)).toEqual([]);
+  });
+
+  it('handles a combined default + named import', () => {
+    const msgs = lintRuntimeImports(
+      src({ 'a.ts': "import React, { useState } from 'react';\n" }),
+      RT,
+    );
+    expect(msgs).toEqual([]);
+  });
+});
+
+describe('buildApp — runtime import check', () => {
+  it('FAILS the build rather than publishing an app that cannot link', async () => {
+    const res = await buildApp(
+      src({
+        'App.tsx':
+          "import { host } from './lib/store';\nexport default function App(){return <div/>;}\n",
+        'lib/store.ts': "import host from '@host';\nexport { host };\n",
+      }),
+      { runtimeExports: RT },
+    );
+    expect(res.ok).toBe(false);
+    expect(res.errors[0]!.text).toContain("'@host' has no default export");
+    // Nothing is emitted — a caller must not be able to publish this.
+    expect(res.code).toBeUndefined();
+  });
+
+  it('builds normally when the imports are right', async () => {
+    const res = await buildApp(
+      src({
+        'App.tsx':
+          "import { host } from '@host';\nexport default function App(){return <div>{String(!!host)}</div>;}\n",
+      }),
+      { runtimeExports: RT },
+    );
+    expect(res.ok).toBe(true);
+    expect(res.errors).toEqual([]);
+  });
+});