npm - @sixb/desktop - Versions diffs - 0.0.0-stage → 0.2.0 - Mend

@sixb/desktop 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/LICENSE +21 -0
package/README.md +83 -2
package/dist/generate.d.ts +30 -0
package/dist/generate.d.ts.map +1 -0
package/dist/identity.d.ts +22 -0
package/dist/identity.d.ts.map +1 -0
package/dist/index.d.ts +18 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +326 -0
package/dist/index.js.map +14 -0
package/dist/mac-icon.d.ts +7 -0
package/dist/mac-icon.d.ts.map +1 -0
package/dist/run.d.ts +3 -0
package/dist/run.d.ts.map +1 -0
package/dist/shell/bridge.d.ts +16 -0
package/dist/shell/bridge.d.ts.map +1 -0
package/dist/shell/main.d.ts +2 -0
package/dist/shell/main.d.ts.map +1 -0
package/dist/shell/navigation.d.ts +39 -0
package/dist/shell/navigation.d.ts.map +1 -0
package/dist/shell/preload.d.ts +2 -0
package/dist/shell/preload.d.ts.map +1 -0
package/dist/shell/window.d.ts +48 -0
package/dist/shell/window.d.ts.map +1 -0
package/dist/tsconfig.json +5 -0
package/package.json +57 -4
package/src/generate.ts +133 -0
package/src/identity.ts +83 -0
package/src/index.ts +177 -0
package/src/mac-icon.ts +81 -0
package/src/packager.mjs +5 -0
package/src/run.ts +11 -0
package/src/shell/bridge.ts +16 -0
package/src/shell/index.html +204 -0
package/src/shell/main.ts +107 -0
package/src/shell/navigation.ts +84 -0
package/src/shell/preload.ts +44 -0
package/src/shell/window.ts +85 -0

package/src/shell/bridge.ts ADDED Viewed

@@ -0,0 +1,16 @@
+/** The name a page finds the desktop app under, through `useDesktop` in `@sixb/client/hooks`. */
+export const DESKTOP_BRIDGE_NAME = "sixbDesktop"
+/**
+ * What the shell offers the page. `SixbDesktop` in `@sixb/client` is the page's view of this, and
+ * `tests/app.test.ts` holds the two together.
+ *
+ * The page is remote, and anything here is open to whatever runs in it. To offer more:
+ *  1. Add one narrow method here, calling `ipcRenderer.invoke`, never a general way to run a command
+ *     or read a file. The page asks; the person decides, in a native dialog, what it gets.
+ *  2. Handle it in `main.ts`, refusing any sender that `isAppUrl` does not accept.
+ *  3. Add it to `SixbDesktop` as optional, because a page can outlive the shell it runs in.
+ */
+export function desktopBridge<const Platform extends NodeJS.Platform>(platform: Platform) {
+  return { platform }
+}

package/src/shell/index.html ADDED Viewed

@@ -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 ADDED Viewed

@@ -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,
+  hasHiddenTitleBar,
+  isAppUrl,
+  mayNavigate,
+  pageWebPreferences,
+  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
+const inset = hasHiddenTitleBar(process.platform)
+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: pageWebPreferences(join(appDir, "preload.js")),
+  })
+  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 ADDED Viewed

@@ -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
+  }
+}

package/src/shell/preload.ts ADDED Viewed

@@ -0,0 +1,44 @@
+// Runs in every page the window shows, before the page's own scripts, in a world of its own. Electron
+// sandboxes it: of what it imports, only `electron` may remain once compiled.
+import { contextBridge } from "electron"
+import { DESKTOP_BRIDGE_NAME, desktopBridge } from "./bridge"
+import { CONTROLS_HEIGHT_PX, hasHiddenTitleBar } from "./window"
+contextBridge.exposeInMainWorld(DESKTOP_BRIDGE_NAME, desktopBridge(process.platform))
+if (hasHiddenTitleBar(process.platform)) installHiddenTitleBar()
+/**
+ * Marks `<html>` the moment the element exists, so an app can read the mark on its first render,
+ * and adds the drag handle once there is a body to hold it.
+ */
+function installHiddenTitleBar(): void {
+  const mark = () => {
+    const root = document.documentElement
+    if (!root) return false
+    root.dataset.sixbDesktop = "inset"
+    root.style.setProperty("--sixb-desktop-controls-height", `${CONTROLS_HEIGHT_PX}px`)
+    return true
+  }
+  if (!mark()) {
+    const observer = new MutationObserver(() => {
+      if (mark()) observer.disconnect()
+    })
+    observer.observe(document, { childList: true })
+  }
+  const addHandle = () => {
+    if (!document.body || document.getElementById("sixb-desktop-drag")) return
+    const handle = document.createElement("div")
+    handle.id = "sixb-desktop-drag"
+    handle.setAttribute("aria-hidden", "true")
+    // First in the body, not last: the draggable area is built in document order, so a control
+    // is only cut out of it if it comes after the handle.
+    document.body.prepend(handle)
+  }
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", addHandle, { once: true })
+  } else {
+    addHandle()
+  }
+}

package/src/shell/window.ts ADDED Viewed

@@ -0,0 +1,85 @@
+import type { ShellConfig } from "./navigation"
+/**
+ * Whether the window itself may show `url`: only the app and the API that serves its sign-in
+ * pages. Anything else a page links to opens in the user's browser instead.
+ */
+export function mayNavigate(config: ShellConfig, url: string): boolean {
+  try {
+    const { origin } = new URL(url)
+    return origin === new URL(config.appUrl).origin || origin === new URL(config.apiOrigin).origin
+  } catch {
+    return false
+  }
+}
+/**
+ * Whether `url` is on the app's own origin. Camera, location and the like are the app's to ask for,
+ * and not a frame it embeds from elsewhere.
+ */
+export function isAppUrl(config: ShellConfig, url: string): boolean {
+  try {
+    return new URL(url).origin === new URL(config.appUrl).origin
+  } catch {
+    return false
+  }
+}
+/**
+ * What the window paints before a page has: the loading page's own background, so the window
+ * opens, and passes from that page to the app, without a flash of white.
+ */
+export const WINDOW_BACKGROUND = { light: "#fafafa", dark: "#0a0a0a" } as const
+/**
+ * What the window's page runs with. The page is remote: it gets no Node and a world apart from the
+ * preload's, on every platform, and reaches the shell only through what the preload exposes.
+ */
+export function pageWebPreferences(preload: string) {
+  return { sandbox: true, contextIsolation: true, nodeIntegration: false, preload }
+}
+/** Only macOS draws window controls over the page; elsewhere the title bar stays. */
+export function hasHiddenTitleBar(platform: NodeJS.Platform): boolean {
+  return platform === "darwin"
+}
+/** The band at the top of a window without a title bar where macOS draws the window controls. */
+export const CONTROLS_HEIGHT_PX = 36
+/**
+ * Styles for a window without a title bar, inserted into every page it shows.
+ *
+ * The page reaches the top edge, under the window controls, so two things a title bar did have
+ * to come from the page: somewhere to grab the window, and room for the controls.
+ *  - `#sixb-desktop-drag` (added by the preload) is the drag handle: a strip across the top, above
+ *    the page. It ignores the pointer, and every control is cut out of the draggable area, so
+ *    buttons and links under the strip still take their clicks and the space between them moves
+ *    the window. Something clickable that is none of the things listed here needs
+ *    `-webkit-app-region: no-drag` of its own.
+ *  - The shared sidebar is moved down so most apps need nothing. Other layouts can use
+ *    `html[data-sixb-desktop]` and `--sixb-desktop-controls-height`, which the preload sets.
+ */
+export const HIDDEN_TITLE_BAR_CSS = [
+  `#sixb-desktop-drag{position:fixed;top:0;left:0;right:0;height:${CONTROLS_HEIGHT_PX}px;`,
+  "z-index:2147483647;pointer-events:none;-webkit-app-region:drag}",
+  `${[
+    "a",
+    "button",
+    "input",
+    "select",
+    "textarea",
+    "summary",
+    "label",
+    "[role=button]",
+    "[role=link]",
+    "[role=tab]",
+    "[role=menuitem]",
+    "[role=switch]",
+    "[role=checkbox]",
+    "[role=combobox]",
+    "[contenteditable]",
+    "[tabindex]:not([tabindex='-1'])",
+  ].join(",")}{-webkit-app-region:no-drag}`,
+  `[data-slot="sidebar-inner"]{padding-top:calc(${CONTROLS_HEIGHT_PX}px - 0.5rem)}`,
+].join("")