@mosetta/build 0.0.0-stage → 0.0.9

package/src/buildDependencies.mjs

@@ -0,0 +1,97 @@
+import commonjs from '@rollup/plugin-commonjs';
+import { path } from './nodeApi.mjs';
+import { packageDirOf } from './packageMeta.mjs';
+import { defineEnv } from './plugins/defineEnv.mjs';
+import { portResolve } from './plugins/portResolve.mjs';
+import { resolveSpecifier } from './specifiers.mjs';
+import { assertNamedRegister } from './buildConfig.mjs';
+import { userPluginsFor } from './buildModules.mjs';
+import { sourcemapPathTransformFor } from './sourcemap.mjs';
+import { transformTs, minifyChunk } from './plugins/transform.mjs';
+
+const isBareExternal = (id) =>
+  !id.startsWith('.') && !path.isAbsolute(id) && !id.startsWith('\0');
+
+const FACADE_ID = '\0mosetta-facade';
+
+/**
+ * Build one external dependency (npm or framework package) into a System artifact.
+ * Internal/relative imports are bundled; cross-package bare imports stay external
+ * (→ their own artifacts, resolved by the import map).
+ * For CJS deps, `namedExports` (enumerated via Node) generates a facade so the artifact
+ * exposes real named exports (needed for cross-artifact `import { x } from 'pkg'`).
+ * Returns { full, code, imports } where imports = bare deps of this artifact.
+ */
+export async function buildDependency(fileSystem, { resolver, specifier, resolvedFile, full, namedExports, mode = 'development', buildConfig = null, engine, sourceBase }) {
+  // this dependency's OWN transitives resolve from ITS package — dockview finds
+  // dockview-core in its .pnpm neighbourhood, no app-level declarations
+  const baseDir = packageDirOf(fileSystem, resolvedFile) ?? path.dirname(resolvedFile);
+  // maps are always EXTERNAL (placed into the private counterpart by writeJs); in dev,
+  // heavy vendor deps (react) skip map generation entirely — nobody debugs their internals
+  const isTS = /\.tsx?$/.test(resolvedFile);
+  const sourcemap = mode === 'production' || isTS;
+  const useFacade = Array.isArray(namedExports) && namedExports.length > 0;
+  const facadeCode = useFacade
+    ? `import __cjs from ${JSON.stringify(resolvedFile)};\n`
+      + `export default __cjs;\n`
+      + `export const { ${namedExports.join(', ')} } = __cjs;\n`
+    : null;
+
+  // the rollupOptions escape hatch transforms the composed INPUT options; user
+  // plugins land after the facade virtual entry (it must keep resolving first) and before the
+  // framework chain
+  const optionsHook = (o) => buildConfig?.rollupOptions?.(o, { target: 'dependency', mode }) ?? o;
+  const bundle = await engine.rollup(optionsHook({
+    input: useFacade ? FACADE_ID : resolvedFile,
+    external: isBareExternal,
+    plugins: [
+      {
+        name: 'mosetta-facade',
+        resolveId(id) {
+          return id === FACADE_ID ? id : null;
+        },
+        load(id) {
+          return id === FACADE_ID ? facadeCode : null;
+        },
+      },
+      ...userPluginsFor(buildConfig, 'dependency', mode),
+      defineEnv(mode),
+      portResolve(fileSystem, resolver, baseDir),
+      commonjs(),
+      transformTs(engine), // .js (CJS deps like react) is handled by @rollup/plugin-commonjs
+    ],
+    onwarn(w, warn) {
+      if (w.code === 'UNRESOLVED_IMPORT' || w.code === 'CIRCULAR_DEPENDENCY') return;
+      warn(w);
+    },
+  }));
+
+  // rewrite cross-package externals `bare` → version-qualified full-id
+  const externalMap = new Map();
+  const paths = (id) => {
+    const f = resolveSpecifier(fileSystem, resolver, id, baseDir)?.full || id;
+    externalMap.set(id, f);
+    return f;
+  };
+  // named register (SSR epic stage 1) — same rationale as buildModules.generateSystem; production
+  // minify mangles only artifact-internal scope (linkage names are string literals)
+  const { output } = await bundle.generate({
+    format: 'system', name: full, exports: 'named', sourcemap, paths,
+    sourcemapPathTransform: sourcemapPathTransformFor(sourceBase),
+    plugins: mode === 'production' ? [minifyChunk(engine)] : [],
+  });
+  const watchFiles = bundle.watchFiles.slice();
+  await bundle.close();
+
+  const chunk = output.find((o) => o.type === 'chunk');
+  assertNamedRegister(chunk.code, full, buildConfig); // protocol invariant
+  const map = sourcemap === true && chunk.map ? chunk.map.toString() : null;
+  return {
+    full,
+    jsCode: chunk.code,
+    map,
+    imports: [...externalMap.values()], // full-ids
+    rawImports: [...externalMap.keys()], // bare specifiers (for closure traversal)
+    watchFiles,
+  };
+}

package/src/buildModules.mjs

@@ -0,0 +1,328 @@
+import commonjs from '@rollup/plugin-commonjs';
+import { path } from './nodeApi.mjs';
+import { packageDirOf } from './packageMeta.mjs';
+import { fullTileName } from './moduleName.mjs';
+import { cssIntercept } from './plugins/cssIntercept.mjs';
+import { assets } from './plugins/assets.mjs';
+import { defineEnv } from './plugins/defineEnv.mjs';
+import { portResolve } from './plugins/portResolve.mjs';
+import { processCss } from './css.mjs';
+import { resolveSpecifier } from './specifiers.mjs';
+import { assertNamedRegister } from './buildConfig.mjs';
+import { sourcemapPathTransformFor } from './sourcemap.mjs';
+import { transformTs, minifyChunk } from './plugins/transform.mjs';
+import { mtimeStamp } from './artifactCache.mjs';
+
+// Every bare specifier (npm AND framework packages) is external — they become
+// import-map-resolved System deps. Relative/absolute imports are bundled into the module.
+// css is NEVER external: rollup consults `external` BEFORE plugin resolveId hooks, and a bare
+// css import ('@mosetta/ui/ui.css') must reach cssIntercept, not the dep closure.
+const isExternal = (id) =>
+  !id.endsWith('.css') && !id.startsWith('.') && !path.isAbsolute(id) && !id.startsWith('\0');
+
+// external maps in EVERY mode: the map is a separate artifact the build places into
+// the store's private counterpart; dev DX comes from the dev server's SourceMap response header
+export const sourcemapFor = () => true;
+
+// user hooks: plugins from mosetta.build.mjs land BEFORE the framework ones (React
+// Compiler wants original JSX, an scss plugin must run before cssIntercept), the rollupOptions
+// escape hatch transforms the composed INPUT options (output shape is protocol — not exposed)
+export function userPluginsFor(buildConfig, target, mode) {
+  return buildConfig?.clientPlugins?.({ target, mode }) ?? [];
+}
+function applyOptionsHook(buildConfig, options, target, mode) {
+  return buildConfig?.rollupOptions?.(options, { target, mode }) ?? options;
+}
+
+// production minify is a render-chunk post-pass — mangling touches only artifact-internal scope:
+// the System.register name, dep specifiers and export names are string literals, so the
+// cross-artifact runtime linkage survives untouched
+async function generateSystem({ engine, sourceBase, input, name, plugins, sourcemap = 'inline', resolveExternal, minified = false, buildConfig = null, target = 'module', mode = 'development' }) {
+  const bundle = await engine.rollup(applyOptionsHook(buildConfig, {
+    input,
+    external: isExternal,
+    plugins,
+    onwarn(w, warn) {
+      if (w.code === 'UNRESOLVED_IMPORT' || w.code === 'CIRCULAR_DEPENDENCY') return;
+      warn(w);
+    },
+  }, target, mode));
+  // output.paths rewrites every emitted external `bare` → version-qualified full-id,
+  // and records the (bare → full) of externals actually rendered into this artifact.
+  const externalMap = new Map();
+  const paths = (id) => {
+    const full = (resolveExternal && resolveExternal(id)) || id;
+    externalMap.set(id, full);
+    return full;
+  };
+  // NAMED register (SSR epic stage 1): `System.register('<full-id>', …)` — the artifact is
+  // self-identified, executable by the server mini-System AND concatenable into bundles later.
+  // The client keeps loading by URL: the named-register extra links the URL load to the name
+  // (one instance), so the browser path needs no changes.
+  const { output } = await bundle.generate({
+    format: 'system', name, exports: 'named', sourcemap, paths,
+    sourcemapPathTransform: sourcemapPathTransformFor(sourceBase),
+    plugins: minified ? [minifyChunk(engine)] : [],
+  });
+  const watchFiles = bundle.watchFiles.slice();
+  await bundle.close();
+  const chunk = output.find((o) => o.type === 'chunk');
+  assertNamedRegister(chunk.code, name, buildConfig); // protocol invariant
+  // sourcemap:'inline' embeds the map in chunk.code; true → external map returned separately
+  const map = sourcemap === true && chunk.map ? chunk.map.toString() : null;
+  return {
+    code: chunk.code,
+    map,
+    imports: [...externalMap.values()], // full-ids (the artifact's resolved dependencies)
+    rawImports: [...externalMap.keys()], // bare specifiers (for closure traversal)
+    watchFiles,
+  };
+}
+
+/**
+ * Build one module to a System artifact. Returns code + descriptor (no disk write).
+ */
+export async function buildModule(fileSystem, mod, { resolver, mode = 'development', buildConfig = null, engine, sourceBase, assetExtensions = [] } = {}) {
+  const full = fullTileName(mod);
+  // externals resolve from the MODULE's own package — the full-id rewritten into the
+  // artifact must match what the closure walk resolves and builds from the same context
+  const baseDir = path.dirname(mod.file);
+  const cssRefs = [];
+  const jsAssets = new Map(); // out -> srcAbs (assets imported from JS)
+  const { code, map, imports, rawImports, watchFiles } = await generateSystem({
+    engine,
+    sourceBase,
+    input: mod.file,
+    name: full,
+    plugins: [
+      ...userPluginsFor(buildConfig, 'module', mode),
+      defineEnv(mode), assets(jsAssets, assetExtensions, fileSystem), cssIntercept(cssRefs, resolver, baseDir), transformTs(engine),
+      // LAST: rollup's built-in resolver used to work here, and it runs after all plugins —
+      // placing it earlier would intercept css, assets and the transpiler
+      portResolve(fileSystem, resolver, baseDir),
+    ],
+    sourcemap: sourcemapFor(mode),
+    resolveExternal: (id) => resolveSpecifier(fileSystem, resolver, id, baseDir)?.full,
+    minified: mode === 'production',
+    buildConfig,
+    target: 'module',
+    mode,
+  });
+
+  // css partition: a file from the module's own package is authored styles (a scoped per-module
+  // artifact, as before); a file from a FOREIGN package is dependency css and leaves as one
+  // shared artifact per closure (emitted by build()). realpath — because of workspace symlinks.
+  const ownPkg = packageDirOf(fileSystem, fileSystem.realPath(mod.file));
+  const ownCss = [];
+  const sharedCss = []; // {file, specifier: '<pkg>/<rel>', version}
+  for (const ref of cssRefs) {
+    const real = fileSystem.realPath(ref);
+    const pkgDir = packageDirOf(fileSystem, real);
+    if (!pkgDir || pkgDir === ownPkg) {
+      ownCss.push(ref);
+      continue;
+    }
+    const pkg = fileSystem.readJson(path.join(pkgDir, 'package.json'));
+    sharedCss.push({
+      file: real,
+      specifier: `${pkg.name}/${path.relative(pkgDir, real).split(path.sep).join('/')}`,
+      version: pkg.version ?? '0.0.0',
+    });
+  }
+
+  let css = null;
+  const allAssets = new Map(jsAssets);
+  if (ownCss.length) {
+    const r = await processCss({ fileSystem, cssFiles: ownCss, scopeClass: full, engine, mode });
+    css = r.css;
+    for (const [out, src] of r.assets) allAssets.set(out, src);
+  }
+
+  // entity descriptor: id + reference + assets (css is injected, the rest is preload) +
+  // graph edges; css dependencies are appended by build() (known only after the partition)
+  const descriptor = {
+    id: full,
+    reference: {
+      namespace: mod.namespace,
+      name: mod.name,
+      type: mod.type,
+      version: mod.version,
+    },
+    assets: [...(css ? [`${full}.css`] : []), ...allAssets.keys()],
+    dependencies: imports, // version-qualified full-ids (declared intent)
+    // A PAGE ROOT is a component facet only by file type: it takes the page's tree as a prop,
+    // it is what `page.reference` names, and it can never be someone's child — so the editor
+    // must not offer it as a block to place. Read off the import the facet actually made:
+    // the binding is emitted as a property access on the imported namespace, which survives
+    // minification (property names are not renamed), and merely importing the definer IS the
+    // declaration. Absent rather than false — descriptors stay free of noise.
+    ...(ROOT_DEFINER_RE.test(code) ? { isRoot: true } : {}),
+    // an INTERNAL block (a tool's own — an editor panel, the editor's fallback): placed by the
+    // platform's pages, never offered to an author. The same reading, off the marker the facet
+    // imported — a wrapper over any definer, so a fallback is marked the way a component is
+    ...(INTERNAL_MARK_RE.test(code) ? { internal: true } : {}),
+  };
+
+  return { full, descriptor, jsCode: code, map, css, sharedCss, assets: allAssets, watchFiles, rawImports };
+}
+
+/** how `import { defineRootComponentSide } from '@mosetta/react'` looks once bundled */
+const ROOT_DEFINER_RE = /\.defineRootComponentSide\b/;
+/** …and `markInternalTile(...)` — a block the picker leaves out */
+const INTERNAL_MARK_RE = /\.markInternalTile\b/;
+
+const VIRTUAL_PROLOG = '\0mosetta-loader-prolog-entry';
+
+// identical across modules, roots and rebuilds — built once per mode, but VALIDATED by the
+// mtimes of its own source graph: the dev server process is long-lived, and a checkout (or
+// framework-source edit in this repo) must not keep serving a stale prolog until restart
+let prologCache = null; // { mode, jsCode, watchFiles, stamp }
+
+/**
+ * The loader PROLOG: the idempotent resolver installation
+ * (`installResolverFromPage()`) bundled as a self-contained IIFE. build() concatenates it after
+ * `systemjs + named-register` into the `system.js` co-located with every script facet — the
+ * prolog runs before any `systemjs-module` entry is processed, so the resolve hook is always
+ * installed first.
+ */
+export async function buildLoaderProlog(fileSystem, { resolver, mode = 'development', buildConfig = null, engine } = {}) {
+  if (prologCache && prologCache.mode === mode
+    && prologCache.configStamp === (buildConfig?.stamp ?? 'none')
+    && mtimeStamp(fileSystem, prologCache.watchFiles) === prologCache.stamp) return prologCache;
+  // livereload is BUILD knowledge: the dev prolog itself listens to the provider's SSE
+  // (the dev provider's /__mosetta__/reload endpoint, base — from the envelope), prod is clean
+  // by construction; the cross-cutting machinery (runner/env/shells) knows nothing about dev
+  // mode. The guard — one subscription per realm (as many prologs as script facets).
+  // The page's dev companions: SSE reload and the ERROR OVERLAY. The overlay lives here rather
+  // than as a distributive module precisely because it is needed when the build is BROKEN: there
+  // are no new artifacts, yet the prolog arrived with the last successful build and keeps
+  // working. The status sits next to the artifact tree and survives a build failure.
+  // ONE connection per ORIGIN, not per realm. A browser gives an origin about six sockets and
+  // SHARES them across tabs; an EventSource holds one of them for its whole life. The editor
+  // alone is three realms (the page plus a preview frame per canvas), so two open tabs used to
+  // pin six permanent subscriptions and the origin ran dry — a sibling frame's document could
+  // then never load (a gray canvas, an eternal spinner). So: whoever wins the web lock talks to
+  // the server and fans the news out over a BroadcastChannel; every other realm only listens.
+  const livereloadSnippet = mode === 'development'
+    ? 'try {\n'
+      + '  if (!globalThis.__mosettaReload) {\n'
+      + '    globalThis.__mosettaReload = true;\n'
+      + '    var show = function (status) {\n'
+      + "      var id = 'mosetta-dev-overlay';\n"
+      + '      var node = document.getElementById(id);\n'
+      + '      var broken = status && status.ok === false;\n'
+      + '      if (!broken) { if (node) node.remove(); return; }\n'
+      + '      if (globalThis.__mosettaOverlayHidden === status.stamp) return;\n'
+      + "      if (!node) { node = document.createElement('div'); node.id = id; document.body.appendChild(node); }\n"
+      + "      node.setAttribute('style', 'position:fixed;inset:0;z-index:2147483647;overflow:auto;"
+      + "background:rgba(20,20,24,.96);color:#f5f5f5;font:12px/1.5 ui-monospace,monospace;padding:24px');\n"
+      + "      var parts = [];\n"
+      + "      if (status.build) parts.push('<b style=\"color:#ff8080\">Build failed</b>\\n\\n' + esc(status.build));\n"
+      + "      if (status.typescript) parts.push('<b style=\"color:#ffd280\">Type errors</b>\\n\\n' + esc(status.typescript));\n"
+      + "      node.innerHTML = '<button style=\"position:sticky;top:0;float:right;cursor:pointer\">close</button>"
+      + "<pre style=\"white-space:pre-wrap;margin:0\">' + parts.join('\\n\\n') + '</pre>';\n"
+      + "      node.querySelector('button').onclick = function () {\n"
+      + '        globalThis.__mosettaOverlayHidden = status.stamp;\n'
+      + '        node.remove();\n'
+      + '      };\n'
+      + '    };\n'
+      + "    var esc = function (s) { return String(s).replace(/[&<>]/g, function (c) { return ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]; }); };\n"
+      // the fan-out: news reaches every realm of the origin over the channel, so only the realm
+      // holding the lock ever opens a socket. A late-arriving realm asks for the last status
+      // instead of fetching it (`ask`), and the leader answers off its own memory
+      + "    var chan = typeof BroadcastChannel === 'function' ? new BroadcastChannel('mosetta-dev') : null;\n"
+      + '    var leading = false;\n'
+      + '    var last = null;\n'
+      + '    var apply = function (msg) {\n'
+      + '      if (msg.reload) { location.reload(); return; }\n'
+      + '      show(msg.status);\n'
+      + '    };\n'
+      + '    var tell = function (msg) {\n'
+      + '      if (chan) chan.postMessage({ mosetta: true, reload: msg.reload, status: msg.status });\n'
+      + '      apply(msg);\n'
+      + '    };\n'
+      + '    if (chan) chan.onmessage = function (e) {\n'
+      + '      var msg = e.data;\n'
+      + '      if (!msg || !msg.mosetta) return;\n'
+      + '      if (msg.ask) {\n'
+      + '        if (leading && last) chan.postMessage({ mosetta: true, status: last });\n'
+      + '        return;\n'
+      + '      }\n'
+      + '      apply(msg);\n'
+      + '    };\n'
+      // ONE stream, no polling: the build status rides the same SSE (`event: status`, sent on
+      // connect and then on every change), so the browser never spends a second socket — and
+      // never learns about a broken build a whole second late either
+      + '    var lead = function () {\n'
+      + '      leading = true;\n'
+      + "      var src = new EventSource(new URL('__mosetta__/reload', base).href);\n"
+      + '      src.onmessage = function (e) {\n'
+      + "        if (e.data === 'reload') tell({ reload: true });\n"
+      + '      };\n'
+      + "      src.addEventListener('status', function (e) {\n"
+      + '        var status = null;\n'
+      + '        try { status = JSON.parse(e.data); } catch (err) { return; }\n'
+      + '        last = status;\n'
+      + '        tell({ status: status });\n'
+      + '      });\n'
+      + '    };\n'
+      // the lock is held for the life of the realm and released by the browser when the realm
+      // dies, so a closed (or reloaded) leader hands the connection to the next realm by itself.
+      // Without a channel there is nobody to fan out to, and without locks nobody to elect —
+      // then every realm speaks for itself, as it did before
+      + "    var locks = typeof navigator === 'object' && navigator ? navigator.locks : null;\n"
+      + '    if (chan && locks && typeof locks.request === "function") {\n'
+      + "      locks.request('mosetta-dev-channel', function () {\n"
+      + '        lead();\n'
+      + '        return new Promise(function () {});\n'
+      + '      }).catch(function () { if (!leading) lead(); });\n'
+      + '      chan.postMessage({ mosetta: true, ask: true });\n'
+      + '    } else {\n'
+      + '      lead();\n'
+      + '    }\n'
+      + '  }\n'
+      + '} catch (e) { /* dev-only, optional */ }\n'
+    : '';
+  const bootstrapEntry = resolver.resolveFramework('@mosetta/runtime/bootstrap');
+  const source =
+    `import { installResolverFromPage } from ${JSON.stringify(bootstrapEntry)};\n`
+    + `const { base } = installResolverFromPage();\n${livereloadSnippet}`;
+  const bundle = await engine.rollup({
+    input: VIRTUAL_PROLOG,
+    plugins: [
+      {
+        name: 'mosetta-loader-prolog',
+        resolveId: (id) => (id === VIRTUAL_PROLOG ? id : null),
+        load: (id) => (id === VIRTUAL_PROLOG ? source : null),
+      },
+      ...userPluginsFor(buildConfig, 'prolog', mode),
+      defineEnv(mode),
+      portResolve(fileSystem, resolver, path.dirname(bootstrapEntry)),
+      commonjs(),
+      transformTs(engine),
+    ],
+    onwarn(w, warn) {
+      if (w.code === 'CIRCULAR_DEPENDENCY') return;
+      warn(w);
+    },
+  });
+  const { output } = await bundle.generate({
+    format: 'iife', name: 'mosettaLoaderProlog', plugins: mode === 'production' ? [minifyChunk(engine)] : [],
+  });
+  const watchFiles = bundle.watchFiles.slice();
+  // the GENERATOR is part of the prolog's graph: the livereload/overlay snippet is authored
+  // right here as a string, invisible to rollup — without this line an edit to it would keep
+  // serving stale cached prologs (in-memory AND on-disk) until the cache is wiped by hand.
+  // Non-file realms (an in-browser build) skip it: a missing path stamps as a constant.
+  if (import.meta.url.startsWith('file:')) watchFiles.push(new URL(import.meta.url).pathname);
+  await bundle.close();
+  prologCache = {
+    mode,
+    jsCode: output.find((o) => o.type === 'chunk').code,
+    watchFiles,
+    stamp: mtimeStamp(fileSystem, watchFiles),
+    configStamp: buildConfig?.stamp ?? 'none',
+  };
+  return prologCache;
+}
+

package/src/buildServer.mjs

@@ -0,0 +1,155 @@
+import { path } from './nodeApi.mjs';
+import { fullTileName } from './moduleName.mjs';
+import { portResolveEsbuild } from './plugins/portResolveEsbuild.mjs';
+import { monolithCompat, monolithCompatOptions } from './plugins/monolithCompat.mjs';
+import { MONOLITH_CONDITIONS } from './conditions.mjs';
+import { mtimeStamp } from './artifactCache.mjs';
+
+// Private monoliths are built by esbuild (self-contained ESM, everything inside), but it no
+// longer resolves BY ITSELF — all I/O goes through the port via `portResolveEsbuild`, and the
+// engine itself is injected from outside (`engine.bundle`). `absWorkingDir` is pinned to the
+// distributive root: esbuild bakes the path into module identity (`__commonJS` keys, comments),
+// and without pinning the shape depends on the working directory — engines diverge and the
+// build stops being reproducible.
+// `frameworkDir` — the directory GENERATED facets resolve their imports from (the default
+// the generated ssr default is built from a string source, which imports framework packages,
+// `@mosetta/server` and react). It used to be derived from `import.meta.url` — and that broke
+// exactly like the `fileSystem`/`engine` defaults did: the binding came from the CODE's location
+// instead of being supplied from outside, and did not survive bundling into an isolate.
+const portOptions = (fileSystem, resolver, sourceBase, frameworkDir, wasmAssets = null, watched = null) => ({
+  plugins: [
+    ...(wasmAssets ? [wasmAssetsPlugin(resolver, frameworkDir, wasmAssets)] : []),
+    // workerd compatibility — BEFORE the port resolver: package substitutions and onLoad patches
+    // must fire before the port resolves/reads the files itself
+    monolithCompat(fileSystem, resolver),
+    portResolveEsbuild(fileSystem, resolver, frameworkDir, MONOLITH_CONDITIONS, watched),
+  ],
+  ...monolithCompatOptions(),
+  ...(sourceBase ? { absWorkingDir: sourceBase } : {}),
+});
+
+// Wasm assets of a server facet: a `*.wasm` import is NOT bundled — runtime wasm compilation is
+// forbidden in workerd, an engine can only exist as a declared bundle module. The import
+// resolves to a file, the file travels as an asset next to the monolith (and into
+// descriptor.assets — the runner puts it into the bundle as `{ wasm }`), while the code keeps
+// `./<name>.wasm` — exactly the specifier the runner will declare the module under. Placed
+// FIRST in the chain: otherwise the port resolver would resolve .wasm to a path and esbuild
+// would try to read it as js.
+function wasmAssetsPlugin(resolver, frameworkDir, collected) {
+  return {
+    name: 'mosetta-wasm-assets',
+    setup(build) {
+      build.onResolve({ filter: /\.wasm$/ }, (args) => {
+        const fromDir = args.resolveDir || frameworkDir;
+        const file = resolver.resolve(args.path, fromDir, MONOLITH_CONDITIONS);
+        const name = file.slice(file.lastIndexOf('/') + 1);
+        const known = collected.get(name);
+        if (known && known !== file) {
+          throw new Error(`wasm assets with the same name: ${name} (${known} and ${file})`);
+        }
+        collected.set(name, file);
+        return { path: `./${name}`, external: true };
+      });
+    },
+  };
+}
+
+// server artifacts get EXTERNAL maps in every mode: they live in a private store, so
+// the map sits right next to them (writeJs appends the co-located sourceMappingURL). esbuild with
+// write:false emits two virtual files — pick them apart. `outdir` only shapes the virtual paths.
+const SOURCEMAP = { sourcemap: 'external', outdir: '.' };
+const pickOutputs = (result) => ({
+  jsCode: result.outputFiles.find((f) => !f.path.endsWith('.map')).text,
+  map: result.outputFiles.find((f) => f.path.endsWith('.map'))?.text ?? null,
+});
+
+// Build a server-action module into a SELF-CONTAINED monolith. Unlike client modules
+// (Rollup → SystemJS, deps externalized for singleton sharing), a server module runs alone in a Worker
+// Loader isolate — no sharing concern — so we bundle EVERYTHING in (`external: []`) into one ESM. Web
+// API only (`platform: 'neutral'`) → runs unchanged in the workerd isolate. The coder authors
+// `export default defineServerSide({ services })`; the monolith re-exports `module`,
+// which the static Worker-Loader glue imports.
+// user hook: transforms the composed esbuild options of a server-side monolith build
+function applyServerHook(buildConfig, options, target, mode) {
+  return buildConfig?.serverEsbuild?.(options, { target, mode }) ?? options;
+}
+
+export async function buildServerModule(fileSystem, { file, name, type, namespace, version }, { resolver, mode = 'development', buildConfig = null, engine, sourceBase, frameworkDir } = {}) {
+  const full = fullTileName({ namespace, type, name, version });
+  const wasmAssets = new Map(); // asset name -> absolute source file
+  const watched = new Set(); // the monolith's source graph — for invalidation and watching
+  const result = await engine.bundle(applyServerHook(buildConfig, {
+    ...portOptions(fileSystem, resolver, sourceBase, frameworkDir, wasmAssets, watched),
+    entryPoints: [file],
+    bundle: true,
+    format: 'esm',
+    platform: 'neutral',
+    target: 'es2022',
+    write: false,
+    minify: mode === 'production',
+    logLevel: 'silent', // the caller reports a concise warn-skip on failure; suppress esbuild's own dump
+    ...SOURCEMAP,
+    tsconfigRaw: { compilerOptions: { experimentalDecorators: true, jsx: 'automatic' } },
+  }, 'server', mode));
+  return { full, wasmAssets, watchFiles: [...watched], ...pickOutputs(result) };
+}
+
+// ---- ssr facet of app modules (the shell is a degenerate SSR case) --------------------------
+
+// The DEFAULT ssr grain: generated when the app module has no <name>.ssr.tsx of its own
+// (convention-with-override). A coder's grain replaces it entirely — that
+// is also where another binding plugs in: the definer lives WITH its binding (@mosetta/react/ssr
+// over the server's engine), so a preact page writes preact's.
+//
+// It resolves from the APP's directory, not the framework's, precisely because of that import:
+// which binding renders a page is the APP's choice, and the app is what has it installed.
+const DEFAULT_SSR_SOURCE = `import { defineSsrSide } from '@mosetta/react/ssr';
+
+export default defineSsrSide();
+`;
+
+// the default bundles react-dom/server — identical across app modules and rebuilds, so memoize
+// (keyed by the build-config stamp too: a serverEsbuild hook edit must not serve a stale default).
+// VALIDATED by its graph's mtime, like the prolog: the dev server lives long, and the default
+// facet is built from the FRAMEWORK's sources — in the monorepo they are hand-edited and must
+// be picked up.
+let defaultSsrCache = null; // { mode, configStamp, jsCode, map, watchFiles, stamp }
+
+export async function buildSsrModule(fileSystem, { file, name, namespace, version }, { resolver, mode = 'development', buildConfig = null, engine, sourceBase, frameworkDir } = {}) {
+  const full = fullTileName({ namespace, type: 'ssr', name, version });
+  const grain = path.join(path.dirname(file), `${name}.ssr.tsx`);
+  const custom = fileSystem.exists(grain);
+
+  const configStamp = buildConfig?.stamp ?? 'none';
+  if (!custom && defaultSsrCache && defaultSsrCache.mode === mode && defaultSsrCache.configStamp === configStamp
+    && mtimeStamp(fileSystem, defaultSsrCache.watchFiles) === defaultSsrCache.stamp) {
+    return {
+      full, custom, jsCode: defaultSsrCache.jsCode, map: defaultSsrCache.map,
+      watchFiles: defaultSsrCache.watchFiles, watchFile: null,
+    };
+  }
+  const watched = new Set();
+  const result = await engine.bundle(applyServerHook(buildConfig, {
+    ...portOptions(fileSystem, resolver, sourceBase, frameworkDir, null, watched),
+    ...(custom
+      ? { entryPoints: [grain] }
+      : { stdin: { contents: DEFAULT_SSR_SOURCE, resolveDir: sourceBase ?? frameworkDir, sourcefile: `${name}.ssr.default.ts`, loader: 'ts' } }),
+    bundle: true,
+    format: 'esm',
+    platform: 'neutral',
+    target: 'es2022',
+    write: false,
+    minify: mode === 'production',
+    logLevel: 'silent',
+    ...SOURCEMAP,
+    // react packages branch on it; workerd has no `process`
+    define: { ...monolithCompatOptions().define, 'process.env.NODE_ENV': JSON.stringify(mode) },
+    tsconfigRaw: { compilerOptions: { jsx: 'automatic' } },
+  }, 'ssr', mode));
+  const { jsCode, map } = pickOutputs(result);
+  const watchFiles = [...watched];
+  if (!custom) {
+    defaultSsrCache = { mode, configStamp, jsCode, map, watchFiles, stamp: mtimeStamp(fileSystem, watchFiles) };
+  }
+  return { full, custom, jsCode, map, watchFiles, watchFile: custom ? grain : null };
+}

package/src/cjsExports.mjs

@@ -0,0 +1,81 @@
+import { path } from './nodeApi.mjs';
+import { parse, init } from 'cjs-module-lexer';
+
+// the lexer's wasm is embedded in the package as base64 (no fetch, no file) — init is one-shot and lazy
+let ready = null;
+function ensureLexer() {
+  if (!ready) ready = init();
+  return ready;
+}
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+// `default` — arrives separately via the facade; `__esModule` is an interop MARKER, not an
+// export: it is set non-enumerable (`Object.defineProperty`), so the old runtime walk never saw it.
+const NOT_AN_EXPORT = new Set(['default', '__esModule']);
+const LEXABLE_EXT = new Set(['.js', '.cjs']);
+const MAX_REEXPORT_DEPTH = 16;
+
+/**
+ * Named exports of a CJS module — by STATIC parsing.
+ *
+ * Needed by the dependency artifact's facade: a cross-artifact
+ * `import { createContext } from 'react'` requires the artifact to serve REAL named exports —
+ * default-based CJS interop loses them at artifact boundaries.
+ *
+ * The list used to be obtained by executing the module (`require(file)` + `Object.keys`).
+ * Parsing the string instead of executing removes three things at once: running foreign code on
+ * the build machine, depending on the node loader, and the last reason to keep `cjsNamedExports`
+ * in the port — the function only needs `readFile` and `resolve`, so it lives OUTSIDE the port
+ * and works with any implementation of it. The lexer is the same `cjs-module-lexer` node itself
+ * uses to determine CJS named exports.
+ *
+ * Returns string[], or null when this is not parseable CJS (ESM, another extension, a syntax
+ * error) — then rollup handles the module natively, as before.
+ */
+export async function cjsNamedExports(fileSystem, resolver, file, fromDir) {
+  if (!LEXABLE_EXT.has(path.extname(file))) return null;
+  await ensureLexer();
+
+  const collected = new Set();
+  const visited = new Set();
+
+  // `module.exports = require('./cjs/react.production.js')` — the form half of real-world npm
+  // lives in: the entry itself exports NOTHING, everything is in the re-export target.
+  const walk = (target, dir, depth) => {
+    if (depth > MAX_REEXPORT_DEPTH || visited.has(target)) return true;
+    visited.add(target);
+
+    let source;
+    try {
+      source = fileSystem.readFile(target, 'utf8');
+    } catch {
+      return false; // file missing / unreadable — treat the parse as failed
+    }
+
+    let parsed;
+    try {
+      parsed = parse(source, target);
+    } catch {
+      return false; // ESM syntax or broken CJS — let rollup decide on its own
+    }
+
+    for (const name of parsed.exports) {
+      if (!NOT_AN_EXPORT.has(name) && IDENTIFIER.test(name)) collected.add(name);
+    }
+
+    const nextDir = path.dirname(target);
+    for (const specifier of parsed.reexports) {
+      let resolved;
+      try {
+        resolved = resolver.resolve(specifier, nextDir);
+      } catch {
+        continue; // unresolvable re-export (conditional/optional) — simply adds no names
+      }
+      if (!LEXABLE_EXT.has(path.extname(resolved))) continue;
+      if (!walk(resolved, nextDir, depth + 1)) return false;
+    }
+    return true;
+  };
+
+  return walk(file, fromDir, 0) ? [...collected] : null;
+}