Background

The simulator currently lives under docs/.vitepress/theme/components/simulator. This has created repeated type drift risk and extra maintenance overhead, because simulator code and SDK source are separated by docs-specific wrappers and shims.

The target is to move simulator implementation into src/simulator so it can share source-level types and be easier to test, while ensuring simulator code is never bundled into SDK runtime outputs (dist, dist-app, dist-docs behavior must stay intentional and predictable).

Goal and scope

This plan covers architecture and migration for simulator source location only.

In scope:

• Move simulator implementation from docs theme folder to src/simulator.
• Keep docs page as a thin shell that imports simulator from src/simulator.
• Remove duplicated docs-only type shims where possible.
• Add guardrails to prevent simulator from being imported by SDK runtime entry modules.
• Prepare testability hooks and folder boundaries for future tests.

Out of scope:

• New simulator features.
• SDK public API changes for business consumers.
• Large UI redesign.

Brainstorming summary

Option A: keep simulator in docs and keep improving shims

Pros:

• Lowest migration cost.
• No import path changes in docs.

Cons:

• Type source remains split and can drift again.
• Harder to add shared tests.
• Architectural boundary stays weak.

Option B (recommended): move simulator to src/simulator and keep docs as host

Pros:

• One source-of-truth for simulator logic.
• Easier unit/integration tests and future reuse.
• Cleaner type usage with direct source aliases.

Cons:

• Medium migration effort.
• Requires clear packaging and import guardrails.

Option C: extract simulator into an internal workspace package

Pros:

• Strong isolation and independent lifecycle.
• Clear ownership boundaries.

Cons:

• Highest complexity and tooling overhead.
• Not justified for current team size and iteration speed.

Recommendation: adopt Option B now; revisit Option C only if simulator grows into an independent product surface.

Chosen approach

Use src/simulator as the implementation root and keep docs as the presentation host.

Target structure

• src/simulator/core/*: render and runtime orchestration hooks.
• src/simulator/components/*: UI components used by the simulator page.
• src/simulator/types/*: simulator-specific domain types.
• src/simulator/adapters/*: integration with SDK runtime (MapApplication, parsers, callbacks).
• src/simulator/index.ts: stable entry for docs consumption.

Docs side keeps only:

• page routing and markdown.
• a thin Vue wrapper that imports from src/simulator.

Packaging and build constraints

Simulator must not be included in SDK distributed runtime outputs.

Control points:

• build:core entry remains src/core/index.ts.
• build:rjs entry remains src/rjs-entry/index.ts.
• build:app entry remains src/app/index.html.
• No runtime entry may import @simulator/*.

Guardrails to add during implementation:

• Add alias @simulator/* -> src/simulator/* for docs/dev usage.
• Add lint/CI rule to forbid @simulator/* imports from:
  • src/core/**
  • src/rjs-entry/**
  • src/app/**
• Keep npm files config unchanged so src/** is not published as source payload.

Type strategy

• Prefer direct imports from @core/@types and @core/@types/callbacks.
• Remove docs-only duplicated type declarations for simulator.
• If a bridge declaration is still required for docs toolchain, keep it minimal and reference core types instead of redefining contracts.

Migration phases

1. Create src/simulator skeleton and move pure TS composables first.
2. Move simulator Vue components and update local imports.
3. Replace docs theme imports with src/simulator entry imports.
4. Remove obsolete docs simulator files and stale shims.
5. Add guardrails and run full verification.

Impacted files and modules

Expected primary changes:

• src/simulator/** (new)
• docs/.vitepress/theme/components/MapPlayground.vue (thin host update)
• docs/.vitepress/theme/components/simulator/** (deletion or wrappers)
• docs/.vitepress/tsconfig.json (path cleanup)
• vite.config.js and/or docs VitePress alias config (simulator alias)
• lint config and CI scripts (import guardrail)

Verification checklist

• npm run lint passes.
• npx tsc --noEmit passes.
• npm run typecheck:docs passes.
• npm run docs:dev starts and simulator page works.
• npm run build:core output contains no simulator modules.
• npm run build:rjs output contains no simulator modules.
• npm run build:app output contains no simulator modules.
• Simulator interactions still work: map/path/room input, runtime controls, events filter, local cache restore.

Risks and mitigations

• Risk: accidental import from runtime entries brings simulator into SDK bundle. Mitigation: lint/CI import restriction and explicit bundle grep checks.

• Risk: alias mismatch between docs and root config. Mitigation: define simulator alias once and reference consistently.

• Risk: migration breaks docs-only UX integration. Mitigation: keep docs wrapper thin and preserve existing props/events contract.

Decision

Proceed with Option B (src/simulator migration) in a dedicated implementation session, with packaging guardrails as mandatory acceptance criteria.