dsh-vision-router 1.2.2 → 1.2.3

package/README.md

@@ -28,9 +28,11 @@
 <p align="center">💬 <strong>QQ community group: 1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **Announcement (v1.2.2)**
+> 📌 **Announcement (v1.2.3)**
 >
-> v1.2.2 closes the last attachment-id gap — ids announced for images the host persisted itself (e.g. `read_image` re-uploads, `sha256:…`) now resolve in `vision_describe` and every pixel tool (issue #72) — stops `vision_present` and other tool-result image blocks from ever locking a text-model session with `UNSUPPORTED_CONTENT` (issue #74; already-locked sessions heal after upgrading), and warns loudly when a stale sharp left over from a pre-v1.2 upgrade would break the pixel tools with `colourspace: parameter space not set` (issue #75).
+> v1.2.3 fixes DSH Desktop's re-appearing first-run dialog: the onboarding "seen" flag and the model-guide step now persist in the profile settings file instead of origin-scoped `localStorage`, which a random per-launch port (`--port 0`) wiped on every boot (issue #78).
+>
+> v1.2.2 closed the last attachment-id gap — ids announced for images the host persisted itself (e.g. `read_image` re-uploads, `sha256:…`) now resolve in `vision_describe` and every pixel tool (issue #72) — stopped `vision_present` and other tool-result image blocks from ever locking a text-model session with `UNSUPPORTED_CONTENT` (issue #74; already-locked sessions heal after upgrading), and warned loudly when a stale sharp left over from a pre-v1.2 upgrade would break the pixel tools with `colourspace: parameter space not set` (issue #75).
 >
 > v1.2.1 hardened the pixel loop: all eleven pixel tools now accept uploaded-image attachment ids directly (no more `cannot read …/sha256:…` round trips), artifact filenames carry collision-free fingerprints, `vision_ground` retries degenerate boxes, the model guide replays fully from step 1 (leaving the settings first), and the settings card scrolls smoothly even with hundreds of models per provider.
 

package/README.zh.md

@@ -28,7 +28,9 @@
 <p align="center">💬 <strong>QQ 用户交流群：1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **公告（v1.2.2）**
+> 📌 **公告（v1.2.3）**
+>
+> v1.2.3 现已支持：修复 DSH Desktop 每次启动都重复弹出首次引导的问题——引导「已读」标记与模型引导步骤改存 profile 设置文件（不再依赖按 origin 隔离、每次随机端口重启即清零的 `localStorage`）（issue #78）。
 >
 > v1.2.2 现已支持：补上最后一处附件 ID 缺口——宿主 `read_image` 回挂图片公布的 `sha256:…` ID 现在可被 `vision_describe` 与全部像素工具解析（issue #72）；`vision_present` 等工具结果里的图像块不再把文本模型会话锁死在 `UNSUPPORTED_CONTENT`（issue #74，已锁死的历史会话升级后自动修复）；检测到 v1.1.x 升级残留的旧版 sharp 时明确告警，把玄学的 `colourspace` 报错变成一眼可见的修复指引（issue #75）。
 >

package/index.js

@@ -233,6 +233,15 @@ export const Config = z.object({
   tool: z.boolean().default(true),
   progressiveTools: z.boolean().default(true),
   autoActivateOnImage: z.boolean().default(true),
+  // Client-persisted UI state (issue #78): DSH Desktop serves the Web UI from
+  // a random port on every launch, so origin-scoped localStorage forgets the
+  // first-run onboarding dialog and it re-appeared on every boot. These keys
+  // live in the settings section (the profile settings file) instead; the
+  // client still mirrors best-effort copies into localStorage for downgrades.
+  // Both are internal to the client bundle — the settings card renders them
+  // nowhere, and the server half never reads them.
+  onboardingSeen: z.boolean().default(false),
+  visionGuideStep: z.string().default(''),
   artifactsDir: z.string().default('.dsh-vision-router/artifacts'),
   rewriteImages: z.boolean().default(true),
   downscale: z.boolean().default(true),

package/lib/client.js

@@ -554,20 +554,116 @@ window.__ModuleLoader__.load({
     }
 
     const ONBOARDING_STORAGE_KEY = 'dsh-vision-router:onboarding:model-guide-v2'
+    // issue #78: DSH Desktop serves the Web UI from a random port on every
+    // launch (--port 0), so origin-scoped localStorage forgets everything
+    // between restarts and the first-run dialog re-appeared on every boot.
+    // The durable source of truth is now the `vision-router` settings section
+    // (the profile settings file, synced through ctx.settingsScope);
+    // localStorage survives only as a legacy/migration fallback for
+    // pre-v1.2.3 browsers and as a best-effort downgrade channel.
+    const ONBOARDING_SETTINGS_KEY = 'onboardingSeen'
     // The walkthrough has three steps: step1 (the session/text model selector
     // on the chat page), step2 (open Settings → Plugins → Vision Router), and
     // step3 (the highlighted vision chain, rendered by the settings card as a
     // callout). Only step1/step2 need persistence; step3 re-derives from the
     // card being on screen.
     const VISION_GUIDE_STORAGE_KEY = 'dsh-vision-router:guide:vision-backend-v2'
+    const VISION_GUIDE_SETTINGS_KEY = 'visionGuideStep'
     const VISION_GUIDE_EVENT = 'dsh-vision-router:vision-settings-guide'
     let visionGuidePrompt
     let visionGuideStepMemory
+    // Installed by apply(): a narrow, defensive view of the settings scope.
+    // { get, set, unset } never throw, and subscribe returns a disposer (or
+    // undefined when the scope is unavailable — the legacy paths take over).
+    let settingsPersistence
+    function installSettingsPersistence(scope) {
+      const readSection = () => {
+        try {
+          const snapshot = scope && scope.getSnapshot && scope.getSnapshot()
+          return snapshot && snapshot.value ? snapshot.value : undefined
+        } catch {
+          return undefined
+        }
+      }
+      settingsPersistence = {
+        get(field) {
+          const section = readSection()
+          return section ? section[field] : undefined
+        },
+        set(field, value) {
+          try {
+            const snapshot = scope && scope.getSnapshot && scope.getSnapshot()
+            if (!snapshot || !snapshot.writable || typeof scope.set !== 'function') return
+            void scope.set(field, value)
+          } catch {
+            // Read-only provider or unavailable scope: the localStorage
+            // fallback keeps this load functional.
+          }
+        },
+        unset(field) {
+          try {
+            const snapshot = scope && scope.getSnapshot && scope.getSnapshot()
+            if (!snapshot || !snapshot.writable || typeof scope.unset !== 'function') return
+            void scope.unset(field)
+          } catch {
+            // Same fallback reasoning as set().
+          }
+        },
+        subscribe(listener) {
+          try {
+            return scope && typeof scope.subscribe === 'function' ? scope.subscribe(listener) : undefined
+          } catch {
+            return undefined
+          }
+        },
+      }
+    }
+
+    function readOnboardingSeen() {
+      try {
+        if (settingsPersistence && settingsPersistence.get(ONBOARDING_SETTINGS_KEY) === true) return true
+      } catch {
+        // Fall through to the legacy origin-scoped marker.
+      }
+      try {
+        if (window.localStorage && window.localStorage.getItem(ONBOARDING_STORAGE_KEY) === 'seen') {
+          // Legacy value from before the settings-backed flag: migrate it so
+          // it survives desktop restarts, then honor it for this load.
+          if (settingsPersistence) settingsPersistence.set(ONBOARDING_SETTINGS_KEY, true)
+          return true
+        }
+      } catch {
+        // Best effort only.
+      }
+      return false
+    }
+    function rememberOnboardingSeen() {
+      try {
+        if (settingsPersistence) settingsPersistence.set(ONBOARDING_SETTINGS_KEY, true)
+      } catch {
+        // The dialog can still be dismissed for this page load.
+      }
+      try {
+        if (window.localStorage) window.localStorage.setItem(ONBOARDING_STORAGE_KEY, 'seen')
+      } catch {
+        // Best effort: the dialog can still be dismissed for this page load.
+      }
+    }
 
     function readVisionGuideStep() {
       try {
-        const value = window.localStorage && window.localStorage.getItem(VISION_GUIDE_STORAGE_KEY)
+        const value = settingsPersistence && settingsPersistence.get(VISION_GUIDE_SETTINGS_KEY)
         if (value === 'step1' || value === 'step2') return value
+      } catch {
+        // Fall through to the legacy origin-scoped marker.
+      }
+      try {
+        const value = window.localStorage && window.localStorage.getItem(VISION_GUIDE_STORAGE_KEY)
+        if (value === 'step1' || value === 'step2') {
+          // Legacy value: migrate into settings for desktop durability.
+          if (settingsPersistence) settingsPersistence.set(VISION_GUIDE_SETTINGS_KEY, value)
+          return value
+        }
       } catch {
         // Fall through to page-memory state when storage access is blocked.
       }
@@ -575,6 +671,14 @@ window.__ModuleLoader__.load({
     }
     function writeVisionGuideStep(step) {
       visionGuideStepMemory = step === 'step1' || step === 'step2' ? step : undefined
+      try {
+        if (settingsPersistence) {
+          if (visionGuideStepMemory) settingsPersistence.set(VISION_GUIDE_SETTINGS_KEY, visionGuideStepMemory)
+          else settingsPersistence.unset(VISION_GUIDE_SETTINGS_KEY)
+        }
+      } catch {
+        // Page-memory state still keeps the guide functional for this load.
+      }
       try {
         if (!window.localStorage) return
         if (visionGuideStepMemory) window.localStorage.setItem(VISION_GUIDE_STORAGE_KEY, visionGuideStepMemory)
@@ -677,9 +781,13 @@ window.__ModuleLoader__.load({
       syncVisionGuidePrompt(t)
       window.addEventListener(VISION_GUIDE_EVENT, sync)
       window.addEventListener('popstate', sync)
+      // The durable step now lives in the settings section; re-sync when its
+      // snapshot changes (e.g. the first read resolves after page load).
+      const unsubscribe = settingsPersistence && settingsPersistence.subscribe(sync)
       return () => {
         window.removeEventListener(VISION_GUIDE_EVENT, sync)
         window.removeEventListener('popstate', sync)
+        if (typeof unsubscribe === 'function') unsubscribe()
         removeVisionGuidePrompt()
       }
     }
@@ -687,13 +795,6 @@ window.__ModuleLoader__.load({
     let onboardingOverlay
     let onboardingKeyDown
 
-    function rememberOnboardingSeen() {
-      try {
-        if (window.localStorage) window.localStorage.setItem(ONBOARDING_STORAGE_KEY, 'seen')
-      } catch {
-        // Best effort: the dialog can still be dismissed for this page load.
-      }
-    }
     function dismissOnboarding(remember = true) {
       if (remember) rememberOnboardingSeen()
       if (typeof document !== 'undefined' && onboardingKeyDown) {
@@ -779,16 +880,33 @@ window.__ModuleLoader__.load({
     }
     function installOnboarding(t) {
       if (typeof document === 'undefined' || typeof window === 'undefined') return
-      try {
-        if (window.localStorage && window.localStorage.getItem(ONBOARDING_STORAGE_KEY) === 'seen') return
-      } catch {
-        // Privacy/storage restrictions should not prevent the guidance itself.
+      let timer
+      const clearTimer = () => {
+        if (timer !== undefined) window.clearTimeout(timer)
+        timer = undefined
       }
-
-      const timer = window.setTimeout(() => showOnboarding(t), 650)
-
+      // Reactive against the settings scope: the settings snapshot arrives
+      // asynchronously on a cold page load, so a one-shot localStorage check
+      // could show the dialog before the durable "seen" flag lands. Re-sync
+      // on every snapshot change and dismiss the overlay if the flag appears.
+      const sync = () => {
+        if (readOnboardingSeen()) {
+          clearTimer()
+          if (onboardingOverlay) dismissOnboarding(false)
+          return
+        }
+        if (timer === undefined && !onboardingOverlay) {
+          timer = window.setTimeout(() => {
+            timer = undefined
+            if (!readOnboardingSeen()) showOnboarding(t)
+          }, 650)
+        }
+      }
+      sync()
+      const unsubscribe = settingsPersistence && settingsPersistence.subscribe(sync)
       return () => {
-        if (timer !== undefined) window.clearTimeout(timer)
+        clearTimer()
+        if (typeof unsubscribe === 'function') unsubscribe()
         // Unmounting is not a user choice: drop the dialog without marking
         // the guide seen, so the first-run overview can still auto-open.
         if (onboardingOverlay) dismissOnboarding(false)
@@ -1894,6 +2012,10 @@ window.__ModuleLoader__.load({
 
     function apply(ctx) {
       const scope = ctx.settingsScope.bind({ namespace: 'vision-router' })
+      // issue #78: route the onboarding/guide durability through the settings
+      // section (profile settings file) so it survives DSH Desktop's random
+      // per-launch port. Installed before the effects below run.
+      installSettingsPersistence(scope)
       const presentedImageUrls = new Map()
       const createdImageUrls = new Set()
       const loadPresentedImage = (sessionId, attachment) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vision-router",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Eyes for text-only DeepSeek Harness agents: built-in free vision chain (no key) + pixel-level vision tools (Q&A, grounding, crop, pixel diff, colors, OCR, SVG trace, cutout, screenshots). One-command install, no Python, image turns work like ordinary tool-calling turns.",
   "license": "MIT",
   "repository": {