dd-timer/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Règles de collaboration

• Toujours répondre et écrire en français
• Ne jamais modifier les fichiers de tests sans le signaler explicitement à l'utilisateur avant de le faire
• Toujours écrire des tests (unitaires + fonctionnels/régression) lors de toute correction de bug ou ajout de feature — les tests font partie de la livraison, pas une étape optionnelle
• Toujours mettre à jour algorithmes.md quand un algorithme ou une formule de calcul change
• Ne jamais utiliser de taux fixe pour les jauges — toujours utiliser gainedIn / timeToGain avec traversée des tiers (erreur historique du monolithe)
• Signaler explicitement tout changement qui touche aux snapshots du timer (snapGauges, snapStats, gaugeRecharges) car cela peut affecter tous les calculs en cours de session
• Les tests ne tournent pas en WSL — toujours rappeler à l'utilisateur de lancer npm test depuis un terminal Windows

Project Overview

Obsidienne (anciennement "Minuteur Dragodinde") is a Windows desktop app (Electron + Vite + TypeScript) for managing Dragodinde breeding timers in Dofus 3. French-language UI.

Commands

• Dev: npm start (runs Vite dev server + Electron via vite-plugin-electron)
• Build: npm run build (Vite build + electron-builder → NSIS installer in dist/)
• Test: npm test (Vitest, run from Windows — native bindings incompatible with WSL)
• Test watch: npm run test:watch
• Build scripts: build.bat (auto-elevates to admin) or build.ps1 for Windows

Architecture

DDD hexagonal architecture with Vite + TypeScript. Four layers:

src/
  domain/          — Entities, value objects, domain services (pure TS, no deps)
  application/     — Command handlers, query handlers, CommandBus/QueryBus
  infrastructure/  — LocalStorageRepository, ElectronNotification, WebAudioAlarm
  presentation/    — Components, helpers, UIState, entry point (index.ts)

Domain layer

• entities/Enclos.ts — Enclos entity with TimerData (includes gaugeRecharges: Record<string, GaugeRecharge[]>)
• entities/Dragodinde.ts — DD entity with stats, targets, levelTarget, sereniteTarget
• services/GaugeCalculator.ts — Core pure functions: gainedIn, timeToGain, gaugeAfter, elapsed, computeGaugeState
• value-objects/GaugeType.ts — GAUGE_DEFS, STAT_DEFS, DEFAULT_TARGETS (mangeoire default = 100, but UI uses 200 when levelTarget is null)
• value-objects/XpTable.ts — xpForLevel, levelFromXp
• value-objects/Tier.ts — tierNum, tierRate

Application layer

Commands: StartTimer, StopTimer, CompleteTimer, ResetTimer, CreateEnclos, DeleteEnclos, AddDragodinde, RemoveDragodinde, UpdateGauge (toggle + level), RechargeGauge, RegisterAccouplement, UpdateSettings, ResetStats, ReorderEnclos, UpdateWorkflow, DeleteWorkflow, EnclosActions (clear, rename, reset-timer), DragodindeActions (rename, update-stat, seren-target, level-target, reorder)

Queries: GetDashboard, GetEnclosDetail, GetTimerState, GetBreedingOptions, GetReapproTree, GetInventaire, GetSettings, GetWorkflows

Presentation layer

• components/App.ts — Root component, animation loop (requestAnimationFrame), CommandBus/QueryBus wiring
• components/EnclosView.ts — Main timer view: gauge inputs (with input listener for real-time updates), DD grid, "Alarme dans" display
• components/DragodindeCard.ts — Per-DD card: stat pills, targets (all with input listeners for real-time preview)
• helpers/gauge-live.ts — All live calculation helpers: computeGaugeLive, enclosGaugeCurGl, enclosGlobalState, calcSerenEtaLive, calcLevelEtaLive

Key data flows

Timer start (fresh): snapshots gaugeLevels → snapGauges, DD stats → snapStats, clears gaugeRecharges Timer resume (from pause): accumulates pausedMs += now - pausedAt, preserves snapshots Gauge recharge (during timer): pushes { atSec, level } to gaugeRecharges[gid], updates gaugeLevels[gid] Live display: requestAnimationFrame loop → enclosGlobalState(enc) → per-DD computeGaugeLive → DOM updates

Timer calculation core — computeGaugeState

The central calculation function. Handles:

• Multiple gauge recharges during a session (segments between each recharge)
• Freeze at absolute stat cap (sérénité ±5000, end/mat/amour 20000, niveau 200)
• Returns { gained, curGl, effectiveEl }

Pre-start preview: enclosGlobalState computes even when timer not started (started = false), using current gaugeLevels as startGl and el = 0. "Alarme dans" updates in real-time as the user types gauge values and DD targets.

XP gauge (mangeoire): when the target is unreachable in a single gauge drain, countdown shows drain time instead of ∞. Formula: timeToGain(curGl, Math.min(xpRestante, curGl)) — consistent with "Vide en" display.

Default level target: when dd.levelTarget === null, the XP gauge defaults to targeting level 200.

IPC channels

Main→Renderer: app-version, play-alarm-sound, update-available, update-downloading, update-progress, update-ready, update-error Renderer→Main: trigger-alarm, show-notification, send-ntfy, focus-window, install-update, get-version

Auto-update flow

Checks Gitea Releases API on startup (after 3s) and hourly. Downloads NSIS Setup .exe to temp, launches with /S (silent), then quits app.

Dev vs packaged mode

When !app.isPackaged, userData is stored in Obsidienne-DEV (isolated from installed app) and a DEV badge is injected into the UI. On first packaged launch, data is auto-migrated from the old Minuteur Dragodinde folder.

Tests

tests/
  unit/domain/        — GaugeCalculator, Enclos, Dragodinde, XpTable, etc.
  unit/application/   — commands.test.ts, queries.test.ts, CommandBus.test.ts
  unit/infrastructure/
  functional/         — breeding-workflow, enclos-management, timer-workflow
  regression/         — gauge-tier-calculation, gauge-recharge, xp-timer-display, etc.

Vitest with path aliases (@domain, @application, @infrastructure, @presentation). Run with npm test from Windows.

Key conventions

• All UI text is in French
• TypeScript strict mode — no any unless unavoidable
• Immutable domain entities (functions return new objects)
• Commands mutate shared state object directly (no Redux-style reducers)
• repo.save(state) called after every state mutation
• CSS uses custom properties in :root (dark purple/gaming aesthetic), component styles in src/presentation/styles/