2026-03-11 simulator src migration implementation record

This record captures the implementation of the simulator source migration from docs/.vitepress/theme/components/simulator to src/simulator, while keeping simulator code out of all SDK runtime build artifacts.

Change summary

• Moved simulator implementation into src/simulator with a structured layout: components/, core/, adapters/, and types/index.ts.
• Replaced docs MapPlayground with a thin host component that only mounts the simulator implementation from src/simulator.
• Removed docs-side simulator implementation files and docs-side simulator type shims.
• Unified simulator type sourcing to @core/@types and @core/@types/callbacks through src/simulator/adapters/sdkTypes.ts.
• Added import guardrails to forbid @simulator imports from runtime modules: src/core/**, src/rjs-entry/**, and src/app/**.
• Added @simulator alias wiring for root Vite/TypeScript and VitePress docs.

Key files

• src/simulator/components/SimulatorMapPlayground.vue
• src/simulator/core/useMapPlayground.ts
• src/simulator/adapters/external.ts
• src/simulator/adapters/sdkTypes.ts
• src/simulator/types/index.ts
• src/simulator/index.ts
• docs/.vitepress/theme/components/MapPlayground.vue
• docs/.vitepress/config.ts
• docs/.vitepress/tsconfig.json
• vite.config.js
• tsconfig.json
• eslint.config.js
• package.json

Risk points and handling

• Risk: simulator code accidentally enters SDK/runtime bundles.
  • Handling: added ESLint no-restricted-imports guardrail for runtime folders and verified built outputs by keyword scanning.
• Risk: docs typecheck pulls in full core runtime implementation and fails for unrelated reasons.
  • Handling: constrained docs typecheck path mapping to simulator-relevant targets and type-only modules.
• Risk: behavior regression during file relocation.
  • Handling: migrated files with no feature changes and preserved existing simulator render/runtime/event/cache logic paths.

Verification results

• npm run lint: pass
• npx tsc --noEmit: pass
• npm run typecheck:docs: pass
• npm run build:core: pass
• npm run build:rjs: pass
• npm run build:app: pass

Artifact exclusion evidence

After each build target, outputs were scanned with: rg -n "simulator|SimulatorMapPlayground|@simulator|useMapPlayground|src/simulator".

• build:core output (dist/**): no simulator markers found.
• build:rjs output (dist/index.rjs.js): no simulator markers found.
• build:app output (dist-app/**): no simulator markers found.