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

package/dist/constant/methods.js

@@ -1 +1 @@
-const e=["areRoomsAdjacent","getForbiddenSweepZones","getForbiddenMopZones","getCleanZones","getVirtualWalls","getThresholds","getSpots","getRoomAnchors","getWayPoints","getViewportCenterPoint","getMapCenterPoint","getWallPointsByViewportCenter","getForbiddenSweepZonePointsByViewportCenter","getForbiddenMopZonePointsByViewportCenter","getCleanZonePointsByViewportCenter","getSpotPointByViewportCenter","getEffectiveDividerPoints","getDividerEndPoints","isNearChargerOrRobot","isPointInAnyRoom","isWallIntersectsAnyRoom","isZoneIntersectsAnyRoom","resetPanZoom","snapshot","snapshotByData","getCustomCarpets","forceEndGesture","getFurniturePointsByViewportCenter","getCustomCarpetPointsByViewportCenter","getRectPointsByCenter","getFurnitures","drawCustomZones","getCustomZones","clearCustomZones","setEditingCustomZones"],o=["onMapFirstDrawed","onMapDrawed","onPathDrawed","onRoomPropertiesDrawed","onRoomsDrawed","onClickRoom","onClickRoomProperties","onRemoveForbiddenSweepZone","onRemoveForbiddenMopZone","onRemoveCleanZone","onRemoveVirtualWall","onRemoveThreshold","onUpdateForbiddenSweepZone","onUpdateForbiddenMopZone","onUpdateCleanZone","onUpdateVirtualWall","onUpdateThreshold","onUpdateSpot","onUpdateRoomAnchor","onUpdateWayPoint","onUpdateDivider","onClickForbiddenSweepZone","onClickForbiddenMopZone","onClickCleanZone","onClickVirtualWall","onClickThreshold","onClickSpot","onClickRoomAnchor","onClickWayPoint","onClickDetectedObject","onClickCustomElement","onClickMap","onClickCarpet","onDeleteCarpet","onUpdateCustomCarpet","onDeleteCustomCarpet","onGestureStart","onGestureEnd","onClickRobot","onClickChargingStation","onRemoveFurniture","onUpdateFurniture","onClickFurniture","onRemoveCustomZone","onUpdateCustomZone","onClickCustomZone"];export{e as MAP_API_METHODS,o as MAP_CALLBACK_METHODS};
+const e=["areRoomsAdjacent","getForbiddenSweepZones","getForbiddenMopZones","getCleanZones","getVirtualWalls","getThresholds","getRamps","getSpots","getRoomAnchors","getWayPoints","getViewportCenterPoint","getMapCenterPoint","getWallPointsByViewportCenter","getForbiddenSweepZonePointsByViewportCenter","getForbiddenMopZonePointsByViewportCenter","getCleanZonePointsByViewportCenter","getThresholdPointsByViewportCenter","getRampPointsByViewportCenter","getSpotPointByViewportCenter","getEffectiveDividerPoints","getDividerEndPoints","isNearChargerOrRobot","isPointInAnyRoom","isWallIntersectsAnyRoom","isZoneIntersectsAnyRoom","resetPanZoom","snapshot","snapshotByData","getCustomCarpets","forceEndGesture","getFurniturePointsByViewportCenter","getCustomCarpetPointsByViewportCenter","getRectPointsByCenter","getFurnitures","drawCustomZones","getCustomZones","clearCustomZones","setEditingCustomZones"],o=["onMapFirstDrawed","onMapDrawed","onPathDrawed","onRoomPropertiesDrawed","onRoomsDrawed","onClickRoom","onClickRoomProperties","onRemoveForbiddenSweepZone","onRemoveForbiddenMopZone","onRemoveCleanZone","onRemoveVirtualWall","onRemoveThreshold","onRemoveRamp","onUpdateForbiddenSweepZone","onUpdateForbiddenMopZone","onUpdateCleanZone","onUpdateVirtualWall","onUpdateThreshold","onUpdateRamp","onUpdateSpot","onUpdateRoomAnchor","onUpdateWayPoint","onUpdateDivider","onClickForbiddenSweepZone","onClickForbiddenMopZone","onClickCleanZone","onClickVirtualWall","onClickThreshold","onClickRamp","onClickSpot","onClickRoomAnchor","onClickWayPoint","onClickDetectedObject","onClickCustomElement","onClickMap","onClickCarpet","onDeleteCarpet","onUpdateCustomCarpet","onDeleteCustomCarpet","onGestureStart","onGestureEnd","onClickRobot","onClickChargingStation","onRemoveFurniture","onUpdateFurniture","onClickFurniture","onRemoveCustomZone","onUpdateCustomZone","onClickCustomZone"];export{e as MAP_API_METHODS,o as MAP_CALLBACK_METHODS};

package/dist/index.d.ts

@@ -74,8 +74,9 @@ export declare type AppConfig = {
             /**
              * 外壳规整档：`'faithful'`（缺省）外壳紧贴原始轮廓，未测绘到的空洞原样
              * 保留；`'boxy'` 花掉一份面积预算换更少的边，房间趋向规整的矩形 / L 形
-             * （空洞被浅色外壳盖住）。两档都只加不减，绝不削掉设备测绘到的区域，
-             * 也绝不吞掉别的房间已测绘的区域。档位映射到的化简预算是内部标定常量。
+             * （空洞被浅色外壳盖住）。两档都只加不减，绝不削掉设备测绘到的区域；
+             * 别的房间已测绘的区域也不会被外壳盖住（渲染分层保证，几何上贴身档的
+             * 外壳仍可能与邻居交叠）。档位映射到的化简预算是内部标定常量。
              */
             level: 'faithful' | 'boxy'
             /** 外壳边框宽度（像素），边框颜色复用 `map.obstacleColor` */
@@ -775,19 +776,24 @@ export declare type ComponentPropsApp = {
     app: MapApplicationInstance
 }
 
-/** 控制层内可排序元素 */
+/**
+ * 控制层内可排序元素。
+ *
+ * 门槛（threshold）不在其中：它是不透明地面元素，画在地面标记层
+ * （路径 / 机器人 / 房间名之下），层内顺序固定，不参与控制层排序
+ * （见 ADR 0006）。
+ */
 export declare type ControlRenderItem =
 | 'forbiddenSweepZone'
 | 'forbiddenMopZone'
 | 'cleanZone'
 | 'virtualWall'
-| 'threshold'
 | 'spot'
 | 'roomAnchor'
 | 'wayPoint'
 | 'divider'
 // Allow any string for custom zone types while keeping IDE autocomplete
-// for the seven built-in items via the `(string & {})` trick.
+// for the eight built-in items via the `(string & {})` trick.
 | (string & {})
 
 /**
@@ -838,6 +844,8 @@ export declare type ControlsConfig = {
     virtualWall: VirtualWallConfig
     /** 门槛配置 */
     threshold: ThresholdConfig
+    /** 坡道配置 */
+    ramp: RampConfig
     /** 定点清扫配置 */
     spot: SpotConfig
     /**
@@ -1129,9 +1137,9 @@ export declare type LoggerPayload = {
     ts: number
 }
 
-export declare const MAP_API_METHODS: readonly ["areRoomsAdjacent", "getForbiddenSweepZones", "getForbiddenMopZones", "getCleanZones", "getVirtualWalls", "getThresholds", "getSpots", "getRoomAnchors", "getWayPoints", "getViewportCenterPoint", "getMapCenterPoint", "getWallPointsByViewportCenter", "getForbiddenSweepZonePointsByViewportCenter", "getForbiddenMopZonePointsByViewportCenter", "getCleanZonePointsByViewportCenter", "getSpotPointByViewportCenter", "getEffectiveDividerPoints", "getDividerEndPoints", "isNearChargerOrRobot", "isPointInAnyRoom", "isWallIntersectsAnyRoom", "isZoneIntersectsAnyRoom", "resetPanZoom", "snapshot", "snapshotByData", "getCustomCarpets", "forceEndGesture", "getFurniturePointsByViewportCenter", "getCustomCarpetPointsByViewportCenter", "getRectPointsByCenter", "getFurnitures", "drawCustomZones", "getCustomZones", "clearCustomZones", "setEditingCustomZones"];
+export declare const MAP_API_METHODS: readonly ["areRoomsAdjacent", "getForbiddenSweepZones", "getForbiddenMopZones", "getCleanZones", "getVirtualWalls", "getThresholds", "getRamps", "getSpots", "getRoomAnchors", "getWayPoints", "getViewportCenterPoint", "getMapCenterPoint", "getWallPointsByViewportCenter", "getForbiddenSweepZonePointsByViewportCenter", "getForbiddenMopZonePointsByViewportCenter", "getCleanZonePointsByViewportCenter", "getThresholdPointsByViewportCenter", "getRampPointsByViewportCenter", "getSpotPointByViewportCenter", "getEffectiveDividerPoints", "getDividerEndPoints", "isNearChargerOrRobot", "isPointInAnyRoom", "isWallIntersectsAnyRoom", "isZoneIntersectsAnyRoom", "resetPanZoom", "snapshot", "snapshotByData", "getCustomCarpets", "forceEndGesture", "getFurniturePointsByViewportCenter", "getCustomCarpetPointsByViewportCenter", "getRectPointsByCenter", "getFurnitures", "drawCustomZones", "getCustomZones", "clearCustomZones", "setEditingCustomZones"];
 
-export declare const MAP_CALLBACK_METHODS: readonly ["onMapFirstDrawed", "onMapDrawed", "onPathDrawed", "onRoomPropertiesDrawed", "onRoomsDrawed", "onClickRoom", "onClickRoomProperties", "onRemoveForbiddenSweepZone", "onRemoveForbiddenMopZone", "onRemoveCleanZone", "onRemoveVirtualWall", "onRemoveThreshold", "onUpdateForbiddenSweepZone", "onUpdateForbiddenMopZone", "onUpdateCleanZone", "onUpdateVirtualWall", "onUpdateThreshold", "onUpdateSpot", "onUpdateRoomAnchor", "onUpdateWayPoint", "onUpdateDivider", "onClickForbiddenSweepZone", "onClickForbiddenMopZone", "onClickCleanZone", "onClickVirtualWall", "onClickThreshold", "onClickSpot", "onClickRoomAnchor", "onClickWayPoint", "onClickDetectedObject", "onClickCustomElement", "onClickMap", "onClickCarpet", "onDeleteCarpet", "onUpdateCustomCarpet", "onDeleteCustomCarpet", "onGestureStart", "onGestureEnd", "onClickRobot", "onClickChargingStation", "onRemoveFurniture", "onUpdateFurniture", "onClickFurniture", "onRemoveCustomZone", "onUpdateCustomZone", "onClickCustomZone"];
+export declare const MAP_CALLBACK_METHODS: readonly ["onMapFirstDrawed", "onMapDrawed", "onPathDrawed", "onRoomPropertiesDrawed", "onRoomsDrawed", "onClickRoom", "onClickRoomProperties", "onRemoveForbiddenSweepZone", "onRemoveForbiddenMopZone", "onRemoveCleanZone", "onRemoveVirtualWall", "onRemoveThreshold", "onRemoveRamp", "onUpdateForbiddenSweepZone", "onUpdateForbiddenMopZone", "onUpdateCleanZone", "onUpdateVirtualWall", "onUpdateThreshold", "onUpdateRamp", "onUpdateSpot", "onUpdateRoomAnchor", "onUpdateWayPoint", "onUpdateDivider", "onClickForbiddenSweepZone", "onClickForbiddenMopZone", "onClickCleanZone", "onClickVirtualWall", "onClickThreshold", "onClickRamp", "onClickSpot", "onClickRoomAnchor", "onClickWayPoint", "onClickDetectedObject", "onClickCustomElement", "onClickMap", "onClickCarpet", "onDeleteCarpet", "onUpdateCustomCarpet", "onDeleteCustomCarpet", "onGestureStart", "onGestureEnd", "onClickRobot", "onClickChargingStation", "onRemoveFurniture", "onUpdateFurniture", "onClickFurniture", "onRemoveCustomZone", "onUpdateCustomZone", "onClickCustomZone"];
 
 /**
  * 地图 API 接口定义
@@ -1276,6 +1284,12 @@ export declare interface MapApi {
      * @returns 门槛数据数组（长度已修正，`height` 已补默认值并钳制）
      */
     getThresholds(): ThresholdParam[];
+    /**
+     * 获取当前地图上所有坡道数据
+     *
+     * @returns 坡道数据数组（角点为归一化后的结果）
+     */
+    getRamps(): RampParam[];
     /**
      * 获取当前地图上所有定点清扫数据
      *
@@ -1440,6 +1454,50 @@ export declare interface MapApi {
         offsetX?: number;
         offsetY?: number;
     }): Point[];
+    /**
+     * 基于视口中心生成门槛的四个角点坐标
+     *
+     * 缺省尺寸 1m × 0.15m（长 × 厚）—— 「新建门槛」的初始尺寸，不是配置项；
+     * 需要别的初始尺寸就传 `width` / `height`。传入值会被钳制到
+     * `controls.threshold` 的 `minLength`/`maxLength` 与 `minHeight`/`maxHeight`
+     * （米）区间内。
+     *
+     * @param options - 配置选项
+     * @param options.width - 门槛长度，单位米，默认 1
+     * @param options.height - 门槛厚度，单位米，默认 0.15
+     * @param options.offsetX - X方向像素偏移，支持负数，默认为 0
+     * @param options.offsetY - Y方向像素偏移，支持负数，默认为 0
+     * @returns 四个角点坐标，顺时针顺序：[左上, 右上, 右下, 左下]（0→1 为长度
+     *   方向，0→3 为厚度方向），可直接作为 `ThresholdParam.points`
+     */
+    getThresholdPointsByViewportCenter(options?: {
+        width?: number;
+        height?: number;
+        offsetX?: number;
+        offsetY?: number;
+    }): Point[];
+    /**
+     * 基于视口中心生成坡道的四个角点坐标
+     *
+     * 缺省尺寸 0.8m × 0.4m（宽 × 高，高方向即坡向）—— 「新建坡道」的初始尺寸，不是配置项；
+     * 需要别的初始尺寸就传 `width` / `height`。传入值会被钳制到
+     * `controls.ramp` 的 `minWidth`/`maxWidth` 与 `minHeight`/`maxHeight`
+     * （米）区间内。
+     *
+     * @param options - 配置选项
+     * @param options.width - 坡道宽度，单位米，默认 0.8
+     * @param options.height - 坡道高度，单位米，默认 0.4（正好等于 minHeight）
+     * @param options.offsetX - X方向像素偏移，支持负数，默认为 0
+     * @param options.offsetY - Y方向像素偏移，支持负数，默认为 0
+     * @returns 四个角点坐标，顺时针顺序：[左上, 右上, 右下, 左下]（0→1 为宽
+     *   方向，0→3 为高方向），可直接作为 `RampParam.points`；坡向为屏幕上方
+     */
+    getRampPointsByViewportCenter(options?: {
+        width?: number;
+        height?: number;
+        offsetX?: number;
+        offsetY?: number;
+    }): Point[];
     /**
      * 基于任意中心点生成矩形的四个顶点坐标
      *
@@ -1723,6 +1781,15 @@ export declare interface MapCallbacks {
      * @param.en id - ID of the deleted threshold
      */
     onRemoveThreshold?: (id: string) => void;
+    /**
+     * @description.zh 点击坡道删除按钮的回调
+     * @description.en Callback when clicking the delete button of ramp
+     * @description.zh 当用户点击编辑态坡道的删除按钮时触发。SDK 不会移除该坡道，宿主更新自己的坡道列表后重绘。
+     * @description.en Triggered when the user clicks the delete button of an editing ramp. The SDK does not remove it; the host updates its own list and redraws.
+     * @param.zh id - 被删除的坡道ID
+     * @param.en id - ID of the deleted ramp
+     */
+    onRemoveRamp?: (id: string) => void;
     /**
      * @description.zh 更新禁扫区域的回调
      * @description.en Callback when updating forbidden sweep zone
@@ -1768,6 +1835,15 @@ export declare interface MapCallbacks {
      * @param.en threshold - Updated threshold data
      */
     onUpdateThreshold?: (threshold: ThresholdParam) => void;
+    /**
+     * @description.zh 更新坡道的回调
+     * @description.en Callback when updating ramp
+     * @description.zh 当用户完成一次坡道编辑操作（旋转 / 缩放 / 移动，或拖拽整体平移）后触发，携带最终几何。
+     * @description.en Triggered after the user finishes a ramp edit (rotate/scale/move, or body drag), carrying the final geometry.
+     * @param.zh ramp - 更新后的坡道数据
+     * @param.en ramp - Updated ramp data
+     */
+    onUpdateRamp?: (ramp: RampParam) => void;
     /**
      * @description.zh 更新定点清扫的回调
      * @description.en Callback when updating spot clean
@@ -1849,6 +1925,15 @@ export declare interface MapCallbacks {
      * @param.en threshold - Clicked threshold data
      */
     onClickThreshold?: (threshold: ThresholdParam) => void;
+    /**
+     * @description.zh 点击坡道回调
+     * @description.en Callback when clicking ramp
+     * @description.zh 点击坡道时触发。常用于「点击进入编辑」（把该 id 加入 editingRampIds）。
+     * @description.en Triggered when the user taps a ramp. Commonly used to enter edit mode (add the id to editingRampIds).
+     * @param.zh ramp - 被点击的坡道数据
+     * @param.en ramp - Clicked ramp data
+     */
+    onClickRamp?: (ramp: RampParam) => void;
     /**
      * @description.zh 点击定点清扫回调
      * @description.en Callback when clicking spot clean
@@ -2202,6 +2287,114 @@ export declare type ProcessedRasterData = {
     totalPixels: number
 }
 
+/** 坡道配置 */
+export declare type RampConfig = {
+    /** 底色（不透明 —— 坡道是地面元素，画在路径 / 机器人之下，见 ADR 0006） */
+    fillColor: ColorSource
+    /** 描边颜色 */
+    strokeColor: ColorSource
+    /** 描边线宽（屏幕像素，不随地图缩放） */
+    strokeWidth: number
+    /**
+     * 箭头颜色。默认白色 40% 透明叠在底色上（与 UED 稿一致）——
+     * 这样改 `fillColor` 时箭头会自动跟随，不用两处对着调。
+     */
+    arrowColor: ColorSource
+    /**
+     * 箭头**最小**线宽（屏幕像素，不随地图缩放）。
+     *
+     * 实际线宽取 `实际行距 × arrowThicknessRatio` 与本值中的较大者：正常缩放
+     * 下由比例决定（线与缝的粗细比恒定，观感等于 UED 稿），坡道小到 / 地图
+     * 缩到线要细过本值时由本值兜底，保证箭头不会细成看不见。
+     */
+    arrowThickness: number
+    /**
+     * 箭头线宽相对**实际行距**的比例，UED 稿量得 `3 / 7 ≈ 0.43`。
+     *
+     * 线宽跟着行距走而不是锁在固定像素：行距随坡道尺寸变化，若线宽不跟着长，
+     * 放大地图就会看到又粗又疏的缝里夹着细发丝一样的箭头。按比例算才能任何
+     * 缩放下都是同一张贴纸。
+     */
+    arrowThicknessRatio: number
+    /**
+     * 相邻箭头的**最小**间隙（屏幕像素），沿坡向度量。
+     *
+     * 最小步距 = `arrowThickness + arrowGap`，它是密度上限：箭头永远不会比这
+     * 更挤。地图缩得很小时它会顶掉 {@link RampConfig.arrowDensity} 算出的砖
+     * 尺寸，让砖变大、行数变少，保证箭头不会糊成一片。
+     */
+    arrowGap: number
+    /**
+     * 纹样密度：**短边**上铺几个箭头。UED 稿是方形坡道上 6 个，故默认 6。
+     *
+     * 箭头是一块比例固定的「砖」，而不是拉满坡道宽度的单根折线：砖的尺寸
+     * 取 `短边 / arrowDensity`，再沿坡向铺若干**行**、沿宽方向铺若干**列**。
+     * 因此任何宽高比的坡道看到的都是同一块砖，只是数量不同。
+     *
+     * 若改成「整宽一个箭头 + 固定行数」，折角深浅由宽决定、线宽由高决定，
+     * 两个特征分别挂在两条边上：窄高坡道会退化成胖带子（折角只有线宽的
+     * 1/7），宽矮坡道会退化成细丝配大折角。见 plan record
+     * `docs/records/plans/2026-08-06-ramp-map-element-plan.md`。
+     *
+     * 调小更稀、调大更密；密度还受最小步距 `arrowThickness + arrowGap` 约束。
+     */
+    arrowDensity: number
+    /**
+     * 箭头两臂相对横轴的抬升角度（度），钳制在 `[1, 60]`。
+     *
+     * **不是固定的外凸像素**：外凸量由 `半个砖宽 × tan(角度)` 反推，所以任何
+     * 坡道尺寸、任何地图缩放下箭头形状恒定。若改成固定像素，宽砖上的箭头会
+     * 被摊平成直线。UED 稿量得约 8.7°，默认取 9。
+     */
+    arrowAngle: number
+    /** 箭头区域相对坡道边缘的内缩（屏幕像素），箭头不贴边 */
+    arrowInset: number
+    /** 最小宽度 (米)，绘制与缩放时宽边（顶点 0→1）被钳制到不小于该值 */
+    minWidth: number
+    /** 最大宽度 (米)，可选。缺省或 ≤ minWidth 时不限制。 */
+    maxWidth?: number
+    /** 最小高度 (米)，绘制与缩放时高边（顶点 0→3）被钳制到不小于该值 */
+    minHeight: number
+    /** 最大高度 (米)，可选。缺省或 ≤ minHeight 时不限制。 */
+    maxHeight?: number
+    /** 四角控制按钮图标容器填充颜色（编辑态显示） */
+    iconWrapperFillColor: ColorSource
+    /** 编辑态轮廓相对坡道边缘的偏移（屏幕像素） */
+    outlineOffset: number
+    /** 编辑态轮廓描边颜色 */
+    outlineStrokeColor: ColorSource
+    /** 编辑态轮廓描边宽度 */
+    outlineStrokeWidth: number
+    /** 编辑态轮廓是否虚线 */
+    outlineDashed: boolean
+    /** 编辑态轮廓虚线数组 */
+    outlineDashArray: [number, number]
+    /** 编辑态轮廓填充颜色 */
+    outlineFillColor: ColorSource
+    /** 尺寸标签（宽×高）文本颜色（编辑态显示） */
+    textColor: ColorSource
+    /** 尺寸标签相对轮廓边缘向外的偏移（屏幕像素） */
+    textOffset: number
+}
+
+/** 坡道参数 */
+export declare type RampParam = {
+    /** 坡道ID */
+    id: string
+    /**
+     * 四角坐标（地图像素坐标系），顺时针 左上→右上→右下→左下，与家具 /
+     * 禁区等四边形元素同序：顶点 0→1 为宽（w）方向，0→3 为高（h）方向。
+     *
+     * 坡道的上坡方向由点序自带：垂直于 0→1 边、从 3→2 边指向 0→1 边
+     * （未旋转时即"朝上"）。旋转时点集整体旋转，坡向随之旋转 —— 没有独立的
+     * direction 字段。因此点序**不做**长边规范（那会翻转坡向），入口只纠正
+     * 绕向为顺时针、把宽与高分别钳制到 `minWidth`/`maxWidth` 与
+     * `minHeight`/`maxHeight`（米）区间并拉直成标准矩形。`getRamps()` 回吐的
+     * 点集是归一化后的结果，不一定与传入的原始点逐字相同。
+     */
+    points: Point[]
+}
+
 /**
  * 栅格房间的美化几何（仅 `runtime.enableBeautify` 开启时由 MapManager 计算，
  * 随 `ProcessedRasterData` 一并交给渲染层）。
@@ -2455,6 +2648,14 @@ export declare type RuntimeConfig = {
      * 加入本列表即可。
      */
     editingThresholdIds: string[]
+    /**
+     * 正在编辑的坡道ID列表。
+     *
+     * 列入的坡道显示编辑控件（虚线轮廓、尺寸标签与删除 / 旋转 / 缩放 / 移动
+     * 按钮）并可整体拖拽；未列入的坡道不显示编辑控件，但坡道本身仍可点击
+     * （上抛 `onClickRamp`，宿主可借此实现「点击进入编辑」）。
+     */
+    editingRampIds: string[]
     /** 正在编辑的定点清扫ID列表 */
     editingSpotIds: string[]
     /** 正在编辑的房间锚点ID列表（独立于 editingSpotIds，互不影响） */
@@ -2630,28 +2831,57 @@ export declare type SpotParam = {
 
 /** 门槛配置 */
 export declare type ThresholdConfig = {
-    /** 条纹线宽（屏幕像素，不随地图缩放变化） */
+    /**
+     * 条纹线宽，垂直于斜纹方向度量（斜纹角度见 {@link ThresholdConfig.stripeAngle}）。
+     *
+     * **单位是条带厚度的比例，不是像素**（0.3 表示线宽为条带厚度的 30%）。
+     * 于是整套纹路跟着条带一起缩放：跨条带的条纹根数、疏密、着色比例在任何
+     * 地图缩放下都不变，薄门槛与厚门槛看起来也是同一张贴纸。
+     */
     stripeWidth: number
-    /** 相邻条纹间距（屏幕像素） */
+    /**
+     * 相邻条纹间距，沿条带长度方向度量。**单位同样是条带厚度的比例。**
+     *
+     * 步距 `stripeWidth + stripeGap` 决定疏密：取 0.7 时，一根斜纹横穿条带的
+     * 水平距离约为步距的 `1 / (0.7 × tan(stripeAngle))` 倍。
+     *
+     * 两者不同轴：`stripeWidth` 是垂直于斜纹的线宽，同一根斜纹沿长度方向占
+     * `stripeWidth / sin(stripeAngle)`（45° 时为 `× √2`），所以着色比例约为
+     * `stripeWidth / sin(stripeAngle) / (stripeWidth + stripeGap)`——默认值下
+     * 约 55%。调陡 `stripeAngle` 会让条带变淡，需同步放大 `stripeWidth`。
+     */
     stripeGap: number
+    /**
+     * 斜纹倾斜方向：`'forward'` 为 `/`（沿长度方向向右上），`'backward'` 为
+     * `\`（向右下）。缺省 `'forward'`。厂商之间惯例不一，两种都保留。
+     */
+    stripeDirection: 'forward' | 'backward'
+    /**
+     * 斜纹与条带长度方向的夹角（度）。`45` 是常见的危险胶带角度，`90` 为垂直
+     * 于条带的竖条纹；取值钳制在 `[10, 90]`。
+     *
+     * 注意角度会连带改变疏密与着色：斜纹越陡，横穿条带需要的水平距离越短
+     * （`厚度 / tan(角度)`），同样的步距下穿过条带的条纹越少；同时一根斜纹沿
+     * 长度方向只占 `stripeWidth / sin(角度)`，所以着色比例也会下降。改陡以后
+     * 想维持观感，需要同步调小 `stripeGap`。
+     */
+    stripeAngle: number
     /** 条带边框线宽（屏幕像素） */
     borderWidth: number
     /** 条带圆角半径（屏幕像素，自动不超过条带半厚 / 半长） */
     cornerRadius: number
-    /** 可通行门槛样式（默认绿色斜纹） */
+    /** 可通行门槛样式（默认蓝白斜纹） */
     passable: ThresholdStyle
-    /** 不可通行门槛样式（默认红色斜纹） */
+    /** 不可通行门槛样式（默认红白斜纹） */
     impassable: ThresholdStyle
-    /** 最小长度 (米)，绘制与缩放时长度被钳制到不小于该值 */
+    /** 最小长度 (米)，绘制与缩放时长边（顶点 0→1）被钳制到不小于该值 */
     minLength: number
     /** 最大长度 (米)，可选。缺省或 ≤ minLength 时不限制。 */
     maxLength?: number
-    /** 最小高度 (米)，绘制与缩放时条带高度被钳制到不小于该值 */
+    /** 最小厚度 (米)，绘制与缩放时厚度边（顶点 0→3）被钳制到不小于该值 */
     minHeight: number
-    /** 最大高度 (米)，可选。缺省或 ≤ minHeight 时不限制。 */
+    /** 最大厚度 (米)，可选。缺省或 ≤ minHeight 时不限制。 */
     maxHeight?: number
-    /** 数据未携带 height 时的默认条带高度 (米) */
-    defaultHeight: number
     /** 四角控制按钮图标容器填充颜色（编辑态显示） */
     iconWrapperFillColor: ColorSource
     /**
@@ -2672,7 +2902,7 @@ export declare type ThresholdConfig = {
     outlineDashArray: [number, number]
     /** 编辑态轮廓填充颜色 */
     outlineFillColor: ColorSource
-    /** 尺寸标签（长×高）文本颜色（编辑态显示） */
+    /** 尺寸标签（长×厚）文本颜色（编辑态显示） */
     textColor: ColorSource
     /** 尺寸标签相对轮廓边缘向外的偏移（屏幕像素） */
     textOffset: number
@@ -2681,27 +2911,30 @@ export declare type ThresholdConfig = {
 /**
  * 门槛参数。
  *
- * 门槛是「中心线 + 高度」的矩形条带元素，用可通行 / 不可通行两种类型标记
- * 机器人能否跨越的通道，渲染为斜纹条带（可通行绿色 / 不可通行红色）。条带
- * 为真实世界尺寸：长度由两端点决定，厚度由 `height` 决定，随地图缩放。
+ * 门槛是四角坐标描述的矩形条带元素，用可通行 / 不可通行两种类型标记机器人
+ * 能否跨越的通道，渲染为白底斜纹条带（可通行蓝白 / 不可通行红白）。条带为真实
+ * 世界尺寸（长度与厚度都由四角坐标决定，随地图缩放）。数据形态与禁区 /
+ * 家具等四边形元素一致 —— 与主流厂商的门槛协议对齐（见 ADR 0005）。
  *
  * 交互由运行时 `editingThresholdIds` 门控：列入的门槛显示编辑控件（虚线
  * 轮廓、尺寸标签与删除 / 旋转 / 缩放 / 移动按钮，与禁区等四边形元素同一套
- * 编辑面），长与高在缩放时各自钳制到 `minLength`/`maxLength` 与
+ * 编辑面），长与厚在缩放时各自钳制到 `minLength`/`maxLength` 与
  * `minHeight`/`maxHeight`（米）区间。编辑结束触发 `onUpdateThreshold`，
  * 点击触发 `onClickThreshold`，删除按钮触发 `onRemoveThreshold`。
  */
 export declare type ThresholdParam = {
     /** 门槛ID */
     id: string
-    /** 中心线两端点坐标（起点、终点），与其他元素同为地图像素坐标系 */
-    points: [Point, Point]
     /**
-     * 条带高度（厚度），单位与 points 相同（地图像素）。缺省时取
-     * `controls.threshold.defaultHeight`（米）换算；绘制与缩放时被钳制在
-     * `minHeight` / `maxHeight`（米）区间内。
+     * 四角坐标（地图像素坐标系），顺时针 左上→右上→右下→左下，与家具 /
+     * 禁区等四边形元素同序：顶点 0→1 为长度方向，0→3 为厚度方向。
+     *
+     * 入口处会归一化：绕向纠正为顺时针、较长的一条边规范到 0→1、长与厚
+     * 分别钳制到 `minLength`/`maxLength` 与 `minHeight`/`maxHeight`（米）区间，
+     * 再拉直成标准矩形（保留旋转角与中心）。因此 `getThresholds()` 回吐的
+     * 点集是归一化后的结果，不一定与传入的原始点逐字相同。
      */
-    height?: number
+    points: Point[]
     /** 门槛类型（可通行 / 不可通行）。缺省为 `passable`（可通行）。 */
     type?: ThresholdType
 }
@@ -2717,8 +2950,8 @@ export declare type ThresholdStyle = {
 /**
  * 门槛类型。
  *
- * - `'passable'`：可通行门槛，机器人可尝试跨越，默认渲染为绿色斜纹条带
- * - `'impassable'`：不可通行门槛，机器人不得跨越，默认渲染为红色斜纹条带
+ * - `'passable'`：可通行门槛，机器人可尝试跨越，默认渲染为蓝白斜纹条带
+ * - `'impassable'`：不可通行门槛，机器人不得跨越，默认渲染为红白斜纹条带
  */
 export declare type ThresholdType = 'passable' | 'impassable'
 
@@ -2873,3 +3106,19 @@ export declare type ZoneParam = {
 export declare type ZoneTypeDefinition = ZoneConfig
 
 export { }
+
+/**
+ * Minimal `node:fs` surface for the few tests that read source files off disk
+ * (structural invariants like `throttle-cancel-invariant.test.ts`).
+ *
+ * `@types/node` is installed but unreachable: `tsconfig.json` pins `typeRoots`
+ * to `./src/core/@types`, deliberately keeping Node globals out of a browser
+ * SDK's type surface. Shimming the three functions actually used is contained;
+ * widening `typeRoots` would put `process`, `Buffer` and friends in scope for
+ * every `src/` file, where they must never be used.
+ */
+declare module 'node:fs' {
+  export function readFileSync(path: string, encoding: 'utf8'): string
+  export function readdirSync(path: string): string[]
+  export function statSync(path: string): { isDirectory(): boolean }
+}