# GIA Workspace Interface Plan

## Goals

- Replace page-by-page navigation with a workspace shell that can open any major surface as a widget.
- Keep transport quirks behind shared adapters so UI code deals in people, sessions, messages, PS, MS, PSC, and MSC.
- Make widget loading, live updates, and history browsing shared primitives instead of page-specific implementations.

## Interface Map

### 1. Workspace Shell

- One grid workspace shell owns widget layout, persistence, focus, close, restore, and launch.
- A launcher surface replaces the current nav-as-destination approach.
- Every major area can render as:
  - page
  - widget
  - embeddable fragment

### 2. Core Widgets

- Compose widget:
  - simple thread viewer
  - simple outbound composer
  - reply target
  - attachment strip
  - live MS/PS chips
- Contact launcher widget:
  - search
  - recent contacts
  - open thread widget
  - create/match contact
- Message history browser:
  - long-range session browsing
  - filters by service, person, session, direction, attachments, date
  - open selected history in a compose/thread widget
- Person intelligence widget:
  - current PS summary
  - current MS summary
  - PSC/MSC highlights
  - links into evidence and history
- Session evidence widget:
  - timeline of events
  - annotated durations
  - state transitions
- Insight workbench widget:
  - hypothesis cards
  - mitigation planning
  - evidence drill-down
- Help/reference widget:
  - PS/MS glossary
  - PSC/MSC explanations
  - research basis

### 3. Behavioral Surfaces

- PS lane:
  - unavailable -> available -> typing -> typing_stopped
  - duration chips and transition stats
- MS lane:
  - sent -> delivered -> read -> responded
  - duration chips and transition stats
- PSC surface:
  - correlation patterns within PS sequences
  - return-window priority, abandoned typing, repeated hesitation
- MSC surface:
  - correlation patterns within MS sequences
  - reply delay shifts, asymmetry, reciprocity, timing escalation
- Combined inference surface:
  - PSC + MSC combinations with evidence, confidence, and caveats

## Shared Technical Primitives

### Widget Contract

Every widget-capable surface should declare:

- title
- icon
- source URL
- refresh URL
- websocket topic or polling policy
- default grid dimensions
- optional launch context

### Shared Client Modules

- `workspace-shell`
  - open widget from URL
  - replace/update widget
  - compact grid
  - persist layout
- `widget-loader`
  - HTMX/bootstrap helper for hidden widget loads
  - one primitive reused by page bootstraps and launch actions
- `live-channel`
  - shared websocket subscription lifecycle
  - reconnect and backoff
  - channel-to-widget routing
- `history-browser`
  - filters, pagination, range selection, transcript fetch
- `compose-client`
  - message list render/update
  - outbound send
  - attachment handling
  - reply targeting

### Shared Server Patterns

- Each surface provides `page`, `widget`, and `fragment` modes from one context builder where possible.
- Widget launch URLs are generated centrally, not manually concatenated in templates.
- Behavioral computations read shared PS/MS event abstractions, not transport names.
- Live updates publish transport-neutral event payloads.

## Implementation Phases

### Phase 1. Workspace Foundation

- Extract workspace shell logic from inline page scripts into shared assets.
- Standardize the hidden widget loader include.
- Slim launcher widgets so they do not dump entire datasets into one partial.
- Add a reusable message history browser endpoint and widget shell.

### Phase 2. Compose Rewrite

- Keep compose to:
  - thread
  - send
  - reply
  - attachment preview
  - live state indicators
- Move history/export/receipt/debug extras out into dedicated widgets.
- Keep page mode and widget mode on the same client code.

### Phase 3. Behavioral Workspace

- Add PS/MS event browser widgets.
- Add PSC/MSC evidence widgets with drill-down into raw events.
- Add person/session dashboards that combine evidence instead of hiding it behind static pages.

### Phase 4. Live Update Layer

- Replace page-local polling with a shared websocket abstraction.
- Route updates by widget topic:
  - compose thread
  - message state
  - presence state
  - analysis refresh
- Keep HTMX for request/response actions and server-rendered fragments.

## Immediate Debt Kill List

- Large launcher partials that dump whole universes of contacts or objects.
- Inline workspace shell JS in templates.
- Page-specific widget bootstraps that repeat the same hidden HTMX loader block.
- Mixed transport-specific UI conditionals in templates.
- Heavy detail views that combine history, inference, controls, and diagnostics in one render.