GIA/artifacts/workspace_interface_plan.md

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.