paseo-beads 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cuongntr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# paseo-beads
+
+A read-only Beads console for Paseo workspaces. For the workspace you are in it shows how far
+along the project is per parent issue, what is in progress, what can start now, how the project's
+own labels spread over open work, and the critical chain of dependencies; a whole-project board
+by work state;
+execution tracks; risks; issue search; Markdown-rendered issue detail; and a composer attachment
+source for Beads issues.
+
+The plugin never invokes a mutating `br` or `bd` command. There is no claim, close,
+update, or create path in the code. `bv` may refresh its own compatibility export while
+loading a `bd`/Dolt workspace, so `bv` calls are serialized per workspace.
+
+## Screenshots
+
+Shown on a made-up demo project.
+
+**Overview**: progress per parent, what is in progress, held and ready now, the project's labels
+over open work, and the critical chain.
+
+![Overview](images/overview.png)
+
+**Board**: one column per work state in the order work moves, filtered by parent or label, each
+column with its definition.
+
+![Board](images/board.png)
+
+**Plan**: `bv`'s parallel execution tracks, containers left out.
+
+![Plan](images/plan.png)
+
+**Risks**: stuck and parked work, alerts by severity, and the keystones that unblock the most.
+
+![Risks](images/risks.png)
+
+## Requirements
+
+- Paseo `>=0.8.0` (daemon and app).
+- The [`bv`](https://github.com/Dicklesworthstone/beads_viewer) analysis CLI on the daemon machine's `PATH`.
+  Verified against `bv v0.25.0`.
+- A project that uses Beads through `br` or `bd`. The tracker CLI matching the project must
+  also be on the daemon `PATH` for issue detail and for issue types and assignees; everything
+  else works without it.
+
+Everything else degrades gracefully: a missing `bv`, a workspace without a `.beads` source,
+and an empty-but-healthy project are three distinct, clearly labelled states.
+
+## Install
+
+```bash
+paseo plugin add cuongntr/paseo-beads-viewer
+paseo plugin ls paseo-beads     # expect paseo-beads running
+```
+
+Update to the latest release with `paseo plugin update paseo-beads`. If the panel does not
+appear, `paseo plugin logs paseo-beads` shows why; the most common cause is `bv` missing from
+the daemon's `PATH`.
+
+To run a local checkout instead:
+
+```bash
+npm install && npm run typecheck && npm test
+paseo plugin install /absolute/path/to/paseo-beads
+```
+
+After editing source, run `paseo plugin reload paseo-beads`.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+Mobile audit — a hit here is a bug:
+
+```bash
+rg -n "document\.|window\.|localStorage|navigator\.|<[a-z]+[ >]|className=|onClick=" client/
+```
+
+## What it contributes
+
+| Contribution | Where |
+| --- | --- |
+| Workspace panel `beads` ("Beads") | Workspace tab bar and the Explorer |
+| Command Center: **Open Beads** | Workspace context |
+| Command Center: **Refresh Beads triage** | Workspace context; re-reads `bv` then opens the panel |
+| Slash command `/beads` | Opens the panel for the current workspace |
+| Slash command `/bead <issue-id>` | Opens the panel with that issue selected |
+| Attachment source **Beads issue** | Composer attachment picker |
+
+## Security and read-only behaviour
+
+- Only the daemon-side `server/` code touches Node, the process table, or the filesystem.
+  Client code imports no Node module.
+- Subprocesses are spawned with `spawn` using a **literal argv** and an absolute executable
+  path resolved by scanning `PATH` directly. `shell` is never enabled, so no input can be
+  interpreted as a shell operator.
+- The working directory always comes from Paseo's own workspace record
+  (`paseo.workspaces.ref(id).refresh()`), never from client input, and must be an existing
+  absolute directory.
+- Only an explicit allowlist of read-only commands can run: `bv --version`,
+  `bv --robot-triage`, `bv --robot-plan`, `bv --robot-alerts`, `bv --robot-graph`,
+  `bv --robot-search`,
+  `<tracker> --db <validated-route> list --status all --fields id,issue_type,assignee --format csv`,
+  and `<tracker> --db <validated-route> show --json -- <id>`. `br` reads also pass
+  `--no-auto-import --no-auto-flush`. Bare `bv` is never invoked. Neither tracker argv takes any
+  user input beyond the validated route and, for `show`, a pattern-checked issue id.
+- The search query is whitespace-collapsed, control-character-stripped, length-bounded, and
+  passed as a single argv value. Issue ids are pattern-checked and passed after `--` so an id
+  can never be read as a flag.
+- `bv` calls clear inherited `BEADS_DIR`, `BEADS_DB`, `BEADS_JSONL`, and `BD_DB` values so
+  daemon-level environment configuration cannot redirect a workspace read. Tracker detail calls set those
+  variables only to the validated route.
+- Every subprocess has a timeout and an output size cap, and is killed when either is
+  exceeded. Unavailable binary, timeout, non-zero exit, oversized output, and malformed JSON
+  are reported as distinct error codes. Plugin cleanup kills any process still running.
+- Plugin code never parses or writes `.beads/*.jsonl` or a Beads SQLite/Dolt database. It reads
+  only `.beads/metadata.json` to bind tracker identity to `bv`'s selected source; issue data comes
+  from CLI output. `bv` itself may refresh a `bd` compatibility export, so its calls are serialized.
+- `bv --robot-*` is the authority for ranking, recommendations, execution tracks, alerts, cycle
+  detection, and velocity. The plugin derives only each issue's work state (from its status and
+  its still-open blockers) and the longest remaining dependency chain, because `bv`'s own counts
+  treat dependency-blocked work as unblocked and containers as ready; see the design doc. `bv` and its `source_authority`, freshness, and `data_hash` are shown as
+  reported.
+- Only short-lived normalized command results are cached (15 s for the dashboard, 2 min for
+  tracker identity and its validated route), invalidated purely by expiry. No derived graph is
+  ever cached.
+
+## Limitations
+
+- Read-only by design. Claiming, closing, and editing issues stay in `br`/`bd`.
+- Issue detail requires an exact tracker and database route. The plugin checks `bv`, then the
+  selected source's `.beads/metadata.json`; if identity or routing remains inconclusive, detail
+  reads are disabled rather than guessed.
+- Attachment search has no workspace context, so it scans a bounded set of recently active
+  Paseo workspaces, searches at most 4 Beads-enabled ones, and returns at most 8 items. An
+  issue in a workspace outside that window will not appear.
+- Search relevance, ranking, and analysis semantics are entirely `bv`'s; the plugin only
+  reshapes them.
+- Statuses, readiness values, and alert severities are treated as opaque strings, so a newer
+  `bv` renders without a plugin update but without bespoke styling for new values.
+- The panel serves any Beads project, so it interprets only what Beads and `bv` define and what
+  the data's structure says. Statuses are Beads' built-in set (`open`, `in_progress`, `hooked`,
+  `blocked`, `deferred`, `draft`, `pinned`, `closed`, `tombstone`); a custom status declared in a
+  project's `.beads/policy.yaml` is shown verbatim under **Other status**, not guessed to be ready
+  or done. Groups follow parent links, never type names or id patterns. Labels are the project's
+  own vocabulary: they are shown and counted as written, a label carried by every open item is
+  set aside as uninformative, and no label is given a meaning — so there is no built-in "needs a
+  human". To keep agents off some work, use `bv`'s own `BV_ROBOT_NOT_READY_LABELS`, which the
+  panel's `bv` reads inherit.
+- Work states, in Beads' own terms (Ready and Waiting match `br ready` and `br blocked`):
+  **Ready** — status `open`, and nothing it depends on is still open. **Waiting** — status
+  `open`, but a dependency, or one of its parent's, is still open; a parent's dependency on its
+  own children does not count. **In progress** — `in_progress` or `hooked`. **Held** — status
+  set by hand to `blocked`, `deferred`, `draft` or `pinned`. **Other status** — a custom status.
+  **Done** — `closed`. Each Board column shows its definition under its title.
+- The **Board** is a plain board: one column per work state in the order work moves — Ready,
+  Waiting, In progress, Held and Other status (each only when non-empty), and Done (only with
+  **Show done**) — each column
+  one list that scrolls on its own, with no swimlanes. A **Filter** narrows every column at once
+  to one parent's subtree or one of the project's labels; each card names its parent. On a phone
+  the columns become a state picker over one list. Issues that other issues name as parent are
+  filter options and card context, never cards. Each column renders at most 60 cards with the
+  rest reported as `+N more`, and a project past 2000 issues drops closed issues from the payload
+  first and says so. If the graph read fails, the panel falls back to the triage and plan
+  working set and says so. It is read-only: no drag, no drop, no status change.
+- Issue prose renders through a bounded in-repo Markdown subset (headings h1–h3, lists, task
+  items, quotes, rules, code, bold, italic, links). HTML, images, and tables are not rendered,
+  and link targets are shown as text — the panel never opens a URL.

package/client/board-view.tsx

@@ -0,0 +1,290 @@
+import type { PluginTheme } from "@getpaseo/plugin";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import { useState, type ReactNode } from "react";
+import { Pressable, ScrollView, Text, View } from "react-native";
+import {
+  boardFilters,
+  filterKey,
+  parentLabel,
+  type BoardColumn,
+  type BoardFilter,
+  type BoardModel,
+} from "./board";
+import { stateDescription, stateIconName, stateLabel, stateTone, toneColor } from "./format";
+import type { ProjectModel, WorkItem, WorkState } from "./project";
+import { Empty, facetContext, WorkFacets, workAccessibility, type FacetContext } from "./rows";
+import type { PanelStyles } from "./styles";
+
+/**
+ * Read-only project board: one column per work state, each an independent
+ * list, narrowed by one filter. On a compact panel the columns become a state
+ * picker over a single list, as board apps do on a phone. There is no drag,
+ * drop, or mutation affordance anywhere in this file.
+ */
+export function BoardView({
+  styles,
+  theme,
+  project,
+  board,
+  compact,
+  selectedId,
+  onSelect,
+  onFilterChange,
+  onShowDoneChange,
+}: {
+  readonly styles: PanelStyles;
+  readonly theme: PluginTheme;
+  readonly project: ProjectModel;
+  readonly board: BoardModel;
+  readonly compact: boolean;
+  readonly selectedId: string | null;
+  readonly onSelect: (issueId: string) => void;
+  readonly onFilterChange: (filter: BoardFilter) => void;
+  readonly onShowDoneChange: (showDone: boolean) => void;
+}) {
+  // Compact shows one column at a time; start where work can be picked up.
+  const [compactState, setCompactState] = useState<WorkState>("ready");
+  const context = facetContext(project);
+  const activeKey = filterKey(board.filter);
+
+  const caveats = [
+    project.complete
+      ? null
+      : "Whole-project graph unavailable: only triage picks and plan items appear, without their parents, so containers among them cannot be told from work.",
+    project.truncated ? "Some closed issues were left out to bound the payload; open work is all here." : null,
+  ].filter((line): line is string => line !== null);
+
+  const controls = (
+    <View style={compact ? styles.boardHeaderStacked : styles.boardHeader}>
+      <View style={styles.boardControlRow}>
+        <Text style={styles.segmentCaption}>Filter</Text>
+        <ScrollView
+          horizontal
+          style={styles.filterScroll}
+          contentContainerStyle={styles.filterRow}
+          accessibilityRole="tablist"
+          accessibilityLabel="Filter the board"
+        >
+          {boardFilters(project).map((option) => {
+            const selected = option.key === activeKey;
+            return (
+              <Pressable
+                key={option.key}
+                accessibilityRole="tab"
+                accessibilityState={{ selected }}
+                accessibilityLabel={`Show ${option.label}, ${option.live} open`}
+                onPress={() => onFilterChange(option.filter)}
+                style={({ pressed }) => [
+                  styles.filterChip,
+                  option.filter.kind === "label" ? styles.filterChipLabel : null,
+                  selected ? styles.filterChipSelected : null,
+                  pressed ? styles.actionPressed : null,
+                ]}
+              >
+                <Text
+                  style={selected ? styles.segmentLabelSelected : styles.segmentLabel}
+                  numberOfLines={1}
+                >
+                  {option.depth > 0 ? "› " : ""}
+                  {option.label}
+                </Text>
+                <Text style={styles.switcherCount}>{option.live}</Text>
+              </Pressable>
+            );
+          })}
+        </ScrollView>
+        <Pressable
+          accessibilityRole="switch"
+          accessibilityState={{ checked: board.showDone }}
+          accessibilityLabel="Show finished work"
+          onPress={() => onShowDoneChange(!board.showDone)}
+          style={({ pressed }) => [
+            styles.filterChip,
+            board.showDone ? styles.filterChipSelected : null,
+            pressed ? styles.actionPressed : null,
+          ]}
+        >
+          <Text style={board.showDone ? styles.segmentLabelSelected : styles.segmentLabel}>
+            {board.showDone ? "Showing done" : "Show done"}
+          </Text>
+        </Pressable>
+      </View>
+      {caveats.map((line) => (
+        <Text key={line} style={styles.muted}>
+          {line}
+        </Text>
+      ))}
+    </View>
+  );
+
+  if (project.work.length === 0) {
+    return (
+      <View style={compact ? styles.boardStack : styles.boardPane}>
+        {controls}
+        <View style={compact ? styles.stateBlock : styles.paneContent}>
+          <Empty styles={styles} theme={theme} message="bv reported no issues in this project, so there is nothing to lay out." />
+        </View>
+      </View>
+    );
+  }
+
+  const card = (item: WorkItem, showState: boolean) => (
+    <Card
+      key={item.id}
+      styles={styles}
+      theme={theme}
+      item={item}
+      // The chosen parent is already the whole board's context.
+      parent={board.filter.kind === "parent" && board.filter.id === item.parentId ? null : parentLabel(item, project)}
+      showState={showState}
+      context={context}
+      selected={selectedId === item.id}
+      onSelect={onSelect}
+    />
+  );
+
+  if (compact) {
+    const shown = board.columns.find((column) => column.state === compactState) ?? board.columns[0];
+    return (
+      <View style={styles.boardStack}>
+        {controls}
+        <View style={styles.segmentRow} accessibilityRole="tablist" accessibilityLabel="Board column">
+          {board.columns.map((column) => {
+            const selected = column.state === shown?.state;
+            return (
+              <Pressable
+                key={column.state}
+                accessibilityRole="tab"
+                accessibilityState={{ selected }}
+                accessibilityLabel={`${stateLabel(column.state)}, ${column.total}`}
+                onPress={() => setCompactState(column.state)}
+                style={({ pressed }) => [
+                  styles.segmentItem,
+                  styles.segmentItemGrow,
+                  selected ? styles.segmentItemSelected : null,
+                  pressed ? styles.actionPressed : null,
+                ]}
+              >
+                <Text style={selected ? styles.segmentLabelSelected : styles.segmentLabel} numberOfLines={1}>
+                  {stateLabel(column.state)} {column.total}
+                </Text>
+              </Pressable>
+            );
+          })}
+        </View>
+        {shown === undefined ? null : (
+          <View style={styles.boardColumnBody}>
+            <Text style={styles.boardColumnHint}>{stateDescription(shown.state)}</Text>
+            {shown.cards.length === 0 ? <Text style={styles.muted}>Nothing here.</Text> : null}
+            {shown.cards.map((item) => card(item, false))}
+            <MoreNote styles={styles} hidden={shown.hidden} />
+          </View>
+        )}
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.boardPane}>
+      {controls}
+      <View style={styles.boardColumns}>
+        {board.columns.map((column) => (
+          <Column key={column.state} styles={styles} theme={theme} column={column}>
+            {column.cards.map((item) => card(item, false))}
+          </Column>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+/** One state's column: a fixed header over its own scrolling list. */
+function Column({
+  styles,
+  theme,
+  column,
+  children,
+}: {
+  readonly styles: PanelStyles;
+  readonly theme: PluginTheme;
+  readonly column: BoardColumn;
+  readonly children: ReactNode;
+}) {
+  const tone = stateTone(column.state);
+  return (
+    <View style={styles.boardColumn}>
+      <View
+        style={styles.boardColumnHead}
+        accessibilityRole="header"
+        accessibilityLabel={`${stateLabel(column.state)}, ${column.total}. ${stateDescription(column.state)}`}
+      >
+        <View style={styles.boardColumnHeader}>
+          <Icon
+            name={stateIconName(column.state)}
+            size={13}
+            color={tone === "neutral" ? theme.colors.foregroundMuted : toneColor(theme, tone)}
+          />
+          <Text style={styles.boardColumnTitle}>{stateLabel(column.state)}</Text>
+          <Text style={styles.boardColumnCount}>{column.total}</Text>
+        </View>
+        <Text style={styles.boardColumnHint}>{stateDescription(column.state)}</Text>
+      </View>
+      <ScrollView style={styles.boardScroll} contentContainerStyle={styles.boardColumnBody}>
+        {column.total === 0 ? <Text style={styles.muted}>Nothing here.</Text> : null}
+        {children}
+        <MoreNote styles={styles} hidden={column.hidden} />
+      </ScrollView>
+    </View>
+  );
+}
+
+function MoreNote({ styles, hidden }: { readonly styles: PanelStyles; readonly hidden: number }) {
+  if (hidden === 0) return null;
+  return <Text style={styles.muted}>+{hidden} more. Narrow the filter or search to reach them.</Text>;
+}
+
+function Card({
+  styles,
+  theme,
+  item,
+  parent,
+  showState,
+  context,
+  selected,
+  onSelect,
+}: {
+  readonly styles: PanelStyles;
+  readonly theme: PluginTheme;
+  readonly item: WorkItem;
+  /** The parent's title, shown as the card's context; null when it would repeat the filter. */
+  readonly parent: string | null;
+  readonly showState: boolean;
+  readonly context: FacetContext;
+  readonly selected: boolean;
+  readonly onSelect: (issueId: string) => void;
+}) {
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityState={{ selected }}
+      accessibilityLabel={`${workAccessibility(item)}${parent === null ? "" : `, in ${parent}`}`}
+      onPress={() => onSelect(item.id)}
+      style={({ pressed }) => [styles.boardCard, selected || pressed ? styles.boardCardSelected : null]}
+    >
+      <View style={[styles.boardCardRail, { backgroundColor: toneColor(theme, stateTone(item.state)) }]} />
+      <View style={styles.boardCardBody}>
+        {parent === null ? null : (
+          <Text style={styles.boardCardParent} numberOfLines={1}>
+            {parent}
+          </Text>
+        )}
+        <Text style={styles.boardCardTitle} numberOfLines={2}>
+          {item.title}
+        </Text>
+        <View style={styles.facetRow}>
+          <WorkFacets styles={styles} theme={theme} item={item} showState={showState} context={context} />
+        </View>
+      </View>
+    </Pressable>
+  );
+}

package/client/board.ts

@@ -0,0 +1,160 @@
+/**
+ * Board layout for the read-only project board: a plain board, one column per
+ * derived {@link WorkState}, each column one continuous list.
+ *
+ * Columns are the derived state, not the raw status: on a real project every
+ * live issue had status `open`, so a status board was one column of 27 cards
+ * that could not tell ready work from work waiting on three others.
+ *
+ * Grouping is a filter, not swimlanes. A lanes × columns matrix left most cells
+ * empty, repeated a card in every label lane it carried, and made the reader
+ * scan two ways at once; the usual boards (GitHub Projects, Linear, Jira) keep
+ * swimlanes off by default for the same reasons. Each card names its parent
+ * instead, and choosing a parent or a label narrows every column at once.
+ *
+ * Only work is carded; a container is a filter option and a card's context.
+ * Everything is pure for the Vitest node environment.
+ */
+import { countStates, WORK_STATES, type ProjectModel, type StateCounts, type WorkItem, type WorkState } from "./project";
+
+/** What the board is narrowed to: everything, one parent's subtree, or one label. */
+export type BoardFilter =
+  | { readonly kind: "all" }
+  | { readonly kind: "parent"; readonly id: string }
+  | { readonly kind: "label"; readonly label: string };
+
+export const ALL_WORK: BoardFilter = { kind: "all" };
+
+export interface BoardFilterOption {
+  readonly key: string;
+  readonly filter: BoardFilter;
+  readonly label: string;
+  /** Unfinished work the option would show. */
+  readonly live: number;
+  /** Nesting depth for parents: 0 for a top-level issue. */
+  readonly depth: number;
+}
+
+/** Cards rendered per column before the rest is reported as "+N more". */
+export const BOARD_COLUMN_CARD_LIMIT = 60;
+
+export interface BoardColumn {
+  readonly state: WorkState;
+  readonly cards: readonly WorkItem[];
+  readonly total: number;
+  readonly hidden: number;
+}
+
+export interface BoardModel {
+  /** The filter applied, which falls back to all work when the chosen one no longer matches. */
+  readonly filter: BoardFilter;
+  /** Columns to render, in {@link WORK_STATES} order. */
+  readonly columns: readonly BoardColumn[];
+  /** Work per state under the filter. */
+  readonly counts: StateCounts;
+  readonly showDone: boolean;
+}
+
+export function filterKey(filter: BoardFilter): string {
+  switch (filter.kind) {
+    case "all":
+      return "all";
+    case "parent":
+      return `parent:${filter.id}`;
+    case "label":
+      return `label:${filter.label}`;
+  }
+}
+
+/**
+ * Filters this project's data supports: every parent that still has open
+ * work, nested under its top-level issue in plan order, then the project's own
+ * labels, most used first. Nothing here comes from a fixed list.
+ */
+export function boardFilters(project: ProjectModel): readonly BoardFilterOption[] {
+  const options: BoardFilterOption[] = [
+    {
+      key: "all",
+      filter: ALL_WORK,
+      label: "All work",
+      live: project.work.length - project.counts.done,
+      depth: 0,
+    },
+  ];
+  for (const root of project.roots) {
+    if (root.id === null || root.settled) continue;
+    options.push(parentOption(root.id, root.title, root.total - root.done, 0));
+    for (const pkg of root.packages) {
+      if (pkg.id === null || pkg.id === root.id || pkg.settled) continue;
+      options.push(parentOption(pkg.id, pkg.title, pkg.total - pkg.done, 1));
+    }
+  }
+  for (const stat of project.labels) {
+    const filter: BoardFilter = { kind: "label", label: stat.label };
+    options.push({ key: filterKey(filter), filter, label: stat.label, live: stat.live, depth: 0 });
+  }
+  return options;
+}
+
+function parentOption(id: string, title: string, live: number, depth: number): BoardFilterOption {
+  const filter: BoardFilter = { kind: "parent", id };
+  return { key: filterKey(filter), filter, label: title, live, depth };
+}
+
+export function buildBoard(project: ProjectModel, filter: BoardFilter, showDone: boolean): BoardModel {
+  // A filter chosen on an earlier read may have nothing left to match.
+  const known = boardFilters(project).some((option) => option.key === filterKey(filter));
+  const active = known ? filter : ALL_WORK;
+  const items = project.work.filter((item) => matches(item, active, project));
+  const counts = countStates(items);
+
+  // Held and other statuses are exceptions, so their columns appear only when
+  // something is in them. Done is a column only on request.
+  const states = WORK_STATES.filter((state) => {
+    if (state === "held") return counts.held > 0;
+    if (state === "other") return counts.other > 0;
+    if (state === "done") return showDone;
+    return true;
+  });
+
+  const columns = states.map((state) => {
+    // Work arrives in project order, which is already the in-column order.
+    const inState = items.filter((item) => item.state === state);
+    return {
+      state,
+      cards: inState.slice(0, BOARD_COLUMN_CARD_LIMIT),
+      total: inState.length,
+      hidden: Math.max(0, inState.length - BOARD_COLUMN_CARD_LIMIT),
+    };
+  });
+
+  return { filter: active, columns, counts, showDone };
+}
+
+function matches(item: WorkItem, filter: BoardFilter, project: ProjectModel): boolean {
+  switch (filter.kind) {
+    case "all":
+      return true;
+    case "label":
+      return item.labels.includes(filter.label);
+    case "parent":
+      return hasAncestor(item, filter.id, project);
+  }
+}
+
+/** True when `id` is on the item's parent chain; a cyclic chain ends the walk. */
+function hasAncestor(item: WorkItem, id: string, project: ProjectModel): boolean {
+  const visited = new Set<string>([item.id]);
+  for (let parent = item.parentId; parent !== null && !visited.has(parent); ) {
+    if (parent === id) return true;
+    visited.add(parent);
+    parent = project.byId.get(parent)?.parentId ?? null;
+  }
+  return false;
+}
+
+/** A card's context line: its direct parent's title, or its id when the parent is not loaded. */
+export function parentLabel(item: WorkItem, project: ProjectModel): string | null {
+  if (item.parentId === null) return null;
+  return project.byId.get(item.parentId)?.title ?? item.parentId;
+}