HIPCTF2/.kilo/plans/880.md

Implementation Plan: Authenticated Shell LED Visibility Fix

1. Architectural Reconnaissance

• Codebase style & conventions: Node.js monorepo with an Angular 17 standalone-component SPA and NestJS backend. The authenticated shell uses OnPush components, signal inputs/outputs, inline Angular templates/styles, and theme CSS custom properties. HomeComponent owns event-stream lifecycle and passes EventStatusStore.state() into the presentational ShellHeaderComponent. Quick tabs and change-password behavior are already implemented and are not implicated in this regression.
• Data Layer: TypeORM-backed backend settings provide eventStartUtc and eventEndUtc; no schema or persistence changes are required. The backend event-state calculation and authenticated SSE payload are already functioning: the shell receives the correct running, countdown, stopped, or unconfigured state and applies the matching class.
• Test Framework & Structure: Root Jest 29 multi-project configuration with ts-jest; frontend tests run in jsdom from the dedicated tests/frontend/ directory. npm test runs all backend and frontend tests, while npm run test:frontend runs the frontend project only. Existing tests/frontend/shell-led.spec.ts is a source-structure assertion and does not instantiate the component or verify the rendered style binding.
• Required Tools & Dependencies: No new system tools, global CLIs, npm packages, persistent /data assets, or setup.sh changes are required. Existing Angular, Jest, jsdom, and TypeScript dependencies are sufficient.

2. Impacted Files

• To Modify:
  • frontend/src/app/features/shell/header/shell-header.component.ts — remove the conflicting transparent base declaration and bind the state-specific background color directly on the LED element so the browser paints the themed color reliably.
  • tests/frontend/shell-led.spec.ts — replace/extend brittle source-only assertions with a focused automated regression covering the style value produced for each event state and preserving the accessible state label.
• To Create: None.

3. Proposed Changes

1. Database / Schema Migration: None. Event timestamps, settings storage, REST/SSE contracts, and backend state computation remain unchanged.
2. Backend Logic & APIs: None. /api/v1/events/status already emits the correct state, and EventStatusStore already forwards it to the shell.
3. Frontend UI Integration:
   1. In ShellHeaderComponent, define a typed state-to-theme-color mapping for all EventState values: running → var(--color-success), countdown → var(--color-warning), stopped → var(--color-danger), and unconfigured → var(--color-secondary).
   2. Replace the unused ledClass computed value with a computed background-color value derived from eventState(); keep the existing state class bindings because they are useful selectors and preserve the current DOM contract.
   3. Bind the computed value directly to the LED span's style.background-color. This gives the element an explicit non-transparent author value while continuing to resolve the active theme token at runtime, matching the reported proof that a direct targeted declaration makes the dot visible.
   4. Remove background-color: transparent from the component base .led rule, and remove the redundant component state-color declarations if the inline binding becomes the single authoritative color source. Retain only the shape/layout styling (inline-block, 10×10 dimensions, circular radius, border, alignment).
   5. Remove the global LED state rules from frontend/src/styles.css if they are no longer consumed, avoiding duplicate ownership and future cascade ambiguity; keep canonical theme token declarations untouched.
   6. Preserve the existing data-testid, four state classes, and aria-label="Event status: <state>", so status remains exposed textually rather than by color alone.
   7. Do not modify HomeComponent, QuickTabsComponent, change-password components, event store, routes, SSE transport, or backend services because repository tracing shows those layers already deliver the correct state and shell behavior.

4. Test Strategy

• Target Unit Test File: tests/frontend/shell-led.spec.ts.
• Mocking Strategy: No backend, HTTP, SSE, timers, filesystem fixtures, browser automation, or persistent data. Exercise a small exported pure state-to-color helper (or equivalent component mapping) with table-driven assertions for the four states, and retain focused source/template assertions that the LED consumes that value through [style.background-color], keeps each state class binding, and keeps the dynamic aria-label. This directly prevents a regression to a transparent base color while remaining fast and CLI-only under npm test.
• Verification Commands for the implementer: Run npm run test:frontend, npm test, and npm run build from /repo. The root build compiles both Angular and NestJS; no separate lint or typecheck script is defined.