@sixb/desktop 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,177 @@
+import { mkdir, readdir, rm } from "node:fs/promises"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { type DesktopAppOptions, desktopDir, writeDesktopApp } from "./generate"
+import { bundleIdentifier } from "./identity"
+import { run } from "./run"
+
+export type { DesktopAppOptions } from "./generate"
+
+export interface DesktopWindow {
+  /** Resolves with Electron's exit code once the user quits it. */
+  readonly exited: Promise<number>
+  close(): void
+}
+
+export interface DesktopBuild {
+  /** What to hand to users: a zip of the app on macOS, the app's folder elsewhere. */
+  readonly path: string
+  /** Whether it was signed and notarized, and so opens without a warning. */
+  readonly signed: boolean
+}
+
+const packageRequire = createRequire(import.meta.url)
+// From the package's `src`, like the shell: see `SHELL_SOURCE_DIR`.
+const PACKAGER_SCRIPT = fileURLToPath(new URL("../src/packager.mjs", import.meta.url))
+
+/** Opens the app in a desktop window. `sixb dev --desktop` calls this. */
+export async function openDesktopApp(options: DesktopAppOptions): Promise<DesktopWindow> {
+  const app = await writeDesktopApp(options)
+  // Chromium writes plenty to stderr when all is well, so it goes to a file, named if the window
+  // quits on its own with an error.
+  const log = join(dirname(app.dir), "electron.log")
+  const electron = Bun.spawn([electronBinary(), app.dir], {
+    stdio: ["ignore", "ignore", Bun.file(log)],
+  })
+  let closing = false
+  const exited = electron.exited.then((code) => {
+    if (code !== 0 && !closing) {
+      console.error(`[SixbDesktop] The desktop window quit with exit code ${code}. See ${log}.`)
+    }
+    return code
+  })
+  return {
+    exited,
+    close: () => {
+      closing = true
+      electron.kill()
+    },
+  }
+}
+
+/** Packages the app for this machine's platform. `sixb desktop build` calls this. */
+export async function buildDesktopApp(options: DesktopAppOptions): Promise<DesktopBuild> {
+  const app = await writeDesktopApp(options)
+  const out = desktopDir(options.projectRoot, "dist")
+  await rm(out, { recursive: true, force: true })
+
+  const mac = process.platform === "darwin"
+  const notarize = mac ? appleNotarization() : null
+  const packaged = await packageApp({
+    dir: app.dir,
+    name: app.name,
+    out,
+    appBundleId: bundleIdentifier(options.appUrl),
+    appVersion: app.version,
+    electronVersion: (packageRequire("electron/package.json") as { readonly version: string })
+      .version,
+    ...(mac && app.icon ? { icon: await macIcon(app.icon) } : {}),
+    // Signs with the Developer ID certificate in the keychain, which notarization requires.
+    ...(notarize ? { osxSign: {}, osxNotarize: notarize } : {}),
+  })
+  if (!mac) return { path: packaged, signed: false }
+
+  const name = (await readdir(packaged)).find((entry) => entry.endsWith(".app"))
+  if (!name) throw new Error(`[SixbDesktop] The packaged app is missing from ${packaged}.`)
+  const bundle = join(packaged, name)
+  // Packaging breaks the ad-hoc signature Electron ships with. macOS calls a downloaded app with a
+  // broken signature damaged, and offers no way to open it; signed ad hoc, it can be allowed.
+  if (!notarize) {
+    await run(["codesign", "--force", "--deep", "--sign", "-", bundle], "Could not sign the app.")
+  }
+  // `ditto`, not `zip`: it keeps the bundle's symlinks, and with them its signature.
+  const zip = `${packaged}.zip`
+  await run(["ditto", "-c", "-k", "--keepParent", bundle, zip], "Could not zip the app.")
+  return { path: zip, signed: notarize !== null }
+}
+
+/**
+ * An App Store Connect API key, which notarizes the app so macOS opens it without a warning.
+ * Without one, the app is built unsigned.
+ */
+function appleNotarization(): {
+  readonly appleApiKey: string
+  readonly appleApiKeyId: string
+  readonly appleApiIssuer: string
+} | null {
+  const { APPLE_API_KEY, APPLE_API_KEY_ID, APPLE_API_ISSUER } = process.env
+  if (!APPLE_API_KEY && !APPLE_API_KEY_ID && !APPLE_API_ISSUER) return null
+  if (!APPLE_API_KEY || !APPLE_API_KEY_ID || !APPLE_API_ISSUER) {
+    throw new Error(
+      "[SixbDesktop] Set all of APPLE_API_KEY, APPLE_API_KEY_ID and APPLE_API_ISSUER to sign the " +
+        "macOS app, or none of them to build it unsigned."
+    )
+  }
+  return {
+    appleApiKey: APPLE_API_KEY,
+    appleApiKeyId: APPLE_API_KEY_ID,
+    appleApiIssuer: APPLE_API_ISSUER,
+  }
+}
+
+/**
+ * The packager wants `.icns`: every size macOS shows, scaled from the 1024-pixel icon, in one file.
+ * `sips` and `iconutil` ship with every Mac. Written beside the app, not in it: everything in the
+ * app's directory ships inside the bundle.
+ */
+async function macIcon(png: string): Promise<string> {
+  const desktop = dirname(dirname(png))
+  const iconset = join(desktop, "icon.iconset")
+  await rm(iconset, { recursive: true, force: true })
+  await mkdir(iconset)
+  const sizes = [16, 32, 128, 256, 512].flatMap((points) => [
+    { name: `icon_${points}x${points}.png`, pixels: points },
+    { name: `icon_${points}x${points}@2x.png`, pixels: points * 2 },
+  ])
+  await Promise.all(
+    sizes.map(({ name, pixels }) =>
+      run(
+        ["sips", "-z", `${pixels}`, `${pixels}`, png, "--out", join(iconset, name)],
+        "Could not scale the icon."
+      )
+    )
+  )
+  const icns = join(desktop, "icon.icns")
+  await run(["iconutil", "-c", "icns", iconset, "-o", icns], "Could not convert the icon.")
+  return icns
+}
+
+/**
+ * Runs `@electron/packager` into `options.out`, which starts empty, and resolves with the one
+ * directory it wrote there. Under Electron's own binary, which doubles as the Node the packager was
+ * written for: under Bun, the packager fails whenever it verifies a download (its checksum
+ * dependency does not load).
+ */
+async function packageApp(
+  options: { readonly out: string } & Record<string, unknown>
+): Promise<string> {
+  const packager = Bun.spawn(
+    [electronBinary(), PACKAGER_SCRIPT, JSON.stringify({ ...options, quiet: true })],
+    {
+      stdio: ["ignore", "inherit", "inherit"],
+      // Without the second, Electron's file system reads the `app.asar` the packager writes as a
+      // directory.
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: "1", ELECTRON_NO_ASAR: "1" },
+    }
+  )
+  if ((await packager.exited) !== 0) {
+    throw new Error("[SixbDesktop] Packaging failed. See the output above.")
+  }
+  const [written] = await readdir(options.out)
+  if (!written) throw new Error(`[SixbDesktop] The packager wrote nothing to ${options.out}.`)
+  return join(options.out, written)
+}
+
+// Outside Electron, `require("electron")` is the path of the binary its install script fetched.
+function electronBinary(): string {
+  try {
+    return packageRequire("electron") as string
+  } catch {
+    const electronDir = dirname(packageRequire.resolve("electron/package.json"))
+    throw new Error(
+      "[SixbDesktop] Electron's binary is missing: its install script did not run. " +
+        `Run \`bun run --cwd ${electronDir} postinstall\`, then try again.`
+    )
+  }
+}

package/src/mac-icon.ts

@@ -0,0 +1,81 @@
+import { run } from "./run"
+
+/**
+ * Draws `png` the way macOS draws app icons, into `out`: on Apple's grid, a rounded square of 824
+ * pixels with continuous corners in a canvas of 1024, over the soft shadow Apple's own icons have.
+ * An icon drawn to its edges otherwise stands larger than every other icon in the Dock.
+ */
+export async function drawMacIcon(png: string, out: string): Promise<void> {
+  await run(
+    ["osascript", "-l", "JavaScript", "-e", MAC_ICON_SCRIPT, png, out],
+    "Could not draw the macOS icon."
+  )
+}
+
+// AppKit, through the JavaScript `osascript` runs, which every Mac has. The corner is the curve
+// UIKit rounds continuous corners with; with this radius it matches the outline of Apple's Notes
+// icon to a few pixels, and the shadow matches its shadow.
+const MAC_ICON_SCRIPT = `
+ObjC.import("AppKit")
+ObjC.import("CoreGraphics")
+
+function run([input, output]) {
+  const canvas = 1024
+  const body = 824
+  const radius = 185.4
+  const min = (canvas - body) / 2
+  const max = min + body
+
+  // One corner, as offsets in radii from the edge it leaves and the edge it joins.
+  const corner = [
+    [[1.52866483, 0]],
+    [[0.66993427, 0.065496], [1.08849323, 0], [0.86840689, 0.02065986]],
+    [[0.63149399, 0.074911]],
+    [[0.074911, 0.63149399], [0.37282392, 0.16906933], [0.16906933, 0.37282392]],
+    [[0.065496, 0.66993427]],
+    [[0, 1.52866483], [0.02065986, 0.86840689], [0, 1.08849323]],
+  ]
+  const corners = [
+    ([u, v]) => $.NSMakePoint(max - u * radius, max - v * radius),
+    ([u, v]) => $.NSMakePoint(max - v * radius, min + u * radius),
+    ([u, v]) => $.NSMakePoint(min + u * radius, min + v * radius),
+    ([u, v]) => $.NSMakePoint(min + v * radius, max - u * radius),
+  ]
+  const shape = $.NSBezierPath.bezierPath
+  shape.moveToPoint(corners[3]([0, 1.52866483]))
+  for (const at of corners) {
+    for (const [to, c1, c2] of corner) {
+      if (c1) shape.curveToPointControlPoint1ControlPoint2(at(to), at(c1), at(c2))
+      else shape.lineToPoint(at(to))
+    }
+  }
+  shape.closePath
+
+  const image = $.NSImage.alloc.initWithContentsOfFile(input)
+  if (image.isNil()) throw new Error("Cannot read " + input)
+  const bitmap = $.NSBitmapImageRep.alloc
+    .initWithBitmapDataPlanesPixelsWidePixelsHighBitsPerSampleSamplesPerPixelHasAlphaIsPlanarColorSpaceNameBytesPerRowBitsPerPixel(
+      null, canvas, canvas, 8, 4, true, false, $.NSDeviceRGBColorSpace, 0, 0
+    )
+  const context = $.NSGraphicsContext.graphicsContextWithBitmapImageRep(bitmap)
+  $.NSGraphicsContext.setCurrentContext(context)
+  context.setImageInterpolation($.NSImageInterpolationHigh)
+
+  const shadow = $.NSShadow.alloc.init
+  shadow.setShadowOffset($.NSMakeSize(0, -8))
+  shadow.setShadowBlurRadius(30)
+  shadow.setShadowColor($.NSColor.colorWithWhiteAlpha(0, 0.22))
+  shadow.set
+  // A layer, so the shadow falls from the clipped icon and not from the clip.
+  $.CGContextBeginTransparencyLayer(context.CGContext, null)
+  shape.addClip
+  image.drawInRectFromRectOperationFraction(
+    $.NSMakeRect(min, min, body, body), $.NSZeroRect, $.NSCompositingOperationSourceOver, 1
+  )
+  $.CGContextEndTransparencyLayer(context.CGContext)
+  context.flushGraphics
+
+  const png = bitmap.representationUsingTypeProperties($.NSBitmapImageFileTypePNG, $.NSDictionary.dictionary)
+  if (!png.writeToFileAtomically(output, true)) throw new Error("Cannot write " + output)
+}
+`

package/src/packager.mjs

@@ -0,0 +1,5 @@
+// Runs `@electron/packager` with the options `buildDesktopApp` passes as JSON. Started under
+// Electron's own Node, not Bun: see `packageApp`.
+import { packager } from "@electron/packager"
+
+await packager(JSON.parse(process.argv[2]))

package/src/run.ts

@@ -0,0 +1,11 @@
+/** Runs a command to completion, quietly unless it fails: then it throws `failure` and its errors. */
+export async function run(command: readonly string[], failure: string): Promise<void> {
+  const child = Bun.spawn([...command], {
+    stdio: ["ignore", "ignore", "pipe"],
+    timeout: 120_000,
+  })
+  const [exitCode, errors] = await Promise.all([child.exited, new Response(child.stderr).text()])
+  if (exitCode !== 0) {
+    throw new Error(`[SixbDesktop] ${failure}${errors.trim() ? `\n${errors.trim()}` : ""}`)
+  }
+}

package/src/shell/index.html

@@ -0,0 +1,204 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{name}}</title>
+    <style>
+      /* The colors mirror packages/ui/src/styles/globals.css, so the app replaces this page
+         without a change of tone. `WINDOW_BACKGROUND` in window.ts repeats --background. */
+      :root {
+        color-scheme: light dark;
+        --background: #fafafa;
+        --foreground: #101010;
+        --primary: #0a0a0a;
+        --primary-foreground: #ffffff;
+        --muted-foreground: #5f5f5f;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --background: #0a0a0a;
+          --foreground: #f4f4f4;
+          --primary: #f4f4f4;
+          --primary-foreground: #0a0a0a;
+          --muted-foreground: #8a8a8a;
+        }
+      }
+      * {
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        height: 100%;
+      }
+      body {
+        margin: 0;
+        /* Sits a little above dead-center. */
+        padding-bottom: 8vh;
+        display: grid;
+        place-items: center;
+        font-family: "SF Pro Text", "Segoe UI Variable Text", "Segoe UI", system-ui, sans-serif;
+        background: var(--background);
+        color: var(--foreground);
+        -webkit-font-smoothing: antialiased;
+        /* Nothing here is a document: the whole page moves the window, and no text selects. */
+        -webkit-app-region: drag;
+        user-select: none;
+        cursor: default;
+      }
+      main {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        animation: enter 0.5s cubic-bezier(0.2, 0.8, 0.2, 1) both;
+      }
+      .mark {
+        display: grid;
+        place-items: center;
+        width: 3.5rem;
+        height: 3.5rem;
+        border-radius: 0.875rem;
+        background: var(--primary);
+        color: var(--primary-foreground);
+        font-size: 1.5rem;
+        font-weight: 600;
+        letter-spacing: -0.02em;
+        box-shadow:
+          0 1px 1px rgb(0 0 0 / 0.06),
+          0 12px 28px -12px rgb(0 0 0 / 0.35);
+      }
+      @media (prefers-color-scheme: dark) {
+        /* A shadow on black is only a smudge around the mark. */
+        .mark {
+          box-shadow: none;
+        }
+      }
+      /* The app's own icon brings its own shape. */
+      img.mark {
+        width: 4rem;
+        height: 4rem;
+        border-radius: 0;
+        background: none;
+        box-shadow: none;
+      }
+      h1 {
+        margin: 1.125rem 0 0;
+        font-size: 1.0625rem;
+        font-weight: 600;
+        letter-spacing: -0.01em;
+      }
+      /* One fixed height for both states, so the name does not move when one replaces the other. */
+      .status {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        height: 4.5rem;
+        margin-top: 1.25rem;
+      }
+      p {
+        margin: 0;
+        font-size: 0.8125rem;
+        color: var(--muted-foreground);
+      }
+      .progress {
+        position: relative;
+        width: 5rem;
+        height: 3px;
+        border-radius: 3px;
+        overflow: hidden;
+        background: color-mix(in srgb, var(--foreground) 10%, transparent);
+      }
+      .progress::after {
+        content: "";
+        position: absolute;
+        inset: 0;
+        width: 40%;
+        border-radius: inherit;
+        background: var(--foreground);
+        animation: slide 1.3s cubic-bezier(0.65, 0, 0.35, 1) infinite;
+      }
+      /* A quick load never gets as far as words; a slow one says what it is waiting for. */
+      #connecting p {
+        margin-top: 1rem;
+        opacity: 0;
+        animation: appear 0.4s ease 2.5s forwards;
+      }
+      #unreachable a {
+        display: inline-flex;
+        align-items: center;
+        height: 2rem;
+        margin-top: 0.875rem;
+        padding: 0 0.875rem;
+        border-radius: 0.375rem;
+        background: var(--primary);
+        color: var(--primary-foreground);
+        font-size: 0.8125rem;
+        font-weight: 500;
+        text-decoration: none;
+        cursor: pointer;
+        -webkit-app-region: no-drag;
+      }
+      #unreachable a:hover {
+        opacity: 0.9;
+      }
+      #unreachable a:focus-visible {
+        outline: 2px solid var(--primary);
+        outline-offset: 2px;
+      }
+      /* The shell reopens this page at #unreachable when the app's server does not answer. It is
+         the same page a moment later, so it does not make its entrance twice. */
+      #unreachable:not(:target),
+      :root:has(#unreachable:target) #connecting {
+        display: none;
+      }
+      :root:has(#unreachable:target) main {
+        animation: none;
+      }
+      @keyframes enter {
+        from {
+          opacity: 0;
+          transform: translateY(4px);
+        }
+      }
+      @keyframes appear {
+        to {
+          opacity: 1;
+        }
+      }
+      @keyframes slide {
+        from {
+          transform: translateX(-100%);
+        }
+        to {
+          transform: translateX(250%);
+        }
+      }
+      @media (prefers-reduced-motion: reduce) {
+        main,
+        #connecting p {
+          animation: none;
+          opacity: 1;
+        }
+        .progress::after {
+          animation: none;
+          width: 100%;
+          opacity: 0.35;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      {{mark}}
+      <h1>{{name}}</h1>
+      <div class="status" id="connecting">
+        <div class="progress"></div>
+        <p role="status">Connecting to {{host}}&hellip;</p>
+      </div>
+      <div class="status" id="unreachable">
+        <p>Can&rsquo;t reach {{host}}</p>
+        <a href="{{appUrl}}">Try again</a>
+      </div>
+    </main>
+  </body>
+</html>

package/src/shell/main.ts

@@ -0,0 +1,107 @@
+// The desktop shell's main process. `writeDesktopApp` compiles this file into the generated
+// Electron app; nothing imports it.
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { app, BrowserWindow, type Event, nativeTheme, session, shell } from "electron"
+import { createNavigationState, isWebUrl, nextNavigationStep, type ShellConfig } from "./navigation"
+import { HIDDEN_TITLE_BAR_CSS, isAppUrl, mayNavigate, WINDOW_BACKGROUND } from "./window"
+
+// Chromium's code for a load that was replaced by another one, which is not a failure.
+const ERR_ABORTED = -3
+
+// Not `__dirname`: the bundler replaces it with this source file's directory at compile time,
+// which is not where the compiled app lives.
+const appDir = app.getAppPath()
+const config = JSON.parse(readFileSync(join(appDir, "shell.json"), "utf-8")) as ShellConfig
+const loadingPage = join(appDir, "index.html")
+const icon = existsSync(join(appDir, "icon.png")) ? join(appDir, "icon.png") : undefined
+// Only macOS draws window controls over the page; elsewhere the title bar stays.
+const inset = process.platform === "darwin"
+const state = createNavigationState()
+
+app.setName(config.name)
+
+function createWindow(): void {
+  const win = new BrowserWindow({
+    title: config.name,
+    width: 1280,
+    height: 832,
+    titleBarStyle: inset ? "hiddenInset" : "default",
+    icon,
+    // Opens once the loading page has painted, over a background of that page's color.
+    show: false,
+    backgroundColor: nativeTheme.shouldUseDarkColors
+      ? WINDOW_BACKGROUND.dark
+      : WINDOW_BACKGROUND.light,
+    webPreferences: {
+      // The window shows a remote page: it gets no Node, and a world apart from the preload's.
+      sandbox: true,
+      contextIsolation: true,
+      nodeIntegration: false,
+      preload: inset ? join(appDir, "preload.js") : undefined,
+    },
+  })
+  const contents = win.webContents
+  win.once("ready-to-show", () => win.show())
+
+  // A load that fails or is replaced also rejects; `did-fail-load` below is what answers it.
+  const load = (url: string) => void win.loadURL(url).catch(() => {})
+
+  function onNavigation(url: string, event?: Event): void {
+    const step = nextNavigationStep(config, state, url)
+    if (step?.kind === "load") {
+      event?.preventDefault()
+      load(step.url)
+      return
+    }
+    if (step?.kind === "open-external") void shell.openExternal(step.url)
+    if (event && !mayNavigate(config, url)) {
+      event.preventDefault()
+      if (isWebUrl(url)) void shell.openExternal(url)
+    }
+  }
+
+  contents.on("will-navigate", (event, url) => onNavigation(url, event))
+  contents.on("will-redirect", (event, url) => onNavigation(url, event))
+  contents.on("did-navigate", (_event, url) => onNavigation(url))
+
+  // Links that ask for a new window belong in the user's browser, not in a second shell window.
+  contents.setWindowOpenHandler(({ url }) => {
+    if (isWebUrl(url)) void shell.openExternal(url)
+    return { action: "deny" }
+  })
+
+  if (inset) {
+    contents.on("dom-ready", () => void contents.insertCSS(HIDDEN_TITLE_BAR_CSS))
+  }
+
+  // The loading page stays on screen until the app's first response replaces it. If the app
+  // cannot be reached, it comes back saying so.
+  contents.on("did-fail-load", (_event, errorCode, _description, _url, isMainFrame) => {
+    if (isMainFrame && errorCode !== ERR_ABORTED) {
+      void win.loadFile(loadingPage, { hash: "unreachable" })
+    }
+  })
+  void win.loadFile(loadingPage).then(() => load(config.appUrl))
+}
+
+void app.whenReady().then(() => {
+  // A packaged app carries its icon in its bundle. Run from source, it would show Electron's.
+  if (icon && !app.isPackaged) app.dock?.setIcon(icon)
+
+  // Judged by the frame that asks, which may be another site's embedded in the app.
+  session.defaultSession.setPermissionRequestHandler(
+    (_contents, _permission, callback, details) => {
+      callback(isAppUrl(config, details.requestingUrl))
+    }
+  )
+
+  createWindow()
+  app.on("activate", () => {
+    if (BrowserWindow.getAllWindows().length === 0) createWindow()
+  })
+})
+
+app.on("window-all-closed", () => {
+  if (process.platform !== "darwin") app.quit()
+})

package/src/shell/navigation.ts

@@ -0,0 +1,84 @@
+/** What the shell was built to open. Written into the app by `writeDesktopApp`. */
+export interface ShellConfig {
+  /** Shown in the title bar, and to the user approving this window's sign-in. */
+  readonly name: string
+  /** The app, such as `https://app.example.com/`. */
+  readonly appUrl: string
+  readonly apiOrigin: string
+}
+
+export interface NavigationState {
+  /** Approval pages already opened, so a waiting page that reloads opens its browser tab once. */
+  readonly openedCodes: Set<string>
+  lastSignIn: { readonly url: string; readonly at: number } | null
+}
+
+export type NavigationStep =
+  /** Send the window somewhere else instead. */
+  | { readonly kind: "load"; readonly url: string }
+  /** Hand a URL to the system browser. */
+  | { readonly kind: "open-external"; readonly url: string }
+
+// One sign-in redirect can be reported more than once (as it starts, and again if the server
+// redirects to it). Answering each report would start a second sign-in request and orphan the first.
+const SIGN_IN_REPEAT_WINDOW_MS = 2_000
+
+export function createNavigationState(): NavigationState {
+  return { openedCodes: new Set(), lastSignIn: null }
+}
+
+/**
+ * Decides what the shell does about a navigation of its window.
+ *
+ * The window is a browser the user cannot finish a sign-in in: a magic link opens in their own
+ * browser, and identity providers turn embedded ones away. So the app's ordinary sign-in redirect
+ * becomes a request to be approved from the system browser, and the approval page opens there.
+ */
+export function nextNavigationStep(
+  config: ShellConfig,
+  state: NavigationState,
+  navigatedTo: string,
+  now: number = Date.now()
+): NavigationStep | null {
+  let url: URL
+  try {
+    url = new URL(navigatedTo)
+  } catch {
+    return null
+  }
+  if (url.origin !== new URL(config.apiOrigin).origin) return null
+
+  if (url.pathname === "/auth/sign-in") {
+    const last = state.lastSignIn
+    if (last && last.url === url.href && now - last.at < SIGN_IN_REPEAT_WINDOW_MS) return null
+    state.lastSignIn = { url: url.href, at: now }
+
+    const waiting = new URL("/auth/sign-in/device", url.origin)
+    const returnTo = url.searchParams.get("returnTo")
+    if (returnTo) waiting.searchParams.set("returnTo", returnTo)
+    waiting.searchParams.set("client", config.name)
+    return { kind: "load", url: waiting.href }
+  }
+
+  if (url.pathname === "/auth/sign-in/device") {
+    const userCode = url.searchParams.get("user_code")
+    if (!userCode || state.openedCodes.has(userCode)) return null
+    state.openedCodes.add(userCode)
+
+    const approval = new URL("/auth/device", url.origin)
+    approval.searchParams.set("user_code", userCode)
+    return { kind: "open-external", url: approval.href }
+  }
+
+  return null
+}
+
+/** Only web addresses leave for the system browser; a page cannot make the shell launch programs. */
+export function isWebUrl(value: string): boolean {
+  try {
+    const { protocol } = new URL(value)
+    return protocol === "https:" || protocol === "http:"
+  } catch {
+    return false
+  }
+}