Imported from sapategu/podomoro-deno (AGENTS.md). Install upstream with npx skills add sapategu/podomoro-deno. Copyright stays with the author.

AGENTS.md

Working notes for anyone — human or agent — changing this repository.

Cadence is a focus-session timer built on deno desktop (Deno 2.9), targeting Fedora / GNOME. Read README.md first for what the app is; this file covers how to work on it and the runtime traps that cost real time to discover.

Commands

deno task doctor    # check this machine's desktop integration support
deno task dev       # build + run
deno task build     # distributable bundle -> dist/Cadence/
deno task test      # 25 tests, no display server needed
deno task verify    # check + lint + test — run before every commit

deno task verify is the gate. Do not commit with it failing.

Dependencies live in deno.json and are pinned in deno.lock. There is no install step; do not add a node_modules or a package manager.

Verified runtime behaviour

These were established empirically against Deno 2.9.3 + laufey webview 0.5.0 on Fedora. The published docs at https://docs.deno.com/runtime/desktop/ are wrong or silent on every one of them. If a change depends on desktop API behaviour, verify it against the installed runtime rather than trusting doc prose — write a throwaway probe, build it, run it, read the error.

• Menu items are an externally tagged union, not the flat objects the docs show:

  { item: { label, id?, accelerator?, enabled, checked? } }   // enabled is REQUIRED
  { submenu: { label, items } }                               // items is REQUIRED
  "separator"
  { role: { role: "quit" } }

  A flat { label, id, enabled } fails with serde_v8 error: length mismatch, got: 3, expected: 1. That error means "wrong union shape", not "wrong argument count".

• setApplicationMenu and showContextMenu are BrowserWindow methods, not Deno.* functions. showContextMenu(x, y, items) takes three positional arguments in screen coordinates.

• executeJs resolves to { ok, value }, not the bare value, and cannot await a promise — it returns { ok: false, value: "Unsupported result type" }.

• Tray.setIcon requires raw PNG bytes (Uint8Array). A file path string is rejected with expected typed ArrayBufferView. This is why src/png.ts exists.

• Deno.Tray is a no-op on Linux. new Deno.Tray(), setIcon, setTooltip and setMenu all return cleanly, trayId is always 0, getBounds() is always null, and no StatusNotifierItem is ever registered on the session bus — verified on both the webview and cef backends with a working AppIndicator host present. The icon simply never appears. TrayController.verifyRegistration() detects this by fingerprinting the watcher's registered-item list before and after init, and self-corrects once the runtime implements the tray. Do not "fix" the tray by removing that check.

• The constructor's title option never reaches the window manager. A window that is not given an explicit setTitle() renders with the literal title (null). navigate() then replaces the title with the URL, so set it again after navigating — see openAuxWindow in src/main.ts.

• setPosition does nothing on Wayland. A Wayland client cannot position its own surface; the call is accepted and the window stays put. setSize, setOpacity and setAlwaysOnTop do work.

• Frameless windows are unusable on Wayland. frameless: true works, but WebKitGTK does not support -webkit-app-region: drag (CSS.supports(...) is false) and setPosition is ignored, so nothing can move the window. Native decorations are deliberate — do not switch to a custom headerbar without solving dragging first. Native window mousedown/mousemove events report window-relative coordinates in both clientX and screenX, so they cannot substitute for screen coordinates either.

• The first BrowserWindow created is adopted as the main window and auto-navigated to /. Create it synchronously at startup, or the runtime makes its own and you end up with a second blank window. navigate() called later works normally — see openAuxWindow in src/main.ts.

• win.bind() bindings do not work. The name registers, then every call rejects with No callback bound for: <name>. The app uses Deno.serve + fetch + SSE instead. The binding API is typed in src/native/types.ts for whenever it is fixed — do not migrate to it without verifying it first.

• Permissions are baked in at compile time (deno desktop -A ...), not at run time. A missing permission surfaces as a NotCapable error inside the built app, not at build time.

• deno desktop main.ts builds; it does not run. The output is a directory bundle and the executable is the inner binary (dist/Cadence/Cadence, not dist/Cadence).

• Deno.dock is macOS-only. On Linux every call is accepted and silently ignored. Keep the calls wrapped in try/catch and never make behaviour depend on them.

Platform constraints (Fedora / GNOME)

• The tray needs a StatusNotifierItem host, which stock GNOME 40+ does not provide. Without gnome-shell-extension-appindicator the icon never appears and nothing reports an error. src/native/tray.ts detects this by looking for StatusNotifierWatcher on the session bus and surfaces it in the log, in /api/diagnostics, and as a banner in the UI.
• Enabling that extension requires a logout/login. gnome-extensions enable fails with "does not exist" until GNOME Shell rescans, and Wayland cannot restart the shell in place. Writing the UUID into org.gnome.shell enabled-extensions via gsettings works ahead of time.
• Never report a probe failure as a missing feature. A denied read and an absent package look identical to naive code — hasLibrary in scripts/doctor.ts returns "unknown" rather than false when nothing was scannable, because the earlier version claimed WebKitGTK was missing on a machine that had it.

Architecture rules

State flows one way:

Store ──snapshot──> tray icon / menus / window title / SSE ──> web views
  ^                                                              |
  └────────── handleMenuAction  |  POST /api/*  <────────────────┘

• src/state.ts must not import anything from the desktop runtime. That is what keeps the timer and task model testable under plain deno test with no display server. Tests run headless; keep it that way.
• Every native surface is a subscriber, never a second source of truth. If the tray and the window can disagree, the change is wrong.
• All menu ids funnel through handleMenuAction in src/main.ts. Dynamic ids encode their target after a colon (ctx:delete:<uuid>). Add new ids to the MenuAction union in src/native/menu.ts.
• Menus are rebuilt from a snapshot, not mutated. There is no API to toggle one item. Rebuilds are gated behind a signature check in renderNative — rebuilding on every 250ms tick makes the OS menu flicker and closes an open tray menu.
• Modal dialogs block the Deno thread. alert/confirm/prompt stop the timer and queue HTTP requests behind them. Route every dialog through src/native/dialogs.ts, which pauses the clock across the call deliberately. Do not use them for anything non-modal.

Conventions

• Comments explain why, not what. Several comments in this repo record a runtime trap that is invisible from the code — do not strip them as noise.
• Errors from native calls are logged and swallowed, never thrown into the timer loop: a failed tooltip update must not stop the clock.
• deno fmt before committing (lineWidth 110). deno lint must be clean.
• Cover new store behaviour in tests/. Advance phases with skip() rather than waiting on real time.