# io-matrix — complete library (all audiences)

_Generated whole-library download. See `agent-manifest.json` → `library` for discovery._

## Table of contents

- **Overview** (`00-overview`, developers)
- **Schema and document** (`01-schema-document`, developers)
- **Matrix view** (`02-matrix-view`, developers)
- **Import and export** (`03-import-export`, developers)

---

# Overview — developers

# Overview — Developers

**Audience:** Engineers evaluating or adopting `@x12i/io-matrix-schema` and `@x12i/io-matrix-view`.  
**Related:** [Schema and document](../01-schema-document/developers/BOOK.md) · [Matrix view](../02-matrix-view/developers/BOOK.md)

---

## 1. What it is

The **Object–Property I/O Matrix** shows, for every process step:

1. Which object properties the step receives as input
2. What the step does
3. Which object properties the step produces or updates as output

Columns are object properties. Rows are ordered pipeline steps. Cells use `R` / `S` / `O` / `-` for required, supporting, optional, or unused.

This monorepo publishes:

| Package | Role |
|---------|------|
| `@x12i/io-matrix-schema` | Types, Zod validation, abstracts, transforms |
| `@x12i/io-matrix-view` | React viewer/editor (matrix, map, abstracts, Try) |
| `@x12i/io-matrix-docs` | Docify knowledge SDK (devDependency) |

The demo app and `data/` fixtures are **not** shipped inside the npm packages.

---

## 2. Install

```bash
pnpm add @x12i/io-matrix-view @x12i/io-matrix-schema
```

Requires React 18+ or 19. Import the stylesheet once:

```ts
import '@x12i/io-matrix-view/style.css';
```

---

## 3. Minimal example

```tsx
import { useState } from 'react';
import { ObjectPropertyIOMatrix } from '@x12i/io-matrix-view';
import '@x12i/io-matrix-view/style.css';
import type { Matrix } from '@x12i/io-matrix-schema';

export function App({ initial }: { initial: Matrix }) {
  const [matrix, setMatrix] = useState(initial);

  return (
    <ObjectPropertyIOMatrix
      matrix={matrix}
      onChange={setMatrix}
      mode="edit"
    />
  );
}
```

Pass your own `matrix` — the packages contain no sample business data.

---

## 4. Where to go next

- Model documents and abstracts → [Schema and document](../01-schema-document/developers/BOOK.md)
- Surfaces, map view, presets → [Matrix view](../02-matrix-view/developers/BOOK.md)
- JSON persistence vs view exports → [Import and export](../03-import-export/developers/BOOK.md)

---

# Schema and document — developers

# Schema and document — Developers

**Audience:** Authors of matrix JSON and integrators who load/save documents.  
**Related:** [Overview](../00-overview/developers/BOOK.md) · [Import and export](../03-import-export/developers/BOOK.md)

---

## 1. Document contract

The **only** persistence unit is a versioned document. Never persist steps alone — object types, properties, abstracts, transforms, and examples travel together.

```json
{
  "formatVersion": "1.2.0",
  "matrix": {
    "abstractCatalog": ["asset_id"],
    "objectTypes": [],
    "steps": []
  }
}
```

| Field | Role |
|-------|------|
| `formatVersion` | `1.x` documents parse; current write version is `1.2.0` |
| `matrix.objectTypes` | Raw object model (keys, labels, optional `abstracts[]`) |
| `matrix.abstractCatalog` | Canonical abstract names |
| `matrix.steps[].inputs/outputs` | Raw column I/O (`Object.property` → `R`/`S`/`O`/`-`) |
| `matrix.steps[].abstractInputs/Outputs` | Abstract-name I/O |
| `matrix.steps[].transforms` | Declarative field transforms |
| `matrix.steps[].examples` | Try-playground fixtures |

---

## 2. Cells and steps

Each step is a conceptual three-line block: **input**, **process**, **output**.

| Symbol | Input meaning | Output meaning |
|--------|---------------|----------------|
| **R** | Required input | Required output |
| **S** | Supporting input | Recommended output |
| **O** | Optional input | Optional output |
| **—** / `-` | Not used | Not produced |

Step kinds include `ui`, `ai-service`, `connector`, `target-connector`, and related labels used by the view toolbar filters.

---

## 3. Abstracts

Abstracts map raw `Object.property` columns to stable conceptual names:

- `matrix.abstractCatalog` lists canonical names
- Object types and properties may declare `abstracts[]`
- Steps may carry `abstractInputs` / `abstractOutputs` alongside raw I/O

The React view exposes an **Abstracts** surface and a Raw / Abstract naming lens on Matrix and Map.

---

## 4. Parse serialize

```ts
import { parseDocument, serializeDocument } from '@x12i/io-matrix-schema';

const doc = parseDocument(JSON.parse(raw));
const out = serializeDocument(doc);
```

Prefer JSON for load/save. Markdown export is view-aware and not a lossless persistence format.

---

# Matrix view — developers

# Matrix view — Developers

**Audience:** App developers embedding `@x12i/io-matrix-view`.  
**Related:** [Overview](../00-overview/developers/BOOK.md) · [Schema and document](../01-schema-document/developers/BOOK.md)

---

## 1. Surfaces

| View | Purpose |
|------|---------|
| **Matrix** | Classic step × property I/O table |
| **Map** | Atlas-style swimlanes / ribbons between properties and steps |
| **Abstracts** | Assign abstract names to raw object properties |
| **Transforms** | Declarative step input→output ops + step abstract I/O |
| **Try** | Playground: sample input → computed output + validation |

Matrix and Map share a **Raw / Abstract** naming lens. Abstracts / Transforms / Try keep focused chrome.

---

## 2. Props and config

| Prop | Type | Description |
|------|------|-------------|
| `matrix` | `Matrix` | Controlled matrix value |
| `defaultMatrix` | `Matrix` | Uncontrolled initial value |
| `onChange` | `(m: Matrix) => void` | Edit-mode changes |
| `mode` | `'readonly' \| 'edit'` | Controlled mode |
| `config` | `MatrixViewConfig` | Feature flags + filters |
| `memorix` | `MemorixClientConfig` | Optional remote load/save |

```tsx
import { ObjectPropertyIOMatrix, PRESET_READONLY_VIEWER } from '@x12i/io-matrix-view';

<ObjectPropertyIOMatrix
  matrix={matrix}
  onChange={setMatrix}
  mode="readonly"
  config={PRESET_READONLY_VIEWER}
/>
```

---

## 3. Map and layers

The **Map** surface lays out object-property nodes and step ribbons using `computeMapLayout`. Layer toggles control:

- Process descriptions (matrix row or map ribbon)
- Step names on map ribbons
- Other surface-specific visibility flags

Expand nested sub-matrices to include nested steps in the map graph.

---

## 4. Presets

- `PRESET_UI_ONLY` — only `ui` steps
- `PRESET_CONNECTORS_ONLY` — `connector` + `target-connector`
- `PRESET_READONLY_VIEWER` — no editing / promote-demote

Tune `visibleKinds`, `visibleObjectTypeKeys`, and `features` for import/export, sub-matrix promote/demote, and cell editing.

---

# Import and export — developers

# Import and export — Developers

**Audience:** Integrators who persist matrices or share filtered views.  
**Related:** [Schema and document](../01-schema-document/developers/BOOK.md)

---

## 1. JSON document

Use the versioned document as the **only** persistence format:

```ts
import { parseDocument, serializeDocument } from '@x12i/io-matrix-schema';

const doc = parseDocument(await res.json());
// …edit…
JSON.stringify(serializeDocument(doc), null, 2);
```

The view’s import/export controls round-trip the full document when JSON is selected.

---

## 2. View exports

Markdown, PNG, and PDF export the **current filtered view** (kinds, object types, naming lens). They may append abstract-mapping and transforms sections when present — they are not lossless persistence.

Prefer JSON for load/save; use Markdown/images for sharing a specific slice.

---

## 3. Demo fixtures

The monorepo demo loads worked examples from `data/` (for example `data/sample-matrix.json`). Those fixtures are **not** bundled inside `@x12i/io-matrix-view` or `@x12i/io-matrix-schema`.