hivecast-sdk/packages/core/README.md

# @open-matrix/core

Matrix runtime SDK — actors, Web Components, transports, serialization, and LISP-on-Protocol.

## Install

```bash
npm install @open-matrix/core
```

## Usage

### Headless Actor (daemon-side)

```typescript
import { MatrixActor } from '@open-matrix/core';

class PingActor extends MatrixActor {
  static accepts = {
    ping: { message: 'string' },
  };
  static emits = {
    pong: { echo: 'string', ts: 'number' },
  };

  onPing(payload: { message: string }) {
    this.emit('pong', { echo: payload.message, ts: Date.now() });
  }
}
```

### Browser Web Component

```typescript
import { MatrixActorHtmlElement } from '@open-matrix/core';

class StatusPanel extends MatrixActorHtmlElement {
  static accepts = { showStatus: { text: 'string' } };
  static template = `<div id="status"></div>`;
  static styles = `#status { font-family: monospace; padding: 8px; }`;

  onShowStatus(payload: { text: string }) {
    this.shadowRoot!.querySelector('#status')!.textContent = payload.text;
  }
}

customElements.define('status-panel', StatusPanel);
```

### Programmatic Runtime

```typescript
import { InMemoryBroker, InMemoryTransport, MatrixRuntime } from '@open-matrix/core';

const broker = new InMemoryBroker();
const transport = new InMemoryTransport(broker, { name: 'demo' });
const runtime = new MatrixRuntime({ transport });
```

## What's Included

| Category | Key Exports |
|----------|------------|
| **Core** | `MatrixActor`, `Supervisor`, `HeadlessComponentRegistry` |
| **Framework** | `MatrixActorHtmlElement`, `MxContract`, `MxInterface`, `MxProxy` |
| **Runtime** | `MatrixRuntime`, `HeadlessHost`, `ConsoleLogger` |
| **Transports** | `InMemoryBroker`, `NatsTransport`, `FederationTransportAdapter` |
| **Messaging** | `TopicRouter`, `SubscriptionBag`, `RequestReply` |
| **LISP** | `Interpreter`, `EvalContext`, `parseSExpr` |
| **Serialization** | `serialize`, `parse`, 5-format parity |
| **Flow** | `FlowBuilder`, `FlowEngine`, `FlowContext` |

135 named exports total. Full type declarations included.

## Requirements

- Node.js >= 20
- TypeScript >= 5.0 (for type checking)

## License

MIT