---
id: NL-SPEC-9D4A99C2
type: spec
title: Read-only CalDAV calendar
---

# Read-only CalDAV calendar

## Outcome

The clock popup shows the current six-week month grid and today's agenda from one Nextcloud CalDAV account.
It remains useful offline and before setup.

## Data behavior

- Event and task calendars are discovered rather than hardcoded; disabled calendars are excluded.
- Recurring events arrive expanded by the server.
- Task queries are not recurrence-expanded because expansion can drop VTODO data.
- The fetched window covers all 42 visible Monday-first cells.
- Timed values become local display times from UTC instants.
- All-day values remain calendar dates without timezone conversion.
- Folded lines, escaped text, exclusive all-day end dates, timed events, and dated tasks parse defensively.
- Invalid records are skipped without discarding valid records; undated tasks are ignored.

## Presentation

- Timed single-day events render as calendar-colored dots; all-day events render as pills.
- Multi-day events render as non-overlapping bands split at week boundaries.
- Today is emphasized and adjacent-month days are subdued.
- Weekday labels are lowercase `m d m d f s s`, with weekends dimmed.
- Today's agenda lists all-day items and tasks before timed events.
- Open tasks use `○`, completed tasks are subdued, and timed events show local time.
- Empty agenda text is `keine termine`.
- The grid has a fixed six-row height and remains borderless, without gradients, shadows, or animation.

## Setup, refresh, and failure

- Initial setup collects a server URL, username, and app-password.
- Setup explicitly says to use an app-password, not the main password.
- Non-secret configuration and discovered metadata persist across restarts.
- Data refreshes on initial load, when the popup opens, and every 15 minutes.
- Missing configuration or credentials presents lowercase setup affordances.
- Network, authentication, keyring, or parse failure never breaks the clock or grid.
- Failure preserves last-good data and shows a subtle stale marker.
- Keyring failure produces an inline, lowercase, actionable error.

## Security and contracts

- Calendar access permits DAV discovery and reads only.
- The app-password is stored in the system keyring.
- The password is never persisted in calendar configuration, written to disk, placed in process arguments, logged, or returned through IPC.
- Transient password state is cleared after successful storage.
- Additive IPC exposes status, non-secret account identity, counts, and setup booleans, never credentials.

## Acceptance

- Parser and layout checks cover unfolding, escaping, dates, tasks, malformed input, week wrapping, and overlapping lanes.
- Service checks cover discovery, timezone-independent windows, setup drafts, and state serialization.
- A live read discovers calendars and returns events and dated tasks without credential exposure.
- Offline and missing-keyring tests preserve the shell and show the specified state.
- Screenshots verify grid, bands, agenda ordering, stale state, setup guidance, and lowercase labels.

## Out of scope

- Month navigation or day selection.
- Calendar mutation, multiple accounts, client-side recurrence, or cross-restart event caching.
- Undated tasks, subtasks, and calendar alarms.