@pond-ts/charts 0.54.0 → 0.56.2

package/CHANGELOG.md

@@ -8,7 +8,11 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.54.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.56.2...HEAD
+[0.56.2]: https://github.com/pond-ts/pond/compare/v0.56.1...v0.56.2
+[0.56.1]: https://github.com/pond-ts/pond/compare/v0.56.0...v0.56.1
+[0.56.0]: https://github.com/pond-ts/pond/compare/v0.55.0...v0.56.0
+[0.55.0]: https://github.com/pond-ts/pond/compare/v0.54.0...v0.55.0
 [0.54.0]: https://github.com/pond-ts/pond/compare/v0.53.1...v0.54.0
 [0.53.1]: https://github.com/pond-ts/pond/compare/v0.53.0...v0.53.1
 [0.53.0]: https://github.com/pond-ts/pond/compare/v0.52.0...v0.53.0
@@ -55,8 +59,454 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.56.2] — 2026-08-05
+
+### Fixed
+
+- **charts (tests only, no shipped change):** the log-axis rendered-label test
+  is no longer an exact-set assertion over every digit-bearing node in the
+  render tree. It passed on Node 22 and failed on CI's Node 18 with one extra
+  element, blocking the publish twice. The discrepancy is **unreproduced and
+  still open** — recorded as `[PND-LOGTICK-N18]` in `PND_CHARTS_PLAN.md` with
+  everything measured about it. The assertion now checks that every chosen tick
+  renders in order, which is the wiring this test exists to cover; the tick
+  _selection_ it was really about is pinned deterministically by the
+  `yTickValues` unit tests.
+
+## [0.56.1] — 2026-08-05
+
+### Fixed
+
+- **charts (tests only, no shipped change):** a log-axis test asserted on
+  rendered label _text_, parsing numbers back out of the DOM to infer scale
+  behaviour. It passed locally and failed in CI on a value it could not have
+  produced there, which blocked the v0.56.0 publish. The root cause was never
+  reproduced; rather than guess at it, the assertion now compares the rendered
+  labels against the ticks the axis is specified to draw, formatted through the
+  same formatter — deterministic regardless of locale, formatting or DOM
+  differences, and the numeric guarantee itself was already pinned directly by
+  the `yTickValues` unit tests. The published artifact is identical to what
+  v0.56.0 would have been.
+
+## [0.56.0] — 2026-08-05
+
+### Added
+
+- **charts:** **`<YAxis scale="log">` — a base-10 logarithmic y axis.** Every y
+  scale was `scaleLinear`, so data spanning orders of magnitude was
+  undrawable: on a linear axis everything below the top decade collapses onto
+  the baseline. Set `scale="log"` and the axis maps by ratio, ticking the
+  decades. `format` still formats the **value**, so a readout says `1.2 PB`
+  rather than its logarithm — the transform is in the scale, not in the data,
+  which is what keeps it transparent to every draw layer, annotation and
+  cursor readout.
+
+  A log domain cannot contain zero, and d3 maps a non-positive value to
+  **`NaN`** — a coordinate the canvas silently _drops_, which is why every
+  consequence below is about something failing invisibly rather than throwing.
+  So the axis is deliberate about it:
+  - **Domain policy matches the linear axis exactly.** Auto-fit takes the
+    smallest **positive** extent (one zero sample can't collapse the axis, and
+    a `BarChart` — whose extent always widens to include zero — can still share
+    it); a positive explicit `min`/`max` is honoured verbatim and never
+    discarded, with the _auto-fit_ side moving if the domain would otherwise
+    invert; a fully auto-fit domain is `.nice()`d out to whole powers of ten, so
+    the extremes get headroom instead of sitting clipped on the plot edge. A
+    non-positive bound has no position and is refused in favour of the data.
+    `pad` is applied multiplicatively, adding the same fraction of a decade at
+    both ends.
+  - **A value with no position on the axis renders as a gap.** Previously the
+    gap test was `Number.isFinite(value)`, and `0` is finite — so the coordinate
+    became `NaN`, the canvas dropped the path op without breaking the path, and
+    the two neighbours were joined by a straight line _over_ the missing data.
+    Lines, area fills and outlines, and band envelopes now all break there.
+  - **Layers that reach for a baseline rest on the axis floor.** `AreaChart`
+    resolves an out-of-domain `baseline` there (writing `baseline={0}` is
+    natural and correct on a linear axis), and a **stacked** bar layer starts
+    its first segment there — starting at zero made the bottom segment of every
+    stack both invisible and unhittable. Unchanged on a linear axis, where zero
+    clamped into the domain _is_ zero.
+  - **The dev-mode warning names only unambiguous mistakes**: a refused
+    `min`/`max`, negative data, or an axis with no positive data at all. It
+    deliberately says nothing about an extent of exactly `[0, hi]`, which a
+    line touching zero and a bar layer on strictly positive data both report
+    identically — warning there fired on _every_ bar chart on a log axis. It
+    warns once per distinct complaint rather than on every repaint.
+
+- **charts:** **pan and zoom now yield whole-millisecond view ranges.** A
+  wheel-zoom derives its range from pixel positions through `xScale.invert()`,
+  so the result was fractional by construction — an ordinary scroll produced
+  `1.7e12 + 0.37`. The epoch millisecond is this model's atomic unit and
+  consumers are entitled to assume it; one did, and a calendar `cursorSequence`
+  threw on a plain scroll. `zoomRange` / `panRange` round both ends, and never
+  collapse a positive span to zero width in doing so. (Core's fractional-instant
+  fix covers the same crash from the other side; this closes the class.)
+
+- **charts:** **`AreaStyle.flatFill` — stacked areas that read as slabs.** An
+  area's fill has always graded to transparent at the baseline, which is right
+  for the elevation form and wrong for a stack: every band showed the one
+  beneath it through the fade, so a stacked area was not really drawable. Set
+  `flatFill` and the fill is flat; omitted, the gradient is unchanged, so no
+  existing theme shifts. The docs theme's `seq1…seq8` area roles set it, since
+  stacking is what they exist for.
+
+- **docs theme:** **a sequential ramp — `seq1…seq8` — for charts with more
+  series than the categorical set has hues.** `--pond-viz-1…5` were, and
+  remain, the categorical set; a chart needing more slots (an eight-source
+  stack, a wall of climate stripes) now steps **tonally** through the brand
+  teal instead of introducing competing hues. Eight steps, evenly spaced
+  (~ΔL\* 9 in CIELAB), defined for light and dark, each mode's ramp containing
+  that mode's `--pond-viz-1` exactly. Exposed as `line` / `area` / `bar` theme
+  roles on `docsTheme` (Storybook) and the docs site's `useSiteChartTheme`,
+  and as an array from the site's `useSequentialRamp()`. Dev-only: the ramp
+  lives in the `docs-theme.fixture.ts` Storybook fixture and the website's
+  CSS, both excluded from the published `@pond-ts/charts` build — the library
+  still ships no palette.
+
+### Fixed
+
+- **core:** **a fractional epoch millisecond no longer crashes calendar
+  math.** `Temporal.Instant` refuses a non-integer epoch ms outright
+  (`epoch milliseconds must be an integer`), and `toPlainDateStart` passed
+  whatever it was given straight through — so realizing a `Sequence.calendar`
+  over a fractional range threw, and in a React app the exception unmounted the
+  page. A fraction is not a caller error: a chart's wheel-zoom derives its view
+  range from pixel positions via `xScale.invert()`, so an ordinary scroll
+  produces `1.7e12 + 0.37`. The instant is now floored to the millisecond
+  containing it — the epoch millisecond is this model's atomic unit and
+  calendar boundaries are themselves whole milliseconds, so the bucket
+  containing `t` and the one containing `t + 0.37` are necessarily the same,
+  and integer inputs are untouched. (`Math.floor`, not `Math.trunc`: pre-1970
+  they disagree, and `-5.5` lies inside the millisecond spanning `[-6, -5)`.)
+
+- **charts:** toggling **`<ChartContainer grid>`** now repaints immediately.
+  `Layers`' draw callback read `container.grid` but didn't depend on it, so
+  switching gridlines off changed nothing until an unrelated dependency moved —
+  in practice you had to pan or zoom a little to force the update. The same
+  omission covered `sessionDividers` and `xKind`.
+
+- **charts:** the log axis's dev-mode warning no longer requires **node's
+  ambient types**. It was guarded by a bare `process.env.NODE_ENV`, which
+  typechecks only when a tool happens to resolve `@types/node` from a parent
+  `node_modules` — so `tsc` inside the package passed while running the _same_
+  tsconfig from a consumer's directory failed with `TS2591: Cannot find name
+'process'`. That took out the docs site's TypeDoc step, and would equally hit
+  any consumer typechecking the package's sources. The guard now lives in
+  `src/dev.ts` behind a local declaration and a `typeof` check, so a browser
+  bundle with no `process` global doesn't throw at import either.
+
+## [0.55.0] — 2026-08-04
+
+### Added
+
+- **process:** **`@pond-ts/process` publishes for the first time —
+  experimental, pre-1.0.** Computations as data over pond-ts: a processing
+  graph authored fluently in application code (or composed as JSON by a saved
+  view or a tool-calling model) resolves against a declared op vocabulary and
+  runs over a bound `TimeSeries`, with content-addressed caching, provenance,
+  and per-node timings on every response. Two entry points: the plan layer at
+  `.` and the Node worker pool at `./pool`. The docs section
+  ([pond-ts.org/docs/process](https://pond-ts.org/docs/process/)) is listed on
+  the site with a TypeDoc API reference; the publication follows the 2026-08
+  external audit hardening (all P1 findings fixed and regression-pinned). The
+  API is expected to move as friction reports land — pin an exact version.
+
+- **charts:** **`<BarChart categories>` now works horizontally** ([PND-HCAT],
+  the 2026-08 API review's #3 item) — the funnel / ranking / comparison shape.
+  `orientation="horizontal"` puts the categories on the **y** axis as unit
+  slots with the value on x, and a `<YAxis>` with no explicit `ticks` **derives
+  one label per category by itself**, so the chart no longer needs a
+  hand-built `i + 0.5` tick list. It previously threw ("horizontal category
+  axes are not yet supported"), which forced consumers to convert their
+  categories into ordinal `bins` records _and_ hand-place the labels — the
+  workaround the gallery funnel documents.
+
+  Explicit `<YAxis ticks>` still wins, and vertical categorical charts are
+  untouched (categories stay on the container's ordinal x band scale). A new
+  internal `RowLayer.binCategories()` channel carries the names to whichever
+  axis they land on.
+
+- **charts:** **the list family's series door** — `<BarList series={splits}
+label={…}>` / `<BoxList series>` take a `TimeSeries` / `ValueSeries`
+  directly (one row per event; exactly-one-of with `rows`), closing the
+  "required adapter" gap the 2026-08 API review named: starting from a pond
+  series there is no shaping step. The `listRowsFrom*` readers remain for
+  record rows. Docs across the charts hub, cheat sheet, and type pages now
+  present the series as the whole data contract, with the exported `from*`
+  builders re-documented as **interop escape hatches for non-pond data**.
+
+- **charts:** **`<BarList>` + `<BoxList>` — standalone ranked row lists** (the
+  react-timeseries-charts `HorizontalBarChart` shape, rebuilt as what it
+  always was: a table). One DOM row per _entity_ — an interface, a split, a
+  symbol — with a label cell (any node, links included), one glyph line per
+  configured column on **one shared value scale**, optional data cells
+  before/after the glyphs, `sortBy`/`sortDirection` or a full custom
+  comparator (missing values sort last either direction), an optional per-row
+  expander (`renderExpanded`, keyed on row identity so it survives a re-sort),
+  and consumer-owned row selection with an accent edge in the marks register.
+  A vertical **baseline rule** at the scale origin anchors the rows to one
+  reference (on by default for `<BoxList>`, whose lines float at their lower
+  quantile; opt-in for `<BarList>`, whose tracks already show zero), and
+  reference **`markers`** (`{ value, label? }`) draw a labelled dotted rule
+  through every row in the annotation register — an SLA / capacity line —
+  with marker values joining the auto domain fit.
+  `<BarList>` draws proportional value bars; its sister `<BoxList>` draws a
+  five-number distribution per line — range band, `q1`→`q3` body, median line
+  — plus an optional **current-value tick** with a formatted inline label (the
+  esnet traffic-by-interface look), using the same quantile vocabulary as the
+  canvas `<BoxPlot>` (`lower`/`q1`/`median`/`q3`/`upper`, both-or-neither
+  body, quantiles computed upstream — `reduce` facts — never by the chart).
+  Styling stays on the one channel: bars resolve `theme.bar[as]`, boxes
+  `theme.box[as]`; both built-in themes gain a `box.secondary` role for the
+  paired-direction case. Readers `listRowsFromTimeSeries` /
+  `listRowsFromValueSeries` build one row per event / axis key. The in-plot
+  histogram remains `<BarChart orientation="horizontal">` — the lists are for
+  the table-shaped cases it can't be (link labels, cells, expanders, custom
+  sort).
+
+- **charts:** **`BarStyle.hover` — a distinct hover colour for bars**
+  ([#577](https://github.com/pond-ts/pond/issues/577)). A theme may now give
+  bars a three-step emphasis — `fill` at rest → `hover` under the pointer →
+  `highlight` (plus the outline) when selected. Previously one `highlight`
+  served both live states, so hover and select differed only by the presence of
+  an outline; `ScatterStyle` has carried distinct rest / selected treatments
+  (`outline` vs `selectedOutline`) all along, making bars the less expressive
+  layer for the same two-state interaction.
+
+  **Optional, with a `highlight` fallback**, so no existing theme changes
+  meaning or rendering — a theme that wants the distinction adds one colour.
+  Selection outranks hover on a bar that is both. Single-series only: a stacked
+  or per-bin-coloured bar has no separate highlight colour to replace (it pops
+  its _own_ fill, so a red/green volume bar keeps its meaning while live), and
+  that convention is unchanged.
+
+### Changed
+
+- **charts:** **a bar's capabilities now follow the mark it draws, not the
+  prop that fed it** ([PND-BARSEM], the 2026-08 API review's #2 item). A
+  **one-column vertical** histogram (`bins` + a single `column`) and a
+  one-entry `columns` draw exactly the mark a `series` + `column` chart
+  draws, but they used to route through the stacked path purely because of
+  which prop supplied them — and so silently lost whole-slot hit-testing
+  (#584), the `BarStyle.hover` colour, the cursor readout, stable per-bar
+  identity and per-bar decimation. They now take the single-series path, so
+  visually identical bars behave identically.
+
+  **What this changes in practice:** on a one-column histogram, hover and
+  click now hit the bar's **whole slot** rather than only the drawn
+  rectangle (so the space above a short bar is live, and slots tile the
+  axis); the layer gains a cursor readout; and `theme.bar.hover` applies.
+  A genuine multi-group stack, `categories`, and horizontal charts are
+  unchanged — their segments share a bin's x-range, so only y distinguishes
+  them. New reader `barsFromBins` backs the normalized path.
+
+  **Not a pure widening, in one respect:** dense-bar envelope decimation is
+  now live on a one-column histogram (it was single-series-only). It engages
+  only once bars fall under ~1px, where it is visually lossless, but at that
+  density the per-bar `gap` and highlight give way to envelope rects — pass
+  `decimate={false}` to keep every bar drawn. The `colors` map, the
+  `theme.bar[<column>]` role and `SelectInfo.label` are all preserved across
+  the reroute (each was a silent regression caught in review).
+
+  This shrinks `BarStyle.hover`'s scope warning from a list of five
+  path-accidents to the two real exclusions (a multi-group stack has no
+  hover channel on `StackStyle`; `binColors` keeps each bar's own colour by
+  design) — which was the acceptance test the task set itself.
+
+- **charts:** **column names and source modes are now checked at compile
+  time** ([PND-CHARTAPI], the 2026-08 API review's #1 item). Every draw
+  layer's column props are derived from the series' schema, so
+  `<LineChart series={cpu} column="cpuu" />` — and a numeric prop pointed at
+  a string column, where the schema has some other numeric column — fail to
+  **compile** instead of throwing at render; the
+  same holds for `readout`, the band edges, the box quantiles, and the OHLC
+  prices. `<BarChart>`'s props became a **union of its legal source modes**,
+  so mixing sources (`series` + `bins`) or column forms (`column` +
+  `columns`), or passing `categories` a `column`, are compile errors too.
+  `<BarList>` / `<BoxList>` get the same treatment for `rows` XOR `series`,
+  which additionally closes the row-type hole #590 documented (annotating a
+  callback with a custom row type while passing `series` claimed a shape the
+  series door cannot produce).
+
+  **This narrows what compiles — deliberately.** Code carrying a typo, an
+  illegal mode mix, or a lying row annotation stops building; that is the
+  point, and each case was already a runtime failure. Two compatibility
+  behaviours are preserved on purpose: a **loosely-typed** series
+  (`TimeSeries<SeriesSchema>`, e.g. from a helper that doesn't narrow) still
+  accepts any column name, because an unparameterized schema leaves the name
+  union open and nothing can be checked against it; and `bins` column names
+  stay `string`, since they name aggregate fields of a bin record rather than
+  schema columns. Note the deliberate distinction: a schema that _does_ name
+  its columns but has **no numeric one** rejects every name — there is nothing
+  numeric to plot — which is not the same as the loose case.
+
+  **One new limitation.** Because a layer's props are a union _per series
+  kind_, a value typed as _either_ kind (`TimeSeries<A> | ValueSeries<B>` — a
+  wrapper that forwards whatever it is given) matches no single member and
+  must be narrowed or cast at the boundary. `DurationAxis.stories.tsx` is the
+  worked example. The alternative design (one generic over the series type)
+  handles that case but changes every props type's public generic parameters;
+  the trade is recorded in `spikes/charts-type-seam/REPORT.md`.
+
+- **charts:** **a bar's hover / click target is now its whole slot**, not the
+  rectangle it draws. A bar _is_ the full width of its interval; the `gap` that
+  separates adjacent columns is a display affordance. Hit-testing the drawn
+  rect made that affordance interactive — the gap was a dead channel you could
+  point at and select nothing, and so was the empty plot space above a short
+  bar, even though the x-scrub cursor at that same x reported the bar quite
+  happily. `barAt` now tests the bar's full interval width and the full plot
+  height, so hover, click and the cursor readout all agree on which bar you are
+  on, and slots tile the axis.
+
+  **Widening, with one exception.** Points that previously selected _nothing_
+  now select the bar whose slot they fall in. The exception: a bar whose value
+  exceeds an explicit `<YAxis max>` used to draw — and be clickable — above the
+  plot top, in the strip a `'top'` axis title reserves; the slot stops at the
+  axis domain, so that sliver no longer hits. Everything inside the plot that
+  hit before still hits.
+
+  **It reaches across the full plot height, so it can shadow layers beneath
+  it.** The topmost hit wins, so a `<BarChart>` declared _after_ a
+  `<ScatterChart>` / `<BoxPlot>` / another `<BarChart>` in the same row now
+  claims every hit in its x-range at any y. Declare a bar layer **below** the
+  marks that should stay clickable.
+
+  **Single-series vertical only** — a stacked, `bins`, `categories` or
+  horizontal chart still hit-tests the drawn segment, because a stack's
+  segments share a bin's x-range and only y tells them apart.
+
+  Unchanged: a genuine hole between non-contiguous intervals still misses (the
+  change makes the drawing gap hittable, it doesn't invent coverage the data
+  lacks), a gap (`NaN`) bar owns no slot, and a shared edge goes to the left
+  bar — the rule `barIndexAtTime` already documented, so the two now agree by
+  construction.
+
+### Fixed
+
+- **process:** **audit hardening — five wrong-answer / silent-acceptance paths
+  in the plan layer closed** (external Codex audit, 2026-08; all reproduced,
+  all regression-pinned). Unit validation of a **picked output** read
+  `outputs[0]` instead of the selected output, so a picked `variance` was
+  refused where variance was demanded and — worse, silently — accepted where
+  price was. `Registry.define()` now rejects duplicate input roles and
+  duplicate output ids (both used to _collapse_ at run time rather than fail:
+  inputs resolved to the last role, outputs dropped the earlier column),
+  invalid param defaults, and `dependsOn` naming unknown params. An op result
+  whose length does not match the bound series is refused at the producer —
+  it used to ride out unchecked whenever `assemble: false` skipped the only
+  length check. The column-selection loop now honours `onError` (an operator
+  exception escaped `'collect'`), and a selector naming a nonexistent output
+  is a `skipped` entry instead of silently surfacing nothing. Fact provenance
+  (`id`, `name`, `op`, `unit`) now wins over a custom fold body's fields, and
+  `columnBytes` sums a chunked column's chunks instead of reporting 0 — which
+  a byte budget would read as "free".
+
+  Also: the derived fold slots in both builders now key by **params** —
+  `shape({points: 100})` after `shape({points: 20})` silently returned the
+  20-point node — and `shape` itself uses a `ceil` stride, so 200 points
+  asked of 399 rows returns ≤200 rather than all 399. The nested JSON Schema
+  projection can now express the `PickedOutput` input form, `Host` accepts
+  `budgetBytes` (the [PND-PROCCACHE] cap was unreachable from the long-lived
+  host shape) and grows `remove(id)`, and CI's package-content check covers
+  `@pond-ts/process`. Package remains **unpublished** (`private: true`).
+
+  A second audit round tightened the same seams. `columnBytes` now counts
+  what is actually retained: the **backing buffer's capacity** rather than
+  the column's logical length (core documents `_values` as possibly
+  oversized, so a one-row column viewing a 1000-slot buffer retains 8,000
+  bytes, not 8 — an undercount that defeats the budget), the chunk-offset
+  index and the bitmap's real bytes on chunked columns. The
+  **request-driven half of a `Host`'s footprint is now boundable**:
+  `runAsync` binds a graph per distinct caller-supplied `SourceRef`, so
+  `maxSources` caps registry-loaded sources LRU (author-added datasets are
+  never evicted), and a `remove()` racing an in-flight load now wins — the
+  landing load discards its result instead of resurrecting the dataset.
+  And an omitted param now unifies with its explicit default in the fluent
+  layer's derived fold slots (`shape()` ≡ `shape({points: 40})`, the same
+  rule `specId` applies), while the response labels a computation with the
+  **first** slot that named it rather than whichever was declared last.
+
+- **charts:** **a hovered or selected single-series bar now pops to full
+  opacity** ([#576](https://github.com/pond-ts/pond/issues/576)). `drawBars`
+  set `globalAlpha` once to the resting `style.opacity` and never lifted it for
+  the highlight **fill** on the single-series path — only for the selected
+  bar's outline. The per-bar-`binColors` branch in the same function and
+  `drawStacks` both already popped to 1, and `drawBars`' own docstring claimed
+  it did too. So on a theme with `opacity < 1` a **hovered** bar (which has no
+  outline) barely changed, and a **selected** one read only by its outline.
+  All three paths now treat the highlight fill identically.
+
+  **This changes pixels** on any single-series `<BarChart>` with an alpha'd
+  theme: highlighted bars are brighter. A theme that raised its base `opacity`
+  to compensate may now want it back down.
+
+  **It also flattens select against hover**, which is worth knowing before you
+  upgrade. The selected bar's outline strokes in `highlight` — previously that
+  read as a brighter ring over an alpha'd fill, and it was the main thing
+  separating a selected bar from a hovered one. Now the fill underneath is the
+  same colour at the same alpha, so only the half of the stroke falling
+  outside the rect distinguishes them. Hover is no longer nearly invisible,
+  but the two live states are closer together. A theme that needs them clearly
+  apart should set the new `BarStyle.hover`.
+
 ## [0.54.0] — 2026-08-02
 
+### Fixed
+
+- **core:** **`fromArrow` now reads a field's declared Arrow type instead of
+  guessing from the runtime shape of `toArray()`** — closing a
+  silent-corruption class. The reader worked out what a column held from what
+  `toArray()` handed back, which is correct for the types it supports and
+  quietly wrong outside them, because Arrow's physical layouts do not all store
+  one machine word per logical value. Measured, before the fix: **`Float16`
+  ingested `1.5` as `15872`** (its half-float bit pattern — the length matched,
+  so nothing caught it), and a **`Decimal128` column with a single null
+  ingested `123.45` as `12345`** (the per-element path produced exactly `rows`
+  values, so the length check never fired). A dense `Decimal` merely threw the
+  wrong error, blaming a length mismatch.
+
+  The readable set is now an explicit allowlist — `Int` (any width),
+  `Float32`/`Float64`, `Date32`/`Date64`, `Time32`/`Time64`, `Timestamp`,
+  `Utf8`/`LargeUtf8`/`Utf8View`, `Null` (an all-missing value column), and a
+  `Dictionary` of any of those (the encoding is transparent; readability
+  follows the value type) — checked per field, on the key and value columns of every
+  Arrow door (`TimeSeries.fromArrow`, `ValueSeries.fromArrow`, and the
+  flattened key edges). Anything else is refused **by name**, with the cast
+  that would fix it: `Decimal` names the float64 precision trade-off, `Float16`
+  says to cast, `Bool` names the real reason (the columnar ingest engine
+  carries `number` and `string` value columns only). A duck-typed stand-in
+  carrying no `typeId` keeps working — the `ArrowTableLike` contract is
+  deliberately structural — and gains a width check that catches the Decimal
+  shape anyway.
+
+  Behavioural change worth noting: a `Utf8` **key** now throws on its declared
+  type rather than on its shape, so the message names the type and points at
+  passing it as a value column instead.
+
+### Changed
+
+- **A fold no longer builds a `TimeSeries`** ([PND-PROCTERM]). Every node's
+  `compute` widened the source with `appendColumn` for each nested input, so
+  an op could call the corpus normally — the studies take
+  `(series, { column })`. For a fold that was waste twice over: the column it
+  reads is already in its inputs, and it was being packed into a series only
+  to be read straight back out.
+
+  The cost was not incidental. `appendColumn` **boxes a gapped column** on
+  the way in, because core's `withColumn` takes values rather than a column —
+  22.4 ms per column at 1M rows. Every rolling study is gapped, so the
+  expensive path was the ordinary one.
+
+  20 folds × 500k rows, on top of the columnar fold context below:
+  **383 → 129 ms** (2.96×), rss 173 → 113 MB. Against the boxed, assembling
+  baseline the two changes together are **606 → 129 ms**.
+
+  A facts-only request now returns no `series` at all, and the upstream
+  column still resolves through the node graph rather than the terminal's
+  `needed` set — so the failure the plan warned about, a fact silently
+  coming back with no value because its column was never selected, cannot
+  happen.
+
 ### Added
 
 - **`ctx.out` — prepared output buffers for a ranged recompute**

package/dist/AreaChart.d.ts

@@ -1,30 +1,10 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import type { DecimateOption } from './decimate.js';
 import { type Curve } from './curve.js';
 import { type GapMode } from './gaps.js';
-export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
-    /**
-     * The source series. A `TimeSeries` fills against the time axis; a
-     * `ValueSeries` (`series.byValue('dist')`) against its value axis — the
-     * container infers which from the data, no axis-type prop (mirrors
-     * `<LineChart>`). Either way `column` names the numeric value to fill from.
-     *
-     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
-     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
-     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
-     */
-    series: TimeSeries<S> | ValueSeries<VS>;
-    /** Name of the numeric value column to fill from. */
-    column: string;
-    /**
-     * Optional column to **read out** at the cursor instead of the plotted
-     * `column` — the area still fills `column`, but each tracker sample also
-     * carries this column's value as {@link TrackerSample.readout}, so an
-     * off-chart readout can show a **source** value while the area draws a derived
-     * one. Mirrors `<LineChart readout>`. **Omitted ⇒ no readout channel.**
-     */
-    readout?: string;
+export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The series' semantic identifier — what the data _is_ / how it should read
      * (e.g. `elevation`, or a signed-traffic role like `in` / `out`). The theme
@@ -96,6 +76,50 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      */
     index?: number;
 }
+/**
+ * AreaChart's source + column props, a **union over the series kind** so the
+ * column names are checked against the schema that was actually passed
+ * ([PND-CHARTAPI]). A single member carrying `NumericColumn<S> |
+ * ValueNumericColumn<VS>` would silently widen to `string`: only one of the
+ * two generics is ever inferred, and the other falls back (measured in
+ * `spikes/charts-type-seam/`). Loosely-typed series still accept any name.
+ */
+type AreaChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = {
+    /**
+     * The source series. **Live charts:** `series.byValue(…)` mints a
+     * *fresh* projection each call, so an inline `series={s.byValue('d')}`
+     * re-registers this layer every render — on a frequently re-rendering
+     * (e.g. scrub-driven) chart, memoize the projection (`useMemo`) so the
+     * layer isn't rebuilt each frame.
+     */
+    series: TimeSeries<S>;
+    column: NumericColumn<S>;
+    readout?: NumericColumn<S>;
+} | {
+    series: ValueSeries<VS>;
+    column: ValueNumericColumn<VS>;
+    readout?: ValueNumericColumn<VS>;
+};
+/** `<AreaChart>`'s props: the shared knobs plus one series-kind source shape. */
+export type AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = AreaChartCommon<S, VS> & AreaChartSource<S, VS>;
+/** Read a d3 linear scale's domain lower bound (the axis floor) from the plain
+ *  `(value) => pixel` function the row hands to `draw`. The runtime object is a
+ *  d3 `ScaleLinear` (it carries `.domain()`); the {@link RowLayer} type narrows
+ *  it to the call signature, so this reads the bound through a localized,
+ *  documented shape rather than widening `drawArea`'s contract to d3-scale. */
+/**
+ * The area's baseline in **data** units: the caller's `baseline` when it has a
+ * finite position on this axis, else the axis floor.
+ *
+ * The fallback is not defensive padding — it's the log case. `baseline={0}` is
+ * the natural thing to write and is correct on a linear axis; on a log axis
+ * zero has no position at all — `scaleLog()(0)` is **`NaN`** (the `-Infinity`
+ * the log *transform* produces is then interpolated into the range, and
+ * `∞ − ∞` is what comes out) — and a single non-finite coordinate turns the
+ * whole filled path into nothing drawn at all. Resolving to the floor keeps the
+ * layer's meaning ("fill from the bottom") on both scale kinds.
+ */
+export declare function resolveAreaBaseline(baseline: number | undefined, yScale: (value: number) => number): number;
 /**
  * An area draw layer: fills between a value `column` and a `baseline`, with a
  * graded (gradient) shade — opaque at the line, transparent at the baseline —
@@ -117,4 +141,5 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * ```
  */
 export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
+export {};
 //# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -12,6 +12,24 @@ import { useSlotKey } from './use-slot-key.js';
  *  d3 `ScaleLinear` (it carries `.domain()`); the {@link RowLayer} type narrows
  *  it to the call signature, so this reads the bound through a localized,
  *  documented shape rather than widening `drawArea`'s contract to d3-scale. */
+/**
+ * The area's baseline in **data** units: the caller's `baseline` when it has a
+ * finite position on this axis, else the axis floor.
+ *
+ * The fallback is not defensive padding — it's the log case. `baseline={0}` is
+ * the natural thing to write and is correct on a linear axis; on a log axis
+ * zero has no position at all — `scaleLog()(0)` is **`NaN`** (the `-Infinity`
+ * the log *transform* produces is then interpolated into the range, and
+ * `∞ − ∞` is what comes out) — and a single non-finite coordinate turns the
+ * whole filled path into nothing drawn at all. Resolving to the floor keeps the
+ * layer's meaning ("fill from the bottom") on both scale kinds.
+ */
+export function resolveAreaBaseline(baseline, yScale) {
+    const floor = domainFloor(yScale);
+    if (baseline === undefined)
+        return floor;
+    return Number.isFinite(yScale(baseline)) ? baseline : floor;
+}
 function domainFloor(yScale) {
     const d = yScale.domain?.();
     return d && d.length > 0 ? d[0] : 0;
@@ -137,7 +155,12 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
             // Omitted baseline rests on the axis floor (resolved late from the
             // scale, so it tracks the auto-fit domain); a fixed baseline is used
             // verbatim.
-            baseline ?? domainFloor(yScale), curveFactory, gaps, gapConnectorOpacity, decimate),
+            // A log axis has no position for zero — or anything at or below
+            // it — so an explicit out-of-domain `baseline` would scale to
+            // `NaN` and poison every coordinate in the fill path. Fall back
+            // to the axis floor, which is exactly what an omitted baseline
+            // already resolves to.
+            resolveAreaBaseline(baseline, yScale), curveFactory, gaps, gapConnectorOpacity, decimate),
         },
         axisId: axis,
         index,

package/dist/BandChart.d.ts

@@ -1,24 +1,9 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import { type Curve } from './curve.js';
 import type { DecimateOption } from './decimate.js';
-export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
-    /**
-     * The source series. A `TimeSeries` fills the envelope against the time axis;
-     * a `ValueSeries` (`series.byValue('dist')`) against its value axis — the
-     * container infers which from the data, no axis-type prop (mirrors
-     * `<LineChart>` / `<AreaChart>`). Either way `lower`/`upper` name the numeric
-     * edge columns.
-     *
-     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
-     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
-     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
-     */
-    series: TimeSeries<S> | ValueSeries<VS>;
-    /** Name of the numeric column for the band's lower edge (e.g. `p25`). */
-    lower: string;
-    /** Name of the numeric column for the band's upper edge (e.g. `p75`). */
-    upper: string;
+export interface BandChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The band's semantic identifier — what the spread _is_ (e.g. `outer` for a
      * p5/p95 envelope, `inner` for p25/p75). The theme maps it to a
@@ -64,6 +49,32 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      */
     index?: number;
 }
+/**
+ * BandChart's source + column props, a **union over the series kind** so the
+ * column names are checked against the schema that was actually passed
+ * ([PND-CHARTAPI]). A single member carrying `NumericColumn<S> |
+ * ValueNumericColumn<VS>` would silently widen to `string`: only one of the
+ * two generics is ever inferred, and the other falls back (measured in
+ * `spikes/charts-type-seam/`). Loosely-typed series still accept any name.
+ */
+type BandChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = {
+    /**
+     * The source series. **Live charts:** `series.byValue(…)` mints a
+     * *fresh* projection each call, so an inline `series={s.byValue('d')}`
+     * re-registers this layer every render — on a frequently re-rendering
+     * (e.g. scrub-driven) chart, memoize the projection (`useMemo`) so the
+     * layer isn't rebuilt each frame.
+     */
+    series: TimeSeries<S>;
+    lower: NumericColumn<S>;
+    upper: NumericColumn<S>;
+} | {
+    series: ValueSeries<VS>;
+    lower: ValueNumericColumn<VS>;
+    upper: ValueNumericColumn<VS>;
+};
+/** `<BandChart>`'s props: the shared knobs plus one series-kind source shape. */
+export type BandChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = BandChartCommon<S, VS> & BandChartSource<S, VS>;
 /**
  * A variance-band draw layer: fills the envelope between the `lower` and `upper`
  * columns of `series` (typically `rollingByColumn` percentiles), gap-aware, and
@@ -82,4 +93,5 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * ```
  */
 export declare function BandChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, upper, as: semantic, axis, curve, decimate, legend, index, }: BandChartProps<S, VS>): null;
+export {};
 //# sourceMappingURL=BandChart.d.ts.map