testerkit 0.4.0__py3-none-any.whl

testerkit/_docs/reference/operator-ui/channels/list.md

@@ -0,0 +1,70 @@
+# Channels — list view
+
+**URL:** `/channels`
+
+Every channel TesterKit has seen — streaming numeric / array signals
+captured during test runs (scope traces, PSU readback, sensor logs).
+Each row shows a live sparkline of the last 50 samples and the
+latest value; values update in place as new samples arrive. Click a
+row to drill into the [single-channel chart](detail.md).
+
+## Table
+
+![Channels — table](../../../_assets/operator-ui/channels/table.png)
+
+A count above the table tells you how many channels have been seen.
+
+| Column | What it shows |
+|---|---|
+| Channel ID | The channel's identifier — typically `<instrument-role>.<signal>` or `<channel-name>` |
+| Latest | The most recent sample, with units appended when known. `—` when no samples yet. |
+| History | An inline sparkline of the last 50 samples (or `—` for series with fewer than 2 samples). |
+| Type | Sample data type (e.g. `scalar:float`, `array:float`) from the channel descriptor |
+| Instrument | The instrument role this channel belongs to, when known |
+| Last updated | When the most recent sample arrived, in browser-local time |
+
+The table is dense — rows are about 30 pixels tall; sparklines
+render inside the row at 80×24 pixels.
+
+## Filters
+
+A filter card above the table narrows the list: **Channel ID contains**,
+**Type**, **Instrument**, and a **Since / Until** date window, plus a
+**Refresh** button. When you arrive from a run (via its detail page), a
+banner scopes the list to that session with a Clear button.
+
+## Live updates
+
+The view refreshes live as channels appear and update — no manual
+reload needed. Cells re-render in place; unchanged rows don't repaint,
+so the view stays calm during quiet periods. If live events aren't
+available, the page falls back to polling every couple of seconds.
+
+## Empty state
+
+When no channels have been written yet, the table is replaced with a card
+explaining how channels get populated: "Channels appear once a test
+writes to the channel store (e.g. `context.observe('scope', value)`
+or instrument observers)."
+
+## Underlying data
+
+Channel samples are stored separately from runs and measurements.
+Programmatic access goes through `ChannelStore`
+(`from testerkit.data.channels.store import ChannelStore`); there is no
+first-class CLI equivalent today.
+
+## Common tasks
+
+- **Watch a sensor live during a test** — open `/channels`, find the
+  row, watch the Latest column and sparkline update.
+- **Drill into one channel's full history** — click any row to open
+  the [single-channel detail](detail.md) with a full chart + raw data
+  table + session/date filters.
+
+## See also
+
+- [Channel detail](detail.md) — the per-channel view you reach by
+  clicking a row
+- [Concepts → Data stores](../../../concepts/data/data-stores.md) — why
+  ChannelStore is separate from EventStore and the parquet runs index

testerkit/_docs/reference/operator-ui/dashboard.md

@@ -0,0 +1,87 @@
+# Dashboard
+
+**URL:** `/`
+
+The home page. Two short sections: configured stations as cards, and
+recent runs as a compact table. For a fresh install with neither
+stations nor runs, the page swaps to a three-step Getting Started
+card instead.
+
+## Stations
+
+![Dashboard — stations](../../_assets/operator-ui/dashboard/stations.png)
+
+One card per station configured in the project. Each card shows:
+
+| Element | What it shows |
+|---|---|
+| Title | Station name (falls back to the station id if the name is left blank) |
+| Status badge | A green outlined `Ready` badge |
+| Description | The station's description, when set |
+| Identifier row | Station id + location, prefixed with tag and pin icons |
+| Start Test button | Jumps to `/launch?station=<id>` ([Launch Test](launch.md), prefilled with this station) |
+
+When no stations are configured but runs exist, the section renders
+an empty-state card naming the cause and the next step — add a station
+YAML under `stations/`.
+
+## Recent Runs
+
+![Dashboard — recent runs](../../_assets/operator-ui/dashboard/runs.png)
+
+A 10-row table of the most recent finished runs across the project.
+Runs still in progress (not yet finished) are NOT shown here — open
+the [Results list](results/list.md) to see them. The Dashboard's table
+is deliberately a quick-glance summary.
+
+| Column | What it shows |
+|---|---|
+| UUT | UUT serial number |
+| Station | Station hostname (the machine an operator recognizes), not the internal station id |
+| Started | Run start timestamp, browser-local time |
+| Outcome | Outcome status; a bell badge appears (linking to the live view) when the run has operator dialogs waiting |
+
+Click a row to open the [Results detail](results/detail.md) for that run.
+
+When no runs have been recorded yet, the section renders an empty-state
+card naming the cause and the next step — launch a test to populate
+the list.
+
+## Getting Started (empty state)
+
+When the project has **neither stations nor runs**, the page swaps
+to a Getting Started card with three numbered steps:
+
+1. **Create a station** — buttons for "New Station" (jumps to the
+   create-station form) and a one-liner pointing at `testerkit station
+   init` on the CLI
+2. **Write a test** — `testerkit new-test <name>` command snippet
+3. **Run it** — `pytest --mock-instruments` command snippet
+
+Below the steps, a hint card points at `testerkit init --starter` for
+authors who'd rather start from a fully populated example project.
+
+## Live updates
+
+The Dashboard loads its data once when you open the page; it doesn't
+update live — refresh the browser to pick up new runs or station
+changes. (The one exception: a run's pending-dialog bell badge
+refreshes on its own every second.)
+
+## Underlying data
+
+- Stations come from the local project's `stations/` directory
+- Recent runs come from the same runs index as [Results list](results/list.md)
+
+## Common tasks
+
+- **Open a station's launch form** — click `Start Test` on the station card
+- **Drill into the latest run** — click any row in Recent Runs
+- **Bootstrap a fresh project** — follow the three steps in the
+  Getting Started card
+
+## See also
+
+- [Launch Test](launch.md) — start a new test session
+- [Results list](results/list.md) — full run history beyond the 10
+  shown here

testerkit/_docs/reference/operator-ui/designer.md

@@ -0,0 +1,167 @@
+# System Designer
+
+**URL:** `/designer`
+
+The System Designer is the visual surface for wiring a part's
+UUT pins to a station's instrument channels. Pick a part, pick
+a station, click a pin, click an instrument channel — the page
+draws the wire and auto-saves a fixture YAML to disk.
+
+The bottom of the page has three tabs (Connections, Station Type,
+YAML Preview) that always reflect the current graph state.
+
+> **Experimental.** The System Designer is less mature than the rest
+> of TesterKit, and the screen carries an "Experimental" banner. Expect
+> rough edges, and check the saved fixture YAML before you depend on it
+> in a run.
+
+## Top bar — selection
+
+| Control | Purpose |
+|---|---|
+| Part | Dropdown of every part in the project's `parts/` directory. Picking one loads the part's pin map onto the design surface and, if a matching fixture YAML already exists for the auto-generated fixture ID, loads its connections too. |
+| Station | Dropdown of every station in the project's `stations/` directory. Picking one loads the station's instruments + channels into the right-side pool of wiring targets. |
+| Load Fixture | Opens a dialog listing every fixture in `fixtures/`. Pick one and the designer replaces the current connections with that fixture's. |
+| Add Instrument | Opens a dialog to add an instrument to the current station definition. Fields: Instrument Type (optional dropdown from the project catalog — selecting one pre-fills channel names from the type's capability spec), Role Name (e.g. `dmm`, `psu`), Driver (e.g. `examples.drivers.DMM`), Channels (comma-separated). |
+
+## ID bar
+
+| Field | Purpose |
+|---|---|
+| System ID | Identifier the Station Type tab uses when rendering the station-type YAML preview. The designer does not write a station-type YAML on its own — the preview is for copy-paste or for matching against a hand-written `stations/<id>.yaml`. |
+| Fixture ID | Identifier for the fixture YAML the designer writes on auto-save. |
+
+**Auto-save** writes `fixtures/<fixture_id>.yaml` whenever both IDs
+are set and the graph has at least one connection. It runs after:
+
+- Adding a wire (clicking a channel node while a pin is selected)
+- Auto-Match
+- Clear All
+
+Because auto-save only writes when at least one connection exists,
+**Clear All does not rewrite the file to the empty state** — the saved
+fixture keeps its last non-empty connections until you add the next
+wire. Drawer-initiated actions (Delete Connection, Delete Pin, Delete
+Instrument, editing a pin field) don't save on their own either; add a
+wire to write them out.
+
+There is no Save button anywhere on the page.
+
+## Status bar
+
+A row of counters and toggles, just above the design surface:
+
+| Indicator | Meaning |
+|---|---|
+| `N / M pins wired` | How many of the part's pins are connected, and the total. |
+| `N available` | How many pins are still unconnected. |
+| `N instruments` | Instruments currently in the station. |
+| Wiring: \<pin\> | When a pin is selected and waiting for a channel click, the status bar shows it in a blue chip. |
+| Hide Unused checkbox | Filters the graph to only nodes with at least one connection. |
+| Auto-Match button | Walks every unconnected pin that has a characteristic defined on it, asks the matching engine for a compatible channel from the current station, and creates the connection. Pins without a characteristic are skipped silently. |
+| Clear All button | Wipes every connection on the current fixture in memory. The saved file is not rewritten to the empty state (auto-save only writes when at least one connection exists) — the cleared state lives in the page until you add the next wire. |
+
+## Design Surface
+
+An [ECharts](https://echarts.apache.org/) graph showing UUT pins on
+the left and instrument channels on the right, with wires drawn
+between connected nodes. Three interactions:
+
+- **Click a pin** — selects it. Status bar shows "Wiring: \<pin\>".
+- **Click a channel** while a pin is selected — creates the
+  connection and clears the selection.
+- **Click a wire** — opens the connection in the right-side
+  properties drawer. The drawer shows the connection's fields
+  (Point Name, UUT Pin, Net, Instrument, Channel, optional
+  Terminal) as read-only inputs with a Delete Connection button —
+  it's a remove-or-leave-alone affordance, not an edit form.
+
+When no part is selected and no instruments are loaded, the
+graph is replaced with a hint: "Select a part and load a station
+to begin."
+
+## Bottom tabs
+
+Three tabs share the panel below the graph; they always reflect the
+current graph state.
+
+### Connections tab
+
+A table of every current wire on the fixture.
+
+| Column | What it shows |
+|---|---|
+| Point | The connection point name — auto-generated from pin + role at wire time and not user-editable |
+| UUT Pin | The pin on the part side |
+| Net | Net / signal name (optional, free-text) |
+| Instrument | The station instrument the wire terminates on |
+| Channel | The channel / terminal on that instrument |
+
+Click a row to open the same read-only-with-Delete drawer that the
+graph wires open.
+
+When the fixture has no connections, the tab shows: "No connections
+yet. Wire pins to instrument channels above."
+
+### Station Type tab
+
+A live YAML preview of a station-type document derived from the
+current station's instruments. The structure mirrors what
+`/stations` consumes — useful for copying out to a
+`stations/<id>.yaml` file by hand. The designer does not save this
+on its own; you write it to disk yourself.
+
+When no instruments are loaded, the tab shows: "No instruments
+added yet."
+
+### YAML Preview tab
+
+A live YAML preview of the **fixture** document — the file that
+gets auto-saved to `fixtures/<fixture_id>.yaml`. Cross-check this
+against the [Fixture YAML schema](../configuration.md#fixture-yaml)
+to confirm the shape before you depend on the fixture in a run.
+
+When the fixture has no connections, the tab shows: "No connections
+to preview."
+
+## Pre-fill via URL
+
+The designer accepts three URL query parameters; the URL is also
+kept in sync (via `history.replaceState`) as you make selections so
+the current state is bookmarkable.
+
+| Parameter | Pre-fills |
+|---|---|
+| `part` | The Part dropdown — `?part=<id>` |
+| `station` | The Station dropdown — `?station=<id>` |
+| `fixture` | Loads an existing fixture by ID — `?fixture=<id>` |
+
+## Underlying data
+
+- Parts come from `parts/`.
+- Stations come from `stations/`.
+- Fixtures (loaded and saved) live in `fixtures/`.
+- Auto-Match uses the same
+  [capability matching](../../concepts/configuration/capabilities.md)
+  used elsewhere to find a station-channel that satisfies a part
+  pin's required signal direction.
+
+## Common tasks
+
+- **Wire a fresh fixture from scratch** — pick Part + Station,
+  set Fixture ID, click pins → click channels. Save happens
+  automatically.
+- **Iterate on an existing fixture** — open the designer with
+  `?fixture=<id>` (or pick it from Load Fixture), make changes,
+  watch the YAML Preview tab confirm the shape.
+- **Generate a draft fixture quickly** — load Part + Station,
+  click Auto-Match, then refine the suggestions by clicking
+  individual wires.
+
+## See also
+
+- [Fixtures](fixtures.md) — the entity reference for what gets saved
+- [Configuration reference → Fixture YAML](../configuration.md#fixture-yaml) — the schema the designer writes
+- [Concepts → Capabilities](../../concepts/configuration/capabilities.md) — how Auto-Match decides what fits
+- [Stations](stations.md) — the station whose instruments populate the channel side
+- [Parts](parts.md) — the part whose pins populate the UUT side

testerkit/_docs/reference/operator-ui/events.md

@@ -0,0 +1,89 @@
+# Events
+
+**URL:** `/events`
+
+Browse the event log — the append-only stream of everything TesterKit
+records: session lifecycle, run lifecycle, test step starts and ends,
+measurements, channel starts, instrument writes, operator dialogs, and
+diagnostics. The Results pages roll events up into runs; this page
+shows them raw.
+
+Use it to debug timing ("why did this run pause for 4 seconds?"),
+trace instrument activity ("what did the DMM actually do during this
+test?"), or audit dialog responses ("did the operator confirm
+calibration before that batch?").
+
+## Filters
+
+![Events — filters](../../_assets/operator-ui/events/filters.png)
+
+| Filter | What it does | Notes |
+|---|---|---|
+| Session ID | Restrict to events for one session | Free-text. Full or short (first 8 chars) UUID works. |
+| Event type | Pick one of 15 curated event types, or `(any)` for all | The event log can hold any event type; this dropdown lists the categories worth a one-click filter — it is **not exhaustive**. Other event types (e.g. `fixture.uut_scanned`, `route.*`, `site.*`, `channel.*`) only appear under `(any)`. See the [Event types reference](../data/event-types.md) for the full list. |
+| Role | Filter by instrument role (e.g. `dmm`, `psu`) | Free-text. |
+| Since (ISO) | Earliest event timestamp | ISO-8601 string. |
+| Limit | Maximum events fetched | Default 100, range 1–10,000. |
+| Refresh | Force a re-fetch | Filter changes already auto-refresh. |
+
+## Table
+
+![Events — table](../../_assets/operator-ui/events/table.png)
+
+One row per event, newest first. Above the table a count tells you
+how many events matched.
+
+| Column | What it shows |
+|---|---|
+| Timestamp | When the event was recorded, in browser-local time |
+| Type | Event type (e.g. `channel.started`, `test.measurement`) |
+| Role | Instrument or fixture role for events that carry one; otherwise blank |
+| Summary | A type-specific one-liner — channel name for channel starts, measurement name + value + outcome for measurements, station id for session events, UUT serial for run events, step name for step events |
+
+Click a row to open a detail dialog showing the full event JSON
+(every field on the event record).
+
+When no events match, the table area shows "No events match the
+current filters." instead.
+
+## Bookmarkable URL state
+
+All filters serialize to query parameters so a URL captures the view:
+
+| Parameter | Meaning |
+|---|---|
+| `session_id` | Session UUID filter |
+| `event_type` | One of the dropdown values (or omitted for `(any)`) |
+| `role` | Instrument role filter |
+| `since` | ISO-8601 lower bound |
+| `limit` | Result cap (omitted at default 100) |
+
+## Underlying data
+
+The page reads from the event log — the same append-only stream every
+other view reads from. There is no first-class CLI equivalent today;
+events are observable in aggregate via the Runs / Metrics CLIs, and
+raw events can be read programmatically — see
+[Querying events](../../how-to/data/querying-events.md).
+
+For the schema of each event type, see
+[Event types reference](../data/event-types.md).
+
+For how the event log works, see
+[Concepts → Event log](../../concepts/data/event-log.md).
+
+## Common tasks
+
+- **Why did this run pause?** — Filter by Session ID, sort by
+  timestamp, look for gaps between consecutive `test.step_*` events.
+- **Did the operator confirm before the batch?** — Filter event type
+  to `dialog.opened` then `dialog.responded`, narrow by Session ID.
+- **Which channels did this test actually touch?** — Filter event
+  type to `channel.started`, scoped by Session ID.
+
+## See also
+
+- [Results detail](results/detail.md) — the same events grouped into
+  a single run's tabs
+- [Event types reference](../data/event-types.md)
+- [Concepts → Event log](../../concepts/data/event-log.md)

testerkit/_docs/reference/operator-ui/files.md

@@ -0,0 +1,74 @@
+# Files
+
+`/files` lists the artifacts in the FileStore — images, waveforms, byte
+streams, and any other file a test recorded via `observe(name, value)` or
+`files.write(...)`. Each row links to a per-artifact detail page with an
+inline viewer and a download button.
+
+Reach it from the **Files** entry under DATA STORES in the sidebar.
+
+## Filters
+
+Filter widgets render above the table:
+
+- **Type** — dropdown of the MIME types (or file extensions) actually present,
+  `(any)` by default.
+- **Filename contains** — case-insensitive substring match on the filename.
+- **Since / Until** — created-at date window.
+- **Session** — set only by deep-links from a run (`/results/{run_id}` →
+  Files), shown as a banner with a Clear affordance. There is no session
+  picker; operators scope by date / name / MIME, not by session UUID.
+
+## Table
+
+![Files — artifact list](../../_assets/operator-ui/files/table.png)
+
+One row per artifact:
+
+| Column | Meaning |
+|--------|---------|
+| Live | `● live` while the artifact is still being written (a stream), `○ done` once finalized. |
+| Filename | The artifact's name (the `name` passed to `observe` / `files.write`, plus the format's extension). |
+| Type | The recorded MIME type, or the file extension when the sidecar MIME is absent. |
+| Size | Human-readable file size. |
+| Created | When the artifact was written. |
+| Download | A link that saves the artifact. |
+
+Clicking a row opens `/files/{date}/{session_id}/{filename}`.
+
+## Detail page — viewer + download
+
+The detail page shows a metadata card (MIME, extension, size, modified,
+and the session it belongs to) and an **inline viewer chosen by file
+type**. Supported viewers:
+
+- **Image** (`.png`, `.jpg`, …) — rendered inline.
+- **Video** (`.mp4`, `.webm`) — played inline.
+- **JSON** — pretty-printed.
+- **JSONL** (`.jsonl`, `.ndjson`) — one row per line in a table.
+- **CSV** — parsed into a table.
+- **Text** (`.txt`, `.log`, `.md`) — shown as plain text.
+- **NPZ** — a `Waveform` chart.
+- **NPY** — array stats.
+- Anything else, or files over the viewer size cap — a **hex / download**
+  fallback.
+
+The **Download** button saves the artifact rather than rendering it
+inline; it works on every deployment.
+
+## Bookmarkable URL state
+
+The list mirrors its filters into the URL (`?mime=`, `?name=`, `?since=`,
+`?until=`, `?session_id=`), so a filtered view is shareable. The detail page's
+URL is the artifact's full key — `/files/{date}/{session_id}/{filename}`.
+
+## Underlying data
+
+Rows come from the **FileStore catalog** (the `testerkit_files` MCP tool and
+`GET /api/files/catalog` expose the same list), never from a directory scan.
+
+## See also
+
+- [How-to: capture an artifact](../../how-to/data/capture-an-artifact.md) — `observe` / `files.write` / `files.stream`
+- [Concepts: the three verbs](../../concepts/data/three-verbs.md) — how `observe` routes a file to the FileStore
+- [Channels](channels/list.md) — the time-series sibling store

testerkit/_docs/reference/operator-ui/fixtures.md

@@ -0,0 +1,100 @@
+# Fixtures
+
+**URLs:** `/fixtures` (list), `/fixtures/new`, `/fixtures/{id}`, `/fixtures/{id}/edit`
+
+A fixture is the wiring between a UUT's pins and a station's
+instrument channels — which probe goes on which pin, which DMM
+channel reads which voltage. A fixture is bound to a part (so it
+gets used in the right runs) and is used at run time by stations
+whose instruments cover the fixture's connections. The fixture's
+connection rows themselves carry free-text UUT-pin and channel
+fields — they're not validated against the part's pin map at
+edit time.
+
+## List — `/fixtures`
+
+A table with one row per fixture that is either configured in the project
+(a YAML file exists) or has been observed in run history (no YAML file,
+only referenced by past runs). Columns:
+
+| Column | What it shows |
+|---|---|
+| Status | **Configured** chip (grey) — a YAML file exists. **Observed** chip (amber) — appears in run history but has no YAML file. |
+| ID | Fixture identifier |
+| Name | Human-readable name |
+| Part | Part name (falls back to the bound part ID when the part name isn't resolvable) |
+| Rev | Revision string (when set) |
+| Connections | Count of pin → channel connections defined; `—` for Observed rows |
+| Runs | Total runs that have used this fixture |
+| Passed | Run count with outcome `passed` |
+| Failed | Run count with outcome `failed` |
+| Last Run | Most recent run start timestamp, browser-local time |
+
+Above the table, a filter card with **All / Configured / Observed** buttons
+narrows the view. The active filter is mirrored into the URL so the view is
+bookmarkable.
+
+A **New Fixture** button at the top right jumps to `/fixtures/new`.
+Clicking a Configured row jumps to the detail view at `/fixtures/{id}`.
+Observed rows are not clickable — no YAML exists to display.
+
+When no fixtures are configured or observed, the table is replaced with an
+empty-state card explaining the entity and offering a Create Fixture button.
+
+## Detail — `/fixtures/{id}`
+
+A header bar (Back + Edit buttons), one Fixture Information card
+(Fixture ID, Part Family, Connections count, Description, and a link
+to the Part), then a tab strip with three tabs:
+
+| Tab | Content |
+|---|---|
+| Pin Mappings | The connections table — one row per (UUT pin → instrument channel) mapping. Columns: Connection (the mapping's name), UUT Pin, Net, Instrument, Channel, Description. |
+| Compatible Stations | Stations whose instruments cover this fixture's required instruments (matched by instrument role). |
+| Diagram | A Mermaid-rendered diagram of the pin-to-instrument wiring. |
+
+## Edit — `/fixtures/{id}/edit`
+
+The Edit page carries the fixture's info fields (Fixture ID, Name,
+Part, Part Revision, Description) plus a **Pin Mappings** card where
+you manage connections. The Part is a dropdown. The UUT Pin and
+Instrument Channel fields on each connection row are **free-text
+inputs**, not dropdowns sourced from the part pin map. The Instrument
+dropdown on each connection row pulls its options from the union of
+all stations' instruments in the project, so any instrument role
+declared anywhere is selectable. Connections are managed as rows —
+Add / Edit / Delete one at a time via per-row buttons and an Add
+Connection dialog.
+
+Not every YAML field is editable here — `instrument_terminal`,
+`function`, `route`, `station_types`, `uut_resource`, and `sites` are
+YAML-only.
+
+## New — `/fixtures/new`
+
+A short form for just the fixture info (ID, Name, Part, Part Revision,
+Description) — no connection rows. On create it redirects to the Edit
+page, where you add the pin mappings.
+
+## Underlying data
+
+Fixtures are stored as YAML in `fixtures/*.yaml` under the project
+root.
+
+For the YAML schema, see
+[Configuration reference → Fixtures](../configuration.md#fixture-yaml).
+For the concept, see [Concepts → Fixtures](../../concepts/configuration/fixtures.md).
+
+## Common tasks
+
+- **Wire a new probe to a pin** — open `/fixtures/{id}/edit`, add a
+  connection row mapping pin → instrument-role + channel.
+- **See where a fixture has been used** — the List view's Runs +
+  Passed + Failed columns + Last Run; the [Results list](results/list.md)
+  doesn't filter by fixture today, so use the Runs column here as
+  the quick scoreboard.
+
+## See also
+
+- [Configuration reference → Fixtures](../configuration.md#fixture-yaml)
+- [Concepts → Fixtures](../../concepts/configuration/fixtures.md)