@mosetta/build 0.0.0-stage → 0.0.10

package/src/build.mjs

@@ -0,0 +1,576 @@
+import { crypto, path } from './nodeApi.mjs';
+import { packageDirOf } from './packageMeta.mjs';
+import { discoverRoots, discoverModulesIn, discoverServerModulesIn, discoverRouterModulesIn, discoverPrefabsIn, discoverPagesIn, readConfig } from './discovery.mjs';
+import { buildModule, buildLoaderProlog } from './buildModules.mjs';
+import { fullTileName } from './moduleName.mjs';
+import { buildServerModule, buildSsrModule } from './buildServer.mjs';
+import { buildDependency } from './buildDependencies.mjs';
+import { resolveSpecifier, dependencyFullId } from './specifiers.mjs';
+import { cjsNamedExports } from './cjsExports.mjs';
+import { processCss } from './css.mjs';
+import { INERT_BUILD_CONFIG } from './buildConfig.mjs';
+import { formatBytes } from './format.mjs';
+import { mtimeStamp } from './artifactCache.mjs';
+import { describeSettings, SETTINGS_SUFFIX } from './settings.mjs';
+
+// entry barrel `.`: exposes the build itself and the size formatter for the host's report
+export { formatBytes };
+export { INERT_BUILD_CONFIG } from './buildConfig.mjs';
+
+// core + the named-register extra: artifacts are NAMED System.register('<full-id>', …) bundles
+// (SSR epic stage 1) — the extra links a URL load to its name (one instance both ways).
+// Read THROUGH THE PORT and lazily: importing the build module must not touch the disk by itself.
+let systemjsCache = null;
+function readSystemjs(fileSystem, resolver) {
+  if (!systemjsCache) {
+    systemjsCache = `${fileSystem.readFile(resolver.resolveFramework('systemjs/dist/system.js'), 'utf8')}\n${
+      fileSystem.readFile(resolver.resolveFramework('systemjs/dist/extras/named-register.js'), 'utf8')}`;
+  }
+  return systemjsCache;
+}
+
+// Distributive layout: the in-memory FS (and any disk mirror) is split into two top-level
+// namespaces so nothing leaks across the trust boundary on deploy:
+//   public/   — client-facing static (modules + co-located loaders, deps, prefabs, pages, manifests).
+//               Its CONTENTS are what a CDN serves at its root; the dev provider serves it at `/`.
+//   private/  — server-only artifacts (server-action monoliths, later server info). Never public;
+//               the render worker reaches it via the private channel (dev `/private`, prod S3).
+// The internal structure inside `public/` is unchanged — only the top-level folder is new.
+const PUB = 'public';
+
+// Snapshot of the artifact tree — IN MEMORY ONLY. Disk mirroring is deliberately ABSENT here:
+// the build writes nothing, the snapshot is returned by value, and what to do with it is the
+// caller's decision. This is not tidiness but a property: the port stays read-only, and the
+// build isolate has no write capability at all.
+class OutputFS {
+  constructor() {
+    this.files = new Map(); // relPath -> content
+  }
+  set(rel, content) {
+    this.files.set(rel, content);
+  }
+  get(rel) {
+    return this.files.get(rel);
+  }
+}
+
+/**
+ * Full build of a distributive into an in-memory artifact-tree snapshot.
+ * Returns { fs, prefabs, pages, watchFiles, watchDirs, report }.
+ *
+ * The function READS through the port and mutates nothing: no writes, no execution
+ * (`mosetta.build.mjs` arrives already loaded — `buildConfig`; the blocks' settings schemas are run
+ * by `evaluate`, the host's, when it gives one). `fileSystem`, `engine`, `log`, `frameworkDir`
+ * have no defaults on purpose: the environment binding is supplied from outside, otherwise a
+ * default would quietly pull node back into portable code.
+ *
+ * `released` — the ids already in the catalog the build goes into (a platform builds into its
+ * own): a library root whose distribution is there and a published package that is there are not
+ * built again. Absent — everything is built, as a local build does.
+ */
+export async function build(root, { mode = 'development', log, fileSystem, resolver, engine, frameworkDir, buildConfig = INERT_BUILD_CONFIG, cache = null, evaluate = null, released = null }) {
+  const out = new OutputFS();
+  const watchFiles = new Set();
+  const addWatch = (arr) => arr.forEach((f) => watchFiles.add(f));
+  // The cross-iteration artifact cache (`artifactCache.mjs`) is an ENVIRONMENT concern, like the
+  // port and the engine: the long-lived dev server passes one, a one-shot prod build passes
+  // nothing and builds everything.
+  const memo = cache
+    ? (key, produce, filesOf) => cache.memo(key, produce, filesOf)
+    : (key, produce) => produce();
+
+  // Sourcemap rule: a JS artifact's map lives in the PRIVATE counterpart of its store
+  // at the same relative path (public/ → private/, content-public/ → content-private/); the public
+  // js carries NO sourceMappingURL — the pairing is convention, the dev server surfaces it via the
+  // SourceMap response header. Artifacts already in a private zone keep the map NEXT to them, with
+  // the co-located comment (nothing leaks — the whole zone is behind the trust boundary).
+  const MAP_ZONES = [['public/', 'private/'], ['content-public/', 'content-private/']];
+  // the bundlers stamp their own chunk-named comment — normalize it away, writeJs owns the linkage
+  const stripMapComment = (code) => code.replace(/\n?\/\/# sourceMappingURL=\S*\s*$/, '\n');
+  const writeJs = (rel, code, map) => {
+    if (!map) {
+      out.set(rel, code);
+      return;
+    }
+    const zone = MAP_ZONES.find(([pub]) => rel.startsWith(pub));
+    if (zone) {
+      out.set(rel, stripMapComment(code));
+      out.set(`${zone[1]}${rel.slice(zone[0].length)}.map`, map);
+    } else {
+      out.set(rel, `${stripMapComment(code)}//# sourceMappingURL=${path.basename(rel)}.map\n`);
+      out.set(`${rel}.map`, map);
+    }
+  };
+
+  // SRI hash of the artifact's SERVED bytes: computed after emission (writeJs strips the map
+  // comment for the public zone — we hash exactly what goes over the wire)
+  const sriOf = (rel) => `sha256-${crypto.createHash('sha256').update(out.get(rel)).digest('base64')}`;
+
+  // 1) distributive roots (app + libraries; devLibraries only outside production) → modules
+  const roots = discoverRoots(fileSystem, root, { resolver, includeDev: mode !== 'production', log });
+  // ALREADY RELEASED where this build goes (`released` — the ids of the target's catalog): a library
+  // whose distribution is there at this version is there whole — its blocks, facets, server modules
+  // and prefabs — and is not built again. The app itself always builds.
+  const releasedRoot = (r) => r.dir !== root && !!released?.has(fullTileName({ namespace: r.namespace, type: 'distribution', name: r.namespace, version: r.version }));
+  const builtRoots = roots.filter((r) => !releasedRoot(r));
+  const mods = builtRoots.flatMap((r) => discoverModulesIn(fileSystem, r));
+  log(`mosetta: ${roots.length} root(s)${builtRoots.length < roots.length ? ` (${roots.length - builtRoots.length} released — not built)` : ''}, ${mods.length} client tile side(s)`);
+  // composition inputs are watched too: mosetta.json (library list), package.json (version feeds
+  // full-ids) of the app and every root, plus the app's content config.json (languages, namespace) —
+  // a checkout or a hand edit that changes ANY of them must trigger a rescan-rebuild, not require
+  // a dev-server restart (chokidar accepts not-yet-existing paths and fires on creation)
+  for (const dir of new Set([root, ...roots.map((r) => r.dir)])) {
+    watchFiles.add(path.join(dir, 'mosetta.json'));
+    watchFiles.add(path.join(dir, 'package.json'));
+  }
+  watchFiles.add(path.join(root, 'config.json'));
+
+  // build-extension hooks: mosetta.build.mjs of the APP root, fresh per build() run
+  // (mtime cache-bust) — an edit of the config is a composition change like any other
+  if (buildConfig.file) watchFiles.add(buildConfig.file);
+  // the data-level knob rides along: extra asset extensions (a custom asset type in
+  // the simple case needs no plugin at all)
+  const assetExtensions = readConfig(fileSystem, root).assetExtensions ?? [];
+
+  // Artifact-cache EPOCH: everything that changes the build as a whole rather than through
+  // individual graph files — mode, config hooks, the package catalog (a reinstall changes
+  // resolution without touching sources) and the composition inputs (mosetta.json/package.json of
+  // the roots, config.json, mosetta.build.mjs itself). An epoch change wipes the cache entirely;
+  // within an epoch artifacts live by the mtime of their graphs.
+  cache?.epoch([mode, buildConfig?.stamp ?? 'none', resolver.stamp, mtimeStamp(fileSystem, [...watchFiles])].join('|'));
+
+  // the loader for script facets: systemjs + named-register + resolver prolog,
+  // co-located into EVERY script facet's folder — a System.register entry is not executable
+  // without the loader, and the module folder gives it a version-qualified (immutable) URL.
+  let loaderJs = null;
+  if (mods.some((m) => m.type === 'script')) {
+    const prolog = await buildLoaderProlog(fileSystem, { resolver, mode, buildConfig, engine, sourceBase: root });
+    addWatch(prolog.watchFiles);
+    loaderJs = `${readSystemjs(fileSystem, resolver)}\n${prolog.jsCode}`;
+  }
+
+  // catalog of LOGICAL artifacts for the report (renderBuildReport): distributive → module → facets
+  const catalog = new Map(); // ns -> { version, modules: Map(name -> [{facet, bytes, info}]) }
+  const record = ({ namespace, version, name }, facet, bytes, info = '') => {
+    const dist = catalog.get(namespace) ?? { version, modules: new Map() };
+    catalog.set(namespace, dist);
+    const facets = dist.modules.get(name) ?? [];
+    dist.modules.set(name, facets);
+    facets.push({ facet, bytes, info });
+  };
+
+  // dependency css: one shared UNscoped artifact per closure (identity — the dependency-artifact
+  // formula); delivery goes through the catalog graph
+  const sharedCssArtifacts = new Map(); // cssFull -> {file, specifier, version}
+  const entityDescriptors = []; // descriptors of PACKAGE entities (deps + css) for the aggregate
+
+  const moduleResults = [];
+  let skippedSettings = 0;
+  for (const m of mods) {
+    const cached = await memo(`module:${fullTileName(m)}`,
+      () => buildModule(fileSystem, m, { resolver, mode, buildConfig, engine, sourceBase: root, assetExtensions }));
+    // the descriptor below gets AUGMENTED (edges to css entities, integrity) — the cached object
+    // must stay untouched, otherwise edits would accumulate from iteration to iteration
+    const r = { ...cached, descriptor: { ...cached.descriptor, dependencies: [...cached.descriptor.dependencies] } };
+    moduleResults.push(r);
+    addWatch(r.watchFiles);
+    for (const s of r.sharedCss) {
+      const cssFull = dependencyFullId(s.specifier, s.version);
+      if (!sharedCssArtifacts.has(cssFull)) sharedCssArtifacts.set(cssFull, s);
+      // a css dependency is a graph node: an edge in the importer's descriptor
+      if (!r.descriptor.dependencies.includes(cssFull)) r.descriptor.dependencies.push(cssFull);
+    }
+    writeJs(`${PUB}/modules/${r.full}/${r.full}.js`, r.jsCode, r.map);
+    r.descriptor.integrity = sriOf(`${PUB}/modules/${r.full}/${r.full}.js`);
+    // a block's ICON: `<name>.icon.svg` beside its module — shipped in the module's folder under a
+    // name of its content (a new icon is a new name: no cache keeps the old one) and named by the
+    // descriptor; the pickers show it
+    if (m.type === 'component') {
+      const iconFile = path.join(path.dirname(m.file), `${m.name}.icon.svg`);
+      watchFiles.add(iconFile);
+      if (fileSystem.exists(iconFile)) {
+        const icon = fileSystem.readFile(iconFile);
+        r.descriptor.icon = `${r.full}.icon.${contentHash(icon)}.svg`;
+        out.set(`${PUB}/modules/${r.full}/${r.descriptor.icon}`, icon);
+      }
+      // its SETTINGS: `<name>.settings.ts` beside it — what the block's node keeps, as JSON Schema
+      // in the descriptor (settings.mjs); run by the host, skipped where the host runs nothing
+      const settingsFile = path.join(path.dirname(m.file), `${m.name}${SETTINGS_SUFFIX}`);
+      watchFiles.add(settingsFile);
+      if (fileSystem.exists(settingsFile)) {
+        if (evaluate) {
+          const described = await memo(`settings:${r.full}`,
+            () => describeSettings(fileSystem, settingsFile, { resolver, engine, evaluate, frameworkDir, sourceBase: root }));
+          addWatch(described.watchFiles);
+          r.descriptor.settings = described.schema;
+        } else {
+          skippedSettings++;
+        }
+      }
+    }
+    out.set(`${PUB}/modules/${r.full}/${r.full}.json`, JSON.stringify(r.descriptor, null, 2));
+    if (r.css) out.set(`${PUB}/modules/${r.full}/${r.full}.css`, r.css);
+    if (m.type === 'script') out.set(`${PUB}/modules/${r.full}/system.js`, loaderJs);
+    let assetBytes = 0;
+    for (const [outName, srcAbs] of r.assets) {
+      const content = fileSystem.readFile(srcAbs);
+      out.set(`${PUB}/modules/${r.full}/${outName}`, content);
+      assetBytes += content.length;
+    }
+    record(m, m.type, r.jsCode.length, r.assets.size ? `${r.assets.size} asset(s) ${formatBytes(assetBytes)}` : '');
+    // css gets its own row right under its facet (and honestly counts into the distributive total)
+    if (r.css) record(m, 'css', r.css.length);
+  }
+  if (skippedSettings) log(`mosetta: ${skippedSettings} settings schema(s) not read — this environment runs no code at build time`);
+
+  // 2) — the ROOT-LEVEL runtime files (bootstrap.js/system.js and their content-public copies)
+  // are GONE: the loader ships co-located with script facets (§ above), the
+  // bootstrap logic lives in @mosetta/runtime shipped as an ordinary dependency artifact.
+
+  // 3) dependency closure — keyed by version-qualified full-id. Specifiers resolve
+  // FROM THE IMPORTER (node semantics): a module's externals from its package, a
+  // dependency's transitives from its own .pnpm neighbourhood — the app manifest no longer
+  // carries foreign transitives (scheduler/dockview/zod-style leaks). Dedup builds by full-id,
+  // so distinct versions of one lib produce distinct artifacts. No import map is emitted: the
+  // runtime resolver derives each URL by formula (modules/<full-id>/<full-id>.js — flat layout).
+  const seen = new Set(); // full-ids already built
+  const queued = new Set(); // importerDir|specifier pairs already enqueued
+  const queue = []; // [specifier, importerDir]
+  const enqueue = (specs, importerDir) => specs.forEach((s) => {
+    const key = `${importerDir}|${s}`;
+    if (!queued.has(key)) {
+      queued.add(key);
+      queue.push([s, importerDir]);
+    }
+  });
+  for (let i = 0; i < mods.length; i++) enqueue(moduleResults[i].rawImports, path.dirname(mods[i].file));
+
+  let depCount = 0;
+  let releasedDeps = 0;
+  const depRows = []; // {specifier, version, bytes} — for the dependency-artifact report
+  while (queue.length) {
+    const [specifier, importerDir] = queue.shift();
+    const resolved = resolveSpecifier(fileSystem, resolver, specifier, importerDir, log);
+    if (!resolved) continue;
+    const { full, resolvedFile, kind, version } = resolved;
+    if (seen.has(full)) continue;
+    seen.add(full);
+    // a PUBLISHED package already released where this build goes is there with everything it
+    // imports (released together with it): neither it nor its closure is built again. A package of
+    // the distribution's own sources always is — new bytes under its version must be seen
+    if (released?.has(full) && fileSystem.realPath(resolvedFile).split(/[\\/]/).includes('node_modules')) {
+      releasedDeps++;
+      continue;
+    }
+
+    // a dependency artifact is cached together with its cjs-export scan: both read the same
+    // package files and only change together with them
+    const res = await memo(`dep:${full}`, async () => {
+      const namedExports = kind === 'builtin' ? null : await cjsNamedExports(fileSystem, resolver, resolvedFile, importerDir);
+      return buildDependency(fileSystem, { resolver, specifier, resolvedFile, full, namedExports, mode, buildConfig, engine, sourceBase: root });
+    });
+    addWatch(res.watchFiles);
+    writeJs(`${PUB}/modules/${full}/${full}.js`, res.jsCode, res.map);
+    const depVersion = version;
+    const depDescriptor = {
+      id: full,
+      reference: { type: 'package', specifier, version: depVersion },
+      assets: [],
+      dependencies: res.imports,
+      integrity: sriOf(`${PUB}/modules/${full}/${full}.js`),
+      // built from the distribution's OWN sources (a workspace package), not a published one: new
+      // bytes under its version are a change that needs a new version — a published package's
+      // bytes may differ by build tooling alone, and its first deployed copy stands (deploy.mjs)
+      ...(fileSystem.realPath(resolvedFile).split(/[\\/]/).includes('node_modules') ? {} : { local: true }),
+    };
+    out.set(`${PUB}/modules/${full}/${full}.json`, JSON.stringify(depDescriptor, null, 2));
+    entityDescriptors.push(depDescriptor);
+    depRows.push({ specifier, version: depVersion, bytes: res.jsCode.length });
+    // this artifact's own imports resolve from ITS package next
+    enqueue(res.rawImports, packageDirOf(fileSystem, resolvedFile) ?? path.dirname(resolvedFile));
+    depCount++;
+  }
+
+  // 3b) css entities: a shared UNscoped css artifact is a full catalog entity
+  // (folder: css + url() assets + descriptor, no JS facet)
+  for (const [cssFull, s] of sharedCssArtifacts) {
+    if (released?.has(cssFull)) continue; // released with the package it comes from
+    // a dependency's css entity is the file itself plus its url() assets; there is no graph here,
+    // so we assemble the watched set ourselves (otherwise editing an image would not change its
+    // hash-based name)
+    const { css, assets: cssAssets } = await memo(`css:${cssFull}`,
+      async () => {
+        const r = await processCss({ fileSystem, cssFiles: [s.file], scopeClass: null, engine, mode });
+        return { ...r, watchFiles: [s.file, ...r.assets.values()] };
+      });
+    out.set(`${PUB}/modules/${cssFull}/${cssFull}.css`, css);
+    for (const [outName, srcAbs] of cssAssets) {
+      out.set(`${PUB}/modules/${cssFull}/${outName}`, fileSystem.readFile(srcAbs));
+    }
+    const cssDescriptor = {
+      id: cssFull,
+      // type 'css' (not 'package'): the entity has no JS facet — preloader/linking tell these apart
+      reference: { type: 'css', specifier: s.specifier, version: s.version },
+      assets: [`${cssFull}.css`, ...cssAssets.keys()],
+      dependencies: [],
+      integrity: sriOf(`${PUB}/modules/${cssFull}/${cssFull}.css`),
+    };
+    out.set(`${PUB}/modules/${cssFull}/${cssFull}.json`, JSON.stringify(cssDescriptor, null, 2));
+    entityDescriptors.push(cssDescriptor);
+    watchFiles.add(s.file);
+    depRows.push({ specifier: `${s.specifier} (css)`, version: s.version, bytes: css.length });
+  }
+
+  // 3c) DISTRIBUTIONS name themselves: one entity per root that brings blocks or prefabs — its
+  // title, description, icon, cover and where its source lives. The descriptor is the root's
+  // mosetta.json; the description falls back to package.json's, the source to its `repository`
+  // (url + directory). Files ship in the entity's folder under names of their content.
+  for (const r of builtRoots) {
+    // the APP's own prefabs are its site's content (the picker's "prefabs of this site"), not a
+    // distribution: the app counts only for blocks of its own
+    const brings = mods.some((m) => m.namespace === r.namespace)
+      || (r.dir !== root && discoverPrefabsIn(fileSystem, r.dir, () => {}).length > 0);
+    if (!brings) continue;
+    const descriptor = distributionDescriptor(fileSystem, r, (key, file) => {
+      watchFiles.add(file);
+      if (!fileSystem.exists(file)) {
+        log(`  ! ${r.namespace}: its ${key} ${path.relative(r.dir, file)} is not there — skipped`);
+        return null;
+      }
+      const bytes = fileSystem.readFile(file);
+      const name = `${key}.${contentHash(bytes)}${path.extname(file)}`;
+      out.set(`${PUB}/modules/${fullTileName({ namespace: r.namespace, type: 'distribution', name: r.namespace, version: r.version })}/${name}`, bytes);
+      return name;
+    });
+    out.set(`${PUB}/modules/${descriptor.id}/${descriptor.id}.json`, JSON.stringify(descriptor, null, 2));
+    entityDescriptors.push(descriptor);
+  }
+
+  // 4) manifests + prefabs (namespaces.json is dead — namespaces derive from the catalog).
+  // scripts.json/styles.json/dependencies.json are dead — their roles are carried by the catalog
+  // below. The unified entity catalog: an aggregate of ALL public descriptors of the provider —
+  // modules + package entities (deps, css). Replaces scripts.json / styles.json /
+  // dependencies.json: a script facet's presence = a `_t_script_` entity in the catalog, css
+  // lives in the entity's assets, the graph is the descriptor edges. One fetch for
+  // shell/runner/editor.
+  // prefabs = reusable templates (all roots); pages = routed/servable trees (app root only — they are
+  // the application's pages, not a library's). Both stored per-file; the render path reads PAGES.
+  // a prefab is filed under its AUTHOR — the root's namespace — so two libraries may name theirs
+  // alike; a page embeds one as `_ns_<namespace>_t_prefab_n_<name>_v_live`
+  const prefabs = builtRoots.flatMap((r) => discoverPrefabsIn(fileSystem, r.dir, log).map((p) => ({ ...p, namespace: r.namespace, library: r.dir !== root, version: r.version })));
+  // a library's prefab is LIVE — taken at its current form wherever it is placed — and it names the
+  // blocks of the distributions built with it at the versions they are built at now, whatever
+  // version its file was written at
+  const builtVersions = new Map(roots.map((r) => [r.namespace, r.version]));
+  for (const p of prefabs) out.set(`${PUB}/prefabs/${p.namespace}/${p.name}.json`, JSON.stringify(atBuiltVersions(p.json, builtVersions), null, 2));
+  // …and the catalog names it, so the editor can offer it beside its distribution's blocks
+  for (const p of prefabs.filter((q) => q.library)) {
+    entityDescriptors.push({
+      id: fullTileName({ namespace: p.namespace, type: 'prefab', name: p.name, version: p.version }),
+      reference: { namespace: p.namespace, name: p.name, type: 'prefab', version: p.version },
+      assets: [],
+      dependencies: [],
+    });
+  }
+
+  const entityCatalog = [...moduleResults.map((r) => r.descriptor), ...entityDescriptors];
+  out.set(`${PUB}/modules.json`, JSON.stringify(entityCatalog, null, 2));
+  const pages = discoverPagesIn(fileSystem, root, log);
+  for (const pg of pages) out.set(`${PUB}/pages/${pg.name}.json`, JSON.stringify(pg.json, null, 2));
+
+  // 5) server-action modules → PRIVATE monoliths: one self-contained ESM per module, run
+  // in a Worker Loader isolate; not client artifacts, not split into deps. Legacy @mosetta/* server
+  // modules can't bundle for Web API yet (node builtins) → each is warn-skipped (not silently dropped)
+  // until the framework is consolidated into @mosetta/server-action.
+  //
+  // PRIVATE CATALOG: private entities carry the same descriptors as public ones:
+  // id + reference + assets + dependencies + integrity, a per-entity json next to the monolith
+  // plus the private/modules.json aggregate. This gives the runner the isolate's file list and an
+  // integrity check on delivery, and gives future action assets (wasm build engines) a place to be
+  // declared. dependencies is always [] — a monolith is self-contained.
+  const privateDescriptors = [];
+  const recordPrivate = (full, reference, extra = {}, moreAssets = []) => {
+    const base = `private/modules/${full}`;
+    const descriptor = {
+      id: full,
+      reference,
+      assets: [...moreAssets, ...(out.get(`${base}/${full}.js.map`) ? [`${full}.js.map`] : [])],
+      dependencies: [],
+      integrity: sriOf(`${base}/${full}.js`),
+      ...extra,
+    };
+    out.set(`${base}/${full}.json`, JSON.stringify(descriptor, null, 2));
+    privateDescriptors.push(descriptor);
+  };
+  const serverMods = builtRoots.flatMap((r) => discoverServerModulesIn(fileSystem, r));
+  let serverCount = 0;
+  for (const sm of serverMods) {
+    try {
+      const s = await memo(`server:${fullTileName(sm)}`,
+        () => buildServerModule(fileSystem, sm, { resolver, mode, buildConfig, engine, sourceBase: root, frameworkDir }));
+      addWatch(s.watchFiles);
+      writeJs(`private/modules/${s.full}/${s.full}.js`, s.jsCode, s.map);
+      // the facet's wasm imports travel as assets next to the monolith: the runner will declare
+      // them as bundle modules under the same relative names
+      for (const [assetName, srcFile] of s.wasmAssets) {
+        out.set(`private/modules/${s.full}/${assetName}`, fileSystem.readFile(srcFile));
+      }
+      recordPrivate(s.full, { namespace: sm.namespace, name: sm.name, type: 'server', version: sm.version },
+        {}, [...s.wasmAssets.keys()]);
+      record(sm, 'server', s.jsCode.length, 'private'
+        + (s.wasmAssets.size ? `, ${s.wasmAssets.size} wasm asset(s)` : ''));
+      serverCount++;
+    } catch (e) {
+      log(`  ! server side ${sm.name}@${sm.namespace} not bundled (${String(e.message || e)})`
+        + ` — skipped; needs @mosetta/server-action Web-API port`);
+    }
+  }
+  // no glue artifacts anymore: the UNIVERSAL glue is embedded in the runner and
+  // composed with every isolate — monoliths carry their aspects themselves.
+
+  // 6) there is NO router (ADR-0053): the runner dispatches by path and the site isolate routes —
+  // an authored `.router.ts` facet is a mistake to name, not a file to ignore
+  const routerFacets = roots.flatMap((r) => discoverRouterModulesIn(fileSystem, r));
+  if (routerFacets.length) {
+    throw new Error(`mosetta: router sides are no longer built — the site line routes (${routerFacets.map((rm) => path.relative(root, rm.file)).join(', ')})`);
+  }
+
+  // 7) ssr facet per ROOT-CAPABLE module (the shell is a degenerate SSR case): the
+  // coder's <name>.ssr.tsx or the generated react default → private/modules/<full-id>/ —
+  // what the site isolate of its engine runs. Root-capable = component facet + script facet in one module
+  // (the script facet marks root-capability, the default ssr grain is keyed off it;
+  // script-only modules are pure early scripts — nothing to render).
+  let ssrCount = 0;
+  const scriptDirs = new Set(mods.filter((m) => m.type === 'script').map((m) => path.dirname(m.file)));
+  const ssrRoots = mods.filter((m) => m.type === 'component' && scriptDirs.has(path.dirname(m.file)));
+  for (const am of ssrRoots) {
+    const s = await memo(`ssr:${fullTileName(am)}`,
+      () => buildSsrModule(fileSystem, am, { resolver, mode, buildConfig, engine, sourceBase: root, frameworkDir }));
+    if (s.watchFile) watchFiles.add(s.watchFile);
+    addWatch(s.watchFiles);
+    writeJs(`private/modules/${s.full}/${s.full}.js`, s.jsCode, s.map);
+    recordPrivate(s.full, { namespace: am.namespace, name: am.name, type: 'ssr', version: am.version });
+    record(am, 'ssr', s.jsCode.length, s.watchFile ? 'private' : 'private, generated default');
+    ssrCount++;
+  }
+
+  // the private-zone aggregate is the twin of public/modules.json: one fetch
+  // for the runner — composition, integrity, well-known pointers
+  out.set('private/modules.json', JSON.stringify(privateDescriptors, null, 2));
+
+  log(`mosetta: ${moduleResults.length} tile side(s), ${depCount} package tile(s)${releasedDeps ? ` (${releasedDeps} released — not built)` : ''}, ${prefabs.length} prefab(s), ${pages.length} page(s)`
+    + (serverCount ? `, ${serverCount} server monolith(s)` : '')
+    + `, ${ssrCount} ssr`);
+  const watchDirs = [
+    ...roots.flatMap((r) => [path.join(r.dir, 'tiles'), path.join(r.dir, 'prefabs')]),
+    path.join(root, 'pages'),
+  ];
+  const report = {
+    distributions: [...catalog].map(([namespace, d]) => ({
+      namespace,
+      version: d.version,
+      modules: [...d.modules].map(([name, facets]) => ({ name, facets })),
+    })),
+    dependencies: depRows,
+  };
+  return { fs: out, prefabs, pages, watchFiles: [...watchFiles], watchDirs, report };
+}
+
+/** a short name of some bytes' content — what makes a shipped file's name change with it */
+function contentHash(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex').slice(0, 10);
+}
+
+/** a GitHub-like repository field (`git+https://github.com/o/r.git` + directory) as a link to the folder */
+export function sourceLinkOf(repository) {
+  const url = typeof repository === 'string' ? repository : repository?.url;
+  if (typeof url !== 'string') return null;
+  const base = url.replace(/^git\+/, '').replace(/\.git$/, '').replace(/^git@github\.com:/, 'https://github.com/');
+  if (!/^https?:\/\//.test(base)) return null;
+  const directory = typeof repository === 'object' && typeof repository.directory === 'string' ? repository.directory.replace(/^\/+|\/+$/g, '') : '';
+  return directory ? `${base}/tree/HEAD/${directory}` : base;
+}
+
+/**
+ * A distribution's catalog entity: what it calls itself, from its mosetta.json (title,
+ * description, icon, cover, source) with package.json behind the description and the source.
+ * `ship(key, file)` puts a file into the entity's folder and answers its shipped name (null: none).
+ */
+export function distributionDescriptor(fileSystem, root, ship) {
+  const cfg = readConfig(fileSystem, root.dir);
+  let pkg = {};
+  try {
+    pkg = fileSystem.readJson(path.join(root.dir, 'package.json'));
+  } catch { /* a root without package.json names no description or source */ }
+  const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : undefined);
+  const files = {};
+  for (const key of ['icon', 'cover']) {
+    if (typeof cfg[key] !== 'string') continue;
+    const name = ship(key, path.join(root.dir, cfg[key]));
+    if (name) files[key] = name;
+  }
+  const descriptor = {
+    id: fullTileName({ namespace: root.namespace, type: 'distribution', name: root.namespace, version: root.version }),
+    reference: { namespace: root.namespace, name: root.namespace, type: 'distribution', version: root.version },
+    assets: [],
+    dependencies: [],
+    title: text(cfg.title) ?? root.namespace,
+    // a tool's own distribution (the editor): carries no blocks for authors — no card, no switch
+    ...(cfg.internal === true ? { internal: true } : {}),
+    // the distribution others are built on (the UI kit): always connected, no switch
+    ...(cfg.base === true ? { base: true } : {}),
+    ...(text(cfg.description) ?? text(pkg.description) ? { description: text(cfg.description) ?? text(pkg.description) } : {}),
+    ...(text(cfg.source) ?? sourceLinkOf(pkg.repository) ? { source: text(cfg.source) ?? sourceLinkOf(pkg.repository) } : {}),
+    ...(changesOf(fileSystem, root) ? { changes: changesOf(fileSystem, root) } : {}),
+    ...files,
+  };
+  return descriptor;
+}
+
+/** a module reference with a version (not a live prefab): its namespace, the rest, its version */
+const VERSIONED_REFERENCE_RE = /^_ns_(.+?)(_t_[a-z][A-Za-z0-9]*_n_.+)_v_(\d+(?:_\d+)*)$/;
+
+/**
+ * A library prefab's tree with every block of a distribution built with it at that distribution's
+ * version now (`versions`: namespace → X.Y.Z) — a prefab written when its kit was 0.0.1 names the
+ * kit's blocks at 0.0.1, and is shipped live with the kit at 0.0.2. Other references stay.
+ */
+export function atBuiltVersions(json, versions) {
+  const visit = (node) => {
+    if (!node || typeof node !== 'object') return node;
+    const match = typeof node.reference === 'string' ? VERSIONED_REFERENCE_RE.exec(node.reference) : null;
+    const version = match ? versions.get(match[1]) : undefined;
+    const reference = version ? `_ns_${match[1]}${match[2]}_v_${version.replace(/[^a-zA-Z0-9]/g, '_')}` : node.reference;
+    return {
+      ...node,
+      ...(reference !== node.reference ? { reference } : {}),
+      ...(Array.isArray(node.children) ? { children: node.children.map(visit) } : {}),
+    };
+  };
+  return json && typeof json === 'object' && json.root ? { ...json, root: visit(json.root) } : json;
+}
+
+/** the most a version's notes may say in the catalog — what a window has room for */
+const MAX_CHANGES = 4000;
+
+/**
+ * What this version says it changed: its section of the distribution's CHANGELOG.md — the lines
+ * under a heading naming the version (`## 1.2.0`, as changesets writes it), up to the next heading
+ * of that level. Nothing for a distribution without one, or a version it does not name.
+ */
+export function changesOf(fileSystem, root) {
+  const file = path.join(root.dir, 'CHANGELOG.md');
+  if (!fileSystem.exists(file)) return undefined;
+  const lines = fileSystem.readFile(file, 'utf8').split(/\r?\n/);
+  const at = lines.findIndex((line) => new RegExp(`^(#{1,3})\\s*\\[?v?${root.version.replace(/\./g, '\\.')}\\]?(\\s|$)`).test(line));
+  if (at < 0) return undefined;
+  const level = /^#+/.exec(lines[at])[0].length;
+  const section = [];
+  for (const line of lines.slice(at + 1)) {
+    const heading = /^(#+)\s/.exec(line);
+    if (heading && heading[1].length <= level) break;
+    section.push(line);
+  }
+  const notes = section.join('\n').trim();
+  return notes ? notes.slice(0, MAX_CHANGES) : undefined;
+}

package/src/buildConfig.mjs

@@ -0,0 +1,22 @@
+// mosetta.build.mjs: the app's build-extension hooks. mosetta.json stays pure data —
+// build CODE lives in this co-located convention file. Loaded per build() run with an mtime
+// cache-bust (the ESM import cache is permanent, a re-import needs a fresh URL), so a dev-server
+// rebuild picks up config edits without a restart. Missing file → inert config.
+
+/** Inert form: `mosetta.build.mjs` is absent or the caller did not load it. */
+export const INERT_BUILD_CONFIG = Object.freeze({
+  file: null, stamp: 'none', clientPlugins: null, serverEsbuild: null, rollupOptions: null,
+});
+
+
+// The protocol invariant a user plugin must not break: a client artifact is a
+// NAMED System.register — the runtime links artifacts by these string names. Checked after every
+// generate; quote-agnostic (production minify normalizes quotes).
+export function assertNamedRegister(code, full, buildConfig) {
+  const re = new RegExp(`System\\.register\\(\\s*["']${full.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']`);
+  if (re.test(code)) return;
+  const hint = buildConfig?.file && buildConfig.stamp !== 'none'
+    ? ` — check your plugins in ${buildConfig.file} (reproduce without them first)`
+    : '';
+  throw new Error(`artifact ${full} lost its named System.register form${hint}`);
+}