// OPENBOX DOCS

Frontend modules

Inventory of the 35 static/ JS modules, entry wiring, and the search worker contract.

The web UI ships as index.html plus 35 ES modules in static/ (33 domain modules plus app.js and worker.search.js), served from /static/* with cache headers. app.js is the entry point; every other main-thread module imports shared state and helpers from state.js / util.js.

Module inventory

ModuleResponsibility
app.jsEntry/boot: wires all domain modules into the shell
state.jsAppState, api client, session token, search index (filteredGames, trigram helpers)
util.jsShared helpers ($, escapeHtml, controller map, trigram utilities)
library.jsLibrary grid rendering, cover grouping, search worker client
router.jsHash router for library view state (ADR 0021)
navigation.jsKeyboard + gamepad navigation for grid and list views
dialogs.jsDialog manager (focus trap, Escape to close)
settings.jsSettings UI
setup.jsLibrary Setup Center workflow (preview/commit imports)
imports.jsImport dialogs (storefronts, ROM folders, arcade DATs, wizards)
media.jsMedia audit, gallery, bulk downloads
metadata.jsMetadata dialog and batch auto-match
insights.jsPlay Insights dashboard (heatmap, streaks, rankings; lazy-loaded)
activity.jsActivity Center (durable operations, jobs, SSE progress)
sessions.jsSessions and play-history UI
recap.jsSession recap card and post-session actions
moments.jsMoments capture, timeline, and resume-from-moment UI
clips.jsRecord That clip gallery and reel actions
bigbox.jsBig Box kiosk UI (stage/hybrid/coverflow, gamepad, screensaver)
arcaderoom.jsController-friendly Arcade Room and Museum canvas surface
party.jsGame Night queue, wheel, and round controls
household.jsHousehold members, challenges, shares, and leaderboard UI
storefront.jsStorefront manager (Gameyfin install/download, owned-vs-installed)
constellation.jsLibrary relationship graph
picker.js“What should I play?” recommendation picker
mood.jsAdaptive cover theming
mastery.jsMastery completion dashboard
wrapped.jsPrintable Year in Games report
timeline.jsHistory timeline view
timemachine.jsJournal timeline, as-of view, and revert preview UI
palette.jsCtrl/Cmd-K command palette and shortcut help
whatsnew.jsWhat's New panel and local tips
reader.jsDocument/manual reader
i18n.jsInternationalization (t(key, params), data-i18n attributes, locale loading)
worker.search.jsOff-main-thread trigram search worker (see contract below)

Search worker contract (worker.search.js)

Trigram expansion runs off the main thread with identical logic to the main-thread index (util.js / state.js indexTerms) so results match either path.

  • Worker script: static/worker.search.js, spawned by library.js via new Worker('./static/worker.search.js').
  • Request: postMessage {id, type, ...} where type is search ({query, games}), expand (trigram expansion), or warm.
  • Response: postMessage {id, type: 'search', results, count} (or {id, type: 'expand', trigrams}, {id, type: 'warm', ok: true}); unknown types and exceptions return {id, error}.
  • Fallback: when Worker is unavailable, library.js uses the main-thread filteredGames() / index path directly — same results, main-thread cost.