@quickgui/native 0.0.1

package/integrations.ts

@@ -0,0 +1,258 @@
+import { Buffer } from "node:buffer";
+import { resolve as resolvePath } from "node:path";
+import * as binding from "./binding.js";
+
+export type AutoStartMode =
+  | "native"
+  | "macos-launch-agent"
+  | "macos-apple-script"
+  | "linux-systemd"
+  | "windows-system";
+
+export interface AutoStartOptions {
+  /** Portable registration identifier: ASCII letters, digits, dots, underscores, and hyphens. */
+  appName: string;
+  /** Defaults to the current packaged executable. */
+  executable?: string;
+  arguments?: readonly string[];
+  mode?: AutoStartMode;
+  /** Required by some macOS autostart modes. */
+  bundleIdentifier?: string;
+}
+
+export interface ProtocolRegistrationOptions {
+  scheme: string;
+  appName: string;
+  /** Stable reverse-DNS identifier used for Linux desktop integration. */
+  appId: string;
+  /** Defaults to the current packaged executable. */
+  executable?: string;
+  arguments?: readonly string[];
+}
+
+export interface UpdateClientOptions {
+  currentVersion: string;
+  /** Minisign public key, either raw or in Minisign's public-key file format. */
+  publicKey: string;
+  /** Defaults to QuickGUI's current `system-architecture` target. */
+  target?: string;
+  /** Hard download limit. The core caps this at 2 GiB. */
+  maximumDownloadBytes?: number;
+}
+
+export interface AvailableUpdate {
+  version: string;
+  currentVersion: string;
+  target: string;
+  url: string;
+  signature: string;
+  notes?: string;
+  publishedAt?: string;
+}
+
+export interface UpdateInstallOptions {
+  targetExecutable?: string;
+  retainBackup?: boolean;
+  windowsMode?: "basic-ui" | "quiet" | "passive";
+  installerArguments?: readonly string[];
+}
+
+export interface InstalledUpdate {
+  version: string;
+  disposition: "applied" | "installer-launched";
+  installedPath: string;
+  backupPath?: string;
+  installerProcessId?: number;
+  requiresApplicationExit: boolean;
+  relaunchRecommended: boolean;
+}
+
+/** Native login-launch registration. Operations run outside the JavaScript event loop. */
+export const AutoStart = Object.freeze({
+  isSupported(): boolean {
+    return binding.isAutoStartSupported();
+  },
+
+  enable(options: AutoStartOptions): Promise<void> {
+    return binding.enableAutoStart(nativeAutoStartOptions(options));
+  },
+
+  disable(options: AutoStartOptions): Promise<void> {
+    return binding.disableAutoStart(nativeAutoStartOptions(options));
+  },
+
+  isEnabled(options: AutoStartOptions): Promise<boolean> {
+    return binding.isAutoStartEnabled(nativeAutoStartOptions(options));
+  },
+});
+
+/** Native URL-scheme registration. macOS schemes are declared in the signed app bundle. */
+export const Protocol = Object.freeze({
+  supportsDynamicRegistration(): boolean {
+    return binding.supportsDynamicProtocolRegistration();
+  },
+
+  async register(options: ProtocolRegistrationOptions): Promise<void> {
+    await binding.registerProtocol(nativeProtocolOptions(options));
+  },
+
+  unregister(options: ProtocolRegistrationOptions): Promise<boolean> {
+    return binding.unregisterProtocol(nativeProtocolOptions(options));
+  },
+
+  isRegistered(options: ProtocolRegistrationOptions): Promise<boolean> {
+    return binding.isProtocolRegistered(nativeProtocolOptions(options));
+  },
+});
+
+/** Keychain Services, Windows Credential Manager, or Secret Service. */
+export const SecureStorage = Object.freeze({
+  isSupported(): boolean {
+    return binding.isSecureStorageSupported();
+  },
+
+  async set(service: string, account: string, secret: Uint8Array): Promise<void> {
+    await binding.setSecureStorage(service, account, Buffer.from(secret));
+  },
+
+  async get(service: string, account: string): Promise<Uint8Array | undefined> {
+    const secret = await binding.getSecureStorage(service, account);
+    return secret === undefined ? undefined : new Uint8Array(secret);
+  },
+
+  async setText(service: string, account: string, value: string): Promise<void> {
+    await binding.setSecureStorage(service, account, Buffer.from(value, "utf8"));
+  },
+
+  async getText(service: string, account: string): Promise<string | undefined> {
+    const secret = await binding.getSecureStorage(service, account);
+    return secret?.toString("utf8");
+  },
+
+  delete(service: string, account: string): Promise<boolean> {
+    return binding.deleteSecureStorage(service, account);
+  },
+});
+
+/** Signed update discovery, staging, mandatory re-verification, and native installation. */
+export const Updater = Object.freeze({
+  defaultTarget(): string {
+    return binding.defaultUpdateTarget();
+  },
+
+  async check(
+    endpoint: string,
+    options: UpdateClientOptions,
+  ): Promise<AvailableUpdate | undefined> {
+    const update = await binding.checkForUpdate(endpoint, nativeUpdateOptions(options));
+    return update === undefined ? undefined : normalizeAvailableUpdate(update);
+  },
+
+  downloadAndStage(
+    update: AvailableUpdate,
+    destinationDirectory: string,
+    options: UpdateClientOptions,
+  ): Promise<string> {
+    return binding.stageUpdate(
+      nativeAvailableUpdate(update),
+      destinationDirectory,
+      nativeUpdateOptions(options),
+    );
+  },
+
+  verify(
+    path: string,
+    signature: string,
+    options: UpdateClientOptions,
+  ): Promise<void> {
+    return binding.verifyUpdate(path, signature, nativeUpdateOptions(options));
+  },
+
+  async install(
+    update: AvailableUpdate,
+    artifact: string,
+    installOptions: UpdateInstallOptions,
+    options: UpdateClientOptions,
+  ): Promise<InstalledUpdate> {
+    const native: binding.NativeUpdateInstallOptions = {};
+    if (installOptions.targetExecutable !== undefined) {
+      native.targetExecutable = resolvePath(installOptions.targetExecutable);
+    }
+    if (installOptions.retainBackup !== undefined) {
+      native.retainBackup = installOptions.retainBackup;
+    }
+    if (installOptions.windowsMode !== undefined) native.windowsMode = installOptions.windowsMode;
+    if (installOptions.installerArguments !== undefined) {
+      native.installerArguments = [...installOptions.installerArguments];
+    }
+    const installed = await binding.installUpdate(
+      nativeAvailableUpdate(update),
+      resolvePath(artifact),
+      native,
+      nativeUpdateOptions(options),
+    );
+    return { ...installed } as InstalledUpdate;
+  },
+});
+
+function nativeAutoStartOptions(options: AutoStartOptions): binding.NativeAutoStartOptions {
+  const native: binding.NativeAutoStartOptions = { appName: options.appName };
+  if (options.executable !== undefined) native.executable = options.executable;
+  if (options.arguments !== undefined) native.arguments = [...options.arguments];
+  if (options.mode !== undefined) native.mode = options.mode;
+  if (options.bundleIdentifier !== undefined) {
+    native.bundleIdentifier = options.bundleIdentifier;
+  }
+  return native;
+}
+
+function nativeProtocolOptions(
+  options: ProtocolRegistrationOptions,
+): binding.NativeProtocolRegistrationOptions {
+  const native: binding.NativeProtocolRegistrationOptions = {
+    scheme: options.scheme,
+    appName: options.appName,
+    appId: options.appId,
+  };
+  if (options.executable !== undefined) native.executable = options.executable;
+  if (options.arguments !== undefined) native.arguments = [...options.arguments];
+  return native;
+}
+
+function nativeUpdateOptions(options: UpdateClientOptions): binding.NativeUpdateClientOptions {
+  const native: binding.NativeUpdateClientOptions = {
+    currentVersion: options.currentVersion,
+    publicKey: options.publicKey,
+  };
+  if (options.target !== undefined) native.target = options.target;
+  if (options.maximumDownloadBytes !== undefined) {
+    native.maximumDownloadBytes = options.maximumDownloadBytes;
+  }
+  return native;
+}
+
+function nativeAvailableUpdate(update: AvailableUpdate): binding.NativeAvailableUpdate {
+  const native: binding.NativeAvailableUpdate = {
+    version: update.version,
+    currentVersion: update.currentVersion,
+    target: update.target,
+    url: update.url,
+    signature: update.signature,
+  };
+  if (update.notes !== undefined) native.notes = update.notes;
+  if (update.publishedAt !== undefined) native.publishedAt = update.publishedAt;
+  return native;
+}
+
+function normalizeAvailableUpdate(update: binding.NativeAvailableUpdate): AvailableUpdate {
+  const normalized: AvailableUpdate = {
+    version: update.version,
+    currentVersion: update.currentVersion,
+    target: update.target,
+    url: update.url,
+    signature: update.signature,
+  };
+  if (update.notes !== undefined) normalized.notes = update.notes;
+  if (update.publishedAt !== undefined) normalized.publishedAt = update.publishedAt;
+  return normalized;
+}

package/native-tree.ts

@@ -0,0 +1,377 @@
+import {
+  NativeNodeTag,
+  PropertyCode,
+  type NativePropertyValue,
+} from "./protocol.ts";
+
+export type ColorValue = number | string;
+export type NativeElementName =
+  | "view"
+  | "div"
+  | "text"
+  | "button"
+  | "input"
+  | "textarea"
+  | "markdown"
+  | "virtual-list"
+  | "terminal"
+  | "svg";
+export type NativeEventType =
+  | "click"
+  | "mouseenter"
+  | "mouseleave"
+  | "input"
+  | "submit"
+  | "dismiss"
+  | "terminal"
+  | "pointer";
+export type NativeEventListener = (event: QuickGuiEvent) => void;
+
+export interface NativeNodeHost {
+  readonly nativeId: number;
+  readonly app: { readonly nativeId: number };
+  readonly nodes: Map<number, NativeNode>;
+  readonly closed: boolean;
+  flush(): number | undefined;
+  _trackMount(dispose: () => void): () => void;
+  _focusNode(node: NativeNode): boolean;
+  _enqueueCreate(node: NativeNode): void;
+  _enqueueProperty(
+    node: NativeNode,
+    property: PropertyCode,
+    value: NativePropertyValue,
+    color: boolean,
+  ): void;
+  _enqueueText(node: NativeNode): void;
+  _enqueueInsert(
+    parent: NativeNode,
+    child: NativeNode,
+    before?: NativeNode,
+  ): void;
+  _enqueueRemove(parent: NativeNode, child: NativeNode): void;
+  _enqueueCleanup(parent: NativeNode, children: readonly NativeNode[]): void;
+}
+
+let nextNodeId = 1;
+
+export class NativeNode {
+  readonly id: number;
+  readonly tag: NativeNodeTag;
+  text: string;
+  parent: NativeNode | undefined;
+  readonly children: NativeNode[] = [];
+  readonly properties = new Map<PropertyCode, NativePropertyValue>();
+  readonly colorProperties = new Set<PropertyCode>();
+  readonly listeners = new Map<NativeEventType, NativeEventListener>();
+  host: NativeNodeHost | undefined;
+  materialized = false;
+
+  constructor(tag: NativeNodeTag, text = "", id = allocateNodeId()) {
+    this.id = id;
+    this.tag = tag;
+    this.text = text;
+  }
+
+  /** Focus this mounted node, matching the web `HTMLElement.focus()` shape. */
+  focus(): boolean {
+    return this.host?._focusNode(this) ?? false;
+  }
+}
+
+export class QuickGuiEvent {
+  readonly type: NativeEventType;
+  readonly target: NativeNode;
+  currentTarget: NativeNode;
+  defaultPrevented = false;
+  propagationStopped = false;
+  readonly value: string | undefined;
+
+  constructor(type: NativeEventType, target: NativeNode, value?: string) {
+    this.type = type;
+    this.target = target;
+    this.currentTarget = target;
+    this.value = value;
+  }
+
+  preventDefault(): void {
+    this.defaultPrevented = true;
+  }
+
+  stopPropagation(): void {
+    this.propagationStopped = true;
+  }
+}
+
+export function createNativeElement(name: NativeElementName): NativeNode {
+  const tag =
+    name === "button"
+      ? NativeNodeTag.Button
+      : name === "input" || name === "textarea"
+        ? NativeNodeTag.Input
+        : name === "markdown"
+          ? NativeNodeTag.Markdown
+          : name === "virtual-list"
+            ? NativeNodeTag.VirtualList
+            : name === "terminal"
+              ? NativeNodeTag.Terminal
+              : name === "svg"
+                ? NativeNodeTag.Svg
+                : NativeNodeTag.View;
+  const node = new NativeNode(tag);
+  if (name === "textarea")
+    setNativeProperty(node, PropertyCode.Multiline, true);
+  return node;
+}
+
+export function createNativeText(value: string): NativeNode {
+  return new NativeNode(NativeNodeTag.Text, value);
+}
+
+export function createNativeSentinel(): NativeNode {
+  return new NativeNode(NativeNodeTag.Sentinel);
+}
+
+export function replaceNativeText(node: NativeNode, value: string): void {
+  if (node.tag !== NativeNodeTag.Text)
+    throw new TypeError("replaceText expects a text node");
+  if (node.text === value) return;
+  node.text = value;
+  if (node.materialized) node.host?._enqueueText(node);
+}
+
+export function setNativeProperty(
+  node: NativeNode,
+  property: PropertyCode,
+  value: NativePropertyValue,
+  options: { color?: boolean } = {},
+): void {
+  const normalized = value ?? null;
+  if (normalized === null) {
+    if (!node.properties.delete(property)) return;
+    node.colorProperties.delete(property);
+  } else {
+    const previous = node.properties.get(property);
+    if (
+      Object.is(previous, normalized) &&
+      node.colorProperties.has(property) === !!options.color
+    ) {
+      return;
+    }
+    node.properties.set(property, normalized);
+    if (options.color) node.colorProperties.add(property);
+    else node.colorProperties.delete(property);
+  }
+  if (node.materialized) {
+    node.host?._enqueueProperty(node, property, normalized, !!options.color);
+  }
+}
+
+export function setNativeEventListener(
+  node: NativeNode,
+  type: NativeEventType,
+  listener: NativeEventListener | undefined,
+): void {
+  if (listener) node.listeners.set(type, listener);
+  else node.listeners.delete(type);
+  if (type === "click") {
+    setNativeProperty(
+      node,
+      PropertyCode.ClickListener,
+      node.listeners.has("click"),
+    );
+  } else if (type === "input") {
+    setNativeProperty(
+      node,
+      PropertyCode.InputListener,
+      node.listeners.has("input"),
+    );
+  } else if (type === "submit") {
+    setNativeProperty(
+      node,
+      PropertyCode.SubmitListener,
+      node.listeners.has("submit"),
+    );
+  } else if (type === "dismiss") {
+    setNativeProperty(
+      node,
+      PropertyCode.DismissListener,
+      node.listeners.has("dismiss"),
+    );
+  } else if (type === "terminal") {
+    setNativeProperty(
+      node,
+      PropertyCode.TerminalStatusListener,
+      node.listeners.has("terminal"),
+    );
+  } else if (type === "pointer") {
+    setNativeProperty(
+      node,
+      PropertyCode.PointerListener,
+      node.listeners.has("pointer"),
+    );
+  } else {
+    const listensForHover =
+      node.listeners.has("mouseenter") || node.listeners.has("mouseleave");
+    setNativeProperty(node, PropertyCode.HoverListener, listensForHover);
+  }
+}
+
+export function insertNativeNode(
+  parent: NativeNode,
+  node: NativeNode,
+  anchor?: NativeNode,
+): void {
+  if (anchor && anchor.parent !== parent)
+    throw new Error("anchor is not a child of parent");
+  if (node === parent) throw new Error("a native node cannot contain itself");
+  if (anchor === node && node.parent === parent) return;
+
+  if (node.parent) {
+    const previousIndex = node.parent.children.indexOf(node);
+    if (previousIndex >= 0) node.parent.children.splice(previousIndex, 1);
+  }
+  const index = anchor
+    ? parent.children.indexOf(anchor)
+    : parent.children.length;
+  parent.children.splice(index, 0, node);
+  node.parent = parent;
+
+  if (parent.host) {
+    materialize(node, parent.host);
+    parent.host._enqueueInsert(parent, node, anchor);
+  }
+}
+
+export function removeNativeNode(parent: NativeNode, node: NativeNode): void {
+  if (node.parent !== parent) return;
+  const index = parent.children.indexOf(node);
+  if (index >= 0) parent.children.splice(index, 1);
+  node.parent = undefined;
+  if (node.materialized && parent.host)
+    parent.host._enqueueRemove(parent, node);
+  dematerialize(node);
+}
+
+export function cleanupNativeNodes(
+  parent: NativeNode,
+  nodes: readonly NativeNode[],
+): void {
+  const attached = nodes.filter((node) => node.parent === parent);
+  if (attached.length === 0) return;
+  for (const node of attached) {
+    const index = parent.children.indexOf(node);
+    if (index >= 0) parent.children.splice(index, 1);
+    node.parent = undefined;
+  }
+  if (parent.host) parent.host._enqueueCleanup(parent, attached);
+  for (const node of attached) dematerialize(node);
+}
+
+export function getNativeParent(node: NativeNode): NativeNode | undefined {
+  return node.parent;
+}
+
+export function getNativeFirstChild(node: NativeNode): NativeNode | undefined {
+  return node.children[0];
+}
+
+export function getNativeNextSibling(node: NativeNode): NativeNode | undefined {
+  if (!node.parent) return undefined;
+  const index = node.parent.children.indexOf(node);
+  return index < 0 ? undefined : node.parent.children[index + 1];
+}
+
+export function isNativeText(node: NativeNode): boolean {
+  return node.tag === NativeNodeTag.Text;
+}
+
+export function parseColor(value: ColorValue): number {
+  if (typeof value === "number") return value >>> 0;
+  const color = value.trim().toLowerCase();
+  if (color === "transparent") return 0;
+  if (color === "black") return packColor(0, 0, 0, 255);
+  if (color === "white") return packColor(255, 255, 255, 255);
+  if (color.startsWith("#")) {
+    const hex = color.slice(1);
+    if (hex.length === 3 || hex.length === 4) {
+      const [r = "0", g = "0", b = "0", a = "f"] = hex;
+      return packColor(
+        Number.parseInt(r + r, 16),
+        Number.parseInt(g + g, 16),
+        Number.parseInt(b + b, 16),
+        Number.parseInt(a + a, 16),
+      );
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      return packColor(
+        Number.parseInt(hex.slice(0, 2), 16),
+        Number.parseInt(hex.slice(2, 4), 16),
+        Number.parseInt(hex.slice(4, 6), 16),
+        hex.length === 8 ? Number.parseInt(hex.slice(6, 8), 16) : 255,
+      );
+    }
+  }
+  const rgb = color.match(/^rgba?\(([^)]+)\)$/);
+  if (rgb) {
+    const parts = rgb[1]?.split(",").map((part) => part.trim()) ?? [];
+    if (parts.length === 3 || parts.length === 4) {
+      return packColor(
+        Number(parts[0]),
+        Number(parts[1]),
+        Number(parts[2]),
+        parts[3] === undefined ? 255 : Math.round(Number(parts[3]) * 255),
+      );
+    }
+  }
+  throw new TypeError(`unsupported QuickGUI color \`${value}\``);
+}
+
+function packColor(r: number, g: number, b: number, a: number): number {
+  const component = (value: number) =>
+    Math.max(0, Math.min(255, Math.round(value)));
+  return (
+    (component(r) |
+      (component(g) << 8) |
+      (component(b) << 16) |
+      (component(a) << 24)) >>>
+    0
+  );
+}
+
+function allocateNodeId(): number {
+  if (nextNodeId >= 0xffff_ffff)
+    throw new Error("QuickGUI native node id space exhausted");
+  return nextNodeId++;
+}
+
+function materialize(node: NativeNode, host: NativeNodeHost): void {
+  if (node.materialized) {
+    if (node.host !== host)
+      throw new Error("a native node cannot move between QuickGUI windows");
+    return;
+  }
+  node.host = host;
+  node.materialized = true;
+  host.nodes.set(node.id, node);
+  host._enqueueCreate(node);
+  for (const [property, value] of node.properties) {
+    host._enqueueProperty(
+      node,
+      property,
+      value,
+      node.colorProperties.has(property),
+    );
+  }
+  for (const child of node.children) {
+    materialize(child, host);
+    host._enqueueInsert(node, child);
+  }
+}
+
+function dematerialize(node: NativeNode): void {
+  const host = node.host;
+  if (host) host.nodes.delete(node.id);
+  node.materialized = false;
+  node.host = undefined;
+  for (const child of node.children) dematerialize(child);
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@quickgui/native",
+  "version": "0.0.1",
+  "description": "Low-overhead Bun and Node-API host for QuickGUI",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/egoist/quickgui.git",
+    "directory": "packages/native"
+  },
+  "bugs": "https://github.com/egoist/quickgui/issues",
+  "homepage": "https://github.com/egoist/quickgui#readme",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./host": "./host.ts",
+    "./protocol": "./protocol.ts"
+  },
+  "files": [
+    "index.ts",
+    "dialog.ts",
+    "integrations.ts",
+    "native-tree.ts",
+    "single-instance.ts",
+    "system.ts",
+    "tray.ts",
+    "host.ts",
+    "protocol.ts",
+    "scripts",
+    "binding.js",
+    "binding.d.ts",
+    "*.node",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun ./scripts/build.ts",
+    "build:debug": "bun ./scripts/build.ts --debug",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "3.8.6"
+  },
+  "napi": {
+    "binaryName": "quickgui-native",
+    "targets": [
+      "aarch64-apple-darwin",
+      "x86_64-apple-darwin",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-pc-windows-msvc",
+      "x86_64-pc-windows-msvc"
+    ]
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT OR Apache-2.0"
+}