dsh-vision-router 3.2.0 → 3.3.0

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.
Files changed (56) hide show
  1. package/README.md +6 -6
  2. package/README.zh.md +21 -6
  3. package/THIRD_PARTY_NOTICES.md +167 -0
  4. package/assets/licenses/apache-2.0.txt +202 -0
  5. package/assets/licenses/llvm-mingw-LICENSE.txt +279 -0
  6. package/assets/licenses/mingw-w64-runtime-COPYING.txt +265 -0
  7. package/assets/licenses/moxcms-BSD-3-Clause.txt +26 -0
  8. package/assets/licenses/ncnn-LICENSE.txt +86 -0
  9. package/assets/licenses/roots-BSD-2-Clause.txt +24 -0
  10. package/assets/licenses/unicode-ident-Unicode-3.0.txt +39 -0
  11. package/assets/licenses/vtracer-MIT.txt +25 -0
  12. package/assets/licenses/zlib-rs-Zlib.txt +19 -0
  13. package/docs/architecture/dsh-support-window.md +25 -6
  14. package/docs/compatibility/dsh-0.2.2-rc2-audit.md +40 -0
  15. package/docs/compatibility/dsh-0.2.2-rc3-audit.md +131 -0
  16. package/docs/compliance/vtracer-alpha4-provenance.md +47 -0
  17. package/docs/compliance/vtracer-alpha4-reconstructed-Cargo.lock +567 -0
  18. package/docs/compliance/vtracer-alpha4-rust-inventory.json +421 -0
  19. package/docs/compliance/vtracer-alpha4-rust-license-texts.md +13018 -0
  20. package/docs/releases/v3.2.1.md +21 -0
  21. package/docs/releases/v3.2.2.md +25 -0
  22. package/docs/releases/v3.3.0.md +34 -0
  23. package/docs/remote-settings.md +83 -8
  24. package/index.js +280 -169
  25. package/lib/client.js +17 -17
  26. package/lib/core-primitives.js +155 -214
  27. package/lib/dsh-support-window.js +6 -3
  28. package/lib/native-ocr-annotation-risk.js +33 -0
  29. package/lib/native-ocr-canary.js +156 -0
  30. package/lib/native-ocr-chemistry-review.js +37 -0
  31. package/lib/native-ocr-document.js +243 -0
  32. package/lib/native-ocr-installation.js +17 -0
  33. package/lib/native-ocr-integrity.js +93 -0
  34. package/lib/native-ocr-question-labels.js +167 -0
  35. package/lib/native-ocr-supervisor.js +268 -0
  36. package/lib/remote-settings-bridge.js +93 -57
  37. package/lib/remote-settings-risk-client-boundary.js +2 -2
  38. package/lib/runtime-reliability.js +7 -0
  39. package/lib/session-query-readers.js +8 -2
  40. package/lib/session-vision-attachment-index.js +61 -14
  41. package/lib/settings-client-017-compat.js +4 -2
  42. package/lib/settings-ia-client-prelude.js +26 -10
  43. package/lib/tesseract-image-preprocess.js +35 -0
  44. package/lib/trace-vtracer-process-runtime.js +133 -0
  45. package/lib/trace-vtracer-process.js +43 -0
  46. package/lib/trace-vtracer-worker.js +163 -0
  47. package/lib/vision-attachment-handle-runtime.js +11 -2
  48. package/lib/vision-backend-runtime-policy.js +5 -3
  49. package/lib/vision-image-input-reader.js +67 -0
  50. package/lib/vision-image-input-verdict.js +24 -3
  51. package/lib/vision-tool-runtime-boundary.js +7 -10
  52. package/lib/vision-tool-stage.js +58 -0
  53. package/lib/web/dsh-settings-017-root-transport.js +52 -6
  54. package/lib/web-capability-boundary.js +6 -0
  55. package/package.json +10 -6
  56. package/scripts/install-native-ocr.mjs +144 -0
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: '保存失败:部分配置未写入。未写入的修改已保留,请重试。',
@@ -394,8 +394,8 @@ openLogFolder,
394
394
  numVisionTaskTimeoutMs: '识图任务最长时间(毫秒)',
395
395
  numOcrTimeoutMs: 'OCR 最长时间(毫秒)',
396
396
  selectOcrEngine: 'OCR 默认引擎',
397
- hintOcrEngine: '决定 vision_ocr 未显式指定 engine 时的默认策略。自动:先本地 Tesseract,失败/空结果再用视觉模型;Tesseract:只用本地 OCR;视觉模型:直接跳过 Tesseract。单次工具调用显式 engine=tesseract/vision 始终优先。',
398
- ocrEngineAuto: '自动(Tesseract → 视觉模型)',
397
+ hintOcrEngine: '决定 vision_ocr 未显式指定 engine 时的默认策略。自动:优先已安装并校验的 PP-OCRv6(Mac ARM64 / Windows x64),否则使用本地 Tesseract,失败/空结果再用视觉模型;Tesseract:只用本地 OCR;视觉模型:直接跳过 Tesseract。单次工具调用显式 engine=tesseract/vision 始终优先。',
398
+ ocrEngineAuto: '自动(PP-OCRv6 → Tesseract → 视觉模型)',
399
399
  ocrEngineTesseract: '仅 Tesseract',
400
400
  ocrEngineVision: '仅视觉模型',
401
401
  numDownscaleMaxPixels: '图片像素上限',
@@ -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.',
@@ -682,8 +682,8 @@ openLogFolder,
682
682
  numVisionTaskTimeoutMs: 'Vision task maximum time (ms)',
683
683
  numOcrTimeoutMs: 'OCR maximum time (ms)',
684
684
  selectOcrEngine: 'Default OCR engine',
685
- hintOcrEngine: 'Default policy when vision_ocr does not explicitly choose an engine. Auto tries local Tesseract first and falls back to the vision model; Tesseract uses local OCR only; Vision skips Tesseract. An explicit engine=tesseract/vision on a tool call always wins.',
686
- ocrEngineAuto: 'Auto (Tesseract → vision)',
685
+ hintOcrEngine: 'Default policy when vision_ocr does not explicitly choose an engine. Auto prefers verified locally installed PP-OCRv6 (macOS ARM64 / Windows x64), otherwise local Tesseract; falls back to the vision model; Tesseract uses local OCR only; Vision skips Tesseract. An explicit engine=tesseract/vision on a tool call always wins.',
686
+ ocrEngineAuto: 'Auto (PP-OCRv6 → Tesseract → vision)',
687
687
  ocrEngineTesseract: 'Tesseract only',
688
688
  ocrEngineVision: 'Vision model only',
689
689
  numDownscaleMaxPixels: 'Image pixel limit',
@@ -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,
@@ -4,11 +4,10 @@ import path from 'node:path'
4
4
 
5
5
  import { existsSync } from 'node:fs'
6
6
  import { execFile } from 'node:child_process'
7
- import { Worker } from 'node:worker_threads'
8
7
  import { createRequire } from 'node:module'
9
8
  import { pathToFileURL } from 'node:url'
10
- import { promisify } from 'node:util'
11
9
  import { fetchWithOpenAICompatibility } from './http-compat.js'
10
+ import { runIsolatedTraceProcess } from './trace-vtracer-process-runtime.js'
12
11
  import {
13
12
  directSessionAffinityHeaders,
14
13
  rawSessionIdentity,
@@ -652,7 +651,7 @@ export function cacheKeyFor({ pairs, httpProviders, contentIds, wantJson, questi
652
651
  ]
653
652
  const payload = JSON.stringify({
654
653
  chains,
655
- contentIds: [...(contentIds ?? [])].sort(),
654
+ contentIds: [...(contentIds ?? [])],
656
655
  mode: wantJson ? 'json' : 'text',
657
656
  question: String(question ?? ''),
658
657
  })
@@ -1191,227 +1190,149 @@ function isVisionAbort(error, signal) {
1191
1190
  return signal?.aborted === true || error?.name === 'AbortError' || error?.code === 'ABORT_ERR'
1192
1191
  }
1193
1192
 
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
1202
- return new Promise((resolve, reject) => {
1203
- let settled = false
1204
- let worker
1205
- let timer
1206
- let abortListener
1207
- const finish = (error, svg) => {
1208
- if (settled) return
1209
- settled = true
1210
- if (timer !== undefined) clearTimeout(timer)
1211
- if (signal && abortListener) signal.removeEventListener?.('abort', abortListener)
1212
- void worker?.terminate()
1213
- if (error) reject(error)
1214
- else resolve(svg)
1215
- }
1216
- abortListener = () => finish(visionAbortReason(signal, 'potrace aborted'))
1217
- if (signal?.aborted) {
1218
- finish(visionAbortReason(signal, 'potrace aborted'))
1219
- return
1220
- }
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)
1229
- 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 },
1251
- })
1252
- worker.once('message', (message) => {
1253
- if (message && message.error) finish(new Error(message.error))
1254
- else finish(undefined, message && message.svg)
1255
- })
1256
- worker.once('error', (error) => finish(error))
1257
- worker.once('exit', (code) => {
1258
- if (code !== 0 && !settled) finish(new Error(`potrace worker exited with code ${code}`))
1259
- })
1260
- } catch (error) {
1261
- finish(error)
1262
- }
1193
+ /** Shared deadline and cancellation wrapper around the isolated trace subprocess. */
1194
+ function runTraceWorker(mode, payload, timeoutMs, signal) {
1195
+ return runIsolatedTraceProcess({
1196
+ mode, payload, timeoutMs, signal,
1197
+ abortReason: () => visionAbortReason(signal, 'vector trace aborted'),
1263
1198
  })
1264
1199
  }
1265
1200
 
1201
+ /** Compatible export: grayscale trace in an isolated Worker with adaptive posterized levels. */
1202
+ export function posterizeSvg(bytes, steps = 4, fillStrategy = 'dominant', timeoutMs = 60000, options = {}) {
1203
+ if (options?.signal?.aborted) return Promise.reject(visionAbortReason(options.signal, 'vector trace aborted'))
1204
+ if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0 || bytes.byteLength > 32 * 1024 * 1024) {
1205
+ return Promise.reject(new RangeError('invalid trace image byte length'))
1206
+ }
1207
+ if (!Number.isInteger(steps) || steps < 1 || steps > 16) {
1208
+ return Promise.reject(new RangeError('trace steps must be an integer between 1 and 16'))
1209
+ }
1210
+ if (fillStrategy !== 'dominant') {
1211
+ return Promise.reject(new RangeError('unsupported grayscale fill strategy'))
1212
+ }
1213
+ const sharpUrl = pathToFileURL(createRequire(import.meta.url).resolve('sharp')).href
1214
+ return runTraceWorker('grayscale', { bytes: Buffer.from(bytes), steps, sharpUrl }, timeoutMs, options?.signal)
1215
+ }
1216
+
1266
1217
  /**
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.
1218
+ * Local color SVG tracing.
1219
+ * An explicit palette array must be honored exactly (VTracer palette option);
1220
+ * an integer 1..16 requests automatic colors with that strict maximum.
1221
+ * The public vision_trace tool uses the integer form for higher visual fidelity.
1222
+ */
1223
+ export function posterizeSvgColor(data, info, paletteOrColors, timeoutMs = 60000, options = {}) {
1224
+ if (options?.signal?.aborted) return Promise.reject(visionAbortReason(options.signal, 'color trace aborted'))
1225
+ const width = info?.width
1226
+ const height = info?.height
1227
+ if (
1228
+ !Number.isSafeInteger(width) || !Number.isSafeInteger(height) ||
1229
+ width < 1 || height < 1 || width * height > 1_000_000 ||
1230
+ !(data instanceof Uint8Array) || data.byteLength !== width * height * 4
1231
+ ) return Promise.reject(new RangeError('invalid color trace RGBA dimensions'))
1232
+ const explicit = Array.isArray(paletteOrColors)
1233
+ if (explicit
1234
+ ? (paletteOrColors.length > 16 || paletteOrColors.some((p) =>
1235
+ !p || typeof p.hex !== 'string' || !/^#[a-f0-9]{6}$/i.test(p.hex)))
1236
+ : (!Number.isInteger(paletteOrColors) || paletteOrColors < 1 || paletteOrColors > 16)
1237
+ ) return Promise.reject(new RangeError('invalid trace color palette or color limit'))
1238
+ return runTraceWorker('color', {
1239
+ data: Buffer.from(data), width, height,
1240
+ ...(explicit
1241
+ ? { palette: paletteOrColors.map((p) => ({ hex: p.hex.toLowerCase() })) }
1242
+ : { colors: paletteOrColors }),
1243
+ }, timeoutMs, options?.signal)
1244
+ }
1245
+
1246
+ /** Resolve the effective vision_ocr engine without hiding explicit user/model intent. */
1247
+ export function resolveVisionOcrEngine(requestedEngine, configuredEngine = 'auto') {
1248
+ if (requestedEngine === 'tesseract' || requestedEngine === 'vision') return requestedEngine
1249
+ if (configuredEngine === 'tesseract' || configuredEngine === 'vision') return configuredEngine
1250
+ return 'auto'
1251
+ }
1252
+
1253
+ /** Node's asynchronous execFile does not support an \`input\` option.
1254
+ * Explicitly stream bounded image bytes to the subprocess's stdin.
1255
+ * The callback still owns timeout, AbortSignal, output cap and exit status.
1279
1256
  */
1280
- export function posterizeSvgColor(data, info, palette, timeoutMs = 60000, options = {}) {
1281
- const signal = options?.signal
1257
+ export function execFileWithStdin(file, args, { input, ...options } = {}) {
1258
+ if (!(input instanceof Uint8Array)) {
1259
+ return Promise.reject(new TypeError('subprocess input must be a byte array'))
1260
+ }
1282
1261
  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'))
1262
+ let inputError
1263
+ const child = execFile(file, args, { encoding: 'utf8', ...options }, (error, stdout, stderr) => {
1264
+ if (error || inputError) reject(error ?? inputError)
1265
+ else resolve({ stdout, stderr })
1266
+ })
1267
+ if (!child.stdin) {
1268
+ child.kill()
1269
+ reject(new Error('subprocess stdin unavailable'))
1299
1270
  return
1300
1271
  }
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)
1272
+ child.stdin.on('error', error => {
1273
+ inputError = error
1274
+ if (child.exitCode === null) child.kill()
1275
+ })
1309
1276
  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
- })
1277
+ child.stdin.end(input)
1399
1278
  } catch (error) {
1400
- finish(error)
1279
+ inputError = error
1280
+ child.kill()
1401
1281
  }
1402
1282
  })
1403
1283
  }
1404
1284
 
1405
- /** Resolve the effective vision_ocr engine without hiding explicit user/model intent. */
1406
- export function resolveVisionOcrEngine(requestedEngine, configuredEngine = 'auto') {
1407
- if (requestedEngine === 'tesseract' || requestedEngine === 'vision') return requestedEngine
1408
- if (configuredEngine === 'tesseract' || configuredEngine === 'vision') return configuredEngine
1409
- return 'auto'
1285
+ /** Never spend a model call on uncertain local OCR when the caller explicitly
1286
+ * requested local-only text, a breaker is degraded, or the shared deadline is low.
1287
+ */
1288
+ export function shouldVerifyUncertainAutoOcr({
1289
+ engine, uncertain, localOnlyVision, degraded, remainingMs,
1290
+ } = {}) {
1291
+ return engine === 'auto' && uncertain === true &&
1292
+ localOnlyVision !== true && degraded !== true &&
1293
+ Number.isFinite(remainingMs) && remainingMs >= 1200
1294
+ }
1295
+
1296
+ /**
1297
+ * A nonempty, uncertain local transcript remains useful evidence. In auto
1298
+ * mode only, optionally verify it using the caller's existing vision route,
1299
+ * without discarding the local result if no trustworthy review is available.
1300
+ * The caller owns permission, breaker, deadline and abort enforcement.
1301
+ */
1302
+ export async function verifyUncertainAutoOcrResult(localResult, {
1303
+ engine = 'auto', localOnlyVision = false, degraded = false,
1304
+ remainingMs = 0, verifyVision, checkAbort,
1305
+ } = {}) {
1306
+ if (!shouldVerifyUncertainAutoOcr({
1307
+ engine, uncertain: localResult?.uncertain, localOnlyVision, degraded, remainingMs,
1308
+ }) || typeof verifyVision !== 'function') return localResult
1309
+
1310
+ let vision
1311
+ try {
1312
+ vision = await verifyVision()
1313
+ } catch (error) {
1314
+ checkAbort?.(error)
1315
+ return localResult
1316
+ }
1317
+ checkAbort?.()
1318
+ if (vision?.ok === false || typeof vision?.text !== 'string' ||
1319
+ vision.text.trim() === '') return localResult
1320
+ return {
1321
+ engine: 'vision',
1322
+ text: vision.text.trim(),
1323
+ review: {
1324
+ fallbackReason: 'low_confidence_local_ocr',
1325
+ localEngine: localResult.engine,
1326
+ localText: localResult.text.slice(0, 1000),
1327
+ ...(Number.isFinite(localResult.review?.quality)
1328
+ ? { localQuality: localResult.review.quality } : {}),
1329
+ },
1330
+ }
1410
1331
  }
1411
1332
 
1412
1333
  /** OCR image bytes with a local tesseract binary (chi_sim+eng) when available. */
1413
1334
  export async function ocrWithTesseract(bytes, timeoutMs = 60000, options = {}) {
1414
- const exec = typeof options.exec === 'function' ? options.exec : promisify(execFile)
1335
+ const exec = typeof options.exec === 'function' ? options.exec : execFileWithStdin
1415
1336
  const signal = options.signal
1416
1337
  throwIfVisionAborted(signal, 'tesseract OCR aborted')
1417
1338
  const { stdout } = await exec(
@@ -1428,7 +1349,7 @@ export async function ocrWithTesseract(bytes, timeoutMs = 60000, options = {}) {
1428
1349
  return String(stdout ?? '')
1429
1350
  }
1430
1351
 
1431
- const TESSERACT_OCR_PSMS = Object.freeze([6, 3, 11])
1352
+ const TESSERACT_OCR_PSMS = Object.freeze([6, 7, 3, 11])
1432
1353
  const TESSERACT_REVIEW_THRESHOLD = 70
1433
1354
  const TESSERACT_CANDIDATE_MARGIN = 5
1434
1355
  const TESSERACT_CONFUSABLE_RUN = /[0O1IlL]{3,}/
@@ -1487,7 +1408,7 @@ export function selectTesseractOcrCandidate(candidates) {
1487
1408
  }
1488
1409
 
1489
1410
  export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options = {}) {
1490
- const exec = typeof options.exec === 'function' ? options.exec : promisify(execFile)
1411
+ const exec = typeof options.exec === 'function' ? options.exec : execFileWithStdin
1491
1412
  const signal = options.signal
1492
1413
  const requestedBudget = Number(timeoutMs)
1493
1414
  const budgetMs = Number.isFinite(requestedBudget) && requestedBudget > 0
@@ -1496,27 +1417,27 @@ export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options
1496
1417
  const started = Date.now()
1497
1418
  const attemptedPsms = []
1498
1419
  const remaining = () => Math.max(1, budgetMs - (Date.now() - started))
1499
- const run = async (psm) => {
1420
+ const run = async (psm, inputBytes = bytes, variant = 'original') => {
1500
1421
  throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
1501
1422
  attemptedPsms.push(psm)
1502
1423
  const common = ['stdin', 'stdout', '-l', 'chi_sim+eng', '--psm', String(psm)]
1503
1424
  const execOptions = () => ({
1504
1425
  timeout: remaining(),
1505
1426
  maxBuffer: 32 * 1024 * 1024,
1506
- input: bytes,
1427
+ input: inputBytes,
1507
1428
  ...(signal === undefined ? {} : { signal }),
1508
1429
  })
1509
1430
  const { stdout: plain } = await exec('tesseract', common, execOptions())
1510
1431
  throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
1511
1432
  const text = String(plain ?? '').trim()
1512
- if (text === '') return assessTesseractOcr('', '', psm)
1433
+ if (text === '') return { ...assessTesseractOcr('', '', psm), variant }
1513
1434
  try {
1514
1435
  const { stdout: tsv } = await exec('tesseract', [...common, 'tsv'], execOptions())
1515
1436
  throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
1516
- return assessTesseractOcr(text, String(tsv ?? ''), psm)
1437
+ return { ...assessTesseractOcr(text, String(tsv ?? ''), psm), variant }
1517
1438
  } catch (error) {
1518
1439
  if (isVisionAbort(error, signal)) throw error
1519
- return { psm, text, words: 0, quality: 0, riskyTokens: [], uncertain: true }
1440
+ return { psm, text, words: 0, quality: 0, riskyTokens: [], uncertain: true, variant }
1520
1441
  }
1521
1442
  }
1522
1443
 
@@ -1533,7 +1454,27 @@ export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options
1533
1454
  // Keep the first successful local OCR result when an optional review pass fails.
1534
1455
  }
1535
1456
  }
1536
- const selected = selectTesseractOcrCandidate(candidates) ?? candidates[0]
1457
+ let selected = selectTesseractOcrCandidate(candidates) ?? candidates[0]
1458
+ // Last resort only. A damaged/low-confidence original can still contain
1459
+ // a legitimate single subtitle line; a bounded local crop may recover it.
1460
+ if (selected.uncertain && typeof options.preprocess === 'function' &&
1461
+ budgetMs - (Date.now() - started) >= 900) {
1462
+ try {
1463
+ const processed = await options.preprocess(bytes, {
1464
+ signal, remainingMs: Math.max(0, budgetMs - (Date.now() - started)),
1465
+ })
1466
+ throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
1467
+ if (processed?.bytes instanceof Uint8Array && processed.bytes.length > 0 &&
1468
+ processed.bytes.length <= 16 * 1024 * 1024 &&
1469
+ budgetMs - (Date.now() - started) >= 500) {
1470
+ const retry = await run(7, processed.bytes, processed.variant ?? 'preprocessed')
1471
+ selected = selectTesseractOcrCandidate([...candidates, retry]) ?? selected
1472
+ }
1473
+ } catch (error) {
1474
+ if (isVisionAbort(error, signal)) throw error
1475
+ // The original best candidate still wins when preprocessing is unavailable.
1476
+ }
1477
+ }
1537
1478
  return { ...selected, attemptedPsms }
1538
1479
  }
1539
1480
 
@@ -10,6 +10,8 @@ export const DSH_SUPPORT_WINDOW = Object.freeze({
10
10
  export const DSH_VERIFICATION_EVIDENCE = Object.freeze({
11
11
  exactFloor: '0.2.1-rc.5',
12
12
  exactRecommended: '0.2.2-rc.1',
13
+ // Qualified exact-host evidence is distinct from the recommended upgrade target.
14
+ exactVerified: Object.freeze(['0.2.1-rc.5', '0.2.2-rc.1', '0.2.2-rc.2', '0.2.2-rc.3']),
13
15
  stableCanaryDistTag: 'latest',
14
16
  nextCanaryDistTag: 'next',
15
17
  previewCanaryDistTag: 'alpha',
@@ -70,7 +72,7 @@ export function supportWindowUpgradeAdvice(capabilities = {}, {
70
72
  }
71
73
  // Admission is an open 0.2.x train on purpose, not blanket evidence.
72
74
  // A later Host or Node major is not automatically verified by the exact
73
- // rc5/rc1, Node 24.9/24.21 matrix; Doctor reports unknown, not green.
75
+ // pinned-release Node 24.9/24.21 matrix; Doctor reports unknown, not green.
74
76
  if (semver.major(node) !== 24) {
75
77
  return Object.freeze({
76
78
  level: 'unknown', code: 'NODE_FORWARD_MAJOR_UNVERIFIED',
@@ -78,10 +80,10 @@ export function supportWindowUpgradeAdvice(capabilities = {}, {
78
80
  })
79
81
  }
80
82
  const exactHost = semver.valid(String(hostVersion).replace(/^v/, ''))
81
- if (![DSH_VERIFICATION_EVIDENCE.exactFloor, DSH_VERIFICATION_EVIDENCE.exactRecommended].includes(exactHost)) {
83
+ if (!DSH_VERIFICATION_EVIDENCE.exactVerified.includes(exactHost)) {
82
84
  return Object.freeze({
83
85
  level: 'unknown', code: 'HOST_FORWARD_RELEASE_UNVERIFIED',
84
- message: `DSH ${hostVersion} meets the 0.2.x admission range but lacks the two pinned exact-release acceptance gates`,
86
+ message: `DSH ${hostVersion} meets the 0.2.x admission range but has no exact-release acceptance evidence`,
85
87
  })
86
88
  }
87
89
  return Object.freeze({
@@ -102,6 +104,7 @@ export function formatDshSupportWindowLines(capabilities = {}, options = {}) {
102
104
  'DSH compatibility verification evidence:',
103
105
  ` exact supported Host floor: ${DSH_VERIFICATION_EVIDENCE.exactFloor}`,
104
106
  ` exact recommended Host: ${DSH_VERIFICATION_EVIDENCE.exactRecommended}`,
107
+ ` verified exact Host releases: ${DSH_VERIFICATION_EVIDENCE.exactVerified.join(', ')}`,
105
108
  ` scheduled published canary: npm dist-tag ${DSH_VERIFICATION_EVIDENCE.stableCanaryDistTag}`,
106
109
  ` scheduled next/rc canary: npm dist-tag ${DSH_VERIFICATION_EVIDENCE.nextCanaryDistTag}`,
107
110
  ` scheduled alpha/pre-release canary: npm dist-tag ${DSH_VERIFICATION_EVIDENCE.previewCanaryDistTag}`,
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Optional visual-evidence flag for photographed pages with red pen annotations.
3
+ * This is NOT OCR: it never changes recognized text and never reconstructs
4
+ * hidden numeric dots or digits. Coordinates are from the same RGB source.
5
+ */
6
+ export function detectRedAnnotationNearText(rgb,width,height,box,{
7
+ scanWidth=165,redFractionThreshold=0.012,
8
+ }={}) {
9
+ if(!(rgb instanceof Uint8Array) ||
10
+ !Number.isSafeInteger(width) || !Number.isSafeInteger(height) ||
11
+ width<=0 || height<=0 || rgb.length!==width*height*3 ||
12
+ !Array.isArray(box) || box.length!==4 || !box.every(Number.isFinite)) {
13
+ return {detected:false,reason:'invalid_geometry'}
14
+ }
15
+ const x1=Math.max(0,Math.floor(box[0]))
16
+ const x2=Math.min(width,Math.ceil(box[2]),x1+scanWidth)
17
+ const y1=Math.max(0,Math.floor(box[1]))
18
+ const y2=Math.min(height,Math.ceil(box[3]))
19
+ if(x2<=x1 || y2<=y1)return {detected:false,reason:'empty_region'}
20
+ let colored=0,total=0
21
+ for(let y=y1;y<y2;y++){
22
+ for(let x=x1;x<x2;x++){
23
+ const at=(y*width+x)*3
24
+ const r=rgb[at],g=rgb[at+1],b=rgb[at+2]
25
+ if(r>80 && r-g>35 && r-b>46)colored++
26
+ total++
27
+ }
28
+ }
29
+ const fraction=colored/total
30
+ const detected=colored>=15 && fraction>=redFractionThreshold
31
+ return {detected,redPixelFraction:Math.round(fraction*10000)/10000,
32
+ redPixelCount:colored,scannedPixelCount:total}
33
+ }