MMRL

https://mmrl.dev/guide/
Admin
MMRL is an advanced, open-source Android application for streamlined management of Magisk, KernelSU,...
Tokens:17,969
Snippets:228
Trust Score:7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install mmrl-util dependencies

Source: https://mmrl.dev/guide/mmrl-util

Install the required package using pip.

```shell
pip3 install mmrl-util
```

--------------------------------

### Apply Custom CSS Styles

Source: https://mmrl.dev/guide/webuix/patching

Example content for patch.css to modify UI elements like headers, backgrounds, and buttons.

```css
/* Hide header bar */
.header-bar {
  display: none !important;
}

/* Change background color */
body {
  background-color: #1e1e2e !important;
}

/* Style buttons */
button {
  border-radius: 8px !important;
  padding: 6px 12px !important;
}
```

--------------------------------

### Check if Installing in MMRL

Source: https://mmrl.dev/guide/installer

Verifies if the current environment is running within MMRL by checking the MMRL variable.

```shell
if [ ! -z $MMRL ]; then
  ui_print "Installing in MMRL"
fi
```

--------------------------------

### Configure repository via CLI arguments

Source: https://mmrl.dev/guide/mmrl-util

Initialize the configuration file by passing parameters directly as command-line arguments.

```shell
cli.py config --write name="Your Magisk Repo" base_url="https://you.github.io/magisk-modules-repo/" max_num=3 enable_log=true log_dir="log"
```

--------------------------------

### Initialize Lua Plugin

Source: https://mmrl.dev/guide/webuix/mx/plugins

Create an index.lua file in the webroot folder to serve as the entry point for Lua plugins.

```lua
require("lua/plugin")
```

--------------------------------

### Configure repository via stdin

Source: https://mmrl.dev/guide/mmrl-util

Initialize the configuration file by piping JSON content directly to the CLI.

```shell
cli.py config --stdin << EOF
{
  "name": "Your Magisk Repo",
  "base_url": "https://you.github.io/magisk-modules-repo/",
  "max_num": 3,
  "enable_log": true,
  "log_dir": "log"
}
EOF
```

--------------------------------

### Retrieve and check application flags

Source: https://mmrl.dev/guide/webuix/application-info-flags

Demonstrates how to fetch application info using the Package Manager and check for the system app flag using bitwise operations.

```javascript
// To use the `global` variable you require the WXU Plugin
const pm = global.require("pm")
const info = JSON.parse(pm.getApplicationInfo("com.goolag.pif"))

let number = info.flags;
// flag for system apps
let flag = 1<<0;

if ((number & flag) != 0) {
    console.log("This app is a system app");
} else {
    console.log("This app is not a system app");
}
```

--------------------------------

### View mmrl-util help

Source: https://mmrl.dev/guide/mmrl-util

Display the help menu to see available commands and options.

```text
mmrl-util --help
usage: mmrl-util [-h] [-v] [-V] command ...

Magisk Modules Repo Util

positional arguments:
  command
    config            Modify config of repository.
    track             Module tracks utility.
    github            Generate tracks from GitHub.
    sync              Sync modules in repository.
    index             Generate modules.json from local.
    check             Content check and migrate.
    sitemap           Sitemap generator.

options:
  -h, --help          Show this help message and exit.
  -v, --version       Show util version and exit.
  -V, --version-code  Show util version code and exit.
```

--------------------------------

### Check Multiple Application Flags

Source: https://mmrl.dev/guide/webuix/application-info-flags

Demonstrates how to manually define flag constants and perform bitwise AND operations to verify specific application states.

```javascript
const info = JSON.parse(pm.getApplicationInfo("com.example.app"));
const flags = info.flags;

// Define flag constants
const FLAG_SYSTEM = 1<<0;
const FLAG_DEBUGGABLE = 1<<1;
const FLAG_ALLOW_BACKUP = 1<<15;

// Check multiple flags
const isSystem = (flags & FLAG_SYSTEM) != 0;
const isDebuggable = (flags & FLAG_DEBUGGABLE) != 0;
const allowsBackup = (flags & FLAG_ALLOW_BACKUP) != 0;

console.log(`System app: ${isSystem}`);
console.log(`Debuggable: ${isDebuggable}`);
console.log(`Allows backup: ${allowsBackup}`);
```

--------------------------------

### moduleInterface.createShortcut()

Source: https://mmrl.dev/guide/webuix/shortcuts

Creates a shortcut on the home screen using the configuration defined in config.mmrl.json or custom parameters.

```APIDOC
## moduleInterface.createShortcut()

### Description
Creates a shortcut for the WebUI on the device home screen. This method can either use the default configuration from `config.mmrl.json` or accept custom title and icon parameters.

### Parameters
- **title** (string) - Optional - The title of the shortcut displayed on the home screen.
- **icon** (string) - Optional - The filename of the image located in the webroot to be used as the shortcut icon.

### Usage Example
```javascript
const moduleInterface = window.$example_module;

// Uses title and icon from config.mmrl.json
moduleInterface.createShortcut();

// Uses custom title and icon
moduleInterface.createShortcut("Custom Title", "icon.webp");
```
```

--------------------------------

### createShortcut()

Source: https://mmrl.dev/guide/webuix/mx/application

Pins a home-screen shortcut for the WebUI on the device launcher.

```APIDOC
## createShortcut()

### Description
Pins a home-screen shortcut for this WebUI on the device launcher. Note: This is currently not implemented and subject to change.
```

--------------------------------

### Navigate to Configuration Directory

Source: https://mmrl.dev/guide/webuix/patching

The path where custom patches for a specific WebUI X instance must be placed.

```text
/data/adb/.config/<id>/
```

--------------------------------

### Define Complete App Structure

Source: https://mmrl.dev/guide/webuix/css-setup

Standard boilerplate for importing required CSS modules and setting up base layout styles.

```css
@import "https://mui.kernelsu.org/internal/insets.css";
@import "https://mui.kernelsu.org/internal/colors.css";

body {
  background-color: var(--background);
  color: var(--onBackground);
  margin: 0;
  padding: 0;
}

.app-bar {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  height: 64px;
  padding-top: var(--window-inset-top);
  background-color: var(--surface);
  color: var(--onSurface);
  z-index: 1000;
}

.main-content {
  margin-top: calc(64px + var(--window-inset-top));
  margin-bottom: calc(56px + var(--window-inset-bottom));
  padding: 16px;
}
```

--------------------------------

### Create Home Screen Shortcut via JavaScript

Source: https://mmrl.dev/guide/webuix/shortcuts

Use the module interface to register a shortcut, either using the default configuration or custom parameters.

```javascript
const moduleInterface = window.$example_module;

// Picks `title` and `icon` from config.json
moduleInterface.createShortcut()

// Define your own paths from webroot
moduleInterface.createShortcut("Custom Title", "icon.webp")
```

--------------------------------

### Define Plugin Directory Structure

Source: https://mmrl.dev/guide/webuix/mx/plugins

Recommended file system layout for organizing plugin files and the webroot directory.

```text
├── module.prop
└── webroot
    ├── index.lua
    └── lua
        └── plugin.lua
```

--------------------------------

### Define README URL

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Provide the URL to the project's README file.

```yaml
readme: "https://github.com/owner/project#readme"
```

--------------------------------

### Implement ES Module Scripts

Source: https://mmrl.dev/guide/webuix/patching

Shows how to use ES modules by importing a helper function into a main body script.

```javascript
// Example module script using ES modules
import { greet } from "./greet-helper.mjs";

window.addEventListener("DOMContentLoaded", () => {
  greet("WebUI X Portable (module script)");
});
```

```javascript
// Example helper module
export function greet(name) {
  console.log(`[WebUI X] Hello from ${name}!`);
  alert(`Greetings from ${name}!`);
}
```

--------------------------------

### Configure HTML structure for WebUI X

Source: https://mmrl.dev/guide/webuix/index-setup

Includes the required CSS links for window safe area insets and theme colors to ensure a native feel.

```html
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>ModConf Compose WebUI</title>
    <!-- Window Safe Area Insets -->
    <link rel="stylesheet" type="text/css" href="https://mui.kernelsu.org/internal/insets.css" />
    <!-- App Theme which the user has currently selected -->
    <link rel="stylesheet" type="text/css" href="https://mui.kernelsu.org/internal/colors.css" />
    <!-- Your styles -->
    <link rel="stylesheet" type="text/css" href="styles.css" />

  </head>
  <body>
    <div class="scaffold">
      <div class="card">
        <span>Hello from WebUI!</span>
      </div>
    </div>
  </body>
</html>
```

--------------------------------

### Define manager configuration

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Configure settings for specific root providers like Magisk, KernelSU, or APatch.

```yaml
manager:
  magisk:
    min: 25200,
    devices: []
    arch: []
    require: []
```

--------------------------------

### Check multiple application flags

Source: https://mmrl.dev/guide/webuix/application-info-flags

Shows how to define multiple flag constants and verify their status using the bitwise AND operator.

```javascript
const FLAG_SYSTEM = 1<<0;  // Value: 1
const FLAG_DEBUGGABLE = 1<<1;  // Value: 2

// Check if app is a system app
if ((info.flags & FLAG_SYSTEM) != 0) {
    console.log("System app");
}

// Check if app is debuggable
if ((info.flags & FLAG_DEBUGGABLE) != 0) {
    console.log("Debuggable app");
}
```

--------------------------------

### Define Dependencies

Source: https://mmrl.dev/guide/mmrl-util/track-json

Lists required tracks or dependencies.

```yaml
require:
  - "track1"
  - "track2"
```

--------------------------------

### Enable logging

Source: https://mmrl.dev/guide/mmrl-util/config-json

Toggles repository logging functionality.

```json
"enable_log": true
```

--------------------------------

### Enable Track

Source: https://mmrl.dev/guide/mmrl-util/track-json

Sets the activation status of the track.

```yaml
enable: true
```

--------------------------------

### Define Media Assets

Source: https://mmrl.dev/guide/mmrl-util/track-json

Sets paths or URLs for icons, covers, and screenshots.

```yaml
icon: "https://example.com/icon.png"
```

```yaml
cover: "https://example.com/cover.png"
```

```yaml
screenshots:
  - "https://example.com/screenshot1.png"
  - "https://example.com/screenshot2.png"
```

--------------------------------

### Specify Supported Architectures

Source: https://mmrl.dev/guide/mmrl-util/track-json

List the CPU architectures supported by the track.

```yaml
arch:
  - "arm64-v8a"
  - "x86_64"
```

--------------------------------

### WebUI X Portable Configuration Directory Structure

Source: https://mmrl.dev/guide/webuix/patching

The required directory structure for injecting custom scripts and styles into the WebUI X environment.

```text
/data/adb/.config/<id>/
│
├── js/
│   ├── head/                   # Scripts injected into <head>
│   │   └── example-head.js
│   └── body/                   # Scripts injected into <body>
│       ├── example-body.js
│       └── example-module.mjs
│
└── style/
└── patch.css   # Custom CSS styles
```

--------------------------------

### WebUI X Configuration Structure

Source: https://mmrl.dev/guide/webuix/config

The base JSON schema for defining module configuration properties.

```json
{
  "modId": "string",
  "require": {
    "packages": [
      {
        "code": -1,
        "packageName": "string or array of strings",
        "supportText": "string",
        "supportLink": "string"
      }
    ]
  },
  "permissions": ["string", "..."],
  "historyFallback": false,
  "title": "string",
  "icon": "string",
  "windowResize": true,
  "backHandler": true,
  "backInterceptor": null,
  "refreshInterceptor": "string",
  "exitConfirm": true,
  "pullToRefresh": false,
  "historyFallbackFile": "index.html",
  "autoStatusBarsStyle": true,
  "dexFiles": [
    {
      "type": "dex | apk",
      "path": "string",
      "className": "string",
      "cache": true,
    }
  ],
  "killShellWhenBackground": true,
  "contentSecurityPolicy": "string",
  "caching": true,
  "cachingMaxAge": 86400
}
```

--------------------------------

### fs.inputstream(path, options)

Source: https://mmrl.dev/guide/webuix/mx/filesystem

Opens a file as an input stream.

```APIDOC
## fs.inputstream(path, options)

### Description
Opens a file as an input stream.

### Parameters
- **path** (string) - Required - Path to the file.
- **options** (Omit<FileOptions, "encoding">) - Required - Stream open options. The encoding option is not applicable.

### Returns
- **Promise<InputStream>** - A readable input stream.
```

--------------------------------

### Enable Event Handling in Configuration

Source: https://mmrl.dev/guide/webuix/events

Add these options to your configuration file to enable back button handling and JavaScript interception.

```jsonc
{
  // Enables default back button handling (ignored if `backInterceptor` is set)
  "backHandler": true,
  // Use JavaScript to control back button behavior
  "backInterceptor": "javascript"
}
```

--------------------------------

### Define project icon

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Set the URL for the project icon, recommended size 512x512 pixels.

```yaml
icon: "https://example.com/icon.png"
```

--------------------------------

### Define base URL

Source: https://mmrl.dev/guide/mmrl-util/config-json

Sets the base URL for fetching modules and tracks. An ending slash is mandatory.

```json
"base_url": "https://example.com/"
```

--------------------------------

### Clone the MMRL Repository

Source: https://mmrl.dev/guide

Use this command to download the source code from GitHub to your local machine.

```bash
git clone https://github.com/MMRLApp/MMRL.git
```

--------------------------------

### Configure WebUI Shortcut in config.mmrl.json

Source: https://mmrl.dev/guide/webuix/shortcuts

Define the shortcut title and icon path within the module's configuration file.

```json
{
  "title": "bindhosts",
  "icon": "bindhosts-icon.jpg"
}
```

--------------------------------

### Define support URL

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Specify the project's support page or issue tracker.

```yaml
support: https://github.com/owner/project/issues
```

--------------------------------

### Define homepage URL

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Provide the URL to the project's homepage.

```yaml
homepage: "https://example.com"
```

--------------------------------

### Define support URL

Source: https://mmrl.dev/guide/mmrl-util/config-json

Sets the URL for the repository support page.

```json
"support": "url"
```

--------------------------------

### fs.outputstream(path, options)

Source: https://mmrl.dev/guide/webuix/mx/filesystem

Opens a file as an output stream.

```APIDOC
## fs.outputstream(path, options)

### Description
Opens a file as an output stream.

### Parameters
- **path** (string) - Required - Path to the file.
- **options** (Omit<FileOptions, "encoding">) - Required - Stream open options. The encoding option is not applicable.

### Returns
- **Promise<OutputStream>** - A writable output stream.
```

--------------------------------

### Define license

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Specify the project license using an SPDX identifier.

```yaml
license: "MIT"
```

--------------------------------

### Global FileSystem Instance

Source: https://mmrl.dev/guide/webuix/mx/filesystem

Declaration of the global filesystem API instance.

```typescript
/**
 * Global filesystem API instance.
 */
declare var fs: FileSystem
```

--------------------------------

### Define website URL

Source: https://mmrl.dev/guide/mmrl-util/config-json

Sets the URL for the repository's official website.

```json
"website": "https://mmrl.dergoogler.com"
```

--------------------------------

### Set Track Options

Source: https://mmrl.dev/guide/mmrl-util/track-json

Configure global track settings such as archive compression methods and remote metadata handling.

```yaml
options:
  archive:
    compression: "gzip"
  disableRemoteMetadata: true
```

--------------------------------

### Define screenshots

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Provide an array of URLs for module screenshots.

```yaml
"screenshots": [
"https://example.com/screenshot1.png",
"https://example.com/screenshot2.png"
]
```

--------------------------------

### prompt(options, onValid)

Source: https://mmrl.dev/guide/webuix/mx/application

Displays a native text-input dialog.

```APIDOC
## prompt(options, onValid)

### Description
Shows a native text-input dialog and resolves to the string the user entered, or an empty string if they cancelled.

### Parameters
- **options** (PromptOptions) - Required - Dialog and input configuration.
- **onValid** (function) - Optional - Callback invoked with the current input value whenever it changes. Return true to enable the confirm button, false to disable it.

### Returns
- **Promise<string | null>** - Resolves to the submitted string, or null if cancelled.
```

--------------------------------

### confirm(options)

Source: https://mmrl.dev/guide/webuix/mx/application

Displays a native confirmation dialog.

```APIDOC
## confirm(options)

### Description
Shows a native confirmation dialog and resolves to true if the user tapped the confirm button, or false if they tapped cancel or dismissed the dialog.

### Parameters
- **options** (DialogOptions) - Required - Dialog configuration.

### Returns
- **Promise<boolean>** - Resolves to true (confirmed) or false (cancelled).
```

--------------------------------

### Define repository description

Source: https://mmrl.dev/guide/mmrl-util/config-json

Sets a short text description for the repository.

```json
"description": "My repository description."
```

--------------------------------

### Import WebUI X CSS APIs

Source: https://mmrl.dev/guide/webuix/css-setup

Include these imports at the top of your style.css file to access insets and color variables.

```css
@import "https://mui.kernelsu.org/internal/insets.css";
@import "https://mui.kernelsu.org/internal/colors.css";

/* @deprecated */
@import "https://mui.kernelsu.org/mmrl/insets.css";
/* @deprecated */
@import "https://mui.kernelsu.org/mmrl/colors.css";
```

--------------------------------

### Define log directory

Source: https://mmrl.dev/guide/mmrl-util/config-json

Sets the file system path where logs are stored.

```json
"log_dir": "log"
```

--------------------------------

### FileSystem Interface

Source: https://mmrl.dev/guide/webuix/mx/filesystem

The FileSystem interface provides methods for file I/O operations and defines POSIX-style file flags.

```APIDOC
## FileSystem.readFile(path: string, options: FileOptions)

### Description
Reads a file asynchronously.

### Parameters
- **path** (string) - Required - Path to the file.
- **options** (FileOptions) - Required - File reading options.

### Returns
- **Promise<string>** - The file contents.

## FileSystem.readFileSync(path: string, options: FileOptions)

### Description
Reads a file synchronously.

### Parameters
- **path** (string) - Required - Path to the file.
- **options** (FileOptions) - Required - File reading options.

### Returns
- **string | null** - The file contents, or null if the read fails.

## FileSystem.writeFile(path: string, options: FileOptions)

### Description
Writes a file asynchronously.

### Parameters
- **path** (string) - Required - Path to the file.
- **options** (FileOptions) - Required - File writing options.

### Returns
- **Promise<void>**
```

--------------------------------

### Configure Package Manager Requirements

Source: https://mmrl.dev/guide/mmrl-util/track-json

Define minimum versions, supported devices, architectures, and dependencies for specific package managers like Magisk or KernelSU.

```yaml
manager:
  magisk:
    min: 25200
    devices:
      - "device1"
    arch:
      - "arm64-v8a"
    require:
      - "module1"
  kernelsu:
    min: 10000
    devices:
      - "device2"
    arch:
      - "x86_64"
    require:
      - "module2"
```

--------------------------------

### Define FileSystem interfaces and types

Source: https://mmrl.dev/guide/webuix/mx/filesystem

TypeScript definitions for byte streams, file options, and the FileSystem interface.

```typescript
/**
 * Represents a readable byte stream.
 */
interface InputStream {
    /**
     * Reads a single byte from the stream.
     *
     * @returns The byte value, or `-1` if the end of the stream has been reached.
     */
    read(): number

    /**
     * Reads bytes into the provided buffer.
     *
     * @param b Destination buffer.
     * @returns Number of bytes read, or `-1` if the end of the stream has been reached.
     */
    read(b: Array<number>): number

    /**
     * Reads up to `len` bytes into the provided buffer starting at `off`.
     *
     * @param b Destination buffer.
     * @param off Offset within the buffer to begin writing.
     * @param len Maximum number of bytes to read.
     * @returns Number of bytes read, or `-1` if the end of the stream has been reached.
     */
    read(b: Array<number>, off: number, len: number): number

    /**
     * Skips over and discards bytes from the stream.
     *
     * @param n Number of bytes to skip.
     * @returns Actual number of bytes skipped.
     */
    skip(n: number): number

    /**
     * Marks the current position in the stream.
     *
     * @param readLimit Maximum number of bytes that can be read before the mark becomes invalid.
     */
    mark(readLimit: number): void

    /**
     * Resets the stream position to the last marked location.
     */
    reset(): void

    /**
     * Indicates whether this stream supports mark/reset operations.
     */
    markSupported(): void

    /**
     * Returns the number of bytes that can be read without blocking.
     *
     * @returns Number of available bytes.
     */
    available(): number

    /**
     * Closes the stream and releases any associated resources.
     */
    close(): void
}

/**
 * Represents a writable byte stream.
 */
interface OutputStream {
    /**
     * Writes the provided bytes to the stream.
     *
     * @param chunk Bytes to write.
     */
    write(chunk: Array<number>): void

    /**
     * Closes the stream and releases any associated resources.
     */
    close(): void
}

/**
 * Options used when reading or writing files.
 */
type FileOptions = {
    /**
     * Character encoding used for file contents.
     *
     * @default "UTF-8"
     */
    encoding: string

    /**
     * File open flags.
     * Use the constants exposed by {@link FileSystem}.
     */
    flags: number

    /**
     * File permission mode.
     */
    mode: number
}

/**
 * Provides access to filesystem operations and POSIX-style file flags.
 */
interface FileSystem {
    /**
     * Error if the file already exists.
     */
    O_EXCL: number

    /**
     * Do not assign the opened file as the controlling terminal.
     */
    O_NOCTTY: number

    /**
     * Fail if the target path is a symbolic link.
     */
    O_NOFOLLOW: number

    /**
     * Open file in non-blocking mode.
     */
    O_NONBLOCK: number

    /**
     * Open file for read-only access.
     */
    O_RDONLY: number

    /**
     * Open file for both reading and writing.
     */
    O_RDWR: number

    /**
     * Synchronous I/O file integrity completion.
     */
    O_SYNC: number

    /**
     * Synchronized data I/O completion.
     *
     * Below Android 8.1 this value will be `0`.
     */
    O_DSYNC: number

    /**
     * Truncate the file to zero length when opening.
     */
    O_TRUNC: number

    /**
     * Open file for write-only access.
     */
    O_WRONLY: number

    /**
     * Mask for access mode bits.
     */
    O_ACCMODE: number

    /**
     * Append all writes to the end of the file.
     */
    O_APPEND: number

    /**
     * Close the file descriptor on process execution.
     *
     * Below Android 8.1 this value will be `0`.
     */
    O_CLOEXEC: number

    /**
     * Create the file if it does not already exist.
     */
    O_CREAT: number

    /**
     * Reads a file asynchronously.
     *
     * @param path Path to the file.
     * @param options File reading options.
     * @returns The file contents.
     */
    readFile(path: string, options: FileOptions): Promise<string>

    /**
     * Reads a file synchronously.
     *
     * @param path Path to the file.
     * @param options File reading options.
     * @returns The file contents, or `null` if the read fails.
     */
    readFileSync(path: string, options: FileOptions): string | null

    /**
     * Writes a file asynchronously.
     *
     * @param path Path to the file.
     * @param options File writing options.
     */
    writeFile(path: string, options: FileOptions): Promise<void>
```

--------------------------------

### Set Max Instances

Source: https://mmrl.dev/guide/mmrl-util/track-json

Defines the maximum number of users or instances.

```yaml
max_num: 100
```

--------------------------------

### exit()

Source: https://mmrl.dev/guide/webuix/mx/application

Closes the WebUI and returns control to the host application.

```APIDOC
## exit()

### Description
Closes the WebUI and returns control to the host application or launcher.
```

--------------------------------

### FileSystem API Interface Definitions

Source: https://mmrl.dev/guide/webuix/mx/filesystem

Definitions for file access and stream management methods.

```typescript
    /**
     * Tests whether the current process can access a file.
     *
     * @param path Path to the file.
     * @param mode Access mode to check.
     * @returns `true` if access is allowed; otherwise `false`.
     */
    access(path: string, mode: number): Promise<boolean>

    /**
     * Opens a file as an input stream.
     *
     * @param path Path to the file.
     * @param options Stream open options. The `encoding` option is not applicable.
     * @returns A readable input stream.
     */
    inputstream(
        path: string,
        options: Omit<FileOptions, "encoding">
    ): Promise<InputStream>

    /**
     * Opens a file as an output stream.
     *
     * @param path Path to the file.
     * @param options Stream open options. The `encoding` option is not applicable.
     * @returns A writable output stream.
     */
    outputstream(
        path: string,
        options: Omit<FileOptions, "encoding">
    ): Promise<OutputStream>
}
```

--------------------------------

### Display a text-input prompt

Source: https://mmrl.dev/guide/webuix/mx/application

Shows a native text-input dialog and returns the user's input or null if cancelled.

```ts
const email = await webui.prompt(
  {
    title: "Enter your email",
    message: null,
    default: "",
    launchKeyboard: true,
    buttons: { confirmText: "Submit", cancelText: "Cancel" },
    theme: "md3",
  },
  () => /\S+@\S+\.\S+/.test(currentInput),
);
```

--------------------------------

### Define repository name

Source: https://mmrl.dev/guide/mmrl-util/config-json

Sets the display name for the Magisk repository.

```json
"name": "Template Magisk Modules Repository"
```

--------------------------------

### Define cover image

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Set the URL for the project's featured cover graphic.

```yaml
cover: "https://example.com/cover.png"
```

--------------------------------

### Configure Prompt Dialogs

Source: https://mmrl.dev/guide/webuix/mx/application

Interface for dialogs that collect user input, extending base dialog options.

```ts
/**
 * Configuration for a dialog that collects a text value from the user.
 *
 * Extends {@link DialogOptions} with input-specific settings.
 * Pass this to {@link WebUI.prompt}.
 *
 * @example
 * ```ts
 * const name = await webui.prompt({
 *   title: "Enter your name",
 *   message: null,
 *   default: "",
 *   launchKeyboard: true,
 *   buttons: { confirmText: "OK", cancelText: "Skip" },
 *   theme: "md3",
 * });
 * ```
 */
interface PromptOptions extends DialogOptions {
    /**
     * Pre-filled value shown in the input field when the dialog opens.
     *
     * @default ""
     */
    default: string;

    /**
     * Whether to open the soft keyboard automatically when the dialog appears.
     * Set to `false` to suppress the keyboard on devices where it would obscure the UI.
     *
     * @default true
     */
    launchKeyboard: boolean;
}
```

--------------------------------

### Implement echo shell function

Source: https://mmrl.dev/guide/text-formatting

Processes custom formatting tags based on the MMRL environment variable.

```shell
echo() {
    local msg="$*"
    if [ "$MMRL" = "true" ]; then
        command echo "$msg"
    else
        # Remove all custom formatting tags before printing
        command echo "$msg" | sed -E 's/\[(color|bg|bold|italic|underline)(=[^]]+)?]//g'
    fi
}
```

--------------------------------

### Configure Dialog Options

Source: https://mmrl.dev/guide/webuix/mx/application

Base configuration interface for dialogs, including title, message, and button labels.

```ts
/**
 * Base configuration shared by all dialog types.
 *
 * Pass this to {@link WebUI.confirm} to show a simple yes/no dialog.
 * For an input dialog, use the extended {@link PromptOptions} instead.
 */
interface DialogOptions {
    /**
     * The dialog's heading text.
     *
     * @default "Confirm"
     */
    title: string;

    /**
     * Optional body text displayed beneath the title.
     *
     * @throws If the message was null
     */
    message: string;

    /**
     * Custom labels for the confirm and cancel buttons.
     *
     * @see DialogButtons
     */
    buttons: DialogButtons;

    /**
     * Material Design theme variant applied to the dialog.
     *
     * @default "md3"
     */
    theme: string;
}
```

--------------------------------

### Define submission URL

Source: https://mmrl.dev/guide/mmrl-util/config-json

Sets the URL for submitting new modules or tracks.

```json
"submission": "url"
```

--------------------------------

### Define Source Repository

Source: https://mmrl.dev/guide/mmrl-util/track-json

Specifies the URL or path to the track's source code.

```yaml
source: "https://github.com/owner/track-source"
```

--------------------------------

### Check for WebUI Interface Availability

Source: https://mmrl.dev/guide/webuix/sanitized-ids

Verify the existence of a bound host interface before executing WebUI logic.

```javascript
if (typeof $bindhosts !== 'undefined' && Object.keys($bindhosts).length > 0) {
    console.log("Running WebUI X!")
}
```

--------------------------------

### Define categories

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Provide an array of categories for the module.

```yaml
categories: 
 - Utility
 - Tools
```

--------------------------------

### Define CSS styles for WebUI X

Source: https://mmrl.dev/guide/webuix/index-setup

Applies window insets to the body and defines card styling using theme-provided CSS variables.

```css
body {
    padding-top: var(--window-inset-top);
    padding-bottom: var(--window-inset-bottom);
    background-color: var(--background);
}

.scaffold {
    padding: 16px;
}

.card {
    padding: 16px;
    background-color: var(--surfaceContainer);
    border-radius: 20px;
    span {
        color: var(--inverseSurface);
    }
}
```

--------------------------------

### Define compatible devices

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Specify an array of device model IDs. Overrides specific manager-level device settings.

```yaml
devices:
  - SM-A705FN" # will only work on the Samsung Galaxy A70
```

--------------------------------

### Define Changelog

Source: https://mmrl.dev/guide/mmrl-util/track-json

Provides a description of updates or changes.

```yaml
changelog: "Bug fixes and performance improvements."
```

--------------------------------

### Specify Supported Devices

Source: https://mmrl.dev/guide/mmrl-util/track-json

Define a list of device model IDs to restrict track compatibility.

```yaml
devices:
  - "SM-A705FN"
  - "SM-G960F"
```

--------------------------------

### Handle Events with WXEvent API

Source: https://mmrl.dev/guide/webuix/events

Use the WXEventHandler to listen for navigation and lifecycle events like back, pause, resume, and refresh.

```javascript
import { WXEventHandler } from "webuix";

// Initialize the event system (recommended for best compatibility)
window.wx = new WXEventHandler()

// Handle back event for a specific element (e.g., appDetails)
wx.on(appDetails, "back", (event) => {
  if (appDetails.open) {
    event.stopImmediatePropagation();
    appDetails.open = false; // Close the details panel
  }
});

// Handle back event at the window level
wx.on(window, "back", (event) => {
  const appDetails = document.getElementById("appDetails");

  if (appDetails?.open) {
    appDetails.open = false;
    return;
  }

  if (confirm("Close the app?")) {
    webui.exit(); // Exit the WebUI app
  }
});

// Example: Listen for a custom pause event (replace with your own logic)
wx.on(window, "pause", (event) => {
  focusInput.focus();
  statusEl.textContent = 'App paused - input focused';
  statusEl.style.color = getCssVar('error');
});

// Listen for resume events
wx.on(window, "resume", (event) => {
    statusEl.textContent = 'App resumed';
    statusEl.style.color = getCssVar('success');
    // Add any additional logic needed when the app resumes
});

// If you have nested scroll elements you may need to handle it on the JavaScript side
wx.on(window, 'refresh', () => {
    webui.setRefreshing(true);

    if (confirm("Do you really wanna refresh the page?")) {
        location.reload()
    }

    webui.setRefreshing(false);
});
```

--------------------------------

### Define Application and Dialog Interfaces

Source: https://mmrl.dev/guide/webuix/mx/application

TypeScript interfaces for describing host application metadata and dialog button labels.

```ts
/**
 * Metadata describing the host Android application.
 */
interface Application {
    /** The application's unique package identifier (e.g. `"com.example.app"`). */
    packageName: string;

    /** The human-readable version name (e.g. `"1.4.2"`). */
    version: string;

    /** The internal integer version code used for update comparisons. */
    versionCode: number;
}

/**
 * Labels for the action buttons shown in a {@link DialogOptions} or {@link PromptOptions} dialog.
 */
interface DialogButtons {
    /**
     * Label for the primary/confirm button.
     *
     * @default "Confirm"
     */
    confirmText: string;

    /**
     * Label for the secondary/cancel button.
     *
     * @default "Cancel"
     */
    cancelText: string;
}
```

--------------------------------

### Define donation URL

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Provide a link to the project's donation page.

```yaml
donate: "https://example.com/donate"
```

--------------------------------

### Define maximum capacity

Source: https://mmrl.dev/guide/mmrl-util/config-json

Sets the maximum number of modules or users supported by the repository.

```json
"max_num": 3
```

--------------------------------

### Set API Constraints

Source: https://mmrl.dev/guide/mmrl-util/track-json

Defines the supported API level range.

```yaml
maxApi: 30
```

```yaml
minApi: 21
```

--------------------------------

### Display a confirmation dialog

Source: https://mmrl.dev/guide/webuix/mx/application

Shows a native confirmation dialog and returns a boolean based on user interaction.

```ts
const ok = await webui.confirm({
  title: "Delete item?",
  message: "This action cannot be undone.",
  buttons: { confirmText: "Delete", cancelText: "Keep" },
  theme: "md3",
});
if (ok) deleteItem();
```

--------------------------------

### fs.access(path, mode)

Source: https://mmrl.dev/guide/webuix/mx/filesystem

Tests whether the current process can access a file.

```APIDOC
## fs.access(path, mode)

### Description
Tests whether the current process can access a file.

### Parameters
- **path** (string) - Required - Path to the file.
- **mode** (number) - Required - Access mode to check.

### Returns
- **Promise<boolean>** - Returns true if access is allowed; otherwise false.
```

--------------------------------

### Define module description formatting

Source: https://mmrl.dev/guide/text-formatting

Applies custom formatting tags within the description field of a module's config.json file.

```json
{
  "name": {
    "en": "Systemless module",
    "de": "Systemloses Modul"
  },
  "description": {
    "en": "[bg=red]Hello[bg], [color=primary]World[color]!",
    "de": "Hallo, [color=green]Welt[color]!"
  }
}
```

--------------------------------

### Define Module and Path Interfaces

Source: https://mmrl.dev/guide/webuix/mx/module

TypeScript interfaces representing the module environment, including global ADB paths, specific module file paths, and the core module metadata structure.

```typescript
/**
 * Absolute and derived paths used by the ADB-based module environment.
 */
interface AdbPath {
    /**
     * Root directory for all module-related data.
     */
    baseDir: string

    /**
     * Directory containing global configuration files.
     */
    configDir: string

    /**
     * Directory used for local, device-specific data.
     */
    localDir: string

    /**
     * Directory containing installed modules.
     */
    modulesDir: string
}

/**
 * File system paths associated with a specific module.
 */
interface ModulePath {
    /**
     * Directory containing the module's configuration files.
     */
    configDir: string

    /**
     * Root directory of the module.
     */
    moduleDir: string

    /**
     * Directory exposed as the module's web root.
     */
    webrootDir: string

    /**
     * Web UI configuration file.
     */
    webrootConfig: string

    /**
     * Entry-point Lua script for the web UI.
     */
    webrootLuaIndex: string

    /**
     * Module property file (typically `module.prop`).
     */
    propFile: string

    /**
     * Module action script.
     */
    actionFile: string

    /**
     * Service script executed by the module.
     */
    serviceFile: string

    /**
     * Script executed during the post-fs-data stage of boot.
     */
    postFsDataFile: string

    /**
     * Script executed after partitions are mounted.
     */
    postMountFile: string

    /**
     * File containing system property definitions.
     */
    systemPropFile: string

    /**
     * Script executed when the system boot process completes.
     */
    bootCompletedFile: string

    /**
     * SELinux policy file provided by the module.
     */
    sepolicyFile: string

    /**
     * Marker or script used during module uninstallation.
     */
    uninstallFile: string

    /**
     * Module-provided system directory.
     */
    systemDir: string

    /**
     * Marker file indicating the module is disabled.
     */
    disableFile: string

    /**
     * Marker file indicating the module should be removed.
     */
    removeFile: string

    /**
     * Marker file indicating the module should be updated.
     */
    updateFile: string

    /**
     * All files belonging to the module.
     */
    files: Array<string>

    /**
     * Service-related files associated with the module.
     */
    serviceFiles: Array<string>
}

/**
 * Metadata and paths describing an installed module.
 */
interface Module {
    /**
     * Unique module identifier.
     */
    id: string

    /**
     * Human-readable module name.
     */
    name: string

    /**
     * Name of the module author or maintainer.
     */
    author: string

    /**
     * Module version string.
     */
    version: string

    /**
     * Numeric version code used for update comparisons.
     */
    versionCode: number

    /**
     * Human-readable description of the module.
     */
    description: string

    /**
     * URL or path to the module update manifest.
     * `null` if the module does not provide update information.
     */
    updateJson: string | null

    /**
     * Global ADB-related paths available to the module environment.
     */
    adbPath: AdbPath

    /**
     * File system paths associated with this module.
     */
    path: ModulePath
}

/**
 * Global reference to the currently loaded module.
 */
declare var mod: Module
```

--------------------------------

### Define architectures

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Specify an array of supported device architectures. Overrides specific manager-level architecture settings.

```yaml
arch:
  - "arm64-v8a"
```

--------------------------------

### Render styled text in Jetpack Compose

Source: https://mmrl.dev/guide/text-formatting

Uses the toStyleMarkup extension function to convert tagged strings into AnnotatedString for UI rendering.

```kotlin
// Simplified conceptual usage
@Composable
fun MyStyledText(text: String) {
    Text(text = text.toStyleMarkup())
}

// Example
MyStyledText(text = "Hello [color=blue]Blue World[color] with [bg=yellow]yellow background[bg] and [bold]bold[bold] text!")
```

--------------------------------

### Configure Update Source

Source: https://mmrl.dev/guide/mmrl-util/track-json

Various methods to define the update target for a track.

```yaml
id: zygisk_lsposed
update_to: https://lsposed.github.io/LSPosed/release/zygisk.json
license: GPL-3.0
```

```yaml
id: zygisk_lsposed
update_to: zygisk.json
license: GPL-3.0
```

```yaml
id: zygisk_lsposed
update_to: https://github.com/LSPosed/LSPosed/releases/download/v1.8.6/LSPosed-v1.8.6-6712-zygisk-release.zip
license: GPL-3.0
changelog: https://lsposed.github.io/LSPosed/release/changelog.md
```

```yaml
id: busybox-ndk
update_to: https://github.com/Magisk-Modules-Repo/busybox-ndk.git
```

```yaml
id: zygisk_lsposed
update_to: LSPosed-v1.8.6-6712-zygisk-release.zip
license: GPL-3.0
changelog: changelog.md
```

--------------------------------

### Implement Safe Area Insets

Source: https://mmrl.dev/guide/webuix/css-setup

Use window insets for fixed elements at screen edges, avoiding them for general content.

```css
/* Correct: For fixed elements at edges */
.top-bar {
  position: fixed;
  top: 0;
  padding-top: var(--window-inset-top);
}

/* Incorrect: For general content */
.main-content {
  padding-top: var(--window-inset-top); /* Avoid */
}
```

--------------------------------

### Test echo function behavior

Source: https://mmrl.dev/guide/text-formatting

Demonstrates how the echo function handles tags depending on the MMRL environment variable state.

```shell
# With MMRL not "true" (default behavior)
echo "This is a [color=red]red[color] message with [bold]bold text[bold]."
# Output: This is a red message with bold text.

# With MMRL="true"
MMRL="true" echo "This is a [color=red]red[color] message with [bold]bold text[bold]."
# Output: This is a [color=red]red[color] message with [bold]bold text[bold].
```

--------------------------------

### Define Track Note

Source: https://mmrl.dev/guide/mmrl-util/track-json

Adds a formatted note to the track.

```yaml
note:
  color: "red"
  title: "Important Update"
  message: "This track requires an update to version 2.0."
```

--------------------------------

### Create a Flag Checker Function

Source: https://mmrl.dev/guide/webuix/application-info-flags

Encapsulates flag checking logic into a reusable function that maps multiple bitwise flags to descriptive names.

```javascript
function checkAppFlags(packageName) {
    const info = JSON.parse(pm.getApplicationInfo(packageName));
    const flags = info.flags;
    
    const flagChecks = {
        'System App': (flags & (1<<0)) != 0,
        'Debuggable': (flags & (1<<1)) != 0,
        'Has Code': (flags & (1<<2)) != 0,
        'Persistent': (flags & (1<<3)) != 0,
        'Updated System App': (flags & (1<<7)) != 0,
        'Test Only': (flags & (1<<8)) != 0,
        'External Storage': (flags & (1<<18)) != 0,
        'Large Heap': (flags & (1<<20)) != 0,
        'Stopped': (flags & (1<<21)) != 0,
        'Suspended': (flags & (1<<30)) != 0
    };
    
    console.log(`Flags for ${packageName}:`);
    for (const [flagName, isSet] of Object.entries(flagChecks)) {
        console.log(`  ${flagName}: ${isSet}`);
    }
}

// Usage
checkAppFlags("com.android.settings");
```

--------------------------------

### Apply Safe Area Insets

Source: https://mmrl.dev/guide/webuix/css-setup

Use these variables to pad elements positioned at screen edges.

```css
/* Safe area usage */
.top-navigation {
  padding-top: var(--window-inset-top);
}
```

```css
.bottom-navigation {
  padding-bottom: var(--window-inset-bottom);
}
```

--------------------------------

### Handle Keyboard Height

Source: https://mmrl.dev/guide/webuix/css-setup

Use the keyboard height variable with a fallback to ensure layout stability when the keyboard is closed.

```css
/* Extra keys bar */
#extra-keys {
  background: #1a1a1a;
  border-top: 1px solid #333;
  padding: 8px;
  padding-bottom: calc(var(--window-keyboard-height, var(--window-inset-bottom, 0px)) + 8px) !important;
  display: flex;
  flex-wrap: wrap;
  gap: 4px;
  justify-content: space-around;
  min-height: 44px;
  box-sizing: border-box;
  flex-shrink: 0;
  transition:
    transform 0.3s ease,
    opacity 0.3s ease;
}
```

--------------------------------

### Apply Dark Mode via Body Script

Source: https://mmrl.dev/guide/webuix/patching

Modifies global body styles and inverts image colors to implement a basic dark mode.

```javascript
// Example body script: Force dark mode
window.addEventListener("DOMContentLoaded", () => {
  document.body.style.backgroundColor = "#1e1e2e";
  document.body.style.color = "#f8f8f2";

  // Invert all images (optional)
  document.querySelectorAll("img").forEach((img) => {
    img.style.filter = "invert(1) hue-rotate(180deg)";
  });

  console.log("[WebUI X] Body script loaded: Dark mode applied.");
});
```

--------------------------------

### Define donation URL

Source: https://mmrl.dev/guide/mmrl-util/config-json

Sets the URL for user donations.

```json
"donate": "url"
```

--------------------------------

### webui.canGoBackOrForward(steps)

Source: https://mmrl.dev/guide/webuix/mx/application

Checks if the WebView can navigate a specific number of steps in the history.

```APIDOC
## canGoBackOrForward(steps)

### Description
Resolves to true if the WebView can navigate the given number of steps through its history.

### Parameters
- **steps** (number) - Required - Number of history steps to check. Use negative values to check backward navigation (e.g., -2 checks two steps back).

### Returns
- **Promise<boolean>** - A Promise that resolves to a boolean.
```

--------------------------------

### Define Special Utility Colors

Source: https://mmrl.dev/guide/webuix/css-setup

List of CSS variables for semantic color management.

```css
--shadow                    /* Shadow color                     */
--inverseSurface            /* Inverse surface for contrast     */
--inverseOnSurface          /* Content on inverse surface       */
--inversePrimary            /* Inverse primary color            */
--surfaceBright             /* Bright surface variant           */
--surfaceDim                /* Dim surface variant              */
```

--------------------------------

### Check for WebUI availability

Source: https://mmrl.dev/guide/webuix/mx/application

Verifies the existence of the global webui object before accessing its properties.

```ts
if (typeof webui !== "undefined" && webui.isDarkMode) {
  document.documentElement.classList.add("dark");
}
```

--------------------------------

### webui.canGoBack()

Source: https://mmrl.dev/guide/webuix/mx/application

Checks if the WebView has a page in its back history.

```APIDOC
## canGoBack()

### Description
Resolves to true if the WebView has a page in its back history.

### Returns
- **Promise<boolean>** - A Promise that resolves to a boolean indicating if backward navigation is possible.
```

--------------------------------

### Register ModuleInterface in WebView

Source: https://mmrl.dev/guide/webuix/sanitized-ids

Expose module functionality to the WebView using the sanitized module ID as the interface name.

```kotlin
addJavascriptInterface(
    ModuleInterface(
        options = options,
        context = context,
        webView = this,
        insets = insets
    ), "${options.sanitizedModId}"
)
```

--------------------------------

### Define Categories

Source: https://mmrl.dev/guide/mmrl-util/track-json

Classifies the track into one or more categories.

```yaml
category: "Utility"
```

```yaml
categories:
  - "Tools"
  - "Performance"
```

--------------------------------

### Define anti-features in track.json

Source: https://mmrl.dev/guide/antifeatures

Add an array of anti-feature strings to the track.json file to mark a module.

```json
"antifeatures": ["Ads"]
```

--------------------------------

### Define category

Source: https://mmrl.dev/guide/mmrl-util/repo-json

Set the module category; note that this property is deprecated in MMRL V4 and above.

```yaml
category: "Utility
```
Tokens:
Raw