# 0008 — Angular for the overlay frontend

- **Status:** Accepted
- **Date:** 2026-05-07

## Context and problem statement

`PROJECT_CONTEXT.md` explicitly deferred the overlay framework choice to Stage 2, noting that Vanilla TypeScript + Lit "is likely a better fit" for bundle size and Twitch review simplicity. The overlay app was scaffolded with Angular as a placeholder. A decision is required before building any real overlay components.

## Decision drivers

- **Bundle size.** Twitch reviews extensions manually; a smaller bundle reduces scrutiny risk and load time over arbitrary stream content.
- **Developer velocity.** Familiarity with a framework dominates iteration speed, especially for a solo build.
- **Component model fit.** The overlay has three display states and a PubSub subscription — straightforward enough for any framework.
- **Existing scaffold.** The Angular app already exists in the workspace; switching adds setup cost with no immediate payoff.

## Considered options

1. **Angular.** Full framework; already scaffolded; developer is expert-level.
2. **Lit.** Web-component library; ~15–20 KB; closer to the platform.
3. **Vanilla TypeScript (hand-rolled).** Minimal; total control; no dependency; highest maintenance burden for reactivity.

## Decision outcome

**Chosen: Angular.**

The developer is very familiar with Angular and unfamiliar with Lit. Velocity matters more than the marginal bundle-size improvement. Angular's production build with `@angular/build` treeshakes aggressively; the overlay's initial budget is set to 1 MB error / 500 KB warning in `project.json`, which is comfortably achievable. The three overlay states map naturally to standalone Angular components with signals for reactive state.

## Consequences

### Positive

- No framework ramp-up time; patterns (signals, standalone components, `HttpClient`, RxJS) are immediately available.
- `@angular/build` produces well-optimised production bundles with differential loading and full treeshaking.
- Existing workspace tooling (`@nx/angular`, ESLint, Vitest via `vitest-angular`) works without additional configuration.

### Negative

- Baseline bundle is larger than Lit or vanilla (~120–200 KB gzipped vs ~15–20 KB). Mitigate with lazy routes if the expanded view grows significantly.
- If Twitch introduces strict size limits in a future review cycle, migrating is non-trivial.

### Neutral

- Revisit if the production bundle consistently exceeds 400 KB gzipped after Stage 2 is complete. At that point, incremental Lit migration (replacing individual components) is feasible without a full rewrite.