@solazah/solazah-runtime 0.2.34 → 0.2.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solazah/solazah-runtime",
-  "version": "0.2.34",
+  "version": "0.2.37",
   "main": "index.cjs",
   "module": "index.js",
   "types": "types/index.d.ts",

package/types/SystemOCR.d.ts

@@ -6,6 +6,22 @@ export interface OCRTextBlock {
     /** 四个角点坐标,顺时针或逆时针,不是 x/y/width/height 矩形 */
     box: [number, number][];
 }
+/** 检测结果,与主进程 OcrProtocol 的 OcrDetection 同构(真源在那里)。 */
+export interface OCRDetection {
+    /** 帧句柄,交给 recognizeBoxes 按框取字。 */
+    frame: string;
+    width: number;
+    height: number;
+    /** 文字框,每个是四个角点坐标(顺时针,从左上起),按阅读顺序排列;recognizeBoxes 的 indices 指的就是这里的序号。 */
+    boxes: [number, number][][];
+}
+/** 按框识别的结果,与主进程 OcrProtocol 的 OcrBoxTexts 同构(真源在那里)。 */
+export type OCRBoxTexts = {
+    found: true;
+    texts: Array<OCRTextBlock | null>;
+} | {
+    found: false;
+};
 export default class SystemOCR {
     private transport;
     constructor(transport?: IpcRenderer);
@@ -17,4 +33,31 @@ export default class SystemOCR {
      * @throws 图片解码失败或 OCR 引擎未就绪时抛错。
      */
     recognize: (base64String: string) => Promise<OCRTextBlock[]>;
+    /**
+     * 两步式识别的第一步:只检测出文字框,不认字。检测只占整图识别耗时的一小部分,大头是逐框认字;
+     * 先要框的位置(如框选、高亮)时用它,文字再用 recognizeBoxes 按需取。
+     * 同一张图重复调用命中缓存,直接返回同一个帧句柄。
+     *
+     * @param base64String Base64 编码的图片数据(PNG、JPEG、BMP)。
+     * @returns frame(帧句柄)、width/height(图片尺寸)、boxes(文字框,阅读顺序)。
+     * @throws 图片解码失败或 OCR 引擎未就绪时抛错。
+     */
+    detect: (base64String: string) => Promise<OCRDetection>;
+    /**
+     * 两步式识别的第二步:按框认字。已认过的框直接返回,同一个框不会重复推理。
+     *
+     * 返回 found: false 表示这一帧已不在引擎里(之后检测的图太多把它挤出、OCR 进程空闲回收或重启),
+     * 或要的框里有没认过的、而这一帧的原图已经释放(之后又有几张图检测完在等补字,引擎只给最近用过的几张留原图);
+     * 这是预期内的结果,不是失败:用同一张图重新 detect,拿新的 frame 再取(框的序号不变)。
+     *
+     * @param frame detect 返回的帧句柄。
+     * @param indices 要认的框在 detect 返回的 boxes 里的序号。
+     * @param options background 为 true 时排在一切前台请求之后,适合在后台分批把整帧补齐;
+     *                用户正在看、正在选的框不要带它。
+     * @returns found 为 true 时 texts 与 indices 一一对应,框里认不出字为 null。
+     * @throws 序号越界或 OCR 引擎出错时抛错。
+     */
+    recognizeBoxes: (frame: string, indices: number[], options?: {
+        background?: boolean;
+    }) => Promise<OCRBoxTexts>;
 }

package/types/SystemScreen.d.ts

@@ -151,6 +151,54 @@ export type BlobSource = string | {
     region?: ScreenRect;
     image?: string;
 };
+/** findFlicker 的参数：在哪块截、截多久、多快，以及闪光判据。坐标都是显示器物理像素、相对显示器左上角。 */
+export interface FlickerOptions {
+    /** 目标显示器 id；省略取光标所在显示器 */
+    displayId?: number;
+    /** 只看这一块；省略整屏。聊天框这类会滚字的界面要排除在外 */
+    region?: ScreenRect;
+    /** 连截多久，缺省 4000 */
+    durationMs?: number;
+    /** 每秒截几帧，1..30，缺省 4 */
+    fps?: number;
+    /** 和前后各几帧比，缺省 4 */
+    halfWindow?: number;
+    /** 亮度要比前后帧的中位数高出多少才算闪，0..255，缺省 45 */
+    lift?: number;
+    /** 闪光像素的最低亮度（三通道最大值），缺省 140 */
+    minValue?: number;
+    /** 闪光的色相范围（角度），缺省 45..85，即偏黄绿的星光 */
+    hueLow?: number;
+    hueHigh?: number;
+    /** 闪光的最低饱和度 0..1，缺省 0.25 */
+    minSaturation?: number;
+    /** 一个光点的像素数范围，缺省 4..40 */
+    minSize?: number;
+    maxSize?: number;
+    /** 同一帧里多近的闪光像素合成一个光点，缺省 6 */
+    groupRadius?: number;
+    /** 多近的光点算同一处，缺省 50 */
+    clusterRadius?: number;
+    /** 最多返回几处，缺省 10 */
+    maxResults?: number;
+    /** 取消记号，同 WaitOptions.token */
+    token?: string;
+}
+/** 反复冒光点的一处：中心（屏幕物理像素）、冒过光点的帧数、光点总数。 */
+export interface FlickerCluster {
+    x: number;
+    y: number;
+    frames: number;
+    spots: number;
+}
+/** 按冒过光点的帧数降序；unstableFrames 是画面整体在动、被跳过的帧数。 */
+export interface FlickerResult {
+    clusters: FlickerCluster[];
+    frames: number;
+    unstableFrames: number;
+    durationMs: number;
+    cancelled: boolean;
+}
 export interface RecordStartOptions {
     /** 目标显示器 id；省略取光标所在显示器 */
     displayId?: number;
@@ -476,6 +524,14 @@ export default class SystemScreen {
      * @returns `[{x, y, width, height, area, cx, cy}]`；给图片时坐标相对图片左上角，截屏时是屏幕物理像素坐标。找不到是空数组。
      */
     findBlobs: (source: BlobSource, options: ColorBlobOptions) => Promise<ColorBlob[]>;
+    /**
+     * 闪烁光点：在显示器的一块区域上连截一段，找反复冒小光点的地方——游戏里可采集物冒出的星光、界面上闪的提示点。
+     * 静止的东西每帧一样亮，只有闪的才比前后帧亮出来；同一处反复冒光点的排在前面。截帧期间视角要保持不动。
+     *
+     * @param options `{displayId?, region?, durationMs?, fps?, hueLow?, hueHigh?, …, token?}`，见 FlickerOptions。
+     * @returns `{clusters: [{x, y, frames, spots}], frames, unstableFrames, durationMs, cancelled}`，坐标是屏幕物理像素；找不到 clusters 为空。
+     */
+    findFlicker: (options?: FlickerOptions) => Promise<FlickerResult>;
     /**
      * 屏幕录制：采集与编码全在宿主的原生线程（mac ScreenCaptureKit + VideoToolbox 硬件 H.264，Windows WGC + Media Foundation），
      * mp4 或 gif 直接写到给定路径，页面不经手任何帧。同一时刻只有一个会话；本视图销毁、到了 maxSeconds 都会自动停。