When you compose a storyboard scene in Trail mode, you’re making a deliberate narrative choice: show the recent history of each platform — the snail-trail leading up to a moment — rather than its entire route. “The minute before contact” reads very differently as a growing tail than as a fully-drawn line that was there from the start. Spec #258 taught the main application to capture that Full-vs-Trail choice per scene and honour it on playback. But the exported briefing — the standalone, air-gapped SPA you hand to someone who was never near the analysis environment — quietly ignored it, always drawing each platform’s complete route. A scene you framed to build toward a moment played back flat, its emphasis silently discarded.

This change makes the briefing renderer honour the display mode that was captured with the scene. In Trail mode each track now grows from its start up to the current playback time, trailing the moving position dot. In Full mode — and in legacy briefings exported before display mode was a thing — the whole track shows exactly as it always has. The author’s intent now survives the trip from the app preview into the shareable, offline briefing.

How It Fits

The briefing renderer is the end of the storyboarding pipeline (epic E13): the point where a composed, scoped storyboard becomes a self-contained file someone can play back offline, with no service and no network behind it. Everything the fix needs was already there — the per-scene display mode and the per-vertex track timing are carried into the exported briefing, and the moving position dot already depends on that same timing. This was never a data-capture or export gap; it was the renderer not reading what it had been handed. The fix stays entirely on the display side: one front-end component (BriefingMap.tsx) plus a new trackDisplay.ts helper, no schema change, no change to how scenes are captured, scoped, or exported.

Key Decisions

• Reuse the main app’s exact trail-slicing helper rather than writing a renderer-specific copy. The briefing calls the same sliceTrackToTime from @debrief/utils that the in-app preview uses, so the trail in the exported file is identical in shape to what the author saw while composing — visual parity by construction, with no second implementation to drift out of step. It’s an internal workspace package the renderer already pulls in transitively, so this is reuse, not a new third-party surface.

• Grow the track as a stable-keyed map polyline whose points update in place each frame, mirroring how the moving dot already updates, rather than rebuilding the map layer on every tick. An earlier oscillation bug (#264) came from tearing the layer down too eagerly each frame; updating positions in place keeps the growth smooth and steers well clear of that failure mode. Non-temporal context — region outlines, annotations, reference points — stays on the existing layer, untouched.

• One predicate decides everything: a scene is Trail only if its display mode is exactly trail; anything else shows the full track. Full, absent (legacy), and any unrecognised value all fall through to “show the whole route” — the safe, non-destructive default. That single rule is also why every briefing exported before #258 keeps playing back exactly as it does today.

• A track that lacks usable per-vertex timestamps falls back to its full line — never blank, never an error — even in a Trail scene. This reuses the same validity gate that already governs the moving dot, so a track either participates in both time-driven behaviours or neither. No half-states, no confusing empty geometry where context is expected.

Screenshots

The trail grows as playback time advances. Here’s the same 8-point Alpha track at the window start, midway through playback, and at the end:

Scrubbing the playback slider forward and back shows the trail growing and shrinking in real time:

By the Numbers

The 24-test suite breaks down as 20 unit tests covering the trail-slicing contracts and the mode predicate, and 4 Playwright tests exercising the full playback flow: a growing trail in Trail mode, a constant track in Full mode, legacy scenes without a display mode falling back to full, and a mixed briefing reapplying the right mode per scene.

Lessons Learned

Reusing the main app’s exact sliceTrackToTime helper made visual parity true by construction — there’s no second implementation to drift out of step. The real fix was a reading gap, not a data gap: everything needed (per-scene display_mode, per-vertex timestamps) was already in the exported briefing; the renderer just wasn’t paying attention to it.

Sharing one validity gate between the growing trail and the moving dot keeps them consistent — a track shows both time-driven behaviours or neither, with no confusing empty geometry where context is expected. And a deterministic, hidden per-track vertex-count node made the Playwright growth assertion robust against Leaflet’s polyline simplification: the exact vertex count can vary as Leaflet’s optimisation kicks in, but it strictly grows from start to mid to end, and that monotonic growth is what the test asserts.

What’s Next

This completes the Trail-mode story for both the standalone, air-gapped briefing and the #273 live-Preview tab. Epic E13 (storyboarding end-to-end) is now whole: Trail and Full modes are captured per scene, honoured on playback in the main app, and honoured in exported briefings. A subtle fade on the trail’s tail is possible future polish — not required for correctness, but it could draw the eye even more explicitly to the direction of motion.

→ See the spec → View the evidence

What We Built

Read a debrief:provenance_log off a STAC Item in either of our writer hosts and you now get the type the schema promises — not unknown, and not a value you’ve had to cast into shape and hope you spelled the key right. That was the gap; it’s closed. The modelled debrief:* keys now arrive at the writers’ real call sites as named, typed slots flowing straight from the LinkML schema, and the as casts that papered over the gap are gone — across three surfaces: the five item-property fields (platforms, tags, feature_tags, overrides, provenance_log), the three collection-summary fields on StacSummaries, and the two asset-level keys (debrief:toolId, debrief:snapshotTimestamp) we newly modelled onto StacAsset. Crucially the typing now reaches the write path too: both hosts used to widen the properties bag to Record<string, unknown> at the mutation site, so a mis-typed write slipped through — that widening is gone.

The payoff is the next field, not the current ten. Add a new debrief:* slot to the schema, regenerate, and it appears as a typed slot wherever the writers touch it — without anyone editing a writer-owned type declaration. A misspelled or renamed key stops being a silent runtime undefined and becomes a build failure. The kind of quiet data loss that happens when a properties bag grows but the access sites don’t keep up simply can’t compile any more.

How It Fits

This finishes a promise we deliberately deferred. Spec #240 made PropertiesProvenanceEntry LinkML-derived and added a schema drift gate, but it stopped short of claiming new fields flow to the writer’s typed surface — because that needed the prefix problem solved first. Spec #236 had already made the writer a single source of truth across both the VS Code and web-shell hosts. This feature lands on top of both: it routes the schema’s authority all the way through to where the writers actually read and write, closing the Article II.1 (LinkML as single source of truth) audit deferral recorded against #240, and reusing #240’s existing src/generated drift gate rather than inventing a new one.

Key Decisions

• Why the naive fix does nothing. LinkML’s gen-typescript strips the debrief: prefix and emits bare slot names (provenance_log), but the data on disk — and every one of the ~27 real call sites — uses the prefixed key (debrief:provenance_log). A StacItem.properties: StacExtensionProperties intersection, the obvious move, keys on the bare names and matches none of the prefixed access sites. Zero benefit. That’s exactly why #240 punted it here.

• Generator post-processor over writer refactor. We extended the existing shared/schemas/scripts/generate.py post-processor with one step that rewrites generated slot keys to their on-disk prefixed form. TypeScript resolves string-literal index access to the matching named slot, so the existing literal-key call sites gain types with no rewrite. The alternative — rewriting all ~27 sites to unprefixed keys behind a serialisation adapter — has a larger blast radius and introduces a new boundary where a forgotten field can silently drop, the precise ADR-033 / Article IV.5 failure class we guard against.

• Schema-driven from slot_uri, not per-class text rules. The step reads each slot’s LinkML slot_uri and uses it verbatim. We deliberately did not hard-code a “prepend debrief:” rule: it can’t generalise across the three target classes — StacSummaries keys are underscore-named (debrief_platforms → debrief:platforms, a substitution), and StacAsset mixes Debrief slots with non-Debrief ones (href, roles) that must stay untouched. Reading slot_uri is the only thing that handles all three and keeps the add-a-field promise — a new slot flows through with no edit to the generator.

• We typed the write path, not just reads. The naive generated-type fix only reaches the read sites; both writer hosts widened the properties bag to Record<string, unknown> at the mutation path, leaving write-side typos silent — exactly the failure this feature exists to kill. Removing those widenings (and re-homing debrief:toolId / debrief:snapshotTimestamp onto StacAsset) is what makes the guarantee real end-to-end. We also found debrief:label is a feature property, not a STAC one, and left it alone rather than mistyping it.

• Reuse the drift gate; change no bytes on disk. The committed artefacts are already covered by #240’s src/generated CI drift gate, so freshness is enforced without a new gate. The two new StacAsset slots are additive and their keys already exist on disk — the on-disk JSON is byte-for-byte unchanged, verified by a round-trip golden check.

By the Numbers

Typing-only and behaviour-preserving — every figure below comes from the committed test run and the round-trip golden check.

Lessons Learned

The scope grew during implementation, and it grew in the right direction. The original plan targeted StacExtensionProperties alone — that looked like five slot renames and done. Working through the generator step revealed that StacSummaries had the same problem (underscore-mangled names, no match on disk) and StacAsset had no typed home for debrief:toolId and debrief:snapshotTimestamp at all. Folding both in was the right call: a “prepend debrief:” text rule would have sufficed for StacExtensionProperties but would have silently mishandled StacSummaries and trashed StacAsset’s non-Debrief slots. Reading slot_uri from the schema handled all three cleanly and made scope expansion cheap rather than risky.

The more interesting moment was what typing debrief:provenance_log properly uncovered. Spec #240 had generated a wide PropertiesProvenanceEntry (all fields from LinkML) but the consuming component had narrowed it to a local hybrid — an as cast was bridging the mismatch invisibly. Once the props bag gained a proper type, the cast was gone and pyright surfaced the divergence. The fix — an explicit typed narrowing bridge from the persistence shape to the domain shape — is the kind of thing that should have been written at #240. The types found a real latent bug, which is the point of this entire class of work.

The half-naivety trap bears repeating: if you only fix the read path, you get a false sense of safety. Both writer hosts had widened item.properties to Record<string, unknown> at the mutation site. That’s where a field gets added to a schema, a developer writes props['debrief:newField'] = value with a typo, and nothing complains until the data shows up missing downstream. Re-typing the write path from Record<string, unknown> to StacItemProperties is the move that actually closes the loop.

What’s Next

The same schema-driven technique — read slot_uri, emit the on-disk key verbatim — is now the established pattern for any future debrief:* slot. The generator step is a pure function; a new slot in the schema flows through to every writer host’s typed surface automatically. No hand-edits, no drift.

One thing we deliberately left out: debrief:label. It’s a GeoJSON feature property and an MCP annotation, not a STAC item property, and modelling it onto StacExtensionProperties would recreate the very mismatch this feature removes. Giving it a typed home on BaseFeatureProperties is the natural next step when that surface gets attention.

→ See the spec → View the evidence

Saving a plot writes three things: the feature collection (features.geojson), the STAC metadata (item.json), and the thumbnail PNGs. Until now those were three independent writes done in sequence, and the “Plot saved” confirmation fired before the last of them had necessarily landed. Most of the time that is invisible. But if anything goes wrong partway through — the disk fills up, a permission is denied, the browser hits its storage quota, or the machine simply dies mid-write — you could be left with a plot that is quietly broken: new geometry against stale metadata, or a half-written file that won’t open.

This spec closes that gap. A save is now atomic from the analyst’s perspective (FR-001): after any save attempt, the persisted plot is observable as either the complete new state or the complete previous state, never a partial mixture. The success marker only appears once every write that makes up the save has committed (FR-005). And if a save is cut off by something we can’t catch — a crash, a power loss — reopening the plot yields a single coherent version rather than a corrupt one (FR-007). We deliberately aimed for coherence, not power-loss durability of the newest in-flight save: the guarantee is that you never lose or corrupt what was already there, not that the very last keystroke survives the plug being pulled.

How It Works

Atomicity is concentrated behind the persistence boundary rather than scattered across frontend code. We added two host-agnostic operations to the StacWriter interface (shared/stac-writer/src/interface.ts): commitPlotSave, which commits the whole save unit as one, and reconcilePlotSave, which runs on open before the first read to heal any interrupted save. Each host implements the pair against its native backend.

On the VS Code filesystem adaptor (apps/vscode/src/services/stacWriterFs.ts), the commit point is a write-ahead intent journal:

flowchart LR
  A[Stage all new files<br/>as temporaries] --> B[Atomically write journal<br/>listing pending renames]
  B -->|COMMIT POINT| C[Apply renames]
  C --> D[Delete journal]

If we die before the journal exists, nothing has moved — reconcilePlotSave discards the temporaries and the previous plot is byte-identical. If we die after it exists, the journal tells reconciliation exactly which renames to roll forward to finish the save. The journal’s presence or absence is the single bit that decides roll-forward versus roll-back, and the temp-write plus rename reuse the adaptor’s existing atomicWriteSync helper.

On the web-shell adaptor (apps/web-shell/src/services/stacWriterIdb.ts), there is no journal to invent: the three writes collapse into a single multi-store IndexedDB transaction and lean on IndexedDB’s native atomicity. The call site in apps/web-shell/src/mocks/stacService.ts swapped its separate writeItem + writeAsset calls for one commitPlotSave.

The honest-reporting half lives at the call sites. apps/vscode/src/commands/saveSession.ts moves its markClean / “Plot saved” marker to after the commit returns, and a failure now surfaces through window.showWarningMessage while preserving the dirty editor state for retry. apps/vscode/src/commands/openPlot.ts calls reconcilePlotSave before loadPlotData, so every open heals first and reads second.

No new runtime dependencies — just node:fs / node:crypto on the desktop and the existing idb library in the browser.

Key Decisions

• The boundary owns atomicity, not the frontend (Article IV). The feature-collection write moved off a raw fs.writeFileSync onto the @debrief/stac-writer boundary, so neither host can regress it and the logic lives in exactly two adaptors.
• Coherence over durability, on purpose. Guaranteeing the newest in-flight save survives power loss would have meant fsync barriers and a heavier design. The narrower “never corrupt, never half-update” guarantee removed the silent-corruption risk entirely at a fraction of the cost.
• Pick-derived DTOs. The CommitPlotSaveInput type is derived rather than hand-listed, so a new save artifact can’t be silently omitted from a commit — the omission becomes a compile error.

By the Numbers

Three properties are enforced mechanically: exactly one IndexedDB transaction per save, zero success messages for an uncommitted save, and compile-time guards against omitted fields. A fault-injection matrix exercises interruption points across both backends — every one resolves to a single coherent version.

What’s Next

This makes the persistence boundary the right place to add any future durability knob, should analyst feedback ask for one — the commit point is now a single, named operation per host rather than a sequence of bare writes. For now, the half-updated plot is gone: a save either lands or it doesn’t, and you always reopen something whole.

→ See the spec → View the evidence

flowchart LR
  subgraph PlotDir["a plot on disk (three files)"]
    Item["item.json — catalog metadata"]
    Features["features.geojson — tracks, points, annotations"]
    Sidecar["item.debrief-session — viewport, time window, playhead, selection, hidden features"]
  end
  Features -. emailed / committed / copied .-> Colleague["Colleague's machine"]
  Sidecar -. left behind .-x Colleague

After — the sidecar is gone. A plot is two files, and the entire interactive view rebuilds from features.geojson alone:

flowchart LR
  subgraph PlotDir["a plot on disk (two files)"]
    Item["item.json — catalog metadata"]
    subgraph Features["features.geojson"]
      Geo["tracks, points, annotations (with visible flags)"]
      SS_SP["SystemState: state.spatial"]
      SS_TM["SystemState: state.temporal"]
      SS_SE["SystemState: state.selection"]
      SS_AS["SystemState: state.activestoryboard"]
    end
  end
  Features -. emailed / committed / copied .-> Colleague["Colleague's machine — same view, time, selection"]

What We Built

When you save a plot today, the part of it you were actually looking at gets left behind. The map viewport, the analytical time window, the playhead position, the feature selection, which features you’d hidden — all of it lives in a sibling file, the item.debrief-session sidecar, that gets stripped the moment the plot leaves your machine. Email a colleague the GeoJSON, pull it from a STAC catalogue, check it out of git, copy it to a USB stick, and they open it on the default global view, a default time window, and an empty selection. The portable artefact — features.geojson — carries none of the state that makes the plot yours.

This work deletes the sidecar entirely. Every field it held is given a proper home: plot state (viewport, time window, playhead, selection, active storyboard) becomes a handful of SystemState Features written directly into the FeatureCollection, addressed by deterministic ids like state.spatial and state.temporal; per-feature state — visibility — becomes a visible flag on the individual feature it describes, so hiding a track travels with that track; and genuinely ephemeral runtime — whether you’re currently playing, transient drawing mode, a viewport lock — simply isn’t persisted, and defaults cleanly on load. After this, a plot is exactly two files, item.json and features.geojson, and the whole interactive state is reconstructable from the GeoJSON alone. Hand a colleague a single file and they open it exactly where you left it.

How It Fits

This is the payoff of two principles the project has held from the start: schema-first single source of truth, and the plot file as the one portable, canonical artefact. Until now those principles were quietly contradicted by the sidecar — a second persistence path that split plot state across two files, only one of which travelled. The fix generalises a pattern that already shipped for a single case: #237 introduced the SystemState Feature for the active-storyboard pin, and this work makes that the general home for all non-spatial plot state. The same shape on disk, the same deterministic addressing, now covering spatial, temporal, and selection too. It also substantially narrows a separate planned piece of work — web-shell session persistence — because the VS Code extension and the browser web-shell now read and write the same FeatureCollection through one shared helper, rather than each carrying its own persistence path.

Key Decisions

• Everything that looked like “session state” is actually plot state. The earlier assumption that playback speed, step size, the time filter, and display mode were per-user preferences turned out to be wrong: they describe the data being replayed, not the person replaying it, so they belong to the plot. Once that lands, the design collapses — there is no residual per-user bucket left for the sidecar to hold, which is precisely why the sidecar can be deleted outright rather than merely shrunk. No replacement store.

• One shared read/write helper, not one per host. Both frontends — the VS Code extension and the web-shell — go through a single helper that owns reading and writing every SystemState variant. #237’s host-private writer is folded into it. Plot-load and plot-save become the only two places this state is touched, so the two hosts can never drift into divergent persistence behaviour.

• Exploration never marks the plot dirty. Panning, zooming, scrubbing the time cursor, changing the selection — none of these flag unsaved changes. Merely looking at a plot should never nag you to save. An explicit Save still commits the current view; only substantive content edits drive the unsaved-changes prompt. The state is captured in memory as you explore and persisted only when you choose to save.

• Visibility lives on the feature, not in a separate list. Hiding a track sets visible: false on that track and records it in the track’s own provenance log. We accept that the provenance grows a little as the price of visibility travelling with the feature it describes — a hidden track stays hidden when the plot moves, with no separate hidden-list to keep in sync.

• Strict on import. A malformed or self-contradictory saved state — a playhead sitting outside its own time window, say — fails loudly with a clear error that names the offending feature. Never a silent default, never a quiet clamp. If the plot file claims something impossible, you find out immediately and you find out where.

Screenshots

The whole round-trip in one loop — host A sets a view, only features.geojson is carried across, and host B rebuilds the same view (then the visibility round-trip):

The headline test is a round-trip across two hosts. Host A gets a recognisable viewport, a scoped time window, a scrubbed playhead, and a feature selection — the kind of state the sidecar used to strand on the machine that created it.

Host A: the view we want to travel — viewport, scoped time window, playhead, and selection.

Then we copy only features.geojson to a different machine — no STAC catalogue, no sidecar, just the one file — and open it. The whole view comes back. The title bar reads transferred/plot.geojson, the playhead has restored to 09:30:00, and track-hms-defender is selected, all rebuilt from the GeoJSON alone.

Host B: the same view, restored from features.geojson alone. No sidecar was carried across.

Visibility travels the same way. A feature hidden on host A carries properties.visible: false on the feature itself, so a features-only reopen keeps it hidden — there is no separate hidden-list to lose.

Host A: a feature hidden.

Host B: still hidden after a features-only reopen — the visible flag rode along on the feature.

And when a saved state contradicts itself — a current_time outside its own [start_time, end_time], or a duplicate state_type — load fails loudly. The error banner names the offending feature id rather than silently clamping or falling back to a default.

Strict-on-import: a self-contradictory saved state fails loudly and names the feature at fault.

By the Numbers

The four suites are schema adherence (Python, 1071), session-state (Vitest, 696), the VS Code extension (Vitest, 845), and the web-shell Playwright round-trip. A plot dropped from three files to two. The split persistence story — a web-shell-private active_storyboard writer plus a VS Code extension that wrote no SystemState at all — collapsed into one shared helper that is now the sole producer and consumer of every variant, covered by 42 focused unit tests.

The one risk we flagged in planning (FR-006a) was that gen-json-schema had a known bug with Coordinate as a multivalued class range — exactly the shape of ViewportPolygon.coordinates — and moving viewport onto SystemStateProperties (which is in the JSON Schema build) might resurface it. It didn’t. The existing generate.py post-processor pattern already handled the case; it was a non-event.

Lessons Learned

A type name collision had to be paid off before anything else could move. The schema cluster held two different things both called Coordinate — a scalar type in one file and a lng/lat class in another. As long as the duplicates lived in separate schemas this stayed dormant, but SystemStateProperties lives in geojson.yaml, which imports common.yaml, and pointing viewport at the canonical ViewportPolygon meant consolidating all the shared value types into common.yaml first. The moment they shared a namespace, the two Coordinates collided and the consolidation had to resolve which one survived. The prerequisite refactor was larger than the feature it unblocked.

A circular dependency decided where one variant’s logic lives. We wanted the shared helper to own all four SystemState variants. But active_storyboard originally read through @debrief/components, and routing the helper back through that package would have closed a dependency loop. So the helper implements the active-storyboard wire shape natively — verbatim to #237’s format (NG-002), just no longer borrowed. The web-shell’s interactive read of active-storyboard deliberately stays on the tolerant @debrief/components helper (R-011), because that read runs on every edit and the strict load reader throws on a duplicate or malformed feature. The shared helper owns the unified load-time read of all four variants and is the single writer for the three migrated ones; no host re-implements the wire shape.

Reclassifying view-state as exploration was the real unlock. The rule that panning, zooming, scrubbing, and selecting never mark the plot dirty (FR-019) reads like a UX nicety, but it forced a second decision that made the whole thing usable: an explicit Save now persists the current view regardless of the dirty flag (FR-020). VS Code’s save command used to early-return “no unsaved changes” when the plot wasn’t dirty — which, once view-state stopped setting the flag, would have made a looked-at-only view impossible to save at all. Relaxing that guard is what lets you open a plot, arrange the view you want, and commit it without having edited a single feature.

What’s Next

A few follow-ups are scheduled rather than done:

• #250 — web-shell durable persistence. This work landed the in-memory mirror (FR-009a): view-state is written into the FeatureCollection, which the web-shell already auto-persists to IndexedDB. The residual is the auto-commit-trigger UX — when to debounce a viewport nudge versus require an explicit gesture — which is a UX decision, not a persistence-mechanism gap.
• #266 — purge stale references. The legacy bbox / center fields are removed from the schema; lingering mentions in docs and ADRs still need a sweep.
• #267 — out-of-window current_time policy. Strict-on-import is the chosen default; whether a tolerant import path is ever warranted is parked here, to be revisited only if strict proves user-hostile.
• #268 — broader multi-asset save atomicity. With the sidecar gone, the dual-write failure class is gone too. The wider question — features.geojson versus thumbnails versus item.json written transactionally — is its own item.

→ See the spec → View the evidence

When you assemble a Storyboard, each time-range Scene claims a window of the exercise — a stretch of [start, end] you want replayed. Most of the time those windows sit end to end: Scene A hands off to Scene B, B to C, and the story walks forward through time. But sometimes two Scenes quietly cover the same stretch — you nudged a window while editing, or duplicated a Scene and forgot to move it, and now the same minutes get replayed twice without you meaning them to. Nothing breaks, so nothing tells you.

This adds a quiet tell. When two time-range Scenes overlap, each offending row in the Storyboard panel grows a small warning that names its partner — “Overlaps with Egress leg” — so the accidental double-cover is visible at a glance instead of waiting to be noticed on playback. It is deliberately a nudge, not a rule. The platform never reorders, merges, rejects, or blocks a thing. If the overlap is intentional — a deliberate re-play to land an emphasis — you dismiss the warning and it stays gone for the session. The aim is to catch authoring drift without putting the platform in the business of policing a legitimate creative choice.

How It Fits

This is a follow-up to #263, which shipped time-range Scenes but left overlap detection to authoring discipline. It is the lightweight safety net that closes that gap — TypeScript-only, frontend-only, no schema change and no service call. Detection lives in one pure, synchronous helper, detectSceneOverlaps() in shared/components/src/storyboard/overlap.ts, consumed verbatim by both the VS Code extension and the web-shell so the two surfaces can’t drift in what they consider an overlap. The warning itself is a new presentational OverlapBadge that reuses the per-row slot pattern already established for the stale indicator, and the whole thing is a read-only derivation over data already in the plot — offline by default, like everything else.

import { detectSceneOverlaps } from '@debrief/components';

// plot = the FeatureCollection; storyboardId = the active Storyboard;
// dismissedPairs = optional Set of dismissed pair keys.
const overlaps = detectSceneOverlaps(plot, storyboardId, dismissedPairs);
// -> ReadonlyMap<sceneId, { sceneId; title }[]>
//    non-overlapping and instant Scenes are simply absent

Each host computes overlaps from the active-Storyboard Scene set it already holds, merges the result into the per-row view-model, and owns its own dismissed-pairs set — apps/vscode/src/views/storyboardPanelView.ts on one side, apps/web-shell/src/StoryboardPanelMount.tsx on the other. The host code only wires data in and renders the result.

Key Decisions

• Strict interior overlap, not touching endpoints. The rule is aStart < bEnd && bStart < aEnd on epoch milliseconds. Scenes that merely meet at an edge — A ends exactly where B starts — are a normal contiguous handoff and produce no warning. Well-formed sequential Storyboards stay completely clean, which is what keeps the signal worth trusting.
• Time-range Scenes only. Instant, single-timestamp Scenes are excluded; their timestamp collisions are a separate existing flow, and folding them in here would muddy the meaning of the badge.
• One shared helper, two hosts. detectSceneOverlaps() is a single pure function in shared/components. Putting the rule in one place — rather than implementing it twice — means the VS Code panel and the web-shell can never disagree about what overlaps.
• Dismissal is session-scoped, keyed by the unordered Scene pair, and not persisted. Dismissing clears the warning on both rows; pull the windows apart and re-overlap them and it warns afresh. We deliberately kept this out of plot state — no new persisted field — to hold the feature at the one-to-two-dev-day aid it was scoped to be. A deliberate overlap you re-open in a new session warns again, and that felt like the right default: better to re-confirm intent than to silently carry a stale “I meant this” forever.
• Passive and non-blocking, by design. No reorder, no merge, no rejection. Accidental overlaps are a mistake worth surfacing; intentional ones are a creative decision the platform has no business overruling. The badge respects that line.

Screenshots

The warning is a per-row badge naming the conflicting Scene. Two overlapping Scenes each warn about the other; the non-overlapping range Scene and the instant Scene below stay clean.

Light theme. “Approach run” (10:00–10:30) and “Egress leg” (10:15–10:45) overlap; each warning names the other. “Final approach” and the instant “Contact datum” stay clean.

The badge inherits the theming of the existing stale-indicator slot, so it lands correctly across all three theme variants without any new colour work.

Dark theme.

VS Code theme.

Clicking Dismiss on either badge clears the warning on both rows at once. Nothing in the plot changes — the Scene windows are untouched.

After dismiss — pair it with the light-theme shot above as a before/after. (A static pair stands in for an animated clip.)

By the Numbers

Lessons Learned

The crux of this was the overlap rule itself: strict interior overlap versus inclusive of touching endpoints. Getting it wrong — treating A.end === B.start as an overlap — would have warned on every normal sequential handoff, which is the most common arrangement in any well-formed Storyboard. The badge would have lit up everywhere and the signal would have drowned in its own noise. The single-character difference between < and <= was the whole feature working or being useless.

Two structural choices paid off quietly. Reusing the existing per-row stale-badge slot meant the warning dropped in with no new layout risk and inherited the accessible, contrast-safe theming that slot already had — which is why the three theme variants passed without separate colour work. And keeping detection as one shared pure function, rather than implementing the rule once in the VS Code panel and again in the web-shell, is what guarantees the two hosts can’t disagree about what counts as an overlap.

What’s Next

Dismissal is session-scoped today — re-open the plot in a new session and an intentional overlap warns again, which we chose deliberately. If analyst feedback shows people would rather their dismissals survived reloads, persisting them is the natural follow-up. Otherwise this closes the FR-SCO-003 gap deferred from #263, and there is nothing further owed here.

→ See the spec → View the evidence

What We Built

When you open a plot whose saved playhead position falls outside its saved analytical time window, the plot now opens. The playhead clamps to the nearest window edge — start if it undershot, end if it overshot — and a notification explains the adjustment. You land in your colleague’s analysis at a sensible moment instead of staring at a load failure.

This closes a sharp edge introduced when we moved the playhead position into the plot file. The realistic case: you scrub the playhead to a moment, later trim the analytical window to a tighter span, and save. The playhead is now orphaned outside the new window — the window itself is fine, only the playhead points past it. Under the old strict rule, the plot wouldn’t open at all: a heavy penalty for a trivially recoverable mismatch on a non-critical, re-derivable field. The genuinely broken case — a window where start_time > end_time — keeps its hard failure. Tolerance is granted only where recovery is real.

How It Fits

This is the deliberate revisit our own Constitution asked for. Spec-261 put the playhead in the plot file and shipped strict-on-import validation under Article XIV.4 (“strict on import, fail fast”) to keep the data contract clean during pre-release — but Article XIV’s trigger note explicitly flagged that those clauses “should be revisited to introduce appropriate tolerance for real-world data ingestion.”

This is that revisit, kept honest by being maximally narrow: one field (current_time), one variant (temporal), one precondition (a coherent surrounding window). The clamp logic lives once in the shared @debrief/session-state load layer that both the VS Code extension and the browser-based web-shell consume — concretely in read.ts (the clamp + diagnostic), validate.ts (the recoverable-vs-fatal severity split), and store-bridge.ts (hydrateStoreFromFeatures, the shared load entry). Each host only decides how to render the resulting diagnostic. There is no schema change — the field already exists. This is a behavioural amendment to the load path, not a new contract.

How It Works

• A sanctioned relaxation, not a free-for-all. Tolerance applies to exactly one field, one variant, and only when the window is coherent. The unrecoverable start > end case keeps its hard, structured load error as the guard rail. Tolerance never leaks into structurally broken data.
• Clamp to the nearest edge, don’t discard. Moving the playhead to the closer boundary preserves the analyst’s intent — start if they undershot, end if they overshot — rather than dumping it back to the window start regardless of direction.
• Never silent. Article I.3 says users must always know the state of their data, so every clamp surfaces a non-blocking notification on every load until you save the corrected position. The relaxation makes the data issue loud while still letting you work.
• Single-sourced rule, host-rendered UI. The clamp decision is made once in the shared load layer; the VS Code host renders a warning notification and the web-shell renders a toast. Services emit data, frontends own presentation.
• No dirty-on-open. The clamp is in-memory only — it doesn’t mark the plot modified or auto-save, preserving the predecessor’s “scrubbing doesn’t dirty the file” contract. The orphaned value heals in the file only when you next save; re-opening before that re-clamps idempotently.

Screenshots

The tolerant recovery (User Story 1): a plot with current_time past the window end opens successfully. An amber notification bar reports that the saved time-cursor was outside the time range and was moved to the window end. No modal, no blocking — the plot is already open and the playhead is already positioned on the nearest edge.

The preserved guard rail (User Story 2): an incoherent window (start_time > end_time) still surfaces the red cross-field-invariant error banner naming the offending feature and field values. The plot does not open. The tolerant path was never reached.

By the Numbers

Lessons Learned

The original integration plan used the web-shell’s existing LogPanel transient — the actionResultMessage slot — as the notification surface for the clamp. The problem: actionResultMessage is rendered only while the Log tab is mounted. Setting it during load, before the analyst has navigated to that tab, means the notice fires into an unmounted component and silently disappears. You open a plot, a message is set, the Log panel is somewhere else in the layout, and nothing is ever shown.

The fix was a dedicated App-level toast, distinct from the error banner, rendered unconditionally at the application root, so it is always visible in the context where the load event fires. The general lesson: a “non-blocking notification” surface must be visible where the event happens, not buried in a panel the user may not be looking at. A notification that requires the user to already be on the right tab is effectively silent.

What’s Next

Two items were deliberately deferred during review as YAGNI and captured in the backlog: coalescing multiple clamp notifications into one summary if a batch or session-restore load path is ever added (both hosts load plots one at a time today), and generalising the playhead clamp diagnostic into a reusable recoverable-load diagnostics channel once a second tolerant-import case is commissioned.

→ See the spec → View the evidence

A briefing leaves Debrief as a single .zip file. The recipient unzips it on any machine with a modern browser — a classified workstation, a stakeholder’s laptop, a training-room PC with the network cable out — double-clicks index.html, and the Storyboard plays. Same Scene order, same viewport tweens, same time-slider scrub through every time-range Scene from #263, same per-frame track motion. No install, no extension host, no server, no network call. The zip carries its own basemap tiles, its own Scene thumbnails, its own GeoJSON, its own SPA.

Two viewing modes live behind a hover-revealed toggle. Minimal shows a transport bar (play, pause, next/previous Scene) and a scrubber, for an interactive walkthrough where the audience wants to stop on a moment. Present hides every control and lets the map fill the screen, for the room where the briefer is talking and the screen should just be the picture. Mode survives the toggle; playback position survives the toggle; nothing about the rendering changes between them — only what chrome is on top.

How It Fits

The briefing renderer is the second consumer of the Storyboard playback engine that #217 and #258 built and #263 extended for time-range Scenes. That engine — StoryboardPlaybackService — moved during this feature out of apps/vscode/ into shared/components/src/storyboardPlayback/service.ts. The hoist is net-zero behaviour for the VS Code app (every pre-existing test passes against the relocated service via a thin re-export shim) but it removes the structural barrier to a second consumer: the briefing renderer can now compose the same service directly when its playback surface grows beyond the current read-only minimum.

The new SPA at apps/briefing-renderer/ (sibling to apps/backlog-navigator/ and apps/spec-navigator/) currently composes a smaller SPA-local driver around the host-agnostic runTimeRangeTween primitive that #263 placed in shared/components/ — sufficient for a recipient-side playback view, and a clean swap target for the full service when the briefing grows interactive editing. Four browser-side port adapters (Map, SessionStore, PanelView, TimeRangeView) sit between the driver and Leaflet, the local Zustand store, and the chrome surface.

The export command lives in the VS Code extension as debrief.storyboard.exportAsBriefingZip, and the pre-built SPA bundle ships as a static resource inside the extension so every export is reproducible from the version of the tool that produced it.

Key Decisions

• Inline the data, don’t fetch() it. Browsers restrict fetch() from file:// origins by design. The export injects features.geojson and item.json into index.html as <script type="application/json"> blocks, and binary assets (Scene thumbnails, basemap tiles) load through ordinary relative <img> and Leaflet TileLayer paths — which file:// allows. This is the pattern that lets the zip work on a totally cold machine.
• Strip Vite’s crossorigin attribute from the built <script> and <link> tags. Chrome and Edge apply CORS to module scripts that carry that attribute, and the file:// origin can never pass a CORS check — the attribute would cause the renderer to fail at boot. A 30-line post-build script (scripts/strip-crossorigin.mjs) removes it. The Playwright suite catches any regression: the file-protocol spec opens the built index.html from a real file:// URL and asserts the SPA mounts.
• Pre-fetch tiles per Scene at export time, including the interpolation path. Each Scene’s captured viewport and zoom give a tile set; for time-range Scenes we sample the viewport tween between viewport_start and viewport_end and union the coverage so mid-scrub pans never hit a missing tile. The bytes go in tiles/{z}/{x}/{y}.png. The zip is the basemap server.
• Boundary types derived, not re-listed. BriefingFeatureCollection = StoryboardPlot; BriefingItemJson is a strict subset of the source plot’s STAC item.json. Constitution Article IV.5 applies; future fields on the source flow through automatically rather than disappearing silently into a recipient’s briefing.
• One new dependency: jszip. Pure JS, MIT-licensed, no native binaries, used only at export time inside the VS Code extension. Considered shelling out to zip(1) and rejected on cross-platform grounds (Windows hosts).
• Export per Storyboard, not per plot. The command lives on the Storyboard’s own overflow menu — there is no ambiguity about which one you exported, even when a plot accumulates several over an exercise’s iteration. The scoping pass walks the chosen Storyboard’s SceneFeature references and includes only the features they actually touch.
• Browser scope narrowed to current Chrome and Edge on desktop. The original four-browser matrix (add Firefox + Safari) doubled the loader work for a marginal audience gain. The supported pair shares the same file://-origin loading rules; the SPA’s boot-time browser probe surfaces a banner naming the supported browsers when opened in Firefox / Safari / mobile — Article I.3, no silent failure. Captured as ADR-NEW (2026-05-20).
• Hoist the playback service, but ship a smaller driver for now. The 983-line StoryboardPlaybackService was tightly bound to vscode.Event and vscode.workspace.fs. The hoist replaces those with a host-agnostic HostEvent<T> / HostEventEmitter<T> pair (structurally compatible with vscode.EventEmitter — the VS Code app’s vscode.EventEmitter instances pass through unchanged) and lifts the three vscode-backed defaults (showErrorMessage, setContext, showInformationMessage) up to the instantiation site. The shared service is now the single source of truth; the VS Code app composes it via a thin re-export shim, and 840 pre-existing vscode tests pass against the new module unchanged.

Screenshots

Minimal mode (default) vs Present mode

The recipient lands in Minimal mode — title bar, transport, time slider all visible. Pressing P (or clicking Enter Present (P)) hides every control and the map fills the viewport.

Minimal mode (default)	Present mode

The two components in isolation

The TransportBar exposes play/pause, prev/next Scene, and a Replay button that appears in place of Next at the final Scene. The ModeToggle is always visible in Minimal mode and hover-revealed in Present mode (the P key works in both).

TransportBar — Idle	TransportBar — End of Storyboard

ModeToggle — Minimal	ModeToggle — Present (hover-revealed)

MapView with the briefing-friendly tile-layer props (T-MAPVIEW-EXT)

The four new MapView props (errorTileUrl, maxZoom, noWrap, tileLayerCrossOrigin) — captured in three themes from the shared-components Storybook. Defaults preserve today’s behaviour for every existing MapView consumer.

light	dark	vscode

Failure-mode surfaces (Article I.3)

The empty state when a Storyboard has no Scenes; the error state when the inline JSON is unreadable; and the “playback halted” state any adapter throw or tween rejection transitions into. None of the three is silent — every recipient sees an explicit message.

Empty state	Error state	Playback halted

Interaction GIF

The mode-toggle + playback flow, captured via Playwright recordVideo and post-processed with ffmpeg into a small looping GIF (~100 KB, well under the 2 MB target).

By the Numbers

• One new SPA workspace at apps/briefing-renderer/ — Vite + React 18 + Zustand + react-leaflet 4.2 — ~1 500 LOC TS including tests.
• One major hoist: StoryboardPlaybackService (983 lines) moved from apps/vscode/src/services/ to shared/components/src/storyboardPlayback/. The four port interfaces split out into ports.ts; the vscode.EventEmitter dependency replaced by a host-agnostic HostEventEmitter<T>; the three vscode.window.* defaults lifted to the instantiation site. Zero behaviour change — all 49 pre-existing storyboardPlayback tests pass against the relocated service.
• New VS Code command surface: debrief.storyboard.exportAsBriefingZip + a 6-step orchestrator (scopeStoryboard, buildItemJson, computeTileCoverage, fetchTiles, injectInlineData, assembleZip).
• 935 passing tests across the feature surface (no failures): 840 vscode vitest cases (including 60 new briefing-zip-export cases + 49 pre-existing storyboardPlayback tests against the hoisted service), 58 briefing-renderer vitest cases (loader, probes, adapters, playback driver, halted-state, TransportBar, ModeToggle, TimeSlider, boot), 31 MapView vitest cases (9 new for briefing props), and 19 Playwright E2E specs.
• 19 Playwright specs, all passing: 16 in the briefing-renderer suite covering the file:// boot, network isolation (SC-002), 10× mode toggle (SC-005), failure-mode surfaces, screenshot producers, story-mode component captures, the end-to-end real-export → real-unzip → real-play test, and the interaction GIF; plus 3 in shared/components covering the MapView briefing-props story in all three theme variants.
• One new runtime dependency (jszip ^3.10.1) in the VS Code extension; no new dependencies in the SPA beyond React, Leaflet, react-leaflet, and Zustand.

What’s Next

• Swap the SPA-local driver for the hoisted StoryboardPlaybackService once the briefing renderer needs the additional surface area the full service provides (Scene-rectangle click handling, snapshot stream, missing-data detection). With T-HOIST already complete this is now a small follow-up rather than the architectural blocker it once was.
• PMTiles basemap (#272) when zip size becomes a real transport problem — the integer-zoom-only policy in #264’s research caps typical zips around 50 MB but very large Storyboards may exceed that.
• MP4 / GIF export (#265 — research spike) for the audience that wants a recorded playback rather than an interactive one.
• Bidirectional time-range scrubbing in the briefing SPA’s time slider — the slider currently reads the engine’s frame-by-frame writes; letting the user drag it backwards through a tween is the next polish step.
• Multi-theme support in the briefing renderer so the chrome ships in light / dark / vscode variants alongside the MapView prop matrix already covered.

→ See the spec → View the evidence

A briefing leaves Debrief as a single .zip file. The recipient unzips it on any machine with a modern browser — a classified workstation, a stakeholder’s laptop, a training-room PC with the network cable out — double-clicks index.html, and the Storyboard plays. Same Scene order, same viewport tweens, same time-slider scrub through every time-range Scene from #263, same per-frame track motion. No install, no extension host, no server, no network call. The zip carries its own basemap tiles, its own Scene thumbnails, its own GeoJSON, its own SPA.

Two viewing modes live behind a hover-revealed toggle. Minimal shows a transport bar (play, pause, next/previous Scene) and a scrubber, for an interactive walkthrough where the audience wants to stop on a moment. Present hides every control and lets the map fill the screen, for the room where the briefer is talking and the screen should just be the picture. Mode survives the toggle; playback position survives the toggle; nothing about the rendering changes between them — only what chrome is on top.

How It Fits

The briefing renderer is the second consumer of the Storyboard playback engine that #217 and #258 built and #263 extended for time-range Scenes. That engine — StoryboardPlaybackService — moved during this feature out of apps/vscode/ into shared/components/src/storyboardPlayback/service.ts. The hoist is net-zero behaviour for the VS Code app (every pre-existing test passes against the relocated service via a thin re-export shim) but it removes the structural barrier to a second consumer: the briefing renderer can now compose the same service directly when its playback surface grows beyond the current read-only minimum.

The new SPA at apps/briefing-renderer/ (sibling to apps/backlog-navigator/ and apps/spec-navigator/) currently composes a smaller SPA-local driver around the host-agnostic runTimeRangeTween primitive that #263 placed in shared/components/ — sufficient for a recipient-side playback view, and a clean swap target for the full service when the briefing grows interactive editing. Four browser-side port adapters (Map, SessionStore, PanelView, TimeRangeView) sit between the driver and Leaflet, the local Zustand store, and the chrome surface.

The export command lives in the VS Code extension as debrief.storyboard.exportAsBriefingZip, and the pre-built SPA bundle ships as a static resource inside the extension so every export is reproducible from the version of the tool that produced it.

Key Decisions

• Inline the data, don’t fetch() it. Browsers restrict fetch() from file:// origins by design. The export injects features.geojson and item.json into index.html as <script type="application/json"> blocks, and binary assets (Scene thumbnails, basemap tiles) load through ordinary relative <img> and Leaflet TileLayer paths — which file:// allows. This is the pattern that lets the zip work on a totally cold machine.
• Strip Vite’s crossorigin attribute from the built <script> and <link> tags. Chrome and Edge apply CORS to module scripts that carry that attribute, and the file:// origin can never pass a CORS check — the attribute would cause the renderer to fail at boot. A 30-line post-build script (scripts/strip-crossorigin.mjs) removes it. The Playwright suite catches any regression: the file-protocol spec opens the built index.html from a real file:// URL and asserts the SPA mounts.
• Pre-fetch tiles per Scene at export time, including the interpolation path. Each Scene’s captured viewport and zoom give a tile set; for time-range Scenes we sample the viewport tween between viewport_start and viewport_end and union the coverage so mid-scrub pans never hit a missing tile. The bytes go in tiles/{z}/{x}/{y}.png. The zip is the basemap server.
• Boundary types derived, not re-listed. BriefingFeatureCollection = StoryboardPlot; BriefingItemJson is a strict subset of the source plot’s STAC item.json. Constitution Article IV.5 applies; future fields on the source flow through automatically rather than disappearing silently into a recipient’s briefing.
• One new dependency: jszip. Pure JS, MIT-licensed, no native binaries, used only at export time inside the VS Code extension. Considered shelling out to zip(1) and rejected on cross-platform grounds (Windows hosts).
• Export per Storyboard, not per plot. The command lives on the Storyboard’s own overflow menu — there is no ambiguity about which one you exported, even when a plot accumulates several over an exercise’s iteration. The scoping pass walks the chosen Storyboard’s SceneFeature references and includes only the features they actually touch.
• Browser scope narrowed to current Chrome and Edge on desktop. The original four-browser matrix (add Firefox + Safari) doubled the loader work for a marginal audience gain. The supported pair shares the same file://-origin loading rules; the SPA’s boot-time browser probe surfaces a banner naming the supported browsers when opened in Firefox / Safari / mobile — Article I.3, no silent failure. Captured as ADR-NEW (2026-05-20).
• Hoist the playback service, but ship a smaller driver for now. The 983-line StoryboardPlaybackService was tightly bound to vscode.Event and vscode.workspace.fs. The hoist replaces those with a host-agnostic HostEvent<T> / HostEventEmitter<T> pair (structurally compatible with vscode.EventEmitter — the VS Code app’s vscode.EventEmitter instances pass through unchanged) and lifts the three vscode-backed defaults (showErrorMessage, setContext, showInformationMessage) up to the instantiation site. The shared service is now the single source of truth; the VS Code app composes it via a thin re-export shim, and 840 pre-existing vscode tests pass against the new module unchanged.

Screenshots

Minimal mode (default) vs Present mode

The recipient lands in Minimal mode — title bar, transport, time slider all visible. Pressing P (or clicking Enter Present (P)) hides every control and the map fills the viewport.

Minimal mode (default)	Present mode

The two components in isolation

The TransportBar exposes play/pause, prev/next Scene, and a Replay button that appears in place of Next at the final Scene. The ModeToggle is always visible in Minimal mode and hover-revealed in Present mode (the P key works in both).

TransportBar — Idle	TransportBar — End of Storyboard

ModeToggle — Minimal	ModeToggle — Present (hover-revealed)

MapView with the briefing-friendly tile-layer props

The four new MapView props (errorTileUrl, maxZoom, noWrap, tileLayerCrossOrigin) — captured in three themes from the shared-components Storybook. Defaults preserve today’s behaviour for every existing MapView consumer.

light	dark	vscode

Failure-mode surfaces

The empty state when a Storyboard has no Scenes; the error state when the inline JSON is unreadable; and the “playback halted” state any adapter throw or tween rejection transitions into. None of the three is silent — every recipient sees an explicit message.

Empty state	Error state	Playback halted

Interaction

The mode-toggle and playback flow, captured via Playwright recordVideo and post-processed with ffmpeg into a small looping GIF (~100 KB, well under the 2 MB target).

By the Numbers

• One new SPA workspace at apps/briefing-renderer/ — Vite + React 18 + Zustand + react-leaflet 4.2 — ~1,500 LOC TS including tests.
• One major hoist: StoryboardPlaybackService (983 lines) moved from apps/vscode/src/services/ to shared/components/src/storyboardPlayback/. The four port interfaces split out into ports.ts; the vscode.EventEmitter dependency replaced by a host-agnostic HostEventEmitter<T>; the three vscode.window.* defaults lifted to the instantiation site. Zero behaviour change — all 49 pre-existing storyboardPlayback tests pass against the relocated service.
• New VS Code command surface: debrief.storyboard.exportAsBriefingZip + a 6-step orchestrator (scopeStoryboard, buildItemJson, computeTileCoverage, fetchTiles, injectInlineData, assembleZip).
• 935 passing tests across the feature surface (no failures): 840 vscode vitest cases (including 60 new briefing-zip-export cases + 49 pre-existing storyboardPlayback tests against the hoisted service), 58 briefing-renderer vitest cases (loader, probes, adapters, playback driver, halted-state, TransportBar, ModeToggle, TimeSlider, boot), 31 MapView vitest cases (9 new for briefing props), and 19 Playwright E2E specs.
• 19 Playwright specs, all passing: 16 in the briefing-renderer suite covering the file:// boot, network isolation, 10× mode toggle, failure-mode surfaces, screenshot producers, story-mode component captures, the end-to-end real-export → real-unzip → real-play test, and the interaction GIF; plus 3 in shared/components covering the MapView briefing-props story in all three theme variants.
• One new runtime dependency (jszip ^3.10.1) in the VS Code extension; no new dependencies in the SPA beyond React, Leaflet, react-leaflet, and Zustand.

What’s Next

• Swap the SPA-local driver for the hoisted StoryboardPlaybackService once the briefing renderer needs the additional surface area the full service provides (Scene-rectangle click handling, snapshot stream, missing-data detection). With the hoist already complete this is now a small follow-up rather than the architectural blocker it once was.
• PMTiles basemap (#272) when zip size becomes a real transport problem — the integer-zoom-only policy in #264’s research caps typical zips around 50 MB but very large Storyboards may exceed that.
• MP4 / GIF export (#265 — research spike) for the audience that wants a recorded playback rather than an interactive one.
• Bidirectional time-range scrubbing in the briefing SPA’s time slider — the slider currently reads the engine’s frame-by-frame writes; letting the user drag it backwards through a tween is the next polish step.
• Multi-theme support in the briefing renderer so the chrome ships in light / dark / vscode variants alongside the MapView prop matrix already covered.

→ See the spec → View the evidence

What We Built

Until now, the only way to annotate a single point on a track — or correct the nationality on one contact, or label a single vertex of an exclusion zone — was to open the underlying JSON. The Properties Panel handled the plot as a whole, and stopped there. With #192 the same panel becomes the editing surface for whatever the analyst has selected: a feature, a single vertex on that feature, several features compared side by side, or the whole plot. Clicking a track point lets you mark it as the moment of intercept and attach a note; clicking a polygon vertex lets you tag it the same way; Ctrl-clicking two contacts on the map shows a read-only summary of where they agree and where they differ.

The change is deliberately larger than it looked at first. After a Spec Navigator review I pulled four things out of the “out of scope” pile that the original plan had quietly assumed away. Multi-select emission, because the multi-select summary mode was unreachable without it — a documented capability that nothing in the running app could actually trigger. Read-only plot detection, because a save against a locked catalog item was failing silently and writing a provenance entry for a save that never happened, which is the exact failure mode the constitution forbids. Per-field revert, because shipping per-platform overrides without a way to undo them was half a feature. And sub-feature editing for non-track annotations, because designing a vertex-metadata schema slot now and then designing another one for polygons later would have been an obvious mistake.

How It Fits

This sits on top of #447’s Properties Panel shell and consumes the per-platform override fields from #181, the structured vertex-path convention from #053, the annotation geometries from #093, and the auto-derived values from #135. Nothing new joins the dependency graph — no new packages, no new runtime libraries, no new Zustand stores. The staging buffer lives in React state inside the panel’s host controller, the read-only signal lives on the existing session-state plot slice as isReadOnly plus a readOnlyReason, and the selection model stays the existing features slice — the map and Layers panel click handlers grow modifier flags but the shape of selection is unchanged. The headline schema change is one LinkML class (VertexMetadata) and one slot (vertex_metadata) added to BaseFeatureProperties, which means every feature class that inherits from it — TrackProperties plus the seven annotation classes — picks up the slot for free. The address inside each entry is a structured string path following #053’s selection-path convention: positions/N for tracks, rings/R/vertices/V for polygons, vertices/N for lines and multipoints, vertex/0 for points.

Key Decisions

• Staging buffer is panel-local React state, not a new Zustand slice. The first plan had me adding a cross-package store; the Spec Navigator review pointed out that nothing outside the panel reads it, and that introducing shared state for a panel-private concern would be the wrong call. It now lives where the panel can see it and nowhere else.
• The staging buffer, the save→flush wiring, and the per-save provenance call site are net-new in #192, not extensions of #447. The original plan claimed they were inherited from the plot-editor; an Article I.3 audit showed they weren’t. Misclassifying them risked shipping the silent-save bug into the per-feature path too, so I added an integrated save-path Vitest specifically to close that hole.
• Read-only detection combines a writer capability report with post-write escalation. The writer’s CapabilityReport.persistent flag drives the pre-flight banner. If a save still fails with ReadOnlyFilesystemError, EACCES, or EPERM, the panel escalates to read-only after the fact and surfaces a notice. Where the catalog lock and the filesystem permission disagree, the most restrictive wins.
• One shared VertexMetadata class, addressed by a structured string path. The alternative was a per-geometry class hierarchy, which would have meant generating four near-identical types and four mode-resolver branches. A single class with a path slot kept the schema sparse (vertices with no metadata add nothing to the saved file), kept the editor branch-free (the same label/tags/note form regardless of geometry kind), and meant the mode resolver only needs to recognise a vertex path — not decode it.
• PropertiesForm gets a mode prop and three new sibling components — FeatureEditorMode, SubFeatureEditorMode, MultiSelectSummaryMode — rather than a single super-component that branches internally. Each mode is independently storyable, independently testable, and independently rerenderable when the selection changes.
• Multi-select emission is upstream of the panel. The map’s onSelect and the Layers panel’s row click handler grow modifier flags; the panel itself learns nothing new about how the selection was built. This keeps the panel’s mode-resolution logic pure: it reads the selection and renders, and it never asks where the selection came from.
• Vertex re-mapping under geometry mutation is explicitly deferred. If a later feature edits a polygon’s vertices, the rules for how vertex_metadata entries follow insertions and deletions will be defined alongside that feature, not pre-emptively here. Annotating today is in scope; reshaping is not.

Screenshots

The Properties Panel renders one of four modes based on what’s selected. Below: feature mode (with the per-platform override chip and the revert affordance), sub-feature mode on a track point and on a polygon vertex (cross-geometry hero — same form, different address), the multi-select read-only summary, and the read-only banner that fires either pre-flight or after a permission-denied save.

Feature mode	Sub-feature mode (track point)
Sub-feature mode (polygon ring vertex) — same form, different address	Multi-select summary
Read-only banner alone	Read-only in the live web-shell (banner + disabled inputs)

The mode-swap frame strip captures the four key states the dispatcher cycles through. (The cloud environment has no ffmpeg, so the spec’s planned GIF is rendered as a four-frame sequence the PR description displays side-by-side.)

By the Numbers

Lessons Learned

• Audit “we inherit that from #447” claims before designing on top of them. The original plan said the save path, the provenance call site, and the staging buffer were #447 plumbing reused as-is. The Spec Navigator review showed that wasn’t true — the save path landed but the staging buffer and the provenance call site were never wired. I’d been planning to lean on infrastructure that didn’t exist. The integrated save-path Vitest (saveSession-integration.test.ts) is the test that closes that gap; it would not have existed without the second review pass.
• A breaking signature change to a high-traffic prop is cheap if the package boundary is right. MapView.onSelect going from (featureId, event) to ({ target, modifier, shift }) rippled through one VS Code call-site and two web-shell call-sites, the FeatureList convergence, two Storybook stories, and one selection-sync test. It took the Phase 5 agent under 20 minutes from first edit to all-green. The same change spread across packages owned by different teams would have cost a week.
• Browser-safe subpath exports are worth setting up before they bite. Adding @debrief/session-state/browser for the components package was a 30-line change that took an hour to discover (the regression was invisible until the VS Code webview pretest fell over with Could not resolve "fs/promises"). The web-shell was already aliasing the package to a local shim for the same reason — that pattern should be a project-wide convention, not a per-app workaround.
• Inlining a JSON registry into a component is fragile, even when it’s expedient. The platform registry lookup for the revert affordance reads shared/data/platform-registry.json. The @debrief/data package uses node:fs, which doesn’t work in the webview. The Phase 8 work mirrored the JSON inline; this is a known follow-up. The right fix is a @debrief/data/browser subpath that ships the JSON bundled at build time.

What’s Next

• Wire a Save action in the host UI. The staging buffer’s applyEditsToFeatures → saveSession → appendProvenance glue is shipped; the panel currently never invokes it from a visible control. The follow-up backlog item will surface a Save button in the panel header.
• Add @debrief/data/browser to remove the inline platform-registry mirror in FeatureEditorMode.tsx.
• Vertex re-mapping under geometry mutation. The current sparse-path keying means that if a polygon shrinks under the analyst, vertex_metadata entries whose path no longer resolves are skipped. The next feature to edit polygon vertices should define the re-mapping rules at the same time.
• Convert the workflow PNG sequences into GIFs once ffmpeg is on the CI image. The capture spec is already in place — only the post-processing step is missing.

→ See the spec → View the evidence

What We Built

STAC catalog payloads — the item.json, catalog.json and collection.json files that record every plot in the local store — had been hand-typed on both sides of the Python ↔ TypeScript boundary since the catalog landed. Twelve interface declarations across four files, three separate copies of StacItem, and nothing connecting them. These files persist to disk between sessions: Python writes, TypeScript reads. A field added to one side and missed on the other didn’t crash — it silently dropped on the next save.

This work promoted the cluster onto a single LinkML source. StacItem, StacCatalog, StacCollection, StacLink, StacAsset, StacExtent, StacSummaries and StacProvider now live in one file, and Pydantic models plus TypeScript types are generated from it. Every committed item.json under preview/workspace/samples/local-store/ — 73 real files — loads cleanly through the generated validators on both sides. That fixture-corpus test is the strongest evidence the schema captures the wire shape that actually ships, not a sanitised cartoon of it.

How It Fits

This is the third slice of Epic E11 — Schema-First Boundary Typing — the same programme that #222 (MCP envelopes) closed last month. Same pattern, different cluster: the audit’s drift table flagged five sites in §3.1, seven more siblings were masked by the file-level R4 rule but still hand-written, and one inline alias rounded out the thirteen. All of them collapsed onto one generated class per name. The audit’s cross-domain-hand-typed count attributed to #223 drops from 5 to 0; the StacItem and StacCatalog drift clusters in §3.2 disappear entirely.

Key Decisions

• STAC 1.0 and 1.1 both accepted via additive optional fields. The local stores currently ship 1.0; spec #241 (in flight) upgrades them to 1.1. Modelling stac_version as a string and making the new 1.1-only fields optional means #223 and #241 can land in either order — neither blocks the other.
• StacCatalog and StacCollection are siblings, not parent and child. Each declares its type slot with equals_string, which generates a TypeScript literal that makes if (x.type === 'Collection') narrow at the call site. Inheritance was tempting — Collection is structurally Catalog-plus-extras — but it captures the relationship wrong: a Collection’s type is "Collection", not "Catalog".
• Open-record extension slots, with eyes open. StacItem.properties, StacAsset and StacSummaries all carry additional_properties: true so the <namespace>:<key> convention (debrief:platforms, file:checksum, processing:datetime, proj:shape) survives the boundary. Same Article XV.2 exception #222 used for MCPContentItem.structuredContent, applied where STAC’s own spec is genuinely open.
• Composition over re-declaration. StacItemProperties mixes in the existing StacExtensionProperties from stac-extension.yaml; StacItem.geometry references the seven existing geometry classes from geojson.yaml. No re-declared shapes anywhere — the same rule that made #222 stick.
• Python writes through Pydantic too. scripts/enrich-legacy-catalog.py switches from dict[str, Any] constructions to Pydantic class constructions. Field-name typos now fail at write time, not three releases later when somebody finally notices the missing key in the tree view.
• Out of scope, and named. The camelCase StacItemSummary adapter (#214 follow-up) and the STAC 1.1 wire-format work (#241) both touch adjacent files, but neither is in this feature. Calling them out keeps the diff honest and the reviewer’s job small.

By the Numbers

The audit re-run is the clearest single signal — the rows that started this feature are gone.

The shape of what landed:

The fixture corpus is the load-bearing test. Every committed item.json under preview/workspace/samples/local-store/ (73 STAC 1.1 items + 1 Collection root) and apps/vscode/test-data/local-store/ (2 STAC 1.0 items + 1 Catalog root) loads through the generated Pydantic validators with zero coercion. Three golden fixtures — boat1, analysis2-track1, and the 81 KB preview Collection — go through Py → JSON → Py and emerge byte-equivalent.

The write side now flows through Pydantic too:

from debrief_schemas import StacItem

item = {
    "type": "Feature",
    "stac_version": "1.1.0",
    "id": "core--boat1",
    "geometry": {"type": "Polygon", "coordinates": [...]},
    "bbox": [-21.866, 21.947, -21.580, 22.186],
    "properties": {
        "datetime": "1995-12-12T05:00:00+00:00",
        "title": "Saxon Warrior: Boat1",
        "debrief:platforms": [{"id": "NELSON", "name": "HMS Nelson"}],
        # extension keys: file:size, proj:shape, processing:* —
        # all accepted via the Article XV.2 open-record exception.
    },
    "links": [...],
    "assets": {...},
}

StacItem.model_validate(item)  # raises on field-name typos, missing slots

And the read side, on every TypeScript consumer:

import type { StacItem, StacCatalogOrCollection } from '@debrief/schemas';

const item: StacItem = JSON.parse(content);

if (root.type === 'Collection') {
  // TypeScript narrows to StacCollection — no predicate, no cast.
  // root.extent.spatial.bbox, root.license, root.summaries are typed.
}

The writer package re-exports StacItem and StacAsset from @debrief/schemas rather than declaring them locally. That closes A-009: both ends of the writer ↔ mock boundary now reference the same generated class, so the JSON projection cast that previously laundered between two structurally-equivalent-but-nominally-distinct StacItem types at apps/web-shell/src/mocks/stacService.ts:464-474 is gone.

Lessons Learned

The STAC extension convention is genuinely open. STAC’s <namespace>:<key> pattern (debrief:platforms, file:checksum, proj:shape, processing:datetime) is not a closed set we could enumerate. Pydantic’s extra='allow' and TypeScript’s [key: string]: unknown — the Article XV.2 exception #222 introduced — are the right shape for this, not a tighter union. The plan’s Complexity Tracking section spells out the trade-off: we lose compile-time knowledge of extension keys in exchange for a schema that survives contact with the on-disk corpus without coercion. Three open-record classes (StacItemProperties, StacAsset, StacSummaries, plus StacItemAssetDefinition) carry the exception. Everything else is closed.

Nested arrays needed no new machinery. STAC’s bbox: number[] and interval: (string | null)[] slots have the same generator gotcha as GeoJSON’s nested coordinate arrays — LinkML’s gen-pydantic and gen-typescript emit the inner array shape incorrectly without a post-processing pass. The pass that already exists for GeoJSON handled this. No new mechanism, just a precedent applied.

Item assets and Collection item_assets are not the same class. STAC 1.1 makes the distinction explicit: an Item.assets[k] is a concrete asset with a required href, but a Collection.item_assets[k] is an asset definition — a template that downstream items will fill in, with no href of its own. The temptation was to model these as one class with href: Optional[str]. That would have weakened typing on the read side: consumers iterating item.assets would have to null-check href on every access despite the STAC spec guaranteeing it. Two classes — StacAsset (href required) and StacItemAssetDefinition (no href) — preserves the guarantee.

The writer-package edit closed a fragile cast nobody had complained about. Decision 1B brought @debrief/stac-writer into the migration, which initially looked like scope creep — the writer’s StacItem was structurally compatible with the schema’s. But the structural compatibility was the problem: the web-shell mock had a JSON.parse(JSON.stringify(...)) projection at the writer-to-mock boundary specifically to launder between two nominally-distinct-but-equivalent shapes. Collapsing them onto one generated class let that cast go. Worth doing, even though no test was failing because of it.

What’s Next

E11 has three more phases queued. #224 promotes the session-state cluster — the next set of cross-boundary types where the audit still flags drift. #225 takes on the loader ↔ main IPC envelopes (smaller surface, same pattern). #226 is the residual roll-up — whatever single-domain shapes the audit still flags after #224 and #225 are merged.

Parallel to all of that, #241 (STAC 1.1 best-practices upgrade) is in flight. The local stores currently ship 1.0 in the VS Code test data and 1.1 in the preview store; #241 normalises everything to 1.1 with file:checksum and the rest of the 1.1 extension set. Now that the schema is rooted, #241 lands additively against generated types instead of having to coordinate with thirteen hand-typed sites.

→ See the spec → View the evidence