npm - @ray-js/robot-map-sdk - Versions diffs - 0.0.14-beta.5 → 0.0.14 - Mend

@ray-js/robot-map-sdk 0.0.14-beta.5 → 0.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (122) hide show

package/dist-docs/assets/records_bugs_2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md.BbQpA41Y.js DELETED Viewed

	@@ -1,2 +0,0 @@
1	- import{_ as o,c as i,o as s,aq as a}from"./chunks/framework.CBLqO2Q1.js";const u=JSON.parse('{"title":"2026-02-28 fix: Pixi WebGPU snapshot roomInfo white screen","description":"","frontmatter":{},"headers":[],"relativePath":"records/bugs/2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md","filePath":"records/bugs/2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md","lastUpdated":1772253529000}'),r={name:"records/bugs/2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md"};function t(n,e,c,l,d,h){return s(),i("div",null,[...e[0]\|\|(e[0]=[a(`<h1 id="_2026-02-28-fix-pixi-webgpu-snapshot-roominfo-white-screen" tabindex="-1">2026-02-28 fix: Pixi WebGPU snapshot roomInfo white screen <a class="header-anchor" href="#_2026-02-28-fix-pixi-webgpu-snapshot-roominfo-white-screen" aria-label="Permalink to "2026-02-28 fix: Pixi WebGPU snapshot roomInfo white screen""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>After upgrading <code>pixi.js</code> to <code>8.16.0</code>, the WebGPU rendering flow started failing in one specific sequence: call <code>snapshotByData</code>, then render room information in the main instance.</p><p>This record captures the reproduction path, root cause, fix, and regression checklist so future Pixi upgrades are easier to verify.</p><h2 id="symptom" tabindex="-1">Symptom <a class="header-anchor" href="#symptom" aria-label="Permalink to "Symptom""></a></h2><p>In the demo, run this sequence:</p><ol><li>Render either Raster Map or Structured Map.</li><li>Click <strong>Snapshot Other Map</strong> (this triggers <code>snapshotByData</code>).</li><li>Click <strong>Draw roomInfo</strong>.</li></ol><p>The map turns white and the console reports:</p><ul><li><code>BindGroupSystem._createBindGroup</code></li><li><code>Cannot read properties of null (reading '0'/'2')</code></li></ul><h2 id="root-cause" tabindex="-1">Root cause <a class="header-anchor" href="#root-cause" aria-label="Permalink to "Root cause""></a></h2><p>The issue is in Pixi <code>BindGroup.setResource(resource, index)</code>.</p><p>When replacing a resource, the old logic incorrectly called <code>off('change')</code> on the <strong>new</strong> resource instead of the <strong>previous</strong> resource (<code>currentResource</code>). Because of this, stale listeners can survive on the old resource. After the old resource is destroyed, it can still trigger the current BindGroup callback and null out <code>resources[i]</code>, which later crashes WebGPU bind group creation.</p><h2 id="fix" tabindex="-1">Fix <a class="header-anchor" href="#fix" aria-label="Permalink to "Fix""></a></h2><p>The project patch updates both CJS and ESM files:</p><ul><li><code>node_modules/pixi.js/lib/rendering/renderers/gpu/shader/BindGroup.js</code></li><li><code>node_modules/pixi.js/lib/rendering/renderers/gpu/shader/BindGroup.mjs</code></li></ul><p>Key change:</p><div class="language-diff vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">diff</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#B31D28;--shiki-dark:#FDAEB7;">- resource.off?.("change", this.onResourceChange, this)</span></span>
2	- <span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">+ currentResource.off?.("change", this.onResourceChange, this)</span></span></code></pre></div><p>Patch location:</p><ul><li><code>patches/pixi.js+8.16.0.patch</code></li></ul><h2 id="risk-assessment" tabindex="-1">Risk assessment <a class="header-anchor" href="#risk-assessment" aria-label="Permalink to "Risk assessment""></a></h2><p>This is a low-intrusion lifecycle fix. It only changes listener cleanup in the resource replacement path. It does not change rendering strategy or public business APIs.</p><h2 id="regression-checklist" tabindex="-1">Regression checklist <a class="header-anchor" href="#regression-checklist" aria-label="Permalink to "Regression checklist""></a></h2><p>Run these checks after each Pixi upgrade or patch refresh:</p><ol><li>Raster -> Snapshot Other Map -> Draw roomInfo.</li><li>Structured -> Snapshot Other Map -> Draw roomInfo.</li><li>Repeat snapshot multiple times, then toggle <code>showRoomProperty</code>.</li><li>Run one core flow on both WebGPU and WebGL.</li></ol><h2 id="related-changes" tabindex="-1">Related changes <a class="header-anchor" href="#related-changes" aria-label="Permalink to "Related changes""></a></h2><ul><li><code>package.json</code>: upgrade <code>pixi.js</code> to <code>8.16.0</code></li><li><code>yarn.lock</code>: lockfile update</li><li><code>patches/pixi.js+8.16.0.patch</code>: new versioned patch (includes this fix)</li></ul>`,26)])])}const g=o(r,[["render",t]]);export{u as __pageData,g as default};

package/dist-docs/assets/records_bugs_2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md.BbQpA41Y.lean.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as o,c as i,o as s,aq as a}from"./chunks/framework.CBLqO2Q1.js";const u=JSON.parse('{"title":"2026-02-28 fix: Pixi WebGPU snapshot roomInfo white screen","description":"","frontmatter":{},"headers":[],"relativePath":"records/bugs/2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md","filePath":"records/bugs/2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md","lastUpdated":1772253529000}'),r={name:"records/bugs/2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md"};function t(n,e,c,l,d,h){return s(),i("div",null,[...e[0]||(e[0]=[a("",26)])])}const g=o(r,[["render",t]]);export{u as __pageData,g as default};

package/dist-docs/assets/records_bugs_2026-03-10-events-drawer-toolbar-scroll-bugfix.md.DbHxPv4D.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as a,c as t,o,aq as r}from"./chunks/framework.CBLqO2Q1.js";const m=JSON.parse('{"title":"Events drawer toolbar and scroll bugfix","description":"","frontmatter":{},"headers":[],"relativePath":"records/bugs/2026-03-10-events-drawer-toolbar-scroll-bugfix.md","filePath":"records/bugs/2026-03-10-events-drawer-toolbar-scroll-bugfix.md","lastUpdated":1773145284000}'),l={name:"records/bugs/2026-03-10-events-drawer-toolbar-scroll-bugfix.md"};function s(i,e,n,d,c,h){return o(),t("div",null,[...e[0]||(e[0]=[r('<h1 id="events-drawer-toolbar-and-scroll-bugfix" tabindex="-1">Events drawer toolbar and scroll bugfix <a class="header-anchor" href="#events-drawer-toolbar-and-scroll-bugfix" aria-label="Permalink to "Events drawer toolbar and scroll bugfix""></a></h1><p>This record captures a small simulator follow-up that simplified the Events panel and fixed the drawer scroll container behavior.</p><h2 id="symptom" tabindex="-1">Symptom <a class="header-anchor" href="#symptom" aria-label="Permalink to "Symptom""></a></h2><p>The Events drawer exposed controls that were not useful in the current simulator workflow. It also showed a subtle visual overflow when the event list became long. The last event card could appear to extend slightly past the visible drawer boundary.</p><h2 id="reproducible-steps" tabindex="-1">Reproducible steps <a class="header-anchor" href="#reproducible-steps" aria-label="Permalink to "Reproducible steps""></a></h2><ol><li>Open the simulator page.</li><li>Open the Events drawer from the map preview.</li><li>Trigger enough SDK callbacks to populate a longer list.</li><li>Scroll to the bottom of the drawer.</li><li>Observe that the final event item appears to sit slightly outside the container edge.</li></ol><h2 id="root-cause" tabindex="-1">Root cause <a class="header-anchor" href="#root-cause" aria-label="Permalink to "Root cause""></a></h2><p>The drawer mixed fixed-height assumptions with a scrollable list that used a <code>calc()</code>-based max-height. That layout became fragile once the drawer header and content height varied. The panel also retained extra toolbar actions that no longer matched the intended minimal UX.</p><h2 id="patch-summary" tabindex="-1">Patch summary <a class="header-anchor" href="#patch-summary" aria-label="Permalink to "Patch summary""></a></h2><ul><li>Removed the unused Events actions and kept only <code>Close</code> and <code>Clear</code>.</li><li>Simplified <code>useSimulatorEvents()</code> to remove filter, pause, and copy state.</li><li>Converted the Events drawer to a column flex layout.</li><li>Let the event list consume remaining space with <code>flex: 1</code> and <code>min-height: 0</code>.</li><li>Added inner scroll padding to avoid the final item visually touching the container boundary.</li></ul><h2 id="risk-assessment" tabindex="-1">Risk assessment <a class="header-anchor" href="#risk-assessment" aria-label="Permalink to "Risk assessment""></a></h2><p>This change is localized to the simulator Events UI and its local state store. It does not change SDK callback wiring or event payload recording.</p><h2 id="regression-checklist" tabindex="-1">Regression checklist <a class="header-anchor" href="#regression-checklist" aria-label="Permalink to "Regression checklist""></a></h2><ul><li>Confirm the Events drawer still opens and closes from the preview panel.</li><li>Confirm <code>Clear</code> removes all recorded entries.</li><li>Confirm event recording still works for <code>onClickRoom</code> and <code>onClickRoomProperties</code>.</li><li>Confirm long event lists scroll entirely within the drawer.</li></ul>',14)])])}const p=a(l,[["render",s]]);export{m as __pageData,p as default};

package/dist-docs/assets/records_bugs_2026-03-10-events-drawer-toolbar-scroll-bugfix.md.DbHxPv4D.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_bugs_2026-03-10-simulator-initial-render-layout-bugfix.md.w7--2hvH.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as a,c as i,o as t,aq as r}from"./chunks/framework.CBLqO2Q1.js";const m=JSON.parse('{"title":"Simulator initial render and layout bugfix (March 10, 2026)","description":"","frontmatter":{},"headers":[],"relativePath":"records/bugs/2026-03-10-simulator-initial-render-layout-bugfix.md","filePath":"records/bugs/2026-03-10-simulator-initial-render-layout-bugfix.md","lastUpdated":1773123455000}'),o={name:"records/bugs/2026-03-10-simulator-initial-render-layout-bugfix.md"};function l(s,e,n,d,c,u){return t(),i("div",null,[...e[0]||(e[0]=[r('<h1 id="simulator-initial-render-and-layout-bugfix-march-10-2026" tabindex="-1">Simulator initial render and layout bugfix (March 10, 2026) <a class="header-anchor" href="#simulator-initial-render-and-layout-bugfix-march-10-2026" aria-label="Permalink to "Simulator initial render and layout bugfix (March 10, 2026)""></a></h1><h2 id="symptom" tabindex="-1">Symptom <a class="header-anchor" href="#symptom" aria-label="Permalink to "Symptom""></a></h2><p>The simulator page showed an empty canvas after load even though default <code>mapHex</code> data existed. The map preview area also looked too small for practical inspection of large maps.</p><h2 id="reproducible-steps" tabindex="-1">Reproducible steps <a class="header-anchor" href="#reproducible-steps" aria-label="Permalink to "Reproducible steps""></a></h2><ol><li>Open <code>/simulator/</code> in docs.</li><li>Observe status text before any action.</li><li>Observe preview panel size on desktop.</li></ol><h2 id="root-cause" tabindex="-1">Root cause <a class="header-anchor" href="#root-cause" aria-label="Permalink to "Root cause""></a></h2><ul><li>The component only prefilled <code>mapHex</code> state and initialized canvas, but did not trigger first render.</li><li>The page inherited default docs content width and the previous grid split, which constrained the preview area.</li></ul><h2 id="patch-summary" tabindex="-1">Patch summary <a class="header-anchor" href="#patch-summary" aria-label="Permalink to "Patch summary""></a></h2><ul><li>Trigger initial <code>renderMap()</code> on mount.</li><li>Switch layout to preview-first with a larger desktop map area.</li><li>Expand simulator page content width and disable page aside via frontmatter.</li><li>Increase preview container minimum height.</li></ul><h2 id="risk-assessment" tabindex="-1">Risk assessment <a class="header-anchor" href="#risk-assessment" aria-label="Permalink to "Risk assessment""></a></h2><ul><li>Low risk. Changes are isolated to simulator docs UI.</li><li>No runtime SDK behavior changes.</li></ul><h2 id="regression-checklist" tabindex="-1">Regression checklist <a class="header-anchor" href="#regression-checklist" aria-label="Permalink to "Regression checklist""></a></h2><ul><li>[ ] <code>/simulator/</code> renders default <code>mapHex</code> without manual click.</li><li>[ ] Preview area is significantly larger on desktop.</li><li>[ ] Mobile layout remains stacked and usable.</li><li>[ ] <code>mapHex</code> required behavior remains unchanged.</li><li>[ ] Optional <code>pathHex</code> and <code>roomProperties</code> remain non-blocking.</li></ul>',13)])])}const p=a(o,[["render",l]]);export{m as __pageData,p as default};

package/dist-docs/assets/records_bugs_2026-03-10-simulator-initial-render-layout-bugfix.md.w7--2hvH.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_bugs_2026-03-10-simulator-wheel-scroll-leak-bugfix.md.B6gIem2P.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as a,c as l,o,aq as r}from"./chunks/framework.CBLqO2Q1.js";const d=JSON.parse('{"title":"Simulator wheel scroll leak bugfix (March 10, 2026)","description":"","frontmatter":{},"headers":[],"relativePath":"records/bugs/2026-03-10-simulator-wheel-scroll-leak-bugfix.md","filePath":"records/bugs/2026-03-10-simulator-wheel-scroll-leak-bugfix.md","lastUpdated":1773123455000}'),s={name:"records/bugs/2026-03-10-simulator-wheel-scroll-leak-bugfix.md"};function t(i,e,c,h,n,u){return o(),l("div",null,[...e[0]||(e[0]=[r('<h1 id="simulator-wheel-scroll-leak-bugfix-march-10-2026" tabindex="-1">Simulator wheel scroll leak bugfix (March 10, 2026) <a class="header-anchor" href="#simulator-wheel-scroll-leak-bugfix-march-10-2026" aria-label="Permalink to "Simulator wheel scroll leak bugfix (March 10, 2026)""></a></h1><h2 id="symptom" tabindex="-1">Symptom <a class="header-anchor" href="#symptom" aria-label="Permalink to "Symptom""></a></h2><p>When users use the mouse wheel over the map preview area to zoom the map, the whole docs page scrolls at the same time.</p><h2 id="reproducible-steps" tabindex="-1">Reproducible steps <a class="header-anchor" href="#reproducible-steps" aria-label="Permalink to "Reproducible steps""></a></h2><ol><li>Open <code>/simulator/</code>.</li><li>Move cursor over the map canvas area.</li><li>Scroll mouse wheel.</li><li>Observe map zoom and page scroll happening together.</li></ol><h2 id="root-cause" tabindex="-1">Root cause <a class="header-anchor" href="#root-cause" aria-label="Permalink to "Root cause""></a></h2><p>Wheel events in the map container did not prevent browser default page scroll. The map interaction consumed wheel input for zoom, but the document scroll behavior was still active.</p><h2 id="patch-summary" tabindex="-1">Patch summary <a class="header-anchor" href="#patch-summary" aria-label="Permalink to "Patch summary""></a></h2><ul><li>Added wheel handler on map container to call <code>preventDefault()</code>.</li><li>Added <code>overscroll-behavior: contain</code> to the map container.</li><li>Moved parsed map result panel to the right-side data panel to improve visual hierarchy.</li></ul><h2 id="risk-assessment" tabindex="-1">Risk assessment <a class="header-anchor" href="#risk-assessment" aria-label="Permalink to "Risk assessment""></a></h2><ul><li>Low risk and isolated to simulator docs page UI.</li><li>Does not change SDK runtime logic.</li></ul><h2 id="regression-checklist" tabindex="-1">Regression checklist <a class="header-anchor" href="#regression-checklist" aria-label="Permalink to "Regression checklist""></a></h2><ul><li>[ ] Wheel zoom over map no longer scrolls the whole page.</li><li>[ ] Page can still scroll normally when cursor is outside map area.</li><li>[ ] Parsed map summary and tree are still available after rendering.</li></ul>',13)])])}const p=a(s,[["render",t]]);export{d as __pageData,p as default};

package/dist-docs/assets/records_bugs_2026-03-10-simulator-wheel-scroll-leak-bugfix.md.B6gIem2P.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_bugs_2026-03-11-docs-server-bin-clean-bugfix.md.GGWCjkok.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as o,c as s,o as i,aq as c}from"./chunks/framework.CBLqO2Q1.js";const b=JSON.parse('{"title":"2026-03-11 docs server bin deletion bugfix","description":"","frontmatter":{},"headers":[],"relativePath":"records/bugs/2026-03-11-docs-server-bin-clean-bugfix.md","filePath":"records/bugs/2026-03-11-docs-server-bin-clean-bugfix.md","lastUpdated":1773214888000}'),a={name:"records/bugs/2026-03-11-docs-server-bin-clean-bugfix.md"};function r(d,e,t,l,n,u){return i(),s("div",null,[...e[0]||(e[0]=[c('<h1 id="_2026-03-11-docs-server-bin-deletion-bugfix" tabindex="-1">2026-03-11 docs server bin deletion bugfix <a class="header-anchor" href="#_2026-03-11-docs-server-bin-deletion-bugfix" aria-label="Permalink to "2026-03-11 docs server bin deletion bugfix""></a></h1><h2 id="symptom" tabindex="-1">Symptom <a class="header-anchor" href="#symptom" aria-label="Permalink to "Symptom""></a></h2><p>After publishing version <code>0.0.10</code>, running <code>npx -y -p @ray-js/robot-map-sdk@latest robot-map-docs</code> failed with <code>command not found</code>.</p><h2 id="reproducible-steps" tabindex="-1">Reproducible steps <a class="header-anchor" href="#reproducible-steps" aria-label="Permalink to "Reproducible steps""></a></h2><ol><li>Run <code>npm run mcp:build</code>.</li><li>Observe that <code>bin/docs-server.js</code> is removed.</li><li>Publish package with <code>package.json</code> still declaring <code>"robot-map-docs": "./bin/docs-server.js"</code>.</li><li>Execute <code>npx ... robot-map-docs</code> from a clean environment.</li></ol><h2 id="root-cause" tabindex="-1">Root cause <a class="header-anchor" href="#root-cause" aria-label="Permalink to "Root cause""></a></h2><p><code>tsup.mcp.config.ts</code> used:</p><ul><li><code>outDir: 'bin'</code></li><li><code>clean: true</code></li></ul><p><code>mcp:build</code> therefore cleaned the entire <code>bin/</code> folder and rebuilt only <code>mcp-server</code>, deleting <code>docs-server.js</code>.</p><h2 id="patch-summary" tabindex="-1">Patch summary <a class="header-anchor" href="#patch-summary" aria-label="Permalink to "Patch summary""></a></h2><ul><li>Restored <code>bin/docs-server.js</code>.</li><li>Changed MCP tsup config to <code>clean: false</code> so <code>mcp:build</code> no longer wipes other <code>bin</code> scripts.</li><li>Hardened publish guard in <code>prepublishOnly</code>: fail fast if <code>bin/docs-server.js</code> is missing before publish.</li></ul><h2 id="risk-assessment" tabindex="-1">Risk assessment <a class="header-anchor" href="#risk-assessment" aria-label="Permalink to "Risk assessment""></a></h2><ul><li>Low runtime risk.</li><li>Main tradeoff: with <code>clean: false</code>, stale MCP artifacts could remain in <code>bin/</code> if filenames change in the future.</li></ul><h2 id="regression-checklist" tabindex="-1">Regression checklist <a class="header-anchor" href="#regression-checklist" aria-label="Permalink to "Regression checklist""></a></h2><ul><li>[x] <code>bin/docs-server.js</code> exists after <code>npm run mcp:build</code>.</li><li>[x] <code>npm run lint</code> passes.</li><li>[x] <code>npx tsc --noEmit</code> passes.</li><li>[x] <code>npm pack --dry-run --json</code> includes <code>bin/docs-server.js</code>.</li></ul>',15)])])}const h=o(a,[["render",r]]);export{b as __pageData,h as default};

package/dist-docs/assets/records_bugs_2026-03-11-docs-server-bin-clean-bugfix.md.GGWCjkok.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_bugs_2026-03-11-render-result-runtime-sync-bugfix.md.DRNUuaFT.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as r,c as a,o as i,aq as s}from"./chunks/framework.CBLqO2Q1.js";const p=JSON.parse('{"title":"Render result runtime sync bugfix (2026-03-11)","description":"","frontmatter":{},"headers":[],"relativePath":"records/bugs/2026-03-11-render-result-runtime-sync-bugfix.md","filePath":"records/bugs/2026-03-11-render-result-runtime-sync-bugfix.md","lastUpdated":1773225787000}'),t={name:"records/bugs/2026-03-11-render-result-runtime-sync-bugfix.md"};function o(l,e,n,d,c,u){return i(),a("div",null,[...e[0]||(e[0]=[s('<h1 id="render-result-runtime-sync-bugfix-2026-03-11" tabindex="-1">Render result runtime sync bugfix (2026-03-11) <a class="header-anchor" href="#render-result-runtime-sync-bugfix-2026-03-11" aria-label="Permalink to "Render result runtime sync bugfix (2026-03-11)""></a></h1><h2 id="symptom" tabindex="-1">Symptom <a class="header-anchor" href="#symptom" aria-label="Permalink to "Symptom""></a></h2><p>When map rendering partially failed (for example, invalid <code>pathHex</code> or invalid <code>roomProperties</code>) but the main map still rendered successfully, simulator flows incorrectly treated the whole render as failed.</p><p>This blocked runtime synchronization and could prevent import-based scene recovery from applying runtime snapshot data.</p><h2 id="reproducible-steps" tabindex="-1">Reproducible steps <a class="header-anchor" href="#reproducible-steps" aria-label="Permalink to "Reproducible steps""></a></h2><ol><li>Provide a valid <code>mapHex</code>.</li><li>Provide an invalid <code>pathHex</code> or malformed <code>roomProperties</code>.</li><li>Trigger render or import diagnostic dump.</li><li>Observe that map can appear, but runtime synchronization/recovery is skipped.</li></ol><h2 id="root-cause" tabindex="-1">Root cause <a class="header-anchor" href="#root-cause" aria-label="Permalink to "Root cause""></a></h2><p><code>usePlaygroundRender.renderMap()</code> returned a single boolean and used <code>false</code> for both:</p><ul><li>fatal map-render failure, and</li><li>non-fatal overlay parse failures.</li></ul><p><code>useMapPlayground.renderMapWithRuntimeSync()</code> interpreted <code>false</code> as a hard failure and returned early, skipping runtime sync.</p><h2 id="patch-summary" tabindex="-1">Patch summary <a class="header-anchor" href="#patch-summary" aria-label="Permalink to "Patch summary""></a></h2><ul><li>Changed <code>renderMap()</code> to return structured result: <ul><li><code>rendered</code>: whether the main map render succeeded.</li><li><code>hasWarnings</code>: whether non-blocking overlay errors occurred.</li><li><code>errors</code>: captured warning/error messages.</li></ul></li><li>Updated runtime sync guard to proceed when <code>rendered === true</code>, even with warnings.</li><li>Kept status messaging explicit for warning cases while preserving successful map render flow.</li></ul><h2 id="risk-assessment" tabindex="-1">Risk assessment <a class="header-anchor" href="#risk-assessment" aria-label="Permalink to "Risk assessment""></a></h2><ul><li>Low-to-medium risk: modifies render result contract used by playground orchestration.</li><li>Limited blast radius: affected call sites are inside simulator core.</li><li>Expected impact: restores runtime synchronization in partial-failure scenarios without masking fatal map failures.</li></ul><h2 id="regression-checklist" tabindex="-1">Regression checklist <a class="header-anchor" href="#regression-checklist" aria-label="Permalink to "Regression checklist""></a></h2><ul><li>[ ] Valid <code>mapHex</code> + invalid <code>pathHex</code> still renders map and syncs runtime.</li><li>[ ] Valid <code>mapHex</code> + invalid <code>roomProperties</code> still renders map and syncs runtime.</li><li>[ ] Import flow with non-fatal overlay errors still applies runtime snapshot.</li><li>[ ] Fatal <code>mapHex</code> parse failure still blocks sync and reports error.</li></ul>',16)])])}const h=r(t,[["render",o]]);export{p as __pageData,h as default};

package/dist-docs/assets/records_bugs_2026-03-11-render-result-runtime-sync-bugfix.md.DRNUuaFT.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_bugs_2026-03-26-fix-pixi-gc-deprecation-warning-bugfix.md.DaCuhvTA.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as i,c as a,o as t,aq as o}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"2026-03-26 fix: Pixi GC deprecation warning","description":"","frontmatter":{},"headers":[],"relativePath":"records/bugs/2026-03-26-fix-pixi-gc-deprecation-warning-bugfix.md","filePath":"records/bugs/2026-03-26-fix-pixi-gc-deprecation-warning-bugfix.md","lastUpdated":1774530199000}'),r={name:"records/bugs/2026-03-26-fix-pixi-gc-deprecation-warning-bugfix.md"};function n(c,e,d,s,l,p){return t(),a("div",null,[...e[0]||(e[0]=[o('<h1 id="_2026-03-26-fix-pixi-gc-deprecation-warning" tabindex="-1">2026-03-26 fix: Pixi GC deprecation warning <a class="header-anchor" href="#_2026-03-26-fix-pixi-gc-deprecation-warning" aria-label="Permalink to "2026-03-26 fix: Pixi GC deprecation warning""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>After upgrading to <code>pixi.js@8.16.0</code>, application initialization started printing this warning:</p><ul><li><code>TextureGCSystem.run is deprecated, please use the GCSystem instead.</code></li></ul><p>The SDK was still passing deprecated <code>textureGCMaxIdle</code> and <code>textureGCCheckCountMax</code> options during renderer initialization.</p><h2 id="symptom" tabindex="-1">Symptom <a class="header-anchor" href="#symptom" aria-label="Permalink to "Symptom""></a></h2><p>Any normal app startup could emit the deprecation warning before any user interaction, which made it harder to distinguish real runtime issues from known library migration noise.</p><h2 id="root-cause" tabindex="-1">Root cause <a class="header-anchor" href="#root-cause" aria-label="Permalink to "Root cause""></a></h2><p>Pixi <code>8.15+</code> moved the primary garbage collection configuration to <code>GCSystem</code> (<code>gcActive</code>, <code>gcMaxUnusedTime</code>, <code>gcFrequency</code>), while the SDK still used the legacy texture GC option names.</p><h2 id="fix" tabindex="-1">Fix <a class="header-anchor" href="#fix" aria-label="Permalink to "Fix""></a></h2><p>Update renderer initialization to use the current Pixi GC options:</p><ul><li>Replace <code>textureGCMaxIdle</code> with <code>gcMaxUnusedTime</code></li><li>Replace <code>textureGCCheckCountMax</code> with <code>gcFrequency</code></li><li>Convert the existing frame-based thresholds to milliseconds so the configured timings keep the same intent after the API migration</li></ul><h2 id="regression-coverage" tabindex="-1">Regression coverage <a class="header-anchor" href="#regression-coverage" aria-label="Permalink to "Regression coverage""></a></h2><ul><li>Added assertions in <code>test/core/application/MapApplication-uncovered-branches.test.ts</code> to verify: <ul><li>the new <code>gc*</code> options are passed</li><li>the old <code>textureGC*</code> options are no longer passed</li></ul></li></ul>',14)])])}const h=i(r,[["render",n]]);export{g as __pageData,h as default};

package/dist-docs/assets/records_bugs_2026-03-26-fix-pixi-gc-deprecation-warning-bugfix.md.DaCuhvTA.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_bugs_2026-03-26-fix-room-floor-type-auto-gc-bugfix.md.DeytN_el.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as o,c as a,o as t,aq as r}from"./chunks/framework.CBLqO2Q1.js";const m=JSON.parse('{"title":"2026-03-26 fix: room floor type auto GC disappearance","description":"","frontmatter":{},"headers":[],"relativePath":"records/bugs/2026-03-26-fix-room-floor-type-auto-gc-bugfix.md","filePath":"records/bugs/2026-03-26-fix-room-floor-type-auto-gc-bugfix.md","lastUpdated":1774530199000}'),i={name:"records/bugs/2026-03-26-fix-room-floor-type-auto-gc-bugfix.md"};function l(s,e,c,d,n,p){return t(),a("div",null,[...e[0]||(e[0]=[r('<h1 id="_2026-03-26-fix-room-floor-type-auto-gc-disappearance" tabindex="-1">2026-03-26 fix: room floor type auto GC disappearance <a class="header-anchor" href="#_2026-03-26-fix-room-floor-type-auto-gc-disappearance" aria-label="Permalink to "2026-03-26 fix: room floor type auto GC disappearance""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>Raster map room floor materials could disappear after the map stayed idle for a few minutes, even when no runtime state changed and no warning was printed.</p><p>The floor material layer is built from a static <code>TilingSprite</code> plus cloned <code>Graphics</code> masks in <code>RoomFloorType</code>.</p><h2 id="symptom" tabindex="-1">Symptom <a class="header-anchor" href="#symptom" aria-label="Permalink to "Symptom""></a></h2><p>Reproduction path:</p><ol><li>Render a raster map with room properties and floor materials.</li><li>Do not interact with the map.</li><li>Wait a few minutes.</li></ol><p>The room floor material pattern disappears while the base room fill remains.</p><h2 id="root-cause" tabindex="-1">Root cause <a class="header-anchor" href="#root-cause" aria-label="Permalink to "Root cause""></a></h2><p>The SDK uses a mostly on-demand render model (<code>renderOnce</code> / <code>renderOnceNextFrame</code>) instead of continuous rendering. Under Pixi <code>8.15+</code>, idle renderables can be collected by the unified <code>GCSystem</code>.</p><p><code>RoomFloorType</code> created three static render resources with default automatic GC enabled:</p><ul><li>the <code>TilingSprite</code> for the floor material</li><li>cloned <code>Graphics</code> objects used by the mask</li><li>cloned <code>GraphicsContext</code> objects behind those masks</li></ul><p>Because these resources were not continuously rendered, Pixi could unload them after the GC idle threshold elapsed.</p><h2 id="fix" tabindex="-1">Fix <a class="header-anchor" href="#fix" aria-label="Permalink to "Fix""></a></h2><p>Disable automatic GC for the entire room floor material render chain:</p><ul><li><code>tilingSprite.autoGarbageCollect = false</code></li><li><code>clonedGraphics.autoGarbageCollect = false</code></li><li><code>clonedContext.autoGarbageCollect = false</code></li></ul><p>This keeps the static floor material layer resident until the SDK explicitly clears or destroys it.</p><h2 id="regression-coverage" tabindex="-1">Regression coverage <a class="header-anchor" href="#regression-coverage" aria-label="Permalink to "Regression coverage""></a></h2><p>Added a focused test in <code>test/core/components/RoomFloorType.test.ts</code> to verify that floor sprites, mask graphics, and mask contexts all opt out of automatic GC.</p>',19)])])}const h=o(i,[["render",l]]);export{m as __pageData,h as default};

package/dist-docs/assets/records_bugs_2026-03-26-fix-room-floor-type-auto-gc-bugfix.md.DeytN_el.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-02-furniture-feature-plan.md.CqSsyNDo.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as t,c as o,o as d,aq as r}from"./chunks/framework.CBLqO2Q1.js";const h=JSON.parse('{"title":"Furniture Feature Implementation Plan","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-02-furniture-feature-plan.md","filePath":"records/plans/2026-03-02-furniture-feature-plan.md","lastUpdated":1772616139000}'),a={name:"records/plans/2026-03-02-furniture-feature-plan.md"};function i(n,e,c,s,l,u){return d(),o("div",null,[...e[0]||(e[0]=[r('<h1 id="furniture-feature-implementation-plan" tabindex="-1">Furniture Feature Implementation Plan <a class="header-anchor" href="#furniture-feature-implementation-plan" aria-label="Permalink to "Furniture Feature Implementation Plan""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>Robot vacuum map applications commonly support furniture placement to help users visualize and manage their home layout. This feature allows placing furniture images on the map with full editing capabilities (move, scale, rotate).</p><h2 id="goal-and-scope" tabindex="-1">Goal and Scope <a class="header-anchor" href="#goal-and-scope" aria-label="Permalink to "Goal and Scope""></a></h2><p>Implement a furniture placement and editing feature for the robot vacuum map SDK:</p><ul><li>Render furniture as image sprites on the map using a points-based coordinate system (4 corner vertices)</li><li>Support click-to-rotate (90-degree increments), drag-to-move, and handle-to-scale interactions</li><li>Follow the <code>ControlsManager</code> + <code>Zone</code> architecture pattern for manager structure and CRUD logic</li><li>Expose public API methods (<code>drawFurnitures</code>, <code>getFurniturePointsByViewportCenter</code>) and callbacks (<code>onRemoveFurniture</code>, <code>onUpdateFurniture</code>, <code>onClickFurniture</code>)</li></ul><h2 id="chosen-approach" tabindex="-1">Chosen Approach <a class="header-anchor" href="#chosen-approach" aria-label="Permalink to "Chosen Approach""></a></h2><ul><li><strong>Parameter Design</strong>: <code>FurnitureParam</code> uses the same 4-point model as <code>ZoneParam</code>, with an additional <code>furnitureType</code> field for asset matching</li><li><strong>Architecture</strong>: <code>FurnitureManager</code> manages CRUD via diff-based updates; <code>Furniture</code> component combines <code>Sprite</code> + <code>EditControlLayer</code> + <code>TapRotateButton</code></li><li><strong>Config</strong>: <code>FurnitureConfig</code> added as a top-level <code>AppConfig</code> property with asset definitions, opacity, and outline styling</li><li><strong>Rotation</strong>: New <code>TapRotateButton</code> component (extending <code>BaseControlButton</code>) provides click-to-rotate-90-degree behavior, replacing the standard drag-rotate control</li><li><strong>Layer</strong>: <code>LAYER_FURNITURE</code> inserted between <code>LAYER_PATH</code> and <code>LAYER_CONTROLS</code> in the rendering order</li></ul><h2 id="impacted-files-modules" tabindex="-1">Impacted Files/Modules <a class="header-anchor" href="#impacted-files-modules" aria-label="Permalink to "Impacted Files/Modules""></a></h2><h3 id="new-files" tabindex="-1">New Files <a class="header-anchor" href="#new-files" aria-label="Permalink to "New Files""></a></h3><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><code>src/core/managers/FurnitureManager.ts</code></td><td>Texture loading, CRUD via <code>drawFurnitures</code>, edit-state subscription</td></tr><tr><td><code>src/core/components/Furniture/Furniture.ts</code></td><td>Sprite display + <code>EditControlLayer</code> + <code>TapRotateButton</code></td></tr><tr><td><code>src/core/components/Base/TapRotateButton.ts</code></td><td>Click-to-rotate-90-degrees button</td></tr></tbody></table><h3 id="modified-files" tabindex="-1">Modified Files <a class="header-anchor" href="#modified-files" aria-label="Permalink to "Modified Files""></a></h3><table tabindex="0"><thead><tr><th>File</th><th>Changes</th></tr></thead><tbody><tr><td><code>src/core/@types/index.d.ts</code></td><td>Added <code>FurnitureParam</code>, <code>FurnitureAsset</code>, <code>FurnitureConfig</code> types; <code>furniture</code> to <code>AppConfig</code>; <code>editingFurnitureIds</code> to <code>RuntimeConfig</code></td></tr><tr><td><code>src/core/@types/callbacks.ts</code></td><td>Added <code>onRemoveFurniture</code>, <code>onUpdateFurniture</code>, <code>onClickFurniture</code></td></tr><tr><td><code>src/core/@types/methods.ts</code></td><td>Added <code>drawFurnitures</code>, <code>getFurniturePointsByViewportCenter</code>; <code>furnitures</code> to <code>snapshotByData</code> data param</td></tr><tr><td><code>src/core/constant/methods.ts</code></td><td>Added method/callback names for RJS bundle exposure</td></tr><tr><td><code>src/core/constant/config.ts</code></td><td>Added furniture defaults to <code>DEFAULT_CONFIG</code> and <code>DEFAULT_RUNTIME_CONFIG</code></td></tr><tr><td><code>src/core/application/AppContainer.ts</code></td><td>Added <code>LAYER_FURNITURE</code> constant and layer ordering</td></tr><tr><td><code>src/core/application/MapApplication.ts</code></td><td>Registered <code>FurnitureManager</code>, exposed public API, wired asset preloading/snapshot/origin</td></tr><tr><td><code>src/core/application/AppService.ts</code></td><td>Added <code>furnitureManager</code> and <code>furnitureConfig</code> accessors</td></tr><tr><td><code>src/core/index.docs.ts</code></td><td>Exported <code>FurnitureParam</code> type</td></tr><tr><td><code>src/app/debugTools/index.ts</code></td><td>Added "Test Furniture" button for development verification</td></tr></tbody></table><h2 id="verification-checklist" tabindex="-1">Verification Checklist <a class="header-anchor" href="#verification-checklist" aria-label="Permalink to "Verification Checklist""></a></h2><ul><li>[x] <code>FurnitureParam</code>, <code>FurnitureAsset</code>, <code>FurnitureConfig</code> types defined</li><li>[x] Callbacks (<code>onRemoveFurniture</code>, <code>onUpdateFurniture</code>, <code>onClickFurniture</code>) registered</li><li>[x] Public API methods (<code>drawFurnitures</code>, <code>getFurniturePointsByViewportCenter</code>) exposed</li><li>[x] Default config values provided with <code>doubleBed.png</code> asset</li><li>[x] <code>LAYER_FURNITURE</code> added between <code>LAYER_PATH</code> and <code>LAYER_CONTROLS</code></li><li>[x] <code>TapRotateButton</code> component created</li><li>[x] <code>Furniture</code> component renders sprite from points with editing controls</li><li>[x] <code>FurnitureManager</code> handles CRUD, edit-state, and layer positioning</li><li>[x] Integration in <code>MapApplication</code> (managers, assets, snapshot, origin, destroy)</li><li>[x] Demo app test button functional</li><li>[x] <code>npm run lint</code> passes</li><li>[x] <code>npx tsc --noEmit</code> passes</li></ul>',15)])])}const m=t(a,[["render",i]]);export{h as __pageData,m as default};

package/dist-docs/assets/records_plans_2026-03-02-furniture-feature-plan.md.CqSsyNDo.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-05-testing-infrastructure-design.md.DLHGz5Ez.js DELETED Viewed

@@ -1,77 +0,0 @@
-import{_ as e,c as t,o as a,aq as i}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"Testing Infrastructure Design — robot-map-sdk","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-05-testing-infrastructure-design.md","filePath":"records/plans/2026-03-05-testing-infrastructure-design.md","lastUpdated":1773653672000}'),n={name:"records/plans/2026-03-05-testing-infrastructure-design.md"};function o(r,s,l,p,d,c){return a(),t("div",null,[...s[0]||(s[0]=[i(`<h1 id="testing-infrastructure-design-—-robot-map-sdk" tabindex="-1">Testing Infrastructure Design — robot-map-sdk <a class="header-anchor" href="#testing-infrastructure-design-—-robot-map-sdk" aria-label="Permalink to &quot;Testing Infrastructure Design — robot-map-sdk&quot;"></a></h1><p><strong>Date</strong>: 2026-03-05 <strong>Status</strong>: Implemented — rollout delivered, hardening follow-ups pending <strong>Scope</strong>: Core SDK unit testing infrastructure, phased rollout</p><hr><h2 id="_1-background" tabindex="-1">1. Background <a class="header-anchor" href="#_1-background" aria-label="Permalink to &quot;1. Background&quot;"></a></h2><p>robot-map-sdk is a PIXI.js 8 based 2D robot vacuum map rendering SDK with 85+ TypeScript source files, 10 managers, 50+ visual components, and ~10,000+ LOC of core logic. The testing infrastructure is now in place with broad unit test coverage across <code>src/core</code>.</p><p>This design references <a href="https://github.com/anthropics/openclaw" target="_blank" rel="noreferrer">OpenClaw</a>&#39;s production-grade Vitest setup (1,700+ test files, multi-layer configs, comprehensive isolation) and adapts patterns suitable for a browser-oriented rendering SDK.</p><hr><h3 id="_1-1-actual-delivered-status-as-of-march-16-2026" tabindex="-1">1.1 Actual delivered status (as of March 16, 2026) <a class="header-anchor" href="#_1-1-actual-delivered-status-as-of-march-16-2026" aria-label="Permalink to &quot;1.1 Actual delivered status (as of March 16, 2026)&quot;"></a></h3><ul><li>Completed phases: Phase 1 (infrastructure), Phase 2 (algorithm tests), Phase 3 (manager logic tests), Phase 4 (component tests), and Phase 5 (application layer tests) are delivered.</li><li>Current coverage (<code>npm run test:coverage</code>): lines 93.15%, statements 92.27%, functions 92.04%, branches 81.71%.</li><li>Current test scale (<code>npm run test:coverage</code>): 143 passed test files, 1373 passed tests.</li><li>Current gate baseline: coverage thresholds in <code>vitest.config.ts</code> are non-zero (<code>lines/functions/statements: 85</code>, <code>branches: 70</code>).</li><li>Remaining risk: ratchet upgrades beyond the current baseline should continue release-by-release using the rule in Section 6.3.</li><li>Remaining recommendation: CI gate order (<code>lint</code> → <code>tsc --noEmit</code> → <code>vitest run</code> → <code>build</code>) still needs explicit workflow enforcement.</li><li>Remaining recommendation: visual regression and browser-level E2E remain out of scope and should be planned separately for rendering regressions.</li></ul><hr><h2 id="_2-technical-validation" tabindex="-1">2. Technical Validation <a class="header-anchor" href="#_2-technical-validation" aria-label="Permalink to &quot;2. Technical Validation&quot;"></a></h2><p>All key claims verified against actual source code:</p><table tabindex="0"><thead><tr><th>Claim</th><th>Status</th><th>Evidence</th></tr></thead><tbody><tr><td><code>algorithm.ts</code> functions are pure</td><td>Verified</td><td>38 exported functions, no PIXI/Canvas/DOM/global state imports</td></tr><tr><td>Valtio subscriptions properly cleaned</td><td>Verified</td><td>RoomManager (10 subs), PathManager (2 subs) all unsubscribed in <code>destroy()</code></td></tr><tr><td><code>@ray-js/robot-protocol</code> is lightweight</td><td>Verified</td><td>Type definitions + codec utilities only</td></tr><tr><td>Pure ESM, no CJS</td><td>Verified</td><td><code>&quot;type&quot;: &quot;module&quot;</code>, no <code>require()</code> calls</td></tr><tr><td>No circular dependency risk</td><td>Verified</td><td>AppService uses constructor injection, no circular imports</td></tr><tr><td>PIXI mock needs layered approach</td><td>Verified</td><td>MapApplication extends <code>Application</code>, uses 10+ PIXI APIs</td></tr><tr><td><code>browser.ts</code> needs browser API mock</td><td>Verified</td><td>Uses <code>navigator.userAgent</code>, <code>navigator.deviceMemory</code></td></tr></tbody></table><hr><h2 id="_3-framework-choice" tabindex="-1">3. Framework Choice <a class="header-anchor" href="#_3-framework-choice" aria-label="Permalink to &quot;3. Framework Choice&quot;"></a></h2><p><strong>Vitest</strong> — rationale:</p><ul><li>Native Vite integration (project already uses Vite for builds)</li><li>ESM-first (matches <code>&quot;type&quot;: &quot;module&quot;</code>)</li><li>Path alias resolution reuses <code>vite.config.js</code></li><li>Built-in mocking (<code>vi.fn()</code>, <code>vi.mock()</code>, <code>vi.spyOn()</code>)</li><li><code>@vitest/coverage-v8</code> for accurate V8 coverage</li><li><code>pool: &quot;forks&quot;</code> for process isolation (prevents PIXI global state leaks)</li></ul><p><strong>Installed</strong>: <code>vitest@4.0.18</code>, <code>@vitest/coverage-v8</code> (latest)</p><hr><h2 id="_4-test-organization" tabindex="-1">4. Test Organization <a class="header-anchor" href="#_4-test-organization" aria-label="Permalink to &quot;4. Test Organization&quot;"></a></h2><h3 id="_4-1-directory-structure" tabindex="-1">4.1 Directory Structure <a class="header-anchor" href="#_4-1-directory-structure" aria-label="Permalink to &quot;4.1 Directory Structure&quot;"></a></h3><p>Test files are <strong>centralized</strong> in the <code>test/</code> directory, mirroring the <code>src/core/</code> folder structure. This keeps <code>src/</code> clean and all test-related code in one place.</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>ray-robot-map-sdk/</span></span>
-<span class="line"><span>├── vitest.config.ts                        # Main test config</span></span>
-<span class="line"><span>├── test/</span></span>
-<span class="line"><span>│   ├── setup.ts                            # Global setup (PIXI mock registration, Logger suppression)</span></span>
-<span class="line"><span>│   ├── mocks/</span></span>
-<span class="line"><span>│   │   ├── pixi.ts                         # PIXI.js v8 layered mock</span></span>
-<span class="line"><span>│   │   └── robot-protocol.ts               # @ray-js/robot-protocol mock</span></span>
-<span class="line"><span>│   ├── factories/</span></span>
-<span class="line"><span>│   │   ├── map-data.ts                     # MapData / ParsedRasterMapData builders</span></span>
-<span class="line"><span>│   │   ├── path-data.ts                    # PathData / PathPoint builders</span></span>
-<span class="line"><span>│   │   ├── config.ts                       # AppConfig partial builder</span></span>
-<span class="line"><span>│   │   └── runtime.ts                      # RuntimeConfig partial builder</span></span>
-<span class="line"><span>│   ├── core/</span></span>
-<span class="line"><span>│   │   ├── utils/</span></span>
-<span class="line"><span>│   │   │   ├── algorithm.test.ts           # mirrors src/core/utils/algorithm.ts</span></span>
-<span class="line"><span>│   │   │   └── index.test.ts              # mirrors src/core/utils/index.ts</span></span>
-<span class="line"><span>│   │   ├── application/</span></span>
-<span class="line"><span>│   │   │   ├── AppService.test.ts          # mirrors src/core/application/AppService.ts</span></span>
-<span class="line"><span>│   │   │   ├── MapApplication.test.ts      # mirrors src/core/application/MapApplication.ts</span></span>
-<span class="line"><span>│   │   │   └── Interaction.test.ts         # mirrors src/core/application/Interaction.ts</span></span>
-<span class="line"><span>│   │   ├── managers/</span></span>
-<span class="line"><span>│   │   │   ├── MapManager.test.ts          # mirrors src/core/managers/MapManager.ts</span></span>
-<span class="line"><span>│   │   │   ├── RoomManager.test.ts         # mirrors src/core/managers/RoomManager.ts</span></span>
-<span class="line"><span>│   │   │   ├── PathManager.test.ts         # mirrors src/core/managers/PathManager.ts</span></span>
-<span class="line"><span>│   │   │   └── ControlsManager.test.ts     # mirrors src/core/managers/ControlsManager.ts</span></span>
-<span class="line"><span>│   │   └── components/</span></span>
-<span class="line"><span>│   │       ├── Robot.test.ts               # mirrors src/core/components/Robot.ts</span></span>
-<span class="line"><span>│   │       ├── Path.test.ts                # mirrors src/core/components/Path.ts</span></span>
-<span class="line"><span>│   │       └── ...                         # other component tests</span></span></code></pre></div><h3 id="_4-2-conventions" tabindex="-1">4.2 Conventions <a class="header-anchor" href="#_4-2-conventions" aria-label="Permalink to &quot;4.2 Conventions&quot;"></a></h3><ul><li>Test files centralized in <code>test/core/</code> mirroring <code>src/core/</code> structure: <code>src/core/utils/algorithm.ts</code> → <code>test/core/utils/algorithm.test.ts</code></li><li>Shared mocks and factories centralized in <code>test/mocks/</code> and <code>test/factories/</code></li><li>Test code follows same formatting rules (single quotes, no semicolons, 2-space indent)</li><li>Vitest <code>include</code> pattern: <code>test/**/*.test.ts</code></li></ul><hr><h2 id="_5-mocking-strategy" tabindex="-1">5. Mocking Strategy <a class="header-anchor" href="#_5-mocking-strategy" aria-label="Permalink to &quot;5. Mocking Strategy&quot;"></a></h2><h3 id="_5-1-pixi-js-—-layered-approach" tabindex="-1">5.1 PIXI.js — Layered Approach <a class="header-anchor" href="#_5-1-pixi-js-—-layered-approach" aria-label="Permalink to &quot;5.1 PIXI.js — Layered Approach&quot;"></a></h3><p>PIXI mock complexity is the biggest technical challenge. MapApplication extends <code>Application</code> and uses <code>Assets</code>, <code>RenderTexture</code>, <code>Graphics</code>, <code>Matrix</code>, <code>isMobile</code>, <code>RendererType</code>, <code>FederatedPointerEvent</code>.</p><p><strong>Layer 1 — Algorithm tests</strong>: No PIXI mock needed. Pure functions.</p><p><strong>Layer 2 — Manager and component logic tests</strong>: Lightweight stubs for Container, Sprite, Graphics, Text. Only mock the PIXI classes each manager/component directly constructs.</p><p><strong>Layer 3 — Application lifecycle tests</strong>: Comprehensive mock including <code>Application.init()</code>, <code>Assets.add()</code>, <code>RenderTexture.create()</code>, renderer type detection, ticker management.</p><h3 id="_5-2-valtio" tabindex="-1">5.2 Valtio <a class="header-anchor" href="#_5-2-valtio" aria-label="Permalink to &quot;5.2 Valtio&quot;"></a></h3><p>Use real Valtio (<code>valtio/vanilla</code>) — it runs in Node.js without DOM. <code>subscribeKey</code> fires synchronously, making assertions straightforward:</p><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> runtime</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> proxy</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ showPath: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> manager</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> PathManager</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">mockAppService</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(runtime))</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">runtime.showPath </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> false</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">expect</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(manager.path.visible).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">toBe</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span></code></pre></div><h3 id="_5-3-logger" tabindex="-1">5.3 Logger <a class="header-anchor" href="#_5-3-logger" aria-label="Permalink to &quot;5.3 Logger&quot;"></a></h3><p>Mock globally in <code>test/setup.ts</code> to suppress output and optionally assert log calls:</p><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">vi.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">mock</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;@core/utils/logger&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  Logger: { log: vi.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), debug: vi.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), warn: vi.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), error: vi.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}))</span></span></code></pre></div><h3 id="_5-4-ray-js-robot-protocol" tabindex="-1">5.4 @ray-js/robot-protocol <a class="header-anchor" href="#_5-4-ray-js-robot-protocol" aria-label="Permalink to &quot;5.4 @ray-js/robot-protocol&quot;"></a></h3><p>Two strategies depending on test type:</p><ul><li><strong>Unit tests</strong>: Mock <code>decodeMap</code>/<code>decodeMapStructured</code> to return factory-built test data</li><li><strong>Integration tests</strong>: Use real decode functions with hex fixture data for end-to-end validation</li></ul><h3 id="_5-5-browser-apis" tabindex="-1">5.5 Browser APIs <a class="header-anchor" href="#_5-5-browser-apis" aria-label="Permalink to &quot;5.5 Browser APIs&quot;"></a></h3><p><code>browser.ts</code> uses <code>navigator.userAgent</code> and <code>navigator.deviceMemory</code>. Options:</p><ul><li>Use <code>vi.stubGlobal(&#39;navigator&#39;, {...})</code> for targeted tests</li><li>Or configure Vitest <code>environment: &#39;jsdom&#39;</code> for specific test files via <code>// @vitest-environment jsdom</code> comment</li></ul><hr><h2 id="_6-coverage-strategy" tabindex="-1">6. Coverage Strategy <a class="header-anchor" href="#_6-coverage-strategy" aria-label="Permalink to &quot;6. Coverage Strategy&quot;"></a></h2><h3 id="_6-1-ratchet-model" tabindex="-1">6.1 Ratchet Model <a class="header-anchor" href="#_6-1-ratchet-model" aria-label="Permalink to &quot;6.1 Ratchet Model&quot;"></a></h3><p>Coverage thresholds follow a <strong>ratchet</strong> (only-up) model instead of a fixed target:</p><ul><li><strong>Initial thresholds</strong> set after Phase 2 completion based on actual coverage</li><li><strong>Ratchet rule</strong>: After each release, update thresholds to <code>max(current_threshold, actual_coverage - 2%)</code></li><li>Coverage can only go up, never down. The repository now enforces a non-zero baseline and should continue ratcheting upward per release.</li></ul><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Example progression:</span></span>
-<span class="line"><span>  v0.0.10: actual 52% → threshold stays 50%</span></span>
-<span class="line"><span>  v0.0.11: actual 61% → threshold raised to 59%</span></span>
-<span class="line"><span>  v0.0.12: actual 68% → threshold raised to 66%</span></span></code></pre></div><h3 id="_6-2-configuration" tabindex="-1">6.2 Configuration <a class="header-anchor" href="#_6-2-configuration" aria-label="Permalink to &quot;6.2 Configuration&quot;"></a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">coverage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  provider</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;v8&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  reporter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;text&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;lcov&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  include</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;src/core/**/*.ts&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],   </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Vitest 4.x removed \`all\` option; include controls scope</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  exclude</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &#39;src/core/@types/**&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,         </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Pure type definitions</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &#39;src/core/constant/**&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,       </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Static constants</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &#39;src/app/**&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,                 </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Demo app</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &#39;src/rjs-entry/**&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,           </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Entry wrapper</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &#39;**/*.test.ts&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,               </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Test files themselves</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  thresholds</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    lines</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">85</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,                    </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Current enforced baseline</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    functions</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">85</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    branches</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">70</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    statements</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">85</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="_6-3-ratchet-update-process" tabindex="-1">6.3 Ratchet Update Process <a class="header-anchor" href="#_6-3-ratchet-update-process" aria-label="Permalink to &quot;6.3 Ratchet Update Process&quot;"></a></h3><p>After each release:</p><ol><li>Run <code>npm run test:coverage</code></li><li>Read actual coverage numbers from output</li><li>For each metric: <code>new_threshold = max(current_threshold, actual - 2)</code></li><li>Update <code>vitest.config.ts</code> thresholds</li><li>Commit as part of release prep</li></ol><hr><h2 id="_7-phased-rollout" tabindex="-1">7. Phased Rollout <a class="header-anchor" href="#_7-phased-rollout" aria-label="Permalink to &quot;7. Phased Rollout&quot;"></a></h2><h3 id="phase-1-infrastructure-this-task" tabindex="-1">Phase 1: Infrastructure (This Task) <a class="header-anchor" href="#phase-1-infrastructure-this-task" aria-label="Permalink to &quot;Phase 1: Infrastructure (This Task)&quot;"></a></h3><p><strong>Goal</strong>: First test passes, CI-ready framework.</p><p><strong>Deliverables</strong>:</p><ul><li><code>vitest.config.ts</code> with path alias resolution, setup file, coverage config</li><li><code>test/setup.ts</code> with PIXI global mock, Logger mock</li><li><code>test/mocks/pixi.ts</code> — Layer 1-2 PIXI stubs</li><li><code>test/factories/</code> — mapData, pathData, config, runtime builders</li><li>npm scripts: <code>test</code>, <code>test:watch</code>, <code>test:coverage</code></li><li>1 smoke test proving the setup works (e.g., algorithm utility test)</li></ul><p><strong>Verification</strong>: <code>npm test</code> passes, <code>npx tsc --noEmit</code> passes, <code>npm run lint</code> passes.</p><h3 id="phase-2-algorithm-tests-highest-roi" tabindex="-1">Phase 2: Algorithm Tests (Highest ROI) <a class="header-anchor" href="#phase-2-algorithm-tests-highest-roi" aria-label="Permalink to &quot;Phase 2: Algorithm Tests (Highest ROI)&quot;"></a></h3><p><strong>Goal</strong>: Cover core computational functions — 0 mocking required.</p><table tabindex="0"><thead><tr><th>File</th><th>Functions</th><th>Test Focus</th></tr></thead><tbody><tr><td><code>utils/algorithm.ts</code></td><td>38 exported</td><td>Point-in-polygon, four-color greedy, Bresenham, room adjacency, boundary calculation, binary search, vector operations</td></tr><tr><td><code>utils/index.ts</code></td><td>~10 exported</td><td>Coordinate conversion, precision fixing, easing functions, room property decode</td></tr></tbody></table><p><strong>Estimated</strong>: 5-6 test files, 80+ test cases.</p><h3 id="phase-3-manager-logic-tests" tabindex="-1">Phase 3: Manager Logic Tests <a class="header-anchor" href="#phase-3-manager-logic-tests" aria-label="Permalink to &quot;Phase 3: Manager Logic Tests&quot;"></a></h3><p><strong>Goal</strong>: Cover data processing and state reaction logic in managers.</p><table tabindex="0"><thead><tr><th>Manager</th><th>LOC</th><th>Test Focus</th></tr></thead><tbody><tr><td>MapManager</td><td>1,489</td><td>Room detection flow, caching, structured vs raster processing</td></tr><tr><td>ControlsManager</td><td>1,010</td><td>Control lifecycle (add/update/remove), state sync</td></tr><tr><td>PathManager</td><td>212</td><td>Incremental vs full draw decision, path dedup</td></tr><tr><td>RoomManager</td><td>463</td><td>Valtio subscription reactions, visibility toggling</td></tr></tbody></table><p><strong>Estimated</strong>: 4-6 test files, 60+ test cases.</p><h3 id="phase-4-component-tests" tabindex="-1">Phase 4: Component Tests <a class="header-anchor" href="#phase-4-component-tests" aria-label="Permalink to &quot;Phase 4: Component Tests&quot;"></a></h3><p><strong>Goal</strong>: Cover visual PIXI.js component logic — construction, property updates, destroy cleanup.</p><p>Components use PIXI APIs (Container, Sprite, Graphics, Text) but their <strong>data logic</strong> (coordinate transforms, visibility toggling, property updates) can be unit-tested with Layer 2 PIXI mocks.</p><table tabindex="0"><thead><tr><th>Component Category</th><th>Examples</th><th>Test Focus</th></tr></thead><tbody><tr><td>Core entities</td><td>Robot, ChargingStation</td><td>Position/rotation updates, icon switching</td></tr><tr><td>Map overlays</td><td>Path, Heatmap, VirtualWall</td><td>Data-driven rendering, point processing</td></tr><tr><td>Room visuals</td><td>RoomInfo, RoomLabel</td><td>Room property display, color/label updates</td></tr><tr><td>Interactive controls</td><td>ForbiddenZone, Carpet, Mop</td><td>Resize/move/rotate state, boundary validation</td></tr></tbody></table><p><strong>Estimated</strong>: 6-10 test files, 60+ test cases.</p><h3 id="phase-5-application-layer" tabindex="-1">Phase 5: Application Layer <a class="header-anchor" href="#phase-5-application-layer" aria-label="Permalink to &quot;Phase 5: Application Layer&quot;"></a></h3><p><strong>Goal</strong>: Cover MapApplication lifecycle and cross-component integration.</p><table tabindex="0"><thead><tr><th>Module</th><th>Test Focus</th></tr></thead><tbody><tr><td>MapApplication</td><td><code>initialize()</code> → <code>drawMap()</code> → <code>clear()</code> lifecycle, config merge</td></tr><tr><td>AppService</td><td>Unit conversions, getter correctness</td></tr><tr><td>Interaction</td><td>Gesture state machine (pinch/pan/tap), animation easing</td></tr></tbody></table><p><strong>Estimated</strong>: 3-4 test files, 40+ test cases.</p><h3 id="phase-6-hardening" tabindex="-1">Phase 6: Hardening <a class="header-anchor" href="#phase-6-hardening" aria-label="Permalink to &quot;Phase 6: Hardening&quot;"></a></h3><ul><li>Ratchet coverage thresholds based on actual numbers (see Section 6.3)</li><li>Visual regression testing consideration (PIXI screenshot comparison)</li><li>CI pipeline integration: <code>lint</code> → <code>tsc --noEmit</code> → <code>vitest run</code> → <code>build</code></li><li>Edge case and regression test additions</li></ul><hr><h2 id="_8-npm-scripts" tabindex="-1">8. npm Scripts <a class="header-anchor" href="#_8-npm-scripts" aria-label="Permalink to &quot;8. npm Scripts&quot;"></a></h2><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;test&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;vitest run&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;test:watch&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;vitest&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;test:coverage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;vitest run --coverage&quot;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><hr><h2 id="_9-scope-exclusions" tabindex="-1">9. Scope Exclusions <a class="header-anchor" href="#_9-scope-exclusions" aria-label="Permalink to &quot;9. Scope Exclusions&quot;"></a></h2><table tabindex="0"><thead><tr><th>Excluded</th><th>Reason</th></tr></thead><tbody><tr><td>MCP server tests</td><td>Separate initiative, not in this plan</td></tr><tr><td>Demo app (<code>src/app/</code>) tests</td><td>Not distributed code</td></tr><tr><td>E2E / browser tests</td><td>Requires Playwright or similar, separate effort</td></tr></tbody></table><hr><h2 id="_10-execution-model-—-sub-agent-parallel-dispatch" tabindex="-1">10. Execution Model — Sub Agent Parallel Dispatch <a class="header-anchor" href="#_10-execution-model-—-sub-agent-parallel-dispatch" aria-label="Permalink to &quot;10. Execution Model — Sub Agent Parallel Dispatch&quot;"></a></h2><p>Each phase of test writing uses a <strong>main agent + sub agent</strong> parallel execution pattern:</p><h3 id="_10-1-workflow" tabindex="-1">10.1 Workflow <a class="header-anchor" href="#_10-1-workflow" aria-label="Permalink to &quot;10.1 Workflow&quot;"></a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Main Agent</span></span>
-<span class="line"><span>  │</span></span>
-<span class="line"><span>  ├── 1. Review phase scope and divide into independent tasks</span></span>
-<span class="line"><span>  │</span></span>
-<span class="line"><span>  ├── 2. Dispatch sub agents in parallel (one per module/file)</span></span>
-<span class="line"><span>  │      ├── Sub Agent A: algorithm.test.ts (geometry functions)</span></span>
-<span class="line"><span>  │      ├── Sub Agent B: algorithm.test.ts (room adjacency/coloring)</span></span>
-<span class="line"><span>  │      ├── Sub Agent C: AppService.test.ts</span></span>
-<span class="line"><span>  │      └── Sub Agent D: MapManager.test.ts</span></span>
-<span class="line"><span>  │</span></span>
-<span class="line"><span>  ├── 3. Collect results from all sub agents</span></span>
-<span class="line"><span>  │</span></span>
-<span class="line"><span>  ├── 4. Verify all outputs:</span></span>
-<span class="line"><span>  │      ├── npx tsc --noEmit        (type check)</span></span>
-<span class="line"><span>  │      ├── npm run lint             (code style)</span></span>
-<span class="line"><span>  │      └── npm test                 (vitest run)</span></span>
-<span class="line"><span>  │</span></span>
-<span class="line"><span>  ├── 5. Fix any issues found in verification</span></span>
-<span class="line"><span>  │</span></span>
-<span class="line"><span>  └── 6. Output test report summary</span></span></code></pre></div><h3 id="_10-2-sub-agent-task-division-principles" tabindex="-1">10.2 Sub Agent Task Division Principles <a class="header-anchor" href="#_10-2-sub-agent-task-division-principles" aria-label="Permalink to &quot;10.2 Sub Agent Task Division Principles&quot;"></a></h3><ul><li>Each sub agent receives <strong>one module or one test file</strong> as its scope</li><li>Sub agents work in <strong>isolation</strong> — no shared mutable state between tasks</li><li>Main agent provides each sub agent with: <ul><li>Target source file path and its content context</li><li>Shared test infrastructure (mock locations, factory imports)</li><li>Coding standards (single quotes, no semicolons, 2-space indent)</li></ul></li><li>Sub agents are free to use any tools needed (Read, Write, Grep, etc.)</li></ul><h3 id="_10-3-main-agent-verification-checklist" tabindex="-1">10.3 Main Agent Verification Checklist <a class="header-anchor" href="#_10-3-main-agent-verification-checklist" aria-label="Permalink to &quot;10.3 Main Agent Verification Checklist&quot;"></a></h3><p>After all sub agents complete, main agent runs sequentially:</p><ol><li><code>npx tsc --noEmit</code> — all test files must type-check</li><li><code>npm run lint</code> — all test files must pass ESLint + Prettier</li><li><code>npm test</code> — all tests must pass</li><li><code>npm run test:coverage</code> — coverage must meet thresholds</li><li>Produce a summary report including: <ul><li>Total test files created</li><li>Total test cases (passed / failed / skipped)</li><li>Coverage numbers per module</li><li>Any issues encountered and how they were resolved</li></ul></li></ol><hr><h2 id="_11-risks-and-mitigations" tabindex="-1">11. Risks and Mitigations <a class="header-anchor" href="#_11-risks-and-mitigations" aria-label="Permalink to &quot;11. Risks and Mitigations&quot;"></a></h2><table tabindex="0"><thead><tr><th>Risk</th><th>Impact</th><th>Mitigation</th></tr></thead><tbody><tr><td>PIXI mock maintenance burden</td><td>High</td><td>Layer mocks by test type; only mock what each test needs</td></tr><tr><td><code>@ray-js/robot-protocol</code> internal changes</td><td>Medium</td><td>Pin version, use type-safe factory builders</td></tr><tr><td>Valtio subscription timing</td><td>Low</td><td>Verified synchronous; add explicit <code>await</code> if async needed</td></tr><tr><td><code>browser.ts</code> browser API dependency</td><td>Low</td><td>Use <code>vi.stubGlobal()</code> or per-file jsdom environment</td></tr><tr><td>Test-induced PIXI global state leaks</td><td>Medium</td><td><code>pool: &quot;forks&quot;</code> ensures process isolation</td></tr></tbody></table>`,100)])])}const u=e(n,[["render",o]]);export{g as __pageData,u as default};

package/dist-docs/assets/records_plans_2026-03-05-testing-infrastructure-design.md.DLHGz5Ez.lean.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as e,c as t,o as a,aq as i}from"./chunks/framework.CBLqO2Q1.js";const g=JSON.parse('{"title":"Testing Infrastructure Design — robot-map-sdk","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-05-testing-infrastructure-design.md","filePath":"records/plans/2026-03-05-testing-infrastructure-design.md","lastUpdated":1773653672000}'),n={name:"records/plans/2026-03-05-testing-infrastructure-design.md"};function o(r,s,l,p,d,c){return a(),t("div",null,[...s[0]||(s[0]=[i("",100)])])}const u=e(n,[["render",o]]);export{g as __pageData,u as default};

package/dist-docs/assets/records_plans_2026-03-10-simulator-events-console-plan.md.CfHLEHcc.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as o,c as a,o as i,aq as l}from"./chunks/framework.CBLqO2Q1.js";const u=JSON.parse('{"title":"Simulator events console plan","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-10-simulator-events-console-plan.md","filePath":"records/plans/2026-03-10-simulator-events-console-plan.md","lastUpdated":1773138773000}'),t={name:"records/plans/2026-03-10-simulator-events-console-plan.md"};function s(n,e,c,r,d,p){return i(),a("div",null,[...e[0]||(e[0]=[l('<h1 id="simulator-events-console-plan" tabindex="-1">Simulator events console plan <a class="header-anchor" href="#simulator-events-console-plan" aria-label="Permalink to "Simulator events console plan""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>The simulator page already helps developers validate source data input and runtime configuration, but it does not expose SDK callback activity. Developers can interact with the map yet still need custom code to inspect which callbacks fire and what payloads they receive.</p><h2 id="goal-and-scope" tabindex="-1">Goal and scope <a class="header-anchor" href="#goal-and-scope" aria-label="Permalink to "Goal and scope""></a></h2><p>This iteration adds a developer-facing <code>Events</code> console to the simulator.</p><p>In scope:</p><ul><li>record SDK public callbacks only</li><li>start with <code>onClickRoom</code> and <code>onClickRoomProperties</code></li><li>show callback names, times, summaries, and expandable JSON payloads</li><li>add pause, clear, copy, and filter actions</li><li>place the console near the map preview</li><li>introduce <code>reka-ui</code> as a lightweight primitive layer for new overlays and collapsible UI</li></ul><p>Out of scope:</p><ul><li>logging simulator-internal actions</li><li>toast notifications for each callback</li><li>a generic SDK logging framework</li><li>a full migration of simulator controls to <code>reka-ui</code></li></ul><h2 id="chosen-approach" tabindex="-1">Chosen approach <a class="header-anchor" href="#chosen-approach" aria-label="Permalink to "Chosen approach""></a></h2><p>Use a dedicated <code>Events</code> console placed with the map preview. Record events by wrapping the SDK <code>MapCallbacks</code> passed into the map instance. Persist only a bounded in-memory event list, with lightweight helpers for summaries, filtering, and JSON export.</p><p>Introduce <code>reka-ui</code> only for the new interaction primitives that need stronger accessibility and structure, such as collapsible payload details and event filter controls.</p><h2 id="impacted-files-or-modules" tabindex="-1">Impacted files or modules <a class="header-anchor" href="#impacted-files-or-modules" aria-label="Permalink to "Impacted files or modules""></a></h2><p>Expected implementation targets:</p><ul><li><code>docs/.vitepress/theme/components/MapPlayground.vue</code></li><li><code>docs/.vitepress/theme/components/simulator/useMapPlayground.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/useMapCanvas.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/usePlaygroundRender.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/types.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/sdkTypes.ts</code></li><li>new event composables under <code>docs/.vitepress/theme/components/simulator/</code></li><li>new event UI components under <code>docs/.vitepress/theme/components/simulator/</code></li><li><code>package.json</code> and lockfile for the new UI primitive dependency</li></ul><h2 id="verification-checklist" tabindex="-1">Verification checklist <a class="header-anchor" href="#verification-checklist" aria-label="Permalink to "Verification checklist""></a></h2><ul><li>[ ] Clicking a room appends an <code>onClickRoom</code> record.</li><li>[ ] Clicking a room property appends an <code>onClickRoomProperties</code> record.</li><li>[ ] Event rows show exact callback names and readable summaries.</li><li>[ ] Pause stops new records without clearing the list.</li><li>[ ] Clear resets only the event log.</li><li>[ ] Copy exports valid JSON.</li><li>[ ] The event list is bounded to the latest <code>100</code> entries.</li><li>[ ] <code>npm run lint</code> passes.</li><li>[ ] <code>npx tsc --noEmit</code> passes.</li><li>[ ] <code>npm run docs:build</code> passes.</li></ul>',17)])])}const h=o(t,[["render",s]]);export{u as __pageData,h as default};

package/dist-docs/assets/records_plans_2026-03-10-simulator-events-console-plan.md.CfHLEHcc.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-10-simulator-last-successful-combo-cache-plan.md.Z2RoK239.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as a,c as o,o as l,aq as s}from"./chunks/framework.CBLqO2Q1.js";const h=JSON.parse('{"title":"Simulator Last Successful Combo Cache Plan","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-10-simulator-last-successful-combo-cache-plan.md","filePath":"records/plans/2026-03-10-simulator-last-successful-combo-cache-plan.md","lastUpdated":1773123455000}'),c={name:"records/plans/2026-03-10-simulator-last-successful-combo-cache-plan.md"};function i(t,e,r,n,d,u){return l(),o("div",null,[...e[0]||(e[0]=[s('<h1 id="simulator-last-successful-combo-cache-plan" tabindex="-1">Simulator Last Successful Combo Cache Plan <a class="header-anchor" href="#simulator-last-successful-combo-cache-plan" aria-label="Permalink to "Simulator Last Successful Combo Cache Plan""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>The simulator page allows developers to paste <code>mapHex</code>, optional <code>pathHex</code>, and optional <code>roomProperties</code> for real-time rendering. Refreshing the page currently risks losing in-progress data.</p><h2 id="goal-and-scope" tabindex="-1">Goal And Scope <a class="header-anchor" href="#goal-and-scope" aria-label="Permalink to "Goal And Scope""></a></h2><p>Persist the last successfully rendered combination locally so developers can refresh and continue without data loss.</p><p>In scope:</p><ul><li>Save input combo after successful render.</li><li>Restore input combo on page load.</li><li>Fallback to built-in demo defaults when no cache hit exists.</li><li>Provide an explicit cache clear action.</li></ul><p>Out of scope:</p><ul><li>Cross-device sync.</li><li>Server-side persistence.</li><li>IndexedDB migration.</li></ul><h2 id="chosen-approach" tabindex="-1">Chosen Approach <a class="header-anchor" href="#chosen-approach" aria-label="Permalink to "Chosen Approach""></a></h2><ul><li>Use browser <code>localStorage</code> with key <code>rayRobotMap:simulator:lastSuccessfulCombo:v1</code>.</li><li>Store payload with version and timestamp: <ul><li><code>mapHex</code></li><li><code>pathHex</code></li><li><code>roomProperties</code></li></ul></li><li>Read and validate cache shape at startup.</li><li>Only persist when full render completes without layer errors.</li><li>Keep render behavior unchanged for optional inputs.</li><li>Add <code>清除缓存</code> action to remove stored combo manually.</li></ul><h2 id="impacted-files-or-modules" tabindex="-1">Impacted Files Or Modules <a class="header-anchor" href="#impacted-files-or-modules" aria-label="Permalink to "Impacted Files Or Modules""></a></h2><ul><li><code>docs/.vitepress/theme/components/MapPlayground.vue</code></li></ul><h2 id="verification-checklist" tabindex="-1">Verification Checklist <a class="header-anchor" href="#verification-checklist" aria-label="Permalink to "Verification Checklist""></a></h2><ul><li><code>npm run lint</code> passes (project lint scope currently covers <code>src</code> only).</li><li><code>npm run docs:build</code> passes.</li><li><code>npx tsc --noEmit</code> still fails due existing unrelated test typing issues in <code>test/core/application/Interaction.test.ts</code>.</li></ul>',15)])])}const m=a(c,[["render",i]]);export{h as __pageData,m as default};

package/dist-docs/assets/records_plans_2026-03-10-simulator-last-successful-combo-cache-plan.md.Z2RoK239.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-10-simulator-map-parsed-view-plan.md.S9jPz75o.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as a,c as r,o as i,aq as o}from"./chunks/framework.CBLqO2Q1.js";const m=JSON.parse('{"title":"Simulator map parsed view plan (March 10, 2026)","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-10-simulator-map-parsed-view-plan.md","filePath":"records/plans/2026-03-10-simulator-map-parsed-view-plan.md","lastUpdated":1773123455000}'),l={name:"records/plans/2026-03-10-simulator-map-parsed-view-plan.md"};function t(d,e,s,n,c,p){return i(),r("div",null,[...e[0]||(e[0]=[o('<h1 id="simulator-map-parsed-view-plan-march-10-2026" tabindex="-1">Simulator map parsed view plan (March 10, 2026) <a class="header-anchor" href="#simulator-map-parsed-view-plan-march-10-2026" aria-label="Permalink to "Simulator map parsed view plan (March 10, 2026)""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>The simulator currently visualizes only the rendered map. Developers also need an inspectable parsed-data view to compare raw <code>mapHex</code> input with decoded map structure during debugging.</p><h2 id="goal-and-scope" tabindex="-1">Goal and scope <a class="header-anchor" href="#goal-and-scope" aria-label="Permalink to "Goal and scope""></a></h2><p>Add a parsed map data panel in the simulator that:</p><ul><li>Shows map parse summary fields for quick verification.</li><li>Supports on-demand tree inspection for large decoded objects.</li><li>Keeps the main map rendering workflow unchanged.</li></ul><p>Out of scope:</p><ul><li>Path parsed-view panel.</li><li>Diff view between raw hex and parsed JSON.</li></ul><h2 id="chosen-approach" tabindex="-1">Chosen approach <a class="header-anchor" href="#chosen-approach" aria-label="Permalink to "Chosen approach""></a></h2><p>Use <code>json-editor-vue</code> in read-only tree mode and render it lazily behind a "展开详情" toggle. Keep summary cards visible by default and load the full tree only when requested.</p><h2 id="impacted-files-and-modules" tabindex="-1">Impacted files and modules <a class="header-anchor" href="#impacted-files-and-modules" aria-label="Permalink to "Impacted files and modules""></a></h2><ul><li><code>package.json</code></li><li><code>yarn.lock</code></li><li><code>docs/.vitepress/theme/components/MapPlayground.vue</code></li></ul><h2 id="verification-checklist" tabindex="-1">Verification checklist <a class="header-anchor" href="#verification-checklist" aria-label="Permalink to "Verification checklist""></a></h2><ul><li>[ ] Structured map parse result appears in summary panel.</li><li>[ ] Tree viewer expands and collapses without blocking map interaction.</li><li>[ ] Copy JSON action works in secure browser context.</li><li>[ ] <code>npm run lint</code> passes.</li><li>[ ] <code>npm run docs:build</code> passes.</li><li>[ ] <code>npx tsc --noEmit</code> status is recorded.</li></ul>',14)])])}const h=a(l,[["render",t]]);export{m as __pageData,h as default};

package/dist-docs/assets/records_plans_2026-03-10-simulator-map-parsed-view-plan.md.S9jPz75o.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-10-simulator-map-playground-refactor-plan.md.BuILlmcV.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as o,c as a,o as t,aq as i}from"./chunks/framework.CBLqO2Q1.js";const m=JSON.parse('{"title":"Simulator MapPlayground Refactor Plan","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-10-simulator-map-playground-refactor-plan.md","filePath":"records/plans/2026-03-10-simulator-map-playground-refactor-plan.md","lastUpdated":1773127806000}'),l={name:"records/plans/2026-03-10-simulator-map-playground-refactor-plan.md"};function s(r,e,c,n,d,p){return t(),a("div",null,[...e[0]||(e[0]=[i('<h1 id="simulator-mapplayground-refactor-plan" tabindex="-1">Simulator MapPlayground Refactor Plan <a class="header-anchor" href="#simulator-mapplayground-refactor-plan" aria-label="Permalink to "Simulator MapPlayground Refactor Plan""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p><code>MapPlayground.vue</code> had accumulated page composition, rendering lifecycle, cache persistence, and editor modal logic in one file, making iterative changes costly.</p><h2 id="goal-and-scope" tabindex="-1">Goal And Scope <a class="header-anchor" href="#goal-and-scope" aria-label="Permalink to "Goal And Scope""></a></h2><p>Refactor to align with Vue 3 composition practices while preserving behavior and UI.</p><p>In scope:</p><ul><li>Move simulator state and business logic into a composable.</li><li>Move fullscreen editor modal into a standalone component.</li><li>Keep existing render behavior, cache behavior, and interactions unchanged.</li></ul><p>Out of scope:</p><ul><li>Functional redesign.</li><li>New features.</li></ul><h2 id="chosen-approach" tabindex="-1">Chosen Approach <a class="header-anchor" href="#chosen-approach" aria-label="Permalink to "Chosen Approach""></a></h2><ul><li>Reduced <code>MapPlayground.vue</code> to a page-level composition shell.</li><li>Split rendering state and pipeline into <code>usePlaygroundRender.ts</code>.</li><li>Kept page interaction state in <code>useMapPlayground.ts</code>.</li><li>Extracted cache, summaries, default room demo generation, auto-render debounce, and map canvas lifecycle into focused utility modules.</li><li>Extracted preview, tabs, input field, parsed panel, action bar, and editor dialog into standalone UI components.</li></ul><h2 id="impacted-files-or-modules" tabindex="-1">Impacted Files Or Modules <a class="header-anchor" href="#impacted-files-or-modules" aria-label="Permalink to "Impacted Files Or Modules""></a></h2><ul><li><code>docs/.vitepress/theme/components/MapPlayground.vue</code></li><li><code>docs/.vitepress/theme/components/simulator/SimulatorActionBar.vue</code></li><li><code>docs/.vitepress/theme/components/simulator/useMapPlayground.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/SimulatorEditorDialog.vue</code></li><li><code>docs/.vitepress/theme/components/simulator/SimulatorInputField.vue</code></li><li><code>docs/.vitepress/theme/components/simulator/SimulatorParsedPanel.vue</code></li><li><code>docs/.vitepress/theme/components/simulator/SimulatorPreviewPanel.vue</code></li><li><code>docs/.vitepress/theme/components/simulator/SimulatorTabs.vue</code></li><li><code>docs/.vitepress/theme/components/simulator/cache.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/constants.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/defaultRoomProperties.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/summaries.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/types.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/useAutoRender.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/useMapCanvas.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/usePlaygroundRender.ts</code></li></ul><h2 id="verification-checklist" tabindex="-1">Verification Checklist <a class="header-anchor" href="#verification-checklist" aria-label="Permalink to "Verification Checklist""></a></h2><ul><li><code>npm run lint</code> passes.</li><li><code>npx tsc --noEmit</code> passes.</li><li><code>npm run docs:build</code> passes.</li></ul>',15)])])}const h=o(l,[["render",s]]);export{m as __pageData,h as default};

package/dist-docs/assets/records_plans_2026-03-10-simulator-map-playground-refactor-plan.md.BuILlmcV.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-10-simulator-playground-plan.md.CQAR-T7p.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as a,c as o,o as i,aq as l}from"./chunks/framework.CBLqO2Q1.js";const h=JSON.parse('{"title":"Simulator playground plan (March 10, 2026)","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-10-simulator-playground-plan.md","filePath":"records/plans/2026-03-10-simulator-playground-plan.md","lastUpdated":1773123455000}'),t={name:"records/plans/2026-03-10-simulator-playground-plan.md"};function r(d,e,n,s,c,p){return i(),o("div",null,[...e[0]||(e[0]=[l('<h1 id="simulator-playground-plan-march-10-2026" tabindex="-1">Simulator playground plan (March 10, 2026) <a class="header-anchor" href="#simulator-playground-plan-march-10-2026" aria-label="Permalink to "Simulator playground plan (March 10, 2026)""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>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.</p><h2 id="goal-and-scope" tabindex="-1">Goal and scope <a class="header-anchor" href="#goal-and-scope" aria-label="Permalink to "Goal and scope""></a></h2><p>Add a new documentation section named <code>simulator</code> with a browser-only playground that:</p><ul><li>Accepts <code>mapHex</code> as required input.</li><li>Accepts optional <code>pathHex</code> and optional <code>roomProperties</code> JSON.</li><li>Renders the map in real time after an explicit action.</li><li>Uses a clean and minimal UI suited for long payload input.</li></ul><p>Out of scope:</p><ul><li>Sharing logic with <code>src/app/debugTools</code>.</li><li>Heatmap and other advanced layers in this first version.</li></ul><h2 id="chosen-approach" tabindex="-1">Chosen approach <a class="header-anchor" href="#chosen-approach" aria-label="Permalink to "Chosen approach""></a></h2><p>Implement a standalone VitePress component (<code>MapPlayground.vue</code>) and register it globally in the VitePress theme. The component owns parsing, rendering, error display, and long-text editing mode.</p><p>Parsing rule:</p><ul><li>If normalized <code>mapHex</code> starts with <code>7b22</code>, treat it as structured map data.</li><li>Otherwise, treat it as raster map data.</li></ul><h2 id="impacted-files-and-modules" tabindex="-1">Impacted files and modules <a class="header-anchor" href="#impacted-files-and-modules" aria-label="Permalink to "Impacted files and modules""></a></h2><ul><li><code>docs/.vitepress/config.ts</code></li><li><code>docs/.vitepress/theme/index.ts</code></li><li><code>docs/.vitepress/theme/components/MapPlayground.vue</code></li><li><code>docs/simulator/index.md</code></li></ul><h2 id="verification-checklist" tabindex="-1">Verification checklist <a class="header-anchor" href="#verification-checklist" aria-label="Permalink to "Verification checklist""></a></h2><ul><li>[ ] Navigation includes <code>模拟调试</code> and routes to <code>/simulator/</code>.</li><li>[ ] <code>mapHex</code> is required and has default sample data.</li><li>[ ] <code>pathHex</code> and <code>roomProperties</code> are optional.</li><li>[ ] Structured/raster branch follows the <code>7b22</code> rule.</li><li>[ ] Long inputs can be edited in full-screen mode.</li><li>[ ] Errors are scoped to each optional field when possible.</li><li>[ ] <code>npm run lint</code> passes.</li><li>[ ] <code>npx tsc --noEmit</code> passes.</li></ul>',16)])])}const m=a(t,[["render",r]]);export{h as __pageData,m as default};

package/dist-docs/assets/records_plans_2026-03-10-simulator-playground-plan.md.CQAR-T7p.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-10-simulator-runtime-controls-plan.md.DSVD-qCa.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as o,c as t,o as a,aq as i}from"./chunks/framework.CBLqO2Q1.js";const m=JSON.parse('{"title":"Simulator runtime controls plan","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-10-simulator-runtime-controls-plan.md","filePath":"records/plans/2026-03-10-simulator-runtime-controls-plan.md","lastUpdated":1773145284000}'),l={name:"records/plans/2026-03-10-simulator-runtime-controls-plan.md"};function r(s,e,n,d,c,p){return a(),t("div",null,[...e[0]||(e[0]=[i('<h1 id="simulator-runtime-controls-plan" tabindex="-1">Simulator runtime controls plan <a class="header-anchor" href="#simulator-runtime-controls-plan" aria-label="Permalink to "Simulator runtime controls plan""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>The simulator page already supports source-data debugging for <code>mapHex</code>, <code>pathHex</code>, and <code>roomProperties</code>, but it does not expose the SDK <code>runtime</code> surface. Developers cannot validate runtime-only behavior such as room selection, visibility toggles, or interaction gates from the docs UI.</p><h2 id="goal-and-scope" tabindex="-1">Goal and scope <a class="header-anchor" href="#goal-and-scope" aria-label="Permalink to "Goal and scope""></a></h2><p>This iteration adds a runtime control console to the simulator page.</p><p>In scope:</p><ul><li>cover every <code>RuntimeConfig</code> field in the docs UI</li><li>group fields by behavior and dependency</li><li>keep unsupported fields visible but disabled</li><li>support bidirectional room selection between controls and map clicks</li><li>update runtime incrementally through <code>mapApi.updateRuntime()</code></li></ul><p>Out of scope:</p><ul><li>full editing workflows for zones, carpets, furniture, spots, or waypoints</li><li>persistence of runtime state across page reloads</li><li>raw JSON runtime editing as the primary input mode</li></ul><h2 id="chosen-approach" tabindex="-1">Chosen approach <a class="header-anchor" href="#chosen-approach" aria-label="Permalink to "Chosen approach""></a></h2><p>Use a dedicated runtime console in the left control column, separate from the existing source-data tabs. Model simulator state in three layers:</p><ul><li>source data state for <code>mapHex</code>, <code>pathHex</code>, and <code>roomProperties</code></li><li>derived map state for rooms and runtime support</li><li>runtime draft state for live incremental updates</li></ul><p>Use a dedicated room-selection sub-panel for the only strong map-driven interaction. All runtime updates go through <code>updateRuntime(partial)</code> rather than the full render pipeline.</p><h2 id="impacted-files-or-modules" tabindex="-1">Impacted files or modules <a class="header-anchor" href="#impacted-files-or-modules" aria-label="Permalink to "Impacted files or modules""></a></h2><p>Expected implementation targets:</p><ul><li><code>docs/.vitepress/theme/components/MapPlayground.vue</code></li><li><code>docs/.vitepress/theme/components/simulator/useMapPlayground.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/usePlaygroundRender.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/useMapCanvas.ts</code></li><li><code>docs/.vitepress/theme/components/simulator/types.ts</code></li><li>new runtime composables under <code>docs/.vitepress/theme/components/simulator/</code></li><li>new runtime UI components under <code>docs/.vitepress/theme/components/simulator/</code></li></ul><h2 id="verification-checklist" tabindex="-1">Verification checklist <a class="header-anchor" href="#verification-checklist" aria-label="Permalink to "Verification checklist""></a></h2><ul><li>[x] <code>RuntimeConfig</code> fields are all represented in the simulator UI.</li><li>[x] Runtime changes update the live map without full re-render.</li><li>[x] <code>selectRoomIds</code> stays synchronized between checklist and map clicks.</li><li>[x] Dependency rules disable or normalize invalid child fields.</li><li>[x] Unsupported runtime fields show disabled state with a reason.</li><li>[x] <code>npm run lint</code> passes.</li><li>[x] <code>npx tsc --noEmit</code> passes.</li><li>[x] <code>npm run docs:build</code> passes.</li></ul>',18)])])}const h=o(l,[["render",r]]);export{m as __pageData,h as default};

package/dist-docs/assets/records_plans_2026-03-10-simulator-runtime-controls-plan.md.DSVD-qCa.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-11-docs-cli-ui-polish-plan.md.B8oZt_5R.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as o,c as a,o as i,aq as l}from"./chunks/framework.CBLqO2Q1.js";const u=JSON.parse('{"title":"2026-03-11 docs CLI UI polish plan","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-11-docs-cli-ui-polish-plan.md","filePath":"records/plans/2026-03-11-docs-cli-ui-polish-plan.md","lastUpdated":1773218350000}'),c={name:"records/plans/2026-03-11-docs-cli-ui-polish-plan.md"};function d(t,e,n,r,s,p){return i(),a("div",null,[...e[0]||(e[0]=[l('<h1 id="_2026-03-11-docs-cli-ui-polish-plan" tabindex="-1">2026-03-11 docs CLI UI polish plan <a class="header-anchor" href="#_2026-03-11-docs-cli-ui-polish-plan" aria-label="Permalink to "2026-03-11 docs CLI UI polish plan""></a></h1><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p><code>robot-map-docs</code> previously printed a single plain startup line. The command worked, but the startup UX was minimal and lacked optional browser auto-open.</p><h2 id="goal-and-scope" tabindex="-1">Goal and scope <a class="header-anchor" href="#goal-and-scope" aria-label="Permalink to "Goal and scope""></a></h2><ul><li>Improve startup presentation while keeping command behavior lightweight.</li><li>Add optional browser auto-open without changing default safety.</li><li>Keep implementation limited to the docs server bin script.</li></ul><h2 id="chosen-approach" tabindex="-1">Chosen approach <a class="header-anchor" href="#chosen-approach" aria-label="Permalink to "Chosen approach""></a></h2><ul><li>Add a compact colorized startup banner with key runtime details.</li><li>Introduce CLI flags: <ul><li><code>--open</code> / <code>-o</code></li><li><code>--no-open</code></li><li><code>--quiet</code> / <code>-q</code></li></ul></li><li>Support environment-based open toggle: <ul><li><code>ROBOT_MAP_DOCS_OPEN=1|true</code></li></ul></li><li>Add structured log helpers and better startup error hints (including <code>EADDRINUSE</code> guidance).</li><li>Keep request handling and file serving logic unchanged.</li></ul><h2 id="impacted-files-or-modules" tabindex="-1">Impacted files or modules <a class="header-anchor" href="#impacted-files-or-modules" aria-label="Permalink to "Impacted files or modules""></a></h2><ul><li><code>bin/docs-server.js</code></li><li><code>docs/records/plans/2026-03-11-docs-cli-ui-polish-plan.md</code></li></ul><h2 id="verification-checklist" tabindex="-1">Verification checklist <a class="header-anchor" href="#verification-checklist" aria-label="Permalink to "Verification checklist""></a></h2><ul><li>[x] <code>npm run lint</code></li><li>[x] <code>npx tsc --noEmit</code></li><li>[x] <code>node bin/docs-server.js --help</code> shows the new flags</li></ul>',11)])])}const m=o(c,[["render",d]]);export{u as __pageData,m as default};

package/dist-docs/assets/records_plans_2026-03-11-docs-cli-ui-polish-plan.md.B8oZt_5R.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-11-simulator-logger-dump-plan.md.CkjDCM2N.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as a,c as o,o as i,aq as l}from"./chunks/framework.CBLqO2Q1.js";const m=JSON.parse('{"title":"2026-03-11 simulator logger and diagnostic dump plan","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-11-simulator-logger-dump-plan.md","filePath":"records/plans/2026-03-11-simulator-logger-dump-plan.md","lastUpdated":1773225787000}'),t={name:"records/plans/2026-03-11-simulator-logger-dump-plan.md"};function r(s,e,d,n,c,p){return i(),o("div",null,[...e[0]||(e[0]=[l('<h1 id="_2026-03-11-simulator-logger-and-diagnostic-dump-plan" tabindex="-1">2026-03-11 simulator logger and diagnostic dump plan <a class="header-anchor" href="#_2026-03-11-simulator-logger-and-diagnostic-dump-plan" aria-label="Permalink to "2026-03-11 simulator logger and diagnostic dump plan""></a></h1><p>This record captures the simulator enhancement that adds one-file diagnostic export/import and a header-level logger toggle for immediate debug switching.</p><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-label="Permalink to "Background""></a></h2><p>Developers need a fast way to share reproducible simulator sessions and toggle SDK logs during investigation without restarting docs with custom startup flags.</p><h2 id="goal-and-scope" tabindex="-1">Goal and scope <a class="header-anchor" href="#goal-and-scope" aria-label="Permalink to "Goal and scope""></a></h2><ul><li>Add one-click diagnostic export for <code>mapHex</code>, <code>pathHex</code>, <code>roomProperties</code>, and <code>runtime</code>.</li><li>Add one-click diagnostic import that restores state and re-renders automatically.</li><li>Add a header-level logger toggle and apply changes immediately by rebuilding simulator render state.</li></ul><p>Out of scope:</p><ul><li>Multi-file zip diagnostic packages.</li><li>Persisting derived metadata such as runtime support matrix.</li></ul><h2 id="chosen-approach" tabindex="-1">Chosen approach <a class="header-anchor" href="#chosen-approach" aria-label="Permalink to "Chosen approach""></a></h2><ul><li>Remove logger-specific CLI startup flags from <code>robot-map-docs</code>.</li><li>Keep logger state in simulator UI (<code>default: off</code>) and map it to <code>config.global.enableLogger</code>.</li><li>Re-render map after logger toggle so logger config takes effect immediately.</li><li>Use a versioned single JSON dump (<code>version: 1</code>) as the diagnostic exchange format.</li><li>Validate and normalize imported runtime payload by runtime defaults before applying to the SDK instance.</li></ul><h2 id="impacted-files-or-modules" tabindex="-1">Impacted files or modules <a class="header-anchor" href="#impacted-files-or-modules" aria-label="Permalink to "Impacted files or modules""></a></h2><ul><li><code>bin/docs-server.js</code></li><li><code>src/simulator/types/index.ts</code></li><li><code>src/simulator/core/useRuntimeBindings.ts</code></li><li><code>src/simulator/core/usePlaygroundRender.ts</code></li><li><code>src/simulator/core/useMapPlayground.ts</code></li><li><code>src/simulator/components/SimulatorActionBar.vue</code></li><li><code>src/simulator/components/SimulatorMapPlayground.vue</code></li></ul><h2 id="verification-checklist" tabindex="-1">Verification checklist <a class="header-anchor" href="#verification-checklist" aria-label="Permalink to "Verification checklist""></a></h2><ul><li>[ ] <code>robot-map-docs --open</code> still opens docs correctly.</li><li>[ ] Header logger toggle defaults to OFF on initial load.</li><li>[ ] Toggling logger ON/OFF re-renders the map and updates visual state.</li><li>[ ] Export action downloads a valid <code>.simulator-dump.json</code> file.</li><li>[ ] Import action restores map/path/room/runtime and re-renders successfully.</li><li>[ ] Import flow does not report success when map render fails.</li><li>[ ] <code>npm run lint</code> passes.</li><li>[ ] <code>npx tsc --noEmit</code> passes.</li></ul>',14)])])}const g=a(t,[["render",r]]);export{m as __pageData,g as default};

package/dist-docs/assets/records_plans_2026-03-11-simulator-logger-dump-plan.md.CkjDCM2N.lean.js DELETED Viewed

@@ -1 +0,0 @@

package/dist-docs/assets/records_plans_2026-03-11-simulator-src-migration-implementation.md.FnB5Cx6R.js DELETED Viewed

@@ -1 +0,0 @@

- import{_ as i,c as o,o as t,aq as a}from"./chunks/framework.CBLqO2Q1.js";const p=JSON.parse('{"title":"2026-03-11 simulator src migration implementation record","description":"","frontmatter":{},"headers":[],"relativePath":"records/plans/2026-03-11-simulator-src-migration-implementation.md","filePath":"records/plans/2026-03-11-simulator-src-migration-implementation.md","lastUpdated":1773212341000}'),r={name:"records/plans/2026-03-11-simulator-src-migration-implementation.md"};function s(l,e,d,c,n,u){return t(),o("div",null,[...e[0]||(e[0]=[a('<h1 id="_2026-03-11-simulator-src-migration-implementation-record" tabindex="-1">2026-03-11 simulator src migration implementation record <a class="header-anchor" href="#_2026-03-11-simulator-src-migration-implementation-record" aria-label="Permalink to "2026-03-11 simulator src migration implementation record""></a></h1><p>This record captures the implementation of the simulator source migration from <code>docs/.vitepress/theme/components/simulator</code> to <code>src/simulator</code>, while keeping simulator code out of all SDK runtime build artifacts.</p><h2 id="change-summary" tabindex="-1">Change summary <a class="header-anchor" href="#change-summary" aria-label="Permalink to "Change summary""></a></h2><ul><li>Moved simulator implementation into <code>src/simulator</code> with a structured layout: <code>components/</code>, <code>core/</code>, <code>adapters/</code>, and <code>types/index.ts</code>.</li><li>Replaced docs <code>MapPlayground</code> with a thin host component that only mounts the simulator implementation from <code>src/simulator</code>.</li><li>Removed docs-side simulator implementation files and docs-side simulator type shims.</li><li>Unified simulator type sourcing to <code>@core/@types</code> and <code>@core/@types/callbacks</code> through <code>src/simulator/adapters/sdkTypes.ts</code>.</li><li>Added import guardrails to forbid <code>@simulator</code> imports from runtime modules: <code>src/core/**</code>, <code>src/rjs-entry/**</code>, and <code>src/app/**</code>.</li><li>Added <code>@simulator</code> alias wiring for root Vite/TypeScript and VitePress docs.</li></ul><h2 id="key-files" tabindex="-1">Key files <a class="header-anchor" href="#key-files" aria-label="Permalink to "Key files""></a></h2><ul><li><code>src/simulator/components/SimulatorMapPlayground.vue</code></li><li><code>src/simulator/core/useMapPlayground.ts</code></li><li><code>src/simulator/adapters/external.ts</code></li><li><code>src/simulator/adapters/sdkTypes.ts</code></li><li><code>src/simulator/types/index.ts</code></li><li><code>src/simulator/index.ts</code></li><li><code>docs/.vitepress/theme/components/MapPlayground.vue</code></li><li><code>docs/.vitepress/config.ts</code></li><li><code>docs/.vitepress/tsconfig.json</code></li><li><code>vite.config.js</code></li><li><code>tsconfig.json</code></li><li><code>eslint.config.js</code></li><li><code>package.json</code></li></ul><h2 id="risk-points-and-handling" tabindex="-1">Risk points and handling <a class="header-anchor" href="#risk-points-and-handling" aria-label="Permalink to "Risk points and handling""></a></h2><ul><li>Risk: simulator code accidentally enters SDK/runtime bundles. <ul><li>Handling: added ESLint <code>no-restricted-imports</code> guardrail for runtime folders and verified built outputs by keyword scanning.</li></ul></li><li>Risk: docs typecheck pulls in full core runtime implementation and fails for unrelated reasons. <ul><li>Handling: constrained docs typecheck path mapping to simulator-relevant targets and type-only modules.</li></ul></li><li>Risk: behavior regression during file relocation. <ul><li>Handling: migrated files with no feature changes and preserved existing simulator render/runtime/event/cache logic paths.</li></ul></li></ul><h2 id="verification-results" tabindex="-1">Verification results <a class="header-anchor" href="#verification-results" aria-label="Permalink to "Verification results""></a></h2><ul><li><code>npm run lint</code>: pass</li><li><code>npx tsc --noEmit</code>: pass</li><li><code>npm run typecheck:docs</code>: pass</li><li><code>npm run build:core</code>: pass</li><li><code>npm run build:rjs</code>: pass</li><li><code>npm run build:app</code>: pass</li></ul><h2 id="artifact-exclusion-evidence" tabindex="-1">Artifact exclusion evidence <a class="header-anchor" href="#artifact-exclusion-evidence" aria-label="Permalink to "Artifact exclusion evidence""></a></h2><p>After each build target, outputs were scanned with: <code>rg -n "simulator|SimulatorMapPlayground|@simulator|useMapPlayground|src/simulator"</code>.</p><ul><li><code>build:core</code> output (<code>dist/**</code>): no simulator markers found.</li><li><code>build:rjs</code> output (<code>dist/index.rjs.js</code>): no simulator markers found.</li><li><code>build:app</code> output (<code>dist-app/**</code>): no simulator markers found.</li></ul>',13)])])}const h=i(r,[["render",s]]);export{p as __pageData,h as default};

package/dist-docs/assets/records_plans_2026-03-11-simulator-src-migration-implementation.md.FnB5Cx6R.lean.js DELETED Viewed

@@ -1 +0,0 @@