orca/src/shared/window-material.ts

/** What sits behind the main window's translucent surfaces: nothing, the desktop, or the blurred desktop. */
export type WindowMaterial = 'off' | 'translucent' | 'blur'

const WINDOW_MATERIAL_ARGUMENT_PREFIX = '--orca-window-material='

export type WindowMaterialSettings = {
  /** Main-window backdrop shown through translucent terminals; creation-time, so changes need a restart. */
  windowMaterial?: WindowMaterial
  /** Legacy switch, read only when `windowMaterial` is unset (see windowMaterialPreference). */
  windowBackgroundBlur?: boolean
  /** Drops modal/backdrop blur and the window material for remote or GPU-less sessions (#20936). */
  reduceVisualEffects?: boolean
}

type WindowMaterialInputs = WindowMaterialSettings & { terminalBackgroundOpacity?: number }

function isWindowMaterial(value: unknown): value is WindowMaterial {
  return value === 'off' || value === 'translucent' || value === 'blur'
}

/** The user's choice. Profiles from before `windowMaterial` carry it in the legacy blur switch,
 *  which never did anything on Linux, so it is not promoted to a transparent window there. */
export function windowMaterialPreference(
  settings: WindowMaterialInputs,
  platform: NodeJS.Platform
): WindowMaterial {
  if (isWindowMaterial(settings.windowMaterial)) {
    return settings.windowMaterial
  }
  return settings.windowBackgroundBlur === true && platform !== 'linux' ? 'blur' : 'off'
}

/** Where the window runs; Windows release strings look like `10.0.22631`. */
export type WindowMaterialHost = { platform: NodeJS.Platform; osRelease: string }

// Why: DWM system backdrops (acrylic) exist from Windows 11 22H2 (build 22621); earlier builds would show black.
const WINDOWS_BACKDROP_MIN_BUILD = 22621

/** Materials each host can render: Windows has no unblurred transparency, Linux compositors own blur. */
export function selectableWindowMaterials(host: WindowMaterialHost): readonly WindowMaterial[] {
  if (host.platform === 'darwin') {
    return ['off', 'translucent', 'blur']
  }
  if (host.platform === 'win32') {
    const build = Number(host.osRelease.split('.')[2])
    return build >= WINDOWS_BACKDROP_MIN_BUILD ? ['off', 'blur'] : ['off']
  }
  return ['off', 'translucent']
}

/** Maps a stored choice onto what this host renders, e.g. a macOS profile opened on Linux. */
export function hostWindowMaterial(
  material: WindowMaterial,
  host: WindowMaterialHost
): WindowMaterial {
  const selectable = selectableWindowMaterials(host)
  if (selectable.includes(material)) {
    return material
  }
  // Why only blur degrades: unblurred see-through never silently becomes a blur effect.
  return material === 'blur' && selectable.includes('translucent') ? 'translucent' : 'off'
}

/**
 * The material the main window is created with. Off unless a surface actually shows through:
 * an occluded vibrancy or alpha window still costs WindowServer composition every frame (#8482).
 */
export function resolveWindowMaterial(
  settings: WindowMaterialInputs | null | undefined,
  host: WindowMaterialHost,
  prefersReducedTransparency: boolean
): WindowMaterial {
  if (!settings || settings.reduceVisualEffects === true || prefersReducedTransparency) {
    return 'off'
  }
  const opacity = settings.terminalBackgroundOpacity
  if (opacity === undefined || !(opacity < 1)) {
    return 'off'
  }
  return hostWindowMaterial(windowMaterialPreference(settings, host.platform), host)
}

export function formatWindowMaterialArgument(material: WindowMaterial): string {
  return `${WINDOW_MATERIAL_ARGUMENT_PREFIX}${material}`
}

/** Read once by the renderer: the material is fixed when the window is created. */
export function parseWindowMaterialArgument(argv: readonly string[]): WindowMaterial {
  const value = argv
    .find((arg) => arg.startsWith(WINDOW_MATERIAL_ARGUMENT_PREFIX))
    ?.slice(WINDOW_MATERIAL_ARGUMENT_PREFIX.length)
  return isWindowMaterial(value) ? value : 'off'
}