From acc4fe841bf5b73aa2c82e96b853341db314ac7b Mon Sep 17 00:00:00 2001 From: yutakobayashidev Date: Tue, 14 Jul 2026 01:28:23 +0900 Subject: [PATCH] docs: document tweet conversations --- README.md | 9 +++++++++ .../plans/2026-07-13-twitter-lite.md | 4 ++++ .../specs/2026-07-13-twitter-lite-design.md | 19 ++++++++++++++++++- 3 files changed, 31 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 79f537b..6424515 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,16 @@ enter a user handle, profile URL, or search query. - Popular (`Top`) and chronological (`Latest`) search - Optional `filter:follows` search - Infinite cursor pagination with explicit retry +- Deliberate post detail pages with the visible conversation +- Infinite conversation loading with explicit continuation retry - Read-only cards for text, media, quotes, articles, and quiet engagement counts It intentionally has no home feed, recommendations, trends, notifications, history, account directory, or write actions. +Post detail pages show only the selected post and its visible conversation; +they do not add related-post recommendations or an account-discovery surface. + ## Requirements and setup Use Nix, or Node.js `>=22.12.0` with pnpm `11.9.0`. The package link also @@ -72,3 +77,7 @@ only on a trusted network and obtain the Tailscale address with Bird uses X's internal GraphQL operations through the configured relay. Query IDs and response shapes can change without notice. + +Conversation pages use Bird's current per-page chronological ordering. Keeping +X's original ranked branch order is deferred until Bird exposes that order +without expanding the relay surface. diff --git a/docs/superpowers/plans/2026-07-13-twitter-lite.md b/docs/superpowers/plans/2026-07-13-twitter-lite.md index 780abd1..8a571db 100644 --- a/docs/superpowers/plans/2026-07-13-twitter-lite.md +++ b/docs/superpowers/plans/2026-07-13-twitter-lite.md @@ -2,6 +2,10 @@ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. +> Subsequent extension: tweet detail and conversation loading are implemented +> by `2026-07-13-tweet-detail-thread.md` and specified by +> `../specs/2026-07-13-tweet-detail-thread-design.md`. + **Goal:** Build a localhost-only TanStack Start reader that loads user timelines and Top/Latest searches through a read-only Bird server boundary. **Architecture:** First extend the sibling Bird repository with a typed search product option. Then build Twitter Lite as a TanStack Start application whose server functions call Bird, while TanStack Query owns cursor pagination and the browser renders the Mist Instrument interface. diff --git a/docs/superpowers/specs/2026-07-13-twitter-lite-design.md b/docs/superpowers/specs/2026-07-13-twitter-lite-design.md index 9cc12dd..5a522e8 100644 --- a/docs/superpowers/specs/2026-07-13-twitter-lite-design.md +++ b/docs/superpowers/specs/2026-07-13-twitter-lite-design.md @@ -33,6 +33,7 @@ The product reduces ambient discovery rather than limiting how far a deliberate - raw X search syntax; - `Top` and `Latest` search products; - `filter:follows` search filtering; +- deliberate post detail pages with cursor-paginated visible conversations; - photos, videos, animated GIFs, quoted posts, article previews, and engagement counts when supplied by Bird; - infinite cursor pagination; - explicit retry, empty, error, loading, and end states; @@ -46,6 +47,7 @@ The product reduces ambient discovery rather than limiting how far a deliberate - all X mutation operations; - user autocomplete and typeahead; - People and Media search products; +- related-post feeds and automatic post discovery; - a generic relay proxy; - deployment beyond a personal localhost process. @@ -105,6 +107,7 @@ TanStack Start supplies the browser/server boundary. Bird is imported only by se - `/user?target=` displays the User tab. - `/search?q=&product=&following=` displays the Search tab. +- `/status/:tweetId` displays one selected post and its visible conversation. - `/` redirects to `/user` without a target. The target, query, product, and following flag are validated typed search parameters. Cursor state is internal to TanStack Query because it is transport state rather than a user-controlled view setting. @@ -125,7 +128,7 @@ new TwitterClient({ `TWITTER_RELAY_BASE_URL` is required. `BIRD_PROFILE_NAME` is optional but must be passed explicitly because the Bird library does not read that environment variable itself. -Only two server functions are callable by the application: +Only three server functions are callable by the application: ```ts type PostPage = { @@ -144,8 +147,18 @@ searchPosts(input: { following: boolean cursor?: string }): Promise + +loadThreadPosts(input: + | { tweetId: string } + | { tweetId: string; conversationId: string; cursor: string } +): Promise ``` +The status route and `loadThreadPosts` contract are specified in +`2026-07-13-tweet-detail-thread-design.md`. Conversation reads compose Bird's +existing `getTweet()` and `getThreadPaged()` methods; they add no Bird or relay +operation. + Neither function exposes the Bird client, arbitrary method names, arbitrary relay URLs, or mutation operations. ### User Timeline Flow @@ -174,6 +187,10 @@ The first request fetches 20 posts. An IntersectionObserver sentinel near the li Flattened pages are deduplicated by post ID while preserving API order. A failed later page leaves all previously loaded posts visible and presents one explicit Retry control. Requests do not retry automatically. +User and search pages preserve API order. Conversation pages preserve Bird's +current order: chronological within a fetched page, with cursor pages appended +in retrieval order. + ## Interface Design ### Layout