@yannelli/paseo-linear-plugin 0.3.0 → 0.4.0

package/OVERVIEW.md

@@ -16,6 +16,7 @@ To use a different Linear key for one Paseo project, add it under **Project keys
 - Select **Sub-issues** to nest sub-issues under their parent. The breadcrumbs above an issue show its team and parent chain.
 - Change the status, priority, and assignee. Add comments, or create an issue.
 - Descriptions and comments show as Markdown.
+- Edit the description in place. It saves to Linear about one second after you stop typing, and the line under the editor confirms each save. Select a task list checkbox to check or uncheck it without opening the editor.
 - `/linear` opens the panel. `/linear ENG-123` opens an issue.
 
 ## Start an agent

package/README.md

@@ -7,6 +7,7 @@ A Paseo plugin for Linear. It adds a Linear screen and a workspace panel where y
 - Browse issues in a list next to the issue view. Search and filter the list, and change its sort order.
 - Nest sub-issues under their parent. Breadcrumbs show the parent chain of an issue.
 - Read descriptions and comments as Markdown.
+- Edit the description in place. It saves as you type. Check off task list items without opening the editor.
 - Change the status, priority, and assignee. Add comments and create issues.
 - Start an agent or a review from an issue. Choose the prompt, agent, model, effort, project, and where the agent runs.
 - Use a different Linear key for a Paseo project.
@@ -87,6 +88,8 @@ The issue header shows breadcrumbs: the team, the parent chain, then the issue,
 
 - Select the status, priority, or assignee chip to change it.
 - Descriptions and comments show as Markdown: headings, lists, task lists, code, quotes, tables, and links.
+- Select the pencil next to **Description** to edit it as Markdown. The plugin saves about one second after you stop typing, and when you leave the box. The line under the box shows **Saving…**, then **Saved to Linear**. If a save fails, it shows **Could not save** and a **Retry** button. **Done** (or Escape) closes the editor only after Linear accepts the text.
+- Select a task list checkbox in the description to check or uncheck it. The plugin changes only that box in the Markdown and saves it to Linear. If the save fails, the issue reloads from Linear.
 - Add a comment in the **Activity** section.
 - The header buttons refresh the issue, copy its branch name, and open it in Linear.
 - Select **New issue**, or run **Linear: Create issue**, to create an issue. Set the team, status, priority, assignee, title, and a Markdown description.
@@ -137,6 +140,7 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 | `client/browser.tsx` | App | Screen and panel: picks the key, then shows the list, the issue, or the agent setup page |
 | `client/issue-list.tsx`, `client/issue-row.tsx`, `client/issue-tree.ts` | App | Search, filters, sort, rows, status groups, and sub-issue nesting |
 | `client/issue-detail.tsx`, `client/issue-sections.tsx`, `client/breadcrumbs.tsx` | App | Issue view: properties, breadcrumbs, sub-issues, links, agents, and comments |
+| `client/issue-description.tsx`, `client/autosave.ts` | App | Description editor, task list checkboxes, and debounced saves |
 | `client/markdown.tsx` | App | Renders Markdown |
 | `client/launch.tsx`, `client/launch-fields.tsx`, `client/launch-choices.ts`, `client/launch-plan.ts`, `client/agent-options.ts` | App | Agent setup page, Run in options, and agent start |
 | `client/model-browser.tsx`, `client/provider-icon.tsx` | App | Model picker and provider icons |
@@ -149,7 +153,7 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 | `shared/issues.ts` | Both | The `issues.search` RPC and the composer attachment source |
 | `shared/settings.ts` | Both | Settings schema: templates, agent defaults, and project settings |
 | `shared/prompts.ts` | Both | Default templates and the issue snapshot |
-| `shared/markdown.ts` | Both | Markdown parser |
+| `shared/markdown.ts` | Both | Markdown parser and task list toggle |
 | `server/handlers.ts` | Daemon | RPC handlers, key lookup, and cache use |
 | `server/credentials.ts` | Daemon | Key file and key order |
 | `server/cache.ts` | Daemon | Response cache in memory |
@@ -170,7 +174,7 @@ npm run check
 paseo plugin add "$PWD"
 ```
 
-After you edit the source, run `paseo plugin reload linear`. `npm run check` runs the typecheck and the tests. The tests cover the Linear client, the key file, the cache, the handlers, sub-issue nesting, the Markdown parser, the agent options, and the release scripts. They use a local GraphQL server and do not call Linear.
+After you edit the source, run `paseo plugin reload linear`. `npm run check` runs the typecheck and the tests. The tests cover the Linear client, the key file, the cache, the handlers, sub-issue nesting, the Markdown parser and task list toggle, the description autosave, the agent options, and the release scripts. They use a local GraphQL server and do not call Linear.
 
 ## Graphics
 

package/client/autosave.ts

@@ -0,0 +1,77 @@
+// Debounced, single-flight saving for one text value. Pure so the tests can drive it
+// with fake timers. Only the latest value is kept, and one save runs at a time, so
+// saves always reach the server in edit order.
+
+export type SaveStatus = "idle" | "pending" | "saving" | "saved" | "error";
+
+export interface AutosaveOptions {
+  delayMs: number;
+  save(value: string): Promise<void>;
+  onStatus(status: SaveStatus, error?: unknown): void;
+}
+
+export interface Autosave {
+  /** Queues `value` and saves it after `delayMs` (or the given delay) without changes. */
+  schedule(value: string, delayMs?: number): void;
+  /** Saves the queued value now. Resolves when nothing is left to save. */
+  flush(): Promise<void>;
+  /** Drops the queued value. A save in flight still finishes. */
+  cancel(): void;
+  /** True while a value is queued or saving. */
+  busy(): boolean;
+}
+
+export function createAutosave(options: AutosaveOptions): Autosave {
+  let queued: string | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let inFlight: Promise<void> | null = null;
+
+  function clearTimer() {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  }
+
+  // Starts the next save unless one is running. Rejects with the save error.
+  function run(): Promise<void> {
+    clearTimer();
+    if (inFlight) return inFlight.then(() => (queued === null ? undefined : run()));
+    if (queued === null) return Promise.resolve();
+    const value = queued;
+    queued = null;
+    options.onStatus("saving");
+    inFlight = options.save(value).then(
+      () => {
+        inFlight = null;
+        if (queued === null) options.onStatus(timer === null ? "saved" : "pending");
+        else if (timer === null) return run();
+      },
+      (error: unknown) => {
+        inFlight = null;
+        // Keep the failed value for a retry unless a newer edit replaced it.
+        if (queued === null) queued = value;
+        if (timer === null) options.onStatus("error", error);
+        throw error;
+      },
+    );
+    return inFlight;
+  }
+
+  function background() {
+    run().catch(() => undefined);
+  }
+
+  return {
+    schedule(value, delayMs = options.delayMs) {
+      queued = value;
+      clearTimer();
+      options.onStatus("pending");
+      timer = setTimeout(background, delayMs);
+    },
+    flush: run,
+    cancel() {
+      clearTimer();
+      queued = null;
+    },
+    busy: () => queued !== null || inFlight !== null,
+  };
+}

package/client/issue-description.tsx

@@ -0,0 +1,206 @@
+import { TextInput, useToast } from "@getpaseo/plugin/client/react-native";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  type NativeSyntheticEvent,
+  Pressable,
+  Text,
+  type TextInputKeyPressEventData,
+  View,
+} from "react-native";
+import type { IssueDetail } from "../shared/linear";
+import { toggleTask } from "../shared/markdown";
+import { createAutosave, type SaveStatus } from "./autosave";
+import { Markdown } from "./markdown";
+import { useDescriptionSaver } from "./queries";
+import { Button, errorMessage, IconButton, SectionLabel, type Theme } from "./ui";
+
+// Typing saves after a pause. Checkbox taps save sooner and coalesce rapid taps.
+const EDIT_DELAY_MS = 1200;
+const TOGGLE_DELAY_MS = 400;
+
+const STATUS_COPY: Record<SaveStatus, string> = {
+  idle: "Saves as you type",
+  pending: "Unsaved changes",
+  saving: "Saving…",
+  saved: "Saved to Linear",
+  error: "Could not save",
+};
+
+const HEADER_STYLE = {
+  flexDirection: "row",
+  alignItems: "center",
+  justifyContent: "space-between",
+} as const;
+
+const noop = () => undefined;
+
+export function IssueDescription(props: { theme: Theme; compact: boolean; issue: IssueDetail }) {
+  const { theme, compact, issue } = props;
+  const { colors } = theme;
+  const toast = useToast();
+  const saver = useDescriptionSaver(issue.id);
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState("");
+  const [status, setStatus] = useState<SaveStatus>("idle");
+  const [closing, setClosing] = useState(false);
+  // Read by the autosave callbacks and the unmount flush, which outlive a render.
+  const live = useRef({ editing, draft, toast });
+  useEffect(() => {
+    live.current = { editing, draft, toast };
+  });
+
+  const autosave = useMemo(() => {
+    let lastSaved: string | null = null;
+    const instance = createAutosave({
+      delayMs: EDIT_DELAY_MS,
+      save: async (value) => {
+        await saver.save(value);
+        lastSaved = value;
+      },
+      onStatus: (next, error) => {
+        setStatus(next);
+        // A refetch during the save may have brought back older text. Nothing is queued now.
+        if (next === "saved" && lastSaved !== null) saver.show(lastSaved);
+        if (next !== "error" || live.current.editing) return;
+        // A checkbox save failed: drop it and show what Linear has.
+        instance.cancel();
+        live.current.toast.error(`Could not update the checklist: ${errorMessage(error)}`);
+        saver.reload();
+      },
+    });
+    return instance;
+  }, [saver]);
+
+  // Leaving the issue saves any pending text instead of losing it.
+  useEffect(
+    () => () => {
+      if (!autosave.busy()) return;
+      const { editing: wasEditing, draft: text, toast: notify } = live.current;
+      if (wasEditing) saver.show(text);
+      autosave.flush().catch((error: unknown) => {
+        notify.error(`Description not saved: ${errorMessage(error)}`);
+        saver.reload();
+      });
+    },
+    [autosave, saver],
+  );
+
+  const description = issue.description ?? "";
+  const startEditing = useCallback(() => {
+    setDraft(description);
+    setStatus("idle");
+    setEditing(true);
+  }, [description]);
+  const change = useCallback(
+    (text: string) => {
+      setDraft(text);
+      autosave.schedule(text);
+    },
+    [autosave],
+  );
+  const flushQuietly = useCallback(() => void autosave.flush().catch(noop), [autosave]);
+  // Closes only after Linear confirms the text. A failure keeps the editor open.
+  const finish = useCallback(() => {
+    setClosing(true);
+    autosave
+      .flush()
+      .then(() => {
+        saver.show(live.current.draft);
+        setEditing(false);
+        setStatus("idle");
+      }, noop)
+      .finally(() => setClosing(false));
+  }, [autosave, saver]);
+  const keyPress = useCallback(
+    (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+      if (event.nativeEvent.key === "Escape") finish();
+    },
+    [finish],
+  );
+  const toggle = useCallback(
+    (ordinal: number) => {
+      const next = toggleTask(description, ordinal);
+      if (next === null) {
+        live.current.toast.error("The checklist changed. Refresh the issue and try again.");
+        return;
+      }
+      saver.show(next);
+      autosave.schedule(next, TOGGLE_DELAY_MS);
+    },
+    [description, saver, autosave],
+  );
+
+  const styles = useMemo(
+    () =>
+      ({
+        input: {
+          minHeight: 200,
+          padding: 10,
+          borderRadius: 8,
+          borderWidth: 1,
+          borderColor: colors.border,
+          backgroundColor: colors.surface1,
+          color: colors.foreground,
+          fontSize: 14,
+          lineHeight: 21,
+          textAlignVertical: "top",
+        },
+        footer: { flexDirection: "row", alignItems: "center", gap: 8, marginTop: 8 },
+        status: {
+          flex: 1,
+          fontSize: 12,
+          color: status === "error" ? colors.statusDanger : colors.foregroundMuted,
+        },
+        empty: { color: colors.foregroundMuted, fontSize: 14, lineHeight: 21 },
+      }) as const,
+    [colors, status],
+  );
+
+  if (editing) {
+    return (
+      <View>
+        <SectionLabel theme={theme}>Description</SectionLabel>
+        <TextInput
+          value={draft}
+          onChangeText={change}
+          onBlur={flushQuietly}
+          onKeyPress={keyPress}
+          multiline
+          autoFocus
+          placeholder="Add a description in Markdown…"
+          placeholderTextColor={colors.foregroundMuted}
+          accessibilityLabel="Issue description"
+          style={styles.input}
+        />
+        <View style={styles.footer}>
+          <Text accessibilityLiveRegion="polite" style={styles.status}>
+            {STATUS_COPY[status]}
+          </Text>
+          {status === "error" ? (
+            <Button theme={theme} icon="RefreshCw" label="Retry" onPress={flushQuietly} />
+          ) : null}
+          <Button theme={theme} icon="Check" label="Done" busy={closing} onPress={finish} />
+        </View>
+      </View>
+    );
+  }
+  return (
+    <View>
+      <View style={HEADER_STYLE}>
+        <SectionLabel theme={theme}>Description</SectionLabel>
+        <IconButton theme={theme} icon="Pencil" label="Edit description" onPress={startEditing} />
+      </View>
+      {description.trim() ? (
+        <Markdown theme={theme} compact={compact} source={description} onToggleTask={toggle} />
+      ) : (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel="Add a description"
+          onPress={startEditing}
+        >
+          <Text style={styles.empty}>No description. Add one…</Text>
+        </Pressable>
+      )}
+    </View>
+  );
+}

package/client/issue-detail.tsx

@@ -6,7 +6,7 @@ import type { IssueDetail, IssuePatch, LinearTeam, LinearUser } from "../shared/
 import { ACTION_LABELS } from "../shared/prompts";
 import type { AgentAction } from "../shared/settings";
 import { IssueBreadcrumbs } from "./breadcrumbs";
-import { Markdown } from "./markdown";
+import { IssueDescription } from "./issue-description";
 import { Comments, IssueLinks, IssueRelations, LinkedAgents } from "./issue-sections";
 import type { LaunchTarget } from "./launch";
 import {
@@ -27,7 +27,6 @@ import {
   LabelPill,
   priorityMeta,
   PriorityIcon,
-  SectionLabel,
   StateIcon,
   type Theme,
 } from "./ui";
@@ -90,7 +89,8 @@ export function IssueDetailView(props: IssueDetailProps) {
       </EmptyState>
     );
   }
-  return <LoadedIssue {...props} issue={issue.data} refetch={reload} />;
+  // Keyed so that switching issues never carries a draft or a pending save across.
+  return <LoadedIssue key={issue.data.id} {...props} issue={issue.data} refetch={reload} />;
 }
 
 function LoadedIssue(props: IssueDetailProps & { issue: IssueDetail; refetch(): void }) {
@@ -108,7 +108,6 @@ function LoadedIssue(props: IssueDetailProps & { issue: IssueDetail; refetch():
         fontWeight: "500",
         lineHeight: compact ? 24 : 28,
       },
-      description: { color: colors.foregroundMuted, fontSize: 14, lineHeight: 21 },
     } as const;
   }, [colors, compact]);
   return (
@@ -140,14 +139,7 @@ function LoadedIssue(props: IssueDetailProps & { issue: IssueDetail; refetch():
         ) : null}
         <LaunchButtons theme={theme} onLaunch={props.onLaunch} />
         <LinkedAgents theme={theme} identifier={issue.identifier} navigation={props.navigation} />
-        <View>
-          <SectionLabel theme={theme}>Description</SectionLabel>
-          {issue.description?.trim() ? (
-            <Markdown theme={theme} compact={compact} source={issue.description} />
-          ) : (
-            <Text style={styles.description}>No description.</Text>
-          )}
-        </View>
+        <IssueDescription theme={theme} compact={compact} issue={issue} />
         <IssueRelations theme={theme} issue={issue} onOpenIssue={props.onOpenIssue} />
         <IssueLinks theme={theme} issue={issue} />
         <Comments theme={theme} issue={issue} />

package/client/markdown.tsx

@@ -1,8 +1,22 @@
 import { openExternalUrl } from "@getpaseo/plugin/client";
 import { Icon } from "@getpaseo/plugin/client/react-native";
 import { type ReactNode, useCallback, useMemo } from "react";
-import { Platform, ScrollView, type StyleProp, Text, type TextStyle, View } from "react-native";
-import { type MarkdownBlock, type MarkdownInline, parseMarkdown } from "../shared/markdown";
+import {
+  Platform,
+  Pressable,
+  ScrollView,
+  type StyleProp,
+  Text,
+  type TextStyle,
+  View,
+} from "react-native";
+import {
+  type MarkdownBlock,
+  type MarkdownInline,
+  type MarkdownListItem,
+  parseMarkdown,
+  taskItems,
+} from "../shared/markdown";
 import type { Theme } from "./ui";
 
 type ListBlock = Extract<MarkdownBlock, { type: "list" }>;
@@ -73,11 +87,20 @@ type Styles = ReturnType<typeof createStyles>;
 
 // `s` styles the current blocks. `quoted` is the muted context for blockquotes; inside a
 // quote it is unset, so nested quotes reuse the current (already muted) context.
+// `tasks` maps each task item to its `taskItems` ordinal when checkboxes are pressable.
 interface Context {
   s: Styles;
   quoted?: Context;
+  tasks?: TaskToggles;
 }
 
+interface TaskToggles {
+  ordinals: Map<MarkdownListItem, number>;
+  onToggle(ordinal: number): void;
+}
+
+const CHECKBOX_HIT_SLOP = 8;
+
 function Link(props: { url: string; style: StyleProp<TextStyle>; children: ReactNode }) {
   const { url } = props;
   const open = useCallback(() => void openExternalUrl(url), [url]);
@@ -121,8 +144,37 @@ function renderBlocks(blocks: MarkdownBlock[], ctx: Context): ReactNode[] {
   return blocks.map((block, index) => <Block key={index} block={block} ctx={ctx} />);
 }
 
-function ListMarker(props: { list: ListBlock; index: number; checked: boolean | null; s: Styles }) {
-  const { list, index, checked, s } = props;
+function TaskBox(props: { checked: boolean; ordinal: number; tasks: TaskToggles; s: Styles }) {
+  const { checked, ordinal, tasks } = props;
+  const { onToggle } = tasks;
+  const toggle = useCallback(() => onToggle(ordinal), [onToggle, ordinal]);
+  const a11yState = useMemo(() => ({ checked }), [checked]);
+  return (
+    <Pressable
+      accessibilityRole="checkbox"
+      accessibilityState={a11yState}
+      accessibilityLabel={checked ? "Uncheck item" : "Check item"}
+      hitSlop={CHECKBOX_HIT_SLOP}
+      onPress={toggle}
+    >
+      <Icon name={checked ? "SquareCheck" : "Square"} size={14} color={props.s.ink} />
+    </Pressable>
+  );
+}
+
+function ListMarker(props: {
+  list: ListBlock;
+  item: MarkdownListItem;
+  index: number;
+  ctx: Context;
+}) {
+  const { list, item, index, ctx } = props;
+  const { s, tasks } = ctx;
+  const { checked } = item;
+  const ordinal = tasks?.ordinals.get(item);
+  if (checked !== null && tasks && ordinal !== undefined) {
+    return <TaskBox checked={checked} ordinal={ordinal} tasks={tasks} s={s} />;
+  }
   if (checked !== null) {
     return <Icon name={checked ? "SquareCheck" : "Square"} size={14} color={s.ink} />;
   }
@@ -140,7 +192,7 @@ function List({ list, ctx }: { list: ListBlock; ctx: Context }) {
       {list.items.map((item, index) => (
         <View key={index} style={s.item}>
           <View style={s.marker}>
-            <ListMarker list={list} index={index} checked={item.checked} s={s} />
+            <ListMarker list={list} item={item} index={index} ctx={ctx} />
           </View>
           <View style={s.itemBody}>{renderBlocks(item.children, ctx)}</View>
         </View>
@@ -209,7 +261,11 @@ function Block({ block, ctx }: { block: MarkdownBlock; ctx: Context }) {
         </View>
       );
     case "blockquote":
-      return <View style={s.quote}>{renderBlocks(block.children, ctx.quoted ?? ctx)}</View>;
+      return (
+        <View style={s.quote}>
+          {renderBlocks(block.children, ctx.quoted ? { ...ctx.quoted, tasks: ctx.tasks } : ctx)}
+        </View>
+      );
     case "list":
       return <List list={block} ctx={ctx} />;
     case "table":
@@ -224,17 +280,23 @@ export interface MarkdownProps {
   source: string;
   compact?: boolean;
   muted?: boolean;
+  /** Makes task checkboxes pressable. Gets the item's ordinal in `taskItems` order. */
+  onToggleTask?(ordinal: number): void;
 }
 
 export function Markdown(props: MarkdownProps) {
   const { colors } = props.theme;
   const compact = props.compact === true;
   const muted = props.muted === true;
+  const { onToggleTask } = props;
   const blocks = useMemo(() => parseMarkdown(props.source), [props.source]);
   const ctx = useMemo<Context>(() => {
     const quoted: Context = { s: createStyles(colors, compact, true) };
-    return { s: muted ? quoted.s : createStyles(colors, compact, false), quoted };
-  }, [colors, compact, muted]);
+    const tasks = onToggleTask
+      ? { ordinals: new Map(taskItems(blocks).map((item, n) => [item, n])), onToggle: onToggleTask }
+      : undefined;
+    return { s: muted ? quoted.s : createStyles(colors, compact, false), quoted, tasks };
+  }, [colors, compact, muted, blocks, onToggleTask]);
   if (blocks.length === 0) return null;
   return <View style={ctx.s.root}>{renderBlocks(blocks, ctx)}</View>;
 }

package/client/queries.ts

@@ -6,6 +6,7 @@ import {
   useQuery,
   useQueryClient,
 } from "@tanstack/react-query";
+import { useMemo } from "react";
 import {
   authStatusRpc,
   cachedCatalogRpc,
@@ -128,6 +129,36 @@ export function useUpdateIssue(issueId: string) {
   });
 }
 
+// Plain RPC calls, not a mutation, so a save that finishes after the view closes still
+// updates the cache. The update returns a summary without the description, so callers
+// show the new text with `show` and the save leaves the cached description alone.
+export function useDescriptionSaver(issueId: string) {
+  const scope = useKeyScope();
+  const update = useRpc(updateIssueRpc);
+  const queries = useQueryClient();
+  return useMemo(() => {
+    const key = queryKeys.issue(scope, issueId);
+    return {
+      show(description: string) {
+        void queries.cancelQueries({ queryKey: key });
+        queries.setQueryData<IssueDetail>(key, (current) =>
+          current ? { ...current, description } : current,
+        );
+      },
+      async save(description: string) {
+        const { issue } = await update({ id: issueId, patch: { description }, projectId: scope });
+        queries.setQueryData<IssueDetail>(key, (current) =>
+          current ? { ...current, ...issue } : current,
+        );
+        void queries.invalidateQueries({ queryKey: queryKeys.issues(scope) });
+      },
+      reload() {
+        void queries.invalidateQueries({ queryKey: key });
+      },
+    };
+  }, [scope, issueId, update, queries]);
+}
+
 export function useAddComment(issueId: string) {
   const scope = useKeyScope();
   const create = useRpc(createCommentRpc);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yannelli/paseo-linear-plugin",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Browse and triage Linear issues in Paseo and start agents from them",
   "license": "Apache-2.0",
   "type": "module",

package/shared/markdown.ts

@@ -414,3 +414,48 @@ function readBareUrl(text: string, i: number): Token | null {
   if (!safe) return null;
   return { nodes: [{ type: "link", url: safe, children: label }], end: i + url.length };
 }
+
+/** Task items in document order. Renderers number checkboxes with this walk. */
+export function taskItems(blocks: MarkdownBlock[]): MarkdownListItem[] {
+  const out: MarkdownListItem[] = [];
+  const walk = (children: MarkdownBlock[]) => {
+    for (const block of children) {
+      if (block.type === "blockquote") walk(block.children);
+      if (block.type !== "list") continue;
+      for (const item of block.items) {
+        if (item.checked !== null) out.push(item);
+        walk(item.children);
+      }
+    }
+  };
+  walk(blocks);
+  return out;
+}
+
+// A "[ ]" or "[x]" after any quote and list markers. The parser has the final word.
+const TASK_LINE = /^((?:[ \t]*(?:>[ \t]?|(?:[-*+]|\d{1,9}[.)])[ \t]+))+)\[[ xX]\](?=[ \t]|$)/;
+
+const taskStates = (source: string) => taskItems(parseMarkdown(source)).map((item) => item.checked);
+
+// Flips task `ordinal` (0-based, `taskItems` order) by changing only its box character.
+// Returns null when no line maps to that task, so callers never save a guess.
+export function toggleTask(source: string, ordinal: number): string | null {
+  const before = taskStates(source);
+  if (!Number.isInteger(ordinal) || ordinal < 0 || ordinal >= before.length) return null;
+  const parts = source.split(/(\r\n?|\n)/);
+  let offset = 0;
+  let candidate = 0;
+  for (let k = 0; k < parts.length; k += 2) {
+    const match = TASK_LINE.exec(parts[k]);
+    // Every task is a candidate and both run in document order, so earlier ones can't match.
+    if (match && candidate++ >= ordinal) {
+      const at = offset + match[1].length + 1;
+      const next = `${source.slice(0, at)}${source[at] === " " ? "x" : " "}${source.slice(at + 1)}`;
+      const after = taskStates(next);
+      const flipsOnly = (state: boolean | null, n: number) => (n === ordinal) !== (state === before[n]);
+      if (after.length === before.length && after.every(flipsOnly)) return next;
+    }
+    offset += parts[k].length + (parts[k + 1]?.length ?? 0);
+  }
+  return null;
+}