@develemit/web-hooks 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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,7 @@ 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 |
 
 Behavior only. No styling and no components: each app keeps its own look.
 
@@ -405,3 +406,54 @@ 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>
+))}
+```