Skip to content

AI-native design editor. Open-source Figma alternative.

10.0 KB
Raw Blame
import { BROWSER_BASELINE } from './baseline'
import { baselineBrowserFor, type SupportEnvironment } from './detect'

/**
 * Copy for the pre-boot notice. It renders before Vue and the i18n catalogs
 * exist, so it is plain English by design.
 */
export interface SupportNotice {
  readonly heading: string
  readonly paragraphs: readonly string[]
  /** Technical facts shown behind a disclosure and prefilled into a bug report. */
  readonly details: readonly string[]
  readonly links: readonly SupportLink[]
}

export interface SupportLink {
  readonly label: string
  readonly url: string
}

export const SYSTEM_REQUIREMENTS_URL = 'https://openpencil.dev/getting-started#system-requirements'
export const WEBVIEW2_DOWNLOAD_URL = 'https://developer.microsoft.com/microsoft-edge/webview2/'
const ISSUE_URL = 'https://github.com/open-pencil/open-pencil/issues/new'

export const MINIMUM_MACOS_VERSION = 13
export const MINIMUM_WEBKITGTK_VERSION = '2.40'

const BROWSER_LABELS = {
  chrome: 'Chrome',
  edge: 'Edge',
  opera: 'Opera',
  firefox: 'Firefox',
  safari: 'Safari',
  unknown: 'this browser'
} as const

export function requirementsSentence(): string {
  const { chrome, edge, firefox, safari } = BROWSER_BASELINE
  return `OpenPencil needs Chrome ${chrome}, Edge ${edge}, Firefox ${firefox}, or Safari ${safari} or later.`
}

function majorVersion(version: string | undefined): number | undefined {
  if (!version) return undefined
  const major = Number.parseInt(version, 10)
  return Number.isFinite(major) ? major : undefined
}

function versionLabel(version: number): string {
  return Number.isInteger(version) ? String(version) : version.toFixed(1)
}

function environmentDetails(env: SupportEnvironment): string[] {
  const details = [`Host: ${env.host === 'desktop' ? 'desktop app' : 'browser'}`]
  details.push(`OS: ${env.os}${env.osVersion ? ` ${env.osVersion}` : ''}`)
  if (env.browserVersion !== undefined) {
    details.push(`Browser: ${BROWSER_LABELS[env.browser]} ${versionLabel(env.browserVersion)}`)
  }
  if (env.webviewVersion) details.push(`WebView: ${env.webviewVersion}`)
  details.push(`User agent: ${env.userAgent}`)
  return details
}

/** Option labels of the bug report form's Platform dropdown. */
const DESKTOP_ISSUE_PLATFORMS: Partial<Record<SupportEnvironment['os'], string>> = {
  macos: 'macOS (Tauri)',
  windows: 'Windows (Tauri)',
  linux: 'Linux (Tauri)'
}

function issuePlatform(env: SupportEnvironment): string {
  if (env.host === 'browser') return 'Web (app.openpencil.dev)'
  return DESKTOP_ISSUE_PLATFORMS[env.os] ?? 'Not sure'
}

function issueLink(
  env: SupportEnvironment,
  title: string,
  details: readonly string[]
): SupportLink {
  const params = new URLSearchParams({
    template: 'bug_report.yml',
    title,
    platform: issuePlatform(env),
    'affected-area': 'App UI',
    version: typeof __OPENPENCIL_APP_VERSION__ === 'string' ? __OPENPENCIL_APP_VERSION__ : '',
    browser: env.userAgent,
    logs: details.join('\n')
  })
  return { label: 'Report a problem', url: `${ISSUE_URL}?${params.toString()}` }
}

function requirementsLink(): SupportLink {
  return { label: 'System requirements', url: SYSTEM_REQUIREMENTS_URL }
}

interface Advice {
  heading: string
  paragraphs: string[]
  extraLinks?: SupportLink[]
}

function desktopAdvice(env: SupportEnvironment): Advice {
  switch (env.os) {
    case 'macos': {
      const major = majorVersion(env.osVersion)
      const running = env.osVersion ? `This Mac is running macOS ${env.osVersion}. ` : ''
      if (major !== undefined && major < MINIMUM_MACOS_VERSION) {
        return {
          heading: `OpenPencil needs macOS ${MINIMUM_MACOS_VERSION} or later`,
          paragraphs: [
            `${running}OpenPencil renders with the WebKit engine that ships with macOS, and this version is too old to run it. Upgrade to macOS ${MINIMUM_MACOS_VERSION} or later to use OpenPencil.`
          ]
        }
      }
      return {
        heading: 'Update macOS to run OpenPencil',
        paragraphs: [
          `${running}OpenPencil renders with the WebKit engine that ships with macOS, and this Mac's copy is older than Safari ${BROWSER_BASELINE.safari}.`,
          'Open System Settings → General → Software Update, install the available macOS and Safari updates, then reopen OpenPencil.'
        ]
      }
    }
    case 'linux':
      return {
        heading: 'Update WebKitGTK to run OpenPencil',
        paragraphs: [
          `OpenPencil renders with WebKitGTK${env.webviewVersion ? ` ${env.webviewVersion}` : ''}, which is too old.`,
          `Update the webkit2gtk-4.1 package to ${MINIMUM_WEBKITGTK_VERSION} or later with your distribution's package manager, then reopen OpenPencil.`
        ]
      }
    case 'windows':
      return {
        heading: 'Update WebView2 to run OpenPencil',
        paragraphs: [
          `OpenPencil renders with the Microsoft Edge WebView2 Runtime${env.webviewVersion ? ` ${env.webviewVersion}` : ''}, which is too old.`,
          'Install the latest Evergreen runtime from Microsoft, then reopen OpenPencil.'
        ],
        extraLinks: [{ label: 'Download WebView2', url: WEBVIEW2_DOWNLOAD_URL }]
      }
    default:
      return {
        heading: 'OpenPencil needs a newer WebView',
        paragraphs: [
          'The system WebView engine is too old to run OpenPencil. Install your operating system updates, then reopen OpenPencil.'
        ]
      }
  }
}

function browserUpdateSteps(env: SupportEnvironment): string {
  switch (env.browser) {
    case 'chrome':
      return 'Open the Chrome menu → Help → About Google Chrome to install the update.'
    case 'edge':
      return 'Open Settings and more → Help and feedback → About Microsoft Edge to install the update.'
    case 'opera':
      return 'Open the Opera menu → Update & Recovery to install the update.'
    case 'firefox':
      return 'Open the Firefox menu → Help → About Firefox to install the update.'
    case 'safari':
      return 'Update it through System Settings → General → Software Update, or open OpenPencil in a current Chrome, Edge, or Firefox.'
    default:
      return requirementsSentence()
  }
}

function browserAdvice(env: SupportEnvironment): Advice {
  if (env.os === 'ios') {
    return {
      heading: 'Update iOS to run OpenPencil',
      paragraphs: [
        `OpenPencil needs iOS ${BROWSER_BASELINE.ios} or later. Every browser on iPhone and iPad uses the system WebKit engine, so update in Settings → General → Software Update.`
      ]
    }
  }
  const baseline = baselineBrowserFor(env)
  if (baseline === undefined) {
    return {
      heading: "OpenPencil can't run in this browser",
      paragraphs: [requirementsSentence()]
    }
  }
  const label = BROWSER_LABELS[env.browser]
  const minimum = BROWSER_BASELINE[baseline]
  const detected =
    env.browserVersion === undefined
      ? ''
      : `${label} ${versionLabel(env.browserVersion)} detected. `
  const needs =
    env.browser === 'opera'
      ? `OpenPencil needs Opera built on Chrome ${minimum} or later.`
      : `OpenPencil needs ${label} ${minimum} or later.`
  return {
    heading: `Update ${label} to run OpenPencil`,
    paragraphs: [`${detected}${needs}`, browserUpdateSteps(env)]
  }
}

/** True when the UA claims a version at or above the baseline for its browser. */
function claimsSupportedVersion(env: SupportEnvironment): boolean {
  const baseline = baselineBrowserFor(env)
  return (
    baseline !== undefined &&
    env.browserVersion !== undefined &&
    env.browserVersion >= BROWSER_BASELINE[baseline]
  )
}

/** Notice for an engine that fails the support sentinels before boot. */
export function unsupportedNotice(
  env: SupportEnvironment,
  missing: readonly string[]
): SupportNotice {
  const details = [`Missing: ${missing.join(', ')}`, ...environmentDetails(env)]
  const report = issueLink(env, 'bug: unsupported browser notice shown', details)

  if (env.host === 'browser' && claimsSupportedVersion(env)) {
    return {
      heading: 'A required browser feature is unavailable',
      paragraphs: [
        `Your browser reports ${BROWSER_LABELS[env.browser]} ${versionLabel(env.browserVersion ?? 0)}, which should run OpenPencil, but it is missing ${missing.join(', ')}.`,
        'A browser policy, an extension, or a preview build may have disabled it. Try a current release of Chrome, Edge, Firefox, or Safari.'
      ],
      details,
      links: [requirementsLink(), report]
    }
  }

  const advice = env.host === 'desktop' ? desktopAdvice(env) : browserAdvice(env)
  return {
    heading: advice.heading,
    paragraphs: advice.paragraphs,
    details,
    links: [requirementsLink(), ...(advice.extraLinks ?? []), report]
  }
}

function errorDetails(error: unknown): string[] {
  if (!(error instanceof Error)) return [String(error)]
  const summary = `${error.name}: ${error.message}`
  const frames = (error.stack ?? '')
    .split('\n')
    // V8 repeats the summary as the first stack line; WebKit and Gecko do not.
    .filter((line, index) => line.trim() !== '' && !(index === 0 && line.trim() === summary))
    .slice(0, 8)
  return [summary, ...frames]
}

function bootFailureHint(env: SupportEnvironment): string {
  if (env.host === 'browser') return requirementsSentence()
  if (env.os === 'macos') {
    return 'OpenPencil renders with the WebKit engine that ships with macOS. If this Mac has pending macOS or Safari updates, install them first.'
  }
  return 'OpenPencil renders with the system WebView engine. If your operating system has pending updates, install them first.'
}

/** Notice for an app that failed while loading and left the window blank. */
export function bootFailureNotice(env: SupportEnvironment, error: unknown): SupportNotice {
  const details = [...errorDetails(error), ...environmentDetails(env)]
  return {
    heading: "OpenPencil couldn't start",
    paragraphs: [
      'Something failed while the app was loading, so nothing could be shown.',
      bootFailureHint(env),
      'If it keeps happening, report the problem and include the details below.'
    ],
    details,
    links: [requirementsLink(), issueLink(env, 'bug: app fails to start', details)]
  }
}