Repository / docs/FRONTEND.md
Panel development
TgWitness / Documentation · Development
Native ES modules and plain DOM, no frontend build step. python start.py runs the panel
locally; browser checks make their own temp workspaces and never touch Telegram.
Restart the application after updating panel assets or translation dictionaries.
panel_assets.PanelFiles builds the page and its subresource-integrity metadata at
startup, and the locale endpoint caches generated dictionaries. Replacing files in
a running installation does not refresh that metadata.
On this page
Language#
Write new UI text, guides and release notes in English first. English strings are the translation keys and the fallback. Keep the user's chosen language across reloads, use the browser's preference until they pick one.
Modules#
| Location | Owns |
|---|---|
tgwitness/static/app.js |
Bootstrap, session boundary, adapters for old controllers |
static/router.js |
Paths, workspace query, journal filters, deep links, Back/Forward |
static/core/view-host.js |
Active view, request cancellation, retained roots |
static/core/time.js |
UTC/local display, relative time |
static/views/ |
Sources, Parameters, Accounts, Access, System log, Exports, chat list |
static/components/ |
Health, notices, journal controls, drafts, connection feedback |
Controllers get their API, translation and permission functions passed in. Don't reach into
another controller's form and don't assume classic-script globals live on window.
Only the active view root is in the document, the rest stay in memory so drafts and
listeners survive. Not real code splitting yet: index.html still has the initial markup
and app.js still has old controllers.
Navigation and requests#
/?ws=defaultopens the default view. Routes:/chats,/chats/:chatId,/journal,/journal/event/:seq,/sources,/parameters,/accounts,/access,/integrations,/exports,/extras/:card.- A route is just a view, it grants nothing. The API checks permissions and scope every time.
- The static demo uses a
routequery param because GitHub Pages can't serve panel paths. Missing API and asset paths must never fall back to HTML. enter(context)gets an abort signal and acurrent()guard. Stop reads on leave, and check request and workspace generation before applying a response.- Hidden tabs pause periodic reads. Retries repeat status reads only, never a POST after an unclear network error.
- Startup reads access and the workspace list concurrently, then reads status for the resolved workspace. The initial profile result is reused. Chat export discovery waits for a selected chat and shares its in-flight request; only active jobs are polled.
Forms#
Background updates patch rows in place. Never rebuild a form, steal focus or drop an unsaved
value. On save, compare the sent snapshot with the current draft and keep newer edits.
Clear write-only credentials from the field and the Discard baseline. Tokens and credentials
never go to browser storage, except the panel sign-in token in tab-scoped sessionStorage
(cleared on lock).
Wizard drafts and appearance preferences debounce saves by 400 ms. Each queue keeps the latest complete payload, allows one write at a time and settles all callers of the combined save. A workspace reset cancels unsent work; completed old requests must pass the owner/generation guard before changing UI state. Failed writes are reported to their callers and are never retried automatically.
Use tr() for UI text. Keep tools/i18n_keys.py aware of dynamic labels. New module files
go into the wheel, demo asset list and source archive.
The panel only reads signed records. Grouping, filters, download history and drafts are not journal edits.
Keep the daily navigation and reading area compact. Collection health belongs in
the status menu, chat-specific operations in Chat actions, and optional journal
filters in their disclosure. A collapsed control must remain reachable with a
keyboard. Keep selected journal filters visible outside the disclosure, preserve
drafts when navigating, and reset action menus when the workspace or route changes.
components/layout.css supplies the shared layout and responsive overrides.
components/polish.css loads last and owns depth, motion, icon tiles, dialog and
notification presentation. The page forbids inline styles, so charts set sizes through
the CSS object model and SVG attributes. The counters and charts in views/pulse.js read
the status counters and the chat list beside the overview from views/home.js.
The report studio steps live in
views/report-selection.js with the editor layout in views/report-editor.js.
Still to extract#
- Request helpers into
core/api.js, keeping their cancellation, timeout and error behavior. One controller at a time, run its stale-response tests. - Session/workspace state into
core/store.jswith narrow subscriptions, no global re-render. - Remaining chat, journal and integration controllers out of
app.js. Not together with backend changes. - Lazy-load view templates once nothing needs eager markup.
Checks#
python -m ruff check .
python tools/publication_guard.py --git-index
Use the private browser regressions for routing, stale polling responses, source selection, journal rendering, controls and write-only drafts. Use synthetic data; keep generated journals, sessions and real-account screenshots out of Git.