# `@crouton-kit/crouter` public API

This is a pointer document, not a second source of truth. The canonical
surface is `package.json#exports` plus the two source barrels it points at —
read this file to know WHERE to look, not to get a duplicated symbol list that
can drift.

## Supported import surfaces

`package.json#exports` gates the package to exactly three subpaths. Nothing
else resolves — deep imports into `dist/` or `src/` are unsupported and will
break without notice across versions.

| Import specifier | Source barrel | Purpose |
|---|---|---|
| `@crouton-kit/crouter` | `src/index.ts` → `dist/index.js` | The one sanctioned library surface: runtime control (`spawnChild`, `reviveNode`, `closeNode`, `appendInbox`), canvas reads (`getNode`, `listNodes`, `nodeDir`, `asksForNodes`, `readTelemetry`, …), the broker socket client (`ViewSocketClient`), the broker wire protocol (frame types + codec), and a small set of side-effect-free utilities (see below). |
| `@crouton-kit/crouter/cli` | `src/cli.ts` → `dist/cli.js` | The `crtr` CLI entrypoint. Not a library API — invoked as a program, not imported for its exports. |
| `@crouton-kit/crouter/web` | `src/web/index.ts` → `dist/web/index.js` | The dual-target view framework (`ViewPane`, `useViewCore`, `createViewStore`, `ViewChrome`, the four-state vocabulary) that a crtr *view* (`web.jsx`) imports to compose into the web shell. Unrelated to consuming crtr as a runtime library. |

Both barrels declare no load-time side effects and no circular imports —
importing either is safe to do speculatively.

## Root-barrel surface, by area

Read `src/index.ts` for the exact current export list (it is short and
comment-organized); this table is the map, not the inventory:

- **Runtime control** — `spawnChild`, `reviveNode`, `closeNode`,
  `appendInbox`, `appendSituationalContext` (+ their result/opts types).
  `reviveNode` is the only sanctioned launcher of a node's broker engine; do
  not construct a broker process out-of-band. `appendSituationalContext`
  upserts a node's hidden ambient "current situation" text without exposing
  the underlying storage file.
- **Canvas reads** — `getNode`, `listNodes`, `nodeDir`, `asksForNodes`,
  `asksAcrossCanvas`, `readTelemetry`, `readContextTokens` (+ their types).
  Read-only queries against the canvas.db-backed node graph.
- **Broker client** — `ViewSocketClient`, `BrokerUnavailableError`. A typed
  client for a node's `view.sock` (see `docs/compat/hearth-crtr-v2.md` for
  the socket path resolution and a minimal-subset alternative that avoids
  depending on this class).
- **Broker wire protocol** — `encodeFrame`, `FrameDecoder`,
  `FrameOverflowError`, `CLIENT_READ_CAPS`, `BROKER_READ_CAPS`, and every
  frame/protocol type (`WelcomeFrame`, `AckFrame`, `HelloFrame`,
  `ReloadAuthFrame` is intentionally NOT re-exported by name here but is
  covered as a documented wire contract — see the compat note).
- **Utility exports** — `general` (an error constructor from
  `core/errors.js`; the type `CrtrError` is exported type-only) and `nowIso`
  (an ISO-timestamp helper from `core/fs-utils.js`). Both are plain,
  side-effect-free functions over Node builtins. No other error helper
  (`notFound`, `usage`, `ambiguous`, `network`, `notImplemented`) is exported
  — construct a `general(message, details)` error instead if you need one
  from outside the package.

## What is NOT public

- `startWebServer` / `RunningWebServer` (`src/clients/web/server.ts`) are
  **not exported** and are not part of the public API. A consumer that needs
  an HTTP front for guest/remote use cases builds its own process; it does
  not import crtr's web server.
- Anything under `src/commands/`, `src/daemon/`, `src/core/canvas/*` (writer
  paths), or any file not reachable from one of the three barrels above.
- Deep imports (`@crouton-kit/crouter/dist/...`, `@crouton-kit/crouter/src/...`)
  — the `exports` map blocks these at resolution time for ESM/Node16
  consumers; treat any working deep import as an accident, not a contract.

## External runtime contracts (not library imports)

A consumer that runs alongside crtr (a separate process, a separate repo)
also has a CLI/socket/schema surface to depend on instead of an import.
That contract — `crtr sys version`, `crtr node message send`, the in-guest web port,
the broker `view.sock` `reload_auth` subset, and the canvas.db byte-shape —
is documented separately and versioned: see `docs/compat/hearth-crtr-v2.md`.

## Packaging

`docs/` is listed in `package.json#files`, so this note and the compat note
ship inside the published npm package, not only in the GitHub repo.