clickgo 7.0.0 → 7.2.0

package/dist/lib/core.d.ts

@@ -19,6 +19,7 @@ import * as clickgo from '../clickgo';
 import * as lForm from './form';
 import * as lControl from './control';
 import type * as lCommand from './command';
+import type * as lNativeEvents from './native/events';
 import * as lCore from './core';
 /**
  * --- 初始化系统级 ID，仅能设置一次 ---
@@ -29,6 +30,19 @@ export declare function initSysId(id: string): void;
 export declare let config: IConfig;
 /** --- App 抽象类 --- */
 export declare abstract class AbstractApp {
+    /**
+     * --- Native 普通启动及再次启动事件；网页不触发，App/Form 要求 root ---
+     * @param event 业务参数、原生工作目录、来源及请求 ID
+     * @returns 无；各层级独立收到通知，同一业务动作由应用选择一处执行
+     */
+    onNativeLaunch(event: lNativeEvents.INativeLaunchEvent): void | Promise<void>;
+    /**
+     * --- Native 文件打开全局事件，要求宿主启用 openFiles；App/Form 要求 root ---
+     * @param paths 不含 /storage/ 的 ClickGo 绝对文件路径
+     * @param info startup、second-instance、association 或 drop 来源及请求 ID
+     * @returns 无；各层级独立通知，业务自行确认、保存和打开
+     */
+    onNativeOpenFiles(paths: string[], info: lNativeEvents.INativeOpenFilesInfo): void | Promise<void>;
     /** --- 当前 js 文件在包内的完整路径 --- */
     filename: string;
     /** --- 系统会自动设置本项 --- */
@@ -252,7 +266,7 @@ export interface IAvailArea {
     'oheight': number;
 }
 /** --- 全局事件类型 --- */
-export type TGlobalEvent = 'trayCreated' | 'trayChanged' | 'trayRemoved' | 'error' | 'screenResize' | 'configChanged' | 'formCreated' | 'formRemoved' | 'formTitleChanged' | 'formIconChanged' | 'formStateMinChanged' | 'formStateMaxChanged' | 'formShowChanged' | 'formFocused' | 'formBlurred' | 'formFlash' | 'formShowInSystemTaskChange' | 'formHashChange' | 'taskStarted' | 'taskEnded' | 'webMcpStatusChanged' | 'launcherShowChanged' | 'launcherFolderNameChanged' | 'hashChanged' | 'keydown' | 'keyup';
+export type TGlobalEvent = 'nativeLaunch' | 'nativeOpenFiles' | 'trayCreated' | 'trayChanged' | 'trayRemoved' | 'error' | 'screenResize' | 'configChanged' | 'formCreated' | 'formRemoved' | 'formTitleChanged' | 'formIconChanged' | 'formStateMinChanged' | 'formStateMaxChanged' | 'formShowChanged' | 'formFocused' | 'formBlurred' | 'formFlash' | 'formShowInSystemTaskChange' | 'formHashChange' | 'taskStarted' | 'taskEnded' | 'webMcpStatusChanged' | 'launcherShowChanged' | 'launcherFolderNameChanged' | 'hashChanged' | 'keydown' | 'keyup';
 /** --- 现场下载 app 的参数 --- */
 export interface ICoreFetchAppOptions {
     'notify'?: number | {

package/dist/lib/form.d.ts

@@ -2,6 +2,7 @@ import * as lCore from './core';
 import * as lCommand from './command';
 import * as lDom from './dom';
 import * as lControl from './control';
+import type * as lNativeEvents from './native/events';
 /**
  * --- 初始化系统级 ID，仅能设置一次 ---
  * @param id 系统级 ID
@@ -177,6 +178,19 @@ export declare abstract class AbstractComponent extends AbstractCommon {
 }
 /** --- 窗体的抽象类 --- */
 export declare abstract class AbstractForm extends AbstractCommon {
+    /**
+     * --- Native 普通启动及再次启动事件；网页不触发，App/Form 要求 root ---
+     * @param event 业务参数、原生工作目录、来源及请求 ID
+     * @returns 无；各层级独立收到通知，同一业务动作由应用选择一处执行
+     */
+    onNativeLaunch(event: lNativeEvents.INativeLaunchEvent): void | Promise<void>;
+    /**
+     * --- Native 文件打开全局事件，要求宿主启用 openFiles；App/Form 要求 root ---
+     * @param paths 不含 /storage/ 的 ClickGo 绝对文件路径
+     * @param info startup、second-instance、association 或 drop 来源及请求 ID
+     * @returns 无；各层级独立通知，业务自行确认、保存和打开
+     */
+    onNativeOpenFiles(paths: string[], info: lNativeEvents.INativeOpenFilesInfo): void | Promise<void>;
     /** --- 当前是否完全创建完毕 --- */
     isReady: boolean;
     /** --- 是否是 native 下无边框的第一个窗体 --- */

package/dist/lib/native/events.d.ts

@@ -0,0 +1,37 @@
+/** --- 操作系统文件打开请求来源 --- */
+export type TNativeOpenFilesSource = 'startup' | 'second-instance' | 'association' | 'drop';
+/** --- 普通 GUI 启动请求；CLI/stdio 由 Native 单独处理，不投递此事件 --- */
+export interface INativeLaunchEvent {
+    /** --- 本进程内请求 ID；同一次启动的文件事件使用相同 ID --- */
+    'requestId': number;
+    'source': 'startup' | 'second-instance';
+    /** --- 去掉可执行文件和开发入口后的业务参数，保留顺序 --- */
+    'args': string[];
+    /** --- 原生绝对工作目录，参数中的相对路径以此为基准 --- */
+    'cwd': string;
+}
+/** --- 文件事件上下文；paths 为不含 /storage/ 的 ClickGo 绝对文件路径 --- */
+export interface INativeOpenFilesInfo {
+    'requestId': number;
+    'source': TNativeOpenFilesSource;
+}
+/** --- Native 主文档桥接数据；框架内部使用 --- */
+export type TNativeEvent = {
+    'type': 'launch';
+    'event': INativeLaunchEvent;
+} | {
+    'type': 'openFiles';
+    'paths': string[];
+    'info': INativeOpenFilesInfo;
+};
+/** --- 系统事件传输适配，生命周期与授权由调用方控制 --- */
+export interface INativeEventDispatcherOptions {
+    /** --- ClickGo Boot.main 已完成且处于 Native 环境 --- */
+    'ready': () => boolean;
+    /** --- 读取当前会话未投递请求；旧宿主为 null，失败为 false --- */
+    'read': () => Promise<TNativeEvent[] | null | false>;
+    /** --- 按事件类型进入框架全局分发 --- */
+    'dispatch': (event: TNativeEvent) => Promise<void>;
+    /** --- 传输异常报告，不输出业务参数 --- */
+    'error': (error: unknown) => void;
+}

package/dist/lib/native/update.d.ts

@@ -0,0 +1,48 @@
+import * as lCore from '../core';
+/** --- 下载进度：百分比 0–100，其余值为字节数或字节/秒 --- */
+export interface IUpdateProgress {
+    'percent': number;
+    'transferred': number;
+    'total': number;
+    'bytesPerSecond': number;
+}
+/** --- Native 软件级更新状态，不含更新源、凭据和安装路径 --- */
+export interface IUpdateState {
+    'status': 'idle' | 'checking' | 'available' | 'up-to-date' | 'disabled' | 'error' | 'downloading' | 'downloaded' | 'restarting';
+    'currentVersion': string;
+    'version'?: string;
+    'progress'?: IUpdateProgress;
+    'reason'?: 'not-enabled' | 'development' | 'portable';
+    'errorCode'?: 'check-failed' | 'download-failed' | 'not-ready' | 'install-failed';
+}
+/**
+ * --- 检测软件更新，主进程须 launcher({ updates: true }) 并配置 build.publish ---
+ * @param current 当前 App 或窗体，要求 root 权限
+ * @returns 检测状态；开发/便携/未启用返回 disabled，无权限为 false，网页/旧宿主为 null
+ */
+export declare function checkUpdates(current: lCore.TCurrent): Promise<IUpdateState | null | false>;
+/**
+ * --- 下载检测到的版本，合并并发下载，由 Native 校验文件 ---
+ * @param current 当前 App 或窗体，要求 root 权限，业务须先取得用户确认
+ * @returns downloaded 表示校验完成，未就绪/失败为 error；无权限为 false，不支持为 null
+ */
+export declare function downloadUpdate(current: lCore.TCurrent): Promise<IUpdateState | null | false>;
+/**
+ * --- 安装本进程已下载的版本并重启，业务须先保存文档并确认 ---
+ * @param current 当前 App 或窗体，要求 root 权限
+ * @returns restarting 表示安装开始；异步失败由 onUpdateState 通知，无权限为 false，不支持为 null
+ */
+export declare function installUpdate(current: lCore.TCurrent): Promise<IUpdateState | null | false>;
+/**
+ * --- 读取 Native 软件级更新状态快照 ---
+ * @param current 当前 App 或窗体，要求 root 权限
+ * @returns 当前状态，无权限为 false，网页或旧宿主不支持为 null
+ */
+export declare function getUpdateState(current: lCore.TCurrent): Promise<IUpdateState | null | false>;
+/**
+ * --- 监听软件级公开状态及下载进度；不包含 URL、凭据或文件路径 ---
+ * @param current 当前 App 或窗体，不要求 root；控制更新仍须 root
+ * @param handler 状态回调，业务不需要定义 Native 事件名
+ * @returns 无返回值；窗体或任务销毁时自动解除，网页/旧宿主不会投递
+ */
+export declare function onUpdateState(current: lCore.TCurrent, handler: (state: IUpdateState) => void | Promise<void>): void;

package/dist/lib/native.d.ts

@@ -2,11 +2,27 @@ import * as lCore from './core';
 import type * as lNativeStorage from './native/storage';
 export * as storage from './native/storage';
 export * as secret from './native/secret';
+export { checkUpdates, downloadUpdate, installUpdate, getUpdateState, onUpdateState } from './native/update';
+export type { IUpdateState, IUpdateProgress } from './native/update';
+export type { INativeLaunchEvent, INativeOpenFilesInfo, TNativeOpenFilesSource } from './native/events';
 /**
  * --- 初始化系统级 ID，仅能设置一次 ---
  * @param id 系统级 ID
  */
 export declare function initSysId(id: string): void;
+/**
+ * --- 完成宿主业务初始化并读取 Native 暂存事件，仅系统入口可调用 ---
+ * @param current 系统级 ID
+ * @returns 无
+ */
+export declare function ready(current: string): void;
+/**
+ * --- 接入固定的软件更新动作，不允许网页提供地址或安装路径 ---
+ * @param current 已确认有效的任务
+ * @param action 固定更新动作
+ * @returns 更新状态；任务失效为 false，旧宿主缺少能力时为 null
+ */
+export declare function invokeUpdate(current: lCore.TCurrent, action: 'check' | 'download' | 'install' | 'state'): Promise<import('./native/update').IUpdateState | null | false>;
 /** --- 本地 MCP 客户端连接设置；仅向已授权 root 的 App 提供 --- */
 export interface IMcpInfo {
     'transport': 'streamable-http';