From 1e4bed5bbb23454205012bbc2f0b8d4e0190533e Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Wed, 11 Nov 2026 21:56:41 +0700 Subject: [PATCH] docs(theme): push a theme record only when its keys differ from the server copy --- .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 3998f82d5e..c1bc309070 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 a record dirty when the keys it owns changed, or when this Mac holds no copy of it and the theme sets its keys. Each record pushes whole, so a re-push of keys the edit did not touch would revert another Mac's edit of them. While the first full pull is pending, theme records wait for it, as the seed does. 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 every record the theme sets. A push sends a record only when the keys it owns differ from this Mac's last copy of it from the server, or this Mac holds none: each record pushes whole, so a re-push of keys the edit did not touch would revert another Mac's edit of them. A theme kept as a copy beside a synced one drops the deletions queued for its old id. While the first full pull is pending, theme records wait for it, as the seed does. 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.