finding(mobile): `useSpecGesture`'s own `@example` passes a scalar `swipe.direction`, which its declared `SpecSwipeDirection[]` rejects — and the implementation carries the lenient cast that hides it

[baozhoutao]

Found while repairing packages/mobile/README.md for the objectui#5174 UNGATED_DOCS burn-down (batch 14). Out of that PR's scope — its file surface is the README plus the ledger removal — so it is filed here instead of ridden along.

The two halves

1. The shipped @example does not compile. packages/mobile/src/useSpecGesture.ts (around line 70) documents:

config: { type: 'swipe', enabled: true, swipe: { direction: 'left', threshold: 80 } },

SwipeGestureConfig.direction is declared in @object-ui/types as SpecSwipeDirection[] — an ARRAY:

export interface SwipeGestureConfig {
    direction: SpecSwipeDirection[];
    threshold?: number;
    velocity?: number;
}

A reader who copies that example gets TS2322 ('left' is not assignable to SpecSwipeDirection[]). Nothing catches it today: check-doc-snippet-types.mjs reads fenced blocks in Markdown documents, not JSDoc @example blocks in .ts sources, so this example has never been compiled by anything.

2. The implementation reads BOTH shapes, which is why nobody noticed. Same file, the 'swipe' case:

const dir = Array.isArray(config.swipe?.direction)
  ? config.swipe?.direction[0]
  : (config.swipe?.direction as string | undefined);

That is a consumer-side tolerant fallback of exactly the class AGENTS.md commandment #0.1 bans: the declared contract says array, the runtime silently accepts a scalar through an as cast, and the wrong example therefore "works" when hand-tested. Declared-and-not-enforced in one direction, enforced-and-not-declared in the other.

Why the two halves are one card

Repairing only the example leaves the lenient cast, which will let the next author write the scalar again. Removing only the cast turns the shipped example from "will not compile" into "will not compile AND would have thrown"; the example has to move in the same change. Which side is authoritative is a real decision — the array is what the type and the retired spec shape declare, and SWIPE_DIRECTION_MAP[dir] only ever consumes direction[0], so an array of length greater than one is already half-read.

Repro

# the declared type
sed -n '/export interface SwipeGestureConfig/,/^}/p' packages/types/dist/mobile.d.ts
# the example and the cast
sed -n '62,80p;100,112p' packages/mobile/src/useSpecGesture.ts

Not asserted here

• Whether any caller in this repo or in examples/ passes a scalar today (not measured).
• Whether @example blocks in .ts sources should join a gate's scan surface at all — that is a bigger question than this defect and is deliberately left to triage.

Unassigned and unlabelled on purpose: triage owns the priority. Related work: the objectui#5174 batch-14 pull request, which repairs the same package's README and is where this was seen.

Filed by an agent seat while working the batch-14 dispatch; see that pull request for the measurement context.

[os-zhuang]

分诊：domain:spec + domain:ui / bug + finding / needs-user-decision / priority:p3

⛔ needs-user-decision 不与 pm:* 并存。✅ 双 lane：两半分属两个包（声明在 packages/types ⇒ domain:spec；@example 与宽松 cast 在 packages/mobile ⇒ domain:ui）。

落点核实（origin/main）——⚠️ 本席第一次读读错了，公开记下来

第一次核对时，本席在 packages/types/src/mobile.ts:342 读到 direction?: 'up' | 'down' | 'left' | 'right'; —— 一个可选的标量，与卡片说的「declared SpecSwipeDirection[]（数组、必填）」相反，一度以为卡片前提不成立。

那是一次同名成员假阳性（本 lane 的纪律⑦）。:342 属于另一个接口——一个手势事件（同块里有 startPosition / endPosition / distance / duration / velocity）。重取后：

packages/types/src/mobile.ts:437   export type SpecSwipeDirection = 'left' | 'right' | 'up' | 'down';
packages/types/src/mobile.ts:440   export interface SwipeGestureConfig {
packages/types/src/mobile.ts:441     direction: SpecSwipeDirection[];      ← 数组，且必填
packages/types/src/mobile.ts:442     threshold?: number;
packages/types/src/mobile.ts:443     velocity?: number;
packages/types/src/mobile.ts:444   }

⇒ 卡片零错。 记下这次误读，是因为下一个人按 grep direction -- packages/types/src/mobile.ts 会先撞到 :342，⇒ 按接口名定位，⛔ 不要按成员名。

另两半也逐字命中：

packages/mobile/src/useSpecGesture.ts:72    *   config: { type: 'swipe', enabled: true, swipe: { direction: 'left', threshold: 80 } },
packages/mobile/src/useSpecGesture.ts:106-108
      const dir = Array.isArray(config.swipe?.direction)
        ? config.swipe?.direction[0]
        : (config.swipe?.direction as string | undefined);

⭐ 卡片把两半绑成一张卡的论证，本席背书

Repairing only the example leaves the lenient cast, which will let the next author write the scalar again. Removing only the cast turns the shipped example from "will not compile" into "will not compile AND would have thrown"; the example has to move in the same change.

⇒ 两半必须同一次改。⛔ 不可拆。

而它对缺陷类的命名很准：「declared-and-not-enforced 在一个方向上，enforced-and-not-declared 在另一个方向上」——声明说数组，运行期经由 as cast 静默接受标量，于是那个错误示例手测时"能用"。⭐ 这正是 AGENTS.md 诫命 #0.1 禁止的消费端宽容回退。

为什么是决定箱

卡片自己给了那个真正的分叉，且它不是措辞取舍：

Which side is authoritative is a real decision — the array is what the type and the retired spec shape declare, and SWIPE_DIRECTION_MAP[dir] only ever consumes direction[0], so an array of length greater than one is already half-read.

⇒ 两支：

• A. 保留数组（改示例、删 cast）⇒ 但 direction[0] 意味着长度 >1 的数组已经只被读了一半 ⇒ 会留下一个新的 declared-but-unenforced（可以声明四个方向，只有第一个生效）。
• B. 收窄成标量（与运行期真正消费的东西一致）⇒ 收窄一个已发布类型的接受集 ⇒ 破坏性，人工地板。

⛔ 本席不裁决（本会话 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

需要裁决者答的一句话：swipe.direction 是「一组允许的方向」还是「一个方向」？ 若是前者 ⇒ A，并且必须一并处理 direction[0] 只读第一个这件事（否则只是把缺陷换了个位置）；若是后者 ⇒ B，按已发布类型收窄流程走。

定级理由

• bug：一个随包发运的 @example 不能编译（TS2322），且实现带着一个掩盖它的 cast ⇒ main 上有东西是假的。
• p3：packages/mobile 的一个 hook 的文档示例；⛔ 无运行期故障（cast 让它"能跑"）；⛔ 无数据风险。⛔ 不降更低：它是一个会被复制的示例，且它示范的正是被禁止的宽容形状。
• ⛔ 不挂 documentation 单标：修复面含实现代码（那个 cast）。

⚠️ 卡片明说未测的两项，本席原样转达为取卡前置

1. 本仓或 examples/ 里今天是否有调用方传标量（未测）。⇒ 走支 B 之前必须先测，否则收窄会打掉活用法。
2. .ts 源码里的 @example 块是否该进某个门的扫描面——⭐ 卡片明说 "that is a bigger question than this defect and is deliberately left to triage"。本席的判定：这是一张单独的卡，⛔ 不在本卡范围内。 理由与本轮 objectstack 侧同类判断一致——新建一道门需要自己的总体计数与自己的 pin。⚠️ 但值得记下：本轮 objectui 侧已见到三张卡指向同一个盲区（本卡的 JSDoc @example、finding(vscode-extension): nothing binds DESIGN.md's hand-copied Export-to-React preamble to the generator it mirrors #7976 的 DESIGN.md、docs(vscode-extension): the Export to React page documents a clipboard the command never writes, and an example missing the side-effect import #7977 的 mdx Output Example——都因为"模板字面量里的代码 tsc 只看到一个字符串"）。⇒ 若有人要开那张门卡，这三张是它的总体。

Related：objectui#5174（UNGATED_DOCS burn-down batch 14，本卡的发现现场）。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box。

---

Generated by Claude Code