Simulator runtime controls Implementation Plan

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

Goal: Add a runtime control console to the simulator page so developers can inspect and update all RuntimeConfig fields from the docs UI.

Architecture: Keep source data rendering and runtime updates on separate paths. Source inputs continue to use the existing full render pipeline, while runtime controls update a dedicated runtime draft and call mapApi.updateRuntime() incrementally. Build the new UI as focused simulator components and composables so the page stays maintainable.

Tech Stack: Vue 3 Composition API, VitePress, TypeScript, existing simulator composables, MapApplication.updateRuntime()

---

Task 1: Define runtime-facing simulator types and defaults

Files:

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

Step 1: Add runtime UI metadata types

Add types for:

• runtime field groups
• disabled-state reasons
• room option descriptors
• runtime preset descriptors
• runtime support matrix

Step 2: Add simulator runtime defaults and labels

Define:

• the default runtime draft
• unit-to-label defaults
• field-group metadata
• safe preset definitions

Step 3: Run type-check

Run: npx tsc --noEmit Expected: PASS

Task 2: Build runtime state composable

Files:

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

Step 1: Create useRuntimePlayground()

Implement a composable that manages:

• runtimeDraft
• runtimeModified
• preset application
• normalization helpers
• runtime JSON snapshot
• room-derived option lists

Step 2: Encode normalization rules

Add helpers to:

• filter invalid room IDs
• reset dividingRoomId to -1 when needed
• force enableMapClickCapture off when interaction is disabled
• keep custom unitLabel once it has diverged from the default

Step 3: Integrate the composable into useMapPlayground.ts

Expose runtime state and actions from the page-level composable without mixing them into source-input logic.

Step 4: Run type-check

Run: npx tsc --noEmit Expected: PASS

Task 3: Expose map instance and room-derived support data

Files:

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

Step 1: Expose the active map instance

Update useMapCanvas.ts so callers can access the live map instance and call updateRuntime() after the initial render succeeds.

Step 2: Extract room-level derived data after render

Update usePlaygroundRender.ts to publish:

• parsed room list
• room labels derived from map and roomProperties
• runtime support signals based on parsed content

Step 3: Avoid full redraw on runtime-only changes

Keep renderMap() responsible for source data changes only. Do not route runtime updates back into this function.

Step 4: Run type-check

Run: npx tsc --noEmit Expected: PASS

Task 4: Build the runtime-to-map binding layer

Files:

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

Step 1: Create useRuntimeBindings()

Implement bindings that:

• accept partial runtime changes from the UI
• call mapApi.updateRuntime(partial)
• keep a last-applied snapshot
• surface lightweight runtime errors

Step 2: Add room-click synchronization

Wire map room-click callbacks so:

• clicking a room updates selectRoomIds
• checkmark mode toggles selection
• order mode appends or removes while preserving order

Step 3: Add normalization after source re-render

When map data changes, re-validate runtime draft against the new room list and re-apply the normalized runtime if needed.

Step 4: Run type-check

Run: npx tsc --noEmit Expected: PASS

Task 5: Build runtime panel UI components

Files:

• Create: docs/.vitepress/theme/components/simulator/SimulatorRuntimePanel.vue
• Create: docs/.vitepress/theme/components/simulator/SimulatorRuntimeGroup.vue
• Create: docs/.vitepress/theme/components/simulator/SimulatorRuntimeField.vue
• Create: docs/.vitepress/theme/components/simulator/SimulatorRoomSelectionPanel.vue
• Create: docs/.vitepress/theme/components/simulator/SimulatorInspectorPanel.vue
• Test: npm run lint

Step 1: Build generic runtime group and field components

Support the control types needed in V1:

• switch
• select
• segmented choice
• range plus number
• room checklist
• room chips
• disabled readonly lists

Step 2: Build the room-selection sub-panel

Include:

• enable switch
• selection mode switch
• room checklist
• selected-room chips
• clear selection action
• disabled-state hints

Step 3: Build the inspector panel

Show:

• runtime snapshot JSON
• selected room IDs
• captured map click
• lightweight dependency summary

Step 4: Run lint

Run: npm run lint Expected: PASS

Task 6: Integrate runtime console into page layout

Files:

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

Step 1: Add the runtime and inspector panels to the left column

Keep the existing source-data panel intact and add the runtime console beneath it without shrinking the map preview more than necessary.

Step 2: Add preview-side runtime summary

Show a lightweight summary overlay for key states such as:

• selection enabled
• selected room count
• map rotation

Step 3: Verify responsive behavior

Ensure the layout remains usable on mobile and on medium desktop widths.

Step 4: Run docs build

Run: npm run docs:build Expected: PASS

Task 7: Verify the full simulator flow

Files:

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

Step 1: Run lint

Run: npm run lint Expected: PASS

Step 2: Run type-check

Run: npx tsc --noEmit Expected: PASS

Step 3: Run docs build

Run: npm run docs:build Expected: PASS

Step 4: Update the verification checklist

Mark the record checklist with actual results and note any scoped follow-up work that was intentionally deferred.