# Phase 21G - Live Story Intelligence Visualisation Engine

## Purpose

Phase 21G changes the Story Intelligence Experience from a periodically refreshed view into a live visualisation that reconciles incoming snapshots in the browser. It does not change the Story Intelligence pipeline, Illustration Library, prototype layout, prompts, data schema, or approval workflow.

## Animation Architecture

The browser now follows a small live rendering pipeline:

1. Snapshot loader polls the existing visualisation snapshot endpoint.
2. Snapshot comparator compares the current snapshot with the next snapshot.
3. Visual operation queue records the detected changes.
4. Renderer updates keyed DOM elements and SVG connections in place.
5. CSS transitions animate changed properties, inserted elements, and removed elements.

Polling still uses the Phase 21F endpoint and still ignores unchanged change tokens. When a new token arrives, the page preserves the previous snapshot, stores the next snapshot, derives visual operations, and then updates only the affected visual surface.

## Snapshot Reconciliation

The comparator detects operations including:

- `ProgressChanged`
- `StageChanged`
- `SceneChanged`
- `CharacterAdded`
- `CharacterRemoved`
- `CharacterImportanceChanged`
- `CharacterImageChanged`
- `LocationChanged`
- `AssetAdded`
- `AssetRemoved`
- `AssetImportanceChanged`
- `RelationshipAdded`
- `RelationshipRemoved`
- `RelationshipStrengthChanged`
- `KnowledgeThreadAdded`
- `KnowledgeThreadResolved`
- `ObservationAdded`
- `ObservationRemoved`
- `TimelineAdvanced`
- `DiscoveryAdded`
- `RunCompleted`

The current implementation compares the active scene represented by the latest scene in each snapshot, plus run status, terminal state, and progress metadata.

## DOM Reuse Strategy

Stable IDs are used as reconciliation keys for:

- Characters
- Assets
- Relationship insight cards
- Knowledge cards
- Observation cards
- Scene ribbon cards
- Timeline markers
- Latest discoveries
- Live activity items
- SVG connection groups

Matching nodes are retained and have their text, image, class, position, and path attributes updated. New nodes enter with `is-entering`; removed nodes receive `is-removing` and are deleted after their exit animation.

## Performance Notes

The renderer avoids emptying large panels on every snapshot. It reuses images, entity cards, list rows, scene cards, timeline markers, and SVG paths where stable IDs match. Connection drawing remains scheduled through `requestAnimationFrame`, and polling remains paused while the tab is hidden.

Progress, elapsed time, and the progress ring animate rather than jumping directly to the next value. Reduced-motion preferences are respected by shortening transition timing and disabling animated number interpolation.

## Development Diagnostics

The development Story Intelligence Experience page now includes a collapsible diagnostics panel showing:

- Current snapshot version
- Previous snapshot version
- Change token
- Animation queue length
- Last refresh time
- Snapshot fetch/build time from the browser perspective
- Operations detected

The page remains guarded by the existing Development controller environment check.

## Known Limitations

The operation model is currently client-side only and is derived from snapshot comparison. It does not yet receive event-level updates from the analysis worker. Relationship SVG paths are reused by connection ID, but their labels are still re-laid out on each draw to preserve collision avoidance.

The active-scene strategy follows the latest scene in the snapshot. If future phases expose a richer run cursor, the comparator should use that cursor instead.

## Future SignalR Migration Notes

Phase 21H can migrate snapshot delivery from polling to SignalR without changing the reconciliation model. SignalR messages should carry either a full next snapshot or a server-side change token that instructs the browser to fetch the snapshot endpoint. The existing comparator can remain the boundary between incoming data and visual animation.
