Custom System
>
ENCOUNTER RECOVERY
+
Resume Last Encounter?
+
+
Resume where you left off, or begin with a clean encounter. Your
permanent Library, assets, presets, settings, and recovery snapshots
are not deleted when you choose New Encounter.
+
Resume Last Encounter?
>
New Encounter
+
Resume Last Encounter
@@ -490,14 +1055,34 @@
Resume Last Encounter?
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/programs/app/js/core/config.js b/programs/app/js/core/config.js
index 0928f4a..4009739 100644
--- a/programs/app/js/core/config.js
+++ b/programs/app/js/core/config.js
@@ -12,7 +12,7 @@ const ENC = window.ENC;
======================================== */
ENC.APP_NAME = "enCounter";
-ENC.APP_VERSION = "0.1.0-alpha.1";
+ENC.APP_VERSION = "0.2.0-alpha.1";
ENC.APP_STAGE = "Alpha";
/*
@@ -189,6 +189,100 @@ ENC.sanitizeAssetUrl = function (value) {
}
};
+
+ENC.sanitizeAudioUrl = function (value) {
+ const text = String(value || "").trim();
+ if (!text) return "";
+
+ try {
+ const url = new URL(text, window.location.origin);
+ if (url.origin !== window.location.origin) return "";
+ if (!url.pathname.startsWith("/assets/sounds/")) return "";
+ if (!/\.(mp3|ogg|wav|flac)$/i.test(url.pathname)) return "";
+ return url.pathname;
+ } catch {
+ return "";
+ }
+};
+
+ENC.ENCOUNTER_PHASES = new Set(["prepared", "scene", "combat", "complete"]);
+ENC.PLAYER_DISPLAY_MODES = new Set(["standby", "scene", "combat"]);
+
+ENC.normalizeAudioTrack = function (track = {}, defaults = {}) {
+ const source = track && typeof track === "object" ? track : {};
+ const defaultVolume = ENC.finiteNumber(defaults.volume, 0.5);
+ const volume = Math.min(1, Math.max(0, ENC.finiteNumber(source.volume, defaultVolume)));
+ const combatBehavior = ["stop", "continue", "duck"].includes(source.combatBehavior)
+ ? source.combatBehavior
+ : String(defaults.combatBehavior || "stop");
+ const combatVolume = Math.min(1, Math.max(0, ENC.finiteNumber(source.combatVolume, 0.15)));
+
+ return {
+ id: String(source.id || ENC.makeId("audio")),
+ name: String(source.name || defaults.name || "Audio Track").trim() || "Audio Track",
+ asset: ENC.sanitizeAudioUrl(source.asset),
+ volume,
+ loop: source.loop !== false,
+ combatBehavior,
+ combatVolume,
+ };
+};
+
+ENC.createDefaultSoundscape = function () {
+ return {
+ enabled: true,
+ masterVolume: 0.8,
+ fadeMs: 2500,
+ autoSwitchToCombat: true,
+ returnToSceneAfterCombat: true,
+ scene: {
+ music: ENC.normalizeAudioTrack({ name: "Scene Music", loop: true, volume: 0.35 }),
+ ambience: [],
+ },
+ combat: {
+ music: ENC.normalizeAudioTrack({ name: "Combat Music", loop: true, volume: 0.65 }),
+ ambience: [],
+ },
+ cues: [],
+ };
+};
+
+ENC.normalizeSoundscape = function (soundscape = {}) {
+ const source = soundscape && typeof soundscape === "object" ? soundscape : {};
+ const defaults = ENC.createDefaultSoundscape();
+ const scene = source.scene && typeof source.scene === "object" ? source.scene : {};
+ const combat = source.combat && typeof source.combat === "object" ? source.combat : {};
+
+ const normalizeList = (items, defaultBehavior = "stop") =>
+ (Array.isArray(items) ? items : [])
+ .slice(0, 8)
+ .map((item, index) => ENC.normalizeAudioTrack(item, {
+ name: `Ambience ${index + 1}`,
+ volume: 0.4,
+ combatBehavior: defaultBehavior,
+ }));
+
+ return {
+ enabled: source.enabled !== false,
+ masterVolume: Math.min(1, Math.max(0, ENC.finiteNumber(source.masterVolume, defaults.masterVolume))),
+ fadeMs: Math.min(15000, Math.max(0, Math.trunc(ENC.finiteNumber(source.fadeMs, defaults.fadeMs)))),
+ autoSwitchToCombat: source.autoSwitchToCombat !== false,
+ returnToSceneAfterCombat: source.returnToSceneAfterCombat !== false,
+ scene: {
+ music: ENC.normalizeAudioTrack(scene.music || {}, { name: "Scene Music", volume: 0.35, combatBehavior: "stop" }),
+ ambience: normalizeList(scene.ambience, "duck"),
+ },
+ combat: {
+ music: ENC.normalizeAudioTrack(combat.music || {}, { name: "Combat Music", volume: 0.65, combatBehavior: "continue" }),
+ ambience: normalizeList(combat.ambience, "continue"),
+ },
+ cues: (Array.isArray(source.cues) ? source.cues : []).slice(0, 20).map((cue, index) => {
+ const normalized = ENC.normalizeAudioTrack(cue, { name: `Cue ${index + 1}`, volume: 0.8 });
+ return { ...normalized, loop: false };
+ }),
+ };
+};
+
ENC.normalizeSettings = function (settings = {}) {
const source = settings && typeof settings === "object" ? settings : {};
const validModes = new Set(["simple", "standard", "advanced", "custom"]);
@@ -226,12 +320,20 @@ ENC.createDefaultEncounter = function () {
return {
id: "active",
kind: "active",
+ sourceEncounterId: null,
name: "New Encounter",
systemId: "generic",
customProfile: ENC.deepClone(ENC.DEFAULT_SETTINGS.customProfile),
+ phase: "prepared",
+ playerDisplayMode: "standby",
round: 1,
currentId: null,
background: "",
+ display: {
+ sceneImage: "",
+ combatImage: "",
+ },
+ soundscape: ENC.createDefaultSoundscape(),
combatants: [],
updatedAt: new Date().toISOString(),
};
@@ -244,6 +346,11 @@ ENC.isMeaningfulEncounter = function (encounter) {
Number(encounter.round || 1) > 1 ||
Boolean(encounter.currentId) ||
Boolean(encounter.background) ||
+ Boolean(encounter.display?.sceneImage) ||
+ Boolean(encounter.display?.combatImage) ||
+ Boolean(encounter.soundscape?.scene?.music?.asset) ||
+ Boolean(encounter.soundscape?.combat?.music?.asset) ||
+ Boolean(encounter.soundscape?.scene?.ambience?.some?.((track) => track.asset)) ||
String(encounter.name || "").trim().toLowerCase() !== "new encounter",
);
};
@@ -378,7 +485,7 @@ ENC.normalizeCombatant = function (
ENC.normalizeEncounter = function (encounter = {}) {
const source = encounter && typeof encounter === "object" ? encounter : {};
- const kind = source.kind === "preset" ? "preset" : "active";
+ const kind = ["active", "preset", "saved"].includes(source.kind) ? source.kind : "active";
const systemId = ENC.normalizeSystemId(source.systemId || "generic");
const customProfile = ENC.normalizeCustomProfile(source.customProfile);
const combatants = Array.isArray(source.combatants)
@@ -394,15 +501,32 @@ ENC.normalizeEncounter = function (encounter = {}) {
: null;
const rawRound = Number(source.round);
+ const legacyBackground = ENC.sanitizeAssetUrl(source.background);
+ const displaySource = source.display && typeof source.display === "object" ? source.display : {};
+ const combatImage = ENC.sanitizeAssetUrl(displaySource.combatImage || legacyBackground);
+ const sceneImage = ENC.sanitizeAssetUrl(displaySource.sceneImage || legacyBackground);
+ const phase = ENC.ENCOUNTER_PHASES.has(source.phase) ? source.phase : "prepared";
+ const playerDisplayMode = ENC.PLAYER_DISPLAY_MODES.has(source.playerDisplayMode)
+ ? source.playerDisplayMode
+ : "standby";
+
return {
- id: String(source.id || (kind === "active" ? "active" : ENC.makeId("preset"))),
+ id: String(source.id || (kind === "active" ? "active" : ENC.makeId(kind === "saved" ? "enc" : "preset"))),
kind,
- name: String(source.name || (kind === "active" ? "New Encounter" : "Encounter Preset")).trim() || "Encounter",
+ sourceEncounterId: source.sourceEncounterId ? String(source.sourceEncounterId) : null,
+ name: String(source.name || (kind === "active" ? "New Encounter" : "Saved Encounter")).trim() || "Encounter",
systemId,
customProfile,
+ phase,
+ playerDisplayMode,
round: Number.isFinite(rawRound) ? Math.max(1, Math.trunc(rawRound)) : 1,
currentId,
- background: ENC.sanitizeAssetUrl(source.background),
+ background: combatImage,
+ display: {
+ sceneImage,
+ combatImage,
+ },
+ soundscape: ENC.normalizeSoundscape(source.soundscape),
combatants,
updatedAt: String(source.updatedAt || new Date().toISOString()),
};
diff --git a/programs/app/js/core/db.js b/programs/app/js/core/db.js
index 428a3ff..f2027ff 100644
--- a/programs/app/js/core/db.js
+++ b/programs/app/js/core/db.js
@@ -137,6 +137,84 @@ ENC.db = {
return this.put("encounters", ENC.deepClone(normalized));
},
+ async saveEncounterTemplate(encounter, name = null, existingId = null) {
+ const source = ENC.normalizeEncounter(ENC.deepClone(encounter));
+ const templateId = existingId || source.sourceEncounterId || ENC.makeId("enc");
+ const template = ENC.normalizeEncounter({
+ ...source,
+ id: templateId,
+ kind: "saved",
+ sourceEncounterId: null,
+ name: String(name || source.name || "Saved Encounter").trim() || "Saved Encounter",
+ phase: "prepared",
+ playerDisplayMode: "standby",
+ currentId: null,
+ round: 1,
+ combatants: (source.combatants || []).map((combatant) => ({
+ ...combatant,
+ hp: combatant.maxHp ?? combatant.hp ?? "",
+ conditionTrack: "Normal",
+ visibleStatus: "",
+ combatState: "active",
+ delayed: false,
+ ready: false,
+ })),
+ updatedAt: new Date().toISOString(),
+ });
+ template.id = templateId;
+ template.kind = "saved";
+ template.sourceEncounterId = null;
+ await this.put("encounters", template);
+ return template;
+ },
+
+ async getSavedEncounters() {
+ const all = await this.getAll("encounters");
+ return all
+ .filter((item) => item?.kind === "saved")
+ .map((item) => ENC.normalizeEncounter(item))
+ .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+ },
+
+ async loadSavedEncounter(id) {
+ const saved = await this.get("encounters", id);
+ if (!saved || saved.kind !== "saved") return null;
+
+ const working = ENC.normalizeEncounter({
+ ...ENC.deepClone(saved),
+ id: "active",
+ kind: "active",
+ sourceEncounterId: saved.id,
+ phase: "prepared",
+ playerDisplayMode: "standby",
+ currentId: null,
+ round: 1,
+ combatants: (saved.combatants || []).map((combatant) => ({
+ ...combatant,
+ id: ENC.makeId("cmb"),
+ hp: combatant.maxHp ?? combatant.hp ?? "",
+ conditionTrack: "Normal",
+ visibleStatus: "",
+ combatState: "active",
+ hidden: Boolean(combatant.hidden),
+ delayed: false,
+ ready: false,
+ createdOrder: Date.now() + Math.random(),
+ })),
+ });
+ working.id = "active";
+ working.kind = "active";
+ working.sourceEncounterId = saved.id;
+ await this.saveActiveEncounter(working);
+ return working;
+ },
+
+ async duplicateSavedEncounter(id) {
+ const saved = await this.get("encounters", id);
+ if (!saved || saved.kind !== "saved") return null;
+ return this.saveEncounterTemplate(saved, `${saved.name} Copy`, null);
+ },
+
async savePreset(encounter, name) {
const preset = ENC.normalizeEncounter({
...ENC.deepClone(encounter),
diff --git a/programs/app/js/display.js b/programs/app/js/display.js
index 97c6c1d..de85345 100644
--- a/programs/app/js/display.js
+++ b/programs/app/js/display.js
@@ -9,8 +9,13 @@ ENC.display = {
lastDmSeenAt: 0,
connectionTimer: null,
- // Player Display privacy state
- paused: false,
+ // Visual Timer state
+ timerRenderer: null,
+ timerController: null,
+
+ // Player Display presentation state
+ displayMode: "standby",
+ paused: true,
awaitingDmState: true,
/* ========================================
@@ -19,6 +24,7 @@ ENC.display = {
async load() {
this.encounter = ENC.normalizeEncounter(await ENC.db.getActiveEncounter());
+
this.render();
},
@@ -31,11 +37,17 @@ ENC.display = {
return ENC.isTurnEligibleCombatant(combatant);
},
+ /* ========================================
+ CONNECTION STATUS
+ ======================================== */
+
setConnectionState(state) {
const indicator = document.getElementById("displayConnectionStatus");
+
if (!indicator) return;
indicator.classList.remove("connecting", "connected", "disconnected");
+
indicator.classList.add(state);
const labels = {
@@ -43,40 +55,238 @@ ENC.display = {
connected: "DM SYNC: CONNECTED",
disconnected: "DM SYNC: DISCONNECTED",
};
+
indicator.textContent = labels[state] || labels.disconnected;
},
markDmSeen() {
this.lastDmSeenAt = Date.now();
+
this.setConnectionState("connected");
},
/* ========================================
- PLAYER DISPLAY PRIVACY
-======================================== */
+ PLAYER DISPLAY PRIVACY
+ ======================================== */
+
+ setDisplayMode(mode) {
+ this.displayMode = ENC.PLAYER_DISPLAY_MODES.has(mode) ? mode : "standby";
+ this.paused = this.displayMode === "standby";
+ document.body.dataset.displayMode = this.displayMode;
+
+ const overlay = document.getElementById("playerDisplayPrivacyOverlay");
+ if (overlay) overlay.classList.toggle("show", this.paused || this.awaitingDmState);
+
+ this.updateTimerLayer();
+ if (!this.paused && !this.awaitingDmState) this.render();
+ },
setPaused(paused) {
this.paused = Boolean(paused);
+ if (this.paused) this.displayMode = "standby";
+ else if (this.displayMode === "standby") this.displayMode = this.encounter?.phase === "combat" ? "combat" : "scene";
+ document.body.dataset.displayMode = this.displayMode;
const overlay = document.getElementById("playerDisplayPrivacyOverlay");
- if (!overlay) return;
+ if (overlay) {
+ overlay.classList.toggle("show", this.paused || this.awaitingDmState);
+ }
+
+ /*
+ * Also hide the visual timer while the
+ * Player Display privacy screen is active.
+ */
+ this.updateTimerLayer();
+ },
+
+ /* ========================================
+ VISUAL TIMER
+ ======================================== */
+
+ initializeTimer() {
+ if (!ENC.timerRenderer || typeof ENC.timerRenderer.create !== "function") {
+ throw new Error(
+ "Timer renderer did not load. Check js/modules/timer-renderer.js.",
+ );
+ }
+
+ if (!ENC.timer || typeof ENC.timer.create !== "function") {
+ throw new Error("Timer engine did not load. Check js/modules/timer.js.");
+ }
+
+ const timerContainer = document.getElementById("playerTimer");
+
+ if (!timerContainer) {
+ throw new Error("Player Display timer container was not found.");
+ }
+
+ /*
+ * Create one renderer for the Player Display.
+ *
+ * Overlay / Featured / Focus all reuse this
+ * same renderer. We simply change the outer
+ * layer classes.
+ */
+ this.timerRenderer = ENC.timerRenderer.create(timerContainer);
+
+ this.timerController = ENC.timer.create({
+ renderer: this.timerRenderer,
+
+ audience: "player",
+
+ initialState: {
+ id: "primary-timer",
+
+ name: "Countdown",
+
+ mode: "countdown",
+
+ skin: "hourglass",
+
+ durationMs: ENC.timer.DEFAULT_DURATION_MS || 300000,
+
+ remainingMs: ENC.timer.DEFAULT_DURATION_MS || 300000,
+
+ endAt: null,
+
+ status: "idle",
+
+ visibleToPlayers: false,
+
+ showNumericToDM: true,
+
+ showNumericToPlayers: false,
+
+ displayMode: "overlay",
+ },
+
+ /*
+ * The Player Display never owns timer
+ * state and never broadcasts changes.
+ *
+ * The DM Console is authoritative.
+ */
+ onComplete: () => {
+ this.updateTimerLayer();
+ },
+ });
+
+ this.updateTimerLayer();
+ },
+
+ /* ----------------------------------------
+ APPLY TIMER STATE FROM DM
+ ---------------------------------------- */
+
+ applyTimerState(timerState) {
+ if (!this.timerController || !timerState) {
+ return;
+ }
+
+ /*
+ * applyRemoteState() updates the Player
+ * timer without causing another broadcast.
+ *
+ * If the timer is running, the shared endAt
+ * value allows this window to independently
+ * calculate the correct remaining time.
+ */
+ this.timerController.applyRemoteState(timerState);
+
+ this.updateTimerLayer();
+ },
+
+ /* ----------------------------------------
+ SHOW / HIDE PLAYER TIMER
+ ---------------------------------------- */
+
+ updateTimerLayer() {
+ const layer = document.getElementById("playerTimerLayer");
+
+ if (!layer) {
+ return;
+ }
+
+ const state = this.timerController?.getState() || null;
+
+ /*
+ * Timer visibility requires all three:
+ *
+ * 1. DM selected Show Timer to Players.
+ * 2. Player Display itself is not hidden.
+ * 3. Initial DM state has been received.
+ */
+ const visible =
+ Boolean(state?.visibleToPlayers) && !this.paused && !this.awaitingDmState;
+
+ const mode = state?.displayMode || "overlay";
+
+ /*
+ * Remove all prior mode classes.
+ *
+ * The exact timer visual remains mounted
+ * inside #playerTimer.
+ */
+ layer.className = "";
+
+ /* --------------------------------------
+ FOCUS MODE
+ -------------------------------------- */
+
+ if (mode === "focus") {
+ layer.classList.add("player-timer-focus");
+
+ if (visible) {
+ layer.classList.add("show");
+ }
+ } else {
+ /* --------------------------------------
+ OVERLAY / FEATURED MODE
+ -------------------------------------- */
+ layer.classList.add("player-timer-overlay");
+
+ if (mode === "featured") {
+ layer.classList.add("timer-mode-featured");
+ }
+
+ if (!visible) {
+ layer.classList.add("timer-overlay-hidden");
+ }
+ }
+
+ /*
+ * The hidden property prevents an invisible
+ * timer from intercepting mouse events or
+ * occupying accessible UI.
+ */
+ layer.hidden = !visible;
- overlay.classList.toggle("show", this.paused || this.awaitingDmState);
+ layer.setAttribute("aria-hidden", visible ? "false" : "true");
},
+ /* ========================================
+ REQUEST DM PRESENCE
+ ======================================== */
+
requestDmPresence() {
- ENC.sync.broadcast("display-hello", { sentAt: Date.now() });
+ ENC.sync.broadcast("display-hello", {
+ sentAt: Date.now(),
+ });
},
startConnectionMonitor() {
this.setConnectionState("connecting");
+
this.requestDmPresence();
clearInterval(this.connectionTimer);
+
this.connectionTimer = setInterval(() => {
this.requestDmPresence();
+
const age = this.lastDmSeenAt ? Date.now() - this.lastDmSeenAt : Infinity;
+
if (age > ENC.DM_PRESENCE_TIMEOUT_MS) {
this.setConnectionState("disconnected");
}
@@ -153,51 +363,84 @@ ENC.display = {
this.updateIdleLogo(false);
},
+ /* ========================================
+ SCENE / ROLEPLAY DISPLAY
+ ======================================== */
+
+ renderScene() {
+ if (!this.encounter) {
+ this.renderStandby();
+ return;
+ }
+
+ document.body.dataset.displayMode = "scene";
+ const background = document.getElementById("displayBackground");
+ const sceneImage = this.encounter.display?.sceneImage || this.encounter.background || "";
+ if (background) background.style.backgroundImage = sceneImage ? `url("${sceneImage}")` : "";
+ const name = document.getElementById("displayEncounterName");
+ if (name) name.textContent = this.encounter.name || "Scene";
+ this.updateIdleLogo(Boolean(sceneImage));
+ },
+
/* ========================================
MAIN RENDER
======================================== */
render() {
+ /*
+ * Do not render encounter changes behind
+ * the DM-controlled privacy screen.
+ */
if (this.paused || this.awaitingDmState) {
return;
}
+
+ if (this.displayMode === "scene") {
+ this.renderScene();
+ return;
+ }
+
+ document.body.dataset.displayMode = "combat";
+
/* ----------------------------------------
- No active encounter
- ---------------------------------------- */
+ No active encounter
+ ---------------------------------------- */
if (!this.encounter) {
this.renderStandby();
+
return;
}
/* ----------------------------------------
- Make sure combatants array exists
- ---------------------------------------- */
+ Make sure combatants array exists
+ ---------------------------------------- */
if (!Array.isArray(this.encounter.combatants)) {
this.encounter.combatants = [];
}
/* ----------------------------------------
- Sort initiative
- ---------------------------------------- */
+ Sort initiative
+ ---------------------------------------- */
ENC.sortCombatants(this.encounter.combatants);
/* ----------------------------------------
- Determine player-visible state
- ---------------------------------------- */
+ Determine player-visible state
+ ---------------------------------------- */
const visibleCombatants = ENC.getPlayerVisibleCombatants(
this.encounter.combatants,
);
+
const hasVisibleCombatants = visibleCombatants.length > 0;
this.updateIdleLogo(hasVisibleCombatants);
/* ----------------------------------------
- Encounter header
- ---------------------------------------- */
+ Encounter header
+ ---------------------------------------- */
document.getElementById("displayEncounterName").textContent =
this.encounter.name || "New Encounter";
@@ -211,28 +454,29 @@ ENC.display = {
this.encounter.round || 1;
/* ----------------------------------------
- Encounter background
- ---------------------------------------- */
+ Encounter background
+ ---------------------------------------- */
const background = document.getElementById("displayBackground");
- if (this.encounter.background) {
- background.style.backgroundImage = `url("${this.encounter.background}")`;
+ const combatImage = this.encounter.display?.combatImage || this.encounter.background || "";
+ if (combatImage) {
+ background.style.backgroundImage = `url("${combatImage}")`;
} else {
background.style.backgroundImage = "";
}
/* ----------------------------------------
- Initiative track
- ---------------------------------------- */
+ Initiative track
+ ---------------------------------------- */
const track = document.getElementById("initiativeTrack");
track.innerHTML = "";
/* ----------------------------------------
- No combatants yet
- ---------------------------------------- */
+ No combatants yet
+ ---------------------------------------- */
if (!hasVisibleCombatants) {
document.getElementById("currentName").textContent =
@@ -244,21 +488,21 @@ ENC.display = {
}
/* ----------------------------------------
- Find current combatant
- ---------------------------------------- */
+ Find current combatant
+ ---------------------------------------- */
const currentIndex = this.encounter.combatants.findIndex(
(combatant) => combatant.id === this.encounter.currentId,
);
/* ========================================
- BUILD INITIATIVE CARDS
- ======================================== */
+ BUILD INITIATIVE CARDS
+ ======================================== */
for (const combatant of visibleCombatants) {
/* ------------------------------------
- Card
- ------------------------------------ */
+ Card
+ ------------------------------------ */
const card = document.createElement("article");
@@ -266,8 +510,8 @@ ENC.display = {
`initiative-card ` + `${combatant.type} ` + `${combatant.combatState}`;
/* ------------------------------------
- Current turn highlighting
- ------------------------------------ */
+ Current turn highlighting
+ ------------------------------------ */
if (
combatant.id === this.encounter.currentId &&
@@ -277,8 +521,8 @@ ENC.display = {
}
/* ------------------------------------
- Portrait
- ------------------------------------ */
+ Portrait
+ ------------------------------------ */
const portrait = document.createElement("div");
@@ -297,8 +541,8 @@ ENC.display = {
}
/* ------------------------------------
- Name
- ------------------------------------ */
+ Name
+ ------------------------------------ */
const name = document.createElement("div");
@@ -307,8 +551,8 @@ ENC.display = {
name.textContent = combatant.name;
/* ------------------------------------
- Initiative
- ------------------------------------ */
+ Initiative
+ ------------------------------------ */
const initiative = document.createElement("div");
@@ -323,8 +567,8 @@ ENC.display = {
initiative.append(document.createTextNode(combatant.initiative));
/* ------------------------------------
- Status badges
- ------------------------------------ */
+ Status badges
+ ------------------------------------ */
const badges = document.createElement("div");
@@ -380,8 +624,8 @@ ENC.display = {
}
/* ------------------------------------
- Assemble card
- ------------------------------------ */
+ Assemble card
+ ------------------------------------ */
card.append(portrait, name, initiative, badges);
@@ -389,11 +633,12 @@ ENC.display = {
}
/* ========================================
- CURRENT TURN
- ======================================== */
+ CURRENT TURN
+ ======================================== */
const current =
currentIndex >= 0 ? this.encounter.combatants[currentIndex] : null;
+
const currentIsVisible =
ENC.isPlayerVisibleCombatant(current) && this.isTurnEligible(current);
@@ -404,8 +649,8 @@ ENC.display = {
: "Waiting for combat…";
/* ========================================
- NEXT TURN
- ======================================== */
+ NEXT TURN
+ ======================================== */
const next =
currentIndex >= 0 ? this.nextActive(this.encounter.currentId) : null;
@@ -413,8 +658,8 @@ ENC.display = {
document.getElementById("nextName").textContent = next ? next.name : "—";
/* ========================================
- CENTER CURRENT CARD
- ======================================== */
+ CENTER CURRENT CARD
+ ======================================== */
setTimeout(() => {
document.querySelector(".initiative-card.current")?.scrollIntoView({
@@ -431,20 +676,21 @@ ENC.display = {
bind() {
/* ----------------------------------------
- DM -> Player synchronization
- ---------------------------------------- */
+ DM -> Player synchronization
+ ---------------------------------------- */
ENC.sync.onMessage((message) => {
- // ========================================
+ // =====================================
// DM PRESENCE / INITIAL DISPLAY STATE
- // ========================================
+ // =====================================
if (message.type === "dm-presence") {
this.markDmSeen();
/*
- * We now know whether the DM wants the
- * Player Display visible or hidden.
+ * We now know whether the DM wants
+ * the Player Display visible or
+ * hidden.
*/
this.awaitingDmState = false;
@@ -452,7 +698,26 @@ ENC.display = {
this.encounter = ENC.normalizeEncounter(message.encounter);
}
- this.setPaused(Boolean(message.playerDisplayPaused));
+ this.setDisplayMode(
+ message.playerDisplayMode ||
+ (message.playerDisplayPaused
+ ? "standby"
+ : this.encounter?.phase === "combat"
+ ? "combat"
+ : "scene"),
+ );
+
+ /*
+ * main.js will include the current
+ * timer state in dm-presence.
+ *
+ * This allows a Player Display opened
+ * halfway through an active countdown
+ * to immediately catch up.
+ */
+ if (message.timer) {
+ this.applyTimerState(message.timer);
+ }
if (!this.paused) {
this.render();
@@ -461,9 +726,22 @@ ENC.display = {
return;
}
- // ========================================
- // HIDE / SHOW PLAYER DISPLAY
- // ========================================
+ // =====================================
+ // PLAYER DISPLAY MODE
+ // =====================================
+
+ if (message.type === "player-display-mode") {
+ this.markDmSeen();
+ this.awaitingDmState = false;
+ if (message.encounter) this.encounter = ENC.normalizeEncounter(message.encounter);
+ if (message.timer) this.applyTimerState(message.timer);
+ this.setDisplayMode(message.mode || "standby");
+ return;
+ }
+
+ // =====================================
+ // HIDE / SHOW PLAYER DISPLAY (LEGACY)
+ // =====================================
if (message.type === "player-display-visibility") {
this.markDmSeen();
@@ -471,8 +749,9 @@ ENC.display = {
this.awaitingDmState = false;
/*
- * main.js includes the newest encounter
- * when changing display visibility.
+ * main.js includes the newest
+ * encounter when changing display
+ * visibility.
*/
if (message.encounter) {
this.encounter = ENC.normalizeEncounter(message.encounter);
@@ -480,6 +759,15 @@ ENC.display = {
this.setPaused(Boolean(message.paused));
+ /*
+ * Refresh the timer from the DM's
+ * authoritative state whenever the
+ * Player Display is hidden or shown.
+ */
+ if (message.timer) {
+ this.applyTimerState(message.timer);
+ }
+
/*
* When Show Player Display is pressed,
* immediately render the newest state.
@@ -491,9 +779,23 @@ ENC.display = {
return;
}
- // ========================================
+ // =====================================
+ // VISUAL TIMER UPDATES
+ // =====================================
+
+ if (message.type === "timer-state") {
+ this.markDmSeen();
+
+ if (message.timer) {
+ this.applyTimerState(message.timer);
+ }
+
+ return;
+ }
+
+ // =====================================
// NORMAL ENCOUNTER UPDATES
- // ========================================
+ // =====================================
if (message.type === "encounter-updated") {
this.markDmSeen();
@@ -505,8 +807,8 @@ ENC.display = {
this.encounter = ENC.normalizeEncounter(message.encounter || {});
/*
- * But never render private changes while
- * the privacy screen is active.
+ * But never render private changes
+ * while the privacy screen is active.
*/
if (!this.paused && !this.awaitingDmState) {
this.render();
@@ -519,8 +821,8 @@ ENC.display = {
this.startConnectionMonitor();
/* ----------------------------------------
- Fullscreen
- ---------------------------------------- */
+ Fullscreen
+ ---------------------------------------- */
document
.getElementById("fullscreenBtn")
@@ -540,11 +842,20 @@ ENC.display = {
document.addEventListener("DOMContentLoaded", async () => {
const versionElement = document.getElementById("playerAppVersion");
+
if (versionElement) {
- versionElement.textContent = `${ENC.APP_STAGE.toUpperCase()} · v${ENC.APP_VERSION}`;
+ versionElement.textContent =
+ `${ENC.APP_STAGE.toUpperCase()} · ` + `v${ENC.APP_VERSION}`;
}
await ENC.db.open();
+ document.body.dataset.displayMode = "standby";
+
+ /*
+ * Timer modules must already be loaded by
+ * display.html before display.js executes.
+ */
+ ENC.display.initializeTimer();
ENC.display.bind();
diff --git a/programs/app/js/main.js b/programs/app/js/main.js
index ed6d005..c6a8d58 100644
--- a/programs/app/js/main.js
+++ b/programs/app/js/main.js
@@ -6,10 +6,13 @@
ENC.app = {
toastTimer: null,
- playerDisplayPaused: false,
+ playerDisplayPaused: true,
+ playerDisplayMode: "standby",
playerDisplayConnected: false,
playerDisplayWindow: null,
playerDisplayWatchTimer: null,
+ timerPreviewRenderer: null,
+ timerController: null,
toast(message) {
const toast = document.getElementById("toast");
@@ -28,14 +31,95 @@ ENC.app = {
announceDmPresence(includeEncounter = false) {
ENC.sync.broadcast("dm-presence", {
sentAt: Date.now(),
- playerDisplayPaused: this.playerDisplayPaused,
+
+ playerDisplayPaused: this.playerDisplayMode === "standby",
+ playerDisplayMode: this.playerDisplayMode,
+
encounter:
includeEncounter && ENC.combat?.encounter
? ENC.deepClone(ENC.combat.encounter)
: null,
+
+ /*
+ * Include the current timer state so a
+ * Player Display opened after the timer
+ * has already started immediately joins
+ * at the correct point.
+ */
+ timer: this.getTimerSyncState(),
+ });
+ },
+
+ getTimerSyncState() {
+ if (!this.timerController) {
+ return null;
+ }
+
+ const state = this.timerController.getState();
+
+ if (!state) {
+ return null;
+ }
+
+ /*
+ * Timer state only contains plain data,
+ * but clone it so the synchronization
+ * layer never shares a mutable reference
+ * with the DM timer controller.
+ */
+ return ENC.deepClone(state);
+ },
+
+ broadcastTimerState(timerState = null) {
+ const state = timerState || this.getTimerSyncState();
+
+ if (!state) {
+ return;
+ }
+
+ ENC.sync.broadcast("timer-state", {
+ sentAt: Date.now(),
+
+ timer: ENC.deepClone(state),
+ });
+ },
+
+ broadcastDisplayState() {
+ ENC.sync.broadcast("player-display-mode", {
+ sentAt: Date.now(),
+ mode: this.playerDisplayMode,
+ encounter: ENC.combat?.encounter ? ENC.deepClone(ENC.combat.encounter) : null,
+ timer: this.getTimerSyncState(),
});
},
+ setPlayerDisplayMode(mode) {
+ const next = ENC.PLAYER_DISPLAY_MODES.has(mode) ? mode : "standby";
+ this.playerDisplayMode = next;
+ this.playerDisplayPaused = next === "standby";
+ if (ENC.combat?.encounter) {
+ ENC.combat.encounter.playerDisplayMode = next;
+ ENC.db.saveActiveEncounter(ENC.combat.encounter).catch((error) => console.warn("Could not persist display mode", error));
+ }
+ this.broadcastDisplayState();
+ this.updatePlayerDisplayButton();
+ ENC.encounterUI?.renderPhase?.();
+ },
+
+ refreshEncounterMediaControls() {
+ if (!ENC.combat?.encounter) return;
+ ENC.assets.fillSelect(
+ document.getElementById("backgroundSelect"),
+ "backgrounds/",
+ ENC.combat.encounter.display?.combatImage || ENC.combat.encounter.background || "",
+ );
+ ENC.assets.fillSelect(
+ document.getElementById("sceneImageSelect"),
+ "backgrounds/",
+ ENC.combat.encounter.display?.sceneImage || ENC.combat.encounter.background || "",
+ );
+ },
+
updatePlayerDisplayButton() {
const button = document.getElementById("openDisplayBtn");
@@ -49,11 +133,9 @@ ENC.app = {
return;
}
- if (this.playerDisplayPaused) {
+ if (this.playerDisplayMode === "standby") {
button.textContent = "Show Player Display";
-
button.classList.add("player-display-paused");
-
return;
}
@@ -76,13 +158,438 @@ ENC.app = {
this.playerDisplayWatchTimer = null;
this.playerDisplayWindow = null;
this.playerDisplayConnected = false;
- this.playerDisplayPaused = false;
this.updatePlayerDisplayButton();
}
}, 1000);
},
+ // ========================================
+ // VISUAL TIMER
+ // ========================================
+
+ getTimerDurationFromInputs() {
+ const minutesInput = document.getElementById("timerMinutes");
+ const secondsInput = document.getElementById("timerSeconds");
+
+ if (!minutesInput || !secondsInput) {
+ return 0;
+ }
+
+ const rawMinutes = Number(minutesInput.value);
+ const rawSeconds = Number(secondsInput.value);
+
+ const minutes = Number.isFinite(rawMinutes)
+ ? Math.max(0, Math.floor(rawMinutes))
+ : 0;
+
+ const seconds = Number.isFinite(rawSeconds)
+ ? Math.min(59, Math.max(0, Math.floor(rawSeconds)))
+ : 0;
+
+ minutesInput.value = String(minutes);
+ secondsInput.value = String(seconds);
+
+ return (minutes * 60 + seconds) * 1000;
+ },
+
+ setTimerDurationInputs(milliseconds) {
+ const minutesInput = document.getElementById("timerMinutes");
+ const secondsInput = document.getElementById("timerSeconds");
+
+ if (!minutesInput || !secondsInput) {
+ return;
+ }
+
+ const totalSeconds = Math.max(
+ 0,
+ Math.ceil(Number(milliseconds || 0) / 1000),
+ );
+
+ const minutes = Math.floor(totalSeconds / 60);
+ const seconds = totalSeconds % 60;
+
+ minutesInput.value = String(minutes);
+ secondsInput.value = String(seconds);
+ },
+
+ formatTimerStatus(state) {
+ if (!state) {
+ return "Unavailable";
+ }
+
+ if (state.status === "running") {
+ return "Running";
+ }
+
+ if (state.status === "paused") {
+ return "Paused";
+ }
+
+ if (state.status === "complete") {
+ return "Complete";
+ }
+
+ if (state.status === "idle" && state.remainingMs < state.durationMs) {
+ return "Stopped";
+ }
+
+ return "Ready";
+ },
+
+ updateTimerUI() {
+ if (!this.timerController) {
+ return;
+ }
+
+ const state = this.timerController.getState();
+
+ if (!state) {
+ return;
+ }
+
+ const activeName = document.getElementById("timerActiveName");
+ const statusText = document.getElementById("timerStatusText");
+
+ if (activeName) {
+ activeName.textContent = state.name || "Countdown";
+ }
+
+ if (statusText) {
+ statusText.textContent = this.formatTimerStatus(state);
+ }
+
+ const startButton = document.getElementById("timerStartBtn");
+ const pauseButton = document.getElementById("timerPauseBtn");
+ const resumeButton = document.getElementById("timerResumeBtn");
+ const resetButton = document.getElementById("timerResetBtn");
+ const stopButton = document.getElementById("timerStopBtn");
+
+ if (startButton) {
+ startButton.disabled =
+ state.status === "running" || state.status === "paused";
+ }
+
+ if (pauseButton) {
+ pauseButton.disabled = state.status !== "running";
+ }
+
+ if (resumeButton) {
+ resumeButton.disabled = state.status !== "paused";
+ }
+
+ if (resetButton) {
+ resetButton.disabled = false;
+ }
+
+ if (stopButton) {
+ stopButton.disabled =
+ state.status === "idle" || state.status === "complete";
+ }
+
+ const durationLocked =
+ state.status === "running" || state.status === "paused";
+
+ const minutesInput = document.getElementById("timerMinutes");
+ const secondsInput = document.getElementById("timerSeconds");
+
+ if (minutesInput) {
+ minutesInput.disabled = durationLocked;
+ }
+
+ if (secondsInput) {
+ secondsInput.disabled = durationLocked;
+ }
+
+ /*
+ * Keep the configured duration fields aligned with the timer
+ * engine. Adding time can expand durationMs when the new
+ * remaining time exceeds the original configured duration.
+ */
+ if (!durationLocked) {
+ this.setTimerDurationInputs(state.durationMs);
+ }
+ },
+
+ initializeTimer() {
+ if (!ENC.timerRenderer || typeof ENC.timerRenderer.create !== "function") {
+ throw new Error(
+ "Timer renderer did not load. Check js/modules/timer-renderer.js.",
+ );
+ }
+
+ if (!ENC.timer || typeof ENC.timer.create !== "function") {
+ throw new Error("Timer engine did not load. Check js/modules/timer.js.");
+ }
+
+ const previewContainer = document.getElementById("timerPreview");
+
+ if (!previewContainer) {
+ throw new Error("Timer preview container was not found.");
+ }
+
+ const initialDuration =
+ this.getTimerDurationFromInputs() ||
+ ENC.timer.DEFAULT_DURATION_MS ||
+ 300000;
+
+ this.timerPreviewRenderer = ENC.timerRenderer.create(previewContainer);
+
+ this.timerController = ENC.timer.create({
+ renderer: this.timerPreviewRenderer,
+ audience: "dm",
+
+ initialState: {
+ id: "primary-timer",
+ name: document.getElementById("timerName")?.value.trim() || "Countdown",
+ mode: "countdown",
+ skin: document.getElementById("timerSkin")?.value || "hourglass",
+ durationMs: initialDuration,
+ remainingMs: initialDuration,
+ status: "idle",
+ visibleToPlayers:
+ document.getElementById("timerShowPlayers")?.checked === true,
+ showNumericToDM:
+ document.getElementById("timerShowNumericDM")?.checked !== false,
+ showNumericToPlayers:
+ document.getElementById("timerShowNumericPlayers")?.checked === true,
+ displayMode:
+ document.getElementById("timerDisplayMode")?.value || "overlay",
+ },
+
+ onStateChange: (timerState, reason) => {
+ /*
+ * Keep the DM controls/status synchronized
+ * with the timer controller.
+ */
+ this.updateTimerUI();
+
+ /*
+ * Send state changes to the Player Display.
+ *
+ * We do NOT transmit animation frames.
+ * The Player Display animates independently
+ * using the shared endAt timestamp.
+ */
+ this.broadcastTimerState(timerState);
+
+ console.debug("Timer state changed:", reason, timerState);
+ },
+
+ onComplete: (timerState) => {
+ this.updateTimerUI();
+
+ /*
+ * Ensure the Player Display receives the
+ * final completed state immediately.
+ */
+ this.broadcastTimerState(timerState);
+
+ this.toast("Timer complete.");
+ },
+ });
+
+ this.updateTimerUI();
+ },
+
+ bindTimerControls() {
+ if (!this.timerController) {
+ return;
+ }
+
+ const timerName = document.getElementById("timerName");
+ const timerSkin = document.getElementById("timerSkin");
+ const timerDisplayMode = document.getElementById("timerDisplayMode");
+
+ const showPlayers = document.getElementById("timerShowPlayers");
+ const showNumericPlayers = document.getElementById(
+ "timerShowNumericPlayers",
+ );
+ const showNumericDM = document.getElementById("timerShowNumericDM");
+
+ const minutesInput = document.getElementById("timerMinutes");
+ const secondsInput = document.getElementById("timerSeconds");
+
+ const startButton = document.getElementById("timerStartBtn");
+ const pauseButton = document.getElementById("timerPauseBtn");
+ const resumeButton = document.getElementById("timerResumeBtn");
+ const resetButton = document.getElementById("timerResetBtn");
+ const stopButton = document.getElementById("timerStopBtn");
+
+ const subtractMinuteButton = document.getElementById(
+ "timerSubtractMinuteBtn",
+ );
+ const subtractTenButton = document.getElementById("timerSubtractTenBtn");
+ const addTenButton = document.getElementById("timerAddTenBtn");
+ const addMinuteButton = document.getElementById("timerAddMinuteBtn");
+
+ const applyDurationIfEditable = () => {
+ const state = this.timerController.getState();
+
+ if (!state) {
+ return false;
+ }
+
+ if (state.status === "running" || state.status === "paused") {
+ return false;
+ }
+
+ const durationMs = this.getTimerDurationFromInputs();
+
+ if (durationMs <= 0) {
+ this.toast("Timer duration must be greater than zero.");
+ this.setTimerDurationInputs(state.durationMs);
+ return false;
+ }
+
+ if (durationMs !== state.durationMs) {
+ this.timerController.setDuration(durationMs);
+ }
+
+ return true;
+ };
+
+ if (timerName) {
+ timerName.addEventListener("input", () => {
+ this.timerController.setName(timerName.value);
+ });
+ }
+
+ if (timerSkin) {
+ timerSkin.addEventListener("change", () => {
+ this.timerController.setSkin(timerSkin.value);
+ });
+ }
+
+ if (timerDisplayMode) {
+ timerDisplayMode.addEventListener("change", () => {
+ this.timerController.setDisplayMode(timerDisplayMode.value);
+ });
+ }
+
+ if (showPlayers) {
+ showPlayers.addEventListener("change", () => {
+ this.timerController.setVisibleToPlayers(showPlayers.checked);
+ });
+ }
+
+ if (showNumericPlayers) {
+ showNumericPlayers.addEventListener("change", () => {
+ this.timerController.setShowNumericToPlayers(
+ showNumericPlayers.checked,
+ );
+ });
+ }
+
+ if (showNumericDM) {
+ showNumericDM.addEventListener("change", () => {
+ this.timerController.setShowNumericToDM(showNumericDM.checked);
+ });
+ }
+
+ if (minutesInput) {
+ minutesInput.addEventListener("change", applyDurationIfEditable);
+ }
+
+ if (secondsInput) {
+ secondsInput.addEventListener("change", applyDurationIfEditable);
+ }
+
+ if (startButton) {
+ startButton.addEventListener("click", () => {
+ const state = this.timerController.getState();
+
+ if (!state) {
+ return;
+ }
+
+ if (state.status === "paused") {
+ return;
+ }
+
+ /*
+ * If the configured duration fields changed while the
+ * timer was idle/complete, apply them before starting.
+ *
+ * A stopped timer preserves its remaining time when the
+ * duration fields still match the configured duration.
+ */
+ const requestedDuration = this.getTimerDurationFromInputs();
+
+ if (requestedDuration <= 0) {
+ this.toast("Timer duration must be greater than zero.");
+ return;
+ }
+
+ if (
+ state.status === "complete" ||
+ requestedDuration !== state.durationMs
+ ) {
+ this.timerController.setDuration(requestedDuration);
+ }
+
+ this.timerController.start();
+ this.updateTimerUI();
+ });
+ }
+
+ if (pauseButton) {
+ pauseButton.addEventListener("click", () => {
+ this.timerController.pause();
+ this.updateTimerUI();
+ });
+ }
+
+ if (resumeButton) {
+ resumeButton.addEventListener("click", () => {
+ this.timerController.resume();
+ this.updateTimerUI();
+ });
+ }
+
+ if (resetButton) {
+ resetButton.addEventListener("click", () => {
+ this.timerController.reset();
+ this.updateTimerUI();
+ });
+ }
+
+ if (stopButton) {
+ stopButton.addEventListener("click", () => {
+ this.timerController.stop();
+ this.updateTimerUI();
+ });
+ }
+
+ if (subtractMinuteButton) {
+ subtractMinuteButton.addEventListener("click", () => {
+ this.timerController.subtractTime(60_000);
+ this.updateTimerUI();
+ });
+ }
+
+ if (subtractTenButton) {
+ subtractTenButton.addEventListener("click", () => {
+ this.timerController.subtractTime(10_000);
+ this.updateTimerUI();
+ });
+ }
+
+ if (addTenButton) {
+ addTenButton.addEventListener("click", () => {
+ this.timerController.addTime(10_000);
+ this.updateTimerUI();
+ });
+ }
+
+ if (addMinuteButton) {
+ addMinuteButton.addEventListener("click", () => {
+ this.timerController.addTime(60_000);
+ this.updateTimerUI();
+ });
+ }
+ },
+
bindAppControls() {
// ========================================
// PLAYER DISPLAY
@@ -99,8 +606,6 @@ ENC.app = {
// ------------------------------------
if (!this.playerDisplayConnected) {
- this.playerDisplayPaused = false;
-
const displayWindow = window.open(
"/programs/app/display.html",
"enCounterPlayerDisplay",
@@ -124,28 +629,17 @@ ENC.app = {
}
// ------------------------------------
- // HIDE / SHOW EXISTING PLAYER DISPLAY
+ // HIDE / RESTORE EXISTING PLAYER DISPLAY
// ------------------------------------
- this.playerDisplayPaused = !this.playerDisplayPaused;
-
- ENC.sync.broadcast("player-display-visibility", {
- sentAt: Date.now(),
-
- paused: this.playerDisplayPaused,
-
- encounter: ENC.combat?.encounter
- ? ENC.deepClone(ENC.combat.encounter)
- : null,
- });
-
- this.updatePlayerDisplayButton();
-
- this.toast(
- this.playerDisplayPaused
- ? "Player Display hidden. DM changes are private."
- : "Player Display restored with the latest encounter.",
- );
+ if (this.playerDisplayMode === "standby") {
+ const phase = ENC.combat?.encounter?.phase;
+ this.setPlayerDisplayMode(phase === "combat" ? "combat" : "scene");
+ this.toast("Player Display restored.");
+ } else {
+ this.setPlayerDisplayMode("standby");
+ this.toast("Player Display hidden. DM changes are private.");
+ }
});
}
@@ -498,7 +992,7 @@ ENC.app = {
const category = document.getElementById("assetUploadCategory").value;
if (!file) {
- return this.toast("Choose an image first.");
+ return this.toast("Choose an asset first.");
}
try {
@@ -514,11 +1008,7 @@ ENC.app = {
},
refreshAssetUI() {
- ENC.assets.fillSelect(
- document.getElementById("backgroundSelect"),
- "backgrounds/",
- ENC.combat.encounter?.background || "",
- );
+ this.refreshEncounterMediaControls();
ENC.libraryUI.fillPortraitSelect(
document.getElementById("libraryPortraitSelect").value,
@@ -528,6 +1018,7 @@ ENC.app = {
document.getElementById("assetGrid"),
document.getElementById("assetFilter").value,
);
+ ENC.soundscapeUI?.refreshAudioSelects?.();
},
bindCustomSystem() {
@@ -575,11 +1066,20 @@ ENC.app = {
await ENC.combat.load();
+ this.playerDisplayMode = ENC.PLAYER_DISPLAY_MODES.has(ENC.combat.encounter?.playerDisplayMode)
+ ? ENC.combat.encounter.playerDisplayMode
+ : "standby";
+ this.playerDisplayPaused = this.playerDisplayMode === "standby";
+ ENC.audio.setSoundscape(ENC.combat.encounter?.soundscape);
+
ENC.combat.render();
await ENC.assets.refresh();
this.refreshAssetUI();
+ await ENC.encounterUI?.refreshSaved?.();
+ ENC.encounterUI?.renderPhase?.();
+ ENC.soundscapeUI.render();
await this.renderSnapshots();
@@ -618,8 +1118,18 @@ ENC.app = {
await ENC.combat.load();
+ this.playerDisplayMode = ENC.PLAYER_DISPLAY_MODES.has(ENC.combat.encounter?.playerDisplayMode)
+ ? ENC.combat.encounter.playerDisplayMode
+ : "standby";
+ this.playerDisplayPaused = this.playerDisplayMode === "standby";
+ ENC.audio.setSoundscape(ENC.combat.encounter?.soundscape);
+
this.bindNavigation();
+ this.initializeTimer();
+
+ this.bindTimerControls();
+
this.bindAppControls();
ENC.libraryUI.bind();
@@ -632,6 +1142,9 @@ ENC.app = {
this.bindCustomSystem();
+ await ENC.encounterUI.initialize();
+ ENC.soundscapeUI.initialize();
+
ENC.libraryUI.resetForm();
ENC.libraryUI.render();
diff --git a/programs/app/js/modules/assets.js b/programs/app/js/modules/assets.js
index 79a4587..c259323 100644
--- a/programs/app/js/modules/assets.js
+++ b/programs/app/js/modules/assets.js
@@ -37,9 +37,17 @@ ENC.assets = {
async upload(file, category) {
if (!file) throw new Error("Choose a file first.");
- const allowed = ["image/png", "image/jpeg", "image/webp"];
- if (!allowed.includes(file.type)) throw new Error("Only PNG, JPEG, and WebP images are supported.");
- if (file.size > 10 * 1024 * 1024) throw new Error("The image is larger than 10 MB.");
+ const isAudioCategory = String(category || "").startsWith("sounds/");
+ const imageTypes = ["image/png", "image/jpeg", "image/webp"];
+ const audioTypes = ["audio/mpeg", "audio/ogg", "audio/wav", "audio/x-wav", "audio/flac", "audio/x-flac"];
+ const allowed = isAudioCategory ? audioTypes : imageTypes;
+ if (!allowed.includes(file.type)) {
+ throw new Error(isAudioCategory
+ ? "Only MP3, OGG, WAV, and FLAC audio files are supported."
+ : "Only PNG, JPEG, and WebP images are supported.");
+ }
+ const maxBytes = isAudioCategory ? 50 * 1024 * 1024 : 10 * 1024 * 1024;
+ if (file.size > maxBytes) throw new Error(isAudioCategory ? "The audio file is larger than 50 MB." : "The image is larger than 10 MB.");
const params = new URLSearchParams({ category, name: file.name });
const response = await fetch(`/api/assets/upload?${params.toString()}`, {
@@ -67,11 +75,18 @@ ENC.assets = {
const card = document.createElement("article");
card.className = "asset-card";
const isImage = /\.(png|jpe?g|webp)$/i.test(item.name);
+ const isAudio = /\.(mp3|ogg|wav|flac)$/i.test(item.name);
if (isImage) {
const img = document.createElement("img");
img.src = item.url;
img.alt = "";
card.appendChild(img);
+ } else if (isAudio) {
+ const audio = document.createElement("audio");
+ audio.controls = true;
+ audio.preload = "metadata";
+ audio.src = item.url;
+ card.appendChild(audio);
}
const name = document.createElement("strong");
name.textContent = item.name;
diff --git a/programs/app/js/modules/audio.js b/programs/app/js/modules/audio.js
new file mode 100644
index 0000000..59db9c4
--- /dev/null
+++ b/programs/app/js/modules/audio.js
@@ -0,0 +1,240 @@
+/*
+ * Copyright (C) 2026 Zygons
+ * SPDX-License-Identifier: MIT
+ * This file is part of enCounter. See LICENSE for the full license terms.
+ */
+
+window.ENC = window.ENC || {};
+
+(function (ENC) {
+ "use strict";
+
+ const active = new Map();
+ const cuePlayers = new Set();
+ let mode = "stopped";
+ let resumeSceneAfterCombat = false;
+ let soundscape = ENC.createDefaultSoundscape();
+ let stateListener = null;
+
+ function emit(reason = "updated") {
+ if (typeof stateListener === "function") {
+ stateListener({ mode, soundscape: ENC.deepClone(soundscape), reason });
+ }
+ }
+
+ function effectiveVolume(track, multiplier = 1) {
+ return Math.min(
+ 1,
+ Math.max(0, Number(track?.volume || 0) * Number(soundscape.masterVolume || 0) * multiplier),
+ );
+ }
+
+ function createPlayer(key, track, targetVolume) {
+ if (!track?.asset) return null;
+ const audio = new Audio(track.asset);
+ audio.preload = "auto";
+ audio.loop = track.loop !== false;
+ audio.volume = 0;
+ active.set(key, { audio, track: ENC.deepClone(track), targetVolume });
+ return audio;
+ }
+
+ function fadeAudio(audio, from, to, durationMs, onDone = null) {
+ const duration = Math.max(0, Number(durationMs || 0));
+ const start = performance.now();
+ audio.volume = Math.min(1, Math.max(0, from));
+
+ if (!duration) {
+ audio.volume = Math.min(1, Math.max(0, to));
+ onDone?.();
+ return;
+ }
+
+ const tick = (now) => {
+ const ratio = Math.min(1, (now - start) / duration);
+ audio.volume = Math.min(1, Math.max(0, from + (to - from) * ratio));
+ if (ratio < 1) requestAnimationFrame(tick);
+ else onDone?.();
+ };
+ requestAnimationFrame(tick);
+ }
+
+ async function startTrack(key, track, volumeMultiplier = 1, fadeMs = null) {
+ if (!track?.asset) return null;
+ stopTrack(key, 0);
+ const targetVolume = effectiveVolume(track, volumeMultiplier);
+ const audio = createPlayer(key, track, targetVolume);
+ if (!audio) return null;
+
+ try {
+ await audio.play();
+ fadeAudio(audio, 0, targetVolume, fadeMs ?? soundscape.fadeMs);
+ return audio;
+ } catch (error) {
+ active.delete(key);
+ console.warn("Audio playback could not start:", track.asset, error);
+ throw new Error("Audio could not start. Click the audio control again and check the selected output device.");
+ }
+ }
+
+ function stopTrack(key, fadeMs = null) {
+ const entry = active.get(key);
+ if (!entry) return;
+ active.delete(key);
+ const { audio } = entry;
+ const finish = () => {
+ audio.pause();
+ audio.currentTime = 0;
+ };
+ fadeAudio(audio, audio.volume, 0, fadeMs ?? soundscape.fadeMs, finish);
+ }
+
+ function stopGroup(prefix, fadeMs = null) {
+ for (const key of [...active.keys()]) {
+ if (key.startsWith(prefix)) stopTrack(key, fadeMs);
+ }
+ }
+
+ function setTrackVolume(key, volume, fadeMs = null) {
+ const entry = active.get(key);
+ if (!entry) return;
+ entry.targetVolume = Math.min(1, Math.max(0, volume));
+ fadeAudio(entry.audio, entry.audio.volume, entry.targetVolume, fadeMs ?? soundscape.fadeMs);
+ }
+
+ async function playScene() {
+ stopGroup("combat:");
+ stopGroup("scene:");
+
+ const tasks = [];
+ if (soundscape.scene.music?.asset) {
+ tasks.push(startTrack("scene:music", soundscape.scene.music));
+ }
+ soundscape.scene.ambience.forEach((track, index) => {
+ if (track.asset) tasks.push(startTrack(`scene:amb:${index}`, track));
+ });
+ await Promise.allSettled(tasks);
+ mode = "scene";
+ emit("scene-started");
+ }
+
+ async function playCombat() {
+ resumeSceneAfterCombat = mode === "scene";
+ // Scene music always yields to combat music.
+ stopTrack("scene:music");
+
+ soundscape.scene.ambience.forEach((track, index) => {
+ const key = `scene:amb:${index}`;
+ if (!active.has(key)) return;
+ if (track.combatBehavior === "continue") {
+ setTrackVolume(key, effectiveVolume(track));
+ } else if (track.combatBehavior === "duck") {
+ setTrackVolume(key, Math.min(1, Math.max(0, Number(track.combatVolume || 0.15) * soundscape.masterVolume)));
+ } else {
+ stopTrack(key);
+ }
+ });
+
+ stopGroup("combat:");
+ const tasks = [];
+ if (soundscape.combat.music?.asset) {
+ tasks.push(startTrack("combat:music", soundscape.combat.music));
+ }
+ soundscape.combat.ambience.forEach((track, index) => {
+ if (track.asset) tasks.push(startTrack(`combat:amb:${index}`, track));
+ });
+ await Promise.allSettled(tasks);
+ mode = "combat";
+ emit("combat-started");
+ }
+
+ async function returnToScene() {
+ stopGroup("combat:");
+ if (resumeSceneAfterCombat) {
+ await playScene();
+ } else {
+ stopAll();
+ }
+ resumeSceneAfterCombat = false;
+ }
+
+ function stopAll(fadeMs = null) {
+ for (const key of [...active.keys()]) stopTrack(key, fadeMs);
+ for (const audio of cuePlayers) {
+ audio.pause();
+ audio.currentTime = 0;
+ }
+ cuePlayers.clear();
+ mode = "stopped";
+ resumeSceneAfterCombat = false;
+ emit("stopped");
+ }
+
+ async function playCue(cue) {
+ const normalized = ENC.normalizeAudioTrack(cue, { name: "Cue", volume: 0.8 });
+ if (!normalized.asset) return;
+ const audio = new Audio(normalized.asset);
+ audio.preload = "auto";
+ audio.loop = false;
+ audio.volume = effectiveVolume(normalized);
+ cuePlayers.add(audio);
+ const cleanup = () => cuePlayers.delete(audio);
+ audio.addEventListener("ended", cleanup, { once: true });
+ try {
+ await audio.play();
+ } catch (error) {
+ cleanup();
+ throw new Error("Sound cue could not start.");
+ }
+ }
+
+ function setSoundscape(next) {
+ const wasPlaying = mode;
+ soundscape = ENC.normalizeSoundscape(next);
+ if (wasPlaying !== "stopped") {
+ // Keep current audio stable until DM explicitly restarts/changes mode.
+ for (const entry of active.values()) {
+ entry.audio.volume = Math.min(1, entry.audio.volume);
+ }
+ }
+ emit("configuration-updated");
+ }
+
+ function setMasterVolume(value) {
+ soundscape.masterVolume = Math.min(1, Math.max(0, Number(value || 0)));
+ for (const [key, entry] of active.entries()) {
+ let multiplier = 1;
+ if (mode === "combat" && key.startsWith("scene:amb:") && entry.track.combatBehavior === "duck") {
+ const index = Number(key.split(":").pop());
+ const configured = soundscape.scene.ambience[index];
+ const volume = Number(configured?.combatVolume || 0.15) * soundscape.masterVolume;
+ setTrackVolume(key, volume, 150);
+ continue;
+ }
+ setTrackVolume(key, effectiveVolume(entry.track, multiplier), 150);
+ }
+ emit("master-volume");
+ }
+
+ ENC.audio = {
+ get mode() {
+ return mode;
+ },
+ get soundscape() {
+ return ENC.deepClone(soundscape);
+ },
+ setSoundscape,
+ setMasterVolume,
+ playScene,
+ playCombat,
+ returnToScene,
+ stopAll,
+ playCue,
+ onStateChange(listener) {
+ stateListener = typeof listener === "function" ? listener : null;
+ },
+ getState() {
+ return { mode, soundscape: ENC.deepClone(soundscape) };
+ },
+ };
+})(window.ENC);
diff --git a/programs/app/js/modules/combat.js b/programs/app/js/modules/combat.js
index ba5e6ce..2ef1b31 100644
--- a/programs/app/js/modules/combat.js
+++ b/programs/app/js/modules/combat.js
@@ -105,6 +105,22 @@ ENC.combat = {
);
},
+ followCurrentTurn() {
+ requestAnimationFrame(() => {
+ const currentCard = document.querySelector(
+ "#combatantList .combatant-card.current",
+ );
+
+ if (!currentCard) return;
+
+ currentCard.scrollIntoView({
+ behavior: "smooth",
+ block: "center",
+ inline: "nearest",
+ });
+ });
+ },
+
async moveTurn(direction) {
const all = this.encounter.combatants;
if (!all.length) return;
@@ -130,7 +146,9 @@ ENC.combat = {
await this.save(
hadCurrent ? (direction > 0 ? "next turn" : "previous turn") : "turn set",
);
+
this.render();
+ this.followCurrentTurn();
},
async changeHp(combatant, amount) {
@@ -170,11 +188,20 @@ ENC.combat = {
combatant.combatState = "active";
combatant.delayed = false;
combatant.ready = false;
- if (takeTurn) this.encounter.currentId = combatant.id;
+
+ if (takeTurn) {
+ this.encounter.currentId = combatant.id;
+ }
+
await this.save(
takeTurn ? "delayed/readied action triggered" : "combatant restored",
);
+
this.render();
+
+ if (takeTurn) {
+ this.followCurrentTurn();
+ }
},
statSummary(combatant) {
@@ -540,6 +567,7 @@ ENC.combat = {
.classList.toggle("hidden", this.encounter.combatants.length > 0);
this.renderLibrarySelect();
this.renderPresetControls();
+ ENC.encounterUI?.renderPhase?.();
},
renderLibrarySelect() {
@@ -626,11 +654,8 @@ ENC.combat = {
);
await this.save("preset loaded");
this.render();
- ENC.assets.fillSelect(
- document.getElementById("backgroundSelect"),
- "backgrounds/",
- this.encounter.background,
- );
+ ENC.app?.refreshEncounterMediaControls?.();
+ ENC.soundscapeUI?.render?.();
},
async newEncounter() {
@@ -660,19 +685,22 @@ ENC.combat = {
ENC.DEFAULT_SETTINGS.customProfile,
);
+ ENC.audio?.stopAll(250);
this.encounter = ENC.createDefaultEncounter();
this.encounter.systemId = systemId;
this.encounter.customProfile = customProfile;
+ this.encounter.phase = "prepared";
+ this.encounter.playerDisplayMode = "standby";
+ ENC.app.playerDisplayMode = "standby";
+ ENC.app.playerDisplayPaused = true;
await this.save();
ENC.app?.renderSnapshots?.();
this.render();
- ENC.assets.fillSelect(
- document.getElementById("backgroundSelect"),
- "backgrounds/",
- "",
- );
+ ENC.app?.refreshEncounterMediaControls?.();
+ ENC.soundscapeUI?.render?.();
+ ENC.app?.broadcastDisplayState?.();
ENC.app?.toast("New encounter ready.");
},
@@ -727,6 +755,16 @@ ENC.combat = {
.getElementById("backgroundSelect")
.addEventListener("change", async (event) => {
this.encounter.background = event.target.value;
+ this.encounter.display = this.encounter.display || {};
+ this.encounter.display.combatImage = event.target.value;
+ await this.save();
+ this.render();
+ });
+ document
+ .getElementById("sceneImageSelect")
+ ?.addEventListener("change", async (event) => {
+ this.encounter.display = this.encounter.display || {};
+ this.encounter.display.sceneImage = event.target.value;
await this.save();
this.render();
});
@@ -738,11 +776,9 @@ ENC.combat = {
try {
const result = await ENC.assets.upload(file, "backgrounds/custom");
this.encounter.background = result.url;
- ENC.assets.fillSelect(
- document.getElementById("backgroundSelect"),
- "backgrounds/",
- result.url,
- );
+ this.encounter.display = this.encounter.display || {};
+ this.encounter.display.combatImage = result.url;
+ ENC.app?.refreshEncounterMediaControls?.();
await this.save();
this.render();
ENC.app.toast("Background imported.");
diff --git a/programs/app/js/modules/encounters.js b/programs/app/js/modules/encounters.js
new file mode 100644
index 0000000..370fc75
--- /dev/null
+++ b/programs/app/js/modules/encounters.js
@@ -0,0 +1,311 @@
+/*
+ * Copyright (C) 2026 Zygons
+ * SPDX-License-Identifier: MIT
+ * This file is part of enCounter. See LICENSE for the full license terms.
+ */
+
+ENC.encounterUI = {
+ saved: [],
+
+ getPreparedCues() {
+ const soundscape = ENC.normalizeSoundscape(
+ ENC.combat?.encounter?.soundscape,
+ );
+ return (soundscape.cues || []).filter((cue) => cue?.asset);
+ },
+
+ renderCues() {
+ const container = document.getElementById("encounterCueButtons");
+ if (!container) return;
+
+ container.innerHTML = "";
+ const cues = this.getPreparedCues();
+
+ if (!cues.length) {
+ const empty = document.createElement("span");
+ empty.className = "hint";
+ empty.textContent = "No prepared sound cues for this encounter.";
+ container.appendChild(empty);
+ return;
+ }
+
+ cues.forEach((cue, index) => {
+ const button = document.createElement("button");
+ button.type = "button";
+ button.className = "encounter-cue-button";
+ button.textContent = cue.name || `Cue ${index + 1}`;
+ button.title = `Play ${cue.name || `Cue ${index + 1}`}`;
+
+ button.addEventListener("click", async () => {
+ const encounter = ENC.combat?.encounter;
+ if (!encounter) return;
+
+ // Use the soundscape belonging to the loaded working encounter.
+ ENC.audio?.setSoundscape(encounter.soundscape);
+ button.classList.add("is-playing");
+
+ try {
+ await ENC.audio?.playCue(cue);
+ } catch (error) {
+ ENC.app.toast(error.message || "Sound cue could not start.");
+ } finally {
+ window.setTimeout(() => button.classList.remove("is-playing"), 220);
+ }
+ });
+
+ container.appendChild(button);
+ });
+ },
+
+ async refreshSaved() {
+ this.saved = await ENC.db.getSavedEncounters();
+ const select = document.getElementById("savedEncounterSelect");
+ if (!select) return;
+ const selected = select.value;
+ select.innerHTML = '
Load saved encounter… ';
+ for (const encounter of this.saved) {
+ const option = document.createElement("option");
+ option.value = encounter.id;
+ option.textContent = `${encounter.name} — ${ENC.getSystemLabel(encounter.systemId, encounter.customProfile)}`;
+ select.appendChild(option);
+ }
+ if (this.saved.some((item) => item.id === selected))
+ select.value = selected;
+ },
+
+ renderPhase() {
+ const encounter = ENC.combat?.encounter;
+ if (!encounter) return;
+ const phase = encounter.phase || "prepared";
+ const badge = document.getElementById("encounterPhaseStatus");
+ if (badge) badge.textContent = phase.toUpperCase();
+
+ const sceneButton = document.getElementById("showSceneBtn");
+ const combatButton = document.getElementById("startCombatBtn");
+ const endButton = document.getElementById("endCombatBtn");
+ if (sceneButton)
+ sceneButton.disabled =
+ phase === "scene" && encounter.playerDisplayMode === "scene";
+ if (combatButton) combatButton.disabled = phase === "combat";
+ if (endButton) endButton.disabled = phase !== "combat";
+
+ const sourceText = document.getElementById("loadedEncounterSource");
+ if (sourceText) {
+ const source = this.saved.find(
+ (item) => item.id === encounter.sourceEncounterId,
+ );
+ sourceText.textContent = source
+ ? `Loaded from: ${source.name}`
+ : "Unsaved working encounter";
+ }
+
+ this.renderCues();
+ },
+
+ async saveCurrent(saveAs = false) {
+ const encounter = ENC.combat?.encounter;
+ if (!encounter) return;
+ let existingId = saveAs ? null : encounter.sourceEncounterId;
+ let name = encounter.name;
+ if (ENC.soundscapeUI?.collect) {
+ encounter.soundscape = ENC.soundscapeUI.collect();
+ ENC.audio?.setSoundscape(encounter.soundscape);
+ }
+ if (saveAs || !existingId) {
+ const requested = prompt(
+ "Saved encounter name:",
+ encounter.name || "Encounter",
+ );
+ if (!requested?.trim()) return;
+ name = requested.trim();
+ }
+
+ const saved = await ENC.db.saveEncounterTemplate(
+ encounter,
+ name,
+ existingId,
+ );
+ encounter.sourceEncounterId = saved.id;
+ encounter.name = saved.name;
+ await ENC.combat.save(
+ saveAs ? "encounter saved as" : "encounter template saved",
+ );
+ await this.refreshSaved();
+ this.renderPhase();
+ ENC.app.toast(
+ saveAs || !existingId
+ ? "Encounter saved to Library."
+ : "Saved encounter updated.",
+ );
+ },
+
+ async loadSelected() {
+ const select = document.getElementById("savedEncounterSelect");
+ const id = select?.value;
+ if (!id) return ENC.app.toast("Choose a saved encounter first.");
+ const item = this.saved.find((entry) => entry.id === id);
+ if (!item) return;
+ if (
+ !confirm(
+ `Load “${item.name}”? Your current working encounter will be replaced.`,
+ )
+ )
+ return;
+
+ ENC.audio?.stopAll(250);
+ const loaded = await ENC.db.loadSavedEncounter(id);
+ if (!loaded) return ENC.app.toast("Saved encounter could not be loaded.");
+ ENC.combat.encounter = loaded;
+ ENC.audio?.setSoundscape(loaded.soundscape);
+ ENC.app.playerDisplayPaused = true;
+ ENC.app.playerDisplayMode = "standby";
+ ENC.app.broadcastDisplayState?.();
+ ENC.app.updatePlayerDisplayButton?.();
+ ENC.combat.render();
+ ENC.app.refreshEncounterMediaControls?.();
+ ENC.soundscapeUI?.render?.();
+ this.renderPhase();
+ ENC.app.toast(`Loaded ${loaded.name}.`);
+ },
+
+ async duplicateSelected() {
+ const id = document.getElementById("savedEncounterSelect")?.value;
+ if (!id) return ENC.app.toast("Choose a saved encounter first.");
+ const copy = await ENC.db.duplicateSavedEncounter(id);
+ if (!copy) return;
+ await this.refreshSaved();
+ document.getElementById("savedEncounterSelect").value = copy.id;
+ ENC.app.toast(`Created ${copy.name}.`);
+ },
+
+ async deleteSelected() {
+ const id = document.getElementById("savedEncounterSelect")?.value;
+ if (!id) return ENC.app.toast("Choose a saved encounter first.");
+ const item = this.saved.find((entry) => entry.id === id);
+ if (!item) return;
+ if (
+ !confirm(
+ `Delete saved encounter “${item.name}”? This does not delete the currently loaded working copy.`,
+ )
+ )
+ return;
+ await ENC.db.delete("encounters", id);
+ if (ENC.combat.encounter?.sourceEncounterId === id) {
+ ENC.combat.encounter.sourceEncounterId = null;
+ await ENC.combat.save();
+ }
+ await this.refreshSaved();
+ this.renderPhase();
+ ENC.app.toast("Saved encounter deleted.");
+ },
+
+ async setPhase(phase, displayMode) {
+ const encounter = ENC.combat?.encounter;
+ if (!encounter) return;
+ encounter.phase = phase;
+ encounter.playerDisplayMode = displayMode;
+
+ if (phase === "combat") {
+ encounter.round = Math.max(1, Number(encounter.round || 1));
+ if (!encounter.currentId) {
+ ENC.sortCombatants(encounter.combatants);
+ encounter.currentId =
+ encounter.combatants.find(ENC.isTurnEligibleCombatant)?.id || null;
+ }
+ if (encounter.soundscape?.autoSwitchToCombat) {
+ ENC.audio?.setSoundscape(encounter.soundscape);
+ try {
+ await ENC.audio?.playCombat();
+ } catch (error) {
+ ENC.app.toast(error.message);
+ }
+ }
+ } else if (
+ phase === "scene" &&
+ encounter.soundscape?.returnToSceneAfterCombat &&
+ ENC.audio?.mode === "combat"
+ ) {
+ ENC.audio?.setSoundscape(encounter.soundscape);
+ try {
+ await ENC.audio?.returnToScene();
+ } catch (error) {
+ ENC.app.toast(error.message);
+ }
+ }
+
+ await ENC.combat.save(`phase changed: ${phase}`);
+ ENC.app.setPlayerDisplayMode?.(displayMode);
+
+ ENC.combat.render();
+
+ if (phase === "combat") {
+ ENC.combat.followCurrentTurn();
+ }
+
+ this.renderPhase();
+ },
+
+ async startSceneAudio() {
+ const encounter = ENC.combat?.encounter;
+ if (!encounter) return;
+ ENC.audio.setSoundscape(encounter.soundscape);
+ try {
+ await ENC.audio.playScene();
+ ENC.soundscapeUI?.renderStatus?.();
+ ENC.app.toast("Scene soundscape started.");
+ } catch (error) {
+ ENC.app.toast(error.message);
+ }
+ },
+
+ stopAudio() {
+ ENC.audio?.stopAll();
+ ENC.soundscapeUI?.renderStatus?.();
+ ENC.app.toast("Audio stopped.");
+ },
+
+ bind() {
+ document
+ .getElementById("saveEncounterLibraryBtn")
+ ?.addEventListener("click", () => this.saveCurrent(false));
+ document
+ .getElementById("saveEncounterAsBtn")
+ ?.addEventListener("click", () => this.saveCurrent(true));
+ document
+ .getElementById("loadSavedEncounterBtn")
+ ?.addEventListener("click", () => this.loadSelected());
+ document
+ .getElementById("duplicateSavedEncounterBtn")
+ ?.addEventListener("click", () => this.duplicateSelected());
+ document
+ .getElementById("deleteSavedEncounterBtn")
+ ?.addEventListener("click", () => this.deleteSelected());
+
+ document
+ .getElementById("showSceneBtn")
+ ?.addEventListener("click", () => this.setPhase("scene", "scene"));
+ document
+ .getElementById("startCombatBtn")
+ ?.addEventListener("click", () => this.setPhase("combat", "combat"));
+ document
+ .getElementById("endCombatBtn")
+ ?.addEventListener("click", () => this.setPhase("scene", "scene"));
+ document
+ .getElementById("hideEncounterDisplayBtn")
+ ?.addEventListener("click", () =>
+ ENC.app.setPlayerDisplayMode?.("standby"),
+ );
+ document
+ .getElementById("startSceneAudioBtn")
+ ?.addEventListener("click", () => this.startSceneAudio());
+ document
+ .getElementById("stopEncounterAudioBtn")
+ ?.addEventListener("click", () => this.stopAudio());
+ },
+
+ async initialize() {
+ await this.refreshSaved();
+ this.bind();
+ this.renderPhase();
+ },
+};
diff --git a/programs/app/js/modules/soundscape.js b/programs/app/js/modules/soundscape.js
new file mode 100644
index 0000000..3b3ca15
--- /dev/null
+++ b/programs/app/js/modules/soundscape.js
@@ -0,0 +1,182 @@
+/*
+ * Copyright (C) 2026 Zygons
+ * SPDX-License-Identifier: MIT
+ * This file is part of enCounter. See LICENSE for the full license terms.
+ */
+
+ENC.soundscapeUI = {
+ trackFromRow(prefix, defaultName, defaultVolume = 0.4, defaultBehavior = "stop") {
+ const asset = document.getElementById(`${prefix}Asset`)?.value || "";
+ const volume = Number(document.getElementById(`${prefix}Volume`)?.value ?? defaultVolume * 100) / 100;
+ const behavior = document.getElementById(`${prefix}Behavior`)?.value || defaultBehavior;
+ const combatVolume = Number(document.getElementById(`${prefix}CombatVolume`)?.value ?? 15) / 100;
+ return ENC.normalizeAudioTrack({
+ name: defaultName,
+ asset,
+ volume,
+ loop: true,
+ combatBehavior: behavior,
+ combatVolume,
+ }, { name: defaultName, volume: defaultVolume, combatBehavior: defaultBehavior });
+ },
+
+ cueFromRow(index) {
+ const asset = document.getElementById(`cue${index}Asset`)?.value || "";
+ const name = document.getElementById(`cue${index}Name`)?.value.trim() || `Cue ${index}`;
+ const volume = Number(document.getElementById(`cue${index}Volume`)?.value ?? 80) / 100;
+ return { ...ENC.normalizeAudioTrack({ name, asset, volume, loop: false }, { name, volume: 0.8 }), loop: false };
+ },
+
+ collect() {
+ const sceneAmbience = [1, 2, 3]
+ .map((index) => this.trackFromRow(`sceneAmb${index}`, `Scene Ambience ${index}`, 0.4, "duck"))
+ .filter((track) => track.asset);
+ const combatAmbience = [1, 2]
+ .map((index) => this.trackFromRow(`combatAmb${index}`, `Combat Ambience ${index}`, 0.35, "continue"))
+ .filter((track) => track.asset);
+ const cues = [1, 2, 3]
+ .map((index) => this.cueFromRow(index))
+ .filter((track) => track.asset);
+
+ return ENC.normalizeSoundscape({
+ enabled: true,
+ masterVolume: Number(document.getElementById("soundscapeMasterVolume")?.value ?? 80) / 100,
+ fadeMs: Number(document.getElementById("soundscapeFadeSeconds")?.value ?? 2.5) * 1000,
+ autoSwitchToCombat: document.getElementById("soundscapeAutoCombat")?.checked !== false,
+ returnToSceneAfterCombat: document.getElementById("soundscapeReturnScene")?.checked !== false,
+ scene: {
+ music: this.trackFromRow("sceneMusic", "Scene Music", 0.35, "stop"),
+ ambience: sceneAmbience,
+ },
+ combat: {
+ music: this.trackFromRow("combatMusic", "Combat Music", 0.65, "continue"),
+ ambience: combatAmbience,
+ },
+ cues,
+ });
+ },
+
+ setTrackRow(prefix, track = {}, behavior = "stop") {
+ const asset = document.getElementById(`${prefix}Asset`);
+ const volume = document.getElementById(`${prefix}Volume`);
+ const behaviorSelect = document.getElementById(`${prefix}Behavior`);
+ const combatVolume = document.getElementById(`${prefix}CombatVolume`);
+ if (asset) asset.value = track.asset || "";
+ if (volume) volume.value = Math.round(Number(track.volume ?? 0.4) * 100);
+ if (behaviorSelect) behaviorSelect.value = track.combatBehavior || behavior;
+ if (combatVolume) combatVolume.value = Math.round(Number(track.combatVolume ?? 0.15) * 100);
+ },
+
+ refreshAudioSelects() {
+ const audioItems = ENC.assets.byPrefix("sounds/");
+ for (const select of document.querySelectorAll("select[data-audio-select]")) {
+ const selected = select.value;
+ const prefix = select.dataset.audioPrefix || "sounds/";
+ select.innerHTML = '
— None — ';
+ for (const item of audioItems.filter((entry) => entry.category.startsWith(prefix))) {
+ const option = document.createElement("option");
+ option.value = item.url;
+ option.textContent = `${item.category.replace("sounds/", "")} / ${item.name}`;
+ select.appendChild(option);
+ }
+ if ([...select.options].some((option) => option.value === selected)) select.value = selected;
+ }
+ },
+
+ render() {
+ const soundscape = ENC.normalizeSoundscape(ENC.combat?.encounter?.soundscape);
+ this.refreshAudioSelects();
+ const master = document.getElementById("soundscapeMasterVolume");
+ const fade = document.getElementById("soundscapeFadeSeconds");
+ const auto = document.getElementById("soundscapeAutoCombat");
+ const returnScene = document.getElementById("soundscapeReturnScene");
+ if (master) master.value = Math.round(soundscape.masterVolume * 100);
+ if (fade) fade.value = soundscape.fadeMs / 1000;
+ if (auto) auto.checked = soundscape.autoSwitchToCombat;
+ if (returnScene) returnScene.checked = soundscape.returnToSceneAfterCombat;
+
+ this.setTrackRow("sceneMusic", soundscape.scene.music, "stop");
+ [1, 2, 3].forEach((index) => this.setTrackRow(`sceneAmb${index}`, soundscape.scene.ambience[index - 1] || {}, "duck"));
+ this.setTrackRow("combatMusic", soundscape.combat.music, "continue");
+ [1, 2].forEach((index) => this.setTrackRow(`combatAmb${index}`, soundscape.combat.ambience[index - 1] || {}, "continue"));
+
+ [1, 2, 3].forEach((index) => {
+ const cue = soundscape.cues[index - 1] || {};
+ const name = document.getElementById(`cue${index}Name`);
+ const asset = document.getElementById(`cue${index}Asset`);
+ const volume = document.getElementById(`cue${index}Volume`);
+ if (name) name.value = cue.name || `Cue ${index}`;
+ if (asset) asset.value = cue.asset || "";
+ if (volume) volume.value = Math.round(Number(cue.volume ?? 0.8) * 100);
+ });
+ this.renderStatus();
+ ENC.encounterUI?.renderCues?.();
+ },
+
+ renderStatus() {
+ const status = document.getElementById("soundscapeStatus");
+ const live = document.getElementById("encounterAudioStatus");
+ const label = ENC.audio?.mode === "scene" ? "SCENE AUDIO PLAYING" : ENC.audio?.mode === "combat" ? "COMBAT AUDIO PLAYING" : "AUDIO STOPPED";
+ if (status) status.textContent = label;
+ if (live) live.textContent = label;
+ },
+
+ async save() {
+ if (!ENC.combat?.encounter) return;
+ ENC.combat.encounter.soundscape = this.collect();
+ ENC.audio.setSoundscape(ENC.combat.encounter.soundscape);
+ await ENC.combat.save("soundscape updated");
+ this.renderStatus();
+ ENC.encounterUI?.renderCues?.();
+ ENC.app.toast("Soundscape applied to the working encounter. Use Encounter → Save to update the Saved Encounter template.");
+ },
+
+ async previewScene() {
+ ENC.combat.encounter.soundscape = this.collect();
+ ENC.audio.setSoundscape(ENC.combat.encounter.soundscape);
+ try { await ENC.audio.playScene(); this.renderStatus(); } catch (error) { ENC.app.toast(error.message); }
+ },
+
+ async previewCombat() {
+ ENC.combat.encounter.soundscape = this.collect();
+ ENC.audio.setSoundscape(ENC.combat.encounter.soundscape);
+ try { await ENC.audio.playCombat(); this.renderStatus(); } catch (error) { ENC.app.toast(error.message); }
+ },
+
+ async playCue(index) {
+ const cue = this.cueFromRow(index);
+ if (!cue.asset) return ENC.app.toast("Choose a sound for this cue first.");
+ try { await ENC.audio.playCue(cue); } catch (error) { ENC.app.toast(error.message); }
+ },
+
+ bind() {
+ document.getElementById("saveSoundscapeBtn")?.addEventListener("click", () => this.save());
+ document.getElementById("previewSceneAudioBtn")?.addEventListener("click", () => this.previewScene());
+ document.getElementById("previewCombatAudioBtn")?.addEventListener("click", () => this.previewCombat());
+ document.getElementById("stopSoundscapeBtn")?.addEventListener("click", () => { ENC.audio.stopAll(); this.renderStatus(); });
+ [1, 2, 3].forEach((index) => document.getElementById(`playCue${index}Btn`)?.addEventListener("click", () => this.playCue(index)));
+
+ document.getElementById("soundscapeMasterVolume")?.addEventListener("input", (event) => ENC.audio.setMasterVolume(Number(event.target.value) / 100));
+
+ document.getElementById("uploadAudioBtn")?.addEventListener("click", async () => {
+ const file = document.getElementById("audioUploadFile")?.files[0];
+ const category = document.getElementById("audioUploadCategory")?.value || "sounds/custom";
+ if (!file) return ENC.app.toast("Choose an audio file first.");
+ try {
+ await ENC.assets.upload(file, category);
+ this.refreshAudioSelects();
+ ENC.app.toast("Audio imported.");
+ } catch (error) {
+ ENC.app.toast(error.message);
+ }
+ });
+
+ ENC.audio.onStateChange(() => this.renderStatus());
+ },
+
+ initialize() {
+ ENC.audio.setSoundscape(ENC.combat?.encounter?.soundscape);
+ this.bind();
+ this.render();
+ },
+};
diff --git a/programs/app/js/modules/timer-renderer.js b/programs/app/js/modules/timer-renderer.js
new file mode 100644
index 0000000..1ae96ed
--- /dev/null
+++ b/programs/app/js/modules/timer-renderer.js
@@ -0,0 +1,819 @@
+/*
+ * Copyright (C) 2026 Zygons
+ * SPDX-License-Identifier: MIT
+ * This file is part of enCounter. See LICENSE for the full license terms.
+ */
+
+/*
+ * ============================================================
+ * enCounter Timer Renderer
+ * ============================================================
+ *
+ * Responsibilities:
+ *
+ * - Render timer skins.
+ * - Update visual progress.
+ * - Update optional numeric countdown.
+ * - Apply running / paused / warning / critical / complete states.
+ * - Render:
+ * Fantasy Hourglass
+ * Candle
+ * Sci-Fi Pixel Depletion
+ *
+ * This module DOES NOT keep track of time.
+ *
+ * timer.js is responsible for:
+ *
+ * - starting timers
+ * - pausing timers
+ * - resuming timers
+ * - resetting timers
+ * - calculating remaining milliseconds
+ * - calculating remainingRatio
+ *
+ * remainingRatio:
+ *
+ * 1.00 = all time remaining
+ * 0.50 = halfway
+ * 0.00 = complete
+ *
+ * ============================================================
+ */
+
+window.ENC = window.ENC || {};
+
+(function (ENC) {
+ "use strict";
+
+ const TIMER_RENDERER_VERSION = "1.0";
+
+ const DEFAULT_SKIN = "hourglass";
+
+ const SUPPORTED_SKINS = new Set(["hourglass", "candle", "scifi-pixels"]);
+
+ const SCI_FI_PIXEL_COUNT = 64;
+
+ /*
+ * Warning thresholds.
+ *
+ * 25% remaining -> warning
+ * 10% remaining -> critical
+ */
+ const WARNING_RATIO = 0.25;
+ const CRITICAL_RATIO = 0.1;
+
+ /*
+ * Keep track of renderer instances.
+ *
+ * This allows the DM Console and Player Display to each have
+ * their own renderer while using the same rendering engine.
+ */
+ const renderers = new Set();
+
+ /* ============================================================
+ UTILITY FUNCTIONS
+ ============================================================ */
+
+ function clamp(value, min, max) {
+ const number = Number(value);
+
+ if (!Number.isFinite(number)) {
+ return min;
+ }
+
+ return Math.min(max, Math.max(min, number));
+ }
+
+ function normalizeRatio(value) {
+ return clamp(value, 0, 1);
+ }
+
+ function normalizeSkin(skin) {
+ if (SUPPORTED_SKINS.has(skin)) {
+ return skin;
+ }
+
+ return DEFAULT_SKIN;
+ }
+
+ function normalizeStatus(status) {
+ switch (status) {
+ case "running":
+ case "paused":
+ case "complete":
+ case "idle":
+ return status;
+
+ default:
+ return "idle";
+ }
+ }
+
+ function formatTime(milliseconds) {
+ let value = Number(milliseconds);
+
+ if (!Number.isFinite(value) || value < 0) {
+ value = 0;
+ }
+
+ /*
+ * Use Math.ceil so a timer with 0.4 seconds remaining
+ * still displays 00:01 rather than prematurely showing
+ * 00:00.
+ */
+ const totalSeconds = Math.ceil(value / 1000);
+
+ const hours = Math.floor(totalSeconds / 3600);
+
+ const minutes = Math.floor((totalSeconds % 3600) / 60);
+
+ const seconds = totalSeconds % 60;
+
+ const paddedSeconds = String(seconds).padStart(2, "0");
+
+ if (hours > 0) {
+ return (
+ String(hours).padStart(2, "0") +
+ ":" +
+ String(minutes).padStart(2, "0") +
+ ":" +
+ paddedSeconds
+ );
+ }
+
+ return String(minutes).padStart(2, "0") + ":" + paddedSeconds;
+ }
+
+ function createElement(tag, className, text) {
+ const element = document.createElement(tag);
+
+ if (className) {
+ element.className = className;
+ }
+
+ if (text !== undefined && text !== null) {
+ element.textContent = text;
+ }
+
+ return element;
+ }
+
+ /*
+ * Deterministic shuffle for Sci-Fi pixels.
+ *
+ * We want pixels to disappear in a visually irregular order,
+ * but they must always disappear in the SAME order so the
+ * visual is directly tied to remaining time.
+ *
+ * This is intentionally deterministic rather than random.
+ */
+ function createPixelDecayOrder(count) {
+ const values = [];
+
+ for (let i = 0; i < count; i += 1) {
+ values.push(i);
+ }
+
+ let seed = 0x5eed1234;
+
+ function nextRandom() {
+ seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+
+ return seed / 4294967296;
+ }
+
+ for (let i = values.length - 1; i > 0; i -= 1) {
+ const j = Math.floor(nextRandom() * (i + 1));
+
+ const temp = values[i];
+
+ values[i] = values[j];
+ values[j] = temp;
+ }
+
+ return values;
+ }
+
+ const SCI_FI_DECAY_ORDER = createPixelDecayOrder(SCI_FI_PIXEL_COUNT);
+
+ /* ============================================================
+ BASE TIMER STRUCTURE
+ ============================================================ */
+
+ function createBaseStructure(container) {
+ container.innerHTML = "";
+
+ const root = createElement("div", "timer-display timer-visible");
+
+ root.setAttribute("aria-label", "enCounter timer");
+
+ /*
+ * Timer label
+ */
+ const label = createElement("div", "timer-label");
+
+ /*
+ * Skin container
+ *
+ * The selected timer skin will be inserted here.
+ */
+ const skinHost = createElement("div", "timer-skin-host");
+
+ /*
+ * Optional numerical countdown.
+ */
+ const numeric = createElement(
+ "div",
+ "timer-numeric timer-numeric-hidden",
+ "00:00",
+ );
+
+ numeric.setAttribute("aria-live", "off");
+
+ root.appendChild(label);
+ root.appendChild(skinHost);
+ root.appendChild(numeric);
+
+ container.appendChild(root);
+
+ return {
+ root,
+ label,
+ skinHost,
+ numeric,
+ };
+ }
+
+ /* ============================================================
+ HOURGLASS SKIN
+ ============================================================ */
+
+ function createHourglassSkin() {
+ const hourglass = createElement("div", "timer-hourglass");
+
+ /*
+ * Outer wooden / fantasy frame.
+ */
+ const frame = createElement("div", "timer-hourglass-frame");
+
+ /*
+ * Glass chamber.
+ */
+ const glass = createElement("div", "timer-hourglass-glass");
+
+ /*
+ * Upper sand.
+ */
+ const topSand = createElement("div", "timer-hourglass-sand-top");
+
+ /*
+ * Lower collected sand.
+ */
+ const bottomSand = createElement("div", "timer-hourglass-sand-bottom");
+
+ /*
+ * Falling sand stream.
+ */
+ const stream = createElement("div", "timer-hourglass-stream");
+
+ /*
+ * Decorative sand particles.
+ */
+ const particles = createElement("div", "timer-hourglass-particles");
+
+ for (let i = 0; i < 3; i += 1) {
+ particles.appendChild(createElement("span", "timer-hourglass-particle"));
+ }
+
+ glass.appendChild(topSand);
+ glass.appendChild(bottomSand);
+ glass.appendChild(stream);
+ glass.appendChild(particles);
+
+ hourglass.appendChild(frame);
+ hourglass.appendChild(glass);
+
+ return {
+ element: hourglass,
+
+ refs: {
+ glass,
+ topSand,
+ bottomSand,
+ stream,
+ particles,
+ },
+ };
+ }
+
+ function updateHourglassSkin(skin, timer, remainingRatio) {
+ const status = normalizeStatus(timer.status);
+
+ skin.element.classList.toggle("timer-idle", status === "idle");
+
+ skin.element.classList.toggle("timer-paused", status === "paused");
+
+ skin.element.classList.toggle(
+ "timer-complete",
+ status === "complete" || remainingRatio <= 0,
+ );
+ }
+
+ /* ============================================================
+ CANDLE SKIN
+ ============================================================ */
+
+ function createCandleSkin() {
+ const candle = createElement("div", "timer-candle");
+
+ const base = createElement("div", "timer-candle-base");
+
+ /*
+ * Candle body.
+ *
+ * Flame, wick and glow are children of the body so they
+ * move downward naturally as the candle height decreases.
+ */
+ const body = createElement("div", "timer-candle-body");
+
+ const wick = createElement("div", "timer-candle-wick");
+
+ const glow = createElement("div", "timer-candle-glow");
+
+ const flameWrap = createElement("div", "timer-candle-flame-wrap");
+
+ const flame = createElement("div", "timer-candle-flame");
+
+ const smoke = createElement("div", "timer-candle-smoke");
+
+ flameWrap.appendChild(flame);
+
+ body.appendChild(glow);
+ body.appendChild(flameWrap);
+ body.appendChild(wick);
+ body.appendChild(smoke);
+
+ candle.appendChild(base);
+ candle.appendChild(body);
+
+ return {
+ element: candle,
+
+ refs: {
+ base,
+ body,
+ wick,
+ glow,
+ flameWrap,
+ flame,
+ smoke,
+ },
+ };
+ }
+
+ function updateCandleSkin(skin, timer, remainingRatio) {
+ /*
+ * CSS handles the actual height using:
+ *
+ * --timer-remaining
+ *
+ * This method is currently responsible only for
+ * skin-specific state if needed later.
+ */
+
+ const complete = timer.status === "complete" || remainingRatio <= 0;
+
+ skin.element.classList.toggle("timer-complete", complete);
+ }
+
+ /* ============================================================
+ SCI-FI PIXEL SKIN
+ ============================================================ */
+
+ function createSciFiSkin() {
+ const scifi = createElement("div", "timer-scifi");
+
+ /*
+ * Decorative animated scanning line.
+ */
+ const scan = createElement("div", "timer-scifi-scan");
+
+ const heading = createElement(
+ "div",
+ "timer-scifi-heading",
+ "TEMPORAL SEQUENCE",
+ );
+
+ const grid = createElement("div", "timer-scifi-grid");
+
+ grid.setAttribute("aria-hidden", "true");
+
+ const pixels = [];
+
+ for (let i = 0; i < SCI_FI_PIXEL_COUNT; i += 1) {
+ const pixel = createElement("span", "timer-scifi-pixel");
+
+ pixel.dataset.pixelIndex = String(i);
+
+ grid.appendChild(pixel);
+
+ pixels.push(pixel);
+ }
+
+ const footer = createElement("div", "timer-scifi-footer");
+
+ const footerLeft = createElement("span", "", "SEQ ACTIVE");
+
+ const footerRight = createElement("span", "", "ENC-TMR");
+
+ footer.appendChild(footerLeft);
+ footer.appendChild(footerRight);
+
+ scifi.appendChild(scan);
+ scifi.appendChild(heading);
+ scifi.appendChild(grid);
+ scifi.appendChild(footer);
+
+ return {
+ element: scifi,
+
+ refs: {
+ scan,
+ heading,
+ grid,
+ pixels,
+ footer,
+ footerLeft,
+ footerRight,
+ },
+
+ /*
+ * Store previous number of active pixels.
+ *
+ * This allows us to briefly animate a pixel when it
+ * changes from active to depleted.
+ */
+ previousActiveCount: SCI_FI_PIXEL_COUNT,
+ };
+ }
+
+ function updateSciFiSkin(skin, timer, remainingRatio) {
+ const pixels = skin.refs.pixels;
+
+ /*
+ * Convert the exact timer percentage into the number of
+ * illuminated pixels.
+ *
+ * Example with 64 pixels:
+ *
+ * 1.00 -> 64
+ * 0.75 -> 48
+ * 0.50 -> 32
+ * 0.25 -> 16
+ * 0.00 -> 0
+ */
+ const activeCount = Math.ceil(SCI_FI_PIXEL_COUNT * remainingRatio);
+
+ const activeIndexes = new Set(SCI_FI_DECAY_ORDER.slice(0, activeCount));
+
+ for (let i = 0; i < pixels.length; i += 1) {
+ const pixel = pixels[i];
+
+ const shouldBeActive = activeIndexes.has(i);
+
+ const wasActive = !pixel.classList.contains("off");
+
+ if (shouldBeActive) {
+ pixel.classList.remove("off", "decaying");
+ } else {
+ /*
+ * If this pixel just transitioned from ON to OFF,
+ * briefly apply the decay animation.
+ */
+ if (wasActive) {
+ pixel.classList.remove("decaying");
+
+ /*
+ * Force a reflow so repeatedly applying the
+ * animation works reliably.
+ */
+ void pixel.offsetWidth;
+
+ pixel.classList.add("decaying");
+
+ window.setTimeout(() => {
+ pixel.classList.remove("decaying");
+ }, 300);
+ }
+
+ pixel.classList.add("off");
+ }
+ }
+
+ skin.previousActiveCount = activeCount;
+
+ /*
+ * Footer status.
+ */
+ if (timer.status === "complete" || remainingRatio <= 0) {
+ skin.refs.footerLeft.textContent = "SEQUENCE ENDED";
+ } else if (timer.status === "paused") {
+ skin.refs.footerLeft.textContent = "SEQUENCE HOLD";
+ } else if (timer.status === "running") {
+ skin.refs.footerLeft.textContent = "SEQ ACTIVE";
+ } else {
+ skin.refs.footerLeft.textContent = "SEQ READY";
+ }
+ }
+
+ /* ============================================================
+ SKIN FACTORY
+ ============================================================ */
+
+ function createSkin(skinName) {
+ const normalizedSkin = normalizeSkin(skinName);
+
+ switch (normalizedSkin) {
+ case "candle":
+ return {
+ name: "candle",
+ ...createCandleSkin(),
+ };
+
+ case "scifi-pixels":
+ return {
+ name: "scifi-pixels",
+ ...createSciFiSkin(),
+ };
+
+ case "hourglass":
+ default:
+ return {
+ name: "hourglass",
+ ...createHourglassSkin(),
+ };
+ }
+ }
+
+ /* ============================================================
+ WARNING / CRITICAL STATE
+ ============================================================ */
+
+ function updateWarningState(root, timer, remainingRatio) {
+ root.classList.remove("timer-warning", "timer-critical");
+
+ if (timer.status === "complete" || remainingRatio <= 0) {
+ return;
+ }
+
+ if (timer.status !== "running" && timer.status !== "paused") {
+ return;
+ }
+
+ if (remainingRatio <= CRITICAL_RATIO) {
+ root.classList.add("timer-critical");
+
+ return;
+ }
+
+ if (remainingRatio <= WARNING_RATIO) {
+ root.classList.add("timer-warning");
+ }
+ }
+
+ /* ============================================================
+ TIMER ROOT STATE
+ ============================================================ */
+
+ function updateRootState(root, timer, remainingRatio) {
+ const status = normalizeStatus(timer.status);
+
+ root.classList.toggle("timer-paused", status === "paused");
+
+ root.classList.toggle(
+ "timer-complete",
+ status === "complete" || remainingRatio <= 0,
+ );
+
+ root.classList.toggle("timer-hidden", timer.visible === false);
+
+ root.classList.toggle("timer-visible", timer.visible !== false);
+
+ /*
+ * Update the CSS custom properties that drive the
+ * time-accurate visual animations.
+ */
+ root.style.setProperty("--timer-remaining", String(remainingRatio));
+
+ root.style.setProperty("--timer-elapsed", String(1 - remainingRatio));
+
+ updateWarningState(root, timer, remainingRatio);
+ }
+
+ /* ============================================================
+ CREATE RENDERER INSTANCE
+ ============================================================ */
+
+ function createRenderer(container) {
+ /*
+ * Allow either:
+ *
+ * ENC.timerRenderer.create("#timerPreview")
+ *
+ * or:
+ *
+ * ENC.timerRenderer.create(element)
+ */
+ let resolvedContainer = container;
+
+ if (typeof container === "string") {
+ resolvedContainer = document.querySelector(container);
+ }
+
+ if (!(resolvedContainer instanceof Element)) {
+ throw new Error("Timer renderer requires a valid container element.");
+ }
+
+ const structure = createBaseStructure(resolvedContainer);
+
+ let currentSkin = null;
+
+ let destroyed = false;
+
+ function installSkin(skinName) {
+ const normalizedSkin = normalizeSkin(skinName);
+
+ if (currentSkin && currentSkin.name === normalizedSkin) {
+ return currentSkin;
+ }
+
+ structure.skinHost.innerHTML = "";
+
+ currentSkin = createSkin(normalizedSkin);
+
+ structure.skinHost.appendChild(currentSkin.element);
+
+ return currentSkin;
+ }
+
+ function updateSkin(timer, remainingRatio) {
+ if (!currentSkin) {
+ return;
+ }
+
+ switch (currentSkin.name) {
+ case "hourglass":
+ updateHourglassSkin(currentSkin, timer, remainingRatio);
+ break;
+
+ case "candle":
+ updateCandleSkin(currentSkin, timer, remainingRatio);
+ break;
+
+ case "scifi-pixels":
+ updateSciFiSkin(currentSkin, timer, remainingRatio);
+ break;
+
+ default:
+ break;
+ }
+ }
+
+ function render(timer = {}, remainingRatio = 1) {
+ if (destroyed) {
+ return;
+ }
+
+ const ratio = normalizeRatio(remainingRatio);
+
+ const skinName = normalizeSkin(timer.skin);
+
+ installSkin(skinName);
+
+ /*
+ * Label
+ */
+ structure.label.textContent = timer.name || timer.label || "";
+
+ structure.label.hidden = structure.label.textContent.trim() === "";
+
+ /*
+ * Numeric timer
+ */
+ const showNumeric =
+ timer.showNumeric === true || timer.showNumericToPlayers === true;
+
+ structure.numeric.classList.toggle("timer-numeric-hidden", !showNumeric);
+
+ if (showNumeric) {
+ const remainingMs = Number.isFinite(Number(timer.remainingMs))
+ ? Number(timer.remainingMs)
+ : Number(timer.durationMs || 0) * ratio;
+
+ structure.numeric.textContent = formatTime(remainingMs);
+ }
+
+ /*
+ * Root timer state.
+ */
+ updateRootState(structure.root, timer, ratio);
+
+ /*
+ * Skin-specific changes.
+ */
+ updateSkin(timer, ratio);
+ }
+
+ function clear() {
+ if (destroyed) {
+ return;
+ }
+
+ structure.label.textContent = "";
+
+ structure.numeric.textContent = "00:00";
+
+ structure.root.classList.remove(
+ "timer-warning",
+ "timer-critical",
+ "timer-paused",
+ "timer-complete",
+ );
+
+ structure.root.style.setProperty("--timer-remaining", "1");
+
+ structure.root.style.setProperty("--timer-elapsed", "0");
+
+ if (currentSkin) {
+ structure.skinHost.innerHTML = "";
+ currentSkin = null;
+ }
+ }
+
+ function setVisible(visible) {
+ if (destroyed) {
+ return;
+ }
+
+ structure.root.classList.toggle("timer-hidden", visible === false);
+
+ structure.root.classList.toggle("timer-visible", visible !== false);
+ }
+
+ function destroy() {
+ if (destroyed) {
+ return;
+ }
+
+ destroyed = true;
+
+ renderers.delete(api);
+
+ resolvedContainer.innerHTML = "";
+
+ currentSkin = null;
+ }
+
+ const api = {
+ render,
+ clear,
+ setVisible,
+ destroy,
+
+ get element() {
+ return structure.root;
+ },
+
+ get skin() {
+ return currentSkin ? currentSkin.name : null;
+ },
+ };
+
+ renderers.add(api);
+
+ return api;
+ }
+
+ /* ============================================================
+ PUBLIC API
+ ============================================================ */
+
+ ENC.timerRenderer = {
+ VERSION: TIMER_RENDERER_VERSION,
+
+ skins: Object.freeze(["hourglass", "candle", "scifi-pixels"]),
+
+ create: createRenderer,
+
+ formatTime,
+
+ normalizeRatio,
+
+ /*
+ * Primarily useful for debugging.
+ */
+ getRendererCount() {
+ return renderers.size;
+ },
+ };
+})(window.ENC);
diff --git a/programs/app/js/modules/timer.js b/programs/app/js/modules/timer.js
new file mode 100644
index 0000000..67cf931
--- /dev/null
+++ b/programs/app/js/modules/timer.js
@@ -0,0 +1,1161 @@
+/*
+ * Copyright (C) 2026 Zygons
+ * SPDX-License-Identifier: MIT
+ * This file is part of enCounter. See LICENSE for the full license terms.
+ */
+
+/*
+ * ============================================================
+ * enCounter Visual Timer Engine
+ * ============================================================
+ *
+ * Responsibilities:
+ *
+ * - Maintain timer state.
+ * - Start countdowns.
+ * - Pause countdowns.
+ * - Resume countdowns.
+ * - Reset countdowns.
+ * - Stop countdowns.
+ * - Add or subtract time.
+ * - Calculate accurate remaining time.
+ * - Drive timer-renderer.js.
+ * - Export/import timer state for Player Display synchronization.
+ *
+ * IMPORTANT:
+ *
+ * This module does NOT count downward by subtracting a fixed
+ * amount every second.
+ *
+ * Instead, a running timer stores an absolute ending timestamp:
+ *
+ * endAt = Date.now() + remainingMs
+ *
+ * Every rendered frame calculates:
+ *
+ * remainingMs = endAt - Date.now()
+ *
+ * This prevents timer drift and allows the Player Display to
+ * independently render the same timer accurately.
+ *
+ * ============================================================
+ */
+
+window.ENC = window.ENC || {};
+
+(function (ENC) {
+ "use strict";
+
+ const TIMER_VERSION = "1.0";
+
+ const DEFAULT_DURATION_MS = 5 * 60 * 1000;
+
+ const DEFAULT_STATE = Object.freeze({
+ id: "primary-timer",
+
+ name: "Countdown",
+
+ /*
+ * Only countdown is active in the first implementation.
+ *
+ * Future values may include:
+ *
+ * countup
+ * rounds
+ */
+ mode: "countdown",
+
+ /*
+ * Timer skin names must match timer-renderer.js.
+ */
+ skin: "hourglass",
+
+ /*
+ * Full configured duration.
+ */
+ durationMs: DEFAULT_DURATION_MS,
+
+ /*
+ * Amount of time currently remaining.
+ *
+ * While running this value is refreshed from endAt.
+ */
+ remainingMs: DEFAULT_DURATION_MS,
+
+ /*
+ * Absolute JavaScript timestamp for timer completion.
+ *
+ * null when idle, paused, stopped or complete.
+ */
+ endAt: null,
+
+ /*
+ * idle
+ * running
+ * paused
+ * complete
+ */
+ status: "idle",
+
+ /*
+ * Whether the timer is visible on the Player Display.
+ */
+ visibleToPlayers: false,
+
+ /*
+ * DM may always choose to see exact time in the preview.
+ */
+ showNumericToDM: true,
+
+ /*
+ * Whether players see exact numerical time.
+ */
+ showNumericToPlayers: false,
+
+ /*
+ * Initial display mode.
+ *
+ * overlay
+ * featured
+ * focus
+ */
+ displayMode: "overlay",
+ });
+
+ const VALID_SKINS = new Set(["hourglass", "candle", "scifi-pixels"]);
+
+ const VALID_STATUSES = new Set(["idle", "running", "paused", "complete"]);
+
+ const VALID_DISPLAY_MODES = new Set(["overlay", "featured", "focus"]);
+
+ /*
+ * Registry primarily useful for debugging and future cleanup.
+ */
+ const controllers = new Set();
+
+ /* ============================================================
+ GENERAL UTILITIES
+ ============================================================ */
+
+ function clamp(value, min, max) {
+ const number = Number(value);
+
+ if (!Number.isFinite(number)) {
+ return min;
+ }
+
+ return Math.min(max, Math.max(min, number));
+ }
+
+ function normalizeMilliseconds(value) {
+ const number = Number(value);
+
+ if (!Number.isFinite(number)) {
+ return 0;
+ }
+
+ return Math.max(0, Math.round(number));
+ }
+
+ function normalizeSkin(value) {
+ if (VALID_SKINS.has(value)) {
+ return value;
+ }
+
+ return DEFAULT_STATE.skin;
+ }
+
+ function normalizeStatus(value) {
+ if (VALID_STATUSES.has(value)) {
+ return value;
+ }
+
+ return "idle";
+ }
+
+ function normalizeDisplayMode(value) {
+ if (VALID_DISPLAY_MODES.has(value)) {
+ return value;
+ }
+
+ return DEFAULT_STATE.displayMode;
+ }
+
+ function createTimerId() {
+ if (window.crypto && typeof window.crypto.randomUUID === "function") {
+ return window.crypto.randomUUID();
+ }
+
+ return (
+ "timer-" + Date.now() + "-" + Math.random().toString(36).slice(2, 10)
+ );
+ }
+
+ function cloneState(state) {
+ return {
+ id: state.id,
+ name: state.name,
+ mode: state.mode,
+ skin: state.skin,
+
+ durationMs: state.durationMs,
+ remainingMs: state.remainingMs,
+
+ endAt: state.endAt,
+
+ status: state.status,
+
+ visibleToPlayers: state.visibleToPlayers,
+
+ showNumericToDM: state.showNumericToDM,
+
+ showNumericToPlayers: state.showNumericToPlayers,
+
+ displayMode: state.displayMode,
+ };
+ }
+
+ function sanitizeState(input = {}) {
+ let durationMs = normalizeMilliseconds(input.durationMs);
+
+ if (durationMs <= 0) {
+ durationMs = DEFAULT_STATE.durationMs;
+ }
+
+ let remainingMs;
+
+ if (input.remainingMs === undefined || input.remainingMs === null) {
+ remainingMs = durationMs;
+ } else {
+ remainingMs = normalizeMilliseconds(input.remainingMs);
+ }
+
+ /*
+ * A timer can have more remaining time than its original
+ * duration if the DM added time.
+ *
+ * If that occurs, expand duration to match.
+ */
+ if (remainingMs > durationMs) {
+ durationMs = remainingMs;
+ }
+
+ const status = normalizeStatus(input.status);
+
+ let endAt = null;
+
+ if (status === "running" && Number.isFinite(Number(input.endAt))) {
+ endAt = Number(input.endAt);
+ }
+
+ return {
+ id:
+ typeof input.id === "string" && input.id.trim()
+ ? input.id.trim()
+ : createTimerId(),
+
+ name:
+ typeof input.name === "string" ? input.name.trim() : DEFAULT_STATE.name,
+
+ mode: "countdown",
+
+ skin: normalizeSkin(input.skin),
+
+ durationMs,
+ remainingMs,
+
+ endAt,
+
+ status,
+
+ visibleToPlayers: input.visibleToPlayers === true,
+
+ showNumericToDM: input.showNumericToDM !== false,
+
+ showNumericToPlayers: input.showNumericToPlayers === true,
+
+ displayMode: normalizeDisplayMode(input.displayMode),
+ };
+ }
+
+ /* ============================================================
+ TIMER CONTROLLER
+ ============================================================ */
+
+ function createTimer(options = {}) {
+ /*
+ * Optional renderer created by timer-renderer.js.
+ *
+ * Example:
+ *
+ * const renderer =
+ * ENC.timerRenderer.create("#timerPreview");
+ *
+ * const timer =
+ * ENC.timer.create({
+ * renderer: renderer
+ * });
+ */
+ let renderer = options.renderer || null;
+
+ /*
+ * audience determines what the renderer should see.
+ *
+ * dm
+ * player
+ *
+ * DM preview is always visible.
+ *
+ * Player rendering respects visibleToPlayers.
+ */
+ const audience = options.audience === "player" ? "player" : "dm";
+
+ /*
+ * Optional integration hooks.
+ *
+ * We are deliberately NOT hard-wiring BroadcastChannel
+ * here yet.
+ *
+ * main.js / display.js can connect these hooks to the
+ * existing enCounter synchronization system.
+ */
+ const onStateChange =
+ typeof options.onStateChange === "function"
+ ? options.onStateChange
+ : null;
+
+ const onComplete =
+ typeof options.onComplete === "function" ? options.onComplete : null;
+
+ let state = sanitizeState({
+ ...DEFAULT_STATE,
+ ...(options.initialState || {}),
+ });
+
+ let animationFrameId = null;
+
+ let destroyed = false;
+
+ let completionNotified = false;
+
+ /* ========================================================
+ CURRENT TIME CALCULATION
+ ======================================================== */
+
+ function calculateRemainingMs() {
+ if (state.status !== "running") {
+ return state.remainingMs;
+ }
+
+ if (!Number.isFinite(state.endAt)) {
+ return state.remainingMs;
+ }
+
+ return Math.max(0, state.endAt - Date.now());
+ }
+
+ function syncRemainingFromClock() {
+ if (state.status !== "running") {
+ return state.remainingMs;
+ }
+
+ state.remainingMs = calculateRemainingMs();
+
+ return state.remainingMs;
+ }
+
+ function calculateRemainingRatio() {
+ const duration = Math.max(1, state.durationMs);
+
+ const remaining =
+ state.status === "running" ? calculateRemainingMs() : state.remainingMs;
+
+ return clamp(remaining / duration, 0, 1);
+ }
+
+ /* ========================================================
+ RENDER STATE
+ ======================================================== */
+
+ function createRenderState() {
+ syncRemainingFromClock();
+
+ /*
+ * The renderer uses the generic "visible" and
+ * "showNumeric" properties.
+ *
+ * Resolve those based on whether this controller is
+ * rendering the DM Console or Player Display.
+ */
+ return {
+ ...cloneState(state),
+
+ visible: audience === "player" ? state.visibleToPlayers : true,
+
+ showNumeric:
+ audience === "player"
+ ? state.showNumericToPlayers
+ : state.showNumericToDM,
+ };
+ }
+
+ function render() {
+ if (destroyed) {
+ return;
+ }
+
+ if (!renderer || typeof renderer.render !== "function") {
+ return;
+ }
+
+ const ratio = calculateRemainingRatio();
+
+ renderer.render(createRenderState(), ratio);
+ }
+
+ /* ========================================================
+ NOTIFICATIONS / SYNC HOOK
+ ======================================================== */
+
+ function notifyStateChange(reason) {
+ if (destroyed) {
+ return;
+ }
+
+ /*
+ * Make sure a running timer exports the most recent
+ * remaining time.
+ */
+ syncRemainingFromClock();
+
+ if (onStateChange) {
+ onStateChange(cloneState(state), reason);
+ }
+ }
+
+ /* ========================================================
+ ANIMATION LOOP
+ ======================================================== */
+
+ function cancelAnimationLoop() {
+ if (animationFrameId !== null) {
+ window.cancelAnimationFrame(animationFrameId);
+
+ animationFrameId = null;
+ }
+ }
+
+ function finishTimer() {
+ cancelAnimationLoop();
+
+ state.remainingMs = 0;
+ state.endAt = null;
+ state.status = "complete";
+
+ render();
+
+ notifyStateChange("complete");
+
+ if (!completionNotified && onComplete) {
+ completionNotified = true;
+
+ onComplete(cloneState(state));
+ }
+ }
+
+ function animationLoop() {
+ if (destroyed) {
+ return;
+ }
+
+ if (state.status !== "running") {
+ animationFrameId = null;
+ return;
+ }
+
+ const remaining = syncRemainingFromClock();
+
+ if (remaining <= 0) {
+ finishTimer();
+ return;
+ }
+
+ render();
+
+ animationFrameId = window.requestAnimationFrame(animationLoop);
+ }
+
+ function startAnimationLoop() {
+ cancelAnimationLoop();
+
+ if (state.status !== "running") {
+ return;
+ }
+
+ animationFrameId = window.requestAnimationFrame(animationLoop);
+ }
+
+ /* ========================================================
+ START
+ ======================================================== */
+
+ function start() {
+ if (destroyed) {
+ return false;
+ }
+
+ if (state.status === "running") {
+ return true;
+ }
+
+ /*
+ * Starting a completed timer begins it again from the
+ * configured duration.
+ */
+ if (state.status === "complete" || state.remainingMs <= 0) {
+ state.remainingMs = state.durationMs;
+ }
+
+ completionNotified = false;
+
+ state.endAt = Date.now() + state.remainingMs;
+
+ state.status = "running";
+
+ render();
+
+ notifyStateChange("start");
+
+ startAnimationLoop();
+
+ return true;
+ }
+
+ /* ========================================================
+ PAUSE
+ ======================================================== */
+
+ function pause() {
+ if (destroyed) {
+ return false;
+ }
+
+ if (state.status !== "running") {
+ return false;
+ }
+
+ state.remainingMs = calculateRemainingMs();
+
+ state.endAt = null;
+
+ state.status = "paused";
+
+ cancelAnimationLoop();
+
+ render();
+
+ notifyStateChange("pause");
+
+ return true;
+ }
+
+ /* ========================================================
+ RESUME
+ ======================================================== */
+
+ function resume() {
+ if (destroyed) {
+ return false;
+ }
+
+ if (state.status !== "paused") {
+ return false;
+ }
+
+ if (state.remainingMs <= 0) {
+ finishTimer();
+ return false;
+ }
+
+ completionNotified = false;
+
+ state.endAt = Date.now() + state.remainingMs;
+
+ state.status = "running";
+
+ render();
+
+ notifyStateChange("resume");
+
+ startAnimationLoop();
+
+ return true;
+ }
+
+ /* ========================================================
+ RESET
+ ======================================================== */
+
+ function reset() {
+ if (destroyed) {
+ return false;
+ }
+
+ cancelAnimationLoop();
+
+ state.remainingMs = state.durationMs;
+
+ state.endAt = null;
+
+ state.status = "idle";
+
+ completionNotified = false;
+
+ render();
+
+ notifyStateChange("reset");
+
+ return true;
+ }
+
+ /* ========================================================
+ STOP
+ ======================================================== */
+
+ function stop() {
+ if (destroyed) {
+ return false;
+ }
+
+ if (state.status === "running") {
+ state.remainingMs = calculateRemainingMs();
+ }
+
+ cancelAnimationLoop();
+
+ state.endAt = null;
+
+ /*
+ * Stop preserves the current remaining time.
+ *
+ * Reset restores the full configured duration.
+ */
+ state.status = "idle";
+
+ completionNotified = false;
+
+ render();
+
+ notifyStateChange("stop");
+
+ return true;
+ }
+
+ /* ========================================================
+ DURATION
+ ======================================================== */
+
+ function setDuration(milliseconds) {
+ if (destroyed) {
+ return false;
+ }
+
+ const newDuration = normalizeMilliseconds(milliseconds);
+
+ if (newDuration <= 0) {
+ return false;
+ }
+
+ cancelAnimationLoop();
+
+ state.durationMs = newDuration;
+
+ state.remainingMs = newDuration;
+
+ state.endAt = null;
+
+ state.status = "idle";
+
+ completionNotified = false;
+
+ render();
+
+ notifyStateChange("duration");
+
+ return true;
+ }
+
+ /* ========================================================
+ ADD / SUBTRACT TIME
+ ======================================================== */
+
+ function adjustTime(deltaMilliseconds) {
+ if (destroyed) {
+ return false;
+ }
+
+ const delta = Number(deltaMilliseconds);
+
+ if (!Number.isFinite(delta)) {
+ return false;
+ }
+
+ if (state.status === "running") {
+ state.remainingMs = calculateRemainingMs();
+ }
+
+ let newRemaining = state.remainingMs + delta;
+
+ newRemaining = Math.max(0, newRemaining);
+
+ /*
+ * If the DM adds enough time that the remaining value
+ * exceeds the original configured duration, expand the
+ * duration.
+ *
+ * Example:
+ *
+ * 10:00 timer
+ * currently 10:00
+ * DM presses +1 minute
+ *
+ * new duration = 11:00
+ * new remaining = 11:00
+ */
+ if (newRemaining > state.durationMs) {
+ state.durationMs = newRemaining;
+ }
+
+ state.remainingMs = newRemaining;
+
+ if (newRemaining <= 0) {
+ finishTimer();
+ return true;
+ }
+
+ if (state.status === "running") {
+ state.endAt = Date.now() + newRemaining;
+ } else {
+ state.endAt = null;
+
+ if (state.status === "complete") {
+ state.status = "paused";
+ }
+ }
+
+ completionNotified = false;
+
+ render();
+
+ notifyStateChange(delta >= 0 ? "add-time" : "subtract-time");
+
+ if (state.status === "running") {
+ startAnimationLoop();
+ }
+
+ return true;
+ }
+
+ function addTime(milliseconds) {
+ return adjustTime(Math.abs(Number(milliseconds) || 0));
+ }
+
+ function subtractTime(milliseconds) {
+ return adjustTime(-Math.abs(Number(milliseconds) || 0));
+ }
+
+ /* ========================================================
+ TIMER NAME
+ ======================================================== */
+
+ function setName(name) {
+ if (destroyed) {
+ return false;
+ }
+
+ state.name = typeof name === "string" ? name.trim() : "";
+
+ render();
+
+ notifyStateChange("name");
+
+ return true;
+ }
+
+ /* ========================================================
+ TIMER SKIN
+ ======================================================== */
+
+ function setSkin(skin) {
+ if (destroyed) {
+ return false;
+ }
+
+ if (!VALID_SKINS.has(skin)) {
+ return false;
+ }
+
+ state.skin = skin;
+
+ render();
+
+ notifyStateChange("skin");
+
+ return true;
+ }
+
+ /* ========================================================
+ PLAYER VISIBILITY
+ ======================================================== */
+
+ function setVisibleToPlayers(visible) {
+ if (destroyed) {
+ return false;
+ }
+
+ state.visibleToPlayers = visible === true;
+
+ render();
+
+ notifyStateChange("visibility");
+
+ return true;
+ }
+
+ function showToPlayers() {
+ return setVisibleToPlayers(true);
+ }
+
+ function hideFromPlayers() {
+ return setVisibleToPlayers(false);
+ }
+
+ /* ========================================================
+ NUMERIC DISPLAY
+ ======================================================== */
+
+ function setShowNumericToPlayers(show) {
+ if (destroyed) {
+ return false;
+ }
+
+ state.showNumericToPlayers = show === true;
+
+ render();
+
+ notifyStateChange("player-numeric");
+
+ return true;
+ }
+
+ function setShowNumericToDM(show) {
+ if (destroyed) {
+ return false;
+ }
+
+ state.showNumericToDM = show !== false;
+
+ render();
+
+ notifyStateChange("dm-numeric");
+
+ return true;
+ }
+
+ /* ========================================================
+ DISPLAY MODE
+ ======================================================== */
+
+ function setDisplayMode(mode) {
+ if (destroyed) {
+ return false;
+ }
+
+ if (!VALID_DISPLAY_MODES.has(mode)) {
+ return false;
+ }
+
+ state.displayMode = mode;
+
+ render();
+
+ notifyStateChange("display-mode");
+
+ return true;
+ }
+
+ /* ========================================================
+ RENDERER
+ ======================================================== */
+
+ function setRenderer(newRenderer) {
+ if (destroyed) {
+ return false;
+ }
+
+ renderer = newRenderer || null;
+
+ render();
+
+ return true;
+ }
+
+ /* ========================================================
+ STATE EXPORT
+ ======================================================== */
+
+ function getState() {
+ if (destroyed) {
+ return null;
+ }
+
+ syncRemainingFromClock();
+
+ return cloneState(state);
+ }
+
+ function getRemainingMs() {
+ if (destroyed) {
+ return 0;
+ }
+
+ return calculateRemainingMs();
+ }
+
+ function getRemainingRatio() {
+ if (destroyed) {
+ return 0;
+ }
+
+ return calculateRemainingRatio();
+ }
+
+ /* ========================================================
+ IMPORT / REMOTE STATE
+ ======================================================== */
+
+ function setState(incomingState, options = {}) {
+ if (destroyed) {
+ return false;
+ }
+
+ cancelAnimationLoop();
+
+ state = sanitizeState(incomingState);
+
+ /*
+ * A remote running timer should normally include
+ * endAt.
+ *
+ * If it does not, rebuild it from remainingMs.
+ */
+ if (state.status === "running" && !Number.isFinite(state.endAt)) {
+ state.endAt = Date.now() + state.remainingMs;
+ }
+
+ /*
+ * If the remote end time has already passed, show the
+ * completed state immediately.
+ */
+ if (state.status === "running" && state.endAt <= Date.now()) {
+ state.remainingMs = 0;
+ state.endAt = null;
+ state.status = "complete";
+ }
+
+ completionNotified = state.status === "complete";
+
+ render();
+
+ /*
+ * Normally remote synchronization should not be
+ * rebroadcast, otherwise DM and Player Display could
+ * bounce the same timer update back and forth.
+ */
+ if (options.notify === true) {
+ notifyStateChange(options.reason || "set-state");
+ }
+
+ if (state.status === "running") {
+ startAnimationLoop();
+ }
+
+ return true;
+ }
+
+ /*
+ * Convenience alias specifically intended for data that
+ * arrived from another display/window.
+ */
+ function applyRemoteState(incomingState) {
+ return setState(incomingState, {
+ notify: false,
+ });
+ }
+
+ /* ========================================================
+ PAGE VISIBILITY
+ ======================================================== */
+
+ /*
+ * requestAnimationFrame may be throttled or completely
+ * paused when a browser tab/window is not visible.
+ *
+ * That is okay because the timer uses an absolute endAt.
+ *
+ * When the document becomes visible again, immediately
+ * recalculate from Date.now().
+ */
+ function handleVisibilityChange() {
+ if (destroyed) {
+ return;
+ }
+
+ if (state.status !== "running") {
+ return;
+ }
+
+ const remaining = syncRemainingFromClock();
+
+ if (remaining <= 0) {
+ finishTimer();
+ return;
+ }
+
+ render();
+
+ if (!document.hidden) {
+ startAnimationLoop();
+ }
+ }
+
+ document.addEventListener("visibilitychange", handleVisibilityChange);
+
+ /* ========================================================
+ DESTROY
+ ======================================================== */
+
+ function destroy() {
+ if (destroyed) {
+ return;
+ }
+
+ destroyed = true;
+
+ cancelAnimationLoop();
+
+ document.removeEventListener("visibilitychange", handleVisibilityChange);
+
+ controllers.delete(api);
+
+ renderer = null;
+ }
+
+ /* ========================================================
+ PUBLIC CONTROLLER API
+ ======================================================== */
+
+ const api = {
+ start,
+ pause,
+ resume,
+ reset,
+ stop,
+
+ setDuration,
+
+ adjustTime,
+ addTime,
+ subtractTime,
+
+ setName,
+ setSkin,
+
+ setVisibleToPlayers,
+ showToPlayers,
+ hideFromPlayers,
+
+ setShowNumericToPlayers,
+ setShowNumericToDM,
+
+ setDisplayMode,
+
+ setRenderer,
+
+ getState,
+ getRemainingMs,
+ getRemainingRatio,
+
+ setState,
+ applyRemoteState,
+
+ render,
+
+ destroy,
+
+ get status() {
+ return state.status;
+ },
+
+ get running() {
+ return state.status === "running";
+ },
+
+ get paused() {
+ return state.status === "paused";
+ },
+
+ get complete() {
+ return state.status === "complete";
+ },
+ };
+
+ controllers.add(api);
+
+ /*
+ * Render the initial state immediately.
+ */
+ render();
+
+ /*
+ * If an imported initial state is already running,
+ * continue rendering from its absolute end timestamp.
+ */
+ if (state.status === "running") {
+ if (!Number.isFinite(state.endAt)) {
+ state.endAt = Date.now() + state.remainingMs;
+ }
+
+ startAnimationLoop();
+ }
+
+ return api;
+ }
+
+ /* ============================================================
+ PUBLIC ENC API
+ ============================================================ */
+
+ ENC.timer = {
+ VERSION: TIMER_VERSION,
+
+ DEFAULT_DURATION_MS,
+
+ skins: Object.freeze(["hourglass", "candle", "scifi-pixels"]),
+
+ displayModes: Object.freeze(["overlay", "featured", "focus"]),
+
+ create: createTimer,
+
+ createDefaultState() {
+ return sanitizeState({
+ ...DEFAULT_STATE,
+ id: createTimerId(),
+ });
+ },
+
+ getControllerCount() {
+ return controllers.size;
+ },
+ };
+})(window.ENC);
diff --git a/programs/enCounter_version_info.txt b/programs/enCounter_version_info.txt
index b690aeb..0899d74 100644
--- a/programs/enCounter_version_info.txt
+++ b/programs/enCounter_version_info.txt
@@ -4,8 +4,8 @@
VSVersionInfo(
ffi=FixedFileInfo(
- filevers=(0, 1, 0, 0),
- prodvers=(0, 1, 0, 0),
+ filevers=(0, 2, 0, 0),
+ prodvers=(0, 2, 0, 0),
mask=0x3f,
flags=0x0,
OS=0x40004,
@@ -20,11 +20,11 @@ VSVersionInfo(
[
StringStruct(u'CompanyName', u'Zygons'),
StringStruct(u'FileDescription', u'enCounter TTRPG Encounter Console'),
- StringStruct(u'FileVersion', u'0.1.0-alpha.1'),
+ StringStruct(u'FileVersion', u'0.2.0-alpha.1'),
StringStruct(u'InternalName', u'enCounter'),
StringStruct(u'OriginalFilename', u'enCounter.exe'),
StringStruct(u'ProductName', u'enCounter'),
- StringStruct(u'ProductVersion', u'0.1.0-alpha.1'),
+ StringStruct(u'ProductVersion', u'0.2.0-alpha.1'),
StringStruct(u'LegalCopyright', u'Copyright (C) 2026 Zygons'),
StringStruct(u'Comments', u'Open-source software licensed under the MIT License')
]
diff --git a/programs/launcher.py b/programs/launcher.py
index b4c1851..b977947 100644
--- a/programs/launcher.py
+++ b/programs/launcher.py
@@ -20,7 +20,7 @@
PORT = 5500
APP_NAME = "enCounter"
-APP_VERSION = "0.1.0-alpha.1"
+APP_VERSION = "0.2.0-alpha.1"
APP_STAGE = "Alpha"
if getattr(sys, "frozen", False):
@@ -53,9 +53,14 @@
"icons/combat",
"icons/systems",
"tokens",
+ "sounds/music",
+ "sounds/ambience",
+ "sounds/sfx",
+ "sounds/custom",
}
ALLOWED_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".webp"}
-PUBLIC_ASSET_EXTENSIONS = ALLOWED_IMAGE_EXTENSIONS | {".ico", ".wav", ".mp3", ".ogg", ".flac"}
+ALLOWED_AUDIO_EXTENSIONS = {".wav", ".mp3", ".ogg", ".flac"}
+PUBLIC_ASSET_EXTENSIONS = ALLOWED_IMAGE_EXTENSIONS | ALLOWED_AUDIO_EXTENSIONS | {".ico"}
APP_FILE_EXTENSIONS = {".html", ".css", ".js", ".map"}
DOC_FILE_EXTENSIONS = {".html", ".md", ".txt"}
PUBLIC_ROOT_FILES = {
@@ -66,7 +71,7 @@
"/THIRD_PARTY_NOTICES.md",
"/CHANGELOG.md",
}
-MAX_UPLOAD_BYTES = 10 * 1024 * 1024
+MAX_UPLOAD_BYTES = 50 * 1024 * 1024
MAX_BACKUP_BYTES = 50 * 1024 * 1024
for path in [BACKUP_DIR, EXPORT_DIR, IMPORT_DIR]:
@@ -117,6 +122,21 @@ def detect_image_type(data: bytes) -> str | None:
return None
+def detect_audio_type(data: bytes) -> str | None:
+ """Return a normalized MIME type for supported audio signatures, or None."""
+ if data.startswith(b"ID3"):
+ return "audio/mpeg"
+ if len(data) >= 2 and data[0] == 0xFF and (data[1] & 0xE0) == 0xE0:
+ return "audio/mpeg"
+ if data.startswith(b"OggS"):
+ return "audio/ogg"
+ if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WAVE":
+ return "audio/wav"
+ if data.startswith(b"fLaC"):
+ return "audio/flac"
+ return None
+
+
class EnCounterHandler(http.server.SimpleHTTPRequestHandler):
server_version = f"{APP_NAME}Local/{APP_VERSION}"
@@ -273,7 +293,9 @@ def do_GET(self):
if relative.startswith("branding/"):
continue
- if file_path.suffix.lower() not in ALLOWED_IMAGE_EXTENSIONS:
+ if file_path.suffix.lower() not in PUBLIC_ASSET_EXTENSIONS:
+ continue
+ if file_path.suffix.lower() == ".ico":
continue
category = Path(relative).parent.as_posix()
@@ -328,27 +350,53 @@ def do_POST(self):
content_length = self._read_content_length(MAX_UPLOAD_BYTES)
if content_length is None:
- return self.send_text("Image must be between 1 byte and 10 MB.", 400)
+ return self.send_text("Asset must be between 1 byte and 50 MB.", 400)
filename = safe_name(requested_name)
extension = Path(filename).suffix.lower()
- if extension not in ALLOWED_IMAGE_EXTENSIONS:
- return self.send_text("Only PNG, JPEG, and WebP images are allowed.", 400)
+ is_audio = category.startswith("sounds/")
+ allowed_extensions = ALLOWED_AUDIO_EXTENSIONS if is_audio else ALLOWED_IMAGE_EXTENSIONS
+ if extension not in allowed_extensions:
+ return self.send_text(
+ "Only MP3, OGG, WAV, and FLAC audio files are allowed."
+ if is_audio
+ else "Only PNG, JPEG, and WebP images are allowed.",
+ 400,
+ )
content_type = self.headers.get("Content-Type", "").split(";", 1)[0].lower()
- expected_mime = {
- ".png": "image/png",
- ".jpg": "image/jpeg",
- ".jpeg": "image/jpeg",
- ".webp": "image/webp",
- }[extension]
- if content_type != expected_mime:
- return self.send_text("The file extension does not match its image type.", 400)
-
- data = self.rfile.read(content_length)
- detected_mime = detect_image_type(data)
- if detected_mime != expected_mime:
- return self.send_text("The uploaded file is not a valid supported image.", 400)
+ if is_audio:
+ allowed_mimes = {
+ ".mp3": {"audio/mpeg", "audio/mp3"},
+ ".ogg": {"audio/ogg", "application/ogg"},
+ ".wav": {"audio/wav", "audio/x-wav", "audio/wave"},
+ ".flac": {"audio/flac", "audio/x-flac"},
+ }
+ if content_type not in allowed_mimes[extension]:
+ return self.send_text("The file extension does not match its audio type.", 400)
+ data = self.rfile.read(content_length)
+ detected_audio = detect_audio_type(data)
+ normalized_expected = {
+ ".mp3": "audio/mpeg",
+ ".ogg": "audio/ogg",
+ ".wav": "audio/wav",
+ ".flac": "audio/flac",
+ }[extension]
+ if detected_audio != normalized_expected:
+ return self.send_text("The uploaded file is not valid supported audio.", 400)
+ else:
+ expected_mime = {
+ ".png": "image/png",
+ ".jpg": "image/jpeg",
+ ".jpeg": "image/jpeg",
+ ".webp": "image/webp",
+ }[extension]
+ if content_type != expected_mime:
+ return self.send_text("The file extension does not match its image type.", 400)
+ data = self.rfile.read(content_length)
+ detected_mime = detect_image_type(data)
+ if detected_mime != expected_mime:
+ return self.send_text("The uploaded file is not a valid supported image.", 400)
folder = ROOT / "assets" / category
folder.mkdir(parents=True, exist_ok=True)
diff --git a/tests/core.test.js b/tests/core.test.js
index 68e47f8..3b4177d 100644
--- a/tests/core.test.js
+++ b/tests/core.test.js
@@ -194,3 +194,52 @@ test("player display next-turn helper can advance from a hidden current combatan
const next = ENC.findNextPlayerVisibleEligibleCombatant(combatants, "hidden");
assert.equal(next?.id, "c");
});
+
+test("sanitizeAudioUrl accepts only local supported sound assets", () => {
+ assert.equal(
+ ENC.sanitizeAudioUrl("/assets/sounds/ambience/forest.mp3"),
+ "/assets/sounds/ambience/forest.mp3",
+ );
+ assert.equal(ENC.sanitizeAudioUrl("https://example.com/forest.mp3"), "");
+ assert.equal(ENC.sanitizeAudioUrl("/assets/backgrounds/forest.mp3"), "");
+});
+
+test("normalizeEncounter preserves scene/combat display modes and soundscape", () => {
+ const encounter = ENC.normalizeEncounter({
+ kind: "saved",
+ phase: "scene",
+ playerDisplayMode: "scene",
+ display: {
+ sceneImage: "/assets/backgrounds/fantasy/market.png",
+ combatImage: "/assets/backgrounds/fantasy/battle.png",
+ },
+ soundscape: {
+ masterVolume: 0.75,
+ scene: {
+ ambience: [
+ {
+ name: "Market",
+ asset: "/assets/sounds/ambience/market.mp3",
+ volume: 0.5,
+ combatBehavior: "duck",
+ combatVolume: 0.2,
+ },
+ ],
+ },
+ combat: {
+ music: {
+ name: "Battle",
+ asset: "/assets/sounds/music/battle.mp3",
+ volume: 0.6,
+ },
+ },
+ },
+ });
+
+ assert.equal(encounter.kind, "saved");
+ assert.equal(encounter.phase, "scene");
+ assert.equal(encounter.playerDisplayMode, "scene");
+ assert.equal(encounter.display.sceneImage, "/assets/backgrounds/fantasy/market.png");
+ assert.equal(encounter.soundscape.scene.ambience[0].combatBehavior, "duck");
+ assert.equal(encounter.soundscape.combat.music.asset, "/assets/sounds/music/battle.mp3");
+});
New Encounter