Skip to content

ALS: Trace, Correlation and Waveform on one workbench - #208

Draft
YektaY wants to merge 153 commits into
mainfrom
yektay/als-main-catchup
Draft

YektaY wants to merge 153 commits into
mainfrom
yektay/als-main-catchup

Conversation

@YektaY

@YektaY YektaY commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

The single PR that takes the ALS change set into main: Trace moves onto a shared workbench, and Correlation and Waveform join it as two more tools in the same build.

It replaces #159–#170. Those stay open, unchanged, as the review record, and are closed with a link here once this merges. Fixes from their reviews land here as further commits. Merge with a merge commit, not a squash, so the stack's history is kept.

What's in it

The ALS stack, as reviewed:

PR What
#159 Carbon compiled from Sass, self-hosted IBM Plex, no CDN URLs in dist
#160 Canopy SDK adoption (the pin moves to the coming SDK release)
#161 Host contract for running Trace inside a workspace; same-origin requests
#162 Schema-driven tool layout and one properties pane
#163 Plot interaction core and drawing tools
#164 Shared statistics library and panel
#165 Guards for chrome literals and module boundaries
#166 Trace on the workbench, with its plot model, docs and browser tests
#167 Correlation
#168 Waveform
#169 Three pages in one build, cross-tool specs and docs
#170 No install scripts for any registry dependency

Main's features and fixes from after the stack was cut, merged in and ported:

Commit What
1847ec9 Merge main (c948b8b), measured from the stack's own base (09165ab). The message lists every resolution.
b8e0eab #187: declare dimensions on the typed-array line series
c7bbad3 #179: Trace's plot draws with CanopyChart, with the per-chart capture registry
561d107 The curve card's diagnostics and status labels come back; friendly archive errors; archive retry split by error code
630aaa8 #131 / #184: Autoscroll, re-picking the range or re-committing the span resumes following; a pan still queued is dropped
6dc2786 A socket blip no longer blanks slow PVs: the break is drawn at the disconnect time, and a Vole backfill covers it
006bccc Error boundaries on the Signals and Properties panes; #183's e-log capture tests
87fe851 Search PVs (bulk add), the config store dialog and ?config= links, the header's product name and Live/Archive counter
a9c27c8 Simulated PV, archiver and facility names in examples, placeholders and tests
11f2dca User guide and workbench docs for the workbench Trace

Base path: with VITE_CANOPY_BASE_PATH unset, Canopy is at the site root at any page depth, as on main. The layout with Canopy's modules beside trace/ is opt-in with VITE_CANOPY_BASE_PATH=... The dev proxy treats .. as unset.

Checked locally (at 11f2dca)

  • pnpm test: all 281 test files pass, with the SDK packages installed from local builds.
  • pnpm typecheck, pnpm lint and prettier are clean.
  • pnpm build and the dist check pass.
  • Playwright: 191 tests pass.
  • In the browser against a local Canopy stack: live and archive plots, fullscreen and Escape, the theme toggle, a narrow window, the Correlation and Waveform pages, and stopping and restarting the Canopy API while plotting live.

Before this leaves draft

YektaY and others added 30 commits October 15, 2026 22:41
Map the @slaclab scope to npm.pkg.github.com in a committed .npmrc (no
token), and give the Test and Lint workflows read access to GitHub
Packages: packages: read, setup-node registry-url and scope, and
NODE_AUTH_TOKEN from GITHUB_TOKEN on install.

The README documents the read:packages PAT developers need in
~/.npmrc, and the per-package Actions access grant that CI relies on.

No @slaclab dependency is added yet; #86, #87 and #88 build on this.
Replace trace's own color-mode store with the shared one from
@slaclab/canopy-shell 0.2:

- main.tsx configures it with the existing trace.theme key and the dark
  default, so users keep their choice, and paints <html> before the
  first render. It also loads the shell's CSS after Carbon's.
- App renders ColorModeTheme: g10 in light mode and g100 (not g90) in
  dark mode. The detached plot and Data Insight windows use it too, and
  DetachedWindow copies the Carbon theme class to the popup's <html>.
- The hard-coded body background is gone; Carbon's theme class on
  <html> paints it, and index.html starts dark (g100) to avoid a white
  first paint.
- Workspace import calls the store's setColorMode directly.

The SDK store reads localStorage lazily and guarded, so the jsdom tests
no longer need --no-experimental-webstorage on Node 26.
The header is now the SLAC standard AppHeader, rendered by a small
TraceHeader component:

- "SLAC Trace" in brand red, following the page theme instead of a
  forced g100 bar
- trace's actions first, then the standard theme toggle (Sun/Moon, with
  the Alt/Option+T hint), "Report a bug" and "Docs"
- the live/archive counts in the middle slot, still right-aligned
- in-flow (not fixed), with the skip link pointing at the panel group,
  which is now #main-content

Toolbar keeps only trace's own actions. The local header CSS rules go
away, since canopy-shell's styles cover them; the 0.04em letter-spacing
is dropped to match react-squirrel and react-badger.

Tests cover the header's name, action order, e-log action, theme toggle
persistence and the bug/docs links. The jsdom helpers for Carbon and an
in-memory localStorage live in src/test/dom.ts.
A render error (or an ECharts setOption error) in one panel used to
unmount the whole app and leave a blank page. The layers panel, the
plot area, the docked Data Insight tool and the properties panel now
each sit in an ErrorBoundary. A crash shows the standard fallback,
with "Try again" and "Reload", in that panel only. TraceApp's state
lives above the boundaries, so "Try again" keeps the workspace.

Each boundary also resets when its context changes: the active plot,
the view mode, the inspected PV or the selection.
Add @slaclab/canopy-client and @slaclab/canopy-react 0.2 as dependencies
and @slaclab/canopy-vite 0.2 as a dev dependency.

src/api/connection.ts now defines the one CanopyConnection (the
VITE_CANOPY_BASE_PATH prefix, or '' for per-module paths). client.ts,
mole.ts and types.ts become thin shims over the SDK with their old
signatures, so every REST call already goes through the SDK's
canopyFetch and its error mapping (FastAPI 422 bodies become a readable
validation_error instead of "[object Object]") without touching call
sites. time.ts re-exports the SDK's nowNs/msToNs/nsToMs and keeps its
range parsing.

Part of #86.
vite.config.ts builds its proxy with @slaclab/canopy-vite instead of the
hand-written /mole, /hare, /fox and /elog blocks. It forwards REST and
WebSocket traffic and injects X-API-Key (and the e-log token)
server-side as before. It also refuses cross-origin browser requests,
drops cookies, and matches prefixes only on a path-segment boundary.

The layout follows VITE_CANOPY_BASE_PATH, the same setting the bundle
uses: unset, the per-module paths are forwarded unchanged; set (the
deployed /trace/api/canopy layout), that one prefix is proxied and
stripped, like the container's nginx. canopyProxyOptions() holds that
mapping and has a test.

package.json declares "type": "module": canopy-vite is ESM-only, and a
CommonJS-loaded vite.config.ts can't require it. eslint.config.js was
already ESM.

.env.example and the README describe the per-module key scope and the
cross-origin refusal.

Part of #86.
Trace keeps alarm severity as the wire string. Mole samples, Fox
results, the Data Insight table, the right panel's colours and the
CSV/MAT exports already use it, and it is the SDK's WireAlarmSeverity.
liveStore now uses that type.

The SDK's PV services report the numeric AlarmSeverity, which adds
DISCONNECTED. toWireSeverity() converts it at the boundary, mapping
DISCONNECTED to null because it is a connection state, not an alarm.
The live store uses it from the next commit.

Part of #86.
Plots now take their colors from @slaclab/canopy-charts instead of the
local g90-era chart theme:

- useChartTheme() follows the shared canopy-shell color mode and gives
  the Carbon g10/g100 token values.
- The option starts from baseChartOption(): animation off, IBM Plex
  Sans, and the shared axis, tooltip, axis-pointer and legend styling.
- Each axis spreads chartAxisStyle(). Trace keeps its own grid, axis
  layout, font sizes, gridline style and opacity, tooltip content and
  legend placement on top.
- The light chart background is now g10 #f4f4f4 (was #ffffff). The
  dark tokens move to g100: axis lines #6f6f6f, axis names and
  crosshair #a8a8a8, tooltip border #525252.

The "follow the theme vs user override" rule for plot backgrounds stays
in the app, in plotBackground.ts. It treats #161616, #f4f4f4 and the
old #ffffff default as theme defaults. Print, PNG export and e-log
captures use the same chart theme backgrounds.
liveStore no longer runs its own WebSocket. The SDK's HarePVService (on
the shared ResilientSocket) now owns the connection: capped-backoff
reconnect, resubscribe on reconnect, and a ping every 15 s that drops a
socket silent for 10 s. Trace keeps what is its own: per-trace
retention, the numeric ring buffers the charts draw, refcounting (one
Hare subscription per PV however many traces watch it), and ref-stable
snapshots.

Behaviour notes:
- Only connected numeric updates enter the buffer. The service reports
  a dropped socket as a DISCONNECTED update carrying the last value,
  and maps a disconnected PV's null to 0; neither may become a sample.
- Severity comes through toWireSeverity(), so points and entries keep
  the wire strings.
- The socket closes when the last live trace is released, and the next
  watch() opens it again, matching the old "no reconnect while idle".
- The service is built on the first watch(). Its URL is
  toWsUrl(connection.baseUrl, '/hare/v1/ws/pvs'), resolved against the
  page.
- `latest` is the SDK's PVData. Nothing outside useLiveSeries reads it.

The tests drive the store through the SDK's createFakeWebSocketFactory
instead of a hand-rolled MockWebSocket. New cases cover disconnect
updates, ping timeout, idle close, factory failure and URL resolution.

src/api/hare.ts and trace's Hare wire types are gone.

Part of #86.
Swap PlotArea's local formatAxisTick and formatTooltipValue for the
shared canopy-charts versions.

- Axis ticks are unchanged: exponential below 1e-3 and at or above
  1e6, otherwise the default number string.
- Tooltip values and the crosshair y readout now use formatValue, which
  keeps 7 significant digits but trims trailing zeros: 0.5 instead of
  0.5000000, and 1.234568e-5 instead of 1.2346e-5 (the exponential form
  now also shows 7 digits).

Tests pin the tick formatter and the tooltip output.
main.tsx wraps the app in @slaclab/canopy-react's CanopyProvider with
the shared connection. usePVSearch, ArchiverPicker and TraceApp's
unit-axis lookup read it with useCanopyConnection() and call the SDK's
searchPVs, listArchivers and fetchMetadata directly. Before, the
module-level BASE decided where those calls went.

The module-level stores (archiveStore, liveStore) still import the
same connection object, because they live outside React.

usePVSearch has a test that renders the hook under a provider whose
connection uses the SDK's createFakeFetch.

Part of #86.
Print, Export PNG and the e-log capture now go through canopy-charts'
captureChartPng, and data: URLs are decoded with its dataUrlToBlob.

- capturePlot.ts keeps trace's DOM lookup, which prefers the fullscreen
  copy and skips detached plots. The capture itself is captureChartPng
  with the plot's effective background at pixel ratio 2. It returns
  null instead of throwing for a disposed chart or an ECharts error.
- capturePlots (e-log) uses the same helper and skips any plot that
  yields no image. The local dataUrlToBlob copy is gone.
- downloadDataUrl decodes with dataUrlToBlob instead of fetch()ing the
  data: URL, still downloading through a blob: URL.

Tests cover the fullscreen preference, the theme and custom
backgrounds, pixel ratio 2, and skipping empty or throwing captures.
The SDK has Fox's live-formula WebSocket (FoxFormulaService) but no
helpers for its REST validate and evaluate endpoints, so those stay in
src/api/fox.ts. They now call the SDK's canopyFetch with an explicit
connection and use its FormulaSpec and FormulaResultDTO types.
FormulaValidationDTO, which the SDK lacks, moves into fox.ts.

The formula editor's validation (RightPanel) and useFormulaSeries read
the connection with useCanopyConnection(). A FastAPI 422 from validate
now reads as a readable message in the editor, not "[object Object]".

formulaWsUrl() is removed; nothing used it. Live formula curves on
FoxFormulaService are left for a follow-up, because trace has no
live-formula path to port yet.

Part of #86.
archiveStore and useInsightData import fetchData, fetchMetadata,
CanopyError and the Mole DTO types from @slaclab/canopy-client. Severity
is now WireAlarmSeverity. archiveStore passes the shared connection (it
lives outside React); useInsightData reads it with
useCanopyConnection(). Only imports and call sites change in those
files.

src/api/mole.ts, src/api/types.ts and the shim's test are gone.
src/api/client.ts keeps only a CanopyError re-export for the e-log
client, which moves to its own package under a separate ticket.

This commit can be dropped if #93's PR lands first and conflicts. That
PR adds tests that import or mock ../api/mole, ../api/client and
../api/types, so the shims have to stay until those move too.

Part of #86.
docker/Dockerfile now copies the tokenless .npmrc next to the lockfile,
and mounts BuildKit secret "npmrc" as /root/.npmrc for the pnpm install
step only, so the token never lands in an image layer. Secret mounts
are optional by default, so a plain docker build without --secret still
works while there is no @slaclab dependency.

build-image.yml opts into the new swapps-ci-helpers npm-github-packages
input, which passes GITHUB_TOKEN npm auth as that secret. The helper is
pinned to the head of the draft swapps-ci-helpers#15 for now and needs
re-pinning to the release tag after it merges. The job's existing
packages: write grant covers the packages: read the image build needs.

The README's Registry access section covers the image build and the
local docker build --secret command.
Picks up b09012a from the updated base (#96): docker/Dockerfile copies the
tokenless .npmrc and mounts BuildKit secret "npmrc" for pnpm install only,
and build-image.yml opts into the shared helper's npm-github-packages input.
Without it the image build can't install the @slaclab/canopy-* packages this
branch adds.
.env.example advertised ELOG_TOKEN_HEADER, but canopyProxyOptions()
passed only ELOG_BASE_URL and ELOG_API_KEY to canopyDevProxy. loadEnv()
doesn't put .env values in process.env, so the SDK's own
process.env.ELOG_TOKEN_HEADER fallback never saw it, and the token went
out as x-vouch-idp-accesstoken regardless.

It is now passed as elog.accessTokenHeader. The SDK treats an empty
value as unset, so ELOG_TOKEN_HEADER= still gets the default header. The
README's e-log section mentions the setting.

Part of #86.
…in dist

Trace is served on networks without internet access. The precompiled
@carbon/styles CSS loads IBM Plex from IBM's CDN (s81c.com), so Carbon is
now compiled from Sass with its @font-face rules off (src/index.scss), and
the Plex faces Carbon declares come from @ibm/plex-sans and
@ibm/plex-mono, bundled under ./assets. main.tsx loads it before the
app's own CSS.

`pnpm build` runs check-dist afterwards, which fails on any IBM or Google
font host in dist/. A build plugin fails on a second copy of react,
react-dom or @carbon/react; resolve.dedupe and an @carbon/react alias keep
them single when a dependency (the @slaclab SDK packages) brings its own.
…bon-from-Sass PR (stacking base, no PR of its own)

A base for a stack of pull requests, not one itself. The SDK-adoption,
type-check, e-log and Formula Engine PRs branch from 7945aed, 84 commits
behind main, and are independent of one another (#101 contains #100,
#102 contains #96). This one merge puts them all on main, together with
the Carbon-from-Sass build PR, so the stacked PRs above it show only their
own change. Once these merge, the stack is rebased onto main.

Parents: ea89d17 main, 2f6f667 #101, 18e1c73 #102, 6e704c6 #128,
7c833fb #150, 7478c98 #151, ff97285 (Carbon from Sass, self-hosted Plex).

How the PRs meet main's newer code and one another:
- #101 on main's PlotArea refactor: useChartTheme, chartAxisStyle and
  the base options sit on main's memoised series, with hideOverlap and
  the INVALID-marker margin; the ErrorBoundary wrappers pass main's new
  props; TraceHeader takes main's docs URL.
- #102 on main's new code: archiveStore's injectable fetchData defaults
  to the SDK's fetchData(canopyConnection); useInsightData and
  useFormulaSeries (FormulaStore) read useCanopyConnection; users of
  api/types take the SDK types (WireAlarmSeverity, FormulaSpec,
  FetchDataParams); test mocks of ../api/mole mock the SDK module, and
  their call assertions shift by the connection argument; tests that
  render a component or hook reading useCanopyConnection wrap it in
  <CanopyProvider> (src/test/canopy.tsx, one fixed connection).
- #150 on #102: the e-log client calls the SDK's canopyFetch (client.ts
  and types.ts are gone; the e-log DTOs live in api/elog.ts), its test
  fakes are real Responses, and a 422 reads as the SDK's
  validation_error with field paths. vite.config keeps #102's
  canopyDevProxy and adds #150's app-scoped e-log route (its own key,
  the `..` check), listed first so it also wins under
  VITE_CANOPY_BASE_PATH; #102's direct elog-plus proxy options and
  their tests go, as #150 retires that setup.
- #151 on everything the others and main added: /fox paths become
  /formula-engine, api/fox becomes api/formulaEngine, and the prose
  follows.
- Carbon from Sass on #100: main.tsx loads index.scss, then the
  canopy-shell styles, then index.css.
All five @slaclab packages (client, react, shell, charts, vite) move from
0.2 to 0.3.1-als.1, pinned exactly. That build is the first to carry the
shell's host-theme API (useHostTheme, HOST_THEME_ID,
applyHostSheetFallback, useChartFont) that the embedding topics use; the
published 0.3.0 lacks it, so a ^0.3.0 range would resolve a release that
fails them. The pin moves to the upstream release that carries the API
once one is published.

0.3 renames the SDK's Fox symbols to FormulaEngine* and makes
FormulaSpec.expression optional (table formulas carry per-column
expressions); the one comment and the one test fake that relied on the old
shapes follow.
…-origin requests

- Sub-path gateway: without VITE_CANOPY_BASE_PATH the Canopy connection's
  base is the page's parent directory (Trace at /x/y/trace/ reaches
  /x/y/mole, /x/y/hare, /x/y/formula-engine; at the site root it stays the
  per-module paths). It is read at each request.
- Same origin only: the connection's fetch refuses any URL that resolves
  outside window.location.origin (an absolute VITE_CANOPY_BASE_PATH, a
  <base href> elsewhere), and leading slashes in the page path collapse.
- Message bridge: with ?embedded=true, same-origin visibility and theme
  messages from the parent, and a trace-ready handshake, installed before
  the first render by a bootstrap module every page entry imports. The
  bootstrap also fixes the stylesheet order (Carbon, the shell's styles,
  its host-contract sheet, the app's own) and applies the host-sheet
  fallback first.
- Host theme on the canopy-shell colour-mode store: embedded, the host's
  ?theme= id and its later theme messages set the store's mode under a
  key of their own, which each host message clears, so the host wins and
  the operator's standalone choice under trace.theme is never read or
  written. The root Carbon zone (and each detached window's) is the
  host-theme anchor; detached windows inherit the host marker and the
  opener's body colour.
- The per-plot autoscroll clock holds while the host hides Trace and
  nothing is detached, so live re-renders neither slide a window nor
  refetch.
- Test workers run without Node's own localStorage (Node >= 25 shadows
  jsdom's), and a test pins the shell's host-contract wiring against this
  app's Carbon.

E-log needs nothing here: since #150 its availability is Canopy's e-log
config, the same standalone and embedded.
A tool describes itself as a schema plus a binding (ToolDefinition); the
workbench renders the actions bar, the one-pane sidebar (cards above, plot-wide
sections below), the field controls with the modified dot and reset, the
right-click registry, and shortcuts bound from the actions themselves. A host
that draws the tool's tile bar (embedded=true&hostbar=1) gets the actions as
canopy:tool-actions and invokes them with canopy:tool-invoke.

src/pvSearch merges an optional host channel catalog with Mole search behind one
PV field. The old panels keep their own hook until Trace moves over.
src/plot is one gesture layer (wheel, pan, zoom box, axis drag), the time-window
and log-aware axis maths, the docked read-out, strip toggles and PNG overlay
composition, for any ECharts plot. src/annotations is the drawing core: a data
model, a tool catalog with seven built-in tools (one module per tool, checked by
makeCatalog), the overlay layer and rail, the drawing host any plot mounts, undo
history, and the plot= and ann= link codecs. Neither names a tool: each host
passes its catalog and x axis. Drawing colours are app data layered on the
canopy-charts theme, so they live in src/annotationTheme.ts (drawingThemeFor
/ useDrawingTheme key them by the colour mode), where isColorLiteral is the
one rule for a colour read from a link or a saved file.

Tests that need a real tool arrive with that tool.

A drawing with no width takes the width a new drawing gets (0.75) in links
and files alike; 1.5 gets its own link flag, `w1.5`, and the encoder no
longer writes `w.75`; the decoder still reads it.
A catalog-parameterised metric model, an expression parser with no eval, strip
history and histograms, and one panel and Properties tab for every plot tool.
The tests take Correlation's catalog as data, so they arrive with it.

Function and constant tables have no prototype and are tested with
Object.hasOwn, so a name like constructor or __proto__ is an unknown function
or variable; a metric that throws while evaluating costs its own cell, not
the table.

The charts take their colours from the canopy-charts theme (the dark g100
theme unless the host passes one).
The chrome-literal guard fails on a colour or font written as a literal in the
chrome files, so a host stylesheet can restyle everything; pnpm test runs it.
One eslint rule factory builds the import allow-lists that keep src/workbench,
src/plot and src/annotations free of tool code.
… and browser tests

The plot model and the Trace workbench depend on each other (the model drops
fields only the old panels read; the workbench reads the new fields), so they
land as one change.

Plot model:
Plot and trace fields stay optional and are stored only off their default, and
.trc.json stays schema 1, so old files and old readers keep working. Palettes
move from one per-user store to one per plot (a legacy key is still read on a
fresh tab). The live store records disconnects as breaks and changes retention
in place; automatic retention follows the plot's span. src/api/archiveErrors.ts
is the one mapping from archiver error codes to the "Not archived" text, used
by the archive store, the layers row and the plot notice. PVTrace.updateRate,
which nothing read, is gone, as is the keyboard shortcut hook the workbench's
action registry replaces.

The read-out tooltip is HTML: it escapes the value and names only the MINOR,
MAJOR and INVALID severities, as it escapes labels. A saved trace's sample
array is never read back from a file (it is regenerated at runtime).

relativeSpanFor writes a window's width back as a relative range, in seconds now
that spans accept them.

Not archived reads per code: archiver_not_configured reads "No archiver";
pv_not_found_in_archiver and pv_not_found read "Not archived". All three are
remembered without retry, and the plot's empty-archive notice names each PV
with its own code's text.

Workbench:
LeftPanel, RightPanel, Toolbar, PanelRail and usePVSearch are replaced by
src/tools/trace: a schema and binding on the workbench, with drawings and
statistics on every plot, gesture-driven view windows and right-click menus
from one registry.

TraceApp and PlotArea keep upstream's behaviour since the fork:
- the per-plot autoscroll clock, useFollowNow scrolling and freeze-at-displayed-
  end, with a pan, the Autoscroll toggle and a range pick as the transitions;
- INVALID samples break the line and get upstream's markers; our alarm tint
  covers MINOR and MAJOR only. Archive spacing gaps, live disconnect breaks and
  the stale-seam rule join them in components/traceGaps.ts;
- typed-array series data, reused across scroll frames;
- overlap hiding for time labels, instead of a second tick-spacing fix;
- Escape closes fullscreen, the pop-up blocked notice, add-plot selecting the
  new plot, the shared save timestamp, unit lookups aborted on load and unmount.
Upstream's panel fixes are ported to the fields: seconds spans and the 30 s to
15 min presets, the refresh-interval cap, formula help colour, "Not archived",
new axes expanded. Its Gridline Opacity slider fixes do not apply: that field is
a number input here. Upstream's panel-mounting tests are rewritten on a harness
that drives the real workbench.

plotOption.ts holds the pure option builder, shared with the Code tab; PlotArea
keeps the React mounting. src/embed adds the pv=/range=/plot= query grammar, the
debounced state write-back and cross-tool open.

Docs: upstream's Overview and User Guide stay; the nav gains the properties
panel, statistics and drawing pages, the user guide follows the workbench, and
its screenshots are retaken. Playwright (@playwright/test, a dev dependency)
runs the Trace specs on a new CI job,
without the @Perf specs, which need a quiet machine.

On the SDK adoption (#100, #101, #102), Canopy e-log (#150) and the Formula
Engine path (#151), this change takes their versions and carries onto the
workbench what they added to code it replaces:
- #100: the colour mode is the canopy-shell store; the actions bar's theme
  toggle flips it (it persists under trace.theme), detached windows take its
  Carbon theme, and an imported workspace sets it. The workbench's actions bar
  is the app's first row, so TraceHeader goes with the Toolbar it framed: its
  trace actions, theme toggle, bug report and Docs are actions in that bar.
  The plot canvas and the docked Data Insight Tool sit in ErrorBoundary as
  SLAC placed them.
- #101: chart colours are canopy-charts' (useChartTheme, chartThemeFor); the
  option builder starts from baseChartOption and chartAxisStyle and formats
  with formatValue and formatAxisTick. Each text slot names the family the
  chart's wrapper computes once it has loaded, so the chart redraws with the
  loaded face. Capture goes through captureChartPng, with the drawings composed
  on top, and attachments through dataUrlToBlob. effectiveBackground in
  src/plotBackground.ts takes an undefined (automatic) background, and the
  save writes a theme-default background as the current theme's.
- #102: every SDK call takes the connection: useCanopyConnection() in React
  (the formula editor's live validation), canopyConnection in the
  module-level schemas and menus (unit and metadata lookups). The live store's
  breaks and in-place retention are layered on HarePVService. The legend's
  live value shows a number as the SDK formats it (displayValue), which knows
  when a PV has no precision.
- #150: Post to E-Log, for Trace and the single-chart tools, follows Canopy's
  e-log config and preselects its logbook ids.
- #151: formula requests go to /formula-engine, and the browser-test mocks
  follow.
Drawing colours come from src/annotationTheme.ts, whose drawingThemeFor now
hands back one frozen theme per mode, so memos keyed on the theme hold across
renders as they did on the old constant themes. The visibility-pause test
commits React once per ten simulated seconds while hidden (no clock timer runs
then), so its cost no longer grows with host load.
A second page, correlation.html: one PV against others as a scatter or density
plot, fed by the Formula Engine's table formula, on the workbench with drawings and statistics.
One state writer and one link grammar with a 4 KB shed order. Saved-link and
canopy table fixtures are byte-pinned. Helpers Waveform also needs live in
src/tools/shared (record edits, Y colours, CSV with spreadsheet-formula
neutralising, chart images, query publishing, PV tracking). Statistics tests that
take this tool's metric catalog as data arrive here.

A c<i> colour from a page link must pass isColorLiteral (hex, rgb(), rgba()),
like drawing colours; anything else, named colours included, is dropped with
a warning. scripts/make_orm_fixture.py regenerates the synthetic seeded frame
the statistics oracle is checked against. The cross-catalog uniqueness test
arrives with Waveform, the last catalog it covers.

On the SDK adoption (#100, #102) and the Formula Engine path (#151): the page
takes its colour mode from the canopy-shell store and renders under
<CanopyProvider> with the app's connection, as Trace's page does. Its Hare and
Formula Engine services are built in src/tools/shared/canopyServices.ts from
that connection (toWsUrl, as the live store builds its socket) and keep
reconnecting after any close; formula sockets and the browser-test mocks use
/formula-engine, and the code's Fox names and texts read Formula Engine. Chart
and drawing colours come from canopy-charts and src/annotationTheme.ts.
A third page, waveform.html: array PVs drawn element by element, live, with a
reference and delta, persistence and averaging, and an X axis PV, on the
workbench with drawings and statistics. A pure model and a ring-buffered
controller behind one state writer; the link grammar is in docs/waveform.md.

A trace colour from a page link must pass isColorLiteral, like drawing
colours; anything else gives the curve its automatic colour. With Waveform
in place, one test pins every drawing catalog the app builds: unique kinds,
codes and keys, and no tool key on a reserved or plot-action shortcut.

On the SDK adoption (#100, #102): the page takes its colour mode from the
canopy-shell store and renders under <CanopyProvider> with the app's
connection; its Hare service is built from that connection by
src/tools/shared/canopyServices.ts. Post to E-Log follows Canopy's e-log
config (#150). Chart and drawing colours come from canopy-charts and
src/annotationTheme.ts, and the browser-test mocks use /formula-engine.
The build takes correlation.html and waveform.html as pages beside index.html;
the guard, the docs nav and the README pick up both tools. Browser specs that
run across the tools (host bar, host stylesheet smoke and styling, context menus,
plot gestures) arrive here.

On the new base: the page-root anchor tests take the canopy-shell colour-mode
store (#100), whose dark Carbon zone is g100, and render the tool pages under
a Canopy connection (#102); the cross-tool browser specs mock the Formula
Engine at /formula-engine (#151). The package is an ES module now,
so the host-probe loader makes its require from its own URL.
The links were hard-coded to a site feedback form and a docs address that
no longer exists. Read VITE_BUG_REPORT_URL and VITE_DOCS_URL the way main's
TraceHeader does since #182, defaulting to the public repo's issue chooser
and docs site, and expect those defaults in the host-bar e2e spec.
A double-click in a Trace plot (or on its time band) still resets every
axis, but time now goes back to the range the plot is set to ("Last
1 h", a custom range), re-applied as Reset view does: the zoom or pan
window is dropped and a relative range follows now again. Before, it
applied the span of everything loaded, which read as "Last 3605.774 s".

Tests changed to the decided rule (PlotArea.timeBand.test.tsx):
- "dblclick on a frozen, panned-back window applies the all-loaded span
  once" now expects the picked range;
- "dblclick with nothing loaded is a no-op" now expects the picked
  range re-applied.
As on main, a new Trace plot shows the crosshair, and the wire baseline
follows: PLOT_DEFAULTS.showCrosshair is true, so a plot= link writes the
crosshair only when it is off, and a link or .trc.json plot without the
key opens with it on (serialize.ts reads a missing key as on, as main
does). Both writers stamp the flag on every plot, so only files from
before the crosshair existed and stack links that left it out (meaning
off) read differently. The built-in value is in src/site/builtins.ts.

Tests changed to the decided rule:
- plotConfig.test.ts "crosshair and drag defaults" (541-574): the
  crosshair is on by default and written only when off;
- serialize.test.ts (533-534): a plot without the flag reads as on;
- annotations/__fixtures__/trace-wire.json: the eight recorded link
  plots (none of whose links carries the key) now decode with the
  crosshair on; every link's bytes are unchanged;
- schema.completeness.test.ts: the everything fixture sets the crosshair
  off, its non-default value now;
- this series' own site tests use crosshair off as their off-baseline
  value.
New pins: a new plot, a fresh link, a plot= link and a .trc.json plot
without the key all have the crosshair on. The user guide says so.
A new curve stamps no live retention: it follows the plot's span, at
most 1800 s, a curve's own value wins, and a saved per-curve value loads
(R9). It is not a site default. Tests only: the behaviour is already so.
As on main, Trace's data tooltip follows the cursor. Docking it in a
corner of the plot (dodging the cursor, moved by its grip) is a new
Display setting, Dock data tooltip, off by default. It rides in plot=
links and .trc.json files as dockReadout, written only when on, so an
older reader drops it and a link or file without it follows the cursor.
A pinned tooltip without the dock sits at the plot's top-right, as
before. The read-out grip is attached only while docked.

The site's tooltip choice now reaches Trace as the creation default of
the setting (built in: cursor, in src/site/builtins.ts), with a site dot
on the field. Correlation and Waveform keep the docked read-out.

Tests changed to the decided rule:
- schema/plot.test.tsx "orders Display ...": Dock data tooltip follows
  Pin data window in the L2 list;
- schema.completeness.test.ts: the everything fixture turns the new
  plot-class key on, off its default.
New tests pin the cursor-following default, the pinned and docked
positions, the key's link and file round trips, the site's creation
value and the dot. The user guide says so.
The user guide, drawing-tools and workbench pages now say what Trace
does after C2-C5 and C7: the wheel zooms time (Alt+wheel: time and the
Y axes), a Y-axis drag moves that axis (Shift+drag zooms it), a
double-click returns time to the plot's range, a new plot shows the
crosshair, and the data tooltip follows the cursor unless Dock data
tooltip is on. Correlation and Waveform are described as before, with a
pointer to the site defaults.
The cross-tool Open in writers (tools/contextMenu.ts) give Correlation
its PVs and the source plot's lookback. A lookback now counts like
Trace's range: a query carrying only PVs and a lookback opens with the
site's defaults, keeping the lookback it carries. Correlation's own
links also state the period, row count and view, so they still read at
the baseline.

New tests open each tool through the real writers (traceQueryFor,
correlationQueryFor, the pv= Waveform query) and pin that a static
server's SPA page in place of Canopy's settings is a quiet none.
Field labels (Color, Alarm coloring, Background color), the drawing style
panel's label, aria-label and title, the palette re-pick tooltip, the rms
help text and the Outline's move-canceled announcement now read in
American English. The tests that assert those strings follow.

Left alone: field ids and kinds ('colour', 'alarm-colouring'), the
LABELS key, data-testids, CSS classes, type/function/file names
(ColourSwatch), code comments, test titles and the stub tool fixture's
label, which is test-only.
The user and developer docs, README, CONTRIBUTING and the $comment text of
config.example.json now say color, behavior, center and centered.
Prettier realigned the tables whose cells changed width.

Left alone: config keys, link keys and code spans (none of them carries a
British spelling), and the out-of-scope src-tauri README and
scripts/check-chrome-literals.mjs.
The last user-facing "behaviour" outside src and docs.
ECharts 6 moves the grid by default (outerBoundsMode 'auto') so axis
labels stay inside the chart. Trace places the grid itself (plotLayout),
and its Y-axis hit-zones and drawing layer use the same numbers, so any
move put them out of step: with two left axes the drawn grid sat at 164
px against 150, and while a Y axis was panned its raw edge labels
(109.63855421686748) changed width every frame and slid the whole plot
back and forth. The axes and their names jittered, and a drag on the
second left axis could land on the wrong one. The drawing layer's 14 px
offset had the same cause.

The grid now stays put (outerBoundsMode 'none'), and an axis with a set
range rounds its labels to three decimals below its span's leading digit,
so a panned edge reads 109.6 and stays clear of the next axis.
The embedded tile wrote a query the serializer had kept under 4 KB, but on
reload the parser measured it after plotQuery re-encoded it through
URLSearchParams (`:,[]{}` became %XX) and after the browser's URL turned
`'` into %27, so a query near the limit came back over it and the plot
opened empty.

parseTraceQuery now measures the query as serializeTraceQuery writes it,
page keys left out, so nothing the writer produced is refused. A query
that is over the limit on arrival opens without its drawings when that
fits, else without its plot config, and is ignored whole only when its PVs
and range alone are over.
The card let a locked drawing be restyled, moved to another axis or
reshaped (Value, Extend), and a locked note be relabeled, although a
locked drawing keeps its look and place and a locked note keeps its text.

While a drawing is locked, Color, Width, Style, Axis and the tools' own
fields are disabled with the reason "Locked", and so is Label for a note.
Locked, Visible and Delete stay available.
The docs say a drawing can be right-clicked to edit, lock or delete it,
but a right-click on a drawing opened only the point menu, and one on its
card opened nothing.

The menu registry gains a drawing scope with Edit (select the drawing,
which opens its card), Lock / Unlock and Delete, headed by the drawing's
name. On the plot, the host opens it when the right-click hits a drawing
and writes through the plot's drawing document, one commit per change; on
a card, the Outline opens it for a row that is no signal, through writers
derived from the drawing card's own fields. Trace, Correlation and
Waveform all get it.
Correlation and Waveform say what to do next while a drawing tool is
armed ("Box: drag or click twice"); Trace's status line read a copy of the
drawing document whose tool was forced to the pointer, kept from before
the status line moved onto the drawing host, when Trace passed no tool.
Nothing depended on it, so the status line now reads the host itself.
Only the first plot of an embedded Trace tile is written to its URL, and
the status line has a notice for every other plot ("Drawings on this plot
are not saved in the tile"), but no plot mount passed its position or the
embedded flag, so the notice never showed.

Every SinglePlot mount (tab, grid, fullscreen, detached) now passes its
plot's position, and the plot reads the embedded flag once on mount.
"Add note here" added an empty note and left it there, while the docs say
a new note opens its text box, as placing one with the Note tool does.

The overlay handle gains editText, and the menu's add opens the new note's
text box through it, so the note is typed in place and Enter or leaving
the field keeps the text.
…ith a minus

An ink drawing's card handed the native color input the theme variable it
shows on the swatch (var(--cds-text-primary)), which the input rejects
with a console warning and shows as black. The swatch now gives the input
only #rrggbb values and, for any other value, resolves the color the
swatch shows when the picker opens.

A falling measurement's card name printed its Δ with a hyphen
("Δ-21.49"); it now uses the minus sign, as the readout does.
…cards

Describe the right-click menu of a drawing (Edit, Lock / Unlock, Delete)
on the plot and on its card, the card fields a lock disables, that Locked
and Visible are buttons on the card's head rather than fields, that Add
note here opens the note's text box, and what a tile link keeps and how an
over-long one opens. Describe the Measure cards of Correlation (Δx, Δy,
Δy/Δx, no Δ%) and Waveform (Δx, Δy, per-curve rows, no Δ%), and that
Shift-drag measures without picking the tool.
The input still took an empty value for a theme color until its picker
opened, and the browser warns on an empty value as on var(...). The
input is now uncontrolled for such a value, with no value until the
picker opens and sets the color the swatch shows.
The armed Measure tool's status-line hint read "shift-drag to measure",
but while it is armed a plain drag or two clicks place a measurement;
Shift-drag is the quick measure that needs no tool. The hint now reads
"Measure: drag or click twice", as the other two-point tools' do.
A note placed with the tool or added from the menu opens its text box;
Escape closed the box but left an empty note on the plot. Escape on a
note just added that still has no text now removes it, as one delete
commit, so undo brings it back. A note reopened with a double-click keeps
today's Escape: the draft is dropped and the note stays as it was.

The existing Escape test now expects the empty new note to be gone, and
still that no typed text is committed.
The drawing rail floats over the plot's left gutter, 2 to 32 px in, where
Trace draws its left Y axes' names; the outermost name sat about 5 px in,
under the rail, with one left axis or several.

While the rail is mounted, plotLayout widens the left gutter until that
name clears the rail's right edge (railMetrics.ts). SinglePlot passes the
same width to the option and to its own layout, so the hit-zones and the
drawn grid still agree. Without the rail (Drawing tools off, no drawing
writers, the Code tab) the grid keeps its old inset.
The color field keyed its input on the value's form, so the first edit of
a theme-colored drawing (its ink, a CSS variable, becoming a hex) replaced
the input and dropped keyboard focus out of the sidebar, and primary+Z
there no longer undid the edit. Three browser tests caught it.

The input is now one element throughout. A non-hex value gives it the
color the swatch is painted with, read back as #rrggbb after layout and
again when the picker opens, so the browser never sees a CSS variable.
With the drawing rail mounted, a one-axis plot's grid now starts at 115
px (the gutter keeps the axis name clear of the rail). The test aimed its
Y-axis Shift-drag at half the old 70 px inset, which now lands on the
rail's edge, so the stretch never started.
In grid view the drawing rail runs down each cell's left edge, 2 to 32 px
in (railMetrics.ts), and the cell's Fullscreen button, 8 px in, sat on
top of the rail's first button. Fullscreen now starts 8 px past the rail,
at 40 px, and Detach keeps its 12 px gap after it, at 76 px.
A PV that didn't change in the window gets one archive point: its last
value before the window, held at the window start (holdLastBefore). The
merge ran the archive up to its last sample and live after it, so on
every refetch that point stood in front of live's own value at the new
window start until the axis scrolled past it. Whenever the two disagreed,
the curve stepped at the left edge and autoscale jumped for a few frames
on each refresh: against a simulated live backend, QUAD:LI30:501:BCON's
archived -14.98 kG stood in front of a ±10 sine.

A raw archive answer of one point is now left out of the line and the
samples when live has a sample at or before it, since live has the value
there. A trace whose live buffer starts after the window start still
takes the held value up to live's first sample, and an archive with
samples in the window, or a binned one, merges as before.
A toggle row showed its name twice: in the label column, and beside the
switch, where Carbon prints a hideLabel Toggle's label. A toggle row now
has no label column. The switch starts at the row's edge, the modified
dot and reset end the row, and a note runs under both. Other kinds keep
the label column, since their controls don't name themselves. The label
element stays in the DOM (it is aria-hidden, visual only), hidden in the
panel.
…e rail

Display repeated three of the drawing rail's toggles: Data tooltip, Mouse
drag and Drawings. While the rail is shown they are now left to it.
Turning Drawing tools off lists them right after it, so they can still be
set with the rail hidden. The same in Trace, Correlation and Waveform.
Trace's Data tooltip moves from L1 to L2 to stand with the other two, as
Correlation's already did.

The schema and App tests list the three with the rail off, and the
Drawings tests check that the rail and Display agree across turning the
rail off and on. The user guide and the drawing tools page say where to
find them.
Carbon hides a toggle's real button and a checkbox's input as 1 px
absolute boxes. The pane's scroll container wasn't positioned, so they
were placed against the page: below it while the pane was scrolled, which
made the page taller than the window. Clicking a toggle focuses its
button, and the browser scrolled the whole page to show it, leaving an
empty band at the bottom under the shifted app. The root's overflow:
hidden doesn't stop a focus scroll.

The pane's scroll container is now positioned, so it holds them and a
click scrolls the pane. A browser test scrolls the pane, clicks Show
statistics low in it, and checks that the page didn't move; without the
fix the page scrolled 1026 px.
Without the drawing rail (Drawing tools off, the Code tab), a plot with
left Y axes kept the old 70 px left inset, which put the outermost axis
name 6 px past the plot's left edge, half cut off. The gutter now gives
that name the same room either way: it clears the rail's right edge while
the rail is shown, and the plot's left edge while it is not. One left
axis starts the grid at 83 px without the rail (115 px with it, as
before); a plot with no left axis keeps 70 px.

The SinglePlot fixtures that assumed the 70 px inset now take the grid
from plotLayout, or from constants that match it where the chart mock is
hoisted, and the gutter tests measure the drawn name against the plot's
edge without the rail.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants