feat(ayet-kosesi): 1.5.0 — copy/share/refresh actions, day-rollover fix, status line

ayet-kosesi/README.md

@@ -18,6 +18,33 @@ Add the `ayet` desktop widget from Noctalia's desktop widget settings.
 
 The plugin polls `https://akilkuran.com/api/daily-verse` once per minute. The API is the single source of truth for Akıl Kuran's current automatic/manual Günün Ayeti.
 
-The optional `author` query parameter is used to request the same daily verse in a selected public translation. The plugin first checks `~/.config/ayet-kosesi/meal-id`; if absent, it executes `~/.local/bin/akilkuran-meal-id`. If no local meal is available, it falls back to a language-based default (Turkish 105, English 32).
+The optional `author` query parameter is used to request the same daily verse in a selected public translation. The plugin resolves it through the following chain:
 
-The plugin stores only its own verse/logo cache under Noctalia's plugin data directory. It does not access Akıl Kuran user accounts, browser storage, cookies, Firebase credentials, or private source code.
+1. `~/.config/ayet-kosesi/meal-id` — manual override (highest priority; must be a public author ID).
+2. `~/.local/bin/akilkuran-meal-id` — helper that reads the user's Akıl Kuran selection (`meal.settings.mealOrder[0]`) from the default browser's local storage. It prints the ID only when a valid selection exists; empty output means "no selection".
+3. Every resolved ID is validated against `https://akilkuran.com/api/meal-registry` (public, anonymous). Non-public IDs fall through to the next step.
+4. `languageDefaults[language]` from the registry (registry is authoritative — the plugin contains no hardcoded tr/en mapping).
+5. Registry `default`, then `105` as a last-resort constant.
+
+The plugin language is detected from Noctalia's own `settings.toml` (`[shell] lang`, read with the API 24 `readFile`) — the most reliable signal, because the Noctalia process may run with an unrelated `LANG`. If the file is missing or unreadable, the process environment (`LC_ALL` / `LC_MESSAGES` / `LANG`) is used as a fallback.
+
+## Interactions (1.5.0)
+
+- **Copy verse** — click the verse text (or the copy glyph button).
+- **Share text** — the share glyph copies "verse" + reference + author + URL in one line.
+- **Copy URL** — the link glyph copies the verse URL.
+- **Header reference** — the header shows the full reference (e.g. `Rad 13:13`) next to the logo.
+- **Manual refresh** — the refresh glyph re-resolves the meal selection chain (including the browser helper) and fetches; 20 s cooldown prevents spam.
+- Every copy shows a brief "✓ …" confirmation in the status line (2 s, independent from the verse area); long verses scroll instead of being clipped (fixed 420×260 size).
+- Status line shows automatic/manual mode, language, and a plain-language notice on network/429/503 errors while the cached verse stays visible.
+
+## Caching and polling
+
+- `/api/meal-registry` is cached ~1 hour (memory + plugin data dir), so the selection chain costs no extra request in the common case.
+- The verse cache is validated by day: after midnight the first poll fetches the new verse; the cached verse is never shown for a day it does not belong to.
+- The daily verse is fetched only when the day or the resolved meal changes; otherwise the cached verse is rendered. Every ~5 minutes one silent revalidation keeps manual changes in sync; failed requests back off for 90 s.
+- Requests are debounced (30 s minimum gap). The helper process is cached for 3 minutes; only manual refresh re-runs it immediately.
+- On API failure the last successful verse stays on screen. Cached verses remember their meal; a cache belonging to a different meal is not shown as if it matched the new selection.
+- The update loop re-arms its 1 s interval on every tick (interval is one-shot in this Noctalia build), so "✓" confirmations always expire exactly 2 s after the action — verified against the live runtime; a render-time expiry gate is the final safety net.
+
+The plugin stores only its own verse/registry/logo cache under Noctalia's plugin data directory. It does not access Akıl Kuran user accounts, send user data anywhere, or use cookies, Firebase credentials, or private source code.