dsh-custom-theme 0.1.1 → 0.2.0

package/README.md

@@ -24,6 +24,7 @@ Served routes:
 | `GET /dsh-custom-theme/themes` | `{ themes: [{ id, bundled }], dir }` |
 | `GET /dsh-custom-theme/theme/<id>.css` | The stylesheet text |
 | `GET /dsh-custom-theme/backgrounds` | `{ backgrounds: [{ name, url }], dir }` |
+| `POST /dsh-custom-theme/backgrounds?name=<file>` | Stores the body as a picture and answers `{ name, backgrounds, dir }` with the name it stored |
 | `GET /dsh-custom-theme/background/<name>` | The image bytes |
 | `GET /dsh-custom-theme/update` | The cached update state — see [Updates](#updates) |
 | `POST /dsh-custom-theme/update/check` | Asks the registries again, ignoring the cache |
@@ -173,9 +174,25 @@ other's. The page's selector falls back to its built-in entry to match the windo
 
 ## Background images
 
-Drop an image into the background directory (`$DSH_HOME/backgrounds` by default),
-press **Rescan**, and pick it in the **Background image** row. Served extensions
-are `.png .jpg .jpeg .webp .gif .avif .bmp`, up to 16 MiB each.
+Two ways in: press **选择图片…** in the **背景图片** row and pick a file, or drop one
+into the background directory (`$DSH_HOME/backgrounds` by default) and press
+**Rescan**. A picked file is uploaded to the Host, which stores it in that same
+directory, so it becomes the same kind of citizen as one dropped in by hand and every
+zone can select it. Served extensions are `.png .jpg .jpeg .webp .gif .avif .bmp`,
+up to 16 MiB each.
+
+What gets stored is decided by the bytes, not by the file's name or its declared type:
+the Host sniffs the leading bytes and refuses anything that is no served format. The
+name is folded into the ASCII the directory whitelist accepts (`suite upload.png` →
+`suite-upload.png`), and a name already in use stays with the picture that holds it —
+picking the same file twice reuses it, a different picture takes the next free `-1`,
+`-2`, … beside it.
+
+Which zone the controls below edit is chosen in the **workbench**: a row of tabs naming
+each zone, and a schematic of the window whose regions are clickable. Both mark a zone
+that already carries a picture, so the panel answers at a glance what is set where. The
+**整体** label belongs to the whole-window zone, which owns the frame the other regions
+sit inside — dashed while it is empty, solid once it carries a picture.
 
 Each of six zones holds its own image, picture opacity, blur, fit and position:
 
@@ -392,10 +409,13 @@ button: no code is swapped until you click it.
 **Where it shows up.** Both surfaces read the same cached answer:
 
 - A row on **设置 → 主题与背景**, next to the theme and background pickers.
-- Two contributions to the plugin manager's own page for this bundle — a badge beside
-  the title and a section under the page's content, both drawn only when a newer
-  release exists. Every other plugin's page is untouched: an entry renders nothing for
-  a subject it has nothing to say about.
+- Three contributions to the plugin manager's own page for this bundle, each with one
+  job: **升级** in the page's actions area beside the enable switch and uninstall, an
+  *Update available* badge beside the title, and a section under the page's content
+  carrying the version detail and **检查更新**. All three are drawn only when a newer
+  release exists, and every other plugin's page is untouched — an entry renders nothing
+  for a subject it has nothing to say about. The upgrade button lives in one place, so
+  the section does not repeat it.
 
 **Upgrading.** **升级** installs the exact version the check resolved, through the
 plugin manager's own `installBundle`, so the profile's lockfile and bundle list stay
@@ -426,21 +446,31 @@ diagnostic, and the upgrade stays on offer.
 
 Verified against `dsh` 0.2.0-rc.2 on Windows:
 
-- `node --test "test/**/*.test.mjs"` — 35 tests, all passing: id and image-name
+- `node --test "test/**/*.test.mjs"` — 47 tests, all passing: id and image-name
   whitelists, ordering, directory resolution, seeding, re-sync on a new seed
   generation, both asset routes, both listings, traversal, extension and method
-  rejection, and the update surface — semver precedence including prerelease
-  ordering, registry-candidate order and the private-registry rule, the registry
-  query falling through a failure to the next candidate, the cache's success and
-  failure windows, and all three update routes, including that a failed install is
-  reported as a failure rather than as a pending restart.
-- `node test/browser/appearance.mjs` — 33 steps in a real headless Edge, all
+  rejection, image sniffing from the leading bytes, the upload-name fold and its
+  collision rule, and the upload route — that it stores the bytes it was handed, that
+  a name it cannot serve is folded rather than refused, that it cannot be made to name
+  a path outside the directory, and that an oversized, empty or non-image body is
+  refused — and the update surface: semver precedence including prerelease ordering,
+  registry-candidate order and the private-registry rule, the registry query falling
+  through a failure to the next candidate, the cache's success and failure windows, and
+  all three update routes, including that a failed install is reported as a failure
+  rather than as a pending restart.
+- `node test/browser/appearance.mjs` — 35 steps in a real headless Edge, all
   passing. It boots the app, asserts the controls are absent from the chat view and
   still absent once Settings opens, then opens the plugin's own page from the nav
   and drives it. It asserts on rendered state: each bundled theme paints its light
   set and then follows the page's colour-scheme control into its dark set without
   being dropped, the empty option restores a built-in token, a saved theme and
-  background both re-apply on boot before Settings is opened. For backgrounds it
+  background both re-apply on boot before Settings is opened. For the background
+  workbench it checks that every zone is reachable both as a tab and as a schematic
+  region, and that clicking the picture of a zone moves the very selection the tabs
+  report. For the file picker it puts a real `File` on the input — the state the
+  dialog leaves behind — and asserts the picture is uploaded, comes back under the
+  folded name, is added to the listing, is selected for the zone that was being
+  edited, and is genuinely painted on that zone. For backgrounds it
   checks that the picture really is on the layer and not on the surface element, that
   the layer's own alpha is the configured picture opacity while the panel fill stays
   at its per-zone percentage, that a blur lands on the picture layer and nowhere a
@@ -498,6 +528,12 @@ row removes the rows and the palette together.
   geometry match and the finished-turn label. The rotation is driven by a
   `setInterval` on the configured interval.
 
+- **A picked file keeps its bytes, not its name.** The background directory's
+  whitelist is ASCII, and a stored file has to pass it to be listed or served at all,
+  so a name outside it is folded rather than refused: `我的壁纸.png` is stored as
+  `background.png`. The picture and its selection are unaffected. Allowing Unicode
+  names would mean relaxing that whitelist, which is the boundary guarding every read
+  from the directory, so it is left strict.
 - **The page cannot choose its nav icon.** `settings.section` has no icon field;
   the shell maps the entry id to a glyph and falls back to a generic settings gear
   for an id it does not know, which is what this page gets.

package/lib/client.js

@@ -125,6 +125,41 @@ window.__ModuleLoader__.load({
 .dct-update-section { margin-top: 16px; padding-top: 12px; border-top: 1px solid var(--dsw-alias-border-l1, currentColor); }
 .dct-update-section .dct-text { margin-bottom: 8px; }
 .dct-update-section .dct-control { justify-content: flex-start; }
+/* The background workbench: a row of zone tabs above a schematic of the window. Both
+   decide which zone the controls below are editing, so both mark the same two states. */
+.dct-file { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
+.dct-zones { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
+.dct-zone-tab { display: flex; flex-direction: column; gap: 1px; min-width: 0; padding: 5px 10px; font: inherit; text-align: left; color: var(--dsw-alias-label-secondary, inherit); background: var(--dsw-alias-bg-layer-2, transparent); border: 1px solid var(--dsw-alias-border-l1, currentColor); border-radius: 6px; cursor: pointer; }
+.dct-zone-tab:hover { border-color: var(--dsw-alias-border-l2, currentColor); }
+.dct-zone-tab.selected { color: var(--dsw-alias-label-primary, inherit); border-color: var(--dsw-alias-label-primary, currentColor); }
+.dct-zone-tab:disabled { opacity: 0.5; cursor: default; }
+.dct-zone-tab strong { font-size: 13px; font-weight: 500; }
+.dct-zone-tab small { max-width: 130px; overflow: hidden; font-size: 11px; color: var(--dsw-alias-label-caption, inherit); text-overflow: ellipsis; white-space: nowrap; }
+.dct-zone-tab.has-image strong::after { content: "●"; margin-left: 5px; font-size: 8px; vertical-align: middle; }
+.dct-schematic { position: relative; isolation: isolate; display: grid; grid-template-columns: 96px minmax(0, 1fr) 84px; grid-template-rows: 26px minmax(0, 1fr); grid-template-areas: "windowbar windowbar windowbar" "sidebar main dock"; gap: 5px; min-height: 152px; margin-top: 8px; padding: 18px 12px 12px; border-radius: 8px; }
+.dct-schematic button { min-width: 0; display: grid; place-items: center; padding: 5px; font: inherit; font-size: 11px; color: var(--dsw-alias-label-secondary, inherit); background: var(--dsw-alias-bg-layer-2, transparent); border: 1px solid var(--dsw-alias-border-l1, currentColor); border-radius: 6px; cursor: pointer; }
+.dct-schematic button:hover { border-color: var(--dsw-alias-border-l2, currentColor); }
+.dct-schematic button.selected { color: var(--dsw-alias-label-primary, inherit); border-color: var(--dsw-alias-label-primary, currentColor); }
+.dct-schematic button:disabled { opacity: 0.5; cursor: default; }
+.dct-schematic button.has-image::before { content: "●"; margin-right: 4px; font-size: 8px; }
+/* The whole-window zone is the frame the other regions sit inside rather than another
+   region beside them, so it owns the outer border: dashed while that zone is empty,
+   solid once it carries a picture, and highlighted when it is the one being edited.
+   Its label sits in the band the container's top padding leaves free, because every
+   other pixel of the frame is covered by a region.
+   These rules are written as button.dct-schematic-global on purpose: the shared
+   .dct-schematic button rule above is a class plus an element, so it outranks a
+   single class and would otherwise centre this label behind the regions. */
+.dct-schematic button.dct-schematic-global { position: absolute; inset: 0; z-index: 0; display: flex; align-items: flex-start; justify-content: flex-end; padding: 3px 10px; border: 1px dashed var(--dsw-alias-border-l1, currentColor); border-radius: 8px; background: transparent; }
+.dct-schematic button.dct-schematic-global.selected { color: var(--dsw-alias-label-primary, inherit); border-color: var(--dsw-alias-label-primary, currentColor); }
+.dct-schematic button.dct-schematic-global.has-image { border-style: solid; }
+/* The mark sits on the label's line rather than its own, since the frame lays its
+   contents out in a row. */
+.dct-schematic button.dct-schematic-global.has-image::before { margin-top: 3px; }
+.dct-schematic-windowbar { grid-area: windowbar; z-index: 1; position: relative; }
+.dct-schematic-sidebar { grid-area: sidebar; z-index: 1; position: relative; }
+.dct-schematic-dock { grid-area: dock; z-index: 1; position: relative; }
+.dct-schematic-main { grid-area: main; z-index: 1; position: relative; display: grid; grid-template-rows: minmax(0, 1fr) 26px; gap: 5px; }
 `
 
     /** Read the persisted selection; an unreadable store means no selection. */
@@ -184,9 +219,15 @@ window.__ModuleLoader__.load({
             loading: '正在加载…',
             failed: '主题加载失败',
             bgTitle: '背景图片',
-            bgHint: '从背景目录选择图片；也可直接向该目录放入图片文件',
+            bgHint: '选择图片文件，或直接向背景目录放入图片',
             bgConfigured: '部分区域已设置背景',
             bgZone: '区域',
+            bgZonesHint: '点击区域标签或下方示意图，选中要修改的位置',
+            bgSchematic: '布局示意图',
+            bgUnset: '未设置',
+            bgImport: '选择图片…',
+            bgImporting: '上传中…',
+            bgImportFailed: '图片未能上传，请换一张再试',
             bgImage: '图片',
             bgNone: '无',
             bgOpacity: '图片透明度',
@@ -254,9 +295,15 @@ window.__ModuleLoader__.load({
             loading: 'Loading…',
             failed: 'Theme failed to load',
             bgTitle: 'Background image',
-            bgHint: 'Pick an image from the background directory; drop image files in to add them',
+            bgHint: 'Pick a picture file, or drop one into the background directory',
             bgConfigured: 'Some zones have a background',
             bgZone: 'Zone',
+            bgZonesHint: 'Pick a zone from the tabs, or click the layout below',
+            bgSchematic: 'Layout schematic',
+            bgUnset: 'Not set',
+            bgImport: 'Choose a picture…',
+            bgImporting: 'Uploading…',
+            bgImportFailed: 'The picture could not be uploaded; try another one',
             bgImage: 'Image',
             bgNone: 'None',
             bgOpacity: 'Image opacity',
@@ -1246,6 +1293,27 @@ window.__ModuleLoader__.load({
       return Array.isArray(payload.backgrounds) ? payload.backgrounds.map((entry) => entry.name) : []
     }
 
+    /**
+     * Hand one picture the user picked to the Host, which stores it in the background
+     * directory beside the images dropped in by hand.
+     *
+     * The bytes go up as the body and the reported name as a query parameter: the Host
+     * decides the stored name from the bytes and its own directory, so a name it cannot
+     * serve is folded rather than refused.
+     * @param file - The file the picker produced.
+     * @returns The name the Host stored it under.
+     */
+    async function uploadBackground(file) {
+      const response = await fetch(`${BACKGROUNDS_URL}?name=${encodeURIComponent(file.name)}`, {
+        method: 'POST',
+        cache: 'no-store',
+        body: file,
+      })
+      const payload = await response.json().catch(() => ({}))
+      if (!response.ok) throw new Error(payload.error ?? `background upload failed: ${response.status}`)
+      return payload.name
+    }
+
     /*
      * Update state, shared by the two places that show it: this card's own row and
      * the entry contributed to the plugin manager's page. The Host caches its check,
@@ -1362,15 +1430,17 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * The update controls, rendered both as a row on this card and as a section on
-     * the plugin manager's page for this bundle.
-     * @param props - `t` plus `as`, the element and class the controls sit in.
+     * The update controls, rendered as a row on this card and as a section on the
+     * plugin manager's page for this bundle.
+     * @param props - `t`; `as`, the element and class the controls sit in; and
+     *   `primary`, which drops the upgrade button where the page's own actions area
+     *   already carries it, so the same button is never drawn twice on one page.
      */
-    function UpdateRow({ t, as = 'row' }) {
+    function UpdateRow({ t, as = 'row', primary = true }) {
       const snapshot = useUpdate()
       const busy = snapshot.phase === 'loading' || snapshot.phase === 'applying'
       const controls = [
-        canUpgrade(snapshot) ? h('button', {
+        primary && canUpgrade(snapshot) ? h('button', {
           key: 'upgrade',
           type: 'button',
           className: 'dct-button dct-upgrade',
@@ -1415,10 +1485,28 @@ window.__ModuleLoader__.load({
       return h('span', { className: 'dct-update-badge' }, `${t('updateBadge')} ${snapshot.state.latest}`)
     }
 
+    /**
+     * The upgrade button in the plugin page's own actions area, beside its enable
+     * switch and uninstall. Drawn only for this bundle and only when a newer release
+     * exists, so every other plugin's page is left exactly as the shell built it.
+     */
+    function PluginUpdateAction({ subject, t }) {
+      const snapshot = useUpdate()
+      if (!isOwnBundle(subject)) return null
+      if (!canUpgrade(snapshot)) return null
+      const busy = snapshot.phase === 'loading' || snapshot.phase === 'applying'
+      return h('button', {
+        type: 'button',
+        className: 'dct-button dct-upgrade',
+        disabled: busy,
+        onClick: () => { applyUpdateNow() },
+      }, snapshot.phase === 'applying' ? t('updateUpgrading') : `${t('updateUpgrade')} ${snapshot.state.latest}`)
+    }
+
     /** The update section under the plugin page's own content. */
     function PluginUpdateSection({ subject, t }) {
       if (!isOwnBundle(subject)) return null
-      return h(UpdateRow, { t, as: 'section' })
+      return h(UpdateRow, { t, as: 'section', primary: false })
     }
 
     function ThemeRow({ t }) {
@@ -1428,6 +1516,8 @@ window.__ModuleLoader__.load({
       const [images, setImages] = React.useState([])
       const [backgrounds, setBackgrounds] = React.useState(readSavedBackgrounds)
       const [zone, setZone] = React.useState('global')
+      const [importing, setImporting] = React.useState(false)
+      const [importFailed, setImportFailed] = React.useState(false)
       const [preference, setPreference] = React.useState(() => ctx.theme.getTheme().preference)
       const [appearance, setAppearance] = React.useState(readSavedAppearance)
       const [fontSize, setFontSize] = React.useState(() => ctx.theme.getTheme().fontSize)
@@ -1490,6 +1580,33 @@ window.__ModuleLoader__.load({
         })
       }, [zone])
 
+      /** The hidden picker the import button drives. */
+      const fileInput = React.useRef(null)
+
+      /**
+       * Store a picture the user picked, then select it for the zone being edited.
+       *
+       * The picker is cleared before anything else so choosing the same file twice still
+       * fires a change, and the listing is re-read afterwards because the Host decides
+       * the stored name — a name it cannot serve comes back folded.
+       */
+      const onPickFile = React.useCallback(async (event) => {
+        const file = event.target.files && event.target.files[0]
+        event.target.value = ''
+        if (!file) return
+        setImporting(true)
+        setImportFailed(false)
+        try {
+          const stored = await uploadBackground(file)
+          setImages(await listBackgrounds())
+          updateZone({ name: stored })
+        } catch {
+          setImportFailed(true)
+        } finally {
+          setImporting(false)
+        }
+      }, [updateZone])
+
       /** Persist one conversation-stream choice, then redeclare the overrides. */
       const updateAppearance = React.useCallback((patch) => {
         setAppearance((current) => {
@@ -1512,6 +1629,22 @@ window.__ModuleLoader__.load({
       const configured = ZONES.filter((item) => backgrounds[item.id].name !== '').length
       const busy = status === 'loading'
       const noImage = config.name === ''
+      const active = ZONES.find((item) => item.id === zone)
+
+      /**
+       * One clickable region of the layout schematic.
+       *
+       * A region marks itself when its zone already carries a picture, which is the
+       * question the schematic exists to answer at a glance.
+       */
+      const region = (id, extra) => h('button', {
+        type: 'button',
+        className: `${extra}${zone === id ? ' selected' : ''}${backgrounds[id].name === '' ? '' : ' has-image'}`,
+        'data-dct-pick': id,
+        'aria-pressed': zone === id,
+        disabled: busy,
+        onClick: () => setZone(id),
+      }, h('span', null, t(ZONES.find((item) => item.id === id).labelKey)))
 
       return h('div', { className: 'dct-page' },
         h('h2', { className: 'dct-heading' }, t('nav')),
@@ -1603,15 +1736,56 @@ window.__ModuleLoader__.load({
         h('div', { className: 'dct-row dct-sub' },
           h('div', { className: 'dct-text' },
             h('div', { className: 'dct-title' }, t('bgTitle')),
-            h('div', { className: 'dct-hint' }, configured > 0 ? t('bgConfigured') : t('bgHint'))),
+            h('div', { className: 'dct-hint' },
+              importFailed ? t('bgImportFailed') : (configured > 0 ? t('bgConfigured') : t('bgHint')))),
+          h('div', { className: 'dct-control dct-wrap' },
+            h('input', {
+              ref: fileInput,
+              className: 'dct-file',
+              type: 'file',
+              accept: 'image/*',
+              'aria-label': t('bgImport'),
+              onChange: onPickFile,
+            }),
+            h('button', {
+              type: 'button',
+              className: 'dct-button dct-import',
+              disabled: busy || importing,
+              onClick: () => { if (fileInput.current) fileInput.current.click() },
+            }, importing ? t('bgImporting') : t('bgImport')))),
+        /*
+         * The tabs and the schematic are two views of one choice, so either can decide
+         * which zone the controls below edit: the tabs name every zone, the schematic
+         * shows where each one sits in the window. Both mark a zone that already
+         * carries a picture, since that is the question the panel exists to answer.
+         */
+        h('div', { className: 'dct-zones', role: 'group', 'aria-label': t('bgZonesHint') },
+          ZONES.map((item) => h('button', {
+            key: item.id,
+            type: 'button',
+            className: `dct-zone-tab${zone === item.id ? ' selected' : ''}${backgrounds[item.id].name === '' ? '' : ' has-image'}`,
+            'data-dct-tab': item.id,
+            'aria-pressed': zone === item.id,
+            disabled: busy,
+            onClick: () => setZone(item.id),
+          },
+          h('strong', null, t(item.labelKey)),
+          h('small', null, backgrounds[item.id].name === '' ? t('bgUnset') : backgrounds[item.id].name)))),
+        h('div', { className: 'dct-schematic', role: 'group', 'aria-label': t('bgSchematic') },
+          // `global` covers the whole window, so it is drawn as the frame the rest of
+          // the schematic sits inside rather than as another region beside them.
+          region('global', 'dct-schematic-global'),
+          region('windowbar', 'dct-schematic-windowbar'),
+          region('sidebar', 'dct-schematic-sidebar'),
+          h('div', { className: 'dct-schematic-main' },
+            region('conversation', 'dct-schematic-conversation'),
+            region('composer', 'dct-schematic-composer')),
+          region('dock', 'dct-schematic-dock')),
+        h('div', { className: 'dct-row dct-sub' },
+          h('div', { className: 'dct-text' },
+            h('div', { className: 'dct-title' }, `${t('bgZone')} · ${t(active.labelKey)}`),
+            h('div', { className: 'dct-hint' }, noImage ? t('bgUnset') : config.name)),
           h('div', { className: 'dct-control dct-wrap' },
-            h('select', {
-              className: 'dct-select dct-zone',
-              value: zone,
-              disabled: busy,
-              'aria-label': t('bgZone'),
-              onChange: (event) => setZone(event.target.value),
-            }, ZONES.map((item) => h('option', { key: item.id, value: item.id }, t(item.labelKey)))),
             h('select', {
               className: 'dct-select dct-image',
               value: config.name,
@@ -1695,6 +1869,14 @@ window.__ModuleLoader__.load({
          * newer release is worth mentioning. Both entries render null for any other
          * subject; the page's own version and switch stay untouched.
          */
+        ctx.slots.inject('plugins.detail.actions', () => ctx.slots.register({
+          name: 'plugins.detail.actions',
+          id: 'dsh-custom-theme-update',
+          order: 40,
+          label: () => ctx.locale.bind(LOCALE_NS)('updateTitle'),
+          locale: LOCALE_NS,
+        }, PluginUpdateAction))
+
         ctx.slots.inject('plugins.detail.badge', () => ctx.slots.register({
           name: 'plugins.detail.badge',
           id: 'dsh-custom-theme-update',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-custom-theme",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "User-editable CSS themes and background images for the DSH Web GUI and Desktop app, with pickers in Settings",
   "license": "MIT",
   "author": "Sparrived",

package/src/index.mjs

@@ -22,12 +22,15 @@ import {
   MAX_THEME_BYTES,
   SEED_VERSION,
   backgroundContentType,
+  backgroundNameFrom,
   backgroundsDirectory,
   isBackgroundName,
   isBundledThemeId,
   isThemeId,
   orderThemeIds,
+  sniffImageMediaType,
   themesDirectory,
+  uniqueBackgroundName,
 } from './themes.mjs'
 import { PACKAGE_NAME, checkForUpdate, createCache } from './update.mjs'
 
@@ -215,6 +218,70 @@ async function readBackground(directory, name) {
   return bytes.length > MAX_BACKGROUND_BYTES ? undefined : bytes
 }
 
+/**
+ * The background listing the read route and an upload both answer with.
+ * @param directory - Background directory.
+ * @returns `{ backgrounds, dir }`, one served url per image.
+ */
+async function backgroundListing(directory) {
+  const names = await scanBackgrounds(directory)
+  return {
+    backgrounds: names.map((name) => ({ name, url: `${ROUTE_PATH}/background/${encodeURIComponent(name)}` })),
+    dir: directory,
+  }
+}
+
+/**
+ * Store one uploaded picture: read the body under the size cap, identify it from its own
+ * bytes, then write it under a name no existing picture uses.
+ *
+ * The bytes are what lands in the directory, so a picture picked from the file dialog is
+ * the same kind of citizen as one dropped in by hand: every zone can select it, and it
+ * outlives the browser that uploaded it.
+ * @param req - Request carrying the image bytes as its body.
+ * @param url - Parsed request URL; its `name` parameter carries the browser file name.
+ * @param directory - Background directory.
+ * @returns `{ status, body }`; a success body carries the stored name and the new listing.
+ */
+async function receiveBackground(req, url, directory) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > MAX_BACKGROUND_BYTES) {
+      // Stop reading rather than buffer the rest of a body this large.
+      req.destroy()
+      return { status: 413, body: { error: `the picture is larger than ${MAX_BACKGROUND_BYTES} bytes` } }
+    }
+    chunks.push(chunk)
+  }
+  if (size === 0) return { status: 400, body: { error: 'the request carried no picture' } }
+
+  const bytes = Buffer.concat(chunks)
+  const mediaType = sniffImageMediaType(bytes)
+  if (mediaType === undefined) {
+    return { status: 415, body: { error: 'the bytes are no png, jpeg, gif, webp, avif or bmp picture' } }
+  }
+
+  const desired = backgroundNameFrom(url.searchParams.get('name'), mediaType)
+  const taken = await scanBackgrounds(directory)
+  let name = desired
+  if (taken.includes(desired)) {
+    // Picking the same file twice should not pile up copies, but a different picture
+    // that happens to share a name must not overwrite the one already there.
+    const existing = await readFile(join(directory, desired)).catch(() => undefined)
+    if (existing !== undefined && existing.equals(bytes)) {
+      return { status: 200, body: { name: desired, ...await backgroundListing(directory) } }
+    }
+    name = uniqueBackgroundName(desired, taken)
+    if (name === undefined) return { status: 409, body: { error: `no free name is left beside ${desired}` } }
+  }
+
+  await mkdir(directory, { recursive: true })
+  await writeFile(join(directory, name), bytes)
+  return { status: 200, body: { name, ...await backgroundListing(directory) } }
+}
+
 /**
  * Read one theme stylesheet under the id whitelist.
  * @param directory - Theme directory.
@@ -265,6 +332,14 @@ async function handleRoute(req, res, paths) {
     send(res, 200, 'application/json; charset=utf-8', JSON.stringify(answer))
     return
   }
+  // A picture the user picked is posted as the raw body, so it lands in the directory
+  // the same way a dropped-in file does and every zone can then select it. This is a
+  // POST because it writes, and it carries no JSON, so it is read as bytes.
+  if (rest === 'backgrounds' && method === 'POST') {
+    const answer = await receiveBackground(req, url, paths.backgrounds)
+    send(res, answer.status, 'application/json; charset=utf-8', JSON.stringify(answer.body))
+    return
+  }
   if (method !== 'GET' && method !== 'HEAD') {
     send(res, 405, 'text/plain; charset=utf-8', 'method not allowed')
     return
@@ -279,9 +354,7 @@ async function handleRoute(req, res, paths) {
     return
   }
   if (rest === 'backgrounds') {
-    const names = await scanBackgrounds(paths.backgrounds)
-    const backgrounds = names.map((name) => ({ name, url: `${ROUTE_PATH}/background/${encodeURIComponent(name)}` }))
-    send(res, 200, 'application/json; charset=utf-8', JSON.stringify({ backgrounds, dir: paths.backgrounds }))
+    send(res, 200, 'application/json; charset=utf-8', JSON.stringify(await backgroundListing(paths.backgrounds)))
     return
   }
   const theme = /^theme\/([^/]+)\.css$/u.exec(rest)

package/src/themes.mjs

@@ -107,6 +107,92 @@ export function backgroundContentType(name) {
   return BACKGROUND_TYPES.get(name.slice(name.lastIndexOf('.')).toLowerCase()) ?? 'application/octet-stream'
 }
 
+/** The extension a stored upload of each accepted media type gets. */
+const EXTENSION_BY_MEDIA_TYPE = new Map([
+  ['image/png', '.png'],
+  ['image/jpeg', '.jpg'],
+  ['image/gif', '.gif'],
+  ['image/webp', '.webp'],
+  ['image/avif', '.avif'],
+  ['image/bmp', '.bmp'],
+])
+
+/**
+ * The image formats this plugin accepts, each identified by its leading bytes.
+ *
+ * Both the declared content type and the file-name extension arrive from the browser
+ * and neither is trustworthy, so an upload is stored under the format its own bytes
+ * show rather than the one it claims.
+ */
+const IMAGE_SIGNATURES = [
+  { mediaType: 'image/png', test: (bytes) => bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 && bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a },
+  { mediaType: 'image/jpeg', test: (bytes) => bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff },
+  { mediaType: 'image/gif', test: (bytes) => bytes.length >= 6 && bytes.subarray(0, 4).toString('latin1') === 'GIF8' },
+  { mediaType: 'image/webp', test: (bytes) => bytes.length >= 12 && bytes.subarray(0, 4).toString('latin1') === 'RIFF' && bytes.subarray(8, 12).toString('latin1') === 'WEBP' },
+  { mediaType: 'image/avif', test: (bytes) => bytes.length >= 12 && bytes.subarray(4, 8).toString('latin1') === 'ftyp' && ['avif', 'avis'].includes(bytes.subarray(8, 12).toString('latin1')) },
+  { mediaType: 'image/bmp', test: (bytes) => bytes.length >= 2 && bytes[0] === 0x42 && bytes[1] === 0x4d },
+]
+
+/**
+ * Identify an uploaded image from its leading bytes.
+ * @param bytes - The uploaded bytes.
+ * @returns The media type, or `undefined` when the bytes are no format this plugin serves.
+ */
+export function sniffImageMediaType(bytes) {
+  if (!Buffer.isBuffer(bytes)) return undefined
+  for (const signature of IMAGE_SIGNATURES) {
+    if (signature.test(bytes)) return signature.mediaType
+  }
+  return undefined
+}
+
+/**
+ * Turn the file name a browser reported into one this plugin will serve.
+ *
+ * The background directory's whitelist is ASCII, and a stored file has to pass it to be
+ * listed or served at all, so everything outside it is folded into dashes here rather
+ * than refused — an upload the user asked for should not fail over its name. The
+ * extension comes from the sniffed bytes, never from the request.
+ * @param original - File name the browser reported, possibly as a full path.
+ * @param mediaType - Media type accepted by {@link sniffImageMediaType}.
+ * @returns A name accepted by {@link isBackgroundName}, or `undefined` for an unserved type.
+ */
+export function backgroundNameFrom(original, mediaType) {
+  const extension = EXTENSION_BY_MEDIA_TYPE.get(mediaType)
+  if (extension === undefined) return undefined
+  // Some platforms report a full path, so only the last segment is a name.
+  const base = String(original ?? '').split(/[\\/]/u).pop() ?? ''
+  const stem = base
+    .replace(/\.[^.]*$/u, '')
+    .replace(/[^A-Za-z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '')
+    .slice(0, 48)
+    // A name cut mid-separator would otherwise end on a dash.
+    .replace(/-+$/gu, '')
+  return `${stem === '' ? 'background' : stem}${extension}`
+}
+
+/**
+ * Pick a name no existing entry uses, so an upload never overwrites a picture the user
+ * already had in the directory.
+ * @param name - Desired name, already accepted by {@link isBackgroundName}.
+ * @param taken - Names already present in the directory.
+ * @returns `name`, the same stem with the first free `-<n>` suffix, or `undefined` when none is free.
+ */
+export function uniqueBackgroundName(name, taken) {
+  const used = new Set(taken)
+  if (!used.has(name)) return name
+  const dot = name.lastIndexOf('.')
+  if (dot <= 0) return undefined
+  const stem = name.slice(0, dot)
+  const extension = name.slice(dot)
+  for (let index = 1; index < 1000; index += 1) {
+    const candidate = `${stem}-${index}${extension}`
+    if (!used.has(candidate)) return candidate
+  }
+  return undefined
+}
+
 /**
  * Resolve the background directory: an explicit `backgroundsDir` config value
  * wins, then `<home>/backgrounds`. Nothing is seeded here; the directory only