@hy-bricks/canvas 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @hy-bricks/canvas
 
+## [0.6.1] - 2026-06-16 · free-split 编辑控件可见性
+
+free-split 容器编辑控件(分隔条 + 叶 affordance)的显示时机修复 + 常驻开关。非破坏,@hy-bricks 4 包同步升 0.6.1。
+
+### Fixed
+- **选中容器内子组件时,父容器控件不再消失**:`InteractionLayer` 的 divider / leaf overlay 可见集从"仅选中容器自身"改为 ancestor-aware —— 选中实例自身是 free-split 容器、或其**最近 free-split 祖先**、或正在内容拖拽的容器,都渲控件。修"选容器看到分隔条 → 再点容器内子组件调参 → 分隔条秒消失、没法拖"。
+
+### Added
+- **`freeSplitControlsAlways`**(`createCanvasContext` option / `<HyperCardCanvasDesigner>` prop,`boolean | (() => boolean)`,默认 `false`):
+  - `false`(默认,向后兼容)→ 控件按选区显示(上面的 ancestor-aware 口径);
+  - `true` → 编辑态下**所有** free-split 容器的控件常驻显示,不用选 / 不用悬停。
+  - getter 形式 → 跟 prop / ref 实时联动(开关即时翻转,无需重挂)。给不给用户开关是**宿主策略**(SDK 只出可反应的 prop;参考实现见 portal toolbar「常驻控件」开关)。
+- spec `freeSplit-p3b-interaction-layer.spec.ts` 新增 ancestor-aware + 常驻开关用例(canvas test → 1713)。
+
+> 已知小尾(留作后续增强):常驻模式下满内容叶的角落工具条仍 `:hover` 才显(分隔条已常显),详见 `docs/feedback/portal-ui/`。
+
+## [0.6.0] - 2026-06-15 · 公开面收口 + 坑点修复 + 性能 + 级联删除
+
+deliberate API 收口的 minor。从 `@hy-bricks/canvas` 公开面删掉 test-only / 内部符号,并合入本轮审计发现的 free-split / 命令栈 / 数据绑定运行时坑点修复 + 渲染/交互性能 + 重复实现收口。@hy-bricks 4 包同步升 0.6.0。
+
+### ⚠️ BREAKING — 公开面移除 + 行为收紧
+
+- **`removeInstance` 默认级联删除**:删容器实例时连同其全部后代(含 free-split 容器的叶)一并删除,undo 完整恢复整棵子树 + 关联 bindings —— 替代旧"只删自身、子实例留成 missing-parent 孤儿(渲染警告 overlay、存档带垃圾)"行为。需要旧口径的宿主用 `cascadeRemove: false`(`createCanvasContext` option / Designer `:cascade-remove="false"` prop)退回。配套新公开 API:`CanvasHandle.getRemoveImpact(instanceId)` 删除前预检影响面(`{ instanceIds, descendantCount }`),宿主据此自行做确认弹窗 /「已删 N 个 · 可撤销」提示(SDK 不内置弹窗,异步确认不进命令流保 undo 原子性;参考实现见 playground 工作台「删除确认」开关)。
+- 从 `@hy-bricks/canvas` 公开 barrel(及 `dist/index.d.ts`)移除:
+  - `__resetRendererDiagnosticsRegistry` —— 测试隔离 reset(canvas/devtools spec 专用)。仍从 `rendererDiagnosticsRegistry` 源模块导出供 SDK 内部 spec 深路径 import。
+  - `assertNeverBindingSource` / `assertNeverBindingTarget` —— 穷尽检查守门(`(x: never): never`),纯内部 switch default,无 host 用途。留在 `bindingRefs.ts` 内部。
+- **`beginBatch` / `endBatch` 改深度计数器**:此前是单 bool(begin 已 batch 则 idempotent、end 第一次就 flush),嵌套交互线会把多条 action 塌成一条 record / 第二个 endBatch 静默 no-op。改深度计数后嵌套 batch 语义正确。若 host 之前依赖"重复 begin 幂等"的隐式行为需复核(正常成对使用零影响)。
+
+### 🐛 Fixes(本轮审计坑点)
+
+- free-split:结构变更(尤其 merge)+ undo/redo restore 后清陈旧 selection 引用,避免 dividerIndex 越界 / 悬空 leaf 选中。
+- 框选(marquee)命中口径与点击对齐(传 `domBoxLookup`),容器/slot 子实例点击能命中、框选也能命中。
+- 数据绑定运行时:data-preview 模式不再误触发 lifecycle binding 的 target;共享 cacheKey 的订阅被拆时迁移给幸存 binding(不再静默丢更新);`errorPolicy=stop` 在 remount 后正确复位;`invalidate()` 刷新带 params 的 binding 不再丢 params。
+- 命令栈:`updateLayout` 同值 no-op 不再塞空 record(Ctrl+Z 不再撤销"看不见的改动")。
+- dataSource 查询链 trace 可关联(C8):`data-query-started` 与失败时的 `data-query-failed` 现在共用同一个查询链 `chainId`(此前 dataSource 路径不带,host 无法把一次取数的起止关联;event 路径行为不变)。
+
+### ⚡ Perf
+
+- `DocumentStore` 新增 `id→instance` Map 索引,`getInstance` 与写路径从 O(N) 线性扫转 O(1)。
+- hit-test 沿父链比较复用 byId 索引,避免大画布每次点击 O(N²) 退化。
+- `HyperCardPageRenderer` 渲染消除 per-instance 的 `computeParentLayoutMode` / `parentSplitDirectionFor` / `resolveOutlet` 重复求值(整页从 O(N²) 收敛);resize 帧去掉 `JSON` 深拷贝/比对。
+
+### 🧹 Refactor
+
+- NodeSize 合法性规则收口到单一来源(此前 buildRenderPlan / validateInstanceTree / normalize 三份各自实现)。
+- short id 生成、`structuredCloneSafe`、`Rect` 几何类型统一收口(去掉散落的裸 `JSON.parse(JSON.stringify())` 与重复同名类型)。
+- 类型洞:`computeInverse` 构造 inverse payload 去掉 `as never`,恢复 payload 结构检查。
+
+### 依赖
+
+- `@hy-bricks/core@0.6.0`(fixed 组同步)。
+
 ## [0.5.0] - 2026-06-03 · free-split 自由分割布局
 
 新增第 6 种容器布局 `free-split`(递归分割树)+ 渲染/编辑 gate 解耦。@hy-bricks 4 包同步升 0.5.0。
@@ -170,4 +222,4 @@ grep -rn "instance:ready\|onInstanceLifecycle\|getInstanceReady" src/
   - 用了就简化:`handle.on("instance:ready", id => { const c = handle.getCachedBySourceId(src); if (c?.status === "success") handle.getInstanceRuntime(id)?.setDataInput?.(key, c.value) })`
   - workaround(`replayFromCache` / `mountConcurrency:50` / 首屏 reload)**可保留**,SDK 不强制删
 
-  详见 `docs/v1/frontend-sdk/20260523-1648-claude-渲染核心-挂载就绪信号-实施稿-rev1.md`。
+  详见 `docs/archive/development-history/v1/frontend-sdk/20260523-1648-claude-渲染核心-挂载就绪信号-实施稿-rev1.md`。