# Phase 21F - Story Intelligence Visualisation Snapshot

## Snapshot Architecture

Phase 21F adds a read-only real-data snapshot path for the existing Story Intelligence Experience prototype. The browser contract remains the existing `StoryIntelligenceExperiencePrototypeViewModel` shape so the renderer can display either simulation data or persisted Story Intelligence run data.

## Data Sources

The snapshot service reads:

- `StoryIntelligenceSavedRun`
- `StoryIntelligenceSavedSceneResult`
- parsed `SceneIntelligenceScene` JSON
- existing Illustration Library resolution through `IIllustrationLibraryService.ApplyApprovedIllustrationsAsync`

It deliberately does not expose source manuscript text, raw AI responses, prompts, or import write operations.

## DTO Contract

The model adds snapshot metadata:

- `mode`
- `runId`
- `runStatus`
- `changeToken`
- `generatedUtc`
- `isTerminal`
- `snapshotMessage`
- `availableRuns`

The renderer continues to consume `scenes`, `characters`, `location`, `assets`, `relationships`, `knowledgeThreads`, `observations`, `latestDiscoveries`, and `activityFeed`.

## Stable Visual IDs

Stable IDs are deterministic:

- scenes: `scene-result-{SceneResultID}`
- waiting scene: `run-{RunID}-waiting`
- characters: `character-result-{normalised-name}`
- locations: `location-result-{normalised-name}`
- assets: `asset-result-{normalised-name}`
- relationships: `relationship-result-{character-a}-{character-b}-{signal}`
- knowledge: `knowledge-result-{recipient}-{knowledge-item}` or `question-result-{question}`
- observations: `observation-result-{type}-{subject}-{predicate}`

Normalised names are lower-case, alphanumeric slug keys.

## Current Scene Selection

The current scene is the latest valid parsed scene at or below the run's completed-scene count. If no parsed scenes exist, the snapshot returns a waiting scene so the visual shell remains intact.

## Character Rules

The current scene maps parsed characters and point-of-view data. Explicit POV receives weight `100`. Mentioned-only characters are lower weight. No POV is invented if the parsed data does not provide one.

## Location Rules

The snapshot chooses one active location, preferring present, specific, high-confidence locations. If none exists, it returns a graceful "Location not yet identified" placeholder.

## Asset Rules

The snapshot returns up to five significant current-scene assets. Mentioned-only and clearly low-value/background assets are filtered.

## Relationship Rules

Relationships are limited to the current scene parsed relationships. They use deterministic IDs and confidence-derived weights. The renderer may suppress inline labels if there is no clean visual space.

## Knowledge Mapping

Questions raised and knowledge changes feed the Knowledge Threads panel. Parsed observations feed the Story Observations panel. Wording is concise and user-facing.

## Illustration Resolution

The snapshot assigns starter Illustration Library stable codes using simple non-manuscript heuristics and then reuses the existing Illustration Library resolver. It does not generate images.

## API Route

`GET /api/story-intelligence/runs/{runId}/visualisation-snapshot`

The endpoint is authenticated and returns only runs owned by the signed-in user in this phase.

## Development Route

- Simulation: `/Development/StoryIntelligenceExperience?mode=simulation`
- Real run: `/Development/StoryIntelligenceExperience?runId={runId}`
- Selector: `/Development/StoryIntelligenceExperience`

The selector is development/admin-only.

## Refresh Mechanism

Real mode uses restrained polling of the snapshot endpoint. It polls about every 7 seconds while visible, backs off while hidden, avoids overlapping requests, and stops once the run is terminal.

## Completion Behaviour

Completed and completed-with-warning runs show the final provisional snapshot and stop polling. Failed and cancelled runs show the available snapshot plus a clear status message.

## Performance Notes

The service parses scene result JSON once per snapshot request, limits central collections, does not load manuscript source text, and logs snapshot build duration.

## Tests

Added coverage for:

- simulation mode remaining available
- real snapshot contract metadata
- absence of raw manuscript text, raw AI responses, and prompts from the visualisation contract

Existing build and Story Intelligence/Illustration tests continue to run.

## Known Gaps

- Collaborator/project access beyond run ownership is not yet expanded for this development endpoint.
- Canonical uploaded entity images are not resolved ahead of Illustration Library images yet.
- The route is not linked from the production Story Intelligence progress workflow.
- Relationship/knowledge mapping uses current scene parsed data, not a durable replay history.

## Recommended Phase 21G Work

- Broaden access checks to full project collaborator semantics.
- Resolve canonical entity images before library fallbacks where canonical entity matches are available.
- Connect the real Story Intelligence workflow to this visualisation at the appropriate handoff point.
- Add a lightweight status-token endpoint if polling full snapshots becomes too heavy.