issue-flow 0.7.6 → 0.8.0

package/dist/web-JVPK2PIF.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+import {
+  ensureSingleWebServer,
+  getWebLockFile,
+  readWebLock,
+  removeWebLock
+} from "./chunk-F52S6ZGF.js";
+import "./chunk-SLHZPB3C.js";
+import {
+  ISSUES_DIR_NAME,
+  PROJECTS_DIR_NAME,
+  getGlobalRoot,
+  loadWebConfig
+} from "./chunk-BASRRXAM.js";
+import {
+  printError,
+  printInfo,
+  printWarning,
+  sessionSnapshotSchema
+} from "./chunk-BH7DYADV.js";
+
+// src/web/session-directory.ts
+import { readdir, readFile, stat as statFile } from "fs/promises";
+import { join } from "path";
+var DEFAULT_POLL_INTERVAL_MS = 3e3;
+var DEFAULT_STALE_AFTER_MS = 3e4;
+async function listSubdirectories(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}
+async function discoverSessionFiles(root) {
+  const projectsDir = join(root, PROJECTS_DIR_NAME);
+  const projectIds = await listSubdirectories(projectsDir);
+  const perProject = await Promise.all(
+    projectIds.map(async (projectId) => {
+      const issuesDir = join(projectsDir, projectId, ISSUES_DIR_NAME);
+      const issueIds = await listSubdirectories(issuesDir);
+      return issueIds.map((issueId) => join(issuesDir, issueId, "session.json"));
+    })
+  );
+  return perProject.flat();
+}
+async function readSessionFile(filePath) {
+  let raw;
+  let mtimeMs;
+  try {
+    const [content, stat] = await Promise.all([readFile(filePath, "utf-8"), statFile(filePath)]);
+    raw = content;
+    mtimeMs = stat.mtimeMs;
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = sessionSnapshotSchema.safeParse(JSON.parse(raw));
+    if (!parsed.success || parsed.data.sessionId === null) return null;
+    return { snapshot: parsed.data, updatedAtMs: mtimeMs };
+  } catch {
+    return null;
+  }
+}
+function watchSessionDirectory(options = {}) {
+  const root = getGlobalRoot(options);
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+  const warn = options.onWarn;
+  let sessions = /* @__PURE__ */ new Map();
+  let warned = false;
+  async function scan() {
+    let files;
+    try {
+      files = await discoverSessionFiles(root);
+    } catch (err) {
+      if (!warned) {
+        warned = true;
+        warn?.(
+          `issue-flow: web monitor could not scan the session directory (will keep retrying silently): ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+      return;
+    }
+    const now = Date.now();
+    const next = /* @__PURE__ */ new Map();
+    for (const filePath of files) {
+      const result = await readSessionFile(filePath);
+      if (result === null) continue;
+      if (now - result.updatedAtMs > staleAfterMs) continue;
+      const sessionId = result.snapshot.sessionId;
+      next.set(sessionId, {
+        issueDir: join(filePath, ".."),
+        filePath,
+        snapshot: result.snapshot,
+        updatedAtMs: result.updatedAtMs
+      });
+    }
+    sessions = next;
+  }
+  void scan();
+  const timer = setInterval(() => void scan(), pollIntervalMs);
+  timer.unref();
+  return {
+    sessions: () => [...sessions.values()],
+    getSession: (sessionId) => sessions.get(sessionId),
+    refresh: scan,
+    close: () => clearInterval(timer)
+  };
+}
+
+// src/commands/web.ts
+var STOP_POLL_INTERVAL_MS = 100;
+var STOP_TIMEOUT_MS = 5e3;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runWebServe(options) {
+  const cli = {};
+  if (options.port !== void 0) cli.port = options.port;
+  if (options.host !== void 0) cli.host = options.host;
+  if (options.refresh !== void 0) cli.refreshSeconds = options.refresh;
+  const webConfig = await loadWebConfig({ cli });
+  const sessions = watchSessionDirectory();
+  const noop = () => {
+  };
+  const handle = await ensureSingleWebServer({
+    sessions,
+    port: webConfig.port,
+    host: webConfig.host,
+    refreshSeconds: webConfig.refreshSeconds,
+    unref: false,
+    info: noop,
+    warn: noop
+  });
+  if (handle === null) {
+    sessions.close();
+    return 1;
+  }
+  if (handle.server === void 0) {
+    sessions.close();
+    return 0;
+  }
+  const originalClose = handle.close;
+  handle.close = async () => {
+    await originalClose();
+    sessions.close();
+  };
+  return 0;
+}
+async function runWebStop() {
+  const lockFile = getWebLockFile();
+  const lock = await readWebLock(lockFile);
+  if (lock === null) {
+    printInfo("No web monitor is currently running.");
+    return 0;
+  }
+  try {
+    process.kill(lock.pid, "SIGTERM");
+  } catch (err) {
+    if (err.code === "ESRCH") {
+      printWarning(
+        "The web monitor lock referenced a process that is no longer running; removing it."
+      );
+      await removeWebLock(lockFile);
+      return 0;
+    }
+    printError(
+      `Failed to stop the web monitor: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return 1;
+  }
+  const deadline = Date.now() + STOP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (await readWebLock(lockFile) === null) {
+      printInfo(`Web monitor (pid ${lock.pid}) stopped.`);
+      return 0;
+    }
+    await sleep(STOP_POLL_INTERVAL_MS);
+  }
+  printWarning("Sent the stop signal, but the web monitor did not confirm shutdown in time.");
+  return 0;
+}
+export {
+  runWebServe,
+  runWebStop
+};
+//# sourceMappingURL=web-JVPK2PIF.js.map

package/dist/web-JVPK2PIF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/web/session-directory.ts","../src/commands/web.ts"],"sourcesContent":["import { readdir, readFile, stat as statFile } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport type { ValidatedSessionSnapshot } from '../schemas.js';\nimport { sessionSnapshotSchema } from '../schemas.js';\nimport {\n  type GetGlobalRootOptions,\n  getGlobalRoot,\n  ISSUES_DIR_NAME,\n  PROJECTS_DIR_NAME,\n} from '../storage/paths.js';\n\n/**\n * Multi-session discovery for the web monitoring server (US-003).\n *\n * The single-instance server (`web/lock.ts`) runs decoupled from any one\n * pipeline invocation, so it cannot hold a `SessionPublisher` in memory for\n * \"the\" run being monitored — there may be zero, one or several running at\n * once, each in its own process. Instead this module polls every\n * `~/.issue-flow/projects/<project>/issues/<n>/session.json` on disk (the\n * same file `FilePublisher` already writes) and keeps an in-memory map of the\n * ones that are both well-formed and recently updated.\n *\n * Polling rather than `fs.watch` is a deliberate choice, not a placeholder:\n * `fs.watch`'s `recursive` option is only reliable on macOS and Windows (Linux\n * needs a manual per-directory watch tree, and the whole thing still degrades\n * to polling on network filesystems), while a `~/.issue-flow` tree is small\n * and local — a cheap poll of it is simpler and behaves identically on every\n * platform, which is what the US-003 acceptance criteria ask to validate.\n */\n\n/** How often the directory tree is rescanned, unless overridden. */\nexport const DEFAULT_POLL_INTERVAL_MS = 3000;\n\n/**\n * A session stops being reported once its file has gone this long without an\n * update. `FilePublisher` throttles writes to ~1s and force-flushes on every\n * phase/session boundary, so a live run's file is never quiet for long; this\n * threshold only needs to be comfortably above one throttle window plus one\n * poll interval to avoid flapping a session in and out on timing alone.\n */\nexport const DEFAULT_STALE_AFTER_MS = 30_000;\n\nexport interface ActiveSession {\n  /** Directory the session.json was read from, one level up from the file. */\n  issueDir: string;\n  filePath: string;\n  snapshot: ValidatedSessionSnapshot;\n  /** mtime of the file at the last successful read, in epoch ms. */\n  updatedAtMs: number;\n}\n\nexport interface SessionDirectoryOptions extends GetGlobalRootOptions {\n  /** Poll interval, in ms. Default {@link DEFAULT_POLL_INTERVAL_MS}. */\n  pollIntervalMs?: number;\n  /** Staleness threshold, in ms. Default {@link DEFAULT_STALE_AFTER_MS}. */\n  staleAfterMs?: number;\n  /** Invoked (at most once) when a poll fails unexpectedly. Best-effort logging only. */\n  onWarn?: (message: string) => void;\n}\n\nexport interface SessionDirectoryHandle {\n  /** Snapshot of every session currently considered active. */\n  sessions(): ActiveSession[];\n  /** A single active session by id, or undefined. */\n  getSession(sessionId: string): ActiveSession | undefined;\n  /** Force an immediate rescan instead of waiting for the next tick. Never throws. */\n  refresh(): Promise<void>;\n  /** Stop polling. Idempotent. */\n  close(): void;\n}\n\nasync function listSubdirectories(dir: string): Promise<string[]> {\n  try {\n    const entries = await readdir(dir, { withFileTypes: true });\n    // Symlinks are skipped on purpose, same discipline as the storage\n    // migration walk: following one could pull session data from outside the\n    // global tree into the listing.\n    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);\n  } catch {\n    // Missing/unreadable projects (or issues) directory reads as \"none yet\" —\n    // this is routinely the case before the first --web run ever happens.\n    return [];\n  }\n}\n\n/** Every `session.json` path currently on disk, one per project/issue pair. */\nasync function discoverSessionFiles(root: string): Promise<string[]> {\n  const projectsDir = join(root, PROJECTS_DIR_NAME);\n  const projectIds = await listSubdirectories(projectsDir);\n\n  const perProject = await Promise.all(\n    projectIds.map(async (projectId) => {\n      const issuesDir = join(projectsDir, projectId, ISSUES_DIR_NAME);\n      const issueIds = await listSubdirectories(issuesDir);\n      return issueIds.map((issueId) => join(issuesDir, issueId, 'session.json'));\n    }),\n  );\n\n  return perProject.flat();\n}\n\ninterface ReadResult {\n  snapshot: ValidatedSessionSnapshot;\n  updatedAtMs: number;\n}\n\n/**\n * Read and validate one `session.json`. Anything short of a fully valid file\n * (missing, mid-write, corrupted, written by an incompatible future version)\n * reads as \"not currently a session\" — the directory scan must never fail\n * because one file is momentarily inconsistent (`FilePublisher` writes via a\n * temp file + rename, but a reader can still race a concurrent write).\n */\nasync function readSessionFile(filePath: string): Promise<ReadResult | null> {\n  let raw: string;\n  let mtimeMs: number;\n  try {\n    const [content, stat] = await Promise.all([readFile(filePath, 'utf-8'), statFile(filePath)]);\n    raw = content;\n    mtimeMs = stat.mtimeMs;\n  } catch {\n    return null;\n  }\n\n  try {\n    const parsed = sessionSnapshotSchema.safeParse(JSON.parse(raw));\n    if (!parsed.success || parsed.data.sessionId === null) return null;\n    return { snapshot: parsed.data, updatedAtMs: mtimeMs };\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Start polling the global storage tree for active sessions.\n *\n * Returns a handle immediately; the first scan happens synchronously in the\n * background and `sessions()` answers `[]` until it completes, same as \"no\n * sessions found yet\" — there is nothing to await here that would not also\n * delay the server's very first bind.\n */\nexport function watchSessionDirectory(\n  options: SessionDirectoryOptions = {},\n): SessionDirectoryHandle {\n  const root = getGlobalRoot(options);\n  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;\n  const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;\n  const warn = options.onWarn;\n\n  // Keyed by sessionId, not by file path: a session's identity is the id\n  // inside its content, and that is what /api/status?session=<id> looks up.\n  let sessions = new Map<string, ActiveSession>();\n  let warned = false;\n\n  async function scan(): Promise<void> {\n    let files: string[];\n    try {\n      files = await discoverSessionFiles(root);\n    } catch (err) {\n      if (!warned) {\n        warned = true;\n        warn?.(\n          `issue-flow: web monitor could not scan the session directory (will keep retrying silently): ${\n            err instanceof Error ? err.message : String(err)\n          }`,\n        );\n      }\n      return;\n    }\n\n    const now = Date.now();\n    const next = new Map<string, ActiveSession>();\n    for (const filePath of files) {\n      const result = await readSessionFile(filePath);\n      if (result === null) continue;\n      if (now - result.updatedAtMs > staleAfterMs) continue; // stopped updating: not active\n      const sessionId = result.snapshot.sessionId as string;\n      next.set(sessionId, {\n        issueDir: join(filePath, '..'),\n        filePath,\n        snapshot: result.snapshot,\n        updatedAtMs: result.updatedAtMs,\n      });\n    }\n    sessions = next;\n  }\n\n  // The first scan runs immediately (not just after the first interval tick)\n  // so a server started right after a session begins does not report \"no\n  // sessions\" for a whole poll interval.\n  void scan();\n  const timer = setInterval(() => void scan(), pollIntervalMs);\n  timer.unref();\n\n  return {\n    sessions: () => [...sessions.values()],\n    getSession: (sessionId: string) => sessions.get(sessionId),\n    refresh: scan,\n    close: () => clearInterval(timer),\n  };\n}\n","import { loadWebConfig } from '../config.js';\nimport type { WebConfig } from '../schemas.js';\nimport { printError, printInfo, printWarning } from '../ui/logger.js';\nimport { ensureSingleWebServer, getWebLockFile, readWebLock, removeWebLock } from '../web/lock.js';\nimport { watchSessionDirectory } from '../web/session-directory.js';\n\n/**\n * `issue-flow web serve` / `issue-flow web stop` (US-002).\n *\n * `serve` is the process `ensureWebMonitor()` (`web/lock.ts`) spawns detached\n * — it is not meant to be run interactively, though nothing stops a user from\n * doing so to watch every session on the machine without going through a\n * pipeline command first. It never exits on its own: the server stays bound\n * (see `unref: false` in `web/server.ts`) until `stop` sends it `SIGTERM`, at\n * which point `startWebServer`'s own signal handler closes it (removing the\n * lock) and re-raises the signal for the default termination behavior.\n */\n\nconst STOP_POLL_INTERVAL_MS = 100;\nconst STOP_TIMEOUT_MS = 5000;\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nexport interface RunWebServeOptions {\n  port?: number;\n  host?: string;\n  refresh?: number;\n}\n\n/**\n * Bind (or defer to) the single web monitor instance and keep the process\n * alive for as long as it stays bound. Logging is intentionally silent on the\n * happy path: this process is spawned with `stdio: 'ignore'`, so anything\n * printed here goes nowhere — the caller (`ensureWebMonitor`) is the one that\n * tells the user the server is up.\n */\nexport async function runWebServe(options: RunWebServeOptions): Promise<number> {\n  // Built conditionally, not `{ port: options.port, ... }`: loadWebConfig()\n  // spreads this object directly over the lower-precedence layers, and an\n  // explicit `undefined` value would overwrite an env/.issue-flow.json\n  // setting instead of falling through to it (only an *absent* key does).\n  const cli: Partial<WebConfig> = {};\n  if (options.port !== undefined) cli.port = options.port;\n  if (options.host !== undefined) cli.host = options.host;\n  if (options.refresh !== undefined) cli.refreshSeconds = options.refresh;\n  const webConfig = await loadWebConfig({ cli });\n\n  const sessions = watchSessionDirectory();\n\n  const noop = (): void => {};\n  const handle = await ensureSingleWebServer({\n    sessions,\n    port: webConfig.port,\n    host: webConfig.host,\n    refreshSeconds: webConfig.refreshSeconds,\n    unref: false,\n    info: noop,\n    warn: noop,\n  });\n\n  if (handle === null) {\n    sessions.close();\n    return 1;\n  }\n\n  if (handle.server === undefined) {\n    // Another instance already won the race (or was already running by the\n    // time this process got here): nothing to serve, so it exits right away\n    // instead of idling as a redundant detached process.\n    sessions.close();\n    return 0;\n  }\n\n  const originalClose = handle.close;\n  handle.close = async () => {\n    await originalClose();\n    sessions.close();\n  };\n\n  return 0;\n}\n\n/** Stop the single running web monitor instance, if any. */\nexport async function runWebStop(): Promise<number> {\n  const lockFile = getWebLockFile();\n  const lock = await readWebLock(lockFile);\n  if (lock === null) {\n    printInfo('No web monitor is currently running.');\n    return 0;\n  }\n\n  try {\n    process.kill(lock.pid, 'SIGTERM');\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === 'ESRCH') {\n      printWarning(\n        'The web monitor lock referenced a process that is no longer running; removing it.',\n      );\n      await removeWebLock(lockFile);\n      return 0;\n    }\n    printError(\n      `Failed to stop the web monitor: ${err instanceof Error ? err.message : String(err)}`,\n    );\n    return 1;\n  }\n\n  const deadline = Date.now() + STOP_TIMEOUT_MS;\n  while (Date.now() < deadline) {\n    if ((await readWebLock(lockFile)) === null) {\n      printInfo(`Web monitor (pid ${lock.pid}) stopped.`);\n      return 0;\n    }\n    await sleep(STOP_POLL_INTERVAL_MS);\n  }\n\n  printWarning('Sent the stop signal, but the web monitor did not confirm shutdown in time.');\n  return 0;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "issue-flow",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "Unified CLI for orchestrating the full issue-flow pipeline via Claude Code Headless",
   "type": "module",
   "bin": {

package/web/CLAUDE.md

@@ -20,6 +20,54 @@ zero é um valor legítimo.
 Texto dinâmico sempre via `textContent`/`el()`; nunca `innerHTML` com dados
 do snapshot.
 
+## Abas, Kanban e drawer
+
+O painel tem duas abas ("Execução" e "Kanban") e um drawer de detalhes por
+story. Três regras seguram esse conjunto:
+
+- **Acesso a story sempre por `getStoryById()` / `getStories()`.** Elas são a
+  camada de leitura: normalizam num lugar só o que pode faltar num
+  `session.json` antigo (`status` → `'backlog'`, `dependencies`/
+  `acceptanceCriteria` → `[]`, `description` → `''`) e são o ponto onde uma
+  futura camada de escrita entra. Nenhum consumidor varre `snapshot.stories`
+  por conta própria, ou a normalização se espalha.
+- **Estado de UI vive em `state`** (`activeTab`, `selectedStoryId`), junto de
+  `logFilter`, nunca em variável solta ou em referência a nó do DOM. O drawer
+  guarda o **id** da story, não o card: `render()` recria o Kanban a cada poll,
+  então uma referência guardada na abertura apontaria para um nó fora do
+  documento. Pelo mesmo motivo o foco volta ao card via
+  `[data-story-id="…"]` no momento de fechar.
+- **`renderKanban()` e `renderDrawer()` são chamadas incondicionalmente** dentro
+  de `render()`, não ao trocar de aba. Uma aba inativa não pode ficar defasada,
+  e é o `renderDrawer()` de cada poll que mantém o drawer aberto em dia (e o
+  fecha quando a story some do plano).
+
+Cada card do Kanban é um `<button>` — Enter/Espaço e foco saem de graça. Como
+`<button>` só aceita *phrasing content*, todo o conteúdo interno é `<span>` com
+`display: block`/`flex` no CSS; `<p>` ou `<div>` ali dentro é HTML inválido.
+
+Detalhes cosméticos que não são cosméticos: `.tab-panel[hidden]` e
+`.drawer[hidden]` precisam de `display: none` explícito, senão o `display:
+grid`/`flex` da regra base vence o atributo `hidden`. E o overlay/drawer ficam
+em `z-index` 20/21 para cobrir o `.banner` de desconexão, que é `sticky` com
+`z-index: 10`.
+
+## Escrita: o que ainda não existe
+
+A interface é somente leitura por contrato (`snapshot.readOnly === true`,
+`capabilities: []`), e o servidor não registra nenhuma rota de escrita — o
+comentário em `src/web/server.ts` reserva `POST /api/control/*` para isso. O
+Kanban e o drawer foram desenhados para que a escrita caiba depois sem
+redesenhar a interação: o drawer já é o lugar onde uma story é inspecionada por
+id, e `getStoryById()` já é o único ponto por onde ela é lida.
+
+Quando essa etapa chegar, o contrato esperado é: as rotas de escrita passam a
+ser anunciadas em `capabilities` (o client decide o que renderizar a partir
+disso, nunca da versão do servidor), `readOnly` passa a `false`, e cada
+mutação responde com o snapshot atualizado para que a UI não precise adivinhar
+o efeito nem esperar o próximo poll. Enquanto `capabilities` estiver vazio,
+nenhum controle de escrita deve aparecer na tela.
+
 ## Métricas (tokens e custo)
 
 `formatUsage()` espelha `formatTokens()` de `src/core/metrics.ts` — mesma

package/web/public/app.css

@@ -18,6 +18,7 @@
   --ok-bg: #dcfce7;
   --idle-bg: #e5e7eb;
   --shadow: 0 1px 2px rgb(0 0 0 / 0.06);
+  --overlay: rgb(0 0 0 / 0.45);
 }
 
 @media (prefers-color-scheme: dark) {
@@ -38,6 +39,7 @@
     --ok-bg: #14301f;
     --idle-bg: #262d38;
     --shadow: none;
+    --overlay: rgb(0 0 0 / 0.65);
   }
 }
 
@@ -110,6 +112,53 @@ a:hover {
   text-decoration: underline;
 }
 
+/* ---- Abas ---- */
+
+.tabs {
+  display: flex;
+  gap: 4px;
+  border-bottom: 1px solid var(--border);
+}
+
+.tab {
+  appearance: none;
+  background: none;
+  border: none;
+  border-bottom: 2px solid transparent;
+  margin-bottom: -1px;
+  padding: 8px 14px;
+  font: inherit;
+  font-weight: 600;
+  color: var(--muted);
+  cursor: pointer;
+  border-radius: 6px 6px 0 0;
+}
+
+.tab:hover {
+  color: var(--fg);
+  background: var(--card);
+}
+
+.tab.is-active {
+  color: var(--accent);
+  border-bottom-color: var(--accent);
+}
+
+/* O painel repete o grid de main: as seções dentro dele são os cards que antes
+   eram filhos diretos de main e dependem desse espaçamento. */
+.tab-panel {
+  display: grid;
+  gap: 16px;
+}
+
+.tab-panel[hidden] {
+  display: none;
+}
+
+.tab-panel > * {
+  min-width: 0;
+}
+
 /* ---- Cabeçalho ---- */
 
 .header {
@@ -534,6 +583,223 @@ progress {
   word-break: break-word;
 }
 
+/* ---- Kanban ---- */
+
+.kanban {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 12px;
+  align-items: start;
+}
+
+.kanban-column {
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 10px;
+  display: grid;
+  gap: 8px;
+  min-width: 0;
+}
+
+.kanban-column-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.kanban-column-title {
+  margin: 0;
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--muted);
+}
+
+.kanban-column-count {
+  flex: none;
+  background: var(--idle-bg);
+  color: var(--muted);
+  border-radius: 999px;
+  padding: 0 7px;
+  font-size: 0.74rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.kanban-card {
+  appearance: none;
+  display: grid;
+  gap: 6px;
+  justify-items: start;
+  width: 100%;
+  text-align: left;
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 10px;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  box-shadow: var(--shadow);
+}
+
+.kanban-card:hover {
+  border-color: var(--accent);
+}
+
+.kanban-card-head {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  color: var(--muted);
+  font-size: 0.8rem;
+}
+
+.kanban-card-title {
+  display: block;
+  font-weight: 600;
+  line-height: 1.35;
+  overflow-wrap: anywhere;
+}
+
+/* Trecho curto: limita a 3 linhas sem truncar a string, então o texto completo
+   continua no DOM para leitores de tela e para o drawer. */
+.kanban-card-desc {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.84rem;
+  line-height: 1.4;
+  overflow: hidden;
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
+  line-clamp: 3;
+  overflow-wrap: anywhere;
+}
+
+.kanban-empty {
+  font-size: 0.84rem;
+}
+
+@media (max-width: 719px) {
+  .kanban {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+/* ---- Drawer de detalhes ---- */
+
+/* Acima do .banner sticky (z-index 10), que senão atravessa o overlay. */
+.drawer-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 20;
+  background: var(--overlay);
+}
+
+.drawer {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: min(420px, 100vw);
+  z-index: 21;
+  display: flex;
+  flex-direction: column;
+  background: var(--card);
+  border-left: 1px solid var(--border);
+  padding: 16px;
+  gap: 12px;
+}
+
+.drawer[hidden],
+.drawer-overlay[hidden] {
+  display: none;
+}
+
+.drawer-head {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.drawer-head h2 {
+  margin: 0;
+  /* O título carrega o id + o título da story: fora do padrão caixa-alta das
+     demais seções, que são rótulos fixos e curtos. */
+  font-size: 0.95rem;
+  text-transform: none;
+  letter-spacing: normal;
+  color: var(--fg);
+  overflow-wrap: anywhere;
+}
+
+.drawer-close {
+  appearance: none;
+  flex: none;
+  background: none;
+  border: none;
+  padding: 2px 6px;
+  font: inherit;
+  color: var(--muted);
+  cursor: pointer;
+  border-radius: 6px;
+}
+
+.drawer-close:hover {
+  color: var(--fg);
+  background: var(--idle-bg);
+}
+
+/* A rolagem vive aqui, não na página: o drawer é fixo e ocupa a altura toda. */
+.drawer-body {
+  overflow-y: auto;
+  display: grid;
+  gap: 14px;
+  align-content: start;
+  justify-items: start;
+}
+
+.drawer-timing {
+  margin: 0;
+  font-size: 0.84rem;
+}
+
+.drawer-section {
+  width: 100%;
+  display: grid;
+  gap: 6px;
+}
+
+.drawer-section-title {
+  margin: 0;
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--muted);
+}
+
+.drawer-text {
+  margin: 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.drawer-list {
+  margin: 0;
+  padding-left: 18px;
+  display: grid;
+  gap: 4px;
+}
+
+.drawer-list li {
+  overflow-wrap: anywhere;
+}
+
 /* ---- Diversos ---- */
 
 .empty {