@liuzw/dsh-web-ui-custom 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liuzwZYW
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @liuzw/dsh-web-ui-custom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 **DeepSeek Harness Web** 的两项界面定制，做成插件——升级 DSH 不会再被覆盖：
+
+1. **PWA 应用图标**：深色圆角底 + 白色鲸鱼，替换上游白底灰鲸那一套；
+2. **侧栏设置齿轮**：账户行右侧（收起时在头像上方）加一个齿轮，单击直接打开设置面板。
+
+> 之前的做法是直接改 DSH 安装目录里的前端 `dist` 和客户端 bundle，每次升级都会被还原。这个包用 DSH 的插件接口重做了一遍，安装、卸载、升级互不影响。
+
+## 安装
+
+**从 npm（推荐）**——在 DSH 的插件市场里搜 `@liuzw/dsh-web-ui-custom` 安装，或手动：
+
+```bash
+cd ~/.dsh/profiles/web
+pnpm add @liuzw/dsh-web-ui-custom
+```
+
+然后把包名加进 `package.json` 的 `dsh.profile.bundles`：
+
+```json
+"bundles": ["...", "@liuzw/dsh-web-ui-custom"]
+```
+
+重启 `dsh web` 生效。
+
+**源码方式**（本仓库 clone 后）：
+
+```bash
+./install.sh     # 写入 file: 依赖 + bundle，并 pnpm install --offline
+./uninstall.sh   # 撤销
+```
+
+两条脚本都要求先停掉 `dsh web/serve`，失败会自动回滚 profile 配置。
+
+## 实现
+
+| 部分 | 做法 |
+| --- | --- |
+| 图标（宿主 `index.js`） | `webServer.register` 以 **exact route** 接住 `/icon-192.png`、`/icon-512.png`、`/icon-maskable-512.png`、`/apple-touch-icon.png`，返回包内 `assets/` 的 PNG。上游 `manifest.webmanifest` 与 `index.html` 引用的正是这些路径，因此前端 `dist` 一个字节都不用改。 |
+| 齿轮（浏览器 `client.js`） | 在侧栏账户行追加一个按钮；点击时沿 React fiber 向上找到启动器组件的 `openSettings` 属性并调用。React 重渲染会移除外来子节点，用 MutationObserver 补回。 |
+
+## 行为与边界
+
+- 图标路由带 `cache-control: no-cache`，DSH 静态资源本身也是 `no-cache`，刷新即可看到新图标；已安装的 PWA 若仍显示旧图标，是系统缓存，卸载重装 PWA 即可。
+- 齿轮依赖 `_settingsArea` / `_triggerRow` 两个 CSS Module 后缀和启动器组件上的 `openSettings`。DSH 改这两处时齿轮会静默不显示（图标不受影响），届时只需调整 `client.js` 里的 `findRow`。
+- 宿主以 exact match 匹配图标路径，DSH 若改文件名，需要同步更新 `index.js` 的 `ICONS` 表。
+
+## 许可
+
+MIT

package/client.js

@@ -0,0 +1,144 @@
+/**
+ * Client half of the local Web UI kit: a settings gear beside the sidebar
+ * account launcher.
+ *
+ * The shipped account row opens a menu; the gear is a direct shortcut into the
+ * settings dialog. It is mounted as a sibling of the row's anchor and marks the
+ * row with `data-dsh-wuc-row`, so the stylesheet below can lay the pair out
+ * on one line when the sidebar is wide and stack the gear above the avatar in
+ * the 56px rail.
+ *
+ * How the settings dialog is opened: the row is the shipped launcher, and the
+ * settings shell hands that component an `openSettings` prop. React keeps the
+ * fiber for every host element under `__reactFiber$…`, so walking up from the
+ * row's own node reaches the component fiber that carries the callback. This
+ * uses no private module import and degrades quietly: when the prop is not
+ * found the gear is removed instead of becoming a dead button.
+ *
+ * React re-renders replace foreign children, so a MutationObserver re-mounts
+ * the gear after any reconciliation that drops it.
+ *
+ * @module dsh-web-ui-custom
+ */
+window.__ModuleLoader__.load({
+  id: '@liuzw/dsh-web-ui-custom',
+  factory() {
+    /** Marks the account row our gear belongs to. */
+    const ROW_ATTR = 'data-dsh-wuc-row'
+    /** Marks the gear button itself. */
+    const GEAR_ATTR = 'data-dsh-wuc-gear'
+
+    const LABEL = (typeof navigator !== 'undefined' && /^zh/i.test(navigator.language ?? '')) ? '设置' : 'Settings'
+
+    /** 16px outline gear, drawn with `currentColor` so it follows the row. */
+    const GEAR_SVG = [
+      '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">',
+      '<circle cx="12" cy="12" r="3.2"/>',
+      '<path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"/>',
+      '</svg>',
+    ].join('')
+
+    const CSS = [
+      /* One line: anchor takes the space, gear keeps its box. */
+      `[${ROW_ATTR}]{display:flex;align-items:center;gap:4px}`,
+      `[${ROW_ATTR}]>:first-child{flex:1;min-width:0}`,
+      `[${GEAR_ATTR}]{flex:none;width:36px;height:36px;display:inline-flex;align-items:center;justify-content:center;padding:0;border:0;border-radius:8px;background:transparent;color:inherit;cursor:pointer}`,
+      `[${GEAR_ATTR}]:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(0,0,0,.06))}`,
+      `[${GEAR_ATTR}]:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#4f6ef7);outline-offset:2px}`,
+      /* Rail: stack the gear above the avatar, keeping the icon column centred. */
+      `[class*="_collapsed"] [${ROW_ATTR}]{flex-direction:column;gap:8px}`,
+      `[class*="_collapsed"] [${GEAR_ATTR}]{order:-1}`,
+    ].join('')
+
+    /**
+     * The shipped account launcher row.
+     * @returns the row element, or `undefined` while the sidebar is not mounted.
+     */
+    function findRow() {
+      const area = document.querySelector('[class*="_settingsArea"]')
+      if (area === null) return undefined
+      const trigger = area.querySelector('[class*="_triggerRow"]')
+      const row = (trigger ?? area).firstElementChild
+      return row instanceof HTMLElement ? row : undefined
+    }
+
+    /**
+     * Walk up the React fiber chain looking for the launcher's `openSettings`.
+     * @param node - a host element inside the launcher's subtree.
+     * @returns the callback the settings shell handed the launcher, if any.
+     */
+    function resolveOpenSettings(node) {
+      const key = Object.keys(node).find((name) => name.startsWith('__reactFiber$'))
+      if (key === undefined) return undefined
+      let fiber = node[key]
+      for (let depth = 0; fiber && depth < 64; depth += 1) {
+        const props = fiber.memoizedProps
+        if (props && typeof props.openSettings === 'function') return props.openSettings
+        fiber = fiber.return
+      }
+      return undefined
+    }
+
+    /**
+     * Mount the gear into the account row when both the row and its settings
+     * callback are present.
+     * @param row - the launcher row.
+     */
+    function mount(row) {
+      if (row.querySelector(`:scope > [${GEAR_ATTR}]`) !== null) return
+      if (typeof resolveOpenSettings(row) !== 'function') return
+
+      row.setAttribute(ROW_ATTR, '')
+      const gear = document.createElement('button')
+      gear.type = 'button'
+      gear.dataset.dshWucGear = ''
+      gear.setAttribute('aria-label', LABEL)
+      gear.title = LABEL
+      gear.innerHTML = GEAR_SVG
+      gear.addEventListener('click', (event) => {
+        event.preventDefault()
+        event.stopPropagation()
+        const open = resolveOpenSettings(row)
+        if (typeof open === 'function') open()
+      })
+      row.append(gear)
+    }
+
+    return {
+      /**
+       * Install the stylesheet, the gear, and the observer that keeps it there.
+       * @param ctx - browser plugin context, for effect ownership.
+       */
+      apply(ctx) {
+        ctx.effect(() => {
+          const style = document.createElement('style')
+          style.dataset.plugin = '@liuzw/dsh-web-ui-custom'
+          style.textContent = CSS
+          document.head.append(style)
+
+          let scheduled = false
+          const sync = () => {
+            scheduled = false
+            const row = findRow()
+            if (row !== undefined) mount(row)
+          }
+          const schedule = () => {
+            if (scheduled) return
+            scheduled = true
+            requestAnimationFrame(sync)
+          }
+
+          sync()
+          const observer = new MutationObserver(schedule)
+          observer.observe(document.body, { childList: true, subtree: true })
+          return () => {
+            observer.disconnect()
+            style.remove()
+            for (const gear of document.querySelectorAll(`[${GEAR_ATTR}]`)) gear.remove()
+            for (const row of document.querySelectorAll(`[${ROW_ATTR}]`)) row.removeAttribute(ROW_ATTR)
+          }
+        }, '@liuzw/dsh-web-ui-custom: sidebar settings gear')
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# Bundle patch: mount the local Web UI kit (brand PWA icons + sidebar settings gear).
+- insert:
+    - id: web-ui-custom
+      name: '@liuzw/dsh-web-ui-custom'

package/index.js

@@ -0,0 +1,86 @@
+/**
+ * Host half of the local Web UI kit.
+ *
+ * The shipped Web frontend serves its PWA icons from its own `dist/`, so an
+ * upgrade replaces any replaced image files. This row claims the four icon
+ * paths as exact routes instead and answers with the brand set kept inside
+ * this package, which leaves the frontend untouched and survives upgrades.
+ *
+ * The manifest itself is not claimed here: it keeps pointing at
+ * `icon-192.png`, `icon-512.png`, `icon-maskable-512.png`, and the built
+ * `index.html` still links `./apple-touch-icon.png`. Exact routes win over the
+ * static file of the same path, so both keep resolving to these bytes.
+ *
+ * @module dsh-web-ui-custom
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+/** Stable Cordis plugin name. */
+export const name = 'web-ui-custom'
+
+/** The web server is required before any icon route can be claimed. */
+export const inject = ['webServer']
+
+/** Icon files served from this package, keyed by the path the frontend links. */
+const ICONS = {
+  '/icon-192.png': 'icon-192.png',
+  '/icon-512.png': 'icon-512.png',
+  '/icon-maskable-512.png': 'icon-maskable-512.png',
+  '/apple-touch-icon.png': 'apple-touch-icon.png',
+}
+
+const ASSET_DIR = join(dirname(fileURLToPath(import.meta.url)), 'assets')
+
+/**
+ * Read one bundled icon once.
+ * @param file - file name inside `assets/`.
+ * @returns the file bytes, or `undefined` when the package is incomplete.
+ */
+function readIcon(file) {
+  try {
+    return readFileSync(join(ASSET_DIR, file))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Serve the brand icons over the shipped asset paths.
+ * @param ctx - plugin context carrying the webServer service.
+ */
+export function apply(ctx) {
+  ctx.effect(() => {
+    const disposers = []
+    for (const [route, file] of Object.entries(ICONS)) {
+      const body = readIcon(file)
+      if (body === undefined) {
+        ctx.logger?.warn?.(`web-ui-custom: missing asset ${file}, keeping the shipped icon for ${route}`)
+        continue
+      }
+      disposers.push(ctx.webServer.register({
+        kind: 'exact',
+        path: route,
+        handler: (request, response) => {
+          if (request.method !== 'GET' && request.method !== 'HEAD') {
+            response.writeHead(405, { allow: 'GET, HEAD' })
+            response.end()
+            return
+          }
+          response.writeHead(200, {
+            'content-type': 'image/png',
+            'content-length': body.byteLength,
+            /* Revalidate so a replaced icon reaches an installed app. */
+            'cache-control': 'no-cache',
+          })
+          if (request.method === 'HEAD') response.end()
+          else response.end(body)
+        },
+      }))
+    }
+    return () => {
+      for (const dispose of disposers) dispose()
+    }
+  }, 'web-ui-custom: icon routes')
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@liuzw/dsh-web-ui-custom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Custom PWA icons and a sidebar settings gear for the DeepSeek Harness Web app. 为 DSH Web 换上自制 PWA 图标，并在侧栏账户行加一个直开设置的齿轮。",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "assets/*.png"
+  ],
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "pwa",
+    "icons",
+    "sidebar",
+    "settings",
+    "web"
+  ],
+  "author": "liuzwZYW",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liuzwZYW/dsh-web-ui-custom.git"
+  },
+  "homepage": "https://github.com/liuzwZYW/dsh-web-ui-custom#readme",
+  "bugs": {
+    "url": "https://github.com/liuzwZYW/dsh-web-ui-custom/issues"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.2.0 <0.3.0-0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }