Simulator events console Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add a developer-facing Events console to the simulator that records public SDK callbacks and exposes them as a live, filterable event stream.

Architecture: Keep event recording separate from source-data rendering and runtime patching. Inject recorder-backed MapCallbacks into the live map instance, store bounded event records in a focused composable, and render them in a dedicated panel near the map preview. Introduce reka-ui only for the new collapsible and menu primitives required by this console.

Tech Stack: Vue 3 Composition API, VitePress, TypeScript, existing simulator composables, SDK MapCallbacks, reka-ui

---

Task 1: Add event-facing simulator types and helpers

Files:

• Modify: docs/.vitepress/theme/components/simulator/types.ts
• Create: docs/.vitepress/theme/components/simulator/eventSummaries.ts
• Test: npx tsc --noEmit

Step 1: Add event record and filter types

Define types for:

• SimulatorEventRecord
• supported callback names in V1
• event filter values
• event panel action payloads if needed

Step 2: Add summary helpers

Create a helper that maps supported callbacks to concise summaries and falls back to a safe default when payload parsing fails.

Step 3: Run type-check

Run: npx tsc --noEmit Expected: PASS

Task 2: Build the event store composable

Files:

• Create: docs/.vitepress/theme/components/simulator/useSimulatorEvents.ts
• Test: npx tsc --noEmit

Step 1: Create bounded event state

Implement state for:

• full event list
• paused state
• active callback filter
• derived filtered list

Limit the stored list to the latest 100 entries.

Step 2: Add event actions

Implement:

• pushEvent()
• clearEvents()
• toggleEventsPaused()
• setEventFilter()
• copyEventsJson()

Step 3: Run type-check

Run: npx tsc --noEmit Expected: PASS

Task 3: Add recorder-backed SDK callbacks

Files:

• Modify: docs/.vitepress/theme/components/simulator/useMapCanvas.ts
• Modify: docs/.vitepress/theme/components/simulator/usePlaygroundRender.ts
• Modify: docs/.vitepress/theme/components/simulator/useMapPlayground.ts
• Test: npx tsc --noEmit

Step 1: Define callback wrappers

Create a recorder-backed events object that wraps supported MapCallbacks and forwards payloads into pushEvent().

Step 2: Attach wrappers to the map lifecycle

Ensure the live map instance always receives the wrapped callbacks after render and after source-data reinitialization.

Step 3: Keep runtime and event paths separate

Do not route event recording through runtime patch logic or source-data cache logic.

Step 4: Run type-check

Run: npx tsc --noEmit Expected: PASS

Task 4: Install and integrate reka-ui primitives

Files:

• Modify: package.json
• Modify: lockfile
• Test: npm install
• Test: npx tsc --noEmit

Step 1: Add the dependency

Install reka-ui and update the lockfile.

Step 2: Verify the docs bundle resolves the package

Confirm imports compile cleanly in the docs app.

Step 3: Run type-check

Run: npx tsc --noEmit Expected: PASS

Task 5: Build the events UI components

Files:

• Create: docs/.vitepress/theme/components/simulator/SimulatorEventsPanel.vue
• Create: docs/.vitepress/theme/components/simulator/SimulatorEventItem.vue
• Test: npm run lint

Step 1: Build the panel shell

Render:

• title
• filter control
• pause button
• clear button
• copy button
• empty state
• scrollable event list

Step 2: Build event rows

Each row must show:

• callback name
• timestamp label
• summary
• collapsible JSON payload

Use reka-ui primitives for the collapsible payload and filter control if they materially improve structure and accessibility.

Step 3: Run lint

Run: npm run lint Expected: PASS

Task 6: Integrate the events panel into the simulator layout

Files:

• Modify: docs/.vitepress/theme/components/MapPlayground.vue
• Modify: docs/.vitepress/theme/components/simulator/SimulatorPreviewPanel.vue
• Modify: docs/.vitepress/theme/components/simulator/useMapPlayground.ts
• Test: npm run docs:build

Step 1: Add the events panel below the map preview

Keep the map large and ensure the event console does not collapse the preview area unreasonably.

Step 2: Pass event state through the page-level composable

Expose filtered events and event actions cleanly from useMapPlayground().

Step 3: Run docs build

Run: npm run docs:build Expected: PASS

Task 7: Verify the full event flow and update traceability

Files:

• Modify: docs/records/plans/2026-03-10-simulator-events-console-plan.md
• Test: npm run lint
• Test: npx tsc --noEmit
• Test: npm run docs:build

Step 1: Update verification checklist

Mark completed verification items and note any deferred event types.

Step 2: Run the full validation suite

Run: npm run lint Expected: PASS

Run: npx tsc --noEmit Expected: PASS

Run: npm run docs:build Expected: PASS

Step 3: Prepare for implementation handoff

Ensure the plan remains aligned with the approved design and current simulator structure.