From 2b7cd110ee717603c72dc2a3e0947a0d617980f9 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Wed, 11 Nov 2026 21:21:14 +0700 Subject: [PATCH] docs(theme): upload a theme's base record on every edit --- .claude/rules/theme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/rules/theme.md b/.claude/rules/theme.md index b6a3239f1c..db07cbee68 100644 --- a/.claude/rules/theme.md +++ b/.claude/rules/theme.md @@ -56,7 +56,7 @@ paths: ## Sync - **Each user theme syncs as the `AppSettings` record `theme.`**, holding only its schema 3 keys, encoded at schema 3, so the previous stable reads and edits it. A theme that sets a key schema N introduced also syncs `themeSchema.`, holding the whole theme at schema N. An older Mac skips a record it cannot read but keeps it as the merge base, so a single record at the newer schema would be overwritten by its next edit. -- **Each record owns its keys.** Applying `theme.` keeps the local theme's keys newer than 3, and applying `themeSchema.` changes only the keys schema N introduced. `theme.` also owns the name, author and appearance. A user edit marks dirty only the records whose keys it changed, since each pushes whole and a stale copy would revert another Mac's edit. A trash marks both deleted once the trash lands, an undo of it keeps no deletion it does not replace, and a load or migration marks nothing. Built-ins never sync. +- **Each record owns its keys.** Applying `theme.` keeps the local theme's keys newer than 3, and applying `themeSchema.` changes only the keys schema N introduced. `theme.` also owns the name, author and appearance. A user edit marks `theme.` dirty, which changes nothing on the server unless its keys changed or the server lacks it. It marks `themeSchema.` only when the keys schema N introduced changed or the record was never uploaded, since that record holds the whole theme and a stale copy would revert another Mac's edit. A trash marks both deleted once the trash lands, an undo of it keeps no deletion it does not replace, and a load or migration marks nothing. Built-ins never sync. - **A synced theme is untrusted.** `ThemeCatalog.applyRemote(category:data:)` checks the category id (never a built-in), a 64 KB cap, nesting depth, a full decode and the file id, and never writes over bytes it has not read. A validation failure is a logged skip; only a disk failure returns `.failed`, which withholds the change token so the pull replays. A remote delete trashes the file through `removeWithoutSync(ids:)`. - The light and dark theme ids sync. The appearance mode and fonts are device-local, and a received `appearance` record never changes them. - `SyncCoordinator.themeContentKind` names `ThemeSchema.current`, so a Mac upgraded past a bump refetches the zone once. After the first full pull, only local themes the server lacks are marked dirty, once.