@solazah/solazah-runtime 0.1.154 → 0.1.158

package/package.json

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

package/types/Plugin.d.ts

@@ -144,6 +144,13 @@ export default class Plugin {
      * @param enabled 开或关。
      */
     setContentProtection: (enabled: boolean) => Promise<void>;
+    /**
+     * 让插件自己的窗口对鼠标透明:点击、滚动全部穿过去落到下面的窗口。给罩在屏幕上只做展示的浮层用
+     * (录制期间的选区边框),不然它盖住的那块屏幕就点不到了。
+     *
+     * @param ignore 开或关。
+     */
+    setIgnoreMouseEvents: (ignore: boolean) => Promise<void>;
     /**
      * 取发起方插件自身的完整信息。
      * 通过 webContents 逆向定位插件,返回插件实体字段 + 其全部命令(commands 数组)+

package/types/SystemKeyboard.d.ts

@@ -16,4 +16,47 @@ export default class SystemKeyboard {
      * @returns 选区内容对象 {type, content},type 为 text/image/fileName/fileUrl 之一;无内容时返回 null。
      */
     copy: () => Promise<any>;
+    /**
+     * 向当前前台窗口合成一次组合键（按下修饰键→敲主键→全部抬起）。
+     *
+     * @param combo 组合键字符串，形如 "ctrl+v"、"win+r"、"ctrl+shift+t"；分隔符 +、空格、制表符可混用。
+     * @returns 无返回
+     */
+    keypress: (combo: string) => Promise<void>;
+    /**
+     * 按下一个键不抬起，配合 keyUp 做「按住直到条件满足」的闭环控制。键名与 keypress 同一套，但只能是单键。
+     * 宿主按调用方记账：本视图销毁、页面整页导航（重载）、宿主退出时，它按着的键全部自动抬起。
+     *
+     * @param key 键名，形如 "w"、"shift"、"space"、"f5"，不区分大小写。
+     * @returns 无返回
+     * @throws 键名不被支持时抛错（code UNSUPPORTED_KEY）。
+     */
+    keyDown: (key: string) => Promise<void>;
+    /**
+     * 抬起一个键。抬一个没按着的键也照发，可用来解开账本没记到的键。
+     *
+     * @param key 键名，与 keyDown 一致。
+     * @returns 无返回
+     */
+    keyUp: (key: string) => Promise<void>;
+    /**
+     * 按住一个键指定时长后抬起，Promise 在抬起后兑现；途中不论出什么异常，抬起都会发出。
+     * 需要按住直到某个条件满足时，用 keyDown + keyUp 自己收口。
+     *
+     * @param key     键名，与 keyDown 一致。
+     * @param options `{durationMs}`，按住多少毫秒，不小于 0。
+     * @returns 无返回
+     */
+    hold: (key: string, options: {
+        durationMs: number;
+    }) => Promise<void>;
+    /**
+     * 急停：抬起本视图按着的全部键与鼠标键（keyDown / hold / systemMouse.buttonDown 按下的）。
+     *
+     * @returns `{keys, buttons}`，实际抬起了哪些；什么都没按着时两个都是空数组。
+     */
+    releaseAll: () => Promise<{
+        keys: string[];
+        buttons: Array<"left" | "right" | "middle">;
+    }>;
 }

package/types/SystemMouse.d.ts

@@ -79,4 +79,28 @@ export default class SystemMouse {
      * @returns 无返回。
      */
     scroll: (dx: number, dy: number, at?: Point) => Promise<any>;
+    /**
+     * 从当前光标位置相对移动，给转镜头一类的拖拽用（先 buttonDown，再多次 moveBy，最后 buttonUp）。
+     * 走光标定位，不产生原始输入（Raw Input）的相对位移事件；只读原始输入位移的应用看不到这次移动。
+     *
+     * @param dx 水平位移像素，正数向右。
+     * @param dy 垂直位移像素，正数向下。
+     * @returns 移动后的光标屏幕坐标 `{x, y}`。
+     */
+    moveBy: (dx: number, dy: number) => Promise<Point>;
+    /**
+     * 按下鼠标键不抬起。宿主按调用方记账：本视图销毁、页面整页导航、宿主退出时自动抬起，
+     * systemKeyboard.releaseAll 也会一并抬起。
+     *
+     * @param button left / right / middle，缺省 left。
+     * @returns 无返回
+     */
+    buttonDown: (button?: "left" | "right" | "middle") => Promise<void>;
+    /**
+     * 抬起鼠标键。
+     *
+     * @param button left / right / middle，缺省 left。
+     * @returns 无返回
+     */
+    buttonUp: (button?: "left" | "right" | "middle") => Promise<void>;
 }

package/types/SystemScreen.d.ts

@@ -63,6 +63,182 @@ export interface GoneWait {
     timeoutMs: number;
     cancelled: boolean;
 }
+/** 帧的编码：png / jpeg 时 data 是 Data URL 字符串；raw 时 data 是 BGRA 像素（Uint8Array，自顶向下，每像素 4 字节）。 */
+export type StreamFormat = "png" | "jpeg" | "raw";
+export interface StreamOptions {
+    /** 目标显示器 id；省略则是开流那一刻光标所在的显示器，之后不随光标变 */
+    displayId?: number;
+    /** 只截这一块，显示器物理像素、相对显示器左上角；省略整屏。超出显示器的部分裁掉 */
+    region?: ScreenRect;
+    /** 每秒几帧，1..30，缺省 10 */
+    fps?: number;
+    /** 缺省 png。1080p 整屏 png 一帧要几十毫秒且占主进程，高帧率大画面用 jpeg 或 raw */
+    format?: StreamFormat;
+    /** jpeg 质量 1..100，缺省 85 */
+    quality?: number;
+}
+/** 开流的结果：帧从 channel 推来，用 `window.ipcRenderer.on(channel, (_, frame) => …)` 接。 */
+export interface StreamInfo {
+    streamId: string;
+    /** 帧通道名 screen.stream.frame.<streamId>，一条流一个通道 */
+    channel: string;
+    displayId: number;
+    /** 实际截取的区域（已裁到显示器内），显示器物理像素、相对显示器左上角 */
+    region: ScreenRect;
+    width: number;
+    height: number;
+    /** 实际生效的帧率 */
+    fps: number;
+    format: StreamFormat;
+}
+/** 推来的一帧。 */
+export interface StreamFrame {
+    streamId: string;
+    /** 从 1 起、逐帧加一：收到的帧序号连续，丢掉的帧不占序号 */
+    seq: number;
+    /** 抓帧那一刻的墙钟毫秒时间戳，与 Date.now() 同一时基（带亚毫秒小数）：插件自己记的事件按 Date.now() 打时间戳就能与帧对齐 */
+    at: number;
+    width: number;
+    height: number;
+    format: StreamFormat;
+    data: string | Uint8Array;
+    /** 到这一帧为止累计丢了几帧（页面没处理完上一帧、或截屏还没回来时到期的拍） */
+    dropped: number;
+}
+export interface StreamStats {
+    streamId: string;
+    /** 推出去的帧数 */
+    frames: number;
+    dropped: number;
+    durationMs: number;
+}
+/** HSV 颜色：h 色相角度 0..360，s 饱和度 0..100，v 明度 0..100。 */
+export interface Hsv {
+    h: number;
+    s: number;
+    v: number;
+}
+export interface ColorBlobOptions {
+    /** 色域下限。hsvLow.h 大于 hsvHigh.h 时按跨 0 度处理（红色给 {h: 350} 到 {h: 10}） */
+    hsvLow: Hsv;
+    hsvHigh: Hsv;
+    /** 面积（像素数）不到它的连通域不要，缺省 1 */
+    minArea?: number;
+    /** 最多返回几个，按面积降序取，缺省 50 */
+    maxResults?: number;
+}
+/** 一个色块：外接框、面积（像素数）、质心。 */
+export interface ColorBlob {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    area: number;
+    cx: number;
+    cy: number;
+}
+/** findBlobs 的来源：图片（Data URL 或本机绝对路径），或截显示器上的一块（region 为显示器物理像素、相对显示器左上角）。 */
+export type BlobSource = string | {
+    displayId?: number;
+    region?: ScreenRect;
+    image?: string;
+};
+export interface RecordStartOptions {
+    /** 目标显示器 id；省略取光标所在显示器 */
+    displayId?: number;
+    /** 只录这一块，显示器物理像素、相对显示器左上角；省略整屏。超出显示器的部分裁掉，宽高取到偶数 */
+    region?: ScreenRect;
+    /** 目标帧率 1..60；mp4 缺省 30，gif 缺省 12。画面不变时不产生新帧，文件按可变帧率写，时长仍与墙钟一致 */
+    fps?: number;
+    /** 是否把光标录进去，缺省 true */
+    cursor?: boolean;
+    /** mp4：H.264 硬件编码；gif：全局调色板抖动量化 */
+    format: "mp4" | "gif";
+    /** 输出文件的绝对路径，后缀由调用方按 format 定 */
+    output: string;
+    /** mp4 目标码率（bit/s），省略按分辨率与帧率取 */
+    bitrate?: number;
+    /** gif 输出最大宽度，省略不缩放 */
+    maxWidth?: number;
+    /** 到这个秒数自动停，结果留到下一次 stop 取 */
+    maxSeconds?: number;
+}
+/** 开始录制的结果：实际生效的区域（已裁到显示器内、取到偶数）与参数。 */
+export interface RecordInfo {
+    displayId: number;
+    region: ScreenRect;
+    width: number;
+    height: number;
+    fps: number;
+    format: "mp4" | "gif";
+    output: string;
+    /** Date.now() */
+    startedAt: number;
+}
+export interface RecordStats {
+    path: string;
+    format: string;
+    /** 实际用的编码器，如 h264_videotoolbox(zero-copy) */
+    encoder: string;
+    width: number;
+    height: number;
+    frames: number;
+    dropped: number;
+    durationMs: number;
+    bytes: number;
+    displayId: number;
+    region: ScreenRect;
+}
+export interface RecordStatus {
+    active: boolean;
+    frames: number;
+    dropped: number;
+    elapsedMs: number;
+    info: RecordInfo | null;
+    /** 自动停下来（到时、视图销毁）还没被 stop 取走的结果 */
+    finished: RecordStats | null;
+}
+export interface LongShotOptions {
+    /** 目标显示器 id；省略取光标所在显示器 */
+    displayId?: number;
+    /** 要截取的区域，显示器物理像素、相对显示器左上角；省略整屏 */
+    region?: ScreenRect;
+    /** 输出 PNG 的绝对路径 */
+    output: string;
+    /**
+     * 排查用：把每一帧连同当帧算出的判定落到这个目录，供离线重放。
+     * 编码每帧会拖慢抓取节奏（滚动会发涩），只在查问题时开。
+     */
+    traceDir?: string;
+}
+export interface LongShotResult {
+    path: string;
+    width: number;
+    height: number;
+    /** 在第一屏之后接上了几段 */
+    segments: number;
+}
+export interface LongShotStatus {
+    active: boolean;
+    /** 已拼长图的宽高（物理像素） */
+    width: number;
+    height: number;
+    /** 当前屏顶边在长图里的位置与当前屏高度（物理像素）；滚到起点之上时 viewportTop 为负 */
+    viewportTop: number;
+    viewportHeight: number;
+    /** 任何变化（接上新内容、视口移动）都加 1 */
+    version: number;
+    /** 缩略图变化（接上新内容）时加 1 */
+    thumbVersion: number;
+    /** 长图到了高度上限，不再接 */
+    capped: boolean;
+    /** since 早于 thumbVersion 时才有：整幅长图的缩略图 PNG Data URL 与尺寸 */
+    thumbnail?: {
+        dataUrl: string;
+        width: number;
+        height: number;
+    };
+}
 export default class SystemScreen {
     private transport;
     constructor(transport?: IpcRenderer);
@@ -256,4 +432,89 @@ export default class SystemScreen {
      * @returns 该点的 RGBA 颜色值 `{R, G, B, A}`,各通道 0–255。
      */
     colorAt: (point: Point) => Promise<any>;
+    /**
+     * 连续截图流：宿主按 fps 截显示器（或其中一块区域），逐帧推给本视图。
+     * 区域在宿主侧直接截，不是整屏截了再裁。背压由宿主处理：页面还没处理完上一帧就到期的拍直接丢，
+     * 绝不排队；每帧的 dropped 与 stop 的统计里能看到丢了多少。本视图销毁时流自动停。
+     *
+     * 用法：`const {channel} = await start({fps: 10, region}); window.ipcRenderer.on(channel, (_, frame) => …)`。
+     * 帧通道是单监听（同 ipcRenderer.on 的约定），一条流一个通道，多条流互不影响。
+     */
+    stream: {
+        /**
+         * 开一条流。
+         *
+         * @param options `{displayId?, region?, fps?, format?, quality?}`，fps 上限 30。
+         * @returns `{streamId, channel, displayId, region, width, height, fps, format}`。
+         * @throws 显示器不存在、区域完全在显示器外时抛错。
+         */
+        start: (options?: StreamOptions) => Promise<StreamInfo>;
+        /**
+         * 停一条流，之后不再有帧。
+         *
+         * @param streamId start 给的流 id。
+         * @returns `{streamId, frames, dropped, durationMs}`；不是本视图开的、或已经停了给 null。
+         */
+        stop: (streamId: string) => Promise<StreamStats | null>;
+    };
+    /**
+     * 色域连通域检测：把落在 HSV 阈值内的像素连成块，给回每块的外接框、面积、质心，按面积降序。
+     * 给闭环控制里认血条、准星、标记点这类纯色目标用。
+     *
+     * @param source  图片的 Data URL 或本机绝对路径；或 `{displayId?, region?}` 截显示器上的一块（缺省光标所在显示器整屏）；
+     *   `{image, region}` 则在给定图片里只看一块。
+     * @param options `{hsvLow, hsvHigh, minArea?, maxResults?}`，h 0..360、s 与 v 0..100。
+     * @returns `[{x, y, width, height, area, cx, cy}]`；给图片时坐标相对图片左上角，截屏时是屏幕物理像素坐标。找不到是空数组。
+     */
+    findBlobs: (source: BlobSource, options: ColorBlobOptions) => Promise<ColorBlob[]>;
+    /**
+     * 屏幕录制：采集与编码全在宿主的原生线程（mac ScreenCaptureKit + VideoToolbox 硬件 H.264，Windows WGC + Media Foundation），
+     * mp4 或 gif 直接写到给定路径，页面不经手任何帧。同一时刻只有一个会话；本视图销毁、到了 maxSeconds 都会自动停。
+     *
+     * 用法：`await record.start({format: "mp4", output, region})` … `const stats = await record.stop()`；
+     * 录制中用 `record.status()` 取帧数与已录时长。
+     */
+    record: {
+        /**
+         * 开始录制。
+         *
+         * @param options `{displayId?, region?, fps?, cursor?, format, output, bitrate?, maxWidth?, maxSeconds?}`。
+         * @returns `{displayId, region, width, height, fps, format, output, startedAt}`。
+         * @throws 已有录制、区域太小、平台不支持时抛错。
+         */
+        start: (options: RecordStartOptions) => Promise<RecordInfo>;
+        /**
+         * 停止并给回统计；录制已经自动停了就给那一次的结果。
+         *
+         * @returns `{path, format, encoder, width, height, frames, dropped, durationMs, bytes, displayId, region}`。
+         */
+        stop: () => Promise<RecordStats>;
+        /** 取消：停下来并删掉已写的文件；录制已经自动停了就删那次的产物。 */
+        cancel: () => Promise<void>;
+        /** 进行中的帧数、丢帧、已录时长、会话信息；自动停下来还没取走的结果在 finished 里。 */
+        status: () => Promise<RecordStatus>;
+    };
+    /**
+     * 滚动长截图：宿主盯着区域，使用者自己滚动页面，每帧与上一帧比出位移后把新露出的部分接上去，finish 时把 PNG 写到给定路径。
+     * 粘性头部/底部的页面靠只比中间一条窄带减轻错位，仍可能拼得不完美。
+     */
+    longshot: {
+        /**
+         * 开始一张长图，直到 finish 或 cancel 才返回。
+         *
+         * @param options `{displayId?, region?, output}`。
+         * @returns `{path, width, height, segments}`；被 cancel 取消时是 null。
+         */
+        capture: (options: LongShotOptions) => Promise<LongShotResult | null>;
+        /** 收尾：停止拼接、把已拼的长图落盘，capture 随之返回。 */
+        finish: () => Promise<void>;
+        /** 取消：停止拼接、不落盘，capture 返回 null。 */
+        cancel: () => Promise<void>;
+        /**
+         * 进行中长截图的状态：已拼尺寸、当前屏位置、版本号。
+         *
+         * @param since 上次拿到的 thumbVersion；缩略图没变就不再附带。省略则总是附带。
+         */
+        status: (since?: number) => Promise<LongShotStatus>;
+    };
 }