docs/FRONTEND.md

SatQuery AI — Frontend

Chapter scope. This chapter documents the SatQuery AI web frontend end to end: the static tier and every page in it, the staging and deploy path that publishes it, the Analyze console in full depth (every DOM handle, every state, every event), the eight-event execution protocol and the trace bar it drives, the REAL-vs-PREVIEW driver split, the captured-run page, the Hugging Face header link, cache-busting, and the Cloudflare platform traps that shape all of the above.

Grounding. Every claim below is taken from a file that was read for this chapter. Where a claim comes from code, the file is cited inline, e.g. (frontend/assets/js/mission.js). Where a number is quoted it is a number that appears in a file; none is estimated. Where the evidence does not exist, the text says exactly: UNKNOWN — not established from the available evidence.

Status vocabulary follows release/DOCS_STYLE_GUIDE.md §2: IMPLEMENTED · VERIFIED · MEASURED · ATTEMPTED · NOT RUN · BLOCKED · DEFERRED · REJECTED · OPEN · RESOLVED · CLOSED.

Nothing in this chapter is a system-level accuracy claim. Per release/DOCS_STYLE_GUIDE.md §3 there is no end-to-end benchmark for SatQuery AI; the frontend is a client of the service, and the only system-level numbers quoted here are the ones the delivery documents themselves recorded (live validation 3 passes × 8 cases, 8/8 each, 24 runs, 0 mock nodes, trace fill 94.4444 %).

---

1. What the frontend is, and what it is not

SatQuery AI's frontend is a static site. It is HTML, CSS, and ES modules served from Cloudflare Pages. There is no build step that compiles application code, no bundler, no framework, no server rendering, and no runtime dependency on a Node process. The staging tool (scripts/stage_pages.mjs) copies a reference-closed subset of frontend/ into an output directory and then hands that directory to wrangler.

The site is hermetic except for one page. The staging tool computes and prints a reference integrity and external-dependency audit, and it reports HERMETIC when a page's reference closure contains zero network dependencies (scripts/stage_pages.mjs). The single deliberate exception is frontend/mission.html, the Analyze console, which carries a live API base in a <meta> tag and can call the deployed service. Everything else — the homepage, the essay, the atlas, the architecture tour, the benchmark and research pages, the captured-run page — is designed to render without any network call beyond its own assets.

Honesty note (drift recorded, not hidden). An older comment inside frontend/_headers claimed the site was "100% static, zero network calls". That claim is stale and is not repeated here as current truth: mission.html is a live-calling page, and mission.html is one of the eleven shipped pages. The correct current statement is: ten of eleven pages are hermetic; mission.html is the one live-calling page.

1.1 The design law the frontend was built under

frontend/HANDOFF.md is the governing design document for the frontend. Its §1 states the design law; §2 defines the token system as CSS custom properties on :root; §3–§10 lay out build phases A–G; §9 names the integration seam (SQ.run().ingest); §13 lists known hard limits; §14 lists the real SatQuery schema type names that the frontend is allowed to speak.

The practical consequences of that design law, as they appear in the shipped code:

• No fabricated imagery is presented as real. Synthetic imagery produced at runtime carries a synthetic: true flag (frontend/assets/js/core.js, SQ.scene), and pages that use placeholder numbers say so in their own prose (e.g. frontend/atlas.html states its numbers are placeholders).
• The eight-event vocabulary is fixed. The frontend may not invent event names; it emits exactly the eight names declared in SQ.EVENT_NAMES (frontend/assets/js/core.js).
• The event stream is the seam. Any driver — mock, live, or a captured replay — talks to the UI only by calling ingest(type, payload). Nothing else may mutate the console.

---

2. The static tier: file layout

The shipped frontend is a flat set of pages plus three asset trees.

frontend/
  *.html                      top-level pages (the staging seed set)
  _headers                    Cloudflare Pages header rules (see §12)
  HANDOFF.md                  the frontend design/handoff document
  assets/
    css/                      stylesheets
    js/
      core.js                 SQ namespace: rng, scene synthesis, policy router,
                              event names, mock run driver, shared components
      live.js                 the real HTTP ingestion client (assets + infer)
      mission.js              the Analyze console driver (PREVIEW + LIVE)
      run.js                  the captured-run ("Anatomy of a Run") driver
      <page drivers>          per-page behaviour
    data/
      anatomy-run.js          the captured real ResultEnvelope (sanitized)
    img/                      real EO imagery (eo/…), plates, thumbnails
    video/                    the launch film and clips
    fonts/                    webfonts

Two facts about this layout matter for deployment:

1. The staging seed is the set of top-level frontend/*.html files (scripts/stage_pages.mjs). Pages are discovered from HTML, and then their reference closure (CSS @import/url(), JS import/export … from, and dynamic imports) is walked so that only referenced assets ship.
2. Because the closure is reference-driven, an asset that is not referenced by a reachable page does not ship. This is deliberate: it keeps the uploaded tree small and it makes dead assets visible (they simply do not appear in the staged tree report).

---

3. The eleven pages

Eleven HTML pages ship. Each was read for this chapter. The table gives the page's purpose and its data-view (the attribute each page's <body> carries, which the CSS uses to scope page-specific rules).

#	File	Purpose	Notes
1	frontend/index.html	Homepage / front door. Orbit hero, invitation form, open questions, essay film, discover/evidence/understand/measure/atlas sections.	Carries the launch video and the delta pair.
2	frontend/mission.html	The Analyze console. Query box, two upload widgets, intent panel, viewer, comparison, answer, evidence, confidence, provenance, trace bar, event drawer.	The only live-calling page. Carries <meta name="satquery-api-base">.
3	frontend/architecture.html	Architecture tour: how a query becomes an answer, stage by stage.	Footer discloses that its transmission is driven by the prototype mock event stream.
4	frontend/run.html	Anatomy of a Run — renders a real captured ResultEnvelope (run_d124d8b9adea).	Driven by frontend/assets/js/run.js over frontend/assets/data/anatomy-run.js.
5	frontend/benchmark.html	Benchmark page: measured results with an evidence-state legend.	Legend vocabulary: VERIFIED / SUPPORTED / UNVERIFIED / BLOCKED / NOT RUN.
6	frontend/research.html	Research notes: methods, calibration, honest caveats.	Links into the measurement story.
7	frontend/journey.html	The build journey / narrative page.	Carries the HF + GitHub header links.
8	frontend/atlas.html	Atlas of four real EO thumbnails.	Page states its numbers are placeholders.
9	frontend/references.html	References / citations page.	—
10	frontend/video.html	Video library: four clips, three planned shorts named.	—
11	frontend/404.html	Not-found page.	Prose says "Ten pages exist" but links five — drift, recorded in §13.

3.1 Page-by-page detail

index.html (homepage). 424 lines. Structure: a navigation bar carrying the GitHub and Hugging Face links; an orbit hero using assets/img/eo/nile-wide.jpg; an invitation form whose action is mission.html; an "open questions" list containing three mission.html?q=… links (so a visitor can land in the Analyze console with a question pre-filled); an essay-film section using assets/video/satquery-launch-50s.mp4 with eight data-chapters markers; an "ask" section using assets/img/eo/delta-plain.jpg; a "discover" section that presents the delta-growth t0/t1 pair as a wipe slider (delta-growth-t0-720 / delta-growth-t1-720); an "evidence" section using delta-growth-t2-2075.jpg; an "understand" section listing six layers; a "measure" section with benchmark and research cards; and an "atlas" section with four real EO thumbnails. The footer notes name the event span QUERY_RECEIVED → RESULT_ASSEMBLED, i.e. the first and last of the eight events.

mission.html (Analyze console). 297 lines. This is the page this chapter spends most of its length on; see §5.

architecture.html. The architecture tour. It walks the reader from a natural-language query through routing, planning, specialists, evidence, confidence, and result assembly. Its footer makes an explicit honesty disclosure: the transmission shown on the page is driven by the prototype mock event stream, not by a live run. That disclosure is the page doing the right thing — the animation is real UI driven by the same eight-event seam, but the data behind it on this page is the mock driver's.

run.html ("Anatomy of a Run"). Renders a real captured envelope. See §9.

benchmark.html. Presents measured results. It carries an evidence-state legend whose vocabulary is VERIFIED / SUPPORTED / UNVERIFIED / BLOCKED / NOT RUN, and it notes the measured reliability curve. Per release/DOCS_STYLE_GUIDE.md §3, this page is the right place for the per-artifact numbers (grounding under two protocols, change IoU, optical-SAR accuracy-with-macro-F1, change-VQA two test sets, router validation-only), and it must never present them as a system-level score.

research.html. Research notes: method, calibration, and caveats. This is where the calibration result belongs, and per the style guide it must be stated correctly: ECE went 0.013755 → 0.014929 — worse, and the transform is retained only because it is in the frozen config.

journey.html. Narrative page for the build process.

atlas.html. Four real EO thumbnails. The page states in its own prose that its numbers are placeholders. That statement is correct and must be preserved: the atlas is a gallery, not a measurement.

references.html. Citations.

video.html. Lists four clips and names three planned shorts. The planned shorts are labelled as planned, not shipped.

404.html. The not-found page. Its prose says "Ten pages exist" while eleven do, and it links five. This is documentation drift inside a shipped page; it is recorded here and in §13 rather than silently corrected, because correcting it would be an edit outside this chapter's scope.

3.2 The Hugging Face header link — present on all eleven pages

Every one of the eleven pages carries, in its navigation, both:

• a GitHub link to https://github.com/Anish-lab-blip/SatQuery-AI, and
• a Hugging Face link to https://huggingface.co/thundercode/SatQuery.

This was verified by searching all frontend/*.html for huggingface.co and github.com and confirming a match in each of: index, journey, mission, 404, video, atlas, architecture, benchmark, run, research, references — eleven files, eleven matches each. docs/FINAL_DELIVERY_TODO.md records this as a post-handoff sprint outcome ("the HF link on all 11 pages").

The reason this is called out as its own subsection: the public release is GitHub + Hugging Face, and the requirement that the HF link appear on all pages (not just the homepage) is a delivery requirement, so it is stated as a verified fact with the method of verification.

---

4. Staging and deploy path

4.1 scripts/stage_pages.mjs — the reference-closed staging tool

scripts/stage_pages.mjs is 378 lines and is the tool that turns the working frontend/ directory into a deployable tree. It is deliberately conservative.

Constants.

Constant	Value	Meaning
PAGES_FILE_LIMIT	26214400 (25 MiB)	Cloudflare Pages per-file hard limit.
BIG_WARN_BYTES	10485760 (10 MiB)	Warn threshold for a large file.

Reference extraction. The tool uses a small set of regexes to find references inside each file type:

• RE_HTML — HTML references (<script src>, <link href>, <img src>, etc.)
• RE_CSS_IMPORT — CSS @import
• RE_CSS_URL — CSS url(...)
• RE_JS_IMPORT — JS import … from
• RE_JS_EXPORT — JS export … from
• RE_JS_DYN — JS dynamic import(...)

Supporting helpers: stripComments() (so a reference inside a comment does not become a false edge), extractRefs(), isExternal() (absolute URLs and protocol-relative URLs are not followed), stripQueryHash() (so app.js?v=2 resolves to app.js), and insideFrontend() (a guard so a reference cannot escape the frontend/ root).

Algorithm.

1. Seed. Take the set of top-level frontend/*.html files.
2. Closure walk. For each file in the frontier, extract its references, resolve each to a path inside frontend/, and add the new ones to the frontier. Repeat until the frontier is empty.
3. Copy. Copy every file in the closure into the output root, preserving relative paths.
4. Size gate. If any file exceeds PAGES_FILE_LIMIT (25 MiB), hard-fail with exit code 2. Files above BIG_WARN_BYTES (10 MiB) produce a warning.
5. Verify. Re-walk the staged tree and confirm the closure is intact (no dangling reference). Failure is exit code 3.
6. Report. Print four report blocks:
   • === STAGED TREE ===
   • === REFERENCE INTEGRITY ===
   • === EXTERNAL DEPENDENCY AUDIT === — prints HERMETIC when zero network dependencies are found.
   • === OPTIONS APPLIED ===
7. Hint. Print the deploy command to run next: npx wrangler pages deploy "<OUT_ROOT>" --project-name <name>.

Why the exit codes matter. A staging run that silently produced an incomplete tree would deploy a broken site; a staging run that silently produced an over-limit tree would deploy a site that Cloudflare rejects. The tool therefore fails loudly before upload (exit 2 for size, exit 3 for integrity) rather than letting wrangler discover the problem.

Argument parsing. parseArgs() handles the CLI surface and usage() prints help. The tool is invoked as a Node script (node scripts/stage_pages.mjs …).

4.2 The deploy command

The tool's own final hint is the deploy step:

npx wrangler pages deploy "<OUT_ROOT>" --project-name <name>

Deployment is therefore: stage to a directory → wrangler pages deploy that directory. There is no compile step between the two. The deployed frontend HEAD recorded in the delivery documents is 2d7ae53b482d (docs/FINAL_DELIVERY_TODO.md, release/DOCS_STYLE_GUIDE.md §3).

Superseded-topology note. docs/DEPLOYMENT_ARCHITECTURE.md opens with a superseded-topology banner, and its body still names Railway / HF-Space hosts while the active topology is Render / Codespace (docs/DEPLOYMENT_TOPOLOGY.md). For the frontend specifically, the host is Cloudflare Pages in both readings; the drift concerns the backend hosts, not the static tier.

---

5. The Analyze console (frontend/mission.html) in depth

The Analyze console is the frontend's centre of gravity. This section documents its markup (every handle), its state machine, its two drivers, and its event rendering.

5.1 Markup and DOM handles

frontend/mission.html is 297 lines. Its <head> carries the live API base:

<meta name="satquery-api-base" content="https://<backend-host>">

That meta tag is the second entry in the API-base resolution order (see §5.4). The page loads three scripts, in order:

<script src="assets/js/core.js"></script>
<script src="assets/js/live.js"></script>
<script src="assets/js/mission.js"></script>

core.js defines the SQ namespace and the mock driver; live.js defines the real HTTP client; mission.js is the page driver that decides which of the two to use. The load order is significant: mission.js runs last because it consumes both.

The console's handles, by region:

Query and run.

Handle	Role
#qtext	The natural-language query input.
#btnRun	The Run button.
#runid	Displays the run identifier for the current run.

Observation / upload.

Handle	Role
#obsTail	The observation status tail. Its initial text content is none — i.e. no asset loaded yet.
#dropZone	The drop target for a file.
#fileInput	The primary file input (the single observation).
#obsNote	The note under the observation widget.

Metadata.

Handle	Role
#metaHost	Container for the metadata readout.
#mFile	Metadata: file name.
#mAcq	Metadata: acquisition date (one of the #m* fields inside #metaHost).
#metaEmpty	The empty-state placeholder for the metadata block.

Intent panel.

Handle	Role
#intentTail	Intent status tail.
#intentHost	Container for the parsed intent (task, assets, route).
#pairTail	Pair status tail (for the two-asset change tasks).
#pairNote	Note under the pair widget.
#fileInputT0	The second file input — the t0 (before) image for paired tasks.

Viewer.

Handle	Role
#vbtns	Viewer mode buttons.
#viewerState	Viewer state label.
#plate	The plate container.
#plateImg	The plate image; its src is assets/img/eo/reservoir-low.jpg.
#ev	The evidence overlay layer on the plate.
#evNote	Note under the evidence overlay.
#plateCreditLead	Plate credit lead-in text.
#plateCredit	Plate credit text.

Comparison (paired tasks).

Handle	Role
#cmpWrap	Comparison wrapper.
#cmpT0	The t0 pane.
#cmpT1	The t1 pane.
#cmpRange	The comparison range/slider control.
#cmpCredit	Comparison credit.
#cmpEmpty	Comparison empty state.

Answer.

Handle	Role
#answerHost	Container for the rendered answer.
#ansTail	Answer status tail.

Evidence.

Handle	Role
#evHost	Container for the evidence list.
#evEmpty	Evidence empty state.
#evTail	Evidence status tail.

Confidence.

Handle	Role
#confHost	Container for the confidence readout.
#confC	The confidence value.
#confNote	Note under the confidence value.

Provenance.

Handle	Role
#provHost	Container for provenance.
#pRun	Provenance: run id.
#pPolicy	Provenance: policy.
#pProtocol	Provenance: protocol.
#pSchema	Provenance: schema version.

Report and trace.

Handle	Role
#btnReport	The report button.
#ctrace	The trace container.
#traceNow	The "now" label on the trace bar.
#trace	The trace bar (the element whose width is animated).
#traceNote	Note under the trace bar.

Event drawer.

Handle	Role
#drawer	The event-log drawer.
#evlog	The event log list.
#btnClose	Close-drawer button.
#btnEvents	Open-drawer button.

5.2 The intent panel

The intent panel (#intentHost, #intentTail) is rendered by renderIntent() in frontend/assets/js/mission.js. It shows the interpreted query: which task the router chose, which assets the task requires, and which route (live vs mock) will be taken.

The interpretation itself is interpret() in mission.js — a lexical router that runs in the browser. Its notable features, as read from the file:

• a change stem /chang/ (no \b word boundary) so "change"/"changed"/"changes" all match;
• a newAsChange rule so phrasing like "new …" can be read as a change request;
• a caption regex for caption/describe phrasings.

interpret() is deliberately simple and deterministic. It exists so the console can show the user a reason for the task it is about to run, and so the console can decide which file inputs are relevant. It is not the server-side router: the server has its own deterministic policy planner (see the SERVING.md chapter and core/controller.py). The browser-side interpret() is a UI affordance; the authoritative routing decision is the server's, and the console renders what the server returns.

5.3 Task selection and asset requirements

mission.js maps the interpreted intent onto a server task name via ROUTE_TASK_TO_SERVER. The paired tasks are declared in PAIRED_TASKS:

PAIRED_TASKS = { change, change_vqa, optical_sar }

These three tasks need two assets (a before/after pair), which is why the console has a second file input (#fileInputT0) and a comparison region (#cmpWrap). When a paired task is selected but only one asset is available, the console falls back to a single-asset task via SINGLE_ASSET_FALLBACK = 'vqa'. This is a UI-level fallback: rather than failing the run, the console narrows the request to something one image can answer.

For optical-SAR there is a dedicated precondition check, validateOpticalSar(), because that task has modality-specific requirements. assetsForTask() assembles the asset list the chosen task needs.

5.4 API-base resolution

frontend/assets/js/live.js defines the resolution order for the API base in SQ.live.baseUrl():

1. window.SATQUERY_API_BASE (a runtime override, useful for testing), then
2. <meta name="satquery-api-base"> (the page's declared base — on mission.html this is https://<backend-host>), then
3. the default /api (a same-origin path).

_normalizeBase() normalises trailing slashes, and SQ.live.url() composes the final URL. SQ.ENDPOINTS names the four endpoints the client talks to:

SQ.ENDPOINTS = { assets: '/assets', infer: '/infer', capabilities: '/capabilities', health: '/health' }

With the default /api base these resolve to /api/assets, /api/infer, /api/capabilities, and /api/health. On the deployed configuration the base is the Render orchestrator host, which is the /api/* mirror of the four-endpoint contract (see the SERVING.md chapter).

5.5 Upload widgets

Two file inputs exist: #fileInput (primary) and #fileInputT0 (the before image for paired tasks). Both are wired through handleFile() in mission.js, and both feed SQ.live.uploadAsset() in live.js.

live.js declares the accepted content types:

SQ.CONTENT_TYPES = { tif, tiff, png, jpg, jpeg }

and maps a file to its MIME type via SQ.contentTypeFor(). The upload is a raw-bytes POST with a Content-Type header — not a multipart form. This mirrors the server contract: POST /v1/assets takes the file as the request body with its content type in the header, and POST /v1/analyze takes JSON (multipart is explicitly not implemented — see docs/API_CONTRACT.md §2.4 and the SERVING.md chapter).

uploadAsset() asserts that the response contains an asset_id; uploadAssets() uploads a list sequentially (so the second upload cannot race the first). The returned asset_id is an opaque handle — the client never parses it, it only passes it back. The asset store's TTL and the fact that handles are ephemeral are documented in SERVING.md.

5.6 The observation tail: none → ready

#obsTail starts with text content none. When an asset is uploaded successfully, the tail is updated to a ready state. This is the console's way of making the precondition for a run visible: a query can be typed at any time, but a run that requires an asset cannot produce evidence until an asset is present. The #obsNote field carries the supporting note.

5.7 The Run button, #runid, and #answerHost

Pressing #btnRun calls runQuery() in mission.js. runQuery() decides between the two drivers (§6) and then dispatches. #runid is populated with the run identifier the service returns (run_…); #answerHost receives the rendered answer.

5.8 The trace bar and the eight events

The console's most load-bearing UI element is the trace bar. It is driven entirely by the eight execution events.

The eight event names are declared once, in frontend/assets/js/core.js:

SQ.EVENT_NAMES = [
  'QUERY_RECEIVED',
  'QUERY_UNDERSTOOD',
  'ROUTE_SELECTED',
  'SPECIALIST_STARTED',
  'SPECIALIST_COMPLETED',
  'EVIDENCE_GENERATED',
  'CONFIDENCE_COMPUTED',
  'RESULT_ASSEMBLED'
]

(Declared at core.js:616–620.) These names are the protocol between any driver and the UI. The architecture.html footer's disclosure — that its transmission is driven by the mock event stream — is a statement about which driver feeds these names, not about the names themselves.

The nine UI states. mission.js declares STATES (nine ControllerState values) and maps each event to a state via EVENT_TO_STATE, with per-state explanatory text in STATE_NOTE. Nine states over eight events is not an inconsistency: there is a state for "idle / not started" plus the eight event-driven states.

The fill formula. markState() sets the trace bar width with:

traceFill.style.width = ((traceProgress + 0.5) / STATES.length) * 100 + '%'

With eight events completed against nine states, the final fill is ((8 + 0.5) / 9) × 100 = 94.4444 %. This is why the delivery documents record the trace fill as 94.4444 %: it is the arithmetic consequence of the formula, not a measurement of a rendering. The + 0.5 means the bar advances half a step on entry to each state, so a completed eight-event run lands at 8.5/9 rather than 8/9 or 9/9. The remaining 5.5556 % corresponds to the ninth state, which a completed run does not enter.

buildTrace() constructs the trace bar's segments; logEvent() appends to the event log (#evlog); resetUI() clears the console back to its initial state (including resetting #obsTail to none).

5.9 The event drawer

#drawer is the event log, opened by #btnEvents and closed by #btnClose. #evlog is the list itself. Each event appended by logEvent() records the event type and its payload summary, so a reader can see the full ordered sequence rather than only the current state. The drawer is what makes the "0 mock nodes" / "9 preview nodes" distinction auditable by a human: the live driver's log contains no mock nodes; the preview driver's log contains nine.

---

6. REAL vs PREVIEW: two drivers, one event seam

mission.js opens with the comment "TWO DRIVERS, ONE EVENT SEAM". That is the whole design: two driver implementations, one ingest() seam, one UI.

6.1 The seam

SQ.run(opts) in core.js owns an ingest() switch (lines ~742–788) that dispatches each of the eight event types to the UI handlers. Any driver that wants to drive the console calls ingest(type, payload); it does not touch the DOM. The console boot sequence builds the engine with engine = SQ.run(...), then calls runMock(QUERY) to paint an initial state, then loadCapabilities() to fetch the service's capability block.

6.2 PREVIEW (runMock)

runMock() is the preview driver. Its properties, as read from mission.js and core.js:

• It emits empty payloads — the payloads carry the shape of the data but not real values, because there is no real run behind it.
• It labels the console as a preview (is-mock).
• It emits nine mock nodes — the event log for a preview run contains nine mock nodes.
• It drives the trace bar through the same markState() path, so the fill arithmetic is identical.

core.js's startMock() drives the sequence with setTimeout timings, so the preview is animated: each event arrives after a short delay, which is what makes the trace bar and the event drawer move.

What preview does not emit. The preview driver emits no specialist events — i.e. no SPECIALIST_STARTED / SPECIALIST_COMPLETED for a real specialist. This is the honest distinction between the two paths: the preview can show the envelope of a run, but it cannot show a specialist that actually ran, because no specialist ran.

6.3 REAL (runLive)

runLive() is the live driver. Its properties:

• It makes real HTTP calls via SQ.live (live.js).
• It sets a liveRun flag.
• It reads two response headers from SQ.live.infer(): X-SatQuery-State and x-satquery-transport. The state header carries the controller's state (see the nine ControllerState values); the transport header records how the response was carried (the tunnel transport vs a direct/forwarded transport).
• It translates failures with translateError() and, for upload/inference failures, SQ.live.describeFailure() / LiveError in live.js.
• A live run shows 0 mock nodes — the event log contains no mock nodes at all.

6.4 Why the 0-vs-9 distinction is the honesty test

The delivery documents record that live validation produced 24 runs (3 passes × 8 cases, 8/8 each) with 0 mock nodes. That number is only meaningful because the preview path does produce mock nodes (nine of them). The console's event drawer therefore lets a reader distinguish, from the UI alone, whether what they are looking at is a real run or a preview. This is the frontend's contribution to the project's truthfulness discipline: the same eight-event vocabulary is used for both, and the drawer is what tells them apart.

6.5 loadCapabilities() and setMode()

loadCapabilities() calls SQ.live.capabilities() (i.e. GET /api/capabilities on the deployed base) and renders the capability block. setMode() switches the console between modes. Because capabilities are fetched live, the console can show which tasks are available right now on the deployed service — which matters because the deployed device is CPU and because some capabilities are gated on artifacts that may be absent (the SERVING.md chapter documents the capability adapter and the five-word vocabulary it emits).

6.6 The test hook

mission.js exposes window.SQ_MISSION as a test hook. It lets an automated harness drive the console (select a task, inject a file, press run) without synthesising DOM events. This is how the live validation runs in the delivery documents were executed against the page.

6.7 translateError()

translateError() maps a service error into human-readable text in the console. It is the frontend half of the error contract: the service returns a machine code and an HTTP status (docs/API_CONTRACT.md §5.1–§5.3; gateway/policy.py _CODE_STATUS), and the console turns that into a sentence a person can act on. The console does not invent codes; it renders the ones it receives. One consequence worth stating: a 422 from the service is not necessarily a validation failure of the user's data — see the G-1 annotation-scope defect in the SERVING.md chapter, where a 422 {"detail":[{"loc":["query","request"]}]} is a server-side bug that masquerades as a client validation error. translateError() will render it as an error; only the backend fix removes it.

---

7. The captured-run page: "Anatomy of a Run" (run.html)

frontend/run.html renders a real captured ResultEnvelope. This is the page that lets a reader inspect an actual run without running anything.

7.1 The captured envelope

The data lives in frontend/assets/data/anatomy-run.js (329 lines), assigned to window.SATQUERY_ANATOMY_RUN. Its header states the provenance:

• _source: "Captured live 2026-09-25 … Sanitized".

The fields that matter, all read from the file:

Field	Value
run_id	run_d124d8b9adea
task	grounding
query	"Where is the reservoir?"
answer	"[grounding] Located 3 candidate region(s) … Highest objectness 0.61."
config_hash	78f1e3700da15aa1
transport	tunnel
intent.source	forced
plan	step_001 grounding, requires_assets
steps	8 steps, RECEIVE → RESPOND
selected_models	ViT-B-32 (RemoteCLIP path) → GroundingHead (params=1052677)
evidence	4 items: 3 bounding_box + 1 statistic
regions	3 (region_1cd3973de749, …)
confidence	raw 0.5231253252136926 / calibrated 0.5236623182649384 (temperature_scaling)
calibration component	temperature: 0.9772731820958189, calibration_samples: 16441.0
timings	step_001: 209.873
geospatial	730×730, has_crs false
warnings	2 — no CRS; contradictory spatial claims

7.2 How the page renders it

frontend/assets/js/run.js (380 lines) is the driver. It reads window.SATQUERY_ANATOMY_RUN and exposes the envelope through a set of named views: QUERY, TASK, RUN_ID, MODELS, EVIDENCE, CONF, TIMINGS, GEO, INTENT, PLAN, HASH, PLATE.

• REGIONS is built from A.regions, so the three captured regions drive the plate overlays.
• paintAll() loads the real plate image and clears the t0 and diff layers (this run has no before/after pair, so those layers are empty rather than faked).
• buildEvidence() renders the four evidence items; evCandidates(), evLock(), and evConfirmed() render the three stages of the evidence story (candidates → locked → confirmed).
• SPECIALISTS_FOR_TASK maps the task to the specialists that would run, so the page can show the specialist panel even though this run's only specialist is grounding.
• buildLattice() builds the step lattice from the 8 captured steps.
• DATA is a table of eight key/value views, one per stage, and each entry names the event that corresponds to that stage — i.e. the captured page is wired to the same eight-event vocabulary.
• setStage(), resetEvidence(), and gotoStep() drive the page as the reader scrolls or uses the keyboard.

7.3 What the page proves, and what it does not

It proves: a real grounding run was captured, sanitized, and shipped with its full envelope — run id, task, query, answer, config hash, transport, intent source, plan, steps, selected models with parameter counts, evidence with types, regions, raw and calibrated confidence with the calibration component and sample count, timings, geospatial facts, and warnings. A reader can verify that the number shown as "confidence" on the page is a calibrated value with a documented temperature and a documented calibration-sample count.

It does not prove: any system-level accuracy. One captured run is one run. Per release/DOCS_STYLE_GUIDE.md §3 there is no end-to-end benchmark, and this page does not create one. The calibrated confidence 0.5236623182649384 is a per-run confidence, not an accuracy.

The two captured warnings are also part of the honest record: has_crs false (the imagery had no coordinate reference system) and "contradictory spatial claims". Both are shown rather than suppressed.

---

8. Benchmark, Research, and Lab pages

The frontend has a measurement-facing tier whose job is to present numbers with their status.

• benchmark.html carries the evidence-state legend: VERIFIED / SUPPORTED / UNVERIFIED / BLOCKED / NOT RUN. It notes the measured reliability curve. This page is where the per-artifact results live, and per the style guide each must be stated with its correct qualification: grounding under two protocols (canonical 0.2838 / matched6 0.2566) and two decode variants (head_argmax 0.1215, zero-shot 0.0972) — never one alone; optical-SAR accuracy 0.931 with macro-F1 0.434161, ruling OPEN; change-VQA two test sets (test 0.697626/0.378373 and test2 0.651469/0.372309), ruling OPEN; router 0.965116 = validation, ungated, n = 86, test split NOT RUN; the VLM adapter usable (exact_match 0.963) but ACCEPTANCE-REJECTED.
• research.html carries the method and caveat material, including the calibration result stated correctly: ECE 0.013755 → 0.014929 — worse.
• The Lab page. The brief for this chapter names a "Lab" page. frontend/HANDOFF.md §12 gives the file map, and the eleven shipped pages are enumerated in §3 above. A page named "Lab" is not among the eleven HTML files read for this chapter. The nearest things are the Analyze console (mission.html) and the captured-run page (run.html), which are the pages where a reader can "do" or "inspect" work. Whether a page named "Lab" existed at any point and was renamed or dropped is UNKNOWN — not established from the available evidence.

---

9. The Hugging Face header link (delivery requirement)

Stated separately because it is a delivery requirement with a verification method. See §3.2: the Hugging Face link https://huggingface.co/thundercode/SatQuery and the GitHub link https://github.com/Anish-lab-blip/SatQuery-AI are present in the navigation of all eleven pages, verified by searching every frontend/*.html for both hostnames.

---

10. Cache-busting behaviour

The frontend uses URL-versioned assets plus header rules to control caching. The header rules live in frontend/_headers (a Cloudflare Pages file), and the versioning is visible in the markup.

10.1 The _headers rules

frontend/_headers declares:

Path pattern	Rule
/*	Baseline security headers: X-Content-Type-Options, Referrer-Policy, X-Frame-Options, Cross-Origin-Opener-Policy.
/ and /*.html	Revalidate.
/assets/video/*	max-age=604800 (7 days).
/assets/fonts/*	max-age=31536000 (1 year).
/assets/css/*	public, max-age=0, must-revalidate.
/assets/js/*	public, max-age=0, must-revalidate.
/assets/img/*	max-age=604800 (7 days).

10.2 The rule that matters for correctness

JS and CSS are served public, max-age=0, must-revalidate. That is the safe setting for code: the browser may cache a copy but must revalidate before using it. This is what makes a code change take effect without asking users to hard-refresh. Images, fonts, and video get long lifetimes because they are content, not logic — and because a changed image is given a new URL rather than overwriting the old one.

10.3 The delta-growth pair as the worked example

frontend/_headers itself carries a note that the delta-growth image pair was given new URLs when it changed (delta-growth-t0-720 / delta-growth-t1-720, referenced from index.html). That is the correct pattern for a long-cached asset: change the URL, keep the long max-age. The homepage's wipe slider uses that pair, and the "evidence" section uses delta-growth-t2-2075.jpg — a third URL in the same family.

---

11. Cloudflare platform traps

Two Cloudflare behaviours shape this frontend. Both are recorded because a future maintainer will hit them.

11.1 _headers rules CONCATENATE (they do not override)

This is the single most surprising Cloudflare Pages behaviour in this project, and frontend/_headers documents it verbatim in a comment inside the file. The rule is: when more than one _headers rule matches a path, Cloudflare concatenates the header values rather than letting the more specific rule override the more general one.

The practical consequence: if two rules both set Cache-Control, the client receives two Cache-Control values. Chromium honours the first max-age it sees. So a broad rule that sets max-age=0 and a specific rule that sets max-age=604800 do not "resolve" to the specific one — the client sees both, in order, and takes the first.

docs/FINAL_DELIVERY_TODO.md §1.7 lists this as known blocker item 9. The mitigation, as evidenced by the shipped _headers, is to scope the patterns so that they do not overlap where the value must be exact — i.e. write one rule per asset tree rather than a general rule plus an override. The /assets/js/* and /assets/css/* rules are separate from /assets/img/* precisely so that each tree has exactly one matching rule and there is nothing to concatenate.

11.2 The 308 .html → extensionless redirect

Cloudflare Pages issues a 308 redirect from a path that ends in .html to the extensionless path: a request for /run.html redirects to /run. A 308 preserves the method (unlike 301/302 in some clients), so a POST is not silently turned into a GET, but the redirect still happens and the final URL differs from the requested one.

The second, related trap is the trailing-slash 307: Starlette's redirect_slashes behaviour issues a 307 when a request's trailing slash does not match the route. This is documented for the API in docs/API_CONTRACT.md §5.1 as a footgun, and it matters to the frontend because the frontend is the caller: SQ.live.url() and _normalizeBase() exist partly to make the client's URL composition predictable so that the client is not relying on a redirect to reach an endpoint.

Both traps share a lesson: the frontend must link to the canonical URL. A page that links to /run (extensionless) never triggers the 308; a page that links to /run.html does.

---

12. Accessibility and UX caveats

This section states what can be established from the files read, and marks the rest.

12.1 What is established

• Keyboard driving exists on the captured-run page. run.js supports keyboard input to move between steps (gotoStep() plus key handling), so run.html is operable without a mouse.
• Reduced-motion and focus styling are governed by the token system in frontend/HANDOFF.md §2 (CSS custom properties on :root). The handoff document is the design authority for the token layer.
• The event drawer is a named, focusable pair of controls (#btnEvents / #btnClose) with a labelled region (#drawer → #evlog), so the event log is not hover-only.
• The upload widgets are real <input type="file"> elements (#fileInput, #fileInputT0), which are natively keyboard- and screen-reader-operable, and they are paired with a #dropZone for pointer drag-and-drop. Drag-and-drop is an addition to the file input, not a replacement.

12.2 What is not established

• A formal accessibility audit (axe / Lighthouse / WCAG conformance level) has not been performed: UNKNOWN — not established from the available evidence.
• Contrast ratios for the token palette: UNKNOWN — not established from the available evidence.
• Screen-reader behaviour of the trace bar's animated width (whether a live region announces each state transition): UNKNOWN — not established from the available evidence. The trace bar is a visual affordance driven by markState(); whether its state changes are announced is not determinable from the code read.
• Mobile/responsive breakpoints beyond what the CSS declares: UNKNOWN — not established from the available evidence.
• The 404 page's page count is stale: 404.html says "Ten pages exist" and links five, while eleven ship. This is drift, recorded here and not silently repaired.

---

13. Documentation drift recorded (not propagated as current truth)

Per the project's practice (mirrored from P10-T02), drift found during this chapter's research is recorded honestly rather than smoothed over:

Location	Stale claim	Correct current statement
frontend/_headers comment	"100% static, zero network calls"	Ten of eleven pages are hermetic; mission.html calls the live service.
frontend/404.html prose	"Ten pages exist" (links five)	Eleven pages ship.
frontend/mission.html / _headers relationship	(implicit)	The live API base is declared in <meta name="satquery-api-base">, which is a live dependency the hermeticity audit must be read as exempting.

None of these is a code defect; each is a documentation statement inside a shipped file that no longer matches the tree. They are listed so a reader is not misled by them.

---

14. What the frontend does NOT do

Stated explicitly, because the depth of §5–§7 could otherwise imply more capability than exists:

• No framework and no build step for application code. Pages are hand-written HTML plus ES modules; scripts/stage_pages.mjs copies, it does not compile.
• No client-side model inference. The browser never runs a model. All inference happens on the service (POST /api/infer → the tunnel → the inference service).
• No multipart upload. Uploads are raw-bytes POSTs with a Content-Type header, matching the server contract (docs/API_CONTRACT.md §2.4: multipart is not implemented).
• No streaming. There is no server-sent-events or websocket channel. The eight events are client-side UI states; on a live run they are derived from the single inference response (plus the two response headers X-SatQuery-State and x-satquery-transport), not pushed from the server. (See the SERVING.md chapter: the service does not stream.)
• No authentication UI. The service has no auth (docs/API_CONTRACT.md §7), so there is no login.
• No persistence of runs. Nothing in the frontend stores a run; the console's state is in-memory, and the captured-run page reads a static data file.
• No offline mode beyond the fact that ten pages need no network.

---

4.3 The staging tool in detail: closure algorithm and report format

This subsection expands §4.1 because the staging tool is the only build-like step in the frontend and its behaviour determines what ships.

4.3.1 Why a closure walk instead of "copy the directory"

Copying frontend/ wholesale would ship unreferenced assets: draft images, superseded JS, experiment files. A closure walk ships exactly the transitive set of files reachable from the eleven seed pages. The consequences are worth stating precisely:

• Adding a page is a deliberate act. Because the seed set is frontend/*.html (top level only), a page placed in a subdirectory is not a seed. It ships only if a seed page references it.
• Removing a reference removes a file from the deploy. If the last page that used assets/img/eo/old.jpg stops referencing it, that image silently stops shipping. This is a feature (smaller tree) and a hazard (an asset can disappear without an error) — which is exactly why the tool prints the staged tree and the integrity report, so the disappearance is visible in the build log rather than only in production.
• Query strings and hashes are normalised away. stripQueryHash() means app.js?v=3 and app.js are the same edge, so versioned references do not create phantom files.
• External URLs are not followed. isExternal() stops the walk at https://… and //…, which is why the external-dependency audit can report HERMETIC: any external URL that was followed would show up as a network dependency.
• References cannot escape the root. insideFrontend() rejects a resolved path that leaves frontend/, so a stray ../../secret reference cannot pull a file from outside the tree.

4.3.2 The four report blocks

The tool prints four blocks. Reading them in order answers the four questions a deployer has.

1. === STAGED TREE === — what will be uploaded? A listing of every file copied into the output root, with sizes. Files over BIG_WARN_BYTES (10 MiB) are flagged.
2. === REFERENCE INTEGRITY === — is the closure complete? The staged tree is re-walked and every reference must resolve inside it. A dangling reference fails with exit code 3. This is the check that catches the case where a file was referenced but not copied (e.g. because of a case-sensitivity difference between the developer's filesystem and Linux).
3. === EXTERNAL DEPENDENCY AUDIT === — is the site hermetic? External URLs found in the closure are listed. When the list is empty the block prints HERMETIC. This is the check that keeps the "ten of eleven pages are hermetic" claim honest: if a page gained a CDN script, the audit would stop printing HERMETIC.
4. === OPTIONS APPLIED === — what flags were used? The effective options, so a build log is self-describing.

4.3.3 The two hard gates and their exit codes

Condition	Exit code	Why it is fatal
Any file exceeds PAGES_FILE_LIMIT (25 MiB)	2	Cloudflare Pages rejects a file over the limit; deploying would fail after upload. Failing before upload is cheaper and clearer.
Staged tree fails reference-integrity re-walk	3	A dangling reference means a broken page in production.

The deliberate design choice is fail before upload. Both gates run locally, on the staged tree, before wrangler is invoked. A non-zero exit stops a shell pipeline (&&) before the deploy command can run.

4.3.4 The deploy hint

The last thing the tool prints is the command to run:

npx wrangler pages deploy "<OUT_ROOT>" --project-name <name>

Note that the tool does not run the deploy itself. Staging and deploying are separate steps, which means a human (or CI) can inspect the staged tree between them. This is consistent with the project's general posture: make the artifact inspectable before it is published.

---

5.10 The nine console states

mission.js declares nine ControllerState values in STATES, an EVENT_TO_STATE map from the eight event names onto those states, and a STATE_NOTE table of human-readable text per state. markState() is the single function that advances the UI from one state to the next, and it is the only place the trace-bar width is written.

The relationship between the nine states and the eight events is:

• One state is the idle / pre-run state — the state the console is in before QUERY_RECEIVED. resetUI() returns the console to it (and resets #obsTail to none).
• The other eight states are entered by the eight events, in order. EVENT_TO_STATE is the mapping, so the console's state names and the protocol's event names are kept in one place rather than duplicated across if branches.

STATE_NOTE gives each state a sentence, which is what #traceNow and #traceNote display while the run progresses. The point of the separate state text is that the event name is protocol (SPECIALIST_STARTED) while the state text is human ("running the grounding specialist"). The console shows both: the event name in the drawer's log, the state text in the trace region.

5.10.1 Why the fill formula uses (traceProgress + 0.5) / STATES.length

The formula is:

traceFill.style.width = ((traceProgress + 0.5) / STATES.length) * 100 + '%'

Three observations about it:

1. STATES.length is 9, not 8. The denominator is the number of states, which includes the idle state. So the maximum reachable fill from events alone is (8 + 0.5) / 9 = 94.4444 %.
2. The + 0.5 is a half-step lead. Entering state n shows the bar at (n + 0.5)/9, i.e. the midpoint of that state's band. The bar therefore never sits exactly on a boundary, which reads better visually and means the bar is always "inside" a labelled state.
3. The remaining 5.5556 % is the idle state's band. A completed run does not enter idle, so a completed run does not fill the bar. This is the arithmetic origin of the 94.4444 % figure the delivery documents record.

Stated as a status: the formula is IMPLEMENTED; the 94.4444 % figure is MEASURED as the arithmetic consequence of the formula against nine states, and it is corroborated by the live validation runs recorded in the delivery documents. It is not a claim about anything else.

5.10.2 onEvent() — the single funnel

onEvent() is the console's event handler: every event delivered through the ingest() seam passes through it. It is responsible for

• appending to the event log via logEvent() (which writes to #evlog in the drawer),
• advancing the state via markState() (which writes the trace bar),
• routing the payload to the appropriate renderer (renderEvidence(), renderConfidence(), renderIntent(), the answer renderer into #answerHost, and the provenance writers into #pRun / #pPolicy / #pProtocol / #pSchema).

Having a single funnel is what makes the REAL/PREVIEW distinction safe: both drivers call the same onEvent(), so the rendering path is identical and only the payload source differs. It is also why the "0 mock nodes vs 9 mock nodes" property is checkable at one place — the drawer's contents are produced by one function.

---

5.11 The viewer and comparison regions

5.11.1 The viewer

The viewer is the plate at the top of the console's results area. Handles: #vbtns (mode buttons), #viewerState (state label), #plate (container), #plateImg (the image, src initially assets/img/eo/reservoir-low.jpg), #ev (evidence overlay), #evNote (overlay note), #plateCreditLead and #plateCredit (attribution).

The initial src is a real EO image (reservoir-low.jpg), not a synthetic one. That matters for honesty: before any run, the console shows a real image with a credit, so a visitor is never looking at invented imagery while the console is idle.

#vbtns selects a viewer mode and #viewerState names it. The evidence overlay #ev is where the grounding result's regions are drawn — for the captured grounding run there are three regions (region_1cd3973de749, …), which is why the overlay is a layer separate from the plate image rather than something painted into the image.

5.11.2 The comparison region

For paired tasks (change, change_vqa, optical_sar), the console shows a comparison region: #cmpWrap (wrapper), #cmpT0 (before pane), #cmpT1 (after pane), #cmpRange (the range/slider control), #cmpCredit (attribution), #cmpEmpty (empty state).

The two panes are fed from the two upload widgets (#fileInput for t1, #fileInputT0 for t0). When only one asset is available for a paired task, SINGLE_ASSET_FALLBACK = 'vqa' narrows the request so the console can still produce an answer instead of failing. #cmpEmpty is the state shown when there is nothing to compare.

The homepage uses the same visual idiom for its delta-growth wipe slider, which is a nice consistency: the idea of "two dates, one place, slide to compare" appears both as a landing-page illustration and as a functional control in the console.

---

5.12 Provenance and report controls

5.12.1 The provenance block

#provHost contains four fields that together answer "what exactly produced this?":

Handle	Field	Meaning
#pRun	run id	The run_… identifier.
#pPolicy	policy	The routing/planning policy that produced the plan.
#pProtocol	protocol	The protocol under which the result was produced.
#pSchema	schema	The schema version of the response.

The reason a provenance block is worth four fields: the project's measurement discipline depends on being able to say which protocol a number came from. The style guide's grounding rule — that grounding was measured under two protocols (canonical 0.2838 / matched6 0.2566) and two decode variants (head_argmax 0.1215, zero-shot 0.0972) — is exactly the kind of fact that a protocol field exists to disambiguate. A result rendered without its protocol is a result that cannot be compared to anything.

5.12.2 The report button and the event drawer

#btnReport triggers the console's report action. #btnEvents opens #drawer, whose #evlog contains the ordered event log; #btnClose closes it. The drawer is the console's audit surface: it is the one place where a reader can count events and check for mock nodes.

---

5.13 The mock data model inside core.js

core.js (1029 lines) is not only the event seam; it is also the source of everything the preview driver draws. Its internals, as read:

Utilities. SQ.util provides rnd (random), rng (a seeded random-number generator — which is what makes the preview deterministic across reloads), pad, and ms (formatting).

Raster synthesis. The synthetic imagery path:

Symbol	Role
BIOMES	The biome definitions the synthesised terrain is drawn from.
CANON	{w: 900, h: 600} — the canonical raster size.
buildMasks()	Builds the masks (land/water/etc.) the raster is composed from.
fbm	Fractal Brownian motion — the noise function that gives the terrain texture.
SQ.scene	Produces a scene; it sets a synthetic: true flag and fills placeholder gsd, aoi, and dates.

The synthetic: true flag is the load-bearing honesty mechanism: synthetic imagery is labelled as synthetic in the data, so any renderer can disclose it. The placeholder gsd (ground sample distance), aoi (area of interest), and dates are placeholders, not measurements — and the flag says so.

Imagery. SQ.imagery resolves which image to show.

Stages. SQ.STAGES is the eight-stage list from QUERY through ANSWER. This is the narrative stage list (what a human sees), distinct from the eight event names (the protocol). The two are aligned but not identical: SQ.STAGES is the visual progression; SQ.EVENT_NAMES is the wire vocabulary.

The deterministic policy. SQ.policy() is a deterministic router used by the preview. Its documented quirks: a where-first fix (a query containing "where" is routed to grounding before other rules are considered), the removal of a built keyword, and the newAsChange rule. Because it is deterministic and seeded, the same query produces the same preview every time — which is what makes the preview useful as a UI demo and useless as a measurement.

Answer material. SQ.ANSWER_BANK supplies canned answers for the preview; SQ.COMPONENTS lists seven components with their model strings, which is what the preview's model panel shows.

Shared components. SQ.frame, SQ.reliabilityPlot, and SQ.chip are reusable renderers. The SQ.reliabilityPlot is the component that draws the reliability curve referenced on benchmark.html.

The run engine. SQ.run(opts) is the engine; its ingest() switch (lines ~742–788) dispatches the eight event types to handlers. startMock() drives a preview run by calling ingest() on a schedule of setTimeout delays.

Honesty note on SQ.policy() vs the server router. The browser's SQ.policy() and mission.js's interpret() are UI-side interpretations. The authoritative router is server-side (core/controller.py, core/registry.py). The preview's routing can therefore differ from what the server would do, and that is acceptable precisely because the preview is labelled a preview and emits no specialist events. A reader must not read SQ.policy() as the routing specification.

---

6.8 live.js API surface reference

frontend/assets/js/live.js is 392 lines. Its header documents the end-to-end flow and three design rules. The module's public surface, as read:

Symbol	Kind	Behaviour
SQ.ENDPOINTS	const	{ assets: '/assets', infer: '/infer', capabilities: '/capabilities', health: '/health' }.
SQ.CONTENT_TYPES	const	{ tif, tiff, png, jpg, jpeg } — the accepted upload types.
SQ.contentTypeFor(file)	fn	Maps a file to its MIME type; used to set the upload Content-Type.
SQ.live.baseUrl()	fn	Resolution order: window.SATQUERY_API_BASE → <meta name="satquery-api-base"> → /api.
_normalizeBase(base)	fn (internal)	Normalises the base (trailing slashes).
SQ.live.url(endpoint)	fn	Composes the final URL from the normalised base and an endpoint.
LiveError	class	The client's error type, carrying enough detail for describeFailure().
describeFailure(err)	fn	Turns a LiveError into human-readable text.
SQ.live.uploadAsset(file)	fn	Raw-bytes POST with Content-Type; asserts the response contains asset_id.
SQ.live.uploadAssets(files)	fn	Uploads a list sequentially (no parallel uploads).
SQ.live.infer(request)	fn	POSTs the analysis request; reads X-SatQuery-State and x-satquery-transport from the response.
SQ.live.run(opts)	fn	Composes upload + infer into one run.
SQ.live.capabilities()	fn	GET the capability block (used by loadCapabilities()).

6.8.1 The three design rules (as stated in the file's header)

The file's header states three rules that govern the client. They are worth restating because they explain several behaviours that would otherwise look arbitrary:

1. Raw bytes, not multipart. The upload is a body-with-content-type POST because that is what the service accepts (docs/API_CONTRACT.md §2.4: multipart is not implemented). A client that sent multipart would be rejected.
2. Sequential uploads. uploadAssets() uploads one at a time because the server's asset store is a small ephemeral store with a file cap (SERVING.md: default _asset_max_files() = 32), and because a paired task's second upload depends on the first succeeding. Parallel uploads would make partial failure harder to reason about.
3. The asset handle is opaque. The client asserts the handle exists and passes it back unexamined. The handle's shape (asset_<32 hex>) and its TTL are server facts; the client must not depend on either.

6.8.2 The two response headers

SQ.live.infer() reads two custom headers:

Header	Meaning
X-SatQuery-State	The controller state for the response (the same vocabulary as the console's STATES).
x-satquery-transport	How the response was carried (the captured envelope records transport: "tunnel").

These two headers are how the console can display a state and a transport without a streaming channel. They are the reason the console can show a live run's progress truthfully: the state and the transport come from the server's own response, not from a client-side guess.

---

7.4 The captured envelope, field by field

This subsection expands §7.1 into a complete inventory, because the captured envelope is the frontend's single richest piece of real data and a reader should be able to reconstruct it.

Provenance and identity.

Field	Value	Note
_source	"Captured live 2026-09-25 … Sanitized"	The capture date and the fact that the payload was sanitized before shipping.
run_id	run_d124d8b9adea	The run identifier.
config_hash	78f1e3700da15aa1	The frozen config hash — the same value recorded in the style guide §3.

Request.

Field	Value
query	"Where is the reservoir?"
task	grounding
intent.source	forced (the task was forced rather than inferred).
transport	tunnel

Plan.

Field	Value
plan	step_001, task grounding, requires_assets
steps	8 steps, RECEIVE → RESPOND
timings.step_001	209.873 (ms)

Models.

Field	Value
selected_models	ViT-B-32 (the RemoteCLIP path) → GroundingHead
GroundingHead params	1052677

Result.

Field	Value
answer	"[grounding] Located 3 candidate region(s) … Highest objectness 0.61."
evidence	4 items: 3 × bounding_box, 1 × statistic
regions	3, e.g. region_1cd3973de749

Confidence.

Field	Value
raw	0.5231253252136926
calibrated	0.5236623182649384
method	temperature_scaling
temperature	0.9772731820958189
calibration_samples	16441.0

The calibration_samples value 16441.0 is the size of the validation set the temperature was fitted on; docs/API_CONTRACT.md §4 records the same figure as 16,441 Val rows. The temperature 0.9772731820958189 is also recorded in docs/API_CONTRACT.md §4. This is a real cross-check: the number on the public page matches the number in the API contract.

Geospatial and warnings.

Field	Value
geospatial	730 × 730, has_crs false
warnings	2 — no CRS; contradictory spatial claims

The presence of the warnings in the shipped envelope is itself a design statement: the capture was not cleaned up to look better than it was.

Why this page is important to the release. It is the one place where a reader can see a complete, real, sanitized result envelope — including its imperfections — rendered by the same event vocabulary the live console uses. It is a sample of one, and the page does not present it as more than that.

---

11.3 A worked path through the platform traps

The following Mermaid diagram shows where the two traps (§11.1, §11.2) bite. It is a description of the behaviours documented in frontend/_headers, docs/API_CONTRACT.md §5.1, and the Cloudflare redirect behaviour recorded in the delivery documents — not a measurement.

flowchart TD
    A["Browser requests /run.html"] --> B{"Cloudflare Pages"}
    B -->|"308 (method preserved)"| C["/run"]
    C --> D["run.html served from the staged tree"]

    E["Browser loads the page"] --> F{"Assets referenced"}
    F -->|"/assets/js/run.js"| G["Rule: /assets/js/*"]
    F -->|"/assets/img/…"| H["Rule: /assets/img/*"]
    G --> I["Cache-Control: public, max-age=0, must-revalidate"]
    H --> J["Cache-Control: max-age=604800"]

    K["If two rules matched one path"] --> L["Values CONCATENATE"]
    L --> M["Chromium honours the FIRST max-age"]
    M --> N["Mitigation: scope patterns so they do not overlap"]

Read together, the traps say: link to the canonical extensionless URL (so the 308 never fires for an internal navigation) and give each asset tree exactly one matching _headers rule (so there is nothing to concatenate).

The third, API-side trap — the Starlette trailing-slash 307 documented in docs/API_CONTRACT.md §5.1 — is the client's concern rather than the static tier's: _normalizeBase() and SQ.live.url() exist so the client composes a URL that matches the route exactly, rather than relying on a redirect to reach it.

---

14.1 What the frontend is a client of

Because this chapter documents a client, it is worth stating precisely what contract the client is written against, so a reader can follow the thread into the SERVING.md chapter.

• The client posts raw bytes to /api/assets and receives an opaque asset_id (docs/API_CONTRACT.md §2.5).
• The client posts JSON to /api/infer (docs/API_CONTRACT.md §2.4) and receives a ResultEnvelope.
• The client reads GET /api/capabilities (docs/API_CONTRACT.md §2.2) to know which tasks are available now.
• The client may read GET /api/health (docs/API_CONTRACT.md §2.1) for the service's health block.
• The client reads two custom response headers (X-SatQuery-State, x-satquery-transport).
• The client renders errors from the service's machine codes (docs/API_CONTRACT.md §5.2 — a 23-code taxonomy in core/errors.py, plus the gateway-origin rate_limited, mapped by gateway/policy.py _CODE_STATUS).
• The client sends no credentials; the service has no auth (docs/API_CONTRACT.md §7). CORS is configured on the orchestrator (deploy/render/main.py _PRODUCTION_ORIGINS includes the Pages origin).

Every one of those six interactions is documented from the server side in the SERVING.md chapter, which is the other half of this pair.

---

15. Status summary

Subsystem	Status
Static tier (11 pages, CSS, JS modules, assets)	IMPLEMENTED
Staging tool scripts/stage_pages.mjs (closure, size gate, integrity gate, hermeticity report)	IMPLEMENTED
Deploy path (wrangler pages deploy of the staged tree)	IMPLEMENTED; deployed HEAD 2d7ae53b482d
Analyze console (mission.html + mission.js + live.js + core.js)	IMPLEMENTED
Eight-event protocol + trace bar (94.4444 % fill)	IMPLEMENTED; fill MEASURED as the arithmetic consequence of the formula
PREVIEW driver (runMock, 9 mock nodes, no specialist events)	IMPLEMENTED
REAL driver (runLive, real HTTP, 0 mock nodes)	IMPLEMENTED; exercised in the 24-run live validation recorded in the delivery docs
Captured-run page (run.html over anatomy-run.js)	IMPLEMENTED; data is a real sanitized capture (run_d124d8b9adea)
Hugging Face + GitHub header links on all 11 pages	VERIFIED by search across frontend/*.html
Cache-busting (_headers rules + URL versioning)	IMPLEMENTED
_headers concatenation trap	KNOWN (blocker item 9 in docs/FINAL_DELIVERY_TODO.md §1.7); mitigated by non-overlapping patterns
Accessibility audit	NOT RUN

---

16. NOT RUN / OPEN / BLOCKED (frontend)

Per release/DOCS_STYLE_GUIDE.md §4, every doc ends with this list.

NOT RUN

• No formal accessibility audit (axe / Lighthouse / WCAG conformance level).
• No measured contrast-ratio audit of the token palette.
• No screen-reader behaviour verification for the trace bar's state transitions.
• No responsive-breakpoint verification beyond the CSS as written.
• No end-to-end benchmark of the system (this is project-wide, per release/DOCS_STYLE_GUIDE.md §3 — it is not a frontend gap, it is a project-level fact that the frontend must not contradict).

OPEN

• frontend/404.html prose says "Ten pages exist" while eleven ship — documentation drift, OPEN.
• The _headers concatenation behaviour remains a known platform trap (blocker item 9); the shipped rules avoid overlap, but the underlying platform behaviour is unchanged and OPEN as a hazard.
• A page named "Lab" is not among the eleven shipped pages; whether it existed is UNKNOWN — not established from the available evidence.
• Accessibility conformance level: UNKNOWN — not established from the available evidence.

BLOCKED

• Nothing in the frontend is blocked. The frontend's live path depends on the backend, and the backend's own blockers (e.g. B-07, tunnel gaps; patch prepared, NOT deployed) are recorded in the SERVING.md chapter and the delivery documents. A backend blocker surfaces in the console only as an error rendered by translateError().

---

17. Where the evidence lives

Claim area	Evidence file(s)
Page inventory, purposes, data-view, section structure	frontend/*.html (11 files, each read)
Homepage structure, video chapters, delta pair, open-question links	frontend/index.html
Analyze console markup and every DOM handle	frontend/mission.html
Console driver, interpret(), chooseTask(), assetsForTask(), validateOpticalSar(), translateError(), routeSpecialists(), renderIntent(), STATES/EVENT_TO_STATE/STATE_NOTE, markState() (fill formula), buildTrace(), logEvent(), resetUI(), renderEvidence(), renderConfidence(), onEvent(), runMock(), runLive(), runQuery(), loadCapabilities(), setMode(), handleFile(), window.SQ_MISSION	frontend/assets/js/mission.js
SQ namespace, rng/util, synthetic scene flag, SQ.STAGES, SQ.EVENT_NAMES, SQ.policy(), SQ.run().ingest(), startMock(), SQ.COMPONENTS	frontend/assets/js/core.js
Live client: SQ.ENDPOINTS, SQ.CONTENT_TYPES, SQ.contentTypeFor(), SQ.live.baseUrl(), _normalizeBase(), SQ.live.url(), LiveError, describeFailure(), uploadAsset(), uploadAssets(), infer() (header reads), run(), capabilities()	frontend/assets/js/live.js
Captured-run driver: QUERY…PLATE, REGIONS, paintAll(), buildEvidence(), evCandidates()/evLock()/evConfirmed(), SPECIALISTS_FOR_TASK, buildLattice(), DATA (8 KV tables with event names), setStage(), resetEvidence(), gotoStep()	frontend/assets/js/run.js
Captured envelope (run id, task, answer, config hash, transport, plan, steps, models, evidence, regions, confidence + calibration, timings, geospatial, warnings)	frontend/assets/data/anatomy-run.js
Cache rules and the concatenation trap (verbatim comment)	frontend/_headers
Design law, token system, phases A–G, file map, hard limits, schema types, ingest seam, 8 event names	frontend/HANDOFF.md
Staging tool: constants, regexes, closure walk, exit codes 2/3, report blocks, HERMETIC, deploy hint	scripts/stage_pages.mjs
Deployed frontend HEAD 2d7ae53b482d; HF link on all 11 pages; blocker item 9	docs/FINAL_DELIVERY_TODO.md
Live topology and per-component responsibilities	docs/DEPLOYMENT_TOPOLOGY.md
Superseded-topology banner; entrypoint requirements; failure-mode table	docs/DEPLOYMENT_ARCHITECTURE.md
API contract the client speaks (endpoints, enums, confidence, errors, no-auth, CORS, multipart-not-implemented, 307 footgun, 23-code taxonomy)	docs/API_CONTRACT.md
Captured run ids per task; metrics table; blockers	docs/FINAL_DELIVERY_REPORT.md
Style, grounding rules, status vocabulary, facts-that-must-not-be-wrong, 94.4444 % trace fill	release/DOCS_STYLE_GUIDE.md