First Class Lookup — Motivation

When a Reader user selects text, the lookup experience should be a first-class feature — not a basic dictionary popup but a rich, contextual panel that handles definitions, encyclopedia entries, translations, character/place lookups (X-Ray), and more. The goal is to make looking things up while reading feel native and delightful, reducing the friction of leaving the reading surface to search externally.

This is especially important for Reader's power users who read across languages and genres, and for Bookwise where the reading experience is the core product. The lookup panel replaces what was previously a minimal dictionary-only feature with an LLM-powered contextual tool.

First Class Lookup — Shape

Key design decisions

• Multiple lookup modes in one panel — Dictionary, Encyclopedia, Translate, X-Ray (characters/places) all accessible from the same selection-triggered panel, not separate features.
• Reader-first, then Bookwise — Originally designed for Bookwise, switched to Reader-first in Nov 2025 after Christina's design rounds. Same design doc, different product target.
• LLM-powered contextual responses — Definitions and lookups use LLMs for contextual, single-definition answers rather than raw dictionary dumps.
• X-Ray uses Turbopuffer/FTS — Character and place lookups search across the document via hybrid search (full-text + vector) to find all mentions.

Scope

• Dictionary lookup with contextual single-definition responses
• Encyclopedia lookup for real-world terms
• X-Ray for fictional characters and places (per-document search)
• Translation with inline display
• Copy-to-highlight flow from lookup results
• Panel UI with animations, resize, scroll

Design contributors

• Jackson (initial Figma prototype, Aug 2025)
• Christina Xie (design rounds Nov 2025 — Looms + Notion spec updates)
• Dan (PM shaping, prompt quality requirements)
• Kris (design direction, Reader-first pivot)

Appetite

Medium-large — design from Aug-Nov 2025, build from Nov 2025-Mar 2026.

First Class Lookup — Build

What was built

• Lookup panel UI — Selection-triggered panel with dictionary, encyclopedia, translate, and X-Ray modes. Built by Adam Lynch.
• X-Ray document search — Piotr wired up Turbopuffer-based document search for character/place lookups via document index (PR #8578, merged Mar 18).
• LLM integration — Contextual definitions and encyclopedia entries powered by LLM prompts. Piotr handled the LLM/X-Ray/Turbopuffer backend.
• Various UI/UX — Adam's "First Class Lookup: various" PR (#8569, merged Mar 18) covered panel interactions, animations, and core UI.
• Staff-only deployment — Feature deployed to staff builds by ~Mar 18 for dogfooding.

Build contributors

• Adam Lynch (UI/panel, primary builder)
• Piotr (LLM backend, X-Ray, Turbopuffer search)

Open Questions (for Expedite)

• X-Ray hallucinating for characters/places — needs FTS/hybrid search + prompt rewrite
• Dictionary returning multiple definitions instead of one contextual definition
• Encyclopedia hallucinating on fictional terms
• Panel scroll bugs (content clipping, scroll getting stuck)
• Translate display glitch + markdown leaking
• Copy-to-highlight flow triggering selection menu again
• Panel polish (animation, button shifting, shadow, resize grabber)

First Class Lookup — Expedite (WIP)

This document is underway while the project is in Expedite. It will be finalized when the stage completes.

Entered Expedite: 2026-03-31 · Owner: @adam · Initiative: rw-projects

Goal

Get First Class Lookup from staff-only builds to ship-ready. The UI/chrome is solid — remaining work is primarily LLM response quality + panel bugs.

Team

• Expediter: Kris
• Tasters: Dan (prompt quality), Kris (UI)
• Fixers: Adam (UI/panel), Piotr (LLM/X-Ray/Turbopuffer)

The Plate

1. X-Ray quality overhaul — hallucinating for characters/places, needs FTS/hybrid search + prompt rewrite
2. Dictionary prompt fix — returning multiple definitions instead of one contextual definition
3. Lookup (encyclopedia) hallucinating on fictional terms
4. Panel scroll bugs — content clipping, scroll getting stuck
5. Translate bugs — display glitch + markdown leaking
6. Copy → highlight flow — triggers selection menu again after copying
7. Panel polish — animation, button shifting, shadow, resize grabber

Pass recordings

• Kris: https://www.loom.com/share/88f593db364c4865a9e0414aa3ab7c1f (21 min)
• Dan: https://www.loom.com/share/f5e3fd377785454dbda30cb5643dc94c (16.5 min)

What's been done

• Adam reviewing expedite items and working through fixes
• Expedite scenarios shaped using Dan's scenario-testing skill + Kris's expedite approach
• E-ink color issues discovered and spun off to separate #bwl-eink-tuneups channel (Apr 15)

What's in progress

• Adam working through the plate items
• Piotr on LLM/X-Ray quality fixes

Open Questions (for Ship)

• Feedback format needs iteration — Adam noted scenarios sometimes contain multiple separate issues, making them harder to work through
• E-ink rendering not optimized (tracked separately in #bwl-eink-tuneups)