path: root/docs/superpowers/plans/2026-10-13-calendar.md

# Calendar Panel Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** A calendar panel dropping from the island's clock pill: month grid, day agenda, and an event editor that writes the vdirsyncer calendars.

**Architecture:** `calctl`, a Python CLI over the vdir (icalendar + dateutil), does every read and write and answers in one JSON envelope. `Cal.js` holds the pure date logic the QML needs, tested under node. `Calendar.qml` is a singleton that runs calctl and watches the calendar directories; `CalendarPanel.qml` and `EventEditor.qml` are the UI; the clock pill hosts the panel in its capsule as the status pill hosts the sound and controls panels.

**Tech Stack:** `/usr/bin/python3` 3.12 with `icalendar` 6.1.1 and `python-dateutil` 2.9.0 (system packages, already used by cal-notif); Quickshell 0.3.1 QML; node for JS tests; `inotifywait`.

**Spec:** `docs/superpowers/specs/2026-10-13-calendar-design.md`

---

## Read first

- `AGENTS.md`: "The rule that bites first", "Verifying, and how not to", "Reloading", and the per-component notes. In short: the process is `qs`; never `pkill -f`; never start a detached `qs` from a tool call; read the running shell with `qs log -p ~/Programming/GIT/quickshell/desktop -t 40`; a new directory may need `./reload.sh desktop` from the user's terminal.
- `desktop/island/Island.qml`, `StatusPill.qml`, `ClockPill.qml`, `ControlsPanel.qml`: the panel mechanism this copies.
- `desktop/modules/mail/Accounts.qml`: the `inotifywait` watch + debounce + respawn pattern reused here.
- Never run calctl's write commands against the live calendars (`~/.local/share/calendars/`). Tests use temporary vdirs; the only live-data command an agent runs is the read-only `calctl list` timing check in Task 3.
- Live data facts, measured: two calendars in `~/.config/khal/config` (`light green`, `light magenta`), 281 event files (all parse with icalendar; a month list measured 0.11s), every RRULE outside VTIMEZONE is `FREQ=YEARLY;WKST=TU`, no `RECURRENCE-ID` or `EXDATE`, 97 events with alarms of which 84 are `-PT1H`. Local zone `Europe/Rome` (`/etc/localtime`).

GPLv2 header, used in every new file (`// ` prefix in JS/QML, `# ` in Python, after the shebang):

```
Copyright (C) 2026 Danilo M. <danix@danix.xyz>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
```

The code blocks below write it as `// <GPLv2 header>` or `# <GPLv2 header>`. Compare `desktop/island/Logic.js` (JS with `.pragma library` first) and `desktop/modules/status/statusctl` (script with shebang first).

## Files

| File | Action | Responsibility |
| --- | --- | --- |
| `docs/superpowers/specs/2026-10-13-calendar-design.md` | modify | protocol details settled while planning |
| `desktop/island/calendar/calctl` | create | the vdir: calendars, list, get, new, edit, delete |
| `desktop/island/calendar/test_calctl.py` | create | CLI tests against temporary vdirs |
| `desktop/island/calendar/Cal.js` | create | pure date logic for the QML |
| `desktop/island/calendar/test_cal.js` | create | node test for Cal.js |
| `desktop/island/calendar/Calendar.qml` | create | singleton: runs calctl, watches the vdir |
| `desktop/island/calendar/CalendarPanel.qml` | create | month grid, agenda, hosts the editor |
| `desktop/island/calendar/EventEditor.qml` | create | the form |
| `desktop/island/ClockPill.qml` | modify | click opens the panel; hosts it |
| `desktop/island/Island.qml` | modify | `"calendar"` panel, focus, close |
| `desktop/island/README.md`, `AGENTS.md` | modify | docs |

---

### Task 1: Spec corrections

Planning settled four protocol details the spec left open or got differently. Edit `docs/superpowers/specs/2026-10-13-calendar-design.md`:

- [ ] **Step 1: Commands block.** Replace the block under "Commands:" with:

```
    calctl calendars                 {default, calendars: [{name, color, path}]}
    calctl list <from> <to>          occurrences in [from, to), local time
    calctl get <uid>                 the series itself, for the editor
    calctl new <event-json>          {uid}
    calctl edit <uid> <event-json>   {uid}
    calctl delete <uid>              {}
```

- [ ] **Step 2: The envelope.** Replace the line `Errors go to stderr with exit 1; stdout is JSON only on success.` with:

```
Every command prints one JSON object on stdout: `{"ok": true, "data": ...}`
or `{"ok": false, "error": "..."}` with exit 1, the error also on stderr.
The shell reads stdout only, so it never has to order an exit code against
a stream. The event JSON is an argument rather than stdin, which keeps the
QML side to a plain `Process` command. `get` exists because the editor edits
the series: an occurrence's start is not the series' DTSTART.

Event JSON, in and out: `calendar`, `title`, `allDay`, `start`, `end`
(`YYYY-MM-DDTHH:MM` local, or `YYYY-MM-DD` all day with an inclusive last
day), `repeat`, `until` (`YYYY-MM-DD` or ""), `alarm`, `location`, `notes`;
out also `uid`, `color` and `override`.

Recurrence is expanded in naive local time, which keeps the wall-clock time
of a TZID event across DST, as RFC 5545 asks. ponytail: a `Z` UNTIL is read
as local time, so an until-date can be off by the UTC offset at its very
end.
```

- [ ] **Step 3: Files.** In "Where it lives", add the line `      Cal.js              pure date logic for the QML, node-tested` after `test_calctl.py`, and `      test_cal.js         node test for Cal.js` after it.

- [ ] **Step 4: Commit**

```bash
git add docs/superpowers/specs/2026-10-13-calendar-design.md
git commit -m "docs(spec): calendar protocol settled while planning

One JSON envelope on stdout for every calctl command, the event as an
argument rather than stdin, a get command because the editor edits the
series rather than the occurrence clicked, and a pure Cal.js for the
date logic so it is tested under node like the island's other helpers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 2: calctl reading (calendars, list, get)

**Files:**
- Create: `desktop/island/calendar/calctl` (executable)
- Create: `desktop/island/calendar/test_calctl.py`

- [ ] **Step 1: Write the reading half of the test**

`desktop/island/calendar/test_calctl.py`:

```python
#!/usr/bin/python3
# <GPLv2 header>
"""Run: /usr/bin/python3 desktop/island/calendar/test_calctl.py

Drives calctl as a CLI against temporary vdirs and a temporary khal config,
never the live calendars. Plain asserts, no framework.
"""

import json
import os
import shutil
import subprocess
import tempfile
from pathlib import Path

CALCTL = Path(__file__).resolve().parent / "calctl"

tmp = Path(tempfile.mkdtemp(prefix="calctl-test-"))
(tmp / "a").mkdir()
(tmp / "b").mkdir()
(tmp / "khal").write_text(f"""[calendars]

[[home]]
path = {tmp}/a
type = calendar
color = light green

[[birthdays]]
path = {tmp}/b
color = '#ff8800'

[locale]
firstweekday = 0

[default]
default_calendar = home
""")
ENV = dict(os.environ,
           CALCTL_KHAL_CONFIG=str(tmp / "khal"),
           CALCTL_OVERRIDES=str(tmp / "overrides.toml"),
           CALCTL_NOSYNC="1",
           TZ="Europe/Rome")


def run(*args, ok=True):
    p = subprocess.run([str(CALCTL), *args], env=ENV, capture_output=True, text=True)
    r = json.loads(p.stdout)
    assert r["ok"] is ok, (args, p.stdout, p.stderr)
    assert (p.returncode == 0) is ok, (args, p.returncode)
    return r["data"] if ok else r["error"]


def put(path, body):
    """A hand-written .ics, CRLF like a real one."""
    Path(path).write_text(body.strip().replace("\n", "\r\n") + "\r\n")


# calendars: khal colour names mapped to Theme names, a hex passed through.
c = run("calendars")
assert c["default"] == "home"
assert [(x["name"], x["color"]) for x in c["calendars"]] == [("home", "green"), ("birthdays", "#ff8800")]
assert c["calendars"][0]["path"] == str(tmp / "a")

# A yearly all-day event from long ago is expanded into the asked window.
put(tmp / "b" / "bday.ics", """
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//test//EN
BEGIN:VEVENT
UID:bday-1
DTSTAMP:20200101T000000Z
DTSTART;VALUE=DATE:19900417
DTEND;VALUE=DATE:19900418
RRULE:FREQ=YEARLY;WKST=TU
SUMMARY:Birthday
END:VEVENT
END:VCALENDAR
""")
apr = [e for e in run("list", "2026-04-01", "2026-05-01") if e["uid"] == "bday-1"]
assert len(apr) == 1, apr
assert apr[0]["start"] == "2026-04-17" and apr[0]["end"] == "2026-04-17", apr
assert apr[0]["allDay"] is True and apr[0]["repeat"] == "yearly" and apr[0]["color"] == "#ff8800"

# A rich rule and two alarms read as custom; the weekly rule is expanded in
# local time, so 09:00 stays 09:00 across the DST change on 25 October.
put(tmp / "a" / "weird.ics", """
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//test//EN
BEGIN:VEVENT
UID:weird-1
DTSTAMP:20260101T000000Z
DTSTART;TZID=Europe/Rome:20261005T090000
DTEND;TZID=Europe/Rome:20261005T100000
RRULE:FREQ=WEEKLY;BYDAY=MO,WE
SUMMARY:Standup
X-FOO:bar
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:a
TRIGGER:-PT1H
END:VALARM
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:b
TRIGGER:-PT5M
END:VALARM
END:VEVENT
END:VCALENDAR
""")
w = run("get", "weird-1")
assert w["repeat"] == "custom" and w["alarm"] == "custom" and w["title"] == "Standup", w
assert w["start"] == "2026-10-05T09:00", w
occ = [e["start"] for e in run("list", "2026-10-01", "2026-11-01") if e["uid"] == "weird-1"]
assert len(occ) == 8 and occ[0] == "2026-10-05T09:00" and "2026-10-26T09:00" in occ, occ

# A broken file is skipped, not fatal.
(tmp / "a" / "broken.ics").write_text("this is not a calendar\n")
assert run("list", "2026-10-01", "2026-11-01")

# Unknown uid and bad usage: the error envelope, exit 1.
assert "no event" in run("get", "nope", ok=False)
assert "usage" in run("frobnicate", ok=False)

# --- writes (Task 3) go here ---

shutil.rmtree(tmp)
print("test_calctl: ok")
```

- [ ] **Step 2: Run it to see it fail**

Run: `/usr/bin/python3 desktop/island/calendar/test_calctl.py`
Expected: FAIL, `FileNotFoundError` or `PermissionError` for `calctl`.

- [ ] **Step 3: Write calctl's reading half**

`desktop/island/calendar/calctl`:

```python
#!/usr/bin/python3
#
# <GPLv2 header>
#
# The island calendar's backend: the vdirsyncer calendars as JSON. Reads the
# calendar list from khal's config so there is no second list to keep in
# step; khal and cal-notif read the same files and are not affected.
#
#   calctl calendars                 {default, calendars: [{name, color, path}]}
#   calctl list FROM TO              occurrences in [FROM, TO), local time
#   calctl get UID                   the series itself, for the editor
#   calctl new EVENT-JSON            {uid}
#   calctl edit UID EVENT-JSON       {uid}
#   calctl delete UID                {}
#
# Every command prints one object: {"ok": true, "data": ...} or
# {"ok": false, "error": "..."} with exit 1. Environment, for the tests:
# CALCTL_KHAL_CONFIG, CALCTL_OVERRIDES, CALCTL_NOSYNC.

import json
import os
import subprocess
import sys
import tempfile
import tomllib
import uuid
from datetime import date, datetime, time, timedelta, timezone
from pathlib import Path
from zoneinfo import ZoneInfo

import icalendar
from dateutil.rrule import rrulestr

HOME = Path.home()
KHAL_CONFIG = Path(os.environ.get("CALCTL_KHAL_CONFIG", HOME / ".config/khal/config"))
OVERRIDES = Path(os.environ.get("CALCTL_OVERRIDES", HOME / ".config/cal-notif/overrides.toml"))
SYNC_LOG = HOME / ".local/share/vdirsyncer/sync.log"

PRESET_REPEAT = {"daily": "DAILY", "weekly": "WEEKLY", "monthly": "MONTHLY", "yearly": "YEARLY"}
PRESET_ALARM = {"10m": timedelta(minutes=10), "1h": timedelta(hours=1), "1d": timedelta(days=1)}

# khal's colour names as Theme property names; a #rrggbb colour passes
# through and anything else is the accent.
COLORS = {
    "black": "crust", "white": "text", "gray": "subtext", "light gray": "subtext",
    "dark gray": "overlay", "brown": "peach",
    "red": "red", "dark red": "red", "light red": "red",
    "green": "green", "dark green": "green", "light green": "green",
    "yellow": "yellow", "light yellow": "yellow",
    "blue": "blue", "dark blue": "blue", "light blue": "blue",
    "magenta": "mauve", "dark magenta": "mauve", "light magenta": "mauve",
    "cyan": "teal", "dark cyan": "teal", "light cyan": "teal",
}

USAGE = "usage: calctl calendars | list FROM TO | get UID | new JSON | edit UID JSON | delete UID"


class Fail(Exception):
    pass


def local_zone():
    tz = os.environ.get("TZ", "").lstrip(":")
    if tz:
        try:
            return ZoneInfo(tz)
        except Exception:
            pass
    real = os.path.realpath("/etc/localtime")
    if "zoneinfo/" in real:
        return ZoneInfo(real.split("zoneinfo/", 1)[1])
    return ZoneInfo("UTC")


LOCAL = local_zone()


def calendars():
    """([{name, path, color}], default name) from khal's [calendars].

    ponytail: khal's `type = discover` globs are not expanded; every
    calendar here is a plain path.
    """
    try:
        lines = KHAL_CONFIG.read_text().splitlines()
    except OSError as e:
        raise Fail(f"cannot read {KHAL_CONFIG}: {e.strerror}")
    cals, section, cur, default = [], None, None, None
    for raw in lines:
        line = raw.strip()
        # Only whole-line comments: a colour value can start with '#'.
        if not line or line.startswith("#"):
            continue
        if line.startswith("[["):
            cur = None
            if section == "calendars":
                cur = {"name": line.strip("[]").strip(), "path": None, "color": "accent"}
                cals.append(cur)
            continue
        if line.startswith("["):
            section, cur = line.strip("[]").strip(), None
            continue
        if "=" not in line:
            continue
        key, value = (s.strip() for s in line.split("=", 1))
        value = value.strip("'\"")
        if cur is not None and key == "path":
            cur["path"] = Path(os.path.expanduser(value))
        elif cur is not None and key == "color":
            cur["color"] = COLORS.get(value, value if value.startswith("#") else "accent")
        elif section == "default" and key == "default_calendar":
            default = value
    cals = [c for c in cals if c["path"]]
    if not cals:
        raise Fail(f"no calendars in {KHAL_CONFIG}")
    names = [c["name"] for c in cals]
    return cals, default if default in names else names[0]


def master(ics):
    """The series' VEVENT: the first one that is not an occurrence override."""
    for ev in ics.walk("VEVENT"):
        if "RECURRENCE-ID" not in ev:
            return ev
    return None


def events():
    """(calendar, path, VEVENT) for every event file. A file that fails to
    parse is skipped: one bad file must not blank the month."""
    cals, _ = calendars()
    for cal in cals:
        for path in sorted(cal["path"].glob("*.ics")):
            try:
                ev = master(icalendar.Calendar.from_ical(path.read_bytes()))
            except Exception:
                continue
            # ponytail: occurrence overrides (RECURRENCE-ID) and EXDATE are not
            # applied; none exist in the live calendars (spec, Scope).
            if ev is not None:
                yield cal, path, ev


def find(uid):
    for cal, path, ev in events():
        if str(ev.get("UID", "")) == uid:
            return cal, path
    raise Fail(f"no event {uid}")


def as_local(value):
    """A date-time as naive local time; a date stays a date. A floating
    time (no zone) is local by definition."""
    if isinstance(value, datetime) and value.tzinfo is not None:
        return value.astimezone(LOCAL).replace(tzinfo=None)
    return value


def span(ev):
    """(start, end, all_day): naive local datetimes, or dates with an
    exclusive end for an all-day event."""
    start = as_local(ev["DTSTART"].dt)
    all_day = not isinstance(start, datetime)
    if "DTEND" in ev:
        end = as_local(ev["DTEND"].dt)
    elif "DURATION" in ev:
        end = start + ev["DURATION"].dt
    else:
        end = start + timedelta(days=1) if all_day else start
    return start, end, all_day


def repeat_of(ev):
    """(repeat, until) as the form shows them."""
    rule = ev.get("RRULE")
    if rule is None:
        return "none", ""
    names = {v: k for k, v in PRESET_REPEAT.items()}
    freq = rule.get("FREQ", [""])[0]
    # WKST changes nothing for a plain FREQ; the live birthdays all carry it.
    if set(rule) - {"WKST"} <= {"FREQ", "UNTIL"} and freq in names:
        until = ""
        if "UNTIL" in rule:
            u = as_local(rule["UNTIL"][0])
            until = (u.date() if isinstance(u, datetime) else u).isoformat()
        return names[freq], until
    return "custom", ""


def alarm_of(ev):
    alarms = [c for c in ev.subcomponents if c.name == "VALARM"]
    if not alarms:
        return "none"
    if len(alarms) == 1:
        trig = alarms[0].get("TRIGGER")
        if (trig is not None and isinstance(trig.dt, timedelta)
                and trig.params.get("RELATED", "START") == "START"):
            for name, before in PRESET_ALARM.items():
                if trig.dt == -before:
                    return name
    return "custom"


def overrides():
    """UIDs with a per-event alarm in cal-notif, which wins over the VALARM."""
    try:
        return set(tomllib.loads(OVERRIDES.read_text()))
    except (OSError, tomllib.TOMLDecodeError):
        return set()


def stamp(value):
    if isinstance(value, datetime):
        return value.isoformat(timespec="minutes")
    return value.isoformat()


def to_json(cal, ev, start, end, all_day, ov):
    repeat, until = repeat_of(ev)
    uid = str(ev.get("UID", ""))
    return {
        "uid": uid,
        "calendar": cal["name"],
        "color": cal["color"],
        "title": str(ev.get("SUMMARY", "")),
        "allDay": all_day,
        "start": stamp(start),
        # All-day ends go out inclusive: the last day the event covers.
        "end": stamp(max(start, end - timedelta(days=1))) if all_day else stamp(end),
        "location": str(ev.get("LOCATION", "")),
        "notes": str(ev.get("DESCRIPTION", "")),
        "repeat": repeat,
        "until": until,
        "alarm": alarm_of(ev),
        "override": uid in ov,
    }


def cmd_list(lo_s, hi_s):
    lo, hi = datetime.fromisoformat(lo_s), datetime.fromisoformat(hi_s)
    ov, out = overrides(), []
    for cal, _, ev in events():
        try:
            start, end, all_day = span(ev)
            s = datetime.combine(start, time()) if all_day else start
            e = datetime.combine(end, time()) if all_day else end
            dur = e - s
            if "RRULE" in ev:
                # Naive local time keeps the wall-clock time across DST.
                rule = rrulestr(ev["RRULE"].to_ical().decode(), dtstart=s, ignoretz=True)
                starts = rule.between(lo - dur, hi, inc=True)
            else:
                starts = [s]
        except Exception:
            continue
        for o in starts:
            if not (o < hi and (o + dur > lo or (not dur and o >= lo))):
                continue
            if all_day:
                out.append(to_json(cal, ev, o.date(), (o + dur).date(), True, ov))
            else:
                out.append(to_json(cal, ev, o, o + dur, False, ov))
    out.sort(key=lambda x: (x["start"][:10], not x["allDay"], x["start"]))
    return out


def cmd_get(uid):
    cal, path = find(uid)
    ev = master(icalendar.Calendar.from_ical(path.read_bytes()))
    start, end, all_day = span(ev)
    return to_json(cal, ev, start, end, all_day, overrides())


def main(argv):
    cmd, args = (argv[1], argv[2:]) if len(argv) > 1 else ("", [])
    try:
        if cmd == "calendars" and not args:
            cals, default = calendars()
            data = {"default": default,
                    "calendars": [{"name": c["name"], "color": c["color"], "path": str(c["path"])}
                                  for c in cals]}
        elif cmd == "list" and len(args) == 2:
            data = cmd_list(*args)
        elif cmd == "get" and len(args) == 1:
            data = cmd_get(*args)
        else:
            raise Fail(USAGE)
    except Exception as e:
        msg = str(e) if isinstance(e, Fail) else f"{type(e).__name__}: {e}"
        print(json.dumps({"ok": False, "error": msg}))
        print(f"calctl: {msg}", file=sys.stderr)
        return 1
    print(json.dumps({"ok": True, "data": data}, ensure_ascii=False))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))
```

`new`, `edit` and `delete` are added in Task 3; until then they print the usage error. The imports they need (`subprocess`, `tempfile`, `uuid`, `date`, `timezone`) are already here.

Then: `chmod +x desktop/island/calendar/calctl`.

- [ ] **Step 4: Run the test**

Run: `/usr/bin/python3 desktop/island/calendar/test_calctl.py`
Expected: `test_calctl: ok`

- [ ] **Step 5: Commit**

```bash
git add desktop/island/calendar/calctl desktop/island/calendar/test_calctl.py
git commit -m "feat(calendar): calctl reads the vdir as JSON

The calendar list comes from khal's config, so there is no second list.
Recurrence is expanded with dateutil in naive local time, which keeps a
weekly 09:00 at 09:00 across the DST change; the test pins that on 26
October. A rule richer than a plain FREQ, or alarms other than one
preset, read as custom, which is what lets an edit leave them alone.
A file that fails to parse is skipped rather than blanking the month.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 3: calctl writing (new, edit, delete)

**Files:**
- Modify: `desktop/island/calendar/calctl`
- Modify: `desktop/island/calendar/test_calctl.py`

- [ ] **Step 1: Write the writing half of the test**

In `test_calctl.py`, replace the line `# --- writes (Task 3) go here ---` with:

```python
def ev(**kw):
    e = {"calendar": "home", "title": "Dentist", "allDay": False,
         "start": "2026-10-15T14:30", "end": "2026-10-15T15:30",
         "repeat": "none", "until": "", "alarm": "1h", "location": "", "notes": ""}
    e.update(kw)
    return json.dumps(e)


def no_temp():
    assert not list(tmp.rglob(".calctl-*")), "temp file left behind"


# new, timed: the local zone with its VTIMEZONE, the alarm; read back in
# local time.
uid = run("new", ev())["uid"]
f = tmp / "a" / f"{uid}.ics"
t = f.read_text()
assert "DTSTART;TZID=Europe/Rome:20261015T143000" in t, t
assert "BEGIN:VTIMEZONE" in t and "TRIGGER:-PT1H" in t, t
no_temp()
mine = [e for e in run("list", "2026-10-01", "2026-11-01") if e["uid"] == uid]
assert len(mine) == 1, mine
assert mine[0]["start"] == "2026-10-15T14:30" and mine[0]["end"] == "2026-10-15T15:30"
assert mine[0]["alarm"] == "1h" and mine[0]["repeat"] == "none" and mine[0]["color"] == "green"
assert mine[0]["override"] is False
assert run("get", uid)["title"] == "Dentist"

# all-day, multi-day: exclusive DTEND on disk, inclusive end in JSON.
trip = run("new", ev(title="Trip", allDay=True, start="2026-10-30", end="2026-11-02", alarm="none"))["uid"]
t = (tmp / "a" / f"{trip}.ics").read_text()
assert "DTSTART;VALUE=DATE:20261030" in t and "DTEND;VALUE=DATE:20261103" in t, t
assert "VALARM" not in t
nov = [e for e in run("list", "2026-11-01", "2026-12-01") if e["uid"] == trip]
assert len(nov) == 1 and nov[0]["start"] == "2026-10-30" and nov[0]["end"] == "2026-11-02", nov
assert not [e for e in run("list", "2026-10-01", "2026-10-30") if e["uid"] == trip]

# weekly with an until-date, across the DST change.
gym = run("new", ev(title="Gym", repeat="weekly", until="2026-10-29"))["uid"]
occ = [e["start"] for e in run("list", "2026-10-01", "2026-12-01") if e["uid"] == gym]
assert occ == ["2026-10-15T14:30", "2026-10-22T14:30", "2026-10-29T14:30"], occ
assert run("get", gym)["until"] == "2026-10-29"

# edit keeping custom: the rich rule, both alarms and an unknown property
# survive; SEQUENCE goes up.
run("edit", "weird-1", ev(title="Standup v2", start="2026-10-05T09:30",
                         end="2026-10-05T10:00", repeat="custom", alarm="custom"))
t = (tmp / "a" / "weird.ics").read_text()
assert "BYDAY=MO,WE" in t and t.count("BEGIN:VALARM") == 2 and "X-FOO:bar" in t, t
assert "SUMMARY:Standup v2" in t and "SEQUENCE:1" in t, t
no_temp()

# edit to presets: the rule goes, the alarms become one.
run("edit", "weird-1", ev(title="Standup v2", start="2026-10-05T09:30",
                         end="2026-10-05T10:00", repeat="none", alarm="10m"))
t = (tmp / "a" / "weird.ics").read_text()
assert "RRULE" not in t and t.count("BEGIN:VALARM") == 1 and "TRIGGER:-PT10M" in t, t

# a calendar change moves the file.
run("edit", uid, ev(calendar="birthdays"))
assert not f.exists() and (tmp / "b" / f.name).exists()
assert run("get", uid)["calendar"] == "birthdays"

# cal-notif's per-event override is reported.
(tmp / "overrides.toml").write_text(f'"{uid}" = ["10m"]\n')
assert run("get", uid)["override"] is True

# delete.
assert run("delete", uid) == {}
assert not (tmp / "b" / f.name).exists()
assert "no event" in run("get", uid, ok=False)

# validation: the error envelope, exit 1, nothing written.
before = sorted(p.name for p in tmp.rglob("*.ics"))
assert "title" in run("new", ev(title="  "), ok=False)
assert "end" in run("new", ev(end="2026-10-15T14:00"), ok=False)
assert "calendar" in run("new", ev(calendar="nope"), ok=False)
assert "json" in run("new", "{not json", ok=False)
assert sorted(p.name for p in tmp.rglob("*.ics")) == before
no_temp()
```

- [ ] **Step 2: Run it to see it fail**

Run: `/usr/bin/python3 desktop/island/calendar/test_calctl.py`
Expected: FAIL on the first `run("new", ...)` with the usage error in the assertion message.

- [ ] **Step 3: Add the writing half to calctl**

Insert before `def main(argv):`:

```python
def parse_payload(text, cals):
    """The form's JSON, checked. Dates become date/datetime; an all-day end
    becomes exclusive."""
    try:
        p = json.loads(text)
    except json.JSONDecodeError as e:
        raise Fail(f"bad event json: {e}")
    if not isinstance(p, dict):
        raise Fail("bad event json: not an object")
    by_name = {c["name"]: c for c in cals}
    if p.get("calendar") not in by_name:
        raise Fail(f"unknown calendar {p.get('calendar')!r}")
    title = str(p.get("title", "")).strip()
    if not title:
        raise Fail("title is empty")
    all_day = bool(p.get("allDay"))
    try:
        if all_day:
            start = date.fromisoformat(p["start"])
            end = date.fromisoformat(p["end"]) + timedelta(days=1)
        else:
            start = datetime.fromisoformat(p["start"])
            end = datetime.fromisoformat(p["end"])
        until = date.fromisoformat(p["until"]) if p.get("until") else None
    except (KeyError, TypeError, ValueError) as e:
        raise Fail(f"bad date: {e}")
    if end < start:
        raise Fail("end is before start")
    repeat = p.get("repeat", "none")
    if repeat not in PRESET_REPEAT and repeat not in ("none", "custom"):
        raise Fail(f"unknown repeat {repeat!r}")
    alarm = p.get("alarm", "none")
    if alarm not in PRESET_ALARM and alarm not in ("none", "custom"):
        raise Fail(f"unknown alarm {alarm!r}")
    return {"cal": by_name[p["calendar"]], "title": title, "allDay": all_day,
            "start": start, "end": end, "until": until, "repeat": repeat, "alarm": alarm,
            "location": str(p.get("location", "")).strip(), "notes": str(p.get("notes", ""))}


def apply(ev, p):
    """Write the form's fields into a VEVENT. Everything else on it is left
    alone; a `custom` repeat or alarm keeps what is there."""
    for key in ("DTSTART", "DTEND", "DURATION", "SUMMARY", "LOCATION", "DESCRIPTION",
                "DTSTAMP", "LAST-MODIFIED"):
        ev.pop(key, None)
    if p["allDay"]:
        ev.add("DTSTART", p["start"])
        ev.add("DTEND", p["end"])
    else:
        ev.add("DTSTART", p["start"].replace(tzinfo=LOCAL))
        ev.add("DTEND", p["end"].replace(tzinfo=LOCAL))
    ev.add("SUMMARY", p["title"])
    if p["location"]:
        ev.add("LOCATION", p["location"])
    if p["notes"]:
        ev.add("DESCRIPTION", p["notes"])
    if p["repeat"] != "custom":
        ev.pop("RRULE", None)
        if p["repeat"] != "none":
            rule = {"FREQ": PRESET_REPEAT[p["repeat"]]}
            if p["until"]:
                # RFC 5545: UNTIL is a DATE for a DATE start, UTC otherwise.
                rule["UNTIL"] = (p["until"] if p["allDay"] else
                                 datetime.combine(p["until"], time(23, 59, 59), LOCAL)
                                 .astimezone(timezone.utc))
            ev.add("RRULE", rule)
    if p["alarm"] != "custom":
        ev.subcomponents = [c for c in ev.subcomponents if c.name != "VALARM"]
        if p["alarm"] != "none":
            alarm = icalendar.Alarm()
            alarm.add("ACTION", "DISPLAY")
            alarm.add("DESCRIPTION", p["title"])
            alarm.add("TRIGGER", -PRESET_ALARM[p["alarm"]])
            ev.add_component(alarm)
    now = datetime.now(timezone.utc).replace(microsecond=0)
    ev.add("DTSTAMP", now)
    ev.add("LAST-MODIFIED", now)


def write(path, ics):
    """Temporary file in the same directory, then rename: a reader (khal,
    cal-notif, vdirsyncer, the panel's watch) never sees half a file. The
    temporary name does not end in .ics, so nothing lists it."""
    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".calctl-", suffix=".tmp")
    try:
        with os.fdopen(fd, "wb") as f:
            f.write(ics.to_ical())
        os.replace(tmp, path)
    except BaseException:
        if os.path.exists(tmp):
            os.unlink(tmp)
        raise


def sync():
    """Push the change now rather than at the next cron run. Detached and
    not waited for; a failure only means the cron run carries it."""
    if os.environ.get("CALCTL_NOSYNC"):
        return
    try:
        SYNC_LOG.parent.mkdir(parents=True, exist_ok=True)
        with open(SYNC_LOG, "ab") as log:
            subprocess.Popen(["vdirsyncer", "-v", "ERROR", "sync"], stdin=subprocess.DEVNULL,
                             stdout=log, stderr=subprocess.STDOUT, start_new_session=True)
    except OSError:
        pass


def cmd_new(text):
    cals, _ = calendars()
    p = parse_payload(text, cals)
    uid = str(uuid.uuid4())
    ics = icalendar.Calendar()
    ics.add("PRODID", "-//quickshell//calctl//EN")
    ics.add("VERSION", "2.0")
    ev = icalendar.Event()
    ev.add("UID", uid)
    apply(ev, p)
    ics.add_component(ev)
    ics.add_missing_timezones()
    write(p["cal"]["path"] / f"{uid}.ics", ics)
    sync()
    return {"uid": uid}


def cmd_edit(uid, text):
    cals, _ = calendars()
    p = parse_payload(text, cals)
    _, path = find(uid)
    ics = icalendar.Calendar.from_ical(path.read_bytes())
    ev = master(ics)
    apply(ev, p)
    sequence = int(ev.pop("SEQUENCE", 0))
    ev.add("SEQUENCE", sequence + 1)
    ics.add_missing_timezones()
    target = p["cal"]["path"] / path.name
    if target != path and target.exists():
        raise Fail(f"{target.name} already exists in {p['cal']['name']}")
    write(target, ics)
    if target != path:
        path.unlink()
    sync()
    return {"uid": uid}


def cmd_delete(uid):
    _, path = find(uid)
    path.unlink()
    sync()
    return {}
```

In `main`, before the final `else:` of the command chain, add:

```python
        elif cmd == "new" and len(args) == 1:
            data = cmd_new(*args)
        elif cmd == "edit" and len(args) == 2:
            data = cmd_edit(*args)
        elif cmd == "delete" and len(args) == 1:
            data = cmd_delete(*args)
```

- [ ] **Step 4: Run the test**

Run: `/usr/bin/python3 desktop/island/calendar/test_calctl.py`
Expected: `test_calctl: ok`

- [ ] **Step 5: Time a read-only list on the live calendars**

Read-only; writes nothing.

Run: `time desktop/island/calendar/calctl list 2026-09-28 2026-11-09 | head -c 300`
Expected: `{"ok": true, "data": [...` and `real` under 1.5s. Record the time for Task 10. If it is over 1.5s, report it (DONE_WITH_CONCERNS); do not optimise here.

- [ ] **Step 6: Commit**

```bash
git add desktop/island/calendar/calctl desktop/island/calendar/test_calctl.py
git commit -m "feat(calendar): calctl creates, edits and deletes events

Edits change only what the form owns: a custom rule, extra alarms and
properties this tool does not know survive, which the test checks on an
event with BYDAY, two alarms and an X- property. Writes go through a
temporary file and a rename so khal, cal-notif and vdirsyncer never read
half a file, and a vdirsyncer sync is started detached afterwards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 4: Cal.js

**Files:**
- Create: `desktop/island/calendar/Cal.js`
- Create: `desktop/island/calendar/test_cal.js`

- [ ] **Step 1: Write the failing test**

`desktop/island/calendar/test_cal.js`:

```js
// <GPLv2 header>

// Run: node desktop/island/calendar/test_cal.js
// Cal.js is a QML library, so its .pragma line is stripped first.

const fs = require("fs");
const assert = require("assert");

const src = fs.readFileSync(__dirname + "/Cal.js", "utf8").replace(/^\.pragma library$/m, "");
const C = new Function(src + "\nreturn { pad, addDays, today, daysBetween, monthCells, shiftMonth," +
    " lastDay, onDay, dayEvents, dots, timeLabel, validTime, stepTime, newDraft, fromEvent, pick," +
    " toPayload };")();

// Dates are plain YYYY-MM-DD strings, arithmetic in UTC so DST never moves a day.
assert.strictEqual(C.addDays("2026-10-31", 1), "2026-11-01");
assert.strictEqual(C.addDays("2026-03-01", -1), "2026-02-28");
assert.strictEqual(C.addDays("2026-10-24", 2), "2026-10-26");
assert.strictEqual(C.daysBetween("2026-10-30", "2026-11-02"), 3);
assert.strictEqual(C.today(new Date(2026, 9, 13, 23, 59)), "2026-10-13");

// Month cells: six weeks from Monday. October 2026 starts on a Thursday.
const oct = C.monthCells(2026, 9);
assert.strictEqual(oct.length, 42);
assert.strictEqual(oct[0].iso, "2026-09-28");
assert.strictEqual(oct[0].inMonth, false);
assert.strictEqual(oct[3].iso, "2026-10-01");
assert.strictEqual(oct[3].inMonth, true);
assert.strictEqual(oct[3].day, 1);
assert.strictEqual(oct[41].iso, "2026-11-08");
// June 2026 starts on a Monday: no leading days.
assert.strictEqual(C.monthCells(2026, 5)[0].iso, "2026-06-01");

assert.deepStrictEqual(C.shiftMonth(2026, 11, 1), { y: 2027, m0: 0 });
assert.deepStrictEqual(C.shiftMonth(2026, 0, -1), { y: 2025, m0: 11 });

// Which days an event covers.
const timed = { uid: "t", calendar: "home", allDay: false, start: "2026-10-15T14:30", end: "2026-10-15T15:30" };
const night = { uid: "n", calendar: "home", allDay: false, start: "2026-10-15T22:00", end: "2026-10-16T00:00" };
const late = { uid: "l", calendar: "home", allDay: false, start: "2026-10-15T23:00", end: "2026-10-16T01:00" };
const trip = { uid: "a", calendar: "trips", allDay: true, start: "2026-10-14", end: "2026-10-16" };
assert.strictEqual(C.lastDay(timed), "2026-10-15");
assert.strictEqual(C.lastDay(night), "2026-10-15");   // ends at midnight: not on the 16th
assert.strictEqual(C.lastDay(late), "2026-10-16");
assert.strictEqual(C.lastDay(trip), "2026-10-16");
assert.ok(C.onDay(trip, "2026-10-15") && !C.onDay(trip, "2026-10-17"));

// The day's agenda: all-day first, then by start.
const evs = [timed, late, trip, night];
assert.deepStrictEqual(C.dayEvents(evs, "2026-10-15").map(e => e.uid), ["a", "t", "n", "l"]);
assert.deepStrictEqual(C.dayEvents(evs, "2026-10-16").map(e => e.uid), ["a", "l"]);

// Dots: one per calendar with something that day, in calendar order.
const cals = [{ name: "home", color: "green" }, { name: "trips", color: "#ff8800" }];
assert.deepStrictEqual(C.dots(evs, "2026-10-15", cals).map(c => c.name), ["home", "trips"]);
assert.deepStrictEqual(C.dots(evs, "2026-10-14", cals).map(c => c.name), ["trips"]);
assert.deepStrictEqual(C.dots(evs, "2026-10-20", cals), []);

assert.strictEqual(C.timeLabel(trip, "2026-10-15"), "all day");
assert.strictEqual(C.timeLabel(timed, "2026-10-15"), "14:30–15:30");
assert.strictEqual(C.timeLabel(late, "2026-10-15"), "23:00–…");
assert.strictEqual(C.timeLabel(late, "2026-10-16"), "…–01:00");

// Times.
assert.ok(C.validTime("09:05") && C.validTime("23:59"));
assert.ok(!C.validTime("24:00") && !C.validTime("9:05") && !C.validTime("ab:cd"));
assert.strictEqual(C.stepTime("14:30", 15), "14:45");
assert.strictEqual(C.stepTime("23:50", 15), "00:05");
assert.strictEqual(C.stepTime("00:05", -15), "23:50");
assert.strictEqual(C.stepTime("bad", 15), "bad");

// A new event: the next whole hour, one hour long, alarm 1h.
const d = C.newDraft("2026-10-20", new Date(2026, 9, 13, 9, 20), "home");
assert.strictEqual(d.startTime, "10:00");
assert.strictEqual(d.endTime, "11:00");
assert.strictEqual(d.startDay, "2026-10-20");
assert.strictEqual(d.alarm, "1h");
assert.strictEqual(d.calendar, "home");
assert.strictEqual(C.newDraft("2026-10-20", new Date(2026, 9, 13, 23, 10), "home").startTime, "22:00");

// From calctl's JSON.
const fe = C.fromEvent({ uid: "u", calendar: "home", title: "Trip", allDay: true, start: "2026-10-14",
    end: "2026-10-16", repeat: "none", until: "", alarm: "none", location: "", notes: "", override: false });
assert.strictEqual(fe.startDay, "2026-10-14");
assert.strictEqual(fe.endDay, "2026-10-16");
assert.strictEqual(fe.allDay, true);
assert.strictEqual(C.fromEvent(Object.assign({}, timed, { title: "x" })).startTime, "14:30");

// Picking on the grid: a click moves the event and keeps its length in days;
// shift-click sets the end, or the start when before it.
const p1 = C.pick(fe, "2026-10-20", false);
assert.strictEqual(p1.startDay, "2026-10-20");
assert.strictEqual(p1.endDay, "2026-10-22");
assert.strictEqual(fe.startDay, "2026-10-14");          // input untouched
const p2 = C.pick(fe, "2026-10-18", true);
assert.strictEqual(p2.startDay, "2026-10-14");
assert.strictEqual(p2.endDay, "2026-10-18");
const p3 = C.pick(fe, "2026-10-10", true);
assert.strictEqual(p3.startDay, "2026-10-10");
assert.strictEqual(p3.endDay, "2026-10-16");

// To calctl's JSON.
assert.strictEqual(C.toPayload(Object.assign({}, d, { title: " " })).error, "Title is empty");
assert.strictEqual(C.toPayload(Object.assign({}, d, { title: "x", startTime: "9:00" })).error, "Times are HH:MM");
assert.strictEqual(C.toPayload(Object.assign({}, d, { title: "x", endTime: "09:00" })).error, "End is before start");
assert.strictEqual(C.toPayload(Object.assign({}, d, { title: "x", repeat: "weekly", until: "2026-10-01" })).error,
    "Until is before the start");
const ok = C.toPayload(Object.assign({}, d, { title: " Gym ", repeat: "weekly", until: "2026-12-01" })).payload;
assert.deepStrictEqual(ok, { calendar: "home", title: "Gym", allDay: false, start: "2026-10-20T10:00",
    end: "2026-10-20T11:00", repeat: "weekly", until: "2026-12-01", alarm: "1h", location: "", notes: "" });
const ad = C.toPayload(Object.assign({}, fe, { repeat: "none", until: "2026-12-01" })).payload;
assert.strictEqual(ad.start, "2026-10-14");
assert.strictEqual(ad.end, "2026-10-16");
assert.strictEqual(ad.until, "");                        // no repeat, no until

console.log("test_cal: ok");
```

- [ ] **Step 2: Run it to see it fail**

Run: `node desktop/island/calendar/test_cal.js`
Expected: FAIL, `ENOENT ... Cal.js`.

- [ ] **Step 3: Write Cal.js**

`desktop/island/calendar/Cal.js`:

```js
.pragma library

// <GPLv2 header>

// Pure date logic for the calendar panel. Days are "YYYY-MM-DD" strings and
// times "HH:MM", the shapes calctl speaks; day arithmetic goes through UTC so
// a DST change never shifts a day. Tested by test_cal.js under node.

function pad(n) {
    return (n < 10 ? "0" : "") + n;
}

function fromUtc(t) {
    return t.getUTCFullYear() + "-" + pad(t.getUTCMonth() + 1) + "-" + pad(t.getUTCDate());
}

function utc(day) {
    return Date.UTC(+day.slice(0, 4), +day.slice(5, 7) - 1, +day.slice(8, 10));
}

function addDays(day, n) {
    return fromUtc(new Date(utc(day) + n * 86400000));
}

function daysBetween(a, b) {
    return Math.round((utc(b) - utc(a)) / 86400000);
}

// The local calendar day of a JS Date.
function today(now) {
    return now.getFullYear() + "-" + pad(now.getMonth() + 1) + "-" + pad(now.getDate());
}

// 42 cells, six weeks from Monday (khal's firstweekday = 0).
function monthCells(y, m0) {
    const first = new Date(Date.UTC(y, m0, 1));
    const month = fromUtc(first).slice(0, 7);
    const lead = (first.getUTCDay() + 6) % 7;
    const start = addDays(fromUtc(first), -lead);
    const out = [];
    for (let i = 0; i < 42; i++) {
        const iso = addDays(start, i);
        out.push({ iso: iso, day: +iso.slice(8, 10), inMonth: iso.slice(0, 7) === month });
    }
    return out;
}

function shiftMonth(y, m0, n) {
    const t = new Date(Date.UTC(y, m0 + n, 1));
    return { y: t.getUTCFullYear(), m0: t.getUTCMonth() };
}

// The last day an event covers. calctl gives all-day ends inclusive; a
// timed event ending exactly at midnight does not reach the day it ends on.
function lastDay(ev) {
    const endDay = ev.end.slice(0, 10);
    if (!ev.allDay && ev.end.slice(11, 16) === "00:00" && ev.end > ev.start)
        return addDays(endDay, -1);
    return endDay;
}

function onDay(ev, day) {
    return ev.start.slice(0, 10) <= day && lastDay(ev) >= day;
}

// The day's events, all-day first, then by start.
function dayEvents(events, day) {
    return events.filter(e => onDay(e, day)).sort((a, b) =>
        (b.allDay - a.allDay) || (a.start < b.start ? -1 : a.start > b.start ? 1 : 0));
}

// The calendars with something on the day, in calendar order.
function dots(events, day, calendars) {
    return calendars.filter(c => events.some(e => e.calendar === c.name && onDay(e, day)));
}

function timeLabel(ev, day) {
    if (ev.allDay) return "all day";
    const s = ev.start.slice(0, 10) === day ? ev.start.slice(11, 16) : "…";
    const e = ev.end.slice(0, 10) === day ? ev.end.slice(11, 16) : "…";
    return s + "–" + e;
}

function validTime(s) {
    return /^([01]\d|2[0-3]):[0-5]\d$/.test(s);
}

// Step a time by minutes, wrapping within the day; an invalid time is left
// for the user to fix rather than guessed at.
function stepTime(s, minutes) {
    if (!validTime(s)) return s;
    const m = ((+s.slice(0, 2) * 60 + +s.slice(3, 5) + minutes) % 1440 + 1440) % 1440;
    return pad(Math.floor(m / 60)) + ":" + pad(m % 60);
}

// A new event on `day`: the next whole hour, one hour long, alarm 1h (the
// most common alarm in the live calendars). Capped at 22:00 so the end stays
// on the same day.
function newDraft(day, now, calendar) {
    const h = Math.min(22, now.getHours() + 1);
    return { uid: "", calendar: calendar, title: "", allDay: false,
             startDay: day, endDay: day, startTime: pad(h) + ":00", endTime: pad(h + 1) + ":00",
             repeat: "none", until: "", alarm: "1h", location: "", notes: "", override: false };
}

// calctl's event JSON as an editor draft.
function fromEvent(ev) {
    return { uid: ev.uid, calendar: ev.calendar, title: ev.title, allDay: ev.allDay,
             startDay: ev.start.slice(0, 10), endDay: ev.end.slice(0, 10),
             startTime: ev.allDay ? "09:00" : ev.start.slice(11, 16),
             endTime: ev.allDay ? "10:00" : ev.end.slice(11, 16),
             repeat: ev.repeat, until: ev.until, alarm: ev.alarm,
             location: ev.location, notes: ev.notes, override: ev.override };
}

// A click on the grid while editing. Plain: move the event, keeping its
// length in days. Shift: set the end, or the start when before it.
function pick(draft, day, shift) {
    const d = Object.assign({}, draft);
    if (!shift) {
        const len = daysBetween(d.startDay, d.endDay);
        d.startDay = day;
        d.endDay = addDays(day, len);
    } else if (day >= d.startDay) {
        d.endDay = day;
    } else {
        d.startDay = day;
    }
    return d;
}

// The draft as calctl's event JSON, or the first thing wrong with it.
function toPayload(d) {
    if (!d.title.trim()) return { error: "Title is empty" };
    if (!d.allDay && (!validTime(d.startTime) || !validTime(d.endTime)))
        return { error: "Times are HH:MM" };
    const start = d.allDay ? d.startDay : d.startDay + "T" + d.startTime;
    const end = d.allDay ? d.endDay : d.endDay + "T" + d.endTime;
    if (end < start) return { error: "End is before start" };
    const repeats = d.repeat !== "none" && d.repeat !== "custom";
    if (repeats && d.until && d.until < d.startDay) return { error: "Until is before the start" };
    return { payload: {
        calendar: d.calendar, title: d.title.trim(), allDay: d.allDay, start: start, end: end,
        repeat: d.repeat, until: repeats ? d.until : "", alarm: d.alarm,
        location: d.location, notes: d.notes } };
}
```

- [ ] **Step 4: Run the test**

Run: `node desktop/island/calendar/test_cal.js`
Expected: `test_cal: ok`

- [ ] **Step 5: Commit**

```bash
git add desktop/island/calendar/Cal.js desktop/island/calendar/test_cal.js
git commit -m "feat(calendar): pure date logic for the panel

Month cells from Monday, which days an event covers, the day's agenda
order, the grid's dots, time stepping, and the editor's draft in both
directions. Days are strings and arithmetic is in UTC, so the DST change
at the end of October never moves a day; the test steps across it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 5: Calendar.qml

**Files:**
- Create: `desktop/island/calendar/Calendar.qml`

- [ ] **Step 1: Write the singleton**

```qml
// <GPLv2 header>

pragma Singleton

import Quickshell
import Quickshell.Io
import QtQuick

// The calendars, through calctl. Holds the occurrences of the range the
// panel shows and reloads them when a calendar directory changes, whoever
// changed it: the panel, khal, or the cron sync bringing the phone's edits.
Singleton {
    id: root

    readonly property string calctl: Qt.resolvedUrl("calctl").toString().replace(/^file:\/\//, "")

    property var calendars: []          // [{name, color, path}]
    property string defaultCalendar: ""
    property var events: []             // occurrences in [from, to)
    property string from: ""
    property string to: ""
    property string error: ""

    // A list that finishes after a newer one started is dropped.
    property int generation: 0

    readonly property var paths: calendars.map(c => c.path)

    function load(fromDay, toDay) {
        root.from = fromDay;
        root.to = toDay;
        root.refresh();
    }

    function refresh() {
        if (!root.from) return;
        const g = ++root.generation;
        root.run(["list", root.from, root.to], r => {
            if (g !== root.generation) return;
            if (r.ok) { root.events = r.data; root.error = ""; }
            else root.error = r.error;
        });
    }

    function get(uid, cb) { root.run(["get", uid], cb); }
    function create(event, cb) { root.run(["new", JSON.stringify(event)], cb); }
    function update(uid, event, cb) { root.run(["edit", uid, JSON.stringify(event)], cb); }
    function remove(uid, cb) { root.run(["delete", uid], cb); }

    // One Process per call, so a list and a save never share one (a running
    // Process ignores a second start, AGENTS.md). cb gets calctl's envelope.
    function run(args, cb) {
        op.createObject(root, { command: [root.calctl].concat(args), cb: cb }).running = true;
    }

    Component {
        id: op
        Process {
            id: proc
            property var cb: null
            stdout: StdioCollector {
                onStreamFinished: {
                    let r;
                    try { r = JSON.parse(text); }
                    catch (e) { r = { ok: false, error: "calctl: " + (text.trim() || "no output") }; }
                    if (proc.cb) proc.cb(r);
                    proc.destroy();
                }
            }
        }
    }

    Component.onCompleted: root.run(["calendars"], r => {
        if (!r.ok) { root.error = r.error; return; }
        root.calendars = r.data.calendars;
        root.defaultCalendar = r.data.default;
    })

    // Same shape as the mail count's xapian watch: one burst of file events
    // (a write is a temp file plus a rename; a sync touches several) becomes
    // one reload, and a dead watcher comes back.
    Process {
        id: watcher
        running: root.paths.length > 0
        command: ["inotifywait", "-m", "-q", "-e", "close_write,moved_to,delete", "--format", "x"]
            .concat(root.paths)
        stdout: SplitParser { onRead: debounce.restart() }
        onExited: respawn.start()
    }

    Timer { id: debounce; interval: 300; onTriggered: root.refresh() }
    Timer { id: respawn; interval: 5000; onTriggered: watcher.running = root.paths.length > 0 }
}
```

- [ ] **Step 2: Commit**

Nothing imports it yet; Task 8 exercises it.

```bash
git add desktop/island/calendar/Calendar.qml
git commit -m "feat(calendar): the calendar service

Runs calctl, one Process per call so a reload and a save never collide,
and drops a list that a newer one overtook. Watches the calendar
directories the way the mail count watches xapian, so an edit from khal
or a cron sync repaints the panel too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 6: EventEditor.qml

**Files:**
- Create: `desktop/island/calendar/EventEditor.qml`

- [ ] **Step 1: Write the editor**

```qml
// <GPLv2 header>

import QtQuick
import "../.."
import "Cal.js" as Cal

// The event form. The month grid beside it is its date picker: the panel
// forwards grid clicks to pick(). Text fields are filled imperatively by
// load() and write back on edit, so typing never fights a binding.
Column {
    id: ed

    property var draft: Cal.newDraft(Cal.today(new Date()), new Date(), "")
    property bool pickUntil: false
    property bool confirmDelete: false
    property bool busy: false
    property string err: ""

    signal done()

    spacing: 8

    function load(d) {
        ed.draft = d;
        ed.err = "";
        ed.pickUntil = false;
        ed.confirmDelete = false;
        ed.busy = false;
        title.input.text = d.title;
        startTime.input.text = d.startTime;
        endTime.input.text = d.endTime;
        location.input.text = d.location;
        notes.text = d.notes;
        title.input.forceActiveFocus();
    }

    function set(key, value) {
        const d = Object.assign({}, ed.draft);
        d[key] = value;
        ed.draft = d;
    }

    function pick(day, shift) {
        if (ed.pickUntil) {
            ed.set("until", day);
            ed.pickUntil = false;
        } else {
            ed.draft = Cal.pick(ed.draft, day, shift);
        }
    }

    function finish(r) {
        ed.busy = false;
        if (r.ok) ed.done();
        else ed.err = r.error;
    }

    function save() {
        const r = Cal.toPayload(ed.draft);
        if (r.error) { ed.err = r.error; return; }
        ed.busy = true;
        if (ed.draft.uid) Calendar.update(ed.draft.uid, r.payload, ed.finish);
        else Calendar.create(r.payload, ed.finish);
    }

    function remove() {
        if (!ed.confirmDelete) { ed.confirmDelete = true; return; }
        ed.busy = true;
        Calendar.remove(ed.draft.uid, ed.finish);
    }

    function dayLabel(day) {
        const d = new Date(+day.slice(0, 4), +day.slice(5, 7) - 1, +day.slice(8, 10));
        return Qt.formatDate(d, "ddd d MMM");
    }

    // An unhandled Escape from any field lands here: leave the editor, not
    // the panel.
    Keys.onEscapePressed: ed.done()

    component Field: Rectangle {
        property alias input: ti
        property string placeholder: ""
        height: 30
        radius: 8
        color: Theme.surface
        TextInput {
            id: ti
            anchors { fill: parent; leftMargin: 8; rightMargin: 8 }
            verticalAlignment: TextInput.AlignVCenter
            clip: true
            selectByMouse: true
            color: Theme.text
            font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 3 }
        }
        Text {
            anchors { fill: parent; leftMargin: 8 }
            verticalAlignment: Text.AlignVCenter
            visible: ti.text === "" && !ti.activeFocus
            text: parent.placeholder
            color: Theme.overlay
            font: ti.font
        }
    }

    component Chip: Rectangle {
        property string label: ""
        property bool on: false
        property color tint: Theme.accent
        signal clicked()
        width: chipText.implicitWidth + 16
        height: 26
        radius: 13
        color: on ? Qt.alpha(tint, 0.35) : Theme.surface
        Text {
            id: chipText
            anchors.centerIn: parent
            text: parent.label
            color: Theme.text
            font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 }
        }
        MouseArea { anchors.fill: parent; cursorShape: Qt.PointingHandCursor; onClicked: parent.clicked() }
    }

    component Label: Text {
        width: 58
        anchors.verticalCenter: parent ? parent.verticalCenter : undefined
        color: Theme.subtext
        font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 }
    }

    Field {
        id: title
        width: ed.width
        placeholder: "Title"
        input.onTextEdited: ed.set("title", input.text)
        input.onAccepted: ed.save()
    }

    // When: the dates come from the grid.
    Row {
        spacing: 6
        Label { text: "When" }
        Text {
            anchors.verticalCenter: parent.verticalCenter
            text: ed.draft.startDay === ed.draft.endDay ? ed.dayLabel(ed.draft.startDay)
                : ed.dayLabel(ed.draft.startDay) + " – " + ed.dayLabel(ed.draft.endDay)
            color: Theme.text
            font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 3 }
        }
        Text {
            anchors.verticalCenter: parent.verticalCenter
            text: "click the month, shift for the end"
            color: Theme.overlay
            font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 6 }
        }
    }

    Row {
        spacing: 6
        Label { text: "Time" }
        Field {
            id: startTime
            width: 62
            visible: !ed.draft.allDay
            input.onTextEdited: ed.set("startTime", input.text)
            MouseArea {
                anchors.fill: parent
                acceptedButtons: Qt.NoButton
                property real acc: 0
                onWheel: wheel => {
                    acc += wheel.angleDelta.y;
                    if (Math.abs(acc) < 120) return;
                    parent.input.text = Cal.stepTime(parent.input.text, acc > 0 ? 15 : -15);
                    ed.set("startTime", parent.input.text);
                    acc = 0;
                }
            }
        }
        Text {
            anchors.verticalCenter: parent.verticalCenter
            visible: !ed.draft.allDay
            text: "–"
            color: Theme.subtext
        }
        Field {
            id: endTime
            width: 62
            visible: !ed.draft.allDay
            input.onTextEdited: ed.set("endTime", input.text)
            MouseArea {
                anchors.fill: parent
                acceptedButtons: Qt.NoButton
                property real acc: 0
                onWheel: wheel => {
                    acc += wheel.angleDelta.y;
                    if (Math.abs(acc) < 120) return;
                    parent.input.text = Cal.stepTime(parent.input.text, acc > 0 ? 15 : -15);
                    ed.set("endTime", parent.input.text);
                    acc = 0;
                }
            }
        }
        Chip {
            anchors.verticalCenter: parent.verticalCenter
            label: "all day"
            on: ed.draft.allDay
            onClicked: ed.set("allDay", !ed.draft.allDay)
        }
    }

    Row {
        spacing: 6
        Label { text: "Calendar" }
        Repeater {
            model: Calendar.calendars
            delegate: Chip {
                required property var modelData
                anchors.verticalCenter: parent.verticalCenter
                label: modelData.name
                on: ed.draft.calendar === modelData.name
                tint: modelData.color.startsWith("#") ? modelData.color : Theme[modelData.color]
                onClicked: ed.set("calendar", modelData.name)
            }
        }
    }

    Row {
        spacing: 4
        Label { text: "Repeat" }
        Repeater {
            // custom is shown, never offered: it means a rule this form
            // cannot express, kept as it is.
            model: ["none", "daily", "weekly", "monthly", "yearly"]
                .concat(ed.draft.repeat === "custom" ? ["custom"] : [])
            delegate: Chip {
                required property string modelData
                anchors.verticalCenter: parent.verticalCenter
                label: ({ none: "none", daily: "day", weekly: "week", monthly: "month",
                          yearly: "year", custom: "custom" })[modelData]
                on: ed.draft.repeat === modelData
                onClicked: if (modelData !== "custom") ed.set("repeat", modelData)
            }
        }
    }

    Row {
        spacing: 6
        visible: ed.draft.repeat !== "none" && ed.draft.repeat !== "custom"
        Label { text: "Until" }
        Chip {
            anchors.verticalCenter: parent.verticalCenter
            label: ed.pickUntil ? "pick a day…" : (ed.draft.until ? ed.dayLabel(ed.draft.until) : "forever")
            on: ed.pickUntil
            onClicked: ed.pickUntil = !ed.pickUntil
        }
        Chip {
            anchors.verticalCenter: parent.verticalCenter
            visible: ed.draft.until !== ""
            label: "×"
            onClicked: ed.set("until", "")
        }
    }

    Row {
        spacing: 4
        Label { text: "Alarm" }
        Repeater {
            model: ["none", "10m", "1h", "1d"].concat(ed.draft.alarm === "custom" ? ["custom"] : [])
            delegate: Chip {
                required property string modelData
                anchors.verticalCenter: parent.verticalCenter
                label: modelData
                on: ed.draft.alarm === modelData
                onClicked: if (modelData !== "custom") ed.set("alarm", modelData)
            }
        }
    }

    Text {
        visible: ed.draft.override === true
        width: ed.width
        wrapMode: Text.WordWrap
        text: "cal-notif has its own alarm for this event, and it wins."
        color: Theme.overlay
        font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 5 }
    }

    Field {
        id: location
        width: ed.width
        placeholder: "Location"
        input.onTextEdited: ed.set("location", input.text)
    }

    Rectangle {
        width: ed.width
        height: 56
        radius: 8
        color: Theme.surface
        TextEdit {
            id: notes
            anchors { fill: parent; margins: 8 }
            wrapMode: TextEdit.Wrap
            selectByMouse: true
            clip: true
            color: Theme.text
            font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 }
            onTextChanged: if (text !== ed.draft.notes) ed.set("notes", text)
        }
        Text {
            anchors { left: parent.left; top: parent.top; margins: 8 }
            visible: notes.text === "" && !notes.activeFocus
            text: "Notes"
            color: Theme.overlay
            font: notes.font
        }
    }

    Text {
        visible: ed.err !== ""
        width: ed.width
        wrapMode: Text.WordWrap
        text: ed.err
        color: Theme.red
        font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 }
    }

    Item {
        width: ed.width
        height: 28

        Chip {
            visible: ed.draft.uid !== ""
            label: ed.confirmDelete ? "Delete, really" : "Delete"
            tint: Theme.red
            on: ed.confirmDelete
            onClicked: if (!ed.busy) ed.remove()
        }
        Row {
            anchors.right: parent.right
            spacing: 6
            Chip { label: "Cancel"; onClicked: ed.done() }
            Chip { label: ed.busy ? "Saving…" : "Save"; on: true; onClicked: if (!ed.busy) ed.save() }
        }
    }
}
```

- [ ] **Step 2: Commit**

```bash
git add desktop/island/calendar/EventEditor.qml
git commit -m "feat(calendar): the event form

Dates come from the month grid beside it; times are typed or scrolled in
15-minute steps. Repeat and alarm offer the presets and show custom,
unselectable, for an event carrying something richer, which the save
then leaves alone. A failed save keeps the form open with calctl's line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 7: CalendarPanel.qml

**Files:**
- Create: `desktop/island/calendar/CalendarPanel.qml`

- [ ] **Step 1: Write the panel**

```qml
// <GPLv2 header>

import Quickshell
import QtQuick
import "../.."
import "Cal.js" as Cal

// Month grid on the left, the selected day's agenda on the right. Opening
// an event swaps the agenda for the editor, and the grid becomes its date
// picker.
Item {
    id: panel

    signal closeRequested()

    property int viewY: 2026
    property int viewM0: 0
    property string selected: ""
    property bool editing: false
    property string agendaError: ""

    readonly property var cells: Cal.monthCells(viewY, viewM0)
    readonly property real gridWidth: 252

    implicitHeight: Math.max(left.implicitHeight, right.implicitHeight)

    SystemClock { id: clock; precision: SystemClock.Minutes }
    readonly property string todayIso: Cal.today(clock.date)

    function colorOf(c) {
        return c.startsWith("#") ? c : Theme[c];
    }

    function show(y, m0) {
        panel.viewY = y;
        panel.viewM0 = m0;
        const cells = Cal.monthCells(y, m0);
        Calendar.load(cells[0].iso, Cal.addDays(cells[41].iso, 1));
    }

    // Each time the panel opens: today, its month, no editor.
    function reset() {
        const now = new Date();
        panel.editing = false;
        panel.agendaError = "";
        panel.selected = Cal.today(now);
        panel.show(now.getFullYear(), now.getMonth());
    }

    function shift(n) {
        const m = Cal.shiftMonth(panel.viewY, panel.viewM0, n);
        panel.show(m.y, m.m0);
    }

    function clickDay(day, shiftKey) {
        if (panel.editing) {
            editor.pick(day, shiftKey);
            return;
        }
        panel.selected = day;
        if (day.slice(0, 7) !== Cal.monthCells(panel.viewY, panel.viewM0)[10].iso.slice(0, 7))
            panel.show(+day.slice(0, 4), +day.slice(5, 7) - 1);
    }

    function openEvent(uid) {
        Calendar.get(uid, r => {
            if (!r.ok) { panel.agendaError = r.error; return; }
            editor.load(Cal.fromEvent(r.data));
            panel.editing = true;
        });
    }

    function newEvent() {
        editor.load(Cal.newDraft(panel.selected, new Date(), Calendar.defaultCalendar));
        panel.editing = true;
    }

    function closeEditor() {
        panel.editing = false;
        panel.forceActiveFocus();
    }

    // Escape: the editor first, then the panel.
    function escape() {
        if (panel.editing) { panel.closeEditor(); return true; }
        return false;
    }

    Keys.onEscapePressed: if (!panel.escape()) panel.closeRequested()

    Component.onCompleted: panel.reset()

    // --- left: the month ---------------------------------------------------

    Column {
        id: left
        width: panel.gridWidth
        spacing: 6

        Item {
            width: parent.width
            height: 22

            Text {
                anchors.verticalCenter: parent.verticalCenter
                text: Qt.locale().standaloneMonthName(panel.viewM0) + " " + panel.viewY
                color: Theme.text
                font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 2; bold: true }
            }
            Row {
                anchors { right: parent.right; verticalCenter: parent.verticalCenter }
                spacing: 12
                Repeater {
                    model: [{ t: "‹", n: -1 }, { t: "›", n: 1 }]
                    delegate: Text {
                        required property var modelData
                        text: modelData.t
                        color: Theme.subtext
                        font { family: Theme.fontFamily; pixelSize: Theme.fontSize + 2 }
                        MouseArea {
                            anchors { fill: parent; margins: -6 }
                            cursorShape: Qt.PointingHandCursor
                            onClicked: panel.shift(parent.modelData.n)
                        }
                    }
                }
            }
        }

        Grid {
            columns: 7
            spacing: 2

            Repeater {
                model: [0, 1, 2, 3, 4, 5, 6]
                delegate: Text {
                    required property int modelData
                    width: (panel.gridWidth - 12) / 7
                    horizontalAlignment: Text.AlignHCenter
                    // Monday first: Qt.locale().dayName counts from Sunday.
                    text: Qt.locale().dayName((modelData + 1) % 7, Locale.NarrowFormat)
                    color: Theme.overlay
                    font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 5 }
                }
            }

            Repeater {
                model: panel.cells
                delegate: Rectangle {
                    id: cell
                    required property var modelData
                    readonly property bool inDraft: panel.editing
                        && modelData.iso >= editor.draft.startDay && modelData.iso <= editor.draft.endDay

                    width: (panel.gridWidth - 12) / 7
                    height: 32
                    radius: 8
                    color: inDraft ? Qt.alpha(Theme.accent, 0.35)
                         : hover.containsMouse ? Qt.alpha(Theme.surface, 0.8) : "transparent"
                    border.width: !panel.editing && modelData.iso === panel.selected ? 1 : 0
                    border.color: Theme.accent

                    Text {
                        anchors { horizontalCenter: parent.horizontalCenter; top: parent.top; topMargin: 5 }
                        text: cell.modelData.day
                        color: cell.modelData.iso === panel.todayIso ? Theme.accent
                             : cell.modelData.inMonth ? Theme.text : Theme.overlay
                        font {
                            family: Theme.fontFamily
                            pixelSize: Theme.fontSize - 4
                            bold: cell.modelData.iso === panel.todayIso
                        }
                    }

                    Row {
                        anchors { horizontalCenter: parent.horizontalCenter; bottom: parent.bottom; bottomMargin: 4 }
                        spacing: 2
                        Repeater {
                            model: Cal.dots(Calendar.events, cell.modelData.iso, Calendar.calendars)
                            delegate: Rectangle {
                                required property var modelData
                                width: 4
                                height: 4
                                radius: 2
                                color: panel.colorOf(modelData.color)
                            }
                        }
                    }

                    MouseArea {
                        id: hover
                        anchors.fill: parent
                        hoverEnabled: true
                        cursorShape: Qt.PointingHandCursor
                        onClicked: mouse => panel.clickDay(cell.modelData.iso,
                                                           (mouse.modifiers & Qt.ShiftModifier) !== 0)
                    }
                }
            }
        }
    }

    // --- right: agenda or editor -------------------------------------------

    Item {
        id: right
        x: panel.gridWidth + 16
        width: panel.width - x
        implicitHeight: panel.editing ? editor.implicitHeight : agenda.implicitHeight

        Column {
            id: agenda
            width: parent.width
            spacing: 6
            visible: !panel.editing

            Text {
                text: panel.selected === "" ? ""
                    : Qt.formatDate(new Date(+panel.selected.slice(0, 4), +panel.selected.slice(5, 7) - 1,
                                             +panel.selected.slice(8, 10)), "dddd d MMMM")
                color: Theme.text
                font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 2; bold: true }
            }

            Text {
                visible: text !== ""
                width: parent.width
                wrapMode: Text.WordWrap
                text: panel.agendaError || Calendar.error
                color: Theme.red
                font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 5 }
            }

            Repeater {
                id: dayList
                model: Cal.dayEvents(Calendar.events, panel.selected)
                delegate: Rectangle {
                    id: row
                    required property var modelData
                    width: agenda.width
                    height: 30
                    radius: 8
                    color: rowHover.containsMouse ? Theme.surfaceAlt : Theme.surface

                    Rectangle {
                        x: 6
                        anchors.verticalCenter: parent.verticalCenter
                        width: 3
                        height: parent.height - 12
                        radius: 2
                        color: panel.colorOf(row.modelData.color)
                    }
                    Text {
                        id: when
                        x: 16
                        width: 82
                        anchors.verticalCenter: parent.verticalCenter
                        text: Cal.timeLabel(row.modelData, panel.selected)
                        color: Theme.subtext
                        font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 5 }
                    }
                    Text {
                        anchors { left: when.right; right: parent.right; rightMargin: 8; verticalCenter: parent.verticalCenter }
                        elide: Text.ElideRight
                        text: row.modelData.title
                        color: Theme.text
                        font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 }
                    }
                    MouseArea {
                        id: rowHover
                        anchors.fill: parent
                        hoverEnabled: true
                        cursorShape: Qt.PointingHandCursor
                        onClicked: panel.openEvent(row.modelData.uid)
                    }
                }
            }

            Text {
                visible: dayList.count === 0
                text: "Nothing on this day"
                color: Theme.overlay
                font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 }
            }

            Rectangle {
                width: agenda.width
                height: 30
                radius: 8
                color: "transparent"
                border.width: 1
                border.color: Theme.surfaceAlt
                Text {
                    anchors.centerIn: parent
                    text: "+ New event"
                    color: Theme.subtext
                    font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 }
                }
                MouseArea {
                    anchors.fill: parent
                    cursorShape: Qt.PointingHandCursor
                    onClicked: panel.newEvent()
                }
            }
        }

        EventEditor {
            id: editor
            width: parent.width
            visible: panel.editing
            onDone: panel.closeEditor()
        }
    }
}
```

- [ ] **Step 2: Commit**

```bash
git add desktop/island/calendar/CalendarPanel.qml
git commit -m "feat(calendar): month grid beside the day's agenda

Six weeks from Monday, a dot per calendar with something that day, today
and the selection marked. The agenda lists the selected day, all-day
first; a click opens the event in the editor, and while the editor is
open the grid picks its dates instead of the selection. Escape closes
the editor before the panel.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 8: Wire it into the clock pill and the island

**Files:**
- Modify: `desktop/island/ClockPill.qml`
- Modify: `desktop/island/Island.qml`

- [ ] **Step 1: ClockPill**

Add `import "calendar"` after `import "../modules/vm"`.

Update the top comment to: `// Date and time at rest, with one dot per VM that is not plainly shut off. During a flick: the workspace's desktop icon, the app's icon and its name. A click opens the calendar panel in this capsule.` (wrapped like the file).

After `property string flickApp: ""` add:

```qml
    property string panel: ""

    signal openCalendar()
    signal closeCalendar()

    expanded: panel === "calendar"
    panelWidth: 620
    panelHeight: calendarPanel.implicitHeight + 28

    // The island calls these: focus moves into the panel when it opens, and
    // Escape asks the panel before closing it.
    function focusPanel() { calendarPanel.reset(); calendarPanel.forceActiveFocus(); }
    function escape() { return calendarPanel.escape(); }
```

In `restRow` change `opacity: pill.flicking ? 0 : 1` to `opacity: pill.flicking || pill.expanded ? 0 : 1`.

In `flickRow` change `opacity: pill.flicking ? 1 : 0` to `opacity: pill.flicking && !pill.expanded ? 1 : 0`.

At the end of the pill, after `flickRow`, add:

```qml
    // At rest the whole pill is the button; open, the panel takes the clicks.
    MouseArea {
        anchors.fill: parent
        enabled: !pill.expanded
        cursorShape: Qt.PointingHandCursor
        onClicked: pill.openCalendar()
    }

    CalendarPanel {
        id: calendarPanel
        x: 14
        y: 14
        width: pill.panelWidth - 28
        opacity: pill.expanded ? 1 : 0
        visible: opacity > 0
        Behavior on opacity { NumberAnimation { duration: 160 } }
        onCloseRequested: pill.closeCalendar()
    }
```

- [ ] **Step 2: Island**

Change the comment `// "", "sound" or "controls".` to `// "", "sound", "controls" or "calendar".`

Replace the `onPanelChanged` handler with:

```qml
    onPanelChanged: {
        if (panel === "calendar") clock.focusPanel();
        else if (panel !== "") keys.forceActiveFocus();
        else if (!hovered) hideTimer.restart();
    }
```

In the `keys` item, replace `Keys.onEscapePressed: win.panel = ""` with:

```qml
        Keys.onEscapePressed: if (!(win.panel === "calendar" && clock.escape())) win.panel = ""
```

In `ClockPill { ... }` add:

```qml
        panel: win.panel
        onOpenCalendar: win.panel = win.panel === "calendar" ? "" : "calendar"
        onCloseCalendar: win.panel = ""
```

- [ ] **Step 3: Check the running shell**

Run: `sleep 2; qs log -p ~/Programming/GIT/quickshell/desktop -t 40 2>&1 | grep -v "host portal\|playerctld"`
Expected: a `Reloading configuration...` / `Configuration Loaded` pair after the edit and no `ReferenceError`, `TypeError`, `is not a type`, `Cannot assign` or `unresolvable import` naming `calendar`, `Calendar`, `CalendarPanel`, `EventEditor`, `Cal`, `ClockPill` or `Island`.

If the log shows `Ignoring unresolvable import` for `calendar`, or the shell did not reload, ask the user to run `./reload.sh desktop` from their terminal (AGENTS.md, Reloading: a new directory may not be indexed by hot reload), then read the log again. Do not start `qs` yourself.

Then confirm the watcher started: `pgrep -a inotifywait | grep -c calendars`
Expected: `1`.

- [ ] **Step 4: Commit**

```bash
git add desktop/island/ClockPill.qml desktop/island/Island.qml
git commit -m "feat(island): the clock pill opens the calendar panel

A click on the pill opens the panel in its capsule, 620px wide, growing
left from the gap so the status pill does not move. Focus goes into the
panel so its text fields and Escape work; Escape closes the editor
before the panel.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```

---

### Task 9: Check with the user

No code. Ask the user to check on screen, and fix what they report before Task 10. Writes here are the user's own, on their live calendars, by their hand.

- Click the clock pill: the panel opens on today's month, today marked, dots on days with events in the two calendars' colours; arrows change month; Escape closes.
- A day click lists its events, all-day first, with times.
- "+ New event": title, a time, Save. It appears in the agenda and the grid within a second; `khal list today 7d` shows it.
- Open it again: change the time by scrolling, change the date by clicking the grid and a range by shift-click, move it to the other calendar, set weekly until a date; Save, and check the grid.
- Alarm: set 10m; open an existing birthday (repeat reads year, its alarm as it is).
- Delete: one click arms, the second deletes.
- An edit made with `khal edit` or `ikhal` while the panel is open shows up in it.
- Typing in the title then pressing Escape closes the editor, not the panel; a second Escape closes the panel.

---

### Task 10: Docs

**Files:**
- Modify: `desktop/island/README.md`
- Modify: `AGENTS.md`

- [ ] **Step 1: README**

In `desktop/island/README.md`, in `## Clock pill`, add `Click opens the calendar panel.` to its description, and add a section after the controls panel section:

```
## Calendar panel

The clock pill opens a month grid beside the selected day's agenda. Dots
are one per calendar with something that day, in the khal colours. A click
on an event, or "+ New event", opens the editor; while it is open the grid
picks the date (shift-click for the end). Repeat is none, daily, weekly,
monthly or yearly with an optional until-date; the alarm is none, 10m, 1h or
1d. An event with something richer shows custom and an edit leaves it
alone. Edit and delete act on the whole series.

Everything goes through `calendar/calctl`, which reads the calendar list
from khal's config, writes the `.ics` files atomically and starts a
`vdirsyncer sync` after each write. The panel watches the calendar
directories, so khal edits and cron syncs show up live. Tests:
`/usr/bin/python3 calendar/test_calctl.py`, `node calendar/test_cal.js`.
```

- [ ] **Step 2: AGENTS.md**

Update the island line in "What this is" to end `controls panel (SUPER alone), calendar`. Add to the per-component notes whatever Tasks 2 to 9 established that is not obvious, at minimum:

```
- **khal 0.11 has no JSON output**, which is why the calendar reads the vdir
  itself through `calctl` rather than parsing `khal list -f`. khal and
  cal-notif read the same files and are unaffected by calctl's writes.
- **Recurrence is expanded in naive local time.** A TZID event keeps its
  wall-clock time across DST that way; expanding in UTC moved a weekly
  09:00 to 10:00 after the change. `test_calctl.py` pins it on 26 October.
```

Only keep the second note's "expanding in UTC moved" clause if that was actually observed during the build; otherwise state the rule without it. Add the `calctl list` timing from Task 3 Step 5 to the first note.

- [ ] **Step 3: Commit**

```bash
git add desktop/island/README.md AGENTS.md
git commit -m "docs: the calendar panel and calctl

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```