@develemit/web-hooks 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.0 - 2026-11-06
+
+- **New optional peer dependency:** `@tanstack/react-virtual` (`^3.13.0`), needed only by apps that import `@develemit/web-hooks/virtual-list`. Every other entry, including the root, works without it.
+- `virtual-list`: `useVirtualLog({ lines, scrollRef, query, estimateSize, overscan, resetKey, filename })` combines `useVirtualList` with `useFollowTail`, a deferred `filterLines` search, incremental `findFailures` with `jumpToFailure` / `nextFailure` / `previousFailure` by index, and `copyText` / `download` over the whole log. Also exports `logToText` and `downloadText`. Budgets measured in WebKit on a 20,765-line, 1.4 MB log: first render about 20 ms with 40 rows in the page, filter keystrokes under 50 ms, about 3 ms of render per batch of appended lines.
+- `virtual-list`: new subpath with `useVirtualList({ count, estimateSize, scrollRef | windowScroll, scrollMargin, overscan = 10, measure = true, getItemKey, initialCount = 30 })` returning `{ items, totalSize, measureRef, scrollToIndex, scrollToOffset, virtualizer }`, plus the pure `measuredOrEstimate`, `shouldRealign`, `targetOffset` and `initialVisibleCount`. Rows are measured by default (a 0 reading falls back to the estimate), it can scroll an element or the window, `scrollToIndex` re-aligns for up to 3 frames after measuring so it lands on unrendered rows, and the server render includes the first rows. `@tanstack/react-virtual` (`^3.13.0`) is an **optional** peer dependency used only by this subpath; the root index does not re-export it.
+
+## 0.4.0 - 2026-11-06
+
+- `terminal-output`: `useFollowTail` detaches on a user scroll up even when output streams every frame. It now detects intent (wheel up, a finger dragging down, a press on the scrollbar gutter, or a scroll event above where the hook last scrolled to) instead of ignoring scroll events in the frame after its own scroll. New pure `isUserScrollUp`.
+- `terminal-output`: `useFollowTail({ scrollRef, itemCount, scrollToEnd, resetKey, threshold })` returning `{ atBottom, unread, jumpToBottom }`, plus the pure `shouldStick`, `isNearEnd`, `distanceFromEnd` and `unreadDelta`. Follows new output while at the bottom (24px threshold, so iOS rubber-band counts), detaches on a user scroll up without being fooled by its own scrolls, counts unread items, and works with a virtualizer through `scrollToEnd`.
+- `terminal-output`: log helpers on plain lines. `filterLines` and `splitByMatch` (case-insensitive plain-text search and highlight), `findFailures` / `firstFailureIndex` (per-tool patterns for Vitest, Nx, tsc, pnpm, npm and Docker, returning `{ index, tool, kind }`), `isNoise` and `tailMeaningful`. `FAILURE_PATTERNS` and `NOISE_PATTERNS` are exported so apps can extend them.
+- `terminal-output`: `createAnsiStream().finish(partial?)` ends a stream without adding a trailing newline (pushes after it are ignored until `reset()`). `push()` now re-renders only rows that were written to, instead of cloning and rendering the whole tail on every call.
+- `terminal-output`: `createLineBuffer` (stream chunks or bytes to complete lines; holds the unfinished line and any half-written escape code, joins `\r\n` and UTF-8 split across chunks, caps memory with a `dropped` count, tracks the server's resume cursor) and `createAnsiStream` (renders those lines with a small screen tail, so streamed cursor-up redraws give the same rows as `parseAnsi` of the whole log).
+- `terminal-output`: `stripAnsi`, `parseAnsi` and `createAnsiParser`. Styled segments with `\r`, cursor-up and erase-line redraws collapsed, OSC 8 links filtered to `http`/`https`/`file`, no HTML anywhere.
+- `terminal-output`: new subpath. Holds the real terminal captures (`src/terminal-output/fixtures/`, test-only, not published) that the ANSI strip, parse, line-buffer and log helpers will be tested against.
+
 ## 0.3.1 - 2026-11-06
 
 - `service-worker`: `useServiceWorker({ onError })` and `registerServiceWorker({ onError })`. Called with the rejection when `register()` fails (not after unmount or dispose). The latest callback is used; a throwing callback is swallowed. Registration failure still never throws into React.

package/README.md

@@ -24,6 +24,8 @@ that every app ends up hand-copying from the last one.
 | `@develemit/web-hooks/share` | Native share sheet with a clipboard fallback that works over plain http |
 | `@develemit/web-hooks/keyboard-inset` | On-screen keyboard height, without the phantom gap in standalone iPhone PWAs |
 | `@develemit/web-hooks/push` | Web push subscription, with iOS install detection and silent re-subscribe |
+| `@develemit/web-hooks/terminal-output` | Strip and parse ANSI, buffer streamed lines, search logs and find failures, and follow the tail of a scrolling log |
+| `@develemit/web-hooks/virtual-list` | Virtualize long lists on `@tanstack/react-virtual` with phone-safe defaults (optional peer) |
 
 Behavior only. No styling and no components: each app keeps its own look.
 
@@ -405,3 +407,116 @@ the dead subscription is unsubscribed and one fresh one is made and sent. The
 package never makes HTTP requests: `onSubscribe(subscription:
 PushSubscriptionJSON)` and `onUnsubscribe(endpoint)` are yours. The pure
 `urlBase64ToUint8Array`, `getPushSupport` and `shouldResubscribe` are exported.
+
+### terminal-output
+
+`@develemit/web-hooks/terminal-output` turns raw terminal text into data. Log helpers (search, failures, noise) work on plain lines. Tests run against real captures in `src/terminal-output/fixtures/` (not published).
+
+- `stripAnsi(text)` removes CSI (including `?` private modes), OSC (BEL or `ESC \` terminated) and two-byte escapes. It leaves `\r` and `\n` alone.
+- `parseAnsi(text, { linkSchemes? })` returns `AnsiLine[]`, each line an array of `{ text, fg?, bg?, bold?, dim?, italic?, underline?, inverse?, href? }`. Colours are `{ kind: 'ansi', index }` (0-15, or 0-255 for 256-colour) or `{ kind: 'rgb', r, g, b }`; your app maps them to its palette. OSC 8 links become `href`, and only `http`, `https` and `file` are kept.
+- It emulates what progress output needs: `\r`, cursor up/down (`A`/`B`), column set (`G`), erase-line (`K`) and erase-below (`0J`), so redraws collapse to their final state. Every other escape sequence is dropped; use xterm.js for full emulation.
+- `createAnsiParser(options)` returns `{ parse(chunk), reset() }`. Colour and link state carry across calls; the screen does not, so give it whole lines.
+
+- `createLineBuffer({ maxLines })` turns chunks (`string` or `Uint8Array`) into complete raw lines. `push(chunk, { cursor? })` returns `{ lines, partial, dropped }`: the new lines (escape codes intact), the unfinished line (without a half-written escape code, which waits for the next chunk), and how many old lines this push dropped. `\r\n` and multi-byte characters split across chunks are joined; a lone `\r` stays in the line for the parser. `flush()` ends the stream, `buffer.lines` holds what is kept, `buffer.dropped` the total dropped.
+- **Resuming is the server's job.** Pass its cursor to `push`; after a dropped connection ask the server for `since: buffer.cursor` and push again. The buffer never compares text, so a log that repeats a line keeps both.
+- `createAnsiStream({ tailLines = 50 })` renders those lines. `push(lines, partial)` returns `{ replaced?: { from, lines } }`: truncate your rendered rows to `from`, then append `lines`. Its screen tail lets a redraw reach rows already shown (pnpm's cursor-up progress, npm's spinner), so the result equals `parseAnsi(wholeLog)`. The tail grows to the largest cursor-up it sees; rows further back are frozen. `from` counts from the stream's first row, not from your capped list. When the stream ends, call `stream.finish()`: it renders the unfinished line you last pushed (or the `partial` you pass) without adding a newline, so the rows equal `parseAnsi(wholeLog)`. Don't push `lineBuffer.flush()` output into the stream. Pushes after `finish()` are ignored until `reset()`.
+
+```ts
+const buffer = createLineBuffer({ maxLines: 10_000 });
+const stream = createAnsiStream();
+const rows: AnsiLine[] = [];
+
+function onChunk(chunk: string | Uint8Array, cursor: number) {
+  const { lines, partial } = buffer.push(chunk, { cursor });
+  const { replaced } = stream.push(lines, partial);
+  if (replaced) rows.splice(replaced.from, rows.length, ...replaced.lines);
+}
+```
+
+**Log helpers** take plain lines (run `stripAnsi` or join `parseAnsi` segments first):
+
+- `filterLines(lines, query)` returns the matching indexes (every index for a blank query). `splitByMatch(line, query)` returns `{ text, match }[]` for highlighting. Both are case-insensitive plain text, never regex.
+- `findFailures(lines, patterns?)` returns `{ index, tool, kind }[]` (tools: `vitest`, `nx`, `tsc`, `pnpm`, `npm`, `docker`, `generic`); `firstFailureIndex` returns the first index or `-1`. Nx matches both `targets failed, including` and the older `Failed tasks`. Stack-frame lines never count. Extend with `[...FAILURE_PATTERNS, { tool, kind, pattern }]`.
+- `isNoise(line)` and `tailMeaningful(lines, n)` hide Docker pull and compose chatter and Nx cache lines; the tail is the last `n` non-blank lines that matter. Extend `NOISE_PATTERNS` the same way.
+
+**Following live output.** `useFollowTail({ scrollRef, itemCount, scrollToEnd?, resetKey?, threshold = 24 })` returns `{ atBottom, unread, jumpToBottom }`. While the user is within `threshold` px of the end (rubber-band overshoot counts), new items scroll to the end in a layout effect. A user scroll up detaches; items added after that are counted in `unread`; scrolling back down or calling `jumpToBottom()` re-sticks and clears it. The hook's own scrolls never detach. Pass `scrollToEnd` to use a virtualizer (`() => virtualizer.scrollToIndex(count - 1, { align: 'end' })`), and `resetKey` to snap back when the content changes (a project switch). The pure `shouldStick`, `isNearEnd`, `distanceFromEnd` and `unreadDelta` are exported.
+
+Segments are plain text, so there is no HTML to escape:
+
+```tsx
+import { parseAnsi } from '@develemit/web-hooks/terminal-output';
+
+const COLORS = ['text-black', 'text-red', 'text-green', 'text-yellow', 'text-blue', 'text-magenta', 'text-cyan', 'text-white'];
+
+{parseAnsi(log).map((line, i) => (
+  <div key={i}>
+    {line.map((seg, j) => (
+      <span key={j} className={`${seg.bold ? 'font-bold' : ''} ${seg.fg?.kind === 'ansi' ? COLORS[seg.fg.index % 8] : ''}`}>
+        {seg.text}
+      </span>
+    ))}
+  </div>
+))}
+```
+
+### virtual-list
+
+`@develemit/web-hooks/virtual-list` wraps `@tanstack/react-virtual` (v3.13+). Install it yourself (`pnpm add @tanstack/react-virtual`); it is an **optional** peer, needed only by apps that import this subpath. The root `@develemit/web-hooks` import does not re-export it, so root imports never need the peer.
+
+`useVirtualList({ count, estimateSize, scrollRef? | windowScroll: true, scrollMargin = 0, overscan = 10, measure = true, getItemKey?, initialCount = 30 })` returns `{ items, totalSize, measureRef, scrollToIndex(i, { align }), scrollToOffset, virtualizer }`; `items` are `{ index, key, start, size }`, and `virtualizer` is the raw escape hatch.
+
+- Rows are measured by default; a row that reads 0 before layout keeps its estimate, so the list never collapses. Pass `measure: false` if your own maths relies on flat estimates.
+- `windowScroll: true` scrolls with the page (use `scrollMargin` for the list's distance from the page top; item `start` is relative to the list).
+- `scrollToIndex` to a row that isn't rendered yet scrolls to the estimate, then re-aligns after measuring, for up to 3 frames.
+- The server render includes the first `initialCount` rows.
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const { items, totalSize, measureRef } = useVirtualList({ count: lines.length, estimateSize: () => 20, scrollRef: ref });
+
+<div ref={ref} className="h-96 overflow-auto">
+  <div style={{ height: totalSize, position: 'relative' }}>
+    {items.map((it) => (
+      <div key={it.key} data-index={it.index} ref={measureRef}
+           style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: `translateY(${it.start}px)` }}>
+        {lines[it.index]}
+      </div>
+    ))}
+  </div>
+</div>
+```
+
+Each row needs `data-index={it.index}` and `ref={measureRef}`.
+
+#### useVirtualLog
+
+`useVirtualLog({ lines, scrollRef, query = '', estimateSize = () => 18, overscan = 12, resetKey?, filename = 'log.txt' })` joins `useVirtualList` with the `terminal-output` helpers for a live, searchable log. Pass the lines as strings (strip or keep escape codes; search and failure scans run on what you pass, so give it plain text if you want to search plain text).
+
+It returns `rows` (`{ index, lineIndex, key, start, size }`, where `lineIndex` is the row's place in `lines`), `totalSize`, `measureRef`, `isFiltering`, `shownCount`, `atBottom`, `unread`, `jumpToBottom`, `failures`, `failurePosition`, `jumpToFailure(n)`, `nextFailure()`, `previousFailure()`, `text()`, `copyText()` and `download(filename?)`.
+
+- Search goes through `useDeferredValue`, so typing stays instant on 20k lines. Rows are the matches; map them back with `lines[row.lineIndex]` for highlighting with `splitByMatch`.
+- It follows the tail and stops when the user scrolls up. While a filter is on, following pauses and `unread` counts matches that arrived since the filter began.
+- `failures` is scanned once per content change, and only on appended rows. `jumpToFailure(n)` scrolls by index (so it works for rows that aren't rendered) and returns `false` if that failure is hidden by the filter.
+- `copyText()` and `download()` use the whole log with escape codes stripped, however few rows are in the page. `logToText(lines, { stripAnsi })` and `downloadText(filename, text)` are exported on their own.
+- `lines` is an array, not a stream: keep your own state (for example `createLineBuffer` + `createAnsiStream`) and pass its rows.
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const [query, setQuery] = useState('');
+const log = useVirtualLog({ lines, scrollRef: ref, query });
+
+<div ref={ref} className="h-96 overflow-auto">
+  <div style={{ height: log.totalSize, position: 'relative' }}>
+    {log.rows.map((row) => (
+      <div key={row.key} data-index={row.index} ref={log.measureRef}
+           style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: `translateY(${row.start}px)` }}>
+        {log.isFiltering
+          ? splitByMatch(lines[row.lineIndex] ?? '', query).map((s, j) => (s.match ? <mark key={j}>{s.text}</mark> : <span key={j}>{s.text}</span>))
+          : lines[row.lineIndex]}
+      </div>
+    ))}
+  </div>
+</div>
+{!log.atBottom && <button onClick={log.jumpToBottom}>{log.unread} new</button>}
+<button onClick={log.nextFailure}>Next failure</button>
+```

package/dist/chunk-IVLRQ23V.js

@@ -0,0 +1,483 @@
+"use client";
+
+// src/terminal-output/ansi-sgr.ts
+var FLAG_ON = {
+  1: "bold",
+  2: "dim",
+  3: "italic",
+  4: "underline",
+  7: "inverse"
+};
+var FLAG_OFF = {
+  22: ["bold", "dim"],
+  23: ["italic"],
+  24: ["underline"],
+  27: ["inverse"]
+};
+function byte(n) {
+  return Math.max(0, Math.min(255, n));
+}
+function extendedColor(args) {
+  if (args[0] === 5 && args.length >= 2) return { kind: "ansi", index: byte(args[1] ?? 0) };
+  if (args[0] === 2 && args.length >= 4) {
+    const [r = 0, g = 0, b = 0] = args.slice(-3);
+    return { kind: "rgb", r: byte(r), g: byte(g), b: byte(b) };
+  }
+  return null;
+}
+function setKey(style, key, value) {
+  if (value === void 0 || value === false) delete style[key];
+  else style[key] = value;
+}
+function applySgr(style, params) {
+  const next = { ...style };
+  const tokens = params === "" ? ["0"] : params.split(";");
+  for (let i = 0; i < tokens.length; i++) {
+    const parts = (tokens[i] ?? "").split(":").map((p) => p === "" ? 0 : Number(p));
+    const code = parts[0] ?? 0;
+    if (Number.isNaN(code)) continue;
+    if (code === 38 || code === 48) {
+      const key = code === 38 ? "fg" : "bg";
+      let args = parts.slice(1);
+      if (parts.length === 1) {
+        args = tokens.slice(i + 1, i + 5).map(Number);
+        const used = args[0] === 5 ? 2 : args[0] === 2 ? 4 : 0;
+        i += used;
+        args = args.slice(0, used);
+      }
+      const color = extendedColor(args);
+      if (color) setKey(next, key, color);
+      continue;
+    }
+    if (code === 0) {
+      for (const k of Object.keys(next)) delete next[k];
+    } else if (FLAG_ON[code]) setKey(next, FLAG_ON[code], true);
+    else if (FLAG_OFF[code]) (FLAG_OFF[code] ?? []).forEach((k) => setKey(next, k, void 0));
+    else if (code >= 30 && code <= 37) setKey(next, "fg", { kind: "ansi", index: code - 30 });
+    else if (code === 39) setKey(next, "fg", void 0);
+    else if (code >= 40 && code <= 47) setKey(next, "bg", { kind: "ansi", index: code - 40 });
+    else if (code === 49) setKey(next, "bg", void 0);
+    else if (code >= 90 && code <= 97) setKey(next, "fg", { kind: "ansi", index: code - 90 + 8 });
+    else if (code >= 100 && code <= 107) setKey(next, "bg", { kind: "ansi", index: code - 100 + 8 });
+  }
+  return next;
+}
+function colorEquals(a, b) {
+  if (a === b) return true;
+  if (!a || !b || a.kind !== b.kind) return false;
+  if (a.kind === "ansi") return a.index === b.index;
+  const o = b;
+  return a.r === o.r && a.g === o.g && a.b === o.b;
+}
+function styleEquals(a, b) {
+  return a === b || colorEquals(a.fg, b.fg) && colorEquals(a.bg, b.bg) && !!a.bold === !!b.bold && !!a.dim === !!b.dim && !!a.italic === !!b.italic && !!a.underline === !!b.underline && !!a.inverse === !!b.inverse;
+}
+
+// src/terminal-output/ansi-screen.ts
+var BLANK = {};
+var newRow = () => ({ cells: [], shared: false });
+var Screen = class _Screen {
+  rows = [newRow()];
+  row = 0;
+  col = 0;
+  line() {
+    const row = this.rows[this.row] ??= newRow();
+    if (row.shared) {
+      row.cells = row.cells.slice();
+      row.shared = false;
+    }
+    row.segments = void 0;
+    return row.cells;
+  }
+  write(ch, style, href) {
+    const line = this.line();
+    while (line.length < this.col) line.push({ ch: " ", style: BLANK });
+    line[this.col] = { ch, style, href };
+    this.col++;
+  }
+  newline() {
+    this.moveRow(this.row + 1);
+    this.col = 0;
+  }
+  carriageReturn() {
+    this.col = 0;
+  }
+  backspace() {
+    this.col = Math.max(0, this.col - 1);
+  }
+  moveRow(row) {
+    this.row = Math.max(0, row);
+    while (this.rows.length <= this.row) this.rows.push(newRow());
+  }
+  moveRowBy(delta) {
+    this.moveRow(this.row + delta);
+  }
+  setColumn(col) {
+    this.col = Math.max(0, col);
+  }
+  /** `ESC[nK`: 0 cursor to end, 1 start to cursor, 2 whole line. */
+  eraseLine(mode) {
+    const line = this.line();
+    if (mode === 2) this.rows[this.row] = newRow();
+    else if (mode === 1) {
+      for (let i = 0; i < Math.min(this.col + 1, line.length); i++) line[i] = { ch: " ", style: BLANK };
+    } else if (this.col < line.length) line.length = this.col;
+  }
+  /** `ESC[0J`: erase from the cursor to the end of the screen. */
+  eraseBelow() {
+    this.eraseLine(0);
+    this.rows.length = this.row + 1;
+  }
+  lines() {
+    return this.rows.map((row) => row.segments ??= toSegments(row.cells));
+  }
+  get rowCount() {
+    return this.rows.length;
+  }
+  get cursorRow() {
+    return this.row;
+  }
+  /** Forgets the first `count` rows (never the cursor's row) and returns how many went. */
+  dropTop(count) {
+    const n = Math.max(0, Math.min(count, this.row));
+    this.rows.splice(0, n);
+    this.row -= n;
+    return n;
+  }
+  /** An independent copy, so a partial line can be rendered without committing it. */
+  clone() {
+    const copy = new _Screen();
+    for (const row of this.rows) row.shared = true;
+    copy.rows = this.rows.map((r) => ({ ...r }));
+    copy.row = this.row;
+    copy.col = this.col;
+    return copy;
+  }
+};
+function toSegments(cells) {
+  const out = [];
+  let current = null;
+  let currentStyle = null;
+  for (const cell of cells) {
+    if (current && currentStyle && current.href === cell.href && styleEquals(currentStyle, cell.style)) {
+      current.text += cell.ch;
+      continue;
+    }
+    current = { text: cell.ch, ...cell.style };
+    if (cell.href) current.href = cell.href;
+    currentStyle = cell.style;
+    out.push(current);
+  }
+  return out;
+}
+
+// src/terminal-output/ansi.ts
+var ESCAPE_SOURCE = "\\x1b(?:\\[([0-?]*)([ -/]*)([@-~])|\\]([^\\x07\\x1b]*)(?:\\x07|\\x1b\\\\)|[ -/]+[0-~]|[0-~])";
+var DEFAULT_SCHEMES = ["http", "https", "file"];
+function stripAnsi(text) {
+  return text.replace(new RegExp(ESCAPE_SOURCE, "g"), "");
+}
+function allowedHref(uri, schemes) {
+  const match = /^([a-z][a-z0-9+.-]*):/i.exec(uri);
+  return match && schemes.includes((match[1] ?? "").toLowerCase()) ? uri : void 0;
+}
+function writeText(screen, state, text) {
+  for (const ch of text) {
+    if (ch === "\n") screen.newline();
+    else if (ch === "\r") screen.carriageReturn();
+    else if (ch === "\b") screen.backspace();
+    else if (ch === "	" || ch >= " " && ch !== "\x7F") screen.write(ch, state.style, state.href);
+  }
+}
+function applyCsi(screen, state, params, inter, final) {
+  if (inter !== "") return;
+  if (final === "m") {
+    if (/^[0-9;:]*$/.test(params)) state.style = applySgr(state.style, params);
+    return;
+  }
+  if (!/^[0-9;]*$/.test(params)) return;
+  const n = params === "" ? NaN : Number(params.split(";")[0]);
+  const count = Number.isNaN(n) || n === 0 ? 1 : n;
+  const mode = Number.isNaN(n) ? 0 : n;
+  if (final === "A") screen.moveRowBy(-count);
+  else if (final === "B") screen.moveRowBy(count);
+  else if (final === "G") screen.setColumn(count - 1);
+  else if (final === "K") screen.eraseLine(mode);
+  else if (final === "J" && mode === 0) screen.eraseBelow();
+}
+function applyOsc(state, payload, schemes) {
+  if (!payload.startsWith("8;")) return;
+  const split = payload.indexOf(";", 2);
+  state.href = split === -1 ? void 0 : allowedHref(payload.slice(split + 1), schemes);
+}
+function feedAnsi(screen, state, text, options) {
+  const schemes = options.linkSchemes ?? DEFAULT_SCHEMES;
+  const re = new RegExp(ESCAPE_SOURCE, "g");
+  let last = 0;
+  for (let m = re.exec(text); m; m = re.exec(text)) {
+    writeText(screen, state, text.slice(last, m.index));
+    last = m.index + m[0].length;
+    if (m[3] !== void 0) applyCsi(screen, state, m[1] ?? "", m[2] ?? "", m[3]);
+    else if (m[4] !== void 0) applyOsc(state, m[4], schemes);
+  }
+  writeText(screen, state, text.slice(last));
+}
+function run(text, state, options) {
+  const screen = new Screen();
+  feedAnsi(screen, state, text, options);
+  return screen.lines();
+}
+function parseAnsi(text, options = {}) {
+  return run(text, { style: {} }, options);
+}
+function createAnsiParser(options = {}) {
+  const state = { style: {} };
+  return {
+    parse: (chunk) => run(chunk, state, options),
+    reset: () => {
+      state.style = {};
+      state.href = void 0;
+    }
+  };
+}
+
+// src/terminal-output/log-helpers.ts
+var escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function queryMatcher(query) {
+  const q = query.trim();
+  return q ? new RegExp(escapeRegExp(q), "giu") : null;
+}
+function filterLines(lines, query) {
+  const matcher = queryMatcher(query);
+  const indexes = [];
+  lines.forEach((line, i) => {
+    if (!matcher) indexes.push(i);
+    else {
+      matcher.lastIndex = 0;
+      if (matcher.test(line)) indexes.push(i);
+    }
+  });
+  return indexes;
+}
+function splitByMatch(line, query) {
+  const matcher = queryMatcher(query);
+  if (!matcher) return [{ text: line, match: false }];
+  const segments = [];
+  let last = 0;
+  for (const m of line.matchAll(matcher)) {
+    const start = m.index ?? 0;
+    if (start > last) segments.push({ text: line.slice(last, start), match: false });
+    segments.push({ text: m[0], match: true });
+    last = start + m[0].length;
+  }
+  if (last < line.length || segments.length === 0) {
+    segments.push({ text: line.slice(last), match: false });
+  }
+  return segments;
+}
+var FAILURE_PATTERNS = [
+  { tool: "tsc", kind: "error", pattern: /\berror TS\d+/ },
+  { tool: "pnpm", kind: "error", pattern: /\bERR_PNPM_[A-Z_]+/ },
+  { tool: "npm", kind: "error", pattern: /\bnpm (?:ERR!|error\b)/ },
+  { tool: "nx", kind: "failed tasks", pattern: /targets failed, including|Failed tasks/ },
+  { tool: "nx", kind: "task failed", pattern: /^\s*✖\s+nx run / },
+  { tool: "nx", kind: "failed", pattern: /^\s*✖\s+\d+\/\d+ failed/ },
+  { tool: "vitest", kind: "fail", pattern: /^\s*FAIL\s/ },
+  { tool: "vitest", kind: "test", pattern: /^\s*[×✗]\s/ },
+  { tool: "docker", kind: "error", pattern: /^\s*(?:Error response from daemon|ERROR: failed to solve|failed to solve|pull access denied)/ },
+  { tool: "docker", kind: "exit", pattern: /^\s*Container \S+\s+(?:Error|exited with code [1-9]\d*)/ },
+  { tool: "generic", kind: "error", pattern: /\b\w*Error\b(?: \[\w+\])?:/ }
+];
+var STACK_FRAME = /^\s*at\s/;
+function findFailures(lines, patterns = FAILURE_PATTERNS) {
+  const failures = [];
+  lines.forEach((line, index) => {
+    if (STACK_FRAME.test(line)) return;
+    const hit = patterns.find((p) => p.pattern.test(line));
+    if (hit) failures.push({ index, tool: hit.tool, kind: hit.kind });
+  });
+  return failures;
+}
+function firstFailureIndex(lines, patterns = FAILURE_PATTERNS) {
+  return findFailures(lines, patterns)[0]?.index ?? -1;
+}
+var NOISE_PATTERNS = [
+  /^\s*[0-9a-f]{12}: (?:Pulling fs layer|Waiting|Downloading|Download complete|Verifying Checksum|Extracting|Pull complete|Already exists)/,
+  /^\s*[0-9a-f]{12} (?:Pulling fs layer|Waiting|Downloading|Download complete|Verifying|Extracting|Pull complete|Already exists)/,
+  /^\s*Image \S+\s+(?:Pulling|Pulled)\s*$/,
+  /^\s*Container \S+\s+(?:Creating|Created|Starting|Started|Running|Waiting|Healthy|Stopping|Stopped|Removing|Removed)\s*$/,
+  /^\s*Nx read the output from the cache/
+];
+function isNoise(line, patterns = NOISE_PATTERNS) {
+  return patterns.some((p) => p.test(line));
+}
+function tailMeaningful(lines, n, patterns = NOISE_PATTERNS) {
+  const out = [];
+  for (let i = lines.length - 1; i >= 0 && out.length < n; i--) {
+    const line = (lines[i] ?? "").trimEnd();
+    if (line.trim() && !isNoise(line, patterns)) out.unshift(line);
+  }
+  return out;
+}
+
+// src/terminal-output/follow-tail.ts
+var DEFAULT_TAIL_THRESHOLD = 24;
+function distanceFromEnd({ scrollTop, scrollHeight, clientHeight }) {
+  return scrollHeight - scrollTop - clientHeight;
+}
+function isNearEnd(metrics, threshold = DEFAULT_TAIL_THRESHOLD) {
+  return distanceFromEnd(metrics) <= threshold;
+}
+function shouldStick(prevAtBottom, metrics, userInitiated, threshold = DEFAULT_TAIL_THRESHOLD) {
+  if (!userInitiated) return prevAtBottom;
+  return isNearEnd(metrics, threshold);
+}
+function isUserScrollUp({ kind, delta = 0, lastTarget, scrollTop }, threshold = DEFAULT_TAIL_THRESHOLD) {
+  if (kind === "wheel") return delta < 0;
+  if (kind === "touch") return delta > 0;
+  if (kind === "gutter") return true;
+  return lastTarget !== null && scrollTop < lastTarget - threshold;
+}
+function unreadDelta(prevCount, nextCount, attached) {
+  if (attached) return 0;
+  return Math.max(0, nextCount - prevCount);
+}
+
+// src/terminal-output/use-follow-tail.ts
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+var useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+function useFollowTail({
+  scrollRef,
+  itemCount,
+  scrollToEnd,
+  resetKey,
+  threshold = DEFAULT_TAIL_THRESHOLD
+}) {
+  const [atBottom, setAtBottom] = useState(true);
+  const [unread, setUnread] = useState(0);
+  const attached = useRef(true);
+  const programmatic = useRef(false);
+  const lastTarget = useRef(null);
+  const lastTop = useRef(0);
+  const frame = useRef(0);
+  const prevCount = useRef(itemCount);
+  const prevReset = useRef(resetKey);
+  const latest = useRef({ scrollToEnd, threshold });
+  latest.current = { scrollToEnd, threshold };
+  const attach = useCallback((value) => {
+    attached.current = value;
+    setAtBottom(value);
+    if (value) setUnread(0);
+  }, []);
+  const followEnd = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    programmatic.current = true;
+    if (latest.current.scrollToEnd) latest.current.scrollToEnd();
+    else el.scrollTop = el.scrollHeight;
+    lastTarget.current = el.scrollHeight - el.clientHeight;
+    if (typeof requestAnimationFrame === "function") {
+      cancelAnimationFrame(frame.current);
+      frame.current = requestAnimationFrame(() => {
+        programmatic.current = false;
+      });
+    } else {
+      programmatic.current = false;
+    }
+  }, [scrollRef]);
+  useIsomorphicLayoutEffect(() => {
+    const count = prevCount.current;
+    prevCount.current = itemCount;
+    if (prevReset.current !== resetKey) {
+      prevReset.current = resetKey;
+      attach(true);
+      followEnd();
+      return;
+    }
+    if (attached.current) {
+      if (itemCount > 0) followEnd();
+      return;
+    }
+    const added = unreadDelta(count, itemCount, false);
+    if (added > 0) setUnread((n) => n + added);
+  }, [itemCount, resetKey, attach, followEnd]);
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const takeOver = () => {
+      programmatic.current = false;
+      lastTarget.current = null;
+      if (attached.current) attach(false);
+    };
+    const onScroll = () => {
+      const { threshold: limit } = latest.current;
+      const movedUp = el.scrollTop < lastTop.current;
+      lastTop.current = el.scrollTop;
+      const info = { kind: "scroll", lastTarget: movedUp ? lastTarget.current : null, scrollTop: el.scrollTop };
+      const user = isUserScrollUp(info, limit);
+      if (user) takeOver();
+      const next = shouldStick(attached.current, el, user || !programmatic.current, limit);
+      if (next !== attached.current) attach(next);
+    };
+    const canScrollUp = () => el.scrollHeight > el.clientHeight && el.scrollTop > 0;
+    const onWheel = (e) => {
+      if (canScrollUp() && isUserScrollUp({ kind: "wheel", delta: e.deltaY, lastTarget: null, scrollTop: el.scrollTop })) takeOver();
+    };
+    let touchY = 0;
+    const onTouchStart = (e) => {
+      touchY = e.touches[0]?.clientY ?? 0;
+    };
+    const onTouchMove = (e) => {
+      const delta = (e.touches[0]?.clientY ?? touchY) - touchY;
+      if (canScrollUp() && isUserScrollUp({ kind: "touch", delta, lastTarget: null, scrollTop: el.scrollTop })) takeOver();
+    };
+    const onPointerDown = (e) => {
+      const gutter = el.offsetWidth - el.clientWidth;
+      if (e.target !== el || gutter <= 0) return;
+      if (e.clientX >= el.getBoundingClientRect().left + el.clientWidth) {
+        if (isUserScrollUp({ kind: "gutter", lastTarget: null, scrollTop: el.scrollTop })) takeOver();
+      }
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    el.addEventListener("wheel", onWheel, { passive: true });
+    el.addEventListener("touchstart", onTouchStart, { passive: true });
+    el.addEventListener("touchmove", onTouchMove, { passive: true });
+    el.addEventListener("pointerdown", onPointerDown, { passive: true });
+    return () => {
+      el.removeEventListener("scroll", onScroll);
+      el.removeEventListener("wheel", onWheel);
+      el.removeEventListener("touchstart", onTouchStart);
+      el.removeEventListener("touchmove", onTouchMove);
+      el.removeEventListener("pointerdown", onPointerDown);
+      if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(frame.current);
+    };
+  }, [scrollRef, attach]);
+  const jumpToBottom = useCallback(() => {
+    attach(true);
+    followEnd();
+  }, [attach, followEnd]);
+  return { atBottom, unread, jumpToBottom };
+}
+
+export {
+  Screen,
+  stripAnsi,
+  feedAnsi,
+  parseAnsi,
+  createAnsiParser,
+  filterLines,
+  splitByMatch,
+  FAILURE_PATTERNS,
+  findFailures,
+  firstFailureIndex,
+  NOISE_PATTERNS,
+  isNoise,
+  tailMeaningful,
+  DEFAULT_TAIL_THRESHOLD,
+  distanceFromEnd,
+  isNearEnd,
+  shouldStick,
+  isUserScrollUp,
+  unreadDelta,
+  useFollowTail
+};