JavaScript API

The engine reference for consumers that embed noggin in a JavaScript runtime — the VS Code extension, the desktop app, the docs playground, custom tooling, tests. Detail pages are generated by TypeDoc from the hand-written .d.mts files under engine/, so descriptions, signatures, and release tags stay in sync with the source automatically.

Release tiers

Every public symbol carries a TSDoc release tag. Breaking changes respect the tier:

• @public — stable. Breaking changes require a major bump.
• @experimental — public but the shape may still change.
• @deprecated — still works; scheduled for removal in a future major.

Symbols tagged @internal exist in the source but are deliberately hidden from this reference. Consumers should not depend on internal exports.

The groups

• Handles — the live-noggin surface: Noggin and NogginStore.
• Opening a noggin — openNoggin plus the provider registry.
• Verbs — the verbs singleton, one options interface per verb, plus small wiring types.
• Core data model — NogginDocument, Item, view shapes, Placement, and type aliases.
• Atomic ops — AtomicOp, applyOps, plus pure document utilities.
• Events — ItemChange / ChangeEvent and the Event / Disposable subscribe primitive.
• Errors — NogginError, the NogginErrorCode union, and NogginErrorData.
• Response envelope — JsonEnvelope and its helpers.
• Path utilities — pure walkers over a {items, active} snapshot.
• Constants — SCHEMA_VERSION, RESPONSE_ENVELOPE_VERSION, CLOSE_NOTE_TEXT.
• Serializers — YAML and JSON document I/O.

Quick example

import '@noggin/engine/providers/file'; // side-effect: registers file://
import { openNoggin } from '@noggin/engine';

const noggin = await openNoggin('file:///work/today.yaml', { watch: true });
const view = await noggin.push({ title: 'go async' });
console.log(noggin.active?.title);
noggin.onDidChange((changes) => render(noggin.items, changes));
await noggin.dispose();

Every URI passed to openNoggin needs an explicit scheme (file://, memory://, localstorage://, https://). Hosts that take a raw OS path from a file dialog or CLI flag either convert to file:// at the boundary or use openFileNoggin(path) from @noggin/engine/providers/file.

Anatomy of a mutation

Every write follows the same three-step path so behaviour is identical across providers:

1. A verb (e.g. verbs.push) reads current state via the noggin's accessors and composes a list of AtomicOps.
2. The verb calls noggin.apply(ops) once. Providers execute the list atomically and normalise + validate the resulting document.
3. The provider fires onDidChange with a ChangeEvent that describes what shifted between the previous and current snapshot.

Every provider fires the same ChangeEvent shape whether the change originated in-process or from the outside world, so consumers write one listener that handles both.

Errors

Verbs and provider operations throw NogginError on failure. Each carries a stable string code plus a frozen structured data payload. Hosts that render user-facing strings key off code; the raw message is a short host-neutral fallback.

For CLI / MCP / RPC serialisation, wrap engine results with formatSuccess() / formatError() to produce a versioned JsonEnvelope.