@ray-js/robot-map-sdk 0.0.16 → 0.0.17-beta.2

package/dist-docs/assets/adr_0004-beautify-shells-enclose-never-subtract.md.PRaaUF5r.js

@@ -0,0 +1 @@
+import{_ as t,c as a,o as n,aq as o}from"./chunks/framework.CBLqO2Q1.js";const u=JSON.parse('{"title":"Beautify shells enclose, never subtract","description":"","frontmatter":{},"headers":[],"relativePath":"adr/0004-beautify-shells-enclose-never-subtract.md","filePath":"adr/0004-beautify-shells-enclose-never-subtract.md","lastUpdated":1785228213000}'),s={name:"adr/0004-beautify-shells-enclose-never-subtract.md"};function i(l,e,r,d,h,c){return n(),a("div",null,[...e[0]||(e[0]=[o('<h1 id="beautify-shells-enclose-never-subtract" tabindex="-1">Beautify shells enclose, never subtract <a class="header-anchor" href="#beautify-shells-enclose-never-subtract" aria-label="Permalink to &quot;Beautify shells enclose, never subtract&quot;">​</a></h1><p>The first shipped beautify fitting (T2, 2026-07-21) was <em>best-fit</em>: each wall sat on the length-weighted mean line of its edge run, so the shell straddled the original outline and the footprint mask silently discarded roughly half of the genuinely mapped area along every wall. Field feedback on real maps (2026-07-22) rejected this: the outline is real device-collected data and the presentation layer was amputating it.</p><p>We replaced the fitting&#39;s core contract:</p><ul><li><p><strong>The original outline is ground truth. Beautify may only add presentation area around it, never subtract mapped area.</strong> A shell is the minimal-edge-count <em>enclosing</em> rectilinear polygon of the room outline in the dominant frame; the bounding rectangle is the limit case.</p><blockquote><p><strong>Update (2026-07-22):</strong> the dominant-frame rotation was disabled (θ=0). Shells are now enclosed in the SCREEN frame — the SDK no longer straightens device-tilted maps (that is the navigation stack&#39;s job). The enclose-never- subtract contract and the strict raw-outline containment below are unchanged; only the frame the enclosure is computed in changed (dominant → screen).</p></blockquote></li><li><p>Containment is a <strong>strict guarantee against the raw outline, not a tolerance</strong> (Round 3, 2026-07-22): the shell encloses every raw point with zero clipping (only float noise from the rotation round-trip, ~1e-6 px, is slack). The raw outline is device-scanned reachable area — the robot can physically get there — so it is rendered verbatim and unclipped; clipping it could make the robot appear to leave the map. Sub-<code>minNotch</code> features are smoothed <em>outward</em> only (dents fill, bumps lift their local wall); the RDP chord that grazes inside a real bump is corrected by an outward-expansion pass before the notch guard runs. <code>containTolerance</code> is removed.</p></li><li><p>The shared wall between two shells is welded along the <strong>gap corridor</strong>, not a single line: per row, the weld position must lie outside both rooms&#39; material, and where no common straight line exists (interlocked steps, weaving outlines) the overlap is segmented into a shared polyline so each room keeps its own steps — the previously structural clips (interlocked steps ~6 px, weaving outlines ~80 px²) are gone (all baselines now ≤ 1 px post-snap). The one principled residual clip is a <strong>true T-junction</strong>: a wall already welded to one neighbour, pinned across a third room&#39;s data on the same line — that span takes the locked line (the geometric floor of three-room co-linearity).</p></li><li><p>The fallback criterion follows the semantics: area <em>inflation ratio</em> (enclosing shells only grow), defaulted so that all baseline rooms stay rectilinear (worst 78%) while pathological diagonal shapes (≥ 100%) fall back. A fallback room carries <strong>no beautify geometry</strong> (<code>shell === null</code>) and renders its original geometry — conformal smoothing was removed in Round 3 because it altered the raw-outline shape.</p></li></ul><h2 id="consequences" tabindex="-1">Consequences <a class="header-anchor" href="#consequences" aria-label="Permalink to &quot;Consequences&quot;">​</a></h2><ul><li>Enclosing shells run visibly larger than the outline on wavy walls (baselines: 4–78% area inflation). This is the intended look: the light shell margin is presentation slack around the honest footprint, which is never visibly cut on exterior walls.</li><li>The footprint mask clip (ADR 0003) is <strong>retired</strong> (Round 3): containment is a pipeline invariant (the shell provably encloses every raw point), so the footprint renders in full with no render-time clip. Removing the mask is what makes any residual clipping visible — hence the strict guarantee.</li><li>Any future beautify geometry (curved shells, diagonal support) must keep the strict containment guarantee against the raw outline; a proposal that clips mapped area at all (beyond float noise) is a redesign of this ADR, not a parameter tweak.</li><li>Shapes that best-fit could not close (a triangle&#39;s ring cannot alternate) now produce their enclosing box via U-turn cap runs and are governed by the inflation fallback instead of returning null.</li><li>Wall-snap can emit <strong>polylines</strong>, not just moved straight edges: welded shells may gain vertices where a shared wall is segmented along the gap corridor. Downstream consumers (border split, doorway inference) must treat a shell edge as possibly subdivided.</li></ul><h2 id="update-2026-07-28-shell-levels-and-the-no-engulfment-guard" tabindex="-1">Update (2026-07-28): shell levels and the no-engulfment guard <a class="header-anchor" href="#update-2026-07-28-shell-levels-and-the-no-engulfment-guard" aria-label="Permalink to &quot;Update (2026-07-28): shell levels and the no-engulfment guard&quot;">​</a></h2><p>Field feedback: real rooms are mostly neat rectangles, so the <em>tightest</em> enclosing polygon renders a room whose honest shape is one rectangle as a 14–66 edge C or L, because every unscanned void stays carved out. This ADR already named the target — &quot;minimal-edge-count … the bounding rectangle is the limit case&quot; — so the fix is a budget, not a redesign.</p><p><code>map.beautify.level</code> selects between two fitting strengths:</p><ul><li><strong><code>faithful</code></strong> (default): today&#39;s tight fit, byte-identical output.</li><li><strong><code>boxy</code></strong>: on top of the faithful fit, keep applying the <strong>cheapest</strong> remaining notch merge (least added area) until the edge target is reached or an internal inflation budget is spent. Ordering by added area rather than edge length is what protects narrow-but-deep features: a 5 px wide, 40 px deep corridor bite is expensive and is filled last or not at all, while a shallow dent along a long wall is cheap and goes first.</li></ul><p>Two invariants make this safe, both verified against all five baselines:</p><ul><li><strong>Enclose-never-subtract is unchanged.</strong> Boxy only ever adds area; the strict raw-outline containment guarantee holds exactly (measured escape: 0 px).</li><li><strong>New clause — a shell may never <em>newly</em> contain another room&#39;s raw outline point.</strong> Pre-existing overlap stays tolerated (enclosing shells of interlocked rooms already collide and wall-snap welds them); only new engulfment is rejected. This clause is load-bearing, not defensive: without it shells swallow their neighbours, the shared wall ceases to exist, and doorway inference loses it (mockMapData2 16 → 12 doorways, raster-normal 12 → 8). It is what makes boxy shells <em>tile</em> the floorplan instead of stacking.</li></ul><p>Ordering matters and is part of the contract: the boxy pass must run <strong>after</strong> the tight pass, never instead of it. The tight pass is unbounded in inflation during smoothing (only the fallback threshold caps the result), so a budget-capped pass alone stops earlier and yields <em>more</em> edges. Composing them makes boxy edge counts monotonically ≤ faithful and keeps the O(m²) boxy scan on an already-shortened run list.</p><p>The boxy level carries its own, looser fallback threshold. Relaxing notch smoothing without relaxing the fallback would make the holey rooms this feature targets render <em>raw</em> — strictly worse than before.</p><p>Consequence, accepted: on a <strong>diagonal</strong> shared wall the polyline weld staircases down the diagonal and the post-snap vertex count grows well past the fitted count (mockMapData1: 7 → 33). That is the correct answer, not a defect — in a rectilinear system no single weld line can separate two diagonally-abutting rooms without clipping one of them, and capping the vertex count would buy a cosmetic number by clipping mapped area, which this ADR forbids.</p><h3 id="refinement-2026-07-28-the-inflation-budget-is-split-in-two" tabindex="-1">Refinement (2026-07-28): the inflation budget is split in two <a class="header-anchor" href="#refinement-2026-07-28-the-inflation-budget-is-split-in-two" aria-label="Permalink to &quot;Refinement (2026-07-28): the inflation budget is split in two&quot;">​</a></h3><p>Field question right after the boxy level landed: a room whose bottom-left notch was plainly free to expand still rendered as an L. Diagnosis: the general inflation budget, not the neighbour guard — the room&#39;s raw footprint is a thin snaking blob, so its bounding rectangle costs 118% inflation against an 80% cap.</p><p>The obvious fix (raise the general budget) is the wrong one. Measured across all five baselines, a global budget of 1.5 produces <strong>exactly the same number of rectangles</strong> as the alternative below, while additionally manufacturing rooms that are both heavily inflated <em>and</em> still lumpy — mockMapData3 room 0 goes from 10 edges / 76% to 8 edges / 133%, paying 57 points of invented area and still not reaching a rectangle.</p><p>So the budget is split: a general cap, plus a <strong>looser cap that applies only to the one merge that lands the room exactly on 4 edges</strong>. A rectangle is this level&#39;s goal state, so spending extra to land exactly on it is worth more than spending the same amount to stop halfway. The rectangle cap is still a cap, not a blank cheque — a thin L whose bounding rectangle would cost 170% keeps its notch. (2.5 was measured too and yields the same rectangles as 1.5, so 1.5 is where the curve flattens.)</p><p>The consequence is explicit and intended: a room can now render as a rectangle where <strong>more than half the drawn area was never scanned</strong> (the room above is 118% inflated). That is the trade this level exists to make; <code>faithful</code> remains the default for callers who will not take it. What has <em>not</em> changed is the guard — every remaining non-rectangular room on that baseline is held by real neighbour data, not by budget.</p>',20)])])}const p=t(s,[["render",i]]);export{u as __pageData,p as default};

package/dist-docs/assets/adr_0004-beautify-shells-enclose-never-subtract.md.PRaaUF5r.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as a,o as n,aq as o}from"./chunks/framework.CBLqO2Q1.js";const u=JSON.parse('{"title":"Beautify shells enclose, never subtract","description":"","frontmatter":{},"headers":[],"relativePath":"adr/0004-beautify-shells-enclose-never-subtract.md","filePath":"adr/0004-beautify-shells-enclose-never-subtract.md","lastUpdated":1785228213000}'),s={name:"adr/0004-beautify-shells-enclose-never-subtract.md"};function i(l,e,r,d,h,c){return n(),a("div",null,[...e[0]||(e[0]=[o("",20)])])}const p=t(s,[["render",i]]);export{u as __pageData,p as default};

package/dist-docs/assets/{app.Cd1m9LaA.js → app.BKcB-q3l.js}

@@ -1 +1 @@
-import{R as p}from"./chunks/theme.CUoWj-PI.js";import{R as s,ad as i,ae as u,af as c,ag as l,ah as f,ai as d,aj as m,ak as h,al as g,am as A,d as v,u as R,v as w,s as y,an as C,ao as P,ap as b,a7 as E}from"./chunks/framework.CBLqO2Q1.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),P(),b(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=D(),a=j();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function j(){return A(S)}function D(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};
+import{R as p}from"./chunks/theme.CAU4HwNY.js";import{R as s,ad as i,ae as u,af as c,ag as l,ah as f,ai as d,aj as m,ak as h,al as g,am as A,d as v,u as R,v as w,s as y,an as C,ao as P,ap as b,a7 as E}from"./chunks/framework.CBLqO2Q1.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),P(),b(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=D(),a=j();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function j(){return A(S)}function D(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};