# VisDelta: start here for agents

Current package: visdelta@0.4.2. Copy this complete HTML into index.html,
serve it over HTTP (for example `npx serve .`), and open the printed URL.

```html
<!doctype html>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/visdelta@0.4.2/dist/visdelta.css">
<div id="chart" style="width:100%;max-width:640px;height:400px"></div>
<script type="module">
  import { bar, transition, visualizationWarnings }
    from 'https://cdn.jsdelivr.net/npm/visdelta@0.4.2/+esm';
  const rows = [
    { product: 'Hardware', revenue: 12, profit: 5 },
    { product: 'Software', revenue: 18, profit: 11 },
    { product: 'Services', revenue: 9, profit: 7 },
  ];
  const from = bar(rows).x('product').y('revenue').key('product');
  const to = from.y('profit');
  console.log(await visualizationWarnings(to));
  const change = await transition(from, to, {
    target: '#chart', width: 'auto', height: 400,
  });
  // A complete, synchronous endpoint. play() returns a controller, not a Promise.
  change.progress(1);
</script>
```

## Invariants and current boundaries

- Supply tidy rows. Declare each encoding; there is no implicit color field.
- Keep source-record identity (datumKey) separate from mark identity (key).
- where() changes membership; highlight() changes emphasis; focus() moves the
  camera without filtering. Filters do not reset category colors or legends.
- Line fits inferred x/y domains to visible rows. Other charts have their own
  domain rules: do not assume where() always refits every chart's axes.
- Explicit valid numeric/temporal position domains are not niced. Inferred
  domains may be rounded. Write fixed domains only when the story needs them.
- Decide whether dates mean local calendar time or absolute instants before
  parsing. The temporal axis uses local-time scaleTime; there is no utc option.
- Every frame couples marks and the scales/axes that explain them. Source data,
  semantic changes, planned stages and rendered frames are distinct layers.
- transition progress is 0..1. sequence progress is 0..states.length-1:
  1.5 means halfway through the second leg. A stage is not a state-change count.
- duration is per serial route stage, not per whole story. play() is not awaitable.
- Await transition()/sequence() before seeking; there is no additional ready.
- inspect() reports compiled SVG property tracks. It is not a mark snapshot.
  state.resolve(), inspect(t), global strict/debug and bindScroll are unavailable.
- The optional Unit directionalEase profile is an exception to strict identical
  forward/reverse frames. Follow the chart-specific contract instead of guessing.

## Verification workflow

1. Check tidy rows, field types and unique identities; preserve the source state.
2. Inspect state.rows(), state.toSpec(), delta(a, b).stateChanges and
   await visualizationWarnings(state). These work without rendering for inline
   or supplied named data; warnings do not fetch a remote dataset for you.
3. Await creation, seek exact endpoints, and inspect stageCount(), stageChanges(),
   stageOperations() and await inspect() on pair controllers. A sequence exposes
   inspect() for its active leg, not the pair's stage-count methods.
4. Check actual mark geometry, visibility and axes in a browser. Cover forward,
   reverse, scroll/scrub, resizing and reduced motion. Compare endpoints with
   independent static charts under the same dimensions, margins and theme.
5. Use screenshots for final appearance checks; a successful import or an SVG
   element alone does not prove the chart is drawn correctly.

## Copy a tested story instead of inventing a scroll controller

- [Single-file scroll story](https://songhaifan.github.io/visdelta/templates/scroll-story.html)
- [Agent workflow](https://songhaifan.github.io/visdelta/docs/guides/agent-workflow/)
- [Automatic behaviors](https://songhaifan.github.io/visdelta/docs/guides/automatic-behaviors/)
- [Scroll template and iframe contract](https://songhaifan.github.io/visdelta/docs/guides/scroll-template/)
- [Progress model](https://songhaifan.github.io/visdelta/docs/concepts/progress/)
- [Troubleshooting](https://songhaifan.github.io/visdelta/docs/guides/troubleshooting/)

Repository template: examples/templates/scroll-story.html. Its inline data is
fictional, and its only network dependencies are pinned VisDelta JS and CSS.
A content-height iframe needs manual controls or a cooperating parent page;
child scroll code cannot observe cross-origin parent scrolling on its own.

## API and semantic references

- [Reference](https://songhaifan.github.io/visdelta/docs/api/)
- [Machine-readable page index](https://songhaifan.github.io/visdelta/llms.txt)
- [Complete current documentation](https://songhaifan.github.io/visdelta/llms-full.txt)

The repository's semantic constitution is docs/language-framework.md;
docs/reference.md records implemented behavior. Public entries include visdelta,
visdelta/core, visdelta/area, visdelta/bar, visdelta/line, visdelta/point,
visdelta/unit, visdelta/pie, visdelta/facet, visdelta/transition, visdelta/plugins,
visdelta/toolkit, visdelta/chart-style, visdelta/browser and visdelta/style.css.
Diagnostic API proposals are design documents, not available exports.


# VisDelta

> Declare two immutable chart states. VisDelta reports what changed and renders one seekable transition you can play, reverse or scrub.

Links below point to the Markdown source of each page. The HTML pages live under https://songhaifan.github.io/visdelta/docs/, and the complete documentation is a single file at https://songhaifan.github.io/visdelta/llms-full.txt.

# Docs


- **Introduction**
- [Overview](https://songhaifan.github.io/visdelta/llms.mdx/docs/content.md): Write a chart one chained call at a time. Every call is a new state, and VisDelta draws the change.
- [Installation](https://songhaifan.github.io/visdelta/llms.mdx/docs/installation/content.md): Install VisDelta from npm or load it directly in a browser. Then import a chart module, the transition runtime and the stylesheet.
- [Quick start](https://songhaifan.github.io/visdelta/llms.mdx/docs/quick-start/content.md): Your first transition in four steps.

- **Concepts**
- [Chart states](https://songhaifan.github.io/visdelta/llms.mdx/docs/concepts/chart-states/content.md): Immutable, chainable builders that describe one chart. Every visual mapping is explicit.
- [Data and transforms](https://songhaifan.github.io/visdelta/llms.mdx/docs/concepts/data-and-transforms/content.md): VisDelta expects tidy data. Declared transforms change which rows a state uses; they are not a data-cleaning API.
- [where, highlight and focus](https://songhaifan.github.io/visdelta/llms.mdx/docs/concepts/selection/content.md): Three selection words with three separate meanings. Membership, emphasis and camera.
- [State changes](https://songhaifan.github.io/visdelta/llms.mdx/docs/concepts/state-changes/content.md): delta() names what changed between two states, using seven kinds of change.
- [Identity](https://songhaifan.github.io/visdelta/llms.mdx/docs/concepts/identity/content.md): How VisDelta knows which mark is the same mark in both states.
- [Transitions](https://songhaifan.github.io/visdelta/llms.mdx/docs/concepts/transitions/content.md): How VisDelta gets from one state to the other, and why every frame is a real chart.
- [Progress](https://songhaifan.github.io/visdelta/llms.mdx/docs/concepts/progress/content.md): A transition is a function of one number. Play, pause and seek all move that number.
- [Design principles](https://songhaifan.github.io/visdelta/llms.mdx/docs/concepts/principles/content.md): The rules VisDelta is built on, and which a chart module must keep.

- **Charts**
- [Choosing a chart](https://songhaifan.github.io/visdelta/llms.mdx/docs/charts/content.md): Six peer chart modules, each answering one kind of question and owning its own transition rules.
- [Bar](https://songhaifan.github.io/visdelta/llms.mdx/docs/charts/bar/content.md): Categorical comparison on a shared quantitative baseline, with stacked, grouped and flipped layouts.
- [Line](https://songhaifan.github.io/visdelta/llms.mdx/docs/charts/line/content.md): Ordered trends with keyed observations inside the path and honest gaps by default.
- [Area](https://songhaifan.github.io/visdelta/llms.mdx/docs/charts/area/content.md): Magnitude and composition over an ordered dimension, with stacked layers, streamgraphs and direct labels.
- [Point](https://songhaifan.github.io/visdelta/llms.mdx/docs/charts/point/content.md): Scatterplots, dot plots, dumbbells and lollipops on compact Cartesian axes.
- [Unit](https://songhaifan.github.io/visdelta/llms.mdx/docs/charts/unit/content.md): Countable items as individually matched circles, in grid, force, unit-bar and beeswarm layouts.
- [Pie](https://songhaifan.github.io/visdelta/llms.mdx/docs/charts/pie/content.md): Nonnegative parts of one positive total, with keyed angular motion and direct transitions.
- [Small multiples](https://songhaifan.github.io/visdelta/llms.mdx/docs/charts/repeat/content.md): Partition any chart into panels with .repeat(), in one SVG with one transition controller.

- **Guides**
- [Start here for agents](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/agent-workflow/content.md): A verified entry point, observable API facts and a short workflow for building a correct VisDelta story.
- [Automatic behaviors](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/automatic-behaviors/content.md): What VisDelta derives automatically, what affects it and which controls exist in 0.4.2.
- [Copy a scroll story](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/scroll-template/content.md): A runnable single-file template with measured step positions, holds, replay, themes and an explicit iframe contract.
- [Author a downstream MDX story](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/mdx/content.md): Use native VisDelta states in a narrative application, with explicit ownership of progress and asynchronous chart creation.
- [Controlling playback](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/controlling-playback/content.md): Drive one transition from buttons, a slider, scroll position or your own timeline.
- [Multi-step stories](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/stories/content.md): Use sequence() to join several authored states into one seekable timeline.
- [Updating a chart in an app](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/updating-a-chart/content.md): Keep a chart on screen and animate it to each new state your application produces.
- [Use with React](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/react/content.md): One Chart component for static states, transitions and sequences.
- [JSON specs](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/json/content.md): Save and load ViewSpec declarations with the same runtime as builders and React.
- [Use without a bundler](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/cdn/content.md): Run VisDelta from one versioned ESM URL, or from a self-contained global script.
- [Styling and themes](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/styling/content.md): Structural chart styles, CSS token themes and dark mode. Style changes presentation, never meaning.
- [Visualization warnings](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/warnings/content.md): Advisory design checks that never change what renders.
- [Design comparisons](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/design-comparisons/content.md): Paired "Not ideal → Better" charts for common design choices, drawn live by VisDelta with its own advisory warnings and runnable code.
- [Custom chart types](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/custom-chart-types/content.md): Add an independent chart module through the plugin SDK, without changing the runtime.
- [Troubleshooting](https://songhaifan.github.io/visdelta/llms.mdx/docs/guides/troubleshooting/content.md): The errors VisDelta throws, what causes them and how to fix them.

- **Examples**
- [Playground](https://songhaifan.github.io/visdelta/playground/)
- [Gallery](https://songhaifan.github.io/visdelta/gallery/)

- **Reference**
- [API overview](https://songhaifan.github.io/visdelta/llms.mdx/docs/api/content.md): Entry points, what each exports, and where each part of the API is documented.
- [transition()](https://songhaifan.github.io/visdelta/llms.mdx/docs/api/transition/content.md): Create one seekable transition between two states of the same chart type.
- [sequence()](https://songhaifan.github.io/visdelta/llms.mdx/docs/api/sequence/content.md): Join several authored states into one seekable timeline of adjacent transitions.
- [Builders](https://songhaifan.github.io/visdelta/llms.mdx/docs/api/builders/content.md): Signatures of every builder method. Behaviour is documented on the concept and chart pages linked from each section.
- [Core](https://songhaifan.github.io/visdelta/llms.mdx/docs/api/core/content.md): DOM-free inspection. delta(), declaration edits and planning, identity, lineage and camera helpers.
- [Types](https://songhaifan.github.io/visdelta/llms.mdx/docs/api/types/content.md): The public types you are most likely to read or annotate, generated from the library's TypeScript source.