The viewer threads the model's doc through normalizeModel into both
composite view states — appended to INFO.B (collapsed box) and INFO.C
(expanded cluster frame) — and shows the root composite's doc as a muted
header line (#rootdoc span in GRAPH_HEAD, empty when absent; the DOM
population sits in the browser-only block, the same boundary as the
breadcrumb). viewer_tooltip.mjs pins the doc'd cases beside the
byte-exact un-doc'd pins; sample-model.json gains the additive doc key;
e2e drives aura graph over a nested-doc blueprint into the emitted page.
closes#125
The headless viewer suite covered only the DOT half (normalizeModel/
genDot); the tooltip half — INFO.B (collapsed), INFO.C (expanded
cluster), INFO.P (ports), and md()'s markdown-to-HTML step — was
asserted by no test. viewer_tooltip.mjs pins the current shapes;
graph-viewer.js only hoists md() above the browser guard and exports
it (location-only move, no behaviour change), so the pin can drive the
real conversion headlessly. Surfaced by the grounding-check on the #125
composite-doc spec: its viewer assumptions had no current-behaviour pin.
refs #125
Builder: NodeHandle::param -> ParamRef, GraphBuilder::gang, build() resolves
the gang table (collect-then-reject, BuildError::{UnknownParam,AmbiguousParam,
BadGang}) and terminates in Composite::with_gangs — the same predicate the
op-script and serde boundaries use. C24 lockstep extended: an op-script gang
replay serializes byte-identically to the GraphBuilder twin (FlatGraph edges +
sources + canonical JSON).
Render: model_to_json emits a per-scope gangs fragment (name, kind, [node,pos,
"param"] members) for ganged scopes only — the gang-free model stays
byte-identical (model_golden untouched). graph-viewer.js annotates a ganged
open param with its public knob name; guarded by a viewer_gang_param.{mjs,rs}
pair RED-first per the established viewer_bound_param convention (a welcome
extra beyond the plan's file list).
Ratified deviation: the model's kind string uses the serde form ("I64") — the
plan's implementation snippet (kind_str -> "i64") contradicted its own test;
resolved toward the test + the blueprint_serde form. Two quality nits held as
principled plan-holds (inline resolution block; the unreachable unwrap_or
placeholder check_gangs refuses first).
Verified: aura-engine lib 264/0 (model_golden, lockstep, builder, carrier all
green), viewer_gang_param 1/0, workspace clippy -D warnings clean. Slice
resumed across a transient API failure via workflow resume (cached prefix).
refs #61
Second half of the style pin. assets/aura.css now carries (a) the full
:root token palette (Catppuccin-Mocha-derived; --bg deliberately darker
than Mocha base; new --border3 #585b70 completes the border ladder at an
identical computed value), (b) the shell rules migrated color-literal to
var() with identical computed values (font stacks stay literal — the
--mono token's longer fallback chain would change the computed value),
and (c) an opt-in, class-scoped component library distilled from the
milestone demo page (.aura-doc register, .wrap, .badge, .stats, .cards,
.term, .callout, table.res, .pipe) — unused by the runtime pages, which
render pixel-identically. CHART_CSS migrates to the same tokens (it
lands in the same document after the shell <style>, so :root resolves).
CLAUDE.md gains the binding '## HTML surfaces' rule: every HTML surface
embeds this asset; extend, never fork.
Gates: suite 1043/0, clippy -D warnings clean, doc build 0 warnings;
regenerated chart page resolves all 17 used var() names against its
:root. Independent CSS audit passed (two cosmetic notes: --bg3/--orange
currently unused; the pre-existing html,body height:100% also reaches
future .aura-doc pages).
closes#209
Pure byte-preserving extraction: the CSS block inside SHELL_HEAD moves
verbatim into crates/aura-cli/assets/aura.css and is spliced back via
concat!(.., include_str!(..), ..). Proven against a pre-change baseline:
chart HTML (aura chart 42edebd2-0/597d719b-GER40-w0) and graph HTML
(bare aura graph) regenerate sha256-identical (bcc2cc0f.., a0e6a97f..),
each deterministic across two generations. Suite 1043/0.
First half of the style pin: the asset becomes the single source the
runtime pages embed; tokens + component library follow separately.
refs #209
Hardens the families-comparison chart page (#107) so it is openable and legible on
real multi-year data. Two halves, both confined to the CLI render path (engine +
registry untouched, C14):
#108 — serve-time min-max decimation. A pure `decimate(ChartData, buckets)`
transform partitions the shared union-ts spine into <=~2000 buckets and emits each
series' per-bucket min+max (nulls preserved), bounding the served page to a few
thousand points regardless of the underlying M1 point count. Applied in emit_chart
on both the single-run and family paths; a no-op under budget (every existing
fixture). Full recorded data stays on disk; only the page is thinned. For a
walk-forward family the null-fill blow-up collapses for free (an all-null bucket
stays null). Deterministic (C1).
#102 — a run-context header. A `ChartMeta` (name/commit/window/broker/seed/taps,
+ member count for a family, + bound params for a single run) is built from the
RunManifest in build_chart_data / build_comparison_chart_data (which gain a `name`
arg), injected into window.AURA_TRACES.meta, and rendered by a new pure buildHeader
in chart-viewer.js (headless .mjs-guarded). The family window is the SPAN across
members (min from, max to), not the first member's window — the only reading that
labels a disjoint walk-forward family's true OOS coverage (it collapses to the
shared window for sweep/MC). Reuses the existing render_value for param display
(no new Scalar Display, keeping C7's tag-only param plane). The earlier
"manifest is NOT carried into the page" render pin is flipped to a positive one.
Verified: cargo test --workspace = 446 passed / 0 failed; cargo clippy --workspace
--all-targets -D warnings clean. New coverage: 5 decimate unit tests, single-run +
family meta wiring (incl. the span-window invariant), a buildHeader headless guard,
and two end-to-end cli_run tests pinning the served-page meta at the binary boundary.
closes#108closes#102
Keyboard control for the served chart, deliberately the discrete counterpart to the
glitchy hand-rolled pointer drag that was just removed: each key is one clean
setScale("x", …), deterministic, with none of uPlot's pointer-pan jank.
- arrows pan (15% of the visible span), +/- zoom, 0/Home reset, x toggles the spine.
- zoom anchors on the CURSOR: the x-value under the mouse keeps its relative position,
so the point under the pointer stays put while zooming (centre when the mouse is off
the chart). The mouse position is tracked per chart via posToVal on mousemove.
- keys drive every chart instance together, so panels stay x-aligned.
- uPlot's default mouse (drag = box-zoom, double-click = reset) is retained — you have
both.
The load-bearing math is the pure keyXRange(key, lo, hi, anchor, ext) helper (the rest
is browser-only DOM wiring in mount); it is node-guarded by chart_viewer_keys.mjs, which
pins the zoom-toward-cursor invariant (anchor keeps its relative position) with an
off-centre anchor so a centre-zoom regression fails loudly. All five chart guards green.
refs #103
The hand-rolled wheel-zoom + drag-pan (wheelZoomPlugin) was hakelig/glitchy —
uPlot is not built to be driven that way. Remove the plugin and the cursor.drag
override so uPlot's own defaults govern the mouse: drag = box-zoom on x,
double-click = reset to full range, with the legend value-readout and crosshair
unchanged.
Everything else from the Tier-1 pass stays: the ordinal (gap-collapsed) x-axis
default + continuous toggle, the ordinal-label honesty (ticks/legend report the
real xs[i]), and panel cursor-sync (cursor.sync key retained; only the drag
override and the plugin are dropped). The x-mode guard is flipped to pin the
revert — overlay carries no custom plugin and no cursor.drag override, panels
carry no plugin — and stays green alongside the other three chart guards.
refs #103
The served trace chart's x-axis no longer plots against raw timestamps by
default — non-trading gaps (nights, weekends) left horizontal blanks that
dominated the view. The x spine is now ordinal by default: every recorded slot
sits at an even position, so gaps collapse and the signal fills the width. A
header toggle flips to continuous (real-time-proportional) spacing and back;
default ordinal honours the requested "x-axis should not be continuous", with
continuous as the one-click option.
Comfort, all on the read/render side (the engine and the Rust serve contract
are untouched — window.AURA_TRACES still carries the real xs, the ordinal
indices are derived client-side):
- ordinal mode keeps the axis honest: ticks and the legend value-readout map a
collapsed index back to the real xs[i], never the index itself.
- wheel-zoom (x, cursor-anchored), drag-pan, double-click-reset on the plot
(uPlot's default drag-box-zoom is disabled so drag pans).
- panels share a cursor.sync key, so the crosshair lines up across stacked
panels.
Confined to chart-viewer.js (buildCharts gains an xMode param + a wheelZoomPlugin
factory; mount re-renders on the toggle) and render.rs (CHART_HEAD toggle button
+ a chart-only style). The two twin node guards (build/gaps) re-point to the
ordinal default in lockstep; a new x-mode guard pins ordinal-default / continuous
/ panel-sync / plugin wiring, and a label-honesty guard (gappy-traces fixture,
xs far from the index spine) pins that ordinal ticks report the real timestamp.
Verified: cargo test --workspace green (incl. the four chart guards + render
inline tests), clippy --all-targets -D warnings clean, e2e (aura run --trace +
aura chart) emits a self-contained page defaulting to ordinal with the toggle.
Spec docs/specs/0057, plan docs/plans/0057 (boss-signed; grounding-check PASS).
Derived-fork decision log in the issue comments.
closes#103
Iteration 2 (serve half) of the visual face — spec 0056 / plan 0056:
read a persisted run's traces and serve them as a self-contained uPlot
HTML chart. Completes the goal "tap data from a graph, serve it as a
chart in the browser".
- chart-viewer.js (first-party): a pure buildCharts(traces, mode) that
maps the injected window.AURA_TRACES to uPlot configs (no DOM) — overlay
= one plot, every series on its own y-scale over the shared xs; panels =
one plot per series, all on the same timestamp x. A browser-only mount()
instantiates the vendored global uPlot. Guarded by a node .mjs DOM test
(+ a sparse/gaps variant) shelling out exactly like viewer_dot.rs.
- render_chart_html + ChartMode/ChartData/Series (aura-cli/render.rs):
mirrors render_html — self-contained page, uPlot (1.6.32, vendored
d534f10) + chart-viewer.js inlined via include_str!, data injected as
window.AURA_TRACES.
- emit_chart + build_chart_data (aura-cli/main.rs): the spec-§6 3-step
union-spine alignment — xs = sorted-dedup union of every tap's ts; a
synthetic empty-payload spine + ALL taps as symmetric join_on_ts sides
(no tap privileged, no point dropped); flatten each (tap,column) to a
Series of Option<f64>. New arms `aura chart <name> [--panels]`; a
missing run is stderr + exit 2 (TraceStoreError::NotFound), never a
panic. USAGE advertises the verb in lockstep.
Verified by the orchestrator: `cargo test --workspace` green (incl. the
node guards, render_chart_html, and the chart e2e); `cargo clippy
--workspace --all-targets -D warnings` exit 0; and a real end-to-end —
`aura run --trace demo && aura chart demo` emits a 57KB self-contained
page (doctype + inlined uPlot + AURA_TRACES carrying the equity/exposure
series), `--panels` reflects the panels mode, `aura chart nope` exits 2.
Implementer deviation folded in (compiler-prescribed): serde added to
aura-cli/Cargo.toml for the Series derive (Cargo.lock updated).
refs #101
Vendors uPlot.iife.min.js (the IIFE bundle exposing the global `uPlot`) + uPlot.min.css under assets/, pinned at uplot@1.6.32 via unpkg, mirroring the existing Graphviz-WASM/pan-zoom vendoring (checked in verbatim so include_str! + the build stay hermetic/offline, C1/C8). refresh-assets.sh gains the matching pinned-fetch lines. Consumed by iteration 2's render_chart_html (serve half of spec 0056).
refs #101
A node built with `.bind(slot, value)` fixes a declared param to a structural
constant: the slot correctly leaves the tunable surface (param_space / sweep axes),
but it also vanished from the RENDERED signature, because prim_record emitted only
schema.params. The cycle-0036 `blend` (a LinComb(3) with weights[2] bound to 0.5)
rendered `LinComb[weights[0], weights[1]]` — a 2-arity signature over a 3-port box,
with the fixed 0.5 invisible. The signature misrepresented the node.
bind now ANNOTATES instead of erasing. All slots are shown; the bound one renders
`name=value`, dimmed. The blend renders:
blend: LinComb[weights[0], weights[1], weights[2]=0.5]
Structurally a twin of cycle 0035's instance-name thread (commit 0ae8320): a
conditional field threaded engine -> model -> viewer.
- aura-core: a `BoundParam { pos, name, kind, value }` recorded by bind alongside
the unchanged closure capture, plus a `bound_params()` accessor (twin of
instance_name()). `pos` is the slot's ORIGINAL pre-bind position (the compressed
index is mapped back over earlier-bound positions), so the render is faithful for
any bind pattern, not just a trailing one.
- aura-engine: a conditional `"bound"` field in prim_record (present only when the
node has binds, mirroring the conditional "name"), each entry [pos,"name","kind",
"value"] via a new scalar_str helper (f64 via {:?} — keeps a decimal point so a
bound f64 never reads as an i64).
- graph-viewer.js: adaptNodes/genDot carry `bound`; cellLabel merges free + bound
params back into slot order by position and renders the bound slot dimmed
(reusing the 0035 separator grey #9399b2).
Render notation settled with the user (issue #63, reconciliation comment): keep the
[...] convention and name=value (not parens, not positional value-only).
Render/debug surface only: dropped at lowering (C23 — bind still resolves the name
to a fixed position and the compilat is unchanged), model stays deterministic (C14
— the inline no-bind golden is byte-unchanged; only the sample fixture's blend node
gains "bound"). The tunable surface is untouched: the eight-param sweep pins stay
byte-identical (C12/C19). New unit tests pin the recorded original position and the
conditional model field; a new headless render guard pins the dimmed name=value
render and slot-order faithfulness for both a trailing and a non-trailing bind.
Verified: cargo build/test (0 failed) + clippy -D warnings (0) all green.
closes#63
A leaf primitive built with `.named("fast")` now renders its `aura graph` viewer
box head as `fast: SMA[length]` — the instance name as a `:` declaration prefix.
An unnamed leaf keeps the bare `SMA[length]`.
Engine half: a new raw `PrimitiveBuilder::instance_name() -> Option<&str>` (the
explicit name, default not resolved) feeds a conditional leading `"name"` field
in prim_record, present only for an explicitly-named node; both golden twins
(inline model_golden + sample-model.json) re-captured. Viewer half: adaptNodes
carries `name`, the genDot leaf-emit forwards it, and cellLabel prepends the
`name: ` prefix when present (composites stay bare). `named()`'s non-empty
debug_assert is unchanged, its doc re-grounded to the now load-bearing Some/None
invariant (knob-address segment + prefix switch).
The name is a render/model-only debug symbol — dropped at lowering (C23), and the
model stays deterministic (C14). Parameter ganging (one knob, several nodes) was
considered and spun off as an explicit composite-shared-param idea (#61), not via
name collision (param_space is injective, C12/C19).
closes#58
The viewer box head built the param signature in round parens — SMA(length) —
which reads as a function call. Switch the brackets to square — SMA[length] — so
the head reads as parametrisation, not invocation. cellLabel render-only change
in graph-viewer.js; the JSON model surface and both goldens are untouched.
Observed bug in the graph viewer shipped in 66dff88: clicking `[+]` to
inline-expand a composite in `aura graph`'s HTML output renders a broken graph —
the interior nodes' edges collapse onto a single phantom node "0" with uncoloured
arrows, and the real pin docking is lost. The collapsed view and the body-drill
view both render correctly; only inline-expand breaks.
Root cause: in graph-viewer.js, genDot's `build` forms a node id by path-joining
the model keys (`cid = cpath.join("__")`). The aura model keys interior nodes by
numeric index (C23), so an inline-expanded composite yields ids like `0__0`. A
DOT identifier that begins with a digit but is not a pure numeral is invalid —
Graphviz parses `0__0` as the numeral `0` plus a leftover token, collapsing
`0__0`/`0__1`/`0__2` onto one phantom node `0`. The collapsed view survives only
because its ids are single-digit numerals (accidentally valid); the prototype
survived because it used name keys, never digit-prefixed ones. The bug surfaced
only against the real index-keyed model.
Fix: letter-prefix the id (`cid = "n" + cpath.join("__")`) so every id is a valid
identifier by construction. The fix lives in the viewer (DOT-syntax is its
responsibility), not in model_to_json — the model's index keys are correct, and
leaking the Graphviz identifier constraint into the model would be a leaky
abstraction.
RED-first guard (this establishes the project's first JS test infra, since the
viewer now carries real logic — normalizeModel + genDot — that the model golden
does not cover):
- tests/viewer_dot_ids.mjs: a headless node guard that loads the real viewer
module, discovers the expandable composites from a collapsed pass, inline-
expands them, and asserts every node id in the produced DOT is a valid Graphviz
identifier (quoted | pure numeral | bare identifier). Version-independent — it
checks the identifier grammar, not a render. The expand keys are DISCOVERED via
genDot's `expandable`, never hard-coded, so the guard cannot go vacuously green
when the fix reshapes the id (a hard-coded "0" key would stop matching "n0" and
silently test only the collapsed view — a false-green this guard refuses).
- tests/viewer_dot.rs: a Rust integration test that shells out to `node`,
wiring the guard into `cargo test --workspace`. `node` is required: if it is
absent the test fails (a skipped guard is not a guard).
- tests/fixtures/sample-model.json: the triggering fixture (numeric index keys,
a nested composite).
- graph-viewer.js: made node-loadable (typeof window/document guards + a
module.exports) so the guard can exercise the pure generator headless. This is
a test-enabler, behaviour-neutral in the browser — verified by the existing
render_html / graph_emits self-containment tests staying green and by the
expand re-rendering correctly through the vendored WASM-Graphviz.
Verified RED against the unfixed viewer (the guard trips on `0__0`/`0__1`/`0__2`
and the Rust test fails), GREEN after the prefix; full `cargo test --workspace`
green; clippy clean. Rendered the expanded state through the vendored
WASM-Graphviz to confirm the interior wires up correctly (price -> both SMA
series, SMA value -> Sub lhs/rhs, Sub -> signal, all f64-blue).
Iteration 2 of cycle 0026 (graph render redesign). `aura graph` no longer emits
ASCII: it now prints one self-contained `.html` to stdout — the ported prototype
pin-graph viewer (drill / inline-expand / styled tooltips / breadcrumb) driven by
the deterministic model serializer that shipped in iteration 1, with layout and
SVG done in-browser by Graphviz compiled to WebAssembly. Closes the redesign
opened by spec 0026; unblocked by cycle 0027 (input ports are now named, so the
viewer labels every input pin from the model's real names instead of inventing
"a"/"b").
What ships:
- crates/aura-cli/assets/: the ported graph-viewer.js (prototype genDot/chrome
verbatim + a normalizeModel adapter mapping aura's real model tuple shape —
ins = [kind, firing, name], index node keys, `comp` refs, `src_<role>` — into
the viewer's native shape), plus the vendored Graphviz-WASM (@viz-js/viz@3.7.0)
and svg-pan-zoom@3.6.1 blobs and a refresh-assets.sh provenance script.
- crates/aura-cli/src/render.rs: render_html(&Composite) -> String, a read-only
(C9) assembly — model_to_json + include_str! of the inlined assets, no eval,
no build, no serde (C14). The `["graph"]` arm calls it.
- Retired: the ascii-dag adapter (graph.rs), the `ascii-dag` dependency, the
`--compiled`/`--macd` graph flag plumbing, render_compiled, the color/terminal
plumbing, and the 12 ascii-dag-asserting tests + the now-orphaned helpers.
The cli_run integration test now pins the HTML page envelope.
- crates/aura-core/src/node.rs: the two last ascii-dag prose justifications
re-grounded (single-line label rule kept, re-justified generically; the
param-generic rule re-justified on C23, not on a renderer limitation).
- docs/design/INDEX.md: the cycle-0026 C9 realization note (both iterations).
Vendoring decision (spec deferred it to the plan): the WASM/JS blobs are checked
in, not fetched at build time. include_str! needs them at compile time, and a
build-time unpkg fetch would make the build non-hermetic/non-offline and let the
shipped artifact drift with the registry — against C1 (determinism) and C8
(frozen artifacts). ~1.4 MB is the price of a hermetic, frozen render asset.
Three adaptations beyond the plan, each verified: (1) render.rs imports
`aura_engine::Composite` (the path model_to_json takes), not aura_core; (2)
macd_blueprint is now test-only — removing the `--macd` arm left it used solely
by the param-space test, so it took `#[cfg(test)]` rather than removal or an
`#[allow]` suppression (the production `aura run --macd` path is intact, verified
emitting JSON); (3) the `grep ascii-dag` over crates/ matches only the new
contract test, which names the term deliberately to document the retirement — no
stale justification prose remains.
Invariants held (verified independently, not on agent report): C9 (render path
read-only), C10 (viewer is a render asset, no logic/DSL), C4 (four-colour palette
= the four scalar base types), C14 (no serde). The iteration-1 model byte golden
is unchanged and green. cargo build --workspace: 0 errors. cargo test --workspace:
157 passed, 0 failed (incl. the two new HTML tests + the unchanged model_golden).
cargo clippy --workspace --all-targets -- -D warnings: clean. ascii-dag absent
from `cargo tree -p aura-cli`.
closes#51
Brummel