dsh-background-by-model 0.8.2 → 0.9.1

package/lib/index.js

@@ -19,23 +19,16 @@ const HOLIDAYS = [{
 /**
 * The persisted configuration shape — declared exactly ONCE, for both halves.
 *
-* This shape used to be written out twice: the node half owns persistence and
-* sanitizes every write, the browser half owns the UI and its own reading of the
-* same file. A field added to only one side was silently dropped by the other
-* side's sanitizer — the matching slider stayed live in memory, `writeConfig`
-* wrote a config without it, and the next load fell back to the default.
-* `blurs.rightbar` / `rightbarOpacity` in 0.3.2 was exactly that bug, and the key
-* lists were duplicated 6 times across the two halves, so it was due to happen.
-*
-* The types, the key lists, the defaults and the pure normalizers therefore live
-* here and both halves import them: adding a field means editing this file, and
-* the two halves cannot disagree about the shape. The host additionally logs one
-* warning per unknown key while sanitizing a write (see `warnUnknownConfigKeys`
-* in `src/index.ts`), so a field that reaches the node half without being
-* declared here shows up in the host log instead of quietly disappearing.
-*
-* Nothing in this module may touch the DOM, Node or the Cordis context: it is
-* imported by the browser bundle and by the node half alike.
+* The types, the key lists, the defaults and the pure normalizers live here and
+* both halves import them, so adding a field means editing this file and the two
+* halves cannot disagree about the shape. (This was written twice until 0.3.2,
+* when a field declared on one side was silently dropped by the other side's
+* sanitizer.) The host also logs one warning per unknown key while sanitizing a
+* write (`warnUnknownConfigKeys` in `src/index.ts`), so a field that reaches the
+* node half without being declared here shows up in the log.
+*
+* Nothing here may touch the DOM, Node or the Cordis context: it is imported by
+* the browser bundle and by the node half alike.
 */
 const DEFAULT_BG_STATE = {
 	zoom: 1,
@@ -70,14 +63,14 @@ function defaultRotation() {
 	return { ...DEFAULT_ROTATION };
 }
 /**
-* Main interface opacities (0..1), global (Interface page):
-*   `bg`      main background (`--dsw-alias-bg-base`)
-*   `sidebar` sidebar (`--dsw-specific-sidebar-fill`)
-*   `card`    cards/panels (`--dsw-alias-bg-layer-1/2/3`, `--dsw-specific-menu`
-*             and its 0.1.7 alias `--dsw-menu-surface-fill`)
-*   `code`    code blocks, banner included (`--dsw-alias-markdown-code-block`,
-*             `--dsw-alias-markdown-code-block-banner`)
-*   `input`   input/control surfaces (`--dsw-specific-input-major`)
+* Main interface opacities (0..1), global (Interface page) — each part is the token
+* set it owns:
+*   `bg`       `--dsw-alias-bg-base`
+*   `sidebar`  `--dsw-specific-sidebar-fill`
+*   `card`     `--dsw-alias-bg-layer-1/2/3`, `--dsw-specific-menu` (and its alias
+*              `--dsw-menu-surface-fill`)
+*   `code`     `--dsw-alias-markdown-code-block`, `…-banner`
+*   `input`    `--dsw-specific-input-major`
 */
 const PART_OPACITY_KEYS = [
 	"bg",
@@ -120,12 +113,10 @@ const DEFAULT_TRAJECTORY_OPACITY = .73;
 const DEFAULT_RIGHTBAR_OPACITY = .45;
 /**
 * `#RRGGBB` → the `[h, s, l]` triple every rule stores (`s` and `l` in 0..1), or
-* null when the string is not a hex color.
+* null when the string is not a hex colour.
 *
-* A holiday names its color as hex because that is how a color is quoted, and a
-* hand-converted triple is a magic number nothing downstream can check. The
-* conversion lives here rather than in ./holiday because `[h, s, l]` is this
-* module's own rule shape.
+* Holidays name their colour as hex (`HOLIDAYS`) because a hand-converted triple
+* is a magic number nothing downstream can check.
 */
 function hexToHsl(hex) {
 	const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
@@ -158,11 +149,8 @@ function hexToHsl(hex) {
 /**
 * One holiday's appearance, untouched.
 *
-* Holidays default to `fill` rather than a rule's `fit`: these are full-bleed
-* festival wallpapers, and `fit` would letterbox them on every aspect ratio the
-* art was not cut for. The mode now lives on the IMAGE (see `BgImage.bgMode`), so
-* that default is written there — and `fill` is what a holiday's read-back
-* sanitizer refuses to lose (see `normalizeHolidayRule`).
+* The mode is `fill` rather than a rule's `fit`: full-bleed festival art would be
+* letterboxed by `fit` on every aspect ratio it was not cut for.
 */
 function defaultHolidayRule(def) {
 	const color = hexToHsl(def.color);
@@ -184,21 +172,13 @@ function defaultHolidayRule(def) {
 	};
 }
 /**
-* A rule with nothing in it yet: no picture, no match string, no color.
-*
-* Two states need this factory and they are the same state — a fresh install
-* (see `freshThemeConfig` and `normalizeConfig`), and the "add rule" tile one
-* entry further down the list.
+* A rule with nothing in it yet: no picture, no match string, no colour — a fresh
+* install's rule 1 and the "add rule" tile alike.
 *
-* Such a rule is deliberately valid rather than half-built: it is skipped by
-* matching until it has something of its own to paint (`ruleCanPaint` — a picture,
-* or a theme color), which is what makes a rule nobody has filled in yet invisible
-* instead of letting an empty background steal the fallback from rule 1.
-*
-* It used to be born with an allocated slot and an empty image entry, which is
-* what put a blank tile at position 1 of a new rule's strip — and, worse, stopped
-* the picture the user added next from being the first one (a rule paints its
-* FIRST image). The slot is allocated when the first picture arrives.
+* Valid rather than half-built: `ruleCanPaint` skips it until it has something of
+* its own, so it cannot steal the fallback from rule 1. It deliberately carries NO
+* image entry: a rule paints its FIRST image, and a placeholder slot left the
+* picture the user added next in position 2. The slot is allocated on arrival.
 */
 function blankRule(id) {
 	return {
@@ -279,18 +259,12 @@ function legacyFadeMs(rawRules) {
 	}
 }
 /**
-* Coerce one persisted transition block; a config written before this setting
-* existed has no `transition` key at all and gets the shipped default, which is
-* the behaviour it already had.
-*
-* `legacyMs` is the per-rule `fadeMs` this shape replaced (see `legacyFadeMs`),
-* adopted only when the incoming config has no `durationMs` of its own — so a
-* deliberate hand-tuned blend survives the upgrade instead of being dropped with
-* the field it used to live on.
+* Coerce one persisted transition block; a config without one gets the shipped
+* default, which is what it was already showing.
 *
-* `durationMs` is clamped with `0` kept as a real value (a hard cut) rather than
-* read as "absent": 0 is exactly how a hard cut is asked for without changing
-* the effect.
+* `legacyMs` is the per-rule `fadeMs` this shape replaced (`legacyFadeMs`), adopted
+* only when the incoming config carries no `durationMs` of its own. `0` is kept as
+* a real value (a hard cut), not read as "absent".
 */
 function normalizeTransition(raw, legacyMs) {
 	const t = raw ?? {};
@@ -305,25 +279,15 @@ function normalizeTransition(raw, legacyMs) {
 /**
 * Coerce one persisted image entry, or null when it lacks a usable slot.
 *
-* `inherit` is the RULE's own color, and it is applied only to an entry that has
-* no `color` key at all — the shape every release before 0.7.1 wrote, where a
-* rule's color was the only color there was. Lifting it here, once, is what makes
-* an upgrade a no-op on screen: a themed wallpaper keeps its theme instead of
-* silently dropping to the system palette, and it happens in the shared sanitizer
-* so both halves lift identically.
+* `inherit` (the RULE's colour) is applied only to an entry with no `color` KEY at
+* all — the shape written before per-image colours, where the rule's colour was the
+* only one there was. The key's PRESENCE is the whole distinction: `color: null` is
+* a deliberate "follow the system theme" and must not be re-inherited on every load.
 *
-* The KEY's presence is the whole distinction, which is why `null` is not the
-* same as absent: an entry with `color: null` is an image the user explicitly set
-* to "follow the system theme", and re-inheriting the rule's color over that
-* would undo a deliberate choice on every load.
-*
-* `inheritMode` is the same one-shot lift for the layout mode, and it is the
-* caller's to resolve because the two callers answer differently: a user rule
-* passes the mode its config carried at the RULE level (a schema-5 config, where
-* 适应/填充 was one choice for the whole rotation), a holiday passes `fill` (its
-* own default, which is not up for the lift to change). An entry that HAS a
-* `bgMode` key keeps it — including one that has just been set to a value equal
-* to the default, which is a decision and not an absence.
+* `inheritMode` is the same one-shot lift for the layout mode. It is the caller's to
+* resolve because the callers answer differently: a user rule passes the mode its
+* config carried at the RULE level (schema 5), a holiday passes its own `fill`. An
+* entry that HAS a `bgMode` key keeps it, even when it equals the default.
 */
 function normalizeImage(raw, inherit = null, inheritMode = "fit") {
 	const i = raw ?? {};
@@ -336,36 +300,21 @@ function normalizeImage(raw, inherit = null, inheritMode = "fit") {
 	};
 }
 /**
-* Coerce one persisted rule, or null when it names no image AT ALL.
-*
-* Accepts BOTH image shapes: the 0.7 list (`images`), and the single
-* `slot`/`bgState` pair every earlier version wrote — the latter is lifted to a
-* one-entry list here rather than at a dozen call sites, which is what keeps the
-* rest of the codebase free of "old config" branches. Duplicate slots inside one
-* rule are dropped: two entries pointing at the same bytes would only make the
-* rotation look stuck.
+* Coerce one persisted rule, or null when it names no image ANYWHERE.
 *
-* The rule's color is resolved FIRST and handed to every image entry, because it
-* is what an entry written before 0.7.1 inherits (`normalizeImage`). The rule keeps
-* it as well: it is not a default for its images at paint time any more, but it
-* is still what the rule paints once its last picture is gone.
+* Both image shapes are accepted here and nowhere else: the 0.7 list (`images`),
+* and the single `slot`/`bgState` pair every earlier version wrote, lifted into a
+* one-entry list. That is what keeps the rest of the codebase free of "old config"
+* branches. Duplicate slots inside one rule are dropped — two entries pointing at
+* the same bytes only make a rotation look stuck.
 *
-* The layout mode makes the same trip in the other direction, and this is the
-* last release that has to: a config written before 0.7.5 keeps `bgMode` at the RULE
-* level, where one value covered every picture of a rotation, so it is read here
-* once and handed to each image as its inherited mode. What the user chose
-* therefore survives the move the same way it survived the color's — the mode is
-* not reset to the default on upgrade, and the field it used to live on is simply
-* not written back.
+* The rule's colour is resolved FIRST and handed to every image entry (what a
+* pre-0.7.1 entry inherits), and the rule keeps it: it is what the rule paints once
+* its last picture is gone. The layout mode makes the same trip from the RULE level
+* a pre-0.7.5 config carries, so the user's choice survives the move.
 *
-* An EMPTY list is a legitimate rule, not a broken one: removing a rule's last
-* picture has to be expressible, and forcing an entry back in is what produced a
-* phantom blank image that took slot 1 and could never be deleted again (the next
-* upload landed at position 2 and the rule kept painting nothing). What such a
-* rule then does is `ruleCanPaint`'s business: with a color of its own it paints
-* the interface, with neither it is skipped by matching — which the card's own
-* hint says in so many words. Only a rule that names no image anywhere — no list,
-* no legacy slot, or a slot that could never be a filename — is dropped.
+* An EMPTY list is a legitimate rule: removing a rule's last picture has to be
+* expressible. `ruleCanPaint` decides what such a rule then does.
 */
 function normalizeRule(raw) {
 	const r = raw ?? {};
@@ -409,17 +358,11 @@ function normalizeRule(raw) {
 /**
 * Coerce one persisted holiday entry.
 *
-* `id`, `images` and every theme color (the rule's and each image's) come from
-* the DEFINITION, never from disk: a holiday's slot is the only thing tying it to
-* its bytes, and its theme color is a fixed part of what that holiday looks like —
-* so a stale or hand-edited value would either orphan the wallpaper, point the
-* holiday at a rule's image, or paint a festival in a color it does not have.
-* Everything else is sanitized exactly like a rule's field — except three things
-* that stay the definition's own: the image list and the rotation (so a festival
-* can never be swapped or cycled), and the layout mode, which is the definition's
-* `fill` for the same reason the color is its own — full-bleed art letterboxed by
-* a stale `fit` is the one thing this feature must not do, and the mode is not
-* editable for a holiday anywhere in the panel.
+* `id`, the image list and every theme colour come from the DEFINITION, never from
+* disk: a stale or hand-edited value would orphan the wallpaper, point the holiday
+* at a rule's image, or paint a festival in a colour it does not have. The layout
+* mode and the rotation stay the definition's own for the same reason (a festival
+* is never swapped or cycled). Everything else is sanitized like a rule's field.
 */
 function normalizeHolidayRule(def, raw) {
 	const r = raw ?? {};
@@ -452,21 +395,12 @@ function normalizeHolidays(raw) {
 	};
 }
 /**
-* The file-preview panel's own opacity.
+* The file-preview panel's own opacity: a number is the card's own value, `null` is
+* "never owned, follow `opacities.bg`", and a MISSING key is the shipped 45%.
 *
-* Three states, and the middle one is why this is a function rather than the
-* one-line fallback every other field gets: a real number is the card's own
-* value, `null` is "never owned, so follow `opacities.bg`", and a KEY that is not
-* there at all — a hand-written config, or one written before the option existed
-* — is the shipped profile's 45% (see DEFAULT_RIGHTBAR_OPACITY).
-*
-* `null` has to survive as ITSELF instead of falling through to the default:
-* every release so far has written it — a panel the user never dragged is
-* persisted as an explicit `null` — so treating it as "missing" would hand the
-* shipped 45% to every configuration whose preview panel was following the main
-* background, a silent change to a setup nobody asked to change. It is also
-* unreachable from the UI (no control returns to it); it exists for configs that
-* were written while the shipped default was `null`.
+* `null` has to survive as itself: every release so far persisted it for a panel the
+* user never dragged, so treating it as missing would silently hand the shipped 45%
+* to every configuration that was following the main background.
 */
 function normalizeRightbarOpacity(v) {
 	if (v === null) return null;
@@ -534,20 +468,19 @@ function presetRetryDelayMs(failedAttempt) {
 /**
 * Node half of dsh-background-by-model: file-backed rule persistence.
 *
-* Owns the `~/.dsh/.dsh-background-by-model-data/` store and exposes a small RPC
-* surface on the dedicated `/dsh-background-by-model` channel (never the shared
-* `/api`, so slash commands stay intact).
+* Owns the `~/.dsh/.dsh-background-by-model-data/` store and exposes the RPC
+* surface on the plugin's own `/dsh-background-by-model` channel (never the shared
+* `/api`, which slash commands own).
 *
-*   theme-config.json   the ordered rule list + the global interface settings
-*   modelbg-<slot>      one background image per rule (raw bytes, no extension;
-*                       the MIME is sniffed from the magic bytes when served)
-*   holiday-cache/<tag>/  festival art downloaded from the CDN — one directory
-*                       per pinned release of the asset repository, one file per
-*                       holiday asset inside it, deliberately NOT a slot (below)
+*   theme-config.json     the ordered rule list + the global interface settings
+*   modelbg-<slot>        one background image per rule (raw bytes, no extension;
+*                         the MIME is sniffed from the magic bytes when served)
+*   holiday-cache/<tag>/  festival art downloaded from the CDN, one directory per
+*                         pinned release, deliberately NOT in the slot namespace
 *
-* Images travel as data URLs over the RPC channel — there is no separate HTTP
-* image route. A legacy single-wallpaper / video-background store is migrated
-* to rule 1 on first read.
+* Images travel as data URLs over the RPC channel; there is no separate HTTP image
+* route. A legacy single-wallpaper / video-background store is migrated to rule 1
+* on first read.
 */
 const name = "dsh-background-by-model";
 const inject = ["connection", "webServer"];
@@ -569,105 +502,59 @@ const WALLPAPER_FETCH_TIMEOUT = 2e4;
 /**
 * Where the festival art is hosted, and which revision of it this build wants.
 *
-* The two holiday wallpapers used to ship inside the package. They do not any
-* more: they were 746 KB of the 1.1 MB tarball — two thirds of everything anyone
-* downloaded — for art that is looked at on one day a year, and they are the one
-* part of the package that is a picture rather than code. The bytes now live in
-* the `assets` repository beside the README screenshots and are fetched from a
-* CDN the first time a holiday actually needs one (see `readHolidayAsset`).
+* The art is fetched from the `assets` repository the first time a holiday needs it
+* (see `readHolidayAsset`), never shipped in the package.
 *
-* The reference is a **release tag**, never a branch. Runtime art has to be
-* immutable: a branch reference would let a later reshuffle of the documentation
-* screenshots silently kill a shipped feature, on a day nobody is watching, with
-* nothing in the log — and jsDelivr serves a version reference as immutable,
-* which is exactly what a file that never changes wants. A tag says that to the
-* CDN in the same breath as it says it to a human: `v0.1.0` is the reference the
-* README's screenshots and the recommended profile are read at, so one release
-* of the assets repository is one version of every byte this plugin fetches,
-* where a raw commit hash was a value nobody could compare against anything.
-* The cost is unchanged — new art means a new tag there and a new value here —
-* with one addition: a tag that is MOVED does not reach jsDelivr's edge on its
-* own (the reference is served as immutable), so re-pointing one means a purge
-* request. Cutting a new tag is the cheap move.
+* The reference is a **release tag**, never a branch: runtime art has to be
+* immutable, and a branch reference would let a reshuffle of the documentation
+* screenshots silently kill a shipped feature. One tag also means one version of
+* everything the plugin fetches (art, profile, README screenshots). A MOVED tag
+* does not reach jsDelivr's edge on its own, so new art means a new tag, never a
+* force-push of the old one.
 */
 const HOLIDAY_ASSETS_REPO = "HarmlessFunny/assets";
 const HOLIDAY_ASSETS_REF = "v0.1.0";
 const HOLIDAY_ASSETS_DIR = "dsh-background-by-model/holiday";
 /**
-* Mirrors, tried in order. jsDelivr first because it is reachable from networks
-* where `raw.githubusercontent.com` is not; raw second because a CDN can be
-* blocked, rate-limited or down, and one dead mirror must not cost the easter
-* egg. Every mirror serves the same version, so a fallback cannot mix revisions.
+* Mirrors, tried in order: jsDelivr is reachable where `raw.githubusercontent.com`
+* is not, and raw is the fallback for a CDN that is blocked or down. Both serve the
+* same version, so a fallback cannot mix revisions.
 */
 const HOLIDAY_ASSET_HOSTS = [`https://cdn.jsdelivr.net/gh/${HOLIDAY_ASSETS_REPO}@${HOLIDAY_ASSETS_REF}/${HOLIDAY_ASSETS_DIR}`, `https://raw.githubusercontent.com/${HOLIDAY_ASSETS_REPO}/${HOLIDAY_ASSETS_REF}/${HOLIDAY_ASSETS_DIR}`];
 /**
 * Sub-directory of the store holding downloaded festival art: one directory per
 * release of the asset repository, one file per asset inside it.
 *
-* It is NOT part of the slot namespace and must never become part of it: the
-* cached files are named after the ASSET (`mid-autumn.webp`) and their parent
-* after the release the plugin pins (`v0.1.0`), never after a slot, so nothing
-* here can ever be mistaken for a user's `modelbg-<slot>`. That is what lets a
-* holiday slot stay read-only — `writeImage` still refuses it, and the store
-* still never holds a `modelbg-h-*` file — while the art itself is now fetched
-* rather than shipped.
+* NOT part of the slot namespace, and must never become part of it: files are named
+* after the ASSET and their parent after the pinned release, never after a slot, so
+* nothing here can be mistaken for a user's `modelbg-<slot>`. That is what lets a
+* holiday slot stay read-only while the art itself is downloaded.
 *
-* The version segment is load-bearing. A cache keyed by asset name alone answers
-* a NEW generation with the OLD bytes and says nothing about it, on a day nobody
-* is watching — which is the failure the pinned reference exists to prevent, one
-* layer further down. With the tag in the path, a build that pins a new tag looks
-* in a directory nobody has written to yet, so the first holiday after an update
-* is a cache MISS instead of a stale hit. What happens to the generation that
-* leaves behind is `pruneHolidayCache`.
+* The version segment is load-bearing: a cache keyed by asset name alone would
+* answer a NEW generation with the OLD bytes and say nothing about it. With the tag
+* in the path, a build that pins a new tag looks in a directory nobody has written
+* to yet, so the first holiday after an update is a miss. Superseded generations
+* are swept by `pruneHolidayCache`.
 */
 const HOLIDAY_CACHE_DIR = "holiday-cache";
 /** Cap and timeout for one asset download; these files are 228 KB and 500 KB. */
 const HOLIDAY_FETCH_MAX = 8388608;
 const HOLIDAY_FETCH_TIMEOUT = 1e4;
 /**
-* The recommended profile, served from the same assets repository as the
-* festival art — as a DIRECTORY, in the store's own shape.
-*
-* It used to be one theme file with every wallpaper inlined as base64: 2.9 MB
-* where 99.8% of the bytes were a picture, so changing the `match` string of one
-* rule meant finding it inside a single line of several hundred thousand
-* characters. Now the published layout is exactly the layout of
-* `~/.dsh/.dsh-background-by-model-data/` — a readable `theme-config.json` and
-* one raw file per slot — which makes the configuration editable in place and
-* makes publishing it a `cp` out of the data directory rather than a special
-* export step. The bytes on the wire are the same; only their arrangement is
-* different.
+* The recommended profile, served from the same assets repository as the festival
+* art — as a DIRECTORY in the store's own shape: a readable `theme-config.json`
+* plus one raw file per slot. Publishing it is a `cp` out of the data directory,
+* not an export step.
 *
 * Nothing lists the images: the request set is DERIVED from the config's own
-* `rules[].images[].slot`, so adding a wallpaper is adding a rule entry and a
-* file, with no second place to keep in sync.
-*
-* Referenced by the same **release tag** as the festival art. This used to be a
-* branch, and deliberately: the reason the art is immutable — a reshuffle of the
-* assets repository would make a shipped feature disappear SILENTLY, on a day
-* nobody is watching — does not apply to a profile, because a profile fails
-* LOUDLY (the user is looking at the button and gets an error naming what went
-* missing), and a branch bought the ability to correct a bad recommendation
-* without a plugin release.
-*
-* That trade is now the other way round. What a branch also bought was a plugin
-* whose bytes could change under the user between the build and the click, and
-* with one tag covering the screenshots, the festival art and this profile, one
-* release of the assets repository is one version of everything the plugin
-* fetches — the same value in the README, in `HOLIDAY_ASSETS_REF` and here. The
-* price is that correcting one JSON file now costs a tag in `assets`, a new
-* value in this file and a release on npm, and that MOVING the tag does not
-* reach jsDelivr's edge by itself (it is served as immutable, and the purge tool
-* is the only way to re-point it) — so a correction is a new tag, never a
-* force-push of the old one.
-*
-* The re-pointed-tag case is why `presetKey` survives this change: an edge that
-* has not been purged can still answer with the previous bytes of the same URL,
-* so two fetches of "the profile" are not guaranteed to be one revision, and a
-* press that resumes must not glue them together. See `fetchPresetConfig`.
-*
-* The risk that IS real — a profile written for a config shape this build cannot
-* read — is what `preset.json` exists for (see `fetchPresetConfig`).
+* `rules[].images[].slot`, so adding a wallpaper is a rule entry and a file.
+*
+* Referenced by the same release tag as the art (one tag = one version of
+* everything the plugin fetches). The re-pointed-tag case is why `presetKey`
+* exists: an edge that has not been purged can still answer with the previous
+* bytes of the same URL, and a resumed download must not glue two revisions
+* together (see `fetchPresetConfig`). A profile written for a config shape this
+* build cannot read is refused by the `preset.json` gate.
 */
 const PRESET_ASSETS_REPO = "HarmlessFunny/assets";
 const PRESET_ASSETS_REF = "v0.1.0";
@@ -680,28 +567,18 @@ const PRESET_IMAGE_PREFIX = "modelbg-";
 /** Mirrors, tried in order — same reason as the festival art's. */
 const PRESET_ASSET_HOSTS = [`https://cdn.jsdelivr.net/gh/${PRESET_ASSETS_REPO}@${PRESET_ASSETS_REF}/${PRESET_ASSET_DIR}`, `https://raw.githubusercontent.com/${PRESET_ASSETS_REPO}/${PRESET_ASSETS_REF}/${PRESET_ASSET_DIR}`];
 /**
-* Caps for the profile, now per file rather than for one document.
-*
-* Three of them, because a profile is now a SET of transfers and each has a
-* different way of going wrong. The manifest and the config are small by nature
-* — a manifest is one field, a config is a few kilobytes of JSON — so their caps
-* are what stops a mirror from answering with something enormous instead. The
-* images are the payload, so their cap is about the content.
-*
-* The count is the one that matters: the request set is derived from the config,
-* so a hostile or broken config could name a thousand slots and turn one button
-* press into a thousand downloads. `SLOT_RE` bounds each name and
-* `PRESET_IMAGE_COUNT_MAX` bounds how many names there can be. The running TOTAL
-* of what those transfers add up to is bounded on the client instead, because
-* these calls are independent and this side never sees more than one file.
-*
-* The timeout is set by measurement, not by symmetry with the festival art's
-* 10 s. A 350 KB wallpaper takes a second or two over jsDelivr from a normal
-* connection, and the mirror that exists for the case where jsDelivr does not
-* answer is the slower one — so a tight budget would fail exactly in the
-* situation it was written for. A minute tolerates a slow link and is still
-* bounded; the user is watching a button that says it is downloading, which is
-* the one place waiting is honest.
+* Caps for the profile, now per file rather than for one document: a profile is a
+* SET of transfers, and each has a different way of going wrong.
+*
+* The count is the one that matters — the request set is derived from the config,
+* so a hostile config could name a thousand slots and turn one button press into a
+* thousand downloads. `SLOT_RE` bounds each name, `PRESET_IMAGE_COUNT_MAX` bounds
+* how many there are, and the running TOTAL is bounded on the client, which is the
+* only side that sees more than one file.
+*
+* The timeout is set by measurement: a 350 KB wallpaper takes a second or two over
+* jsDelivr, and the fallback mirror is the slower one, so a tight budget would fail
+* exactly in the situation it exists for.
 */
 const PRESET_MANIFEST_MAX = 65536;
 const PRESET_CONFIG_MAX = 1048576;
@@ -722,19 +599,18 @@ const exists = async (p) => {
 	}
 };
 /**
-* One-shot migration of the pre-0.3 store.
-*
-* Anything without a `rules` array is an old config: its single wallpaper
-* becomes rule 1 (`m1`, empty match = pure fallback) carrying the old color,
-* layout mode, opacity, blur and framing, and the remaining legacy files
-* (background video, upload temp) are removed. Idempotent: the rewritten config
-* carries `rules`, so the next read short-circuits.
-*
-* The one case that is NOT a migration — a store with no config file at all — is
-* handed through untouched rather than being filled in as `rules: []`. That empty
-* list would be the same thing the sanitizer reads as "the user deleted every
-* rule", and a fresh install is the opposite of that: `normalizeConfig` turns a
-* config that names no rule list into the one blank rule the panel opens on.
+* One-shot migration of the pre-0.3 store. Idempotent: the rewritten config carries
+* `rules`, so the next read short-circuits.
+*
+* Anything without a `rules` array is an old config: its single wallpaper becomes
+* rule 1 (`m1`, empty match = pure fallback) carrying the old colour, layout mode,
+* opacity, blur and framing, and the remaining legacy files (background video,
+* upload temp) are removed.
+*
+* A store with NO config file at all is NOT migrated: it is handed through as `{}`.
+* Filling it in as `rules: []` would be the same thing the sanitizer reads as "the
+* user deleted every rule", while a fresh install is the opposite of that —
+* `normalizeConfig` turns a config that names no rule list into one blank rule.
 */
 async function migrateLegacy(raw) {
 	const r = raw ?? {};
@@ -879,10 +755,9 @@ async function writeConfig(config) {
 * not a recognised image at all.
 *
 * The null answer is what a DOWNLOAD is checked against (see `fetchHolidayAsset`):
-* a CDN that answers 200 with an error page, a captive-portal redirect or a
-* truncated body has to be rejected, and neither a status code nor a
-* `content-type` header survives contact with a misconfigured mirror. The magic
-* bytes of the payload are the only claim that cannot lie.
+* neither a status code nor a `content-type` header survives contact with a
+* misconfigured mirror, so the payload's own magic bytes are the only claim that
+* cannot lie.
 */
 function imageMimeOrNull(buf) {
 	if (buf.length >= 4 && buf[0] === 137 && buf[1] === 80 && buf[2] === 78 && buf[3] === 71) return "image/png";
@@ -893,11 +768,9 @@ function imageMimeOrNull(buf) {
 	return null;
 }
 /**
-* Sniff an image's MIME from its leading magic bytes (defaults to JPEG).
-*
-* The default is deliberate for the bytes a USER uploaded: an unrecognised format
-* is better served as a JPEG and left to the browser than refused outright — the
-* browser decides, and it can sniff what this list does not know.
+* Sniff an image's MIME (defaults to JPEG). The default is deliberate for the bytes
+* a USER uploaded: an unrecognised format is better served as a JPEG and left to
+* the browser, which can sniff what this list does not know.
 */
 function sniffImageMime(buf) {
 	return imageMimeOrNull(buf) ?? "image/jpeg";
@@ -905,16 +778,13 @@ function sniffImageMime(buf) {
 /**
 * Read one slot as a data URL, or null when it has nothing to serve.
 *
-* Two very different sources behind one answer. A holiday slot resolves to the
-* festival art — downloaded on demand and cached, never shipped (see
-* `readHolidayAsset`). Everything else is the user's own bytes on disk. Both are
-* resolved lazily, so neither is read, fetched or even looked for until a
-* wallpaper actually needs it.
+* Two sources behind one answer: a holiday slot resolves to the festival art
+* (downloaded on demand, never shipped — see `readHolidayAsset`), everything else is
+* the user's own bytes on disk.
 *
-* `null` is a legitimate answer for a holiday — offline, a blocked CDN, a cold
-* cache — and the caller is built for it: `pickHoliday` treats "no bytes" as
-* "this holiday does not take over" and the model rules keep painting. A
-* festival that cannot be downloaded must never blank the interface.
+* `null` is legitimate for a holiday — offline, a blocked CDN, a cold cache — and
+* the caller is built for it: `pickHoliday` treats "no bytes" as "this holiday does
+* not take over". A festival that cannot be downloaded must never blank the screen.
 */
 async function readImage(slot) {
 	const asset = holidayAssetFor(slot);
@@ -941,16 +811,12 @@ const holidayInFlight = /* @__PURE__ */ new Map();
 * One holiday's art: from the cache if it is there and sound, otherwise from the
 * network.
 *
-* The cached copy is validated rather than trusted — a process killed mid-write
-* (or a full disk) would otherwise leave a permanently truncated file that every
-* later read happily serves, and the holiday would be broken forever with no way
-* back short of deleting a file nobody knows about. A cache entry that is not an
-* image is treated exactly like a miss and overwritten by the next download.
+* The cached copy is VALIDATED rather than trusted: a process killed mid-write would
+* otherwise leave a truncated file that every later read serves, breaking the holiday
+* forever. A cache entry that is not an image is treated as a miss.
 *
-* The in-flight map matters because the two readers can race: the boot hydrate
-* and the midnight rollover timer both ask for the same slot, and the timer
-* fires precisely when a machine that was asleep all day is waking up. Without
-* it that is two simultaneous half-megabyte transfers for one picture.
+* The in-flight map exists because the boot hydrate and the midnight rollover can
+* ask for the same slot at the same moment (a machine waking from sleep).
 */
 async function readHolidayAsset(asset) {
 	const cached = await readFileOrNull(holidayCachePath(asset));
@@ -978,21 +844,14 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
 * One asset over the wire, or WHY it did not arrive.
 *
-* Never throws: a holiday that cannot be fetched is a holiday that does not paint
-* today, and a profile file that cannot be fetched is a sentence on the button —
-* neither is an error path the caller should have to wrap. What it answers with
-* instead is the reason, because the two callers treat those differently: the
-* profile asks `presetRetryable` whether the reason is weather (./preset) and the
-* festival art takes the null and waits for the next apply.
+* Never throws: a festival that cannot be fetched simply does not paint today, and a
+* profile file that cannot be fetched is a sentence on the button. It answers with
+* the reason instead, because the two callers treat it differently — the profile
+* asks `presetRetryable` (./preset), the art waits for the next apply.
 *
-* The `content-length` check is a courtesy — a mirror that announces a huge body
-* never gets to send it — while the post-read size check is the one that holds.
-*
-* Deliberately says nothing about WHAT the bytes are: the festival art and the
-* recommended profile are both "a file from the assets repository", and the one
-* thing they do not share is how a payload is recognised (magic bytes vs JSON).
-* That check belongs to the caller, which is the only half that knows what it
-* asked for.
+* The `content-length` check is a courtesy; the post-read size check is the one that
+* holds. It says nothing about WHAT the bytes are: magic bytes vs JSON is the
+* caller's check, because only the caller knows what it asked for.
 */
 async function fetchAsset(url, max, timeout) {
 	const ctl = new AbortController();
@@ -1034,12 +893,10 @@ async function fetchAsset(url, max, timeout) {
 	}
 }
 /**
-* The status codes worth another round: 5xx is a mirror having a bad moment, 429
-* is one asking to be left alone for a bit, 408 is one giving up on us.
-*
-* Every other non-2xx means the file is not there — jsDelivr answers a path
-* outside the repository with 403, both hosts answer a missing file with 404 — and
-* the profile follows a BRANCH, so that answer has to arrive fast and unchanged.
+* The status codes worth another round: 5xx is a mirror having a bad moment, 429 one
+* asking to be left alone, 408 one giving up on us. Every other non-2xx means the
+* file is not there (jsDelivr answers 403 outside the repository, 404 for a missing
+* file), and that answer must arrive fast and unchanged.
 */
 function fetchFailureForStatus(status) {
 	return status >= 500 || status === 429 || status === 408 ? "server" : "missing";
@@ -1047,11 +904,9 @@ function fetchFailureForStatus(status) {
 /**
 * One festival picture, or null when no mirror served an image.
 *
-* One round, deliberately, unlike the profile's (see `fetchPresetFile`): this is
-* fetched during boot, on the day, before the first wallpaper is painted, and a
-* retry round would add its delay to that first paint. The art does not need one
-* either — it is cached once it arrives, and every later read tries again, while a
-* button press has no later read of its own.
+* One round, unlike the profile's (`fetchPresetFile`): this is fetched during boot,
+* before the first wallpaper is painted, and a retry round would delay that paint.
+* The art is cached once it arrives and every later read tries again.
 */
 async function fetchHolidayAsset(url) {
 	const got = await fetchAsset(url, HOLIDAY_FETCH_MAX, HOLIDAY_FETCH_TIMEOUT);
@@ -1060,13 +915,11 @@ async function fetchHolidayAsset(url) {
 /**
 * One file out of the profile directory, or null when no mirror served it.
 *
-* Every mirror is asked in every round, so a round is "all the hosts there are"
-* and the rounds are the retry: the case this exists for is a mirror that answers
-* 502 on one round and correctly on the next, on the sixth of seven files, with
-* six good downloads behind it. A round in which every failure was terminal — the
-* file is not there, or it is too big — ends the attempts outright, so "the author
-* renamed a file" still costs exactly two requests and a sentence naming the slot
-* (see `presetRetryable`, ./preset).
+* Every mirror is asked in every round, so a round is "all the hosts there are" and
+* the rounds are the retry (a mirror that answers 502 once and correctly the next
+* time, on the sixth of seven files). A round whose failures were all terminal — the
+* file is gone, or too big — ends the attempts outright, so a renamed file costs two
+* requests and a sentence naming the slot (`presetRetryable`, ./preset).
 */
 async function fetchPresetFile(name, max) {
 	for (let attempt = 1; attempt <= 3; attempt++) {
@@ -1084,27 +937,20 @@ async function fetchPresetFile(name, max) {
 /**
 * The profile's shape gate and its configuration, in one answer.
 *
-* Two files, fetched in order, because they answer different questions. The
-* manifest says what SHAPE the config is written for, and a config written for a
-* shape this build cannot read is refused here — before anything is downloaded
-* in earnest and long before anything is deleted. The config then says what the
-* profile IS.
+* Two files in order: the manifest says what SHAPE the config is written for, and a
+* config this build cannot read is refused here — before anything is downloaded in
+* earnest, long before anything is deleted. The config then says what the profile IS.
 *
-* The sanitizer runs on this side, and that is not merely tidiness: the list of
-* images to download is DERIVED from `rules[].images[].slot`, so an unsanitized
-* config would let a remote file choose what this process requests. After
-* `normalizeConfig` every slot has passed `SLOT_RE` (see `normalizeImage`), and
-* the only names left to reject are the holiday slots — which a config CAN name,
-* legally, inside `holidays.items`, and which have no file at all.
+* The sanitizer runs on this side on purpose: the download list is DERIVED from
+* `rules[].images[].slot`, so an unsanitized config would let a remote file choose
+* what this process requests. After `normalizeConfig` every slot has passed `SLOT_RE`
+* (`normalizeImage`). Holiday slots are then DROPPED rather than refused: they are
+* named legally in `holidays.items`, have no file at all, and `writeImage` refuses
+* them anyway, so a rule pointing at one is already inert on the client.
 *
-* Holiday slots are dropped rather than refused. They are unwritable by design
-* (`writeImage` refuses them), so a rule that points at one is already inert on
-* the client; failing the whole profile over a slot nothing could ever fill
-* would be a worse answer than ignoring it.
-*
-* Nothing is cached to disk, unlike the festival art. That cache exists because
-* the art is fetched on a schedule without anyone asking and must work offline
-* afterwards; this is a button whose entire point is to fetch what is there NOW.
+* Nothing is cached to disk, unlike the festival art: that cache exists because the
+* art is fetched on a schedule and must work offline afterwards, while this is a
+* button whose whole point is to fetch what is there NOW.
 */
 async function fetchPresetConfig() {
 	const manifestRaw = await fetchPresetFile(PRESET_MANIFEST, PRESET_MANIFEST_MAX);
@@ -1126,10 +972,14 @@ async function fetchPresetConfig() {
 		ok: false,
 		error: "not a profile"
 	};
-	if (declared > 9) return {
-		ok: false,
-		error: "newer version"
-	};
+	if (declared > 9) {
+		console.warn(`dsh-background-by-model: the recommended profile declares schema ${declared}, this build writes 9`);
+		return {
+			ok: false,
+			error: "newer version"
+		};
+	}
+	if (declared < 9) console.warn(`dsh-background-by-model: the recommended profile is written for schema ${declared}; importing it with defaults for the fields it predates`);
 	const configRaw = await fetchPresetFile(PRESET_CONFIG, PRESET_CONFIG_MAX);
 	if (configRaw === null) return {
 		ok: false,
@@ -1198,11 +1048,9 @@ async function fetchPresetImage(slot) {
 /**
 * Cache one downloaded asset, atomically and best-effort.
 *
-* Written to a temp name and renamed into place, so a reader never sees a partial
-* file even if this process dies between the two calls. A failure to cache is
-* logged and otherwise ignored: the bytes are already in hand and the caller is
-* waiting for them — losing the cache costs a re-download next time, and failing
-* the read over it would cost the holiday.
+* Temp name + rename, so no reader ever sees a partial file. A failure is logged
+* and otherwise ignored: the bytes are in hand and the caller is waiting; losing
+* the cache only costs a re-download.
 */
 async function writeHolidayCache(asset, buf) {
 	try {
@@ -1220,19 +1068,12 @@ async function writeHolidayCache(asset, buf) {
 /**
 * Drop every generation of the cache except the one this build reads.
 *
-* Called AFTER a successful download, never before it, so a generation is only
-* ever removed once its replacement is on disk: a pinned release that turns out
-* to be unreachable must not cost the user the art they already had.
+* Called AFTER a successful download, never before it: a pinned release that turns
+* out to be unreachable must not cost the user the art they already had.
 *
-* It walks the cache ROOT and removes every entry whose name is not this build's
-* tag, so the generation in use cannot be touched however the comparison goes:
-* the entries it compares are generation names, never asset names. That also
-* makes an upgrade clean up after itself — 0.7.9 cached flat `holiday-cache/<asset>`
-* files, which this build never reads and this sweep removes.
-*
-* Best-effort, like the write that calls it: a cache that could not be pruned is
-* a cache with one extra entry in it, and failing a festival over that would be
-* the tail wagging the dog.
+* It walks the cache ROOT and compares GENERATION names, never asset names, so the
+* generation in use cannot be touched. That also makes an upgrade clean up after
+* itself (0.7.9's flat `holiday-cache/<asset>` files are removed here).
 */
 async function pruneHolidayCache() {
 	try {
@@ -1252,11 +1093,8 @@ async function pruneHolidayCache() {
 * The wallpaper a holiday slot resolves to, or null when the slot is not a
 * holiday's.
 *
-* This mapping is the ONLY thing that makes a holiday slot read-only, so both
-* `readImage` and `writeImage` go through it rather than each testing the holiday
-* list on their own. It reads no config: the festival art has stopped being a
-* fallback that a flag could disable. What changed is only WHERE the bytes come
-* from — the slot's identity, and its refusal to accept a write, are untouched.
+* This mapping is the ONLY thing that makes a holiday slot read-only, so `readImage`
+* and `writeImage` both go through it instead of testing the holiday list each.
 */
 function holidayAssetFor(slot) {
 	return HOLIDAYS.find((h) => h.slot === slot)?.asset ?? null;
@@ -1290,22 +1128,19 @@ async function listSlots() {
 /**
 * Empty the store: the config and every rule image, and nothing else.
 *
-* The hard reset behind "use the recommended profile", and it has to be a real
-* one rather than a config overwrite. `nextSlot` hands out `m1`, `m2`, … — a
-* running counter, not a random token — so a profile and a store that both have
-* pictures collide on those names as a matter of course. Emptying first is what
-* makes the profile's own slots free to write, and it is why this feature needs
-* no slot remapping: there is nothing left to collide with.
+* The hard reset behind "use the recommended profile", and it has to be a real one
+* rather than a config overwrite: `nextSlot` hands out `m1`, `m2`, … as a running
+* counter, so a profile and a store that both have pictures collide on those names
+* as a matter of course. Emptying first is what makes the profile's own slots free
+* to write, which is why no slot remapping is needed.
 *
-* `holiday-cache/` is deliberately untouched — every generation of it. It is not
-* the user's configuration: it is downloaded festival art that belongs to no
-* slot, costs a network round trip to get back, and has nothing to do with which
-* profile is selected. Pruning superseded generations is `pruneHolidayCache`'s
-* job, and it is not this one.
+* `holiday-cache/` is deliberately untouched: downloaded art that belongs to no
+* slot and costs a round trip to get back. Pruning generations is
+* `pruneHolidayCache`'s job.
 *
-* Best-effort per entry — one unremovable file must not abort the rest and leave
-* the store half wiped — but the failures are logged rather than swallowed,
-* because the caller is about to write a fresh config over whatever survives.
+* Best-effort per entry (one unremovable file must not leave the store half wiped),
+* but failures are logged, because a fresh config is about to be written over
+* whatever survives.
 */
 async function resetStore() {
 	let ok = true;
@@ -1419,13 +1254,27 @@ function defaultModel(ctx) {
 	} catch {}
 	return null;
 }
-const NS = "dshBackgroundByModel";
 const RPC_CHANNEL = "/dsh-background-by-model";
+/** One request's ceiling. The host's own bridge uses the same number. */
 const RPC_BODY_MAX = 314572800;
-/** Dispatch one decoded RPC method to the matching persistence routine and
-*  return the wire `result` half of the server-response envelope. */
+/** The namespace half of every endpoint on it: `dshBackgroundByModel/read`. */
+const RPC_NS = "dshBackgroundByModel";
+/**
+* One RPC method, as `ConnectionRpcHandler` delivers it: `(endpoint, payload,
+* signal, peer)`, with the endpoint spelled `dshBackgroundByModel/<method>`.
+* Envelope parsing, the body cap, the 401/403 fence and the method-match check
+* belong to the connection service (see `apply`).
+*/
 async function handleRpcMethod(ctx, endpoint, payload) {
-	const method = endpoint.slice(`${NS}/`.length);
+	if (typeof endpoint !== "string") return {
+		ok: false,
+		error: {
+			code: "dsh-background-by-model/bad-request",
+			message: "missing endpoint",
+			details: {}
+		}
+	};
+	const method = endpoint.startsWith(`${RPC_NS}/`) ? endpoint.slice(21) : "";
 	const rawSlot = payload?.slot;
 	const slot = typeof rawSlot === "string" && SLOT_RE.test(rawSlot) ? rawSlot : null;
 	try {
@@ -1550,7 +1399,7 @@ function apply(ctx) {
 					return;
 				}
 				const pathname = new URL(req.url ?? "/", "http://dsh.internal").pathname;
-				const endpoint = pathname.startsWith(`${RPC_CHANNEL}/`) ? pathname.slice(25) : void 0;
+				const endpoint = pathname.startsWith(`/dsh-background-by-model/`) ? pathname.slice(25) : void 0;
 				if (endpoint === void 0 || endpoint.length === 0) {
 					res.writeHead(404);
 					res.end();
@@ -1624,4 +1473,4 @@ function apply(ctx) {
 	});
 }
 //#endregion
-export { apply, inject, name };
+export { RPC_CHANNEL, apply, handleRpcMethod, inject, name };