feat: add native CJK karaoke glow support

app/src/main/java/dev/amenhancer/module/ModuleConstants.kt

@@ -10,6 +10,7 @@ object ModuleConstants {
     const val FEATURE_EDITORIAL_VIDEO = "editorial_video"
     const val FEATURE_PHONE_LIQUID_GLASS = "phone_liquid_glass"
     const val FEATURE_FUTURE_BLUR = "future_blur"
+    const val FEATURE_CJK_KARAOKE_ANIMATION = "cjk_karaoke_animation"
     const val FEATURE_LYRICS_TYPEFACE = "lyrics_typeface"
     const val FEATURE_CUSTOM_LYRICS = "custom_lyrics"
     const val FEATURE_CURRENT_SONG_IDENTITY = "current_song_identity"

app/src/main/java/dev/amenhancer/module/config/ModuleSettingsSchema.kt

@@ -17,6 +17,10 @@ internal object ModuleSettingsSchema {
             default = false,
         ),
         futureBlurEnabled = values.boolean(KEY_FUTURE_BLUR, default = true),
+        cjkKaraokeAnimationEnabled = values.boolean(
+            KEY_CJK_KARAOKE_ANIMATION_ENABLED,
+            default = true,
+        ),
         navigationCompensationEnabled = values.boolean(
             KEY_NAVIGATION_COMPENSATION,
             default = false,
@@ -62,6 +66,7 @@ internal object ModuleSettingsSchema {
             KEY_DISABLE_EDITORIAL_VIDEO_ON_TABLET to settings.disableEditorialVideoOnTablet,
             KEY_PHONE_LIQUID_GLASS to settings.phoneLiquidGlassEnabled,
             KEY_FUTURE_BLUR to settings.futureBlurEnabled,
+            KEY_CJK_KARAOKE_ANIMATION_ENABLED to settings.cjkKaraokeAnimationEnabled,
             KEY_NAVIGATION_COMPENSATION to settings.navigationCompensationEnabled,
             KEY_LYRIC_BLUR_RADIUS_OFFSET to settings.lyricBlurRadiusOffsetPx.coerceIn(
                 ModuleSettings.MIN_LYRIC_BLUR_RADIUS_OFFSET_PX,
@@ -186,6 +191,7 @@ internal object ModuleSettingsSchema {
         KEY_DISABLE_EDITORIAL_VIDEO_ON_TABLET,
         KEY_PHONE_LIQUID_GLASS,
         KEY_FUTURE_BLUR,
+        KEY_CJK_KARAOKE_ANIMATION_ENABLED,
         KEY_NAVIGATION_COMPENSATION,
         KEY_LYRIC_BLUR_RADIUS_OFFSET,
         KEY_TITLE_CORRECTION_ENABLED,
@@ -212,6 +218,7 @@ internal object ModuleSettingsSchema {
         "disable_editorial_video_on_tablet"
     private const val KEY_PHONE_LIQUID_GLASS = "phone_liquid_glass_enabled"
     private const val KEY_FUTURE_BLUR = "future_blur_enabled"
+    private const val KEY_CJK_KARAOKE_ANIMATION_ENABLED = "cjk_karaoke_animation_enabled"
     private const val KEY_NAVIGATION_COMPENSATION = "navigation_compensation_enabled"
     private const val KEY_LYRIC_BLUR_RADIUS_OFFSET = "lyric_blur_radius_offset_px"
     private const val KEY_TITLE_CORRECTION_ENABLED = "title_correction_enabled"

app/src/main/java/dev/amenhancer/module/hook/CjkKaraokeAnimationFeature.kt

@@ -0,0 +1,21 @@
+package dev.amenhancer.module.hook
+
+import dev.amenhancer.module.ModuleConstants
+
+/**
+ * Installs the narrow Apple Music 6.5.2 karaoke animation adaptation.
+ *
+ * The target adapter owns all version and symbol checks; unsupported hosts
+ * therefore report a degraded health result without touching existing lyric
+ * layout or blur paths.
+ */
+internal class CjkKaraokeAnimationFeature : FeatureHook {
+    override val key: String = ModuleConstants.FEATURE_CJK_KARAOKE_ANIMATION
+
+    override fun install(context: HookContext): FeatureInstallResult {
+        if (!context.config.settings().cjkKaraokeAnimationEnabled) {
+            return FeatureInstallResult.disabled("CJK 长尾歌词动画已关闭")
+        }
+        return context.target.cjkKaraokeAnimation.install().toFeatureInstallResult()
+    }
+}

app/src/main/java/dev/amenhancer/module/hook/CjkKaraokeWordGate.kt

@@ -0,0 +1,36 @@
+package dev.amenhancer.module.hook
+
+/**
+ * The host still owns the actual long-glow thresholds. AM++ only answers the
+ * safety question: is this a single, unmerged CJK native word? Returning
+ * false is deliberately fail-closed, so a malformed binding keeps Apple's
+ * original (non-overridden) classifier result.
+ */
+internal data class CjkKaraokeWordTiming(
+    val text: CharSequence,
+    val nativeDurationMs: Int,
+    val cumulativeDurationMs: Int,
+    val cumulativeTextLength: Int,
+    val splitBindingCount: Int,
+    val isBackground: Boolean,
+)
+
+/**
+ * Does not impose Apple's duration/length trigger. Those conditions remain in
+ * z.a0; this gate only blocks merged or multi-character CJK chunks.
+ */
+internal fun isSingleUnmergedCjkWord(timing: CjkKaraokeWordTiming): Boolean {
+    if (timing.isBackground) return false
+    if (timing.splitBindingCount < 0 || timing.splitBindingCount > 1) return false
+
+    val normalized = timing.text.toString().trim()
+    if (normalized.isEmpty() || normalized.codePointCount(0, normalized.length) != 1) {
+        return false
+    }
+    if (!containsCjkKaraokeScript(normalized)) return false
+
+    // g0 writes f/g as the visual chunk's accumulated duration/text length.
+    // Equality with the current native word's values is the non-merged case.
+    return timing.cumulativeDurationMs == timing.nativeDurationMs &&
+        timing.cumulativeTextLength == 1
+}

app/src/main/java/dev/amenhancer/module/hook/FeatureInstallation.kt

@@ -276,6 +276,7 @@ private fun productionFeatureInstallationModule(
                 feature = FutureLyricBlurFeature(),
                 registerResources = { LyricCreditsRowResourceHook.install() },
             ),
+            FeatureInstallationPlan(feature = CjkKaraokeAnimationFeature()),
             FeatureInstallationPlan(
                 feature = LyricsTypefaceFeature(),
                 registerResources = lyricsTypefaceSession::registerResources,

app/src/main/java/dev/amenhancer/module/hook/TargetAdaptation.kt

@@ -16,6 +16,9 @@ internal data class TargetAdaptation(
     val dualPane: DualPaneTarget,
     val editorialVideo: EditorialVideoTarget,
     val bidirectionalLyricBlur: BidirectionalLyricBlurTarget,
+    val cjkKaraokeAnimation: CjkKaraokeAnimationTarget = CjkKaraokeAnimationTarget {
+        TargetCapabilityInstall.Degraded("CJK karaoke animation target was not configured")
+    },
     val lyricsTypeface: LyricsTypefaceTarget = LyricsTypefaceTarget {
         TargetCapabilityInstall.Degraded("Lyrics typeface target was not configured")
     },
@@ -84,6 +87,7 @@ internal data class TargetAdaptation(
                 dualPane = AppleMusicDualPaneTarget(resolver, build),
                 editorialVideo = AppleMusicEditorialVideoTarget(application, resolver),
                 bidirectionalLyricBlur = AppleMusicBidirectionalLyricBlurTarget(resolver),
+                cjkKaraokeAnimation = AppleMusicCjkKaraokeAnimationTarget(resolver),
                 lyricsTypeface = AppleMusicLyricsTypefaceTarget(
                     symbols = resolver,
                     session = lyricsTypefaceSession,
@@ -130,6 +134,10 @@ internal fun interface BidirectionalLyricBlurTarget {
     fun install(): TargetCapabilityInstall
 }
 
+internal fun interface CjkKaraokeAnimationTarget {
+    fun install(): TargetCapabilityInstall
+}
+
 internal fun interface LyricsTypefaceTarget {
     fun install(): TargetCapabilityInstall
 }

app/src/main/java/dev/amenhancer/module/hook/TargetSymbols.kt

@@ -261,6 +261,10 @@ internal enum class TargetSymbolId {
     MEDIA_ENTITY_TO_SONG_CONVERTER,
     STORE_FRONT_LANGUAGE_ARRAY_OWNER,
     STORE_FRONT_LANGUAGE_ARRAY_METHOD,
+    CJK_KARAOKE_ANIMATION_OWNER,
+    CJK_KARAOKE_ANIMATION_METHOD,
+    CJK_UNICODE_BLOCK_HELPER_OWNER,
+    CJK_UNICODE_BLOCK_HELPER_METHOD,
 }
 
 private object AppleMusicProfiles {
@@ -378,12 +382,16 @@ private object AppleMusicProfiles {
             TargetSymbolId.LYRICS_AVAILABILITY_OWNER to "com.apple.android.music.player.e1",
             TargetSymbolId.MEDIA_ENTITY_TO_SONG_CONVERTER to "y8.B",
             TargetSymbolId.STORE_FRONT_LANGUAGE_ARRAY_OWNER to "J5.a",
+            TargetSymbolId.CJK_KARAOKE_ANIMATION_OWNER to "com.apple.android.music.player.z",
+            TargetSymbolId.CJK_UNICODE_BLOCK_HELPER_OWNER to "com.apple.android.music.utils.I0\$a",
         ),
         exactMethods = mapOf(
             TargetSymbolId.PLAYER_ACTIVITY_CREATE_STACKED_NAVIGATION_HOLDER to "k1",
             TargetSymbolId.PLAYER_ACTIVITY_ROOT to "n0",
             TargetSymbolId.LYRICS_ITEM_UPDATE_METHOD to "o2",
             TargetSymbolId.STORE_FRONT_LANGUAGE_ARRAY_METHOD to "b",
+            TargetSymbolId.CJK_KARAOKE_ANIMATION_METHOD to "a0",
+            TargetSymbolId.CJK_UNICODE_BLOCK_HELPER_METHOD to "a",
         ),
         exactFields = mapOf(
             TargetSymbolId.PLAYER_ACTIVITY_BEHAVIOR_FIELD to "c1",
@@ -402,6 +410,36 @@ private object AppleMusicProfiles {
 }
 
 internal object AppleMusicSymbols {
+    /**
+     * Apple Music 6.5.2/1586's karaoke transition entry point
+     * (`com.apple.android.music.player.z.a0(z$a, int, int, int, boolean)`).
+     * This is intentionally profile-only: a structural match on another
+     * obfuscated build could alter the host's animation state machine.
+     */
+    val CjkKaraokeAnimationMethod = methodSymbol(
+        id = "cjk-karaoke-animation-method",
+        profileOwner = TargetSymbolId.CJK_KARAOKE_ANIMATION_OWNER,
+        profilePolicy = ProfilePolicy.EXACT_REQUIRED,
+        exactMethodId = TargetSymbolId.CJK_KARAOKE_ANIMATION_METHOD,
+        fallbackOwner = { false },
+        contract = ::isCjkKaraokeAnimationMethod,
+    )
+
+    /**
+     * Apple Music 6.5.2/1586's UnicodeBlock-set predicate
+     * (`com.apple.android.music.utils.I0$a.a(CharSequence, Set): boolean`).
+     * Like the animation entry point, this must never fall back to a guessed
+     * helper on 6.5.0/6.5.1 or an unknown host build.
+     */
+    val CjkUnicodeBlockPredicateMethod = methodSymbol(
+        id = "cjk-unicode-block-predicate-method",
+        profileOwner = TargetSymbolId.CJK_UNICODE_BLOCK_HELPER_OWNER,
+        profilePolicy = ProfilePolicy.EXACT_REQUIRED,
+        exactMethodId = TargetSymbolId.CJK_UNICODE_BLOCK_HELPER_METHOD,
+        fallbackOwner = { false },
+        contract = ::isCjkUnicodeBlockPredicateMethod,
+    )
+
     val PlayerController = classSymbol(
         id = "player-controller",
         profileId = TargetSymbolId.PLAYER_CONTROLLER,
@@ -1741,6 +1779,25 @@ internal object AppleMusicSymbols {
 
 }
 
+private fun isCjkKaraokeAnimationMethod(method: Method): Boolean =
+    !Modifier.isStatic(method.modifiers) &&
+        method.name == "a0" &&
+        method.parameterTypes.size == 5 &&
+        method.parameterTypes[0].name.endsWith("\$a") &&
+        method.parameterTypes[1] == Int::class.javaPrimitiveType &&
+        method.parameterTypes[2] == Int::class.javaPrimitiveType &&
+        method.parameterTypes[3] == Int::class.javaPrimitiveType &&
+        method.parameterTypes[4] == Boolean::class.javaPrimitiveType &&
+        method.returnType == Void.TYPE
+
+private fun isCjkUnicodeBlockPredicateMethod(method: Method): Boolean =
+    Modifier.isStatic(method.modifiers) &&
+        method.name == "a" &&
+        method.parameterTypes.contentEquals(
+            arrayOf(CharSequence::class.java, java.util.Set::class.java),
+        ) &&
+        method.returnType == Boolean::class.javaPrimitiveType
+
 private fun classSymbol(
     id: String,
     profileId: TargetSymbolId? = null,

app/src/main/java/dev/amenhancer/module/model/ModuleModels.kt

@@ -9,6 +9,8 @@ data class ModuleSettings(
     val disableEditorialVideoOnTablet: Boolean = true,
     val phoneLiquidGlassEnabled: Boolean = false,
     val futureBlurEnabled: Boolean = true,
+    /** Enables the native rush-gradient adaptation for CJK karaoke lyrics. */
+    val cjkKaraokeAnimationEnabled: Boolean = true,
     val navigationCompensationEnabled: Boolean = false,
     val lyricBlurRadiusOffsetPx: Int = 0,
     val titleCorrectionEnabled: Boolean = false,

app/src/main/java/dev/amenhancer/module/ui/EmbeddedSettingsHost.kt

@@ -2237,6 +2237,18 @@ internal class EmbeddedSettingsHost private constructor(
                 ),
             ) { onSettingsChanged(settings.copy(futureBlurEnabled = it)) })
             addView(embeddedDivider(activity))
+            addView(embeddedSettingRow(
+                activity,
+                "CJK 长尾歌词动画",
+                "CJK 歌词启用原生 rush-gradient 动画 · 重开 Apple Music 后生效",
+                settings.cjkKaraokeAnimationEnabled,
+                iconTint = EmbeddedSettingsPalette.accent,
+                iconDrawable = EmbeddedGlyphDrawable(
+                    EmbeddedGlyphKind.Music,
+                    EmbeddedSettingsPalette.accent,
+                ),
+            ) { onSettingsChanged(settings.copy(cjkKaraokeAnimationEnabled = it)) })
+            addView(embeddedDivider(activity))
             addView(embeddedSettingRow(
                 activity,
                 "歌曲名显示修正",

app/src/main/java/dev/amenhancer/module/ui/SettingsActivity.kt

@@ -410,6 +410,15 @@ class SettingsActivity : Activity() {
                 store.saveSettings(store.settings().copy(futureBlurEnabled = enabled))
             })
             addView(insetDivider())
+            addView(settingRow(
+                title = "CJK 长尾歌词动画",
+                summary = "CJK 歌词启用原生 rush-gradient 动画 · 修改后重开 Apple Music",
+                checked = settings.cjkKaraokeAnimationEnabled,
+                enabled = writable,
+            ) { enabled ->
+                store.saveSettings(store.settings().copy(cjkKaraokeAnimationEnabled = enabled))
+            })
+            addView(insetDivider())
             addView(blurRadiusOffsetRow(
                 offsetPx = settings.lyricBlurRadiusOffsetPx,
                 enabled = writable,

app/src/test/java/dev/amenhancer/module/config/ModuleSettingsSchemaTest.kt

@@ -17,6 +17,7 @@ class ModuleSettingsSchemaTest {
                 disableEditorialVideoOnTablet = true,
                 phoneLiquidGlassEnabled = false,
                 futureBlurEnabled = true,
+                cjkKaraokeAnimationEnabled = true,
                 navigationCompensationEnabled = false,
                 lyricBlurRadiusOffsetPx = 0,
                 titleCorrectionEnabled = false,
@@ -45,6 +46,7 @@ class ModuleSettingsSchemaTest {
                 "disable_editorial_video_on_tablet" to false,
                 "phone_liquid_glass_enabled" to true,
                 "future_blur_enabled" to false,
+                "cjk_karaoke_animation_enabled" to true,
                 "navigation_compensation_enabled" to false,
                 "lyric_blur_radius_offset_px" to 6,
                 "title_correction_enabled" to false,
@@ -78,6 +80,7 @@ class ModuleSettingsSchemaTest {
                 "disable_editorial_video_on_tablet" to true,
                 "phone_liquid_glass_enabled" to true,
                 "future_blur_enabled" to true,
+                "cjk_karaoke_animation_enabled" to true,
                 "navigation_compensation_enabled" to false,
                 "lyric_blur_radius_offset_px" to 0,
                 "title_correction_enabled" to false,
@@ -141,6 +144,7 @@ class ModuleSettingsSchemaTest {
                 disableEditorialVideoOnTablet = false,
                 phoneLiquidGlassEnabled = false,
                 futureBlurEnabled = false,
+                cjkKaraokeAnimationEnabled = true,
                 navigationCompensationEnabled = false,
                 lyricBlurRadiusOffsetPx = 0,
                 titleCorrectionEnabled = false,
@@ -246,6 +250,29 @@ class ModuleSettingsSchemaTest {
         )
     }
 
+    @Test
+    fun `cjk karaoke animation defaults on and round trips`() {
+        assertEquals(
+            true,
+            ModuleSettingsSchema.decode(emptyMap<String, Any?>()).cjkKaraokeAnimationEnabled,
+        )
+        assertEquals(
+            true,
+            ModuleSettingsSchema.decode(
+                mapOf("cjk_karaoke_animation_enabled" to "not-a-boolean"),
+            ).cjkKaraokeAnimationEnabled,
+        )
+
+        val encoded = ModuleSettingsSchema.encodeOrdinarySettings(
+            ModuleSettings(cjkKaraokeAnimationEnabled = false),
+        )
+        assertEquals(false, encoded["cjk_karaoke_animation_enabled"])
+        assertEquals(
+            false,
+            ModuleSettingsSchema.decode(encoded).cjkKaraokeAnimationEnabled,
+        )
+    }
+
     @Test
     fun `an old online lyric setting migrates to the custom lyrics gate`() {
         val upgraded = ModuleSettingsSchema.upgrade(

app/src/test/java/dev/amenhancer/module/config/OrdinarySettingsWritePolicyTest.kt

@@ -105,6 +105,7 @@ class OrdinarySettingsWritePolicyTest {
                 "disable_editorial_video_on_tablet" to false,
                 "phone_liquid_glass_enabled" to true,
                 "future_blur_enabled" to false,
+                "cjk_karaoke_animation_enabled" to true,
                 "navigation_compensation_enabled" to false,
                 "lyric_blur_radius_offset_px" to 6,
                 "title_correction_enabled" to false,