Internals

1. One update path
2. Module map
3. Layering rules
4. Where to look when something breaks
5. Budgets
6. Test environment notes

These notes explain the core implementation. For the public contract, read concepts.md. This section covers internal mechanisms, invariants, and changes that can break them.

One update path

The whole library is one pipeline with adapters on either end. Everything downstream of a yield is the same code whether the state lives in this tab or on a server:

flowchart LR
    Y["yield next"] --> R["reconcile(prev, next)"]
    R --> P["patch<br/>(set / del / splice on JSON pointers)"]
    P --> A{"intersects this reader's<br/>recorded paths?"}
    A -->|no| S["reader sleeps"]
    A -->|yes| G["bump its gate"]
    G --> F["flush queue<br/>(one drain per microtask)"]
    F --> E["reader runs"]
    P -.->|"same patch, JSON-encoded"| W["wire → a remote reader"]

Keep two consequences in mind when changing this code:

• The diff is the contract. The patch a local binding reacts to is the patch that crosses the socket. packages/wire/spec/ certifies external hosts against those op shapes, so a change to the op vocabulary is a protocol change, not an implementation detail.
• Precision is a property of reads, not writes. Application code writes immutable updates and never declares dependencies. Everything fine-grained comes from the reader side recording what it touched.

Module map

flowchart TD
    subgraph core["@nonchalant/core"]
        TY["types.ts<br/>the Process type surface"]
        RC["reconcile.ts + pointer.ts<br/>diff + apply"]
        TR["track.ts + paths.ts + unwrap.ts<br/>read recording, patch matching"]
        SY["system.ts<br/>alien-signals port; do not layer here"]
        GR["graph.ts + watch.ts + queue.ts<br/>source / gate / effect / flush"]
        PR["process.ts + mailbox / scope / calls / instrument<br/>mailbox + drive loop + ownership"]
        RG["registry.ts + key.ts<br/>get-or-spawn by name"]
        IX["index.ts<br/>spawn, derive, cell, mount"]
    end
    DOM["@nonchalant/dom<br/>VNode → DOM, keyed regions"]
    WIRE["@nonchalant/wire<br/>codec, connect, expose"]
    HOST["@nonchalant/host<br/>Node WebSocket host"]

    RC --> TR
    RC --> GR
    TR --> GR
    SY --> GR
    GR --> PR
    PR --> RG
    GR --> IX
    PR --> IX
    RG --> IX
    TY -.-> PR
    TY -.-> RG
    IX --> DOM
    IX --> WIRE
    RC --> WIRE
    WIRE --> HOST

Read bottom-up on first contact: reconcile → track → graph → process → registry. Each layer only knows about the ones below it.

Layering rules

These are the constraints that keep the design coherent; CLAUDE.md carries the full list.

• system.ts stays 1:1 with upstream alien-signals. It is a faithful MIT port, attributed in THIRD-PARTY-NOTICES.md. Path precision is layered in graph.ts via gates precisely so the port never needs editing. Changes go in graph.ts.
• packages/core never touches the DOM, and packages/wire stays isomorphic and DOM-free (host-universal globals reached through globalThis are fine).
• Budgets are CI assertions. Tighten them when you can; never loosen one to make a change fit.
• New public concepts must dissolve at least two existing problems. The registry earned its place by being DI, query cache, and remote addressing at once. Otherwise it belongs in recipes.md as userland code.

Where to look when something breaks

Budgets

Every performance or granularity claim in the docs points at the test that enforces it:

Test environment notes

Two environment quirks that cause confusing false failures:

• Leak tests need gc({ execution: 'async' }). Plain gc() false-fails under V8 conservative stack scanning.
• happy-dom's MutationObserver misses characterData, so DOM-write tests spy on Text#data and setAttribute instead of observing mutations.

This page's source on GitHub