Simulator playground plan (March 10, 2026)

Background

Developers need a direct way to validate raw map payloads while reading the SDK docs. The goal is to avoid switching to a separate demo app for basic integration checks.

Goal and scope

Add a new documentation section named simulator with a browser-only playground that:

• Accepts mapHex as required input.
• Accepts optional pathHex and optional roomProperties JSON.
• Renders the map in real time after an explicit action.
• Uses a clean and minimal UI suited for long payload input.

Out of scope:

• Sharing logic with src/app/debugTools.
• Heatmap and other advanced layers in this first version.

Chosen approach

Implement a standalone VitePress component (MapPlayground.vue) and register it globally in the VitePress theme. The component owns parsing, rendering, error display, and long-text editing mode.

Parsing rule:

• If normalized mapHex starts with 7b22, treat it as structured map data.
• Otherwise, treat it as raster map data.

Impacted files and modules

• docs/.vitepress/config.ts
• docs/.vitepress/theme/index.ts
• docs/.vitepress/theme/components/MapPlayground.vue
• docs/simulator/index.md

Verification checklist

• [ ] Navigation includes 模拟调试 and routes to /simulator/.
• [ ] mapHex is required and has default sample data.
• [ ] pathHex and roomProperties are optional.
• [ ] Structured/raster branch follows the 7b22 rule.
• [ ] Long inputs can be edited in full-screen mode.
• [ ] Errors are scoped to each optional field when possible.
• [ ] npm run lint passes.
• [ ] npx tsc --noEmit passes.