@anchrd/intel-ui 0.38.0 → 0.40.0

package/src/board/board-panel/board-panel.tsx

@@ -1,74 +1,265 @@
 import type { BoardTaskFilter } from "@anchrd/intel-contract/board";
 import type { Node } from "@anchrd/intel-contract/node";
-import { useState } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import type { ColumnVisibilityState } from "@tanstack/react-table";
+import { KanbanSquare, Settings, Table2 } from "lucide-react";
+import { Suspense, useCallback, useState } from "react";
+import { ActionSlot } from "@/app/action-slot/action-slot.tsx";
 import { useBoard } from "@/board/board-data/board-data.ts";
 import { BoardKanban } from "@/board/board-kanban/board-kanban.tsx";
-import type { GroupKey, Sort } from "@/board/board-table/board-table.ts";
+import { BoardSettings } from "@/board/board-settings/board-settings.tsx";
 import { BoardTable } from "@/board/board-table/board-table.tsx";
+import { BoardTaskDocument } from "@/board/board-task/board-task.tsx";
 import { useI18n } from "@/i18n/i18n-context.tsx";
+import { NodeEditor } from "@/node-editor/node-editor.tsx";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+import { openTaskFrom } from "@/router/selection-search.ts";
 
 type View = "kanban" | "table";
 
+const views = [
+  { name: "kanban", Icon: KanbanSquare },
+  { name: "table", Icon: Table2 },
+] as const;
+
 /**
  * A board on the node screen, beside the folder, the table and the editor (D66, #376).
  *
  * ⚠️ The whole board is ONE answer. `board_get` returns the columns and every card in them, and the
- * views below read that one object — no view fetches per card, per column, or on scroll. A board
- * that loaded its cards one by one would look exactly the same on screen and be a different thing
- * over the wire, which is why `board-panel.unit.tsx` counts the calls rather than the cards.
+ * views below read that one object — no view fetches per card, per column, or on scroll.
+ *
+ * ⚠️ **The controls live in the title line, not in a row of their own** (#363). `title-actions` puts
+ * them before the three-dot menu, which is where everything that acts on THIS thing already sits —
+ * a third bar above the board would be a permanent row for something nobody uses twice a minute.
  */
 export function BoardPanel({ node }: { node: Node }) {
   const i18n = useI18n();
   const [view, setView] = useState<View>("kanban");
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  // Which columns the table shows outlives the trip through the kanban — see `BoardTable`.
+  const [hidden, setHidden] = useState<ColumnVisibilityState>({});
+  /**
+   * ⚠️ **The filter lives HERE and not in the table, since #671.** Opening a card unmounts the
+   * table, so a filter kept down there was silently thrown away by the one control that is the only
+   * way back out. It does NOT reach the kanban: that view reads this component's own unfiltered
+   * board answer, a different query — which is what kept the filter out of it before, and still is.
+   */
+  const [filter, setFilter] = useState<Partial<BoardTaskFilter>>({});
+  const board = useBoard(node.id);
+  const search = useSearch({ strict: false });
+  const navigate = useNavigate();
+  const openId = openTaskFrom(search);
+
+  /**
+   * ⚠️ **The address, not a piece of state.** A task opened into component state would have no link
+   * and no back button — the browser's back would leave the board entirely, which is the one thing
+   * somebody pressing it after opening a card does not want.
+   */
+  const open = useCallback(
+    (taskId: string | null) =>
+      void navigate({
+        to: ".",
+        // ⚠️ **Closing REPLACES, opening pushes.** Opening a card is a step somebody took and the
+        // back button must undo it; closing is the undo itself. Pushed as well, the history holds
+        // board → card → board, and one press of Back re-opens the card that was just closed —
+        // exactly the behaviour the address was chosen to avoid.
+        replace: taskId === null,
+        search: (previous: Record<string, unknown>) =>
+          taskId === null ? { ...previous, task: undefined } : { ...previous, task: taskId },
+      }),
+    // ⚠️ Stable, or the table's `useMemo` over its columns rebuilds on every render and the memo
+    // is decoration.
+    [navigate],
+  );
+
   return (
     <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
-      {/* No wrapper role: the house switch (`view-toggle.tsx`) carries none either, and a `group`
-          on a plain `div` is the shape a linter rightly asks to be a `fieldset`. What names the
-          control is each button — its own text, plus `aria-pressed` for which view is showing. */}
-      <div className="flex shrink-0 items-center gap-1 border-b px-4 py-2">
-        {(["kanban", "table"] as const).map((name) => (
+      <ActionSlot name="title-actions">
+        {/* ⚠️ **Gone while a card is open.** The switch chooses between two views OF THE BOARD, and
+            an open card is neither — left standing it reports `aria-pressed` for a view nobody is
+            looking at and does nothing when pressed, which is a control that lies twice. */}
+        {(openId === null ? views : []).map(({ name, Icon }) => (
           <button
             key={name}
             type="button"
             aria-pressed={view === name}
+            aria-label={i18n.t(`board.view.${name}`)}
             onClick={() => setView(name)}
-            className="rounded-md px-3 py-1 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring aria-pressed:bg-muted aria-pressed:font-medium"
+            className="inline-flex size-8 items-center justify-center rounded-md outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring aria-pressed:bg-accent"
           >
-            {i18n.t(`board.view.${name}`)}
+            <Icon aria-hidden="true" className="size-4" />
           </button>
         ))}
-      </div>
-      {view === "kanban" ? <KanbanView nodeId={node.id} /> : <TableView nodeId={node.id} />}
+        <button
+          type="button"
+          aria-label={i18n.t("board.settings.open")}
+          onClick={() => setSettingsOpen(true)}
+          className="inline-flex size-8 items-center justify-center rounded-md outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <Settings aria-hidden="true" className="size-4" />
+        </button>
+      </ActionSlot>
+      {/* ⚠️ Mounted only while open, so its draft is seeded once per opening. Handed an `open` flag
+          instead, a draft re-seeded from the board would lose what somebody typed the moment a
+          write from elsewhere answers. */}
+      {settingsOpen ? <BoardSettings board={board} onClose={() => setSettingsOpen(false)} /> : null}
+      {openId === null ? (
+        view === "kanban" ? (
+          <KanbanView board={board} onOpen={open} />
+        ) : (
+          <TableView
+            nodeId={node.id}
+            hidden={hidden}
+            onHidden={setHidden}
+            onOpen={open}
+            filter={filter}
+            onFilter={setFilter}
+          />
+        )
+      ) : (
+        // ⚠️ Drawn from the panel's own UNFILTERED board answer, which is also what the kanban
+        // reads — the open task is not a second read of the card. ⚠️ It is NOT the table's answer:
+        // the table keeps its own filtered query, so a card filtered out of the table still opens
+        // from a link. What this cannot find is a card that is gone, or one on another board.
+        <OpenTask board={board} taskId={openId} onOpen={open} />
+      )}
     </div>
   );
 }
 
-function KanbanView({ nodeId }: { nodeId: string }) {
-  const board = useBoard(nodeId);
-  return <BoardKanban board={board} />;
+function KanbanView({
+  board,
+  onOpen,
+}: {
+  board: ReturnType<typeof useBoard>;
+  onOpen(taskId: string): void;
+}) {
+  return <BoardKanban board={board} onOpen={onOpen} />;
 }
 
 /**
- * ⚠️ **The filter lives HERE, inside the table's own branch, not beside both views.** Held one
- * level up it would survive a switch to the kanban board — which draws whatever the query answered
- * and would then show a column full and the rest empty, with nothing on screen saying why. That is
- * the quiet failure: cards that look deleted. Unmounting the table takes its filter with it, and
- * the kanban asks for the whole board every time.
+ * One card, opened.
+ *
+ * ⚠️ **The body is the node's own document and is the ONE thing this screen reads separately.** The
+ * head and the link list come out of `board_get`; the markdown text does not live in that answer at
+ * all — a card's text is a node version, and `board_get` returns cards, not documents.
  */
-function TableView({ nodeId }: { nodeId: string }) {
-  const [filter, setFilter] = useState<Partial<BoardTaskFilter>>({});
-  const [sort, setSort] = useState<Sort | null>(null);
-  const [group, setGroup] = useState<GroupKey>("none");
+function OpenTask({
+  board,
+  taskId,
+  onOpen,
+}: {
+  board: ReturnType<typeof useBoard>;
+  taskId: string;
+  onOpen(taskId: string | null): void;
+}) {
+  const i18n = useI18n();
+  const task = board.columns.flatMap((entry) => entry.cards).find((card) => card.id === taskId);
+
+  if (board.isPending) {
+    return <p className="p-6 text-sm text-muted-foreground">{i18n.t("common.loading")}</p>;
+  }
+  // ⚠️ Back to the board rather than an empty screen. The board answer here is unfiltered, so a
+  // card missing from it is a card that is gone, archived out of view, or on a different board —
+  // a stale link and a deleted card look exactly the same from here, and both want the same way out.
+  if (task === undefined) {
+    return (
+      <div className="flex flex-col items-start gap-3 p-6">
+        <p className="text-sm text-muted-foreground">{i18n.t("board.taskGone")}</p>
+        <button
+          type="button"
+          onClick={() => onOpen(null)}
+          className="rounded-md border px-3 py-1 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          {board.title}
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <BoardTaskDocument
+      task={task}
+      board={board}
+      onOpen={onOpen}
+      onClose={() => onOpen(null)}
+      body={<TaskBody nodeId={task.id} />}
+    />
+  );
+}
+
+/**
+ * ⚠️ **The filter is handed DOWN since #671, and that is safe for a different reason than it looks.**
+ * It used to live here so that unmounting the table took it along — until opening a card, which
+ * also unmounts the table, threw the filter away through the one control that is the way back out.
+ * It sits in the panel now, and the kanban still shows everything: that view reads the panel's own
+ * unfiltered query, a different key, so no filtered answer ever reaches it. Measured, not argued —
+ * after a switch there is no new request at all, and `leaves the kanban unfiltered after a filter
+ * was set in the table` renders the whole panel, so it exercises exactly this arrangement.
+ */
+function TableView({
+  nodeId,
+  hidden,
+  onHidden,
+  onOpen,
+  filter,
+  onFilter,
+}: {
+  nodeId: string;
+  hidden: ColumnVisibilityState;
+  onHidden(next: ColumnVisibilityState): void;
+  onOpen(taskId: string): void;
+  filter: Partial<BoardTaskFilter>;
+  onFilter(next: Partial<BoardTaskFilter>): void;
+}) {
   const board = useBoard(nodeId, filter);
+  // ⚠️ Sorting and grouping live INSIDE the table since #670 — they are the table's own state and
+  // never travel. The column choice and the filter are handed DOWN from the panel because both have
+  // to outlive this component; the kanban stays unfiltered because it reads a different query.
   return (
     <BoardTable
       board={board}
       filter={filter}
-      onFilter={setFilter}
-      sort={sort}
-      onSort={setSort}
-      group={group}
-      onGroup={setGroup}
+      onFilter={onFilter}
+      hidden={hidden}
+      onHidden={onHidden}
+      onOpen={onOpen}
     />
   );
 }
+
+/**
+ * The card's markdown text — the node's own document, in the editor every other document uses.
+ *
+ * ⚠️ **A second read, and the only one on this screen.** `board_get` answers with cards, not with
+ * documents: a card's text is a node version and is not in that answer at all. Building a second
+ * editor here instead would be the more expensive mistake — one text surface that saves, links and
+ * renders differently from the one next door.
+ */
+function TaskBody({ nodeId }: { nodeId: string }) {
+  const i18n = useI18n();
+  const { data } = useIntelRouterContext();
+  const queryClient = useQueryClient();
+  const document = useQuery({
+    queryKey: ["node", nodeId],
+    queryFn: () => data.getNode(nodeId),
+  });
+
+  if (document.data === undefined) {
+    return <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>;
+  }
+  return (
+    <Suspense
+      fallback={<p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>}
+    >
+      <NodeEditor
+        key={nodeId}
+        data={data}
+        document={document.data}
+        i18n={i18n}
+        onSaved={(saved) => queryClient.setQueryData(["node", nodeId], saved)}
+      />
+    </Suspense>
+  );
+}

package/src/board/board-settings/board-settings.tsx

@@ -0,0 +1,209 @@
+import { ARCHIVE_COLUMN_ID, type BoardColumn } from "@anchrd/intel-contract/board";
+import { ChevronDown, ChevronUp, X } from "lucide-react";
+import { useState } from "react";
+import type { BoardHandle } from "@/board/board-data/board-data.types.ts";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+
+/**
+ * A board's basic settings: its columns, and whether the archive is drawn.
+ *
+ * ⚠️ **The whole list is written at once and never patched.** Adding, renaming and reordering are
+ * one call, because the ORDER is the list's order — there is nothing to patch a position with. So
+ * the dialog holds a draft and sends it on save; a control that wrote per keystroke would write a
+ * version per letter.
+ *
+ * ⚠️ **The archive column is not in this list and cannot be.** It is derived from `archived_at`
+ * (D68) and the server refuses a configured column that claims its id. What the switch below
+ * changes is only whether it is drawn.
+ */
+export function BoardSettings({ board, onClose }: { board: BoardHandle; onClose(): void }) {
+  const i18n = useI18n();
+  // ⚠️ Seeded once per OPENING, which is why the caller mounts this only while it is open rather
+  // than handing it an `open` flag: a draft re-seeded from a prop would lose what somebody typed
+  // the moment the board answers a write from somewhere else.
+  const [columns, setColumns] = useState<BoardColumn[]>(() =>
+    board.columns
+      .filter((entry) => entry.unknown !== true && entry.column.id !== ARCHIVE_COLUMN_ID)
+      .map((entry) => entry.column),
+  );
+  const [archiveVisible, setArchiveVisible] = useState(board.archiveVisible);
+  const [failed, setFailed] = useState(false);
+
+  /**
+   * How many cards each column carries, taken once from the board.
+   *
+   * ⚠️ **A column with cards is not removable here** — `destructive.md`: *verweigern schlägt
+   * kaskadieren*. Removed, its cards do not vanish from the database, but their `status` names a
+   * column nobody configured any more: they fall into the stray column, and nobody was asked where
+   * they should go. That is the same cascade one level delayed.
+   */
+  const cardsIn = new Map(board.columns.map((entry) => [entry.column.id, entry.cards.length]));
+
+  const move = (index: number, by: -1 | 1) => {
+    const next = [...columns];
+    const target = index + by;
+    const a = next[index];
+    const b = next[target];
+    if (a === undefined || b === undefined) return;
+    next[index] = b;
+    next[target] = a;
+    setColumns(next);
+  };
+
+  const save = () => {
+    setFailed(false);
+    void board
+      .setColumns({
+        columns: columns.map((column) => ({ ...column, title: column.title.trim() })),
+        archiveVisible,
+        idempotencyKey: crypto.randomUUID(),
+      })
+      .then(onClose)
+      .catch(() => setFailed(true));
+  };
+
+  // ⚠️ An empty title would be refused by the contract, and a list with none at all by the server.
+  // Saying so before the call is the difference between a form and a guessing game.
+  const titles = columns.map((column) => column.title.trim());
+  /**
+   * ⚠️ **Two columns with the same NAME are refused too**, although the server only refuses
+   * duplicate ids. An id nobody sees may repeat without confusing anybody; a name is what a person
+   * reads, and two columns called the same thing are two columns nobody can tell apart — on the
+   * board, in the filter, and in this very dialog.
+   */
+  const duplicate = titles.find((title, index) => titles.indexOf(title) !== index);
+  const incomplete =
+    columns.length === 0 || titles.some((title) => title.length === 0) || duplicate !== undefined;
+
+  return (
+    <Dialog open onOpenChange={(next) => (next ? undefined : onClose())}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>{i18n.t("board.settings.title")}</DialogTitle>
+          <DialogDescription>{i18n.t("board.settings.description")}</DialogDescription>
+        </DialogHeader>
+
+        <ul className="space-y-2">
+          {columns.map((column, index) => (
+            <li key={column.id} className="flex items-center gap-2">
+              <input
+                value={column.title}
+                aria-label={i18n.t("board.settings.columnName", { column: column.title })}
+                onChange={(event) => {
+                  const next = [...columns];
+                  next[index] = { ...column, title: event.target.value };
+                  setColumns(next);
+                }}
+                className="min-w-0 flex-1 rounded-md border bg-background px-2 py-1 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              />
+              <button
+                type="button"
+                aria-label={i18n.t("board.settings.moveUp", { column: column.title })}
+                disabled={index === 0}
+                onClick={() => move(index, -1)}
+                className="rounded-md p-1 outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-30"
+              >
+                <ChevronUp aria-hidden="true" className="size-4" />
+              </button>
+              <button
+                type="button"
+                aria-label={i18n.t("board.settings.moveDown", { column: column.title })}
+                disabled={index === columns.length - 1}
+                onClick={() => move(index, 1)}
+                className="rounded-md p-1 outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-30"
+              >
+                <ChevronDown aria-hidden="true" className="size-4" />
+              </button>
+              <button
+                type="button"
+                aria-label={
+                  (cardsIn.get(column.id) ?? 0) > 0
+                    ? // ⚠️ No count in this sentence. `packages/ui/CLAUDE.md`: a sentence that
+                      // carries a number has to read correctly at ONE, and "1 card(s)" is a written
+                      // admission that it does not. The number is on the board anyway; here what
+                      // matters is that the column is not empty.
+                      i18n.t("board.settings.removeBlocked", { column: column.title })
+                    : i18n.t("board.settings.remove", { column: column.title })
+                }
+                disabled={(cardsIn.get(column.id) ?? 0) > 0}
+                onClick={() => setColumns(columns.filter((entry) => entry.id !== column.id))}
+                className="rounded-md p-1 outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-30"
+              >
+                <X aria-hidden="true" className="size-4" />
+              </button>
+            </li>
+          ))}
+        </ul>
+
+        <button
+          type="button"
+          onClick={() =>
+            setColumns([
+              ...columns,
+              {
+                id: crypto.randomUUID(),
+                title: i18n.t("board.settings.newColumn"),
+                terminal: false,
+              },
+            ])
+          }
+          className="self-start rounded-md px-2 py-1 text-sm text-muted-foreground outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          {i18n.t("board.settings.addColumn")}
+        </button>
+
+        <label className="flex items-start gap-3 border-t pt-3 text-sm">
+          <input
+            type="checkbox"
+            checked={archiveVisible}
+            onChange={(event) => setArchiveVisible(event.target.checked)}
+            className="mt-1"
+          />
+          <span>
+            {i18n.t("board.settings.showArchive")}
+            <span className="block text-xs text-muted-foreground">
+              {i18n.t("board.settings.showArchiveHint")}
+            </span>
+          </span>
+        </label>
+
+        {duplicate === undefined ? null : (
+          <p role="alert" className="text-sm text-destructive">
+            {i18n.t("board.settings.duplicateName", { column: duplicate })}
+          </p>
+        )}
+        {failed ? (
+          <p role="alert" className="text-sm text-destructive">
+            {i18n.t("board.settings.failed")}
+          </p>
+        ) : null}
+
+        <DialogFooter>
+          <button
+            type="button"
+            onClick={onClose}
+            className="rounded-md border px-3 py-2 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {i18n.t("common.cancel")}
+          </button>
+          <button
+            type="button"
+            disabled={incomplete || board.isWriting}
+            onClick={save}
+            className="rounded-md bg-primary px-3 py-2 text-sm font-medium text-primary-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+          >
+            {i18n.t("common.save")}
+          </button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/board/board-stripes/board-stripes.ts

@@ -0,0 +1,128 @@
+import type { BoardTask } from "@anchrd/intel-contract/board";
+
+/** How many steps the family ramp has before it repeats (`styles.css`). */
+export const FAMILY_TONES = 6;
+
+/**
+ * ⚠️ **A guard against a cycle in the parent chain, not a limit on nesting.** The depth itself is
+ * unbounded (D37) and the server refuses a move into a node's own descendant — but this walk runs
+ * on whatever answer arrived, and an answer that somehow carried a loop would hang the render
+ * rather than draw a wrong card. A number this large is never reached by real work.
+ */
+const MAX_WALK = 1_000;
+
+export interface Family {
+  /** 1 for a root task, 2 for its child, and so on — the number of stripes drawn. 0 means none. */
+  level: number;
+  /** Which step of the ramp, 1…`FAMILY_TONES`. Every card of one family shares it. */
+  tone: number;
+  /** The root task of the family, or `null` when this card is not in one. */
+  rootId: string | null;
+}
+
+/**
+ * Which family a card belongs to, and how deep it sits in it.
+ *
+ * ⚠️ **A card alone is in NO family and takes no stripes.** The pattern exists to relate cards to
+ * one another; drawn on a card that relates to nothing it says "family" where there is none, and a
+ * mark that appears on every card carries no information at all. That is a deliberate reading of
+ * "a root task has one stripe": a root WITH children has one, a card by itself has none.
+ *
+ * ⚠️ **An unknown parent is treated as no parent.** Under a filter a subtask can be in the answer
+ * while its parent is not (`board.ts` says so on `parentTaskId`), and a walk that insisted on
+ * finding it would lose the card entirely.
+ */
+export function familyOf(task: BoardTask, tasks: BoardTask[]): Family {
+  return familiesOf(tasks).get(task.id) ?? { level: 0, tone: 0, rootId: null };
+}
+
+/**
+ * Every card's family, in ONE pass over the board.
+ *
+ * ⚠️ **Per board, not per card.** Asking `familyOf` once per card rebuilds the index every time,
+ * which is quadratic — measured at 800 cards it cost 36 ms per render, and `dnd-kit` re-renders on
+ * every pointer move while a card is being dragged. The whole board is one answer; its families are
+ * one derivation.
+ */
+export function familiesOf(tasks: BoardTask[]): Map<string, Family> {
+  const byId = new Map(tasks.map((entry) => [entry.id, entry]));
+  const parents = new Set<string>();
+  for (const entry of tasks) if (entry.parentTaskId !== null) parents.add(entry.parentTaskId);
+
+  const families = new Map<string, Family>();
+  for (const task of tasks) families.set(task.id, walkFamily(task, byId, parents.has(task.id)));
+  return families;
+}
+
+function walkFamily(task: BoardTask, byId: Map<string, BoardTask>, hasChildren: boolean): Family {
+  let level = 1;
+  let root = task;
+  const seen = new Set<string>([task.id]);
+  for (let step = 0; step < MAX_WALK; step += 1) {
+    const parentId = root.parentTaskId;
+    if (parentId === null || seen.has(parentId)) break;
+    const parent = byId.get(parentId);
+    if (parent === undefined) break;
+    seen.add(parentId);
+    root = parent;
+    level += 1;
+  }
+
+  if (level === 1 && !hasChildren) return { level: 0, tone: 0, rootId: null };
+  return { level, tone: toneOf(root.id), rootId: root.id };
+}
+
+/**
+ * ⚠️ **Derived from the root's ID, not from its place in the list.** A position would change every
+ * time somebody drags a card, and with it every stripe on the board — the one thing a reader was
+ * meant to recognise across a whole session.
+ */
+export function toneOf(rootId: string): number {
+  let sum = 0;
+  for (const character of rootId) sum = (sum * 31 + character.charCodeAt(0)) % 1_000_003;
+  return (sum % FAMILY_TONES) + 1;
+}
+
+/**
+ * The cards of ONE column, ordered so a subtask follows its parent.
+ *
+ * ⚠️ **Threaded, not nested.** A subtask that sits in the same column as its parent is drawn
+ * directly below it, and its own children below that — depth first. A subtask whose parent is in
+ * ANOTHER column has no thread to join here and takes its ordinary place by position. The cards
+ * stay the same width with the same left edge; the relation is carried by the stripes, not by an
+ * indent that would eat the width exactly where the title is.
+ */
+export function threaded(cards: BoardTask[]): BoardTask[] {
+  const here = new Set(cards.map((card) => card.id));
+  const byPosition = [...cards].sort((a, b) => a.position - b.position);
+  const children = new Map<string, BoardTask[]>();
+  const roots: BoardTask[] = [];
+
+  for (const card of byPosition) {
+    const parentId = card.parentTaskId;
+    if (parentId === null || !here.has(parentId)) {
+      roots.push(card);
+      continue;
+    }
+    const siblings = children.get(parentId);
+    if (siblings === undefined) children.set(parentId, [card]);
+    else siblings.push(card);
+  }
+
+  const out: BoardTask[] = [];
+  const emitted = new Set<string>();
+  // ⚠️ A REAL guard, and against a real hole: with a loop in the parent chain (a under b, b under a,
+  // or a card under itself) neither card is a root, so the walk below never starts on them. Left at
+  // that, the column silently loses them — work falls off the board with no error anywhere.
+  const walk = (card: BoardTask) => {
+    if (emitted.has(card.id)) return;
+    emitted.add(card.id);
+    out.push(card);
+    for (const child of children.get(card.id) ?? []) walk(child);
+  };
+  for (const root of roots) walk(root);
+  // ⚠️ Whatever the walk did not reach is appended in the board's own order. A card in a loop has
+  // no sensible place in a thread, and the bottom of the column is the honest one — visible.
+  for (const card of byPosition) walk(card);
+  return out;
+}