@preset.nz/pom 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 preset.nz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# rhizome
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared node API for the preset.nz desktop apps: mechanics only. A network of nodes with no fixed centre.
+
+rhizome knows no app. It stores, validates, edits, undoes, diffs, saves and copies nodes of whatever types an app declares. Each app's **object model** holds its business logic, in the app's own repo.
+
+**Status: first slice and POM phase 1 built.** `crates/rhizome-core` holds the mechanics: the registry, the tree, edits with undo, diff, the file format, opaque nodes, copy/paste, tree rules. `crates/rhizome-pom` is POM, the Preset Object Model: the base every app's object model is built on (documents, kinds with policy, presets, commands, projections). `crates/rhizome-pom-tauri` puts one open document behind Tauri commands and events. `@preset.nz/pom` (`src-ts/`) is the webview client of `rhizome-pom-tauri`.
+
+## Install
+
+```toml
+[dependencies]
+rhizome-core = "0.1"
+rhizome-pom = "0.1"        # an object model on POM
+rhizome-pom-tauri = "0.1"  # a Tauri 2 app with one open document
+```
+
+Take only what you need: `rhizome-pom` brings `rhizome-core` with it, and `rhizome-pom-tauri` brings both.
+
+## TypeScript: `@preset.nz/pom`
+
+The webview client of `rhizome-pom-tauri`: unbuilt TypeScript in `src-ts/`, versioned with the crates and not yet published. `react` and `@tauri-apps/api` are peer dependencies.
+
+```ts
+import { createChannel, createMirror, PomProvider, tauriBackend, useNode } from '@preset.nz/pom';
+
+const channel = createChannel(tauriBackend); // commands reach Rust in the order they were made
+const mirror = createMirror(tauriBackend);   // made outside React
+await mirror.start();                        // connect, listen, then read the view
+
+await channel.run('value.set', { at: '/threads/warp', key: 'thread.tension', value: 0.8 });
+```
+
+- **`PomBackend`** is the `pom_*` commands and the `pom://commit` and `pom://status` events, nothing else. `tauriBackend` implements it over Tauri; tests pass a fake.
+- **`createChannel`** is one ordered queue. `run`, `begin`, `end` and `cancel` keep their order, so a gesture's `end` finds its token. `drag` is latest-wins, for scrubs and transforms only. The gate starts open; `{ held: true }` shuts it until `release()`.
+- **`createMirror`** keeps the rows by id with a path index, from the view and the commits that follow. It re-reads the view on a gap in `seq` or a new `generation`.
+- **Hooks**, through `useSyncExternalStore`: `useNode(id)`, `useNodeAt(path)`, `useChildren(id, order)` and `useStatus()`, under a `<PomProvider mirror={mirror}>`. A hook returns the same object until its own node changes.
+- **Wire types** (`Row`, `View`, `Update`, `Status`, `Ran`, ...) follow the Rust structs. The tests read the Rust goldens, so a shape that moves in one half fails the other's build.
+
+## Tests
+
+`just check` runs `check-rust` (fmt, clippy and every suite) and `check-ts` (tsc, Biome and vitest), then the licence check.
+
+`just check` runs fmt, clippy and every suite.
+
+- **Acid** (`tests/acid.rs`, `just acid`): builds one of everything through the Rust verbs and again through `Op`s, then operates every verb, refusal and cascade. The built file and the changeset log are goldens in `tests/golden/`.
+- **Core workflows** (`tests/core_workflows.rs`, `just workflows`): twelve workflows a person does, stored as data in `tests/workflows/*.json` and driven only through the stable surface (`Op` JSON, the file format, edits, gestures, undo). Each has a transcript pinned beside it. A change to the SDK that alters a workflow fails here.
+- **POM** (`crates/rhizome-pom/tests/pom.rs`, `just pom`) and **POM's core workflows** (`tests/workflows.rs`, data in `tests/workflows/*.json`): two made-up object models, and six workflows run through commands by id.
+- **Wire** (`crates/rhizome-pom/tests/wire.rs`): the `View`, `Update`, `Status`, `Ran` and `CommandState` JSON a transport carries, pinned in `crates/rhizome-pom/tests/golden/*.json`. With core's `commit.json` and `view.json` they are what the TypeScript tests (`tests/`, `just test-ts`) read.
+- **Invariants** (`tests/invariants.rs`, `just invariants`): seeded random `Op`s, checking after every step that nothing dangles, values fit their schema, a refused edit leaves no trace, a save reloads identically and undo walks back through every state.
+
+`just bless` rewrites the goldens. Read every changed line before committing it.
+
+## Design docs
+
+`guidance/` holds **copies** of the planning docs so the work can continue away from the main machine. The canonical versions live in the private guidance repo (`design/node-api.md`, `design/rhizome-api.md`, `design/pom.md`, `handovers/rhizome/handover.md`). Edit there, then recopy. Relative links inside the copies won't resolve.
+
+- [`guidance/node-api.md`](guidance/node-api.md): the model and decisions 1 to 35.
+- [`guidance/rhizome-api.md`](guidance/rhizome-api.md): the API as built — verbs, shape, guarantees, and the line between rhizome and an object model.
+- [`guidance/pom.md`](guidance/pom.md): POM, the Preset Object Model every app's object model builds on (draft).
+- [`guidance/handover.md`](guidance/handover.md): code state and next steps.
+
+## Licence
+
+MIT.

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@preset.nz/pom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.5",
+  "description": "The webview client of rhizome-pom-tauri: an ordered command channel, a read-only mirror of the document and React hooks over it.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/preset-nz/rhizome.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src-ts/index.ts"
+  },
+  "files": [
+    "src-ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@tauri-apps/api": "^2",
+    "react": "^19"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@tauri-apps/api": "^2",
+    "@testing-library/react": "^16",
+    "@types/node": "^24",
+    "@types/react": "^19",
+    "jsdom": "^27",
+    "lefthook": "^2.1.17",
+    "react": "^19",
+    "react-dom": "^19",
+    "@types/react-dom": "^19",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.11"
+  }
 }

package/src-ts/backend.ts

@@ -0,0 +1,56 @@
+/**
+ * The one module that talks to `rhizome-pom-tauri`: its `pom_*` commands and its
+ * `pom://commit` and `pom://status` events. Commands only (rhizome decision 46): there is no
+ * way to send a raw edit. An app's own events and commands stay in the app.
+ *
+ * `PomBackend` is the interface; `tauriBackend` implements it over Tauri, and tests pass a fake.
+ */
+import { invoke } from '@tauri-apps/api/core';
+import { listen } from '@tauri-apps/api/event';
+import type { CommandState, Ran, Status, Update, View } from './wire.ts';
+
+export type Unlisten = () => void;
+
+export interface PomBackend {
+  /**
+   * The front end is listening. Ends any gesture a reloaded page left open, sends the status,
+   * and answers a path macOS asked the app to open before the page was listening, if any. A file
+   * opened that way wins over a restored one.
+   */
+  connect(): Promise<string | null>;
+  view(): Promise<View>;
+  status(): Promise<Status>;
+  /** Every command with its label and whether it can run with `payload`. */
+  commands(payload?: unknown): Promise<CommandState[]>;
+  /**
+   * Runs a command by id. With `coalesce`, consecutive runs with that key are one undo step.
+   */
+  run(id: string, payload?: unknown, coalesce?: string): Promise<Ran>;
+  /** Opens a gesture: commands run until `end` are one undo step. Answers its token. */
+  begin(label: string): Promise<number>;
+  end(token: number): Promise<void>;
+  /** Ends a gesture and takes back everything done in it. */
+  cancel(token: number): Promise<void>;
+  /** Every commit, in order: undo, redo and cancel included. */
+  onUpdate(f: (u: Update) => void): Promise<Unlisten>;
+  /** The status, whenever it changed. */
+  onStatus(f: (s: Status) => void): Promise<Unlisten>;
+}
+
+/** The event names `rhizome-pom-tauri` emits. */
+export const COMMIT_EVENT = 'pom://commit';
+export const STATUS_EVENT = 'pom://status';
+
+/** Tauri camelCases the argument names of a Rust command; these are all one word. */
+export const tauriBackend: PomBackend = {
+  connect: () => invoke<string | null>('pom_connect'),
+  view: () => invoke<View>('pom_view'),
+  status: () => invoke<Status>('pom_status'),
+  commands: (payload) => invoke<CommandState[]>('pom_commands', { payload }),
+  run: (id, payload = {}, coalesce) => invoke<Ran>('pom_run', { id, payload, coalesce }),
+  begin: (label) => invoke<number>('pom_begin', { label }),
+  end: (token) => invoke<void>('pom_end', { token }),
+  cancel: (token) => invoke<void>('pom_cancel', { token }),
+  onUpdate: (f) => listen<Update>(COMMIT_EVENT, (e) => f(e.payload)),
+  onStatus: (f) => listen<Status>(STATUS_EVENT, (e) => f(e.payload)),
+};

package/src-ts/channel.ts

@@ -0,0 +1,132 @@
+/**
+ * The ordering on top of a `PomBackend`. Every call goes through one promise chain, so commands
+ * reach Rust in the order they were made and a gesture's `end` finds its token.
+ */
+import type { PomBackend } from './backend.ts';
+import type { CommandState, Ran, Status, View } from './wire.ts';
+
+export interface ChannelOptions {
+  /**
+   * Start with the gate shut: calls queue until `release()`. For an app that has to be ready
+   * before its first command may run. The default is open.
+   */
+  held?: boolean;
+  /** Resolves after the next paint; a drag's next command waits for it. */
+  nextFrame?: () => Promise<void>;
+}
+
+const defaultNextFrame = (): Promise<void> =>
+  new Promise((resolve) => {
+    if (typeof requestAnimationFrame === 'function') requestAnimationFrame(() => resolve());
+    else setTimeout(resolve, 0);
+  });
+
+interface Waiting {
+  id: string;
+  payload: unknown;
+  coalesce?: string;
+  done: Promise<Ran>;
+}
+
+export interface Channel {
+  /** Calls made and not yet answered; a drag that replaced a waiting move doesn't count. */
+  readonly pending: number;
+  /** Lets the queued calls through. A no-op on a gate that is already open. */
+  release(): void;
+  /** Called whenever the queue empties. Returns a function that stops listening. */
+  onIdle(f: () => void): () => void;
+  run(id: string, payload?: unknown, coalesce?: string): Promise<Ran>;
+  /**
+   * A command for a scrub or a transform only: latest wins. While one is on its way, a newer
+   * move with the same key replaces the one waiting instead of queueing behind it, and the
+   * next is sent only after a frame, once the last update could be applied and painted.
+   * Without this a slow redraw builds a backlog and the result trails the pointer.
+   *
+   * **Never use it for input that accumulates**, such as a paint stroke: the moves it drops
+   * are gone. A stroke batches its own cells and calls `run` once per frame.
+   */
+  drag(key: string, id: string, payload: unknown, coalesce?: string): Promise<Ran>;
+  /** Opens a gesture; its token is what `end` and `cancel` take. */
+  begin(label: string): Promise<number>;
+  /** Takes the token, or its promise, so it is queued behind everything the gesture ran. */
+  end(token: number | Promise<number>): Promise<void>;
+  cancel(token: number | Promise<number>): Promise<void>;
+  view(): Promise<View>;
+  status(): Promise<Status>;
+  commands(payload?: unknown): Promise<CommandState[]>;
+}
+
+export function createChannel(backend: PomBackend, options: ChannelOptions = {}): Channel {
+  const nextFrame = options.nextFrame ?? defaultNextFrame;
+  let release: () => void = () => undefined;
+  let chain: Promise<unknown> = options.held
+    ? new Promise<void>((resolve) => {
+        release = resolve;
+      })
+    : Promise.resolve();
+  let pending = 0;
+  const idle = new Set<() => void>();
+
+  /** Runs `f` after every call made before it, and after the gate opens. */
+  function queued<T>(f: () => Promise<T>): Promise<T> {
+    pending += 1;
+    const next = chain.then(f);
+    chain = next.catch(() => undefined);
+    const settle = () => {
+      pending -= 1;
+      if (pending === 0) for (const f of [...idle]) f();
+    };
+    next.then(settle, settle);
+    return next;
+  }
+
+  const waiting = new Map<string, Waiting>();
+
+  return {
+    get pending() {
+      return pending;
+    },
+    release: () => release(),
+    onIdle: (f) => {
+      idle.add(f);
+      return () => {
+        idle.delete(f);
+      };
+    },
+    run: (id, payload = {}, coalesce) => queued(() => backend.run(id, payload, coalesce)),
+    drag(key, id, payload, coalesce) {
+      const w = waiting.get(key);
+      if (w) {
+        w.id = id;
+        w.payload = payload;
+        w.coalesce = coalesce;
+        return w.done;
+      }
+      const entry = { id, payload, coalesce } as Waiting;
+      waiting.set(key, entry);
+      entry.done = queued(async () => {
+        waiting.delete(key);
+        try {
+          return await backend.run(entry.id, entry.payload, entry.coalesce);
+        } finally {
+          await nextFrame();
+        }
+      });
+      return entry.done;
+    },
+    begin: (label) => queued(() => backend.begin(label)),
+    end: (token) =>
+      queued(async () => {
+        const t = await Promise.resolve(token).catch(() => null);
+        if (t !== null) await backend.end(t);
+      }),
+    cancel: (token) =>
+      queued(async () => {
+        const t = await Promise.resolve(token).catch(() => null);
+        if (t !== null) await backend.cancel(t);
+      }),
+    view: () => queued(() => backend.view()),
+    status: () => queued(() => backend.status()),
+    commands: (payload) => queued(() => backend.commands(payload)),
+  };
+}

package/src-ts/index.ts

@@ -0,0 +1,8 @@
+export type { PomBackend, Unlisten } from './backend.ts';
+export { COMMIT_EVENT, STATUS_EVENT, tauriBackend } from './backend.ts';
+export type { Channel, ChannelOptions } from './channel.ts';
+export { createChannel } from './channel.ts';
+export type { Applied, MirrorOptions } from './mirror.ts';
+export { createMirror, Mirror, Rows } from './mirror.ts';
+export { PomProvider, useChildren, useMirror, useNode, useNodeAt, useStatus } from './react.ts';
+export type * from './wire.ts';

package/src-ts/mirror.ts

@@ -0,0 +1,248 @@
+/**
+ * The document as rows, by id with a path index (rhizome decision 48): a view, then updates.
+ * Read-only: every edit is a command through the channel, and the commit that comes back is
+ * what changes the mirror. Create it outside React, `start()` it once, and read it through the
+ * hooks.
+ */
+import type { PomBackend, Unlisten } from './backend.ts';
+import type { NodeId, Row, Schema, Status, Update, View } from './wire.ts';
+
+export interface MirrorOptions {
+  /** A re-read that failed after the mirror started. The mirror keeps what it had. */
+  onError?: (error: unknown) => void;
+}
+
+type Event = { kind: 'update'; update: Update } | { kind: 'status'; status: Status };
+
+/** What `Mirror.apply` did with an update. */
+export type Applied = 'applied' | 'stale' | 'gap';
+
+/** The rows and the rules for taking updates: no backend, no events. `Mirror` drives it. */
+export class Rows {
+  private byId = new Map<NodeId, Row>();
+  private paths = new Map<string, NodeId>();
+  schema: Schema = { categories: [], types: [] };
+  seq = 0;
+  generation = 0;
+
+  get size(): number {
+    return this.byId.size;
+  }
+
+  ids(): IterableIterator<NodeId> {
+    return this.byId.keys();
+  }
+
+  get(id: NodeId): Row | undefined {
+    return this.byId.get(id);
+  }
+
+  byPath(path: string): Row | undefined {
+    const id = this.paths.get(path);
+    return id === undefined ? undefined : this.byId.get(id);
+  }
+
+  load(view: View): void {
+    this.byId.clear();
+    this.paths.clear();
+    for (const r of view.rows) this.put(r);
+    this.schema = view.schema;
+    this.seq = view.seq;
+    this.generation = view.generation;
+  }
+
+  /**
+   * An update applies when it is next in line. `stale` is one from an older generation, or at
+   * or before the seq the mirror has. `gap` is anything else: a seq that skips, or a
+   * generation the mirror hasn't loaded yet. Either way the caller re-reads the view.
+   */
+  apply(u: Update): Applied {
+    if (u.generation < this.generation) return 'stale';
+    if (u.generation > this.generation) return 'gap';
+    if (u.seq <= this.seq) return 'stale';
+    if (u.seq !== this.seq + 1) return 'gap';
+    this.seq = u.seq;
+    for (const id of u.removed) this.drop(id);
+    for (const r of u.rows) this.put(r);
+    return 'applied';
+  }
+
+  private put(r: Row): void {
+    const old = this.byId.get(r.id);
+    if (old && old.path !== r.path && this.paths.get(old.path) === r.id) {
+      this.paths.delete(old.path);
+    }
+    this.byId.set(r.id, r);
+    this.paths.set(r.path, r.id);
+  }
+
+  private drop(id: NodeId): void {
+    const old = this.byId.get(id);
+    if (old && this.paths.get(old.path) === id) this.paths.delete(old.path);
+    this.byId.delete(id);
+  }
+}
+
+export class Mirror {
+  private readonly rows = new Rows();
+  private readonly listeners = new Set<() => void>();
+  private current: Status | null = null;
+  private loaded = false;
+  private reading = false;
+  private again = false;
+  private buffer: Event[] = [];
+  private unlisten: Unlisten[] = [];
+  private started = false;
+  private stopped = false;
+
+  constructor(
+    private readonly backend: PomBackend,
+    private readonly options: MirrorOptions = {},
+  ) {}
+
+  /** `true` once the first view has loaded. */
+  get ready(): boolean {
+    return this.loaded;
+  }
+
+  get status(): Status | null {
+    return this.current;
+  }
+
+  get schema(): Schema {
+    return this.rows.schema;
+  }
+
+  get seq(): number {
+    return this.rows.seq;
+  }
+
+  get generation(): number {
+    return this.rows.generation;
+  }
+
+  get size(): number {
+    return this.rows.size;
+  }
+
+  /** The row for `id`. A row is immutable; a changed node is a new object. */
+  node(id: NodeId): Row | undefined {
+    return this.rows.get(id);
+  }
+
+  nodeAt(path: string): Row | undefined {
+    return this.rows.byPath(path);
+  }
+
+  ids(): IterableIterator<NodeId> {
+    return this.rows.ids();
+  }
+
+  /** Calls `f` after the mirror changes. Returns a function that stops listening. */
+  subscribe = (f: () => void): (() => void) => {
+    this.listeners.add(f);
+    return () => {
+      this.listeners.delete(f);
+    };
+  };
+
+  /**
+   * Connects, listens, then reads the view, in that order, so nothing a commit sends in
+   * between is lost: updates and statuses that arrive before the view resolves wait, and are
+   * applied after it (the ones it already covers are dropped as stale). Answers what
+   * `connect` did: a path macOS asked the app to open before the page was listening.
+   * Calling it again is a no-op.
+   */
+  async start(): Promise<string | null> {
+    if (this.started || this.stopped) return null;
+    this.started = true;
+    const held = await this.backend.connect();
+    this.reading = true; // from here on, events wait for the view
+    const u = await this.backend.onUpdate((update) => this.receive({ kind: 'update', update }));
+    const s = await this.backend.onStatus((status) => this.receive({ kind: 'status', status }));
+    this.unlisten = [u, s];
+    if (this.stopped) {
+      this.stop();
+      return held;
+    }
+    await this.reload(true);
+    // connect sends the status as an event; ask as well, for one that went before we listened
+    if (this.current === null && !this.stopped) {
+      const status = await this.backend.status();
+      if (this.current === null) this.setStatus(status);
+    }
+    return held;
+  }
+
+  /** Stops listening. The rows stay readable. */
+  stop(): void {
+    this.stopped = true;
+    for (const f of this.unlisten.splice(0)) f();
+    this.buffer = [];
+  }
+
+  private receive(e: Event): void {
+    if (this.stopped) return;
+    if (this.reading) this.buffer.push(e);
+    else this.process(e);
+  }
+
+  private process(e: Event): void {
+    if (e.kind === 'status') {
+      this.setStatus(e.status);
+      return;
+    }
+    const result = this.rows.apply(e.update);
+    if (result === 'applied') this.notify();
+    else if (result === 'gap') this.refresh();
+  }
+
+  private setStatus(s: Status): void {
+    this.current = s;
+    this.notify();
+    if (this.loaded && s.generation > this.rows.generation) this.refresh();
+  }
+
+  private refresh(): void {
+    this.reload().catch((error) => this.options.onError?.(error));
+  }
+
+  /**
+   * Reads the view and takes it, then applies what arrived while it was on its way. A
+   * re-read asked for meanwhile (another gap, a newer generation) runs again after.
+   */
+  private async reload(initial = false): Promise<void> {
+    if (this.reading && !initial) {
+      this.again = true;
+      return;
+    }
+    this.reading = true;
+    try {
+      do {
+        this.again = false;
+        const view = await this.backend.view();
+        if (this.stopped) return;
+        // only ever forward: a view older than what is held would undo an update
+        if (!this.loaded || view.generation > this.rows.generation || view.seq >= this.rows.seq) {
+          this.rows.load(view);
+          this.loaded = true;
+          this.notify();
+        }
+        const waiting = this.buffer.splice(0);
+        for (const e of waiting) this.process(e);
+      } while (this.again && !this.stopped);
+    } finally {
+      this.reading = false;
+      this.again = false;
+    }
+  }
+
+  private notify(): void {
+    for (const f of [...this.listeners]) f();
+  }
+}
+
+/** A mirror for `backend`. Call `start()` on it once. */
+export function createMirror(backend: PomBackend, options?: MirrorOptions): Mirror {
+  return new Mirror(backend, options);
+}

package/src-ts/react.ts

@@ -0,0 +1,73 @@
+/**
+ * React hooks over a `Mirror`, through `useSyncExternalStore`. The mirror is made outside
+ * React and handed in with `PomProvider`, so StrictMode's double mount costs nothing. Rows are
+ * immutable and a changed node is a new object, so a hook returns the same value until its own
+ * node changes and the component re-renders only then.
+ */
+import {
+  createContext,
+  createElement,
+  type ReactNode,
+  useContext,
+  useSyncExternalStore,
+} from 'react';
+import type { Mirror } from './mirror.ts';
+import type { NodeId, Row, Status } from './wire.ts';
+
+const MirrorContext = createContext<Mirror | null>(null);
+
+export function PomProvider(props: { mirror: Mirror; children?: ReactNode }): ReactNode {
+  return createElement(MirrorContext.Provider, { value: props.mirror }, props.children);
+}
+
+/** The mirror from the nearest `PomProvider`. */
+export function useMirror(): Mirror {
+  const mirror = useContext(MirrorContext);
+  if (!mirror) throw new Error('usePom hooks need a <PomProvider mirror={…}> above them');
+  return mirror;
+}
+
+/** The node with this id, or `undefined` while it isn't there (or before the first view). */
+export function useNode(id: NodeId | null | undefined): Row | undefined {
+  const mirror = useMirror();
+  return useSyncExternalStore(
+    mirror.subscribe,
+    () => (id == null ? undefined : mirror.node(id)),
+    () => undefined,
+  );
+}
+
+/** The node at this path, e.g. `/images/sky`. It follows a rename or a move. */
+export function useNodeAt(path: string | null | undefined): Row | undefined {
+  const mirror = useMirror();
+  return useSyncExternalStore(
+    mirror.subscribe,
+    () => (path == null ? undefined : mirror.nodeAt(path)),
+    () => undefined,
+  );
+}
+
+const NONE: readonly NodeId[] = Object.freeze([]);
+
+/**
+ * The ids in the node's named order, such as `draw`: the row's own `orders[order]` list, so it
+ * is the same array until the node changes. Empty when the node or the order isn't there.
+ */
+export function useChildren(id: NodeId | null | undefined, order: string): readonly NodeId[] {
+  const mirror = useMirror();
+  return useSyncExternalStore(
+    mirror.subscribe,
+    () => (id == null ? undefined : mirror.node(id)?.orders?.[order]) ?? NONE,
+    () => NONE,
+  );
+}
+
+/** The document's status (title, unsaved, undo and redo labels, gesture), or `null` before it. */
+export function useStatus(): Status | null {
+  const mirror = useMirror();
+  return useSyncExternalStore(
+    mirror.subscribe,
+    () => mirror.status,
+    () => null,
+  );
+}

package/src-ts/wire.ts

@@ -0,0 +1,188 @@
+/**
+ * The wire types: what `rhizome-pom-tauri` carries, written from the Rust structs. Each says
+ * which one it follows. Rust skips empty maps and lists and unset options when it serialises,
+ * so those fields are optional here. A test reads the goldens in the crates' `tests/golden/` folders so
+ * a drift between the two fails the build.
+ */
+
+/** A node's id: 26 characters of Crockford base32 (rhizome-core `NodeId`, as a string). */
+export type NodeId = string;
+
+/** Plain JSON, as a node's values travel (rhizome-core `Value::to_json`). */
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+/** What a node is to the tree (rhizome-core `Role`, snake_case). */
+export type Role = 'root' | 'category' | 'group' | 'node' | 'opaque';
+
+/** What a binding attaches to on its target (rhizome-core `On`, snake_case). */
+export type On = { slot: string } | { value: string };
+
+/** A reference by id as a row carries it (rhizome-core `RefRow`). */
+export interface RefRow {
+  file?: string;
+  node?: NodeId;
+}
+
+/** A reference as a change carries it (rhizome-core `Ref`): a row's, plus the path written to disk. */
+export interface Ref extends RefRow {
+  path?: string;
+}
+
+/** A binding onto a node, its values resolved (rhizome-core `BindingRow`). */
+export interface BindingRow {
+  on: On;
+  source: NodeId;
+  values?: Record<string, Json>;
+}
+
+/** One node as plain data (rhizome-core `Row`; `type_name` is `type` on the wire). */
+export interface Row {
+  id: NodeId;
+  path: string;
+  name: string;
+  type: string;
+  role: Role;
+  parent: NodeId | null;
+  /** Every value in the schema, resolved. */
+  values?: Record<string, Json>;
+  /** The keys actually stored; the rest are defaults. */
+  set?: string[];
+  refs?: Record<string, RefRow>;
+  bindings?: BindingRow[];
+  /** Named child orders, such as a draw order. */
+  orders?: Record<string, NodeId[]>;
+  members?: NodeId[];
+}
+
+/** Whether a category's nodes are owned by a file or built from a recipe (rhizome-core `Origin`). */
+export type Origin = 'loaded' | 'calculated';
+
+/** rhizome-core `ValueKind`, snake_case. */
+export type ValueKind =
+  | 'bool'
+  | 'int'
+  | 'float'
+  | 'text'
+  | 'choice'
+  | 'vec2'
+  | 'vec3'
+  | 'colour'
+  | 'floats'
+  | 'shaped';
+
+/** What a `shaped` value must look like (rhizome-core `Shape`, externally tagged, snake_case). */
+export type Shape =
+  | 'bool'
+  | 'int'
+  | 'float'
+  | 'text'
+  | 'vec2'
+  | 'vec3'
+  | 'colour'
+  | { choice: string[] }
+  | { list: Shape }
+  | { record: [string, Shape][] }
+  | { optional: Shape };
+
+/** rhizome-core `ValueSchema`. */
+export interface ValueSchema {
+  key: string;
+  kind: ValueKind;
+  default: Json;
+  range?: [number, number];
+  choices?: string[];
+  len?: number;
+  shape?: Shape;
+  /** The range's max is a control's end, not a limit. Absent when false. */
+  soft_max?: boolean;
+}
+
+/** rhizome-core `CategorySchema`. */
+export interface CategorySchema {
+  name: string;
+  origin: Origin;
+}
+
+/** rhizome-core `TypeSchema`. */
+export interface TypeSchema {
+  name: string;
+  categories?: string[];
+  values?: ValueSchema[];
+  refs?: string[];
+  slots?: string[];
+  bindable?: ValueSchema[];
+}
+
+/** The registry as plain data (rhizome-core `Schema`). */
+export interface Schema {
+  categories: CategorySchema[];
+  types: TypeSchema[];
+}
+
+/** One entry of a commit, tagged by `change` (rhizome-core `Change` with its flattened `ChangeKind`). */
+export type Change = { path: string; id: NodeId } & (
+  | { change: 'added'; type: string }
+  | { change: 'removed'; type: string }
+  | { change: 'moved'; from: string }
+  | { change: 'value'; key: string; from: Json | null; to: Json | null }
+  | { change: 'ref'; key: string; from: Ref | null; to: Ref | null }
+  | {
+      change: 'bound';
+      on: On;
+      source: NodeId;
+      from: Record<string, Json> | null;
+      to: Record<string, Json> | null;
+    }
+  | { change: 'reordered'; order: string; from: NodeId[]; to: NodeId[] }
+  | { change: 'membership'; added: NodeId[]; removed: NodeId[] }
+);
+
+/** A commit (rhizome-core `Commit`; a `Changeset` is its entries as a list). */
+export interface Commit {
+  seq: number;
+  label: string;
+  changes: Change[];
+}
+
+/** The whole document, for a mirror to start from (rhizome-pom `View`). */
+export interface View {
+  seq: number;
+  generation: number;
+  schema: Schema;
+  rows: Row[];
+}
+
+/** A commit as a mirror takes it, on `pom://commit` (rhizome-pom `Update`). */
+export interface Update {
+  seq: number;
+  label: string;
+  changes: Change[];
+  /** The fresh rows of every node the commit touched. */
+  rows: Row[];
+  removed: NodeId[];
+  /** The tree this belongs to. */
+  generation: number;
+}
+
+/** The document as a window shows it, on `pom://status` (rhizome-pom `Status`). */
+export interface Status {
+  title: string;
+  path: string | null;
+  unsaved: boolean;
+  /** What Undo and Redo would do, when they can. */
+  undo: string | null;
+  redo: string | null;
+  gesture: boolean;
+  /** Only grows; moves whenever the whole tree is replaced. */
+  generation: number;
+}
+
+/** What `pom_run` answers (rhizome-pom `Ran`, snake_case, externally tagged). */
+export type Ran = 'nothing' | { committed: Commit } | { text: string };
+
+/** A command as a menu shows it (rhizome-pom `CommandState`). */
+export interface CommandState {
+  id: string;
+  label: string;
+  enabled: boolean;
+}