Footnote Architecture Read this entire file before modifying any footnote-related code. Every prior fix to footnotes broke something else because the underlying model was misunderstood. This document is the source of truth.

 

Footnote Architecture

Read this entire file before modifying any footnote-related code. Every prior fix to footnotes broke something else because the underlying model was misunderstood. This document is the source of truth.

---

The data model

Numbering is GLOBAL, not section-local

Footnotes in The Secret Book of Walt are numbered 1 through 158 across the entire critical edition. The numbering follows the print Pergamon edition exactly. Footnote ¹³⁸ is the 138th footnote in the book, not the 1st footnote in any subsection.

A paragraph in Introduction can reference footnote ¹³⁸, even though footnote ¹³⁸'s definition lives in Gospel §IX (because §IX of the gospel is what generated the apparatus entry). Likewise, the Manuscripts section uses footnotes ¹¹⁹–¹²⁷, which appear only in Manuscripts. There is no per-section restart, and there must never be one.

The actual distribution in walt_full_data.json:

Section	Declared footnotes
introduction	¹, ², ³, ¹³⁸–¹⁵¹, ¹¹⁰–¹¹⁶
manuscripts	¹¹⁹–¹²⁷
gospel	⁴–¹⁵⁶ (111 footnotes; not contiguous, gaps where notes live elsewhere)
appendix_d	¹¹⁷, ¹¹⁸
appendix_e	¹²⁸–¹³⁶
appendix_h	¹³⁷
appendix_k	¹⁵⁷, ¹⁵⁸

Body-text references to these numbers can appear in any section. The single source of truth is therefore a global footnote map, built once at load time by walking every section.

NOT every superscript is a footnote

The text uses Unicode superscripts (¹²³⁴⁵⁶⁷⁸⁹⁰) for two purposes:

1. Footnote references — at the end of a sentence, after a quote, or adjacent to whitespace. Examples: …catalogue.³ / …inside it."¹³⁸ / arrived from the future).¹⁴²

2. Identifier suffixes on letters — most importantly, "Golden Ticket" identifiers in the codicological apparatus. Examples: G⁴⁶ / G³¹–G⁴⁵ / G¹–G³ | §I.

The disambiguation rule is exact:

A run of superscripts is a footnote reference if and only if it is NOT immediately preceded by an alphabetical letter (A-Z / a-z).

Implementation: negative-lookbehind regex /(?<![A-Za-z])([¹²³⁴⁵⁶⁷⁸⁹⁰]+)/g, or equivalent character-by-character scan if lookbehind support is in doubt.

This rule is non-negotiable. Breaking it makes ticket references like G⁴⁶ clickable as fake footnotes, which has happened in past iterations.

Paragraph-level footnote definitions

A footnote definition is a paragraph object of the form:

{ "type": "footnote", "text": "¹³⁸ The description \"heavier than gold should be\" has led..." }

The leading superscript is the footnote ID. The remainder is the footnote body. The system parses both at map-build time.

Some entries also carry an fn_id field (used in versed gospel data); when present, it must equal the parsed leading superscript. If both are present and they disagree, the parsed superscript wins (it is what the body text references).

---

The component model

useGlobalFnMap(rootData) — single source of truth

A hook (or pure function) that walks the entire data object and produces:

{
  '¹':   { id: '¹',   text: 'Sharks, L. (2015)…',          section: 'introduction' },
  '²':   { id: '²',   text: 'The parallel to…',             section: 'introduction' },
  '³':   { id: '³',   text: 'The numbering of the archons…', section: 'introduction' },
  '⁴':   { id: '⁴',   text: 'On the appearance of…',         section: 'gospel' },
  …
  '¹³⁸': { id: '¹³⁸', text: 'The description "heavier than gold…"', section: 'introduction' },
  …
  '¹⁵⁸': { id: '¹⁵⁸', text: '…',                              section: 'appendix_k' }
}

Built once per book, memoized by the data object identity. Built on the client (no server-side preprocessing required). Fast — Walt has 158 entries.

<FootnotedText text glossaryLink isVeil onFnClick visibleFns /> — universal renderer

Replaces the legacy Leaf component for all body-text rendering in front matter, gospel, and back matter. Outputs a sequence of:

• Plain text spans (with optional glossary linking via injectLinks / LinkedText) for non-superscript runs;
• Clickable footnote markers (in veil mode), or styled-but-passive footnote markers (in pierce mode), for superscript runs that pass the not-preceded-by-letter rule.

Veil mode click behavior: toggles the footnote into the section's visibleFns map; the footnote text is rendered inline immediately below the paragraph that contained the marker. Re-clicking the same marker collapses it.

Pierce mode: the markers are still rendered (as a low-saturation blue), but click handlers and keyboard handlers are not bound. Pierce mode exists to give a quieter reading experience; the markers still indicate "there is apparatus here" without offering it.

<InlineFootnote text fnColor depth /> — popup display

The visible footnote body when a marker is clicked. Renders below the parent paragraph with a thin left rule, the footnote text, and (optionally) a close button. Uses fnColor for the marker rule.

Where the components live

Component	File	Notes
useGlobalFnMap	src/footnotes.js	Pure JS, no React imports — testable.
FootnotedText	src/footnotes.jsx	Render-only. No state. State lives in caller.
InlineFootnote	src/footnotes.jsx	The popup leaf.

Both App.jsx (Walt) and Antioch.jsx import from src/footnotes.jsx.

---

State model

Each section maintains its own visibleFns useState({}) keyed by footnote ID (the superscript string itself, e.g. '¹³⁸'). This is section-local because two different sections might both reference ¹³⁸, and we want each render of ¹³⁸ to be independently togglable.

const [visibleFns, setVisibleFns] = useState({});
const toggleFn = (id) => setVisibleFns(prev => ({ ...prev, [id]: !prev[id] }));

After click: the parent paragraph renders <InlineFootnote> immediately below itself if visibleFns[id] is truthy.

---

What NOT to do

• Do not renumber footnotes per section. The numbering is canonical and matches the print edition.
• Do not strip the leading superscript from footnote bodies when rendering the footnote — the user expects to see "¹³⁸ The description…" as the leaf text.
• Do not use the old ✦ adjacency toggle. It only worked when a footnote paragraph was immediately after the prose paragraph that referenced it, which is rarely the case.
• Do not use the old per-section "endnotes block" toggle. It hid inline references and required users to scroll.
• Do not strip <sup> styling from non-clickable markers in pierce mode. The markers remain visible as a reading cue.
• Do not turn ticket numbers like G⁴⁶ into clickable footnotes. Apply the not-preceded-by-letter rule.
• Do not regenerate walt_full_data.json from scratch — the JSON has been hand-aligned with the print edition. Modify the rendering logic, not the data, to fix display bugs.

---

Pierce mode vs Veil mode

Aspect	Pierce	Veil
Body text	Black on cream, no apparatus shown by default	Black on warm cream, apparatus accessible
Footnote markers (¹²³) in body	Rendered, blue, no click	Rendered, blue, clickable
Inline footnote popup	Not available	Toggles below paragraph
Endnotes block	Hidden	Hidden (legacy; we removed)
Glossary terms (LinkedText)	Active in both	Active in both
Visual feel	Stripped down — reading focus	Critical edition with apparatus reachable

Pierce mode is a reader's mode, not a no-apparatus mode. The blue markers are the cue. The reader knows footnotes exist and can switch to veil mode to read them.

---

Antioch parity

The same architecture must apply to The Gospel of Antioch. Antioch also has globally-numbered footnotes (counted from the start of its own critical edition; not shared with Walt). The same FootnotedText, useGlobalFnMap, and InlineFootnote components are used.

Antioch's data file antioch_gospel_data.json must include all four section types — front matter (introduction, headnote), gospel (114 logia), apparatus criticus, appendices (A–E). Until that data file is regenerated, Antioch will only display footnotes embedded in its gospel chapters (none currently exist there).

---

How to test a footnote change

Before merging, check:

1. Front matter: Click ¹ in Introduction §I — popup appears below that paragraph; popup contains "Sharks, L. (2015)…"
2. Cross-section: Click ¹³⁸ in Introduction §IX (Physical Description) — popup appears with the heavier-than-gold note (defined in introduction but lives in the same section).
3. Manuscripts: Click ¹¹⁹ in Note on the Manuscripts — popup with manuscripts §A note.
4. Codicological table: G⁴⁶ and G³¹ in the codicological table are NOT clickable — they remain inline text with the same superscript styling but no cursor change, no click handler.
5. Pierce mode: All markers are blue; clicking them does NOTHING; the popup never opens.
6. Gospel verse: Proem footnote ⁴ opens inline below the verse, as it always has.
7. Re-click: Clicking an opened footnote closes it.
8. Section switch: Switching sections preserves no state (each section's visibleFns is local).

---

Maintenance log

Date	Change	Author
2026-04-28	Universal footnote system: global fnMap, FootnotedText component, InlineFootnote popup. Removed ✦ adjacency toggle and endnotes block. Documented architecture.	TACHYON / Sharks, Lee

When you change footnote rendering, append an entry to this table and update the relevant section above if the architecture changed.