references/structure-viewer-handoff.md

# Result presentation handoff

Biohub ESM should finish with something the user can inspect immediately, while keeping checksummed scientific artifacts authoritative.

## Default completion

- ESMFold2: after successful serialization, consume the emitted `presentation-request.json` and automatically hand its exact verified mmCIF or PDB to an available molecular-structure-viewing capability using its retained `openIntentId`. Verify the primary object and request predicted-confidence coloring only when the viewer is ready. Label it as serialized pLDDT, not an experimental temperature factor. Do not ask whether the user wants the result opened.
- ESM Atlas: automatically open the first returned coordinate artifact. If no coordinates are returned but at least one hit exists, fetch at most one public pLDDT thumbnail for the first-ranked hit, preserve its provenance sidecar, and display the PNG inline. Do not turn an empty result into an implicit fold.
- ESMC: display the deterministic `mutation-score.svg` artifact inline after a successful substitution score. Its labels must describe model likelihood in one masked context and must not imply biological fitness, stability, activity, binding, or function.

Visual presentation is best-effort and never replaces the raw result, normalized result, confidence metrics, or provenance. Never fabricate an image or generate replacement HTML/JavaScript viewer code.

Decide availability by semantic capability, not by tool name. A pending viewer and an unavailable viewer are distinct presentation outcomes; neither changes whether inference and artifact creation succeeded. If presentation is blocked, retain the intent, return the verified absolute artifact path, and report confidence values (pLDDT, pAE, pTM, iPTM) as text. The same independence applies to inline images.

## Semantic presentation contract

The producer status `pending-delivery` is not a viewer readiness state. It means
the retained intent has not yet been acknowledged by a renderer: deliver it once
using its exact `openIntentId`. Only after that initial open may a viewer report
`pending` while it mounts; do not skip delivery or treat `pending-delivery` as an
already-open session.

1. For `managed-post` or `managed-recover`, load and validate the exact emitted `presentation-request.json`. Use its absolute artifact path, checksum, requested view, and exact retained `openIntentId`; never replace that ID. Prefer mmCIF for all-atom output and PDB for sequence-only `/fold`, and do not inline coordinate bytes merely to open it.
2. Open once with the retained ID. Reuse it only for delivery retry. Generate one new stable `openIntentId` only for a legacy artifact set that lacks `presentation-request.json`.
3. Retain the returned viewer session only within the same task. Never infer or reuse a session identifier across tasks.
4. Respect reported readiness. While pending, retain the request and report `viewer pending`; do not reopen as polling, style, or use renderer-backed state as a startup probe. Continue only on a supported readiness signal. Once ready, use the viewer's listing capability to verify the primary object before requesting style.
5. If a mutation times out, treat its commit state as unknown. Inspect acknowledged state before retrying or issuing a different mutation; never retry blindly.

Report `structure available`, confidence completeness, and viewer status separately. Do not claim visible coloring from a file path, an issued request, or an unacknowledged mutation.

## Current `structure.*` adapter mapping

These names are the current host implementation, not a plugin requirement:

- Open: call `structure.open_from_chat` with the verified absolute path and exact `openIntentId` from `presentation-request.json`; retain returned `viewerSessionId` for this task.
- Verify: once ready, pass that value as `sessionId` to `structure.list_structures` and verify the primary object.
- Predicted confidence: once ready and verified, call `structure.control_viewer` with `action: set_color` and `color: bfactor`. Here `bfactor` means serialized pLDDT confidence, not experimental displacement.
- Timed-out mutation reconciliation only: call `structure.get_state` with the same `sessionId`; do not use it as the initial readiness probe.

## Compare generated structures

- Call `structure.add_structure` for each additional Atlas PDB using a stable object ID such as `atlas_hit_1`, representation `cartoon`, an explicit color, and the exact absolute local path.
- When Biohub already emitted `hit-N-aligned.pdb`, load that artifact directly. Do not align it again: report the recorded global-sequence plus unique chain/residue-bound ATOM C-alpha Kabsch RMSD and aligned-position count from `workflow-summary.json`.
- If the user instead asks to recompute from a raw Atlas PDB, call `structure.align_structures` with explicit primary/mobile object IDs and label the viewer's method and returned RMSD/count separately. Never replace or conflate it with the Biohub pipeline metric.
- For a reproducible live scene after readiness, read `structure.get_state`, use its current revision for `structure.apply_scene`, and target the named objects. When workspace publication is available, call `structure.render_image` with the viewer's source-relative destination contract: base `opened-source`, kind `workspace`, collision policy `exact`, a safe relative PNG path, matching `outputPath`, and `overwrite: false`. Preserve the PNG and viewer-owned `.render.json` provenance checksums.

## Point back to the source

Close a successful result with one link to the model or dataset behind it, so the user
can read what produced the answer. Use the exact page for what ran:

- ESMC results: <https://biohub.ai/models/esmc>
- ESMFold2 results: <https://biohub.ai/models/esmfold2>
- Atlas results: <https://biohub.ai/esm/protein/atlas>
- General ESM models and data: <https://biohub.ai/esm/protein>

One link, after the science, not before it. Do not stack all four, and do not turn this
into a marketing line.

## Evidence labels

- ESMFold2 coordinates are static model hypotheses.
- Atlas PDB formatting does not make a structure experimental. Treat Atlas coordinates as model hypotheses unless an authoritative source explicitly proves an experimentally determined structure and records that provenance.
- The combined demonstration contains no experimental structure. Keep query pLDDT/pTM, Atlas pLDDT/pTM, similarity, alignment method/RMSD/count, model IDs, accessions, source metadata, timestamps, and checksums in Biohub JSON. Viewer annotations are only a bounded visual summary, not the authoritative record.

The Structure Viewer does not ingest arbitrary Biohub JSON sidecars. The model must preserve `workflow-summary.json` and `provenance.json` alongside the coordinate artifacts and use their metrics when answering.