Morphe Patcher

<!-- Mirror: this skill also exists in kveld-extra-morphe-patches/.agents/skills (hardlinked to its .claude/skills). When editing shared core guidance, replicate the change there. -->

Morphe Patcher Architectural Guidelines

1. Patch DSL & Typology

Morphe patches are declared using functional Kotlin builder DSLs provided by app.morphe.patcher.patch:

A. bytecodePatch

Primary tool for Dalvik/Smali AST bytecode transformations via dexlib2 fingerprints and instructions.

val myPatch = bytecodePatch(
    name = "Unique Patch Name",
    description = "Concise technical description of the modification.",
    default = true // Whether enabled by default in Morphe Manager
) {
    compatibleWith(Constants.COMPATIBILITY_BRAVE)
    dependsOn(companionResourcePatch) // Optional dependency execution

    execute {
        // Fingerprinting and instruction insertion
    }
}

B. resourcePatch

Used for parsing and transforming decompiled Android resource XML files prior to DEX assembly.

val myResourcePatch = resourcePatch(
    name = "Resource Defaults Patch",
    description = "Overwrites default XML attributes.",
    default = false
) {
    compatibleWith(Constants.COMPATIBILITY_BRAVE)

    execute {
        val targetFile = get("res/xml").listFiles()
            ?.firstOrNull { it.extension == "xml" && it.readText().contains("target_key") }
            ?: return@execute

        document(targetFile.absolutePath).use { doc ->
            val nodes = doc.getElementsByTagName("SwitchPreference")
            for (i in 0 until nodes.length) {
                val elem = nodes.item(i) as? Element ?: continue
                if (elem.getAttribute("android:key") == "target_key") {
                    elem.setAttribute("android:defaultValue", "true")
                }
            }
        }
    }
}

C. rawResourcePatch

Direct byte-level modification of bundled binary shared libraries (.so) or uncompressed assets (assets/index.android.bundle).

val myNativePatch = rawResourcePatch(
    name = "Native Hardening Patch",
    description = "Direct binary patching of libchrome.so",
    default = false
) {
    compatibleWith(Constants.COMPATIBILITY_BRAVE)

    execute {
        val soFile = get("lib/arm64-v8a/libchrome.so")
        if (!soFile.exists()) return@execute
        // Validate offsets and mutate bytes via RandomAccessFile
    }
}

2. Compatibility Scope & Universal Patches

Compatibility is configured via compatibleWith(...):

• Single Target:

  compatibleWith(Constants.COMPATIBILITY_BRAVE)

• Multi-Compatibility Varargs: Accepts multiple Compatibility contracts for cross-target or dual-package applications:

  compatibleWith(targetA, targetB)

• Universal Patches: Omitting compatibleWith(...) entirely produces a universal patch (e.g. LocaleResourceSlimmerPatch, DpiResourceSlimmerPatch). Universal patches are offered across all target applications in Morphe Manager and the CLI patcher. Universal patch sources live in app.morphe.patches.universal; app.morphe.patches.shared holds only contracts and helpers.

3. User Configurable Options (stringOption DSL)

Patches can expose configurable settings to users in Morphe Manager or CLI using the stringOption property delegate:

import app.morphe.patcher.patch.stringOption

val targetLocales by stringOption(
    key = "locales",
    title = "Locales to keep",
    description = "Comma-separated language codes to preserve (e.g. 'en, es, pt, fr, de'). English fallback is always retained.",
    default = "en",
    required = false,
)

Metadata Synchronization Rule

When patch options, descriptions, titles, or defaults are added or modified in Kotlin code, verify catalog registration by running the patch list generator against the built .mpp from a temporary working directory outside the repository, and confirm the expected entries appear. Do NOT run ./gradlew generatePatchesList in the repository checkout: it rewrites the tracked patches-list.json, which the release pipeline regenerates (see AGENTS.md, rule 11).

4. Fingerprint Resolution Strategies

Fingerprints locate target methods across obfuscated versions without hardcoding method names:

1. String Literals: Most resilient anchor. Locate methods referencing unique log strings or preference keys.

   Fingerprint(
       returnType = "V",
       strings = listOf("brave.origin.package_name_android", "brave.origin.product_id_android")
   )

2. Signature & Parameter Filtering: Match methods by strict parameter and return type signatures.

   Fingerprint(
       returnType = "Z",
       parameters = listOf("Lorg/chromium/chrome/browser/profiles/Profile;"),
       strings = listOf("getIsSubscriptionActive profile is null")
   )

3. Instruction Filters & Register Sniffing:

   val fp = Fingerprint(
       definingClass = "Lorg/chromium/chrome/browser/settings/BraveOriginPreferences;",
       returnType = "V",
       parameters = listOf("Ljava/lang/String;", "Landroid/os/Bundle;"),
       filters = listOf(
           methodCall(definingClass = "Lcom/target/Class;", name = "predicate", returnType = "Z")
       )
   )
   val matchIndex = fp.instructionMatches.first().index
   val targetReg = fp.method.getInstruction<OneRegisterInstruction>(matchIndex + 1).registerA

   Runtime safety (device-proven): never remove+replace a lone invoke and never grow the register frame. Both cause device-only VerifyError boot crashes that a green runPatchTest does not catch. Insert-only after move-result, reusing existing registers. See agy-orchestrator references/observations.md:40-41.

5. Metadata Contracts (Constants.kt)

Every patch must reference the shared compatibility object defined centrally in Constants.kt. Never inline Compatibility(...) objects.

Active targets defined in Constants.kt:

1. Brave: Constants.COMPATIBILITY_BRAVE (com.brave.browser)
2. Gboard Lite: Constants.COMPATIBILITY_GBOARD (com.google.android.inputmethod.latin)
3. Hevy: Constants.COMPATIBILITY_HEVY (com.hevy)
4. TikTok: Constants.COMPATIBILITY_TIKTOK (com.zhiliaoapp.musically)
5. NokoPrint: Constants.COMPATIBILITY_NOKOPRINT (com.nokoprint)
6. Xiaomi Earbuds: Constants.COMPATIBILITY_XIAOMI_EARBUDS (com.mi.earphone)

Single Target Version Invariant: Every target app maintains strictly ONE active version (the latest supported release) in targets = listOf(AppTarget(...)). Never retain older versions or multi-version entries in targets.