@mh-gg/host 0.1.1-alpha.20260626T104441232Z

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matterhorn contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @mh-gg/host
+
+Matterhorn host: the room session runtime that manages a room store, serves connected clients (frontend bundle transfer), and embeds/spawns a local relay. Depends on `@mh-gg/relay` for relay config, identity, wire-validation, and the embedded relay factory.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mh-gg/host",
+  "version": "0.1.1-alpha.20260626T104441232Z",
+  "description": "Matterhorn host: room session runtime that serves connected clients and embeds a local relay.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.21.0",
+    "@mh-gg/host-config": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/host-ipc": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/host-store": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/relay": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/room-link": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/room-security": "^0.1.1-alpha.20260626T104441232Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=60 --test-coverage-include=src/**/*.cjs test/*.test.cjs"
+  }
+}

package/src/host.cjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+const path = require("node:path");
+const fs = require("node:fs");
+const WebSocket = require("ws");
+const { ensureRoomSecurity } = require("@mh-gg/room-security");
+const { parseArgs } = require("@mh-gg/host-config");
+const { loadStore, saveStore } = require("@mh-gg/host-store");
+const { normalizeAppUrl } = require("@mh-gg/room-link");
+const { applymatterhornrcDefaults } = require("@mh-gg/relay");
+const { ensureLocalRelay, relayIpcUrl } = require("./localRelayClient.cjs");
+const { createHostSession } = require("./hostSession.cjs");
+
+function roomAppFromEnv(env = process.env) {
+  if (!env.MATTERHORN_ROOM_APP) return undefined;
+  try {
+    const value = JSON.parse(env.MATTERHORN_ROOM_APP);
+    if (!value || typeof value !== "object") return undefined;
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseJsonObjectEnv(value) {
+  if (!value) return undefined;
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function frontendBundleRebuildFromEnv(env) {
+  const rebuild = parseJsonObjectEnv(env.MATTERHORN_FRONTEND_BUNDLE_REBUILD);
+  return typeof rebuild?.command === "string" ? rebuild : undefined;
+}
+
+function frontendBundleManifestFromEnv(env) {
+  const manifestFile = env.MATTERHORN_FRONTEND_BUNDLE_MANIFEST_FILE ? path.resolve(env.MATTERHORN_FRONTEND_BUNDLE_MANIFEST_FILE) : undefined;
+  if (!manifestFile) return {};
+  try {
+    return { manifestFile, manifest: JSON.parse(fs.readFileSync(manifestFile, "utf8")) };
+  } catch (error) {
+    if (!error || (error.code !== "ENOENT" && error.code !== "ENOTDIR")) globalThis.__matterhornIgnoredError?.(error, "host/host.cjs");
+    return { manifestFile };
+  }
+}
+
+function frontendBundleSourceRootsFromEnv(env) {
+  if (!env.MATTERHORN_FRONTEND_BUNDLE_SOURCE_ROOTS) return undefined;
+  return env.MATTERHORN_FRONTEND_BUNDLE_SOURCE_ROOTS.split(path.delimiter).filter(Boolean).map((item) => path.resolve(item));
+}
+
+function frontendBundleSourceIgnorePathsFromEnv(env) {
+  if (!env.MATTERHORN_FRONTEND_BUNDLE_SOURCE_IGNORE_PATHS) return undefined;
+  return env.MATTERHORN_FRONTEND_BUNDLE_SOURCE_IGNORE_PATHS.split(path.delimiter).filter(Boolean).map((item) => path.resolve(item));
+}
+
+function frontendBundleSourceRootFromEnv(env) {
+  if (!env.MATTERHORN_FRONTEND_BUNDLE_SOURCE_ROOT) return undefined;
+  return path.resolve(env.MATTERHORN_FRONTEND_BUNDLE_SOURCE_ROOT);
+}
+
+function addOptionalFrontendBundleField(target, key, value) {
+  if (value !== undefined) target[key] = value;
+}
+
+function frontendBundleFromEnv(env = process.env) {
+  if (!env.MATTERHORN_FRONTEND_BUNDLE_FILE) return undefined;
+  const manifestFromEnv = frontendBundleManifestFromEnv(env);
+  const sourceRoots = frontendBundleSourceRootsFromEnv(env);
+  const sourceIgnorePaths = frontendBundleSourceIgnorePathsFromEnv(env);
+  const sourceRoot = frontendBundleSourceRootFromEnv(env);
+  const rebuild = frontendBundleRebuildFromEnv(env);
+  const bundle = {
+    file: path.resolve(env.MATTERHORN_FRONTEND_BUNDLE_FILE),
+    id: env.MATTERHORN_FRONTEND_BUNDLE_ID || undefined,
+    integrity: env.MATTERHORN_FRONTEND_BUNDLE_INTEGRITY || undefined,
+    dynamic: env.MATTERHORN_FRONTEND_BUNDLE_DYNAMIC === "1"
+  };
+  addOptionalFrontendBundleField(bundle, "manifestFile", manifestFromEnv.manifestFile);
+  addOptionalFrontendBundleField(bundle, "manifest", manifestFromEnv.manifest);
+  addOptionalFrontendBundleField(bundle, "sourceRoot", sourceRoot);
+  addOptionalFrontendBundleField(bundle, "sourceRoots", sourceRoots);
+  addOptionalFrontendBundleField(bundle, "sourceIgnorePaths", sourceIgnorePaths);
+  addOptionalFrontendBundleField(bundle, "rebuild", rebuild);
+  return bundle;
+}
+
+function appRefFromEnv(env = process.env) {
+  if (!env.MATTERHORN_APP_REF) return undefined;
+  return {
+    appRef: env.MATTERHORN_APP_REF,
+    appCwd: env.MATTERHORN_APP_CWD || process.cwd()
+  };
+}
+
+async function main() {
+  applymatterhornrcDefaults();
+  const args = parseArgs(process.argv.slice(2), {
+    defaultDataDir: path.join(__dirname, "data")
+  });
+  const store = loadStore(args);
+  const appUrl = normalizeAppUrl(args.appUrl);
+  const localRelay = await ensureLocalRelay({
+    relayPeers: args.relayPeers,
+    matterhornProfile: args.matterhornProfile,
+    iceServers: args.iceServers,
+    localPeerjs: args.localPeerjs,
+    nondiscoverable: args.nondiscoverable,
+    dataDir: args.dataDir
+  });
+  const roomPeerId = localRelay.info.relayPeerId || localRelay.config.relayPeerId;
+  store.roomPeerId = roomPeerId;
+  store.relayAddress = localRelay.info.relayAddress || localRelay.config.relayAddress;
+  const roomApp = roomAppFromEnv();
+  if (roomApp) store.roomApp = roomApp;
+  ensureRoomSecurity(store);
+  saveStore(store);
+
+  const hostSession = createHostSession({
+    store,
+    args,
+    appUrl,
+    ...appRefFromEnv(),
+    frontendBundle: frontendBundleFromEnv(),
+    localRelay,
+    roomPeerId,
+    saveStore,
+    reconnectRelay: true
+  });
+  const relaySocket = new WebSocket(relayIpcUrl(localRelay.config));
+  hostSession.attachRelaySocket(relaySocket);
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  frontendBundleFromEnv,
+  appRefFromEnv,
+  main,
+  roomAppFromEnv
+};

package/src/hostAnnouncement.cjs

@@ -0,0 +1,71 @@
+const qrcode = require("qrcode-terminal");
+const { activePublicInvite } = require("@mh-gg/room-security");
+const { stateFile } = require("@mh-gg/host-store");
+const { buildInviteUrl } = require("@mh-gg/room-link");
+const { peerJsSignalingUrl } = require("@mh-gg/relay");
+
+function buildInvite(store, appUrl, roomPeerId, invite, adminToken) {
+  return buildInviteUrl(appUrl, store.roomName, roomPeerId, invite.secret, store.relayAddress, invite.id, adminToken);
+}
+
+function announceGuestInvite(options) {
+  const {
+    store,
+    appUrl,
+    roomPeerId,
+    logger = console,
+    qr = qrcode
+  } = options;
+  const invite = activePublicInvite(store);
+  if (!invite) {
+    logger.log("Guest Invite: no active public invite\n");
+    return false;
+  }
+
+  const shareUrl = buildInvite(store, appUrl, roomPeerId, invite);
+  logger.log(`Guest Invite: ${shareUrl}\n`);
+  qr.generate(shareUrl, { small: true });
+  return true;
+}
+
+function announceHost(options) {
+  const {
+    store,
+    appUrl,
+    localRelay,
+    roomPeerId,
+    logger = console,
+    qr = qrcode
+  } = options;
+
+  logger.log("\nMatterhorn host is live through the local relay.");
+  logger.log(`Room:        ${store.roomName}`);
+  logger.log(`Room peer:   ${roomPeerId}`);
+  logger.log(`Relay mesh:  ${store.relayAddress}`);
+  logger.log(`Profile:     ${store.matterhornProfile || "development"}`);
+  logger.log(`Relay IPC:   ws://${localRelay.config.ipcHost}:${localRelay.config.ipcPort}/room${localRelay.spawned ? " (started)" : " (existing)"}`);
+  logger.log(`Signaling:   ${peerJsSignalingUrl()}`);
+  logger.log(`Launcher:    ${appUrl}`);
+  if (store.roomApp?.appPack?.id) logger.log(`Room app:    ${store.roomApp.appPack.id}@${store.roomApp.appPack.version || "unknown"}`);
+  const frontend = Array.isArray(store.roomApp?.frontends) ? store.roomApp.frontends[0] : undefined;
+  if (frontend?.id) logger.log(`Frontend:    ${frontend.id}@${frontend.version || "unknown"} via ${frontend.delivery || "unknown"}`);
+  logger.log(`Data file:   ${stateFile(store.dataDir, store.roomName)}`);
+  const invite = activePublicInvite(store);
+  let guestInviteAnnounced = false;
+  if (invite) {
+    if (store.adminBootstrapToken) {
+      const adminUrl = buildInvite(store, appUrl, roomPeerId, invite, store.adminBootstrapToken);
+      logger.log(`JOIN AS ADMIN: ${adminUrl}\n`);
+    }
+    guestInviteAnnounced = announceGuestInvite(options);
+  } else {
+    logger.log("Guest Invite: no active public invite\n");
+  }
+  logger.log("\nKeep this process running while guests are connected. Press Ctrl+C to stop.\n");
+  return { guestInviteAnnounced };
+}
+
+module.exports = {
+  announceGuestInvite,
+  announceHost
+};

package/src/hostClients/constants.cjs

@@ -0,0 +1,7 @@
+const OPERATION_SNAPSHOT_INTERVAL = 50;
+const DEFAULT_FRONTEND_CHUNK_BYTES = 6 * 1024;
+
+module.exports = {
+  DEFAULT_FRONTEND_CHUNK_BYTES,
+  OPERATION_SNAPSHOT_INTERVAL
+};

package/src/hostClients/frontendBundleManifest.cjs

@@ -0,0 +1,29 @@
+const fs = require("node:fs");
+
+function readManifest(file) {
+  if (!file) return undefined;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (manifest?.kind !== "matterhorn.frontend.manifest" || manifest.version !== 1) return undefined;
+    if (typeof manifest.entrypoint !== "string" || !manifest.entrypoint) return undefined;
+    if (!Array.isArray(manifest.files)) return undefined;
+    if (!manifest.files.some((item) => item?.path === "index.html")) return undefined;
+    return manifest;
+  } catch (error) {
+    if (!error || (error.code !== "ENOENT" && error.code !== "ENOTDIR")) {
+      globalThis.__matterhornIgnoredError?.(error, "host/hostClients/frontendBundleManifest.cjs");
+    }
+    return undefined;
+  }
+}
+
+function sameManifest(left, right) {
+  if (left === right) return true;
+  if (!left || !right) return false;
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+module.exports = {
+  readManifest,
+  sameManifest
+};

package/src/hostClients/frontendBundleRefresh.cjs

@@ -0,0 +1,246 @@
+const fs = require("node:fs");
+const { createHash } = require("node:crypto");
+const { spawn, spawnSync } = require("node:child_process");
+const path = require("node:path");
+const { commandInvocation, replaceTokens } = require("../../../../bin/appFrontend/processes.cjs");
+const { buildMatterhornCommandEnv } = require("../../../../bin/appFrontend/commandEnv.cjs");
+const { assertAppCommandAllowed, commandEnvTrustForPolicy } = require("../../../../bin/appFrontend/commandPolicy.cjs");
+const { manifestBundleIdentity } = require("../../../../bin/appFrontend/artifacts.cjs");
+const { readManifest, sameManifest } = require("./frontendBundleManifest.cjs");
+const { latestSourceRootsMtime } = require("./sourceMtime.cjs");
+
+function fileIntegrity(file) {
+  return `sha256-${createHash("sha256").update(fs.readFileSync(file)).digest("hex")}`;
+}
+
+function rebuildEnv(rebuild, options, policy) {
+  const env = Object.fromEntries(
+    Object.entries(rebuild.env || {}).map(([key, value]) => [key, replaceTokens(value, options)])
+  );
+  return buildMatterhornCommandEnv({
+    trust: commandEnvTrustForPolicy(policy || rebuild.trust || "trusted-local-dev"),
+    commandEnv: env,
+    port: options.port,
+    bundlePort: options.bundlePort,
+    mountPath: options.mountPath,
+    unsafeInheritEnv: rebuild.unsafeInheritEnv,
+    allowSensitiveCommandEnv: rebuild.allowSensitiveCommandEnv,
+    matterhornProfile: options.matterhornProfile
+  });
+}
+
+function rebuildOptions(frontendBundle, rebuild) {
+  return {
+    port: rebuild.port || 0,
+    bundlePort: rebuild.bundlePort || rebuild.port || 0,
+    mountPath: rebuild.mountPath || "/",
+    matterhornProfile: frontendBundle.matterhornProfile
+  };
+}
+
+function runRebuildCommand(command, options, policy) {
+  if (!command?.command) return true;
+  const args = Array.isArray(command.args) ? command.args.map((arg) => replaceTokens(arg, options)) : [];
+  const invocation = commandInvocation(command.command, args);
+  const result = spawnSync(invocation.command, invocation.args, {
+    cwd: command.cwd || process.cwd(),
+    env: rebuildEnv(command, options, policy),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true
+  });
+  return result.status === 0;
+}
+
+function runRebuildCommandAsync(command, options, policy) {
+  if (!command?.command) return Promise.resolve(true);
+  const args = Array.isArray(command.args) ? command.args.map((arg) => replaceTokens(arg, options)) : [];
+  const invocation = commandInvocation(command.command, args);
+  return new Promise((resolve) => {
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: command.cwd || process.cwd(),
+      env: rebuildEnv(command, options, policy),
+      stdio: ["ignore", "ignore", "ignore"],
+      windowsHide: true
+    });
+    child.on("error", () => resolve(false));
+    child.on("exit", (code) => resolve(code === 0));
+  });
+}
+
+function runDynamicBundleRebuild(frontendBundle) {
+  const rebuild = frontendBundle?.rebuild;
+  if (!rebuild?.command) return false;
+  const policy = assertAppCommandAllowed({ commandExecution: rebuild.trust || "trusted-local-dev" }, "matterhorn dynamic bundle rebuild");
+  const options = rebuildOptions(frontendBundle, rebuild);
+  for (const command of rebuild.before || []) {
+    if (!runRebuildCommand(command, options, policy)) return false;
+  }
+  return runRebuildCommand(rebuild, options, policy);
+}
+
+async function runDynamicBundleRebuildAsync(frontendBundle) {
+  const rebuild = frontendBundle?.rebuild;
+  if (!rebuild?.command) return false;
+  const policy = assertAppCommandAllowed({ commandExecution: rebuild.trust || "trusted-local-dev" }, "matterhorn dynamic bundle rebuild");
+  const options = rebuildOptions(frontendBundle, rebuild);
+  for (const command of rebuild.before || []) {
+    if (!await runRebuildCommandAsync(command, options, policy)) return false;
+  }
+  return await runRebuildCommandAsync(rebuild, options, policy);
+}
+
+function dynamicSourceRoots(frontendBundle) {
+  if (!frontendBundle?.dynamic || !frontendBundle.sourceRoot || !frontendBundle.file) return [];
+  return (frontendBundle.sourceRoots || [frontendBundle.sourceRoot]).filter(Boolean).map((root) => path.resolve(root));
+}
+
+function dynamicBundleNeedsRebuild(frontendBundle) {
+  const roots = dynamicSourceRoots(frontendBundle);
+  if (roots.length === 0 || roots.every((root) => !fs.existsSync(root))) return false;
+  const bundleFile = path.resolve(frontendBundle.file);
+  const ignoredRoots = [
+    path.dirname(bundleFile),
+    ...(frontendBundle.sourceIgnorePaths || [])
+  ].filter(Boolean).map((item) => path.resolve(item));
+  const bundleMtime = fs.existsSync(bundleFile) ? fs.statSync(bundleFile).mtimeMs : 0;
+  return latestSourceRootsMtime(roots, ignoredRoots) > bundleMtime;
+}
+
+function rebuildDynamicBundleIfSourceChanged(frontendBundle) {
+  if (!dynamicBundleNeedsRebuild(frontendBundle)) return false;
+  return runDynamicBundleRebuild(frontendBundle);
+}
+
+function dynamicBundleSnapshotStore(frontendBundle) {
+  if (!frontendBundle) return undefined;
+  if (!frontendBundle.dynamicBundleSnapshots) {
+    Object.defineProperty(frontendBundle, "dynamicBundleSnapshots", {
+      configurable: true,
+      enumerable: false,
+      value: new Map(),
+      writable: true
+    });
+  }
+  return frontendBundle.dynamicBundleSnapshots;
+}
+
+function rememberDynamicBundleSnapshot(frontendBundle, frontend) {
+  if (!frontendBundle?.dynamic || !frontendBundle.file || !frontend || frontend.manifest || !frontend.integrity) return;
+  if (frontendBundle.id && frontendBundle.id !== frontend.id) return;
+  if (!fs.existsSync(frontendBundle.file)) return;
+
+  let stat;
+  let integrity;
+  try {
+    stat = fs.statSync(frontendBundle.file);
+    if (!stat.isFile()) return;
+    integrity = fileIntegrity(frontendBundle.file);
+  } catch {
+    return;
+  }
+  if (integrity !== frontend.integrity) return;
+
+  const snapshots = dynamicBundleSnapshotStore(frontendBundle);
+  if (!snapshots || snapshots.has(integrity)) return;
+  snapshots.set(integrity, {
+    buffer: fs.readFileSync(frontendBundle.file),
+    byteLength: stat.size,
+    chunkSize: frontend.chunkSize,
+    id: frontend.id,
+    integrity,
+    name: frontend.name
+  });
+  while (snapshots.size > 4) snapshots.delete(snapshots.keys().next().value);
+}
+
+function frontendBundleIdentity(file, manifest) {
+  if (manifest) return manifestBundleIdentity(manifest);
+  const stat = fs.statSync(file);
+  if (!stat.isFile()) return undefined;
+  return {
+    integrity: fileIntegrity(file),
+    byteLength: stat.size
+  };
+}
+
+function createDynamicFrontendRefresher({ store, frontendBundle, onRoomAppChange = () => {} }) {
+  let pendingRebuild;
+
+  function refreshFrontendMetadata(frontend) {
+    if (!frontendBundle?.dynamic || !frontendBundle.file || !frontend) return frontend;
+    if (frontendBundle.id && frontendBundle.id !== frontend.id) return frontend;
+    if (!fs.existsSync(frontendBundle.file)) return frontend;
+    let identity;
+    try {
+      const manifest = readManifest(frontendBundle.manifestFile);
+      if (frontendBundle.manifestFile && !manifest) return frontend;
+      frontendBundle.manifest = manifest;
+      identity = frontendBundleIdentity(frontendBundle.file, frontendBundle.manifest);
+      if (!identity) return frontend;
+    } catch {
+      return frontend;
+    }
+    if (frontend.integrity === identity.integrity && frontend.byteLength === identity.byteLength && sameManifest(frontend.manifest, frontendBundle.manifest)) return frontend;
+
+    const frontends = Array.isArray(store.roomApp?.frontends) ? store.roomApp.frontends : [];
+    const index = frontends.findIndex((candidate) => candidate.id === frontend.id);
+    if (index < 0) return frontend;
+    const nextFrontend = {
+      ...frontend,
+      integrity: identity.integrity,
+      byteLength: identity.byteLength,
+      ...(frontendBundle.manifest ? { manifest: frontendBundle.manifest } : {})
+    };
+    store.roomApp = {
+      ...store.roomApp,
+      frontends: frontends.map((candidate, candidateIndex) => candidateIndex === index ? nextFrontend : candidate)
+    };
+    onRoomAppChange(store.roomApp);
+    return nextFrontend;
+  }
+
+  function refreshDynamicFrontends(options = {}) {
+    const frontends = Array.isArray(store.roomApp?.frontends) ? store.roomApp.frontends : [];
+    for (const frontend of frontends) refreshDynamicFrontend(frontend, options);
+  }
+
+  function snapshotCurrentDynamicFrontends() {
+    const frontends = Array.isArray(store.roomApp?.frontends) ? store.roomApp.frontends : [];
+    for (const frontend of frontends) rememberDynamicBundleSnapshot(frontendBundle, frontend);
+  }
+
+  function scheduleDynamicBundleRebuild() {
+    if (pendingRebuild || !dynamicBundleNeedsRebuild(frontendBundle)) return;
+    snapshotCurrentDynamicFrontends();
+    pendingRebuild = runDynamicBundleRebuildAsync(frontendBundle)
+      .then((rebuilt) => {
+        if (rebuilt) refreshDynamicFrontends({ scheduleRebuild: false });
+      })
+      .catch((error) => {
+        (globalThis.__matterhornIgnoredError || (() => undefined))(error, "packages/matterhorn-host/src/hostClients/frontendBundleRefresh.cjs");
+      })
+      .finally(() => {
+        pendingRebuild = undefined;
+      });
+  }
+
+  function refreshDynamicFrontend(frontend, options = {}) {
+    if (!frontendBundle?.dynamic || !frontendBundle.file || !frontend) return frontend;
+    if (frontendBundle.id && frontendBundle.id !== frontend.id) return frontend;
+    if (options.scheduleRebuild !== false) scheduleDynamicBundleRebuild();
+    return refreshFrontendMetadata(frontend);
+  }
+
+  return {
+    refreshDynamicFrontend,
+    refreshDynamicFrontends
+  };
+}
+
+module.exports = {
+  createDynamicFrontendRefresher,
+  rebuildEnv,
+  rebuildDynamicBundleIfSourceChanged,
+  runDynamicBundleRebuild
+};

package/src/hostClients/frontendCacheStatus.cjs

@@ -0,0 +1,39 @@
+function cachedFrontendProof(message) {
+  const proof = message?.cachedFrontend;
+  if (!proof || typeof proof !== "object" || Array.isArray(proof)) return undefined;
+  if (typeof proof.id !== "string" || !proof.id) return undefined;
+  if (typeof proof.integrity !== "string" || !proof.integrity) return undefined;
+  const result = { id: proof.id, integrity: proof.integrity };
+  if (Number.isInteger(proof.byteLength) && proof.byteLength >= 0) result.byteLength = proof.byteLength;
+  return result;
+}
+
+function frontendCacheStatus(frontend, message) {
+  const proof = cachedFrontendProof(message);
+  const sameFrontend = proof?.id === frontend.id && proof.integrity === frontend.integrity;
+  const sameLength = proof?.byteLength === undefined || frontend.byteLength === undefined || proof.byteLength === frontend.byteLength;
+  return {
+    frontendId: frontend.id,
+    integrity: frontend.integrity,
+    byteLength: frontend.byteLength,
+    clientHasCurrentBundle: Boolean(sameFrontend && sameLength)
+  };
+}
+
+function logFrontendCacheStatus({ debug, store, source, peerId, frontend, cache }) {
+  debug("frontend cache status", {
+    source,
+    peerId,
+    roomName: store.roomName,
+    frontendId: frontend.id,
+    integrity: frontend.integrity,
+    byteLength: frontend.byteLength,
+    clientHasCurrentBundle: cache.clientHasCurrentBundle
+  });
+}
+
+module.exports = {
+  cachedFrontendProof,
+  frontendCacheStatus,
+  logFrontendCacheStatus
+};