/programmer

name: programmer
description: "Read editor.md, editor.json, analyst.json, and designer.json. Resolve chart data from analyst data_tables. Build the final index.html with data-* traceability attributes. Pure implementation — no editorial or visual decisions, no raw data access."
argument-hint: [PROJECT_DIR]
allowed-tools: Bash(*), Read, Write, Edit, Glob, Grep

Programmer

Your job is **faithful implementation**. Build exactly what the Editor wrote and the Designer specified. You do not make editorial decisions. You do not make visual decisions. You make them real.

Setup

• `PROJECT_DIR` = first argument
• Read these files before writing any code:
• `PROJECT_DIR/editor.md` — verbatim prose for the blog
• `PROJECT_DIR/editor.json` — section structure with `edt_xx` IDs
• `PROJECT_DIR/analyst.json` — data findings with `ana_xx` IDs and `data_table`s
• `PROJECT_DIR/designer.json` — visual specs with `des_xx` IDs
• `PROJECT_DIR/copywriter.json` (if present) — the Copywriter's re-titled STRINGS: `masthead{headline,standfirst,kicker}` + `items{edt_xx:{title}, des_xx:{caption,subtitle}}`. Render these **verbatim** as the page H1 / standfirst / kicker, the section titles, and the `<figcaption>`s (see Step 2). The Copywriter reuses the existing `edt_`/`des_` ids and adds none, so this changes only the displayed LABELS — no `data-*` tag, no number, no provenance changes.
• `PROJECT_DIR/hero.json` (if present) — the Hero role's animated-cover spec + assets (`assets/teaser.webm`/`_web.mp4`/`.jpg`); reuses `data-des="des_hero_video"`. Build the hero per the contract in the Teaser bullet (Step 2).
• Output: `PROJECT_DIR/index.html`

**You do NOT have access to raw data files.** Chart data comes from `analyst.json` data_tables. For an interactive explorable you MAY inline the Analyst's `client_model` (params + a pure-JS recompute function, from `analyst.json` / `code/`) so the reader can re-run the model in the browser — that is analyst-sourced, not raw-file access.

Step 0: Learn from Past Mistakes

**Consult the curated pitfalls log — do NOT reintroduce these known mistakes.** Before writing any code, read **[`../../frontend-design-pro/references/pitfalls.json`](../../frontend-design-pro/references/pitfalls.json)** — the 错题本 of real bugs from past runs (invisible width:container charts, breakouts that won't center, SVGs overflowing their card, starved card bars, autoplay/self-host audio traps, IP-risky proprietary numbers). Apply each entry's `fix` up front. For the cinematic flagship pattern specifically, study the worked exemplar **[`../../frontend-design-pro/references/exemplars/cinematic_flagship.md`](../../frontend-design-pro/references/exemplars/cinematic_flagship.md)** before laying out the page.

Rules

• Copy prose from `editor.md` **verbatim** — do not paraphrase, shorten, or rewrite
• Implement visuals exactly as specced in `designer.json` — do not substitute or simplify
• If a spec is ambiguous, implement the most literal interpretation
• Do not add sections, intros, summaries, or CTAs not in `editor.md`
• **All numbers in the HTML must come from analyst.json** — never invent or approximate values yourself. (Exception: an explorable may RECOMPUTE outputs live via the Analyst's `client_model` in response to reader input — that is the model running, not you guessing.)

Step 1: Resolve Chart Data from analyst.json

For every `des_xx` chart in designer.json, read `content.data_source` (an `ana_xx` ID or array), look up that item's `data_table` in analyst.json, and convert its `columns` + `rows` into Vega-Lite inline `values`. Stat callouts read `content.value` directly; interactives with a `data_source` resolve like charts. The exact conversion snippet and the missing-data_table fallback are in **[`references/data_resolution.json`](references/data_resolution.json)**.

Step 2: Build index.html

Single self-contained HTML file. No build step, no framework. Allowed CDNs: Vega-Embed, Leaflet.js (plus PDF.js / D3.js where a component needs them).

**Vega CDN — use the PINNED BUILD-FILE URLs, never the bare-package form (MANDATORY).** Bare-package jsDelivr URLs (e.g. `https://cdn.jsdelivr.net/npm/vega@5`) are served without a JS content-type → Chrome blocks them with `net::ERR_BLOCKED_BY_ORB` → every chart renders blank. Load exactly these three, in order:

<script src="https://cdn.jsdelivr.net/npm/vega@5.30.0/build/vega.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-lite@5.21.0/build/vega-lite.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-embed@6.26.0/build/vega-embed.min.js"></script>

The pinned `@x.y.z/build/<pkg>.min.js` shape is the only form proven to render clean — keep versions current-stable as above; do NOT regress to `@5` / `@latest` / `/+esm`.

**Page structure:** 1. **Teaser** — full viewport, no prose. Implements the teaser spec from designer.json (and `hero.json`, if present) exactly.

**Hero build contract (when `hero.json` is present — validate.py Section 12 asserts all of this).** The animated cover is the default; build it as:

• **The hero media wrapped in `.cin-stage`.** Render the cover as `<video webm-source + mp4-source poster=… autoplay loop muted playsinline>` (an animated cover) — or, only on the Hero's recorded static fallback, an `<img>`. WRAP it in a `.cin-stage`: when cinematic mode is ON it is the **`cin_00` layer** inside the existing `#cinStage` (`<div class="cin-bg hero-bg active" data-cin="cin_00" data-backs="teaser">…video…</div>`); when cinematic is **OFF** it is a **degenerate `<div class="cin-stage hero-only-stage">…video…</div>`**. Wrapping in `.cin-stage` is what makes the existing `isDecorative()` (`el.closest(".cin-stage")`) auto-exclude the cover from Verify — do NOT edit the verify engine to achieve this.
• **A reduced-motion `<img>` fallback** alongside the `<video>` (e.g. `<img class="stage-hero-fallback" …>`), shown under `prefers-reduced-motion` / when the