@vanduo-oss/vd3-cbun 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `@vanduo-oss/vd3-cbun` are documented here. This file
+tracks the PACKAGE only — never docs-site content. Per-component VERSION
+constants are listed alongside each bundle release.
+
+## 1.0.0 — 2026-07-14
+
+First public release of `@vanduo-oss/vd3-cbun` — the Vanduo **components bundle**
+for the vd3 line: Vue3-only charts, flowchart, hex-grid, and music-player
+consolidated into ONE package with tree-shakeable subpath exports, replacing the
+four old-line per-repo publishes (`@vanduo-oss/charts`, `@vanduo-oss/flowchart`,
+`@vanduo-oss/hex-grid`, `@vanduo-oss/music-player`). Sole peer: `vue >=3.3` — no
+IIFE runtime and no `./vue` subpaths (the Vue bindings ARE the subpath exports;
+framework-agnostic cores are re-exported alongside them). The bullets below roll
+up the development history that makes up 1.0.0 (scaffold → consolidation →
+tests). Publish prep (`cbun-publish-prep`) set the first public version, added
+`publishConfig.access: "public"` and a build-before-publish `release` script
+(the hardened `.npmrc ignore-scripts=true` skips `prepack` at publish time, so
+the release must build explicitly), relaxed `engines.node` `>=24` → `>=20.19.0`
+for LTS consumers, and finished the README/SKILL to the house standard
+(`Install`, `Theming`, `Security`).
+
+Component versions in this release: **charts 1.0.0, flowchart 1.2.0, hex-grid
+1.0.0, music-player 1.0.0** — the bundle's own semver is decoupled from the
+per-component `VERSION` constants (tracked in `component-versions.json` and
+asserted against the exported `VD3_CBUN_VERSIONS` map). `VD_FLOWCHART_VERSION`
+continues the old-line `1.2.0` lineage because it is serialized into user
+documents via `toJSON().version`; resetting it would mislabel documents saved by
+the old line.
+
+- Component consolidation (`cbun-consolidation`) + test suites (`cbun-tests`):
+  - All four components ported Vue3-only from their standalone repos, vanilla
+    auto-init/window-global layers excised: `./charts`, `./flowchart`,
+    `./hex-grid` (+ `./hex-grid/hex-math`), `./music-player`, with per-component
+    `./…/css` where applicable (hex-grid is canvas-rendered, no CSS).
+  - Multi-entry esbuild build (esm+cjs per subpath, `vue` external) with
+    post-build guards: all 20 export targets verified on disk, subpath
+    tree-shake isolation, vue-externality.
+  - Newly authored hex-grid core type declarations (`index.d.ts`,
+    `hex-math.d.ts`); music-player types moved into `src/music-player/`.
+  - Tests: 15 vitest files / 261 tests (core logic + Vue wrapper mounts),
+    tsc type-test harness (`test:types`), Playwright real-canvas smoke
+    (`test:e2e`, charts + hex-grid).
+  - Music-player keeps DOM CustomEvents (`musicplayer:*`) in v1 by design.
+- Repo scaffold (`init-cbun-scaffold`): package metadata with the full subpath
+  exports contract, hardened pnpm install policy, Phase-0 esbuild harness (root
+  entry only), `component-versions.json` manifest (charts 1.0.0, flowchart
+  1.2.0, hex-grid 1.0.0, music-player 1.0.0), version-consistency smoke test,
+  CI, and doc stubs.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Vanduo Open Source Foundation
+
+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

@@ -0,0 +1,160 @@
+# @vanduo-oss/vd3-cbun
+
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+The Vanduo **components bundle** for the vd3 line: Vue3-only charts, flowchart,
+hex-grid, and music-player consolidated into ONE package with tree-shakeable
+subpath exports. It replaces the four per-repo publishes (`@vanduo-oss/charts`,
+`@vanduo-oss/flowchart`, `@vanduo-oss/hex-grid`, `@vanduo-oss/music-player`)
+of the old line.
+
+**Status: 1.0.0 — first public release.** All four component families are
+consolidated Vue3-only (vanilla auto-init/window-global layers excised), each on
+its own tree-shakeable subpath, with the esbuild metafile isolation guard in
+place.
+
+## Install
+
+```sh
+pnpm add @vanduo-oss/vd3-cbun
+```
+
+`vue >=3.3.0` is a **required** peer dependency (the only runtime dep) — install
+it alongside if your project does not already depend on Vue. For correct
+theming, also provide the Vanduo `--vd-*` design tokens (see
+[Theming](#theming)).
+
+## Subpath-import model
+
+Each component lives on its own subpath — importing one never pulls in another:
+
+```js
+import { VdChart } from '@vanduo-oss/vd3-cbun/charts';
+import '@vanduo-oss/vd3-cbun/charts/css';
+
+import { VdFlowchart } from '@vanduo-oss/vd3-cbun/flowchart';
+import '@vanduo-oss/vd3-cbun/flowchart/css';
+
+import { VdHexGrid } from '@vanduo-oss/vd3-cbun/hex-grid';
+import { hexToPixel } from '@vanduo-oss/vd3-cbun/hex-grid/hex-math';
+
+import { VdMusicPlayer } from '@vanduo-oss/vd3-cbun/music-player';
+import '@vanduo-oss/vd3-cbun/music-player/css';
+```
+
+The root import exposes only the per-component VERSION-constants map:
+
+```js
+import { VD3_CBUN_VERSIONS } from '@vanduo-oss/vd3-cbun';
+```
+
+Each subpath entry (`dist/<component>/index.js`) re-exports **both** the Vue
+component and its framework-agnostic core (the core aliased with a `Core`
+suffix where the names collide — `VdFlowchartCore`, `VdHexGridCore`). Isolation
+is not a convention but a build guard: `scripts/build.js` bundles every entry
+separately with `vue` external, emits an esbuild metafile (`dist/meta.json`),
+and **fails the build** if any component entry's inputs reach outside its own
+`src/<component>/` directory or if anything but `vue` is externalized. The
+package declares `sideEffects: ["**/*.css"]`, so bundlers may drop any unused
+JS export while preserving the CSS side-effect imports. Inspect `dist/meta.json`
+to confirm tree-shaking downstream.
+
+Notes:
+
+- `vue >=3.3.0` is a **required** peer dependency (the only runtime dep; never
+  bundled — it stays external in both the esm and cjs outputs).
+- Named exports only — no default exports on any subpath.
+- No IIFE builds and no `./vue` subpaths — the Vue bindings ARE the subpath
+  exports; framework-agnostic cores stay exported alongside them.
+- hex-grid ships no CSS (canvas-based; it reads `--vd-*` tokens via
+  `getComputedStyle`).
+
+## Per-component version policy
+
+The bundle's own semver (`package.json` version) is decoupled from the
+components inside it. Each component carries a VERSION constant tracked in
+`component-versions.json` at the repo root and asserted in tests against the
+exported `VD3_CBUN_VERSIONS` map. At bundle launch, charts, hex-grid, and
+music-player reset to `1.0.0`; **flowchart continues its old-line lineage at
+`1.2.0`** because `VD_FLOWCHART_VERSION` is load-bearing — it is serialized
+into user documents via `toJSON().version`.
+
+## Theming
+
+All four components render against Vanduo's `--vd-*` design tokens — the same
+tokens `@vanduo-oss/vd3` defines. charts, flowchart, and hex-grid carry built-in
+fallbacks and degrade gracefully without them; **music-player expects the tokens**
+and renders with unset colors/backgrounds if none are provided. For correct
+theming, supply the tokens on an ancestor element — the simplest way is to ship
+the vd3 stylesheet:
+
+```js
+import '@vanduo-oss/vd3/css'; // full tokens + component CSS
+// …or the tokens-only layer:
+import '@vanduo-oss/vd3/css/core';
+```
+
+The tokens consumed include `--vd-bg-primary`, `--vd-bg-secondary`,
+`--vd-text-primary`, `--vd-text-muted`, `--vd-border-color`, and
+`--vd-color-primary`. hex-grid reads them off the host element via
+`getComputedStyle`; the CSS-based components resolve them through `var(--vd-*)`.
+(vd3 is not a package dependency of the bundle — any provider of the `--vd-*`
+tokens works — but it is the canonical source.)
+
+## Security
+
+- **One runtime dependency** — the `vue >=3.3.0` peer; nothing else is bundled
+  or required (`vue` stays external in every esm/cjs output, and the build fails
+  if any other module is externalized or any `node_modules` input is bundled).
+- **Hardened `.npmrc`:** `ignore-scripts`, `minimum-release-age`, `save-exact`,
+  `strict-peer-dependencies`, `trust-policy=no-downgrade`,
+  `block-exotic-subdeps`, and an explicit `registry`.
+- **MIT** licensed ([LICENSE](./LICENSE)); the bundle vendors no third-party
+  runtime code.
+
+## Exports
+
+| Export                                    | Contents                                                     |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| `@vanduo-oss/vd3-cbun`                    | Root — the `VD3_CBUN_VERSIONS` per-component version map      |
+| `@vanduo-oss/vd3-cbun/charts`             | `VdChart` + typed chart wrappers, factories, scales, `resolveTheme` |
+| `@vanduo-oss/vd3-cbun/charts/css`         | Charts stylesheet (`dist/charts/vd3-charts.css`)             |
+| `@vanduo-oss/vd3-cbun/flowchart`          | `VdFlowchart` + `VdFlowchartCore`, `computeLayout`, `FLOWCHART_*` |
+| `@vanduo-oss/vd3-cbun/flowchart/css`      | Flowchart stylesheet (`dist/flowchart/vd3-flowchart.css`)    |
+| `@vanduo-oss/vd3-cbun/hex-grid`           | `VdHexGrid` + `VdHexGridCore`, `VD_HEX_VERSION`              |
+| `@vanduo-oss/vd3-cbun/hex-grid/hex-math`  | Pure coordinate/terrain math (`hexToPixel`, `TerrainType`, …) |
+| `@vanduo-oss/vd3-cbun/music-player`       | `VdMusicPlayer` + `MusicPlayer` core                         |
+| `@vanduo-oss/vd3-cbun/music-player/css`   | Music-player stylesheet (`dist/music-player/vd3-music-player.css`) |
+
+## Development
+
+```sh
+pnpm install
+pnpm lint          # eslint
+pnpm format:check  # prettier
+pnpm test          # vitest unit/wrapper suites (jsdom + node)
+pnpm build         # esbuild harness → dist/
+pnpm test:types    # tsc --noEmit over tests/types (needs dist/ — run build first)
+pnpm test:e2e      # Playwright canvas smoke, Chromium (needs dist/ — run build first)
+```
+
+`test:types` and `test:e2e` both consume the built `dist/` output, so **run
+`pnpm build` first** (CI orders them after the build step). The type harness
+type-checks the shipped declarations by resolving the package's own `exports`
+map (self-reference → `dist/<component>/*.d.ts`); the Playwright fixtures
+(`tests/e2e/fixtures/*.html`) import the built ESM entries directly and are
+served over a dependency-free `python3 -m http.server` (the `vue` external is
+resolved to the locally installed browser build via an import map). Chromium
+must be installed once: `pnpm exec playwright install chromium`.
+
+The published package declares a consumer-friendly `engines.node >=20.19.0`; the
+dev/CI toolchain pins Node 24 via `packageManager` + `.github/workflows/ci.yml`.
+
+## Documentation
+
+- Agent / LLM reference — [SKILL.md](./SKILL.md)
+- Changelog — [CHANGELOG.md](./CHANGELOG.md)
+
+## License
+
+[MIT](./LICENSE) © Vanduo Open Source Foundation

package/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: vanduo-vd3-cbun
+description: Use when adding Vanduo vd3 components with @vanduo-oss/vd3-cbun — the Vue 3 components bundle (charts, flowchart, hex-grid, music-player) with tree-shakeable subpath exports. Covers install, per-subpath imports, CSS, theming, and per-component versioning.
+---
+
+# @vanduo-oss/vd3-cbun
+
+One bundle, four Vue 3 components, each on its own tree-shakeable subpath
+(`./charts`, `./flowchart`, `./hex-grid`, `./music-player`). `vue >=3.3.0` is a
+required peer. The root import exposes only `VD3_CBUN_VERSIONS` — the per-
+component VERSION map. Every subpath re-exports the Vue wrapper AND the
+framework-agnostic core alongside it (the core aliased with a `Core` suffix
+where the names collide).
+
+## Install
+
+```sh
+pnpm add @vanduo-oss/vd3-cbun
+```
+
+`vue >=3.3.0` is a required peer. Import each component from its own subpath
+(below); nothing registers globally. For correct theming, provide the Vanduo
+`--vd-*` design tokens (see [Theming](#theming) at the end).
+
+## Charts
+
+```js
+import {
+  VdChart, // generic; pick the type via the `type` prop
+  VdBarChart,
+  VdLineChart,
+  VdAreaChart,
+  VdScatterChart,
+  VdDonutChart,
+  VdPieChart,
+} from '@vanduo-oss/vd3-cbun/charts';
+import '@vanduo-oss/vd3-cbun/charts/css';
+```
+
+The same subpath re-exports the framework-agnostic core: the chart factories
+(`BarChart`, `LineChart`, `AreaChart`, `ScatterChart`, `DonutChart`, `PieChart`),
+the scales (`scaleLinear`, `scaleTime`, `scaleBand`, `scalePoint`,
+`scaleOrdinal`), accessor/tick helpers (`createAccessor`, `ticks`,
+`niceDomain`), the path builders (`linePath`, `areaPath`, `arcPath`), and
+`resolveTheme`. No name collision, so the core factories keep their own names.
+CSS ships at `@vanduo-oss/vd3-cbun/charts/css`. `VD_CHARTS_VERSION` is `1.0.0`.
+
+## Flowchart
+
+```js
+import { VdFlowchart, VdFlowchartCore } from '@vanduo-oss/vd3-cbun/flowchart';
+import '@vanduo-oss/vd3-cbun/flowchart/css';
+```
+
+`VdFlowchart` is the Vue 3 wrapper; the framework-agnostic editor core is the
+same class name upstream, so it is re-exported as `VdFlowchartCore`. The subpath
+also re-exports `computeLayout`, `LAYOUT_MODES`, and the `FLOWCHART_*` constant
+tables (`FLOWCHART_NODE_TYPES`, `FLOWCHART_PORTS`, `FLOWCHART_EDGE_MARKERS`,
+`FLOWCHART_EDGE_ROUTES`) plus `VD_FLOWCHART_VERSION`. CSS ships at
+`@vanduo-oss/vd3-cbun/flowchart/css`. `VD_FLOWCHART_VERSION` is `1.2.0` — it
+continues the old-line lineage (never reset to `1.0.0`) because the value is
+serialized into user documents via `toJSON().version`; resetting it would
+mislabel documents saved by the old line.
+
+## Hex-grid
+
+```js
+import { VdHexGrid, VdHexGridCore } from '@vanduo-oss/vd3-cbun/hex-grid';
+import {
+  hexToPixel,
+  pixelToHex,
+  axialRound,
+  getHexCorners,
+  getAdjacentHexes,
+  hexDistance,
+  TerrainType,
+} from '@vanduo-oss/vd3-cbun/hex-grid/hex-math';
+```
+
+`VdHexGrid` is the Vue wrapper; the framework-agnostic canvas core class shares
+the name upstream, so it is re-exported as `VdHexGridCore` alongside
+`VD_HEX_VERSION`. The pure math module lives on its own `./hex-grid/hex-math`
+subpath (coordinate transforms, rotation, distance, plus the terrain tables:
+`TerrainType`, `TERRAIN_COLORS`, `TERRAIN_YIELDS`, `TERRAIN_MOVEMENT_COSTS`,
+and the `isPassable` / `getMovementCost` / `getTerrainYields` / `getTerrainColor`
+helpers). Hex-grid ships **no CSS** — it renders to a canvas and reads `--vd-*`
+theme tokens off the host element via `getComputedStyle`. `VD_HEX_VERSION` is
+`1.0.0`.
+
+## Music-player
+
+```js
+import { VdMusicPlayer, MusicPlayer } from '@vanduo-oss/vd3-cbun/music-player';
+import '@vanduo-oss/vd3-cbun/music-player/css';
+```
+
+`VdMusicPlayer` is the Vue 3 wrapper; `MusicPlayer` is the framework-agnostic
+core (no name collision, so it keeps its own name) re-exported alongside
+`VD_MUSIC_PLAYER_VERSION`. The core still dispatches its v1 DOM `CustomEvent`s
+(`musicplayer:play`, `musicplayer:pause`, `musicplayer:trackchange`,
+`musicplayer:volumechange`, `musicplayer:repeatchange`, `musicplayer:ended`,
+`musicplayer:detach`, `musicplayer:attach`, `musicplayer:minimize`,
+`musicplayer:expand`); the wrapper re-emits each as a Vue event (`@play`,
+`@trackchange`, …, plus `@ready`) carrying `event.detail`. CSS ships at
+`@vanduo-oss/vd3-cbun/music-player/css`. `VD_MUSIC_PLAYER_VERSION` is `1.0.0`.
+
+## Theming
+
+All four components render against Vanduo's `--vd-*` design tokens — the same
+tokens `@vanduo-oss/vd3` defines. charts, flowchart, and hex-grid ship built-in
+fallbacks and degrade gracefully without them; **music-player expects the tokens**
+and renders with unset colors/backgrounds if none are present. Provide them on an
+ancestor element — simplest is to import the vd3 stylesheet (`@vanduo-oss/vd3/css`,
+or the tokens-only `@vanduo-oss/vd3/css/core`). Tokens consumed include
+`--vd-bg-primary`, `--vd-bg-secondary`, `--vd-text-primary`, `--vd-text-muted`,
+`--vd-border-color`, and `--vd-color-primary`. vd3 is **not** a package dependency
+of the bundle — any provider of the `--vd-*` tokens works; vd3 is just the
+canonical source. hex-grid reads the tokens off the host element via
+`getComputedStyle`; the CSS-based components resolve them through `var(--vd-*)`.

package/dist/charts/core.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Type declarations for the vd3-cbun charts core (the framework-agnostic
+ * factory API). The Vue wrappers have their own `vue.d.ts`; both surfaces are
+ * re-exported by the `./charts` entry's `index.d.ts`.
+ */
+
+export type Row = Record<string, unknown>;
+
+/** A field name (supports dotted paths) or an extractor function. */
+export type Accessor<T = Row, R = unknown> = string | ((row: T) => R);
+
+/**
+ * Color option:
+ *  - a CSS color string applied to every mark, OR a field name whose distinct
+ *    values map to the theme's ordinal palette;
+ *  - a function returning a CSS color per datum (e.g. `(row) => '#40c057'`).
+ */
+export type ColorOption<T = Row> = string | ((row: T) => string);
+
+export interface ChartTheme {
+  fontFamily: string;
+  textColor: string;
+  mutedTextColor: string;
+  gridColor: string;
+  axisColor: string;
+  backgroundColor: string;
+  colors: string[];
+}
+
+export interface AxisOptions {
+  label?: string;
+}
+
+/** Context object passed to a function `tooltip`. */
+export interface TooltipContext<T = Row> {
+  datum: T;
+  x?: unknown;
+  y?: number;
+  /** Numeric value of the mark (y for cartesian, slice value for pie/donut). */
+  value?: number;
+  /** Category label (bar x, pie/donut slice label). */
+  label?: unknown;
+  index?: number;
+  /** Present for multi-series charts. */
+  seriesIndex?: number;
+  seriesName?: string;
+}
+
+export type TooltipOption<T = Row> =
+  string | false | ((datum: T, context: TooltipContext<T>) => string | false);
+
+/** One series in a multi-series cartesian chart (bar / line / area). */
+export interface Series<T = Row> {
+  name: string;
+  /** y accessor for this series (falls back to the chart-level `y`). */
+  y?: Accessor<T, number>;
+  /** Per-series data (falls back to the chart-level `data`). */
+  data?: T[];
+  /** Explicit color; defaults to the next theme palette slot. */
+  color?: string;
+}
+
+export interface LegendOptions {
+  position?: 'top' | 'right';
+}
+
+export interface DataLabelsOption {
+  /** Format the value shown (defaults to the chart's number formatting). */
+  format?: (value: number) => string;
+  color?: string;
+}
+
+export interface Annotation {
+  /** Horizontal reference line at this y value. */
+  y?: number;
+  /** Vertical reference line at this x value (numeric or category). */
+  x?: number | string;
+  label?: string;
+  color?: string;
+  /** Dashed by default; set `false` for a solid line. */
+  dash?: boolean;
+}
+
+export interface ClickEvent<T = Row> {
+  event: Event;
+  datum: T;
+  index: number;
+}
+
+export interface BaseChartOptions<T = Row> {
+  /** Element or CSS selector to render into. */
+  target: string | Element;
+  data?: T[];
+  title?: string;
+  description?: string;
+  ariaLabel?: string;
+  width?: number;
+  height?: number;
+  margin?: number | { top?: number; right?: number; bottom?: number; left?: number };
+  theme?: Partial<ChartTheme>;
+  tooltip?: TooltipOption<T>;
+  /** Re-render on container resize (default true). */
+  responsive?: boolean;
+  /** Show a legend. Multi-series charts show one by default; pass `false` to hide. */
+  legend?: boolean | LegendOptions;
+  /** Draw value labels on each mark. */
+  dataLabels?: boolean | DataLabelsOption;
+}
+
+export interface CartesianChartOptions<T = Row> extends BaseChartOptions<T> {
+  x?: Accessor<T>;
+  y?: Accessor<T, number>;
+  color?: ColorOption<T>;
+  xScale?: 'linear' | 'time' | 'point';
+  xFormat?: (value: unknown) => string;
+  yFormat?: (value: number) => string;
+  xAxis?: AxisOptions;
+  yAxis?: AxisOptions;
+  /** Pin axis bounds (otherwise auto-scaled to the data). */
+  xMin?: number;
+  xMax?: number;
+  yMin?: number;
+  yMax?: number;
+  /** Target number of y ticks (default 5). */
+  yTickCount?: number;
+  /** Force 0 into the y domain. */
+  yIncludeZero?: boolean;
+  /** Multiple series (bar → grouped, line/area → one path each). */
+  series?: Series<T>[];
+  /** Reference lines drawn across the plot. */
+  annotations?: Annotation[];
+  onPointClick?: (e: ClickEvent<T>) => void;
+}
+
+export interface BarChartOptions<T = Row> extends CartesianChartOptions<T> {
+  /** Band padding between bars/groups (default 0.18). */
+  barPadding?: number;
+  onBarClick?: (e: ClickEvent<T>) => void;
+}
+
+export interface LineChartOptions<T = Row> extends CartesianChartOptions<T> {
+  stroke?: string;
+  strokeWidth?: number;
+  points?: boolean;
+  pointRadius?: number;
+  pointFill?: string;
+}
+
+export interface AreaChartOptions<T = Row> extends LineChartOptions<T> {
+  fill?: string;
+  fillOpacity?: number;
+}
+
+export interface ScatterChartOptions<T = Row> extends CartesianChartOptions<T> {
+  pointRadius?: number;
+  pointOpacity?: number;
+}
+
+export interface PieChartOptions<T = Row> extends BaseChartOptions<T> {
+  label?: Accessor<T>;
+  value?: Accessor<T, number>;
+  innerRadiusRatio?: number;
+  centerLabel?: string | false;
+  centerSubLabel?: string;
+  onSliceClick?: (e: ClickEvent<T>) => void;
+}
+
+export interface ChartInstance {
+  kind: string;
+  options: Record<string, unknown>;
+  target: Element;
+  render(): ChartInstance;
+  update(options?: Record<string, unknown>): ChartInstance;
+  resize(): ChartInstance;
+  destroy(): void;
+  showTooltip(content: string, event?: Event): void;
+  hideTooltip(): void;
+}
+
+export function BarChart<T = Row>(options: BarChartOptions<T>): ChartInstance;
+export function LineChart<T = Row>(options: LineChartOptions<T>): ChartInstance;
+export function AreaChart<T = Row>(options: AreaChartOptions<T>): ChartInstance;
+export function ScatterChart<T = Row>(options: ScatterChartOptions<T>): ChartInstance;
+export function DonutChart<T = Row>(options: PieChartOptions<T>): ChartInstance;
+export function PieChart<T = Row>(options: PieChartOptions<T>): ChartInstance;
+
+// --- scales & helpers ---
+
+export interface LinearScale {
+  (value: number): number | null;
+  domain(): [number, number];
+  range(): [number, number];
+  ticks(count?: number): number[];
+}
+
+export interface BandScale {
+  (value: unknown): number | null;
+  domain(): string[];
+  range(): [number, number];
+  bandwidth(): number;
+  step(): number;
+}
+
+export interface PointScale {
+  (value: unknown): number | null;
+  domain(): string[];
+  range(): [number, number];
+  bandwidth(): number;
+  step(): number;
+}
+
+export interface TimeScale {
+  (value: unknown): number | null;
+  domain(): Date[];
+  range(): [number, number];
+  ticks(count?: number): Date[];
+}
+
+export type OrdinalScale = ((value: unknown) => string) & {
+  domain(): string[];
+  range(): string[];
+};
+
+export function scaleLinear(config?: {
+  domain?: [number, number];
+  range?: [number, number];
+}): LinearScale;
+export function scaleTime(config?: { domain?: unknown[]; range?: [number, number] }): TimeScale;
+export function scaleBand(config?: {
+  domain?: unknown[];
+  range?: [number, number];
+  padding?: number;
+  paddingInner?: number;
+  paddingOuter?: number;
+}): BandScale;
+export function scalePoint(config?: {
+  domain?: unknown[];
+  range?: [number, number];
+  padding?: number;
+}): PointScale;
+export function scaleOrdinal(config?: { domain?: unknown[]; range?: string[] }): OrdinalScale;
+
+export function createAccessor<T = Row, R = unknown>(
+  accessor: Accessor<T, R> | undefined,
+  fallback?: Accessor<T, R>,
+): (row: T) => R;
+
+export function resolveTheme(target: Element | null, overrides?: Partial<ChartTheme>): ChartTheme;
+
+export function ticks(min: number, max: number, count?: number): number[];
+
+/**
+ * Compute a "nice" [min, max] domain. Pass a boolean for the legacy
+ * `includeZero` shorthand, or an options object; an explicit `min`/`max`
+ * pins that bound exactly.
+ */
+export function niceDomain(
+  values: unknown[],
+  options?: boolean | { includeZero?: boolean; min?: number; max?: number; tickCount?: number },
+): [number, number];
+
+export function linePath(points: Array<{ x: number; y: number }>): string;
+export function areaPath(points: Array<{ x: number; y: number }>, baselineY: number): string;
+export function arcPath(
+  cx: number,
+  cy: number,
+  outerRadius: number,
+  innerRadius: number,
+  startAngle: number,
+  endAngle: number,
+): string;
+
+export const VD_CHARTS_VERSION: string;