sailfork / t3code-github / apps/ desktop/ src/ snapShot/ LinuxSnapShot.ts

// @effect-diagnostics globalTimers:off -- D-Bus deadlines run at a native async boundary.
// @effect-diagnostics nodeBuiltinImport:off -- Read the portal file through one bounded file descriptor at the native adapter boundary.

import * as NodeCrypto from "node:crypto";
import {
  DBusError,
  Message,
  MessageFlag,
  MessageType,
  NameFlag,
  RequestNameReply,
  Variant,
  sessionBus,
  type MessageBus,
  type MessageLike,
} from "dbus-next";
import * as Schema from "effect/Schema";
import { isKdeCaptureSession, type KdeCapturePaths } from "./KdeSnapShot.ts";
import { isGnomeCaptureSession, readPortalPng, resizeLinuxCapture } from "./linuxCaptureSession.ts";
export { readPortalPng } from "./linuxCaptureSession.ts";
import { isHyprlandCaptureSession, type HyprlandCapturePaths } from "./HyprlandSnapShot.ts";

const PORTAL = "org.freedesktop.portal.Desktop";
const PORTAL_PATH = "/org/freedesktop/portal/desktop";
const SCREENSHOT = "org.freedesktop.portal.Screenshot";
const REQUEST = "org.freedesktop.portal.Request";
const EXTENSION = "org.gnome.Shell.Extensions.T3SnapShot";
const EXTENSION_PATH = "/org/gnome/Shell/Extensions/T3SnapShot";
const DBUS = "org.freedesktop.DBus";
const DBUS_PATH = "/org/freedesktop/DBus";
const UInt = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 0xffff_ffff }));
const UIntVariant = Schema.Struct({ signature: Schema.Literal("u"), value: UInt });
const StringVariant = Schema.Struct({ signature: Schema.Literal("s"), value: Schema.String });
const PortalProperties = Schema.Struct({
  version: UIntVariant,
  AvailableTargets: Schema.optional(UIntVariant),
});
const WindowMetadata = Schema.Struct({
  title: Schema.String,
  appName: Schema.String,
  appIdentifier: Schema.String,
  processId: UInt,
  bounds: Schema.Struct({
    x: Schema.Int,
    y: Schema.Int,
    width: Schema.Int.check(Schema.isGreaterThan(0)),
    height: Schema.Int.check(Schema.isGreaterThan(0)),
  }),
});
export type LinuxWindowMetadata = typeof WindowMetadata.Type & {
  readonly clientBounds?: typeof WindowMetadata.Type.bounds;
  readonly accessibilityBoundsReliable?: boolean;
};
const decodeProperties = Schema.decodeUnknownSync(PortalProperties);
const decodeExtension = Schema.decodeUnknownSync(Schema.Struct({ Version: UIntVariant }));
const decodeKde = Schema.decodeUnknownSync(Schema.Struct({ Version: UIntVariant }));
const decodeString = Schema.decodeUnknownSync(Schema.String);
const decodeBoolean = Schema.decodeUnknownSync(Schema.Boolean);
const decodeResponse = Schema.decodeUnknownSync(
  Schema.Tuple([UInt, Schema.Record(Schema.String, Schema.Unknown)]),
);
const decodeUri = Schema.decodeUnknownSync(StringVariant);
const decodeWindow = Schema.decodeUnknownSync(Schema.fromJsonString(WindowMetadata));
export type LinuxCaptureBackend =
  | "screenshot-portal"
  | "gnome-extension"
  | "niri"
  | "kde"
  | "hyprland"
  | "picker";
export type LinuxWindowSnapshot = {
  readonly png: Buffer;
  readonly window?: LinuxWindowMetadata;
  readonly feedback?: LinuxCaptureFeedback;
};

export type LinuxCaptureFeedback = {
  readonly animationStarted: boolean;
  readonly activate: (title: string) => Promise<void>;
  readonly animateTo: (frame: {
    x: number;
    y: number;
    width: number;
    height: number;
  }) => Promise<void>;
  readonly complete: () => Promise<void>;
  readonly close: () => void;
};
type FeedbackOptions = { readonly flash: boolean; readonly animate: boolean };

function unavailable(error: unknown): boolean {
  return (
    error instanceof DBusError &&
    ["ServiceUnknown", "NameHasNoOwner", "UnknownObject", "UnknownInterface", "UnknownMethod"].some(
      (name) => error.type === `${DBUS}.Error.${name}`,
    )
  );
}

/** One connection per operation: portal registration and request ownership stay together. */
class LinuxCaptureConnection {
  private readonly bus: MessageBus;
  private readonly disconnected: Promise<never>;
  private uniqueName = "";
  private extensionVersion = 0;
  private closed = false;
  private feedbackTimer: ReturnType<typeof setTimeout> | undefined;

  get feedbackAvailable() {
    return this.extensionVersion === 2;
  }

  constructor(bus = sessionBus()) {
    this.bus = bus;
    this.disconnected = new Promise((_, reject) => {
      bus.on("error", reject);
    });
    // A disconnect between calls must not become an unhandled rejection.
    void this.disconnected.catch(() => undefined);
  }

  close() {
    if (this.closed) return;
    this.closed = true;
    clearTimeout(this.feedbackTimer);
    this.bus.disconnect();
  }

  private async wait<T>(pending: Promise<T>, timeoutMs = 5_000): Promise<T> {
    let timer: ReturnType<typeof setTimeout> | undefined;
    try {
      return await Promise.race([
        pending,
        this.disconnected,
        new Promise<never>((_, reject) => {
          timer = setTimeout(() => reject(new Error("Snapshot timed out.")), timeoutMs);
        }),
      ]);
    } finally {
      clearTimeout(timer);
    }
  }

  private async call(message: MessageLike) {
    const reply = await this.wait(this.bus.call(new Message(message)));
    if (!reply) throw new Error("Missing D-Bus reply.");
    this.uniqueName = reply.destination;
    return reply;
  }

  private async properties(destination: string, path: string, iface: string) {
    const reply = await this.call({
      destination,
      path,
      interface: "org.freedesktop.DBus.Properties",
      member: "GetAll",
      signature: "s",
      body: [iface],
    });
    return reply.body[0] as unknown;
  }

  async backend(appId: string): Promise<LinuxCaptureBackend> {
    if (isKdeCaptureSession()) {
      const kde = await this.properties(
        "org.kde.KWin.ScreenShot2",
        "/org/kde/KWin/ScreenShot2",
        "org.kde.KWin.ScreenShot2",
      ).catch((error: unknown) => {
        if (!unavailable(error)) throw error;
        return undefined;
      });
      if (kde !== undefined && decodeKde(kde).Version.value >= 2) return "kde";
    }
    if (!process.env.FLATPAK_ID && !process.env.SNAP) {
      await this.call({
        destination: PORTAL,
        path: PORTAL_PATH,
        interface: "org.freedesktop.host.portal.Registry",
        member: "Register",
        signature: "sa{sv}",
        body: [appId, {}],
      }).catch((error: unknown) => {
        if (!unavailable(error)) throw error;
      });
    }
    const properties = await this.properties(PORTAL, PORTAL_PATH, SCREENSHOT).catch(
      (error: unknown) => {
        if (!unavailable(error)) throw error;
        return undefined;
      },
    );
    if (properties !== undefined) {
      const parsed = decodeProperties(properties);
      if (parsed.version.value >= 3 && ((parsed.AvailableTargets?.value ?? 0) & 8) !== 0) {
        return "screenshot-portal";
      }
    }
    if (!isGnomeCaptureSession(process.env)) return "picker";
    const extension = await this.properties(EXTENSION, EXTENSION_PATH, EXTENSION).catch(
      (error: unknown) => {
        if (!unavailable(error)) throw error;
        return undefined;
      },
    );
    if (extension !== undefined) {
      const parsed = decodeExtension(extension);
      this.extensionVersion = parsed.Version.value;
      if (this.extensionVersion === 1 || this.extensionVersion === 2) return "gnome-extension";
    }
    return "picker";
  }

  async capturePortal(): Promise<LinuxWindowSnapshot> {
    const owner = await this.call({
      destination: DBUS,
      path: DBUS_PATH,
      interface: DBUS,
      member: "GetNameOwner",
      signature: "s",
      body: [PORTAL],
    });
    const sender = decodeString(owner.body[0]);
    const token = `t3_${NodeCrypto.randomUUID().replaceAll("-", "")}`;
    const namespace = `${PORTAL_PATH}/request/${this.uniqueName.slice(1).replaceAll(".", "_")}/`;
    let handle = namespace + token;
    let completed = false;
    // Subscribe before Screenshot: the response may precede its method reply.
    const responses = new Map<string, unknown>();
    let deliver: ((body: unknown) => void) | undefined;
    const listener = (message: Message) => {
      if (
        message.type !== MessageType.SIGNAL ||
        message.sender !== sender ||
        message.interface !== REQUEST ||
        message.member !== "Response" ||
        !message.path.startsWith(namespace)
      )
        return;
      if (deliver && message.path === handle) deliver(message.body);
      else if (responses.size < 8) responses.set(message.path, message.body);
    };
    this.bus.on("message", listener);
    try {
      await this.call({
        destination: DBUS,
        path: DBUS_PATH,
        interface: DBUS,
        member: "AddMatch",
        signature: "s",
        body: [
          `type='signal',sender='${sender}',interface='${REQUEST}',member='Response',path_namespace='${namespace.slice(0, -1)}'`,
        ],
      });
      const reply = await this.call({
        destination: sender,
        path: PORTAL_PATH,
        interface: SCREENSHOT,
        member: "Screenshot",
        signature: "sa{sv}",
        body: [
          "",
          {
            handle_token: new Variant("s", token),
            interactive: new Variant("b", false),
            modal: new Variant("b", false),
            target: new Variant("u", 8),
          },
        ],
      });
      handle = decodeString(reply.body[0]);
      if (!handle.startsWith(namespace)) throw new Error("Invalid screenshot request handle.");
      const body = await this.wait(
        new Promise<unknown>((resolve) => {
          deliver = resolve;
          if (responses.has(handle)) resolve(responses.get(handle));
        }),
        120_000,
      );
      const [status, results] = decodeResponse(body);
      completed = true;
      if (status === 1) throw new Error("Snapshot was cancelled.");
      if (status !== 0) throw new Error("Your desktop did not allow the snapshot.");
      const uri = decodeUri(results.uri).value;
      return { png: await readPortalPng(uri) };
    } finally {
      this.bus.removeListener("message", listener);
      if (!completed) {
        this.bus.send(
          new Message({
            destination: sender,
            path: handle,
            interface: REQUEST,
            member: "Close",
            flags: MessageFlag.NO_REPLY_EXPECTED,
          }),
        );
      }
    }
  }

  async captureExtension(appId: string, options?: FeedbackOptions): Promise<LinuxWindowSnapshot> {
    const result = await this.wait(
      this.bus.requestName(`${appId}.SnapShot`, NameFlag.DO_NOT_QUEUE),
    );
    if (result !== RequestNameReply.PRIMARY_OWNER) {
      throw new Error("Another T3 Code instance is capturing a window. Try again.");
    }
    const withFeedback = this.feedbackAvailable && options !== undefined;
    const reply = await this.call({
      destination: EXTENSION,
      path: EXTENSION_PATH,
      interface: EXTENSION,
      member: withFeedback ? "CaptureWithFeedback" : "Capture",
      ...(withFeedback ? { signature: "bb", body: [options.flash, options.animate] } : {}),
    });
    const bytes: unknown = reply.body[0];
    if (!(bytes instanceof Uint8Array)) throw new Error("Invalid extension screenshot.");
    const window = decodeWindow(reply.body[1]);
    const png = resizeLinuxCapture(Buffer.from(bytes));
    if (!withFeedback) return { png, window };
    const animationStarted = decodeBoolean(reply.body[2]);
    // Keep the same authenticated sender alive through activation and the compositor flight.
    this.feedbackTimer = setTimeout(() => this.close(), 15_000);
    let flight: Promise<void> | undefined;
    const feedback: LinuxCaptureFeedback = {
      animationStarted,
      activate: async (title) => {
        await this.feedbackCall("Activate", "s", [title]);
      },
      animateTo: (frame) => {
        flight ??= this.feedbackCall("Animate", "dddd", [
          frame.x,
          frame.y,
          frame.width,
          frame.height,
        ]);
        return flight;
      },
      complete: async () => {
        try {
          await flight;
        } finally {
          this.close();
        }
      },
      close: () => this.close(),
    };
    return { png, window, feedback };
  }

  private async feedbackCall(member: string, signature: string, body: unknown[]): Promise<void> {
    if (this.closed) return;
    await this.call({
      destination: EXTENSION,
      path: EXTENSION_PATH,
      interface: EXTENSION,
      member,
      signature,
      body,
    });
  }
}

export async function getLinuxCaptureSupport(appId: string) {
  if (isHyprlandCaptureSession())
    return { linuxBackend: "hyprland" as const, linuxFeedbackAvailable: false };
  const { niriSocketPath, checkNiriCaptureSupport } = await import("./NiriSnapShot.ts");
  const niri = niriSocketPath();
  if (niri) {
    await checkNiriCaptureSupport(niri);
    return { linuxBackend: "niri" as const, linuxFeedbackAvailable: false };
  }
  const connection = new LinuxCaptureConnection();
  try {
    const linuxBackend = await connection.backend(appId);
    return { linuxBackend, linuxFeedbackAvailable: connection.feedbackAvailable };
  } finally {
    connection.close();
  }
}

/** Undefined means capability missing, not denied: only that case may open the picker. */
export async function captureLinuxWindow(
  appId: string,
  options?: FeedbackOptions,
  kdePaths?: KdeCapturePaths,
  hyprlandPaths?: HyprlandCapturePaths,
): Promise<LinuxWindowSnapshot | undefined> {
  if (isHyprlandCaptureSession()) {
    if (!hyprlandPaths) throw new Error("Hyprland capture setup is unavailable in this build.");
    const { captureHyprlandWindow } = await import("./HyprlandSnapShot.ts");
    return captureHyprlandWindow(hyprlandPaths, options);
  }
  const { niriSocketPath, captureNiriWindow } = await import("./NiriSnapShot.ts");
  const niri = niriSocketPath();
  if (niri) return captureNiriWindow(niri);
  const connection = new LinuxCaptureConnection();
  let retained = false;
  try {
    switch (await connection.backend(appId)) {
      case "kde": {
        if (!kdePaths) throw new Error("KDE capture setup is unavailable in this build.");
        const { captureKdeWindow } = await import("./KdeSnapShot.ts");
        return await captureKdeWindow(kdePaths, options);
      }
      case "screenshot-portal":
        return await connection.capturePortal();
      case "gnome-extension": {
        const snapshot = await connection.captureExtension(appId, options);
        retained = snapshot.feedback !== undefined;
        return snapshot;
      }
      case "picker":
        return undefined;
    }
  } finally {
    if (!retained) connection.close();
  }
}