Metadata-Version: 2.4
Name: unidecompiler-gui
Version: 0.1.11
Summary: Read-only desktop workbench for unidecompiler
Author-email: Wker <1670133844@qq.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/Wker666/unidecompiler
Project-URL: Repository, https://github.com/Wker666/unidecompiler
Project-URL: Issues, https://github.com/Wker666/unidecompiler/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: unidecompiler<0.2.0,>=0.1.4
Requires-Dist: unidecompiler-simulator<0.2.0,>=0.1.2
Requires-Dist: unidecompiler-simulation-host-python<0.2.0,>=0.1.1
Requires-Dist: unidecompiler-gui-sdk<0.2.0,>=0.1.0
Requires-Dist: PySide6>=6.6
Provides-Extra: all-formats
Requires-Dist: unidecompiler-plugin-python-pyc<0.2.0,>=0.1.2; extra == "all-formats"
Requires-Dist: unidecompiler-plugin-jvm-class<0.2.0,>=0.1.2; extra == "all-formats"
Requires-Dist: unidecompiler-plugin-lua<0.2.0,>=0.1.2; extra == "all-formats"
Requires-Dist: unidecompiler-plugin-dotnet-cli<0.2.0,>=0.1.2; extra == "all-formats"
Requires-Dist: unidecompiler-plugin-wasm<0.2.0,>=0.1.3; extra == "all-formats"

# unidecompiler-gui

`unidecompiler-gui` is a read-only PySide6 workbench for the public
`unidecompiler.DecompilerEngine` API. It accepts one artifact, a directory, or
a ZIP/JAR archive and shows pseudocode, AST, bytecode, and diagnostics together.

Install from PyPI; cloning this repository is not required for normal use.

Install the base GUI with its Qt dependency:

```sh
python -m pip install unidecompiler-gui
```

Install all separately published frontend plugins when needed:

```sh
python -m pip install 'unidecompiler-gui[all-formats]'
```

The GUI never imports frontend plugin packages directly. It discovers installed
plugins through `DecompilerEngine` and does not modify input artifacts or save
workspace state. Its optional Simulation tab uses the separate generic IR
simulator and can load a trusted Python runtime file for unresolved functions.

## Structure and Hex analysis

`Structure / Hex` is a read-only, IR-first provenance view. It shows the
generic recovered structure beside a virtualized hexadecimal view of the
original input. Selecting a structure node highlights every exact artifact byte
range known for its source instructions. When a frontend only has a logical VM
offset, the GUI shows that offset and deliberately does not guess a file byte
location. The view is analysis-only: it does not edit bytes, re-encode opcodes,
or execute frontend bytecode.

## Extension templates

Use `Tools -> Export extension template` to create a self-contained starter
project for either a VM frontend or a GUI plugin. The exporter writes a new
directory only and never overwrites an existing path. Each project includes its
matching full development guide, a focused `AGENTS.md`, a README containing the
requested feature, packaging metadata, and test skeletons.

The VM frontend template keeps decoding and thin-IR submission separate from
core recovery. Its optional simulation adapter is data-only; the generic IR
simulator remains responsible for execution. The GUI plugin template depends
only on `unidecompiler-gui-sdk` and remains a read-only application extension.

## Frontend persistence

Custom VM frontend folders registered from `View -> Frontends` are persisted by
the GUI host. After the first successful registration, the GUI restores the
folder on the next startup before opening input files. The frontend registry
and core remain runtime-only; the GUI stores only the normalized source path
and frontend ID.

`Unload selected` removes a frontend from the current process but keeps its
startup record. `Remove from startup` removes it from the current process and
from the GUI startup records, but never deletes the frontend directory from
disk. Built-in entry-point frontends are not stored as user records.

If a saved directory is missing or its manifest/module is invalid, startup
continues. The frontend manager marks the record `unavailable` and shows the
diagnostic so the path can be repaired or removed. Frontend source is trusted
Python code and is not sandboxed.

## GUI plugins

The `Plugins` menu manages optional Python GUI plugins. A plugin is an
application-layer extension, separate from bytecode frontend plugins. It can
inspect immutable snapshots of open documents, functions, AST/reference
summaries and selections; add commands and declarative panels; request
navigation through stable IDs/source locations; and start asynchronous
simulation jobs.

Plugins cannot modify artifacts, generic IR, AST, pseudocode, frontend
registration, or simulator execution. They never receive a Qt Workbench,
frontend decoder payload, `ModuleIR`/`FunctionIR`, simulator frame, or stack.
Function lookup remains frontend-owned: a plugin submits an opaque query while
the GUI host delegates execution to the generic simulator.

Plugins are trusted in-process Python code, with the same permissions as the
GUI process. Review every local folder or GitHub repository before installing.
Dependencies in the manifest are checked at load time but never installed
automatically. Install, update, enable, disable, and removal take effect after
restart.

### Plugin layout

Install a folder with `plugin.toml` through `Plugins -> Manage plugins`, or
install a GitHub `owner/repository` or `/tree/ref` URL.

```toml
[plugin]
id = "example.function-browser"
name = "Function browser"
version = "1.0.0"
api = "1"
entry = "function_browser:register"

[python]
requires = []
```

```python
from unidecompiler_gui_sdk import Command, Panel, PanelState

def register(context):
    context.panels.register(Panel("functions", "Functions"))

    def refresh(ctx):
        document = ctx.active_document
        rows = () if document is None else tuple((item.name, item.status) for item in document.functions)
        ctx.set_panel_state("functions", PanelState.table(("Function", "Status"), rows))

    context.commands.register(Command("refresh", "Refresh function browser", refresh))
    context.subscribe("document_selected", lambda _document: refresh(context))
```

Use only `unidecompiler_gui_sdk` types. Its API is Qt-neutral and versioned;
`plugin.toml` must declare the matching API version. The repository includes
`unidecompiler-gui-test-plugin/` as a complete working example.

To simulate, first call `context.request_simulation_targets(document_id)`. It
returns immediately with a target-discovery job; observe
`simulation_targets_completed`, obtain its `SimulationTargetSnapshot` values
through `context.get_target_job(job_id)`, then pass a selected snapshot's
opaque `query` to `context.submit_simulation(...)`. Observe
`simulation_completed` and use the SDK's `SimulationResultSnapshot`; plugins
never receive simulator runner objects or frontend adapters.
