Margin Calendar: a Google Calendar client for desktop and phone

Tauri 2, React 19 and zustand on the front, Rust behind. Rust owns auth,
all HTTP to Google, the SQLite store, the sync loop, recurrence expansion
and timezone maths. TypeScript owns rendering and never talks to Google,
which keeps the content security policy locked to ipc:.

Week, day and agenda views, and no month view: it would be a second layout
engine, and the fit and fold logic that makes a day fit the window without
scrolling is the whole point of the app.

Runs on macOS, Linux, Android and iOS. Desktop catches Google's OAuth
redirect on a loopback port. A phone cannot, and Google rejects loopback
for mobile client types anyway, so it redirects to a custom URI scheme and
needs its own public OAuth clients, which docs/mobile.md covers. Refresh
tokens are sealed with XChaCha20-Poly1305 in the app data directory on
every platform, with no OS credential store in the picture.

On a phone the chrome becomes a top bar and a bottom tab bar, overlays
become sheets, hover affordances become taps, and dragging out an event
waits for a long press. Navigation moves one day at a time everywhere,
a swipe included.

docs/architecture.md

@@ -0,0 +1,133 @@
+# Architecture
+
+Tauri 2, React 19, Vite, TypeScript and zustand on the front, Rust behind. Same stack as
+margin, which means the OAuth flow, the token handling and the build and bundle setup carry
+over rather than being invented again.
+
+The split is strict. Rust owns authentication, all HTTP to Google, the local store, the sync
+loop, recurrence expansion and timezone arithmetic. TypeScript owns rendering and interaction
+and nothing else. The frontend never talks to Google, which keeps the content security policy
+locked to `ipc:` exactly as margin has it.
+
+## Authentication
+
+Lifted from `margin/src-tauri/src/gdrive.rs`, then split in two when mobile arrived. Both halves
+build the same consent URL with PKCE S256 and a CSRF state parameter and open it in the system
+browser through the opener plugin, never an in-app webview: Google blocks the embedded-webview
+flow, and it deserves to be blocked, because a webview the app controls can read the password
+typed into it. They differ only in how the answer comes back.
+
+Desktop binds a listener on `127.0.0.1:0` and catches the redirect on the loopback socket. The
+verifier lives on that listener's stack for the two minutes it is alive.
+
+Mobile cannot do that. iOS will not keep a background listener alive dependably, and Google
+rejects loopback redirects for Android and iOS client types outright, so the redirect is a custom
+URI scheme the OS routes back to the app through `tauri-plugin-deep-link`. There is no listener to
+hold the verifier, the browser is a separate app and this process may be backgrounded while the
+user consents, so the verifier waits in `AuthState.pending` and `handle_redirect` picks it up
+whenever the link lands. It is taken rather than read, so a replayed link cannot start a second
+exchange.
+
+That split forces one more difference. A desktop client is confidential and has a secret; an
+Android or iOS client is public and has none, so `google-credentials.json` carries up to three
+clients and the build embeds the one for the platform it is compiling for. Details and the
+console steps are in [mobile.md](mobile.md).
+
+The scope is `https://www.googleapis.com/auth/calendar` plus `openid email`. Calendar is a
+sensitive scope, so an unverified client shows the unverified-app interstitial and caps at 100
+users. Irrelevant for personal use, relevant the moment this ships the way margin ships.
+
+Refresh tokens never go to disk in plaintext and never into SQLite. They are sealed with
+XChaCha20-Poly1305 in the app data directory, the same way on all five platforms.
+
+There is no `keyring` here, and its absence is deliberate rather than an omission. It has no
+Android backend at all; on macOS it ties an item to the code signature, so an ad-hoc signed build
+gets a new identity on every compile and macOS re-asks for authorization every time; and on Linux
+it is missing on exactly the minimal window managers that run no Secret Service daemon. That left
+one real implementation behind four ways of reaching it. `src-tauri/src/google/secrets.rs` states
+plainly what the file is worth on each platform, which is more on the mobile sandboxes than on a
+desktop home directory.
+
+## Store
+
+SQLite through `rusqlite` with the bundled feature, so there is no system SQLite dependency on
+either platform.
+
+Accounts hold an email and a reference naming the sealed token, never the token itself. The
+column is still called `keychain_ref` from when there was a keychain; renaming it would cost a
+migration and buy nothing. Calendars hold their account, summary,
+colour, selection state, access role, default timezone and their own sync token. Events hold
+the raw Google shape flattened: identity and etag, summary, description, location, start and
+end with their separate timezones, an all-day flag, the recurrence rule set, the pointer back
+to a master plus original start for exception instances, status, and attendees and conference
+data as JSON blobs. An outbox table holds pending writes.
+
+Events are stored as Google returns them with `singleEvents=false`, meaning recurring series
+are one row carrying an RRULE rather than thousands of rows. Expansion happens on read.
+
+## Sync
+
+Incremental sync through `events.list` with a stored `syncToken`, one cursor per calendar,
+`singleEvents=false`, `showDeleted=true`, `maxResults=2500`. The parameter set has to be
+byte-identical across every call in a chain, including the initial one.
+
+The constraint that shapes everything: `timeMin` and `timeMax` cannot be used with
+`syncToken`, along with `q`, `orderBy`, `updatedMin`, `iCalUID` and the extended property
+filters. There is no way to sync a window. The initial full sync pulls the entire calendar
+history, which for an old personal calendar is a few thousand rows and a one-time cost of
+seconds, and is only tolerable because recurring series collapse to single rows.
+
+`nextSyncToken` appears only on the final page, so pages must be walked to exhaustion with
+`pageToken` before anything is persisted. A 410 means the token is dead: drop that calendar's
+rows and its cursor and full-resync it alone, without touching the others. `calendarList.list`
+carries its own sync token for the set of calendars itself.
+
+Polling, not webhooks. Push notifications need a publicly verified HTTPS callback and channels
+that expire every few days, neither of which a desktop app has. Sixty seconds while the window
+is focused, five minutes when it is not. An incremental poll with no changes is a single small
+request against a million-a-day quota.
+
+## Writes
+
+Optimistic. A write lands in SQLite, is marked dirty, is enqueued in the outbox and renders
+immediately; the push to Google happens behind it. Requests carry `If-Match` with the stored
+etag, and a 412 means someone else changed it first, so refetch and surface the conflict
+rather than clobbering. Offline writes queue and drain on reconnect. The outbox is the reason
+the app works on a plane and the reason it never spins.
+
+## Recurrence
+
+The `rrule` crate, which is built on `chrono-tz`. Expansion takes a window and a set of
+masters, generates occurrences, drops any occurrence whose original start matches a cancelled
+or overridden instance, then merges the override events back in at their moved times. The
+frontend asks for a range and receives a flat array of instances; it has no concept of a
+recurrence rule.
+
+Editing a series is three distinct operations. Editing one instance resolves the real instance
+through `events.instances` and patches that, rather than constructing the instance id by hand.
+Editing this and all following truncates the master's rule with an UNTIL and creates a new
+master from the split point. Editing the whole series patches the master. All three are worth
+tests before they are worth UI.
+
+## Time
+
+Every event keeps its own timezone; the grid renders in the local zone. All-day events are
+date-only and must never be shifted into a zone, which is the single most common bug in this
+category of app and deserves a test that runs in a non-UTC zone. DST transitions mean a day is
+sometimes 23 or 25 hours long, which the vertical fit calculation has to accept rather than
+assume away.
+
+## Platforms
+
+macOS uses the overlay title bar with the header row padded for the traffic lights, as margin
+does. Linux has no traffic lights, so that padding is conditional. Linux builds need
+`libwebkit2gtk-4.1-dev` and ship as AppImage and deb.
+
+## Order of work
+
+The sync engine and the grid are the two hard things and neither is proven by the other, so
+the first milestone is authentication, sync and a read-only grid with correct vertical fit.
+Recurrence and timezone correctness come second, with tests, because everything after depends
+on the instance stream being right. Create, edit and delete with the outbox come third.
+Multiple accounts, the command palette and natural language parsing come last, since they are
+the parts that are pleasant rather than load-bearing.

docs/conventions.md

@@ -0,0 +1,89 @@
+# Conventions
+
+This project is a sibling to `../margin` and follows its conventions deliberately rather than
+inventing new ones. When something here is unclear, the answer is almost always "do what margin
+does", and the file to look at is named below.
+
+## Rust
+
+`Result<T, String>` everywhere. No `anyhow`, no custom error enum except `google::api::ApiError`,
+which exists only because the sync engine has to distinguish a 410 and a 412 from everything else.
+
+DTOs crossing the IPC boundary live in `src-tauri/src/dto.rs` and are marked
+`#[serde(rename_all = "camelCase")]`. That file is the contract and is frozen: implementation
+modules add bodies, not fields. Its mirror is `src/ipc.ts`.
+
+Read Google's responses through `google::auth::read_json`, which takes the body to a `String`
+first so the error payload survives into the message. Ported from `margin/src-tauri/src/gdrive.rs:286`.
+
+Heavy synchronous work goes behind `#[tauri::command(async)]` on a synchronous fn, which is
+margin's `pdf.rs:90` trick for getting off the main thread without hand-writing `spawn_blocking`.
+
+Comments are rare and explain why, never what. Match the density in `lib.rs`.
+
+## TypeScript
+
+One zustand store per domain in `src/store/`. No middleware. One selector call per field
+(`useThing((s) => s.field)`, never a destructured object), actions as inline arrow properties, and
+`set((s) => ...)` returning `{}` to no-op. See `margin/src/store/useBackup.ts`.
+
+Async actions use a string phase union (`"idle" | "syncing" | "error"`), never boolean loading
+flags. Errors stringify with `String(e)` and surface as a toast.
+
+Side effects that touch disk, the DOM or Tauri live in a sibling module, never inside the store.
+
+The OAuth connect flow reuses the promise-holding-its-own-resolver pattern from
+`margin/src/store/useBackup.ts:70`: `connect()` returns a promise whose `resolve` is stashed in
+state for a later Tauri event to settle.
+
+Typed IPC wrappers live in `src/api/`, one module per domain, one thin function per command. They
+are already written; add bodies to Rust, not new wrappers.
+
+## CSS
+
+Flat kebab-case class names, not BEM. State is a `data-*` attribute, never an `is-` class.
+
+Every colour, radius and size goes through a token in `src/styles/tokens.css`. If a value is not
+in there, add a token rather than a literal.
+
+Dark mode is `data-theme` on `<html>`, with both palettes defining an identical variable set.
+Never a media query for theme.
+
+Transitions name explicit properties and use `var(--ease)`. Never `transition: all`.
+
+Responsiveness is JS-driven through `useCompact()`, which writes `data-compact` on the root.
+Style against that attribute rather than adding media queries.
+
+`usePhone()` and `useTouch()` write `data-phone` and `data-touch` the same way, and they answer
+different questions. `data-phone` is a window too narrow for the desktop chrome and it governs
+layout; `data-touch` is a coarse pointer and it governs interaction. A tablet is touch and not a
+phone, a narrow desktop window is a phone and not touch, and treating either as a proxy for the
+other is how a hover-only control ends up unreachable. Both are also set by the boot script in
+`index.html`, so the first paint is already the right shape.
+
+A rule that reads "you cannot hover here" belongs on `data-touch`. A rule that reads "there is no
+room for this" belongs on `data-phone` or `data-compact`.
+
+The one exception is the event block, which uses a container query on its own inline size. That is
+deliberate: `data-compact` describes the window, but what decides how many lines of a title fit is
+the block's own width, and in a three-deep overlap cluster that is a quarter of a column. Nothing
+else may reach for a container query without the same kind of reason.
+
+Overlays follow margin's `.overlay` and `.panel` idiom, already in `app.css`, and every one of
+them registers with `useEscapeLayer` from `src/escape.ts` so Escape unwinds the layers in order.
+
+## Icons
+
+Inline Feather-style 24x24 stroke `d` strings passed to `<Icon d={...} />`. There is no icon set
+and no registry, and there will not be one. An icon-only button always carries a `title` with its
+shortcut written in real glyphs.
+
+## Storage keys
+
+Anything in `localStorage` is prefixed `margincal-`, following margin's convention in `theme.ts`
+and `panes.ts`. Keys read before first paint are restored by the blocking IIFE in `index.html`.
+
+## Never
+
+No CSS framework, no component library, no router, no zustand middleware, no directory trees in
+any document, and no em dashes anywhere including code comments.

docs/design.md

@@ -0,0 +1,135 @@
+# Design
+
+A desktop calendar for Google Calendar, macOS and Linux. It exists because Google Calendar
+wastes vertical space you cannot reclaim and surrounds the grid with chrome you never asked
+for. Everything below follows from those two complaints.
+
+## The grid owns the window
+
+There is no permanent sidebar. The mini-month, the calendar list, search and settings are all
+overlays: summoned by a key or a hover, dismissed with Escape, never resident. The only
+persistent chrome is a single header row carrying the date range, the view switcher and the
+current time range. On macOS the traffic lights float over that row, so it costs no extra
+height.
+
+This is the whole point. A 1440p monitor should show a week of your life, not a week of your
+life inside a browser inside a Google header.
+
+## Vertical fit
+
+The grid never scrolls. Row height is derived from the window, so whatever range is visible
+always fits exactly.
+
+The visible range is computed from the events in the span you are looking at: floor to the
+hour before your earliest event, ceil to the hour after your latest, clamped to a minimum of
+eight hours so a quiet week does not render four enormous rows. Empty bands at the top and
+bottom fold into thin strips labelled with their range and a count of anything hiding inside.
+Click or press `z` to unfold one.
+
+The range expands immediately when it needs to, but only contracts when it would shrink by two
+hours or more. Without that hysteresis the axis flickers as you page through weeks, and a
+flickering axis destroys the positional memory that makes a keyboard-driven calendar fast.
+
+Interior gaps stay at full scale. A three-hour hole on a Wednesday afternoon is the most
+useful thing on the screen, because it is where work goes, and folding it automatically would
+make a packed day look identical to an open one. But you can fold one deliberately with `z`,
+and it stays folded across navigation until you unfold it. The fold is per range, remembered
+in local state, not derived from the data.
+
+One consequence worth stating plainly: within the unfolded region the scale is strictly
+linear, so a block twice as tall is an event twice as long, always. That property is why the
+grid is worth having at all, and it is the thing automatic gap-folding would have cost.
+
+## Events on the grid
+
+Overlapping events use the standard constraint model. Sort by start, partition into collision
+clusters, assign each event the leftmost free column within its cluster, then let every event
+expand rightward into columns that stay free for its whole duration. Colliding events end up
+the same width, nothing visually overlaps, and an event that only collides briefly still gets
+most of the day's width.
+
+An event block is a washed neutral surface with a two-pixel coloured edge on the left
+identifying its calendar. Colour never fills the block. This keeps the grid quiet enough to
+read as a shape while still letting you tell work from personal at a glance, and it means the
+app looks like a sibling of margin rather than a different product.
+
+All-day events sit in a fixed band under the day headers, one row tall, with anything that does
+not fit behind a count that expands over the grid. The band's height has to be constant: the axis
+below is solved from whatever height is left, so a band that grew with its contents would change
+the row height as you paged and slide every hour on the grid, which is the same positional memory
+the contraction hysteresis exists to protect. A taller fixed reserve would be the other sin, an
+empty band eating space you cannot reclaim.
+
+## Keyboard
+
+Keyboard-first, mouse fully supported. Drag on empty grid to create, drag a block to move it,
+drag its edge to resize. None of that is second class.
+
+Navigation is `h` and `l` for previous and next day, `H` and `L` for week, `t` for today.
+`j` and `k` move the selection through the events of the focused day. `d`, `w` and `a` switch
+view, and `m` summons the mini-month, since there is no month view for it to switch to. `z`
+folds or unfolds the band under the cursor.
+
+Actions are `c` to create, `Enter` to open the selection, `e` to edit, `x` to delete, `/` to
+search, `Escape` to dismiss whatever is open. `Cmd-K` opens the command palette, which is also
+where creation happens.
+
+Every binding is listed in an overlay behind `?`. Nothing is modal and nothing is chorded.
+Vimcal's ceiling is higher and its users find it confusing, which is a trade worth refusing.
+
+## On a phone
+
+Keyboard-first stops being a design when there is no keyboard, so a phone gets a different set of
+affordances for the same commands rather than a shrunken copy of the desktop ones. The build steps
+are in [mobile.md](mobile.md); the decisions are here.
+
+The chrome inverts. The desktop header holds three groups across a single row and there is no
+arrangement of that which fits 390 points, so the date and the day arrows go to a top bar, the
+views go to a bottom tab bar where a thumb can reach them, and the rest goes into an overflow
+sheet. Overlays become bottom sheets for the same reason: a centred panel puts its buttons where
+the hand is not.
+
+Interaction changes on touch, not on width. Anything that only appeared on hover is always visible
+instead, because a finger cannot hover and an affordance nobody can reach is not an affordance.
+Dragging out a new event waits for a long press, because the alternative is that every tap on an
+empty afternoon starts creating something. A tablet gets these and keeps the week grid; a narrow
+desktop window gets the layout and keeps its mouse behaviour.
+
+Navigation still moves one day at a time. A swipe is one day, never a week.
+
+The week view survives on a phone rather than being hidden, because an overview has value even at
+fifty points a column, but it is an overview: no times on the blocks, one letter for the day name,
+and tapping a day header drops into that day. The day view is what a phone opens on.
+
+What does not change is the premise. The day still fits without scrolling, the grid still owns
+what is left after the two bars, and there is still no month view.
+
+## Creating an event
+
+Press `c` or `Cmd-K` and type. `lunch with sam tue 1pm 45m` creates a 45-minute event on
+Tuesday. The parse is shown live underneath the input as you type, as a plain sentence with
+the resolved date, time, duration and target calendar, so you can see what will be created
+before you commit. If the parse is ambiguous the preview says so rather than guessing
+silently.
+
+`#work` targets a calendar, `at <place>` sets the location, a bare time range like `9-10am`
+sets both ends. Anything the parser does not recognise stays in the title.
+
+Dragging on the grid also creates: drag the range, type the title in place, Enter. Same event,
+different mood.
+
+## Meetings
+
+Attendees and conference links are shown read-only on an event that has them, including who
+has accepted. There is no RSVP flow, no availability finder and no scheduling links. That is
+a deliberate cut, not an oversight, and it can be revisited once the calendar itself is good.
+
+## Visual language
+
+The token layer is lifted from margin unchanged: warm paper surfaces, ink and two softer ink
+tones, hairline borders, a four-step type scale, three radii, one easing curve, light and dark
+driven by `data-theme` on the root. The additions are grid-specific: hour and half-hour rule
+colours, the now-line, the folded-band surface, and a set of eight muted calendar hues chosen
+to sit on warm paper without shouting.
+
+No CSS framework and no component library, same as margin. Hand-written CSS on top of tokens.

docs/mobile.md

@@ -0,0 +1,198 @@
+# Android and iOS
+
+The same Rust core and the same React app, with a different shape of chrome and a different way of
+getting a token back from Google. Nothing is forked: the layout switches on a `data-phone`
+attribute and the OAuth flow switches on `cfg(mobile)`.
+
+## Google will not let you reuse the desktop client
+
+This is the part that cannot be automated away, so do it first or nothing will sign in.
+
+Google issues OAuth clients per platform and refuses one in another's place. The desktop client
+redirects to a loopback port; Google rejects loopback redirects for Android and iOS client types
+outright, and iOS will not dependably keep a listener alive to catch one anyway. So a phone build
+redirects to a custom URI scheme instead, and needs its own client to do it.
+
+Both mobile clients are **public**: no client secret exists, and PKCE is the only thing between an
+intercepted authorization code and a token. That is why the verifier is not optional anywhere in
+`auth.rs`.
+
+In the Google Cloud console, on the same project that already has the Calendar API enabled:
+
+1. Create an OAuth client of type **Android**. It wants the package name, which is
+   `studio.margin.calendar`, and the SHA-1 fingerprint of the certificate that signs the build.
+   For a debug build that is the shared debug keystore:
+
+   ```
+   keytool -list -v -keystore ~/.android/debug.keystore \
+     -alias androiddebugkey -storepass android -keypass android
+   ```
+
+   A release build is signed with a different key and needs its fingerprint added too. An APK
+   signed by a key Google has not been told about fails at consent, not at build.
+
+2. Create an OAuth client of type **iOS**. It wants the bundle identifier, which is also
+   `studio.margin.calendar`.
+
+3. Put both client ids in `google-credentials.json` alongside the desktop one, matching
+   `google-credentials.example.json`:
+
+   ```json
+   {
+     "installed": { "client_id": "...", "client_secret": "...", "...": "..." },
+     "android": { "client_id": "YOUR_ANDROID_CLIENT_ID.apps.googleusercontent.com" },
+     "ios": { "client_id": "YOUR_IOS_CLIENT_ID.apps.googleusercontent.com" }
+   }
+   ```
+
+   The file is gitignored and embedded at build time. A build with no `android` or `ios` block
+   compiles and then says so at runtime rather than failing to compile, which is the same bargain
+   the desktop client already had.
+
+## The redirect schemes
+
+Android redirects to `studio.margin.calendar:/oauth2redirect`. That is the package name, which is
+Google's documented form for an Android client, and being known at build time means it can sit in
+`AndroidManifest.xml` permanently rather than being pasted in per install.
+
+iOS gets no such choice. Google requires the reversed client id, so the scheme is only knowable
+once your client id is: take the client id, drop the `.apps.googleusercontent.com` suffix, and
+prefix `com.googleusercontent.apps.`.
+
+Register it in `src-tauri/tauri.conf.json`, as a second entry in the deep link plugin's scheme
+list:
+
+```json
+"deep-link": {
+  "desktop": { "schemes": ["studio.margin.calendar"] },
+  "mobile": [{ "scheme": ["studio.margin.calendar", "com.googleusercontent.apps.YOUR_ID"] }]
+}
+```
+
+Not in `Info.plist`. Editing that by hand looks like it works and then silently stops working: the
+plugin's build script rewrites `CFBundleURLTypes` wholesale from this config on every build, and
+when the `mobile` array is empty it deletes the key outright. That one empty array is why the
+callback was dead on both platforms at first, so if a deep link ever stops arriving, look here
+before anywhere else.
+
+If the console shows you something different from either default, put it in the client's block in
+`google-credentials.json` as `redirect_uri` and it wins over both. Whatever you put there still
+has to have its scheme registered above, or the OS has no reason to hand the link to this app.
+
+## Toolchain
+
+iOS needs Xcode and the iOS Rust targets:
+
+```
+rustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
+```
+
+Android needs the SDK, an NDK of r25 or newer, a JDK that the generated Gradle build accepts (21
+works, 25 does not), and the four Android Rust targets:
+
+```
+rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
+export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools
+export NDK_HOME=$ANDROID_HOME/ndk/27.2.12479018
+export JAVA_HOME=/opt/homebrew/opt/openjdk@21
+```
+
+## Building
+
+```
+pnpm tauri ios init          # once, generates the Xcode project
+pnpm tauri ios dev           # simulator, with the Vite dev server
+pnpm tauri ios build
+
+pnpm tauri android init      # once, generates the Gradle project
+pnpm tauri android dev       # emulator or attached device
+pnpm tauri android build
+```
+
+The generated projects are committed. Re-running `init` overwrites them, so check afterwards that
+`MainActivity.kt` still publishes the window insets, since nothing else on Android does.
+
+Both `dev` commands start Vite themselves and fail outright if port 1430 is already taken, which
+it will be if a browser dev server is still up. Kill it, or pass a different port through
+`--config`.
+
+Three failures that look like bugs and are not. Xcode refusing to build with "Entitlements file
+was modified during the build" is a stale mtime in DerivedData, fixed once by deleting
+`~/Library/Developer/Xcode/DerivedData/margin-calendar-*`. An Android run panicking with "failed
+to build WebSocket client, Connection refused" is a stale
+`$TMPDIR/studio.margin.calendar-server-addr` pointing at a dead port; delete it. And an emulator
+that will not boot by name usually means `avdmanager` and `emulator` disagree about where AVDs
+live, which `ANDROID_AVD_HOME` settles.
+
+Finally, an empty calendar on a device is correct. The browser fixture is gated on not being
+inside Tauri, so on a phone the real backend answers and there is nothing to show until an account
+is connected. Events without signing in only ever happen in a browser.
+
+## What is different on a phone
+
+The desktop header carries three groups of controls across one row, which does not fit in 390
+points. Under `data-phone` it becomes a top bar with the date and the day arrows and a bottom tab
+bar with the views, and everything the trailing icon row used to hold moves into an overflow
+sheet. Overlays become bottom sheets. Both bars pad themselves out of the way of the notch and the
+home indicator with `env(safe-area-inset-*)`.
+
+Under `data-touch`, which a tablet gets and a narrow desktop window does not, interaction changes
+rather than layout. Anything that only appeared on hover is always visible instead, because a
+finger cannot hover. Dragging out a new event waits for a long press, because on a touchscreen the
+alternative is that every tap on an empty afternoon starts creating something.
+
+Navigation still moves one day at a time. A swipe is one day, not one week.
+
+Both attributes are also set by the boot script in `index.html` before first paint, so a phone
+does not render the desktop layout for a frame and then jump.
+
+## Keeping out from under the system bars
+
+`--safe-top` and `--safe-bottom` are `env(safe-area-inset-*)` by default, which is correct on iOS
+and wrong on Android in a way that is easy to miss. Android's WebView derives those values from the
+display cutout alone and never from the system bars, so it reports 0 at the bottom while the
+navigation bar really occupies 24dp of gesture pill or 48dp of buttons, and the tab bar renders
+underneath it. `targetSdk` is 36, so edge-to-edge is mandatory and there is nothing to opt out of.
+The top only looked right on a test device by luck, because that device had a cutout; a phone
+without one would have tucked the top bar under the status bar for the same reason.
+
+So Android measures the bars natively. `MainActivity.kt` reads `systemBars() or displayCutout()`
+from `WindowInsetsCompat`, exposes them over a JavaScript bridge, and re-fires on every inset
+change, which covers rotation, the keyboard, and switching between gesture and button navigation
+live. `src/safeArea.ts` converts device pixels to CSS pixels and writes the two variables onto the
+root, where they beat the `env()` defaults. Off Android the bridge is simply absent and the
+defaults stand, so iOS and desktop are untouched.
+
+Two consequences worth knowing. `tauri android init` regenerates `MainActivity.kt`, and nothing
+else on Android supplies these values, so check the bridge is still there after re-running it.
+And installing the inset listener makes `env(safe-area-inset-*)` read 0 inside that WebView, which
+does not matter only because those two token lines are the sole consumers and the bridge overrides
+both with better numbers. Anything new that reaches for `env()` directly on Android will get zero.
+
+iOS needed one line of native code for the same class of problem, in the opposite direction.
+
+UIKit hands a scroll view the safe areas as content insets unless told otherwise, and wry never
+tells it otherwise: it touches the scroll view only to switch `bounces` off. WebKit then lays the
+page out in what is left. On an iPhone 17 Pro that meant a layout viewport 778pt tall against an
+874pt screen, still anchored at y 0, so the bottom 96pt of the display was outside the page
+altogether and showed as a dead band of shell colour under the tab bar. `body` is
+`position: fixed`, so nothing could paint down there whatever the stylesheet said.
+
+`stop_uikit_shrinking_the_viewport` in `lib.rs` sets `contentInsetAdjustmentBehavior` to `never`
+through `with_webview`, which gives the page the whole screen back. The insets are not lost, they
+arrive as `env(safe-area-inset-*)` instead, which is where both bars already read them from.
+
+Worth knowing before anyone tries to solve that in CSS, because it looks like a CSS problem and
+the obvious fix is worse than the bug. While the viewport was short, `100dvh` was the only unit
+reporting the real box; `vh`, `svh` and `lvh` all reported the full screen. Sizing the root
+`100svh` therefore did not reclaim the bottom of the screen, it laid the tab bar out past the clip
+where it was invisible and, less obviously, untappable. The root is `height: 100%`, which inherits
+whatever the box is and cannot drift if the native line ever regresses.
+
+## Limits worth knowing
+
+There is no auto-updater and no process restart on mobile: the store is the update channel, and
+both plugins are compiled out rather than merely hidden.
+
+The initial sync pulls the whole calendar history, because Google forbids `timeMin` alongside a
+`syncToken`. That is already the desktop behaviour and it is slower on a phone radio.

docs/setup.md

@@ -0,0 +1,55 @@
+# Setup
+
+## The Google OAuth client
+
+The app talks to Google with its own OAuth desktop client, which is not in this repo and cannot
+be. You need to make one before the app can connect to anything.
+
+1. In the Google Cloud console, enable the Google Calendar API on a project.
+2. On the OAuth consent screen, add the `https://www.googleapis.com/auth/calendar` scope. It is a
+   sensitive scope, so an unverified client shows an interstitial and caps at 100 users. That is
+   fine for personal use and matters the day this ships more widely.
+3. Create an OAuth client ID of type **Desktop app**. That type permits the loopback redirect, and
+   Google allows installed clients any loopback port, so there is nothing to register. This client
+   is for macOS, Linux and Windows only; phones need their own, see [mobile.md](mobile.md).
+4. Save the downloaded JSON as `google-credentials.json` in the repo root. It should match the
+   shape of `google-credentials.example.json`: an `installed` object with `client_id`,
+   `client_secret`, `auth_uri` and `token_uri`.
+
+The real file is gitignored. The build embeds it when it is present and embeds the example when it
+is not, so a fresh clone builds and then tells you at runtime that Google Calendar is not set up
+yet, rather than failing to compile.
+
+Building for a phone needs a second and third OAuth client, because Google will not accept a
+desktop client from Android or iOS. That, and the toolchain, is in [mobile.md](mobile.md).
+
+Refresh tokens never go to disk in plaintext and never into the SQLite database. They are sealed
+with XChaCha20-Poly1305 in the app data directory, identically on all five platforms, by
+`src-tauri/src/google/secrets.rs`. That file states what the encryption is worth where: on iOS and
+Android the app sandbox is the real boundary and this is defence behind it, while on a desktop
+anyone who can read your home directory can read the token. There is no OS credential store in the
+picture and nothing will ever prompt you for keychain access.
+
+## Building
+
+```
+pnpm install
+pnpm tauri dev
+```
+
+`pnpm test` runs the frontend suites, `cargo test` inside `src-tauri` runs the Rust ones. Both
+should be green before anything is considered done.
+
+## Linux
+
+Building needs `libwebkit2gtk-4.1-dev`, `libgtk-3-dev`, `librsvg2-dev`,
+`libayatana-appindicator3-dev` and `libxdo-dev`. Build on the oldest baseline you intend to
+support, which is Ubuntu 22.04 or Debian 12, because the resulting binary will not run on anything
+older than the glibc it was linked against.
+
+## Where the data lives
+
+`~/Library/Application Support/studio.margin.calendar/` on macOS and
+`~/.local/share/studio.margin.calendar/` on Linux. The bundle identifier is deliberately distinct
+from margin's, so the two apps never share a directory. Deleting that directory resets the app;
+the accounts reconnect and sync pulls everything back.