# Failure Field Guide

Each entry follows symptom → cause → diagnosis → fix → regression check.

## Hidden overflow from decoration

- **Symptom:** no scrollbar, but the browser audit reports a descendant outside the canvas.
- **Cause:** a pseudo-element or absolutely positioned ornament uses negative `right`/`bottom` values.
- **Diagnose:** inspect descendant bounds and pseudo-element rules on the failed page.
- **Fix:** keep decoration inside `inset:0`, clip it deliberately, or resize it without negative offsets.
- **Regression:** run desktop and fullscreen-like bounds checks.

## `[hidden]` pages remain in layout

- **Symptom:** multiple slides overlap or document size becomes several canvases tall.
- **Cause:** a more specific display rule overrides the browser’s `[hidden]` behavior.
- **Diagnose:** inspect computed `display` on an inactive slide/panel.
- **Fix:** add `.slide[hidden] { display:none; }` or `.assistant-panel[hidden] { display:none !important; }`.
- **Regression:** assert exactly one active slide outside print mode.

## Favicon 404 pollutes console

- **Symptom:** otherwise clean pages still report one failed request.
- **Cause:** the browser automatically requests `/favicon.ico`.
- **Diagnose:** inspect failed-request URLs.
- **Fix:** include an inline data-URI favicon.
- **Regression:** require zero failed requests on first load.

## PDF ignores 16:9 page size

- **Symptom:** PDF is Letter/A4, clipped, or has unexpected margins.
- **Cause:** missing `@page` or PDF generation did not prefer CSS page size.
- **Diagnose:** inspect PDF media boxes and print CSS.
- **Fix:** set `@page { size:16in 9in; margin:0; }` and enable CSS page size.
- **Regression:** compare PDF page dimensions and count with the manifest.

## Mobile controls cover content

- **Symptom:** the last lines or buttons cannot be read on a phone.
- **Cause:** fixed navigation occupies space that mobile content did not reserve.
- **Diagnose:** compare the last visible element’s bottom with the controls’ top.
- **Fix:** add mobile bottom padding and reduce/hide secondary controls.
- **Regression:** audit a 390×844 viewport on the densest page.

## Fullscreen breaks events or IDs

- **Symptom:** navigation/assistant works normally but fails in fullscreen; duplicate-ID warnings appear.
- **Cause:** fullscreen was implemented by cloning deck DOM.
- **Diagnose:** count IDs and inspect event targets after entering fullscreen.
- **Fix:** fullscreen the original `deckFrame` element.
- **Regression:** exercise keyboard, navigation, and assistant in fullscreen.

## Mechanical card-grid rhythm

- **Symptom:** every thumbnail looks like the same 3–4 cards.
- **Cause:** components were chosen by convenience, not communication task.
- **Diagnose:** review the desktop contact sheet at thumbnail scale.
- **Fix:** alternate statement, relationship, table, case, chapter, and exercise structures as content requires.
- **Regression:** no long run of visually identical information pages without a content reason.

## Generated image contains wrong Chinese

- **Symptom:** labels are malformed or semantically wrong.
- **Cause:** generated imagery was asked to render exact text.
- **Diagnose:** compare every visible label with the approved copy.
- **Fix:** keep generated images text-free; overlay live HTML/SVG labels.
- **Regression:** text remains searchable and matches the manifest/source.

## Global CSS leaks across page types

- **Symptom:** changing one page shifts typography or layout on unrelated pages.
- **Cause:** broad selectors such as `article`, `svg`, or `.card` are unscoped.
- **Diagnose:** use computed-style provenance on the unexpected property.
- **Fix:** scope rules under the page-type class and use component-specific names.
- **Regression:** screenshot-diff representative pages from every family.

## Tiny fonts hide content overload

- **Symptom:** overflow passes but projection text is unreadable.
- **Cause:** font sizes were reduced instead of splitting the page.
- **Diagnose:** inspect minimum visible font size and occupancy.
- **Fix:** split the page, compress wording only with approval, or move detail to notes.
- **Regression:** enforce minimum font thresholds and review at projected size.

## Assistant fails: key, CORS, file protocol, rate, timeout

- **Symptom:** assistant shows network errors or no response.
- **Cause:** missing/invalid credential, browser CORS policy, `file://`, rate limiting, or slow endpoint.
- **Diagnose:** use the explicit status message and browser Network panel.
- **Fix:** verify preset/base URL/model, use a local HTTP server, add an approved proxy when required, wait after 429, and reduce timeout load.
- **Regression:** test missing config, 401/403, 429, timeout, empty response, and success; never ship a key.

## Remote font/script/image fails onsite

- **Symptom:** classroom computer shows fallback fonts, blank images, or broken controls.
- **Cause:** runtime depends on the public network.
- **Diagnose:** disconnect network and reload while watching failed requests.
- **Fix:** bundle licensed/local assets and use system-font fallbacks.
- **Regression:** static audit remote dependencies and run an offline smoke test.

## Manifest, HTML, screenshots, and package drift

- **Symptom:** page counts/order differ between source, evidence, PDF, or ZIP.
- **Cause:** artifacts were regenerated selectively after structural edits.
- **Diagnose:** compare manifest IDs, `data-page-id`, report page IDs, PDF count, and archive files.
- **Fix:** rerun the entire validation → audit → render → package chain.
- **Regression:** package only after fresh passing reports.

## Element outside canvas without scroll overflow

- **Symptom:** `scrollWidth` equals `clientWidth`, yet content is visibly clipped.
- **Cause:** absolutely positioned descendants do not always change scroll metrics.
- **Diagnose:** compare every visible descendant rectangle with the slide rectangle.
- **Fix:** adjust anchoring, size, or clipping boundary.
- **Regression:** keep both scroll and descendant-bounds checks.

## Screen and print thresholds conflict

- **Symptom:** a print-only page fails screen font/overflow rules or vice versa.
- **Cause:** one threshold set was applied to different layout modes.
- **Diagnose:** record the active media mode with each finding.
- **Fix:** use mode-specific assertions; print validates page box/count/clipping, screen validates viewport interaction.
- **Regression:** reports must identify mode for every issue.
