@dsh-workbench/shared 0.3.5 → 0.3.7

package/src/components/FormNodes.tsx

@@ -1,7 +1,7 @@
 import type { ReactNode } from '../lib/react.js';
 import { h } from '../lib/react.js';
 import type { FormAction } from './FormActions.js';
-import type { FormField, FormValue } from './FormTypes.js';
+import type { FormField, FormFieldOf, FormValues } from './FormTypes.js';
 import { FormRow } from './FormRows.js';
 
 /**
@@ -9,7 +9,9 @@ import { FormRow } from './FormRows.js';
  * @param fields - 表单的字段清单。
  * @returns 保序的新数组，`visible` 不给或为 `true` 的都在；全不可见时给空数组。
  */
-export function visibleFieldsOf(fields: readonly FormField[]): readonly FormField[] {
+export function visibleFieldsOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
+): readonly FormFieldOf<Values>[] {
   return fields.filter((field) => field.visible !== false);
 }
 
@@ -19,7 +21,7 @@ export function visibleFieldsOf(fields: readonly FormField[]): readonly FormFiel
  * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
  * @returns 出问题的键的清单、按首次出现顺序去重；缺失的键一律记成空串（报的时候印成 `（空 key）`），空表给空数组。
  */
-export function duplicateKeysOf(fields: readonly FormField[]): readonly string[] {
+export function duplicateKeysOf(fields: readonly { readonly key: string }[]): readonly string[] {
   const seen = new Set<string>();
   const duplicated = new Set<string>();
   for (const field of fields) {
@@ -39,7 +41,7 @@ export function duplicateKeysOf(fields: readonly FormField[]): readonly string[]
  * 形式与理由同 `FormActions` 里那颗多出来的 `primary`：装配的小错不该让 `CardBoundary` 把用户的整张卡变空白。
  * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
  */
-export function reportDuplicateKeys(fields: readonly FormField[]): void {
+export function reportDuplicateKeys(fields: readonly { readonly key: string }[]): void {
   const duplicated = duplicateKeysOf(fields);
   if (duplicated.length === 0) return;
   const named = duplicated.map((key) => (key === '' ? '（空 key）' : key));
@@ -54,10 +56,12 @@ export function reportDuplicateKeys(fields: readonly FormField[]): void {
  * @param fields - 表单的字段清单；取的就是它们的 `value`，`value` 是数组的那格（多选）原样带出、不复制。
  * @returns 键为字段 `key`、值为该格 `value` 的表；`fields` 为空时给空表，不是 `undefined`。
  */
-export function formValuesOf(fields: readonly FormField[]): Readonly<Record<string, FormValue>> {
-  const values: Record<string, FormValue> = {};
+export function formValuesOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
+): Readonly<Values> {
+  const values: Record<string, unknown> = {};
   for (const field of fields) values[field.key] = field.value;
-  return values;
+  return values as Readonly<Values>;
 }
 
 /**
@@ -68,19 +72,26 @@ export function formValuesOf(fields: readonly FormField[]): Readonly<Record<stri
  * @param show - 提交过没有；false 时全给 `undefined`，true 时逐格调 `field.validate` 并按真值收。
  * @returns 键为 `key`、值为那句文案或 `undefined` 的表；没给 `validate` 的格子也是 `undefined`。
  */
-export function formProblemsOf(
-  fields: readonly FormField[],
+export function formProblemsOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
   show: boolean,
 ): Readonly<Record<string, ReactNode | undefined>> {
   const values = formValuesOf(fields);
   const problems: Record<string, ReactNode | undefined> = {};
   for (const field of fields) {
-    const found = show ? field.validate?.(field.value, values) : undefined;
+    const found = show ? problemOf(field, values) : undefined;
     problems[field.key] = found ? found : undefined;
   }
   return problems;
 }
 
+function problemOf<K extends string, V, Vals extends object>(
+  field: FormField<K, V, Vals>,
+  values: Readonly<Vals>,
+): ReactNode | undefined {
+  return field.validate?.(field.value, values);
+}
+
 /**
  * 按字段顺序取第一处错误 —— 提交被挡住时要带进视口的就是这一格。
  * 判的是**真值**（与 `formProblemsOf` 同一口径）：假值那种"错误文案"渲染出来本来就是空的，不算错。
@@ -88,19 +99,19 @@ export function formProblemsOf(
  * @param problems - `formProblemsOf` 那张表，也可以是调用点自己拼的（同样按真值判）。
  * @returns 第一格有错的字段；一格都没错时给 `undefined`。
  */
-export function formFirstProblemOf(
-  fields: readonly FormField[],
+export function formFirstProblemOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
   problems: Readonly<Record<string, ReactNode | undefined>>,
-): FormField | undefined {
+): FormFieldOf<Values> | undefined {
   return fields.find((field) => Boolean(problems[field.key]));
 }
 
 /**
  * 提交那一拍的结果：有错就挡住（并点出第一处错在哪一格），没错就把键值表交出去。
  */
-export type FormSubmitOutcome =
-  | { readonly blocked: true; readonly first: FormField }
-  | { readonly blocked: false; readonly values: Readonly<Record<string, FormValue>> };
+export type FormSubmitOutcome<Values extends object = FormValues> =
+  | { readonly blocked: true; readonly first: FormFieldOf<Values> }
+  | { readonly blocked: false; readonly values: Readonly<Values> };
 
 /**
  * 算提交那一拍该干什么 —— `Form` 的提交钮点下去、以及 `<form>` 的 Enter 提交，走的都是它。
@@ -109,7 +120,9 @@ export type FormSubmitOutcome =
  * @returns `blocked: true` 时带上是按字段顺序数第一格有错的字段（拿它去 `revealFirstProblem`）；
  * `blocked: false` 时带上从 `fields` 现取的键值表。空表一定给 `blocked: false` 与空 values。
  */
-export function formSubmitOf(fields: readonly FormField[]): FormSubmitOutcome {
+export function formSubmitOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
+): FormSubmitOutcome<Values> {
   const problems = formProblemsOf(fields, true);
   const first = formFirstProblemOf(fields, problems);
   if (first !== undefined) return { blocked: true, first };
@@ -170,8 +183,8 @@ export function formActionsOf(args: {
  * @param args.busy - 提交中：每格的绑定 `disabled` 为真。
  * @returns `FormRow` 组成的数组；没有可画的格子时给空数组。
  */
-export function formRowsOf(args: {
-  readonly fields: readonly FormField[];
+export function formRowsOf<Values extends object>(args: {
+  readonly fields: readonly FormFieldOf<Values>[];
   readonly problems: Readonly<Record<string, ReactNode | undefined>>;
   readonly showProblem: boolean;
   readonly busy: boolean;
@@ -183,11 +196,22 @@ export function formRowsOf(args: {
       hint: field.hint,
       problem: args.showProblem ? args.problems[field.key] : undefined,
       layout: field.layout,
-    }, field.control({
-      id: `wb-form-${field.key}`,
-      name: field.key,
-      invalid: args.showProblem && Boolean(args.problems[field.key]),
-      disabled: args.busy || field.disabled === true,
-    })),
+    }, controlOf(field, args.problems, args.showProblem, args.busy)),
   );
-}
+}
+
+function controlOf<K extends string, V, Vals extends object>(
+  field: FormField<K, V, Vals>,
+  problems: Readonly<Record<string, ReactNode | undefined>>,
+  showProblem: boolean,
+  busy: boolean,
+): ReactNode {
+  return field.control({
+    id: `wb-form-${field.key}`,
+    name: field.key,
+    invalid: showProblem && Boolean(problems[field.key]),
+    disabled: busy || field.disabled === true,
+    value: field.value,
+    onChange: field.onChange,
+  });
+}

package/src/components/FormRows.css

@@ -24,6 +24,10 @@
   gap: var(--wb-len-6);
 }
 
+.wb-formRows > .wb-formRow[data-layout='stacked'] {
+  grid-template-columns: minmax(0, 1fr);
+}
+
 .wb-formLabel {
   min-width: 0;
   font-size: var(--dsw-font-xs-13-font-size);
@@ -36,12 +40,39 @@
   white-space: normal;
 }
 
+.wb-formRow[data-layout='stacked'] .wb-formHint,
+.wb-formRow[data-layout='stacked'] .wb-formProblem {
+  grid-column: 1 / -1;
+}
+
 .wb-formControl {
   display: flex;
   align-items: center;
   min-width: 0;
 }
 
+.wb-formControl
+  > :where(
+    .wb-selectAnchor,
+    .wb-choiceMenu,
+    input:not(
+      [type='checkbox'],
+      [type='radio'],
+      [type='button'],
+      [type='submit'],
+      [type='reset'],
+      [type='image'],
+      [type='color'],
+      [type='range']
+    ),
+    select,
+    textarea
+  ) {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+}
+
 .wb-formHint {
   grid-column: 2;
   font-size: var(--dsw-font-xxs-12-font-size);

package/src/components/FormRows.test.tsx

@@ -84,11 +84,37 @@ describe('FormRow', () => {
 
 const FORM_CSS = readFileSync(new URL('./FormRows.css', import.meta.url), 'utf8');
 
+function normalize(selector: string): string {
+  return selector
+    .replace(/\s+/g, ' ')
+    .replace(/\(\s+/g, '(')
+    .replace(/\s+\)/g, ')')
+    .trim();
+}
+
+function selectorParts(head: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = '';
+  for (const char of head) {
+    if (char === '(') depth += 1;
+    if (char === ')') depth -= 1;
+    if (char === ',' && depth === 0) {
+      parts.push(normalize(current));
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  parts.push(normalize(current));
+  return parts;
+}
+
 function declarations(selector: string): string[] {
   for (const block of FORM_CSS.split('}')) {
     const [head, ...rest] = block.split('{');
     if (rest.length === 0 || head === undefined) continue;
-    if (head.trim() !== selector) continue;
+    if (!selectorParts(head).includes(normalize(selector))) continue;
     return rest
       .join('{')
       .split(';')
@@ -132,7 +158,51 @@ describe('标签列：同一个 FormRows 共用一列（ADR-0052 §11）', () =>
     );
   });
 
+  it('★ stacked 行在 FormRows 里也压得过 subgrid 与那条回退（同权重、靠后那条赢过的老坑）', () => {
+    expect(declarations(".wb-formRows > .wb-formRow[data-layout='stacked']")).toContain(
+      'grid-template-columns: minmax(0, 1fr)',
+    );
+  });
+
+  it('★ stacked 行里 hint / problem 通栏（它们的 grid-column: 2 会造出隐式第二列）', () => {
+    expect(declarations(".wb-formRow[data-layout='stacked'] .wb-formHint")).toContain(
+      'grid-column: 1 / -1',
+    );
+    expect(declarations(".wb-formRow[data-layout='stacked'] .wb-formProblem")).toContain(
+      'grid-column: 1 / -1',
+    );
+  });
+
   it('★ 不是 FormRow 的子项（分组标题那种）通栏，别被塞进标签那一列', () => {
     expect(declarations('.wb-formRows > :not(.wb-formRow)')).toContain('grid-column: 1 / -1');
   });
 });
+
+const EXCLUDED_INPUT_TYPES = [
+  'checkbox',
+  'radio',
+  'button',
+  'submit',
+  'reset',
+  'image',
+  'color',
+  'range',
+];
+const CONTROL_FILL_SELECTOR = `.wb-formControl > :where(.wb-selectAnchor, .wb-choiceMenu, input:not(${EXCLUDED_INPUT_TYPES.map((one) => `[type='${one}']`).join(', ')}), select, textarea)`;
+
+describe('控件槽那一格：字段控件铺满，宽度不归调用点写（ADR-0052 §13）', () => {
+  it('★ 那一格里的字段控件吃满控件槽：border-box + width 100% + min-width 0', () => {
+    const fill = declarations(CONTROL_FILL_SELECTOR);
+
+    expect(fill).toContain('box-sizing: border-box');
+    expect(fill).toContain('width: 100%');
+    expect(fill).toContain('min-width: 0');
+  });
+
+  it('★ 开关与按钮那一族不在名单里（拉宽一颗 switch、一颗 <input type=submit> 就是另一回事）', () => {
+    for (const type of EXCLUDED_INPUT_TYPES) {
+      expect(CONTROL_FILL_SELECTOR).toContain(`[type='${type}']`);
+    }
+    expect(FORM_CSS).not.toMatch(/\.wb-formControl\s*>\s*\*/);
+  });
+});

package/src/components/FormTypes.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { FormFieldOf, FormProps } from './FormTypes.js';
+
+type Draft = { readonly env: string; readonly branch?: string };
+
+type Submitted = Parameters<FormProps<Draft>['onSubmit']>[0];
+type EnvField = Extract<FormFieldOf<Draft>, { readonly key: 'env' }>;
+type BranchField = Extract<FormFieldOf<Draft>, { readonly key: 'branch' }>;
+type AcceptedKeys = Pick<FormFieldOf<Draft>, 'key'>['key'];
+type StrangerKeyAccepted = { readonly key: 'nope' } extends Pick<FormFieldOf<Draft>, 'key'> ? true : false;
+
+const draft: FormFieldOf<Draft> = {
+  key: 'env',
+  label: '环境',
+  value: 'stage',
+  onChange: (next) => void next.trim(),
+  control: (binding) => binding.value,
+};
+
+describe('Form<Values> 把每一格的键与值钉住（这几条由 tsc 核，`vitest run` 跑的是最后那条 expect）', () => {
+  it('★ 键只取 Values 的键、值只取那一键的类型；会隐藏的键写成可选键，提交表跟着带上 undefined', () => {
+    expectTypeOf<AcceptedKeys>().toEqualTypeOf<'env' | 'branch'>();
+    expectTypeOf<StrangerKeyAccepted>().toEqualTypeOf<false>();
+    expectTypeOf<EnvField['value']>().toEqualTypeOf<string>();
+    expectTypeOf<EnvField['onChange']>().toEqualTypeOf<(next: string) => void>();
+    expectTypeOf<BranchField['value']>().toEqualTypeOf<string | undefined>();
+    expectTypeOf<Submitted>().toEqualTypeOf<Readonly<Draft>>();
+    expectTypeOf<Submitted['branch']>().toEqualTypeOf<string | undefined>();
+    expect(draft.key).toBe('env');
+  });
+});

package/src/components/FormTypes.ts

@@ -2,38 +2,65 @@ import type { ReactNode } from '../lib/react.js';
 import type { FormAction } from './FormActions.js';
 
 /**
- * 一格控件的值：单值（`TextField` / `SelectField` / `ChoiceGroup` 单选），或一组值（`ChoiceGroup` 多选）。
+ * 默认档一格控件的值：单值（`TextField` / `SelectField` / `ChoiceGroup` 单选），或一组值（`ChoiceGroup` 多选）。
+ * 写了 `Form<Values>` 的类型参数之后，每一格的值类型由 `Values[那一格的键]` 定 —— 这个联合只是**没写类型参数**时的默认档。
  */
 export type FormValue = string | readonly string[];
 
 /**
- * `Form` 递给控件那一格的绑定：`id` / `name` / `invalid` / `disabled` 由 `Form` 定，控件只负责接上。
+ * 默认档的 `Values`：键是任意 `string`、值是 `FormValue` —— 不写 `Form<Values>` 的类型参数时就是它，
+ * 于是 `fields` 的键与值都不钉（老写法照旧能编），代价是每格拿到的都是那个联合、要自己收窄。
  */
-export interface FormFieldBinding {
+export type FormValues = Readonly<Record<string, FormValue>>;
+
+/**
+ * `Form` 递给控件那一格的绑定：`id` / `name` / `invalid` / `disabled` 由 `Form` 定；
+ * `value` / `onChange` 就是这一格自己那份配置里的那两个**原样转手**（`Form` 不持有值）——
+ * 控件接上即可，别再自己接 model：值只写在字段配置里那一次。
+ */
+export interface FormFieldBinding<K extends string = string, V = FormValue> {
   readonly id: string;
-  readonly name: string;
+  readonly name: K;
   readonly invalid: boolean;
   readonly disabled: boolean;
+  readonly value: V;
+  readonly onChange: (next: V) => void;
 }
 
 /**
- * 一格字段的配置：键、标签、值、怎么算错（`validate`）、控件本身 —— 排布、时机、阻断都不写在这里，那些归 `Form`。
+ * 一格字段的配置：键、标签、值、值怎么改（`onChange`）、怎么算错（`validate`）、控件本身 ——
+ * 排布、时机、阻断都不写在这里，那些归 `Form`。`value` 与 `onChange` 就在同一格里，`control` 从绑定直接取
+ * （`(binding) => …（{ value: binding.value, onChange: binding.onChange }）`），值不再有第二处。
  * `validate` 是纯函数、同步、只读 `values`：返回**真值**才算这一格错，假值（`undefined` / `null` / `false` / 空串）
  * 一律当"没错"—— 所以 `(value) => value.trim() === '' && '必填'` 这种用 `&&` 算文案的写法是对的，
  * 它的返回值就是错误行那句话。
  */
-export interface FormField {
-  readonly key: string;
+export interface FormField<
+  K extends string = string,
+  V = FormValue,
+  Vals extends object = FormValues,
+> {
+  readonly key: K;
   readonly label: ReactNode;
   readonly hint?: ReactNode | undefined;
   readonly layout?: 'inline' | 'stacked' | undefined;
-  readonly value: FormValue;
+  readonly value: V;
+  readonly onChange: (next: V) => void;
   readonly visible?: boolean | undefined;
   readonly disabled?: boolean | undefined;
-  readonly validate?: (value: FormValue, values: Readonly<Record<string, FormValue>>) => ReactNode | undefined;
-  readonly control: (binding: FormFieldBinding) => ReactNode;
+  readonly validate?: (value: V, values: Readonly<Vals>) => ReactNode | undefined;
+  readonly control: (binding: FormFieldBinding<K, V>) => ReactNode;
 }
 
+/**
+ * 把 `Values` 的每一键映射成一格字段 —— 写 `Form<Values>` 时 `fields` 就是这个联合的数组：
+ * `{ key: 'env', … }` 那一格的 `value` / `onChange` / `validate` 只认 `Values['env']`，
+ * `control` 拿到的绑定也只带它。要"键值都不钉"的松档就干脆别写类型参数（默认档 `FormValues`），别手写这个类型。
+ */
+export type FormFieldOf<Values extends object> = {
+  [K in keyof Values & string]: FormField<K, Values[K], Values>;
+}[keyof Values & string];
+
 /**
  * 提交钮：文案归调用点，位置、禁用与忙态归 `Form`。
  */
@@ -51,15 +78,19 @@ export interface FormCancel {
 }
 
 /**
- * `Form` 的契约：fields 配置进，排布、校验时机、提交阻断、操作区全归组件。
+ * `Form` 的契约：`fields` 配置进，排布、校验时机、提交阻断、操作区全归组件。
+ * `Values` 是**那张值表**的形状（不写就是默认档 `FormValues`）：`fields` 的键只能取它的键，
+ * 每格的 `value` / `onChange` / `validate` 只认它那一键的值类型，`onSubmit` 与 `validate` 第二参收到的也是它。
+ * **会 `visible: false` 的键写成可选键**（`branch?: string`）—— 那一格不渲染、不校验、不进 `values`（规则五），
+ * 可选键让"它可能不在表里"这件事在类型上也成立；永远可见的键照常必填。
  */
-export interface FormProps {
-  readonly fields: readonly FormField[];
-  readonly onSubmit: (values: Readonly<Record<string, FormValue>>) => void;
+export interface FormProps<Values extends object = FormValues> {
+  readonly fields: readonly FormFieldOf<Values>[];
+  readonly onSubmit: (values: Readonly<Values>) => void;
   readonly submit: FormSubmit;
   readonly cancel?: FormCancel | undefined;
   readonly extra?: readonly FormAction[] | undefined;
   readonly busy?: boolean | undefined;
   readonly disabled?: boolean | undefined;
   readonly problem?: ReactNode | undefined;
-}
+}

package/src/components/FormWiring.test.tsx

@@ -7,6 +7,7 @@ function field(key: string, value: FormValue, validate?: FormField['validate']):
     key,
     label: key,
     value,
+    onChange: () => {},
     control: (binding) => `${key}:${binding.id}:${String(binding.invalid)}:${String(binding.disabled)}`,
     ...(validate === undefined ? {} : { validate }),
   };

package/src/components/LongTaskRow.css

@@ -45,4 +45,56 @@
   margin: var(--wb-len-4) 0 0;
   max-height: var(--wb-len-220);
   overflow: auto;
+}
+
+.wb-longTaskStop {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  align-self: center;
+  justify-content: center;
+  width: var(--wb-len-20);
+  height: var(--wb-len-20);
+  padding: 0;
+  margin-left: auto;
+  border: 0.5px solid var(--dsw-alias-border-l2);
+  border-radius: var(--dsw-radius-sm);
+  background: var(--dsw-specific-menu);
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.wb-longTaskStop:hover:not(:disabled),
+.wb-longTaskStop:focus-visible {
+  border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.wb-longTaskStop:disabled {
+  cursor: default;
+}
+
+.wb-longTaskStopArmed,
+.wb-longTaskStopArmed:hover:not(:disabled),
+.wb-longTaskStopArmed:focus-visible {
+  gap: var(--wb-len-4);
+  width: auto;
+  padding: 0 var(--wb-len-7);
+  border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent);
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.wb-longTaskStopLabel {
+  white-space: nowrap;
+  font-size: var(--dsw-font-xxxs-11-font-size);
+  line-height: var(--wb-line-18);
+}
+
+.wb-longTaskStopWhy {
+  margin: 0;
+  font-size: var(--dsw-font-xxxs-11-font-size);
+  line-height: var(--wb-line-16);
+  color: var(--dsw-alias-state-error-primary);
+  overflow-wrap: anywhere;
 }

package/src/components/LongTaskRow.tsx

@@ -1,11 +1,12 @@
-import { longTaskDot, type LongTaskStatus } from '../api/long-task.js';
+import { longTaskDot, longTaskStopPress, longTaskStopStage, LONG_TASK_STOP_ARM_MS, type LongTaskStatus } from '../api/long-task.js';
 import { Link } from './Link.js';
-import { Fragment, h, useState } from '../lib/react.js';
+import { Fragment, h, useEffect, useState } from '../lib/react.js';
 import {
   CodeBlock,
   DisclosureRow,
   IconCodeOutlineRegular,
   IconFlatListOutlineRegular,
+  IconStopFillRegular,
   StateDot,
 } from '@deepseek-ai/dsh-client-ui-primitives';
 import './LongTaskRow.css';
@@ -19,7 +20,22 @@ export interface LongTaskRowLink {
 }
 
 /**
- * `LongTaskRow` 的契约：状态、标题、问题、链接，与两处可展开的原始输出。
+ * `LongTaskRow` 那颗两按停止钮的契约：确认之后真发的那一下、三句词、在飞与失败两态。
+ * `label` 是没上膛时那颗钮的 aria-label（dsh 的词：`停止任务 {label}`）；`askLabel` 是上膛时那颗钮上显示的字（`确认停止`）；
+ * `armedLabel` 是上膛时的 aria-label，不给就用 `askLabel`（`再次点击确认停止`）；`busy` = 这一趟正在被停、钮禁用；
+ * `failed` 给了才在问题那行后面再画一行。
+ */
+export interface LongTaskRowStop {
+  readonly onStop: () => void;
+  readonly label: string;
+  readonly askLabel: string;
+  readonly armedLabel?: string | undefined;
+  readonly busy?: boolean | undefined;
+  readonly failed?: string | null | undefined;
+}
+
+/**
+ * `LongTaskRow` 的契约：状态、标题、问题、链接，两处可展开的原始输出，与最右边那颗可选的停止钮。
  */
 export interface LongTaskRowProps {
   readonly status: LongTaskStatus;
@@ -32,6 +48,7 @@ export interface LongTaskRowProps {
   readonly rawTitle?: string | undefined;
   readonly copyLabel?: string | undefined;
   readonly copiedLabel?: string | undefined;
+  readonly stop?: LongTaskRowStop | undefined;
 }
 
 function RowLink({ href, text }: LongTaskRowLink) {
@@ -45,7 +62,7 @@ function RowLink({ href, text }: LongTaskRowLink) {
 /**
  * 长任务那一行：状态点 + 标题 + 链接，跑失败时把步骤与原始输出收在两处可展开里。
  * 发布、扫描、迁移这类跑得久的事都用它，别自己画进度。
- * @param props.status - `longTaskDot` 认的四态之一，决定状态点颜色与要不要画"失败"那两块。
+ * @param props.status - `longTaskDot` 认的五态之一，决定状态点颜色与要不要画"失败"那两块。
  * @param props.headline - 这一行在干什么（一句话）。
  * @param props.problem - 失败原因；不给不画。
  * @param props.links - 行尾的链接，通常指向产物或日志。
@@ -53,15 +70,38 @@ function RowLink({ href, text }: LongTaskRowLink) {
  * @param props.raw - 原始输出；只在失败时画，且要同时给 `rawTitle` 才成一块可展开。
  * @param props.stepsTitle - 步骤那块展开行的标题；`rawTitle` 同理是原始输出那块。
  * @param props.copyLabel - 复制钮文案：给了才画复制钮；`copiedLabel` 是复制成功后那句。
+ * @param props.stop - 给了才在最右边画那颗两按停止钮；**不给就一个像素都不变**。只在生产方认 `signal` 时给。
  * @returns 一行长任务。
  */
 export function LongTaskRow(props: LongTaskRowProps) {
   const [stepsOpen, setStepsOpen] = useState(false);
   const [rawOpen, setRawOpen] = useState(false);
+  const [armed, setArmed] = useState(false);
   const failed = props.status === 'failed';
   const problem = props.problem ?? '';
   const raw = (props.raw ?? '').trim();
   const steps = props.steps ?? [];
+  const stop = props.stop;
+  const busy = stop?.busy === true;
+  const stopWhy = stop?.failed ?? '';
+
+  useEffect(() => {
+    if (!armed) return undefined;
+    const timer = setTimeout(() => setArmed(false), LONG_TASK_STOP_ARM_MS);
+    return () => clearTimeout(timer);
+  }, [armed]);
+
+  const onStopPress = (): void => {
+    if (stop === undefined) return;
+    const press = longTaskStopPress(longTaskStopStage({ armed, busy }));
+    if (press === 'ignore') return;
+    if (press === 'arm') {
+      setArmed(true);
+      return;
+    }
+    setArmed(false);
+    stop.onStop();
+  };
 
   return (
     <div className="wb-longTask">
@@ -71,8 +111,23 @@ export function LongTaskRow(props: LongTaskRowProps) {
         {(props.links ?? []).map((link) => (
           <RowLink href={link.href} key={`${link.text}@${link.href}`} text={link.text} />
         ))}
+        {stop === undefined ? null : (
+          <button
+            type="button"
+            className={`wb-longTaskStop${armed ? ' wb-longTaskStopArmed' : ''}`}
+            data-stop-state={longTaskStopStage({ armed, busy })}
+            aria-label={armed ? stop.armedLabel ?? stop.askLabel : stop.label}
+            disabled={busy}
+            onClick={onStopPress}
+            onBlur={() => setArmed(false)}
+          >
+            <IconStopFillRegular size={12} />
+            {armed ? <span className="wb-longTaskStopLabel">{stop.askLabel}</span> : null}
+          </button>
+        )}
       </p>
       {problem === '' ? null : <p className="wb-longTaskProblem">{problem}</p>}
+      {stopWhy === '' ? null : <p className="wb-longTaskStopWhy">{stopWhy}</p>}
       {!failed ? null : (
         <Fragment>
           {steps.length === 0 || props.stepsTitle === undefined ? null : (