feat(window-recognition): 窗口信号层（HWND解析/几何计算，注入式可测）

Author: Aparencia

client/electron/windowSignals.test.ts

@@ -0,0 +1,57 @@
+// @vitest-environment node
+/**
+ * 窗口信号层测试（注入式：native 数据由调用方传入，本模块不依赖 electron）
+ * @ai-context: 覆盖 HWND 解析、native 索引构建、几何信号计算、信号缺失降级。
+ */
+import { describe, it, expect } from 'vitest';
+import { parseHwndFromSourceId, buildNativeIndex, resolveGeometrySignals } from './windowSignals.js';
+
+describe('parseHwndFromSourceId', () => {
+  it('解析标准 desktopCapturer id', () => {
+    expect(parseHwndFromSourceId('window:123456:0')).toBe('123456');
+  });
+  it('非 window 前缀返回 null', () => {
+    expect(parseHwndFromSourceId('screen:0:0')).toBeNull();
+    expect(parseHwndFromSourceId('')).toBeNull();
+    expect(parseHwndFromSourceId(null as unknown as string)).toBeNull();
+  });
+  it('畸形 id 返回 null', () => {
+    expect(parseHwndFromSourceId('window:')).toBeNull();
+    expect(parseHwndFromSourceId('window:abc:0')).toBe('abc');
+  });
+});
+
+describe('buildNativeIndex', () => {
+  it('按 hwnd 字符串建索引', () => {
+    const idx = buildNativeIndex([
+      { hwnd: '111', processName: 'chrome.exe', width: 1280, height: 720, alwaysOnTop: false },
+    ]);
+    expect(idx.get('111')?.processName).toBe('chrome.exe');
+    expect(idx.size).toBe(1);
+  });
+  it('空输入返回空 Map', () => {
+    expect(buildNativeIndex([]).size).toBe(0);
+  });
+});
+
+describe('resolveGeometrySignals', () => {
+  it('计算宽高比与面积占比', () => {
+    const s = resolveGeometrySignals(
+      { hwnd: '1', processName: 'chrome.exe', width: 1280, height: 720, alwaysOnTop: true },
+      1920 * 1080,
+    );
+    expect(s.aspectRatio).toBeCloseTo(16 / 9, 5);
+    expect(s.areaRatio).toBeCloseTo(1280 * 720 / (1920 * 1080), 5);
+    expect(s.alwaysOnTop).toBe(true);
+  });
+  it('native 缺失（undefined）时返回空信号（降级）', () => {
+    expect(resolveGeometrySignals(undefined, 1920 * 1080)).toEqual({});
+  });
+  it('显示器面积为 0 时避免除零', () => {
+    const s = resolveGeometrySignals(
+      { hwnd: '1', processName: 'x.exe', width: 100, height: 100, alwaysOnTop: false },
+      0,
+    );
+    expect(s.areaRatio).toBeUndefined();
+  });
+});

client/electron/windowSignals.ts

@@ -0,0 +1,82 @@
+/**
+ * 窗口信号采集（注入式纯函数层）
+ *
+ * 将 desktopCapturer source id 与 native 窗口枚举（listAudioWindows）对齐，
+ * 产出评分所需的进程名/几何信号。native 数据由调用方（screenCaptureHandlers）
+ * 经 loadProcessAudioNative 获取后注入——本模块不依赖 electron，可单测。
+ *
+ * @ai-context: source id 形如 "window:<HWND>:0"，HWND 用字符串传递（可能超
+ * 2^32，见 addon.cc）。native 缺失时降级为空信号（纯标题评分路径，与现状一致）。
+ * @ai-context EN: Pure signal-resolution layer. Callers inject native window
+ * enumeration results; missing native degrades to title-only scoring.
+ */
+
+// ================================================================
+// 类型定义
+// ================================================================
+
+/** native 枚举窗口的最小信号子集（对齐 processAudioNative.NativeWindowInfo 扩展后字段） */
+export interface NativeWindowSignal {
+  hwnd: string;
+  processName: string;
+  width: number;
+  height: number;
+  alwaysOnTop: boolean;
+}
+
+/** 评分所需几何信号（全部可选，缺失即不参与） */
+export interface GeometrySignals {
+  aspectRatio?: number;
+  areaRatio?: number;
+  alwaysOnTop?: boolean;
+}
+
+// ================================================================
+// 信号解析
+// ================================================================
+
+/**
+ * 从 desktopCapturer source id 解析 HWND。
+ * @param sourceId 形如 "window:<HWND>:0"；非 window 前缀或结构缺失返回 null
+ */
+export function parseHwndFromSourceId(sourceId: string | null): string | null {
+  if (!sourceId || !sourceId.startsWith('window:')) return null;
+  const parts = sourceId.split(':');
+  if (parts.length < 2 || !parts[1]) return null;
+  return parts[1];
+}
+
+/**
+ * 按 hwnd 字符串建索引，供 source id → native 窗口 O(1) 匹配。
+ */
+export function buildNativeIndex(
+  nativeWindows: NativeWindowSignal[],
+): Map<string, NativeWindowSignal> {
+  const index = new Map<string, NativeWindowSignal>();
+  for (const w of nativeWindows) {
+    index.set(w.hwnd, w);
+  }
+  return index;
+}
+
+/**
+ * 由 native 窗口 + 显示器面积计算几何信号。
+ * @param native 匹配到的 native 窗口；undefined 表示未匹配/信号源缺失
+ * @param displayArea 显示器面积（px²，screen 模块计算）；0 时面积占比置空避免除零
+ */
+export function resolveGeometrySignals(
+  native: NativeWindowSignal | undefined,
+  displayArea: number,
+): GeometrySignals {
+  if (!native) return {};
+  const signals: GeometrySignals = {
+    alwaysOnTop: native.alwaysOnTop,
+  };
+  if (native.width > 0 && native.height > 0) {
+    signals.aspectRatio = native.width / native.height;
+  }
+  if (displayArea > 0 && native.width > 0 && native.height > 0) {
+    signals.areaRatio = (native.width * native.height) / displayArea;
+  }
+  return signals;
+}