diff --git a/docs/requirements/015-rates-time-range.md b/docs/requirements/015-rates-time-range.md new file mode 100644 index 0000000..06b65c9 --- /dev/null +++ b/docs/requirements/015-rates-time-range.md @@ -0,0 +1,108 @@ +# 015 - Time Range in the Rates Panel + +## User Story + +As the operator, I want to pick any window of the hub's history and the rate +unit in the one Rates per period panel, and read every rate over exactly that +window, so that I see how the agents worked in any past stretch with one +control instead of three. + +## Decisions (operator-confirmed 2026-11-17; do not re-litigate) + +1. **One panel**: the time range menu (`1 h โ–พ`) and the rate period select + leave the header; time range, replay and rate unit live in the Rates per + period panel the rates chip opens. The header keeps the Live line and the + chip. Rejected: keeping the header menus as shortcuts (two controls for + one value). +2. **Two-thumb slider over the whole history**: one slider spans the first + record to now with a From and a To thumb; the window moves and stretches + freely, the thumbs never cross. Presets 1 h, 6 h, 24 h, 7 d and all set + both thumbs with the end at now; arrow keys step a thumb; the exact From + and To inputs stay below the slider. The window drives the whole page as + the time range does today. Rejected: a length and an end slider (two + controls for one window), a brush on a mini timeline (most effort). +3. **Replay and Live**: Replay slides the window at its length from where it + stands to now in 48 steps of 500 ms; a click pauses. Live puts the To + thumb on now and keeps the length. A window ending at now is live. +4. **Rates over the chosen window**: a count is the sum inside the window, a + gauge its average over the window. Every unit column converts that one + window: per minute, hour, day, week, month (30 days) and year (365 days); + `all` is the sum inside the window (a gauge: its average). Example: last + 7 days and unit day give the mean daily tokens of those 7 days. A window + reaching back before the first record of a kind divides by the covered + part and shows โ‰ˆ, the covered span in the tooltip. Rejected: each column + its own trailing window and the scaling from the next longer window + (014 decisions 2 and 5), one value column only. +5. **Chip**: shows window and unit (`7 d ยท /d`) and the chosen metrics, 2 to + 9 of the nine; the default stays tasks done, tokens, CPU. Where the header + lacks room the chip shows as many as fit and `+n`. Rejected: a limit of 3 + or 5. +6. **Persistence**: unit and chip metrics persist in the hub settings + `rates` without a passkey, as today; the window stays page state, 1 h + live on load, as today. +7. **Timing**: implemented after every other open skills requirement. + +## Approach + +```mermaid +flowchart TD + subgraph P["๐Ÿงญ 0 ยท Preparation"] + P1["๐Ÿ“‹ Write requirement"] --> P2{"โœ… Operator approves?"} + P2 -- "โœ๏ธ corrections" --> P1 + end + P2 -- "๐Ÿค– yes, after the other requirements" --> A1 + subgraph A["๐Ÿ—„๏ธ A ยท Data"] + A1["๐Ÿงฎ /api/rates over from and to, settings 2 to 9"] --> A2{"๐Ÿงช Unit and integration green?"} + A2 -- "๐Ÿ”ด no: fix" --> A1 + end + A2 -- "๐ŸŸข yes" --> B1 + subgraph B["๐ŸŽš๏ธ B ยท Panel"] + B1["๐Ÿงฉ Header cleanup, slider, presets, replay, unit, chip"] --> B2{"๐Ÿงช E2E green?"} + B2 -- "๐Ÿ”ด no: fix" --> B1 + B2 -- "๐ŸŸข yes" --> BF{"๐Ÿ’ฌ Operator feedback on screenshots?"} + BF -- "โœ๏ธ changes" --> B1 + end + BF -- "๐Ÿ‘ fits" --> D1["๐Ÿ Review, commit with operator OK, hand-over"] +``` + +## Acceptance Criteria + +### Data + +- [ ] `/api/rates?from=&to=` returns per unit and metric the window's + sum converted to the unit, or the gauge's average; `all` holds the sum. +- [ ] A 7-day window holding 7,000,000 tokens gives `day` 1,000,000, `week` + 7,000,000 and `all` 7,000,000. +- [ ] A window starting before the first record of a kind divides by the + covered seconds and returns `approx: true` with `covered` seconds. +- [ ] A gauge without a sample in the window returns null. +- [ ] `rates.metrics` accepts 2 to 9 distinct metrics; 1 or a duplicate is + refused with a 400. + +### Panel + +- [ ] The header holds no time range menu and no rate period select; the + Live line and the chip stay. +- [ ] The panel shows the presets, the two-thumb slider, Replay, Live, the + From and To inputs, the unit picker and the table. +- [ ] Dragging From to 9 days ago and To to 2 days ago reloads the stream, + the charts and the rates for that window, and the label names both + ends. +- [ ] Each preset sets both thumbs with the end at now. +- [ ] ArrowLeft and ArrowRight move the focused thumb one step; From never + passes To. +- [ ] Replay slides the window to now and ends live; a click pauses it. +- [ ] With 7 d and unit d the chip's tokens equal the table's `d` cell and + the window's token sum divided by 7. +- [ ] With 9 metrics chosen the chip shows every one at 1920 and `+n` at + 390, and the header never grows wider than the viewport. +- [ ] Unit and metrics survive a reload; the window returns to 1 h live. + +### Tests + +- [ ] Unit: window sums per unit, the covered part and approx, gauge + averages over the window, the settings round trip with 2 and 9 metrics. +- [ ] Integration: the hub serves `/api/rates?from&to` from fixture files. +- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: header without the + old controls, slider by mouse and keys, presets, replay to live, unit + change, the 9-metric chip; screenshots for the checkpoint. diff --git a/docs/requirements/016-agents-controls-row.md b/docs/requirements/016-agents-controls-row.md new file mode 100644 index 0000000..a53f6ca --- /dev/null +++ b/docs/requirements/016-agents-controls-row.md @@ -0,0 +1,62 @@ +# 016 - Agents Controls in the View Row + +## User Story + +As the operator, I want the Priority, Day/Night and Status controls of the +agents screen in the row of its view switcher, so that the screen spends one +row on controls and the graph gets the room. + +## Decisions (operator-confirmed 2026-11-17; do not re-litigate) + +1. **One row**: the controls card holds on the left the view switcher + (Orbit, Chord, Swimlane, Tree, 3D, Hierarchy) and the 3D layout tools, on + the right Priority, Day/Night and Status; the toolbar row above it goes. + Rejected: keeping the separate toolbar row. +2. **Same controls**: the three keep their menus, labels and behaviour; only + their place changes. +3. **Narrow screens**: without room for one row the right group wraps under + the switcher, aligned right, with no horizontal scroll. +4. **Timing**: implemented after every other open skills requirement. + +## Approach + +```mermaid +flowchart TD + subgraph P["๐Ÿงญ 0 ยท Preparation"] + P1["๐Ÿ“‹ Write requirement"] --> P2{"โœ… Operator approves?"} + P2 -- "โœ๏ธ corrections" --> P1 + end + P2 -- "๐Ÿค– yes, after the other requirements" --> A1 + subgraph A["๐Ÿงญ A ยท Controls row"] + A1["๐Ÿงฉ Move the three controls into the view card"] --> A2{"๐Ÿงช E2E green?"} + A2 -- "๐Ÿ”ด no: fix" --> A1 + A2 -- "๐ŸŸข yes" --> AF{"๐Ÿ’ฌ Operator feedback on screenshots?"} + AF -- "โœ๏ธ changes" --> A1 + end + AF -- "๐Ÿ‘ fits" --> D1["๐Ÿ Review, commit with operator OK, hand-over"] +``` + +## Acceptance Criteria + +### Layout + +- [ ] On every agents view the `.graph` holds no `.toolbar` before + `.card.controls`. +- [ ] `.card.controls` holds the View group first and Priority, Day/Night + and Status last; at 1920 and 1366 the Status menu's right edge lies + within 16 px of the card's content edge. +- [ ] At 390 the document's `scrollWidth` is at most `innerWidth` and the + three controls sit below the switcher. + +### Behaviour + +- [ ] Priority opens the agent order, Day/Night shows the night mode and its + actions, Status hides and shows agent states, each as before. + +### Tests + +- [ ] Unit: n/a: a layout change without logic. +- [ ] Integration: n/a: no server change. +- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390 on Orbit, Chord, + Swimlane, Tree, 3D and Hierarchy: the row, the wrap, the three menus + open; screenshots for the checkpoint. diff --git a/docs/requirements/017-legend-toggle.md b/docs/requirements/017-legend-toggle.md new file mode 100644 index 0000000..42085d0 --- /dev/null +++ b/docs/requirements/017-legend-toggle.md @@ -0,0 +1,74 @@ +# 017 - Legend Toggle + +## User Story + +As the operator, I want to hide and show a chart's legend on its Home tile +and in its view, so that a small tile shows the chart instead of its legend. + +## Decisions (operator-confirmed 2026-11-17; do not re-litigate) + +1. **Info button**: a button with the info icon (`bi-info-circle`) and + `aria-pressed` shows or hides the legend; on a Home tile it sits left of + the Open button, in a view next to the star. Only panels whose content + holds a legend get it, among them Tasks burndown and burnup, Tokens and + Hardware resources. +2. **Per tile and per view, in the hub store**: each Home pin and each view + keeps its own state in the hub view store, shared by every browser; the + default is shown. Rejected: one global switch, a per-browser state. +3. **The chart takes the room**: a hidden legend frees its space for the + chart; series switched off in legend chips stay off while the chips are + hidden. +4. **Timing**: implemented after every other open skills requirement. + +## Approach + +```mermaid +flowchart TD + subgraph P["๐Ÿงญ 0 ยท Preparation"] + P1["๐Ÿ“‹ Write requirement"] --> P2{"โœ… Operator approves?"} + P2 -- "โœ๏ธ corrections" --> P1 + end + P2 -- "๐Ÿค– yes, after the other requirements" --> A1 + subgraph A["๐Ÿ—„๏ธ A ยท State"] + A1["๐Ÿงฎ View store keys for tile and view legends"] --> A2{"๐Ÿงช Unit green?"} + A2 -- "๐Ÿ”ด no: fix" --> A1 + end + A2 -- "๐ŸŸข yes" --> B1 + subgraph B["โ„น๏ธ B ยท Buttons"] + B1["๐Ÿงฉ Info button on tiles and views"] --> B2{"๐Ÿงช E2E green?"} + B2 -- "๐Ÿ”ด no: fix" --> B1 + B2 -- "๐ŸŸข yes" --> BF{"๐Ÿ’ฌ Operator feedback on screenshots?"} + BF -- "โœ๏ธ changes" --> B1 + end + BF -- "๐Ÿ‘ fits" --> D1["๐Ÿ Review, commit with operator OK, hand-over"] +``` + +## Acceptance Criteria + +### Button + +- [ ] A DOM scan of Home and every view finds the info button exactly on + the tiles and views whose content holds a `.legend`. +- [ ] On a tile it is the head button left of Open; in a view it sits next + to the star. +- [ ] A click hides the legend and the chart's height grows; a second click + shows it again. + +### State + +- [ ] The state survives a reload and shows in a second browser. +- [ ] Hiding the legend on the Tokens tile leaves the Tokens view's legend + shown, and the reverse. +- [ ] With the IAM series switched off and the Tokens legend hidden, the + chart still leaves IAM out. +- [ ] The view store refuses an unknown panel key and a non-boolean value + with a 400. + +### Tests + +- [ ] Unit: view store validation and defaults of the legend keys. +- [ ] Integration: the hub keeps the legend state across a restart from its + view file. +- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: the scan, hide and + show on a tile and in a view, persistence across a reload and a second + browser; screenshots for the checkpoint. diff --git a/docs/requirements/README.md b/docs/requirements/README.md index a82fc1f..287e0b2 100644 --- a/docs/requirements/README.md +++ b/docs/requirements/README.md @@ -18,3 +18,6 @@ skill defines the format. - [012 - Match Review](012-match-review.md) - [013 - Voice Input](013-voice-input.md) - [014 - Header Rates](014-header-rates.md) +- [015 - Time Range in the Rates Panel](015-rates-time-range.md) +- [016 - Agents Controls in the View Row](016-agents-controls-row.md) +- [017 - Legend Toggle](017-legend-toggle.md)