@tidegap/cli 0.0.0-stage → 0.19.0

package/ui/dialog.js

@@ -0,0 +1,284 @@
+// Modal dialogs on one native <dialog>: reschedule (date and time), the
+// move-to list (the touch and keyboard path for drag and drop), the row
+// action menu, confirmations and the shortcut help. showModal() gives focus
+// containment and Esc; focus goes back to where it was on close.
+
+import {
+  dateInput,
+  dayLabel,
+  dayOffset,
+  fromInputs,
+  h,
+  hm,
+  parse,
+  relDay,
+  timeInput,
+  title,
+  when,
+} from "./dom.js";
+
+const HOUR = 3_600_000;
+let returnTo = null;
+let returnId = null;
+let onClose = null;
+
+function dlg() {
+  return document.getElementById("dialog");
+}
+
+export function dialogOpen() {
+  return dlg().open;
+}
+
+/** Open the shared dialog with `content` (used by other panels). */
+export function openDialog(content, opts) {
+  open(content, opts);
+}
+
+function open(content, { label, wide = false, close } = {}) {
+  const d = dlg();
+  if (d.open) d.close();
+  // A menu item that opens the next dialog keeps the original focus target.
+  if (!returnTo?.isConnected) {
+    returnTo = document.activeElement;
+    // Inside the drawer the drawer itself is the fallback; on a row, the row.
+    returnId = returnTo?.closest?.("#drawer") ? null : returnTo?.closest?.("[data-task-id]")?.dataset.taskId || null;
+  }
+  onClose?.();
+  onClose = close || null;
+  d.className = `dialog${wide ? " dialog-wide" : ""}`;
+  d.replaceChildren(...content);
+  if (label) d.setAttribute("aria-label", label);
+  else d.removeAttribute("aria-label");
+  d.showModal();
+  const first = d.querySelector("[autofocus], .menu-item, input, button");
+  first?.focus();
+}
+
+export function closeDialog() {
+  const d = dlg();
+  if (d.open) d.close();
+}
+
+export function initDialog() {
+  const d = dlg();
+  d.addEventListener("close", () => {
+    // close fires after the fact; a dialog opened meanwhile owns the box now.
+    if (d.open) return;
+    const fn = onClose;
+    onClose = null;
+    d.replaceChildren();
+    if (returnTo?.isConnected) returnTo.focus();
+    else if (returnId) {
+      // The row was rebuilt while the dialog was open (an action, a stream
+      // event): focus its replacement, else the view.
+      const row = [...document.querySelectorAll("#view .row[data-task-id]")].find((r) => r.dataset.taskId === returnId);
+      (row || document.getElementById("view"))?.focus();
+    } else {
+      const drawer = document.getElementById("drawer");
+      if (drawer && !drawer.hidden) drawer.querySelector(".drawer-close, button")?.focus();
+    }
+    returnTo = null;
+    returnId = null;
+    fn?.();
+  });
+  // A click on the backdrop (the dialog box itself, outside its content) closes.
+  d.addEventListener("click", (e) => {
+    if (e.target === d) d.close();
+  });
+  // Arrow keys move through menu items.
+  d.addEventListener("keydown", (e) => {
+    if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
+    const items = [...d.querySelectorAll(".menu-item:not([disabled])")];
+    if (items.length === 0) return;
+    e.preventDefault();
+    const i = items.indexOf(document.activeElement);
+    const next = e.key === "ArrowDown" ? (i + 1) % items.length : (i - 1 + items.length) % items.length;
+    items[next].focus();
+  });
+}
+
+function head(text, sub) {
+  return h("header", { class: "dialog-head" },
+    h("h2", { id: "dialog-title", class: "dialog-title" }, text),
+    sub ? h("p", { class: "dialog-sub" }, sub) : null);
+}
+
+/** Day bounds as ISO instants in the browser's zone; today starts now. */
+export function dayBounds(dayStartMs, now = Date.now()) {
+  const next = new Date(dayStartMs);
+  next.setDate(next.getDate() + 1);
+  const start = Math.max(dayStartMs, now);
+  const end = next.getTime();
+  if (end - start < HOUR) return null;
+  return { day_start: new Date(start).toISOString(), day_end: new Date(end).toISOString() };
+}
+
+/**
+ * Reschedule dialog. `onSubmit(target, summary)` gets the API body:
+ * {at}, {day_start, day_end} or {deadline}.
+ */
+export function rescheduleDialog(task, onSubmit) {
+  const now = Date.now();
+  const current = parse(task.scheduled_for);
+  const base = Number.isFinite(current) && current > now ? current : now + HOUR;
+  const date = h("input", { type: "date", class: "input", id: "rs-date", value: dateInput(base), min: dateInput(now), required: true });
+  const time = h("input", { type: "time", class: "input", id: "rs-time", value: timeInput(base), step: "300" });
+  const modes = [
+    ["at", "At this time", "Runs at the exact time. No carbon choice."],
+    ["day", "Cleanest hour that day", "tidegap picks the cleanest forecast hour on that day."],
+    ["deadline", "Cleanest hour before", "tidegap picks the cleanest hour between now and this time."],
+  ];
+  const err = h("p", { class: "form-error", role: "alert", hidden: true });
+  const radios = modes.map(([value, label, hint], i) =>
+    h("label", { class: "radio" },
+      h("input", { type: "radio", name: "rs-mode", value, checked: i === 0 ? true : undefined }),
+      h("span", { class: "radio-body" }, h("span", { class: "radio-label" }, label), h("span", { class: "radio-hint" }, hint))));
+  const timeField = h("label", { class: "field" }, h("span", { class: "field-label" }, "Time"), time);
+  const form = h("form", { class: "dialog-form", method: "dialog" },
+    head("Reschedule", title(task)),
+    h("fieldset", { class: "radios" }, h("legend", { class: "sr-only" }, "How to schedule"), radios),
+    h("div", { class: "field-row" },
+      h("label", { class: "field" }, h("span", { class: "field-label" }, "Date"), date),
+      timeField),
+    err,
+    h("footer", { class: "dialog-foot" },
+      h("button", { type: "button", class: "btn btn-ghost", onclick: closeDialog }, "Cancel"),
+      h("button", { type: "submit", class: "btn btn-primary" }, "Reschedule")));
+  const mode = () => form.querySelector('input[name="rs-mode"]:checked').value;
+  form.addEventListener("change", () => {
+    timeField.hidden = mode() === "day";
+  });
+  form.addEventListener("submit", (e) => {
+    e.preventDefault();
+    const m = mode();
+    const ms = fromInputs(date.value, m === "day" ? "00:00" : time.value);
+    const fail = (msg) => {
+      err.textContent = msg;
+      err.hidden = false;
+    };
+    if (!Number.isFinite(ms)) return fail("Pick a valid date and time.");
+    let target, summary;
+    if (m === "day") {
+      const b = dayBounds(ms);
+      if (!b) return fail("That day is over. Pick a later day.");
+      target = b;
+      summary = `Moved to ${dayName(ms)}`;
+    } else {
+      if (ms < Date.now()) return fail("That time has passed.");
+      target = m === "at" ? { at: new Date(ms).toISOString() } : { deadline: new Date(ms).toISOString() };
+      summary = m === "at" ? "Rescheduled" : `Due by ${when(ms)}`;
+    }
+    closeDialog();
+    onSubmit(target, summary, ms);
+  });
+  open([form], { label: "Reschedule" });
+}
+
+/** Move-to list: Run now, Today, Tomorrow, next 5 days, Pick date and time. */
+export function moveDialog(task, { runNow, moveTo, pick }) {
+  const now = Date.now();
+  const at = parse(task.scheduled_for);
+  const items = [];
+  if (task.actions?.runNow) {
+    items.push(menuItem("▶", "Run now", "on the next dispatcher tick", runNow));
+  }
+  for (let i = 0; i < 7; i++) {
+    const start = dayOffset(i, now);
+    const bounds = dayBounds(start, now);
+    if (!bounds) continue;
+    const same = Number.isFinite(at) && dayOffset(0, at) === start;
+    const label = i < 2 ? relDay(start, now) : dayLabel(start);
+    items.push(menuItem("↦", label, same ? "current day" : i < 2 ? dayLabel(start) : "cleanest hour that day", () => moveTo(start, bounds), same));
+  }
+  items.push(menuItem("…", "Pick date and time…", "exact time or deadline", pick));
+  open([head("Move to", title(task)), h("div", { class: "menu", role: "menu" }, items)], { label: "Move to" });
+}
+
+/** Row "⋯" menu: every action for touch and narrow screens. */
+export function actionMenu(task, handlers) {
+  const a = task.actions || {};
+  const items = [menuItem("→", "Open", "details, result, reply", handlers.open)];
+  if (a.runNow) items.push(menuItem("▶", "Run now", "n", handlers.runNow));
+  if (a.reschedule) {
+    items.push(menuItem("↦", "Move to…", "m", handlers.move));
+    items.push(menuItem("⏲", "Reschedule…", "r", handlers.reschedule));
+  }
+  if (a.markRead) items.push(menuItem("●", task.read_at ? "Mark unread" : "Mark read", "u", handlers.toggleRead));
+  if (a.cancel) items.push(menuItem("✕", "Cancel", "c", handlers.cancel, false, "danger"));
+  if (a.stopSeries) items.push(menuItem("⊘", "Stop series", "C", handlers.stopSeries, false, "danger"));
+  open([head(title(task)), h("div", { class: "menu", role: "menu" }, items)], { label: "Task actions" });
+}
+
+function menuItem(glyph, label, hint, run, disabled = false, tone = "") {
+  return h("button", {
+    type: "button",
+    class: ["menu-item", tone && `menu-${tone}`],
+    role: "menuitem",
+    disabled: disabled ? true : undefined,
+    onclick: () => {
+      closeDialog();
+      run();
+    },
+  },
+  h("span", { class: "menu-glyph", "aria-hidden": "true" }, glyph),
+  h("span", { class: "menu-label" }, label),
+  hint ? h("span", { class: "menu-hint" }, hint) : null);
+}
+
+/** Confirmation; resolves true on confirm. */
+export function confirmDialog({ heading, body, confirm, danger = false }) {
+  return new Promise((resolve) => {
+    let ok = false;
+    const form = h("form", { class: "dialog-form", method: "dialog" },
+      head(heading),
+      body ? h("p", { class: "dialog-body" }, body) : null,
+      h("footer", { class: "dialog-foot" },
+        h("button", { type: "button", class: "btn btn-ghost", onclick: closeDialog }, "Keep"),
+        h("button", { type: "submit", class: `btn ${danger ? "btn-danger-solid" : "btn-primary"}`, autofocus: true }, confirm)));
+    form.addEventListener("submit", (e) => {
+      e.preventDefault();
+      ok = true;
+      closeDialog();
+    });
+    open([form], { label: heading, close: () => resolve(ok) });
+  });
+}
+
+const SHORTCUTS = [
+  ["j / ↓", "next row"],
+  ["k / ↑", "previous row"],
+  ["Enter", "open detail"],
+  ["Esc", "close dialog, drawer or drag"],
+  ["c", "cancel (with Undo)"],
+  ["C", "stop series"],
+  ["r", "reschedule"],
+  ["m", "move to a day"],
+  ["n", "run now"],
+  ["u", "mark read / unread"],
+  ["R", "reply (completed task)"],
+  ["1 2 3", "Agenda, Timeline, Journal"],
+  ["/", "Journal filters"],
+  ["?", "this help"],
+];
+
+export function helpDialog() {
+  open([
+    head("Keyboard shortcuts"),
+    h("dl", { class: "keys" }, SHORTCUTS.map(([k, v]) => [h("dt", {}, k.split(" ").map((x) => (x === "/" && k !== "/" ? " / " : h("kbd", {}, x)))), h("dd", {}, v)])),
+    h("footer", { class: "dialog-foot" }, h("button", { type: "button", class: "btn", onclick: closeDialog, autofocus: true }, "Close")),
+  ], { label: "Keyboard shortcuts", wide: true });
+}
+
+/** Confirmation text: "Moved to Fri 16 Oct · runs 03:00" or "Rescheduled · runs tomorrow 10:30". */
+export function movedText(t, fallback, dayKnown = false) {
+  const at = parse(t?.scheduled_for);
+  if (!Number.isFinite(at)) return fallback;
+  return `${fallback} · runs ${dayKnown ? hm(at) : when(at)}`;
+}
+
+/** "Tomorrow · Fri 16 Oct" or "Sat 17 Oct". */
+export function dayName(ms) {
+  const rel = relDay(ms);
+  return rel === dayLabel(ms) ? rel : `${rel} · ${dayLabel(ms)}`;
+}

package/ui/dnd.js

@@ -0,0 +1,131 @@
+// Native HTML5 drag and drop: a row onto a day header (move to that day)
+// or onto the "Run now" zone. While a row is dragged, a dock under the
+// header shows Run now plus the next seven days, and every day header in
+// the Agenda is outlined. Only valid targets accept the drop. Touch and
+// keyboard use the move-to list (dialog.js) instead.
+
+import { dayLabel, dayOffset, h, parse, relDay } from "./dom.js";
+import { dayBounds } from "./dialog.js";
+
+const MIME = "text/x-tidegap-task";
+let drag = null;
+
+export function isDragging() {
+  return drag !== null;
+}
+
+/**
+ * Wire drag and drop on the page.
+ *   findTask(id) -> task
+ *   onMove(task, dayStartMs, bounds)
+ *   onRunNow(task)
+ *   onEnd()     re-render deferred while dragging
+ */
+export function initDnd({ findTask, onMove, onRunNow, onEnd }) {
+  const dock = document.getElementById("drop-dock");
+
+  document.addEventListener("dragstart", (e) => {
+    const row = e.target instanceof Element ? e.target.closest(".row[draggable='true']") : null;
+    if (!row) return;
+    const task = findTask(row.dataset.taskId);
+    if (!task?.actions?.reschedule) {
+      e.preventDefault();
+      return;
+    }
+    const at = parse(task.scheduled_for);
+    drag = { task, row, day: Number.isFinite(at) ? dayOffset(0, at) : null };
+    e.dataTransfer.setData(MIME, task.task_id);
+    e.dataTransfer.setData("text/plain", task.display_title || task.task_id);
+    e.dataTransfer.effectAllowed = "move";
+    buildDock(dock, task, drag.day);
+    // Let the browser snapshot the row before it fades.
+    requestAnimationFrame(() => {
+      if (!drag) return;
+      row.classList.add("is-dragging");
+      document.body.classList.add("dragging");
+      dock.hidden = false;
+    });
+  });
+
+  document.addEventListener("dragover", (e) => {
+    if (!drag) return;
+    const target = dropTarget(e.target);
+    clearOver(target);
+    if (!target || !valid(target)) {
+      e.dataTransfer.dropEffect = "none";
+      return;
+    }
+    e.preventDefault();
+    e.dataTransfer.dropEffect = "move";
+    target.classList.add("drop-over");
+  });
+
+  document.addEventListener("dragleave", (e) => {
+    const target = dropTarget(e.target);
+    // Chrome often sends no relatedTarget; the next dragover clears stale outlines.
+    if (target && e.relatedTarget && !target.contains(e.relatedTarget)) target.classList.remove("drop-over");
+  });
+
+  document.addEventListener("drop", (e) => {
+    if (!drag) return;
+    const target = dropTarget(e.target);
+    if (!target || !valid(target)) return;
+    e.preventDefault();
+    const task = drag.task;
+    finish();
+    if (target.dataset.dropRun !== undefined) onRunNow(task);
+    else {
+      const start = Number(target.dataset.dropDay);
+      onMove(task, start, dayBounds(start));
+    }
+  });
+
+  document.addEventListener("dragend", () => {
+    if (drag) finish();
+  });
+
+  function finish() {
+    drag?.row.classList.remove("is-dragging");
+    drag = null;
+    document.body.classList.remove("dragging");
+    clearOver(null);
+    dock.hidden = true;
+    dock.replaceChildren();
+    onEnd();
+  }
+}
+
+function dropTarget(node) {
+  return node instanceof Element ? node.closest("[data-drop-day], [data-drop-run]") : null;
+}
+
+function valid(target) {
+  if (!drag) return false;
+  if (target.dataset.dropRun !== undefined) return !!drag.task.actions?.runNow;
+  const start = Number(target.dataset.dropDay);
+  if (!Number.isFinite(start) || start === drag.day) return false;
+  return dayBounds(start) !== null;
+}
+
+function clearOver(keep) {
+  for (const el of document.querySelectorAll(".drop-over")) if (el !== keep) el.classList.remove("drop-over");
+}
+
+function buildDock(dock, task, currentDay) {
+  const now = Date.now();
+  const items = [];
+  if (task.actions?.runNow) {
+    items.push(h("div", { class: "dock-target dock-run", "data-drop-run": "" }, h("span", { class: "dock-glyph" }, "▶"), "Run now"));
+  }
+  for (let i = 0; i < 7; i++) {
+    const start = dayOffset(i, now);
+    if (!dayBounds(start, now)) continue;
+    const same = start === currentDay;
+    items.push(h("div", {
+      class: ["dock-target", same && "is-current"],
+      "data-drop-day": String(start),
+      "aria-label": same ? `${dayLabel(start)} (current day)` : `Move to ${dayLabel(start)}`,
+    }, h("span", { class: "dock-day" }, i < 2 ? relDay(start, now) : dayLabel(start).split(" ")[0]), h("span", { class: "dock-date" }, dayLabel(start).split(" ").slice(1).join(" "))));
+  }
+  dock.replaceChildren(h("span", { class: "dock-label" }, "Drop on"), ...items);
+}

package/ui/dom.js

@@ -0,0 +1,255 @@
+// DOM and formatting helpers. Task strings (titles, prompts, results) are
+// untrusted model or user text: they only ever reach the page as text
+// nodes or attribute values, never as markup.
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+/** Element builder: h("p", {class: "x"}, "text", child). */
+export function h(tag, attrs = {}, ...children) {
+  const el = document.createElement(tag);
+  setAttrs(el, attrs);
+  append(el, children);
+  return el;
+}
+
+/** SVG element builder. */
+export function s(tag, attrs = {}, ...children) {
+  const el = document.createElementNS(SVG_NS, tag);
+  setAttrs(el, attrs);
+  append(el, children);
+  return el;
+}
+
+function setAttrs(el, attrs) {
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === undefined || v === null || v === false) continue;
+    if (k === "class") el.setAttribute("class", Array.isArray(v) ? v.filter(Boolean).join(" ") : v);
+    else if (k.startsWith("on") && typeof v === "function") el.addEventListener(k.slice(2), v);
+    else if (k === "dataset") Object.assign(el.dataset, v);
+    else if (k === "value" && "value" in el) el.value = v;
+    else el.setAttribute(k, v === true ? "" : String(v));
+  }
+}
+
+function append(el, children) {
+  for (const c of children.flat(Infinity)) {
+    if (c === undefined || c === null || c === false) continue;
+    el.append(c instanceof Node ? c : document.createTextNode(String(c)));
+  }
+}
+
+/**
+ * Replace `el`'s children unless the new ones are identical, so a redraw
+ * with no change keeps the live nodes (and any click in flight on them).
+ */
+export function swapChildren(el, children) {
+  const next = children.flat(Infinity).filter((c) => c !== null && c !== undefined && c !== false);
+  const nodes = next.map((c) => (c instanceof Node ? c : document.createTextNode(String(c))));
+  const same = el.childNodes.length === nodes.length && nodes.every((n, i) => n.isEqualNode(el.childNodes[i]));
+  if (!same) el.replaceChildren(...nodes);
+  return !same;
+}
+
+// ── time ────────────────────────────────────────────────────────────────
+
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+const LOCALE = "en-GB";
+
+export function parse(iso) {
+  if (!iso) return NaN;
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? t : NaN;
+}
+
+/** Local midnight of the day holding `ms`. */
+export function dayStart(ms) {
+  const d = new Date(ms);
+  d.setHours(0, 0, 0, 0);
+  return d.getTime();
+}
+
+/** Local midnight of the day after the one holding `ms` (DST-safe). */
+export function nextDayStart(ms) {
+  const d = new Date(dayStart(ms));
+  d.setDate(d.getDate() + 1);
+  return d.getTime();
+}
+
+/** Local midnight `n` days after today's. */
+export function dayOffset(n, from = Date.now()) {
+  const d = new Date(dayStart(from));
+  d.setDate(d.getDate() + n);
+  return d.getTime();
+}
+
+/** Whole local days from today to the day holding `ms` (0 = today). */
+export function daysFromToday(ms, now = Date.now()) {
+  return Math.round((dayStart(ms) - dayStart(now)) / DAY);
+}
+
+/** "14:00" */
+export function hm(ms) {
+  if (!Number.isFinite(ms)) return "";
+  return new Date(ms).toLocaleTimeString(LOCALE, { hour: "2-digit", minute: "2-digit", hourCycle: "h23" });
+}
+
+/** "Thu 15 Oct" */
+export function dayLabel(ms) {
+  return new Date(ms).toLocaleDateString(LOCALE, { weekday: "short", day: "numeric", month: "short" });
+}
+
+/** "Today", "Tomorrow", "Yesterday" or "Thu 15 Oct". */
+export function relDay(ms, now = Date.now()) {
+  const n = daysFromToday(ms, now);
+  if (n === 0) return "Today";
+  if (n === 1) return "Tomorrow";
+  if (n === -1) return "Yesterday";
+  return dayLabel(ms);
+}
+
+/** "Today 14:00", "Fri 18:00" (this week) or "Thu 29 Oct 14:00". */
+export function when(ms, now = Date.now()) {
+  if (!Number.isFinite(ms)) return "";
+  const n = daysFromToday(ms, now);
+  if (n === 0) return `today ${hm(ms)}`;
+  if (n === 1) return `tomorrow ${hm(ms)}`;
+  if (n > 1 && n < 7) {
+    return `${new Date(ms).toLocaleDateString(LOCALE, { weekday: "short" })} ${hm(ms)}`;
+  }
+  return `${dayLabel(ms)} ${hm(ms)}`;
+}
+
+/** Deadline text: "by Fri 18:00", or "by end of Fri" for a midnight deadline. */
+export function by(ms, now = Date.now()) {
+  if (!Number.isFinite(ms)) return "";
+  const d = new Date(ms);
+  if (d.getHours() === 0 && d.getMinutes() === 0) {
+    const day = relDay(ms - 1, now);
+    return `by end of ${day === "Today" || day === "Tomorrow" ? day.toLowerCase() : day}`;
+  }
+  return `by ${when(ms, now)}`;
+}
+
+/** "just now", "4 min ago", "3 h ago", "2 days ago". */
+export function ago(ms, now = Date.now()) {
+  const d = now - ms;
+  if (!Number.isFinite(d)) return "";
+  const min = Math.round(d / 60000);
+  if (min < 1) return "just now";
+  if (min < 60) return `${min} min ago`;
+  const hr = Math.round(min / 60);
+  if (hr < 48) return `${hr} h ago`;
+  return `${Math.round(hr / 24)} days ago`;
+}
+
+const pad2 = (n) => String(n).padStart(2, "0");
+
+/** Value for <input type="date"> in local time. */
+export function dateInput(ms) {
+  const d = new Date(ms);
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+/** Value for <input type="time"> in local time. */
+export function timeInput(ms) {
+  const d = new Date(ms);
+  return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+
+/** Local date + time inputs to epoch ms (NaN when invalid). */
+export function fromInputs(date, time) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date || "");
+  const t = /^(\d{2}):(\d{2})$/.exec(time || "00:00");
+  if (!m || !t) return NaN;
+  return new Date(+m[1], +m[2] - 1, +m[3], +t[1], +t[2]).getTime();
+}
+
+// ── carbon bands ────────────────────────────────────────────────────────
+
+/** Same thresholds as packages/core-ts/src/data/bands.json (g/kWh). */
+const BAND_LIMITS = [
+  [100, "very_clean"],
+  [250, "clean"],
+  [450, "average"],
+  [700, "dirty"],
+];
+
+export function bandOf(g) {
+  if (typeof g !== "number" || !Number.isFinite(g)) return null;
+  for (const [max, band] of BAND_LIMITS) if (g < max) return band;
+  return "very_dirty";
+}
+
+export const BAND_LABEL = {
+  very_clean: "very clean",
+  clean: "clean",
+  average: "average",
+  dirty: "dirty",
+  very_dirty: "very dirty",
+};
+
+/** Band chip: colour plus the text label, so colour is never the only cue. */
+export function bandChip(band, opts = {}) {
+  if (!band) return null;
+  return h("span", { class: `chip band band-${band}`, title: opts.title }, BAND_LABEL[band] || band);
+}
+
+/** "0.41 g" with two significant digits under 10 g. */
+export function grams(g) {
+  if (typeof g !== "number" || !Number.isFinite(g)) return "";
+  if (g === 0) return "0 g";
+  if (g < 0.01) return "<0.01 g";
+  if (g < 10) return `${g.toFixed(g < 1 ? 2 : 1)} g`;
+  return `${Math.round(g)} g`;
+}
+
+// ── task facts ──────────────────────────────────────────────────────────
+
+export const PENDING = ["queued", "scheduled", "submitted", "running"];
+export const FINISHED = ["completed", "failed", "cancelled"];
+
+export function isFinished(t) {
+  return FINISHED.includes(t.status);
+}
+
+export function isUnread(t) {
+  return (t.status === "completed" || t.status === "failed") && !t.read_at;
+}
+
+export function title(t) {
+  return t.display_title || t.title || t.task_id;
+}
+
+export const REPEAT_LABEL = {
+  daily: "repeats daily",
+  weekly: "repeats weekly",
+  quota_reset: "repeats every reset",
+};
+
+/** "anthropic · sonnet-5" or "". */
+export function providerModel(t) {
+  const model = t.model ? shortModel(t.model) : "";
+  return [t.provider, model].filter(Boolean).join(" · ");
+}
+
+/** "claude-sonnet-4-5-20250929" -> "sonnet-4-5". */
+function shortModel(m) {
+  return String(m).replace(/^claude-/, "").replace(/-\d{8}$/, "").replace(/-latest$/, "");
+}
+
+/** Short task id for monospace hints: first 8 characters. */
+export function shortId(id) {
+  return String(id).length > 12 ? `${String(id).slice(0, 8)}…` : String(id);
+}
+
+export function taskHref(id) {
+  return `#/task/${encodeURIComponent(id)}`;
+}
+
+/** True when keyboard focus is in a text field, so single-key shortcuts stay off. */
+export function typing(target = document.activeElement) {
+  if (!target) return false;
+  const tag = target.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || target.isContentEditable;
+}