PlotDirector/docs/phases/Phase-21F-Story-Intelligence-Visualisation-Snapshot.md

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.