@motionscript/charts 0.0.0-stage → 0.1.0-alpha.10

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# @motionscript/charts
+
+## 0.1.0-alpha.10
+
+## 0.1.0-alpha.9
+
+## 0.1.0-alpha.8
+
+## 0.1.0-alpha.7
+
+### Minor Changes
+
+- 737f7d0: What was left of the class authoring system is gone. Each piece existed to write or extend a node class, and a node type is a component now; no built-in, kit or host used them.
+
+  Removed from `@motionscript/core`:
+
+  - the registration functions `property`, `node`, `command` and `withdraw`, and the thirteen typed property helpers (`fillProperty`, `strokeProperty`, `shadowProperty`, `effectsProperty`, `colorProperty`, `cornerRadiusProperty`, `cornerStyleProperty`, `pathProperty`, `insetsProperty`, `alignmentProperty`, `vector2Property`, `sizeProperty`, `textProperty`) with their `AttributePropOptions` type. A component declares its entries with `Types`. `getPropertyMeta`, `getNodeDescriptor`, `getCommandMeta` and the metadata types stay;
+  - `TextSelection`, `TextSelectionHost`, `TextSelectionProps`, `TextRange`, `SelectionOverrides` and `normalizeRanges`: the component `Text` has no selection API, so nothing could make one. Style a range with `runs`;
+  - `AudioScope` and the `declareAudio` hook on `Node`: sound plays from commands (`timeline.sound`). `busPathOf` and `busPathTo` take a function answering a node's span instead of an `AudioScope`;
+  - the `Node.tick` hook and the `Node2D` hooks `beforeRender`, `afterRender`, `renderStroke`, `clipPathSelf`, `resolveSizeInput` and `constraints`, which only a subclass could reach;
+  - `NodeTypeRecord.withdrawn` and `CommandMeta.withdrawn`. `PropertyMeta.withdrawn` stays, deprecated: nothing sets it.
+
+  Removed from `@motionscript/core/component`, and so from `@motionscript/sdk/component` and `@motionscript/charts/kit`, which re-export it: the seekable composition `at`, `hold`, `sequence` and `together`, with the `Seekable` and `Placed` types. A component command returns timeline pieces.
+
+  Removed from `@motionscript/sdk`: `TextSelection`, `TextSelectionProps`, `TextRange`, `SelectionOverrides`, `AudioScope` and `AudioClip`.
+
+## 0.1.0-alpha.6
+
+### Minor Changes
+
+- 163b708: Node types are components: one spec object handed to `component2d`, `component3d` or `componentAudio`, with no classes, decorators or JSX.
+
+  - **Writing a node type.** A component is one object literal: `key`, `state` (literals and `Types`), `defaults`, `commands`, `children`, `allowedChildren`/`allowedParents`, `provide`, `load`, and its tree's own fields (`measure`, `layout`, `render` for 2D). Behaviour comes from modules you spread in and call: `Paint`, `Flow`, `Shapes`, `Typeface`, `TextLayout`, `Aim`, `Material`, `View3D`. ADR 0007 and the custom-node docs cover it.
+  - **Building nodes in code** uses calls: `Rect({ fill: 'tomato', children: [Text({ text: 'Hi' })] })`, or `new Rect({...})` for the node itself.
+  - **Every built-in and every kit node is a component**, under the same document key. Code that tested `instanceof` a class now uses the component's `.is`, or `instanceof X.node`. Changed members:
+    - `SurfacePlot3d.valueAt` and `FunctionPlot.valueAt` are now the functions `surfaceValueAt` and `curveValue`.
+    - A system's `coordinates` is replaced by `planeMap`/`axesMap`/`systemMap`.
+    - `PieChart.isSelected` is replaced by `isSliceSelected`.
+    - `ItemGrid` is a kit module (`ItemGrid.isGrid`, `ItemGrid.define`), not a base class.
+  - **The sdk no longer exports the class surface:**
+    - the decorators: `node`, `property` and every `*Property`, `command`, `withdraw`, `driveCommand`;
+    - the authoring bases: `PaintNode`, `ShapeNode`, `TextBase`, `Mesh3DBase`, `Canvas3DBase` and the `*Base` geometry classes;
+    - `asCommand`, `compose`, `drive` and `declarePaints` from `@motionscript/sdk/component`;
+    - the `jsx-runtime` and `jsx-dev-runtime` subpaths.
+    - `Node`, `Node2D`, `Node3D` and `NodeAudio` remain as types.
+  - **Editor metadata leaves the engine.** The kits no longer declare `parentKey`, `forkable`, `layout`, `seed`, `within`, `beside` or `closed`; a host keeps those in its own configs. `describe()` now reports `holds`, the trees a type takes children from, and the placement checks use it, so a 2D viewport of your own that takes 3D children places them.
+  - A command called from code with no argument runs, and a refused child is told what its parent takes (`allowedChildren`) or where it goes (`allowedParents`).
+
+## 0.1.0-alpha.5
+
+### Patch Changes
+
+- da6f97a: Every package ships a `NOTICE`, and a browser build lists what it bundles.
+
+  - Each tarball carries the repository `NOTICE`: the copyright line and the MIT attributions for the noise functions in `skia-render`'s fractal-noise fill (David Hoskins' "Hash without Sine", Inigo Quilez's 2D simplex noise).
+  - `@motionscript/canvaskit` ships `THIRD_PARTY_NOTICES.txt` with the licences of the libraries compiled into the binary: FreeType, HarfBuzz, ICU 74, zlib, libpng, Brotli, WOFF2, Emscripten and musl.
+  - `dist/browser/manifest.json` gains `thirdParty`, the packages the browser build bundled (`name`, `version`, `license`), and their licence and NOTICE files are written to `dist/browser/THIRD_PARTY_LICENSES.txt`. `@motionscript/browser` bundles mediabunny (MPL-2.0, unmodified; source at https://github.com/Vanilagy/mediabunny), esbuild-wasm and three; `@motionscript/math` bundles MathJax.
+
+- 1778355: The published packages carry what a user needs and say what they are.
+
+  - `@motionscript/code` no longer ships `dist/tests/diff.bench.*`, and `@motionscript/math` no longer ships `dist/tests/harness.*` or `mathjax.setup.*`: test helpers under a `tests` folder are left out of every package's build.
+  - `@motionscript/sdk`'s description no longer repeats core's, and `@motionscript/math`'s names the coordinate systems, plots, 3D graphs and network graphs it has as well as formulas.
+  - The READMEs of `@motionscript/canvaskit`, `@motionscript/charts`, `@motionscript/geo`, `@motionscript/grids`, `@motionscript/skia-render` and `@motionscript/geography` say what to install, and `@motionscript/sdk`'s example now opens the document in an engine and plays it. Links between packages point at the repository, so they work on npm.
+
+## 0.1.0-alpha.4
+
+### Patch Changes
+
+- d8ae489: A chart legend's entries now open and close from their own width. A series that started hidden stayed zero-width for the whole `showSeries` move and snapped open at the end, and a `hideSeries` that was seeked to straight away (a scrub or an export) collapsed at zero width, while the same hide played from before shrank from the measured width. An entry's width is now measured from its caption and swatch at any reveal, so playing and seeking give the same frame, and a fully shown entry is laid out exactly as before.
+- 96d49af: A pie ring's wedge outline and shadow can be painted with an image. `PieRing` declared each slice fill and the leader stroke only, so an image in `ring.stroke` or in a `ring.shadow` fill was never loaded and the renderer failed on it. Both are now declared with the rest of the ring's paints.
+- ad28707: Component kit fixes.
+
+  - Charts: a bar chart maps its columns across the plot panel as laid out (and takes the line chart's top headroom), so a column ends on its marker's grid line. A pie chart's wedges, labels and legend follow `data` and the palette once they are set. A restated value-axis or y/x-axis `range` or `ticks` in `to()` rescales continuously from the axis as drawn, instead of cutting at the midpoint. Without a legend (or without series) the entrance keeps that beat's share, so the call-out and legend land where the slot lays them out. A constant line series gets a scale with width, a `NaN` or infinite cell reads as 0, and tick captions gain decimals when the step is finer than 0.1.
+  - Code: the compiled highlighter is cached per style object, so two styles sharing a name no longer colour alike. A `CodeRanges` chain serialises as its ranges, so a stored `highlight` target selects what it did before it was saved.
+  - LaTeX: seeking from inside a morph to a time before it restores the source formula instead of leaving the last morph frame.
+  - Geo: custom border rings are wound for d3, so a GeoJSON counter-clockwise ring draws as the small region it encloses; a great-circle path between antipodal points runs over the north pole instead of wherever rounding lands.
+  - Audio: bottom-aligned waveform bars stand on the floor of the box instead of hanging from the top.
+  - `Code` and `Latex` take an optional props bag, so `new Registry({ nodes: NODES })` and `createBrowserEngine({ nodes: NODES })` type-check without a cast.
+
+- 75b6908: Fixes in document validation, the clip timeline and the expression language.
+
+  - `validateDocument` reports tree and command issues at the row's place in the document. A malformed row earlier in `nodes` or `commands` used to shift every later path by one.
+  - The parts a command writes on a node's own children (a chart's ring, legend or bars) are restored to what they were built with before the command starts and after a seek back, so a frame no longer depends on how the playhead arrived. The chart legend's per-series reveal is now one slot, so the timeline can restore it.
+  - A child that enters before its parent is baselined once the parent has mounted it, so it keeps what it inherits (a text style, for example) instead of the pre-attach values.
+  - A row that an animated `removeChildAt` takes out of its parent is back in place before the command starts, in a fresh build and after a scrub alike.
+  - An unknown `targetId` is one error naming it for every node-scoped command (`to`, `set`, `save`, `moveTo`, component commands). Global-table commands used to be skipped silently, and named ones blamed the node type.
+  - Instant `removeChildAt` detaches the removed subtree, as `remove()` and `clear()` do.
+  - Expressions: `toString`, `constructor`, `__proto__` and the other `Object.prototype` names are unknown functions and constants rather than a `TypeError`, in the shared parser and the plot kit (and `alignmentOps.resolve` rejects them as `isKey` does). A blank string operand is `NaN`, not `0`. `step` and `smoothstep` propagate `NaN`, and `smoothstep` with equal edges is a step at the edge. Arity errors say "1 argument". `renameRefs` hands its callback the trimmed reference name.
+
+## 0.1.0-alpha.3
+
+### Patch Changes
+
+- 6697bb4: Every chart command runs from a document.
+
+  - Thirteen of the twenty chart commands returned a composition of seekable parts rather than a `Command`, so a document naming one failed to compile with `TypeError: made.at is not a function`: `enter` on all three charts, `showSeries`, `hideSeries` and `spotlightSeries` on the line and bar charts, and `selectSlice`, `deselectSlice`, `selectOnlySlice` and `clearSelection` on the pie. So did `zoomTo` with a region naming neither axis, and `resetZoom` before any zoom. Each now returns a `Command` that lasts the duration it was given. A line or bar `enter` without a legend, whose beats end before that, holds its last frame for the rest of it.
+  - `@motionscript/sdk/component` gains `asCommand(part, duration?)`, which makes a composition built with `at`, `sequence`, `together`, `hold`, `compose` or `drive` the `Command` a `@command()` method returns. A part that ends before `duration` holds its last frame, and one that runs longer is played faster, so the command always ends where the part does.
+  - A line chart's first `zoomTo` from an auto axis tweens. It started from the unset range and ticks, which the axis tween steps at the midpoint, so the first zoom cut halfway through and only later ones moved. A zoom, and `resetZoom`, now start from the range and ticks the axis draws.
+
+## 0.1.0-alpha.2
+
+## 0.1.0-alpha.1
+
+### Minor Changes
+
+- 59cecba: Build on `@motionscript/sdk` instead of `@motionscript/core`. The peer dependency is now `@motionscript/sdk`, every import goes through it (and `@motionscript/sdk/component` for the component machinery), and the browser build leaves `@motionscript/sdk` an import, so an import map names it once. A component copied with `ms add` imports the SDK too, and its registry item depends on `@motionscript/sdk` rather than `@motionscript/core`. `@motionscript/charts/kit` re-exports `@motionscript/sdk/component` where it re-exported `@motionscript/core/component`.
+
+## 0.1.0-alpha.0
+
+Initial release.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,49 @@
+Motionscript
+Copyright 2026 Motionscript LLC
+
+This product includes the third-party code below, each part under the MIT
+License reproduced at the end of this file.
+
+- packages/renderer/crates/renderer/src/shaders/prim.wgsl (`fn_hash2`):
+  "Hash without Sine" by David Hoskins (https://www.shadertoy.com/view/4djSRW).
+  Copyright (c) 2014 David Hoskins.
+
+- packages/renderer/crates/renderer/src/shaders/prim.wgsl (`simplex_noise`): "Noise - simplex - 2D" by Inigo Quilez
+  (https://www.shadertoy.com/view/Msf3WH). Copyright (c) 2013 Inigo Quilez.
+
+- packages/renderer/crates/render3d (in @motionscript/renderer's WebAssembly):
+  its shaders (src/shaders/mesh.wgsl) port three.js r185's mesh programs and
+  src/geometry.rs its primitive generators (https://threejs.org).
+  Copyright (c) 2010-2026 three.js authors.
+
+@motionscript/renderer's WebAssembly (dist/ms_renderer_bg.wasm) compiles in
+Rust crates under MIT, Apache-2.0, Zlib and Unicode-3.0 terms (wgpu, naga,
+harfrust, read-fonts, kurbo, wasm-bindgen and others); their notices are in
+packages/renderer/THIRD_PARTY_NOTICES.txt.
+
+MP3 export loads @mediabunny/mp3-encoder (MPL-2.0), a WebAssembly build of
+the LAME MP3 encoder (LGPL, https://lame.sourceforge.io), on first use.
+
+The browser builds under dist/browser/ bundle each package's npm dependencies;
+dist/browser/THIRD_PARTY_LICENSES.txt in each package lists them with their
+licences.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,99 @@
-# Temporary Holding Version
+# @motionscript/charts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+Animated data charts for [Motion Script](https://motionscript.dev): a line chart,
+a bar chart and a pie chart, built from one shared kit (plot panel, value axis,
+legend, number formatting, theme resolution). Written against
+[`@motionscript/sdk`](https://github.com/motionscript-dev/motionscript/tree/main/packages/sdk), which it takes as a peer dependency.
+
+```ts
+import { NODES } from '@motionscript/charts';
+
+export const nodes = NODES; // [LineChart, BarChart, PieChart]
+```
+
+Importing registers nothing; the host hands `NODES` to the engine (see
+[`packages/components/CLAUDE.md`](https://github.com/motionscript-dev/motionscript/blob/main/packages/components/CLAUDE.md) for the registration and import rules every kit shares).
+
+## Install
+
+```bash
+npm install @motionscript/charts @motionscript/sdk
+```
+
+## Exports
+
+| Path | Source | What |
+|---|---|---|
+| `@motionscript/charts` | `src/index.ts` | the three chart barrels, `src/engine.ts` and `NODES` |
+| `@motionscript/charts/kit` | `src/engine.ts` | the shared kit (`src/kit/*`) and all of `@motionscript/sdk/component` |
+
+Each chart folder (`line-chart/`, `bar-chart/`, `pie-chart/`) has an `index.ts`
+barrel with the node, its parts, its theme (`DEFAULT_*_THEME`, `resolve*Theme`,
+`lerp*Theme`) and its pure helpers (`resolveXScale`, `barSpans`, `pieArcs`, ...).
+The charts and their parts (`ChartLine`, `ChartBars`, `PieRing`, `VerticalAxis`, ...)
+are components (`component2d`); only the charts are registered node types, so a
+document cannot name a part. A chart tells a host its key, entries and commands;
+where it is shelved and the box it is seeded at are the host's to keep. `lineChartDomains` and `barChartDomain` give the axes as drawn, and
+`isSliceSelected` whether a pie slice is out.
+
+## Nodes
+
+| Key | Made for (w x h) | Data props | Commands |
+|---|---|---|---|
+| `lineChart` | 760 x 460 | `data`, `xField`, `series`, `xAxis`, `yAxis`, `region` | `enter`, `spotlightRegion`, `clearRegion`, `zoomTo`, `resetZoom`, `showSeries`/`hideSeries`/`spotlightSeries` |
+| `barChart` | 760 x 460 | `data`, `categoryField`, `series`, `valueAxis`, `stacked` | `enter`, `showSeries`/`hideSeries`/`spotlightSeries`, `spotlightCategory`, `clearCategory` |
+| `pieChart` | 680 x 480 | `data`, `categoryField`, `valueField` | `enter`, `revealCenter`, `selectSlice`/`deselectSlice`/`selectOnlySlice`/`clearSelection` |
+
+Every command takes the duration its row (or call) gives, and eases out unless
+given an easing. Arguments: `seriesIndex`, `sliceIndex`, `categoryIndex` (each 0
+when left out), and for `spotlightRegion` and `zoomTo` a `region` of
+`{ x?: [min, max], y?: [min, max] }`.
+
+## Rules worth knowing
+
+- **The kit stays an import.** A copy of `line-chart` takes only `line-chart/*` and
+  rewrites its kit imports to `@motionscript/charts` (`registry.json`): a second
+  copy of `VerticalAxis` would render as nothing, with no error.
+- **Resting state is the finished chart.** `enter` arms every part on its first
+  frame: every piece of a component command is built run to its end, and a beat
+  ahead of the playhead writes nothing, so the first frame writes what each later
+  beat moves from. `duration` is the whole entrance: a beat with nothing to do (no
+  legend, no series) holds its share.
+- **A part's command has no duration of its own.** The charts pass every part the
+  duration and easing it moves with; called directly, a part's command takes the
+  duration it is given, and a part's own frames ease out unless given an easing.
+- **Some props are read once, at construction**: the series list (count, labels,
+  `enabled`), `showLegend`, `showValues`, `showCenter`, axis captions, text styles and
+  paddings, the bar chart's category captions, the pie's label and legend-row counts,
+  `labelMode`, `labelPlacement`, `gap`, `centerLabel`, `centerCaption`. A `set` or `to`
+  of them changes nothing; a document edit re-instantiates the node, which does
+  refresh them. `data`, scales, ticks, theme paints, `region`, `stacked`, `weights`
+  and `pops` are live.
+- **Non-finite cells plot as 0.** `num()` returns a cell only when it is a finite
+  number, so a numeric string, `NaN`, `Infinity` and a missing cell all read 0.
+- **x units on the line chart.** `xAxis.range`, `xAxis.ticks` and a region's `x`
+  are in the x scale's own units: the number (numeric column), UTC epoch
+  milliseconds (time column) or the row index (ordinal column), chosen from the
+  column by `resolveXScale` (dates via `parseInstant`).
+- **`zoomTo` remembers the resting domain once** (`home`, a private entry its
+  frames write) and `resetZoom`'s frames clear it, so the pair is order dependent
+  and a seek back before a zoom forgets it again: a `resetZoom` with no earlier
+  `zoomTo`, and a `zoomTo` naming neither axis, write nothing for their duration.
+  A zoom keeps the tick count so each marker slides.
+- **A `to` of an axis `range` or `ticks` tweens from the domain as drawn**
+  (`lerpAxisEntry`): an auto side is held mid-move as an `AxisDomainBlend`, which
+  the chart settles against its data, so a rescale from an auto axis is continuous.
+  A restated range without ticks spreads explicit ticks across it; one side of an
+  auto axis restated alone leaves the other to the data.
+- **Pie angles** are radians clockwise from 12 o'clock; `startAngle` is degrees.
+
+## Development
+
+```bash
+pnpm --filter @motionscript/charts build
+pnpm --filter @motionscript/charts test
+```
+
+Tests sit beside the code (`*.test.ts`); `src/document.test.ts` runs the commands
+through a compiled document, and `src/tests/harness.ts` supplies the attach, measure
+and record helpers.