# dirtytalk

> Dirty-tracking primitives for TypeScript: after a mutation, what changed, who cares, and when do we tell them? `@dirtytalk/engine` is the space-agnostic core (DirtyChannel + schedulers); `@dirtytalk/structural` tracks paths in state trees; `@dirtytalk/spatial` tracks damage rects in 2D scene graphs.

Every page below is plain Markdown. The full documentation in one file: https://dirtytalk.42.dog/llms-full.txt

## Getting started

- [Introduction](https://dirtytalk.42.dog/docs.md): dirtytalk is a set of dirty-tracking primitives that answer what changed, who cares, and when to tell them, for any domain.
- [Installation](https://dirtytalk.42.dog/docs/installation.md): Install @dirtytalk/engine, structural and spatial with pnpm, plus module formats, TypeScript, runtime requirements and version pinning.
- [Concepts](https://dirtytalk.42.dog/docs/concepts.md): The model shared by all dirtytalk packages: regions, spaces, mark-coalesce-flush, interest thunks, schedulers and re-entrancy.

## Engine

- [Engine overview](https://dirtytalk.42.dog/docs/engine.md): @dirtytalk/engine is a zero-dependency dirty-tracking core: a Space algebra, pluggable schedulers and a DirtyChannel that coalesces marks.
- [DirtyChannel](https://dirtytalk.42.dog/docs/engine/dirty-channel.md): How DirtyChannel accumulates marks, coalesces them per scheduler window, notifies interested subscribers, handles re-entrancy and reports errors.
- [Schedulers](https://dirtytalk.42.dog/docs/engine/schedulers.md): The Scheduler interface and the four built-in schedulers (Sync, Manual, Microtask, RAF): when each flushes, fallbacks, how to choose and write your own.
- [Custom spaces](https://dirtytalk.42.dog/docs/engine/custom-spaces.md): Implement the Space<Region> contract for your own domain, with laws, worked key-set and numeric-range examples, the optional unionInto, and common pitfalls.
- [API reference](https://dirtytalk.42.dog/docs/engine/api.md): Reference for every public export of @dirtytalk/engine with exact TypeScript signatures, parameters, return values, behaviour and examples.

## Structural

- [Overview](https://dirtytalk.42.dog/docs/structural.md): Path-based dirty tracking for state trees, built on @dirtytalk/engine. Consumers wake only when a path they read changes.
- [Containers](https://dirtytalk.42.dog/docs/structural/containers.md): StructuralContainer holds immutable state, marks changed paths on a DirtyChannel, and wakes only consumers that read them.
- [Tracking](https://dirtytalk.42.dog/docs/structural/tracking.md): trackRender records the paths a consumer reads through a proxy. Covers ProxyCache, raw, hazards, ancestor wake-ups and diff helpers.
- [React](https://dirtytalk.42.dog/docs/structural/react.md): useStructural subscribes a component to a StructuralContainer and re-renders it only when a path it read during render changes.
- [API reference](https://dirtytalk.42.dog/docs/structural/api.md): Every public export of @dirtytalk/structural and @dirtytalk/structural/react with TypeScript signatures, parameters, returns and examples.

## Spatial

- [Overview](https://dirtytalk.42.dog/docs/spatial.md): @dirtytalk/spatial tracks damage as rects on top of @dirtytalk/engine, so a 2D scene graph can repaint only the regions that changed.
- [Scene graph](https://dirtytalk.42.dog/docs/spatial/scene-graph.md): SceneNode and SceneRoot: bounds, parent/children, damage kinds, the data, layout, paint pipeline, batching, subclassing and scheduler choice.
- [Rendering](https://dirtytalk.42.dog/docs/spatial/rendering.md): The Renderer2D contract, which damage regions a frame receives, FrameTiming, the Damage and DirtyRegion types, rect helpers and a Canvas2D renderer.
- [Pointer events](https://dirtytalk.42.dog/docs/spatial/pointer-events.md): Hit-test a scene graph and route pointer events to nodes with PointerRouter, including capture semantics and DOM wiring.
- [API reference](https://dirtytalk.42.dog/docs/spatial/api.md): Every public export of @dirtytalk/spatial with exact TypeScript signatures, parameters, return values, errors and examples.