feat(motion): 落相变凝固签名动效

Author: Aparencia

app/src/components/Waveform.test.tsx

@@ -13,6 +13,8 @@
  *     （非削波时也染状态戳色 ⇒ W3b 红）。
  *   · W4 零颜色字面量：两件生产件剥注释后 hex 0 命中 ∧ 渲染出的每个着色面都是 `var(--ed-*)`
  *     ⇒ 变异体 = 写 `backgroundColor: "#0d9488"`。
+ *   · （T29 追加）W5 收束：`freeze=1` ⇒ 条高**集合大小 1**、`freeze=0` ⇒ 两组；**被改的内联属性恰
+ *     `transform`**（`height` 在场但不变 ⇒ 收束没动布局属性）⇒ 变异体 = 收束只改 `opacity` / 改用 `height`。
  *
  * 副作用：无（只读磁盘 + 只挂载 jsdom 容器）。边界：jsdom **无排版引擎** ⇒ 本文件判得到
  *   「条数 / 次序 / 色值 / 属性」，**判不到**「波形看起来像波形」（观感面进报告 `## 诚实边界`）。
@@ -22,10 +24,12 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { afterEach, describe, expect, it } from "vitest";
+import { animatedProps } from "../test/motionHarness";
 import Waveform, {
   WAVEFORM_BARS,
   WAVEFORM_CLIP_BARS,
   WAVEFORM_FLOOR_DB,
+  WAVEFORM_GROOVE_SCALE,
   inClipZone,
   litBars,
 } from "./Waveform";
@@ -185,3 +189,42 @@ describe("W4 · 零颜色字面量（色值只在 ui/tokens.css 与 token 生成
     expect(colors.length, "读到 0 个着色面 ⇒ 本条是空真").toBe(6);
   });
 });
+
+/** 逐条条高（`scaleY` 是几何的唯一通道 ⇒ 也是唯一的读数口）。 */
+const barScales = (el: HTMLElement): number[] =>
+  barsOf(el).map((b) => Number.parseFloat(/scaleY\(([^)]+)\)/.exec(b.style.transform)?.[1] ?? "NaN"));
+
+describe("W5 · 收束成直线（T29：受控 `freeze` 0..1）", () => {
+  it("freeze=0 ⇒ 逐序两组条高（点亮 5 条满高 / 其余底槽）· freeze=1 ⇒ 集合大小恰 1", () => {
+    render(<Waveform rms={0.1} clipping={false} bars={8} freeze={0} />);
+    expect(barScales(root()), "采集态的波形：点亮段与底槽段两组高度").toEqual([
+      1, 1, 1, 1, 1, WAVEFORM_GROOVE_SCALE, WAVEFORM_GROOVE_SCALE, WAVEFORM_GROOVE_SCALE,
+    ]);
+    cleanup();
+    render(<Waveform rms={0.1} clipping={false} bars={8} freeze={1} />);
+    const settled = barScales(root());
+    expect(settled, "凝固 = 每条都落到**同一**高度（上沿是一条水平线）").toEqual(
+      Array.from({ length: 8 }, () => WAVEFORM_GROOVE_SCALE),
+    );
+    expect(new Set(settled).size, "集合大小必须是 1").toBe(1);
+    cleanup();
+    render(<Waveform rms={0.1} clipping={false} bars={8} />);
+    expect(barScales(root()), "缺省 freeze=0 ⇒ 既有调用点的渲染逐字不变").toEqual([
+      1, 1, 1, 1, 1, WAVEFORM_GROOVE_SCALE, WAVEFORM_GROOVE_SCALE, WAVEFORM_GROOVE_SCALE,
+    ]);
+  });
+
+  it("收束**只改 `transform`**：freeze 0 → 0.5 的内联属性**增量** ⊆ 白名单，`height` 在场但逐字不变", () => {
+    const inlineOf = (el: HTMLElement): Record<string, string> =>
+      Object.fromEntries(animatedProps(el).map((p) => [p, el.style.getPropertyValue(p)]));
+    const view = render(<Waveform rms={0.1} clipping={false} bars={8} freeze={0} />);
+    const before = barsOf(root()).map(inlineOf);
+    view.rerender(<Waveform rms={0.1} clipping={false} bars={8} freeze={0.5} />);
+    const after = barsOf(root()).map(inlineOf);
+    const changed = [...new Set(after.flatMap((props, i) => Object.keys(props).filter((p) => props[p] !== before[i][p])))];
+    expect(changed, "收束改了 `height`（或别的非合成属性）⇒ 会触发排版").toEqual(["transform"]);
+    expect(Object.keys(after[0]), "`height` 是静态几何基准（在场但不在增量里）").toContain("height");
+    expect(barScales(root())[0], "中途值落在两端之间（不是瞬切）").toBeGreaterThan(WAVEFORM_GROOVE_SCALE);
+    expect(barScales(root())[0]).toBeLessThan(1);
+  });
+});

app/src/components/Waveform.tsx

@@ -17,6 +17,10 @@
  *   计算）；③ 颜色**零字面量**，一律 `var(--ed-*)`（与 `views/session/SessionCardFlowView.tsx` 同一
  *   纪律：色值只在 `ui/tokens.css` 与生成器里）；④ 动效接缝（ADR-033 §4 允许的用途）只声明
  *   `background` 的 micro 档 token 过渡 —— **几何不做 transition**（§8.4「宽度本身不做 transition」）。
+ * @ai-context T29 追加（规格 §8.6 第 3 行「波形收束成直线」）：受控 prop `freeze`（0..1）+ 唯一映射
+ *   `barScale()` —— **几何只经 `scaleY` 表达**（静态 `height: 100%` 只是几何基准，不入动画属性集合）。
+ *   本件**不自建时间线**：编排层（`shell/usePhaseFreeze.ts`，唯一 `startControllable` 调用点）把持有
+ *   的 `freeze` 传进来。缺省 `freeze = 0` ⇒ 既有调用点的渲染逐字不变（T18 的六条判据零改动）。
  */
 import type { CSSProperties, ReactElement } from "react";
 
@@ -42,6 +46,14 @@ export interface WaveformProps {
   readonly bars?: number;
   readonly height?: number;
   readonly testId?: string;
+  /**
+   * 相变**凝固进度**（批 6 T29 · 规格 §8.6 第 3 行「波形收束成直线」）：`0` = 采集态的活波形
+   * （点亮条满高、未点亮条留底槽 ⇒ 两组高度 ⇒ 有波形），`1` = **所有条同一高度**（= 底槽档 ⇒ 上沿
+   * 是一条水平线）。缺省 `0` ⇒ 既有调用点的渲染与 T18 落库时**逐字相同**。
+   * 🔴 只动 `transform` 的 `scaleY`（+ 静态 `height: 100%` 作几何基准）—— **不许动 `height` 的值**
+   * （R8.4 的属性集合审计 / §8.4「不 animate height」）。
+   */
+  readonly freeze?: number;
 }
 
 /**
@@ -60,6 +72,25 @@ export function inClipZone(index: number, bars: number): boolean {
   return index >= bars - WAVEFORM_CLIP_BARS;
 }
 
+/**
+ * 底槽档：未点亮条的静态高度比（相对满高）。**收束的终态与它共用同一个数**（收束 = 一律落到这个
+ * 高度 ⇒ 上沿成一条水平线），所以「波形收束」只引入**一个**几何新数字（R27.1：数字只有一个落点）。
+ */
+export const WAVEFORM_GROOVE_SCALE = 0.28;
+
+/**
+ * 条高（`scaleY`）的**唯一映射**（T29）：
+ *   · `freeze = 0` ⇒ 点亮条 `1` / 未点亮条 `WAVEFORM_GROOVE_SCALE`（两个不同值 ⇒ 波形有起伏）；
+ *   · `freeze ∈ (0,1)` ⇒ 各自向终态线性收拢（对 `freeze` 单调）；
+ *   · `freeze = 1` ⇒ **一律** `WAVEFORM_GROOVE_SCALE`（集合大小 1 ⇒ 收束成直线）。
+ * 全定义域安全：`freeze` 非有限值按 `0`（永不抛、永不把 NaN 漏进 `style`）。
+ */
+export function barScale(lit: boolean, freeze: number): number {
+  const base = lit ? 1 : WAVEFORM_GROOVE_SCALE;
+  const f = Number.isFinite(freeze) ? Math.min(1, Math.max(0, freeze)) : 0;
+  return base + (WAVEFORM_GROOVE_SCALE - base) * f;
+}
+
 /** 条的公共几何 + 动效接缝（色值逐条不同，故在渲染处合并）。 */
 const BAR_STYLE: CSSProperties = {
   flex: 1,
@@ -80,6 +111,7 @@ export default function Waveform({
   bars = WAVEFORM_BARS,
   height = WAVEFORM_HEIGHT,
   testId = "waveform",
+  freeze = 0,
 }: WaveformProps): ReactElement {
   // 条数先归一到非负整数：`Array.from({length:-1})` 本就是空数组，但显式归零让 `data-bars`
   // 与真实条数永远一致（负值 / 小数不会漏进属性）。
@@ -108,6 +140,11 @@ export default function Waveform({
             data-clip={hot ? "true" : "false"}
             style={{
               ...BAR_STYLE,
+              // 几何基准（静态，不是被动画的属性）：满高由 `height` prop 给定的根盒子高度决定，
+              // 条高本身一律交给 `scaleY` 表达 ⇒ 相变收束**不动** `height`（R8.4 / §8.4）。
+              height: "100%",
+              transformOrigin: "bottom",
+              transform: `scaleY(${barScale(on, freeze)})`,
               // 用**长写** `backgroundColor` 而不是 `background` 简写：jsdom 30 的 CSSStyleDeclaration
               // 会把简写里的 `var(...)` 整条丢掉（实测 `style.background === ""`），长写则逐字保真
               // ⇒ 判据读得到真实产出的色值（本批「判据读不到产出 = 假绿」的家族）。

app/src/shell/LiveBar.tsx

@@ -25,6 +25,14 @@
  *   棘轮因**新文件**当场红；且播放/暂停控制在 WAI-ARIA 的惯用做法本就是**换可访问名**而非按下态
  *   （按下态适用于静音一类**模式**开关）。琥珀徽标 = R4.5 逐字点名的「暂停徽标」，也是 T29
  *   「琥珀退去」要作用的那个元素。
+ * @ai-context T29 追加（#3 相变凝固 · R5.3 / R4.5）：本件挂 `usePhaseFreeze(phase)` —— 相位经
+ *   `LiveBarHost` 注入（**可选**槽，缺省 `"capture"` = 本件既有渲染，冻结进度 0）。三处新结构：
+ *   ① 受控 prop `phase`（唯一新槽；`LiveBarProps` 的既有五项一字未动）；
+ *   ② **墨度层** `data-testid="live-ink"`（唯一 GSAP 目标 = 「琥珀退去」的载体；R4.5 点名的 LIVE 仪表与
+ *      暂停徽标都在它里面 —— 徽标是条件渲染，单独作载体在未暂停时会落空）；
+ *   ③ `kind="warn"`：LIVE 仪表本身走 `--ed-due` 族（R4.5 逐字「采集态 LIVE 仪表/暂停徽标的 `--ed-due`
+ *      族元素」）—— 退去只改**墨度**、不改色值。⚠️ 缺省相位下 hook **不建时间线**（相位未变）⇒ 本件
+ *      既有六条判据零改动。
  */
 import { useEffect, useState } from "react";
 import type { ReactElement } from "react";
@@ -33,6 +41,8 @@ import { Button, StatusLine, Text } from "../ui/primitives";
 import { Icon } from "../ui/icons";
 import { fmtMs } from "../utils/fmt";
 import Waveform from "../components/Waveform";
+import { usePhaseFreeze } from "./usePhaseFreeze";
+import type { ShellPhase } from "./shellPhase";
 
 /**
  * 采集态顶栏高度：**消费 T17 落真的新 token**（R4.1）。兜底 58px 与真源同值
@@ -57,6 +67,8 @@ export interface LiveBarProps {
   readonly onTogglePause: () => void;
   readonly onMark: () => void;
   readonly onStop: () => void;
+  /** 当前相位（T29 追加的**可选**槽；缺省 `"capture"` = 本件既有渲染：冻结进度 0、无编排动效）。 */
+  readonly phase?: ShellPhase;
 }
 
 /**
@@ -71,8 +83,11 @@ export default function LiveBar({
   onTogglePause,
   onMark,
   onStop,
+  phase = "capture",
 }: LiveBarProps): ReactElement {
   const [level, setLevel] = useState<AudioLevelPayload>({ rms: 0, clipping: false });
+  // T29：相变凝固的编排（波形按 `barsFreeze` 收束成直线；墨度层由 hook 的 GSAP 目标退到常态档）
+  const { inkRef, barsFreeze } = usePhaseFreeze(phase);
 
   useEffect(() => {
     const unlisten = listen<AudioLevelPayload>("live:audio-level", (e) => {
@@ -100,39 +115,55 @@ export default function LiveBar({
         overflow: "hidden",
       }}
     >
-      {/* 语义（`role="status"`）与基类由 `StatusLine` 原语承载；仪表本体走它的 `action` 纯插槽
-          （该槽**不额外包 DOM、不加类** —— 见 `StatusLine.tsx` 边界④）。 */}
-      <StatusLine
-        kind="info"
-        testId="live-meter"
-        action={
-          <>
-            <Waveform rms={level.rms} clipping={level.clipping} testId="live-waveform" />
-            <Text as="span" size={4} font="mono" tone="ink-2" testId="live-elapsed">
-              {fmtMs(elapsedMs)}
-            </Text>
-            {paused ? (
-              <Text as="span" size={5} tone="due" testId="live-paused-badge">
-                已暂停
-              </Text>
-            ) : null}
-            <Button variant="secondary" size="sm" testId="live-pause" onClick={onTogglePause}
-              icon={<Icon name={paused ? "play" : "pause"} size={16} />}>
-              {paused ? LIVE_PAUSE_LABELS.paused : LIVE_PAUSE_LABELS.running}
-            </Button>
-            <Button variant="ghost" size="sm" testId="live-mark" onClick={onMark}
-              icon={<Icon name="check" size={16} />}>
-              标记
-            </Button>
-            <Button variant="ghost" size="sm" testId="live-stop" onClick={onStop}
-              icon={<Icon name="stop" size={16} />}>
-              停止
-            </Button>
-          </>
-        }
+      {/* 墨度层（T29「琥珀退去」的载体 · 唯一 GSAP 目标）：**新建**的 div，**不声明任何 transition**
+          （类规则或行内 transition 都会与逐帧写入打架：GSAP 每帧写、CSS 再插值 ⇒ 值永远追不上）。
+          它的 `opacity` 由 `usePhaseFreeze` 从 1 退到常态档；采集态（freeze 0）恒为 1 ⇒ 零观感变化。 */}
+      <div
+        ref={inkRef}
+        data-testid="live-ink"
+        style={{ flex: "1 1 auto", minWidth: 0, display: "block" }}
       >
-        LIVE
-      </StatusLine>
+        {/* 语义（`role="status"`）与基类由 `StatusLine` 原语承载；仪表本体走它的 `action` 纯插槽
+            （该槽**不额外包 DOM、不加类** —— 见 `StatusLine.tsx` 边界④）。
+            `kind="warn"` = R4.5 逐字「采集态 LIVE 仪表…的 `--ed-due` 族」：琥珀是**采集态的身份墨**，
+            退去只退墨度（色值仍逐字是 `--ed-due`，见 `motion.css` 的相位块侧锁）。 */}
+        <StatusLine
+          kind="warn"
+          testId="live-meter"
+          action={
+            <>
+              <Waveform
+                rms={level.rms}
+                clipping={level.clipping}
+                testId="live-waveform"
+                freeze={barsFreeze}
+              />
+              <Text as="span" size={4} font="mono" tone="ink-2" testId="live-elapsed">
+                {fmtMs(elapsedMs)}
+              </Text>
+              {paused ? (
+                <Text as="span" size={5} tone="due" testId="live-paused-badge">
+                  已暂停
+                </Text>
+              ) : null}
+              <Button variant="secondary" size="sm" testId="live-pause" onClick={onTogglePause}
+                icon={<Icon name={paused ? "play" : "pause"} size={16} />}>
+                {paused ? LIVE_PAUSE_LABELS.paused : LIVE_PAUSE_LABELS.running}
+              </Button>
+              <Button variant="ghost" size="sm" testId="live-mark" onClick={onMark}
+                icon={<Icon name="check" size={16} />}>
+                标记
+              </Button>
+              <Button variant="ghost" size="sm" testId="live-stop" onClick={onStop}
+                icon={<Icon name="stop" size={16} />}>
+                停止
+              </Button>
+            </>
+          }
+        >
+          LIVE
+        </StatusLine>
+      </div>
     </div>
   );
 }

app/src/shell/PhaseChrome.tsx

@@ -56,7 +56,7 @@ export default function PhaseChrome({ phase, children }: PhaseChromeProps): Reac
       </div>
       {/* 采集层：**恒挂载**（两态叠在同一格才能交叉淡入；条件挂载会让淡出变成硬切） */}
       <div className={PHASE_LIVE_CLASS} data-testid="phase-live" inert={phase !== "capture"}>
-        <LiveBarHost />
+        <LiveBarHost phase={phase} />
       </div>
     </div>
   );
@@ -77,8 +77,11 @@ export default function PhaseChrome({ phase, children }: PhaseChromeProps): Reac
  *     —— 与 `LiveActivityPanel.tsx:130/154/161` 的既有范式同源。
  *     ⚠️ 登记：`live_session_status` 的载荷里**没有** `started_at`（`types/live.ts:36-48` 实测）⇒ 前端
  *     只能用「自己第一次看到 active 的时刻」，与后端会话起点的毫秒级误差属后端事件面（本任务不改后端）。
+ *   · `phase`（T29 追加的**可选**槽）= 本宿主从 `PhaseChrome` 拿到的同一相位值 ⇒ 往下传给 `LiveBar` 的
+ *     相变凝固编排（`usePhaseFreeze`）。缺省 `"capture"`：`LiveBarHost` 单测（T19 的 C4–C6）不传它 ⇒
+ *     冻结进度 0、**不建任何时间线**（相位未变），既有判据零改动。
  */
-export function LiveBarHost(): ReactElement {
+export function LiveBarHost({ phase = "capture" }: { readonly phase?: ShellPhase }): ReactElement {
   const capture = useCaptureControl();
   const active = capture.active;
   const paused = capture.pausedReason !== null;
@@ -99,6 +102,7 @@ export function LiveBarHost(): ReactElement {
     <LiveBar
       elapsedMs={elapsedMs}
       paused={paused}
+      phase={phase}
       onTogglePause={() => {
         void (paused ? capture.resume() : capture.pause());
       }}