### Setup Qt6 Environment Variables for macOS Build

Source: https://github.com/ahrm/sioyek/blob/development/README.md

Sets up necessary environment variables for building Sioyek on macOS after installing Qt6. This includes paths for Qt binaries, plugins, and pkg-config.

```bash
pip install aqtinstall
cd /path/to/qt
aqt install-qt mac desktop 6.8.2 clang_64 -m all
export Qt6_DIR=/path/to/qt/6.8.2/macos/
export QT_PLUGIN_PATH=/path/to/qt/6.8.2/macos/plugins
export PKG_CONFIG_PATH=/path/to/qt/6.8.2/macos/lib/pkgconfig
export QML2_IMPORT_PATH=/path/to/qt/6.8.2/macos/qml
export PATH="/path/to/qt/6.8.2/macos/bin:$PATH"
```

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

### User Configuration Example (`prefs_user.config`)

Source: https://context7.com/ahrm/sioyek/llms.txt

Example of a user-specific configuration file showing customizations for dark mode, color schemes, database paths, fonts, zoom, and paper folders.

```ini
# ~/.config/sioyek/prefs_user.config

# Start in dark mode
startup_commands    toggle_dark_mode

# Custom sepia-like color scheme
custom_background_color   0.957 0.929 0.882
custom_text_color         0.180 0.141 0.082

# Point to synced shared database
shared_database_path    /home/user/Dropbox/sioyek/shared.db

# Font and size
ui_font   JetBrains Mono
font_size 16

# Zoom sensitivity
zoom_inc_factor   1.15

# Automatically watch a folder for new papers
paper_folder_path   /home/user/Papers

# Window layout (copy actual values with `copy_window_size_config` command)
main_window_size    1200 900
main_window_move    0 0
helper_window_size  900 900
helper_window_move  1200 0
```

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

### Install Deployment Script

Source: https://github.com/ahrm/sioyek/blob/development/CMakeLists.txt

Installs the generated deployment script. This makes the script available in the installation directory, allowing for post-installation application setup.

```cmake
install(SCRIPT ${deploy_script})
```

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

### Build Sioyek on macOS

Source: https://context7.com/ahrm/sioyek/llms.txt

Steps to build Sioyek on macOS, involving installing Qt via aqtinstall, setting environment variables for Qt, cloning the repository, and building using the provided script. Includes code signing.

```bash
# ── macOS (Qt6 via aqtinstall) ────────────────────────────────────────────
pip install aqtinstall
aqt install-qt mac desktop 6.8.2 clang_64 -m all
export Qt6_DIR=/path/to/qt/6.8.2/macos/
export PATH="/path/to/qt/6.8.2/macos/bin:$PATH"
git clone --recursive --branch development https://github.com/ahrm/sioyek
cd sioyek && MAKE_PARALLEL=8 ./build_mac.sh
mv build/sioyek.app /Applications/
sudo codesign --force --sign - --deep /Applications/sioyek.app
```

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

### Build Sioyek on Fedora

Source: https://github.com/ahrm/sioyek/blob/development/README.md

Installs dependencies, clones the repository, and compiles Sioyek on Fedora Linux. Ensure you have `qt5-qtbase-devel`, `qt5-qtbase-static`, `qt5-qt3d-devel`, and `harfbuzz-devel` installed.

```bash
sudo dnf install qt5-qtbase-devel qt5-qtbase-static qt5-qt3d-devel harfbuzz-devel
git clone --recursive --branch development https://github.com/ahrm/sioyek
cd sioyek
./build_linux.sh
```

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

### Build Sioyek on Generic Linux

Source: https://github.com/ahrm/sioyek/blob/development/README.md

Installs `libharfbuzz-dev`, clones the repository, and compiles Sioyek. Requires Qt 5 with `qmake` in the PATH. This is for generic Linux distributions.

```bash
sudo apt install libharfbuzz-dev
git clone --recursive --branch development https://github.com/ahrm/sioyek
cd sioyek
./build_linux.sh
```

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

### Print Sioyek Version

Source: https://context7.com/ahrm/sioyek/llms.txt

Prints the installed version of Sioyek to the console.

```bash
sioyek --version
# Output: sioyek 2.0.0
```

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

### Install Sioyek Target

Source: https://github.com/ahrm/sioyek/blob/development/CMakeLists.txt

Installs the 'sioyek' target to the bundle destination and runtime directory. This defines where the built executable and its related files will be placed after installation.

```cmake
install(TARGETS sioyek
    BUNDLE DESTINATION .
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)
```

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

### Build Sioyek on Linux with CMake

Source: https://context7.com/ahrm/sioyek/llms.txt

Instructions for building Sioyek on Linux using CMake, including installing dependencies, cloning the repository, configuring, building, and installing the project.

```bash
# ── Linux (CMake) ──────────────────────────────────────────────────────────
sudo apt install qt6-base-dev libharfbuzz-dev libsqlite3-dev
git clone --recursive --branch development https://github.com/ahrm/sioyek
cd sioyek
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
sudo cmake --install build
```

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

### Install Sioyek with Homebrew Cask

Source: https://github.com/ahrm/sioyek/blob/development/README.md

Use this command to install Sioyek on macOS using Homebrew Cask. Ensure Homebrew is installed.

```bash
brew install --cask sioyek
```

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

### ConfigManager: Get All Configurations

Source: https://context7.com/ahrm/sioyek/llms.txt

Retrieves all configuration settings, useful for UI elements like a configuration editor.

```cpp
// Get all configs (for the config editor UI)
std::vector<Config> all = config_manager.get_configs();
for (auto& c : all)
    std::wcout << c.name << L" = " << c.get_current_string() << L"\n";
```

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

### Use Shared Database

Source: https://context7.com/ahrm/sioyek/llms.txt

Specifies a shared SQLite database path for Sioyek, useful for synchronizing data across different installations or devices.

```bash
sioyek --shared-database-path /dropbox/sioyek/shared.db /path/to/paper.pdf
```

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

### Build Sioyek on Windows

Source: https://context7.com/ahrm/sioyek/llms.txt

Instructions for building Sioyek on Windows using a batch script, requiring Qt (5/6) and Visual Studio to be in the system's PATH.

```bat
# ── Windows (MSVC 64-bit Developer Prompt) ────────────────────────────────
git clone --recursive --branch development https://github.com/ahrm/sioyek
cd sioyek
build_windows.bat         # requires Qt5/6 qmake in PATH and Visual Studio
```

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

### Build Sioyek on Windows

Source: https://github.com/ahrm/sioyek/blob/development/README.md

Builds Sioyek on Windows using a 64-bit Visual Studio Developer Command Prompt. Requires Visual Studio and Qt 5 with `qmake` in the PATH.

```batch
git clone --recursive --branch development https://github.com/ahrm/sioyek
cd sioyek
build_windows.bat
```

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

### Initialize MainWidget

Source: https://context7.com/ahrm/sioyek/llms.txt

Constructs the main application window. Requires various manager and context objects.

```cpp
MainWidget* main_widget = new MainWidget(
    mupdf_context,
    &db_manager,
    &document_manager,
    &config_manager,
    command_manager,
    &input_handler,
    &checksummer,
    &quit_flag
);
```

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

### Build Sioyek on Linux with QMake

Source: https://context7.com/ahrm/sioyek/llms.txt

Command to build Sioyek on Linux using the legacy QMake script, which builds the executable into the ./build/sioyek directory.

```bash
# ── Linux (legacy QMake script) ───────────────────────────────────────────
./build_linux.sh          # builds into ./build/sioyek
```

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

### Build and Sign Sioyek on macOS

Source: https://github.com/ahrm/sioyek/blob/development/README.md

Clones the repository, builds Sioyek using `build_mac.sh`, moves the application to `/Applications`, and codesigns it. Ensure Qt6 environment variables are set.

```bash
git clone --recursive --branch development https://github.com/ahrm/sioyek
cd sioyek
chmod +x build_mac.sh
setopt PIPE_FAIL PRINT_EXIT_VALUE ERR_RETURN SOURCE_TRACE XTRACE
MAKE_PARALLEL=8 ./build_mac.sh

mv build/sioyek.app /Applications/
sudo codesign --force --sign - --deep /Applications/sioyek.app
```

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

### QtTextToSpeechHandler Usage

Source: https://context7.com/ahrm/sioyek/llms.txt

Demonstrates how to use the QtTextToSpeechHandler for text-to-speech functionality, including setting playback rate, handling word and state callbacks, and controlling playback.

```cpp
// QtTextToSpeechHandler wraps Qt's QTextToSpeech engine
QtTextToSpeechHandler tts_handler;

// Set playback rate (0.0 = slowest, 1.0 = normal, 2.0 = double speed)
tts_handler.set_rate(1.0f);

// Speak a string
tts_handler.say(QString::fromStdString("Hello from Sioyek"));

// Word-boundary callback: called with (start_index, length) for each word
tts_handler.set_word_callback([](int start, int length) {
    std::cout << "Word at [" << start << ", " << start+length << "]\n";
});

// State-change callback: "reading", "stopped", "paused"
tts_handler.set_state_change_callback([](QString state) {
    std::cout << "TTS state: " << state.toStdString() << "\n";
});

// Pause / resume
tts_handler.pause();
tts_handler.say(QString("Resuming..."));

// Stop completely
tts_handler.stop();

// Check capabilities
bool can_pause   = tts_handler.is_pausable();       // true on most desktop engines
bool word_by_word = tts_handler.is_word_by_word();  // true if word callbacks fire
```

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

### Use Named Instance

Source: https://context7.com/ahrm/sioyek/llms.txt

Launches Sioyek with a specific instance name, allowing multiple independent Sioyek servers to run concurrently.

```bash
sioyek --instance-name my-instance /path/to/paper.pdf
```

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

### Manage Portals

Source: https://context7.com/ahrm/sioyek/llms.txt

Initiate portal creation, jump to destinations, edit destinations via history, or remove portals.

```python
s.portal()                         # begin creating portal (first call sets src)
s.goto_portal()                    # jump to nearest portal destination
s.edit_portal()                    # update portal destination via history
s.delete_portal()                  # remove nearest portal
```

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

### ConfigManager: Instantiate and Read Configuration

Source: https://context7.com/ahrm/sioyek/llms.txt

Instantiates the ConfigManager with multiple configuration file paths and demonstrates reading typed configuration values.

```cpp
// Instantiate (done once in main())
ConfigManager config_manager(
    default_config_path,    // prefs.config shipped with the app
    auto_config_path,       // auto.config written by sioyek itself
    user_config_paths       // prefs_user.config(s) edited by the user
);

// Read a typed config value
const float* zoom_factor = config_manager.get_config<float>(L"zoom_inc_factor");
if (zoom_factor) std::cout << "Zoom factor: " << *zoom_factor << "\n";
// Output: Zoom factor: 1.2

const bool* flat_toc = config_manager.get_config<bool>(L"flat_toc");
const float* bg = config_manager.get_config<float>(L"background_color"); // float[3]
```

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

### Command-Line Interface

Source: https://context7.com/ahrm/sioyek/llms.txt

Sioyek can be controlled and launched using various command-line flags. These flags allow for opening files, controlling the initial view, enabling SyncTeX, and executing commands in a running instance.

```APIDOC
## Command-Line Interface

Sioyek is launched from the terminal with a path to a PDF file. A rich set of flags controls the initial view, enables SyncTeX integration, and routes commands to a running instance via a local socket.

```bash
# Open a file (reuses an existing instance if one is running)
sioyek /path/to/paper.pdf

# Print version string
sioyek --version
# Output: sioyek 2.0.0

# Open on a specific page (1-based)
sioyek --page 42 /path/to/paper.pdf

# Open at exact coordinates and zoom
sioyek --page 5 --xloc 0.2 --yloc 0.35 --zoom 2.0 /path/to/paper.pdf

# Force a new window even if an instance is running
sioyek --new-window /path/to/paper.pdf

# Force reuse of existing window
sioyek --reuse-window /path/to/paper.pdf

# SyncTeX forward search: jump from .tex source to PDF location
sioyek --forward-search-file /path/to/main.tex \
       --forward-search-line 142 \
       /path/to/output.pdf

# Execute an internal command in a running instance (no focus change)
sioyek --execute-command toggle_dark_mode --nofocus

# Execute a command with data (e.g. jump to page)
sioyek --execute-command goto_page_with_page_number \
       --execute-command-data "87"

# Point all data to a shared database (useful for Dropbox sync)
sioyek --shared-database-path /dropbox/sioyek/shared.db /path/to/paper.pdf

# Use a named instance (allows multiple independent sioyek servers)
sioyek --instance-name my-instance /path/to/paper.pdf

# Open a file:// URI with an optional page fragment
sioyek "file:///home/user/paper.pdf#page=10"
```
```

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

### Set and Go to Marks

Source: https://context7.com/ahrm/sioyek/llms.txt

Set local or global marks at the current location and navigate back to them.

```python
s.set_mark("m")                    # mark current location as 'm' (local)
s.set_mark("M")                    # 'M' is a global mark (cross-document)
s.goto_mark("m")                   # jump back to mark 'm'
```

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

### Toggle Window Configuration

Source: https://context7.com/ahrm/sioyek/llms.txt

Switches to or from the two-window portal mode, showing a helper window for portal destinations.

```cpp
main_widget->toggle_window_configuration();
```

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

### Open PDF File with Sioyek

Source: https://context7.com/ahrm/sioyek/llms.txt

Opens a PDF file. If Sioyek is already running, it reuses the existing instance by default.

```bash
sioyek /path/to/paper.pdf
```

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

### Initialize Sioyek Python Wrapper

Source: https://context7.com/ahrm/sioyek/llms.txt

Initializes the Sioyek Python class, connecting to a running instance and optionally specifying database paths for read access.

```python
from sioyek import Sioyek

s = Sioyek(
    sioyek_path="/usr/bin/sioyek",
    local_database_path="/home/user/.local/share/sioyek/local.db",
    shared_database_path="/home/user/.local/share/sioyek/shared.db",
)
```

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

### Generate Qt Deploy App Script

Source: https://github.com/ahrm/sioyek/blob/development/CMakeLists.txt

Generates a deployment script for the 'sioyek' target using Qt's deploy functionality. It suppresses errors for unsupported platforms, ensuring script generation even in varied environments.

```cmake
qt_generate_deploy_app_script(
    TARGET sioyek
    OUTPUT_SCRIPT deploy_script
    NO_UNSUPPORTED_PLATFORM_ERROR
)
```

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

### DatabaseManager: Insert and Query Bookmarks

Source: https://context7.com/ahrm/sioyek/llms.txt

Inserts new bookmarks with descriptions and offsets, and queries all bookmarks associated with a document checksum.

```cpp
std::string checksum = "sha256hexstring...";

// Insert a bookmark
db.insert_bookmark(checksum, L"Important derivation", /*offset_y=*/523.4f,
                   uuid_wstring);

// Query all bookmarks for a document
std::vector<BookMark> bookmarks;
db.select_bookmark(checksum, bookmarks);
for (auto& bm : bookmarks)
    std::wcout << bm.description << L" @ y=" << bm.get_y_offset() << L"\n";
```

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

### Navigate Bookmarks and Highlights

Source: https://context7.com/ahrm/sioyek/llms.txt

Open bookmark or highlight lists for the current document or across all documents.

```python
s.goto_bookmark()                            # open bookmark list for current doc
s.goto_bookmark_g()                          # open bookmark list across ALL docs
s.goto_highlight()                           # open highlights for current doc
s.goto_highlight_g()                         # open highlights across all docs
```

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

### Build Sioyek for Android with CMake

Source: https://context7.com/ahrm/sioyek/llms.txt

Command to configure the CMake build for Android cross-compilation, specifying the toolchain file, ABI, and Android platform version.

```bash
# ── Android (CMake cross-compile) ─────────────────────────────────────────
# Define SIOYEK_ANDROID in CMakeLists, handled automatically when targeting Android
cmake -B build-android \
  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-24
cmake --build build-android -j8
```

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

### MainWidget Operations

Source: https://context7.com/ahrm/sioyek/llms.txt

Provides methods for controlling the main application window, opening documents, executing commands, and managing window configurations.

```APIDOC
## MainWidget Operations

### `open_document(const std::wstring& path)`

Opens a PDF document at the specified file path.

### `open_document_at_location(const Path& path, int page, std::optional<float> x_loc, float y_loc, float zoom_level)`

Opens a PDF document and navigates to a specific page and coordinate, with an optional zoom level.

### `do_synctex_forward_search(const Path& pdf_path, const Path& tex_path, int line, int column)`

Performs a SyncTeX forward search from a LaTeX source file to the PDF document.

### `execute_command(const std::wstring& command_name, std::optional<std::wstring> argument = std::nullopt)`

Executes an internal command with an optional argument. This is equivalent to using the `--execute-command` command-line option.

### `execute_macro_if_enabled(const std::wstring& macro_string)`

Executes a semicolon-separated macro string if macros are enabled.

### `toggle_window_configuration()`

Toggles the two-window portal mode, showing a helper window for portal destinations.

### `set_inverse_search_command(const std::wstring& command_string)`

Programmatically sets the command string for SyncTeX inverse search, used to link from the PDF back to the editor.

### `move_document(float dx, float dy)`

Scrolls the document view by the specified delta in the x and y directions.

### `zoom(WindowPos position, float zoom_factor, bool zoom_in)`

Zooms the document view in or out from a specified window position.
```

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

### Run Arbitrary Commands

Source: https://context7.com/ahrm/sioyek/llms.txt

Execute specific Sioyek commands or chain multiple commands with semicolons.

```python
s.run_command("set_page_offset", "5", focus=False)
s.execute("move_down;move_down;move_down")  # chain commands with semicolons
```

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

### Execute Internal Command with Data

Source: https://context7.com/ahrm/sioyek/llms.txt

Executes an internal Sioyek command and provides associated data, such as a page number for navigation.

```bash
sioyek --execute-command goto_page_with_page_number \
       --execute-command-data "87"
```

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

### Force Reuse of Existing Sioyek Window

Source: https://context7.com/ahrm/sioyek/llms.txt

Forces Sioyek to reuse an existing instance to open the specified PDF, overriding any potential new window preference.

```bash
sioyek --reuse-window /path/to/paper.pdf
```

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

### Coordinate System Conversions

Source: https://context7.com/ahrm/sioyek/llms.txt

Demonstrates the conversion between different coordinate systems used within Sioyek, including document-relative, absolute document, window, and normalized window coordinates.

```APIDOC
## Coordinate System Conversions

Sioyek uses four interchangeable coordinate spaces: `DocumentPos`, `AbsoluteDocumentPos`, `WindowPos`, and `NormalizedWindowPos`. Each position type provides `to_*()` methods for conversion.

### `DocumentPos`
Represents coordinates relative to a specific page (page index + x,y within the page).

### `AbsoluteDocumentPos`
Represents coordinates with a single y-axis spanning all concatenated pages.

### `WindowPos`
Represents pixel coordinates within the `QWidget`.

### `NormalizedWindowPos`
Represents coordinates in a [-1, 1] range, where the center of the screen is (0,0).

### Conversion Methods

- `DocumentPos.to_absolute(Document* doc)`: Converts `DocumentPos` to `AbsoluteDocumentPos`.
- `AbsoluteDocumentPos.to_window(QWidget* view)`: Converts `AbsoluteDocumentPos` to `WindowPos`.
- `AbsoluteDocumentPos.to_window_normalized(QWidget* view)`: Converts `AbsoluteDocumentPos` to `NormalizedWindowPos`.
- `WindowPos.to_document(QWidget* view)`: Converts `WindowPos` back to `DocumentPos`.

Rectangle types follow a similar pattern, with methods like `to_document(Document* doc)` available for `AbsoluteRect`.
```

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

### Open File URI with Fragment

Source: https://context7.com/ahrm/sioyek/llms.txt

Opens a PDF file specified by a file URI, optionally including a fragment to navigate to a specific page.

```bash
sioyek "file:///home/user/paper.pdf#page=10"
```

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

### Create Highlight Annotation

Source: https://context7.com/ahrm/sioyek/llms.txt

Represents a text selection with a configurable color type and an optional description.

```cpp
Highlight hl;
hl.selection_begin = AbsoluteDocumentPos{0.1f, 300.0f};
hl.selection_end   = AbsoluteDocumentPos{0.9f, 315.0f};
hl.description     = L"Selected text content";
hl.type            = 'b';  // 'a'-'z', each maps to a configurable color
```

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

### Force New Sioyek Window

Source: https://context7.com/ahrm/sioyek/llms.txt

Forces Sioyek to open the specified PDF in a new window, even if an instance is already running.

```bash
sioyek --new-window /path/to/paper.pdf
```

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

### Sioyek Python API: Navigation Commands

Source: https://context7.com/ahrm/sioyek/llms.txt

Provides Python methods for navigating through a PDF document, including going to the beginning/end, specific pages, and using history.

```python
# --- Navigation ---
s.goto_begining()                  # jump to first page
s.goto_end()                       # jump to last page
s.goto_page_with_page_number("42") # jump to page 42
s.next_page()                      # advance one full page
s.previous_page()
s.screen_down()                    # scroll down by one screen
s.screen_up()
s.next_chapter()                   # jump to next TOC chapter
s.prev_chapter()
s.prev_state()                     # navigate back in history (like browser back)
s.next_state()
```

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

### Execute Internal Command

Source: https://context7.com/ahrm/sioyek/llms.txt

Executes an internal Sioyek command by its string name. Some commands accept string arguments.

```cpp
main_widget->execute_command(L"toggle_dark_mode");
main_widget->execute_command(L"goto_page_with_page_number", L"87");
```

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

### Open Document Programmatically

Source: https://context7.com/ahrm/sioyek/llms.txt

Opens a PDF document using its file path.

```cpp
main_widget->open_document(L"/path/to/paper.pdf");
```

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

### Create Portal Link

Source: https://context7.com/ahrm/sioyek/llms.txt

Defines a bidirectional link between documents or locations, specifying source and destination states.

```cpp
Portal portal = Portal::with_src_offset(/*src_offset_y=*/350.0f);
portal.dst.document_checksum = "deadbeef...";
portal.dst.book_state.offset_y  = 800.0f;
portal.dst.book_state.zoom_level = 1.5f;
bool visible = portal.is_visible();  // true if dst.book_state has valid state
```

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

### Execute Internal Command (No Focus)

Source: https://context7.com/ahrm/sioyek/llms.txt

Executes an internal Sioyek command in a running instance without changing the window's focus.

```bash
sioyek --execute-command toggle_dark_mode --nofocus
```

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

### Direct Database Access

Source: https://context7.com/ahrm/sioyek/llms.txt

Access the shared Sioyek database using sqlite3 and query for bookmark information.

```python
db = s.get_shared_database()       # returns sqlite3.Connection
rows = db.execute(
    "SELECT desc, offset_y FROM bookmarks WHERE document_hash = ?",
    ("abc123def456",)
).fetchall()
for desc, y in rows:
    print(f"  Bookmark '{desc}' at y={y:.3f}")
```

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

### Create BookMark Annotation

Source: https://context7.com/ahrm/sioyek/llms.txt

Represents a labeled location in a document, with an offset and automatically updated timestamp.

```cpp
BookMark bm;
bm.description = L"Key lemma";
bm.y_offset_   = 523.0f;
bm.update_creation_time();  // sets ISO-8601 timestamp
QJsonObject bm_json = bm.to_json("sha256checksum");
```

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

### Document Operations

Source: https://context7.com/ahrm/sioyek/llms.txt

Open documents, toggle display modes (dark, presentation, fullscreen), and embed annotations.

```python
s.open_document("/path/to/other.pdf", focus=True)
s.open_prev_doc()                  # reopen most recently closed document
s.toggle_dark_mode()
s.toggle_presentation_mode()
s.toggle_fullscreen()
s.embed_annotations()              # write sioyek annotations into PDF file itself
```

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

### DatabaseManager: Global Bookmark Search

Source: https://context7.com/ahrm/sioyek/llms.txt

Performs a global search across all documents to retrieve bookmarks.

```cpp
// Search globally across ALL documents
std::vector<std::pair<std::string, BookMark>> all_bms;
db.global_select_bookmark(all_bms);
```

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

### DatabaseManager: Open and Manage SQLite Databases

Source: https://context7.com/ahrm/sioyek/llms.txt

Initializes and opens local and shared SQLite databases for annotation storage. Ensures database schema compatibility.

```cpp
DatabaseManager db;
// Open with separate local.db (per-machine state like scroll position)
// and shared.db (synced state like bookmarks, highlights)
db.open(L"/home/user/.local/share/sioyek/local.db",
        L"/home/user/.local/share/sioyek/shared.db");
db.ensure_database_compatibility(local_path, global_path);
db.ensure_schema_compatibility();
```

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

### Document Class - Core Document State

Source: https://context7.com/ahrm/sioyek/llms.txt

Manage document content, page information, text extraction, search, bookmarks, highlights, marks, and portals. Ensure the fz_context is initialized before use.

```cpp
// Obtain a document (created once, then cached)
// fz_context* mupdf_context already initialized in main()
Document* doc = document_manager.get_document(L"/path/to/paper.pdf");

// Open the document (loads page dimensions, starts background indexing)
bool invalid = false;
doc->open(&invalid, /*force_load_dimensions=*/false, /*password=*/"");

// --- Page info ---
int n = doc->num_pages();                    // total page count
float h = doc->get_page_height(3);           // height of page index 3 (0-based)
float w = doc->get_page_width(3);
float accum = doc->get_accum_page_height(3); // sum of heights of pages 0..2
std::wstring label = doc->get_page_label(3); // e.g. L"iv" or L"42"
```

```cpp
// --- Text extraction via MuPDF structured text ---
fz_stext_page* stext = doc->get_stext_with_page_number(0); // page 0
std::vector<fz_stext_char*> flat_chars;
get_flat_chars_from_stext_page(stext, flat_chars, /*dehyphenate=*/true);
// flat_chars now contains every character on the page in reading order
```

```cpp
// --- Full-text search ---
std::vector<SearchResult> hits = doc->search_text(
    L"attention mechanism",
    SearchCaseSensitivity::CaseInsensitive,
    /*begin_page=*/0, /*min_page=*/0, /*max_page=*/n - 1
);
for (const auto& hit : hits) {
    std::wcout << L"  page " << hit.page
               << L", " << hit.rects.size() << L" rect(s)\n";
}

// Regex search
std::vector<SearchResult> regex_hits = doc->search_regex(
    L"Fig\\.\\s*\\d+",
    SearchCaseSensitivity::SmartCase,
    0, 0, n - 1
);
```

```cpp
// --- Bookmarks ---
std::string uuid = doc->add_bookmark(L"Key theorem", /*y_offset=*/423.5f);
std::vector<BookMark>& bms = doc->get_bookmarks();
doc->delete_bookmark_with_index(0);
```

```cpp
// --- Highlights ---
// selection_begin/end are AbsoluteDocumentPos (concatenated y across pages)
AbsoluteDocumentPos sel_begin{0.12f, 120.0f};
AbsoluteDocumentPos sel_end{0.88f, 135.0f};
std::string hl_uuid = doc->add_highlight(
    L"Important claim",
    sel_begin,
    sel_end,
    'a'   // highlight type: 'a'-'z' map to configurable colors
);
const std::vector<Highlight>& hls = doc->get_highlights();
```

```cpp
// --- Marks (single-char labels) ---
doc->add_mark('a', /*y_offset=*/200.0f, /*x_offset=*/{}, /*zoom=*/{});
std::optional<Mark> m = doc->get_mark_if_exists('a');
if (m) std::wcout << L"Mark 'a' at y=" << m->y_offset << L"\n";
```

```cpp
// --- Portals ---
Portal portal;
portal.src_offset_y = 350.0f;
portal.dst.document_checksum = "deadbeef01234567";
portal.dst.book_state.offset_y = 800.0f;
portal.dst.book_state.zoom_level = 1.5f;
int portal_idx = doc->add_portal(portal);

std::optional<Portal> closest = doc->find_closest_portal(/*to_offset_y=*/360.0f);
```

```cpp
// --- Smart jump: find figure / reference by heuristic text matching ---
std::vector<IndexedData> refs =
    doc->find_reference_with_string(L"Transformer2017", /*page_number=*/5);
// refs[i].page is the likely page of that reference's target
```

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

### Open PDF at Specific Coordinates and Zoom

Source: https://context7.com/ahrm/sioyek/llms.txt

Opens a PDF file at a precise location defined by x/y coordinates and a zoom level.

```bash
sioyek --page 5 --xloc 0.2 --yloc 0.35 --zoom 2.0 /path/to/paper.pdf
```

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

### Convert Window Position Back to Document Space

Source: https://context7.com/ahrm/sioyek/llms.txt

Converts pixel coordinates from the QWidget view back into a page-relative DocumentPos.

```cpp
DocumentPos back = win_pos.to_document(document_view);
```

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

### Open PDF on Specific Page

Source: https://context7.com/ahrm/sioyek/llms.txt

Opens a PDF file and navigates to a specified page number (1-based index).

```bash
sioyek --page 42 /path/to/paper.pdf
```

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

### Perform SyncTeX Forward Search

Source: https://context7.com/ahrm/sioyek/llms.txt

Initiates a forward search using SyncTeX, linking from a LaTeX source file to a PDF location.

```cpp
main_widget->do_synctex_forward_search(
    Path(L"/path/to/output.pdf"),
    Path(L"/path/to/main.tex"),
    /*line=*/142,
    /*column=*/0
);
```

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

### Access Current Document

Source: https://context7.com/ahrm/sioyek/llms.txt

Retrieves a pointer to the currently opened Document object. Returns nullptr if no document is open.

```cpp
Document* doc = main_widget->doc(); // nullptr if no file is open
```

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

### Execute Macro

Source: https://context7.com/ahrm/sioyek/llms.txt

Executes a semicolon-separated sequence of internal commands as a macro, if macros are enabled.

```cpp
main_widget->execute_macro_if_enabled(L"toggle_visual_scroll;toggle_dark_mode");
```

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

### Open Document at Specific Location

Source: https://context7.com/ahrm/sioyek/llms.txt

Opens a PDF document and navigates to a specific page, coordinate, and zoom level.

```cpp
main_widget->open_document_at_location(
    Path(L"/path/to/paper.pdf"),
    /*page=*/41,          // 0-based
    /*x_loc=*/{},         // std::optional<float>
    /*y_loc=*/0.25f,
    /*zoom_level=*/1.5f
);
```

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

### DatabaseManager: Export and Import Annotations via JSON

Source: https://context7.com/ahrm/sioyek/llms.txt

Exports all annotations to a JSON file for backup or migration and imports them back into the database.

```cpp
// JSON export/import for backup or cross-machine migration
db.export_json(L"/backup/annotations.json", &checksummer);
db.import_json(L"/backup/annotations.json", &checksummer);
```

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

### Add and Delete Bookmarks

Source: https://context7.com/ahrm/sioyek/llms.txt

Use these functions to manage bookmarks at the current location or delete the nearest bookmark.

```python
s.add_bookmark("important section")          # add bookmark at current location
s.delete_bookmark()                          # delete nearest bookmark
```

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

### InputHandler: Key Bindings for Navigation and Actions

Source: https://context7.com/ahrm/sioyek/llms.txt

Defines key bindings for various commands, including single keys, modifier combos, multi-key sequences, and chained commands.

```config
# keys_user.config  — full vim-style key sequence syntax

# Single key
goto_beginning     gg
goto_end           G

# Modifier combos
search             <C-f>
copy               <C-c>
new_window         <C-t>
close_window       <C-w>

# Multi-key sequences (like vim)
goto_bookmark      gb
goto_highlight     gh
delete_bookmark    db
delete_highlight   dh
goto_portal        gp
goto_toc           t

# Chain multiple commands on one binding
goto_top_of_page;goto_right_smart    zz

# Numbered prefix (like vim: 150gg → go to page 150)
goto_beginning     gg    # prefix e.g. 150gg → page 150

# Bind a custom shell command to a key
execute_shell     <C-e>    # prompts for a shell command and runs it

# External web search (s = Google Scholar, g = Google)
external_search    s

# SyncTeX inverse search toggle (right-click → jump to .tex source)
toggle_synctex     <f4>
```

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

### Sioyek Python API: Search Commands

Source: https://context7.com/ahrm/sioyek/llms.txt

Provides Python methods for performing text searches within a PDF document and navigating through search results.

```python
# --- Search ---
s.search("neural network")         # start full-text search
s.chapter_search("attention")      # search only the current chapter
s.next_item()                      # go to next search result
s.previous_item()
```

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

### Sioyek Python API: Zoom Commands

Source: https://context7.com/ahrm/sioyek/llms.txt

Provides Python methods for controlling the zoom level of the PDF view, including fitting the page to different dimensions.

```python
# --- Zoom ---
s.zoom_in()
s.zoom_out()
s.fit_to_page_width()              # fit horizontally
s.fit_to_page_width_smart()        # fit horizontally, ignoring white margins
s.fit_to_page_height()
```

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

### ConfigManager: Set and Persist Configuration

Source: https://context7.com/ahrm/sioyek/llms.txt

Programmatically sets a configuration value and persists the changes to the user configuration file.

```cpp
// Programmatically set a config value (persisted to prefs_user.config)
config_manager.deserialize_config("background_color", L"0.1 0.1 0.1");
config_manager.persist_config();
```

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

### Python Scripting API - Sioyek Class

Source: https://context7.com/ahrm/sioyek/llms.txt

The `Sioyek` class in `scripts/sioyek.py` provides a Python interface to control Sioyek. It allows programmatic navigation, zooming, and searching within documents by interacting with a running Sioyek instance.

```APIDOC
## Python Scripting API — `Sioyek` class

`scripts/sioyek.py` provides a Python wrapper around the `--execute-command` socket interface. Instantiate `Sioyek` with the path to the binary and optionally the SQLite database paths for read access.

```python
from sioyek import Sioyek

# Connect to a running sioyek instance
s = Sioyek(
    sioyek_path="/usr/bin/sioyek",
    local_database_path="/home/user/.local/share/sioyek/local.db",
    shared_database_path="/home/user/.local/share/sioyek/shared.db",
)

# Enable dry-run mode (prints commands instead of executing)
s.set_dummy_mode(True)

# --- Navigation ---
s.goto_begining()                  # jump to first page
s.goto_end()                       # jump to last page
s.goto_page_with_page_number("42") # jump to page 42
s.next_page()                      # advance one full page
s.previous_page()
s.screen_down()                    # scroll down by one screen
s.screen_up()
s.next_chapter()                   # jump to next TOC chapter
s.prev_chapter()
s.prev_state()                     # navigate back in history (like browser back)
s.next_state()

# --- Zoom ---
s.zoom_in()
s.zoom_out()
s.fit_to_page_width()              # fit horizontally
s.fit_to_page_width_smart()        # fit horizontally, ignoring white margins
s.fit_to_page_height()

# --- Search ---
s.search("neural network")         # start full-text search
s.chapter_search("attention")      # search only the current chapter
s.next_item()                      # go to next search result
s.previous_item()
```
```

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

### DatabaseManager: Insert Portal

Source: https://context7.com/ahrm/sioyek/llms.txt

Inserts a portal, which is a cross-document link with source and destination coordinates and zoom level.

```cpp
// Insert a portal (cross-document link)
db.insert_portal(
    /*src_checksum=*/"abc...", /*dst_checksum=*/"def...",
    /*dst_offset_y=*/800.0f, /*dst_offset_x=*/0.0f,
    /*dst_zoom_level=*/1.5f,
    /*src_offset_y=*/350.0f, uuid_wstring
);
```

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

### Link Libraries for Sioyek Target

Source: https://github.com/ahrm/sioyek/blob/development/CMakeLists.txt

Links necessary libraries for the 'sioyek' target, including AppKit framework, mupdf libraries, and zlib. This is typically used on macOS.

```cmake
target_link_libraries(sioyek PRIVATE
    "-framework AppKit"
    -ldl
    -L${CMAKE_CURRENT_SOURCE_DIR}/mupdf/build/release
    -lmupdf
    -lmupdf-third
    -lmupdf-threads
    -lz
)
```

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

### DatabaseManager: Insert Highlight

Source: https://context7.com/ahrm/sioyek/llms.txt

Inserts a highlight annotation for a document, specifying its bounding box and type.

```cpp
// Insert a highlight (selection rectangle in absolute document coords)
db.insert_highlight(checksum, L"Key finding",
                    /*begin_x=*/0.1f, /*begin_y=*/300.0f,
                    /*end_x=*/0.9f,   /*end_y=*/315.0f,
                    /*type=*/'b', uuid_wstring);
```

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

### Document Class Methods

Source: https://context7.com/ahrm/sioyek/llms.txt

Methods for managing and interacting with a single document, including opening, page access, text extraction, search, bookmarks, highlights, marks, and portals.

```APIDOC
## Document Class

### Description
Manages the state of a PDF document, including its content, annotations, and search capabilities.

### Methods

#### `open`
- **Description**: Opens the document, loading page dimensions and initiating background indexing.
- **Parameters**:
  - `invalid` (bool*) - Output parameter to indicate if the document is invalid.
  - `force_load_dimensions` (bool) - Whether to force loading page dimensions.
  - `password` (const char*) - Password for encrypted documents.

#### `num_pages`
- **Description**: Returns the total number of pages in the document.
- **Returns**: (int) Total page count.

#### `get_page_height`
- **Description**: Gets the height of a specific page.
- **Parameters**:
  - `page_index` (int) - The 0-based index of the page.
- **Returns**: (float) The height of the page.

#### `get_page_width`
- **Description**: Gets the width of a specific page.
- **Parameters**:
  - `page_index` (int) - The 0-based index of the page.
- **Returns**: (float) The width of the page.

#### `get_accum_page_height`
- **Description**: Calculates the cumulative height of pages up to a given index.
- **Parameters**:
  - `page_index` (int) - The 0-based index of the page.
- **Returns**: (float) The sum of heights of pages 0 to `page_index - 1`.

#### `get_page_label`
- **Description**: Retrieves the display label for a specific page (e.g., 'iv', '42').
- **Parameters**:
  - `page_index` (int) - The 0-based index of the page.
- **Returns**: (std::wstring) The page label.

#### `get_stext_with_page_number`
- **Description**: Extracts structured text information for a given page.
- **Parameters**:
  - `page_number` (int) - The 0-based page number.
- **Returns**: (fz_stext_page*) Pointer to the structured text page object.

#### `search_text`
- **Description**: Performs a full-text search for a given string.
- **Parameters**:
  - `query` (const std::wstring&) - The text to search for.
  - `case_sensitivity` (SearchCaseSensitivity) - Specifies case sensitivity.
  - `begin_page` (int) - The starting page for the search.
  - `min_page` (int) - The minimum page index to consider.
  - `max_page` (int) - The maximum page index to consider.
- **Returns**: (std::vector<SearchResult>) A list of search results.

#### `search_regex`
- **Description**: Performs a regular expression search.
- **Parameters**:
  - `regex` (const std::wstring&) - The regular expression to search for.
  - `case_sensitivity` (SearchCaseSensitivity) - Specifies case sensitivity.
  - `begin_page` (int) - The starting page for the search.
  - `min_page` (int) - The minimum page index to consider.
  - `max_page` (int) - The maximum page index to consider.
- **Returns**: (std::vector<SearchResult>) A list of search results.

#### `add_bookmark`
- **Description**: Adds a bookmark to the document at a specific vertical offset.
- **Parameters**:
  - `label` (const std::wstring&) - The label for the bookmark.
  - `y_offset` (float) - The vertical offset on the current page.
- **Returns**: (std::string) The unique identifier (UUID) of the added bookmark.

#### `get_bookmarks`
- **Description**: Retrieves all bookmarks in the document.
- **Returns**: (std::vector<BookMark>&) A reference to the list of bookmarks.

#### `delete_bookmark_with_index`
- **Description**: Deletes a bookmark by its index.
- **Parameters**:
  - `index` (int) - The index of the bookmark to delete.

#### `add_highlight`
- **Description**: Adds a highlight to a specified region of the document.
- **Parameters**:
  - `label` (const std::wstring&) - The label for the highlight.
  - `sel_begin` (AbsoluteDocumentPos) - The starting position of the selection.
  - `sel_end` (AbsoluteDocumentPos) - The ending position of the selection.
  - `highlight_type` (char) - The type of highlight (a-z), mapping to configurable colors.
- **Returns**: (std::string) The unique identifier (UUID) of the added highlight.

#### `get_highlights`
- **Description**: Retrieves all highlights in the document.
- **Returns**: (const std::vector<Highlight>&) A constant reference to the list of highlights.

#### `add_mark`
- **Description**: Adds a single-character mark at a specific vertical and horizontal offset.
- **Parameters**:
  - `mark_char` (char) - The character representing the mark.
  - `y_offset` (float) - The vertical offset.
  - `x_offset` (std::optional<float>) - The horizontal offset (optional).
  - `zoom` (std::optional<float>) - The zoom level at which the mark is relevant (optional).

#### `get_mark_if_exists`
- **Description**: Retrieves a mark if it exists.
- **Parameters**:
  - `mark_char` (char) - The character of the mark to find.
- **Returns**: (std::optional<Mark>) An optional Mark object if found.

#### `add_portal`
- **Description**: Adds a portal to the document, linking to another location or document.
- **Parameters**:
  - `portal` (Portal) - The Portal object defining the source and destination.
- **Returns**: (int) The index of the added portal.

#### `find_closest_portal`
- **Description**: Finds the closest portal to a given vertical offset.
- **Parameters**:
  - `to_offset_y` (float) - The vertical offset to search from.
- **Returns**: (std::optional<Portal>) An optional Portal object if a close one is found.

#### `find_reference_with_string`
- **Description**: Attempts to find a reference within the document using heuristic text matching.
- **Parameters**:
  - `text` (const std::wstring&) - The text string to search for.
  - `page_number` (int) - The page number to start the search from.
- **Returns**: (std::vector<IndexedData>) A list of potential reference matches.
```

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

### Export and Import Annotations

Source: https://context7.com/ahrm/sioyek/llms.txt

Export annotations to JSON format or import them from a JSON file.

```python
s.export()                         # export annotations to JSON
s.import_()                        # import annotations from JSON
```

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

### SyncTeX Forward Search

Source: https://context7.com/ahrm/sioyek/llms.txt

Initiates a SyncTeX forward search, jumping from a specified line in a TeX source file to the corresponding location in the PDF.

```bash
sioyek --forward-search-file /path/to/main.tex \
       --forward-search-line 142 \
       /path/to/output.pdf
```

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

### Create Freehand Drawing Annotation

Source: https://context7.com/ahrm/sioyek/llms.txt

Represents a freehand drawing made with a pen or mouse, stored as a sequence of points with thickness and color.

```cpp
FreehandDrawing drawing;
drawing.type  = 'r';    // color type ('r'=red by default)
drawing.alpha = 0.8f;
drawing.points.push_back(FreehandDrawingPoint{
    AbsoluteDocumentPos{0.3f, 400.0f}, /*thickness=*/2.0f
});
```

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

### DocumentManager Class - Document Lifecycle

Source: https://context7.com/ahrm/sioyek/llms.txt

Manage the lifecycle of documents, ensuring they are opened once and shared across windows. Handles document caching, lookup by checksum, and tab management.

```cpp
// Construct (once in main())
DocumentManager document_manager(mupdf_context, &db_manager, &checksummer);

// Get or create a cached Document*
Document* doc = document_manager.get_document(L"/path/to/paper.pdf");
```

```cpp
// Look up by SHA-256 checksum (used to find a document even after rename)
std::optional<std::wstring> path =
    document_manager.get_path_from_hash("a1b2c3d4...");
```

```cpp
// Tab management (tracks open file list for the tab bar)
document_manager.add_tab(L"/path/to/paper.pdf");
std::vector<std::wstring> tabs = document_manager.get_tabs();
document_manager.remove_tab(L"/path/to/paper.pdf");
```

```cpp
// Free a document when no window holds it any more
document_manager.free_document(doc);
```