Design #75 — participant profile v2: sidebar surfacing + AE domains

1. Summary

Participant profile v1 (#45) shipped the drill-down as a module with two mounts — a standalone renderer and a dock below the host chart. Reviewing it, @jwildfire asked for the default click to open the profile in a right-hand rail with an expand to full screen control, and for the profile to grow past labs into AE Summary and AE Timeline.

This design does three things:

• Promotes the deferred drawer to a first-class mode: 'sidebar', with the dock retained as the narrow-viewport fallback rather than deleted. This supersedes the surfacing half of #45's D1; D1's rejection of a full view as the primary mode still stands — full screen becomes a state of the rail, not a mode of its own.
• Adds an AE domain to the module — a second data contract alongside the long-lab one — feeding an AE summary block and an AE timeline whose x-axis is the same study-day scale the labs chart draws. This is exactly the "AE-domain v2" that #45's D2/D5 deferred.
• Breaks the work into ten independently shippable safety.viz increments plus a matrix companion, so an autonomous session can take them one at a time.

2. What v1 shipped, and what v2 changes

3. Surfacing: the rail (D1–D4)

3.1 The four options, as built in the mockup

3.2 The narrow-rail problem, measured

The rail's real cost is not the layout — it is that the v1 contents were designed for a full-width dock. Measured on the mockup against the shipped module:

• The measure table will not lay out below 455px of content width. A rail narrower than about 500px clips its sparkline column; at 320px it loses MAX as well.
• The demographics header wraps to two rows somewhere below 400px.
• The sparkline inset chart, which expands inline under a row, has not been assessed at rail width and is the most likely second casualty.

So the rail default is 520px, and a narrow-layout pass is its own increment: column priority in the measure table (drop MIN before MEDIAN before MAX; never drop the sparkline), header wrapping, and an inset that reflows rather than scrolls. This is the largest piece of v2 work that adds no new functionality, and it should not be bundled with the rail mechanics.

4. Contents: the profile grows (D5–D7)

4.1 Section order

Proposed order in both the rail and the expanded state:

┌ stepper (when a cohort is selected, pinned)
├ header — id, demographics, R Ratio, Clear, link-out
├ labs over time — spaghetti, ×ULN / ×baseline
├ adverse events — summary tiles + severity mix + timeline   ← new
├ measures — table with sparklines and insets
└ records — optional listing

4.2 AE summary

A participant has five to twenty events. At that scale a bar chart of counts by body system is decoration, so the summary is: four figures (events, highest severity, serious, no end date), a severity mix bar, and the top body systems as a counted list.

Severity is ordinal and semantic, so it takes the reserved status ramp rather than a categorical slot — mild #fab219, moderate #ec835a, severe #d03b3b, not recorded #c3c2b7 — and is always labelled, never colour alone. Seriousness is a separate channel (a ring on the bar plus the word "serious"), because an event can be mild and serious at once.

One wording decision that matters clinically: a blank stop day means unresolved or unrecorded, and the profile cannot tell which. The tile reads "no end date", not "ongoing", and the timeline draws those bars fading out rather than ending.

4.3 AE timeline

One row per event: term above, bar below, running from start day to stop day on the labs chart's x-scale. Rows are ordered worst-first (severity, then onset). Events with no stop day fade to the domain edge; events with no start day cannot be placed and are listed beneath the plot rather than dropped silently. Ten rows fit a rail; the remainder are counted, not hidden.

The mockup implements the axis lock literally — it reads the live Chart.js scales.x from the spaghetti and places every bar and tick with the same mapping — which is the behaviour the implementation should reproduce, whether by sharing the scale or by drawing both tracks in one chart.

5. The cohort stepper in a rail (D8)

v1 renders the stepper at the top of the block, which in a dock is always visible because the block starts where you are looking. In a scrolling rail it leaves the viewport the moment you reach the measure table, so "next participant" becomes a scroll-up.

6. Data contract for the AE domain

The AE records the profile needs are the records ae-timelines and ae-explorer already ingest. The contract should reuse their setting names verbatim rather than invent a third vocabulary:

Cleaning rules, following the hep-core precedent of one ingest per setData: records without an id drop; records with a non-numeric start day are retained but listed rather than plotted; a stop day before the start day is treated as missing; severity values outside the configured list fall to "not recorded" rather than to a colour slot.

Proposed refactor, to be confirmed at implementation: extract the shared cleaning into src/ae-core/ the way hep-core was extracted for the lab family, so ae-explorer, ae-timelines and the profile share one reducer set. If that turns out to be a larger split than the increment can carry, the profile ships its own adapter first and the extraction becomes a follow-on — the same sequencing #45's D4 used for hep-core, in reverse.

7. Module API and settings

Back-compatible: profile: true keeps meaning "on", but now resolves to the rail; profile: false is unchanged. The object form carries the new settings.

SafetyViz.hepExplorer('#chart', {
  profile: {
    mode: 'sidebar',          // 'sidebar' | 'dock' | 'auto'   ('auto' = rail above the
                              //   shell breakpoint, dock below it — the D4 default)
    width: 520,               // rail width in px
    behavior: 'push',         // 'push' | 'overlay'            (D1)
    expandable: true,         // show the expand control       (D3)
    collapseControls: true,   // auto-collapse the host's controls on open (D2)
    axis: 'union',            // 'union' | 'labs' | 'independent'         (D7)
    ae: {                     // omit to keep the v1 lab-only profile
      data: aeRows,
      id_col: 'USUBJID',
      term_col: 'AETERM',
      minor_col: 'AEDECOD',
      major_col: 'AEBODSYS',
      stdy_col: 'ASTDY',
      endy_col: 'AENDY',
      color: { value_col: 'AESEV', values: ['MILD', 'MODERATE', 'SEVERE'] },
      highlight: { value_col: 'AESER', value: 'Y' }
    }
  }
})

The standalone factory takes the same ae block: SafetyViz.participantProfile(el, labRows, { ae: {...} }). Hosts that already hold AE records — ae-explorer, ae-timelines — pass their own cleaned rows, keeping the one-ingest-per-setData rule the dock established.

Shell change: renderShell gains a rail slot beside the main column (sv-rail), a sibling of sv-sidebar on the other side. The existing sv-profile dock slot stays exactly where it is; which slot the module mounts into is what mode selects.

8. Rollout and delivery (D9)

8.1 Increments

Each row is intended to be shippable on its own — a session can take one, gate it, and stop.

9. Requirement matrix plan

obot.agent/docs/requirements/participant-profile.md gains v2 areas under the existing PPRF-<AREA>-<NNN> base-ID scheme, so the evidence pages keep resolving rows by exact base-ID match:

Existing rows are amended, not deleted: PPRF-CORE-003/004 (dock slot, standalone chrome) gain a note that the rail is the new default mount; PPRF-STEP-001/002 gain the sticky-strip behaviour; the per-adopter rollout areas (PPRF-HEP-*, PPRF-SH-*, PPRF-QT-*, PPRF-OE-*, PPRF-DD-*, PPRF-SSP-*) gain a rail-default row each. PPRF-COV-001, which today records the ae-explorer / ae-timelines deferral, is superseded by their adoption rows.

10. Risks and things this design does not settle

• Chart width on a laptop. Opposite rails plus a 520px profile leaves roughly 560px of eDISH on a 1280px screen before auto-collapse, about 800px after. That is workable but not generous; if it reads badly in use, the fallback is D2's tabbed option, which costs a migration but no width.
• The inset chart at rail width is unassessed. It is the most likely place increment 2 grows.
• Study day is now load-bearing. Any host feeding the profile visit numbers rather than days gets a summary without a timeline. Whether that is acceptable or whether the module should offer a visit-based axis is not settled here.
• gsm.safety widget binding stays out of scope, as in #45 — but D3's "fill the container" choice is made specifically so the binding does not need a special case later.
• Print and export. The dock printed naturally; a rail does not. Nothing in v2 addresses print, and if it matters, expand-then-print is the answer rather than a print stylesheet.

Drafted by Claude Code using Opus 5 and reviewed by @jwildfire.