From 00b9099be189b82669fd090e2e2d14c0ce139785 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 7 Jun 2026 22:55:09 +0000 Subject: [PATCH] docs: expand SDK README --- README.md | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 185 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 8c57492..5e133dc 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,192 @@ -# Matrix SDK Workspace +# Matrix SDK -This workspace is the isolated SDK incubation area for -`WORKSTREAMS/matrix-sdk-isolation`. +Matrix SDK is the package-author layer for building Matrix actors, browser +surfaces, and broker-connected applications without depending on the HiveCast +platform repo. -Current proven checkpoints: +This repository contains the SDK packages that were split out of Matrix-3 and +renamed to their publishable `@open-matrix/*` package names. The split is +proven as a standalone workspace: a fresh clone can install, build, test, +type-check, pack every package, and compile an external consumer against the +packed tarballs. -- copied SDK-bearing packages build/test/type-check/pack independently -- copied package identities were renamed to final `@open-matrix/*` names -- `@open-matrix/sdk` facade package builds/tests/packs -- `@open-matrix/browser-kit` builds package-manager-ready `dist` exports -- a fresh external temp consumer installs packed tarballs, compiles, starts a - `MatrixActor`, and calls it through the Matrix runtime/transport path +## What You Can Build -Proof commands: +- Headless actors with `MatrixActor` +- Browser custom elements with `MatrixActorHtmlElement` +- In-memory actor graphs for tests and local development +- NATS-backed transports for broker-connected actors +- Browser host integrations for Matrix web surfaces +- Package-author CLIs and project scaffolds -```bash -pnpm --dir projects/matrix-sdk prove -pnpm --dir projects/matrix-sdk prove:external-consumer +Matrix SDK is provider-neutral. It does not require HiveCast, Device Link, Host +Link, Host Service, or a local HiveCast install. HiveCast is one managed provider +that can issue broker credentials and host runtimes on top of the SDK. + +## Packages + +| Package | Purpose | +| --- | --- | +| `@open-matrix/sdk` | Public umbrella facade for actor/package authors | +| `@open-matrix/core` | Actor kernel, runtime, transports, serialization, browser actor base classes | +| `@open-matrix/cli` | Package-author `matrix` CLI | +| `@open-matrix/browser-kit` | Browser app shims, theme tokens, Vite helpers, shell components | +| `@open-matrix/browser-host` | Browser runtime host shell and app-ready integration | +| `@open-matrix/contracts` | Shared type contracts for placement, service registry, and runtime presence | +| `@open-matrix/federation` | Cross-realm messaging, MX envelope handling, and routing helpers | +| `@open-matrix/omega-core` | Narrow Omega interpreter facade used by Matrix membranes | + +Prefer narrow imports when possible: + +```ts +import { MatrixActor } from '@open-matrix/core'; ``` -Matrix-3 consumers have not been repointed yet. +Use the umbrella package when you intentionally want the public SDK facade: + +```ts +import { MatrixActor } from '@open-matrix/sdk'; +``` + +## Quick Start + +```bash +git clone git@github.com:matrix-sdk/matrix-sdk.git +cd matrix-sdk +pnpm install --frozen-lockfile +pnpm prove +``` + +`pnpm prove` runs the standalone proof: + +```text +clean -> build -> test -> type-check -> pack all packages +``` + +For the external-consumer proof: + +```bash +pnpm prove:external-consumer +``` + +That proof packs the SDK packages, creates a temporary consumer outside this +repo, installs the packed tarballs, compiles TypeScript, starts a `MatrixActor`, +and calls it through the Matrix runtime/transport path. + +## Minimal Actor + +```ts +import { + InMemoryBroker, + InMemoryTransport, + MatrixActor, + MatrixRuntime, + TopicRouter, +} from '@open-matrix/core'; + +class EchoActor extends MatrixActor { + static accepts = { + echo: {}, + }; + + onEcho(payload: { message?: string }) { + return { + ok: true, + message: payload.message ?? null, + }; + } +} + +const broker = new InMemoryBroker(); +const transport = new InMemoryTransport(broker, { name: 'demo' }); +const runtime = new MatrixRuntime({ transport, logging: false }); + +await runtime.create(EchoActor, 'demo.echo'); + +const replyTo = '$replies.demo'; +const response = new Promise((resolve) => { + const unsubscribe = transport.subscribe(replyTo, (value) => { + unsubscribe(); + resolve(value); + }); +}); + +transport.publish(TopicRouter.inbox('demo.echo'), { + op: 'echo', + payload: { message: 'hello' }, + replyTo, + correlationId: 'demo-1', +}); + +console.log(await response); +await runtime.shutdown(); +``` + +## CLI + +The SDK CLI package owns the package-author `matrix` binary. + +```bash +matrix init [dir] +matrix add actor +matrix actor +matrix configure --key --cloud --space +matrix run --mount +matrix invoke [json] +``` + +The current CLI proof is: + +```bash +pnpm prove:cli-uat +``` + +The CLI is intended to let a package author initialize a folder, add actors, +configure broker access, run actors, and invoke them without importing HiveCast +product packages into the SDK layer. + +## Repository Layout + +```text +packages/ + browser-host/ + browser-kit/ + cli/ + contracts/ + core/ + federation/ + omega-core/ + sdk/ +scripts/ + prove-external-consumer.mjs + prove-sdk-cli-uat.mjs +``` + +## Current Status + +Done and proven: + +- The SDK packages build independently from Matrix-3. +- Package identities use final `@open-matrix/*` names. +- `@open-matrix/sdk` re-exports the public actor facade. +- A fresh clone passes `pnpm install --frozen-lockfile && pnpm prove`. +- A temporary external consumer can install packed SDK tarballs, compile, start + a `MatrixActor`, and call it through Matrix runtime/transport. + +Still planned: + +- Provider-neutral credential resolution for `matrix configure` and SDK users. +- `matrix login --provider hivecast` to write the same config shape as + `matrix configure`. +- Direct broker mode with explicit broker URL/JWT/seed credentials. +- HiveCast provider mode where HiveCast issues scoped broker credentials. +- Publishing the packages to npm after the provider-login contract is complete. + +## Relationship To HiveCast + +Matrix SDK is the open, provider-neutral actor SDK. + +HiveCast is a managed overlay on top of Matrix SDK. HiveCast can provide account +management, Spaces, API keys, broker credential issuance, runtime hosting, +package distribution, and operator UI. SDK users should still be able to connect +to another broker directly when they already manage their own broker credentials.