left4me/docs/superpowers/specs/2026-05-16-timeago-shared-display-design.md

Shared relative-time display helper (spec)

Brainstorm scratch artifact. On approval, copy to docs/superpowers/specs/2026-05-16-timeago-shared-display-design.md and commit (per AGENTS.md planning-artifact convention).

Context

left4me's web UI renders datetimes inconsistently. Three styles coexist:

1. Raw Python datetime repr in admin/blueprint/job tables (admin_users.html, blueprints.html, _job_table.html, job_detail.html) — unfriendly for users.
2. Bespoke inline math in templates/_live_state.html — three expressions of the form ((now - x).total_seconds() // 60) | int }}m ago with their own vocabulary (12s ago, 0m ago inside the first minute, no singular handling).
3. Centralised but Python-side humanize_delta (in l4d2web/l4d2web/services/timeago.py) called from page_routes.py for latest_job_when and latest_build_when. Correct output but only reachable by route-side precomputation, so adoption is friction-heavy.

The existing humanize_delta also has three design gaps that make it unsuitable as the single source of truth:

• No sub-minute precision (under 45s it returns just now, hiding the detail _live_state.html cares about).
• Future timestamps are clamped to just now (latent bug).
• Falls back to a bare ISO date (2025-04-21) after 7 days, which reads awkwardly next to relative siblings.

This spec unifies the three styles behind one Jinja filter, fixes the ladder, and leaves a known follow-up.

Goal

Every user-facing datetime in l4d2web templates flows through one filter, {{ ts | timeago }}, producing a self-describing HTML <time> element that combines a friendly relative label with a precise tooltip.

Contract

A single Jinja filter timeago returns a markupsafe.Markup wrapping an HTML <time> element:

<time datetime="2026-05-16T14:32:11+00:00"
      title="2026-05-16 14:32:11 UTC">5 minutes ago</time>

• datetime= carries the ISO 8601 form with explicit timezone offset.
• title= is the hover tooltip — human-readable UTC string.
• The text node is the relative label produced by the ladder below.

Ladder (long form, symmetric for past and future)

abs(delta)	Past label	Future label
0 (sub-second)	now	now
< 60s	1 second ago / N seconds ago	in 1 second / in N seconds
< 60m	1 minute ago / N minutes ago	in 1 minute / in N minutes
< 24h	1 hour ago / N hours ago	in 1 hour / in N hours
< 7d	1 day ago / N days ago	in 1 day / in N days
≥ 7d, same year as now	16 Feb	30 May
≥ 7d, different year	16 May 2025	16 May 2027

• Singular form when the leading number is exactly 1.
• Day-first English month abbreviation (16 Feb, not Feb 16).
• Year suppressed only when then.year == now.year.
• then.day rendered without leading zero (use then.day directly, not %d, for portability).

Defensive input handling

• then.tzinfo is None → assume UTC (preserves current behaviour and works against today's naive-UTC SQLite columns; becomes a harmless no-op once the follow-up cleanup lands).
• now defaults to datetime.now(UTC) and is similarly normalised.
• None is not accepted — callers guard nullable columns with {% if x %}{{ x | timeago }}{% else %}-{% endif %}.

Module shape

File: l4d2web/l4d2web/services/timeago.py (existing).

Two callables, one source of truth for the ladder:

• humanize_delta(then: datetime, now: datetime | None = None) -> str — pure text; ladder above. Kept for non-HTML callers (e.g. log lines, emails) and for unit-testing the label logic in isolation.
• format_time_html(then: datetime, now: datetime | None = None) -> Markup — wraps humanize_delta in the <time> element. UTC-normalises then for the datetime= and title= attributes. Escapes the title via markupsafe.escape (defensive — ISO strings carry no HTML-special characters, but the explicit call is free and keeps the helper trustworthy if its inputs ever grow).

Register format_time_html as Jinja filter timeago in the Flask app factory.

Files to modify

Helper + registration

• l4d2web/l4d2web/services/timeago.py — rewrite humanize_delta to the symmetric ladder with sub-minute precision and future support; add format_time_html.
• Flask app factory (locate during implementation; likely l4d2web/l4d2web/app.py or __init__.py) — register format_time_html as filter timeago: app.add_template_filter(format_time_html, "timeago").

Templates (replace raw datetimes / bespoke math)

• l4d2web/l4d2web/templates/admin_users.html:25-26
• l4d2web/l4d2web/templates/blueprints.html:17-18
• l4d2web/l4d2web/templates/_job_table.html:22-23
• l4d2web/l4d2web/templates/job_detail.html:24-26
• l4d2web/l4d2web/templates/_live_state.html:10, 31, 55

For nullable columns (finished_at, started_at, last_downloaded_at), preserve the current - placeholder:

{% if job.finished_at %}{{ job.finished_at | timeago }}{% else %}-{% endif %}

Routes

• l4d2web/l4d2web/routes/page_routes.py:240, 294, 443, 475 — drop the inline humanize_delta imports and latest_job_when / latest_build_when precomputation. Pass the raw datetime into the template context (rename keys to latest_job_at / latest_build_at for type-honesty) and let the templates call | timeago.

_live_state.html now parameter

After the rewrite, check whether the now context variable is still referenced anywhere in _live_state.html. If not, remove it from the template render call (likely in page_routes.py and server_routes.py) and from whichever helper builds the live-state context. Dead-code cleanup, not behaviour change.

Files to read for context during implementation

• l4d2web/l4d2web/services/timeago.py:1-29 — current ladder, the function we're extending.
• l4d2web/l4d2web/models.py:22-23 — now_utc() factory.
• l4d2web/l4d2web/routes/profile_routes.py:86-88 — documented workaround comment that explains why naive datetimes exist (informs the defensive tzinfo is None line).
• l4d2web/l4d2web/routes/page_routes.py:240-294, 443-475 — the existing precomputation pattern being removed.

Testing

Unit tests (l4d2web/tests/test_timeago.py, new file)

Parameterised boundary coverage for humanize_delta:

Input delta	Expected
0	now
+1s past	1 second ago
+2s past	2 seconds ago
+59s past	59 seconds ago
+60s past	1 minute ago
+1m past	1 minute ago
+59m past	59 minutes ago
+60m past	1 hour ago
+23h past	23 hours ago
+24h past	1 day ago
+6d past	6 days ago
+7d past, same year	date form (e.g. now=2026-02-23 → 16 Feb)
+1y past, different year	date form with year (e.g. now=2026-05-16 → 16 May 2025)
-1s future	in 1 second
-59s future	in 59 seconds
-60s future	in 1 minute
-1d future	in 1 day
-7d future, same year	date form
-1y future, different year	date form

Plus:

• Naive input → treated as UTC; no TypeError.
• Same-year vs different-year branch.
• Year-boundary edge: then = 2025-12-30, now = 2026-01-02 → 16 May 2025-style with year (because years differ).

format_time_html tests

• Returns markupsafe.Markup.
• Contains <time datetime="..." title="...">...</time>.
• datetime= attribute is ISO 8601 with +00:00 offset.
• title= matches YYYY-MM-DD HH:MM:SS UTC.
• Label inside element equals humanize_delta(then, now).

Smoke test (Flask test client)

Render a minimal template {{ ts | timeago }} via the test client and assert:

• Response contains <time (filter is registered).
• No literal <time> (no double-escaping).

Verification

End-to-end checks before declaring done:

1. pytest l4d2web/tests -q — full suite green, including the new test_timeago.py.
2. Manual UI walk in a logged-in session:
   • /admin/users — Created / Updated columns show "N minutes ago" / date form.
   • /blueprints — same.
   • /jobs (and a single job detail) — Created / Started / Finished use the filter; null Finished still shows -.
   • A server with live state — polled N seconds ago, joined N minutes ago, last seen N minutes ago.
3. Hover one of the new <time> elements — browser-native tooltip shows the UTC string.
4. Check page source — no double-escaped tags; <time> element present with both attributes.

Out of scope

• Switching models.py DateTime columns to timezone=True and removing the ~6 replace(tzinfo=None) workarounds. Worth doing, but mechanical and separable. See follow-up below.
• Client-side ticker JS to keep visible labels fresh on long-open tabs. The tooltip carries the precise UTC value; HTMX-polled pages refresh anyway.
• Duration formatting (running for 12 minutes). The helper renders points in time, not intervals.
• Localisation. English month names everywhere, matching the rest of the app's strings.

Follow-up spec (file separately after this lands)

docs/superpowers/specs/YYYY-MM-DD-naive-datetime-cleanup-design.md — switch models.py DateTime columns to DateTime(timezone=True), remove the .replace(tzinfo=None) workarounds in profile_routes.py:88, server_routes.py:210/234/273, page_routes.py:174, live_state_poller.py:37, and confirm auth markers, staleness comparisons, and session helpers still work. Mechanical refactor, no behaviour change visible to users. The timeago helper's defensive tzinfo is None line becomes a no-op afterwards — leave it as a safety net.