Dispatch Panel Theming

The panel is themeable in four tiers. Pick the lowest that meets your goal.

Layers combine. A theme with no jsText skips the source-review gate (see Security model). Reach for Tier 4 last: it is the only tier where new panel features do not appear automatically.

Tier 1 — Design tokens

Set these via cssVars, a :root { … } block in cssText, or theme.setVar(). Generated from theme-sdk/tokens.ts:

The shared UI kit uses a second set, on the shadcn/UnoCSS convention: --background, --foreground, --card, --primary, --secondary, --muted, --accent, --destructive (each with a -foreground partner), --border, --input, --ring, --radius. Set only the dispatch tokens and the modals stay on the default palette. --accent (UI-kit hover) is not --accent-raw (dispatch).

Derived -rgb companions — do not set these

The panel reads a triplet per tinted color — --accent-raw-rgb: 77, 166, 255 — and builds tints as rgba(var(--accent-raw-rgb), 0.15). They recompute on every theme change, so setting one does nothing. Use the same form for your own tints.

Tier 2 — CSS

cssText is injected as a <style> block, so it can restyle any part of the stock panel. Target the panel's class names or the Tier 1 tokens. It is sanitized at install: @import, expression(…) and every url(…), relative paths and data: URIs included, are removed. Use gradients or Unicode glyphs instead.

extends inherits a built-in theme's tokens: dark-minimal (default), dark, dark-blue, basic, basic-dark.

Tier 3 — Slot overrides

A slot replaces one kind of component while the host keeps the shell: feature gates, keyboard handling, ARIA, localization and every guard. What you leave alone stays stock.

A fragment is ordinary data-rd-* markup, bound by the same binder and action allow-list as a template. Only scope differs: an item slot gets the item as a scope variable as well as the root view model, so ch.name and counts.panics both resolve in a channel fragment.

{ "id": "mcc5500-slots", "slots": {
  "channel": "<div class=\"mx-tile\" data-rd-class=\"cur:ch.isCurrent\">…</div>"
} }

Host gates are checked before the slot renders, so a theme never sees them: an overridden call-card cannot appear where 911 is off. See mcc5500-slots-demo.js.

Compatibility — requires

The view model and slot registry are versioned separately. A theme declares its floor with { "requires": { "viewModel": 2, "slots": 1 } }. These are floors, not pins: a theme needing v2 runs on v2 and later. No requires means v1. On a mismatch install is rejected, and a stored incompatible theme fails safe at mount.

Tier 4 — Full takeover

Hides the stock panel and renders your own, two combinable ways:

• Declarative templates — binder-driven data-rd-* markup. No JavaScript, so it auto-publishes. Recommended
• Theme JavaScript — jsText, imperative, full DOM access. Trips the review gate

Either way you take on full parity. mcc5500-theme.js rebuilds a console from scratch, delegating the rest to a small jsText layer.

Theme JavaScript

Three globals are injected: dispatch (state, events, actions), theme (CSS and DOM) and onUnmount(fn).

Reading state

dispatch.getViewModel() returns the typed view model — the versioned contract templates bind to, and a superset of getState(). Prefer it. dispatch-theme.d.ts carries autocomplete and the nested shapes.

It carries version (currently 2), channels flattened across zones, counts.panics and calls911, which getState() lacks.

Each view-model user also carries emergencyMode ("alarm", "call", "alarmCall" or null), emergencySilent and emergencyBadge; each transmission carries emergency. Neither call subscribes. getState() returns:

channel: string, scannedChannels: string[], zones: Zone[], pttActive: boolean, channelPttActive: boolean, channelPttFrequency: string, voiceStatus: string, micReady: boolean | null, activeAlerts: Record<string, string>, alertTypes: AlertType[], tones: { id, name }[], patches: Patch[], transmissions: TransmissionEntry[] (last 50), announcementGroups: AnnouncementGroup[], activeAnnouncementGroup: string | null, settings: DispatchSettings, callsign: string, serverName: string, connected: boolean, health: string, authenticated: boolean.

voiceStatus is MUTED, LISTENING, TRANSMITTING, TX (IMBE) or TX (Opus); health is connected, stale or disconnected.

Events

Subscribe with dispatch.on(event, callback). Each fires immediately with current state, so there is no initialization call.

const handler = ({ zones }) => render(zones);
dispatch.on("dispatch:zones", handler);
onUnmount(() => dispatch.off("dispatch:zones", handler));

Actions

dispatch.joinChannel("460.25");       dispatch.leaveChannel();
dispatch.addScan("154.755");          dispatch.removeScan("154.755");
dispatch.startPTT();                  dispatch.stopPTT();
dispatch.startChannelPTT("460.25");   dispatch.stopChannelPTT();
dispatch.activateAnnouncementGroup("group-id");  // null disarms
dispatch.triggerAlert("460.25", "SIGNAL 100");
dispatch.acknowledgePanic(serverId, unitId);     // unitId optional
dispatch.updateSettings({ voiceVolume: 80 });
dispatch.openSettings();              dispatch.closeSettings();

// type: General | Information | Priority | Emergency Alert
dispatch.sendBroadcastAlert({ frequency: "460.25", type: "Priority Alert",
                              message: "All units respond", tone: "PRIORITY" });

await dispatch.createPatch("Tac 1", [460.25, 154.755]); // numbers; -> { ok, error? }
await dispatch.removePatch(dispatch.getViewModel().patches[0].id);

// These four return Promise<boolean>
dispatch.kickUser(serverId);
dispatch.alertUser(serverId, "Message text", frequency);
dispatch.setUserCallsign(serverId, "UNIT-5");
dispatch.switchUserChannel(serverId, "462.45", "460.25"); // (id, newFreq, oldFreq)

PTT no-ops with no active channel, on a canTransmit:false channel, or while another PTT runs. Acknowledgment is per unit: the radio shows Ack received and its alarm stops, but the emergency ends only on an Alarm-mode profile.

DOM control

All of this reverses when the theme changes or the panel unmounts.

theme.setVar("--accent-raw", "#ff6600"); // CSS variable on <html>
theme.removeVar("--accent-raw");
theme.addClass("ptt-active");            // becomes "tj-ptt-active"
theme.removeClass("ptt-active");
theme.hideDefaultUI();                   // hides Header, ZoneList, announcement bar
theme.showDefaultUI();
theme.getContainer();                    // persistent <div> inside .dispatch-app

Variable names: --[a-zA-Z][a-zA-Z0-9-]*, max 60 characters. Class names: [a-zA-Z][a-zA-Z0-9-_]*, max 40, without the tj- prefix. hideDefaultUI() spares the Settings, broadcast and patch modals — overlay portals.

Declarative templates

Annotate HTML with data-rd-* attributes and pass it to theme.mountTemplate(). The binder pushes the view model in, keeps it in sync and reconciles lists by key. No arbitrary JavaScript runs, so template-only themes are safe.

theme.hideDefaultUI();
theme.mountTemplate(`
  <header data-rd-text="serverName"></header>
  <div data-rd-repeat="ch in channels" data-rd-key="ch.id"
       data-rd-class="active:ch.isCurrent"
       data-rd-on="click:join(ch.frequency)">
    <span data-rd-text="ch.name"></span>
    <span data-rd-show="ch.hasPanic">⚠ PANIC</span>
  </div>
`);

mountTemplate handles updates and teardown. reference-panel.html is a styled starting point.

A theme can also ship a template field with no JavaScript: the panel hides its default UI and auto-mounts it. The markup is sanitized at install — <script>, inline on* handlers and javascript: URIs stripped — so it skips review.

Binding attributes

Expressions are dotted paths and literals with a fixed operator set: negation, strict comparison, ordering, && / ||, ternary, grouping and filters. Repeat variables shadow the view model, nested repeats see their parent's scope, and "ch, i in channels" binds an index.

Filters chain left to right as expression | name or | name:arg. The list is fixed; an unknown name passes the value through. Arguments are expressions, so field names need quoting (where:'hasAudio'), and a | inside one ends it.

Template actions (data-rd-on) are a fixed allow-list — the same registry the JS API exposes, so each is also callable as dispatch.<name>(…).

The table lists only arity:

• activateGroup(null) disarms. focusCall911 and openBroadcast take a frequency, acceptCall911 / endCall911 a call id, removePatch a vm.patches[].id
• Creating a patch needs free text, so it is JS-only
• setLogFilter takes 'all', 'monitored' or 'current'. Volume actions take 0–100, and the grammar has no arithmetic, so render discrete steps
• playTransmission / stopTransmission replay buffered audio. Gate on tx.hasAudio, read tx.playing

Reaching what a template cannot express

The binder passes only paths and literals to an action, so it can never read an <input>. Free text, key capture, drag-and-drop and popouts must be delegated.

1. Open a built-in modal. SettingsModal, BroadcastModal, SpeakerBoard and PatchPanel render outside .dispatch-default-ui, so they survive hideDefaultUI().

2. Go hybrid. theme.mountTemplate() works inside jsText, so templates still cover the lists. Mark intent with a plain data-* attribute — unknown ones are ignored — then delegate:

//   <button data-rd-attr="data-alert-user:u.id">Alert…</button>
theme.getContainer().addEventListener("click", (e) => {
  const el = e.target.closest?.("[data-alert-user]");
  if (el) myDialog((msg) => dispatch.alertUser(el.dataset.alertUser, msg, freq));
}, true); // capture phase — see below

The themes folder

A theme is a folder in layouts/themes/ with a module.json declaring what it is and a theme.json of colors. You need both: theme.json alone is not found, module.json alone is skipped.

{ "schema": 1, "kind": "theme", "id": "my-theme", "name": "My Theme",
  "version": "1.0.0", "author": "You", "license": "CC0-1.0" }

{ "id": "my-theme", "cssVars": { "--accent-raw": "#22d3ee" } }

cssVars is the only required field; cssText, jsText, template, slots, requires, extends, font and fontSize are optional. The folder name is the theme's id, and module.json's id must match it exactly.

Radio skins use the same shape with "kind": "layout". Sounds do not: a sound is the audio file alone in layouts/sounds/ (see Adding a sound). sounds and themes are reserved names.

Shipping your own font

Setting --font-sans picks a family; it does not supply one. The panel bundles Poppins and JetBrains Mono and assumes Courier New and Courier. Name anything else and the browser paints the first family it can match — silently, so check its console.

To supply one, put the .woff2 in a fonts/ directory inside your theme and declare it in module.json. --font-sans then resolves, because the panel emits an @font-face per entry.

"theme": { "fonts": [
  { "family": "Inter", "file": "inter-400.woff2", "weight": "400", "license": "OFL-Inter.txt" }
] }

Live authoring

Any dispatch panel exposes window.__tjDev = { dispatch, theme } while you are logged in — the same objects a jsText theme gets. Logging in is the only gate.

window.__tjDev.theme.hideDefaultUI();
window.__tjDev.theme.mountTemplate(`<div data-rd-repeat="zone in zones" data-rd-key="zone.id">…</div>`);
window.__tjDev.dispatch.getViewModel();

Keep the template in DevTools Snippets (Sources → Snippets) rather than retyping it: a multi-line editor that survives reloads, with Ctrl+Enter to re-run. Editing the live DOM in Elements does not work for anything the binder controls — it re-asserts state and overwrites your edits.

Install from the same console, with an active admin session. It appears in Settings → Theme at once; pass the same id later to edit in place.

fetch("/admin/api/themes", {
  method: "POST", credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "My Theme", cssVars: { "--accent-raw": "#22d3ee" } }),
});

Publishing a theme

Submit in the theme editor — tgstudios → Marketplace → Themes → Create Theme. Build against your live panel first (see Live authoring). Every layer composes, so one theme can carry colors, a slot override and JavaScript.

A live preview runs your template or slots against mock data. JavaScript cannot be previewed. Validation errors block submission; warnings do not.

An edit that introduces JavaScript drops the theme back to pending even if already approved. Once live, updates reach installed servers on their next panel refresh. Themes cap at 10 MB and 256 variables.

Security model

Next steps

• Exports, Web API and Socket.IO: API Reference
• Installing a theme someone else published: Themes