Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 18 additions & 17 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,23 +96,24 @@ CI derives the npm dist-tag from the version string alone: a prerelease (hyphen)

### Viewer & scroll

| Term | Definition |
| ------------------- | ------------------------------------------------------------------------------------------------------ |
| Viewer | The scrollable content area (`<scrollbox>`) |
| Viewport | The currently visible region of the Viewer (`box.viewport.{y,height}`) |
| Geometry | `BoxGeometry` — the narrow structural port over the scrollbox that all pure scroll math reads |
| Overlay | The sticky region painted over the top of the Viewport (Trail row + Ancestor rows) |
| Fold | Line `topOffset + PIN_TOP_OFFSET` below the viewport top that decides which heading is current |
| Fold offset | Rows the Overlay occludes for a given heading; `Fold.offsetFor` / `aboveOffsetFor` |
| Pin | A scroll that parks a heading at the Fold (`scrollChildToTop`, `pinHeadingPostLayout`) |
| Pending target | Queued scroll (heading / top / match) retried each post-layout frame until reached; `pendingReducer` |
| Swap reposition | A Pending target flagged `isSwap`; resolving it fires `onRepositioned`, which drops the Cover |
| Cover | Opaque box masking the Viewer while a Doc swap repositions, so the reader never sees the top-then-jump |
| Progressive mount | Mounting top-level nodes in chunks (`CHUNK_SIZE`) after a viewport-sized first paint |
| Scrollbox tail | Empty `<box height={tailSpace}>` after content so the last heading can scroll to the Fold |
| Tail reserve | Fold offset withheld from the tail so the last heading pins correctly |
| Real content height | `scrollHeight` minus the tail — the height used for scrollability and thumb-size math |
| Scroll marks | Search matches resolved to document-space `y` and painted onto scrollbar track rows (`TrackCell`) |
| Term | Definition |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| Viewer | The scrollable content area (`<scrollbox>`) |
| Viewport | The currently visible region of the Viewer (`box.viewport.{y,height}`) |
| Breakout width | Columns a rendered diagram may span: `contentWidth` with the TOC shown, the whole column with it hidden |
| Geometry | `BoxGeometry` — the narrow structural port over the scrollbox that all pure scroll math reads |
| Overlay | The sticky region painted over the top of the Viewport (Trail row + Ancestor rows) |
| Fold | Line `topOffset + PIN_TOP_OFFSET` below the viewport top that decides which heading is current |
| Fold offset | Rows the Overlay occludes for a given heading; `Fold.offsetFor` / `aboveOffsetFor` |
| Pin | A scroll that parks a heading at the Fold (`scrollChildToTop`, `pinHeadingPostLayout`) |
| Pending target | Queued scroll (heading / top / match) retried each post-layout frame until reached; `pendingReducer` |
| Swap reposition | A Pending target flagged `isSwap`; resolving it fires `onRepositioned`, which drops the Cover |
| Cover | Opaque box masking the Viewer while a Doc swap repositions, so the reader never sees the top-then-jump |
| Progressive mount | Mounting top-level nodes in chunks (`CHUNK_SIZE`) after a viewport-sized first paint |
| Scrollbox tail | Empty `<box height={tailSpace}>` after content so the last heading can scroll to the Fold |
| Tail reserve | Fold offset withheld from the tail so the last heading pins correctly |
| Real content height | `scrollHeight` minus the tail — the height used for scrollability and thumb-size math |
| Scroll marks | Search matches resolved to document-space `y` and painted onto scrollbar track rows (`TrackCell`) |

### Headings & overlay

Expand Down
2 changes: 1 addition & 1 deletion bench/scroll.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ for (const file of files) {
}

const renderables = countTree(setup.renderer.root)
const matches = findMatches(nodes, 'e').length
const matches = findMatches({ nodes: nodes, pattern: 'e', breakoutWidth: 80 }).length
if (asJson) {
console.log(
JSON.stringify({
Expand Down
4 changes: 2 additions & 2 deletions bench/stages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,5 +38,5 @@ time('buildTreeFromTokens', () => buildTreeFromTokens(tokens))
time('buildTree (lex+tree)', () => buildTree(body))
time('buildDocument (all)', () => buildDocument(md, file))
const { nodes } = buildDocument(md, file)
time("findMatches 'e'", () => findMatches(nodes, 'e'))
time("findMatches 'zzqx'", () => findMatches(nodes, 'zzqx'))
time("findMatches 'e'", () => findMatches({ nodes: nodes, pattern: 'e', breakoutWidth: 80 }))
time("findMatches 'zzqx'", () => findMatches({ nodes: nodes, pattern: 'zzqx', breakoutWidth: 80 }))
12 changes: 7 additions & 5 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,8 @@ Heading nodes carry an `id` (slug). The renderer for `Heading` emits a `<box id=
- `tocWidth = clamp(16, contentWidth + 3, floor(termWidth * 0.4))` (3 cols for the inner scrollbox's paddingX + a buffer). The TOC always auto-sizes to its visible content.
- `effectiveContentMax = contentWidthOverride ?? contentMaxWidth` — a session-only `contentWidthOverride` (set by dragging the content/TOC seam, see §9 TOC) lifts the configured cap when non-null; it is not persisted.
- `viewerColumnWidth = (hasToc ? termWidth - tocWidth : termWidth) - 2` (2 cols for the viewer scrollbar + paddingRight).
- `contentWidth = min(effectiveContentMax, viewerColumnWidth)` — exposed via context so block renderers can size to it. `effectiveContentMax` also flows to context as `contentMaxWidth`, so the Viewer's inner cap lifts with the drag.
- `contentWidth = min(effectiveContentMax, viewerColumnWidth)` — the reading width, exposed via context so block renderers can size to it. The Viewer's inner box is exactly `contentWidth + 1` (its paddingRight), so prose wraps at it.
- `breakoutWidth = isTocShown ? contentWidth : viewerColumnWidth` — the columns a rendered diagram may span. With no sidebar on the right, the Viewer (and the Overlay, Cover, and search bar with it) spans the whole terminal; prose stays at `contentWidth` and diagrams overflow the inner box into the free columns (`CodeBlock`'s `minWidth`).
- Memoises an `AppState` object into `AppStateContext` so descendants read state via `useAppState()`.
- Wires `useKeyboard` → `mapKey(ev, focus, { searchActive, helpOpen })` → `dispatch(action, commands)`. When `focus === 'search'`, `App` skips dispatch entirely — `SearchInput` owns its own `useKeyboard`.
- Runs two effects:
Expand All @@ -88,7 +89,7 @@ Layout (rendered tree):
<box flexDirection=column height=100%>
<box flexDirection=row flexGrow=1 overflow=hidden position=relative>
<StickyHeader /> ← absolute overlay; top/left 0; zIndex 10
<Viewer /> ← scrollbox, contentWidth + overhead
<Viewer /> ← scrollbox, breakoutWidth + overhead
{hasToc && <box width=tocWidth position=relative><Toc /><ResizeHandle /></box>}
{isResizing && <box absolute full-screen zIndex 1000/>} ← drag shield
</box>
Expand All @@ -115,6 +116,7 @@ Both are measured against **the content below the sticky overlay**, not the raw
- `search: SearchState | null` — `{ pattern, matches, index, dir }`.
- `viewerRef: RefObject<ScrollboxHandle>` — imperative scroll API.
- `contentWidth: number` — Viewer's inner content width after subtracting TOC, scrollbar, and padding; capped to `CONTENT_MAX_WIDTH` (100).
- `breakoutWidth: number` — columns a rendered diagram may span: `contentWidth` while the TOC is shown, the whole Viewer column otherwise. Diagram fitting (`codeText` in `src/app/lib/diagram-fit.ts`), the search Projection, and the seam's reflow key all read it.

`ScrollboxHandle` is the only place mutation crosses the React boundary. See [Imperative scroll](#imperative-scroll).

Expand Down Expand Up @@ -149,7 +151,7 @@ Pure key mapping, an effectful command layer, and a pure dispatcher between them

The viewer is a `<scrollbox>` wrapping `<NodeList>` plus a trailing `<box height={tailSpace}>` so the _last_ heading can still scroll to the top of the viewport (`tailSpace = max(0, termHeight - 1 - tailReserve)`, where `tailReserve` is the last heading's overlay height).

On mount it calls `createScrollboxHandle` (`src/app/lib/scrollbox-handle.ts`) with the raw `ScrollBoxRenderable` ref plus a `live` bag of getters (`tail`, `projections`, `isFullyMounted`, `contentWidth`, `mountedCount`, `docKey`); the seam owns the geometry port, the pending protocol and the scrollbar patches, and hands back `{ handle, onFrame, requestNotify, dispose }`. The main handle methods:
On mount it calls `createScrollboxHandle` (`src/app/lib/scrollbox-handle.ts`) with the raw `ScrollBoxRenderable` ref plus a `live` bag of getters (`tail`, `projections`, `isFullyMounted`, `contentWidth`, `breakoutWidth`, `mountedCount`, `docKey`); the seam owns the geometry port, the pending protocol and the scrollbar patches, and hands back `{ handle, onFrame, requestNotify, dispose }`. The main handle methods:

| Method | Implementation |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down Expand Up @@ -201,11 +203,11 @@ The scrollbox is wrapped in a `position=relative` box; `ScrollIndicators` render

Block boxes carry a stable id via `blockId(path)` (`src/app/lib/scroll-marks.ts`), keyed by the block's index path through the AST — the same convention headings already use via their slug `id`. `Match.blockElementId` (stamped during search) joins a match back to its block box, so `getScrollMarks` can resolve the block through the `BoxGeometry` port — `findChildren` / `collectTextBearersFor`, both one `collectById` walk over the renderable tree — and then locate the exact visual line within it via `plainText`/`lineInfo` (falling back to the block's own `y` if no text-bearing descendant is found).

`computeTrackCells` (pure, in `scroll-marks.ts`) maps each resolved mark's document-space `y` onto a track row proportionally (`round(y / scrollHeight * viewportHeight)`), independent of scroll position. It maps over the **full `scrollHeight`** (tail included) — the exact scale OpenTUI positions the thumb with (`thumbTop = scrollPosition / scrollHeight * trackHeight`), so a mark for a match lands inside the thumb once you navigate to it; `realContentHeight` (scrollHeight minus tail) is used only to suppress the overlay when the whole document already fits the viewport. Marks resolve on **reflow**, not on every scroll tick: `createMarkCache` (`src/app/lib/mark-cache.ts`) re-resolves when the seam's reflow key (`docKey:contentWidth:mountedCount`) changes — latched in `onFrame` so it always describes the laid-out state rather than the pending render — or when the search mints a new `matches` array, which the cache detects by identity. A key change also fires a notify, so `ScrollIndicators` re-reads on a resize or TOC toggle without waiting for a scroll. It reads the current layout off `viewerRef`, on a `setTimeout(…, 0)` after mount/search changes and on every scroll notification. When several marks land on the same row, the highest-priority kind wins (`activeMatch > match`), painted with `theme.scrollMarkActive` / `scrollMarkMatch`. With no active search or on a non-scrollable document (`contentHeight <= trackHeight`), `computeTrackCells` returns no cells and the overlay renders nothing.
`computeTrackCells` (pure, in `scroll-marks.ts`) maps each resolved mark's document-space `y` onto a track row proportionally (`round(y / scrollHeight * viewportHeight)`), independent of scroll position. It maps over the **full `scrollHeight`** (tail included) — the exact scale OpenTUI positions the thumb with (`thumbTop = scrollPosition / scrollHeight * trackHeight`), so a mark for a match lands inside the thumb once you navigate to it; `realContentHeight` (scrollHeight minus tail) is used only to suppress the overlay when the whole document already fits the viewport. Marks resolve on **reflow**, not on every scroll tick: `createMarkCache` (`src/app/lib/mark-cache.ts`) re-resolves when the seam's reflow key (`docKey:contentWidth:breakoutWidth:mountedCount`) changes — latched in `onFrame` so it always describes the laid-out state rather than the pending render — or when the search mints a new `matches` array, which the cache detects by identity. A key change also fires a notify, so `ScrollIndicators` re-reads on a resize or TOC toggle without waiting for a scroll. It reads the current layout off `viewerRef`, on a `setTimeout(…, 0)` after mount/search changes and on every scroll notification. When several marks land on the same row, the highest-priority kind wins (`activeMatch > match`), painted with `theme.scrollMarkActive` / `scrollMarkMatch`. With no active search or on a non-scrollable document (`contentHeight <= trackHeight`), `computeTrackCells` returns no cells and the overlay renders nothing.

## 8. Sticky overlay (`src/app/components/StickyHeader.tsx`)

An **absolute overlay** over the top of the viewer (VS Code "sticky scroll" model), not a chrome row. The box is `position=absolute` at `top/left 0` of the viewer's `position=relative` row container, sized to `contentWidth`, `zIndex 10`, on `theme.stickyBg`. Being out of Yoga's flow, it never changes the viewer's height — the rows paint _over_ the top content lines rather than pushing content down, so the overlay can grow from zero without the content region reflowing.
An **absolute overlay** over the top of the viewer (VS Code "sticky scroll" model), not a chrome row. The box is `position=absolute` at `top/left 0` of the viewer's `position=relative` row container, sized to `breakoutWidth + 1` (reaching the scrollbar), `zIndex 10`, on `theme.stickyBg`. Being out of Yoga's flow, it never changes the viewer's height — the rows paint _over_ the top content lines rather than pushing content down, so the overlay can grow from zero without the content region reflowing.

Content is `ancestorRows({ chain, visibleHeadingIds, hasH1, fileLabel })` (in `overlay-rows.ts`), where `chain = ancestorChain(toc, currentHeadingId)` is the root→current lineage:

Expand Down
14 changes: 13 additions & 1 deletion src/app/App.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,9 @@ export function App({
(isTocShown ? termWidth - tocWidth : termWidth) - VIEWER_OVERHEAD,
)
const contentWidth = Math.min(effectiveContentMax, viewerColumnWidth)
// With no sidebar on the right, diagrams may break out past the reading cap into
// the free columns; prose stays at `contentWidth`.
const breakoutWidth = isTocShown ? contentWidth : viewerColumnWidth

// Stable across nav; rebuilt only when the doc (toc/fileLabel) changes.
const fold = useMemo(() => createFold({ toc, fileLabel }), [toc, fileLabel])
Expand Down Expand Up @@ -292,6 +295,7 @@ export function App({
doc: { nodes, toc, headingIds, fileLabel },
fold,
viewportHeight: renderer.height,
breakoutWidth,
stateRef,
actions,
historyDepth: nav.historyDepth,
Expand All @@ -315,6 +319,7 @@ export function App({
// resize; depend on the value so `scrollPage`/`scrollHalf` rebuild with the
// new page size instead of the pre-resize one.
renderer.height,
breakoutWidth,
nav.historyDepth,
nav.follow,
nav.back,
Expand All @@ -331,6 +336,11 @@ export function App({
commands.syncFromScroll()
}, [commands])

// A width change can re-fit a diagram, which moves the match offsets inside it.
useEffect(() => {
commands.refreshSearch()
}, [breakoutWidth])

const headingState = useMemo<HeadingState>(
() => ({
currentHeadingId: view.currentHeadingId,
Expand All @@ -349,6 +359,7 @@ export function App({
tocCursorId: view.tocCursorId,
search: view.search,
contentWidth,
breakoutWidth,
contentMaxWidth: effectiveContentMax,
dir: nav.doc.dir,
historyDepth: nav.historyDepth,
Expand All @@ -364,6 +375,7 @@ export function App({
view.search,
view.helpVisible,
contentWidth,
breakoutWidth,
effectiveContentMax,
nav.doc.dir,
nav.historyDepth,
Expand Down Expand Up @@ -457,7 +469,7 @@ export function App({
position="absolute"
top={0}
left={0}
width={contentWidth + VIEWER_OVERHEAD}
width={breakoutWidth + VIEWER_OVERHEAD}
height="100%"
backgroundColor={theme.background}
zIndex={20}
Expand Down
1 change: 1 addition & 0 deletions src/app/RenderView.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ export function RenderView({
tocCursorId: null,
search: null,
contentWidth: Math.min(contentMaxWidth, width),
breakoutWidth: Math.min(contentMaxWidth, width),
contentMaxWidth,
dir: undefined,
historyDepth: 0,
Expand Down
Loading
Loading