@tom2012/dsh-pomodoro-overlay 0.0.0-stage → 0.1.2

package/docs/verification.md

@@ -0,0 +1,102 @@
+# 验证记录
+
+验证日期：2026-10-25  
+目标版本：DSH `0.2.1-rc.2`  
+GUI：`https://dsh.zhbc.bid:3003/`（不记录认证参数）  
+历史真实 GUI 方法：正式 `dsh plugin --profile web add` 本地 link 安装，重启原部署，在隔离 Chrome 中运行当时的 Host/Client bundle。当前修订的验证范围见下文，不与历史结果混用。
+
+## 自动化
+
+- `npm run verify`：通过。
+- `node:test`：**38/38 通过**（覆盖原生设置 slot、外观与字体校验、字体栈及 store 层外观即时更新语义；不是 DOM 样式验收）。
+- 历史独立只读审查：当时无阻断、高、中严重度问题；逐步推进 oracle 对拍 `settleState` 的 896 组边界全部一致。此后未修改 `settleState` 的阶段推进算法。
+- 构建后客户端冒烟：ModuleLoader 加载、配置 ready 后 store 启动、slots 注册，以及 `style.remove`、store 的 `storage` / `focus` / `pageshow` / `visibilitychange` 监听和 interval 清理通过。测试的 React 桩不会挂载 `ActiveOverlay`，因此不宣称 `ResizeObserver` / `MutationObserver`、窗口 resize / scroll、rAF / timeout 或 overlay DOM 清理已做真实 DOM 测试。
+- `npm publish --dry-run`：当前发布包内容检查通过。
+
+## 当前发布基线：0.1.2（2026-10-25）
+
+- npm 包及运行时包标识为 `@tom2012/dsh-pomodoro-overlay`，发布版本为 `0.1.2`；GitHub 仓库继续使用 `zbc0315/dsh-pomodoro-overlay`。
+- Cordis patch ID 与 ConfigForm ID 保持 `pomodoro-overlay`，localStorage 键保持 `dsh-pomodoro-overlay:state:v1`；作用域迁移不更改这些持久化读取键。
+- 当前聊天区只显示大倒计时，不显示可见阶段标签、工具条或控制按钮；屏幕阅读器状态保留。
+- 旧版 `running: false` 快照会继续保持暂停；README 已说明仅删除 `dsh-pomodoro-overlay:state:v1` 并刷新的重置方法，不影响 DSH 配置。
+- 当前版本完成自动化测试、构建产物静态检查和 npm 发布演练。下述历史 GUI 结果仅作回归基线，不作为当前七字段设置、字体保存或无阶段标签 UI 已完成真实 GUI 验收的证明。
+
+## 当前功能：原生设置窗口与外观配置（2026-10-25）
+
+- 设置入口已从 `plugins.bundle.config` 迁移到 DSH 设置窗口的 `settings.section`，导航 ID 为 `pomodoro`。
+- Host schema 和 ConfigForm 已扩展为七字段：全局字体、专注/休息时长、`#RRGGBB` 颜色和 0–1 不透明度；设置 UI 显示 0–100%。
+- 字体默认等线（DengXian），支持本机字体名称和常用候选；只解析本地字体栈，不下载字体，切换后重新测量数字宽度。
+- 两阶段草稿预览共用所选字体；七个字段使用同一 revision 一次原子保存。
+- `npm run verify` 通过，**38/38 测试通过**；旧配置自动补齐默认字体与外观，不改变运行时间线。
+- Host schema 变更需要在**外部 Terminal** 重载 DSH；禁止从 DSH 会话内部杀掉自己的宿主。真实窗口保存验收将在外部重载后补记。
+
+## 当前修订：移除可见阶段标签（2026-10-25）
+
+- 应用户要求，聊天区不再显示「专注 / 休息」阶段标签及其胶囊样式，只保留大倒计时。
+- 屏幕阅读器的阶段与剩余时间文本保留；颜色、透明度、字体和计时行为不变。
+- 包检查新增约束：客户端不得重新出现 `dpo-phase` 可见标签或对应 `data-dpo-phase` 标记。
+- `npm run verify` 通过，**38/38 测试通过**。
+
+## 历史修订：聊天区纯展示（2026-10-25）
+
+应用户要求，已移除聊天区右下角的「暂停 / 跳过 / 重置」及整个工具条。该版本 overlay 保留阶段标签、大倒计时和屏幕阅读器时间文本；设置页的保存/放弃按钮不受影响。
+
+- `npm run verify` 再次通过，**34/34 测试通过**。
+- 包检查新增约束：构建产物不得包含 `data-dpo-action`、`dpo-toolbar` 或「番茄钟控制」。
+- 真实客户端 DOM 检查：`overlayButtons: 0`、`actionControls: 0`、`toolbarNodes: 0`、`toolbarStyles: false`。
+- 阶段标签与根 overlay 的 `pointer-events` 均为 `none`，继续不阻断聊天操作。
+
+## 历史真实 GUI 基线（含已移除的控制按钮）
+
+下表是此前带控制按钮版本的完整回归记录；其中暂停/继续、跳过/重置、工具栏和 44px 聊天按钮行仅作历史证据，不再描述当前聊天区 UI。底层状态机及自动循环行为未改变。
+
+| 项目 | 结果 |
+| --- | --- |
+| 插件加载 | 插件详情显示 `v0.1.0`，包含的组件共 1 个、运行中 |
+| 自动启动 | 原生配置 ready 后无需点击即开始专注倒计时 |
+| 设置读取 | 设置页显示默认专注 25、休息 5，两个输入框均可编辑 |
+| 非法输入 | 专注设为 0 后显示「请输入 1–240 之间的整数分钟」，未保存 |
+| 原子保存 | 改为 1/1 后一次保存成功，出现新时长从下一阶段生效的提示 |
+| 当前阶段不变 | 保存 1/1 前后，当前 25 分钟专注的 `endsAt` 完全相等，仍显示约 24 分钟 |
+| 下一阶段生效 | 跳过后休息显示 `01:00`；保存 1/1 后的自动循环均为 60 秒 |
+| 专注配色 | 计算样式为主题灰色，alpha `0.2` |
+| 休息配色 | 计算样式为主题红色，alpha `0.3` |
+| 暂停/继续 | 暂停后连续 1.3 秒文字不变并显示「已暂停」；继续后文字随时间减少 |
+| 跳过/重置 | 专注→休息→专注正确；重置回到运行中的 `25:00` 专注 |
+| 桌面几何 | overlay 的 left/top/width 与聊天区一致，bottom 等于 composer 顶部 |
+| 数字适配 | 桌面示例中 322px 数字完整位于 920×584 的 overlay 内 |
+| 鼠标穿透 | overlay 与数字均为 `pointer-events: none`，中心命中元素不属于插件；工具栏为 `auto` |
+| 触控目标 | 暂停/继续、跳过、重置按钮高度均为 44px |
+| 自动休息→专注 | 在原休息边界准确进入专注，新 `startedAt` 等于旧 `endsAt`，时长 60000ms |
+| 自动专注→休息 | 在原专注边界准确进入休息，新 `startedAt` 等于旧 `endsAt`，时长 60000ms |
+| 刷新恢复 | 刷新前后运行状态 `endsAt` 完全相等，并继续原时间线 |
+| 非聊天视图 | 空白新会话没有消息流时隐藏；插件设置页中也隐藏 |
+| 窄窗口 | 380px viewport 下 overlay 为 324×523，数字缩至 106px，无裁切，仍扣除 composer |
+
+自动边界测试只在隔离浏览器的 localStorage 中构造合法、即将到期的运行状态，以缩短等待；执行的是实际刷新、原生配置加载和正式客户端计时逻辑，没有 mock 定时器或替换组件。
+
+测试结束后：
+
+- 原生配置已恢复为 **25/5**。
+- 隔离浏览器中的运行状态已重置为运行中的 25 分钟专注。
+- 测试 Chrome 已关闭，临时 profile、重启脚本和临时日志已删除。
+
+## 历史 GUI 环境备注（既有冲突）
+
+未隔离的首次启动出现：
+
+```text
+Failed to load plugins
+@deepseek-ai/dsh-client-ui-sidebar-files
+web boot: 1 entry did not activate
+```
+
+捕获到的原始异常是：
+
+```text
+slot "sidebar.right.tab.files.actions" is already declared
+```
+
+只读检查确认，既有 `@tom/dsh-file-tree` 与 DSH 内置 `@deepseek-ai/dsh-client-ui-sidebar-files` 同时声明了这个 slot；番茄钟没有声明或修改该 slot。为让该次历史番茄钟自测能够进入真实聊天区，仅在隔离 Chrome 的 boot 清单中临时跳过了重复的内置 sidebar-files 客户端，并关闭该测试页的 HMR 以防完整清单再次注入。没有因此修改 DSH、file-tree 或 profile。
+
+因此：**上述历史版本的番茄钟真实 GUI 检查全部通过，但这既不表示当前修订已完成全部 GUI 验收，也不表示未隔离的日常 GUI 已解决上述既有冲突。** 日常 GUI 若要正常启动，需要另行处理 file-tree 与内置 sidebar-files 的重复声明；历史测试没有擅自卸载或改写它们。

package/lib/index.js

@@ -0,0 +1,28 @@
+import z from '@deepseek-ai/schemastery'
+
+export const name = '@tom2012/dsh-pomodoro-overlay'
+
+/** Volatile fields are exposed through DSH's revision-fenced settings forms. */
+export const Config = z.object({
+  focusMinutes: z.number().step(1).min(1).max(240).default(25).volatile()
+    .description('专注时长（分钟），从下一专注阶段生效'),
+  breakMinutes: z.number().step(1).min(1).max(240).default(5).volatile()
+    .description('休息时长（分钟），从下一休息阶段生效'),
+  focusColor: z.string().pattern(/^#[0-9a-f]{6}$/i).default('#9ca3af').volatile()
+    .description('专注倒计时颜色，保存后立即生效'),
+  breakColor: z.string().pattern(/^#[0-9a-f]{6}$/i).default('#ef4444').volatile()
+    .description('休息倒计时颜色，保存后立即生效'),
+  focusOpacity: z.number().step(0.01).min(0).max(1).default(0.1).volatile()
+    .description('专注倒计时数字不透明度，0–1'),
+  breakOpacity: z.number().step(0.01).min(0).max(1).default(0.3).volatile()
+    .description('休息倒计时数字不透明度，0–1'),
+  fontFamily: z.string().pattern(/^[\p{L}\p{N}][\p{L}\p{N} _.-]{0,79}$/u).default('等线').volatile()
+    .description('专注与休息共用的时钟字体，默认等线（DengXian）'),
+})
+
+export function apply(ctx) {
+  // The plugin provides its own settings UI; disable any generated placeholder.
+  ctx.inject(['settings'], (child) => {
+    child.effect(() => child.settings.configure({ auto: false }, ctx.fiber))
+  })
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@tom2012/dsh-pomodoro-overlay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Automatic focus/break Pomodoro cycles with a chat-sized translucent countdown for DeepSeek Harness Web.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zbc0315/dsh-pomodoro-overlay.git"
+  },
+  "homepage": "https://github.com/zbc0315/dsh-pomodoro-overlay#readme",
+  "bugs": {
+    "url": "https://github.com/zbc0315/dsh-pomodoro-overlay/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.0-rc.1 <0.3.0-0"
+  },
+  "files": [
+    "lib",
+    "client",
+    "src",
+    "tests",
+    "tools",
+    "cordis.patch.yml",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node tools/build.mjs",
+    "check": "node --check lib/index.js && node --check client/client.js && node tools/check-package.mjs",
+    "test": "node --test tests/*.test.js",
+    "verify": "npm run build && npm run check && npm test"
+  },
+  "dsh": {
+    "category": "extension",
+    "displayName": "番茄钟 Overlay",
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./client/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0 <5.0.0",
+    "@deepseek-ai/dsh": ">=0.2.0-rc.1 <0.3.0-0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.11"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "pomodoro",
+    "timer",
+    "focus",
+    "番茄钟"
+  ]
+}

package/src/browser-store.js

@@ -0,0 +1,251 @@
+import {
+  DEFAULT_CONFIG,
+  FOCUS,
+  createRunningState,
+  formatRemaining,
+  pauseState,
+  parseConfig,
+  remainingAt,
+  resetState,
+  resumeState,
+  settleState,
+  skipState,
+  stateFromJSON,
+} from './timer-core.js'
+
+export const STATE_KEY = 'dsh-pomodoro-overlay:state:v1'
+
+function defaultStorage() {
+  try {
+    return typeof window === 'undefined' ? null : window.localStorage
+  } catch {
+    return null
+  }
+}
+
+function defaultEventTarget() {
+  return typeof window === 'undefined' ? null : window
+}
+
+function defaultDocument() {
+  return typeof document === 'undefined' ? null : document
+}
+
+/**
+ * Browser-local runtime state. Configuration arrives from DSH's native
+ * ConfigForm after it is ready; this store never substitutes defaults while
+ * that asynchronous read is still pending.
+ */
+export function createPomodoroStore(options = {}) {
+  const now = options.now ?? (() => Date.now())
+  const storage = options.storage === undefined ? defaultStorage() : options.storage
+  const events = options.events === undefined ? defaultEventTarget() : options.events
+  const documentRef = options.document === undefined ? defaultDocument() : options.document
+  const timers = options.timers ?? events
+  const tickMs = options.tickMs ?? 250
+
+  const listeners = new Set()
+  let config = parseConfig(options.initialConfig ?? DEFAULT_CONFIG)
+  let state = createRunningState(FOCUS, config, now())
+  let snapshot = null
+  let started = false
+  let disposed = false
+  let intervalId = null
+  let storageAvailable = Boolean(storage)
+
+  function readState() {
+    if (!storage) {
+      storageAvailable = false
+      return null
+    }
+    try {
+      const value = storage.getItem(STATE_KEY)
+      storageAvailable = true
+      return stateFromJSON(value)
+    } catch {
+      storageAvailable = false
+      return null
+    }
+  }
+
+  function writeState() {
+    if (!storage) {
+      storageAvailable = false
+      return false
+    }
+    try {
+      storage.setItem(STATE_KEY, JSON.stringify(state))
+      storageAvailable = true
+      return true
+    } catch {
+      // A persistence failure must not stop the active timer or its next phase.
+      storageAvailable = false
+      return false
+    }
+  }
+
+  function makeSnapshot(time) {
+    const remainingMs = remainingAt(state, time)
+    return Object.freeze({
+      active: started && !disposed,
+      phase: state.phase,
+      running: state.running,
+      text: formatRemaining(remainingMs),
+      remainingMs,
+      config,
+      state,
+      storageAvailable,
+      updatedAt: state.updatedAt,
+    })
+  }
+
+  function emit(time, force = false) {
+    const next = makeSnapshot(time)
+    const changed = force || !snapshot
+      || next.active !== snapshot.active
+      || next.phase !== snapshot.phase
+      || next.running !== snapshot.running
+      || next.text !== snapshot.text
+      || next.config !== snapshot.config
+      || next.updatedAt !== snapshot.updatedAt
+      || next.storageAvailable !== snapshot.storageAvailable
+    if (!changed) return
+    snapshot = next
+    for (const listener of [...listeners]) listener()
+  }
+
+  function refresh(force = false) {
+    if (!started || disposed) return
+    const time = now()
+    const settled = settleState(state, config, time)
+    if (settled !== state) {
+      state = settled
+      writeState()
+    }
+    emit(time, force)
+  }
+
+  function commit(next, time) {
+    state = next
+    writeState()
+    emit(time, true)
+  }
+
+  function onStorage(event) {
+    if (disposed || !started || event?.key !== STATE_KEY) return
+    const incoming = stateFromJSON(event.newValue)
+    if (!incoming || incoming.updatedAt < state.updatedAt) return
+    const time = now()
+    const settled = settleState(incoming, config, time)
+    state = settled
+    if (settled !== incoming) writeState()
+    emit(time, true)
+  }
+
+  function onVisibility() {
+    if (!documentRef?.hidden) refresh(true)
+  }
+
+  function onWake() {
+    refresh(true)
+  }
+
+  function start() {
+    if (started || disposed) return
+    started = true
+
+    const storedState = readState()
+    state = storedState ?? createRunningState(FOCUS, config, now())
+    if (!storedState) writeState()
+
+    events?.addEventListener?.('storage', onStorage)
+    events?.addEventListener?.('focus', onWake)
+    events?.addEventListener?.('pageshow', onWake)
+    documentRef?.addEventListener?.('visibilitychange', onVisibility)
+    intervalId = timers?.setInterval?.(refresh, tickMs) ?? null
+    refresh(true)
+  }
+
+  function subscribe(listener) {
+    if (typeof listener !== 'function') throw new TypeError('Listener must be a function')
+    listeners.add(listener)
+    return () => listeners.delete(listener)
+  }
+
+  function getSnapshot() {
+    if (!snapshot) snapshot = makeSnapshot(now())
+    return snapshot
+  }
+
+  /** Accept a newly ready or updated native DSH configuration. */
+  function setConfig(value) {
+    if (disposed) return
+    const next = parseConfig(value)
+    const time = now()
+    if (started) {
+      // First settle with the OLD durations. Otherwise an expired focus could
+      // be rewritten as a break using the new break duration retroactively.
+      const settled = settleState(state, config, time)
+      if (settled !== state) {
+        state = settled
+        writeState()
+      }
+    }
+    config = next
+    // The actual current phase, total duration and deadline stay untouched.
+    emit(time, true)
+  }
+
+  function pause() {
+    if (!started || disposed) return
+    const time = now()
+    commit(pauseState(state, config, time), time)
+  }
+
+  function resume() {
+    if (!started || disposed) return
+    const time = now()
+    const settled = settleState(state, config, time)
+    commit(resumeState(settled, config, time), time)
+  }
+
+  function skip() {
+    if (!started || disposed) return
+    const time = now()
+    const settled = settleState(state, config, time)
+    commit(skipState(settled, config, time), time)
+  }
+
+  function reset() {
+    if (!started || disposed) return
+    const time = now()
+    commit(resetState(config, time), time)
+  }
+
+  function dispose() {
+    if (disposed) return
+    disposed = true
+    started = false
+    if (intervalId !== null) timers?.clearInterval?.(intervalId)
+    intervalId = null
+    events?.removeEventListener?.('storage', onStorage)
+    events?.removeEventListener?.('focus', onWake)
+    events?.removeEventListener?.('pageshow', onWake)
+    documentRef?.removeEventListener?.('visibilitychange', onVisibility)
+    listeners.clear()
+    snapshot = null
+  }
+
+  return {
+    start,
+    subscribe,
+    getSnapshot,
+    setConfig,
+    pause,
+    resume,
+    skip,
+    reset,
+    refresh,
+    dispose,
+  }
+}

package/src/chat-geometry.js

@@ -0,0 +1,49 @@
+export const CHAT_SELECTOR = '[data-conversation-content][data-conversation-region="chat"]'
+export const COMPOSER_SELECTOR = '[data-composer-seat]'
+export const CHAT_FLOW_SELECTOR = '[data-chat-flow]'
+
+function finiteRect(rect) {
+  return rect && ['left', 'top', 'right', 'bottom', 'width', 'height'].every((key) => Number.isFinite(rect[key]))
+}
+
+/**
+ * Resolve the visible message-only rectangle. This reads current DSH semantic
+ * DOM markers but never mutates them. Any mismatch fails closed.
+ */
+export function chatOverlayRect(chat) {
+  if (!chat || chat.isConnected === false || chat.closest?.('[hidden], [inert]')) return null
+  if (!chat.querySelector?.(CHAT_FLOW_SELECTOR)) return null
+  const body = chat.getBoundingClientRect?.()
+  if (!finiteRect(body) || body.width <= 0 || body.height <= 0) return null
+
+  const composer = chat.querySelector?.(COMPOSER_SELECTOR)
+  const composerRect = composer?.getBoundingClientRect?.()
+  const bottom = finiteRect(composerRect)
+    ? Math.min(body.bottom, composerRect.top)
+    : body.bottom
+  const height = bottom - body.top
+  if (body.width < 160 || height < 120) return null
+
+  return {
+    left: body.left,
+    top: body.top,
+    right: body.right,
+    bottom,
+    width: body.width,
+    height,
+  }
+}
+
+/** Prefer the largest visible Conversation when embedded chats also exist. */
+export function findChatOverlay(documentRef) {
+  if (!documentRef?.querySelectorAll) return null
+  let best = null
+  for (const chat of documentRef.querySelectorAll(CHAT_SELECTOR)) {
+    const rect = chatOverlayRect(chat)
+    if (!rect) continue
+    if (!best || rect.width * rect.height > best.rect.width * best.rect.height) {
+      best = { chat, rect }
+    }
+  }
+  return best
+}