dsh-clean-desktop-shell 0.1.3 → 0.1.5

package/README.en.md

@@ -29,24 +29,43 @@ Key differences from other desktop clients in the ecosystem:
 | **Visual changes** | Custom title bar / frosted glass etc. | **None** — pure window shell |
 | **Upstream** | Pinned version | **Tracks rc.7** |
 
-## Install
+## Usage
 
-> **Status**: plugin-market install (Option 2) is under construction, expected live early tomorrow. **Only Option 1 (the installer) is currently available.**
+1. If the plugin is installed, launching `dsh` from the command line pops up the desktop window automatically; you can also double-click the desktop shortcut created by the plugin — on par with a native desktop app.
+2. Everything from the original web UI works as-is.
+3. Detailed settings live in the tray right-click menu. The main window adds no controls of its own, keeping the page clean.
+
+**All backend controls live in the tray** — the main window stays a pure shell:
 
-**Option 1: download the installer from Releases (recommended for end users — the only full desktop-app install)**
+- Start / restart / stop the backend (with progress dialogs; stopping really shuts down the service on 3080, including externally started instances)
+- Auto-detect backend · set the backend install folder (auto-detect default)
+- Reload window · create desktop shortcut · check for updates · repo homepage
+
+**Window reliability (Edge-style instant refresh):**
+
+- Shows immediately on launch, never waits for the backend
+- While the backend is down, a local "backend offline" screen is shown and re-probed; the real page loads automatically the moment it answers
+- The instant the backend stops (tray stop, kill or crash) the window flips back to the offline screen — a stale page never fakes "still alive"
+- The offline screen has self-service buttons: reload / start backend / auto-detect backend / set backend install folder
+
+## Install
+
+**Option 1: download the installer from Releases (for a standalone desktop app)**
 
 - Windows: `DSH-Clean-Desktop-Shell-Setup-<version>.exe`
 - macOS: `DSH-Clean-Desktop-Shell-<version>.dmg` (Intel) or `-arm64.dmg` (Apple Silicon)
 
 The installer **creates a desktop shortcut automatically** and provides the full desktop experience (tray). The first time you run the Windows installer you may see a SmartScreen warning — **this is normal for unsigned programs, not a virus**, see "Windows SmartScreen warning" below.
 
-**Option 2: register as a DSH plugin (developers/power users only) — ⚠️ this command does NOT install any desktop app**
+**Option 2: install as a DSH plugin (DSH ecosystem users)**
 
 ```sh
 dsh plugin --profile web add dsh-clean-desktop-shell
 ```
 
-> **Important**: Option 2 only "registers" the shell into your DSH profile. **No desktop app appears on your machine** — no installer, no desktop icon, no tray. It is meant for developers who want the shell mounted in the DSH ecosystem (reuses your web profile config, future settings integration). **For a double-clickable desktop app, use Option 1** (or run the source with `npm run dev`).
+Restart `dsh web` and the desktop shell window **opens automatically** (the first run prepares the Electron runtime over the network, ~1-2 minutes).
+
+> Option 2 gives you a shell that launches alongside DSH: the window is spawned by the plugin when `dsh web` starts, with **no standalone installer / desktop icon**. For a double-clickable app with a desktop shortcut and auto-update, use Option 1. The core window experience is identical either way.
 
 > The shell needs a reachable `dsh web` service (local or configured remote address). See Usage.
 
@@ -87,22 +106,30 @@ Unblock-File -Path "$env:USERPROFILE\Downloads\DSH-Clean-Desktop-Shell-Setup-*.e
 ## Architecture
 
 ```
-        ┌─────────────────── Core (dsh web / headless service) ───────────────────┐
-        │  Sessions · Agent · Plugins · Memory live here, decoupled from UI       │
-        └─────────────────────────────────────────────────────────────────────────┘
-                              ▲
-              ┌───────────────┴───────────────┐
-              │   dsh-clean-desktop-shell      │
-              │   Electron shell (client)      │
-              │   tray · single-instance ·     │
-              │                              │
-              └────────────────────────────────┘
+        ┌────────────── Core (dsh web / headless service) ──────────────┐
+        │    Sessions · Agent · Plugins · Memory live here,            │
+        │    decoupled from the UI                                     │
+        └───────────────────────────┬───────────────────────────────────┘
+                                    │  http://127.0.0.1:3080 (or remote)
+                                    ▼
+        ┌───────────────────────────────────────────────────────────┐
+        │            dsh-clean-desktop-shell (Electron shell)       │
+        │      tray · single-instance · offline auto-reconnect      │
+        │      · desktop shortcut                                    │
+        │                                                           │
+        │    One shell codebase, two distribution forms:            │
+        │     ├─ Installer: standalone exe, auto-update             │
+        │     └─ Plugin: auto-pops on dsh web start                 │
+        │        (self-managed Electron runtime)                     │
+        └───────────────────────────────────────────────────────────┘
 ```
 
+- **Shell / core separation**: the shell handles only the window, tray and backend management; sessions, agents, plugins and memory all live in the core, decoupled from the UI.
 - **Default**: loads the local `127.0.0.1:3080` (your configured web profile, zero migration).
 - **Remote-capable**: configure any remote DSH address; the shell is just a window. Phones / Linux / other devices can reach the core via browser or PWA — the shell is never bound to a local service.
+- **One shell codebase, two distribution forms**: the installer (standalone exe) and the plugin (launches with `dsh web`) share the same `electron/` code — only the runtime source and launch differ (see Install).
 
-### Platform matrix
+## Platform matrix
 
 | Platform | Shell | Status |
 |:--|:--|:--|
@@ -111,29 +138,6 @@ Unblock-File -Path "$env:USERPROFILE\Downloads\DSH-Clean-Desktop-Shell-Setup-*.e
 | Linux | — (browser / PWA to the core) | Not planned |
 | Termux / phone / tablet | — (headless / PWA to the core) | Covered by remote core access |
 
-## Usage
-
-1. Start `dsh web` (or configure a remote service address).
-2. Launch the shell: it auto-detects local 3080 — loads the page if the backend is up, otherwise shows the "backend offline" screen where you can start it in one click.
-3. Drag the window by its top area (right side reserved for native buttons); close minimizes to tray by default.
-
-**All backend controls live in the tray** — the main window stays a pure shell:
-
-- Start / restart / stop the backend (with progress dialogs; stopping really
-  shuts down the service on 3080, including externally started instances)
-- Auto-detect backend · set the backend install folder (auto-detect default)
-- Reload window · check for updates · repo homepage
-
-**Window reliability (Edge-style instant refresh):**
-
-- Shows immediately on launch, never waits for the backend
-- While the backend is down, a local "backend offline" screen is shown and
-  re-probed; the real page loads automatically the moment it answers
-- The instant the backend stops (tray stop, kill or crash) the window flips
-  back to the offline screen — a stale page never fakes "still alive"
-- The offline screen has self-service buttons: reload / start backend /
-  auto-detect backend / set backend install folder
-
 ## Development
 
 ```sh
@@ -145,6 +149,17 @@ npm run pack    # package NSIS (Win) / DMG (mac)
 
 ## Changelog
 
+### 0.1.4
+- Branch 2 (plugin-market distribution) is now live: `dsh plugin add` →
+  restart `dsh web` → the desktop shell opens automatically. The Electron
+  runtime is self-provisioned by the plugin (local reuse / network-aware
+  source selection).
+- Desktop shortcut: first-run prompt + one-click "create desktop shortcut"
+  in the tray (both the installer and plugin forms).
+- Icons: Windows taskbar and macOS Dock show the whale icon in bare-runtime
+  (plugin) mode.
+- Auto-launch (login item) removed — both forms are now fully manual.
+
 ### 0.1.2
 - Windows auto-update: tray "check for updates" now downloads in the
   background with progress and installs on restart (electron-updater);

package/README.md

@@ -29,24 +29,43 @@
 | **视觉改造** | 自绘标题栏 / 毛玻璃等 | **零改造**，纯净窗口壳 |
 | **跟随上游** | 固定版本 | **跟随 rc.7** |
 
-## 安装
+## 使用
 
-> **状态提示**：插件形式安装（方式二）施工中，预计今日凌晨上线。**当前仅支持方式一安装包安装**。
+1. 若安装过插件，命令行启动 `dsh` 自动弹出桌面窗口；也可通过插件创建的桌面快捷方式双击，媲美原生桌面端的体验。
+2. 使用原网页端的一切功能。
+3. 托盘右键可以进行详细设置。主窗口不添加任何控件，保持页面纯净。
 
-**方式一：从 Release 下载安装包（推荐普通用户，唯一完整的桌面应用安装方式）**
+**后端的一切操作都在托盘右键**，主窗口保持纯壳：
+
+- 启动 / 重启 / 关闭后端（带进度弹窗；关闭会真正停掉 3080 上的服务，包括外部启动的实例）
+- 自动探测后端 · 设置后端安装文件夹（默认自动探测定位）
+- 刷新窗口 · 创建桌面快捷方式 · 检查更新 · 仓库主页
+
+**窗口的可靠性（Edge 式即时刷新）**：
+
+- 双击启动立即出窗，不等后端就绪
+- 后端没起来时显示「后端未连接」页，自动探测；后端一通立即加载
+- 后端关闭 / 被杀的一刻，窗口立刻切回离线页——不会停在旧页面假装还活着
+- 离线页内置快捷按钮：重新加载 / 启动后端 / 自动探测后端 / 设置后端安装文件夹
+
+## 安装
+
+**方式一：从 Release 下载安装包（想要独立桌面应用的用户）**
 
 - Windows：下载 `DSH-Clean-Desktop-Shell-Setup-<版本>.exe`
 - macOS：下载 `DSH-Clean-Desktop-Shell-<版本>.dmg`（Intel）或 `-arm64.dmg`（Apple Silicon）
 
 安装包会**自动创建桌面快捷方式**，并提供系统托盘等完整桌面体验。首次运行 Windows 安装包可能触发 SmartScreen 警告——**这是未签名程序的正常现象，不是病毒**，见下方「Windows SmartScreen 警告说明」。
 
-**方式二：作为 DSH 插件注册（仅开发者/高级用户）——⚠️ 这个命令不会安装任何桌面应用**
+**方式二：作为 DSH 插件安装（DSH 生态用户）**
 
 ```sh
 dsh plugin --profile web add dsh-clean-desktop-shell
 ```
 
-> **重要**：方式二只是把壳"登记"进 DSH profile，**你的电脑上不会多出任何桌面应用**——没有安装包、没有桌面图标、没有系统托盘。它只用于开发者把壳挂进 DSH 生态（复用 web profile 配置、供未来设置集成）。**想要可双击使用的桌面应用，请用方式一**（或源码 `npm run dev` 运行）。
+重启 `dsh web` 后，桌面壳窗口会**自动弹出**（首次运行需联网准备 Electron 运行时，约 1-2 分钟）。
+
+> 方式二得到的是"随 DSH 启动的桌面壳"：窗口由插件在 `dsh web` 启动时自动拉起，**不产生独立安装包 / 桌面图标**。想要可双击启动、带桌面快捷方式和自动更新的独立应用，请用方式一。两种方式的核心窗口体验一致。
 
 > 桌面壳需要本机有可用的 `dsh web` 服务（或配置的远程地址）。见下方「使用」。
 
@@ -91,21 +110,27 @@ Unblock-File -Path "$env:USERPROFILE\Downloads\DSH-Clean-Desktop-Shell-Setup-*.e
 ## 架构
 
 ```
-        ┌──────────────────── 内核（dsh web / headless 服务） ────────────────────┐
-        │  会话 · Agent · 插件 · 记忆 都在这层，与界面解耦                          │
-        └─────────────────────────────────────────────────────────────────────────┘
-                              ▲
-              ┌───────────────┴───────────────┐
-              │   dsh-clean-desktop-shell      │
-              │   Electron 壳（客户端）          │
-              │   托盘 · 单实例       │
-              └────────────────────────────────┘
+        ┌────────────── 内核（dsh web / headless 服务）──────────────┐
+        │     会话 · Agent · 插件 · 记忆 都在这层，与界面解耦          │
+        └───────────────────────────┬──────────────────────────────┘
+                                    │  http://127.0.0.1:3080（或远程地址）
+                                    ▼
+        ┌───────────────────────────────────────────────────────────┐
+        │            dsh-clean-desktop-shell（Electron 壳）          │
+        │       托盘 · 单实例 · 离线自动重连 · 桌面快捷方式            │
+        │                                                           │
+        │    同一份壳代码，两种分发形态：                              │
+        │     ├─ 安装包版：独立 exe，双击即用，自动更新                │
+        │     └─ 插件版：随 dsh web 启动自动弹窗（自管 Electron 运行时）│
+        └───────────────────────────────────────────────────────────┘
 ```
 
+- **壳 / 内核分离**：壳只负责窗口、托盘、后端管理；会话、Agent、插件、记忆都在内核层，与界面解耦。
 - **默认**：加载本地 `127.0.0.1:3080`（已配置好的 web profile，零迁移）。
 - **可配远程**：在设置里填入任意远程 DSH 地址，壳只当窗口——手机 / Linux / 其他设备通过浏览器或 PWA 也能接入内核，壳本身不绑定本地服务。
+- **同一套壳代码，两种分发形态**：安装包版（独立 exe）与插件版（随 `dsh web` 启动）共用 `electron/` 壳代码，仅运行时来源与启动方式不同（见「安装」）。
 
-### 平台矩阵
+## 平台矩阵
 
 | 平台 | 壳 | 状态 |
 |:--|:--|:--|
@@ -114,25 +139,6 @@ Unblock-File -Path "$env:USERPROFILE\Downloads\DSH-Clean-Desktop-Shell-Setup-*.e
 | Linux | —（浏览器 / PWA 直连内核） | 不做 |
 | Termux / 手机 / 平板 | —（headless / PWA 直连内核） | 由内核远程访问支持 |
 
-## 使用
-
-1. 启动 `dsh web`（或配置远程服务地址）。
-2. 启动桌面壳：自动检测本地 3080——后端在跑则直接加载，未运行则显示「后端未连接」页，可在离线页一键启动。
-3. 窗口顶部（右侧留系统按钮）可拖动窗口；关闭默认缩到托盘。
-
-**后端的一切操作都在托盘右键**，主窗口保持纯壳：
-
-- 启动 / 重启 / 关闭后端（带进度弹窗；关闭会真正停掉 3080 上的服务，包括外部启动的实例）
-- 自动探测后端 · 设置后端安装文件夹（默认自动探测定位）
-- 刷新窗口 · 检查更新 · 仓库主页
-
-**窗口的可靠性（Edge 式即时刷新）**：
-
-- 双击启动立即出窗，不等后端就绪
-- 后端没起来时显示「后端未连接」页，自动探测；后端一通立即加载
-- 后端关闭 / 被杀的一刻，窗口立刻切回离线页——不会停在旧页面假装还活着
-- 离线页内置快捷按钮：重新加载 / 启动后端 / 自动探测后端 / 设置后端安装文件夹
-
 ## 开发
 
 ```sh
@@ -144,6 +150,12 @@ npm run pack    # 打包 NSIS (Win) / DMG (mac)
 
 ## 更新历史
 
+### 0.1.4
+- 分支二（插件市场分发）正式可用：`dsh plugin add` 装插件 → 重启 `dsh web` → 桌面壳自动弹出；Electron 运行时由插件自管理（本地复用 / 按网络环境自动选源下载）。
+- 桌面快捷方式：首次启动询问创建 + 托盘「创建桌面快捷方式」一键添加（安装包与插件两种形态均支持）。
+- 图标：Windows 任务栏 / macOS Dock 均显示鲸鱼图标（裸运行时场景）。
+- 移除开机自启（两种形态统一为纯手动启动）。
+
 ### 0.1.2
 - Windows 自动更新：托盘「检查更新」改为后台下载 + 进度显示 + 重启安装（electron-updater）；macOS 仍为手动下载。
 - 移除启动时自动拉起后端（改纯手动，与「关闭后端」不冲突）。

package/electron/aumid.js

@@ -0,0 +1,17 @@
+import { app } from 'electron'
+
+/**
+ * AppUserModelID, shared by main (process-level), window (taskbar button)
+ * and shortcut (Start-menu .lnk) so the three always agree.
+ *
+ * Why plugin mode gets its own ID: Windows caches the taskbar button icon
+ * per AUMID. If the plugin shell reuses the installer's ID that ever ran
+ * with Electron's default icon (an early dev launch / an old build), the
+ * taskbar keeps showing that stale icon — no window `icon`, `setAppDetails`
+ * or exe patch can override the cache. A distinct ID makes Windows treat it
+ * as a brand-new app and re-read the icon. It also keeps the plugin shell
+ * from merging with an installed copy on the same machine.
+ */
+export const APP_USER_MODEL_ID = app.isPackaged
+  ? 'com.icather.dsh-clean-desktop-shell'
+  : 'com.icather.dsh-clean-desktop-shell.plugin'

package/electron/main.js

@@ -8,20 +8,39 @@
  *
  * The main window is a pure shell — all backend controls live in the tray.
  */
-import { app, BrowserWindow, dialog } from 'electron'
+import { app, BrowserWindow, dialog, nativeImage } from 'electron'
+import { fileURLToPath } from 'node:url'
 import { createMainWindow, reloadWindow } from './window.js'
 import { createTray, refreshTrayMenu } from './tray.js'
 import { loadConfig, saveConfig } from './config.js'
 import { detect } from './service.js'
 import { setupAutoUpdater } from './update.js'
-import { shortcutSupported, hasDesktopShortcut, createDesktopShortcut } from './shortcut.js'
+import { shortcutSupported, hasDesktopShortcut, createDesktopShortcut, ensureStartMenuShortcut } from './shortcut.js'
+import { APP_USER_MODEL_ID } from './aumid.js'
 
 const isMac = process.platform === 'darwin'
 
 // Windows: pin the AppUserModelId so the taskbar shows our whale icon
-// instead of the generic Electron icon.
+// instead of the generic Electron icon. Plugin mode uses a distinct ID
+// (see aumid.js) so Windows re-reads the icon instead of serving a
+// stale per-AUMID cached one.
 if (process.platform === 'win32') {
-  app.setAppUserModelId('com.icather.dsh-clean-desktop-shell')
+  app.setAppUserModelId(APP_USER_MODEL_ID)
+}
+
+// macOS: a bare runtime has no .app bundle (no icon resource), so set the
+// Dock icon at runtime. Unlike Windows there is no per-AUMID taskbar cache
+// here — app.dock.setIcon applies directly. Packaged builds already carry
+// the icon in their bundle, so skip those.
+if (isMac && !app.isPackaged) {
+  try {
+    const dockIcon = nativeImage.createFromPath(
+      fileURLToPath(new URL('../build/icon.png', import.meta.url)),
+    )
+    if (!dockIcon.isEmpty()) app.dock.setIcon(dockIcon)
+  } catch {
+    // non-fatal: keep the default icon
+  }
 }
 
 // Uniform userData across both distribution branches (installer vs
@@ -130,6 +149,14 @@ if (!gotLock) {
     // Windows: wire the auto-updater (downloads new installers silently).
     setupAutoUpdater()
 
+    // Windows: ensure the AUMID-carrying Start-menu shortcut exists so the
+    // taskbar button shows our icon (see shortcut.js). Best-effort.
+    try {
+      ensureStartMenuShortcut()
+    } catch {
+      // non-fatal
+    }
+
     // First run: offer a desktop shortcut (never nags twice).
     ensureShortcut().catch(() => {})
 

package/electron/shortcut.js

@@ -5,20 +5,44 @@
  *  - first-run prompt in main.js ("create a desktop shortcut?")
  *  - the tray "create desktop shortcut" item (always available)
  *
- * Only meaningful for packaged apps — in dev mode there is no stable
- * executable to point the shortcut at, so the feature is disabled there.
+ * Works in both distribution branches:
+ *  - installer (packaged): targets the installed exe, no arguments
+ *  - plugin-market (bare runtime): targets the provisioned electron.exe
+ *    with the plugin's electron/main.js as its argument
+ *
+ * Pure dev mode (npm run dev from a checkout) has no stable executable,
+ * so the feature stays disabled there.
  */
-import { app } from 'electron'
+import { app, shell } from 'electron'
 import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { APP_USER_MODEL_ID } from './aumid.js'
 
 const isWin = process.platform === 'win32'
 const SHORTCUT_NAME = 'DSH Clean Desktop Shell.lnk'
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+const ICON_ICO = join(PKG_ROOT, 'build', 'icon.ico')
+
+/**
+ * Plugin-market mode: the host half spawns a bare electron runtime with the
+ * plugin's electron/main.js as its entry. process.execPath is the runtime
+ * electron.exe; process.argv[1] is the entry script (packaged installers
+ * have no such argument).
+ */
+function pluginArgs() {
+  if (app.isPackaged) return []
+  const entry = process.argv[1]
+  if (entry && /\.js$/i.test(entry)) return [entry]
+  return []
+}
 
-/** Shortcuts are a Windows packaged-app feature. */
+/** Shortcuts need a stable executable — supported when packaged or in
+ *  plugin mode (where the runtime path is fixed under DSH_HOME). */
 export function shortcutSupported() {
-  return isWin && app.isPackaged
+  return isWin && (app.isPackaged || pluginArgs().length > 0)
 }
 
 function ps(str) {
@@ -59,14 +83,48 @@ export async function hasDesktopShortcut() {
 export async function createDesktopShortcut() {
   if (!shortcutSupported()) return false
   const target = process.execPath
+  const args = pluginArgs()
   const lnk = join(homedir(), 'Desktop', SHORTCUT_NAME)
+  // Plugin mode: point the shortcut at the runtime exe + main.js argument.
+  // WScript needs the path double-quoted inside the Arguments string.
+  const argPart = args.length
+    ? `; $s.Arguments = ${ps(`"${args[0]}"`)}; `
+    : ''
+  // Plugin-mode exe has no custom icon resource — point the shortcut at the
+  // bundled .ico when present (packaged installers use the exe itself).
+  const iconLoc = existsSync(ICON_ICO) ? ICON_ICO : `${target},0`
   const script =
     `$ws = New-Object -ComObject WScript.Shell; ` +
     `$s = $ws.CreateShortcut(${ps(lnk)}); ` +
     `$s.TargetPath = ${ps(target)}; ` +
+    argPart +
     `$s.WorkingDirectory = ${ps(dirname(target))}; ` +
-    `$s.IconLocation = ${ps(`${target},0`)}; ` +
+    `$s.IconLocation = ${ps(iconLoc)}; ` +
     `$s.Save()`
   const out = await runPs(script)
   return out !== null
 }
+
+/**
+ * Ensure a Start-menu shortcut carrying the AppUserModelID. This is what
+ * makes the taskbar button show our icon: Windows matches a running
+ * window's AUMID to a shortcut's icon (bare runtime electron.exe has no
+ * icon resource of its own). Idempotent — the shortcut is only created
+ * when missing.
+ */
+export function ensureStartMenuShortcut() {
+  if (!isWin || !shortcutSupported()) return false
+  const lnkDir = join(
+    process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'),
+    'Microsoft', 'Windows', 'Start Menu', 'Programs',
+  )
+  const lnk = join(lnkDir, SHORTCUT_NAME)
+  const args = pluginArgs()
+  return shell.writeShortcutLink(lnk, 'create', {
+    target: process.execPath,
+    args: args.length ? args.join(' ') : undefined,
+    icon: existsSync(ICON_ICO) ? ICON_ICO : undefined,
+    iconIndex: 0,
+    appUserModelId: APP_USER_MODEL_ID,
+  })
+}

package/electron/window.js

@@ -15,16 +15,26 @@
  *    window flips back to the offline screen instead of showing a stale page
  *    that suggests the app is still alive.
  */
-import { BrowserWindow, ipcMain } from 'electron'
+import { app, BrowserWindow, ipcMain } from 'electron'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { probe, onStatusChange, detect } from './service.js'
 import { startBackendWithProgress, chooseBackendFolder } from './tray.js'
+import { APP_USER_MODEL_ID } from './aumid.js'
 
 export const WINDOWS_TITLEBAR_HEIGHT = 32
 
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 const PRELOAD_PATH = fileURLToPath(new URL('./preload.js', import.meta.url))
+// Windows taskbar follows the window icon only when it is an .ico; a png
+// covers the title bar / alt-tab but not the taskbar button. In plugin
+// mode there is no exe icon resource, so prefer the bundled .ico.
+const TASKBAR_ICO = join(PKG_ROOT, 'build', 'icon.ico')
 // Black-whale app icon (matches the DSH web favicon).
-const ICON_PATH = fileURLToPath(new URL('../build/icon.png', import.meta.url))
+const ICON_PATH = existsSync(TASKBAR_ICO)
+  ? TASKBAR_ICO
+  : fileURLToPath(new URL('../build/icon.png', import.meta.url))
 // Local fallback page shown while the backend is down.
 const ERROR_PAGE = fileURLToPath(new URL('./error.html', import.meta.url))
 
@@ -189,6 +199,15 @@ export function createMainWindow({ target }) {
   // Linux / other: keep the native frame.
 
   const win = new BrowserWindow(options)
+  // Windows taskbar button: bare runtime electron.exe has no custom icon,
+  // so pin the button to our .ico via setAppDetails (appId must match the
+  // app-level AppUserModelId set in main.js, else the options are ignored).
+  if (process.platform === 'win32' && existsSync(TASKBAR_ICO)) {
+    win.setAppDetails({
+      appId: APP_USER_MODEL_ID,
+      appIconPath: TASKBAR_ICO,
+    })
+  }
   windowTargets.set(win.id, target)
   win.loadURL(target).catch(() => startReconnect(win, target))
 

package/lib/client.js

@@ -1,10 +1,19 @@
 /**
  * dsh-clean-desktop-shell — client half (web browser bundle).
  *
- * Registers a settings row so the shell's target URL / material options
- * are editable from Settings → General. This is a minimal placeholder:
- * real UI wiring lands with the Electron shell work.
+ * The shell is a standalone Electron window; it injects nothing into the
+ * dsh web UI. This client module exists only to satisfy the client-modules
+ * loader contract — a bundle's client entry must register itself via
+ * `window.__ModuleLoader__.load({ id, factory })`, otherwise dsh reports
+ * "loaded without registering … via __ModuleLoader__.load".
  */
-export function apply() {
-  // placeholder: settings-row wiring arrives with the shell implementation
-}
+window.__ModuleLoader__.load({
+  id: 'dsh-clean-desktop-shell',
+  factory: () => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+    exports.apply = () => {};
+    return module.exports;
+  },
+});

package/lib/common.js

@@ -0,0 +1,22 @@
+/**
+ * Shared constants and helpers for the host half modules.
+ *
+ * These compiled files sit at lib/<name>.js, so two dirname hops reach the
+ * package root — the same layout as src/host/ before build, and the same
+ * location electron/ and build/ live in the published package.
+ */
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+export const MAIN_JS = join(PKG_ROOT, 'electron', 'main.js')
+export const isWin = process.platform === 'win32'
+export const EXE_NAME = isWin ? 'electron.exe' : 'electron'
+export const ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
+export const PLATFORM = isWin ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux'
+
+/** Where the self-provisioned runtimes live (shared with icon.js). */
+export function runtimeRoot() {
+  return join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'desktop-shell-runtime')
+}

package/lib/icon.js

@@ -0,0 +1,63 @@
+/**
+ * Patch the runtime electron.exe's icon resource so the Windows taskbar
+ * shows our whale icon.
+ *
+ * A bare runtime exe ships Electron's default icon and — as documented —
+ * no runtime API (BrowserWindow icon, setAppDetails, AUMID shortcuts) can
+ * change the taskbar button: it reads the exe's icon resource. rcedit
+ * (electron team's official tool) rewrites it in place.
+ *
+ * Best-effort: icon patching must never block the shell from launching.
+ * Idempotent: a marker file next to the exe records success; a re-provisioned
+ * (new version) exe has no marker and gets patched again.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PKG_ROOT, isWin, runtimeRoot } from './common.js'
+
+export async function patchExeIcon(ctx, exe) {
+  if (!isWin) return
+  const ico = join(PKG_ROOT, 'build', 'icon.ico')
+  if (!existsSync(ico)) return
+  const marker = `${exe}.whale-icon`
+  if (existsSync(marker)) return
+
+  // rcedit is a single self-contained exe, cached next to the runtimes.
+  const rcedit = join(runtimeRoot(), 'rcedit-x64.exe')
+  if (!existsSync(rcedit)) {
+    const url = 'https://github.com/electron/rcedit/releases/download/v2.0.0/rcedit-x64.exe'
+    ctx.logger.info('[clean-desktop-shell] downloading rcedit for icon patching')
+    if (!(await fetchFile(url, rcedit))) {
+      ctx.logger.warn('[clean-desktop-shell] rcedit download failed — taskbar icon stays default')
+      return
+    }
+  }
+
+  const child = spawn(rcedit, [exe, '--set-icon', ico], {
+    windowsHide: true,
+    stdio: 'ignore',
+  })
+  const ok = await new Promise((resolve) => {
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
+  })
+  if (ok) {
+    writeFileSync(marker, String(Date.now()), 'utf8')
+    ctx.logger.info('[clean-desktop-shell] taskbar icon patched (rcedit)')
+  } else {
+    ctx.logger.warn('[clean-desktop-shell] rcedit patch failed — taskbar icon stays default')
+  }
+}
+
+function fetchFile(url, dest) {
+  return new Promise((resolve) => {
+    const child = spawn(
+      'curl',
+      ['-L', '--fail', '--silent', '--show-error', '--retry', '2', '--max-time', '600', '-o', dest, url],
+      { windowsHide: true, stdio: 'ignore' },
+    )
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
+  })
+}