diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..11c2596
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to the Drum Highway plugin. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow `plugin.json`.
+
+## [Unreleased]
+
+Version 4.1.0 in `plugin.json`.
+
+### Added
+- **Rock Band-style scoring** from a JavaScript port of YARG.Core's drums engine (`assets/engine.js`,
+  LGPL-3.0, see `NOTICE.md`): ±70 ms hit window, multiplier up to x4 (x8 in star power), pro-drums
+  cymbal/tom lanes, accent/ghost dynamics bonus, stars, and star power with fill activation. Driven
+  through `assets/session.js`, which also adds spot-on timing, roll and drum-solo bonuses. The 2D view
+  marks hits / misses from the engine and shows a score HUD when **Score** is on.
+- **Difficulty per player** — Easy, Medium, Hard, Expert, Expert+ (`drums_difficulty_v1`), from the
+  settings panel, the HUD badge or D / Shift+D; Expert drops the double-kick notes. Easier levels, star
+  power, fills and solos come from the drum tab's feedpak 1.20.0 gameplay metadata; without it the song
+  plays Expert (plus Expert+ when the chart has double-kick notes, e.g. a legacy chart with GM 35 kicks),
+  without star power.
+- **Assists** — auto kick / auto cymbals up to a chosen difficulty (played on the drum sound at their own
+  volume), hit-timing presets (Relaxed / Forgiving / Normal / Precision), **Pro cymbals** toggle and an
+  input **Offset** (ms) for audio / MIDI latency.
+- **Timing meter** under the score: the last 24 hits early / late on a ±100 ms bar, their median, and the
+  input offset that would centre them, with an **Apply** button.
+- **Star power without fills**: on charts with star power phrases but no drum fills, press **Enter** or
+  hit the **SP pad** (settings: off, hi-hat pedal, ride bell, splash or china; `drums_sp_pad_v1`) to
+  activate it. With fills, the note that ends a fill activates it, as before.
+- **Results card** at the end of the song (single view, Score on): total score with the bonuses, best
+  score per song and difficulty (`drums.best:<song>|<difficulty>` in `localStorage`), stars, accuracy,
+  notes hit, best streak / full combo and where the points came from.
+- The drum view on a part that isn't drums (no drum tab, arrangement not named Drums / Percussion) shows
+  "This song has no drums" or "Pick the Drums part" and plays / scores nothing, instead of reading guitar
+  notes as drum notes.
+
+### Changed
+- Hit timing: the view draws and scores on a smoothed per-highway clock (interpolated between the
+  player's audio samples, like core's 3D highway), a pad hit is timed when the MIDI message arrived
+  (its timestamp, when the MIDI provider passes one) rather than at the last frame, and the engine runs
+  60 ms behind the frame clock so a hit struck just before a frame is judged at its own time instead of
+  being moved forward to the frame.
+- The input offset applies to the engine's clock as well as to the hits, so a positive offset no longer
+  leaves a late-registered hit facing a note the engine has already missed.
+- MIDI velocity reaches the engine as 0..1 (velocity / 127); velocity 1 used to count as full strength.
+- Auto kick / auto cymbals are timed from the audio clock (mapped to the stems plugin's audio context
+  when it is there), scheduled 100 ms ahead by one forward-only schedule shared by all drum views and
+  cancelled on pause / seek: no more late or doubled auto notes.
+- Splitscreen: kit hits go to the focused drum view if it is on screen, else to the drum view that is,
+  so a hidden main-player drum view no longer swallows them.
+- A scoring file that failed to load is loaded again on the next try (its dead `<script>` element is
+  removed).
+- A drum-tab hit is an accent only when the tab marks it (`a`, feedpak 1.20.0) or, for older tabs, when it
+  has a written velocity of 100 or more; a hit with no velocity is no longer drawn as an accent. A kick
+  marked `x2` is a double kick (GM 35).
+- The "Hits" checkbox is now **Score**.
diff --git a/LICENSE.GPL-3.0 b/LICENSE.GPL-3.0
new file mode 100644
index 0000000..f288702
--- /dev/null
+++ b/LICENSE.GPL-3.0
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, 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
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If 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 convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU 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
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "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 PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM 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 PROGRAM (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 PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state 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 program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program 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 General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.
diff --git a/LICENSE.LGPL-3.0 b/LICENSE.LGPL-3.0
new file mode 100644
index 0000000..153d416
--- /dev/null
+++ b/LICENSE.LGPL-3.0
@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  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 that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU 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 as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
\ No newline at end of file
diff --git a/NOTICE.md b/NOTICE.md
new file mode 100644
index 0000000..de88b1d
--- /dev/null
+++ b/NOTICE.md
@@ -0,0 +1,26 @@
+# Licensing notice for the drums plugin
+
+Most of this plugin is original code under the **MIT** license (see `README.md`). That includes
+`screen.js`, `assets/session.js`, `plugin.json`, the other assets and the tests other than
+`tests/engine.test.js`.
+
+Two files are ports of [YARG.Core](https://github.com/YARC-Official/YARG.Core) and are licensed under the
+**GNU Lesser General Public License v3.0** (full text in [`LICENSE.LGPL-3.0`](LICENSE.LGPL-3.0); the LGPL
+builds on the GNU GPL v3.0, whose text is in [`LICENSE.GPL-3.0`](LICENSE.GPL-3.0)):
+
+| File | Status |
+|------|--------|
+| `assets/engine.js` | LGPL-3.0. JavaScript port, with modifications, of YARG.Core's drums engine (`Engine/Drums/DrumsEngine.cs`, `Engine/Drums/Engines/YargDrumsEngine.cs`, `DrumsEngineParameters.cs`, `DrumsStats.cs`, `Engine/BaseEngine*.cs`, `BaseStats.cs`, `HitWindowSettings.cs`, `Chart/Notes/DrumNote.cs`, `Note.cs`, drum activation flags from `InstrumentDifficultyExtensions.cs`, and defaults from `Game/Presets/EnginePreset*.cs`). It also takes the drum star thresholds from YARG's `DrumsPlayer.cs` (LGPL-3.0). Copyright (c) YARC (YARG) contributors. |
+| `tests/engine.test.js` | LGPL-3.0. Tests for `engine.js`, partly ported from `YARG.Core.UnitTests/Engine/DrumEngineTester.cs` and `DrumsStatsTests.cs`. |
+
+`assets/engine.js` is a standalone, unminified script with no dependencies, shipped as its own file and
+loaded at runtime. `screen.js` and `assets/session.js` only use it through its public API
+(`window.DrumsEngine` / `require('./engine.js')`), so they remain separate MIT works that use the Library
+as described in LGPL-3.0 section 4 ("Combined Works"). You may replace `assets/engine.js` with a modified
+version. A modified `assets/engine.js` that you distribute is conveyed under LGPL-3.0 or, as LGPL-3.0
+section 2(b) allows, under the GPL-3.0 (without the LGPL's additional permissions), with its source
+available either way. Combining an LGPL-3.0 file with MIT code this way is permitted by both licenses, and
+both are compatible with feedBack's AGPL-3.0.
+
+The header of `assets/engine.js` lists every behaviour that deviates from YARG ("Deviations from YARG").
+The scoring look and feel imitates rhythm-game drum tracks but uses no artwork, fonts or logos from them.
diff --git a/README.md b/README.md
index baa3cd9..626dbfc 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,9 @@ A plugin for [Slopsmith](https://github.com/got-feedback/feedback) that replaces
 - **MIDI drum pad input** — connect any MIDI drum pad, electronic kit, or controller via Web MIDI API
 - **Custom MIDI mapping** — "Learn" mode to assign any MIDI note to any lane, for non-standard drum pads
 - **Built-in drum sounds** — WebAudioFont-powered GM drum kit playback on MIDI hit
-- **Accuracy scoring** — hit detection with tight +/-50ms timing window, accuracy %, streak counter
+- **Rock Band-style scoring** — score, multiplier, streak, stars and star power from a port of the YARG drums engine (`assets/engine.js`). See [Scoring](#scoring).
+- **Difficulty** — Easy, Medium, Hard, Expert or Expert+ per player (browser), changeable mid-song. See [Difficulty](#difficulty).
+- **Assists** — auto kick, auto cymbals (each up to a chosen difficulty) and hit-timing presets. See [Assists](#assists).
 - **Inline settings** — MIDI device, volume, channel filter, lane labels, hit detection, and mapping table
 
 ## Drum Lanes
@@ -32,6 +34,85 @@ A plugin for [Slopsmith](https://github.com/got-feedback/feedback) that replaces
 | Ride | Ri | 51, 59 | White | Diamond |
 | Kick | Ki | 35, 36 | Red | Full-width bar |
 
+## Scoring
+
+Turn on **Score** in the settings panel (gear) to see the scoring HUD: multiplier, score, streak, stars
+and the star power meter. Hit notes turn green, missed notes grey, and a pad hit on an empty lane flashes it
+red.
+
+Scoring is a JavaScript port of YARG.Core's drums engine (`assets/engine.js`, LGPL-3.0 — see
+[License](#license)), used through `assets/session.js`:
+
+- **Hit window** ±70 ms (see [Assists](#assists) for wider ones); one pad hit hits at most one note.
+- **Multiplier** grows every 10 notes up to x4, doubled during star power (x8). 60 points per note (pro
+  drums), plus a dynamics bonus for hitting an accent hard or a ghost note soft (needs a velocity-sensitive
+  kit). Pro drums: a cymbal and the tom of the same colour are different notes; with **Pro cymbals** off
+  either one hits that colour's notes.
+- **Star power** — notes in a star power phrase are drawn silver-white; hitting every note of a phrase fills
+  a quarter of the meter. With half a meter, the chart's **fills** are marked green: the hit that ends the
+  fill activates star power. A chart with star power phrases but no fills activates it by hand: press
+  **Enter** (drum view focused) or hit the **SP pad** chosen in the settings (`drums_sp_pad_v1`: off,
+  hi-hat pedal 44, ride bell 53, splash 55 or china 52; that pad then activates star power instead of
+  scoring as a note). The HUD says which when star power is ready.
+- **Bonuses** (shown in the score) — +10 x multiplier for a hit within 25 ms, extra points for snare / tom
+  rolls, and a drum-solo bonus (100 per note hit, doubled for a perfect solo) with a live percentage during
+  a solo.
+- **Offset** (ms) — subtracted from the time of every hit and from the engine's clock; raise it if your
+  hits register late (audio or MIDI latency). The default is 0. The **timing meter** under the score
+  shows the last 24 hits early (blue) / late (orange) on a ±100 ms bar and, after 6 hits that are off by
+  10 ms or more, the offset that would centre them: click **Apply** to use it.
+- **Hit timing** — the view runs a smoothed clock (interpolated between the player's audio samples), a pad
+  hit is timed when its MIDI message arrived (when the MIDI provider passes the message's timestamp)
+  rather than at the last frame, and the engine trails the frame clock by 60 ms so a hit struck just
+  before a frame keeps its own time.
+- **Results card** — when the song ends (single view, Score on): total score with the bonuses, best score
+  per song and difficulty, stars, accuracy, notes hit, best streak and where the points came from.
+- Seeking (or a loop jumping back) restarts scoring from the new position; skipped notes aren't misses.
+
+The scoring files load on first use from core's plugin assets route (`/api/plugins/drums/assets/`). Until
+they have loaded the view shows the chart as it is.
+
+### Difficulty
+
+Each player picks **Easy**, **Medium**, **Hard**, **Expert** or **Expert+**, stored per browser
+(`localStorage` key `drums_difficulty_v1`, default Expert), so in splitscreen / multiplayer every player
+keeps their own. Change it in the settings panel, by clicking the difficulty badge (top-left of the lanes),
+or with **D** (harder) / **Shift+D** (easier) while the view is focused.
+
+- **Expert+** is the drum part as charted, double kicks included; **Expert** drops the double-kick notes
+  (`x2`). **Easy / Medium / Hard** come from the chart's own easier levels; the badge says **AUTO** when a
+  level was reduced by software rather than hand-charted.
+- A level the chart doesn't have is greyed out with the reason; a song without your saved level plays
+  Expert (the badge is dimmed) and your choice is kept for the next song.
+- Changing difficulty mid-song rebuilds the chart from the current position, like a seek.
+
+### Where star power, fills and levels come from
+
+They are part of the song's drum tab (`drum_tab.json`, feedpak 1.20.0 "drum gameplay metadata"): per-hit
+`a` (accent) and `x2` (double kick) flags, `star_power` / `fills` / `solos` as `{start_time, end_time}`
+ranges, and `levels.easy|medium|hard` with their own `hits` and a `generated` marker. feedBack's Rock Band /
+Clone Hero / YARG chart importer writes them, and core streams them to the plugin with the tab
+(`bundle.drumTab`). A tab without them — an older tab, a core that doesn't stream them yet, or drums encoded
+as guitar notes — plays **Expert, without star power** (plus **Expert+** when the chart has double-kick
+notes: a legacy chart's GM 35 kicks count); everything else works the same.
+
+On a part that isn't drums (no drum tab and an arrangement not named Drums / Percussion, e.g. a
+splitscreen panel left on the Drum Highway on a song without drums) the view says so and plays / scores
+nothing.
+
+### Assists
+
+- **Auto kick / Auto cymbals** (`drums_auto_kick_v1`, `drums_auto_cymbals_v1`): `Off`, `Easy only`,
+  `Easy – Medium`, `Easy – Hard` or `Every difficulty` — the assist is on at that difficulty and the ones
+  below it. Those notes are left out of scoring, marked as played when they reach the now line, and pad hits
+  on them are ignored. Cymbals = the chart's hi-hat, ride and crash notes. They are **played on the drum
+  sound** (scheduled 100 ms ahead on the audio clock, mapped to the stems plugin's audio context when it is
+  there; a pause or seek cancels what hasn't played) so muting the drum stem leaves no holes, at their own
+  **Auto vol** (`drums_auto_volume_v1`, default 80%), so pads can stay silent when the kit module makes the
+  sound.
+- **Timing** (`drums_timing_v1`): Relaxed ±130 ms, Forgiving ±100 ms, Normal ±70 ms (YARG's default),
+  Precision (YARG's dynamic window that tightens on fast notes).
+
 ## Requirements
 
 - **Chrome or Edge** for MIDI drum pad input (Firefox does not support Web MIDI)
@@ -71,6 +152,15 @@ Different drum pads send different MIDI note numbers. Use the "Learn" mode in se
 
 Click "Reset Map" to return to standard GM mapping.
 
+## Development
+
+Tests run with plain Node (the org CI runs each `tests/*.test.js`): `node tests/engine.test.js`,
+`node tests/session.test.js`, `node tests/screen.test.js`.
+
 ## License
 
-MIT
+MIT, except `assets/engine.js` and `tests/engine.test.js`: they are ports of
+[YARG.Core](https://github.com/YARC-Official/YARG.Core) and are licensed under the **LGPL-3.0**
+(`LICENSE.LGPL-3.0`, with the GPL-3.0 it builds on in `LICENSE.GPL-3.0`; LGPL-3.0 section 2(b) also allows
+conveying a modified copy under the GPL-3.0). The engine is a separate,
+replaceable file that the MIT code only calls through its public API. Details in [NOTICE.md](NOTICE.md).
diff --git a/assets/engine.js b/assets/engine.js
new file mode 100644
index 0000000..4c6aeb8
--- /dev/null
+++ b/assets/engine.js
@@ -0,0 +1,1081 @@
+/*
+ * engine.js: Rock Band-style drums hit detection and scoring for the feedBack drums plugin.
+ *
+ * Ported from YARG.Core (https://github.com/YARC-Official/YARG.Core):
+ *   YARG.Core/Engine/Drums/DrumsEngine.cs
+ *   YARG.Core/Engine/Drums/Engines/YargDrumsEngine.cs
+ *   YARG.Core/Engine/Drums/DrumsEngineParameters.cs
+ *   YARG.Core/Engine/Drums/DrumsStats.cs
+ *   YARG.Core/Engine/BaseEngine.cs, BaseEngine.Generic.cs, BaseEngineParameters.cs, BaseStats.cs
+ *   YARG.Core/Engine/HitWindowSettings.cs
+ *   YARG.Core/Chart/Notes/DrumNote.cs, YARG.Core/Chart/Notes/Note.cs
+ *   YARG.Core/Chart/Tracks/InstrumentDifficultyExtensions.cs (SetDrumActivationFlags)
+ *   YARG.Core/Chart/Events/WaitCountdown.cs (MIN_SECONDS)
+ *   YARG.Core/Game/Presets/EnginePreset.Instruments.cs and EnginePreset.Defaults.cs (default parameters)
+ * and from the YARG game (https://github.com/YARC-Official/YARG, also LGPL-3.0):
+ *   Assets/Script/Gameplay/Player/DrumsPlayer.cs (drum star score thresholds)
+ *
+ * Copyright (c) YARC (YARG) contributors
+ * Licensed under the GNU Lesser General Public License v3.0
+ * (see https://github.com/YARC-Official/YARG.Core/blob/master/LICENSE, and LICENSE.LGPL-3.0 at the plugin root; LGPL-3.0 builds on the GPL-3.0 in LICENSE.GPL-3.0).
+ *
+ * Ported and modified to JavaScript for the feedBack drums plugin. This file is a derivative work of the
+ * above files and stays under LGPL-3.0. The rest of the plugin is MIT (see NOTICE.md).
+ * Modifications: rewritten as a dependency-free JavaScript module, uses an immediate hit()/update() API
+ * in place of YARG's input queue, works in seconds/measures in place of chart ticks, and decodes feedBack
+ * wire notes (General MIDI drum numbers). The deviations are listed below.
+ *
+ * -------------------------------------------------------------------------------------------------
+ * Rules ported from YARG (defaults = EnginePreset.Default):
+ *  - Hit window: 140 ms total, front/back ratio 1.0, so it runs from 70 ms early to 70 ms late. It is not
+ *    dynamic by default. YARG's "Dark YARG" dynamic window is ported (params.hitWindow.isDynamic) along with
+ *    the "Precision" preset (DrumsEngine.PRESETS.precision). The window scales with params.songSpeed.
+ *    A note can still be hit exactly at the back edge. It is missed once time > t + backEnd.
+ *  - Matching (YargDrumsEngine.CheckForNoteHit): scan from the oldest unresolved chord forward while the
+ *    chords are inside the hit window, and hit the first note whose lane equals the input lane. Every note
+ *    in a chord is hit separately. Hitting a later chord counts every unresolved note in earlier chords as
+ *    a miss (SkipPreviousNotes). One input hits at most one note.
+ *  - Lanes (FourLaneDrumPad): with pro drums, a yellow, blue or green cymbal is a separate lane from the tom
+ *    of the same colour, so a cymbal hit on a tom note does not hit it and is an overhit. Non-pro drums map
+ *    cymbal inputs onto the drum lanes. The engine has no cymbal/tom fallback.
+ *  - Overhit (DrumsEngine.Overhit): a pad hit that hits no note resets the combo, adds 1 to overhits and
+ *    fails the star power phrase in progress (unless the current note starts the phrase). It does not
+ *    change the score. An overhit is ignored before the first note is resolved, after the last note, and
+ *    during a WaitCountdown (a gap of 9 s or more between notes).
+ *  - Combo: +1 for each note hit, so a chord adds 1 per note. Multiplier = min(floor(combo / 10) + 1, 4),
+ *    doubled while star power is active (up to 8x). The multiplier updates before the note is scored, so
+ *    the 10th note already scores at 2x.
+ *  - Score: 60 points per note with pro drums, 50 without, times the multiplier. Dynamics: an accent or ghost
+ *    note hit with the right velocity scores +25 x multiplier (ApplyVelocity, threshold 0.35, 1.5 s window
+ *    for relative velocity). This only applies when hit() gets a velocity.
+ *  - Star power: hitting every note of a phrase awards a quarter bar (2 measures). The bar holds 8 measures.
+ *    Activation needs half a bar (4 measures). While active, the bar drains 1 measure per measure of song
+ *    time, so a full bar lasts 8 measures. A phrase hit while star power is active adds to the bar and
+ *    pushes the end time back (unless params.noStarPowerOverlap is set). A miss in a phrase fails it.
+ *  - Drum fill activation (SetDrumActivationFlags + DrumsEngine.HitNote): the activation chord of a fill
+ *    gets the "activator" flag. With YARG's default RightmostNote type, only the rightmost lane of that
+ *    chord gets it. Hitting the activator when the bar is at least half full activates star power.
+ *    If the player lets the activator pass while star power could activate, it is auto-hit: it scores and
+ *    adds to the combo but does not activate star power and fires no 'hit' event.
+ *  - Stars: BaseScore = the score of a full combo with no star power and no dynamics bonus, using the same
+ *    pre-increment multiplier as CalculateChartScores. Thresholds come from DrumsPlayer.cs:
+ *    [0.06, 0.12, 0.2, 0.45, 0.75, 1.09] x BaseScore for 1-5 stars and gold.
+ *
+ * Deviations from YARG:
+ *  1. Time model: YARG runs a queued-input simulation in chart ticks. This engine uses seconds and a
+ *     time->measure map built from opts.measures (barline times), opts.beats (numbers or {time, measure}
+ *     objects, where a measure >= 0 marks a downbeat), or opts.tempo ([{t, bpm}] plus opts.beatsPerMeasure,
+ *     default 4). The fallback is 120 BPM in 4/4, so 1 measure = 2 s. Star power is tracked as fractional
+ *     measures rather than integer measure ticks, so there is no tick rounding.
+ *  2. hit() and update() run immediately. Times earlier than the engine clock are clamped forward, as
+ *     YARG's QueueInput does. Misses and the star power end are processed in time order inside each call.
+ *  3. Not ported: trill/tremolo lanes, kick lanes and their lane leniency, BRE/coda, solos and solo bonus,
+ *     band/unison bonus, revives, the Elite and 5-lane modes, bots, and replays. The wildcard pad is not
+ *     reachable from this API.
+ *  4. Chart import: notes less than 1 ms apart form a chord (YARG uses identical ticks). A second note on
+ *     the same lane in one chord is dropped, like DrumNote.AddChildNote. With proDrums:false a yellow tom
+ *     and a yellow cymbal in one chord collapse into one note, and noteState() of the dropped id reports
+ *     the surviving note. 35 (kick 2x) is kept unless opts.kick2x === false, rather than YARG's
+ *     Expert+ difficulty switch.
+ *  5. Star power phrase membership: start - 0.1 ms <= chord.t < end - 0.1 ms (half-open, like tick ranges).
+ *     Phrases that contain no notes are left out of phrasesTotal.
+ *  6. Phrase failure is tracked per phrase. Missing any note of a phrase, including a child note of a
+ *     chord, fails the whole phrase. YARG's StripStarPower only strips the child note in that case, which
+ *     looks like a bug.
+ *  7. Activation window -> activator chord: the last chord with start - 0.1 ms <= t <= end + 0.1 ms
+ *     (Rock Band: the fill ends on the activation chord). If no chord falls in the window, YARG's rule is
+ *     used: the first chord at or after `end`. Without opts.activation, eng.activateStarPower() works
+ *     whenever the bar is half full. With fills, manual activation is off unless opts.manualActivation is
+ *     true. YARG drums have no manual activation; it auto-generates fills.
+ *  8. Hitting a pad that matches a chord note already hit is consumed with no effect, as in YARG. This
+ *     engine returns {type:'ignored'} and, unlike YARG, does not run the velocity bonus again.
+ *  9. Velocity comparison (ApplyVelocity): the comparison note is looked up across all notes of earlier
+ *     chords on the same lane, not only parent notes. Velocities above 1 are read as MIDI 0-127.
+ * 10. Reporting: getState().notesMissed counts notes actually missed so far (YARG reports
+ *     TotalNotes - NotesHit). accuracy = hit / (hit + missed) so far, and percent = YARG's
+ *     NotesHit / TotalNotes. maxMultiplier is the cap (params.maxMultiplier) and peakMultiplier is the
+ *     highest multiplier reached. 'combo-break' fires only when a combo above 0 resets.
+ * -------------------------------------------------------------------------------------------------
+ */
+(function (root, factory) {
+    'use strict';
+    const api = factory();
+    if (typeof module === 'object' && module && module.exports) module.exports = api;
+    if (typeof window !== 'undefined' && window) window.DrumsEngine = api;
+    else if (typeof module !== 'object' && root) root.DrumsEngine = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+    'use strict';
+
+    // ── Constants ───────────────────────────────────────────────────────────────
+
+    // Plugin-facing pad colours (shared with screen.js).
+    const PAD = Object.freeze({ KICK: 0, RED: 1, YELLOW: 2, BLUE: 3, GREEN: 4 });
+
+    // YARG FourLaneDrumPad (DrumNote.cs). These are the engine's internal "lanes".
+    const LANE = Object.freeze({
+        KICK: 0, RED: 1, YELLOW_DRUM: 2, BLUE_DRUM: 3, GREEN_DRUM: 4,
+        YELLOW_CYMBAL: 5, BLUE_CYMBAL: 6, GREEN_CYMBAL: 7,
+    });
+
+    // BaseEngine.cs
+    const POINTS_PER_NOTE = 50;
+    const POINTS_PER_PRO_NOTE = POINTS_PER_NOTE + 10;
+    // YargDrumsEngine.CheckForNoteHit: velocityBonus = POINTS_PER_NOTE / 2
+    const VELOCITY_BONUS = POINTS_PER_NOTE / 2;
+    // BaseEngine.UpdateMultiplier: (Combo / 10) + 1
+    const NOTES_PER_MULTIPLIER = 10;
+
+    const CHORD_EPS = 0.001;   // notes closer than 1 ms form a chord
+    const PHRASE_EPS = 0.0001; // tolerance for phrase/window boundaries
+    const SP_EPS = 1e-9;
+
+    // General MIDI drum number -> pad/cymbal (the drums wire encoding is midi = s*24 + f).
+    const MIDI_MAP = Object.freeze({
+        36: { pad: PAD.KICK, cymbal: false },
+        35: { pad: PAD.KICK, cymbal: false, kick2x: true },
+        38: { pad: PAD.RED, cymbal: false },     // acoustic snare
+        37: { pad: PAD.RED, cymbal: false },     // side stick / cross-stick
+        40: { pad: PAD.RED, cymbal: false },     // electric snare
+        42: { pad: PAD.YELLOW, cymbal: true },   // closed hi-hat
+        46: { pad: PAD.YELLOW, cymbal: true },   // open hi-hat
+        44: { pad: PAD.YELLOW, cymbal: true, hatPedal: true }, // pedal hi-hat (opt-in)
+        48: { pad: PAD.YELLOW, cymbal: false },  // hi-mid tom
+        50: { pad: PAD.YELLOW, cymbal: false },  // high tom
+        45: { pad: PAD.BLUE, cymbal: false },    // low tom
+        47: { pad: PAD.BLUE, cymbal: false },    // low-mid tom
+        41: { pad: PAD.GREEN, cymbal: false },   // low floor tom
+        43: { pad: PAD.GREEN, cymbal: false },   // high floor tom
+        58: { pad: PAD.GREEN, cymbal: false },   // vibraslap (some kits send it from the floor tom)
+        51: { pad: PAD.BLUE, cymbal: true },     // ride
+        53: { pad: PAD.BLUE, cymbal: true },     // ride bell
+        59: { pad: PAD.BLUE, cymbal: true },     // ride 2
+        49: { pad: PAD.GREEN, cymbal: true },    // crash
+        57: { pad: PAD.GREEN, cymbal: true },    // crash 2
+        55: { pad: PAD.GREEN, cymbal: true },    // splash
+        52: { pad: PAD.GREEN, cymbal: true },    // china
+    });
+
+    // ── Default parameters ─────────────────────────────────────────────────────
+
+    /**
+     * YARG's default drum engine parameters. Sources:
+     *  - hitWindow: EnginePreset.Instruments.cs DrumsPreset.HitWindow (MaxWindow 0.14, MinWindow 0.14,
+     *    IsDynamic false, FrontToBackRatio 1.0, LaneAutohitWindow 0.160) plus HitWindowPreset defaults
+     *    (DynamicScale 1.0, DynamicSlope 0.93, DynamicGamma 1.5, LaneProximityProtectionWindow 0.080).
+     *  - maxMultiplier: EnginePreset.DEFAULT_MAX_MULTIPLIER = 4.
+     *  - velocityThreshold 0.35, situationalVelocityWindow 1.5: DrumsEngineParameters constructor.
+     *  - noStarPowerOverlap false: DrumsPreset.NoStarPowerOverlap.
+     *  - starPowerMeasures 8: BaseEngine.STAR_POWER_MAX_MEASURES (TicksPerFullSpBar = 8 measures).
+     *    A phrase gives TicksPerQuarterSpBar (2 measures), and activation needs TicksPerHalfSpBar (4 measures).
+     *  - starMultiplierThresholds: YARG DrumsPlayer.cs StarMultiplierThresholds.
+     *  - waitCountdownSeconds 9: WaitCountdown.MIN_SECONDS.
+     *  - activationType 'rightmost': YargProfile default StarPowerActivationType.RightmostNote.
+     *  - pointsPerNote/pointsPerProNote/velocityBonus/notesPerMultiplier: BaseEngine.cs constants.
+     */
+    function defaultParams() {
+        return {
+            hitWindow: {
+                maxWindow: 0.14,
+                minWindow: 0.14,
+                isDynamic: false,
+                frontToBackRatio: 1.0,
+                dynamicScale: 1.0,
+                dynamicSlope: 0.93,
+                dynamicGamma: 1.5,
+                laneAutohitWindow: 0.160,          // unused (lanes not ported); kept for parity
+                laneProximityProtectionWindow: 0.080, // unused (lanes not ported); kept for parity
+            },
+            songSpeed: 1.0,
+            maxMultiplier: 4,
+            notesPerMultiplier: NOTES_PER_MULTIPLIER,
+            pointsPerNote: POINTS_PER_NOTE,
+            pointsPerProNote: POINTS_PER_PRO_NOTE,
+            velocityBonus: VELOCITY_BONUS,
+            velocityThreshold: 0.35,
+            situationalVelocityWindow: 1.5,
+            noStarPowerOverlap: false,
+            starPowerMeasures: 8,
+            starMultiplierThresholds: [0.06, 0.12, 0.2, 0.45, 0.75, 1.09],
+            waitCountdownSeconds: 9,
+            activationType: 'rightmost', // 'rightmost' (YARG default) | 'all' (old YARG style)
+        };
+    }
+
+    // EnginePreset.Defaults.cs: overrides applied by YARG's built-in presets for drums.
+    const PRESETS = Object.freeze({
+        default: Object.freeze({}),
+        casual: Object.freeze({ hitWindow: { laneAutohitWindow: 0.200, laneProximityProtectionWindow: 0.100 } }),
+        precision: Object.freeze({
+            hitWindow: {
+                maxWindow: 0.13, minWindow: 0.05, isDynamic: true,
+                dynamicScale: 1, dynamicSlope: 0.60615, dynamicGamma: 2,
+                laneAutohitWindow: 0.160, laneProximityProtectionWindow: 0.080,
+            },
+        }),
+    });
+
+    function clamp(v, lo, hi) { return v < lo ? lo : (v > hi ? hi : v); }
+
+    function mergeParams(over) {
+        const p = defaultParams();
+        if (!over || typeof over !== 'object') return finalizeParams(p);
+        for (const k of Object.keys(over)) {
+            if (k === 'hitWindow' && over.hitWindow && typeof over.hitWindow === 'object') {
+                Object.assign(p.hitWindow, over.hitWindow);
+            } else if (over[k] !== undefined) {
+                p[k] = over[k];
+            }
+        }
+        return finalizeParams(p);
+    }
+
+    // HitWindowSettings constructor normalisation.
+    function finalizeParams(p) {
+        const hw = p.hitWindow;
+        if (hw.maxWindow < hw.minWindow) { const t = hw.maxWindow; hw.maxWindow = hw.minWindow; hw.minWindow = t; }
+        hw.dynamicSlope = clamp(hw.dynamicSlope, 0, 1);
+        hw.dynamicScale = clamp(hw.dynamicScale, 0.3, 3);
+        hw.dynamicGamma = clamp(hw.dynamicGamma, 0.1, 10);
+        if (!(p.songSpeed > 0)) p.songSpeed = 1;
+        return p;
+    }
+
+    // HitWindowSettings.CalculateHitWindow (+ Dark_Yarg_Impl)
+    function calculateHitWindow(hw, averageTimeDistance) {
+        if (!hw.isDynamic) return hw.maxWindow;
+        const x = averageTimeDistance * 1000;
+        const minMs = hw.minWindow * 1000;
+        const maxMs = hw.maxWindow * 1000;
+        const maxMultiScale = maxMs * hw.dynamicScale;
+        const gammaPow = Math.pow(x / maxMultiScale, hw.dynamicGamma);
+        const minMultiSlope = minMs * hw.dynamicSlope;
+        const result = (gammaPow * (maxMs - minMultiSlope) + minMultiSlope) / 1000;
+        return clamp(result, hw.minWindow, hw.maxWindow);
+    }
+    // HitWindowSettings.GetFrontEnd / GetBackEnd (Scale = song speed)
+    function frontEnd(hw, full, scale) { return -(Math.abs(full / 2) * hw.frontToBackRatio) * scale; }
+    function backEnd(hw, full, scale) { return Math.abs(full / 2) * (2 - hw.frontToBackRatio) * scale; }
+
+    // ── Chart decoding ─────────────────────────────────────────────────────────
+
+    function padFromMidi(midi, opts) {
+        const m = MIDI_MAP[midi];
+        if (!m) return null;
+        if (m.hatPedal && !(opts && opts.includeHatPedal)) return null;
+        return { pad: m.pad, cymbal: m.cymbal };
+    }
+
+    function wireMidi(n) {
+        if (n.midi != null && Number.isFinite(+n.midi)) return +n.midi;
+        return ((n.s | 0) * 24) + (n.f | 0);
+    }
+
+    /**
+     * Decode drums wire notes ({t, s, f, ac, mt}) into a drum chart.
+     * opts.kick2x (default true): keep 35 (expert+ double bass).
+     * opts.includeHatPedal (default false): keep 44 (pedal hi-hat) as a yellow cymbal.
+     */
+    function decodeNotes(wireNotes, opts) {
+        opts = opts || {};
+        const raw = [];
+        const list = Array.isArray(wireNotes) ? wireNotes : [];
+        for (let i = 0; i < list.length; i++) {
+            const n = list[i];
+            if (!n || typeof n !== 'object') continue;
+            const t = +n.t;
+            if (!Number.isFinite(t)) continue;
+            const midi = wireMidi(n);
+            const m = MIDI_MAP[midi];
+            if (!m) continue;
+            if (m.hatPedal && !opts.includeHatPedal) continue;
+            if (m.kick2x && opts.kick2x === false) continue;
+            raw.push({
+                t,
+                pad: m.pad,
+                cymbal: !!m.cymbal,
+                kick2x: !!m.kick2x,
+                dyn: n.ac ? 'accent' : (n.mt ? 'ghost' : null),
+                midi,
+                _order: i,
+            });
+        }
+        raw.sort((a, b) => (a.t - b.t) || (a._order - b._order));
+
+        const notes = [];
+        const chords = [];
+        let cur = null;
+        for (const r of raw) {
+            if (!cur || r.t - cur.t > CHORD_EPS) {
+                cur = { t: r.t, notes: [] };
+                chords.push(cur);
+            } else if (cur.notes.some(x => x.pad === r.pad && x.cymbal === r.cymbal)) {
+                continue; // DrumNote.AddChildNote ignores a duplicate pad in a chord
+            }
+            delete r._order;
+            r.id = notes.length;
+            r.chord = chords.length - 1;
+            notes.push(r);
+            cur.notes.push(r);
+        }
+        return { notes, chords };
+    }
+
+    function groupNotes(notes) {
+        const sorted = notes.slice().sort((a, b) => a.t - b.t);
+        const chords = [];
+        let cur = null;
+        for (const n of sorted) {
+            if (!cur || n.t - cur.t > CHORD_EPS) { cur = { t: n.t, notes: [] }; chords.push(cur); }
+            cur.notes.push(n);
+        }
+        return chords;
+    }
+
+    // Lane for a pad/cymbal pair (ConvertInputToPad). Pro drums keep cymbals separate on Y/B/G.
+    function laneFor(pad, cymbal, proDrums) {
+        if (proDrums !== false && cymbal) {
+            if (pad === PAD.YELLOW) return LANE.YELLOW_CYMBAL;
+            if (pad === PAD.BLUE) return LANE.BLUE_CYMBAL;
+            if (pad === PAD.GREEN) return LANE.GREEN_CYMBAL;
+        }
+        return pad; // KICK/RED/drum lanes share numbers with PAD
+    }
+
+    // ── Time -> measure map (stands in for YARG's SyncTrack measure ticks) ─────
+
+    function buildMeasureMap(opts) {
+        const bpmDefault = 120;
+        const bpmPerMeasure = (opts && opts.beatsPerMeasure > 0) ? opts.beatsPerMeasure : 4;
+        let times = [];
+        let pos = [];
+        let slopeBefore = null;
+        let slopeAfter = null;
+
+        const pushKnot = (t, p) => {
+            if (!Number.isFinite(t) || !Number.isFinite(p)) return;
+            if (times.length && t <= times[times.length - 1]) return; // keep strictly increasing
+            times.push(t); pos.push(p);
+        };
+
+        if (opts && Array.isArray(opts.measures) && opts.measures.length) {
+            const ms = opts.measures.map(Number).filter(Number.isFinite).sort((a, b) => a - b);
+            ms.forEach((t, i) => pushKnot(t, i));
+        } else if (opts && Array.isArray(opts.beats) && opts.beats.length) {
+            const beats = opts.beats;
+            const isObj = typeof beats[0] === 'object' && beats[0] !== null;
+            if (isObj) {
+                const bt = beats.map(b => +(b.time != null ? b.time : b.t)).filter(Number.isFinite);
+                const down = beats.filter(b => b && b.measure != null && +b.measure >= 0)
+                    .map(b => +(b.time != null ? b.time : b.t)).filter(Number.isFinite).sort((a, b) => a - b);
+                if (down.length >= 2) down.forEach((t, i) => pushKnot(t, i));
+                else bt.sort((a, b) => a - b).forEach((t, i) => pushKnot(t, i / bpmPerMeasure));
+            } else {
+                beats.map(Number).filter(Number.isFinite).sort((a, b) => a - b)
+                    .forEach((t, i) => pushKnot(t, i / bpmPerMeasure));
+            }
+        } else if (opts && Array.isArray(opts.tempo) && opts.tempo.length) {
+            const tempos = opts.tempo
+                .map(x => ({ t: +x.t, bpm: +x.bpm }))
+                .filter(x => Number.isFinite(x.t) && x.bpm > 0)
+                .sort((a, b) => a.t - b.t);
+            let p = 0;
+            for (let i = 0; i < tempos.length; i++) {
+                if (i > 0) p += (tempos[i].t - tempos[i - 1].t) * tempos[i - 1].bpm / 60 / bpmPerMeasure;
+                pushKnot(tempos[i].t, p);
+            }
+            if (tempos.length) {
+                slopeBefore = tempos[0].bpm / 60 / bpmPerMeasure;
+                slopeAfter = tempos[tempos.length - 1].bpm / 60 / bpmPerMeasure;
+            }
+        }
+
+        const fallbackSlope = bpmDefault / 60 / bpmPerMeasure; // 0.5 measures/s at 120 BPM 4/4
+        if (times.length === 0) { times = [0]; pos = [0]; }
+        if (times.length >= 2) {
+            const n = times.length;
+            if (slopeBefore == null) slopeBefore = (pos[1] - pos[0]) / (times[1] - times[0]);
+            if (slopeAfter == null) slopeAfter = (pos[n - 1] - pos[n - 2]) / (times[n - 1] - times[n - 2]);
+        }
+        if (!(slopeBefore > 0)) slopeBefore = fallbackSlope;
+        if (!(slopeAfter > 0)) slopeAfter = fallbackSlope;
+
+        function upper(arr, v) { // first index with arr[i] > v
+            let lo = 0, hi = arr.length;
+            while (lo < hi) { const mid = (lo + hi) >> 1; if (arr[mid] > v) hi = mid; else lo = mid + 1; }
+            return lo;
+        }
+        function measureAt(t) {
+            const n = times.length;
+            if (t <= times[0]) return pos[0] - (times[0] - t) * slopeBefore;
+            if (t >= times[n - 1]) return pos[n - 1] + (t - times[n - 1]) * slopeAfter;
+            const i = upper(times, t) - 1;
+            return pos[i] + (t - times[i]) * (pos[i + 1] - pos[i]) / (times[i + 1] - times[i]);
+        }
+        function timeAtMeasure(m) {
+            const n = pos.length;
+            if (m <= pos[0]) return times[0] - (pos[0] - m) / slopeBefore;
+            if (m >= pos[n - 1]) return times[n - 1] + (m - pos[n - 1]) / slopeAfter;
+            const i = upper(pos, m) - 1;
+            return times[i] + (m - pos[i]) * (times[i + 1] - times[i]) / (pos[i + 1] - pos[i]);
+        }
+        return { measureAt, timeAtMeasure };
+    }
+
+    // ── Engine ──────────────────────────────────────────────────────────────────
+
+    const EVENTS = ['hit', 'miss', 'overhit', 'combo-break', 'multiplier', 'sp-phrase', 'sp-phrase-fail',
+        'sp-ready', 'sp-activate', 'sp-end'];
+
+    function Engine(chart, opts) {
+        opts = opts || {};
+        if (Array.isArray(chart)) chart = decodeNotes(chart, opts);
+        chart = chart || { notes: [], chords: [] };
+        this.opts = opts;
+        this.params = mergeParams(opts.params);
+        this.proDrums = opts.proDrums !== false;
+        this._tempo = buildMeasureMap(opts);
+        this._listeners = Object.create(null);
+
+        const p = this.params;
+        const hw = p.hitWindow;
+        const srcChords = Array.isArray(chart.chords) && chart.chords.length
+            ? chart.chords.slice().sort((a, b) => a.t - b.t)
+            : groupNotes(Array.isArray(chart.notes) ? chart.notes : []);
+
+        // Build engine chords (YARG parent note + child notes).
+        this.chords = [];
+        this._byId = new Map();
+        this._alias = new Map();
+        let autoId = 0;
+        for (const sc of srcChords) {
+            if (!sc || !Array.isArray(sc.notes) || !sc.notes.length) continue;
+            const t = Number.isFinite(+sc.t) ? +sc.t : +sc.notes[0].t;
+            const ec = { index: this.chords.length, t, notes: [], phrase: null, front: 0, back: 0 };
+            for (const sn of sc.notes) {
+                const id = sn.id != null ? sn.id : ('n' + (autoId++));
+                const pad = sn.pad | 0;
+                if (pad < 0 || pad > 4) continue;
+                const lane = laneFor(pad, !!sn.cymbal, this.proDrums);
+                const dup = ec.notes.find(x => x.lane === lane);
+                if (dup) { this._alias.set(id, dup.id); continue; }
+                const en = {
+                    id, src: sn, lane, pad, cymbal: !!sn.cymbal,
+                    dyn: sn.dyn === 'accent' || sn.dyn === 'ghost' ? sn.dyn : null,
+                    chord: ec, activator: false,
+                    hit: false, missed: false, autoHit: false,
+                    hitTime: null, offset: null, hitVelocity: null, bonus: false,
+                };
+                ec.notes.push(en);
+                this._byId.set(id, en);
+            }
+            if (ec.notes.length) this.chords.push(ec);
+        }
+
+        // Hit window per chord (GetAverageNoteDistance + CalculateHitWindow).
+        const ch = this.chords;
+        for (let i = 0; i < ch.length; i++) {
+            const c = ch[i];
+            const currentToNext = i + 1 < ch.length ? (ch[i + 1].t - c.t) / 2 : hw.maxWindow / 2;
+            const prevToCurrent = i > 0 ? (c.t - ch[i - 1].t) / 2 : currentToNext;
+            const full = calculateHitWindow(hw, prevToCurrent + currentToNext);
+            c.front = frontEnd(hw, full, p.songSpeed);
+            c.back = backEnd(hw, full, p.songSpeed);
+        }
+
+        // Star power phrases.
+        this.phrases = [];
+        const sp = Array.isArray(opts.starPower) ? opts.starPower.slice() : [];
+        sp.sort((a, b) => (+a.start) - (+b.start));
+        for (const ph of sp) {
+            const start = +ph.start, end = +ph.end;
+            if (!Number.isFinite(start) || !Number.isFinite(end)) continue;
+            const members = ch.filter(c => !c.phrase && c.t >= start - PHRASE_EPS && c.t < end - PHRASE_EPS);
+            if (!members.length) continue;
+            const phrase = { index: this.phrases.length, start, end, first: members[0], last: members[members.length - 1],
+                chords: members, failed: false, awarded: false };
+            for (const c of members) c.phrase = phrase;
+            this.phrases.push(phrase);
+        }
+
+        // Drum fill activation phrases (SetDrumActivationFlags).
+        const act = Array.isArray(opts.activation) ? opts.activation : [];
+        this.activationWindows = [];
+        for (const w of act) {
+            const start = +w.start, end = +w.end;
+            if (!Number.isFinite(start) || !Number.isFinite(end)) continue;
+            let target = null;
+            for (const c of ch) {
+                if (c.t >= start - PHRASE_EPS && c.t <= end + PHRASE_EPS) target = c;
+                else if (c.t > end + PHRASE_EPS) break;
+            }
+            if (!target) target = ch.find(c => c.t >= end) || null; // YARG: first note at/after the fill end
+            if (!target) continue;
+            if (p.activationType === 'all') {
+                for (const n of target.notes) n.activator = true;
+            } else {
+                let right = target.notes[0];
+                for (const n of target.notes) if (n.lane > right.lane) right = n;
+                right.activator = true;
+            }
+            this.activationWindows.push({ start, end, chord: target });
+        }
+        this.manualActivation = opts.manualActivation != null ? !!opts.manualActivation : act.length === 0;
+
+        // Chart totals (SetInitialStats / DrumsEngine constructor).
+        this.totalNotes = 0;
+        this.totalAccents = 0;
+        this.totalGhosts = 0;
+        for (const c of ch) {
+            this.totalNotes += c.notes.length;
+            for (const n of c.notes) {
+                if (n.dyn === 'accent') this.totalAccents++;
+                else if (n.dyn === 'ghost') this.totalGhosts++;
+            }
+        }
+        const scores = this._calculateChartScores();
+        this.baseScore = scores.baseScore;
+        this.baseNoteScore = scores.noteScore;
+        this.starThresholds = (p.starMultiplierThresholds || []).map(x => Math.floor(this.baseScore * x));
+
+        this.reset();
+    }
+
+    Engine.prototype._pointsPerNote = function () {
+        return this.proDrums ? this.params.pointsPerProNote : this.params.pointsPerNote;
+    };
+
+    // DrumsEngine.CalculateChartScores
+    Engine.prototype._calculateChartScores = function () {
+        const p = this.params;
+        let base = 0, noteScore = 0, combo = 0;
+        for (const c of this.chords) {
+            const mult = Math.min(Math.floor(combo / p.notesPerMultiplier) + 1, p.maxMultiplier);
+            const s = this._pointsPerNote() * c.notes.length;
+            base += mult * s;
+            noteScore += s;
+            combo += c.notes.length;
+        }
+        return { baseScore: Math.round(base), noteScore: Math.round(noteScore) };
+    };
+
+    Engine.prototype.reset = function () {
+        this.noteIndex = 0;
+        this.currentTime = -Infinity;
+        this.stats = {
+            score: 0, noteScore: 0, multiplierScore: 0, starPowerScore: 0,
+            combo: 0, maxCombo: 0, multiplier: 1, peakMultiplier: 1,
+            notesHit: 0, notesMissed: 0, overhits: 0, overhitsByLane: {},
+            dynamicsBonus: 0, accentsHit: 0, ghostsHit: 0,
+            totalOffset: 0, offsetSamples: 0,
+            stars: 0, starIndex: 0,
+        };
+        this.sp = {
+            amount: 0,           // measures (full bar = params.starPowerMeasures)
+            active: false,
+            phrasesHit: 0,
+            activations: 0,
+            activationTime: null,
+            lastPos: 0,
+            endTime: Infinity,
+            timeInStarPower: 0,
+            totalGained: 0,
+        };
+        for (const c of this.chords) {
+            for (const n of c.notes) {
+                n.hit = false; n.missed = false; n.autoHit = false;
+                n.hitTime = null; n.offset = null; n.hitVelocity = null; n.bonus = false;
+            }
+        }
+        for (const ph of this.phrases) { ph.failed = false; ph.awarded = false; }
+        this._updateStars();
+    };
+
+    // ── Events ──
+
+    Engine.prototype.on = function (name, cb) {
+        if (typeof cb !== 'function') return () => {};
+        (this._listeners[name] || (this._listeners[name] = [])).push(cb);
+        return () => this.off(name, cb);
+    };
+    Engine.prototype.off = function (name, cb) {
+        const l = this._listeners[name];
+        if (!l) return;
+        if (cb === undefined) { delete this._listeners[name]; return; }
+        const i = l.indexOf(cb);
+        if (i >= 0) l.splice(i, 1);
+    };
+    Engine.prototype._emit = function (name, payload) {
+        const l = this._listeners[name];
+        if (!l || !l.length) return;
+        for (const cb of l.slice()) {
+            try { cb(payload); } catch (e) {
+                if (typeof console !== 'undefined' && console.error) console.error('[DrumsEngine] listener error', name, e);
+            }
+        }
+    };
+
+    // ── Helpers ──
+
+    function chordResolved(c) { return c.notes.every(n => n.hit || n.missed); }
+    function chordFullyHit(c) { return c.notes.every(n => n.hit); }
+    function isSp(c) { return !!(c.phrase && !c.phrase.failed); }
+
+    Engine.prototype._fullBar = function () { return this.params.starPowerMeasures; };
+    Engine.prototype._halfBar = function () { return this.params.starPowerMeasures / 2; };
+    Engine.prototype._quarterBar = function () { return this.params.starPowerMeasures / 4; };
+    Engine.prototype._canActivate = function () { return this.sp.amount >= this._halfBar() - SP_EPS; };
+
+    Engine.prototype._advanceIndex = function () {
+        while (this.noteIndex < this.chords.length && chordResolved(this.chords[this.noteIndex])) this.noteIndex++;
+    };
+
+    // BaseEngine.UpdateMultiplier
+    Engine.prototype._updateMultiplier = function (time) {
+        const p = this.params;
+        let m = Math.min(Math.floor(this.stats.combo / p.notesPerMultiplier) + 1, p.maxMultiplier);
+        if (this.sp.active) m *= 2;
+        const prev = this.stats.multiplier;
+        this.stats.multiplier = m;
+        if (m > this.stats.peakMultiplier) this.stats.peakMultiplier = m;
+        if (m !== prev) this._emit('multiplier', { time, multiplier: m, previous: prev });
+    };
+
+    Engine.prototype._incrementCombo = function () {
+        this.stats.combo++;
+        if (this.stats.combo > this.stats.maxCombo) this.stats.maxCombo = this.stats.combo;
+    };
+
+    Engine.prototype._resetCombo = function (time, reason) {
+        const prev = this.stats.combo;
+        this.stats.combo = 0;
+        if (prev > 0) this._emit('combo-break', { time, combo: prev, reason });
+    };
+
+    // BaseEngine.AddScore(int)
+    Engine.prototype._addScore = function (points) {
+        const s = this.stats;
+        const scored = points * s.multiplier;
+        s.score += scored;
+        if (this.sp.active) {
+            const spScore = Math.trunc(scored / 2);
+            s.starPowerScore += spScore;
+            s.multiplierScore += spScore - points;
+        } else {
+            s.multiplierScore += scored - points;
+        }
+        this._updateStars();
+    };
+
+    // BaseEngine.UpdateStars
+    Engine.prototype._updateStars = function () {
+        const s = this.stats;
+        const th = this.starThresholds || [];
+        while (s.starIndex < th.length && s.score > th[s.starIndex]) s.starIndex++;
+        let progress = 0;
+        if (s.starIndex < th.length) {
+            const prev = s.starIndex > 0 ? th[s.starIndex - 1] : 0;
+            const next = th[s.starIndex];
+            progress = next === prev ? 0 : clamp((s.score - prev) / (next - prev), 0, 1);
+        }
+        s.stars = s.starIndex + progress;
+    };
+
+    // ── Star power ──
+
+    Engine.prototype._drainTo = function (time) {
+        const sp = this.sp;
+        if (!sp.active) return;
+        const pos = this._tempo.measureAt(time);
+        const d = pos - sp.lastPos;
+        if (d > 0) {
+            sp.amount -= d;
+            if (sp.amount < SP_EPS) sp.amount = 0;
+            sp.lastPos = pos;
+        }
+    };
+
+    Engine.prototype._recomputeSpEnd = function () {
+        this.sp.endTime = this._tempo.timeAtMeasure(this.sp.lastPos + this.sp.amount);
+    };
+
+    // BaseEngine.GainStarPower
+    Engine.prototype._gainStarPower = function (measures, time) {
+        const sp = this.sp;
+        const prev = sp.amount;
+        if (!sp.active && prev < this._halfBar() - SP_EPS && prev + measures >= this._halfBar() - SP_EPS) {
+            this._emit('sp-ready', { time, amount: (prev + measures) / this._fullBar() });
+        }
+        sp.amount = Math.min(this._fullBar(), sp.amount + measures);
+        sp.totalGained += measures;
+        if (sp.active) this._recomputeSpEnd();
+    };
+
+    // BaseEngine.ActivateStarPower
+    Engine.prototype._activateStarPower = function (time) {
+        const sp = this.sp;
+        if (sp.active) return false;
+        sp.active = true;
+        sp.activationTime = time;
+        sp.lastPos = this._tempo.measureAt(time);
+        this._recomputeSpEnd();
+        sp.activations++;
+        this._updateMultiplier(time);
+        this._emit('sp-activate', { time, amount: sp.amount / this._fullBar(), endTime: sp.endTime });
+        return true;
+    };
+
+    // BaseEngine.ReleaseStarPower
+    Engine.prototype._releaseStarPower = function (time) {
+        const sp = this.sp;
+        sp.active = false;
+        sp.amount = 0;
+        sp.timeInStarPower += time - sp.activationTime;
+        sp.endTime = Infinity;
+        this._updateMultiplier(time);
+        this._emit('sp-end', { time });
+    };
+
+    // BaseEngine.StripStarPower: fail the whole phrase.
+    Engine.prototype._failPhrase = function (phrase, time) {
+        if (!phrase || phrase.failed || phrase.awarded) return;
+        phrase.failed = true;
+        this._emit('sp-phrase-fail', { time, phrase: phrase.index, start: phrase.start, end: phrase.end });
+    };
+
+    // BaseEngine.AwardStarPower
+    Engine.prototype._awardPhrase = function (phrase, time) {
+        phrase.awarded = true;
+        this.sp.phrasesHit++;
+        this._gainStarPower(this._quarterBar(), time);
+        this._emit('sp-phrase', { time, phrase: phrase.index, start: phrase.start, end: phrase.end,
+            amount: this.sp.amount / this._fullBar() });
+    };
+
+    // ── Clock ──
+
+    // Process note misses and the star power end up to `time`, in time order.
+    Engine.prototype._advance = function (time) {
+        if (!(time >= this.currentTime)) return;
+        for (;;) {
+            const c = this.chords[this.noteIndex];
+            const missAt = c ? c.t + c.back : Infinity;
+            const spEnd = this.sp.active ? this.sp.endTime : Infinity;
+            if (spEnd <= time && spEnd <= missAt) {
+                this._drainTo(spEnd);
+                this.currentTime = Math.max(this.currentTime, spEnd);
+                this._releaseStarPower(spEnd);
+                continue;
+            }
+            if (time > missAt) {
+                this._drainTo(missAt);
+                this.currentTime = Math.max(this.currentTime, missAt);
+                this._missChord(c, missAt);
+                continue;
+            }
+            break;
+        }
+        this._drainTo(time);
+        this.currentTime = time;
+    };
+
+    // YargDrumsEngine.CheckForNoteHit: the first chord was missed out the back end.
+    Engine.prototype._missChord = function (c, time) {
+        for (const n of c.notes) {
+            if (n.hit || n.missed) continue;
+            // Players may skip SP activation notes without penalty.
+            if (n.activator && this._canActivate()) {
+                this._hitNote(n, time, true);
+                continue;
+            }
+            this._missNote(n, time);
+        }
+        this._advanceIndex();
+    };
+
+    // DrumsEngine.MissNote
+    Engine.prototype._missNote = function (n, time) {
+        if (n.hit || n.missed) return;
+        n.missed = true;
+        n.hitTime = time;
+        this.stats.notesMissed++;
+        if (isSp(n.chord)) this._failPhrase(n.chord.phrase, time);
+        this._resetCombo(time, 'miss');
+        this._updateMultiplier(time);
+        this._emit('miss', { time, id: n.id, note: n.src, lane: n.lane, pad: n.pad, cymbal: n.cymbal, noteTime: n.chord.t });
+        this._advanceIndex();
+    };
+
+    // BaseEngine.SkipPreviousNotes
+    Engine.prototype._skipPreviousNotes = function (c, time) {
+        for (let i = c.index - 1; i >= 0; i--) {
+            const prev = this.chords[i];
+            if (chordResolved(prev)) break;
+            for (const n of prev.notes) if (!n.hit && !n.missed) this._missNote(n, time);
+        }
+    };
+
+    // DrumsEngine.HitNote
+    Engine.prototype._hitNote = function (n, time, autoHit) {
+        if (n.hit || n.missed) return false;
+        const c = n.chord;
+        n.hit = true;
+        n.autoHit = !!autoHit;
+        n.hitTime = time;
+        n.offset = time - c.t;
+
+        this._skipPreviousNotes(c, time);
+
+        if (isSp(c)) {
+            if (this.sp.active && this.params.noStarPowerOverlap) {
+                this._failPhrase(c.phrase, time);
+            } else if (c === c.phrase.last && chordFullyHit(c)) {
+                this._awardPhrase(c.phrase, time);
+            }
+        }
+
+        if (!autoHit && n.activator && this._canActivate() && c.notes.every(x => !x.activator || x.hit)) {
+            this._activateStarPower(time);
+        }
+
+        this._incrementCombo();
+        this.stats.notesHit++;
+        if (!autoHit) { this.stats.totalOffset += n.offset; this.stats.offsetSamples++; }
+        this._updateMultiplier(time);
+        const pts = this._pointsPerNote();
+        this._addScore(pts);
+        this.stats.noteScore += pts;
+
+        this._advanceIndex();
+        return true;
+    };
+
+    // DrumsEngine.ApplyVelocity
+    Engine.prototype._applyVelocity = function (n, velocity) {
+        if (!n.dyn) return false;
+        if (velocity == null) return false;
+        n.hitVelocity = velocity;
+        const p = this.params;
+        let threshold = p.velocityThreshold;
+        let compare = null;
+        for (let i = n.chord.index - 1; i >= 0 && !compare; i--) {
+            const pc = this.chords[i];
+            if (n.chord.t - pc.t > p.situationalVelocityWindow) break;
+            compare = pc.notes.find(x => x.lane === n.lane && x.hitVelocity != null) || null;
+        }
+        if (compare) {
+            const rel = compare.dyn === n.dyn ? compare.hitVelocity : compare.hitVelocity - p.velocityThreshold;
+            threshold = Math.max(threshold, rel != null ? rel : 0);
+        }
+        if (n.dyn === 'ghost') return velocity < threshold;
+        if (n.dyn === 'accent') return velocity > (1 - threshold);
+        return false;
+    };
+
+    function normVelocity(v) {
+        if (v == null) return null;
+        v = +v;
+        if (!Number.isFinite(v)) return null;
+        if (v > 1) v = v / 127;
+        return clamp(v, 0, 1);
+    }
+
+    // BaseEngine.WaitCountdown: a gap of >= MIN_SECONDS between notes (or song start) and the next note.
+    Engine.prototype._inWaitCountdown = function (time) {
+        const ch = this.chords;
+        let k = this.noteIndex;
+        while (k < ch.length && ch[k].t <= time) k++;
+        if (k >= ch.length) return false;
+        const prevEnd = k > 0 ? ch[k - 1].t : 0;
+        return ch[k].t - prevEnd >= this.params.waitCountdownSeconds && time >= prevEnd && time < ch[k].t;
+    };
+
+    // DrumsEngine.Overhit. Returns null if the overhit was counted, or the reason it was ignored.
+    Engine.prototype._overhit = function (time, lane, pad, cymbal) {
+        if (this.noteIndex === 0) return 'before-first-note';
+        if (this.noteIndex > this.chords.length - 1) return 'after-last-note';
+        if (this._inWaitCountdown(time)) return 'countdown';
+
+        const c = this.chords[this.noteIndex];
+        if (isSp(c) && c !== c.phrase.first) this._failPhrase(c.phrase, time);
+
+        this._resetCombo(time, 'overhit');
+        this.stats.overhits++;
+        this.stats.overhitsByLane[lane] = (this.stats.overhitsByLane[lane] || 0) + 1;
+        this._updateMultiplier(time);
+        this._emit('overhit', { time, pad, cymbal, lane });
+        return null;
+    };
+
+    // ── Public API ──
+
+    Engine.prototype.update = function (time) {
+        time = +time;
+        if (!Number.isFinite(time)) return;
+        this._advance(time);
+    };
+
+    /**
+     * Register a pad hit. pad: DrumsEngine.PAD value. opts.cymbal: cymbal input (pro drums only).
+     * opts.velocity: 0..1 (or MIDI 1..127). Returns {type:'hit'|'overhit'|'ignored', note?, offset?, bonus?, reason?}.
+     */
+    Engine.prototype.hit = function (time, pad, opts) {
+        opts = opts || {};
+        time = +time;
+        if (!Number.isFinite(time)) return { type: 'ignored', reason: 'bad-time' };
+        pad = pad | 0;
+        if (pad < 0 || pad > 4) return { type: 'ignored', reason: 'bad-pad' };
+        if (time < this.currentTime) time = this.currentTime; // QueueInput moves stale inputs forward
+        this._advance(time);
+
+        const cymbal = !!opts.cymbal;
+        const lane = laneFor(pad, cymbal, this.proDrums);
+        const velocity = normVelocity(opts.velocity);
+
+        for (let i = this.noteIndex; i < this.chords.length; i++) {
+            const c = this.chords[i];
+            if (time < c.t + c.front || time > c.t + c.back) break; // you can't skip past a note outside the window
+            for (const n of c.notes) {
+                if (n.lane !== lane) continue;
+                if (n.hit || n.missed) return { type: 'ignored', reason: 'already-hit', note: n.src };
+                const bonus = this._applyVelocity(n, velocity);
+                this._hitNote(n, time, false);
+                if (bonus) {
+                    this._addScore(this.params.velocityBonus);
+                    this.stats.dynamicsBonus += this.params.velocityBonus;
+                    if (n.dyn === 'accent') this.stats.accentsHit++;
+                    else if (n.dyn === 'ghost') this.stats.ghostsHit++;
+                }
+                n.bonus = bonus;
+                this._emit('hit', {
+                    time, id: n.id, note: n.src, lane: n.lane, pad: n.pad, cymbal: n.cymbal,
+                    noteTime: c.t, offset: n.offset, bonus, velocity,
+                    combo: this.stats.combo, multiplier: this.stats.multiplier, score: this.stats.score,
+                });
+                return { type: 'hit', note: n.src, id: n.id, offset: n.offset, bonus };
+            }
+        }
+
+        const reason = this._overhit(time, lane, pad, cymbal);
+        if (reason === null) return { type: 'overhit' };
+        return { type: 'ignored', reason };
+    };
+
+    Engine.prototype.activateStarPower = function (time) {
+        time = +time;
+        if (Number.isFinite(time)) {
+            if (time < this.currentTime) time = this.currentTime;
+            this._advance(time);
+        } else {
+            time = this.currentTime;
+        }
+        if (!this.manualActivation) return false;
+        if (this.sp.active || !this._canActivate()) return false;
+        return this._activateStarPower(time);
+    };
+
+    Engine.prototype.getState = function () {
+        const s = this.stats;
+        const sp = this.sp;
+        const resolved = s.notesHit + s.notesMissed;
+        return {
+            score: s.score,
+            combo: s.combo,
+            maxCombo: s.maxCombo,
+            multiplier: s.multiplier,
+            maxMultiplier: this.params.maxMultiplier,
+            peakMultiplier: s.peakMultiplier,
+            notesHit: s.notesHit,
+            notesMissed: s.notesMissed,
+            totalNotes: this.totalNotes,
+            overhits: s.overhits,
+            accuracy: resolved > 0 ? s.notesHit / resolved : 1,
+            percent: this.totalNotes === 0 ? 1 : s.notesHit / this.totalNotes,
+            stars: s.stars,
+            starThresholds: this.starThresholds.slice(),
+            baseScore: this.baseScore,
+            dynamicsBonus: s.dynamicsBonus,
+            starPowerScore: s.starPowerScore,
+            accentsHit: s.accentsHit,
+            ghostsHit: s.ghostsHit,
+            totalAccents: this.totalAccents,
+            totalGhosts: this.totalGhosts,
+            averageOffset: s.offsetSamples ? s.totalOffset / s.offsetSamples : 0,
+            fullCombo: s.notesMissed === 0 && s.overhits === 0 && s.notesHit === this.totalNotes,
+            time: this.currentTime,
+            starPower: {
+                amount: sp.amount / this._fullBar(),
+                active: sp.active,
+                canActivate: this._canActivate() && !sp.active,
+                phrasesHit: sp.phrasesHit,
+                phrasesTotal: this.phrases.length,
+                activations: sp.activations,
+                endTime: sp.active ? sp.endTime : null,
+                timeInStarPower: sp.timeInStarPower + (sp.active ? Math.max(0, this.currentTime - sp.activationTime) : 0),
+            },
+        };
+    };
+
+    Engine.prototype._note = function (id) {
+        if (this._alias.has(id)) id = this._alias.get(id);
+        return this._byId.get(id) || null;
+    };
+
+    Engine.prototype.noteState = function (id) {
+        const n = this._note(id);
+        if (!n) return null;
+        return n.hit ? 'hit' : (n.missed ? 'miss' : null);
+    };
+
+    Engine.prototype.noteInfo = function (id) {
+        const n = this._note(id);
+        if (!n) return null;
+        return {
+            state: n.hit ? 'hit' : (n.missed ? 'miss' : null),
+            offset: n.hit ? n.offset : null,
+            time: n.hitTime,
+            velocity: n.hitVelocity,
+            bonus: n.bonus,
+            autoHit: n.autoHit,
+            starPower: isSp(n.chord),
+            activator: n.activator,
+            lane: n.lane,
+        };
+    };
+
+    Engine.prototype.isStarPowerNote = function (id) {
+        const n = this._note(id);
+        return !!(n && isSp(n.chord));
+    };
+
+    Engine.prototype.isActivatorNote = function (id) {
+        const n = this._note(id);
+        return !!(n && n.activator);
+    };
+
+    Engine.prototype.hitWindow = function () {
+        const c = this.chords[this.noteIndex];
+        if (c) return { front: c.front, back: c.back };
+        const hw = this.params.hitWindow;
+        return { front: frontEnd(hw, hw.maxWindow, this.params.songSpeed), back: backEnd(hw, hw.maxWindow, this.params.songSpeed) };
+    };
+
+    function create(chart, opts) { return new Engine(chart, opts); }
+
+    return {
+        PAD,
+        LANE,
+        MIDI_MAP,
+        PRESETS,
+        EVENTS,
+        POINTS_PER_NOTE,
+        POINTS_PER_PRO_NOTE,
+        decodeNotes,
+        padFromMidi,
+        laneFor,
+        create,
+        defaultParams,
+        calculateHitWindow,
+        buildMeasureMap,
+        Engine,
+    };
+});
diff --git a/assets/session.js b/assets/session.js
new file mode 100644
index 0000000..731df3d
--- /dev/null
+++ b/assets/session.js
@@ -0,0 +1,1015 @@
+/*
+ * session.js: chart model, difficulty levels and the scoring session for the feedBack drums plugin
+ * (MIT, original code).
+ *
+ * Shared by both views (screen.js loads it lazily as a plain script). No DOM, no THREE. Exported on
+ * window.DrumsSession (browser) and module.exports (Node tests):
+ *  - Pure helpers: chart flattening, gem classification, drum_tab gameplay metadata (star power,
+ *    fills, solos, difficulty levels: feedpak 1.20.0), difficulty availability / fallback / labels,
+ *    auto lanes, HUD formatting, MIDI -> pad mapping, timing helpers.
+ *  - createSession(DrumsEngine, opts): owns the engine (engine.js, LGPL-3.0, used only through its
+ *    public API) for one chart. Builds it from wire notes, applies star power / fill metadata,
+ *    rebuilds on seeks, adds the bonus score (spot-on timing, rolls, drum solos) and queues engine
+ *    events for the view.
+ */
+(function (root, factory) {
+    'use strict';
+    const api = factory();
+    if (typeof module === 'object' && module && module.exports) module.exports = api;
+    if (typeof window !== 'undefined' && window) window.DrumsSession = api;
+    else if (root) root.DrumsSession = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+    'use strict';
+
+    // ── Constants ───────────────────────────────────────────────────────────
+
+    // Engine pads (engine.js PAD). Lane index = pad - 1 for the four pad lanes; the kick has no lane.
+    const PAD = Object.freeze({ KICK: 0, RED: 1, YELLOW: 2, BLUE: 3, GREEN: 4 });
+    const LANE_NAMES = Object.freeze(['red', 'yellow', 'blue', 'green']);
+
+    // Lane / gem colours (0xRRGGBB). One place to tweak the look (both views).
+    const LANE_COLORS = Object.freeze({
+        red: 0xff2b3d,
+        yellow: 0xffcc1f,
+        blue: 0x2b8bff,
+        green: 0x27d65c,
+    });
+    const COLORS = Object.freeze({
+        kick: 0xff8a14,
+        kick2x: 0xff4fc8,
+        starPowerGem: 0xdcf1ff,     // silver-white with a blue tint
+        starPowerEdge: 0x86ddff,
+        activator: 0x6dffb6,
+        fill: 0x38ffa8,
+        miss: 0xff2424,
+        missedGem: 0x3b3b48,
+        background: 0x05060c,
+        track: 0x0c0f1c,
+        rail: 0x3a4a78,
+        beat: 0x8090c0,
+        measure: 0xd0dcff,
+        strike: 0xe8ecff,
+    });
+
+    // screen.js lane ids (Learn / custom mapping) -> engine pad.
+    const LANE_ID_TO_PAD = Object.freeze({
+        kick: { pad: PAD.KICK, cymbal: false },
+        snare: { pad: PAD.RED, cymbal: false },
+        hihat: { pad: PAD.YELLOW, cymbal: true },
+        tom1: { pad: PAD.YELLOW, cymbal: false },
+        tom2: { pad: PAD.BLUE, cymbal: false },
+        tom3: { pad: PAD.GREEN, cymbal: false },
+        ride: { pad: PAD.BLUE, cymbal: true },
+        crash: { pad: PAD.GREEN, cymbal: true },
+    });
+
+    // Seeks: a jump larger than this (seconds) rebuilds the engine from the new position.
+    const SEEK_BACK = 0.25;
+    const SEEK_FORWARD = 1.5;
+    // The engine runs this far (seconds) behind the frame clock, so a pad hit timestamped a little
+    // before the latest frame is judged at its own time (see createSession update()).
+    const INPUT_GRACE = 0.06;
+    // Hits kept for the early/late timing meter.
+    const TIMING_SAMPLES = 24;
+    // Input offset range (ms), same as the settings panel.
+    const INPUT_OFFSET_MIN = -250, INPUT_OFFSET_MAX = 250;
+
+    function clamp(v, lo, hi) { return v < lo ? lo : (v > hi ? hi : v); }
+    function defaultNow() {
+        return (typeof performance !== 'undefined' && performance && typeof performance.now === 'function')
+            ? performance.now() : Date.now();
+    }
+
+    // ── Pure helpers: chart ─────────────────────────────────────────────────
+
+    /**
+     * Flatten bundle.notes + bundle.chords into one wire-note list. Chord notes take the chord's
+     * time. Visual-only notes (drum_tab flam graces, `_noScore`) are left out.
+     */
+    function collectWireNotes(notes, chords) {
+        const out = [];
+        if (Array.isArray(notes)) {
+            for (const n of notes) if (n && typeof n === 'object' && !n._noScore) out.push(n);
+        }
+        if (Array.isArray(chords)) {
+            for (const c of chords) {
+                if (!c || !Array.isArray(c.notes)) continue;
+                for (const cn of c.notes) {
+                    if (!cn || typeof cn !== 'object' || cn._noScore) continue;
+                    const t = Number.isFinite(+cn.t) ? +cn.t : +c.t;
+                    out.push(cn.t === t ? cn : Object.assign({}, cn, { t }));
+                }
+            }
+        }
+        return out;
+    }
+
+    /**
+     * Classify a decoded drum note (DrumsEngine.decodeNotes output: {pad, cymbal, kick2x, dyn}) into
+     * its gem: kind 'kick' | 'kick2x' | 'pad' | 'cymbal', lane 0..3 (-1 for the kick), dynamics and
+     * the base colour.
+     */
+    function classifyNote(n, opts) {
+        if (!n || typeof n !== 'object') return null;
+        const pro = !(opts && opts.pro === false);
+        const pad = n.pad | 0;
+        if (pad < 0 || pad > 4) return null;
+        const accent = n.dyn === 'accent';
+        const ghost = n.dyn === 'ghost';
+        if (pad === PAD.KICK) {
+            const kick2x = !!n.kick2x;
+            return { kind: kick2x ? 'kick2x' : 'kick', lane: -1, cymbal: false, kick2x, accent, ghost,
+                color: kick2x ? COLORS.kick2x : COLORS.kick };
+        }
+        const lane = pad - 1;
+        // Non-pro drums (opts.pro === false): no cymbals, every Y/B/G note is a plain pad.
+        const cymbal = pro && !!n.cymbal && pad !== PAD.RED;
+        return { kind: cymbal ? 'cymbal' : 'pad', lane, cymbal, kick2x: false, accent, ghost,
+            color: LANE_COLORS[LANE_NAMES[lane]] };
+    }
+
+    /**
+     * Render model: one gem per decoded note, sorted by time, keyed by the engine note id.
+     * opts.pro === false (non-pro drums) draws cymbals as pads and, like the engine, keeps one
+     * gem when a tom and a cymbal of the same colour land together (< 1 ms apart).
+     */
+    function buildGems(decoded, opts) {
+        const notes = decoded && Array.isArray(decoded.notes) ? decoded.notes : [];
+        const pro = !(opts && opts.pro === false);
+        const gems = [];
+        for (const n of notes) {
+            const c = classifyNote(n, opts);
+            if (!c) continue;
+            c.id = n.id;
+            c.t = n.t;
+            c.pad = n.pad | 0;
+            c.chartCymbal = !!n.cymbal;   // the chart's cymbal marking, even when non-pro draws it as a pad
+            c.auto = isAutoNote(c.pad, c.chartCymbal, opts && opts.auto);
+            gems.push(c);
+        }
+        gems.sort((a, b) => a.t - b.t);
+        if (pro) return gems;
+        const out = [];
+        for (const g of gems) {
+            let dup = false;
+            for (let i = out.length - 1; i >= 0 && g.t - out[i].t < 0.001; i--) {
+                if (out[i].lane === g.lane && out[i].kind === g.kind) { dup = true; break; }
+            }
+            if (!dup) out.push(g);
+        }
+        return out;
+    }
+
+    /** [i0, i1) of the gems with t0 <= t < t1 (gems sorted by t). */
+    function visibleRange(gems, t0, t1) {
+        let lo = 0, hi = gems.length;
+        while (lo < hi) { const m = (lo + hi) >> 1; if (gems[m].t < t0) lo = m + 1; else hi = m; }
+        const i0 = lo;
+        hi = gems.length;
+        while (lo < hi) { const m = (lo + hi) >> 1; if (gems[m].t < t1) lo = m + 1; else hi = m; }
+        return [i0, lo];
+    }
+
+    /** bundle.beats ([{time, measure}] or numbers) -> [{t, measure: bool}] sorted. */
+    function normalizeBeats(beats) {
+        if (!Array.isArray(beats)) return [];
+        const out = [];
+        for (const b of beats) {
+            if (b == null) continue;
+            if (typeof b === 'number') { if (Number.isFinite(b)) out.push({ t: b, measure: false }); continue; }
+            const t = +(b.time != null ? b.time : b.t);
+            if (!Number.isFinite(t)) continue;
+            out.push({ t, measure: b.measure != null && +b.measure >= 0 });
+        }
+        out.sort((a, b) => a.t - b.t);
+        return out;
+    }
+
+    // ── Pure helpers: auto lanes (accessibility) ────────────────────────────
+    //
+    // Auto kick / auto cymbals take those notes off the player: they are left out of the chart the
+    // engine scores (YARG "no kicks" style, so score / accuracy / streak only count what you play),
+    // still drawn (dimmed) and flash at the strikeline as if played, and pad hits on them are ignored.
+    // The setting is a difficulty ceiling: 'off' | 'easy' | 'medium' | 'hard' | 'all' = on at that
+    // difficulty and the ones below it.
+
+    const AUTO_LEVELS = Object.freeze(['off', 'easy', 'medium', 'hard', 'all']);
+
+    function normalizeAutoLevel(raw) {
+        return typeof raw === 'string' && AUTO_LEVELS.includes(raw) ? raw : 'off';
+    }
+
+    /** Is an auto setting on at this difficulty? */
+    function autoAppliesAt(level, difficultyId) {
+        level = normalizeAutoLevel(level);
+        if (level === 'off') return false;
+        if (level === 'all') return true;
+        return DIFFICULTIES.indexOf(normalizeDifficulty(difficultyId)) <= DIFFICULTIES.indexOf(level);
+    }
+
+    /** {kick, cymbals} booleans for the difficulty being played. */
+    function autoFor(settings, difficultyId) {
+        settings = settings || {};
+        return {
+            kick: autoAppliesAt(settings.kick, difficultyId),
+            cymbals: autoAppliesAt(settings.cymbals, difficultyId),
+        };
+    }
+
+    function normalizeAuto(auto) {
+        return { kick: !!(auto && auto.kick), cymbals: !!(auto && auto.cymbals) };
+    }
+
+    /** A chart note (engine pad + the chart's cymbal marking) the player does not have to hit. */
+    function isAutoNote(pad, cymbal, auto) {
+        if (!auto) return false;
+        if (auto.kick && pad === PAD.KICK) return true;
+        return !!(auto.cymbals && cymbal && pad >= PAD.YELLOW);
+    }
+
+    /** First index of a gem with g.t > t (gems sorted by t). */
+    function firstAfter(gems, t) {
+        let lo = 0, hi = gems.length;
+        while (lo < hi) { const m = (lo + hi) >> 1; if (gems[m].t <= t) lo = m + 1; else hi = m; }
+        return lo;
+    }
+
+    // ── Pure helpers: drum_tab gameplay metadata (feedpak 1.20.0) ───────────
+
+    /** A drum_tab range list ([{start_time, end_time}]) -> sorted [{start, end}], malformed entries dropped. */
+    function _ranges(list) {
+        if (!Array.isArray(list)) return [];
+        const out = [];
+        for (const p of list) {
+            if (!p || typeof p !== 'object' || Array.isArray(p)) continue;
+            const start = +p.start_time, end = +p.end_time;
+            if (!Number.isFinite(start) || !Number.isFinite(end) || end < start) continue;
+            out.push({ start, end });
+        }
+        out.sort((a, b) => a.start - b.start);
+        return out;
+    }
+
+    /**
+     * The gameplay metadata of a drum tab (bundle.drumTab, as core streams it): star power, fills
+     * (star power activation), solos and the easier difficulty levels. `toNotes` converts drum_tab
+     * hits into wire notes (screen.js _drumTabHitsToNotes) so a level plays exactly like the Expert
+     * chart. Returns null when the tab carries none of it (a pre-1.20.0 tab, or a core that does not
+     * stream it yet): the song then plays Expert only, without star power.
+     * Output is in DrumsEngine.create option shape: starPower / activation as [{start, end}].
+     */
+    function parseDrumTabMeta(tab, toNotes) {
+        if (!tab || typeof tab !== 'object' || Array.isArray(tab)) return null;
+        const starPower = _ranges(tab.star_power);
+        const activation = _ranges(tab.fills);
+        const solos = _ranges(tab.solos);
+        let levels = null;
+        const generated = [];
+        const raw = tab.levels;
+        if (raw && typeof raw === 'object' && !Array.isArray(raw) && typeof toNotes === 'function') {
+            for (const id of LOWER_LEVELS) {
+                const lv = Object.prototype.hasOwnProperty.call(raw, id) ? raw[id] : null;
+                if (!lv || typeof lv !== 'object' || !Array.isArray(lv.hits)) continue;
+                const notes = toNotes(lv.hits);
+                if (!Array.isArray(notes) || !notes.length) continue;
+                (levels || (levels = {}))[id] = notes;
+                if (lv.generated === true) generated.push(id);
+            }
+        }
+        if (!starPower.length && !activation.length && !solos.length && !levels) return null;
+        return {
+            pro: true,                    // drum_tab pieces always say cymbal vs tom
+            starPower,
+            activation,
+            solos,
+            levels,                       // {easy?, medium?, hard?}: wire notes, or null
+            levelsGenerated: generated,   // lower levels reduced by software rather than hand-charted
+        };
+    }
+
+    // ── Pure helpers: difficulty levels ─────────────────────────────────────
+    //
+    // The drum tab's `hits[]` (or the legacy GM-encoded notes) are the full chart. Expert+ = all of
+    // it; plain Expert drops the double-kick notes (drum_tab `x2`, GM 35 on the wire). Easy / Medium /
+    // Hard come from the tab's `levels` (parseDrumTabMeta) when the chart has them.
+
+    const DIFFICULTIES = Object.freeze(['easy', 'medium', 'hard', 'expert', 'expert_plus']);
+    const LOWER_LEVELS = Object.freeze(['easy', 'medium', 'hard']);
+    const DEFAULT_DIFFICULTY = 'expert';
+    const DIFFICULTY_LABELS = Object.freeze({
+        easy: 'EASY', medium: 'MEDIUM', hard: 'HARD', expert: 'EXPERT', expert_plus: 'EXPERT+',
+    });
+    const DIFFICULTY_NAMES = Object.freeze({
+        easy: 'Easy', medium: 'Medium', hard: 'Hard', expert: 'Expert', expert_plus: 'Expert+',
+    });
+    const DIFFICULTY_COLORS = Object.freeze({
+        easy: '#4be37a', medium: '#ffd23f', hard: '#ff8a3d', expert: '#ff4b5c', expert_plus: '#ff4fc8',
+    });
+    const KICK2X_MIDI = 35;
+
+    /** A stored / user-supplied difficulty id, or the default ('expert') when it is not a known id. */
+    function normalizeDifficulty(raw) {
+        return typeof raw === 'string' && DIFFICULTIES.includes(raw) ? raw : DEFAULT_DIFFICULTY;
+    }
+
+    function _wireGm(n) {
+        if (n.midi != null && Number.isFinite(+n.midi)) return +n.midi;
+        return ((n.s | 0) * 24) + (n.f | 0);
+    }
+
+    /** True when the wire chart (notes + chords) has 2x kick (GM 35) notes. */
+    function hasKick2x(notes, chords) {
+        if (Array.isArray(notes)) {
+            for (const n of notes) if (n && typeof n === 'object' && _wireGm(n) === KICK2X_MIDI) return true;
+        }
+        if (Array.isArray(chords)) {
+            for (const c of chords) {
+                if (!c || !Array.isArray(c.notes)) continue;
+                for (const n of c.notes) if (n && typeof n === 'object' && _wireGm(n) === KICK2X_MIDI) return true;
+            }
+        }
+        return false;
+    }
+
+    /** Notes / chords without the 2x kick notes. Returns the same arrays when there are none. */
+    function stripKick2x(notes, chords) {
+        if (!hasKick2x(notes, chords)) return { notes, chords };
+        const keep = (n) => !(n && typeof n === 'object' && _wireGm(n) === KICK2X_MIDI);
+        const outNotes = Array.isArray(notes) ? notes.filter(keep) : notes;
+        let outChords = chords;
+        if (Array.isArray(chords)) {
+            outChords = [];
+            for (const c of chords) {
+                if (!c || !Array.isArray(c.notes)) { outChords.push(c); continue; }
+                const cn = c.notes.filter(keep);
+                if (cn.length === c.notes.length) outChords.push(c);
+                else if (cn.length) outChords.push(Object.assign({}, c, { notes: cn }));
+            }
+        }
+        return { notes: outNotes, chords: outChords };
+    }
+
+    /**
+     * Which difficulties the loaded chart offers.
+     *   ctx.meta   parseDrumTabMeta() output (or null)
+     *   ctx.has2x  the full chart has double-kick notes (hasKick2x)
+     * -> [{id, label, name, available, reason, generated}] in DIFFICULTIES order. Expert is always
+     * available; Expert+ needs double-kick notes; Easy/Medium/Hard need the tab's levels.
+     */
+    function difficultyOptions(ctx) {
+        ctx = ctx || {};
+        const meta = ctx.meta || null;
+        const levels = meta && meta.levels ? meta.levels : null;
+        const gen = meta && Array.isArray(meta.levelsGenerated) ? meta.levelsGenerated : [];
+        return DIFFICULTIES.map((id) => {
+            const o = { id, label: DIFFICULTY_LABELS[id], name: DIFFICULTY_NAMES[id], available: true, reason: '', generated: false };
+            if (id === 'expert') return o;
+            if (id === 'expert_plus') {
+                if (!ctx.has2x) {
+                    o.available = false;
+                    o.reason = 'No double-kick notes in this chart';
+                }
+                return o;
+            }
+            const lv = levels && Array.isArray(levels[id]) ? levels[id] : null;
+            if (lv && lv.length) {
+                o.generated = gen.includes(id);
+                return o;
+            }
+            o.available = false;
+            if (!levels) o.reason = 'This chart only has Expert';
+            else o.reason = 'This chart has no ' + o.name + ' part';
+            return o;
+        });
+    }
+
+    /**
+     * Pick the difficulty to play: the saved choice when the chart has it, otherwise Expert
+     * (the saved preference itself is left alone). -> {id, requested, fallback, reason}.
+     */
+    function resolveDifficulty(saved, options) {
+        const requested = normalizeDifficulty(saved);
+        const opts = Array.isArray(options) ? options : [];
+        const want = opts.find(o => o && o.id === requested);
+        if (!want || want.available) return { id: requested, requested, fallback: false, reason: '' };
+        return { id: DEFAULT_DIFFICULTY, requested, fallback: true, reason: want.reason || '' };
+    }
+
+    /** The next available difficulty up (dir > 0) or down (dir < 0), wrapping around. */
+    function nextDifficulty(current, options, dir) {
+        const avail = DIFFICULTIES.filter(id => {
+            const o = Array.isArray(options) ? options.find(x => x && x.id === id) : null;
+            return !o || o.available;
+        });
+        if (!avail.length) return normalizeDifficulty(current);
+        const step = dir < 0 ? -1 : 1;
+        let i = DIFFICULTIES.indexOf(normalizeDifficulty(current));
+        for (let k = 0; k < DIFFICULTIES.length; k++) {
+            i = (i + step + DIFFICULTIES.length) % DIFFICULTIES.length;
+            if (avail.includes(DIFFICULTIES[i])) return DIFFICULTIES[i];
+        }
+        return normalizeDifficulty(current);
+    }
+
+    /** 'hard' -> 'HARD'; generated levels get an AUTO marker ('HARD · AUTO'). */
+    function difficultyLabel(id, generated) {
+        const base = DIFFICULTY_LABELS[normalizeDifficulty(id)];
+        return generated ? base + ' · AUTO' : base;
+    }
+
+    /**
+     * HUD badge for a resolved difficulty: {id, text, sub, color, title}. `sub` is 'AUTO' for an
+     * auto-generated level; `title` explains a fallback.
+     */
+    function difficultyBadge(resolved, options) {
+        const id = resolved ? normalizeDifficulty(resolved.id) : DEFAULT_DIFFICULTY;
+        const o = Array.isArray(options) ? options.find(x => x && x.id === id) : null;
+        const generated = !!(o && o.generated);
+        let title = 'Drum difficulty: ' + DIFFICULTY_NAMES[id] + (generated ? ' (auto-generated from Expert)' : '');
+        if (resolved && resolved.fallback) {
+            title += '. ' + DIFFICULTY_NAMES[resolved.requested] + ' is not available for this song'
+                + (resolved.reason ? ' (' + resolved.reason + ')' : '');
+        }
+        return {
+            id,
+            text: DIFFICULTY_LABELS[id],
+            sub: generated ? 'AUTO' : null,
+            color: DIFFICULTY_COLORS[id],
+            fallback: !!(resolved && resolved.fallback),
+            title,
+        };
+    }
+
+    /**
+     * Wire chart for a difficulty: Expert+ = the chart's notes/chords as they are, Expert = the same
+     * without double-kick notes, Easy/Medium/Hard = the tab's level (no chords). Unknown /
+     * unavailable lower levels fall back to Expert.
+     */
+    function difficultyChart(id, notes, chords, meta) {
+        id = normalizeDifficulty(id);
+        if (id === 'expert_plus') return { id, notes, chords };
+        if (LOWER_LEVELS.includes(id)) {
+            const lv = meta && meta.levels && Array.isArray(meta.levels[id]) ? meta.levels[id] : null;
+            if (lv && lv.length) return { id, notes: lv, chords: [] };
+            id = 'expert';
+        }
+        const s = stripKick2x(notes, chords);
+        return { id, notes: s.notes, chords: s.chords };
+    }
+
+    // ── Pure helpers: input ─────────────────────────────────────────────────
+
+    /**
+     * Difficulty shortcut: D = next harder difficulty, Shift+D = next easier (both views). D is not a
+     * drum key and not a core player shortcut. -> {dir: 1 | -1} or null.
+     */
+    function isDifficultyKey(e) {
+        if (!e || e.ctrlKey || e.metaKey || e.altKey) return null;
+        const code = typeof e.code === 'string' ? e.code : '';
+        const key = typeof e.key === 'string' ? e.key : '';
+        if (code !== 'KeyD' && !(code === '' && key.toLowerCase() === 'd')) return null;
+        return { dir: e.shiftKey ? -1 : 1 };
+    }
+
+    /**
+     * MIDI note -> engine pad. A Learn / custom mapping entry for the note wins (its lane id is
+     * translated with LANE_ID_TO_PAD); otherwise the General MIDI map (DrumsEngine.padFromMidi).
+     * The 2D lane preset is ignored on purpose: scoring always uses the 4-lane pro-drums layout.
+     */
+    function midiToPad(midi, customMapping, padFromMidi) {
+        midi = midi | 0;
+        if (midi < 0 || midi > 127) return null;
+        if (customMapping && typeof customMapping === 'object'
+            && Object.prototype.hasOwnProperty.call(customMapping, midi)) {
+            const m = LANE_ID_TO_PAD[customMapping[midi]];
+            if (m) return { pad: m.pad, cymbal: m.cymbal };
+        }
+        return typeof padFromMidi === 'function' ? (padFromMidi(midi) || null) : null;
+    }
+
+    /** True for elements that take typed text (keyboard drumming must not steal their keys). */
+    function isTypingTarget(el) {
+        if (!el || typeof el !== 'object') return false;
+        if (el.isContentEditable) return true;
+        const tag = typeof el.tagName === 'string' ? el.tagName.toUpperCase() : '';
+        if (tag === 'TEXTAREA' || tag === 'SELECT') return true;
+        if (tag === 'INPUT') {
+            const type = String(el.type || 'text').toLowerCase();
+            return !['checkbox', 'radio', 'range', 'button', 'submit', 'reset', 'color'].includes(type);
+        }
+        return false;
+    }
+
+    /**
+     * Song time of an input event that arrived between frames. bundle.currentTime only advances once
+     * per frame, so extrapolate from the last two frames while playback is running (up to 60 ms).
+     */
+    function estimateTime(clock, nowWall) {
+        if (!clock || !Number.isFinite(clock.time)) return NaN;
+        const { time, wall, prevTime, prevWall } = clock;
+        if (!Number.isFinite(prevTime) || !Number.isFinite(wall) || !Number.isFinite(prevWall)) return time;
+        const dw = (wall - prevWall) / 1000;
+        const dt = time - prevTime;
+        if (!(dw > 0) || dw > 0.25 || !(dt > 0)) return time; // paused, stalled or seeking
+        const rate = clamp(dt / dw, 0.1, 4);
+        const ahead = clamp((nowWall - wall) / 1000, 0, 0.06);
+        return time + ahead * rate;
+    }
+
+    /**
+     * Smoothed song clock for one highway (the pattern core's 3D highway uses for its own clock).
+     * bundle.currentTime is the audio time sampled by the player's tick, so it steps unevenly from
+     * frame to frame and is up to a frame old by the time a pad hit is handled. The clock anchors on
+     * every new sample, measures the playback rate between samples, and interpolates from there:
+     *  - tick(raw, isPlaying, perfNow): the time to draw / score this frame;
+     *  - at(perfNow): the song time at another moment (e.g. when a MIDI message arrived), extrapolated
+     *    up to 100 ms forward or 250 ms back from the last sample; the raw time while paused.
+     * isPlaying is core's bundle.isPlaying (false = paused / stalled / seeking; undefined on older
+     * hosts, where a sample older than 100 ms counts as stalled).
+     */
+    function createFrameClock() {
+        let anchorT = NaN, anchorP = NaN, rate = 1, raw = NaN, playing = false;
+        function reset() { anchorT = anchorP = raw = NaN; rate = 1; playing = false; }
+        function tick(rawTime, isPlaying, perfNow) {
+            rawTime = +rawTime;
+            const p = Number.isFinite(perfNow) ? perfNow : defaultNow();
+            if (!Number.isFinite(rawTime)) return NaN;
+            raw = rawTime;
+            if (isPlaying === false) {
+                anchorT = rawTime; anchorP = p; rate = 1; playing = false;
+                return rawTime;
+            }
+            if (rawTime !== anchorT) {
+                if (Number.isFinite(anchorP)) {
+                    const dP = (p - anchorP) / 1000;
+                    if (dP > 0.001 && dP < 0.5) {
+                        const r = (rawTime - anchorT) / dP;
+                        rate = (r > 0.05 && r < 5) ? r : 1;   // seek / loop: start over at 1x
+                    } else if (dP >= 0.5) rate = 1;          // long gap (paused, tab hidden)
+                }
+                anchorT = rawTime; anchorP = p; playing = true;
+                return rawTime;
+            }
+            // Same sample as last frame: interpolate, unless the clock has stalled.
+            const dt = (p - anchorP) / 1000;
+            if (dt > 0.1) { playing = false; return rawTime; }
+            if (dt <= 0) return rawTime;
+            return anchorT + rate * dt;
+        }
+        function at(perfNow) {
+            if (!playing || !Number.isFinite(anchorT)) return raw;
+            const p = Number.isFinite(perfNow) ? perfNow : defaultNow();
+            return anchorT + rate * clamp((p - anchorP) / 1000, -0.25, 0.1);
+        }
+        reset();
+        return { tick, at, reset, get rate() { return rate; }, get playing() { return playing; } };
+    }
+
+    /** True when the playhead jumped (seek, loop restart) and the engine must be rebuilt. */
+    function isSeek(prevTime, time) {
+        if (!Number.isFinite(prevTime) || !Number.isFinite(time)) return false;
+        return time < prevTime - SEEK_BACK || time > prevTime + SEEK_FORWARD;
+    }
+
+    // ── Pure helpers: HUD ───────────────────────────────────────────────────
+
+    function formatScore(n) {
+        n = Math.max(0, Math.floor(+n || 0));
+        return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    }
+
+    function formatAccuracy(acc) {
+        if (!Number.isFinite(+acc)) return '--';
+        return (clamp(+acc, 0, 1) * 100).toFixed(1) + '%';
+    }
+
+    /** Multiplier badge colour: x1 grey, x2 yellow, x3 green, x4 violet, star power (x>4 or SP) cyan. */
+    function multiplierColor(mult, spActive) {
+        if (spActive || mult > 4) return '#7fe6ff';
+        if (mult >= 4) return '#c77dff';
+        if (mult === 3) return '#4be37a';
+        if (mult === 2) return '#ffd23f';
+        return '#c8ccd8';
+    }
+
+    /** Stars earned and progress toward the next one (0..1). 6 stars = gold. */
+    function starProgress(state) {
+        const th = state && Array.isArray(state.starThresholds) ? state.starThresholds : [];
+        const score = state ? +state.score || 0 : 0;
+        let count = 0;
+        while (count < th.length && score >= th[count]) count++;
+        if (count >= th.length) return { count, frac: 1, gold: th.length > 0 && count >= 6 };
+        const prev = count > 0 ? th[count - 1] : 0;
+        const next = th[count];
+        const frac = next > prev ? clamp((score - prev) / (next - prev), 0, 1) : 0;
+        return { count, frac, gold: false };
+    }
+
+    /** Strings + numbers the HUD draws, from DrumsEngine.getState() (null state -> zeros). */
+    function hudModel(state) {
+        const s = state || {};
+        const sp = s.starPower || {};
+        const mult = s.multiplier || 1;
+        const notesPerMult = 10;
+        const maxBase = s.maxMultiplier || 4;
+        const baseMult = sp.active ? mult / 2 : mult;
+        const progress = baseMult >= maxBase ? 1 : ((s.combo || 0) % notesPerMult) / notesPerMult;
+        const stars = starProgress(s);
+        return {
+            score: formatScore(s.score),
+            multiplier: mult,
+            multiplierText: 'x' + mult,
+            multiplierColor: multiplierColor(mult, !!sp.active),
+            multiplierProgress: progress,
+            streak: s.combo || 0,
+            streakText: String(s.combo || 0),
+            accuracy: formatAccuracy(s.accuracy != null ? s.accuracy : 1),
+            hitsText: (s.notesHit || 0) + ' / ' + (s.totalNotes || 0),
+            stars: stars.count,
+            starFrac: stars.frac,
+            gold: stars.gold,
+            spAmount: clamp(+sp.amount || 0, 0, 1),
+            spActive: !!sp.active,
+            spReady: !!sp.canActivate,
+            fullCombo: !!s.fullCombo,
+        };
+    }
+
+    /**
+     * Early/late timing meter model. offsets: hit time minus note time in ms (+ = late), oldest
+     * first, as session.getBonus().offsets gives them; currentOffsetMs: the input offset in use.
+     * -> {count, median, state: 'waiting'|'early'|'late'|'ok', label, suggest}. `suggest` is the
+     * input offset that would centre the hits (after at least `minHits` hits and when the median is
+     * at least `deadMs` off), else null. Hits are already offset-corrected, so a late median
+     * raises the offset by that much.
+     */
+    function timingSummary(offsets, currentOffsetMs, o) {
+        o = o || {};
+        const minHits = o.minHits || 6, deadMs = o.deadMs != null ? o.deadMs : 10;
+        const list = Array.isArray(offsets) ? offsets.filter(Number.isFinite) : [];
+        const cur = Number.isFinite(+currentOffsetMs) ? Math.round(+currentOffsetMs) : 0;
+        if (!list.length) return { count: 0, median: null, state: 'waiting', label: 'waiting for hits', suggest: null, current: cur };
+        const srt = list.slice().sort((a, b) => a - b), mid = srt.length >> 1;
+        const median = srt.length % 2 ? srt[mid] : (srt[mid - 1] + srt[mid]) / 2;
+        const off = Math.abs(median) >= deadMs;
+        const state = !off ? 'ok' : (median < 0 ? 'early' : 'late');
+        const label = !off ? 'ON TIME' : (median > 0 ? '+' : '') + Math.round(median) + ' ms ' + (median < 0 ? 'EARLY' : 'LATE');
+        const suggest = list.length >= minHits && off
+            ? clamp(Math.round(cur + median), INPUT_OFFSET_MIN, INPUT_OFFSET_MAX) : null;
+        return { count: list.length, median, state, label, suggest: suggest === cur ? null : suggest, current: cur };
+    }
+
+    /**
+     * Star power hint for the HUD: how the player activates star power when it is ready, or null.
+     * With fills in the chart the fill-end note activates it; without fills (manual activation) a
+     * key / pad does. spPadName: the configured star power pad's name, or ''.
+     */
+    function starPowerHint(meta, state, spPadName) {
+        const sp = state && state.starPower;
+        if (!sp || !sp.canActivate || sp.active) return null;
+        if (meta && Array.isArray(meta.activation) && meta.activation.length) return 'Hit the note at the end of the fill to activate';
+        return 'Press Enter' + (spPadName ? ' or hit ' + spPadName : '') + ' to activate star power';
+    }
+
+    // ── Session: the engine for one chart ───────────────────────────────────
+
+    function normalizeInputOffset(ms) {
+        const n = Math.round(Number(ms));
+        return Number.isFinite(n) ? clamp(n, INPUT_OFFSET_MIN, INPUT_OFFSET_MAX) : 0;
+    }
+
+    /**
+     * createSession(DrumsEngine, {now, inputOffsetMs, ...}) -> session. load() a chart (wire notes
+     * + beats), optionally setMeta() the drums block, then update(time) every frame and
+     * hit()/activate() on input. drainEvents() hands queued visual events ({type, pad, cymbal, sp,
+     * wall}) to the view.
+     *
+     * Times passed to update(), hit() and activate() are on the highway's clock (what the player
+     * sees). The session subtracts the input offset from all of them alike, so with a positive
+     * offset a hit that registers late is compared against an engine that has not yet moved past
+     * its note.
+     */
+    function createSession(Engine, opts) {
+        opts = opts || {};
+        const now = typeof opts.now === 'function' ? opts.now : defaultNow;
+        const MAX_EVENTS = 256;
+        const s = {
+            decoded: null, gems: [], beats: [], rawBeats: null, meta: null, engine: null,
+            lastTime: null, lastFrame: null, events: [], builds: 0,
+            proWanted: opts.proDrums !== false,   // the player's "Pro cymbals" setting
+            auto: normalizeAuto(opts.auto),       // {kick, cymbals}: lanes played for the player
+            params: opts.params || null,          // engine params override (hit window)
+            bonus: null,                          // Rock Band-style extras on top of the engine score
+            offset: normalizeInputOffset(opts.inputOffsetMs) / 1000,   // input offset (s)
+            onHit: null,
+        };
+        // Highway time -> player time (the input offset applied).
+        const playerTime = (t) => +t - s.offset;
+
+        // ── Bonus score (on top of the engine's score) ──
+        //  - timing: +10 x multiplier for a hit within 25 ms of the note;
+        //  - rolls: snare/tom notes in a fast run (>= 4 within +-0.25 s, i.e. 8 per
+        //    second) earn +25 x multiplier; a run of >= 8 pops "ROLL h/n +pts";
+        //  - solos (meta.solos): live % of the solo's notes hit, and at the end
+        //    100 per note hit (x2 when perfect) with a Rock Band-style rating.
+        // The engine already scores dynamics (accent/ghost) and star power.
+        const ROLL_WIN = 0.25, ROLL_N = 4, ROLL_MIN = 8, ROLL_GAP = 0.6;
+        const noteKey = (t, pad) => Math.round(t * 1000) * 8 + (pad | 0);
+        function newBonus() {
+            const rolls = new Set();
+            if (s.decoded) {
+                const toms = s.decoded.notes.filter(n => n.pad >= 1 && n.pad <= 4 && !n.cymbal)
+                    .map(n => ({ t: s.decoded.chords[n.chord].t, pad: n.pad })).sort((a, b) => a.t - b.t);
+                for (let i = 0, lo = 0, hi = 0; i < toms.length; i++) {
+                    while (toms[lo].t < toms[i].t - ROLL_WIN) lo++;
+                    while (hi + 1 < toms.length && toms[hi + 1].t <= toms[i].t + ROLL_WIN) hi++;
+                    if (hi - lo + 1 >= ROLL_N) rolls.add(noteKey(toms[i].t, toms[i].pad));
+                }
+            }
+            const solos = ((s.meta && s.meta.solos) || []).map(r => ({ start: r.start, end: r.end, h: 0, n: 0, done: false }));
+            return { total: 0, timing: 0, rolls: 0, solo: 0, perfect: 0, dynamics: 0, rollSet: rolls, run: null,
+                runs: [], solos, soloDone: [], feed: [], offsets: (s.bonus && s.bonus.offsets) || [] };
+        }
+        function bonusFeed(text, color) {
+            const b = s.bonus;
+            b.feed.push({ text, color, wall: now() });
+            if (b.feed.length > 4) b.feed.shift();
+        }
+        function soloOf(t) { return s.bonus.solos.find(x => t >= x.start - 0.05 && t < x.end); }
+        function bonusHit(e) {
+            const b = s.bonus;
+            const mult = e.multiplier || 1;
+            const nt = Number.isFinite(e.noteTime) ? e.noteTime : e.time;
+            // Early/late meter: hit time minus note time (ms, + = late), the last TIMING_SAMPLES hits.
+            b.offsets.push(Math.round((e.time - nt) * 1000) || 0);   // || 0: no -0
+            if (b.offsets.length > TIMING_SAMPLES) b.offsets.shift();
+            let pts = 0;
+            if (Math.abs(e.time - nt) <= 0.025) { pts += 10 * mult; b.timing += 10 * mult; b.perfect++; }
+            if (b.rollSet.has(noteKey(nt, e.pad))) {
+                const r = 25 * mult;
+                pts += r; b.rolls += r;
+                if (!b.run || nt - b.run.last > ROLL_GAP) b.run = { h: 0, n: 0, pts: 0, last: nt };
+                b.run.h++; b.run.n++; b.run.pts += r; b.run.last = nt;
+            }
+            if (e.bonus) { b.dynamics++; bonusFeed('+' + (e.velocityBonus || 25) * mult + ' dynamics', '#b77bff'); }
+            const so = soloOf(nt);
+            if (so && !so.done) { so.h++; so.n++; }
+            b.total += pts;
+        }
+        function bonusMiss(e) {
+            const b = s.bonus;
+            const nt = Number.isFinite(e.noteTime) ? e.noteTime : e.time;
+            if (b.rollSet.has(noteKey(nt, e.pad)) && b.run && nt - b.run.last <= ROLL_GAP) { b.run.n++; b.run.last = nt; }
+            const so = soloOf(nt);
+            if (so && !so.done) so.n++;
+        }
+        function bonusTick(time) {
+            const b = s.bonus;
+            if (!b) return;
+            if (b.run && time - b.run.last > ROLL_GAP + 0.2) {
+                const r = b.run; b.run = null;
+                if (r.n >= ROLL_MIN) {
+                    b.runs.push({ h: r.h, n: r.n, pts: r.pts });
+                    push({ type: 'bonus-pop', text: 'ROLL ' + r.h + '/' + r.n + '  +' + formatScore(r.pts), color: r.h === r.n ? '#ffc531' : '#ff9a40' });
+                }
+            }
+            for (const so of b.solos) {
+                if (so.done || time < so.end + 0.3) continue;
+                so.done = true;
+                if (!so.n) continue;
+                const pct = 100 * so.h / so.n, perfect = so.h === so.n;
+                const pts = so.h * 100 * (perfect ? 2 : 1);
+                b.solo += pts; b.total += pts;
+                const rating = perfect ? 'PERFECT SOLO!' : pct >= 95 ? 'AWESOME SOLO!' : pct >= 90 ? 'GREAT SOLO!' : pct >= 80 ? 'GOOD SOLO!'
+                    : pct >= 70 ? 'SOLID SOLO' : pct >= 60 ? 'OKAY SOLO' : 'MESSY SOLO';
+                b.soloDone.push({ h: so.h, n: so.n, pct: Math.round(pct * 100) / 100, bonus: pts, rating });
+                push({ type: 'solo-end', text: rating, sub: pct.toFixed(2) + '%  ·  solo bonus +' + formatScore(pts), perfect });
+            }
+        }
+
+        function gemsFor() {
+            return buildGems(s.decoded, { pro: effectivePro(), auto: s.auto });
+        }
+
+        // Pro drums only when the player wants it and the chart has cymbal markings.
+        function effectivePro() {
+            return s.proWanted && !(s.meta && s.meta.pro === false);
+        }
+
+        // Rebuild from where the song is now (mid-song changes keep the score from here on).
+        function rebuildHere() {
+            build(s.lastTime != null && s.lastTime > (s.gems.length ? s.gems[0].t - 0.5 : 0)
+                ? s.lastTime : undefined);
+        }
+
+        function push(ev) {
+            ev.wall = now();
+            s.events.push(ev);
+            if (s.events.length > MAX_EVENTS) s.events.splice(0, s.events.length - MAX_EVENTS);
+        }
+
+        function build(fromTime) {
+            if (!s.decoded) { s.engine = null; return; }
+            let chart = s.decoded;
+            const auto = s.auto.kick || s.auto.cymbals;
+            if (Number.isFinite(fromTime) || auto) {
+                // Auto lanes are left out of the scored chart (chords regroup from the notes).
+                chart = { notes: s.decoded.notes.filter(n => (!Number.isFinite(fromTime) || n.t >= fromTime - 0.001)
+                    && !(auto && isAutoNote(n.pad, n.cymbal, s.auto))), chords: [] };
+            }
+            const m = s.meta;
+            const eopts = { beats: s.rawBeats || [], proDrums: effectivePro() };
+            if (s.params) eopts.params = s.params;
+            if (m) {
+                eopts.starPower = m.starPower;
+                eopts.activation = m.activation;
+            }
+            const eng = Engine.create(chart, eopts);
+            s.bonus = newBonus();   // a new engine starts its score over, and so do the bonuses
+            eng.on('hit', e => {
+                push({ type: 'hit', pad: e.pad, cymbal: e.cymbal, id: e.id, sp: eng.isStarPowerNote(e.id), bonus: !!e.bonus, time: e.time });
+                bonusHit(e);
+                if (s.onHit) {
+                    try { s.onHit({ time: e.time, noteTime: Number.isFinite(e.noteTime) ? e.noteTime : e.time, pad: e.pad }); } catch (_) { /* listener only */ }
+                }
+            });
+            eng.on('miss', e => {
+                push({ type: 'miss', pad: e.pad, cymbal: e.cymbal, id: e.id, time: e.time });
+                bonusMiss(e);
+            });
+            eng.on('overhit', e => push({ type: 'overhit', pad: e.pad, cymbal: e.cymbal, time: e.time }));
+            eng.on('sp-phrase', e => push({ type: 'sp-phrase', time: e.time }));
+            eng.on('sp-phrase-fail', e => push({ type: 'sp-phrase-fail', time: e.time }));
+            eng.on('sp-ready', e => push({ type: 'sp-ready', time: e.time }));
+            eng.on('sp-activate', e => push({ type: 'sp-activate', time: e.time }));
+            eng.on('sp-end', e => push({ type: 'sp-end', time: e.time }));
+            eng.on('combo-break', e => push({ type: 'combo-break', combo: e.combo, time: e.time }));
+            s.engine = eng;
+            s.builds++;
+        }
+
+        const api = {
+            /** Load a chart. notes/chords: wire arrays (drum_tab hits converted by screen.js, or legacy notes). */
+            load(chart) {
+                chart = chart || {};
+                const wire = collectWireNotes(chart.notes, chart.chords);
+                s.decoded = Engine.decodeNotes(wire, { kick2x: true });
+                s.gems = gemsFor();
+                s.rawBeats = Array.isArray(chart.beats) ? chart.beats : [];
+                s.beats = normalizeBeats(s.rawBeats);
+                s.lastTime = null;
+                s.events.length = 0;
+                build(undefined);
+                return api;
+            },
+            /** Apply the gameplay metadata (parseDrumTabMeta output, or null). Rebuilds from the current time. */
+            setMeta(meta) {
+                s.meta = meta || null;
+                if (s.decoded) {
+                    s.gems = gemsFor();
+                    rebuildHere();
+                }
+                return api;
+            },
+            /** Auto lanes ({kick, cymbals}); mid-song changes score from the current time. */
+            setAuto(auto) {
+                auto = normalizeAuto(auto);
+                if (auto.kick === s.auto.kick && auto.cymbals === s.auto.cymbals) return api;
+                s.auto = auto;
+                if (s.decoded) {
+                    s.gems = gemsFor();
+                    rebuildHere();
+                }
+                return api;
+            },
+            /** Engine params override (e.g. {hitWindow: {...}}), or null for the defaults. */
+            setParams(params) {
+                params = params || null;
+                if (JSON.stringify(params) === JSON.stringify(s.params)) return api;
+                s.params = params;
+                if (s.decoded) rebuildHere();
+                return api;
+            },
+            /** The player's "Pro cymbals" setting. false = non-pro drums (no cymbal lanes). */
+            setProDrums(on) {
+                on = on !== false;
+                if (on === s.proWanted) return api;
+                s.proWanted = on;
+                if (s.decoded) {
+                    s.gems = gemsFor();
+                    rebuildHere();
+                }
+                return api;
+            },
+            /** Advance to the highway time of this frame (the input offset is applied here too). */
+            update(frameTime) {
+                frameTime = +frameTime;
+                if (!Number.isFinite(frameTime) || !s.engine) return;
+                const time = playerTime(frameTime);
+                if (s.lastTime != null) {
+                    if (isSeek(s.lastTime, time)) build(time);
+                    else if (s.lastFrame != null && frameTime > s.lastFrame && (s.auto.kick || s.auto.cymbals)) {
+                        // Auto notes crossing the strikeline this frame flash as if played
+                        // (on the highway clock: that is when the player sees them arrive).
+                        for (let i = firstAfter(s.gems, s.lastFrame); i < s.gems.length && s.gems[i].t <= frameTime; i++) {
+                            const g = s.gems[i];
+                            if (g.auto) push({ type: 'hit', pad: g.pad, cymbal: g.cymbal, id: g.id, sp: false, auto: true, time: g.t });
+                        }
+                    }
+                }
+                // First frame after a load that starts mid-song (view switched while playing,
+                // renderer installed late): score from here instead of missing everything before.
+                else if (s.gems.length && time > s.gems[0].t - SEEK_BACK) build(time);
+                // The engine runs INPUT_GRACE behind: pad hits are timed by when they were struck
+                // (their MIDI timestamp), and the engine moves any input older than its own time
+                // forward to it (YARG QueueInput). Advanced to the frame time, every hit that
+                // arrived just after a frame would be judged late by up to a frame. Misses are
+                // only final INPUT_GRACE later.
+                s.engine.update(time - INPUT_GRACE);
+                bonusTick(time);
+                s.lastTime = time;
+                s.lastFrame = frameTime;
+            },
+            /** A pad hit struck at highway time `time`. o: {cymbal, velocity (0..1)}. */
+            hit(time, pad, o) {
+                o = o || {};
+                push({ type: 'press', pad: pad | 0, cymbal: !!o.cymbal });
+                // Pads the game plays for you: no score, no overhit.
+                if (isAutoNote(pad | 0, !!o.cymbal, s.auto)) return { type: 'ignored', reason: 'auto' };
+                if (!s.engine || !Number.isFinite(+time)) return { type: 'ignored', reason: 'no-chart' };
+                const t = playerTime(time);
+                if (s.lastTime != null && isSeek(s.lastTime, t)) return { type: 'ignored', reason: 'seek' };
+                return s.engine.hit(t, pad, { cymbal: !!o.cymbal, velocity: o.velocity });
+            },
+            /**
+             * Activate star power at highway time `time` (the Enter key / star power pad). Only
+             * works on charts without fills (with fills, the fill-end note activates it).
+             */
+            activate(time) {
+                if (!s.engine || !Number.isFinite(+time)) return false;
+                return s.engine.activateStarPower(playerTime(time));
+            },
+            /** Input offset in ms (subtracted from every time above; + = hits register earlier). */
+            setInputOffset(ms) {
+                const v = normalizeInputOffset(ms) / 1000;
+                if (v === s.offset) return api;
+                s.offset = v;
+                if (s.bonus) s.bonus.offsets = [];   // the meter measured the old offset
+                return api;
+            },
+            get inputOffsetMs() { return Math.round(s.offset * 1000); },
+            /** Per-hit timing listener ({time, noteTime, pad}: player seconds) or null. */
+            setOnHit(fn) { s.onHit = typeof fn === 'function' ? fn : null; return api; },
+            /** Forget the early/late samples. */
+            resetTiming() { if (s.bonus) s.bonus.offsets = []; return api; },
+            drainEvents() {
+                if (!s.events.length) return [];
+                const out = s.events.slice();
+                s.events.length = 0;
+                return out;
+            },
+            getState() { return s.engine ? s.engine.getState() : null; },
+            /** The chart note behind an event id: {t, midi, pad, cymbal}, or null. */
+            noteInfo(id) {
+                const n = s.decoded && Number.isInteger(id) ? s.decoded.notes[id] : null;
+                return n ? { t: n.t, midi: n.midi, pad: n.pad, cymbal: n.cymbal } : null;
+            },
+            /** True when the note (event / gem id) belongs to a star power phrase still alive. */
+            isStarPowerNote(id) { return !!(s.engine && s.engine.isStarPowerNote(id)); },
+            /** Bonus score on top of the engine's: totals, recent feed, the live solo. */
+            getBonus() {
+                const b = s.bonus;
+                if (!b) return null;
+                const t = s.lastTime;
+                const live = t == null ? null : b.solos.find(x => t >= x.start - 0.5 && t < x.end + 0.3);
+                return { total: b.total, timing: b.timing, rolls: b.rolls, solo: b.solo, perfect: b.perfect, dynamics: b.dynamics,
+                    feed: b.feed.slice(), rollActive: !!(b.run && b.run.n >= 3), runs: b.runs.slice(), solos: b.soloDone.slice(),
+                    offsets: b.offsets.slice(),
+                    soloLive: live ? { h: live.h, n: live.n, active: t >= live.start && t < live.end } : null };
+            },
+            get engine() { return s.engine; },
+            get gems() { return s.gems; },
+            get beats() { return s.beats; },
+            get meta() { return s.meta; },
+            get proDrums() { return effectivePro(); },
+            get auto() { return { kick: s.auto.kick, cymbals: s.auto.cymbals }; },
+            get builds() { return s.builds; },
+            get lastTime() { return s.lastTime; },
+        };
+        return api;
+    }
+
+    return {
+        PAD, LANE_NAMES, LANE_COLORS, COLORS, LANE_ID_TO_PAD, SEEK_BACK, SEEK_FORWARD, INPUT_GRACE, TIMING_SAMPLES,
+        collectWireNotes, classifyNote, buildGems, visibleRange, normalizeBeats,
+        AUTO_LEVELS, normalizeAutoLevel, autoAppliesAt, autoFor, isAutoNote,
+        parseDrumTabMeta,
+        DIFFICULTIES, LOWER_LEVELS, DEFAULT_DIFFICULTY, DIFFICULTY_LABELS, DIFFICULTY_NAMES, DIFFICULTY_COLORS,
+        normalizeDifficulty, hasKick2x, stripKick2x, difficultyOptions,
+        resolveDifficulty, nextDifficulty, difficultyLabel, difficultyBadge, difficultyChart, isDifficultyKey,
+        midiToPad, isTypingTarget, estimateTime, createFrameClock, isSeek,
+        formatScore, formatAccuracy, multiplierColor, starProgress, hudModel, timingSummary, starPowerHint,
+        normalizeInputOffset,
+        createSession,
+    };
+});
diff --git a/plugin.json b/plugin.json
index 3697612..510fa33 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,7 +1,7 @@
 {
   "id": "drums",
   "name": "Drum Highway",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "visualization",
   "private": false,
   "script": "screen.js",
@@ -30,6 +30,6 @@
     }
   },
   "category": "practice",
-  "description": "Drum chart playback and notation.",
+  "description": "Drum chart playback with Rock Band-style scoring, difficulty levels (Easy to Expert+), star power and assists.",
   "icon": "assets/thumb.svg"
 }
diff --git a/screen.js b/screen.js
index 4055811..9da3ac4 100644
--- a/screen.js
+++ b/screen.js
@@ -1,6 +1,11 @@
 // Drum Highway visualization plugin — lane-based scrolling drum
 // renderer (Rock Band-style) with MIDI drum pad input, WebAudioFont
-// drum kit sounds, and accuracy scoring.
+// drum kit sounds, and Rock Band-style scoring.
+//
+// Scoring: assets/engine.js (an LGPL-3.0 port of YARG.Core's drums
+// engine, see NOTICE.md) driven through assets/session.js (difficulty
+// levels, star power, assists, bonuses). Both load lazily as plain
+// scripts on first use; this file only uses their public APIs.
 //
 // Wave C (slopsmith#36): per-instance refactor. Earlier Wave B
 // landed setRenderer support with an explicit single-instance
@@ -15,9 +20,10 @@
 // Under splitscreen (N panels, N simultaneous drum instances):
 //   - each panel hosts its own overlay canvas, scoring, settings
 //     panel + gear docked inside the panel's bar
-//   - MIDI input is a browser singleton; the currently-focused
-//     panel (clicked most recently) is the sole recipient of
-//     drum-pad note-on events
+//   - MIDI input is a browser singleton; one panel receives the
+//     drum-pad note-on events: the focused one (clicked most
+//     recently) if it is on screen, else the first drum panel on
+//     screen (_routeTarget)
 //   - focus-change clears held-pad / lane-flash state on the
 //     outgoing panel
 //   - _cfg.learnLane stays module-scope (per-user-intent — clicking
@@ -65,12 +71,65 @@ const STORE_KEYS = {
     // Cr/Ri/Ki layout. 'rb4' is a denser 7-lane Rock-Band-style preset.
     // Persisted via _saveCfg below.
     lanePreset:     'drums_lane_preset_v1',
+    // Drum difficulty: easy | medium | hard | expert | expert_plus. Per
+    // browser, so each player keeps their own; songs without that level
+    // play Expert without overwriting the choice.
+    difficulty:     'drums_difficulty_v1',
+    // Pro cymbals: true = pro drums (cymbal and tom of a colour are
+    // separate); false = non-pro, either pad of a colour hits its notes.
+    proCymbals:     'drums_pro_cymbals_v1',
+    // Accessibility: auto kick / auto cymbals are played for you up to a
+    // difficulty ('off' | 'easy' | 'medium' | 'hard' | 'all').
+    autoKick:       'drums_auto_kick_v1',
+    autoCymbals:    'drums_auto_cymbals_v1',
+    // Hit window preset (TIMING_PRESETS).
+    timing:         'drums_timing_v1',
+    // Volume of the notes the auto kick / auto cymbals play for you (0..1),
+    // separate from the pad volume so pads can be silent (the kit module
+    // makes the sound) while the auto notes still fill in for a muted drum
+    // stem.
+    autoVolume:     'drums_auto_volume_v1',
+    // Subtracted from the song time of every scored hit, in ms (positive =
+    // your hits register earlier; for audio / MIDI latency).
+    inputOffsetMs:  'drums_input_offset_ms',
+    // MIDI note of the pad that activates star power on charts without
+    // drum fills (-1 = none; the Enter key always works).
+    spPad:          'drums_sp_pad_v1',
 };
 
+// Pads offered for star power activation: notes the engine does not score
+// (hat pedal) or seldom-charted extras. Any other note can be stored too.
+const SP_PAD_CHOICES = [
+    [-1, 'Off (Enter key only)'],
+    [44, 'Hi-hat pedal (44)'],
+    [53, 'Ride bell (53)'],
+    [55, 'Splash (55)'],
+    [52, 'China (52)'],
+];
+
 // Valid preset ids — kept here so _saveCfg can validate before persisting
 // (drums_lane_preset_v1 is user-controlled, like every other storage key
 // in this plugin).
 const _VALID_LANE_PRESETS = new Set(['phase_shift_8', 'rb4']);
+// Same ids as DrumsSession.DIFFICULTIES (session.js loads lazily).
+const DIFFICULTY_IDS = ['easy', 'medium', 'hard', 'expert', 'expert_plus'];
+const DIFFICULTY_NAMES = { easy: 'Easy', medium: 'Medium', hard: 'Hard', expert: 'Expert', expert_plus: 'Expert+' };
+const _VALID_DIFFICULTIES = new Set(DIFFICULTY_IDS);
+// Same ids as DrumsSession.AUTO_LEVELS.
+const AUTO_LEVEL_IDS = ['off', 'easy', 'medium', 'hard', 'all'];
+const AUTO_LEVEL_NAMES = { off: 'Off', easy: 'Easy only', medium: 'Easy – Medium', hard: 'Easy – Hard', all: 'Every difficulty' };
+const _VALID_AUTO_LEVELS = new Set(AUTO_LEVEL_IDS);
+
+// Hit window presets for the engine (engine.js params.hitWindow).
+// Normal = YARG's default 140 ms window (±70 ms).
+const TIMING_PRESETS = {
+    relaxed:   { name: 'Relaxed (±130 ms)', params: { hitWindow: { maxWindow: 0.26, minWindow: 0.26, isDynamic: false } } },
+    forgiving: { name: 'Forgiving (±100 ms)', params: { hitWindow: { maxWindow: 0.20, minWindow: 0.20, isDynamic: false } } },
+    normal:    { name: 'Normal (±70 ms)', params: null },
+    precision: { name: 'Precision (tightens on fast notes)', params: { hitWindow: {
+        maxWindow: 0.13, minWindow: 0.05, isDynamic: true, dynamicScale: 1, dynamicSlope: 0.60615, dynamicGamma: 2 } } },
+};
+const TIMING_IDS = ['relaxed', 'forgiving', 'normal', 'precision'];
 
 // Safe localStorage reader — getItem can throw SecurityError in
 // sandboxed iframes, under Safari on file://, or when storage is
@@ -146,6 +205,26 @@ const _cfg = {
         const raw = _readStore(STORE_KEYS.lanePreset);
         return _VALID_LANE_PRESETS.has(raw) ? raw : 'phase_shift_8';
     })(),
+    autoVolume:     _readNum(STORE_KEYS.autoVolume, 0.8, 0, 1),
+    inputOffsetMs:  Math.round(_readNum(STORE_KEYS.inputOffsetMs, 0, -250, 250)),
+    spPad:          Math.round(_readNum(STORE_KEYS.spPad, -1, -1, 127)),
+    difficulty:     (function () {
+        const raw = _readStore(STORE_KEYS.difficulty);
+        return _VALID_DIFFICULTIES.has(raw) ? raw : 'expert';
+    })(),
+    proCymbals:     _readStore(STORE_KEYS.proCymbals) !== 'false',
+    autoKick:       (function () {
+        const raw = _readStore(STORE_KEYS.autoKick);
+        return _VALID_AUTO_LEVELS.has(raw) ? raw : 'off';
+    })(),
+    autoCymbals:    (function () {
+        const raw = _readStore(STORE_KEYS.autoCymbals);
+        return _VALID_AUTO_LEVELS.has(raw) ? raw : 'off';
+    })(),
+    timing:         (function () {
+        const raw = _readStore(STORE_KEYS.timing);
+        return Object.prototype.hasOwnProperty.call(TIMING_PRESETS, raw) ? raw : 'normal';
+    })(),
     // Transient: which lane is in learn mode. Module-scope across
     // panels — the Learn-mode UX is "click Learn in any panel, then
     // hit a pad on the focused MIDI device." The next focused-panel
@@ -169,6 +248,27 @@ function _saveCfg(key, val) {
     if (key === 'lanePreset' && !_VALID_LANE_PRESETS.has(val)) {
         val = 'phase_shift_8';
     }
+    if (key === 'difficulty' && !_VALID_DIFFICULTIES.has(val)) {
+        val = 'expert';
+    }
+    if ((key === 'autoKick' || key === 'autoCymbals') && !_VALID_AUTO_LEVELS.has(val)) {
+        val = 'off';
+    }
+    if (key === 'timing' && !Object.prototype.hasOwnProperty.call(TIMING_PRESETS, val)) {
+        val = 'normal';
+    }
+    if (key === 'autoVolume' || key === 'synthVolume') {
+        const n = Number(val);
+        val = Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : (key === 'autoVolume' ? 0.8 : 0.7);
+    }
+    if (key === 'inputOffsetMs') {
+        const n = Math.round(Number(val));
+        val = Number.isFinite(n) ? Math.max(-250, Math.min(250, n)) : 0;
+    }
+    if (key === 'spPad') {
+        const n = Math.round(Number(val));
+        val = Number.isFinite(n) && n >= 0 && n <= 127 ? n : -1;
+    }
     _cfg[key] = val;
     const storeKey = STORE_KEYS[key];
     if (!storeKey) return;
@@ -208,10 +308,135 @@ const _instances = new Set();
 // Monotonic id for per-instance DOM tagging (useful for debugging).
 let _nextInstanceId = 0;
 
+// The host event bus (window.feedBack; window.slopsmith is its legacy alias).
+function _bus() {
+    const b = (typeof window !== 'undefined') && (window.feedBack || window.slopsmith);
+    return b && typeof b.on === 'function' ? b : null;
+}
+
+// Save the drum difficulty (per browser) and apply it to every live
+// instance: each one resolves it against its own chart (falling back to
+// Expert for that song when the level is missing) and, mid-song, rebuilds
+// its chart from the current position on its next frame.
+function _setDifficulty(id) {
+    _saveCfg('difficulty', id);
+    try {
+        document.querySelectorAll('.drums-difficulty-select').forEach((sel) => { sel.value = _cfg.difficulty; });
+    } catch (_) { /* no DOM */ }
+    for (const inst of _instances) {
+        try { inst._difficultyChanged(); } catch (e) { console.warn('[Drums] difficulty update failed:', e); }
+    }
+}
+
+// Save "Pro cymbals" (per browser) and apply it to every live instance;
+// mid-song, scoring restarts from the current position.
+function _setProCymbals(on) {
+    _saveCfg('proCymbals', !!on);
+    try {
+        document.querySelectorAll('.drums-chk-pro').forEach((chk) => { chk.checked = _cfg.proCymbals; });
+    } catch (_) { /* no DOM */ }
+    for (const inst of _instances) {
+        try { inst._proCymbalsChanged(); } catch (e) { console.warn('[Drums] pro cymbals update failed:', e); }
+    }
+}
+
+// Save an assist setting (auto kick / auto cymbals / timing) and apply it
+// to every live instance (mid-song, scoring restarts from the current
+// position, like a difficulty change).
+function _setAssist(key, val) {
+    _saveCfg(key, val);
+    const cls = { autoKick: '.drums-auto-kick', autoCymbals: '.drums-auto-cym', timing: '.drums-timing-select' }[key];
+    try {
+        if (cls) document.querySelectorAll(cls).forEach((sel) => { sel.value = _cfg[key]; });
+    } catch (_) { /* no DOM */ }
+    for (const inst of _instances) {
+        try { if (inst._assistsChanged) inst._assistsChanged(); } catch (e) { console.warn('[Drums] assist update failed:', e); }
+    }
+}
+
+// Save the input offset (ms) and hand it to every live scoring session (the
+// settings field, and the timing meter's Apply button).
+function _setInputOffset(ms) {
+    _saveCfg('inputOffsetMs', ms);
+    try {
+        document.querySelectorAll('.drums-offset-input').forEach((el) => { el.value = String(_cfg.inputOffsetMs); });
+    } catch (_) { /* no DOM */ }
+    for (const inst of _instances) {
+        try { if (inst._inputOffsetChanged) inst._inputOffsetChanged(); } catch (e) { console.warn('[Drums] input offset update failed:', e); }
+    }
+    return _cfg.inputOffsetMs;
+}
+
+// Save the star power pad (MIDI note, -1 = none).
+function _setSpPad(note) {
+    _saveCfg('spPad', note);
+    try {
+        document.querySelectorAll('.drums-sp-pad').forEach((sel) => { sel.innerHTML = _spPadOptions(_cfg.spPad); });
+    } catch (_) { /* no DOM */ }
+}
+
+function _spPadOptions(current) {
+    const list = SP_PAD_CHOICES.slice();
+    if (current >= 0 && !list.some(([n]) => n === current)) list.push([current, 'MIDI note ' + current]);
+    return list.map(([n, name]) => `<option value="${n}"${n === current ? ' selected' : ''}>${name}</option>`).join('');
+}
+
+// Short name of the star power pad for the HUD hint ('' = none).
+function _spPadName() {
+    if (_cfg.spPad < 0) return '';
+    const c = SP_PAD_CHOICES.find(([n]) => n === _cfg.spPad);
+    return c ? c[1].replace(/\s*\(\d+\)$/, '').toLowerCase() : 'MIDI note ' + _cfg.spPad;
+}
+
+// MIDI velocity (1..127) -> the engine's 0..1. The engine also accepts raw
+// MIDI values, but reads anything <= 1 as already normalised, so velocity 1
+// (the softest ghost note) would count as full strength.
+function _engineVelocity(v) {
+    const n = Number(v);
+    if (!Number.isFinite(n)) return undefined;
+    return Math.max(0, Math.min(1, n / 127));
+}
+
+// <option> lists for the settings selects (values are fixed ids; names are ours).
+function _optList(ids, names, current) {
+    return ids.map(id => `<option value="${id}"${id === current ? ' selected' : ''}>${names[id]}</option>`).join('');
+}
+function _autoOptions(current) { return _optList(AUTO_LEVEL_IDS, AUTO_LEVEL_NAMES, current); }
+function _timingOptions(current) {
+    const names = {};
+    for (const id of TIMING_IDS) names[id] = TIMING_PRESETS[id].name;
+    return _optList(TIMING_IDS, names, current);
+}
+
+const _SEL_CSS = 'background:#1a1a2e;border:1px solid #333;border-radius:6px;padding:3px 6px;font-size:11px;color:#ccc;outline:none;';
+
+// Auto lanes for a difficulty: each setting is a ceiling ('easy' = on at
+// Easy only, 'hard' = Easy..Hard, 'all' = always). Mirrors
+// DrumsSession.autoFor (kept here so it works before session.js loads).
+function _autoAt(diffId) {
+    const rank = (id) => DIFFICULTY_IDS.indexOf(id);
+    const on = (lvl) => lvl === 'all' || (lvl !== 'off' && rank(diffId) >= 0 && rank(diffId) <= rank(lvl));
+    return { kick: on(_cfg.autoKick), cymbals: on(_cfg.autoCymbals) };
+}
+
+// 2D lane ids played for the player by the auto settings.
+function _laneIsAuto(laneIdx, auto) {
+    const lane = DRUM_LANES[laneIdx];
+    if (!lane || !auto) return false;
+    if (lane.id === 'kick') return !!auto.kick;
+    return !!auto.cymbals && (lane.id === 'hihat' || lane.id === 'crash' || lane.id === 'ride');
+}
+
+function _timingParams() {
+    const p = TIMING_PRESETS[_cfg.timing];
+    return p && p.params ? JSON.parse(JSON.stringify(p.params)) : null;
+}
+
 // ── Synth ─────────────────────────────────────────────────────────────
 let _audioCtx = null;
 let _synthPlayer = null;
 let _synthGain = null;
+let _autoGain = null;        // bus for auto-played notes (its own volume)
 let _synthLoading = false;
 let _playerScriptLoaded = false;
 const _drumPresets = {};           // midiNote -> preset
@@ -251,14 +476,19 @@ const PIECE_DEFAULT_MIDI = {
 };
 
 // Convert a drum_tab.hits[] payload into the legacy {t, s, f, ac, mt}
-// note objects the renderer already understands. Velocity ≥ 100 →
-// accent (renders larger + brighter glow). Ghost notes carry `mt: true`
-// (intent for dimming/shrinking — not yet consumed by the renderer). Flams
-// emit a small leading grace note 30 ms ahead so the user sees the
-// characteristic two-tap shape. Unknown piece-ids are dropped — better
-// silent than a mis-rendered piece on an outdated client.
+// note objects the renderer already understands. Accent (`ac`, renders
+// larger + brighter, scores the dynamics bonus): the tab's authored `a`
+// flag (feedpak 1.20.0) when the tab uses it anywhere, otherwise a written
+// velocity ≥ 100 as before. A hit without `v` is not an accent. Ghost notes
+// carry `mt: true`; a hit is never both. A double kick (`x2: true` on a
+// kick) becomes GM 35 — the engine's Expert+ kick — so the Expert chart can
+// drop it. Flams emit a small leading grace note 30 ms ahead so the user
+// sees the characteristic two-tap shape. Unknown piece-ids are dropped —
+// better silent than a mis-rendered piece on an outdated client.
+const KICK2X_MIDI = 35;
 function _drumTabHitsToNotes(hits) {
     if (!Array.isArray(hits)) return [];
+    const authoredAccents = hits.some(h => h && h.a === true);
     const out = [];
     for (const h of hits) {
         const piece = h && h.p;
@@ -266,8 +496,10 @@ function _drumTabHitsToNotes(hits) {
         // '__proto__', 'constructor', etc., the plain-object lookup would
         // return an inherited value instead of undefined.
         if (!Object.prototype.hasOwnProperty.call(PIECE_DEFAULT_MIDI, piece)) continue;
-        const midi = PIECE_DEFAULT_MIDI[piece];
+        const midi = (piece === 'kick' && h.x2 === true) ? KICK2X_MIDI : PIECE_DEFAULT_MIDI[piece];
         const v = (typeof h.v === 'number') ? h.v : 100;
+        const ghost = !!h.g;
+        const accent = !ghost && (authoredAccents ? h.a === true : (typeof h.v === 'number' && h.v >= 100));
         const t = +h.t;
         // Skip hits with missing or non-finite timestamps — rendering at t=0
         // by default would score bogus notes at the song start.
@@ -276,8 +508,8 @@ function _drumTabHitsToNotes(hits) {
             t,
             s: (midi / 24) | 0,
             f: midi % 24,
-            ac: v >= 100,
-            mt: !!h.g,        // ghost — carries intent for renderer (dim/small); TODO: wire up
+            ac: accent,
+            mt: ghost,        // ghost — the engine scores it; the renderer draws it smaller
             _piece: piece,    // carried for future rendering/debug use
             _vel: v,
         };
@@ -418,17 +650,62 @@ function _rgbStr(r, g, b, a) {
 // Script loader
 // ═══════════════════════════════════════════════════════════════════════
 
+// A failed load removes its <script> element, so a later call for the same
+// URL loads it again instead of resolving at once on the dead tag.
 function _loadScript(url) {
     return new Promise((resolve, reject) => {
         if (document.querySelector(`script[src="${url}"]`)) { resolve(); return; }
         const s = document.createElement('script');
         s.src = url;
         s.onload = resolve;
-        s.onerror = () => reject(new Error('Failed to load ' + url));
+        s.onerror = () => {
+            try { s.remove(); } catch (_) { /* already gone */ }
+            reject(new Error('Failed to load ' + url));
+        };
         document.head.appendChild(s);
     });
 }
 
+// Remove the <script> element for `url` (a load that "succeeded" without
+// registering its global, e.g. an error page served as JS).
+function _dropScript(url) {
+    try { document.querySelectorAll(`script[src="${url}"]`).forEach((el) => el.remove()); } catch (_) { /* no DOM */ }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Scoring modules (engine.js + session.js, lazily loaded)
+// ═══════════════════════════════════════════════════════════════════════
+//
+// plugin.json names one script, so the scoring files live in assets/ and
+// load through core's sandboxed /api/plugins/<id>/assets/ route on first
+// use. One shared promise, so N instances never race on the same tags.
+
+const PLUGIN_ID = 'drums';
+const ASSET_VERSION = '4.1.0';   // cache-buster for the lazily loaded files
+const PLUGIN_ASSETS = '/api/plugins/' + PLUGIN_ID + '/assets/';
+
+let _scoringPromise = null;
+function _loadScoring() {
+    if (window.DrumsEngine && window.DrumsSession) {
+        return Promise.resolve({ E: window.DrumsEngine, H: window.DrumsSession });
+    }
+    if (_scoringPromise) return _scoringPromise;
+    const files = [['engine.js', 'DrumsEngine'], ['session.js', 'DrumsSession']];
+    const url = (name) => PLUGIN_ASSETS + name + '?v=' + ASSET_VERSION;
+    const want = (name, global) => (window[global] ? Promise.resolve() : _loadScript(url(name)));
+    _scoringPromise = Promise.all(files.map(([name, global]) => want(name, global))).then(() => {
+        if (!window.DrumsEngine || !window.DrumsSession) throw new Error('drums scoring modules did not register');
+        return { E: window.DrumsEngine, H: window.DrumsSession };
+    }).catch((e) => {
+        // Allow a retry on the next init: drop the script elements of the
+        // files that didn't register, or _loadScript would resolve on them.
+        for (const [name, global] of files) if (!window[global]) _dropScript(url(name));
+        _scoringPromise = null;
+        throw e;
+    });
+    return _scoringPromise;
+}
+
 // ═══════════════════════════════════════════════════════════════════════
 // WebAudioFont drum kit synthesizer (module-level — one audio context per tab)
 // ═══════════════════════════════════════════════════════════════════════
@@ -455,10 +732,13 @@ async function _synthInit() {
         }
         if (typeof WebAudioFontPlayer === 'undefined') return;
 
-        _audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+        _audioCtx = new (window.AudioContext || window.webkitAudioContext)({ latencyHint: 'interactive' });
         _synthGain = _audioCtx.createGain();
         _synthGain.gain.value = _cfg.synthVolume;
         _synthGain.connect(_audioCtx.destination);
+        _autoGain = _audioCtx.createGain();
+        _autoGain.gain.value = _cfg.autoVolume;
+        _autoGain.connect(_audioCtx.destination);
         _synthPlayer = new WebAudioFontPlayer();
 
         await _synthLoadDrumKit();
@@ -497,21 +777,198 @@ function _synthEnsureCtx() {
     }
 }
 
+// One drum sound at `when` (AudioContext time; 0 = now). dest: the output
+// bus (default: the pad bus _synthGain; _autoGain for auto-played notes).
+// Returns the WebAudioFont envelope (so a scheduled note can be cancelled),
+// or null.
+function _synthPlayNote(midiNote, velocity, when, dest) {
+    if (!_synthPlayer || !_audioCtx || !_synthGain) return null;
+    const preset = _drumPresets[midiNote];
+    if (!preset) return null;
+    dest = dest || _synthGain;
+    return _synthPlayer.queueWaveTable(_audioCtx, dest, preset, when || 0, midiNote, when ? 0.6 : 0.5,
+        (velocity / 127) * (dest === _synthGain ? _cfg.synthVolume : 1)) || null;
+}
+
 function _synthDrumHit(midiNote, velocity) {
     if (!_synthPlayer || !_audioCtx || !_synthGain) return;
-    const preset = _drumPresets[midiNote];
-    if (!preset) return;
     _synthEnsureCtx();
-
-    const vol = (velocity / 127) * _cfg.synthVolume;
-    _synthPlayer.queueWaveTable(
-        _audioCtx, _synthGain, preset, 0, midiNote, 0.5, vol
-    );
+    _synthPlayNote(midiNote, velocity, 0);
 }
 
 function _synthSetVolume(vol) {
     _saveCfg('synthVolume', vol);
-    if (_synthGain) _synthGain.gain.value = vol;
+    if (_synthGain) _synthGain.gain.value = _cfg.synthVolume;
+    try {
+        document.querySelectorAll('.drums-vol-slider').forEach((el) => { el.value = String(Math.round(_cfg.synthVolume * 100)); });
+    } catch (_) { /* no DOM */ }
+}
+
+function _setAutoVolume(vol) {
+    _saveCfg('autoVolume', vol);
+    if (_autoGain) _autoGain.gain.value = _cfg.autoVolume;
+    try {
+        document.querySelectorAll('.drums-autovol-slider').forEach((el) => { el.value = String(Math.round(_cfg.autoVolume * 100)); });
+    } catch (_) { /* no DOM */ }
+}
+
+// GM notes the auto settings play for the player (engine.js MIDI_MAP: kick
+// pads and the yellow/blue/green cymbals; the hat pedal is never scored).
+const _AUTO_KICK_MIDI = new Set([35, 36]);
+const _AUTO_CYM_MIDI = new Set([42, 46, 49, 51, 52, 53, 55, 57, 59]);
+
+function _isAutoMidi(midi, auto) {
+    return !!auto && ((auto.kick && _AUTO_KICK_MIDI.has(midi)) || (auto.cymbals && _AUTO_CYM_MIDI.has(midi)));
+}
+
+// Velocity for an auto note: drum-tab velocity, else accent / ghost / normal.
+function _autoVelocity(n) {
+    if (Number.isFinite(n._vel)) return n._vel;
+    return n.ac ? 118 : (n.mt ? 55 : 100);
+}
+
+// Auto notes with from < t <= to in a sorted wire list ({t, s, f}) and its
+// chords, as [{t, midi, vel}]. Pure (tested).
+function _autoNotesBetween(notes, chords, from, to, auto) {
+    const out = [];
+    if (!auto || (!auto.kick && !auto.cymbals) || !(to > from)) return out;
+    const scan = (list, each) => {
+        if (!Array.isArray(list)) return;
+        let lo = 0, hi = list.length;
+        while (lo < hi) { const m = (lo + hi) >> 1; if (!(list[m] && list[m].t > from)) lo = m + 1; else hi = m; }
+        for (let i = lo; i < list.length && list[i] && list[i].t <= to; i++) each(list[i]);
+    };
+    scan(notes, (n) => {
+        if (n._noScore) return;
+        const midi = (n.s | 0) * 24 + (n.f | 0);
+        if (_isAutoMidi(midi, auto)) out.push({ t: n.t, midi, vel: _autoVelocity(n) });
+    });
+    scan(chords, (c) => {
+        for (const cn of (c.notes || [])) {
+            const midi = (cn.s | 0) * 24 + (cn.f | 0);
+            if (_isAutoMidi(midi, auto)) out.push({ t: c.t, midi, vel: _autoVelocity(cn) });
+        }
+    });
+    return out;
+}
+
+// ── Auto-note scheduler ──
+// Auto notes are timed from the song's audio clock, not the frame clock: a
+// frame's song time is up to a frame old and jittery, which played the auto
+// kick ~30 ms late with ±15 ms wobble, and a repeated or backward frame time
+// restarted the window so a note now and then played twice. Here a note's
+// song time maps to the stems plugin's AudioContext (when it is there: the
+// stems playhead runs on that context's clock) and then to the drum context
+// heard at the same moment (both contexts' getOutputTimestamp), so the two
+// line up even when their output latencies differ. One schedule for all drum
+// panels, and it only moves forward (no note is scheduled twice); a pause,
+// seek or song change cancels the notes that haven't sounded yet.
+const AUTO_LOOKAHEAD = 0.1;   // song seconds scheduled ahead of the playhead
+const _autoSched = { key: null, owner: null, ownerWall: -1e9, to: NaN, last: NaN, offs: [], pending: [], hooked: null };
+
+function _autoCancel() {
+    const now = _audioCtx ? _audioCtx.currentTime : 0;
+    for (const p of _autoSched.pending) {
+        if (p.t0 <= now) continue;
+        const src = p.env && p.env.audioBufferSourceNode;
+        try { if (src) src.stop(); else if (p.env && p.env.cancel) p.env.cancel(); } catch (_) { /* not started / gone */ }
+    }
+    _autoSched.pending = [];
+    _autoSched.to = NaN;
+}
+
+// The stems plugin's AudioContext (its gain nodes live in it), or null.
+function _stemsCtx() {
+    try {
+        const st = window.stems && typeof window.stems.getState === 'function' ? window.stems.getState() : null;
+        for (const s of (st || [])) if (s && s.gain && s.gain.context) return s.gain.context;
+    } catch (_) { /* no stems */ }
+    return null;
+}
+
+// Drum context time minus stems context time for sounds heard at the same
+// moment (s). Median of recent frames (getOutputTimestamp is a little noisy).
+function _autoCtxOffset(sctx) {
+    let off = NaN;
+    try {
+        const od = _audioCtx.getOutputTimestamp(), os = sctx.getOutputTimestamp();
+        if (od && os && od.performanceTime > 0 && os.performanceTime > 0) {
+            off = (od.contextTime - os.contextTime) - (od.performanceTime - os.performanceTime) / 1000;
+        }
+    } catch (_) { /* older engine */ }
+    if (!Number.isFinite(off)) {
+        const lat = (c) => (+c.outputLatency || 0) + (+c.baseLatency || 0);
+        off = (_audioCtx.currentTime - sctx.currentTime) - (lat(_audioCtx) - lat(sctx));
+    }
+    const o = _autoSched.offs;
+    o.push(off);
+    if (o.length > 31) o.shift();
+    const sorted = o.slice().sort((a, b) => a - b);
+    return sorted[sorted.length >> 1];
+}
+
+// Called every frame by each drum view with the chart it plays. owner: the
+// view's instance id (one view drives the schedule at a time). The song
+// time comes from the player's <audio> element (chart offsets other than the
+// loose-folder song offset are 0, so audio time = chart time).
+function _autoSchedule(notes, chords, auto, owner) {
+    const S = _autoSched;
+    const wall = performance.now();
+    if (S.owner !== owner) {
+        if (wall - S.ownerWall < 300) return;   // another view is scheduling
+        S.owner = owner;
+    }
+    S.ownerWall = wall;
+    let a = null;
+    try { a = document.getElementById('audio'); } catch (_) { /* no DOM */ }
+    const on = !!auto && (auto.kick || auto.cymbals) && !!_audioCtx && !!_autoGain && _cfg.autoVolume > 0;
+    if (!on || !a || a.paused) {
+        if (S.pending.length || Number.isFinite(S.to)) _autoCancel();
+        S.last = NaN;
+        return;
+    }
+    if (S.hooked !== a) {
+        // Pause / seek between frames: drop what's queued right away.
+        S.hooked = a;
+        try { a.addEventListener('pause', _autoCancel); a.addEventListener('seeking', _autoCancel); } catch (_) { /* shimmed element */ }
+    }
+    const t = +a.currentTime;
+    if (!Number.isFinite(t)) return;
+    const sctx = _stemsCtx();
+    const sNow = sctx ? sctx.currentTime : NaN;
+    const rate = Math.max(0.25, Math.min(2, +a.playbackRate || 1));
+    if (S.key !== notes) { _autoCancel(); S.key = notes; }
+    // A seek the events missed: the playhead went back or jumped ahead.
+    if (Number.isFinite(S.last) && (t < S.last - 0.03 || t > S.last + 0.5)) _autoCancel();
+    S.last = t;
+    const off = sctx ? _autoCtxOffset(sctx) : 0;
+    if (!Number.isFinite(S.to)) S.to = t;   // (re)start here: nothing already due is replayed
+    const to = t + AUTO_LOOKAHEAD * rate;
+    if (!(to > S.to)) return;
+    // After a stall, notes more than 20 ms overdue are skipped, not played late.
+    const due = _autoNotesBetween(notes, chords, Math.max(S.to, t - 0.02), to, auto);
+    S.to = to;
+    if (!due.length) return;
+    _synthEnsureCtx();
+    const now = _audioCtx.currentTime;
+    // Drum context time at which song time t is heard.
+    const base = sctx && Number.isFinite(sNow) ? sNow + off : now;
+    S.pending = S.pending.filter((p) => p.t0 > now);
+    for (const n of due) {
+        const when = Math.max(now, base + (n.t - t) / rate);
+        const env = _synthPlayNote(n.midi, n.vel, when, _autoGain);
+        if (env) S.pending.push({ env, t0: when });
+    }
+}
+
+// Stop scheduling for a view that goes away (its notes are no longer due).
+function _autoRelease(owner) {
+    if (_autoSched.owner !== owner) return;
+    _autoCancel();
+    _autoSched.owner = null;
+    _autoSched.ownerWall = -1e9;
+    _autoSched.key = null;
+    _autoSched.last = NaN;
 }
 
 // ═══════════════════════════════════════════════════════════════════════
@@ -696,8 +1153,11 @@ async function _midiConnect(key) {
         if (res && res.handle) {
             _midiHandle = res.handle;
             // The domain handle delivers raw MIDI data; adapt to the old
-            // MIDIMessageEvent shape so _midiOnMessage stays unchanged.
-            _midiListener = (data) => _midiOnMessage({ data });
+            // MIDIMessageEvent shape so _midiOnMessage stays unchanged. A
+            // second argument, when a provider passes one, is the message's
+            // timeStamp (performance.now() clock): hits are then timed when
+            // the pad was struck rather than when this code ran.
+            _midiListener = (data, timeStamp) => _midiOnMessage({ data, timeStamp });
             // Wire the listener only when at least one renderer is active. A
             // late open() from an async _midiInit that resolved post-destroy
             // would otherwise re-enable scoring/synth in the background.
@@ -776,12 +1236,23 @@ function _midiResumeHandler() {
     if (_midiHandle && _midiListener) { try { _midiHandle.addListener(_midiListener); } catch (_) { /* best-effort */ } }
 }
 
+// Which drum view gets kit hits: the focused one if it is on screen, else
+// the first drum view on screen, else the focused one. Splitscreen focus
+// starts on panel 1 and moves on click, so a drum panel that was never
+// clicked (or a hidden main-player drum view holding focus) used to swallow
+// every hit.
+function _routeTarget() {
+    const vis = [];
+    for (const i of _instances) { try { if (i._isVisible && i._isVisible()) vis.push(i); } catch (_) { /* ignore */ } }
+    if (_activeInstance && vis.includes(_activeInstance)) return _activeInstance;
+    if (vis.length) return vis[0];
+    return _activeInstance;
+}
+
 function _midiOnMessage(e) {
-    // Only the focused instance receives MIDI. Module-level
-    // _activeInstance is the routing slot; it points at null when
-    // no instance is focused (splitscreen toggled off mid-session
-    // between teardowns, or no instance initialised yet).
-    if (!_activeInstance) return;
+    // Hits go to one drum view (_routeTarget); none live -> dropped.
+    const target = _routeTarget();
+    if (!target) return;
 
     const [status, note, velocity] = e.data;
     const ch = status & 0x0F;
@@ -789,7 +1260,7 @@ function _midiOnMessage(e) {
 
     const cmd = status & 0xF0;
     if (cmd === 0x90 && velocity > 0) {
-        _activeInstance._handleDrumHit(note, velocity);
+        target._handleDrumHit(note, velocity, e.timeStamp);
     }
     // Drums don't need note-off handling (one-shot hits)
 }
@@ -1058,6 +1529,518 @@ function createFactory() {
     // closure across the destroy.
     let _focusSubscribed = false;
 
+    // ── Scoring (engine.js via session.js) ──
+    // The chart (drum tab hits, or the legacy notes) is the full Expert+
+    // part; Easy/Medium/Hard come from the tab's `levels` (feedpak 1.20.0).
+    let _h = null;                  // DrumsSession (helpers + session factory) once loaded
+    let _E = null;                  // DrumsEngine once loaded
+    let _session = null;            // _h.createSession(...) for this instance
+    let _chartRefs = null;          // [notes, chords, beats] identities loaded into the session
+    let _metaKey;                   // drum tab the metadata was parsed from (undefined = none yet)
+    let _metaCache = null;          // _h.parseDrumTabMeta(...) for _metaKey (null = Expert only, no star power)
+    let _diffOptions = null;        // _h.difficultyOptions(...) for the loaded chart
+    let _diff = null;               // _h.resolveDifficulty(...) in use: {id, requested, fallback, reason}
+    let _badge = null;              // _h.difficultyBadge(...) drawn in the HUD
+    let _diffUiKey = '';            // last difficulty state written to the DOM
+    let _lvlMemo = null;            // {notes, chords, id, src, chart}: chart for the difficulty
+    let _has2xMemo = null;          // {notes, chords, val}
+    let _badgeBtn = null;           // clickable button over the HUD badge
+    let _badgeRectKey = '';
+    let _diffMenu = null;           // difficulty pop-up menu
+    let _onDiffKey = null, _onMenuOutside = null;
+    let _onVisibility = null, _onCanvasReplaced = null, _onSongEnded = null;
+    let _hwVisible = true;
+    let _auto = { kick: false, cymbals: false };   // auto lanes for the difficulty in use
+    // Auto notes (kick / cymbals) are played so a muted drum stem doesn't
+    // leave holes: see _autoSchedule (module level, shared by all views).
+    function _scheduleAutoSounds(notes, chords) { _autoSchedule(notes, chords, _auto, _instanceId); }
+
+    // Smoothed highway clock (session.js createFrameClock): what this view
+    // draws and scores with each frame, and the time of a pad hit between
+    // frames. Created when session.js has loaded.
+    let _frameClock = null;
+    let _frameT = NaN;              // the clock's time at the last frame
+
+    function _now() { return performance.now(); }
+
+    // Highway time of a hit. ts: when the MIDI message arrived
+    // (performance.now() clock), when the provider passes it; otherwise
+    // now. The scoring session subtracts the input offset.
+    function _inputTime(ts) {
+        const nowW = _now();
+        const at = (Number.isFinite(ts) && ts > 0 && ts <= nowW + 5 && nowW - ts < 250) ? ts : nowW;
+        const t = _frameClock ? _frameClock.at(at) : NaN;
+        if (Number.isFinite(t)) return t;
+        return Number.isFinite(_frameT) ? _frameT : (+_latestTime || 0);
+    }
+
+    // Load engine.js + session.js and build this instance's scoring session.
+    function _startScoring() {
+        _loadScoring().then(({ E, H }) => {
+            if (_instanceDestroyed || !_isReady) return;
+            _E = E;
+            _h = H;
+            if (!_frameClock) _frameClock = H.createFrameClock();
+            if (!_session) {
+                _auto = _autoAt(_diff ? _diff.id : _cfg.difficulty);
+                _session = H.createSession(E, { proDrums: _cfg.proCymbals, auto: _auto, params: _timingParams(),
+                    inputOffsetMs: _cfg.inputOffsetMs });
+                _chartRefs = null;
+            }
+        }).catch((e) => console.warn('[Drums] scoring unavailable (engine/session failed to load):', e));
+    }
+
+    // Shared bus wiring. The difficulty badge is sibling DOM, so hide it
+    // with the highway canvas (splitscreen display:none's #highway). Filter
+    // by canvas: every highway instance emits on the shared bus.
+    function _wireBus() {
+        const bus = _bus();
+        if (!bus || typeof bus.off !== 'function') return;
+        _onVisibility = (e) => {
+            if (!e || !e.detail || e.detail.canvas !== _highwayCanvas) return;
+            _hwVisible = e.detail.visible !== false;
+            if (!_hwVisible) { _placeBadge(null); _placeTimingBtn(null); _toggleDiffMenu(false); }
+        };
+        _onCanvasReplaced = (e) => {
+            if (!e || !e.detail || e.detail.oldCanvas !== _highwayCanvas) return;
+            _highwayCanvas = e.detail.newCanvas;
+        };
+        // End-of-song results card (single view; splitscreen panels skip it).
+        _onSongEnded = () => {
+            if (_instanceDestroyed || !_session || !_cfg.hitDetection || _ssActive() || !_isVisible()) return;
+            _drumsEndCard(_session, _badge);
+        };
+        try { bus.on('highway:visibility', _onVisibility); } catch (_) { _onVisibility = null; }
+        try { bus.on('highway:canvas-replaced', _onCanvasReplaced); } catch (_) { _onCanvasReplaced = null; }
+        try { bus.on('song:ended', _onSongEnded); } catch (_) { _onSongEnded = null; }
+    }
+
+    // This view is on screen (splitscreen hides the panels it doesn't show).
+    function _isVisible() {
+        const c = _highwayCanvas;
+        return !!(c && c.isConnected && c.getClientRects && c.getClientRects().length && _hwVisible !== false);
+    }
+
+    function _unwireBus() {
+        const bus = _bus();
+        if (bus && typeof bus.off === 'function') {
+            if (_onVisibility) { try { bus.off('highway:visibility', _onVisibility); } catch (_) { /* ignore */ } }
+            if (_onCanvasReplaced) { try { bus.off('highway:canvas-replaced', _onCanvasReplaced); } catch (_) { /* ignore */ } }
+            if (_onSongEnded) { try { bus.off('song:ended', _onSongEnded); } catch (_) { /* ignore */ } }
+        }
+        _onVisibility = null;
+        _onCanvasReplaced = null;
+        _onSongEnded = null;
+    }
+
+    // Gameplay metadata (star power, fills, solos, difficulty levels)
+    // rides on the drum tab core streams (feedpak 1.20.0). Parsed once per
+    // tab: draw() only runs after `ready`, when every level chunk is in. A
+    // legacy chart (GM-encoded notes, no tab) or a pre-1.20.0 tab has none:
+    // Expert only, no star power.
+    function _syncMeta(dt) {
+        if (!_h || dt === _metaKey) return;
+        _metaKey = dt;
+        _metaCache = dt ? _h.parseDrumTabMeta(dt, _drumTabHitsToNotes) : null;
+        if (_session && _chartRefs) _session.setMeta(_metaCache);
+    }
+
+    // ── Difficulty ──
+
+    // Chart for the selected difficulty, memoised on the source arrays so
+    // identities stay stable across frames (the session reloads only when
+    // they change). Before session.js loads the chart plays as it is.
+    function _applyDifficulty(bundle, notes, chords) {
+        const H = _h;
+        if (!H) return { notes, chords };
+        const chordKey = (Array.isArray(chords) && chords.length) ? chords : null;
+        if (!_has2xMemo || _has2xMemo.notes !== notes || _has2xMemo.chords !== chordKey) {
+            _has2xMemo = { notes, chords: chordKey, val: H.hasKick2x(notes, chordKey) };
+        }
+        _diffOptions = H.difficultyOptions({ meta: _metaCache, has2x: _has2xMemo.val });
+        _diff = H.resolveDifficulty(_cfg.difficulty, _diffOptions);
+        const id = _diff.id;
+        const src = _metaCache && _metaCache.levels ? (_metaCache.levels[id] || null) : null;
+        const m = _lvlMemo;
+        if (!m || m.notes !== notes || m.chords !== chordKey || m.id !== id || m.src !== src) {
+            const switched = !!(m && m.notes === notes && m.chords === chordKey && m.id !== id);
+            const chart = H.difficultyChart(id, notes, chordKey || chords, _metaCache);
+            _lvlMemo = { notes, chords: chordKey, id, src, chart };
+            // Same song, other difficulty: the session reloads (scoring
+            // from the current time, like a seek); clear the hit marks.
+            if (switched) _resetScoring();
+        }
+        _refreshDifficultyUI();
+        _syncAuto();
+        return _lvlMemo.chart;
+    }
+
+    // Auto kick / cymbals follow the difficulty being played.
+    function _syncAuto() {
+        const a = _autoAt(_diff ? _diff.id : _cfg.difficulty);
+        if (a.kick !== _auto.kick || a.cymbals !== _auto.cymbals) {
+            _auto = a;
+            _resetScoring();
+        }
+        if (_session) _session.setAuto(_auto);
+    }
+
+    function _assistsChanged() {
+        _syncAuto();
+        if (_session) _session.setParams(_timingParams());
+    }
+
+    function _proCymbalsChanged() {
+        if (_session) _session.setProDrums(_cfg.proCymbals);
+    }
+
+    function _inputOffsetChanged() {
+        if (_session) _session.setInputOffset(_cfg.inputOffsetMs);
+    }
+
+    function _difficultyChanged() {
+        if (_h && _diffOptions) _diff = _h.resolveDifficulty(_cfg.difficulty, _diffOptions);
+        _refreshDifficultyUI(true);
+    }
+
+    function _optionsHtml() {
+        const H = _h;
+        const opts = _diffOptions || (H ? H.difficultyOptions({}) : null);
+        const esc = (v) => String(v).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+        return DIFFICULTY_IDS.map((id) => {
+            const o = opts ? opts.find(x => x.id === id) : null;
+            const off = !!(o && !o.available);
+            const text = DIFFICULTY_NAMES[id] + (o && o.generated ? ' (auto)' : '') + (off ? ' – n/a' : '');
+            return `<option value="${id}"${id === _cfg.difficulty ? ' selected' : ''}${off ? ' disabled' : ''}`
+                + `${off && o.reason ? ` title="${esc(o.reason)}"` : ''}>${esc(text)}</option>`;
+        }).join('');
+    }
+
+    function _difficultyNote() {
+        if (!_diff) return '';
+        if (_diff.fallback) {
+            return 'Playing Expert: ' + (_diff.reason || (DIFFICULTY_NAMES[_diff.requested] + ' is not available'));
+        }
+        const o = _diffOptions ? _diffOptions.find(x => x.id === _diff.id) : null;
+        return o && o.generated ? DIFFICULTY_NAMES[_diff.id] + ' is auto-generated from Expert' : '';
+    }
+
+    // Push the difficulty state into the DOM (badge tooltip, settings
+    // panel, open menu) when it changed.
+    function _refreshDifficultyUI(force) {
+        const H = _h;
+        if (!H || !_diff || !_diffOptions) return;
+        const key = _cfg.difficulty + '|' + _diff.id + '|' + _diff.fallback + '|'
+            + _diffOptions.map(o => (o.available ? 1 : 0) + (o.generated ? 'g' : '') + o.reason).join(',');
+        if (!force && key === _diffUiKey) return;
+        _diffUiKey = key;
+        _badge = H.difficultyBadge(_diff, _diffOptions);
+        if (_badgeBtn) {
+            _badgeBtn.title = _badge.title + '. Click, or press D / Shift+D, to change.';
+            _badgeBtn.setAttribute('aria-label', 'Drum difficulty: ' + _badge.text
+                + (_badge.sub ? ' ' + _badge.sub : '') + '. Change difficulty');
+            _badgeBtn.dataset.difficulty = _badge.id;
+            _badgeBtn.dataset.fallback = _badge.fallback ? '1' : '0';
+        }
+        if (_settingsPanel) {
+            const sel = _settingsPanel.querySelector('.drums-difficulty-select');
+            if (sel) { sel.innerHTML = _optionsHtml(); sel.value = _cfg.difficulty; }
+            const note = _settingsPanel.querySelector('.drums-difficulty-note');
+            if (note) note.textContent = _difficultyNote();
+        }
+        if (_diffMenu && _diffMenu.style.display !== 'none') _renderDiffMenu();
+    }
+
+    // Clickable (transparent) button over the HUD difficulty badge.
+    function _ensureBadge() {
+        if (_badgeBtn || !_highwayCanvas || !_highwayCanvas.parentNode) return;
+        const b = document.createElement('button');
+        b.type = 'button';
+        b.className = 'drums-diff-badge';
+        b.dataset.drumsInstance = String(_instanceId);
+        b.setAttribute('aria-haspopup', 'menu');
+        b.setAttribute('aria-label', 'Change drum difficulty');
+        b.style.cssText = 'position:absolute;z-index:3;display:none;margin:0;padding:0;border:0;'
+            + 'background:transparent;cursor:pointer;border-radius:999px;';
+        b.onclick = (e) => {
+            e.stopPropagation();
+            b.blur();   // keep Space = play/pause rather than "click the badge again"
+            _toggleDiffMenu();
+        };
+        _highwayCanvas.parentNode.insertBefore(b, _highwayCanvas.nextSibling);
+        _badgeBtn = b;
+        _diffUiKey = '';
+        _refreshDifficultyUI();
+    }
+
+    // rect: the badge in canvas css px (from the HUD draw), or null to hide.
+    function _placeBadge(rect) {
+        if (!_badgeBtn) return;
+        if (!rect || !_hwVisible || !_highwayCanvas) {
+            if (_badgeRectKey !== '') { _badgeBtn.style.display = 'none'; _badgeRectKey = ''; }
+            return;
+        }
+        const x = Math.round(_highwayCanvas.offsetLeft + rect.x);
+        const y = Math.round(_highwayCanvas.offsetTop + rect.y);
+        const w = Math.round(rect.w), h = Math.round(rect.h);
+        const key = x + '|' + y + '|' + w + '|' + h;
+        if (key === _badgeRectKey) return;
+        _badgeRectKey = key;
+        const st = _badgeBtn.style;
+        st.left = x + 'px'; st.top = y + 'px'; st.width = w + 'px'; st.height = h + 'px';
+        st.display = '';
+    }
+
+    // The timing meter's Apply pill: a transparent button over it sets the
+    // input offset to the suggested value (and restarts the meter).
+    let _timingBtn = null, _timingRectKey = '', _timingWant = null;
+    function _placeTimingBtn(rect, want) {
+        if (!rect || !_hwVisible || !_highwayCanvas || !_highwayCanvas.parentNode) {
+            if (_timingBtn && _timingRectKey !== '') { _timingBtn.style.display = 'none'; _timingRectKey = ''; }
+            return;
+        }
+        if (!_timingBtn) {
+            const b = document.createElement('button');
+            b.type = 'button';
+            b.className = 'drums-timing-apply';
+            b.dataset.drumsInstance = String(_instanceId);
+            b.setAttribute('aria-label', 'Apply the suggested input offset');
+            b.style.cssText = 'position:absolute;z-index:3;display:none;margin:0;padding:0;border:0;'
+                + 'background:transparent;cursor:pointer;border-radius:999px;';
+            b.onclick = (e) => {
+                e.stopPropagation();
+                b.blur();   // keep Space = play/pause
+                if (Number.isFinite(_timingWant)) _setInputOffset(_timingWant);
+            };
+            _highwayCanvas.parentNode.insertBefore(b, _highwayCanvas.nextSibling);
+            _timingBtn = b;
+        }
+        _timingWant = want;
+        _timingBtn.title = 'Set the input offset to ' + want + ' ms (now ' + _cfg.inputOffsetMs + ' ms)';
+        const x = Math.round(_highwayCanvas.offsetLeft + rect.x), y = Math.round(_highwayCanvas.offsetTop + rect.y);
+        const w = Math.round(rect.w), h = Math.round(rect.h);
+        const key = x + '|' + y + '|' + w + '|' + h;
+        if (key === _timingRectKey) return;
+        _timingRectKey = key;
+        const st = _timingBtn.style;
+        st.left = x + 'px'; st.top = y + 'px'; st.width = w + 'px'; st.height = h + 'px';
+        st.display = '';
+    }
+
+    function _renderDiffMenu() {
+        const menu = _diffMenu;
+        if (!menu) return;
+        menu.textContent = '';
+        const head = document.createElement('div');
+        head.textContent = 'Difficulty';
+        head.style.cssText = 'font:700 10px system-ui,sans-serif;color:#7a84a6;padding:2px 8px 4px;'
+            + 'letter-spacing:0.08em;text-transform:uppercase;';
+        menu.appendChild(head);
+        const colors = (_h && _h.DIFFICULTY_COLORS) || {};
+        for (const o of (_diffOptions || [])) {
+            const item = document.createElement('button');
+            item.type = 'button';
+            item.className = 'drums-diff-option';
+            item.dataset.diff = o.id;
+            item.setAttribute('role', 'menuitemradio');
+            const current = !!(_diff && _diff.id === o.id);
+            item.setAttribute('aria-checked', current ? 'true' : 'false');
+            item.disabled = !o.available;
+            if (!o.available) item.title = o.reason;
+            item.style.cssText = 'display:block;width:100%;text-align:left;border:0;border-radius:6px;padding:4px 8px;'
+                + 'font:700 12px system-ui,sans-serif;background:' + (current ? 'rgba(255,255,255,0.09)' : 'transparent') + ';'
+                + 'color:' + (o.available ? (colors[o.id] || '#ddd') : '#5a6078') + ';'
+                + 'cursor:' + (o.available ? 'pointer' : 'not-allowed') + ';';
+            const label = document.createElement('span');
+            label.textContent = (current ? '▸ ' : ' ') + o.name;
+            item.appendChild(label);
+            const tag = (text) => {
+                const g = document.createElement('span');
+                g.textContent = ' ' + text;
+                g.style.cssText = 'font:800 9px system-ui,sans-serif;color:#9aa4c4;';
+                item.appendChild(g);
+            };
+            if (o.generated) tag('AUTO');
+            if (_diff && _diff.fallback && _diff.requested === o.id) tag('(saved)');
+            if (!o.available && o.reason) {
+                const r = document.createElement('div');
+                r.textContent = o.reason;
+                r.style.cssText = 'font:400 10px system-ui,sans-serif;color:#5a6078;padding-left:1.3em;white-space:normal;';
+                item.appendChild(r);
+            }
+            item.onclick = (e) => {
+                e.stopPropagation();
+                item.blur();
+                _toggleDiffMenu(false);
+                _setDifficulty(o.id);
+            };
+            menu.appendChild(item);
+        }
+    }
+
+    function _toggleDiffMenu(open) {
+        const isOpen = !!(_diffMenu && _diffMenu.style.display !== 'none');
+        if (open === undefined) open = !isOpen;
+        if (!open) {
+            if (_diffMenu) _diffMenu.style.display = 'none';
+            if (_onMenuOutside) { document.removeEventListener('pointerdown', _onMenuOutside, true); _onMenuOutside = null; }
+            return;
+        }
+        if (!_badgeBtn || !_badgeBtn.parentNode) return;
+        if (!_diffMenu) {
+            const m = document.createElement('div');
+            m.className = 'drums-diff-menu';
+            m.dataset.drumsInstance = String(_instanceId);
+            m.setAttribute('role', 'menu');
+            m.style.cssText = 'position:absolute;z-index:26;display:none;min-width:150px;max-width:260px;padding:4px;'
+                + 'background:rgba(8,10,24,0.96);border:1px solid #2a3150;border-radius:8px;'
+                + 'box-shadow:0 6px 20px rgba(0,0,0,0.5);';
+            _badgeBtn.parentNode.insertBefore(m, _badgeBtn.nextSibling);
+            _diffMenu = m;
+        }
+        _renderDiffMenu();
+        const bx = _badgeBtn.offsetLeft, by = _badgeBtn.offsetTop, bh = _badgeBtn.offsetHeight;
+        _diffMenu.style.left = bx + 'px';
+        _diffMenu.style.top = (by + bh + 4) + 'px';
+        _diffMenu.style.display = '';
+        // Open upward when it would run off the bottom of the highway.
+        if (_highwayCanvas) {
+            const mh = _diffMenu.offsetHeight;
+            const bottom = _highwayCanvas.offsetTop + _highwayCanvas.offsetHeight;
+            if (by + bh + 4 + mh > bottom && by - mh - 4 >= _highwayCanvas.offsetTop) {
+                _diffMenu.style.top = (by - mh - 4) + 'px';
+            }
+        }
+        if (!_onMenuOutside) {
+            _onMenuOutside = (e) => {
+                if (_diffMenu && _diffMenu.contains(e.target)) return;
+                if (_badgeBtn && _badgeBtn.contains(e.target)) return;
+                _toggleDiffMenu(false);
+            };
+            document.addEventListener('pointerdown', _onMenuOutside, true);
+        }
+    }
+
+    function _removeDifficultyUI() {
+        _toggleDiffMenu(false);
+        if (_diffMenu) { _diffMenu.remove(); _diffMenu = null; }
+        if (_badgeBtn) { _badgeBtn.remove(); _badgeBtn = null; }
+        if (_timingBtn) { _timingBtn.remove(); _timingBtn = null; }
+        _badgeRectKey = '';
+        _timingRectKey = '';
+        if (_onDiffKey) { window.removeEventListener('keydown', _onDiffKey, true); _onDiffKey = null; }
+        if (_onSpKey) { window.removeEventListener('keydown', _onSpKey, true); _onSpKey = null; }
+    }
+
+    // D = harder, Shift+D = easier (focused, visible panel only; not while typing).
+    function _wireDifficultyKey() {
+        if (_onDiffKey) return;
+        _onDiffKey = (e) => {
+            if (_instanceDestroyed || !_isReady || !_isFocused || !_hwVisible || !_h) return;
+            const H = _h;
+            if (H.isTypingTarget(e.target) || H.isTypingTarget(document.activeElement)) return;
+            const k = H.isDifficultyKey(e);
+            if (!k) return;
+            e.preventDefault();
+            e.stopImmediatePropagation();
+            if (e.repeat) return;
+            _setDifficulty(H.nextDifficulty(_diff ? _diff.id : _cfg.difficulty, _diffOptions, k.dir));
+        };
+        window.addEventListener('keydown', _onDiffKey, true);
+    }
+
+    // Enter = activate star power on charts without fills (with fills the
+    // fill-end note activates it). Only when it can activate right now, so
+    // Enter keeps its usual meaning otherwise.
+    let _onSpKey = null;
+    function _wireStarPowerKey() {
+        if (_onSpKey) return;
+        _onSpKey = (e) => {
+            if (_instanceDestroyed || !_isReady || !_isFocused || !_hwVisible || !_h || !_session) return;
+            if (e.code !== 'Enter' && e.code !== 'NumpadEnter' && e.key !== 'Enter') return;
+            if (e.ctrlKey || e.metaKey || e.altKey || e.repeat) return;
+            const H = _h;
+            if (H.isTypingTarget(e.target) || H.isTypingTarget(document.activeElement)) return;
+            const ae = document.activeElement;
+            if (ae && /^(BUTTON|A)$/.test(String(ae.tagName || '').toUpperCase())) return;
+            const eng = _session.engine;
+            const st = _session.getState();
+            if (!eng || !eng.manualActivation || !st || !st.starPower || !st.starPower.canActivate || st.starPower.active) return;
+            e.preventDefault();
+            e.stopImmediatePropagation();
+            _session.activate(_inputTime());
+        };
+        window.addEventListener('keydown', _onSpKey, true);
+    }
+
+    // The badge is drawn on the lane canvas, top centre: left of the score
+    // HUD when it shows (hudLeft), else on its own (the player's song title
+    // overlay owns the top-left corner).
+    function _drawDifficulty2D(ctx, W, hudLeft) {
+        const b = _badge;
+        if (!b) { _placeBadge(null); return; }
+        const y = 8, h = 20, padX = 8, gap = 5;
+        ctx.save();
+        ctx.font = 'italic bold 11px sans-serif';
+        const tw = ctx.measureText(b.text).width;
+        ctx.font = 'bold 8px sans-serif';
+        const sw = b.sub ? ctx.measureText(b.sub).width + gap : 0;
+        const w = tw + sw + padX * 2;
+        const x = Number.isFinite(hudLeft) ? Math.max(4, hudLeft - w - 6) : Math.round((W - w) / 2);
+        ctx.fillStyle = 'rgba(8,8,20,0.8)';
+        _roundRect(ctx, x, y, w, h, h / 2);
+        ctx.fill();
+        ctx.globalAlpha = b.fallback ? 0.55 : 1;
+        ctx.strokeStyle = b.color;
+        ctx.lineWidth = 1.5;
+        ctx.stroke();
+        ctx.globalAlpha = 1;
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'middle';
+        ctx.font = 'italic bold 11px sans-serif';
+        ctx.fillStyle = b.color;
+        ctx.fillText(b.text, x + padX, y + h / 2 + 0.5);
+        if (b.sub) {
+            ctx.font = 'bold 8px sans-serif';
+            ctx.fillStyle = '#9aa4c4';
+            ctx.fillText(b.sub, x + padX + tw + gap, y + h / 2 + 0.5);
+        }
+        ctx.restore();
+        _placeBadge({ x, y, w, h });
+    }
+
+    // ── Engine session ──
+
+    // Load the difficulty's chart into the session when its arrays change
+    // identity (new song / difficulty) and advance it to the playhead.
+    // Empty chord lists compare as "none": the drum_tab path builds a fresh
+    // [] every frame. A reload mid-song scores from the current time.
+    // t: this frame's highway time (_frameClock). The session applies the
+    // input offset to it, the same as to the hits.
+    function _syncSession(bundle, notes, chords, t) {
+        if (!_session) return;
+        const chordKey = (Array.isArray(chords) && chords.length) ? chords : null;
+        if (!_chartRefs || _chartRefs[0] !== notes || _chartRefs[1] !== chordKey || _chartRefs[2] !== bundle.beats) {
+            _chartRefs = [notes, chordKey, bundle.beats];
+            _session.load({ notes, chords, beats: bundle.beats });
+            _session.setMeta(_metaCache);
+            _resetScoring();
+        }
+        _session.update(t);
+    }
+
+    // Engine verdicts -> the lane view's hit / miss marks (keyed like the
+    // drawn notes: time + GM note).
+    function _drainSessionEvents() {
+        if (!_session) return;
+        for (const ev of _session.drainEvents()) {
+            if (ev.type !== 'hit' && ev.type !== 'miss') continue;
+            const info = _session.noteInfo(ev.id);
+            if (!info) continue;
+            (ev.type === 'hit' ? _hitNoteKeys : _missedNoteKeys).add(_noteKey(info.t, info.midi));
+        }
+    }
+
     // ── Listener refs (per-instance so destroy() detach matches) ──
     const _onWinResize = () => _applyCanvasDims();
     const _onFocusChange = () => _updateFocusState();
@@ -1105,7 +2088,8 @@ function createFactory() {
 
     // ── MIDI event handler (called by _midiOnMessage via _activeInstance) ──
 
-    function _handleDrumHit(midiNote, velocity) {
+    // ts: when the MIDI message arrived (performance.now() clock), if known.
+    function _handleDrumHit(midiNote, velocity, ts) {
         if (midiNote < 0 || midiNote > 127) return;
 
         // Learn mode: assign this MIDI note to the pending lane.
@@ -1142,6 +2126,22 @@ function createFactory() {
             });
         }
 
+        if (_session && _h && _E) {
+            // The star power pad (settings) activates star power instead of
+            // scoring (charts without fills; with fills the fill-end note does).
+            if (_cfg.spPad >= 0 && midiNote === _cfg.spPad) {
+                _session.activate(_inputTime(ts));
+                return;
+            }
+            // The engine scores: a Learn/custom mapping entry wins, else GM.
+            const m = _h.midiToPad(midiNote, _cfg.customMapping, _E.padFromMidi);
+            if (m) {
+                const r = _session.hit(_inputTime(ts), m.pad, { cymbal: m.cymbal, velocity: _engineVelocity(velocity) });
+                if (r && r.type === 'overhit' && laneIdx >= 0) _wrongFlashes.push({ lane: laneIdx, wall: performance.now() });
+            }
+            return;
+        }
+
         if (_cfg.hitDetection) {
             _checkHit(midiNote);
         }
@@ -1165,6 +2165,7 @@ function createFactory() {
 
         const playedLane = _midiToLaneIdx(playedMidi);
         if (playedLane < 0) return;
+        if (_laneIsAuto(playedLane, _auto)) return;   // played for you: no hit, no miss
 
         let foundHit = false;
 
@@ -1216,7 +2217,9 @@ function createFactory() {
     }
 
     function _updateMissedNotes(t, notes, chords) {
-        if (!_cfg.hitDetection) return;
+        _expireFlashes();
+        // With the engine loaded its verdicts mark the notes (_drainSessionEvents).
+        if (!_cfg.hitDetection || _session) return;
         const cutoff = t - HIT_TOLERANCE - 0.05;
 
         if (notes) {
@@ -1227,6 +2230,7 @@ function createFactory() {
                 // user is expected to hit the main note, not the grace ornament.
                 if (n._noScore) continue;
                 const songMidi = noteToMidi(n.s, n.f);
+                if (_laneIsAuto(_songNoteToLaneIdx(songMidi), _auto)) continue;
                 const key = _noteKey(n.t, songMidi);
                 if (!_hitNoteKeys.has(key) && !_missedNoteKeys.has(key) && n.t < cutoff) {
                     _missedNoteKeys.add(key);
@@ -1239,6 +2243,7 @@ function createFactory() {
                 if (c.t < cutoff - 2) continue;
                 for (const cn of (c.notes || [])) {
                     const songMidi = noteToMidi(cn.s, cn.f);
+                    if (_laneIsAuto(_songNoteToLaneIdx(songMidi), _auto)) continue;
                     const key = _noteKey(c.t, songMidi);
                     if (!_hitNoteKeys.has(key) && !_missedNoteKeys.has(key) && c.t < cutoff) {
                         _missedNoteKeys.add(key);
@@ -1246,7 +2251,9 @@ function createFactory() {
                 }
             }
         }
+    }
 
+    function _expireFlashes() {
         const now = performance.now();
         while (_wrongFlashes.length && now - _wrongFlashes[0].wall > 400) {
             _wrongFlashes.shift();
@@ -1270,6 +2277,9 @@ function createFactory() {
     function _resetForNewChart() {
         _resetScoring();
         _heldPads.clear();
+        _chartRefs = null;
+        _metaKey = undefined;
+        _metaCache = null;
         // Drop the drum_tab → notes memo so a song-change replay
         // doesn't keep showing the previous chart's drum hits while
         // the new bundle is still loading.
@@ -1398,13 +2408,63 @@ function createFactory() {
                     <input type="checkbox" class="drums-chk-labels" ${_cfg.showLaneLabels ? 'checked' : ''}
                         style="accent-color:#ef4444;"> Labels
                 </label>
-                <label style="display:flex;align-items:center;gap:3px;font-size:11px;color:#999;cursor:pointer;">
+                <label style="display:flex;align-items:center;gap:3px;font-size:11px;color:#999;cursor:pointer;"
+                    title="Show the score: hit / miss marks on the notes, score, multiplier, streak and star power.">
                     <input type="checkbox" class="drums-chk-hits" ${_cfg.hitDetection ? 'checked' : ''}
-                        style="accent-color:#22cc66;"> Hits
+                        style="accent-color:#22cc66;"> Score
                 </label>
                 <button class="drums-reset-map" style="background:#1a1a2e;border:1px solid #333;border-radius:4px;
                     padding:2px 8px;font-size:10px;color:#aaa;cursor:pointer;">Reset Map</button>
             </div>
+            <div style="display:flex;gap:14px;align-items:center;flex-wrap:wrap;margin-bottom:6px;">
+                <label style="display:flex;align-items:center;gap:4px;font-size:10px;color:#666;"
+                    title="Drum difficulty, saved in this browser. Expert+ adds the double-kick notes. Easy/Medium/Hard need a chart that has them; otherwise the song plays Expert. While playing: click the difficulty badge, or press D (harder) / Shift+D (easier).">
+                    Difficulty
+                    <select class="drums-difficulty-select" aria-label="Drum difficulty" style="${_SEL_CSS}width:128px;">
+                        ${_optionsHtml()}
+                    </select>
+                </label>
+                <label style="display:flex;align-items:center;gap:3px;font-size:11px;color:#999;cursor:pointer;"
+                    title="On: pro drums, cymbals and toms of the same colour are separate notes. Off: either the cymbal or the tom of a colour hits that colour's notes.">
+                    <input type="checkbox" class="drums-chk-pro" ${_cfg.proCymbals ? 'checked' : ''}
+                        style="accent-color:#eab308;"> Pro cymbals
+                </label>
+                <label style="display:flex;align-items:center;gap:4px;font-size:10px;color:#666;"
+                    title="How early or late a hit can be and still count.">
+                    Timing
+                    <select class="drums-timing-select" aria-label="Hit timing window" style="${_SEL_CSS}width:150px;">${_timingOptions(_cfg.timing)}</select>
+                </label>
+                <label style="display:flex;align-items:center;gap:4px;font-size:10px;color:#666;"
+                    title="Input offset in ms, subtracted from each hit's time (raise it if your hits register late). The timing meter under the score suggests a value: click Apply.">
+                    Offset
+                    <input type="number" class="drums-offset-input" min="-250" max="250" step="1"
+                        value="${_cfg.inputOffsetMs}" style="${_SEL_CSS}width:58px;"> ms
+                </label>
+                <label style="display:flex;align-items:center;gap:4px;font-size:10px;color:#666;"
+                    title="On charts without drum fills, star power is activated with the Enter key or this pad (it then does not score as a note).">
+                    SP pad
+                    <select class="drums-sp-pad" aria-label="Star power pad" style="${_SEL_CSS}width:132px;">${_spPadOptions(_cfg.spPad)}</select>
+                </label>
+                <span class="drums-difficulty-note" style="font-size:10px;color:#a8946a;">${_difficultyNote()}</span>
+            </div>
+            <div style="display:flex;gap:14px;align-items:center;flex-wrap:wrap;margin-bottom:6px;">
+                <label style="display:flex;align-items:center;gap:4px;font-size:10px;color:#666;"
+                    title="Kick notes are played for you (no score, no misses) at the difficulties picked here.">
+                    Auto kick
+                    <select class="drums-auto-kick" aria-label="Auto kick" style="${_SEL_CSS}width:118px;">${_autoOptions(_cfg.autoKick)}</select>
+                </label>
+                <label style="display:flex;align-items:center;gap:4px;font-size:10px;color:#666;"
+                    title="Cymbal notes (hi-hat, ride, crash) are played for you at the difficulties picked here.">
+                    Auto cymbals
+                    <select class="drums-auto-cym" aria-label="Auto cymbals" style="${_SEL_CSS}width:118px;">${_autoOptions(_cfg.autoCymbals)}</select>
+                </label>
+                <label style="display:flex;align-items:center;gap:4px;font-size:10px;color:#666;"
+                    title="Volume of the kick / cymbal notes played for you (so a muted drum stem has no holes).">
+                    Auto vol
+                    <input type="range" class="drums-autovol-slider" min="0" max="100"
+                        value="${Math.round(_cfg.autoVolume * 100)}" style="width:70px;accent-color:#ef4444;height:14px;">
+                </label>
+            </div>
             <details style="margin-top:2px;">
                 <summary style="font-size:10px;color:#666;cursor:pointer;">MIDI Mapping</summary>
                 <table class="drums-map-table" style="font-size:11px;margin-top:4px;">${_buildMappingRows()}</table>
@@ -1465,6 +2525,21 @@ function createFactory() {
             _midiUpdateAllDeviceLists();
         };
 
+        panel.querySelector('.drums-chk-pro').onchange = function () {
+            _setProCymbals(this.checked);
+        };
+        panel.querySelector('.drums-difficulty-select').onchange = function () {
+            _setDifficulty(this.value);
+        };
+        panel.querySelector('.drums-offset-input').onchange = function () {
+            _setInputOffset(this.value);
+        };
+        panel.querySelector('.drums-sp-pad').onchange = function () { _setSpPad(this.value); };
+        panel.querySelector('.drums-auto-kick').onchange = function () { _setAssist('autoKick', this.value); };
+        panel.querySelector('.drums-auto-cym').onchange = function () { _setAssist('autoCymbals', this.value); };
+        panel.querySelector('.drums-timing-select').onchange = function () { _setAssist('timing', this.value); };
+        panel.querySelector('.drums-autovol-slider').oninput = function () { _setAutoVolume(parseInt(this.value, 10) / 100); };
+
         _wireLearnButtons(panel);
     }
 
@@ -1499,7 +2574,8 @@ function createFactory() {
 
     // ── Drawing ──
 
-    function _draw(notes, chords, t, beats) {
+    // message: text drawn over the empty lanes instead of the HUD (not a drum chart).
+    function _draw(notes, chords, t, beats, message) {
         if (!_drumCanvas || !_drumCtx) return;
 
         // Update the MIDI-scoring snapshots FIRST — before the
@@ -1535,6 +2611,10 @@ function createFactory() {
         ctx.fillStyle = '#040408';
         ctx.fillRect(0, 0, W, H);
 
+        const st = _session ? _session.getState() : null;
+        const spActive = !!(st && st.starPower && st.starPower.active);
+        const meta = _session ? _session.meta : null;
+
         // ── Lane backgrounds (vertical columns) ─────────────────────────
         for (let i = 0; i < laneLayout.length; i++) {
             const ll = laneLayout[i];
@@ -1561,6 +2641,27 @@ function createFactory() {
             }
         }
 
+        // Star power active: a blue wash over the lanes.
+        if (spActive) {
+            const last = laneLayout[laneLayout.length - 1];
+            ctx.fillStyle = 'rgba(80,170,255,0.10)';
+            ctx.fillRect(laneLayout[0].x, topY, last.x + last.w - laneLayout[0].x, nowLineY + 20);
+        }
+        // Fills (star power activation): a green band while star power is
+        // ready; the fill ends on the note that activates it.
+        if (meta && meta.activation.length && st && st.starPower && st.starPower.canActivate && !spActive) {
+            const last = laneLayout[laneLayout.length - 1];
+            for (const f of meta.activation) {
+                if (f.end < t - 0.3 || f.start > t + VISIBLE_SECONDS) continue;
+                const y0 = _timeToY(Math.min(f.end - t, VISIBLE_SECONDS), nowLineY, topY);
+                const y1 = _timeToY(Math.max(f.start - t, -0.3), nowLineY, topY);
+                ctx.fillStyle = 'rgba(56,255,168,0.10)';
+                ctx.fillRect(laneLayout[0].x, y0, last.x + last.w - laneLayout[0].x, y1 - y0);
+                ctx.fillStyle = 'rgba(56,255,168,0.7)';
+                ctx.fillRect(laneLayout[0].x, y0 - 1, last.x + last.w - laneLayout[0].x, 2);
+            }
+        }
+
         // ── Kick lane separator ─────────────────────────────────────────
         if (kickIdx >= 0) {
             const kickLL = laneLayout[kickIdx];
@@ -1603,8 +2704,16 @@ function createFactory() {
             _drawLaneLabels(ctx, laneLayout, nowLineY, H);
         }
 
-        if (_cfg.hitDetection && (_hits + _misses) > 0) {
-            _drawAccuracyHUD(ctx, W, H);
+        if (message) {
+            _drawMessage(ctx, W, nowLineY, message);
+            return;
+        }
+
+        let hudLeft = null;
+        if (_cfg.hitDetection && _session) hudLeft = _drawScoreHud(ctx, W);
+        else {
+            _placeTimingBtn(null);
+            if (_cfg.hitDetection && (_hits + _misses) > 0) _drawAccuracyHUD(ctx, W, H);
         }
 
         // MIDI indicator — show on the focused panel only; non-focused
@@ -1620,6 +2729,8 @@ function createFactory() {
             ctx.textBaseline = 'middle';
             ctx.fillText('MIDI', W - 28, 16);
         }
+
+        _drawDifficulty2D(ctx, W, hudLeft);
     }
 
     function _drawScrollingNotes(ctx, notes, chords, t, laneLayout, nowLineY, topY /* , W, H */) {
@@ -1630,7 +2741,7 @@ function createFactory() {
                 const dt = n.t - t;
                 if (dt > VISIBLE_SECONDS + 1) break;
                 if (dt < -1) continue;
-                allNotes.push({ midi: noteToMidi(n.s, n.f), t: n.t, ac: n.ac });
+                allNotes.push({ midi: noteToMidi(n.s, n.f), t: n.t, ac: n.ac, mt: n.mt });
             }
         }
         if (chords) {
@@ -1639,11 +2750,23 @@ function createFactory() {
                 if (dt > VISIBLE_SECONDS + 1) break;
                 if (dt < -1) continue;
                 for (const cn of (c.notes || [])) {
-                    allNotes.push({ midi: noteToMidi(cn.s, cn.f), t: c.t, ac: cn.ac });
+                    allNotes.push({ midi: noteToMidi(cn.s, cn.f), t: c.t, ac: cn.ac, mt: cn.mt });
                 }
             }
         }
 
+        // Star power phrases still alive: their notes are drawn silver-white.
+        // Resolved once per frame for the phrases on screen.
+        const spRanges = (_session && _session.engine && _session.meta) ? _session.meta.starPower : null;
+        const livePhrases = spRanges
+            ? spRanges.filter(r => r.end > t - 1 && r.start < t + VISIBLE_SECONDS + 1 && !_spFailed(r)) : [];
+        const inLivePhrase = (nt) => {
+            for (const r of livePhrases) {
+                if (nt >= r.start - 0.0001 && nt < r.end - 0.0001) return true;
+            }
+            return false;
+        };
+
         for (const n of allNotes) {
             const laneIdx = _songNoteToLaneIdx(n.midi);
             if (laneIdx < 0 || laneIdx >= laneLayout.length) continue;
@@ -1667,8 +2790,9 @@ function createFactory() {
             let [cr, cg, cb] = lane.color;
             if (useHitColor) { cr = 0; cg = 1; cb = 0.27; }
             else if (useMissColor) { cr = 0.33; cg = 0.33; cb = 0.4; }
+            else if (inLivePhrase(n.t)) { cr = 0.86; cg = 0.95; cb = 1; }
 
-            const velFactor = n.ac ? 1.3 : 1.0;
+            const velFactor = n.ac ? 1.3 : (n.mt ? 0.75 : 1.0);
             const cx = ll.centerX;
 
             if (lane.id === 'kick') {
@@ -1824,6 +2948,193 @@ function createFactory() {
         }
     }
 
+    // A star power phrase the player already broke (a miss inside it).
+    function _spFailed(range) {
+        if (!_session || !_session.engine || !_session.gems.length) return false;
+        const gems = _session.gems;
+        const [i0, i1] = _h.visibleRange(gems, range.start - 0.0001, range.end - 0.0001);
+        for (let i = i0; i < i1; i++) {
+            // Auto notes and notes before a rebuild point aren't scored: skip them.
+            const info = gems[i].auto ? null : _session.engine.noteInfo(gems[i].id);
+            if (info) return !info.starPower;
+        }
+        return false;
+    }
+
+    // Engine HUD: score, multiplier, streak, stars and the star power bar
+    // (top centre), plus the live drum-solo percentage.
+    function _drawScoreHud(ctx, W) {
+        const st = _session.getState();
+        if (!st || !_h) return;
+        const m = _h.hudModel(st);
+        const bonus = _session.getBonus ? _session.getBonus() : null;
+        const score = _h.formatScore((st.score || 0) + (bonus ? bonus.total : 0));
+        ctx.save();
+        const y = 6, h = 24;
+        ctx.font = 'bold 13px sans-serif';
+        const scoreW = Math.max(70, ctx.measureText(score).width + 16);
+        const streakText = m.streakText + ' streak';
+        ctx.font = 'bold 11px sans-serif';
+        const streakW = ctx.measureText(streakText).width + 16;
+        const multW = 34, spW = 80, starW = 66, gap = 6;
+        const total = scoreW + streakW + multW + spW + starW + gap * 4;
+        let x = Math.max(120, (W - total) / 2);
+        const left = x;
+        const box = (w) => { ctx.fillStyle = 'rgba(8,8,20,0.78)'; _roundRect(ctx, x, y, w, h, 6); ctx.fill(); };
+        ctx.textBaseline = 'middle';
+        ctx.textAlign = 'center';
+        // multiplier
+        box(multW);
+        ctx.font = 'italic bold 13px sans-serif';
+        ctx.fillStyle = m.multiplierColor;
+        ctx.fillText(m.multiplierText, x + multW / 2, y + h / 2);
+        x += multW + gap;
+        // score
+        box(scoreW);
+        ctx.font = 'bold 13px sans-serif';
+        ctx.fillStyle = '#f1f5f9';
+        ctx.fillText(score, x + scoreW / 2, y + h / 2);
+        x += scoreW + gap;
+        // streak
+        box(streakW);
+        ctx.font = 'bold 11px sans-serif';
+        ctx.fillStyle = m.fullCombo && m.streak > 0 ? '#ffc531' : '#c8ccd8';
+        ctx.fillText(streakText, x + streakW / 2, y + h / 2);
+        x += streakW + gap;
+        // stars
+        box(starW);
+        ctx.font = '12px sans-serif';
+        ctx.textAlign = 'left';
+        for (let i = 0; i < 5; i++) {
+            ctx.fillStyle = m.gold ? '#ffcf3a' : (i < m.stars ? '#f4f6ff' : '#3a4060');
+            ctx.fillText('★', x + 5 + i * 12, y + h / 2);
+        }
+        ctx.textAlign = 'center';
+        x += starW + gap;
+        // star power bar
+        box(spW);
+        ctx.fillStyle = 'rgba(255,255,255,0.08)';
+        ctx.fillRect(x + 6, y + 9, spW - 12, 6);
+        ctx.fillStyle = m.spActive ? '#7fe6ff' : (m.spReady ? '#bff3ff' : '#4aa8ff');
+        ctx.fillRect(x + 6, y + 9, (spW - 12) * m.spAmount, 6);
+        if (m.spReady && !m.spActive) {
+            ctx.strokeStyle = 'rgba(191,243,255,0.8)';
+            ctx.lineWidth = 1;
+            ctx.strokeRect(x + 5.5, y + 8.5, spW - 11, 7);
+        }
+        // Lines under the HUD: live drum solo, star power hint, timing meter.
+        let ly = y + h + 6;
+        const solo = bonus && bonus.soloLive && bonus.soloLive.active ? bonus.soloLive : null;
+        if (solo) {
+            const pct = solo.n ? Math.round(100 * solo.h / solo.n) : 100;
+            const text = 'SOLO ' + pct + '%  ' + solo.h + '/' + solo.n;
+            ctx.font = 'bold 12px sans-serif';
+            const sw = ctx.measureText(text).width + 18;
+            const sx = (W - sw) / 2;
+            ctx.fillStyle = 'rgba(60,30,110,0.85)';
+            _roundRect(ctx, sx, ly, sw, 20, 6);
+            ctx.fill();
+            ctx.fillStyle = '#e6dbff';
+            ctx.fillText(text, W / 2, ly + 10);
+            ly += 26;
+        }
+        const hint = _h.starPowerHint(_session.meta, st, _spPadName());
+        if (hint) {
+            ctx.font = 'bold 11px sans-serif';
+            const hw = ctx.measureText(hint).width + 18;
+            ctx.fillStyle = 'rgba(20,50,80,0.85)';
+            _roundRect(ctx, (W - hw) / 2, ly, hw, 20, 6);
+            ctx.fill();
+            ctx.fillStyle = '#bff3ff';
+            ctx.fillText(hint, W / 2, ly + 10);
+            ly += 26;
+        }
+        ctx.restore();
+        _drawTimingMeter2D(ctx, left, ly, bonus);
+        return left;
+    }
+
+    // Early/late meter (2D view): the last hits as ticks on a ±100 ms bar
+    // (blue early, orange late), their median, and the input offset that
+    // would centre them with an Apply button (a DOM button over the pill).
+    function _drawTimingMeter2D(ctx, x, y, bonus) {
+        const offs = bonus && bonus.offsets ? bonus.offsets : [];
+        if (!offs.length || !_h) { _placeTimingBtn(null); return; }
+        const sum = _h.timingSummary(offs, _cfg.inputOffsetMs);
+        const EARLY = '#66c7ff', LATE = '#ff9a40', OK = '#e5e7eb', RANGE = 100, DEAD = 10;
+        const col = (ms) => (Math.abs(ms) < DEAD ? OK : ms < 0 ? EARLY : LATE);
+        const h = 22, bw = 110, bh = 8;
+        ctx.save();
+        ctx.textBaseline = 'middle';
+        ctx.textAlign = 'left';
+        ctx.font = 'bold 11px sans-serif';
+        const word = sum.label;
+        const ww = ctx.measureText(word).width;
+        const applyText = sum.suggest != null ? 'Apply ' + sum.suggest + ' ms' : '';
+        ctx.font = 'bold 10px sans-serif';
+        const aw = applyText ? ctx.measureText(applyText).width + 16 : 0;
+        const total = 52 + bw + 10 + ww + (aw ? 10 + aw : 0) + 12;
+        ctx.fillStyle = 'rgba(8,8,20,0.78)';
+        _roundRect(ctx, x, y, total, h, 6);
+        ctx.fill();
+        let cx = x + 8;
+        ctx.font = 'bold 9px sans-serif';
+        ctx.fillStyle = '#7a84a6';
+        ctx.fillText('TIMING', cx, y + h / 2);
+        cx += 44;
+        const by = y + (h - bh) / 2;
+        ctx.fillStyle = 'rgba(255,255,255,0.08)';
+        ctx.fillRect(cx, by, bw, bh);
+        ctx.fillStyle = 'rgba(160,170,200,0.5)';
+        ctx.fillRect(cx + bw / 2 - 0.5, by, 1, bh);
+        const px = (ms) => cx + bw / 2 + (bw / 2) * Math.max(-1, Math.min(1, ms / RANGE));
+        offs.forEach((ms, i) => {
+            ctx.globalAlpha = 0.25 + 0.75 * (i + 1) / offs.length;
+            ctx.fillStyle = col(ms);
+            ctx.fillRect(px(ms) - 1, by + 1, 2, bh - 2);
+        });
+        ctx.globalAlpha = 1;
+        ctx.fillStyle = col(sum.median);
+        ctx.fillRect(px(sum.median) - 1.5, by - 3, 3, bh + 6);
+        cx += bw + 10;
+        ctx.font = 'bold 11px sans-serif';
+        ctx.fillText(word, cx, y + h / 2);
+        cx += ww + 10;
+        if (aw) {
+            const ph = 16, py = y + (h - ph) / 2;
+            ctx.fillStyle = 'rgba(30,40,70,0.95)';
+            _roundRect(ctx, cx, py, aw, ph, ph / 2);
+            ctx.fill();
+            ctx.strokeStyle = '#7f8cc0';
+            ctx.lineWidth = 1;
+            ctx.stroke();
+            ctx.fillStyle = '#f1f5f9';
+            ctx.textAlign = 'center';
+            ctx.font = 'bold 10px sans-serif';
+            ctx.fillText(applyText, cx + aw / 2, y + h / 2 + 0.5);
+            ctx.restore();
+            _placeTimingBtn({ x: cx, y: py, w: aw, h: ph }, sum.suggest);
+            return;
+        }
+        ctx.restore();
+        _placeTimingBtn(null);
+    }
+
+    function _drawMessage(ctx, W, nowLineY, text) {
+        ctx.save();
+        ctx.font = 'bold 15px sans-serif';
+        const tw = ctx.measureText(text).width + 32;
+        const y = Math.max(40, nowLineY * 0.4);
+        ctx.fillStyle = 'rgba(8,8,20,0.85)';
+        _roundRect(ctx, (W - tw) / 2, y - 18, tw, 36, 8);
+        ctx.fill();
+        ctx.fillStyle = '#c8ccd8';
+        ctx.textAlign = 'center';
+        ctx.textBaseline = 'middle';
+        ctx.fillText(text, W / 2, y);
+        ctx.restore();
+    }
+
     function _drawAccuracyHUD(ctx, W /* , H */) {
         const total = _hits + _misses;
         if (total === 0) return;
@@ -1864,7 +3175,23 @@ function createFactory() {
         }
         _drumCanvas = null;
         _drumCtx = null;
+        _removeDifficultyUI();
+        _unwireBus();
         _highwayCanvas = null;
+        _hwVisible = true;
+        _session = null;
+        _chartRefs = null;
+        _metaKey = undefined;
+        _metaCache = null;
+        _diffOptions = null;
+        _diff = null;
+        _badge = null;
+        _diffUiKey = '';
+        _lvlMemo = null;
+        _has2xMemo = null;
+        _autoRelease(_instanceId);
+        if (_frameClock) _frameClock.reset();
+        _frameT = NaN;
 
         _removeSettingsPanel();
         _removeSettingsGear();
@@ -1934,6 +3261,10 @@ function createFactory() {
             _injectSettingsGear();
             _applyCanvasDims();
             window.addEventListener('resize', _onWinResize);
+            _wireBus();
+            _ensureBadge();
+            _wireDifficultyKey();
+            _wireStarPowerKey();
 
             const ss = window.slopsmithSplitscreen;
             // Subscribe only when splitscreen is FULLY supported and
@@ -1961,6 +3292,7 @@ function createFactory() {
             _synthInit();
 
             _isReady = true;
+            _startScoring();
 
             // Determine focus BEFORE resuming the MIDI handler so
             // _activeInstance is populated when onmidimessage gets
@@ -2019,9 +3351,44 @@ function createFactory() {
                 drumNotes = bundle.notes;
                 drumChords = bundle.chords;
             }
+            // This highway's smoothed clock (falls back to the raw sample
+            // until session.js has loaded).
+            const t = _frameClock ? _frameClock.tick(+bundle.currentTime || 0, bundle.isPlaying, _now()) : (+bundle.currentTime || 0);
+            _frameT = t;
+            // Not a drum chart (no drum tab, and the arrangement isn't
+            // Drums): e.g. a splitscreen panel left on the Drum Highway
+            // falls back to Lead on a song without a Drums part. Guitar
+            // notes read as drum notes (string * 24 + fret) gave a few
+            // random gems to score; show a message and play / score nothing.
+            const hasTab = !!(dt && Array.isArray(dt.hits));
+            if (isReady && !hasTab && !_isDrumsArrangement(bundle.songInfo)) {
+                _latestNotes = [];
+                _latestChords = [];
+                _latestTime = t;
+                _autoRelease(_instanceId);
+                _placeBadge(null);
+                _placeTimingBtn(null);
+                _draw([], [], t, bundle.beats, _noDrumsMessage(bundle.songInfo));
+                return;
+            }
+            if (isReady) {
+                // Difficulty: Expert+ = the full chart, Expert drops the
+                // double kicks, Easy/Medium/Hard come from the tab's levels.
+                _syncMeta(hasTab ? dt : null);
+                const lv = _applyDifficulty(bundle, drumNotes, drumChords);
+                drumNotes = lv.notes;
+                drumChords = lv.chords;
+            }
             _latestNotes = drumNotes;
             _latestChords = drumChords;
-            _latestTime = bundle.currentTime;
+            _latestTime = t;
+            if (isReady) {
+                _scheduleAutoSounds(drumNotes, drumChords);
+                _syncSession(bundle, drumNotes, drumChords, t);
+                _drainSessionEvents();
+            } else {
+                _autoRelease(_instanceId);
+            }
 
             // Loading / reconnect window — chart isn't confirmed
             // yet. Paint the plugin's base background so the
@@ -2035,10 +3402,12 @@ function createFactory() {
                     _drumCtx.fillStyle = '#040408';
                     _drumCtx.fillRect(0, 0, W, H);
                 }
+                _placeBadge(null);
+                _placeTimingBtn(null);
                 return;
             }
 
-            _draw(drumNotes, drumChords, bundle.currentTime, bundle.beats);
+            _draw(drumNotes, drumChords, t, bundle.beats);
         },
         resize(/* w, h */) {
             if (!_isReady) return;
@@ -2074,11 +3443,117 @@ function createFactory() {
         // Internal hooks used by module-level MIDI router + device-swap.
         _handleDrumHit,
         _releaseAllSounding,
+        // Called by the module-level setters for every live instance.
+        _difficultyChanged,
+        _proCymbalsChanged,
+        _assistsChanged,
+        _inputOffsetChanged,
+        _isVisible,
+        // Read-only snapshots for debugging / tools: engine state
+        // (DrumsEngine.getState()), the difficulty in use and auto lanes.
+        _engineState() { return _session ? _session.getState() : null; },
+        _difficulty() { return _diff ? Object.assign({ options: _diffOptions }, _diff) : null; },
+        _autoLanes() { return Object.assign({}, _auto); },
     };
 
     return instance;
 }
 
+// The selected arrangement is a drum part (by name).
+function _isDrumsArrangement(si) {
+    if (!si) return false;
+    if (si.arrangement && DRUMS_PATTERNS.test(si.arrangement)) return true;
+    if (Array.isArray(si.arrangements)) {
+        const arr = si.arrangements.find(a => a && a.index === si.arrangement_index);
+        if (arr && DRUMS_PATTERNS.test(arr.name || '')) return true;
+    }
+    return false;
+}
+
+// What the drum view says on a part that is not drums.
+function _noDrumsMessage(si) {
+    si = si || {};
+    const hasDrums = Array.isArray(si.arrangements)
+        && si.arrangements.some((a) => a && DRUMS_PATTERNS.test(a.name || ''));
+    return hasDrums ? 'Pick the Drums part: ' + (si.arrangement || 'this part') + ' is not drums'
+        : 'This song has no drums';
+}
+
+// ── End-of-song results card ──────────────────────────────────────────
+// Final score (engine score + session bonuses), stars, accuracy, best streak
+// and where the points came from: notes x multiplier, star power, accents /
+// ghosts, spot-on timing, rolls and drum solos. The best score per song and
+// difficulty is kept in localStorage ("drums.best:<song>|<difficulty>").
+// Shown once per song end, only when the player hit something.
+let _endCardAt = -Infinity;
+function _drumsEndCard(session, badge) {
+    const st = session && session.getState ? session.getState() : null;
+    if (!st || !(st.notesHit > 0)) return null;
+    if (performance.now() - _endCardAt < 2000) return null;   // one card per song end
+    _endCardAt = performance.now();
+    const b = (session.getBonus && session.getBonus()) || { total: 0, timing: 0, rolls: 0, solo: 0, perfect: 0, runs: [], solos: [] };
+    const bus = _bus();
+    const cs = (bus && bus.currentSong) || {};
+    const diff = badge && badge.text ? badge.text : 'EXPERT';
+    const total = Math.round((st.score || 0) + (b.total || 0));
+    const key = 'drums.best:' + (cs.filename || cs.title || '') + '|' + diff;
+    let prev = null;
+    try { prev = Number(localStorage.getItem(key)) || null; } catch (_) { /* storage blocked */ }
+    const isBest = prev == null || total > prev;
+    if (isBest) { try { localStorage.setItem(key, String(total)); } catch (_) { /* storage blocked */ } }
+    const n = (x) => Math.round(x || 0).toLocaleString('en-US');
+    const esc = (x) => String(x == null ? '' : x).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+    const resolved = st.notesHit + st.notesMissed;
+    const acc = resolved ? 100 * st.notesHit / resolved : 100;
+    const stars = Math.floor(st.stars || 0), gold = (st.stars || 0) >= 6;
+    const starHtml = Array.from({ length: 5 }, (_, i) =>
+        `<span style="color:${gold ? '#ffcf3a' : i < stars ? '#f4f6ff' : '#3a4060'}">★</span>`).join('');
+    const chip = (label, col) => `<span style="font-size:12px;padding:3px 9px;border-radius:10px;background:rgba(255,255,255,.06);color:${col}">${esc(label)}</span>`;
+    const sp = st.starPowerScore || 0;
+    const chips = [
+        chip('notes × multiplier +' + n((st.score || 0) - sp), '#f1f5f9'),
+        sp ? chip('star power +' + n(sp), '#8fe6ff') : '',
+        (st.totalAccents || st.totalGhosts) ? chip('dynamics: ' + (st.accentsHit || 0) + '/' + (st.totalAccents || 0) + ' accents, '
+            + (st.ghostsHit || 0) + '/' + (st.totalGhosts || 0) + ' ghosts', '#b77bff') : '',
+        b.timing ? chip('spot-on timing +' + n(b.timing) + ' (' + b.perfect + ' hits)', '#ffc531') : '',
+        b.rolls ? chip('rolls +' + n(b.rolls) + (b.runs && b.runs.length ? ' (' + b.runs.map((r) => r.h + '/' + r.n).join(', ') + ')' : ''), '#ff9a40') : '',
+        b.solo ? chip('solos +' + n(b.solo), '#c9b6ff') : '',
+    ].join('');
+    const solos = (b.solos || []).map((x) => `<div style="color:#c9b6ff;font-size:13px">${esc(x.rating)} ${Number(x.pct).toFixed(2)}% (${x.h}/${x.n}) · +${n(x.bonus)}</div>`).join('');
+    const ov = document.createElement('div');
+    ov.className = 'drums-endcard';
+    ov.setAttribute('role', 'dialog');
+    ov.setAttribute('aria-label', 'Drums results');
+    ov.style.cssText = 'position:fixed;inset:0;z-index:300;display:flex;align-items:center;justify-content:center;background:rgba(0,0,0,.55);font-family:system-ui,sans-serif';
+    ov.innerHTML = `<div style="width:30rem;max-width:92vw;background:#0e1322;border:1px solid #2b3556;border-radius:14px;padding:22px 24px;color:#cbd5e1;text-align:center;box-shadow:0 20px 60px rgba(0,0,0,.6)">
+        <div style="font-size:12px;letter-spacing:3px;color:#8b95a5">DRUMS · ${esc(diff)}</div>
+        ${cs.title ? `<div style="font-size:17px;color:#f1f5f9;margin-top:2px">${esc(cs.title)}${cs.artist ? `<span style="color:#8b95a5"> — ${esc(cs.artist)}</span>` : ''}</div>` : ''}
+        <div style="font:900 46px/1.1 system-ui,sans-serif;color:${isBest ? '#ffc531' : '#f1f5f9'};margin-top:12px">${n(total)}</div>
+        <div style="font-size:12px;color:#8b95a5">${isBest ? '<b style="color:#ffc531">NEW BEST SCORE</b>' + (prev != null ? ' · previous ' + n(prev) : '') : 'best ' + n(prev)}</div>
+        <div style="font-size:26px;margin-top:6px;letter-spacing:4px">${starHtml}</div>
+        <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:6px;margin:14px 0">
+            <div><div style="font-weight:800;font-size:20px;color:#f1f5f9">${acc.toFixed(2)}%</div><div style="font-size:11px;color:#8b95a5">accuracy</div></div>
+            <div><div style="font-weight:800;font-size:20px;color:#f1f5f9">${st.notesHit} / ${st.totalNotes}</div><div style="font-size:11px;color:#8b95a5">notes hit</div></div>
+            <div><div style="font-weight:800;font-size:20px;color:${st.fullCombo ? '#ffc531' : '#f1f5f9'}">${st.fullCombo ? 'FC' : st.maxCombo}</div><div style="font-size:11px;color:#8b95a5">${st.fullCombo ? 'full combo!' : 'best streak'}</div></div>
+        </div>
+        <div style="display:flex;flex-wrap:wrap;gap:6px;justify-content:center;margin-bottom:8px">${chips}</div>
+        ${solos}
+        ${st.overhits ? `<div style="font-size:12px;color:#8b95a5;margin-top:4px">${st.overhits} overhit${st.overhits > 1 ? 's' : ''}</div>` : ''}
+        <button type="button" class="drums-endcard-close" style="margin-top:14px;padding:6px 22px;border-radius:8px;border:1px solid #3a4670;background:#1b2440;color:#f1f5f9;cursor:pointer">Close</button>
+    </div>`;
+    const onKey = (e) => { if (e.key === 'Escape' || e.key === 'Enter') { e.preventDefault(); close(); } };
+    function close() {
+        ov.remove();
+        document.removeEventListener('keydown', onKey, true);
+        if (bus && typeof bus.off === 'function') { try { bus.off('song:loading', close); } catch (_) { /* ignore */ } }
+    }
+    ov.addEventListener('click', (e) => { if (e.target === ov || (e.target && e.target.closest && e.target.closest('.drums-endcard-close'))) close(); });
+    document.addEventListener('keydown', onKey, true);
+    document.body.appendChild(ov);
+    if (bus) { try { bus.on('song:loading', close); } catch (_) { /* ignore */ } }
+    return { total, best: isBest, previous: prev, accuracy: acc, element: ov, close };
+}
+
 createFactory.matchesArrangement = function (songInfo) {
     if (!songInfo) return false;
     // First-class signal: sloppaks with a top-level `drum_tab:` manifest
@@ -2106,8 +3581,15 @@ if (typeof module !== 'undefined' && module.exports) {
     module.exports = {
         noteToMidi, _rgbStr, _validateCustomMapping, _drumTabHitsToNotes,
         _applyLanePreset, _getActiveDrumMap, _midiToLaneIdx, _songNoteToLaneIdx,
-        _midiResolveSaved, DRUM_LANES, PIECE_DEFAULT_MIDI,
+        _midiResolveSaved, DRUM_LANES, PIECE_DEFAULT_MIDI, KICK2X_MIDI,
         matchesArrangement: createFactory.matchesArrangement,
+        DIFFICULTY_IDS, STORE_KEYS, AUTO_LEVEL_IDS, TIMING_PRESETS, TIMING_IDS,
+        _difficultyPref: () => _cfg.difficulty, _cfg: () => _cfg,
+        _setDifficulty, _setAssist, _saveCfg,
+        _autoAt, _laneIsAuto, _timingParams, _autoNotesBetween, _isAutoMidi,
+        _engineVelocity, _setInputOffset, _setSpPad, _spPadName, SP_PAD_CHOICES,
+        _loadScoring, _routeTarget, _isDrumsArrangement, _noDrumsMessage, _drumsEndCard,
+        _instances: () => _instances, _midiOnMessage,
     };
 }
 
diff --git a/tests/engine.test.js b/tests/engine.test.js
new file mode 100644
index 0000000..5398372
--- /dev/null
+++ b/tests/engine.test.js
@@ -0,0 +1,690 @@
+'use strict';
+// Tests for engine.js (the LGPL-3.0 port of YARG.Core's drums engine).
+// Some scenarios are ported from YARG.Core.UnitTests/Engine/DrumEngineTester.cs and DrumsStatsTests.cs.
+// Copyright (c) YARC (YARG) contributors
+// Licensed under the GNU Lesser General Public License v3.0
+// (see https://github.com/YARC-Official/YARG.Core/blob/master/LICENSE and ../LICENSE.LGPL-3.0).
+// Ported and modified to JavaScript (node:test) for the feedBack drums plugin.
+// Run: node tests/engine.test.js
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const fs = require('node:fs');
+const vm = require('node:vm');
+
+const ENGINE_PATH = path.join(__dirname, '..', 'assets', 'engine.js');
+const D = require(ENGINE_PATH);
+const { PAD } = D;
+
+const KICK = 36, SNARE = 38, HAT = 42, CRASH = 49, RIDE = 51, HI_TOM = 48, LOW_TOM = 45, FLOOR_TOM = 41;
+
+function w(t, midi, extra) {
+    return Object.assign({ t, s: (midi / 24) | 0, f: midi % 24 }, extra || {});
+}
+// N single snare notes starting at `start`, `gap` seconds apart.
+function snares(n, start = 1, gap = 0.5) {
+    const out = [];
+    for (let i = 0; i < n; i++) out.push(w(start + i * gap, SNARE));
+    return out;
+}
+function engineFor(wire, opts) {
+    return D.create(D.decodeNotes(wire, opts && opts.decode), opts);
+}
+function collect(eng, names) {
+    const log = [];
+    for (const n of names) eng.on(n, (p) => log.push([n, p]));
+    return log;
+}
+// Hit every note of the chart on time.
+function playAll(eng) {
+    for (const c of eng.chords) for (const n of c.notes) eng.hit(c.t, n.pad, { cymbal: n.cymbal });
+}
+
+// ── decodeNotes / padFromMidi ──────────────────────────────────────────────
+
+test('decodeNotes maps every General MIDI drum number to pad + cymbal', () => {
+    const expected = {
+        36: [PAD.KICK, false], 35: [PAD.KICK, false],
+        38: [PAD.RED, false], 37: [PAD.RED, false], 40: [PAD.RED, false],
+        42: [PAD.YELLOW, true], 46: [PAD.YELLOW, true],
+        48: [PAD.YELLOW, false], 50: [PAD.YELLOW, false],
+        45: [PAD.BLUE, false], 47: [PAD.BLUE, false],
+        41: [PAD.GREEN, false], 43: [PAD.GREEN, false], 58: [PAD.GREEN, false],
+        51: [PAD.BLUE, true], 53: [PAD.BLUE, true], 59: [PAD.BLUE, true],
+        49: [PAD.GREEN, true], 57: [PAD.GREEN, true], 55: [PAD.GREEN, true], 52: [PAD.GREEN, true],
+    };
+    const midis = Object.keys(expected).map(Number);
+    const chart = D.decodeNotes(midis.map((m, i) => w(i, m)));
+    assert.equal(chart.notes.length, midis.length);
+    for (const n of chart.notes) {
+        assert.deepEqual([n.pad, n.cymbal], expected[n.midi], 'midi ' + n.midi);
+        assert.equal(n.kick2x, n.midi === 35);
+        const live = D.padFromMidi(n.midi);
+        assert.deepEqual([live.pad, live.cymbal], expected[n.midi]);
+    }
+    // unknown numbers are dropped
+    assert.equal(D.decodeNotes([w(0, 60), w(1, 39)]).notes.length, 0);
+    assert.equal(D.padFromMidi(60), null);
+});
+
+test('decodeNotes: 44 hi-hat pedal dropped unless includeHatPedal', () => {
+    assert.equal(D.decodeNotes([w(0, 44)]).notes.length, 0);
+    const on = D.decodeNotes([w(0, 44)], { includeHatPedal: true });
+    assert.equal(on.notes.length, 1);
+    assert.deepEqual([on.notes[0].pad, on.notes[0].cymbal], [PAD.YELLOW, true]);
+    assert.equal(D.padFromMidi(44), null);
+    assert.deepEqual(D.padFromMidi(44, { includeHatPedal: true }), { pad: PAD.YELLOW, cymbal: true });
+});
+
+test('decodeNotes: kick 2x (35) kept by default, dropped with kick2x:false', () => {
+    const wire = [w(0, KICK), w(0.5, 35)];
+    assert.equal(D.decodeNotes(wire).notes.length, 2);
+    const off = D.decodeNotes(wire, { kick2x: false });
+    assert.equal(off.notes.length, 1);
+    assert.equal(off.notes[0].midi, 36);
+});
+
+test('decodeNotes: accent / ghost dynamics', () => {
+    const c = D.decodeNotes([w(0, SNARE, { ac: true }), w(1, SNARE, { mt: true }), w(2, SNARE)]);
+    assert.deepEqual(c.notes.map(n => n.dyn), ['accent', 'ghost', null]);
+});
+
+test('decodeNotes: sorts by time, groups notes within 1ms into chords, assigns ids', () => {
+    const c = D.decodeNotes([w(2, SNARE), w(1.0005, CRASH), w(1, KICK), w(1.01, HAT), w(1, KICK)]);
+    assert.deepEqual(c.notes.map(n => n.t), [1, 1.0005, 1.01, 2]); // duplicate kick in chord dropped
+    assert.deepEqual(c.notes.map(n => n.id), [0, 1, 2, 3]);
+    assert.equal(c.chords.length, 3);
+    assert.deepEqual(c.chords[0].notes.map(n => n.midi), [KICK, CRASH]);
+    assert.equal(c.chords[0].t, 1);
+    assert.deepEqual(c.notes.map(n => n.chord), [0, 0, 1, 2]);
+    // tolerates junk
+    assert.deepEqual(D.decodeNotes(null), { notes: [], chords: [] });
+    assert.equal(D.decodeNotes([null, { t: 'x', s: 1, f: 14 }, w(0, SNARE)]).notes.length, 1);
+});
+
+// ── Hit window / matching ────────────────────────────────────────────────
+
+test('defaultParams are YARG EnginePreset.Default drums values', () => {
+    const p = D.defaultParams();
+    assert.equal(p.hitWindow.maxWindow, 0.14);
+    assert.equal(p.hitWindow.minWindow, 0.14);
+    assert.equal(p.hitWindow.isDynamic, false);
+    assert.equal(p.hitWindow.frontToBackRatio, 1.0);
+    assert.equal(p.maxMultiplier, 4);
+    assert.equal(p.velocityThreshold, 0.35);
+    assert.equal(p.situationalVelocityWindow, 1.5);
+    assert.equal(p.starPowerMeasures, 8);
+    assert.deepEqual(p.starMultiplierThresholds, [0.06, 0.12, 0.2, 0.45, 0.75, 1.09]);
+    const eng = engineFor(snares(1));
+    const hw = eng.hitWindow();
+    assert.ok(Math.abs(hw.front + 0.07) < 1e-12 && Math.abs(hw.back - 0.07) < 1e-12);
+});
+
+test('on-time hit scores 60 (pro), records offset and noteState', () => {
+    const eng = engineFor(snares(1));
+    const r = eng.hit(1, PAD.RED);
+    assert.equal(r.type, 'hit');
+    assert.equal(r.id, 0);
+    assert.equal(r.offset, 0);
+    const s = eng.getState();
+    assert.equal(s.score, 60);
+    assert.equal(s.combo, 1);
+    assert.equal(s.notesHit, 1);
+    assert.equal(eng.noteState(0), 'hit');
+    assert.equal(eng.noteInfo(0).offset, 0);
+});
+
+test('early/late hits inside the 70ms window hit; outside do not', () => {
+    for (const dt of [-0.069, 0.069, -0.07, 0.07]) {
+        const eng = engineFor(snares(2, 1, 1));
+        const r = eng.hit(1 + dt, PAD.RED);
+        assert.equal(r.type, 'hit', 'offset ' + dt);
+        assert.ok(Math.abs(r.offset - dt) < 1e-9);
+    }
+    // too early: nothing in window; before first note so overhit is suppressed (YARG Overhit: NoteIndex == 0)
+    let eng = engineFor(snares(2, 1, 1));
+    assert.deepEqual(eng.hit(1 - 0.071, PAD.RED), { type: 'ignored', reason: 'before-first-note' });
+    assert.equal(eng.noteState(0), null);
+    // too late: the note is missed first, then the hit becomes an overhit
+    eng = engineFor([w(0.5, KICK), ...snares(2, 1, 1)]);
+    eng.hit(0.5, PAD.KICK);
+    assert.equal(eng.hit(1.071, PAD.RED).type, 'overhit');
+    assert.equal(eng.noteState(1), 'miss');
+    assert.equal(eng.getState().overhits, 1);
+});
+
+test('update() registers misses for notes past the back of the window', () => {
+    const eng = engineFor(snares(3, 1, 1));
+    const log = collect(eng, ['miss']);
+    eng.update(1.07);
+    assert.equal(eng.noteState(0), null); // exactly at back end is still hittable
+    eng.update(1.0701);
+    assert.equal(eng.noteState(0), 'miss');
+    eng.update(10);
+    assert.equal(log.length, 3);
+    assert.equal(eng.getState().notesMissed, 3);
+});
+
+test('wrong pad inside the window = overhit (combo break, no score change)', () => {
+    const eng = engineFor(snares(5, 1, 0.5));
+    eng.hit(1, PAD.RED);
+    eng.hit(1.5, PAD.RED);
+    const log = collect(eng, ['overhit', 'combo-break']);
+    const before = eng.getState().score;
+    assert.equal(eng.hit(2, PAD.BLUE).type, 'overhit');
+    const s = eng.getState();
+    assert.equal(s.overhits, 1);
+    assert.equal(s.combo, 0);
+    assert.equal(s.score, before);
+    assert.equal(eng.noteState(2), null); // note still hittable
+    assert.equal(eng.hit(2.01, PAD.RED).type, 'hit');
+    // YARG order: ResetCombo runs before OnOverhit
+    assert.deepEqual(log.map(x => x[0]), ['combo-break', 'overhit']);
+    assert.equal(log[0][1].reason, 'overhit');
+    assert.equal(log[0][1].combo, 2);
+});
+
+test('pro drums: cymbal hit on a tom note (and tom on cymbal) is an overhit', () => {
+    const wire = [w(0.5, KICK), w(1, HI_TOM), w(2, HAT), w(3, LOW_TOM), w(4, RIDE), w(5, FLOOR_TOM), w(6, CRASH)];
+    const eng = engineFor(wire);
+    eng.hit(0.5, PAD.KICK);
+    assert.equal(eng.hit(1, PAD.YELLOW, { cymbal: true }).type, 'overhit');
+    assert.equal(eng.hit(1.01, PAD.YELLOW).type, 'hit');
+    assert.equal(eng.hit(2, PAD.YELLOW, { cymbal: false }).type, 'overhit');
+    assert.equal(eng.hit(2.01, PAD.YELLOW, { cymbal: true }).type, 'hit');
+    assert.equal(eng.hit(3, PAD.BLUE, { cymbal: true }).type, 'overhit');
+    assert.equal(eng.hit(4, PAD.BLUE).type, 'overhit');
+    assert.equal(eng.hit(5, PAD.GREEN, { cymbal: true }).type, 'overhit');
+    assert.equal(eng.hit(6, PAD.GREEN).type, 'overhit');
+    assert.equal(eng.getState().overhits, 6);
+});
+
+test('proDrums:false ignores the cymbal/tom distinction and scores 50 per note', () => {
+    const wire = [w(1, HI_TOM), w(2, HAT), w(3, RIDE), w(4, CRASH)];
+    const eng = engineFor(wire, { proDrums: false });
+    assert.equal(eng.hit(1, PAD.YELLOW, { cymbal: true }).type, 'hit');
+    assert.equal(eng.hit(2, PAD.YELLOW, { cymbal: false }).type, 'hit');
+    assert.equal(eng.hit(3, PAD.BLUE).type, 'hit');
+    assert.equal(eng.hit(4, PAD.GREEN, { cymbal: true }).type, 'hit');
+    assert.equal(eng.getState().score, 200);
+    assert.equal(eng.getState().overhits, 0);
+});
+
+test('proDrums:false collapses yellow tom + hat in one chord; dropped id aliases the kept note', () => {
+    const chart = D.decodeNotes([w(1, HI_TOM), w(1, HAT)]);
+    assert.equal(chart.notes.length, 2);
+    const eng = D.create(chart, { proDrums: false });
+    assert.equal(eng.getState().totalNotes, 1);
+    eng.hit(1, PAD.YELLOW);
+    assert.equal(eng.noteState(0), 'hit');
+    assert.equal(eng.noteState(1), 'hit');
+    assert.equal(eng.noteState(99), null);
+});
+
+test('chords: each note hit separately, partial chord -> unhit notes miss, combo per note', () => {
+    const wire = [w(1, KICK), w(1, SNARE), w(1, CRASH), w(2, KICK), w(2, HAT)];
+    const eng = engineFor(wire);
+    assert.equal(eng.hit(1, PAD.KICK).type, 'hit');
+    assert.equal(eng.hit(1.005, PAD.GREEN, { cymbal: true }).type, 'hit');
+    assert.equal(eng.getState().combo, 2);
+    // hitting the same pad again on the partially-hit chord is consumed (no overhit)
+    assert.deepEqual(eng.hit(1.01, PAD.KICK).type, 'ignored');
+    assert.equal(eng.getState().overhits, 0);
+    eng.update(1.5);
+    assert.equal(eng.noteState(1), 'miss');
+    assert.equal(eng.getState().combo, 0);
+    eng.hit(2, PAD.YELLOW, { cymbal: true });
+    eng.hit(2, PAD.KICK);
+    const s = eng.getState();
+    assert.equal(s.notesHit, 4);
+    assert.equal(s.notesMissed, 1);
+    assert.equal(s.combo, 2);
+    assert.equal(s.score, 4 * 60);
+});
+
+test('hitting a later chord inside the window skips (misses) unhit earlier notes', () => {
+    const eng = engineFor([w(1, SNARE), w(1.04, KICK)]);
+    assert.equal(eng.hit(1.03, PAD.KICK).type, 'hit');
+    assert.equal(eng.noteState(0), 'miss');
+    assert.equal(eng.noteState(1), 'hit');
+    assert.equal(eng.getState().combo, 1);
+});
+
+test('one input hits only the oldest matching note in the window', () => {
+    const eng = engineFor([w(1, SNARE), w(1.05, SNARE)]);
+    eng.hit(1.02, PAD.RED);
+    assert.equal(eng.noteState(0), 'hit');
+    assert.equal(eng.noteState(1), null);
+});
+
+// ── Combo / multiplier / score ───────────────────────────────────────────
+
+test('combo -> multiplier: +1x every 10 notes up to 4x; score totals', () => {
+    const eng = engineFor(snares(40));
+    const mults = [];
+    eng.on('multiplier', (p) => mults.push([eng.getState().combo, p.multiplier]));
+    for (let i = 0; i < 40; i++) eng.hit(1 + i * 0.5, PAD.RED);
+    assert.deepEqual(mults, [[10, 2], [20, 3], [30, 4]]);
+    const s = eng.getState();
+    assert.equal(s.multiplier, 4);
+    assert.equal(s.maxMultiplier, 4);
+    assert.equal(s.peakMultiplier, 4);
+    // 9x1 + 10x2 + 10x3 + 11x4 notes at 60 points
+    assert.equal(s.score, 60 * (9 + 20 + 30 + 44));
+    assert.equal(s.maxCombo, 40);
+    assert.equal(s.fullCombo, true);
+
+    const np = engineFor(snares(40), { proDrums: false });
+    for (let i = 0; i < 40; i++) np.hit(1 + i * 0.5, PAD.RED);
+    assert.equal(np.getState().score, 50 * (9 + 20 + 30 + 44));
+});
+
+test('a miss resets combo and multiplier', () => {
+    const eng = engineFor(snares(15));
+    for (let i = 0; i < 12; i++) eng.hit(1 + i * 0.5, PAD.RED);
+    assert.equal(eng.getState().multiplier, 2);
+    const log = collect(eng, ['combo-break', 'miss']);
+    eng.update(1 + 12 * 0.5 + 0.2);
+    const s = eng.getState();
+    assert.equal(s.combo, 0);
+    assert.equal(s.multiplier, 1);
+    assert.equal(s.maxCombo, 12);
+    assert.deepEqual(log.map(x => x[0]), ['combo-break', 'miss']); // YARG: ResetCombo before OnNoteMissed
+});
+
+test('an overhit resets combo and multiplier', () => {
+    const eng = engineFor(snares(15));
+    for (let i = 0; i < 12; i++) eng.hit(1 + i * 0.5, PAD.RED);
+    eng.hit(1 + 12 * 0.5, PAD.KICK);
+    assert.equal(eng.getState().combo, 0);
+    assert.equal(eng.getState().multiplier, 1);
+});
+
+test('overhits are ignored before the first note, after the last, and during a wait countdown', () => {
+    // YARG DrumEngineTester: Overhit_DoesNothingBeforeFirstNote / Overhit_DoesNothingAfterLastNote
+    const eng = engineFor([w(1, SNARE), w(2, SNARE), w(20, SNARE)]);
+    assert.deepEqual(eng.hit(0.5, PAD.BLUE), { type: 'ignored', reason: 'before-first-note' });
+    eng.hit(1, PAD.RED);
+    eng.hit(2, PAD.RED);
+    // 18 s gap >= 9 s WaitCountdown.MIN_SECONDS
+    assert.deepEqual(eng.hit(5, PAD.BLUE), { type: 'ignored', reason: 'countdown' });
+    eng.hit(20, PAD.RED);
+    assert.deepEqual(eng.hit(21, PAD.BLUE), { type: 'ignored', reason: 'after-last-note' });
+    assert.equal(eng.getState().overhits, 0);
+    assert.equal(eng.getState().combo, 3);
+});
+
+test('dynamics: correct-velocity accent/ghost hits earn +25 x multiplier', () => {
+    const wire = [w(1, SNARE, { ac: true }), w(4, SNARE, { ac: true }), w(7, SNARE, { mt: true }),
+        w(10, SNARE, { mt: true }), w(13, SNARE), w(16, SNARE, { ac: true })];
+    const eng = engineFor(wire);
+    assert.equal(eng.hit(1, PAD.RED, { velocity: 0.9 }).bonus, true);   // accent > 1 - 0.35
+    assert.equal(eng.hit(4, PAD.RED, { velocity: 0.5 }).bonus, false);  // too soft
+    assert.equal(eng.hit(7, PAD.RED, { velocity: 0.2 }).bonus, true);   // ghost < 0.35
+    assert.equal(eng.hit(10, PAD.RED).bonus, false);                     // no velocity -> no bonus
+    assert.equal(eng.hit(13, PAD.RED, { velocity: 1 }).bonus, false);   // neutral note
+    assert.equal(eng.hit(16, PAD.RED, { velocity: 120 }).bonus, true);  // MIDI velocity normalised
+    const s = eng.getState();
+    assert.equal(s.dynamicsBonus, 75);
+    assert.equal(s.accentsHit, 2);
+    assert.equal(s.ghostsHit, 1);
+    assert.equal(s.totalAccents, 3);
+    assert.equal(s.totalGhosts, 2);
+    assert.equal(s.score, 6 * 60 + 75);
+});
+
+test('dynamics: situational threshold compares against the previous dynamic note on the same pad', () => {
+    // ghost hit at 0.3, then another ghost 0.5 s later: threshold = max(0.35, 0.3) -> 0.34 still a ghost
+    const eng = engineFor([w(1, SNARE, { mt: true }), w(1.5, SNARE, { mt: true }), w(2, SNARE, { mt: true })]);
+    eng.hit(1, PAD.RED, { velocity: 0.3 });
+    assert.equal(eng.hit(1.5, PAD.RED, { velocity: 0.34 }).bonus, true);
+    // ghost after a ghost hit at 0.34: threshold = max(0.35, 0.34) -> 0.36 is not soft enough
+    assert.equal(eng.hit(2, PAD.RED, { velocity: 0.36 }).bonus, false);
+});
+
+test('stars: full combo without star power lands in the 5-star band', () => {
+    const eng = engineFor(snares(50));
+    playAll(eng);
+    const s = eng.getState();
+    // YARG's BaseScore uses the multiplier *before* each chord's combo increment, while live scoring
+    // updates the multiplier first (the 10th note scores 2x), so a full combo slightly exceeds BaseScore.
+    assert.ok(s.score > s.baseScore);
+    assert.ok(s.stars >= 5 && s.stars < 6, 'stars ' + s.stars);
+    assert.deepEqual(s.starThresholds, [0.06, 0.12, 0.2, 0.45, 0.75, 1.09].map(x => Math.floor(s.baseScore * x)));
+});
+
+// ── Star power ───────────────────────────────────────────────────────────
+
+const SP_WIRE = snares(40, 1, 0.5); // notes at 1.0 .. 20.5
+// phrases: notes 0-3 (1.0-2.5), 10-13 (6.0-7.5), 20-23 (11.0-12.5)
+const PHRASES = [{ start: 0.9, end: 2.9 }, { start: 5.9, end: 7.9 }, { start: 10.9, end: 12.9 }];
+
+test('star power: hitting every note of a phrase awards a quarter bar', () => {
+    const eng = engineFor(SP_WIRE, { starPower: PHRASES });
+    const log = collect(eng, ['sp-phrase', 'sp-ready']);
+    assert.equal(eng.isStarPowerNote(0), true);
+    assert.equal(eng.isStarPowerNote(4), false);
+    for (let i = 0; i < 4; i++) eng.hit(1 + i * 0.5, PAD.RED);
+    let s = eng.getState().starPower;
+    assert.equal(s.amount, 0.25);
+    assert.equal(s.phrasesHit, 1);
+    assert.equal(s.phrasesTotal, 3);
+    assert.equal(log.length, 1);
+    assert.equal(log[0][0], 'sp-phrase');
+    for (let i = 4; i < 14; i++) eng.hit(1 + i * 0.5, PAD.RED);
+    s = eng.getState().starPower;
+    assert.equal(s.amount, 0.5);
+    assert.equal(s.canActivate, true);
+    assert.deepEqual(log.map(x => x[0]), ['sp-phrase', 'sp-ready', 'sp-phrase']);
+});
+
+test('star power: one miss in a phrase fails it (no award)', () => {
+    const eng = engineFor(SP_WIRE, { starPower: PHRASES });
+    const log = collect(eng, ['sp-phrase', 'sp-phrase-fail']);
+    eng.hit(1, PAD.RED);
+    eng.hit(1.5, PAD.RED);
+    eng.update(2.2); // note at 2.0 missed
+    eng.hit(2.5, PAD.RED);
+    assert.equal(eng.getState().starPower.amount, 0);
+    assert.equal(eng.getState().starPower.phrasesHit, 0);
+    assert.deepEqual(log.map(x => x[0]), ['sp-phrase-fail']);
+    assert.equal(eng.isStarPowerNote(3), false);
+});
+
+test('star power: an overhit mid-phrase fails it, but not before the phrase starts', () => {
+    const eng = engineFor([w(0.5, KICK), ...SP_WIRE], { starPower: PHRASES });
+    eng.hit(0.5, PAD.KICK);
+    eng.hit(0.8, PAD.BLUE); // overhit while next note is the phrase start -> phrase survives
+    for (let i = 0; i < 4; i++) eng.hit(1 + i * 0.5, PAD.RED);
+    assert.equal(eng.getState().starPower.phrasesHit, 1);
+    for (let i = 4; i < 11; i++) eng.hit(1 + i * 0.5, PAD.RED); // first note of phrase 2 hit (6.0)
+    eng.hit(6.25, PAD.BLUE); // overhit inside phrase 2
+    for (let i = 11; i < 14; i++) eng.hit(1 + i * 0.5, PAD.RED);
+    assert.equal(eng.getState().starPower.phrasesHit, 1);
+    assert.equal(eng.getState().overhits, 2);
+});
+
+test('star power: activation needs half a bar', () => {
+    const eng = engineFor(SP_WIRE, { starPower: PHRASES });
+    for (let i = 0; i < 4; i++) eng.hit(1 + i * 0.5, PAD.RED);
+    assert.equal(eng.activateStarPower(3), false);
+    for (let i = 4; i < 14; i++) eng.hit(1 + i * 0.5, PAD.RED);
+    assert.equal(eng.activateStarPower(7.6), true);
+    assert.equal(eng.activateStarPower(7.7), false); // already active
+    assert.equal(eng.getState().starPower.active, true);
+});
+
+test('star power: doubles the multiplier (8x max) and drains to the end (120 BPM default)', () => {
+    const eng = engineFor(snares(80, 1, 0.25), { starPower: [{ start: 0, end: 2 }, { start: 2, end: 3 }] });
+    const log = collect(eng, ['sp-activate', 'sp-end', 'multiplier']);
+    for (let i = 0; i < 32; i++) eng.hit(1 + i * 0.25, PAD.RED); // to t=8.75, combo 32 -> 4x
+    assert.equal(eng.getState().starPower.amount, 0.5);
+    assert.equal(eng.getState().multiplier, 4);
+    assert.equal(eng.activateStarPower(8.8), true);
+    assert.equal(eng.getState().multiplier, 8);
+    const before = eng.getState().score;
+    eng.hit(9, PAD.RED);
+    assert.equal(eng.getState().score - before, 60 * 8);
+    // half bar = 4 measures = 8 s at 120 BPM 4/4
+    assert.ok(Math.abs(eng.getState().starPower.endTime - 16.8) < 1e-9);
+    for (let i = 33; i < 48; i++) eng.hit(1 + i * 0.25, PAD.RED); // up to t=12.75
+    eng.update(12.8);
+    assert.ok(Math.abs(eng.getState().starPower.amount - 0.25) < 1e-9); // 2 of 4 measures drained
+    for (let i = 48; i < 80; i++) eng.hit(1 + i * 0.25, PAD.RED);
+    const s = eng.getState();
+    assert.equal(s.starPower.active, false);
+    assert.equal(s.starPower.amount, 0);
+    assert.equal(s.multiplier, 4);
+    assert.ok(Math.abs(s.starPower.timeInStarPower - 8) < 1e-9);
+    const ends = log.filter(x => x[0] === 'sp-end');
+    assert.equal(ends.length, 1);
+    assert.ok(Math.abs(ends[0][1].time - 16.8) < 1e-9);
+    assert.deepEqual(log.filter(x => x[0] === 'multiplier').map(x => x[1].multiplier), [2, 3, 4, 8, 4]);
+});
+
+test('star power: drain follows the tempo map (tempo / beats / measures)', () => {
+    const wire = snares(8, 1, 0.25);
+    const opts = { starPower: [{ start: 0, end: 1.6 }, { start: 1.6, end: 3 }] };
+    const run = (extra) => {
+        const eng = engineFor(wire, Object.assign({}, opts, extra));
+        for (let i = 0; i < 8; i++) eng.hit(1 + i * 0.25, PAD.RED);
+        eng.activateStarPower(3);
+        return eng.getState().starPower.endTime - 3;
+    };
+    assert.ok(Math.abs(run({ tempo: [{ t: 0, bpm: 60 }] }) - 16) < 1e-9);       // 4 measures x 4 s
+    assert.ok(Math.abs(run({ tempo: [{ t: 0, bpm: 240 }] }) - 4) < 1e-9);
+    assert.ok(Math.abs(run({ tempo: [{ t: 0, bpm: 120 }], beatsPerMeasure: 3 }) - 6) < 1e-9);
+    const beats = [];
+    for (let i = 0; i < 200; i++) beats.push({ time: i * 0.25, measure: i % 4 === 0 ? i / 4 + 1 : -1 });
+    assert.ok(Math.abs(run({ beats }) - 4) < 1e-9);                               // 1 s measures
+    assert.ok(Math.abs(run({ beats: beats.map(b => b.time) }) - 4) < 1e-9);       // plain beat times, 4/4
+    assert.ok(Math.abs(run({ measures: [0, 3, 6, 9, 12, 15, 18, 21] }) - 12) < 1e-9);
+    assert.ok(Math.abs(run({}) - 8) < 1e-9);                                      // 120 BPM fallback
+});
+
+test('star power: phrase hit while active extends the end time', () => {
+    const eng = engineFor(snares(60, 1, 0.25), { starPower: [{ start: 0, end: 2 }, { start: 2, end: 3 }, { start: 4, end: 5 }] });
+    for (let i = 0; i < 8; i++) eng.hit(1 + i * 0.25, PAD.RED);
+    eng.activateStarPower(3);
+    const end0 = eng.getState().starPower.endTime;
+    for (let i = 8; i < 16; i++) eng.hit(1 + i * 0.25, PAD.RED); // phrase 3 (4.0-4.75) completes
+    const end1 = eng.getState().starPower.endTime;
+    assert.ok(Math.abs(end1 - end0 - 4) < 1e-9); // +2 measures = 4 s
+});
+
+test('drum fill activation: hitting the fill-ending activator activates SP', () => {
+    // chord at 9.0 = kick + crash; rightmost lane (green cymbal) is the activator
+    const wire = [...snares(8, 1, 0.25), w(9, KICK), w(9, CRASH), w(10, SNARE)];
+    const opts = { starPower: [{ start: 0, end: 2 }, { start: 2, end: 3 }], activation: [{ start: 8, end: 9 }] };
+    const eng = engineFor(wire, opts);
+    assert.equal(eng.isActivatorNote(9), true);  // crash
+    assert.equal(eng.isActivatorNote(8), false); // kick
+    for (let i = 0; i < 8; i++) eng.hit(1 + i * 0.25, PAD.RED);
+    assert.equal(eng.activateStarPower(5), false); // manual activation is off when fills are given
+    eng.hit(9, PAD.KICK);
+    assert.equal(eng.getState().starPower.active, false);
+    eng.hit(9, PAD.GREEN, { cymbal: true });
+    assert.equal(eng.getState().starPower.active, true);
+});
+
+test('drum fill activation: activator skipped while SP is ready is auto-hit (no penalty)', () => {
+    const wire = [...snares(8, 1, 0.25), w(9, CRASH), w(10, SNARE)];
+    const opts = { starPower: [{ start: 0, end: 2 }, { start: 2, end: 3 }], activation: [{ start: 8, end: 9 }] };
+    const eng = engineFor(wire, opts);
+    const log = collect(eng, ['hit', 'miss']);
+    for (let i = 0; i < 8; i++) eng.hit(1 + i * 0.25, PAD.RED);
+    eng.update(9.5);
+    const s = eng.getState();
+    assert.equal(eng.noteState(8), 'hit');
+    assert.equal(eng.noteInfo(8).autoHit, true);
+    assert.equal(s.combo, 9);
+    assert.equal(s.starPower.active, false);
+    assert.equal(log.filter(x => x[0] === 'miss').length, 0);
+    assert.equal(log.filter(x => x[0] === 'hit').length, 8); // auto-hit fires no 'hit' event
+});
+
+test('drum fill activation: without enough SP the activator is an ordinary note', () => {
+    const wire = [...snares(4, 1, 0.25), w(9, CRASH), w(10, SNARE)];
+    const eng = engineFor(wire, { starPower: [{ start: 0, end: 2 }], activation: [{ start: 8, end: 9 }] });
+    for (let i = 0; i < 4; i++) eng.hit(1 + i * 0.25, PAD.RED);
+    eng.update(9.5);
+    assert.equal(eng.noteState(4), 'miss');
+    const eng2 = engineFor(wire, { starPower: [{ start: 0, end: 2 }], activation: [{ start: 8, end: 9 }] });
+    for (let i = 0; i < 4; i++) eng2.hit(1 + i * 0.25, PAD.RED);
+    eng2.hit(9, PAD.GREEN, { cymbal: true });
+    assert.equal(eng2.getState().starPower.active, false);
+    assert.equal(eng2.getState().starPower.amount, 0.25);
+});
+
+test('activationType "all" requires every note of the activation chord', () => {
+    const wire = [...snares(8, 1, 0.25), w(9, KICK), w(9, CRASH)];
+    const eng = engineFor(wire, { params: { activationType: 'all' },
+        starPower: [{ start: 0, end: 2 }, { start: 2, end: 3 }], activation: [{ start: 8, end: 9 }] });
+    for (let i = 0; i < 8; i++) eng.hit(1 + i * 0.25, PAD.RED);
+    eng.hit(9, PAD.GREEN, { cymbal: true });
+    assert.equal(eng.getState().starPower.active, false);
+    eng.hit(9.01, PAD.KICK);
+    assert.equal(eng.getState().starPower.active, true);
+});
+
+test('sp-activate fires and noStarPowerOverlap blocks gaining while active', () => {
+    const eng = engineFor(snares(60, 1, 0.25), { params: { noStarPowerOverlap: true },
+        starPower: [{ start: 0, end: 2 }, { start: 2, end: 3 }, { start: 4, end: 5 }] });
+    const log = collect(eng, ['sp-activate', 'sp-phrase-fail']);
+    for (let i = 0; i < 8; i++) eng.hit(1 + i * 0.25, PAD.RED);
+    eng.activateStarPower(3);
+    const end0 = eng.getState().starPower.endTime;
+    for (let i = 8; i < 16; i++) eng.hit(1 + i * 0.25, PAD.RED);
+    assert.equal(eng.getState().starPower.endTime, end0);
+    assert.deepEqual(log.map(x => x[0]), ['sp-activate', 'sp-phrase-fail']);
+});
+
+// ── Misc API ─────────────────────────────────────────────────────────────
+
+test('reset() clears runtime state but keeps chart totals (YARG Reset_ClearsRuntimeDrumStatsButPreservesChartTotals)', () => {
+    const wire = [...snares(10), w(7, SNARE, { ac: true }), w(8, SNARE, { mt: true })];
+    const eng = engineFor(wire, { starPower: [{ start: 0, end: 2 }] });
+    playAll(eng);
+    eng.hit(20, PAD.KICK);
+    eng.update(30);
+    const before = eng.getState();
+    assert.ok(before.score > 0);
+    eng.reset();
+    const s = eng.getState();
+    assert.equal(s.score, 0);
+    assert.equal(s.combo, 0);
+    assert.equal(s.notesHit, 0);
+    assert.equal(s.notesMissed, 0);
+    assert.equal(s.overhits, 0);
+    assert.equal(s.dynamicsBonus, 0);
+    assert.equal(s.multiplier, 1);
+    assert.equal(s.starPower.amount, 0);
+    assert.equal(s.starPower.phrasesHit, 0);
+    assert.equal(s.totalNotes, before.totalNotes);
+    assert.equal(s.totalAccents, 1);
+    assert.equal(s.totalGhosts, 1);
+    assert.equal(s.starPower.phrasesTotal, 1);
+    assert.equal(eng.noteState(0), null);
+    assert.equal(eng.isStarPowerNote(0), true);
+    // replay works after reset (clock went back)
+    assert.equal(eng.hit(1, PAD.RED).type, 'hit');
+});
+
+test('bot-style run hits all notes, no overhits, full combo, 100% (YARG BotRun_HitsAllNotes...)', () => {
+    const wire = [];
+    const kit = [KICK, SNARE, HAT, HI_TOM, LOW_TOM, RIDE, FLOOR_TOM, CRASH];
+    for (let i = 0; i < 64; i++) {
+        wire.push(w(1 + i * 0.2, kit[i % kit.length]));
+        if (i % 4 === 0) wire.push(w(1 + i * 0.2, KICK));
+    }
+    const eng = engineFor(wire);
+    playAll(eng);
+    eng.update(100);
+    const s = eng.getState();
+    assert.equal(s.notesHit, s.totalNotes);
+    assert.equal(s.overhits, 0);
+    assert.equal(s.fullCombo, true);
+    assert.equal(s.percent, 1);
+    assert.equal(s.accuracy, 1);
+});
+
+test('matching input raises a hit event with velocity; mismatched raises overhit (YARG MatchingInput/MismatchedInput)', () => {
+    const eng = engineFor([w(1, KICK), w(3, SNARE), w(5, SNARE)]);
+    eng.hit(1, PAD.KICK);
+    const log = collect(eng, ['hit', 'overhit']);
+    eng.update(2.9);
+    eng.hit(3, PAD.RED, { velocity: 0.9 });
+    assert.equal(log.length, 1);
+    assert.equal(log[0][0], 'hit');
+    assert.equal(log[0][1].velocity, 0.9);
+    assert.equal(log[0][1].bonus, false);
+    assert.equal(log[0][1].id, 1);
+    eng.hit(5, PAD.YELLOW, { cymbal: true, velocity: 0.8 });
+    assert.equal(log[1][0], 'overhit');
+    assert.equal(log[1][1].lane, D.LANE.YELLOW_CYMBAL);
+    assert.equal(eng.noteState(2), null);
+    assert.equal(eng.getState().overhits, 1);
+    assert.equal(eng.stats.overhitsByLane[D.LANE.YELLOW_CYMBAL], 1);
+});
+
+test('precision preset uses YARG dynamic hit window (narrower for dense notes)', () => {
+    const dense = engineFor(snares(10, 1, 0.05), { params: D.PRESETS.precision });
+    const sparse = engineFor(snares(10, 1, 1), { params: D.PRESETS.precision });
+    const dw = dense.hitWindow(), sw = sparse.hitWindow();
+    assert.ok(dw.back - dw.front < sw.back - sw.front);
+    assert.ok(sw.back - sw.front <= 0.13 + 1e-12);
+    assert.ok(dw.back - dw.front >= 0.05 - 1e-12);
+    // songSpeed scales the window like HitWindowSettings.Scale
+    const slow = engineFor(snares(2), { params: { songSpeed: 0.5 } });
+    assert.ok(Math.abs(slow.hitWindow().back - 0.035) < 1e-12);
+});
+
+test('on() returns an unsubscribe function; off() removes listeners', () => {
+    const eng = engineFor(snares(3, 1, 1));
+    let n = 0;
+    const unsub = eng.on('hit', () => n++);
+    eng.hit(1, PAD.RED);
+    unsub();
+    eng.hit(2, PAD.RED);
+    const cb = () => n++;
+    eng.on('hit', cb);
+    eng.off('hit', cb);
+    eng.hit(3, PAD.RED);
+    assert.equal(n, 1);
+    // a throwing listener does not break the engine
+    const e2 = engineFor(snares(2, 1, 1));
+    const origErr = console.error;
+    console.error = () => {};
+    try {
+        e2.on('hit', () => { throw new Error('boom'); });
+        assert.equal(e2.hit(1, PAD.RED).type, 'hit');
+    } finally { console.error = origErr; }
+    assert.equal(e2.getState().combo, 1);
+});
+
+test('create() accepts raw wire notes; bad input is ignored; stale times clamp forward', () => {
+    const eng = D.create([w(1, SNARE), w(2, KICK)]);
+    assert.equal(eng.getState().totalNotes, 2);
+    assert.equal(eng.hit(1, 7).type, 'ignored');
+    assert.equal(eng.hit(NaN, PAD.RED).type, 'ignored');
+    eng.update(1.5);
+    assert.equal(eng.noteState(0), 'miss');
+    // hit stamped in the past is processed at the current clock (YARG QueueInput behaviour)
+    // clamped to 1.5: the kick at 2.0 is not in its window yet, so this is an overhit
+    assert.equal(eng.hit(1.0, PAD.KICK).type, 'overhit');
+    assert.equal(eng.getState().time, 1.5);
+    assert.equal(eng.hit(2, PAD.KICK).type, 'hit');
+});
+
+test('empty chart is safe', () => {
+    const eng = D.create({ notes: [], chords: [] });
+    eng.update(10);
+    assert.equal(eng.hit(1, PAD.RED).type, 'ignored');
+    const s = eng.getState();
+    assert.equal(s.totalNotes, 0);
+    assert.equal(s.accuracy, 1);
+    assert.equal(s.percent, 1);
+});
+
+test('browser build: assigns window.DrumsEngine with no module system', () => {
+    const src = fs.readFileSync(ENGINE_PATH, 'utf8');
+    const win = {};
+    vm.runInNewContext(src, { window: win, self: win, console });
+    assert.equal(typeof win.DrumsEngine.create, 'function');
+    assert.deepEqual({ ...win.DrumsEngine.PAD }, { KICK: 0, RED: 1, YELLOW: 2, BLUE: 3, GREEN: 4 });
+});
+
+// ── DrumsStatsTests-style: stats bookkeeping ─────────────────────────────
+
+test('stats: overhitsByLane counts per lane and resets', () => {
+    const eng = engineFor([w(1, KICK), w(3, SNARE), w(6, SNARE)]);
+    eng.hit(1, PAD.KICK);
+    eng.hit(2, PAD.BLUE);
+    eng.hit(2.1, PAD.BLUE);
+    eng.hit(2.2, PAD.GREEN, { cymbal: true });
+    assert.equal(eng.stats.overhitsByLane[D.LANE.BLUE_DRUM], 2);
+    assert.equal(eng.stats.overhitsByLane[D.LANE.GREEN_CYMBAL], 1);
+    assert.equal(eng.getState().overhits, 3);
+    eng.reset();
+    assert.deepEqual(eng.stats.overhitsByLane, {});
+});
diff --git a/tests/screen.test.js b/tests/screen.test.js
index 54a025b..7660cc8 100644
--- a/tests/screen.test.js
+++ b/tests/screen.test.js
@@ -138,3 +138,325 @@ test('PIECE_DEFAULT_MIDI covers the canonical piece set used by _drumTabHitsToNo
     assert.equal(mod.PIECE_DEFAULT_MIDI.kick, 36);
     assert.equal(mod.PIECE_DEFAULT_MIDI.snare, 38);
 });
+
+// ── scoring: drum_tab gameplay flags (feedpak 1.20.0) ──────────────────────
+
+test('_drumTabHitsToNotes: authored accents (a) win over velocity; a hit without v is no accent', () => {
+    const mod = freshPlugin();
+    // pre-1.20.0 tab: written velocity >= 100 is the accent, missing v is not
+    let notes = mod._drumTabHitsToNotes([{ p: 'snare', t: 1, v: 110 }, { p: 'snare', t: 2 }, { p: 'snare', t: 3, v: 120, g: true }]);
+    assert.deepEqual(notes.map(n => [n.ac, n.mt]), [[true, false], [false, false], [false, true]], 'never accent + ghost');
+    // a tab that marks accents: only `a` counts, whatever the velocity
+    notes = mod._drumTabHitsToNotes([{ p: 'snare', t: 1, v: 127 }, { p: 'snare', t: 2, a: true }]);
+    assert.deepEqual(notes.map(n => n.ac), [false, true]);
+});
+
+test('_drumTabHitsToNotes: a double kick (x2) becomes GM 35, the engine\'s Expert+ kick', () => {
+    const mod = freshPlugin();
+    const notes = mod._drumTabHitsToNotes([{ p: 'kick', t: 1 }, { p: 'kick', t: 1.1, x2: true }, { p: 'snare', t: 1.2, x2: true }]);
+    assert.deepEqual(notes.map(n => n.s * 24 + n.f), [36, mod.KICK2X_MIDI, 38], 'x2 only means something on a kick');
+    assert.equal(mod.KICK2X_MIDI, 35);
+});
+
+test('drum_tab gameplay metadata plays through session.js: levels, Expert / Expert+, star power', () => {
+    const mod = freshPlugin();
+    const H = require(path.join(__dirname, '..', 'assets', 'session.js'));
+    const tab = {
+        hits: [{ t: 1, p: 'kick' }, { t: 1, p: 'crash_l', a: true }, { t: 1.25, p: 'kick', x2: true }, { t: 1.5, p: 'snare' }],
+        star_power: [{ start_time: 1, end_time: 2 }],
+        fills: [{ start_time: 6, end_time: 8 }],
+        levels: { easy: { hits: [{ t: 1, p: 'crash_l' }], generated: true } },
+    };
+    const notes = mod._drumTabHitsToNotes(tab.hits);
+    const meta = H.parseDrumTabMeta(tab, mod._drumTabHitsToNotes);
+    assert.deepEqual(meta.starPower, [{ start: 1, end: 2 }]);
+    const opts = H.difficultyOptions({ meta, has2x: H.hasKick2x(notes, []) });
+    assert.deepEqual(opts.filter(o => o.available).map(o => o.id), ['easy', 'expert', 'expert_plus']);
+    assert.equal(H.difficultyChart('expert', notes, [], meta).notes.length, 3, 'Expert drops the double kick');
+    assert.equal(H.difficultyChart('expert_plus', notes, [], meta).notes.length, 4);
+    assert.deepEqual(H.difficultyChart('easy', notes, [], meta).notes.map(n => n.s * 24 + n.f), [49]);
+});
+
+test('difficulty preference: drums_difficulty_v1, default Expert, junk ignored, same ids as session.js', () => {
+    const H = require(path.join(__dirname, '..', 'assets', 'session.js'));
+    let mod = freshPlugin();
+    assert.deepEqual(mod.DIFFICULTY_IDS, Array.from(H.DIFFICULTIES));
+    assert.deepEqual(mod.AUTO_LEVEL_IDS, Array.from(H.AUTO_LEVELS));
+    assert.equal(mod.STORE_KEYS.difficulty, 'drums_difficulty_v1');
+    assert.equal(mod._difficultyPref(), 'expert');
+    const store = { drums_difficulty_v1: 'hard' };
+    const load = () => {
+        global.window = {};
+        global.localStorage = { getItem: (k) => (k in store ? store[k] : null), setItem: (k, v) => { store[k] = String(v); } };
+        global.document = { addEventListener: () => {}, querySelectorAll: () => [] };
+        const file = path.join(__dirname, '..', 'screen.js');
+        delete require.cache[require.resolve(file)];
+        return require(file);
+    };
+    mod = load();
+    assert.equal(mod._difficultyPref(), 'hard');
+    store.drums_difficulty_v1 = 'insane';
+    assert.equal(load()._difficultyPref(), 'expert');
+    mod = load();
+    mod._setDifficulty('expert_plus');
+    assert.equal(store.drums_difficulty_v1, 'expert_plus');
+    mod._setDifficulty('<script>');
+    assert.equal(store.drums_difficulty_v1, 'expert', 'invalid ids are not persisted');
+});
+
+test('assists: _autoAt follows the difficulty ceiling; _saveCfg validates the new settings', () => {
+    const mod = freshPlugin();
+    const cfg = mod._cfg();
+    assert.equal(cfg.autoKick, 'off');
+    assert.equal(cfg.timing, 'normal');
+    assert.equal(cfg.proCymbals, true);
+    assert.equal(cfg.inputOffsetMs, 0);
+    mod._saveCfg('autoKick', 'medium');
+    mod._saveCfg('autoCymbals', 'all');
+    assert.deepEqual(mod._autoAt('easy'), { kick: true, cymbals: true });
+    assert.deepEqual(mod._autoAt('hard'), { kick: false, cymbals: true });
+    mod._saveCfg('autoKick', 'nonsense');
+    mod._saveCfg('timing', 'turbo');
+    mod._saveCfg('synthVolume', 7);
+    mod._saveCfg('inputOffsetMs', 9000);
+    assert.equal(cfg.autoKick, 'off');
+    assert.equal(cfg.timing, 'normal');
+    assert.equal(cfg.synthVolume, 1);
+    assert.equal(cfg.inputOffsetMs, 250);
+    assert.equal(mod._timingParams(), null);
+    mod._saveCfg('timing', 'relaxed');
+    assert.equal(mod._timingParams().hitWindow.maxWindow, 0.26);
+    assert.deepEqual(mod.TIMING_IDS, Object.keys(mod.TIMING_PRESETS));
+});
+
+test('assists: _laneIsAuto maps 2D lanes (kick; hi-hat/crash/ride)', () => {
+    const mod = freshPlugin();
+    const idx = (id) => mod.DRUM_LANES.findIndex(l => l.id === id);
+    const a = { kick: true, cymbals: false };
+    assert.equal(mod._laneIsAuto(idx('kick'), a), true);
+    assert.equal(mod._laneIsAuto(idx('hihat'), a), false);
+    assert.equal(mod._laneIsAuto(idx('ride'), { cymbals: true }), true);
+    assert.equal(mod._laneIsAuto(idx('snare'), { kick: true, cymbals: true }), false);
+});
+
+test('auto notes: _autoNotesBetween returns the auto kick / cymbal notes in (from, to] with velocities', () => {
+    const mod = freshPlugin();
+    const n = (t, midi, extra) => Object.assign({ t, s: Math.floor(midi / 24), f: midi % 24 }, extra || {});
+    const notes = [n(1, 36), n(1, 42), n(1.5, 38), n(2, 36, { ac: true }), n(2, 49), n(3, 35, { mt: true }), n(3, 44)];
+    const chords = [{ t: 2.5, notes: [{ s: 1, f: 12 }, { s: 1, f: 14 }] }];   // kick + snare
+    const k = mod._autoNotesBetween(notes, chords, 1, 3, { kick: true });
+    assert.deepEqual(k, [{ t: 2, midi: 36, vel: 118 }, { t: 3, midi: 35, vel: 55 }, { t: 2.5, midi: 36, vel: 100 }]);
+    const c = mod._autoNotesBetween(notes, [], 0, 3, { cymbals: true });
+    assert.deepEqual(c.map(x => x.midi), [42, 49], 'hat pedal 44 is not an auto note');
+    assert.deepEqual(mod._autoNotesBetween(notes, chords, 0, 3, { kick: false, cymbals: false }), []);
+    assert.deepEqual(mod._autoNotesBetween(notes, chords, 3, 3, { kick: true }), [], 'empty window');
+    assert.equal(mod._cfg().autoVolume, 0.8);
+});
+
+// ── review fixes: velocity, script retry, input offset, star power pad ────
+
+test('_engineVelocity: MIDI 1..127 -> 0..1, so velocity 1 is the softest hit (not full strength)', () => {
+    const mod = freshPlugin();
+    assert.equal(mod._engineVelocity(127), 1);
+    assert.ok(Math.abs(mod._engineVelocity(1) - 1 / 127) < 1e-12);
+    assert.ok(mod._engineVelocity(1) < 0.35, 'below the engine ghost threshold');
+    assert.equal(mod._engineVelocity(64), 64 / 127);
+    assert.equal(mod._engineVelocity(200), 1);
+    assert.equal(mod._engineVelocity(undefined), undefined, 'no velocity -> no dynamics judgement');
+});
+
+// A tiny DOM for the script loader: <script> elements in <head>, found by src.
+function fakeScriptDom() {
+    const head = [];
+    const doc = {
+        addEventListener: () => {},
+        querySelectorAll: (sel) => {
+            const m = /^script\[src="(.*)"\]$/.exec(sel);
+            return m ? head.filter(s => s.src === m[1]) : [];
+        },
+        querySelector: (sel) => doc.querySelectorAll(sel)[0] || null,
+        createElement: () => {
+            const el = { src: '', onload: null, onerror: null };
+            el.remove = () => { const i = head.indexOf(el); if (i >= 0) head.splice(i, 1); };
+            return el;
+        },
+        head: { appendChild: (el) => { head.push(el); } },
+    };
+    return { doc, head };
+}
+
+test('_loadScoring: a failed script load can be retried (the dead <script> element is removed)', async () => {
+    const { doc, head } = fakeScriptDom();
+    global.window = {};
+    global.localStorage = { getItem: () => null, setItem: () => {} };
+    global.document = doc;
+    const file = path.join(__dirname, '..', 'screen.js');
+    delete require.cache[require.resolve(file)];
+    const mod = require(file);
+
+    // First try: engine.js loads, session.js fails (network error).
+    const p1 = mod._loadScoring();
+    assert.equal(head.length, 2);
+    window.DrumsEngine = { fake: 'engine' };
+    head[0].onload();
+    head[1].onerror();
+    await assert.rejects(p1, /Failed to load/);
+    assert.equal(head.length, 1, 'the failed session.js element is gone');
+
+    // Retry: session.js is requested again (not resolved on the stale tag).
+    const p2 = mod._loadScoring();
+    assert.equal(head.length, 2);
+    assert.match(head[1].src, /session\.js/);
+    window.DrumsSession = { fake: 'session' };
+    head[1].onload();
+    const r = await p2;
+    assert.equal(r.E, window.DrumsEngine);
+    assert.equal(r.H, window.DrumsSession);
+});
+
+test('_loadScoring: a script that loads but never registers is dropped so a retry reloads it', async () => {
+    const { doc, head } = fakeScriptDom();
+    global.window = {};
+    global.localStorage = { getItem: () => null, setItem: () => {} };
+    global.document = doc;
+    const file = path.join(__dirname, '..', 'screen.js');
+    delete require.cache[require.resolve(file)];
+    const mod = require(file);
+    const p1 = mod._loadScoring();
+    head[0].onload(); head[1].onload();            // e.g. an HTML error page served as JS
+    await assert.rejects(p1, /did not register/);
+    assert.equal(head.length, 0);
+    const p2 = mod._loadScoring();
+    assert.equal(head.length, 2, 'both files requested again');
+    window.DrumsEngine = {}; window.DrumsSession = {};
+    head[0].onload(); head[1].onload();
+    await p2;
+});
+
+test('_setInputOffset saves, clamps and hands the offset to every live view', () => {
+    const mod = freshPlugin();
+    const seen = [];
+    mod._instances().add({ _inputOffsetChanged: () => seen.push(mod._cfg().inputOffsetMs) });
+    assert.equal(mod._setInputOffset(23), 23);
+    assert.equal(mod._setInputOffset('-400'), -250);
+    assert.deepEqual(seen, [23, -250]);
+    mod._instances().clear();
+});
+
+test('star power pad: drums_sp_pad_v1, off by default, any MIDI note 0..127', () => {
+    const mod = freshPlugin();
+    assert.equal(mod.STORE_KEYS.spPad, 'drums_sp_pad_v1');
+    assert.equal(mod._cfg().spPad, -1);
+    assert.equal(mod._spPadName(), '');
+    mod._saveCfg('spPad', '44');
+    assert.equal(mod._cfg().spPad, 44);
+    assert.equal(mod._spPadName(), 'hi-hat pedal');
+    mod._saveCfg('spPad', 99);
+    assert.equal(mod._spPadName(), 'MIDI note 99');
+    mod._saveCfg('spPad', 300);
+    assert.equal(mod._cfg().spPad, -1);
+    mod._saveCfg('spPad', 'x');
+    assert.equal(mod._cfg().spPad, -1);
+    assert.equal(mod.SP_PAD_CHOICES[0][0], -1);
+});
+
+// ── drum view on a part that isn't drums ────────────────────────────────────
+
+test('_isDrumsArrangement / _noDrumsMessage: refuse guitar parts, explain why', () => {
+    const mod = freshPlugin();
+    assert.equal(mod._isDrumsArrangement({ arrangement: 'Drums' }), true);
+    assert.equal(mod._isDrumsArrangement({ arrangement_index: 2, arrangements: [{ index: 2, name: 'Percussion' }] }), true);
+    assert.equal(mod._isDrumsArrangement({ arrangement: 'Lead' }), false);
+    assert.equal(mod._isDrumsArrangement({ has_drum_tab: true, arrangement: 'Lead' }), false, 'the drum tab is checked separately');
+    assert.equal(mod._isDrumsArrangement(null), false);
+    assert.equal(mod._noDrumsMessage({ arrangement: 'Lead', arrangements: [{ name: 'Lead' }, { name: 'Drums' }] }),
+        'Pick the Drums part: Lead is not drums');
+    assert.equal(mod._noDrumsMessage({ arrangement: 'Lead', arrangements: [{ name: 'Lead' }, { name: 'Bass' }] }),
+        'This song has no drums');
+    assert.equal(mod._noDrumsMessage(undefined), 'This song has no drums');
+});
+
+// ── MIDI routing (splitscreen) ──────────────────────────────────────────────
+
+test('_routeTarget: kit hits go to the focused drum view on screen, else the first one on screen', () => {
+    const mod = freshPlugin();
+    const hits = [];
+    const view = (name, visible) => ({ name, _isVisible: () => visible, _handleDrumHit: (n, v, ts) => hits.push([name, n, v, ts]) });
+    const hidden = view('hidden main player', false);
+    const panel = view('panel 2', true);
+    mod._instances().add(hidden);
+    mod._instances().add(panel);
+    assert.equal(mod._routeTarget(), panel, 'the hidden view does not swallow hits');
+    mod._midiOnMessage({ data: [0x99, 38, 90], timeStamp: 1234.5 });
+    mod._midiOnMessage({ data: [0x89, 38, 0] });    // note off: ignored
+    mod._midiOnMessage({ data: [0x99, 38, 0] });    // note on velocity 0 = off
+    assert.deepEqual(hits, [['panel 2', 38, 90, 1234.5]], 'the MIDI timestamp is passed on');
+    mod._instances().clear();
+    assert.equal(mod._routeTarget(), null);
+});
+
+// ── end-of-song results card ────────────────────────────────────────────────
+
+function fakeCardDom() {
+    const body = [];
+    const listeners = [];
+    global.performance = global.performance || { now: () => Date.now() };
+    return {
+        body,
+        listeners,
+        doc: {
+            addEventListener: (type, fn) => listeners.push([type, fn]),
+            removeEventListener: (type, fn) => { const i = listeners.findIndex(l => l[1] === fn); if (i >= 0) listeners.splice(i, 1); },
+            querySelectorAll: () => [],
+            createElement: () => {
+                const el = { style: {}, attrs: {}, innerHTML: '', className: '', handlers: {} };
+                el.setAttribute = (k, v) => { el.attrs[k] = v; };
+                el.addEventListener = (t, fn) => { el.handlers[t] = fn; };
+                el.remove = () => { const i = body.indexOf(el); if (i >= 0) body.splice(i, 1); };
+                return el;
+            },
+            body: { appendChild: (el) => body.push(el) },
+        },
+    };
+}
+
+test('_drumsEndCard: total with bonuses, best score per song + difficulty, nothing when nothing was hit', () => {
+    const dom = fakeCardDom();
+    const store = {};
+    const events = {};
+    global.window = { feedBack: {
+        currentSong: { filename: 'song.sloppak', title: 'Song <1>', artist: 'Band' },
+        on: (n, fn) => { events[n] = fn; }, off: (n) => { delete events[n]; },
+    } };
+    global.localStorage = { getItem: (k) => (k in store ? store[k] : null), setItem: (k, v) => { store[k] = String(v); } };
+    global.document = dom.doc;
+    const file = path.join(__dirname, '..', 'screen.js');
+    delete require.cache[require.resolve(file)];
+    const mod = require(file);
+    const session = (st, bonus) => ({ getState: () => st, getBonus: () => bonus });
+    const st = { notesHit: 90, notesMissed: 10, totalNotes: 100, score: 5000, starPowerScore: 600, stars: 4.2,
+        maxCombo: 40, fullCombo: false, overhits: 2 };
+    const bonus = { total: 250, timing: 150, perfect: 15, rolls: 100, runs: [{ h: 9, n: 10 }], solo: 0, solos: [] };
+    const r = mod._drumsEndCard(session(st, bonus), { text: 'HARD' });
+    assert.equal(r.total, 5250);
+    assert.equal(r.best, true);
+    assert.equal(store['drums.best:song.sloppak|HARD'], '5250');
+    assert.equal(dom.body.length, 1);
+    assert.match(dom.body[0].innerHTML, /Song &lt;1&gt;/, 'song title escaped');
+    assert.match(dom.body[0].innerHTML, /90\.00%/);
+    assert.ok(events['song:loading'], 'closes when the next song loads');
+    r.close();
+    assert.equal(dom.body.length, 0);
+    assert.equal(dom.listeners.length, 0, 'key listener removed');
+    // a second card right away (another view on the same song end) is skipped
+    assert.equal(mod._drumsEndCard(session(st, bonus), { text: 'HARD' }), null);
+    // nothing hit: no card
+    const mod2 = (() => { delete require.cache[require.resolve(file)]; return require(file); })();
+    assert.equal(mod2._drumsEndCard(session(Object.assign({}, st, { notesHit: 0 }), bonus), null), null);
+    // a lower score keeps the best
+    const r3 = mod2._drumsEndCard(session(Object.assign({}, st, { score: 100 }), { total: 0 }), { text: 'HARD' });
+    assert.equal(r3.best, false);
+    assert.equal(r3.previous, 5250);
+    assert.equal(store['drums.best:song.sloppak|HARD'], '5250');
+    r3.close();
+});
diff --git a/tests/session.test.js b/tests/session.test.js
new file mode 100644
index 0000000..1b49b32
--- /dev/null
+++ b/tests/session.test.js
@@ -0,0 +1,837 @@
+'use strict';
+// Unit tests for session.js: chart -> render model, gem classification, drum_tab gameplay metadata
+// (feedpak 1.20.0), difficulty levels, auto lanes, MIDI mapping, timing and HUD helpers, and the engine
+// session. No DOM needed.
+// Run: node tests/session.test.js
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const H = require(path.join(__dirname, '..', 'assets', 'session.js'));
+const E = require(path.join(__dirname, '..', 'assets', 'engine.js'));
+
+const w = (t, midi, extra) => Object.assign({ t, s: Math.floor(midi / 24), f: midi % 24 }, extra || {});
+
+// Minimal drum_tab hits -> wire notes converter (screen.js _drumTabHitsToNotes does the full job).
+const GM = { kick: 36, snare: 38, hh_closed: 42, crash_l: 49, ride: 51, tom_hi: 48 };
+const toNotes = (hits) => hits.filter(h => GM[h.p]).map(h => w(h.t, h.p === 'kick' && h.x2 ? 35 : GM[h.p],
+    h.a ? { ac: true } : (h.g ? { mt: true } : {})));
+const tabMeta = (tab) => H.parseDrumTabMeta(tab, toNotes);
+
+// ── chart -> render model ──────────────────────────────────────────────────
+
+test('collectWireNotes flattens chords with the chord time and drops visual-only notes', () => {
+    const notes = [w(1, 38), w(0.5, 36), Object.assign(w(0.97, 38), { _noScore: true }), null];
+    const chords = [{ t: 2, notes: [{ s: 1, f: 12 }, { s: 1, f: 18 }] }, { t: 3 }, null];
+    const out = H.collectWireNotes(notes, chords);
+    assert.equal(out.length, 4);
+    assert.deepEqual(out.slice(2).map(n => [n.t, n.s * 24 + n.f]), [[2, 36], [2, 42]]);
+    assert.deepEqual(H.collectWireNotes(null, undefined), []);
+    // the chord's own note objects are not mutated
+    assert.equal(chords[0].notes[0].t, undefined);
+});
+
+test('classifyNote: pads, cymbals, kick and 2x kick, with dynamics and lane colours', () => {
+    assert.deepEqual(H.classifyNote({ pad: 0 }), { kind: 'kick', lane: -1, cymbal: false, kick2x: false, accent: false, ghost: false, color: H.COLORS.kick });
+    assert.equal(H.classifyNote({ pad: 0, kick2x: true }).kind, 'kick2x');
+    assert.equal(H.classifyNote({ pad: 0, kick2x: true }).color, H.COLORS.kick2x);
+    const red = H.classifyNote({ pad: 1, dyn: 'accent' });
+    assert.deepEqual([red.kind, red.lane, red.accent, red.color], ['pad', 0, true, H.LANE_COLORS.red]);
+    assert.equal(H.classifyNote({ pad: 1, cymbal: true }).kind, 'pad', 'there is no red cymbal');
+    const hat = H.classifyNote({ pad: 2, cymbal: true, dyn: 'ghost' });
+    assert.deepEqual([hat.kind, hat.lane, hat.ghost, hat.color], ['cymbal', 1, true, H.LANE_COLORS.yellow]);
+    assert.equal(H.classifyNote({ pad: 3 }).color, H.LANE_COLORS.blue);
+    assert.equal(H.classifyNote({ pad: 4, cymbal: true }).lane, 3);
+    assert.equal(H.classifyNote({ pad: 7 }), null);
+    assert.equal(H.classifyNote(null), null);
+});
+
+test('buildGems maps General MIDI wire notes to gems keyed by engine note id', () => {
+    const wire = [w(1, 42), w(1, 36), w(1.5, 48), w(2, 51), w(2, 45), w(2.5, 49, { ac: true }), w(2.5, 41),
+        w(3, 35), w(3.25, 38, { mt: true })];
+    const decoded = E.decodeNotes(wire);
+    const gems = H.buildGems(decoded);
+    const desc = gems.map(g => `${g.t}:${g.kind}:${g.lane}`);
+    assert.deepEqual(desc, ['1:cymbal:1', '1:kick:-1', '1.5:pad:1', '2:cymbal:2', '2:pad:2', '2.5:cymbal:3', '2.5:pad:3',
+        '3:kick2x:-1', '3.25:pad:0']);
+    assert.ok(gems.find(g => g.t === 2.5 && g.cymbal).accent);
+    assert.ok(gems[gems.length - 1].ghost);
+    for (const g of gems) assert.equal(decoded.notes[g.id].t, g.t, 'gem id is the decoded/engine note id');
+    // the engine knows every gem id
+    const eng = E.create(decoded);
+    for (const g of gems) assert.equal(eng.noteState(g.id), null);
+});
+
+test('visibleRange returns the half-open index range of gems in [t0, t1)', () => {
+    const gems = [0, 1, 1, 2, 3, 5].map(t => ({ t }));
+    assert.deepEqual(H.visibleRange(gems, 1, 3), [1, 4]);
+    assert.deepEqual(H.visibleRange(gems, -5, 0), [0, 0]);
+    assert.deepEqual(H.visibleRange(gems, 4, 10), [5, 6]);
+    assert.deepEqual(H.visibleRange([], 0, 1), [0, 0]);
+});
+
+test('normalizeBeats keeps finite times, marks downbeats (measure >= 0) and sorts', () => {
+    const out = H.normalizeBeats([{ time: 1, measure: -1 }, { time: 0.5, measure: 1 }, { t: 1.5 }, 2, { time: 'x' }, null]);
+    assert.deepEqual(out, [{ t: 0.5, measure: true }, { t: 1, measure: false }, { t: 1.5, measure: false }, { t: 2, measure: false }]);
+    assert.deepEqual(H.normalizeBeats(undefined), []);
+});
+
+// ── drums metadata (star power / fills) ───────────────────────────────────
+
+test('parseDrumTabMeta reads drum_tab star power / fills / solos into engine option shape', () => {
+    const tab = { version: 1, hits: [],
+        star_power: [{ start_time: 10, end_time: 14 }, { start_time: 2, end_time: 4.5 }],
+        fills: [{ start_time: 20, end_time: 22 }], solos: [{ start_time: 30, end_time: 40 }] };
+    assert.deepEqual(tabMeta(tab), { pro: true,
+        starPower: [{ start: 2, end: 4.5 }, { start: 10, end: 14 }], activation: [{ start: 20, end: 22 }],
+        solos: [{ start: 30, end: 40 }], levels: null, levelsGenerated: [] });
+});
+
+test('parseDrumTabMeta drops malformed ranges; a tab without metadata gives null', () => {
+    const m = tabMeta({ hits: [], star_power: [{ start_time: 5, end_time: 1 }, { start_time: 'a', end_time: 2 },
+        [1, 2], { end_time: 3 }, { start_time: 3, end_time: 4 }, 7], fills: 'nope' });
+    assert.deepEqual(m.starPower, [{ start: 3, end: 4 }]);
+    assert.deepEqual(m.activation, []);
+    assert.equal(tabMeta({ version: 1, hits: [{ t: 1, p: 'kick' }] }), null, 'pre-1.20.0 tab');
+    assert.equal(tabMeta({ hits: [], star_power: [] }), null);
+    assert.equal(tabMeta(null), null);
+    assert.equal(tabMeta([1, 2]), null);
+});
+
+// ── difficulty levels ─────────────────────────────────────────────────────
+
+const LEVELS_TAB = {
+    version: 1, hits: [], star_power: [{ start_time: 1, end_time: 2 }],
+    levels: {
+        easy: { hits: [{ t: 2, p: 'kick' }, { t: 1, p: 'snare' }, { t: 1, p: 'kick' }], generated: true },
+        medium: { hits: [{ t: 1, p: 'kick' }, { t: 1, p: 'hh_closed' }, { t: 1.5, p: 'snare', a: true }, { t: 2, p: 'hh_closed', g: true }], generated: true },
+        hard: { hits: [{ t: 1, p: 'kick' }, { t: 2, p: 'snare' }] },
+        expert: { hits: [{ t: 0, p: 'kick' }] },          // not a lower level: ignored
+    },
+};
+
+test('parseDrumTabMeta reads the levels as wire notes, with the generated marker per level', () => {
+    const m = tabMeta(LEVELS_TAB);
+    assert.deepEqual(Object.keys(m.levels).sort(), ['easy', 'hard', 'medium']);
+    assert.deepEqual(m.levels.hard.map(n => [n.t, n.s * 24 + n.f]), [[1, 36], [2, 38]]);
+    assert.equal(m.levels.medium[2].ac, true);
+    assert.equal(m.levels.medium[3].mt, true);
+    assert.deepEqual(m.levelsGenerated, ['easy', 'medium']);
+    // a tab with only levels is accepted; odd / empty levels are dropped
+    assert.ok(tabMeta({ levels: { easy: { hits: [{ t: 1, p: 'kick' }] } } }).levels.easy);
+    assert.equal(tabMeta({ levels: [1, 2] }), null);
+    assert.equal(tabMeta({ levels: { easy: 'x', medium: { hits: [] }, hard: { hits: [{ t: 1, p: 'cowbell' }] } } }), null);
+    assert.equal(H.parseDrumTabMeta(LEVELS_TAB).levels, null, 'no converter: no levels');
+    // the engine decodes a level like the main chart: one chord at t=1 (kick + hat), accent kept
+    const dec = E.decodeNotes(m.levels.medium);
+    assert.equal(dec.chords[0].notes.length, 2);
+    assert.equal(dec.notes.find(n => n.pad === 1).dyn, 'accent');
+});
+
+test('hasKick2x / stripKick2x: 2x kick (GM 35) in notes and chords; same arrays when there is none', () => {
+    const notes = [w(1, 36), w(1.5, 35), w(2, 38)];
+    const chords = [{ t: 3, notes: [{ s: 1, f: 11 }, { s: 1, f: 14 }] }, { t: 4, notes: [{ s: 1, f: 11 }] }, { t: 5, notes: [{ s: 1, f: 12 }] }];
+    assert.equal(H.hasKick2x(notes, null), true);
+    assert.equal(H.hasKick2x([w(1, 36)], chords), true);
+    assert.equal(H.hasKick2x([{ t: 1, midi: 35 }], null), true);
+    assert.equal(H.hasKick2x([w(1, 36)], [chords[2]]), false);
+    const s = H.stripKick2x(notes, chords);
+    assert.deepEqual(s.notes.map(n => n.s * 24 + n.f), [36, 38]);
+    assert.equal(s.chords.length, 2, 'a chord of only 2x kicks disappears');
+    assert.deepEqual(s.chords[0].notes.map(n => n.s * 24 + n.f), [38]);
+    assert.equal(s.chords[1], chords[2], 'untouched chords are kept as they are');
+    assert.equal(chords[0].notes.length, 2, 'input not mutated');
+    const plain = [w(1, 36)], plainChords = [chords[2]];
+    const same = H.stripKick2x(plain, plainChords);
+    assert.ok(same.notes === plain && same.chords === plainChords);
+});
+
+test('difficultyOptions: Expert always, Expert+ with double kicks, lower levels from the tab', () => {
+    const byId = (opts) => Object.fromEntries(opts.map(o => [o.id, o]));
+    // pre-1.20.0 tab / legacy chart: no levels
+    let o = byId(H.difficultyOptions({ meta: null, has2x: false }));
+    assert.deepEqual(H.DIFFICULTIES.filter(id => o[id].available), ['expert']);
+    assert.match(o.easy.reason, /only has Expert/);
+    assert.match(o.expert_plus.reason, /double-kick/);
+    o = byId(H.difficultyOptions({ meta: tabMeta({ star_power: [{ start_time: 1, end_time: 2 }] }), has2x: true }));
+    assert.deepEqual(H.DIFFICULTIES.filter(id => o[id].available), ['expert', 'expert_plus']);
+    // levels present: available, generated marker
+    const meta = tabMeta({ levels: { easy: LEVELS_TAB.levels.easy } });
+    o = byId(H.difficultyOptions({ meta, has2x: true }));
+    assert.deepEqual([o.easy.available, o.easy.generated, o.easy.label, o.easy.name], [true, true, 'EASY', 'Easy']);
+    assert.deepEqual([o.medium.available, o.hard.available], [false, false]);
+    assert.match(o.hard.reason, /no Hard part/);
+    assert.equal(o.expert.generated, false);
+});
+
+test('resolveDifficulty falls back to Expert for unavailable levels without changing the request', () => {
+    const opts = H.difficultyOptions({ meta: null, has2x: false });
+    assert.deepEqual(H.resolveDifficulty('expert', opts), { id: 'expert', requested: 'expert', fallback: false, reason: '' });
+    const r = H.resolveDifficulty('hard', opts);
+    assert.deepEqual([r.id, r.requested, r.fallback], ['expert', 'hard', true]);
+    assert.match(r.reason, /only has Expert/);
+    assert.equal(H.resolveDifficulty('expert_plus', opts).id, 'expert');
+    assert.equal(H.resolveDifficulty('expert_plus', H.difficultyOptions({ has2x: true })).id, 'expert_plus');
+    // junk / missing preference -> Expert, no fallback flagged
+    assert.deepEqual(H.resolveDifficulty('insane', opts), { id: 'expert', requested: 'expert', fallback: false, reason: '' });
+    assert.equal(H.resolveDifficulty(undefined, null).id, 'expert');
+    assert.equal(H.normalizeDifficulty('easy'), 'easy');
+    assert.equal(H.normalizeDifficulty({}), 'expert');
+});
+
+test('nextDifficulty steps through the available levels and wraps', () => {
+    const all = H.difficultyOptions({ meta: tabMeta(LEVELS_TAB), has2x: true });
+    assert.equal(H.nextDifficulty('easy', all, 1), 'medium');
+    assert.equal(H.nextDifficulty('expert_plus', all, 1), 'easy');
+    assert.equal(H.nextDifficulty('easy', all, -1), 'expert_plus');
+    const few = H.difficultyOptions({ meta: null, has2x: false });
+    assert.equal(H.nextDifficulty('expert', few, 1), 'expert');
+    const two = H.difficultyOptions({ meta: null, has2x: true });
+    assert.equal(H.nextDifficulty('expert', two, 1), 'expert_plus');
+    assert.equal(H.nextDifficulty('expert_plus', two, 1), 'expert');
+    assert.equal(H.nextDifficulty('expert', two, -1), 'expert_plus');
+});
+
+test('difficultyLabel / difficultyBadge: HUD text, AUTO marker for generated levels, fallback tooltip', () => {
+    assert.equal(H.difficultyLabel('hard'), 'HARD');
+    assert.equal(H.difficultyLabel('expert_plus'), 'EXPERT+');
+    assert.equal(H.difficultyLabel('easy', true), 'EASY · AUTO');
+    const meta = tabMeta(LEVELS_TAB);
+    const opts = H.difficultyOptions({ meta, has2x: true });
+    let b = H.difficultyBadge(H.resolveDifficulty('medium', opts), opts);
+    assert.deepEqual([b.id, b.text, b.sub, b.fallback, b.color], ['medium', 'MEDIUM', 'AUTO', false, H.DIFFICULTY_COLORS.medium]);
+    assert.match(b.title, /auto-generated/);
+    b = H.difficultyBadge(H.resolveDifficulty('hard', opts), opts);
+    assert.deepEqual([b.text, b.sub], ['HARD', null]);
+    const none = H.difficultyOptions({ meta: null });
+    b = H.difficultyBadge(H.resolveDifficulty('hard', none), none);
+    assert.deepEqual([b.id, b.text, b.fallback], ['expert', 'EXPERT', true]);
+    assert.match(b.title, /Hard is not available for this song/);
+    assert.equal(H.difficultyBadge(null, null).text, 'EXPERT');
+});
+
+test('difficultyChart: Expert+ as is, Expert without double kicks, lower levels from the tab', () => {
+    const notes = [w(1, 36), w(1, 42), w(1.25, 35), w(1.5, 38)];
+    const chords = [];
+    const meta = tabMeta(LEVELS_TAB);
+    const xp = H.difficultyChart('expert_plus', notes, chords, meta);
+    assert.ok(xp.notes === notes && xp.chords === chords && xp.id === 'expert_plus');
+    const ex = H.difficultyChart('expert', notes, chords, meta);
+    assert.deepEqual(ex.notes.map(n => n.s * 24 + n.f), [36, 42, 38]);
+    const plain = [w(1, 36)];
+    assert.equal(H.difficultyChart('expert', plain, null, null).notes, plain, 'no 2x kick: the same array');
+    const md = H.difficultyChart('medium', notes, chords, meta);
+    assert.equal(md.id, 'medium');
+    assert.deepEqual(md.notes.map(n => [n.t, n.s * 24 + n.f, !!n.ac, !!n.mt]),
+        [[1, 36, false, false], [1, 42, false, false], [1.5, 38, true, false], [2, 42, false, true]]);
+    assert.deepEqual(md.chords, []);
+    // a level the chart lacks plays Expert
+    const fb = H.difficultyChart('hard', notes, chords, null);
+    assert.equal(fb.id, 'expert');
+    assert.deepEqual(fb.notes.map(n => n.s * 24 + n.f), [36, 42, 38]);
+});
+
+test('isDifficultyKey: D harder, Shift+D easier; never a drum key', () => {
+    assert.deepEqual(H.isDifficultyKey({ code: 'KeyD', key: 'd' }), { dir: 1 });
+    assert.deepEqual(H.isDifficultyKey({ code: 'KeyD', key: 'D', shiftKey: true }), { dir: -1 });
+    assert.deepEqual(H.isDifficultyKey({ key: 'd' }), { dir: 1 });
+    assert.equal(H.isDifficultyKey({ code: 'KeyD', key: 'd', ctrlKey: true }), null);
+    assert.equal(H.isDifficultyKey({ code: 'KeyF', key: 'f' }), null);
+    assert.equal(H.isDifficultyKey(null), null);
+    for (const code of ['KeyB', 'KeyF', 'KeyJ', 'KeyK', 'KeyL', 'KeyU', 'KeyI', 'KeyO', 'Enter', 'Space', 'ShiftLeft']) {
+        assert.equal(H.isDifficultyKey({ code, key: code }), null, code);
+    }
+});
+
+test('session: a level chart plays like any chart; switching level mid-song scores from the current time', () => {
+    const hit = (t, p) => ({ t, p });
+    const meta = tabMeta({ levels: {
+        easy: { hits: [hit(1, 'kick'), hit(2, 'snare'), hit(3, 'kick'), hit(4, 'snare')] },
+        hard: { hits: [hit(1, 'kick'), hit(1, 'hh_closed'), hit(2, 'snare'), hit(2, 'hh_closed'),
+            hit(3, 'kick'), hit(3, 'hh_closed'), hit(4, 'snare'), hit(4, 'hh_closed')] },
+    } });
+    const s = H.createSession(E, { now: () => 0 });
+    s.load({ notes: H.difficultyChart('easy', [], [], meta).notes, chords: [], beats: [] });
+    s.setMeta(meta);
+    s.update(0);
+    for (const g of s.gems.filter(g => g.t < 2.5)) { s.update(g.t); s.hit(g.t, g.pad, { cymbal: g.cymbal }); }
+    s.update(2.5);
+    assert.equal(s.getState().notesHit, 2);
+    // switch to Hard at t=2.5 (what screen.js does: load the other chart, keep the meta)
+    s.load({ notes: H.difficultyChart('hard', [], [], meta).notes, chords: [], beats: [] });
+    s.setMeta(meta);
+    s.update(2.5);
+    const st = s.getState();
+    assert.equal(st.totalNotes, 4, 'only the Hard notes from 2.5 s on');
+    assert.equal(st.notesMissed, 0);
+    for (const g of s.gems.filter(g => g.t > 2.5)) { s.update(g.t); s.hit(g.t, g.pad, { cymbal: g.cymbal }); }
+    s.update(5);
+    assert.deepEqual([s.getState().notesHit, s.getState().notesMissed, s.getState().overhits], [4, 0, 0]);
+});
+
+// ── input mapping ─────────────────────────────────────────────────────────
+
+test('midiToPad: Learn/custom mapping wins, otherwise General MIDI', () => {
+    const gm = E.padFromMidi;
+    assert.deepEqual(H.midiToPad(38, null, gm), { pad: 1, cymbal: false });
+    assert.deepEqual(H.midiToPad(42, null, gm), { pad: 2, cymbal: true });
+    assert.deepEqual(H.midiToPad(48, null, gm), { pad: 2, cymbal: false });
+    assert.deepEqual(H.midiToPad(51, null, gm), { pad: 3, cymbal: true });
+    assert.deepEqual(H.midiToPad(49, null, gm), { pad: 4, cymbal: true });
+    assert.deepEqual(H.midiToPad(35, null, gm), { pad: 0, cymbal: false });
+    assert.equal(H.midiToPad(44, null, gm), null, 'hi-hat pedal is not a hit');
+    assert.equal(H.midiToPad(60, null, gm), null);
+    const custom = { 60: 'snare', 61: 'crash', 62: 'tom2', 63: 'hihat', 64: 'ride', 65: 'kick', 66: 'tom1', 67: 'tom3',
+        38: 'kick', 68: 'not-a-lane' };
+    assert.deepEqual(H.midiToPad(60, custom, gm), { pad: 1, cymbal: false });
+    assert.deepEqual(H.midiToPad(61, custom, gm), { pad: 4, cymbal: true });
+    assert.deepEqual(H.midiToPad(62, custom, gm), { pad: 3, cymbal: false });
+    assert.deepEqual(H.midiToPad(63, custom, gm), { pad: 2, cymbal: true });
+    assert.deepEqual(H.midiToPad(64, custom, gm), { pad: 3, cymbal: true });
+    assert.deepEqual(H.midiToPad(65, custom, gm), { pad: 0, cymbal: false });
+    assert.deepEqual(H.midiToPad(66, custom, gm), { pad: 2, cymbal: false });
+    assert.deepEqual(H.midiToPad(67, custom, gm), { pad: 4, cymbal: false });
+    assert.deepEqual(H.midiToPad(38, custom, gm), { pad: 0, cymbal: false }, 'a remapped GM note follows the custom map');
+    assert.equal(H.midiToPad(68, custom, gm), null, 'unknown lane id falls back to GM (68 is unmapped)');
+    assert.deepEqual(H.midiToPad(42, custom, gm), { pad: 2, cymbal: true }, 'notes missing from the custom map use GM');
+    assert.equal(H.midiToPad(200, null, gm), null);
+    assert.equal(H.midiToPad(-1, null, gm), null);
+    // a null-prototype map (screen.js _validateCustomMapping output) works too
+    const np = Object.assign(Object.create(null), { 70: 'snare' });
+    assert.deepEqual(H.midiToPad(70, np, gm), { pad: 1, cymbal: false });
+});
+
+test('isTypingTarget: text inputs, textareas, selects and contenteditable', () => {
+    assert.equal(H.isTypingTarget({ tagName: 'INPUT', type: 'text' }), true);
+    assert.equal(H.isTypingTarget({ tagName: 'input' }), true);
+    assert.equal(H.isTypingTarget({ tagName: 'INPUT', type: 'number' }), true);
+    assert.equal(H.isTypingTarget({ tagName: 'INPUT', type: 'checkbox' }), false);
+    assert.equal(H.isTypingTarget({ tagName: 'INPUT', type: 'range' }), false);
+    assert.equal(H.isTypingTarget({ tagName: 'TEXTAREA' }), true);
+    assert.equal(H.isTypingTarget({ tagName: 'SELECT' }), true);
+    assert.equal(H.isTypingTarget({ tagName: 'DIV', isContentEditable: true }), true);
+    assert.equal(H.isTypingTarget({ tagName: 'CANVAS' }), false);
+    assert.equal(H.isTypingTarget(null), false);
+});
+
+// ── timing ────────────────────────────────────────────────────────────────
+
+test('estimateTime extrapolates between frames only while playing', () => {
+    const playing = { time: 10, wall: 1000, prevTime: 9.984, prevWall: 984 };
+    assert.ok(Math.abs(H.estimateTime(playing, 1010) - 10.01) < 1e-9);
+    assert.ok(Math.abs(H.estimateTime(playing, 1500) - 10.06) < 1e-9, 'capped at 60 ms ahead');
+    assert.equal(H.estimateTime(playing, 990), 10, 'never before the frame time');
+    assert.equal(H.estimateTime({ time: 10, wall: 1000, prevTime: 10, prevWall: 984 }, 1010), 10, 'paused');
+    assert.equal(H.estimateTime({ time: 10, wall: 1000, prevTime: 30, prevWall: 984 }, 1010), 10, 'seek back');
+    assert.equal(H.estimateTime({ time: 10, wall: 1000, prevTime: 9, prevWall: 500 }, 1010), 10, 'stalled frames');
+    assert.equal(H.estimateTime({ time: 10, wall: 1000, prevTime: NaN, prevWall: NaN }, 1010), 10);
+    assert.ok(Number.isNaN(H.estimateTime({ time: NaN }, 0)));
+    // half-speed playback extrapolates at half speed
+    const slow = { time: 10, wall: 1000, prevTime: 9.992, prevWall: 984 };
+    assert.ok(Math.abs(H.estimateTime(slow, 1020) - 10.01) < 1e-9);
+});
+
+test('isSeek flags backward jumps and large forward jumps', () => {
+    assert.equal(H.isSeek(10, 10.016), false);
+    assert.equal(H.isSeek(10, 11), false);
+    assert.equal(H.isSeek(10, 12), true);
+    assert.equal(H.isSeek(10, 9.9), false);
+    assert.equal(H.isSeek(10, 9.5), true);
+    assert.equal(H.isSeek(NaN, 3), false);
+    assert.equal(H.isSeek(null, 3), false);
+});
+
+// ── HUD ───────────────────────────────────────────────────────────────────
+
+test('formatScore / formatAccuracy', () => {
+    assert.equal(H.formatScore(0), '0');
+    assert.equal(H.formatScore(999), '999');
+    assert.equal(H.formatScore(1000), '1,000');
+    assert.equal(H.formatScore(1234567.9), '1,234,567');
+    assert.equal(H.formatScore(-5), '0');
+    assert.equal(H.formatScore(undefined), '0');
+    assert.equal(H.formatAccuracy(1), '100.0%');
+    assert.equal(H.formatAccuracy(0.9567), '95.7%');
+    assert.equal(H.formatAccuracy(2), '100.0%');
+    assert.equal(H.formatAccuracy(NaN), '--');
+});
+
+test('multiplierColor: x1..x4 and star power', () => {
+    const set = new Set([1, 2, 3, 4].map(m => H.multiplierColor(m, false)));
+    assert.equal(set.size, 4);
+    assert.equal(H.multiplierColor(8, true), H.multiplierColor(2, true));
+    assert.equal(H.multiplierColor(6, false), H.multiplierColor(8, true));
+});
+
+test('starProgress: stars earned and progress to the next threshold', () => {
+    const th = [100, 200, 400, 800, 1600, 2400];
+    assert.deepEqual(H.starProgress({ score: 0, starThresholds: th }), { count: 0, frac: 0, gold: false });
+    assert.deepEqual(H.starProgress({ score: 50, starThresholds: th }), { count: 0, frac: 0.5, gold: false });
+    assert.deepEqual(H.starProgress({ score: 300, starThresholds: th }), { count: 2, frac: 0.5, gold: false });
+    assert.deepEqual(H.starProgress({ score: 2400, starThresholds: th }), { count: 6, frac: 1, gold: true });
+    assert.deepEqual(H.starProgress(null), { count: 0, frac: 1, gold: false });
+});
+
+test('hudModel turns DrumsEngine.getState() into HUD values', () => {
+    const eng = E.create(E.decodeNotes([w(1, 38), w(2, 38)]));
+    const m0 = H.hudModel(eng.getState());
+    assert.equal(m0.score, '0');
+    assert.equal(m0.multiplierText, 'x1');
+    assert.equal(m0.streakText, '0');
+    assert.equal(m0.accuracy, '100.0%');
+    assert.equal(m0.hitsText, '0 / 2');
+    assert.equal(m0.spActive, false);
+    const st = { score: 12345, combo: 37, multiplier: 8, maxMultiplier: 4, accuracy: 0.5, notesHit: 37, totalNotes: 74,
+        starThresholds: [1, 2, 3, 4, 5, 99999], starPower: { amount: 0.625, active: true, canActivate: false } };
+    const m = H.hudModel(st);
+    assert.equal(m.score, '12,345');
+    assert.equal(m.multiplierText, 'x8');
+    assert.equal(m.multiplierProgress, 1, 'base x4 is maxed');
+    assert.equal(m.multiplierColor, H.multiplierColor(8, true));
+    assert.equal(m.spAmount, 0.625);
+    assert.equal(m.spActive, true);
+    assert.equal(m.stars, 5);
+    assert.equal(m.accuracy, '50.0%');
+    assert.equal(H.hudModel({ combo: 13, multiplier: 2, maxMultiplier: 4 }).multiplierProgress, 0.3);
+    assert.equal(H.hudModel(null).score, '0');
+});
+
+// ── session ───────────────────────────────────────────────────────────────
+
+function chart() {
+    // 4/4 at 120 BPM: beats every 0.5 s. Snare + kick on every beat from t=1 to t=12.5.
+    const notes = [];
+    const beats = [];
+    for (let i = 0; i < 40; i++) beats.push({ time: i * 0.5, measure: i % 4 === 0 ? i / 4 + 1 : -1 });
+    for (let t = 1; t <= 12.5; t += 0.5) notes.push(w(t, 38), w(t, 36));
+    return { notes, chords: [], beats };
+}
+
+function playPerfect(s, from, to) {
+    for (const g of s.gems) {
+        if (g.t < from || g.t > to) continue;
+        s.update(g.t);
+        s.hit(g.t + 0.005, g.pad, { cymbal: g.cymbal });
+    }
+    s.update(to);
+}
+
+test('session: load builds the engine and render model; perfect play scores and queues hit events', () => {
+    let wall = 0;
+    const s = H.createSession(E, { now: () => wall });
+    s.load(chart());
+    assert.equal(s.gems.length, 48);
+    assert.equal(s.getState().totalNotes, 48);
+    assert.equal(s.beats.length, 40);
+    playPerfect(s, 0, 5.2);
+    const st = s.getState();
+    assert.equal(st.notesHit, 18);
+    assert.equal(st.combo, 18);
+    assert.equal(st.multiplier, 2);
+    const ev = s.drainEvents();
+    assert.equal(ev.filter(e => e.type === 'hit').length, 18);
+    assert.equal(ev.filter(e => e.type === 'press').length, 18);
+    assert.equal(s.drainEvents().length, 0, 'drain empties the queue');
+    assert.ok(ev.every(e => e.wall === 0));
+});
+
+test('session bonus: perfect timing, snare roll, drum solo bonus and rating', () => {
+    let wall = 0;
+    const s = H.createSession(E, { now: () => wall });
+    // 16 snare notes 0.1 s apart from 1.0 s (the 14 with >= 4 neighbours within 0.25 s form the roll), inside a drum solo 0.9-3.0 s; a kick at 4 s.
+    const notes = [];
+    for (let i = 0; i < 16; i++) notes.push({ t: 1 + i * 0.1, s: 1, f: 14 });
+    notes.push({ t: 4, s: 1, f: 12 });
+    const beats = [];
+    for (let i = 0; i < 12; i++) beats.push({ time: i * 0.5, measure: i % 4 === 0 ? i / 4 : -1 });
+    s.load({ notes, chords: [], beats });
+    s.setMeta(tabMeta({ solos: [{ start_time: 0.9, end_time: 3.0 }] }));
+    playPerfect(s, 0, 3.5);
+    const b = s.getBonus();
+    assert.equal(b.perfect, 16, 'every hit within 25 ms');
+    assert.ok(b.rolls > 0, 'roll bonus');
+    assert.equal(b.solos.length, 1);
+    assert.equal(b.solos[0].rating, 'PERFECT SOLO!');
+    assert.equal(b.solos[0].bonus, 16 * 100 * 2);
+    assert.equal(b.total, b.timing + b.rolls + b.solo);
+    const ev = s.drainEvents();
+    assert.ok(ev.some(e => e.type === 'solo-end'));
+    assert.ok(ev.some(e => e.type === 'bonus-pop' && /^ROLL 14\/14 /.test(e.text)));
+    // a seek rebuilds the engine: score and bonuses start over
+    s.update(0.2);
+    assert.equal(s.getBonus().total, 0);
+});
+
+test('session: misses and overhits queue events for the view', () => {
+    const s = H.createSession(E);
+    s.load(chart());
+    s.update(1); s.hit(1, 1); s.hit(1, 0);   // hit both notes at t=1
+    s.update(1.4); s.hit(1.4, 3);            // blue overhit
+    s.update(2);                             // t=1.5 notes missed
+    const types = s.drainEvents().map(e => e.type + (e.pad != null ? ':' + e.pad : ''));
+    assert.ok(types.includes('overhit:3'));
+    assert.ok(types.includes('miss:1') && types.includes('miss:0'));
+    assert.ok(types.includes('combo-break'));
+});
+
+test('session: a backward seek rebuilds the engine from the new position', () => {
+    const s = H.createSession(E);
+    s.load(chart());
+    playPerfect(s, 0, 6);
+    const before = s.builds;
+    assert.ok(s.getState().score > 0);
+    s.update(3);                             // seek back
+    assert.equal(s.builds, before + 1);
+    const st = s.getState();
+    assert.equal(st.score, 0);
+    assert.equal(st.totalNotes, 40, 'notes before the seek point are left out');
+    playPerfect(s, 3, 4);
+    assert.equal(s.getState().notesHit, 6);
+    s.update(4.016);
+    assert.equal(s.builds, before + 1, 'normal playback does not rebuild');
+    s.update(9);                             // big forward jump
+    assert.equal(s.builds, before + 2);
+    assert.equal(s.getState().notesMissed, 0, 'skipped notes are not counted as misses');
+});
+
+test('session: a chart loaded mid-song scores from the first frame, not from the song start', () => {
+    const s = H.createSession(E);
+    s.load(chart());
+    s.update(6.2);
+    const st = s.getState();
+    assert.equal(st.notesMissed, 0);
+    assert.equal(st.totalNotes, 26);
+    const s2 = H.createSession(E);
+    s2.load(chart());
+    s2.update(0);                            // normal start: nothing rebuilt
+    assert.equal(s2.builds, 1);
+    assert.equal(s2.getState().totalNotes, 48);
+});
+
+test('session: setMeta applies star power phrases and drum fills (activation by the fill-end note)', () => {
+    const s = H.createSession(E);
+    s.load(chart());
+    // phrases: two 2-beat phrases -> half a bar; fill ending at t=8 activates star power
+    s.setMeta(tabMeta({ star_power: [{ start_time: 1, end_time: 2 }, { start_time: 3, end_time: 4 }],
+        fills: [{ start_time: 7, end_time: 8 }] }));
+    assert.ok(s.engine.isStarPowerNote(s.gems[0].id));
+    playPerfect(s, 0, 7.9);
+    let st = s.getState();
+    assert.equal(st.starPower.phrasesHit, 2);
+    assert.equal(st.starPower.canActivate, true);
+    assert.equal(s.activate(7.9), false, 'fills disable manual activation');
+    const ev1 = s.drainEvents();
+    assert.ok(ev1.some(e => e.type === 'hit' && e.sp));
+    assert.ok(ev1.some(e => e.type === 'sp-phrase'));
+    assert.ok(ev1.some(e => e.type === 'sp-ready'));
+    playPerfect(s, 7.95, 8.2);
+    st = s.getState();
+    assert.equal(st.starPower.active, true);
+    assert.ok(s.drainEvents().some(e => e.type === 'sp-activate'));
+    assert.equal(st.multiplier, 8, 'x4 doubled by star power');
+});
+
+test('session: without gameplay metadata there is no star power and manual activation is allowed', () => {
+    const s = H.createSession(E);
+    s.load(chart());
+    s.setMeta(null);
+    assert.equal(s.getState().starPower.phrasesTotal, 0);
+    assert.equal(s.engine.manualActivation, true);
+    assert.equal(s.activate(1), false, 'empty bar');
+});
+
+test('session: setMeta mid-song rebuilds from the current time; hits during a seek are ignored', () => {
+    const s = H.createSession(E);
+    s.load(chart());
+    playPerfect(s, 0, 4.2);
+    const b = s.builds;
+    s.setMeta(tabMeta({ star_power: [{ start_time: 6, end_time: 7 }] }));
+    assert.equal(s.builds, b + 1);
+    assert.equal(s.getState().totalNotes, 34);
+    assert.equal(s.getState().starPower.phrasesTotal, 1);
+    assert.deepEqual(s.hit(1, 1), { type: 'ignored', reason: 'seek' });
+    assert.deepEqual(H.createSession(E).hit(1, 1), { type: 'ignored', reason: 'no-chart' });
+});
+
+// ── non-pro drums ("Pro cymbals" off) ──────────────────────────────────────
+
+test('classifyNote / buildGems with pro:false draw cymbals as pads and merge a same-colour tom+cymbal', () => {
+    assert.equal(H.classifyNote({ pad: 2, cymbal: true }, { pro: false }).kind, 'pad');
+    assert.equal(H.classifyNote({ pad: 2, cymbal: true }, { pro: false }).cymbal, false);
+    // yellow tom (48) + hi-hat (42) together, then a ride (51) alone
+    const decoded = E.decodeNotes([w(1, 48), w(1, 42), w(2, 51)], { kick2x: true });
+    const pro = H.buildGems(decoded);
+    assert.deepEqual(pro.map(g => g.kind), ['pad', 'cymbal', 'cymbal']);
+    const plain = H.buildGems(decoded, { pro: false });
+    assert.deepEqual(plain.map(g => [g.t, g.kind, g.lane]), [[1, 'pad', 1], [2, 'pad', 2]]);
+});
+
+test('session: setProDrums(false) lets a cymbal input hit a tom note and redraws without cymbals', () => {
+    const notes = [w(1, 48), w(2, 51)];         // yellow tom, blue cymbal (ride)
+    const pro = H.createSession(E).load({ notes });
+    pro.update(1); const r1 = pro.hit(1, 2, { cymbal: true });   // hi-hat on a yellow tom note
+    assert.notEqual(r1.type, 'hit', 'pro drums: wrong pad type');
+    assert.equal(pro.proDrums, true);
+
+    const s = H.createSession(E, { proDrums: false }).load({ notes });
+    assert.equal(s.proDrums, false);
+    assert.ok(s.gems.every(g => g.kind === 'pad'));
+    s.update(1); assert.equal(s.hit(1, 2, { cymbal: true }).type, 'hit');
+    s.update(2); assert.equal(s.hit(2, 3).type, 'hit', 'blue tom pad hits the (non-pro) ride note');
+    assert.equal(s.getState().notesHit, 2);
+
+    // switching mid-song rebuilds from the current position, and back again
+    const m = H.createSession(E).load({ notes });
+    m.update(1.5);
+    m.setProDrums(false);
+    assert.ok(m.gems.every(g => g.kind === 'pad'));
+    m.update(2); assert.equal(m.hit(2, 3).type, 'hit');
+    m.setProDrums(true);
+    assert.equal(m.gems.filter(g => g.kind === 'cymbal').length, 1);
+});
+
+test('session: a chart marked non-pro stays non-pro even with Pro cymbals on', () => {
+    const s = H.createSession(E).load({ notes: [w(1, 42)] });
+    s.setMeta({ pro: false, starPower: [], activation: [], solos: [], levels: null, levelsGenerated: [] });
+    assert.equal(s.proDrums, false);
+    assert.equal(s.gems[0].kind, 'pad');
+});
+
+// ── auto kick / auto cymbals ───────────────────────────────────────────────
+
+test('autoAppliesAt / autoFor: each setting is a difficulty ceiling', () => {
+    assert.equal(H.autoAppliesAt('off', 'easy'), false);
+    assert.equal(H.autoAppliesAt('all', 'expert_plus'), true);
+    assert.equal(H.autoAppliesAt('easy', 'easy'), true);
+    assert.equal(H.autoAppliesAt('easy', 'medium'), false);
+    assert.equal(H.autoAppliesAt('hard', 'medium'), true);
+    assert.equal(H.autoAppliesAt('hard', 'expert'), false);
+    assert.equal(H.autoAppliesAt('bogus', 'easy'), false);
+    assert.deepEqual(H.autoFor({ kick: 'medium', cymbals: 'off' }, 'easy'), { kick: true, cymbals: false });
+    assert.deepEqual(H.autoFor(null, 'easy'), { kick: false, cymbals: false });
+});
+
+test('isAutoNote: kick by pad, cymbals by the chart marking (never red)', () => {
+    const a = { kick: true, cymbals: true };
+    assert.equal(H.isAutoNote(H.PAD.KICK, false, a), true);
+    assert.equal(H.isAutoNote(H.PAD.YELLOW, true, a), true);
+    assert.equal(H.isAutoNote(H.PAD.YELLOW, false, a), false);
+    assert.equal(H.isAutoNote(H.PAD.RED, true, a), false);
+    assert.equal(H.isAutoNote(H.PAD.KICK, false, { kick: false, cymbals: true }), false);
+    assert.equal(H.isAutoNote(H.PAD.KICK, false, null), false);
+});
+
+test('session: auto kick leaves kicks out of scoring, ignores kick input and flashes them as played', () => {
+    // kick+hi-hat, snare, kick+hi-hat
+    const notes = [w(1, 36), w(1, 42), w(2, 38), w(3, 36), w(3, 42)];
+    const s = H.createSession(E, { auto: { kick: true } }).load({ notes });
+    assert.equal(s.getState().totalNotes, 3, 'kicks are not scored');
+    assert.equal(s.gems.filter(g => g.auto).length, 2, 'kicks are still drawn, marked auto');
+    assert.deepEqual(s.auto, { kick: true, cymbals: false });
+    s.update(0.5); s.drainEvents();
+    s.update(1);
+    const ev = s.drainEvents();
+    assert.ok(ev.some(e => e.type === 'hit' && e.auto && e.pad === H.PAD.KICK), 'kick flashes at the strikeline');
+    assert.equal(s.hit(1, H.PAD.KICK).reason, 'auto', 'kick pedal is ignored');
+    assert.equal(s.hit(1, H.PAD.YELLOW, { cymbal: true }).type, 'hit');
+    s.update(2); assert.equal(s.hit(2, H.PAD.RED).type, 'hit');
+    s.update(3); assert.equal(s.hit(3, H.PAD.YELLOW, { cymbal: true }).type, 'hit');
+    s.update(4);
+    const st = s.getState();
+    assert.equal(st.notesHit, 3);
+    assert.equal(st.notesMissed, 0);
+    assert.equal(st.overhits, 0);
+});
+
+test('session: auto cymbals; setAuto mid-song rescoring from the current time', () => {
+    const notes = [w(1, 42), w(1, 38), w(2, 49), w(2, 36), w(3, 51), w(3, 38)];
+    const s = H.createSession(E).load({ notes });
+    assert.equal(s.getState().totalNotes, 6);
+    s.update(1.5);
+    s.setAuto({ cymbals: true });
+    assert.equal(s.gems.filter(g => g.auto).length, 3);
+    assert.equal(s.hit(2, H.PAD.GREEN, { cymbal: true }).reason, 'auto', 'cymbal pads are ignored');
+    s.update(2); assert.equal(s.hit(2, H.PAD.KICK).type, 'hit');
+    s.update(3); assert.equal(s.hit(3, H.PAD.RED).type, 'hit');
+    s.update(4);
+    assert.equal(s.getState().notesMissed, 0, 'the auto ride is not missed');
+    // unchanged setting -> no rebuild
+    const b = s.builds;
+    s.setAuto({ cymbals: true, kick: false });
+    assert.equal(s.builds, b);
+});
+
+test('session: setParams widens the hit window', () => {
+    const notes = [w(1, 38)];
+    const n = H.createSession(E).load({ notes });
+    n.update(0.5); n.update(1.09); assert.notEqual(n.hit(1.09, H.PAD.RED).type, 'hit', 'normal window is +-70 ms');
+    const r = H.createSession(E, { params: { hitWindow: { maxWindow: 0.26, minWindow: 0.26 } } }).load({ notes });
+    r.update(0.5); r.update(1.09); assert.equal(r.hit(1.09, H.PAD.RED).type, 'hit', 'relaxed window is +-130 ms');
+    const m = H.createSession(E).load({ notes });
+    m.update(0.5);
+    m.setParams({ hitWindow: { maxWindow: 0.26, minWindow: 0.26 } });
+    m.update(1.09); assert.equal(m.hit(1.09, H.PAD.RED).type, 'hit');
+});
+
+// ── hit timing: input offset, engine grace, timing meter, frame clock ─────
+
+test('session: a positive input offset delays the engine too, so a late-registered hit still counts', () => {
+    // Note at t=1.0. The player's hits register 200 ms late (input offset +200 ms):
+    // the pad is struck on the beat but the hit arrives at highway time 1.2.
+    const s = H.createSession(E, { inputOffsetMs: 200 });
+    s.load({ notes: [w(1, 38)], chords: [], beats: [] });
+    s.update(0.9);
+    s.update(1.25);            // the frame drawn before the late hit arrives
+    const r = s.hit(1.2, H.PAD.RED);
+    assert.equal(r.type, 'hit', 'the engine has not moved past the note yet');
+    assert.ok(Math.abs(r.offset) < 0.001, 'judged on time once the offset is applied');
+    s.update(2);
+    assert.equal(s.getState().notesMissed, 0);
+    assert.equal(s.inputOffsetMs, 200);
+
+    // An engine advanced on the raw frame time (the old behaviour: offset 0 for the frame
+    // clock) has already missed the note when the same late hit arrives.
+    const s0 = H.createSession(E);
+    s0.load({ notes: [w(1, 38)], chords: [], beats: [] });
+    s0.update(0.9); s0.update(1.25);
+    assert.notEqual(s0.hit(1.2 - 0.2, H.PAD.RED).type, 'hit');
+    assert.equal(s0.getState().notesMissed, 1);
+});
+
+test('session: setInputOffset applies to later frames and hits, and restarts the timing meter', () => {
+    const s = H.createSession(E);
+    s.load({ notes: [w(1, 38), w(2, 38)], chords: [], beats: [] });
+    s.update(0.95); s.hit(1.03, H.PAD.RED);   // 30 ms late
+    assert.deepEqual(s.getBonus().offsets, [30]);
+    s.setInputOffset(30);
+    assert.deepEqual(s.getBonus().offsets, [], 'samples measured with the old offset are dropped');
+    s.update(1.95); s.hit(2.03, H.PAD.RED);
+    assert.deepEqual(s.getBonus().offsets, [0]);
+    s.setInputOffset('junk');
+    assert.equal(s.inputOffsetMs, 0);
+    s.setInputOffset(999);
+    assert.equal(s.inputOffsetMs, 250, 'clamped like the settings field');
+});
+
+test('session: a hit timestamped before the latest frame keeps its own time (not moved to the frame)', () => {
+    const s = H.createSession(E);
+    s.load({ notes: [w(1, 38)], chords: [], beats: [] });
+    const seen = [];
+    s.setOnHit((h) => seen.push(h));
+    s.update(0.9);
+    s.update(1.016);           // the frame after the note at t=1 was drawn...
+    s.hit(1.004, H.PAD.RED);   // ...then a hit struck at 1.004 arrives (MIDI timestamp)
+    assert.equal(seen.length, 1);
+    assert.ok(Math.abs(seen[0].time - 1.004) < 1e-9, 'judged at the strike, not at the frame time 1.016');
+    assert.equal(seen[0].noteTime, 1);
+    s.update(1.5);
+    assert.equal(s.getState().notesHit, 1);
+    // misses are still found, INPUT_GRACE later
+    const m = H.createSession(E);
+    m.load({ notes: [w(1, 38)], chords: [], beats: [] });
+    m.update(0.9); m.update(1.08);
+    assert.equal(m.getState().notesMissed, 0, 'still inside the window + grace');
+    m.update(1.2);
+    assert.equal(m.getState().notesMissed, 1);
+});
+
+test('session: MIDI velocity normalised to 0..1 decides the dynamics bonus (soft hit on an accent gets none)', () => {
+    const play = (vel) => {
+        const s = H.createSession(E);
+        s.load({ notes: [w(1, 38, { ac: true })], chords: [], beats: [] });
+        s.update(0.95);
+        const r = s.hit(1.0, H.PAD.RED, { velocity: vel });
+        s.update(1.5);
+        return { r, st: s.getState() };
+    };
+    const soft = play(1 / 127);   // screen.js passes velocity / 127
+    assert.equal(soft.r.type, 'hit');
+    assert.equal(soft.r.bonus, false, 'velocity 1 is the softest hit, not full strength');
+    const hard = play(127 / 127);
+    assert.equal(hard.r.bonus, true);
+    assert.ok(hard.st.score > soft.st.score);
+});
+
+test('session: activate() uses the input offset and works on a chart without fills', () => {
+    const s = H.createSession(E, { inputOffsetMs: 40 });
+    s.load(chart());
+    s.setMeta(tabMeta({ star_power: [{ start_time: 1, end_time: 2 }, { start_time: 3, end_time: 4 }] }));
+    playPerfect(s, 0, 5);
+    const st = s.getState();
+    assert.equal(st.starPower.canActivate, true);
+    assert.equal(s.engine.manualActivation, true, 'no fills: manual activation');
+    assert.equal(H.starPowerHint(s.meta, st, 'hi-hat pedal'), 'Press Enter or hit hi-hat pedal to activate star power');
+    assert.equal(s.activate(5.05), true);
+    assert.equal(s.getState().starPower.active, true);
+    assert.equal(H.starPowerHint(s.meta, s.getState(), ''), null, 'no hint while active');
+    assert.equal(s.activate(NaN), false);
+});
+
+test('starPowerHint: fills say how they activate; nothing while not ready', () => {
+    const ready = { starPower: { canActivate: true, active: false } };
+    assert.equal(H.starPowerHint({ activation: [{ start: 1, end: 2 }] }, ready, ''), 'Hit the note at the end of the fill to activate');
+    assert.equal(H.starPowerHint(null, ready, ''), 'Press Enter to activate star power');
+    assert.equal(H.starPowerHint(null, { starPower: { canActivate: false } }, ''), null);
+    assert.equal(H.starPowerHint(null, null, ''), null);
+});
+
+test('timingSummary: median, early / late label and the suggested input offset', () => {
+    assert.deepEqual(H.timingSummary([], 0), { count: 0, median: null, state: 'waiting', label: 'waiting for hits', suggest: null, current: 0 });
+    const late = H.timingSummary([20, 25, 30, 28, 22, 35, 400], 10);
+    assert.equal(late.median, 28);
+    assert.equal(late.state, 'late');
+    assert.equal(late.label, '+28 ms LATE');
+    assert.equal(late.suggest, 38, 'current offset + median');
+    const early = H.timingSummary([-30, -30, -30, -30, -30, -30], 0);
+    assert.equal(early.label, '-30 ms EARLY');
+    assert.equal(early.suggest, -30);
+    const ok = H.timingSummary([4, -3, 5, -6, 2, 0], 12);
+    assert.equal(ok.state, 'ok');
+    assert.equal(ok.label, 'ON TIME');
+    assert.equal(ok.suggest, null);
+    assert.equal(H.timingSummary([40, 40, 40], 0).suggest, null, 'needs 6 hits before suggesting');
+    assert.equal(H.timingSummary([200, 200, 200, 200, 200, 200], 200).suggest, 250, 'clamped to the field range');
+});
+
+test('session: the timing meter keeps the last 24 hits and survives a seek', () => {
+    const s = H.createSession(E);
+    const notes = [];
+    for (let i = 0; i < 30; i++) notes.push(w(1 + i * 0.5, 38));
+    s.load({ notes, chords: [], beats: [] });
+    for (const n of notes) { s.update(n.t - 0.01); s.hit(n.t + 0.012, H.PAD.RED); }
+    const offs = s.getBonus().offsets;
+    assert.equal(offs.length, H.TIMING_SAMPLES);
+    assert.ok(offs.every(v => v === 12));
+    s.update(2);   // seek back: the score restarts, the timing samples stay
+    assert.equal(s.getBonus().total, 0);
+    assert.equal(s.getBonus().offsets.length, H.TIMING_SAMPLES);
+    s.resetTiming();
+    assert.deepEqual(s.getBonus().offsets, []);
+});
+
+test('createFrameClock: interpolates between audio samples, holds while paused, times past input', () => {
+    const c = H.createFrameClock();
+    assert.ok(Number.isNaN(c.at(0)));
+    assert.equal(c.tick(10, true, 1000), 10);
+    assert.equal(c.tick(10.02, true, 1020), 10.02);           // new sample: rate 1
+    assert.ok(Math.abs(c.tick(10.02, true, 1030) - 10.03) < 1e-9, 'same sample: interpolated');
+    assert.ok(Math.abs(c.at(1025) - 10.025) < 1e-9, 'a hit between frames');
+    assert.ok(Math.abs(c.at(1010) - 10.01) < 1e-9, 'a hit timestamped before the last sample');
+    assert.ok(Math.abs(c.at(1500) - 10.12) < 1e-9, 'capped 100 ms ahead');
+    // paused (core's bundle.isPlaying false): no interpolation
+    assert.equal(c.tick(10.5, false, 2000), 10.5);
+    assert.equal(c.tick(10.5, false, 2050), 10.5);
+    assert.equal(c.at(2060), 10.5);
+    // older hosts (isPlaying undefined): a stalled sample stops interpolating after 100 ms
+    const d = H.createFrameClock();
+    d.tick(5, undefined, 0); d.tick(5.016, undefined, 16);
+    assert.ok(d.tick(5.016, undefined, 30) > 5.016);
+    assert.equal(d.tick(5.016, undefined, 200), 5.016);
+    assert.equal(d.at(210), 5.016);
+    // half speed: the rate is measured
+    const e = H.createFrameClock();
+    e.tick(1, true, 0); e.tick(1.01, true, 20);
+    assert.ok(Math.abs(e.tick(1.01, true, 30) - 1.015) < 1e-9);
+    c.reset();
+    assert.ok(Number.isNaN(c.at(0)));
+});