nicegui updates

docs/step5.md

@@ -17,15 +17,19 @@ This step composes Steps 1–4 into a usable UI.
 
 Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/registers NiceGUI pages via explicit page modules.
 
+Reference baseline: `resource://skills/nicegui/document`
+
 ### Core architecture decisions
 
 - **App factory:** `create_app()`
 - **Lifespan-managed resources:** worker start/stop managed in startup/shutdown
 - **Modular pages:** upload and jobs pages in separate modules (no monolithic UI file)
 - **Health endpoint:** FastAPI-side `/healthz`
+- **UI composition:** route pages stay modular and reusable shared shell/components live under `ui/components` as needed
+- **Styling architecture:** shared CSS loaded once at startup; avoid ad-hoc per-page styling drift
 - **Dependency direction (one-way):**
   - `app` -> `config/logging/db/worker/ui/api`
-  - `ui/pages` -> `services`
+  - `ui/pages` -> `ui/components` + `services`
   - `services` -> `db/models/providers`
   - no reverse imports from services into UI/API
 
@@ -33,6 +37,14 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist
 
 - **DB:** already enabled (SQLModel + SQLite), session lifecycle remains request/service-scoped as built in prior steps.
 - **AI workflow:** already in place via Step 3 transcription service + Step 4 worker; UI does not call provider SDK directly.
+- **Mounted docs:** not in Step 5 scope; docs mounting remains disabled for MVP.
+
+### Async and responsiveness stance
+
+- Prefer `async def` for page handlers and service boundaries when I/O is involved.
+- Keep UI handlers non-blocking (no blocking sleeps or synchronous long I/O calls).
+- For long-running user actions, always provide explicit loading/progress/error states.
+- Keep cancellation/timeout behavior explicit for refresh/poll operations where applicable.
 
 ---
 
@@ -62,6 +74,8 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist
 - `src/transcription/ui/upload_page.py` (upload flow)
 - `src/transcription/ui/jobs_page.py` (status list + detail)
 - `src/transcription/ui/__init__.py` (explicit `register_pages(...)` export)
+- `src/transcription/ui/components/*` (shared shell/navigation/status components if introduced)
+- `src/transcription/ui/static/*.css` (optional shared CSS loaded once at startup)
 
 ### Test files
 - `tests/test_app.py`
@@ -74,6 +88,8 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist
 
 ## Implementation Plan + Checklist
 
+Plan baseline and guardrails source: `resource://skills/nicegui/document`
+
 ## Phase A — App factory and lifespan orchestration
 
 - [ ] Create `create_app()` in `src/transcription/app.py`
@@ -89,6 +105,7 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist
   - [ ] join/cleanup worker thread/task cleanly
 - [ ] Register API router(s), including health route
 - [ ] Register NiceGUI pages via explicit page registration function
+- [ ] Load shared CSS once at startup (if present)
 
 ## Phase B — FastAPI health endpoint
 
@@ -107,7 +124,8 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist
 - [ ] On error:
   - [ ] show user-safe error message
   - [ ] restore ready UI state
-- [ ] Ensure no blocking calls in UI event handlers beyond bounded service interaction
+- [ ] Ensure non-blocking I/O in UI event handlers; offload CPU-heavy work to worker path
+- [ ] Make timeout/cancellation behavior explicit for any long-running action
 
 ## Phase D — Jobs page (`ui/jobs_page.py`)
 
@@ -117,6 +135,7 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist
 - [ ] Show transcript on success, error detail on failure
 - [ ] Include explicit refresh action and loading state
 - [ ] Ensure error states are surfaced to user and logged
+- [ ] Keep refresh path async and bounded to avoid UI freeze
 
 ## Phase E — UI registration module
 
@@ -125,6 +144,12 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist
 - [ ] Ensure each page module exports `register_page(...)`
 - [ ] Keep page registration explicit and modular
 
+## Phase F — Shared components and style consistency
+
+- [ ] Add `ui/components` module only for reusable shell elements (header/nav/status chips), not page-local logic
+- [ ] Keep structural layout in Python; keep visual polish in shared CSS
+- [ ] Avoid one-off styling duplication across upload/jobs pages
+
 ---
 
 ## MCP Testing Workflow (Required)
@@ -190,6 +215,7 @@ Suggested coverage:
 - [ ] success feedback displayed
 - [ ] error feedback displayed for `UploadError`
 - [ ] loading/progress state behavior covered
+- [ ] timeout/cancellation behavior covered (if implemented)
 
 ### `tests/ui/test_jobs_page.py`
 - [ ] list renders job statuses
@@ -202,6 +228,10 @@ Marker strategy:
 - [ ] `integration` for app/page/service+DB contracts
 - [ ] `external` not required for default Step 5 lane
 
+Async behavior assertions:
+- [ ] long-running actions keep button/inputs in expected disabled state
+- [ ] completion/failure returns controls to ready state
+
 ---
 
 ## Validation Sequence (strict)
@@ -222,8 +252,10 @@ Marker strategy:
 - [ ] Do not collapse pages into one file.
 - [ ] Do not use implicit global side effects for runtime wiring.
 - [ ] Keep UI responsive with explicit loading/progress/error states.
+- [ ] Do not block UI handlers with synchronous long I/O.
 - [ ] Do not place provider SDK calls in UI handlers.
 - [ ] Keep dependency direction one-way and maintainable.
+- [ ] Keep shared UI in `ui/components`; keep service logic out of page modules.
 
 ---
 
@@ -234,9 +266,20 @@ Marker strategy:
 - [ ] Upload page creates queued jobs through service boundary
 - [ ] Jobs list/detail pages render status/transcript/failure data
 - [ ] Worker lifecycle is started/stopped by app lifespan
+- [ ] Async UI states (loading/success/error) are deterministic and tested
 - [ ] Scaffold->fill testing flow completed and validated
 - [ ] Full suite passes: `uv run pytest -q`
 
+## Completion Checks (NiceGUI skill aligned)
+
+- [ ] Uses app factory and FastAPI lifespan
+- [ ] Pages are modularized (not single-file UI)
+- [ ] Health endpoint exists on FastAPI side
+- [ ] Dependency direction is clean and one-way
+- [ ] Async-first guidance is applied where I/O exists, with explicit non-blocking UX states
+- [ ] DB/AI/docs decisions are explicit and reflected in structure
+- [ ] Plan references baseline URI: `resource://skills/nicegui/document`
+
 ---
 
 ## PR Checklist (Integrated)