Chat

Appearance

Package manifest ​

Both Chat packages ship a matrix.json. They are mostly identical; the differences are documented at the bottom of this page.

Fields ​

Identity ​

json
"name":      "@open-matrix/chat",         // package name (or @open-matrix/chat-component)
"version":   "0.2.9",                     // semver (chat) / 0.1.0 (chat-component)
"description": "Matrix Chat - standalone-capable hybrid browser/runtime package",
"class":     "hybrid",                    // hybrid = both browser and runtime
"namespace": "chat"                       // logical mount root

Root mount ​

json
"root": {
  "type":    "MatrixChatApp",
  "export":  "MatrixChatApp",
  "mount":   "chat",
  "surface": "browser"
}

The root actor is chat (mount). It's a browser-side custom element (<chat-app>).

Runtime metadata ​

json
"runtime": {
  "language": "typescript",
  "entry":          "./dist/runtime/index.js",
  "browserEntry":   "./dist/browser/register-elements.js",
  "bootstrapEntry": "./dist/browser/bootstrap.js",
  "environments": ["browser", "headless-dom", "runtime"],
  "executionClassCompatibility": [
    "shared_host_service",
    "dedicated_process",
    "container",
    "isolate",
    "remote_managed_service"
  ]
}

Three entry files for three loaders:

  • Runtime entry — Host Service uses this when starting the runtime side.
  • Browser entry — gateway serves; auto-registers all custom elements on import.
  • Bootstrap entry — host shells use this to drive Chat's startup themselves.

environments and executionClassCompatibility declare what containers Chat is willing to run in. Host Service uses these to pick a launcher.

Webapp ​

json
"webapp": {
  "distDir":    "./dist/browser",
  "entry":      "index.html",
  "appName":    "chat",                          // chat-component: "chat-component"
  "displayName":"Chat",                          // chat-component: "Chat Component"
  "icon":       "💬",
  "navOrder":   30,                              // chat-component: 35
  "description":"Conversation and agent workspace",
  "shells":     ["platform", "edge"],
  "base":       "relative"
}

shells: ["platform", "edge"] means both the matrix-web and matrix-edge shells should surface Chat in their app drawer.

Components (the runtime-side actors) ​

json
"components": [
  { "type": "ChatSecurityRealmService", "mount": "security-realm",   "autoStart": true,  "surface": "headless" },
  { "type": "ChatTopicClaimService",    "mount": "topic-claims",     "autoStart": true,  "surface": "headless" },
  { "type": "ChatConversationProxy",    "mount": "conversation",     "autoStart": true,  "surface": "headless" },
  { "type": "ChatComponentLibraryProxy","mount": "component-library","autoStart": true,  "surface": "headless" },
  { "type": "ChatIdentityProxy",        "mount": "identity",         "autoStart": true,  "surface": "headless" },
  { "type": "ChatPreferencesProxy",     "mount": "preferences",      "autoStart": true,  "surface": "headless" },
  { "type": "ChatSessionStateProxy",    "mount": "session-state",    "autoStart": true,  "surface": "headless" },
  { "type": "ChatMcpProxy",             "mount": "mcp",              "autoStart": false, "surface": "headless" },
  { "type": "ChatExportService",        "mount": "export",           "autoStart": true,  "surface": "headless" }
]

Each mount is namespaced under chat, so the actual mount paths are chat.security-realm, chat.topic-claims, etc. Per surface: "headless", none of these are user-visible elements.

Consumes ​

json
"consumes": [
  { "contract": "IChatConversationService",     "required": true,  "bindingKey": "conversation-service" },
  { "contract": "IChatComponentLibraryService", "required": true,  "bindingKey": "component-library-service" },
  { "contract": "IChatIdentityService",         "required": false, "bindingKey": "identity-service" },
  { "contract": "IChatPreferencesService",      "required": false, "bindingKey": "preferences-service" },
  { "contract": "IChatSessionStateService",     "required": true,  "bindingKey": "session-state-service" },
  { "contract": "IChatMcpStatusService",        "required": false, "bindingKey": "mcp-status-service" }
]

required: true services must be bound before the chat runtime starts; required: false services may be omitted (the proxy then renders empty / null).

Config ​

json
"config": {
  "schema":    "./config/config.schema.json",
  "defaults":  "./config/config.defaults.json",
  "envPrefix": "MATRIX_CHAT_",
  "providers": [
    { "kind": "env",     "prefix": "MATRIX_CHAT_" },
    { "kind": "file",    "env": "MATRIX_CHAT_CONFIG_FILE", "optional": true },
    { "kind": "service", "service": "system.config", "namespace": "@open-matrix/chat",
      "env": "MATRIX_CHAT_CONFIG_SERVICE", "optional": true }
  ]
}

Config is resolved by reading the schema, applying the per-mode profile from config/profiles/, and merging providers in order. See Config.

Permissions ​

json
"permissions": {
  "fsPolicy":   "none",
  "network":    true,
  "subprocess": false,
  "env":        false
}
  • fsPolicy: "none" — Chat cannot read or write files.
  • network: true — required for the bus and font fetches.
  • subprocess: false, env: false — Chat cannot spawn or read env.

chat-component differences ​

chat-component/matrix.json adds:

json
"surfaces": {
  "conversation": {
    "tag":    "conversation-surface",
    "module": "./dist/browser/surface/register-surface.js",
    "route":  "/apps/chat-component/surface/register-surface.js",
    "description": "Embeddable conversation surface plugin loaded by host shells (Director, etc.) via dynamic import"
  }
}

And changes webapp.appName to chat-component, displayName to Chat Component, navOrder to 35.

Other than that, the manifests are identical.

See also ​

Source: projects/matrix-3/packages/chat/matrix.json, projects/matrix-3/packages/chat-component/matrix.json.