dsh-background-by-model 0.5.5 → 0.7.1

package/CHANGELOG.md

@@ -1,6 +1,53 @@
 # Changelog
 
-> The full release history lives here; the two most recent releases (v0.5.5 / v0.5.4) are also listed in [README.md](./README.md#recent-optimizations).
+> The full release history lives here; the two most recent releases (v0.7.1 / v0.7.0) are also listed in [README.md](./README.md#recent-optimizations).
+
+## v0.7.1
+
+- **The theme color moved down to the image** — a rule is a rotation through several pictures, and pictures collected for different moods do not share one accent. Every image now carries its own `color: [h, s, l] | null`, and the whole color section — wheel, numeric inputs, inspiration palette, **Extract from this image**, eyedropper and **Follow system theme** — edits the image selected in the filmstrip. The controls gained one line that names their target ("Applies to the selected image: 2 / 3") and the filmstrip marks the images that already carry a color of their own (with the hex on hover), because a section that silently retargets is exactly how "I changed the color and nothing happened" starts. No new control and no layout change: the filmstrip was already the way to pick a picture, and it was already where framing is chosen.
+- **A rule's own `color` now means exactly one thing: what an image-less rule paints** — it is deliberately NOT a default for the rule's pictures. An image with no color of its own follows the **system theme** rather than inheriting the rule's, which is what makes a rotation through a green picture, a red one and a system-themed one expressible at all: with inheritance, clearing a picture's color would only hand it back to the rule's, and the clear button would look broken (there would also be no way to reach the system theme for a rule that has both a color and pictures). Clearing one image's color therefore clears only that image; the rule keeps its own, ready for the state where it is the only thing left to paint. The panel's two branches follow the same rule: with an image to address, the controls edit the image; with `images: []`, they edit the rule.
+- **Nothing loses its theme on upgrade, and the distinction is one key** — an image entry written before this release has no `color` key at all, and that is the whole test `normalizeImage` uses: a missing key means "this picture never had a color of its own", so the rule's color is lifted onto it (once, in the shared sanitizer, so both halves lift identically and the file heals on the first write); an explicit `null` means "cleared on purpose" and is never re-inherited over. That is also why every write emits the key even when the value is null — writing "no color" as an absent key would re-inherit the rule's color on every single load. A config predating the field therefore looks identical after the upgrade, and the pre-0.7 single-`slot` shape goes through the same lift (synthesized rather than read).
+- **A rotation step re-emits the interface palette, and that is the bug this feature would otherwise ship with** — the step only repainted the wallpaper, so a per-image color existed in the config and in the panel while the interface behind it kept the previous picture's palette until *something else* re-ran an apply: dragging the color wheel, or switching models. That is the symptom this plugin already had once, verbatim ("it only updates when I touch the color wheel"), so the palette apply is now one function (`applyPalette`) called by both a model switch and every step of the rotation — the timer's tick and the manual **Next image** button share the single `paintImage` funnel that paints a step. `pnpm check:repaint` fails if either `paintImage` or `applyActive` stops going through it, or if the palette stops reading the color in force (`activeColor`: the painted image's color, else the rule's).
+- **Holidays carry their palette per image too** — a festival's fixed color is written on the holiday *and* on its image, and `normalizeHolidayRule` forces both from the definition on every read (a hand-edited value in either place is replaced). The shape is therefore ready for a holiday that rotates through several pieces of art with a palette each, as a change to `HOLIDAYS`, its assets and the node half's slot→asset map rather than a second code path in the render layer.
+- **The config shape moved to 4, and an older host still cannot eat a profile** — `images[].color` is unknown to a schema-3 `normalizeImage`, which REBUILDS each image entry from the keys it knows: the color would live in memory until the next reload and then be gone, silently and with nothing in the host log to explain it. `SCHEMA_VERSION = 4` is published on every `read`, and the client's `>=` comparison puts a host announcing less into the hold-writes path, which logs once and says so in the panel ("restart DSH"). Theme exports move to format 5; 4 and older still import, with the lift above supplying the colors they never had.
+- **A rule with no picture has exactly one upload target** — the big empty preview tile *is* the button now (a real `<button>`, so it is focusable and keyboard-reachable; click it or drop files onto it), and the filmstrip is not rendered at all while the rule holds nothing: it contained nothing but a second "add image" tile, and a filmstrip is a list of pictures — a state with none does not have one. The drop handler moves up with it rather than disappearing, because hiding the strip would otherwise take drag & drop away from the state every rule starts in. Nothing else moved: the labelled **Add images** / **From URL** buttons stay where they were, the empty-state sentences are unchanged, and with pictures present the preview is still deliberately inert (dropping on the strip adds, and *replace* stays an explicit labelled action, which is what keeps a preview from swallowing a click the user did not mean).
+- **Gates** — `check:node` gained the per-image color shape end to end through the real RPC handler: the lift in both directions (an absent key inherits the rule's color, an explicit `null` does not), independent colors surviving the round trip in order, holidays forcing both copies, the announced schema moving to 4, and `null` landing on disk as a key rather than as an omission. `check:repaint` gained the palette-on-a-rotation-step section above, and `setImageColor` — the new write path — is now one of the actions it requires to sample the winner and close with `repaintIfMoved`. `check:ui` covers the three new strings and the two new classes (`.dab-strip-dot`, `.dab-rule-thumb-add`), as it covers every other one.
+
+## v0.7.0
+
+- **Multi-image rotation, per rule — and off by default** — a rule now owns an ordered list of images (`images: [{ slot, bgState }]`) and can cycle them on its own rhythm: 10 s / 30 s / 1 min / 5 min / 30 min / 1 h, or any custom dwell from 5 s to 24 h, **in order** or **shuffle**. It ships OFF because rotating spends real bandwidth, memory and battery, and a default that quietly animates a wallpaper nobody asked to animate is a default that decided for the user.
+- **A second trigger that needs no timer at all** — *also step on a model switch* advances the image once every time the model changes and lands on that rule. For a rule that should simply look different each time, that is the whole feature: nothing is scheduled, nothing wakes up, and the image only changes when the user does something.
+- **Shuffle never lands on the image already on screen** — the picker is uniform over every index *except* the current one, because a tick that leaves the picture unchanged is indistinguishable from a tick that never fired — the one failure this feature could produce with no error anywhere. `pnpm check:rotation` walks the whole support of the roll for lists of 2, 3 and 7 images rather than sampling it once, and also pins the sequential walk's wrap, out-of-range and fractional indices, and that "rotating" is never claimed for a rule with fewer than two images or a non-finite interval.
+- **One timer for the plugin, aimed at the active rule, re-armed by signature** — a timer per rule would burn wakeups on rules that are not painting anything, and only one rule can be on screen. It is (re)armed only when the signature of its own inputs changes — rule id, enabled flag, interval, order, image count, tab visibility — so the dozens of full re-applies a slider drag triggers can never restart the dwell (with a naive "re-arm on apply", dragging the opacity slider for 30 seconds would mean the rotation never advances during it). A hidden tab stops the rotation with the pixels and resumes on a fresh interval, instead of painting three times into a tab nobody is looking at.
+- **The picture changes; the rule does not** — theme color, layout mode, wallpaper opacity and blur stay the rule's, and the transition is the same two-layer cross-fade a model switch already used. A rule can ask for a longer blend than a switch, or `fadeMs: 0` for a hard cut — which is kept as a real value rather than read as "absent".
+- **Framing moved onto the image, where it belongs** — a crop is a property of a picture: two wallpapers of different aspect ratios share the rule's mode, color, opacity and blur, but one `fit` framing computed for the first is simply wrong for the second. Each image carries its own `bgState` and the background editor edits the image selected in the strip.
+- **The single thumbnail became a filmstrip** — add several images at once (**multi-select**, **drag & drop**, or **one URL per line**, fetched sequentially so N downloads do not interleave with no progress to show), click one to edit it, reorder it, promote it to **first** (which is what the rule paints when nothing rotates), **replace this image** in place (which keeps its position in the rotation, so it is labelled apart from adding), or remove it.
+- **A rule may hold NO image, and that has to be a real state** — the first cut of this feature refused to remove a rule's last picture and cleared its bytes "instead", which left the entry itself behind: a blank tile at position 1 of the filmstrip that could never be deleted, so the next upload landed at position 2 and the rule kept painting nothing while the preview showed an empty frame. Removing the last image now empties the list. A brand-new rule starts in that state too (no slot is allocated until the first picture), and a hand-edited list whose entries are all unusable lands in it rather than being conjured back into a broken slot. Only a rule that names no image anywhere — no list, no legacy slot — is dropped by the sanitizer.
+- **A rule with no image left keeps painting from its theme color** — an empty list is not "this rule is off", which is what the first cut made of it: usability only asked whether an image was there, so a rule whose pictures had all been removed **stopped matching altogether** — its own theme color, the wheel, the swatches and the clear-to-system-theme button all became decoration (the reported symptom was "the theme color does nothing") — and the models it used to match were quietly handed to the **next** rule: empty the fallback rule and another model's wallpaper appears. Usability is now *an image, or a theme color of its own* (`ruleCanPaint`): such a rule still matches, still serves as the fallback, and simply paints the interface instead of a wallpaper; only a rule with neither (a freshly added one) is skipped. The card's copy now says which of the three real states it is in — no image but a color, neither, or an image whose bytes have not arrived — where one sentence used to claim "this rule has no image" for all three, and the "extracts from this image" hint no longer appears when there is no image to extract from.
+- **Every edit that can move the winner takes effect at once, and only an edit that cannot may skip the repaint** — `color`, `enabled` and `match` all feed which rule wins, but each write path asked its own narrow question ("is this the rule that is painting right now?") before re-running the resolution, so only an edit to the rule that was *already* winning repainted. The edits that are not already winning are exactly the ones that **create** the winner: the first picture of a rule that was empty (which is what makes it paintable at all — see `ruleCanPaint`), and the first or auto-extracted color landing on it. Those landed in the config and in the panel's own readout while the interface behind it kept the previous rule, which was reported as "the update is never timely, it only appears when I move the color wheel or switch models" — dragging the wheel or a model switch was what finally re-ran the resolution. Every path now samples the winner before its mutation and compares it after (`repaintIfMoved`, over the pure `shouldRepaint` in `src/client/repaint.ts`), which also repairs a tracker that had gone stale: an edit to a rule that *is* the winner repaints even if the page never recorded it as active. `pnpm check:repaint` walks that decision's truth table — both directions of the winner moving, and the cases that must stay cheap — and fails if any of the nine write paths in the entry file — the auto-extraction that lands after an upload included — stops asking it. The live check that pinned this down drove a throwaway rule through the exact sequence (create empty → move to the top → upload one picture → touch nothing): with the old test the paint never moved until something else did, with this one it moved in ~280 ms, and the picture's own auto-extracted color came with it.
+- **An older host process can no longer eat a profile — the check is a version comparison, which is why the shape moved to 3** — the browser half and the node half are loaded separately, so updating the package and merely refreshing the page can pair a NEW client bundle with a host process still running the PREVIOUS node half. That older sanitizer knows nothing about `images` and drops every rule that has one — silently, on the first slider drag. The node half therefore publishes the config shape it writes (`schema` on every `read`), and a client that finds an older answer **holds every config write** (one funnel, `canWriteConfig` in `src/client/rpc.ts`), logs once, and says so in the panel: "restart DSH". Edits that silently do not persist are worse than edits that visibly wait for a restart; edits that silently delete rules are worse than both. During 0.7.0's own development this gate did let one through: the version was 2, and the running 0.7 node half reported `schema: 2` while being a build from **before the empty-rule fix**, so a write that emptied a rule was allowed through and the host erased those rules from disk. The number therefore now means "**an empty image list is legal**" (`SCHEMA_VERSION = 3`), not merely "rules carry `images`": any host announcing less than that lands in the hold-writes state.
+- **An emptied rule and an upload after it** — the picture you add is the picture you are then looking at (the card moves its selection to the first newly added image, and the strip, the big preview and the position readout all follow), instead of leaving the panel showing whatever used to be selected.
+- **Only the images that are needed are loaded** — boot hydrates each rule's **first** image, which is exactly what it hydrated per rule before multi-image existed, plus today's holiday and the image the current model paints. The rest arrive when a card is expanded or when the rotation is about to need one. Hydrating every image of every rule would mean twenty full-size data URLs over this plugin's RPC channel before the first frame on a five-rule setup with four pictures each; the slot list the store reports is likewise no longer hydrated, because an orphaned slot nothing references has no card to appear on.
+- **An older host process can no longer eat a profile** — see the version-comparison entry above: the shape's version number is what a stale host is judged by, and it now stands for "an empty image list is legal" as well.
+- **Older configs still load, and older exports still import** — `normalizeRule` accepts both shapes: a rule's single `slot`/`bgState` pair is lifted into `images: [{ slot, bgState }]` on read, duplicates within a rule are dropped, and an unusable slot is dropped. Theme exports move to **format version 4** and now carry, and restore, every image of every rule rather than just the first; version 3 files still import.
+- **Per-image slots are independent, and removing a rule releases only what it owns** — a rule with three images owns three `modelbg-<slot>` files; `nextSlot` scans every slot in the config (rules *and* holiday entries) so a second image can never collide with an existing one, and deleting a rule reclaims each of its slots only when nothing else references it.
+- **The node half reports nested drift too, and migration writes the new shape** — `warnUnknownConfigKeys` now compares `rules[].rotate` and `rules[].images[]` one level deeper, which is where a field that only the client bundle knows would otherwise disappear in silence, while the legacy `slot`/`bgState` names are explicitly exempt because the sanitizer lifts them on purpose. The pre-0.3 migration writes an image list directly instead of leaving a legacy shape on disk until the first write.
+
+## v0.6.0
+
+- **Holiday backgrounds — one switch, not a settings block** — On 中秋节 and 国庆节 the wallpaper switches to that holiday's own image, with that holiday's own fixed theme color, and switches back the next morning. It ships ON, and the **only** UI it has is a single switch on the **Config** page. There is deliberately no card per holiday, no thumbnail and no image picker — the panels that briefly lived there made the feature read as something the user is expected to configure, which is exactly what it is not.
+- **The switch is the off-ramp, and only an explicit `false` takes it down** — a config written before the feature existed, or one whose switch was never touched, keeps working.
+- **A holiday with nothing to paint falls through instead of blanking the background** — the override needs all three of: the switch, a window that contains today, and actual bytes in that holiday's slot. The last one is the point — a switched-on holiday with no image leaves the model rules in charge.
+- **中秋 is lunar, 国庆 is fixed, and both are read in Asia/Shanghai** — 中秋 is 农历八月十五 and moves across the Gregorian calendar (2024-09-17, 2025-10-06, 2026-09-25, 2027-09-15 …); National Day is the fixed October 1–7 window. The calendar comes from the browser's own ICU (no dependency at all). The zone is **pinned rather than taken from the machine**: the lunar day rolls over at Beijing midnight, so reading "today" off a UTC clock puts the festival on the wrong day for most of the planet — the day-boundary behaviour is pinned by a test at Beijing 23:59 / 00:01.
+- **A leap eighth month cannot drag the festival a month late** — ICU marks a leap month by suffixing `bis`, so an exact `month === '8'` test is what keeps 中秋 on the **regular** eighth month. Checked against every leap-eighth-month year in 1900–2100 (1900, 1957, 1976, 1995, 2052, 2071, 2090): in 2052 the plugin fires on **2052-09-07**, never on the `8bis` fifteenth that falls in October that year.
+- **中秋 wins the overlap with 国庆** — the two do collide (2025-10-06 was both). A single precise day is the better answer than one day inside a seven-day window.
+- **The wallpapers ship inside the package, at one twelfth of the source art: 8.37 MB → 729 KB** — native resolution, WebP q80 (`中秋节` 1856 KB → 228 KB, `国庆节` 6716 KB → 500 KB). The tarball goes **401 KB → 1.12 MB**, and because the files are already-compressed images gzip cannot shrink them further — that is the entire cost of the feature, and the reason they are not shipped raw (raw would be a 21× heavier install, and every boot would then push a 6.7 MB base64 payload through the plugin's own RPC channel).
+- **The wallpapers belong to the package, and nothing can replace them** — a holiday slot is read-only: the node half serves the bundled asset and never consults the data directory for it, and writing, deleting or URL-fetching into such a slot is refused. A file planted there is ignored by every read, which is what keeps the egg an egg instead of a setting.
+- **An unused holiday costs nothing — and neither does an unused DAY** — with the override on by default and invisible, boot fetches only the holiday that can actually paint *today*; on any other day the 729 KB is never read at all. The rollover tick fetches the art if midnight lands *on* a holiday, since boot had no reason to. The node half looks the bundled file up lazily rather than loading it with the plugin.
+- **The holiday theme colors are constants, not something read off the art** — 中秋 paints in `#384A77` and 国庆 in `#FFF6EB`: quoted as hex in the holiday definition, beside its slot and its wallpaper, converted to the rule shape's `[h, s, l]` by the shared schema, and forced on every read — so a hand-edited `color` in `theme-config.json` is replaced by the definition's on load. The extraction pass that decoded a full-size festival photo to re-derive a hue that was always going to be the same one is gone, and with it the "has this image been tried yet" bookkeeping; the palette is now a design decision that costs nothing at boot.
+- **Theme exports carry rules only** — the holiday wallpapers are not in `dsh-background-by-model-theme.json`. They ship with the package, so exporting them would add ~970 KB of base64 to every file to move bytes that every install already has, into slots that refuse them anyway.
+- **Two dependency-free checks now guard the parts that fail silently** — `pnpm check:holiday` (`scripts/holiday-check.ts`) pins the two windows, the Beijing day boundary, the leap-eighth-month behaviour, and the four gates `pickHoliday` applies before a holiday may take over; `pnpm check:ui` (`scripts/ui-strings-check.ts`) fails on a `t('…')` key missing from either dictionary, on a `dab-…` class with no rule in the stylesheet, and on a dictionary entry nothing references any more. A third, `pnpm check:node` (`scripts/node-half-check.mjs`), drives the BUILT node half through its real RPC handler with `DSH_HOME` pointed at a throwaway directory — so it covers the persistence layer without ever touching a real `~/.dsh`: the holiday block through the shared sanitizer, the packaged wallpapers served out of an empty slot, a holiday slot refusing writes, deletes and URL fetches while a file dropped into it is ignored, an ordinary rule slot still writing and deleting, and a hand-edited config unable to point a holiday at another rule's image. All three run on plain `node` (≥ 22.6 strips the types itself), so they need no dependency, no transformer and no browser, and `pnpm test` now runs them. The decision itself — `pickHoliday` — was extracted out of the plugin's apply closure into `src/holiday.ts` precisely so it could be tested at all.
+- **`check:ui` immediately retired ten strings that had been dead since earlier releases** — `close`, `ruleMatchLabel`, `ruleFraming`, `ruleFramingLocked`, `colorHint`, `swatchTitle`, `hexCaption`, `extractColor`, `extractNoWp`, and the `holidayPreview` this release had just added.
 
 ## v0.5.5
 

package/CHANGELOG.zh.md

@@ -1,6 +1,52 @@
 # 更新日志
 
-> 这里保留完整的历史记录；最近两个版本（v0.5.5 / v0.5.4）同时列在 [README.zh.md](./README.zh.md#近期优化) 里。
+> 这里保留完整的历史记录；最近两个版本（v0.7.1 / v0.7.0）同时列在 [README.zh.md](./README.zh.md#近期优化) 里。
+
+## v0.7.1
+
+- **主题色下放到图片** —— 一条规则是一组图片的轮换，而这些图往往是为不同心情收的，不该共用一个强调色。每张图现在带自己的 `color: [h, s, l] | null`，整个调色区——色轮、数值输入、灵感色板、「从本图提取」、吸管、「跟随系统主题」——作用于**胶片条里选中的那张图**。控件上方多了一行写明目标（「作用于选中的图片：2 / 3」），胶片条标出哪些图已经各自有颜色（悬停显示色值），因为一个会悄悄换目标的区块，正是「我改了颜色却没反应」的开端。没有新控件、也没有布局改动：胶片条本来就是选图的入口，也本来就是逐图取景的入口。
+- **规则自己的 `color` 只剩一个含义：一张图都没有时它画什么** —— 它刻意**不是**该规则图片的默认值。没有自己颜色的图**跟随系统主题**，而不是去继承规则色；正是这一点才让「绿的、红的、跟随系统主题」这样一组轮换可以表达——若改成继承，清空某张图的颜色只会把它交还给规则色，「跟随系统主题」按钮看起来就成了失效的按钮（而且一条既有颜色又有图片的规则将无处抵达系统主题）。所以清空某张图的颜色只影响那一张；规则自己的颜色留着，等「只剩它能画」的那个状态。面板的两个分支遵循同一条规则：有图可指就编辑图，`images: []` 就编辑规则。
+- **升级不丢主题色，而区分只靠一个键** —— 这个版本之前写下的图片条目**根本没有** `color` 键，这就是 `normalizeImage` 的全部判据：缺键 = 「这张图从来没有自己的颜色」，于是规则色被抬升到它身上（只做一次，且在共享 sanitizer 里做，两半边行为一致，文件也会在第一次写入时自愈）；显式 `null` = 「主动清空过」，任何时候都不会被重新继承覆盖。这也是为什么每次写入都会带上这个键、哪怕是 null——把「没有颜色」写成缺键，等于每次加载都把规则色继承回来。因此这份字段出现之前的配置升级后观感完全一致，0.7 之前那对单图字段（`slot` / `bgState`）也走同一次抬升（只是那一条是构造出来的，不是读出来的）。
+- **轮换每一步都重发界面调色板，否则这个功能一出生就带着那个 bug** —— 换图原本只重画壁纸，于是「逐图主题色」只存在于配置和面板里，界面配色要等**别的**事情顺手重跑一次 apply 才跟上：拖动调色盘，或者切换模型。这正是这个插件已经踩过一次的现象，一字不差（「更新的不太及时，只有我动调色盘或者切模型的时候才出现」）。所以调色板的施加被收成一个函数（`applyPalette`），模型切换和轮换的每一步都走它——定时器 tick 与手动「下一张」共用那个负责画一步的 `paintImage` 出口。只要 `paintImage` 或 `applyActive` 不再经过它、或者它不再读取「当前生效的颜色」（`activeColor`：正在显示的那张图的颜色，否则规则色），`pnpm check:repaint` 就会报错。
+- **节日配色同样逐图** —— 节日的固定配色同时写在节日条目**和它的图片**上，`normalizeHolidayRule` 每次读取都用定义强制覆盖两处（任一处手改都会被替换回来）。所以「节日多图轮换、每张带自己的配色」已经只差 `HOLIDAYS`、它的素材，以及 node 半边的「槽位 → 素材」映射，而不需要在渲染层再开一条代码路径。
+- **配置格式升到 4，旧宿主依旧吃不掉配置** —— `images[].color` 对 schema 3 的 `normalizeImage` 是未知字段，而它会**按自己认识的键重建**每个图片条目：颜色会一直在内存里活到下一次重新加载，然后悄无声息地消失，宿主日志里也什么都不会说。`SCHEMA_VERSION = 4` 在每次 `read` 时公布，客户端用 `>=` 比较，报出更低版本的宿主会进入扣住写入的分支：日志提示一次，面板里说明（「重启 DSH」）。主题文件升到格式 5；4 及更早仍可导入，它们从来没有的颜色由上面那次抬升补上。
+- **没有图片的规则只剩一个上传入口** —— 上方那块大预览**本身就是按钮**了（真正的 `<button>`，可聚焦、可键盘触发；点它上传，也可以把文件拖上去），而胶片条在一张图都没有时**完全不渲染**：它里面除了一块「添加图片」再没有别的东西，而胶片条是一组图片的列表，一张图都没有的状态下它没有存在的理由。拖放处理跟着一起上移而不是消失——把胶片条藏起来，不该把每条规则诞生时都要用的拖放也一起拿走。其它都没动：带文字的 **添加图片** / **从网址** 按钮还在原位，空状态那几句话一字未改；有图片时预览依旧刻意保持惰性（拖到胶片条是新增，「替换这张」仍是显式的带文字按钮——正是这一点让预览不会吞掉用户无意的点击）。
+- **门禁** —— `check:node` 通过真实 RPC 处理器把逐图主题色这套形状端到端跑了一遍：抬升的两个方向（缺键继承规则色、显式 `null` 不继承）、颜色经过文件往返后各自独立且保持顺序、节日两处颜色都被强制、公布的 schema 升到 4，以及 `null` 落盘时是**键**而不是被省略。`check:repaint` 多了一节「轮换步骤必须重发调色板」，而新写入路径 `setImageColor` 也进入它要求「先采样 winner、再以 `repaintIfMoved` 收尾」的清单。`check:ui` 覆盖那三条新文案与两个新类（`.dab-strip-dot`、`.dab-rule-thumb-add`），跟其它每一条一样。
+
+## v0.7.0
+
+- **每条规则多图轮换 —— 默认关闭** —— 规则现在持有一组有序图片（`images: [{ slot, bgState }]`），可以按自己的节奏循环：10 秒 / 30 秒 / 1 分钟 / 5 分钟 / 30 分钟 / 1 小时，或 5 秒 – 24 小时之间的任意秒数；顺序可选**按顺序**或**随机**。默认是关的：轮换真的要花流量、内存和电，一个偷偷让壁纸动起来的默认值，等于替用户做了决定。
+- **第二种触发完全不需要定时器** —— 「切换模型时也换一张」：每次切换模型落到这条规则上就前进一张。对一条「每次都想看到不一样」的规则来说，这就是全部功能：不排期、不唤醒，只在用户做事的时候换图。
+- **随机绝不会抽到当前正在显示的那张** —— 挑选在**除当前这张之外**的所有下标上等概率进行，因为一次「图没变」的 tick 与一次「压根没触发」的 tick 完全无法区分 —— 而这正是这个功能唯一可能悄无声息失败的方式。`pnpm check:rotation` 对 2、3、7 张图的列表把整个随机取值范围**穷举**了一遍（不是抽一次样本），同时钉住顺序巡回的环绕、越界与小数下标，以及「只有一张图或间隔非有限值时报出的绝不是『正在轮换』」。
+- **全插件只有一个定时器，始终对准生效规则，按签名重排** —— 每条规则一个定时器会让根本没在画的规则白白唤醒，而屏幕上同时只可能有一条规则的图。它只在**排期真正依赖的那些输入**组成的签名变化时重排：规则 id、开关、间隔、顺序、图片数量、标签页可见性。所以拖动滑块导致每秒重跑几十次 apply 也不会把停留计时反复清零（若按「每次 apply 就重排」的写法，把透明度滑块拖上 30 秒就意味着这 30 秒里轮换永远不会前进）。标签页隐藏时轮换跟着画面一起停下，回到前台时按全新间隔重新计时，而不是对着没人看的标签页画三次。
+- **换的只有画面，规则本身不动** —— 主题色、布局模式、背景透明度与模糊度都留在规则上，过渡用的就是切换模型时那套双层交叉淡入。规则还能要求比切换更慢的淡入，或者 `fadeMs: 0` 直接硬切 —— 而 0 是一个真实取值，不会被当成「没设置」。
+- **取景移到图片上，这才是它该在的地方** —— 构图属于某一张图：两张宽高比不同的壁纸共享规则的模式、颜色、透明度与模糊度，但为第一张算出来的那套适应取景，用在第二张上就是错的。每张图各自带一份 `bgState`，背景编辑器编辑的是胶片条里选中的那一张。
+- **单图缩略图变成胶片条** —— 可一次加多张（**多选文件**、**拖放**，或**一行一个网址**批量粘贴，逐个下载以免 N 个请求互相穿插、连进度都没法显示）、点选要编辑的那张、排序、设为**第一张**（不轮换时规则画的就是它）、**原地替换这张**（替换会保住它在轮换里的位置，所以它与「添加」分开命名）、或删除。
+- **规则可以一张图都没有，而这是一个必须成立的状态** —— 这个功能的第一版拒绝删除最后一张，转而「清空它的字节」，结果留下的正是条目本身：胶片条第 1 位一块永远删不掉的空白图，于是下一次上传只能排到第 2 位，规则继续什么都不画，预览也一直停在空帧。现在删除最后一张就是把列表清空。新建的规则也从空列表开始（第一张图到达时才分配槽位）；手改导致「每一项都不可用」的列表同样落到这个状态，而不是被硬塞回一个坏槽位。只有「哪里都没提到可用图片」的规则（既没有列表、也没有旧式槽位）才会被 sanitizer 丢掉。
+- **一张图都没有的规则，靠主题色继续生效** —— 空列表不等于「这条规则失效」，而第一版把它当成了失效：「可用」只看有没有图，于是一条图片删光、主题色还在的规则**不再参与匹配**，它那份主题色连同色轮、灵感色板、「跟随系统主题」全成了摆设（报告里的现象就是「主题色无效」），而它原本匹配的模型还会被悄悄交给**下一条**规则 —— 把兜底规则的图删光，屏幕上出现的就是另一个模型的壁纸。现在判定标准是**有图，或者有自己的主题色**（`ruleCanPaint`）：这样的规则照旧匹配、照旧当兜底，只是不铺壁纸、只给界面配色；两者都没有（比如刚新增的空规则）才会被跳过。面板上的提示也按三种真实状态分开说：没有图但有主题色、既没有图也没有主题色、有图但选中的那张还没取到内容 —— 之前这三种情况共用一句「这条规则还没有图片」，其中两种是假话；「从本图提取」旁边那句「优先从本图取色」也不再出现在无图可取的时候。
+- **凡是可能改变「谁赢」的编辑，现在都立刻生效；只有不可能改变的才允许跳过重画** —— `color`、`enabled`、`match` 都参与「哪条规则赢」的判定，但每条写入路径各自问的是一个很窄的问题（「这条规则是不是正在画的那条？」），于是只有对**已经**在生效的那条规则的编辑会重画。而「本来没在生效」的编辑恰恰就是**制造**赢家的那些：一条空规则的第一张图（正是它让这条规则变得可画 —— 见 `ruleCanPaint`），以及落在它身上的第一个颜色或自动提取出的颜色。这些改动确实进了配置、也进了面板自己的读数，但背后的界面还停在原来的规则上；报告里的说法是「更新的不太及时，只有我动调色盘或者切模型的时候才出现」—— 拖色轮或切模型才终于重跑了一次解析。现在每条路径都会在改动**之前**取一次赢家、改动之后再做比较（`repaintIfMoved`，判定本身是 `src/client/repaint.ts` 里的纯函数 `shouldRepaint`），这同时修好了一个会变旧的记录：当被编辑的规则**就是**赢家时，即使页面从没把它记成生效规则，也会重画。`pnpm check:repaint` 把这条判定的真值表走了一遍 —— 赢家移动的两个方向、以及那些必须保持廉价的情形 —— 并且只要入口文件里那九条写入路径（外加上传之后才到达的自动提取）中的任何一条不再询问它，就会失败。把它钉下来的实机验证让一条一次性规则走了完整序列（新建空规则 → 移到最上 → 上传一张图 → 之后什么都不碰）：用旧判断时画面一直不动，直到有别的东西去动它；用现在这版，约 280 毫秒内画面就跟着换了，而且那张图自动提取出的颜色一起到位。
+- **清空之后再上传** —— 你加进去的那张就是你正在看的那张（卡片会把编辑焦点移到新加入的第一张，胶片条、大预览与位置读数一起跟上），而不是把面板留在之前选中的东西上。
+- **只加载用得到的图** —— 启动时只灌每条规则的**第一张**（与多图出现之前每条规则灌一张完全一致），外加今天生效的节日图与当前模型正在画的那张。其余的在展开卡片时、或轮换即将用到它时再取。若在启动时灌满每条规则的每张图，「五条规则各四张」就意味着首帧之前先把二十张全尺寸 data URL 从本插件自己的 RPC 通道推一遍；同理，store 报出的槽位列表也不再被灌进内存 —— 没有任何规则引用的孤儿槽位，本来就没有卡片可以显示它。
+- **旧宿主进程再也不可能吃掉一份配置 —— 判定改成版本比较，格式版本因此升到 3** —— 浏览器半边与 node 半边是分开加载的，所以「更新包之后只刷新一次页面」会把**新的**客户端 bundle 与仍在运行**上一个** node 半边的宿主进程配在一起。那个旧 sanitizer 完全不认识 `images`，于是会在下一次拖动滑块时悄无声息地丢掉每一条规则。因此 node 半边会公布自己写入的配置格式（每次 `read` 都带 `schema`），而发现答案是旧版的客户端会**扣住所有配置写入**（唯一入口：`src/client/rpc.ts` 的 `canWriteConfig`）、在控制台警告一次，并在面板里说明「重启 DSH」。悄悄不保存的修改，比明说要等重启的修改更糟；而悄悄删掉规则的修改，比两者都糟。0.7.0 开发期间这道闸门真的漏过一次：当时版本号是 2，正在运行的 0.7 node 半边虽然也报 `schema: 2`，却是**空规则修复之前**的构建，于是「把规则删空」的写入照旧放行，宿主把这几条规则从磁盘上抹掉了。所以这个版本号现在表示的是「**空图片列表合法**」（`SCHEMA_VERSION = 3`），而不只是「规则里有 `images` 字段」：任何报出更低版本的宿主一律进入扣住写入的状态。
+- **老配置照常读，老导出照常导入** —— `normalizeRule` 同时接受两种形状：规则里那对单图字段（`slot` / `bgState`）在读取时被提升成 `images: [{ slot, bgState }]`，同一条规则里重复的槽位被去掉，不可用的槽位被去掉。主题导出升到**格式版本 4**，导出与还原的是每条规则的**全部**图片而不只是第一张；版本 3 的文件仍可导入。
+- **各图槽位互不干扰，删除规则只回收它自己那份** —— 一条三张图的规则占三个 `modelbg-<slot>` 文件；`nextSlot` 扫描配置里的**每一个**槽位（用户规则**与**节日条目都算），所以新加的一张图绝不会撞上已有的槽位；删除规则时，只有当某个槽位不再被任何地方引用时才回收。
+- **node 半边连嵌套字段的漂移也一并报告，迁移直接写新形状** —— `warnUnknownConfigKeys` 现在会往深一层比较 `rules[].rotate` 与 `rules[].images[]` —— 一个只有客户端 bundle 知道的字段正是在那里无声消失的；同时 `slot` / `bgState` 这两个旧字段名被明确豁免，因为 sanitizer 是**故意**要提升它们的。0.3 之前配置的迁移也直接写出图片列表，而不是把一个旧形状留在磁盘上等第一次写入。
+
+## v0.6.0
+
+- **节日特殊背景 —— 只有一个开关，不是一整块设置** —— 中秋与国庆当天，壁纸自动换成那个节日自己的图片、并配上该节日固定的主题色，第二天早上自动换回。功能默认就是开的，而它在界面上**只有一行**：**「配置」页**上一个开关。刻意不做每个节日的卡片、缩略图和选图入口 —— 那些面板短暂存在过，但它们让这个功能看起来像是等着用户去配置的东西，而它恰恰不是。
+- **这个开关是「下车口」，只有显式 `false` 才算关** —— 功能存在之前写下的配置、或者从没动过开关的配置，都照常工作。
+- **没图可画的节日会回落到规则，而不是把背景刷空** —— 覆盖需要同时满足三件事：开关、今天在窗口内、槽位里确实有字节。最后一条是关键：开了开关却没有图的节日，仍然让模型规则说了算。
+- **中秋按农历、国庆按公历，两者都按 Asia/Shanghai 判定** —— 中秋是农历八月十五，在公历上逐年移动（2024-09-17、2025-10-06、2026-09-25、2027-09-15……）；国庆是固定的 10 月 1–7 日。农历换算直接用浏览器自带的 ICU，**零依赖**。时区是**钉死的，不取机器本地时区**：农历日期在北京时间午夜翻页，用 UTC 时钟读「今天」会让地球上大多数人过错日子 —— 北京 23:59 / 00:01 的跨日行为有测试钉住。
+- **闰八月不会把中秋拖后一个月** —— ICU 用后缀 `bis` 标记闰月，所以判等必须写死 `month === '8'`，这样中秋才永远落在**正**八月。已对 1900–2100 年间所有闰八月年份做过校验（1900、1957、1976、1995、2052、2071、2090）：2052 年插件在 **2052-09-07** 生效，而不是那年落在十月的 `8bis` 十五。
+- **中秋与国庆重叠时中秋优先** —— 两者确实会撞（2025-10-06 就是同一天）。一个精确的单日，比七天窗口里的某一天更值得采信。
+- **壁纸内置在包里，压到原图的十二分之一：8.37 MB → 729 KB** —— 原生分辨率、WebP q80（中秋节 1856 KB → 228 KB，国庆节 6716 KB → 500 KB）。npm 包从 **401 KB 涨到 1.12 MB**；图片本身已是压缩格式，gzip 再压不动，这就是这个功能的全部代价 —— 也正是不能直接塞原图的原因（原图会让安装包重 21 倍，而且每次启动都要把 6.7 MB 的 base64 从插件自己的 RPC 通道推一遍）。
+- **壁纸属于包，任何入口都换不掉** —— 节日槽位是只读的：node 半边直接送出内置资源，从不为此查询数据目录，写入、删除和抓取这些槽位一律被拒。丢进去的文件不会被任何一次读取采用 —— 这正是让这个彩蛋保持为彩蛋、而不是一项设置的原因。
+- **没启用的节日不花任何代价 —— 没在过节的那天也不花** —— 既然覆盖默认开着又不显示，启动时就只取**今天真能生效**的那一个节日，别的日子那 729 KB 一个字节都不读；如果午夜正好跨进某个节日，由跨日轮询去补取（启动时没理由取它）。node 半边同样是按需才去找内置文件，而不是跟着插件一起加载。
+- **节日主题色是常量，不是从图里读出来的** —— 中秋用 `#384A77`，国庆用 `#FFF6EB`：以十六进制写在节日定义里（就在槽位和壁纸旁边），由共享 schema 转成规则形状的 `[h, s, l]`，并在每次读取时强制覆盖 —— 所以手改 `theme-config.json` 里的 `color`，加载时也会被定义值换掉。原来那个「解码一张全尺寸节日照片，只为重新算出一个永远相同的色相」的取色流程，以及配套的「这张图试过了吗」记账，全部删除；配色现在是一项不花启动代价的设计决定。
+- **导出的主题文件只带规则** —— 节日壁纸不在 `dsh-background-by-model-theme.json` 里。它们随包发布，导出意味着给每个文件多加约 970 KB base64，只为了搬运每份安装本来就有、而槽位还拒绝接收的字节。
+- **三道零依赖校验，守住那些「静默出错」的地方** —— `pnpm check:holiday`（`scripts/holiday-check.ts`）钉住两个节日窗口、北京时间的跨日边界、闰八月的行为，以及 `pickHoliday` 允许节日接管背景之前必须通过的四道闸门；`pnpm check:ui`（`scripts/ui-strings-check.ts`）会在某个 `t('…')` 键只存在于一本字典、某个 `dab-…` 类在样式表里没有规则、或某条字典条目已经没人引用时直接失败。第三道 `pnpm check:node`（`scripts/node-half-check.mjs`）把**构建产物**里的 node 半边通过它真实的 RPC 处理器跑一遍，`DSH_HOME` 指向临时目录 —— 因此它覆盖了持久化层却从不碰真实的 `~/.dsh`：节日配置块穿过共享 sanitizer、内置壁纸从空槽位送出、节日槽位拒绝写入 / 删除 / 抓取而丢进去的文件被忽略、普通规则槽位照常写入和删除，以及手改过的配置无法把节日指向别的规则的图片。三道都用裸 `node` 跑（≥ 22.6 自己剥类型），不需要依赖、不需要转译器、也不需要浏览器，`pnpm test` 现在会一并执行。判定本身 —— `pickHoliday` —— 正是为了能测才从插件的 apply 闭包里抽到 `src/holiday.ts` 的。
+- **`check:ui` 当场清掉了从早期版本遗留至今的十个死键** —— `close`、`ruleMatchLabel`、`ruleFraming`、`ruleFramingLocked`、`colorHint`、`swatchTitle`、`hexCaption`、`extractColor`、`extractNoWp`，以及本次刚加进去的 `holidayPreview`。
 
 ## v0.5.5
 

package/README.md

@@ -76,19 +76,47 @@ One interface, one config — only the current model differs:
 
 - **Ordered Rule List** — Add, remove, reorder and name rules. Each rule is matched by its own match string; the first hit wins and rule 1 is the fallback.
 - **Live Match Readout** — The top of the Model Background tab shows the current state, e.g. `Current model deepseek-flash → matched · Rule 1`, so you can verify a rule on the spot. If the current model can't be detected, a hint is shown instead.
-- **Per-rule Appearance** — Every rule owns its wallpaper, theme color, layout mode, framing, opacity and blur. Nothing is shared globally except the Interface tab.
-- **Import / Export** — Export every rule **including its wallpaper** to a `dsh-background-by-model-theme.json` (format version 3, images inlined as base64) and restore it anywhere.
+- **Per-rule Appearance** — Every rule owns its wallpapers, layout mode, opacity and blur, and **every image owns its framing and its theme color**. Nothing is shared globally except the Interface tab.
+- **Several Images per Rule** — A rule holds an ordered set of images, shown as a filmstrip: add several at once (file picker, drag & drop, or a list of URLs, one per line), reorder them, promote one to first, **replace one in place** (which keeps its position in the rotation), or remove them one by one. The image a rule paints when nothing rotates is its **first**. Removing the last image simply leaves the rule empty — and empty is not the same as off: while the rule keeps a theme color of its own it still matches, still serves as the fallback, and paints the interface instead of a wallpaper; only a rule with neither (a freshly added one) is skipped by matching. So an emptied rule is a visible, reversible state rather than one you get stuck in. While it holds no picture the filmstrip is hidden and the big preview tile **is** the upload button, so there is exactly one obvious place to add one.
+- **Import / Export** — Export every rule **including all of its images** to a `dsh-background-by-model-theme.json` (format version 5, images inlined as base64) and restore it anywhere. Files written by earlier releases still import: each rule's single image is lifted into its image list, and a color written before per-image colors is lifted onto every image that has none — so an older theme file restores its look unchanged.
 - **File-based Persistence** — All settings and images are stored on the filesystem under `~/.dsh/.dsh-background-by-model-data/`, not `localStorage`.
 - **Automatic Migration** — Old single-wallpaper configs are upgraded in place on first read. See the [v0.3.0 entry in CHANGELOG.md](./CHANGELOG.md#v030).
 - **Bilingual** — Full Chinese / English UI with automatic locale detection.
 - **Theme Watchdog** — Re-asserts the custom theme if the host resets it.
 
+### Image rotation
+
+Per rule, and **off by default** — cycling spends real bandwidth, memory and battery, so nothing turns it on for you.
+
+- **Enable it per rule** — the switch appears in the rule card and only becomes usable once the rule holds two or more images.
+- **Dwell time** — 10 s / 30 s / 1 min / 5 min / 30 min / 1 h, or any custom value in seconds (clamped to 5 s – 24 h).
+- **Order** — **In order** walks the list top-down and wraps around; **Shuffle** picks uniformly among every image *except* the one on screen, so a tick never looks like it was missed.
+- **Also step on a model switch** — an optional second trigger: every time the model changes and lands on that rule, it steps once. That is the whole feature for a rule meant to show "a different picture every time" without any timer running.
+- **Only the active rule rotates** — one timer for the whole plugin, aimed at whichever rule the current model resolved to. It stops while the tab is hidden and resumes on a fresh interval; a single-image rule (and every [holiday](#holiday-backgrounds)) never schedules anything.
+- **Next image** — steps the wallpaper immediately, for when you want to check the set.
+- **What follows a switch is the rule — except the color, which travels with the picture** — layout mode, opacity and blur belong to the rule and stay put. The theme color belongs to the **image**, so a rotation can move through a green picture, a red one and a system-themed one, and the interface palette changes with the wallpaper. The cross-fade between two images is the same one a model switch already used.
+- **Framing is per image, and so is the color** — a crop and an accent both belong to a picture, so each image keeps its own while sharing the rule's layout, opacity and blur. The filmstrip marks the images that carry a color of their own, and the color controls always say which image they are editing.
+- **Only the images it needs are loaded** — boot reads each rule's first image; the rest stream in when a card is expanded or when the rotation is about to need one. Ten images per rule therefore do not mean ten wallpapers transferred before the first frame.
+
+### Holiday backgrounds
+
+A small one, not a settings block: **one switch on the Config page and nothing else**. It is on out of the box, and on the day the background changes by itself and changes back the next morning.
+
+- **How it behaves** — On 中秋节 and 国庆节 the wallpaper switches to that holiday's own image, with that holiday's own fixed theme color (中秋 `#384A77`, 国庆 `#FFF6EB`). The next day, the model rules take over again.
+- **Mid-Autumn Festival** — 农历八月十五, the day itself. It moves every year (2024-09-17, 2025-10-06, 2026-09-25, 2027-09-15 …), so it is resolved from the Chinese calendar at runtime, in **Asia/Shanghai** — the lunar day turns over at Beijing midnight, not yours.
+- **National Day** — October 1–7.
+- **Mid-Autumn wins the overlap** — the two do collide (2025-10-06 was both); the single precise day is the better answer.
+- **A holiday with no image falls through** to the model rules rather than blanking the wallpaper.
+- **Built-in wallpapers** — Both holidays ship with a compressed wallpaper (228 KB and 500 KB at native resolution, against 8.37 MB of source art). Only the holiday that can paint *today* is ever fetched, so a profile that is not on a holiday transfers none of it.
+- **Neither the art nor the palette is swappable, by design** — an easter egg that asks to be configured is not an easter egg. A holiday slot is read-only: a file dropped into `modelbg-h-midautumn` / `modelbg-h-nationalday` is ignored by every read, and the plugin refuses to write, fetch into or delete those slots. The theme colors are constants in the holiday definition and are forced on every read — on the holiday **and on its image**, since a theme color lives on the image now — so a hand-edited `color` in `theme-config.json` cannot repaint a festival either. Theme exports therefore carry your rules only.
+- **Turning it off** — the switch on the Config page, or `"holidays": { "enabled": false }` in the same file.
+
 ### Per-rule settings
 
-- **Wallpaper** — Upload any image as this rule's wallpaper; each rule keeps its own file.
-- **Theme Color** — HSL wheel plus numeric input and an inspiration palette, with **Extract from this image** and an **eyedropper**. When a rule sets no theme color, the system theme is used. Generates the full CSS design-token set in real time. Following the system theme hands the palette back to the host while the wallpaper and the Interface-tab opacity/blur sliders keep working — the surface colors are read back from the host's own tokens and re-emitted with your alpha, so the wallpaper is never buried under an opaque plate.
+- **Wallpaper** — Give a rule one or more images; each image is its own file. The filmstrip picks which one you are editing, and the "first" one is what the rule paints when no rotation is running. A rule may also hold **no** image: it then paints no wallpaper, but as long as it has a theme color of its own it still matches and still serves as the fallback (painting the interface alone), and only with neither is it skipped by matching until you give it something.
+- **Theme Color** — HSL wheel plus numeric input and an inspiration palette, with **Extract from this image** and an **eyedropper**. **The color belongs to the image**: those controls edit the one selected in the filmstrip, the strip shows which images already carry a color of their own, and an image that has none follows the system theme rather than inheriting its rule's. A rule with **no image at all** has only its own color left to edit — and that is exactly what such a rule paints. Generates the full CSS design-token set in real time. Following the system theme hands the palette back to the host while the wallpaper and the Interface-tab opacity/blur sliders keep working — the surface colors are read back from the host's own tokens and re-emitted with your alpha, so the wallpaper is never buried under an opaque plate.
 - **Layout Mode** — Fit / Fill / Stretch / Tile / Center.
-- **Framing** — Drag to pan and scroll to zoom inside a viewport-proportional editor; **only editable in Fit mode**, and the committed framing stays consistent across window resizes and cross-monitor moves.
+- **Framing** — Drag to pan and scroll to zoom inside a viewport-proportional editor; **only editable in Fit mode**, and the committed framing stays consistent across window resizes and cross-monitor moves. Stored per image.
 - **Background Opacity** — `0–100%` for the rule's wallpaper layer.
 - **Background Blur** — `0–60 px`, applied to the wallpaper layer.
 
@@ -106,8 +134,8 @@ Settings → **Theme** now has three tabs:
 | Tab | Scope | Contents |
 | --- | --- | --- |
 | **Interface** | Global, shared by every model | Opacity & blur for the main background, left panel, right panel, cards & panels, input & controls, settings panel, conversation text box and trajectory page |
-| **Model Background** | Per rule | The ordered rule list, the live match readout, and each rule's wallpaper, theme color, layout mode, framing, opacity and blur |
-| **Config** | — | Import / export the whole rule set (`dsh-background-by-model-theme.json`) |
+| **Model Background** | Per rule | The ordered rule list, the live match readout, and each rule's images (filmstrip), theme color, layout mode, per-image framing, opacity, blur and [rotation](#image-rotation) |
+| **Config** | — | Import / export the whole rule set (`dsh-background-by-model-theme.json`), plus the single [holiday background](#holiday-backgrounds) switch |
 
 The old **Color** tab is gone — the theme color is now a property of each rule. The old **Background** tab became **Model Background**.
 
@@ -117,8 +145,9 @@ Data directory: `~/.dsh/.dsh-background-by-model-data/` (Windows: `C:\Users\<you
 
 | File | Contents |
 | --- | --- |
-| `theme-config.json` | The rule list plus the global Interface settings |
-| `modelbg-<slot>` | The image of each rule, stored as raw bytes without a file extension |
+| `theme-config.json` | The rule list (each rule with its image list and rotation) plus the global Interface settings and the holiday overrides |
+| `modelbg-<slot>` | One image, stored as raw bytes without a file extension — one file per image, so a rule with three images owns three slots |
+| `modelbg-h-midautumn` / `modelbg-h-nationalday` | Not used: both holiday wallpapers ship inside the package and are served straight out of it |
 
 ## Installation
 
@@ -170,7 +199,13 @@ To mount a working copy into a profile instead, add it to the profile's `package
 
 After changing anything under `src/`, run `pnpm run bundle` again — the mounted profile loads `lib/`, so edits do not take effect until the bundle is rebuilt.
 
-`pnpm test` builds and typechecks (`tsdown && tsc -p tsconfig.json`).
+`pnpm test` builds, typechecks and runs five checks (`tsdown && tsc -p tsconfig.json && node scripts/holiday-check.ts && node scripts/rotation-check.ts && node scripts/repaint-check.ts && node scripts/ui-strings-check.ts && node scripts/node-half-check.mjs`). None of them needs a dependency, a transformer or a browser, and each can be run alone with `pnpm check:holiday` / `pnpm check:rotation` / `pnpm check:repaint` / `pnpm check:ui` / `pnpm check:node`:
+
+- **`check:holiday`** — the two holiday windows against known dates, the Beijing day boundary (23:59 vs 00:01), leap eighth months across 1900–2100, and the four gates `pickHoliday` applies before a holiday is allowed to take over the background.
+- **`check:rotation`** — the rotation's decisions (`nextIndex` / `isRotating`): no walking off the end of a list, shuffle never repeating the image already on screen (across the whole support of the roll), and "rotating" never claimed for a rule with nothing to rotate.
+- **`check:repaint`** — the decision that says whether an edit has to repaint the interface (`shouldRepaint`), including the case that kept failing in the field: an edit that **creates** the winner (a rule's first picture, its first or auto-extracted color) must repaint even though the edited rule was not the active one yet. It also fails if any of the write paths in `src/client/index.tsx` stops asking — so re-introducing the old `id === activeRuleId` test breaks the build's checks instead of the user's next upload — and if a rotation step stops re-emitting the interface palette (a theme color belongs to the image, so a step changes it).
+- **`check:ui`** — every `t('…')` key exists in both dictionaries, both dictionaries carry the same key set, every `dab-…` class has a rule in the stylesheet, and no dictionary entry has gone unreferenced.
+- **`check:node`** — the built node half driven through its real RPC handler with `DSH_HOME` redirected to a throwaway directory: the holiday block through the shared sanitizer, the packaged wallpapers served from an empty slot (without being copied into the data directory), a holiday slot refusing writes, deletes and URL fetches while a file dropped into it is ignored, an ordinary rule slot still writing, listing and deleting, a hand-edited config unable to redirect a holiday at another rule's image, and the per-image color shape: the read-time lift in both directions (an absent key inherits the rule's color, an explicit `null` does not), independent colors through the file, and a `null` written as a key rather than omitted.
 
 ## FAQ
 
@@ -181,7 +216,25 @@ Your first rule probably has an empty match string, which makes it a pure fallba
 Matching is first-hit, not best-hit. Put the more specific rule higher in the list, or reorder so the rule you want comes first.
 
 **Where are my wallpapers?**
-In `~/.dsh/.dsh-background-by-model-data/`, one `modelbg-<slot>` file per rule plus `theme-config.json`.
+In `~/.dsh/.dsh-background-by-model-data/`, one `modelbg-<slot>` file per image plus `theme-config.json`.
+
+**I turned the rotation on and the background never changed.**
+Three things can hold it: the rule needs two or more images, the tab has to be visible (a hidden tab paints nothing, so the rotation pauses with it), and only the rule the current model resolved to rotates — a rule that is not active has a disabled **Next image** button for exactly that reason.
+
+**Does rotating cost anything?**
+Yes, and that is why it is off by default. Each image is stored at full fidelity — no re-encoding — so a rule with ten 8 MB wallpapers holds ten of them, and every switch repaints the whole interface. Keep the sets small (two to five images is the sweet spot) and the dwell time sane; boot only reads each rule's first image, and the rotation warms the image it is about to need, so the cost is memory and disk rather than start-up time.
+
+**Why did the theme color stop working after I removed a rule's images?**
+That was the old behaviour, and its root cause was reading "has an image" as "is usable": a rule with no pictures left stopped matching at all, so its color had nothing to act on — and the models it used to own were handed to the next rule instead. A rule now counts while it has **an image, or a theme color of its own**: no wallpaper, the interface painted from that color (the card says which state it is in). Only a rule with neither — nothing to show at all — is skipped, with the card spelling that out.
+
+**I updated the plugin and the panel says my edits are not being saved.**
+The browser half and the host half are updated separately: a refreshed page can run the new client while DSH's own process still runs the previous plugin, which cannot read the new config shape (it announces a lower `SCHEMA_VERSION`) and could drop rules on the next write. The client detects that and holds its writes — restart DSH and the multi-image config, rotation settings and everything else save normally.
+
+**I set a color for one image and the other images did not change.**
+That is the design: since 0.7.1 a theme color belongs to the **image**, not to the rule, so a rotation can move through pictures with different accents (a green one, a red one, and one that follows the system theme). The color controls edit whichever image the filmstrip has selected, and the hint above them names it. A rule with **no image at all** is the one case where the controls edit the rule's own color — that color is what such a rule paints, and it is deliberately not a default for the rule's pictures.
+
+**Where did the theme color I set before this update go?**
+Nowhere: an image written before per-image colors has no color of its own at all, which is exactly what the loader uses to tell "never had one" from "cleared on purpose", and it lifts the rule's color onto every such image. So a themed rule comes back looking identical, and from then on each picture can be retinted on its own.
 
 **Can I share a setup?**
 Yes — export it from the **Config** tab; the JSON inlines every rule's image.
@@ -200,18 +253,33 @@ The other half of the same hole: while it owns a color the plugin **forces** `bo
 
 ## Recent Optimizations
 
-> Only the two most recent releases are listed here; older ones (v0.5.0 and earlier) live in [CHANGELOG.md](./CHANGELOG.md).
-
-### v0.5.5
-
-- **The color preview field prints its own hex** — it sat at the bottom of the H/S/L (R/G/B) column behind the same 1px border and carried no text, so on a light color (reported: `#BADEE8`, L 82%) it read as one more — blank — text input with nothing to type into it. It now prints `#RRGGBB` in monospace centered on the color, inked by **Rec.709 luma** (the wallpaper extractor's own brightness measure) so the value never disappears into its fill, and the hover `scale(1.02)` it never backed up is gone. The duplicate hex caption above the HSL/RGB toggle went with it.
-- **The clear-color button says what it does** — **System theme** (a state) is now **Follow system theme** (the action), with the host's own sun glyph. It is the mirror of the 0.5.3 rename that turned the no-color button into **Custom color**.
-
-### v0.5.4
-
-- **A brand-filled control takes its label from the host's on-brand ink, not from `brand-text`** — Following the system theme painted the active layout chip, the **+ Add rule** button and the settings brand tile from the host's own `--dsw-alias-brand-primary`, which is a **contrast ink rather than a hue**: near-black (`#0f1115`) in the host's light scheme, near-white (`#f9fafb`) in its dark one. Their labels read `--dsw-alias-brand-text`, which the host defines as that very same color in both schemes and never uses in its own CSS. On a dark system that made them filled boxes with invisible labels — white primary button, white active chip, white icon tile (measured at exactly `#f9fafb`) — and they were only ever readable while the plugin owned the palette and generated its own brand pair. All four now read `--dsw-alias-label-primary-inverted`, the host's own ink for a brand/contrast fill: `#fff` on the light scheme's black fill, `#353638` on the dark scheme's white one.
-- **The toggle's on-state knob was the same bug one size smaller** — a hard-coded `#fff` on a `--dsw-alias-brand-primary` track, i.e. a white knob on the white track the dark scheme paints there.
-- **The plugin's own dark palette had the mirror of it** — that branch deliberately keeps its brand fill at 50%+ lightness, while `--dsw-alias-label-primary-foreground` — the token the **host's** own primary buttons label themselves with over `--dsw-alias-button-primary-fill` — was hard-coded white. It now flips with the fill (one shared verdict with `brand-text`), and the light branch re-emits `label-primary-inverted` so the plugin's palette owns the pair instead of inheriting it from whichever scheme the host happens to be in.
+> Only the two most recent releases are listed here; older ones (v0.6.0 and earlier) live in [CHANGELOG.md](./CHANGELOG.md).
+
+### v0.7.1
+
+- **The theme color moved down to the image** — a rule is a rotation through several pictures, and pictures collected for different moods do not share one accent. Each image now carries its own `color`, and the wheel, the numeric inputs, the inspiration palette, **Extract from this image**, the eyedropper and **Follow system theme** all edit the image selected in the filmstrip. The controls say which image they are addressing and the strip marks the images that already have a color of their own, so "I changed it and nothing happened" cannot be the first thing this feature teaches.
+- **A rule's own color now means exactly one thing** — what a rule with **no image left** paints. It is not a default for the rule's pictures: an image with no color of its own follows the **system theme** rather than inheriting it, which is what makes a rotation through a green picture, a red one and a system-themed one expressible at all. Clearing one image's color therefore clears only that image, and the rule's color survives for the state where it is the only thing left to paint.
+- **Nothing loses its theme on upgrade** — an image entry written before this release has no `color` key at all, and that is the whole distinction the loader uses: a missing key means "never had a color of its own", so the rule's color is lifted onto it (once, in the shared sanitizer, so both halves lift identically); an explicit `null` means "cleared on purpose" and is left alone. The rule keeps its color as well, so emptying a themed rule still paints it.
+- **A rotation step re-emits the palette, and that is not a detail** — the step only repainted the wallpaper, so a per-image color would have appeared when *something else* re-ran an apply: dragging the color wheel, or switching models. That is the exact symptom this plugin already had once ("it only updates when I touch the color wheel"), so the palette apply is now one function called by both a model switch and every step of the rotation (the timer and the manual **Next image** button, which share one funnel).
+- **Holidays carry their palette per image too** — a festival's fixed color is written on the holiday *and* on its image and is forced from the definition on every read, so the shape is ready for a holiday that rotates through several pieces of art, each with its own palette, as a change to `HOLIDAYS` and its assets rather than a second code path in the render layer.
+- **A rule with no picture has exactly one upload target** — the big empty preview tile *is* the button now (click it, or drop files onto it), and the filmstrip is not rendered at all while the rule holds nothing: it contained nothing but a second "add image" tile, and a filmstrip is a list of pictures — a state with none does not have one. Nothing else moved: the labelled **Add images** / **From URL** buttons stay where they were, and with pictures present the preview is still deliberately inert (dropping on the strip adds, and *replace* stays an explicit labelled action, which is what keeps a preview from swallowing a click the user did not mean).
+- **The config shape moved to 4, and an older host still cannot eat a profile** — `images[].color` is unknown to a schema-3 sanitizer, which rebuilds each image entry from the keys it knows: the color would survive in memory until the next reload and then be gone, with nothing in the log to explain it. The version check is a plain `>=`, so a host announcing less holds every write and says so in the panel until DSH is restarted.
+- **The gates cover it** — `check:node` now pins the lift in both directions (an absent key inherits the rule's color, an explicit `null` does not), per-image independence through the file, holidays forcing both colors, and that a `null` is written as an explicit key rather than as an absent one (writing it as absent would silently re-inherit the rule's color on every load). `check:repaint` additionally fails if a rotation step ever stops re-emitting the palette.
+
+### v0.7.0
+
+- **Multi-image rotation, per rule** — a rule now owns an ordered list of images and can cycle them on its own rhythm: 10 s / 30 s / 1 min / 5 min / 30 min / 1 h or a custom dwell, **in order** or **shuffle** (which never lands on the image already on screen, because that is indistinguishable from a missed tick). Off by default, because rotating spends bandwidth, memory and battery and no default should decide that quietly.
+- **A second trigger: a model switch** — with *also step on a model switch* on, stepping has nothing to do with time at all: every model change that lands on the rule shows its next image. A rule can then read as "a different picture every time" with no timer scheduled.
+- **One timer, aimed at the active rule** — it is armed by a signature of exactly the inputs the schedule depends on (rule, interval, order, image count, visibility), so a slider drag re-runs the whole apply dozens of times a second without ever restarting the dwell. A hidden tab stops the rotation instead of painting three times into the void.
+- **What follows the image is nothing** — theme color, layout mode, opacity and blur stay the rule's; only the picture changes, through the cross-fade a model switch already used. A rule can ask for a slower blend than a switch (or 0 for a hard cut).
+- **Storyboard, not a form** — the rule card's single thumbnail became a filmstrip: add several images at once (multi-select, drop, or one URL per line), click one to edit it, reorder it, promote it to first, replace it in place, remove it. The big preview above the strip shows the selected image, and the one on screen carries a live dot.
+- **An empty rule is a state, not a dead end** — the first cut refused to remove a rule's last picture and cleared its bytes "instead", which left the entry itself behind: a blank tile at position 1 that could never be deleted, so the next upload landed at position 2 and the rule kept painting nothing while the preview showed an empty frame. Removing the last image now empties the list, a brand-new rule starts empty (no slot is allocated until the first picture), the picture you add becomes the one you are looking at, and a hand-edited list whose entries are all unusable lands in the same state instead of being conjured back into a broken slot.
+- **Empty is not off: the theme color keeps working** — the first cut read "has an image" as "is usable", so a rule whose pictures had all been removed **stopped matching and stopped being the fallback**: its own theme color, the wheel, the swatches and the clear-to-system-theme button became decoration (the symptom is "the theme color does nothing") and the models it used to own were handed to the next rule. A rule now counts while it has **an image, or a theme color of its own** (`ruleCanPaint`) — no wallpaper, just the interface painted from that color. The card's copy names which of the three real states it is in (no image but a color / neither / an image whose bytes have not arrived) instead of covering all three with one sentence.
+- **Editing a rule that is not the active one takes effect at once** — `color`, `enabled` and `match` all feed which rule wins, but the write path only re-ran the resolution when the edited rule was already the winner: picking the first color for an empty rule, or typing a match string into a rule that had not won yet, changed nothing on screen until some unrelated event re-ran it.
+- **Only the images that are needed are loaded** — boot hydrates each rule's FIRST image (exactly what it hydrated per rule before multi-image), the rest arrive when a card is expanded or when the rotation is about to need one. Twenty pictures across five rules therefore do not mean twenty full-size data URLs before the first frame.
+- **A stale host can no longer eat a profile** — the node half publishes the config shape it writes, and a client that finds a host announcing an older version (`SCHEMA_VERSION`, where 3 is the first that means "an empty image list is legal") **holds every config write** and says so in the panel. Without it, updating the package and merely refreshing the page would let the previous sanitizer drop every rule on the next slider drag.
+- **Old configs still load, and old exports still import** — a rule's single `slot`/`bgState` pair is lifted into `images: [{ slot, bgState }]` on read; theme files (version 4 now, version 3 and earlier still accepted) carry, and restore, every image of every rule rather than just the first.
+- **A fourth static gate: `pnpm check:rotation`** — the rotation's decisions are pure (`nextIndex` / `isRotating`) and are now pinned down: no walking off the end of a list, shuffle never repeating the current image (checked across the whole support of the roll, not one sample), and "rotating" never being claimed for a rule with nothing to rotate. `check:node` covers the new shape through the real RPC handler: legacy lifting, per-image framing, dedupe, clamping, nested-drift warnings and per-image slot independence.
 
 ## Star History