A flat, alphabetical reference for every documented window.CODEX_* global, helper function, and codex:* custom event the app dispatches.
Signatures use TypeScript-style notation but the runtime is plain JS. Prose descriptions are intentionally one or two sentences each — for deep context see SPEC.md and MODULES.md.
type Bible = {
translations: Translation[];
getChapter(translation: string, book: string, chapter: number): Promise<{ verses: Verse[] }>;
// … plus internal _memCache and helpers
};The translation registry + verse fetcher. Backs every reader view and seeds CODEX_SEARCH and CODEX_GEMATRIA_INDEX.
Imperative navigator. Pass "jhn.1.1" or "jhn.1" to jump the reader to that location. Dispatches codex:navigate and (if a verse is given) codex:verse-select.
Looks up a BCP-47 language code's display name, honoring the active UI language. Falls back to the code itself when unknown.
TTS bridge over speechSynthesis. Cancels any in-flight utterance before speaking.
{ start(); stop(); status(): { phase, progress, total }; resume(); }Background pre-fetch controller for chapters/panels. Emits codex:autocache-start|tick|done|error.
Curated array of external Bible-study links surfaced in the verse menu. Each entry: { id, name, url(ref), category, langs }.
Returns cross-references for a verse, drawing from any loaded cross-reference modules.
React component rendering the right-rail cross-reference UI. Internal — listed for completeness.
Static tables: book ids, canonical orders, chapter counts, abbreviation maps. Read-only.
Browser-direct AI client used in BYO-key mode. Same {system, messages, …} → { text, model, usage } shape as /api/chat, but talks to providers from the page when the user has supplied their own key.
Animation/typography drift helpers (subtle motion utilities used in chrome).
{
detectLang(text: string): "hebrew" | "greek" | "english" | "mixed";
strip(text: string): string;
hebrew: { hechrachi, gadol, sidduri, katan, katan_mispari, boneh, kidmi,
atbash, albam, neelam, haakhor }; // each: (text) => number
greek: { isopsephy, ordinal, reduced };
english: { ordinal, reduction, reverse };
all(text: string): Record<string, number>;
}Pure on-device gematria. No network, no async.
{
build(): Promise<void>;
find(value: number, system?: string): { ref, word, system }[];
stats(): { values, entries, builtAt };
reset(): Promise<void>;
ensure(): Promise<Index>;
}Cross-reference index that groups every cached verse's words by gematria value. Persisted under codex.gematria.index.v1. Auto-rebuilds (throttled) when new chapters arrive.
In-app Help: open(id?), search(q), categories, articles. Reads data/help/articles.json.
Active UI language and the registry of available languages.
{ list(): Theme[]; apply(id: string): void; current(): Theme; }Light-theme registry. Emits codex:light-theme-change on apply.
Curated array of manuscript-image links (Leningrad Codex, Sinaiticus, etc.) for the verse menu.
{
loadModule(id: string): Promise<Module>;
loadModuleFromUrl(url: string, expectedId: string):Promise<Module>;
listModules(): Promise<MetaSummary[]>;
removeModule(id: string): Promise<void>;
hasModule(id: string): Promise<boolean>;
VALID_TYPES: string[];
}Data module loader with IDB cache + version-aware revalidation. See SPEC.md §4 and MODULES.md.
Beginner-mode switch. get(): boolean · set(on: boolean): void. Hides advanced affordances when on.
{
cacheKey(book: string, chapter: number): string;
load(book, chapter, bookName): Promise<PanelData>;
getCached(book, chapter): PanelData | null;
getCachedMeta(book, chapter): { fetchedAt } | null;
cacheStats(): { ref, bytes, fetchedAt }[];
purge(book, chapter): void;
subscribe(fn): () => void;
}AI-backed panel JSON generator for Talmud/Commentary/Gematria/Gnosis/Apologetics. localStorage cache (codex.panels.v1.*).
Curated pilgrimage-route data (e.g. Via Dolorosa, Camino).
Raw plugin array. Pre-boot scripts push directly; the API adopts pending entries on load.
{
register(plugin: Plugin): boolean;
list(): Plugin[];
getPanels(): PluginPanel[];
getVerseActions(): PluginVerseAction[];
dispatch(event: string, detail: any): void;
onNavigate(book, chapter): void;
onVerseSelect(ref): void;
}Canonical plugin host. See SPEC.md §3.
Quest engine (Messianic, manuscript, geography quests). start(id), progress(id), complete(id).
Discovery / Reels feed: next(), seen(id), deck().
{
index(translation: string, refsObject: any): Promise<void>;
ingestPassage(passage: any): Promise<void>;
search(query: string, opts?: { limit? }): Promise<Result[]>;
clear(): Promise<void>;
stats(): { translations, verses, indexedAt, built };
ready: Promise<void>;
}Full-text search over cached verses. Self-contained IDB (codex-search).
React component for the top-bar search input. Internal — opens CODEX_SEARCH UI.
Look up a Strong's entry by id (e.g. "H430", "G3056") across loaded lexicons.
React component rendering the right-rail Strong's UI.
Helper that decorates verse text with clickable Strong's tokens when an aligned concordance module covers it.
{
backend(): "github" | "firebase" | null;
push(): Promise<void>;
pull(): Promise<void>;
status(): { lastSync, backend, auto };
}Cross-device sync (Gist / Firebase backends).
i18n string lookup. window.t is an alias.
Drift-aware translation lookup used for poetic/literary UI strings (subtle variation across reloads).
Mutable array of right-rail tab descriptors. Plugins extend it via CODEX_PLUGINS_API.register({ panels: […] }).
All events are CustomEvent instances dispatched on window. Subscribe with addEventListener(name, e => e.detail).
Background-cache lifecycle. Detail: { phase, progress, total, error? }.
Bible bundle loaded. Detail: { translation, refs }.
Detail: { ref, label, ts }.
Progressive-discovery system unlocked something. Detail: { category, id }.
User changed AI provider/model. Detail: { provider, model }.
Global Esc-key broadcast. No detail. Use to dismiss your overlay.
A gematria computation completed. Detail: { word, lang, values }.
User saved/cleared an API key. Detail: { provider, hasKey }.
UI language changed. Detail: { lang }.
Detail: { id }.
Reader moved to a new chapter. Detail: { book, chapter }.
Notes/highlights changed. Detail: { kind, ref }.
Open a right-rail panel by id. Detail: { id }. Useful to call dispatch("codex:open-panel", { id: "strongs" }) from a verse action.
Reader overlay (red-letter, YHWH, verse-numbers, …) toggled. Detail: { which, on }.
A plugin successfully registered. Detail: { plugin }.
Hotkey fired. Detail: { key }.
Inline token tapped. Detail: { strong } e.g. "H430".
Tourist mode lifecycle. Details: { on } / { stop } / { ref }.
User granted geolocation. Detail: { lat, lng }.
Verse cursor moved. Detail: { ref } ("jhn.1.1").
Timeline scrubbed. Detail: { year }.
SPEC.md— formal extension specificationMODULES.md— module authoring guideCONTRIBUTING.md— how to contribute code, modules, translationsROADMAP.md— what's next
Read-only JSON endpoints over the bundled data/modules/*.json files. All endpoints are GET, return application/json, are CORS-open (Access-Control-Allow-Origin: *), and are rate-limited to 100 requests / minute / IP (429 with Retry-After on exceed).
Base path: /api/v1
Safe-for-monitoring health probe. Reveals no key, usage, or provider info.
{ "ok": true, "version": "5.4.0", "modules_count": 18 }Lists every bundled module's meta block.
{ "count": 18, "modules": [ { "file": "strongs-hebrew.json", "id": "strongs-hebrew", "type": "lexicon", "name": "...", "version": "1.0.0" }, ... ] }Strong's lexicon entry. id is H<n> (Hebrew) or G<n> (Greek). 404 if missing.
GET /api/v1/strongs/H1
→ { "id": "H1", "word": "אָב", "translit": "av", "gloss": "father", "def": "...", "usage": 1215 }
TSK cross-references for a verse. ref uses lowercase book.chapter.verse (e.g. gen.1.1, john.3.16).
GET /api/v1/crossref/gen.1.1
→ { "ref": "gen.1.1", "crossrefs": [ { "ref": "jhn.1.1", "theme": "..." }, ... ], "source": "TSK ..." }
Stub. Full-text server-side search is not yet implemented; CODEX currently searches client-side against cached Bible text. The response includes an explanatory note and stub: true.
{ "q": "love", "translation": "kjv", "limit": 20, "results": [], "stub": true, "note": "Server-side full-text search is not yet implemented..." }Filter the bundled timeline events. All query params optional. from/to are integer years (negative = BCE).
{ "count": 12, "from": -2000, "to": 2000, "category": "narrative", "era": null, "events": [ ... ] }Returns the parsha for the given ISO week (1..53), or the current ISO week if week is omitted or current. The 54-parsha cycle wraps modulo its length.
{ "week": 20, "parsha": { "n": 20, "name": "...", "translit": "Tetzaveh", "torah": "exo.27.20-30.10", ... }, "cycle": "annual" }Every /api/v1/* response sets X-RateLimit-Limit and X-RateLimit-Remaining. When the limit is exceeded:
HTTP/1.1 429 Too Many Requests
Retry-After: 47
{ "error": "rate limit exceeded", "retryAfter": 47 }Misses return JSON 404 with a friendly shape:
{ "error": "not found", "ref": "gen.99.99" }