2026-03-11 simulator logger and diagnostic dump plan

This record captures the simulator enhancement that adds one-file diagnostic export/import and a header-level logger toggle for immediate debug switching.

Background

Developers need a fast way to share reproducible simulator sessions and toggle SDK logs during investigation without restarting docs with custom startup flags.

Goal and scope

• Add one-click diagnostic export for mapHex, pathHex, roomProperties, and runtime.
• Add one-click diagnostic import that restores state and re-renders automatically.
• Add a header-level logger toggle and apply changes immediately by rebuilding simulator render state.

Out of scope:

• Multi-file zip diagnostic packages.
• Persisting derived metadata such as runtime support matrix.

Chosen approach

• Remove logger-specific CLI startup flags from robot-map-docs.
• Keep logger state in simulator UI (default: off) and map it to config.global.enableLogger.
• Re-render map after logger toggle so logger config takes effect immediately.
• Use a versioned single JSON dump (version: 1) as the diagnostic exchange format.
• Validate and normalize imported runtime payload by runtime defaults before applying to the SDK instance.

Impacted files or modules

• bin/docs-server.js
• src/simulator/types/index.ts
• src/simulator/core/useRuntimeBindings.ts
• src/simulator/core/usePlaygroundRender.ts
• src/simulator/core/useMapPlayground.ts
• src/simulator/components/SimulatorActionBar.vue
• src/simulator/components/SimulatorMapPlayground.vue

Verification checklist

• [ ] robot-map-docs --open still opens docs correctly.
• [ ] Header logger toggle defaults to OFF on initial load.
• [ ] Toggling logger ON/OFF re-renders the map and updates visual state.
• [ ] Export action downloads a valid .simulator-dump.json file.
• [ ] Import action restores map/path/room/runtime and re-renders successfully.
• [ ] Import flow does not report success when map render fails.
• [ ] npm run lint passes.
• [ ] npx tsc --noEmit passes.