inter-hub/docs/phase6-summary.md

# IHF Phase 6 Summary — Cross-Framework UI Adaptation Layer

## What Was Built

Phase 6 ensures that widget identity, interaction capture, and annotation capability are preserved when UI components are authored outside of IHP HSX — React, Vue, or any JS-based component — without bypassing the IHF core.

### Contract Artifacts

**EnvelopeEmissionContract** (`envelope_emission_contracts`)
- Formalises the widget envelope as a versioned, immutable contract
- v1.0 seed: required `["data-widget-id", "data-view-context", "data-hub-id"]`, optional `["data-policy-scope", "data-widget-version"]`
- `widgetEnvelope` helper updated to validate required attributes at render time (non-crashing warning)
- Read-only controller + index/show pages under "Contracts" nav

**InteractionReportingContract** (`interaction_reporting_contracts`)
- Standardised REST interface contract for external event and annotation submission
- v1.0 seed: endpoint `/api/v1/interaction-events`, accepted event types `["clicked","viewed","submitted","dismissed","errored"]`, required fields `["widget_id","hub_id","event_type","occurred_at"]`
- Read-only controller + index/show pages

**WidgetAdapterSpec** (`widget_adapter_specs`)
- Registry of supported UI framework adapters; links to envelope and reporting contracts
- Status lifecycle: `draft → active → deprecated`
- Full CRUD controller (no delete — audit artifact)
- Widgets gain an optional `adapter_spec_id` FK (null = native IHP widget)

### REST API

`POST /api/v1/interaction-events` — JSON body, Bearer token auth (per-hub `api_key`):
- Validates payload against active `InteractionReportingContract`
- Creates `InteractionEvent` record
- Returns `201 Created` with `{id, widget_id, event_type, occurred_at}` or `422` with errors
- Custom `CanRoute`/`HasPath` instances (not AutoRoute) for the `/api/v1/` path prefix

### JavaScript Client

**`static/js/ihf-annotation-launcher.js`** — vanilla JS IIFE (no framework dependency):
- Scans DOM for `[data-widget-id]` on `DOMContentLoaded`
- Injects inline "annotate" trigger adjacent to each enrolled element
- On click: opens an inline form (textarea + category select) and POSTs to existing `/widgets/:widgetId/annotations` endpoint
- Works in React-rendered pages where IHP does not own the DOM
- Feature-flagged via `IHP_ANNOTATION_LAUNCHER=true` env var (`AnnotationLauncherEnabled` typed config)

**`static/js/ihf-react-adapter.js`** — ESM module for React 18+:
- `useWidgetEnvelope(widgetId, hubId, viewContext)` — returns `data-*` props conforming to envelope v1.0
- `withWidgetEnvelope(WrappedComponent, widgetId, hubId, viewContext)` — HOC wrapping root element
- `useInteractionReporter(widgetId, hubId)` — returns `reportEvent(type)` POSTing to `/api/v1/interaction-events`

**`static/ihf-react-test.html`** — static test fixture with CDN React 18, a React-rendered widget, and an IHP-rendered widget on the same page, both enrolled with the annotation launcher.

### Dashboards and Navigation

**Adapter Compatibility Dashboard** (`AdapterCompatibilityDashboardAction { hubId }`):
- Panel 1: Adapter spec counts by status (active / draft / deprecated)
- Panel 2: Widget coverage — native IHP vs adapter-backed with percentage bar and per-spec breakdown
- Panel 3: Active contract versions in use (envelope + reporting)
- Panel 4: Unassigned widgets (no `adapter_spec_id`)
- Panel 5: Active adapter specs table with widget counts
- `autoRefresh` — live-updates on any DB change
- Linked from hub Show page and global nav ("Adapters")

Widget show page renders an adapter badge (purple, links to spec) when `adapter_spec_id` is set.

## Contract Model

Contracts are **immutable once active**. A new version supersedes the old; old versions remain readable for audit. The status lifecycle is:

```
draft → active → superseded  (EnvelopeEmissionContract, InteractionReportingContract)
draft → active → deprecated  (WidgetAdapterSpec)
```

This prevents retroactive mutation of the rules that governed historical interaction events.

## Adapter Pattern

Any UI technology participates by honouring three obligations:

1. **Envelope** — root DOM element carries `data-widget-id`, `data-view-context`, `data-hub-id`
2. **Event reporting** — interactions submitted to `POST /api/v1/interaction-events` with bearer auth
3. **Annotation** — annotation launcher picks up `data-widget-id` automatically; no adapter-specific code required

Native IHP widgets are unaffected. `adapter_spec_id` is nullable. The `widgetEnvelope` helper continues to work unchanged.

## Known Limitations

- **No local JS build toolchain.** `ihf-react-adapter.js` is a plain ESM module; consumers must bundle it themselves (e.g. Vite, esbuild). Phase 6 does not add npm/webpack to the IHP project.
- **Bearer token scope.** The per-hub `api_key` is a simple secret stored in `hubs.api_key`. Phase 8 (federated) should replace this with OAuth or a proper token management service.
- **Annotation launcher requires no CSP violations.** The inline form approach works in permissive CSP environments; strict `script-src` policies may require nonce injection.
- **Cross-machine consistency checks.** The State Hub consistency checker runs on the server and cannot reach the local repo filesystem; C-01/C-07 errors in the check output are path false-positives for this deployment topology.

## Phase 7 Readiness

Phase 6 leaves the IHF core stable and extensible:
- All Phase 6 contracts are versioned and immutable — Phase 7 can introduce v1.1 contracts without breaking existing adapters
- Widget `adapter_spec_id` is nullable and indexed — adapter assignment is opt-in
- The REST API surface is defined by the `InteractionReportingContract` record — contract evolution is data-driven
- The JS adapter is a thin ESM module — framework-specific adapters for Vue, Web Components, etc. follow the same pattern as `ihf-react-adapter.js`