@lynx-js/lynxtron 0.0.1 → 0.0.3

package/apis/api/dock.d.ts

@@ -0,0 +1,88 @@
+// 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 { Menu } from './menu';
+import { NativeImage } from './native-image';
+
+export declare class Dock {
+  /**
+   * an ID representing the request.
+   *
+   * When `critical` is passed, the dock icon will bounce until either the
+   * application becomes active or the request is canceled.
+   *
+   * When `informational` is passed, the dock icon will bounce for one second.
+   * However, the request remains active until either the application becomes active
+   * or the request is canceled.
+   *
+   * > [!NOTE] This method can only be used while the app is not focused; when the
+   * app is focused it will return -1.
+   *
+   * @platform darwin
+   */
+  bounce(type?: 'critical' | 'informational'): number;
+  /**
+   * Cancel the bounce of `id`.
+   *
+   * @platform darwin
+   */
+  cancelBounce(id: number): void;
+  /**
+   * Bounces the Downloads stack if the filePath is inside the Downloads folder.
+   *
+   * @platform darwin
+   */
+  downloadFinished(filePath: string): void;
+  /**
+   * The badge string of the dock.
+   *
+   * @platform darwin
+   */
+  getBadge(): string;
+  /**
+   * The application's dock menu.
+   *
+   * @platform darwin
+   */
+  getMenu(): Menu | null;
+  /**
+   * Hides the dock icon.
+   *
+   * @platform darwin
+   */
+  hide(): void;
+  /**
+   * Whether the dock icon is visible.
+   *
+   * @platform darwin
+   */
+  isVisible(): boolean;
+  /**
+   * Sets the string to be displayed in the dock’s badging area.
+   *
+   * > [!IMPORTANT] You need to ensure that your application has the permission to
+   * display notifications for this method to work.
+   *
+   * @platform darwin
+   */
+  setBadge(text: string): void;
+  /**
+   * Sets the `image` associated with this dock icon.
+   *
+   * @platform darwin
+   */
+  setIcon(image: NativeImage | string): void;
+  /**
+   * Sets the application's dock menu.
+   *
+   * @platform darwin
+   */
+  setMenu(menu: Menu): void;
+  /**
+   * Resolves when the dock icon is shown.
+   *
+   * @platform darwin
+   */
+  show(): Promise<void>;
+}

package/apis/api/environment.d.ts

@@ -0,0 +1,9 @@
+// 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 declare function getVar(name: string): string | null;
+
+export declare function hasVar(name: string): boolean;
+
+export declare function setVar(name: string, value: string): boolean;

package/apis/api/event.d.ts

@@ -0,0 +1,8 @@
+// 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 type Event<Params extends object = {}> = {
+  preventDefault: () => void;
+  readonly defaultPrevented: boolean;
+} & Params;

package/apis/api/jump-list-item.d.ts

@@ -0,0 +1,83 @@
+// 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 JumpListCategory {
+  /**
+   * Array of `JumpListItem` objects if `type` is `tasks` or `custom`, otherwise it
+   * should be omitted.
+   */
+  items?: JumpListItem[];
+  /**
+   * Must be set if `type` is `custom`, otherwise it should be omitted.
+   */
+  name?: string;
+  /**
+   * One of the following:
+   */
+  type?: 'tasks' | 'frequent' | 'recent' | 'custom';
+}
+
+export interface JumpListSettings {
+  /**
+   * The minimum number of items that will be shown in the Jump List (for a more
+   * detailed description of this value see the MSDN docs).
+   */
+  minItems: number;
+  /**
+   * Array of `JumpListItem` objects that correspond to items that the user has
+   * explicitly removed from custom categories in the Jump List. These items must not
+   * be re-added to the Jump List in the **next** call to `app.setJumpList()`,
+   * Windows will not display any custom category that contains any of the removed
+   * items.
+   */
+  removedItems: JumpListItem[];
+}
+
+export interface JumpListItem {
+  /**
+   * The command line arguments when `program` is executed. Should only be set if
+   * `type` is `task`.
+   */
+  args?: string;
+  /**
+   * Description of the task (displayed in a tooltip). Should only be set if `type`
+   * is `task`. Maximum length 260 characters.
+   */
+  description?: string;
+  /**
+   * The index of the icon in the resource file. If a resource file contains multiple
+   * icons this value can be used to specify the zero-based index of the icon that
+   * should be displayed for this task. If a resource file contains only one icon,
+   * this property should be set to zero.
+   */
+  iconIndex?: number;
+  /**
+   * The absolute path to an icon to be displayed in a Jump List, which can be an
+   * arbitrary resource file that contains an icon (e.g. `.ico`, `.exe`, `.dll`). You
+   * can usually specify `process.execPath` to show the program icon.
+   */
+  iconPath?: string;
+  /**
+   * Path of the file to open, should only be set if `type` is `file`.
+   */
+  path?: string;
+  /**
+   * Path of the program to execute, usually you should specify `process.execPath`
+   * which opens the current program. Should only be set if `type` is `task`.
+   */
+  program?: string;
+  /**
+   * The text to be displayed for the item in the Jump List. Should only be set if
+   * `type` is `task`.
+   */
+  title?: string;
+  /**
+   * One of the following:
+   */
+  type?: 'task' | 'separator' | 'file';
+  /**
+   * The working directory. Default is empty.
+   */
+  workingDirectory?: string;
+}

package/apis/api/lynx-library.d.ts

@@ -0,0 +1,7 @@
+// 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 type LynxLibraryRegistry = Record<never, never>;
+
+export declare const lynx: LynxLibraryRegistry;

package/apis/api/lynx-template-bundle.d.ts

@@ -0,0 +1,32 @@
+// 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 class LynxTemplateBundle {
+  /**
+   * A pre-decoded Lynx template bundle.
+   *
+   * This class corresponds to Lynx SDK's `LynxTemplateBundle` (TemplateBundle),
+   * which is the output of Lynx's pre-decode capability. You can parse a Lynx
+   * App Bundle ahead of time to obtain a TemplateBundle and then load it via
+   * `LynxWindow.loadBundle(templateBundle)` for faster startup.
+   *
+   * Notes:
+   * - A LynxTemplateBundle instance can be non-null but still invalid. Use
+   *   `isValid()` to check and `getErrorMessage()` to inspect the parsing error.
+   * - The constructor accepts either a Node.js `Buffer` or any `ArrayBufferView`
+   *   containing the bundle bytes.
+   */
+  constructor(buffer: Buffer | ArrayBufferView);
+  /**
+   * Returns whether this TemplateBundle is valid.
+   */
+  isValid(): boolean;
+  /**
+   * Returns an error message when the TemplateBundle is invalid, otherwise an
+   * empty string.
+   */
+  getErrorMessage(): string;
+}
+
+export default LynxTemplateBundle;

package/apis/api/lynx-template-data.d.ts

@@ -0,0 +1,10 @@
+// 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 class LynxTemplateData<T extends object = Record<string, unknown>> {
+  constructor(value: T);
+  toObject(): T;
+}
+
+export default LynxTemplateData;

package/apis/api/lynx-update-meta.d.ts

@@ -0,0 +1,16 @@
+// 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 type LynxTemplateData from './lynx-template-data';
+
+export class LynxUpdateMeta {
+  constructor(init?: {
+    updateData?: LynxTemplateData;
+    globalProps?: LynxTemplateData;
+  });
+  updateData: LynxTemplateData;
+  globalProps: LynxTemplateData;
+}
+
+export default LynxUpdateMeta;

package/apis/api/lynx-window.d.ts

@@ -0,0 +1,405 @@
+// 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 { NativeImage } from './native-image';
+import { BaseWindow, WillResizeDetails } from './base-window';
+import { LynxTemplateBundle } from './lynx-template-bundle';
+import { LynxUpdateMeta } from './lynx-update-meta';
+import { Point } from '../structures/point';
+import { Rectangle } from '../structures/rectangle';
+
+export interface LynxPreference {
+  /**
+   * Script path to load before the Lynx page runs, mirroring Electron's
+   * `webPreferences.preload` option.
+   */
+  preload?: string;
+}
+
+export interface LynxWindowConstructorOptions {
+  /**
+   * Window's width in pixels. Default is `800`.
+   */
+  width?: number;
+  /**
+   * Window's height in pixels. Default is `600`.
+   */
+  height?: number;
+  /**
+   * (**required** if y is used) Window's left offset from screen. Default is to
+   * center the window.
+   */
+  x?: number;
+  /**
+   * (**required** if x is used) Window's top offset from screen. Default is to
+   * center the window.
+   */
+  y?: number;
+  /**
+   * The `width` and `height` would be used as the content area's size, which means
+   * the actual window's size will include the window frame's size and be slightly
+   * larger. Default is `false`.
+   */
+  useContentSize?: boolean;
+  /**
+   * Show window in the center of the screen.
+   */
+  center?: boolean;
+  /**
+   * Window's minimum width. Default is `0`.
+   */
+  minWidth?: number;
+  /**
+   * Window's minimum height. Default is `0`.
+   */
+  minHeight?: number;
+  /**
+   * Window's maximum width. Default is no limit.
+   */
+  maxWidth?: number;
+  /**
+   * Window's maximum height. Default is no limit.
+   */
+  maxHeight?: number;
+  /**
+   * Whether window is resizable. Default is `true`.
+   */
+  resizable?: boolean;
+  /**
+   * Whether window is movable. This is not implemented on Linux. Default is `true`.
+   */
+  movable?: boolean;
+  /**
+   * Whether window is minimizable. This is not implemented on Linux. Default is
+   * `true`.
+   */
+  minimizable?: boolean;
+  /**
+   * Whether window is maximizable. This is not implemented on Linux. Default is
+   * `true`.
+   */
+  maximizable?: boolean;
+  /**
+   * Whether window is closable. This is not implemented on Linux. Default is `true`.
+   */
+  closable?: boolean;
+  /**
+   * Whether the window can be focused. Default is `true`. On Windows setting
+   * `focusable: false` also implies setting `skipTaskbar: true`. On Linux setting
+   * `focusable: false` makes the window stop interacting with wm, so the window will
+   * always stay on top in all workspaces.
+   */
+  focusable?: boolean;
+  /**
+   * Whether the window should always stay on top of other windows. Default is
+   * `false`.
+   */
+  alwaysOnTop?: boolean;
+  /**
+   * Whether the window should show in fullscreen. When explicitly set to `false` the
+   * fullscreen button will be hidden or disabled on macOS. Default is `false`.
+   */
+  fullscreen?: boolean;
+  /**
+   * Whether the window can be put into fullscreen mode. On macOS, also whether the
+   * maximize/zoom button should toggle full screen mode or maximize window. Default
+   * is `true`.
+   */
+  fullscreenable?: boolean;
+  /**
+   * Use pre-Lion fullscreen on macOS. Default is `false`.
+   */
+  simpleFullscreen?: boolean;
+  /**
+   * Whether to show the window in taskbar. Default is `false`.
+   */
+  skipTaskbar?: boolean;
+  hiddenInMissionControl?: boolean;
+  /**
+   * The window icon. On Windows it is recommended to use `ICO` icons to get best
+   * visual effects, you can also leave it undefined so the executable's icon will be
+   * used.
+   */
+  icon?: NativeImage | string;
+  /**
+   * Whether window should be shown when created. Default is `true`.
+   */
+  show?: boolean;
+  /**
+   * Specify `false` to create a [Frameless Window]. Default is `true`.
+   */
+  frame?: boolean;
+  /**
+   * Specify parent window. Default is `null`.
+   */
+  parent?: LynxWindow;
+  /**
+   * Whether this is a modal window. This only works when the window is a child
+   * window. Default is `false`.
+   */
+  modal?: boolean;
+  /**
+   * Whether to hide cursor when typing. Default is `false`.
+   */
+  disableAutoHideCursor?: boolean;
+  /**
+   * Auto hide the menu bar unless the `Alt` key is pressed. Default is `false`.
+   */
+  autoHideMenuBar?: boolean;
+  /**
+   * Enable the window to be resized larger than screen. Only relevant for macOS, as
+   * other OSes allow larger-than-screen windows by default. Default is `false`.
+   */
+  enableLargerThanScreen?: boolean;
+  /**
+   * Window's background color as a hexadecimal value, like `#66CD00` or `#FFF` or
+   * `#80FFFFFF` (alpha in #AARRGGBB format is supported if `transparent` is set to
+   * `true`). Default is `#FFF` (white).
+   */
+  backgroundColor?: string;
+  /**
+   * Whether window should have a shadow. Default is `true`.
+   */
+  hasShadow?: boolean;
+  /**
+   * Set the initial opacity of the window, between 0.0 (fully transparent) and 1.0
+   * (fully opaque). This is only implemented on Windows and macOS.
+   */
+  opacity?: number;
+  /**
+   * Makes the window [transparent]. Default is `false`. On Windows, does not work
+   * unless the window is frameless.
+   */
+  transparent?: boolean;
+  /**
+   * The type of window, default is normal window. See more about this below.
+   */
+  type?: string;
+  /**
+   * Specify how the material appearance should reflect window activity state on
+   * macOS. Must be used with the `vibrancy` property. Possible values are:
+   */
+  visualEffectState?: 'followWindow' | 'active' | 'inactive';
+  /**
+   * The style of window title bar. Default is `default`. Only supported on macOS.
+   * Other platforms ignore this option.
+   *
+   * @platform darwin
+   */
+  titleBarStyle?: 'default' | 'hidden' | 'hiddenInset' | 'customButtonsOnHover';
+  /**
+   * Set a custom position for the traffic light buttons in frameless windows.
+   */
+  trafficLightPosition?: Point;
+  /**
+   * Whether frameless window should have rounded corners on macOS. Default is
+   * `true`.
+   */
+  roundedCorners?: boolean;
+  /**
+   * Use `WS_THICKFRAME` style for frameless windows on Windows, which adds standard
+   * window frame. Setting it to `false` will remove window shadow and window
+   * animations. Default is `true`.
+   */
+  thickFrame?: boolean;
+  /**
+   * Add a type of vibrancy effect to the window, only on macOS. Can be
+   * `appearance-based`, `light`, `dark`, `titlebar`, `selection`, `menu`, `popover`,
+   * `sidebar`, `medium-light`, `ultra-dark`, `header`, `sheet`, `window`, `hud`,
+   * `fullscreen-ui`, `tooltip`, `content`, `under-window`, or `under-page`. Please
+   * note that `appearance-based`, `light`, `dark`, `medium-light`, and `ultra-dark`
+   * are deprecated and have been removed in macOS Catalina (10.15).
+   */
+  vibrancy?:
+    | 'appearance-based'
+    | 'light'
+    | 'dark'
+    | 'titlebar'
+    | 'selection'
+    | 'menu'
+    | 'popover'
+    | 'sidebar'
+    | 'medium-light'
+    | 'ultra-dark'
+    | 'header'
+    | 'sheet'
+    | 'window'
+    | 'hud'
+    | 'fullscreen-ui'
+    | 'tooltip'
+    | 'content'
+    | 'under-window'
+    | 'under-page';
+  /**
+   * Tab group name, allows opening the window as a native tab on macOS 10.12+.
+   * Windows with the same tabbing identifier will be grouped together. This also
+   * adds a native new tab button to your window's tab bar and allows your `app` and
+   * window to receive the `new-window-for-tab` event.
+   */
+  tabbingIdentifier?: string;
+  /**
+   * Lynx page preferences.
+   */
+  lynxPreference?: LynxPreference;
+
+  title?: string;
+}
+
+export interface LynxBridgeInvokeEvent {
+  sendReply(result?: unknown): boolean;
+}
+
+export type LynxBridgeInvokeListener = (
+  event: LynxBridgeInvokeEvent,
+  methodName: string,
+  params: unknown
+) => void | Promise<void>;
+
+export type LynxBridgeMessageListener = (
+  methodName: string,
+  params: unknown
+) => void;
+
+export declare class LynxWindow extends BaseWindow {
+  /**
+   * LynxWindow
+   */
+  constructor(options?: LynxWindowConstructorOptions);
+  on(event: '-lynx-invoke', listener: LynxBridgeInvokeListener): this;
+  on(event: '-lynx-message', listener: LynxBridgeMessageListener): this;
+  on(
+    event: 'app-command',
+    listener: (event: Event, command: string) => void
+  ): this;
+  on(event: 'blur', listener: (event: Event) => void): this;
+  on(event: 'close', listener: (event: Event) => void): this;
+  on(event: 'closed', listener: () => void): this;
+  on(event: 'will-enter-full-screen', listener: () => void): this;
+  on(event: 'enter-full-screen', listener: () => void): this;
+  on(event: 'focus', listener: (event: Event) => void): this;
+  on(event: 'hide', listener: () => void): this;
+  on(event: 'will-leave-full-screen', listener: () => void): this;
+  on(event: 'leave-full-screen', listener: () => void): this;
+  on(event: 'maximize', listener: () => void): this;
+  on(event: 'minimize', listener: () => void): this;
+  on(event: 'move', listener: () => void): this;
+  on(event: 'moved', listener: () => void): this;
+  on(event: 'resize', listener: () => void): this;
+  on(event: 'resized', listener: () => void): this;
+  on(event: 'restore', listener: () => void): this;
+  on(
+    event: 'always-on-top-changed',
+    listener: (event: Event, isAlwaysOnTop: boolean) => void
+  ): this;
+  on(
+    event: 'rotate-gesture',
+    listener: (event: Event, rotation: number) => void
+  ): this;
+  on(event: 'session-end', listener: (event: any) => void): this;
+  on(event: 'sheet-begin', listener: () => void): this;
+  on(event: 'sheet-end', listener: () => void): this;
+  on(event: 'new-window-for-tab', listener: (event: Event) => void): this;
+  on(event: 'show', listener: () => void): this;
+  on(event: 'swipe', listener: (event: Event, direction: string) => void): this;
+  on(
+    event: 'system-context-menu',
+    listener: (event: Event, point: Point) => void
+  ): this;
+  on(event: 'unmaximize', listener: () => void): this;
+  on(
+    event: 'will-move',
+    listener: (event: Event, newBounds: Rectangle) => void
+  ): this;
+  on(
+    event: 'will-resize',
+    listener: (
+      event: Event,
+      newBounds: Rectangle,
+      details: WillResizeDetails
+    ) => void
+  ): this;
+  /**
+   * The window with the given `id`.
+   */
+  static fromId(id: number): LynxWindow | null;
+  /**
+   * An array of all opened windows.
+   */
+  static getAllWindows(): LynxWindow[];
+  /**
+   * The window that is focused in this application, otherwise returns `null`.
+   */
+  static getFocusedWindow(): LynxWindow | null;
+  tabbingIdentifier: string;
+  /**
+   * Starts loading a Lynx bundle from a local file path.
+   *
+   * Returns `true` when the request is accepted synchronously. Final load
+   * completion is reported asynchronously via window events such as
+   * `ready-to-show` and `--lynx-error`.
+   */
+  loadFile(
+    filePath: string,
+    options?: {
+      data?: Object;
+      globalProps?: Object;
+    }
+  ): boolean;
+  /**
+   * Load a Lynx bundle from a URL.
+   *
+   * Supported URLs include remote URLs such as `https://...` and local file
+   * URLs such as `file:///abs/path/to/main.lynx.bundle`.
+   *
+   * Returns `true` when the request is accepted synchronously. Final load
+   * completion is reported asynchronously via window events such as
+   * `ready-to-show` and `--lynx-error`.
+   */
+  loadURL(
+    url: string,
+    options?: {
+      data?: Object;
+      globalProps?: Object;
+    }
+  ): boolean;
+  /**
+   * Load a pre-decoded Lynx template bundle.
+   *
+   * Returns `true` when the request is accepted synchronously. Final load
+   * completion is reported asynchronously via window events such as
+   * `ready-to-show` and `--lynx-error`.
+   */
+  loadBundle(
+    templateBundle: LynxTemplateBundle,
+    options?: {
+      data?: Object;
+      globalProps?: Object;
+    }
+  ): boolean;
+  /**
+   * Updates the Lynx view with new template data.
+   *
+   * This is the primary entry point for triggering template data updates on the client side.
+   *
+   * - `meta.updateData`: Template data content used to update the page.
+   * - `meta.globalProps`: Global props content used to update the page.
+   *
+   * When called before the first template load, updates are cached and applied after the view is created and the first load finishes.
+   */
+  updateMetaData(meta: LynxUpdateMeta): boolean;
+  /**
+   * Set global props for the Lynx view.
+   *
+   * This is the primary entry point for setting global props on the client side.
+   *
+   * When called before the first template load, updates are cached and applied after the view is created and the first load finishes.
+   */
+  setGlobalProps(globalProps: Object): boolean;
+  /**
+   * Send global event to the window.
+   * Lynx-side GlobalEventListener signature:
+   * `(...args) => { }`
+   */
+  sendGlobalEvent(eventName: string, ...args: any[]): boolean;
+}