Console: watch a device from its drawer's Screen tab; the lease stream route goes #910

Part of #906.

Scope

An operator watches a device's screen from the device drawer, on a single worker or a gateway, whether or not the device is leased. The drawer gets two tabs, Details and Screen, and opens on Details. The picture starts when Screen opens and stops when the operator leaves the tab or closes the drawer. The stream numbers move behind an ⓘ button. The lease drawer loses its Screen tab. With its last caller gone, GET /v1/stream/leases/{id} is removed.

In short

Today: Leases → a lease → Screen tab → Show screen. After: Fleet → a worker → a device → Screen tab, and the picture starts by itself. When the device is not running, the tab says why and starts by itself once the device is ready again.

flowchart TD
  R[Device row] --> D["Device drawer, Details tab (changed: tabs)"]
  D -->|Screen tab, ?drawer=screen| S{device state}
  S -->|ready or leased| P["Picture (new: no button)"]
  S -->|other| N[Its sentence]
  N -->|becomes ready| P
  P -->|ⓘ| I[Popover: stream numbers]
  P -->|leave tab, close drawer| X[Request aborted]

The tab's text, word for word (<worker> is the worker's name as the console shows it):

The ⓘ button (named "Stream details") opens a popover with State, Picture, Frames, Rate, Bandwidth and Dropped, the facts that sit under the picture today. Escape, a click outside or a second click closes it.

A new term: drawer query parameter, the device drawer's open tab in the URL, e.g. /fleet/w1/dev_1?tab=devices&drawer=screen. tab stays the worker page's tab. drawer belongs to one open drawer: closing the drawer drops it, and device row links never carry it, so the next device opens on Details.

If this goes wrong, a user would see the picture keep the worker capturing after they left the tab, or no picture for a running device.

Technical spec

Facts

Modules touched

Searches: rg "ScreenPanel|ScreenView|refusalOf|useScreen|stream/leases|leaseIdOf|requireLease|unknownLease|holder\(|DrawerTabs|streamOffer" over ui/src, src/, e2e, docs/internal, website/src/content/docs. Beyond F14–F16 they find e2e/console/leases.spec.ts:337 (the lease Screen tab), ui/src/screens/leases/leases.test.tsx:168-228 (ScreenView), ui/src/state/screen.test.ts:25-31 (the 404's lease words), src/stream/gateway-link.test.ts:82, watching-the-screen.mdx:103. The lease path also sits in src/daemon/stream-gateway.e2e.test.ts:144, src/http/openapi.test.ts:353-355, src/http/core-routes.test.ts:88, ui/src/data/stream.ts:2, ui/src/data/api.test.ts:273 and src/stream/{service,gateway-link,create}.test.ts; each moves to the device route or goes.

flowchart LR
  DD[screens/fleet/device-drawer *] --> SP[screens: ScreenPanel, moved *]
  SP --> US[state/screen: useScreen by worker+device *]
  US --> API[data/api stream]
  DD --> DT[ds/drawer DrawerTabs: value from URL *]
  SP --> PO[ds/popover new *]
  SP --> IC[ds/icon info *]
  LD[screens/leases/drawer *] -.Screen tab removed.-> SP
  ST[src/stream: lease route removed *]

sequenceDiagram
  participant O as Operator
  participant C as Console
  participant D as Daemon
  O->>C: Screen tab
  C->>D: GET /v1/stream/workers/w1/devices/d1
  D-->>C: 409 DEVICE_NOT_RUNNING
  C-->>O: "The device is shut down. Its screen shows while it runs."
  D-->>C: 200 frames
  O->>C: Details tab
  C->>D: abort

Contract and event changes

• HTTP: GET /v1/stream/leases/{id} is removed, with its lease lookup, owner check and the lease keying of the capture registry (F19, F22). noSuchStream changes for every unmatched stream path, the old one included: 404 UNKNOWN_LEASE "This path names no stream lease" becomes 404 UNKNOWN_DEVICE "This path names no stream" (F21), and definition.ts's 404 lists UNKNOWN_DEVICE and UNKNOWN_WORKER only. The route's declaration leaves the OpenAPI document. No protocol bump (no src/contract change); no events.
• Console URL: drawer query parameter, screen or absent (Details). Any other value reads as Details.

Other code on the same state

The console's live stream request and the worker's capture. Searched rg "useScreen|api.stream" ui/src (3 hits): the screen hook, its test, the API client. One ScreenPanel is mounted at a time per drawer; Base UI unmounts a tab panel that is not keepMounted, and the Screen tab is not, so leaving it aborts its request. Two browser tabs on one device run two captures (ADR 0045 §5). #909 serves the route; this task only reads it. #912 changes ActionBar, which the device drawer keeps using as is.

Failure modes

No state written.

Rules in play

• ADR 0045 §1: one route shape on either daemon — the console builds the URL from the drawer's worker id and device id, in both modes.
• ADR 0037: "the console acts through the HTTP routes, on Base UI" — the popover is Base UI's.
• DESIGN.md drawer rule — rewritten: a device's drawer has Details and Screen tabs; a lease's has Details and Events.
• ui/AGENTS.md Rules: "A screen never fetches" — the stream stays in state/screen.ts; the sentence table is a pure function in model/screen.ts.
• documentation rule 9: console.mdx (the device drawer and its Screen tab; the lease drawer without it), watching-the-screen.mdx (Fleet path, picture not bound to a lease, the lease route gone), ui/AGENTS.md pages table, src/stream/AGENTS.md (lease route gone).

Tests

Seam: the browser lane e2e/console/screen.spec.ts against a started worker with the scripted capture program (its witness log counts captures opened and closed), plus ui/src/model/screen.test.ts for the sentence table, and src/stream/service.test.ts for the removed route.

• An operator opens a device drawer and its Screen tab: opens on Details with no capture started; Screen → one capture opened and a picture painted, URL has drawer=screen; Details → the capture closed; closing the drawer → closed, and the URL has no drawer; opening another device after that → Details, no capture; the device is leased while the tab is open → the same request stays open (one capture opened, none closed); a gateway with one worker gives the same, through the same URL shape.
• The Screen tab of a device that is not running: each state's sentence from the table, no capture opened (model unit test for the five states, deleted, an unknown word, and a 409 on a ready row; browser for shutdown); the device turns ready while the tab is open → the picture starts; the device is shut down while watched → the stream ends and the tab shows the shutdown sentence; the console reopens only after a refusal or an end, never on a ready→leased change; streaming off on the worker → "Streaming is off on ." with no request.
• An operator opens the stream numbers: ⓘ "Stream details" → popover with State, Picture, Frames, Rate, Bandwidth, Dropped; Escape and a second click close it while the drawer stays open and no capture closes; no Picture fact is drawn outside the popover.
• An operator opens a lease drawer: its tabs are Details and Events (leases.spec.ts:645 changes to this).
• A caller asks for a stream path that names no stream: GET /v1/stream/leases/lse_1, /v1/stream/workers/w1, /v1/stream/devices/d1 → 404 UNKNOWN_DEVICE "This path names no stream", nothing opened (extends service.test.ts:58).

Done when

• pnpm test and pnpm test:console pass, with the five Tests lines above.
• rg -l "stream/leases" src ui e2e website docs/internal --glob '!docs/internal/adr/**' lists only the test that proves the old path answers 404.
• The OpenAPI document has no /v1/stream/leases/{id}.
• console.mdx, watching-the-screen.mdx, ui/AGENTS.md, src/stream/AGENTS.md and DESIGN.md's drawer rule describe the device drawer's Screen tab.

Out of scope

• The stream route itself (Stream any running device to an operator by worker and device id #909).
• Touch or key input on the picture.
• Any other drawer's tabs.

Depends on

• Stream any running device to an operator by worker and device id #909