# API overview (/docs/api)

> Entry points, what each exports, and where each part of the API is documented.

VisDelta's API has three parts: **builders** that create immutable chart
states, **`delta()`** to inspect what changed, and **`transition()`** and
**`sequence()`** to render a seekable path.

<TransitionWorkbench />

The workbench above is a real controller. Seek in either direction, then switch
the inspector to **Delta** for `change.delta` or **Spec** for the resolved
endpoints.

```ts
import { bar } from 'visdelta/bar';                         // builders
import { delta } from 'visdelta/core';                       // inspection
import { transition, sequence } from 'visdelta/transition';  // rendering
import 'visdelta/style.css';
```

JSON transport uses `parseSpec` and `stringifySpec` from `visdelta/core` or
`visdelta`. See [JSON specs](/docs/guides/json) for validation boundaries and
using the same `ViewSpec` with builders, playback and React.

## Reference pages [#reference-pages]

<Cards>
  <Card title="transition()" href="/docs/api/transition" description="Options and the pair controller." />
  <Card title="sequence()" href="/docs/api/sequence" description="Options and the timeline controller." />
  <Card title="React" href="/docs/guides/react" description="One Chart component for states, pairs and sequences." />
  <Card title="Builders" href="/docs/api/builders" description="Every builder method, by chart." />
  <Card title="Core" href="/docs/api/core" description="delta(), declaration edits and planning, identity and lineage." />
  <Card title="Types" href="/docs/api/types" description="StateChange, VisualizationWarning, styles and layout options." />
</Cards>

## Entry points [#entry-points]

| Entry                  | Main exports                                                                                       |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| `visdelta`             | Every builder, `delta`, `transition`, `sequence`, `visualizationWarnings`, `smallMultiples`, chart styles, `defineChartType`, `registerChartModule` and the core helpers |
| `visdelta/bar`         | `bar`, `BarState`, `barModule`, `createBarGrainDeclarationOperationCodec`                          |
| `visdelta/line`        | `line`, `LineState`, `lineModule`, `D3_CURVE_NAMES`                                                |
| `visdelta/area`        | `area`, `AreaState`, `areaModule`, `D3_AREA_CURVE_NAMES`                                           |
| `visdelta/point`       | `point`, `PointState`, `pointModule`                                                               |
| `visdelta/unit`        | `unit`, `UnitState`, `unitModule`, `UNIT_LAYOUTS`                                                  |
| `visdelta/pie`         | `pie`, `PieState`, `pieModule`                                                                     |
| `visdelta/transition`  | `transition`, `sequence`                                                                           |
| `visdelta/react`       | Optional React `Chart`, `ChartProps` and `ChartController` |
| `visdelta/core`        | `delta`, `visualizationSpec`, declaration edits and planning, identity, lineage and camera helpers |
| `visdelta/facet`       | `smallMultiples`                                                                                   |
| `visdelta/chart-style` | `defineChartStyle`, `d3ChartStyle`, `paperChartStyle`, `darkChartStyle`, `editorialChartStyle`, `chartStylePresets` |
| `visdelta/plugins`     | `defineChartType`, `defineChartModule`, `ChartState`, `registerChartModule`, `motion`, `directionalEase` and SDK types |
| `visdelta/toolkit`     | Optional scale, timing, geometry, topology, matching and policy helpers for plugins               |
| `visdelta/browser`     | The browser-global adapter used by the `VisDelta` global bundle                                    |
| `visdelta/style.css`   | The required base stylesheet                                                                       |
| `visdelta/themes/*.css`| `default.css`, `dark.css` and `paper.css` token themes                                             |

Importing an entry never registers chart types globally. A builder carries its
own lazily loaded module; registration is needed only for plain JSON specs.

## TypeScript [#typescript]

Declarations ship with the package. Commonly used types:

```ts
import type { Visualization, VisualizationTransition, VisualizationSequence, TransitionOptions, PlayOptions } from 'visdelta/transition';
import type { DeltaResult, StateChange, StateChangeCategory } from 'visdelta/core';
import type { VisualizationWarning } from 'visdelta';
import type { ChartStyleModule } from 'visdelta/chart-style';
```

## Current boundaries [#current-boundaries]

- Endpoint chart types must match; Bar-to-Line is rejected.
- VisDelta depends on the `d3-*` modules it renders with; they are not injected
  or configurable.
- Declared transforms execute within VisDelta; data cleaning stays outside it.
- Controls call `progress()` from outside the library.

## Persistent views [#persistent-views]

Use `render(target, spec, options)` from `visdelta` to mount JSON strings, plain
specs or builders. The returned view provides `update`, `render`, `transition`,
`snapshot`, `resize` and `destroy`. Updates use a latest-pending policy by
default. See [JSON specs](/docs/guides/json) for scheduling, lifecycle and scoped
module examples.

`view.edit(message, options?)` accepts a fluent JSON batch with `requestId`,
`baseRevision` and `edits: [{ method, args }]`. It returns the same completion
result as `update()`. The Bar adapter supports a conservative method subset;
see [small agent edits](/docs/guides/json#small-edits-from-an-agent) for supported
methods, conflict handling and retry limits.