@mh-gg/schema 0.1.1-alpha.20260613T085325975Z

package/src/builder/matterhornApp/build.cjs

@@ -0,0 +1,137 @@
+const {
+  computeAppProtocolHash,
+  definePlayerPlugin,
+  hashCanonical,
+  manifestHash,
+  resolvePluginGraph
+} = require('@mh-gg/base');
+const { createActionDispatchersFromComposition } = require('../../actions.cjs');
+const {
+  appCompositionSchemaHash,
+  resolveCompositionHostPluginEntries,
+  validateAppCompositionSchema
+} = require('../../composition.cjs');
+const { schemaDefinedHostPluginEntry } = require('../../model/plugin.cjs');
+const { matterhornAppDescriptorFromBuilt } = require('./descriptors.cjs');
+const { normalizeHostPluginEntries, primaryHostPluginDescriptorForBuilt } = require('./plugins.cjs');
+const { DEFAULT_PUBLISHER, DEFAULT_TRUST, mergedOptions, slugFromAppId } = require('./shared.cjs');
+
+function buildMatterhornApp(app, options = {}) {
+  const merged = mergedOptions(app, options);
+  const composition = validateAppCompositionSchema(merged.compositionSchema || app.toJSON(), { registry: merged.registry });
+  const appId = merged.appId || composition.app.id;
+  const version = merged.version || composition.app.version || '1.0.0';
+  const name = merged.name || composition.app.name || appId;
+  const slug = merged.slug || slugFromAppId(appId);
+  const packageName = merged.packageName || slug;
+  const compositionHostPlugins = resolveCompositionHostPluginEntries(composition, merged.registry);
+  const primarySchemaPlugin = !merged.hostPlugin ? schemaDefinedHostPluginEntry(composition, { packageName }) : undefined;
+  const hostPluginEntries = normalizeHostPluginEntries({
+    ...merged,
+    packageName,
+    hostPlugins: [primarySchemaPlugin, ...(merged.hostPlugins || []), ...compositionHostPlugins].filter(Boolean)
+  }, version);
+  const graph = resolvePluginGraph(hostPluginEntries.map((entry) => entry.plugin));
+  const hostPluginDescriptors = graph.descriptors;
+  const appProtocolHash = computeAppProtocolHash({ appPackId: appId, appVersion: version, hostPlugins: hostPluginDescriptors });
+  const pluginGraphHash = graph.pluginGraphHash;
+  const publisher = merged.publisher || DEFAULT_PUBLISHER;
+  const trust = merged.trust || DEFAULT_TRUST;
+  const compositionHash = appCompositionSchemaHash(composition);
+
+  const hostPack = {
+    kind: 'matterhorn.host-pack',
+    id: `${appId}.host`,
+    appPackId: appId,
+    version,
+    plugins: hostPluginEntries.map((entry) => ({
+      id: entry.plugin.id,
+      version: entry.plugin.version,
+      source: entry.source || `workspace:${entry.packageName}#${entry.exportName}`,
+      integrity: hashCanonical({ package: entry.packageName, export: entry.exportName, version: entry.plugin.version || version }),
+      ...(entry.dependsOn && entry.dependsOn.length ? { dependsOn: entry.dependsOn } : {}),
+      ...(entry.conflictsWith && entry.conflictsWith.length ? { conflictsWith: entry.conflictsWith } : {})
+    })),
+    compatibility: { appProtocolHash, pluginGraphHash },
+    runtime: { minMatterhornVersion: '0.1.0', sandbox: 'process' },
+    capabilities: merged.hostCapabilities || { required: ['room.state', 'room.roles'], optional: ['relay.event-cache'] },
+    composition: {
+      schemaHash: compositionHash,
+      primaryPlugin: composition.primaryPlugin,
+      plugins: composition.plugins,
+      sharedScopes: composition.sharedScopes || {},
+      views: composition.views,
+      actions: composition.actions,
+      ...(composition.notifications === undefined ? {} : { notifications: composition.notifications })
+    },
+    trust
+  };
+
+  const pluginIds = hostPluginDescriptors.map((descriptor) => descriptor.id);
+  const support = { appPackId: appId, appPackRange: `^${version}`, appProtocolHash, pluginIds, compositionSchemaHash: compositionHash };
+  const playerPack = {
+    kind: 'matterhorn.player-pack',
+    id: merged.playerPackId || `${appId}.player`,
+    name: `${name} Player`,
+    version,
+    publisher,
+    entrypoints: merged.entrypoints || {
+      default: `https://apps.matterhorn.gg/${slug}/player/${version}/`,
+      admin: `https://apps.matterhorn.gg/${slug}/admin/${version}/`
+    },
+    supports: [support],
+    recommendedFor: merged.recommendedFor || { devices: ['desktop', 'tablet'], roles: ['admin', 'member'] },
+    mode: 'external',
+    trust: {
+      integrity: hashCanonical({ package: packageName, export: merged.playerPluginExport || 'playerPlugin', version }),
+      signatures: trust.signatures
+    }
+  };
+
+  const builtForPrimary = { config: { ...merged, hostPlugin: merged.hostPlugin }, compositionSchema: composition, hostPluginDescriptors, hostPlugins: hostPluginEntries.map((entry) => entry.plugin) };
+  const primaryHostPluginDescriptor = primaryHostPluginDescriptorForBuilt(builtForPrimary);
+  const appPack = {
+    kind: 'matterhorn.app-pack',
+    id: appId,
+    name,
+    version,
+    publisher,
+    matterhornVersion: '>=0.1 <0.2',
+    hostPack: { url: `workspace:${packageName}#${merged.hostPackExport || 'hostPack'}`, integrity: manifestHash(hostPack) },
+    playerPacks: [{ id: playerPack.id, name: playerPack.name, url: `workspace:${packageName}#${merged.playerPackExport || 'playerPack'}`, integrity: manifestHash(playerPack), recommendedFor: playerPack.recommendedFor }],
+    compatibility: {
+      appProtocolHash,
+      operationSchemaHash: primaryHostPluginDescriptor.operationSchemaHash,
+      stateSchemaHash: primaryHostPluginDescriptor.stateSchemaHash,
+      pluginGraphHash,
+      compositionSchemaHash: compositionHash
+    },
+    composition,
+    capabilities: merged.appCapabilities || { required: ['room.state', 'room.roles', 'relay.route'], optional: ['relay.event-cache'] },
+    trust: { createdAt: merged.createdAt || '2026-05-27T00:00:00Z', signatures: trust.signatures }
+  };
+
+  const generatedActions = createActionDispatchersFromComposition(composition, { registry: merged.registry });
+  const playerPlugin = definePlayerPlugin({
+    id: merged.playerPluginId || `${appId}.player-plugin`,
+    version,
+    meta: { name: `${name} Player Plugin`, publisher },
+    supports: [support],
+    routes: merged.routes || composition.routes || [{ path: '/', component: `${name.replace(/[^A-Za-z0-9]/g, '')}Page`, requiredPlugins: pluginIds }],
+    actions: { ...generatedActions, ...(merged.actions || {}) },
+    optimisticReducers: merged.optimisticReducers || {},
+    navigation: { defaultRoute: '/', adminRoute: '/admin', ...(merged.navigation || {}) },
+    deviceHints: { desktop: true, tablet: true, ...(merged.deviceHints || {}) }
+  });
+
+  return { appPack, appProtocolHash, hostPack, hostPluginDescriptors, hostPlugins: hostPluginEntries.map((entry) => entry.plugin), playerPack, playerPlugin, pluginGraphHash, compositionSchema: composition, publisher, trust, config: { ...merged, appId, version, name, slug, packageName } };
+}
+
+function createMatterhornAppDescriptor(app, options = {}) {
+  return matterhornAppDescriptorFromBuilt(buildMatterhornApp(app, options));
+}
+
+module.exports = {
+  buildMatterhornApp,
+  createMatterhornAppDescriptor
+};

package/src/builder/matterhornApp/bundle.cjs

@@ -0,0 +1,89 @@
+const path = require('node:path');
+const fs = require('node:fs');
+const { cloneJson } = require('../../json.cjs');
+const { buildMatterhornApp } = require('./build.cjs');
+const { matterhornAppDescriptorFromBuilt, schemaArtifactsForBuilt } = require('./descriptors.cjs');
+const { APP_MATTERHORN_META } = require('./shared.cjs');
+
+const BUNDLE_DESCRIPTOR_KEYS = new Set([
+  'id',
+  'name',
+  'version',
+  'appPack',
+  'hostPack',
+  'hostPlugins',
+  'playerPacks',
+  'playerPlugins',
+  'deployment',
+  'frontend',
+  'matterhorn'
+]);
+
+function bundleDescriptorExtras(matterhornApp) {
+  const extras = {};
+  for (const [key, value] of Object.entries(matterhornApp)) {
+    if (!BUNDLE_DESCRIPTOR_KEYS.has(key) && value !== undefined) extras[key] = cloneJson(value);
+  }
+  return extras;
+}
+
+function cleanBundlePluginRef(plugin) {
+  const ref = {
+    kind: 'matterhorn.registry-host-plugin',
+    key: plugin.key,
+    id: plugin.id,
+    version: plugin.version
+  };
+  if (plugin.config !== undefined) ref.config = cloneJson(plugin.config);
+  return ref;
+}
+
+function bundleHostPluginRefs(built) {
+  const primaryId = built.compositionSchema.primaryPlugin.id;
+  const refs = [{
+    kind: 'matterhorn.schema-model-host-plugin',
+    id: primaryId,
+    version: built.compositionSchema.primaryPlugin.version,
+    composition: cloneJson(built.compositionSchema)
+  }];
+  for (const plugin of built.compositionSchema.plugins || []) refs.push(cleanBundlePluginRef(plugin));
+  return refs;
+}
+
+function createMatterhornAppBundle(app, options = {}) {
+  const built = buildMatterhornApp(app, options);
+  const matterhornApp = matterhornAppDescriptorFromBuilt(built);
+  return Object.freeze({
+    kind: 'matterhorn.app-bundle',
+    schemaVersion: 1,
+    id: matterhornApp.id,
+    name: matterhornApp.name,
+    version: matterhornApp.version,
+    appPack: matterhornApp.appPack,
+    hostPack: matterhornApp.hostPack,
+    hostPlugins: bundleHostPluginRefs(built),
+    playerPacks: matterhornApp.playerPacks,
+    deployment: matterhornApp.deployment,
+    ...(matterhornApp.frontend ? { frontend: matterhornApp.frontend } : {}),
+    ...(matterhornApp.matterhorn ? { matterhorn: matterhornApp.matterhorn } : {}),
+    ...bundleDescriptorExtras(matterhornApp),
+    compositionSchema: cloneJson(built.compositionSchema),
+    artifacts: schemaArtifactsForBuilt(built)
+  });
+}
+
+function emitMatterhornAppBundle(app, options = {}) {
+  const bundle = createMatterhornAppBundle(app, options);
+  const meta = app?.[APP_MATTERHORN_META] || {};
+  const outDir = path.resolve(options.outDir || options.packageRoot || meta.packageRoot || process.cwd());
+  const fileName = options.fileName || `${bundle.id}.json`;
+  const filePath = path.join(outDir, fileName);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(bundle, null, 2)}\n`);
+  return Object.freeze({ bundlePath: filePath, bundle });
+}
+
+module.exports = {
+  createMatterhornAppBundle,
+  emitMatterhornAppBundle
+};

package/src/builder/matterhornApp/demo.cjs

@@ -0,0 +1,161 @@
+const { manifestHash } = require('@mh-gg/base');
+const { createSignedPartyEvent, nostrEventToPartyEvent, partyEventToNostrEvent } = require('@mh-gg/event');
+const {
+  HostPluginRuntime,
+  createMemoryOperationLog,
+  createMemoryRoomStore
+} = require('@mh-gg/host-runtime');
+const { ensureOperationIdentity } = require('@mh-gg/protocol');
+const { cloneJson } = require('../../json.cjs');
+const {
+  createRecordPrefixes,
+  rememberCreatedDemoAlias,
+  rewriteDemoOperation
+} = require('./demoAliases.cjs');
+
+const DEMO_FILE_SIGNER = Object.freeze({
+  privateKey: '0000000000000000000000000000000000000000000000000000000000000001',
+  pubkey: '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'
+});
+
+function actorForDemo(value = {}) {
+  const role = value.role || 'admin';
+  const memberId = value.memberId || role;
+  return {
+    memberId,
+    deviceId: value.deviceId || `dev_${memberId}`,
+    role,
+    displayName: value.displayName || memberId,
+    ...value
+  };
+}
+
+function pluginIdFromDemoRef(ref, app) {
+  if (!ref || ref === 'primary' || ref === '$primary') return app.hostPlugin.id;
+  const plugin = app.appPack.composition.plugins.find((item) => item.key === ref || item.id === ref);
+  return plugin?.id || ref;
+}
+
+function payloadForDemoOperation(item, roomId) {
+  const payload = cloneJson(item.payload || {});
+  if (item.type !== 'file.upload' || !payload.event) return payload;
+
+  const partyEvent = nostrEventToPartyEvent(payload.event);
+  if (partyEvent.kind !== 'file.upload' || partyEvent.partyId === roomId) return payload;
+
+  const signed = createSignedPartyEvent({
+    kind: 'file.upload',
+    partyId: roomId,
+    identity: DEMO_FILE_SIGNER,
+    payload: partyEvent.payload,
+    createdAt: partyEvent.createdAt
+  });
+  return { ...payload, event: partyEventToNostrEvent(signed) };
+}
+
+function operationsFromDemoDefinition(demo, app, roomId = demo?.roomId) {
+  if (!demo) return [];
+  const appPackHash = manifestHash(app.appPack);
+  return (demo.operations || []).map((item, index) => {
+    const actor = actorForDemo(item.actor);
+    const createdAt = item.createdAt || ((demo.startTime || 1700000000000) + index + 1);
+    const operation = {
+      clientOperationId: item.id,
+      roomId,
+      appPackId: app.appPack.id,
+      appPackHash,
+      pluginId: pluginIdFromDemoRef(item.plugin || item.pluginId, app),
+      type: item.type,
+      actor,
+      seq: item.seq || index + 1,
+      createdAt,
+      hlc: item.hlc,
+      payload: payloadForDemoOperation(item, roomId),
+      auth: { credentialId: `cred_${actor.memberId}`, signature: 'sig' }
+    };
+    return ensureOperationIdentity(operation, { now: createdAt, nodeId: actor.deviceId || actor.memberId || 'demo' });
+  });
+}
+
+function countLive(value) {
+  if (Array.isArray(value)) return value.filter((item) => !item?.deletedAt && !item?.archivedAt && !item?.deleted).length;
+  if (value && typeof value === 'object') return Object.values(value).filter((item) => !item?.deletedAt && !item?.archivedAt && !item?.deleted).length;
+  return 0;
+}
+
+function addSharedPluginSummary(summary, state) {
+  const plugins = state.plugins || {};
+  const comments = plugins['com.matterhorn.examples.plugins.comments'];
+  if (comments?.comments) summary.sharedComments = countLive(comments.comments);
+  const mediaRooms = plugins['com.matterhorn.examples.plugins.media-rooms'];
+  if (mediaRooms?.rooms) summary.mediaRooms = countLive(mediaRooms.rooms);
+  const screenShares = plugins['com.matterhorn.examples.plugins.screen-share'];
+  if (screenShares?.shares) summary.activeScreenShares = Object.values(screenShares.shares).filter((share) => !share.stoppedAt).length;
+  const presence = plugins['com.matterhorn.examples.plugins.presence'];
+  if (presence?.members) summary.onlineMembers = countLive(presence.members);
+  const embeds = plugins['com.matterhorn.examples.plugins.embeds'];
+  if (embeds?.embeds) summary.embeds = countLive(embeds.embeds);
+  const reactions = plugins['com.matterhorn.examples.plugins.reactions'];
+  if (reactions?.reactions) summary.scopedReactions = countLive(reactions.reactions);
+  return summary;
+}
+
+function genericSummary(state, pluginId) {
+  const pluginState = state.plugins?.[pluginId] || {};
+  const summary = { version: state.version };
+  for (const [key, value] of Object.entries(pluginState)) {
+    if (Array.isArray(value) || (value && typeof value === 'object' && key !== 'details' && key !== 'settings')) summary[key] = countLive(value);
+  }
+  if (pluginState.messages && typeof pluginState.messages === 'object') {
+    const messages = Object.values(pluginState.messages);
+    summary.visibleMessages = messages.filter((message) => !message.deletedAt).length;
+    summary.pinnedMessages = messages.filter((message) => message.pinnedAt).length;
+  }
+  if (pluginState.tasks && typeof pluginState.tasks === 'object') {
+    const tasks = Object.values(pluginState.tasks);
+    summary.totalTasks = tasks.length;
+    summary.openTasks = tasks.filter((task) => task.status !== 'done' && !task.archivedAt).length;
+    summary.completedTasks = tasks.filter((task) => task.status === 'done' && !task.archivedAt).length;
+  }
+  if (pluginState.notes && typeof pluginState.notes === 'object') summary.noteCount = countLive(pluginState.notes);
+  if (pluginState.details?.title) summary.title = pluginState.details.title;
+  return summary;
+}
+
+async function replayDemo(app, operations, roomId, summary) {
+  const runtime = new HostPluginRuntime({
+    room: {
+      id: roomId,
+      appPack: {
+        id: app.appPack.id,
+        version: app.appPack.version,
+        hash: manifestHash(app.appPack),
+        protocolHash: app.appPack.compatibility.appProtocolHash
+      }
+    },
+    plugins: app.hostPlugins,
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+  await runtime.start();
+  const aliases = new Map();
+  const createPrefixes = createRecordPrefixes(app);
+  for (const operation of operations) {
+    const operationForReplay = rewriteDemoOperation(operation, aliases);
+    const result = await runtime.handleOperation(operationForReplay);
+    if (!result.ok) throw new Error(result.reason || result.error || `Demo operation ${operation.type} failed`);
+    rememberCreatedDemoAlias(operationForReplay, result, aliases, createPrefixes);
+  }
+  const state = await runtime.getState();
+  const guestView = await runtime.publicView(actorForDemo({ memberId: 'guest', role: 'guest' }));
+  const computedSummary = summary ? summary(state) : genericSummary(state, app.hostPlugin.id);
+  addSharedPluginSummary(computedSummary, state);
+  return { runtime, operations, state, guestView, summary: computedSummary };
+}
+
+module.exports = {
+  genericSummary,
+  operationsFromDemoDefinition,
+  replayDemo
+};

package/src/builder/matterhornApp/demoAliases.cjs

@@ -0,0 +1,50 @@
+const { ensureOperationIdentity } = require('@mh-gg/protocol');
+
+function createRecordPrefixes(app) {
+  const prefixes = new Map();
+  const primaryPluginId = app.hostPlugin?.id || app.appPack?.composition?.primaryPlugin?.id;
+  const primaryOperations = app.appPack?.composition?.primaryPlugin?.model?.operations || {};
+  for (const [type, descriptor] of Object.entries(primaryOperations)) {
+    const createEffect = (descriptor.effects || []).find((effect) => effect?.kind === 'createRecord' && effect.idPrefix);
+    if (createEffect && primaryPluginId) prefixes.set(`${primaryPluginId}:${type}`, createEffect.idPrefix);
+  }
+  return prefixes;
+}
+
+function replaceDemoAliases(value, aliases) {
+  if (typeof value === 'string') return aliases.get(value) || value;
+  if (Array.isArray(value)) return value.map((item) => replaceDemoAliases(item, aliases));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, replaceDemoAliases(item, aliases)]));
+  }
+  return value;
+}
+
+function rememberCreatedDemoAlias(operation, result, aliases, createPrefixes) {
+  const prefix = createPrefixes.get(`${operation.pluginId}:${operation.type}`) || inferredCreatePrefix(operation.type);
+  const legacyId = operation.clientOperationId;
+  const ledgerId = result?.acceptedLedgerId || result?.acceptedSnowflakeId;
+  if (!prefix || !legacyId || !ledgerId) return;
+  aliases.set(`${prefix}_${legacyId}`, `${prefix}_${ledgerId}`);
+}
+
+function inferredCreatePrefix(type) {
+  if (typeof type !== 'string') return undefined;
+  if (!/(^|\.)(create|add|send|upload)$/.test(type)) return undefined;
+  const prefix = type.split('.')[0]?.replace(/[^A-Za-z0-9_-]/g, '_');
+  return prefix || undefined;
+}
+
+function rewriteDemoOperation(operation, aliases) {
+  const rewritten = replaceDemoAliases(operation, aliases);
+  return ensureOperationIdentity(rewritten, {
+    now: rewritten.createdAt,
+    nodeId: rewritten.actor?.deviceId || rewritten.actor?.memberId || 'demo'
+  });
+}
+
+module.exports = {
+  createRecordPrefixes,
+  rememberCreatedDemoAlias,
+  rewriteDemoOperation
+};

package/src/builder/matterhornApp/descriptors.cjs

@@ -0,0 +1,59 @@
+const { cloneJson } = require('../../json.cjs');
+const { generateAppTypeDeclaration } = require('../../types/index.cjs');
+const { frontendDescriptor } = require('./frontend.cjs');
+const { typeNamespaceForBuilt } = require('./shared.cjs');
+
+function matterhornAppDescriptorFromBuilt(built) {
+  const config = built.config;
+  const frontend = frontendDescriptor(config);
+  const matterhornMetadata = config.matterhornApp || (config.matterhorn ? { matterhorn: config.matterhorn } : {});
+  return Object.freeze({
+    id: config.appId,
+    name: config.name,
+    version: config.version,
+    appPack: built.appPack,
+    hostPack: built.hostPack,
+    hostPlugins: built.hostPlugins,
+    playerPacks: [built.playerPack],
+    playerPlugins: [built.playerPlugin],
+    deployment: {
+      kind: 'matterhorn.self-contained-app',
+      host: { runner: 'matterhorn-example-host' },
+      relay: { mode: 'embedded', autoStart: true, acceptsPeerRelays: true },
+      frontendDelivery: { mode: frontend?.bundle ? 'relay-chunks' : 'external' },
+      ...(config.deployment || {})
+    },
+    ...(frontend ? { frontend } : {}),
+    ...matterhornMetadata
+  });
+}
+
+function matterhornAppMetadataForBuilt(built) {
+  const typeNamespace = typeNamespaceForBuilt(built);
+  const generatedTypes = generateAppTypeDeclaration(built.compositionSchema, { namespace: typeNamespace, registry: built.config.registry });
+  return {
+    typeNamespace,
+    generatedTypes
+  };
+}
+
+function schemaArtifactsForBuilt(built) {
+  return Object.freeze({
+    composition: cloneJson(built.compositionSchema),
+    model: cloneJson(built.compositionSchema.primaryPlugin.model || {}),
+    actions: Object.fromEntries((built.compositionSchema.actions || []).map((action) => [action.name, cloneJson({
+      plugin: action.plugin,
+      type: action.type,
+      payloadDefaults: action.payloadDefaults,
+      payloadSchema: action.payloadSchema,
+      requiredRole: action.requiredRole,
+      label: action.label
+    })]))
+  });
+}
+
+module.exports = {
+  matterhornAppDescriptorFromBuilt,
+  matterhornAppMetadataForBuilt,
+  schemaArtifactsForBuilt
+};

package/src/builder/matterhornApp/exports.cjs

@@ -0,0 +1,95 @@
+const { maybeClone, pascalCase } = require('./shared.cjs');
+const { buildMatterhornApp } = require('./build.cjs');
+const { matterhornAppDescriptorFromBuilt, matterhornAppMetadataForBuilt } = require('./descriptors.cjs');
+const { operationsFromDemoDefinition, replayDemo } = require('./demo.cjs');
+const { primaryHostPluginForBuilt } = require('./plugins.cjs');
+
+function createMatterhornAppExports(app, options = {}) {
+  const built = buildMatterhornApp(app, options);
+  const config = built.config;
+  const matterhornAppDescriptor = matterhornAppDescriptorFromBuilt(built);
+  const hostPlugin = primaryHostPluginForBuilt(built);
+  const metadata = matterhornAppMetadataForBuilt(built);
+  const generatedTypes = metadata.generatedTypes;
+  const schemaArtifacts = Object.freeze({
+    schema: app.toJSON(),
+    types: generatedTypes,
+    files: Object.freeze({
+      schema: 'matterhorn.schema.json',
+      types: 'matterhorn.types.d.ts'
+    })
+  });
+  const matterhornApp = Object.freeze({
+    ...matterhornAppDescriptor,
+    types: Object.freeze({ namespace: metadata.typeNamespace, declaration: generatedTypes }),
+    artifacts: schemaArtifacts
+  });
+  const demo = config.demo;
+  const exportPrefix = config.exportPrefix || config.slug;
+  const constantPrefix = (config.constantPrefix || exportPrefix).replace(/[^a-zA-Z0-9]/g, '_').toUpperCase();
+  const pascal = pascalCase(exportPrefix);
+  const example = Object.freeze({
+    id: config.example?.id || `examples/${config.slug}`,
+    title: config.example?.title || `${config.name} Matterhorn example`,
+    appPack: config.appId,
+    hostPlugin: hostPlugin.id
+  });
+  const appDefinition = Object.freeze({
+    slug: config.slug,
+    packageName: config.packageName,
+    appId: config.appId,
+    pluginId: hostPlugin.id,
+    version: config.version,
+    name: config.name,
+    frontend: maybeClone(config.frontend)
+  });
+  const appExport = {
+    built,
+    matterhornApp,
+    appPack: built.appPack,
+    hostPack: built.hostPack,
+    hostPlugin,
+    hostPlugins: built.hostPlugins,
+    hostPluginDescriptors: built.hostPluginDescriptors,
+    playerPack: built.playerPack,
+    playerPlugin: built.playerPlugin,
+    playerPacks: [built.playerPack],
+    playerPlugins: [built.playerPlugin],
+    compositionSchema: built.compositionSchema,
+    example,
+    generatedTypes,
+    schemaArtifacts,
+    appDefinition,
+    demoDefinition: demo,
+    [`${constantPrefix}_APP_ID`]: config.appId,
+    [`${constantPrefix}_PLUGIN_ID`]: hostPlugin.id,
+    [`${constantPrefix}_VERSION`]: config.version,
+    [`${exportPrefix}AppPack`]: built.appPack,
+    [`${exportPrefix}HostPack`]: built.hostPack,
+    [`${exportPrefix}HostPlugin`]: hostPlugin,
+    [`${exportPrefix}HostPlugins`]: built.hostPlugins,
+    [`${exportPrefix}HostPluginDescriptors`]: built.hostPluginDescriptors,
+    [`${exportPrefix}PlayerPack`]: built.playerPack,
+    [`${exportPrefix}PlayerPacks`]: [built.playerPack],
+    [`${exportPrefix}PlayerPlugin`]: built.playerPlugin,
+    [`${exportPrefix}PlayerPlugins`]: [built.playerPlugin],
+    [`${exportPrefix}CompositionSchema`]: built.compositionSchema,
+    [`${exportPrefix}GeneratedTypes`]: generatedTypes,
+    [`${exportPrefix}SchemaArtifacts`]: schemaArtifacts
+  };
+  appExport.createDemoOperations = (roomId = demo?.roomId || `${config.slug}_demo`) => operationsFromDemoDefinition(demo, appExport, roomId);
+  appExport[`create${pascal}DemoOperations`] = appExport.createDemoOperations;
+  appExport.createDemo = async (demoOptions = {}) => {
+    if (!demo) throw new Error(`${config.name} does not define a demo`);
+    const roomId = demoOptions.roomId || demo.roomId;
+    return replayDemo(appExport, appExport.createDemoOperations(roomId), roomId, config.summary);
+  };
+  appExport[`create${pascal}Demo`] = appExport.createDemo;
+  for (const [alias, target] of Object.entries(config.exportAliases || {})) {
+    if (appExport[target] === undefined) throw new Error(`Export alias ${alias} points at missing ${target}`);
+    appExport[alias] = appExport[target];
+  }
+  return Object.freeze(appExport);
+}
+
+module.exports = { createMatterhornAppExports };

package/src/builder/matterhornApp/frontend.cjs

@@ -0,0 +1,80 @@
+const path = require('node:path');
+
+function defaultBundleDevCommand() {
+  return {
+    command: 'npm',
+    args: ['run', 'dev:frontend', '--', '--host', '127.0.0.1', '--port', '${bundlePort}', '--strictPort']
+  };
+}
+
+function defaultBundleBuildCommand() {
+  return { command: 'npm', args: ['run', 'build:frontend'] };
+}
+
+function cleanBackgroundColor(value) {
+  if (typeof value !== 'string') return undefined;
+  const color = value.trim();
+  if (!color || color.length > 128) return undefined;
+  return color;
+}
+
+function cleanIconText(value, max = 64 * 1024) {
+  if (typeof value !== 'string') return undefined;
+  const cleaned = value.trim();
+  if (!cleaned || cleaned.length > max) return undefined;
+  return cleaned;
+}
+
+function cleanIcon(value) {
+  if (typeof value === 'string') {
+    const iconPath = cleanIconText(value, 512);
+    return iconPath ? { path: iconPath } : undefined;
+  }
+  if (!value || typeof value !== 'object') return undefined;
+  const iconPath = cleanIconText(value.path, 512);
+  const svg = cleanIconText(value.svg);
+  const label = cleanIconText(value.label, 120);
+  if (!iconPath && !svg) return undefined;
+  return {
+    ...(iconPath ? { path: iconPath } : {}),
+    ...(svg ? { svg } : {}),
+    ...(label ? { label } : {})
+  };
+}
+
+function frontendDescriptor(options) {
+  const frontend = options.frontend;
+  if (frontend === false || frontend === undefined) return undefined;
+  const appId = options.appId;
+  const slug = options.slug;
+  const name = options.name;
+  const root = path.resolve(frontend.root || options.packageRoot || process.cwd());
+  const defaultPort = frontend.defaultPort || frontend.port || 42730;
+  const bundlePort = frontend.bundlePort || frontend.port || frontend.defaultPort || 42730;
+  const bundleOverrides = frontend.bundle && typeof frontend.bundle === 'object' ? frontend.bundle : {};
+  const devEntry = bundleOverrides.devEntry || frontend.devEntry || 'src/index.ts';
+  const backgroundColor = cleanBackgroundColor(frontend.backgroundColor) || cleanBackgroundColor(bundleOverrides.backgroundColor);
+  const icon = cleanIcon(frontend.icon) || cleanIcon(bundleOverrides.icon);
+  return {
+    kind: frontend.kind || 'matterhorn-player-bundle',
+    appId,
+    root,
+    defaultPort,
+    locations: frontend.locations || [{ type: 'local-path', ref: './frontend', label: frontend.label || `${name} frontend package` }],
+    ...(backgroundColor ? { backgroundColor } : {}),
+    ...(icon ? { icon } : {}),
+    bundle: {
+      mountPath: bundleOverrides.mountPath || frontend.mountPath || `/matterhorn/apps/${appId}/`,
+      defaultPort: bundleOverrides.defaultPort || bundlePort,
+      devEntry,
+      builtEntry: bundleOverrides.builtEntry || frontend.builtEntry || `matterhorn-${slug}.js`,
+      healthPath: bundleOverrides.healthPath || frontend.healthPath || devEntry,
+      dev: bundleOverrides.dev || frontend.dev || defaultBundleDevCommand(),
+      build: bundleOverrides.build || frontend.build || defaultBundleBuildCommand(),
+      dist: bundleOverrides.dist || frontend.dist || 'frontend/dist',
+      ...(bundleOverrides.prebuilt === undefined ? {} : { prebuilt: bundleOverrides.prebuilt })
+    }
+  };
+}
+
+module.exports = { frontendDescriptor };