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

package/src/composition.cjs

@@ -0,0 +1,157 @@
+const { hashCanonical } = require("@mh-gg/base");
+const path = require("node:path");
+const { assertJsonSerializable, assertPlainObject, cloneJson, freezeJson, nonEmptyString } = require("./json.cjs");
+const { builtinMicroPluginRegistry } = require("./registry.cjs");
+const { loadJsonWithImports } = require("./imports/loader.cjs");
+const { assertValidJsonSchema } = require("./jsonSchema/validator.cjs");
+const { normalizeNotifications } = require("./notifications.cjs");
+
+const APP_COMPOSITION_SCHEMA_KIND = "matterhorn.app-composition.schema";
+const APP_COMPOSITION_SCHEMA_VERSION = 1;
+
+function normalizePluginRef(ref, registry = builtinMicroPluginRegistry) {
+  if (typeof ref === "string") {
+    const record = registry.get(ref);
+    return { key: record.schema.key, id: record.schema.id, version: record.schema.version, required: true };
+  }
+  const value = assertPlainObject(ref, "composition plugin ref");
+  const record = registry.get(value.key || value.id);
+  if (value.id && value.id !== record.schema.id) throw new Error(`Micro plugin ${value.key || value.id} resolved to ${record.schema.id}, expected ${value.id}`);
+  if (value.version && value.version !== record.schema.version) throw new Error(`Micro plugin ${record.schema.id} version mismatch: expected ${value.version}, got ${record.schema.version}`);
+  return {
+    key: record.schema.key,
+    id: record.schema.id,
+    version: record.schema.version,
+    required: value.required !== false,
+    ...(value.config === undefined ? {} : { config: value.config })
+  };
+}
+
+function normalizeActionDescriptor(action, name, composition) {
+  const value = assertPlainObject(action, `action ${name}`);
+  const plugin = value.plugin || value.pluginKey || value.pluginId || "primary";
+  const type = nonEmptyString(value.type || value.operation, `action ${name}.type`);
+  return {
+    name: value.name || name,
+    plugin,
+    type,
+    ...(value.label ? { label: String(value.label) } : {}),
+    ...(value.payloadDefaults === undefined ? {} : { payloadDefaults: value.payloadDefaults }),
+    ...(value.payloadSchema === undefined ? {} : { payloadSchema: value.payloadSchema }),
+    ...(value.requiredRole === undefined ? {} : { requiredRole: value.requiredRole })
+  };
+}
+
+function normalizeActions(actions = {}, composition) {
+  if (Array.isArray(actions)) {
+    return Object.freeze(actions.map((action, index) => normalizeActionDescriptor(action, action.name || `action${index + 1}`, composition)));
+  }
+  assertPlainObject(actions, "composition actions");
+  return Object.freeze(Object.entries(actions).map(([name, action]) => normalizeActionDescriptor(action, name, composition)));
+}
+
+function normalizeSharedScopes(sharedScopes = {}) {
+  assertPlainObject(sharedScopes, "composition sharedScopes");
+  return cloneJson(sharedScopes);
+}
+
+function createAppCompositionSchema(input = {}, registry = builtinMicroPluginRegistry) {
+  const value = assertPlainObject(input, "app composition schema");
+  const app = assertPlainObject(value.app || { id: value.appId, version: value.version, name: value.name }, "composition app");
+  const primaryPlugin = assertPlainObject(value.primaryPlugin, "composition primaryPlugin");
+  const pluginRefs = (value.plugins || []).map((ref) => normalizePluginRef(ref, registry));
+  const deduped = [];
+  const seen = new Set([primaryPlugin.id]);
+  for (const ref of pluginRefs) {
+    if (seen.has(ref.id)) continue;
+    seen.add(ref.id);
+    deduped.push(ref);
+  }
+  const composition = {
+    kind: APP_COMPOSITION_SCHEMA_KIND,
+    schemaVersion: APP_COMPOSITION_SCHEMA_VERSION,
+    app: {
+      id: nonEmptyString(app.id, "composition app.id"),
+      version: nonEmptyString(app.version, "composition app.version"),
+      name: nonEmptyString(app.name, "composition app.name")
+    },
+    primaryPlugin: {
+      id: nonEmptyString(primaryPlugin.id, "composition primaryPlugin.id"),
+      version: nonEmptyString(primaryPlugin.version, "composition primaryPlugin.version"),
+      ...(primaryPlugin.source === undefined ? {} : { source: primaryPlugin.source }),
+      ...(primaryPlugin.model === undefined ? {} : { model: cloneJson(primaryPlugin.model) })
+    },
+    plugins: deduped,
+    ...(value.sharedScopes === undefined ? {} : { sharedScopes: normalizeSharedScopes(value.sharedScopes) }),
+    views: cloneJson(value.views || []),
+    actions: normalizeActions(value.actions || {}, value),
+    routes: cloneJson(value.routes || []),
+    ...(value.notifications === undefined ? {} : { notifications: normalizeNotifications(value.notifications) })
+  };
+  assertJsonSerializable(composition, "app composition schema");
+  assertValidJsonSchema("app-composition.schema.json", composition, { label: "app composition schema" });
+  return freezeJson({ ...composition, schemaHash: hashCanonical(composition) });
+}
+
+function validateAppCompositionSchema(schema, options = {}) {
+  const value = assertPlainObject(schema, "app composition schema");
+  if (value.kind !== APP_COMPOSITION_SCHEMA_KIND) throw new Error("Invalid app composition schema kind");
+  if (value.schemaVersion !== APP_COMPOSITION_SCHEMA_VERSION) throw new Error("Invalid app composition schema version");
+  if (!Array.isArray(value.plugins) || !Array.isArray(value.actions) || value.plugins.some((plugin) => typeof plugin === "string")) return createAppCompositionSchema(value, options.registry || builtinMicroPluginRegistry);
+  assertPlainObject(value.app, "composition app");
+  assertPlainObject(value.primaryPlugin, "composition primaryPlugin");
+  nonEmptyString(value.app.id, "composition app.id");
+  nonEmptyString(value.app.version, "composition app.version");
+  nonEmptyString(value.primaryPlugin.id, "composition primaryPlugin.id");
+  if (!Array.isArray(value.plugins)) throw new Error("composition plugins must be an array");
+  if (!Array.isArray(value.actions)) throw new Error("composition actions must be an array");
+  if (!Array.isArray(value.views)) throw new Error("composition views must be an array");
+  if (value.sharedScopes !== undefined) assertPlainObject(value.sharedScopes, "composition sharedScopes");
+  if (value.notifications !== undefined) assertPlainObject(value.notifications, "composition notifications");
+  assertJsonSerializable(value, "app composition schema");
+  assertValidJsonSchema("app-composition.schema.json", value, { label: "app composition schema" });
+  return value;
+}
+
+function loadAppCompositionSchemaFile(filePath, options = {}) {
+  const resolved = path.resolve(filePath);
+  const raw = loadJsonWithImports(resolved, { baseDir: options.baseDir || path.dirname(resolved) });
+  return createAppCompositionSchema(raw, options.registry || builtinMicroPluginRegistry);
+}
+
+function appCompositionSchemaHash(schema) {
+  const copy = { ...validateAppCompositionSchema(schema) };
+  delete copy.schemaHash;
+  return hashCanonical(copy);
+}
+
+function resolveCompositionHostPluginEntries(schema, registry = builtinMicroPluginRegistry) {
+  const composition = validateAppCompositionSchema(schema, { registry });
+  return composition.plugins.map((ref) => {
+    const record = registry.get(ref.key || ref.id);
+    return Object.freeze({
+      plugin: record.plugin,
+      packageName: record.packageName,
+      exportName: record.exportName,
+      source: record.source,
+      schema: record.schema,
+      config: ref.config
+    });
+  });
+}
+
+function compositionPluginIds(schema) {
+  const composition = validateAppCompositionSchema(schema);
+  return Object.freeze([composition.primaryPlugin.id, ...composition.plugins.map((plugin) => plugin.id)]);
+}
+
+module.exports = {
+  APP_COMPOSITION_SCHEMA_KIND,
+  APP_COMPOSITION_SCHEMA_VERSION,
+  appCompositionSchemaHash,
+  compositionPluginIds,
+  loadAppCompositionSchemaFile,
+  createAppCompositionSchema,
+  resolveCompositionHostPluginEntries,
+  validateAppCompositionSchema
+};

package/src/configured.cjs

@@ -0,0 +1,41 @@
+function createConfiguredSchemaApi(schema, entries = []) {
+  const registry = schema.createMicroPluginRegistry(entries);
+  const configured = {
+    ...schema,
+    builtinMicroPluginRegistry: registry,
+    getMicroPluginSchema(selection) {
+      return registry.get(selection).schema;
+    },
+    listMicroPluginSchemas() {
+      return registry.schemas;
+    },
+    createAppCompositionSchema(input = {}, selectedRegistry = registry) {
+      return schema.createAppCompositionSchema(input, selectedRegistry);
+    },
+    validateAppCompositionSchema(value, options = {}) {
+      return schema.validateAppCompositionSchema(value, { ...options, registry: options.registry || registry });
+    },
+    loadAppCompositionSchemaFile(filePath, options = {}) {
+      return schema.loadAppCompositionSchemaFile(filePath, { ...options, registry: options.registry || registry });
+    },
+    resolveCompositionHostPluginEntries(value, selectedRegistry = registry) {
+      return schema.resolveCompositionHostPluginEntries(value, selectedRegistry);
+    },
+    createActionDispatchersFromComposition(value, options = {}) {
+      return schema.createActionDispatchersFromComposition(value, { ...options, registry: options.registry || registry });
+    },
+    pluginIdForAction(descriptor, composition, selectedRegistry = registry) {
+      return schema.pluginIdForAction(descriptor, composition, selectedRegistry);
+    },
+    defineApp(spec = {}) {
+      return schema.defineApp({ ...spec, registry: spec.registry || registry });
+    },
+    generateAppTypeDeclaration(value, options = {}) {
+      return schema.generateAppTypeDeclaration(value, { ...options, registry: options.registry || registry });
+    }
+  };
+  configured.reusableMicroPluginSchemas = configured.listMicroPluginSchemas();
+  return Object.freeze(configured);
+}
+
+module.exports = { createConfiguredSchemaApi };

package/src/configured.d.ts

@@ -0,0 +1 @@
+export function createConfiguredSchemaApi(schema: Record<string, any>, entries?: any[]): Record<string, any>;

package/src/imports/loader.cjs

@@ -0,0 +1,86 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { cloneJson } = require('../json.cjs');
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function assertRelativeJson(ref, fromFile, baseDir) {
+  if (typeof ref !== 'string' || ref.length === 0) throw new Error('Import path must be a non-empty string');
+  if (/^[a-z]+:/i.test(ref) || path.isAbsolute(ref)) throw new Error(`Schema import ${ref} must be a relative JSON file`);
+  const resolved = path.resolve(path.dirname(fromFile), ref);
+  if (!resolved.endsWith('.json')) throw new Error(`Schema import ${ref} must point to a .json file`);
+  if (baseDir) {
+    const root = path.resolve(baseDir);
+    if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) throw new Error(`Schema import ${ref} escapes ${root}`);
+  }
+  return resolved;
+}
+
+function getPath(root, dotted) {
+  if (!dotted) return root;
+  return dotted.split('.').reduce((value, part) => (value == null ? undefined : value[part]), root);
+}
+
+function setPath(root, dotted, next, merge = 'replace') {
+  const parts = dotted.split('.').filter(Boolean);
+  if (!parts.length) return mergeValue(root, next, merge);
+  const out = Array.isArray(root) ? root.slice() : { ...(root || {}) };
+  let cursor = out;
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    const part = parts[index];
+    cursor[part] = Array.isArray(cursor[part]) ? cursor[part].slice() : { ...(cursor[part] || {}) };
+    cursor = cursor[part];
+  }
+  const last = parts[parts.length - 1];
+  cursor[last] = mergeValue(cursor[last], next, merge);
+  return out;
+}
+
+function mergeValue(current, next, merge) {
+  if (merge === 'append') return [...(Array.isArray(current) ? current : []), ...(Array.isArray(next) ? next : [next])];
+  if (merge === 'merge') return { ...(current || {}), ...(next || {}) };
+  return cloneJson(next);
+}
+
+function importItems(imports) {
+  if (!imports) return [];
+  if (Array.isArray(imports)) return imports.map((item) => typeof item === 'string' ? { path: item } : item);
+  if (imports && typeof imports === 'object') {
+    return Object.entries(imports).flatMap(([into, value]) => {
+      const values = Array.isArray(value) ? value : [value];
+      return values.map((item) => typeof item === 'string' ? { path: item, into } : { ...item, into: item.into || into });
+    });
+  }
+  throw new Error('$imports must be an array or object');
+}
+
+function loadJsonWithImports(filePath, options = {}, stack = []) {
+  const resolved = path.resolve(filePath);
+  const baseDir = options.baseDir || path.dirname(resolved);
+  if (stack.includes(resolved)) throw new Error(`Circular schema import: ${[...stack, resolved].join(' -> ')}`);
+  const raw = readJson(resolved);
+  let document = { ...raw };
+  delete document.$imports;
+
+  for (const item of importItems(raw.$imports)) {
+    if (!item || typeof item !== 'object') throw new Error('Schema import entries must be objects');
+    const importedPath = assertRelativeJson(item.path, resolved, baseDir);
+    const importedDoc = loadJsonWithImports(importedPath, { ...options, baseDir }, [...stack, resolved]);
+    const selected = item.select ? getPath(importedDoc, item.select) : importedDoc;
+    if (selected === undefined) throw new Error(`Schema import ${item.path} did not contain ${item.select}`);
+    if (!item.into) {
+      document = mergeValue(document, selected, item.merge || 'merge');
+    } else {
+      document = setPath(document, item.into, selected, item.merge || 'replace');
+    }
+  }
+  return document;
+}
+
+module.exports = {
+  getPath,
+  loadJsonWithImports,
+  setPath
+};

package/src/index.cjs

@@ -0,0 +1,12 @@
+module.exports = {
+  ...require('./json.cjs'),
+  ...require('./microPlugin.cjs'),
+  ...require('./registry.cjs'),
+  ...require('./composition.cjs'),
+  ...require('./actions.cjs'),
+  ...require('./imports/loader.cjs'),
+  ...require('./jsonSchema/validator.cjs'),
+  ...require('./model/index.cjs'),
+  ...require('./types/index.cjs'),
+  ...require('./builder/index.cjs')
+};

package/src/index.d.ts

@@ -0,0 +1,168 @@
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+export type PayloadSchemaSpec =
+  | { type?: "any" | "string" | "number" | "boolean" | "enum" | "array" | "object" | "record" | "literal"; [key: string]: unknown }
+  | string;
+
+export interface Schema<T> {
+  optional(): Schema<T | undefined>;
+  nullable(): Schema<T | null>;
+  default(value: NonNullable<T>): Schema<NonNullable<T>>;
+  clearable(): Schema<T | null>;
+  toJSON(): PayloadSchemaSpec;
+}
+
+type InferSchema<S> = S extends Schema<infer T> ? T : unknown;
+type RequiredKeys<S> = { [K in keyof S]: undefined extends InferSchema<S[K]> ? never : K }[keyof S];
+type OptionalKeys<S> = { [K in keyof S]: undefined extends InferSchema<S[K]> ? K : never }[keyof S];
+export type PayloadOf<S> = { [K in RequiredKeys<S>]: Exclude<InferSchema<S[K]>, undefined> } & { [K in OptionalKeys<S>]?: InferSchema<S[K]> };
+export type { AppDef, AppSpec, EmitOptions, EmitResult, MatterhornAppOptions, MatterhornFrontendCommand, MatterhornFrontendIcon, MatterhornFrontendOptions, NotificationDef, NotificationAudience, NotificationScope, NotificationEntity, NotificationPresentation, NotificationLink, NotificationRead, NotificationReadPolicy, NotificationDelivery, NotificationOn, NotificationExpression, NotificationsBlock } from "./app";
+import type { AppDef, AppSpec, EmitOptions, EmitResult, MatterhornAppOptions } from "./app";
+
+export const p: {
+  any(): Schema<unknown>;
+  string(opts?: { max?: number; min?: number; nonEmpty?: boolean; nullable?: boolean; trim?: boolean; truncate?: boolean }): Schema<string>;
+  number(opts?: { min?: number; max?: number }): Schema<number>;
+  boolean(): Schema<boolean>;
+  enum<const V extends readonly string[]>(values: V, opts?: { fallback?: V[number] }): Schema<V[number]>;
+  array<T>(items?: Schema<T>, opts?: Record<string, unknown>): Schema<T[]>;
+  object<const S extends Record<string, Schema<unknown>>>(shape: S, opts?: { additional?: boolean }): Schema<PayloadOf<S>>;
+  record<T>(values?: Schema<T>, opts?: Record<string, unknown>): Schema<Record<string, T>>;
+  literal<const T extends Json>(value: T): Schema<T>;
+};
+
+export type Ref<T = unknown> = string & { readonly __ref?: T };
+export type PayloadRefs<P> = {
+  payload<K extends keyof P & string>(key: K): Ref<P[K]>;
+  payload<K extends keyof P & string, F extends Json>(key: K, fallback: F): { $expr: Ref<P[K]>; fallback: F };
+  actor(field?: "memberId" | "displayName" | string): Ref<string>;
+  app(field?: "id" | string): Ref<string>;
+  room(field?: "id" | string): Ref<string>;
+  profile(field?: "id" | string): Ref<string>;
+  now(): Ref<number>;
+  operation(field?: "id" | "type" | string): Ref<string>;
+  newId(prefix: string): Ref<string>;
+  literal(value: Json): { $literal: Json };
+  expr(value: string): { $expr: string };
+};
+export const ref: PayloadRefs<Record<string, never>>;
+
+export type { ReadClass, IntegrityClass, ShapeSpec } from "./streamKey";
+
+export interface Collection<T = unknown> {
+  readonly name: string;
+  readonly storage: "array" | "map";
+  readonly readClass: import("./streamKey").ReadClass;
+  readonly integrityClass: import("./streamKey").IntegrityClass;
+}
+export type Effect = { kind: string; [key: string]: unknown };
+export type Guard = { kind: string; [key: string]: unknown };
+export type GuardOperand = { kind: string; [key: string]: unknown };
+
+export const fx: {
+  noop(): Effect;
+  create<T>(collection: Collection<T> | string, spec: { id?: Ref<string>; idPrefix?: string; fields: Partial<Record<keyof T & string, unknown>> | Record<string, unknown>; activity?: string; recordLabel?: string }): Effect;
+  update<T>(collection: Collection<T> | string, spec: { id: Ref<string>; set?: Partial<Record<keyof T & string, unknown>> | Record<string, unknown>; fields?: Record<string, unknown>; activity?: string; recordLabel?: string }): Effect;
+  mark<T>(collection: Collection<T> | string, spec: { id: Ref<string>; set?: Partial<Record<keyof T & string, unknown>> | Record<string, unknown>; fields?: Record<string, unknown>; activity?: string; recordLabel?: string }): Effect;
+  merge(spec: { path: string; fields?: unknown; deleteNullFields?: boolean; activity?: string }): Effect;
+  append(pathOrCollection: Collection | string, item?: unknown): Effect;
+  toggleReaction<T>(collection: Collection<T> | string, spec: { id: Ref<string>; emoji: Ref<string>; activity?: string; recordLabel?: string }): Effect;
+  insertIntoArray<T>(collection: Collection<T> | string, spec: { id?: Ref<string>; matchId?: Ref<string>; field: keyof T & string; value: unknown; at?: unknown; position?: unknown; activity?: string; recordLabel?: string }): Effect;
+  removeFromArray<T>(collection: Collection<T> | string, spec: { id?: Ref<string>; matchId?: Ref<string>; field: keyof T & string; value: unknown; activity?: string; recordLabel?: string }): Effect;
+  upsertActor<T>(collection: Collection<T> | string, spec: { fields: Partial<Record<keyof T & string, unknown>> | Record<string, unknown>; activity?: string; recordLabel?: string }): Effect;
+};
+
+export const guard: {
+  path(path: string): GuardOperand;
+  length(path: string): GuardOperand;
+  value(value: Json): GuardOperand;
+  expr(expr: string): GuardOperand;
+  ownerOrRole<T>(collection: Collection<T> | string, spec: { id?: Ref<string>; match?: Ref<string>; ownerField?: keyof T & string; roles?: string[]; message?: string; recordLabel?: string }): Guard;
+  flagClear<T>(collection: Collection<T> | string, spec: { id?: Ref<string>; match?: Ref<string>; flag: keyof T & string; message?: string; recordLabel?: string }): Guard;
+  eq(left: unknown, right: unknown, message?: string): Guard;
+  ne(left: unknown, right: unknown, message?: string): Guard;
+  lt(left: unknown, right: unknown, message?: string): Guard;
+  lte(left: unknown, right: unknown, message?: string): Guard;
+  gt(left: unknown, right: unknown, message?: string): Guard;
+  gte(left: unknown, right: unknown, message?: string): Guard;
+  exists(path: string, message?: string): Guard;
+  and(...guards: Guard[]): Guard;
+  or(...guards: Guard[]): Guard;
+  not(item: Guard): Guard;
+  noop(): Guard;
+};
+
+export type OperationDef<P = unknown> = { authorize?: object; payload: object; effects: Effect[]; guards?: Guard[] };
+export function op<const S extends Record<string, Schema<unknown>>, P = PayloadOf<S>>(
+  spec: { authorize?: object; payload?: S },
+  build: (builders: { ref: PayloadRefs<P>; fx: typeof fx; guard: typeof guard }) => { effects: Effect[]; guards?: Guard[]; guard?: Guard }
+): OperationDef<P>;
+
+export interface Model<State = unknown, Operations extends Record<string, OperationDef> = Record<string, OperationDef>> {
+  readonly collections: { [K in keyof State & string]: Collection<State[K] extends Array<infer T> ? T : State[K] extends Record<string, infer T> ? T : unknown> };
+  withOperations<O extends Record<string, OperationDef>>(ops: O): Model<State, O>;
+  operation<K extends string, O extends OperationDef>(name: K, definition: O): Model<State, Operations & Record<K, O>>;
+  toJSON(): object;
+}
+export function defineModel<const State extends Record<string, unknown>>(spec: {
+  roles?: Record<string, { name?: string; rank?: number; system?: boolean; description?: string; color?: string }>;
+  state: State | { initial: State; roomIdPath?: string };
+  shapes?: Record<keyof State & string, ShapeSpec>;
+  views?: object;
+  publicView?: object;
+  capabilities?: object;
+}): Model<State>;
+
+export interface QueryDef<Result = unknown> { toJSON(): object; }
+export const q: {
+  state(): QueryDef<unknown>;
+  collection<T>(collection: Collection<T>, options?: { path?: string; includeArchived?: boolean }): QueryDef<T[]>;
+  count<T>(collection: Collection<T>, options?: { path?: string }): QueryDef<number>;
+};
+
+export interface ScopeDef {
+  readonly key: string;
+  readonly view: object;
+  readonly edit: object;
+  readonly readClass: ReadClass;
+  readonly integrityClass: IntegrityClass;
+  toJSON(): object;
+}
+export function defineScope(spec: {
+  key?: string;
+  name?: string;
+  type?: string;
+  scopeType?: string;
+  id?: string;
+  scopeId?: string;
+  identity?: string;
+  participants?: string;
+  collections: Array<Collection | string>;
+  description?: string;
+  readClass?: ReadClass;
+  integrityClass?: IntegrityClass;
+}): ScopeDef;
+
+export { streamKey } from "./streamKey";
+
+export function defineApp(spec: AppSpec): AppDef;
+
+export function defineNotification(spec: NotificationDef): NotificationDef;
+export function defineNotificationsBlock(spec: { schemaVersion?: number; definitions: Record<string, NotificationDef | (() => NotificationDef)> }): NotificationsBlock;
+
+export function emitAppArtifacts(app: AppDef, options?: EmitOptions): EmitResult;
+export function splitCompositionForFiles(composition: object, options?: object): { composition: object; model: object; actions: object };
+export function buildMatterhornApp(app: AppDef, options?: MatterhornAppOptions): object;
+export function createMatterhornAppBundle(app: AppDef, options?: MatterhornAppOptions): Record<string, unknown>;
+export function createMatterhornAppDescriptor(app: AppDef, options?: MatterhornAppOptions): object;
+export function createMatterhornAppExports(app: AppDef, options?: MatterhornAppOptions): Record<string, unknown>;
+export function emitMatterhornAppBundle(app: AppDef, options?: MatterhornAppOptions & { outDir?: string; fileName?: string }): { bundlePath: string; bundle: Record<string, unknown> };
+export function operationsFromDemoDefinition(demo: object | undefined, app: object, roomId?: string): object[];
+export function genericSummary(state: object, pluginId: string): object;
+
+export function generateAppTypeDeclaration(schema: object, options?: { namespace?: string }): string;
+export function namespaceNameForApp(schemaOrApp: object, fallback?: string): string;
+export function inlinePayloadType(schema: object): string;
+export function typeFromSchema(schema: PayloadSchemaSpec): string;
+
+export * from "./runtime-exports";

package/src/json.cjs

@@ -0,0 +1,70 @@
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
+  return value;
+}
+
+function cloneJson(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function assertJsonSerializable(value, name = "value", path = name) {
+  if (value === undefined) return;
+  if (value === null) return;
+  const type = typeof value;
+  if (type === "string" || type === "number" || type === "boolean") {
+    if (type === "number" && !Number.isFinite(value)) throw new Error(`${path} must be finite`);
+    return;
+  }
+  if (type === "function" || type === "symbol" || type === "bigint") throw new Error(`${path} must be JSON serializable`);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertJsonSerializable(item, name, `${path}[${index}]`));
+    return;
+  }
+  if (type === "object") {
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new Error(`${path} must be a plain JSON object`);
+    for (const [key, item] of Object.entries(value)) {
+      if (item !== undefined) assertJsonSerializable(item, name, `${path}.${key}`);
+    }
+    return;
+  }
+  throw new Error(`${path} must be JSON serializable`);
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const item of Object.values(value)) deepFreeze(item);
+  return value;
+}
+
+function freezeJson(value) {
+  assertJsonSerializable(value);
+  return deepFreeze(cloneJson(value));
+}
+
+function jsonArray(value, name) {
+  if (!Array.isArray(value)) throw new Error(`${name} must be an array`);
+  return value;
+}
+
+function nonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${name} must be a non-empty string`);
+  return value.trim();
+}
+
+function optionalString(value, name) {
+  if (value === undefined || value === null) return undefined;
+  return nonEmptyString(value, name);
+}
+
+module.exports = {
+  assertJsonSerializable,
+  assertPlainObject,
+  cloneJson,
+  deepFreeze,
+  freezeJson,
+  jsonArray,
+  nonEmptyString,
+  optionalString
+};

package/src/jsonSchema/validator.cjs

@@ -0,0 +1,131 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCHEMA_ROOT = path.resolve(__dirname, '../../schemas');
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function readSchema(name) {
+  const file = path.join(SCHEMA_ROOT, name);
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function valueType(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  return typeof value;
+}
+
+function isType(value, expected) {
+  if (expected === 'integer') return Number.isInteger(value);
+  if (expected === 'number') return typeof value === 'number' && Number.isFinite(value);
+  if (expected === 'object') return value && typeof value === 'object' && !Array.isArray(value);
+  if (expected === 'array') return Array.isArray(value);
+  if (expected === 'string') return typeof value === 'string';
+  if (expected === 'boolean') return typeof value === 'boolean';
+  if (expected === 'null') return value === null;
+  return false;
+}
+
+function refTarget(schema, ref) {
+  if (!ref.startsWith('#/')) throw new Error(`Only local JSON Schema refs are supported: ${ref}`);
+  return ref.slice(2).split('/').reduce((node, part) => node?.[part.replace(/~1/g, '/').replace(/~0/g, '~')], schema);
+}
+
+function validateNode(rootSchema, schema, value, pathName, errors) {
+  if (!schema || typeof schema !== 'object') return;
+  if (schema.$ref) return validateNode(rootSchema, refTarget(rootSchema, schema.$ref), value, pathName, errors);
+
+  if (schema.const !== undefined && JSON.stringify(value) !== JSON.stringify(schema.const)) {
+    errors.push(`${pathName} must equal ${JSON.stringify(schema.const)}`);
+    return;
+  }
+  if (schema.enum && !schema.enum.some((item) => JSON.stringify(item) === JSON.stringify(value))) errors.push(`${pathName} must be one of ${schema.enum.join(', ')}`);
+  if (schema.oneOf) {
+    const matches = schema.oneOf.filter((candidate) => {
+      const nested = [];
+      validateNode(rootSchema, candidate, value, pathName, nested);
+      return nested.length === 0;
+    });
+    if (matches.length !== 1) errors.push(`${pathName} must match exactly one schema variant`);
+    return;
+  }
+  if (schema.anyOf) {
+    const ok = schema.anyOf.some((candidate) => {
+      const nested = [];
+      validateNode(rootSchema, candidate, value, pathName, nested);
+      return nested.length === 0;
+    });
+    if (!ok) errors.push(`${pathName} must match one schema variant`);
+    return;
+  }
+  if (schema.allOf) {
+    for (const candidate of schema.allOf) validateNode(rootSchema, candidate, value, pathName, errors);
+  }
+
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((type) => isType(value, type))) {
+      errors.push(`${pathName} must be ${types.join(' or ')}, got ${valueType(value)}`);
+      return;
+    }
+  }
+
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) errors.push(`${pathName} must have length >= ${schema.minLength}`);
+    if (schema.pattern && !(new RegExp(schema.pattern).test(value))) errors.push(`${pathName} must match ${schema.pattern}`);
+  }
+
+  if (typeof value === 'number') {
+    if (schema.minimum !== undefined && value < schema.minimum) errors.push(`${pathName} must be >= ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) errors.push(`${pathName} must be <= ${schema.maximum}`);
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) errors.push(`${pathName} must have at least ${schema.minItems} items`);
+    if (schema.items) value.forEach((item, index) => validateNode(rootSchema, schema.items, item, `${pathName}[${index}]`, errors));
+    if (schema.uniqueItems) {
+      const seen = new Set(value.map((item) => JSON.stringify(item)));
+      if (seen.size !== value.length) errors.push(`${pathName} must contain unique items`);
+    }
+  }
+
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    for (const key of schema.required || []) {
+      if (value[key] === undefined) errors.push(`${pathName}.${key} is required`);
+    }
+    const properties = schema.properties || {};
+    for (const [key, propertyValue] of Object.entries(value)) {
+      if (properties[key]) validateNode(rootSchema, properties[key], propertyValue, `${pathName}.${key}`, errors);
+      else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') validateNode(rootSchema, schema.additionalProperties, propertyValue, `${pathName}.${key}`, errors);
+      else if (schema.additionalProperties === false) errors.push(`${pathName}.${key} is not allowed`);
+    }
+  }
+}
+
+function validateJsonSchema(schema, value, options = {}) {
+  const errors = [];
+  validateNode(schema, schema, value, options.name || '$', errors);
+  return errors.length ? { ok: false, errors } : { ok: true, value: clone(value) };
+}
+
+function assertValidJsonSchema(name, value, options = {}) {
+  const schema = typeof name === 'string' ? readSchema(name) : name;
+  const result = validateJsonSchema(schema, value, { name: options.name || '$' });
+  if (!result.ok) {
+    const error = new Error(`${options.label || 'JSON schema validation'} failed: ${result.errors.slice(0, 6).join('; ')}`);
+    error.errors = result.errors;
+    throw error;
+  }
+  return value;
+}
+
+module.exports = {
+  SCHEMA_ROOT,
+  assertValidJsonSchema,
+  readSchema,
+  validateJsonSchema
+};