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

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 (88) hide show
  1. package/bin/mcp-server.js +31 -15
  2. package/dist/constant/methods.js +1 -1
  3. package/dist/index.d.ts +894 -51
  4. package/dist/index.rjs.js +1 -1
  5. package/dist-app/assets/index-BD_1VjD4.js +1 -0
  6. package/dist-app/index.html +1 -1
  7. package/dist-docs/404.html +2 -2
  8. package/dist-docs/assets/{app.Cd1m9LaA.js → app.CEyCC3pk.js} +1 -1
  9. package/dist-docs/assets/chunks/@localSearchIndexroot.DS3IaJJ6.js +1 -0
  10. package/dist-docs/assets/chunks/{BitmapFont.COctfnp7.js → BitmapFont.P11QFENc.js} +1 -1
  11. package/dist-docs/assets/chunks/{BufferResource.BCDLxIzj.js → BufferResource.Ciw3zoJw.js} +1 -1
  12. package/dist-docs/assets/chunks/{CanvasRenderer.Bssy09MS.js → CanvasRenderer.Bd4TJlpG.js} +1 -1
  13. package/dist-docs/assets/chunks/{RenderTargetSystem.CjYHTdeo.js → RenderTargetSystem.CU6a5B7C.js} +1 -1
  14. package/dist-docs/assets/chunks/{VPLocalSearchBox.D8CmmPQy.js → VPLocalSearchBox.cMcNIo6m.js} +1 -1
  15. package/dist-docs/assets/chunks/{WebGLRenderer.Ddc_zq8h.js → WebGLRenderer.BQraRxjU.js} +1 -1
  16. package/dist-docs/assets/chunks/{WebGPURenderer.CiQbGJ6S.js → WebGPURenderer.Qmmhy3Dc.js} +1 -1
  17. package/dist-docs/assets/chunks/{browserAll.DDmHIbps.js → browserAll.BDQA54DN.js} +1 -1
  18. package/dist-docs/assets/chunks/index.Cnrqr1lO.js +744 -0
  19. package/dist-docs/assets/chunks/theme.mgJ4a6Qj.js +4 -0
  20. package/dist-docs/assets/chunks/{webworkerAll.wMItuqKH.js → webworkerAll.DiP9iN0J.js} +1 -1
  21. package/dist-docs/assets/{guide_advanced-usage.md.dxD8u9v3.js → guide_advanced-usage.md.w-yj_56g.js} +142 -82
  22. package/dist-docs/assets/{guide_advanced-usage.md.dxD8u9v3.lean.js → guide_advanced-usage.md.w-yj_56g.lean.js} +1 -1
  23. package/dist-docs/assets/{guide_getting-started.md.BKeG0DkW.js → guide_getting-started.md.BCkW3g7r.js} +1 -1
  24. package/dist-docs/assets/guide_mcp.md.BYlNOxMG.js +1 -0
  25. package/dist-docs/assets/{guide_mcp.md.CabCiX8Z.lean.js → guide_mcp.md.BYlNOxMG.lean.js} +1 -1
  26. package/dist-docs/assets/reference_callbacks.md.5owd-5nN.js +33 -0
  27. package/dist-docs/assets/{reference_callbacks.md.Cm_LNx97.lean.js → reference_callbacks.md.5owd-5nN.lean.js} +1 -1
  28. package/dist-docs/assets/reference_config.md.W-7brnWs.js +303 -0
  29. package/dist-docs/assets/reference_config.md.W-7brnWs.lean.js +1 -0
  30. package/dist-docs/assets/{reference_data.md.DL6rfzez.js → reference_data.md.f7vBtzcn.js} +20 -7
  31. package/dist-docs/assets/{reference_data.md.DL6rfzez.lean.js → reference_data.md.f7vBtzcn.lean.js} +1 -1
  32. package/dist-docs/assets/{reference_methods.md.yWEfqPKf.js → reference_methods.md.CXtsI5Rx.js} +23 -5
  33. package/dist-docs/assets/{reference_methods.md.yWEfqPKf.lean.js → reference_methods.md.CXtsI5Rx.lean.js} +1 -1
  34. package/dist-docs/assets/reference_runtime.md.CXIbwBrR.js +39 -0
  35. package/dist-docs/assets/reference_runtime.md.CXIbwBrR.lean.js +1 -0
  36. package/dist-docs/assets/{reference_types.md.ZQU03iAA.js → reference_types.md.B2PPyukT.js} +25 -9
  37. package/dist-docs/assets/{reference_types.md.ZQU03iAA.lean.js → reference_types.md.B2PPyukT.lean.js} +1 -1
  38. package/dist-docs/guide/advanced-usage.html +145 -85
  39. package/dist-docs/guide/concepts.html +3 -3
  40. package/dist-docs/guide/getting-started.html +5 -5
  41. package/dist-docs/guide/mcp.html +5 -5
  42. package/dist-docs/guide/spot-room-binding.html +3 -3
  43. package/dist-docs/hashmap.json +1 -1
  44. package/dist-docs/index.html +3 -3
  45. package/dist-docs/plans/2026-03-04-detected-objects-visibility-design.html +3 -3
  46. package/dist-docs/plans/2026-03-04-show-detected-objects-implementation-plan.html +3 -3
  47. package/dist-docs/plans/2026-03-10-simulator-debug-design.html +3 -3
  48. package/dist-docs/plans/2026-03-10-simulator-events-console-design.html +3 -3
  49. package/dist-docs/plans/2026-03-10-simulator-events-console-implementation-plan.html +3 -3
  50. package/dist-docs/plans/2026-03-10-simulator-runtime-controls-design.html +3 -3
  51. package/dist-docs/plans/2026-03-10-simulator-runtime-controls-implementation-plan.html +3 -3
  52. package/dist-docs/plans/2026-03-10-testing-rollout-next-steps-plan.html +3 -3
  53. package/dist-docs/plans/2026-03-11-simulator-logger-dump-implementation-plan.html +3 -3
  54. package/dist-docs/reference/callbacks.html +5 -5
  55. package/dist-docs/reference/config.html +68 -12
  56. package/dist-docs/reference/data.html +23 -10
  57. package/dist-docs/reference/methods.html +26 -8
  58. package/dist-docs/reference/runtime.html +24 -5
  59. package/dist-docs/reference/types.html +28 -12
  60. package/dist-docs/reference/utils.html +3 -3
  61. package/dist-docs/simulator/index.html +3 -3
  62. package/package.json +1 -1
  63. package/dist-app/assets/index-awQy0VC0.js +0 -1
  64. package/dist-docs/adr/0001-threshold-mirrors-virtual-wall.html +0 -25
  65. package/dist-docs/adr/0002-threshold-edit-surface-quad-family.html +0 -25
  66. package/dist-docs/agents/domain.html +0 -39
  67. package/dist-docs/agents/issue-tracker.html +0 -25
  68. package/dist-docs/agents/triage-labels.html +0 -25
  69. package/dist-docs/assets/adr_0001-threshold-mirrors-virtual-wall.md.BGtyf9GS.js +0 -1
  70. package/dist-docs/assets/adr_0001-threshold-mirrors-virtual-wall.md.BGtyf9GS.lean.js +0 -1
  71. package/dist-docs/assets/adr_0002-threshold-edit-surface-quad-family.md.BlvHYJT5.js +0 -1
  72. package/dist-docs/assets/adr_0002-threshold-edit-surface-quad-family.md.BlvHYJT5.lean.js +0 -1
  73. package/dist-docs/assets/agents_domain.md.CYB9yWEy.js +0 -15
  74. package/dist-docs/assets/agents_domain.md.CYB9yWEy.lean.js +0 -1
  75. package/dist-docs/assets/agents_issue-tracker.md.CrjzmXmc.js +0 -1
  76. package/dist-docs/assets/agents_issue-tracker.md.CrjzmXmc.lean.js +0 -1
  77. package/dist-docs/assets/agents_triage-labels.md.Cmw0b5xB.js +0 -1
  78. package/dist-docs/assets/agents_triage-labels.md.Cmw0b5xB.lean.js +0 -1
  79. package/dist-docs/assets/chunks/@localSearchIndexroot.Ctil7hF1.js +0 -1
  80. package/dist-docs/assets/chunks/index.010EeCxe.js +0 -744
  81. package/dist-docs/assets/chunks/theme.CUoWj-PI.js +0 -4
  82. package/dist-docs/assets/guide_mcp.md.CabCiX8Z.js +0 -1
  83. package/dist-docs/assets/reference_callbacks.md.Cm_LNx97.js +0 -33
  84. package/dist-docs/assets/reference_config.md.DpjGhNQS.js +0 -247
  85. package/dist-docs/assets/reference_config.md.DpjGhNQS.lean.js +0 -1
  86. package/dist-docs/assets/reference_runtime.md.CE2QTAiD.js +0 -20
  87. package/dist-docs/assets/reference_runtime.md.CE2QTAiD.lean.js +0 -1
  88. /package/dist-docs/assets/{guide_getting-started.md.BKeG0DkW.lean.js → guide_getting-started.md.BCkW3g7r.lean.js} +0 -0
package/dist/index.d.ts CHANGED
@@ -10,6 +10,32 @@ import { TextStyleFontWeight } from 'pixi.js';
10
10
  * 定义了视觉样式、素材资源、交互行为等一次性配置项
11
11
  */
12
12
  export declare type AppConfig = {
13
+ /**
14
+ * 弹性缩放的档位断点(全图共用)
15
+ *
16
+ * 屏幕固定尺寸的元素(房间属性气泡、检测物体图标等)默认在地图缩放时保持
17
+ * 恒定像素大小。弹性缩放在此之上叠一层分档倍数:地图缩到第一个断点以下时
18
+ * 元素略微变小,放大到最后一个断点以上时略微变大,中间保持原状。
19
+ *
20
+ * **断点全图共用,倍数各元素自己给**(见 `room.elasticFactors`、
21
+ * `detectedObject.elasticFactors`)。共用断点保证所有元素在同一刻切档,
22
+ * 否则捏合时气泡和图标会错开变化。
23
+ */
24
+ elasticScale: {
25
+ /**
26
+ * 档位断点,升序排列。`n` 个断点划出 `n + 1` 档。
27
+ *
28
+ * 边界归属**刻意不对称**:`s <= 断点[0]` 归最低档,`s >= 断点[末]` 归最高档,
29
+ * 恰好压在中间某个断点上归上一档。若把 `interaction.zoomRange.max` 设成正好
30
+ * 等于最末断点,捏到顶时会稳定落在最高档。
31
+ *
32
+ * 断点应落在 `interaction.zoomRange` 区间内,否则该档永不触发。
33
+ *
34
+ * @defaultValue [1, 5]
35
+ */
36
+ breakpoints: number[]
37
+ }
38
+
13
39
  /** 全局配置 */
14
40
  global: {
15
41
  /** 容器距离顶部位置 */
@@ -61,6 +87,35 @@ export declare type AppConfig = {
61
87
  freeColor: ColorSource
62
88
  /** 地图自适应时的偏移量(像素) */
63
89
  autoFitOffset?: { x: number; y: number }
90
+ /**
91
+ * 地图美化(Beautify)参数,配合 `runtime.enableBeautify` 使用。
92
+ *
93
+ * 只暴露开发者能凭直觉调整的旋钮:外壳描边样式(`borderWidth` /
94
+ * `shellLightenRatio`)与墙线吸附强度(`wallSnapTolerance`)。RDP 简化容差、
95
+ * 凹凸抹平尺寸、回退膨胀阈值属于算法内部标定参数,已下沉为内部常量、不再
96
+ * 暴露为配置(2026-07-23 收窄)。门口推断(Doorway inference)同理——随美化
97
+ * 自动运行,参数为内部常量(原 `doorway` 子开关已于 2026-07-22 移除)。
98
+ */
99
+ beautify: {
100
+ /**
101
+ * 外壳规整档:`'faithful'`(缺省)外壳紧贴原始轮廓,未测绘到的空洞原样
102
+ * 保留;`'boxy'` 花掉一份面积预算换更少的边,房间趋向规整的矩形 / L 形
103
+ * (空洞被浅色外壳盖住)。两档都只加不减,绝不削掉设备测绘到的区域;
104
+ * 别的房间已测绘的区域也不会被外壳盖住(渲染分层保证,几何上贴身档的
105
+ * 外壳仍可能与邻居交叠)。档位映射到的化简预算是内部标定常量。
106
+ */
107
+ level: 'faithful' | 'boxy'
108
+ /** 外壳边框宽度(像素),边框颜色复用 `map.obstacleColor` */
109
+ borderWidth: number
110
+ /** 外壳浅色调的提亮比例(0 为房间原色,1 为纯白) */
111
+ shellLightenRatio: number
112
+ /**
113
+ * 墙线吸附(wall-snap)容差(地图像素):在原始数据里相邻的房间对,其近平行
114
+ * 外壳边垂直间距不超过此值时吸附到同一条墙线,使相邻外壳零缝隙贴合。
115
+ * 缺省 7;`0` 关闭 wall-snap。相邻性判定复用 `map.adjacencyThreshold`。
116
+ */
117
+ wallSnapTolerance: number
118
+ }
64
119
  }
65
120
 
66
121
  /** 热力图配置 */
@@ -102,6 +157,21 @@ export declare type AppConfig = {
102
157
  inactive: string[]
103
158
  /** 普通状态颜色(非选择模式下使用) */
104
159
  normal?: string[]
160
+ /**
161
+ * 禁用状态(`runtime.disabledRoomIds` 列入的房间)填充色调色板,按四色
162
+ * 索引取用。填单个值即所有禁用房间共用一色;未配置或配置为空数组时回退
163
+ * 到该房间的 `inactive` 色。禁用态优先于选中态,且不受
164
+ * `enableRoomSelection` 影响。
165
+ */
166
+ disabled?: string[]
167
+ /**
168
+ * 美化外壳(Shell)填充色的显式覆盖调色板,按四色索引取用(可选)。
169
+ * 未配置时外壳色由房间基础色向白色按 `map.beautify.shellLightenRatio`
170
+ * 推导(随选择状态变化);配置后外壳直接使用该调色板对应索引的颜色,
171
+ * 覆盖自动推导。仅在 `runtime.enableBeautify` 开启时生效,足迹层始终用
172
+ * 房间基础色,选择态反馈不受影响。修改此项会实时重新着色两层。
173
+ */
174
+ shell?: string[]
105
175
  /** 房间名称颜色 */
106
176
  name: string[]
107
177
  /** 房间名称非激活状态颜色 */
@@ -222,6 +292,14 @@ export declare type AppConfig = {
222
292
  * - 设置为 'auto' 时,文字颜色将自动跟随房间的 active 颜色
223
293
  */
224
294
  color: ColorSource | 'auto'
295
+ /**
296
+ * 圆形序号背景色
297
+ * - 设置为 'auto' 时,背景色跟随房间属性图标的主题色
298
+ * (`room.colors.propertyTheme` / `propertyThemeInactive` /
299
+ * `propertyThemeNormal` 三态)
300
+ * - 设置为固定颜色后与图标颜色解绑,三态一并失效
301
+ */
302
+ backgroundColor: ColorSource | 'auto'
225
303
  /** 字体名称 */
226
304
  fontFamily: string
227
305
  /** 字体粗细 */
@@ -279,24 +357,33 @@ export declare type AppConfig = {
279
357
  /**
280
358
  * 是否启用 RoomInfo 弹性缩放
281
359
  *
282
- * 启用后,RoomInfo 会根据地图缩放程度自动调整大小:
283
- * - 地图缩小到一定程度时,缩小到 elasticMinScale
284
- * - 正常缩放范围内,保持固定大小
285
- * - 地图放大到一定程度时,放大到 elasticMaxScale
360
+ * 启用后,RoomInfo 会按 `elasticScale.breakpoints` 划出的档位调整大小:
361
+ * 地图缩到最低档时缩小、放大到最高档时放大、中间档保持固定大小。
286
362
  */
287
363
  enableElasticScale: boolean
288
364
  /**
289
- * RoomInfo 最小弹性缩放倍数
365
+ * RoomInfo 最小弹性缩放倍数(最低档的倍数)
290
366
  *
291
- * 当地图缩小到一定程度时,RoomInfo 会缩小到此倍数
367
+ * 与 `elasticMaxScale` 一起构成两档式的简写。要控制中间档或使用多于 3 档,
368
+ * 改用 `elasticFactors`。
292
369
  */
293
370
  elasticMinScale: number
294
371
  /**
295
- * RoomInfo 最大弹性缩放倍数
372
+ * RoomInfo 最大弹性缩放倍数(最高档的倍数)
296
373
  *
297
- * 当地图放大到一定程度时,RoomInfo 会放大到此倍数
374
+ * 与 `elasticMinScale` 一起构成两档式的简写。要控制中间档或使用多于 3 档,
375
+ * 改用 `elasticFactors`。
298
376
  */
299
377
  elasticMaxScale: number
378
+ /**
379
+ * RoomInfo 各档倍数,长度须等于 `elasticScale.breakpoints.length + 1`
380
+ *
381
+ * 给了它就以它为准,`elasticMinScale` / `elasticMaxScale` 不再参与。
382
+ * 不给则按 `[elasticMinScale, 1, ..., 1, elasticMaxScale]` 展开。
383
+ *
384
+ * 长度对不上会打 warn 并**整组降级为不启用**(退回纯反向缩放),不会自动补齐。
385
+ */
386
+ elasticFactors?: number[]
300
387
  }
301
388
 
302
389
  /** 路径配置 */
@@ -388,8 +475,6 @@ export declare type AppConfig = {
388
475
  // 地毯材质配置,针对地毯需要不同类型的填充材质的情况,比如羊毛地毯,长毛地毯等等
389
476
  // 优先级比src要高,非必要情况,非必要不要传递,使用src的配置即可
390
477
  material?: { type: number; src: string; opacity: number; scale: number }[]
391
- // 地毯是否支持编辑,默认为false,非必要不要开启,会影响地毯绘制性能
392
- enableEdit?: boolean
393
478
  }
394
479
 
395
480
  /** 机器人配置 */
@@ -544,6 +629,22 @@ export declare type AppConfig = {
544
629
  * - {x: 0.5, y: 1} 表示底部中心(适用于气泡图标)
545
630
  */
546
631
  anchor: Point
632
+ /**
633
+ * 是否启用检测物体图标的弹性缩放
634
+ *
635
+ * 启用后图标会按 `elasticScale.breakpoints` 划出的档位调整大小,
636
+ * 与房间属性气泡在同一刻切档。
637
+ */
638
+ enableElasticScale: boolean
639
+ /**
640
+ * 检测物体图标各档倍数,长度须等于 `elasticScale.breakpoints.length + 1`
641
+ *
642
+ * 倍数与房间属性分开配:图标是小方块、气泡是横向长条,同一个倍数在两者上的
643
+ * 视觉重量不同。倍数乘在最终尺寸上,含单条数据自带的 `width` / `height`。
644
+ *
645
+ * 长度对不上会打 warn 并**整组降级为不启用**(退回纯反向缩放),不会自动补齐。
646
+ */
647
+ elasticFactors: number[]
547
648
  }
548
649
 
549
650
  /** 截图配置 */
@@ -661,19 +762,21 @@ export declare type BaseCustomElementParam = {
661
762
  }
662
763
 
663
764
  /** 区域和地毯配置的基础类型 */
664
- export declare type BaseZoneConfig = {
765
+ export declare type BaseZoneConfig = ZoneBodyStyle & {
665
766
  /** 最小尺寸 (米) */
666
767
  minSize: number
667
768
  /** 最大尺寸 (米),可选。缺省或 ≤ minSize 时不限制。 */
668
769
  maxSize?: number
770
+ /**
771
+ * 区域框中心图标。缺省(`undefined`)时不创建任何 Sprite 子对象。
772
+ *
773
+ * 图标位置实时取四角点的中心(区域容器自身 `rotation` 恒为 0,旋转改的是
774
+ * 四角点),并在地图旋转时反向旋转保持水平;`eventMode` 恒为 `'none'`,
775
+ * 不会挡住区域的体拖拽与点击。
776
+ */
777
+ centerIcon?: ZoneCenterIconConfig
669
778
  /** 图标容器填充颜色 */
670
779
  iconWrapperFillColor: ColorSource
671
- /** 描边颜色 */
672
- strokeColor: ColorSource
673
- /** 描边宽度 */
674
- strokeWidth: number
675
- /** 填充颜色 */
676
- fillColor: ColorSource
677
780
  /** 轮廓偏移 */
678
781
  outlineOffset: number
679
782
  /** 轮廓描边颜色 */
@@ -688,12 +791,39 @@ export declare type BaseZoneConfig = {
688
791
  outlineDashArray: [number, number]
689
792
  /** 是否显示旋转图标 */
690
793
  showRotateButton: boolean
794
+ /**
795
+ * 是否显示删除按钮(编辑态)。缺省 `true`。
796
+ *
797
+ * 纯 UI 显隐,不是能力禁用——按钮隐藏后该按钮通道失效(PIXI 对
798
+ * `visible = false` 的对象跳过命中测试),但元素本体的交互不受影响。
799
+ */
800
+ showDeleteButton?: boolean
801
+ /**
802
+ * 是否显示缩放按钮(编辑态)。缺省 `true`。
803
+ *
804
+ * 对启用了纵横比锁定的地毯,横 / 纵向辅助缩放按钮随本开关一并隐藏。
805
+ */
806
+ showScaleButton?: boolean
807
+ /**
808
+ * 是否显示移动按钮(编辑态)。缺省 `true`。
809
+ *
810
+ * **不禁止平移**:区域本体的拖拽走独立的填充(ControlFill)通道,
811
+ * 隐藏移动按钮只是去掉按钮与它的延长线。
812
+ */
813
+ showMoveButton?: boolean
691
814
  /** 文本颜色 */
692
815
  textColor: ColorSource
693
816
  /** 文本位置 */
694
817
  textPosition: 'top' | 'right' | 'bottom' | 'left'
695
818
  /** 文本偏移 */
696
819
  textOffset: number
820
+ /**
821
+ * 禁用态样式覆盖块(`runtime.disabled*Ids` 列入的元素生效)。
822
+ *
823
+ * 缺省(`undefined`)时禁用态只叠加全局兜底透明度
824
+ * `controls.disabledStyle.opacity`,主体颜色不变。
825
+ */
826
+ disabled?: ZoneDisabledStyle
697
827
  /** 编辑模式样式 */
698
828
  editing: {
699
829
  /** 是否虚线 */
@@ -725,12 +855,19 @@ export declare type Bounds = {
725
855
  /** 地毯配置 */
726
856
  export declare type CarpetConfig = Omit<
727
857
  BaseZoneConfig,
728
- 'strokeColor' | 'strokeWidth'
858
+ 'strokeColor' | 'strokeWidth' | 'disabled'
729
859
  > & {
730
860
  /** 删除图标容器填充颜色,缺省时回退到 iconWrapperFillColor */
731
861
  deleteIconWrapperFillColor?: ColorSource
732
862
  rotateMode: 'step' | 'free'
733
863
  scaleMode: 'free' | 'ratioLocked'
864
+ /**
865
+ * 禁用态样式覆盖块(`runtime.disabledCarpetIds` 列入的地毯生效)。
866
+ *
867
+ * 地毯主体是纹理贴图 + 体填充,没有描边与虚线,故白名单只有 `fillColor`。
868
+ * 缺省时禁用态只叠加全局兜底透明度 `controls.disabledStyle.opacity`。
869
+ */
870
+ disabled?: Partial<Pick<ZoneBodyStyle, 'fillColor'>> & DisabledStyleBase
734
871
  }
735
872
 
736
873
  /** 组件属性类型 */
@@ -739,19 +876,24 @@ export declare type ComponentPropsApp = {
739
876
  app: MapApplicationInstance
740
877
  }
741
878
 
742
- /** 控制层内可排序元素 */
879
+ /**
880
+ * 控制层内可排序元素。
881
+ *
882
+ * 门槛(threshold)不在其中:它是不透明地面元素,画在地面标记层
883
+ * (路径 / 机器人 / 房间名之下),层内顺序固定,不参与控制层排序
884
+ * (见 ADR 0006)。
885
+ */
743
886
  export declare type ControlRenderItem =
744
887
  | 'forbiddenSweepZone'
745
888
  | 'forbiddenMopZone'
746
889
  | 'cleanZone'
747
890
  | 'virtualWall'
748
- | 'threshold'
749
891
  | 'spot'
750
892
  | 'roomAnchor'
751
893
  | 'wayPoint'
752
894
  | 'divider'
753
895
  // Allow any string for custom zone types while keeping IDE autocomplete
754
- // for the seven built-in items via the `(string & {})` trick.
896
+ // for the eight built-in items via the `(string & {})` trick.
755
897
  | (string & {})
756
898
 
757
899
  /**
@@ -790,6 +932,15 @@ export declare type ControlsConfig = {
790
932
  textFontWeight: TextStyleFontWeight
791
933
  /** 控制层内部渲染顺序(从下到上) */
792
934
  renderOrder: ControlRenderItem[]
935
+ /**
936
+ * 禁用态全局兜底样式,只有 `opacity`(唯一跨所有元素类型都成立的视觉
937
+ * 概念,默认 `0.4`)。各类型配置的 `disabled` 块按字段覆盖它;要改颜色
938
+ * 或虚线去类型级。
939
+ */
940
+ disabledStyle: {
941
+ /** 禁用态整体透明度(各类型 `disabled.opacity` 可覆盖) */
942
+ opacity: number
943
+ }
793
944
  /** 禁扫区域配置 */
794
945
  forbiddenSweepZone: ZoneConfig
795
946
  /** 禁拖区域配置 */
@@ -802,6 +953,8 @@ export declare type ControlsConfig = {
802
953
  virtualWall: VirtualWallConfig
803
954
  /** 门槛配置 */
804
955
  threshold: ThresholdConfig
956
+ /** 坡道配置 */
957
+ ramp: RampConfig
805
958
  /** 定点清扫配置 */
806
959
  spot: SpotConfig
807
960
  /**
@@ -886,6 +1039,18 @@ export declare type DetectedObjectParam = {
886
1039
  /** 方向 */
887
1040
  export declare type Direction = 'horizontal' | 'vertical'
888
1041
 
1042
+ /**
1043
+ * 禁用态样式差量的公共部分。
1044
+ *
1045
+ * `opacity` 是唯一跨所有元素类型都成立的视觉概念:叠加在元素根容器上,
1046
+ * 按 PIXI alpha 级联语义与子对象自身透明度相乘。缺省回退全局兜底
1047
+ * `controls.disabledStyle.opacity`。
1048
+ */
1049
+ export declare type DisabledStyleBase = {
1050
+ /** 禁用态整体透明度,缺省回退 `controls.disabledStyle.opacity` */
1051
+ opacity?: number
1052
+ }
1053
+
889
1054
  /** 分割线配置 */
890
1055
  export declare type DividerConfig = {
891
1056
  /** 线条颜色 */
@@ -896,8 +1061,10 @@ export declare type DividerConfig = {
896
1061
  dashLineDashArray: [number, number]
897
1062
  /** 实线线条宽度 */
898
1063
  solidLineWidth: number
899
- /** 端点大小 */
1064
+ /** 端点大小(外接尺寸,菱形取对角线) */
900
1065
  endPointSize: number
1066
+ /** 端点形状 (默认 'circle')。'diamond' 会反向旋转以在地图旋转时保持正菱形 */
1067
+ endPointShape: 'circle' | 'diamond'
901
1068
  /** 端点颜色 */
902
1069
  endPointColor: ColorSource
903
1070
  /** 端点描边颜色 */
@@ -908,6 +1075,17 @@ export declare type DividerConfig = {
908
1075
  hitAreaThickness: number
909
1076
  /** 当分割线完全处在房间外的时候是否重置分割线 */
910
1077
  resetDividerWhenOutOfRoom: boolean
1078
+ /**
1079
+ * 越界判据 (默认 'boundingBox'),同时决定 onDividerOutOfRoom 何时触发与
1080
+ * resetDividerWhenOutOfRoom 何时把线拖回。
1081
+ *
1082
+ * - `'boundingBox'` 宽松:整条线段与房间包围盒完全不相交才算越界。
1083
+ * - `'solidLine'` 严格:算不出有效实线(分割线切不动这个房间)即算越界,
1084
+ * 按房间真实填充判定,端点被拖进房间内部同样算。
1085
+ *
1086
+ * 两者是包含关系——整条线跑出包围盒必然算不出实线,反之不然。
1087
+ */
1088
+ outOfRoomCriterion: 'boundingBox' | 'solidLine'
911
1089
  /** 默认生成的分割线超出房间包围盒的像素值 */
912
1090
  defaultExtension: number
913
1091
  /** 默认生成的分割线方向 */
@@ -934,6 +1112,23 @@ export declare type FurnitureConfig = {
934
1112
  opacity: number
935
1113
  /** 图标容器填充颜色 */
936
1114
  iconWrapperFillColor: ColorSource
1115
+ /**
1116
+ * 是否显示删除按钮(编辑态)。缺省 `true`。
1117
+ *
1118
+ * 纯 UI 显隐,不是能力禁用。
1119
+ */
1120
+ showDeleteButton?: boolean
1121
+ /** 是否显示旋转按钮(编辑态)。缺省 `true`。 */
1122
+ showRotateButton?: boolean
1123
+ /** 是否显示缩放按钮(编辑态)。缺省 `true`。 */
1124
+ showScaleButton?: boolean
1125
+ /**
1126
+ * 是否显示移动按钮(编辑态)。缺省 `true`。
1127
+ *
1128
+ * **不禁止平移**:本体拖拽走元素自身的命中区域,隐藏移动按钮只是去掉
1129
+ * 按钮与它的延长线。
1130
+ */
1131
+ showMoveButton?: boolean
937
1132
  /** 轮廓偏移 */
938
1133
  outlineOffset: number
939
1134
  /** 轮廓描边颜色 */
@@ -962,6 +1157,13 @@ export declare type FurnitureConfig = {
962
1157
  rotateDirection: 'cw' | 'ccw'
963
1158
  /** 缩放时是否锁定宽高比 (默认 false) */
964
1159
  lockAspectRatio: boolean
1160
+ /**
1161
+ * 禁用态样式覆盖块(`runtime.disabledFurnitureIds` 列入的家具生效)。
1162
+ *
1163
+ * 家具主体是纹理贴图,唯一有意义的视觉差量是透明度。禁用透明度叠加在
1164
+ * 家具根容器上,与贴图自身的 `opacity` 相乘。
1165
+ */
1166
+ disabled?: DisabledStyleBase
965
1167
  }
966
1168
 
967
1169
  /** 家具参数 */
@@ -1093,9 +1295,9 @@ export declare type LoggerPayload = {
1093
1295
  ts: number
1094
1296
  }
1095
1297
 
1096
- 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"];
1298
+ export declare const MAP_API_METHODS: readonly ["areRoomsAdjacent", "getAdjacentRoomIds", "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", "setDisabledCustomZones"];
1097
1299
 
1098
- 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"];
1300
+ 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", "onDividerOutOfRoom", "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"];
1099
1301
 
1100
1302
  /**
1101
1303
  * 地图 API 接口定义
@@ -1240,6 +1442,12 @@ export declare interface MapApi {
1240
1442
  * @returns 门槛数据数组(长度已修正,`height` 已补默认值并钳制)
1241
1443
  */
1242
1444
  getThresholds(): ThresholdParam[];
1445
+ /**
1446
+ * 获取当前地图上所有坡道数据
1447
+ *
1448
+ * @returns 坡道数据数组(角点为归一化后的结果)
1449
+ */
1450
+ getRamps(): RampParam[];
1243
1451
  /**
1244
1452
  * 获取当前地图上所有定点清扫数据
1245
1453
  *
@@ -1404,6 +1612,50 @@ export declare interface MapApi {
1404
1612
  offsetX?: number;
1405
1613
  offsetY?: number;
1406
1614
  }): Point[];
1615
+ /**
1616
+ * 基于视口中心生成门槛的四个角点坐标
1617
+ *
1618
+ * 缺省尺寸 1m × 0.15m(长 × 厚)—— 「新建门槛」的初始尺寸,不是配置项;
1619
+ * 需要别的初始尺寸就传 `width` / `height`。传入值会被钳制到
1620
+ * `controls.threshold` 的 `minLength`/`maxLength` 与 `minHeight`/`maxHeight`
1621
+ * (米)区间内。
1622
+ *
1623
+ * @param options - 配置选项
1624
+ * @param options.width - 门槛长度,单位米,默认 1
1625
+ * @param options.height - 门槛厚度,单位米,默认 0.15
1626
+ * @param options.offsetX - X方向像素偏移,支持负数,默认为 0
1627
+ * @param options.offsetY - Y方向像素偏移,支持负数,默认为 0
1628
+ * @returns 四个角点坐标,顺时针顺序:[左上, 右上, 右下, 左下](0→1 为长度
1629
+ * 方向,0→3 为厚度方向),可直接作为 `ThresholdParam.points`
1630
+ */
1631
+ getThresholdPointsByViewportCenter(options?: {
1632
+ width?: number;
1633
+ height?: number;
1634
+ offsetX?: number;
1635
+ offsetY?: number;
1636
+ }): Point[];
1637
+ /**
1638
+ * 基于视口中心生成坡道的四个角点坐标
1639
+ *
1640
+ * 缺省尺寸 0.8m × 0.4m(宽 × 高,高方向即坡向)—— 「新建坡道」的初始尺寸,不是配置项;
1641
+ * 需要别的初始尺寸就传 `width` / `height`。传入值会被钳制到
1642
+ * `controls.ramp` 的 `minWidth`/`maxWidth` 与 `minHeight`/`maxHeight`
1643
+ * (米)区间内。
1644
+ *
1645
+ * @param options - 配置选项
1646
+ * @param options.width - 坡道宽度,单位米,默认 0.8
1647
+ * @param options.height - 坡道高度,单位米,默认 0.4(正好等于 minHeight)
1648
+ * @param options.offsetX - X方向像素偏移,支持负数,默认为 0
1649
+ * @param options.offsetY - Y方向像素偏移,支持负数,默认为 0
1650
+ * @returns 四个角点坐标,顺时针顺序:[左上, 右上, 右下, 左下](0→1 为宽
1651
+ * 方向,0→3 为高方向),可直接作为 `RampParam.points`;坡向为屏幕上方
1652
+ */
1653
+ getRampPointsByViewportCenter(options?: {
1654
+ width?: number;
1655
+ height?: number;
1656
+ offsetX?: number;
1657
+ offsetY?: number;
1658
+ }): Point[];
1407
1659
  /**
1408
1660
  * 基于任意中心点生成矩形的四个顶点坐标
1409
1661
  *
@@ -1450,6 +1702,20 @@ export declare interface MapApi {
1450
1702
  * @returns 是否所有指定的房间都相邻(连通)
1451
1703
  */
1452
1704
  areRoomsAdjacent(roomIds: number[]): boolean;
1705
+ /**
1706
+ * 获取与指定房间相邻的房间 ID 列表
1707
+ *
1708
+ * 支持结构化地图和点阵地图两种协议。判定阈值与 `areRoomsAdjacent` 同为
1709
+ * `config.map.adjacencyThreshold`,结论也一致——
1710
+ * `getAdjacentRoomIds(a)` 含 `b` 等价于 `areRoomsAdjacent([a, b])` 为 true。
1711
+ *
1712
+ * 相邻表一次扫描算出:宿主要得到「与某房间不相邻的房间」(例如房间禁用态
1713
+ * 需要的 `disabledRoomIds`),只需一次调用后取补集。
1714
+ *
1715
+ * @param roomId - 目标房间 ID
1716
+ * @returns 相邻房间 ID 数组(按 ID 升序);房间不存在或地图未就绪时返回空数组
1717
+ */
1718
+ getAdjacentRoomIds(roomId: number): number[];
1453
1719
  /**
1454
1720
  * 判断一个点是否与充电桩或机器人距离小于阈值。
1455
1721
  *
@@ -1687,6 +1953,15 @@ export declare interface MapCallbacks {
1687
1953
  * @param.en id - ID of the deleted threshold
1688
1954
  */
1689
1955
  onRemoveThreshold?: (id: string) => void;
1956
+ /**
1957
+ * @description.zh 点击坡道删除按钮的回调
1958
+ * @description.en Callback when clicking the delete button of ramp
1959
+ * @description.zh 当用户点击编辑态坡道的删除按钮时触发。SDK 不会移除该坡道,宿主更新自己的坡道列表后重绘。
1960
+ * @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.
1961
+ * @param.zh id - 被删除的坡道ID
1962
+ * @param.en id - ID of the deleted ramp
1963
+ */
1964
+ onRemoveRamp?: (id: string) => void;
1690
1965
  /**
1691
1966
  * @description.zh 更新禁扫区域的回调
1692
1967
  * @description.en Callback when updating forbidden sweep zone
@@ -1732,6 +2007,15 @@ export declare interface MapCallbacks {
1732
2007
  * @param.en threshold - Updated threshold data
1733
2008
  */
1734
2009
  onUpdateThreshold?: (threshold: ThresholdParam) => void;
2010
+ /**
2011
+ * @description.zh 更新坡道的回调
2012
+ * @description.en Callback when updating ramp
2013
+ * @description.zh 当用户完成一次坡道编辑操作(旋转 / 缩放 / 移动,或拖拽整体平移)后触发,携带最终几何。
2014
+ * @description.en Triggered after the user finishes a ramp edit (rotate/scale/move, or body drag), carrying the final geometry.
2015
+ * @param.zh ramp - 更新后的坡道数据
2016
+ * @param.en ramp - Updated ramp data
2017
+ */
2018
+ onUpdateRamp?: (ramp: RampParam) => void;
1735
2019
  /**
1736
2020
  * @description.zh 更新定点清扫的回调
1737
2021
  * @description.en Callback when updating spot clean
@@ -1813,6 +2097,15 @@ export declare interface MapCallbacks {
1813
2097
  * @param.en threshold - Clicked threshold data
1814
2098
  */
1815
2099
  onClickThreshold?: (threshold: ThresholdParam) => void;
2100
+ /**
2101
+ * @description.zh 点击坡道回调
2102
+ * @description.en Callback when clicking ramp
2103
+ * @description.zh 点击坡道时触发。常用于「点击进入编辑」(把该 id 加入 editingRampIds)。
2104
+ * @description.en Triggered when the user taps a ramp. Commonly used to enter edit mode (add the id to editingRampIds).
2105
+ * @param.zh ramp - 被点击的坡道数据
2106
+ * @param.en ramp - Clicked ramp data
2107
+ */
2108
+ onClickRamp?: (ramp: RampParam) => void;
1816
2109
  /**
1817
2110
  * @description.zh 点击定点清扫回调
1818
2111
  * @description.en Callback when clicking spot clean
@@ -1858,6 +2151,15 @@ export declare interface MapCallbacks {
1858
2151
  * @param.en divider - Updated divider data
1859
2152
  */
1860
2153
  onUpdateDivider?: (divider: Point[]) => void;
2154
+ /**
2155
+ * @description.zh 分割线拖出房间回调
2156
+ * @description.en Callback when the divider is dragged out of the room
2157
+ * @description.zh 当用户操作分割线结束时,若整条线段与房间包围盒完全不相交则触发。回调携带的是重置前的点,即用户实际拖到的位置;开启 divider.resetDividerWhenOutOfRoom 时,重置后的位置随即由 onUpdateDivider 抛出。该回调只负责告知,与是否自动重置正交——关闭自动重置时同样触发。
2158
+ * @description.en Triggered when a divider operation ends and the whole segment no longer intersects the room bounding box. The payload is the position before reset, i.e. where the user actually dragged it; when divider.resetDividerWhenOutOfRoom is enabled, the position after reset is reported right after by onUpdateDivider. This callback only reports the verdict and is orthogonal to the reset behavior - it fires even when auto reset is disabled.
2159
+ * @param.zh divider - 重置前的分割线数据(用户实际拖到的位置)
2160
+ * @param.en divider - Divider data before reset (where the user actually dragged it)
2161
+ */
2162
+ onDividerOutOfRoom?: (divider: Point[]) => void;
1861
2163
  /**
1862
2164
  * @description.zh 点击地图回调
1863
2165
  * @description.en Callback when clicking map
@@ -1870,8 +2172,8 @@ export declare interface MapCallbacks {
1870
2172
  /**
1871
2173
  * @description.zh 点击地毯回调
1872
2174
  * @description.en Callback when clicking carpet
1873
- * @description.zh 当用户点击地毯区域时触发(需要启用 carpet.enableEdit)。
1874
- * @description.en Triggered when user clicks carpet area (requires carpet.enableEdit to be enabled).
2175
+ * @description.zh 当用户点击地毯区域时触发。
2176
+ * @description.en Triggered when user clicks carpet area.
1875
2177
  * @param.zh carpet - 被点击的地毯信息
1876
2178
  * @param.en carpet - Clicked carpet information
1877
2179
  */
@@ -2166,6 +2468,167 @@ export declare type ProcessedRasterData = {
2166
2468
  totalPixels: number
2167
2469
  }
2168
2470
 
2471
+ /** 坡道配置 */
2472
+ export declare type RampConfig = {
2473
+ /** 底色(不透明 —— 坡道是地面元素,画在路径 / 机器人之下,见 ADR 0006) */
2474
+ fillColor: ColorSource
2475
+ /** 描边颜色 */
2476
+ strokeColor: ColorSource
2477
+ /** 描边线宽(屏幕像素,不随地图缩放) */
2478
+ strokeWidth: number
2479
+ /**
2480
+ * 箭头颜色。默认白色 40% 透明叠在底色上(与 UED 稿一致)——
2481
+ * 这样改 `fillColor` 时箭头会自动跟随,不用两处对着调。
2482
+ */
2483
+ arrowColor: ColorSource
2484
+ /**
2485
+ * 箭头**最小**线宽(屏幕像素,不随地图缩放)。
2486
+ *
2487
+ * 实际线宽取 `实际行距 × arrowThicknessRatio` 与本值中的较大者:正常缩放
2488
+ * 下由比例决定(线与缝的粗细比恒定,观感等于 UED 稿),坡道小到 / 地图
2489
+ * 缩到线要细过本值时由本值兜底,保证箭头不会细成看不见。
2490
+ */
2491
+ arrowThickness: number
2492
+ /**
2493
+ * 箭头线宽相对**实际行距**的比例,UED 稿量得 `3 / 7 ≈ 0.43`。
2494
+ *
2495
+ * 线宽跟着行距走而不是锁在固定像素:行距随坡道尺寸变化,若线宽不跟着长,
2496
+ * 放大地图就会看到又粗又疏的缝里夹着细发丝一样的箭头。按比例算才能任何
2497
+ * 缩放下都是同一张贴纸。
2498
+ */
2499
+ arrowThicknessRatio: number
2500
+ /**
2501
+ * 相邻箭头的**最小**间隙(屏幕像素),沿坡向度量。
2502
+ *
2503
+ * 最小步距 = `arrowThickness + arrowGap`,它是密度上限:箭头永远不会比这
2504
+ * 更挤。地图缩得很小时它会顶掉 {@link RampConfig.arrowDensity} 算出的砖
2505
+ * 尺寸,让砖变大、行数变少,保证箭头不会糊成一片。
2506
+ */
2507
+ arrowGap: number
2508
+ /**
2509
+ * 纹样密度:**短边**上铺几个箭头。UED 稿是方形坡道上 6 个,故默认 6。
2510
+ *
2511
+ * 箭头是一块比例固定的「砖」,而不是拉满坡道宽度的单根折线:砖的尺寸
2512
+ * 取 `短边 / arrowDensity`,再沿坡向铺若干**行**、沿宽方向铺若干**列**。
2513
+ * 因此任何宽高比的坡道看到的都是同一块砖,只是数量不同。
2514
+ *
2515
+ * 若改成「整宽一个箭头 + 固定行数」,折角深浅由宽决定、线宽由高决定,
2516
+ * 两个特征分别挂在两条边上:窄高坡道会退化成胖带子(折角只有线宽的
2517
+ * 1/7),宽矮坡道会退化成细丝配大折角。见 plan record
2518
+ * `docs/records/plans/2026-08-06-ramp-map-element-plan.md`。
2519
+ *
2520
+ * 调小更稀、调大更密;密度还受最小步距 `arrowThickness + arrowGap` 约束。
2521
+ */
2522
+ arrowDensity: number
2523
+ /**
2524
+ * 箭头两臂相对横轴的抬升角度(度),钳制在 `[1, 60]`。
2525
+ *
2526
+ * **不是固定的外凸像素**:外凸量由 `半个砖宽 × tan(角度)` 反推,所以任何
2527
+ * 坡道尺寸、任何地图缩放下箭头形状恒定。若改成固定像素,宽砖上的箭头会
2528
+ * 被摊平成直线。UED 稿量得约 8.7°,默认取 9。
2529
+ */
2530
+ arrowAngle: number
2531
+ /** 箭头区域相对坡道边缘的内缩(屏幕像素),箭头不贴边 */
2532
+ arrowInset: number
2533
+ /** 最小宽度 (米),绘制与缩放时宽边(顶点 0→1)被钳制到不小于该值 */
2534
+ minWidth: number
2535
+ /** 最大宽度 (米),可选。缺省或 ≤ minWidth 时不限制。 */
2536
+ maxWidth?: number
2537
+ /** 最小高度 (米),绘制与缩放时高边(顶点 0→3)被钳制到不小于该值 */
2538
+ minHeight: number
2539
+ /** 最大高度 (米),可选。缺省或 ≤ minHeight 时不限制。 */
2540
+ maxHeight?: number
2541
+ /** 四角控制按钮图标容器填充颜色(编辑态显示) */
2542
+ iconWrapperFillColor: ColorSource
2543
+ /**
2544
+ * 是否显示删除按钮(编辑态)。缺省 `true`。
2545
+ *
2546
+ * 纯 UI 显隐,不是能力禁用。
2547
+ */
2548
+ showDeleteButton?: boolean
2549
+ /** 是否显示旋转按钮(编辑态)。缺省 `true`。 */
2550
+ showRotateButton?: boolean
2551
+ /** 是否显示缩放按钮(编辑态)。缺省 `true`。 */
2552
+ showScaleButton?: boolean
2553
+ /**
2554
+ * 是否显示移动按钮(编辑态)。缺省 `true`。
2555
+ *
2556
+ * **不禁止平移**:本体拖拽走元素自身的命中区域,隐藏移动按钮只是去掉
2557
+ * 按钮与它的延长线。
2558
+ */
2559
+ showMoveButton?: boolean
2560
+ /** 编辑态轮廓相对坡道边缘的偏移(屏幕像素) */
2561
+ outlineOffset: number
2562
+ /** 编辑态轮廓描边颜色 */
2563
+ outlineStrokeColor: ColorSource
2564
+ /** 编辑态轮廓描边宽度 */
2565
+ outlineStrokeWidth: number
2566
+ /** 编辑态轮廓是否虚线 */
2567
+ outlineDashed: boolean
2568
+ /** 编辑态轮廓虚线数组 */
2569
+ outlineDashArray: [number, number]
2570
+ /** 编辑态轮廓填充颜色 */
2571
+ outlineFillColor: ColorSource
2572
+ /** 尺寸标签(宽×高)文本颜色(编辑态显示) */
2573
+ textColor: ColorSource
2574
+ /** 尺寸标签相对轮廓边缘向外的偏移(屏幕像素) */
2575
+ textOffset: number
2576
+ /**
2577
+ * 禁用态样式覆盖块(`runtime.disabledRampIds` 列入的坡道生效)。
2578
+ *
2579
+ * 白名单只收空闲态真正渲染的坡道本体字段(底色、描边、箭头颜色);
2580
+ * `outline*` / 按钮 / 尺寸文本只在编辑态渲染,类型上不承诺覆盖。坡道
2581
+ * 没有虚线渲染,故无虚线键。缺省时禁用态只叠加全局兜底透明度
2582
+ * `controls.disabledStyle.opacity`。
2583
+ */
2584
+ disabled?: DisabledStyleBase & {
2585
+ /** 禁用态底色 */
2586
+ fillColor?: ColorSource
2587
+ /** 禁用态描边颜色 */
2588
+ strokeColor?: ColorSource
2589
+ /** 禁用态描边线宽(屏幕像素) */
2590
+ strokeWidth?: number
2591
+ /** 禁用态箭头颜色 */
2592
+ arrowColor?: ColorSource
2593
+ }
2594
+ }
2595
+
2596
+ /** 坡道参数 */
2597
+ export declare type RampParam = {
2598
+ /** 坡道ID */
2599
+ id: string
2600
+ /**
2601
+ * 四角坐标(地图像素坐标系),顺时针 左上→右上→右下→左下,与家具 /
2602
+ * 禁区等四边形元素同序:顶点 0→1 为宽(w)方向,0→3 为高(h)方向。
2603
+ *
2604
+ * 坡道的上坡方向由点序自带:垂直于 0→1 边、从 3→2 边指向 0→1 边
2605
+ * (未旋转时即"朝上")。旋转时点集整体旋转,坡向随之旋转 —— 没有独立的
2606
+ * direction 字段。因此点序**不做**长边规范(那会翻转坡向),入口只纠正
2607
+ * 绕向为顺时针、把宽与高分别钳制到 `minWidth`/`maxWidth` 与
2608
+ * `minHeight`/`maxHeight`(米)区间并拉直成标准矩形。`getRamps()` 回吐的
2609
+ * 点集是归一化后的结果,不一定与传入的原始点逐字相同。
2610
+ */
2611
+ points: Point[]
2612
+ }
2613
+
2614
+ /**
2615
+ * 栅格房间的美化几何(仅 `runtime.enableBeautify` 开启时由 MapManager 计算,
2616
+ * 随 `ProcessedRasterData` 一并交给渲染层)。
2617
+ *
2618
+ * 由像素掩膜描环(`traceRoomRing`)后经既有美化管线得到,坐标在像素**角点格**
2619
+ * 坐标系(像素 `(x, y)` 占据 `[x, x+1] × [y, y+1]`),渲染时不做 +0.5 居中偏移
2620
+ * ——描环多边形本就与逐像素矩形逐字节对齐。只有拿到可渲染外壳的房间才有此
2621
+ * 记录;描环失败 / 管线回退的房间与特殊房间保持逐像素原样渲染(ADR 0003/0004)。
2622
+ */
2623
+ export declare type RasterBeautifiedRoom = {
2624
+ /** 美化外壳(Shell)顶点(闭合环,不重复首点),严格包含描环足迹 */
2625
+ shell: Point[]
2626
+ /** 美化足迹(Footprint)顶点:无损阶梯描环本身(逐像素原样,不简化) */
2627
+ footprint: Point[]
2628
+ /** 推断出的门口开口段,落在该房间外壳边上(可选,见 Room.doorways) */
2629
+ doorways?: { start: Point; end: Point }[]
2630
+ }
2631
+
2169
2632
  /**
2170
2633
  * 点阵房间数据
2171
2634
  */
@@ -2225,6 +2688,27 @@ export declare type Room = {
2225
2688
  centerPoint: Point
2226
2689
  /** 颜色索引(用于四色算法) */
2227
2690
  colorIndex?: number
2691
+ /**
2692
+ * 美化外壳(Shell)顶点,仅在 `runtime.enableBeautify` 开启时由
2693
+ * MapManager 写入绘制数据;`roomGeometryMap` 中的原始几何不携带该字段
2694
+ * (原始数据保持数据层权威,见 ADR 0003)
2695
+ */
2696
+ shell?: Point[]
2697
+ /**
2698
+ * 美化足迹(Footprint)顶点:房间原始轮廓的轻度简化环,仅在美化开启且该
2699
+ * 房间携带 `shell` 时由 MapManager 一并写入。渲染层用房间基础色把它填入
2700
+ * 外壳内部并裁剪到外壳,呈现设备实际测绘区域(见 ADR 0003)。与 `shell`
2701
+ * 同样不写回 `roomGeometryMap`。
2702
+ */
2703
+ footprint?: Point[]
2704
+ /**
2705
+ * 推断出的门口开口段(Doorway),落在该房间自身外壳边上。门口推断是美化管线的
2706
+ * 内建默认步骤:仅在 `runtime.enableBeautify` 开启、且该房间共享墙上推断出开口时
2707
+ * 由 MapManager 写入(随美化自动运行,不再需要配置或 runtime 子开关)。渲染层据此
2708
+ * 在这些位置打断外壳边框。门口是派生视觉开口,不是门槛(Threshold),绝不影响门槛
2709
+ * 渲染 / 编辑(见 CONTEXT.md §Beautification、ADR 0003)。
2710
+ */
2711
+ doorways?: { start: Point; end: Point }[]
2228
2712
  }
2229
2713
 
2230
2714
  /**
@@ -2380,6 +2864,14 @@ export declare type RuntimeConfig = {
2380
2864
  * 加入本列表即可。
2381
2865
  */
2382
2866
  editingThresholdIds: string[]
2867
+ /**
2868
+ * 正在编辑的坡道ID列表。
2869
+ *
2870
+ * 列入的坡道显示编辑控件(虚线轮廓、尺寸标签与删除 / 旋转 / 缩放 / 移动
2871
+ * 按钮)并可整体拖拽;未列入的坡道不显示编辑控件,但坡道本身仍可点击
2872
+ * (上抛 `onClickRamp`,宿主可借此实现「点击进入编辑」)。
2873
+ */
2874
+ editingRampIds: string[]
2383
2875
  /** 正在编辑的定点清扫ID列表 */
2384
2876
  editingSpotIds: string[]
2385
2877
  /** 正在编辑的房间锚点ID列表(独立于 editingSpotIds,互不影响) */
@@ -2406,6 +2898,13 @@ export declare type RuntimeConfig = {
2406
2898
  unitLabel: string
2407
2899
  /** 是否显示房间属性 */
2408
2900
  showRoomProperty: boolean
2901
+ /**
2902
+ * 是否显示房间属性的折叠指示器(折叠态的小三角)
2903
+ *
2904
+ * 只控制小三角画不画,不影响折叠能力本身:设为 false 后
2905
+ * `roomPropertyFoldIds` 里的房间依旧折叠,只是折叠态完全不可见。
2906
+ */
2907
+ showRoomPropertyFoldIndicator: boolean
2409
2908
  /** 是否显示房间顺序 */
2410
2909
  showRoomOrder: boolean
2411
2910
  /** 是否显示路径 */
@@ -2426,6 +2925,55 @@ export declare type RuntimeConfig = {
2426
2925
  showCustomCarpets: boolean
2427
2926
  /** 选中的房间ID列表 */
2428
2927
  selectRoomIds: number[]
2928
+ /**
2929
+ * 禁用的房间ID列表
2930
+ *
2931
+ * 列入的房间填充为禁用色(`config.room.colors.disabled`),与
2932
+ * `enableRoomSelection` 无关:不进选择模式也照样置灰。禁用优先于选中——
2933
+ * 房间同时出现在 `selectRoomIds` 与本列表时渲染为禁用色(两个列表本应由
2934
+ * 宿主保证互斥)。
2935
+ *
2936
+ * SDK 不拦截交互:禁用房间照常触发 `onClickRoom`,「点了不响应」由宿主在
2937
+ * 回调里判断并 return。本期只作用于房间填充,房间名 / 属性气泡 / 选中指示器
2938
+ * 不跟随。
2939
+ */
2940
+ disabledRoomIds: number[]
2941
+ /**
2942
+ * 禁用的禁扫区域ID列表。
2943
+ *
2944
+ * 与房间禁用(`disabledRoomIds`,只渲染不拦截)**同名不同义**:元素禁用
2945
+ * 会拦截编辑手势(本体拖拽与删除 / 旋转 / 缩放 / 移动按钮全部失效,编辑
2946
+ * 控件不渲染),但点击照常上抛 `onClick*`(宿主可借此弹「不可编辑」提示)。
2947
+ * 视觉上按空闲态渲染并叠加禁用样式差量(`controls.disabledStyle` 全局
2948
+ * 兜底 + 各类型 `disabled` 块覆盖)。禁用优先于编辑:元素同时出现在
2949
+ * `editing*Ids` 与本列表时按禁用处理,也不会被升到本层顶部。取舍见
2950
+ * ADR 0007;层级规则(编辑中的元素不被任何东西遮挡)见 ADR 0009。
2951
+ *
2952
+ * 以下 8 个 `disabled*Ids` 与 `disabledCustomZoneIds` 语义相同,不再逐个
2953
+ * 复述。
2954
+ */
2955
+ disabledForbiddenSweepZoneIds: string[]
2956
+ /** 禁用的禁拖区域ID列表(语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}) */
2957
+ disabledForbiddenMopZoneIds: string[]
2958
+ /** 禁用的清洁区域ID列表(语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}) */
2959
+ disabledCleanZoneIds: string[]
2960
+ /**
2961
+ * Disabled ids for custom zone types, keyed by zone type. Built-in types
2962
+ * use their own `disabled*ZoneIds` fields. Write through
2963
+ * `setDisabledCustomZones()` — the runtime subscription compares this key's
2964
+ * reference, so in-place nested writes never notify.
2965
+ */
2966
+ disabledCustomZoneIds?: Record<string, string[]>
2967
+ /** 禁用的虚拟墙ID列表(语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}) */
2968
+ disabledVirtualWallIds: string[]
2969
+ /** 禁用的门槛ID列表(语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}) */
2970
+ disabledThresholdIds: string[]
2971
+ /** 禁用的坡道ID列表(语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}) */
2972
+ disabledRampIds: string[]
2973
+ /** 禁用的地毯ID列表(语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds};禁用同时压过 `selectedCarpetIds` 的选中框) */
2974
+ disabledCarpetIds: string[]
2975
+ /** 禁用的家具ID列表(语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}) */
2976
+ disabledFurnitureIds: string[]
2429
2977
  /** 是否显示充电桩预警圈 */
2430
2978
  showChargingStationRing: boolean
2431
2979
  /** 是否显示机器人预警圈 */
@@ -2436,6 +2984,17 @@ export declare type RuntimeConfig = {
2436
2984
  showRobotPulseCircle: boolean
2437
2985
  /** 选中的地毯ID列表 */
2438
2986
  selectedCarpetIds: string[]
2987
+ /**
2988
+ * 是否启用地图美化(Beautify)
2989
+ *
2990
+ * 开启后地图以规整外壳(Shell)展示房间:外壳填充为房间色的浅色调,
2991
+ * 边框使用 `config.map.obstacleColor`。结构化地图上障碍点与自由区域点云
2992
+ * 隐藏,未知房间(id >= 255)不参与美化、按原样渲染;栅格地图上房间
2993
+ * 像素掩膜先描成轮廓再走同一条美化管线(2026-07-28),特殊房间与描环 /
2994
+ * 直角化失败的房间保持逐像素原样渲染。切换开关会从缓存的地图数据重新
2995
+ * 处理并立即重绘。样式与算法参数见 `config.map.beautify`。
2996
+ */
2997
+ enableBeautify: boolean
2439
2998
  }
2440
2999
 
2441
3000
  /** 定点清扫配置 */
@@ -2544,30 +3103,76 @@ export declare type SpotParam = {
2544
3103
 
2545
3104
  /** 门槛配置 */
2546
3105
  export declare type ThresholdConfig = {
2547
- /** 条纹线宽(屏幕像素,不随地图缩放变化) */
3106
+ /**
3107
+ * 条纹线宽,垂直于斜纹方向度量(斜纹角度见 {@link ThresholdConfig.stripeAngle})。
3108
+ *
3109
+ * **单位是条带厚度的比例,不是像素**(0.3 表示线宽为条带厚度的 30%)。
3110
+ * 于是整套纹路跟着条带一起缩放:跨条带的条纹根数、疏密、着色比例在任何
3111
+ * 地图缩放下都不变,薄门槛与厚门槛看起来也是同一张贴纸。
3112
+ */
2548
3113
  stripeWidth: number
2549
- /** 相邻条纹间距(屏幕像素) */
3114
+ /**
3115
+ * 相邻条纹间距,沿条带长度方向度量。**单位同样是条带厚度的比例。**
3116
+ *
3117
+ * 步距 `stripeWidth + stripeGap` 决定疏密:取 0.7 时,一根斜纹横穿条带的
3118
+ * 水平距离约为步距的 `1 / (0.7 × tan(stripeAngle))` 倍。
3119
+ *
3120
+ * 两者不同轴:`stripeWidth` 是垂直于斜纹的线宽,同一根斜纹沿长度方向占
3121
+ * `stripeWidth / sin(stripeAngle)`(45° 时为 `× √2`),所以着色比例约为
3122
+ * `stripeWidth / sin(stripeAngle) / (stripeWidth + stripeGap)`——默认值下
3123
+ * 约 55%。调陡 `stripeAngle` 会让条带变淡,需同步放大 `stripeWidth`。
3124
+ */
2550
3125
  stripeGap: number
3126
+ /**
3127
+ * 斜纹倾斜方向:`'forward'` 为 `/`(沿长度方向向右上),`'backward'` 为
3128
+ * `\`(向右下)。缺省 `'forward'`。厂商之间惯例不一,两种都保留。
3129
+ */
3130
+ stripeDirection: 'forward' | 'backward'
3131
+ /**
3132
+ * 斜纹与条带长度方向的夹角(度)。`45` 是常见的危险胶带角度,`90` 为垂直
3133
+ * 于条带的竖条纹;取值钳制在 `[10, 90]`。
3134
+ *
3135
+ * 注意角度会连带改变疏密与着色:斜纹越陡,横穿条带需要的水平距离越短
3136
+ * (`厚度 / tan(角度)`),同样的步距下穿过条带的条纹越少;同时一根斜纹沿
3137
+ * 长度方向只占 `stripeWidth / sin(角度)`,所以着色比例也会下降。改陡以后
3138
+ * 想维持观感,需要同步调小 `stripeGap`。
3139
+ */
3140
+ stripeAngle: number
2551
3141
  /** 条带边框线宽(屏幕像素) */
2552
3142
  borderWidth: number
2553
3143
  /** 条带圆角半径(屏幕像素,自动不超过条带半厚 / 半长) */
2554
3144
  cornerRadius: number
2555
- /** 可通行门槛样式(默认绿色斜纹) */
3145
+ /** 可通行门槛样式(默认蓝白斜纹) */
2556
3146
  passable: ThresholdStyle
2557
- /** 不可通行门槛样式(默认红色斜纹) */
3147
+ /** 不可通行门槛样式(默认红白斜纹) */
2558
3148
  impassable: ThresholdStyle
2559
- /** 最小长度 (米),绘制与缩放时长度被钳制到不小于该值 */
3149
+ /** 最小长度 (米),绘制与缩放时长边(顶点 0→1)被钳制到不小于该值 */
2560
3150
  minLength: number
2561
3151
  /** 最大长度 (米),可选。缺省或 ≤ minLength 时不限制。 */
2562
3152
  maxLength?: number
2563
- /** 最小高度 (米),绘制与缩放时条带高度被钳制到不小于该值 */
3153
+ /** 最小厚度 (米),绘制与缩放时厚度边(顶点 0→3)被钳制到不小于该值 */
2564
3154
  minHeight: number
2565
- /** 最大高度 (米),可选。缺省或 ≤ minHeight 时不限制。 */
3155
+ /** 最大厚度 (米),可选。缺省或 ≤ minHeight 时不限制。 */
2566
3156
  maxHeight?: number
2567
- /** 数据未携带 height 时的默认条带高度 (米) */
2568
- defaultHeight: number
2569
3157
  /** 四角控制按钮图标容器填充颜色(编辑态显示) */
2570
3158
  iconWrapperFillColor: ColorSource
3159
+ /**
3160
+ * 是否显示删除按钮(编辑态)。缺省 `true`。
3161
+ *
3162
+ * 纯 UI 显隐,不是能力禁用。
3163
+ */
3164
+ showDeleteButton?: boolean
3165
+ /** 是否显示旋转按钮(编辑态)。缺省 `true`。 */
3166
+ showRotateButton?: boolean
3167
+ /** 是否显示缩放按钮(编辑态)。缺省 `true`。 */
3168
+ showScaleButton?: boolean
3169
+ /**
3170
+ * 是否显示移动按钮(编辑态)。缺省 `true`。
3171
+ *
3172
+ * **不禁止平移**:本体拖拽走元素自身的命中区域,隐藏移动按钮只是去掉
3173
+ * 按钮与它的延长线。
3174
+ */
3175
+ showMoveButton?: boolean
2571
3176
  /**
2572
3177
  * 点击热区在条带每一侧向外扩展的可抓边距(屏幕像素,不随地图缩放)。
2573
3178
  * 热区厚度 = 条带高度 + 2 × 该值,因此条带无论多厚都保有固定的可抓边距,
@@ -2586,36 +3191,53 @@ export declare type ThresholdConfig = {
2586
3191
  outlineDashArray: [number, number]
2587
3192
  /** 编辑态轮廓填充颜色 */
2588
3193
  outlineFillColor: ColorSource
2589
- /** 尺寸标签(长×高)文本颜色(编辑态显示) */
3194
+ /** 尺寸标签(长×厚)文本颜色(编辑态显示) */
2590
3195
  textColor: ColorSource
2591
3196
  /** 尺寸标签相对轮廓边缘向外的偏移(屏幕像素) */
2592
3197
  textOffset: number
3198
+ /**
3199
+ * 禁用态样式覆盖块(`runtime.disabledThresholdIds` 列入的门槛生效)。
3200
+ *
3201
+ * 门槛主体是斜纹条带,按通行类型分两套样式,禁用覆盖也按同一结构给:
3202
+ * `passable` / `impassable` 各自可部分覆盖 {@link ThresholdStyle}。条带
3203
+ * 没有虚线渲染,故无虚线键。缺省时禁用态只叠加全局兜底透明度
3204
+ * `controls.disabledStyle.opacity`。
3205
+ */
3206
+ disabled?: DisabledStyleBase & {
3207
+ /** 禁用态的可通行门槛样式覆盖 */
3208
+ passable?: Partial<ThresholdStyle>
3209
+ /** 禁用态的不可通行门槛样式覆盖 */
3210
+ impassable?: Partial<ThresholdStyle>
3211
+ }
2593
3212
  }
2594
3213
 
2595
3214
  /**
2596
3215
  * 门槛参数。
2597
3216
  *
2598
- * 门槛是「中心线 + 高度」的矩形条带元素,用可通行 / 不可通行两种类型标记
2599
- * 机器人能否跨越的通道,渲染为斜纹条带(可通行绿色 / 不可通行红色)。条带
2600
- * 为真实世界尺寸:长度由两端点决定,厚度由 `height` 决定,随地图缩放。
3217
+ * 门槛是四角坐标描述的矩形条带元素,用可通行 / 不可通行两种类型标记机器人
3218
+ * 能否跨越的通道,渲染为白底斜纹条带(可通行蓝白 / 不可通行红白)。条带为真实
3219
+ * 世界尺寸(长度与厚度都由四角坐标决定,随地图缩放)。数据形态与禁区 /
3220
+ * 家具等四边形元素一致 —— 与主流厂商的门槛协议对齐(见 ADR 0005)。
2601
3221
  *
2602
3222
  * 交互由运行时 `editingThresholdIds` 门控:列入的门槛显示编辑控件(虚线
2603
3223
  * 轮廓、尺寸标签与删除 / 旋转 / 缩放 / 移动按钮,与禁区等四边形元素同一套
2604
- * 编辑面),长与高在缩放时各自钳制到 `minLength`/`maxLength` 与
3224
+ * 编辑面),长与厚在缩放时各自钳制到 `minLength`/`maxLength` 与
2605
3225
  * `minHeight`/`maxHeight`(米)区间。编辑结束触发 `onUpdateThreshold`,
2606
3226
  * 点击触发 `onClickThreshold`,删除按钮触发 `onRemoveThreshold`。
2607
3227
  */
2608
3228
  export declare type ThresholdParam = {
2609
3229
  /** 门槛ID */
2610
3230
  id: string
2611
- /** 中心线两端点坐标(起点、终点),与其他元素同为地图像素坐标系 */
2612
- points: [Point, Point]
2613
3231
  /**
2614
- * 条带高度(厚度),单位与 points 相同(地图像素)。缺省时取
2615
- * `controls.threshold.defaultHeight`(米)换算;绘制与缩放时被钳制在
2616
- * `minHeight` / `maxHeight`(米)区间内。
3232
+ * 四角坐标(地图像素坐标系),顺时针 左上→右上→右下→左下,与家具 /
3233
+ * 禁区等四边形元素同序:顶点 0→1 为长度方向,0→3 为厚度方向。
3234
+ *
3235
+ * 入口处会归一化:绕向纠正为顺时针、较长的一条边规范到 0→1、长与厚
3236
+ * 分别钳制到 `minLength`/`maxLength` 与 `minHeight`/`maxHeight`(米)区间,
3237
+ * 再拉直成标准矩形(保留旋转角与中心)。因此 `getThresholds()` 回吐的
3238
+ * 点集是归一化后的结果,不一定与传入的原始点逐字相同。
2617
3239
  */
2618
- height?: number
3240
+ points: Point[]
2619
3241
  /** 门槛类型(可通行 / 不可通行)。缺省为 `passable`(可通行)。 */
2620
3242
  type?: ThresholdType
2621
3243
  }
@@ -2631,19 +3253,48 @@ export declare type ThresholdStyle = {
2631
3253
  /**
2632
3254
  * 门槛类型。
2633
3255
  *
2634
- * - `'passable'`:可通行门槛,机器人可尝试跨越,默认渲染为绿色斜纹条带
2635
- * - `'impassable'`:不可通行门槛,机器人不得跨越,默认渲染为红色斜纹条带
3256
+ * - `'passable'`:可通行门槛,机器人可尝试跨越,默认渲染为蓝白斜纹条带
3257
+ * - `'impassable'`:不可通行门槛,机器人不得跨越,默认渲染为红白斜纹条带
2636
3258
  */
2637
3259
  export declare type ThresholdType = 'passable' | 'impassable'
2638
3260
 
2639
3261
  /** 虚拟墙配置 */
2640
- export declare type VirtualWallConfig = {
2641
- /** 图标容器填充颜色 */
2642
- iconWrapperFillColor: ColorSource
3262
+ /**
3263
+ * 虚拟墙主体绘制样式 —— 空闲态真正渲染的部分(墙体线段)。
3264
+ * 单独成型是为了让禁用态覆盖块({@link VirtualWallDisabledStyle})与本体
3265
+ * 字段同源派生,不会漂移。
3266
+ */
3267
+ export declare type VirtualWallBodyStyle = {
2643
3268
  /** 线条宽度 */
2644
3269
  lineWidth: number
2645
3270
  /** 线条颜色 */
2646
3271
  lineColor: ColorSource
3272
+ }
3273
+
3274
+ export declare type VirtualWallConfig = VirtualWallBodyStyle & {
3275
+ /** 图标容器填充颜色 */
3276
+ iconWrapperFillColor: ColorSource
3277
+ /**
3278
+ * 是否显示删除按钮(编辑态)。缺省 `true`。
3279
+ *
3280
+ * 纯 UI 显隐,不是能力禁用。
3281
+ */
3282
+ showDeleteButton?: boolean
3283
+ /**
3284
+ * 是否显示缩放按钮(编辑态)。缺省 `true`。
3285
+ *
3286
+ * 虚拟墙的这颗按钮是**缩放 + 旋转二合一**(拖动同时改长度与朝向,绕固定
3287
+ * 起点旋转),隐藏它等于同时关掉这两个通道。虚拟墙没有独立的旋转按钮,
3288
+ * 因而不支持 `showRotateButton`。
3289
+ */
3290
+ showScaleButton?: boolean
3291
+ /**
3292
+ * 是否显示移动按钮(编辑态)。缺省 `true`。
3293
+ *
3294
+ * **不禁止平移**:墙体本体的拖拽走线段自身的命中区域,隐藏移动按钮只是
3295
+ * 去掉按钮与它的延长线。
3296
+ */
3297
+ showMoveButton?: boolean
2647
3298
  /** 碰撞区域厚度 */
2648
3299
  hitAreaThickness: number
2649
3300
  /** 轮廓偏移 */
@@ -2666,6 +3317,13 @@ export declare type VirtualWallConfig = {
2666
3317
  minWidth: number
2667
3318
  /** 最大宽度 (米),可选。缺省或 ≤ minWidth 时不限制。 */
2668
3319
  maxWidth?: number
3320
+ /**
3321
+ * 禁用态样式覆盖块(`runtime.disabledVirtualWallIds` 列入的虚拟墙生效)。
3322
+ *
3323
+ * 缺省(`undefined`)时禁用态只叠加全局兜底透明度
3324
+ * `controls.disabledStyle.opacity`,墙体颜色不变。
3325
+ */
3326
+ disabled?: VirtualWallDisabledStyle
2669
3327
 
2670
3328
  /** 编辑模式样式 */
2671
3329
  editing: {
@@ -2683,6 +3341,21 @@ export declare type VirtualWallConfig = {
2683
3341
  }
2684
3342
  }
2685
3343
 
3344
+ /**
3345
+ * 虚拟墙禁用态样式覆盖块。
3346
+ *
3347
+ * 白名单只收空闲态真正渲染的墙体线段字段;`outline*` / 按钮 / 长度文本
3348
+ * 只在编辑态渲染,禁用态按空闲切片显示,类型上不承诺覆盖它们。虚线两键
3349
+ * 覆盖墙体线段的虚实,缺省回退 `normal` 块。
3350
+ */
3351
+ export declare type VirtualWallDisabledStyle = Partial<VirtualWallBodyStyle> &
3352
+ DisabledStyleBase & {
3353
+ /** 禁用态墙体是否虚线,缺省回退 `normal.isDashed` */
3354
+ isDashed?: boolean
3355
+ /** 禁用态墙体虚线数组,缺省回退 `normal.dashArray` */
3356
+ dashArray?: [number, number]
3357
+ }
3358
+
2686
3359
  /** 虚拟墙参数 */
2687
3360
  export declare type VirtualWallParam = {
2688
3361
  /** 虚拟墙ID */
@@ -2693,8 +3366,67 @@ export declare type VirtualWallParam = {
2693
3366
 
2694
3367
  /** 途径点配置 */
2695
3368
  export declare type WayPointConfig = {
3369
+ /**
3370
+ * 途经点形态:
3371
+ * - 'pin': 水滴形图钉(默认,带尖角与序号圆圈)
3372
+ * - 'dot': 矢量圆点(非编辑态绿点,编辑态红点)
3373
+ */
3374
+ shape?: 'pin' | 'dot'
3375
+ /** 圆点形态样式配置(当 shape === 'dot' 时生效) */
3376
+ dot?: {
3377
+ /** 普通态样式 */
3378
+ normal?: WayPointDotStyle
3379
+ /** 编辑态样式 */
3380
+ editing?: WayPointDotStyle
3381
+ }
2696
3382
  /** 是否显示序号 */
2697
3383
  showOrder: boolean
3384
+ /**
3385
+ * 是否允许拖拽移动,默认 true。
3386
+ * 若置为 false,则处于编辑/选中态时仅展示高亮图标与样式,禁止手势拖拽(适用于首页/监控页只读选中场景)
3387
+ */
3388
+ canDrag?: boolean
3389
+ /** 名称标签配置 */
3390
+ nameLabel?: {
3391
+ /** 字体大小 */
3392
+ fontSize: number
3393
+ /** 字体名称 */
3394
+ fontFamily: string
3395
+ /** 字体粗细 */
3396
+ fontWeight: TextStyleFontWeight
3397
+ /** 文本颜色(可被 editing.color / normal.color 覆盖) */
3398
+ color?: ColorSource
3399
+ /** 文本位置,默认 bottom */
3400
+ position?: 'top' | 'right' | 'bottom' | 'left'
3401
+ /** 文本偏移量,默认 4 */
3402
+ offset?: number
3403
+ /** 编辑模式显示配置 */
3404
+ editing?: {
3405
+ /** 是否显示 */
3406
+ visible?: boolean
3407
+ /** 字体颜色 */
3408
+ color?: ColorSource
3409
+ /** 字体大小(默认继承外层 fontSize) */
3410
+ fontSize?: number
3411
+ /** 字体粗细(默认继承外层 fontWeight) */
3412
+ fontWeight?: TextStyleFontWeight
3413
+ /** 字体名称(默认继承外层 fontFamily) */
3414
+ fontFamily?: string
3415
+ }
3416
+ /** 普通模式显示配置 */
3417
+ normal?: {
3418
+ /** 是否显示 */
3419
+ visible?: boolean
3420
+ /** 字体颜色 */
3421
+ color?: ColorSource
3422
+ /** 字体大小(默认继承外层 fontSize) */
3423
+ fontSize?: number
3424
+ /** 字体粗细(默认继承外层 fontWeight) */
3425
+ fontWeight?: TextStyleFontWeight
3426
+ /** 字体名称(默认继承外层 fontFamily) */
3427
+ fontFamily?: string
3428
+ }
3429
+ }
2698
3430
  /** 编辑模式样式 */
2699
3431
  editing: {
2700
3432
  /** 图标资源路径 */
@@ -2755,17 +3487,112 @@ export declare type WayPointConfig = {
2755
3487
  }
2756
3488
  }
2757
3489
 
3490
+ /** 途径点圆点外光晕/聚焦环配置 */
3491
+ export declare type WayPointDotHalo = {
3492
+ /** 光晕半径(外径),默认编辑态 10 (radius + 4) */
3493
+ radius?: number
3494
+ /** 光晕填充颜色,默认继承圆点颜色 */
3495
+ color?: ColorSource
3496
+ /** 光晕透明度 (0 ~ 1),默认 0.2;置为 0 时不绘制光晕 */
3497
+ alpha?: number
3498
+ }
3499
+
3500
+ /** 途径点圆点样式配置 */
3501
+ export declare type WayPointDotStyle = {
3502
+ /** 圆点半径,默认普通态与编辑态均为 6 (保持切换时尺寸稳定) */
3503
+ radius?: number
3504
+ /** 圆点填充颜色,默认普通态 '#00B578' (通透绿),编辑态 '#ff4d4f' (珊瑚红) */
3505
+ color?: ColorSource
3506
+ /** 描边颜色,默认 '#ffffff' */
3507
+ strokeColor?: ColorSource
3508
+ /** 描边宽度,默认 2 */
3509
+ strokeWidth?: number
3510
+ /**
3511
+ * 外光晕/聚焦环配置(可选):
3512
+ * 编辑态默认开启(半径 11,透明度 0.2),增加地图聚焦感与层级感;
3513
+ * 可通过 `halo: false` 或 `{ alpha: 0 }` 显式关闭。
3514
+ */
3515
+ halo?: WayPointDotHalo | false
3516
+ }
3517
+
2758
3518
  /** 途径点参数 */
2759
3519
  export declare type WayPointParam = {
2760
3520
  /** 途径点ID */
2761
3521
  id: string
2762
3522
  /** 点坐标 */
2763
3523
  point: Point
3524
+ /** 途径点展示名称 */
3525
+ name?: string
3526
+ /**
3527
+ * 是否允许拖拽移动,默认继承 WayPointConfig.canDrag(即 true)。
3528
+ * 若置为 false,则即使进入编辑/选中态也仅展示高亮图标与样式,不可拖拽移动(适用于首页/巡航只读选中场景)
3529
+ */
3530
+ canDrag?: boolean
3531
+ }
3532
+
3533
+ /**
3534
+ * Zone 主体绘制样式 —— 空闲态真正渲染的部分(体填充与内框描边)。
3535
+ * 单独成型是为了让禁用态覆盖块({@link ZoneDisabledStyle})与本体字段
3536
+ * 同源派生,不会漂移。
3537
+ */
3538
+ export declare type ZoneBodyStyle = {
3539
+ /** 描边颜色 */
3540
+ strokeColor: ColorSource
3541
+ /** 描边宽度 */
3542
+ strokeWidth: number
3543
+ /** 填充颜色 */
3544
+ fillColor: ColorSource
3545
+ }
3546
+
3547
+ /**
3548
+ * 区域中心图标配置(类型级粒度:同一区域类型的所有实例共用一个图标)。
3549
+ *
3550
+ * 字段口径对齐 {@link SpotConfig} 的 `iconSrc` / `iconSize` / `iconSizeFixed` /
3551
+ * `iconAnchor` 与其 `editing.showIcon` / `normal.showIcon`。
3552
+ */
3553
+ export declare type ZoneCenterIconConfig = {
3554
+ /** 图标资源路径 */
3555
+ src: string
3556
+ /** 图标大小(sizeFixed 时为屏幕像素,否则为地图像素),默认 24 */
3557
+ size?: number
3558
+ /** 图标尺寸是否固定(不跟随地图缩放),默认 true */
3559
+ sizeFixed?: boolean
3560
+ /** 图标锚点(x/y 取同一值),0 为左上、0.5 为居中、1 为右下,默认 0.5 */
3561
+ anchor?: number
3562
+ /** 图标不透明度,默认 1 */
3563
+ opacity?: number
3564
+ /** 编辑态是否显示图标,默认 true */
3565
+ showInEditing?: boolean
3566
+ /** 普通态是否显示图标,默认 true */
3567
+ showInNormal?: boolean
3568
+ /**
3569
+ * 禁用态是否显示图标,缺省回退 `showInNormal`。
3570
+ *
3571
+ * 禁用元素整体变淡时,一枚淡化的类型图标(如禁扫区的禁止标)可能被读成
3572
+ * 「这条规则失效了」——语义含混时用本开关把它藏掉。
3573
+ */
3574
+ showInDisabled?: boolean
2764
3575
  }
2765
3576
 
2766
3577
  /** 区域配置 */
2767
3578
  export declare type ZoneConfig = BaseZoneConfig
2768
3579
 
3580
+ /**
3581
+ * 区域禁用态样式覆盖块。
3582
+ *
3583
+ * 白名单只收空闲态真正渲染的主体绘制字段——`outline*` / 按钮 / 尺寸文本
3584
+ * 只在编辑态渲染,而禁用态按空闲切片显示,覆盖它们不会产生任何效果,
3585
+ * 因此类型上不承诺。虚线两键覆盖内框(zoneBorder)的虚实,缺省回退
3586
+ * `normal` 块。
3587
+ */
3588
+ export declare type ZoneDisabledStyle = Partial<ZoneBodyStyle> &
3589
+ DisabledStyleBase & {
3590
+ /** 禁用态内框是否虚线,缺省回退 `normal.isDashed` */
3591
+ isDashed?: boolean
3592
+ /** 禁用态内框虚线数组,缺省回退 `normal.dashArray` */
3593
+ dashArray?: [number, number]
3594
+ }
3595
+
2769
3596
  /** 区域参数 */
2770
3597
  export declare type ZoneParam = {
2771
3598
  /** 区域ID */
@@ -2787,3 +3614,19 @@ export declare type ZoneParam = {
2787
3614
  export declare type ZoneTypeDefinition = ZoneConfig
2788
3615
 
2789
3616
  export { }
3617
+
3618
+ /**
3619
+ * Minimal `node:fs` surface for the few tests that read source files off disk
3620
+ * (structural invariants like `throttle-cancel-invariant.test.ts`).
3621
+ *
3622
+ * `@types/node` is installed but unreachable: `tsconfig.json` pins `typeRoots`
3623
+ * to `./src/core/@types`, deliberately keeping Node globals out of a browser
3624
+ * SDK's type surface. Shimming the three functions actually used is contained;
3625
+ * widening `typeRoots` would put `process`, `Buffer` and friends in scope for
3626
+ * every `src/` file, where they must never be used.
3627
+ */
3628
+ declare module 'node:fs' {
3629
+ export function readFileSync(path: string, encoding: 'utf8'): string
3630
+ export function readdirSync(path: string): string[]
3631
+ export function statSync(path: string): { isDirectory(): boolean }
3632
+ }