docs: clarify layout example dependency and occurrence contracts

examples/flex-constraints.endor

@@ -21,6 +21,7 @@ class Actions {
         self.first.flexBasis = 100
         self.second.flexBasis = 100
         self.first.flex = 1
+        // grow 不清除 shrink 曾设的 flexShrink=1；本例 basis 总量小于可用量，走增长分支，故不影响这里的预期。
         self.second.flex = 3
     }
     // 两项 basis=200 造成缺额，以 flexShrink*basis 分摊；首项 min=150 后第二项继续收缩到90。

examples/global-dependencies.endor

@@ -1,5 +1,6 @@
 // 全局名称依赖示例：paint 读取 color 这个具体名字，而非依赖整个 globals 字典版本。
-// Console 求值 42 仅改变最后结果 _，不应重绘；给 color 赋新值才使绘制失效。
+// Console 求值 42 仅改变最后结果 _，不应重绘；给 color 赋新值才使此处读取失效。
+// 这不排除视口、原生几何或其他被读取的协议依赖触发刷新；本例对比的是 color 与未读取的全局名。
 color = "#ED6A5A"
 // 保持原生几何，覆盖颜色策略，使示例只观察全局读取的依赖粒度。
 class GlobalPaint: RectBlock {

examples/layout-negotiation.endor

@@ -18,6 +18,7 @@ class ArrangedColumn: Column {
         // source_layout 的安排阶段调用覆盖方法，基类利用本轮孩子测量值生成包含全部稳定 slot 的临时结果。
         result = Column.arrange(self, mount, geometry)
         // 只改返回的第一子槽 Bounds.width，宿主会验证槽完整性并据显式分配反推下一轮精确测量约束。
+        // at(0) 只用于挑选返回列表中的首项；该 Bounds 原有的稳定 slot 保持不变，宿主按 slot 而非列表下标关联孩子。
         result.children.at(0).width = self.policy.width
         return result
     }

examples/scroll-axis.endor

@@ -22,7 +22,7 @@ class Actions {
     function both(self: Actions): Unit { self.vertical.axis = "both" }
 }
 paragraph = TextBlock("这里展示的是同一个 TextBlock。左侧只允许纵向滚动，文字会按照这个 Mount 的实际视口宽度换行；右侧只允许横向滚动，文字保留横向展开。对象的文字和业务状态只有一份，每次展示的约束、几何和滚动位置分别保存。修改滚动轴也会重新测量受影响内容，并将已经不再允许的偏移夹回零。布局传播持续到受影响部分稳定，不会按固定跳数丢弃后续更新。这里展示的是同一个 TextBlock，两个视图可以拥有不同的换行结果。")
-// 纵向区域padding后内容宽为244，长文字按此有限宽换行。
+// 构造视口宽 260，左右 padding 各 8 时内容宽为 244；若父分配另行缩窄，则应按该 Mount 实际视口重算。
 vertical = ScrollBlock(260, 140, paragraph)
 vertical.padding = 8
 // 先给左对象设置 vertical，右对象随后独立设 horizontal；同一 paragraph 不保存任何一个父容器的轴策略。

examples/scroll.endor

@@ -25,7 +25,7 @@ firstConnection = first.on("click",actions.click)
 // 三个连接都在创建树时注册一次，第二窗口复用对象不会额外注册或导致一次点击重复计数。
 middleConnection = middle.on("click",actions.click)
 lastConnection = last.on("click",actions.click)
-// 高内容夹有三个按钮与矩形，使固定320x180 scroller产生可观察的横纵滚动范围。
+// 高内容夹有三个按钮与矩形，在获得构造所需的 320×180 分配时产生横纵滚动范围；最终仍受各窗父约束限制。
 body = Column(12,12,first,Painted(520,180,8,"#DCE8FF"),middle,RectBlock(520,180,8,"#E3EFE5"),last)
 scroller = ScrollBlock(320,180,body)
 // body 自然内容大于固定视口，宿主为各 Mount 计算范围；同一 scroller 不需要克隆 body 来独立滚动。

examples/source-hit.endor

@@ -20,6 +20,7 @@ class CircleTarget: RectBlock {
     // 圆内点击递增自身计数并停止向祖先传播；父容器不会为同一次点击再递增。
     function onEvent(self: CircleTarget, event: Event): Unit {
         // 此示例的点击分发选中圆后调用对象方法；stopPropagation 只阻止后续祖先组，不撤销已经执行的捕获处理。
+        // 此覆盖没有按 event.kind 过滤；若从源码派发其他事件，同样会递增 hits 并停止其后续祖先传播。
         self.hits.increment()
         event.stopPropagation()
     }

examples/source-layout.endor

@@ -18,6 +18,7 @@ class MeasuredRect: RectBlock {
     // 此阶段还不能查询最终 bounds，返回值使用 MeasureResult 名义类型。
     function measure(self: MeasuredRect, mount: Mount, constraints: Constraints): MeasureResult {
         // 从当前出现而非共享 rect 查父 Mount，同一 MeasuredRect 换父容器时可读取不同的 metrics。
+        // 读取真实 Mount 上下文时，当前测量缓存会保守判定易变；不能仅因最终宽度只取模型字段就认为结果可跨帧复用。
         parent = mount.parent()
         // 父 Block 需要符合示例的 metrics 约定；MeasureResult 宽高随后仍由宿主按当前 Constraints 检查和钳制。
         return MeasureResult(parent.block.metrics.width, 60)

examples/source-paint.endor

@@ -40,6 +40,7 @@ class RecolorButton: Button {
     // 事件阶段可修改已有业务字段；依赖跟踪检测 tint 变化后重绘两个出现位置。
     function onEvent(self: RecolorButton, event: Event): Unit {
         // 分发器调用 Button 子类的对象方法，无需另写 button.on；这里可写 target，paint 中只能读它。
+        // onEvent 本身不限定 click：本覆盖没有检查 event.kind，其他经对象方法递送的事件也会执行改色。
         self.target.tint = "#526AC7"
     }
 }