feat: per-widget refresh-interval and force-refresh endpoint

[jrnxf]

Closes #327 (request).

This is a fresh take on per-widget refresh, written specifically around the two
concerns you raised on that issue and on #793:

The front-end wasn't built in a way where you can unload/unmount anything, so
refreshing individual widgets without reloading the entire page isn't possible
currently.

The setupPage function calls other functions, some of which add event
listeners to the window/document and have no way of removing those
listeners. If you simply call the setupPage function over and over, you're
creating a memory leak…

I'm not sure how a dedicated refresh button on the page is any different than
just hitting the refresh button in your browser.

All are addressed below.

What it does

• New refresh-interval: <duration> field on every widget. When set, the
  client polls GET /api/widgets/{id}/refresh on that interval and swaps the
  widget's outerHTML in place.
• The endpoint at GET /api/widgets/{widget}/refresh (the route was already
  reserved with a TODO comment in glance.go). ?force=1 bypasses the
  widget's cache; without it, a tick within the cache window just re-renders
  existing data (no upstream call). This is what the existing cache: field
  becomes useful for once you have client polling.
• A validate() call at config load rejects refresh-interval on widget
  types that hold interactive client state, embed external content, or have
  nothing to refetch (calendar, to-do, clock, iframe, html,
  search, bookmarks, group, split-column). Fails fast at config load
  rather than silently ignoring. Minimum 5s as a typo-floor.

Addressing your concerns

"the frontend wasn't built to unmount" — handled, no global lifecycle refactor

I deliberately did not introduce a generic widget lifecycle. Instead:

1. The setupX() functions in page.js, popover.js, masonry.js now
   accept an optional root = document argument. Existing call sites pass
   nothing and behave identically.
2. A small per-widget cleanup-callback registry (_cleanupCallbacks on the
   widget's root element) — only the three setups that bind to
   window/document or instantiate observers register a callback:
   setupCarousels (window resize listener), setupCollapsibleGrids and
   setupMasonries (ResizeObserver). All other setups bind to widget
   descendants and are released naturally when the old DOM is replaced.
3. runWidgetCleanup(widgetEl) runs those callbacks before outerHTML is
   swapped. The new node has its own fresh registry.
4. setupDynamicRelativeTime was the one global timer that captured a stale
   elements array — it now queries the document fresh on each tick and is
   initialized only once. Refreshed widgets are picked up automatically.
5. afterContentReady fires immediately when called post-init, so refresh-
   path setups don't queue forever.

I verified there's no listener accumulation by leaving a horizontal-cards RSS
widget refreshing for several cycles in a real browser and watching its
_cleanupCallbacks count — it stays at 1, not climbing.

"many times more upstream requests" — the math doesn't actually pencil out that way

The whole mechanism is built around cache: being the rate limiter, not the
client interval:

• A client tick inside the cache window calls requiresUpdate → false →
  re-renders the existing buffer. Zero upstream calls.
• A client tick outside the cache window fires exactly one update(),
  serialized by the per-widget mutex (and re-checked inside the lock so two
  concurrent renders can't double-fire).

So with the typical RSS default of cache: 1h and refresh-interval: 1m,
that's 60 client ticks per hour producing 1 upstream call per hour — the
same call cadence you have today, just delivered to the browser without a
manual reload. The user has to set cache: to something tighter to actually
increase upstream traffic, which is the same lever that exists today.

"only update while in foreground" — done

visibilitychange clears all interval handles when the tab is hidden and
reinstalls them on focus, with an immediate refresh if the interval already
elapsed during the hidden period. Tab in the background → zero requests.

"should be per-widget basis" — done

Opt-in per widget, default off. Disallow list enforced at config load.

"how is this different from a browser refresh?" — three things

• Force-bypass the cache. A browser refresh re-runs the page render but
  requiresUpdate short-circuits when the cache is fresh. You can't actually
  pull new data on demand without restarting the server. ?force=1 does.
• Preserves page state. Scroll, theme picker, popovers, expanded lists in
  other widgets, etc.
• Per-widget intervals. The whole point is that monitor / dns-stats /
  server-stats each have their own cadence without a page-wide reload that
  also refetches feeds and other slow widgets.

Locking

The previously-stubbed handleWidgetRequest had a TODO calling out the
locking rework. That's the other half of the backend commit:

• widgetBase gets a sync.Mutex.
• renderTemplate takes the lock (covers all .Render paths via the
  shared templateBuffer).
• updateOutdatedWidgets and containerWidgetBase._update lock per-widget
  around update(ctx) and re-check requiresUpdate inside the lock so two
  concurrent page renders can't both fire the same upstream call.
• The page-level lock around updateOutdatedWidgets is removed (and the
  unused page.mu field with it).

Render() and update() don't recursively call each other in any widget
type, so re-entrance isn't a risk. Containers (group, split-column) don't
have their own mutex contention with children — different mutex objects.

What's not in this PR

• No refresh button UI. Easy follow-up; deliberately out of scope so this PR
  stays focused on the mechanism.
• No persistence of cache across restarts.

Test notes

• TestWidgetValidateRefreshInterval covers the disallow list, the
  minimum-interval floor, and the no-interval baseline.
• TestRegisterWidgetIncludesContainerChildren covers recursive
  registration of nested widgets.
• TestUpdateOutdatedWidgetsDedupesConcurrentCalls and
  TestContainerUpdateDedupesConcurrentCalls fire 10 concurrent renders
  against a counter-stub widget and assert exactly one update() fires —
  evidence that the locking scheme actually delivers the API politeness
  claim above.
• Existing tests all pass.
• Manually exercised in browser across: hacker-news, rss (list +
  horizontal-cards/carousel), monitor, server-stats, dns-stats,
  custom-api. Auto-refresh swaps cleanly, popovers and lazy-images keep
  working post-swap, console stays clean across cycles.
• Visibility pause: tab → background → no requests; tab → foreground → fires
  immediate refresh if interval elapsed.

Happy to split the PR, change naming, restructure the cleanup registry, or
rewrite the description — just let me know what fits the project's direction.

[jrnxf]

@svilenmarkov any chance I could get your eyes on this? Think it would be a big add a lot of people would benefit from! 🍻