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

package/src/types/actionTypes.cjs

@@ -0,0 +1,164 @@
+const { builtinMicroPluginRegistry } = require('../registry.cjs');
+const { coreActionPayloadSchemas } = require('./coreActionPayloadSchemas.cjs');
+const { quoteProp, schemaEntries, typeFromSchema } = require('./schema.cjs');
+
+function isPrimaryAction(action, composition) {
+  return !action.plugin || action.plugin === 'primary' || action.plugin === '$primary' || action.plugin === composition.primaryPlugin.id;
+}
+
+function isCoreAction(action) {
+  return action.plugin === 'core' || action.plugin === 'matterhorn.core';
+}
+
+function operationDescriptorForAction(action, composition, model, registry = builtinMicroPluginRegistry) {
+  if (isPrimaryAction(action, composition)) return model.operations?.[action.type];
+  if (isCoreAction(action) && coreActionPayloadSchemas[action.type]) {
+    return { payload: coreActionPayloadSchemas[action.type], authorize: action.requiredRole ? { roles: [action.requiredRole] } : undefined };
+  }
+  try {
+    return registry.get(action.plugin).schema.schemas.operations[action.type];
+  } catch {
+    return undefined;
+  }
+}
+
+function payloadSchemaForAction(action, composition, model, registry = builtinMicroPluginRegistry) {
+  if (action.payloadSchema) return action.payloadSchema;
+  const descriptor = operationDescriptorForAction(action, composition, model, registry);
+  return descriptor?.payload || descriptor || { additional: true };
+}
+
+function authorizationRolesForAction(action, composition, model, registry = builtinMicroPluginRegistry) {
+  const roles = action.authorize?.roles
+    || (action.requiredRole ? [action.requiredRole] : undefined)
+    || action.payloadSchema?.authorize?.roles
+    || operationDescriptorForAction(action, composition, model, registry)?.authorize?.roles
+    || payloadSchemaForAction(action, composition, model, registry)?.authorize?.roles
+    || [];
+  return Array.isArray(roles) ? roles.filter(Boolean).map(String) : [];
+}
+
+function unionParts(type) {
+  return String(type || 'unknown').split(' | ').map((part) => part.trim()).filter(Boolean);
+}
+
+function withScalarAlias(type, alias) {
+  const parts = unionParts(type).map((part) => {
+    if (part === 'string') return alias;
+    if (part === 'string[]') return `${alias}[]`;
+    return part;
+  });
+  if (!parts.includes('null')) return [...new Set(parts)].join(' | ');
+  return [...new Set(parts.filter((part) => part !== 'null')), 'null'].join(' | ');
+}
+
+function typeForPayloadField(action, name, spec) {
+  if (action.type === 'comments.resolve' && name === 'resolved') return 'boolean';
+  if (action.type.startsWith('presence.') && name === 'status') return 'PresenceStatus';
+  if (action.type.startsWith('media.room.') && name === 'media') return 'MediaFlags';
+  if (action.type.startsWith('media.room.') && name === 'roleAccess') return 'RoomRoleAccess';
+  if (action.type.startsWith('message.') && name === 'embeds') return 'MessageEmbed[]';
+  if (action.type === 'file.upload' && name === 'event') return 'NostrEvent';
+  if (name === 'channelId') return withScalarAlias(typeFromSchema(spec), 'ChannelId');
+  if (name === 'messageId' || name === 'replyToId') return withScalarAlias(typeFromSchema(spec), 'MessageId');
+  if (name === 'roleId') return withScalarAlias(typeFromSchema(spec), 'RoleId');
+  if (name === 'roleIds') return withScalarAlias(typeFromSchema(spec), 'RoleId');
+  if (name === 'memberId' || name === 'userId') return withScalarAlias(typeFromSchema(spec), 'MemberId');
+  if (name.endsWith('MemberId')) return withScalarAlias(typeFromSchema(spec), 'MemberId');
+  if (name === 'userIds') return 'MemberId[]';
+  if (name === 'roomId') return withScalarAlias(typeFromSchema(spec), 'RoomId');
+  if (name === 'threadId') return withScalarAlias(typeFromSchema(spec), 'ThreadId');
+  if (name === 'commentId' || name === 'parentId') return withScalarAlias(typeFromSchema(spec), 'CommentId');
+  if (name === 'embedId') return withScalarAlias(typeFromSchema(spec), 'EmbedId');
+  if (name === 'shareId') return withScalarAlias(typeFromSchema(spec), 'ShareId');
+  if (name === 'scopeType') return withScalarAlias(typeFromSchema(spec), 'ScopeType');
+  return typeFromSchema(spec);
+}
+
+function typeLabelForField(spec) {
+  if (Array.isArray(spec)) return 'string';
+  if (!spec || typeof spec !== 'object') return 'string';
+  if (spec.type === 'array') return 'array';
+  if (spec.type === 'record') return 'record';
+  if (spec.type === 'object') return 'object';
+  if (spec.type === 'enum') return 'enum';
+  return spec.type || 'string';
+}
+
+function fieldDoc(name, spec, optional = false) {
+  const constraints = [];
+  const label = typeLabelForField(spec);
+  if (spec && typeof spec === 'object') {
+    if (spec.min !== undefined) constraints.push(`>= ${spec.min}`);
+    if (spec.max !== undefined) constraints.push(`<= ${spec.max}`);
+    if (spec.nullable || spec.clearable) constraints.push('nullable');
+    if (optional && (spec.nullable || spec.clearable)) constraints.push('omit to leave unchanged; null to clear');
+  }
+  return `${name}: ${[label, ...constraints].join(', ')}`;
+}
+
+function actionPayloadDocs(action, composition, model, registry = builtinMicroPluginRegistry) {
+  const docs = [];
+  const roles = authorizationRolesForAction(action, composition, model, registry);
+  if (roles.length === 1) docs.push(`Requires \`${roles[0]}\` role.`);
+  else if (roles.length > 1) docs.push(`Requires one of ${roles.map((role) => `\`${role}\``).join(', ')} roles.`);
+  const payloadSchema = payloadSchemaForAction(action, composition, model, registry);
+  for (const [name, spec] of schemaEntries(payloadSchema.required)) {
+    docs.push(fieldDoc(name, spec));
+  }
+  for (const [name, spec] of schemaEntries(payloadSchema.optional)) {
+    docs.push(fieldDoc(name, spec, true));
+  }
+  return docs;
+}
+
+function actionPayloadType(action, composition, model, registry = builtinMicroPluginRegistry) {
+  const payloadSchema = payloadSchemaForAction(action, composition, model, registry);
+  const required = schemaEntries(payloadSchema.required);
+  const optional = schemaEntries(payloadSchema.optional);
+  const requiredNames = new Set(required.map(([name]) => name));
+  const optionalNames = new Set(optional.map(([name]) => name));
+  const hasRequiredScope = requiredNames.has('scopeType') && requiredNames.has('scopeId');
+  const hasOptionalScope = optionalNames.has('scopeType') && optionalNames.has('scopeId');
+  const defaults = action.payloadDefaults || {};
+  const chunks = [];
+  for (const [name, spec] of required) {
+    if ((hasRequiredScope || hasOptionalScope) && (name === 'scopeType' || name === 'scopeId')) continue;
+    chunks.push(`${quoteProp(name)}${Object.prototype.hasOwnProperty.call(defaults, name) ? '?' : ''}: ${typeForPayloadField(action, name, spec)}`);
+  }
+  for (const [name, spec] of optional) {
+    if ((hasRequiredScope || hasOptionalScope) && (name === 'scopeType' || name === 'scopeId')) continue;
+    chunks.push(`${quoteProp(name)}?: ${typeForPayloadField(action, name, spec)}`);
+  }
+  const hasShape = payloadSchema.required !== undefined || payloadSchema.optional !== undefined;
+  if (payloadSchema.additional === true || !hasShape) chunks.push('[key: string]: unknown');
+  const objectType = chunks.length ? `{ ${chunks.join('; ')} }` : 'Record<string, never>';
+  if (hasRequiredScope) return objectType === 'Record<string, never>' ? 'ScopeRef' : `${objectType} & ScopeRef`;
+  if (hasOptionalScope) return objectType === 'Record<string, never>' ? 'Partial<ScopeRef>' : `${objectType} & Partial<ScopeRef>`;
+  return objectType;
+}
+
+function actionPayloadEntries(composition, model, registry = builtinMicroPluginRegistry) {
+  const entries = [];
+  for (const action of composition.actions || []) {
+    entries.push([
+      action.name,
+      actionPayloadType(action, composition, model, registry),
+      action.type,
+      actionPayloadDocs(action, composition, model, registry)
+    ]);
+  }
+  return entries;
+}
+
+function actionsMap(composition, model, registry = builtinMicroPluginRegistry) {
+  return Object.fromEntries(actionPayloadEntries(composition, model, registry).map(([name, payloadType]) => [name, payloadType]));
+}
+
+module.exports = {
+  actionPayloadEntries,
+  actionPayloadDocs,
+  actionsMap,
+  isCoreAction,
+  payloadSchemaForAction
+};

package/src/types/coreActionPayloadSchemas.cjs

@@ -0,0 +1,35 @@
+const scopedRole = { type: 'enum', values: ['none', 'viewer', 'editor', 'moderator', 'admin'] };
+
+const coreActionPayloadSchemas = Object.freeze({
+  'dm.message': {
+    required: { userIds: { type: 'array', items: { type: 'string' } }, body: { type: 'string' } },
+    optional: { topicKey: { type: 'string' } }
+  },
+  'scope.role.set': {
+    required: { scopeType: { type: 'string' }, scopeId: { type: 'string' } },
+    optional: { target: { type: 'string' }, role: scopedRole, defaultRole: scopedRole, reason: { type: 'string' } }
+  },
+  'access.role.define': {
+    required: {
+      roleId: { type: 'string' },
+      grants: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: { scopeType: { type: 'string' }, scopeId: { type: 'string' }, role: scopedRole }
+        }
+      }
+    },
+    optional: { name: { type: 'string' }, reason: { type: 'string' } }
+  },
+  'access.role.assign': {
+    required: { target: { type: 'string' }, roleId: { type: 'string' } },
+    optional: { reason: { type: 'string' } }
+  },
+  'access.role.unassign': {
+    required: { target: { type: 'string' }, roleId: { type: 'string' } },
+    optional: { reason: { type: 'string' } }
+  }
+});
+
+module.exports = { coreActionPayloadSchemas };

package/src/types/coreFeatures.cjs

@@ -0,0 +1,29 @@
+function hasCoreDirectMessages(composition) {
+  return (composition.actions || []).some((action) => {
+    return (action.plugin === 'core' || action.plugin === 'matterhorn.core') && action.type === 'dm.message';
+  });
+}
+
+function hasCoreScopedAccess(composition) {
+  return (composition.actions || []).some((action) => {
+    const core = action.plugin === 'core' || action.plugin === 'matterhorn.core';
+    return core && (action.type === 'scope.role.set' || String(action.type || '').startsWith('access.role.'));
+  });
+}
+
+function coreStateFields(composition) {
+  const fields = {};
+  if (hasCoreDirectMessages(composition)) {
+    fields.members = { type: 'Record<MemberId, Member>', optional: false };
+    fields.directThreads = { type: 'Record<ThreadId, DirectThread>', optional: false };
+    fields.directMessages = { type: 'Record<MessageId, DirectMessage>', optional: false };
+  }
+  if (hasCoreScopedAccess(composition)) fields.access = { type: 'CoreAccessState', optional: false };
+  return fields;
+}
+
+module.exports = {
+  coreStateFields,
+  hasCoreDirectMessages,
+  hasCoreScopedAccess
+};

package/src/types/entities.cjs

@@ -0,0 +1,131 @@
+const {
+  literalType,
+  sortedObjectEntries,
+  typeFromExpression,
+  typeNameForCollection
+} = require('./schema.cjs');
+const { finalizeEntityFields, mergeFieldInfo, recordKeyTypeForCollection } = require('./entityAliases.cjs');
+const { interfaceBlock } = require('./interfaceBlock.cjs');
+const {
+  coreStateFields,
+  pluginFlatStateFields,
+  standardPluginEntityTypes
+} = require('./pluginEntities.cjs');
+
+function fieldsFromLiteral(record) {
+  const fields = {};
+  for (const [key, value] of Object.entries(record || {})) fields[key] = { type: literalType(value), optional: value === undefined };
+  return fields;
+}
+
+function fieldsFromEffect(effect, payloadSchema) {
+  const fields = {};
+  const updateOnly = effect.kind === 'updateRecord' || effect.kind === 'markRecord' || effect.kind === 'upsertActorRecord';
+  for (const [key, value] of Object.entries(effect.fields || {})) {
+    const info = typeFromExpression(value, payloadSchema);
+    fields[key] = updateOnly ? { ...info, optional: true, fromUpdate: true } : { ...info, optional: false };
+  }
+  return fields;
+}
+
+function recordCreateShape(createStats, collection, fields) {
+  const stats = createStats.get(collection) || { count: 0, fields: new Map() };
+  stats.count += 1;
+  for (const [key, info] of Object.entries(fields || {})) {
+    const field = stats.fields.get(key) || { count: 0, optional: false };
+    field.count += 1;
+    field.optional = field.optional || info.optional === true;
+    stats.fields.set(key, field);
+  }
+  createStats.set(collection, stats);
+}
+
+function applyCreateRequiredness(entities, createStats) {
+  for (const [collection, stats] of createStats.entries()) {
+    const fields = entities.get(collection);
+    if (!fields || !stats.count) continue;
+    for (const [key, info] of Object.entries(fields)) {
+      const created = stats.fields.get(key);
+      info.optional = !created || created.optional || created.count < stats.count;
+    }
+  }
+}
+
+function mergeEntityFields(entities, collection, fields) {
+  const existing = entities.get(collection) || {};
+  for (const [key, info] of Object.entries(fields)) existing[key] = mergeFieldInfo(existing[key], info);
+  entities.set(collection, existing);
+}
+
+function arrayFieldFromEffect(effect, payloadSchema) {
+  if (!effect.arrayField || !['insertIdIntoRecordArray', 'removeIdFromRecordArray'].includes(effect.kind)) return undefined;
+  const item = typeFromExpression(effect.value, payloadSchema);
+  return { [effect.arrayField]: { type: `${item.type || 'unknown'}[]`, optional: true, fromUpdate: true } };
+}
+
+function collectPrimaryEntities(model) {
+  const initial = model.state?.initial || {};
+  const entities = new Map();
+  const collectionStorage = new Map();
+  const createStats = new Map();
+  for (const [key, value] of Object.entries(initial)) {
+    if (key === 'activity') continue;
+    if (Array.isArray(value)) collectionStorage.set(key, 'array');
+    else if (value && typeof value === 'object') collectionStorage.set(key, 'map');
+    if (value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length > 0) {
+      for (const record of Object.values(value)) {
+        if (record && typeof record === 'object' && !Array.isArray(record)) {
+          const fields = fieldsFromLiteral(record);
+          recordCreateShape(createStats, key, fields);
+          mergeEntityFields(entities, key, fields);
+        }
+      }
+    }
+  }
+  for (const operation of Object.values(model.operations || {})) {
+    for (const effect of operation.effects || []) {
+      if (!effect.collection) continue;
+      const arrayField = arrayFieldFromEffect(effect, operation.payload || {});
+      if (arrayField) mergeEntityFields(entities, effect.collection, arrayField);
+      if (!['createRecord', 'updateRecord', 'markRecord', 'upsertActorRecord'].includes(effect.kind)) continue;
+      collectionStorage.set(effect.collection, effect.storage || collectionStorage.get(effect.collection) || 'map');
+      const fields = fieldsFromEffect(effect, operation.payload || {});
+      if (effect.kind === 'createRecord') {
+        fields.id = mergeFieldInfo(fields.id, { type: 'string', optional: false });
+        recordCreateShape(createStats, effect.collection, fields);
+      }
+      mergeEntityFields(entities, effect.collection, fields);
+    }
+  }
+  applyCreateRequiredness(entities, createStats);
+  finalizeEntityFields(entities);
+  return { entities, collectionStorage };
+}
+
+function primaryStateFields(model, entityData) {
+  const initial = model.state?.initial || {};
+  const fields = {};
+  for (const [key, value] of sortedObjectEntries(initial)) {
+    if (key === 'activity') fields[key] = { type: 'Activity[]', optional: false };
+    else if (Array.isArray(value) || entityData.collectionStorage.get(key) === 'array') fields[key] = { type: entityData.entities.has(key) ? `${typeNameForCollection(key)}[]` : 'unknown[]', optional: false };
+    else if (value && typeof value === 'object') fields[key] = { type: entityData.entities.has(key) ? `Record<${recordKeyTypeForCollection(key)}, ${typeNameForCollection(key)}>` : literalType(value), optional: false };
+    else fields[key] = { type: literalType(value), optional: false };
+  }
+  return fields;
+}
+
+function collectionItemType(collection, entityData) {
+  if (!collection) return 'unknown';
+  if (entityData.entities.has(collection)) return typeNameForCollection(collection);
+  return 'unknown';
+}
+
+module.exports = {
+  collectPrimaryEntities,
+  collectionItemType,
+  coreStateFields,
+  interfaceBlock,
+  pluginFlatStateFields,
+  primaryStateFields,
+  standardPluginEntityTypes
+};

package/src/types/entityAliases.cjs

@@ -0,0 +1,84 @@
+const { union } = require('./schema.cjs');
+
+function unionParts(type) {
+  return String(type || 'unknown').split(' | ').map((part) => part.trim()).filter(Boolean);
+}
+
+function removeUnionPart(type, target) {
+  const parts = unionParts(type).filter((part) => part !== target);
+  return parts.length ? union(parts) : type;
+}
+
+function hasUnionPart(type, target) {
+  return unionParts(type).includes(target);
+}
+
+function mergeFieldInfo(current, next) {
+  if (!current) return next;
+  if (current.type === 'unknown[]' && next.type !== 'unknown[]' && String(next.type).endsWith('[]')) {
+    return { type: next.type, optional: current.optional && next.optional };
+  }
+  if (next.type === 'unknown[]' && current.type !== 'unknown[]' && String(current.type).endsWith('[]')) {
+    return { type: current.type, optional: current.optional && next.optional };
+  }
+  const nextType = next.fromUpdate && !hasUnionPart(current.type, 'null') ? removeUnionPart(next.type, 'null') : next.type;
+  return { type: union([current.type, nextType]), optional: current.optional && next.optional };
+}
+
+function withStringAlias(type, alias) {
+  const out = unionParts(type).map((part) => {
+    if (part === 'string') return alias;
+    if (part === 'string[]') return `${alias}[]`;
+    return part;
+  });
+  if (!out.includes('null')) return union(out);
+  return [...out.filter((part) => part !== 'null'), 'null'].join(' | ');
+}
+
+function collectionIdAlias(collection) {
+  if (collection === 'channels') return 'ChannelId';
+  if (collection === 'messages') return 'MessageId';
+  if (collection === 'roleDefinitions') return 'RoleId';
+  if (collection === 'rooms') return 'RoomId';
+  return undefined;
+}
+
+function entityFieldType(collection, field, type) {
+  const idAlias = field === 'id' ? collectionIdAlias(collection) : undefined;
+  if (idAlias) return withStringAlias(type, idAlias);
+  if (field === 'channelId') return withStringAlias(type, 'ChannelId');
+  if (field === 'messageId' || field === 'replyToId') return withStringAlias(type, 'MessageId');
+  if (field === 'roleId') return withStringAlias(type, 'RoleId');
+  if (field === 'roleIds') return withStringAlias(type, 'RoleId');
+  if (field === 'memberId' || field === 'authorId' || field === 'createdBy' || field === 'updatedBy' || field === 'archivedBy' || field === 'assignedBy' || field === 'deletedBy' || field === 'pinnedBy') return withStringAlias(type, 'MemberId');
+  if (field === 'roomId') return withStringAlias(type, 'RoomId');
+  if (field === 'threadId') return withStringAlias(type, 'ThreadId');
+  if (field === 'commentId' || field === 'parentId') return withStringAlias(type, 'CommentId');
+  if (field === 'embedId') return withStringAlias(type, 'EmbedId');
+  if (field === 'shareId') return withStringAlias(type, 'ShareId');
+  if (field === 'reactions') return 'Reactions';
+  if (field === 'embeds') return 'MessageEmbed[]';
+  return type;
+}
+
+function finalizeEntityFields(entities) {
+  for (const [collection, fields] of entities.entries()) {
+    const finalized = {};
+    for (const [key, info] of Object.entries(fields)) finalized[key] = { type: entityFieldType(collection, key, info.type), optional: info.optional };
+    entities.set(collection, finalized);
+  }
+}
+
+function recordKeyTypeForCollection(collection) {
+  if (collection === 'channels') return 'ChannelId';
+  if (collection === 'messages') return 'MessageId';
+  if (collection === 'roleDefinitions') return 'RoleId';
+  if (collection === 'memberRoles') return 'MemberId';
+  return 'string';
+}
+
+module.exports = {
+  finalizeEntityFields,
+  mergeFieldInfo,
+  recordKeyTypeForCollection
+};

package/src/types/generator.cjs

@@ -0,0 +1,145 @@
+const { validateAppCompositionSchema } = require('../composition.cjs');
+const { builtinMicroPluginRegistry } = require('../registry.cjs');
+const {
+  inlinePayloadType,
+  namespaceNameForApp,
+  pascalCase,
+  quoteProp,
+  sortedObjectEntries,
+  typeNameForCollection
+} = require('./schema.cjs');
+const { actionPayloadEntries, actionsMap, isCoreAction } = require('./actionTypes.cjs');
+const { docBlock } = require('./interfaceBlock.cjs');
+const {
+  collectPrimaryEntities,
+  collectionItemType,
+  coreStateFields,
+  interfaceBlock,
+  pluginFlatStateFields,
+  primaryStateFields,
+  standardPluginEntityTypes
+} = require('./entities.cjs');
+
+function operationsMap(composition, model, registry = builtinMicroPluginRegistry) {
+  const operations = {};
+  for (const [type, descriptor] of sortedObjectEntries(model.operations || {})) operations[type] = inlinePayloadType(descriptor.payload || { additional: true });
+  for (const plugin of composition.plugins || []) {
+    try {
+      const record = registry.get(plugin.key || plugin.id);
+      for (const [type, descriptor] of sortedObjectEntries(record.schema.schemas.operations || {})) operations[type] = inlinePayloadType(descriptor);
+    } catch {
+      // Unknown registries are allowed in schema files; keep generation best-effort.
+    }
+  }
+  return operations;
+}
+
+function queryResultType(view, model, entityData) {
+  if (!view) return 'unknown';
+  if (view.plugin === 'primary' || view.plugin === '$primary' || !view.plugin) {
+    const modelView = model.views?.[view.query || view.name] || view;
+    if (modelView.kind === 'collection') return `${collectionItemType(modelView.collection || modelView.path, entityData)}[]`;
+    if (modelView.kind === 'count') return 'number';
+    if (modelView.kind === 'state') return 'State';
+    return 'unknown';
+  }
+  if (view.query === 'onlineMembers') return 'PresenceMember[]';
+  if (view.query === 'roomDirectory') return 'MediaRoom[]';
+  if (view.query === 'commentsForScope') return 'Comment[]';
+  if (view.query === 'embedsForScope') return 'Embed[]';
+  if (view.query === 'reactionsForScope') return 'ScopedReaction';
+  if (view.query === 'activeShares') return 'ScreenShare[]';
+  return 'unknown';
+}
+
+function routeUnion(routes, field) {
+  const values = [...new Set((routes || []).map((route) => route[field]).filter(Boolean))];
+  return values.length ? values.map((value) => JSON.stringify(value)).join(' | ') : 'string';
+}
+
+function generatedHeader(namespace) {
+  return `/* =============================================================================\n * ${namespace}.types.d.ts — GENERATED by Matterhorn schema type generation.\n * DO NOT EDIT BY HAND.\n *\n * This is the frontend contract emitted from the room config: primary model,\n * composed plugin operations, query results, routes, and launch envelope.\n * ========================================================================== */\n\n`;
+}
+
+function hasPlugin(composition, key) {
+  return (composition.plugins || []).some((plugin) => plugin.key === key || plugin.id === key);
+}
+
+function hasCoreDirectMessages(composition) {
+  return (composition.actions || []).some((action) => isCoreAction(action) && action.type === 'dm.message');
+}
+
+function coreClientMethods(composition) {
+  const methods = [];
+  if (hasPlugin(composition, 'presence')) {
+    methods.push('    sendPresence(input: { status: PresenceStatus; activity?: string; at?: number }): Promise<boolean>;');
+  }
+  return methods;
+}
+
+function appContractDeclaration(namespace, hasDirectMessages) {
+  const lines = [`export interface ${namespace} {`];
+  lines.push(`  State: ${namespace}.State;`);
+  lines.push(`  Actions: ${namespace}.Actions;`);
+  lines.push(`  Queries: ${namespace}.Queries;`);
+  lines.push(`  QueryInput: ${namespace}.QueryInput;`);
+  lines.push(`  Actor: ${namespace}.Actor;`);
+  lines.push(`  Core: ${namespace}.Core;`);
+  lines.push(`  LaunchEnvelope: ${namespace}.LaunchEnvelope;`);
+  if (hasDirectMessages) lines.push(`  DirectMessageThread: ${namespace}.DirectMessageThread;`);
+  lines.push('}');
+  return lines.join('\n');
+}
+
+function generateAppTypeDeclaration(schema, options = {}) {
+  const registry = options.registry || builtinMicroPluginRegistry;
+  const composition = validateAppCompositionSchema(schema, { registry });
+  const namespace = pascalCase(options.namespace || namespaceNameForApp(composition));
+  const model = composition.primaryPlugin.model || { state: { initial: {} }, operations: {}, views: {} };
+  const entityData = collectPrimaryEntities(model);
+  const lines = [generatedHeader(namespace), `export namespace ${namespace} {`];
+  const roleIds = Object.keys(model.state?.initial?.roleDefinitions || {});
+  lines.push(`  export type Role = ${roleIds.length ? roleIds.map((role) => JSON.stringify(role)).join(' | ') : 'string'};`);
+  lines.push(standardPluginEntityTypes(composition));
+  lines.push('  export interface Actor { memberId: MemberId; deviceId: string; role: Role | (string & {}); displayName?: string; avatar?: string; avatarUrl?: string; profileImageUrl?: string; }');
+  lines.push('  export interface Activity { id: string; operationId?: string; actorId?: MemberId; actorName?: string; message: string; createdAt?: number; }');
+
+  for (const [collection, fields] of [...entityData.entities.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push(interfaceBlock(typeNameForCollection(collection), fields, '  ', `From primary model collection \`${collection}\`.`));
+  }
+
+  lines.push(interfaceBlock('State', { ...primaryStateFields(model, entityData), ...pluginFlatStateFields(composition, registry), ...coreStateFields(composition) }));
+  if (hasCoreDirectMessages(composition)) lines.push('  export interface DirectMessageThread { thread: DirectThread; messages: DirectMessage[]; }');
+  const actionEntries = actionPayloadEntries(composition, model, registry);
+  lines.push('  export interface Actions {');
+  for (const [name, payloadType, _operationType, docs] of actionEntries) {
+    const actionDocs = docBlock(docs, '    ');
+    if (actionDocs) lines.push(actionDocs);
+    lines.push(`    ${quoteProp(name)}: ${payloadType};`);
+  }
+  lines.push('  }');
+  lines.push('  export type ActionName = keyof Actions;');
+  lines.push('  export type ActionPayload<K extends ActionName> = Actions[K];');
+  lines.push('  export type OperationType = {');
+  for (const [name, _payloadType, operationType] of actionEntries) lines.push(`    ${quoteProp(name)}: ${JSON.stringify(operationType)};`);
+  lines.push('  };');
+
+  lines.push('  export interface Queries {');
+  for (const view of composition.views || []) lines.push(`    ${quoteProp(view.name)}: ${queryResultType(view, model, entityData)};`);
+  lines.push('  }');
+  lines.push('  export type QueryName = keyof Queries;');
+  lines.push('  export interface QueryInput {');
+  for (const view of composition.views || []) lines.push(`    ${quoteProp(view.name)}: void;`);
+  lines.push('  }');
+  lines.push(`  export type RoutePath = ${routeUnion(composition.routes, 'path')};`);
+  lines.push(`  export type RouteComponent = ${routeUnion(composition.routes, 'component')};`);
+  lines.push('  export interface Core {');
+  for (const method of coreClientMethods(composition)) lines.push(method);
+  lines.push('  }');
+  lines.push('  export interface LaunchEnvelope { room?: { id?: string; name?: string }; actor?: Actor; credentialGrant?: { credentialId?: string }; initialState?: State; }');
+  lines.push('}');
+  lines.push(appContractDeclaration(namespace, hasCoreDirectMessages(composition)));
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = { actionsMap, generateAppTypeDeclaration, operationsMap, queryResultType };

package/src/types/index.cjs

@@ -0,0 +1,5 @@
+module.exports = {
+  ...require('./schema.cjs'),
+  ...require('./entities.cjs'),
+  ...require('./generator.cjs')
+};

package/src/types/interfaceBlock.cjs

@@ -0,0 +1,41 @@
+const { quoteProp, sortedObjectEntries } = require('./schema.cjs');
+
+function docBlock(doc, indent = '  ') {
+  if (!doc) return '';
+  const lines = Array.isArray(doc) ? doc.filter(Boolean) : [doc];
+  if (lines.length === 0) return '';
+  return [
+    `${indent}/**`,
+    ...lines.map((line) => `${indent} * ${line}`),
+    `${indent} */`
+  ].join('\n');
+}
+
+function fieldDocs(info) {
+  const docs = [];
+  if (info.docs) docs.push(...(Array.isArray(info.docs) ? info.docs : [info.docs]));
+  if (info.doc) docs.push(info.doc);
+  if (info.optional && String(info.type).split(' | ').includes('null')) docs.push('omit to leave unchanged; null to clear.');
+  return docs.filter(Boolean);
+}
+
+function interfaceBlock(name, fields, indent = '  ', doc) {
+  const lines = [];
+  const blockDoc = docBlock(doc, indent);
+  if (blockDoc) lines.push(blockDoc);
+  lines.push(`${indent}export interface ${name} {`);
+  const entries = sortedObjectEntries(fields);
+  if (entries.length === 0) lines.push(`${indent}  [key: string]: unknown;`);
+  for (const [key, info] of entries) {
+    const docs = docBlock(fieldDocs(info), `${indent}  `);
+    if (docs) lines.push(docs);
+    lines.push(`${indent}  ${quoteProp(key)}${info.optional ? '?' : ''}: ${info.type};`);
+  }
+  lines.push(`${indent}}`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  docBlock,
+  interfaceBlock
+};