@xvzc/pi-tasks 1.0.0

package/src/tasks-ui.ts

@@ -0,0 +1,228 @@
+/**
+ * Small terminal overlay for `/tasks view`: left task list, right details.
+ * Pure helpers plus a keyboard-driven component using public pi-tui APIs.
+ */
+
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { KeybindingsManager } from "@earendil-works/pi-tui";
+import type { Task } from "./types.js";
+import type { ThemeLike } from "./widget.js";
+import { blockedBySuffix, statusGlyph } from "./widget.js";
+
+/** Visible detail rows in the right pane; PageUp/PageDown move by this amount. */
+export const TASK_VIEWER_PAGE_SIZE = 10;
+
+/** Single-line label for the left task list. */
+export function taskRowLabel(task: Task): string {
+  return `${statusGlyph(task)} #${task.id} (${task.attempt}/${task.maxAttempts}) ${task.subject}${blockedBySuffix(task)}`;
+}
+
+/** Full detail lines for the right pane (plain text; the component truncates). */
+export function buildTaskDetailLines(task: Task): string[] {
+  const lines: string[] = [
+    `Status: ${task.status}`,
+    `Task: #${task.id} (${task.attempt}/${task.maxAttempts})`,
+    `Assignee: ${task.assignee ?? "(none)"}`,
+    `Subject: ${task.subject}`,
+    ...task.description.split("\n").map((line, index) => `${index === 0 ? "Description" : "           "}: ${line}`),
+    `Blocked by: ${task.blockedBy.length === 0 ? "(none)" : task.blockedBy.map((id) => `#${id}`).join(", ")}`,
+    `Created: ${task.createdAt}`,
+    `Updated: ${task.updatedAt}`,
+  ];
+  if (task.startedAt !== undefined) lines.push(`Started: ${task.startedAt}`);
+  if (task.tookMs !== undefined) lines.push(`Took: ${task.tookMs}ms`);
+  lines.push(`Metadata: ${JSON.stringify(task.metadata)}`);
+  lines.push(`Log (${task.log.length}):`);
+  for (const entry of task.log) lines.push(`  [${entry.timestamp}] ${entry.message}`);
+  return lines;
+}
+
+function fit(line: string, width: number): string {
+  if (!Number.isFinite(width) || width <= 0) return "";
+  if (visibleWidth(line) <= width) return line;
+  return truncateToWidth(line, width);
+}
+
+function isKey(data: string, id: Parameters<typeof matchesKey>[1]): boolean {
+  try {
+    return matchesKey(data, id);
+  } catch {
+    return false;
+  }
+}
+
+function matchesBinding(
+  keybindings: TasksViewerOptions["keybindings"],
+  data: string,
+  binding: "tui.editor.cursorUp" | "tui.editor.cursorDown",
+): boolean {
+  if (!keybindings) return false;
+  try {
+    return keybindings.matches(data, binding);
+  } catch {
+    return false;
+  }
+}
+
+function addBorder(lines: string[], width: number, theme?: ThemeLike): string[] {
+  const paint = (text: string): string => {
+    if (!theme) return text;
+    try {
+      return theme.fg("border", text);
+    } catch {
+      return text;
+    }
+  };
+  if (width === 1) return [paint("╷"), ...lines.map(() => paint("│")), paint("╵")];
+  const innerWidth = width - 2;
+  const horizontal = "─".repeat(innerWidth);
+  return [
+    paint(`┌${horizontal}┐`),
+    ...lines.map((line) => {
+      const content = fit(line, innerWidth);
+      return `${paint("│")}${content}${" ".repeat(Math.max(0, innerWidth - visibleWidth(content)))}${paint("│")}`;
+    }),
+    paint(`└${horizontal}┘`),
+  ];
+}
+
+export interface TasksViewerOptions {
+  /** Called to close the overlay. */
+  done: () => void;
+  theme?: ThemeLike;
+  /** Request a redraw after navigation (the TUI object from the custom factory). */
+  tui?: { requestRender?: ((force?: boolean) => void) | undefined; renderNow?: ((force?: boolean) => void) | undefined };
+  /** Resolves the configured `tui.editor.cursorUp` / `tui.editor.cursorDown` bindings. */
+  keybindings?: Pick<KeybindingsManager, "matches">;
+  /** Visible detail rows; defaults to TASK_VIEWER_PAGE_SIZE. */
+  pageSize?: number;
+}
+
+export type TasksViewer = {
+  render(width: number): string[];
+  handleInput(data: string): void;
+  invalidate(): void;
+  dispose(): void;
+  getSelected(): number;
+  getDetailOffset(): number;
+};
+
+/**
+ * Keyboard-driven two-column viewer. Selection follows the configured
+ * `tui.editor.cursorUp` / `tui.editor.cursorDown` bindings (detail scroll
+ * resets); PageUp/PageDown scrolls the detail pane; Escape or Ctrl+C closes.
+ */
+export function createTasksViewer(tasks: Task[], options: TasksViewerOptions): TasksViewer {
+  const snapshot = [...tasks].sort((a, b) => a.id - b.id);
+  const pageSize =
+    typeof options.pageSize === "number" && Number.isFinite(options.pageSize) && options.pageSize > 0
+      ? Math.floor(options.pageSize)
+      : TASK_VIEWER_PAGE_SIZE;
+  let selected = 0;
+  let detailOffset = 0;
+
+  const detailLines = (): string[] =>
+    snapshot.length === 0 ? [] : buildTaskDetailLines(snapshot[Math.min(selected, snapshot.length - 1)]);
+
+  function maxOffset(): number {
+    return Math.max(0, detailLines().length - pageSize);
+  }
+
+  function redraw(): void {
+    try {
+      if (typeof options.tui?.requestRender === "function") options.tui.requestRender();
+      else if (typeof options.tui?.renderNow === "function") options.tui.renderNow();
+    } catch {
+      // Redraws are best-effort in tests and teardown.
+    }
+  }
+
+  function header(): string {
+    const plain = `Tasks (${snapshot.length})`;
+    if (!options.theme) return plain;
+    try {
+      return options.theme.fg("accent", plain);
+    } catch {
+      return plain;
+    }
+  }
+
+  const HINT = "Up/Down select · PgUp/PgDn scroll · Esc close";
+
+  return {
+    render(width: number) {
+      if (!Number.isFinite(width) || width <= 0) return [];
+      const innerWidth = Math.max(0, width - 2);
+      const lines: string[] = [];
+      if (snapshot.length === 0) {
+        return addBorder([fit(header(), innerWidth), fit("No tasks.", innerWidth), fit(HINT, innerWidth)], width, options.theme);
+      }
+      const selectedTask = snapshot[Math.min(selected, snapshot.length - 1)];
+      const allDetail = buildTaskDetailLines(selectedTask);
+      const offset = Math.min(detailOffset, Math.max(0, allDetail.length - pageSize));
+      const visibleDetail = allDetail.slice(offset, offset + pageSize);
+
+      // Narrow terminals stack list above details instead of squeezing columns.
+      if (innerWidth < 40) {
+        lines.push(fit(header(), innerWidth));
+        snapshot.forEach((task, index) => {
+          lines.push(fit(`${index === selected ? "> " : "  "}${taskRowLabel(task)}`, innerWidth));
+        });
+        lines.push(fit("—", innerWidth));
+        for (const line of visibleDetail) lines.push(fit(line, innerWidth));
+        lines.push(fit(HINT, innerWidth));
+        return addBorder(lines, width, options.theme);
+      }
+
+      const leftW = Math.max(18, Math.min(32, Math.floor(innerWidth * 0.35)));
+      const rightW = innerWidth - leftW - 3;
+      lines.push(fit(header(), innerWidth));
+      const rowCount = Math.max(snapshot.length, visibleDetail.length);
+      for (let i = 0; i < rowCount; i++) {
+        const leftRaw = i < snapshot.length ? `${i === selected ? "> " : "  "}${taskRowLabel(snapshot[i])}` : "";
+        const leftFit = fit(leftRaw, leftW);
+        const leftPadded = leftFit + " ".repeat(Math.max(0, leftW - visibleWidth(leftFit)));
+        const rightFit = rightW > 0 ? fit(visibleDetail[i] ?? "", rightW) : "";
+        lines.push(rightW > 0 ? `${leftPadded} │ ${rightFit}` : leftPadded);
+      }
+      lines.push(fit(HINT, innerWidth));
+      return addBorder(lines, width, options.theme);
+    },
+    handleInput(data: string) {
+      if (data === "\x1b" || data === "\x03" || isKey(data, "escape") || isKey(data, "ctrl+c")) {
+        options.done();
+        return;
+      }
+      if (snapshot.length === 0) return;
+      if (data === "\x1b[A" || isKey(data, "up") || matchesBinding(options.keybindings, data, "tui.editor.cursorUp")) {
+        selected = (selected - 1 + snapshot.length) % snapshot.length;
+        detailOffset = 0;
+        redraw();
+        return;
+      }
+      if (data === "\x1b[B" || isKey(data, "down") || matchesBinding(options.keybindings, data, "tui.editor.cursorDown")) {
+        selected = (selected + 1) % snapshot.length;
+        detailOffset = 0;
+        redraw();
+        return;
+      }
+      if (data === "\x1b[5~" || isKey(data, "pageUp")) {
+        detailOffset = Math.max(0, detailOffset - pageSize);
+        redraw();
+        return;
+      }
+      if (data === "\x1b[6~" || isKey(data, "pageDown")) {
+        detailOffset = Math.min(maxOffset(), detailOffset + pageSize);
+        redraw();
+      }
+    },
+    invalidate() {},
+    dispose() {},
+    getSelected() {
+      return selected;
+    },
+    getDetailOffset() {
+      return detailOffset;
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+/** Shared task model and persisted store envelope. */
+
+export type TaskStatus = "pending" | "in_progress" | "completed";
+
+export interface TaskLogEntry {
+  /** ISO 8601 UTC timestamp added by the store. */
+  timestamp: string;
+  /** Caller-supplied execution note. */
+  message: string;
+}
+
+export interface Task {
+  /** Numeric, positive, monotonically allocated within a store. Never reused. */
+  id: number;
+  subject: string;
+  description: string;
+  /** Assigned agent type shown as `[assignee]` in the widget. */
+  assignee?: string;
+  /** Optional accent color name for the status glyph. Never interpreted by the store. */
+  color?: string;
+  status: TaskStatus;
+  /** Number of entries into `in_progress`. Starts at 0, increments on pending/completed -> in_progress. */
+  attempt: number;
+  /** Per-task immutable cap for `attempt`. Defaults to 9. */
+  maxAttempts: number;
+  /** IDs this task depends on. Defaults to []. */
+  blockedBy: number[];
+  /** Free-form agent metadata. Updated with shallow merge. Defaults to {}. */
+  metadata: Record<string, unknown>;
+  /** Append-only timestamped execution notes. Defaults to []. */
+  log: TaskLogEntry[];
+  /** ISO 8601 UTC timestamp. Set once at creation, never changed. */
+  createdAt: string;
+  /** ISO 8601 UTC timestamp. Refreshed on every successful update. */
+  updatedAt: string;
+  /** ISO 8601 UTC timestamp marking the start of the current `in_progress` attempt. Set only on a real non-`in_progress` -> `in_progress` transition; preserved by `in_progress` -> `in_progress` updates; cleared when leaving `in_progress`. Absent on legacy persisted tasks (initialized to the load timestamp on load, so the attempt starts at zero). */
+  startedAt?: string;
+  /** Frozen duration in integer milliseconds of the last completed attempt. Set on transition into `completed`; cleared on entry into `in_progress`; preserved otherwise. Absent until the first completion. */
+  tookMs?: number;
+}
+
+/** On-disk envelope. `version` is always 1. */
+export interface StoreData {
+  version: 1;
+  nextId: number;
+  tasks: Task[];
+  /** Wall-clock union milliseconds accumulated while at least one task was `in_progress`. Finished periods only; the running period (if any) starts at `activeSince`. Defaults to 0 for legacy files. */
+  totalActiveMs: number;
+  /** ISO 8601 UTC start of the current active period. Present iff at least one task is `in_progress`. */
+  activeSince?: string;
+}
+
+export const TASK_STATUSES: TaskStatus[] = ["pending", "in_progress", "completed"];
+
+export function isTaskStatus(value: unknown): value is TaskStatus {
+  return value === "pending" || value === "in_progress" || value === "completed";
+}

package/src/widget.ts

@@ -0,0 +1,341 @@
+/**
+ * Presentational task rendering. Pure functions over task state: this module
+ * never reads or writes the store and never changes lifecycle/model semantics.
+ *
+ * Each line shows the numeric ID with its `(<attempt>/<maxAttempts>)` counter,
+ * the optional `[assignee]`, and the subject. `in_progress` lines append the
+ * running per-attempt duration measured from `startedAt` to the supplied
+ * current time (`Date.now()` by default; pass an explicit `nowMs` for
+ * deterministic rendering/tests), showing `0s` immediately at zero. `completed`
+ * lines append only the frozen `<duration>` for the last completed attempt
+ * (`tookMs`, or the `createdAt` to `updatedAt` span for legacy tasks).
+ * `pending` lines show no duration: a new attempt shows `0s` on entry into
+ * `in_progress`.
+ * The header always shows the total count and the done count (including
+ * `(0 done)`). It appends the global accumulated active (wall-clock union)
+ * time only after a task has entered `in_progress`; the themed header renders
+ * that time dim/gray. Every status uses a filled `■` glyph; color and text styling
+ * distinguish pending, in-progress, and completed tasks. The optional `[assignee]`
+ * always uses the same color, weight, and
+ * decoration as the subject. Pending assignees and subjects use the default
+ * text color while the pending glyph remains gray. The optional task `color`
+ * tints only the in-progress and completed status glyphs; both render green
+ * by default. Elapsed/completed duration text renders dim/gray in themed lines
+ * and is appended plain after the subject in the text fallback.
+ * In-progress glyphs blink by alternating with a same-width blank.
+ */
+
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { Task } from "./types.js";
+
+export type ThemeLike = {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+  strikethrough(text: string): string;
+};
+
+export function statusGlyph(_task: Task): string {
+  return "■";
+}
+
+function formatSecDuration(diffSec: number): string {
+  if (!Number.isFinite(diffSec) || diffSec < 0) diffSec = 0;
+  const days = Math.floor(diffSec / 86400);
+  const hours = Math.floor((diffSec % 86400) / 3600);
+  const minutes = Math.floor((diffSec % 3600) / 60);
+  const seconds = diffSec % 60;
+  const parts: string[] = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0) parts.push(`${seconds}s`);
+  return parts.join(" ");
+}
+
+/**
+ * Format a nonzero day/hour/minute/second elapsed duration from `createdAt`
+ * to `nowMs` (defaults to `Date.now()`), in order (e.g. `1d 1h 1m 1s`).
+ * Components whose value is zero are omitted; a sub-second (or future)
+ * duration yields an empty string. Kept for task-age compatibility; the
+ * widget itself measures attempts from `startedAt` and frozen `tookMs`.
+ */
+export function formatElapsedDuration(createdAt: string, nowMs: number = Date.now()): string {
+  const createdMs = Date.parse(createdAt);
+  return formatSecDuration(Math.floor((nowMs - createdMs) / 1000));
+}
+
+/** Format a millisecond duration the same way; sub-second (or negative) yields an empty string. */
+export function formatMillisDuration(ms: number): string {
+  if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) return "";
+  return formatSecDuration(Math.floor(ms / 1000));
+}
+
+/** Wall-clock union timing supplied by the store for the widget header. */
+export interface ActiveTiming {
+  totalActiveMs?: number;
+  activeSince?: string;
+}
+
+function attemptElapsedMs(task: Task, nowMs: number): number {
+  const startMs = Date.parse(task.startedAt ?? task.createdAt);
+  if (!Number.isFinite(startMs)) return 0;
+  return Math.max(0, nowMs - startMs);
+}
+
+function tookDisplay(task: Task): string {
+  if (task.tookMs !== undefined) return formatMillisDuration(task.tookMs) || "0s";
+  // Legacy completed task without a frozen duration: freeze the
+  // pre-upgrade age span so reloads neither reset it nor let it grow.
+  const endMs = Date.parse(task.updatedAt);
+  const startMs = Date.parse(task.createdAt);
+  if (!Number.isFinite(endMs) || !Number.isFinite(startMs)) return "0s";
+  return formatSecDuration(Math.floor(Math.max(0, endMs - startMs) / 1000)) || "0s";
+}
+
+function durationSuffix(task: Task, nowMs: number): string {
+  if (task.status === "in_progress") {
+    const elapsed = formatMillisDuration(attemptElapsedMs(task, nowMs)) || "0s";
+    return ` ${elapsed}`;
+  }
+  if (task.status === "completed") {
+    return ` ${tookDisplay(task)}`;
+  }
+  return "";
+}
+
+/** Pending-only dependency suffix appended after the subject. */
+export function blockedBySuffix(task: Task): string {
+  return task.status === "pending" && task.blockedBy.length > 0
+    ? ` → (${task.blockedBy.join(", ")})`
+    : "";
+}
+
+/** Resolve the header total: finished union time plus the running slice (if any). Zero renders as `0s`. */
+export function formatActiveTotal(timing: ActiveTiming | undefined, tasks: Task[], nowMs: number): string {
+  const base = timing?.totalActiveMs ?? 0;
+  let bonus = 0;
+  if (timing?.activeSince !== undefined) {
+    const startMs = Date.parse(timing.activeSince);
+    if (Number.isFinite(startMs)) bonus = Math.max(0, nowMs - startMs);
+  } else {
+    // Direct rendering without store timing (e.g. legacy tests): derive the
+    // running slice from the earliest active attempt so the header still ticks.
+    let earliest: number | undefined;
+    for (const task of tasks) {
+      if (task.status !== "in_progress") continue;
+      const startMs = Date.parse(task.startedAt ?? task.createdAt);
+      if (Number.isFinite(startMs)) earliest = earliest === undefined ? startMs : Math.min(earliest, startMs);
+    }
+    if (earliest !== undefined) bonus = Math.max(0, nowMs - earliest);
+  }
+  return formatMillisDuration(base + bonus) || "0s";
+}
+
+/** Plain-text line: `#<id> (<attempt>/<maxAttempts>) [assignee] subject`, a pending-only ` → (<blockedBy>)` suffix, and status-specific duration. No colors. */
+export function formatTaskLine(task: Task, nowMs: number = Date.now()): string {
+  const assignee = task.assignee !== undefined ? ` [${task.assignee}]` : "";
+  return `  ${statusGlyph(task)} #${task.id} (${task.attempt}/${task.maxAttempts})${assignee} ${task.subject}${blockedBySuffix(task)}${durationSuffix(task, nowMs)}`;
+}
+
+interface HeaderParts {
+  base: string;
+  activeTotal?: string;
+}
+
+function buildHeaderParts(tasks: Task[], nowMs: number, timing?: ActiveTiming): HeaderParts {
+  const done = tasks.filter((task) => task.status === "completed").length;
+  const taskLabel = tasks.length === 1 ? "task" : "tasks";
+  const base = `● ${tasks.length} ${taskLabel} (${done} done)`;
+  const hasStarted = tasks.some((task) => task.attempt > 0 || task.status === "in_progress");
+  return hasStarted ? { base, activeTotal: formatActiveTotal(timing, tasks, nowMs) } : { base };
+}
+
+/** Plain-text widget lines. Empty list yields no lines. `nowMs` fixes the elapsed clock for deterministic rendering; `timing` supplies the global union time. */
+export function buildWidgetLines(tasks: Task[], nowMs: number = Date.now(), timing?: ActiveTiming): string[] {
+  if (tasks.length === 0) return [];
+  const sorted = [...tasks].sort((a, b) => a.id - b.id);
+  const { base, activeTotal } = buildHeaderParts(sorted, nowMs, timing);
+  const header = activeTotal === undefined ? base : `${base} ${activeTotal}`;
+  return [header, ...sorted.map((task) => formatTaskLine(task, nowMs))];
+}
+
+/**
+ * Map a user-supplied task color to a known theme color. Unknown values yield
+ * `undefined` (callers fall back to the default glyph color) because
+ * `theme.fg` throws on unknown colors.
+ */
+export function themeColorFor(color: string | undefined): string | undefined {
+  if (color === undefined) return undefined;
+  const name = color.trim().toLowerCase();
+  const mapping: Record<string, string> = {
+    red: "error",
+    green: "success",
+    yellow: "warning",
+    blue: "accent",
+    cyan: "accent",
+    magenta: "accent",
+    purple: "accent",
+    gray: "dim",
+    grey: "dim",
+    white: "text",
+    black: "dim",
+  };
+  return mapping[name];
+}
+
+/** Truncate every line to `width` visible columns. Non-positive widths pass through. */
+function fitLinesToWidth(lines: string[], width: number | undefined): string[] {
+  if (width === undefined || !Number.isFinite(width) || width <= 0) return lines;
+  return lines.map((line) => truncateToWidth(line, width));
+}
+
+/**
+ * Themed widget lines. Falls back to plain lines if the theme rejects a color.
+ * When `width` is a positive finite number, every emitted line is truncated to
+ * fit that many visible columns (ANSI-aware, colors preserved). When
+ * `blinkOn` is false, in-progress glyphs render as a same-width blank (the
+ * widget toggles this to blink); plain-text lines always show steady glyphs.
+ * `nowMs` fixes the elapsed clock for deterministic rendering. Elapsed text
+ * always renders dim; the plain fallback already includes it.
+ */
+export function renderWidgetLines(tasks: Task[], theme: ThemeLike, width?: number, blinkOn = true, nowMs: number = Date.now(), timing?: ActiveTiming): string[] {
+  const plain = buildWidgetLines(tasks, nowMs, timing);
+  if (plain.length === 0) return plain;
+  try {
+    const sorted = [...tasks].sort((a, b) => a.id - b.id);
+    const { base, activeTotal } = buildHeaderParts(sorted, nowMs, timing);
+    const themedHeader = activeTotal === undefined
+      ? theme.fg("accent", base)
+      : `${theme.fg("accent", base)} ${theme.fg("dim", activeTotal)}`;
+    const lines = [themedHeader];
+    for (const task of sorted) {
+      const assigneeText = task.assignee !== undefined ? ` [${task.assignee}]` : "";
+      const idPart = theme.fg("dim", `#${task.id} (${task.attempt}/${task.maxAttempts})`);
+      const suffix = durationSuffix(task, nowMs);
+      const elapsedSuffix = suffix === "" ? "" : ` ${theme.fg("dim", suffix.trim())}`;
+      const completedSubject = theme.fg("dim", task.subject);
+      const completedAssignee = assigneeText ? theme.fg("dim", assigneeText) : "";
+      if (task.status === "completed") {
+        const glyphColor = themeColorFor(task.color) ?? "success";
+        lines.push(`  ${theme.fg(glyphColor, "■")} ${idPart}${completedAssignee} ${completedSubject}${elapsedSuffix}`);
+      } else if (task.status === "in_progress") {
+        const glyphColor = themeColorFor(task.color) ?? "success";
+        const assignee = assigneeText ? theme.fg("success", theme.bold(assigneeText)) : "";
+        lines.push(`  ${theme.fg(glyphColor, blinkOn ? "■" : " ")} ${idPart}${assignee} ${theme.fg("success", theme.bold(task.subject))}${elapsedSuffix}`);
+      } else {
+        const assignee = assigneeText ? theme.fg("text", assigneeText) : "";
+        const dependencies = blockedBySuffix(task);
+        lines.push(`  ${theme.fg("dim", "■")} ${idPart}${assignee} ${theme.fg("text", task.subject)}${dependencies ? theme.fg("dim", dependencies) : ""}${elapsedSuffix}`);
+      }
+    }
+    return fitLinesToWidth(lines, width);
+  } catch {
+    return fitLinesToWidth(plain, width);
+  }
+}
+
+/** Minimal TUI surface needed to read the live terminal width and request redraws for blinking/elapsed updates. */
+export type TuiWidthLike = {
+  terminal?: { columns?: unknown } | undefined;
+  requestRender?: ((force?: boolean) => void) | undefined;
+  renderNow?: ((force?: boolean) => void) | undefined;
+};
+
+/** Blink period for in-progress glyphs. */
+export const BLINK_INTERVAL_MS = 250;
+
+/** Redraw period for elapsed durations. Runs only while an in-progress task is shown. */
+export const ELAPSED_INTERVAL_MS = 1000;
+
+function hasInProgress(tasks: Task[]): boolean {
+  return tasks.some((task) => task.status === "in_progress");
+}
+
+/** Clock override for deterministic rendering/tests. A fixed epoch-ms pins elapsed output; a function is read on every render for live ticking. */
+export type NowProvider = number | (() => number);
+
+function resolveNow(now: NowProvider | undefined, fallback: number | undefined): number {
+  // A per-render override wins over the provider clock.
+  if (typeof fallback === "number" && Number.isFinite(fallback)) return fallback;
+  if (typeof now === "function") {
+    try {
+      const value = now();
+      if (typeof value === "number" && Number.isFinite(value)) return value;
+    } catch {
+      // Fall through to Date.now() below.
+    }
+  } else if (typeof now === "number" && Number.isFinite(now)) {
+    return now;
+  }
+  return Date.now();
+}
+
+/** Request a widget redraw via `requestRender()`, falling back to `renderNow()`. */
+function requestRedraw(tui: TuiWidthLike): void {
+  if (typeof tui?.requestRender === "function") tui.requestRender();
+  else if (typeof tui?.renderNow === "function") tui.renderNow();
+}
+
+/**
+ * Widget component factory. Reads the live `tui.terminal.columns` on every
+ * render (so lines keep fitting after resizes); an explicit positive render
+ * width wins when the TUI passes one. Elapsed durations read the live clock
+ * on every render (or the supplied `now` provider / `render()` override for
+ * deterministic tests).
+ *
+ * When the snapshot contains an in-progress task, a 250 ms timer alternates
+ * the in-progress glyph with a same-width blank and requests a redraw via
+ * `tui.requestRender()` (falling back to `tui.renderNow()`). The blink timer
+ * never starts without an in-progress task. A separate 1 s timer requests a
+ * redraw only while an in-progress task is shown so elapsed durations stay
+ * current. `dispose()` clears all timers, so redraws stop
+ * when the host replaces or removes the widget (the host disposes the
+ * previous widget on every `setWidget`, including refreshes after store
+ * changes and teardown). Follows the `Loader` component pattern in
+ * `@earendil-works/pi-tui` (interval + `requestRender`, cleared on stop).
+ */
+export function createTaskWidget(
+  snapshot: Task[],
+  tui: TuiWidthLike,
+  theme: ThemeLike,
+  now?: NowProvider,
+  timing?: ActiveTiming,
+): { render: (width?: number, nowMs?: number) => string[]; invalidate: () => void; dispose: () => void } {
+  let blinkOn = true;
+  let blinkTimer: ReturnType<typeof setInterval> | undefined;
+  let elapsedTimer: ReturnType<typeof setInterval> | undefined;
+  if (hasInProgress(snapshot)) {
+    blinkTimer = setInterval(() => {
+      blinkOn = !blinkOn;
+      requestRedraw(tui);
+    }, BLINK_INTERVAL_MS);
+  }
+  if (hasInProgress(snapshot)) {
+    elapsedTimer = setInterval(() => {
+      requestRedraw(tui);
+    }, ELAPSED_INTERVAL_MS);
+  }
+  return {
+    render: (width?: number, nowMs?: number) => {
+      const live = tui?.terminal?.columns;
+      const resolved =
+        typeof width === "number" && Number.isFinite(width) && width > 0
+          ? width
+          : typeof live === "number" && Number.isFinite(live) && live > 0
+            ? live
+            : undefined;
+      return renderWidgetLines(snapshot, theme, resolved, blinkOn, resolveNow(now, nowMs), timing);
+    },
+    invalidate: () => {},
+    dispose: () => {
+      if (blinkTimer !== undefined) {
+        clearInterval(blinkTimer);
+        blinkTimer = undefined;
+      }
+      if (elapsedTimer !== undefined) {
+        clearInterval(elapsedTimer);
+        elapsedTimer = undefined;
+      }
+    },
+  };
+}