# Phase 21B - Story Intelligence Experience Prototype

## Purpose

Phase 21B creates an isolated, development-only visual prototype for the PlotDirector Story Intelligence Experience. The product specification is `PlotLine/Docs/Features/PlotDirector_Story_Intelligence_Experience_Design_v2.md`; this note records the implementation approach and limits.

## Route

- `/Development/StoryIntelligenceExperience`
- Implemented by `DevelopmentController`.
- Requires the existing `AdminOnly` policy.
- Returns `NotFound` unless `IWebHostEnvironment.IsDevelopment()` is true.
- Not linked from normal navigation.

## Files added or changed

- `PlotLine/Controllers/DevelopmentController.cs`
- `PlotLine/ViewModels/StoryIntelligenceExperiencePrototypeViewModels.cs`
- `PlotLine/Services/StoryIntelligenceExperiencePrototypeData.cs`
- `PlotLine/Views/Development/StoryIntelligenceExperience.cshtml`
- `PlotLine/wwwroot/css/story-intelligence-experience-prototype.css`
- `PlotLine/wwwroot/js/story-intelligence-experience-prototype.js`
- `PlotLine/wwwroot/images/story-intelligence/prototype/*.svg`
- `docs/phases/Phase-21B-Story-Intelligence-Experience-Prototype.md`

No existing Story Intelligence import, progress, SignalR, worker, persistence or database files were changed.

## Prototype data structure

The prototype uses `StoryIntelligenceExperiencePrototypeData.Build()` to provide simulated Alpha Flame-style scene states. Each state includes:

- Scene number, title, summary and stage
- Progress figures and estimated remaining time
- POV character
- Important and incidental characters
- One active location
- Significant assets
- Relationship changes
- Knowledge threads
- Story observations
- Timeline label/event
- Latest discoveries and activity feed

The Razor view serializes this model into a JSON script tag. The JavaScript renderer consumes that state and reconciles DOM elements by stable prototype IDs.

## Rendering approach

The prototype uses a hybrid renderer:

- HTML/CSS for the full-screen shell, panels, imagery, progress, scene ribbon and timeline.
- SVG for relationship and location connection lines.
- JavaScript for current-to-next state reconciliation and playback controls.

Cytoscape was not reused. It remains useful for the existing Relationship Map, but this prototype is not a free-form network graph. The experience needs authored composition around POV, location, assets, narrative rhythm and side-panel understanding, which is better tested here with HTML/CSS/SVG.

## Animation approach

The JavaScript updates from current scene state to next scene state and reconciles:

- Character prominence, position and role changes
- POV changes
- Location crossfades
- Asset appearance/removal/prominence
- Relationship line drawing
- Insight panel updates
- Scene ribbon movement
- Timeline growth
- Progress/stat changes

The default automatic playback interval is controlled by the prototype speed slider. Manual controls allow play/pause, previous, next and restart for development review only.

## Imagery approach

Prototype-only SVG artwork is stored under:

`PlotLine/wwwroot/images/story-intelligence/prototype/`

The artwork includes character portraits, locations and assets. It is intentionally isolated so it can later be replaced by curated canonical imagery and should not be treated as final artwork.

## Accessibility and reduced motion

The prototype provides:

- Ordinary HTML text for progress, status, discoveries and insights.
- Button elements for all controls.
- Visible focus styles.
- Semantic sections and labelled side panels.
- `prefers-reduced-motion` support that shortens transitions and disables animated line drawing.

## Responsive behaviour

The primary target is desktop/laptop. At narrower widths, the layout stacks and the page becomes scrollable so the current-story view remains usable rather than shrinking into unreadable tiles. A polished mobile version is deferred.

## Technical limitations

- Uses simulated data only.
- No SignalR or API integration.
- No database storage.
- No durable event stream.
- No real import pipeline connection.
- No post-import Story Map.
- No frontend package manager or bundler was introduced.
- The prototype view includes its own full-screen document shell rather than the standard layout.

## Items intentionally deferred

- Real Story Intelligence data binding.
- Snapshot/replay endpoints.
- Durable provisional discovery IDs.
- Event-history tables.
- Production navigation.
- Sigma.js/Graphology evaluation.
- Permanent Story Map route.
- Mobile polish.

## Recommendations for Phase 21C

Phase 21C should keep the current progress page intact while adding the first real data seam behind the prototype:

1. Define a read-only snapshot contract shaped like the prototype scene state.
2. Map existing `StoryIntelligenceRuns` and `StoryIntelligenceSceneResults` into that contract.
3. Add durable discovery/event storage only after the snapshot shape is validated.
4. Preserve the same browser-side state reconciliation API so simulated data can be replaced incrementally.
