paseo-kanban 0.1.2 → 0.1.3

package/OVERVIEW.md

@@ -0,0 +1,9 @@
+# Kanban
+
+Organize tasks in customizable swimlanes, add descriptions and subtasks, and link tasks to Paseo projects. Drag cards to reorder them within a lane or move them between lanes.
+
+Open the board from the sidebar or from a workspace's `+` menu. Workspace tabs initially filter to their project's tasks and can sit beside an agent or terminal using Paseo's native split controls. Each open board has its own project filter; all boards on the same host share tasks and lanes.
+
+Board data is stored in Paseo's host-scoped plugin settings. Concurrent edits use revision checks so a stale edit cannot overwrite a newer board. If a project's name cannot be read, its stored ID remains available. If workspace project context is unavailable when the board opens, it initially shows all tasks.
+
+Requires Paseo 0.8.0 or later. No accounts, tokens, or additional setup are required.

package/README.md

@@ -8,11 +8,12 @@ A lightweight, responsive Kanban board plugin for [Paseo](https://paseo.sh) work
 
 ## Features
 
-- **Flexible Swimlanes**: Default lanes (`To Plan`, `In Progress`, `Done`) with full support for adding, renaming, and deleting custom lanes.
+- **Flexible Swimlanes**: Three initial lanes that you can rename, with support for adding and deleting custom lanes.
 - **Rich Task Cards**:
-  - Task title and multi-line markdown description.
+  - Task title and multi-line description.
   - Subtasks checklist with completion toggles and live progress tracking.
   - Native Paseo project association.
+- **Workspace Tabs and Splits**: Open the board beside an agent or terminal, initially filtered to the workspace's project. The sidebar remains available.
 - **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.
@@ -21,8 +22,8 @@ A lightweight, responsive Kanban board plugin for [Paseo](https://paseo.sh) work
 
 ## 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 +31,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 +57,12 @@ 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.
+Once active, 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.
+
+Both entries share tasks and lanes with full editing support; their filters are independent. Closing and reopening the board or restarting restores the entry's default filter. If workspace project context is unavailable, the board silently shows all tasks and keeps that filter even if context arrives later. Narrow splits retain horizontal lane scrolling.
 
 ### Local Development
 
@@ -66,7 +72,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 +82,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.3 release notes](./docs/releases/0.1.3.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 [`CONTEXT.md`](./CONTEXT.md) and [`docs/adr/`](./docs/adr/).
 
 ---
 

package/README.zh-CN.md

@@ -13,16 +13,17 @@
   - 任务标题与多行描述编辑。
   - 子步骤清单支持独立增删改、完成状态勾选及实时进度展示。
   - 支持关联本地已有的 Paseo 项目。
+- **工作区标签页与分屏**：与 Agent、Terminal 并排打开看板，默认筛选工作区所属项目；保留侧边栏入口。
 - **项目维度筛选**：一键按关联的 Paseo 项目过滤看板卡片，聚焦当前目标。
 - **流畅拖拽交互**：精准的拖拽命中测试（Hit-Testing），支持同泳道排序与跨泳道状态流转。
-- **版本化数据持久化**：基于 Paseo 原生 settings API 存储，内置乐观并发版本控制（CAS），杜绝多会话覆写与状态不一致。
+- **版本化数据持久化**：通过 Paseo settings API 存储看板，使用乐观并发版本控制（CAS）处理多会话写入冲突。
 
 ---
 
 ## 环境要求
 
-- **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 +31,7 @@
 
 ### 快速安装（推荐）
 
-无需克隆源码或手动编译，推荐直接使用 Paseo CLI 安装：
+通过 Paseo CLI 从 npm 或 GitHub 安装：
 
 **方式一：通过 NPM 官方包安装（推荐）**
 
@@ -56,7 +57,12 @@ paseo plugin add breathi3552/paseo-kanban --ref main
 paseo plugin ls
 ```
 
-状态显示为 `running` 后打开 Paseo，侧边栏将出现 **看板** 入口（图标：`PanelsTopLeft`），点击即可进入看板。
+状态显示为 `running` 后，可从两个入口打开看板：
+
+- **侧边栏 → 看板**：默认展示全部任务。
+- **工作区 → `+` → 看板**：默认筛选工作区所属项目，可切换范围；使用 Paseo 原生分屏操作与 Agent、Terminal 等并排显示。
+
+两个入口共享任务和泳道，保留完整编辑能力，筛选互不影响。关闭重开或重启后恢复入口默认筛选。无法取得工作区所属项目时静默展示全部任务，本次打开期间不因项目上下文恢复而自动切换。窄分屏保持横向滚动浏览泳道。
 
 ### 本地开发与调试
 
@@ -66,7 +72,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 +82,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.3 版本说明](./docs/releases/0.1.3.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)。
+核心术语和架构决策见 [`CONTEXT.md`](./CONTEXT.md) 与 [`docs/adr/`](./docs/adr/)。
 
 ---
 

package/client/kanban-board.tsx

@@ -6,6 +6,7 @@ import {
   Pressable,
   StyleSheet,
   ActivityIndicator,
+  type LayoutChangeEvent,
 } from "react-native";
 import { useSettings } from "@getpaseo/plugin/client";
 import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
@@ -25,8 +26,23 @@ import {
 } from "./kanban-session";
 import { useI18n } from "./i18n";
 
-export function KanbanBoardView(props: PluginSurfaceProps) {
-  const { theme, layout } = props;
+interface KanbanBoardProps extends PluginSurfaceProps {
+  initialProjectId?: string | null;
+}
+
+export function KanbanBoardView(props: KanbanBoardProps) {
+  const { theme } = props;
+  const [panelWidth, setPanelWidth] = useState<number | null>(null);
+  const compact =
+    props.layout.compact || (panelWidth !== null && panelWidth < 600);
+  const layout = useMemo(
+    () => ({ ...props.layout, compact }),
+    [props.layout, compact],
+  );
+  const handleLayout = (event: LayoutChangeEvent) => {
+    const { width } = event.nativeEvent.layout;
+    if (width > 0) setPanelWidth(width);
+  };
   const { t, language } = useI18n(props);
   const settings = useSettings(kanbanSettings);
   const {
@@ -35,13 +51,29 @@ export function KanbanBoardView(props: PluginSurfaceProps) {
     isError: projectsError,
   } = useProjects();
 
-  const [selectedProjectId, setSelectedProjectId] = useState<string>("all");
+  const [selectedProjectId, setSelectedProjectId] = useState(
+    props.initialProjectId || "all",
+  );
   const [activeTaskSession, setActiveTaskSession] =
     useState<TaskEditSession | null>(null);
   const [activeLaneSession, setActiveLaneSession] =
     useState<LaneEditSession | null>(null);
   const [reorderError, setReorderError] = useState<string | null>(null);
 
+  const selectableProjects = useMemo(() => {
+    const missingIds = new Set([props.initialProjectId, selectedProjectId]);
+    const missingProjects = [...missingIds]
+      .filter(
+        (id): id is string =>
+          !!id &&
+          id !== "all" &&
+          id !== "unassigned" &&
+          !projects.some((project) => project.projectId === id),
+      )
+      .map((id) => ({ projectId: id, projectDisplayName: id }));
+    return [...projects, ...missingProjects];
+  }, [projects, props.initialProjectId, selectedProjectId]);
+
   const isReady = settings.status === "ready";
   const board = isReady ? settings.values : null;
   const revision = isReady ? settings.revision : "";
@@ -154,6 +186,8 @@ export function KanbanBoardView(props: PluginSurfaceProps) {
       StyleSheet.create({
         container: {
           flex: 1,
+          minWidth: 0,
+          minHeight: 0,
           backgroundColor: theme.colors.surface0,
           userSelect: "none",
         },
@@ -174,6 +208,9 @@ export function KanbanBoardView(props: PluginSurfaceProps) {
         },
         titleRow: {
           flexDirection: "row",
+          flexWrap: "wrap",
+          flexShrink: 1,
+          maxWidth: "100%",
           alignItems: "center",
           gap: 8,
         },
@@ -184,6 +221,8 @@ export function KanbanBoardView(props: PluginSurfaceProps) {
         },
         headerActions: {
           flexDirection: "row",
+          flexWrap: "wrap",
+          maxWidth: "100%",
           alignItems: "center",
           gap: 8,
         },
@@ -270,6 +309,7 @@ export function KanbanBoardView(props: PluginSurfaceProps) {
         },
         lanesWrapper: {
           flex: 1,
+          minHeight: 0,
           position: "relative",
           userSelect: "none",
         },
@@ -370,7 +410,7 @@ export function KanbanBoardView(props: PluginSurfaceProps) {
   if (!board) return null;
 
   return (
-    <View style={styles.container}>
+    <View style={styles.container} onLayout={handleLayout}>
       {/* Top Header */}
       <View style={styles.header}>
         <View style={styles.headerTopRow}>
@@ -462,7 +502,7 @@ export function KanbanBoardView(props: PluginSurfaceProps) {
               </Text>
             </Pressable>
 
-            {projects.map((proj) => {
+            {selectableProjects.map((proj) => {
               const isSelected = selectedProjectId === proj.projectId;
               return (
                 <Pressable
@@ -567,7 +607,7 @@ export function KanbanBoardView(props: PluginSurfaceProps) {
           open={activeTaskSession !== null}
           onClose={() => setActiveTaskSession(null)}
           session={activeTaskSession}
-          projects={projects}
+          projects={selectableProjects}
           theme={theme}
           layout={layout}
         />

package/client/kanban-drag.ts

@@ -90,7 +90,6 @@ export interface TaskPreviewItem {
 
 export interface KanbanDragOptions {
   lanes?: ({ id: string } | string)[];
-  onMoveTask?: (taskId: string, targetLaneId: string) => void | Promise<void>;
   onReorderTask?: (
     taskId: string,
     targetLaneId: string,
@@ -175,10 +174,6 @@ export class KanbanDragController {
   private containerRef: ContainerRefTarget | null = null;
   private scrollX: number = 0;
   private activeSession: ActiveDragSession | null = null;
-  private onMoveTask?: (
-    taskId: string,
-    targetLaneId: string,
-  ) => void | Promise<void>;
   private onReorderTask?: (
     taskId: string,
     targetLaneId: string,
@@ -231,9 +226,6 @@ export class KanbanDragController {
     if (options?.lanes) {
       this.setLanes(options.lanes);
     }
-    if (options?.onMoveTask) {
-      this.setOnMoveTask(options.onMoveTask);
-    }
     if (options?.onReorderTask) {
       this.setOnReorderTask(options.onReorderTask);
     }
@@ -253,12 +245,6 @@ export class KanbanDragController {
     }
   };
 
-  setOnMoveTask = (
-    fn: (taskId: string, targetLaneId: string) => void | Promise<void>,
-  ) => {
-    this.onMoveTask = fn;
-  };
-
   setOnReorderTask = (
     fn: (
       taskId: string,
@@ -908,8 +894,6 @@ export class KanbanDragController {
             drop.targetLaneId,
             drop.targetIndex,
           );
-        } else if (this.onMoveTask && drop.targetLaneId !== drop.sourceLaneId) {
-          await this.onMoveTask(drop.taskId, drop.targetLaneId);
         }
       }
     } finally {
@@ -1396,21 +1380,17 @@ export interface UseKanbanDragReturn {
 export function useKanbanDrag(
   options: KanbanDragOptions = {},
 ): UseKanbanDragReturn {
-  const { lanes = [], onMoveTask, onReorderTask, getTaskPreview } = options;
+  const { lanes = [], onReorderTask, getTaskPreview } = options;
   const controllerRef = useRef<KanbanDragController | null>(null);
   if (!controllerRef.current) {
     controllerRef.current = new KanbanDragController({
       lanes,
-      onMoveTask,
       onReorderTask,
     });
   }
   const controller = controllerRef.current;
 
   controller.setLanes(lanes);
-  if (onMoveTask) {
-    controller.setOnMoveTask(onMoveTask);
-  }
   if (onReorderTask) {
     controller.setOnReorderTask(onReorderTask);
   }

package/client/kanban-workspace-panel.tsx

@@ -0,0 +1,13 @@
+import {
+  useWorkspace,
+  type PluginWorkspacePanelProps,
+} from "@getpaseo/plugin/client";
+import { KanbanBoardView } from "./kanban-board";
+
+export function KanbanWorkspacePanel(props: PluginWorkspacePanelProps) {
+  const projectId = useWorkspace(
+    props.workspaceId,
+    (workspace) => workspace.projectId,
+  );
+  return <KanbanBoardView {...props} initialProjectId={projectId} />;
+}

package/index.client.tsx

@@ -1,33 +1,45 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { KanbanBoardView } from "./client/kanban-board";
+import { KanbanWorkspacePanel } from "./client/kanban-workspace-panel";
 import { t, getLanguage, subscribeLanguage } from "./client/i18n";
 
 export default function contribute(client: PluginClientContext) {
-  client.addSurface("kanban", KanbanBoardView);
-
+  const removeSurface = client.addSurface("kanban", KanbanBoardView);
   let currentLang = getLanguage();
-  let removeSidebar = client.addSidebarItem({
-    id: "kanban",
-    title: t("kanban.sidebarTitle", currentLang),
-    icon: "PanelsTopLeft",
-    surface: "kanban",
-  });
 
+  const registerEntries = () => {
+    const title = t("kanban.sidebarTitle", currentLang);
+    const removeSidebar = client.addSidebarItem({
+      id: "kanban",
+      title,
+      icon: "PanelsTopLeft",
+      surface: "kanban",
+    });
+    const removePanel = client.addWorkspacePanel({
+      id: "kanban",
+      title,
+      icon: "PanelsTopLeft",
+      context: "workspace",
+      Component: KanbanWorkspacePanel,
+    });
+    return () => {
+      removeSidebar();
+      removePanel();
+    };
+  };
+
+  let removeEntries = registerEntries();
   const unsubscribe = subscribeLanguage((newLang) => {
     if (newLang !== currentLang) {
       currentLang = newLang;
-      removeSidebar();
-      removeSidebar = client.addSidebarItem({
-        id: "kanban",
-        title: t("kanban.sidebarTitle", newLang),
-        icon: "PanelsTopLeft",
-        surface: "kanban",
-      });
+      removeEntries();
+      removeEntries = registerEntries();
     }
   });
 
   return () => {
     unsubscribe();
-    removeSidebar();
+    removeEntries();
+    removeSurface();
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-kanban",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A lightweight, responsive Kanban board plugin for Paseo workspaces",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,7 @@
     "board"
   ],
   "files": [
+    "OVERVIEW.md",
     "paseo-plugin.json",
     "index.client.tsx",
     "index.server.ts",
@@ -33,6 +34,7 @@
     "format:check": "prettier --check .",
     "format": "prettier --write .",
     "check:package": "node scripts/check-package.mjs",
+    "verify:release": "node scripts/verify-release.mjs",
     "check": "npm run typecheck && npm run test && npm run lint && npm run format:check && npm run check:package"
   },
   "devDependencies": {