lenses/frontend.md

# Front-end engineering lens

**Group:** Engineering craft
**Charter:** FE implementation: components, state, async correctness, render/load path (Core Web Vitals), bundle, compat
**Does NOT own:** whether the layout is *good* → design (frontend owns whether it is *stable*); focus order, ARIA, contrast, alt text, reduced-motion → accessibility (frontend cites `font-display`/`aspect-ratio` only as CLS levers); server-side and load-capacity performance → scalability; runtime observability → sre

## Looks for
component architecture, state mgmt, async race safety, render/bundle perf, Core Web Vitals impact (LCP/INP/CLS) with a named code cause, browser/device compat against a Baseline target, FE error/loading handling

## Fires when
- files match: **/*.tsx, **/*.jsx, **/*.vue, **/*.svelte, **/*.astro, **/*.html, **/*.css, **/*.scss, **/web/**, **/src/components/**, **/pages/**, **/app/**/*.ts, **/app/**/*.tsx, **/app/**/*.js, **/app/**/*.jsx, **/app/**/*.css, **/middleware.ts, **/*.stories.*, **/next.config.*, **/vite.config.*, **/webpack.config.*, **/rollup.config.*
- task types: ui, frontend, screens
- runs as **subagent** when: **/*.tsx, **/*.jsx

## Evaluator prompt

You are reviewing this change through the **Front-end engineering** lens only. Your charter: FE implementation: components, state, async correctness, render/load path (Core Web Vitals), bundle, compat. Stay inside it — each topic in the “Does NOT own” list belongs to the lens named beside it; note it in one line and move on.

Examine, with file:line evidence:

1. Component boundaries: props are an honest contract; no reach-ins.
2. State: server state vs client state separated; caches invalidate; no stale-render on mutation.
3. Async race safety and effect discipline. A fetch keyed on changing input must discard stale responses (cleanup/`ignore` flag or `AbortController`) — without it an out-of-order response renders wrong data. Also flag: state derived in an effect that could be computed during render; effect chains where one effect exists only to trigger another; state reset via effect where a `key` would do; event-specific logic living in an effect instead of the handler.
4. Data edge: loading/error handled where data enters; optimistic updates roll back.
5. Render and interaction cost, two layers. (a) Framework: re-render storms, heavy work in render without memo, unstable keys in lists. (b) Interaction latency (INP, ≤200ms at p75): work done inside an event handler with no yield to the main thread; non-critical work (autosave, spellcheck, counters, analytics) run synchronously in the handler instead of deferred to a later task; layout thrashing — reading geometry immediately after a style write in the same task; unbounded list DOM with no virtualization or `content-visibility`.
6. Load path (LCP, ≤2.5s at p75) and bundle cost. Is the LCP element discoverable by the preload scanner in the initial HTML — not injected by JS, not behind `data-src`? Never lazy-load the LCP image (`loading="lazy"` above the fold is always wrong). Flag a missing `fetchpriority="high"` on the LCP image, a render-blocking synchronous `<script>` in `<head>`, an LCP resource referenced only from CSS/JS with no `<link rel=preload as=image>`, and content-critical routes that wait on a client fetch instead of being server-rendered or prerendered. Weigh new dependencies and bundler/framework config changes for what they add to the critical path; code-split what is heavy and off the first paint.
7. Layout stability (CLS, ≤0.1 at p75). Media carries `width`/`height` or `aspect-ratio`. Injected content — banners, embeds, consent dialogs — reserves space and is not inserted above existing content. Web fonts use `font-display` other than `auto`/`block`, with metric-matched fallbacks (`size-adjust`, `ascent-override`) where the swap resizes text. Animate composited `transform`/`opacity`, not `top`/`left`/`box-shadow`. No `unload` handler or other bfcache disqualifier.
8. Browser/device compat: check each new web-platform API against Baseline (WebDX Community Group). "Limited availability" — not yet interoperable across Chrome, Edge, Firefox and Safari — needs a fallback or a stated exception; "Newly available" needs a conscious decision if the project targets "Widely available" (30 months post-interop). Name the feature and its Baseline status, or the finding is a `question`.

Scope note — you read a diff, not a running system: no CrUX, no Lighthouse run. Reason from code only. Per-soft-navigation LCP/INP/CLS (Soft Navigations API, unflagged from Chrome 151) is not yet part of Core Web Vitals or CrUX — do not grade against it.

**Blocker** = a state bug that renders wrong data or crashes a route, including an unguarded async race where a stale response can overwrite fresh data.
**Major** = an unhandled fetch failure; a render hot-spot on a common path; a Core Web Vitals regression on a user-facing route stated with a named code cause and a one-line fix — a lazy-loaded LCP image, media with no reserved dimensions, a blocking handler on a primary interaction. A performance claim without a named cause and fix is a `question`, not a Major.
Minor = worth fixing, doesn't gate. Prefer the smallest suggestion that resolves each finding.

## How this lens runs

Apply this lens where it helps verify the requested outcome. Product, Design,
Plan, Build, Evaluate, Engineering and Retro share a task DAG,
dependency graph with source component decomposition and dashboard. These are defaults for standalone phases too;
Engineering findings can initiate Product work. Use native tools and host permissions.
Delegate only when authorized and useful. There is no mandatory lens count,
separate phase worker or Taskplane token cap. Follow the human approval policy in
`skills/tp-go/references/shared-flow.md`: every phase needs explicit human checkpoint
acceptance. Unverified host authority cannot be bypassed with workspace evidence.


## Shared review evidence

Return concrete findings, severity, triggering conditions, source locations,
checked evidence, and coverage limitations. Use `agents/tp-lens.md` and attach
this evidence to the existing run and review index. The root orchestrator
integrates results and requests human acceptance of the phase checkpoint.
Review findings do not grant write scope or approve delivery.