Feedback

Feedback 规范

Feedback 是 Proto UI 的信息通路之一，方向是 Component → User。它承载组件向用户传递的可感知信息，让用户能够感知组件的存在、状态、变化和交互结果。

没有 feedback 通路，用户无法通过 Proto UI 的 portable semantics 感知组件。组件可以接收 props、处理 event、维护 state、向 App Maker 暴露能力，但如果没有任何反馈，User 看不到、听不到、摸不到，也无法理解组件发生了什么。

Feedback 不等同于“渲染”。render 负责产出 template 结构；feedback 负责组件如何被用户感知。很多 feedback 最终会通过视觉呈现实现，但它在语义上是 Component → User 的信息通路，而不是某个 host 样式机制的别名。

Feedback API 遵守 setup / runtime 分离。

setup 期 API 用来声明或计划组件将如何产生反馈。以 feedback.style 为例：

def.feedback.style.use(tw('inline-flex items-center opacity-100'));

这不是立即修改某个真实 host node，而是在 setup 阶段登记 style plan。use() 返回的 unUse 也只用于 setup 期撤销该次贡献；它不是 runtime update 机制，也不是 lifecycle disposer。

runtime 期 API 表达的是运行期反馈副作用。v0 当前公开的是 feedback.style 的 patch escape hatch：

def.lifecycle.onMounted((run) => {
  run.feedback.style.patch(tw('opacity-50'));
});

runtime feedback effect 不得改变 template 逻辑结构或内容。它可以更新反馈，理想情况下只触发 style flush；是否进入 render/update flow 仍由 Lifecycle / runtime update 语义管理。

feedback.style 是当前 v0 编目的视觉反馈 surface。它描述组件应该如何改变自身样貌，让 User 感知组件的状态、变化或交互结果。

def.feedback.style.use(tw('rounded-md bg-primary text-primary-foreground'));

这些 token 是原型作者侧的 Proto UI style token，表达的是原型内部视觉意图。它们不是 DOM class、不是 CSS rule、不是 data-pui-style token，也不要求和最终宿主产物一一对应。

翻译层可以把 style token 映射为 CSS、attribute、样式装饰器、host-private structure，甚至完全不同的宿主机制。只要保持 feedback.style 的语义意图，最终产物的结构由 adapter 或翻译层负责。

作者侧 style token 只能表达样式意图，不能把状态、事件、selector 或 host realization 混进去。

tw('opacity-50'); // valid
tw('hover:opacity-50'); // invalid
tw('data-[open]:opacity-50'); // invalid

禁止 : 不是 parser 能力不足，而是 feedback 通路纯度要求。hover:bg-white 把状态逻辑塞进了 style token；Proto UI 希望这种关系通过更明确的信息通路和 API 表达。

如果要表达“当 hover 时变透明”，推荐路径是用 rule 组合 state、props、context 等信息源与 feedback intent，而不是让 style token 自带状态。adapter 或专门的 rule extension 可以在最终宿主产物中生成 selector 或 data attribute，但那已经是翻译层结果，不再是原型作者侧 style token。

run.feedback.style.patch/suppress/clearPatch 是 runtime-only escape hatch。它不是推荐的动态样式主路径；推荐路径仍然是 rule + feedback + props/state/context。patch 存在是为了处理少数无法自然声明成 rule 的运行期反馈修补。

run.feedback.style.patch(tw('opacity-100'));
run.feedback.style.suppress(tw('bg-primary'));
run.feedback.style.clearPatch();

每个实例只有一份 runtime style patch layer。patch() 写入正向补丁；suppress() 写入负向补丁；同一 semantic group 后写覆盖前写，不同 semantic group 互不影响。clearPatch() 清空 patch layer，使最终结果回到 setup 与 rule 产生的基础 style 语义结果。

patch layer 的位置很关键：

setup style plan
  -> rule style intent
  -> runtime style patch
  -> translation layer
  -> host artifact

也就是说，patch 对 setup/rule 之后的最终可翻译 style 语义结果负责，但不直接覆盖翻译层之后的 host 产物。adapter 必须消费应用 patch 后的 semantic result，而不是绕过 patch 直接消费 setup 或 rule 的中间结果。

Template 允许局部节点携带 style，这是 feedback-only 子结构可以不拆独立原型的一种体现。style 只能激活视觉反馈能力，不能顺便激活 props、event、expose、context 或 state。

如果一个子结构需要独立接收配置、处理事件、暴露能力、共享上下文或维护自己的状态，它就不再只是 feedback-only，通常应该被拆成独立原型。Feedback 的弹性不应被解释为 template 可以嵌套任意原型。

Feedback 的测试映射当前集中在 feedback.style：

这些测试把 feedback.style 从“样式最终长什么样”收敛为“原型作者侧语义 token 如何进入 setup/rule/patch/translation 这条链路”。

• Core 定义信息通路、setup/runtime 与 run handle 基础；Feedback 是其中 Component → User 的具体通路。
• Template 允许节点携带静态 style，但 style 语义由 feedback.style 定义。
• Lifecycle 规定 feedback runtime effect 不应隐式触发 render；style patch 只请求 style flush。
• Rule 不是 feedback 的一部分，但可以表达“当某条件成立时执行 feedback intent”的声明式副作用。
• Props、State、Context 可以作为动态反馈的条件来源；Feedback 负责最终传达给 User 的可感知结果。