A month ago, the VS Code E2E test suite had 8 spec files – all skipped. The web-shell had 81 tests across 13 categories, all passing, but those tests exercised orchestration through mock data. Nothing verified that a scientist could open a real REP file in the real extension, see real tracks parsed by real Python services, select features, and run analysis tools end-to-end.

Now the VS Code E2E suite has 18 active spec files. Four previously-skipped specs have been restored with live assertions. Ten new spec files cover selection sync, time controller, drawing tools, catalog browsing, log panel, edit face, event propagation, styling tools, undo/redo, and evidence capture. The DebriefWebview page object gained 40+ new selectors and methods to support all of this.

Both suites run in parallel CI. The web-shell tests (~30 seconds, mock data, 13 specs) catch orchestration regressions fast. The VS Code E2E tests (~3 minutes, real services, 18 specs) catch the integration problems that only surface when debrief-io parses an actual REP file and debrief-stac stores actual STAC Items.

How It Works

The VS Code E2E tests drive openvscode-server with the Debrief extension sideloaded. Behind the scenes, three Python services – debrief-io, debrief-stac, and debrief-calc – are running and reachable. When a test opens a REP file, the extension calls debrief-io to parse it, debrief-stac to catalogue it, and debrief-calc to run analysis. The test then inspects the webview DOM to verify tracks rendered and results appeared.

test('loads REP file and shows tracks', async ({ codeServerPage }) => {
  await codeServerPage.openFile('samples/boat1.rep');

  const frame = await codeServerPage.getWebviewFrame();
  await frame.locator('.leaflet-container').waitFor({ state: 'visible' });

  const trackCount = await frame.locator('.leaflet-interactive').count();
  expect(trackCount).toBeGreaterThan(0);
});

That last assertion – toBeGreaterThan(0) rather than toEqual(3) – is deliberate. Real service output varies. Structural assertions (“at least one track exists”) are resilient to changes in sample data or parsing improvements. Value-exact assertions against real data break constantly for the wrong reasons.

By the Numbers

The test.fixme() Strategy

Of the 18 VS Code E2E spec files, 10 contain tests marked test.fixme(). These cover features that don’t yet exist in the extension – time controller, drawing tools, styling, undo/redo, and others. The tests are written. The assertions are specified. The features aren’t implemented yet.

test.fixme('time scrubber updates map display', async ({ codeServerPage }) => {
  // Time controller not yet implemented in VS Code extension
  // See backlog: time-controller feature
});

We chose test.fixme() over .skip() for a specific reason: fixme tests appear in Playwright reports as known gaps. They’re visible. They cross-reference backlog items. When someone implements the time controller feature, the test is already waiting – remove the .fixme() wrapper and it either passes or tells you what’s broken. With .skip(), these tests would vanish from reports entirely, and the gaps they represent would be invisible.

This turned the E2E expansion into a feature-completeness audit. Writing 28 fixme tests documented exactly what the extension doesn’t do yet, in executable form.

Page Object Architecture

Two page objects handle the VS Code E2E environment:

• CodeServerPage manages VS Code chrome – command palette, Quick Open, file navigation, the Welcome tab focus trap, keyboard shortcuts
• DebriefWebview manages the extension’s webview – iframe traversal, Leaflet map interactions, feature list, tools panel, selection state

This separation matters because VS Code’s webview sits inside nested iframes. The test code that opens a file through Quick Open is fundamentally different from the code that clicks a track on the map. Mixing them makes tests fragile. Keeping them in separate page objects makes the iframe boundary explicit.

Lessons Learned

Structural assertions save maintenance time. Early drafts of the restored specs used exact value checks against real REP file output. Those broke immediately when we updated a sample file. Switching to existence-based assertions (“at least one track”, “tool result contains measurement text”) made the tests resilient without sacrificing confidence. If zero tracks render, the test still fails.

Writing tests for unimplemented features is useful work. The 28 fixme tests forced us to think through what each feature’s testable behaviour should look like, before writing any implementation code. Several of those tests revealed UX questions we hadn’t considered – what should the time controller’s DOM look like? How should drawing tool state be inspectable from Playwright? Those questions are now documented in the test files themselves.

Dual-platform testing catches different bugs. During development, the web-shell tests passed consistently while a VS Code E2E test failed on catalog browsing. The issue was an extension-specific activation timing problem that the web-shell’s simpler lifecycle couldn’t reproduce. Two test surfaces, two classes of bugs caught.

What’s Next

The 28 fixme tests are now a prioritised implementation queue. As each extension feature ships – time controller, drawing tools, styling panel – the corresponding fixme tests activate and immediately verify the feature works end-to-end with real services.

The CI pipeline runs both suites in parallel, so new features get validated against mock data in 30 seconds and against real services in 3 minutes, without blocking each other.

-> See the spec -> View the evidence

The Logical Result ID Registry provides the indirection layer that lets result views stay synchronized with tool outputs. When a tool produces bt_plot_001_v1.png, the registry maps the stable ID bt_plot_001 to that file. When the analyst tunes a parameter and the tool produces v2, the registry updates the mapping and emits a change event. Views that subscribed to that result ID get notified. No polling, no scanning, no coupling between tool execution and result display.

37 new tests, 521 total tests passing, zero regressions.

How It Works

The registry lives in @debrief/session-state as a pure in-memory Map with callback subscriptions. It populates from two sources: STAC asset metadata when a plot loads, and Log Service entries when tools run.

On plot load, hydrateFromAssets() scans STAC assets for debrief:resultId and debrief:version metadata. For each logical ID, it selects the highest version. A plot with bt_plot_001_v1 and bt_plot_001_v2 assets hydrates with v2 as the current mapping. Hydration is bulk initialization – no change events fire, keeping the initial load quiet.

When a tool executes, the Log Service records a RecordResult entry with generatedResultId and generated fields. The registry observes these entries through registerFromRecordResult(), extracts the result ID and file path, and updates its mapping. This time a change event fires, notifying any subscribers that the result has updated.

Subscriptions come in two flavors. subscribe(resultId, callback) delivers notifications only for a specific result ID. subscribeAll(callback) delivers notifications for any change. Both return an unsubscribe function. When a result view closes, it unsubscribes, and the registry cleans up the callback. When the plot closes, clear() wipes all mappings and subscriptions.

The VS Code extension creates the registry in extension.ts, hydrates it in openPlot.ts, updates it in executeTool.ts after tool runs, and again in logPanelView.ts after replay operations like tune and revert.

Integration Points

The registry provides three registration methods, each tailored to a different data source:

registerFromLogEntry() handles raw Log entries from the Log Service. Used internally but exposed for completeness.

registerFromRecordResult() consumes the structured result from logService.recordToolResult(). This is what executeTool.ts calls after a tool finishes – one line of code, registry updates automatically.

registerFromReplayResult() processes artifacts created during replay operations. When the analyst tunes a parameter, the tuned tool execution creates new artifacts. logPanelView.ts passes replayResult.artifactsCreated to this method, and the registry updates with the new versions.

All three methods produce identical change events. A subscriber doesn’t know or care whether an update came from a tool run, a tune, or a revert. It just knows the result changed.

Lessons Learned

Synchronous operations simplified everything. The registry uses simple Maps and callbacks – no promises, no async, no queues. The JavaScript event loop guarantees ordering, so rapid successive updates for the same result ID produce correctly sequenced change events. We tested this explicitly: register v1, immediately register v2, verify two change events fire in order.

Observing Log entries rather than hooking tool execution preserved separation of concerns. The registry knows nothing about MCP, tool definitions, or parameter schemas. It consumes structured data from the Log Service. The Log Service knows nothing about result ID mappings or subscriptions. It emits structured data. Neither depends on the other’s internals.

Bulk hydration without events was non-negotiable. Early prototypes fired change events during hydrateFromAssets(). Every asset produced a notification. For a plot with 20 result artifacts, that meant 20 callbacks before the plot even opened. The current design treats hydration as initialization, not as live updates. Only runtime changes emit events.

Storing MIME type and version during hydration turned out useful. The registry started as a pure ID-to-path map. Testing revealed that views often need the MIME type to choose a renderer and the version number to display staleness indicators. We extended the mapping to include these fields when available from STAC metadata, keeping them null when registering from Log entries.

What’s Next

Feature #089 (Auto-Refresh) consumes the registry’s change events. When a result view is open and its underlying result updates, the view subscribes to that result ID. The change event arrives, the view checks the debrief.autoRefreshArtifacts setting, and if enabled, reloads the content while preserving viewport state.

The registry provides the notification mechanism. Auto-refresh provides the response behavior. Together they complete the workflow where an analyst tunes a parameter, watches the chart update automatically, and never thinks about versioned file paths.

See the code Test summary

The shape palette from feature 093 let you click ‘+’, pick point or rectangle, and enter drawing mode. But that palette knew nothing about our data model — it just handed back raw Leaflet layers. Feature 094 is the glue: a pure factory function called createDrawnFeature() that converts Geoman’s raw GeoJSON into schema-compliant features.

Two shape types are supported. Points become ReferenceLocation features (kind=POINT) with green markers. Rectangles become RectangleAnnotation features (kind=RECTANGLE) with blue polygons. Each gets a UUID, default styling, and required schema properties. If you click without dragging in rectangle mode, the zero-area geometry is silently discarded — no error, no minimum-size snapping. The analyst didn’t intend a shape, so we don’t create one.

The function is pure. No side effects, no DOM access, no state mutations. You call it with GeoJSON plus the active drawing mode, and you get back a schema-compliant feature or null. This made testing straightforward — 33 unit tests without needing a map or browser.

Screenshots

Point drawing in action:

Rectangle drawing with multiple features:

Callback-Based Integration

The LeafletToolbar listens for Geoman’s pm:create event, extracts the raw GeoJSON, and fires an onShapeCreated callback. The consumer — VS Code webview or Storybook story — calls createDrawnFeature() and decides what to do with the result. The shared component library stays generic. The consumer owns the state update.

In VS Code, drawn features are immediately added to the active plot’s feature collection and auto-selected. In Storybook, they go into a useState array for demonstration purposes. Same conversion function, different destinations.

What Held Up

The default colour choices — green points, blue rectangles — were deliberately distinct from track colours (blue for ownship, red for contacts). Drawn annotations needed to be visually distinguishable from loaded data. We made these constants in a drawingDefaults.ts module. They’re fixed for now, but could be made configurable later if users have strong opinions about annotation colours.

The degenerate rectangle case (click without drag) came up during testing. Geoman fires pm:create even when the drag distance is zero. We added an area check to isValidDrawnGeometry() and return null if the rectangle has zero width or height. The shape is discarded silently. No toast, no error dialog. The analyst didn’t drag, so we assume they didn’t mean to create a shape.

Auto-selecting the newly drawn feature felt right — you’ve just placed a point or drawn a rectangle, you probably want to inspect or label it. The selection happens in the onShapeCreated handler, right after adding the feature to the collection. One less click for the analyst.

Test Coverage

33 unit tests, all passing. These covered geometry validation (zero-area rejection, coordinate pass-through, closed polygon rings), schema compliance (correct kind discriminators, required properties, UUID uniqueness), and default styling (green points, blue rectangles, opacity values).

13 e2e tests via Playwright against the Storybook story. These verified rendering across three theme variants (light, dark, VS Code), point and rectangle creation via actual map clicks, and screenshot capture for visual regression. Total duration 24.8 seconds.

No regressions. The existing ToolMatchHarness e2e suite (12 tests) still passes, confirming that drawing doesn’t interfere with tool matching or existing map interactions.

What’s Next

Drawn features currently live in React state. They disappear when you close the webview. Persistence to STAC is feature 096 — we kept it separate so drawing could ship without coupling to the storage layer. Once 096 lands, drawn annotations will survive across sessions and appear in the STAC catalog alongside loaded data.

The pure function approach paid off. The core conversion logic is in four small files (drawingDefaults.ts, isValidDrawnGeometry.ts, createDrawnFeature.ts, and a barrel export), fully tested in isolation. When we wire up persistence, the conversion logic won’t change. We’ll just add a STAC write after the feature is created.

See the code

Running Playwright against a full VS Code workbench is straightforward on a developer laptop. Running it inside Claude Code’s sandboxed environment – where CDN downloads return 403, snap packages fail, and multi-process Chromium crashes mid-render – took a week of dead ends before anything worked.

The result is an ensure-chromium.sh script, a set of Chromium flags, and a switch from code-server to openvscode-server. Together they let us drive VS Code through its command palette, Quick Open dialog, and file navigation from within the sandbox. Four screenshots prove it.

Command palette (F1) responding to keyboard input inside the sandboxed browser. This was the moment we knew the infrastructure worked.

Four Dead Ends

Each approach seemed reasonable in isolation. Each failed for a different reason.

1. Standard Playwright install. npx playwright install chromium downloads from cdn.playwright.dev. The sandbox returns 403 Forbidden - host_not_allowed. Every Playwright CDN mirror we tried hit the same firewall. Non-starter.

2. @sparticuz/chromium. This npm package bundles a minimal Chromium binary designed for AWS Lambda. It extracts to /tmp/chromium and works for simple pages – we had it rendering HTML and running DOM tests within an hour. But the VS Code workbench is not a simple page. The minimal build crashed consistently when rendering VS Code’s complex DOM. The workbench never got past the initial paint.

3. code-server with Playwright. code-server wraps VS Code as a web application and seemed like the natural host. But its WebSocket authentication depends on vsda, a proprietary WASM module that isn’t open source. In our environment, the connection handshake failed silently. We spent a day tracing WebSocket frames before finding the dependency.

4. Multi-process Chromium. Even after solving the browser and server problems, Chromium’s default multi-process architecture caused renderer crashes in the container. Taking screenshots – the thing we needed most for evidence – would kill the renderer process. The workbench would load, we’d call page.screenshot(), and the browser would crash.

What Actually Worked

GitHub Release browser hosting. Instead of fighting CDN restrictions, we uploaded a full Chromium build (matching Playwright’s expected version) as a GitHub Release asset under the tag playwright-browsers-v1. The ensure-chromium.sh script tries the standard Playwright install first. When that fails, it downloads from the GH release, places the binary where Playwright expects it, and writes a .chromium-path file that playwright.config.ts picks up. The script is idempotent – run it twice, it skips the download.

# Resolution order in ensure-chromium.sh:
# 1. Already installed? → done
# 2. npx playwright install chromium → try CDN
# 3. CDN blocked? → download from GH release

openvscode-server. Gitpod’s open-source VS Code server, without the vsda dependency. The global setup script checks for it first, falls back to code-server if needed. No authentication tokens, no proprietary modules. It just starts and serves the workbench.

Single-process Chromium. The flags --single-process --no-zygote --disable-software-rasterizer collapse Chromium’s process tree into one process. This prevents the renderer crashes that plagued multi-process mode in the container. The trade-off is that a crash in any component takes down the whole browser, but for testing that’s acceptable – a crash is a test failure either way.

// playwright.config.ts -- sandboxed launch options
args: [
  '--no-sandbox',
  '--disable-setuid-sandbox',
  '--disable-gpu',
  '--disable-dev-shm-usage',
  '--disable-software-rasterizer',
  '--single-process',
  '--no-zygote',
]

Welcome tab workaround. VS Code’s Getting Started tab renders inside an iframe that captures keyboard focus. The command palette (Ctrl+Shift+P) and Quick Open (Ctrl+P) won’t respond because keystrokes go to the iframe instead of the main window. The fix is two-part: machine-level settings to disable the Welcome tab (workbench.startupEditor: none), and a Ctrl+W keystroke on load to close it if it appears anyway, followed by clicking the title bar to return focus to the main window.

Evidence

Four screenshots taken during a test run inside the sandbox, each proving a different layer works.

The full VS Code workbench rendered inside headless Chromium. Activity bar, editor area, status bar all present.

F1 opens the command palette and it responds to typed input. This requires keyboard focus to be on the main window, not trapped in an iframe.

Ctrl+P opens Quick Open with file search suggestions. The workbench’s keyboard shortcut handling is fully functional.

Typing a filename into Quick Open. The search executes against the workspace. File navigation works end-to-end.

What We Learned

The research note saved days. Early in the project we documented every Playwright installation approach we tried in docs/project_notes/playwright-installation-research.md. That note ruled out three dead ends immediately when we circled back to E2E testing. Writing down what doesn’t work is as valuable as writing down what does.

@sparticuz/chromium is for simple pages. It’s optimized for Lambda functions that render PDFs or take screenshots of single-page apps. VS Code’s workbench – with its nested iframes, service workers, and complex layout engine – overwhelms the minimal build. The right tool for the wrong job.

Single-process mode contradicts most advice. Chromium documentation and StackOverflow answers consistently warn against --single-process. For production browsers, they’re right. For headless testing in containers, it’s the only configuration that doesn’t crash. Context matters more than best practices.

The Welcome tab is a focus trap. This cost half a day. Everything looked correct – the workbench loaded, the browser was stable, screenshots worked – but keyboard shortcuts did nothing. No error messages, no visible problem. The Getting Started tab’s iframe was silently eating every keystroke.

What’s Next

The infrastructure is ready for real test content. When specs 043 (file loading) and 001 (tool execution) ship their TypeScript implementations, we can write tests that exercise the full analyst workflow: open a REP file, see tracks on the map, run analysis, check results. The page object models (CodeServerPage for VS Code chrome, DebriefWebview for Debrief components) are waiting.

More immediately, any feature branch can now run bash tests/e2e/scripts/ensure-chromium.sh and have a working Playwright environment in seconds, even inside Claude Code.

See the infrastructure code View the spec

The catalog overview panel turns a STAC directory into a navigable spatial-temporal index. Double-click a catalog node in the STAC Stores tree view, and VS Code opens a read-only panel showing two synchronized views: a Leaflet map with bounding box rectangles for every item, and an SVG timeline with horizontal bars representing temporal spans.

Double-clicking an item opens the full plot view with tracks, layers, and time controls:

The component lives in shared/components/ as a reusable React element, tested in Storybook with 11 stories covering nominal cases and edge conditions (empty catalogs, missing bbox, missing temporal metadata). The panel integrates into VS Code as a WebviewPanel, using the same message-passing pattern as the existing plot view.

How It Works

The architecture keeps concerns separated: the React component handles all rendering and layout logic, receiving catalog data as props. The VS Code extension provides a thin wrapper that manages the panel lifecycle, retrieves item metadata via stacService.listItems(), and bridges the webview’s double-click messages back to the “open plot” flow.

The map uses the same Leaflet instance configuration as the plot view, so it feels familiar. The timeline is hand-rolled SVG—rectangles for time ranges, circles for single-point temporal markers, and graceful fallback labels when metadata is absent.

A horizontal drag bar lets users resize the split between map and timeline. The ratio persists across sessions via VS Code’s Memento API, so analysts can save their preferred proportion.

Decisions and Trade-offs

Shared component, not a custom editor provider. STAC catalogs are directories, not files. CustomReadonlyEditorProvider requires backing documents and would have forced a virtual URI workaround. WebviewPanel is clearer about representing multi-file structures.

Lightweight metadata loading. Rather than reading full GeoJSON assets, we extract just bbox, start_datetime, end_datetime, and datetime from each item.json. This keeps the panel responsive even with hundreds of items. The trade-off is that we don’t show asset previews—the overview is intentionally aggregate, not detailed.

Overlapping timeline bars by default. Items with overlapping temporal ranges are rendered in a single row. This is compact and shows temporal density clearly, but can occlude labels. We considered auto-stacking (separate rows per item) but found it consumed too much vertical space for typical catalogs. The Storybook knobs let us test both approaches for different data distributions.

Offline rendering as default. Bounding box rectangles and timeline bars render without map tiles. If you’re disconnected, you still get the structure. The tile layer is additive—it loads asynchronously if available, but doesn’t block rendering.

What Surprised Us

Testing revealed that many items in the wild have incomplete metadata. A plot might have a complete bbox but no start_datetime, or vice versa. Rather than hide incomplete items or throw errors, we show them with a “no time data” label on the timeline or omit them from the map view. Items remain clickable regardless.

The Storybook coverage—11 stories with different fixture configurations—caught edge cases that manual testing would have missed. One story tests an empty catalog (should show a friendly message, not crash). Another tests a single item (should still auto-fit the map, not zoom to maximum). These seem obvious in retrospect but required explicit fixtures to verify.

Tests and Acceptance

13 unit tests cover metadata extraction from item.json files, timeline bar positioning logic, and edge cases like missing fields and empty collections. The Storybook stories serve as both documentation and interaction tests—reviewers can spin up the component in isolation and verify visual behavior without spinning up the full extension.

Acceptance criteria all pass: double-click opens the panel, map shows extent, timeline shows ranges, drag bar resizes, item navigation works, styling adapts to VS Code theme, and missing metadata is handled gracefully.

What’s Next

The overview panel becomes a launchpad for catalog-level operations. Future work could add filtering (show only items from a date range or geographic region), statistics (count items, total coverage area, temporal span), or export capabilities (save the current view as a GeoJSON collection). The shared component architecture means improvements benefit both Storybook and VS Code simultaneously.

The panel is also a foundation for the aggregate analysis track. Imagine comparing two catalogs’ spatial distributions side-by-side, or querying across 100 exercises to find patterns no single analysis could reveal. That’s further down the roadmap, but the catalog overview is where that vision becomes tangible.

→ See the code → Storybook stories

When a calculation tool smooths a track or computes a closest point of approach, something needs to classify that result, persist it to the STAC catalog, and update the display. We’ve now built the machinery that connects these pieces.

The system introduces four top-level result types: mutation (modified features), addition (new features), deletion (removed features), and artifact (reports, images, datasets). Every tool response is an MCP-compliant content array containing one or more items, each classified into one of these types and carrying three required annotations: the result type path, source feature IDs, and a human-readable label.

On the storage side, debrief-stac exposes four atomic operations: update features, add features, delete features, and store artifact. The service has no knowledge of result types. The orchestrator (frontend or LLM) interprets each content item’s type and calls the appropriate operation. After each operation, a diff utility compares the old and new FeatureCollections and the display updates incrementally.

How It Works

Here’s a Python tool returning a smoothed track:

from debrief_calc.result_builder import build_mutation, build_response

smoothed = {"type": "Feature", "id": "track_a", "geometry": {...}, "properties": {...}}
mutation_items = build_mutation(
    features=[smoothed],
    result_subtype="track/smoothed",
    source_feature_ids=["track_a"],
    label="Smoothed Track A",
)
response = build_response(mutation_items)

The orchestrator receives the response, sees the mutation type, and calls:

from debrief_stac.features import update_features
from debrief_stac.provenance import write_provenance

write_provenance(smoothed, "track-smoother", "1.0.0", ["track_a"])
count = update_features("/data/catalog", "plot_001", [smoothed])

For multi-result responses, the content array is processed sequentially. A tool that trims outliers might return two items: a deletion for the removed contacts and an artifact with the analysis report. The orchestrator calls delete_features, then store_artifact, diffing and updating the display after each.

Result Type Hierarchy

Result types use slash-delimited paths like artifact/report/ssa_assessment. The four top-level types are fixed and schema-validated. Below that, organisations can introduce sub-types without registration.

A contrib-aware viewer might recognise the full path and open a specialised report viewer. The generic Debrief UI matches artifact/report and shows a standard report preview. An LLM matches just artifact and reports “The tool produced a report artifact.” Each consumer degrades to the deepest match it understands.

TypeScript provides utilities for this:

import { matchesResultType, getTopLevelType } from "@debrief/diff";

matchesResultType("artifact/report/ssa_assessment", "artifact");         // true
matchesResultType("artifact/report/ssa_assessment", "artifact/report");   // true
getTopLevelType("artifact/report/ssa_assessment");                        // "artifact"

Lessons Learned

The separation of concerns took a few iterations to settle. Initially, I considered embedding result type interpretation inside debrief-stac. That would have made the persistence service brittle and coupled it to frontend concerns. Moving all type awareness into the orchestrator keeps debrief-stac simple: it receives features, writes them, returns updated FeatureCollections.

Multi-result responses turned out to be more common than I expected. A single tool invocation might remove outliers, update the remaining track, and produce a diagnostic plot. Returning these as separate content items, processed sequentially, is cleaner than trying to bundle them into a single compound result.

The diff utility in TypeScript was straightforward but essential. After each atomic STAC operation, the frontend needs to know what changed without re-rendering the entire plot. The utility compares feature IDs and geometries, returning three sets: added, removed, modified. 24 tests confirm it handles edge cases like identical collections, disjoint collections, and partial overlaps.

Test Coverage

88 tests passing across Python and TypeScript:

• 41 tests in debrief-calc (result types, builders, MCP responses)
• 23 tests in debrief-stac (provenance, artifacts, feature updates/deletions)
• 24 tests in @debrief/diff (FeatureCollection diffing, type matching)

The test suite covers all four result types, multi-result responses, hierarchical type matching, atomic STAC operations with provenance, and diff utility correctness.

What’s Next

This architecture supports the workflow where a calculation tool produces results, the orchestrator persists them, and the display updates. The next step is wiring a real calculation tool (track smoothing or CPA analysis) end-to-end through this flow in the VS Code extension.

The hierarchical type system is designed for contrib extensions, but we haven’t tested it with a real organisation-specific sub-type yet. That will be valuable validation once we have contrib partners.

→ See the spec → View the PR

What We Built

This fix completes the temporal interaction pipeline that was half-wired. The TimeController UI already existed, the TemporalTrackLayer rendering logic already existed, and the message pipeline between them already existed — but the final receiver (the map webview) had a TODO stub that ignored incoming time updates.

We added:

• Temporal rendering in TrackRenderer — the vanilla JS Leaflet map now responds to setCurrentTime and setDisplayMode messages
• Binary search algorithms — ported from the shared React components into a standalone temporalUtils.ts module with 15 unit tests
• Highlight markers — L.circleMarker per track in full mode, efficiently repositioned on each frame
• DisplayMode forwarding — the setDisplayMode message type was added to the extension protocol, and MapPanel now forwards mode changes from SessionStore

How It Works

The pipeline is now complete end-to-end:

1. User scrubs the TimeController slider
2. The webview sends a time change message to the extension host
3. SessionStore captures the new time
4. MapPanel’s temporal subscription fires, forwarding setCurrentTime and setDisplayMode to the map webview
5. TrackRenderer performs a binary search to find the nearest track point, then updates the polyline coordinates and marker position

All timestamp parsing (ISO to epoch) happens once on track load. The binary search is O(log n) per track per frame. Leaflet’s setLatLngs() handles efficient DOM updates.

Lessons Learned

Porting beats importing — Rather than pulling in the shared React components (which would have required React in the vanilla JS webview), we copied the two pure functions (60 lines) and unit-tested them independently. Simple, no dependency chain, easy to verify.

The message pipeline was the easy part — The infrastructure from Feature #029 (session state integration) meant the wiring was already 80% done. The real work was in TrackRenderer: managing cached timestamps, highlight markers, display mode state, and coordinate updates without flicker.

What’s Next

• #030: Add replay mode and time acceleration to the temporal state schema
• #026: Add annotation shape renderers to the VS Code extension
• #038: Context-sensitive tool offering integration

The VS Code extension now shows you which analysis tools work with your current selection. Select two tracks on the map, get tools that operate on two tracks. Select one track and a reference point, different tools appear. Right-click for quick access, use Command Palette for keyboard workflows, or browse the sidebar panel.

ToolMatchAdapter bridges session-state’s selection to the matching service we built in #027. The adapter converts feature IDs to kind counts — session-state tracks which features are selected, the adapter looks up what kinds they are (TRACK, POINT, CIRCLE, etc), and ToolMatchService evaluates tool requirements against those counts.

Tools panel shows active tools by default. Enable “show inactive tools” and you see explanations: “Range & Bearing (inactive): Need 2 TRACK, have 1”. Click an active tool, it executes via debrief-calc, results appear on the map with full provenance metadata.

How It Connects

Three pieces came together:

ToolMatchService (#027) — the matching logic that evaluates tools against selections. We built and tested this in Storybook weeks ago. Now it’s integrated.

SessionManager (#029) — centralised selection state. When you select features in the map panel, session-state broadcasts that change. The tool adapter subscribes and updates immediately.

CalcService — the bridge to debrief-calc’s MCP server. Caches tool metadata with a 60-second TTL. Executes tools, creates result layers with provenance, persists to STAC.

The ToolMatchAdapter converts between these contexts. Session-state deals in feature IDs. ToolMatchService deals in kind counts. The adapter has a callback to look up feature kinds from the active collection and does the conversion in-memory.

Three Access Points

Sidebar Tools Panel: Browse all available tools, see descriptions, enable the inactive toggle to understand requirements. Click a tool to execute.

Context Menu: Right-click selected features, see applicable tools in a “Tools” submenu. Fastest path for repetitive workflows.

Command Palette: Type “Debrief:” and see tool commands. VS Code’s when clauses hide inapplicable tools automatically. Keyboard-driven workflows work.

All three surfaces share the same underlying state. Selection changes propagate through session-state, adapter recomputes matches, UI surfaces update.

Provenance on Every Result

Tool execution produces result layers with inline provenance metadata:

{
  "type": "Feature",
  "properties": {
    "provenance": {
      "toolName": "Range & Bearing",
      "toolVersion": "1.0.0",
      "executionTime": "2026-01-27T23:15:42.123Z",
      "sourceFeatureIds": ["track-hms-defender", "track-uss-freedom"],
      "duration": 523
    }
  }
}

Every computed result traces back to its inputs. No separate provenance documents to maintain. Query the feature, get its lineage.

Testing Approach

237 tests pass across 15 test files. The new adapter tests (14 tests) verify selection conversion, kind lookups, and fallback handling when features aren’t found. CalcService tests (8 tests) verify tool execution lifecycle and result layer creation.

Extended test data in apps/vscode/test-data/local-store/ to include all supported feature kinds: tracks, circles, rectangles, lines, vectors, and point types. The adapter needs variety to verify kind grouping works correctly.

Lessons Learned

The adapter pattern worked well. Session-state stays generic (just feature IDs), the adapter adds Debrief-specific knowledge (feature kinds). Testing the adapter in isolation was straightforward because it’s pure conversion logic with a callback for kind lookup.

VS Code’s Command Palette doesn’t support disabled commands with explanations. You can only show or hide commands via when clauses. That’s why inactive tools live in the sidebar panel only — the panel can show grayed items with text. Command Palette just hides inapplicable tools.

Inline provenance was simpler than linking to separate documents. The Constitution requires provenance; we chose the simplest implementation that satisfies it. Future work might add queryable provenance relationships, but for now, results carry their own metadata.

CalcService caching (60-second TTL) prevents re-fetching tool metadata on every selection change. Tool inventories don’t change frequently. If debrief-calc restarts or tools are added, waiting 60 seconds for refresh is acceptable.

What’s Next

This completes the tool offering integration. The matching service (Phase 0-2 in #027) is now wired into VS Code (Phase 3). Analysts can discover tools, execute them, and trace results.

Future enhancements might include tool search/filtering, tool categories, or parameter UI for tools that accept user inputs. This iteration covers parameterless tools operating on selection only.

→ See the feature PR

What We Built

Large features like Storyboarding don’t fit single backlog items. The /epic command uses Opus as both Business Analyst and Technical Architect to decompose them into 3-10 independently valuable items.

The Workflow

/epic docs/feature-spec.md
    ↓
Parse input (text, local path, or GitHub URL)
    ↓
Opus analysis (BA + Architect roles)
    ↓
Generate 3-10 items with:
  - [Ex] prefix for traceability
  - Category, complexity, dependencies
    ↓
Update BACKLOG.md (Epics table + Items table)
    ↓
Create GitHub issues (with offline fallback)

Key Features

Three input modes: Feed it a text description, local markdown file, or GitHub URL. The command fetches and parses whatever you provide.

Opus-powered analysis: The breakdown follows clear principles—vertical slices over horizontal layers, infrastructure first if it unblocks, research spikes early to reduce uncertainty.

Full traceability: Items get an [E01] prefix linking back to their parent epic. The Epics table tracks status and child items.

Offline support: Core breakdown works without network. GitHub issues are created when gh is available, with fallback to local files.

Example Output

## Epic Created: E01 - Storyboarding Briefings

### Breakdown (7 items)

| ID | Category | Title | Complexity |
|----|----------|-------|------------|
| 024 | Infrastructure | [E01] Add storyboard schema | Low |
| 025 | Feature | [E01] Create storyboard panel | Medium |
| 026 | Feature | [E01] Implement scene capture | Medium |
...

### Next Steps
1. Score items with backlog-prioritizer
2. Approve with the-ideas-guy
3. Start with /speckit.start {ID}

Technical Details

The command is implemented as a Claude Code skill at .claude/commands/epic.md. It’s a prompt-based workflow that orchestrates:

• Input parsing and document fetching
• Opus model analysis with structured guidelines
• BACKLOG.md table manipulation
• GitHub issue creation via gh CLI

No new code dependencies—just workflow orchestration using existing tools.

What’s Next

The first epic to use this workflow will be Storyboarding Briefings—a feature complex enough to validate the decomposition approach. Stay tuned for that breakdown.

Epic workflow support is live. Try /epic with your next large feature.

The Debrief VS Code extension now automatically hides non-essential activity bar items when it activates. Instead of seeing Explorer, Search, Source Control, Debug, Extensions, and Testing, analysts see just two activities: Explorer (for browsing STAC stores) and Debrief (for analysis tools).

Five distractions removed. Zero functionality lost. The hidden activities still work if you need them — right-click the activity bar to restore any of them.

How It Works

On first activation, the extension modifies VS Code’s workbench.activity.pinnedViewlets2 setting to hide:

• Search
• Source Control
• Run and Debug
• Extensions
• Testing

The hiding is reversible and respects user choice:

• Right-click activity bar → Show hidden activities
• Command Palette → Debrief: Restore Default Activities
• Settings → debrief.hideActivities.enabled: false

If you re-enable an activity manually, it stays visible on subsequent launches. We track your choices and don’t override them.

Technical Details

The implementation adds an ActivityBarService that:

1. Checks if hiding is enabled (default: yes)
2. Checks if this is the first run
3. Modifies visibility for target activities only
4. Stores a snapshot to detect user overrides later

76 tests pass, including tests for:

• First-run hiding behavior
• Protected views (Explorer and Debrief never hidden)
• User override detection
• Restore command functionality

All operations are local. No network calls. Works completely offline.

Configuration

{
  "debrief.hideActivities.enabled": true,
  "debrief.hideActivities.viewIds": [
    "workbench.view.search",
    "workbench.view.scm",
    "workbench.view.debug",
    "workbench.view.extensions",
    "workbench.view.testing"
  ]
}

Advanced users can customize which activities get hidden.

What’s Next

This is the first of several UX improvements for the analysis environment. Next up: workspace configuration and panel layouts that make better use of screen real estate for map-centric workflows.

View the PR

Read the spec