fix(web): align composer context stack

2026-08-02 12:45:36 +08:00
parent 07202e67ba
commit cd121c636a
23 changed files with 228 additions and 32 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.md
-2026-07-30-composer-context-stack-order.md: 9c269bcaf7fa360b6a5d0e16fd8cda48aa285d66
-2026-07-30-composer-context-stack-order.zh.md: 47288141ea4591b29adde0f85e810fc797740488
+2026-07-30-composer-context-stack-order.md: 150225ce27fa8459703170622cef754b7694e2fc
+2026-07-30-composer-context-stack-order.zh.md: f13ffc3c1136707a86ba5636a5b69304a132df01
@@ -10,7 +10,7 @@ Goal, Todo, and Queue contribute independently to the same `conversation.input.d

 ## Decision

-The composer context stack has one canonical ascending order: Goal at `0`, Todo at `10`, and Queue at `20`, followed by the composer bar outside the list. The gaps leave room for future entries to declare their intended position without relying on plugin activation order.
+The [Todo-first alignment decision](2026-08-02-todo-first-composer-context-order.md) owns the current ascending order. This note retains the stack contract around that order: numeric gaps leave room for future entries to declare their intended position without relying on plugin activation order, and the composer bar follows the list.

 `ConversationRoot` owns the 6px space between independent context cards. Goal is a standalone 752×36px card and collapsed Todo is a standalone 752×44px card. Queue is the terminal dock entry: its 776px wrapper contains the same 752px panel column and subtracts the shared gap plus a named 5px layout overlap, so the later composer card paints over only the queue edge. Empty entries render null and consume no gap.

@@ -18,7 +18,7 @@ The order and overlap are separate contracts. Registration order establishes sem

 ## Verification

-Registration tests pin all three order values. Browser screenshots cover the full Goal/Todo/Queue matrix, Goal+Todo without Queue, and Queue alone; together they exercise every adjacency: Goal–Todo, Todo–Queue, and Queue–Composer.
+Registration tests pin all three order values. The keyless Queue browser scenario renders Todo, Goal, and Queue together, pins their accessibility order, and checks their visible card edges; focused Goal and Queue scenarios cover their independent states.

 ## Alternatives considered

@@ -30,4 +30,4 @@ Registration tests pin all three order values. Browser screenshots cover the ful

 ## Consequences

-The visual hierarchy is stable for every presence combination, and Queue is the only context surface joined to the composer. New input-dock plugins must choose an order relative to Goal `0`, Todo `10`, and Queue `20`; an entry after Queue also requires an explicit decision about which surface owns the composer boundary.
+The visual hierarchy is stable for every presence combination, and Queue is the only context surface joined to the composer. New input-dock plugins must choose an order relative to Todo `0`, Goal `10`, and Queue `20`; an entry after Queue also requires an explicit decision about which surface owns the composer boundary.
@@ -10,7 +10,7 @@ Goal、Todo 与 Queue 独立注册到同一个 `conversation.input.dock` 列表

 ## 决策

-composer 上下文堆栈采用唯一规范的升序排列：Goal 为 `0`，Todo 为 `10`，Queue 为 `20`，随后是位于列表外的 composer bar。顺序值之间的空档使未来条目可以声明预期位置，不必依赖插件激活顺序。
+[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈契约：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。

 `ConversationRoot` 负责独立上下文卡片之间的 6px 间距。Goal 是一张独立的 752×36px 卡片，折叠后的 Todo 是一张独立的 752×44px 卡片。Queue 是末端 dock 条目：其 776px 包装层包含相同的 752px 面板列，并减去共享间距与具名的 5px 布局重叠量，因此后渲染的 composer 卡片只覆盖 Queue 边缘。空条目渲染为 null，不占用间距。

@@ -18,7 +18,7 @@ composer 上下文堆栈采用唯一规范的升序排列：Goal 为 `0`，Todo

 ## 验证

-注册测试固定了三个顺序值。浏览器截图覆盖完整的 Goal／Todo／Queue 组合矩阵、没有 Queue 的 Goal+Todo，以及仅有 Queue 的情况；这些场景共同覆盖全部相邻关系：Goal–Todo、Todo–Queue 与 Queue–Composer。
+注册测试固定了三个顺序值。无密钥 Queue 浏览器场景同时渲染 Todo、Goal 和 Queue，固定它们的无障碍顺序，并检查其可见卡片边缘；聚焦的 Goal 与 Queue 场景覆盖各自的独立状态。

 ## 考虑过的替代方案

@@ -30,4 +30,4 @@ composer 上下文堆栈采用唯一规范的升序排列：Goal 为 `0`，Todo

 ## 后果

-所有存在组合下的视觉层级都保持稳定，Queue 是唯一与 composer 相接的上下文界面。新的 input-dock 插件必须相对于 Goal `0`、Todo `10` 与 Queue `20` 选择顺序；若条目位于 Queue 之后，还必须明确决定由哪个界面负责 composer 边界。
+所有存在组合下的视觉层级都保持稳定，Queue 是唯一与 composer 相接的上下文界面。新的 input-dock 插件必须相对于 Todo `0`、Goal `10` 与 Queue `20` 选择顺序；若条目位于 Queue 之后，还必须明确决定由哪个界面负责 composer 边界。
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.md
+2026-08-02-todo-first-composer-context-order.md: 1d8bd9cfc30069530420e802f935b88b0b2f7cef
+2026-08-02-todo-first-composer-context-order.zh.md: 9324ed666fa33cdbdb324eb732a979344ae4d8a2
@@ -0,0 +1,33 @@
+# Agent Note: Todo-first composer context order
+
+Status: implemented
+
+English | [中文](2026-08-02-todo-first-composer-context-order.zh.md)
+
+## Problem
+
+The composer context stack rendered Goal before Todo even though the Harness design orders the current task plan before its ongoing goal and pending Queue. Todo also used the Queue wrapper's 776px width as its visible card width, while Goal and the Queue panel rendered on the shared 752px card column. The result inverted the intended information hierarchy and left Todo wider than both adjacent panels.
+
+## Decision
+
+The `conversation.input.dock` list uses one ascending product order: Todo at `0`, Goal at `10`, and Queue at `20`, followed by the composer bar outside the list. Registration order remains the semantic source of truth; the renderer does not hardcode known component ids or repair their order with CSS.
+
+Todo, Goal, and the visible Queue panel share the 752px card column inside the 800px composer cap. Queue retains a 776px wrapper with 12px transparent inset on each side because that wrapper owns the composer overlap. Todo is a standalone card rather than a wrapper, so its maximum width subtracts both inset layers directly and exposes the same left and right edges as Goal and the Queue panel.
+
+The [composer stack contract](2026-07-30-composer-context-stack-order.md) continues to own inter-card spacing and Queue's exclusive overlap with the composer. This decision supersedes only that note's Goal-first order.
+
+## Verification
+
+Todo and Goal registration tests pin orders `0` and `10`; Queue remains pinned at `20`. The keyless Queue browser scenario renders all three panels concurrently, records their Todo–Goal–Queue accessibility order, and compares their visible bounding boxes at the desktop viewport before exercising Queue mutations.
+
+## Alternatives considered
+
+**Reorder the known panels inside `ConversationRoot`.** Rejected because `conversation.input.dock` is an extensible ordered list; a hardcoded component inventory would make plugin activation order and rendered order disagree.
+
+**Use CSS `order` to move Todo visually.** Rejected because accessibility and keyboard order must match the visual hierarchy, and the slot ledger already owns semantic order.
+
+**Keep Todo at the Queue wrapper width.** Rejected because the Queue wrapper's transparent inset is layout infrastructure for its composer overlap, not part of the visible panel column.
+
+## Consequences
+
+The standing task plan appears before the ongoing goal, pending Queue work remains closest to the composer, and all three visible cards share one horizontal edge. Future input-dock plugins choose an explicit position relative to Todo `0`, Goal `10`, and Queue `20`; only Queue owns the terminal wrapper overlap.
@@ -0,0 +1,33 @@
+# Agent Note: Todo 优先的 composer 上下文顺序
+
+Status: implemented
+
+[English](2026-08-02-todo-first-composer-context-order.md) | 中文
+
+## 问题
+
+composer 上下文堆栈将 Goal 渲染在 Todo 之前，但 Harness 设计稿把当前任务计划排在进行中的目标和待处理 Queue 之前。Todo 还把 Queue 包装层的 776px 宽度用作自身的可见卡片宽度，而 Goal 和 Queue 面板则渲染在共享的 752px 卡片列上。结果既颠倒了预期的信息层级，也让 Todo 比相邻两个面板更宽。
+
+## 决策
+
+`conversation.input.dock` 列表采用统一的产品顺序，升序依次为 Todo `0`、Goal `10`、Queue `20`，随后是位于列表外的 composer bar。注册顺序仍是语义真源；渲染器不会硬编码已知组件 id，也不会使用 CSS 修正它们的顺序。
+
+Todo、Goal 与可见的 Queue 面板共用 800px composer 宽度上限内的 752px 卡片列。Queue 保留 776px 包装层，并在两侧各留 12px 透明内缩，因为该包装层负责与 composer 重叠。Todo 是独立卡片，而非包装层，因此其最大宽度会直接扣除两层内缩，使左右边缘与 Goal 和 Queue 面板一致。
+
+[composer 堆栈契约](2026-07-30-composer-context-stack-order.md)继续规定卡片间距，以及仅限 Queue 与 composer 重叠。本决策只取代该记录中 Goal 优先的顺序。
+
+## 验证
+
+Todo 与 Goal 的注册测试分别固定顺序 `0` 和 `10`；Queue 仍固定为 `20`。无密钥 Queue 浏览器场景同时渲染三个面板，记录 Todo–Goal–Queue 的无障碍顺序，并在桌面视口下比较其可见边界框，随后再执行 Queue 变更。
+
+## 考虑过的替代方案
+
+**在 `ConversationRoot` 内重新排列已知面板。** 不予采纳，因为 `conversation.input.dock` 是可扩展的有序列表；硬编码的组件清单会使插件激活顺序与渲染顺序不一致。
+
+**使用 CSS `order` 移动 Todo 的视觉位置。** 不予采纳，因为无障碍顺序和键盘顺序必须与视觉层级一致，而 slot 账本已经负责语义顺序。
+
+**让 Todo 保持 Queue 包装层的宽度。** 不予采纳，因为 Queue 包装层的透明内缩是其与 composer 重叠所需的布局基础设施，不属于可见面板列。
+
+## 后果
+
+当前有效的任务计划显示在进行中的目标之前，待处理 Queue 工作仍最靠近 composer，三张可见卡片共用相同的横向边缘。未来的 input-dock 插件必须相对于 Todo `0`、Goal `10` 和 Queue `20` 选择明确位置；仅 Queue 负责末端包装层与 composer 的重叠。