Overview

DearOreUI is a native Windows x64 client mod for LeviLamina 26.10.x. It reads the OreUI resources loaded by the original Minecraft client, combines changes declared by multiple mods, and injects the verified result back into the active OreUI page. This lets you focus on writing your own UI without worrying about UI compatibility with other mods. DearOreUI is not a replacement UI and does not directly expose page pointers, compiled bundle internals, or arbitrary local file access to other mods.

What Works

• Runtime hooks. The mod hooks TechStack selection, SceneProvider scene creation, Router navigation, OreUI::View::initialize, OnReadyForBindings, triggerEvent, and ClientInstance::update.
• Real display chain. A cohtml::View is captured, scripts are gated on OnReadyForBindings, and CoherentHostBridge::sendScript executes them. The DOM overlay is built through CSSOM, not innerHTML. This chain was verified on the world list page (/play/all).
• Resource snapshot. FileSystemSourceReader reads the original gui/dist/hbui resources; ResourceUri and ResourceIndex manage paths and access.
• Multi-mod registry. Mods register resources, scripts, styles, UI, and transforms. The central registry sorts dependencies, detects conflicts, and builds one change plan per page.
• Declarative UI. registerMod / registerOverlay feed UiPlanner, MountManager, and UiStateMachine. A 52-component showcase renders end to end on the real client.
• Host bridge. HostDispatcher and HostMethodRegistry route JS requests to native methods with permission checks. JS to native runs over the game's native facet protocol: DearOreUI.call → facet:request → OreUIFacetBridge → HostDispatcher → bus.push.
• Public API. IDearOreUIApi merges Runtime, Resource, Mod, Host, UI, Page, Event, Transform, Diagnostic, Frame, and RuntimeReport facets. External mods obtain it through the pure C ABI bridge (DearOreUI_QueryApi).
• JS namespace. window.__DearOreUI__ (protocol info, bus, ipc) and window.DearOreUI (call, report) are injected, plus base oreui.* namespaces.
• Diagnostics. JSONL event stream, per-stage telemetry, injection reports, and crash probes are written without touching the game installation.

Development Status

Not covered yet:

Progressive API Model

L0  Runtime queries
    ↓
L1  Resource, script, and stylesheet registration
    ↓
L2  Page lifecycle and PageContext
    ↓
L3  UI mounting and page extensions
    ↓
L4  Permission-checked Host API
    ↓
L5  Versioned code and resource transforms
    ↓
L6  Facet providers and advanced compatibility adapters

Most mods should remain at L1. Higher levels are opt-in because they require more knowledge of page lifecycle, host capabilities, compatibility constraints, or original bundle structure.

Multi-Mod Collaboration

Mods do not directly mutate the same intermediate string or write to the game installation. They register declarations with DearOreUI, which creates one page-scoped change plan from the original resource snapshot.

Mod A registration
Mod B registration
Mod C registration
    ↓
Central registry
    ↓
Page, version, and capability filtering
    ↓
Dependency ordering
    ↓
Conflict detection
    ↓
Resource and code transformation
    ↓
Integrity validation
    ↓
One injection submission

The default rules are:

• Resource paths are isolated by mod namespace.
• Identical registrations are idempotent.
• Different contents targeting the same owned resource produce a conflict.
• Replacements require an expected original fingerprint.
• Multiple replacements of the same original code region conflict by default.
• A failed mod change is isolated from unrelated changes.
• An unsupported version preserves the original page.
• Every conflict, skip, failure, and fallback produces a report.

Compatibility

The current target is a client-only LeviLamina mod for Windows x64:

OreUI bundle compatibility cannot be inferred from the Minecraft version alone. Runtime support depends on the detected OreUI resources, Coherent host, page type, resource fingerprint, and available capabilities.

Verified boundary, from the stage 7.1 and stage 8-A client records:

• The display chain works on OreUI-stack pages, currently the world list page.
• One JS→C++ roundtrip has been recorded against the real client.
• JsonUI pages (main menu, in-game screens) run on a different stack and are outside this pipeline.
• Other Minecraft / LeviLamina versions are unverified. "Unknown" must never be treated as "Supported".

Quick Start

Install the latest stable release with lip (run inside your LeviLamina data directory, e.g. the Bedrock Server root):

lip install github.com/copper-lamp/Dear-OreUI

The mod is placed under mods/DearOreUI/. For development builds, prepare a Windows x64 LeviLamina 26.10.x client environment and build from the DearOreUI/ directory.

xmake repo -u
xmake f -a x64 -m release -p windows --target_type=client -y
xmake -v -y

The generated files are placed under bin/. The package metadata is defined in:

• manifest.json
• tooth.json
• xmake.lua

A successful build validates compilation and packaging. It does not prove runtime OreUI injection.

Build From Source

Requirements

• Windows x64
• Git
• xmake
• Visual Studio or an LLVM installation providing Clang-CL
• A LeviLamina 26.10.x development environment

Release build

xmake repo -u
xmake f -a x64 -m release -p windows --target_type=client -y
xmake -v -y

Debug build

xmake f -a x64 -m debug -p windows --target_type=client -y
xmake -v -y

Build artifacts are written to bin/.

Target-client validation

Recorded:

• Hook discovery and page lifecycle events
• Real cohtml::View capture and OnReadyForBindings gating
• C++→JS script execution and CSSOM overlay build
• One JS→C++ Facet roundtrip with bus.push response
• A 52-component UI showcase mount and cleanup on the real client

Still open:

• JsonUI page injection (main menu, in-game screens)
• Multiple JS→C++ dispatches per View
• Uninstall and lifecycle cleanup regression
• Version matrix evidence beyond the recorded target

Roadmap

Contributing

Before contributing, read the development and API documents listed above. Contributions should:

• Distinguish verified facts, design targets, and unresolved runtime questions.
• Keep runtime-sensitive changes behind the existing validation records.
• Include tests or target-client validation for runtime-sensitive changes.
• Update the relevant API, compatibility, diagnostic, and development documents when contracts change.
• Avoid committing secrets, personal paths, build caches, game logs, or private player data.
• Leave the read-only reference project under libs/ unchanged.

See CONTRIBUTING.md for the contribution workflow and SECURITY.md for private vulnerability reporting.

License

DearOreUI is released under the CC0-1.0 license.