# @dxos/echo-panproto

> Declarative, serializable ECHO foreign-record lenses executed by panproto.

Latest version **0.16.0** (published 2026-10-19) · FSL-1.1-Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @dxos/echo-panproto
pnpm add @dxos/echo-panproto
yarn add @dxos/echo-panproto
bun add @dxos/echo-panproto
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.16.0 |
| Published | 2026-10-19 |
| First published | 2026-07-29 |
| Weekly downloads | 0 |
| License | FSL-1.1-Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 6 |
| Unpacked size | 537 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 532 |
| Author | DXOS.org |
| Maintainers | richburdon, marik_d, wittjosiah, dxos-bot, mykola-vrmchk |

## Links

- npm: https://www.npmjs.com/package/@dxos/echo-panproto
- Repository: https://github.com/dxos/dxos
- Homepage: https://dxos.org
- Issues: https://github.com/dxos/dxos/issues
- npm.io page: https://npm.io/package/@dxos/echo-panproto

## Dependencies (6)

- [react](https://npm.io/package/react.md) ~19.2.7
- [effect](https://npm.io/package/effect.md) 4.0.4
- [@dxos/echo](https://npm.io/package/@dxos/echo.md) 0.16.0
- [@dxos/effect](https://npm.io/package/@dxos/effect.md) 0.16.0
- [@panproto/core](https://npm.io/package/@panproto/core.md) 0.56.1
- [@dxos/invariant](https://npm.io/package/@dxos/invariant.md) 0.16.0

## Recent versions

- 0.16.0 (latest) — 2026-10-19
- 0.17.0-next-6a61a88494afb051ad9f12d6eedd1479c54b0cea (next) — 2026-11-18
- 0.16.0-next-60712ab191a99ba90316cc4be753e9e11b17100a — 2026-10-19
- 0.16.0-next-b440559823fb87ed1a4590dab21ae924d4d76c3a — 2026-10-19
- 0.14.0 — 2026-10-10
- 0.13.0 — 2026-10-07
- 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 — 2026-08-27
- 0.12.0-next-2800d0376abcc62d5544afdd744b16b2b960434e — 2026-08-27
- 0.12.0-next-2be9f24c465d98f4bd186aa03ece788902e6c17a — 2026-08-27
- 1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d — 2026-08-10
- 0.11.1 — 2026-08-05
- 0.11.0 — 2026-08-05
- 0.0.0 — 2026-07-29

## README

# @dxos/echo-panproto

Declarative, serializable lenses between an ECHO object and a foreign (e.g. atproto) record, backed by
[panproto](https://panproto.dev). A lens is **data** — the whole mapping is a `Panproto.Lens` value, not
a hand-written codec.

```ts
import { Panproto } from '@dxos/echo-panproto';

// Register the ECHO-specific codecs a lens references by name (once, from the owning plugin).
Panproto.registerTextFormat('markdown-html', { encode: markdownToHtml, decode: htmlToMarkdown });
Panproto.registerRefType('text', { read: loadTextRef, make: makeTextRef });

const lens: Panproto.Lens = {
  adapters: [
    { kind: 'scalar', wire: 'title', echo: ['catalog', 'title'] },
    { kind: 'array', wire: 'authors', echo: ['catalog', 'authors'], separator: '\t' },
    { kind: 'prefix', wire: 'status', echo: ['status'], prefix: 'buzz.bookhive.defs#' },
    { kind: 'ref', wire: 'review', echo: ['review'], ref: { refType: 'text', format: 'markdown-html' } },
  ],
};

const record = await Panproto.encode(book, lens); // ECHO object -> wire record
const fields = await Panproto.decode(record, lens); // wire record -> ECHO-shaped fields
```

## Two parts: engine (`migration`) + runner (`adapters`)

A `Lens` has two parts, run by `Panproto.encode`/`decode`:

- **`migration` — panproto (structural).** Cross-lexicon vertex/edge alignment: field renames and
  nesting between two atproto lexicons, executed by the panproto engine (`liftJson`). This is what the
  wasm on the `./wasm` entrypoint runs.
- **`adapters` — the runner (ECHO effects).** The value-level and ECHO-specific work panproto's graph
  transform cannot express: `Ref<Text>` resolution, array↔string, object metadata (`createdAt`), scalar
  value coercions (knownValue prefix, date widen), and nested structs. Authored as data; executed
  host-side. Any structural move can shift between `migration` and `adapters` with no consumer change.

## Entrypoint split

- **`@dxos/echo-panproto`** — the durable `Panproto` API (the `Lens` schema, the `encode`/`decode`
  runner, `registerTextFormat`/`registerRefType`). Depends on `@dxos/echo`; the `Lens` schema itself is a
  side-effect-free leaf, so importing it does not load the engine.
- **`@dxos/echo-panproto/wasm`** — the engine. Wraps upstream `@panproto/core` (which ships and loads its
  own wasm) and is loaded lazily by the runner, so the API surface never statically depends on it. This is
  the one swappable implementation detail.

## panproto engine

The engine bridges to upstream **`@panproto/core@0.56.1`**, whose high-level TypeScript API executes
migrations at runtime: `Panproto.init()` → `panproto.parseLexicon(lexicon)` →
`panproto.migration(src, tgt).map().mapEdge().compile()` → `mig.liftJson(record, rootVertex)`. See the
panproto book (https://panproto.dev/book) — verified against `reference/sdk-typescript.html` and the
`tutorials/`. panproto's structural graph transforms are used for `migration`; scalar value transforms and
ECHO effects are the runner's `adapters` (the shipped API exposes structural lens-DSL steps but no
value-expression step).

---
_Source: https://npm.io/package/@dxos/echo-panproto · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
