diff --git a/examples/egocap/AGENTS.md b/examples/egocap/AGENTS.md index f588ebb366..59cae280d2 100644 --- a/examples/egocap/AGENTS.md +++ b/examples/egocap/AGENTS.md @@ -51,7 +51,7 @@ with its history can still work on it. ## Before reporting a change ready -Inspect changed paths against the intended MR base and audit path/install/dependency references. If an external configuration or CI edit is actually required, identify its exact path and purpose and obtain explicit user authorization before editing it. Do not silently broaden scope or duplicate files outside the allowed tree. +Inspect changed paths against the intended MR base and audit path/install/dependency references. Before any push, search the whole diff, the new files and the commit messages for internal names and for anything credential-like (keys, tokens, storage URLs, addresses of real machines); a clean result is a precondition, not a courtesy. If an external configuration or CI edit is actually required, identify its exact path and purpose and obtain explicit user authorization before editing it. Do not silently broaden scope or duplicate files outside the allowed tree. Run all three test suites per "Run the tests yourself" above — check each package's own coverage target, not one combined number (see `pyproject.toml`'s `[tool.coverage.run]` comment for why). diff --git a/examples/egocap/DESIGN.md b/examples/egocap/DESIGN.md index c41fd1ae27..26f7baac26 100644 --- a/examples/egocap/DESIGN.md +++ b/examples/egocap/DESIGN.md @@ -28,16 +28,29 @@ CaptureServer, serves the browser, and writes recorded sessions to local storage ### Operator workflow and station setup -A station belongs to one operator working at a time. A deployment's station file supplies that -station's label, its initial task instruction, the default operator name, the recording output -location, and the cameras it uses. At startup, the backend reads the station's camera names and +A station belongs to one operator working at a time. A site usually has several, so the stations +are kept by the backend and chosen from the page: each has a name, a camera type, the camera that +fills each role (the operator's view and each wrist), and the capture host address last given to +its headset. The station in use names every recording and its activity log. A deployment's station +file still supplies the initial task instruction, the default operator name, the recording output +location, the cameras requested from CaptureServer, and the station label used while no station has +been set up. At startup, the backend reads the station's camera names and types from the file and requests those streams from CaptureServer. An unconfigured deployment uses a fixed development default that requests no cameras; a configured-but-invalid station file blocks new recording until it is fixed. -Before recording, the operator identifies the station and confirms its camera and tracking -assignment, selects or enters the task being demonstrated, and confirms the live preview — camera -video and tracked pose — looks correct. Starting an episode requires every required source to be +The day follows a fixed order, shown as a progress rail: station, devices, record, wrap-up. The +operator puts their station in use and the page shows a live checklist of what that station needs: +every tracking device and camera, the calibration files of its cameras, and room on the recording +disk. Nothing is run; the checklist is judged continuously. With a station in use a take is refused, +with the reason, while any item fails; a device or check the station does not use is skipped. An +item fails for what would stop a take anyway (capture not running, no tracking data, a camera with +no frames) and for a full disk. What goes beyond that only warns: a device reporting another state +than connected, and missing calibration files, which are optional unless the deployment requires +them (an operator setting, off by default). With no stations set up the checklist only advises. + +Before recording, the operator also selects or enters the task being demonstrated, and confirms the +live preview — camera video and tracked pose — looks correct. Starting an episode requires every required source to be producing a current sample, not merely configured, so a camera or tracking source that has gone stale blocks a new take rather than starting one against outdated data. @@ -47,16 +60,26 @@ interrupting the session, and can rotate to a fresh batch of episodes when movin block of work. A kept take is checked automatically once it finishes writing, and any problem found is reported to the operator. -Offline analysis library functions give day's-end oversight, run as ad-hoc scripts rather than a -live page or CLI: a per-station activity log tracks active/inactive time through the day, and a -dataset-reporting function counts each station's valid versus excluded episodes and their recorded -duration from the saved session metadata, attributing each episode to the day it was actually -recorded rather than the session folder's own date. - -Maintenance library functions, likewise ad-hoc scripts rather than a live page or CLI, correct a -misfiled task or studio label and relocate a session saved in the wrong place: one relocates a -session to its correct studio location, another updates task and studio labels across a range of -episodes. Both update a session's bookkeeping; its recorded video and tracking stay as captured. +The station's time is observed, not entered. The backend logs through the day whether the station +could record or was down, and why, and counts active and down time between the first and last take +of the day, so a station left powered on outside working hours adds to neither. Each down period is +kept as a blocker with its reason, in a daily log written on the station. A take that was interrupted +and waits to be recovered or discarded counts as down, as does time the backend could not observe. + +At the end of the day a report lists every take of the day by session with what became of it: kept, +flagged, rejected, discarded, or still pending after an interruption. It is read from the recording +service's own record of each take, so a take that was not kept is counted rather than left out, and +each take belongs to the day it was actually recorded rather than the day its session was opened. +The report shows the station's active and down time with its blockers and the operator's notes, and +can be saved on the station. A dataset-reporting library function also counts each station's valid +versus excluded episodes from the saved session metadata, for offline use. + +A misfiled task can be corrected from the report for one take or a range of a session's takes. Only +labels change; recorded video and tracking stay as captured, and a session is never moved from the +page. A correction is refused for the session still open for recording, while a take of that session +is being time-aligned or another correction of it is being written, and for anything that is not a +recorded session inside the recording output. A library function, for offline use, relocates an +older session saved under the wrong studio. ### Timing and calibration requirements @@ -114,8 +137,9 @@ intrinsics and extrinsics, and the wrist cameras' intrinsics and calibration off preserved with the recording session alongside its episodes, so a take stays tied to the calibration active when it was captured rather than whatever calibration is live on the station later. Camera latency and glove calibration remain station-setup requirements this copying does -not archive; a station missing an optional calibration file can still record, just without that -sidecar present. Keeping a take commits all of this to the local record; discarding one removes +not archive. Calibration files are optional unless the deployment requires them: a station missing +one can still record, just without that sidecar present, and is held from recording only while the +operator setting that requires them is on. Keeping a take commits all of this to the local record; discarding one removes its recorded media, so a discarded take's video and tracking never appear in the saved session. ### Downstream dataset use @@ -273,9 +297,9 @@ to every connected viewer, with the specific reason behind any failure. ### Recordings browser (PoC demo, not part of the final design) A separate, optional browser page lists and downloads the files a station has already recorded, -reading directly from the recording output root. It is off by default; enabling it serves every -file under that root to anyone who can reach the backend, with no login, token, or origin check of -its own, so a deployment turns it on only where that exposure is acceptable. It is independent of +reading directly from the recording output root. It is off by default. Enabled, its listing and +every file need the control token, which the page exchanges once for a same-site cookie, and a +request a browser marks as coming from another site is refused. It is independent of the recording page: it never reconnects to CaptureServer and never affects a live session. ## 4. Assumptions and scope diff --git a/examples/egocap/README.md b/examples/egocap/README.md index c89d3ffde5..c98746b348 100644 --- a/examples/egocap/README.md +++ b/examples/egocap/README.md @@ -94,9 +94,10 @@ process that differs. - The **capture/recording page** (`frontend/`) is always served once built; see [`frontend/README.md`](frontend/README.md) for its development setup and the live protocol it consumes. -- The **recordings browser** (`recordings_frontend/`) is an optional, unauthenticated file - browser over the recording output root — off by default (`EGOCAP_RECORDINGS_ENABLED=1` to - enable). See [`recordings_frontend/README.md`](recordings_frontend/README.md). +- The **recordings browser** (`recordings_frontend/`) is an optional file browser over the + recording output root — off by default (`EGOCAP_RECORDINGS_ENABLED=1` to enable), and it asks + for the control token before it lists or serves anything. See + [`recordings_frontend/README.md`](recordings_frontend/README.md). ## Configuration diff --git a/examples/egocap/backend/README.md b/examples/egocap/backend/README.md index c2241b630e..089b101995 100644 --- a/examples/egocap/backend/README.md +++ b/examples/egocap/backend/README.md @@ -30,12 +30,17 @@ or restarts it. | `GET /stream{id}` | MJPEG camera preview, bound to the backend/session identity advertised in the `/api/session` snapshot. | | `GET /api/capture-status` | Thin HTTP inspection endpoint mirroring the latest snapshot; the frontend does not poll this during normal operation. | | `GET /api/settings` | The backend's effective configuration (CaptureServer URL, sources, station file, recording root, 3D view, origin policy), read-only and gated by the `X-Control-Token` header; the page's Advanced settings tab shows it. Secrets are reported as present or absent, never by value. | -| `GET`/`PUT /api/operator-settings` | The operator's station setup: the camera type (`sensing_gmsl` or `oak_d`), camera roles (`ego`, `wrist_left`, `wrist_right`), the task catalog the recording panel's picker offers (`task_file`) and the task it preselects (`preselected_task`). Kept in `.egocap/operator_settings.json` under the recording output (hidden from the recordings browser) (`EGOCAP_OPERATOR_SETTINGS_FILE` overrides the path) so every browser sees the same values. `PUT` names only the fields it changes and uses `X-Control-Token`; legacy JSON `control_token` remains accepted. A wrong token is 403 and bodies above 16 KiB are rejected with 413 before parsing. | +| `GET`/`PUT /api/operator-settings` | The operator's station setup: the camera type (`sensing_gmsl` or `oak_d`), camera roles (`ego`, `wrist_left`, `wrist_right`), the task catalog the recording panel's picker offers (`task_file`), the task it preselects (`preselected_task`) and whether calibration files are required before recording (`require_calibration`, a boolean, `false` by default; see [Start-of-day flow](#start-of-day-flow)). Kept in `.egocap/operator_settings.json` under the recording output (hidden from the recordings browser) (`EGOCAP_OPERATOR_SETTINGS_FILE` overrides the path) so every browser sees the same values. `PUT` names only the fields it changes and uses `X-Control-Token`; legacy JSON `control_token` remains accepted. A wrong token is 403 and bodies above 16 KiB are rejected with 413 before parsing. | +| `GET`/`POST /api/stations`, `PUT`/`DELETE /api/stations/{id}`, `POST /api/stations/select` | The station registry: the stations an operator chooses between and the one in use. A station is a name, a camera type, the camera filling each role and the capture host address last given to its headset. Kept in `stations.json` beside the operator settings. Every change uses `X-Control-Token` and answers with the new listing; a refusal is a 400 with the specific reason (a duplicate name, a camera in two roles, an unknown field), and an unknown id is 404. The station in use cannot be selected, edited or deleted while a take is being written, and a change that would start a new batch (selecting another station or none, renaming or deleting the station in use) is refused with `recover or discard the interrupted take first` while an interrupted take waits. A station's headset address is listed only when the `GET` carries the token. See [Stations](#stations). | +| `GET`/`POST /api/station-uptime` | What the station in use is doing now (`ready`, `recording`, or `down` with the reason) and its active and down time between today's first and last take, with each down period as a blocker (`end` is `null` for one that has not ended). It is observed by the backend, never set: `POST` (`X-Control-Token`) only saves the day's notes, with the body `{"station": , "notes": }`; when that is no longer the station in use the reply is a 409 and nothing is written. `GET` is open, and returns `notes` as an empty string unless it carries `X-Control-Token`: the notes are the operator's free text, and the end-of-day report, which needs the token, is where the page reads them. See [Stations](#stations). | +| `GET /api/setup` | The start-of-day flow: the four steps' states, the live station checklist (`checks`, each with a `status` of `pass`, `fail`, `warn` or `skip`), `enforced` (whether the checklist gates recording or only advises), `blocked_reason` (why station setup holds a take; only a failed item does) and, when the request carries `X-Control-Token`, `headset`: the capture host address to enter in the headset, the one remembered for the station in use, and whether that one stopped being valid. Everything in one reply describes one station: if the station in use keeps changing while it is gathered the reply is a 503 (`the station in use is changing; try again`). Read-only. See [Start-of-day flow](#start-of-day-flow). | +| `GET /api/day-report`, `POST /api/day-report/save`, `POST /api/day-report/correct` | The end-of-day report, all with `X-Control-Token`. `GET` returns today's takes for the station in use by session, with a count and duration per disposition (kept, flagged, rejected, discarded, pending, recording) read from the recording service's manifests, plus the station's time (`uptime`). `save` writes `__report.json` beside the daily log and refreshes that log's recorded time. `correct` rewrites the task of one take or a range of a session's takes (`session`, `episodes`, `task`). Each take carries `location`, where its data is under the recording output. See [End-of-day report](#end-of-day-report). | | `POST /api/task-files/import`, `DELETE /api/task-files/{name}` | Import a task catalog the operator supplies — by `name` + `content` (text uploaded from the browser) — into the imported-catalog directory beside the operator settings, once it parses; and remove an imported one. `POST` and `DELETE` use the `X-Control-Token` header (legacy JSON tokens remain accepted for `POST`); `DELETE` refuses removal of the selected catalog (409); imports also refuse replacement of that catalog until it is deselected. Imports appear in `GET /api/task-files` (as `imported`) and shadow a shipped catalog of the same name. | -| `GET /api/tools` | The operator tools the Settings drawer offers (headset calibration, glove calibration, fisheye rectification for the SENSING cameras), each with whether this build can launch it. None can yet. | +| `GET /api/tools` | The operator tools the Settings dialog's Devices tab lists (headset calibration, glove calibration, fisheye rectification for the SENSING cameras), each with whether this build can launch it. None can yet. | | `GET /api/livekit-token?room=ROOM` | Viewer token (subscribe and data messages, no media publishing) for a LiveKit room the session offers (404 otherwise, 503 without signing credentials). Which streams exist comes from CaptureServer's session message. | | `GET /api/task-files`, `GET /api/task-files/{name}` | Read-only task-catalog API; see [`../data/taskfiles/README.md`](../data/taskfiles/README.md). | -| `GET /recordings/...` | The optional recordings browser's API and file routes, off unless `EGOCAP_RECORDINGS_ENABLED=1`; see [`../recordings_frontend/README.md`](../recordings_frontend/README.md). | +| `POST /recordings/api/session` | Exchanges `X-Control-Token` for the recordings browser's same-site, HTTP-only cookie, scoped to `/recordings`. | +| `GET /recordings/...` | The optional recordings browser's API and file routes, off unless `EGOCAP_RECORDINGS_ENABLED=1`. The listing and every file need the control token (header) or that cookie, else 401, and a request from another site is 403; see [`../recordings_frontend/README.md`](../recordings_frontend/README.md). | Both frontends' built `dist/` directories are served as static assets from this same process once present (`uv run python build_support.py` from the project root builds them). @@ -51,6 +56,127 @@ configured-but-invalid file blocks new recording AND requests no cameras at all goes empty too, it is not unaffected), with a reason shown in the UI, never a silent fallback. Everything else is an environment variable: +### Stations + +A site usually has several stations, and an operator picks the one they are at. The registry +([`stations.py`](egocap_web/stations.py)) holds them; the Settings dialog's Station tab edits it. + +- **No stations** is the configuration-free default: the deployment's own station label applies and no station + rule blocks recording. +- **Once stations exist**, a take is refused until one is in use and can record: its ego role is assigned and every + camera it names is offered by the capture session. The reason is published as `not_ready_reason` in the recording + snapshot and returned by a refused `start_episode`. +- **Changing the station in use applies in process.** The label shown and recorded changes at once and the + recording batch rotates, so the next take opens a session carrying the new station's name. It is refused while a + take is being written. Any change to the station in use, its camera assignments included, holds a take for the + moment it is applied (`the station is being changed`), so none can open a session under the outgoing name or + record against cameras being reassigned; the batch rotates only when the label changes. While an interrupted + take waits to be recovered or discarded, a change that would rotate the batch is refused (`recover or discard + the interrupted take first`): a new batch would leave that take on disk with nothing on the page to resolve + it. Which cameras CaptureServer is asked for stays a deployment + setting (the station file); restarting the backend is the only way to change that. +- **The station in use holds the camera setup.** `GET /api/operator-settings` returns its camera type and roles, and + they are changed through the station routes; a `PUT` of those two fields to the operator settings is refused + while a station is in use. +- **Names.** Two names that would share one daily log file (they differ only in case or punctuation) are one name. + Renaming the station in use carries its day over: its timeline, its daily log and its saved report move to the + new name, and takes recorded under the old name stay part of its report. Once another station records under + the old name, that name's takes are that station's. +- **Headset address.** The backend remembers, per station, the capture host address its headset was given. It does + so by itself, once a headset is connected, and replaces the remembered one only when the host no longer has it + and the station and its saved address are still the ones that were looked at. + +### Station time + +Nobody marks a station active or blocked. Every two seconds the backend asks whether the station in use is +recording, ready to record, or down (a take would be refused for a station, device or capture reason) and logs the +day as segments ([`station_uptime.py`](egocap_web/station_uptime.py)). + +- **Active and down time are counted between the first and last take of the day**, so a station left powered on + outside working hours adds to neither. Each down period inside that window is a blocker, kept with the reason it + began with. A missing task or operator name is not downtime. An interrupted take waiting to be recovered or + discarded is: nothing records until it is resolved. +- A new state must hold for a few seconds before it is logged, so a device that flickers is not a blocker; the + start and end of a take are logged at once. +- Time nothing was sampled for more than a minute and a half (the backend was not running, or its host was + suspended) is logged as down. The log uses wall-clock time, so a forward clock step of more than that is + logged the same way. A day that crosses midnight is split there, and a take in progress at midnight brings + the old day's daily log up to it. A backend that stopped with the day still open and starts again on a later + day finishes that day first: its open segment ends where it was last seen, the rest of it is down, and its + daily log is brought up to its midnight. +- A daily log or a midnight split that could not be written is made good at the next save of the timeline, so + one failed write does not leave a day's log behind or lose a take that crossed midnight. +- A station's day holds a bounded number of segments. Past that its state is no longer logged and it reports + `down` with the reason that the day's log is full. +- Files, all under `station_status/` in the recording output, written atomically and never uploaded: + `_timeline.json` (the segments and the day's notes, written once the day has a take or notes), + `__activity.json` (the daily log: active and down time, blockers, recorded time; rewritten after + each take) and `__report.json` (the saved end-of-day report). + +### Start-of-day flow + +The flow is station, devices, record, wrap-up ([`setup_service.py`](egocap_web/setup_service.py), +[`setup_checks.py`](egocap_web/setup_checks.py)). With a station in use it gates recording; with none it only advises. + +- **The checklist is live.** There is nothing to run: a background duty judges it every second, and + `GET /api/setup` judges it afresh. It reads the calibration directory and the recording disk, so it is judged in + a worker thread, one evaluation at a time; a slow mount cannot stall the event loop that carries capture frames. +- **What holds a take** is a failed item, and an item fails only for what recording readiness itself refuses, plus + a full disk: the capture session not running, no recent tracking sample, a station camera that is not offered, + delivers no recent frame or, for a LiveKit camera, cannot be recorded, and less than 10 GB free on the disk + holding the recording output. +- **What only warns** (`warn`) is shown with its reason and never holds a take; the Devices step stays done and + names it. A tracking device or a camera that reports another state than connected warns: readiness judges the + data that arrives, not the state a device reports, and a station may leave a controller or a glove unused. +- **Calibration files are optional unless the deployment requires them.** The files of the roles in use are + looked for under `EGOCAP_CALIBRATION_DIR` (head intrinsics and extrinsics, each wrist's intrinsics, and the + wrist offsets once a wrist is assigned); calibration is skipped for a mock session. A missing or unreadable + file warns. With the operator setting `require_calibration` on, the same item fails and holds recording. +- **Skipped, never failed:** a role the station leaves unassigned, and any check that does not apply. +- **Record follows the day, not the batch.** The step is done once the station in use has a take in today's + timeline, so it stays done after a new batch or a restart and starts over at midnight; the current batch's + saved count is only a detail. +- **The gate** decides whether a take is admitted and the readiness that is published. It never interrupts a take: + a setup fact changing mid-take does not stop it, unlike a capture source going stale. It is asked on the event + loop, during a take too, and answers from the last evaluation in memory. Until the station in use has been + judged (at startup, just after it changed, or when the last result is more than ten seconds old because an + evaluation is stuck) a take is held with `the station checks are being evaluated`. A checklist that cannot be + evaluated holds the take and is logged; it never raises into a viewer's connection. + +### End-of-day report + +[`egocap.analytics.day_report`](../recording/egocap/analytics/day_report.py) reads each session's manifests, so every +take is counted with what became of it: + +| Disposition | Meaning | +| --- | --- | +| kept | Finalized, and capture quality did not mark it bad. | +| flagged | Finalized and kept, but capture quality marked its data bad. | +| rejected | Failed its check; a camera failure also removed its media. | +| discarded | The operator discarded it. | +| pending | Interrupted before it finished; it waits to be recovered or discarded. | +| recording | The take being written right now. | + +A take belongs to the day in its finalized episode's `recorded_at`, else the day its manifest was last checkpointed. +A session whose name says it was opened on a later day than the report's is passed over without being read; one +opened on that day or earlier, or with no date in its name, is always read, since it may hold the day's takes. +A manifest that cannot be read, or that holds values of the wrong shape, is reported with its session, never dropped. + +A correction ([`day_report_routes.py`](egocap_web/day_report_routes.py)) accepts only a recorded session inside the +recording output: a recording-service session directly under it, or a studio's group one level below that carries +the recording service's route stamp. The path is resolved first, so a traversal, an absolute path or a link out is +refused, as is a time-aligned copy that leads out. A time-aligned copy or a single episode is never a target of its +own: the copy is corrected with its session. A value the filesystem cannot look up is refused like any other +directory that is not a session, and a range covers at most 10,000 takes. +It is refused while a take is being written and for the session still open for recording, including that session's +routed groups; an interrupted take holds only its own session. It is also refused, to be tried again, while a take +of that session is being time-aligned, since the copy being built already has the old label, and while another +correction of that session is being written. One lock per session ([`session_locks.py`](egocap_web/session_locks.py)) +is held by the correction across every file it writes and by the aligner across a whole alignment, so an episode +waiting to be aligned does not start in the middle of a correction. Each metadata file is +replaced whole, both task labels of a take are kept in step, and the session's own task label changes only when +every take was corrected. Nothing is ever moved. + | Variable | Default | Meaning | | --- | --- | --- | | `EGOCAP_STATION_CONFIG` | unset (development default) | Path to the deployment station YAML described above. | diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py index 80dda3f7bf..c99fd516ce 100644 --- a/examples/egocap/backend/egocap_web/app.py +++ b/examples/egocap/backend/egocap_web/app.py @@ -30,7 +30,9 @@ CalibrationAsset, ConfigurationError, QcConfig, + RecordingPhase, ServiceConfig, + StateError, VideoSourceSpec, ) @@ -38,6 +40,8 @@ from .capture_preview import MAX_CAMERA_JPEG_BYTES from .capture_status import CaptureStatusMonitor from .config import VisualizationConfig, config_from_env, visualization_from_env +from .day_report_routes import router as day_report_router +from .host_addresses import headset_addresses from .livekit_preview import API_KEY_ENV, API_SECRET_ENV, subscriber_token from .livekit_preview import router as livekit_preview_router from .livekit_receiver import RECEIVER_FRAMES_PER_STREAM @@ -56,12 +60,19 @@ RecordingAdapterError, validate_tracking_descriptor, ) -from .recording_command import RecordingContext -from .recording_session import RecordingSessionCoordinator, TaskContext +from .recording_command import RecordingContext, interrupted_take +from .recording_session import CoordinatorBusyError, RecordingSessionCoordinator, TaskContext from .recordings import router as recordings_router +from .session_locks import SessionLocks from .settings_routes import EffectiveSettings from .settings_routes import router as settings_router +from .setup_routes import router as setup_router +from .setup_service import CHECKLIST_SECONDS, SetupService, capture_facts from .station_config import ResolvedStation, StationConfigError, load_station_config, station_config_path_from_env +from .station_routes import router as station_router +from .station_service import TAKE_IN_PROGRESS, StationService, session_adapter +from .station_uptime import DOWN, READY, RECORDING, UPTIME_DIR, UptimeLog, UptimeSampler +from .stations import StationError, StationStore, station_store_path from .task_file_routes import router as task_file_router from .viser_scene import VisualizationScene @@ -141,9 +152,10 @@ def _recording_output_root(station_data_dir: Path | None = None) -> Path: # Per-station calibration files copied into every new session (and, once there, into each -# routed group) when present at EGOCAP_CALIBRATION_DIR. All optional: a station that hasn't -# captured one yet must not be blocked from recording -- see ServiceConfig.calibration_assets' -# own required=False handling for the same reason the old per-manager copy only ever warned. +# routed group) when present at EGOCAP_CALIBRATION_DIR. Calibration files are optional unless +# the deployment requires them: the copy never fails for a missing one (required=False), and a +# station in use is held from recording only while the operator setting require_calibration is +# on (see setup_checks.py). _STATION_CALIBRATION_FILES = ( "head_camera_intrinsics.json", "head_camera_extrinsics.json", @@ -171,7 +183,7 @@ def _recorder_livekit_token(room: str) -> str: def _recording_config_factory( monitor: CaptureStatusMonitor, - station_label: str | None, + station_label: str | None | Callable[[], str | None], output_root: Path, on_video_sources: Callable[[frozenset[str], frozenset[str]], None] | None = None, ): @@ -185,7 +197,10 @@ def _recording_config_factory( (``recording_adapter.convert_camera_image``'s ``intrinsics`` param is always ``None`` today); declaring a schema that doesn't require them is the honest choice until that plumbing is added, rather than manufacturing - calibration values the backend doesn't actually have.""" + calibration values the backend doesn't actually have. + + ``station_label`` may be a callable, read at each session open, so a session opened after the operator + changes the station in use carries the new station's name.""" def factory() -> ServiceConfig: video_sources = tuple( @@ -216,7 +231,7 @@ def factory() -> ServiceConfig: video_sources=video_sources, qc=QcConfig(required_sources=required), calibration_assets=_station_calibration_assets(), - station_label=station_label, + station_label=station_label() if callable(station_label) else station_label, ) largest_decoded_frame_bytes = max((cam.width * cam.height * 3 for cam in video_sources), default=0) if largest_decoded_frame_bytes > 0: @@ -325,6 +340,109 @@ def check() -> tuple[bool, str | None]: return check +#: The recording phases in which no take is being written, so the station in use may change. +_STATION_CHANGE_PHASES = (RecordingPhase.IDLE, RecordingPhase.RECOVERY_REQUIRED, RecordingPhase.CLOSED) + + +def _station_change_blocked(coordinator: RecordingSessionCoordinator) -> str | None: + """Why the station in use cannot change now: a take is being recorded or a recording command is still + running. An interrupted take waiting for recovery does not block; it stays with the session it was in.""" + snapshot = coordinator.snapshot() + writing = snapshot.service is not None and snapshot.service.phase not in _STATION_CHANGE_PHASES + return TAKE_IN_PROGRESS if writing or snapshot.active_operation is not None else None + + +#: The reason the station is logged down while an interrupted take waits to be recovered or discarded. +INTERRUPTED_TAKE = "an interrupted take needs recovery" +#: Why a change that would start a new batch is refused while an interrupted take waits. +RESOLVE_INTERRUPTED_TAKE = "recover or discard the interrupted take first" +#: Why a station change is refused while the recording session cannot end its batch, by what stopped it. +STATION_CHANGE_BUSY = "the recording session is busy; finish the current take before changing stations" +STATION_CHANGE_REFUSED = "the recording session cannot change stations in its current state" + +#: How often the station's state is asked for the uptime log; a take's start and end are logged this late at most. +_UPTIME_SAMPLE_SECONDS = 2.0 +#: How often a connected headset's host address is compared with the one remembered for the station. +_HEADSET_MEMORY_SECONDS = 30.0 + + +def _station_state( + coordinator: RecordingSessionCoordinator, context: RecordingContext, stations: StationService +) -> tuple[str, str, str | None]: + """The station in use and whether it is recording, ready to record, or down and why. Down means a take + would be refused for a station, device or capture reason; a missing task or operator name is not downtime.""" + station = stations.label() + service = coordinator.snapshot().service + # An interrupted take is still the service's episode, but nothing records until it is resolved. + if interrupted_take(service): + return station, DOWN, INTERRUPTED_TAKE + if service is not None and service.episode is not None: + return station, RECORDING, None + blocked = context.setup_block() + if blocked is not None: + return station, DOWN, blocked + ready, reason = coordinator.readiness() + if not ready: + return station, DOWN, reason or "capture is not ready" + return station, READY, None + + +async def _remember_headset_address( + stations: StationService, setup: SetupService, capture_server_url: str +) -> None: + """Keep, for the station in use, the capture host address its headset is evidently using. + + A connected headset proves it was given an address that works. The remembered one is replaced only when it + is no longer one of the host's, so an operator's choice among several valid addresses is never overwritten. + """ + selected = stations.registry.selected + if selected is None or not setup.headset_connected(): + return + candidates = await asyncio.to_thread(headset_addresses, capture_server_url) + addresses = [candidate.address for candidate in candidates] + if addresses and selected.headset_address not in addresses: + # Another station may have been put in use during the await; the service checks what was seen here. + await stations.remember_headset_address(selected.station_id, selected.headset_address, addresses[0]) + + +async def _every(seconds: float, duty: Callable[[], Any], what: str) -> None: + """Run a background duty at an interval for as long as the application runs. One failed pass is logged + and the next still runs: these duties keep records, and must never take the application down.""" + failure: str | None = None + while True: + try: + await duty() + # Said once, so the log shows when a fault that was reported ended. + if failure is not None: + logger.info("%s is working again", what) + failure = None + except Exception as exc: # noqa: BLE001 -- see the docstring + # Logged when the cause changes, not at every pass, or a disk that stays full would fill the log. + if repr(exc) != failure: + failure = repr(exc) + logger.exception("%s failed", what) + await asyncio.sleep(seconds) + + +async def _rotate_batch_for_station(coordinator: RecordingSessionCoordinator) -> None: + """Ends the current batch so the next take opens a session under the new station label. A session's + configuration is frozen when it opens, so the label can only change between sessions. + + Refused while an interrupted take waits: a new batch would leave it on disk with nothing on the page to + recover or discard it, and the station would stop being logged as down for it.""" + if interrupted_take(coordinator.snapshot().service): + raise StationError(RESOLVE_INTERRUPTED_TAKE) + try: + await coordinator.new_batch() + except CoordinatorBusyError as exc: + # The cause stays in the log: its text is the coordinator's own and not written for the page. + logger.info("A station change was refused while the recording session was busy: %s", exc) + raise StationError(STATION_CHANGE_BUSY) from exc + except StateError as exc: + logger.info("A station change was refused by the recording session's state: %s", exc) + raise StationError(STATION_CHANGE_REFUSED) from exc + + @asynccontextmanager async def lifespan(app: FastAPI) -> AsyncIterator[None]: """Creates and starts the one CaptureStatusMonitor for the station, @@ -418,16 +536,23 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: lambda: recordable_livekit_streams(monitor.native.started), _recorder_livekit_token, ) + # Shared by the aligner and the end-of-day correction: whichever holds a session's lock has its labels. + session_locks = SessionLocks() + app.state.session_locks = session_locks # Kept episodes are time-aligned in the background when the station configures an index camera. aligner = ( - AutoAligner(recording_output_root, resolved_station.alignment_index) + AutoAligner(recording_output_root, resolved_station.alignment_index, session_locks) if resolved_station is not None and resolved_station.alignment_index is not None else None ) + # The station's time today, observed rather than entered: see the sampler started below. + station_uptime = UptimeLog(recording_output_root / UPTIME_DIR) + app.state.station_uptime = station_uptime coordinator = RecordingSessionCoordinator( _recording_config_factory( monitor, - config.station_label, + # Read at each session open: the station service below owns the label once it exists. + lambda: station_service.label(), recording_output_root, aligner.note_video_sources if aligner is not None else None, ), @@ -439,6 +564,30 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: tracking_latency=resolved_station.latency if resolved_station is not None else None, ) monitor.set_recording(coordinator) + # The station registry sits beside the operator settings. Its selected station names what is recorded and + # shown; with no station selected the deployment's own label stays in effect. + station_service = StationService( + StationStore(station_store_path(operator_settings_file)), + session_adapter( + offered_cameras=monitor.offered_camera_names, + change_blocked=lambda: _station_change_blocked(coordinator), + show_label=monitor.set_station_label, + rotate_batch=lambda: _rotate_batch_for_station(coordinator), + renamed=station_uptime.rename, + ), + default_label=config.station_label, + ) + app.state.station_service = station_service + monitor.set_station_label(station_service.label()) + # The start-of-day flow: the live station checklist, which gates a take for a station in use. + setup_service = SetupService( + facts=lambda: capture_facts(monitor, config), + stations=station_service, + calibration_dir=calibration_dir, + output_root=recording_output_root, + require_calibration=app.state.operator_settings_store.calibration_required, + ) + app.state.setup_service = setup_service await monitor.start() app.state.monitor = monitor # Generated once per backend process start (a restart is the only way @@ -451,7 +600,10 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: print(f"Recording control token for this run: {control_token}", file=sys.stderr, flush=True) auto_fill_operator_name = resolved_station.auto_fill_operator_name if resolved_station is not None else False app.state.recording_context = RecordingContext( - coordinator=coordinator, control_token=control_token, auto_fill_operator_name=auto_fill_operator_name + coordinator=coordinator, + control_token=control_token, + auto_fill_operator_name=auto_fill_operator_name, + setup_gate=setup_service.block_reason, ) # The 3D view settings are read once, for the view itself and for the settings report. visualization_config: VisualizationConfig | None = None @@ -470,7 +622,27 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: visualization_error=visualization_error, task_file_root=task_file_root, ) - # Kept episodes are time-aligned in the background when the station configures an index camera. + # The station's state is sampled every few seconds for the uptime log. + sampler = UptimeSampler() + + async def sample_uptime() -> None: + """Ask what the station is doing and log it; the file write stays off the event loop.""" + observed = sampler.settle(*_station_state(coordinator, app.state.recording_context, station_service)) + await asyncio.to_thread(station_uptime.observe, *observed) + + # Owned by the lifespan: all stop with the application. + duties = [ + # The gate answers from this duty's last result; a station in use is held until the first one. + asyncio.create_task(_every(CHECKLIST_SECONDS, setup_service.refresh, "the station checklist")), + asyncio.create_task(_every(_UPTIME_SAMPLE_SECONDS, sample_uptime, "the uptime sample")), + asyncio.create_task( + _every( + _HEADSET_MEMORY_SECONDS, + lambda: _remember_headset_address(station_service, setup_service, config.capture_server_url), + "remembering the headset address", + ) + ), + ] aligner_task: asyncio.Task[None] | None = None if aligner is not None: coordinator.on_episode_kept = aligner.submit @@ -482,6 +654,9 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: await visualization.start() # never raises: a failed start only reports the view unavailable yield finally: + for duty in duties: + duty.cancel() + await asyncio.gather(*duties, return_exceptions=True) try: if visualization is not None: await visualization.stop() @@ -517,6 +692,9 @@ def _optional_visualization( app.include_router(task_file_router) app.include_router(settings_router) app.include_router(operator_settings_router) +app.include_router(station_router) +app.include_router(setup_router) +app.include_router(day_report_router) # PoC demo integration: browse/download recorded files, off unless # EGOCAP_RECORDINGS_ENABLED=1. Not part of the final system design -- see # recordings.py's own module docstring. diff --git a/examples/egocap/backend/egocap_web/auto_align.py b/examples/egocap/backend/egocap_web/auto_align.py index 28cfcabe10..086ed1e090 100644 --- a/examples/egocap/backend/egocap_web/auto_align.py +++ b/examples/egocap/backend/egocap_web/auto_align.py @@ -10,6 +10,10 @@ logged with the reason and left as recorded; the raw episode is never modified. Output is published by one rename, so an alignment that is killed leaves no partial result. At startup the worker re-queues the kept episodes that still have no aligned copy. + +The child copies an episode's labels into the aligned copy, so the worker holds the session's lock +(session_locks.py) for the whole alignment: a task correction of that session is refused meanwhile, and an +episode waiting its turn does not start while a correction is being written. """ from __future__ import annotations @@ -32,12 +36,16 @@ ) from recording_service import Disposition, EpisodeResult +from .session_locks import ALIGNER, SessionLocks + logger = logging.getLogger("isaaccapture.egocap_web.auto_align") #: The command-line aligner, run once per episode. _ALIGN_TOOL = Path(__file__).resolve().parents[2] / "recording" / "tools" / "align_episode.py" #: A staging directory untouched this long belongs to a run that is no longer going. _STALE_STAGING_SECONDS = 24 * 3600 +#: How soon the worker looks again when a correction holds the session it is about to align. +_LOCK_RETRY_SECONDS = 0.2 @dataclass(frozen=True) @@ -62,10 +70,12 @@ def refused_marker(self) -> Path: class AutoAligner: """Aligns kept episodes one at a time on its own worker task.""" - def __init__(self, output_root: Path, index_source: str) -> None: - """``output_root`` holds the recording sessions; ``index_source`` is the camera that sets the timeline.""" + def __init__(self, output_root: Path, index_source: str, locks: SessionLocks | None = None) -> None: + """``output_root`` holds the recording sessions; ``index_source`` is the camera that sets the timeline; + ``locks`` is shared with whatever else rewrites a session's labels (none does when it is omitted).""" self._output_root = output_root self._index_source = index_source + self._locks = locks if locks is not None else SessionLocks() # Unbounded: a job is three small fields, and the number waiting is the number of kept episodes. self._queue: asyncio.Queue[_Job] = asyncio.Queue() self._process: asyncio.subprocess.Process | None = None @@ -146,12 +156,24 @@ async def run(self) -> None: while True: job = await self._queue.get() try: - await self._align(job) + await self._align_holding(job) except Exception as exc: # noqa: BLE001 - one episode's failure must not end the worker logger.warning("%s episode %d was not time-aligned: %s", job.session_id, job.episode_index, exc) finally: self._queue.task_done() + async def _align_holding(self, job: _Job) -> None: + """Align one episode while holding its session's lock, so its labels cannot change under the copy.""" + # Resolving asks the filesystem, which stays off the event loop. + group = await asyncio.to_thread(job.final.parent.resolve) + # A correction is brief; waiting here, not in a thread, keeps a shutdown able to cancel the wait. + while self._locks.acquire(group, ALIGNER) is not None: + await asyncio.sleep(_LOCK_RETRY_SECONDS) + try: + await self._align(job) + finally: + self._locks.release(group) + async def close(self, task: asyncio.Task[None], timeout: float) -> None: """Let the queued episodes finish for up to ``timeout`` seconds, then stop the worker ``task``. diff --git a/examples/egocap/backend/egocap_web/capture_status.py b/examples/egocap/backend/egocap_web/capture_status.py index 0b92e7c299..692ff998c8 100644 --- a/examples/egocap/backend/egocap_web/capture_status.py +++ b/examples/egocap/backend/egocap_web/capture_status.py @@ -328,6 +328,23 @@ def camera_descriptors(self) -> tuple[p.CameraStream, ...]: return () return tuple(s for s in self.native.started.streams if isinstance(s, p.CameraStream)) + def offered_camera_names(self) -> frozenset[str] | None: + """Names of every camera the accepted session offers, CaptureServer's own and LiveKit streams alike; + None before a session has been accepted, when what it offers is not known yet.""" + if self.native.started is None: + return None + return frozenset( + s.name for s in self.native.started.streams if isinstance(s, (p.CameraStream, p.LiveKitCameraStream)) + ) + + def set_station_label(self, label: str) -> None: + """Replaces the station label every status and preview snapshot carries. The revision advances so + each viewer is sent the change, the same as any other lifecycle fact.""" + if label == self._station_label: + return + self._station_label = label + self.revision += 1 + def camera_descriptor_by_stream_id(self, stream_id: int) -> p.CameraStream | None: """The accepted camera descriptor advertising this stream ID, if any.""" for cam in self.camera_descriptors: diff --git a/examples/egocap/backend/egocap_web/day_report_routes.py b/examples/egocap/backend/egocap_web/day_report_routes.py new file mode 100644 index 0000000000..29ed03fb47 --- /dev/null +++ b/examples/egocap/backend/egocap_web/day_report_routes.py @@ -0,0 +1,286 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""HTTP surface for the end-of-day report: today's takes for the station in use, saving the report, and +correcting a task. + +The report is read from the recording service's manifests (``egocap.analytics.day_report``), so it shows what +became of every take, with the station's time from the uptime log. Everything here needs the run's control +token: the report names operators and tasks, and the correction rewrites recorded metadata. + +A correction is confined to a recorded session inside the recording output, refused for the session open for +recording, while a take is being written and while that session's take is being time-aligned, and replaces +each metadata file whole. It holds the session's lock (session_locks.py) from its first write to its last, so +neither the aligner nor a second correction can come between them. It changes labels only; recorded video and +tracking stay as captured, and nothing is ever moved. +""" + +from __future__ import annotations + +import asyncio +import datetime +import json +import logging +import re +import time +from pathlib import Path +from typing import Any + +from fastapi import APIRouter, Request +from fastapi.responses import JSONResponse + +from egocap.analytics.day_report import build_day_report, recorded_seconds +from egocap.data_processing.update_episode_task_description import ( + EpisodeRangeError, + update_episode_task_description, +) +from egocap.recording.episode_layout import MANIFEST_DIR, ROUTE_ATTR + +from .recording_command import MAX_TASK_DETAILS_CHARS, control_token_valid, interrupted_take +from .request_body import read_authorized_json +from .session_locks import ALIGNER, CORRECTION, SessionLocks + +logger = logging.getLogger("isaaccapture.egocap.day_report_routes") + +router = APIRouter() + +_NO_STORE = {"Cache-Control": "no-store"} +_MAX_BODY_BYTES = 16 * 1024 +#: Longer than any session path under the output; a longer one is refused before the filesystem is asked. +_MAX_SESSION_CHARS = 512 +#: Room for a range of two long numbers; a longer value is not a take or a range. +_MAX_EPISODES_CHARS = 32 +_NOT_A_SESSION = "that directory is not a recorded session" +_EPISODE_DIR = re.compile(r"episode_\d+") + + +class DayReportError(ValueError): + """A refused correction, with a public, path-free reason.""" + + +def _reply(body: dict[str, Any], status: int = 200) -> JSONResponse: + """A non-cacheable JSON reply: the day changes with every take.""" + return JSONResponse(body, status_code=status, headers=_NO_STORE) + + +def _state(request: Request) -> tuple[Any, Any, Any, Path] | None: + """The recording context, station service, uptime log and recording output, or None before startup.""" + state = request.app.state + names = ("recording_context", "station_service", "station_uptime", "recording_output_root") + found = tuple(getattr(state, name, None) for name in names) + return None if any(item is None for item in found) else found # type: ignore[return-value] + + +def _active_episode_id(snapshot: Any) -> str | None: + """The take being recorded now, so the report does not call it interrupted. A take that was interrupted + is not one: it is still the service's episode, and the report shows it as pending.""" + service = snapshot.service + if service is None or service.episode is None or interrupted_take(service): + return None + return service.episode.episode_id + + +def _gather(state: tuple[Any, Any, Any, Path], snapshot: Any) -> dict[str, Any]: + """Today's report for the station in use, with its time; runs in a worker thread, since it walks the disk. + ``snapshot`` is the recording coordinator's, taken on the event loop that owns its state.""" + _context, stations, uptime, root = state + today = datetime.date.fromtimestamp(time.time()).isoformat() + station = stations.label() + # A station renamed today recorded its earlier takes under the old name; they are still its day. + report = build_day_report( + root, today, stations=uptime.names(station), active_episode_id=_active_episode_id(snapshot) + ) + return { + "report": {**report, "station": station}, + "uptime": uptime.report(station), + "today": today, + "station_in_use": station, + } + + +@router.get("/api/day-report") +async def read_day_report(request: Request) -> JSONResponse: + """Today's takes for the station in use, by session, with totals per disposition and the station's time.""" + state = _state(request) + if state is None: + return _reply({"detail": "the report is not available yet"}, 503) + if not control_token_valid(request.headers.get("x-control-token"), state[0].control_token): + return _reply({"detail": "control token rejected"}, 403) + return _reply(await asyncio.to_thread(_gather, state, state[0].coordinator.snapshot())) + + +def _save(state: tuple[Any, Any, Any, Path], snapshot: Any) -> dict[str, Any]: + """Write the report beside the daily log and refresh that log's recorded time; in a worker thread.""" + _context, _stations, uptime, _root = state + gathered = _gather(state, snapshot) + station = gathered["station_in_use"] + saved = {**gathered, "generated_at": datetime.datetime.now().isoformat(timespec="seconds")} + name = uptime.save_report(station, saved) + # The uptime log cannot measure what was recorded; the report gives the daily log that figure. + total, kept = recorded_seconds(gathered["report"]) + activity_log = uptime.write_log(station, data_seconds=total, valid_seconds=kept) + return {**gathered, "saved": {"report": name, "activity_log": activity_log}} + + +@router.post("/api/day-report/save") +async def save_day_report(request: Request) -> JSONResponse: + """Save today's report as JSON on this machine and bring the daily log up to date.""" + state = _state(request) + if state is None: + return _reply({"detail": "the report is not available yet"}, 503) + body, refused = await read_authorized_json(request, state[0].control_token, _MAX_BODY_BYTES) + if body is None: + return refused # type: ignore[return-value] + try: + return _reply(await asyncio.to_thread(_save, state, state[0].coordinator.snapshot())) + except OSError: + logger.exception("Could not save the day report") + return _reply({"detail": "could not save the report"}, 503) + + +def _route_stamp(directory: Path) -> str | None: + """The stamp the recording service leaves on a routed group, naming the session that fills it, or None + when the directory carries none it can read.""" + try: + stamp = json.loads((directory / "zarr.json").read_text()).get("attributes", {}).get(ROUTE_ATTR) + except (OSError, ValueError, AttributeError): + return None + return stamp if isinstance(stamp, str) else None + + +def _confined_session(root: Path, raw: Any) -> Path: + """A recorded session named relative to the recording output, refused unless it really is one inside it. + + Only two shapes hold recorded episodes: a recording-service session directly under the output, and a + studio's group one level below. Anything else would have metadata written into a place that has none. + """ + if not isinstance(raw, str) or raw.strip() == "": + raise DayReportError("session must be a path under the recording output") + # A NUL or an over-long name makes the path calls raise instead of answering. + if "\x00" in raw or len(raw) > _MAX_SESSION_CHARS: + raise DayReportError(_NOT_A_SESSION) + try: + return _recorded_session(root.resolve(), raw) + except OSError: + # A name the filesystem will not even look up is not a session; the cause is not the caller's to read. + raise DayReportError(_NOT_A_SESSION) from None + + +def _recorded_session(base: Path, raw: str) -> Path: + """The recorded session ``raw`` names under the resolved output ``base``; refused otherwise.""" + target = (base / raw).resolve() + # Resolved first, so a traversal, an absolute path or a link out of the output are all caught here. + if base not in target.parents: + raise DayReportError("the session is outside the recording output") + parts = target.relative_to(base).parts + if any(part.startswith(".") for part in parts) or not target.is_dir(): + raise DayReportError(_NOT_A_SESSION) + # A time-aligned copy and a single episode are corrected with the session they belong to, never alone. + if any(part.endswith("_aligned") for part in parts) or _EPISODE_DIR.fullmatch(target.name): + raise DayReportError(_NOT_A_SESSION) + session = len(parts) == 1 and (target / MANIFEST_DIR).is_dir() + # A routed group is known by the recording service's stamp, not by what the directory happens to lack. + group = len(parts) == 2 and _route_stamp(target) is not None + if not (session or group): + raise DayReportError(_NOT_A_SESSION) + # The time-aligned copy beside a session is rewritten with it, so it must be inside the output too. + aligned = target.with_name(f"{target.name}_aligned") + if aligned.is_symlink() or (aligned.exists() and base not in aligned.resolve().parents): + raise DayReportError("the session's aligned copy is outside the recording output") + # An episode is written through its own directory, so one that is a link would lead the write elsewhere. + if any(episode.is_symlink() for tree in (target, aligned) for episode in tree.glob("episode_*")): + raise DayReportError("the session holds a linked episode and cannot be corrected here") + return target + + +def _owned_by(session: Any, directory: Path) -> bool: + """Whether a directory is the open session itself or a routed group stamped as that session's.""" + try: + if directory.samefile(session.session_path): + return True + except OSError: + # A session path that cannot be compared is not this directory; the route stamp below still decides. + pass + stamp = _route_stamp(directory) + return stamp is not None and stamp.startswith(f"{session.session_id}|") + + +def _refuse_while_recording(snapshot: Any, target: Path) -> None: + """Refuse a correction while a take is being written, or to the session still open for recording. + + ``snapshot`` is from the moment the request was admitted. A take that starts after it cannot reach the + target: a take is written to the session open then, which is refused here, or to a session opened later, + which is always a new directory with route stamps of its own. + """ + service = snapshot.service + # An interrupted take is not being written; its session is still open, which the check below refuses. + writing = service is not None and service.episode is not None and not interrupted_take(service) + if snapshot.active_operation is not None or writing: + raise DayReportError("finish or discard the current take before correcting a session") + if service is not None and service.session is not None and _owned_by(service.session, target): + raise DayReportError("this session is still open for recording; start a new batch first") + + +#: Why a correction is refused while the session's labels are held, by who holds them. +_HELD = { + # The aligner copies a take's labels before it publishes the copy; a correction made in between would + # reach the recording and miss the copy. An alignment can take minutes, so the correction does not wait. + ALIGNER: "time alignment of this take is still running; try again in a moment", + # Two corrections interleaved would leave the episodes, config.yaml and the aligned copy disagreeing. + CORRECTION: "another correction of this session is still being written; try again in a moment", +} + + +def _correct( + state: tuple[Any, Any, Any, Path], snapshot: Any, body: dict[str, Any], locks: SessionLocks +) -> dict[str, Any]: + """Apply one task correction; runs in a worker thread. ``snapshot`` is the recording coordinator's, taken + on the event loop that owns its state, and ``locks`` is shared with the background aligner.""" + _context, _stations, _uptime, root = state + target = _confined_session(root, body.get("session")) + _refuse_while_recording(snapshot, target) + task, episodes = body.get("task"), body.get("episodes") + if not isinstance(task, str) or task.strip() == "" or len(task) > MAX_TASK_DETAILS_CHARS: + raise DayReportError(f"task must be text of 1 to {MAX_TASK_DETAILS_CHARS} characters") + if not isinstance(episodes, str) or len(episodes) > _MAX_EPISODES_CHARS: + raise DayReportError("episodes must be a take or a range, such as 3 or 2-7") + # Held across every file the correction writes; the aligner takes the same lock before it copies labels. + holder = locks.acquire(target, CORRECTION) + if holder is not None: + raise DayReportError(_HELD[holder]) + try: + result = update_episode_task_description(target, episodes, task_description=task.strip()) + except EpisodeRangeError as exc: + raise DayReportError(f"episodes: {exc}") from None + except (OSError, ValueError): + # The library's messages carry paths; the cause goes to the log and the operator gets the outcome. + logger.exception("A task correction could not be written") + raise DayReportError("the session's metadata could not be updated") from None + finally: + locks.release(target) + return { + "session": result.zarr_root.relative_to(root.resolve()).as_posix(), + "updated": result.updated_episodes, + "missing": result.missing_episodes, + "config_updated": result.config_yaml_updated, + } + + +@router.post("/api/day-report/correct") +async def correct_session(request: Request) -> JSONResponse: + """Correct the task of one take or a range of a session's takes.""" + state = _state(request) + locks = getattr(request.app.state, "session_locks", None) + if state is None or locks is None: + return _reply({"detail": "the report is not available yet"}, 503) + body, refused = await read_authorized_json(request, state[0].control_token, _MAX_BODY_BYTES) + if body is None: + return refused # type: ignore[return-value] + try: + # Read here, not in the worker: the coordinator's state changes on this loop, so a thread could see + # its fields part-way through a change. + snapshot = state[0].coordinator.snapshot() + return _reply(await asyncio.to_thread(_correct, state, snapshot, body, locks)) + except DayReportError as exc: + return _reply({"detail": str(exc)}, 400) diff --git a/examples/egocap/backend/egocap_web/host_addresses.py b/examples/egocap/backend/egocap_web/host_addresses.py new file mode 100644 index 0000000000..7ea9a59370 --- /dev/null +++ b/examples/egocap/backend/egocap_web/host_addresses.py @@ -0,0 +1,156 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The capture host address an operator enters in the headset. + +The headset connects to the capture host over the local network, so the operator needs that host's address. When +CaptureServer runs on this machine the candidates are this machine's own IPv4 addresses, wireless first: a +headset is on the wireless network, and a wired link is often a point-to-point cable to another device. When +CaptureServer runs elsewhere its own host is the only candidate. +""" + +from __future__ import annotations + +import fcntl +import ipaddress +import socket +import struct +import sys +from collections.abc import Callable, Iterable +from dataclasses import dataclass +from urllib.parse import urlsplit + +#: Linux ``ioctl`` request that returns an interface's IPv4 address. +_SIOCGIFADDR = 0x8915 + +WIRELESS, WIRED, OTHER, CAPTURE_SERVER = "wireless", "wired", "other", "capture_server" + +#: Interface name prefixes, by the kind of link they name on Linux. +_KIND_PREFIXES = ((WIRELESS, ("wl",)), (WIRED, ("eth", "en"))) + +#: Wireless first; see the module docstring. +_KIND_ORDER = (WIRELESS, WIRED, OTHER) + + +@dataclass(frozen=True) +class HostAddress: + """One address the headset could be given, and where it comes from.""" + + address: str + #: The network interface holding the address, or None when it is not one of this machine's. + interface: str | None + kind: str + + +def interface_kind(name: str) -> str: + """Whether an interface name is a wireless link, a wired one, or neither.""" + for kind, prefixes in _KIND_PREFIXES: + if name.startswith(prefixes): + return kind + return OTHER + + +def _interface_address(name: str) -> str | None: + """The IPv4 address of one interface through the Linux ioctl, or None when it has none.""" + with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe: + try: + packed = fcntl.ioctl(probe.fileno(), _SIOCGIFADDR, struct.pack("256s", name.encode()[:15])) + except OSError: + return None + return socket.inet_ntoa(packed[20:24]) + + +def _system_interfaces() -> list[tuple[str, str]]: + """Every interface of this machine with an IPv4 address, as (name, address); empty off Linux.""" + # The request number below is Linux's; elsewhere it could mean something else, so it is never sent. + if not sys.platform.startswith("linux"): + return [] + found = [] + for _index, name in socket.if_nameindex(): + address = _interface_address(name) + if address is not None: + found.append((name, address)) + return found + + +def _route_address() -> str | None: + """The address this machine would send from, found without sending anything; None when it has no route.""" + with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe: + try: + # Connecting a datagram socket only selects a route; no packet leaves the machine. + probe.connect(("192.0.2.1", 9)) + return probe.getsockname()[0] + except OSError: + return None + + +def local_addresses( + interfaces: Callable[[], Iterable[tuple[str, str]]] = _system_interfaces, + route_address: Callable[[], str | None] = _route_address, +) -> list[HostAddress]: + """This machine's usable IPv4 addresses, wireless first, then in the order the system lists them. + + Where interfaces cannot be listed (the ioctl is Linux only), the outbound route's address is the one + candidate. + """ + try: + listed = list(interfaces()) + except OSError: + listed = [] + usable = [ + HostAddress(address, name, interface_kind(name)) + for name, address in listed + # Loopback and link-local addresses are unreachable from a headset on the network. + if not (ipaddress.ip_address(address).is_loopback or ipaddress.ip_address(address).is_link_local) + ] + if usable: + return sorted(usable, key=lambda candidate: _KIND_ORDER.index(candidate.kind)) + fallback = route_address() + if fallback is None or ipaddress.ip_address(fallback).is_loopback: + return [] + return [HostAddress(fallback, None, OTHER)] + + +def _is_this_machine(host: str) -> bool: + """Whether a CaptureServer host names this machine: ``localhost`` or a loopback address.""" + if host == "localhost": + return True + try: + return ipaddress.ip_address(host).is_loopback + except ValueError: + return False + + +def _resolved(host: str) -> str | None: + """A host as an IP literal: itself when it already is one, else what its name resolves to, else None.""" + try: + return str(ipaddress.ip_address(host)) + except ValueError: + pass + try: + return socket.gethostbyname(host) + except OSError: + return None + + +def headset_addresses( + capture_server_url: str, + local: Callable[[], list[HostAddress]] = local_addresses, + resolve: Callable[[str], str | None] = _resolved, +) -> list[HostAddress]: + """The addresses to offer for the headset, best first; empty when none can be determined. + + Always IP literals: a headset is given an address, not a name, and a station remembers one. + """ + host = urlsplit(capture_server_url).hostname or "" + if host == "" or _is_this_machine(host): + return local() + # A capture host on another machine is where the headset must connect, whatever this machine's addresses are. + address = resolve(host) + return [HostAddress(address, None, CAPTURE_SERVER)] if address is not None else [] + + +def address_changed(saved: str | None, candidates: list[HostAddress]) -> bool: + """Whether the address saved for a station is no longer one the host has, so the headset needs updating.""" + return saved is not None and bool(candidates) and saved not in {candidate.address for candidate in candidates} diff --git a/examples/egocap/backend/egocap_web/operator_settings.py b/examples/egocap/backend/egocap_web/operator_settings.py index 5c9ad24144..8c132a2dae 100644 --- a/examples/egocap/backend/egocap_web/operator_settings.py +++ b/examples/egocap/backend/egocap_web/operator_settings.py @@ -5,7 +5,8 @@ """Operator-adjustable station setup kept by the backend, and the operator tools it knows about. Unlike the deployment settings (settings_routes.py), these are the operator's to change from the page: -camera type and roles, task catalog, and preselected task. They live in one JSON file under a hidden +camera type and roles, task catalog, preselected task, and whether calibration files are required before +recording. They live in one JSON file under a hidden ``.egocap/`` directory in the recording output (``EGOCAP_OPERATOR_SETTINGS_FILE`` overrides the location) so every browser sees the same value and it survives a restart. A change needs the run's control token, the same credential that admits recording commands, so a stray @@ -104,6 +105,9 @@ class OperatorSettings: task_file: str | None = None #: The task (by its catalog name) the picker preselects when the current task is still unset. preselected_task: str | None = None + #: Whether a station in use is held from recording while a calibration file of its cameras is missing. + #: Off by default: calibration files are optional unless the deployment requires them. + require_calibration: bool = False def to_json(self) -> dict[str, Any]: """The wire form, with the accepted camera types and roles so the page needs no second copy of either.""" @@ -114,6 +118,7 @@ def to_json(self) -> dict[str, Any]: "roles": list(CAMERA_ROLES), "task_file": self.task_file, "preselected_task": self.preselected_task, + "require_calibration": self.require_calibration, } def stored(self) -> dict[str, Any]: @@ -123,6 +128,7 @@ def stored(self) -> dict[str, Any]: "camera_roles": dict(self.camera_roles), "task_file": self.task_file, "preselected_task": self.preselected_task, + "require_calibration": self.require_calibration, } def updated(self, changes: dict[str, Any]) -> OperatorSettings: @@ -141,7 +147,7 @@ def updated(self, changes: dict[str, Any]) -> OperatorSettings: return _parse(merged) -def _parse_roles(raw: Any) -> dict[str, str | None]: +def parse_camera_roles(raw: Any) -> dict[str, str | None]: """Role assignments: known roles only, each a non-empty camera name or null, no camera in two roles.""" if raw is None: return {role: None for role in CAMERA_ROLES} @@ -158,9 +164,14 @@ def _parse_roles(raw: Any) -> dict[str, str | None]: if value is not None and (not isinstance(value, str) or value.strip() == ""): raise OperatorSettingsError(f"camera_roles.{role} must be a camera name or null") roles[role] = value - assigned = [value for value in roles.values() if value is not None] - if len(assigned) != len(set(assigned)): - raise OperatorSettingsError("a camera cannot fill two roles") + # Name the camera and both roles, so the operator knows which assignment to change. + holder: dict[str, str] = {} + for role, camera in roles.items(): + if camera is None: + continue + if camera in holder: + raise OperatorSettingsError(f"camera {camera!r} cannot fill both {holder[camera]} and {role}") + holder[camera] = role return roles @@ -181,9 +192,14 @@ def _parse(raw: Any) -> OperatorSettings: camera_type = raw.get("camera_type") if camera_type is not None and camera_type not in CAMERA_TYPES: raise OperatorSettingsError(f"camera_type must be one of {', '.join(CAMERA_TYPES)} or null") + # Absent in a file saved before the setting existed, which keeps the default. + require_calibration = raw.get("require_calibration", False) + if not isinstance(require_calibration, bool): + raise OperatorSettingsError("require_calibration must be true or false") return OperatorSettings( + require_calibration=require_calibration, camera_type=camera_type, - camera_roles=_parse_roles(raw.get("camera_roles")), + camera_roles=parse_camera_roles(raw.get("camera_roles")), task_file=_optional_text(raw, "task_file", check=is_catalog_name, what="a plain *.csv file name"), preselected_task=_optional_text( raw, "preselected_task", check=lambda v: v.strip() != "", what="a task name" @@ -213,6 +229,15 @@ def load(self) -> OperatorSettings: raise OperatorSettingsError("operator settings are not valid JSON") from exc return _parse(raw) + def calibration_required(self) -> bool: + """Whether the deployment holds a station from recording until its calibration files exist. Settings + that cannot be read keep the default, not required: an unreadable file must not start blocking takes. + Reads the file, so not for the event loop.""" + try: + return self.load().require_calibration + except (OperatorSettingsError, OSError): + return False + def save(self, settings: OperatorSettings) -> None: """Write the settings, through a temporary file so a crash never leaves a half-written one.""" self.path.parent.mkdir(parents=True, exist_ok=True) @@ -270,6 +295,23 @@ def _store(request: Request) -> OperatorSettingsStore | None: return getattr(request.app.state, "operator_settings_store", None) +def _station_service(request: Request) -> Any: + """The station service (station_service.py), or None in an application built without one. Read from the + application state rather than imported: that module builds on this one.""" + return getattr(request.app.state, "station_service", None) + + +def _effective(request: Request, settings: OperatorSettings) -> dict[str, Any]: + """The wire form the page acts on: the station in use supplies the camera type and roles, so every + reader sees that station's hardware; with no station in use the stored values apply as before.""" + payload = settings.to_json() + service = _station_service(request) + selected = service.registry.selected if service is not None else None + if selected is not None: + payload.update(camera_type=selected.camera_type, camera_roles=dict(selected.camera_roles)) + return payload + + @router.get("/api/operator-settings") async def read_operator_settings(request: Request) -> JSONResponse: """Return saved settings, or defaults with a repair warning if the saved data is invalid.""" @@ -284,10 +326,13 @@ async def read_operator_settings(request: Request) -> JSONResponse: # Defaults keep the form usable so an authenticated save can repair invalid storage. logger.warning("Invalid operator settings at %s; showing defaults for repair", store.path) return JSONResponse( - {**OperatorSettings().to_json(), "warning": "Saved settings are invalid. Save to replace them."}, + { + **_effective(request, OperatorSettings()), + "warning": "Saved settings are invalid. Save to replace them.", + }, headers=_NO_STORE, ) - return JSONResponse(settings.to_json(), headers=_NO_STORE) + return JSONResponse(_effective(request, settings), headers=_NO_STORE) @router.put("/api/operator-settings") @@ -302,6 +347,17 @@ async def write_operator_settings(request: Request) -> JSONResponse: body, refused = await read_authorized_json(request, recording_context.control_token, 16 * 1024) if body is None: return refused # type: ignore[return-value] + # With a station in use its own record holds the camera setup. Saving these fields here would store + # values nothing reads, so the caller is pointed at the station instead. Every other field, the + # calibration requirement included, is the deployment's and is saved whether or not a station is in use. + service = _station_service(request) + in_use = service.registry.selected if service is not None else None + if in_use is not None and any(key in body for key in ("camera_type", "camera_roles")): + return JSONResponse( + {"detail": "the station in use holds the camera setup; change it on the station"}, + status_code=400, + headers=_NO_STORE, + ) try: settings = await asyncio.to_thread( store.update, @@ -314,7 +370,7 @@ async def write_operator_settings(request: Request) -> JSONResponse: except OSError: logger.exception("Could not save operator settings") return JSONResponse({"detail": "could not save operator settings"}, status_code=503, headers=_NO_STORE) - return JSONResponse(settings.to_json(), headers=_NO_STORE) + return JSONResponse(_effective(request, settings), headers=_NO_STORE) @router.get("/api/tools") diff --git a/examples/egocap/backend/egocap_web/recording_command.py b/examples/egocap/backend/egocap_web/recording_command.py index 1d042ffef3..4466bba86c 100644 --- a/examples/egocap/backend/egocap_web/recording_command.py +++ b/examples/egocap/backend/egocap_web/recording_command.py @@ -30,10 +30,11 @@ import secrets import time import uuid +from collections.abc import Callable from dataclasses import dataclass, field from typing import Any -from recording_service import ConfigurationError, Disposition, EpisodeResult, StateError +from recording_service import ConfigurationError, Disposition, EpisodeResult, RecordingPhase, StateError from .recording_session import ( CoordinatorBusyError, @@ -196,6 +197,14 @@ def control_token_valid(candidate: object, expected: str) -> bool: return secrets.compare_digest(candidate, expected) +def interrupted_take(service: Any) -> bool: + """Whether the recording service (a snapshot of it, or None) holds a take that was interrupted and waits + to be recovered or discarded. The service keeps such a take as its episode, but nothing is writing it.""" + return ( + service is not None and service.episode is not None and service.phase is RecordingPhase.RECOVERY_REQUIRED + ) + + @dataclass class RecordingContext: """Thin wrapper around one ``RecordingSessionCoordinator``: owns the @@ -223,6 +232,11 @@ class RecordingContext: #: auto_fill_operator_name). Never a signal to commit an operator automatically: that #: still always requires the operator's own explicit "Set operator" action. auto_fill_operator_name: bool = False + #: Why station setup does not allow a take right now, or None when it does (see app.py's lifespan for + #: what it checks). It decides admission and the readiness that is published, and never interrupts a + #: take: a setup fact changing mid-take does not stop it, unlike a capture source going stale. It is asked + #: on the event loop at any time, during a take too, so it must answer from memory. + setup_gate: Callable[[], str | None] | None = field(default=None, repr=False) batch_id: str = field(default_factory=_new_batch_id) saved_count: int = 0 last_result: dict[str, Any] | None = None @@ -325,12 +339,20 @@ def _observe(self) -> tuple[CoordinatorSnapshot, tuple[Any, ...]]: """Reads the coordinator and advances ``revision`` if the decision state changed since the last look.""" coordinator_snapshot = self.coordinator.snapshot() ready, reason = self.coordinator.readiness() + # Station setup outranks a capture reason: it is the earlier step, and fixing it is the operator's move. + blocked = self.setup_block() + if blocked is not None: + ready, reason = False, blocked decision_state = self._decision_state(coordinator_snapshot, ready, reason) if decision_state != self._last_decision_state: self._last_decision_state = decision_state self.revision += 1 return coordinator_snapshot, decision_state + def setup_block(self) -> str | None: + """Why station setup does not allow a take right now, or None; None too when no gate is installed.""" + return self.setup_gate() if self.setup_gate is not None else None + def refresh(self) -> None: """Notices a readiness or in-progress change that no callback announces. Each viewer's sender calls this every iteration, before it compares ``revision``, so such a change is pushed without any command.""" @@ -375,6 +397,9 @@ def snapshot(self) -> dict[str, Any]: and ready and coordinator_snapshot.context.task_text.strip() != "" ), + # Why a take would be refused right now, when station setup or a capture source is the cause; + # null when ready, and null when only the task is missing (the page already says so). + "not_ready_reason": None if ready else reason, # Lets a receiver drop a snapshot older than one it already # applied; restarts from 0 with the process, so a receiver # compares it only within one connection. @@ -461,6 +486,10 @@ async def apply(self, command: RecordingCommand) -> tuple[str, str | None]: if command.action == "start_episode": if self.coordinator.snapshot().context.task_text.strip() == "": return "rejected", "set a task before starting an episode" + # Station setup decides admission here; it never stops a take already recording (see setup_gate). + blocked = self.setup_block() + if blocked is not None: + return "rejected", blocked await self.coordinator.start_episode(operator) return "ok", None if command.action == "stop_episode": diff --git a/examples/egocap/backend/egocap_web/recordings.py b/examples/egocap/backend/egocap_web/recordings.py index 14e3f4f452..544191e76e 100644 --- a/examples/egocap/backend/egocap_web/recordings.py +++ b/examples/egocap/backend/egocap_web/recordings.py @@ -14,23 +14,38 @@ Off by default: set EGOCAP_RECORDINGS_ENABLED=1 to turn it on. Unlike EGOCAP_VISER_ENABLED (opt-out, on by default), this feature is opt-in -- -unset, `router` has no routes at all -- every file under the recording -root is otherwise reachable by anyone who can reach the backend, which is -not something a deployment should get without asking for it. +unset, `router` has no routes at all. + +Turned on, the listing and every file need the run's control token, the +same credential that admits recording commands. A caller presents it in +``X-Control-Token``; the page signs in once with it and is given a +same-site, HTTP-only cookie, since a download link cannot carry a header. +A request a browser marks as coming from another site is refused whatever +it carries. The page's own static files stay public: they hold no +recording, and they are what shows the sign-in. """ from __future__ import annotations +import hashlib +import hmac import os +import secrets import stat as stat_module from pathlib import Path from fastapi import APIRouter, Request -from fastapi.responses import FileResponse, JSONResponse, RedirectResponse +from fastapi.responses import FileResponse, JSONResponse, RedirectResponse, Response from fastapi.staticfiles import StaticFiles +from .preview_routes import configured_allowed_origins, trusted_hostnames +from .recording_command import control_token_valid + router = APIRouter() +#: The cookie the page is given once it has presented the control token. +SESSION_COOKIE = "egocap_recordings" + _FRONTEND_DIST = Path(__file__).resolve().parents[2] / "recordings_frontend" / "dist" @@ -98,8 +113,69 @@ def _hidden_path(base: Path, target: Path) -> bool: _NO_STORE_HEADERS = {"Cache-Control": "no-store"} +def _session_value(control_token: str) -> str: + """The cookie value that proves the control token was presented, without being the token: a cookie is + stored by the browser, and the token itself must not be readable from there.""" + return hmac.new(control_token.encode(), b"egocap recordings browser", hashlib.sha256).hexdigest() + + +def _same_site(request: Request) -> bool: + """Whether a request comes from this backend's own page, a configured origin, or no page at all. + + A browser states where a request comes from; one that says another site sent it is refused. A request + with neither header is a navigation or a non-browser client, which the credential alone decides. + """ + site = request.headers.get("sec-fetch-site") + if site is not None and site not in ("same-origin", "none"): + return False + origin = request.headers.get("origin") + if origin is None or origin in configured_allowed_origins(): + return True + # The same rule the live session socket applies: the backend's own origin, and only for a trusted host. + trusted = trusted_hostnames() + if trusted is not None and (request.url.hostname or "") not in trusted: + return False + return origin == f"{request.url.scheme}://{request.headers.get('host', '')}" + + +def _refusal(request: Request, *, cookie_accepted: bool = True) -> JSONResponse | None: + """Why a request may not read recordings, as the reply to send; None when it may.""" + context = getattr(request.app.state, "recording_context", None) + token = getattr(context, "control_token", None) + if token is None: + return JSONResponse({"detail": "recordings are not available yet"}, 503, headers=_NO_STORE_HEADERS) + if not _same_site(request): + return JSONResponse({"detail": "origin not allowed"}, 403, headers=_NO_STORE_HEADERS) + if control_token_valid(request.headers.get("x-control-token"), token): + return None + cookie = request.cookies.get(SESSION_COOKIE) + # compare_digest refuses non-ASCII text outright, so that is ruled out first. + signed_in = cookie is not None and cookie.isascii() and secrets.compare_digest(cookie, _session_value(token)) + if cookie_accepted and signed_in: + return None + return JSONResponse({"detail": "enter the control token to browse recordings"}, 401, headers=_NO_STORE_HEADERS) + + if enabled(): + @router.post("/recordings/api/session", response_model=None) + def sign_in(request: Request) -> Response: + """Exchange the control token, sent in ``X-Control-Token``, for the cookie the page's listing calls + and download links carry. The cookie is HTTP-only and same-site, and is scoped to these routes.""" + refused = _refusal(request, cookie_accepted=False) + if refused is not None: + return refused + response = Response(status_code=204, headers=_NO_STORE_HEADERS) + response.set_cookie( + SESSION_COOKIE, + _session_value(request.app.state.recording_context.control_token), + path="/recordings", + httponly=True, + samesite="strict", + secure=request.url.scheme == "https", + ) + return response + @router.get("/recordings/api/list", response_model=None) @router.get("/recordings/api/list/{path:path}", response_model=None) def list_recordings(request: Request, path: str = "") -> JSONResponse: @@ -109,6 +185,9 @@ def list_recordings(request: Request, path: str = "") -> JSONResponse: mtime per entry. A plain (not async) def: FastAPI runs it in its threadpool, since the filesystem work below is synchronous and would otherwise block the event loop every other route shares.""" + refused = _refusal(request) + if refused is not None: + return refused base = _recording_output_root(request).resolve() target = _resolve(base, path) if target is None or _hidden_path(base, target): @@ -168,11 +247,15 @@ def get_recording_file(request: Request, path: str) -> FileResponse | JSONRespon download go out as an attachment (Content-Disposition), so a stray ``.html``/``.svg`` recorded alongside a take can't execute as script on this origin if opened directly.""" + refused = _refusal(request) + if refused is not None: + return refused base = _recording_output_root(request).resolve() target = _resolve(base, path) if target is None or not target.is_file() or _hidden_path(base, target): return JSONResponse({"detail": "Not Found"}, status_code=404) - return FileResponse(target, filename=target.name) + # The download is admitted by a credential; a cache that kept it could hand it to a request without one. + return FileResponse(target, filename=target.name, headers=_NO_STORE_HEADERS) # Mounted under router so app.py can register everything this module # needs with one `app.include_router(recordings.router)` call. Only diff --git a/examples/egocap/backend/egocap_web/session_locks.py b/examples/egocap/backend/egocap_web/session_locks.py new file mode 100644 index 0000000000..7166048481 --- /dev/null +++ b/examples/egocap/backend/egocap_web/session_locks.py @@ -0,0 +1,49 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""One holder at a time for a recorded session's labels. + +Two things rewrite or copy the labels of a session (or of a routed group): the end-of-day task correction, which +rewrites the episodes, ``config.yaml`` and the time-aligned copy, and the background aligner, which copies an +episode's labels into that aligned copy. Each takes the session's lock for the whole of its work, so a correction +never lands between the aligner's copy and its publication, and two corrections never interleave. + +Taking a lock never waits. A caller that finds it held learns who holds it and decides for itself: the correction +refuses and the operator tries again, the aligner looks again shortly. +""" + +from __future__ import annotations + +import threading +from pathlib import Path + +#: The two kinds of holder. +ALIGNER, CORRECTION = "aligner", "correction" + + +class SessionLocks: + """Which sessions' labels are held, and by whom. Safe to use from the event loop and from worker threads.""" + + def __init__(self) -> None: + """Nothing is held at first.""" + self._guard = threading.Lock() + # A session is listed only while it is held, so this never grows with the sessions on disk. + self._held: dict[Path, str] = {} + + def acquire(self, directory: Path, holder: str) -> str | None: + """Take the lock of ``directory`` for ``holder``. Returns None when taken, else who holds it now. + + ``directory`` is the resolved session or routed group directory; both callers resolve it the same + way, off the event loop, so one session is never two keys. + """ + with self._guard: + current = self._held.get(directory) + if current is None: + self._held[directory] = holder + return current + + def release(self, directory: Path) -> None: + """Give the lock of ``directory`` back.""" + with self._guard: + self._held.pop(directory, None) diff --git a/examples/egocap/backend/egocap_web/setup_checks.py b/examples/egocap/backend/egocap_web/setup_checks.py new file mode 100644 index 0000000000..c476aea183 --- /dev/null +++ b/examples/egocap/backend/egocap_web/setup_checks.py @@ -0,0 +1,269 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The station checklist: what a station must show before it records. + +A list of items, each passed, failed with the reason, warned about, or skipped. It covers every tracking device +the capture session reports, every camera the station uses, the calibration files of those cameras, and room on +the recording disk. A device or check the station does not use is skipped, never failed. + +Only a failed item holds a take. An item fails for what recording readiness itself refuses (capture not running, +no recent tracking sample or camera frame, a camera that cannot be recorded) and for a full disk. What goes beyond +that is a warning: a device's reported state, and calibration files unless the deployment requires them. + +This module is pure: it judges a :class:`CaptureFacts` value and never reads the capture session itself. +setup_service.py gathers the facts, keeps the checklist fresh and turns it into the recording gate. +""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +#: ``warn`` is advisory: shown with its reason, and never a reason to hold a take. +PASS, FAIL, WARN, SKIP = "pass", "fail", "warn", "skip" + +#: The groups items are listed under, in display order. +TRACKING, CAMERAS, SYSTEM = "tracking", "cameras", "system" + +#: Free space, under the recording output, below which a take is refused: a take that fills the disk is lost. +MIN_FREE_BYTES = 10 * 1024**3 + +#: Operator-facing role names, shared by the items below. +ROLE_NAMES = {"ego": "Ego (head)", "wrist_left": "Left wrist", "wrist_right": "Right wrist"} + +#: The calibration file each camera role needs before its video can be related to the tracked pose. +ROLE_CALIBRATION = { + "ego": ("head_camera_intrinsics.json", "head_camera_extrinsics.json"), + "wrist_left": ("left_wrist_camera_intrinsics.json",), + "wrist_right": ("right_wrist_camera_intrinsics.json",), +} +#: Needed once a station has any wrist camera. +WRIST_OFFSETS = "wrist_calibration_offsets.json" + + +@dataclass(frozen=True) +class CheckItem: + """One device or check, and how it stands.""" + + id: str + group: str + label: str + status: str + #: Why it failed, warns or was skipped; None for a pass that needs no comment. + detail: str | None = None + + def to_json(self) -> dict[str, Any]: + """The wire form.""" + return { + "id": self.id, + "group": self.group, + "label": self.label, + "status": self.status, + "detail": self.detail, + } + + +@dataclass(frozen=True) +class DeviceFact: + """One tracking device as the capture status reports it.""" + + label: str + connected: bool + #: The device's own error or state, shown when it is not connected. + detail: str | None = None + #: Whether this is the headset, whose connection is what proves the host address it was given. + headset: bool = False + + +@dataclass(frozen=True) +class CameraFact: + """One CaptureServer camera: whether it is connected and whether a frame arrived recently.""" + + connected: bool + fresh: bool + detail: str | None = None + + +@dataclass(frozen=True) +class CaptureFacts: + """Everything the checklist reads from the capture session, taken at one moment.""" + + running: bool = False + #: Why capture is not running, when it said. + error: str | None = None + #: A mock session has no real cameras to calibrate. + mock: bool = False + tracking_fresh: bool = False + devices: tuple[DeviceFact, ...] = () + cameras: Mapping[str, CameraFact] | None = None + #: Names of the camera streams offered over LiveKit. + livekit_cameras: frozenset[str] = frozenset() + #: Why an offered LiveKit stream cannot be recorded, or None. + livekit_blocked: str | None = None + + @property + def headset_connected(self) -> bool: + """Whether a headset is connected right now.""" + return any(device.headset and device.connected for device in self.devices) + + +def _tracking_items(facts: CaptureFacts) -> list[CheckItem]: + """One item per tracking device the session reports, and one for whether their data is arriving. + + A device that is not connected warns and does not fail. Recording readiness judges the tracking data, not + the state each device reports, and a station may leave a controller or a glove unused. + """ + items = [ + CheckItem( + f"device:{index}", + TRACKING, + device.label, + PASS if device.connected else WARN, + None if device.connected else (device.detail or "not connected"), + ) + for index, device in enumerate(facts.devices) + ] + # Connected devices that deliver nothing would record an empty take. + if items and not facts.tracking_fresh: + items.append(CheckItem("tracking:samples", TRACKING, "Tracking data", FAIL, "no recent sample")) + return items + + +def _camera_item(item_id: str, label: str, name: str, facts: CaptureFacts) -> CheckItem: + """How one named camera stands: a CaptureServer camera must be delivering frames, a LiveKit camera offered + and recordable (its video is joined when a take starts). A camera that delivers frames while reporting + another state than connected warns: its frames are what recording readiness judges.""" + if name in facts.livekit_cameras: + blocked = facts.livekit_blocked + return CheckItem(item_id, CAMERAS, label, FAIL if blocked else PASS, blocked) + camera = (facts.cameras or {}).get(name) + if camera is None: + return CheckItem(item_id, CAMERAS, label, FAIL, f"camera {name!r} is not offered by the capture session") + if not camera.fresh: + # The camera's own reason, when it has one, says more than the missing frame it caused. + detail = "no recent frame" if camera.connected else (camera.detail or "not connected") + return CheckItem(item_id, CAMERAS, label, FAIL, detail) + if not camera.connected: + return CheckItem(item_id, CAMERAS, label, WARN, camera.detail or "not connected") + return CheckItem(item_id, CAMERAS, label, PASS) + + +def _camera_items(facts: CaptureFacts, roles: Mapping[str, str | None] | None) -> list[CheckItem]: + """The station's cameras by role; with no station in use, every camera the session offers by name.""" + if roles is None: + names = sorted({*(facts.cameras or {}), *facts.livekit_cameras}) + return [_camera_item(f"camera:{name}", name, name, facts) for name in names] + items = [] + for role, camera in roles.items(): + label = ROLE_NAMES.get(role, role) + if camera is None: + # A station without this camera has nothing to check here. + items.append(CheckItem(f"camera:{role}", CAMERAS, label, SKIP, "not used by this station")) + else: + items.append(_camera_item(f"camera:{role}", f"{label}: {camera}", camera, facts)) + return items + + +def _calibration_item( + facts: CaptureFacts, roles: Mapping[str, str | None] | None, calibration_dir: Path, required: bool +) -> CheckItem: + """The calibration file each camera role in use needs; skipped for a mock session or with no station. + + Calibration files are optional unless the deployment requires them: a missing or unreadable one fails + when ``required`` and otherwise warns, so a station that has not captured its calibration still records. + """ + absent = FAIL if required else WARN + if facts.mock or roles is None: + why = "mock capture has nothing to calibrate" if facts.mock else "no station in use" + return CheckItem("calibration", SYSTEM, "Camera calibration", SKIP, why) + needed = [name for role, names in ROLE_CALIBRATION.items() if roles.get(role) is not None for name in names] + if roles.get("wrist_left") is not None or roles.get("wrist_right") is not None: + needed.append(WRIST_OFFSETS) + if not needed: + return CheckItem("calibration", SYSTEM, "Camera calibration", SKIP, "the station has no cameras assigned") + try: + missing = [name for name in needed if not (calibration_dir / name).is_file()] + except OSError as exc: + # A directory that cannot be searched is reported with its cause, never an exception for the caller. + detail = f"cannot read the calibration directory: {exc.strerror}" + return CheckItem("calibration", SYSTEM, "Camera calibration", absent, detail) + detail = f"missing: {', '.join(missing)}" if missing else None + return CheckItem("calibration", SYSTEM, "Camera calibration", absent if missing else PASS, detail) + + +def _disk_item(output_root: Path, free_bytes: Callable[[Path], int], min_free_bytes: int) -> CheckItem: + """Whether the recording output has room for takes.""" + try: + free = free_bytes(output_root) + except OSError as exc: + return CheckItem( + "disk", SYSTEM, "Free disk space", FAIL, f"cannot read the recording output: {exc.strerror}" + ) + gib = 1024**3 + detail = f"{free / gib:.1f} GB free" + if free < min_free_bytes: + return CheckItem( + "disk", SYSTEM, "Free disk space", FAIL, f"{detail}; {min_free_bytes / gib:.0f} GB needed" + ) + return CheckItem("disk", SYSTEM, "Free disk space", PASS, detail) + + +def checklist( + facts: CaptureFacts, + roles: Mapping[str, str | None] | None, + *, + calibration_dir: Path, + output_root: Path, + free_bytes: Callable[[Path], int], + min_free_bytes: int = MIN_FREE_BYTES, + require_calibration: bool = False, +) -> list[CheckItem]: + """Every item of the station checklist, in display order. + + ``roles`` is the station in use's camera per role, or None when no station is in use. + ``require_calibration`` is the deployment's choice of whether missing calibration files hold a take. + Reads the calibration directory and the disk, so it is called from a worker thread. + """ + system = [ + _calibration_item(facts, roles, calibration_dir, require_calibration), + _disk_item(output_root, free_bytes, min_free_bytes), + ] + if not facts.running: + # Nothing can be judged device by device without a running session; say that once. + capture = CheckItem("capture", TRACKING, "Capture session", FAIL, facts.error or "capture is not running") + return [capture, *system] + return [*_tracking_items(facts), *_camera_items(facts, roles), *system] + + +def _first(items: list[CheckItem], status: str) -> str | None: + """The first item with ``status`` as one phrase, or None when there is none.""" + for item in items: + if item.status == status: + return f"{item.label}: {item.detail}" if item.detail else item.label + return None + + +def first_failure(items: list[CheckItem]) -> str | None: + """The first failing item as one phrase, or None when nothing failed.""" + return _first(items, FAIL) + + +def first_warning(items: list[CheckItem]) -> str | None: + """The first item that warns as one phrase, or None when nothing does.""" + return _first(items, WARN) + + +def free_bytes_under(path: Path, disk_usage: Callable[[Path], Any]) -> int: + """Free space on the filesystem that holds ``path``, which may not exist yet. + + The recording output is created by the first take, so before that the nearest existing ancestor is measured: + it is on the same filesystem, and a missing directory is not a full disk. + """ + current = path.resolve() + while not current.exists() and current != current.parent: + current = current.parent + return disk_usage(current).free diff --git a/examples/egocap/backend/egocap_web/setup_routes.py b/examples/egocap/backend/egocap_web/setup_routes.py new file mode 100644 index 0000000000..005b7ec3c7 --- /dev/null +++ b/examples/egocap/backend/egocap_web/setup_routes.py @@ -0,0 +1,93 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""HTTP surface for the start-of-day flow: where each step stands and the live station checklist. + +Reading the flow is open to any page that can reach the backend, as the capture status is. The capture host +address to enter in the headset is a LAN detail, so it is included only when the request carries the run's +control token. Nothing here changes anything: the checklist is observed, not run. +""" + +from __future__ import annotations + +import asyncio +from typing import Any + +from fastapi import APIRouter, Request +from fastapi.responses import JSONResponse + +from .host_addresses import address_changed, headset_addresses +from .recording_command import control_token_valid + +router = APIRouter() + +_NO_STORE = {"Cache-Control": "no-store"} +#: How many times a read starts over because the station in use changed while it was gathering. +_ATTEMPTS = 3 + + +def _reply(body: dict[str, Any], status: int = 200) -> JSONResponse: + """A non-cacheable JSON reply: the flow changes under the page.""" + return JSONResponse(body, status_code=status, headers=_NO_STORE) + + +def _state(request: Request) -> tuple[Any, ...] | None: + """The services this route reads, or None until the lifespan has set them all.""" + state = request.app.state + names = ("setup_service", "station_service", "station_uptime", "recording_context", "settings") + found = tuple(getattr(state, name, None) for name in names) + return None if any(item is None for item in found) else found + + +async def headset_address(setup: Any, stations: Any, capture_server_url: str) -> dict[str, Any]: + """The capture host address to enter in the headset, the one remembered for the station in use, and + whether the remembered one stopped being valid. + + A connected headset is proof that the address it was given works, so nothing is reported as changed while + one is connected. + """ + # Interface enumeration and name resolution are blocking system calls, kept off the event loop. + candidates = await asyncio.to_thread(headset_addresses, capture_server_url) + selected = stations.registry.selected + saved = selected.headset_address if selected is not None else None + return { + "address": candidates[0].address if candidates else None, + "saved": saved, + "changed": address_changed(saved, candidates) and not setup.headset_connected(), + } + + +def _day_so_far(uptime: Any, station: str) -> tuple[bool, bool]: + """Whether the station has recorded a take today, and whether today's report was saved.""" + return uptime.took_today(station), uptime.report_saved(station) + + +@router.get("/api/setup") +async def read_setup(request: Request) -> JSONResponse: + """Each step of the start-of-day flow, the station checklist as it stands now, and what holds a take.""" + state = _state(request) + if state is None: + return _reply({"detail": "setup is not available yet"}, 503) + setup, stations, uptime, context, settings = state + for _ in range(_ATTEMPTS): + generation, label = stations.registry, stations.label() + # The checklist reads the disk, so it is judged in a worker thread; the reply below reads that result. + await setup.refresh() + headset = await headset_address(setup, stations, settings.capture.capture_server_url) + # Both read the day's files, so they stay off the event loop. + took_today, report_saved = await asyncio.to_thread(_day_so_far, uptime, label) + # Registry identity catches edits and switches away and back, even with the same final ID and label. + if generation is stations.registry: + break + else: + # Never answered with one station's day under another's name; the page reads again shortly. + return _reply({"detail": "the station in use is changing; try again"}, 503) + body = setup.status( + took_today=took_today, + saved_count=context.saved_count, + report_saved=report_saved, + headset_address_changed=headset["changed"], + ) + holds_token = control_token_valid(request.headers.get("x-control-token"), context.control_token) + return _reply({**body, "headset": headset if holds_token else None}) diff --git a/examples/egocap/backend/egocap_web/setup_service.py b/examples/egocap/backend/egocap_web/setup_service.py new file mode 100644 index 0000000000..69f174fab5 --- /dev/null +++ b/examples/egocap/backend/egocap_web/setup_service.py @@ -0,0 +1,308 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The start-of-day flow: its steps, the live station checklist, and whether station setup allows a take. + +The flow is station, devices, record, wrap-up. The checklist is judged continuously from the capture session, so +there is nothing to run. With a station in use it is the recording gate: a take is refused while any item fails; +an item that only warns never holds one. With no stations set up nothing here gates recording, the same +configuration-free default the station registry keeps; the checklist is then advisory. + +The checklist reads the calibration directory and the recording disk, which can stall on a slow mount, so it is +judged in a worker thread (:meth:`SetupService.refresh`, run as a background duty and by the route). The gate and +every other synchronous reader take the last result from memory and never touch the filesystem. +""" + +from __future__ import annotations + +import asyncio +import logging +import shutil +import time +from collections.abc import Callable +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +from capture_server import protocol as p + +from .capture_status import CaptureStatusMonitor +from .config import CaptureStatusConfig +from .livekit_recording import unrecordable_reason +from .setup_checks import ( + FAIL, + SYSTEM, + CameraFact, + CaptureFacts, + CheckItem, + DeviceFact, + checklist, + first_failure, + first_warning, + free_bytes_under, +) +from .station_service import StationService + +logger = logging.getLogger("isaaccapture.egocap.setup_service") + +DONE, TODO, ATTENTION, SKIPPED = "done", "todo", "attention", "skipped" + +#: How old a sample may be and still count as arriving; the same window recording readiness uses. +_FRESH_SECONDS = 2.0 +#: How often the application judges the checklist afresh (see app.py's duties). +CHECKLIST_SECONDS = 1.0 +#: A result older than this no longer speaks for the station: the evaluation is stuck, on a stalled disk for one. +_STALE_SECONDS = 10.0 +#: Why a take is held while no current result exists: before the first one, just after the station in use +#: changed, or while an evaluation is stuck. +CHECKS_PENDING = "the station checks are being evaluated" + + +def capture_facts(monitor: CaptureStatusMonitor, config: CaptureStatusConfig) -> CaptureFacts: + """The capture session's current state, as the checklist reads it.""" + native = monitor.native + now = time.monotonic() + status = native.latest_status + running = native.stopped is None and native.status is not None and native.status.running + tracking = monitor.preview.tracking() + cameras: dict[str, CameraFact] = {} + for camera in status.cameras if status is not None else (): + slot = monitor.preview.camera(camera.name) + cameras[camera.name] = CameraFact( + connected=camera.status is p.DeviceState.CONNECTED, + fresh=slot is not None and now - slot.received_monotonic <= _FRESH_SECONDS, + detail=camera.error or camera.status.name.lower(), + ) + started = native.started + livekit = [s for s in started.streams if isinstance(s, p.LiveKitCameraStream)] if started is not None else [] + return CaptureFacts( + running=running, + error=None if running else (monitor.snapshot().error_message or "capture is not running"), + mock=started is not None and started.mode is p.CaptureMode.MOCK, + tracking_fresh=tracking is not None and now - tracking.received_monotonic <= _FRESH_SECONDS, + devices=tuple( + DeviceFact( + label=device.description or device.id, + connected=device.status is p.DeviceState.CONNECTED, + detail=device.error or device.status.name.lower(), + headset=device.type == "headset", + ) + for device in (status.devices if status is not None else ()) + # A device switched off by configuration is not part of this station. + if device.status is not p.DeviceState.DISABLED + ), + cameras=cameras, + livekit_cameras=frozenset(stream.name for stream in livekit), + livekit_blocked=unrecordable_reason(started, config.capture_server_url) if livekit else None, + ) + + +def _step(step_id: str, label: str, status: str, detail: str | None = None) -> dict[str, Any]: + """One step of the flow in its wire form.""" + return {"id": step_id, "label": label, "status": status, "detail": detail} + + +@dataclass(frozen=True) +class Evaluation: + """One judgement of the checklist: what was judged, what was found, and when.""" + + #: The camera per role of the station judged, as a comparable value; None with no station in use. + key: tuple[tuple[str, str | None], ...] | None + facts: CaptureFacts + items: tuple[CheckItem, ...] + #: Monotonic time its facts were sampled, so slow file checks age it. + at: float + + +class SetupService: + """The start-of-day state for the station in use, and the gate recording asks.""" + + def __init__( + self, + *, + facts: Callable[[], CaptureFacts], + stations: StationService, + calibration_dir: Callable[[], Path], + output_root: Path, + require_calibration: Callable[[], bool] = lambda: False, + free_bytes: Callable[[Path], int] = lambda path: free_bytes_under(path, shutil.disk_usage), + monotonic: Callable[[], float] = time.monotonic, + ) -> None: + """``facts`` reads the capture session now, on the event loop. ``calibration_dir`` and + ``require_calibration`` are read at each evaluation, in its worker thread: the directory is an + environment setting a relaunch may change, and the requirement is a setting the page can change.""" + self._facts = facts + self._stations = stations + self._calibration_dir = calibration_dir + self._output_root = output_root + self._require_calibration = require_calibration + self._free_bytes = free_bytes + self._monotonic = monotonic + self._latest: Evaluation | None = None + # One evaluation at a time, so a stalled disk holds one worker thread however many callers wait. + self._refreshing = asyncio.Lock() + self._finished = 0 + self._last_failure: str | None = None + # Evaluations under way, held here because the event loop keeps only weak references to tasks. + self._evaluations: set[asyncio.Task[Evaluation]] = set() + + def _roles(self) -> dict[str, str | None] | None: + """The camera each role of the station in use is filled by, or None with no station in use.""" + selected = self._stations.registry.selected + return dict(selected.camera_roles) if selected is not None else None + + @staticmethod + def _key_of(roles: dict[str, str | None] | None) -> tuple[tuple[str, str | None], ...] | None: + """The comparable value an evaluation of these roles is kept under.""" + return tuple(sorted(roles.items())) if roles is not None else None + + def _key(self) -> tuple[tuple[str, str | None], ...] | None: + """What an evaluation for the station in use now would be keyed by.""" + return self._key_of(self._roles()) + + async def refresh(self) -> Evaluation: + """Judge the checklist now and keep the result for the synchronous readers. + + The evaluation is a task of its own: a caller that goes away (a page that closed its request) leaves it + running to keep its result, and still holding its turn, so the worker thread it waits on stays the + only one. + """ + task = asyncio.ensure_future(self._evaluate(self._finished)) + self._evaluations.add(task) + task.add_done_callback(self._evaluations.discard) + return await asyncio.shield(task) + + async def _evaluate(self, asked: int) -> Evaluation: + """One evaluation, asked for when ``asked`` evaluations had finished. + + A caller that waited for another evaluation takes that one's result when it is for the same station: + it finished after this caller asked, so it is as fresh as its own would be. + """ + async with self._refreshing: + latest = self._latest + if latest is not None and self._finished > asked and latest.key == self._key(): + return latest + roles = self._roles() + # Stamped when the facts are sampled, not when the files answer: a stalled disk must age the result. + sampled = self._monotonic() + try: + # The capture facts are plain memory and belong to the event loop; only the files leave it. + facts = self._facts() + items = await asyncio.to_thread(self._judged, facts, roles) + self._last_failure = None + except Exception as exc: # noqa: BLE001 -- the gate must hold with a reason, never raise + facts = CaptureFacts() + items = [ + CheckItem( + "checklist", SYSTEM, "Station checks", FAIL, "could not be evaluated; see backend logs" + ) + ] + # Logged when the cause changes, not on every evaluation, or one fault would fill the log. + if repr(exc) != self._last_failure: + self._last_failure = repr(exc) + logger.exception("The station checklist could not be evaluated") + self._latest = Evaluation(self._key_of(roles), facts, tuple(items), sampled) + self._finished += 1 + return self._latest + + def _judged(self, facts: CaptureFacts, roles: dict[str, str | None] | None) -> list[CheckItem]: + """The checklist for these facts; blocking file work, run in a worker thread.""" + return checklist( + facts, + roles, + calibration_dir=self._calibration_dir(), + output_root=self._output_root, + free_bytes=self._free_bytes, + require_calibration=self._require_calibration(), + ) + + def _current(self) -> Evaluation | None: + """The last evaluation while it still speaks for the station in use, else None.""" + latest = self._latest + if latest is None or latest.key != self._key(): + return None + return latest if self._monotonic() - latest.at <= _STALE_SECONDS else None + + def headset_connected(self) -> bool: + """Whether a headset was connected at the last evaluation, which is what shows the host address it + was given still works. The headset is the same whichever station is in use.""" + latest = self._latest + return latest is not None and latest.facts.headset_connected + + def block_reason(self) -> str | None: + """Why station setup does not allow a take now, or None when it does. Reads memory only: it is asked + on the event loop, by every viewer's sender and by the uptime sample.""" + blocked = self._stations.block_reason() + if blocked is not None: + return blocked + # With no station in use the checklist is advisory: the configuration-free default records as before. + if self._stations.registry.selected is None: + return None + current = self._current() + # Held rather than guessed: a take admitted on no result could fill a disk nobody measured. + if current is None: + return CHECKS_PENDING + return first_failure(list(current.items)) + + def status( + self, *, took_today: bool, saved_count: int, report_saved: bool, headset_address_changed: bool + ) -> dict[str, Any]: + """The flow's steps, the checklist and what holds a take, for the page. + + ``took_today`` is whether the station in use has recorded a take today; ``saved_count`` is the takes + kept in the current batch, which is only a detail of the step. + """ + current = self._current() + items = list(current.items) if current is not None else [] + return { + "steps": [ + self._station_step(headset_address_changed), + # Without a current result nothing is known about the devices; "all checks pass" would be a guess. + self._devices_step(items) + if current is not None + else _step("devices", "Devices", TODO, CHECKS_PENDING), + self._record_step(took_today, saved_count), + _step( + "wrap_up", "Wrap up", DONE if report_saved else TODO, "report saved" if report_saved else None + ), + ], + "checks": [item.to_json() for item in items], + "blocked_reason": self.block_reason(), + # Whether the checklist gates recording, or only advises (no station in use). + "enforced": self._stations.registry.selected is not None, + } + + def _station_step(self, headset_address_changed: bool) -> dict[str, Any]: + """Station: skipped with no stations set up, done once the station in use can record.""" + registry = self._stations.registry + if not registry.stations: + return _step("station", "Station", SKIPPED, "no stations set up") + blocked = self._stations.block_reason() + if blocked is not None: + return _step("station", "Station", TODO if registry.selected is None else ATTENTION, blocked) + # Advisory: a headset pointed at an address this host no longer has cannot connect. + if headset_address_changed: + return _step("station", "Station", ATTENTION, "this host's address changed; update the headset") + return _step("station", "Station", DONE, self._stations.label()) + + @staticmethod + def _record_step(took_today: bool, saved_count: int) -> dict[str, Any]: + """Record: done once the station has recorded today. The batch's own count restarts with every new + batch and outlives midnight, so it never decides the step.""" + if not took_today: + return _step("record", "Record", TODO) + batch = f" · {saved_count} saved in this batch" if saved_count else "" + return _step("record", "Record", DONE, f"recorded today{batch}") + + @staticmethod + def _devices_step(items: list[CheckItem]) -> dict[str, Any]: + """Devices: needs attention while any item of the checklist fails. A warning leaves the step done + and is named in its detail, since it does not hold a take.""" + failure = first_failure(items) + if failure is not None: + return _step("devices", "Devices", ATTENTION, failure) + warning = first_warning(items) + if warning is not None: + return _step("devices", "Devices", DONE, f"{warning}; takes are not held") + return _step("devices", "Devices", DONE, "all checks pass") diff --git a/examples/egocap/backend/egocap_web/station_routes.py b/examples/egocap/backend/egocap_web/station_routes.py new file mode 100644 index 0000000000..fefcf2bdea --- /dev/null +++ b/examples/egocap/backend/egocap_web/station_routes.py @@ -0,0 +1,177 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""HTTP surface for stations: the registry, the station in use, and its time today. + +Reading the registry and the station's time is open to any page that can reach the backend, as the operator +settings are. A station's headset address is a LAN detail and the day's notes are the operator's free text, so +both are returned only with the run's control token. Every change needs that token, the same credential that +admits recording commands. +""" + +from __future__ import annotations + +import asyncio +import logging +from typing import Any + +from fastapi import APIRouter, Request +from fastapi.responses import JSONResponse + +from .recording_command import control_token_valid +from .request_body import read_authorized_json +from .station_uptime import notes_problem +from .stations import StationError, StationNotFoundError + +logger = logging.getLogger("isaaccapture.egocap.station_routes") + +router = APIRouter() + +_NO_STORE = {"Cache-Control": "no-store"} +#: A station record is a few short fields; the day's notes are the largest body accepted here. +_MAX_BODY_BYTES = 32 * 1024 + + +def _reply(body: dict[str, Any], status: int = 200) -> JSONResponse: + """A non-cacheable JSON reply: station state changes under the page and must never be served stale.""" + return JSONResponse(body, status_code=status, headers=_NO_STORE) + + +def _unavailable() -> JSONResponse: + """The reply while the application has not finished starting.""" + return _reply({"detail": "stations are not available yet"}, 503) + + +def _state(request: Request) -> tuple[Any, Any, Any] | None: + """The station service, uptime log and recording context, or None until the lifespan has set them.""" + state = request.app.state + names = ("station_service", "station_uptime", "recording_context") + found = tuple(getattr(state, name, None) for name in names) + return None if any(item is None for item in found) else found # type: ignore[return-value] + + +def _holds_token(request: Request, context: Any) -> bool: + """Whether a read carries the run's control token, which unlocks the LAN details.""" + return control_token_valid(request.headers.get("x-control-token"), context.control_token) + + +def _refusal(exc: StationError) -> JSONResponse: + """A refused station change as its HTTP status: an unknown id is not found, anything else a bad request.""" + return _reply({"detail": exc.public_message}, 404 if isinstance(exc, StationNotFoundError) else 400) + + +@router.get("/api/stations") +async def list_stations(request: Request) -> JSONResponse: + """Every station, the one in use, and why each cannot record yet.""" + state = _state(request) + if state is None: + return _unavailable() + service, _uptime, context = state + return _reply(service.listing(private=_holds_token(request, context))) + + +async def _change(request: Request, change: Any) -> JSONResponse: + """Run one authorized registry change and answer with the new listing.""" + state = _state(request) + if state is None: + return _unavailable() + service, _uptime, context = state + body, refused = await read_authorized_json(request, context.control_token, _MAX_BODY_BYTES) + if body is None: + return refused # type: ignore[return-value] + try: + await change(service, body) + except StationError as exc: + return _refusal(exc) + except OSError: + logger.exception("Could not save the station registry") + return _reply({"detail": "could not save the station registry"}, 503) + return _reply(service.listing(private=True)) + + +@router.post("/api/stations") +async def add_station(request: Request) -> JSONResponse: + """Add a station from its name and, optionally, its hardware.""" + return await _change(request, lambda service, body: service.add(body)) + + +@router.post("/api/stations/select") +async def select_station(request: Request) -> JSONResponse: + """Put one station in use, or none for ``{"id": null}``; refused while a take is being recorded.""" + + async def select(service: Any, body: dict[str, Any]) -> None: + """Validate the id's shape here; whether it names a station is the registry's rule.""" + station_id = body.get("id") + if station_id is not None and not isinstance(station_id, str): + raise StationError("id must be a station id or null") + await service.select(station_id) + + return await _change(request, select) + + +@router.put("/api/stations/{station_id}") +async def update_station(request: Request, station_id: str) -> JSONResponse: + """Change the named fields of one station.""" + return await _change(request, lambda service, body: service.update(station_id, body)) + + +@router.delete("/api/stations/{station_id}") +async def delete_station(request: Request, station_id: str) -> JSONResponse: + """Delete one station. The credential travels in the header: a DELETE carries no body to bound or parse.""" + state = _state(request) + if state is None: + return _unavailable() + service, _uptime, context = state + if not _holds_token(request, context): + return _reply({"detail": "control token rejected"}, 403) + try: + await service.remove(station_id) + except StationError as exc: + return _refusal(exc) + except OSError: + logger.exception("Could not save the station registry") + return _reply({"detail": "could not save the station registry"}, 503) + return _reply(service.listing(private=True)) + + +@router.get("/api/station-uptime") +async def read_station_uptime(request: Request) -> JSONResponse: + """What the station in use is doing now, and its active and down time between today's takes. The day's + notes are left empty unless the request carries the control token.""" + state = _state(request) + if state is None: + return _unavailable() + service, uptime, context = state + report = await asyncio.to_thread(uptime.report, service.label()) + return _reply(report if _holds_token(request, context) else {**report, "notes": ""}) + + +@router.post("/api/station-uptime") +async def save_station_notes(request: Request) -> JSONResponse: + """Save the operator's notes for the station's day. The state itself is observed, never set. + + The body names the station the notes were written for. A draft begun before the station in use changed + is refused, so it never replaces the notes of the station now in use. + """ + state = _state(request) + if state is None: + return _unavailable() + service, uptime, context = state + body, refused = await read_authorized_json(request, context.control_token, _MAX_BODY_BYTES) + if body is None: + return refused # type: ignore[return-value] + station, notes = body.get("station"), body.get("notes") + if not isinstance(station, str): + return _reply({"detail": "station must name the station the notes are for"}, 400) + if station != service.label(): + return _reply({"detail": "the station in use changed; reload the report"}, 409) + problem = notes_problem(notes) + if problem is not None: + return _reply({"detail": problem}, 400) + try: + # Saved under the name just checked, so a change of station during the write cannot redirect it. + return _reply(await asyncio.to_thread(uptime.set_notes, station, notes)) + except OSError: + logger.exception("Could not save the station's notes") + return _reply({"detail": "could not save the notes"}, 503) diff --git a/examples/egocap/backend/egocap_web/station_service.py b/examples/egocap/backend/egocap_web/station_service.py new file mode 100644 index 0000000000..ad13986470 --- /dev/null +++ b/examples/egocap/backend/egocap_web/station_service.py @@ -0,0 +1,268 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Applies station registry changes to the running session. + +The registry (stations.py) only stores values. This service decides when a change is allowed and what it does to +the live session: the station in use cannot change while a take is being recorded, and a change of the station in +use takes effect in process, without a restart. The capture session keeps running; the station label shown and +recorded changes at once, and the recording batch rotates so the next take opens a session carrying the new label. +Which cameras CaptureServer is asked for stays a deployment setting (see station_config.py). +""" + +from __future__ import annotations + +import asyncio +import logging +from collections.abc import Awaitable, Callable +from typing import Any, Protocol + +from .operator_settings import CAMERA_ROLES, CAMERA_TYPES +from .stations import Station, StationError, StationRegistry, StationStore + +logger = logging.getLogger("isaaccapture.egocap.station_service") + +#: Shown when a change would alter the station a take in progress is being recorded against. +TAKE_IN_PROGRESS = "finish or discard the current take before changing the station in use" +#: Why a take is held for the moment a change of the station in use is being applied. +STATION_CHANGING = "the station is being changed" + + +class StationSession(Protocol): + """What this service needs from the live session; the application wires the real objects in.""" + + def offered_cameras(self) -> frozenset[str] | None: + """Names of the cameras the capture session offers, or None before a session has been accepted.""" + + def change_blocked(self) -> str | None: + """Why the station in use cannot change now, or None when it can.""" + + def show_label(self, label: str) -> None: + """Publish the station label every viewer sees.""" + + async def rotate_batch(self) -> None: + """End the current recording batch so the next take opens a session with the new label; raises + :class:`StationError` when the session cannot rotate now.""" + + def renamed(self, previous: str, name: str) -> None: + """The station in use was renamed: carry its day (time and notes) over to the new name.""" + + +class StationService: + """One owner for the station in use: the registry, the label it implies, and the rules for changing either.""" + + def __init__(self, store: StationStore, session: StationSession, default_label: str) -> None: + """``default_label`` is the deployment's own station label, used while no station is selected.""" + self._store = store + self._session = session + self._default_label = default_label + # One change at a time: a rotation awaits, and a second change must not interleave with it. + self._changing = asyncio.Lock() + # True while a change to the station in use is being applied; no take is admitted meanwhile. + self._applying = False + self._warning: str | None = None + self._registry = self._load() + self._label = self._label_of(self._registry) + + def _load(self) -> StationRegistry: + """The stored registry; one that is invalid or cannot be read starts empty with a warning the page + shows. Capture preview does not depend on stations, so neither stops the backend from starting.""" + try: + return self._store.load() + except StationError as exc: + logger.warning("Station registry is unreadable (%s); starting with no stations", exc.public_message) + self._warning = "Saved stations are unreadable. Adding a station replaces them." + except OSError as exc: + # Not set aside on the next change, unlike an invalid file: it may be valid and merely unreadable. + logger.warning("Station registry cannot be read (%s); starting with no stations", exc.strerror) + self._warning = "Saved stations cannot be read. Check the registry file's permissions." + return StationRegistry() + + def _label_of(self, registry: StationRegistry) -> str: + """The label recordings and viewers carry for a registry: the selected station's name, else the default.""" + selected = registry.selected + return selected.name if selected is not None else self._default_label + + @property + def registry(self) -> StationRegistry: + """The registry as last loaded or changed by this process.""" + return self._registry + + def label(self) -> str: + """The station label in effect now; read each time a recording session opens.""" + return self._label + + def block_reason(self) -> str | None: + """Why recording is not allowed for station reasons, or None. + + An empty registry blocks nothing: that is the configuration-free default. Once stations exist, one must + be selected and able to record. While the station in use is being changed nothing may start: the + take would open a session under the label, or record against the cameras, on their way out. + """ + if self._applying: + return STATION_CHANGING + if not self._registry.stations: + return None + selected = self._registry.selected + if selected is None: + return "select a station before recording" + problems = selected.problems(self._session.offered_cameras()) + return f"station {selected.name!r}: {problems[0]}" if problems else None + + def listing(self, *, private: bool) -> dict[str, Any]: + """The wire form of the registry. ``private`` adds each station's headset address, a LAN detail shown + only to a caller holding the control token.""" + offered = self._session.offered_cameras() + stations = [] + for station in self._registry.stations: + record = { + "id": station.station_id, + "name": station.name, + "camera_type": station.camera_type, + "camera_roles": dict(station.camera_roles), + "problems": station.problems(offered), + } + if private: + record["headset_address"] = station.headset_address + stations.append(record) + listing: dict[str, Any] = { + "stations": stations, + "selected": self._registry.selected_id, + "roles": list(CAMERA_ROLES), + "camera_types": list(CAMERA_TYPES), + "label": self._label, + "locked_reason": self._session.change_blocked(), + } + if self._warning is not None: + listing["warning"] = self._warning + return listing + + async def add(self, fields: Any) -> Station: + """Add a station; nothing about the session in use changes, so this is allowed during a take.""" + async with self._changing: + after = await self._persist(lambda registry: registry.added(fields), touches_station_in_use=False) + return after.stations[-1] + + async def update(self, station_id: str, changes: Any) -> None: + """Change one station; changing the station in use is refused while a take is recorded.""" + async with self._changing: + in_use = self._registry.selected_id == station_id + await self._persist( + lambda registry: registry.updated(station_id, changes), touches_station_in_use=in_use + ) + + async def remove(self, station_id: str) -> None: + """Delete one station; deleting the station in use leaves nothing selected.""" + async with self._changing: + in_use = self._registry.selected_id == station_id + await self._persist(lambda registry: registry.removed(station_id), touches_station_in_use=in_use) + + async def select(self, station_id: str | None) -> None: + """Put a station in use, or none for None.""" + async with self._changing: + await self._persist(lambda registry: registry.selecting(station_id), touches_station_in_use=True) + + async def remember_headset_address(self, station_id: str, observed: str | None, address: str) -> None: + """Keep the capture host address a connected headset is evidently using, for the station in use. + + ``station_id`` and ``observed`` are the station the caller looked at and the address it had saved + then. The caller decided across an await, so both are checked again here: another station put in use + meanwhile, or an address the operator just entered, is left alone. + + It changes nothing about what is recorded, so unlike an edit of the station in use it is allowed while + a take is being written. + """ + async with self._changing: + selected = self._registry.selected + if selected is None or selected.station_id != station_id or selected.headset_address != observed: + return + await self._persist( + lambda registry: registry.updated(station_id, {"headset_address": address}), + touches_station_in_use=False, + ) + + async def _persist( + self, apply: Callable[[StationRegistry], StationRegistry], *, touches_station_in_use: bool + ) -> StationRegistry: + """Persist one change and apply its effect on the live session; the caller holds the change lock.""" + # Refused before anything is written, so a blocked change leaves the file as it was. + if touches_station_in_use: + blocked = self._session.change_blocked() + if blocked is not None: + raise StationError(blocked) + # Validated in memory first: a refused change must not have rotated the batch. + candidate = apply(self._registry) + label = self._label_of(candidate) + relabelled = label != self._label + # A rename keeps the same station in use; anything else that changes the label is a different station. + renamed = ( + relabelled + and candidate.selected_id is not None + and candidate.selected_id == self._registry.selected_id + ) + # Held across the awaits below, for every change to the station in use: a take admitted between them + # would open a session under the old label, or record against camera assignments being replaced. + self._applying = touches_station_in_use + try: + # Rotated before the file is written: a session still open under the old label must never + # receive a take attributed to the new one, so a refused rotation refuses the whole change. + if relabelled: + await self._session.rotate_batch() + _, after = await asyncio.to_thread(self._store.change, apply) + self._registry = after + self._warning = None + if relabelled: + previous, self._label = self._label, self._label_of(after) + # The label is live from here; what follows only keeps the day's records in step with it. + self._session.show_label(self._label) + finally: + self._applying = False + if renamed: + await self._carry_day(previous, self._label) + return after + + async def _carry_day(self, previous: str, name: str) -> None: + """Move the renamed station's day to its new name. A failure is logged, not raised: the rename itself + is saved and live, and refusing it now would leave the page and the registry disagreeing.""" + try: + await asyncio.to_thread(self._session.renamed, previous, name) + except OSError: + logger.exception("Could not carry the day's timeline from %r to %r", previous, name) + + +def session_adapter( + *, + offered_cameras: Callable[[], frozenset[str] | None], + change_blocked: Callable[[], str | None], + show_label: Callable[[str], None], + rotate_batch: Callable[[], Awaitable[None]], + renamed: Callable[[str, str], None], +) -> StationSession: + """A :class:`StationSession` built from plain callables, so the application can bind the real monitor, + recording context and uptime log without this module importing any of them.""" + + class _Adapter: + """The callables above, under the protocol's method names.""" + + def offered_cameras(self) -> frozenset[str] | None: + """See :class:`StationSession`.""" + return offered_cameras() + + def change_blocked(self) -> str | None: + """See :class:`StationSession`.""" + return change_blocked() + + def show_label(self, label: str) -> None: + """See :class:`StationSession`.""" + show_label(label) + + async def rotate_batch(self) -> None: + """See :class:`StationSession`.""" + await rotate_batch() + + def renamed(self, previous: str, name: str) -> None: + """See :class:`StationSession`.""" + renamed(previous, name) + + return _Adapter() diff --git a/examples/egocap/backend/egocap_web/station_uptime.py b/examples/egocap/backend/egocap_web/station_uptime.py new file mode 100644 index 0000000000..90df35c315 --- /dev/null +++ b/examples/egocap/backend/egocap_web/station_uptime.py @@ -0,0 +1,576 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The station's time today, logged automatically: when it could record and when it was down, and why. + +Nobody marks the station active or blocked. A sampler asks every few seconds whether the station is recording, +ready to record, or down (a device, the capture session or a check is in the way), and the log keeps the day as a +list of segments, one file per day under the recording output. Active and down time are counted between the +first and last take of the day, so a station left powered on outside working hours adds to neither. Each down +period inside that window is a blocker, kept with the reason it began with. + +Everything here is a local file written atomically; nothing uploads it. +""" + +from __future__ import annotations + +import copy +import datetime +import json +import logging +import os +import threading +import time +from collections.abc import Callable +from pathlib import Path +from typing import Any + +from egocap.analytics.station_status_log import StationStatusTracker +from egocap.recording.episode_layout import write_json_atomic + +logger = logging.getLogger("isaaccapture.egocap.station_uptime") + +READY, RECORDING, DOWN = "ready", "recording", "down" + +#: Bounded so a stray paste cannot bloat a file that is rewritten through the day. +MAX_NOTES_CHARS = 4000 + +#: The directory, under the recording output, holding the day timelines, the daily logs and the saved reports. +UPTIME_DIR = "station_status" + +#: The reason logged for time the backend itself was not running to observe. +BACKEND_NOT_RUNNING = "the backend was not running" +#: The reason reported once a station's day holds as many segments as it may: its state is no longer followed. +LOG_FULL = "the day's log is full; the station's time is no longer logged" + +#: A silence longer than this between two samples means the backend was not running, not that nothing changed. +_GAP_SECONDS = 90.0 +#: How often an unchanged state is still written, so a crash loses at most this much of the last segment. +_HEARTBEAT_SECONDS = 30.0 +#: A day is a few hundred segments; the bound only stops a flapping device from growing the file without limit. +_MAX_SEGMENTS = 5000 + + +class UptimeError(ValueError): + """A refused change to the day's notes, with a public reason.""" + + +def notes_problem(notes: Any) -> str | None: + """Why a value cannot be saved as the day's notes, or None when it can.""" + if not isinstance(notes, str) or len(notes) > MAX_NOTES_CHARS: + return f"notes must be text of at most {MAX_NOTES_CHARS} characters" + return None + + +def _midnight(day: str) -> float: + """The moment a local calendar day (``YYYY-MM-DD``) begins, in epoch seconds.""" + return datetime.datetime.combine(datetime.date.fromisoformat(day), datetime.time.min).timestamp() + + +def _day(now: float) -> str: + """The local calendar day of a moment, as ``YYYY-MM-DD``.""" + return datetime.date.fromtimestamp(now).isoformat() + + +def _duration(seconds: float) -> str: + """A duration as ``Hh MMm SSs``, the form the daily log has always used.""" + whole = max(0, int(round(seconds))) + hours, rest = divmod(whole, 3600) + minutes, secs = divmod(rest, 60) + return f"{hours}h {minutes:02d}m {secs:02d}s" + + +def _open(record: dict[str, Any]) -> dict[str, Any] | None: + """The segment of a station that has not ended yet, or None.""" + segments = record["segments"] + return segments[-1] if segments and segments[-1]["end"] is None else None + + +def _full(record: dict[str, Any]) -> bool: + """Whether a station's day holds as many segments as it may, so nothing more is added to it.""" + return len(record["segments"]) >= _MAX_SEGMENTS + + +def _took(record: dict[str, Any] | None) -> bool: + """Whether a station's day has a take in it.""" + return record is not None and any(segment["state"] == RECORDING for segment in record["segments"]) + + +def window_totals(segments: list[dict[str, Any]], now: float) -> dict[str, Any]: + """Active time, down time and blockers between the first and last take of a day. + + Before the first take there is no window and everything is zero. A take still being recorded extends the + window to now. Adjacent down segments are one blocker, named by the reason it began with; its ``end`` is + None while it has not ended, and its seconds then run to now. + """ + spans = [(s["state"], s["reason"], s["start"], s["end"] if s["end"] is not None else now) for s in segments] + takes = [span for span in spans if span[0] == RECORDING] + totals: dict[str, Any] = {"active_seconds": 0.0, "down_seconds": 0.0, "blockers": []} + if not takes: + return totals + window_start, window_end = takes[0][2], takes[-1][3] + for segment, (state, reason, start, end) in zip(segments, spans): + # Only the part of a segment inside the working window counts. + start, end = max(start, window_start), min(end, window_end) + if end <= start: + continue + if state != DOWN: + totals["active_seconds"] += end - start + continue + totals["down_seconds"] += end - start + blockers = totals["blockers"] + # Still open only when the segment has no end and the window did not cut it short. + ended = None if segment["end"] is None and end == now else end + if blockers and blockers[-1]["end"] == start: + blockers[-1].update(end=ended, seconds=blockers[-1]["seconds"] + end - start) + else: + blockers.append({"reason": reason, "start": start, "end": ended, "seconds": end - start}) + return totals + + +class UptimeLog: + """The day's timeline for every station, behind one lock; one writer process is assumed.""" + + def __init__(self, directory: Path, clock: Callable[[], float] = time.time) -> None: + """``clock`` returns epoch seconds; tests pass their own to move through a day.""" + self._directory = directory + self._clock = clock + self._lock = threading.Lock() + self._payload: dict[str, Any] | None = None + self._written_at = 0.0 + #: Why the station is down right now. A segment keeps the reason it began with; this is the current one. + self._live_reason: str | None = None + self._full_warned = False + #: Stations whose daily log is behind the timeline: a take ended and the log has not been written since. + self._owed_logs: set[str] = set() + + # --- the day file ---------------------------------------------------------------------------------------- + + def _path(self, day: str) -> Path: + """The timeline file of one day.""" + return self._directory / f"{day}_timeline.json" + + def _load(self, day: str) -> dict[str, Any]: + """The stored timeline of a day, or an empty one when it is absent or unusable.""" + fresh: dict[str, Any] = {"date": day, "last_sample": None, "stations": {}} + try: + stored = json.loads(self._path(day).read_text(encoding="utf-8")) + except (OSError, ValueError): + return fresh + stations = stored.get("stations") if isinstance(stored, dict) else None + if not isinstance(stations, dict) or not all(self._usable(record) for record in stations.values()): + logger.warning("Ignoring an unusable timeline at %s", self._path(day)) + return fresh + return {"date": day, "last_sample": stored.get("last_sample"), "stations": stations} + + @staticmethod + def _usable(record: Any) -> bool: + """Whether a stored station record has the shape this module writes.""" + if not isinstance(record, dict) or not isinstance(record.get("segments"), list): + return False + record.setdefault("notes", "") + record.setdefault("aliases", []) + return all( + isinstance(s, dict) and {"state", "reason", "start", "end"} <= set(s) for s in record["segments"] + ) + + def _today(self) -> tuple[dict[str, Any], float]: + """Today's timeline and the time now, loaded on first use and rolled over when the local day changes. + + The time is the wall clock held at the last sample while it reads earlier than that: a clock stepped + back would otherwise end a segment before it began, or roll the log to a day already closed and + replace that day's file. + """ + now = self._clock() + if self._payload is None: + day = _day(now) + self._payload = self._unfinished_before(day) or self._load(day) + last = self._payload["last_sample"] + if isinstance(last, (int, float)): + now = max(now, last) + # Before a rollover, so a silence that crossed midnight is down time on the day it began. + self._bridge_gap(self._payload, now) + # Only ever forward: a day file earlier than the one in hand is finished and must not be rewritten. + if self._payload["date"] < _day(now): + self._payload = self._rolled(self._payload, _day(now)) + return self._payload, now + + def _unfinished_before(self, day: str) -> dict[str, Any] | None: + """The most recent earlier day's timeline when the backend stopped with a segment still open in it + and ``day`` has no timeline yet, else None. + + Starting from that day lets the ordinary gap and rollover steps finish it: its open segment is ended, + its daily log brought up to its midnight, and the state carried into ``day``. + """ + # A day that already has a file was started by a run that finished the one before it. + if self._path(day).exists(): + return None + suffix = "_timeline.json" + try: + names = [path.name for path in self._directory.glob(f"*{suffix}")] + except OSError: + return None + # ISO dates sort as text, so the greatest name below ``day`` is the latest earlier day. + earlier = sorted(name[: -len(suffix)] for name in names if name[: -len(suffix)] < day) + if not earlier: + return None + try: + datetime.date.fromisoformat(earlier[-1]) + except ValueError: + # Not a day file of this log; nothing to finish. + return None + payload = self._load(earlier[-1]) + return payload if any(_open(record) is not None for record in payload["stations"].values()) else None + + def _bridge_gap(self, payload: dict[str, Any], now: float) -> None: + """Account for time nothing was sampled (the backend stopped, or its host was suspended): each open + segment ends at the last sample and the silence since is logged as down.""" + last = payload["last_sample"] + bridged = False + for name, record in payload["stations"].items(): + segment = _open(record) + # A full day takes no further segment; its open one is left as it is. + if segment is None or _full(record): + continue + seen = last if isinstance(last, (int, float)) else segment["start"] + # A quick restart or a late sample is not an outage; the segment simply continues. + if now - seen <= _GAP_SECONDS: + continue + segment["end"] = max(seen, segment["start"]) + # A take the silence cut short has ended like any other, so the daily log is owed its time. + if segment["state"] == RECORDING: + self._owed_logs.add(name) + record["segments"].append( + {"state": DOWN, "reason": BACKEND_NOT_RUNNING, "start": segment["end"], "end": None} + ) + bridged = True + # The silence is accounted for up to now; without this the next read would bridge it again. + if bridged: + payload["last_sample"] = now + + def _rolled(self, previous: dict[str, Any], day: str) -> dict[str, Any]: + """Close the old day at its midnight and carry each open segment into the new one, so time that + crosses midnight is counted on both days and no state is lost. + + ``previous`` is left as it was: the closed day is a copy, so when its write fails the open segments + are still there to be carried by the next attempt. + """ + midnight = _midnight(day) + # The old day ends at its own midnight, which is earlier than the new day's start after a longer stop. + # Found by the calendar, not by adding 24 hours: a day on which the clocks change is not that long. + following = datetime.date.fromisoformat(previous["date"]) + datetime.timedelta(days=1) + closing = min(midnight, _midnight(following.isoformat())) + last = previous["last_sample"] + # A sample later than midnight is a silence already bridged up to then; it must not be bridged again. + sampled = max(midnight, last) if isinstance(last, (int, float)) else midnight + closed = copy.deepcopy(previous) + current: dict[str, Any] = {"date": day, "last_sample": sampled, "stations": {}} + for name, record in closed["stations"].items(): + segment = _open(record) + if segment is None: + continue + segment["end"] = max(closing, segment["start"]) + carried = {"state": segment["state"], "reason": segment["reason"], "start": midnight, "end": None} + current["stations"][name] = {"segments": [carried], "notes": "", "aliases": []} + # The old day's log is otherwise written only when a take ends, so the time after its last take, or + # the part of a take that crosses midnight, would never reach it. + if any(part["state"] == RECORDING for part in record["segments"]): + self._close_log(name, closed, closing) + self._write(closed) + # Each day is told once when its log fills up, and owes nothing for the day before. + self._full_warned = False + self._owed_logs.clear() + return current + + def _close_log(self, station: str, payload: dict[str, Any], midnight: float) -> None: + """Bring a finished day's daily log up to its midnight. A failure is logged, not raised: the rollover + must go on, or the new day would never start.""" + try: + self._write_log(station, payload, midnight, self._measured(station, payload["date"])) + except OSError: + logger.exception("Could not bring the daily log of %s up to midnight", payload["date"]) + + def _write(self, payload: dict[str, Any]) -> None: + """Replace the day file atomically, once the day has something worth keeping. + + Time is counted from the first take, so until then the timeline lives in memory only: a backend that + is merely running, or a test that starts one, leaves no file behind. + """ + self._written_at = self._clock() + path = self._path(payload["date"]) + worth_keeping = any(record["notes"] or _took(record) for record in payload["stations"].values()) + # A file already written is kept current, or notes cleared before the first take would return. + if not worth_keeping and not path.exists(): + return + self._directory.mkdir(parents=True, exist_ok=True) + write_json_atomic(path, payload) + + @staticmethod + def _claim(payload: dict[str, Any], name: str) -> None: + """A name that gets a record of its own stops being another station's earlier name: from here its + takes are that record's, not those of the station renamed away from it.""" + for record in payload["stations"].values(): + if name in record["aliases"]: + record["aliases"].remove(name) + + @classmethod + def _record(cls, payload: dict[str, Any], station: str) -> dict[str, Any]: + """A station's record for the day, created on first use.""" + record = payload["stations"].get(station) + if record is None: + cls._claim(payload, station) + record = payload["stations"][station] = {"segments": [], "notes": "", "aliases": []} + return record + + # --- writing --------------------------------------------------------------------------------------------- + + def observe(self, station: str, state: str, reason: str | None) -> None: + """Log what the station in use is doing now. A new segment starts only when the state changes; a down + period keeps the reason it began with, however the cause shifts while it lasts.""" + with self._lock: + payload, now = self._today() + changed = False + # One station is in use at a time: whatever another station was doing has ended. + for name, other in payload["stations"].items(): + segment = _open(other) + if name != station and segment is not None: + segment["end"], changed = now, True + record = self._record(payload, station) + segment = _open(record) + took = False + if (segment is None or segment["state"] != state) and self._has_room(record): + if segment is not None: + segment["end"], took = now, segment["state"] == RECORDING + record["segments"].append( + {"state": state, "reason": reason if state == DOWN else None, "start": now, "end": None} + ) + changed = True + self._live_reason = reason if state == DOWN else None + payload["last_sample"] = now + # The daily log follows each take, so it is current without anyone saving a report. Owed until + # it is written: a failed write here is made good at the next one below. + if took: + self._owed_logs.add(station) + if changed or now - self._written_at >= _HEARTBEAT_SECONDS: + self._write(payload) + self._settle_logs(payload, now) + + def _settle_logs(self, payload: dict[str, Any], now: float) -> None: + """Write each daily log that is owed; one that cannot be written stays owed for the next attempt.""" + for station in sorted(self._owed_logs): + self._write_log(station, payload, now, self._measured(station, payload["date"])) + self._owed_logs.discard(station) + + def _has_room(self, record: dict[str, Any]) -> bool: + """Whether a station's day takes another segment. At its bound the day stops being logged, and says so + once; its open segment is left open, so an unchanged file is not rewritten at every sample.""" + if not _full(record): + return True + if not self._full_warned: + self._full_warned = True + logger.warning("The day's timeline is full; further state changes today are not logged") + return False + + def rename(self, previous: str, name: str) -> None: + """Move today's timeline of a station to its new name, remembering the old one so the day's takes, + recorded under either name, are reported together.""" + with self._lock: + payload, now = self._today() + self._carry_files(previous, name, payload["date"]) + record = payload["stations"].pop(previous, None) + if record is None: + return + existing = payload["stations"].get(name) + if existing is not None: + # The new name was used earlier today: the two histories are one station's day. + record["segments"] = sorted(existing["segments"] + record["segments"], key=lambda s: s["start"]) + record["notes"] = record["notes"] or existing["notes"] + record["aliases"] = [*existing["aliases"], *record["aliases"]] + else: + self._claim(payload, name) + record["aliases"] = sorted({*record["aliases"], previous} - {name}) + payload["stations"][name] = record + # A log still owed to the old name is owed to the new one. + if previous in self._owed_logs: + self._owed_logs.discard(previous) + self._owed_logs.add(name) + self._write(payload) + # The carried log still names the old station and lacks whatever the new name had done today. + if self._log_path(name, payload["date"]).is_file(): + self._write_log(name, payload, now, self._measured(name, payload["date"])) + + def _carry_files(self, previous: str, name: str, day: str) -> None: + """Move the day's daily log and saved report of a renamed station to its new name, so recorded time and + the saved report follow it and nothing is left to be counted under both names. A file the new name + already has is kept and the old one removed. A failure is logged, not raised: the timeline still moves. + """ + for path_of in (self._log_path, self._report_path): + old, new = path_of(previous, day), path_of(name, day) + # Two names that differ only in case or punctuation share one file; there is nothing to move. + if old == new: + continue + try: + if new.exists(): + old.unlink(missing_ok=True) + elif old.exists(): + os.replace(old, new) + except OSError: + logger.exception("Could not carry %s over to the station's new name", old.name) + + def set_notes(self, station: str, notes: Any) -> dict[str, Any]: + """Save the operator's notes for the day; returns the station's report.""" + problem = notes_problem(notes) + if problem is not None: + raise UptimeError(problem) + with self._lock: + payload, now = self._today() + self._record(payload, station)["notes"] = notes + self._write(payload) + return self._report(station, payload, now) + + # --- reading --------------------------------------------------------------------------------------------- + + def report(self, station: str) -> dict[str, Any]: + """The station's state now and its time today.""" + with self._lock: + payload, now = self._today() + return self._report(station, payload, now) + + def _report(self, station: str, payload: dict[str, Any], now: float) -> dict[str, Any]: + """The wire form of one station's day; the caller holds the lock.""" + record = payload["stations"].get(station) or {"segments": [], "notes": "", "aliases": []} + segment = _open(record) + state = segment["state"] if segment is not None else DOWN + # Until the first sample nothing is known; saying "ready" would be a guess. + reason = (self._live_reason or segment["reason"]) if segment is not None else "not observed yet" + # A full day no longer follows the station, so its last segment's state would be a guess as well. + if _full(record): + state, reason = DOWN, LOG_FULL + return { + "station": station, + "date": payload["date"], + "state": state, + "reason": reason if state == DOWN else None, + "since": segment["start"] if segment is not None else now, + **window_totals(record["segments"], now), + "notes": record["notes"], + # The moment these figures were computed, so a page can keep the open one counting locally. + "as_of": now, + } + + def took_today(self, station: str) -> bool: + """Whether the station has recorded a take today, under this name or one it was renamed from.""" + with self._lock: + return _took(self._today()[0]["stations"].get(station)) + + def names(self, station: str) -> frozenset[str]: + """Every name the station has had today, so takes recorded before a rename are still its own.""" + with self._lock: + record = self._today()[0]["stations"].get(station) + return frozenset({station, *(record["aliases"] if record is not None else ())}) + + # --- the daily log and the saved report ------------------------------------------------------------------ + + def _log_path(self, station: str, day: str) -> Path: + """The station's daily log, named by the library that defines that file.""" + return StationStatusTracker(self._directory).daily_log_path(station, day) + + def _report_path(self, station: str, day: str) -> Path: + """The station's saved report, beside its daily log so the two sort together.""" + log = self._log_path(station, day) + return log.with_name(log.name.replace("_activity.json", "_report.json")) + + def _measured(self, station: str, day: str) -> dict[str, float | None]: + """The recorded-time figures already in a daily log, so a rewrite after a take does not blank them.""" + try: + previous = json.loads(self._log_path(station, day).read_text(encoding="utf-8")) + except (OSError, ValueError): + previous = {} + values = previous if isinstance(previous, dict) else {} + return { + key: float(values[key]) + if isinstance(values.get(key), (int, float)) and not isinstance(values[key], bool) + else None + for key in ("data_seconds", "valid_seconds") + } + + def _write_log( + self, station: str, payload: dict[str, Any], now: float, measured: dict[str, float | None] + ) -> Path: + """Rewrite the station's daily log from the timeline and the recorded time last measured.""" + record = payload["stations"].get(station) or {"segments": []} + totals = window_totals(record["segments"], now) + hours = {key: None if value is None else round(value / 3600.0, 4) for key, value in measured.items()} + path = self._log_path(station, payload["date"]) + write_json_atomic( + path, + { + "station": station, + "date": payload["date"], + "active_station_time": _duration(totals["active_seconds"]), + "active_station_time_seconds": totals["active_seconds"], + "inactive_station_time": _duration(totals["down_seconds"]), + "inactive_station_time_seconds": totals["down_seconds"], + "blockers": len(totals["blockers"]), + "data_hours": hours["data_seconds"], + "data_seconds": measured["data_seconds"], + "valid_hours": hours["valid_seconds"], + "valid_seconds": measured["valid_seconds"], + }, + ) + return path + + def write_log(self, station: str, *, data_seconds: float | None, valid_seconds: float | None) -> str: + """Rewrite the daily log with freshly measured recorded time; returns the log's file name.""" + with self._lock: + payload, now = self._today() + measured = {"data_seconds": data_seconds, "valid_seconds": valid_seconds} + return self._write_log(station, payload, now, measured).name + + def save_report(self, station: str, report: dict[str, Any]) -> str: + """Write the day's report beside the daily log, atomically; returns the file's name.""" + with self._lock: + path = self._report_path(station, _day(self._clock())) + self._directory.mkdir(parents=True, exist_ok=True) + write_json_atomic(path, report) + return path.name + + def report_saved(self, station: str) -> bool: + """Whether today's report for the station has been saved.""" + return self._report_path(station, _day(self._clock())).is_file() + + +class UptimeSampler: + """Decides what to log from the station's state, asked every few seconds. + + A state must hold for a while before it is logged, so a device that flickers for a second does not become a + blocker. A take is the exception in both directions: its start and end are logged at once, because they set + the window everything else is counted in. + """ + + def __init__(self, *, settle_seconds: float = 6.0, monotonic: Callable[[], float] = time.monotonic) -> None: + """``settle_seconds`` is how long a new state must hold before it replaces the logged one.""" + self._settle_seconds = settle_seconds + self._monotonic = monotonic + self._logged: tuple[str, str] | None = None + self._pending: tuple[str, str] | None = None + self._pending_since = 0.0 + + def settle(self, station: str, state: str, reason: str | None) -> tuple[str, str, str | None]: + """What to log for the state just seen: that state once it is settled, else the last settled one.""" + seen = (station, state) + now = self._monotonic() + if seen != self._pending: + self._pending, self._pending_since = seen, now + immediate = ( + self._logged is None + # Another station, or the start or end of a take, is a fact, not a flicker. + or seen[0] != self._logged[0] + or RECORDING in (state, self._logged[1]) + ) + if seen == self._logged or immediate or now - self._pending_since >= self._settle_seconds: + self._logged = seen + return station, state, reason + # Not settled yet: the station is still logged as what it last settled on. + return self._logged[0], self._logged[1], reason if self._logged[1] == DOWN else None diff --git a/examples/egocap/backend/egocap_web/stations.py b/examples/egocap/backend/egocap_web/stations.py new file mode 100644 index 0000000000..c98109e6d5 --- /dev/null +++ b/examples/egocap/backend/egocap_web/stations.py @@ -0,0 +1,356 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The station registry: the stations an operator can choose between, and which one is in use. + +A station is a name plus the hardware that fills its roles: the camera type, which offered camera is the ego view +and which is on each wrist, and the host address last given to the headset. The registry is one JSON file beside +the operator settings, so every browser sees the same stations and they survive a restart. An empty registry is +the configuration-free default: nothing is selected, the deployment's own station label applies, and no station +rule blocks recording. + +This module holds the values and their validation only. Applying a selection to the running session lives in +station_service.py, and the HTTP surface in station_routes.py. +""" + +from __future__ import annotations + +import ipaddress +import json +import logging +import os +import secrets +import tempfile +import threading +from collections.abc import Callable +from dataclasses import dataclass, field, replace +from pathlib import Path +from typing import Any + +from egocap.analytics.station_status_log import StationStatusTracker + +from .operator_settings import ( + CAMERA_ROLES, + CAMERA_TYPES, + OperatorSettingsError, + parse_camera_roles, +) + +logger = logging.getLogger("isaaccapture.egocap.stations") + +#: A registry is a site's stations, not a database; the bound keeps the file and the page small. +MAX_STATIONS = 32 +MAX_STATION_NAME_CHARS = 64 + +#: The role every station must fill before it can record: without the operator's view a take has no subject. +REQUIRED_ROLE = "ego" + +#: Operator-facing role names for messages; the page keeps its own copy for labels. +_ROLE_NAMES = {"ego": "ego (head)", "wrist_left": "left wrist", "wrist_right": "right wrist"} + +#: The fields a create or update may carry. ``control_token`` is the legacy body credential, already checked. +_EDITABLE_FIELDS = ("name", "camera_type", "camera_roles", "headset_address") +_IGNORED_FIELDS = ("control_token",) + + +def _log_stem(name: str) -> str: + """The file-name stem a station's daily log gets, as the library that writes that file derives it.""" + # Any fixed day will do: only the part derived from the name differs between two stations. + return StationStatusTracker(Path(".")).daily_log_path(name, "day").name + + +class StationError(OperatorSettingsError): + """A station change that was refused, with a public, path-free reason naming what to fix.""" + + +class StationNotFoundError(StationError): + """A request named a station id the registry does not hold.""" + + +def _clean_name(raw: Any) -> str: + """A station name with surrounding and repeated whitespace removed, or a refusal saying what is wrong.""" + if not isinstance(raw, str): + raise StationError("station name must be text") + # Names are compared and shown, so "Bay 1" and "Bay 1" must not become two stations. + name = " ".join(raw.split()) + if name == "": + raise StationError("station name cannot be empty") + if len(name) > MAX_STATION_NAME_CHARS: + raise StationError(f"station name is limited to {MAX_STATION_NAME_CHARS} characters") + # The name is recorded with every session and used in a log file name; control characters have no place there. + if not name.isprintable(): + raise StationError("station name cannot contain control characters") + return name + + +def _clean_camera_type(raw: Any) -> str | None: + """A camera type the backend knows, or None for not set.""" + if raw is not None and raw not in CAMERA_TYPES: + raise StationError(f"camera_type must be one of {', '.join(CAMERA_TYPES)} or null") + return raw + + +def _clean_headset_address(raw: Any) -> str | None: + """The host address last given to the headset, as a canonical IP literal, or None when never set.""" + if raw is None: + return None + if not isinstance(raw, str): + raise StationError("headset_address must be an IP address or null") + try: + return str(ipaddress.ip_address(raw.strip())) + except ValueError: + raise StationError(f"headset_address {raw.strip()!r} is not an IP address") from None + + +@dataclass(frozen=True) +class Station: + """One station: its name and the hardware that fills its roles.""" + + station_id: str + name: str + camera_type: str | None = None + #: Which offered camera fills each role; every role is present, None where unassigned. + camera_roles: dict[str, str | None] = field(default_factory=lambda: {role: None for role in CAMERA_ROLES}) + #: The capture host address last entered in the headset; compared with today's to warn of a change. + headset_address: str | None = None + + def stored(self) -> dict[str, Any]: + """The record as written to the registry file.""" + return { + "id": self.station_id, + "name": self.name, + "camera_type": self.camera_type, + "camera_roles": dict(self.camera_roles), + "headset_address": self.headset_address, + } + + def problems(self, offered_cameras: frozenset[str] | None) -> list[str]: + """Why this station cannot record yet, most important first; empty when it can. + + ``offered_cameras`` is what the running capture session offers, or None while that is not known yet, in + which case only the assignments themselves are judged. + """ + found: list[str] = [] + if self.camera_roles[REQUIRED_ROLE] is None: + found.append(f"no camera is assigned to the {_ROLE_NAMES[REQUIRED_ROLE]} role") + if offered_cameras is None: + return found + # A role pointing at a camera the session does not offer would record nothing for that role. + for role in CAMERA_ROLES: + camera = self.camera_roles[role] + if camera is not None and camera not in offered_cameras: + found.append(f"camera {camera!r} ({_ROLE_NAMES[role]}) is not offered by the capture session") + return found + + +def _parse_station(raw: Any) -> Station: + """One stored record as a station; a malformed record is an error, never a guess.""" + if not isinstance(raw, dict): + raise StationError("each station must be an object") + station_id = raw.get("id") + if not isinstance(station_id, str) or station_id == "": + raise StationError("each station needs an id") + return Station( + station_id=station_id, + name=_clean_name(raw.get("name")), + camera_type=_clean_camera_type(raw.get("camera_type")), + camera_roles=_station_roles(raw.get("camera_roles")), + headset_address=_clean_headset_address(raw.get("headset_address")), + ) + + +def _station_roles(raw: Any) -> dict[str, str | None]: + """Role assignments for a station, refused as a station error so the route reports one error family.""" + try: + return parse_camera_roles(raw) + except OperatorSettingsError as exc: + raise StationError(exc.public_message) from None + + +def _checked_fields(changes: Any) -> dict[str, Any]: + """The editable fields a request names; an unknown field is refused so a typo is not silently dropped.""" + if not isinstance(changes, dict): + raise StationError("a station change must be an object") + unknown = sorted(set(changes) - set(_EDITABLE_FIELDS) - set(_IGNORED_FIELDS)) + if unknown: + raise StationError(f"unknown station field(s): {', '.join(unknown)}") + return {key: changes[key] for key in _EDITABLE_FIELDS if key in changes} + + +@dataclass(frozen=True) +class StationRegistry: + """Every station and the selected one. Immutable: each change returns a new registry.""" + + stations: tuple[Station, ...] = () + selected_id: str | None = None + + @property + def selected(self) -> Station | None: + """The station in use, or None when nothing is selected.""" + return self.find(self.selected_id) if self.selected_id is not None else None + + def find(self, station_id: str) -> Station | None: + """The station with this id, or None.""" + return next((station for station in self.stations if station.station_id == station_id), None) + + def require(self, station_id: str) -> Station: + """The station with this id; an unknown id is a refusal the route reports as not found.""" + station = self.find(station_id) + if station is None: + raise StationNotFoundError("no such station") + return station + + def stored(self) -> dict[str, Any]: + """The registry as written to its file.""" + return {"selected": self.selected_id, "stations": [station.stored() for station in self.stations]} + + def _refuse_duplicate_name(self, name: str, except_id: str | None) -> None: + """Refuse a name that would share another station's daily log. The log's file name drops case and + punctuation, so "Bay 1" and "bay_1" are one station as far as the day's records go.""" + for other in self.stations: + if other.station_id != except_id and _log_stem(other.name) == _log_stem(name): + raise StationError(f"a station named {other.name!r} already exists") + + def added( + self, fields: Any, new_id: Callable[[], str] = lambda: f"st_{secrets.token_hex(4)}" + ) -> StationRegistry: + """This registry with one more station built from ``fields``; the new station is last.""" + if len(self.stations) >= MAX_STATIONS: + raise StationError(f"a registry holds at most {MAX_STATIONS} stations") + checked = _checked_fields(fields) + name = _clean_name(checked.get("name")) + self._refuse_duplicate_name(name, except_id=None) + # A colliding id would make one station shadow another; draw until it is free. + station_id = new_id() + while self.find(station_id) is not None: + station_id = new_id() + station = Station( + station_id=station_id, + name=name, + camera_type=_clean_camera_type(checked.get("camera_type")), + camera_roles=_station_roles(checked.get("camera_roles")), + headset_address=_clean_headset_address(checked.get("headset_address")), + ) + return replace(self, stations=(*self.stations, station)) + + def updated(self, station_id: str, changes: Any) -> StationRegistry: + """This registry with the named fields of one station replaced; a role change may name only some roles.""" + current = self.require(station_id) + checked = _checked_fields(changes) + merged = current + if "name" in checked: + name = _clean_name(checked["name"]) + self._refuse_duplicate_name(name, except_id=station_id) + merged = replace(merged, name=name) + if "camera_type" in checked: + merged = replace(merged, camera_type=_clean_camera_type(checked["camera_type"])) + if "camera_roles" in checked: + roles = checked["camera_roles"] + if not isinstance(roles, dict): + raise StationError("camera_roles must be an object of role to camera name or null") + merged = replace(merged, camera_roles=_station_roles({**current.camera_roles, **roles})) + if "headset_address" in checked: + merged = replace(merged, headset_address=_clean_headset_address(checked["headset_address"])) + return replace( + self, + stations=tuple(merged if station.station_id == station_id else station for station in self.stations), + ) + + def removed(self, station_id: str) -> StationRegistry: + """This registry without one station; removing the selected station leaves nothing selected.""" + self.require(station_id) + return StationRegistry( + stations=tuple(station for station in self.stations if station.station_id != station_id), + selected_id=None if self.selected_id == station_id else self.selected_id, + ) + + def selecting(self, station_id: str | None) -> StationRegistry: + """This registry with ``station_id`` in use, or nothing in use for None.""" + if station_id is not None: + self.require(station_id) + return replace(self, selected_id=station_id) + + +def parse_registry(raw: Any) -> StationRegistry: + """A stored object as a registry: unique ids and names, and a selection that names a stored station.""" + if not isinstance(raw, dict): + raise StationError("the station registry must be an object") + records = raw.get("stations", []) + if not isinstance(records, list) or len(records) > MAX_STATIONS: + raise StationError(f"stations must be a list of at most {MAX_STATIONS}") + registry = StationRegistry() + for record in records: + station = _parse_station(record) + # A hand-edited file must hold to the same uniqueness the page enforces. + if registry.find(station.station_id) is not None: + raise StationError(f"station id {station.station_id!r} appears twice") + registry._refuse_duplicate_name(station.name, except_id=None) + registry = replace(registry, stations=(*registry.stations, station)) + selected = raw.get("selected") + if selected is not None and (not isinstance(selected, str) or registry.find(selected) is None): + raise StationError("the selected station is not in the registry") + return replace(registry, selected_id=selected) + + +class StationStore: + """The registry file: absent means no stations, and every write replaces it atomically.""" + + def __init__(self, path: Path) -> None: + """Bind the file and the lock that serialises changes within this backend process.""" + self.path = path + self.lock = threading.RLock() + + def load(self) -> StationRegistry: + """The stored registry, or an empty one when nothing has been saved.""" + try: + text = self.path.read_text(encoding="utf-8") + except FileNotFoundError: + return StationRegistry() + except UnicodeError: + raise StationError("the station registry is not valid UTF-8") from None + try: + raw = json.loads(text) + except json.JSONDecodeError: + raise StationError("the station registry is not valid JSON") from None + return parse_registry(raw) + + def save(self, registry: StationRegistry) -> None: + """Write the registry through a uniquely named temporary file, so a crash never leaves half of one.""" + self.path.parent.mkdir(parents=True, exist_ok=True) + with tempfile.NamedTemporaryFile( + mode="w", encoding="utf-8", dir=self.path.parent, prefix=f".{self.path.name}.", delete=False + ) as handle: + staged = Path(handle.name) + try: + handle.write(json.dumps(registry.stored(), indent=2) + "\n") + handle.flush() + os.fsync(handle.fileno()) + handle.close() + os.replace(staged, self.path) + finally: + staged.unlink(missing_ok=True) + + def change( + self, apply: Callable[[StationRegistry], StationRegistry] + ) -> tuple[StationRegistry, StationRegistry]: + """Apply one change under the lock and persist it; returns the registry before and after. + + An unreadable registry is set aside as ``.invalid`` and replaced, so the page can repair a station + list without shell access while the bad file stays available to inspect. + """ + with self.lock: + try: + before = self.load() + except StationError: + logger.warning("Setting aside an unreadable station registry at %s", self.path) + os.replace(self.path, self.path.with_name(f"{self.path.name}.invalid")) + before = StationRegistry() + after = apply(before) + self.save(after) + return before, after + + +def station_store_path(operator_settings_file: Path) -> Path: + """The registry file, kept beside the operator settings so both stay out of the recordings browser.""" + return operator_settings_file.with_name("stations.json") diff --git a/examples/egocap/frontend/README.md b/examples/egocap/frontend/README.md index 6d3d502d86..2836b60525 100644 --- a/examples/egocap/frontend/README.md +++ b/examples/egocap/frontend/README.md @@ -76,6 +76,56 @@ The page is built for an operator mid-take: the cameras fill it, and everything until then it says `SET UP` and what is missing. A command in flight shows at once (`STOPPING` while a take is written), because the backend's own phase only changes when the command finishes. A stale feed shows `NO FEED`, never a retained `REC`. +- **Start-of-day rail (under the header).** Station, Devices, Record and Wrap up, each done, needing attention, still + to do, or not needed for this station, with a short reason (`StepRail.tsx`). The first step that is neither done nor + skipped is highlighted. Station opens Settings on its Station tab, Devices opens Settings on its Devices tab, and + Wrap up opens the end-of-day report. Record is not a control: recording is the page itself, so the step only shows + where it stands. The rail shows what `GET /api/setup` reports and is read again when a dialog closes, when the + recording readiness reason changes, and ten seconds after each read answers (a slow read is waited for, never + cut short by the timer); it is absent when that cannot be read. +- **Dialogs.** Settings and End of day open over the page, so the cameras stay live behind them. While either is + open the page behind it is inert and the recording shortcuts and voice commands are suspended. +- **Settings (dialog).** Tabs: Station, Devices, Tasks, Display, Advanced (`SettingsPanel.tsx`). + - *Station* is the Stations card (`StationsCard.tsx`): each station with a radio that puts it in use, the camera + filling each role, and why it cannot record yet. *Edit* opens the row's inline editor for its name, camera type and + the camera per role, saved together; only one editor is open at a time, and a save sends only the fields that + editor changed, so it never undoes a change made in another browser meanwhile. The editor of the station in use + ends with the address its headset connects to, and the row warns when this host's address has changed since the + headset was given it. While a take is being recorded the station in use cannot be replaced, edited or deleted, and + while an interrupted take waits for recovery the backend refuses a change of the station in use; the card shows + its reason. + - While the site has no stations, a second card, *Camera setup* (`CameraSetupCard.tsx`), edits the camera type and + the camera per role with the same fields and *Swap wrists*, saved with the operator settings + (`PUT /api/operator-settings`). Adding a station moves that setup onto the station, and the card goes away. + Until the operator changes a field the card follows the saved setup, so after the last station is deleted it + shows what the settings hold, not what that station held. + - *Devices* is a live checklist (`DevicesTab.tsx`): the tracking devices and cameras the station needs, its + calibration files and the free disk space, each passed (`✓`), failed with the reason (`✗`), advisory (`!`, a + finding that does not hold recording) or not needed (`–`), under one line that says whether station setup holds + recording. The backend judges them continuously and the tab reads them again two seconds after each answer while + it is shown, so there is nothing to run. + - Under the checklist, *Require calibration files before recording* is the deployment's choice + (`require_calibration` in the operator settings, off by default, changed with the control token). Off, missing + calibration files are an advisory item and takes are allowed; on, they fail and hold recording. A change is + followed by an immediate read of the checklist. The calibration tools are listed beneath it. +- **End of day (dialog).** Opened from the rail's last step (`WrapUpDialog.tsx`); it always shows today for the station + in use and needs the control token. Top to bottom: the day's takes by outcome; the station's active and down time, + the stretches that blocked it, and a notes field; each session with its takes (outcome, duration, task, operator, + issues) and a form that corrects the task of one take or a range; *Save report*, which writes the report on the + station and names the files. A session with any take routed into a group shows where each take is recorded, since + a routed take is numbered by its slot in its group and an unfinished one by its place in the session; with more + than one group the correction also names the group it changed. Notes come from the day report and are saved for + the station they were typed for: if another station is in use by then the save is refused, the dialog says "The + station in use changed; reload the report." and keeps the draft, and after *Reload* it is saved for the station + the report now shows. Each opening starts from a fresh report, so while notes are unsaved or a correction is half + typed, Escape, the backdrop and *Close* ask "Discard unsaved changes?" instead of closing. +- **Status strip (under the bar).** The station in use, its uptime chip, and the capture headline. The chip + (`UptimeChip.tsx`) is read-only: the backend logs by itself when the station could record. It reads `Ready`, + `Recording`, or `Down` with how long and why, and once the day has a take the active and down time and the number of + blockers follow it. It is read every fifteen seconds, and at once when the recording phase, the readiness reason or + the saved count changes, so it does not lag the bar above. It is read without the control token, so it never + carries the day's notes, and after a change of the station in use it shows nothing until that station's own + uptime has arrived. - **Camera stage (middle).** It takes every pixel the bar above and the dock below leave. The head camera (the one named `head*`, otherwise the first) takes the left two-thirds and the others stack on the right; each tile carries its name and measured / advertised Hz and latency on the picture. A live take puts a red frame around the stage. diff --git a/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx b/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx index 7218e3b4e2..7097714b44 100644 --- a/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx +++ b/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx @@ -101,6 +101,7 @@ const activeSnapshot: RecordingSnapshot = { savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 0, }; diff --git a/examples/egocap/frontend/src/App.operatorLayout.test.tsx b/examples/egocap/frontend/src/App.operatorLayout.test.tsx index 37fe307ff7..b12a522496 100644 --- a/examples/egocap/frontend/src/App.operatorLayout.test.tsx +++ b/examples/egocap/frontend/src/App.operatorLayout.test.tsx @@ -7,10 +7,13 @@ * holds the 3D view and raw data. useCaptureSession is mocked so each test controls the snapshot directly. */ import { afterEach, describe, expect, it, vi, type Mock } from "vitest"; -import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react"; +import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react"; import App from "./App"; import type { PreviewSnapshot } from "./captureProtocol"; +import { DAY_REPORT_FIXTURE, UPTIME_FIXTURE } from "./dayReportTestDoubles"; import type { RecordingSnapshot } from "./recordingTypes"; +import { OPERATOR_SETTINGS_FIXTURE, STATIONS_FIXTURE } from "./settingsTestDoubles"; +import { SETUP_HELD, SETUP_READY } from "./setupTestDoubles"; import { useCaptureSession, type CaptureSessionState } from "./useCaptureSession"; vi.mock("./useCaptureSession", async (importOriginal) => { @@ -58,12 +61,14 @@ function recording(overrides: Partial = {}): RecordingSnapsho savedCount: 3, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 1, ...overrides, }; } -function mount(overrides: Partial = {}) { +/** Set what the capture session reports from the next render on. */ +function stubSession(overrides: Partial = {}) { (useCaptureSession as unknown as Mock).mockReturnValue({ phase: "connected", snapshot: snapshot(), @@ -83,6 +88,10 @@ function mount(overrides: Partial = {}) { clearControlToken: vi.fn(), ...overrides, }); +} + +function mount(overrides: Partial = {}) { + stubSession(overrides); return render(); } @@ -146,6 +155,192 @@ describe("operator page layout", () => { }); }); +/** Answer the routes a test names and leave every other request unanswered, as a backend that is still starting would. */ +function stubRoutes(routes: Record) { + const fetched = vi.fn(async (url: string, _init?: RequestInit) => (url in routes ? new Response(JSON.stringify(routes[url]), { status: 200 }) : new Response("{}", { status: 503 }))); + vi.stubGlobal("fetch", fetched); + return fetched; +} + +/** How many times a route has been read. */ +const readsOf = (fetched: ReturnType, route: string) => fetched.mock.calls.filter(([url]) => url === route).length; + +describe("station uptime in the status strip", () => { + it("shows the station's read-only chip beside its name once today's uptime is read", async () => { + stubRoutes({ "/api/station-uptime": UPTIME_FIXTURE }); + const { container } = mount(); + const chip = await screen.findByRole("img", { name: /^Station down for 5m 00s: Left wrist/ }); + expect(chip.textContent).toBe("Down · 5m 00s"); + expect(container.querySelector(".status-strip .status-station + .station-uptime")).not.toBeNull(); + expect(container.querySelector(".station-uptime")?.textContent).toBe("Down · 5m 00sactive 2h 05m · down 17m · 2 blockers"); + // Active and down time are the backend's to decide: the strip offers nothing to press. + expect(container.querySelector(".status-strip button")).toBeNull(); + }); + + it("reads the uptime again as soon as a take starts, is held or is saved, not on the chip's own timer", async () => { + const fetched = stubRoutes({ "/api/station-uptime": UPTIME_FIXTURE }); + const { rerender } = mount(); + await waitFor(() => expect(readsOf(fetched, "/api/station-uptime")).toBe(1)); + const changes: Array> = [ + { episodePhase: "RECORDING", currentEpisodeElapsedMs: 0 }, + { readyToRecord: false, notReadyReason: "Left wrist: cam_left: no recent frame" }, + { savedCount: 4 }, + ]; + for (const [index, change] of changes.entries()) { + stubSession({ recordingSnapshot: recording(change) }); + rerender(); + await waitFor(() => expect(readsOf(fetched, "/api/station-uptime")).toBe(index + 2)); + } + // A snapshot that changes none of them is no reason to read. + stubSession({ recordingSnapshot: recording({ savedCount: 4, revision: 9 }) }); + rerender(); + await screen.findByRole("img", { name: /^Station down/ }); + expect(readsOf(fetched, "/api/station-uptime")).toBe(4); + }); + + it("shows no chip while the uptime cannot be read", async () => { + const fetched = stubRoutes({}); + const { container } = mount(); + await waitFor(() => expect(readsOf(fetched, "/api/station-uptime")).toBe(1)); + expect(container.querySelector(".station-uptime")).toBeNull(); + }); +}); + +describe("start-of-day rail", () => { + it("shows four steps under the header and reads the flow with the control token", async () => { + const fetched = stubRoutes({ "/api/setup": SETUP_HELD }); + const { container } = mount(); + await screen.findByRole("button", { name: /Step 2, Devices: needs attention/ }); + expect(container.querySelector(".app-header + .step-rail")).not.toBeNull(); + expect(Array.from(container.querySelectorAll(".step-rail .step-label")).map((label) => label.firstChild?.textContent)).toEqual(["Station", "Devices", "Record", "Wrap up"]); + const [, init] = fetched.mock.calls.find(([url]) => url === "/api/setup") ?? []; + expect(new Headers(init?.headers).get("X-Control-Token")).toBe("token"); + }); + + it("opens Settings on the Devices tab over a page that takes no input, and reads the flow again on close", async () => { + const fetched = stubRoutes({ "/api/setup": SETUP_HELD }); + const { container } = mount(); + const devices = await screen.findByRole("button", { name: /Step 2, Devices: needs attention/ }); + expect(container.querySelector(".op-body")?.hasAttribute("inert")).toBe(false); + fireEvent.click(devices); + const dialog = screen.getByRole("dialog", { name: "Settings" }); + expect(dialog.querySelector(".settings-tab--on")?.textContent).toBe("Devices"); + // The page's own read is shown at once; the tab then reads the flow itself. + expect(within(dialog).getByRole("status").textContent).toBe("Recording is held: Left wrist: cam_left: no recent frame."); + // The page behind a dialog is inert, which is also what suspends the recording shortcuts. + expect(container.querySelector(".op-body")?.hasAttribute("inert")).toBe(true); + await waitFor(() => expect(readsOf(fetched, "/api/setup")).toBe(2)); + fireEvent.click(within(dialog).getByRole("button", { name: "Close" })); + expect(screen.queryByRole("dialog")).toBeNull(); + expect(container.querySelector(".op-body")?.hasAttribute("inert")).toBe(false); + // Closing reads the flow again, so a fix made while the dialog was open shows on the rail at once. + await waitFor(() => expect(readsOf(fetched, "/api/setup")).toBe(3)); + }); + + it("opens Settings on the Station tab for the station step, as the only dialog", async () => { + stubRoutes({ "/api/setup": SETUP_HELD }); + mount(); + fireEvent.click(await screen.findByRole("button", { name: /Step 1, Station/ })); + const settings = screen.getByRole("dialog", { name: "Settings" }); + expect(settings.querySelector(".settings-tab--on")?.textContent).toBe("Station"); + expect(screen.getAllByRole("dialog")).toHaveLength(1); + }); + + it("gives Settings the flow, so the station in use shows where its headset connects", async () => { + const station = { id: "st_1", name: "Bench A", camera_type: "oak_d", camera_roles: { ego: null, wrist_left: null, wrist_right: null }, problems: [] }; + stubRoutes({ + "/api/setup": { ...SETUP_READY, headset: { address: "10.0.0.42", saved: "10.0.0.7", changed: true } }, + "/api/stations": { ...STATIONS_FIXTURE, stations: [station], selected: "st_1", label: "Bench A" }, + "/api/operator-settings": OPERATOR_SETTINGS_FIXTURE, + "/api/tools": { tools: [] }, + "/api/task-files": { files: [], imported: [] }, + }); + mount(); + fireEvent.click(await screen.findByRole("button", { name: /Step 1, Station/ })); + const stations = await screen.findByRole("region", { name: "Stations" }); + expect(within(stations).getByText("This host's address changed from 10.0.0.7 to 10.0.0.42. Enter the new one in the headset.")).toBeTruthy(); + fireEvent.click(within(stations).getByRole("button", { name: "Edit" })); + expect(within(stations).getByText("Headset connects to 10.0.0.42")).toBeTruthy(); + }); + + it("shows Record as a step that opens nothing and takes no focus", async () => { + stubRoutes({ "/api/setup": SETUP_READY }); + const { container } = mount(); + await screen.findByRole("button", { name: /Step 1, Station/ }); + expect(screen.queryByRole("button", { name: /Step 3/ })).toBeNull(); + const record = container.querySelectorAll(".step-rail-item")[2].firstElementChild as HTMLElement; + expect(record.textContent).toBe("3Record: to do"); + expect(record.getAttribute("aria-current")).toBe("step"); + const focused = document.activeElement; + fireEvent.click(record); + expect(document.activeElement).toBe(focused); + expect(screen.queryByRole("dialog")).toBeNull(); + expect(container.querySelector(".op-body")?.hasAttribute("inert")).toBe(false); + }); + + it("opens the end-of-day report from the last step", async () => { + stubRoutes({ "/api/setup": SETUP_READY }); + const { container } = mount(); + fireEvent.click(await screen.findByRole("button", { name: /Step 4, Wrap up/ })); + expect(screen.getByRole("dialog", { name: "End of day" })).not.toBeNull(); + expect(container.querySelector(".op-body")?.hasAttribute("inert")).toBe(true); + fireEvent.click(screen.getByRole("button", { name: "Close" })); + expect(screen.queryByRole("dialog")).toBeNull(); + expect(container.querySelector(".op-body")?.hasAttribute("inert")).toBe(false); + }); + + it("moves focus into the end-of-day report when it opens and back to the Wrap up step when it closes", async () => { + stubRoutes({ "/api/setup": SETUP_READY }); + mount(); + const wrapUp = await screen.findByRole("button", { name: /Step 4, Wrap up/ }); + wrapUp.focus(); + fireEvent.click(wrapUp); + const dialog = screen.getByRole("dialog", { name: "End of day" }); + expect(document.activeElement).toBe(dialog); + // Focus sent to the page behind is brought back into the dialog. + wrapUp.focus(); + expect(document.activeElement).toBe(dialog); + fireEvent.keyDown(window, { key: "Escape" }); + expect(screen.queryByRole("dialog")).toBeNull(); + expect(document.activeElement).toBe(wrapUp); + }); + + it("starts the end-of-day report afresh at every opening", async () => { + const fetched = stubRoutes({ "/api/setup": SETUP_READY, "/api/day-report": DAY_REPORT_FIXTURE }); + mount(); + const wrapUp = await screen.findByRole("button", { name: /Step 4, Wrap up/ }); + fireEvent.click(wrapUp); + fireEvent.change(await screen.findByLabelText("Notes"), { target: { value: "half a thought" } }); + // Unsaved notes hold the dialog open until the operator says to discard them. + fireEvent.click(screen.getByRole("button", { name: "Close" })); + fireEvent.click(screen.getByRole("button", { name: "Discard" })); + expect(screen.queryByRole("dialog")).toBeNull(); + fireEvent.click(wrapUp); + // A new dialog: it shows nothing of the last one until its own report arrives. + expect(screen.queryByLabelText("Notes")).toBeNull(); + expect(((await screen.findByLabelText("Notes")) as HTMLTextAreaElement).value).toBe("left glove battery"); + expect(readsOf(fetched, "/api/day-report")).toBe(2); + }); + + it("suspends the recording shortcuts while the end-of-day report is open", async () => { + stubRoutes({ "/api/setup": SETUP_READY }); + const send = vi.fn().mockResolvedValue({ outcome: "ok", reason: null }); + mount({ sendRecordingCommand: send, recordingSnapshot: recording({ episodePhase: "RECORDING", currentEpisodeId: "e1", currentEpisodeElapsedMs: 0 }) }); + fireEvent.click(await screen.findByRole("button", { name: /Step 4, Wrap up/ })); + for (const key of ["a", "w", "s", "r", "t", " "]) fireEvent.keyDown(window, { key }); + expect(send).not.toHaveBeenCalled(); + fireEvent.click(screen.getByRole("button", { name: "Close" })); + fireEvent.keyDown(window, { key: "w" }); + expect(send).toHaveBeenCalledTimes(1); + }); + + it("shows no rail while the flow cannot be read", async () => { + const fetched = stubRoutes({}); + const { container } = mount(); + await waitFor(() => expect(readsOf(fetched, "/api/setup")).toBe(1)); + expect(container.querySelector(".step-rail")).toBeNull(); + }); +}); describe("resizing the side panel", () => { const widthOf = (container: HTMLElement) => diff --git a/examples/egocap/frontend/src/App.test.tsx b/examples/egocap/frontend/src/App.test.tsx index 8999d9fcf4..56fe1e87e1 100644 --- a/examples/egocap/frontend/src/App.test.tsx +++ b/examples/egocap/frontend/src/App.test.tsx @@ -478,7 +478,7 @@ describe("Settings modal recording isolation", () => { recordingSnapshot: { batchId: "b1", episodePhase: "RECORDING", currentEpisodeId: "e1", currentEpisodeElapsedMs: 0, taskText: "Fold towel", taskDetails: "", defaultOperator: null, autoFillOperatorName: false, - savedCount: 0, lastResult: null, readyToRecord: true, revision: 0, + savedCount: 0, lastResult: null, readyToRecord: true, notReadyReason: null, revision: 0, }, })); const { container } = render(); diff --git a/examples/egocap/frontend/src/App.tsx b/examples/egocap/frontend/src/App.tsx index c16d4c220e..07832bfe37 100644 --- a/examples/egocap/frontend/src/App.tsx +++ b/examples/egocap/frontend/src/App.tsx @@ -2,7 +2,7 @@ // // SPDX-License-Identifier: Apache-2.0 -import { useEffect, useId, useRef, useState, type CSSProperties } from "react"; +import { useCallback, useEffect, useId, useReducer, useRef, useState, type CSSProperties } from "react"; import { useCaptureSession, type ConnectionPhase } from "./useCaptureSession"; import type { PreviewSnapshot } from "./captureProtocol"; import { @@ -34,7 +34,11 @@ import { import { deviceTone, retainedTone, type Tone } from "./deviceHealth"; import { PoseViserPanel } from "./PoseViserPanel"; import { RecordingPanel } from "./RecordingPanel"; -import { SettingsPanel } from "./SettingsPanel"; +import { SettingsPanel, type SettingsTab } from "./SettingsPanel"; +import { StepRail, type OpenableStep } from "./StepRail"; +import { UptimeChip } from "./UptimeChip"; +import { useSetup } from "./useSetup"; +import { WrapUpDialog } from "./WrapUpDialog"; import { useOperatorSettings } from "./useOperatorSettings"; import { buildRecordingActions } from "./recordingActions"; import type { RecordingPhase } from "./recordingUiReducer"; @@ -209,7 +213,7 @@ function providerTone(status: ProviderStatus["status"]): Tone { /** The page's top bar: app title, capture mode, feed-health status and the Settings button. * There is no page/tab navigation -- the generic capture display and the * Ego Capture UI recording panel are always-present siblings on one page, and - * Settings opens as a drawer over them rather than replacing them. */ + * Settings and the end-of-day report open as dialogs over them rather than replacing them. */ function AppHeader({ response, feedHealthLabel, @@ -240,16 +244,17 @@ function AppHeader({ ); } -/** The compact status row beneath the header: station and the real capture - * lifecycle headline (a quiet one-liner, not a large hero). The supporting +/** The compact status row beneath the header: station, its read-only uptime + * chip (read again whenever `uptimeKey` changes), and the real capture lifecycle headline (a quiet one-liner, not a large hero). The supporting * session/provider details are reached by scrolling to their own collapsed * disclosure at the bottom of the page, not a link from here. A normal * running/current state stays quiet here; an error or stale feed instead * gets a visible banner from `StaleOrErrorBanner` below. */ -function StatusLine({ response, presentation }: { response: CaptureStatusResponse | null; presentation: Presentation }) { +function StatusLine({ response, presentation, uptimeKey }: { response: CaptureStatusResponse | null; presentation: Presentation; uptimeKey: string }) { return (
{response?.station_label ?? "Station"} + {presentation.freshnessLabel !== null && {presentation.freshnessLabel}} {presentation.headline} @@ -482,22 +487,56 @@ export default function App() { return () => window.removeEventListener("resize", refit); }, []); const unavailable = response === null && feedHealth === "unavailable"; - const [settingsOpen, setSettingsOpen] = useState(false); + // At most one dialog is open over the page; while one is, the page behind it takes no input. + const [dialog, setDialog] = useState<"settings" | "wrap_up" | null>(null); + const [settingsTab, setSettingsTab] = useState("station"); + // Counts Settings openings: each one starts the dialog afresh on the tab that was asked for. + const [settingsOpenings, countSettingsOpening] = useReducer((n: number) => n + 1, 0); + const settingsOpen = dialog === "settings"; + const modalOpen = dialog !== null; // The operator settings the page itself uses (camera roles). Re-read each time Settings closes, so a change // saved there reaches the tiles without a reload. const [settingsGeneration, setSettingsGeneration] = useState(0); const operatorSettings = useOperatorSettings(settingsGeneration); + // The start-of-day flow. It is read again when a dialog that can change it closes, and whenever the facts it + // is derived from change: the backend's own readiness reason, the station in use and the saved count. The + // control token goes with it, so the reply says which address the headset connects to. + const [setupGeneration, refreshSetup] = useReducer((n: number) => n + 1, 0); + const setup = useSetup(`${setupGeneration}|${recordingSnapshot?.notReadyReason ?? ""}|${response?.station_label ?? ""}|${recordingSnapshot?.savedCount ?? 0}`, { controlToken, scope: response?.station_label ?? "" }); + /** Open Settings on the given tab, as a fresh dialog. */ + const openSettings = (tab: SettingsTab) => { + setSettingsTab(tab); + countSettingsOpening(); + setDialog("settings"); + }; + /** Close Settings and read what it can change again: the camera setup the tiles go by, and the flow. */ const closeSettings = () => { - setSettingsOpen(false); + setDialog(null); setSettingsGeneration((n) => n + 1); + refreshSetup(); + }; + /** Close End of day and read the flow again: a correction or a saved report can change the Wrap up step. */ + const closeWrapUp = useCallback(() => { + setDialog(null); + refreshSetup(); + }, []); + /** Open the place a step of the start-of-day flow is dealt with. */ + const openStep = (step: OpenableStep) => { + if (step === "wrap_up") setDialog("wrap_up"); + else openSettings(step); }; - // Camera roles use the capture streams currently available on main. - const cameraSources = (snapshot?.started?.streams ?? []).filter((s) => s.kind === "camera").map((s) => s.name); + // Every camera the session offers can fill a role, whichever path its video takes to the page. + const cameraSources = (snapshot?.started?.streams ?? []).filter((s) => s.kind === "camera" || s.kind === "livekit_camera").map((s) => s.name); return (
- setSettingsOpen(true)} /> + openSettings("station")} /> + + {/* Mounted only while open, so every opening starts from a fresh report and an empty notes draft. */} + {dialog === "wrap_up" && } applyWidth(SIDEBAR_DEFAULT_PX, true)} controlToken={controlToken} cameraSources={cameraSources} + setup={setup} />
@@ -530,7 +570,12 @@ export default function App() { hasControlToken={controlToken !== null} pendingPhase={panelPhase} /> - + {/* The chip is keyed on what the bar above shows, so the two do not disagree until the chip's own timer. */} + {/* The cameras are the page: they take every pixel the status bar above and the controls below leave. */}
@@ -548,7 +593,7 @@ export default function App() { setControlToken={setControlToken} clearControlToken={clearControlToken} onPhaseChange={setPanelPhase} - interactionBlocked={settingsOpen} + interactionBlocked={modalOpen} />
diff --git a/examples/egocap/frontend/src/CameraSetupCard.test.tsx b/examples/egocap/frontend/src/CameraSetupCard.test.tsx new file mode 100644 index 0000000000..6a09fade8b --- /dev/null +++ b/examples/egocap/frontend/src/CameraSetupCard.test.tsx @@ -0,0 +1,28 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The Camera setup card: a setup saved elsewhere while the draft is changed is taken once the draft is clean. */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { cleanup, fireEvent, render, screen } from "@testing-library/react"; +import { CameraSetupCard } from "./CameraSetupCard"; +import { OPERATOR_SETTINGS_FIXTURE } from "./settingsTestDoubles"; + +afterEach(cleanup); + +describe("CameraSetupCard", () => { + it("keeps a changed draft over a setup saved elsewhere, and takes that setup once the draft is clean again", () => { + const props = { cameraSources: ["Ego", "Wrist A"], controlToken: "tok", save: vi.fn(async () => undefined) }; + const { rerender } = render(); + const ego = () => screen.getByLabelText("Ego (head)") as HTMLSelectElement; + const type = () => screen.getByLabelText("Camera type") as HTMLSelectElement; + fireEvent.change(ego(), { target: { value: "Ego" } }); + // Another browser saves a camera type while this draft is changed: the draft is kept as typed. + rerender(); + expect([ego().value, type().value]).toEqual(["Ego", ""]); + // Putting the field back leaves nothing of the operator's own, so the saved setup is shown. + fireEvent.change(ego(), { target: { value: "" } }); + expect([ego().value, type().value]).toEqual(["", "oak_d"]); + expect((screen.getByRole("button", { name: "Save camera setup" }) as HTMLButtonElement).disabled).toBe(true); + }); +}); diff --git a/examples/egocap/frontend/src/CameraSetupCard.tsx b/examples/egocap/frontend/src/CameraSetupCard.tsx new file mode 100644 index 0000000000..47ce24a088 --- /dev/null +++ b/examples/egocap/frontend/src/CameraSetupCard.tsx @@ -0,0 +1,90 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The Camera setup card of the Settings dialog's Station tab, shown only while the site has no stations: the + * camera type and the camera filling each role, saved with the operator settings. + * + * Once a station exists it holds the camera setup and its own row edits it, so this card goes away. The fields + * are the station editor's own, so the two cannot drift apart. + */ +import { useId, useState } from "react"; +import { Card, TokenHint, useAction } from "./settingsParts"; +import type { OperatorSettings, OperatorSettingsChange } from "./settingsApi"; +import { CameraFields, NO_CAMERAS_NOTE, cameraChangesOf, cameraDraftOf, hasWristCamera, selectableCameras, withWristsSwapped, type CameraDraft, type CameraSetup } from "./StationsCard"; + +export interface CameraSetupCardProps { + /** The saved setup, with the camera types and roles the backend accepts. */ + operator: Pick; + /** The cameras the current session offers, by name. */ + cameraSources: string[]; + controlToken: string | null; + /** Saves the changed fields; rejects with the backend's reason. */ + save: (changes: OperatorSettingsChange) => Promise; +} + +/** Edit the camera type and the camera per role of a site without stations, saving only what changed. */ +export function CameraSetupCard({ operator, cameraSources, controlToken, save }: CameraSetupCardProps) { + const fieldId = useId(); + // The setup the draft started from: what this card changed is judged against it, never against a setup + // another browser saved meanwhile, which a save from here must not put back. + const [original, setOriginal] = useState(operator); + const [draft, setDraft] = useState(() => cameraDraftOf(operator)); + const [{ busy, failure }, run] = useAction(); + const changes = cameraChangesOf(original, operator.roles, draft); + // An untouched draft follows the saved setup. The card can appear before the setup has been read again (the + // last station was just deleted, and what it held is still what the dialog shows), and it must not go on + // showing that station's cameras as the site's. A draft the operator has changed is theirs and is kept. + const savedSetup = JSON.stringify([operator.camera_type, operator.roles.map((role) => operator.camera_roles[role] ?? null)]); + const [followed, setFollowed] = useState(savedSetup); + // A saved setup that arrived over a changed draft is still owed: it is taken once the draft is clean again. + const [owed, setOwed] = useState(false); + const clean = Object.keys(changes).length === 0; + if (followed !== savedSetup || (owed && clean)) { + setFollowed(savedSetup); + setOwed(!clean); + if (clean) { + setOriginal(operator); + setDraft(cameraDraftOf(operator)); + } + } + /** Send what changed; once saved, the draft is what later changes are judged against. */ + const saveChanges = () => + run(() => + save(changes).then(() => { + setOriginal({ camera_type: draft.cameraType, camera_roles: { ...draft.cameraRoles } }); + // What was just saved is the newest setup; nothing older is owed. + setOwed(false); + }), + ); + const dirty = Object.keys(changes).length > 0; + const canSave = controlToken !== null && dirty && !busy; + return ( + +
+ +
+ {selectableCameras(cameraSources, operator.camera_roles).length === 0 &&

{NO_CAMERAS_NOTE}

} +
+ + + {failure !== null && Not saved: {failure}} +
+ +
+ ); +} diff --git a/examples/egocap/frontend/src/DevicesTab.test.tsx b/examples/egocap/frontend/src/DevicesTab.test.tsx new file mode 100644 index 0000000000..df98f0fbb2 --- /dev/null +++ b/examples/egocap/frontend/src/DevicesTab.test.tsx @@ -0,0 +1,269 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The Devices tab: the verdict, the live checklist and how often it is read, the calibration requirement, and the calibration tools. */ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { act, cleanup, fireEvent, render, screen, within } from "@testing-library/react"; +import { DEVICES_REFRESH_MS, DevicesTab, type DevicesTabProps } from "./DevicesTab"; +import { SettingsHttpError } from "./settingsApi"; +import { OPERATOR_SETTINGS_FIXTURE, TOOLS_FIXTURE } from "./settingsTestDoubles"; +import type { SetupStatus } from "./setupApi"; +import { SETUP_ADVISED, SETUP_HELD, SETUP_READY, SETUP_UNCALIBRATED } from "./setupTestDoubles"; + +beforeEach(() => vi.useFakeTimers()); +afterEach(() => { + cleanup(); + vi.useRealTimers(); +}); + +/** Let the pending read settle, then advance the fake clock. */ +async function settle(ms = 0) { + await act(async () => { + await vi.advanceTimersByTimeAsync(ms); + }); +} + +const TOOLS: DevicesTabProps["stationSetup"] = { kind: "loaded", value: { tools: TOOLS_FIXTURE, operator: OPERATOR_SETTINGS_FIXTURE } }; + +/** The tab over a backend whose answer a test can swap between reads. */ +async function renderTab(first: SetupStatus | Error, overrides: Partial = {}) { + const state = { answer: first }; + const loadSetup = vi.fn(async () => { + if (state.answer instanceof Error) throw state.answer; + return state.answer; + }); + const saveRequireCalibration = vi.fn(async (_required: boolean) => undefined); + const props: DevicesTabProps = { setup: null, controlToken: "tok", loadSetup, stationSetup: TOOLS, saveRequireCalibration, ...overrides }; + const utils = render(); + await settle(); + return { state, loadSetup, saveRequireCalibration, rerender: (next: Partial) => utils.rerender() }; +} + +/** The dialog's station setup with the calibration requirement as saved. */ +const withRequirement = (required: boolean): DevicesTabProps["stationSetup"] => ({ kind: "loaded", value: { tools: TOOLS_FIXTURE, operator: { ...OPERATOR_SETTINGS_FIXTURE, require_calibration: required } } }); +const requirement = () => within(screen.getByRole("region", { name: "Calibration requirement" })).getByRole("checkbox") as HTMLInputElement; + +const rowsOf = (group: string) => within(screen.getByRole("region", { name: group })).getAllByRole("listitem").map((row) => row.textContent); + +describe("the verdict", () => { + it("says recording is held and why while a required device fails", async () => { + await renderTab(SETUP_HELD); + const verdict = screen.getByRole("status"); + expect(verdict.textContent).toBe("Recording is held: Left wrist: cam_left: no recent frame."); + expect(verdict.className).toContain("setup-verdict--held"); + }); + + it("says station setup allows recording once nothing fails", async () => { + await renderTab(SETUP_READY); + const verdict = screen.getByRole("status"); + expect(verdict.textContent).toBe("Station setup allows recording."); + expect(verdict.className).toContain("setup-verdict--clear"); + }); + + it("says the checks only advise while no station is in use", async () => { + await renderTab({ ...SETUP_READY, enforced: false }); + const verdict = screen.getByRole("status"); + expect(verdict.textContent).toBe("No station is in use, so these checks advise and do not hold recording."); + expect(verdict.className).toBe("setup-verdict"); + }); +}); + +describe("a check whose outcome this page does not know", () => { + it("is shown as unrecognised with its reason, never as passed or not needed", async () => { + const [first, ...rest] = SETUP_READY.checks.filter((check) => check.group === "system"); + await renderTab({ ...SETUP_READY, checks: [{ ...first, status: "unknown", detail: "waiting for the vendor service" }, ...rest] }); + const row = within(screen.getByRole("region", { name: "System" })).getAllByRole("listitem")[0]; + expect(row.className).toBe("check-row check-row--unknown"); + expect(row.querySelector(".check-mark")?.textContent).toBe("?"); + expect(row.querySelector(".visually-hidden")?.textContent).toBe(" outcome not recognised by this page"); + expect(row.querySelector(".check-detail")?.textContent).toBe("Waiting for the vendor service"); + }); +}); + +describe("a check that only warns", () => { + it("has its own mark, colour class and spoken outcome, and its reason", async () => { + await renderTab(SETUP_ADVISED); + expect(rowsOf("System")).toEqual(["!Camera calibration advisoryMissing head_intrinsics.json, head_extrinsics.json", "✓Free disk space passed211.3 GB free"]); + const advised = within(screen.getByRole("region", { name: "System" })).getAllByRole("listitem")[0]; + expect(advised.className).toBe("check-row check-row--warn"); + expect(advised.querySelector(".visually-hidden")?.textContent).toBe(" advisory"); + }); + + it("leaves the verdict saying recording is allowed", async () => { + await renderTab(SETUP_ADVISED); + const verdict = screen.getByRole("status"); + expect(verdict.textContent).toBe("Station setup allows recording."); + expect(verdict.className).toContain("setup-verdict--clear"); + }); +}); + +describe("the calibration requirement", () => { + it("is off by default, beside the checklist, with what Off means", async () => { + await renderTab(SETUP_ADVISED); + const card = screen.getByRole("region", { name: "Calibration requirement" }); + expect(card.previousElementSibling?.getAttribute("aria-label")).toBe("Checklist"); + expect(within(card).getByLabelText("Require calibration files before recording")).toBe(requirement()); + expect(requirement().checked).toBe(false); + expect(requirement().disabled).toBe(false); + expect(within(card).getByText("Off: missing calibration files are shown as a warning and takes are allowed.").id).toBe(requirement().getAttribute("aria-describedby")); + }); + + it("saves the new choice and reads the checklist again at once", async () => { + const { state, loadSetup, saveRequireCalibration, rerender } = await renderTab(SETUP_ADVISED); + expect(loadSetup).toHaveBeenCalledTimes(1); + state.answer = SETUP_UNCALIBRATED; + fireEvent.click(requirement()); + expect(saveRequireCalibration).toHaveBeenCalledWith(true); + // The dialog then carries the saved value; no timer has run. + rerender({ stationSetup: withRequirement(true) }); + await settle(); + expect(loadSetup).toHaveBeenCalledTimes(2); + expect(requirement().checked).toBe(true); + expect(screen.getByRole("status").textContent).toBe("Recording is held: Camera calibration: missing head_intrinsics.json, head_extrinsics.json."); + expect(rowsOf("System")[0]).toBe("✗Camera calibration failedMissing head_intrinsics.json, head_extrinsics.json"); + }); + + it("shows why a save was refused and goes back to the saved choice", async () => { + const saveRequireCalibration = vi.fn(async () => { + throw new SettingsHttpError("control token is invalid"); + }); + const { loadSetup } = await renderTab(SETUP_ADVISED, { saveRequireCalibration }); + fireEvent.click(requirement()); + expect(requirement().checked).toBe(true); // shown while the save is on its way + await settle(); + expect(requirement().checked).toBe(false); + expect(within(screen.getByRole("region", { name: "Calibration requirement" })).getByText("Not saved: control token is invalid")).toBeTruthy(); + expect(loadSetup).toHaveBeenCalledTimes(1); + }); + + it("cannot be changed without the control token, and says where to enter it", async () => { + const { saveRequireCalibration } = await renderTab(SETUP_ADVISED, { controlToken: null, stationSetup: withRequirement(true) }); + expect(requirement().checked).toBe(true); + expect(requirement().disabled).toBe(true); + expect(within(screen.getByRole("region", { name: "Calibration requirement" })).getByText(/Enter the control token in the recording panel/)).toBeTruthy(); + expect(saveRequireCalibration).not.toHaveBeenCalled(); + }); + + it("is absent until the dialog's station setup has loaded", async () => { + await renderTab(SETUP_READY, { stationSetup: { kind: "loading" } }); + expect(screen.queryByRole("region", { name: "Calibration requirement" })).toBeNull(); + }); +}); + +describe("the checklist", () => { + it("groups the checks as Tracking, Cameras and System, each with its outcome and reason", async () => { + await renderTab(SETUP_HELD); + const checklist = screen.getByRole("region", { name: "Checklist" }); + expect(within(checklist).getAllByRole("heading", { level: 4 }).map((heading) => heading.textContent)).toEqual(["Tracking", "Cameras", "System"]); + expect(rowsOf("Tracking")).toEqual(["✓Pico headset passed"]); + expect(rowsOf("Cameras")).toEqual([ + "✓Ego (head): cam_head passed", + "✗Left wrist: cam_left failedNo recent frame", + "–Right wrist not neededNot used by this station", + ]); + expect(rowsOf("System")).toEqual(["–Camera calibration not neededMock capture has nothing to calibrate", "✓Free disk space passed211.3 GB free"]); + // The outcome word is for a screen reader; the mark carries it on screen. + const failed = within(screen.getByRole("region", { name: "Cameras" })).getAllByRole("listitem")[1]; + expect(failed.className).toBe("check-row check-row--fail"); + expect(failed.querySelector(".check-mark")?.getAttribute("aria-hidden")).toBe("true"); + expect(failed.querySelector(".visually-hidden")?.textContent).toBe(" failed"); + }); + + it("leaves out a group the station has nothing in", async () => { + await renderTab({ ...SETUP_READY, checks: SETUP_READY.checks.filter((check) => check.group !== "tracking") }); + expect(screen.queryByRole("region", { name: "Tracking" })).toBeNull(); + expect(screen.getByRole("region", { name: "Cameras" })).toBeTruthy(); + expect(screen.getByRole("region", { name: "System" })).toBeTruthy(); + }); + + it("says so when the backend reports no checks at all", async () => { + await renderTab({ ...SETUP_READY, checks: [] }); + expect(within(screen.getByRole("region", { name: "Checklist" })).getByText("Nothing is being checked yet.")).toBeTruthy(); + }); + + it("is read every two seconds with the control token, so a fixed device shows by itself", async () => { + const { state, loadSetup } = await renderTab(SETUP_HELD); + expect(DEVICES_REFRESH_MS).toBe(2_000); + expect(loadSetup).toHaveBeenCalledTimes(1); + expect(loadSetup).toHaveBeenLastCalledWith(expect.any(AbortSignal), "tok"); + state.answer = SETUP_READY; + await settle(1_999); + expect(loadSetup).toHaveBeenCalledTimes(1); + await settle(1); + expect(loadSetup).toHaveBeenCalledTimes(2); + expect(screen.getByRole("status").textContent).toBe("Station setup allows recording."); + expect(rowsOf("Cameras")[1]).toBe("✓Left wrist: cam_left passed"); + await settle(DEVICES_REFRESH_MS); + expect(loadSetup).toHaveBeenCalledTimes(3); + }); + + it("stops reading once the tab is no longer shown", async () => { + const { loadSetup } = await renderTab(SETUP_READY); + cleanup(); + await settle(3 * DEVICES_REFRESH_MS); + expect(loadSetup).toHaveBeenCalledTimes(1); + }); + + it("offers nothing that runs a test", async () => { + await renderTab(SETUP_HELD); + expect(within(screen.getByRole("region", { name: "Checklist" })).queryByRole("button")).toBeNull(); + expect(screen.getAllByRole("button").map((button) => button.textContent)).toEqual(["Open", "Open", "Open"]); + }); + + it("does not fall back to the page's older flow once its own read has answered and then fails", async () => { + const { state } = await renderTab(SETUP_READY, { setup: SETUP_HELD }); + expect(screen.getByRole("status").textContent).toBe("Station setup allows recording."); + state.answer = new Error("offline"); + await settle(DEVICES_REFRESH_MS); + expect(screen.queryByRole("status")).toBeNull(); + expect(screen.queryByRole("region", { name: "Checklist" })).toBeNull(); + expect(screen.getByText("The checks are unavailable: the backend did not answer.")).toBeTruthy(); + // The next read that answers brings the list back. + state.answer = SETUP_HELD; + await settle(DEVICES_REFRESH_MS); + expect(screen.getByRole("status").textContent).toBe("Recording is held: Left wrist: cam_left: no recent frame."); + }); + + it("shows the page's flow until its own read answers, and says so when neither has one", async () => { + await renderTab(new Error("offline"), { setup: SETUP_HELD }); + expect(screen.getByRole("status").textContent).toBe("Recording is held: Left wrist: cam_left: no recent frame."); + cleanup(); + await renderTab(new Error("offline")); + expect(screen.queryByRole("status")).toBeNull(); + expect(screen.getByText("The checks are unavailable: the backend did not answer.")).toBeTruthy(); + }); +}); + +describe("the calibration tools", () => { + it("lists each tool with its description, why it is unavailable, and a disabled Open button", async () => { + await renderTab(SETUP_READY); + const tools = screen.getByRole("region", { name: "Calibration tools" }); + expect(within(tools).getAllByRole("listitem").map((row) => row.querySelector(".settings-list-name")?.textContent)).toEqual([ + "Headset calibration", + "Glove calibration", + "Fisheye rectification", + ]); + expect(within(tools).getByText("Intrinsics and extrinsics of the headset cameras. — not wired in this build.")).toBeTruthy(); + const buttons = within(tools).getAllByRole("button", { name: "Open" }) as HTMLButtonElement[]; + expect(buttons.every((button) => button.disabled)).toBe(true); + expect(buttons[0].getAttribute("aria-describedby")).toBe("tool-headset_calibration-why"); + }); + + it("opens a tool this build can launch, unless it is for another camera type", async () => { + const tools = TOOLS_FIXTURE.map((tool) => ({ ...tool, available: true, unavailable_reason: null })); + await renderTab(SETUP_READY, { stationSetup: { kind: "loaded", value: { tools, operator: { camera_type: "oak_d", require_calibration: false } } } }); + const buttons = screen.getAllByRole("button", { name: "Open" }) as HTMLButtonElement[]; + expect(buttons.map((button) => button.disabled)).toEqual([false, false, true]); + expect(screen.getByText(/Only fisheye lenses need this; rectilinear cameras do not\. — for SENSING GMSL cameras stations\./)).toBeTruthy(); + }); + + it("says why the tools cannot be listed and still shows the checklist", async () => { + await renderTab(SETUP_READY, { stationSetup: { kind: "error", message: "tools are not available yet" } }); + expect(screen.getByText("Calibration tools unavailable: tools are not available yet")).toBeTruthy(); + expect(screen.getByRole("region", { name: "Checklist" })).toBeTruthy(); + cleanup(); + await renderTab(SETUP_READY, { stationSetup: { kind: "loading" } }); + expect(screen.getByText("Loading…")).toBeTruthy(); + }); +}); diff --git a/examples/egocap/frontend/src/DevicesTab.tsx b/examples/egocap/frontend/src/DevicesTab.tsx new file mode 100644 index 0000000000..19e192c667 --- /dev/null +++ b/examples/egocap/frontend/src/DevicesTab.tsx @@ -0,0 +1,204 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The Devices tab of the Settings dialog: the live checklist of what the station in use needs, whether missing + * calibration files hold recording, and the calibration tools. + * + * The backend judges every device continuously and holds recording while a required one fails. This tab shows + * that verdict and never judges a device itself, and nothing here runs a test: the list is read again every + * couple of seconds while the tab is shown. The dialog is over the page, so the cameras and the 3D view stay + * live behind it while a device is being fixed. + */ +import { useReducer, useState } from "react"; +import { sentence } from "./sentence"; +import { CAMERA_TYPE_LABELS, type OperatorSettings, type ToolInfo } from "./settingsApi"; +import { Card, LoadState, TokenHint, useAction, type Loaded } from "./settingsParts"; +import type { CheckGroup, CheckItem, CheckStatus, SetupStatus } from "./setupApi"; +import { useSetup } from "./useSetup"; + +/** How often the checklist is read while the tab is shown: fast enough to watch a device come back. */ +export const DEVICES_REFRESH_MS = 2_000; + +/** The mark and the words for each outcome; the mark alone is not text. */ +const OUTCOMES: Record = { + pass: { mark: "✓", word: "passed" }, + fail: { mark: "✗", word: "failed" }, + // A finding that does not hold recording, so it must not read as a failure or as a pass. + warn: { mark: "!", word: "advisory" }, + skip: { mark: "–", word: "not needed" }, + // An outcome a newer backend sent that this page has no name for; it may be what holds a take. + unknown: { mark: "?", word: "outcome not recognised by this page" }, +}; + +/** The groups of the checklist, in the order they are listed. */ +const GROUPS: ReadonlyArray<[CheckGroup, string]> = [ + ["tracking", "Tracking"], + ["cameras", "Cameras"], + ["system", "System"], +]; + +/** One device or check: its outcome, its name, and why when it did not simply pass. */ +function CheckRow({ item }: { item: CheckItem }) { + const outcome = OUTCOMES[item.status]; + return ( +
  • + + + {item.label} + {outcome.word} + + {item.detail !== null && {sentence(item.detail)}} +
  • + ); +} + +/** Whether station setup holds a take right now, in one sentence. */ +function Verdict({ setup }: { setup: SetupStatus }) { + // Without a station in use nothing is held, so the line is neither a pass nor a hold. + const tone = setup.blocked_reason !== null ? " setup-verdict--held" : setup.enforced ? " setup-verdict--clear" : ""; + return ( +

    + {setup.blocked_reason !== null + ? `Recording is held: ${setup.blocked_reason}.` + : setup.enforced + ? "Station setup allows recording." + : "No station is in use, so these checks advise and do not hold recording."} +

    + ); +} + +/** The checks by group, leaving out a group the station has nothing in. */ +function Checklist({ checks }: { checks: readonly CheckItem[] }) { + return ( + + {checks.length === 0 &&

    Nothing is being checked yet.

    } + {GROUPS.map(([group, title]) => { + const items = checks.filter((item) => item.group === group); + if (items.length === 0) return null; + return ( +
    +

    {title}

    +
      + {items.map((item) => ( + + ))} +
    +
    + ); + })} +
    + ); +} + +/** The deployment's choice of whether a missing calibration file holds recording or only warns. */ +function CalibrationRequirement({ + required, + controlToken, + save, +}: { + /** The saved choice. */ + required: boolean; + controlToken: string | null; + /** Saves the choice; resolves once the dialog shows the saved value, rejects with the backend's reason. */ + save: (required: boolean) => Promise; +}) { + const [{ busy, failure }, run] = useAction(); + // The choice on its way to the backend, shown until that answers; a refusal drops it, so the box reverts. + const [pending, setPending] = useState(null); + /** Send the new choice and show it meanwhile. */ + const change = (next: boolean) => { + setPending(next); + run(() => save(next).finally(() => setPending(null))); + }; + return ( + + +

    + Off: missing calibration files are shown as a warning and takes are allowed. +

    + {failure !== null &&

    Not saved: {failure}

    } + +
    + ); +} + +/** What the tab reads from the dialog's station setup: the tools, and the settings they and the checklist go by. */ +type ToolSetup = Loaded<{ tools: ToolInfo[]; operator: Pick }>; + +/** The calibration tools this build knows about, and why an unavailable one cannot be opened. */ +function CalibrationTools({ stationSetup }: { stationSetup: ToolSetup }) { + if (stationSetup.kind !== "loaded") return ; + const { tools, operator } = stationSetup.value; + return ( + +
      + {tools.map((tool) => { + const forOtherCameras = tool.applies_to !== null && operator.camera_type !== null && tool.applies_to !== operator.camera_type; + const reason = !tool.available ? tool.unavailable_reason : forOtherCameras ? `for ${CAMERA_TYPE_LABELS[tool.applies_to ?? ""]?.split(" — ")[0] ?? tool.applies_to} stations` : null; + return ( +
    • +
      + {tool.name} + + {tool.description} + {reason !== null && ` — ${reason}.`} + +
      + +
    • + ); + })} +
    +
    + ); +} + +export interface DevicesTabProps { + /** The flow as the page last read it, shown only until this tab's own, faster read first answers. */ + setup: SetupStatus | null; + controlToken: string | null; + loadSetup: (signal: AbortSignal, controlToken?: string | null) => Promise; + /** The dialog's station setup: the tools, the camera type they are judged against, and the calibration choice. */ + stationSetup: ToolSetup; + /** Saves whether calibration files are required; resolves once `stationSetup` carries the saved value. */ + saveRequireCalibration: (required: boolean) => Promise; +} + +/** Show whether station setup holds recording, each device and check as it stands now, the calibration + * requirement, and the calibration tools. */ +export function DevicesTab({ setup, controlToken, loadSetup, stationSetup, saveRequireCalibration }: DevicesTabProps) { + // Bumped when the calibration requirement is saved: it changes what the checklist says, so the list is read + // at once instead of on its timer. + const [saves, countSave] = useReducer((n: number) => n + 1, 0); + const live = useSetup(saves, { controlToken, intervalMs: DEVICES_REFRESH_MS, load: loadSetup }); + // Once the tab has answered, the page's older read must not stand in for a failed one: it would show a + // device as it was up to ten seconds ago with no sign that the list had stopped following. + const [answered, setAnswered] = useState(false); + if (live !== null && !answered) setAnswered(true); + const shown = live ?? (answered ? null : setup); + return ( + <> + {shown === null ? ( +

    The checks are unavailable: the backend did not answer.

    + ) : ( + <> + + + + )} + {stationSetup.kind === "loaded" && ( + saveRequireCalibration(required).then(countSave)} /> + )} + + + ); +} diff --git a/examples/egocap/frontend/src/OperatorBar.test.tsx b/examples/egocap/frontend/src/OperatorBar.test.tsx index eee5876db8..fc0344b28a 100644 --- a/examples/egocap/frontend/src/OperatorBar.test.tsx +++ b/examples/egocap/frontend/src/OperatorBar.test.tsx @@ -25,6 +25,7 @@ function snap(overrides: Partial = {}): RecordingSnapshot { savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 1, ...overrides, }; @@ -55,6 +56,12 @@ describe("deriveRecIndicator", () => { expect(deriveRecIndicator(snap({ readyToRecord: false, taskText: "" }), true).hint).toContain("Set a task"); }); + it("says why a take would be refused, ahead of a missing task", () => { + const blocked = { readyToRecord: false, notReadyReason: "select a station before recording" }; + expect(deriveRecIndicator(snap(blocked), true)).toMatchObject({ label: "NOT READY", hint: "Select a station before recording" }); + expect(deriveRecIndicator(snap({ ...blocked, taskText: "" }), true).hint).toBe("Select a station before recording"); + }); + it("asks for whatever setup is missing instead of claiming READY", () => { const none = deriveRecIndicator(snap(), true, { operatorSet: false, controlTokenSet: false }); expect(none).toMatchObject({ label: "SET UP", variant: "warning" }); diff --git a/examples/egocap/frontend/src/OperatorBar.tsx b/examples/egocap/frontend/src/OperatorBar.tsx index f7fc345aaf..2d10fff845 100644 --- a/examples/egocap/frontend/src/OperatorBar.tsx +++ b/examples/egocap/frontend/src/OperatorBar.tsx @@ -16,6 +16,7 @@ import { chipsNeedingAttention, deriveHealthChips, type HealthChip } from "./dev import { formatElapsed } from "./RecordingPanel"; import type { RecordingSnapshot } from "./recordingTypes"; import type { RecordingPhase } from "./recordingUiReducer"; +import { sentence } from "./sentence"; /** How the recording indicator is drawn. */ export type RecVariant = "recording" | "busy" | "ready" | "idle" | "warning" | "stale"; @@ -74,7 +75,9 @@ export function deriveRecIndicator( return { label: "RECOVERY", variant: "warning", hint: "An interrupted take is blocking Record -- start a new batch" }; case "IDLE": { if (!snapshot.readyToRecord) { - return { label: "NOT READY", variant: "idle", hint: snapshot.taskText ? null : "Set a task to enable Record" }; + // The backend's reason first: station setup and capture come before the task in the operator's order. + const reason = snapshot.notReadyReason !== null ? sentence(snapshot.notReadyReason) : null; + return { label: "NOT READY", variant: "idle", hint: reason ?? (snapshot.taskText ? null : "Set a task to enable Record") }; } // The backend would admit a take, but this browser may not be allowed to start one yet. if (!setup.operatorSet || !setup.controlTokenSet) { diff --git a/examples/egocap/frontend/src/RecordingPanel.taskCatalog.test.tsx b/examples/egocap/frontend/src/RecordingPanel.taskCatalog.test.tsx index 5e6063a162..c1374e4ffe 100644 --- a/examples/egocap/frontend/src/RecordingPanel.taskCatalog.test.tsx +++ b/examples/egocap/frontend/src/RecordingPanel.taskCatalog.test.tsx @@ -36,6 +36,7 @@ function snapshot(overrides: Partial = {}): RecordingSnapshot savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 0, ...overrides, }; diff --git a/examples/egocap/frontend/src/RecordingPanel.test.tsx b/examples/egocap/frontend/src/RecordingPanel.test.tsx index bc5a2eb903..6dc880ad50 100644 --- a/examples/egocap/frontend/src/RecordingPanel.test.tsx +++ b/examples/egocap/frontend/src/RecordingPanel.test.tsx @@ -46,6 +46,7 @@ function activeSnapshot(overrides: Partial = {}): RecordingSn savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 0, ...overrides, }; @@ -139,6 +140,19 @@ describe("RecordingPanel", () => { expect(record.title).toBe("Required sources not ready"); }); + it("Record gives the backend's own reason when it has one", () => { + const noop = vi.fn().mockResolvedValue({ outcome: "ok", reason: null }); + render( + , + ); + const record = screen.getByRole("button", { name: /record \(s\)/i }) as HTMLButtonElement; + expect(record.disabled).toBe(true); + expect(record.title).toBe("Station 'Bench A': no camera is assigned to the ego (head) role"); + }); + it("after an interrupted take, Record points to New batch as the way to clear it", () => { const noop = vi.fn().mockResolvedValue({ outcome: "ok", reason: null }); render( diff --git a/examples/egocap/frontend/src/RecordingPanel.voice.test.tsx b/examples/egocap/frontend/src/RecordingPanel.voice.test.tsx index 0590e45e86..25f8d719a4 100644 --- a/examples/egocap/frontend/src/RecordingPanel.voice.test.tsx +++ b/examples/egocap/frontend/src/RecordingPanel.voice.test.tsx @@ -109,6 +109,7 @@ function activeSnapshot(overrides: Partial = {}): RecordingSn savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 0, ...overrides, }; diff --git a/examples/egocap/frontend/src/SettingsPanel.test.tsx b/examples/egocap/frontend/src/SettingsPanel.test.tsx index 75b0256171..8039bdbc26 100644 --- a/examples/egocap/frontend/src/SettingsPanel.test.tsx +++ b/examples/egocap/frontend/src/SettingsPanel.test.tsx @@ -2,20 +2,31 @@ // // SPDX-License-Identifier: Apache-2.0 -/** The Settings dialog: tabs, the token-gated station/task changes, catalog import and removal, tools, display - * and the read-only deployment tab. */ +/** The Settings dialog: tabs, the token-gated station and task changes, the live device checklist, catalog import + * and removal, display and the read-only deployment tab. */ import { afterEach, describe, expect, it, vi } from "vitest"; -import { cleanup, fireEvent, render, screen, within, waitFor } from "@testing-library/react"; +import { act, cleanup, fireEvent, render, screen, within, waitFor } from "@testing-library/react"; import { SettingsPanel, type SettingsBackend, type StationSetup } from "./SettingsPanel"; import { SettingsHttpError, type OperatorSettings, type TaskFileListing } from "./settingsApi"; -import { KITCHEN_FIXTURE, OPERATOR_SETTINGS_FIXTURE, SETTINGS_FIXTURE, TASK_FILES_FIXTURE, TOOLS_FIXTURE } from "./settingsTestDoubles"; +import { KITCHEN_FIXTURE, OPERATOR_SETTINGS_FIXTURE, SETTINGS_FIXTURE, STATIONS_FIXTURE, TASK_FILES_FIXTURE, TOOLS_FIXTURE, fakeStationRegistry } from "./settingsTestDoubles"; +import type { SetupStatus } from "./setupApi"; +import { SETUP_HELD, SETUP_READY } from "./setupTestDoubles"; +import type { StationRecord } from "./stationsApi"; afterEach(cleanup); const MID_TRAIN = { name: "Mid.csv", format: "mid_train_csv", tasks: [{ name: "fold_towel", instruction: "Fold a towel" }] }; /** A fake backend over in-memory state, so saves show up on the next load like the real one. */ -function fakeBackend(initial: Partial = {}): SettingsBackend & { operator: OperatorSettings; listing: TaskFileListing } { +function fakeBackend( + initial: Partial & { flow?: SetupStatus } = {}, +): SettingsBackend & { operator: OperatorSettings; listing: TaskFileListing; registry: ReturnType } { + const registry = fakeStationRegistry(initial.stations); + /** As the backend does: the station in use supplies the camera type and roles every reader sees. */ + const effective = (): OperatorSettings => { + const inUse = registry.inUse(); + return inUse === null ? state.operator : { ...state.operator, camera_type: inUse.camera_type, camera_roles: inUse.camera_roles }; + }; const state = { operator: initial.operator ?? OPERATOR_SETTINGS_FIXTURE, listing: initial.taskFiles ?? TASK_FILES_FIXTURE, @@ -28,12 +39,19 @@ function fakeBackend(initial: Partial = {}): SettingsBackend & { o get listing() { return state.listing; }, + registry, + addStation: vi.fn(registry.addStation), + updateStation: vi.fn(registry.updateStation), + deleteStation: vi.fn(registry.deleteStation), + selectStation: vi.fn(registry.selectStation), + loadSetup: vi.fn(async () => initial.flow ?? SETUP_READY), loadDeployment: vi.fn(async () => SETTINGS_FIXTURE), - loadStationSetup: vi.fn(async () => ({ operator: state.operator, tools: state.tools, taskFiles: state.listing })), + loadStationSetup: vi.fn(async () => ({ operator: effective(), tools: state.tools, taskFiles: state.listing, stations: registry.listing })), loadTaskFile: vi.fn(async (name: string) => (name === "Mid.csv" ? MID_TRAIN : KITCHEN_FIXTURE)), saveOperator: vi.fn(async (_token: string, changes) => { - state.operator = { ...state.operator, ...changes }; - return state.operator; + // As the backend does: a role change names only the roles it moves. + state.operator = { ...state.operator, ...changes, camera_roles: { ...state.operator.camera_roles, ...changes.camera_roles } }; + return effective(); }), importTaskFile: vi.fn(async (_token: string, source) => { const name = source.name; @@ -47,6 +65,9 @@ function fakeBackend(initial: Partial = {}): SettingsBackend & { o }; } +const BENCH: StationRecord = { id: "st_1", name: "Bench A", camera_type: "oak_d", camera_roles: { ego: "Ego", wrist_left: null, wrist_right: null }, problems: [] }; +const BENCH_IN_USE = { ...STATIONS_FIXTURE, stations: [BENCH], selected: "st_1", label: "Bench A" }; + function renderPanel(overrides: Partial[0]> = {}, backend = fakeBackend()) { const props = { open: true, @@ -63,6 +84,8 @@ function renderPanel(overrides: Partial[0]> = { } const tab = (name: string) => screen.getByRole("button", { name }); +/** The Station tab once its setup has loaded. */ +const stations = () => screen.findByRole("region", { name: "Stations" }); describe("SettingsPanel shell", () => { it("renders nothing while closed and does not fetch", () => { @@ -73,9 +96,16 @@ describe("SettingsPanel shell", () => { expect(backend.loadStationSetup).not.toHaveBeenCalled(); }); + it("offers Station, Devices, Tasks, Display and Advanced, in that order", () => { + renderPanel(); + const nav = screen.getByRole("navigation", { name: "Settings sections" }); + expect(within(nav).getAllByRole("button").map((button) => button.textContent)).toEqual(["Station", "Devices", "Tasks", "Display", "Advanced"]); + }); + it("opens on the Station tab, switches tabs, and closes on Escape or Close", async () => { const { props } = renderPanel(); - expect(await screen.findByText("Camera type")).toBeTruthy(); + expect(await stations()).toBeTruthy(); + expect(tab("Station").getAttribute("aria-current")).toBe("page"); fireEvent.click(tab("Display")); expect(screen.getByText("Keyboard shortcuts")).toBeTruthy(); expect(tab("Display").getAttribute("aria-current")).toBe("page"); @@ -86,82 +116,295 @@ describe("SettingsPanel shell", () => { }); describe("Station tab", () => { - it("saves the camera type with the control token, then has nothing left to save", async () => { - const { backend } = renderPanel(); - const station = await screen.findByRole("region", { name: "Camera type" }); - const save = within(station).getByRole("button", { name: "Save camera type" }) as HTMLButtonElement; - expect(save.disabled).toBe(true); - fireEvent.click(within(station).getByLabelText(/OAK-D cameras/)); - expect(save.disabled).toBe(false); - fireEvent.click(save); - expect(backend.saveOperator).toHaveBeenCalledWith("tok", { camera_type: "oak_d" }); - expect(((await within(station).findByRole("button", { name: "Save camera type" })) as HTMLButtonElement).disabled).toBe(true); - expect((within(station).getByLabelText(/OAK-D cameras/) as HTMLInputElement).checked).toBe(true); - }); - - it("cannot save without the control token and says where to enter it", async () => { - const { backend } = renderPanel({ controlToken: null }); - const station = await screen.findByRole("region", { name: "Camera type" }); - fireEvent.click(within(station).getByLabelText(/SENSING GMSL cameras/)); - const save = within(station).getByRole("button", { name: "Save camera type" }) as HTMLButtonElement; - expect(save.disabled).toBe(true); - expect(within(station).getByText(/Enter the control token in the recording panel/)).toBeTruthy(); - fireEvent.click(save); - expect(backend.saveOperator).not.toHaveBeenCalled(); + it("is the Stations card alone", async () => { + renderPanel({}, fakeBackend({ stations: BENCH_IN_USE })); + await stations(); + const body = document.querySelector(".settings-content-body") as HTMLElement; + expect(Array.from(body.children).map((part) => part.getAttribute("aria-label"))).toEqual(["Stations"]); + }); + + it("edits the camera setup itself while there are no stations, saving only what changed", async () => { + const backend = fakeBackend({ operator: { ...OPERATOR_SETTINGS_FIXTURE, camera_type: "oak_d", camera_roles: { ego: "Ego", wrist_left: "Wrist A", wrist_right: null } } }); + renderPanel({ cameraSources: ["Ego", "Wrist A", "Wrist B"] }, backend); + await stations(); + const body = document.querySelector(".settings-content-body") as HTMLElement; + expect(Array.from(body.children).map((part) => part.getAttribute("aria-label"))).toEqual(["Stations", "Camera setup"]); + const card = () => within(screen.getByRole("region", { name: "Camera setup" })); + const save = () => card().getByRole("button", { name: "Save camera setup" }) as HTMLButtonElement; + const select = (label: string) => card().getByLabelText(label) as HTMLSelectElement; + expect(card().getByText(/Adding a station moves this setup onto the station/)).toBeTruthy(); + expect(select("Camera type").value).toBe("oak_d"); + expect(save().disabled).toBe(true); // nothing changed yet + // The cameras offered are the session's, and one camera fills one role only. + expect(Array.from(select("Right wrist").options).map((option) => [option.value, option.disabled])).toEqual([["", false], ["Ego", true], ["Wrist A", true], ["Wrist B", false]]); + fireEvent.click(card().getByRole("button", { name: "Swap wrists" })); + expect(select("Right wrist").value).toBe("Wrist A"); + fireEvent.click(save()); + await waitFor(() => expect(backend.saveOperator).toHaveBeenCalledWith("tok", { camera_roles: { wrist_left: null, wrist_right: "Wrist A" } })); + await waitFor(() => expect(save().disabled).toBe(true)); + expect(select("Right wrist").value).toBe("Wrist A"); + fireEvent.change(select("Camera type"), { target: { value: "sensing_gmsl" } }); + fireEvent.click(save()); + await waitFor(() => expect(backend.saveOperator).toHaveBeenLastCalledWith("tok", { camera_type: "sensing_gmsl" })); + // The first station takes the setup over, and from then on holds it: the card is gone. + await waitFor(() => expect(backend.operator.camera_type).toBe("sensing_gmsl")); + await waitFor(() => expect(save().textContent).toBe("Save camera setup")); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "Bench A" } }); + fireEvent.click(screen.getByRole("button", { name: "Add station" })); + await waitFor(() => expect(screen.queryByRole("region", { name: "Camera setup" })).toBeNull()); + expect(backend.registry.inUse()).toMatchObject({ camera_type: "sensing_gmsl", camera_roles: { ego: "Ego", wrist_left: null, wrist_right: "Wrist A" } }); }); - it("shows a rejected save in place and keeps the unsaved choice", async () => { + it("shows why a camera setup save was refused and keeps what was chosen", async () => { const backend = fakeBackend(); backend.saveOperator = vi.fn(async () => { - throw new SettingsHttpError("control token rejected"); + throw new SettingsHttpError("camera 'Ego' is not offered by the capture session"); }); - renderPanel({}, backend); - const station = await screen.findByRole("region", { name: "Camera type" }); - fireEvent.click(within(station).getByLabelText(/OAK-D cameras/)); - fireEvent.click(within(station).getByRole("button", { name: "Save camera type" })); - expect(await within(station).findByText(/Not saved: control token rejected/)).toBeTruthy(); - expect((within(station).getByLabelText(/OAK-D cameras/) as HTMLInputElement).checked).toBe(true); - }); - - it("assigns the session's cameras to roles, refuses one camera in two roles, swaps wrists, and saves only the roles", async () => { - const { backend } = renderPanel({ cameraSources: ["Ego", "Wrist A", "Wrist B"] }); - const roles = await screen.findByRole("region", { name: "Camera roles" }); - const ego = within(roles).getByLabelText("Ego (head)") as HTMLSelectElement; - const left = within(roles).getByLabelText("Left wrist") as HTMLSelectElement; - const right = within(roles).getByLabelText("Right wrist") as HTMLSelectElement; - const save = within(roles).getByRole("button", { name: "Save camera roles" }) as HTMLButtonElement; - expect(save.disabled).toBe(true); - fireEvent.change(ego, { target: { value: "Ego" } }); - fireEvent.change(left, { target: { value: "Wrist A" } }); - // A camera already used by another role cannot be picked again. - expect((within(right).getByRole("option", { name: "Wrist A" }) as HTMLOptionElement).disabled).toBe(true); - fireEvent.change(right, { target: { value: "Wrist B" } }); - fireEvent.click(within(roles).getByRole("button", { name: "Swap wrists" })); - expect(left.value).toBe("Wrist B"); - expect(right.value).toBe("Wrist A"); - fireEvent.click(save); - expect(backend.saveOperator).toHaveBeenCalledWith("tok", { camera_roles: { ego: "Ego", wrist_left: "Wrist B", wrist_right: "Wrist A" } }); - expect(((await within(roles).findByRole("button", { name: "Save camera roles" })) as HTMLButtonElement).disabled).toBe(true); - expect(screen.getByLabelText("Station readiness").textContent).toContain("3/3 roles assigned"); - }); - - it("keeps a saved camera the session no longer offers selectable, marked, so it can be cleared", async () => { - renderPanel( - { cameraSources: ["Ego"] }, - fakeBackend({ operator: { ...OPERATOR_SETTINGS_FIXTURE, camera_roles: { ego: "Ego", wrist_left: "Old wrist", wrist_right: null } } }), + renderPanel({ cameraSources: ["Ego"] }, backend); + await stations(); + const card = screen.getByRole("region", { name: "Camera setup" }); + fireEvent.change(within(card).getByLabelText("Ego (head)"), { target: { value: "Ego" } }); + fireEvent.click(within(card).getByRole("button", { name: "Save camera setup" })); + expect(await within(card).findByText("Not saved: camera 'Ego' is not offered by the capture session")).toBeTruthy(); + expect((within(card).getByLabelText("Ego (head)") as HTMLSelectElement).value).toBe("Ego"); + }); + + it("shows the camera setup read-only without the control token", async () => { + renderPanel({ controlToken: null, cameraSources: ["Ego"] }); + await stations(); + const card = screen.getByRole("region", { name: "Camera setup" }); + expect((within(card).getByLabelText("Camera type") as HTMLSelectElement).disabled).toBe(true); + expect((within(card).getByLabelText("Ego (head)") as HTMLSelectElement).disabled).toBe(true); + expect((within(card).getByRole("button", { name: "Save camera setup" }) as HTMLButtonElement).disabled).toBe(true); + expect(within(card).getByText(/Enter the control token in the recording panel/)).toBeTruthy(); + }); + + it("shows the setup saved with the settings once the last station is deleted, not that station's", async () => { + const backend = fakeBackend({ stations: BENCH_IN_USE, operator: { ...OPERATOR_SETTINGS_FIXTURE, camera_type: "sensing_gmsl" } }); + renderPanel({ cameraSources: ["Ego"] }, backend); + const card = await stations(); + const reads: Array<() => void> = []; + vi.mocked(backend.loadStationSetup).mockImplementation( + () => new Promise((resolve) => reads.push(() => resolve({ operator: backend.operator, tools: TOOLS_FIXTURE, taskFiles: backend.listing, stations: backend.registry.listing }))), ); - const roles = await screen.findByRole("region", { name: "Camera roles" }); - const left = within(roles).getByLabelText("Left wrist") as HTMLSelectElement; - expect(left.value).toBe("Old wrist"); - expect(within(left).getByRole("option", { name: "Old wrist (not in this session)" })).toBeTruthy(); - expect(screen.getByLabelText("Station readiness").textContent).toContain("1/2 assigned cameras in this session"); + fireEvent.click(within(card).getByRole("button", { name: "Delete" })); + fireEvent.click(within(card).getByRole("button", { name: "Delete Bench A" })); + // The card appears with the registry change, before the setup has been read again without the station. + const setup = await screen.findByRole("region", { name: "Camera setup" }); + expect(reads).toHaveLength(1); + await act(async () => reads[0]()); + expect((within(setup).getByLabelText("Camera type") as HTMLSelectElement).value).toBe("sensing_gmsl"); + expect((within(setup).getByLabelText("Ego (head)") as HTMLSelectElement).value).toBe(""); + expect((within(setup).getByRole("button", { name: "Save camera setup" }) as HTMLButtonElement).disabled).toBe(true); + }); + + it("holds the camera setup and a first station when the setup cannot be read again after the last station is deleted", async () => { + const backend = fakeBackend({ stations: BENCH_IN_USE, operator: { ...OPERATOR_SETTINGS_FIXTURE, camera_type: "sensing_gmsl" } }); + renderPanel({ cameraSources: ["Ego"] }, backend); + const card = await stations(); + vi.mocked(backend.loadStationSetup).mockRejectedValueOnce(new Error("offline")); + fireEvent.click(within(card).getByRole("button", { name: "Delete" })); + fireEvent.click(within(card).getByRole("button", { name: "Delete Bench A" })); + // What is on screen is still the deleted station's setup, so it is neither shown as the site's nor inherited. + const retry = await screen.findByRole("button", { name: "Read again" }); + expect(screen.queryByRole("region", { name: "Camera setup" })).toBeNull(); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "Bench B" } }); + expect((screen.getByRole("button", { name: "Add station" }) as HTMLButtonElement).disabled).toBe(true); + fireEvent.click(retry); + const setup = await screen.findByRole("region", { name: "Camera setup" }); + expect((within(setup).getByLabelText("Camera type") as HTMLSelectElement).value).toBe("sensing_gmsl"); + expect(screen.queryByRole("button", { name: "Read again" })).toBeNull(); + expect((screen.getByRole("button", { name: "Add station" }) as HTMLButtonElement).disabled).toBe(false); + }); + + it("does not add the first station while a camera setup save is still on its way", async () => { + const backend = fakeBackend(); + const saved: Array<() => void> = []; + const realSave = backend.saveOperator; + backend.saveOperator = vi.fn((token: string, changes) => new Promise((resolve) => saved.push(() => resolve(realSave(token, changes))))); + renderPanel({ cameraSources: ["Ego"] }, backend); + await stations(); + const setup = screen.getByRole("region", { name: "Camera setup" }); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "Bench A" } }); + const add = () => screen.getByRole("button", { name: "Add station" }) as HTMLButtonElement; + expect(add().disabled).toBe(false); + fireEvent.change(within(setup).getByLabelText("Ego (head)"), { target: { value: "Ego" } }); + fireEvent.click(within(setup).getByRole("button", { name: "Save camera setup" })); + // The first station inherits the saved setup, so it waits for the save to answer. + await waitFor(() => expect(add().disabled).toBe(true)); + await act(async () => saved[0]()); + await waitFor(() => expect(add().disabled).toBe(false)); + }); + + it("does not let an older read of the station setup replace a newer change", async () => { + const backend = fakeBackend({ stations: BENCH_IN_USE }); + renderPanel({ cameraSources: ["Ego", "Wrist A"] }, backend); + const card = await stations(); + // From here each read of the setup answers only when the test lets it, with the registry as it was when sent. + const reads: Array<() => void> = []; + vi.mocked(backend.loadStationSetup).mockImplementation(() => { + const picture = { operator: backend.operator, tools: TOOLS_FIXTURE, taskFiles: backend.listing, stations: backend.registry.listing }; + return new Promise((resolve) => reads.push(() => resolve(picture))); + }); + const editButton = () => within(card).getByRole("button", { name: "Edit" }) as HTMLButtonElement; + // A rename starts a read; a camera change is saved while that read is still on its way. + fireEvent.click(editButton()); + fireEvent.change(within(card).getByLabelText("Name"), { target: { value: "Bench Z" } }); + fireEvent.click(within(card).getByRole("button", { name: "Save" })); + await within(card).findByLabelText("Use Bench Z"); + await waitFor(() => expect(editButton().disabled).toBe(false)); + fireEvent.click(editButton()); + fireEvent.change(within(card).getByLabelText("Left wrist"), { target: { value: "Wrist A" } }); + fireEvent.click(within(card).getByRole("button", { name: "Save" })); + const assigned = "Ego (head): Ego · Left wrist: Wrist A · Right wrist: —"; + await within(card).findByText(assigned); + expect(reads).toHaveLength(2); + // The newer read answers first, then the older one, which still shows no left wrist camera. + await act(async () => reads[1]()); + await act(async () => reads[0]()); + expect(within(card).getByText(assigned)).toBeTruthy(); + }); + + it("reads the station setup again when a change is saved while a read is on its way", async () => { + const backend = fakeBackend({ stations: BENCH_IN_USE }); + renderPanel({}, backend); + const card = await stations(); + const reads: Array<(setup: StationSetup) => void> = []; + const current = (): StationSetup => ({ operator: backend.operator, tools: TOOLS_FIXTURE, taskFiles: backend.listing, stations: backend.registry.listing }); + vi.mocked(backend.loadStationSetup).mockImplementation(() => new Promise((resolve) => reads.push(resolve))); + fireEvent.click(within(card).getByLabelText("Use no station")); + await waitFor(() => expect(reads).toHaveLength(1)); + const before = current(); // read before the requirement is saved + fireEvent.click(tab("Devices")); + fireEvent.click(await screen.findByLabelText("Require calibration files before recording")); + await waitFor(() => expect(reads).toHaveLength(2)); + await act(async () => reads[0](before)); + expect((screen.getByLabelText("Require calibration files before recording") as HTMLInputElement).checked).toBe(true); + await act(async () => reads[1](current())); + expect((screen.getByLabelText("Require calibration files before recording") as HTMLInputElement).checked).toBe(true); + }); + + it("adds the first station, puts it in use, and then edits that station's cameras in its row", async () => { + const backend = fakeBackend({ operator: { ...OPERATOR_SETTINGS_FIXTURE, camera_type: "oak_d" } }); + renderPanel({ cameraSources: ["Ego", "Wrist A"] }, backend); + const card = await stations(); + fireEvent.change(within(card).getByLabelText("New station name"), { target: { value: "Bench A" } }); + fireEvent.click(within(card).getByRole("button", { name: "Add station" })); + await waitFor(() => expect((within(card).getByLabelText("Use Bench A") as HTMLInputElement).checked).toBe(true)); + // The camera type saved before any station existed became the station's own. + expect(backend.registry.inUse()).toMatchObject({ name: "Bench A", camera_type: "oak_d" }); + // The station setup is read again, so the rest of the dialog goes by the station in use. + expect(backend.loadStationSetup).toHaveBeenCalledTimes(2); + expect(backend.loadStationSetup).toHaveBeenLastCalledWith(expect.any(AbortSignal)); + fireEvent.click(within(card).getByRole("button", { name: "Edit" })); + const editor = within(card).getByRole("group", { name: "Edit Bench A" }); + expect((within(editor).getByLabelText("Camera type") as HTMLSelectElement).value).toBe("oak_d"); + fireEvent.change(within(editor).getByLabelText("Ego (head)"), { target: { value: "Ego" } }); + fireEvent.click(within(editor).getByRole("button", { name: "Save" })); + await waitFor(() => expect(backend.registry.inUse()?.camera_roles.ego).toBe("Ego")); + expect(backend.updateStation).toHaveBeenCalledWith("tok", "st_1", { camera_roles: { ego: "Ego" } }); + expect(await within(card).findByText("Ego (head): Ego · Left wrist: — · Right wrist: —")).toBeTruthy(); + // Camera setup goes through the station routes only. + expect(backend.saveOperator).not.toHaveBeenCalled(); + }); + + it("shows where the headset connects in the editor of the station in use, from the page's flow", async () => { + const setup: SetupStatus = { ...SETUP_READY, headset: { address: "10.0.0.42", saved: "10.0.0.7", changed: true } }; + renderPanel({ setup }, fakeBackend({ stations: BENCH_IN_USE })); + const card = await stations(); + const warning = "This host's address changed from 10.0.0.7 to 10.0.0.42. Enter the new one in the headset."; + expect(within(card).getByText(warning)).toBeTruthy(); + fireEvent.click(within(card).getByRole("button", { name: "Edit" })); + expect(within(card).getByText("Headset connects to 10.0.0.42")).toBeTruthy(); + expect(within(card).getAllByText(warning)).toHaveLength(1); + }); + + it("says nothing about the headset when the flow was read without the control token", async () => { + renderPanel({ setup: SETUP_READY, controlToken: null }, fakeBackend({ stations: BENCH_IN_USE })); + const card = await stations(); + expect(within(card).queryByText(/Headset connects to/)).toBeNull(); + expect(within(card).getByText(/Enter the control token in the recording panel/)).toBeTruthy(); + }); + + it("closes a station's editor on Escape and stays open itself", async () => { + const { props } = renderPanel({}, fakeBackend({ stations: BENCH_IN_USE })); + const card = await stations(); + fireEvent.click(within(card).getByRole("button", { name: "Edit" })); + fireEvent.keyDown(within(card).getByLabelText("Name"), { key: "Escape" }); + expect(within(card).queryByRole("group")).toBeNull(); + expect(props.onClose).not.toHaveBeenCalled(); + fireEvent.keyDown(within(card).getByLabelText("New station name"), { key: "Escape" }); + expect(props.onClose).toHaveBeenCalledTimes(1); + }); + + it("keeps the changed registry on screen when reading the setup again fails", async () => { + const backend = fakeBackend(); + renderPanel({}, backend); + const card = await stations(); + backend.loadStationSetup = vi.fn(async () => { + throw new SettingsHttpError("stations are not available yet"); + }); + fireEvent.change(within(card).getByLabelText("New station name"), { target: { value: "Bench A" } }); + fireEvent.click(within(card).getByRole("button", { name: "Add station" })); + expect(await within(card).findByLabelText("Use Bench A")).toBeTruthy(); + }); +}); + +describe("Devices tab", () => { + it("reads the flow itself with the control token and shows the verdict and the checklist", async () => { + const { backend } = renderPanel({ initialTab: "devices" }, fakeBackend({ flow: SETUP_HELD })); + expect((await screen.findByRole("status")).textContent).toBe("Recording is held: Left wrist: cam_left: no recent frame."); + expect(backend.loadSetup).toHaveBeenCalledWith(expect.any(AbortSignal), "tok"); + const checklist = screen.getByRole("region", { name: "Checklist" }); + expect(within(checklist).getAllByRole("region").map((group) => group.getAttribute("aria-label"))).toEqual(["Tracking", "Cameras", "System"]); + expect(within(checklist).getByText("Left wrist: cam_left")).toBeTruthy(); + }); + + it("turns the calibration requirement on with the control token, and the checklist is read again at once", async () => { + const backend = fakeBackend({ flow: SETUP_READY }); + renderPanel({ initialTab: "devices" }, backend); + const box = (await screen.findByLabelText("Require calibration files before recording")) as HTMLInputElement; + expect(box.checked).toBe(false); + await waitFor(() => expect(backend.loadSetup).toHaveBeenCalledTimes(1)); + fireEvent.click(box); + await waitFor(() => expect(backend.saveOperator).toHaveBeenCalledWith("tok", { require_calibration: true })); + await waitFor(() => expect(backend.loadSetup).toHaveBeenCalledTimes(2)); + expect(box.checked).toBe(true); + expect(backend.operator.require_calibration).toBe(true); + }); + + it("shows the page's flow at once, before its own read answers", () => { + const backend = fakeBackend(); + backend.loadSetup = vi.fn(() => new Promise(() => {})); // never answers + renderPanel({ initialTab: "devices", setup: SETUP_HELD }, backend); + expect(screen.getByRole("status").textContent).toBe("Recording is held: Left wrist: cam_left: no recent frame."); + }); + + it("does not read the flow while another tab is shown", async () => { + const { backend } = renderPanel(); + await stations(); + expect(backend.loadSetup).not.toHaveBeenCalled(); + fireEvent.click(tab("Devices")); + expect(await screen.findByRole("status")).toBeTruthy(); + expect(backend.loadSetup).toHaveBeenCalledTimes(1); + }); + + it("lists every calibration tool disabled with the backend's reason, and scopes fisheye rectification to SENSING stations", async () => { + renderPanel({ initialTab: "devices" }, fakeBackend({ operator: { ...OPERATOR_SETTINGS_FIXTURE, camera_type: "oak_d" } })); + const tools = await screen.findByRole("region", { name: "Calibration tools" }); + const buttons = within(tools).getAllByRole("button", { name: "Open" }) as HTMLButtonElement[]; + expect(buttons).toHaveLength(3); + expect(buttons.every((button) => button.disabled)).toBe(true); + expect(within(tools).getAllByText(/not wired in this build/)).toHaveLength(3); + expect(within(tools).getByText("Fisheye rectification")).toBeTruthy(); + expect(within(tools).getByText(/Only fisheye lenses need this/)).toBeTruthy(); }); }); describe("Tasks tab", () => { it("lists the catalogs, lets the operator choose the one the task editor offers, and shows its preselect card", async () => { const { backend } = renderPanel(); - await screen.findByText("Camera type"); + await stations(); fireEvent.click(tab("Tasks")); const catalogs = await screen.findByRole("list", { name: "Task catalogs" }); expect(within(catalogs).getByText("Kitchen.csv")).toBeTruthy(); @@ -178,7 +421,7 @@ describe("Tasks tab", () => { it("imports catalogs by file, then lists it as imported and reports its task count", async () => { const { backend } = renderPanel(); - await screen.findByText("Camera type"); + await stations(); fireEvent.click(tab("Tasks")); const add = await screen.findByRole("region", { name: "Add a catalog" }); const mid = new File(["Task Name,Task Description\nfold_towel,Fold a towel\n"], "Mid.csv", { type: "text/csv" }); @@ -203,7 +446,7 @@ describe("Tasks tab", () => { throw new SettingsHttpError("Bad.csv is neither a studio catalog nor a Mid Train file"); }); renderPanel({}, backend); - await screen.findByText("Camera type"); + await stations(); fireEvent.click(tab("Tasks")); const add = await screen.findByRole("region", { name: "Add a catalog" }); const bad = new File(["bad"], "Bad.csv", { type: "text/csv" }); @@ -224,7 +467,7 @@ describe("Tasks tab", () => { it("is read-only without the control token", async () => { renderPanel({ controlToken: null }); - await screen.findByText("Camera type"); + await stations(); fireEvent.click(tab("Tasks")); const catalogs = await screen.findByRole("list", { name: "Task catalogs" }); expect((within(catalogs).getByLabelText("Use Kitchen.csv in the task editor") as HTMLInputElement).disabled).toBe(true); @@ -233,25 +476,10 @@ describe("Tasks tab", () => { }); }); -describe("Tools tab", () => { - it("lists every tool disabled with the backend's reason, and scopes fisheye rectification to SENSING stations", async () => { - renderPanel({}, fakeBackend({ operator: { ...OPERATOR_SETTINGS_FIXTURE, camera_type: "oak_d" } })); - await screen.findByText("Camera type"); - fireEvent.click(tab("Tools")); - const tools = await screen.findByRole("region", { name: "Operator tools" }); - const buttons = within(tools).getAllByRole("button", { name: "Open" }) as HTMLButtonElement[]; - expect(buttons).toHaveLength(3); - expect(buttons.every((button) => button.disabled)).toBe(true); - expect(within(tools).getAllByText(/not wired in this build/)).toHaveLength(3); - expect(within(tools).getByText("Fisheye rectification")).toBeTruthy(); - expect(within(tools).getByText(/Only fisheye lenses need this/)).toBeTruthy(); - }); -}); - describe("Display tab", () => { it("offers a side-panel reset only when the width differs from the default, and lists the shortcuts", async () => { const { props, unmount } = renderPanel({ sidebarWidth: 600 }); - await screen.findByText("Camera type"); + await stations(); fireEvent.click(tab("Display")); expect(screen.getByText("600 px")).toBeTruthy(); fireEvent.click(screen.getByRole("button", { name: "Reset side panel width" })); @@ -314,7 +542,7 @@ describe("SettingsPanel focus ownership", () => { const { rerender, props } = renderPanel(); const dialog = screen.getByRole("dialog"); expect(document.activeElement).toBe(dialog); - await screen.findByText("Camera type"); + await stations(); fireEvent.keyDown(dialog, { key: "Tab" }); expect(document.activeElement).toBe(tab("Station")); const controls = Array.from(dialog.querySelectorAll('button, input, select, textarea, a[href], [tabindex]')) diff --git a/examples/egocap/frontend/src/SettingsPanel.tsx b/examples/egocap/frontend/src/SettingsPanel.tsx index b034a5a515..e818bb2272 100644 --- a/examples/egocap/frontend/src/SettingsPanel.tsx +++ b/examples/egocap/frontend/src/SettingsPanel.tsx @@ -5,16 +5,23 @@ /** * The Settings dialog: a tabbed modal over the page. * - * Tabs, in the order an operator sets up a station: Station (camera type and roles), Tasks (the catalogs the task picker - * offers, imports, and the preselected task), Tools (calibration and rectification), Display (this browser's - * choices and the keyboard shortcuts), Advanced (what the deployment is running with, read-only). Station and Tasks - * are saved by the backend for every browser and need the run's control token to change, as recording - * commands do; Tools lists unavailable stubs; Display is this browser's only; Advanced values are set where the backend is launched. + * Tabs, in the order an operator sets up a station: Station (the stations, the one in use, and each station's + * cameras; the camera setup itself while there are no stations), Devices (the live checklist of what the station + * in use needs, whether calibration files are required, and the calibration tools), Tasks (the catalogs the task + * picker offers, imports, and the preselected task), Display (this browser's choices and the keyboard + * shortcuts), Advanced (what the deployment is running with, read-only). Station, Tasks and the calibration + * requirement are saved by the backend for every browser and need the run's control token to change, as + * recording commands do; the rest of Devices only reports; Display is this browser's only; Advanced values are + * set where the backend is launched. */ -import { useCallback, useEffect, useRef, useState, type ReactNode } from "react"; +import { useCallback, useEffect, useRef, useState } from "react"; +import { CameraSetupCard } from "./CameraSetupCard"; +import { DevicesTab } from "./DevicesTab"; +import { Card, LoadState, TokenHint, errorMessage, useAction, useEscapeToClose, useModalFocus, type Loaded } from "./settingsParts"; +import { StationsCard } from "./StationsCard"; +import { fetchSetup, type SetupStatus } from "./setupApi"; +import { addStation, deleteStation, fetchStations, selectStation, updateStation, type StationChange, type StationListing } from "./stationsApi"; import { - CAMERA_TYPE_LABELS, - ROLE_LABELS, fetchOperatorSettings, fetchSettings, fetchTaskFile, @@ -33,9 +40,11 @@ import { } from "./settingsApi"; export interface StationSetup { + /** The camera setup in effect: the station in use supplies it, else the values saved with the operator settings. */ operator: OperatorSettings; tools: ToolInfo[]; taskFiles: TaskFileListing; + stations: StationListing; } /** The backend calls the dialog makes; tests inject fakes, the page uses the real ones. */ @@ -46,26 +55,42 @@ export interface SettingsBackend { saveOperator: (controlToken: string, changes: OperatorSettingsChange) => Promise; importTaskFile: (controlToken: string, source: TaskFileSource) => Promise; removeTaskFile: (controlToken: string, name: string) => Promise; + addStation: (controlToken: string, fields: StationChange) => Promise; + updateStation: (controlToken: string, id: string, changes: StationChange) => Promise; + deleteStation: (controlToken: string, id: string) => Promise; + selectStation: (controlToken: string, id: string | null) => Promise; + /** The start-of-day flow, which the Devices tab reads on its own, faster timer. */ + loadSetup: (signal: AbortSignal, controlToken?: string | null) => Promise; } export const REAL_SETTINGS_BACKEND: SettingsBackend = { loadDeployment: fetchSettings, loadStationSetup: async (signal) => { - const [operator, tools, taskFiles] = await Promise.all([fetchOperatorSettings(signal), fetchTools(signal), fetchTaskFiles(signal)]); - return { operator, tools, taskFiles }; + const [operator, tools, taskFiles, stations] = await Promise.all([ + fetchOperatorSettings(signal), + fetchTools(signal), + fetchTaskFiles(signal), + fetchStations(signal), + ]); + return { operator, tools, taskFiles, stations }; }, loadTaskFile: fetchTaskFile, saveOperator: saveOperatorSettings, importTaskFile, removeTaskFile, + addStation, + updateStation, + deleteStation, + selectStation, + loadSetup: fetchSetup, }; -export type SettingsTab = "station" | "tasks" | "tools" | "display" | "advanced"; +export type SettingsTab = "station" | "devices" | "tasks" | "display" | "advanced"; const TABS: ReadonlyArray<{ id: SettingsTab; label: string }> = [ { id: "station", label: "Station" }, + { id: "devices", label: "Devices" }, { id: "tasks", label: "Tasks" }, - { id: "tools", label: "Tools" }, { id: "display", label: "Display" }, { id: "advanced", label: "Advanced" }, ]; @@ -81,17 +106,12 @@ export interface SettingsPanelProps { controlToken: string | null; /** The cameras the current session offers, by name. */ cameraSources?: string[]; + /** The start-of-day flow as the page last read it; null while it could not be read. */ + setup?: SetupStatus | null; initialTab?: SettingsTab; backend?: SettingsBackend; } -type Loaded = { kind: "loading" } | { kind: "error"; message: string } | { kind: "loaded"; value: T }; - -/** Turn unknown request failures into a concise operator-facing explanation. */ -function errorMessage(error: unknown): string { - return error instanceof Error ? error.message : String(error); -} - /** Loads `load` each time the dialog opens, so a backend restart shows its new values; abandons a load the * dialog closed on. */ function useLoaded(open: boolean, load: (signal: AbortSignal) => Promise): [Loaded, (update: (value: T) => T) => void] { @@ -138,225 +158,90 @@ function Row({ label, value, mono = false }: { label: string; value: string; mon ); } -/** One titled block of a tab. */ -function Card({ title, lead, children }: { title: string; lead?: string; children: ReactNode }) { - return ( -
    -

    {title}

    - {lead !== undefined &&

    {lead}

    } - {children} -
    - ); -} - -/** Explain why station changes require the recording control token. */ -function TokenHint({ controlToken }: { controlToken: string | null }) { - if (controlToken !== null) return null; - return

    Enter the control token in the recording panel to change these.

    ; -} - -/** The pending/failed state of one save-type action, shown next to its button. */ -function useAction(): [{ busy: boolean; failure: string | null }, (work: () => Promise) => void] { - const [busy, setBusy] = useState(false); - const [failure, setFailure] = useState(null); - /** Keep request failures visible and prevent duplicate submissions. */ - const run = (work: () => Promise) => { - setBusy(true); - setFailure(null); - work().then( - () => setBusy(false), - (error: unknown) => { - setBusy(false); - setFailure(errorMessage(error)); - }, - ); - }; - return [{ busy, failure }, run]; -} - // --- Station --------------------------------------------------------------------------------------------------- -/** Offer persistent camera setup and explain which roles are currently available. */ +/** The stations and the one in use; each station's cameras are edited in its own row. While there are no + * stations the camera setup is edited here instead, since no station holds it yet. */ function StationTab({ + stationSetup, setup, controlToken, backend, cameraSources, - onOperator, + setupUnread, + onReload, + onStations, + onSetup, }: { - setup: Loaded; + stationSetup: Loaded; + setup: SetupStatus | null; controlToken: string | null; backend: SettingsBackend; cameraSources: string[]; - onOperator: (operator: OperatorSettings) => void; -}) { - if (setup.kind !== "loaded") return ; - const { operator } = setup.value; - return ( - <> - - - - - - - - - - ); -} - -/** The station's readiness at a glance: what is set, what is still to do. */ -function ReadyLine({ operator, cameraSources }: { operator: OperatorSettings; cameraSources: string[] }) { - const assigned = operator.roles.filter((role) => operator.camera_roles[role] !== null); - const offered = assigned.filter((role) => cameraSources.includes(operator.camera_roles[role] ?? "")); - const items: Array<[boolean, string]> = [ - [operator.camera_type !== null, operator.camera_type === null ? "Camera type not set" : `Camera type: ${CAMERA_TYPE_LABELS[operator.camera_type]?.split(" — ")[0] ?? operator.camera_type}`], - [assigned.length === operator.roles.length, `${assigned.length}/${operator.roles.length} roles assigned`], - [assigned.length > 0 && offered.length === assigned.length, cameraSources.length === 0 ? "No cameras offered by the session yet" : `${offered.length}/${assigned.length} assigned cameras in this session`], - [operator.task_file !== null, operator.task_file === null ? "No task catalog chosen" : `Task catalog: ${operator.task_file}`], - ]; - return ( -

    - {items.map(([ok, text]) => ( - - {ok ? "✓" : "○"} {text} - - ))} -

    - ); -} - -/** One select per role over the cameras the session offers; a camera already saved for a role that the session - * no longer offers stays selectable, so an operator can see (and clear) it. */ -function CameraRoles({ - operator, - cameraSources, - controlToken, - save, - onSaved, -}: { - operator: OperatorSettings; - cameraSources: string[]; - controlToken: string | null; - save: SettingsBackend["saveOperator"]; - onSaved: (operator: OperatorSettings) => void; + /** Whether the station setup could not be read again after the registry changed, so the camera setup on screen may be a deleted station's. */ + setupUnread: boolean; + onReload: () => void; + onStations: (stations: StationListing) => void; + onSetup: (update: (value: StationSetup) => StationSetup) => void; }) { - const [roles, setRoles] = useState>({ ...operator.camera_roles }); - const [{ busy, failure }, run] = useAction(); - const dirty = operator.roles.some((role) => roles[role] !== operator.camera_roles[role]); - const options = [...new Set([...cameraSources, ...Object.values(roles).filter((name): name is string => name !== null)])]; - /** Exclude cameras assigned to another role from this selector. */ - const taken = (role: string) => new Set(operator.roles.filter((other) => other !== role).map((other) => roles[other])); - /** Swap both wrists in one local update so assignments stay unique. */ - const swapWrists = () => setRoles((current) => ({ ...current, wrist_left: current.wrist_right ?? null, wrist_right: current.wrist_left ?? null })); - return ( - <> - {options.length === 0 &&

    The session offers no cameras yet; roles can be assigned once CaptureServer lists them.

    } -
    - {operator.roles.map((role) => ( - - - - ))} -
    -
    - - - {failure !== null && Not saved: {failure}} -
    - - - ); -} - -/** Group the label and control for a single camera role. */ -function FragmentRow({ role, children }: { role: string; children: ReactNode }) { + // A camera setup save in flight: the first station inherits the saved setup, so it must not be added over it. + const [savingCameras, setSavingCameras] = useState(false); + if (stationSetup.kind !== "loaded") return ; + const { operator, stations } = stationSetup.value; + const empty = stations.stations.length === 0; + // With no station the camera setup on screen is what the first one inherits, so it must be the saved one. + const unknownSetup = empty && setupUnread; + /** Save the camera setup, holding the first station's creation until the save has answered. */ + const saveCameras = (changes: OperatorSettingsChange): Promise => { + if (controlToken === null) return Promise.resolve(); + setSavingCameras(true); + return backend + .saveOperator(controlToken, changes) + .then((saved) => onSetup((value) => ({ ...value, operator: saved }))) + .finally(() => setSavingCameras(false)); + }; return ( <> - - {children} + + {unknownSetup && ( +

    + The camera setup could not be read again, so it cannot be edited or handed to a new station yet.{" "} + +

    + )} + {empty && !unknownSetup && } ); } -/** Edit the station camera type while keeping unsaved choices local. */ -function CameraTypeChoice({ - operator, - controlToken, - save, - onSaved, -}: { - operator: OperatorSettings; - controlToken: string | null; - save: SettingsBackend["saveOperator"]; - onSaved: (operator: OperatorSettings) => void; -}) { - const [choice, setChoice] = useState(operator.camera_type); - const [{ busy, failure }, run] = useAction(); - const dirty = choice !== operator.camera_type; - return ( -
    - Choose the camera type - {operator.camera_types.map((type) => ( - - ))} - -
    - - {failure !== null && Not saved: {failure}} -
    -
    - ); -} - // --- Tasks ----------------------------------------------------------------------------------------------------- /** Manage the selected catalog, task defaults and browser uploads. */ function TasksTab({ - setup, + stationSetup, controlToken, backend, onSetup, }: { - setup: Loaded; + stationSetup: Loaded; controlToken: string | null; backend: SettingsBackend; onSetup: (update: (value: StationSetup) => StationSetup) => void; }) { - if (setup.kind !== "loaded") return ; - const { operator, taskFiles } = setup.value; + if (stationSetup.kind !== "loaded") return ; + const { operator, taskFiles } = stationSetup.value; const canChange = controlToken !== null; return ( <> @@ -555,38 +440,6 @@ function PreselectedTask({ ); } -// --- Tools ----------------------------------------------------------------------------------------------------- - -/** Show calibration tools and the reason unavailable tools are disabled. */ -function ToolsTab({ setup }: { setup: Loaded }) { - if (setup.kind !== "loaded") return ; - const { tools, operator } = setup.value; - return ( - -
      - {tools.map((tool) => { - const forOtherCameras = tool.applies_to !== null && operator.camera_type !== null && tool.applies_to !== operator.camera_type; - const reason = !tool.available ? tool.unavailable_reason : forOtherCameras ? `for ${CAMERA_TYPE_LABELS[tool.applies_to ?? ""]?.split(" — ")[0] ?? tool.applies_to} stations` : null; - return ( -
    • -
      - {tool.name} - - {tool.description} - {reason !== null && ` — ${reason}.`} - -
      - -
    • - ); - })} -
    -
    - ); -} - // --- Display --------------------------------------------------------------------------------------------------- const SHORTCUTS: ReadonlyArray<[string, string]> = [ @@ -698,52 +551,6 @@ function AdvancedTab({ deployment }: { deployment: Loaded }) // --- Shell ----------------------------------------------------------------------------------------------------- -/** Explain an incomplete request without presenting stale controls. */ -function LoadState({ state, what }: { state: Loaded; what: string }) { - if (state.kind === "loading") return

    Loading…

    ; - if (state.kind === "error") return

    {what} unavailable: {state.message}

    ; - return null; -} - -/** Own keyboard focus for the dialog lifetime and return it to the invoking control. */ -function useModalFocus(open: boolean) { - const dialogRef = useRef(null); - useEffect(() => { - if (!open || !dialogRef.current) return; - const dialog = dialogRef.current; - const previous = document.activeElement; - /** Recompute controls because loading, tab changes and saves can change their availability. */ - const controls = () => Array.from(dialog.querySelectorAll( - 'button, input, select, textarea, a[href], [tabindex]', - )).filter((element) => element.tabIndex >= 0 && !element.matches(":disabled") && !element.closest("[hidden], [inert]")); - /** Programmatic focus and pointer interaction must also respect the modal boundary. */ - const containFocus = (event: FocusEvent) => { - if (!dialog.contains(event.target as Node)) dialog.focus(); - }; - /** Cycle only the current dialog controls, including wraparound in either direction. */ - const onTab = (event: KeyboardEvent) => { - if (event.key !== "Tab" || event.altKey || event.ctrlKey || event.metaKey) return; - const available = controls(); - const current = available.indexOf(document.activeElement as HTMLElement); - const next = event.shiftKey - ? (current <= 0 ? available.length - 1 : current - 1) - : (current + 1) % available.length; - event.preventDefault(); - (available[next] ?? dialog).focus(); - }; - document.addEventListener("focusin", containFocus); - document.addEventListener("keydown", onTab); - dialog.focus(); - return () => { - // Release containment before restoring focus; rerenders must not recapture the invoking control. - document.removeEventListener("focusin", containFocus); - document.removeEventListener("keydown", onTab); - if (previous instanceof HTMLElement && previous.isConnected) previous.focus(); - }; - }, [open]); - return dialogRef; -} - /** Present station settings in a modal that owns focus until it closes. */ export function SettingsPanel({ open, @@ -753,6 +560,7 @@ export function SettingsPanel({ onResetSidebar, controlToken, cameraSources = [], + setup = null, initialTab = "station", backend = REAL_SETTINGS_BACKEND, }: SettingsPanelProps) { @@ -761,23 +569,55 @@ export function SettingsPanel({ /** Reload restricted details when the active credential changes. */ const loadDeployment = useCallback((signal: AbortSignal) => backend.loadDeployment(signal, controlToken), [backend, controlToken]); const [deployment] = useLoaded(open && controlToken !== null, loadDeployment); - const [setup, updateSetup] = useLoaded(open, backend.loadStationSetup); + const { loadStationSetup } = backend; + const [stationSetup, applyStationSetup] = useLoaded(open, loadStationSetup); + // The newest read of the station setup asked for after a change, and whether it is still to answer. A read is + // a picture of the backend from when it was sent, so only the newest may replace what the dialog shows. + const reloads = useRef({ latest: 0, pending: false }); + // Whether the newest of those reads failed, leaving the camera setup on screen older than the registry. + const [setupUnread, setSetupUnread] = useState(false); - // Escape closes, as for any dialog. - useEffect(() => { - if (!open) return; - /** Let Escape release the dialog from any focused control. */ - const onKey = (event: KeyboardEvent) => { - if (event.key === "Escape") onClose(); - }; - window.addEventListener("keydown", onKey); - return () => window.removeEventListener("keydown", onKey); - }, [open, onClose]); + useEscapeToClose(open, onClose); if (!open) return null; - /** Keep all tabs in sync with the persisted station setup. */ - const setOperator = (operator: OperatorSettings) => updateSetup((value) => ({ ...value, operator })); + /** Read the station setup again, and show it unless a newer read or change has been made by the time it answers. */ + const reloadStationSetup = () => { + const mine = ++reloads.current.latest; + reloads.current.pending = true; + /** Whether this read is still the newest; if so it is no longer pending. */ + const settled = () => { + if (reloads.current.latest !== mine) return false; + reloads.current.pending = false; + return true; + }; + loadStationSetup(new AbortController().signal).then( + (fresh) => { + if (!settled()) return; + applyStationSetup(() => fresh); + setSetupUnread(false); + }, + () => { + // The change itself succeeded; what could not be read is the setup that goes with it. + if (settled()) setSetupUnread(true); + }, + ); + }; + /** Apply a saved change to what the dialog shows. A read still on its way was sent before this change and + * would put the older value back, so it is replaced by a new one. */ + const updateStationSetup = (update: (value: StationSetup) => StationSetup) => { + applyStationSetup(update); + if (reloads.current.pending) reloadStationSetup(); + }; + /** Show a changed registry at once, then read the station setup again: the station in use supplies the camera + * type and roles the rest of the dialog and the page's tiles go by, so a change of it changes those. */ + const setStations = (stations: StationListing) => { + applyStationSetup((value) => ({ ...value, stations })); + reloadStationSetup(); + }; + /** Save whether calibration files are required, and show the saved value. */ + const saveRequireCalibration = (required: boolean): Promise => + controlToken === null ? Promise.resolve() : backend.saveOperator(controlToken, { require_calibration: required }).then((saved) => updateStationSetup((value) => ({ ...value, operator: saved }))); return ( <> @@ -805,10 +645,10 @@ export function SettingsPanel({
    - {setup.kind === "loaded" && setup.value.operator.warning &&

    {setup.value.operator.warning}

    } - {tab === "station" && } - {tab === "tasks" && } - {tab === "tools" && } + {stationSetup.kind === "loaded" && stationSetup.value.operator.warning &&

    {stationSetup.value.operator.warning}

    } + {tab === "station" && } + {tab === "devices" && } + {tab === "tasks" && } {tab === "display" && } {tab === "advanced" && (controlToken === null ?

    Enter the control token in the recording panel to view deployment settings.

    : )}
    diff --git a/examples/egocap/frontend/src/StationsCard.test.tsx b/examples/egocap/frontend/src/StationsCard.test.tsx new file mode 100644 index 0000000000..52cde9712e --- /dev/null +++ b/examples/egocap/frontend/src/StationsCard.test.tsx @@ -0,0 +1,559 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The Stations card: adding, selecting, editing in place and deleting stations, and what a take in progress freezes. */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { act, cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react"; +import { useState } from "react"; +import { SettingsHttpError } from "./settingsApi"; +import { STATIONS_FIXTURE, fakeStationRegistry } from "./settingsTestDoubles"; +import type { HeadsetLink } from "./setupApi"; +import { StationsCard, type StationsBackend } from "./StationsCard"; +import type { StationListing, StationRecord } from "./stationsApi"; + +afterEach(cleanup); + +const BENCH: StationRecord = { + id: "st_1", + name: "Bench A", + camera_type: "oak_d", + camera_roles: { ego: "cam_head", wrist_left: "cam_left", wrist_right: null }, + problems: [], +}; +const CART: StationRecord = { + id: "st_2", + name: "Cart B", + camera_type: null, + camera_roles: { ego: null, wrist_left: null, wrist_right: "cam_grip" }, + problems: ["no camera is assigned to the ego (head) role", "camera 'cam_grip' (right wrist) is not offered by the capture session"], +}; +const TWO_STATIONS: StationListing = { ...STATIONS_FIXTURE, stations: [BENCH, CART], selected: "st_1", label: "Bench A" }; +const HEADSET: HeadsetLink = { address: "10.0.0.42", saved: "10.0.0.42", changed: false }; +const HEADSET_MOVED: HeadsetLink = { address: "10.0.0.42", saved: "10.0.0.7", changed: true }; +const MOVED_WARNING = "This host's address changed from 10.0.0.7 to 10.0.0.42. Enter the new one in the headset."; + +interface CardOptions { + controlToken?: string | null; + backend?: Partial; + cameraSources?: string[]; + headset?: HeadsetLink | null; +} + +/** The card over an in-memory registry, re-rendered with each listing the backend answers with. */ +function renderCard(initial: StationListing = STATIONS_FIXTURE, options: CardOptions = {}) { + const registry = fakeStationRegistry(initial); + const backend: StationsBackend = { + addStation: vi.fn(registry.addStation), + updateStation: vi.fn(registry.updateStation), + deleteStation: vi.fn(registry.deleteStation), + selectStation: vi.fn(registry.selectStation), + ...options.backend, + }; + const onListing = vi.fn(); + // Lets a test deliver a listing the card did not ask for, as a reload after another browser's change does. + const outside: { deliver: (listing: StationListing) => void } = { deliver: () => undefined }; + function Harness() { + const [listing, setListing] = useState(initial); + outside.deliver = setListing; + return ( + { + onListing(next); + setListing(next); + }} + /> + ); + } + render(); + return { backend, onListing, registry, deliver: (listing: StationListing) => act(() => outside.deliver(listing)) }; +} + +const rows = () => within(screen.getByRole("list", { name: "Stations" })).getAllByRole("listitem"); +const button = (name: string) => screen.getByRole("button", { name }) as HTMLButtonElement; +const editor = (name: string) => screen.getByRole("group", { name: `Edit ${name}` }); +const field = (station: string, label: string) => within(editor(station)).getByLabelText(label) as HTMLInputElement & HTMLSelectElement; +/** Open a station's editor from its row. */ +function edit(row: number) { + fireEvent.click(within(rows()[row]).getByRole("button", { name: "Edit" })); +} + +describe("StationsCard with no stations", () => { + it("says which label recordings carry and offers only to add one", () => { + renderCard(); + expect(screen.getByText(/Recordings carry the deployment's label, “Station 01”/)).toBeTruthy(); + expect(screen.queryByRole("list", { name: "Stations" })).toBeNull(); + expect(button("Add station").disabled).toBe(true); // nothing typed yet + }); + + it("gives the first station the camera setup already saved and puts it in use", async () => { + const { backend } = renderCard(); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: " Bench A " } }); + fireEvent.click(button("Add station")); + await waitFor(() => expect(rows()).toHaveLength(2)); // the station and the "No station" choice + expect(backend.addStation).toHaveBeenCalledWith("tok", { + camera_type: "oak_d", + camera_roles: { ego: "Ego", wrist_left: null, wrist_right: null }, + name: "Bench A", + }); + expect(backend.selectStation).toHaveBeenCalledWith("tok", "st_1"); + expect((screen.getByLabelText("Use Bench A") as HTMLInputElement).checked).toBe(true); + expect(within(rows()[0]).getByText("in use")).toBeTruthy(); + expect((screen.getByLabelText("New station name") as HTMLInputElement).value).toBe(""); + }); + + it("leaves the first station unselected when it is added during a take", async () => { + const registry = fakeStationRegistry(); + const addStation = vi.fn(async (token: string, fields: { name?: string }) => ({ + ...(await registry.addStation(token, fields)), + locked_reason: "finish or discard the current take before changing the station in use", + })); + const { backend } = renderCard(STATIONS_FIXTURE, { backend: { addStation } }); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "Bench A" } }); + fireEvent.keyDown(screen.getByLabelText("New station name"), { key: "Enter" }); + await waitFor(() => expect(rows()).toHaveLength(2)); + expect(backend.selectStation).not.toHaveBeenCalled(); + expect(screen.getByText("Finish or discard the current take before changing the station in use.")).toBeTruthy(); + }); + + it("shows the first station's row and the refusal when it was added but could not be put in use", async () => { + const selectStation = vi.fn(async () => { + throw new SettingsHttpError("stations are not available yet"); + }); + const { onListing } = renderCard(STATIONS_FIXTURE, { backend: { selectStation } }); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "Bench A" } }); + fireEvent.click(button("Add station")); + expect(await screen.findByText("Not saved: stations are not available yet")).toBeTruthy(); + expect((screen.getByLabelText("Use Bench A") as HTMLInputElement).checked).toBe(false); + // The station exists, so its name is not left in the field to be added twice. + expect((screen.getByLabelText("New station name") as HTMLInputElement).value).toBe(""); + expect(onListing).toHaveBeenCalledTimes(1); + expect(onListing).toHaveBeenCalledWith(expect.objectContaining({ selected: null, stations: [expect.objectContaining({ name: "Bench A" })] })); + }); +}); + +describe("StationsCard with stations", () => { + it("lists each station with what fills its roles and why it cannot record", () => { + renderCard(TWO_STATIONS); + const [bench, cart, none] = rows(); + expect(bench.textContent).toContain("Ego (head): cam_head · Left wrist: cam_left · Right wrist: —"); + expect(within(bench).getByText("in use")).toBeTruthy(); + expect(cart.textContent).toContain("Ego (head): — · Left wrist: — · Right wrist: cam_grip"); + const problems = within(cart).getByText("Cannot record yet: no camera is assigned to the ego (head) role; camera 'cam_grip' (right wrist) is not offered by the capture session."); + expect(problems.className).toContain("tone-warning"); + expect(within(none).getByText("Recording is held until a station is in use.")).toBeTruthy(); + }); + + it("adds a later station bare and does not change the station in use", async () => { + const { backend } = renderCard(TWO_STATIONS); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "Desk C" } }); + fireEvent.click(button("Add station")); + await waitFor(() => expect(rows()).toHaveLength(4)); + expect(backend.addStation).toHaveBeenCalledWith("tok", { name: "Desk C" }); + expect(backend.selectStation).not.toHaveBeenCalled(); + }); + + it("puts another station in use, and none", async () => { + const { backend, onListing } = renderCard(TWO_STATIONS); + fireEvent.click(screen.getByLabelText("Use Cart B")); + await waitFor(() => expect((screen.getByLabelText("Use Cart B") as HTMLInputElement).checked).toBe(true)); + expect(backend.selectStation).toHaveBeenLastCalledWith("tok", "st_2"); + fireEvent.click(screen.getByLabelText("Use no station")); + await waitFor(() => expect((screen.getByLabelText("Use no station") as HTMLInputElement).checked).toBe(true)); + expect(backend.selectStation).toHaveBeenLastCalledWith("tok", null); + expect(onListing).toHaveBeenLastCalledWith(expect.objectContaining({ selected: null, label: "Station 01" })); + }); + + it("deletes a station only after the operator confirms", async () => { + const { backend } = renderCard(TWO_STATIONS); + fireEvent.click(within(rows()[1]).getByRole("button", { name: "Delete" })); + fireEvent.click(button("Keep")); + expect(backend.deleteStation).not.toHaveBeenCalled(); + fireEvent.click(within(rows()[1]).getByRole("button", { name: "Delete" })); + fireEvent.click(button("Delete Cart B")); + await waitFor(() => expect(rows()).toHaveLength(2)); + expect(backend.deleteStation).toHaveBeenCalledWith("tok", "st_2"); + }); + + it("shows the backend's reason for a refused change and keeps the list", async () => { + const addStation = vi.fn(async () => { + throw new SettingsHttpError("a station named 'Bench A' already exists"); + }); + renderCard(TWO_STATIONS, { backend: { addStation } }); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "bench a" } }); + fireEvent.click(button("Add station")); + expect(await screen.findByText("Not saved: a station named 'Bench A' already exists")).toBeTruthy(); + expect(rows()).toHaveLength(3); + }); + + it("shows why the station in use cannot change while an interrupted take waits for recovery", async () => { + const refused = async (): Promise => { + throw new SettingsHttpError("recover or discard the interrupted take first"); + }; + const { backend } = renderCard(TWO_STATIONS, { backend: { selectStation: vi.fn(refused), deleteStation: vi.fn(refused), updateStation: vi.fn(refused) } }); + const refusal = "Not saved: recover or discard the interrupted take first"; + fireEvent.click(screen.getByLabelText("Use Cart B")); + expect(await screen.findByText(refusal)).toBeTruthy(); + expect((screen.getByLabelText("Use Bench A") as HTMLInputElement).checked).toBe(true); + // Deleting the station in use is refused the same way, and the row stays. + fireEvent.click(within(rows()[0]).getByRole("button", { name: "Delete" })); + fireEvent.click(button("Delete Bench A")); + await waitFor(() => expect(backend.deleteStation).toHaveBeenCalledWith("tok", "st_1")); + expect(await screen.findByText(refusal)).toBeTruthy(); + expect(rows()).toHaveLength(3); + // A rename of it is refused in its own editor, beside what was typed. + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: "Bench Z" } }); + fireEvent.click(button("Save")); + expect(await within(editor("Bench A")).findByText(refusal)).toBeTruthy(); + expect(field("Bench A", "Name").value).toBe("Bench Z"); + }); + + it("keeps the typed name when the add is refused, so it can be corrected", async () => { + const addStation = vi.fn(async () => { + throw new SettingsHttpError("a station named 'Bench A' already exists"); + }); + renderCard(TWO_STATIONS, { backend: { addStation } }); + const name = screen.getByLabelText("New station name") as HTMLInputElement; + fireEvent.change(name, { target: { value: "bench a" } }); + fireEvent.keyDown(name, { key: "Enter" }); + await screen.findByText("Not saved: a station named 'Bench A' already exists"); + expect(name.value).toBe("bench a"); + expect(name.disabled).toBe(false); + }); + + it("moves keyboard focus to the delete confirmation, and back to Edit when the station is kept", () => { + renderCard(TWO_STATIONS); + fireEvent.click(within(rows()[1]).getByRole("button", { name: "Delete" })); + expect(document.activeElement).toBe(button("Delete Cart B")); + fireEvent.click(button("Keep")); + expect(document.activeElement).toBe(within(rows()[1]).getByRole("button", { name: "Edit" })); + }); + + it("freezes the station in use during a take and leaves the others editable", () => { + renderCard({ ...TWO_STATIONS, locked_reason: "finish or discard the current take before changing the station in use" }); + const [bench, cart] = rows(); + expect((screen.getByLabelText("Use Cart B") as HTMLInputElement).disabled).toBe(true); + expect((screen.getByLabelText("Use no station") as HTMLInputElement).disabled).toBe(true); + expect((within(bench).getByRole("button", { name: "Edit" }) as HTMLButtonElement).disabled).toBe(true); + expect((within(bench).getByRole("button", { name: "Delete" }) as HTMLButtonElement).disabled).toBe(true); + expect((within(cart).getByRole("button", { name: "Edit" }) as HTMLButtonElement).disabled).toBe(false); + expect((within(cart).getByRole("button", { name: "Delete" }) as HTMLButtonElement).disabled).toBe(false); + expect(screen.getByText("Finish or discard the current take before changing the station in use.")).toBeTruthy(); + }); + + it("changes nothing without the control token and says where to enter it", () => { + const { backend } = renderCard(TWO_STATIONS, { controlToken: null }); + expect((screen.getByLabelText("Use Cart B") as HTMLInputElement).disabled).toBe(true); + expect((screen.getByLabelText("New station name") as HTMLInputElement).disabled).toBe(true); + expect((within(rows()[1]).getByRole("button", { name: "Edit" }) as HTMLButtonElement).disabled).toBe(true); + expect((within(rows()[1]).getByRole("button", { name: "Delete" }) as HTMLButtonElement).disabled).toBe(true); + expect(screen.getByText(/Enter the control token in the recording panel/)).toBeTruthy(); + expect(backend.addStation).not.toHaveBeenCalled(); + }); + + it("shows the warning of a registry that could not be read", () => { + renderCard({ ...STATIONS_FIXTURE, warning: "Saved stations are unreadable. Adding a station replaces them." }); + expect(screen.getByText("Saved stations are unreadable. Adding a station replaces them.")).toBeTruthy(); + }); +}); + +describe("a station's inline editor", () => { + it("opens in the station's own row, one row at a time, with the station's saved values", () => { + renderCard(TWO_STATIONS); + expect(screen.queryByRole("group")).toBeNull(); + edit(0); + expect(rows()[0].contains(editor("Bench A"))).toBe(true); + expect(field("Bench A", "Name").value).toBe("Bench A"); + expect(field("Bench A", "Name").maxLength).toBe(64); + expect(document.activeElement).toBe(field("Bench A", "Name")); + expect(field("Bench A", "Camera type").value).toBe("oak_d"); + expect(Array.from(field("Bench A", "Camera type").options).map((option) => option.textContent)).toEqual([ + "Not set", + "SENSING GMSL cameras", + "OAK-D cameras — USB, read by CaptureServer", + ]); + expect(field("Bench A", "Ego (head)").value).toBe("cam_head"); + expect(field("Bench A", "Left wrist").value).toBe("cam_left"); + expect(field("Bench A", "Right wrist").value).toBe(""); + // The row's own actions give way to the editor's. + expect(within(rows()[0]).queryByRole("button", { name: "Edit" })).toBeNull(); + expect(button("Save").disabled).toBe(true); // nothing changed yet + edit(1); + expect(screen.queryByRole("group", { name: "Edit Bench A" })).toBeNull(); + expect(rows()[1].contains(editor("Cart B"))).toBe(true); + expect(field("Cart B", "Camera type").value).toBe(""); + }); + + it("offers the session's cameras and the ones already saved, and one camera to one role only", () => { + renderCard(TWO_STATIONS); + edit(1); + const right = field("Cart B", "Right wrist"); + expect(Array.from(right.options).map((option) => option.textContent)).toEqual(["Not assigned", "cam_head", "cam_left", "cam_right", "cam_grip (not in this session)"]); + expect(right.value).toBe("cam_grip"); + fireEvent.change(field("Cart B", "Ego (head)"), { target: { value: "cam_head" } }); + expect((within(right).getByRole("option", { name: "cam_head" }) as HTMLOptionElement).disabled).toBe(true); + expect((within(field("Cart B", "Left wrist")).getByRole("option", { name: "cam_head" }) as HTMLOptionElement).disabled).toBe(true); + expect((within(field("Cart B", "Ego (head)")).getByRole("option", { name: "cam_head" }) as HTMLOptionElement).disabled).toBe(false); + expect((within(field("Cart B", "Ego (head)")).getByRole("option", { name: "cam_grip (not in this session)" }) as HTMLOptionElement).disabled).toBe(true); + }); + + it("says so when the session offers no cameras to assign", () => { + renderCard({ ...TWO_STATIONS, stations: [{ ...CART, camera_roles: { ego: null, wrist_left: null, wrist_right: null } }] }, { cameraSources: [] }); + edit(0); + expect(within(editor("Cart B")).getByText(/The session offers no cameras yet/)).toBeTruthy(); + expect(button("Swap wrists").disabled).toBe(true); + }); + + it("saves name, camera type and roles in one request of only what changed, then closes", async () => { + const { backend, onListing } = renderCard(TWO_STATIONS); + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: " Bench Z " } }); + fireEvent.change(field("Bench A", "Camera type"), { target: { value: "sensing_gmsl" } }); + fireEvent.change(field("Bench A", "Right wrist"), { target: { value: "cam_right" } }); + fireEvent.click(button("Save")); + await waitFor(() => expect(screen.queryByRole("group")).toBeNull()); + expect(backend.updateStation).toHaveBeenCalledTimes(1); + expect(backend.updateStation).toHaveBeenCalledWith("tok", "st_1", { name: "Bench Z", camera_type: "sensing_gmsl", camera_roles: { wrist_right: "cam_right" } }); + expect(onListing).toHaveBeenCalledTimes(1); + expect(rows()[0].textContent).toContain("Ego (head): cam_head · Left wrist: cam_left · Right wrist: cam_right"); + expect(screen.getByLabelText("Use Bench Z")).toBeTruthy(); + }); + + it("does not send back a field another browser changed while the editor was open", async () => { + const { backend, registry, deliver } = renderCard(TWO_STATIONS); + edit(0); + // Another browser renames the station and changes its camera type; a reload brings that here. + const renamed = await registry.updateStation("tok", "st_1", { name: "Bench Prime", camera_type: "sensing_gmsl" }); + deliver(renamed); + expect(editor("Bench Prime")).toBeTruthy(); + fireEvent.change(field("Bench Prime", "Right wrist"), { target: { value: "cam_right" } }); + fireEvent.click(button("Save")); + await waitFor(() => expect(screen.queryByRole("group")).toBeNull()); + // Only the camera this editor assigned: the name and type it never touched are not sent as they were. + expect(backend.updateStation).toHaveBeenCalledWith("tok", "st_1", { camera_roles: { wrist_right: "cam_right" } }); + expect(registry.listing.stations[0]).toMatchObject({ name: "Bench Prime", camera_type: "sensing_gmsl" }); + expect(screen.getByLabelText("Use Bench Prime")).toBeTruthy(); + }); + + it("sends a single changed field alone, and can clear the camera type and a role", async () => { + const { backend } = renderCard(TWO_STATIONS); + edit(0); + fireEvent.change(field("Bench A", "Camera type"), { target: { value: "" } }); + fireEvent.click(button("Save")); + await waitFor(() => expect(screen.queryByRole("group")).toBeNull()); + expect(backend.updateStation).toHaveBeenLastCalledWith("tok", "st_1", { camera_type: null }); + edit(0); + fireEvent.change(field("Bench A", "Left wrist"), { target: { value: "" } }); + fireEvent.click(button("Save")); + await waitFor(() => expect(screen.queryByRole("group")).toBeNull()); + expect(backend.updateStation).toHaveBeenLastCalledWith("tok", "st_1", { camera_roles: { wrist_left: null } }); + }); + + it("swaps the wrists", async () => { + const { backend } = renderCard(TWO_STATIONS); + edit(0); + fireEvent.click(button("Swap wrists")); + expect(field("Bench A", "Left wrist").value).toBe(""); + expect(field("Bench A", "Right wrist").value).toBe("cam_left"); + fireEvent.click(button("Save")); + await waitFor(() => expect(screen.queryByRole("group")).toBeNull()); + expect(backend.updateStation).toHaveBeenCalledWith("tok", "st_1", { camera_roles: { wrist_left: null, wrist_right: "cam_left" } }); + }); + + it("discards the draft on Cancel", () => { + const { backend } = renderCard(TWO_STATIONS); + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: "Bench Z" } }); + fireEvent.click(button("Cancel")); + expect(screen.queryByRole("group")).toBeNull(); + expect(backend.updateStation).not.toHaveBeenCalled(); + edit(0); + expect(field("Bench A", "Name").value).toBe("Bench A"); + }); + + it("saves on Enter in the name field, and with nothing changed just closes", async () => { + const { backend } = renderCard(TWO_STATIONS); + edit(1); + fireEvent.keyDown(field("Cart B", "Name"), { key: "Enter" }); + expect(screen.queryByRole("group")).toBeNull(); + expect(backend.updateStation).not.toHaveBeenCalled(); + edit(1); + fireEvent.change(field("Cart B", "Name"), { target: { value: "Cart Z" } }); + fireEvent.keyDown(field("Cart B", "Name"), { key: "Enter" }); + await waitFor(() => expect(screen.getByLabelText("Use Cart Z")).toBeTruthy()); + expect(backend.updateStation).toHaveBeenCalledWith("tok", "st_2", { name: "Cart Z" }); + expect(screen.queryByRole("group")).toBeNull(); + }); + + it("does not save an empty name", () => { + const { backend } = renderCard(TWO_STATIONS); + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: " " } }); + expect(button("Save").disabled).toBe(true); + fireEvent.keyDown(field("Bench A", "Name"), { key: "Enter" }); + expect(backend.updateStation).not.toHaveBeenCalled(); + expect(editor("Bench A")).toBeTruthy(); + }); + + it("closes on Escape without letting the dialog see the key", () => { + const { backend } = renderCard(TWO_STATIONS); + const dialogSawKey = vi.fn(); + window.addEventListener("keydown", dialogSawKey); + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: "Bench Z" } }); + fireEvent.keyDown(field("Bench A", "Name"), { key: "Escape" }); + expect(screen.queryByRole("group")).toBeNull(); + edit(0); + fireEvent.keyDown(field("Bench A", "Left wrist"), { key: "Escape" }); + expect(screen.queryByRole("group")).toBeNull(); + window.removeEventListener("keydown", dialogSawKey); + expect(dialogSawKey).not.toHaveBeenCalled(); + expect(backend.updateStation).not.toHaveBeenCalled(); + }); + + it("returns keyboard focus to the row's Edit button when the editor closes by Cancel, Escape or a save", async () => { + renderCard(TWO_STATIONS); + const editOf = (row: number) => within(rows()[row]).getByRole("button", { name: "Edit" }); + edit(0); + fireEvent.click(button("Cancel")); + expect(document.activeElement).toBe(editOf(0)); + edit(0); + fireEvent.keyDown(field("Bench A", "Name"), { key: "Escape" }); + expect(document.activeElement).toBe(editOf(0)); + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: "Bench Z" } }); + fireEvent.click(button("Save")); + await waitFor(() => expect(screen.queryByRole("group")).toBeNull()); + expect(document.activeElement).toBe(editOf(0)); + }); + + it("leaves focus in the editor just opened when it replaces another row's", () => { + renderCard(TWO_STATIONS); + edit(0); + edit(1); + expect(document.activeElement).toBe(field("Cart B", "Name")); + }); + + it("shows a refusal in the row and keeps the editor open with what was typed", async () => { + const updateStation = vi.fn(async () => { + throw new SettingsHttpError("a station named 'Cart B' already exists"); + }); + const { onListing } = renderCard(TWO_STATIONS, { backend: { updateStation } }); + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: "cart b" } }); + fireEvent.change(field("Bench A", "Right wrist"), { target: { value: "cam_right" } }); + fireEvent.click(button("Save")); + expect(await within(rows()[0]).findByText("Not saved: a station named 'Cart B' already exists")).toBeTruthy(); + expect(field("Bench A", "Name").value).toBe("cart b"); + expect(field("Bench A", "Right wrist").value).toBe("cam_right"); + expect(button("Save").disabled).toBe(false); + expect(onListing).not.toHaveBeenCalled(); + }); + + it("holds every other registry control while a save is on its way, and leaves the editor able to hold focus", async () => { + const registry = fakeStationRegistry(TWO_STATIONS); + let finish: () => void = () => undefined; + const updateStation = vi.fn(async (...args: Parameters) => { + await new Promise((resolve) => (finish = resolve)); + return registry.updateStation(...args); + }); + const { backend } = renderCard(TWO_STATIONS, { backend: { updateStation } }); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "Bench C" } }); + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: "Bench Z" } }); + fireEvent.keyDown(field("Bench A", "Name"), { key: "Enter" }); + expect(button("Saving…")).toBeTruthy(); + // Each answer is a whole listing and the last one wins, so nothing else may change the registry meanwhile. + const others = [screen.getByLabelText("Use Bench A"), screen.getByLabelText("Use Cart B"), screen.getByLabelText("Use no station"), button("Add station"), ...within(rows()[1]).getAllByRole("button")] as HTMLInputElement[]; + expect(others.map((control) => control.disabled)).toEqual([true, true, true, true, true, true]); + // A disabled control gives up keyboard focus, and Escape would then close the dialog, not the editor. + const name = field("Bench A", "Name"); + expect([name.disabled, name.readOnly, button("Saving…").disabled]).toEqual([false, true, false]); + fireEvent.keyDown(name, { key: "Enter" }); + fireEvent.click(button("Saving…")); + expect(backend.updateStation).toHaveBeenCalledTimes(1); + await act(async () => finish()); + await waitFor(() => expect(screen.queryByRole("group")).toBeNull()); + expect(within(rows()[0]).getByText("Bench Z")).toBeTruthy(); + expect(others.map((control) => control.disabled)).toEqual([false, false, false, false, false, false]); + }); + + it("releases the other registry controls after a refused save", async () => { + const updateStation = vi.fn(async () => { + throw new SettingsHttpError("a station named 'Cart B' already exists"); + }); + renderCard(TWO_STATIONS, { backend: { updateStation } }); + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: "cart b" } }); + fireEvent.click(button("Save")); + await within(rows()[0]).findByText("Not saved: a station named 'Cart B' already exists"); + expect((screen.getByLabelText("Use Cart B") as HTMLInputElement).disabled).toBe(false); + expect(field("Bench A", "Name").readOnly).toBe(false); + }); + + it("cannot save the station in use once a take starts, while its typed values stay", () => { + const registry = fakeStationRegistry(TWO_STATIONS); + const backend: StationsBackend = { addStation: vi.fn(), updateStation: vi.fn(registry.updateStation), deleteStation: vi.fn(), selectStation: vi.fn() }; + const props = { controlToken: "tok", backend, inherited: {}, cameraSources: ["cam_head"], headset: null, onListing: vi.fn() }; + const { rerender } = render(); + edit(0); + fireEvent.change(field("Bench A", "Name"), { target: { value: "Bench Z" } }); + rerender(); + expect(field("Bench A", "Name").value).toBe("Bench Z"); + expect(button("Save").disabled).toBe(true); + fireEvent.keyDown(field("Bench A", "Name"), { key: "Enter" }); + expect(backend.updateStation).not.toHaveBeenCalled(); + }); +}); + +describe("the headset address in the Stations card", () => { + it("is the last line of the editor of the station in use, and of no other station", () => { + renderCard(TWO_STATIONS, { headset: HEADSET }); + expect(screen.queryByText(/Headset connects to/)).toBeNull(); // only the editor shows it + edit(0); + expect(editor("Bench A").lastElementChild?.textContent).toBe("Headset connects to 10.0.0.42"); + expect(screen.queryByText(/This host's address changed/)).toBeNull(); + edit(1); + expect(screen.queryByText(/Headset connects to/)).toBeNull(); + }); + + it("warns under the station in use that the headset needs the new address, and beside the address while editing", () => { + renderCard(TWO_STATIONS, { headset: HEADSET_MOVED }); + const [bench, cart] = rows(); + const closed = within(bench).getByText(MOVED_WARNING); + expect(closed.className).toContain("tone-warning"); + expect(within(cart).queryByText(MOVED_WARNING)).toBeNull(); + edit(0); + const lines = Array.from(editor("Bench A").children).slice(-2); + expect(lines.map((line) => line.textContent)).toEqual(["Headset connects to 10.0.0.42", MOVED_WARNING]); + expect(lines[1].className).toContain("tone-warning"); + expect(screen.getAllByText(MOVED_WARNING)).toHaveLength(1); // said once, not in the row and the editor both + fireEvent.click(button("Cancel")); + expect(within(rows()[0]).getByText(MOVED_WARNING)).toBeTruthy(); + }); + + it("says nothing while the address is not known", () => { + renderCard(TWO_STATIONS, { headset: { address: null, saved: "10.0.0.7", changed: true } }); + edit(0); + expect(screen.queryByText(/Headset connects to/)).toBeNull(); + expect(screen.queryByText(/This host's address changed/)).toBeNull(); + cleanup(); + renderCard(TWO_STATIONS, { headset: null }); + edit(0); + expect(screen.queryByText(/Headset connects to/)).toBeNull(); + }); + + it("belongs to no row while no station is in use", () => { + renderCard({ ...TWO_STATIONS, selected: null }, { headset: HEADSET_MOVED }); + expect(screen.queryByText(MOVED_WARNING)).toBeNull(); + edit(0); + expect(screen.queryByText(/Headset connects to/)).toBeNull(); + }); +}); diff --git a/examples/egocap/frontend/src/StationsCard.tsx b/examples/egocap/frontend/src/StationsCard.tsx new file mode 100644 index 0000000000..9cea05b004 --- /dev/null +++ b/examples/egocap/frontend/src/StationsCard.tsx @@ -0,0 +1,534 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The Stations card of the Settings dialog: the stations this site records at, the one in use, and each + * station's name, camera type and cameras, edited in place. + * + * The station in use names every recording and its activity log. It cannot change while a take is being + * recorded; the backend says so in `locked_reason` and refuses the change either way. A station that is not in + * use can always be added, edited or deleted. + */ +import { useEffect, useId, useRef, useState } from "react"; +import { Card, TokenHint, useAction } from "./settingsParts"; +import { CAMERA_TYPE_LABELS, ROLE_LABELS } from "./settingsApi"; +import { sentence } from "./sentence"; +import type { HeadsetLink } from "./setupApi"; +import type { StationChange, StationListing, StationRecord } from "./stationsApi"; + +/** The registry calls the card makes; the dialog passes the real ones and tests pass fakes. */ +export interface StationsBackend { + /** Adds a station and answers with the registry as it then stands, as every call here does. */ + addStation: (controlToken: string, fields: StationChange) => Promise; + /** Changes a station's name or cameras. */ + updateStation: (controlToken: string, id: string, changes: StationChange) => Promise; + /** Removes a station; the one in use leaves no station in use. */ + deleteStation: (controlToken: string, id: string) => Promise; + /** Puts a station in use, or none with a null id. */ + selectStation: (controlToken: string, id: string | null) => Promise; +} + +/** The longest name the backend accepts, so the field stops where a save would be refused. */ +const MAX_NAME_CHARS = 64; + +/** Which camera fills each role, in one line, so two stations with different cameras can be told apart at a glance. */ +function roleSummary(station: StationRecord, roles: readonly string[]): string { + return roles.map((role) => `${ROLE_LABELS[role] ?? role}: ${station.camera_roles[role] ?? "—"}`).join(" · "); +} + +/** What to tell the operator when the headset still holds an address this host no longer has; null otherwise. */ +function headsetWarning(headset: HeadsetLink | null): string | null { + if (headset === null || !headset.changed || headset.address === null || headset.saved === null) return null; + return `This host's address changed from ${headset.saved} to ${headset.address}. Enter the new one in the headset.`; +} + +export interface StationsCardProps { + listing: StationListing; + controlToken: string | null; + backend: StationsBackend; + /** The camera setup saved before any station existed; the first station added takes it over. */ + inherited: StationChange; + /** Whether changes are held by something outside the card, such as a camera setup save the first station would inherit. */ + held?: boolean; + /** The cameras the current session offers, by name. */ + cameraSources: string[]; + /** Where the headset of the station in use connects, from the start-of-day flow; null while that is not known. */ + headset: HeadsetLink | null; + /** Called with the backend's listing after every successful change. */ + onListing: (listing: StationListing) => void; +} + +/** List the stations, choose the one in use, and add, edit or delete them. */ +export function StationsCard({ listing, controlToken, backend, inherited, held = false, cameraSources, headset, onListing }: StationsCardProps) { + const [{ busy, failure }, run] = useAction(); + // At most one editor is open, so a draft is never left behind in a row the operator has moved on from. + const [editing, setEditing] = useState(null); + // An editor's save reports to its own row, so it is tracked apart from the card's other changes. + const [saving, setSaving] = useState(false); + const locked = listing.locked_reason !== null; + const idle = controlToken !== null && !busy; + // Every change answers with a whole listing and the last answer wins, so only one may be in flight. + const canChange = idle && !saving && !held; + /** Run one registry change with the token and hand its listing to the dialog; resolves once it has ended either way. */ + const change = (work: (token: string) => Promise): Promise => { + if (controlToken === null) return Promise.resolve(); + const outcome = work(controlToken).then(onListing); + run(() => outcome); + // The card shows a refusal itself, so a caller waiting for the end is not handed it again. + return outcome.catch(() => undefined); + }; + /** Add a station; the first one takes over the camera setup already saved and is put in use. Resolves to whether it now exists. */ + const add = (name: string): Promise => { + let exists = false; + return change(async (token) => { + const first = listing.stations.length === 0; + const added = await backend.addStation(token, first ? { ...inherited, name } : { name }); + // From here the station is in the registry, whatever becomes of putting it in use. + exists = true; + // During a take the station in use cannot change, so the new station is left for the operator to select. + if (!first || added.locked_reason !== null) return added; + try { + return await backend.selectStation(token, added.stations[added.stations.length - 1].id); + } catch (error) { + // The station exists even though it could not be put in use: show its row, then the refusal. + onListing(added); + throw error; + } + }).then(() => exists); + }; + /** Save one editor's changes. A refusal is the editor's to show, beside what was typed. */ + const save = (id: string, changes: StationChange): Promise => { + if (controlToken === null) return Promise.reject(new Error("enter the control token first")); + setSaving(true); + return backend + .updateStation(controlToken, id, changes) + .then(onListing) + .finally(() => setSaving(false)); + }; + + return ( + + {listing.warning !== undefined &&

    {listing.warning}

    } + {listing.stations.length === 0 ? ( +

    + No stations yet. Recordings carry the deployment's label, “{listing.label}”. Add a station to choose between stations here. +

    + ) : ( +
      + {listing.stations.map((station) => { + const inUse = listing.selected === station.id; + return ( + change((token) => backend.selectStation(token, station.id))} + onEdit={() => setEditing(station.id)} + // A save that answers after another row's editor was opened must not close that one. + onCloseEditor={() => setEditing((current) => (current === station.id ? null : current))} + onSave={(changes) => save(station.id, changes)} + onDelete={() => change((token) => backend.deleteStation(token, station.id))} + /> + ); + })} +
    • + +
    • +
    + )} + + {locked &&

    {sentence(listing.locked_reason ?? "")}.

    } + {failure !== null &&

    Not saved: {failure}

    } + +
    + ); +} + +/** One station: the radio that puts it in use, what fills its roles, why it cannot record, and its actions. */ +function StationRow({ + station, + listing, + inUse, + canChange, + canSave, + editing, + cameraSources, + headset, + onSelect, + onEdit, + onCloseEditor, + onSave, + onDelete, +}: { + station: StationRecord; + listing: StationListing; + inUse: boolean; + /** Whether the registry can be changed from this row now: nothing else is in flight. */ + canChange: boolean; + /** Whether the row's open editor can save: as `canChange`, but not held by that editor's own save. */ + canSave: boolean; + editing: boolean; + cameraSources: string[]; + headset: HeadsetLink | null; + onSelect: () => void; + onEdit: () => void; + onCloseEditor: () => void; + onSave: (changes: StationChange) => Promise; + onDelete: () => void; +}) { + const [confirmingDelete, setConfirmingDelete] = useState(false); + const locked = listing.locked_reason !== null; + // The station in use is frozen during a take; every other station stays editable. + const frozen = inUse && locked; + const editable = canChange && !frozen; + const warning = headsetWarning(headset); + // The row's actions give way to the editor or the delete confirmation and come back as new elements. When + // that leaves keyboard focus on nothing, it returns to Edit; focus that already moved elsewhere is left alone. + const editButton = useRef(null); + const replaced = editing || confirmingDelete; + const wasReplaced = useRef(false); + useEffect(() => { + if (wasReplaced.current && !replaced && document.activeElement === document.body) editButton.current?.focus(); + wasReplaced.current = replaced; + }, [replaced]); + return ( +
  • +
    + + {roleSummary(station, listing.roles)} + {station.problems.length > 0 && Cannot record yet: {station.problems.join("; ")}.} + {/* The open editor says the same beside the address, so it is not repeated here. */} + {warning !== null && !editing && {warning}} +
    + {!editing && !confirmingDelete && ( + <> + + + + )} + {!editing && confirmingDelete && ( + <> + + + + )} + {editing && ( + + )} +
  • + ); +} + +/** A camera setup as saved: the camera type and the camera filling each role. */ +export type CameraSetup = Pick; + +/** An editor's working copy of a camera setup. */ +export interface CameraDraft { + cameraType: string | null; + cameraRoles: Record; +} + +/** The editor's working copy of a station. */ +interface StationDraft extends CameraDraft { + name: string; +} + +/** A working copy of a saved camera setup. */ +export function cameraDraftOf(saved: CameraSetup): CameraDraft { + return { cameraType: saved.camera_type, cameraRoles: { ...saved.camera_roles } }; +} + +/** Only the camera fields the draft changes from `original`, the setup the editor was opened on. */ +export function cameraChangesOf(original: CameraSetup, roles: readonly string[], draft: CameraDraft): Pick { + const changes: Pick = {}; + if (draft.cameraType !== original.camera_type) changes.camera_type = draft.cameraType; + const moved = roles.filter((role) => (draft.cameraRoles[role] ?? null) !== (original.camera_roles[role] ?? null)); + if (moved.length > 0) changes.camera_roles = Object.fromEntries(moved.map((role) => [role, draft.cameraRoles[role] ?? null])); + return changes; +} + +/** Only what the draft changes from `original`, the station as it was when the editor opened. Comparing with + * the station as it is now would send back, as a change, every field another browser changed in the meantime. */ +function changesOf(original: StationRecord, roles: readonly string[], draft: StationDraft): StationChange { + const changes: StationChange = cameraChangesOf(original, roles, draft); + if (draft.name.trim() !== original.name) changes.name = draft.name.trim(); + return changes; +} + +/** Whether a draft has a wrist camera to swap. */ +export function hasWristCamera(draft: CameraDraft): boolean { + return (draft.cameraRoles.wrist_left ?? null) !== null || (draft.cameraRoles.wrist_right ?? null) !== null; +} + +/** The draft with its wrists exchanged, in one step so the assignments stay unique throughout. */ +export function withWristsSwapped(draft: T): T { + return { ...draft, cameraRoles: { ...draft.cameraRoles, wrist_left: draft.cameraRoles.wrist_right ?? null, wrist_right: draft.cameraRoles.wrist_left ?? null } }; +} + +/** The camera type and the camera for each role, as label and control pairs for a `settings-fields` grid. */ +export function CameraFields({ + idPrefix, + draft, + onDraft, + saved, + roles, + cameraTypes, + cameraSources, + disabled, +}: { + /** Makes the field ids unique on the page. */ + idPrefix: string; + draft: T; + onDraft: (update: (current: T) => T) => void; + /** The roles as saved: a saved camera stays selectable when the session no longer offers it, so it can be seen and cleared. */ + saved: Record; + roles: readonly string[]; + cameraTypes: readonly string[]; + /** The cameras the current session offers, by name. */ + cameraSources: string[]; + disabled: boolean; +}) { + const cameras = selectableCameras(cameraSources, saved); + /** The cameras the other roles hold: one camera cannot fill two roles. */ + const takenBy = (role: string) => new Set(roles.filter((other) => other !== role).map((other) => draft.cameraRoles[other])); + return ( + <> + + + {roles.map((role) => ( + onDraft((current) => ({ ...current, cameraRoles: { ...current.cameraRoles, [role]: camera } }))} + /> + ))} + + ); +} + +/** Every camera a role can be given: the ones the session offers and the ones already saved. */ +export function selectableCameras(cameraSources: readonly string[], saved: Record): string[] { + return [...new Set([...cameraSources, ...Object.values(saved).filter((name): name is string => name !== null)])]; +} + +/** What to say where no camera can be chosen yet. */ +export const NO_CAMERAS_NOTE = "The session offers no cameras yet; roles can be assigned once CaptureServer lists them."; + +/** A station's inline editor: its name, camera type and the camera for each role, saved together. */ +function StationEditor({ + station, + listing, + cameraSources, + headset, + canSave, + onSave, + onClose, +}: { + station: StationRecord; + listing: StationListing; + cameraSources: string[]; + /** Where this station's headset connects; null for a station that is not in use. */ + headset: HeadsetLink | null; + canSave: boolean; + onSave: (changes: StationChange) => Promise; + onClose: () => void; +}) { + const fieldId = useId(); + // The station as the editor opened on it. The listing can bring another browser's change while the editor is + // open; what this editor changed is judged against what the operator started from, never against that. + const [original] = useState(station); + const [draft, setDraft] = useState({ name: station.name, ...cameraDraftOf(station) }); + const [{ busy, failure }, run] = useAction(); + const { roles } = listing; + const changes = changesOf(original, roles, draft); + const dirty = Object.keys(changes).length > 0; + const named = draft.name.trim() !== ""; + /** Send what changed and close on success; with nothing changed there is nothing to send. */ + const save = () => { + if (!named || busy) return; + if (!dirty) onClose(); + else if (canSave) run(() => onSave(changes).then(onClose)); + }; + const warning = headsetWarning(headset); + return ( +
    { + // Escape belongs to the dialog, which closes on it; here it only closes the editor. + if (e.key === "Escape") { + e.stopPropagation(); + onClose(); + } + }} + > +
    + + setDraft((current) => ({ ...current, name: e.target.value }))} + onKeyDown={(e) => { + if (e.key === "Enter") save(); + }} + /> + +
    + {selectableCameras(cameraSources, station.camera_roles).length === 0 &&

    {NO_CAMERAS_NOTE}

    } +
    + {/* Not disabled while saving, for the same reason as the name field; `save` ignores a second press. */} + + + + {failure !== null && Not saved: {failure}} +
    + {headset !== null && headset.address !== null &&

    Headset connects to {headset.address}

    } + {warning !== null &&

    {warning}

    } +
    + ); +} + +/** The label and select of one camera role. */ +function RoleField({ + id, + role, + value, + cameras, + offered, + taken, + disabled, + onChange, +}: { + id: string; + role: string; + value: string | null; + /** Every camera that can be chosen. */ + cameras: string[]; + /** The ones the session offers right now; the rest are marked. */ + offered: string[]; + /** The cameras the other roles hold. */ + taken: Set; + disabled: boolean; + onChange: (camera: string | null) => void; +}) { + return ( + <> + + + + ); +} + +/** The name field and button that add a station. */ +function AddStation({ canChange, onAdd }: { canChange: boolean; onAdd: (name: string) => Promise }) { + const [name, setName] = useState(""); + const ready = canChange && name.trim() !== ""; + /** Add the typed name and clear the field for the next one; a refused name stays to be corrected. */ + const submit = () => { + if (!ready) return; + onAdd(name.trim()).then((added) => { + if (added) setName(""); + }); + }; + return ( +
    + setName(e.target.value)} + onKeyDown={(e) => { + if (e.key === "Enter") submit(); + }} + /> + +
    + ); +} diff --git a/examples/egocap/frontend/src/StepRail.test.tsx b/examples/egocap/frontend/src/StepRail.test.tsx new file mode 100644 index 0000000000..4dceaca47a --- /dev/null +++ b/examples/egocap/frontend/src/StepRail.test.tsx @@ -0,0 +1,92 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The start-of-day rail: how each step's state reads, which step is current, and what a step opens. */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { cleanup, fireEvent, render, screen } from "@testing-library/react"; +import type { SetupStep } from "./setupApi"; +import { SETUP_HELD, SETUP_READY } from "./setupTestDoubles"; +import { StepRail, currentStep } from "./StepRail"; + +afterEach(cleanup); + +const step = (name: RegExp) => screen.getByRole("button", { name }); +const items = () => screen.getAllByRole("listitem"); + +describe("currentStep", () => { + it("is the first step that is neither done nor skipped", () => { + expect(currentStep(SETUP_HELD.steps)).toBe("devices"); + expect(currentStep(SETUP_READY.steps)).toBe("record"); + const allDone: SetupStep[] = SETUP_READY.steps.map((s): SetupStep => ({ ...s, status: s.id === "devices" ? "skipped" : "done" })); + expect(currentStep(allDone)).toBeNull(); + }); +}); + +describe("StepRail", () => { + it("renders nothing while the flow could not be read", () => { + const { container } = render(); + expect(container.firstChild).toBeNull(); + cleanup(); + expect(render().container.firstChild).toBeNull(); + }); + + it("shows the four steps, which are done and which remain, and marks the one to deal with next", () => { + render(); + expect(screen.getByRole("navigation", { name: "Start-of-day steps" })).toBeTruthy(); + expect(items().map((item) => item.textContent)).toEqual([ + "✓StationBench A", + "!DevicesLeft wrist: cam_left: no recent frame", + "3Record: to do", + "4Wrap up", + ]); + expect(step(/Step 1, Station: done\. Bench A/).getAttribute("aria-current")).toBeNull(); + const devices = step(/Step 2, Devices: needs attention\. Left wrist: cam_left: no recent frame/); + expect(devices.title).toBe("Left wrist: cam_left: no recent frame"); + expect(devices.getAttribute("aria-current")).toBe("step"); + expect(devices.className).toContain("step--current"); + expect(step(/Step 4, Wrap up: to do$/).getAttribute("aria-current")).toBeNull(); + }); + + it("marks a step that does not apply to this station", () => { + const steps: SetupStep[] = [ + { id: "station", label: "Station", status: "done", detail: "Bench A" }, + { id: "devices", label: "Devices", status: "skipped", detail: "no station is in use" }, + ]; + render(); + const devices = step(/Step 2, Devices: not needed\. No station is in use/); + expect(devices.textContent).toBe("–DevicesNo station is in use"); + expect(devices.className).toContain("step--skipped"); + }); + + it("shows Record as a plain item with the same look, not a control", () => { + const onOpen = vi.fn(); + render(); + expect(screen.queryByRole("button", { name: /Record/ })).toBeNull(); + expect(screen.getAllByRole("button")).toHaveLength(3); + const record = items()[2].firstElementChild as HTMLElement; + expect(record.tagName).toBe("SPAN"); + expect(record.tabIndex).toBe(-1); + expect(record.className).toBe("step step--todo step--current step--static"); + // It is still the step the operator is on, and says so to a screen reader. + expect(record.getAttribute("aria-current")).toBe("step"); + expect(record.textContent).toBe("3Record: to do"); + fireEvent.click(record); + expect(onOpen).not.toHaveBeenCalled(); + }); + + it("carries the Record step's reason when it has one", () => { + const steps = SETUP_READY.steps.map((s): SetupStep => (s.id === "record" ? { ...s, status: "attention", detail: "set a task to enable Record" } : s)); + render(); + const record = items()[2].firstElementChild as HTMLElement; + expect(record.textContent).toBe("!Record: needs attentionSet a task to enable Record"); + expect(record.title).toBe("Set a task to enable Record"); + }); + + it("opens the place each of the other steps is dealt with", () => { + const onOpen = vi.fn(); + render(); + for (const name of [/Station/, /Devices/, /Wrap up/]) fireEvent.click(step(name)); + expect(onOpen.mock.calls.map(([id]) => id)).toEqual(["station", "devices", "wrap_up"]); + }); +}); diff --git a/examples/egocap/frontend/src/StepRail.tsx b/examples/egocap/frontend/src/StepRail.tsx new file mode 100644 index 0000000000..4a8b86a1e4 --- /dev/null +++ b/examples/egocap/frontend/src/StepRail.tsx @@ -0,0 +1,100 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The start-of-day progress rail under the header: station, devices, record, wrap-up. + * + * Each step shows whether it is done, needs attention, is still to do or does not apply to this station, with a + * short reason. The first step that is neither done nor skipped is the current one. Station, Devices and Wrap up + * open the place where they are dealt with; the page decides what that is. Record opens nothing, because + * recording is the page itself. The rail only reports what the backend said: it never marks a step done itself. + */ +import { sentence } from "./sentence"; +import type { SetupStep, StepId, StepStatus } from "./setupApi"; + +/** The steps that open something. */ +export type OpenableStep = Exclude; + +/** The mark inside a step's circle: its number until something more specific can be said. */ +function mark(status: StepStatus, position: number): string { + if (status === "done") return "✓"; + if (status === "attention") return "!"; + if (status === "skipped") return "–"; + return String(position); +} + +/** How a step's state is announced, since the mark alone is not text. */ +const STATUS_WORDS: Record = { + done: "done", + todo: "to do", + attention: "needs attention", + skipped: "not needed", +}; + +/** The step the operator should deal with next: the first that is neither done nor skipped; null when none is left. */ +export function currentStep(steps: readonly SetupStep[]): StepId | null { + return steps.find((step) => step.status === "todo" || step.status === "attention")?.id ?? null; +} + +export interface StepRailProps { + /** The flow's steps in order, or null while they could not be read (the rail then renders nothing). */ + steps: readonly SetupStep[] | null; + /** Open the place a step is dealt with. */ + onOpen: (step: OpenableStep) => void; +} + +/** Show the flow's steps in order and let each one that is dealt with elsewhere open that place. */ +export function StepRail({ steps, onOpen }: StepRailProps) { + if (steps === null || steps.length === 0) return null; + const current = currentStep(steps); + return ( + + ); +} diff --git a/examples/egocap/frontend/src/UptimeChip.test.tsx b/examples/egocap/frontend/src/UptimeChip.test.tsx new file mode 100644 index 0000000000..f05d643398 --- /dev/null +++ b/examples/egocap/frontend/src/UptimeChip.test.tsx @@ -0,0 +1,209 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The uptime chip: what it shows in each state, how it counts between loads, and when it reads again. */ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { act, cleanup, render, screen } from "@testing-library/react"; +import { UPTIME_FIXTURE } from "./dayReportTestDoubles"; +import type { StationUptime } from "./stationsApi"; +import { dayHasTake, formatActivity, formatTotal } from "./stationTime"; +import { UPTIME_REFRESH_MS, UptimeChip, downSeconds } from "./UptimeChip"; + +beforeEach(() => vi.useFakeTimers()); +afterEach(() => { + cleanup(); + vi.useRealTimers(); +}); + +/** Before the first take of the day: nothing counted, nothing blocking. */ +const READY: StationUptime = { ...UPTIME_FIXTURE, state: "ready", reason: null, active_seconds: 0, down_seconds: 0, blockers: [] }; +const RECORDING: StationUptime = { ...UPTIME_FIXTURE, state: "recording", reason: null, blockers: UPTIME_FIXTURE.blockers.slice(0, 1) }; + +/** Let the pending load settle, then advance the fake clock. */ +async function settle(ms = 0) { + await act(async () => { + await vi.advanceTimersByTimeAsync(ms); + }); +} + +/** The chip over a backend whose answer a test can swap between loads. */ +async function renderChip(first: StationUptime | Error, stationLabel: string | null = "Bench A") { + const state = { answer: first }; + const load = vi.fn(async () => { + if (state.answer instanceof Error) throw state.answer; + return state.answer; + }); + const utils = render(); + await settle(); + return { state, load, rerender: (label: string | null) => utils.rerender() }; +} + +const chip = () => screen.getByRole("img"); +const summary = () => document.querySelector(".station-uptime-summary"); + +describe("formatActivity, formatTotal, dayHasTake and downSeconds", () => { + it("shows a duration in minutes and seconds, then hours and minutes", () => { + expect(formatActivity(0)).toBe("0m 00s"); + expect(formatActivity(125.9)).toBe("2m 05s"); + expect(formatActivity(7_500)).toBe("2h 05m"); + expect(formatActivity(-5)).toBe("0m 00s"); + }); + + it("shows a day's total to the minute", () => { + expect(formatTotal(0)).toBe("0m"); + expect(formatTotal(59.9)).toBe("<1m"); + expect(formatTotal(720)).toBe("12m"); + expect(formatTotal(3_599)).toBe("59m"); + expect(formatTotal(7_500)).toBe("2h 05m"); + expect(formatTotal(-5)).toBe("0m"); + }); + + it("knows the day has a take once anything was counted", () => { + expect(dayHasTake(READY)).toBe(false); + expect(dayHasTake({ ...READY, active_seconds: 4 })).toBe(true); + expect(dayHasTake({ ...READY, down_seconds: 4 })).toBe(true); + expect(dayHasTake({ ...READY, blockers: UPTIME_FIXTURE.blockers })).toBe(true); + }); + + it("counts a down time from the backend's own figures plus the time since they arrived", () => { + expect(downSeconds(UPTIME_FIXTURE, 0)).toBe(300); + expect(downSeconds(UPTIME_FIXTURE, 60)).toBe(360); + expect(downSeconds(UPTIME_FIXTURE, -3)).toBe(300); + expect(downSeconds(READY, 60)).toBeNull(); + expect(downSeconds({ ...UPTIME_FIXTURE, since: null }, 60)).toBeNull(); + }); +}); + +describe("UptimeChip", () => { + it("says Ready in a positive tone, with no totals before the day's first take", async () => { + await renderChip(READY); + expect(chip().textContent).toBe("Ready"); + expect(chip().className).toBe("uptime-chip uptime-chip--ready"); + expect(chip().getAttribute("aria-label")).toBe("Station ready"); + expect(chip().hasAttribute("title")).toBe(false); + expect(summary()).toBeNull(); + }); + + it("says Recording in the accent tone, with the day's active and down time and its blockers", async () => { + await renderChip(RECORDING); + expect(chip().textContent).toBe("Recording"); + expect(chip().className).toBe("uptime-chip uptime-chip--recording"); + expect(chip().getAttribute("aria-label")).toBe("Station recording"); + expect(summary()?.textContent).toBe("active 2h 05m · down 17m · 1 blocker"); + }); + + it("says Down for how long in a warning tone, with the reason as its title and in its name", async () => { + await renderChip(UPTIME_FIXTURE); + expect(chip().textContent).toBe("Down · 5m 00s"); + expect(chip().className).toBe("uptime-chip uptime-chip--down"); + expect(chip().title).toBe("Left wrist: cam_left: no recent frame"); + expect(chip().getAttribute("aria-label")).toBe("Station down for 5m 00s: Left wrist: cam_left: no recent frame"); + expect(summary()?.textContent).toBe("active 2h 05m · down 17m · 2 blockers"); + }); + + it("leaves out the blockers when there are none", async () => { + await renderChip({ ...RECORDING, blockers: [] }); + expect(summary()?.textContent).toBe("active 2h 05m · down 17m"); + }); + + it("keeps the down time counting between loads", async () => { + await renderChip({ ...UPTIME_FIXTURE, since: UPTIME_FIXTURE.as_of - 59 }); + expect(chip().textContent).toBe("Down · 0m 59s"); + await settle(2_000); + expect(chip().textContent).toBe("Down · 1m 01s"); + expect(chip().getAttribute("aria-label")).toBe("Station down for 1m 01s: Left wrist: cam_left: no recent frame"); + }); + + it("is not a control: nothing in the strip can be pressed", async () => { + await renderChip(UPTIME_FIXTURE); + expect(screen.queryByRole("button")).toBeNull(); + expect(chip().tabIndex).toBe(-1); + }); + + it("reads again every fifteen seconds and when the station in use changes", async () => { + const { state, load, rerender } = await renderChip(READY); + expect(UPTIME_REFRESH_MS).toBe(15_000); + expect(load).toHaveBeenCalledTimes(1); + state.answer = UPTIME_FIXTURE; + await settle(14_999); + expect(load).toHaveBeenCalledTimes(1); + await settle(1); + expect(load).toHaveBeenCalledTimes(2); + expect(chip().textContent).toBe("Down · 5m 00s"); + state.answer = RECORDING; + rerender("Cart B"); + await settle(); + expect(load).toHaveBeenCalledTimes(3); + expect(chip().textContent).toBe("Recording"); + }); + + it("reads again at once when its refresh key changes, without waiting for the timer", async () => { + const state = { answer: READY }; + const load = vi.fn(async () => state.answer); + const { rerender } = render(); + await settle(); + expect(chip().textContent).toBe("Ready"); + state.answer = RECORDING; + rerender(); + await settle(); + expect(load).toHaveBeenCalledTimes(2); + expect(chip().textContent).toBe("Recording"); + // The same key is no reason to read. + rerender(); + await settle(); + expect(load).toHaveBeenCalledTimes(2); + }); + + it("shows the station now in use, not an answer for the last one that arrives late", async () => { + const pending: Array<(uptime: StationUptime) => void> = []; + const load = vi.fn(() => new Promise((resolve) => pending.push(resolve))); + const { rerender, unmount } = render(); + rerender(); + expect(pending).toHaveLength(2); + pending[1](RECORDING); + await settle(); + pending[0](UPTIME_FIXTURE); // Bench A's read answers late + await settle(); + expect(chip().textContent).toBe("Recording"); + unmount(); + }); + + it("shows nothing of the last station while the new station's uptime is still on its way", async () => { + const pending: Array<(uptime: StationUptime) => void> = []; + const load = vi.fn(() => new Promise((resolve) => pending.push(resolve))); + const { rerender } = render(); + pending[0](UPTIME_FIXTURE); + await settle(); + expect(chip().textContent).toBe("Down · 5m 00s"); + rerender(); + // Bench A's state, totals and down-time clock must not stand beside Cart B's name, however long this takes. + expect(document.querySelector(".station-uptime")).toBeNull(); + await settle(3_000); + expect(document.querySelector(".station-uptime")).toBeNull(); + pending[1](READY); + await settle(); + expect(chip().textContent).toBe("Ready"); + }); + + it("keeps the last answer when an abandoned read fails late", async () => { + const pending: Array<{ resolve: (uptime: StationUptime) => void; reject: (reason: Error) => void }> = []; + const load = vi.fn(() => new Promise((resolve, reject) => pending.push({ resolve, reject }))); + const { rerender } = render(); + rerender(); + pending[1].resolve(READY); + await settle(); + pending[0].reject(new Error("offline")); + await settle(); + expect(chip().textContent).toBe("Ready"); + }); + + it("renders nothing while the uptime cannot be read, and recovers on the next refresh", async () => { + const { state } = await renderChip(new Error("offline")); + expect(screen.queryByRole("img")).toBeNull(); + expect(document.querySelector(".station-uptime")).toBeNull(); + state.answer = READY; + await settle(UPTIME_REFRESH_MS); + expect(chip().textContent).toBe("Ready"); + }); +}); diff --git a/examples/egocap/frontend/src/UptimeChip.tsx b/examples/egocap/frontend/src/UptimeChip.tsx new file mode 100644 index 0000000000..341c9f9a26 --- /dev/null +++ b/examples/egocap/frontend/src/UptimeChip.tsx @@ -0,0 +1,103 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The station's uptime chip, beside the station name in the status strip. + * + * Read-only: the backend decides by itself whether the station can record and logs the day's timeline of it. + * The chip says ready, recording, or down and for how long; beside it, once the day has a take, are the active + * and down time between the first take and the last. How long the station has been down keeps counting here + * between loads, from the figure the backend computed and the time since this browser received it, so no clock + * comparison between the two machines is involved. + */ +import { useEffect, useReducer, useState } from "react"; +import { sentence } from "./sentence"; +import { fetchStationUptime, type StationUptime, type UptimeState } from "./stationsApi"; +import { dayHasTake, formatActivity, formatTotal } from "./stationTime"; + +/** How often the uptime is read again when nothing prompts it, so a station that went down or came back shows without a reload. */ +export const UPTIME_REFRESH_MS = 15_000; + +/** Each state as the chip words it. */ +const STATE_WORDS: Record = { ready: "Ready", recording: "Recording", down: "Down" }; + +/** How long the station has been down, counted up to now; null when it is not down or the start is unknown. */ +export function downSeconds(uptime: StationUptime, secondsSinceReceipt: number): number | null { + if (uptime.state !== "down" || uptime.since === null) return null; + return Math.max(0, uptime.as_of - uptime.since) + Math.max(0, secondsSinceReceipt); +} + +export interface UptimeChipProps { + /** The station label in effect; uptime is kept per station, so a change of it loads that station's day. */ + stationLabel: string | null; + /** Anything whose change means the station's state may have: the chip reads again at once instead of on its timer. */ + refreshKey?: unknown; + load?: (signal: AbortSignal) => Promise; +} + +/** Show whether the station can record right now and, once the day has a take, its active and down time. */ +export function UptimeChip({ stationLabel, refreshKey, load = fetchStationUptime }: UptimeChipProps) { + // Kept with the station it was read for: until that station's own answer arrives, another station's state, + // totals and clock must not stand beside its name. + const [answer, setLoaded] = useState<{ uptime: StationUptime; receivedAt: number; stationLabel: string | null } | null>(null); + const loaded = answer !== null && answer.stationLabel === stationLabel ? answer : null; + const [refresh, bumpRefresh] = useReducer((n: number) => n + 1, 0); + const [, tick] = useReducer((n: number) => n + 1, 0); + + useEffect(() => { + const controller = new AbortController(); + load(controller.signal).then( + (uptime) => { + // Kept with the moment it arrived, which is what the live count is measured from. + if (!controller.signal.aborted) setLoaded({ uptime, receivedAt: performance.now(), stationLabel }); + }, + () => { + // The strip stays usable without it; the next refresh tries again. + if (!controller.signal.aborted) setLoaded(null); + }, + ); + return () => controller.abort(); + }, [load, stationLabel, refreshKey, refresh]); + + useEffect(() => { + const id = setInterval(bumpRefresh, UPTIME_REFRESH_MS); + return () => clearInterval(id); + }, []); + + // Re-render once a second only while a down time is counting; the other states show no clock. + const counting = loaded !== null && downSeconds(loaded.uptime, 0) !== null; + useEffect(() => { + if (!counting) return undefined; + const id = setInterval(tick, 1000); + return () => clearInterval(id); + }, [counting]); + + if (loaded === null) return null; + const { uptime, receivedAt } = loaded; + const down = downSeconds(uptime, (performance.now() - receivedAt) / 1000); + const reason = uptime.state === "down" && uptime.reason !== null ? sentence(uptime.reason) : null; + const elapsed = down === null ? null : formatActivity(down); + const blockers = uptime.blockers.length; + return ( + + + + {dayHasTake(uptime) && ( + + active {formatTotal(uptime.active_seconds)} · down {formatTotal(uptime.down_seconds)} + {blockers > 0 && ` · ${blockers} blocker${blockers === 1 ? "" : "s"}`} + + )} + + ); +} diff --git a/examples/egocap/frontend/src/WrapUpDialog.test.tsx b/examples/egocap/frontend/src/WrapUpDialog.test.tsx new file mode 100644 index 0000000000..bd1d46d263 --- /dev/null +++ b/examples/egocap/frontend/src/WrapUpDialog.test.tsx @@ -0,0 +1,648 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The end-of-day dialog: the day's takes and their outcomes, the station's time and notes, correcting a task, saving. */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { act, cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react"; +import type { CorrectionReply, DayReportReply } from "./dayReportApi"; +import { DAY_REPORT_FIXTURE, UPTIME_FIXTURE } from "./dayReportTestDoubles"; +import { SettingsHttpError } from "./settingsApi"; +import { WrapUpDialog, type WrapUpBackend, type WrapUpDialogProps } from "./WrapUpDialog"; + +afterEach(cleanup); + +/** A backend that answers with `reply` and, like the real one, with the notes it was last given. */ +function fakeBackend(reply: DayReportReply | Error = DAY_REPORT_FIXTURE): WrapUpBackend { + let notes = reply instanceof Error ? "" : reply.uptime.notes; + return { + load: vi.fn(async () => { + if (reply instanceof Error) throw reply; + return { ...reply, uptime: { ...reply.uptime, notes } }; + }), + save: vi.fn(async () => ({ ...DAY_REPORT_FIXTURE, saved: { report: "bench_a_2026-03-09_report.json", activity_log: "bench_a_2026-03-09_activity.json" } })), + correct: vi.fn(async () => ({ session: "s", updated: ["episode_0", "episode_1"], missing: ["episode_2"], config_updated: true })), + saveNotes: vi.fn(async (_token: string, _station: string, next: string) => { + notes = next; + return { ...UPTIME_FIXTURE, notes }; + }), + }; +} + +function renderDialog(overrides: Partial = {}, backend = fakeBackend()) { + const props: WrapUpDialogProps = { open: true, onClose: vi.fn(), controlToken: "tok", backend, ...overrides }; + render(); + return { props, backend }; +} + +const region = (name: string) => screen.findByRole("region", { name }); +const notesField = (card: HTMLElement) => within(card).getByLabelText("Notes") as HTMLTextAreaElement; + +describe("WrapUpDialog", () => { + it("renders nothing while closed and does not fetch", () => { + const { backend } = renderDialog({ open: false }); + expect(screen.queryByRole("dialog")).toBeNull(); + expect(backend.load).not.toHaveBeenCalled(); + }); + + it("asks for the control token instead of the report without it", () => { + const { backend } = renderDialog({ controlToken: null }); + expect(screen.getByText("Enter the control token in the recording panel to see the day's report.")).toBeTruthy(); + expect(backend.load).not.toHaveBeenCalled(); + }); + + it("shows today for the station in use, with nothing to choose a day or a station by", async () => { + const { backend } = renderDialog(); + await region("Takes"); + expect(backend.load).toHaveBeenCalledWith("tok", expect.any(AbortSignal)); + expect(screen.getByRole("heading", { name: "End of day — Bench A, 2026-03-09" })).toBeTruthy(); + const body = document.querySelector(".settings-content-body") as HTMLElement; + expect(Array.from(body.children).map((part) => part.getAttribute("aria-label") ?? part.textContent)).toEqual(["Takes", "Station time", "Sessions", "Save report"]); + expect(body.querySelector('input[type="date"], input[type="checkbox"]')).toBeNull(); + }); + + it("shows the day's takes by outcome, with rejected and pending takes counted", async () => { + renderDialog(); + const takes = await region("Takes"); + expect(within(takes).getByText("5 takes, 1h 02m recorded.")).toBeTruthy(); + expect(within(takes).getAllByRole("listitem").map((tile) => tile.textContent)).toEqual([ + "2Kept1h 02m", + "1Flagged0m 08s", + "1Rejected0m 03s", + "0Discarded0m 00s", + "1Pending0m 04s", + ]); + }); + + it("lists each session's takes with their real outcome, time, task and issues", async () => { + renderDialog(); + const sessions = await region("Sessions"); + expect(within(sessions).getByText("08:15 · session_20260309-081500_abc123")).toBeTruthy(); + expect(within(sessions).getByText("Bench A · 2 kept · 1 flagged · 1 rejected · 1 pending")).toBeTruthy(); + const rows = within(sessions).getAllByRole("row").slice(1).map((row) => Array.from(row.querySelectorAll("td")).map((cell) => cell.textContent)); + expect(rows).toEqual([ + ["0", "Kept", "60:00", "Pour water.", "alex", "—"], + ["1", "Kept", "2:05", "Pour water.", "alex", "—"], + ["2", "Flagged", "0:08", "Pour water.", "alex", "sustained_freeze:pico_controller/head_pose"], + ["3", "Rejected", "0:03", "Pour water.", "alex", "camera_min_fps:head_human_camera"], + ["4", "Pending", "0:04", "Pour water.", "alex", "—"], + ]); + }); + + it("opens the latest session and leaves the earlier ones collapsed", async () => { + const [session] = DAY_REPORT_FIXTURE.report.sessions; + const twoSessions = { ...DAY_REPORT_FIXTURE, report: { ...DAY_REPORT_FIXTURE.report, sessions: [{ ...session, session_id: "session_morning" }, session] } }; + renderDialog({}, fakeBackend(twoSessions)); + const sessions = await region("Sessions"); + expect(Array.from(sessions.querySelectorAll("details")).map((details) => details.open)).toEqual([false, true]); + }); + + it("says when nothing was recorded today", async () => { + const empty: DayReportReply = { + ...DAY_REPORT_FIXTURE, + report: { ...DAY_REPORT_FIXTURE.report, sessions: [], totals: { ...DAY_REPORT_FIXTURE.report.totals, episodes: 0, seconds: 0 } }, + uptime: { ...UPTIME_FIXTURE, state: "ready", reason: null, active_seconds: 0, down_seconds: 0, blockers: [], notes: "" }, + }; + renderDialog({}, fakeBackend(empty)); + const time = await region("Station time"); + expect(screen.getByText("0 takes, 0m 00s recorded.")).toBeTruthy(); + expect(screen.getByText("Nothing was recorded today.")).toBeTruthy(); + expect(within(time).getByText("No take yet today.")).toBeTruthy(); + expect(within(time).queryByRole("list")).toBeNull(); + expect(within(time).queryByText("✓ Saved")).toBeNull(); + }); + + it("counts a single take in the singular", async () => { + renderDialog({}, fakeBackend({ ...DAY_REPORT_FIXTURE, report: { ...DAY_REPORT_FIXTURE.report, totals: { ...DAY_REPORT_FIXTURE.report.totals, episodes: 1 } } })); + expect(within(await region("Takes")).getByText("1 take, 1h 02m recorded.")).toBeTruthy(); + }); + + it("shows the report a newer read brought, not an older one that answers late", async () => { + const pending: Array<(reply: DayReportReply) => void> = []; + const backend = fakeBackend(); + backend.load = vi.fn(() => new Promise((resolve) => pending.push(resolve))); + const props: WrapUpDialogProps = { open: true, onClose: vi.fn(), controlToken: "tok", backend }; + const { rerender } = render(); + rerender(); + expect(pending).toHaveLength(2); + await act(async () => pending[1]({ ...DAY_REPORT_FIXTURE, report: { ...DAY_REPORT_FIXTURE.report, station: "Cart B" } })); + await act(async () => pending[0](DAY_REPORT_FIXTURE)); // the first read answers late + expect(screen.getByRole("heading", { name: "End of day — Cart B, 2026-03-09" })).toBeTruthy(); + }); + + it("takes no answer once it is closed", async () => { + const pending: Array<(reason: Error) => void> = []; + const backend = fakeBackend(); + backend.load = vi.fn(() => new Promise((_resolve, reject) => pending.push(reject))); + const props: WrapUpDialogProps = { open: true, onClose: vi.fn(), controlToken: "tok", backend }; + const { rerender } = render(); + rerender(); + rerender(); + await act(async () => pending[0](new SettingsHttpError("offline"))); + // The reopened dialog is waiting for its own read: the abandoned one's failure is not shown. + expect(screen.getByText("Loading…")).toBeTruthy(); + expect(screen.queryByText(/The report is unavailable/)).toBeNull(); + }); + + it("shows a take being recorded now", async () => { + const [session] = DAY_REPORT_FIXTURE.report.sessions; + const live: DayReportReply = { + ...DAY_REPORT_FIXTURE, + report: { + ...DAY_REPORT_FIXTURE.report, + totals: { ...DAY_REPORT_FIXTURE.report.totals, by_disposition: { ...DAY_REPORT_FIXTURE.report.totals.by_disposition, recording: { count: 1, seconds: 0 } } }, + sessions: [{ ...session, episodes: [{ ...session.episodes[4], disposition: "recording" }] }], + }, + }; + renderDialog({}, fakeBackend(live)); + const takes = await region("Takes"); + expect(within(takes).getAllByRole("listitem").pop()?.textContent).toBe("1Recording0m 00s"); + }); + + it("says why the report is unavailable, and closes on Escape and the Close button", async () => { + const { props } = renderDialog({}, fakeBackend(new SettingsHttpError("control token rejected"))); + expect(await screen.findByText("The report is unavailable: control token rejected")).toBeTruthy(); + fireEvent.keyDown(window, { key: "Escape" }); + fireEvent.click(screen.getByRole("button", { name: "Close" })); + expect(props.onClose).toHaveBeenCalledTimes(2); + }); +}); + +describe("station time in the end-of-day dialog", () => { + it("shows the active and down time in one line and each blocker with its clock times", async () => { + renderDialog(); + const time = await region("Station time"); + expect(within(time).getByText("Active 2h 05m · Down 17m")).toBeTruthy(); + expect(within(within(time).getByRole("list", { name: "Blockers" })).getAllByRole("listitem").map((line) => line.textContent)).toEqual([ + "11:02–11:14 · 12m 00s · Left wrist: cam_left: no recent frame", + "14:05–now · 5m 00s · Left wrist: cam_left: no recent frame", + ]); + // The station's state is the backend's own: nothing here sets it. + expect(within(time).getAllByRole("button").map((button) => button.textContent)).toEqual(["Save notes"]); + }); + + it("shows zero active and down time, not that there is no take, once the report counts one", async () => { + renderDialog({}, fakeBackend({ ...DAY_REPORT_FIXTURE, uptime: { ...UPTIME_FIXTURE, state: "ready", reason: null, active_seconds: 0, down_seconds: 0, blockers: [] } })); + const time = await region("Station time"); + expect(screen.getByText("5 takes, 1h 02m recorded.")).toBeTruthy(); + expect(within(time).getByText("Active 0m · Down 0m")).toBeTruthy(); + expect(within(time).queryByText("No take yet today.")).toBeNull(); + }); + + it("shows the totals without a list when nothing blocked the station", async () => { + renderDialog({}, fakeBackend({ ...DAY_REPORT_FIXTURE, uptime: { ...UPTIME_FIXTURE, down_seconds: 0, blockers: [] } })); + const time = await region("Station time"); + expect(within(time).getByText("Active 2h 05m · Down 0m")).toBeTruthy(); + expect(within(time).queryByRole("list")).toBeNull(); + }); + + it("saves the operator's notes and reads the report again", async () => { + const { backend } = renderDialog(); + const time = await region("Station time"); + const notes = notesField(time); + expect(notes.value).toBe("left glove battery"); + expect(notes.maxLength).toBe(4000); + const save = within(time).getByRole("button", { name: "Save notes" }) as HTMLButtonElement; + expect(save.disabled).toBe(true); + expect(within(time).getByText("✓ Saved")).toBeTruthy(); + fireEvent.change(notes, { target: { value: "left glove battery; replaced at 14:10" } }); + expect(within(time).queryByText("✓ Saved")).toBeNull(); + fireEvent.click(save); + await waitFor(() => expect(backend.saveNotes).toHaveBeenCalledWith("tok", "Bench A", "left glove battery; replaced at 14:10")); + await waitFor(() => expect(backend.load).toHaveBeenCalledTimes(2)); // the report is read again + expect(notes.value).toBe("left glove battery; replaced at 14:10"); + expect(await within(time).findByText("✓ Saved")).toBeTruthy(); + expect(save.disabled).toBe(true); + }); + + it("keeps what the operator is typing when the report is read again", async () => { + const { backend } = renderDialog(); + const time = await region("Station time"); + fireEvent.change(notesField(time), { target: { value: "typing…" } }); + const sessions = screen.getByRole("region", { name: "Sessions" }); + fireEvent.change(within(sessions).getByLabelText("Takes to correct"), { target: { value: "0" } }); + fireEvent.change(within(sessions).getByLabelText("Correct task"), { target: { value: "Wash the cup." } }); + fireEvent.click(within(sessions).getByRole("button", { name: "Correct" })); + await waitFor(() => expect(backend.load).toHaveBeenCalledTimes(2)); + await within(sessions).findByText(/^Corrected/); + expect(notesField(time).value).toBe("typing…"); + expect((within(time).getByRole("button", { name: "Save notes" }) as HTMLButtonElement).disabled).toBe(false); + }); + + it("keeps the report, the notes being typed and the correction's outcome when the report cannot be read again", async () => { + const backend = fakeBackend(); + const load = vi.mocked(backend.load); + renderDialog({}, backend); + const time = await region("Station time"); + fireEvent.change(notesField(time), { target: { value: "typing…" } }); + load.mockRejectedValueOnce(new SettingsHttpError("backend restarting")); + const sessions = screen.getByRole("region", { name: "Sessions" }); + fireEvent.change(within(sessions).getByLabelText("Takes to correct"), { target: { value: "0" } }); + fireEvent.change(within(sessions).getByLabelText("Correct task"), { target: { value: "Wash the cup." } }); + fireEvent.click(within(sessions).getByRole("button", { name: "Correct" })); + expect(await screen.findByText(/The report could not be read again, so it is shown as last read: backend restarting/)).toBeTruthy(); + expect(screen.queryByText(/The report is unavailable/)).toBeNull(); + expect(within(sessions).getByText(/^Corrected episode_0, episode_1/)).toBeTruthy(); + expect(notesField(time).value).toBe("typing…"); + expect(screen.getByRole("region", { name: "Takes" })).toBeTruthy(); + // Reading again is offered, and a read that answers takes the notice away without touching the draft. + fireEvent.click(screen.getByRole("button", { name: "Read again" })); + await waitFor(() => expect(screen.queryByText(/could not be read again/)).toBeNull()); + expect(load).toHaveBeenCalledTimes(3); + expect(notesField(time).value).toBe("typing…"); + }); + + it("keeps the saved notes on screen when the report cannot be read again after saving them", async () => { + const backend = fakeBackend(); + renderDialog({}, backend); + const time = await region("Station time"); + vi.mocked(backend.load).mockRejectedValueOnce(new SettingsHttpError("backend restarting")); + fireEvent.change(notesField(time), { target: { value: "replaced the glove" } }); + fireEvent.click(within(time).getByRole("button", { name: "Save notes" })); + expect(await screen.findByText(/The report could not be read again/)).toBeTruthy(); + expect(notesField(time).value).toBe("replaced the glove"); + expect(within(time).getByText("✓ Saved")).toBeTruthy(); + }); + + it("leaves the notes and their button able to hold focus while a save is on its way, and sends it once", async () => { + const backend = fakeBackend(); + let finish: (uptime: typeof UPTIME_FIXTURE) => void = () => undefined; + backend.saveNotes = vi.fn(() => new Promise((resolve) => (finish = resolve))); + renderDialog({}, backend); + const time = await region("Station time"); + const notes = notesField(time); + fireEvent.change(notes, { target: { value: "replaced the glove" } }); + const save = within(time).getByRole("button", { name: "Save notes" }) as HTMLButtonElement; + fireEvent.click(save); + expect(save.textContent).toBe("Saving…"); + // A disabled control gives up keyboard focus, leaving the operator outside the notes they are saving. + expect([notes.disabled, notes.readOnly, save.disabled]).toEqual([false, true, false]); + fireEvent.click(save); + expect(backend.saveNotes).toHaveBeenCalledTimes(1); + await act(async () => finish({ ...UPTIME_FIXTURE, notes: "replaced the glove" })); + expect(notes.readOnly).toBe(false); + }); + + it("shows why the notes were not saved and keeps them", async () => { + const backend = fakeBackend(); + backend.saveNotes = vi.fn(async () => { + throw new SettingsHttpError("notes may be at most 4000 characters"); + }); + renderDialog({}, backend); + const time = await region("Station time"); + fireEvent.change(notesField(time), { target: { value: "too long" } }); + fireEvent.click(within(time).getByRole("button", { name: "Save notes" })); + expect(await within(time).findByText("Not saved: notes may be at most 4000 characters")).toBeTruthy(); + expect(notesField(time).value).toBe("too long"); + }); + + it("saves notes for the station they were typed for, even after the report was read again for another", async () => { + const backend = fakeBackend(); + renderDialog({}, backend); + const time = await region("Station time"); + fireEvent.change(notesField(time), { target: { value: "left glove swapped" } }); + // The station in use changes, and a correction has the report read again: it is Cart B's now. + vi.mocked(backend.load).mockResolvedValue({ ...DAY_REPORT_FIXTURE, station_in_use: "Cart B", uptime: { ...UPTIME_FIXTURE, station: "Cart B", notes: "" } }); + const sessions = screen.getByRole("region", { name: "Sessions" }); + fireEvent.change(within(sessions).getByLabelText("Takes to correct"), { target: { value: "0" } }); + fireEvent.change(within(sessions).getByLabelText("Correct task"), { target: { value: "Wash the cup." } }); + fireEvent.click(within(sessions).getByRole("button", { name: "Correct" })); + await waitFor(() => expect(backend.load).toHaveBeenCalledTimes(2)); + await within(sessions).findByText(/^Corrected/); + fireEvent.click(within(time).getByRole("button", { name: "Save notes" })); + await waitFor(() => expect(backend.saveNotes).toHaveBeenCalledWith("tok", "Bench A", "left glove swapped")); + }); + + it("keeps a draft with the station it was begun for when it is typed back to another station's saved notes", async () => { + const backend = fakeBackend(); + renderDialog({}, backend); + const time = await region("Station time"); + fireEvent.change(notesField(time), { target: { value: "left glove swapped" } }); + // The report is read again and is Cart B's, whose notes are empty. + vi.mocked(backend.load).mockResolvedValue({ ...DAY_REPORT_FIXTURE, station_in_use: "Cart B", uptime: { ...UPTIME_FIXTURE, station: "Cart B", notes: "" } }); + const sessions = screen.getByRole("region", { name: "Sessions" }); + fireEvent.change(within(sessions).getByLabelText("Takes to correct"), { target: { value: "0" } }); + fireEvent.change(within(sessions).getByLabelText("Correct task"), { target: { value: "Wash the cup." } }); + fireEvent.click(within(sessions).getByRole("button", { name: "Correct" })); + await within(sessions).findByText(/^Corrected/); + // Emptying the field matches Cart B's notes, but the draft is Bench A's: it stays unsaved and stays Bench A's. + fireEvent.change(notesField(time), { target: { value: "" } }); + expect((within(time).getByRole("button", { name: "Save notes" }) as HTMLButtonElement).disabled).toBe(false); + fireEvent.change(notesField(time), { target: { value: "x" } }); + fireEvent.click(within(time).getByRole("button", { name: "Save notes" })); + await waitFor(() => expect(backend.saveNotes).toHaveBeenCalledWith("tok", "Bench A", "x")); + }); + + it("says the station in use changed when the notes are refused for that, keeps them, and saves them after a reload", async () => { + const backend = fakeBackend(); + const saveNotes = vi.mocked(backend.saveNotes); + saveNotes.mockRejectedValueOnce(new SettingsHttpError("the station in use changed; reload the report", 409)); + renderDialog({}, backend); + const time = await region("Station time"); + fireEvent.change(notesField(time), { target: { value: "left glove swapped" } }); + fireEvent.click(within(time).getByRole("button", { name: "Save notes" })); + const refusal = await within(time).findByRole("alert"); + expect(refusal.textContent).toBe("The station in use changed; reload the report. Reload"); + expect(within(time).queryByText(/^Not saved/)).toBeNull(); + expect(saveNotes).toHaveBeenLastCalledWith("tok", "Bench A", "left glove swapped"); + expect(notesField(time).value).toBe("left glove swapped"); + // Reloading reads the report of the station now in use; the draft stays and is then saved for that station. + vi.mocked(backend.load).mockResolvedValue({ ...DAY_REPORT_FIXTURE, report: { ...DAY_REPORT_FIXTURE.report, station: "Cart B" }, station_in_use: "Cart B", uptime: { ...UPTIME_FIXTURE, station: "Cart B", notes: "" } }); + fireEvent.click(within(refusal).getByRole("button", { name: "Reload" })); + expect(await screen.findByRole("heading", { name: "End of day — Cart B, 2026-03-09" })).toBeTruthy(); + expect(within(time).queryByRole("alert")).toBeNull(); + expect(notesField(time).value).toBe("left glove swapped"); + fireEvent.click(within(time).getByRole("button", { name: "Save notes" })); + await waitFor(() => expect(saveNotes).toHaveBeenLastCalledWith("tok", "Cart B", "left glove swapped")); + }); + + it("closes on Escape in the notes while nothing is unsaved, also after typing back to what is saved", async () => { + const { props } = renderDialog(); + const notes = notesField(await region("Station time")); + fireEvent.keyDown(notes, { key: "Escape" }); + expect(props.onClose).toHaveBeenCalledTimes(1); + fireEvent.change(notes, { target: { value: "left glove battery; replaced" } }); + fireEvent.change(notes, { target: { value: "left glove battery" } }); + fireEvent.keyDown(notes, { key: "Escape" }); + expect(props.onClose).toHaveBeenCalledTimes(2); + expect(screen.queryByText("Discard unsaved changes?")).toBeNull(); + }); +}); + +describe("closing the end-of-day dialog over something unsaved", () => { + const question = () => screen.queryByRole("group", { name: "Discard unsaved changes?" }); + const backdrop = () => document.querySelector(".settings-backdrop") as HTMLElement; + /** The dialog with notes typed but not saved. */ + async function withUnsavedNotes() { + const rendered = renderDialog(); + const notes = notesField(await region("Station time")); + fireEvent.change(notes, { target: { value: "left glove battery; replaced" } }); + return { ...rendered, notes }; + } + + it("asks instead of closing on Escape from any control, on the backdrop and on Close", async () => { + const { props, notes } = await withUnsavedNotes(); + const asks: Array<() => void> = [ + () => fireEvent.keyDown(notes, { key: "Escape" }), + () => fireEvent.keyDown(screen.getByRole("button", { name: "Save report" }), { key: "Escape" }), + () => fireEvent.click(backdrop()), + () => fireEvent.click(screen.getByRole("button", { name: "Close" })), + ]; + for (const ask of asks) { + ask(); + expect(question()?.textContent).toBe("Discard unsaved changes?DiscardKeep editing"); + // The question stands in for Close until it is answered. + expect(screen.queryByRole("button", { name: "Close" })).toBeNull(); + fireEvent.click(screen.getByRole("button", { name: "Keep editing" })); + expect(question()).toBeNull(); + } + expect(props.onClose).not.toHaveBeenCalled(); + expect(notes.value).toBe("left glove battery; replaced"); + }); + + it("closes once the operator says to discard", async () => { + const { props } = await withUnsavedNotes(); + fireEvent.click(screen.getByRole("button", { name: "Close" })); + fireEvent.click(screen.getByRole("button", { name: "Discard" })); + expect(props.onClose).toHaveBeenCalledTimes(1); + }); + + it("never discards on Escape: a second one takes the question away, and the backdrop leaves it", async () => { + const { props, notes } = await withUnsavedNotes(); + fireEvent.keyDown(notes, { key: "Escape" }); + fireEvent.click(backdrop()); + expect(question()).not.toBeNull(); + fireEvent.keyDown(window, { key: "Escape" }); + expect(question()).toBeNull(); + expect(props.onClose).not.toHaveBeenCalled(); + }); + + it("puts focus on Keep editing, then back where the operator was, or on Close when that is gone", async () => { + const { notes } = await withUnsavedNotes(); + notes.focus(); + fireEvent.keyDown(notes, { key: "Escape" }); + expect(document.activeElement).toBe(screen.getByRole("button", { name: "Keep editing" })); + fireEvent.click(screen.getByRole("button", { name: "Keep editing" })); + expect(document.activeElement).toBe(notes); + // Close itself gives way to the question, so it cannot take focus back as the same element. + const close = screen.getByRole("button", { name: "Close" }); + close.focus(); + fireEvent.click(close); + fireEvent.click(screen.getByRole("button", { name: "Keep editing" })); + expect(document.activeElement).toBe(screen.getByRole("button", { name: "Close" })); + }); + + it("asks over a half-typed correction too, and no longer once it is cleared or applied", async () => { + const { props } = renderDialog(); + const sessions = await region("Sessions"); + const takes = within(sessions).getByLabelText("Takes to correct"); + fireEvent.change(takes, { target: { value: "2-" } }); + fireEvent.keyDown(window, { key: "Escape" }); + expect(question()).not.toBeNull(); + fireEvent.click(screen.getByRole("button", { name: "Keep editing" })); + fireEvent.change(takes, { target: { value: "" } }); + fireEvent.keyDown(window, { key: "Escape" }); + expect(props.onClose).toHaveBeenCalledTimes(1); + fireEvent.change(takes, { target: { value: "2" } }); + fireEvent.change(within(sessions).getByLabelText("Correct task"), { target: { value: "Wash the cup." } }); + fireEvent.click(within(sessions).getByRole("button", { name: "Correct" })); + await within(sessions).findByText(/^Corrected/); + // The form reports that it holds nothing typed in an effect, which may run after the text is on screen. + await act(async () => {}); + fireEvent.click(screen.getByRole("button", { name: "Close" })); + expect(props.onClose).toHaveBeenCalledTimes(2); + }); + + it("closes without asking once the notes are saved", async () => { + const { props } = await withUnsavedNotes(); + const time = screen.getByRole("region", { name: "Station time" }); + fireEvent.click(within(time).getByRole("button", { name: "Save notes" })); + await within(time).findByText("✓ Saved"); + fireEvent.click(backdrop()); + expect(props.onClose).toHaveBeenCalledTimes(1); + }); +}); + +describe("correcting a task", () => { + it("corrects the task of a range of takes, says what changed, and reads the report again", async () => { + const { backend } = renderDialog(); + const sessions = await region("Sessions"); + const correct = within(sessions).getByRole("button", { name: "Correct" }) as HTMLButtonElement; + expect(correct.disabled).toBe(true); + fireEvent.change(within(sessions).getByLabelText("Takes to correct"), { target: { value: " 0-2 " } }); + fireEvent.change(within(sessions).getByLabelText("Correct task"), { target: { value: "Place the cup on the shelf." } }); + fireEvent.click(correct); + expect(await within(sessions).findByText("Corrected episode_0, episode_1. Not found: episode_2.")).toBeTruthy(); + // Nothing but the session, the takes and the task is sent. + expect(backend.correct).toHaveBeenCalledWith("tok", { session: "session_20260309-081500_abc123", episodes: "0-2", task: "Place the cup on the shelf." }); + expect((within(sessions).getByLabelText("Takes to correct") as HTMLInputElement).value).toBe(""); + await waitFor(() => expect(backend.load).toHaveBeenCalledTimes(2)); + }); + + it("offers nothing but the takes and the task to correct in a session recorded in one place", async () => { + renderDialog(); + const form = (await region("Sessions")).querySelector(".wrap-up-correction") as HTMLElement; + expect(Array.from(form.querySelectorAll("input, select, textarea")).map((control) => control.getAttribute("aria-label"))).toEqual(["Takes to correct", "Correct task"]); + expect(within(await region("Sessions")).getAllByRole("columnheader").map((head) => head.textContent)).toEqual(["Take", "Outcome", "Time", "Task", "Operator", "Issues"]); + }); + + it("shows the backend's reason for a refused correction and keeps what was typed", async () => { + const backend = fakeBackend(); + backend.correct = vi.fn(async () => { + throw new SettingsHttpError("this session is still open for recording; start a new batch first"); + }); + renderDialog({}, backend); + const sessions = await region("Sessions"); + fireEvent.change(within(sessions).getByLabelText("Takes to correct"), { target: { value: "0" } }); + fireEvent.change(within(sessions).getByLabelText("Correct task"), { target: { value: "Wash the cup." } }); + fireEvent.click(within(sessions).getByRole("button", { name: "Correct" })); + expect(await within(sessions).findByText("Not corrected: this session is still open for recording; start a new batch first")).toBeTruthy(); + expect((within(sessions).getByLabelText("Correct task") as HTMLInputElement).value).toBe("Wash the cup."); + }); + + it("offers each routed group of a session as the place to correct, and none when no take was finalized", async () => { + const [session] = DAY_REPORT_FIXTURE.report.sessions; + const routed = { + ...DAY_REPORT_FIXTURE, + report: { + ...DAY_REPORT_FIXTURE.report, + sessions: [ + { + ...session, + session_id: "session_routed", + episodes: [ + { ...session.episodes[0], location: "Kitchen/2026-03-09-08-15-00/episode_4" }, + { ...session.episodes[1], location: "Bathroom/2026-03-09-08-40-00/episode_0" }, + ], + }, + { ...session, session_id: "session_nothing_kept", started_at: null, episodes: [session.episodes[3]], problems: ["episode_9.json: unsupported manifest"] }, + ], + }, + }; + const backend = fakeBackend(routed); + renderDialog({}, backend); + const sessions = await region("Sessions"); + const holder = within(sessions).getByLabelText("Recorded under") as HTMLSelectElement; + expect(Array.from(holder.options).map((option) => option.value)).toEqual(["Kitchen/2026-03-09-08-15-00", "Bathroom/2026-03-09-08-40-00"]); + // The take number shown is the one inside that group, which is what a correction addresses; both groups + // number from zero, so each take also says which group it is in. + const table = within(sessions).getAllByRole("table")[0]; + expect(within(table).getAllByRole("columnheader").map((head) => head.textContent)).toEqual(["Take", "Recorded under", "Outcome", "Time", "Task", "Operator", "Issues"]); + expect(within(table).getAllByRole("row").slice(1).map((row) => Array.from(row.querySelectorAll("td")).slice(0, 2).map((cell) => cell.textContent))).toEqual([ + ["4", "Kitchen/2026-03-09-08-15-00"], + ["0", "Bathroom/2026-03-09-08-40-00"], + ]); + fireEvent.change(holder, { target: { value: "Bathroom/2026-03-09-08-40-00" } }); + fireEvent.change(within(sessions).getByLabelText("Takes to correct"), { target: { value: "0" } }); + fireEvent.change(within(sessions).getByLabelText("Correct task"), { target: { value: "Wash the cup." } }); + fireEvent.click(within(sessions).getByRole("button", { name: "Correct" })); + await waitFor(() => expect(backend.correct).toHaveBeenCalledWith("tok", { session: "Bathroom/2026-03-09-08-40-00", episodes: "0", task: "Wash the cup." })); + expect(await within(sessions).findByText("Corrected episode_0, episode_1 in Bathroom/2026-03-09-08-40-00. Not found: episode_2.")).toBeTruthy(); + // The session whose only take was rejected has nothing to relabel, and its unreadable record is reported. + expect(sessions.querySelectorAll(".wrap-up-correction")).toHaveLength(1); + expect(within(sessions).getByText("session_nothing_kept")).toBeTruthy(); + expect(within(sessions).getByText("Unreadable take record: episode_9.json: unsupported manifest")).toBeTruthy(); + }); + + it("says where each take is recorded as soon as one is held outside its session, even in a single group", async () => { + const [session] = DAY_REPORT_FIXTURE.report.sessions; + const routed = { + ...DAY_REPORT_FIXTURE, + report: { + ...DAY_REPORT_FIXTURE.report, + sessions: [ + { + ...session, + episodes: [ + // Kept takes carry their slot in the one group; the interrupted take keeps its place in the session. + { ...session.episodes[0], location: "Kitchen/2026-03-09-08-15-00/episode_0" }, + { ...session.episodes[1], location: "Kitchen/2026-03-09-08-15-00/episode_1" }, + { ...session.episodes[4], location: `${session.session_id}/episode_1` }, + ], + }, + ], + }, + }; + renderDialog({}, fakeBackend(routed)); + const sessions = await region("Sessions"); + const table = within(sessions).getByRole("table"); + expect(within(table).getAllByRole("columnheader").map((head) => head.textContent)).toContain("Recorded under"); + expect(within(table).getAllByRole("row").slice(1).map((row) => Array.from(row.querySelectorAll("td")).slice(0, 2).map((cell) => cell.textContent))).toEqual([ + ["0", "Kitchen/2026-03-09-08-15-00"], + ["1", "Kitchen/2026-03-09-08-15-00"], + ["1", session.session_id], + ]); + // One group leaves nothing to choose for a correction. + expect(within(sessions).queryByLabelText("Recorded under")).toBeNull(); + }); +}); + +describe("saving the report", () => { + it("saves the report and names the files written", async () => { + const { backend } = renderDialog(); + await region("Takes"); + fireEvent.click(screen.getByRole("button", { name: "Save report" })); + expect(await screen.findByText("Saved bench_a_2026-03-09_report.json and bench_a_2026-03-09_activity.json in station_status under the recording output.")).toBeTruthy(); + expect(backend.save).toHaveBeenCalledWith("tok"); + }); + + it("says why the report could not be saved", async () => { + const backend = fakeBackend(); + backend.save = vi.fn(async () => { + throw new SettingsHttpError("could not save the report"); + }); + renderDialog({}, backend); + await region("Takes"); + fireEvent.click(screen.getByRole("button", { name: "Save report" })); + expect(await screen.findByText("Not saved: could not save the report")).toBeTruthy(); + }); +}); + +describe("keyboard focus in the end-of-day dialog", () => { + it("tabs past a collapsed session to the next thing that can take focus, and back", async () => { + const [session] = DAY_REPORT_FIXTURE.report.sessions; + const twoSessions = { ...DAY_REPORT_FIXTURE, report: { ...DAY_REPORT_FIXTURE.report, sessions: [{ ...session, session_id: "session_morning" }, session] } }; + renderDialog({}, fakeBackend(twoSessions)); + const sessions = await region("Sessions"); + const [collapsed, open] = Array.from(sessions.querySelectorAll("summary")); + const notes = notesField(screen.getByRole("region", { name: "Station time" })); + notes.focus(); + // Save notes is disabled, so the collapsed session's summary is next. + fireEvent.keyDown(notes, { key: "Tab" }); + expect(document.activeElement).toBe(collapsed); + // Its takes and its correction form are not on screen: the next stop is the open session. + fireEvent.keyDown(collapsed, { key: "Tab" }); + expect(document.activeElement).toBe(open); + fireEvent.keyDown(open, { key: "Tab" }); + expect(document.activeElement).toBe(within(open.parentElement as HTMLElement).getByLabelText("Takes to correct")); + fireEvent.keyDown(document.activeElement as Element, { key: "Tab", shiftKey: true }); + expect(document.activeElement).toBe(open); + fireEvent.keyDown(open, { key: "Tab", shiftKey: true }); + expect(document.activeElement).toBe(collapsed); + }); + + it("keeps focus in the correction form while a correction is being sent, and sends it once", async () => { + const backend = fakeBackend(); + let answer: (reply: CorrectionReply) => void = () => {}; + backend.correct = vi.fn(() => new Promise((resolve) => (answer = resolve))); + renderDialog({}, backend); + const sessions = await region("Sessions"); + const takes = within(sessions).getByLabelText("Takes to correct") as HTMLInputElement; + const task = within(sessions).getByLabelText("Correct task") as HTMLInputElement; + fireEvent.change(takes, { target: { value: "0" } }); + fireEvent.change(task, { target: { value: "Wash the cup." } }); + task.focus(); + const button = within(sessions).getByRole("button", { name: "Correct" }) as HTMLButtonElement; + fireEvent.click(button); + const busy = (await within(sessions).findByRole("button", { name: "Correcting…" })) as HTMLButtonElement; + // A disabled field cannot hold focus, so the fields are held read-only and the button only marked busy. + expect(document.activeElement).toBe(task); + expect([takes.disabled, takes.readOnly, task.disabled, task.readOnly]).toEqual([false, true, false, true]); + expect([busy.disabled, busy.getAttribute("aria-busy"), busy.getAttribute("aria-disabled")]).toEqual([false, "true", "true"]); + fireEvent.click(busy); + expect(backend.correct).toHaveBeenCalledTimes(1); + await act(async () => answer({ session: "s", updated: ["episode_0"], missing: [], config_updated: true })); + await within(sessions).findByText(/^Corrected episode_0/); + expect(task.readOnly).toBe(false); + }); +}); diff --git a/examples/egocap/frontend/src/WrapUpDialog.tsx b/examples/egocap/frontend/src/WrapUpDialog.tsx new file mode 100644 index 0000000000..f74f227095 --- /dev/null +++ b/examples/egocap/frontend/src/WrapUpDialog.tsx @@ -0,0 +1,601 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The end-of-day dialog: what was recorded today at the station in use and what became of each take, the + * station's active and down time with what blocked it and the operator's notes, correcting a task after + * recording, and saving the report on the station. + * + * Closing would drop notes that are not saved and a correction that is half typed, so while there are any the + * dialog asks before it closes, whichever way the close was asked for. + * + * Notes are written for one station's day. They are saved for the station of the report they were typed over, + * and the backend refuses them when another station is in use by then; the operator reloads the report, sees + * which station it is now for, and saves again. + * + * Everything shown comes from the backend's report, which reads the recording service's own manifests: a + * rejected, discarded or interrupted take is listed with its real outcome, never left out. The dialog itself + * decides nothing about a take, and the station's time is the backend's own log, not something set here. + */ +import { useCallback, useEffect, useRef, useState } from "react"; +import { + DISPOSITIONS, + correctSession, + fetchDayReport, + saveDayReport, + type Correction, + type CorrectionReply, + type DayReportReply, + type ReportEpisode, + type ReportSession, + type TakeDisposition, +} from "./dayReportApi"; +import { formatElapsed } from "./RecordingPanel"; +import { sentence } from "./sentence"; +import { SettingsHttpError } from "./settingsApi"; +import { Card, errorMessage, useAction, useEscapeToClose, useModalFocus, type Loaded } from "./settingsParts"; +import { saveStationNotes, type StationUptime, type UptimeBlocker } from "./stationsApi"; +import { formatActivity, formatTotal } from "./stationTime"; + +/** The calls the dialog makes; the page uses the real ones and tests pass fakes. */ +export interface WrapUpBackend { + /** Reads today's report for the station in use. */ + load: (controlToken: string, signal: AbortSignal) => Promise; + /** Writes the report as a file on the station and answers with it and the files written. */ + save: (controlToken: string) => Promise; + /** Corrects the task of a session's takes and answers with which were changed and which were not found. */ + correct: (controlToken: string, correction: Correction) => Promise; + /** Saves the day's notes for `station`; rejects with a 409 `SettingsHttpError` when that is no longer the station in use. */ + saveNotes: (controlToken: string, station: string, notes: string) => Promise; +} + +/** Notes as typed, with the station whose day they were typed for. */ +interface NotesDraft { + /** The station in use when the notes were typed. */ + station: string; + /** The notes as typed. */ + text: string; +} + +/** The backend's own routes; the dialog uses these unless a test passes fakes. */ +export const REAL_WRAP_UP_BACKEND: WrapUpBackend = { load: fetchDayReport, save: saveDayReport, correct: correctSession, saveNotes: saveStationNotes }; + +/** The longest notes the backend accepts, so the field stops where a save would be refused. */ +const MAX_NOTES_CHARS = 4000; + +/** Each outcome in the operator's words. */ +const DISPOSITION_LABELS: Record = { + kept: "Kept", + flagged: "Flagged", + rejected: "Rejected", + discarded: "Discarded", + pending: "Pending", + recording: "Recording", +}; + +/** A take's episode number where its data is: the trailing number of its location. */ +function episodeNumber(episode: ReportEpisode): string { + return episode.location.slice(episode.location.lastIndexOf("_") + 1); +} + +/** The session or routed group holding a take's data: its location without the episode. */ +function holderOf(episode: ReportEpisode): string { + return episode.location.slice(0, episode.location.lastIndexOf("/")); +} + +/** The clock time a session was opened, from its `YYYY-MM-DDTHH:MM:SS` start. */ +function startedAt(session: ReportSession): string { + return session.started_at === null ? "" : session.started_at.slice(11, 16); +} + +/** A local clock time, in the 24-hour form the session list uses. */ +function clockTime(epochSeconds: number): string { + const at = new Date(epochSeconds * 1000); + return `${String(at.getHours()).padStart(2, "0")}:${String(at.getMinutes()).padStart(2, "0")}`; +} + +export interface WrapUpDialogProps { + /** Whether the dialog is shown; closed, it renders nothing and reads nothing. */ + open: boolean; + /** Asked for when the operator closes the dialog, after any question about unsaved input. */ + onClose: () => void; + /** The run's control token; the report is not readable without it. */ + controlToken: string | null; + /** The calls the dialog makes; the real routes unless a test passes fakes. */ + backend?: WrapUpBackend; +} + +/** Show the day's takes, the station's time and notes, and the correction and report actions. */ +export function WrapUpDialog({ open, onClose, controlToken, backend = REAL_WRAP_UP_BACKEND }: WrapUpDialogProps) { + const dialogRef = useModalFocus(open); + const [state, setState] = useState>({ kind: "loading" }); + // The notes as typed, kept here so that reading the report again never replaces them. Null while the operator + // has typed nothing: the field then shows what is saved. + const [notesDraft, setNotesDraft] = useState(null); + // Whether the backend refused the notes because another station is in use than the one they were typed for. + const [stationChanged, setStationChanged] = useState(false); + // Set by the reload the operator asks for after that refusal: the report it brings is the one they then save + // the notes over, so the draft moves to that report's station. No other read moves it. + const adoptStation = useRef(false); + // Bumped after a correction or saved notes, so the report shows what is now on disk. + const [generation, setGeneration] = useState(0); + // Why the latest read failed. A report already on screen stays there with this beside it: the correction or + // notes save that asked for the read succeeded, and the notes draft is only reachable through the report. + const [readFailure, setReadFailure] = useState(null); + const reload = useCallback(() => setGeneration((n) => n + 1), []); + const { load } = backend; + // The sessions whose correction form holds typed input. Only consulted when a close is asked for, so a ref. + const typedCorrections = useRef(new Set()); + /** Note whether a session's correction form holds typed input. */ + const noteCorrectionTyped = useCallback((sessionId: string, typed: boolean) => { + if (typed) typedCorrections.current.add(sessionId); + else { + typedCorrections.current.delete(sessionId); + // An applied or cleared correction leaves nothing of its own to discard, so the question goes with it. + if (typedCorrections.current.size === 0) setConfirmingDiscard(false); + } + }, []); + // Whether the header is asking to discard what is unsaved instead of offering Close. + const [confirmingDiscard, setConfirmingDiscard] = useState(false); + const closeButton = useRef(null); + const keepButton = useRef(null); + /** Close, or ask first while notes are unsaved or a correction is typed. */ + const requestClose = useCallback(() => { + if (notesDraft !== null || typedCorrections.current.size > 0) setConfirmingDiscard(true); + else onClose(); + }, [notesDraft, onClose]); + // Escape asks to close like the button does; over the question it answers "keep editing", never "discard". + useEscapeToClose(open, confirmingDiscard ? () => setConfirmingDiscard(false) : requestClose); + useEffect(() => { + if (!confirmingDiscard) return; + // The question replaces Close in the header: focus goes to its safe answer, and afterwards back to where + // the operator was, or to Close when that control is gone. + const previous = document.activeElement; + keepButton.current?.focus(); + return () => { + if (previous instanceof HTMLElement && previous.isConnected && previous !== document.body) previous.focus(); + else closeButton.current?.focus(); + }; + }, [confirmingDiscard]); + + useEffect(() => { + if (!open || controlToken === null) return; + const controller = new AbortController(); + // A refresh keeps the last report on screen instead of flashing back to "Loading". + setState((current) => (current.kind === "loaded" ? current : { kind: "loading" })); + load(controlToken, controller.signal).then( + (value) => { + if (controller.signal.aborted) return; + setState({ kind: "loaded", value }); + setReadFailure(null); + if (adoptStation.current) { + adoptStation.current = false; + setNotesDraft((draft) => (draft === null ? null : { ...draft, station: value.station_in_use })); + } + }, + (error: unknown) => { + if (controller.signal.aborted) return; + const message = errorMessage(error); + setState((current) => (current.kind === "loaded" ? current : { kind: "error", message })); + setReadFailure(message); + }, + ); + return () => controller.abort(); + }, [open, controlToken, load, generation]); + + if (!open) return null; + const reply = state.kind === "loaded" ? state.value : null; + /** Show the saved notes at once, then read the report again so all of it is what is on disk. */ + const notesSaved = (uptime: StationUptime) => { + setState((current) => (current.kind === "loaded" ? { kind: "loaded", value: { ...current.value, uptime } } : current)); + setNotesDraft(null); + setStationChanged(false); + // Saved notes are no longer something to discard. + if (typedCorrections.current.size === 0) setConfirmingDiscard(false); + reload(); + }; + /** Read the report for the station now in use, keeping the notes as typed to be saved over it. */ + const reloadForStation = () => { + adoptStation.current = true; + setStationChanged(false); + reload(); + }; + return ( + <> +