dsh-custom-theme 0.1.0 → 0.1.1

package/README.md

@@ -1,5 +1,8 @@
 # dsh-custom-theme
 
+[![npm version](https://img.shields.io/npm/v/dsh-custom-theme.svg)](https://www.npmjs.com/package/dsh-custom-theme)
+[![license](https://img.shields.io/npm/l/dsh-custom-theme.svg)](https://github.com/Sparrived/dsh-custom-theme/blob/main/LICENSE)
+
 User-editable CSS themes for the DeepSeek Harness Web GUI and Desktop app.
 
 This ports the one UI-customization capability DSH does not have: a theme
@@ -22,6 +25,13 @@ Served routes:
 | `GET /dsh-custom-theme/theme/<id>.css` | The stylesheet text |
 | `GET /dsh-custom-theme/backgrounds` | `{ backgrounds: [{ name, url }], dir }` |
 | `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 |
+| `POST /dsh-custom-theme/update/apply` | Installs the release the last check resolved |
+
+The plugin also watches its own releases: it reports a newer one and upgrades to it on
+request, from its settings card or from the plugin manager's page for this bundle. See
+[Updates](#updates).
 
 Adding a theme is dropping a `.css` file into the theme directory and pressing
 **Rescan**; the file only needs to override `--dsw-alias-*` custom properties.
@@ -288,31 +298,44 @@ grant. **This package does not need either.** `src/index.mjs` (Host) and
 load directly, so there is no build step for `prepare` to run and nothing to
 allowlist: the install completes with no code-execution prompt.
 
-### From a tarball, or from npm
-
-Both ship the same prebuilt code:
+### From npm
 
 ```sh
-pnpm pack                                                   # -> dsh-custom-theme-0.1.0.tgz
-dsh plugin --profile <name> add ./dsh-custom-theme-0.1.0.tgz
+dsh plugin --profile <name> add dsh-custom-theme
 ```
 
+### From a tarball
+
+`pnpm pack` produces the same prebuilt code as a single file:
+
 ```sh
-dsh plugin --profile <name> add dsh-custom-theme             # after an npm release
+pnpm pack                                                        # -> dsh-custom-theme-<version>.tgz
+dsh plugin --profile <name> add ./dsh-custom-theme-<version>.tgz
 ```
 
-For the maintainer, publishing a release is:
+### Releasing (maintainer)
 
 ```sh
-git tag v0.1.0 && git push origin v0.1.0
-gh release create v0.1.0 --title v0.1.0 --notes-file CHANGELOG.md
-pnpm publish --access public                                # optional; needs npm auth
+git tag v<version> && git push origin v<version>
+pnpm pack
+gh release create v<version> --title v<version> --notes-file CHANGELOG.md \
+  dsh-custom-theme-<version>.tgz
+npm publish --access public
 ```
 
+npm requires two-factor authentication for **every** publish. A passkey (Windows
+Hello) has no 6-digit code to type, so the publishing token must carry the bypass:
+create a **Granular Access Token** with **Bypass two-factor authentication (2FA)**
+ticked and `Read and write` on packages. A token without that flag is refused with
+`E403 ... granular access token with bypass 2fa enabled is required to publish`,
+and weakening the account's 2FA mode to `auth-only` does not change that.
+
 ### Configuring the directories
 
 `themesDir` and `backgroundsDir` can be overridden on the row; otherwise
-`$DSH_HOME/themes` and `$DSH_HOME/backgrounds` are used:
+`$DSH_HOME/themes` and `$DSH_HOME/backgrounds` are used. `updateCheck: false` skips
+the update check at boot, while the settings card's own button and both routes keep
+working:
 
 ```yaml
 - id: custom-theme
@@ -320,6 +343,7 @@ pnpm publish --access public                                # optional; needs np
   config:
     themesDir: D:/themes/dsh
     backgroundsDir: D:/wallpapers/dsh
+    updateCheck: true
 ```
 
 ### Desktop app
@@ -356,14 +380,60 @@ override the target, the debugging port and where screenshots land. The test
 imports `test/browser/driver.mjs`, a small CDP driver over Node's built-in
 `WebSocket`; no browser automation dependency is installed.
 
+## Updates
+
+The plugin checks npm for a newer release once per boot and caches the answer for six
+hours; a failed check is cached for one minute, so a blip cannot hide an update for
+the rest of the window. A manual **检查更新** ignores the cache.
+
+Nothing is replaced behind your back. The check only reports, and the upgrade is a
+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.
+
+**Upgrading.** **升级** installs the exact version the check resolved, through the
+plugin manager's own `installBundle`, so the profile's lockfile and bundle list stay
+consistent with anything you install from the Plugins page. Replacing a package cannot
+hot-swap the Host module, so an upgrade always ends with *restart DeepSeek Harness*;
+the row then says so instead of offering the same upgrade again.
+
+**Which registry.** The check asks the profile's plugin-manager configuration, in its
+order: the configured registry, then the one pnpm resolves, then the configured
+fallbacks. A mirror or private registry therefore stays authoritative and is never
+silently widened to the public one. With nothing configured, that resolves to
+`https://registry.npmjs.org/`.
+
+**Routes**, under the plugin's prefix and reachable with the page's own token:
+
+| Route | Method | Answers |
+| --- | --- | --- |
+| `/dsh-custom-theme/update` | `GET` | The cached state: running version, latest, whether it is an upgrade, and the registry that answered. |
+| `/dsh-custom-theme/update/check` | `POST` | Asks the registries again, ignoring the cache. |
+| `/dsh-custom-theme/update/apply` | `POST` | Installs the release the last check resolved. |
+
+Only the two actions answer `POST`: a `GET` stays safe for a link, a prefetch or an
+`<img>`, none of which may start an install. A run that does not end in `applied` or
+`restart-required` is reported as an error carrying the plugin manager's own
+diagnostic, and the upgrade stays on offer.
+
 ## Verify
 
 Verified against `dsh` 0.2.0-rc.2 on Windows:
 
-- `node --test "test/**/*.test.mjs"` — 14 tests, all passing: id and image-name
+- `node --test "test/**/*.test.mjs"` — 35 tests, all passing: id and image-name
   whitelists, ordering, directory resolution, seeding, re-sync on a new seed
-  generation, both asset routes, both listings, and traversal, extension and
-  method rejection.
+  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
   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
@@ -379,7 +449,14 @@ Verified against `dsh` 0.2.0-rc.2 on Windows:
   every injected layer rule. Finally, with the panel closed, since the panel is
   portalled over the whole window, it asserts that the image is what
   `elementFromPoint` actually finds at a point inside each zone — which is what keeps
-  the negative-`z-index` layer from silently disappearing behind a surface.
+  the negative-`z-index` layer from silently disappearing behind a surface. That
+  sampling is the one thing DSH's own UI can disturb: a freshly created profile opens
+  the `预览版说明` first-run notice, whose backdrop covers the window and answers every
+  `elementFromPoint` query, so those four visibility steps read nothing even though the
+  assertions before them — which read the tagged surfaces and the layers beside them
+  directly — still pass. The suite dismisses the notice after boot and again before
+  sampling, so it is verified both on a freshly created profile and on a long-lived
+  one.
 - `node test/browser/working-row.mjs` — 5 steps against a session that already has
   turns. It reads the shipped row's computed geometry, asserts the replacement is
   absent while no phrase is configured, configures one, then compares the
@@ -465,6 +542,17 @@ row removes the rows and the palette together.
   `::before` on one of these surfaces would collide with it; the plugin's rule sets
   `content`, `position`, `inset`, `z-index` and the picture, so the shell's own
   `::before` content would be replaced rather than merged.
+- **An upgrade needs a restart.** Replacing a package cannot hot-swap the Host module,
+  so after an upgrade the new code is on disk while the running process keeps the old
+  one. The row says a restart is pending rather than offering the same upgrade again;
+  the Browser half comes back with that restart too.
+- **The update check needs the plugin-manager service.** Without it the row reports
+  that updates cannot be checked rather than guessing. That service names the
+  registries to ask and performs the install, which is why the check follows its
+  configuration instead of a hard-coded URL.
+- **A check answers from a six-hour cache.** The boot check and the first page open
+  share one answer, so a release published in between waits for the next window or for
+  **检查更新**.
 - **No Schemastery `Config` schema**, so `config` is read defensively and never
   validated. That is also why the package carries no peer dependencies at all.
 - **No live file watching.** A new or edited file needs **Rescan**, and an edited

package/lib/client.js

@@ -22,6 +22,9 @@ window.__ModuleLoader__.load({
     const CSS_URL = (id) => `/dsh-custom-theme/theme/${encodeURIComponent(id)}.css`
     const BACKGROUNDS_URL = '/dsh-custom-theme/backgrounds'
     const BACKGROUND_URL = (name) => `/dsh-custom-theme/background/${encodeURIComponent(name)}`
+    const UPDATE_URL = '/dsh-custom-theme/update'
+    const UPDATE_CHECK_URL = '/dsh-custom-theme/update/check'
+    const UPDATE_APPLY_URL = '/dsh-custom-theme/update/apply'
     const STORAGE_KEY = 'dsh-custom-theme.selected'
     const STORAGE_KEY_BACKGROUNDS = 'dsh-custom-theme.backgrounds'
     const LOCALE_NS = 'dshCustomTheme'
@@ -116,6 +119,12 @@ window.__ModuleLoader__.load({
 .dct-area { width: 260px; min-height: 54px; padding: 4px 8px; font: inherit; font-size: 13px; color: var(--dsw-alias-label-primary, inherit); background: var(--dsw-alias-bg-layer-2, transparent); border: 1px solid var(--dsw-alias-border-l1, currentColor); border-radius: 6px; resize: vertical; }
 .dct-area::placeholder { color: var(--dsw-alias-label-caption, currentColor); opacity: 0.85; }
 .dct-sub .dct-wrap .dct-input { width: 130px; }
+/* The update row, the badge beside the plugin page's title, and the section that
+   page renders under its own content. */
+.dct-update-badge { padding: 2px 8px; font-size: 12px; color: var(--dsw-alias-label-primary, inherit); background: var(--dsw-alias-bg-layer-2, transparent); border: 1px solid var(--dsw-alias-border-l1, currentColor); border-radius: 10px; }
+.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; }
 `
 
     /** Read the persisted selection; an unreadable store means no selection. */
@@ -198,6 +207,19 @@ window.__ModuleLoader__.load({
             posBottom: '底部',
             posLeft: '左侧',
             posRight: '右侧',
+            updateTitle: '插件更新',
+            updateHint: '从 npm 检查这个插件的新版本；升级会自动装好，重启后生效',
+            updateCurrent: '当前版本',
+            updateCheck: '检查更新',
+            updateChecking: '检查中…',
+            updateLatest: '最新版本',
+            updateUpgrade: '升级',
+            updateUpgrading: '升级中…',
+            updateRestart: '新版本已装好，重启 DeepSeek Harness 后生效',
+            updateUpToDate: '已是最新版本',
+            updateUnavailable: '插件管理器不可用，无法检查更新',
+            updateFailed: '检查更新失败',
+            updateBadge: '有更新',
           },
           en: {
             nav: 'Theme & background',
@@ -255,6 +277,19 @@ window.__ModuleLoader__.load({
             posBottom: 'Bottom',
             posLeft: 'Left',
             posRight: 'Right',
+            updateTitle: 'Plugin update',
+            updateHint: 'Checks npm for a newer release; upgrading installs it, and a restart makes it active',
+            updateCurrent: 'Installed',
+            updateCheck: 'Check for updates',
+            updateChecking: 'Checking…',
+            updateLatest: 'Latest',
+            updateUpgrade: 'Upgrade',
+            updateUpgrading: 'Upgrading…',
+            updateRestart: 'Installed; restart DeepSeek Harness to activate it',
+            updateUpToDate: 'Up to date',
+            updateUnavailable: 'The plugin manager is unavailable, so updates cannot be checked',
+            updateFailed: 'The update check failed',
+            updateBadge: 'Update available',
           },
         }))
 
@@ -1211,6 +1246,181 @@ window.__ModuleLoader__.load({
       return Array.isArray(payload.backgrounds) ? payload.backgrounds.map((entry) => entry.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,
+     * so both surfaces read one request instead of racing two.
+     */
+    /** This package's name, which the detail-page subject is matched against. */
+    const PLUGIN_PACKAGE = 'dsh-custom-theme'
+
+    /** Latest snapshot: `phase` is `idle`, `loading`, `applying` or `failed`. */
+    let updateSnapshot = { phase: 'idle', state: null, reason: '', result: null }
+    const updateListeners = new Set()
+
+    /** Publish a snapshot to every mounted surface. */
+    function publishUpdate(next) {
+      updateSnapshot = next
+      for (const listener of updateListeners) listener(next)
+    }
+
+    /** The current snapshot without subscribing, for a mount that just needs it. */
+    function readUpdate() {
+      return updateSnapshot
+    }
+
+    /** The in-flight load, so two surfaces mounting together ask the Host once. */
+    let updateLoad = null
+
+    /**
+     * Load the Host's update state.
+     * @param options - `force` asks the Host to query the registries again rather
+     *   than answer from its cache.
+     */
+    function loadUpdate({ force = false } = {}) {
+      if (updateLoad !== null) return updateLoad
+      const promise = (async () => {
+        publishUpdate({ ...updateSnapshot, phase: 'loading', reason: '' })
+        try {
+          const response = force
+            ? await fetch(UPDATE_CHECK_URL, { method: 'POST', cache: 'no-store' })
+            : await fetch(UPDATE_URL, { cache: 'no-store' })
+          if (!response.ok) throw new Error(`HTTP ${response.status}`)
+          publishUpdate({ phase: 'idle', state: await response.json(), reason: '', result: null })
+        } catch (error) {
+          publishUpdate({ ...updateSnapshot, phase: 'failed', reason: error.message })
+        }
+      })()
+      updateLoad = promise
+      const clear = () => { if (updateLoad === promise) updateLoad = null }
+      promise.then(clear, clear)
+      return promise
+    }
+
+    /** Install the release the last check resolved, then re-read what the Host reports. */
+    async function applyUpdateNow() {
+      publishUpdate({ ...updateSnapshot, phase: 'applying', reason: '' })
+      try {
+        const response = await fetch(UPDATE_APPLY_URL, { method: 'POST', cache: 'no-store' })
+        if (!response.ok) throw new Error(`HTTP ${response.status}`)
+        const result = await response.json()
+        if (result.status !== 'ok') {
+          publishUpdate({ ...updateSnapshot, phase: 'failed', reason: result.reason ?? '' })
+          return
+        }
+        // The Host now reports a pending restart in place of the same upgrade.
+        await loadUpdate()
+        publishUpdate({ ...readUpdate(), result })
+      } catch (error) {
+        publishUpdate({ ...updateSnapshot, phase: 'failed', reason: error.message })
+      }
+    }
+
+    /** Subscribe to the shared snapshot, loading it once per page. */
+    function useUpdate() {
+      const [snapshot, setSnapshot] = React.useState(readUpdate)
+      React.useEffect(() => {
+        updateListeners.add(setSnapshot)
+        setSnapshot(readUpdate())
+        // A failed load leaves no state behind, so reopening a surface retries it.
+        if (readUpdate().state === null) loadUpdate()
+        return () => { updateListeners.delete(setSnapshot) }
+      }, [])
+      return snapshot
+    }
+
+    /**
+     * The line of state text under the update controls.
+     * @param snapshot - The shared snapshot.
+     * @param t - Translate function for this plugin's namespace.
+     * @returns One sentence describing what the Host reported.
+     */
+    function updateText(snapshot, t) {
+      const state = snapshot.state
+      // A failure outranks the state text: the state still describes the release it
+      // found, so repeating that here would hide why the upgrade did not happen.
+      if (snapshot.phase === 'failed') return `${t('updateFailed')}: ${snapshot.reason}`
+      if (state === null) return t('updateChecking')
+      // A finished upgrade outranks everything else the state could say: the files
+      // are in place, and only a restart is left.
+      if (state.pendingRestart !== undefined && state.pendingRestart !== null) {
+        return `${t('updateRestart')} (${state.pendingRestart})`
+      }
+      if (state.status === 'unavailable') return t('updateUnavailable')
+      if (state.status !== 'ok') return `${t('updateFailed')}: ${state.reason ?? ''}`
+      if (state.updateAvailable === true) return `${t('updateLatest')} ${state.latest}`
+      return `${t('updateUpToDate')} (${state.current})`
+    }
+
+    /** Whether the shared snapshot justifies offering the upgrade control. */
+    function canUpgrade(snapshot) {
+      const state = snapshot.state
+      return state !== null
+        && state.status === 'ok'
+        && state.updateAvailable === true
+        && (state.pendingRestart === undefined || state.pendingRestart === null)
+    }
+
+    /**
+     * 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.
+     */
+    function UpdateRow({ t, as = 'row' }) {
+      const snapshot = useUpdate()
+      const busy = snapshot.phase === 'loading' || snapshot.phase === 'applying'
+      const controls = [
+        canUpgrade(snapshot) ? h('button', {
+          key: 'upgrade',
+          type: 'button',
+          className: 'dct-button dct-upgrade',
+          disabled: busy,
+          onClick: () => { applyUpdateNow() },
+        }, snapshot.phase === 'applying' ? t('updateUpgrading') : `${t('updateUpgrade')} ${snapshot.state.latest}`) : null,
+        h('button', {
+          key: 'check',
+          type: 'button',
+          className: 'dct-button dct-check-update',
+          disabled: busy,
+          onClick: () => { loadUpdate({ force: true }) },
+        }, snapshot.phase === 'loading' ? t('updateChecking') : t('updateCheck')),
+      ]
+      const body = [
+        h('div', { key: 'text', className: 'dct-text' },
+          h('div', { className: 'dct-title' }, t('updateTitle')),
+          h('div', { className: 'dct-hint' }, updateText(snapshot, t))),
+        h('div', { key: 'control', className: 'dct-control' }, controls),
+      ]
+      return as === 'section'
+        ? h('section', { className: 'dct-update-section' }, body)
+        : h('div', { className: 'dct-row dct-update-row' }, body)
+    }
+
+    /** Whether a detail-page subject is this plugin's own bundle. */
+    function isOwnBundle(subject) {
+      return subject !== null && subject !== undefined
+        && subject.kind === 'bundle'
+        && subject.pkg !== undefined
+        && subject.pkg.name === PLUGIN_PACKAGE
+    }
+
+    /**
+     * The badge beside the plugin's title, drawn only when a newer release exists.
+     * Every other subject renders nothing, which is what the slot expects.
+     */
+    function PluginUpdateBadge({ subject, t }) {
+      const snapshot = useUpdate()
+      if (!isOwnBundle(subject)) return null
+      if (!canUpgrade(snapshot)) return null
+      return h('span', { className: 'dct-update-badge' }, `${t('updateBadge')} ${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' })
+    }
+
     function ThemeRow({ t }) {
       const [themes, setThemes] = React.useState([])
       const [selected, setSelected] = React.useState(readSaved)
@@ -1465,6 +1675,7 @@ window.__ModuleLoader__.load({
               disabled: noImage,
               onClick: () => updateZone({ name: '' }),
             }, t('bgClear')))),
+        h(UpdateRow, { t }),
         status === 'failed' ? h('div', { className: 'dct-error', role: 'status' }, t('failed')) : null)
     }
 
@@ -1478,6 +1689,28 @@ window.__ModuleLoader__.load({
           locale: LOCALE_NS,
         }, ThemeRow))
 
+        /*
+         * The plugin manager's own page declares these list slots so a bundle can
+         * speak about itself where users manage plugins, which is the one place a
+         * 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.badge', () => ctx.slots.register({
+          name: 'plugins.detail.badge',
+          id: 'dsh-custom-theme-update',
+          order: 40,
+          label: () => ctx.locale.bind(LOCALE_NS)('updateTitle'),
+          locale: LOCALE_NS,
+        }, PluginUpdateBadge))
+
+        ctx.slots.inject('plugins.detail.section', () => ctx.slots.register({
+          name: 'plugins.detail.section',
+          id: 'dsh-custom-theme-update',
+          order: 40,
+          label: () => ctx.locale.bind(LOCALE_NS)('updateTitle'),
+          locale: LOCALE_NS,
+        }, PluginUpdateSection))
+
         /*
          * The running label is `chat.deepDiving`, owned by the shell's `chat`
          * namespace. `ctx.locale.register` throws for a namespace and locale that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-custom-theme",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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

@@ -29,6 +29,7 @@ import {
   orderThemeIds,
   themesDirectory,
 } from './themes.mjs'
+import { PACKAGE_NAME, checkForUpdate, createCache } from './update.mjs'
 
 /**
  * Prefix route owned by this plugin. `dsh-client-ui-theme` and the SPA dist use
@@ -43,8 +44,43 @@ const ROUTE_PATH = '/dsh-custom-theme'
 /** Seeded stylesheets live beside the package root, one level above this module. */
 const SEED_ROOT = fileURLToPath(new URL('../themes/', import.meta.url))
 
+/**
+ * This package's manifest, read for the version the update check compares against.
+ * The manifest ships in the published tarball, so the lookup never depends on a
+ * checkout being present.
+ */
+const PACKAGE_JSON = fileURLToPath(new URL('../package.json', import.meta.url))
+
 export const name = 'dsh-custom-theme'
 
+/**
+ * Read the version this build runs.
+ * @returns The version, or `undefined` when the manifest is missing or malformed;
+ *   the update check then reports that it cannot compare rather than guessing.
+ */
+async function readOwnVersion() {
+  try {
+    const manifest = JSON.parse(await readFile(PACKAGE_JSON, 'utf8'))
+    return typeof manifest?.version === 'string' ? manifest.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * One log line for an update state.
+ * @param state - A state from the update module.
+ * @returns Text for the startup log.
+ */
+function describeState(state) {
+  if (state.status === 'ok') {
+    return state.updateAvailable
+      ? `${state.latest} is available (running ${state.current}, from ${state.registry})`
+      : `running the latest release (${state.current}, from ${state.registry})`
+  }
+  return `${state.status}: ${state.reason}`
+}
+
 /**
  * Resolve the DSH home, honouring the environment override the runtime sets.
  * @returns The home directory whose `themes` directory this plugin owns.
@@ -198,27 +234,45 @@ async function readTheme(directory, id) {
 }
 
 /**
- * Answer the listing, stylesheet and background routes. Every other path under
- * the prefix is a 404; the route is `prefix`, so this handler owns the whole
+ * Answer the listing, stylesheet, background and update routes. Every other path
+ * under the prefix is a 404; the route is `prefix`, so this handler owns the whole
  * subtree.
  * @param req - Request from the application origin.
  * @param res - Response owned by this handler.
- * @param paths - `themes` and `backgrounds` directories, plus `ready`, which
- *   settles once the initial seeding pass finished, so a request that arrives
- *   during startup never scans a directory that does not exist yet.
+ * @param paths - `themes` and `backgrounds` directories, `ready`, which settles
+ *   once the initial seeding pass finished, and `updates`, the update state's
+ *   `state`, `check` and `apply` handlers.
  */
 async function handleRoute(req, res, paths) {
   await paths.ready
   const url = new URL(req.url ?? '/', 'http://localhost')
-  if (req.method !== 'GET' && req.method !== 'HEAD') {
-    send(res, 405, 'text/plain; charset=utf-8', 'method not allowed')
-    return
-  }
   const rest = decodePath(url.pathname.slice(ROUTE_PATH.length + 1))
   if (rest === undefined) {
     send(res, 400, 'text/plain; charset=utf-8', 'malformed path')
     return
   }
+  const method = req.method ?? 'GET'
+
+  // The two update actions change the profile, so they answer POST only. A GET has
+  // to stay safe for a link, a prefetch or an image, none of which may start an
+  // install; that also keeps a cross-site navigation from reaching them.
+  if (rest === 'update/check' || rest === 'update/apply') {
+    if (method !== 'POST') {
+      send(res, 405, 'text/plain; charset=utf-8', 'method not allowed')
+      return
+    }
+    const answer = rest === 'update/check' ? await paths.updates.check() : await paths.updates.apply()
+    send(res, 200, 'application/json; charset=utf-8', JSON.stringify(answer))
+    return
+  }
+  if (method !== 'GET' && method !== 'HEAD') {
+    send(res, 405, 'text/plain; charset=utf-8', 'method not allowed')
+    return
+  }
+  if (rest === 'update') {
+    send(res, 200, 'application/json; charset=utf-8', JSON.stringify(await paths.updates.state()))
+    return
+  }
   if (rest === 'themes') {
     const themes = (await scanThemes(paths.themes)).map((id) => ({ id, bundled: isBundledThemeId(id) }))
     send(res, 200, 'application/json; charset=utf-8', JSON.stringify({ themes, dir: paths.themes }))
@@ -275,11 +329,132 @@ export function apply(ctx, config) {
     ctx.logger.warn('dsh-custom-theme: preparing directories failed: %s', error.message)
   })
 
+  /*
+   * The update check needs two things the row cannot demand: the version this build
+   * runs, and the profile's plugin-manager service for the registry list and the
+   * install. Both are read defensively, so a profile without the service still
+   * reports its own version and says why the check cannot run.
+   */
+  let manager
+  let currentVersion
+  let pendingRestart
+  const cache = createCache()
+  const ownVersion = readOwnVersion().then((version) => {
+    currentVersion = version
+  })
+
+  /**
+   * Run one check, sharing a check that is already running.
+   *
+   * An `unavailable` answer — no service mounted yet — is deliberately not cached:
+   * the injection below can settle after the first caller arrives, and caching the
+   * interim answer would report it as the result for the whole failure window.
+   * @returns The settled update state.
+   */
+  let inFlight = null
+  function refresh() {
+    if (inFlight !== null) return inFlight
+    const promise = (async () => {
+      await ownVersion
+      const state = await checkForUpdate({ manager, current: currentVersion })
+      return state.status === 'unavailable' ? state : cache.write(state)
+    })().finally(() => {
+      if (inFlight === promise) inFlight = null
+    })
+    inFlight = promise
+    return promise
+  }
+
+  ctx.inject(['pluginManager'], (service) => {
+    manager = service.pluginManager
+    service.effect(() => () => {
+      manager = undefined
+    })
+    // The startup check runs from here rather than from `apply` itself: this is the
+    // moment the registry list and the install both become reachable, so a profile
+    // that mounts the service late still gets one check and no useless early answer.
+    if (config?.updateCheck !== false) {
+      refresh().then((state) => {
+        ctx.logger.info('dsh-custom-theme: update check %s', describeState(state))
+      }, (error) => {
+        ctx.logger.warn('dsh-custom-theme: update check failed: %s', error.message)
+      })
+    }
+  })
+
+  /** The update surface the route exposes to the browser half. */
+  const updates = {
+    /** The cached state, a running check, or a fresh check when neither exists. */
+    async state() {
+      const state = cache.read() ?? await refresh()
+      return { ...state, package: PACKAGE_NAME, pendingRestart }
+    },
+    /** Ask the registries again, ignoring the cache. */
+    async check() {
+      return { ...await refresh(), package: PACKAGE_NAME, pendingRestart }
+    },
+    /** Install the newer release the last check resolved. */
+    async apply() {
+      const state = cache.read() ?? cache.value
+      const base = { package: PACKAGE_NAME, current: currentVersion, pendingRestart }
+      if (state === null || state.status !== 'ok') {
+        return { ...base, status: 'error', reason: 'no release has been resolved yet; check for updates first' }
+      }
+      if (state.updateAvailable !== true) {
+        return { ...base, status: 'error', reason: 'the running build is already the latest release', latest: state.latest }
+      }
+      if (manager === undefined || typeof manager.installBundle !== 'function') {
+        return { ...base, status: 'error', reason: 'the plugin manager service is not mounted', latest: state.latest }
+      }
+      const spec = `${PACKAGE_NAME}@${state.latest}`
+      try {
+        const result = await manager.installBundle(spec, { enabled: true })
+        const application = result?.application
+        // `installBundle` resolves for a failed run too: the outcome lives in the
+        // result, not in whether the promise rejected. Only these two mean the files
+        // are in place; anything else left the profile as it was, and saying the
+        // upgrade succeeded would send the user looking for a restart that cannot help.
+        if (application !== 'applied' && application !== 'restart-required') {
+          const detail = result?.error?.diagnostic ?? result?.error?.code
+          return {
+            ...base,
+            status: 'error',
+            latest: state.latest,
+            spec,
+            stage: result?.stage,
+            application,
+            restartRequired: false,
+            reason: detail === undefined
+              ? `the ${result?.stage ?? 'install'} step did not complete (${application ?? 'no outcome'})`
+              : `the ${result?.stage ?? 'install'} step did not complete: ${detail}`,
+          }
+        }
+        pendingRestart = state.latest
+        cache.write({ ...state, updateAvailable: false, pendingRestart })
+        return {
+          status: 'ok',
+          package: PACKAGE_NAME,
+          current: currentVersion,
+          latest: state.latest,
+          spec,
+          stage: result?.stage,
+          application,
+          // Replacing a package cannot hot-swap the Host module: the new code is
+          // installed but the running process still holds the old one until restart.
+          restartRequired: application === 'restart-required',
+          pendingRestart,
+        }
+      } catch (error) {
+        return { ...base, status: 'error', reason: error?.message ?? String(error), latest: state.latest, spec }
+      }
+    },
+  }
+
   ctx.inject(['webServer'], (child) => {
     child.effect(() => child.webServer.register({
       kind: 'prefix',
       path: ROUTE_PATH,
-      handler: (req, res) => handleRoute(req, res, { themes, backgrounds, ready }).catch((error) => {
+      handler: (req, res) => handleRoute(req, res, { themes, backgrounds, ready, updates }).catch((error) => {
         child.logger.warn('dsh-custom-theme: %s failed: %s', req.url, error.message)
         if (!res.headersSent) send(res, 500, 'text/plain; charset=utf-8', 'theme read failed')
       }),

package/src/update.mjs

@@ -0,0 +1,241 @@
+/**
+ * Update detection and upgrade planning for dsh-custom-theme.
+ *
+ * Pure version arithmetic and the registry query, kept apart from the route so it
+ * can be exercised without a Host. Nothing here is imported from a package: the row
+ * has to stay loadable by a profile that links this package directly, with no peer
+ * resolution — the same reason the rest of the Host half imports nothing.
+ *
+ * The registry is asked directly rather than through `pluginManager.inspect`.
+ * `inspect` is the pre-install check for a spec the user typed, and it refuses an
+ * already-installed package with `already-installed` for every form of the spec —
+ * including a version that does not exist — so it can never answer "what is the
+ * latest release". The registry list it *does* expose, `registries()`, is used for
+ * the query instead, which keeps a configured mirror or private registry in charge.
+ */
+
+/** The package this row is published as. */
+export const PACKAGE_NAME = 'dsh-custom-theme'
+
+/** The registry asked when the profile names neither a registry nor a resolved one. */
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org/'
+
+/** How long a successful answer is reused before the registry is asked again. */
+export const CACHE_TTL_MS = 6 * 60 * 60 * 1000
+
+/** How long a failed answer is reused, so a blip does not hide an update for hours. */
+export const FAILURE_TTL_MS = 60 * 1000
+
+/** Per-registry request budget. */
+export const FETCH_TIMEOUT_MS = 15_000
+
+/**
+ * Parse a semver string into its comparable parts.
+ *
+ * Build metadata is ignored, as the specification requires: it never takes part in
+ * precedence. A leading `v` is tolerated because registries answer with one or
+ * without it depending on the tool.
+ * @param value - Candidate version text.
+ * @returns The parts, or `undefined` when the text is not a version.
+ */
+export function parseVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(String(value ?? '').trim())
+  if (match === null) return undefined
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] === undefined ? [] : match[4].split('.'),
+  }
+}
+
+/**
+ * Compare two versions by semver precedence.
+ * @param left - Left version text.
+ * @param right - Right version text.
+ * @returns `-1`, `0` or `1`, or `undefined` when either text is not a version.
+ */
+export function compareVersions(left, right) {
+  const a = parseVersion(left)
+  const b = parseVersion(right)
+  if (a === undefined || b === undefined) return undefined
+  for (const part of ['major', 'minor', 'patch']) {
+    if (a[part] !== b[part]) return a[part] < b[part] ? -1 : 1
+  }
+  // A release outranks any prerelease of the same core version.
+  if (a.prerelease.length === 0 && b.prerelease.length === 0) return 0
+  if (a.prerelease.length === 0) return 1
+  if (b.prerelease.length === 0) return -1
+  const length = Math.max(a.prerelease.length, b.prerelease.length)
+  for (let index = 0; index < length; index += 1) {
+    const l = a.prerelease[index]
+    const r = b.prerelease[index]
+    // A shorter identifier list is lower when every preceding one is equal.
+    if (l === undefined) return -1
+    if (r === undefined) return 1
+    const lNumeric = /^\d+$/u.test(l)
+    const rNumeric = /^\d+$/u.test(r)
+    if (lNumeric && rNumeric) {
+      if (Number(l) !== Number(r)) return Number(l) < Number(r) ? -1 : 1
+      continue
+    }
+    // Numeric identifiers always have lower precedence than alphanumeric ones.
+    if (lNumeric !== rNumeric) return lNumeric ? -1 : 1
+    if (l !== r) return l < r ? -1 : 1
+  }
+  return 0
+}
+
+/**
+ * Whether `latest` is a strictly newer release than `current`.
+ *
+ * A version that cannot be parsed never counts as an update: offering an upgrade to
+ * something unreadable is worse than staying quiet.
+ * @param latest - Version the registry answered with.
+ * @param current - Version this build runs.
+ * @returns True when an upgrade is warranted.
+ */
+export function isUpdateAvailable(latest, current) {
+  return compareVersions(latest, current) === 1
+}
+
+/**
+ * The registries to ask, in order, without repeats.
+ *
+ * `pluginManager.registries()` reports the configured first registry (`null` when
+ * pnpm's own configuration decides), the registry that resolves to, and the
+ * configured fallbacks. A profile pointed at a private registry therefore asks only
+ * that one and its own fallbacks; the public registry is appended only when the
+ * profile names nothing at all.
+ * @param registries - The service's answer, read defensively.
+ * @returns Registry base URLs, each without a trailing slash.
+ */
+export function registryCandidates(registries) {
+  const seen = new Set()
+  const out = []
+  const push = (value) => {
+    if (typeof value !== 'string') return
+    const trimmed = value.trim().replace(/\/+$/u, '')
+    if (trimmed === '' || seen.has(trimmed)) return
+    seen.add(trimmed)
+    out.push(trimmed)
+  }
+  push(registries?.registry)
+  push(registries?.resolved)
+  for (const entry of Array.isArray(registries?.fallbackRegistries) ? registries.fallbackRegistries : []) push(entry)
+  if (out.length === 0) push(DEFAULT_REGISTRY)
+  return out
+}
+
+/**
+ * Ask each candidate registry for this package's latest published version.
+ *
+ * A registry that is unreachable, refuses, or answers without a usable version
+ * passes the question to the next one, so a stale mirror does not read as "no
+ * update". Every failure is returned as a state rather than thrown, because the
+ * caller renders it: a profile with no network access must still show its own
+ * version and say why the check could not run.
+ * @param options - `registries` from the plugin manager, plus optional `current`,
+ *   `packageName`, request `timeoutMs` and a `fetchImpl` for tests.
+ * @returns A state whose `status` is `ok`, `unavailable` or `error`.
+ */
+export async function fetchLatestVersion({
+  registries,
+  current,
+  packageName = PACKAGE_NAME,
+  timeoutMs = FETCH_TIMEOUT_MS,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    return { status: 'unavailable', current, reason: 'this runtime has no fetch' }
+  }
+  const candidates = registryCandidates(registries)
+  const asked = []
+  let reason = 'no registry answered'
+  for (const base of candidates) {
+    const url = `${base}/${packageName}/latest`
+    asked.push(base)
+    try {
+      const response = await fetchImpl(url, {
+        headers: { accept: 'application/json' },
+        cache: 'no-store',
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+      if (!response.ok) {
+        reason = `${base} answered HTTP ${response.status}`
+        continue
+      }
+      const body = await response.json()
+      const latest = body?.version
+      if (parseVersion(latest) === undefined) {
+        reason = `${base} answered without a usable version`
+        continue
+      }
+      return {
+        status: 'ok',
+        current,
+        latest,
+        updateAvailable: isUpdateAvailable(latest, current),
+        registry: base,
+        description: typeof body?.description === 'string' ? body.description : undefined,
+        checkedAt: new Date().toISOString(),
+      }
+    } catch (error) {
+      reason = `${base} failed: ${error?.message ?? String(error)}`
+    }
+  }
+  return { status: 'error', current, reason, registries: asked, checkedAt: new Date().toISOString() }
+}
+
+/**
+ * Detect whether a newer release exists.
+ * @param options - `manager` is the Host's plugin-manager service; the rest is
+ *   forwarded to {@link fetchLatestVersion}.
+ * @returns A state whose `status` is `ok`, `unavailable` or `error`.
+ */
+export async function checkForUpdate({ manager, current, ...rest } = {}) {
+  if (manager === undefined || manager === null || typeof manager.registries !== 'function') {
+    return { status: 'unavailable', current, reason: 'the plugin manager service is not mounted' }
+  }
+  let registries
+  try {
+    registries = await manager.registries()
+  } catch (error) {
+    return { status: 'error', current, reason: error?.message ?? String(error) }
+  }
+  return fetchLatestVersion({ ...rest, registries, current })
+}
+
+/**
+ * Cache one update state.
+ *
+ * The check runs once at startup, so without this every page load would ask the
+ * registry again. A failure is cached for less time than a success, so a transient
+ * network problem does not hide an update for hours.
+ * @param options - `ttl` for a successful answer, `failureTtl` for a failed one.
+ * @returns `read`, `write`, `clear` and the current `value`.
+ */
+export function createCache({ ttl = CACHE_TTL_MS, failureTtl = FAILURE_TTL_MS } = {}) {
+  let entry = null
+  return {
+    /** The stored state, whether or not it is still fresh. */
+    get value() {
+      return entry === null ? null : entry.state
+    },
+    /** The stored state while it is still fresh, otherwise null. */
+    read() {
+      if (entry === null) return null
+      const age = Date.now() - entry.at
+      return age < (entry.state?.status === 'ok' ? ttl : failureTtl) ? entry.state : null
+    },
+    /** Store a state, stamped with the current time. */
+    write(state) {
+      entry = { state, at: Date.now() }
+      return state
+    },
+    /** Forget the stored state. */
+    clear() {
+      entry = null
+    },
+  }
+}