dsh-vision-router 3.2.0 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ # v3.2.1 — Settings recovery, VTracer and RC2 Host qualification / 设置恢复、VTracer 与 RC2 兼容验收
2
+
3
+ **Status / 状态:** This is the curated stable v3.2.1 **release candidate note**. A successful protected Release workflow, GitHub Release, npm `latest` and matching package/provenance are necessary before it may be called published. / 本文是 v3.2.1 正式候选发布说明;实际发布必须以受保护 Release 工作流、GitHub Release、npm `latest` 和一致的包体及来源证明为准。
4
+
5
+ ## Since v3.2.0 / 相对 v3.2.0 的变化
6
+
7
+ - **Settings bridge recovery (#823, #828):** Unify the opt-in local/authorized remote configuration path, eliminate conflicting compatibility-script ordering, and mount the native provider settings bridge through the correct Host lifecycle. Reinforce authentication, redaction, permission boundaries and Settings save/readback/reload regression coverage. / 统一本地及经授权的远程设置通道,修复兼容脚本加载顺序和原生设置服务挂载时序,补齐认证、脱敏、权限和设置保存/回读/重载验证。
8
+ - **SVG trace backend (#829):** Replace `potrace → jimp → @jimp/core` with pinned `@visioncortex/vtracer@1.0.0-alpha.4` WASM in an isolated Worker. Preserve the public `vision_trace` entry point while improving dependency/license provenance checks and image-quality test coverage. The trace renderer changes, so SVG path geometry and output may differ from v3.2.0. / 将 SVG 追踪依赖从 Potrace/Jimp 换为固定版本的 VTracer WASM Worker;保留公开工具入口,强化依赖许可与输出质量测试。生成的 SVG 路径形状可能与旧版不同。
9
+ - **Exact DSH 0.2.2-rc.2 acceptance (#830):** Pin official upstream source SHA and verify Session atomic-batch per-event semantics, route ownership, three-OS Host contracts, Chromium Settings and paste flows, macOS and Windows real Desktop, candidate tarball installation, and separately diagnose immutable published 3.2.0 on the real RC2 CLI/Web Host. / 固定 RC2 上游精确提交,对批量事件、路由、三端、真实浏览器/桌面、候选安装包及历史 npm 包做独立验收。
10
+ - **CI supply-chain maintenance (#824, #825):** Upgrade pinned CodeQL SARIF uploader and pnpm/action-setup; cover all 30 relevant workflows including the new RC2 gate. / 更新 CodeQL 与 pnpm Actions 固定 SHA,覆盖全部相关工作流。
11
+
12
+ ## Compatibility and safe upgrade / 兼容边界与安全升级
13
+
14
+ - **No support-floor relaxation:** DSH `>=0.2.1-rc.5 <0.3.0-0` and Node.js `>=24.9.0` remain required. DSH `0.2.1-rc.3` and `0.2.0-rc.2` are **not** compatible with DVR 3.2.x; do not bypass the Host's engine admission checks. / 最低要求不变,较旧 DSH 版本明确不支持,不建议越过安装器的兼容检查。
15
+ - Run the read-only `doctor --upgrade-preflight`, back up your current DSH profile, Settings, attachments and important historical Session records, and preserve a known-good rollback path. DVR does not automatically rewrite or delete Host-owned history. / 升级前只读预检、备份、核验重要会话并保留回滚;插件不自动清理或改写 Host 数据。
16
+ - Official real Host/CLI/Web and macOS/Windows Desktop gates were run on supported exact source lines. **Third-party Dataelem Desktop's generation installer remains a separate path**: removing the Jimp chain addresses the identified dependency closure trigger but is **not evidence of a successful installation of the new npm release in that installer**. Its upstream issue and fix review remain independent. / 官方安装和第三方代际安装器须分开评价;移除 Jimp 是源码层解决已知依赖链,不代表第三方安装路径已获实测认证。
17
+ - No change to the default cloud-vision image egress: the anonymous fallback can transmit image content to a remote provider unless strict local-only mode is selected. / 默认云端视觉链仍可能将图片传给第三方;涉敏内容应启用严格纯本地配置。
18
+
19
+ ## Release integrity / 发布完整性
20
+
21
+ The final candidate must pass fresh main-commit CI and the protected workflow's frozen-lockfile install, build, lint, typecheck, tests, reproducible build, exact published file inventory, SHA/signing/provenance and npm `latest` versus GitHub Release cross-check. Never infer publication merely from this document or a Git tag. / 最终提交须重新通过 CI 与受保护发布门禁,对 npm 与 GitHub 的同一包体、哈希和来源证明作交叉核验。
@@ -1,15 +1,90 @@
1
- # Remote Vision Router settings
1
+ # Vision Router settings: one configuration, two Host transports
2
2
 
3
- Vision Router uses a dedicated DSH Connection RPC channel at `/vision-router-settings/*` because the global DSH settings/credentials plane is intentionally loopback-only.
3
+ Vision Router has **one** Host-owned `vision-router` configuration namespace and
4
+ one schema, revision check and persistence authority. It needs two transport
5
+ adapters for historical DSH browser APIs, **not two different sets of editable
6
+ configuration fields**:
4
7
 
5
- Remote editing is off by default. When a Vision Router settings page is opened through a DSH trusted host while the permission is still disabled, the page shows an explicit risk confirmation. Cancelling leaves remote editing disabled and writes nothing. Confirming enables only `allowRemoteSettings`, then reloads the scoped Vision Router settings immediately. The same permission can still be enabled or revoked from the loopback settings page.
8
+ - **Local Web / official Desktop:** `settingsScope` when supported, otherwise
9
+ the local ConfigEditor-backed `/_dsh/vision-router/local-settings` bridge.
10
+ The latter is strictly local-only and checks both transport provenance and
11
+ the Host's authenticated browser-session rejection result before any read or
12
+ write. No user-facing remote risk prompt is needed.
13
+ - **Remote Web:** `/vision-router-settings/*` over DSH Connection RPC.
14
+ The authenticated Host carrier is mandatory, and the first disabled
15
+ `describe` triggers the user's explicit risk notice. Accepting persists
16
+ `allowRemoteSettings=true` in the Host profile and immediately refreshes
17
+ the settings. Once enabled, ordinary DVR configuration fields have the same
18
+ editability as on the local page.
6
19
 
7
- DSH `trustedHosts` protects the browser carrier against Host/Origin/DNS-rebinding attacks; it is **not user authentication**. Enable remote editing only when you trust the clients that can reach the DSH instance. Ordinary remote mutations remain restricted to the explicit Vision Router allow-list. Credential-bearing HTTP providers, local Ollama/LM Studio configuration, artifact paths and every other field not present in that allow-list stay unavailable remotely. `allowRemoteSettings` itself is not added to the ordinary mutation allow-list: it can be enabled only through the explicit risk-confirmation flow (or from the loopback settings page).
20
+ The remote transport does **not** maintain a separate capability allow-list for
21
+ ordinary configuration. Network and proxy overrides, local Ollama / LM Studio
22
+ definitions, HTTP provider settings, route names, desktop screenshot preference
23
+ and the `localOnlyVision` privacy switch use the same Host schema and
24
+ authoritative revisioned mutation path after the acknowledgement. The local-only
25
+ privacy switch is visible remotely, so take special care when changing it:
26
+ disabling it can permit image traffic to cloud vision providers. A remote change
27
+ does not itself grant operating-system screen-recording permission.
8
28
 
9
- The transport contract differs across supported DSH generations without changing that security model. On the rc.8 Connection contract, Vision Router registers the dedicated channel with the required per-channel `{ authority: 'trusted-host' }` option. Newer Connection contracts expose the carrier-level `requestRejection()` / BrowserAuth fence and `rpc.handle()` no longer accepts a channel authority option; Vision Router feature-detects that carrier and registers with the modern two-argument form. The remote field allow-list and `allowRemoteSettings` gate remain authoritative in both cases.
29
+ `allowRemoteSettings` itself is **not** an ordinary remote mutation: it is
30
+ enabled by the risk-confirmation flow and can be revoked from the local settings
31
+ page. It remains opt-in and off by default. Revocation takes effect on the
32
+ next RPC request; it does not erase the prior acknowledgement from history.
33
+ The acknowledgement is a UX safeguard, **not authentication or proof of local
34
+ presence**. DSH `trustedHosts` alone is likewise *not* authentication.
35
+ Browser-session authentication, Host/Origin policy, and the Connection RPC
36
+ contract are the actual access controls.
10
37
 
11
- If DSH is behind Nginx, Caddy or another reverse proxy, forward `/vision-router-settings/*` to the same DSH origin in addition to the normal DSH routes. The UI detects a 404 on this channel and shows this requirement directly.
38
+ ## Sensitive information and remaining local capabilities
12
39
 
13
- **Reverse-proxy security:** Follow the [upstream DSH public deployment contract](https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/docs/user/guide/public-deployments.md): preserve the **browser-facing `Host`** on proxy requests; do **not** rewrite it to `localhost` or `127.0.0.1` when forwarding remote traffic to a loopback DSH listener. DSH Host/Origin checks and its signed browser session authenticate accepted requests, but do **not** attest that a user is physically local. Vision Router grants local-only diagnostics, permission changes and self-update tokens only to requests classified as local. It conservatively treats loopback TCP requests carrying `Forwarded`, `X-Forwarded-*`, `X-Real-IP`, `Via` or common client-IP proxy headers as **remote for local-only actions**, regardless of an apparent localhost `Host`.
40
+ Settings descriptions are requested from DSH with
41
+ `describe({ redactSecrets: true })`. The remote view additionally masks
42
+ secret-shaped properties and URL username/password and secret query parameters
43
+ (e.g., in a proxy URL). API-key environment names such as `apiKeyEnv` are
44
+ references, not actual credential values. A just-submitted secret-bearing field
45
+ may be echoed **only** in that caller's successful, exact-value write response
46
+ to support readback; subsequent reads remain redacted. If editing a URL
47
+ containing masked username/password or secret query parameters, re-enter
48
+ those values first: the server rejects saving a redaction placeholder rather
49
+ than silently replacing the real credential. Never treat the complete
50
+ settings view as a credential-export endpoint.
14
51
 
15
- **Limit:** Forwarding headers can be absent, stripped or forged; they are only negative evidence, **never positive proof of physical-local origin**. An untrusted proxy that rewrites the browser `Host` to localhost and strips all forwarding evidence is indistinguishable from a genuine local browser using the current DSH Host request contract. Do not expose such a topology. Restrict upstream listener access, preserve external `Host`, configure DSH `trustedHosts` explicitly, and keep local-only actions on a direct trusted loopback UI. The broader local-presence attestation gap remains tracked in [Issue #680](https://github.com/ysr666/dsh-vision-router/issues/680).
52
+ A full settings editor **does not** grant access to separate Host capabilities
53
+ such as reading/opening log files, plugin self-update, local connection probes,
54
+ local diagnostic mutation endpoints, local file access, or OS permission
55
+ prompts. Those routes retain independent server-side local-only restrictions.
56
+ The `/_dsh/vision-router/local-settings` compatibility endpoint is not an
57
+ alternate remote route and must never be forwarded for external use.
58
+
59
+ ## DSH transport compatibility and proxy security
60
+
61
+ Legacy DSH Connection RPC requires the explicit
62
+ `{ authority: 'trusted-host' }` registration option; modern DSH uses
63
+ `connection.requestRejection()` and Host-owned BrowserAuth/Origin checks with
64
+ a two-argument `rpc.handle()`. DVR feature-detects this semantic contract.
65
+ Neither case exposes unauthenticated remote configuration.
66
+
67
+ If using Nginx/Caddy, forward `/vision-router-settings/*` to the same DSH origin
68
+ as the rest of the app. A 404 on this channel means the proxy or plugin runtime
69
+ has not registered/forwarded that route, **not** that the risk prompt needs to be
70
+ clicked again.
71
+
72
+ Follow the [official DSH reverse proxy deployment contract](https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/docs/user/guide/public-deployments.md):
73
+ preserve the browser-facing `Host`, explicitly configure trusted hosts, and
74
+ use HTTPS. The Host's signed browser session authenticates accepted requests
75
+ but cannot prove a user is physically present at the machine. A reverse proxy
76
+ that changes the Host to localhost and removes all forwarding provenance can
77
+ defeat software-only local-presence inference; do not expose that topology.
78
+ See [Issue #680](https://github.com/ysr666/dsh-vision-router/issues/680).
79
+
80
+ ## Regression coverage
81
+
82
+ The settings contract tests cover both compatibility-wrapper load orders
83
+ (Issue #822), local ConfigEditor read/write/reconciliation, request-origin and
84
+ BrowserAuth rejection, remote permission-disabled and consented flows, live
85
+ permission revocation, full configuration admission, prototype/resource guards,
86
+ secret redaction, and independent local-only system operations.
87
+
88
+ Historical release and architecture notes describing a remote field allow-list
89
+ document the behavior **at the time of those releases**; this document describes
90
+ the updated behavior after the unified-settings change.
package/index.js CHANGED
@@ -315,10 +315,10 @@ export const Config = z.object({
315
315
  ocrEngine: z.union(['auto', 'tesseract', 'vision']).default('auto'),
316
316
  proxy: z.string().default(''),
317
317
  proxyHosts: z.array(z.string()).default([...DEFAULT_PROXY_HOSTS]),
318
- // Remote browsers are intentionally unable to use DSH's broad settings.*
319
- // plane. This narrow Vision Router bridge is opt-in and still uses DSH's
320
- // trusted-host transport fence. Only a loopback/local settings page may
321
- // change this permission; the remote bridge rejects writes to the field.
318
+ // DSH versions expose different browser Settings transports. DVR's remote
319
+ // RPC is opt-in, but once acknowledged it edits the same Host-owned config
320
+ // namespace and schema as the local browser. The permission itself is
321
+ // managed by risk confirmation or local revocation, not ordinary remote writes.
322
322
  allowRemoteSettings: z.boolean().default(false),
323
323
  // Privacy policy switch: when enabled, Vision Router executes image-model
324
324
  // requests only against loopback visual endpoints (Ollama, LM Studio, or
@@ -4720,8 +4720,8 @@ ctx.logger?.info(
4720
4720
  deepToolDefs.push({
4721
4721
  name: 'vision_trace',
4722
4722
  description:
4723
- 'Vectorize an image (icon/logo) into an SVG via a local potrace pipeline (no Python). ' +
4724
- 'Default: COLOR-preserving vectorization — one path per dominant color with fill="#rrggbb". ' +
4723
+ 'Vectorize an image (icon/logo) into an SVG via a local VTracer/WASM worker (no Python). ' +
4724
+ 'Default: color-preserving vectorization with a limited color palette. ' +
4725
4725
  'Set color=false for the layered grayscale posterization, where `steps` (1-16, default 4) ' +
4726
4726
  'controls levels. Writes the SVG as an artifact.',
4727
4727
  parameters: {
@@ -4761,16 +4761,21 @@ ctx.logger?.info(
4761
4761
  const colors = Number.isInteger(args.colors) && args.colors > 0 ? Math.min(args.colors, 16) : 8
4762
4762
  const raw = await sharp(traceBytes, { failOn: 'none' }).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
4763
4763
  throwIfVisionTaskAborted(taskSignal)
4764
- const palette = quantizeColors(raw.data, colors)
4765
- colorCount = palette.length
4766
- svg = await posterizeSvgColor(raw.data, raw.info, palette, timeoutMs(), { signal: taskSignal })
4764
+ // User-facing colors is a strict maximum, not an exact
4765
+ // palette. VTracer chooses the colors for better gradient/alpha
4766
+ // fidelity; explicit palette callers use the separate array form.
4767
+ svg = await posterizeSvgColor(raw.data, raw.info, colors, timeoutMs(), { signal: taskSignal })
4768
+ colorCount = Math.min(colors, new Set(
4769
+ [...svg.matchAll(/<path\b[^>]*\bfill="(#[0-9a-fA-F]{6})"/g)]
4770
+ .map((match) => match[1].toLowerCase()),
4771
+ ).size)
4767
4772
  } else {
4768
4773
  svg = await posterizeSvg(traceBytes, steps, 'dominant', timeoutMs(), { signal: taskSignal })
4769
4774
  }
4770
4775
  } catch (error) {
4771
4776
  throwIfVisionTaskAborted(taskSignal, error)
4772
4777
  throw new Error(
4773
- `vision_trace: potrace failed (${error && error.message ? error.message : String(error)})`,
4778
+ `vision_trace: vectorization failed (${error && error.message ? error.message : String(error)})`,
4774
4779
  )
4775
4780
  }
4776
4781
  throwIfVisionTaskAborted(taskSignal)
package/lib/client.js CHANGED
@@ -199,7 +199,7 @@ openLogFolder,
199
199
  remoteSettingsInitializingTitle: '远程设置正在初始化',
200
200
  remoteSettingsInitializingBody: 'Vision Router 设置命名空间尚未就绪,页面会自动重试。',
201
201
  remoteSettingsProxyBody: '远程设置路由返回 404。若使用 Nginx/Caddy/其他反向代理,请同时转发 /vision-router-settings/* 到 DSH。',
202
- remoteSafeScopeHint: '远程页面只允许修改低风险偏好;网络、凭据、本地后端、产物目录、桌面截图和宿主路由等设置只能在 DSH 本机修改。',
202
+ remoteSafeScopeHint: '远程页面已启用完整配置,设置仍由 DSH Host 校验和持久保存。',
203
203
  settingsConflict: '设置已被另一端修改。已刷新最新配置,请确认你的修改后重新保存。',
204
204
  overridden: '已覆盖',
205
205
  reset: '恢复默认',
@@ -312,7 +312,7 @@ openLogFolder,
312
312
  proxyLabel: '视觉专用代理覆盖',
313
313
  proxyHint: '留空即沿用 DSH/Host 网络路径。仅需单独覆盖视觉请求时填写,如 http://127.0.0.1:10808 或 socks5://127.0.0.1:10808;兼容旧配置 socks5h://。修改即时生效。',
314
314
  allowRemoteSettingsLabel: '允许可信 Host 远程修改设置',
315
- allowRemoteSettingsHint: '默认关闭。仅在你信任能访问该 DSH 实例的客户端时开启;trustedHosts 不是身份认证。远程端仅能修改明确列入白名单的低风险偏好,网络、凭据、本地后端、产物目录、桌面截图和宿主路由始终只能在本机修改。',
315
+ allowRemoteSettingsHint: '默认关闭。仅在你信任能访问该 DSH 实例的客户端时开启;trustedHosts 不是身份认证。首次确认后,经过 DSH 认证的远程浏览器也可修改完整的 Vision Router 配置;已保存的凭据不会以明文回显。',
316
316
  proxyHostsLabel: '视觉代理覆盖域名(每行一个)',
317
317
  proxyHostsHint: '仅在上方填写视觉专用代理时生效;这些域名使用插件覆盖,其余请求继续沿用 DSH/Host 网络路径。留空清除覆盖。',
318
318
  saveFailed: '保存失败:部分配置未写入。未写入的修改已保留,请重试。',
@@ -485,7 +485,7 @@ openLogFolder,
485
485
  remoteSettingsInitializingTitle: 'Remote settings are initializing',
486
486
  remoteSettingsInitializingBody: 'The Vision Router settings namespace is not ready yet. This page will retry automatically.',
487
487
  remoteSettingsProxyBody: 'The remote-settings route returned 404. If DSH is behind Nginx, Caddy, or another reverse proxy, also forward /vision-router-settings/* to DSH.',
488
- remoteSafeScopeHint: 'Remote pages can change low-risk preferences only. Network, credentials, local backends, artifact paths, desktop capture, and host routing remain loopback-only.',
488
+ remoteSafeScopeHint: 'Remote settings are enabled for this authenticated DSH browser. Changes use the same Host settings schema and persistence as local settings.',
489
489
  settingsConflict: 'Settings changed on another client. The latest values were refreshed; review your draft and save again.',
490
490
  overridden: 'Overridden',
491
491
  reset: 'Reset',
@@ -598,7 +598,7 @@ openLogFolder,
598
598
  proxyLabel: 'Vision-only proxy override',
599
599
  proxyHint: 'Leave empty to follow the DSH/Host network path. Set only to override vision requests, e.g. http://127.0.0.1:10808 or socks5://127.0.0.1:10808; legacy socks5h:// values are supported. Applies immediately.',
600
600
  allowRemoteSettingsLabel: 'Allow trusted-host remote settings',
601
- allowRemoteSettingsHint: 'Off by default. Enable only when you trust clients that can reach this DSH instance; trustedHosts is not authentication. Remote clients can change only explicitly allow-listed low-risk preferences; network, credentials, local backends, artifact paths, desktop capture, and host routing remain loopback-only.',
601
+ allowRemoteSettingsHint: 'Off by default. Enable only when you trust clients that can reach this DSH instance; trustedHosts is not authentication. After a one-time confirmation, DSH-authenticated remote browsers can edit the full Vision Router configuration; stored credentials are not echoed as plaintext.',
602
602
  proxyHostsLabel: 'Vision proxy override hosts (one per line)',
603
603
  proxyHostsHint: 'Used only when the vision-only proxy override above is set. These hosts use the plugin override; all other requests keep the DSH/Host network path. Empty clears the override.',
604
604
  saveFailed: 'Save failed: some changes were not written. Unwritten changes were kept; please retry.',
@@ -4234,7 +4234,7 @@ openLogFolder,
4234
4234
  depthCapField(),
4235
4235
  // Local vision is a primary capability. Keep the heavy editors
4236
4236
  // collapsed by default, but make the entry obvious at a glance.
4237
- !remoteMode ? h('div', {
4237
+ h('div', {
4238
4238
  className: 'vr-group vr-local-group' + (showLocalVision ? ' vr-local-group-open' : ''),
4239
4239
  },
4240
4240
  h('button', {
@@ -4253,8 +4253,8 @@ openLogFolder,
4253
4253
  localLmStudioEditor(),
4254
4254
  )
4255
4255
  : null,
4256
- ) : null,
4257
- !remoteMode ? toggleField('desktopScreenshot') : null,
4256
+ ),
4257
+ toggleField('desktopScreenshot'),
4258
4258
  h('p', { className: 'vr-hint' }, t('defaultChainNote')),
4259
4259
  visionCaps.status === 'loading'
4260
4260
  ? h('p', { className: 'vr-hint' }, t('visionCapsLoading'))
@@ -4335,18 +4335,18 @@ openLogFolder,
4335
4335
  h('p', { className: 'vr-group-title' }, t('groupCost')),
4336
4336
  COST_TOGGLE_KEYS.map((key) => toggleField(key)),
4337
4337
  ),
4338
- !remoteMode ? h('div', { className: 'vr-group' },
4338
+ h('div', { className: 'vr-group' },
4339
4339
  h('p', { className: 'vr-group-title' }, t('groupNetwork')),
4340
4340
  h('p', { className: 'vr-hint' }, t('networkAuthorityHint')),
4341
- toggleField('allowRemoteSettings'),
4341
+ !remoteMode ? toggleField('allowRemoteSettings') : null,
4342
4342
  textField('proxy', t('proxyLabel'), t('proxyHint'), false),
4343
4343
  textField('proxyHosts', t('proxyHostsLabel'), t('proxyHostsHint'), true),
4344
- ) : null,
4344
+ ),
4345
4345
  h('div', { className: 'vr-group' },
4346
4346
  h('p', { className: 'vr-group-title' }, t('groupDeveloper')),
4347
4347
  h('p', { className: 'vr-hint' }, t('developerHint')),
4348
- !remoteMode ? DEVELOPER_TOGGLE_KEYS.map((key) => toggleField(key)) : null,
4349
- !remoteMode ? stealthNotice() : null,
4348
+ DEVELOPER_TOGGLE_KEYS.map((key) => toggleField(key)),
4349
+ stealthNotice(),
4350
4350
  h('p', { className: 'vr-group-title' }, t('groupWrappers')),
4351
4351
  catalogReady
4352
4352
  ? wrappersEditor()
@@ -4356,7 +4356,7 @@ openLogFolder,
4356
4356
  ? extraVisionModelsEditor()
4357
4357
  : textField('extraVisionModels', t('extraVisionModelsLabel'), t('extraVisionModelsHint'), true),
4358
4358
  h('p', { className: 'vr-group-title' }, t('groupRoutes')),
4359
- !remoteMode ? TEXT_KEYS.map((key) => textField(key, t(LABEL_KEY[key]), t(HINT_KEY[key]), false)) : null,
4359
+ TEXT_KEYS.map((key) => textField(key, t(LABEL_KEY[key]), t(HINT_KEY[key]), false)),
4360
4360
  ),
4361
4361
  )
4362
4362
  : null,
@@ -1191,215 +1191,97 @@ function isVisionAbort(error, signal) {
1191
1191
  return signal?.aborted === true || error?.name === 'AbortError' || error?.code === 'ABORT_ERR'
1192
1192
  }
1193
1193
 
1194
- /** Vectorize an image buffer into an SVG string via potrace posterization. */
1195
- export function posterizeSvg(bytes, steps = 4, fillStrategy = 'dominant', timeoutMs = 60000, options = {}) {
1196
- // potrace is CPU-bound and runs its computation in long synchronous
1197
- // chunks: on the main thread it blocks the whole dsh process (other
1198
- // sessions time out) and a setTimeout-based timeout can NEVER fire while
1199
- // the loop is blocked. Run it in a worker thread instead — the main loop
1200
- // stays responsive, and a timeout hard-terminates the worker.
1201
- const signal = options?.signal
1194
+ /** Shared hard-timeout and cancellation boundary for local VTracer SVG workers. */
1195
+ function runTraceWorker(mode, payload, timeoutMs, signal) {
1196
+ const aborted = () => visionAbortReason(signal, 'vector trace aborted')
1197
+ if (signal?.aborted) return Promise.reject(aborted())
1202
1198
  return new Promise((resolve, reject) => {
1203
- let settled = false
1204
1199
  let worker
1205
1200
  let timer
1206
- let abortListener
1201
+ let finished = false
1207
1202
  const finish = (error, svg) => {
1208
- if (settled) return
1209
- settled = true
1203
+ if (finished) return
1204
+ finished = true
1210
1205
  if (timer !== undefined) clearTimeout(timer)
1211
- if (signal && abortListener) signal.removeEventListener?.('abort', abortListener)
1212
- void worker?.terminate()
1206
+ signal?.removeEventListener?.('abort', onAbort)
1207
+ if (worker) void worker.terminate().catch(() => {})
1213
1208
  if (error) reject(error)
1214
1209
  else resolve(svg)
1215
1210
  }
1216
- abortListener = () => finish(visionAbortReason(signal, 'potrace aborted'))
1217
- if (signal?.aborted) {
1218
- finish(visionAbortReason(signal, 'potrace aborted'))
1211
+ const onAbort = () => finish(aborted())
1212
+ signal?.addEventListener?.('abort', onAbort, { once: true })
1213
+ if (signal?.aborted) { finish(aborted()); return }
1214
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
1215
+ finish(new Error('vector trace timed out'))
1219
1216
  return
1220
1217
  }
1221
- signal?.addEventListener?.('abort', abortListener, { once: true })
1222
- timer = setTimeout(() => {
1223
- finish(
1224
- new Error(
1225
- 'potrace timed out — the image is too large or too complex; crop it to the target region first',
1226
- ),
1227
- )
1228
- }, timeoutMs)
1218
+ timer = setTimeout(() => finish(new Error(
1219
+ 'vector trace timed out — crop the image or reduce its complexity',
1220
+ )), timeoutMs)
1229
1221
  try {
1230
- // Resolve potrace's entry to an absolute file URL the worker can import
1231
- // regardless of the dsh process cwd or the worker's module mode.
1232
- const potraceUrl = pathToFileURL(createRequire(import.meta.url).resolve('potrace')).href
1233
- const source = `
1234
- import('node:worker_threads').then(({ parentPort, workerData }) => {
1235
- import(workerData.potraceUrl).then((mod) => {
1236
- const potrace = mod.default ?? mod
1237
- potrace.posterize(Buffer.from(workerData.bytes), {
1238
- steps: workerData.steps,
1239
- fillStrategy: workerData.fillStrategy,
1240
- }, (error, svg) => {
1241
- parentPort.postMessage(error ? { error: String((error && error.message) || error) } : { svg })
1242
- })
1243
- }).catch((error) => {
1244
- parentPort.postMessage({ error: String((error && error.message) || error) })
1245
- })
1246
- })
1247
- `
1248
- worker = new Worker(source, {
1249
- eval: true,
1250
- workerData: { potraceUrl, bytes, steps, fillStrategy },
1222
+ // This file-backed runtime worker uses only published JavaScript and
1223
+ // absolute peer imports; it never needs Host CLI, eval, test or loader
1224
+ // flags. Inheriting them can fail or run unwanted diagnostic hooks.
1225
+ worker = new Worker(new URL('./trace-vtracer-worker.js', import.meta.url), {
1226
+ execArgv: [],
1227
+ workerData: { mode, ...payload },
1228
+ resourceLimits: { maxOldGenerationSizeMb: 192, maxYoungGenerationSizeMb: 32 },
1251
1229
  })
1252
1230
  worker.once('message', (message) => {
1253
- if (message && message.error) finish(new Error(message.error))
1254
- else finish(undefined, message && message.svg)
1231
+ if (message?.ok === true && typeof message.svg === 'string') finish(undefined, message.svg)
1232
+ else finish(new Error(String(message?.error || 'vector trace worker returned invalid output')))
1255
1233
  })
1256
1234
  worker.once('error', (error) => finish(error))
1257
1235
  worker.once('exit', (code) => {
1258
- if (code !== 0 && !settled) finish(new Error(`potrace worker exited with code ${code}`))
1236
+ if (!finished) finish(new Error('vector trace worker exited before producing SVG (code ' + code + ')'))
1259
1237
  })
1260
- } catch (error) {
1261
- finish(error)
1262
- }
1238
+ } catch (error) { finish(error) }
1263
1239
  })
1264
1240
  }
1265
1241
 
1242
+ /** Compatible export: grayscale trace in an isolated Worker with adaptive posterized levels. */
1243
+ export function posterizeSvg(bytes, steps = 4, fillStrategy = 'dominant', timeoutMs = 60000, options = {}) {
1244
+ if (options?.signal?.aborted) return Promise.reject(visionAbortReason(options.signal, 'vector trace aborted'))
1245
+ if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0 || bytes.byteLength > 32 * 1024 * 1024) {
1246
+ return Promise.reject(new RangeError('invalid trace image byte length'))
1247
+ }
1248
+ if (!Number.isInteger(steps) || steps < 1 || steps > 16) {
1249
+ return Promise.reject(new RangeError('trace steps must be an integer between 1 and 16'))
1250
+ }
1251
+ if (fillStrategy !== 'dominant') {
1252
+ return Promise.reject(new RangeError('unsupported grayscale fill strategy'))
1253
+ }
1254
+ const sharpUrl = pathToFileURL(createRequire(import.meta.url).resolve('sharp')).href
1255
+ return runTraceWorker('grayscale', { bytes: Buffer.from(bytes), steps, sharpUrl }, timeoutMs, options?.signal)
1256
+ }
1257
+
1266
1258
  /**
1267
- * Color-preserving vectorization: quantize the image into its top colors
1268
- * (the caller supplies the palette), build one 1-bit mask per color, trace
1269
- * each mask with potrace, and emit a real colored SVG — one <path> per color
1270
- * with fill="#rrggbb" — instead of potrace posterize's grayscale
1271
- * black + fill-opacity layers. Runs in a worker with the same hard timeout
1272
- * and termination semantics as posterizeSvg.
1273
- *
1274
- * @param data - raw RGBA pixel buffer the tool decoded (already downscaled
1275
- * to the trace budget).
1276
- * @param info - { width, height } of that buffer.
1277
- * @param palette - [{ hex, count, share }] from quantizeColors, ordered by
1278
- * share descending.
1259
+ * Local color SVG tracing.
1260
+ * An explicit palette array must be honored exactly (VTracer palette option);
1261
+ * an integer 1..16 requests automatic colors with that strict maximum.
1262
+ * The public vision_trace tool uses the integer form for higher visual fidelity.
1279
1263
  */
1280
- export function posterizeSvgColor(data, info, palette, timeoutMs = 60000, options = {}) {
1281
- const signal = options?.signal
1282
- return new Promise((resolve, reject) => {
1283
- let settled = false
1284
- let worker
1285
- let timer
1286
- let abortListener
1287
- const finish = (error, svg) => {
1288
- if (settled) return
1289
- settled = true
1290
- if (timer !== undefined) clearTimeout(timer)
1291
- if (signal && abortListener) signal.removeEventListener?.('abort', abortListener)
1292
- void worker?.terminate()
1293
- if (error) reject(error)
1294
- else resolve(svg)
1295
- }
1296
- abortListener = () => finish(visionAbortReason(signal, 'color trace aborted'))
1297
- if (signal?.aborted) {
1298
- finish(visionAbortReason(signal, 'color trace aborted'))
1299
- return
1300
- }
1301
- signal?.addEventListener?.('abort', abortListener, { once: true })
1302
- timer = setTimeout(() => {
1303
- finish(
1304
- new Error(
1305
- 'color trace timed out — the image is too large or too complex; crop it to the target region first',
1306
- ),
1307
- )
1308
- }, timeoutMs)
1309
- try {
1310
- const sharpUrl = pathToFileURL(createRequire(import.meta.url).resolve('sharp')).href
1311
- const potraceUrl = pathToFileURL(createRequire(import.meta.url).resolve('potrace')).href
1312
- const source = `
1313
- import('node:worker_threads').then(({ parentPort, workerData }) => {
1314
- Promise.all([import(workerData.sharpUrl), import(workerData.potraceUrl)]).then(([sharpMod, potraceMod]) => {
1315
- const sharp = sharpMod.default ?? sharpMod
1316
- const potrace = potraceMod.default ?? potraceMod
1317
- const { width, height, palette } = workerData
1318
- const raw = Buffer.from(workerData.raw)
1319
- const hexRgb = (hex) => {
1320
- const n = parseInt(hex.slice(1), 16)
1321
- return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
1322
- }
1323
- const paletteRgb = palette.map((p) => hexRgb(p.hex))
1324
- const pixels = width * height
1325
- const masks = palette.map(() => Buffer.alloc(pixels))
1326
- for (let p = 0; p < pixels; p++) {
1327
- const o = p * 4
1328
- if (raw[o + 3] < 128) continue
1329
- let best = 0
1330
- let bestD = Infinity
1331
- for (let c = 0; c < paletteRgb.length; c++) {
1332
- const dr = raw[o] - paletteRgb[c][0]
1333
- const dg = raw[o + 1] - paletteRgb[c][1]
1334
- const db = raw[o + 2] - paletteRgb[c][2]
1335
- const d = dr * dr + dg * dg + db * db
1336
- if (d < bestD) { bestD = d; best = c }
1337
- }
1338
- masks[best][p] = 1
1339
- }
1340
- const paths = []
1341
- let pending = palette.length
1342
- const maybeDone = () => {
1343
- if (pending > 0) return
1344
- const pathSvg = paths.map((p) => '<path fill="' + p.hex + '" d="' + p.d + '"/>').join('')
1345
- parentPort.postMessage({
1346
- ok: true,
1347
- svg: '<svg xmlns="http://www.w3.org/2000/svg" width="' + width + '" height="' + height +
1348
- '" viewBox="0 0 ' + width + ' ' + height + '"><rect width="' + width + '" height="' + height +
1349
- '" fill="#ffffff"/>' + pathSvg + '</svg>',
1350
- })
1351
- }
1352
- if (pending === 0) { maybeDone(); return }
1353
- palette.forEach((entry, index) => {
1354
- const gray = Buffer.alloc(pixels)
1355
- const mask = masks[index]
1356
- for (let p = 0; p < pixels; p++) gray[p] = mask[p] ? 0 : 255
1357
- sharp(gray, { raw: { width, height, channels: 1 } })
1358
- .png()
1359
- .toBuffer()
1360
- .then((pngBuf) => {
1361
- potrace.trace(pngBuf, (err, svg) => {
1362
- pending -= 1
1363
- if (!err && svg) {
1364
- const found = [...svg.matchAll(/d="([^"]+)"/g)].map((m) => m[1])
1365
- for (const d of found) paths.push({ hex: entry.hex, d })
1366
- }
1367
- maybeDone()
1368
- })
1369
- })
1370
- .catch(() => {
1371
- pending -= 1
1372
- maybeDone()
1373
- })
1374
- })
1375
- }).catch((error) => {
1376
- parentPort.postMessage({ error: String((error && error.message) || error) })
1377
- })
1378
- })
1379
- `
1380
- worker = new Worker(source, {
1381
- eval: true,
1382
- workerData: {
1383
- sharpUrl,
1384
- potraceUrl,
1385
- width: info.width,
1386
- height: info.height,
1387
- palette,
1388
- raw: data,
1389
- },
1390
- })
1391
- worker.once('message', (message) => {
1392
- if (message && message.error) finish(new Error(message.error))
1393
- else finish(undefined, message && message.svg)
1394
- })
1395
- worker.once('error', (error) => finish(error))
1396
- worker.once('exit', (code) => {
1397
- if (code !== 0 && !settled) finish(new Error(`color-trace worker exited with code ${code}`))
1398
- })
1399
- } catch (error) {
1400
- finish(error)
1401
- }
1402
- })
1264
+ export function posterizeSvgColor(data, info, paletteOrColors, timeoutMs = 60000, options = {}) {
1265
+ if (options?.signal?.aborted) return Promise.reject(visionAbortReason(options.signal, 'color trace aborted'))
1266
+ const width = info?.width
1267
+ const height = info?.height
1268
+ if (
1269
+ !Number.isSafeInteger(width) || !Number.isSafeInteger(height) ||
1270
+ width < 1 || height < 1 || width * height > 1_000_000 ||
1271
+ !(data instanceof Uint8Array) || data.byteLength !== width * height * 4
1272
+ ) return Promise.reject(new RangeError('invalid color trace RGBA dimensions'))
1273
+ const explicit = Array.isArray(paletteOrColors)
1274
+ if (explicit
1275
+ ? (paletteOrColors.length > 16 || paletteOrColors.some((p) =>
1276
+ !p || typeof p.hex !== 'string' || !/^#[a-f0-9]{6}$/i.test(p.hex)))
1277
+ : (!Number.isInteger(paletteOrColors) || paletteOrColors < 1 || paletteOrColors > 16)
1278
+ ) return Promise.reject(new RangeError('invalid trace color palette or color limit'))
1279
+ return runTraceWorker('color', {
1280
+ data: Buffer.from(data), width, height,
1281
+ ...(explicit
1282
+ ? { palette: paletteOrColors.map((p) => ({ hex: p.hex.toLowerCase() })) }
1283
+ : { colors: paletteOrColors }),
1284
+ }, timeoutMs, options?.signal)
1403
1285
  }
1404
1286
 
1405
1287
  /** Resolve the effective vision_ocr engine without hiding explicit user/model intent. */