dsh-custom-theme 0.1.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "dsh-custom-theme",
+  "version": "0.1.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",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sparrived/dsh-custom-theme.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Sparrived/dsh-custom-theme/issues"
+  },
+  "homepage": "https://github.com/Sparrived/dsh-custom-theme#readme",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "src",
+    "lib/client.js",
+    "themes",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "test:browser": "node test/browser/appearance.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "cordis",
+    "plugin",
+    "theme"
+  ]
+}

package/src/index.mjs

@@ -0,0 +1,289 @@
+/**
+ * dsh-custom-theme — Host half.
+ *
+ * Owns a user-editable CSS theme directory (`$DSH_HOME/themes`) and serves it to
+ * the browser half over a prefix route on the Web Host. Bundled themes are
+ * seeded once, and a user who drops an extra `.css` file into the directory gets
+ * a new entry in the Appearance picker without touching any configuration.
+ *
+ * Imports no third-party modules: the row must stay loadable by a profile that
+ * links this package directly, with no peer resolution for a Schemastery `Config`
+ * schema yet. `config` is therefore read defensively.
+ */
+
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  BUNDLED_THEME_IDS,
+  MAX_BACKGROUND_BYTES,
+  MAX_THEME_BYTES,
+  SEED_VERSION,
+  backgroundContentType,
+  backgroundsDirectory,
+  isBackgroundName,
+  isBundledThemeId,
+  isThemeId,
+  orderThemeIds,
+  themesDirectory,
+} from './themes.mjs'
+
+/**
+ * Prefix route owned by this plugin. `dsh-client-ui-theme` and the SPA dist use
+ * other paths.
+ *
+ * No trailing slash: the webserver matches a prefix `p` against `p` itself and
+ * `p/<anything>`, so registering `'/dsh-custom-theme/'` would only ever match
+ * `'/dsh-custom-theme//…'` and every real request would fall through.
+ */
+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))
+
+export const name = 'dsh-custom-theme'
+
+/**
+ * Resolve the DSH home, honouring the environment override the runtime sets.
+ * @returns The home directory whose `themes` directory this plugin owns.
+ */
+function dshHome() {
+  const configured = process.env.DSH_HOME
+  return typeof configured === 'string' && configured.trim() !== '' ? configured : join(homedir(), '.dsh')
+}
+
+/**
+ * Copy each bundled stylesheet into the theme directory.
+ *
+ * Within one seed generation an existing file is left alone, so a user edit
+ * survives every restart and a deletion is only repaired. When the generation
+ * advances the bundled stylesheets are written again, because a fixed or extended
+ * bundled palette has to reach a machine that already holds the older copy. Only
+ * bundled ids are ever written; anything else in the directory is the user's.
+ *
+ * The theme directory is owned by this plugin, and `themes/*.css` documents that
+ * a customised palette belongs in a copy under its own name rather than in an
+ * edited bundled file.
+ * @param directory - Theme directory, created when missing.
+ * @returns Ids written by this call, for the startup log.
+ */
+async function seedThemes(directory) {
+  await mkdir(directory, { recursive: true })
+  const marker = join(directory, '.seed-version')
+  let generation = null
+  try {
+    generation = Number.parseInt(await readFile(marker, 'utf8'), 10)
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
+  // A missing marker is a directory this plugin has not seeded, so every bundled
+  // file is written even if an unrelated file of the same name is already there.
+  const stale = generation !== SEED_VERSION
+  const seeded = []
+  for (const id of BUNDLED_THEME_IDS) {
+    const target = join(directory, `${id}.css`)
+    if (!stale) {
+      try {
+        await readFile(target)
+        continue
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error
+      }
+    }
+    await writeFile(target, await readFile(join(SEED_ROOT, `${id}.css`), 'utf8'), 'utf8')
+    seeded.push(id)
+  }
+  if (generation !== SEED_VERSION) await writeFile(marker, String(SEED_VERSION), 'utf8')
+  return seeded
+}
+
+/**
+ * List the theme ids present in the directory.
+ * @param directory - Theme directory.
+ * @returns Ordered ids without the `.css` suffix.
+ */
+async function scanThemes(directory) {
+  const entries = await readdir(directory, { withFileTypes: true })
+  const ids = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.css') && !entry.name.startsWith('.'))
+    .map((entry) => entry.name.slice(0, -'.css'.length))
+  return orderThemeIds(ids)
+}
+
+/**
+ * Write one response. Handlers own the raw `ServerResponse`.
+ * @param res - Response owned by this handler.
+ * @param status - HTTP status code.
+ * @param contentType - Response media type.
+ * @param body - Response body as text or bytes; empty for error statuses.
+ */
+function send(res, status, contentType, body = '') {
+  const payload = Buffer.isBuffer(body) ? body : Buffer.from(body)
+  res.writeHead(status, {
+    'content-type': contentType,
+    'cache-control': 'no-store',
+    'content-length': payload.length,
+  })
+  res.end(payload)
+}
+
+/**
+ * Percent-decode a request path.
+ * @param value - Raw path below the route prefix.
+ * @returns Decoded text, or `undefined` when the escape sequence is malformed.
+ */
+function decodePath(value) {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * List the background images present in the directory.
+ * @param directory - Background directory.
+ * @returns File names in alphabet order; an absent directory lists nothing.
+ */
+async function scanBackgrounds(directory) {
+  let entries
+  try {
+    entries = await readdir(directory, { withFileTypes: true })
+  } catch (error) {
+    if (error.code === 'ENOENT') return []
+    throw error
+  }
+  return entries
+    .filter((entry) => entry.isFile() && !entry.name.startsWith('.') && isBackgroundName(entry.name))
+    .map((entry) => entry.name)
+    .sort((left, right) => left.localeCompare(right))
+}
+
+/**
+ * Read one background image under the file-name whitelist.
+ * @param directory - Background directory.
+ * @param name - Candidate file name from the request path.
+ * @returns The image bytes, or `undefined` when no such image exists or it is oversized.
+ */
+async function readBackground(directory, name) {
+  if (!isBackgroundName(name)) return undefined
+  let bytes
+  try {
+    bytes = await readFile(join(directory, name))
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'EISDIR') return undefined
+    throw error
+  }
+  return bytes.length > MAX_BACKGROUND_BYTES ? undefined : bytes
+}
+
+/**
+ * Read one theme stylesheet under the id whitelist.
+ * @param directory - Theme directory.
+ * @param id - Candidate theme id from the request path.
+ * @returns Stylesheet text, or `undefined` when no such theme exists or it is oversized.
+ */
+async function readTheme(directory, id) {
+  if (!isThemeId(id)) return undefined
+  let text
+  try {
+    text = await readFile(join(directory, `${id}.css`), 'utf8')
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'EISDIR') return undefined
+    throw error
+  }
+  return Buffer.byteLength(text) > MAX_THEME_BYTES ? undefined : text
+}
+
+/**
+ * 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
+ * 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.
+ */
+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
+  }
+  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 }))
+    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 }))
+    return
+  }
+  const theme = /^theme\/([^/]+)\.css$/u.exec(rest)
+  if (theme !== null) {
+    const text = await readTheme(paths.themes, theme[1])
+    if (text === undefined) {
+      send(res, 404, 'text/plain; charset=utf-8', 'theme not found')
+      return
+    }
+    send(res, 200, 'text/css; charset=utf-8', text)
+    return
+  }
+  const background = /^background\/([^/]+)$/u.exec(rest)
+  const bytes = background === null ? undefined : await readBackground(paths.backgrounds, background[1])
+  if (bytes === undefined) {
+    send(res, 404, 'text/plain; charset=utf-8', 'background not found')
+    return
+  }
+  send(res, 200, backgroundContentType(background[1]), bytes)
+}
+
+/**
+ * Seed the theme directory and expose both directories over the Web Host.
+ *
+ * The route is registered through `ctx.inject` so a profile without
+ * `dsh-host-webserver` still seeds the theme directory instead of failing to
+ * load.
+ * @param ctx - Host Cordis context of this row.
+ * @param config - Row configuration; `themesDir` and `backgroundsDir` override
+ *   the default locations.
+ */
+export function apply(ctx, config) {
+  const themes = themesDirectory(config, dshHome())
+  const backgrounds = backgroundsDirectory(config, dshHome())
+  ctx.logger.info('dsh-custom-theme: themes directory %s', themes)
+  ctx.logger.info('dsh-custom-theme: backgrounds directory %s', backgrounds)
+  const ready = Promise.all([
+    seedThemes(themes).then((ids) => {
+      if (ids.length > 0) ctx.logger.info('dsh-custom-theme: seeded %s', ids.join(', '))
+    }),
+    // The background directory holds only user-supplied images, so it is created
+    // but never seeded; the card lists it as empty until something is dropped in.
+    mkdir(backgrounds, { recursive: true }),
+  ]).then(() => {}, (error) => {
+    ctx.logger.warn('dsh-custom-theme: preparing directories failed: %s', error.message)
+  })
+
+  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) => {
+        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')
+      }),
+    }), 'dsh-custom-theme: route')
+    child.logger.info('dsh-custom-theme: serving %s', ROUTE_PATH)
+  })
+}

package/src/themes.mjs

@@ -0,0 +1,121 @@
+// Pure theme-directory model: id validation, picker ordering, directory
+// resolution. No filesystem and no Cordis, so `node --test` drives it directly.
+
+import { join } from 'node:path'
+
+/** Distinct bundle themes, in picker order. Mirrors the ids of `themes/*.css`. */
+export const BUNDLED_THEME_IDS = ['gov', 'monokai-pro', 'one-dark']
+
+/**
+ * Seed generation.
+ *
+ * Bumping it re-syncs the bundled stylesheets on the next start, because a
+ * corrected or extended bundled palette has to reach a machine that already has
+ * the older copy. Files whose id is not bundled are never touched, and
+ * `themes/*.css` is documented as managed so a customised palette belongs in a
+ * copy under its own name.
+ */
+export const SEED_VERSION = 2
+
+/** Refuse to serve or read a stylesheet larger than this; a theme is a few KiB. */
+export const MAX_THEME_BYTES = 1024 * 1024
+
+/**
+ * Theme ids that may reach the filesystem. Must start alphanumeric, so a name
+ * can never be `.`, `..`, or a dotfile, and contains no separator.
+ */
+const THEME_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u
+
+/**
+ * Whether a request-supplied id may be turned into a path.
+ * @param value - Candidate id from a request path or a directory entry.
+ * @returns True when the id is safe to join under the theme directory.
+ */
+export function isThemeId(value) {
+  return typeof value === 'string' && THEME_ID.test(value)
+}
+
+/**
+ * Resolve the theme directory: an explicit `themesDir` config value wins, then
+ * `<home>/themes`.
+ * @param config - Row configuration from the profile patch; every field is optional.
+ * @param home - The DSH home directory, resolved by the caller.
+ * @returns Theme directory path.
+ */
+export function themesDirectory(config, home) {
+  if (typeof config?.themesDir === 'string' && config.themesDir.trim() !== '') return config.themesDir
+  return join(home, 'themes')
+}
+
+/**
+ * Order the ids found in the theme directory: bundled ids first in their fixed
+ * order, then every other id in alphabet order.
+ * @param ids - Ids present in the directory, in any order and possibly with duplicates.
+ * @returns Ordered, de-duplicated ids.
+ */
+export function orderThemeIds(ids) {
+  const unique = [...new Set(ids)].filter(isThemeId)
+  const bundled = BUNDLED_THEME_IDS.filter((id) => unique.includes(id))
+  const extra = unique
+    .filter((id) => !BUNDLED_THEME_IDS.includes(id))
+    .sort((left, right) => left.localeCompare(right))
+  return [...bundled, ...extra]
+}
+
+/**
+ * Whether an id is one of the themes this package seeds.
+ * @param id - Candidate id.
+ * @returns True for a bundled id.
+ */
+export function isBundledThemeId(id) {
+  return BUNDLED_THEME_IDS.includes(id)
+}
+
+/** Background image extensions this plugin serves, with their media types. */
+const BACKGROUND_TYPES = new Map([
+  ['.png', 'image/png'],
+  ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'],
+  ['.webp', 'image/webp'],
+  ['.gif', 'image/gif'],
+  ['.avif', 'image/avif'],
+  ['.bmp', 'image/bmp'],
+])
+
+/** Refuse to serve an image larger than this. */
+export const MAX_BACKGROUND_BYTES = 16 * 1024 * 1024
+
+/**
+ * Whether a request-supplied name may be turned into a path under the
+ * background directory: a valid id plus one served image extension.
+ * @param value - Candidate file name from a request path or a directory entry.
+ * @returns True when the name is safe to join under the background directory.
+ */
+export function isBackgroundName(value) {
+  if (typeof value !== 'string') return false
+  const dot = value.lastIndexOf('.')
+  if (dot <= 0) return false
+  return isThemeId(value.slice(0, dot)) && BACKGROUND_TYPES.has(value.slice(dot).toLowerCase())
+}
+
+/**
+ * Media type for a background file name.
+ * @param name - File name already accepted by {@link isBackgroundName}.
+ * @returns The media type; `application/octet-stream` when the extension is unknown.
+ */
+export function backgroundContentType(name) {
+  return BACKGROUND_TYPES.get(name.slice(name.lastIndexOf('.')).toLowerCase()) ?? 'application/octet-stream'
+}
+
+/**
+ * Resolve the background directory: an explicit `backgroundsDir` config value
+ * wins, then `<home>/backgrounds`. Nothing is seeded here; the directory only
+ * holds images the user put there.
+ * @param config - Row configuration from the profile patch; every field is optional.
+ * @param home - The DSH home directory, resolved by the caller.
+ * @returns Background directory path.
+ */
+export function backgroundsDirectory(config, home) {
+  if (typeof config?.backgroundsDir === 'string' && config.backgroundsDir.trim() !== '') return config.backgroundsDir
+  return join(home, 'backgrounds')
+}

package/themes/gov.css

@@ -0,0 +1,53 @@
+/*
+ * 政务主题 — 宣纸底色、中国红品牌色、国徽金强调色。
+ *
+ * Ported from Deeptop's `themes/gov.css`, which defines both palettes in one file
+ * exactly as this one does: `:root` is the light set and `:root[data-theme="dark"]`
+ * the dark set. The plugin reads each set separately and hands them to the
+ * official theme runtime, so the appearance switch moves between them.
+ *
+ * Deeptop's own variable names map onto the official `--dsw-*` alias tokens:
+ * --surface → bg-base, --surface-raised → bg-layer-1, --surface-soft → bg-layer-2,
+ * --line → border-l1, --line-strong → border-l2, --accent → brand-primary,
+ * --ink → label-primary, --ink-muted → label-secondary, --danger/--good/--warning
+ * → the state colours, --rail → the sidebar fill. `color-scheme` is deliberately
+ * not carried over: the shell and the appearance preference own it.
+ */
+
+:root {
+  --dsw-alias-bg-base: #f4eee3;
+  --dsw-alias-bg-layer-1: #fbf6ec;
+  --dsw-alias-bg-layer-2: #eae2d2;
+  --dsw-alias-bg-overlay: #fbf6ec;
+  --dsw-alias-border-l1: #d6cdb8;
+  --dsw-alias-border-l2: #b8ac92;
+  --dsw-alias-brand-primary: #c8161d;
+  --dsw-alias-label-primary: #1a1714;
+  --dsw-alias-label-secondary: #5a544a;
+  --dsw-alias-state-error-primary: #a02a2a;
+  --dsw-alias-state-idle-primary: #8a8270;
+  --dsw-alias-state-success-primary: #5a7d3d;
+  --dsw-alias-state-warn-primary: #b6812a;
+  --dsw-specific-sidebar-fill: #e6ddc9;
+}
+
+:root[data-theme="dark"] {
+  --dsw-alias-bg-base: #1f1a14;
+  --dsw-alias-bg-layer-1: #2a231a;
+  --dsw-alias-bg-layer-2: #3b3324;
+  --dsw-alias-bg-overlay: #2a231a;
+  --dsw-alias-border-l1: #3b3324;
+  --dsw-alias-border-l2: #54483a;
+  --dsw-alias-brand-primary: #e64c50;
+  --dsw-alias-label-primary: #f0e6d2;
+  --dsw-alias-label-secondary: #a89a82;
+  --dsw-alias-state-error-primary: #e64c50;
+  --dsw-alias-state-idle-primary: #7a6f5c;
+  --dsw-alias-state-success-primary: #82ac5c;
+  --dsw-alias-state-warn-primary: #d4a24c;
+  --dsw-specific-sidebar-fill: #1f1a14;
+}
+
+body {
+  font-family: "Source Han Serif SC", "Noto Serif SC", "Songti SC", SimSun, serif;
+}

package/themes/monokai-pro.css

@@ -0,0 +1,39 @@
+/*
+ * Monokai Pro — both palettes in one file, ported from Deeptop's
+ * `themes/monokai-pro.css`. Mapping onto the official `--dsw-*` alias tokens is
+ * documented in `gov.css`.
+ */
+
+:root {
+  --dsw-alias-bg-base: #fbfaf9;
+  --dsw-alias-bg-layer-1: #ffffff;
+  --dsw-alias-bg-layer-2: #f1efed;
+  --dsw-alias-bg-overlay: #ffffff;
+  --dsw-alias-border-l1: #ddd9d7;
+  --dsw-alias-border-l2: #cbc6c4;
+  --dsw-alias-brand-primary: #2d9bb3;
+  --dsw-alias-label-primary: #2d2a2e;
+  --dsw-alias-label-secondary: #5e5a60;
+  --dsw-alias-state-error-primary: #d6455f;
+  --dsw-alias-state-idle-primary: #8a868b;
+  --dsw-alias-state-success-primary: #3f9d5c;
+  --dsw-alias-state-warn-primary: #b37a1e;
+  --dsw-specific-sidebar-fill: #efedeb;
+}
+
+:root[data-theme="dark"] {
+  --dsw-alias-bg-base: #2d2a2e;
+  --dsw-alias-bg-layer-1: #373438;
+  --dsw-alias-bg-layer-2: #3f3c41;
+  --dsw-alias-bg-overlay: #373438;
+  --dsw-alias-border-l1: #3a373b;
+  --dsw-alias-border-l2: #4d4a4f;
+  --dsw-alias-brand-primary: #78dce8;
+  --dsw-alias-label-primary: #fcfcfa;
+  --dsw-alias-label-secondary: #c5c2c7;
+  --dsw-alias-state-error-primary: #ff6188;
+  --dsw-alias-state-idle-primary: #9a979d;
+  --dsw-alias-state-success-primary: #a9dc76;
+  --dsw-alias-state-warn-primary: #ffd866;
+  --dsw-specific-sidebar-fill: #262326;
+}

package/themes/one-dark.css

@@ -0,0 +1,39 @@
+/*
+ * One Dark — both palettes in one file, ported from Deeptop's
+ * `themes/one-dark.css`. Mapping onto the official `--dsw-*` alias tokens is
+ * documented in `gov.css`.
+ */
+
+:root {
+  --dsw-alias-bg-base: #f6f8fb;
+  --dsw-alias-bg-layer-1: #ffffff;
+  --dsw-alias-bg-layer-2: #eef2f6;
+  --dsw-alias-bg-overlay: #ffffff;
+  --dsw-alias-border-l1: #d9e0e8;
+  --dsw-alias-border-l2: #c3cedb;
+  --dsw-alias-brand-primary: #4078c0;
+  --dsw-alias-label-primary: #282c34;
+  --dsw-alias-label-secondary: #5f6672;
+  --dsw-alias-state-error-primary: #d73a49;
+  --dsw-alias-state-idle-primary: #8b93a1;
+  --dsw-alias-state-success-primary: #22863a;
+  --dsw-alias-state-warn-primary: #b08800;
+  --dsw-specific-sidebar-fill: #edf1f6;
+}
+
+:root[data-theme="dark"] {
+  --dsw-alias-bg-base: #282c34;
+  --dsw-alias-bg-layer-1: #2c313a;
+  --dsw-alias-bg-layer-2: #323842;
+  --dsw-alias-bg-overlay: #2c313a;
+  --dsw-alias-border-l1: #3a404c;
+  --dsw-alias-border-l2: #4b5263;
+  --dsw-alias-brand-primary: #61afef;
+  --dsw-alias-label-primary: #abb2bf;
+  --dsw-alias-label-secondary: #9da5b4;
+  --dsw-alias-state-error-primary: #e06c75;
+  --dsw-alias-state-idle-primary: #5c6370;
+  --dsw-alias-state-success-primary: #98c379;
+  --dsw-alias-state-warn-primary: #e5c07b;
+  --dsw-specific-sidebar-fill: #21252b;
+}