# The Reader — research-grounded design for the WeaveLang explorer **Status:** design specification, ready to implement. **Scope:** the reading and navigation surface for a WeaveLang v0.3 document — RFCs, specifications, books, long technical documents, codebases. --- ## 0. How to read this document Three things govern everything below. **Evidence tiers.** Every claim carries a tier. **[P]** = read against the primary paper and verified digit-for-digit. **[S]** = read through a review or survey I trust, direction reliable, magnitudes not independently checked. **[J]** = judgment call with *no evidence*, stated as such. There are 23 **[J]** calls in this document and they are all labelled. If a decision is not labelled, it has a citation. **Citation hygiene.** Four citations that circulate in this project's research corpus are excluded because adversarial verification found them fabricated or misattributed, and one widely-quoted statistic set is excluded because its claimed source does not contain it. They are named in §18 so nobody re-imports them. Where a finding was corrected, this document uses the corrected version and says so. **The razor.** Among designs that decide the observed cases exactly, the weakest wins — the one committing least beyond the data. Generality is a property of the extension, not the form. Every mechanism below has been asked: *what unseen-but-plausible document does this silently mishandle, and what in today's data forces the commitment?* §15 is the ledger of what that question deleted. --- ## 1. What the evidence actually says ### 1.1 The four places the evidence contradicts the brief The brief asks for **"no more than 3 cognitive elements on screen"** and a **"strictly progressive"** reveal, in service of **"effortless exploration."** All three are qualified or refuted. Leading with the bad news. --- #### Contradiction 1 — "≤3 elements on screen" is folk HCI. The correct unit is elements that must be *bound together*. The rule's usual citation does not support it, its better citation is about something else, and the one controlled experiment that pitted narrow branching against broad found the narrow arm lost. - Miller (1956) described **two different limits** and said so explicitly: the span of absolute judgment (~2.5 bits, unidimensional stimuli) and the span of immediate memory (~7 chunks). Neither is a display limit. Miller called the number "only a pernicious, Pythagorean coincidence." **[P]** - Cowan (2001) puts capacity at 3–5 chunks (mean ~4, individual range 2–6) but is explicit that it is observable **only** under four boundary conditions, two of which are engineering interventions: information overload that limits chunks to individual items, and steps taken specifically to block recoding into larger chunks. A reading surface violates both by construction — the text stays visible, the reader can re-look, and the material connects to prior knowledge. Cowan's own position is that real-world comprehension is governed by *compound* estimates, for which he gives no number. **[P]** - Cowan's usable half, from the same section: an already-formed chunk **occupies one slot regardless of how much it stands for**, and chunk sizes can be grown without bound — while *forming* a new chunk from k parts requires all k parts in the focus of attention simultaneously, which is where ~4 bites. Retrieval is cheap; synthesis is expensive. **[P]** - Halford, Wilson & Phillips (1998) price capacity by **relational arity** — the number of dimensions that must co-vary in one decision — with the adult ceiling at quaternary. Halford, Baker, McCredden & Bain (2005) measured a significant decline in speed and accuracy from three-way to four-way, with five-way at chance. The limit is soft and degrades gradually (Andrews & Halford, 2002). Oberauer (2013) converges: the direct-access region holding temporary bindings has a scope of about four chunks. **[P/S]** - Sweller, van Merriënboer & Paas (2019) refuse to name an element count on principle: "Complexity or element interactivity depends on a combination of both the nature of the information and the knowledge of the person processing the information." A fixed constant is incoherent in CLT terms — the same three units are one element for an expert and nine for a novice. **[P]** - Larson & Czerwinski (1998), 512 documents in three structures: the **8-wide, 3-level tree was reliably slowest and left users most lost**; 16×32 was fastest; 32-wide was not reliably slower than 16. Their conclusion was that short-term memory was not the operative factor at all — label quality was. Their own published abstract is stricter about breadth than the popular retelling: a *medium* breadth/depth condition beat the broadest shallow structure overall. **[P]** - Cockburn, Gutwin & Greenberg (2007) supply the price of each dimension. Novice visual search is **linear**, calibrated at T = 0.08n + 0.30 seconds — and every reader of a given document is a novice *in that document*, so their expertise term is ≈ 0. Ten extra scannable rows cost ~0.8 s. Their multi-level equation charges every additional level a full decision time **plus a steering cost** — a fixed overhead that narrowing the branching factor does not reduce. **[P]** - Zaphiris, Shneiderman & Norman (2002) measured the penalty *scaling with depth*: expandable in-place index vs sequential drill-down, 39.6 vs 35.6 s at depth 2, 46.7 vs 34.9 at depth 3, **65.8 vs 41.1 at depth 4**. Menu type F(1,18)=13.91, p<.01; **Menu Type × Depth interaction F(2,18)=3.62, p<.05**. (Their preference reversal at depth 4 was *not* significant, F(5,34)=0.57 — it is widely quoted and should not be.) **[P]** **A hard 3-wide cap picks the losing arm of Larson & Czerwinski and mechanically forces the depth that Cockburn and Zaphiris both price as the expensive dimension.** **Corrected rule, in three parts:** > **(a) Binding budget ≤ 3, hard ceiling 4.** The number of things the reader must hold *simultaneously* to answer the question the screen poses. This binds at comparisons, at relation endpoints-plus-label, and at any set the reader must synthesise into one idea. > **(b) Scan set is uncapped.** Rows the reader ranks and rejects cost ~0.08 s each. They are governed by fit and by distraction cost, not by a number. > **(c) The root is broad; depth narrows.** Parush & Yuviler-Gavish (2004) found best performance with many choices on introductory screens and fewer at deeper levels. **[S]** Cowan's mechanism also gives the highest-leverage move, and it is not hiding: the way to reduce chunk count is to **make the relation among what is shown explicit**, because that is literally what converts N items into one chunk. --- #### Contradiction 2 — a collapse-by-default view must not be the reading surface. The exact interface proposed was built and it lost. Hornbæk & Frøkjær (2001; reading-pattern re-analysis 2003) built three readers for scientific documents — linear, overview+detail, and a fisheye that held headings and the first and last paragraph of each section at full size while diminishing the rest until clicked. 20 subjects, six IEEE journal papers, 106 hours of logged interaction. **[P]** | Measure | Linear | Fisheye | Overview+Detail | |---|---|---|---| | Essay grade (0–4) | 2.00 | 1.95 | **2.47** — sig. above both, F[2,32]=4.16, p<.05 | | Incidental learning (0–6) | 4.20 | **3.42** — sig. below both, F[2,32]=6.804, p<.005 | 4.58 | | Essay reading time | 44.4 min | **37.4 min** (16% faster, F[1,32]=8.13, p<.01) | 44.5 min | | Q&A time per question | **5.9 min** | — | 7.1 min (F[1,313]=8.33, p<.01) | | Answer quality | no significant interface effect | | Preferred by | **1** | **0** | **19** | Four corrections to the popular retelling, all of which matter here: 1. The fisheye was **not** significantly worse than plain linear text on essay grades. Its clean loss is on **incidental learning**, where it fell *below flat text*. So "staging beats flat text" is **not** validated by this experiment on comprehension measures. 2. The preference split is 19 overview+detail, **1 linear, 0 fisheye**. Nobody preferred the collapsing reader. 3. Overview+detail is **not** slower at reading (44.5 vs 44.4). It is slower at *question answering*, and the authors traced why: the overview pane invited continued exploration after a satisfactory answer was found. 4. The winning "overview" was **not page thumbnails**. It was a **semantic zoom** in which section and subsection headings were held at fixed readable size while the rest of each section was compressed (average 1:17), with a draggable field-of-view box. And the mechanism usually attached to this result — "a persistent index supports orientation and review, which is where integration happens" — is **refuted by the paper's own process data**: fewer subjects reviewed with overview+detail and spent a smaller proportion of time doing so, while the *fisheye* is the interface that invited the initial-orientation phase. This document therefore keeps a persistent ancestor spine but justifies it from Furnas residue and Nekrasovski guaranteed visibility, **not** from this mechanism story. The 2003 re-analysis adds the sharpest operational lesson. Visibility maps showed fisheye subjects **did expand** most collapsed sections. What differed was **dwell**: collapsed-then-expanded parts were visible 5% of total time versus 7% for overview+detail, F[1,32]=46.9, p<.001. **Expanding is not reading.** Collapse converts reading into skimming while producing a felt sense of coverage the dwell time does not support. --- #### Contradiction 3 — "strictly progressive" is the arm that repeatedly loses. Linear must be a shippable mode. - Linear was the **fastest** interface for question answering and beat the fisheye on incidental learning (Hornbæk & Frøkjær, 2001). **[P]** - Lee & Tedder (2003): recall was highest for **linear** text, and the linear advantage was **largest for low-working-memory readers**. **[S]** - McDonald & Stevenson (1996): linear readers opened 45.75 of 45 cards and estimated the document's size at 42.42 of 45 — the only condition that did not lose scope. **[P]** - Hochheiser & Shneiderman (1999): strictly sequential menus beat simultaneous ones **only** for novices on simple tasks (14.6 vs 21.3 s). As soon as the task required backtracking, simultaneous won (39.4 vs 33.5 s), and modelled proficient performance reversed every cell (up to ~40% in favour of simultaneous). Menu × task interaction F(2,36)=8.65, p=0.01. **[P]** - Rey et al. (2019), the segmenting meta-analysis (88 comparisons, N=7713): retention **d=0.32** [0.20, 0.43], transfer **d=0.36** [0.24, 0.48] — small-to-medium. Learning **time d=−0.92** [−1.64, −0.20]: segmented readers took **longer**. And in the cells that describe an explorer — readers who can re-read and can choose sequence — the **retention** benefit is not significant (can-repeat d=0.14 n.s.), while **transfer holds and is larger** (can-repeat d=0.55 vs cannot 0.29; can-reorder 0.46 vs cannot 0.45). Chunking under learner control buys transfer, not retention, and costs time. **[P]** - Rey et al.'s prior-knowledge moderator runs **opposite** to the naive expertise prediction and is non-monotonic: no prior knowledge d=0.29, **some prior knowledge d=−0.12 (n.s.)**, high prior knowledge d=0.73 (moderator Q=20.49, df=2, p<.001, retention only). The reader who is *hurt* by imposed segmentation is the **intermediate** one — the modal RFC reader — because the designer's cut can conflict with a half-formed schema. **[P]** **Consequences.** (a) Ship a real linear mode; it is the baseline the evidence most often favours and the control condition for every measurement. (b) Where the design segments, it must segment on the **document's own boundaries** — a boundary the author drew cannot conflict with a reader's partial schema the way an arbitrary N-rows cut can. (c) Addressing must bypass descent entirely. (d) Do not promise retention gains from progressive disclosure; measure transfer instead. --- #### Contradiction 4 — "effortless" is not on offer. "Not lost" is, and the thing that breaks is SCOPE, not accuracy. Two independent literatures agree that structured, self-paced, non-linear access is **slower**: Rey et al.'s learning-time d=−0.92, and McDonald & Stevenson's 75.63 → 86.19 → 100.62 s across linear, hierarchy and network. McDonald & Stevenson (1996), 45-card ~4500-word document, N=12 (four per condition — small; defend the direction, not any number): **[P]** | Measure (true value 45) | Linear | Hierarchy | Network | |---|---|---|---| | Cards opened | 45.75 | 37.25 | 28.75 | | **Estimated document size** | 42.42 | 35.85 | **25.10** (F(2,9)=4.76, p<.04) | | Q&A time (s) | 75.63 | 86.19 | 100.62 | | Disorientation (higher = better) | 64.75 | 27.5 | 18 | | **Answer accuracy** | **10/10** | **10/10** | **10/10** | Every subject answered every question correctly in every condition. **What broke was scope**: network readers believed a 45-unit document had 25 units and silently skipped a third of it. The authors attribute it to loss of *closure* — with no ordering axis there is no signal that you have reached the end. A tree knows its own subtree sizes. Surfacing them attacks the measured failure directly and costs nothing. ### 1.2 What the evidence does support - **Overview+detail is the safest shape for comprehension.** Cockburn, Karlson & Bederson (2008): "For particular tasks such as document comprehension, no alternative has been found more effective." Their verdict on distortion is hedged and should stay hedged: distortion-oriented displays are "likely to" impair relative spatial judgements and "can cause" target acquisition problems. **[P]** - **Selection is separable from presentation.** Furnas (2006) argues that elision, distortion, semantic zoom and aggregation all display the same fisheye-related subset and differ only in how they show it, opening "the possibility of non-visual fisheye-views." Card & Nation (2002) state the same modularity as a design goal. **[P/S]** - **Scent dominates layout.** Budiu, Pirolli & Fleetwood (2006), 11 participants, ~7000-node ontology: **browser had no significant effect** (t(10)=−1.23, p>.2); only scent did (t(10)=3.75, p<.05). One high-scent task took **65 s in the DOI browser vs 25 s in Explorer** because a semantically-similar node stayed visible as a distractor. Their conclusion: "cramming more information on the screen does not necessarily improve performance. Putting the right labels on the information that you display is a better way to speed up the task." **[P]** *Caveat this honestly: n=11 nulls are weakly powered. This is "the engine is not where the leverage is, on the best available evidence" — not a proof of no upside.* - **Navigability is a property of signage, formally.** Furnas (1997) proves navigation succeeds *iff* outlink information is everywhere well-matched: **NoMis** (if the signage says the target is this way, it is) plus **Coverage** (the target appears in some link's inferred to-set). His metaphor is "highway signage," not "label," and he requires residue to compress from O(n) per node to O(log n) or O(1). *He also notes real structures routinely fail this and remain usable, and nothing measures graceful degradation under probabilistic signage — so "a wrong summary provably breaks navigation" over-claims a theorem. It is a correctness defect in the formalism and an unmeasured risk in practice.* **[P]** - **Previews of destination content work.** Cress & Knabel (2003): link-preview readers learned more and navigated **backwards less**. Zhao, O'Shea & Fung (1994) same direction. Honest limit: Jonassen & Wang (1993) is a **null** — pop-ups describing the *relation between* nodes neither helped nor impaired recall. Two of three positive, and the null was the version that described relation rather than content. **[S]** - **Relation-type words help location.** Baron, Tague-Sutcliffe, Kinnucan & Carey (1996): accuracy at locating information under time limits was **highest** where "a one-word descriptor, such as 'definition' or 'contrast,' was placed in parentheses next to the linked text," with no difference between organizational-only and *unlabelled* content links. Type labels help **location**; content substance helps **learning**; neither has been shown to do the other's job. **[S]** - **Topic sentences equalise low- and high-span readers.** Budd, Whitney & Turley (1995): with topic sentences present, low- and high-working-memory readers performed **equally**; without them, low-span readers fell markedly behind. **[S]** - **Guaranteed visibility substitutes for an overview.** Nekrasovski et al. (2006), N=40, 5918-node tree: with marked nodes always rendered, the overview had **no effect on completion time** (F(1,36)=.184, p>.6) — while being rated significantly more enjoyable (F(1,36)=4.643, p<.05). Pan-and-zoom beat rubber-sheet focus+context, F(1,36)=13.477, p<.001, partial η²=.272. **[P]** - **Automatic folding computed from focus is the one clean fisheye win — and its failures localise.** Jakobsen & Hornbæk (2006), 16 participants: 49.8 s vs 55.2 s over a linear listing, F(1,14)=4.76, p=.047 on log-transformed times (qualified by a significant task × interface interaction, F(8,7)=9.57, p=.004), accuracy identical (91% vs 89%), strongly preferred (t=−5.229, p<.001), delocalization subtask ~51% faster. The **single significant loss** was finding a loop's closing brace (p=.015) — because the implementers rated closing braces uninteresting. The one satisfaction item it lost was *confusing–clear* (p<.04): readers could not tell why something was shown. **Every measured loss came from the relevance function mis-rating something the reader needed.** **[P]** - **A priori importance has never been shown to pay.** Jakobsen & Hornbæk (2011): "neither these evaluations of fisheye interfaces, nor other studies we can think of, are able to link performance benefits to a priori importance." In their Eclipse fisheye, lines shown because they were structurally important contributed nothing measurable; lines related to the focus **semantically** carried the entire result. **[P]** - **Preference is systematically decoupled from performance.** 19/20 preferred the interface slowest at question answering (Hornbæk & Frøkjær, 2001); 26/32 preferred an overview that cost them 22% (Hornbæk, Bederson & Plaisant, 2002); overviews rated more enjoyable with zero performance effect (Nekrasovski et al., 2006); animation rated most "exciting" (4.3 vs 3.1/3.0) while being ~82% slower for analysis and significantly less accurate (Robertson, Fernandez, Fisher, Lee & Stasko, 2008); users preferred the code-compression level they performed worse with (Cockburn & Smith, 2003, reported in Jakobsen & Hornbæk, 2011). **Do not validate this product with preference.** **[P/S]** --- ## 2. Corrected design principles Fourteen principles. Each is the weakest statement that decides the observed cases. **P1 — Budget bindings, not elements.** ≤3 things must be held together to answer the screen's question, hard ceiling 4; the scan set is uncapped and governed by fit. *(Cowan, 2001; Halford, Wilson & Phillips, 1998; Halford et al., 2005; Sweller, van Merriënboer & Paas, 2019; Cockburn, Gutwin & Greenberg, 2007)* **P2 — Selection is one computed function over containment distance; presentation is separate.** No per-`kind` table, no importance enum, no lexical salience, no a priori importance term. *(Furnas, 1986; Furnas, 2006; Jakobsen & Hornbæk, 2011; Card & Nation, 2002)* **P3 — DOI selects; authored order places.** The engine decides *which* units appear. Where they appear is the document's own order, always. *(Card & Nation, 2002 — fractional sibling offsets are a ranking device, not a rendering order; Kieras, 1980 and Budd et al., 1995 — first position is read as the topic)* **P4 — Collapse is navigation; it is never the reading surface.** A committed unit's `content` renders as continuous, uninterrupted prose at full size. *(Hornbæk & Frøkjær, 2001/2003)* **P5 — Verbatim material is never replaced by a gloss, and never gated behind one.** The summary is an addition the reader can decline, skippable by position. This requires no expertise model, which is why it is correct. *(McNamara, Kintsch, Songer & Kintsch, 1996; Kalyuga, Ayres, Chandler & Sweller, 2003; Mayer, 2023 — redundancy median d=0.10, reversing under learner control)* **P6 — Integration partners are co-present; a click is not a substitute for juxtaposition.** Comparison overrides the display budget. *(Schroeder & Cenkci, 2018, g=0.63 over 58 comparisons, n=2426; Blackwell & Green, 2003 — "although a single mouse click will take you to the next branch, the effect on comprehensibility is very worrying")* **P7 — Context is pushed, never offered.** Anything behind a decision to consult will not be consulted. *(Wright, Hull & Black, 1990)* **P8 — Signal uniformly within a peer set, or not at all.** Signalling half a text's topics made the **unsignalled** content recalled *more poorly than in a text with no signals at all*. Where the structure is simple, signal nothing. *(Lorch & Lorch, 1996, Experiments 1 and 3; Lorch, Lorch & Inman, 1993; aggregate effect real: Schneider, Beege, Nebel & Rey, 2018, retention g+=0.53; Alpizar, Adesope & Wong, 2020, d=0.38)* **P9 — Show extent and meaning; never show depth or topology.** Explicit structural markers reduced learning; position-in-hierarchy labels did nothing. *(Shapiro, 1998; McDonald & Stevenson, 1996 — scope is what breaks)* **P10 — Never reflow above the reading position.** Readers incidentally encode within-page location, and location accuracy correlates with substantive recall. Reflow is also the mechanism of the accordion depth penalty. *(Rothkopf, 1971; Zaphiris, Shneiderman & Norman, 2002)* **P11 — No view state derives from reader behaviour.** No adaptive thresholds, no visit-count prominence, no inferred expertise, no dwell-derived "read" state. Behavioural signals are developer metrics; they never reach the renderer. *(Kalyuga et al., 2003 — reversal moves within a session; Rey et al., 2019 — the moderator is non-monotonic and would route the intermediate reader wrongly; Hornbæk & Frøkjær, 2003 — readers distrusted an algorithm deciding what was readable)* **P12 — Animate only where a dimension is shared; cut everywhere else; one duration.** *(Heer & Robertson, 2007, §4.1.6 — without a shared dimension animation "may be ill-defined or misleadingly convey false relations," and they advocate static or dissolve transitions; Shanmugasundaram & Irani, 2008 — 0.25/0.5/1.0 s are statistically indistinguishable on task time; Chevalier, Dragicevic & Franconeri, 2014 — do not stagger)* **P13 — Every mis-selection costs one action.** Relevance will be wrong; the fold must be legible as a fold, its extent stated, and the escape always present. *(Jakobsen & Hornbæk, 2006 — every measured loss was a mis-rating; Tversky, Morrison & Bétrancourt, 2002 — user control is the active ingredient)* **P14 — No view may contain nothing to decide on, and no view may lie about its extent.** *(Jul & Furnas, 1998 [S]; Furnas, 1997 — Coverage; McDonald & Stevenson, 1996)* --- ## 3. What the data must carry Three additions to WeaveLang. Two are optional and degrade cleanly; one is needed. ```ts type Unit = { id: UnitId kind: string // free string, open set. The reader NEVER reads it for ranking. summary: string collapsed_summary?: string preview_summary?: string content?: string // VERBATIM material children: UnitId[] // authored order is significant parent?: UnitId // --- additions --- source_ref?: string // NEEDED. Verbatim from the source. OPAQUE — never parsed. derived_from?: Span[] // OPTIONAL. Provenance of summary phrases into content. } type Span = { field: 'summary'|'collapsed_summary'|'preview_summary', from: number, to: number, // offsets in that field content_from: number, content_to: number } // offsets in this unit's content ``` **`source_ref` — why it is needed and why it is opaque.** Experienced readers navigate their genre by predicting where a thing must live (Dillon, 1991) **[S]**. A generic tree of generated titles discards that and forces an expert to learn a document-specific structure. It is also the only string in the system that *cannot be wrong* — the Furnas NoMis condition is satisfied by construction for a string copied verbatim. It serves addressing, permalinks, citation, print, and the spine. It is a **single opaque string**. The reader displays it, matches it for `g`, and embeds it in permalinks and citations. It never parses it, never sorts by it, never validates its shape. `"4.2.1"`, `"§5.3"`, `"src/retry.ts:backoff"`, `"Act II, sc. 3"` and `"clause 14(b)(ii)"` are all the same type. One weak field replaces every genre-specific assumption the design would otherwise need. **`derived_from` — the provenance fork, decided.** Summary fidelity is the largest unmeasured risk in the product, and NoMis is the design's own correctness property. The obvious mitigation — point at a summary phrase, see the content it came from — requires provenance the schema does not have. Shipping a keybinding over a nonexistent field is the worst option. The call: **`derived_from` is optional, and the step-down affordance exists if and only if the field is present.** No new required field, no vapour keybinding, and the capability is a pure function of what the data carries. A cheaper cross-check that needs no schema at all ships unconditionally (§6.5). **What is NOT added.** No `head_term` field. The Surber (2001) constraint — concepts referred to with a *repeated* label are listed as main topics more often *regardless of actual importance*, so varied paraphrase across the three summary variants will make readers down-rank a unit **[S]** — is real and load-bearing. But it is a **pipeline authoring contract**, not a schema field and not a renderer-side lexical split: > **Pipeline contract SC-1.** The three summary variants of a unit must name that unit the same way. A validation pass flags units whose variants do not share their head noun phrase. A renderer-side split of the first noun phrase would be a lexical heuristic keyed to today's text shapes, and it could not enforce the constraint anyway. **Corpus shape.** A corpus is one or more roots under a virtual root. This is what makes a codebase work: cross-file relations are relations (handled as cuts and a trail), not containment distance, and the virtual root correctly makes cross-document units distant. No new machinery. --- ## 4. The selection engine ### 4.1 The function ``` DOI(x | F) = − d_tree(x, F) where d_tree(x, F) = min over f ∈ F of d_tree(x, f) ``` Containment edges only. No a priori importance term. No sibling offset. No threshold constant. **Why the a priori term is gone.** Furnas (1986) instantiates the tree case as API(x) = −d(x, root), D(x,y) = d(x,y), giving DOI = −(d(x,y) + d(x,root)). Work that out for a focus at depth D: - a child of the focus: depth D+1, distance 1 → **−D−2** - **any top-level unit that is not an ancestor of the focus**: depth 1, distance D+1 → **−D−2** They are equal for every D. At depth 4 in an 18-section RFC, the focus's own children are algebraically indistinguishable from all 18 top-level sections; at depth 9 they also tie with every sibling of every ancestor, a set that grows linearly with depth. That is the exact distractor set Budiu et al. measured as a 2.6× loss. The tie is not a deep-branch quirk — it is a general property of the instantiation. The additive form's other advertised prize also fails: the "spine falls out of the algebra" identity gives the entire lineage *plus the focus* one tied block (gap zero), so any top-N truncation can drop the focus from its own view. Nothing forces API = −depth. Jakobsen & Hornbæk (2011) report no study linking a performance benefit to a priori importance; Furnas's own footnote permits per-point API only with the clause usually dropped — "though often less efficient algorithms may result." So the term is deleted, and with it the false derivation and the hidden special cases the false derivation required. **What pure distance gives.** Parent and children at 1; siblings, grandparent and grandchildren at 2; a top-level stranger at depth 9 at distance 10. The neighbourhood is local, and it is local *identically* whether the branch is 9 deep or 2 deep — which is exactly the invariance WeaveLang's unbounded local depth demands and which −depth destroys. It also preserves the one positive property Budiu et al. found in DOI trees: their browser was **more forgiving of errors** (revisits 6.6 vs 8.15, t(10)=4.34, p<.005) because a wrong-but-nearby click still exposed the right neighbourhood. With pure distance the **parent is always at band 1**, so a wrong descent costs exactly one action to undo, from the view itself. **What is lost, and what replaces it.** The root drops out of the default view on a deep branch. That is correct behaviour, and the spine — an **explicit, separately justified commitment** — carries it. The spine is not derived from the function and this document does not pretend it is. It is justified by: Furnas (1997) residue (the reader needs evidence about what is off-screen); Nekrasovski et al. (2006) guaranteed visibility (which removed the measured benefit of a whole overview panel); Rogers & Chaparro (2003), whose one replicated breadcrumb benefit is a **more accurate mental model of structure** with no efficiency gain **[S]**; and Dillon (1991), because the spine carries `source_ref` — strings that cannot be wrong. **Why the sibling tie-break is gone.** Card & Nation's fractional offsets are ordered by distance from the focus-bearing sibling. In the pseudocode they are *inert* on the focus's own children (no child of the focus lies on a path to the focus, so the offset is zero for all of them — the 40-children case they were introduced for) and *destructive* on the focus's siblings, where they render §4.2.4 above §4.2.1 because the reader is near 4.2.4. Nothing forces reordering an authored sequence. DOI selects; authored order places (P3). Elision leaves a gap in the list with a bar in it — that *is* a fisheye, and an honest one. ### 4.2 Bands, peer sets, and rungs Two different groupings, deliberately named apart because conflating them is a real bug: - **Band k** = every unit at containment distance k from the nearest focus, *excluding the ancestor closure of F* (the spine owns those). Band 1 = children of foci. Band 2 = siblings of foci + grandchildren. Band 3 = uncles + nieces + great-grandchildren. And so on. - **Peer set** = the members of one band that share a parent. This is the unit of the Lorch uniformity constraint (P8) and the unit of demotion and elision. **Rung ladder** — four grades mapped onto the four authored fields, not onto a scaling function (Card & Nation, 2002, used a small fixed size ladder rather than continuous scaling; WeaveLang already authors the ladder): | Rung | Wants | Where | |---|---|---| | `CONTENT` | `content`, verbatim, continuous | every member of F | | `PREVIEW` | `preview_summary` | band 1 | | `COLLAPSED` | `collapsed_summary` | bands ≥ 2, and the spine | | `ELIDED` | an elision bar | what did not fit | **Fall-through, which is also the fail-loud path.** A rung the unit cannot fill falls through to the next field it *can*, and a fall-through is a **loud pipeline warning**, not a silent demotion: ``` PREVIEW : preview_summary → summary → collapsed_summary → first line of content (marked RAW) COLLAPSED : collapsed_summary → summary → preview_summary → first line of content (marked RAW) CONTENT : content → summary (marked NO-MATERIAL) nothing : source_ref ?? id, marked UNSUMMARISED ``` This resolves a contradiction between the source surfaces (fail loud *vs* fall back to raw content) by doing **both**: the reader always sees something real (P14), and the document header carries a warning count with a link to the affected units. A summary-less subtree is unreachable by signage under Furnas's Coverage condition; the reader must not pretend otherwise. ### 4.3 Pseudocode ```ts // ───────────────────────────────────────────────────────────────────────── // THE ENGINE. Knows: containment edges, authored order, which fields exist. // Does NOT know: kind, topic, the reader, relations, pixels, history. // ───────────────────────────────────────────────────────────────────────── type Focus = UnitId[] // reader-designated. Search hits and pins. |F| >= 1. // Ancestor closure of F. Owned by the spine, excluded from the band stream. function ancestorClosure(c: Corpus, F: Focus): Set { const s = new Set() for (const f of F) for (let u = parentOf(c, f); u; u = parentOf(c, u)) s.add(u) return s } // Multi-source BFS over containment edges. O(units visited), never O(corpus). // Cost is bounded by what the renderer pulls -- this is the whole point of // laziness. Heer & Card (2004) measured naive full traversal breaching the // 100 ms interaction threshold at ~30,000 nodes. function* bandStream(c: Corpus, F: Focus): Iterable { const spine = ancestorClosure(c, F) const seen = new Set(F) let frontier = [...F] let k = 0 yield { k: 0, units: [...F] } // the foci themselves while (frontier.length) { k += 1 const next: UnitId[] = [] for (const u of frontier) for (const nbr of [parentOf(c, u), ...childrenOf(c, u)]) { if (!nbr || seen.has(nbr)) continue seen.add(nbr) next.push(nbr) // still traversed, so we can reach past it } const emit = next.filter(u => !spine.has(u)) // spine renders separately if (emit.length) yield { k, units: emit } frontier = next if (k > MAX_WALK) return // safety valve only; see §14.1 } } // Peer sets preserve AUTHORED ORDER. DOI decided membership; order decides place. function peerSets(c: Corpus, band: Band): PeerSet[] { const byParent = groupBy(band.units, u => parentOf(c, u) ?? VIRTUAL_ROOT) return [...byParent].map(([p, us]) => ({ parent: p, members: us.sort((a, b) => ordinalOf(c, a) - ordinalOf(c, b)), // authored rung: band.k === 0 ? CONTENT : band.k === 1 ? PREVIEW : COLLAPSED })) } // ───────────────────────────────────────────────────────────────────────── // THE RENDERER pulls until full. There is no row budget, no screen-fraction // constant, no disinterest threshold, and no exact-N mode. // ───────────────────────────────────────────────────────────────────────── function renderView(c: Corpus, F: Focus, viewport: Box): View { const spine = renderSpine(c, ancestorClosure(c, F), viewport) // §5.2 let room = viewport.height - spine.height const out: RenderedPeerSet[] = [] for (const band of bandStream(c, F)) { for (const ps of peerSets(c, band)) { const full = measure(ps, ps.rung) if (full <= room) { out.push(place(ps, ps.rung)); room -= full; continue } // P8: a peer set is demoted WHOLE, never per-member. Mixed emphasis // among peers suppressed the unemphasised ones BELOW a no-signal // baseline (Lorch & Lorch 1996, Exp. 3). let rung = ps.rung while (rung > COLLAPSED && measure(ps, rung) > room) rung -= 1 if (measure(ps, rung) <= room) { out.push(place(ps, rung)); room -= measure(ps, rung) } else { // WINDOW + BARS, never truncation and never nothing (P14). // A contiguous window in authored order, anchored on the member // nearest a focus; exact numerals in the bars; bars re-centre on click. out.push(windowWithBars(ps, rung, room, anchor = nearestToFocus(ps, F))) room = 0 } if (room <= 0) return assemble(spine, out) } } // Card & Nation (2002) expand-to-fit, in its uniform form: if the stream is // exhausted and room remains, promote the lowest-numbered unpromoted peer // set by one rung. Whole set, or not at all. while (room > 0 && promoteOne(out, room)) { room = recompute(out, viewport) } return assemble(spine, out) } ``` ### 4.4 Properties, stated as invariants rather than proved as lemmas The design does not rest on a band-gap proof (the published one is false on the lineage). It rests on three enforced post-conditions, each with a test: - **INV-1 Ancestor closure.** For every rendered unit, every ancestor is present — in the spine or in the view. *Enforced by construction: the spine renders the closure.* - **INV-2 Focus presence.** Every member of F is rendered at `CONTENT` rung, or is represented in the tracked line (§5.4) if it did not fit. *Enforced by pulling band 0 first and by the tracked line.* - **INV-3 Placement.** Within any peer set, rendered members appear in authored order, with elision bars occupying the positions of the units they hide. *Enforced by `peerSets` and `windowWithBars`.* **Cost.** `bandStream` is a multi-source BFS: O(units visited), regardless of |F|. The renderer visits a bounded multiple of what fits. There is no whole-corpus pass, ever. **Reproducibility.** The view is a pure function of (corpus, F, viewport). A permalink encodes F and nothing else. There is no hysteresis, no history term, no dwell state, no adaptive threshold — so a shared link renders for the recipient exactly as it rendered for the sender (P11). **Degenerate shapes fall out.** A chain document (each unit one child) produces one-member peer sets, so the renderer simply keeps pulling bands until the viewport is full — a readable ladder down the chain, for free, with no special case. A flat document (2000 units at depth 1) produces one enormous peer set at band 2, which becomes a window with bars either side. See §14.1. --- ## 5. What is on screen ### 5.1 The frame ``` ┌───────────────────────────────────────────────────────────────┐ │ RFC 9110 › §4 Request Methods › §4.2 Common Methods │ SPINE │ (ancestor closure of F, authored order, collapsed_summary, │ sizes to │ source_ref shown, middle elided when long, NO depth numbers)│ contents ├───────────────────────────────────────────────────────────────┤ │ §4.2.1 Backoff algorithm 14 units │ │ ───────────────────────────────────────────────────────── │ │ Retry backoff is bounded so a failing peer cannot be │ FOCUS │ amplified into a thundering herd. ← parent collapsed_ │ dominant, │ summary, one line │ scrolls │ │ │ A client that receives a 503 response MUST wait at least │ │ the interval indicated in the Retry-After header before │ │ retrying. If no Retry-After header is present, the client │ │ MUST apply exponential backoff beginning at one second... │ │ ⟨conflicts with §7.3 — permits │ │ immediate retry on idempotent methods⟩│ │ [continuous verbatim prose, full size, one measure] │ ├───────────────────────────────────────────────────────────────┤ │ §4.2.1.1 Jitter Randomises the wait so clients do │ BAND 1 │ not resynchronise after an outage. │ children, │ §4.2.1.2 Caps The 30 s ceiling and how it interacts │ preview, │ with Retry-After. │ authored │ ⋯ §4.2.1.3 – §4.2.1.9 · 7 units │ order ├───────────────────────────────────────────────────────────────┤ │ tracked: §7.3 (came from) · 4 more search hits · §2.4 pinned │ TRACKED └───────────────────────────────────────────────────────────────┘ ``` **No fixed proportions.** There is no 70/30, no 15/70/15. Every region sizes to its contents and collapses to zero when empty: a focused leaf has no band region; a focused root has no spine; a document with one top-level unit has a one-row spine. The published 70/30 figure is from a paper with **no user study** that says so on principle, and it partitions free-layout vs compression+aggregation — a different partition from spine/focus/band. It is not imported. ### 5.2 The spine - Contents: the **ancestor closure of F**, in authored order, indented. With |F| = 1 this is a breadcrumb chain; with a search hit set it is the set of containing sections. One rule, two useful behaviours. - Each row carries the unit's `source_ref` (if present) and its `collapsed_summary`. - **No depth numbers, no level indicators, no "4 of 7."** Shapiro (1998) found readers of a hypertext annotated with markers such as "3rd level" and up-arrows to superordinate topics scored **lower on essays** than readers of the identical hypertext without them, and separately found position-in-hierarchy labels had no effect on learning **[S]**. WeaveLang depth is local and relative, so a depth number would also be uninterpretable across branches. - When the closure does not fit: the **middle** collapses to one elision bar carrying an exact count; root and the nearest ancestors survive. This is deterministic — a one-level move changes the spine by one row, reversibly. **There is no hysteresis**, because there is no size-cap oscillation to damp once the elision point is a pure function of what fits. - Type role: reduced weight, no sentence punctuation, deliberately **not skimmable as running prose**. Cockburn & Smith (2003), reported in Jakobsen & Hornbæk (2011) **[S]**: readers *preferred* the "just legible" compression level and *performed better* with the illegible one — legible-but-small context invites reading; unreadable context is used as structure, which is what the task needed. - The spine is **motionless while reading** and never animated. Salience captures attention away from thematic content (Tversky, Morrison & Bétrancourt, 2002, citing Lowe, 1999). ### 5.3 The focus region Ordered top to bottom: (1) the focus's `source_ref` and its **extent numerals**; (2) the immediate parent's `collapsed_summary`, one sentence, prose weight; (3) the focus's own `summary`, one short paragraph; (4) `content`, verbatim and continuous. - **The parent gloss and the unit's own summary sit above the content and are skippable by position.** Kalyuga et al. (2003): "Redundant information is frequently difficult to ignore" — the expert's cost comes from *forced co-presence*, not from availability. An expert who scrolls past a fixed, learnable slot pays once; an expert who must expand something to reach the clause pays every time. This needs no expertise model (P5, P11). - **The parent gloss is a topic sentence and is not optional.** Budd et al. (1995) **[S]**. - **First position is a semantic commitment, not a layout choice.** Readers assume the first thing is the topic (Kieras, 1980), and initial sentences cost 500–1000 ms more to read (Budd et al., 1995) **[S]**. So slot 1 is the unit's own identity and extent, and slot 2 is its context — never a badge, never a depth marker. - **Extent, not coverage.** "14 units · 9 leaves" is a pure function of the tree. There is **no per-reader "seen" state**: the design forbids the only cheap way to compute it (expansion is not reading — Hornbæk & Frøkjær, 2003), a dwell threshold does not exist anywhere in the literature, and reader-state would make the same document render differently over time and break link reproducibility. McDonald & Stevenson measured **size estimation**, and extent is exactly what fixes size estimation. ### 5.4 The tracked line One persistent row listing, by `source_ref`, everything the reader is currently tracking: members of F not currently rendered, remaining search hits, pinned units, and the origin of the last relation traversal. Every entry is a control. This is the **textual** form of Nekrasovski et al.'s guaranteed visibility. Their Halo-style peripheral arcs encode *direction and distance* to off-screen items — which requires a geometry. A re-rooting list of text units has no bearing to §7.3 and no distance to it, so the arc is imported without its precondition. What actually removed the need for their overview is that **the tracked item never disappears**, and a text list delivers that with no geometry, and delivers it identically to a screen reader (§12). *Honest limit: in Nekrasovski's study the marked nodes* were *the task. In a document nothing is marked by default, so this mechanism has no default content. It is reasonable and untested.* --- ## 6. The leaf: verbatim material ### 6.1 One continuous scroll, no internal pagination `content` renders as one uninterrupted scroll surface. No pagination, no cards, no accordion over prose. Length is bounded by the document, not by the viewport. *(P4; Rey et al., 2019 — segmenting under learner control buys transfer, not retention, and costs time; Larson & Czerwinski, 1998; Zaphiris et al., 2002)* ### 6.2 Lens or list: one computable predicate replaces the code/prose split The tempting rule — "fold code, scroll prose" — is a `kind` enum with the enum filed off. "Machine-verifiable and self-naming" is not computable from WeaveLang data, and in practice becomes `kind.startsWith("software.")`. > **The predicate.** Children are a **lens over the parent's content** iff every child's `content` is a contiguous subrange of the parent's `content`. Otherwise they are a **list**. One string containment test, no domain knowledge. It folds code (a body contains its closures), numbered normative clauses inside a section body, statutes, contracts, and anthologies whose chapters are spans. It refuses to fold a prose section whose children carry summaries rather than spans. It generalises to formats nobody has considered. It also answers a question none of the source designs answered: **what happens when a unit has three pages of content and eight children?** - **Lens case:** there is no separate child band at all. Children are marks in the scroll — foldable regions, in place. Nothing is off the bottom because nothing is duplicated. - **List case:** the child band is a **fixed region that does not scroll with the content**. The reader scrolls prose within the focus region; the band stays put. And it resolves the duplication ambiguity: in the lens case, the parent's content already contains the children's text, so children are never rendered twice. ### 6.3 Folding, in the lens case only Folds are computed from the focus (P2), never managed by hand as the default. This is what separated the one clean fisheye win from the accordion loss (Jakobsen & Hornbæk, 2006 vs Zaphiris et al., 2002). Four rules follow from that study's *failures*: 1. **A fold is legible as a fold.** It states what kind of region it is, in the region's own authored words, and its extent in lines. The one satisfaction item the winning fisheye lost was *confusing–clear* — readers could not tell why something was shown. 2. **Every fold is individually overridable in one action**, and `t` opens everything in the current scope. A mis-rated region costs one keystroke, not a search (P13). 3. **Uniformity within a peer level** (P8): either every hidden region at one level carries a one-line gloss, or none does. 4. **Sparsity**: if the body's structure is simple — few regions, shallow nesting — **do not gloss at all**. Lorch & Lorch (1996), Experiment 1: with a simple topic structure, signalling had *no effect*. Doing nothing here is evidence-based. **The default state of the unit the reader came for is open.** Folding is for material being passed over, not material being read. Signals trade breadth for depth — more topics remembered, less recalled about each (Lorch, Lorch & Inman, 1993) — which is a good trade at map altitude and a bad one at the leaf. *One correction to the record: Cockburn & Smith (2003) did* not *find manual fold management to be the limiting problem; they found elision improved navigation. It was Jakobsen & Hornbæk who raised manual management as an open question and noted C&S's tasks left it unanswered. **There is no head-to-head evidence that automatic beats manual folding.** The automatic default plus universal override is a* **[J]** *made on the ground that every measured loss in the winning study was a mis-rating, so the override is what must be cheap.* ### 6.4 Fidelity - **Byte-exact.** No paraphrase, no normalisation, no re-wrapping of author line breaks, no smart quotes, no whitespace collapsing, no renumbering, no reordering. Overlays (highlight, annotation, line numbers) are non-destructive. - **Never soft-wrap code, tables, or diagrams.** They scroll horizontally in their own container; the page body never scrolls horizontally. - **Copy from a folded region yields the verbatim content, never the gloss.** This decides a real correctness question for normative documents and it must be stated, not left to the clipboard implementation. - **Never shrink prose to signal low interest.** Hornbæk & Frøkjær's fisheye rendered documents at 25% of linear size and lost 0.78–1.16 incidental-learning answers. Demotion is by **substitution and removal**, never by scale. Whether substitution escapes the shrink penalty is **the one place this design is outside the tested envelope** — see E3 in §16. ### 6.5 Auditing a summary Two affordances, one unconditional and one capability-gated: - **Unconditional (`s` with no `derived_from`)**: show the first lines of the unit's `content` beside the summary that describes it. Requires no schema, catches gross mismatch, costs one keystroke. - **Gated (`s` with `derived_from`)**: point at a phrase in any summary and highlight the exact span of `content` it was derived from. Present iff the field is present; the key does nothing visible otherwise, and the help sheet says why. The step-down idea is borrowed from Victor (2011), which has **no user study, no comparison condition and no measured outcome**. The empirical justification is Furnas's NoMis condition, not Victor. --- ## 7. Navigation, key bindings, transitions ### 7.1 The primitive is re-rooting, and its evidence is thinner than usually claimed Entering a unit **re-roots**: the chosen unit becomes the focus, its ancestors collapse into the spine, its children become band 1. Document depth stays unbounded; the *view* never nests. Grounds: Zaphiris et al. (2002) — the winning *sequential* arm replaced the view; Heer & Card (2004) — for "largely textual data" excessive scaling "can be undesirable... The solution implemented in our current work is to automatically translate the view," with a breadcrumb of elided ancestors (note their hedge: scaling is retained, this is what they implemented, not a law); Nielsen (2006) — "Designs that go beyond 2 disclosure levels typically have low usability because users often get lost," which is a practitioner prior with **no cited experiment and no numbers in the article**. **Honest caveat.** Zaphiris's sequential condition replaced the view *entirely*. This design keeps a spine and a band, which is structurally closer to the *expandable* condition that lost. **Re-rooting as a navigation primitive has never been evaluated.** It is the most promising untested idea here and it is E4 in §16. The design does not state a "visible depth = 2" constant, because no evidence produces the integer; visible depth is whatever the stream returns before the viewport fills. ### 7.2 Key bindings Twenty-two bindings. No numeric shortcuts (a position index competes with `source_ref` on the same row and is unstable if the band changes). No peek (a third disclosure state, in a design with two, producing two ways to see a child's content whose results differ — and entering costs 300 ms and reverses with one keystroke). **Selection — instant, silent, no view change** | Key | Action | |---|---| | `↓` `j` | Next rendered row | | `↑` `k` | Previous rendered row | | `Shift+↓` `Shift+↑` | Last / first row of the current peer set | **Movement — animated, one step** | Key | Action | |---|---| | `→` `Enter` | Enter the selected unit (re-root inward) | | `←` | Out to parent (re-root outward) | | `Home` | Out to root of the current document | | `]` `[` | Next / previous unit in **authored document order**, crossing branches | `[` and `]` are the zero-decision default path. Every link is a decision that costs independently of its destination: Miall & Dobson (2001) gave readers three embedded links that all led to the *same* screen the linear group reached by clicking "Next," and the fake-choice readers still reported more confusion and spent more time per node **[S]**. *Genre caveat the review itself insists on: modernist literary short stories, one study, transfer to RFCs unestablished.* **Reading and material** | Key | Action | |---|---| | `PageDown` `PageUp` | Scroll focus content | | `v` | Toggle **linear mode** for the focus subtree (§10) | | `t` | Reveal everything hidden in the current scope — folds and elisions | | `s` | Step down from a summary phrase to its material (§6.5) | | `c` | Copy citation — `source_ref` + unit id + any selected verbatim quote | | `e` | Export / print the linear rendering (§10) | **Foci — the only view state** | Key | Action | |---|---| | `m` | Pin / unpin the selected unit (add to / remove from F) | | `Shift+Enter` | Open the selected unit as an **additional** focus, beside the current one | | `Esc` | Clear F back to the pre-search focus; cancel the topmost transient | **Addressing** | Key | Action | |---|---| | `/` | Search — sets F to the hit set (§9) | | `n` `N` | Move the reading position to the next / previous member of F in authored order | | `g` | Go to a `source_ref` or unit id | | `Ctrl+K` | Command palette — superset of `/` and `g` | **Relations and trail** | Key | Action | |---|---| | `r` | Open the relation list for the focus | | `Enter` in the list | Traverse — a **cut**, pushing onto the trail | | `h` | Show the **trail**: the ordered path of traversals, by `source_ref` | | `Backspace` `Alt+←` / `Alt+→` | Back / forward along the trail | **Repair** | Key | Action | |---|---| | `u` | Undo the last view-state change (`t`, a fold override, a pin) | | `?` | Binding sheet | `u` exists because Tversky et al. (2002) locate the active ingredient in user control — stop, reverse, re-inspect — and because `t` on a 3000-child peer set is otherwise unrecoverable. ### 7.3 Transitions One duration: **300 ms**. Shanmugasundaram & Irani (2008) found task time fell from 50.688 s (instant) to 35.6–36.9 s with animation — a **~29% reduction, not a halving** — with **no significant difference among 0.25 / 0.5 / 1.0 s** (p = .863, .637, .737) and **no error benefit** (F(3,45)=0.705, p=.554; their abstract's "fewer errors" claim is contradicted by their own body statistics). The transition's job is to exist. 300 ms is a **[J]** inside an evidentially flat bracket, biased against spending reading time on watching. Card & Nation's 0.5–1.0 s is the alternative and is not distinguishable on the data. | Move | Animated? | What moves | |---|---|---| | Enter (child → focus) | Yes, 300 ms | The chosen row grows into the focus slot; the old focus collapses into the spine. Siblings fade as **one undifferentiated group**. | | Out (focus → parent) | Yes, 300 ms | Exact inverse | | Row selection | **No** | Highlight only | | Relation traversal | **No — cut** | — | | Search / address jump | **No — cut** | — | | Back / forward | **No — cut** | — | | Linear-mode toggle | **No — cut** | — | | Content arriving | **Never animated** | Appears at once, after motion settles | **Rules with citations:** - **At most two separately identified movers.** Chevalier et al. (2014) summarise tracking at 7–8 objects under controlled conditions, 3–4 generally, and identity tracking "strikingly hard, with capacities as low as 1–2 objects." - **Never stagger.** Chevalier et al. tested per-element start delays across 4,160 trials, pre-selecting the 0.01% most favourable of 10,000 generated tasks, and still bounded the accuracy gain at ≤0.15: "far from staggering." Staggering destroys the common-motion grouping that makes animation work. *(Heer & Robertson endorsed* staging *— splitting a transition by type of change — not staggering, so nothing is being overturned. This design uses a single direct transition with neither.)* - **Design against target crowding, not against a count.** Franconeri, Jonathan & Scimeca (2010) **[S]** found tracking limited by object *spacing*, not by speed, time or capacity; Chevalier et al. name **target crowding** as the metric that most rewards attention. Concretely: no other element crosses the moving row's path. A list preserves spacing by construction, which is another reason not to re-lay-out spatially. - **Cut when no dimension is shared.** Heer & Robertson (2007) §4.1.6. Parent↔child share containment; a rebuttal edge across the tree shares nothing. A camera flight to a cross-referenced clause asserts "this clause became that one." - **Never rotate, never re-lay-out the hierarchy spatially.** Cockburn & McKenzie (2000): 9.9 s vs 6.7 s for a plain tree browser (F(1,11)=71.98, p<.001), and the **revisit** task — return to a previously visited file — was 12.5 s vs 5.6 s, more than twice as slow (t(11)=4.4, p<.01). Returning is exactly what a spec reader does most. - **Content changes are discrete post-transition events.** Simons & Ambinder (2005) list gradual change over several seconds as a standard change-blindness mask, and note detection requires encoding the pre-change state and then *explicitly comparing* it with the post-change state. A search highlight appears ~150 ms after the frame settles, never as part of a fade. If the reader must notice a difference between two units, **show both simultaneously** — do not ask them to compare across a transition from memory. - **`prefers-reduced-motion` disables all motion and the interface is fully usable without it.** Cockburn et al. (2008) note there is no evidence animation aids task-completion time. Nothing here depends on it, and every measurement runs in both modes. --- ## 8. Entry: the first ten seconds with an unfamiliar 200-page standard ``` ┌───────────────────────────────────────────────────────────────┐ │ RFC 9110 │ ← source_ref, verbatim │ Defines the semantics of HTTP: requests, responses, methods, │ ← the ROOT UNIT'S OWN │ status codes and header fields, independent of any version. │ summary, slot 1 │ │ │ 18 top-level units · 1,204 units · 963 leaves │ ← EXTENT, pure function │ ⚠ 3 units have no summary │ ← fail-loud, if any │ │ │ [ search or jump to a section ] (focused) │ ← the expert's door ├───────────────────────────────────────────────────────────────┤ │ 1 Introduction Scope, conformance, and how to read the │ │ requirement language. │ │ 2 Conformance What MUST and SHOULD oblige, and how to │ │ handle errors in received messages. │ │ 3 Terminology Client, server, intermediary, cache, ... │ │ … all 18, each one row of preview_summary │ └───────────────────────────────────────────────────────────────┘ ``` | Element | Why it is that | |---|---| | Root unit's own `summary` in slot 1 | Whatever renders first is read as the topic (Kieras, 1980; Budd et al., 1995) **[S]** | | `source_ref` verbatim | Dillon (1991) — the genre schema experts navigate by **[S]** | | Extent = units + leaves | McDonald & Stevenson (1996) — scope estimation is the measured failure. Counts the tree knows for free. | | **All 18** top-level units, not 3 | Larson & Czerwinski (1998); Parush & Yuviler-Gavish (2004) **[S]** | | One `preview_summary` row each | Cress & Knabel (2003) **[S]**; Budiu et al. (2006) | | Search focused on load | Kalyuga et al. (2003) — the expert's path must not pass through the gloss | | No modal, no expertise question, no tour | Kalyuga et al. (2003) — reversal moves within a session; Rey et al. (2019) — the moderator is non-monotonic | | No animation on first paint | Tversky et al. (2002) | **Not on this screen:** a normative-requirement count (that requires MUST/SHALL detection — the exact lexical salience this design rejects); a page count (a tree does not have one); a genre-specific purpose extraction. **This screen breaks ≤3 on purpose.** Eighteen scannable rows cost ~1.4 s of visual search under Cockburn et al.'s calibrated model; forcing them into a 3-wide tree adds ~2 levels, each costing a decision plus a steering term, and lands on the arm of Larson & Czerwinski that was slowest and left users most lost. The binding budget is untouched: the reader binds one thing here — the section they want. --- ## 9. The reference use case: reach an arbitrary clause without descending This is not a fast lane through the same architecture. **The map must not be on the lookup path.** Hornbæk & Frøkjær measured overview+detail ~20% slower for question answering and traced it precisely: subjects kept exploring after a satisfactory answer was found, and 26% of further explorations began at the overview pane. Plain linear was the fastest interface for question answering. Delgado, Vargas, Ackerman & Salmerón (2018) add that the print-over-screen disadvantage for informational text is **larger under time constraints** (g = −.26) than self-paced (g = −.09; QB = 4.12, p = .04; 54 studies, 171,055 participants) — and lookup is the time-pressured case. Keep it austere. ### 9.1 Search is not a separate mechanism: it sets F ``` / → matches over content and the three summary fields → F := the hit set ``` That is the whole design. Everything else follows from machinery that already exists: - **|F| = 1** — the view is that clause, open, verbatim, with its ancestors in the spine. **Zero drill steps.** - **|F| = many** — every hit renders at `CONTENT` rung in authored order; the spine is the ancestor closure, i.e. the sections that contain hits; overflow goes to the tracked line. This is exactly what "find every MUST in §4" needs, and it required no result-list component, no filter slider and no new mode. - `n` / `N` move the reading position among members of F, pulling more as needed. They do not mutate F. - `Esc` clears F back to the pre-search focus. **Escape is always safe**; the trail holds the origin. Pinning (`m`) and compare (`Shift+Enter`) also just add to F. **F is the only view state** besides the trail, per-unit fold overrides, and the linear-mode flag. This also deletes "arrival mode" — the two-case table that made the same unit render differently depending on how the reader reached it, and therefore made a shared permalink show the recipient something the sender never saw. There is one code path. *Cost note: min-distance over |F| foci is a multi-source BFS, O(units visited) — no blow-up with hit-set size.* ### 9.2 Addressing - `g` accepts a `source_ref` or a unit id, matched as an opaque string. It never parses the reference. - Every unit has a permalink encoding F. Nothing else. Reproducible by construction. - Remaining hits stay in the tracked line after arrival — the reader never re-issues a search to find hit 4 of 9. - A zero-result or ambiguous search returns the nearest ancestors that *do* contain candidate material, never a blank screen (P14). - **Compare is one keystroke from a hit** (`Shift+Enter`), because the reference task is usually "does §4.2 contradict §7.1?" — a comparison, and comparisons must be juxtaposed (P6). - **Citation is one keystroke** (`c`): `source_ref`, unit id, and any selected verbatim quote. ### 9.3 One deliberate asymmetry Signal heavily at map altitude; **strip signalling at the leaf**. Once the reader has committed to a unit, `content` is plain continuous text with minimal chrome. Signals trade substance for shape (Lorch, Lorch & Inman, 1993), and the leaf is where that trade turns against you — and where the reference reader needs the exact words. --- ## 10. Linear mode, export, print, and the trail ### 10.1 Linear mode (`v`) is a first-class mode, not a fallback Renders the focus subtree as **continuous verbatim content in authored order**: every unit, `source_ref` as its heading, `content` unbroken, no folds, no bands, no elision. Summaries are suppressed by default and available as a one-line prefix per unit via a toggle. Why it is first class: 1. It is the arm that repeatedly won (§1.1, Contradiction 3). 2. It is the **control condition** for every measurement in §16. Three of the four source designs had no control. 3. It is the reading-to-learn path. Dillon & Gabbard (1998) conclude hypermedia's genuine advantage is confined to "tasks which require rapid searching through lengthy or multiple information resources and where data manipulation and comparison is necessary" — a reference advantage, not a comprehension one **[S]**. 4. It is the export and print renderer, so there is one implementation. 5. It is the answer for degenerate chain documents (§14.1). **No timers, no auto-advance, no estimated-read-time, no progress nagging.** Self-paced reading cuts the screen penalty by roughly two thirds (Delgado et al., 2018). ### 10.2 Export and print (`e`) The linear rendering, serialised. Deterministic, containing no view state: - every unit of the exported subtree, in authored order; - `source_ref` as headings, unmodified; - `content` byte-exact; - summaries included or excluded by an explicit flag, never silently; - relations as endnotes carrying `kind`, `label`, and both endpoints' `source_ref`; - units that fell through the rung ladder marked `UNSUMMARISED` in the output. Collapsed content that cannot print is a defect. A spec reader will print, diff, and quote. ### 10.3 The trail (`h`) — cross-reference chains Blackwell & Green (2003) define hidden dependencies as the case where "one entity cites another entity, **which in turn cites a third**." A single-hop design does not serve that. The trail is the ordered list of traversals — relation jumps, search landings, address jumps — rendered by `source_ref`, with the relation `kind` between consecutive entries: ``` §4.2.1 —conflicts-with→ §7.3 —depends-on→ §2.4 —defines→ §2.4.1 ``` Any entry is one click away. Back/forward walk it. Cycles are fine: it is a list, not a graph traversal. --- ## 11. Relations ### 11.1 What the evidence forces **Against putting them in the metric or in ambient navigation:** - DeStefano & LeFevre (2007): "the effect of adding semantic links was more consistently negative. In four of the five studies, navigation was slower in hypertexts that included semantic links than in those that were strictly hierarchical," and "semantic links may have obscured the hierarchical nature of the texts." *(The review is internally inconsistent here — elsewhere it lists two of those four as nulls. Reporting the tension rather than resolving it.)* **[S]** - Budiu et al. (2006): the 2.6× loss came from a semantically similar *visible* node. Relation edges are a purpose-built channel for exactly that distractor. - Heer & Card (2004) exploit convexity of the fisheye distribution to bound DOI computation to visible nodes; relation edges destroy convexity, degrading the bound to visible nodes *plus* the nodes linking visible regions. - Niederhauser et al. (2000) found heavier users of a cross-jump feature scored lower — **correlational, self-selected**, and the review states the load was neither manipulated nor measured **[S]**. **For making them first class in the reading surface:** - Blackwell & Green (2003): burying information in encapsulations reduces visibility, and such systems "are to be deprecated for exploratory activities." - Halford et al. (1998): conceptual chunking reduces dimensionality "at the cost of making some relational information inaccessible" — which is precisely what collapsing a unit does to its relations. - Kintsch & Rawson (2005): the situation model is built by integrating text with prior knowledge and the reader's goals. Causation, dependency and rebuttal are **situation-model links**, not textbase links — and a tree of summaries is a machine for manufacturing an excellent textbase with no situation model, which standard "did they get it?" checks will not catch. ### 11.2 The design 1. **Relations are not in `d_tree`.** Traversing one is a **focus change**, not a distance. Same function, no new metric, no lost cost bound. 2. **In-place annotation.** At the span it attaches to, a relation renders as a marker carrying the **verbatim `kind` string** (one word — Baron et al., 1996, won on location) and the **destination's `preview_summary`** on demand (Cress & Knabel, 2003, won on learning). Both, because neither does the other's job. 3. **No badge enum.** A collapsed unit shows the **numeral count** of its relations. There is no mapping from an open `kind` vocabulary onto a fixed icon set — that is the textbook over-commitment, and DeStefano & LeFevre warn that proliferating link-type icons themselves add load. A numeral is read, not counted, and it generalises to any vocabulary. 4. **Traversal is a cut, and it pushes the trail** (§10.3). No camera flight (P12). 5. **Rendered automatically on arrival at a unit** (P7). Not behind a hover, not behind a toggle. 6. **Two shipped metrics** from Yang, Burnett, DeKoven & Zloof (1997) via Blackwell & Green (2003): - **D1** = (relations of the focused unit explicitly depicted) / (relations it has), per view. - **D2** = worst-case steps from any unit to the display of its dependency information. **D2 must be 1 (`r`) at every depth and for every input modality.** A design where D2 grows with depth is broken by construction. 7. **Integrity.** A dangling `to` renders with its `kind` and `label` and an explicit *unresolved target* marker — never a failed view. Self-relations render. Cycles are fine. A unit with 200 relations gets a windowed list with exact numerals, like any peer set. --- ## 12. Accessibility This section changes the structure; it is not a retrofit. ### 12.1 The core problem the source designs did not solve The design's central adaptation move — generated material is **skippable by position**, so an expert who never looks at a summary pays nothing (P5) — is a *visual* skip. A screen-reader user traverses linearly and cannot skip past a gloss to reach the clause without hearing it. For AT users, the Kalyuga cost the design claims to have removed is fully present. **The fix, which changes the DOM:** the gloss and the material are **sibling regions**, never nested, and the **first focusable element inside a unit is a "skip to material" control** that moves focus to the start of `content`. That gives AT users positional-skip parity with a sighted reader's eye. It is one link, and it is the mechanism, not a courtesy. ### 12.2 Structure - **Nested disclosures, not `role="tree"`.** The W3C WAI-ARIA APG's guidance is that the disclosure pattern suits most sites because few need the extra keyboard support a tree requires; a composite tree seizes arrow keys, moves focus via `aria-activedescendant`, and depends on `aria-level` / `aria-setsize` / `aria-posinset` values browsers are permitted to omit. Kiss (2013) documented screen readers announcing every child node whether expanded or not, VoiceOver disclosure commands not operating on the tree, and cursor desynchronisation under roaming tabindex. *That testing is from 2013 and some combinations are dead; re-test the current APG examples before freezing.* Roselli (2020) supports the narrower point that the APG disclosure pattern works well across platforms — he does not discuss trees, and must not be cited for the comparison. - **Elided units are genuinely removed from the accessibility tree**, not merely visually diminished — a sighted user's "faded" is a screen-reader user's "read in full at normal priority," which inverts the design. Consequently the **elision bar is a real, labelled control announcing its exact count**, and it is the only door to that content for an AT user, so it must never be decorative. - **The tracked line is textual by construction** (§5.4), so guaranteed visibility has full AT parity. This is the strongest argument for choosing a text list over Halo arcs. - **`r` is one keystroke for every modality**, so D2 = 1 for AT users too. If D2 differs by modality, the design is broken by its own standard. ### 12.3 Behaviour - Every re-root and every reveal is a content change away from the point of regard: **announce what appeared** via a polite live region, and move focus deliberately (to the new focus heading on re-root; to the revealed region on `t`). - `prefers-reduced-motion` disables all motion; the interface is fully usable without it. - Linear mode and export are the flat, fully-traversable rendering — required output, not a nicety. - Content scroll containers for code are keyboard-scrollable and focusable. - The spine's reduced-contrast type role is *visual*; its AT announcement is full text. --- ## 13. Mobile One column. Everything sizes to contents, so the frame degrades rather than breaking. | Region | Phone form | |---|---| | Spine | **One row**: the immediate parent. Tapping it opens the full ancestor closure as a sheet. | | Focus | Full width, dominant, scrolls. Identical content rules to desktop. | | Band 1 | Below the content, same rows, same authored order. | | Tracked line | Bottom bar, collapsible to a count. | | Compare pane | **Not available in portrait.** | Gestures: tap = enter; tap the spine row = out; swipe right (starting away from the screen edge) = out; vertical drag = scroll; long-press = relations / citation / permalink; two-finger swipe = trail back/forward. **No pinch** — no evidence supports pinch-as-containment, and tap plus swipe decide every case. **The honest degradation.** Portrait phone cannot satisfy P6 (integration partners co-present), so it pays the Schroeder & Cenkci g = 0.63 penalty on any comparison task. The mitigations are landscape split (compare pane returns) and the trail (sequential comparison with one-tap return). This is stated rather than hidden, and it makes "does the reader compare?" the first question to ask about any mobile task. **[J]** — no study in the corpus addresses small viewports. --- ## 14. Failure modes ### 14.1 Degenerate trees | Shape | Behaviour | Why it is acceptable | |---|---|---| | **Chain** (each unit one child, 200 deep) | Peer sets have one member, so the renderer keeps pulling bands until the viewport fills — a readable ladder down the chain. `v` renders the whole chain as continuous prose. | Falls out of the lazy stream with **no special case**. A fixed row budget would have shown one row. | | **Flat** (2,000 units at depth 1) | One vast peer set at band 2 → a contiguous **window in authored order** anchored on the nearest-to-focus member, with elision bars either side carrying exact numerals. **Clicking a bar re-centres the window.** | Gives log-ish traversal without committing to Furnas's geometric-sampling formula. | | **Wildly unbalanced siblings** (3,000 descendants beside 2) | Both render as one row, but the **extent numerals** on each row expose the asymmetry. | This is the McDonald & Stevenson failure, and extent is the fix. | | **Very wide and very deep** | The `MAX_WALK` valve in `bandStream` exists only to bound a pathological corpus; it is never reached in a normal view because the renderer stops first. | Not a design constant — a safety valve, and it is logged when hit. | ### 14.2 Missing or degraded material - **No summaries anywhere** → every rung falls through to raw content, marked `RAW`; the document header shows the warning count. The reader gets a usable, honest, signage-free reader instead of a broken one. - **Partial pipeline output** → per-unit fall-through, per-document count. - **No `content`** on a unit at `CONTENT` rung → its `summary` renders, marked `NO-MATERIAL`. - **Nothing at all** → `source_ref ?? id`, marked `UNSUMMARISED`, still navigable. ### 14.3 Wrong summaries Named four times in the research corpus as the top risk and never designed against. Four mitigations, in order of cost: 1. **`s` cross-check** — always available, no schema (§6.5). 2. **`s` step-down** — exact provenance, iff `derived_from` is present. 3. **Pipeline contract SC-1** — stable head term across the three variants (§3), because varied paraphrase makes readers down-rank a unit (Surber, 2001) **[S]**. 4. **Measurement** — scent hit-rate is the shipped quality metric (§16), and it is the only one that detects this class of defect. **Not built:** confidence shading. It adds a fourth simultaneous typographic encoding (Miller, 1956: more variables raise total information and lower per-variable accuracy) and there is no calibrated confidence to shade with. ### 14.4 Latency The desert-fog rule applies to loading (P14). A unit whose content is still fetching renders its **summary**, which the tree already has — never a blank region. Content arriving is a *content change*, so it arrives discretely after motion settles (P12). A failed fetch renders an explicit error in the content region; the unit stays navigable, the spine and band are unaffected, and retry is one action. ### 14.5 Multi-document corpora and codebases A corpus is roots under a virtual root. Containment distance across documents runs through the virtual root, which correctly makes cross-document units distant — and in a codebase the real connective tissue is **relations**, which are cuts and a trail, not distance. The spine shows corpus → document → section. Extent is reported per document and per corpus. No new machinery. ### 14.6 Repair `u` undoes the last view-state change. Back/forward walk the trail. `Esc` restores the pre-search focus. No view state is derived from behaviour, so there is nothing accumulated that a reader cannot reverse. --- ## 15. The razor ledger: what was removed, and what forced the removal | Removed | Why it was not forced | |---|---| | The a priori importance term (`API = −depth`) | Ties the focus's children with every top-level unit and every ancestor-sibling, at every depth. No study links a performance benefit to a priori importance (Jakobsen & Hornbæk, 2011). | | Fractional sibling DOI offsets (`σ`) | Inert on the case they were introduced for; reorders authored sequence on the case they affect. | | `exactN` selection mode | Rests on a band-gap lemma that is false on the lineage; can drop the focus from its own view. A prefix of a lazy stream is not a mode. | | Row budget, `FREE_ZONE = 0.70`, disinterest threshold `k`, measure-then-refit | Five mechanisms for "stop when the screen is full." A lazy band stream plus a pull loop does it with none. | | 70/30 and 15/70/15 zone proportions | From a paper with no user study, describing a different partition. Regions size to contents. | | "Visible disclosure depth = 2" | No experiment produces the integer; the three source surfaces gave three different values. Keep re-rooting, delete the number. | | Band target of 5–7 | Derived from a cost table built on invented constants, and contradicted by two of its own sibling surfaces ("show all 40," "show all 18"). | | Runtime semantic grouping stage | A synchronous model call in the render path, gated on an undefined trigger, producing an uncacheable viewport-dependent artifact. Grouping belongs in the pipeline as real units. | | Arrival mode (descent vs address) | A two-case table that made a shared permalink render differently for the recipient. Search is a focus change; that is all it ever was. | | Behaviour → view feedback (threshold notching, revisit prominence) | No evidence; contradicted by the design's own no-adaptation principle; breaks reproducibility. | | Coverage / "seen" state and dwell thresholds | The cited finding is scope *estimation*. Extent is a pure function of the tree; coverage needs a threshold nobody has. | | Peek | A third disclosure state in a two-state design, producing two paths to the same content with different results. | | Two-tier rows with a "stable head term" | Requires a field the schema lacks or a lexical split that is banned. The Surber constraint is a pipeline contract instead. | | Relation badge enum capped at 4 | A mapping from an open `kind` vocabulary onto a fixed icon set. A numeral count generalises. | | Numeric band shortcuts (`1`–`9`) | Position index competes with `source_ref` and is unstable. `g` plus typeahead is one general mechanism. | | Recency rail capped at 3 | Its only significant win was against *no aid*, not against the breadcrumb the design already has. The trail serves chains, which the rail could not. | | Spine hysteresis | Damps an oscillation that exists only because of a size cap. Making the elision point a pure function of fit removes the oscillation. | | Halo-style directional edge markers | Require a geometry a re-rooting list does not have. The textual tracked line delivers the mechanism that actually mattered, and does it for AT users too. | | Log-sized elision graphics | Collides with two of the design's own rules (fixed minimum size; counts as numerals, not encodings). | | Separate 180 ms peek duration, k-notch step, dwell threshold | Nothing derives any of them. | | Fold/scroll split keyed to `kind` | Replaced by one computable predicate: children-are-spans. | | Confidence shading | A fourth encoding, with no calibrated quantity to encode. | | Pinch gestures | No evidence; tap and swipe decide every case. | | "Normative requirement count" on entry | Requires the lexical salience the design rejects. | **Also removed: three over-claims.** "A wrong summary *provably* destroys navigability" (an iff over a formal viewing graph whose graceful degradation nobody has measured); "the engine cannot win, only lose" (an n = 11 null, weakly powered); "a persistent index is what produced the comprehension win" (refuted by the source paper's own process data). --- ## 16. What to measure ### 16.1 Never validate with preference Five studies in this corpus show preference tracking confidence rather than competence (§1.2). The control condition is **linear mode**, which we ship. ### 16.2 Shipped instruments | # | Instrument | What it detects | Source | |---|---|---|---| | M1 | **Scent hit-rate, `preview_summary`** — show only a parent's rendering of a child and ask the reader to predict what is inside | The decision to *enter*. This is the field that governs descent. | Budiu et al. (2006); Furnas (1997) NoMis | | M2 | **Scent hit-rate, `collapsed_summary`** — same test on a context row | The decision to *ignore*. Different decision, different field, measured separately. | as above | | M3 | **Incidental learning** (0–6, content the task never pointed at) | The collapse-by-default comprehension risk. The only measure that caught the fisheye deficit when essay grades and answer quality did not. | Hornbæk & Frøkjær (2001) | | M4 | **Transfer** (apply the material to a novel case) | The one thing chunking demonstrably buys under learner control (d = 0.55 re-read, 0.46 reorder). Absent from every source design's plan. | Rey et al. (2019) | | M5 | **Scope estimate** — "how many units does this document have?" | The measured failure of nested reading. Accuracy will not catch it. | McDonald & Stevenson (1996) | | M6 | **Reset and undo rate** (`Home`, `Esc`-to-origin, `u`, searches issued from a leaf) | Disorientation, continuously, in production. | Nekrasovski et al. (2006) | | M7 | **Time-to-clause on address** | The reference task, isolated from the map. | Hornbæk & Frøkjær (2001) | | M8 | **D1 / D2** | Hidden dependencies, as a shipped number. D2 must be 1 at every depth **and every modality**. | Yang et al. (1997) via Blackwell & Green (2003) | M1–M5 and M7 are run against linear mode as the control. M6 and M8 run continuously. ### 16.3 Experiments, cheapest first **E1 — Does a machine-written summary function as one chunk for a naive reader?** *The whole slot economy rests on this and nothing in the literature tests it* (Cowan, 2001: chunk size is unbounded only if the chunk is already in long-term memory). Method: recognition latency and prediction accuracy for a collapsed unit versus its expanded content, on readers with no prior exposure. **Run this first.** It also produces the missing number: *what hit-rate must a summary reach before folding pays for itself?* No published threshold exists anywhere. **E2 — Does the optimal branching factor fall as per-item reading cost rises?** Every breadth/depth study used short labels (Cockburn et al.'s 0.08 s/item is calibrated on menu labels). WeaveLang rows carry sentences. This is the one variable that could rescue a small branching factor, it has never been manipulated, and it is cheap. Method: fixed corpus, vary label length × branching factor, measure time-to-target. **E3 — Does degrading by *substitution* escape the *shrinking* comprehension penalty?** Every fisheye document study degraded by shrinking. WeaveLang substitutes an authored gloss — a different operation. Method: replicate Hornbæk & Frøkjær's three arms with a fourth substitution arm, measuring essay grade and incidental learning. **This is the design's genuine novelty and its genuine risk.** **E4 — Re-rooting versus in-place expansion, at depth.** Re-rooting has never been evaluated as a navigation primitive, and our version keeps a spine and a band — structurally closer to the arm that lost in Zaphiris et al. Method: Zaphiris's design at depths 2/3/4 with our two arms. **E5 — Does one generative prompt at a boundary pay?** Bisra, Liu, Nesbit, Salimi & Winne (2018): induced self-explanation g = 0.55 (69 effect sizes, 64 reports, 5,917 learners) — the **largest interface-actionable effect in the entire corpus**, and every source design dropped it. Deliberately **not shipped by default**, because Mayer's boundary condition is that generative activities need scaffolding and an unprompted "figure it out yourself" is not what the evidence supports. Method: a "what do you expect is inside?" prompt before reveal, A/B, measuring M3 and M4. **E6 — Is multi-focus the active ingredient?** Cockburn et al. (2008) note that studies where a fisheye won often gave it multiple foci and denied them to the baseline. `m` and `Shift+Enter` are the mechanism; test them as the hypothesis rather than assuming them as a feature. **E7 — Relations: annotation versus jump.** The hypertext literature studied undifferentiated "see also" links, not typed labelled edges. Whether a labelled `rebuts` edge behaves like the harmful hypertext link or like the Kintsch situation-model connection is unknown, and it is the most valuable thing this project could measure that nobody has. --- ## 17. Open questions 1. **Does the summary function as a chunk?** (E1.) The design's central premise, untested anywhere. If a generated gloss decomposes into several elements for a naive reader, the slot economy collapses and the right answer is a much flatter, much more linear reader. 2. **What hit-rate must scent reach?** No published threshold. Below it, folding costs more than it saves. 3. **Does locally-varying depth confuse readers?** Every tested system used roughly uniform shallow trees (org charts, taxonomies, file systems). A branch 9 deep beside one 2 deep is unstudied. The design's bet is that pure-distance DOI makes depth invisible and extent makes scope visible, so the question never has to be asked. If M6 shows reset rates rising specifically on deep branches, the bet failed. 4. **Does the children-are-spans predicate cover real corpora?** It is computable and principled, but its coverage on real RFCs, books and codebases is an empirical question about the pipeline's output, answerable by running it over the existing corpus in an afternoon. 5. **Long-run and multi-session use.** DeStefano & LeFevre (2007) note none of their 38 studies examined long-term comprehension, and that novel interface styles "may only be appropriate when the learner is expected to interact with the information over many sessions." **Every negative finding in this document is a first-encounter finding.** A tool used daily by the same engineers on the same codebase is the most likely way the pessimism here turns out not to apply — and re-orientation on return, not initial comprehension, is the dominant cost for a 200-page standard. Nothing here designs for it beyond persisting F. 6. **Does NoMis degrade gracefully?** Furnas proves an iff and notes real structures fail it while remaining usable. Nothing measures navigation under *probabilistically* wrong signage, which is the normal condition for generated summaries. 7. **The reader's goal has no representation.** Kintsch & Rawson locate the situation model in connections to prior knowledge **and to the reader's goals**. Search is currently the only goal channel and it is stateless. A persisted "what I am here for" would feed relation prominence, extent framing, and the return-to-session problem at once — and it is the only route out of the textbase trap this design correctly diagnoses and does not escape. It is also, on P11's logic, exactly the kind of state that must be **reader-declared, never inferred**. 8. **Mobile comparison.** Portrait phone cannot satisfy P6. Whether the trail is an adequate substitute for juxtaposition on a real comparison task is unknown. 9. **AT parity of D2.** Asserted as a design requirement; not yet measured against current NVDA / JAWS / VoiceOver. --- ## 18. References Verified citations only. **[P]** = read against primary text. **[S]** = read through a review or survey named in the entry. ### Capacity and comprehension - Andrews, G., & Halford, G. S. (2002). A cognitive complexity metric applied to cognitive development. *Cognitive Psychology*, 45, 153–219. **[S]** *(source of the soft-limit formulation often misattributed to Halford et al. 1998)* - Bisra, K., Liu, Q., Nesbit, J. C., Salimi, F., & Winne, P. H. (2018). Inducing self-explanation: A meta-analysis. *Educational Psychology Review*, 30(3), 703–725. g = 0.55 [0.45, 0.65], 69 effect sizes, 64 reports, 5,917 learners. **[S]** - Chi, M. T. H., Bassok, M., Lewis, M. W., Reimann, P., & Glaser, R. (1989). Self-explanations: How students study and use examples in learning to solve problems. *Cognitive Science*, 13(2), 145–182. *N = 8; core comparison correlational.* **[S]** - Cowan, N. (2001). The magical number 4 in short-term memory: A reconsideration of mental storage capacity. *Behavioral and Brain Sciences*, 24(1), 87–114. **[P]** - Delgado, P., Vargas, C., Ackerman, R., & Salmerón, L. (2018). Don't throw away your printed books: A meta-analysis on the effects of reading media on reading comprehension. *Educational Research Review*, 25, 23–38. 54 studies, 171,055 participants; g = −.21 [−.28, −.14]; time-frame moderator QB = 4.12, p = .04. **[S]** - Halford, G. S., Wilson, W. H., & Phillips, S. (1998). Processing capacity defined by relational complexity. *Behavioral and Brain Sciences*, 21(6). **[P, abstract]** - Halford, G. S., Baker, R., McCredden, J. E., & Bain, J. D. (2005). How many variables can humans process? *Psychological Science*, 16(1), 70–76. **[S]** - Kalyuga, S., Ayres, P., Chandler, P., & Sweller, J. (2003). The expertise reversal effect. *Educational Psychologist*, 38(1), 23–31. **[P]** - Kintsch, W., & Rawson, K. A. (2005). Comprehension. In M. J. Snowling & C. Hulme (Eds.), *The Science of Reading: A Handbook* (Ch. 12, pp. 209–226). Blackwell. **[P]** *(carries Budd, Whitney & Turley 1995; Kieras 1980; Surber 2001; Dee-Lucas & Larkin 1988; Hyönä 1994)* - Lorch, R. F., & Lorch, E. P. (1996). Effects of organizational signals on free recall of expository text. *Journal of Educational Psychology*, 88(1), 38–48. Three experiments. **[S]** - Lorch, R. F., Lorch, E. P., & Inman, W. E. (1993). Effects of signaling topic structure on text recall. *Journal of Educational Psychology*, 85(2), 281–290. **[S]** - Mayer, R. E. (2023). Research-based principles for designing multimedia instruction. In Overson, Hakala, Kordonowy & Benassi (Eds.), *In Their Own Words* (2nd ed., pp. 143–157). Society for the Teaching of Psychology. Redundancy median d = 0.10 (8/12), reversing under learner control. **[P]** - Cromley, J. G., & Chen, R. (2025). A meta-analysis of Richard Mayer's multimedia learning research. *Educational Research Review*, 49, 100730. 92 articles, 181 studies, 591 effects; overall g = 0.37. **[S]** - McNamara, D. S., Kintsch, E., Songer, N. B., & Kintsch, W. (1996). Are good texts always better? *Cognition and Instruction*, 14(1), 1–43. *Both experiments used junior-high students.* **[S]** - McNamara, D. S., & Kintsch, W. (1996). Learning from texts: Effects of prior knowledge and text coherence. *Discourse Processes*, 22(3), 247–288. *This is the college-sample / reading-time paper.* **[S]** - Miller, G. A. (1956). The magical number seven, plus or minus two. *Psychological Review*, 63(2), 81–97. **[P]** - Oberauer, K. (2013). The focus of attention in working memory — from metaphors to mechanisms. *Frontiers in Human Neuroscience*, 7:673. **[S]** - Rey, G. D., Beege, M., Nebel, S., Wirzberger, M., Schmitt, T. H., & Schneider, S. (2019). A meta-analysis of the segmenting effect. *Educational Psychology Review*, 31(2), 389–419. **[P]** - Rothkopf, E. Z. (1971). Incidental memory for location of information in text. *Journal of Verbal Learning and Verbal Behavior*, 10(6), 608–613. **[S]** - Schneider, S., Beege, M., Nebel, S., & Rey, G. D. (2018). A meta-analysis of how signaling affects learning with media. *Educational Research Review*, 23, 1–24. Retention g+ = 0.53 [0.42, 0.64]; transfer g+ = 0.33 [0.22, 0.43]. **[S]** - Alpizar, D., Adesope, O. O., & Wong, R. M. (2020). A meta-analysis of signaling principle in multimedia learning environments. *ETR&D*, 68(5), 2095–2119. d = 0.38. **[S]** - Schroeder, N. L., & Cenkci, A. T. (2018). Spatial contiguity and spatial split-attention effects in multimedia learning environments: A meta-analysis. *Educational Psychology Review*, 30, 679–701. 58 comparisons, n = 2,426, g = 0.63. **[S]** - Sweller, J. (2010). Element interactivity and intrinsic, extraneous, and germane cognitive load. *Educational Psychology Review*, 22(2), 123–138. **[S]** - Sweller, J., van Merriënboer, J. J. G., & Paas, F. (2019). Cognitive architecture and instructional design: 20 years later. *Educational Psychology Review*, 31(2), 261–292. **[P]** - Trick, L. M., & Pylyshyn, Z. W. (1994). Why are small and large numbers enumerated differently? *Psychological Review*, 101(1), 80–102. **[S]** *(subitizing 1–4 at 40–100 ms/item; note Cowan disputes the separate-capacity reading)* ### Reading, hypertext and navigation - Budiu, R., Pirolli, P., & Fleetwood, M. (2006). Navigation in degree of interest trees. *Proc. AVI 2006*. **[P]** - Cockburn, A., & McKenzie, B. (2000). An evaluation of cone trees. *Proc. BCS HCI 2000*, 425–436. **[P]** - Cockburn, A., Gutwin, C., & Greenberg, S. (2007). A predictive model of menu performance. *Proc. CHI 2007*. T_vs = 0.08n + 0.30. **[P]** - Cockburn, A., Karlson, A., & Bederson, B. B. (2008). A review of overview+detail, zooming, and focus+context interfaces. *ACM Computing Surveys*, 41(1), Article 2. **[P]** - Cockburn, A., & Smith, M. (2003). Hidden messages: Evaluating the efficiency of code elision in program navigation. *Interacting with Computers*, 15(3), 387–407. *Found elision improved navigation; the preference/performance dissociation is reported via Jakobsen & Hornbæk (2011).* **[S]** - DeStefano, D., & LeFevre, J.-A. (2007). Cognitive load in hypertext reading: A review. *Computers in Human Behavior*, 23(3), 1616–1641. **[P]** *(carries Baron et al. 1996; Cress & Knabel 2003; Zhao, O'Shea & Fung 1994; Jonassen & Wang 1993; Shapiro 1998; Niederhauser et al. 2000; van Nimwegen, Pouw & van Oostendorp 1999; Mohageg 1992; McDonald & Stevenson 1998; Zhu 1999; Paolucci 1998; Lee & Tedder 2003; Miall & Dobson 2001; Shin, Schallert & Savenye 1994; Potelle & Rouet 2003; Parush & Yuviler-Gavish 2004; Heo & Hirtle 2001; Wright, Hull & Black 1990)* - Dillon, A. (1991). Readers' models of text structures: The case of academic articles. *International Journal of Man-Machine Studies*, 35(6), 913–925. **[S]** *(do not quote the ~82% placement figure — unverified)* - Dillon, A., & Gabbard, R. (1998). Hypermedia as an educational technology. *Review of Educational Research*, 68(3), 322–349. **[S]** - Hochheiser, H., & Shneiderman, B. (1999). Performance benefits of simultaneous over sequential menus. HCIL Technical Report 99-24, University of Maryland. Journal version: *International Journal of Human-Computer Interaction*, 12(2), 173–192 (2000). **[P]** - Hornbæk, K., & Frøkjær, E. (2001). Reading of electronic documents: The usability of linear, fisheye, and overview+detail interfaces. *Proc. CHI 2001*, 293–300. **[P]** - Hornbæk, K., & Frøkjær, E. (2003). Reading patterns and usability in visualizations of electronic documents. *ACM TOCHI*, 10(2), 119–149. *Reading-pattern re-analysis of the same 20-subject experiment.* **[P]** - Hornbæk, K., Bederson, B. B., & Plaisant, C. (2002). Navigation patterns and usability of zoomable user interfaces with and without an overview. *ACM TOCHI*, 9(4), 362–389. *Carry the field-of-view-box sizing confound with the 22%.* **[P]** - Larson, K., & Czerwinski, M. (1998). Web page design: Implications of memory, structure and scent for information retrieval. *Proc. CHI '98*, 25–32. **[P]** - McDonald, S., & Stevenson, R. J. (1996). Disorientation in hypertext: The effects of three text structures on navigation performance. *Applied Ergonomics*, 27(1), 61–68. *N = 12, four per condition.* **[P]** - Pirolli, P., & Card, S. K. (1999). Information foraging. *Psychological Review*, 106(4), 643–675. **[S]** - Rogers, B. L., & Chaparro, B. (2003). Breadcrumb navigation: Further investigation of usage. *Usability News*, 5(2). 6% of clicks; no efficiency gain; better mental models. **[S]** - Hull, S. (2004). Influence of training and exposure on the usage of breadcrumb navigation. *Usability News*, 6. **[S]** - Brooks, M., West, J. D., Aragon, C. R., & Bergstrom, C. T. (2013). Hoptrees: Branching history navigation for hierarchies. *INTERACT 2013*, LNCS 8119, 316–333. *Breadcrumb vs plain n.s.; hoptree vs breadcrumb n.s. on time after correction.* **[P]** - Zaphiris, P., Shneiderman, B., & Norman, K. L. (2002). Expandable indexes vs. sequential menus for searching hierarchies on the World Wide Web. *Behaviour & Information Technology*, 21(3), 201–207. *Preference results not significant.* **[P]** ### Degree of interest, zooming and view navigation - Card, S. K., & Nation, D. (2002). Degree-of-interest trees: A component of an attention-reactive user interface. *Proc. AVI '02*, 231–245. *No user study.* **[P]** - Furnas, G. W. (1986). Generalized fisheye views. *Proc. CHI '86*, 16–23. **[P]** *(footnote 1 ordinal invariance is over the combined DOI; footnote 3 permits per-point API "though often less efficient algorithms may result")* - Furnas, G. W. (1997). Effective view navigation. *Proc. CHI '97*, 367–374. (Workshop version: Effectively view-navigable structures, HCIC '95.) **[P]** - Furnas, G. W. (2006). A fisheye follow-up: Further reflections on focus + context. *Proc. CHI 2006*, 999–1008. **[P, abstract + secondary]** - Furnas, G. W., & Bederson, B. B. (1995). Space-scale diagrams: Understanding multiscale interfaces. *Proc. CHI '95*, 234–241. *Empirical support explicitly informal.* **[P]** - Heer, J., & Card, S. K. (2004). DOITrees revisited: Scalable, space-constrained visualization of hierarchical data. *Proc. AVI 2004*. *No user study; translation is what they implemented, scaling retained.* **[P]** - Jakobsen, M. R., & Hornbæk, K. (2006). Evaluating a fisheye view of source code. *Proc. CHI 2006*, 377–386. **[P]** - Jakobsen, M. R., & Hornbæk, K. (2011). Fisheye interfaces — research problems and practical challenges. In A. Ebert et al. (Eds.), *HCIV (INTERACT) 2009*, LNCS 6431, pp. 76–91. Springer. **[P]** - Jul, S., & Furnas, G. W. (1998). Critical zones in desert fog: Aids to multiscale navigation. *Proc. UIST '98*, 97–106. **[S — full text unobtainable; abstract and prototypes confirmed]** - Nekrasovski, D., Bodnar, A., McGrenere, J., Guimbretière, F., & Munzner, T. (2006). An evaluation of pan & zoom and rubber sheet navigation with and without an overview. *Proc. CHI 2006*, 11–20. **[P]** - Shneiderman, B. (1996). The eyes have it: A task by data type taxonomy for information visualizations. *Proc. IEEE Symposium on Visual Languages*, 336–343. *Taxonomy and design argument; no controlled experiment.* **[P]** ### Animation, transitions and change - Chevalier, F., Dragicevic, P., & Franconeri, S. (2014). The not-so-staggering effect of staggered animated transitions on visual tracking. *IEEE TVCG*, 20(12), 2241–2250. **[P]** - Franconeri, S. L., Jonathan, S., & Scimeca, J. M. (2010). Tracking multiple objects is limited only by object spacing, not by speed, time, or capacity. *Psychological Science*, 21(7), 920–925. **[S]** - Heer, J., & Robertson, G. G. (2007). Animated transitions in statistical data graphics. *IEEE TVCG*, 13(6), 1240–1247. **[P]** - Levin, D. T., & Simons, D. J. (1997). Failure to detect changes to attended objects in motion pictures. *Psychonomic Bulletin & Review*, 4, 501–506. **[S]** - Levin, D. T., Momen, N., Drivdahl, S. B., & Simons, D. J. (2000). Change blindness blindness. *Visual Cognition*, 7, 397–412. **[S]** - Lowe, R. K. (1999). Extracting information from an animation during complex visual processing. *European Journal of Psychology of Education*, 14, 225–244. **[S]** - Robertson, G., Fernandez, R., Fisher, D., Lee, B., & Stasko, J. (2008). Effectiveness of animation in trend visualization. *IEEE TVCG*, 14(6), 1325–1332. **[P]** - Shanmugasundaram, M., & Irani, P. (2008). The effect of animated transitions in zooming interfaces. *Proc. AVI 2008*, 396–399. *Cite the body, not the abstract: the error result is null.* **[P]** - Simons, D. J., & Ambinder, M. S. (2005). Change blindness: Theory and consequences. *Current Directions in Psychological Science*, 14(1), 44–48. **[P]** - Simons, D. J., & Levin, D. T. (1998). Failure to detect changes to people during a real-world interaction. *Psychonomic Bulletin & Review*, 5, 644–649. **[S]** - Tversky, B., Morrison, J. B., & Bétrancourt, M. (2002). Animation: Can it facilitate? *International Journal of Human-Computer Studies*, 57(4), 247–262. **[P]** ### Notation, practice and accessibility - Blackwell, A. F., & Green, T. R. G. (2003). Notational systems — the cognitive dimensions of notations framework. In J. M. Carroll (Ed.), *HCI Models, Theories, and Frameworks* (pp. 103–134). Morgan Kaufmann. **[P]** - Kiss, J. (2013, February). (Not so) simple ARIA tree views and screen readers. *Accessible Culture*. **[S — 2013 browser/AT combinations, re-test before freezing]** - Nielsen, J. (2006). Progressive disclosure. Nielsen Norman Group. *Contains no effect sizes and no numbers; its one hard claim is the two-level ceiling.* **[P]** - Roselli, A. (2020, May). Disclosure widgets. *Cited only for: the APG disclosure pattern is complete and works well across devices and platforms. It does not discuss tree views.* **[P]** - Victor, B. (2011). Up and down the ladder of abstraction. *Design argument; no user study, no comparison condition, no measured outcome.* **[P]** - W3C Web Accessibility Initiative. WAI-ARIA Authoring Practices Guide — Disclosure and Treeview patterns. **[P]** - Yang, S., Burnett, M. M., DeKoven, E., & Zloof, M. (1997). Representation design benchmarks: A design-time aid for VPL navigable static representations. *Defines D1 and D2; read via Blackwell & Green (2003).* **[S]** ### Excluded — do not re-import These appear in circulating summaries of this literature and were found fabricated, misattributed, or unsourceable by adversarial verification. They must not appear in project documents. - **"Hochheiser & Shneiderman (2000), Proc. ACM CHI 2000, pp. 38–45."** No such publication. The work exists as HCIL TR 99-24 and as *IJHCI* 12(2), 173–192. - **"Whitney, G. (2013), Accessible Culture."** Misattributed byline; the author is **Jason Kiss**. - **"Donskoy & Kaptelinin (1997) — fisheye slowest and least preferred."** The three-way ranking and the preference result are not in the cited survey. Excluded entirely. - **"Lida, Hull & Pilcher (2003) breadcrumb usage figures"** (72 volunteers; 3.25 / 2.11 clicks; 3.5% / 1.4%). The paper that supposedly reports them does not cite that study. Use Rogers & Chaparro (2003) instead. - **"NN/g measured 30–50% faster initial task completion and ~40% fewer support tickets from progressive disclosure."** Neither figure appears in Nielsen (2006), which contains no numbers at all. - **"DOI = F(API, D)" attributed to Furnas (1986).** That general form is Equation 1 of Jakobsen & Hornbæk (2011). Furnas writes only the additive form. - **"8–16 items per level"** as an empirical optimum from Snowberry et al. (1983) / Kiger (1984) / Larson & Czerwinski (1998). None of the three establishes it. Larson & Czerwinski's own abstract is stricter about breadth than its popular retelling.