https://github.com/corychainsman/twitter-bookmarks
Twitter bookmarks media browser
https://github.com/corychainsman/twitter-bookmarks
Last synced: about 19 hours ago
JSON representation
Twitter bookmarks media browser
- Host: GitHub
- URL: https://github.com/corychainsman/twitter-bookmarks
- Owner: corychainsman
- Created: 2026-04-18T03:51:40.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-12T22:46:52.000Z (5 days ago)
- Last Synced: 2026-06-12T23:22:14.417Z (5 days ago)
- Language: TypeScript
- Homepage: https://corychainsman.github.io/twitter-bookmarks/
- Size: 48.4 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Twitter Bookmarks
Media-first browser for X bookmarks exported through Field Theory.
Live demo: [corychainsman.github.io/twitter-bookmarks](https://corychainsman.github.io/twitter-bookmarks/)
## What It Ships
- Real exported bookmark media data committed into `public/data`
- Self-hosted media: all tweet photos/videos are archived and served from
Cloudflare R2 at `tbmedia.corychainsman.com` (no twimg.com dependency),
with pre-generated AVIF tiers and ThumbHash placeholders
- Fast client-side search, folder filtering, sort controls, and URL-backed state
- Static CLIP embedding index for concept search across tweet text, images, and video poster frames
- Text search, image search, and “Similar” browsing with no backend
- `One` / `All` media modes
- `Immersive` media-only mode
- Theme Studio at [`/themes`](https://corychainsman.github.io/twitter-bookmarks/themes) with live cross-tab updates and theme import/export
- Static deployment to GitHub Pages
## Stack
- React 19
- TypeScript
- Vite
- Bun
- shadcn/ui primitives
- Lucide icons
- `@virtuoso.dev/masonry` for the media grid
## Local Development
```bash
bun install
bun run dev
```
App:
- Main app: [http://localhost:5173/](http://localhost:5173/)
- Theme Studio: [http://localhost:5173/themes](http://localhost:5173/themes)
## Data Flow
The app is built to consume static JSON artifacts under `public/data`.
Typical refresh flow:
```bash
bun run sync:ft
bun run data:mirror # download new media + AVIF variants + thumbhashes
bun run mirror:sync # upload archive to R2 + Google Drive backup
bun run data:export
bun run data:embeddings
bun run data:validate
bun run build
```
Convenience commands:
```bash
bun run refresh
bun run refresh:resume
bun run refresh:full
bun run refresh:embeddings
```
Notes:
- `sync:ft` depends on a real local Field Theory/X session.
- `data:mirror` archives originals to `.data/media/assets/` (gitignored) and
tracks status in `.data/media/mirror-manifest.json`; `data:export` rewrites
media URLs to the mirror for confirmed assets. See
[docs/runbooks/media-mirror.md](./docs/runbooks/media-mirror.md).
- `mirror:sync` pulls R2 credentials from 1Password (`op environment read`),
so the 1Password app's CLI integration must be unlocked.
- The exported app dataset is media-only; non-media bookmarks are not included in the shipped browsing surface.
- `data:embeddings` precomputes a compact static CLIP vector index into `public/data/embeddings/index.json`.
- Semantic search runs entirely in the browser: GitHub Pages serves the vector index, and Transformers.js loads the same CLIP model client-side to embed typed text or uploaded query images.
- Video and animated GIF entries are embedded from their exported poster/preview image, so similarity captures the representative visual frame rather than temporal motion.
## Scripts
- `bun run dev`: start the local app
- `bun run test`: run Vitest
- `bun run lint`: run ESLint
- `bun run typecheck`: run TypeScript project checks
- `bun run build`: build the static app
- `bun run preview`: preview the production build locally
- `bun run sync:ft`: sync bookmark data from Field Theory
- `bun run data:mirror`: download/mirror tweet media into the local archive
- `bun run mirror:sync`: sync the media archive to Cloudflare R2 + Google Drive
- `bun run data:export`: build static artifacts into `public/data`
- `bun run data:embeddings`: build static semantic embedding artifacts into `public/data`
- `bun run data:validate`: validate exported artifacts
## GitHub Pages
Deployments are handled by [`.github/workflows/deploy.yml`](./.github/workflows/deploy.yml).
- Push to `main`
- GitHub Actions builds with `GITHUB_PAGES=true`
- The site is published at [corychainsman.github.io/twitter-bookmarks](https://corychainsman.github.io/twitter-bookmarks/)
## Repository Structure
```text
src/app/ App shell, router, theme studio
src/components/ Toolbar, grid, lightbox, media, UI primitives
src/features/bookmarks/ Query state, loaders, export contracts, caching
src/features/theme/ Theme model, runtime variables, persistence
src/workers/ Query worker
scripts/ Field Theory sync, media mirror, and export pipeline
public/data/ Shipped static bookmark artifacts
.data/media/ Local media archive + mirror manifest (gitignored)
```