notifications + window: add Android native plugins

`ux/notifications/events` and `ux/window/events` only had macOS stream
handlers, so on Android/iOS the unconditional Dart subscription threw
MissingPluginException at startup (EventChannel reports activation
failures straight to FlutterError.onError, bypassing the `onError:`
callback).

- Gate each Dart event-channel subscription to platforms that register a
  native handler (`defaultTargetPlatform`), silencing iOS.
- `WindowPlugin`: report app foreground/background as host focus via
  `ProcessLifecycleOwner` ON_START/ON_STOP, so a backgrounded-but-alive
  process reports `focused = false`.
- `NotificationsPlugin`: local notifications (show/cancel by thread/all),
  POST_NOTIFICATIONS request on 13+, and tap routing back over the event
  channel — a tap that cold-starts the process is buffered until Dart
  subscribes.
- Regression tests for the subscription gate plus contract tests for the
  method/event payloads.

android/build.gradle

@@ -51,6 +51,53 @@ android {
     kotlinOptions {
         jvmTarget = '1.8'
     }
+
+    sourceSets {
+        main {
+            // libffmpegJNI.so is built by the buildFfmpegJni task into
+            // build/jniLibs/<abi>/ on first build (and any time the
+            // vendored ffmpeg_jni.cc / CMakeLists.txt change). Adding
+            // the directory here lets AGP package the .so into the
+            // AAR without committing native binaries to the repo.
+            jniLibs.srcDirs += "$buildDir/jniLibs"
+        }
+    }
+}
+
+// FFmpeg video decoder build — runs as part of the normal Android
+// build. On first build for a given checkout it clones Media3 + FFmpeg
+// into build/ffmpeg-work/ and produces libffmpegJNI.so per ABI (~30 min
+// for the FFmpeg static-lib step the first time, fast after). Gradle
+// UP-TO-DATE checking skips the task whenever the vendored JNI source
+// + CMakeLists are unchanged. See android/ffmpeg/README.md.
+def ffmpegSrcDir = file("$projectDir/ffmpeg")
+def ffmpegWorkDir = file("$buildDir/ffmpeg-work")
+def ffmpegOutDir = file("$buildDir/jniLibs")
+def ndkCmakeBin = "${android.sdkDirectory}/cmake/3.22.1/bin"
+def supportedAbis = ['armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64']
+
+task buildFfmpegJni(type: Exec) {
+    group = 'build'
+    description = 'Clones Media3 + FFmpeg if needed, builds libffmpegJNI.so per Android ABI'
+
+    inputs.file "$ffmpegSrcDir/ffmpeg_jni.cc"
+    inputs.file "$ffmpegSrcDir/CMakeLists.txt"
+    inputs.file "$ffmpegSrcDir/build_ffmpeg.sh"
+    supportedAbis.each { abi ->
+        outputs.file "$ffmpegOutDir/$abi/libffmpegJNI.so"
+    }
+
+    workingDir ffmpegSrcDir
+    commandLine 'bash', "$ffmpegSrcDir/build_ffmpeg.sh"
+    environment 'JNI_SRC', ffmpegSrcDir.absolutePath
+    environment 'NDK_PATH', android.ndkDirectory.absolutePath
+    environment 'CMAKE_PATH', ndkCmakeBin
+    environment 'OUTPUT_DIR', ffmpegOutDir.absolutePath
+    environment 'WORK_DIR', ffmpegWorkDir.absolutePath
+}
+
+afterEvaluate {
+    preBuild.dependsOn buildFfmpegJni
 }
 
 dependencies {

android/ffmpeg/CMakeLists.txt

@@ -0,0 +1,64 @@
+#
+# Copyright 2021 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# LINT.IfChange
+cmake_minimum_required(VERSION 3.21.0 FATAL_ERROR)
+# LINT.ThenChange(../../../build.gradle)
+
+# Enable C++11 features.
+set(CMAKE_CXX_STANDARD 11)
+
+project(libffmpegJNI C CXX)
+
+set(ffmpeg_location "${CMAKE_CURRENT_SOURCE_DIR}/ffmpeg")
+set(ffmpeg_binaries "${ffmpeg_location}/android-libs/${ANDROID_ABI}")
+
+foreach(ffmpeg_lib avutil swresample avcodec)
+    set(ffmpeg_lib_filename lib${ffmpeg_lib}.a)
+    set(ffmpeg_lib_file_path ${ffmpeg_binaries}/${ffmpeg_lib_filename})
+    add_library(
+            ${ffmpeg_lib}
+            STATIC
+            IMPORTED)
+    set_target_properties(
+            ${ffmpeg_lib} PROPERTIES
+            IMPORTED_LOCATION
+            ${ffmpeg_lib_file_path})
+endforeach()
+
+include_directories(${ffmpeg_location})
+find_library(android_log_lib log)
+
+add_library(ffmpegJNI
+            SHARED
+            ffmpeg_jni.cc)
+
+target_link_libraries(ffmpegJNI
+                      PRIVATE android
+                      PRIVATE swresample
+                      PRIVATE avcodec
+                      PRIVATE avutil
+                      PRIVATE ${android_log_lib})
+
+# Additional flags needed for "arm64-v8a" from NDK 23.1.7779620 and above.
+# See https://github.com/google/ExoPlayer/issues/9933#issuecomment-1029775358.
+if(ANDROID_ABI STREQUAL "arm64-v8a")
+    target_link_options(ffmpegJNI PRIVATE "-Wl,-Bsymbolic")
+endif()
+
+# Enable 16 KB ELF alignment.
+target_link_options(ffmpegJNI
+                    PRIVATE "-Wl,-z,max-page-size=16384")

android/ffmpeg/LICENSE-FFMPEG.txt

@@ -0,0 +1,502 @@
+                  GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 2.1, February 1999
+
+ Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it.  You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+                  GNU LESSER GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Use a suitable shared library mechanism for linking with the
+    Library.  A suitable mechanism is one that (1) uses at run time a
+    copy of the library already present on the user's computer system,
+    rather than copying library functions into the executable, and (2)
+    will operate properly with a modified version of the library, if
+    the user installs one, as long as the modified version is
+    interface-compatible with the version that the work was made with.
+
+    c) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    d) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    e) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+                            NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!

android/ffmpeg/README.md

@@ -0,0 +1,81 @@
+# Vendored FFmpeg video decoder for `ux`
+
+This directory contains the JNI source + Gradle build wiring for
+`libffmpegJNI.so`, the LGPL-licensed FFmpeg shared library that backs
+`io.swipelab.ux.video.ffmpeg.FfmpegVideoRenderer`. The renderer is
+slotted ahead of `MediaCodecVideoRenderer` so iOS H.264 streams with
+deep DPB (`has_b_frames > 8`) and full-range YUV play on devices where
+the platform decoder fails (notably Huawei Mate 20 on EMUI 11).
+
+## How it builds
+
+The native library is produced by the `:ux:buildFfmpegJni` Gradle task,
+wired as a dependency of `preBuild`. On any consumer build
+(`flutter build apk`, `./gradlew assembleRelease`, IDE sync) the task
+runs automatically; Gradle's UP-TO-DATE checking skips it when nothing
+relevant changed.
+
+What the task does:
+
+1. Clones upstream Media3 (`1.9.2`) and FFmpeg (`release/6.0`) into
+   `<ux-android-build>/ffmpeg-work/` if missing — once per checkout.
+2. Drops the vendored `ffmpeg_jni.cc` + `CMakeLists.txt` over the
+   upstream Media3 copies so the build produces a video-capable JNI.
+3. Builds FFmpeg static libs (`libavcodec`, `libavutil`,
+   `libswresample`) with H.264 decoder enabled for `armeabi-v7a`,
+   `arm64-v8a`, `x86`, `x86_64`. Slow part — first build only
+   (~30 min on a typical x86 host, ~2 min on Apple Silicon). Static
+   libs are cached in `ffmpeg-work/` and reused on subsequent runs.
+4. Cross-compiles `libffmpegJNI.so` per ABI via CMake + Ninja and
+   writes the result into `<ux-android-build>/jniLibs/<abi>/`. AGP
+   picks them up via the `jniLibs.srcDirs +=` line in
+   [build.gradle](../build.gradle) and bundles them in the AAR.
+
+What ships in git:
+
+* `ffmpeg_jni.cc` — JNI bridge exposing the five entry points
+  `FfmpegVideoDecoder.java` calls: initialize / sendPacket /
+  receiveFrame / flush / release. Adapted from Media3's audio-only
+  template; the audio path was dropped (MediaCodec AAC works
+  everywhere we ship to).
+* `CMakeLists.txt` — links the FFmpeg static libs into
+  `libffmpegJNI.so`.
+* `build_ffmpeg.sh` — orchestrates the clone + static-lib build +
+  JNI link. Env-driven, invoked only by the Gradle task — not
+  intended to be run by hand.
+* `LICENSE-FFMPEG.txt` — LGPL v2.1 text. Required attribution.
+
+**No `.so` files in git.** Everything under `<build>/jniLibs/` is
+generated on demand; `/build` is already in [.gitignore](../.gitignore).
+
+## License
+
+FFmpeg is LGPL v2.1. We link to it dynamically (consumer apps load
+`libffmpegJNI.so` at runtime via `System.loadLibrary`), which keeps the
+LGPL boundary intact and does not impose copyleft on the consuming
+app. The build configuration in upstream Media3's `build_ffmpeg.sh`
+intentionally omits `--enable-gpl` and `--enable-nonfree` to keep the
+binaries LGPL-only. Do not add codecs that require GPL configuration
+(e.g. x264) — that would taint the artifact.
+
+## Pinned versions
+
+* Media3 `1.9.2` (matches the version used by the rest of `ux`).
+* FFmpeg `release/6.0` (matches Media3's tested compatibility window).
+* Android NDK is resolved via `android.ndkDirectory` from AGP — the
+  NDK version your Android project pins, normally r27 on a recent
+  AGP. Older NDKs may fail the 16-KB page-size alignment check
+  enforced for Android 15.
+
+Bumping either version: edit the `MEDIA3_TAG` / `FFMPEG_TAG`
+constants near the top of `build_ffmpeg.sh`, then `./gradlew
+:ux:buildFfmpegJni --rerun-tasks` to force a rebuild.
+
+## Why we vendor this instead of using `media3-decoder-ffmpeg`
+
+Media3's published FFmpeg extension is audio-only.
+`ExperimentalFfmpegVideoRenderer` in the same library has been a stub
+since 2020 — `createDecoder()` returns null, `supportsFormat()` returns
+`FORMAT_UNSUPPORTED_TYPE`. The community alternative (NextLib) is
+GPL-3.0, which would impose copyleft on consumers. So we built our own
+on top of the same JNI skeleton.

android/ffmpeg/build_ffmpeg.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+# Builds libffmpegJNI.so for all 4 Android ABIs from vendored JNI sources
+# (ffmpeg_jni.cc + CMakeLists.txt in this directory) against upstream
+# Media3 + FFmpeg cloned into WORK_DIR. Driven entirely by environment
+# variables Gradle sets in the buildFfmpegJni task — no user-facing
+# flags. Reruns are cheap once WORK_DIR is populated (Gradle UP-TO-DATE
+# skips the script entirely when JNI sources haven't changed, and even
+# when forced, the FFmpeg static libs are reused if present).
+#
+# Required env:
+#   JNI_SRC      — this directory (vendored ffmpeg_jni.cc + CMakeLists.txt)
+#   NDK_PATH     — Android NDK root
+#   CMAKE_PATH   — directory containing the cmake + ninja binaries
+#   OUTPUT_DIR   — where to drop the final libffmpegJNI.so per ABI
+#   WORK_DIR     — scratch directory for upstream clones + intermediate
+#                  build artefacts (lives under build/ so a clean wipes it)
+#
+# License: FFmpeg is LGPL v2.1. We link to it dynamically (consumers
+# load libffmpegJNI.so at runtime), keeping the LGPL boundary intact and
+# not imposing copyleft on the consuming app. The build below
+# intentionally omits --enable-gpl and --enable-nonfree.
+
+set -euo pipefail
+
+: "${JNI_SRC:?JNI_SRC env var not set}"
+: "${NDK_PATH:?NDK_PATH env var not set}"
+: "${CMAKE_PATH:?CMAKE_PATH env var not set}"
+: "${OUTPUT_DIR:?OUTPUT_DIR env var not set}"
+: "${WORK_DIR:?WORK_DIR env var not set}"
+
+MEDIA3_TAG="${MEDIA3_TAG:-1.9.2}"
+FFMPEG_TAG="${FFMPEG_TAG:-release/6.0}"
+ABIS="${ABIS:-armeabi-v7a arm64-v8a x86 x86_64}"
+MIN_SDK="${MIN_SDK:-21}"
+
+case "$(uname -s)" in
+  Darwin*) HOST_PLATFORM=darwin-x86_64 ;;
+  Linux*)  HOST_PLATFORM=linux-x86_64 ;;
+  *) echo "Unsupported host: $(uname -s)" >&2; exit 1 ;;
+esac
+
+mkdir -p "$WORK_DIR" "$OUTPUT_DIR"
+cd "$WORK_DIR"
+
+# Serialise concurrent invocations on the shared WORK_DIR so two
+# Gradle daemons (or two parallel app builds depending on this AAR
+# via the same checkout) can't race on clone / cmake / ninja.
+# `mkdir` is atomic per POSIX — first caller wins. `flock` would be
+# nicer but macOS doesn't ship it. A stale lock from a killed prior
+# run (>30 min old) is broken automatically. The trap clears the
+# lock on normal exit.
+LOCK_DIR="$WORK_DIR/.build-lock"
+if [[ -d "$LOCK_DIR" ]]; then
+  if find "$LOCK_DIR" -maxdepth 0 -mmin +30 2>/dev/null | grep -q .; then
+    echo "[ffmpeg-build] removing stale lock (>30 min old)"
+    rm -rf "$LOCK_DIR"
+  fi
+fi
+LOCK_WAIT_SECS=0
+while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+  if [[ "$LOCK_WAIT_SECS" -ge 1800 ]]; then
+    echo "[ffmpeg-build] timed out waiting for $LOCK_DIR" >&2
+    exit 1
+  fi
+  if [[ "$LOCK_WAIT_SECS" -eq 0 ]]; then
+    echo "[ffmpeg-build] another build in progress at $LOCK_DIR, waiting..."
+  fi
+  sleep 5
+  LOCK_WAIT_SECS=$((LOCK_WAIT_SECS + 5))
+done
+trap 'rm -rf "$LOCK_DIR"' EXIT
+
+# Sentinel files mark a clone as fully complete so an interrupted
+# clone (network drop, ^C, OOM kill) doesn't leave a half-populated
+# directory the next run mistakes for a finished checkout. Clone
+# into a staging dir, then atomic-rename into place once the
+# sentinel is written.
+clone_if_missing() {
+  local target="$1"
+  local sentinel="$target/.ux-ffmpeg-build-complete"
+  local tag="$2"
+  local url="$3"
+  local label="$4"
+  if [[ -f "$sentinel" ]]; then
+    return
+  fi
+  # Stale partial clone — wipe before re-clone.
+  rm -rf "$target" "${target}.staging"
+  echo "[ffmpeg-build] cloning $label @${tag}"
+  git clone --depth 1 --branch "$tag" "$url" "${target}.staging"
+  touch "${target}.staging/.ux-ffmpeg-build-complete"
+  mv "${target}.staging" "$target"
+}
+
+# 1. Upstream sources — clone once, reuse on subsequent runs.
+MEDIA3_DIR="$WORK_DIR/media3"
+clone_if_missing "$MEDIA3_DIR" "$MEDIA3_TAG" \
+  "https://github.com/androidx/media.git" "Media3"
+
+FFMPEG_DIR="$MEDIA3_DIR/libraries/decoder_ffmpeg/src/main/jni/ffmpeg"
+clone_if_missing "$FFMPEG_DIR" "$FFMPEG_TAG" \
+  "https://git.ffmpeg.org/ffmpeg.git" "FFmpeg"
+
+# 2. Drop our extended JNI source + CMake config over the upstream copies
+#    so the build produces a video-capable libffmpegJNI.so.
+JNI_BUILD_DIR="$MEDIA3_DIR/libraries/decoder_ffmpeg/src/main/jni"
+cp "$JNI_SRC/ffmpeg_jni.cc" "$JNI_BUILD_DIR/ffmpeg_jni.cc"
+cp "$JNI_SRC/CMakeLists.txt" "$JNI_BUILD_DIR/CMakeLists.txt"
+
+# 3. Build FFmpeg static libs per ABI (H.264 decoder only). The
+#    sentinel below skips this step if all 4 ABIs already have the
+#    static libs from a previous run — important because the FFmpeg
+#    static build is the slow part (~30 min for 4 ABIs); subsequent
+#    Gradle runs just need to re-link libffmpegJNI.so (~5 sec / ABI).
+MODULE_PATH="$MEDIA3_DIR/libraries/decoder_ffmpeg/src/main"
+NEED_STATIC_BUILD=0
+for ABI in $ABIS; do
+  if [[ ! -f "$JNI_BUILD_DIR/ffmpeg/android-libs/$ABI/libavcodec.a" ]]; then
+    NEED_STATIC_BUILD=1
+    break
+  fi
+done
+
+if [[ "$NEED_STATIC_BUILD" -eq 1 ]]; then
+  echo "[ffmpeg-build] building FFmpeg static libs (slow on first run)"
+  chmod +x "$JNI_BUILD_DIR/build_ffmpeg.sh"
+  "$JNI_BUILD_DIR/build_ffmpeg.sh" \
+    "$MODULE_PATH" "$NDK_PATH" "$HOST_PLATFORM" "$MIN_SDK" h264
+else
+  echo "[ffmpeg-build] FFmpeg static libs already present, reusing"
+fi
+
+# 4. Cross-build libffmpegJNI.so per ABI via CMake + Ninja.
+export PATH="$CMAKE_PATH:$PATH"
+for ABI in $ABIS; do
+  ABI_BUILD_DIR="$WORK_DIR/jni-out/$ABI"
+  mkdir -p "$ABI_BUILD_DIR"
+  cmake -G Ninja \
+    -DCMAKE_TOOLCHAIN_FILE="$NDK_PATH/build/cmake/android.toolchain.cmake" \
+    -DANDROID_ABI="$ABI" \
+    -DANDROID_PLATFORM="android-$MIN_SDK" \
+    -DCMAKE_BUILD_TYPE=Release \
+    -S "$JNI_BUILD_DIR" -B "$ABI_BUILD_DIR" >/dev/null
+  ninja -C "$ABI_BUILD_DIR" >/dev/null
+
+  DEST="$OUTPUT_DIR/$ABI"
+  mkdir -p "$DEST"
+  cp "$ABI_BUILD_DIR/libffmpegJNI.so" "$DEST/libffmpegJNI.so"
+done
+
+echo "[ffmpeg-build] libffmpegJNI.so ready in $OUTPUT_DIR"

android/ffmpeg/ffmpeg_jni.cc

@@ -0,0 +1,480 @@
+/*
+ * Copyright 2026 swipelab.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * JNI bridge for the ux FFmpeg video decoder. Exposes a small surface
+ * (init / sendPacket / receiveFrame / flush / release) that
+ * FfmpegVideoDecoder.java drives. The audio path was dropped — Media3's
+ * MediaCodec AAC decoder handles audio on every device we ship to.
+ */
+#include <android/log.h>
+#include <jni.h>
+#include <stdlib.h>
+#include <string.h>
+
+extern "C" {
+#ifdef __cplusplus
+#define __STDC_CONSTANT_MACROS
+#ifdef _STDINT_H
+#undef _STDINT_H
+#endif
+#include <stdint.h>
+#endif
+#include <libavcodec/avcodec.h>
+#include <libavutil/error.h>
+#include <libavutil/imgutils.h>
+#include <libavutil/opt.h>
+#include <libavutil/pixfmt.h>
+}
+
+#define LOG_TAG "ux_ffmpeg_jni"
+#define LOGE(...) \
+  ((void)__android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__))
+#define LOGI(...) \
+  ((void)__android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__))
+#define LOGD(...) \
+  ((void)__android_log_print(ANDROID_LOG_DEBUG, LOG_TAG, __VA_ARGS__))
+
+#define LIBRARY_FUNC(RETURN_TYPE, NAME, ...)                                  \
+  extern "C" {                                                                \
+  JNIEXPORT RETURN_TYPE                                                       \
+  Java_io_swipelab_ux_video_ffmpeg_FfmpegLibrary_##NAME(JNIEnv* env,          \
+                                                        jobject thiz,         \
+                                                        ##__VA_ARGS__);       \
+  }                                                                           \
+  JNIEXPORT RETURN_TYPE                                                       \
+  Java_io_swipelab_ux_video_ffmpeg_FfmpegLibrary_##NAME(                      \
+      JNIEnv* env, jobject thiz, ##__VA_ARGS__)
+
+#define VIDEO_DECODER_FUNC(RETURN_TYPE, NAME, ...)                            \
+  extern "C" {                                                                \
+  JNIEXPORT RETURN_TYPE                                                       \
+  Java_io_swipelab_ux_video_ffmpeg_FfmpegVideoDecoder_##NAME(                 \
+      JNIEnv* env, jobject thiz, ##__VA_ARGS__);                              \
+  }                                                                           \
+  JNIEXPORT RETURN_TYPE                                                       \
+  Java_io_swipelab_ux_video_ffmpeg_FfmpegVideoDecoder_##NAME(                 \
+      JNIEnv* env, jobject thiz, ##__VA_ARGS__)
+
+#define ERROR_STRING_BUFFER_LENGTH 256
+
+// Mirrored in FfmpegVideoDecoder.java.
+static const int VIDEO_DECODER_SUCCESS = 0;
+static const int VIDEO_DECODER_ERROR_INVALID_DATA = -1;
+static const int VIDEO_DECODER_ERROR_OTHER = -2;
+static const int VIDEO_DECODER_READ_AGAIN = -3;
+
+// VideoDecoderOutputBuffer.COLORSPACE_* mirror.
+static const int COLORSPACE_UNKNOWN = 0;
+static const int COLORSPACE_BT601 = 1;
+static const int COLORSPACE_BT709 = 2;
+static const int COLORSPACE_BT2020 = 3;
+
+static jmethodID initForYuvFrameMethod;
+static jfieldID dataField;
+// Carries full-range info (1) vs limited-range info (0) per frame to
+// Java so the GL shader picks the matching BT.709 conversion matrix.
+static jfieldID decoderPrivateField;
+// Reassigned per output frame to the decoded frame's actual PTS
+// (NOT the input packet's PTS — for H.264 reorder, output display
+// order differs from input decode order, and using the input PTS
+// scrambles ExoPlayer's frame-late detection so it drops half the
+// stream).
+static jfieldID timeUsField;
+
+static int colorspaceFromAVColorSpace(AVColorSpace cs) {
+  switch (cs) {
+    case AVCOL_SPC_BT709:
+      return COLORSPACE_BT709;
+    case AVCOL_SPC_BT470BG:
+    case AVCOL_SPC_SMPTE170M:
+      return COLORSPACE_BT601;
+    case AVCOL_SPC_BT2020_NCL:
+    case AVCOL_SPC_BT2020_CL:
+      return COLORSPACE_BT2020;
+    default:
+      return COLORSPACE_UNKNOWN;
+  }
+}
+
+static void logError(const char* fn, int err) {
+  char buf[ERROR_STRING_BUFFER_LENGTH] = {0};
+  av_strerror(err, buf, ERROR_STRING_BUFFER_LENGTH);
+  LOGE("Error in %s: %s", fn, buf);
+}
+
+static int transformError(int err) {
+  return err == AVERROR_INVALIDDATA ? VIDEO_DECODER_ERROR_INVALID_DATA
+                                    : VIDEO_DECODER_ERROR_OTHER;
+}
+
+// Decoder state held across JNI calls; the long handle returned by
+// videoInitialize is a pointer to one of these. AVCodecContext alone
+// isn't enough because we want a reusable AVFrame to avoid per-decode
+// allocation churn, plus a pending_frame slot to cache frames pulled
+// during a send-side EAGAIN drain so the next receiveFrame call emits
+// them in order instead of losing them.
+struct UxFfmpegVideoContext {
+  AVCodecContext* codec_ctx = nullptr;
+  AVFrame* frame = nullptr;
+  AVFrame* pending_frame = nullptr;
+  bool has_pending = false;
+};
+
+static void releaseContext(UxFfmpegVideoContext* ctx) {
+  if (!ctx) return;
+  if (ctx->frame) {
+    av_frame_free(&ctx->frame);
+  }
+  if (ctx->pending_frame) {
+    av_frame_free(&ctx->pending_frame);
+  }
+  if (ctx->codec_ctx) {
+    avcodec_free_context(&ctx->codec_ctx);
+  }
+  delete ctx;
+}
+
+jint JNI_OnLoad(JavaVM* vm, void* reserved) {
+  JNIEnv* env;
+  if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
+    LOGE("JNI_OnLoad: GetEnv failed");
+    return -1;
+  }
+  jclass clazz =
+      env->FindClass("androidx/media3/decoder/VideoDecoderOutputBuffer");
+  if (!clazz) {
+    LOGE("JNI_OnLoad: FindClass(VideoDecoderOutputBuffer) failed");
+    return -1;
+  }
+  initForYuvFrameMethod = env->GetMethodID(clazz, "initForYuvFrame", "(IIIII)Z");
+  if (!initForYuvFrameMethod) {
+    LOGE("JNI_OnLoad: GetMethodID(initForYuvFrame) failed");
+    return -1;
+  }
+  dataField = env->GetFieldID(clazz, "data", "Ljava/nio/ByteBuffer;");
+  if (!dataField) {
+    LOGE("JNI_OnLoad: GetFieldID(data) failed");
+    return -1;
+  }
+  decoderPrivateField = env->GetFieldID(clazz, "decoderPrivate", "J");
+  if (!decoderPrivateField) {
+    LOGE("JNI_OnLoad: GetFieldID(decoderPrivate) failed");
+    return -1;
+  }
+  // timeUs lives on the DecoderOutputBuffer base class but is
+  // discoverable via the concrete subclass.
+  timeUsField = env->GetFieldID(clazz, "timeUs", "J");
+  if (!timeUsField) {
+    LOGE("JNI_OnLoad: GetFieldID(timeUs) failed");
+    return -1;
+  }
+  return JNI_VERSION_1_6;
+}
+
+LIBRARY_FUNC(jstring, ffmpegGetVersion) {
+  return env->NewStringUTF(LIBAVCODEC_IDENT);
+}
+
+LIBRARY_FUNC(jint, ffmpegGetInputBufferPaddingSize) {
+  return (jint)AV_INPUT_BUFFER_PADDING_SIZE;
+}
+
+LIBRARY_FUNC(jboolean, ffmpegHasDecoder, jstring codecName) {
+  if (!codecName) return JNI_FALSE;
+  const char* name = env->GetStringUTFChars(codecName, nullptr);
+  const AVCodec* codec = avcodec_find_decoder_by_name(name);
+  env->ReleaseStringUTFChars(codecName, name);
+  return codec != nullptr;
+}
+
+VIDEO_DECODER_FUNC(jlong, ffmpegVideoInitialize, jstring codecName,
+                   jbyteArray extraData, jint threads) {
+  if (!codecName) {
+    LOGE("ffmpegVideoInitialize: codecName is null");
+    return 0L;
+  }
+  const char* name = env->GetStringUTFChars(codecName, nullptr);
+  const AVCodec* codec = avcodec_find_decoder_by_name(name);
+  env->ReleaseStringUTFChars(codecName, name);
+  if (!codec) {
+    LOGE("ffmpegVideoInitialize: codec not found");
+    return 0L;
+  }
+
+  UxFfmpegVideoContext* ctx = new UxFfmpegVideoContext();
+  ctx->codec_ctx = avcodec_alloc_context3(codec);
+  if (!ctx->codec_ctx) {
+    LOGE("ffmpegVideoInitialize: avcodec_alloc_context3 failed");
+    releaseContext(ctx);
+    return 0L;
+  }
+
+  if (extraData) {
+    jsize size = env->GetArrayLength(extraData);
+    ctx->codec_ctx->extradata =
+        (uint8_t*)av_mallocz(size + AV_INPUT_BUFFER_PADDING_SIZE);
+    if (!ctx->codec_ctx->extradata) {
+      LOGE("ffmpegVideoInitialize: extradata alloc failed");
+      releaseContext(ctx);
+      return 0L;
+    }
+    env->GetByteArrayRegion(extraData, 0, size,
+                            (jbyte*)ctx->codec_ctx->extradata);
+    ctx->codec_ctx->extradata_size = size;
+  }
+
+  ctx->codec_ctx->thread_count = threads > 0 ? threads : 0;
+  // FF_THREAD_SLICE only. FRAME threading buffers thread_count
+  // input frames before producing output, pushing decoded frames
+  // past their PTS deadline and causing ExoPlayer to drop them.
+  // Most iOS-captured H.264 emits one slice per frame, so slice
+  // threading degenerates to single-threaded; libavcodec's H.264
+  // decoder does not auto-promote SLICE-only to FRAME, so we
+  // accept modest throughput in exchange for low latency. 480p
+  // decode is ~2 ms per frame single-threaded on any modern ARM
+  // core anyway.
+  ctx->codec_ctx->thread_type = FF_THREAD_SLICE;
+  ctx->codec_ctx->err_recognition = AV_EF_IGNORE_ERR;
+  // PTS values are passed in microseconds (Media3's native unit),
+  // and libavcodec propagates packet.pts → frame.pts through the
+  // reorder buffer so we can recover display-order timestamps on
+  // receive.
+  ctx->codec_ctx->time_base = AVRational{1, 1000000};
+  ctx->codec_ctx->pkt_timebase = AVRational{1, 1000000};
+
+  int result = avcodec_open2(ctx->codec_ctx, codec, nullptr);
+  if (result < 0) {
+    logError("avcodec_open2", result);
+    releaseContext(ctx);
+    return 0L;
+  }
+
+  ctx->frame = av_frame_alloc();
+  ctx->pending_frame = av_frame_alloc();
+  if (!ctx->frame || !ctx->pending_frame) {
+    LOGE("ffmpegVideoInitialize: av_frame_alloc failed");
+    releaseContext(ctx);
+    return 0L;
+  }
+  ctx->has_pending = false;
+  return (jlong)ctx;
+}
+
+VIDEO_DECODER_FUNC(jint, ffmpegVideoSendPacket, jlong handle, jobject inputData,
+                   jint inputSize, jlong ptsUs) {
+  if (!handle) {
+    LOGE("ffmpegVideoSendPacket: null handle");
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+  if (!inputData || inputSize <= 0) {
+    LOGE("ffmpegVideoSendPacket: bad input");
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+  UxFfmpegVideoContext* ctx = (UxFfmpegVideoContext*)handle;
+  uint8_t* buf = (uint8_t*)env->GetDirectBufferAddress(inputData);
+  if (!buf) {
+    LOGE("ffmpegVideoSendPacket: GetDirectBufferAddress null");
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+  AVPacket* pkt = av_packet_alloc();
+  if (!pkt) {
+    LOGE("ffmpegVideoSendPacket: av_packet_alloc failed");
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+  pkt->data = buf;
+  pkt->size = inputSize;
+  // Media3's C.TIME_UNSET is Long.MIN_VALUE which by happy coincidence
+  // equals libavcodec's AV_NOPTS_VALUE; gate it explicitly so a future
+  // Media3 sentinel change doesn't silently scramble PTS recovery.
+  pkt->pts = (ptsUs == INT64_MIN) ? AV_NOPTS_VALUE : (int64_t)ptsUs;
+  pkt->dts = AV_NOPTS_VALUE;
+
+  // Per libavcodec contract, EAGAIN on send means the packet was NOT
+  // consumed and the caller must drain output before re-sending. We
+  // can't return EAGAIN to SimpleDecoder (its 1-in / 1-out model
+  // would consume the input buffer and lose the packet), so when the
+  // queue is full we drain one frame into pending_frame and retry.
+  // pending_frame is then emitted by the next ffmpegVideoReceiveFrame
+  // call before pulling a new one from libavcodec.
+  int result = avcodec_send_packet(ctx->codec_ctx, pkt);
+  if (result == AVERROR(EAGAIN) && !ctx->has_pending) {
+    int recv = avcodec_receive_frame(ctx->codec_ctx, ctx->pending_frame);
+    if (recv == 0) {
+      ctx->has_pending = true;
+      result = avcodec_send_packet(ctx->codec_ctx, pkt);
+    } else {
+      logError("send-EAGAIN drain receive", recv);
+    }
+  }
+  av_packet_free(&pkt);
+  if (result == AVERROR(EAGAIN)) {
+    // Pending slot already full; drop this packet rather than block.
+    // Should never happen at steady state given numOutputBuffers=16.
+    LOGE("ffmpegVideoSendPacket: queue full and pending slot occupied");
+    return VIDEO_DECODER_READ_AGAIN;
+  }
+  if (result < 0) {
+    logError("avcodec_send_packet", result);
+    return transformError(result);
+  }
+  return VIDEO_DECODER_SUCCESS;
+}
+
+// Pulls the next decoded frame and writes it into the Java
+// VideoDecoderOutputBuffer's YUV planes. Returns:
+//   VIDEO_DECODER_SUCCESS       -> frame written
+//   VIDEO_DECODER_READ_AGAIN    -> no frame yet, send more packets
+//   VIDEO_DECODER_ERROR_*       -> fatal
+VIDEO_DECODER_FUNC(jint, ffmpegVideoReceiveFrame, jlong handle,
+                   jobject outputBuffer) {
+  if (!handle) {
+    LOGE("ffmpegVideoReceiveFrame: null handle");
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+  UxFfmpegVideoContext* ctx = (UxFfmpegVideoContext*)handle;
+  AVFrame* f = ctx->frame;
+  // If a frame was drained into pending_frame to recover from a
+  // send-side EAGAIN, emit it before pulling the next one — keeps
+  // display-order continuity even when libavcodec backpressures the
+  // input queue.
+  if (ctx->has_pending) {
+    av_frame_unref(f);
+    av_frame_move_ref(f, ctx->pending_frame);
+    ctx->has_pending = false;
+  } else {
+    int result = avcodec_receive_frame(ctx->codec_ctx, f);
+    if (result == AVERROR(EAGAIN) || result == AVERROR_EOF) {
+      return VIDEO_DECODER_READ_AGAIN;
+    }
+    if (result < 0) {
+      logError("avcodec_receive_frame", result);
+      return transformError(result);
+    }
+  }
+  // Only planar 4:2:0 YUV is supported by VideoDecoderOutputBuffer's
+  // 3-plane layout. iOS H.264 produces YUV420P (limited range) or
+  // YUVJ420P (full range); identical memory layout, only range
+  // interpretation differs.
+  AVPixelFormat pix = (AVPixelFormat)f->format;
+  if (pix != AV_PIX_FMT_YUV420P && pix != AV_PIX_FMT_YUVJ420P) {
+    LOGE("ffmpegVideoReceiveFrame: unsupported pix_fmt=%d", pix);
+    av_frame_unref(f);
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+
+  int width = f->width;
+  int height = f->height;
+  int yStride = f->linesize[0];
+  int uvStride = f->linesize[1];
+  int colorspace = colorspaceFromAVColorSpace(f->colorspace);
+  if (colorspace == COLORSPACE_UNKNOWN) {
+    // iOS H.264 commonly leaves VUI fields unspecified; default to
+    // BT.709 for HD-shaped frames, BT.601 below SD width threshold.
+    colorspace = (width >= 1280 || height >= 720) ? COLORSPACE_BT709
+                                                  : COLORSPACE_BT601;
+  }
+
+  jboolean ok = env->CallBooleanMethod(outputBuffer, initForYuvFrameMethod,
+                                       width, height, yStride, uvStride,
+                                       colorspace);
+  if (env->ExceptionCheck()) {
+    LOGE("initForYuvFrame threw");
+    env->ExceptionDescribe();
+    env->ExceptionClear();
+    av_frame_unref(f);
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+  if (!ok) {
+    LOGE("initForYuvFrame returned false (overflow?)");
+    av_frame_unref(f);
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+
+  // Display-order PTS recovered from libavcodec. The Java side
+  // initialised the buffer with the input packet's PTS; for B-frame
+  // streams that is the WRONG value because the frame we're about to
+  // emit was decoded out of input order. Overwriting with f->pts puts
+  // each output buffer back on the timeline ExoPlayer expects.
+  if (f->pts != AV_NOPTS_VALUE) {
+    env->SetLongField(outputBuffer, timeUsField, (jlong)f->pts);
+  }
+
+  // Copy each plane into the ByteBuffer that initForYuvFrame allocated.
+  jobject dataBuf = env->GetObjectField(outputBuffer, dataField);
+  if (!dataBuf) {
+    LOGE("ffmpegVideoReceiveFrame: data ByteBuffer is null after init");
+    av_frame_unref(f);
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+  uint8_t* dst = (uint8_t*)env->GetDirectBufferAddress(dataBuf);
+  if (!dst) {
+    LOGE("ffmpegVideoReceiveFrame: GetDirectBufferAddress null");
+    env->DeleteLocalRef(dataBuf);
+    av_frame_unref(f);
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+
+  int uvHeight = (height + 1) / 2;
+  int yLength = yStride * height;
+  int uvLength = uvStride * uvHeight;
+
+  // Plane 0: Y
+  memcpy(dst, f->data[0], yLength);
+  // Plane 1: U
+  memcpy(dst + yLength, f->data[1], uvLength);
+  // Plane 2: V
+  memcpy(dst + yLength + uvLength, f->data[2], uvLength);
+
+  // iOS yuvj420p / AVCOL_RANGE_JPEG => full-range YUV; the renderer's
+  // shader needs to skip the limited-range pre-scale on Y.
+  jlong rangeFlag = (pix == AV_PIX_FMT_YUVJ420P ||
+                     f->color_range == AVCOL_RANGE_JPEG)
+                        ? 1L
+                        : 0L;
+  env->SetLongField(outputBuffer, decoderPrivateField, rangeFlag);
+
+  env->DeleteLocalRef(dataBuf);
+  av_frame_unref(f);
+  return VIDEO_DECODER_SUCCESS;
+}
+
+// Signals libavcodec to flush its reorder buffer so the Java side can
+// pull the remaining frames out via successive ffmpegVideoReceiveFrame
+// calls. Used during end-of-stream drain: SimpleDecoder's EOS short-
+// circuit hides the EOS input from our decode() override, so without
+// this hook libavcodec's buffered tail (~16 frames for iOS H.264
+// High@3.1) would be lost on first play-through.
+VIDEO_DECODER_FUNC(jint, ffmpegVideoSignalEos, jlong handle) {
+  if (!handle) {
+    LOGE("ffmpegVideoSignalEos: null handle");
+    return VIDEO_DECODER_ERROR_OTHER;
+  }
+  UxFfmpegVideoContext* ctx = (UxFfmpegVideoContext*)handle;
+  int result = avcodec_send_packet(ctx->codec_ctx, nullptr);
+  if (result < 0 && result != AVERROR_EOF) {
+    logError("avcodec_send_packet(NULL)", result);
+    return transformError(result);
+  }
+  return VIDEO_DECODER_SUCCESS;
+}
+
+VIDEO_DECODER_FUNC(void, ffmpegVideoFlush, jlong handle) {
+  if (!handle) return;
+  UxFfmpegVideoContext* ctx = (UxFfmpegVideoContext*)handle;
+  if (ctx->has_pending) {
+    av_frame_unref(ctx->pending_frame);
+    ctx->has_pending = false;
+  }
+  avcodec_flush_buffers(ctx->codec_ctx);
+}
+
+VIDEO_DECODER_FUNC(void, ffmpegVideoRelease, jlong handle) {
+  if (!handle) return;
+  releaseContext((UxFfmpegVideoContext*)handle);
+}

android/src/main/AndroidManifest.xml

@@ -1,6 +1,9 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
   package="io.swipelab.ux">
 
+  <!-- NotificationsPlugin posts notifications on Android 13+. -->
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
   <application>
     <provider
       android:name="androidx.core.content.FileProvider"

android/src/main/java/io/swipelab/ux/video/ffmpeg/FfmpegDecoderException.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2026 swipelab.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.swipelab.ux.video.ffmpeg;
+
+import androidx.media3.common.util.UnstableApi;
+import androidx.media3.decoder.DecoderException;
+
+@UnstableApi
+public final class FfmpegDecoderException extends DecoderException {
+  public FfmpegDecoderException(String message) {
+    super(message);
+  }
+
+  public FfmpegDecoderException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

android/src/main/java/io/swipelab/ux/video/ffmpeg/FfmpegLibrary.java

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2026 swipelab.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.swipelab.ux.video.ffmpeg;
+
+import androidx.annotation.Nullable;
+import androidx.media3.common.MimeTypes;
+import androidx.media3.common.util.UnstableApi;
+
+/**
+ * Loads libffmpegJNI.so and answers capability queries against the
+ * statically-linked FFmpeg build. The current native build only enables
+ * the H.264 decoder; queries for other MIME types return false.
+ */
+@UnstableApi
+public final class FfmpegLibrary {
+
+  private static final Object lock = new Object();
+  private static boolean attempted;
+  private static boolean available;
+
+  private FfmpegLibrary() {}
+
+  public static boolean isAvailable() {
+    synchronized (lock) {
+      if (attempted) {
+        return available;
+      }
+      attempted = true;
+      try {
+        System.loadLibrary("ffmpegJNI");
+        available = true;
+      } catch (UnsatisfiedLinkError e) {
+        android.util.Log.w(
+            "UxFfmpeg",
+            "libffmpegJNI.so missing for this ABI; falling back to MediaCodec");
+        available = false;
+      }
+      return available;
+    }
+  }
+
+  public static String getVersion() {
+    return isAvailable() ? ffmpegGetVersion() : "";
+  }
+
+  public static int getInputBufferPaddingSize() {
+    return isAvailable() ? ffmpegGetInputBufferPaddingSize() : 0;
+  }
+
+  /** Whether the given MIME type maps to a decoder built into this libffmpegJNI.so. */
+  public static boolean supportsFormat(@Nullable String mimeType) {
+    if (mimeType == null || !isAvailable()) {
+      return false;
+    }
+    String codecName = getCodecName(mimeType);
+    if (codecName == null) {
+      return false;
+    }
+    return ffmpegHasDecoder(codecName);
+  }
+
+  /**
+   * FFmpeg decoder name for the given MIME type, or null if no mapping
+   * exists. Only video codecs are wired up; the JNI build excludes
+   * audio decoders entirely.
+   */
+  @Nullable
+  public static String getCodecName(String mimeType) {
+    switch (mimeType) {
+      case MimeTypes.VIDEO_H264:
+        return "h264";
+      default:
+        return null;
+    }
+  }
+
+  private static native String ffmpegGetVersion();
+
+  private static native int ffmpegGetInputBufferPaddingSize();
+
+  private static native boolean ffmpegHasDecoder(String codecName);
+}

android/src/main/java/io/swipelab/ux/video/ffmpeg/FfmpegOutputSurface.java

@@ -0,0 +1,426 @@
+/*
+ * Copyright 2026 swipelab.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.swipelab.ux.video.ffmpeg;
+
+import android.opengl.EGL14;
+import android.opengl.EGLConfig;
+import android.opengl.EGLContext;
+import android.opengl.EGLDisplay;
+import android.opengl.EGLSurface;
+import android.opengl.GLES20;
+import android.util.Log;
+import android.view.Surface;
+import androidx.media3.common.util.UnstableApi;
+import androidx.media3.decoder.VideoDecoderOutputBuffer;
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+import java.nio.FloatBuffer;
+
+/**
+ * EGL/GLES2 helper that converts a decoded YUV420P/YUVJ420P frame into
+ * an RGB image written to an Android {@link Surface}. Lives for the
+ * duration of one output Surface; the renderer creates a new one when
+ * the Surface changes and releases this on shutdown.
+ *
+ * <p>The fragment shader handles both limited-range BT.709
+ * (Android-recorded H.264) and full-range BT.709 (iOS yuvj420p). The
+ * decoder flags per-buffer range via
+ * {@link VideoDecoderOutputBuffer#decoderPrivate} (0 = limited,
+ * 1 = full).
+ */
+@UnstableApi
+final class FfmpegOutputSurface {
+
+  private static final String TAG = "UxFfmpegOutputSurface";
+
+  // Fullscreen quad: (x, y, u, v) per vertex in TRIANGLE_STRIP order
+  // (top-left, bottom-left, top-right, bottom-right). UVs encode the
+  // rotation that maps a coded-orientation YUV plane onto a
+  // display-orientation render target — for each 90° step the UV
+  // tuple shifts one vertex around the corner ring. Used by
+  // `pickQuad(rotation)` at configure time so the running shader
+  // doesn't need a per-frame rotation uniform.
+  private static final float[] QUAD_0 = {
+      -1f,  1f, 0f, 0f,
+      -1f, -1f, 0f, 1f,
+       1f,  1f, 1f, 0f,
+       1f, -1f, 1f, 1f,
+  };
+  private static final float[] QUAD_90 = {
+      -1f,  1f, 0f, 1f,
+      -1f, -1f, 1f, 1f,
+       1f,  1f, 0f, 0f,
+       1f, -1f, 1f, 0f,
+  };
+  private static final float[] QUAD_180 = {
+      -1f,  1f, 1f, 1f,
+      -1f, -1f, 1f, 0f,
+       1f,  1f, 0f, 1f,
+       1f, -1f, 0f, 0f,
+  };
+  private static final float[] QUAD_270 = {
+      -1f,  1f, 1f, 0f,
+      -1f, -1f, 0f, 0f,
+       1f,  1f, 1f, 1f,
+       1f, -1f, 0f, 1f,
+  };
+
+  private static float[] pickQuad(int rotation) {
+    switch (((rotation % 360) + 360) % 360) {
+      case 90:
+        return QUAD_90;
+      case 180:
+        return QUAD_180;
+      case 270:
+        return QUAD_270;
+      default:
+        return QUAD_0;
+    }
+  }
+
+  private static final String VERTEX_SHADER =
+      "attribute vec4 aPos;\n"
+      + "attribute vec2 aTex;\n"
+      + "varying vec2 vTex;\n"
+      + "void main() {\n"
+      + "  gl_Position = aPos;\n"
+      + "  vTex = aTex;\n"
+      + "}\n";
+
+  // BT.709 YUV->RGB. uFullRange selects between full-range (iOS
+  // yuvj420p) and limited-range conversion. uSampleScale rescales the
+  // horizontal texture coordinate to skip the right-side padding that
+  // FFmpeg's SIMD-aligned linesize introduces (yStride >= width).
+  // highp on the fragment so the limited-range pre-scale
+  // `(y - 16/255) * (255/219)` doesn't quantize through 10-bit-ish
+  // mediump precision and band dark gradients on older Mali / Adreno
+  // parts. highp on a fragment shader is universally supported on
+  // GLES2 implementations Android ships post-2014.
+  private static final String FRAGMENT_SHADER =
+      "precision highp float;\n"
+      + "varying vec2 vTex;\n"
+      + "uniform sampler2D uY;\n"
+      + "uniform sampler2D uU;\n"
+      + "uniform sampler2D uV;\n"
+      + "uniform float uSampleScale;\n"
+      + "uniform float uFullRange;\n"
+      + "void main() {\n"
+      + "  vec2 c = vec2(vTex.x * uSampleScale, vTex.y);\n"
+      + "  float y = texture2D(uY, c).r;\n"
+      + "  float u = texture2D(uU, c).r - 0.5;\n"
+      + "  float v = texture2D(uV, c).r - 0.5;\n"
+      + "  if (uFullRange < 0.5) {\n"
+      + "    y = (y - 16.0/255.0) * (255.0/219.0);\n"
+      + "    u *= 255.0/224.0;\n"
+      + "    v *= 255.0/224.0;\n"
+      + "  }\n"
+      + "  float r = y + 1.5748 * v;\n"
+      + "  float g = y - 0.1873 * u - 0.4681 * v;\n"
+      + "  float b = y + 1.8556 * u;\n"
+      + "  gl_FragColor = vec4(clamp(vec3(r, g, b), 0.0, 1.0), 1.0);\n"
+      + "}\n";
+
+  private EGLDisplay eglDisplay = EGL14.EGL_NO_DISPLAY;
+  private EGLContext eglContext = EGL14.EGL_NO_CONTEXT;
+  private EGLSurface eglSurface = EGL14.EGL_NO_SURFACE;
+  private EGLConfig eglConfig;
+
+  private int program;
+  private int aPosLoc;
+  private int aTexLoc;
+  private int uYLoc;
+  private int uULoc;
+  private int uVLoc;
+  private int uSampleScaleLoc;
+  private int uFullRangeLoc;
+
+  private final int[] textures = new int[3];
+  // Per-plane allocated dimensions; -1 forces a glTexImage2D on the
+  // next upload (initial frame or size change). Subsequent frames use
+  // glTexSubImage2D which only copies pixels and avoids the driver-
+  // side reallocation that glTexImage2D triggers.
+  private final int[] allocatedStride = { -1, -1, -1 };
+  private final int[] allocatedRows = { -1, -1, -1 };
+  private FloatBuffer quadBuffer;
+
+  // Width/height the EGL window surface was created for; taken from
+  // the first decoded frame, not eglQuerySurface (which can return
+  // stale 1×1 dimensions if the SurfaceTexture's defaultBufferSize
+  // wasn't set before window creation).
+  private int surfaceWidth;
+  private int surfaceHeight;
+  // Rotation (clockwise) the configure() call selected the quad UVs
+  // for. Used to detect mid-stream rotation changes and rebuild.
+  private int configuredRotation;
+
+  /**
+   * Binds this helper to the given surface and creates EGL context +
+   * GL resources sized for the supplied DISPLAY dimensions (i.e.
+   * already swapped for 90°/270° rotated streams). Caller must have
+   * already resized the underlying SurfaceTexture (via
+   * setDefaultBufferSize) so the EGL window surface picks up matching
+   * buffer dimensions on creation.
+   *
+   * @param rotation 0 / 90 / 180 / 270 — the clockwise rotation that
+   *     should be applied to the coded YUV to display correctly.
+   *     Selects which set of pre-rotated quad UVs the shader samples
+   *     with.
+   */
+  void configure(Surface surface, int width, int height, int rotation)
+      throws FfmpegDecoderException {
+    if (eglContext != EGL14.EGL_NO_CONTEXT && eglSurface != EGL14.EGL_NO_SURFACE) {
+      return;
+    }
+    surfaceWidth = width;
+    surfaceHeight = height;
+    this.configuredRotation = rotation;
+    eglDisplay = EGL14.eglGetDisplay(EGL14.EGL_DEFAULT_DISPLAY);
+    if (eglDisplay == EGL14.EGL_NO_DISPLAY) {
+      throw new FfmpegDecoderException("eglGetDisplay failed");
+    }
+    int[] version = new int[2];
+    if (!EGL14.eglInitialize(eglDisplay, version, 0, version, 1)) {
+      throw new FfmpegDecoderException("eglInitialize failed");
+    }
+
+    int[] cfgAttribs = {
+        EGL14.EGL_RED_SIZE, 8,
+        EGL14.EGL_GREEN_SIZE, 8,
+        EGL14.EGL_BLUE_SIZE, 8,
+        EGL14.EGL_ALPHA_SIZE, 8,
+        EGL14.EGL_RENDERABLE_TYPE, EGL14.EGL_OPENGL_ES2_BIT,
+        EGL14.EGL_SURFACE_TYPE, EGL14.EGL_WINDOW_BIT,
+        EGL14.EGL_NONE
+    };
+    EGLConfig[] cfgs = new EGLConfig[1];
+    int[] numCfgs = new int[1];
+    if (!EGL14.eglChooseConfig(eglDisplay, cfgAttribs, 0, cfgs, 0, 1, numCfgs, 0)
+        || numCfgs[0] < 1) {
+      throw new FfmpegDecoderException("eglChooseConfig failed");
+    }
+    eglConfig = cfgs[0];
+
+    int[] ctxAttribs = { EGL14.EGL_CONTEXT_CLIENT_VERSION, 2, EGL14.EGL_NONE };
+    eglContext =
+        EGL14.eglCreateContext(eglDisplay, eglConfig, EGL14.EGL_NO_CONTEXT, ctxAttribs, 0);
+    if (eglContext == EGL14.EGL_NO_CONTEXT) {
+      throw new FfmpegDecoderException("eglCreateContext failed");
+    }
+
+    int[] surfAttribs = { EGL14.EGL_NONE };
+    eglSurface =
+        EGL14.eglCreateWindowSurface(eglDisplay, eglConfig, surface, surfAttribs, 0);
+    if (eglSurface == EGL14.EGL_NO_SURFACE) {
+      throw new FfmpegDecoderException("eglCreateWindowSurface failed");
+    }
+
+    if (!EGL14.eglMakeCurrent(eglDisplay, eglSurface, eglSurface, eglContext)) {
+      throw new FfmpegDecoderException("eglMakeCurrent failed");
+    }
+
+    initGl();
+  }
+
+  private void initGl() throws FfmpegDecoderException {
+    int vs = compileShader(GLES20.GL_VERTEX_SHADER, VERTEX_SHADER);
+    int fs = compileShader(GLES20.GL_FRAGMENT_SHADER, FRAGMENT_SHADER);
+    program = GLES20.glCreateProgram();
+    GLES20.glAttachShader(program, vs);
+    GLES20.glAttachShader(program, fs);
+    GLES20.glLinkProgram(program);
+    int[] linked = new int[1];
+    GLES20.glGetProgramiv(program, GLES20.GL_LINK_STATUS, linked, 0);
+    if (linked[0] == 0) {
+      String log = GLES20.glGetProgramInfoLog(program);
+      throw new FfmpegDecoderException("Program link failed: " + log);
+    }
+    GLES20.glDeleteShader(vs);
+    GLES20.glDeleteShader(fs);
+
+    aPosLoc = GLES20.glGetAttribLocation(program, "aPos");
+    aTexLoc = GLES20.glGetAttribLocation(program, "aTex");
+    uYLoc = GLES20.glGetUniformLocation(program, "uY");
+    uULoc = GLES20.glGetUniformLocation(program, "uU");
+    uVLoc = GLES20.glGetUniformLocation(program, "uV");
+    uSampleScaleLoc = GLES20.glGetUniformLocation(program, "uSampleScale");
+    uFullRangeLoc = GLES20.glGetUniformLocation(program, "uFullRange");
+
+    GLES20.glGenTextures(3, textures, 0);
+    for (int i = 0; i < 3; i++) {
+      int t = textures[i];
+      // Y plane (i=0) is 1:1 sized to the EGL surface, so GL_NEAREST
+      // samples the exact texel value at each pixel center and
+      // preserves luma detail. Chroma planes (i=1,2) are 4:2:0
+      // subsampled — bilinear filtering reconstructs the smooth
+      // colour transitions the encoder expected.
+      int filter = i == 0 ? GLES20.GL_NEAREST : GLES20.GL_LINEAR;
+      GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, t);
+      GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MIN_FILTER, filter);
+      GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MAG_FILTER, filter);
+      GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_S,
+          GLES20.GL_CLAMP_TO_EDGE);
+      GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_T,
+          GLES20.GL_CLAMP_TO_EDGE);
+    }
+
+    float[] quad = pickQuad(configuredRotation);
+    quadBuffer =
+        ByteBuffer.allocateDirect(quad.length * 4)
+            .order(ByteOrder.nativeOrder())
+            .asFloatBuffer();
+    quadBuffer.put(quad).position(0);
+
+    GLES20.glPixelStorei(GLES20.GL_UNPACK_ALIGNMENT, 1);
+  }
+
+  private static int compileShader(int type, String src) throws FfmpegDecoderException {
+    int s = GLES20.glCreateShader(type);
+    GLES20.glShaderSource(s, src);
+    GLES20.glCompileShader(s);
+    int[] ok = new int[1];
+    GLES20.glGetShaderiv(s, GLES20.GL_COMPILE_STATUS, ok, 0);
+    if (ok[0] == 0) {
+      String log = GLES20.glGetShaderInfoLog(s);
+      GLES20.glDeleteShader(s);
+      throw new FfmpegDecoderException(
+          (type == GLES20.GL_VERTEX_SHADER ? "Vertex" : "Fragment")
+              + " shader compile failed: "
+              + log);
+    }
+    return s;
+  }
+
+  /**
+   * Uploads the YUV planes from {@code buffer} into GL textures and
+   * draws the conversion shader to the EGL window surface. Caller is
+   * responsible for calling {@code buffer.release()} afterwards.
+   *
+   * @param rotation rotation degrees from the source format. Must
+   *     match the value passed to {@link #configure} (used here only
+   *     to recover the CODED Y-plane dimensions — needed for the
+   *     stride-vs-width sample-scale calculation — from the buffer's
+   *     DISPLAY-orientation width/height).
+   */
+  void render(VideoDecoderOutputBuffer buffer, int rotation) throws FfmpegDecoderException {
+    if (eglContext == EGL14.EGL_NO_CONTEXT || eglSurface == EGL14.EGL_NO_SURFACE) {
+      throw new FfmpegDecoderException("render called before configure");
+    }
+    if (buffer.yuvPlanes == null || buffer.yuvStrides == null) {
+      throw new FfmpegDecoderException("output buffer has no YUV data");
+    }
+
+    EGL14.eglMakeCurrent(eglDisplay, eglSurface, eglSurface, eglContext);
+
+    int yStride = buffer.yuvStrides[0];
+    int uvStride = buffer.yuvStrides[1];
+    // For 90°/270° streams the renderer swapped buffer.width/height
+    // to display orientation so ExoPlayer's size notification was
+    // correct, but the YUV planes are still stored in coded
+    // orientation — undo the swap here so sampleScale = codedWidth /
+    // yStride lands on the correct value.
+    boolean rotated = rotation == 90 || rotation == 270;
+    int codedWidth = rotated ? buffer.height : buffer.width;
+    int codedHeight = rotated ? buffer.width : buffer.height;
+    int uvHeight = (codedHeight + 1) / 2;
+
+    GLES20.glViewport(0, 0, surfaceWidth, surfaceHeight);
+    GLES20.glClearColor(0f, 0f, 0f, 1f);
+    GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT);
+
+    GLES20.glUseProgram(program);
+
+    uploadPlane(0, textures[0], buffer.yuvPlanes[0], yStride, codedHeight);
+    uploadPlane(1, textures[1], buffer.yuvPlanes[1], uvStride, uvHeight);
+    uploadPlane(2, textures[2], buffer.yuvPlanes[2], uvStride, uvHeight);
+
+    GLES20.glUniform1i(uYLoc, 0);
+    GLES20.glUniform1i(uULoc, 1);
+    GLES20.glUniform1i(uVLoc, 2);
+    GLES20.glUniform1f(uSampleScaleLoc, yStride > 0 ? (float) codedWidth / yStride : 1f);
+    GLES20.glUniform1f(uFullRangeLoc, buffer.decoderPrivate == 1L ? 1f : 0f);
+
+    quadBuffer.position(0);
+    GLES20.glVertexAttribPointer(aPosLoc, 2, GLES20.GL_FLOAT, false, 16, quadBuffer);
+    quadBuffer.position(2);
+    GLES20.glVertexAttribPointer(aTexLoc, 2, GLES20.GL_FLOAT, false, 16, quadBuffer);
+    GLES20.glEnableVertexAttribArray(aPosLoc);
+    GLES20.glEnableVertexAttribArray(aTexLoc);
+
+    GLES20.glDrawArrays(GLES20.GL_TRIANGLE_STRIP, 0, 4);
+
+    GLES20.glDisableVertexAttribArray(aPosLoc);
+    GLES20.glDisableVertexAttribArray(aTexLoc);
+
+    if (!EGL14.eglSwapBuffers(eglDisplay, eglSurface)) {
+      Log.w(TAG, "eglSwapBuffers failed; client may have detached the surface");
+    }
+  }
+
+  private void uploadPlane(
+      int unit, int texture, ByteBuffer src, int stride, int rows) {
+    GLES20.glActiveTexture(GLES20.GL_TEXTURE0 + unit);
+    GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, texture);
+    src.position(0);
+    if (allocatedStride[unit] == stride && allocatedRows[unit] == rows) {
+      GLES20.glTexSubImage2D(
+          GLES20.GL_TEXTURE_2D,
+          0,
+          0, 0,
+          stride, rows,
+          GLES20.GL_LUMINANCE,
+          GLES20.GL_UNSIGNED_BYTE,
+          src);
+    } else {
+      GLES20.glTexImage2D(
+          GLES20.GL_TEXTURE_2D,
+          0,
+          GLES20.GL_LUMINANCE,
+          stride,
+          rows,
+          0,
+          GLES20.GL_LUMINANCE,
+          GLES20.GL_UNSIGNED_BYTE,
+          src);
+      allocatedStride[unit] = stride;
+      allocatedRows[unit] = rows;
+    }
+  }
+
+  void release() {
+    if (eglDisplay != EGL14.EGL_NO_DISPLAY) {
+      EGL14.eglMakeCurrent(eglDisplay, EGL14.EGL_NO_SURFACE, EGL14.EGL_NO_SURFACE,
+          EGL14.EGL_NO_CONTEXT);
+      if (textures[0] != 0) {
+        GLES20.glDeleteTextures(3, textures, 0);
+        textures[0] = textures[1] = textures[2] = 0;
+      }
+      if (program != 0) {
+        GLES20.glDeleteProgram(program);
+        program = 0;
+      }
+      if (eglSurface != EGL14.EGL_NO_SURFACE) {
+        EGL14.eglDestroySurface(eglDisplay, eglSurface);
+        eglSurface = EGL14.EGL_NO_SURFACE;
+      }
+      if (eglContext != EGL14.EGL_NO_CONTEXT) {
+        EGL14.eglDestroyContext(eglDisplay, eglContext);
+        eglContext = EGL14.EGL_NO_CONTEXT;
+      }
+      EGL14.eglReleaseThread();
+      // NB: do NOT eglTerminate(EGL_DEFAULT_DISPLAY) here — the
+      // display is shared with VideoCompositor's EGL context, and
+      // tearing it down would silently kill the other consumer's
+      // surface. eglDestroyContext + eglReleaseThread is sufficient
+      // to clean up our share.
+      eglDisplay = EGL14.EGL_NO_DISPLAY;
+    }
+    quadBuffer = null;
+  }
+}

android/src/main/java/io/swipelab/ux/video/ffmpeg/FfmpegSimpleDecoder.java

@@ -0,0 +1,376 @@
+/*
+ * Adapted from Media3's SimpleDecoder (Apache 2.0, Copyright 2016 The
+ * Android Open Source Project) under the LICENSE-2.0:
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Adds an end-of-stream drain hook. Media3's SimpleDecoder short-
+ * circuits the EOS input and never invokes the subclass decode(), so
+ * libavcodec's reorder buffer (up to ~16 frames for iOS H.264) is
+ * never drained — the last frames of a clip are lost on first
+ * play-through. This subclass extends the decode loop with a
+ * draining state: when EOS hits, signalEndOfInput() tells libavcodec
+ * to flush its reorder queue, then drainAtEndOfStream() is called on
+ * successive output buffers until it reports DRAIN_DONE, at which
+ * point the EOS flag is finally attached.
+ *
+ * Everything else mirrors SimpleDecoder verbatim. Keeping the
+ * mirror tight makes it cheap to adopt upstream improvements.
+ */
+package io.swipelab.ux.video.ffmpeg;
+
+import androidx.annotation.CallSuper;
+import androidx.annotation.Nullable;
+import androidx.media3.common.C;
+import androidx.media3.common.util.UnstableApi;
+import androidx.media3.decoder.Decoder;
+import androidx.media3.decoder.DecoderException;
+import androidx.media3.decoder.DecoderInputBuffer;
+import androidx.media3.decoder.DecoderOutputBuffer;
+import java.util.ArrayDeque;
+
+@UnstableApi
+abstract class FfmpegSimpleDecoder<
+        I extends DecoderInputBuffer, O extends DecoderOutputBuffer, E extends DecoderException>
+    implements Decoder<I, O, E> {
+
+  /** Subclass produced a frame into the supplied output buffer; keep calling. */
+  protected static final int DRAIN_PRODUCED_FRAME = 0;
+  /** Subclass has no more buffered frames; output buffer untouched, attach EOS. */
+  protected static final int DRAIN_DONE = 1;
+  /** Fatal drain error; output buffer untouched, abort the decoder. */
+  protected static final int DRAIN_ERROR = 2;
+
+  private final Thread decodeThread;
+  private final Object lock;
+  private final ArrayDeque<I> queuedInputBuffers;
+  private final ArrayDeque<O> queuedOutputBuffers;
+  private final I[] availableInputBuffers;
+  private final O[] availableOutputBuffers;
+
+  private int availableInputBufferCount;
+  private int availableOutputBufferCount;
+  @Nullable private I dequeuedInputBuffer;
+
+  @Nullable private E exception;
+  private boolean flushed;
+  private boolean released;
+  private int skippedOutputBufferCount;
+  private long outputStartTimeUs;
+  // True between receiving an EOS input and the drain hook returning
+  // DRAIN_DONE. During this window the decode loop fires whenever an
+  // output buffer is available, regardless of the input queue.
+  private boolean draining;
+
+  protected FfmpegSimpleDecoder(I[] inputBuffers, O[] outputBuffers) {
+    lock = new Object();
+    outputStartTimeUs = C.TIME_UNSET;
+    queuedInputBuffers = new ArrayDeque<>();
+    queuedOutputBuffers = new ArrayDeque<>();
+    availableInputBuffers = inputBuffers;
+    availableInputBufferCount = inputBuffers.length;
+    for (int i = 0; i < availableInputBufferCount; i++) {
+      availableInputBuffers[i] = createInputBuffer();
+    }
+    availableOutputBuffers = outputBuffers;
+    availableOutputBufferCount = outputBuffers.length;
+    for (int i = 0; i < availableOutputBufferCount; i++) {
+      availableOutputBuffers[i] = createOutputBuffer();
+    }
+    decodeThread =
+        new Thread("UxFfmpegSimpleDecoder") {
+          @Override
+          public void run() {
+            FfmpegSimpleDecoder.this.runLoop();
+          }
+        };
+    decodeThread.start();
+  }
+
+  protected final void setInitialInputBufferSize(int size) {
+    for (I inputBuffer : availableInputBuffers) {
+      inputBuffer.ensureSpaceForWrite(size);
+    }
+  }
+
+  protected final boolean isAtLeastOutputStartTimeUs(long timeUs) {
+    synchronized (lock) {
+      return outputStartTimeUs == C.TIME_UNSET || timeUs >= outputStartTimeUs;
+    }
+  }
+
+  @Override
+  public final void setOutputStartTimeUs(long outputStartTimeUs) {
+    synchronized (lock) {
+      this.outputStartTimeUs = outputStartTimeUs;
+    }
+  }
+
+  @Override
+  @Nullable
+  public final I dequeueInputBuffer() throws E {
+    synchronized (lock) {
+      maybeThrowException();
+      dequeuedInputBuffer =
+          availableInputBufferCount == 0
+              ? null
+              : availableInputBuffers[--availableInputBufferCount];
+      return dequeuedInputBuffer;
+    }
+  }
+
+  @Override
+  public final void queueInputBuffer(I inputBuffer) throws E {
+    synchronized (lock) {
+      maybeThrowException();
+      queuedInputBuffers.addLast(inputBuffer);
+      maybeNotifyDecodeLoop();
+      dequeuedInputBuffer = null;
+    }
+  }
+
+  @Override
+  @Nullable
+  public final O dequeueOutputBuffer() throws E {
+    synchronized (lock) {
+      maybeThrowException();
+      if (queuedOutputBuffers.isEmpty()) {
+        return null;
+      }
+      return queuedOutputBuffers.removeFirst();
+    }
+  }
+
+  @CallSuper
+  protected void releaseOutputBuffer(O outputBuffer) {
+    synchronized (lock) {
+      outputBuffer.clear();
+      availableOutputBuffers[availableOutputBufferCount++] = outputBuffer;
+      maybeNotifyDecodeLoop();
+    }
+  }
+
+  @Override
+  public final void flush() {
+    synchronized (lock) {
+      flushed = true;
+      draining = false;
+      skippedOutputBufferCount = 0;
+      if (dequeuedInputBuffer != null) {
+        releaseInputBufferInternal(dequeuedInputBuffer);
+        dequeuedInputBuffer = null;
+      }
+      while (!queuedInputBuffers.isEmpty()) {
+        releaseInputBufferInternal(queuedInputBuffers.removeFirst());
+      }
+      while (!queuedOutputBuffers.isEmpty()) {
+        queuedOutputBuffers.removeFirst().release();
+      }
+    }
+  }
+
+  @CallSuper
+  @Override
+  public void release() {
+    synchronized (lock) {
+      released = true;
+      lock.notify();
+    }
+    try {
+      decodeThread.join();
+    } catch (InterruptedException e) {
+      Thread.currentThread().interrupt();
+    }
+  }
+
+  private void maybeThrowException() throws E {
+    @Nullable E e = this.exception;
+    if (e != null) {
+      throw e;
+    }
+  }
+
+  private void maybeNotifyDecodeLoop() {
+    if (canDecodeBuffer()) {
+      lock.notify();
+    }
+  }
+
+  private void runLoop() {
+    try {
+      while (decodeOne()) {
+        // tight loop
+      }
+    } catch (InterruptedException e) {
+      throw new IllegalStateException(e);
+    }
+  }
+
+  private boolean decodeOne() throws InterruptedException {
+    @Nullable I inputBuffer;
+    O outputBuffer;
+    boolean resetDecoder;
+    boolean drainingLocal;
+
+    synchronized (lock) {
+      while (!released && !canDecodeBuffer()) {
+        lock.wait();
+      }
+      if (released) {
+        return false;
+      }
+      outputBuffer = availableOutputBuffers[--availableOutputBufferCount];
+      resetDecoder = flushed;
+      flushed = false;
+      drainingLocal = draining;
+      if (drainingLocal) {
+        inputBuffer = null;
+      } else {
+        inputBuffer = queuedInputBuffers.removeFirst();
+      }
+    }
+
+    @Nullable E iterationException = null;
+    boolean attachEosFlag = false;
+
+    if (drainingLocal) {
+      // Continuation of an EOS drain that started earlier.
+      int drainResult;
+      try {
+        drainResult = drainAtEndOfStream(outputBuffer);
+      } catch (RuntimeException e) {
+        drainResult = DRAIN_ERROR;
+        iterationException = createUnexpectedDecodeException(e);
+      } catch (OutOfMemoryError e) {
+        drainResult = DRAIN_ERROR;
+        iterationException = createUnexpectedDecodeException(e);
+      }
+      if (drainResult == DRAIN_DONE) {
+        attachEosFlag = true;
+        synchronized (lock) {
+          draining = false;
+        }
+      } else if (drainResult == DRAIN_ERROR && iterationException == null) {
+        iterationException = createUnexpectedDecodeException(
+            new IllegalStateException("EOS drain reported DRAIN_ERROR"));
+      }
+    } else if (inputBuffer.isEndOfStream()) {
+      // First time we see EOS — tell libavcodec to flush its reorder
+      // buffer, then drain one frame immediately into this output
+      // buffer. If no buffered frames remain we attach EOS now;
+      // otherwise the next loop iteration runs the draining branch.
+      try {
+        signalEndOfInput();
+      } catch (RuntimeException e) {
+        iterationException = createUnexpectedDecodeException(e);
+      }
+      int drainResult = DRAIN_DONE;
+      if (iterationException == null) {
+        try {
+          drainResult = drainAtEndOfStream(outputBuffer);
+        } catch (RuntimeException e) {
+          drainResult = DRAIN_ERROR;
+          iterationException = createUnexpectedDecodeException(e);
+        }
+      }
+      if (drainResult == DRAIN_PRODUCED_FRAME) {
+        synchronized (lock) {
+          draining = true;
+        }
+      } else if (drainResult == DRAIN_DONE) {
+        attachEosFlag = true;
+      } else if (iterationException == null) {
+        iterationException = createUnexpectedDecodeException(
+            new IllegalStateException("EOS drain reported DRAIN_ERROR"));
+      }
+    } else {
+      // Normal decode path — same shape as SimpleDecoder.
+      outputBuffer.timeUs = inputBuffer.timeUs;
+      if (inputBuffer.isFirstSample()) {
+        outputBuffer.addFlag(C.BUFFER_FLAG_FIRST_SAMPLE);
+      }
+      if (!isAtLeastOutputStartTimeUs(inputBuffer.timeUs)) {
+        outputBuffer.shouldBeSkipped = true;
+      }
+      try {
+        iterationException = decode(inputBuffer, outputBuffer, resetDecoder);
+      } catch (RuntimeException e) {
+        iterationException = createUnexpectedDecodeException(e);
+      } catch (OutOfMemoryError e) {
+        iterationException = createUnexpectedDecodeException(e);
+      }
+    }
+
+    if (iterationException != null) {
+      synchronized (lock) {
+        this.exception = iterationException;
+      }
+      return false;
+    }
+    if (attachEosFlag) {
+      outputBuffer.addFlag(C.BUFFER_FLAG_END_OF_STREAM);
+    }
+
+    synchronized (lock) {
+      if (flushed) {
+        outputBuffer.release();
+      } else if (outputBuffer.shouldBeSkipped) {
+        skippedOutputBufferCount++;
+        outputBuffer.release();
+      } else {
+        outputBuffer.skippedOutputBufferCount = skippedOutputBufferCount;
+        skippedOutputBufferCount = 0;
+        queuedOutputBuffers.addLast(outputBuffer);
+      }
+      if (inputBuffer != null) {
+        releaseInputBufferInternal(inputBuffer);
+      }
+    }
+    return true;
+  }
+
+  private boolean canDecodeBuffer() {
+    if (draining) {
+      return availableOutputBufferCount > 0;
+    }
+    return !queuedInputBuffers.isEmpty() && availableOutputBufferCount > 0;
+  }
+
+  private void releaseInputBufferInternal(I inputBuffer) {
+    inputBuffer.clear();
+    availableInputBuffers[availableInputBufferCount++] = inputBuffer;
+  }
+
+  protected abstract I createInputBuffer();
+
+  protected abstract O createOutputBuffer();
+
+  protected abstract E createUnexpectedDecodeException(Throwable error);
+
+  /**
+   * Decodes the {@code inputBuffer} and stores any decoded output in
+   * {@code outputBuffer}. Same contract as Media3's
+   * {@code SimpleDecoder.decode}.
+   */
+  @Nullable
+  protected abstract E decode(I inputBuffer, O outputBuffer, boolean reset);
+
+  /**
+   * Called once when an end-of-stream input buffer arrives, before
+   * the first call to {@link #drainAtEndOfStream}. Subclass should
+   * tell its backend decoder to flush its internal queue —
+   * {@code avcodec_send_packet(ctx, NULL)} for libavcodec.
+   */
+  protected abstract void signalEndOfInput();
+
+  /**
+   * Pulls one buffered frame from the backend decoder into the
+   * supplied output buffer. Called once per available output buffer
+   * after EOS until it reports {@link #DRAIN_DONE}; the decode loop
+   * then attaches {@code BUFFER_FLAG_END_OF_STREAM} to that same
+   * output buffer before queueing it.
+   *
+   * @return one of {@link #DRAIN_PRODUCED_FRAME}, {@link #DRAIN_DONE},
+   *     {@link #DRAIN_ERROR}.
+   */
+  protected abstract int drainAtEndOfStream(O outputBuffer);
+}

android/src/main/java/io/swipelab/ux/video/ffmpeg/FfmpegSurfaceSizer.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2026 swipelab.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.swipelab.ux.video.ffmpeg;
+
+import androidx.media3.common.util.UnstableApi;
+
+/**
+ * Resizes the SurfaceTexture backing the player's output Surface
+ * before the FFmpeg renderer's EGL window surface is created. Without
+ * this the SurfaceTexture's default buffer size is whatever
+ * implementation default Android picked (often 1×1) — the EGL surface
+ * inherits that, our quad renders into one pixel, and the compositor
+ * stretches it across the Flutter texture.
+ *
+ * <p>The compositor's player listener also calls
+ * setDefaultBufferSize, but only on the main thread after the player
+ * fires onVideoSizeChanged. By then the FFmpeg renderer has already
+ * created its EGL window surface on the player thread. Threading this
+ * hook through ensures resize-before-window-create.
+ */
+@UnstableApi
+public interface FfmpegSurfaceSizer {
+  void resize(int width, int height);
+}

android/src/main/java/io/swipelab/ux/video/ffmpeg/FfmpegVideoDecoder.java

@@ -0,0 +1,224 @@
+/*
+ * Copyright 2026 swipelab.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.swipelab.ux.video.ffmpeg;
+
+import androidx.annotation.Nullable;
+import androidx.media3.common.C;
+import androidx.media3.common.Format;
+import androidx.media3.common.util.UnstableApi;
+import androidx.media3.common.util.Util;
+import androidx.media3.decoder.DecoderInputBuffer;
+import androidx.media3.decoder.VideoDecoderOutputBuffer;
+import java.nio.ByteBuffer;
+import java.util.List;
+
+/**
+ * FFmpeg H.264 video decoder. Mirrors the Media3 audio pattern but
+ * targets {@link VideoDecoderOutputBuffer}. Two-step send/receive maps
+ * directly onto libavcodec's avcodec_send_packet / avcodec_receive_frame
+ * lifecycle so we can drain multiple reordered frames out of a single
+ * input packet.
+ *
+ * <h3>Known limits</h3>
+ * <ul>
+ *   <li><b>Colorspace heuristic.</b> When the bitstream's
+ *   {@code colorspace}/{@code primaries}/{@code transfer} are all
+ *   unspecified we fall back to a size-based guess (BT.709 for >=
+ *   720p, BT.601 below). iPhone 6/7-era 1080p clips that recorded
+ *   BT.601 with unspecified metadata get mislabelled — skin tones
+ *   are slightly oversaturated. Modern iOS sets {@code bt709}
+ *   explicitly so trusting the bitstream is correct for almost
+ *   everything in circulation today.</li>
+ * </ul>
+ */
+@UnstableApi
+public final class FfmpegVideoDecoder
+    extends FfmpegSimpleDecoder<
+        DecoderInputBuffer, VideoDecoderOutputBuffer, FfmpegDecoderException> {
+
+  // Mirrored from ffmpeg_jni.cc.
+  private static final int VIDEO_DECODER_SUCCESS = 0;
+  private static final int VIDEO_DECODER_ERROR_INVALID_DATA = -1;
+  private static final int VIDEO_DECODER_ERROR_OTHER = -2;
+  private static final int VIDEO_DECODER_READ_AGAIN = -3;
+
+  private final String codecName;
+  @Nullable private final byte[] extraData;
+  private final long nativeContext;
+  private volatile @C.VideoOutputMode int outputMode;
+
+  public FfmpegVideoDecoder(
+      Format format, int numInputBuffers, int numOutputBuffers, int initialInputBufferSize, int threads)
+      throws FfmpegDecoderException {
+    super(
+        new DecoderInputBuffer[numInputBuffers],
+        new VideoDecoderOutputBuffer[numOutputBuffers]);
+    if (!FfmpegLibrary.isAvailable()) {
+      throw new FfmpegDecoderException("Failed to load decoder native libraries.");
+    }
+    String mime = format.sampleMimeType;
+    if (mime == null) {
+      throw new FfmpegDecoderException("Format has null sampleMimeType.");
+    }
+    String name = FfmpegLibrary.getCodecName(mime);
+    if (name == null) {
+      throw new FfmpegDecoderException("No FFmpeg codec mapped for " + mime);
+    }
+    codecName = name;
+    extraData = flattenInitializationData(format.initializationData);
+    nativeContext = ffmpegVideoInitialize(codecName, extraData, threads);
+    if (nativeContext == 0) {
+      throw new FfmpegDecoderException("Initialization failed.");
+    }
+    setInitialInputBufferSize(initialInputBufferSize);
+  }
+
+  @Override
+  public String getName() {
+    return "ffmpeg" + FfmpegLibrary.getVersion() + "-" + codecName;
+  }
+
+  @Override
+  protected DecoderInputBuffer createInputBuffer() {
+    return new DecoderInputBuffer(
+        DecoderInputBuffer.BUFFER_REPLACEMENT_MODE_DIRECT,
+        FfmpegLibrary.getInputBufferPaddingSize());
+  }
+
+  @Override
+  protected VideoDecoderOutputBuffer createOutputBuffer() {
+    return new VideoDecoderOutputBuffer(this::releaseOutputBuffer);
+  }
+
+  @Override
+  protected FfmpegDecoderException createUnexpectedDecodeException(Throwable error) {
+    return new FfmpegDecoderException("Unexpected decode error", error);
+  }
+
+  @Override
+  @Nullable
+  protected FfmpegDecoderException decode(
+      DecoderInputBuffer inputBuffer, VideoDecoderOutputBuffer outputBuffer, boolean reset) {
+    if (reset) {
+      ffmpegVideoFlush(nativeContext);
+    }
+
+    ByteBuffer inputData = Util.castNonNull(inputBuffer.data);
+    int inputSize = inputData.limit();
+    int sendResult =
+        ffmpegVideoSendPacket(nativeContext, inputData, inputSize, inputBuffer.timeUs);
+    if (sendResult == VIDEO_DECODER_ERROR_INVALID_DATA) {
+      // Treat invalid bitstream as non-fatal — match MediaCodec behavior.
+      outputBuffer.shouldBeSkipped = true;
+      return null;
+    } else if (sendResult == VIDEO_DECODER_ERROR_OTHER) {
+      return new FfmpegDecoderException("avcodec_send_packet failed (see logcat).");
+    }
+    // sendResult is VIDEO_DECODER_SUCCESS or VIDEO_DECODER_READ_AGAIN.
+    // EAGAIN on send means the decoder needs to be drained first — but
+    // SimpleDecoder gives us one input + one output per decode() call,
+    // so on the next iteration we'll be called with a fresh output
+    // buffer and try receive again. Drop this input on EAGAIN.
+
+    // init seeds outputBuffer.timeUs from the input PTS; the native
+    // receive path overwrites it with the decoded frame's true
+    // display-order PTS (recovered from libavcodec) before returning
+    // success.
+    outputBuffer.init(inputBuffer.timeUs, outputMode, /* supplementalData= */ null);
+    outputBuffer.format = inputBuffer.format;
+    int receiveResult = ffmpegVideoReceiveFrame(nativeContext, outputBuffer);
+    if (receiveResult == VIDEO_DECODER_READ_AGAIN) {
+      // No frame ready yet (decoder still building reorder buffer).
+      // Skip this output buffer; subsequent send/receive cycles will
+      // drain frames once the pipeline fills.
+      outputBuffer.shouldBeSkipped = true;
+      return null;
+    } else if (receiveResult == VIDEO_DECODER_ERROR_INVALID_DATA) {
+      outputBuffer.shouldBeSkipped = true;
+      return null;
+    } else if (receiveResult == VIDEO_DECODER_ERROR_OTHER) {
+      return new FfmpegDecoderException("avcodec_receive_frame failed (see logcat).");
+    }
+    return null;
+  }
+
+  @Override
+  public void release() {
+    super.release();
+    ffmpegVideoRelease(nativeContext);
+  }
+
+  @Override
+  protected void signalEndOfInput() {
+    int result = ffmpegVideoSignalEos(nativeContext);
+    if (result != VIDEO_DECODER_SUCCESS) {
+      throw new RuntimeException("ffmpegVideoSignalEos failed: " + result);
+    }
+  }
+
+  @Override
+  protected int drainAtEndOfStream(VideoDecoderOutputBuffer outputBuffer) {
+    outputBuffer.init(0, outputMode, /* supplementalData= */ null);
+    int result = ffmpegVideoReceiveFrame(nativeContext, outputBuffer);
+    if (result == VIDEO_DECODER_SUCCESS) {
+      return DRAIN_PRODUCED_FRAME;
+    }
+    if (result == VIDEO_DECODER_READ_AGAIN) {
+      // libavcodec returned EAGAIN or EOF after the NULL packet —
+      // reorder buffer is empty, drain is complete.
+      return DRAIN_DONE;
+    }
+    return DRAIN_ERROR;
+  }
+
+  public void setOutputMode(@C.VideoOutputMode int outputMode) {
+    this.outputMode = outputMode;
+  }
+
+  /**
+   * Coalesces the codec-specific data into one contiguous byte array
+   * for FFmpeg's extradata pointer. For AVC the MP4 extractor delivers
+   * a single avcC blob in slot 0; some demuxers split SPS/PPS into
+   * separate NAL units (Annex B). In both cases libavcodec auto-detects
+   * the layout from the first byte.
+   */
+  @Nullable
+  private static byte[] flattenInitializationData(List<byte[]> initializationData) {
+    if (initializationData == null || initializationData.isEmpty()) {
+      return null;
+    }
+    if (initializationData.size() == 1) {
+      return initializationData.get(0);
+    }
+    int total = 0;
+    for (byte[] part : initializationData) total += part.length;
+    byte[] out = new byte[total];
+    int off = 0;
+    for (byte[] part : initializationData) {
+      System.arraycopy(part, 0, out, off, part.length);
+      off += part.length;
+    }
+    return out;
+  }
+
+  private native long ffmpegVideoInitialize(
+      String codecName, @Nullable byte[] extraData, int threads);
+
+  private native int ffmpegVideoSendPacket(
+      long context, ByteBuffer inputData, int inputSize, long ptsUs);
+
+  private native int ffmpegVideoReceiveFrame(long context, VideoDecoderOutputBuffer outputBuffer);
+
+  private native int ffmpegVideoSignalEos(long context);
+
+  private native void ffmpegVideoFlush(long context);
+
+  private native void ffmpegVideoRelease(long context);
+}

android/src/main/java/io/swipelab/ux/video/ffmpeg/FfmpegVideoRenderer.java

@@ -0,0 +1,259 @@
+/*
+ * Copyright 2026 swipelab.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.swipelab.ux.video.ffmpeg;
+
+import static androidx.media3.exoplayer.DecoderReuseEvaluation.DISCARD_REASON_MIME_TYPE_CHANGED;
+import static androidx.media3.exoplayer.DecoderReuseEvaluation.REUSE_RESULT_NO;
+import static androidx.media3.exoplayer.DecoderReuseEvaluation.REUSE_RESULT_YES_WITHOUT_RECONFIGURATION;
+
+import android.os.Handler;
+import android.view.Surface;
+import androidx.annotation.Nullable;
+import androidx.media3.common.C;
+import androidx.media3.common.Format;
+import androidx.media3.common.MimeTypes;
+import androidx.media3.common.util.TraceUtil;
+import androidx.media3.common.util.UnstableApi;
+import androidx.media3.decoder.CryptoConfig;
+import androidx.media3.decoder.DecoderException;
+import androidx.media3.decoder.VideoDecoderOutputBuffer;
+import androidx.media3.exoplayer.DecoderReuseEvaluation;
+import androidx.media3.exoplayer.RendererCapabilities;
+import androidx.media3.exoplayer.video.DecoderVideoRenderer;
+import androidx.media3.exoplayer.video.VideoRendererEventListener;
+import java.util.Objects;
+
+/**
+ * ExoPlayer renderer that decodes video with our vendored FFmpeg
+ * extension and converts the YUV frame to RGB via a GLES2 shader before
+ * presenting on the output Surface. Slotted ahead of
+ * MediaCodecVideoRenderer via EXTENSION_RENDERER_MODE_PREFER so files
+ * that exceed platform decoder caps (deep DPB, iOS yuvj420p) work on
+ * devices where Media3's hardware path fails.
+ */
+@UnstableApi
+public final class FfmpegVideoRenderer extends DecoderVideoRenderer {
+
+  private static final String TAG = "FfmpegVideoRenderer";
+  private static final int DEFAULT_NUM_INPUT_BUFFERS = 4;
+  // iOS H.264 records with max_num_reorder_frames up to 16, and our
+  // shouldBeSkipped-on-EAGAIN path consumes one output buffer per
+  // input until the DPB fills. With 8 buffers the pipeline ran out
+  // before steady state and the renderer dropped frames waiting on
+  // free output buffers; 16 covers the worst iOS reorder shape.
+  private static final int DEFAULT_NUM_OUTPUT_BUFFERS = 16;
+  // 480x848 baseline; the decoder grows the buffer if a packet exceeds.
+  private static final int DEFAULT_INPUT_BUFFER_SIZE = 256 * 1024;
+
+  private final int threads;
+  private final int numInputBuffers;
+  private final int numOutputBuffers;
+  private final FfmpegSurfaceSizer surfaceSizer;
+
+  @Nullable private FfmpegVideoDecoder decoder;
+  @Nullable private FfmpegOutputSurface outputSurface;
+  @Nullable private Surface currentSurface;
+  private int surfaceWidth = -1;
+  private int surfaceHeight = -1;
+  private int surfaceRotation = 0;
+  private @C.VideoOutputMode int currentOutputMode = C.VIDEO_OUTPUT_MODE_NONE;
+
+  public FfmpegVideoRenderer(
+      long allowedJoiningTimeMs,
+      @Nullable Handler eventHandler,
+      @Nullable VideoRendererEventListener eventListener,
+      int maxDroppedFramesToNotify,
+      FfmpegSurfaceSizer surfaceSizer) {
+    this(
+        allowedJoiningTimeMs,
+        eventHandler,
+        eventListener,
+        maxDroppedFramesToNotify,
+        surfaceSizer,
+        /* threads= */ 0,
+        DEFAULT_NUM_INPUT_BUFFERS,
+        DEFAULT_NUM_OUTPUT_BUFFERS);
+  }
+
+  public FfmpegVideoRenderer(
+      long allowedJoiningTimeMs,
+      @Nullable Handler eventHandler,
+      @Nullable VideoRendererEventListener eventListener,
+      int maxDroppedFramesToNotify,
+      FfmpegSurfaceSizer surfaceSizer,
+      int threads,
+      int numInputBuffers,
+      int numOutputBuffers) {
+    super(allowedJoiningTimeMs, eventHandler, eventListener, maxDroppedFramesToNotify);
+    this.threads = threads;
+    this.numInputBuffers = numInputBuffers;
+    this.numOutputBuffers = numOutputBuffers;
+    this.surfaceSizer = surfaceSizer;
+  }
+
+  @Override
+  public String getName() {
+    return TAG;
+  }
+
+  @Override
+  public @Capabilities int supportsFormat(Format format) {
+    String mime = format.sampleMimeType;
+    if (!FfmpegLibrary.isAvailable() || mime == null || !MimeTypes.isVideo(mime)) {
+      return RendererCapabilities.create(C.FORMAT_UNSUPPORTED_TYPE);
+    }
+    if (!FfmpegLibrary.supportsFormat(mime)) {
+      return RendererCapabilities.create(C.FORMAT_UNSUPPORTED_SUBTYPE);
+    }
+    if (!supports8BitH264Profile(format.codecs)) {
+      // The YUV path only handles planar 4:2:0 8-bit (yuv420p /
+      // yuvj420p). High 10 / High 4:2:2 / High 4:4:4 / Main 10
+      // streams initialise libavcodec cleanly and only fail at the
+      // first receive — by then ExoPlayer has committed to this
+      // renderer and can't fall back. Reject upfront so the platform
+      // MediaCodec path (which often handles these via hardware) gets
+      // selected instead.
+      return RendererCapabilities.create(C.FORMAT_UNSUPPORTED_SUBTYPE);
+    }
+    if (format.cryptoType != C.CRYPTO_TYPE_NONE) {
+      return RendererCapabilities.create(C.FORMAT_UNSUPPORTED_DRM);
+    }
+    return RendererCapabilities.create(
+        C.FORMAT_HANDLED, ADAPTIVE_SEAMLESS, TUNNELING_NOT_SUPPORTED);
+  }
+
+  /**
+   * Parses the H.264 profile from an avc1 codec string (e.g.
+   * {@code avc1.640028}). Accepts the 8-bit YUV 4:2:0 profiles —
+   * Baseline (0x42), Main (0x4D), Extended (0x58), High (0x64) —
+   * and rejects everything else. When the codec string is missing or
+   * malformed we permit it: the worst case is a hard fail at decode
+   * time, which is no worse than today's behaviour.
+   */
+  private static boolean supports8BitH264Profile(@Nullable String codecs) {
+    if (codecs == null) return true;
+    String lower = codecs.toLowerCase();
+    if (!lower.startsWith("avc1.") || lower.length() < 11) return true;
+    try {
+      int profile = Integer.parseInt(lower.substring(5, 7), 16);
+      return profile == 0x42 || profile == 0x4D || profile == 0x58 || profile == 0x64;
+    } catch (NumberFormatException e) {
+      return true;
+    }
+  }
+
+  @Override
+  protected FfmpegVideoDecoder createDecoder(Format format, @Nullable CryptoConfig cryptoConfig)
+      throws FfmpegDecoderException {
+    TraceUtil.beginSection("createFfmpegVideoDecoder");
+    int initialInputBufferSize =
+        format.maxInputSize != Format.NO_VALUE ? format.maxInputSize : DEFAULT_INPUT_BUFFER_SIZE;
+    FfmpegVideoDecoder d =
+        new FfmpegVideoDecoder(
+            format, numInputBuffers, numOutputBuffers, initialInputBufferSize, threads);
+    decoder = d;
+    TraceUtil.endSection();
+    return d;
+  }
+
+  /// Pre-swap buffer dims for 90°/270° rotated streams so the
+  /// {@code maybeNotifyVideoSizeChanged} call inside the base
+  /// renderOutputBuffer reports DISPLAY-orientation dimensions
+  /// (matching what MediaCodecVideoRenderer does for the hardware
+  /// path). Without this swap, portrait iOS videos report their
+  /// coded landscape size and the downstream compositor lays out the
+  /// Flutter texture rotated. The swap is bounded to SURFACE_YUV
+  /// output mode because YUV-mode consumers
+  /// ({@code VideoDecoderOutputBufferRenderer.setOutputBuffer}) read
+  /// {@code buffer.width}/{@code height} expecting CODED dimensions
+  /// that match {@code yuvStrides[0]} — swapping there would walk
+  /// the chroma planes off the end of the allocation.
+  @Override
+  protected void renderOutputBuffer(
+      VideoDecoderOutputBuffer outputBuffer, long presentationTimeUs, Format outputFormat)
+      throws DecoderException {
+    if (currentOutputMode == C.VIDEO_OUTPUT_MODE_SURFACE_YUV
+        && outputFormat != null
+        && (outputFormat.rotationDegrees == 90 || outputFormat.rotationDegrees == 270)
+        && outputBuffer.width != outputBuffer.height) {
+      int tmp = outputBuffer.width;
+      outputBuffer.width = outputBuffer.height;
+      outputBuffer.height = tmp;
+    }
+    super.renderOutputBuffer(outputBuffer, presentationTimeUs, outputFormat);
+  }
+
+  @Override
+  protected void renderOutputBufferToSurface(
+      VideoDecoderOutputBuffer outputBuffer, Surface surface) throws FfmpegDecoderException {
+    int rotation = outputBuffer.format != null ? outputBuffer.format.rotationDegrees : 0;
+    if (outputSurface == null
+        || currentSurface != surface
+        || surfaceWidth != outputBuffer.width
+        || surfaceHeight != outputBuffer.height
+        || surfaceRotation != rotation) {
+      releaseOutputSurface();
+      // Resize the SurfaceTexture before creating the EGL window
+      // surface — the EGL surface inherits the SurfaceTexture's buffer
+      // dimensions at creation and won't auto-resize later.
+      surfaceSizer.resize(outputBuffer.width, outputBuffer.height);
+      outputSurface = new FfmpegOutputSurface();
+      outputSurface.configure(surface, outputBuffer.width, outputBuffer.height, rotation);
+      currentSurface = surface;
+      surfaceWidth = outputBuffer.width;
+      surfaceHeight = outputBuffer.height;
+      surfaceRotation = rotation;
+    }
+    try {
+      outputSurface.render(outputBuffer, rotation);
+    } finally {
+      outputBuffer.release();
+    }
+  }
+
+  @Override
+  protected void setDecoderOutputMode(@C.VideoOutputMode int outputMode) {
+    currentOutputMode = outputMode;
+    if (decoder != null) {
+      decoder.setOutputMode(outputMode);
+    }
+  }
+
+  @Override
+  protected DecoderReuseEvaluation canReuseDecoder(
+      String decoderName, Format oldFormat, Format newFormat) {
+    boolean sameMime = Objects.equals(oldFormat.sampleMimeType, newFormat.sampleMimeType);
+    return new DecoderReuseEvaluation(
+        decoderName,
+        oldFormat,
+        newFormat,
+        sameMime ? REUSE_RESULT_YES_WITHOUT_RECONFIGURATION : REUSE_RESULT_NO,
+        sameMime ? 0 : DISCARD_REASON_MIME_TYPE_CHANGED);
+  }
+
+  @Override
+  protected void onDisabled() {
+    releaseOutputSurface();
+    decoder = null;
+    currentOutputMode = C.VIDEO_OUTPUT_MODE_NONE;
+    super.onDisabled();
+  }
+
+  private void releaseOutputSurface() {
+    if (outputSurface != null) {
+      outputSurface.release();
+      outputSurface = null;
+    }
+    currentSurface = null;
+    surfaceWidth = -1;
+    surfaceHeight = -1;
+    surfaceRotation = 0;
+  }
+}

android/src/main/kotlin/io/swipelab/ux/KeyboardPlugin.kt

@@ -151,13 +151,25 @@ class KeyboardPlugin : NativePlugin, MethodChannel.MethodCallHandler {
     private fun publishImeHeight(view: android.view.View, insets: WindowInsets) {
         val density = view.resources.displayMetrics.density
         val imePx: Int = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            // TODO: on devices where a fixed nav bar stacks below the IME
+            // (e.g. HarmonyOS R+ with 3-button nav), Type.ime().bottom may
+            // exclude the nav-bar strip — same shape as the pre-R bug below.
+            // Verify when an R+ Huawei device is available; if confirmed,
+            // add Type.navigationBars() when the IME is visible.
             insets.getInsets(WindowInsets.Type.ime()).bottom
         } else {
-            // systemWindowInsetBottom = nav bar + IME; stableInsetBottom = nav
-            // bar only (stable insets exclude things that animate in/out like
-            // the IME). The difference isolates IME height.
+            // Report the total bottom-occluded area when the IME is open, so
+            // callers can max(keyboard.height, viewPadding.bottom) without
+            // adding the safe-area inset separately — matching iOS, where the
+            // reported keyboard frame already covers the home-indicator strip.
+            //
+            // systemWindowInsetBottom = nav bar + IME (when open) or just nav bar
+            // stableInsetBottom       = nav bar (stable, doesn't animate in/out)
             @Suppress("DEPRECATION")
-            (insets.systemWindowInsetBottom - insets.stableInsetBottom).coerceAtLeast(0)
+            val systemBottom = insets.systemWindowInsetBottom
+            @Suppress("DEPRECATION")
+            val stableBottom = insets.stableInsetBottom
+            if (systemBottom > stableBottom) systemBottom else 0
         }
         val height = imePx.toDouble() / density
 

android/src/main/kotlin/io/swipelab/ux/NotificationsPlugin.kt

@@ -0,0 +1,323 @@
+package io.swipelab.ux
+
+import android.Manifest
+import android.app.Activity
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import androidx.core.app.ActivityCompat
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.content.ContextCompat
+import io.flutter.embedding.engine.plugins.FlutterPlugin
+import io.flutter.embedding.engine.plugins.activity.ActivityPluginBinding
+import io.flutter.plugin.common.EventChannel
+import io.flutter.plugin.common.MethodCall
+import io.flutter.plugin.common.MethodChannel
+import io.flutter.plugin.common.PluginRegistry
+
+/// `ux/notifications` + `ux/notifications/events`. Domain-agnostic OS
+/// notification surface — show / cancel via the method channel, tap +
+/// authorization changes via the event channel. The Apple counterpart is
+/// `NotificationsPlugin.swift` (macOS only). App foreground/background state
+/// lives in `WindowPlugin`, not here.
+class NotificationsPlugin :
+    NativePlugin,
+    MethodChannel.MethodCallHandler,
+    EventChannel.StreamHandler {
+    companion object {
+        private const val CHANNEL_ID = "messages"
+        private const val CHANNEL_NAME = "Messages"
+        private const val PERMISSION_REQUEST_CODE = 0xC3A0
+
+        /// Host app points this at a white-silhouette status drawable
+        /// (a coloured launcher icon renders as a white square). Falls
+        /// back to the launcher icon when absent.
+        private const val ICON_META = "io.swipelab.ux.notification_icon"
+
+        /// Tap payload is carried back on the launch intent: a boolean
+        /// marker plus one string extra per `data` entry, namespaced so it
+        /// can't collide with the host app's own extras.
+        private const val EXTRA_MARKER = "io.swipelab.ux.notif"
+        private const val EXTRA_PREFIX = "io.swipelab.ux.notif."
+    }
+
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    private var context: Context? = null
+    private var methodChannel: MethodChannel? = null
+    private var eventChannel: EventChannel? = null
+    private var eventSink: EventChannel.EventSink? = null
+
+    private var activity: Activity? = null
+    private var activityBinding: ActivityPluginBinding? = null
+    private var pendingPermissionResult: MethodChannel.Result? = null
+
+    /// A tap that cold-started the process arrives before Dart subscribes.
+    /// Hold it until [onListen] gives us a sink, else the launch tap is lost.
+    private var pendingTap: Map<String, String>? = null
+
+    private val permissionListener =
+        PluginRegistry.RequestPermissionsResultListener { code, _, results ->
+            if (code != PERMISSION_REQUEST_CODE) {
+                false
+            } else {
+                val granted = results.isNotEmpty() &&
+                    results[0] == PackageManager.PERMISSION_GRANTED
+                pendingPermissionResult?.success(granted)
+                pendingPermissionResult = null
+                emitAuthorization(granted)
+                true
+            }
+        }
+
+    private val newIntentListener = PluginRegistry.NewIntentListener { intent ->
+        handleTapIntent(intent)
+        false
+    }
+
+    // MARK: - Engine lifecycle
+
+    override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {
+        context = binding.applicationContext
+
+        val mc = MethodChannel(binding.binaryMessenger, "ux/notifications")
+        mc.setMethodCallHandler(this)
+        methodChannel = mc
+
+        val ec = EventChannel(binding.binaryMessenger, "ux/notifications/events")
+        ec.setStreamHandler(this)
+        eventChannel = ec
+    }
+
+    override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {
+        methodChannel?.setMethodCallHandler(null)
+        methodChannel = null
+        eventChannel?.setStreamHandler(null)
+        eventChannel = null
+        eventSink = null
+        context = null
+    }
+
+    // MARK: - Activity lifecycle
+
+    override fun onAttachedToActivity(binding: ActivityPluginBinding) {
+        activity = binding.activity
+        activityBinding = binding
+        binding.addRequestPermissionsResultListener(permissionListener)
+        binding.addOnNewIntentListener(newIntentListener)
+        // The activity may have been launched by a notification tap.
+        handleTapIntent(binding.activity.intent)
+    }
+
+    override fun onDetachedFromActivity() {
+        activityBinding?.removeRequestPermissionsResultListener(permissionListener)
+        activityBinding?.removeOnNewIntentListener(newIntentListener)
+        activity = null
+        activityBinding = null
+        pendingPermissionResult?.success(false)
+        pendingPermissionResult = null
+    }
+
+    // MARK: - EventChannel
+
+    override fun onListen(arguments: Any?, events: EventChannel.EventSink?) {
+        eventSink = events
+        val tap = pendingTap
+        if (tap != null) {
+            pendingTap = null
+            events?.success(mapOf("type" to "tap", "data" to tap))
+        }
+    }
+
+    override fun onCancel(arguments: Any?) {
+        eventSink = null
+    }
+
+    // MARK: - MethodChannel
+
+    override fun onMethodCall(call: MethodCall, result: MethodChannel.Result) {
+        when (call.method) {
+            "requestPermission" -> handleRequestPermission(result)
+            "show" -> handleShow(call, result)
+            "cancelByThread" -> handleCancelByThread(call, result)
+            "cancelAll" -> handleCancelAll(result)
+            else -> result.notImplemented()
+        }
+    }
+
+    private fun handleRequestPermission(result: MethodChannel.Result) {
+        val ctx = context
+            ?: return result.error("no_context", "engine detached", null)
+        // Below 13 there is no runtime permission — notifications are on
+        // unless the user disabled them in system settings.
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+            val enabled = NotificationManagerCompat.from(ctx).areNotificationsEnabled()
+            emitAuthorization(enabled)
+            return result.success(enabled)
+        }
+        val act = activity
+            ?: return result.error("no_activity", "plugin not attached to an activity", null)
+        val granted = ContextCompat.checkSelfPermission(
+            act, Manifest.permission.POST_NOTIFICATIONS,
+        ) == PackageManager.PERMISSION_GRANTED
+        if (granted) {
+            emitAuthorization(true)
+            return result.success(true)
+        }
+        if (pendingPermissionResult != null) {
+            return result.error("in_progress", "another permission request is in flight", null)
+        }
+        pendingPermissionResult = result
+        ActivityCompat.requestPermissions(
+            act,
+            arrayOf(Manifest.permission.POST_NOTIFICATIONS),
+            PERMISSION_REQUEST_CODE,
+        )
+    }
+
+    private fun handleShow(call: MethodCall, result: MethodChannel.Result) {
+        val ctx = context
+            ?: return result.error("no_context", "engine detached", null)
+        val id = call.argument<String>("id")
+        val title = call.argument<String>("title")
+        val body = call.argument<String>("body")
+        if (id == null || title == null || body == null) {
+            return result.error("bad_args", "show expects id/title/body", null)
+        }
+        val threadId = call.argument<String>("threadId")
+        val data = call.argument<Map<String, Any?>>("data")
+            ?.mapValues { it.value?.toString() ?: "" } ?: emptyMap()
+
+        if (!NotificationManagerCompat.from(ctx).areNotificationsEnabled()) {
+            emitAuthorization(false)
+            return result.success(null)
+        }
+        post(ctx, id, title, body, threadId, data)
+        result.success(null)
+    }
+
+    private fun post(
+        ctx: Context,
+        id: String,
+        title: String,
+        body: String,
+        threadId: String?,
+        data: Map<String, String>,
+    ) {
+        ensureChannel(ctx)
+
+        val flags = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        } else {
+            PendingIntent.FLAG_UPDATE_CURRENT
+        }
+        val pending = PendingIntent.getActivity(
+            ctx, id.hashCode(), buildLaunchIntent(ctx, data), flags,
+        )
+
+        val builder = NotificationCompat.Builder(ctx, CHANNEL_ID)
+            .setSmallIcon(smallIcon(ctx))
+            .setContentTitle(title)
+            .setContentText(body)
+            .setPriority(NotificationCompat.PRIORITY_HIGH)
+            .setAutoCancel(true)
+            .setContentIntent(pending)
+        if (threadId != null) builder.setGroup(threadId)
+
+        // Same (tag, id) replaces — `id` is stable per message, so a fresh
+        // preview supersedes the older toast. areNotificationsEnabled() was
+        // checked by the caller, so POST_NOTIFICATIONS is satisfied.
+        NotificationManagerCompat.from(ctx).notify(id, 0, builder.build())
+    }
+
+    private fun handleCancelByThread(call: MethodCall, result: MethodChannel.Result) {
+        val ctx = context
+            ?: return result.error("no_context", "engine detached", null)
+        val threadId = call.argument<String>("threadId")
+            ?: return result.error("bad_args", "cancelByThread expects threadId", null)
+        // getActiveNotifications (used to recover the group key per notification)
+        // is API 23+; below that there is no way to enumerate, so it's a no-op.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+            val mgr = ctx.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+            for (sbn in mgr.activeNotifications) {
+                if (sbn.notification.group == threadId) {
+                    val tag = sbn.tag
+                    if (tag != null) mgr.cancel(tag, sbn.id) else mgr.cancel(sbn.id)
+                }
+            }
+        }
+        result.success(null)
+    }
+
+    private fun handleCancelAll(result: MethodChannel.Result) {
+        val ctx = context
+            ?: return result.error("no_context", "engine detached", null)
+        NotificationManagerCompat.from(ctx).cancelAll()
+        result.success(null)
+    }
+
+    // MARK: - Tap routing
+
+    private fun handleTapIntent(intent: Intent?) {
+        val i = intent ?: return
+        if (!i.getBooleanExtra(EXTRA_MARKER, false)) return
+        val extras = i.extras ?: return
+        val data = HashMap<String, String>()
+        for (key in extras.keySet()) {
+            if (key.startsWith(EXTRA_PREFIX)) {
+                data[key.removePrefix(EXTRA_PREFIX)] = extras.getString(key) ?: ""
+            }
+        }
+        emitTap(data)
+    }
+
+    private fun buildLaunchIntent(ctx: Context, data: Map<String, String>): Intent {
+        val launch = ctx.packageManager.getLaunchIntentForPackage(ctx.packageName)
+            ?: Intent(Intent.ACTION_MAIN)
+        launch.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP)
+        launch.putExtra(EXTRA_MARKER, true)
+        for ((k, v) in data) launch.putExtra(EXTRA_PREFIX + k, v)
+        return launch
+    }
+
+    // MARK: - Helpers
+
+    private fun ensureChannel(ctx: Context) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+        val mgr = ctx.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        if (mgr.getNotificationChannel(CHANNEL_ID) != null) return
+        mgr.createNotificationChannel(
+            NotificationChannel(CHANNEL_ID, CHANNEL_NAME, NotificationManager.IMPORTANCE_HIGH),
+        )
+    }
+
+    private fun smallIcon(ctx: Context): Int {
+        val ai = ctx.packageManager.getApplicationInfo(
+            ctx.packageName, PackageManager.GET_META_DATA,
+        )
+        val meta = ai.metaData?.getInt(ICON_META, 0) ?: 0
+        return if (meta != 0) meta else ai.icon
+    }
+
+    private fun emitTap(data: Map<String, String>) {
+        val sink = eventSink
+        if (sink == null) {
+            pendingTap = data
+            return
+        }
+        mainHandler.post { sink.success(mapOf("type" to "tap", "data" to data)) }
+    }
+
+    private fun emitAuthorization(granted: Boolean) {
+        mainHandler.post {
+            eventSink?.success(mapOf("type" to "authorization", "granted" to granted))
+        }
+    }
+}

android/src/main/kotlin/io/swipelab/ux/WindowPlugin.kt

@@ -0,0 +1,57 @@
+package io.swipelab.ux
+
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleEventObserver
+import androidx.lifecycle.ProcessLifecycleOwner
+import io.flutter.embedding.engine.plugins.FlutterPlugin
+import io.flutter.plugin.common.EventChannel
+
+/// `ux/window/events`. Reports app foreground / background as host-focus
+/// state — emits {"type":"focus","focused":Bool} on `ProcessLifecycleOwner`
+/// ON_START / ON_STOP. The Apple counterpart is `WindowPlugin.swift`
+/// (NSApplication active/resign); together they back Dart's `XWindow`.
+class WindowPlugin : NativePlugin, EventChannel.StreamHandler {
+    private var eventChannel: EventChannel? = null
+    private var eventSink: EventChannel.EventSink? = null
+
+    /// ProcessLifecycleOwner delivers ON_START/ON_STOP on the main thread,
+    /// which is also where EventSink.success must run — no Handler bounce.
+    private val observer = LifecycleEventObserver { _, event ->
+        when (event) {
+            Lifecycle.Event.ON_START -> emitFocus(true)
+            Lifecycle.Event.ON_STOP -> emitFocus(false)
+            else -> Unit
+        }
+    }
+
+    override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {
+        val ec = EventChannel(binding.binaryMessenger, "ux/window/events")
+        ec.setStreamHandler(this)
+        eventChannel = ec
+        ProcessLifecycleOwner.get().lifecycle.addObserver(observer)
+    }
+
+    override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {
+        ProcessLifecycleOwner.get().lifecycle.removeObserver(observer)
+        eventChannel?.setStreamHandler(null)
+        eventChannel = null
+        eventSink = null
+    }
+
+    override fun onListen(arguments: Any?, events: EventChannel.EventSink?) {
+        eventSink = events
+        // Seed the current state so a late subscriber gets the right value
+        // immediately instead of waiting for the next ON_START / ON_STOP.
+        val foreground = ProcessLifecycleOwner.get().lifecycle.currentState
+            .isAtLeast(Lifecycle.State.STARTED)
+        emitFocus(foreground)
+    }
+
+    override fun onCancel(arguments: Any?) {
+        eventSink = null
+    }
+
+    private fun emitFocus(focused: Boolean) {
+        eventSink?.success(mapOf("type" to "focus", "focused" to focused))
+    }
+}

android/src/main/kotlin/io/swipelab/ux/XPlugin.kt

@@ -19,6 +19,8 @@ class XPlugin : FlutterPlugin, ActivityAware {
         VideoPlayerPlugin(),
         CrashPlugin(),
         UrlPlugin(),
+        NotificationsPlugin(),
+        WindowPlugin(),
     )
 
     override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) =

android/src/main/kotlin/io/swipelab/ux/video/Renderers.kt

@@ -1,28 +1,77 @@
 package io.swipelab.ux.video
 
 import android.content.Context
+import android.os.Handler
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.exoplayer.DefaultRenderersFactory
+import androidx.media3.exoplayer.Renderer
 import androidx.media3.exoplayer.RenderersFactory
 import androidx.media3.exoplayer.mediacodec.MediaCodecInfo
 import androidx.media3.exoplayer.mediacodec.MediaCodecSelector
+import androidx.media3.exoplayer.video.VideoRendererEventListener
+import io.swipelab.ux.video.ffmpeg.FfmpegLibrary
+import io.swipelab.ux.video.ffmpeg.FfmpegSurfaceSizer
+import io.swipelab.ux.video.ffmpeg.FfmpegVideoRenderer
 
-/// Renderer factory configured for Banlu. Two non-default tweaks:
+/// Renderer factory configured for Banlu.
 ///
-///   - `setEnableDecoderFallback(true)` — Media3's default refuses to
-///     fall back if the primary decoder fails to start. On Huawei
-///     EMUI (Mate 20 Pro / LYA-L29 / API 29) the hardware AVC decoder
-///     `OMX.hisi.video.decoder.avc` fails codec start; without
-///     fallback the surface stays black.
-///   - `MediaCodecSelector` deprioritises `OMX.hisi.*` so Media3
-///     picks the working software decoder first
-///     (`c2.android.avc.decoder` on the affected device). The
-///     hardware decoder stays as a last-resort option for devices
-///     where it works correctly.
+/// Video path is tiered:
+///   1. `FfmpegVideoRenderer` — vendored Media3 FFmpeg extension that
+///      decodes H.264 with libavcodec and converts YUV→RGB via a GLES2
+///      shader. Selected first for any MIME type FFmpeg supports. Has
+///      no DPB cap, handles iOS yuvj420p full-range streams that defeat
+///      both `c2.hisi.avc.decoder` (EMUI 11 Mate 20 stalls on the first
+///      sample after init) and `c2.android.avc.decoder` (Google C2 SW
+///      caps output delay at 8 frames; iOS H.264 with `has_b_frames=16`
+///      starves the decoder until CCodec's queue timeout). When
+///      `libffmpegJNI.so` is missing for the current ABI, FfmpegLibrary
+///      returns isAvailable()=false and selection falls through.
+///   2. `MediaCodec` path with `setEnableDecoderFallback(true)`. Init
+///      failures (EMUI 10 `OMX.hisi.video.decoder.avc`) bounce to the
+///      next decoder.
+///   3. `MediaCodecSelector` deprioritises every HiSilicon decoder
+///      (`OMX.hisi.*` and `c2.hisi.*`) so Media3 picks
+///      `c2.android.avc.decoder` ahead of `c2.hisi.avc.decoder` when
+///      FFmpeg isn't available. Without this, the EMUI 11 C2 Hisi
+///      decoder is chosen and fails after init — which decoder
+///      fallback doesn't catch.
 @UnstableApi
 internal object Renderers {
-  fun build(context: Context): RenderersFactory {
-    return DefaultRenderersFactory(context)
+  fun build(context: Context, surfaceSizer: FfmpegSurfaceSizer): RenderersFactory {
+    return object : DefaultRenderersFactory(context) {
+      override fun buildVideoRenderers(
+        context: Context,
+        extensionRendererMode: Int,
+        mediaCodecSelector: MediaCodecSelector,
+        enableDecoderFallback: Boolean,
+        eventHandler: Handler,
+        eventListener: VideoRendererEventListener,
+        allowedVideoJoiningTimeMs: Long,
+        out: ArrayList<Renderer>,
+      ) {
+        if (FfmpegLibrary.isAvailable()) {
+          out.add(
+            FfmpegVideoRenderer(
+              allowedVideoJoiningTimeMs,
+              eventHandler,
+              eventListener,
+              MAX_DROPPED_VIDEO_FRAME_COUNT_TO_NOTIFY,
+              surfaceSizer,
+            ),
+          )
+        }
+        super.buildVideoRenderers(
+          context,
+          extensionRendererMode,
+          mediaCodecSelector,
+          enableDecoderFallback,
+          eventHandler,
+          eventListener,
+          allowedVideoJoiningTimeMs,
+          out,
+        )
+      }
+    }
       .setEnableDecoderFallback(true)
       .setMediaCodecSelector { mimeType, requiresSecure, requiresTunneling ->
         val infos = MediaCodecSelector.DEFAULT.getDecoderInfos(
@@ -31,7 +80,12 @@ internal object Renderers {
         val ok = ArrayList<MediaCodecInfo>(infos.size)
         val broken = ArrayList<MediaCodecInfo>()
         for (info in infos) {
-          if (info.name.startsWith("OMX.hisi.")) broken.add(info) else ok.add(info)
+          val name = info.name.lowercase()
+          if (name.startsWith("omx.hisi.") || name.startsWith("c2.hisi.")) {
+            broken.add(info)
+          } else {
+            ok.add(info)
+          }
         }
         ok.addAll(broken)
         ok

android/src/main/kotlin/io/swipelab/ux/video/VideoCompositor.kt

@@ -77,7 +77,7 @@ internal class VideoCompositor(
   private var eglPbufferSurface: EGLSurface = EGL14.EGL_NO_SURFACE
   private var eglWindowSurface: EGLSurface = EGL14.EGL_NO_SURFACE
   private var inputTextureId: Int = 0
-  private var inputSurfaceTexture: SurfaceTexture? = null
+  @Volatile private var inputSurfaceTexture: SurfaceTexture? = null
   private var inputSurface: Surface? = null
 
   private var program: Int = 0
@@ -128,6 +128,23 @@ internal class VideoCompositor(
     }
   }
 
+  /// Sizes the codec-input SurfaceTexture's buffer dimensions. For
+  /// MediaCodec this is unnecessary — the codec writes via native
+  /// surface APIs that auto-size the SurfaceTexture buffer to the
+  /// encoded frame. For our FFmpeg path the codec writes via an EGL
+  /// window surface (created from this Surface), and eglCreateWindow
+  /// Surface inherits the SurfaceTexture's defaultBufferSize at
+  /// creation time and never re-queries. Without this hook the EGL
+  /// surface is created at whatever default the SurfaceTexture is in
+  /// (1×1 in practice) and the rendered quad is squashed to one pixel
+  /// that the downstream blit then stretches across the whole Flutter
+  /// texture — looks like a solid fill. Safe to call from any thread.
+  fun setInputSurfaceSize(width: Int, height: Int) {
+    if (disposed) return
+    if (width <= 0 || height <= 0) return
+    inputSurfaceTexture?.setDefaultBufferSize(width, height)
+  }
+
   fun setDisplaySize(width: Int, height: Int) {
     if (disposed) return
     if (width <= 0 || height <= 0) return
@@ -370,7 +387,11 @@ internal class VideoCompositor(
         EGL14.eglDestroyContext(eglDisplay, eglContext)
         eglContext = EGL14.EGL_NO_CONTEXT
       }
-      EGL14.eglTerminate(eglDisplay)
+      EGL14.eglReleaseThread()
+      // NB: do NOT eglTerminate(EGL_DEFAULT_DISPLAY) here — the
+      // display is shared with FfmpegOutputSurface's EGL context,
+      // and tearing it down would silently kill the other consumer's
+      // window surface. Per-context cleanup above is enough.
       eglDisplay = EGL14.EGL_NO_DISPLAY
     }
   }

android/src/main/kotlin/io/swipelab/ux/video/VideoPlayerInstance.kt

@@ -35,7 +35,6 @@ internal class VideoPlayerInstance(
   val textureId: Long get() = textureEntry.id()
 
   private val mainHandler = Handler(Looper.getMainLooper())
-  private val player: ExoPlayer = ExoPlayer.Builder(context, Renderers.build(context)).build()
 
   /// Wrapped around the Flutter `SurfaceTextureEntry`'s `SurfaceTexture`.
   /// We deliberately do NOT call `setDefaultBufferSize` here — that
@@ -77,6 +76,15 @@ internal class VideoPlayerInstance(
     },
   )
 
+  private val player: ExoPlayer = ExoPlayer.Builder(
+    context,
+    // FFmpeg renderer calls this on its own thread before it builds
+    // an EGL window surface against the codec-input Surface. Sizes
+    // the compositor's INPUT SurfaceTexture so the EGL surface
+    // inherits matching buffer dimensions on creation.
+    Renderers.build(context) { w, h -> compositor.setInputSurfaceSize(w, h) },
+  ).build()
+
   private var disposed = false
   private var firstFrameRendered = false
   private var stateReady = false

docs/architecture.md

@@ -0,0 +1,195 @@
+# ux — architecture
+
+This doc maps the load-bearing modules in the `ux` Flutter package: where
+each lives, what it owns, and which native pieces back it on each
+platform. Banlu is the primary consumer; everything here is meant to be
+reusable across other Flutter apps that depend on `ux`.
+
+Conventions:
+
+* Source paths are anchored at the package root (e.g. `lib/src/...`).
+* Native paths use `android/...` and `darwin/...` (shared
+  iOS+macOS sources) or `ios/` / `macos/` (platform-specific).
+* "Banned" means: don't reintroduce. Lints and tests exist to catch
+  regressions where applicable.
+
+---
+
+## Module map
+
+| Module | Dart | Android | Apple |
+|---|---|---|---|
+| `XKeyboard` — frame-accurate keyboard tracking + interactive dismiss | [lib/src/keyboard/](../lib/src/keyboard/) | [android/src/main/jni/keyboard_bridge.c](../android/src/main/jni/keyboard_bridge.c) | [darwin/Keyboard/](../darwin/Keyboard/) |
+| `XSensors` — gyro / accelerometer over JNI/FFI | [lib/src/sensors/](../lib/src/sensors/) | [android/src/main/jni/sensor_bridge.c](../android/src/main/jni/sensor_bridge.c) | [darwin/Sensors/](../darwin/Sensors/) |
+| `XCamera` — CameraX (Android) / AVCaptureSession (Apple) | [lib/src/camera/](../lib/src/camera/) | [android/src/main/kotlin/io/swipelab/ux/camera/](../android/src/main/kotlin/io/swipelab/ux/camera/) | [darwin/Camera/](../darwin/Camera/) |
+| `XScanner` — ZXing QR scanner (Android) / VNDetect (Apple) | [lib/src/scanner/](../lib/src/scanner/) | [android/src/main/kotlin/io/swipelab/ux/scanner/](../android/src/main/kotlin/io/swipelab/ux/scanner/) | [darwin/Scanner/](../darwin/Scanner/) |
+| `XVideoPlayer` — ExoPlayer (Android) / AVPlayer (Apple) | [lib/src/video/](../lib/src/video/) | [android/src/main/kotlin/io/swipelab/ux/video/](../android/src/main/kotlin/io/swipelab/ux/video/) | [darwin/Video/](../darwin/Video/) |
+| `XNotifications` — OS notifications: show / cancel / tap / authorization | [lib/src/notifications/](../lib/src/notifications/) | [android/.../NotificationsPlugin.kt](../android/src/main/kotlin/io/swipelab/ux/NotificationsPlugin.kt) | [macos/Classes/NotificationsPlugin.swift](../macos/Classes/NotificationsPlugin.swift) (macOS only) |
+| `XWindow` — host focus state (`focused`) | [lib/src/window/](../lib/src/window/) | [android/.../WindowPlugin.kt](../android/src/main/kotlin/io/swipelab/ux/WindowPlugin.kt) | [macos/Classes/WindowPlugin.swift](../macos/Classes/WindowPlugin.swift) (macOS only) |
+| `XFile`, navi — see source | [lib/src/](../lib/src/) | mixed | mixed |
+
+---
+
+## Video pipeline (Android)
+
+The Android video stack is the most involved piece in `ux` because it
+spans four cooperating layers (Dart controller → Kotlin player
+instance → Media3 ExoPlayer → GL compositor → Flutter texture). It
+also carries the most production-load-bearing fix: a vendored FFmpeg
+video decoder that fronts the platform `MediaCodec` path for files
+the OEM hardware decoder can't handle.
+
+### Layers
+
+```
+Dart  XVideoPlayerController (lib/src/video/x_video_player.dart)
+       │   MethodChannel `ux/video`
+       ▼
+Kotlin VideoPlayerInstance (one per Dart controller)
+       │   owns:
+       │   ├── ExoPlayer  (Media3 1.9.2; renderers wired via Renderers.kt)
+       │   ├── VideoCompositor (codec output → Flutter texture; GL blit)
+       │   └── Flutter SurfaceTextureEntry (the texture id Dart Texture() samples)
+       ▼
+Native Media3 video renderer
+       │   tier 1: FfmpegVideoRenderer  (libavcodec, SW decode, GL YUV→RGB)
+       │   tier 2: MediaCodecVideoRenderer (HW path; HiSilicon C2 decoders
+       │           deprioritised so EMUI 10/11 falls through to c2.android.avc.decoder)
+       ▼
+GL    SurfaceTexture (compositor input)
+       │   compositor reads + applies SurfaceTexture transform
+       │   blits to Flutter SurfaceTexture (output)
+       ▼
+Flutter Texture widget samples the SurfaceTexture, scales to widget size
+```
+
+### Files
+
+| What | Where |
+|---|---|
+| Dart controller | [lib/src/video/x_video_player.dart](../lib/src/video/x_video_player.dart) |
+| MethodChannel binding | [lib/src/video/x_video_player_channel.dart](../lib/src/video/x_video_player_channel.dart) |
+| Texture widget | [lib/src/video/x_video_player_view.dart](../lib/src/video/x_video_player_view.dart) |
+| Per-controller native player | [android/src/main/kotlin/io/swipelab/ux/video/VideoPlayerInstance.kt](../android/src/main/kotlin/io/swipelab/ux/video/VideoPlayerInstance.kt) |
+| ExoPlayer renderer factory | [android/src/main/kotlin/io/swipelab/ux/video/Renderers.kt](../android/src/main/kotlin/io/swipelab/ux/video/Renderers.kt) |
+| GL blit between codec and Flutter texture | [android/src/main/kotlin/io/swipelab/ux/video/VideoCompositor.kt](../android/src/main/kotlin/io/swipelab/ux/video/VideoCompositor.kt) |
+| FFmpeg renderer (Java) | [android/src/main/java/io/swipelab/ux/video/ffmpeg/](../android/src/main/java/io/swipelab/ux/video/ffmpeg/) |
+| FFmpeg JNI source | [android/ffmpeg/ffmpeg_jni.cc](../android/ffmpeg/ffmpeg_jni.cc) |
+| FFmpeg build orchestrator | [android/ffmpeg/build_ffmpeg.sh](../android/ffmpeg/build_ffmpeg.sh) |
+
+### Renderer selection (`Renderers.kt`)
+
+`Renderers.build(context, surfaceSizer)` returns a `DefaultRenderersFactory`
+subclass that builds the video renderer list with FFmpeg first and
+MediaCodec second:
+
+1. **`FfmpegVideoRenderer`** — picked when `FfmpegLibrary.isAvailable()`
+   returns true (i.e. `libffmpegJNI.so` is loaded for the device's ABI)
+   *and* the format is H.264. Software decode via libavcodec, no DPB
+   cap, handles iOS `yuvj420p` (full-range) and deep B-frame reorder
+   structures that defeat platform decoders on older Huawei silicon.
+   YUV→RGB happens in a one-pass GLES2 shader inside
+   `FfmpegOutputSurface`. Y plane uses `GL_NEAREST` filtering (1:1
+   sized to the EGL surface, sampling at exact texel centres preserves
+   luma detail); chroma uses `GL_LINEAR` for clean 4:2:0 upsampling.
+2. **`MediaCodecVideoRenderer`** (Media3 default) — picked for any
+   other format, or if FFmpeg is unavailable. Two non-default tweaks:
+   * `setEnableDecoderFallback(true)` so init-time failures bounce to
+     the next decoder.
+   * Custom `MediaCodecSelector` deprioritises every HiSilicon
+     decoder (`OMX.hisi.*` and `c2.hisi.*`). The EMUI 10 OMX variant
+     fails codec start (caught by fallback); the EMUI 11 C2 variant
+     initialises cleanly but errors on the first sample, which
+     fallback can't catch — name-based deprioritisation is the only
+     way past it when FFmpeg is unavailable for that ABI.
+
+The two-tier design is intentional: FFmpeg adds a slight battery cost
+vs. hardware decoding, but it's the only path that reliably plays the
+full range of producer-side content (iOS recordings in particular).
+Hardware stays as the fallback for the formats and devices where it
+works.
+
+### Why we vendor an FFmpeg video renderer
+
+Media3's published `decoder-ffmpeg` is audio-only.
+`ExperimentalFfmpegVideoRenderer` in the same library has been a stub
+since 2020 (`createDecoder` returns null, `supportsFormat` returns
+`FORMAT_UNSUPPORTED_TYPE`). The only well-maintained community
+alternative (NextLib) is GPL-3.0 — would impose copyleft on every
+consumer. So we ship our own Apache-licensed JNI on top of the LGPL
+FFmpeg, vendored under `android/ffmpeg/`.
+
+### How the FFmpeg `.so` gets built
+
+There are no native binaries in the repo. The `:ux:buildFfmpegJni`
+Gradle task (wired to `preBuild` in
+[android/build.gradle](../android/build.gradle)) handles everything:
+
+1. Clones Media3 (`1.9.2`) and FFmpeg (`release/6.0`) into the
+   consumer's `build/ffmpeg-work/` on first run.
+2. Drops the vendored `ffmpeg_jni.cc` + `CMakeLists.txt` over the
+   upstream copies (so the produced JNI exposes the video entry points
+   `FfmpegVideoDecoder.java` calls).
+3. Cross-builds FFmpeg static libs (H.264 only) for all 4 Android ABIs.
+4. Links `libffmpegJNI.so` per ABI and writes them into
+   `<ux-build>/jniLibs/<abi>/`, which AGP picks up via
+   `sourceSets.main.jniLibs.srcDirs +=`.
+
+Up-to-date checking on `ffmpeg_jni.cc` + `CMakeLists.txt` +
+`build_ffmpeg.sh` means subsequent builds skip the task entirely. The
+slow part (FFmpeg static-lib build, ~30 min on an x86 host, ~2 min on
+Apple Silicon) only happens on the first build for a given checkout,
+or after a `gradle clean`.
+
+License: FFmpeg is LGPL v2.1, linked dynamically at runtime via
+`System.loadLibrary("ffmpegJNI")` — the LGPL boundary stays intact.
+The build config omits `--enable-gpl` and `--enable-nonfree`. See
+[android/ffmpeg/LICENSE-FFMPEG.txt](../android/ffmpeg/LICENSE-FFMPEG.txt)
+and [android/ffmpeg/README.md](../android/ffmpeg/README.md).
+
+### Looping and end-of-stream
+
+`XVideoPlayerController.setLooping(true)` maps to ExoPlayer's
+`REPEAT_MODE_ONE` (the entire seek-to-0-and-resume cycle is handled
+in-engine). Non-looping playback emits a `completed` event when
+`STATE_ENDED` is reached without repeat — see
+`VideoPlayerInstance.kt`. Consumers that need tap-play-at-end-restarts
+behavior (Telegram parity) check `position` against `duration` on the
+Dart side and call `seekTo(Duration.zero)` before `play()` when within
+2 seconds of the end.
+
+---
+
+## Video pipeline (Apple)
+
+`AVPlayer` + `AVPlayerItem` + `AVPlayerItemVideoOutput`. No FFmpeg
+fallback needed — `AVFoundation` handles iOS-produced H.264 (and HEVC)
+directly without the DPB-cap / full-range quirks the Android platform
+decoders trip over. See
+[darwin/Video/VideoPlayerInstance.swift](../darwin/Video/VideoPlayerInstance.swift).
+
+## Notifications + window focus
+
+`XNotifications` and `XWindow` share a two-channel shape: a `MethodChannel`
+for commands and an `EventChannel` for native-pushed events. Each Dart
+constructor only subscribes to its `EventChannel` on platforms that
+register a native handler (`defaultTargetPlatform` gate) — otherwise
+activating the stream throws `MissingPluginException`, which Flutter
+reports straight to `FlutterError.onError`.
+
+Handler coverage:
+
+| | macOS | Android | iOS |
+|---|---|---|---|
+| `XWindow` (`ux/window/events`) | `NSApplication` active/resign | `ProcessLifecycleOwner` `ON_START`/`ON_STOP` | none — `focused` stays `true` |
+| `XNotifications` (`ux/notifications` + `…/events`) | `UNUserNotificationCenter` | `NotificationManagerCompat` + `POST_NOTIFICATIONS` | none |
+
+On Android the two are coupled: `XWindow.focused` flipping to `false`
+when the app backgrounds is what lets a consumer (Banlu's
+`MessageNotifier`) post a local notification for a live socket message
+while the process is alive but unfocused — the gap FCM intentionally
+skips for socket-connected devices. The notification's tap `PendingIntent`
+relaunches the app's launcher activity (resolved generically via
+`getLaunchIntentForPackage`, no app class hard-coded) carrying the `data`
+payload, which the plugin re-emits as a `tap` event; a tap that cold-starts
+the process is buffered until Dart subscribes.

lib/src/navi/router.dart

@@ -77,7 +77,8 @@ class XRouter extends BackButtonDispatcher
   late final _overlayEntry = OverlayEntry(builder: _buildContent);
 
   bool get canPop {
-    if (stack.isNotEmpty) return true;
+    final top = stack.lastOrNull;
+    if (top != null) return top.canPop;
     if (home is ScreenShell) {
       for (final screen in (home as ScreenShell).pages) {
         if (!screen.popped) return true;
@@ -225,7 +226,7 @@ class XRouterBack extends RootBackButtonDispatcher {
     }
     if (router.home.handleBack()) return true;
     final page = router.stack.lastOrNull;
-    if (page != null) {
+    if (page != null && page.canPop) {
       page.pop();
       return true;
     }

lib/src/navi/screen_stack.dart

@@ -75,7 +75,7 @@ class ScreenStackState extends State<ScreenStack> with TickerProviderStateMixin
   }
 
   void _updateCanPop() {
-    final canPop = _entries.any((e) => !e.removing);
+    final canPop = _entries.any((e) => !e.removing && e.page.canPop);
     if (canPop == _canPop) return;
     _canPop = canPop;
     WidgetsBinding.instance.addPostFrameCallback((_) {
@@ -258,7 +258,7 @@ class ScreenStackState extends State<ScreenStack> with TickerProviderStateMixin
               ScreenBackHandler(
                 key: entry.key,
                 entry: entry,
-                enabled: entry == top && _canPop,
+                enabled: entry == top && _canPop && entry.page.canPop,
                 onPop: () => entry.page.pop(),
               ),
           ],

lib/src/notifications/x_notifications.dart

@@ -1,6 +1,7 @@
 import 'dart:async';
 
-import 'package:flutter/foundation.dart' show ValueListenable;
+import 'package:flutter/foundation.dart'
+    show ValueListenable, defaultTargetPlatform, TargetPlatform;
 import 'package:flutter/services.dart';
 
 import '../core/emitter.dart';
@@ -8,20 +9,17 @@ import '../log.dart' show Log;
 
 final _log = Log.tag('notifications');
 
-/// Generic OS-notification + window-focus surface. Domain-agnostic — the
-/// caller decides when to emit and how to format the payload. Implemented
-/// on macOS via `UNUserNotificationCenter` and NSWindow key-focus
-/// observers (see `macos/Classes/NotificationsPlugin.swift`).
+/// OS-notification primitive. Domain-agnostic — the caller decides when
+/// to emit and how to format the payload. Backed natively on macOS
+/// (`UNUserNotificationCenter`) and Android (`NotificationManagerCompat`);
+/// see the platform `NotificationsPlugin`. No handler on iOS, where calls
+/// no-op. Window-focus state lives in [XWindow], not here.
 abstract interface class XNotifications {
   /// Production singleton — talks to the native plugin via MethodChannel
   /// + EventChannel. Tests inject a fake `XNotifications` directly into
   /// their service-under-test rather than swap this field.
   static final XNotifications instance = MethodChannelXNotifications();
 
-  /// True when the host window currently holds key focus. Defaults to
-  /// `true` until the native side emits an initial focus event.
-  ValueListenable<bool> get windowFocused;
-
   /// `null` = OS hasn't been asked; `true`/`false` after the user has
   /// answered an authorization prompt.
   ValueListenable<bool?> get authorized;
@@ -42,17 +40,21 @@ abstract interface class XNotifications {
 
 class MethodChannelXNotifications implements XNotifications {
   MethodChannelXNotifications() {
+    if (!_hasNativeHandler) return;
     _eventsChannel.receiveBroadcastStream().listen(_onEvent, onError: (e, st) {
       _log.w('event channel error', error: e, stackTrace: st);
     });
   }
 
+  /// Only macOS and Android register a native handler; activating the events
+  /// channel elsewhere throws `MissingPluginException`.
+  static bool get _hasNativeHandler =>
+      defaultTargetPlatform == TargetPlatform.macOS ||
+      defaultTargetPlatform == TargetPlatform.android;
+
   static const _channel = MethodChannel('ux/notifications');
   static const _eventsChannel = EventChannel('ux/notifications/events');
 
-  @override
-  final ValueEmitter<bool> windowFocused = ValueEmitter(true);
-
   @override
   final ValueEmitter<bool?> authorized = ValueEmitter(null);
 
@@ -97,8 +99,7 @@ class MethodChannelXNotifications implements XNotifications {
   @override
   Future<void> cancelByThread(String threadId) async {
     try {
-      await _channel
-          .invokeMethod('cancelByThread', {'threadId': threadId});
+      await _channel.invokeMethod('cancelByThread', {'threadId': threadId});
     } on PlatformException catch (e) {
       _log.w('cancelByThread failed: ${e.message}');
     } on MissingPluginException {
@@ -121,9 +122,6 @@ class MethodChannelXNotifications implements XNotifications {
     if (event is! Map) return;
     final m = event.cast<Object?, Object?>();
     switch (m['type']) {
-      case 'focus':
-        final f = m['focused'];
-        if (f is bool) windowFocused.value = f;
       case 'authorization':
         final g = m['granted'];
         if (g is bool) authorized.value = g;

lib/src/view_padding.dart

@@ -33,7 +33,10 @@ class XInsets with ChangeNotifier, WidgetsBindingObserver {
   EdgeInsets _system = EdgeInsets.zero;
   EdgeInsets _current = EdgeInsets.zero;
   EdgeInsets _from = EdgeInsets.zero;
-  Duration _start = Duration.zero;
+  // Lazy: captured on the first _tick of an animation so the value lives in
+  // the same time domain as the frame-callback `ts` parameter (epoch-adjusted),
+  // not the raw `currentSystemFrameTimeStamp` which is since-boot.
+  Duration? _start;
   bool _ticking = false;
   Duration? _nextAnimationDuration;
 
@@ -77,19 +80,18 @@ class XInsets with ChangeNotifier, WidgetsBindingObserver {
     }
     _from = _current;
     _animDuration = animDuration;
-    _start = SchedulerBinding.instance.currentSystemFrameTimeStamp;
-    if (!_ticking) {
-      _ticking = true;
-      SchedulerBinding.instance.scheduleFrameCallback(_tick);
-      SchedulerBinding.instance.scheduleFrame();
-    }
+    _start = null;
+    _ticking = true;
+    SchedulerBinding.instance.scheduleFrameCallback(_tick);
+    SchedulerBinding.instance.scheduleFrame();
   }
 
   Duration _animDuration = Duration.zero;
 
   void _tick(Duration ts) {
     if (!_ticking) return;
-    final dt = (ts - _start).inMicroseconds / _animDuration.inMicroseconds;
+    _start ??= ts;
+    final dt = (ts - _start!).inMicroseconds / _animDuration.inMicroseconds;
     final t = curve.transform(dt.clamp(0.0, 1.0));
     _current = EdgeInsets.lerp(_from, _system, t)!;
     notifyListeners();
@@ -98,6 +100,7 @@ class XInsets with ChangeNotifier, WidgetsBindingObserver {
       SchedulerBinding.instance.scheduleFrame();
     } else {
       _ticking = false;
+      _start = null;
     }
   }
 

lib/src/window/x_window.dart

@@ -0,0 +1,54 @@
+import 'package:flutter/foundation.dart'
+    show ValueListenable, defaultTargetPlatform, TargetPlatform;
+import 'package:flutter/services.dart';
+
+import '../core/emitter.dart';
+import '../log.dart' show Log;
+
+final _log = Log.tag('window');
+
+/// Host-window state primitive. Today exposes only [focused] (the macOS
+/// `NSApp.didBecomeActive` / `didResignActive` signal); future window-level
+/// state — minimized, occluded, screen — can land alongside it without
+/// disturbing call sites.
+abstract interface class XWindow {
+  static final XWindow instance = MethodChannelXWindow();
+
+  /// `true` when this app currently has user focus.
+  ///
+  /// - macOS: tracks `NSApplication` active / resign via the native plugin.
+  /// - Android: tracks app foreground / background via `ProcessLifecycleOwner`,
+  ///   so a backgrounded-but-alive process reports `false`.
+  /// - iOS: no native plugin registers, so the emitter stays at its `true`
+  ///   default.
+  ValueListenable<bool> get focused;
+}
+
+class MethodChannelXWindow implements XWindow {
+  MethodChannelXWindow() {
+    if (!_hasNativeHandler) return;
+    _events.receiveBroadcastStream().listen(_onEvent, onError: (e, st) {
+      _log.w('event channel error', error: e, stackTrace: st);
+    });
+  }
+
+  /// Only macOS and Android register a native stream handler for the events
+  /// channel; activating it elsewhere throws `MissingPluginException`.
+  static bool get _hasNativeHandler =>
+      defaultTargetPlatform == TargetPlatform.macOS ||
+      defaultTargetPlatform == TargetPlatform.android;
+
+  static const _events = EventChannel('ux/window/events');
+
+  @override
+  final ValueEmitter<bool> focused = ValueEmitter(true);
+
+  void _onEvent(Object? event) {
+    if (event is! Map) return;
+    final m = event.cast<Object?, Object?>();
+    if (m['type'] == 'focus') {
+      final f = m['focused'];
+      if (f is bool) focused.value = f;
+    }
+  }
+}

lib/ux.dart

@@ -20,6 +20,7 @@ export 'src/video/x_video_player_channel.dart' show MethodChannelXVideoPlayerBac
 export 'src/video/x_video_player_view.dart' show XVideoPlayerView;
 export 'src/clipboard.dart';
 export 'src/notifications/x_notifications.dart';
+export 'src/window/x_window.dart';
 export 'src/file.dart';
 export 'src/gallery.dart';
 export 'src/keyboard.dart';

macos/Classes/NotificationsPlugin.swift

@@ -2,10 +2,10 @@ import AppKit
 import FlutterMacOS
 import UserNotifications
 
-/// `ux/notifications` + `ux/notifications/events`. Generic OS-notification
-/// + app-focus surface used by hosts that want native Notification Center
-/// entries on macOS. Domain-agnostic — the Dart caller decides when to
-/// emit and how to format the payload.
+/// `ux/notifications` + `ux/notifications/events`. Domain-agnostic native
+/// OS-notification surface: show / cancel via the method channel, tap +
+/// authorization changes via the event channel. Window-focus state lives
+/// in `WindowPlugin` (see `XWindow` on the Dart side).
 public class NotificationsPlugin: NSObject, NativePlugin, FlutterStreamHandler,
     UNUserNotificationCenterDelegate
 {
@@ -31,7 +31,6 @@ public class NotificationsPlugin: NSObject, NativePlugin, FlutterStreamHandler,
         eventChannel = events
 
         UNUserNotificationCenter.current().delegate = self
-        observeAppActivation()
     }
 
     // MARK: - FlutterStreamHandler
@@ -41,9 +40,6 @@ public class NotificationsPlugin: NSObject, NativePlugin, FlutterStreamHandler,
         eventSink events: @escaping FlutterEventSink
     ) -> FlutterError? {
         eventSink = events
-        // Seed the initial focus state so Dart-side starts in a deterministic
-        // value rather than the constructor default.
-        emit(["type": "focus", "focused": NSApp.isActive])
         return nil
     }
 
@@ -148,8 +144,6 @@ public class NotificationsPlugin: NSObject, NativePlugin, FlutterStreamHandler,
         UNUserNotificationCenter.current().add(request) { error in
             if let error = error {
                 NSLog("ux notifications: add failed: \(error)")
-            } else {
-                NSLog("ux notifications: posted id=\(id) thread=\(threadId ?? "-")")
             }
         }
     }
@@ -173,32 +167,6 @@ public class NotificationsPlugin: NSObject, NativePlugin, FlutterStreamHandler,
         }
     }
 
-    // MARK: - App-activation observers
-
-    private func observeAppActivation() {
-        let nc = NotificationCenter.default
-        nc.addObserver(
-            self,
-            selector: #selector(onDidBecomeActive),
-            name: NSApplication.didBecomeActiveNotification,
-            object: nil,
-        )
-        nc.addObserver(
-            self,
-            selector: #selector(onDidResignActive),
-            name: NSApplication.didResignActiveNotification,
-            object: nil,
-        )
-    }
-
-    @objc private func onDidBecomeActive() {
-        emit(["type": "focus", "focused": true])
-    }
-
-    @objc private func onDidResignActive() {
-        emit(["type": "focus", "focused": false])
-    }
-
     // MARK: - UNUserNotificationCenterDelegate
 
     public func userNotificationCenter(
@@ -211,12 +179,9 @@ public class NotificationsPlugin: NSObject, NativePlugin, FlutterStreamHandler,
         // it as a banner — entries never reach Notification Center. The
         // 11+ split is `.banner` + `.list`; we need both so the toast
         // shows AND persists in the tray.
-        let id = notification.request.identifier
         if #available(macOS 11.0, *) {
-            NSLog("ux notifications: willPresent id=\(id) → [.banner, .list, .sound]")
             completionHandler([.banner, .list, .sound])
         } else {
-            NSLog("ux notifications: willPresent id=\(id) → [.alert, .sound]")
             completionHandler([.alert, .sound])
         }
     }

macos/Classes/WindowPlugin.swift

@@ -0,0 +1,68 @@
+import AppKit
+import FlutterMacOS
+
+/// `ux/window/events`. Reports host-application focus state — emits
+/// `{type: "focus", focused: Bool}` whenever the active NSApplication
+/// flips. Seeded from `NSApp.isActive` when Dart subscribes so the
+/// emitter starts in a deterministic value.
+public class WindowPlugin: NSObject, NativePlugin, FlutterStreamHandler {
+    private var eventChannel: FlutterEventChannel?
+    private var eventSink: FlutterEventSink?
+
+    public func register(with registrar: FlutterPluginRegistrar) {
+        let events = FlutterEventChannel(
+            name: "ux/window/events",
+            binaryMessenger: registrar.messenger,
+        )
+        events.setStreamHandler(self)
+        eventChannel = events
+
+        observeAppActivation()
+    }
+
+    // MARK: - FlutterStreamHandler
+
+    public func onListen(
+        withArguments arguments: Any?,
+        eventSink events: @escaping FlutterEventSink
+    ) -> FlutterError? {
+        eventSink = events
+        emit(["type": "focus", "focused": NSApp.isActive])
+        return nil
+    }
+
+    public func onCancel(withArguments arguments: Any?) -> FlutterError? {
+        eventSink = nil
+        return nil
+    }
+
+    // MARK: - Observers
+
+    private func observeAppActivation() {
+        let nc = NotificationCenter.default
+        nc.addObserver(
+            self,
+            selector: #selector(onDidBecomeActive),
+            name: NSApplication.didBecomeActiveNotification,
+            object: nil,
+        )
+        nc.addObserver(
+            self,
+            selector: #selector(onDidResignActive),
+            name: NSApplication.didResignActiveNotification,
+            object: nil,
+        )
+    }
+
+    @objc private func onDidBecomeActive() {
+        emit(["type": "focus", "focused": true])
+    }
+
+    @objc private func onDidResignActive() {
+        emit(["type": "focus", "focused": false])
+    }
+
+    private func emit(_ event: [String: Any]) {
+        eventSink?(event)
+    }
+}

macos/Classes/XPlugin.swift

@@ -13,6 +13,7 @@ public class XPlugin: NSObject, FlutterPlugin {
             UxVideoPlayerPlugin(),
             UrlPlugin(),
             NotificationsPlugin(),
+            WindowPlugin(),
         ]
         for plugin in plugins {
             plugin.register(with: registrar)

macos/ux.podspec

@@ -21,6 +21,11 @@ CMD
   s.script_phases    = [{
     :name             => 'Mirror darwin/{Camera,Video}',
     :execution_position => :before_compile,
+    # We want this to run every build (the comment above explains why),
+    # so opt out of Xcode's dependency analysis instead of trying to
+    # enumerate inputs/outputs. Silences the "will be run during every
+    # build" warning without changing semantics.
+    :always_out_of_date => '1',
     :script           => <<-CMD
 set -e
 for MOD in Camera Video; do

test/notifications_test.dart

@@ -0,0 +1,123 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:ux/ux.dart';
+
+void main() {
+  final messenger =
+      TestWidgetsFlutterBinding.ensureInitialized().defaultBinaryMessenger;
+  const methods = MethodChannel('ux/notifications');
+  const events = MethodChannel('ux/notifications/events');
+
+  final calls = <MethodCall>[];
+
+  setUp(() {
+    calls.clear();
+    messenger.setMockMethodCallHandler(methods, (call) async {
+      calls.add(call);
+      return call.method == 'requestPermission' ? true : null;
+    });
+    messenger.setMockMethodCallHandler(events, (_) async => null);
+  });
+
+  tearDown(() {
+    messenger.setMockMethodCallHandler(methods, null);
+    messenger.setMockMethodCallHandler(events, null);
+    debugDefaultTargetPlatformOverride = null;
+  });
+
+  Future<void> sendEvent(Object? event) => messenger.handlePlatformMessage(
+        'ux/notifications/events',
+        const StandardMethodCodec().encodeSuccessEnvelope(event),
+        (_) {},
+      );
+
+  // Regression: iOS has no native handler, so activating the broadcast
+  // stream throws MissingPluginException straight to FlutterError.onError.
+  test('iOS does not activate the events channel', () async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+    final eventCalls = <String>[];
+    messenger.setMockMethodCallHandler(events, (call) async {
+      eventCalls.add(call.method);
+      return null;
+    });
+    MethodChannelXNotifications();
+    await pumpEventQueue();
+    expect(eventCalls, isEmpty);
+  });
+
+  test('Android activates the events channel', () async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.android;
+    final eventCalls = <String>[];
+    messenger.setMockMethodCallHandler(events, (call) async {
+      eventCalls.add(call.method);
+      return null;
+    });
+    MethodChannelXNotifications();
+    await pumpEventQueue();
+    expect(eventCalls, contains('listen'));
+  });
+
+  test('show forwards the exact argument map', () async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.android;
+    final n = MethodChannelXNotifications();
+    await n.show(XNotification(
+      id: 'd1:7',
+      title: 'Alice',
+      body: 'hi',
+      threadId: 'd1',
+      data: const {'dialogId': 'd1', 'messageId': '7'},
+    ));
+    final show = calls.firstWhere((c) => c.method == 'show');
+    expect(show.arguments, {
+      'id': 'd1:7',
+      'title': 'Alice',
+      'body': 'hi',
+      'threadId': 'd1',
+      'data': {'dialogId': 'd1', 'messageId': '7'},
+    });
+  });
+
+  test('requestPermission invokes the method and updates authorized', () async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.android;
+    final n = MethodChannelXNotifications();
+    expect(await n.requestPermission(), isTrue);
+    expect(calls.any((c) => c.method == 'requestPermission'), isTrue);
+    expect(n.authorized.value, isTrue);
+  });
+
+  test('cancelByThread and cancelAll invoke their methods', () async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.android;
+    final n = MethodChannelXNotifications();
+    await n.cancelByThread('d1');
+    await n.cancelAll();
+    expect(
+      calls.any((c) =>
+          c.method == 'cancelByThread' &&
+          (c.arguments as Map)['threadId'] == 'd1'),
+      isTrue,
+    );
+    expect(calls.any((c) => c.method == 'cancelAll'), isTrue);
+  });
+
+  test('authorization and tap events reach the Dart side', () async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.android;
+    final n = MethodChannelXNotifications();
+    await pumpEventQueue();
+    final taps = <Map<String, String>>[];
+    n.onTap.listen(taps.add);
+
+    await sendEvent({'type': 'authorization', 'granted': true});
+    await pumpEventQueue();
+    expect(n.authorized.value, isTrue);
+
+    await sendEvent({
+      'type': 'tap',
+      'data': {'dialogId': 'd1', 'messageId': '7'},
+    });
+    await pumpEventQueue();
+    expect(taps, [
+      {'dialogId': 'd1', 'messageId': '7'},
+    ]);
+  });
+}

test/view_padding_test.dart

@@ -0,0 +1,43 @@
+import 'dart:async';
+
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:ux/src/view_padding.dart';
+
+void main() {
+  testWidgets('animated viewPadding advances past _from on subsequent frames', (tester) async {
+    final binding = TestWidgetsFlutterBinding.ensureInitialized();
+    final insets = XInsets.instance;
+
+    addTearDown(tester.view.resetViewPadding);
+
+    // Seed: snap to a known starting padding (no pending animation).
+    tester.view.viewPadding = FakeViewPadding.zero;
+    binding.handleMetricsChanged();
+    await tester.pump();
+    expect(insets.viewPadding.top, 0);
+
+    // Arm a 200ms animation, then change the system padding.
+    unawaited(insets.setSystemUiMode(
+      SystemUiMode.edgeToEdge,
+      animate: const Duration(milliseconds: 200),
+    ));
+    tester.view.viewPadding = const FakeViewPadding(top: 100);
+    binding.handleMetricsChanged();
+
+    // Drive the lerp chain across a handful of frames. Pre-fix, `_start`
+    // was assigned `currentSystemFrameTimeStamp` (raw since-boot) while
+    // the frame-callback `ts` is epoch-adjusted — different time domains
+    // gave `dt` a massively negative value, `clamp` pinned `t = 0`, and
+    // `_current` never moved past `_from`. The expectation below would
+    // fail with `viewPadding.top == 0`.
+    for (var i = 0; i < 4; i++) {
+      await tester.pump(const Duration(milliseconds: 16));
+    }
+    expect(insets.viewPadding.top, greaterThan(0));
+
+    // Drain the animation chain so no transient callback leaks past
+    // teardown.
+    await tester.pump(const Duration(seconds: 1));
+  });
+}

test/window_test.dart

@@ -0,0 +1,63 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:ux/ux.dart';
+
+void main() {
+  final messenger =
+      TestWidgetsFlutterBinding.ensureInitialized().defaultBinaryMessenger;
+  const channel = MethodChannel('ux/window/events');
+
+  final listenCalls = <String>[];
+
+  setUp(() {
+    listenCalls.clear();
+    messenger.setMockMethodCallHandler(channel, (call) async {
+      listenCalls.add(call.method);
+      return null;
+    });
+  });
+
+  tearDown(() {
+    messenger.setMockMethodCallHandler(channel, null);
+    debugDefaultTargetPlatformOverride = null;
+  });
+
+  Future<void> sendEvent(Object? event) => messenger.handlePlatformMessage(
+        'ux/window/events',
+        const StandardMethodCodec().encodeSuccessEnvelope(event),
+        (_) {},
+      );
+
+  // Regression: iOS has no native handler, so activating the broadcast
+  // stream throws MissingPluginException straight to FlutterError.onError.
+  test('iOS does not activate the events channel', () async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+    final w = MethodChannelXWindow();
+    await pumpEventQueue();
+    expect(listenCalls, isEmpty);
+    expect(w.focused.value, isTrue);
+  });
+
+  test('Android activates the events channel', () async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.android;
+    MethodChannelXWindow();
+    await pumpEventQueue();
+    expect(listenCalls, contains('listen'));
+  });
+
+  test('a focus event flips focused', () async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.android;
+    final w = MethodChannelXWindow();
+    await pumpEventQueue();
+    expect(w.focused.value, isTrue);
+
+    await sendEvent({'type': 'focus', 'focused': false});
+    await pumpEventQueue();
+    expect(w.focused.value, isFalse);
+
+    await sendEvent({'type': 'focus', 'focused': true});
+    await pumpEventQueue();
+    expect(w.focused.value, isTrue);
+  });
+}