JS 自定义工具栏

/** 当前截图选区（屏幕坐标；只用 left/top/width/height，避免 right/bottom 含边歧义）。 */
type CaptureArea = {
  left: number;
  top: number;
  width: number;
  height: number;
};

/**
 * 不透明图片句柄。只能传给 runSp / post.keep / post.confirm / post.plan，
 * 不要当普通对象枚举或序列化。真实像素保存在宿主侧；伪造或过期句柄会被拒绝。
 */
type ImageRef = {
  readonly __captureImageHandle: string;
};

/** 可传入子程序 inputs / 出现在 outputs 中的值。 */
type JsPrimitive = null | boolean | number | string;
type JsInputValue =
  | JsPrimitive
  | ImageRef
  | CaptureArea
  | JsInputValue[]
  | { [key: string]: JsInputValue };
type JsOutputValue = JsInputValue;

type ProgramRunStatus = 'succeeded' | 'cancelled' | 'failed';

/** ctx.runSp 的统一结果。业务失败不抛异常，而是 ok: false。 */
type ProgramRunResult = {
  ok: boolean;
  status: ProgramRunStatus;
  /** 稳定错误码，如 missing_owner_action */
  code?: string;
  message?: string;
  target: {
    type: 'subprogram' | 'publicSubprogram';
    /** 公共子程序的 id 不含 %% 前缀 */
    id: string;
    title?: string;
  };
  /**
   * 子程序输出变量。
   * 处理型（图进图出）推荐：把结果图放到名为 image 的输出 → r.outputs.image → post.keep({ replace })。
   * 宿主不会把其它键名自动猜成 replace。
   */
  outputs?: Record<string, JsOutputValue>;
};

/** ctx.runSp 的完整对象参数；也可用字符串 id + 第二参 inputs 简写。 */
type RunSpOptions = {
  /** 动作内：名称或 GUID；公共：'%%' + 名称或 GUID */
  id: string;
  /** 仅动作内子程序需要；省略则用 ctx.originActionId */
  actionId?: string;
  /** 子程序输入变量，键名与输入变量同名；image: ctx.image 可省略 */
  inputs?: Record<string, JsInputValue>;
  /** 写入附加数据的图；默认 ctx.image；显式 null 表示不注入截图附加数据 */
  image?: ImageRef | null;
  area?: CaptureArea | null;
  timeoutMs?: number;
};

/** 点击自定义按钮时注入的只读上下文。布局阶段没有可用的 runSp。 */
type CaptureToolContext = {
  sessionId: string;
  toolId: string;
  host: 'capturePro' | 'pin';
  /** 点击瞬间合成图（含已提交标注，不含工具栏等界面装饰） */
  image: ImageRef;
  area: CaptureArea;
  /** 仅由动作内「截图 Pro」步骤进入时存在；全局快捷截图可能为空 */
  originActionId?: string;
  /**
   * 运行子程序并等待结束。
   * 简写：runSp('增强图片', { strength: 0.8 })  // 当前图可省略
   * 写全：runSp('增强图片', { image: ctx.image, strength: 0.8 })
   * 公共：runSp('%%上传到图床', { note: 'toolbar' })
   */
  runSp(
    idOrOptions: string | RunSpOptions,
    inputs?: Record<string, JsInputValue>,
  ): Promise<ProgramRunResult>;
};

type CapturePostSession = 'keep' | 'confirm' | 'close';

/**
 * post.keep / confirm / close / plan 的载荷。不要直接 return 图片或普通对象。
 * 未单独指定图片的 clipboard/pin/save/launchAction 使用 replace ?? ctx.image。
 */
type CapturePostPlan = {
  /** 设为当前会话新底图；替换后清空绘制元素 / OCR 层 / 撤销栈，屏幕选区框不变 */
  replace?: ImageRef;
  clipboard?: boolean | { image?: ImageRef };
  pin?: boolean | { image?: ImageRef; showToolbar?: boolean };
  /** 首版只走现有保存对话框，不支持任意路径静默写盘 */
  save?: boolean | { prompt?: boolean; image?: ImageRef };
  /**
   * 启动动作（不等待结束）。
   * 字符串简写为动作 Id 或名称；对象可带字符串 param。
   * 教：post.confirm({ launchAction })，不要写光秃秃的 post.plan({ launchAction })。
   */
  launchAction?:
    | string
    | {
        id: string;
        param?: string;
        image?: ImageRef | null;
        area?: CaptureArea | null;
      };
  session?: CapturePostSession;
  /** 字符串简写为提示文字 */
  notification?:
    | string
    | {
        level?: 'success' | 'info' | 'warning';
        text: string;
      };
};

/** 自定义工具栏按钮。id/type 可省略；必须提供可调用的 run。 */
type CaptureToolbarCommand = {
  id?: string;
  type?: 'command';
  title?: string;
  tooltip?: string;
  /** 如 fa:Light_WandMagic */
  icon?: string;
  /**
   * 点击时执行。允许返回：
   * - undefined / post.none() / post.keep()：成功且无后处理
   * - post.error(...)：失败提示
   * - post.keep / post.confirm / post.close / post.plan：后处理计划
   * 无 await 时可不写 async；有 await ctx.runSp 时必须 async。
   */
  run(
    ctx: CaptureToolContext,
  ): Promise<CapturePostPlan | void> | CapturePostPlan | void;
};

/**
 * 脚本顶层 return 值。
 * 默认：只返回自定义命令数组 → 原工具栏 + 固定位置下拉。
 * 进阶整栏重排：数组里出现内置 id / '|'，或 { layout } / { replace: true, items }。
 */
type CaptureToolbarLayout =
  | CaptureToolbarCommand[]
  | Array<string | string[] | CaptureToolbarCommand | CaptureToolbarCommand[]>
  | {
      version?: number;
      items?: Array<
        string | string[] | CaptureToolbarCommand | CaptureToolbarCommand[]
      >;
      layout?: Array<
        string | string[] | CaptureToolbarCommand | CaptureToolbarCommand[]
      >;
      replace?: boolean;
    };

/**
 * 点击阶段由宿主注入的全局对象（布局阶段不可用）。
 * keep / confirm / close / plan / error / none 的返回值请直接 return 给 run。
 */
declare const post: {
  /** 不关窗，继续截图。 */
  keep(plan?: CapturePostPlan): CapturePostPlan;
  /** 确认结束（等同点勾）；可再 launchAction。 */
  confirm(plan?: CapturePostPlan): CapturePostPlan;
  /** 取消关闭（等同点叉）。 */
  close(plan?: CapturePostPlan): CapturePostPlan;
  /** 进阶组合；请写明 session。 */
  plan(plan: CapturePostPlan): CapturePostPlan;
  error(resultOrMessage: ProgramRunResult | string): CapturePostPlan;
  none(): CapturePostPlan;
};

// 脚本最后应 return 符合 CaptureToolbarLayout 的值