SUBTASK #49: Scan screen (1.3.1, 1.3.2) and message display (SH-5)

What to do

The page where a user starts a scan and watches it run: a scope field and a Start Scan button (1.3.1), and a live view of the scan's progress and outcome (1.3.2). Also the shared pieces every later screen will reuse: one way to call the API (BB-7) and one way to show messages (SH-5).

Built as the product's React app (Vite), in its own project at frontend/app/. This is separate from the dev-only CRUD page in frontend/crud-react/, which is not part of the product and should not be imported from.

Background

• Spec: NFR-01, WF-01, FR-13, OUT-04 (a rejection comes with a reason), OUT-06 (scan status and errors), CM-09, CM-11 and CM-15 (see that a scan is running and who started it)
• System design: 1.3.1 Capture Scan Request, 1.3.2 Show Scan Status ("display running or finished state, who started it, and errors"), SH-5 Display Message (confirmations, rejections, conflict notices, errors), BB-7 Service Request Client; section 3 tier rules (the UI only talks to the API)
• The API and its JSON: SUBTASK #49: Scan and device API endpoints #51 (the shapes there are the contract)
• Rules are in Minimal Application Controller, Scan API and Screens (2.0, 1.3, 1.2.1) #49
• The React + Vite setup follows the CRUD page (frontend/crud-react/): same Vite version, /api proxy, oxlint

Steps

Project setup

• frontend/app/: a new Vite + React project (npm create vite@latest, React, JavaScript), plus react-router-dom
• vite.config.js: proxy /api to #50's app (use the port #50 settles on; it must differ from the CRUD server's 5000 if both are to run at once)
• Routes: /scans is this screen, / redirects to it, /devices is a placeholder that subtask 4 fills in
• npm run lint passes with no warnings; add oxlint's react/no-danger rule as an error (see the XSS step)
• frontend/app/README.md: how to install, run in dev, and build (Node 20.19+); node_modules/ and dist/ are git-ignored

Shared pieces (every screen will use these)

• src/components/api.js, BB-7 Service Request Client: one api(path, { method, body }) function for every API call. Sends and receives JSON, and turns any failure into one error shape, an ApiError with status and message: the server's {"error": ...} text, or "Can't reach the server" (and unreachable: true) when the app is down
• Sample mode: with VITE_USE_SAMPLES=true in frontend/app/.env.local, api() returns the sample JSON from #51 (in src/samples/) instead of calling the server, so the screen can be built before the API exists
• src/components/Messages.jsx, SH-5 Display Message: a MessageProvider around the app, a useMessages() hook giving showMessage(kind, text) with kinds success, warning (for example, a refusal) and error, and one <MessageArea /> that shows them the same way on every screen. Success and warning messages are in an aria-live="polite" region, errors in role="alert", so screen readers announce them
• src/styles/app.css: shared styles for the page, messages, progress bar and tables (subtask 4 uses them too)

The scan screen: src/views/scans/ScanScreen.jsx (plus small components and hooks beside it as needed)

• When the page opens, ask GET /api/scans/status:
  • A scan is running (maybe someone else's): show its progress and start following it (CM-15)
  • Otherwise: show the last scan's outcome, and pre-fill the scope with the last scan's scope
• 1.3.1, start a scan: a scope field and a Start Scan button
  • POST /api/scans. 202: start following the scan. 409: show the refusal as a warning ("A scan started by sam at 14:03 is still running") and start following that scan. 400: show the reason as an error
  • The scope is checked by the server (SH-1); the page only stops an empty submit
  • The button is disabled while a scan runs
• 1.3.2, follow a scan: a useScanStatus() hook polls GET /api/scans/status every 2 seconds while a scan runs, and the screen shows:
  • Who started it, when, and the scope
  • The phase in plain words ("Finding devices", "Saving results") with a progress bar for done / total ("120 of 254")
  • Errors so far, as a list
  • When it ends: stop polling; show the outcome (success as a confirmation, partial as a warning with its reasons, failed as an error) and a link to the device list (/devices)
  • If the server can't be reached, show it once (not every 2 seconds) and keep trying every 5 seconds; clear the message when it answers again
  • The polling timer is cleared when the screen closes or the scan ends (an effect cleanup), so no requests keep running after leaving the page. Check it still behaves under React StrictMode, which runs effects twice in development
• Cross-site scripting: text from the server is only ever rendered as {text} in JSX, which React escapes. Never dangerouslySetInnerHTML. Error messages and, later, device names come from the network and could contain markup. The react/no-danger lint rule enforces this

Serving it

• Development: npm run dev in frontend/app/ (http://localhost:5173), with #50's app running for the API
• The real app and the demo: npm run build creates frontend/app/dist/; #50's app serves those files at /, and sends index.html for any non-/api path so /scans and /devices work on refresh. Node is needed to build, not to run
• A dev.py command for the build (e.g. .\dev build-ui), or a note in the README, so nobody demos a stale build

Testing

• Build against the sample JSON from #51 first (sample mode above), then point it at the real API
• Optional: Vitest unit tests for api.js (server error, unreachable, 204) and for the status-to-text mapping (phases, outcomes)
• A manual test checklist in the PR: start a scan; open a second browser tab and click Start (refusal shown, progress followed); stop MAMP mid-scan (failed outcome shown); stop the app (unreachable message once, recovers when restarted); refresh on /scans with the built app (still loads)

Where

frontend/app/ (new Vite project): src/components/api.js, src/components/Messages.jsx, src/styles/app.css, src/views/scans/ScanScreen.jsx (+ its hook and components), vite.config.js, README.md. The empty frontend/components/, frontend/views/ and frontend/styles/ placeholder folders can be removed.

Done when

• A scan can be started from the browser, and its progress followed to the end
• A second tab clicking Start sees the refusal naming who started the running scan, and then that scan's progress
• Partial and failed outcomes show their reasons
• The built app, served by #50 at /, works in a current Chrome, Edge and Firefox
• npm run lint passes with no warnings

Depends on

• #51 Scan and device API endpoints (the JSON shapes; samples first, then the real API)
• #50 Application entry point and Application Controller (the port, and serving dist/ at /)