# Pinned Source ↔ UI Map

All references below are to the source-clean detached worktree at
`249c2bceedaf3c04f76ae3a899d91acbf8dc2641`. Line numbers identify the audited
pin and may move in later versions.

## Frontend Files

| Source | Responsibility | Visible evidence |
| --- | --- | --- |
| `web/static/index.html:14–82` | Top bar, run controls, Gallery, event stream and current comparison. | Screenshots 03, 04, 12, 15 and 17. |
| `web/static/index.html:86–99` | Fullscreen target/reproduction comparison and sync/fit controls. | Screenshot 06. |
| `web/static/index.html:101–107` | Database overlay. | Screenshots 05 and 16. |
| `web/static/index.html:109–131` | Debug toolbar, modes, canvas and list. | Screenshots 07–09, 13 and 19. |
| `web/static/index.html:133–139` | Pipeline overlay. | Screenshots 10, 11, 14 and 18. |
| `web/static/app.js:5–21` | Client state, timer, status and stop behavior. | Status/stop state model. |
| `web/static/app.js:23–57` | Config display, 45-case loading and pointer selection. | Screenshots 03, 04 and 17. |
| `web/static/app.js:58–107` | Batch bar, concurrency cycle, batch poll/lead-job following. | Screenshot 04; source-confirmed run behavior. |
| `web/static/app.js:108–160` | Upload/single start, polling and final summary. | Screenshot 15; prior canary. |
| `web/static/app.js:166–220` | Event-to-card rendering for grounding, reasoning, tools, gate and errors. | Source-confirmed live stream; persisted events. |
| `web/static/app.js:222–238` | Fullscreen comparison and synchronized scrolling. | Screenshot 06. |
| `web/static/app.js:240–271` | Database count/grid/actions. | Screenshots 05 and 16. |
| `web/static/app.js:273–292` | Debug load and three-mode switch. | Screenshots 07–09. |
| `web/static/app.js:294–367` | Client recomputation from `code.html`, `grounding_assets.json` and events. | Screenshot 07/09 summary. |
| `web/static/app.js:369–443` | Debug summary, boxes, list, labels and cross-highlighting. | Screenshots 07–09. |
| `web/static/app.js:445–519` | Pipeline stage cards, per-epoch detail and frame comparison. | Screenshots 10, 11, 14 and 18. |
| `web/static/app.js:521–536` | Refresh reattachment to active batch/job. | `/current` evidence and source-confirmed behavior. |
| `web/static/style.css:1–166` | Desktop shell, Gallery, stream, gate, comparison and base responsive rule. | Screenshots 03, 04 and 12. |
| `web/static/style.css:168–311` | Batch, Database, Debug and Pipeline overlays. | Screenshots 05–14 and 16. |

## FastAPI Routes

| Route | Data contract | Frontend consumer | Study finding |
| --- | --- | --- | --- |
| `GET /models` | Agent/backbone/grounding/vision strings. | `loadModels`. | Read-only display despite `config` label. |
| `GET /cases` | Case, target URL, optional current render, accepted and epochs. | Gallery. | 45 cases; partial result/render combinations possible. |
| `POST /upload` | New upload-derived case and Job payload. | Hidden file input. | Upload immediately starts compute. |
| `POST /start` | New devset Job payload. | Whole case card. | Large pointer target starts compute immediately. |
| `GET /events/{job}` | Cursor events, status, final, start and target. | Live poller. | In-memory and unavailable after restart. |
| `POST /stop/{job}` | Cooperative stop request. | Stop button. | Kills active CLI process through Job control. |
| `GET /current` | Current job payload and/or batch id. | `resume`. | Refresh reattaches only while in-memory state exists. |
| `GET /db` | Every archive, display/base/delete ids and target/render URLs. | Database. | Good version accumulation; limited metadata. |
| `DELETE /db/{case~n}` | Recursive archive deletion. | Hover delete. | Destructive and no undo. |
| `GET /debug/{case}` | Rendered DOM boxes, grounded image boxes, strategy and summary. | Debug. | Base case resolves newest live workspace. |
| `GET /timeline/{case}` | Grounding, final render, verdict and epoch snapshots/metadata. | Pipeline. | Base case resolves newest live workspace. |
| `GET /log/{vid}` | Readable run log, event JSONL or epoch CLI stream; supports archive id. | No current frontend consumer. | High-value evidence is hidden from UI. |
| `POST /batch` | Batch id/items/status/concurrency. | Run selected. | 1–8 workers; no durable batch archive identity. |
| `GET /batch/{id}` | Batch progress and running job ids. | Batch poller. | UI follows one lead job. |
| `POST /batch/{id}/stop` | Sets batch stop flag. | Stop button. | Does not itself address every running Job in this handler. |
| `GET /artifacts/{case}/{path}` | File from newest live workspace or `_runs`. | Comparison/debug/pipeline. | Path traversal bounded to output root. |
| Static mounts | snapshots, devset and uploads. | Gallery/targets/uploads. | Protected by deployment wrapper. |

## Storage and Runtime Source

| Source | Responsibility | Relevance |
| --- | --- | --- |
| `config.py:93–123` | Devset/output names, artifact names and epoch limit. | Surface labels and required artifact contract. |
| `config.py:174–217` | Archive root, isolated run directories, retention and newest live resolver. | Data management and archive identity mismatch. |
| `web/jobs.py:23–66` | Job/event/control structure. | Live stream and Stop. |
| `web/jobs.py:71–103` | Completed-run archive copy. | Database durability and limited archived files. |
| `web/jobs.py:106–154` | Render-frame capture, runner sink and final status. | HTML replay feasibility. |
| `web/jobs.py:162–228` | Batch state and worker pool. | Multi-case run management. |

## Client-Corrected Debug Statistics

The server's case9 debug response reported 21 editable, 0 hidden, 0 crop and 0
inpaint. The visible Debug UI reported 21 editable, 0 hidden, 5 crop, 0 inpaint,
0 relative and 21 absolute. The difference is intentional client behavior:

1. Fetch final `code.html`, grounding assets and events.
2. Render `code.html` in a hidden iframe and inspect the actual computed
   positioning of every `data-gt` element and ancestor.
3. Find every image referenced by final HTML.
4. Classify referenced images as inpaint when named by an inpaint tool call;
   otherwise classify them as crop, including harness pre-crops that the server
   summary did not count.

This is a useful technique but also a contract smell: the displayed statistic
is not the `/debug` statistic. A unified manager should make derived-field
provenance explicit rather than silently overwrite meaning.

## Deployment Wrapper Map

The manager's `deployment/app.py` mounts the upstream app unchanged and adds:

- `/__login` and `/__logout`;
- authenticated `/healthz`;
- cookie/header authentication for every other upstream route;
- upload content-length cap;
- same-origin check for writes;
- security headers on authenticated downstream responses.

No file in the detached upstream worktree was changed for this deployment or
study.