@lynx-js/lynxtron 0.0.1 → 0.0.3

package/apis/api/menu.d.ts

@@ -0,0 +1,96 @@
+// Copyright 2026 The Lynxtron Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import { EventEmitter } from 'node:events';
+import { NativeImage } from './native-image';
+
+export type MenuItemType =
+  | 'normal'
+  | 'separator'
+  | 'submenu'
+  | 'checkbox'
+  | 'radio'
+  | 'header'
+  | 'palette';
+
+export interface MenuItemConstructorOptions {
+  id?: string;
+  label?: string;
+  sublabel?: string;
+  toolTip?: string;
+  enabled?: boolean;
+  visible?: boolean;
+  checked?: boolean;
+  type?: MenuItemType;
+  role?: string;
+  accelerator?: string | null;
+  acceleratorWorksWhenHidden?: boolean;
+  registerAccelerator?: boolean;
+  icon?: NativeImage | null;
+  submenu?: Menu | MenuItemConstructorOptions[] | null;
+  selector?: string;
+  click?: (menuItem: MenuItem, focusedWindow: any, event: any) => void;
+  after?: string[];
+  before?: string[];
+  afterGroupContaining?: string[];
+  beforeGroupContaining?: string[];
+}
+
+export interface PopupOptions {
+  window?: any;
+  x?: number;
+  y?: number;
+  positioningItem?: number;
+  callback?: () => void;
+}
+
+export declare class MenuItem {
+  constructor(options?: MenuItemConstructorOptions);
+  id?: string;
+  label: string;
+  type: MenuItemType;
+  commandId: number;
+  checked: boolean;
+  enabled: boolean;
+  visible: boolean;
+  submenu?: Menu | null;
+  role?: string;
+  accelerator?: string | null;
+  acceleratorWorksWhenHidden: boolean;
+  registerAccelerator: boolean;
+  icon?: NativeImage | null;
+  sublabel?: string;
+  toolTip?: string;
+  menu?: Menu;
+  selector?: string;
+  groupId: number;
+  click: (event: any, focusedWindow: any) => void;
+  getDefaultRoleAccelerator(): string | null;
+  getCheckStatus(): boolean;
+  overrideProperty(name: string, defaultValue?: any): void;
+  overrideReadOnlyProperty(name: string, defaultValue?: any): void;
+}
+
+export declare class Menu extends EventEmitter {
+  constructor();
+  static getApplicationMenu(): Menu | null;
+  static setApplicationMenu(menu: Menu | null): void;
+  static sendActionToFirstResponder(action: string): void;
+  static buildFromTemplate(
+    template: Array<MenuItemConstructorOptions | MenuItem>
+  ): Menu;
+  popup(
+    options?: PopupOptions
+  ): {
+    lynxWindow: any;
+    x: number;
+    y: number;
+    position: number;
+  };
+  closePopup(window?: any): void;
+  getMenuItemById(id: string): MenuItem | null;
+  append(item: MenuItem): void;
+  insert(pos: number, item: MenuItem): void;
+  items: MenuItem[];
+}

package/apis/api/native-image.d.ts

@@ -0,0 +1,268 @@
+// Copyright 2026 The Lynxtron Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import { Size } from '../structures/size';
+import { Rectangle } from '../structures/rectangle';
+
+export interface CreateFromBitmapOptions {
+  width: number;
+  height: number;
+  /**
+   * Defaults to 1.0.
+   */
+  scaleFactor?: number;
+}
+
+export interface CreateFromBufferOptions {
+  /**
+   * Required for bitmap buffers.
+   */
+  width?: number;
+  /**
+   * Required for bitmap buffers.
+   */
+  height?: number;
+  /**
+   * Defaults to 1.0.
+   */
+  scaleFactor?: number;
+}
+
+export interface AddRepresentationOptions {
+  /**
+   * The scale factor to add the image representation for.
+   */
+  scaleFactor?: number;
+  /**
+   * Defaults to 0. Required if a bitmap buffer is specified as `buffer`.
+   */
+  width?: number;
+  /**
+   * Defaults to 0. Required if a bitmap buffer is specified as `buffer`.
+   */
+  height?: number;
+  /**
+   * The buffer containing the raw image data.
+   */
+  buffer?: Buffer;
+  /**
+   * The data URL containing either a base 64 encoded PNG or JPEG image.
+   */
+  dataURL?: string;
+}
+
+export interface BitmapOptions {
+  /**
+   * Defaults to 1.0.
+   */
+  scaleFactor?: number;
+}
+
+export interface ResizeOptions {
+  /**
+   * Defaults to the image's width.
+   */
+  width?: number;
+  /**
+   * Defaults to the image's height.
+   */
+  height?: number;
+  /**
+   * The desired quality of the resize image. Possible values include `good`,
+   * `better`, or `best`. The default is `best`. These values express a desired
+   * quality/speed tradeoff. They are translated into an algorithm-specific method
+   * that depends on the capabilities (CPU, GPU) of the underlying platform. It is
+   * possible for all three methods to be mapped to the same algorithm on a given
+   * platform.
+   */
+  quality?: 'good' | 'better' | 'best';
+}
+
+export interface ToBitmapOptions {
+  /**
+   * Defaults to 1.0.
+   */
+  scaleFactor?: number;
+}
+
+export interface ToDataURLOptions {
+  /**
+   * Defaults to 1.0.
+   */
+  scaleFactor?: number;
+}
+
+export interface ToPNGOptions {
+  /**
+   * Defaults to 1.0.
+   */
+  scaleFactor?: number;
+}
+
+export declare class NativeImage {
+  /**
+   * Creates an empty `NativeImage` instance.
+   */
+  static createEmpty(): NativeImage;
+  /**
+   * Creates a new `NativeImage` instance from `buffer` that contains the raw bitmap
+   * pixel data returned by `toBitmap()`. The specific format is platform-dependent.
+   */
+  static createFromBitmap(
+    buffer: Buffer,
+    options: CreateFromBitmapOptions
+  ): NativeImage;
+  /**
+   * Creates a new `NativeImage` instance from `buffer`. Tries to decode as PNG or
+   * JPEG first.
+   */
+  static createFromBuffer(
+    buffer: Buffer,
+    options?: CreateFromBufferOptions
+  ): NativeImage;
+  /**
+   * Creates a new `NativeImage` instance from `dataUrl`, a base 64 encoded Data URL
+   * string.
+   */
+  static createFromDataURL(dataURL: string): NativeImage;
+  /**
+   * Creates a new `NativeImage` instance from the `NSImage` that maps to the given
+   * image name. See Apple's `NSImageName` documentation for a list of possible
+   * values.
+   *
+   * The `hslShift` is applied to the image with the following rules:
+   *
+   * * `hsl_shift[0]` (hue): The absolute hue value for the image - 0 and 1 map to 0
+   * and 360 on the hue color wheel (red).
+   * * `hsl_shift[1]` (saturation): A saturation shift for the image, with the
+   * following key values: 0 = remove all color. 0.5 = leave unchanged. 1 = fully
+   * saturate the image.
+   * * `hsl_shift[2]` (lightness): A lightness shift for the image, with the
+   * following key values: 0 = remove all lightness (make all pixels black). 0.5 =
+   * leave unchanged. 1 = full lightness (make all pixels white).
+   *
+   * This means that `[-1, 0, 1]` will make the image completely white and `[-1, 1,0]`
+   * will make the image completely black.
+   *
+   * In some cases, the `NSImageName` doesn't match its string representation; one
+   * example of this is `NSFolderImageName`, whose string representation would
+   * actually be `NSFolder`. Therefore, you'll need to determine the correct string
+   * representation for your image before passing it in. This can be done with the
+   * following:
+   *
+   * where `SYSTEM_IMAGE_NAME` should be replaced with any value from this list.
+   *
+   * @platform darwin
+   */
+  static createFromNamedImage(
+    imageName: string,
+    hslShift?: number[]
+  ): NativeImage;
+  /**
+   * Creates a new `NativeImage` instance from an image file (e.g., PNG or JPEG)
+   * located at `path`. This method returns an empty image if the `path` does not
+   * exist, cannot be read, or is not a valid image.
+   */
+  static createFromPath(path: string): NativeImage;
+  /**
+   * fulfilled with the file's thumbnail preview image, which is a NativeImage.
+   *
+   * Windows implementation will ignore `size.height` and scale the height
+   * according to `size.width`.
+   *
+   * @platform darwin,win32
+   */
+  static createThumbnailFromPath(
+    path: string,
+    size: Size
+  ): Promise<NativeImage>;
+  /**
+   * Add an image representation for a specific scale factor. This can be used to
+   * programmatically add different scale factor representations to an image. This
+   * can be called on empty images.
+   */
+  addRepresentation(options: AddRepresentationOptions): void;
+  /**
+   * The cropped image.
+   */
+  crop(rect: Rectangle): NativeImage;
+  /**
+   * The image's aspect ratio (width divided by height).
+   *
+   * If `scaleFactor` is passed, this will return the aspect ratio corresponding to
+   * the image representation most closely matching the passed value.
+   */
+  getAspectRatio(scaleFactor?: number): number;
+  /**
+   * Legacy alias for `image.toBitmap()`.
+   *
+   * @deprecated Use `image.toBitmap()` instead.
+   */
+  getBitmap(options?: BitmapOptions): void;
+  /**
+   * A Buffer that stores C pointer to underlying native handle of the image. On
+   * macOS, a pointer to `NSImage` instance is returned.
+   *
+   * Notice that the returned pointer is a weak pointer to the underlying native
+   * image instead of a copy, so you _must_ ensure that the associated `nativeImage`
+   * instance is kept around.
+   *
+   * @platform darwin
+   */
+  getNativeHandle(): Buffer;
+  /**
+   * An array of all scale factors corresponding to representations for a given
+   * `NativeImage`.
+   */
+  getScaleFactors(): number[];
+  /**
+   * If `scaleFactor` is passed, this will return the size corresponding to the image
+   * representation most closely matching the passed value.
+   */
+  getSize(scaleFactor?: number): Size;
+  /**
+   * Whether the image is empty.
+   */
+  isEmpty(): boolean;
+  /**
+   * Whether the image is a macOS template image.
+   */
+  isTemplateImage(): boolean;
+  /**
+   * The resized image.
+   *
+   * If only the `height` or the `width` are specified then the current aspect ratio
+   * will be preserved in the resized image.
+   */
+  resize(options: ResizeOptions): NativeImage;
+  /**
+   * Marks the image as a macOS template image.
+   */
+  setTemplateImage(option: boolean): void;
+  /**
+   * A Buffer that contains a copy of the image's raw bitmap pixel data.
+   */
+  toBitmap(options?: ToBitmapOptions): Buffer;
+  /**
+   * The Data URL of the image.
+   */
+  toDataURL(options?: ToDataURLOptions): string;
+  /**
+   * A Buffer that contains the image's `JPEG` encoded data.
+   */
+  toJPEG(quality: number): Buffer;
+  /**
+   * A Buffer that contains the image's `PNG` encoded data.
+   */
+  toPNG(options?: ToPNGOptions): Buffer;
+  /**
+   * A `boolean` property that determines whether the image is considered a template
+   * image.
+   *
+   * Please note that this property only has an effect on macOS.
+   *
+   * @platform darwin
+   */
+  isMacTemplateImage: boolean;
+}

package/apis/api/notification-response.d.ts

@@ -0,0 +1,26 @@
+// Copyright 2026 The Lynxtron Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+export interface NotificationResponse {
+  /**
+   * The identifier string of the action that the user selected.
+   */
+  actionIdentifier: string;
+  /**
+   * The delivery date of the notification.
+   */
+  date: number;
+  /**
+   * The unique identifier for this notification request.
+   */
+  identifier: string;
+  /**
+   * A dictionary of custom information associated with the notification.
+   */
+  userInfo: Record<string, any>;
+  /**
+   * The text entered or chosen by the user.
+   */
+  userText?: string;
+}

package/apis/api/notification.d.ts

@@ -0,0 +1,242 @@
+// Copyright 2026 The Lynxtron Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import { EventEmitter } from 'node:events';
+
+export interface NotificationAction {
+  /**
+   * The label for the given action.
+   */
+  text?: string;
+  /**
+   * The type of action, can be `button`.
+   */
+  type: 'button';
+}
+
+export interface NotificationConstructorOptions {
+  /**
+   * A title for the notification, which will be shown at the top of the notification
+   * window when it is shown.
+   */
+  title?: string;
+  /**
+   * A subtitle for the notification, which will be displayed below the title.
+   *
+   * @platform darwin
+   */
+  subtitle?: string;
+  /**
+   * The body text of the notification, which will be displayed below the title or
+   * subtitle.
+   */
+  body?: string;
+  /**
+   * Whether to show the notification without sound.
+   */
+  silent?: boolean;
+  /**
+   * An icon to use in the notification.
+   */
+  icon?: string;
+  /**
+   * Whether or not to add a reply option to the notification.
+   *
+   * @platform darwin
+   */
+  hasReply?: boolean;
+  /**
+   * The timeout duration of the notification. Can be 'default' or 'never'.
+   *
+   * @platform win32
+   */
+  timeoutType?: 'default' | 'never';
+  /**
+   * The placeholder to write in the reply input field.
+   *
+   * @platform darwin
+   */
+  replyPlaceholder?: string;
+  /**
+   * The name of the sound file to play when the notification is shown.
+   *
+   * @platform darwin
+   */
+  sound?: string;
+  /**
+   * The urgency level of the notification. Can be 'normal', 'critical', or 'low'.
+   *
+   * @platform linux
+   */
+  urgency?: 'normal' | 'critical' | 'low';
+  /**
+   * Actions to add to the notification.
+   *
+   * @platform darwin
+   */
+  actions?: NotificationAction[];
+  /**
+   * A custom title for the close button of an alert. An empty string will cause the
+   * default localized text to be used.
+   *
+   * @platform darwin
+   */
+  closeButtonText?: string;
+  /**
+   * A custom XML string to use for the toast notification.
+   *
+   * @platform win32
+   */
+  toastXml?: string;
+}
+
+export declare class Notification extends EventEmitter {
+  /**
+   * A `NotificationAction[]` property representing the actions of the notification.
+   */
+  actions: NotificationAction[];
+  /**
+   * A `string` property representing the body of the notification.
+   */
+  body: string;
+  /**
+   * A `string` property representing the close button text of the notification.
+   */
+  closeButtonText: string;
+  /**
+   * A `boolean` property representing whether the notification has a reply action.
+   */
+  hasReply: boolean;
+  /**
+   * A `string` property representing the reply placeholder of the notification.
+   */
+  replyPlaceholder: string;
+  /**
+   * A `boolean` property representing whether the notification is silent.
+   */
+  silent: boolean;
+  /**
+   * A `string` property representing the sound of the notification.
+   */
+  sound: string;
+  /**
+   * A `string` property representing the subtitle of the notification.
+   */
+  subtitle: string;
+  /**
+   * A `string` property representing the type of timeout duration for the
+   * notification. Can be 'default' or 'never'.
+   *
+   * If `timeoutType` is set to 'never', the notification never expires. It stays
+   * open until closed by the calling API or the user.
+   *
+   * @platform win32
+   */
+  timeoutType: 'default' | 'never';
+  /**
+   * A `string` property representing the title of the notification.
+   */
+  title: string;
+  /**
+   * A `string` property representing the custom Toast XML of the notification.
+   *
+   * @platform win32
+   */
+  toastXml: string;
+
+  constructor(options?: NotificationConstructorOptions);
+
+  /**
+   * Immediately shows the notification to the user.
+   */
+  public show(): void;
+
+  /**
+   * Dismisses the notification.
+   */
+  public close(): void;
+
+  /**
+   * Whether or not desktop notifications are supported on the current system.
+   */
+  public static isSupported(): boolean;
+
+  /**
+   * Emitted when the notification is shown to the user.
+   */
+  on(event: 'show', listener: () => void): this;
+  off(event: 'show', listener: () => void): this;
+  once(event: 'show', listener: () => void): this;
+  addListener(event: 'show', listener: () => void): this;
+  removeListener(event: 'show', listener: () => void): this;
+
+  /**
+   * Emitted when the notification is clicked by the user.
+   */
+  on(event: 'click', listener: () => void): this;
+  off(event: 'click', listener: () => void): this;
+  once(event: 'click', listener: () => void): this;
+  addListener(event: 'click', listener: () => void): this;
+  removeListener(event: 'click', listener: () => void): this;
+
+  /**
+   * Emitted when the notification is closed by manual intervention from the user.
+   */
+  on(event: 'close', listener: () => void): this;
+  off(event: 'close', listener: () => void): this;
+  once(event: 'close', listener: () => void): this;
+  addListener(event: 'close', listener: () => void): this;
+  removeListener(event: 'close', listener: () => void): this;
+
+  /**
+   * Emitted when the user clicks the "Reply" button on a notification with `hasReply: true`.
+   *
+   * @platform darwin
+   */
+  on(event: 'reply', listener: (event: Event, reply: string) => void): this;
+  off(event: 'reply', listener: (event: Event, reply: string) => void): this;
+  once(event: 'reply', listener: (event: Event, reply: string) => void): this;
+  addListener(
+    event: 'reply',
+    listener: (event: Event, reply: string) => void
+  ): this;
+  removeListener(
+    event: 'reply',
+    listener: (event: Event, reply: string) => void
+  ): this;
+
+  /**
+   * Emitted when the user clicks one of the actions on a notification.
+   *
+   * @platform darwin
+   */
+  on(event: 'action', listener: (event: Event, index: number) => void): this;
+  off(event: 'action', listener: (event: Event, index: number) => void): this;
+  once(event: 'action', listener: (event: Event, index: number) => void): this;
+  addListener(
+    event: 'action',
+    listener: (event: Event, index: number) => void
+  ): this;
+  removeListener(
+    event: 'action',
+    listener: (event: Event, index: number) => void
+  ): this;
+
+  /**
+   * Emitted when an error is encountered while showing the notification.
+   *
+   * @platform win32
+   */
+  on(event: 'failed', listener: (event: Event, error: string) => void): this;
+  off(event: 'failed', listener: (event: Event, error: string) => void): this;
+  once(event: 'failed', listener: (event: Event, error: string) => void): this;
+  addListener(
+    event: 'failed',
+    listener: (event: Event, error: string) => void
+  ): this;
+  removeListener(
+    event: 'failed',
+    listener: (event: Event, error: string) => void
+  ): this;
+}