paseo-kanban 0.1.2 → 0.1.4

package/OVERVIEW.md

@@ -0,0 +1,35 @@
+# Kanban
+
+A lightweight, responsive Kanban board plugin for Paseo workspaces.
+
+## Features
+
+- **Flexible swimlanes**: Add, delete, and rename lanes.
+- **Rich task cards**: Edit task titles and multi-line descriptions, manage subtask checklists, and link tasks to Paseo projects.
+- **Task completion**: Check a card or drag it into the completion lane to finish; uncheck or drag out to restore.
+- **Workspace tabs and splits**: Open the board beside an agent or terminal with Paseo's native split controls, initially filtered to the workspace's project, or use the sidebar entry.
+- **Smooth drag and drop**: Support intra-lane reordering and cross-lane movement.
+
+## Storage and requirements
+
+- **Data and privacy**: Board data is stored locally in host-scoped plugin settings with revision checks for concurrent edits. No accounts, tokens, or external network requests are required.
+- **Host requirement**: Paseo 0.8.0 or later.
+
+---
+
+# 看板 (Kanban)
+
+专为 Paseo 工作区打造的轻量响应式看板插件。
+
+## 核心功能
+
+- **灵活的泳道管理**：支持泳道增删与改名。
+- **丰富的任务卡片**：支持任务标题与多行描述编辑、子步骤清单管理，以及关联 Paseo 项目。
+- **任务完成与恢复**：通过卡片勾选或拖入完成泳道标记完成；取消勾选或拖出即可恢复。
+- **工作区标签页与分屏**：支持通过 Paseo 原生分屏控件与 Agent、Terminal 并排打开，默认筛选工作区所属项目，或使用侧边栏入口。
+- **流畅拖拽交互**：支持同泳道排序与跨泳道状态流转。
+
+## 存储与要求
+
+- **数据与隐私**：看板数据保存在宿主本地插件设置中，具备版本并发冲突保护（CAS）。无需账号、Token 或任何外部网络请求。
+- **宿主要求**：Paseo 0.8.0 或更高版本。

package/README.md

@@ -2,27 +2,26 @@
 
 [简体中文](./README.zh-CN.md)
 
-A lightweight, responsive Kanban board plugin for [Paseo](https://paseo.sh) workspaces. Organize tasks across customizable swimlanes, break them down into subtasks, associate cards with native Paseo projects, and manage workflow status with intuitive drag-and-drop.
+A lightweight, responsive Kanban board plugin for [Paseo](https://paseo.sh) workspaces.
 
 ---
 
 ## Features
 
-- **Flexible Swimlanes**: Default lanes (`To Plan`, `In Progress`, `Done`) with full support for adding, renaming, and deleting custom lanes.
+- **Flexible Swimlanes**: Add, delete, and rename lanes.
 - **Rich Task Cards**:
-  - Task title and multi-line markdown description.
-  - Subtasks checklist with completion toggles and live progress tracking.
-  - Native Paseo project association.
-- **Project Filtering**: Instantly filter board cards by linked Paseo project to keep context focused.
-- **Smooth Drag-and-Drop**: Real-time hit-testing for reordering cards within lanes and moving cards across lanes.
-- **Versioned State Persistence**: Persists board data through Paseo's settings API with optimistic concurrency control (CAS) to prevent race conditions and accidental overwrites.
+  - Task title and multi-line description editing.
+  - Subtasks checklist.
+  - Support linking tasks to projects created in Paseo.
+- **Workspace Tabs and Splits**: Open the board beside an agent or terminal, initially filtered to the workspace's project, or use the sidebar entry.
+- **Smooth Drag-and-Drop**: Support intra-lane reordering and cross-lane movement.
 
 ---
 
 ## Requirements
 
-- **Paseo Host Runtime Commitment**: `>= 0.8.0` (declared in `paseo-plugin.json`). As a Paseo workspace plugin, production runtime execution is managed and hosted by the Paseo application environment. No consumer-side Node version restriction is imposed in `package.json`.
-- **Development & CI Baseline**: Node.js 24 (pinned in `.nvmrc` and `.node-version`). Node 24 is required for local contributors and CI automation workflows running quality checks (`npm run check`), type stripping (`--experimental-strip-types`), and native test suites (`node --test`).
+- **Paseo host**: `>= 0.8.0` (declared in `paseo-plugin.json`). The host runs the plugin.
+- **Development and CI**: Node.js 24 (pinned in `.nvmrc` and `.node-version`) for checks, TypeScript stripping, and native tests.
 
 ---
 
@@ -30,7 +29,7 @@ A lightweight, responsive Kanban board plugin for [Paseo](https://paseo.sh) work
 
 ### Quick Install (Recommended)
 
-No manual build or git cloning needed. You can install directly via npm or GitHub:
+Install directly from npm or GitHub:
 
 **Via NPM (Release package):**
 
@@ -56,7 +55,10 @@ Verify that the plugin is running:
 paseo plugin ls
 ```
 
-Once active, open Paseo. The **Kanban** icon (`PanelsTopLeft`) will appear in the sidebar. Click it to launch the board.
+Open the board from either entry:
+
+- **Sidebar → Kanban**: shows all tasks by default.
+- **Workspace → `+` → Kanban**: initially filters to the workspace's project, with other filters available; use Paseo's native split controls to place it beside an agent or terminal.
 
 ### Local Development
 
@@ -66,7 +68,7 @@ To contribute or debug locally:
 # 1. Clone repository and install dependencies
 git clone https://github.com/breathi3552/paseo-kanban.git
 cd paseo-kanban
-npm install
+npm ci
 
 # 2. Link this directory into your local Paseo daemon
 paseo plugin link .
@@ -76,56 +78,26 @@ paseo plugin link .
 
 ## Development & Testing
 
-### Install Dependencies
+Install dependencies and run the full quality check:
 
 ```bash
-npm install
-# or clean install:
 npm ci
+npm run check
 ```
 
-### Unified Quality Guardrails (Check)
+Individual commands (`npm test`, `npm run typecheck`, `npm run lint`, `npm run format:check`, `npm run check:package`) are defined in [`package.json`](./package.json). For tag-based publishing, release sources of truth, recovery, and host acceptance, see the [development guide](./docs/development.md#21-标签发布github-actions).
 
-Runs typecheck, automated test suites, linting, format verification, and release package checks in sequence:
+---
 
-```bash
-npm run check
-```
+## Releases
 
-### Individual Quality Tasks
-
-- **Package Verification**: Validates release package contents, entrypoints, and TypeScript AST relative imports:
-  ```bash
-  npm run check:package
-  ```
-- **Run Tests**: Cross-platform auto-discovery of all `test/*.test.mjs` suites:
-  ```bash
-  npm test
-  ```
-- **Type Checking**: Validates TypeScript types across client and server entry points:
-  ```bash
-  npm run typecheck
-  ```
-- **Linting**: Static code analysis with ESLint:
-  ```bash
-  npm run lint
-  ```
-- **Formatting**: Check or format code style with Prettier:
-  ```bash
-  npm run format:check
-  npm run format
-  ```
-
-Maintainers can publish a new GitHub Release and npm package in one run of the **Release to GitHub and npm** GitHub Action: select `patch`, `minor`, or `major`. Configure `NPM_TOKEN` and repository write permissions first. For setup, recovery, and manual host acceptance, see the [Development & Acceptance Guide](./docs/development.md#24-一键发布github-actions).
+See the [0.1.4 release notes](./docs/releases/0.1.4.md). Each release's npm package and GitHub Release share the same version tag; GitHub includes the verified npm tarball. `main` may contain changes beyond the latest release.
 
 ---
 
 ## Architecture & Design
 
-The complete architectural breakdown and interactive visual diagram are archived in the repository:
-
-- **Interactive Architecture Viewer**: Open [`docs/architecture/paseo-kanban.architecture.html`](./docs/architecture/paseo-kanban.architecture.html) in your browser.
-- **Architecture Schema & Model**: [`docs/architecture/paseo-kanban.architecture.json`](./docs/architecture/paseo-kanban.architecture.json).
+Core terminology and design decisions are documented in [`GLOSSARY.md`](./GLOSSARY.md) and [`docs/adr/`](./docs/adr/).
 
 ---
 

package/README.zh-CN.md

@@ -2,27 +2,26 @@
 
 [English](./README.md)
 
-专为 [Paseo](https://paseo.sh) 工作区打造的轻量响应式看板插件。支持自定义泳道分类、任务子步骤细化、原生 Paseo 项目关联筛选，以及跨泳道流畅拖拽管理。
+专为 [Paseo](https://paseo.sh) 工作区打造的轻量响应式看板插件。
 
 ---
 
 ## 核心功能
 
-- **灵活的泳道管理**：开箱即用三列基础泳道（`待规划`、`执行中`、`已完成`），支持自由添加、重命名与删除自定义泳道。
+- **灵活的泳道管理**：支持泳道增删与改名。
 - **丰富的任务卡片**：
   - 任务标题与多行描述编辑。
-  - 子步骤清单支持独立增删改、完成状态勾选及实时进度展示。
-  - 支持关联本地已有的 Paseo 项目。
-- **项目维度筛选**：一键按关联的 Paseo 项目过滤看板卡片，聚焦当前目标。
-- **流畅拖拽交互**：精准的拖拽命中测试（Hit-Testing），支持同泳道排序与跨泳道状态流转。
-- **版本化数据持久化**：基于 Paseo 原生 settings API 存储，内置乐观并发版本控制（CAS），杜绝多会话覆写与状态不一致。
+  - 子步骤清单。
+  - 支持关联 Paseo 中创建的项目。
+- **工作区标签页与分屏**：与 Agent、Terminal 并排打开看板，默认筛选工作区所属项目；或使用侧边栏入口。
+- **流畅拖拽交互**：支持同泳道排序与跨泳道状态流转。
 
 ---
 
 ## 环境要求
 
-- **Paseo 宿主版本承诺**：`>= 0.8.0`（声明于 `paseo-plugin.json`）。作为 Paseo 工作区插件，插件的生产运行时环境由 Paseo 宿主应用提供并托管执行，不在 `package.json` 对消费端强加额外的 `engines.node` 限制。
-- **开发与 CI 环境基线**：Node.js 24（显式声明于 `.nvmrc` 与 `.node-version`）。本地参与开发、运行质量检查护栏（`npm run check`）、代码格式化、类型检查与自动化测试必须基于 Node 24，依赖其原生的 `--experimental-strip-types` 类型擦除与原生测试运行器（`node --test`）。
+- **Paseo 宿主**：`>= 0.8.0`（声明于 `paseo-plugin.json`），由 Paseo 运行插件。
+- **开发与 CI**：使用 Node.js 24（声明于 `.nvmrc` 与 `.node-version`）执行质量检查、TypeScript 类型擦除和原生测试。
 
 ---
 
@@ -30,7 +29,7 @@
 
 ### 快速安装（推荐）
 
-无需克隆源码或手动编译，推荐直接使用 Paseo CLI 安装：
+通过 Paseo CLI 从 npm 或 GitHub 安装：
 
 **方式一：通过 NPM 官方包安装（推荐）**
 
@@ -56,7 +55,10 @@ paseo plugin add breathi3552/paseo-kanban --ref main
 paseo plugin ls
 ```
 
-状态显示为 `running` 后打开 Paseo，侧边栏将出现 **看板** 入口（图标：`PanelsTopLeft`），点击即可进入看板。
+可从两个入口打开看板：
+
+- **侧边栏 → 看板**：默认展示全部任务。
+- **工作区 → `+` → 看板**：默认筛选工作区所属项目，可切换范围；使用 Paseo 原生分屏操作与 Agent、Terminal 等并排显示。
 
 ### 本地开发与调试
 
@@ -66,7 +68,7 @@ paseo plugin ls
 # 1. 克隆代码仓库并安装依赖
 git clone https://github.com/breathi3552/paseo-kanban.git
 cd paseo-kanban
-npm install
+npm ci
 
 # 2. 将当前开发目录软链接至本地 Paseo 守护进程
 paseo plugin link .
@@ -76,58 +78,26 @@ paseo plugin link .
 
 ## 开发与测试
 
-### 安装依赖
+安装依赖并运行完整检查：
 
 ```bash
-npm install
-# 或干净安装验证：
 npm ci
+npm run check
 ```
 
-### 统一质量护栏检查
+单项命令（`npm test`、`npm run typecheck`、`npm run lint`、`npm run format:check`、`npm run check:package`）见 [`package.json`](./package.json)。标签发布、事实来源、失败重试与宿主验收见[开发指南](./docs/development.md#21-标签发布github-actions)。
 
-按顺序执行类型检查、自动化测试套件、静态代码检查、代码格式验证及发布包完整性检查：
+---
 
-```bash
-npm run check
-```
+## 版本发布
 
-### 各独立质量命令
-
-- **发布包完整性检查**：静态校验发布包产物清单、入口完整性与 TypeScript AST 相对导入闭包：
-  ```bash
-  npm run check:package
-  ```
-- **运行单元测试**：跨平台自动发现并执行所有 `test/*.test.mjs` 测试套件：
-  ```bash
-  npm test
-  ```
-- **类型检查**：校验前端组件与服务端扩展的 TypeScript 类型完整性：
-  ```bash
-  npm run typecheck
-  ```
-- **代码规范检查 (Lint)**：基于 ESLint 开展轻量静态检查：
-  ```bash
-  npm run lint
-  ```
-- **代码格式检查与格式化 (Format)**：基于 Prettier 校验或自动格式化：
-  ```bash
-  npm run format:check
-  npm run format
-  ```
-
-维护者可在 GitHub Actions 的 **Release to GitHub and npm** 工作流中选择 `patch` / `minor` / `major` 一键发布 GitHub Release 与 npm 包；首次使用需配置 `NPM_TOKEN` 和仓库写入权限。操作及失败重试说明见 [开发与宿主验收指南](./docs/development.md#24-一键发布github-actions)。
-
-详细开发贡献流程、发布前检查机制与真实宿主环境手工验收指南，请参阅 [开发与宿主验收指南](./docs/development.md)。
+参见 [0.1.4 版本说明](./docs/releases/0.1.4.md)。每版 npm 包与 GitHub Release 对应同一个版本 tag，GitHub 附带经过验证的 npm tarball。`main` 可能包含最新发布版之后的改动。
 
 ---
 
 ## 架构设计
 
-完整的插件架构图景与交互式全景模型已归档于仓库：
-
-- **交互式架构全景图**：直接使用浏览器打开 [`docs/architecture/paseo-kanban.architecture.html`](./docs/architecture/paseo-kanban.architecture.html) 查看。
-- **架构定义元数据**：[`docs/architecture/paseo-kanban.architecture.json`](./docs/architecture/paseo-kanban.architecture.json)。
+核心术语和架构决策见 [`GLOSSARY.md`](./GLOSSARY.md) 与 [`docs/adr/`](./docs/adr/)。
 
 ---
 

package/client/i18n.tsx

@@ -1,7 +1,11 @@
-import { useState, useEffect, useMemo } from "react";
+import { useState, useEffect, useMemo, createContext, useContext } from "react";
 
 export type SupportedLanguage = "zh" | "en";
 
+export const I18nLanguageContext = createContext<SupportedLanguage | null>(
+  null,
+);
+
 export type TranslationParams = Record<
   string,
   string | number | boolean | null | undefined
@@ -9,6 +13,19 @@ export type TranslationParams = Record<
 
 export const translations = {
   zh: {
+    "notification.taskCreated": "任务已创建",
+    "notification.taskUpdated": "任务已更新",
+    "notification.taskDeleted": "任务已删除",
+    "notification.laneCreated": "泳道已创建",
+    "notification.laneRenamed": "泳道已重命名",
+    "notification.laneDeleted": "泳道已删除",
+    "notification.taskSaveFailed": "任务保存失败，草稿已保留，请核实最新数据。",
+    "notification.taskDeleteFailed": "任务删除失败，请核实最新数据。",
+    "notification.laneSaveFailed": "泳道保存失败，草稿已保留，请核实最新数据。",
+    "notification.laneDeleteFailed": "泳道删除失败，请核实最新数据。",
+    "notification.taskReorderFailed": "任务移动失败，请刷新最新数据后重试。",
+    "notification.taskCompletionFailed":
+      "任务完成状态保存失败，请核实最新状态。",
     "kanban.sidebarTitle": "看板",
     "kanban.title": "任务看板",
     "kanban.loading": "正在加载看板数据...",
@@ -31,13 +48,18 @@ export const translations = {
     "lane.add": "+ 添加",
     "lane.manage": "管理",
     "lane.emptyHint": "暂无卡片，可点击右上角添加或拖动卡片至此",
+    "lane.emptyCompletionHint": "暂无已完成任务，可勾选任务或将卡片拖入此泳道",
+    "card.completeTask": "完成任务：{title}",
+    "card.reopenTask": "取消完成：{title}",
     "card.dragHandle": "拖动手柄",
     "card.subtasksCount": "子步骤 {completed}/{total}",
     "laneModal.titleEdit": "管理泳道",
     "laneModal.titleCreate": "新增泳道",
     "laneModal.nameLabel": "泳道名称 *",
     "laneModal.namePlaceholder": "例如：待测试、发布中...",
-    "laneModal.cannotDeleteLast": "看板必须至少保留一条泳道，无法删除此泳道。",
+    "laneModal.cannotDeleteLast":
+      "看板必须至少保留一条普通泳道，无法删除此泳道。",
+    "laneModal.cannotDeleteCompletion": "完成泳道不可删除，可以修改名称。",
     "laneModal.cannotDeleteHasTasks":
       "此泳道当前包含 {count} 个任务，需清空或移走任务后方可删除。",
     "laneModal.deleteLane": "删除此泳道",
@@ -69,6 +91,24 @@ export const translations = {
     "taskModal.submitCreate": "创建",
   },
   en: {
+    "notification.taskCreated": "Task created",
+    "notification.taskUpdated": "Task updated",
+    "notification.taskDeleted": "Task deleted",
+    "notification.laneCreated": "Lane created",
+    "notification.laneRenamed": "Lane renamed",
+    "notification.laneDeleted": "Lane deleted",
+    "notification.taskSaveFailed":
+      "Task save failed. Draft preserved; check the latest data.",
+    "notification.taskDeleteFailed":
+      "Task deletion failed. Check the latest data.",
+    "notification.laneSaveFailed":
+      "Lane save failed. Draft preserved; check the latest data.",
+    "notification.laneDeleteFailed":
+      "Lane deletion failed. Check the latest data.",
+    "notification.taskReorderFailed":
+      "Task move failed. Refresh the latest data and try again.",
+    "notification.taskCompletionFailed":
+      "Task completion change failed. Check the latest state.",
     "kanban.sidebarTitle": "Kanban",
     "kanban.title": "Task Kanban",
     "kanban.loading": "Loading kanban board data...",
@@ -92,6 +132,10 @@ export const translations = {
     "lane.manage": "Manage",
     "lane.emptyHint":
       "No cards yet. Click '+' in the top right or drag cards here.",
+    "lane.emptyCompletionHint":
+      "No completed tasks. Check a task or drag it into this lane.",
+    "card.completeTask": "Mark {title} complete",
+    "card.reopenTask": "Mark {title} incomplete",
     "card.dragHandle": "Drag handle",
     "card.subtasksCount": "Subtasks {completed}/{total}",
     "laneModal.titleEdit": "Manage Lane",
@@ -99,7 +143,9 @@ export const translations = {
     "laneModal.nameLabel": "Lane Name *",
     "laneModal.namePlaceholder": "e.g., Testing, In Review...",
     "laneModal.cannotDeleteLast":
-      "A kanban board must retain at least one lane. Cannot delete this lane.",
+      "A kanban board must retain at least one ordinary lane. Cannot delete this lane.",
+    "laneModal.cannotDeleteCompletion":
+      "The completion lane cannot be deleted. You can rename it.",
     "laneModal.cannotDeleteHasTasks":
       "This lane currently contains {count} tasks. Clear or move tasks before deleting.",
     "laneModal.deleteLane": "Delete Lane",
@@ -172,6 +218,7 @@ interface EnvironmentGlobals {
   };
   navigator?: {
     language?: string;
+    languages?: readonly string[];
   };
   window?: {
     addEventListener(
@@ -214,6 +261,12 @@ export function detectPaseoLanguage(
     } catch {}
   }
 
+  // Match Paseo's web system-language source before page/Intl defaults.
+  const navLocale = env.navigator?.languages?.[0] || env.navigator?.language;
+  if (navLocale) {
+    return normalizeLanguage(navLocale);
+  }
+
   const docLang = env.document?.documentElement?.lang;
   if (docLang) {
     return normalizeLanguage(docLang);
@@ -232,11 +285,6 @@ export function detectPaseoLanguage(
     return normalizeLanguage(intlLocale);
   }
 
-  const navLocale = env.navigator?.language;
-  if (navLocale) {
-    return normalizeLanguage(navLocale);
-  }
-
   return "en";
 }
 
@@ -323,6 +371,7 @@ export interface I18nContextValue {
 }
 
 export function useI18n(hostProps?: DetectLanguageOptions): I18nContextValue {
+  const inheritedLanguage = useContext(I18nLanguageContext);
   const hostLocale =
     hostProps?.locale ??
     hostProps?.language ??
@@ -341,14 +390,15 @@ export function useI18n(hostProps?: DetectLanguageOptions): I18nContextValue {
     });
   }, [hostLocale, hostProps]);
 
+  const language = hostLocale ? lang : (inheritedLanguage ?? lang);
   const tBound = useMemo(
     () => (key: TranslationKey, params?: TranslationParams) =>
-      t(key, lang, params),
-    [lang],
+      t(key, language, params),
+    [language],
   );
 
   return {
-    language: lang,
+    language,
     t: tBound,
   };
 }