JavaScript 与 ShellAPI

// Generated from ../../framework/shell_api/common.d.ts, ../../framework/shell_api/dialog.d.ts, ../../framework/shell_api/path.d.ts, ../../framework/shell_api/remoting.d.ts, ../../framework/shell_api/fs.d.ts, ../../framework/shell_api/storage.d.ts, ../../framework/shell_api/log.d.ts, ../../framework/shell_api/network.d.ts, ../../framework/shell_api/utility.d.ts, ../../framework/shell_api/window.d.ts. Do not edit.

declare global {
  interface Window {
    readonly tuffite: typeof import('./dialog').tuffite & typeof import('./path').tuffite & typeof import('./remoting').tuffite & typeof import('./fs').tuffite & typeof import('./storage').tuffite & typeof import('./log').tuffite & typeof import('./network').tuffite & typeof import('./utility').tuffite & typeof import('./window').tuffite & import('../runtime').NativeBridge;
  }
}

export {};

export type Codec = Readonly<Record<string, unknown>>;

export type TuffiteErrorCode =
  | "invalid_argument"
  | "incompatible_abi"
  | "invalid_handle"
  | "unavailable"
  | "resource_exhausted"
  | "internal"
  | "transport_unavailable"
  | "invalid_request"
  | "unknown_command"
  | "handler_failed"
  | "decode_error"
  | "protocol_mismatch"
  | "schema_mismatch"
  | "command_failed"
  | (string & {});

export class TuffiteError extends Error {
  readonly code: TuffiteErrorCode;
  readonly requestId?: bigint;
  readonly cause?: unknown;
  constructor(
    code: TuffiteErrorCode,
    message: string,
    options?: Readonly<{ requestId?: bigint; cause?: unknown }>,
  );
}

export interface ChannelEvent extends Event {
  readonly detail: Readonly<{ channel: string; data: Uint8Array }>;
}

export interface ExplorerMessageEvent<T = unknown> extends Event {
  readonly detail: Readonly<{ data: T; from: string }>;
}

export interface ExplorerOpenEvent extends Event {
  readonly detail: Readonly<{
    url: string;
    disposition: string;
    userGesture: boolean;
    from: string;
  }>;
}

export interface ExplorerDialogController {
  readonly type: "alert" | "confirm" | "prompt" | "beforeunload";
  readonly message: string;
  readonly defaultValue: string;
  readonly isReload: boolean;
  readonly from: string;
  accept(promptText?: string): Promise<boolean>;
  dismiss(): Promise<boolean>;
}

export interface ExplorerDialogEvent extends Event {
  readonly detail: ExplorerDialogController;
}

export type ExplorerSurfaceRef = string & {
  readonly __tuffiteExplorerSurfaceRef: unique symbol;
};
export type ExplorerMessageTarget = "parent" | "top" | ExplorerSurfaceRef;

export interface NativeBridge extends EventTarget {
  invoke(channel: string, payload: Uint8Array): Promise<Uint8Array>;
  postMessage(
    data: unknown,
    options?: Readonly<{ to?: ExplorerMessageTarget }>,
  ): Promise<boolean>;
  addEventListener(
    type: "channel",
    listener: (event: ChannelEvent) => void,
    options?: boolean | AddEventListenerOptions,
  ): void;
  removeEventListener(
    type: "channel",
    listener: (event: ChannelEvent) => void,
    options?: boolean | EventListenerOptions,
  ): void;
  addEventListener(
    type: "message",
    listener: (event: ExplorerMessageEvent) => void,
    options?: boolean | AddEventListenerOptions,
  ): void;
  removeEventListener(
    type: "message",
    listener: (event: ExplorerMessageEvent) => void,
    options?: boolean | EventListenerOptions,
  ): void;
  addEventListener(
    type: "open" | "popup" | "newwindow" | "navigation",
    listener: (event: ExplorerOpenEvent) => void,
    options?: boolean | AddEventListenerOptions,
  ): void;
  removeEventListener(
    type: "open" | "popup" | "newwindow" | "navigation",
    listener: (event: ExplorerOpenEvent) => void,
    options?: boolean | EventListenerOptions,
  ): void;
  addEventListener(
    type: "dialog",
    listener: (event: ExplorerDialogEvent) => void,
    options?: boolean | AddEventListenerOptions,
  ): void;
  removeEventListener(
    type: "dialog",
    listener: (event: ExplorerDialogEvent) => void,
    options?: boolean | EventListenerOptions,
  ): void;
}

export type CommandEntry = readonly [
  path: string,
  id: string,
  schemaFingerprint: string,
  request: readonly Codec[],
  response: Codec,
];

export type ConstantEntry = readonly [path: string, value: unknown];

export function invokeBinary(
  channel: string,
  commandId: bigint,
  schemaFingerprint: bigint,
  payload?: Uint8Array,
): Promise<Uint8Array>;

export function createCommandApi(
  entries: readonly (readonly [path: string, id: bigint])[],
  typed?: boolean,
  rootTarget?: object,
  channelPrefix?: string,
): object;

export function createTypedCommandApi(
  entries: readonly CommandEntry[],
  constants?: readonly ConstantEntry[],
  namespace?: string,
): object;

export type FrameworkEntry = readonly [
  path: string,
  request: readonly Codec[],
  response: Codec,
];

export function createFrameworkApi(
  entries: readonly FrameworkEntry[],
  constants?: readonly ConstantEntry[],
): object;

export type ExplorerNavigationPolicy = "emit" | "allow";
export type ExplorerDialogPolicy = "emit" | "suppress";
export type ExplorerJavaScriptWorld = "isolated" | "main";
export type ExplorerPartitionMode = "shared" | "persist" | "memory";

export interface ExplorerNavigationState {
  readonly url: string;
  readonly title: string;
  readonly documentId: string;
  readonly canGoBack: boolean;
  readonly canGoForward: boolean;
  readonly isLoading: boolean;
  readonly rendererProcess: Readonly<{
    id: number;
    ownerId: number;
    isolated: boolean;
  }>;
  readonly storagePartition: Readonly<{
    domain: string;
    name: string;
    inMemory: boolean;
    isDefault: boolean;
    mode: ExplorerPartitionMode;
    shared: boolean;
    inherited: boolean;
    requested: string;
    createdDomain: string;
    createdName: string;
    createdInMemory: boolean;
    createdIsDefault: boolean;
  }>;
}

export interface ExplorerLoadErrorState extends ExplorerNavigationState {
  readonly errorCode: number;
  readonly errorDescription: string;
}

export interface ExplorerOpenDetail {
  readonly url: string;
  readonly disposition: string;
  readonly userGesture: boolean;
  readonly from: string;
}

export interface ExplorerDialogController {
  readonly type: "alert" | "confirm" | "prompt" | "beforeunload";
  readonly message: string;
  readonly defaultValue: string;
  readonly isReload: boolean;
  readonly from: string;
  accept(promptText?: string): Promise<boolean>;
  dismiss(): Promise<boolean>;
}

export type ExplorerTransferState = "pending" | "attaching" | "transferred" | "closed";

/** Pending resources are owned by the source document, independently of GC. */
export interface ExplorerTransfer extends EventTarget {
  readonly token: string;
  readonly state: ExplorerTransferState;
  close(): Promise<void>;
  onstatechange: ((event: Event) => void) | null;
}

export interface ExplorerEventMap {
  download: CustomEvent<ExplorerDownload>;
  attached: Event;
  detached: Event;
  loadstart: CustomEvent<ExplorerNavigationState>;
  loadstop: CustomEvent<ExplorerNavigationState>;
  loadcommit: CustomEvent<ExplorerNavigationState>;
  loaderror: CustomEvent<ExplorerLoadErrorState>;
  open: CustomEvent<ExplorerOpenDetail>;
  popup: CustomEvent<ExplorerOpenDetail>;
  newwindow: CustomEvent<ExplorerOpenDetail>;
  navigation: CustomEvent<ExplorerOpenDetail>;
  dialog: CustomEvent<ExplorerDialogController>;
  message: CustomEvent<unknown>;
}

export interface HTMLExplorerElement extends HTMLElement {
  src: string;
  /** Empty selects the parent's partition; `shared` is not an element value. */
  partition: string;
  navigation: ExplorerNavigationPolicy;
  dialogs: ExplorerDialogPolicy;
  contextMenuEnabled: boolean;
  deferred: boolean;
  detach(): Promise<ExplorerTransfer>;
  attach(token: string): Promise<void>;
  ondetached: ((event: Event) => void) | null;
  onattached: ((event: Event) => void) | null;
  /** Starts navigation; completion is reported by load events. */
  load(url: string): void;
  download(url: string): Promise<boolean>;
  getDownloads(): Promise<ExplorerDownload[]>;
  cancelDownload(id: number): Promise<boolean>;
  /** Base64 bytes of an owned completed download, bounded to 64 MiB. */
  readDownload(id: number): Promise<string>;
  /** A compositor PNG data URL, or an empty string when unavailable. */
  capturePreview(): Promise<string>;
  back(): Promise<boolean>;
  forward(): Promise<boolean>;
  go(offset: number): Promise<boolean>;
  reload(options?: Readonly<{ bypassCache?: boolean }>): Promise<boolean>;
  stop(): Promise<boolean>;
  getNavigationState(): Promise<ExplorerNavigationState>;
  /** The caller must validate the JSON-representable result at runtime. */
  executeJavaScript(
    source: string,
    options?: Readonly<{
      world?: ExplorerJavaScriptWorld;
      expectedDocumentId?: string;
    }>,
  ): Promise<unknown>;
  postMessage(data: unknown): Promise<boolean>;
  addEventListener<K extends keyof ExplorerEventMap>(
    type: K,
    listener: (this: HTMLExplorerElement, event: ExplorerEventMap[K]) => void,
    options?: boolean | AddEventListenerOptions,
  ): void;
  removeEventListener<K extends keyof ExplorerEventMap>(
    type: K,
    listener: (this: HTMLExplorerElement, event: ExplorerEventMap[K]) => void,
    options?: boolean | EventListenerOptions,
  ): void;
}

declare global {
  interface HTMLElementTagNameMap {
    explorer: HTMLExplorerElement;
  }
}

export type ExplorerDownload = {
  id: number;
  url: string;
  filename: string;
  path: string;
  mimeType: string;
  state: "in-progress" | "complete" | "cancelled" | "interrupted";
  receivedBytes: number;
  totalBytes: number;
  error: number;
  navigation: boolean;
};

export interface TuffiteViteOptions {
  manifest?: string;
  root?: string;
  static?: Readonly<Record<string, string>>;
  shellApi?: false | Readonly<{ url: string; file: string }>;
}

export function tuffite(options?: TuffiteViteOptions): import("vite").Plugin;
export function findManifest(start: string): string | undefined;
export function contentTypeForPath(path: string): string | undefined;
export function decodeRequestPath(requestUrl: string | undefined): string | undefined;
export function resolveConfinedFile(root: string, path: string): Promise<string | undefined>;

/** Filesystem roots accepted by path and fs APIs. */
export enum BaseDirectory {
  Resource = "resource",
  Data = "data",
  Cache = "cache",
  Temp = "temp",
}

export interface OpenFileDialogOptions {
  readonly title?: string;
  readonly defaultPath?: string;
  /** Extension groups without leading dots, for example [["html", "htm"], ["md"]]. */
  readonly extensions?: string[][];
}

export interface OpenDirectoryDialogOptions {
  readonly title?: string;
}

export declare namespace tuffite {
  export namespace dialog {
    export function openFile(options?: OpenFileDialogOptions): Promise<string | undefined>;
    export function openDirectory(options?: OpenDirectoryDialogOptions): Promise<string | undefined>;
  }
}

export declare namespace tuffite {
  export namespace fs {
    export function readFile(base: BaseDirectory, path: string): Promise<Uint8Array>;
    export function writeFile(
      base: BaseDirectory,
      path: string,
      contents: Uint8Array,
    ): Promise<void>;
    export function exists(base: BaseDirectory, path: string): Promise<boolean>;
    export function createDir(base: BaseDirectory, path: string): Promise<void>;
    export function removeFile(base: BaseDirectory, path: string): Promise<void>;
  }
}

export declare namespace tuffite {
  export namespace log {
    export function trace(message: string): Promise<void>;
    export function debug(message: string): Promise<void>;
    export function info(message: string): Promise<void>;
    export function warn(message: string): Promise<void>;
    export function error(message: string): Promise<void>;
  }
}

export interface NetworkResponse {
  readonly status: number;
  readonly body: Uint8Array;
}

export declare namespace tuffite {
  export namespace net {
    export function request(url: string): Promise<NetworkResponse>;
  }
}

export interface PathDirectories {
  readonly resource: string;
  readonly data: string;
  readonly cache: string;
  readonly temp: string;
}

export declare namespace tuffite {
  export namespace path {
    export function directories(): Promise<PathDirectories>;
    export function resolve(base: BaseDirectory, relative?: string): Promise<string>;
  }
}

export interface RemotingCapabilities {
  readonly available: boolean;
  readonly protocol: string;
  readonly videoCodecs: string[];
  readonly input: boolean;
  readonly clipboard: boolean;
  readonly reconnect: boolean;
  readonly snapshot: boolean;
}

export interface RemotingIceServer {
  readonly urls: string[];
  readonly username?: string;
  readonly credential?: string;
}

export interface RemotingStartOptions {
  /** Per-session secret supplied by the application's authenticated control plane. */
  readonly authKey: string;
  readonly iceServers: RemotingIceServer[];
  readonly maxBitrateKbps?: number;
  readonly targetFramerate?: number;
  readonly screenId?: bigint;
}

export interface RemotingSession {
  readonly id: bigint;
  readonly state: string;
}

export interface RemotingSessionDescription {
  readonly type: string;
  readonly sdp: string;
}

export interface RemotingIceCandidate {
  readonly mid: string;
  readonly mLineIndex: number;
  readonly candidate: string;
}

export interface RemotingSignal {
  readonly sequence: bigint;
  readonly description?: RemotingSessionDescription;
  readonly candidates: RemotingIceCandidate[];
}

export interface RemotingInputEvent {
  readonly kind: string;
  readonly pressed?: boolean;
  readonly usbKeycode?: number;
  readonly text?: string;
  readonly x?: number;
  readonly y?: number;
  readonly button?: string;
  readonly buttonDown?: boolean;
  readonly wheelDeltaX?: number;
  readonly wheelDeltaY?: number;
  readonly wheelTicksX?: number;
  readonly wheelTicksY?: number;
  readonly clipboardMimeType?: string;
  readonly clipboardData?: Uint8Array;
}

export interface RemotingStats {
  readonly state: string;
  readonly route: string;
  readonly transport: string;
  readonly latencyMs: number;
  readonly jitterMs: number;
  readonly availableBandwidthKbps: number;
  readonly packetLossPercent: number;
}

export interface RemotingSnapshot {
  readonly width: number;
  readonly height: number;
  readonly mimeType: string;
  readonly data: Uint8Array;
}

export declare namespace tuffite {
  export namespace remoting {
    export function capabilities(): Promise<RemotingCapabilities>;
    export function start(options: RemotingStartOptions): Promise<RemotingSession>;
    export function processSignal(id: bigint, signal: RemotingSignal): Promise<void>;
    export function takeSignals(id: bigint, afterSequence?: bigint): Promise<RemotingSignal[]>;
    export function sendInput(id: bigint, event: RemotingInputEvent): Promise<void>;
    export function stop(id: bigint): Promise<void>;
    export function stats(id: bigint): Promise<RemotingStats>;
    export function capture(screenId?: bigint): Promise<RemotingSnapshot>;
    /** Native application callers only; renderer calls are denied by routing policy. */
    export function injectInput(event: RemotingInputEvent): Promise<void>;
  }
}

export declare namespace tuffite {
  export namespace storage {
    export function get(key: string): Promise<Uint8Array | undefined>;
    export function set(key: string, value: Uint8Array): Promise<void>;
    export function remove(key: string): Promise<void>;
    export function clear(): Promise<void>;
  }
}

export declare namespace tuffite {
  export namespace utility {
    export function invoke(
      name: string,
      requestId: bigint,
      payload?: Uint8Array,
    ): Promise<Uint8Array>;
    export function cancel(name: string, requestId: bigint): Promise<void>;
  }
}

/** Opaque browser-process identifier. It is intentionally not a native handle. */
export type WindowId = bigint;

export interface WindowBounds {
  readonly x: number;
  readonly y: number;
  readonly width: number;
  readonly height: number;
}

export interface WindowInfo {
  readonly id: WindowId;
  readonly label: string;
  readonly title: string;
  readonly url: string;
  readonly bounds: WindowBounds;
  readonly focused: boolean;
  readonly minimized: boolean;
  readonly maximized: boolean;
  readonly fullscreen: boolean;
}

export interface WindowOptions {
  readonly label?: string;
  readonly url?: string;
  readonly title?: string;
  readonly bounds?: WindowBounds;
  readonly focused?: boolean;
}

export declare namespace tuffite {
  export namespace window {
    export function current(): Promise<WindowInfo>;
    export function list(): Promise<WindowInfo[]>;
    export function create(options?: WindowOptions): Promise<WindowInfo>;
    export function focus(id?: WindowId): Promise<WindowInfo>;
    export function minimize(id?: WindowId): Promise<WindowInfo>;
    export function maximize(id?: WindowId): Promise<WindowInfo>;
    export function restore(id?: WindowId): Promise<WindowInfo>;
    export function setFullscreen(fullscreen: boolean, id?: WindowId): Promise<WindowInfo>;
    export function close(id?: WindowId): Promise<void>;
    export function setTitle(title: string, id?: WindowId): Promise<WindowInfo>;
    export function getBounds(id?: WindowId): Promise<WindowBounds>;
    export function setBounds(bounds: WindowBounds, id?: WindowId): Promise<WindowInfo>;
  }
}