hackernews-tui 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# Hacker News TUI
+
+![Hacker News TUI screenshot](./readme.png)
+
+A full terminal UI for browsing Hacker News using the official [Hacker News API](https://github.com/HackerNews/API) and OpenTUI.
+
+## Features
+
+- Browse feeds: Top, New, Best, Ask, Show, Jobs
+- Search loaded stories by title, author, URL, and text
+- Filter stories by post class and minimum points
+- Sort stories by rank, newest, points, or comment count
+- Open article URLs and HN discussion pages from the terminal
+- Deep post view with recursively loaded nested comments
+
+## Install
+
+```bash
+bun install
+```
+
+## Run
+
+```bash
+bun dev
+```
+
+Run from npm with Bun:
+
+```bash
+bunx hackernews-tui
+```
+
+Watch mode (auto-restart on file changes):
+
+```bash
+bun run dev:watch
+```
+
+## Quality Checks
+
+```bash
+bun run typecheck
+bun run lint
+bun run format
+bun run test
+```
+
+## Publish
+
+```bash
+npm login
+npm publish --access public
+```
+
+## Keybindings
+
+- `Tab`: cycle focus (`list -> detail -> search`)
+- `/`: focus search box
+- `Esc` / `Enter` (from search): return to story list
+- `1-6`: switch feed (`Top, New, Best, Ask, Show, Jobs`)
+- `s`: cycle sort mode
+- `t`: cycle post type filter
+- `p`: cycle minimum points filter
+- `j` / `k` or `Down` / `Up`: move through stories
+- `Enter` / `l` / `Right`: move focus to detail pane
+- `h` / `Left`: move focus back to story list
+- `n`: load more stories from current feed
+- `r`: refresh current feed
+- `o`: open selected story URL (or HN link fallback)
+- `i`: open selected HN discussion page
+- `q`: quit

package/bin/hackernews-tui

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/index.tsx";

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "hackernews-tui",
+  "version": "0.1.0",
+  "description": "A terminal UI for browsing Hacker News with search, filters, and deep threads.",
+  "module": "src/index.tsx",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "hackernews-tui": "bin/hackernews-tui"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "readme.png"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "hackernews",
+    "hn",
+    "tui",
+    "terminal",
+    "opentui",
+    "bun"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.tsx",
+    "dev:watch": "bun run --watch src/index.tsx",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "bun run lint && bun run typecheck && bun run test",
+    "prepublishOnly": "bun run check"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.5",
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.84",
+    "@opentui/react": "^0.1.84",
+    "react": "^19.2.4"
+  }
+}

package/src/app/constants.ts

@@ -0,0 +1,58 @@
+export const STORY_FETCH_STEP = 120;
+export const STORY_FETCH_CONCURRENCY = 16;
+export const COMMENT_INITIAL_BATCH = 40;
+export const COMMENT_BATCH_SIZE = 30;
+export const COMMENT_NEAR_BOTTOM_THRESHOLD = 4;
+
+export const FEED_OPTIONS = [
+  { value: "topstories", label: "Top" },
+  { value: "newstories", label: "New" },
+  { value: "beststories", label: "Best" },
+  { value: "askstories", label: "Ask" },
+  { value: "showstories", label: "Show" },
+  { value: "jobstories", label: "Jobs" },
+] as const;
+
+export const SORT_OPTIONS = ["rank", "newest", "points", "comments"] as const;
+export const SORT_LABELS: Record<(typeof SORT_OPTIONS)[number], string> = {
+  rank: "Rank",
+  newest: "Newest",
+  points: "Points",
+  comments: "Comments",
+};
+
+export const TYPE_FILTER_OPTIONS = ["all", "story", "ask", "show", "job"] as const;
+export const TYPE_FILTER_LABELS: Record<(typeof TYPE_FILTER_OPTIONS)[number], string> = {
+  all: "All",
+  story: "Stories",
+  ask: "Ask",
+  show: "Show",
+  job: "Jobs",
+};
+
+export const SCORE_FILTER_OPTIONS = [0, 10, 50, 100, 250] as const;
+
+export const UI = {
+  appBackground: "#111722",
+  panelBackground: "#16202d",
+  border: "#9aa8be",
+  text: "#f4f7ff",
+  muted: "#cad2df",
+  accent: "#8dd6ff",
+  accentWarm: "#ffd58a",
+  success: "#b4ef8b",
+  link: "#9fc4ff",
+  listBackground: "#141d2a",
+  listFocusedBackground: "#1b2738",
+  listSelectedBackground: "#355984",
+  listSelectedText: "#fff6cc",
+  inputBackground: "#0f1622",
+  inputText: "#f4f7ff",
+  inputPlaceholder: "#98a8be",
+  danger: "#ff879a",
+} as const;
+
+export type FeedKey = (typeof FEED_OPTIONS)[number]["value"];
+export type SortMode = (typeof SORT_OPTIONS)[number];
+export type StoryClass = (typeof TYPE_FILTER_OPTIONS)[number];
+export type FocusZone = "list" | "detail" | "search";

package/src/hooks/use-hn-browser-state.ts

@@ -0,0 +1,337 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  COMMENT_BATCH_SIZE,
+  COMMENT_INITIAL_BATCH,
+  STORY_FETCH_CONCURRENCY,
+  STORY_FETCH_STEP,
+  type FeedKey,
+  type SortMode,
+  type StoryClass,
+} from "../app/constants";
+import {
+  createCommentStack,
+  loadNextCommentBatch,
+  type CommentStackNode,
+  type FlatComment,
+} from "../lib/comment-loader";
+import { getFeedIds, getItemCached, mapWithConcurrency } from "../lib/hn-api";
+import { classifyStory, getErrorMessage, htmlToText, type HNItem } from "../lib/hn-utils";
+
+interface CommentCursorState {
+  storyId: number;
+  stack: CommentStackNode[];
+}
+
+export function useHnBrowserState() {
+  const commentCursorRef = useRef<CommentCursorState | null>(null);
+  const commentLoadInFlightRef = useRef(false);
+
+  const [feed, setFeed] = useState<FeedKey>("topstories");
+  const [refreshTick, setRefreshTick] = useState(0);
+  const [storyLimit, setStoryLimit] = useState(STORY_FETCH_STEP);
+  const [feedIds, setFeedIds] = useState<number[]>([]);
+  const [stories, setStories] = useState<HNItem[]>([]);
+  const [selectedStoryIndex, setSelectedStoryIndex] = useState(0);
+
+  const [feedLoading, setFeedLoading] = useState(false);
+  const [storyLoading, setStoryLoading] = useState(false);
+  const [detailLoading, setDetailLoading] = useState(false);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  const [searchQuery, setSearchQuery] = useState("");
+  const [sortMode, setSortMode] = useState<SortMode>("rank");
+  const [storyClass, setStoryClass] = useState<StoryClass>("all");
+  const [minScore, setMinScore] = useState(0);
+
+  const [detailItem, setDetailItem] = useState<HNItem | null>(null);
+  const [detailComments, setDetailComments] = useState<FlatComment[]>([]);
+  const [hasMoreComments, setHasMoreComments] = useState(false);
+  const [loadingMoreComments, setLoadingMoreComments] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    setFeedLoading(true);
+    setStoryLoading(false);
+    setDetailLoading(false);
+    setErrorMessage(null);
+    setFeedIds([]);
+    setStories([]);
+    setStoryLimit(STORY_FETCH_STEP);
+    setSelectedStoryIndex(0);
+    setDetailItem(null);
+    setDetailComments([]);
+    setHasMoreComments(false);
+    setLoadingMoreComments(false);
+    commentCursorRef.current = null;
+    commentLoadInFlightRef.current = false;
+
+    void (async () => {
+      try {
+        const ids = await getFeedIds(feed, refreshTick);
+        if (cancelled) {
+          return;
+        }
+        setFeedIds(ids);
+      } catch (error) {
+        if (cancelled) {
+          return;
+        }
+        setErrorMessage(`Failed to load feed IDs: ${getErrorMessage(error)}`);
+      } finally {
+        if (!cancelled) {
+          setFeedLoading(false);
+        }
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [feed, refreshTick]);
+
+  useEffect(() => {
+    if (feedIds.length === 0) {
+      return;
+    }
+
+    let cancelled = false;
+    const idsToLoad = feedIds.slice(0, storyLimit);
+
+    setStoryLoading(true);
+    setErrorMessage(null);
+
+    void (async () => {
+      try {
+        const items = await mapWithConcurrency(idsToLoad, STORY_FETCH_CONCURRENCY, getItemCached);
+        if (cancelled) {
+          return;
+        }
+
+        const filtered = items.filter((item): item is HNItem => {
+          if (!item) {
+            return false;
+          }
+          return item.type === "story" || item.type === "job" || item.type === "poll";
+        });
+
+        setStories(filtered);
+      } catch (error) {
+        if (cancelled) {
+          return;
+        }
+        setErrorMessage(`Failed to load stories: ${getErrorMessage(error)}`);
+      } finally {
+        if (!cancelled) {
+          setStoryLoading(false);
+        }
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [feedIds, storyLimit]);
+
+  const feedOrder = useMemo(() => {
+    const order = new Map<number, number>();
+    feedIds.forEach((id, index) => {
+      order.set(id, index);
+    });
+    return order;
+  }, [feedIds]);
+
+  const normalizedSearch = searchQuery.trim().toLowerCase();
+  const filteredStories = useMemo(() => {
+    const matches = stories.filter((story) => {
+      if ((story.score ?? 0) < minScore) {
+        return false;
+      }
+      if (storyClass !== "all" && classifyStory(story) !== storyClass) {
+        return false;
+      }
+      if (!normalizedSearch) {
+        return true;
+      }
+
+      const haystack = [story.title ?? "", story.by ?? "", story.url ?? "", htmlToText(story.text)]
+        .join(" ")
+        .toLowerCase();
+      return haystack.includes(normalizedSearch);
+    });
+
+    const sorted = [...matches];
+    sorted.sort((a, b) => {
+      switch (sortMode) {
+        case "newest":
+          return (b.time ?? 0) - (a.time ?? 0);
+        case "points":
+          return (b.score ?? 0) - (a.score ?? 0);
+        case "comments":
+          return (b.descendants ?? 0) - (a.descendants ?? 0);
+        default:
+          return (
+            (feedOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) -
+            (feedOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER)
+          );
+      }
+    });
+    return sorted;
+  }, [stories, minScore, storyClass, normalizedSearch, sortMode, feedOrder]);
+
+  useEffect(() => {
+    if (filteredStories.length === 0 && selectedStoryIndex !== 0) {
+      setSelectedStoryIndex(0);
+      return;
+    }
+
+    if (filteredStories.length > 0 && selectedStoryIndex >= filteredStories.length) {
+      setSelectedStoryIndex(filteredStories.length - 1);
+    }
+  }, [filteredStories.length, selectedStoryIndex]);
+
+  const selectedStory = filteredStories[selectedStoryIndex] ?? null;
+  const selectedStoryId = selectedStory?.id ?? null;
+
+  const loadMoreComments = useCallback(async (storyId: number, batchSize: number = COMMENT_BATCH_SIZE) => {
+    const cursor = commentCursorRef.current;
+    if (!cursor || cursor.storyId !== storyId || commentLoadInFlightRef.current) {
+      return;
+    }
+    if (cursor.stack.length === 0) {
+      setHasMoreComments(false);
+      return;
+    }
+
+    commentLoadInFlightRef.current = true;
+    setLoadingMoreComments(true);
+
+    try {
+      const loadedBatch = await loadNextCommentBatch(cursor.stack, batchSize, getItemCached);
+
+      if (commentCursorRef.current?.storyId !== storyId) {
+        return;
+      }
+      if (loadedBatch.length > 0) {
+        setDetailComments((previous) => [...previous, ...loadedBatch]);
+      }
+      setHasMoreComments(cursor.stack.length > 0);
+    } catch (error) {
+      if (commentCursorRef.current?.storyId !== storyId) {
+        return;
+      }
+      setErrorMessage(`Failed to load comments: ${getErrorMessage(error)}`);
+    } finally {
+      if (commentCursorRef.current?.storyId === storyId) {
+        setLoadingMoreComments(false);
+      }
+      commentLoadInFlightRef.current = false;
+    }
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    if (!selectedStoryId) {
+      setDetailLoading(false);
+      setDetailItem(null);
+      setDetailComments([]);
+      setHasMoreComments(false);
+      setLoadingMoreComments(false);
+      commentCursorRef.current = null;
+      commentLoadInFlightRef.current = false;
+      return;
+    }
+
+    setDetailItem(selectedStory);
+    setDetailComments([]);
+    setHasMoreComments(false);
+    setLoadingMoreComments(false);
+    commentCursorRef.current = null;
+    commentLoadInFlightRef.current = false;
+    setDetailLoading(true);
+    setErrorMessage(null);
+
+    void (async () => {
+      try {
+        const item = await getItemCached(selectedStoryId);
+        if (!item) {
+          throw new Error(`Story ${selectedStoryId} not found`);
+        }
+        if (cancelled) {
+          return;
+        }
+        setDetailItem(item);
+        setDetailComments([]);
+        const stack = createCommentStack(item.kids);
+
+        commentCursorRef.current = {
+          storyId: selectedStoryId,
+          stack,
+        };
+        setHasMoreComments(stack.length > 0);
+
+        if (stack.length > 0) {
+          await loadMoreComments(selectedStoryId, COMMENT_INITIAL_BATCH);
+        }
+      } catch (error) {
+        if (cancelled) {
+          return;
+        }
+        setDetailItem(selectedStory ?? null);
+        setDetailComments([]);
+        setHasMoreComments(false);
+        setLoadingMoreComments(false);
+        commentCursorRef.current = null;
+        commentLoadInFlightRef.current = false;
+        setErrorMessage(`Failed to load post details: ${getErrorMessage(error)}`);
+      } finally {
+        if (!cancelled) {
+          setDetailLoading(false);
+        }
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [selectedStoryId, selectedStory, loadMoreComments]);
+
+  const refreshFeed = () => {
+    setRefreshTick((current) => current + 1);
+  };
+
+  return {
+    feed,
+    setFeed,
+    storyLimit,
+    setStoryLimit,
+    feedIds,
+    stories,
+    selectedStoryIndex,
+    setSelectedStoryIndex,
+    feedLoading,
+    storyLoading,
+    detailLoading,
+    errorMessage,
+    searchQuery,
+    setSearchQuery,
+    sortMode,
+    setSortMode,
+    storyClass,
+    setStoryClass,
+    minScore,
+    setMinScore,
+    detailItem,
+    detailComments,
+    hasMoreComments,
+    loadingMoreComments,
+    feedOrder,
+    filteredStories,
+    selectedStory,
+    selectedStoryId,
+    loadMoreComments,
+    refreshFeed,
+    isCommentLoadInFlight: commentLoadInFlightRef,
+  };
+}