Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
153 commits
Select commit Hold shift + click to select a range
a386198
Install @slaclab packages from GitHub Packages
YektaY Oct 16, 2026
8e78a62
Adopt canopy-shell color mode (g10/g100)
YektaY Oct 16, 2026
e339f1a
Replace the Trace header with canopy-shell AppHeader
YektaY Oct 16, 2026
e88786f
Wrap Trace panels in canopy-shell ErrorBoundary
YektaY Oct 16, 2026
35cfe9b
Route REST, Mole and time helpers through @slaclab/canopy-client
YektaY Oct 16, 2026
8da4af0
Replace the dev proxy blocks with canopyDevProxy
YektaY Oct 16, 2026
3caa169
Use the SDK's WireAlarmSeverity and map numeric severities to it
YektaY Oct 16, 2026
816495e
Theme Trace charts with canopy-charts (g10/g100)
YektaY Oct 16, 2026
d4fc2f9
Build the live store on HarePVService
YektaY Oct 16, 2026
0da5186
Use canopy-charts number formatters in plot axes and tooltips
YektaY Oct 16, 2026
21bef30
Provide the Canopy connection with CanopyProvider
YektaY Oct 16, 2026
2f6f667
Capture plot PNGs with canopy-charts
YektaY Oct 16, 2026
cf3d9e8
Run Fox validate/evaluate on the SDK core and types
YektaY Oct 16, 2026
be6b547
Remove the transitional api shims
YektaY Oct 16, 2026
b09012a
Give the container image build GitHub Packages auth
YektaY Oct 16, 2026
b43047e
Merge yektay/canopy-registry for the image build's registry auth
YektaY Oct 27, 2026
18e1c73
Forward ELOG_TOKEN_HEADER to the dev e-log proxy
YektaY Oct 27, 2026
ff97285
build: compile Carbon from Sass, self-host IBM Plex, refuse CDN URLs …
thellert Nov 3, 2026
09165ab
Merge main with the open PRs #101, #102, #128, #150, #151 and the Car…
thellert Nov 3, 2026
950d9c0
build: Canopy SDK 0.3.1-als.1
thellert Nov 3, 2026
e62e1ac
feat(embed): host contract for running Trace inside a workspace, same…
thellert Nov 3, 2026
051f28f
feat(workbench): schema-driven tool layout and one properties pane
thellert Oct 31, 2026
561f587
feat(plot): plot interaction core and drawing tools
thellert Nov 3, 2026
6a0a2c4
feat(statistics): shared metrics library and panel
thellert Oct 31, 2026
75e3594
build: guard chrome literals and module boundaries
thellert Oct 31, 2026
ea77161
feat(trace): move Trace onto the workbench, with its plot model, docs…
thellert Nov 4, 2026
44bb429
feat(correlation): Correlation tool
thellert Nov 4, 2026
0962b13
feat(waveform): Waveform tool
thellert Nov 4, 2026
75b1a8f
feat(tools): three pages in one build, cross-tool specs and docs
thellert Nov 4, 2026
261f79e
fix(tools): read the bug-report and docs links from the build
YektaY Nov 12, 2026
1847ec9
Merge main (c948b8b) into the ALS stack
YektaY Nov 18, 2026
b8e0eab
Port #187: declare dimensions on the typed-array line series
YektaY Nov 18, 2026
c7bbad3
Port #179: draw Trace's plot with CanopyChart
YektaY Nov 18, 2026
561d107
Restore the curve card's diagnostics and error labels (R12, R17, C10)
YektaY Nov 18, 2026
630aaa8
Port #131/#184: resume following without a stale pan landing
YektaY Nov 18, 2026
6dc2786
Fix R2: a socket blip no longer blanks slow PVs
YektaY Nov 18, 2026
006bccc
Port main's error boundaries to the workbench panes; #183 tests
YektaY Nov 18, 2026
87fe851
Port Search PVs, the config store and the header counter (B5)
YektaY Nov 18, 2026
a9c27c8
Use simulated names in examples, placeholders and tests
YektaY Nov 18, 2026
11f2dca
Docs: describe the workbench Trace after the main catch-up (B7)
YektaY Nov 18, 2026
7bf1e3e
build: deny install scripts for every registry dependency
thellert Oct 31, 2026
1a95741
Stop finiteIndices looping when a row has no joint columns
YektaY Nov 18, 2026
814071d
Bound expression depth so deep input fails with a compile error
YektaY Nov 18, 2026
c9ae0ae
Restore font-display: swap on the self-hosted IBM Plex faces
YektaY Nov 18, 2026
dca21b2
Fail the dist check when .woff fonts are bundled
YektaY Nov 18, 2026
bb4f233
Add the Greek subset to the self-hosted Plex Sans faces
YektaY Nov 18, 2026
a43d4cc
Scan the chrome literal guard's files by syntax, not as raw text
YektaY Nov 18, 2026
5953b1e
Make the chrome literal guard catch every colour form
YektaY Nov 18, 2026
914613e
Document the chrome literal guard in CONTRIBUTING.md
YektaY Nov 18, 2026
79be9a1
Accept "not a style literal" as a literal-guard exemption reason
YektaY Nov 18, 2026
a9cf41e
Fit the properties panel's action buttons to the card
YektaY Nov 18, 2026
60f3cd1
Keep a press inside the note editor from closing it
YektaY Nov 18, 2026
768a93c
Make the read-out grip's hover tracking cheap
YektaY Nov 18, 2026
33ccc50
Move drawings in each axis's own scale
YektaY Nov 18, 2026
23cfd9a
Cancel a plot drag on Escape and on blur
YektaY Nov 18, 2026
d998474
Give each Waveform PV its own metadata window
YektaY Nov 18, 2026
e0e23b0
Refuse string waveforms in the Waveform model
YektaY Nov 18, 2026
a3555c3
Bound the Waveform rings by a memory budget
YektaY Nov 18, 2026
93db6ae
Keep hidden Waveform PVs out of the "no metadata" error
YektaY Nov 18, 2026
d2b7240
Leave the page keys out of Correlation's 4 KB link budget
YektaY Nov 18, 2026
6ca4a6b
Coalesce Correlation result frames before they reach the plot
YektaY Nov 18, 2026
b24aeeb
Drop Correlation's Clear cut when the PVs or lookback change
YektaY Nov 18, 2026
b0c8db5
Fit and bin Correlation's log axes in their scale; report points left…
YektaY Nov 18, 2026
a7c7aae
Hold Correlation's large-frame window only under pressure
YektaY Nov 18, 2026
068927b
Tie a field's disabled reason and help line to its control
YektaY Nov 18, 2026
9774a2d
Give the segmented control radio-group keyboard behaviour
YektaY Nov 18, 2026
8059b01
Keep keyboard focus after Reset, Remove and Collapse
YektaY Nov 18, 2026
e42272f
Announce Outline card moves by label in a polite live region
YektaY Nov 18, 2026
bf64945
Stop a NaN number-field value from looping renders
YektaY Nov 18, 2026
d693ef8
Show an emptied required number field as an error
YektaY Nov 18, 2026
809e04f
Step number fields by the schema's step with the arrow keys
YektaY Nov 18, 2026
2a4d3dc
Keep focus in the Outline when a removed card's section goes too
YektaY Nov 18, 2026
ee682ac
Commit number fields on blur or Enter; Escape reverts the draft
YektaY Nov 18, 2026
f47fdc1
Keep a hidden Y axis when a plot's every axis is hidden
YektaY Nov 18, 2026
caa2c19
Retry a crashed chart when its plot's settings change
YektaY Nov 18, 2026
9963806
Keep a legend left-click from hiding the curve (R4)
YektaY Nov 18, 2026
c33a452
Draw the extension for a Live-on curve live has not reached (R3)
YektaY Nov 18, 2026
a0c01db
Remember the palette choice and open new plots in it (R7)
YektaY Nov 18, 2026
3218c84
Keep the shown Y range when Auto-scale goes off (R8)
YektaY Nov 18, 2026
6862391
Add a formula on the selected axis, not always the first
YektaY Nov 18, 2026
d25f3cc
Pin Print in a field and the fullscreen Escape order (C8)
YektaY Nov 18, 2026
18385ce
Pin the refusal of a file import with no plots
YektaY Nov 18, 2026
caa08e6
Restore main's shortcut tests on the workbench resolver
YektaY Nov 18, 2026
f8f356f
Keep plot tabs reachable at narrow widths (R5)
YektaY Nov 18, 2026
fb92772
Let a re-pick of the current palette reset curve colours
YektaY Nov 18, 2026
d2f1d42
Restore main's panExtent cases on the gesture layer's pan
YektaY Nov 18, 2026
0beb899
Restore main's header tests for the theme toggle and links
YektaY Nov 18, 2026
dd95e45
Restore the time-window case for a pan past the last clock tick
YektaY Nov 18, 2026
ce8342a
Keep the tab strip at its height in the tab bar
YektaY Nov 18, 2026
f505cda
Commit the typed Min in the Auto-scale seed test
YektaY Nov 18, 2026
cb4e1ae
Break archive lines on spacing only when opted in, never on steps (R1)
YektaY Nov 18, 2026
5392fdb
Add the Break on gaps toggle to the curve's Data settings (R1)
YektaY Nov 18, 2026
d6b8c67
Load and save a curve's live retention as main does (R9)
YektaY Nov 18, 2026
8a58779
Search Trace's PV fields with globs, as main's PV name field did
YektaY Nov 18, 2026
ac23d58
Write a white plot background back as read (R11)
YektaY Nov 18, 2026
2d6b9d3
Apply the opt-in stale-tail rule to Live-on curves live has not reach…
YektaY Nov 18, 2026
4070932
Let a plot turn its drawing tools off
YektaY Nov 18, 2026
86f9a0c
Add Drawing tools and Drawings to Trace's Display
YektaY Nov 18, 2026
593125d
Add Drawing tools and Drawings to Correlation's Display
YektaY Nov 18, 2026
3e8d2b5
Add Drawing tools and Drawings to Waveform's Display
YektaY Nov 18, 2026
b9a8de5
Document the Drawing tools and Drawings settings
YektaY Nov 18, 2026
99479b2
List the drawing toggles in the schema layouts
YektaY Nov 18, 2026
66828a7
Carry Trace's Drawing tools in the link's plot= config
YektaY Nov 18, 2026
51a29ab
Show Drawing tools and Drawings in Display's main list
YektaY Nov 18, 2026
819cd5a
Drag a curve onto another plot's tab or grid cell (R6)
YektaY Nov 18, 2026
6612770
Undo a time-band drag on Escape or blur
YektaY Nov 18, 2026
e3215f4
Add Move to plot to the signal menu (R6)
YektaY Nov 18, 2026
43f24f6
Tighten the time-band blur test to the unchanged range
YektaY Nov 18, 2026
412f265
Pin that a live curve keeps its buffer when moved to another plot (R6)
YektaY Nov 18, 2026
b67ad39
Rename a plot from its tab
YektaY Nov 18, 2026
1413454
Stop truncated workbench text clipping its descenders
YektaY Nov 18, 2026
7801a23
Add the site defaults schema and validator
YektaY Nov 18, 2026
7b6eb8e
Resolve site defaults from their sources into one store
YektaY Nov 18, 2026
dd9fb53
Load the site defaults before the first render
YektaY Nov 18, 2026
5560721
Ship a neutral config.json and document the site defaults
YektaY Nov 18, 2026
004385a
Open new Trace plots and curves with the site defaults
YektaY Nov 18, 2026
36432c5
Open fresh Correlation and Waveform views with the site defaults
YektaY Nov 18, 2026
77f076a
Let the site choose the plot gestures and where the read-out sits
YektaY Nov 18, 2026
a5c5b15
Take the header prefix, brand and help links from the site defaults
YektaY Nov 18, 2026
928a328
Mark and reset site-settable fields against the site's values
YektaY Nov 18, 2026
6c4ad02
Pin the shipped left-drag and time pans (C1)
YektaY Nov 18, 2026
49fab25
Ship Trace's time-only wheel (C2)
YektaY Nov 18, 2026
7732b69
Ship Trace's single-axis Y pan (C3)
YektaY Nov 18, 2026
8fe7bc1
Reset Trace's time to the picked range on a double-click (C4)
YektaY Nov 18, 2026
7ca8b70
Turn the crosshair on in new plots and in links that do not say (C5)
YektaY Nov 18, 2026
863a9b3
Pin live retention following the plot span (C6)
YektaY Nov 18, 2026
fe796ae
Let Trace's data tooltip follow the cursor; docking is a setting (C7)
YektaY Nov 18, 2026
0f1439d
Describe the shipped gestures and the docked tooltip in the user docs
YektaY Nov 18, 2026
71d45ba
Treat another tool's Open in Correlation as a fresh view
YektaY Nov 18, 2026
096fc7a
Use American spelling in the workbench's visible text
YektaY Nov 18, 2026
00b1d4f
Use American spelling in the docs and the example config
YektaY Nov 18, 2026
7d23668
Use American spelling in the desktop app's README
YektaY Nov 18, 2026
6d14166
Keep Trace's grid where its axis hit-zones expect it
YektaY Nov 18, 2026
9355272
Count a Trace link's bytes the way its writer does
YektaY Nov 18, 2026
b4edf71
Disable a locked drawing's style and geometry fields on its card
YektaY Nov 18, 2026
228978f
Add a right-click menu for drawings, on the plot and on their cards
YektaY Nov 18, 2026
1024b16
Show the armed tool's hint in Trace's status line
YektaY Nov 18, 2026
9b6653e
Tell an embedded tile's other plots that their drawings are not saved
YektaY Nov 18, 2026
2658e88
Open a note's text box when it is added from the right-click menu
YektaY Nov 18, 2026
b42a2a3
Open the ink's color picker at the ink, and print a falling measure w…
YektaY Nov 18, 2026
d6d5b46
Document the drawing menu, locked cards and the other plots' measure …
YektaY Nov 18, 2026
d6467e7
Give the color input no value at all for a theme color
YektaY Nov 18, 2026
4237e86
Hint what places a measurement while Measure is armed
YektaY Nov 18, 2026
e327c7e
Remove an empty new note closed with Escape
YektaY Nov 19, 2026
610b158
Keep the outermost left axis name clear of the drawing rail
YektaY Nov 19, 2026
d918e99
Keep one color input so a card edit keeps keyboard focus
YektaY Nov 19, 2026
1b296f6
Mirror the rail gutter in the navigation test's grid inset
YektaY Nov 19, 2026
fc2cb2f
Move the grid cell's Fullscreen and Detach buttons clear of the rail
YektaY Nov 19, 2026
51350bb
Stop the held start value stepping in at the left edge on each refresh
YektaY Nov 19, 2026
55e0176
Name each toggle once in the properties panel
YektaY Nov 19, 2026
7c29caf
List the rail's tooltip, drag and hide-all in Display only without th…
YektaY Nov 19, 2026
7334a04
Keep Carbon's hidden controls inside the properties pane
YektaY Nov 19, 2026
a94b897
Keep the outermost left axis name on the plot without the rail
YektaY Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
4 changes: 3 additions & 1 deletion .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ CANOPY_BASE_URL=http://localhost:8000
# VITE_CANOPY_BASE_PATH is /trace/api/canopy: the container injects the API key
# and proxies it to the in-cluster Canopy service. When it is set, the dev proxy
# also serves that one prefix (stripped before forwarding) instead of the
# per-module paths below.
# per-module paths below. VITE_CANOPY_BASE_PATH=.. puts the modules in the
# directory above the page instead (a page at /x/y/trace/ calls /x/y/mole/...);
# the dev proxy treats it as unset.
VITE_BASE_PATH=/
VITE_CANOPY_BASE_PATH=

Expand Down
29 changes: 29 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,32 @@ concurrency:
jobs:
test:
uses: slaclab/swapps-ci-helpers/.github/workflows/js-test.yml@afaac9fd67e0b31c887a48c19d9a6b219ea72a8f

e2e:
name: Browser tests (Playwright)
runs-on: ubuntu-latest

permissions:
contents: read

steps:
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6

- name: Setup pnpm
uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6

- name: Setup Node.js
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
with:
cache: 'pnpm'

- name: Install dependencies
run: pnpm install

- name: Install Chromium
run: pnpm exec playwright install --with-deps chromium

# The @perf specs time the main thread and need a quiet machine; they run
# locally with `pnpm test:e2e --grep @perf`.
- name: Run browser tests
run: pnpm test:e2e --grep-invert @perf
4 changes: 2 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ lerna-debug.log*
*.sln
*.sw?

# MkDocs
site/
# MkDocs / Zensical build output (the repo root's site/ only)
/site/

# Tauri
src-tauri/target/
Expand Down
2 changes: 2 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,5 @@ src/routeTree.gen.ts

# Must stay byte-identical to the Canopy license
LICENSE.md
# Byte-pinned wire fixtures (sha256-asserted); never reformat
src/tools/correlation/__fixtures__
79 changes: 79 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,85 @@ pnpm format:check

`pnpm build` type-checks the app and the Vite config (`tsc -b`) before bundling; run it before opening a pull request.

### Chrome literals: colors and fonts come from the theme tokens

Trace's own interface (its "chrome") takes its colors and fonts from the
`--canopy-*` contract variables, so a host application can restyle it from one
stylesheet. A color or font written as a literal in the chrome escapes that
contract. `scripts/check-chrome-literals.mjs` enforces this. `pnpm test` runs it
first, and you can run it alone:

```bash
node scripts/check-chrome-literals.mjs # every guarded file
node scripts/check-chrome-literals.mjs src/App.css # only the named files
```

**What it checks.** Each guarded file is checked for:

- a color literal: a hex color (`#fff`, `#0f62fe80`), a color function
(`rgb()`, `rgba()`, `hsl()`, `hsla()`, and `hwb()`, `lab()`, `lch()`,
`oklab()`, `oklch()`, `color(srgb ...)`; one that wraps a `var()` is fine),
or a CSS color name (all 148, such as `red` or `rebeccapurple`);
- a `font` or `font-family` that is not `inherit` or a `--canopy-font-*`
variable;
- in the workbench only (`src/workbench/`), a `font-size` that is not `inherit`
or a `--canopy-text-*` variable.

Use `var(--canopy-...)` (colors, text sizes, fonts) instead.

**Where it looks.** The guarded files are the list in `DEFAULT_FILES` plus
every file under `GUARDED_TREES` in the script: all production modules and
stylesheets of `src/workbench`, `src/plot` and `src/annotations`, and the
stylesheets of `src/tools/waveform` and `src/statistics`. Tests and
`__fixtures__` hold sample data and are not guarded. A new file in a guarded
tree is guarded without editing the script.

**How a file is read.** The guard reads each file the way its syntax works, so
ordinary code is not mistaken for a style:

- In a `.css` file only declarations are read: a selector such as `#feed {`, a
`url(#id)` and quoted text are not colors, and a color name counts only in
the value of a color property (`color`, `background`, `border`, `fill`,
custom properties and so on), so `white-space` and `var(--x-red)` pass.
- In a `.ts`/`.tsx` file only string literals, template literals and style
objects (`style={{...}}`, `style: {...}`, a `CSSProperties` value) are read.
Types (`font: string`), identifiers, JSX text, comments, object keys and
import paths are not. A string's context counts too: `href="#a11"`, a
selector passed to `querySelector` or `closest`, and a message passed to
`new Error()` or `console.*` are not styles, and a color name counts only
under a color key (`color`, `backgroundColor`, `fill`, `stroke`, `border...`)
or a color attribute (`fill="red"`), so `<Tag type="red">` passes.
- Any other file is read line by line as raw text, with hex colors, color
functions and fonts checked but not color names.

**How to exempt a line.** Put a comment on the line before it:

```css
/* canopy-allow-literal: document background */
background: #161616;
```

In TypeScript use `// canopy-allow-literal: <reason>`, or
`{/* canopy-allow-literal: <reason> */}` in JSX. The reason must be one of the
accepted reasons below, and every exemption must also be counted in
`scripts/chrome-literals.allow` (`<file>: <reason>: <count>`, one line per file
and reason), which the full run checks in both directions, so an exemption is
never added or dropped silently. Run the guard on its own to see the exempt
lines it found.

**Accepted reasons.**

| Reason | Use it for |
| --------------------- | ------------------------------------------------------------------------------------------- |
| `document background` | the page background behind the app, which no host variable replaces |
| `@media print` | a print stylesheet, where the theme variables do not apply |
| `widget prop default` | the default of a widget prop that takes a color, before a host sets it |
| `Carbon danger pair` | the text color paired with a Carbon danger background token, which has no contract variable |
| `not a style literal` | a string the guard reads as a color or font that is not one (an id, a label, sample data) |

A line that is not really a style is better rewritten so that the guard no
longer sees it than exempted. Use `not a style literal` only when it can't be.

## Documentation

The user guide in `docs/` is built with [Zensical](https://zensical.org/), which needs [uv](https://docs.astral.sh/uv/):
Expand Down
136 changes: 132 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,23 @@ React + Vite frontend for the Canopy / Trace plotting tool. Reads archive data f
Canopy's Mole module (`/mole/v1/...`), live PVs from Hare and formulas from the Formula
Engine, and posts e-log entries through Canopy's e-log module (`/elog/v1/apps/trace/...`).

## User docs

The **Docs** action in every tool opens the documentation site. Its source lives in
`docs/`. It is a [Zensical](https://zensical.org/) site, built with
`uv run zensical build --clean`, or previewed with `uv run zensical serve`:

- [The properties panel](docs/workbench.md): signals and cards, the plot-wide
sections, the modified dot and reset, More, the chart source, and where
actions live.
- [Waveform](docs/waveform.md): its lists, Snapshot → reference, Δ,
persistence and averaging, the X-axis PV rule, its statistics.
- [Correlation](docs/correlation.md): its built-in metrics, variables, units.
- [Statistics](docs/statistics.md): the shared panel, the Metrics list,
writing a metric, the function reference, the token grammar.
- [Drawing tools](docs/drawing-tools.md): time and axis gestures, range
controls, drawing and measuring on a plot, keys, and how drawings are saved.

## Local dev

### 1. Run the Canopy backend
Expand Down Expand Up @@ -33,7 +50,9 @@ cp .env.example .env
e-log app path (`/elog/v1/apps/trace/`), to `CANOPY_BASE_URL` and injects the `X-API-Key`
header, so the key never reaches the browser bundle. If `VITE_CANOPY_BASE_PATH` is set (for
example `/trace/api/canopy`), the dev server proxies that one prefix instead and strips it
before forwarding, like the container's nginx.
before forwarding, like the container's nginx. `VITE_CANOPY_BASE_PATH=..` is for a gateway
that serves the modules beside Trace: a page at `/x/y/trace/` then calls `/x/y/mole/...`.
The dev server treats `..` as unset.

Trace uses two Canopy keys:

Expand Down Expand Up @@ -99,7 +118,32 @@ reach Canopy.
The header's bug and help buttons open this repo's GitHub issues and the public
docs site. A deployment can point them elsewhere with `VITE_BUG_REPORT_URL` and
`VITE_DOCS_URL` at build time; the image build reads them from the
`BUG_REPORT_URL` and `DOCS_URL` repository variables.
`BUG_REPORT_URL` and `DOCS_URL` repository variables. A site's `config.json`
overrides both at runtime (below).

#### Site defaults (optional)

A deployment sets its own defaults without a rebuild: the header prefix and
links, the plot gestures, and what a new plot, curve or view opens with. Every
page reads `config.json` next to it (the image ships a neutral one at
`/usr/share/nginx/html/config.json`; mount your own over it) and Canopy's
site settings (`GET <Canopy base>/magpie/v1/settings/trace`), which win over
the file. `config.example.json` lists every key; `docs/site-defaults.md`
explains them. The file is served to every browser: no secrets in it. (The
desktop app's `src-tauri/config.json`, which holds keys, is a different file
and is never served.)

#### Channel catalog (optional)

Every PV field suggests names from two sources: Mole's archiver index, and a
channel catalog the host may serve beside it. The catalog is
`GET <Canopy base>/channels`, where `<Canopy base>` is the prefix the Mole,
Hare and Formula Engine routes sit under (`VITE_CANOPY_BASE_PATH` when set,
else the site root; `src/api/connection.ts`). It answers with a
JSON array of PV names (`string[]`) and a strong `ETag`; Trace fetches it once
per page and ranks it in the browser (`src/pvSearch/`). A `404` means the
deployment has no catalog, and suggestions then come from Mole alone. A
network error or a body that is not a string array is treated the same way.

### 3. Run the dev server

Expand All @@ -112,9 +156,93 @@ pnpm dev

```bash
pnpm dev # vite dev server
pnpm build # tsc -b && vite build
pnpm build # tsc -b && vite build, then the dist check
pnpm typecheck # tsc -b
pnpm test # vitest
pnpm test # chrome-literal guard, then vitest
pnpm test:e2e # Playwright browser tests (e2e/*.e2e.ts) against a fresh build
pnpm lint # eslint
pnpm format # prettier --write
```

The browser tests need Chromium once per machine
(`pnpm exec playwright install chromium`). CI runs them with
`--grep-invert @perf`; the `@perf` specs time the main thread, so run them
alone on a quiet machine with `pnpm test:e2e --grep @perf`.

## Adding a tool to the workbench

Trace, Correlation and Waveform are the three tools on the workbench
(`src/workbench/`). The workbench owns the layout, the sidebar, the
properties panel and the actions bar. A tool supplies data and rules, and writes no layout
code. The worked example is the stub fourth tool in
`src/workbench/__fixtures__/stubTool.ts` (`createStubTool`, `stubSchema`).
The panel and layout tests run against it, and it has one of
everything described below.

### `ToolDefinition`

A tool hands `WorkbenchLayout` (from `src/workbench/index.ts`) a
`ToolDefinition` (`src/workbench/types.ts`), along with its `state`, `model`,
`ui`, a single writer `update(fn)` and its `capabilities`. The canvas goes in
as `children`. The definition has two halves:

- **`schema: ToolSchema`** is static. Build it once at module level, never
per render. It holds the tool-level object and the `sections` and `items`
by kind. Each object declares its field groups (`tabs`), and each group its
fields (`FieldDef`, levels `L1` to `L3`; `L3` goes under More). The panel
shows an item's groups as the titled blocks of its card, and the tool's as
the plot-wide sections (ids and labels from `src/tools/vocabulary.ts`, each
with a one-line `summary`). A section kind names its top-block `group`
(Signals, Reference, …) and whether its fields sit under its cards or in
Axes (`placement`). The tool's `code` group is the one chart-source link,
printed by `src/tools/codeFragment.ts`. Fields read `ctx.target`, never
the selection, and write only through `ctx.update`.
- **`binding: ToolBinding`** is rebuilt per render and read through a
latest-ref. It holds `outline(state, model)` (the lists of the top block),
`ops` (`add`, which is async and may resolve to an `AddRefusal`, plus
`remove` and `move`), `moveRefusal(item, section)` (the one rule the Plot on
select and card drags share) and optional `footer` actions.

See `src/tools/waveform/tool.ts` for a real tool. It builds its schema at
module level and its binding with `useWaveformDefinition`.

Canvas actions are registered from inside the canvas with `useCanvasActions`
(`src/workbench/useCanvasActions.ts`), and end with
`standardActions({ embedded, theme, bugUrl, docsUrl })`. Leave out an action
the deployment cannot support. Register a temporarily unusable one with
`disabled: '<reason>'`.

### Dot helpers

The workbench never knows a default. A field that has an automatic value
spreads a `Dot` (`modified(ctx)`, `reset(ctx)`) built by one of the helpers
in `src/tools/dotHelpers.ts`:

- `optionalPath`: the value is optional. It is modified when present, and
reset writes `undefined`.
- `recordKey`: the value is an entry in a per-PV record. It is modified when
the entry exists, and reset deletes it.
- `stampedValue`: the tool stamps an automatic value (a palette color, an
axis slot). It is modified when the tool's rule rejects the stored value,
and reset writes the object's own automatic value.

A field with no automatic rule uses no helper and shows no dot.

### Import allow-list

`src/workbench/**` must never reach into a tool. The ESLint rule
`workbench/import-allowlist` (`eslint.config.js`) allows only `react`,
`@carbon/*`, `@dnd-kit/*`, `react-resizable-panels`, `src/workbench/**` and
the shared PV field modules. Tests and `src/workbench/__fixtures__/` may also
use `vitest`, `@testing-library/*`, `src/tools/dotHelpers` and
`src/tools/codeFragment`. Tool code lives under `src/tools/<tool>/` and
imports the workbench, never the reverse. `pnpm lint` enforces this.

### Test ids are a contract

The `data-testid` values in `src/workbench/testids.ts` (`TESTIDS`, and
`inspectorTab(id)` → `inspector-tab-<id>`) are used by the sdk-js host probes
as well as the e2e specs, so they are a cross-repo contract.
`src/workbench/testids.test.ts` pins the set. A rename fails there first and
must be made in the probes too. Test ids are for chrome. Fields are reached by
their `#id`, and a control never has both.
Loading