whose-turn 0.0.0-stage → 1.0.0-alpha.2

package/lib/static.mjs

@@ -0,0 +1,36 @@
+/** Serves the built window from dist/ (ADR 0001): hashed assets cached by the browser for good, the pages never cached, files read once per build. A checkout without a build gets a plain notice. */
+import { readFile, stat } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+
+const TYPES = { '.html': 'text/html', '.js': 'application/javascript', '.css': 'text/css', '.svg': 'image/svg+xml', '.map': 'application/json' };
+const PAGES = { '/': 'index.html', '/report': 'report.html', '/sheet': 'sheet.html' };
+const UNBUILT = Buffer.from('<!doctype html><meta charset="utf-8"><title>Whose Turn</title><p style="font: 15px system-ui; margin: 40px">The window is not built. Run <code>npm run build</code> in the whose-turn directory, then reload. The API on this port works without it.</p>');
+
+export const createStatic = (distDir) => {
+  const cache = new Map();
+  const read = async (relative) => {
+    const file = join(distDir, relative);
+    const { mtimeMs } = await stat(file);
+    const hit = cache.get(relative);
+    if (hit && hit.mtimeMs === mtimeMs) {
+      return hit.body;
+    }
+    const body = await readFile(file);
+    cache.set(relative, { mtimeMs, body });
+    return body;
+  };
+  /** The file for a path, with its type and cache header, or null when the path is not a window file; the unbuilt notice stands in for a missing page. */
+  return async (pathname) => {
+    const relative = PAGES[pathname] || pathname.replace(/^\/+/, '');
+    const type = TYPES[extname(relative)];
+    if (!type || relative.split('/').includes('..')) {
+      return null;
+    }
+    const page = Boolean(PAGES[pathname]);
+    try {
+      return { body: await read(relative), type, cacheControl: page ? 'no-store' : relative.startsWith('assets/') ? 'public, max-age=31536000, immutable' : 'public, max-age=3600' };
+    } catch {
+      return page ? { body: UNBUILT, type: 'text/html', cacheControl: 'no-store' } : null;
+    }
+  };
+};

package/lib/store.mjs

@@ -0,0 +1,61 @@
+/** One workspace's files on disk: state.json (last poll per source), marks.json (seen, handled, notified, health alerts already announced), todos.json and cache.json (connector caches that are data). */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { DAY } from './text.mjs';
+
+export const readJson = (path, fallback) => {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return fallback;
+  }
+};
+
+export const writeJson = (path, value) => {
+  writeFileSync(`${path}.tmp`, JSON.stringify(value));
+  renameSync(`${path}.tmp`, path);
+};
+
+const CACHE_VERSION = 1;
+
+const encodeCache = (cache, keys) => Object.fromEntries(keys.filter((key) => cache[key] instanceof Map).map((key) => [key, [...cache[key]]]));
+
+const decodeCache = (saved) => Object.fromEntries(Object.entries(saved || {}).filter(([, entries]) => Array.isArray(entries)).map(([key, entries]) => [key, new Map(entries)]));
+
+export const openStore = (dataDir, workspaceId) => {
+  const root = resolve(dataDir, 'workspaces');
+  const dir = resolve(root, workspaceId);
+  if (!dir.startsWith(root + sep)) {
+    throw new Error(`Workspace id "${workspaceId}" resolves outside the data directory.`);
+  }
+  mkdirSync(dir, { recursive: true });
+  const files = { state: join(dir, 'state.json'), marks: join(dir, 'marks.json'), todos: join(dir, 'todos.json'), cache: join(dir, 'cache.json') };
+  const state = { version: 0, errors: {}, polled_at: '', fails: {}, sources: {}, events: [], ...readJson(files.state, {}) };
+  const marks = { seen: [], base: null, handled: {}, notified: [], notified_seeded: false, health_alerted: [], ...readJson(files.marks, {}) };
+  if (!marks.base) {
+    marks.base = Date.now() - 3 * DAY;
+  }
+  const todos = readJson(files.todos, []);
+  const saved = readJson(files.cache, {});
+  const savedCaches = saved.version === CACHE_VERSION && saved.entries ? saved.entries : {};
+  let savedText = '';
+  return {
+    state,
+    marks,
+    todos,
+    saveState: () => writeJson(files.state, state),
+    saveMarks: () => writeJson(files.marks, marks),
+    saveTodos: () => writeJson(files.todos, todos),
+    loadCache: (entryId) => decodeCache(savedCaches[entryId]),
+    /** keysByEntry: entry id → the cache keys that are data; anything else (the token) never reaches disk. */
+    saveCaches: (caches, keysByEntry) => {
+      const entries = Object.fromEntries(Object.entries(keysByEntry).map(([entryId, keys]) => [entryId, encodeCache(caches[entryId] || {}, keys)]));
+      const file = { version: CACHE_VERSION, entries };
+      const text = JSON.stringify(file);
+      if (text !== savedText) {
+        savedText = text;
+        writeJson(files.cache, file);
+      }
+    },
+  };
+};

package/lib/table.mjs

@@ -0,0 +1,148 @@
+/** The rules table: validating rows, expanding the "default" marker, finding the first row whose conditions hold, filling {fact} placeholders. See docs/mechanisms/rules-table.md. */
+import { FACTS } from './facts.mjs';
+
+/** `then.whose` values: the label the row shows, and the feed group it forces (none keeps the seed row's group). */
+export const WHOSE = {
+  you: { label: 'You', group: 'you' },
+  reviewer: { label: 'Reviewer', group: null },
+  qa: { label: 'QA', group: null },
+  them: { label: null, group: null },
+  hidden: { label: null, group: 'gone' },
+};
+const THEN_KEYS = ['whose', 'next', 'why', 'rank', 'started', 'hold'];
+const DEFAULT_MARKER = 'default';
+
+const present = (value) => value !== null && value !== undefined;
+const NUMBER_OPERATORS = {
+  gt: (value, operand) => present(value) && value > operand,
+  gte: (value, operand) => present(value) && value >= operand,
+  lt: (value, operand) => present(value) && value < operand,
+  lte: (value, operand) => present(value) && value <= operand,
+};
+const OPERATORS = {
+  ...NUMBER_OPERATORS,
+  prefix: (value, operand) => present(value) && String(value).startsWith(operand),
+  present: (value, operand) => present(value) === operand,
+};
+const PLACEHOLDER = /\{([\w.]+)\}/g;
+
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const conditionHolds = (value, condition) => {
+  if (Array.isArray(condition)) {
+    return condition.includes(value);
+  }
+  if (isPlainObject(condition)) {
+    return Object.entries(condition).every(([operator, operand]) => OPERATORS[operator](value, operand));
+  }
+  return value === condition;
+};
+
+export const firstMatch = (table, facts) => table.find((row) => Object.entries(row.when).every(([fact, condition]) => conditionHolds(facts[fact], condition)));
+
+/** Replaces each {fact} with its value; a missing fact becomes empty text, an unknown name is left as written. */
+export const fillText = (text, facts) => String(text || '').replace(PLACEHOLDER, (placeholder, name) => (name in FACTS ? String(facts[name] ?? '') : placeholder));
+
+export const expandTable = (table, defaults) => (Array.isArray(table) ? table.flatMap((row) => (row === DEFAULT_MARKER ? defaults : [row])) : defaults);
+
+const closedValues = (name, groups) => {
+  const values = FACTS[name].values;
+  return values === 'status groups' ? groups : values;
+};
+
+const valueProblem = (name, value, groups) => {
+  const fact = FACTS[name];
+  if (typeof value !== fact.type) {
+    return `"${name}" is a ${fact.type}, got ${JSON.stringify(value)}`;
+  }
+  const values = closedValues(name, groups);
+  return values && !values.includes(value) ? `"${name}" is one of ${values.join(', ')}, got ${JSON.stringify(value)}` : null;
+};
+
+const operatorProblem = (name, operator, operand) => {
+  const type = FACTS[name].type;
+  if (operator in NUMBER_OPERATORS) {
+    return type === 'number' && typeof operand === 'number' ? null : `"${operator}" needs a number fact and a number, "${name}" is a ${type}`;
+  }
+  if (operator === 'prefix') {
+    return type === 'string' && typeof operand === 'string' ? null : `"prefix" needs a text fact and a text, "${name}" is a ${type}`;
+  }
+  if (operator === 'present') {
+    return typeof operand === 'boolean' ? null : `"present" needs true or false, got ${JSON.stringify(operand)}`;
+  }
+  return `unknown operator "${operator}" on "${name}"; use gt, gte, lt, lte, prefix or present`;
+};
+
+const conditionProblems = (name, condition, groups) => {
+  if (!(name in FACTS)) {
+    return [`unknown fact "${name}"; GET /api/config lists the facts`];
+  }
+  if (Array.isArray(condition)) {
+    return condition.length ? condition.map((value) => valueProblem(name, value, groups)).filter(Boolean) : [`the list for "${name}" is empty`];
+  }
+  if (isPlainObject(condition)) {
+    const entries = Object.entries(condition);
+    return entries.length ? entries.map(([operator, operand]) => operatorProblem(name, operator, operand)).filter(Boolean) : [`the condition on "${name}" is an empty object`];
+  }
+  const problem = valueProblem(name, condition, groups);
+  return problem ? [problem] : [];
+};
+
+const placeholderProblems = (text) => [...String(text).matchAll(PLACEHOLDER)].filter(([, name]) => !(name in FACTS)).map(([, name]) => `unknown fact "{${name}}" in the text`);
+
+const thenProblems = (then) => {
+  if (!isPlainObject(then)) {
+    return ['"then" must be an object { whose, next, why?, rank?, started?, hold? }'];
+  }
+  const problems = Object.keys(then).filter((key) => !THEN_KEYS.includes(key)).map((key) => `unknown key "then.${key}"`);
+  if (!(then.whose in WHOSE)) {
+    problems.push(`"then.whose" is one of ${Object.keys(WHOSE).join(', ')}, got ${JSON.stringify(then.whose)}`);
+  }
+  for (const key of ['started', 'hold']) {
+    if (then[key] !== undefined && typeof then[key] !== 'boolean') {
+      problems.push(`"then.${key}" must be true or false`);
+    }
+  }
+  if (then.rank !== undefined && !(Number.isInteger(then.rank) && then.rank >= 0)) {
+    problems.push('"then.rank" must be a whole number, 0 or more');
+  }
+  for (const key of ['next', 'why']) {
+    if (then[key] !== undefined && typeof then[key] !== 'string') {
+      problems.push(`"then.${key}" must be text`);
+    } else if (then[key]) {
+      problems.push(...placeholderProblems(then[key]));
+    }
+  }
+  if (then.whose !== 'hidden' && !then.next) {
+    problems.push('"then.next" is required unless whose is hidden');
+  }
+  return problems;
+};
+
+const rowProblems = (row, groups) => {
+  if (!isPlainObject(row)) {
+    return [`a row is { when, then } or the text "${DEFAULT_MARKER}"`];
+  }
+  const problems = Object.keys(row).filter((key) => !['when', 'then'].includes(key)).map((key) => `unknown key "${key}"`);
+  if (!isPlainObject(row.when)) {
+    problems.push('"when" must be an object of { fact: condition }');
+  } else {
+    problems.push(...Object.entries(row.when).flatMap(([name, condition]) => conditionProblems(name, condition, groups)));
+  }
+  return [...problems, ...thenProblems(row.then)];
+};
+
+/** What is wrong with a workspace table, one line per problem, each naming its row (1-based); empty when the table is fine or absent. */
+export const tableProblems = (table, groups) => {
+  if (table === undefined) {
+    return [];
+  }
+  if (!Array.isArray(table)) {
+    return ['rules.table must be a list of rows'];
+  }
+  const problems = table.flatMap((row, index) => (row === DEFAULT_MARKER ? [] : rowProblems(row, groups).map((problem) => `rules.table row ${index + 1}: ${problem}`)));
+  if (table.filter((row) => row === DEFAULT_MARKER).length > 1) {
+    problems.push(`rules.table: "${DEFAULT_MARKER}" may appear once`);
+  }
+  return problems;
+};

package/lib/text.mjs

@@ -0,0 +1,46 @@
+/** Small text and time helpers shared by connectors, rules and the store. */
+
+export const DAY = 86400000;
+
+export const toIsoUtc = (value) => {
+  const time = new Date(value || '').getTime();
+  return Number.isFinite(time) ? new Date(time).toISOString().replace(/\.\d{3}Z$/, 'Z') : '';
+};
+
+export const nowIso = () => toIsoUtc(Date.now());
+
+export const daysAgoIso = (days) => toIsoUtc(Date.now() - days * DAY);
+
+export const oneline = (text, limit = 140) => {
+  const flat = String(text || '').replace(/\s+/g, ' ').trim();
+  return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`;
+};
+
+export const escapeRegex = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export const wordsRegex = (words, flags = 'i') => new RegExp(words.length ? words.map(escapeRegex).join('|') : '(?!)', flags);
+
+export const makeKeyFinder = (pattern) => {
+  const regex = new RegExp(pattern);
+  return (text) => {
+    const match = regex.exec(text || '');
+    return match ? match[0] : '';
+  };
+};
+
+export const newestFirst = (list) => list.slice().sort((a, b) => String(b.at).localeCompare(String(a.at)));
+
+export const unionCapped = (list, additions, cap = 5000) => [...new Set([...list, ...additions])].slice(-cap);
+
+export const mapLimit = async (items, limit, worker) => {
+  const results = new Array(items.length);
+  let next = 0;
+  const lane = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await worker(items[index], index);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, lane));
+  return results;
+};

package/lib/token-cache.mjs

@@ -0,0 +1,12 @@
+/** The one token cache of the connectors: a token read once and kept for ten minutes. */
+
+const TOKEN_TTL = 10 * 60 * 1000;
+
+/** The token `read` resolves to, kept in `cache.token` for ten minutes; an empty token is read again next time. */
+export const cachedToken = async (cache, read) => {
+  if (!cache.token || Date.now() - cache.tokenAt > TOKEN_TTL) {
+    cache.token = await read();
+    cache.tokenAt = Date.now();
+  }
+  return cache.token;
+};

package/lib/window.mjs

@@ -0,0 +1,33 @@
+/** The app window's remembered size in <data>/window.json, and the launcher behind the window's "Open as app" button. */
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { ApiError } from './errors.mjs';
+import { readJson, writeJson } from './store.mjs';
+
+const MODES = ['app', 'browser'];
+const inRange = (value) => Number.isInteger(value) && value >= 300 && value <= 10000;
+
+export const readSize = (dataDir) => {
+  const { width, height } = readJson(join(dataDir, 'window.json'), {});
+  return inRange(width) && inRange(height) ? { width, height } : {};
+};
+
+export const saveSize = (dataDir, { width, height }) => {
+  if (!inRange(width) || !inRange(height)) {
+    throw new ApiError('INVALID_ARGUMENT', { detail: 'width and height are whole pixels between 300 and 10000' });
+  }
+  writeJson(join(dataDir, 'window.json'), { width, height });
+  return { width, height };
+};
+
+export const checkMode = (mode) => {
+  if (!MODES.includes(mode)) {
+    throw new ApiError('INVALID_ARGUMENT', { detail: `mode is one of ${MODES.join(', ')}` });
+  }
+  return mode;
+};
+
+export const spawnOpener = (appDir) => ({ mode, port }) => {
+  const args = mode === 'browser' ? ['--browser'] : [];
+  spawn(join(appDir, 'open.sh'), args, { env: { ...process.env, WHOSE_TURN_PORT: String(port) }, detached: true, stdio: 'ignore' }).unref();
+};

package/lib/workspace.mjs

@@ -0,0 +1,294 @@
+/** One workspace: polls its connector entries, stores each result by source, merges them by kind, evaluates the rules once per version and notifies. */
+import { openStore } from './store.mjs';
+import { compileRules, turnRows, feedRows, myMoves, isHandled, withHandled, turnCounts, ticketEvents } from './rules.mjs';
+import { makeKeyFinder, nowIso, daysAgoIso, unionCapped, DAY } from './text.mjs';
+import { buildHandOff, snapshotOf, renderHandOff, frameHandOff } from './handoff.mjs';
+import { notify as desktopNotify } from './notify.mjs';
+import { DEFAULT_LIMITS, nextFails, assess, transition } from './health.mjs';
+import { paletteFrom, derivedSeed } from './palette.mjs';
+import { CONNECTORS, connectorSummaries } from '../connectors/index.mjs';
+import { RateLimited } from './http-client.mjs';
+const KINDS = ['tickets', 'comments', 'prs', 'activity', 'asks', 'runs'];
+
+const stamp = (result, sourceId) => {
+  const stamped = { ...result };
+  for (const kind of KINDS) {
+    stamped[kind] = (result[kind] || []).map((item) => ({ ...item, source: sourceId }));
+  }
+  return stamped;
+};
+
+export const createWorkspace = (definition, { dataDir, historyDays, http, secrets, limits = () => DEFAULT_LIMITS, notify = desktopNotify }) => {
+  const store = openStore(dataDir, definition.id);
+  const rules = compileRules(definition.rules);
+  const keyOf = makeKeyFinder(definition.key_pattern);
+  const seed = definition.theme?.seed || definition.derived_seed || derivedSeed(definition.id);
+  const theme = paletteFrom(seed, definition.theme?.accent);
+  const caches = {};
+  const listeners = new Set();
+  let digest = '';
+  let derived = null;
+  let freshAt = '';
+  const startedAt = nowIso();
+
+  const sources = () => Object.values(store.state.sources);
+  const merged = () => Object.fromEntries(KINDS.map((kind) => [kind, sources().flatMap((source) => source[kind] || [])]));
+  const me = () => Object.fromEntries(Object.entries(store.state.sources).map(([id, source]) => [id, source.me || '']));
+  const ticketUrl = (key) => {
+    const base = sources().map((source) => source.ticket_base).find(Boolean);
+    return base ? `${base}${key}` : '';
+  };
+
+  const rows = () => {
+    const day = nowIso().slice(0, 10);
+    if (!derived || derived.version !== store.state.version || derived.day !== day) {
+      const sources = merged();
+      const state = { ...sources, events: store.state.events };
+      const context = { me: me(), rules, historyDays, ticketUrl };
+      derived = { version: store.state.version, day, turn: turnRows(sources, context), feed: feedRows(state, context) };
+    }
+    return derived;
+  };
+
+  const emit = () => {
+    const message = { ws: definition.id, version: store.state.version, polled_at: store.state.polled_at, open_moves: myMoves(rows().turn, store.marks).length };
+    for (const listener of listeners) {
+      listener(message);
+    }
+  };
+
+  const notifyNewMoves = () => {
+    const moves = myMoves(rows().turn, store.marks);
+    const known = new Set(store.marks.notified);
+    const fresh = moves.filter((move) => !known.has(move.row_id));
+    if (!fresh.length) {
+      return;
+    }
+    if (store.marks.notified_seeded) {
+      const title = fresh.length === 1 ? `${definition.name}: your move on ${fresh[0].key}` : `${definition.name}: ${fresh.length} new items are your move`;
+      notify(title, fresh.length === 1 ? fresh[0].next : fresh.slice(0, 3).map((move) => `${move.key} — ${move.next}`).join('; '));
+    }
+    store.marks.notified = unionCapped(store.marks.notified, fresh.map((move) => move.row_id));
+    store.saveMarks();
+  };
+
+  const health = () => assess({ fails: store.state.fails, freshAt: freshAt || startedAt, now: Date.now(), limits: limits(), sourceCount: definition.connectors.length });
+
+  let shownStreaks = '';
+
+  const checkHealth = () => {
+    const { alerts } = health();
+    const { raised, recovered, alerted } = transition(store.marks.health_alerted, alerts);
+    const streaks = alerts.filter((alert) => alert.id.startsWith('failing:')).map((alert) => alert.text).join('\n');
+    if (!raised.length && !recovered.length) {
+      if (streaks !== shownStreaks) {
+        shownStreaks = streaks;
+        store.state.version += 1;
+        emit();
+      }
+      return;
+    }
+    shownStreaks = streaks;
+    if (raised.length) {
+      notify(`${definition.name}: monitor needs attention`, raised.map((alert) => alert.text).join('; '));
+    } else if (!alerted.length) {
+      notify(`${definition.name}: monitor recovered`, 'Data is flowing again');
+    }
+    store.marks.health_alerted = alerted;
+    store.saveMarks();
+    store.state.version += 1;
+    emit();
+  };
+
+  const pollSource = async (entry) => {
+    const connector = CONNECTORS[entry.type];
+    if (!connector) {
+      return { errors: { [entry.id]: `Unknown connector type "${entry.type}"` } };
+    }
+    caches[entry.id] = caches[entry.id] || store.loadCache(entry.id);
+    try {
+      const result = await connector.poll({ settings: entry, http, secrets, cache: caches[entry.id], sinceIso: daysAgoIso(historyDays), historyDays, keyOf });
+      const errors = Object.fromEntries(Object.entries(result.errors || {}).map(([part, message]) => [`${entry.id}.${part}`, message]));
+      return { data: stamp(result, entry.id), errors };
+    } catch (error) {
+      const rateLimited = error instanceof RateLimited;
+      return { errors: { [entry.id]: `${rateLimited ? 'rate limited' : error.name}: ${error.message}` }, rateLimited };
+    }
+  };
+
+  const saveCaches = () => {
+    const keysByEntry = Object.fromEntries(definition.connectors.map((entry) => [entry.id, CONNECTORS[entry.type]?.persistedCache || []]));
+    store.saveCaches(caches, keysByEntry);
+  };
+
+  const poll = async () => {
+    expireHandled();
+    const outcomes = await Promise.all(definition.connectors.map(pollSource));
+    const state = store.state;
+    const errors = {};
+    const ticketsBefore = merged().tickets;
+    definition.connectors.forEach((entry, index) => {
+      const outcome = outcomes[index];
+      Object.assign(errors, outcome.errors);
+      if (outcome.data) {
+        state.sources[entry.id] = outcome.data;
+      }
+    });
+    for (const id of Object.keys(state.sources)) {
+      if (!definition.connectors.some((entry) => entry.id === id)) {
+        delete state.sources[id];
+      }
+    }
+    if (ticketsBefore.length) {
+      state.events = [...ticketEvents(ticketsBefore, merged().tickets), ...state.events].slice(0, 500);
+    }
+    state.errors = errors;
+    state.polled_at = nowIso();
+    if (outcomes.some((outcome) => outcome.data)) {
+      freshAt = state.polled_at;
+    }
+    const fails = nextFails(state.fails, definition.connectors.map((entry, index) => ({ id: entry.id, failed: Object.keys(outcomes[index].errors).length > 0 })));
+    const failsChanged = JSON.stringify(fails) !== JSON.stringify(state.fails);
+    state.fails = fails;
+    const next = JSON.stringify([state.sources, state.errors]);
+    if (next !== digest) {
+      digest = next;
+      state.version += 1;
+      store.saveState();
+      if (outcomes.some((outcome) => outcome.data)) {
+        notifyNewMoves();
+        store.marks.notified_seeded = true;
+        store.saveMarks();
+      }
+    } else if (failsChanged) {
+      store.saveState();
+    }
+    if (outcomes.some((outcome) => outcome.data)) {
+      saveCaches();
+    }
+    checkHealth();
+    emit();
+    return { errors, rateLimited: outcomes.some((outcome) => outcome.rateLimited) };
+  };
+
+  const quickLinks = () => {
+    const derived = definition.connectors.flatMap((entry) => (CONNECTORS[entry.type]?.links ? CONNECTORS[entry.type].links(entry) : []));
+    const own = definition.links || [];
+    const seen = new Set();
+    return [...own, ...derived].filter((link) => !seen.has(link.url) && seen.add(link.url));
+  };
+
+  const expireHandled = () => {
+    const limit = Date.now() - 7 * DAY;
+    let changed = false;
+    for (const [rowId, at] of Object.entries(store.marks.handled)) {
+      if (new Date(at).getTime() < limit) {
+        delete store.marks.handled[rowId];
+        changed = true;
+      }
+    }
+    if (changed) {
+      store.saveMarks();
+    }
+  };
+
+  const identity = () => ({
+    id: definition.id, name: definition.name, key_pattern: definition.key_pattern, links: quickLinks(),
+    connectors: connectorSummaries(definition.connectors),
+    open_moves: myMoves(rows().turn, store.marks).length,
+  });
+
+  const describe = () => ({ ...identity(), theme, theme_seed: seed });
+
+  const todosWithLinks = () => store.todos.map((todo) => ({ ...todo, ticket_url: todo.key ? ticketUrl(todo.key) : '' }));
+
+  /** The part of the snapshot a marks write changes: the marks, the rows with their handled flags and the counts. */
+  const marked = () => ({ marks: store.marks, turn: withHandled(rows().turn, store.marks), counts: turnCounts(rows().turn, store.marks) });
+
+  const snapshot = (full) => ({
+    version: store.state.version, polled_at: store.state.polled_at, errors: store.state.errors, health: health(), me: me(),
+    ...marked(), feed: rows().feed, todos: todosWithLinks(), workspace: describe(),
+    ...(full ? { ...merged(), events: store.state.events } : {}),
+  });
+
+  const handOffSource = () => ({
+    data: merged(), turn: rows().turn, feed: rows().feed, workspace: describe(), rules: definition.rules,
+    moves: myMoves(rows().turn, store.marks), todos: todosWithLinks().filter((todo) => !todo.done), errors: store.state.errors,
+    handled: (row) => isHandled(row, store.marks),
+  });
+  const handOff = (kind, ref) => buildHandOff(kind, ref, handOffSource());
+  const handOffBody = (kind, ref) => {
+    const context = handOff(kind, ref);
+    return context ? renderHandOff(kind, context) : null;
+  };
+  const handOffText = (kind, ref) => {
+    const body = handOffBody(kind, ref);
+    return body && frameHandOff(definition.name, [body]);
+  };
+  const handOffSnapshot = (kind, ref) => snapshotOf(kind, ref, handOffSource());
+
+  const summary = () => {
+    const seen = new Set(store.marks.seen);
+    const unread = rows().feed.filter((item) => !seen.has(item.id) && new Date(item.at).getTime() > store.marks.base).length;
+    return { ...identity(), moves: myMoves(rows().turn, store.marks), new_events: unread, todos: todosWithLinks().filter((todo) => !todo.done), polled_at: store.state.polled_at, errors: store.state.errors, health: health() };
+  };
+
+  const updateMarks = (body) => {
+    const marks = store.marks;
+    if (body.seen) {
+      marks.seen = unionCapped(marks.seen, body.seen);
+    }
+    if ('base' in body) {
+      marks.base = body.base;
+    }
+    for (const [rowId, value] of Object.entries(body.handled || {})) {
+      if (value === null) {
+        delete marks.handled[rowId];
+      } else {
+        marks.handled[rowId] = value;
+      }
+    }
+    store.saveMarks();
+    emit();
+    return marked();
+  };
+
+  const addTodo = (body) => {
+    const text = String(body.text).trim().slice(0, 500);
+    store.todos.unshift({ id: `t${Date.now()}`, text, key: body.key || keyOf(text), created: nowIso(), by: String(body.by || 'you').slice(0, 20), done: null });
+  };
+
+  const changeTodo = (todo, body) => {
+    switch (body.action) {
+      case 'done':
+        todo.done = nowIso();
+        return true;
+      case 'undo':
+        todo.done = null;
+        return true;
+      case 'delete':
+        store.todos.splice(store.todos.indexOf(todo), 1);
+        return true;
+      case 'edit':
+        if (!String(body.text || '').trim()) {
+          return false;
+        }
+        todo.text = String(body.text).trim().slice(0, 500);
+        todo.key = keyOf(todo.text) || todo.key || '';
+        return true;
+      default:
+        return false;
+    }
+  };
+
+  const saveTodos = () => {
+    store.saveTodos();
+    store.state.version += 1;
+    emit();
+  };
+
+  return {
+    id: definition.id, name: definition.name, rulesTable: rules.table, store, poll, snapshot, summary, describe, checkHealth, handOff, handOffBody, handOffText, handOffSnapshot, updateMarks, addTodo, changeTodo, saveTodos,
+    subscribe: (listener) => { listeners.add(listener); return () => listeners.delete(listener); },
+  };
+};

package/open.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Opens the monitor as its own Chrome or Edge app window at the remembered size, or in a browser tab with --browser or when neither is installed.
+port=${WHOSE_TURN_PORT:-8765}
+base=http://127.0.0.1:$port
+width=1500
+height=950
+
+size=$(curl -fs --max-time 1 "$base/api/window" 2>/dev/null)
+[[ $size =~ \"width\":([0-9]+) ]] && width=${BASH_REMATCH[1]}
+[[ $size =~ \"height\":([0-9]+) ]] && height=${BASH_REMATCH[1]}
+
+tab() {
+  if [[ $(uname) == Darwin ]]; then open "$base/"; else xdg-open "$base/"; fi
+}
+
+if [[ $1 == --browser ]]; then
+  tab
+  exit
+fi
+
+url="$base/?mode=app"
+size_flag=--window-size=$width,$height
+
+if [[ $(uname) == Darwin ]]; then
+  if open -Ra "Google Chrome" 2>/dev/null; then
+    open -na "Google Chrome" --args --app="$url" "$size_flag"
+  else
+    tab
+  fi
+  exit
+fi
+
+for browser in google-chrome chromium chromium-browser microsoft-edge; do
+  if command -v "$browser" >/dev/null; then
+    "$browser" --app="$url" "$size_flag" >/dev/null 2>&1 &
+    disown
+    exit
+  fi
+done
+tab