A new startv1.0.0

10 files changed, 4431 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..e15106e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..f288702
--- /dev/null
+++ b/LICENSE
@@ -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/README.md b/README.md
new file mode 100644
index 0000000..f1e14fd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,149 @@
+# scopekit
+
+`scopekit` is a Python library for creating high-performance, interactive oscilloscope-style plots for large time-series datasets using `matplotlib`.
+
+It is designed to handle millions of data points smoothly by automatically decimating data for the current view. When zoomed out, it displays a performance-optimized "envelope" view, and when zoomed in, it seamlessly transitions to show detailed raw data.
+
+## Installation
+
+To install the package from your local repository, run:
+
+```bash
+pip install .
+```
+
+## Quickstart Example
+
+Here is a simple example of how to create a plot with `scopekit`.
+
+```python
+import numpy as np
+from scopekit import OscilloscopePlot
+
+# 1. Generate some sample data
+fs = 1e7  # 10 MHz sampling rate
+duration = 0.1  # 0.1 seconds of data
+t = np.arange(0, duration, 1/fs)
+# A 50 Hz signal with some high-frequency noise
+x = np.sin(2 * np.pi * 50 * t) + np.sin(2 * np.pi * 1e3 * t) * 0.2
+
+# 2. Create an OscilloscopePlot instance
+# The plot automatically handles decimation and display modes.
+plot = OscilloscopePlot(t, x, name="Sample Waveform")
+
+# 3. Render the plot
+# This creates the matplotlib figure and axes.
+plot.render()
+
+# 4. Show the plot
+# The plot is now interactive: zoom with the mouse and use the toolbar.
+plot.show()
+```
+
+## API Reference
+
+The primary interface for the library is the `OscilloscopePlot` class.
+
+### `OscilloscopePlot`
+
+#### `__init__`
+
+```python
+def __init__(
+    self,
+    t: Union[np.ndarray, List[np.ndarray]],
+    x: Union[np.ndarray, List[np.ndarray]],
+    name: Union[str, List[str]] = "Waveform",
+    trace_colors: Optional[List[str]] = None,
+    max_plot_points: int = 10000,
+    mode_switch_threshold: float = 10e-3,
+    min_y_range: Optional[float] = None,
+    y_margin_fraction: float = 0.15,
+    signal_line_width: float = 1.0,
+    signal_alpha: float = 0.75,
+    envelope_alpha: float = 0.75,
+    region_alpha: float = 0.4,
+    region_zorder: int = -5,
+    envelope_window_samples: Optional[int] = None,
+):
+```
+
+#### Methods
+
+```python
+def add_line(
+    self,
+    t: Union[np.ndarray, List[np.ndarray]],
+    data: Union[np.ndarray, List[np.ndarray]],
+    label: str = "Line",
+    color: Optional[str] = None,
+    alpha: float = 0.75,
+    linestyle: str = "-",
+    linewidth: float = 1.0,
+    display_mode: int = MODE_BOTH,
+    trace_idx: int = 0,
+    zorder: int = 5,
+) -> None:
+```
+
+```python
+def add_ribbon(
+    self,
+    t: Union[np.ndarray, List[np.ndarray]],
+    center_data: Union[np.ndarray, List[np.ndarray]],
+    width: Union[float, np.ndarray],
+    label: str = "Ribbon",
+    color: str = "gray",
+    alpha: float = 0.6,
+    display_mode: int = MODE_DETAIL,
+    trace_idx: int = 0,
+    zorder: int = 2,
+) -> None:
+```
+
+```python
+def add_envelope(
+    self,
+    min_data: Union[np.ndarray, List[np.ndarray]],
+    max_data: Union[np.ndarray, List[np.ndarray]],
+    label: str = "Envelope",
+    color: Optional[str] = None,
+    alpha: float = 0.4,
+    display_mode: int = MODE_ENVELOPE,
+    trace_idx: int = 0,
+    zorder: int = 1,
+) -> None:
+```
+
+```python
+def add_regions(
+    self,
+    regions: np.ndarray,
+    label: str = "Regions",
+    color: str = "crimson",
+    alpha: float = 0.4,
+    display_mode: int = MODE_BOTH,
+    trace_idx: int = 0,
+    zorder: int = -5,
+) -> None:
+```
+
+```python
+def render(self) -> None:
+```
+
+```python
+def show(self) -> None:
+```
+
+```python
+def save(self, filepath: str) -> None:
+```
+
+```python
+def home(self) -> None:
+```
+
+```python
+def refresh(self) -> None:
+```
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..e265c03
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,19 @@
+[project]
+name = "scopekit"
+version = "0.1.0"
+description = "General-purpose oscilloscope plotting components."
+authors = [{ name = "Sam Scholten", email = "s.scholten@uq.edu.au" }]
+requires-python = ">=3.8"
+dependencies = [
+    "numpy",
+    "matplotlib",
+    "numba",
+    "PyQt6" # I guess flexible on this??
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
diff --git a/src/scopekit/__init__.py b/src/scopekit/__init__.py
new file mode 100644
index 0000000..082e66a
--- /dev/null
+++ b/src/scopekit/__init__.py
@@ -0,0 +1,20 @@
+"""

+General-purpose oscilloscope plotting components for PyOSC.

+

+This package contains the core plotting functionality that can be used

+with any time-series data, not just waveforms.

+"""

+

+from .coordinate_manager import CoordinateManager

+from .data_manager import TimeSeriesDataManager

+from .decimation import DecimationManager

+from .display_state import DisplayState

+from .plot import OscilloscopePlot

+

+__all__ = [

+    "OscilloscopePlot",

+    "TimeSeriesDataManager",

+    "CoordinateManager",

+    "DisplayState",

+    "DecimationManager",

+]

diff --git a/src/scopekit/coordinate_manager.py b/src/scopekit/coordinate_manager.py
new file mode 100644
index 0000000..6ee1709
--- /dev/null
+++ b/src/scopekit/coordinate_manager.py
@@ -0,0 +1,107 @@
+from typing import Tuple

+

+import numpy as np

+from loguru import logger

+

+

+class CoordinateManager:

+    """

+    Handles coordinate transformations between raw time and display coordinates.

+

+    Centralises all coordinate conversion logic to prevent inconsistencies.

+    """

+

+    def __init__(self, display_state):

+        """

+        Initialise the coordinate manager.

+

+        Parameters

+        ----------

+        display_state : DisplayState

+            Reference to the display state object.

+        """

+        self.state = display_state

+

+    def get_current_view_raw(self, ax):

+        """Get current view in raw coordinates."""

+        try:

+            xlim_display = ax.get_xlim()

+            logger.debug(f"Converting display xlim {xlim_display} to raw coordinates")

+

+            # Validate display limits

+            if not np.isfinite(xlim_display[0]) or not np.isfinite(xlim_display[1]):

+                logger.warning(f"Invalid display limits: {xlim_display}")

+                # Try to get a valid view from the figure

+                if hasattr(ax, "figure") and hasattr(ax.figure, "canvas"):

+                    ax.figure.canvas.draw()

+                    xlim_display = ax.get_xlim()

+                    if not np.isfinite(xlim_display[0]) or not np.isfinite(

+                        xlim_display[1]

+                    ):

+                        # Still invalid, use a default range

+                        logger.warning(

+                            "Still invalid after redraw, using default range"

+                        )

+                        xlim_display = (0, 1)

+

+            raw_coords = self.xlim_display_to_raw(xlim_display)

+            logger.debug(f"Converted to raw coordinates: {raw_coords}")

+            return raw_coords

+        except Exception as e:

+            logger.exception(f"Error getting current view: {e}")

+            # Return a safe default

+            return (np.float32(0.0), np.float32(1.0))

+

+    def set_view_raw(self, ax, xlim_raw):

+        """Set view using raw coordinates."""

+        xlim_display = self.xlim_raw_to_display(xlim_raw)

+        ax.set_xlim(xlim_display)

+

+    def raw_to_display(self, t_raw: np.ndarray) -> np.ndarray:

+        """Convert raw time to display coordinates."""

+        if self.state.offset_time_raw is not None:

+            return (t_raw - self.state.offset_time_raw) * self.state.current_time_scale

+        else:

+            return t_raw * self.state.current_time_scale

+

+    def display_to_raw(self, t_display: np.ndarray) -> np.ndarray:

+        """Convert display coordinates to raw time."""

+        t_raw = t_display / self.state.current_time_scale

+        if self.state.offset_time_raw is not None:

+            t_raw += self.state.offset_time_raw

+

+        # Only log for scalar values to avoid excessive output

+        if isinstance(t_display, (int, float, np.number)):

+            logger.debug(

+                f"Converting display time {t_display:.6f} to raw time {t_raw:.6f} (scale={self.state.current_time_scale}, offset={self.state.offset_time_raw})"

+            )

+        return t_raw

+

+    def xlim_display_to_raw(

+        self, xlim_display: Tuple[float, float]

+    ) -> Tuple[np.float32, np.float32]:

+        """Convert display xlim tuple to raw time coordinates."""

+        try:

+            # Ensure values are finite

+            if not np.isfinite(xlim_display[0]) or not np.isfinite(xlim_display[1]):

+                logger.warning(

+                    f"Non-finite display limits: {xlim_display}, using defaults"

+                )

+                return (np.float32(0.0), np.float32(1.0))

+

+            return (

+                self.display_to_raw(np.float32(xlim_display[0])),

+                self.display_to_raw(np.float32(xlim_display[1])),

+            )

+        except Exception as e:

+            logger.exception(f"Error converting display to raw coordinates: {e}")

+            return (np.float32(0.0), np.float32(1.0))

+

+    def xlim_raw_to_display(

+        self, xlim_raw: Tuple[np.float32, np.float32]

+    ) -> Tuple[np.float32, np.float32]:

+        """Convert raw time xlim tuple to display coordinates."""

+        return (

+            self.raw_to_display(xlim_raw[0]),

+            self.raw_to_display(xlim_raw[1]),

+        )

diff --git a/src/scopekit/data_manager.py b/src/scopekit/data_manager.py
new file mode 100644
index 0000000..c2dd09c
--- /dev/null
+++ b/src/scopekit/data_manager.py
@@ -0,0 +1,452 @@
+from typing import Any, Dict, List, Optional, Tuple, Union

+

+import numpy as np

+from loguru import logger

+

+

+class TimeSeriesDataManager:

+    """

+    Manages time series data storage and basic operations.

+

+    Handles raw data storage, time scaling, and basic data access patterns.

+    It can also store optional associated data like background estimates,

+    global noise, and overlay lines.

+

+    Supports multiple traces with shared time axis or individual time axes.

+    """

+

+    def __init__(

+        self,

+        t: Union[np.ndarray, List[np.ndarray]],

+        x: Union[np.ndarray, List[np.ndarray]],

+        name: Union[str, List[str]] = "Time Series",

+        trace_colors: Optional[List[str]] = None,

+    ):

+        """

+        Initialise the data manager.

+

+        Parameters

+        ----------

+        t : Union[np.ndarray, List[np.ndarray]]

+            Time array(s) (raw time in seconds). Can be a single array shared by all traces

+            or a list of arrays, one per trace.

+        x : Union[np.ndarray, List[np.ndarray]]

+            Signal array(s). If t is a single array, x can be a 2D array (traces x samples)

+            or a list of 1D arrays. If t is a list, x must be a list of equal length.

+        name : Union[str, List[str]], default="Time Series"

+            Name(s) for identification. Can be a single string or a list of strings.

+        trace_colors : Optional[List[str]], default=None

+            Colors for each trace. If None, default colors will be used.

+

+        Raises

+        ------

+        ValueError

+            If input arrays have mismatched lengths or time array is not monotonic.

+        """

+        # Convert inputs to standardized format: lists of arrays

+        self.t_arrays, self.x_arrays, self.names, self.colors = (

+            self._standardize_inputs(t, x, name, trace_colors)

+        )

+

+        # Validate all data

+        for i, (t_arr, x_arr) in enumerate(zip(self.t_arrays, self.x_arrays)):

+            self._validate_core_data(t_arr, x_arr, trace_idx=i)

+

+        # Optional associated data (per trace)

+        self._overlay_lines: List[List[Dict[str, Any]]] = [

+            [] for _ in range(len(self.t_arrays))

+        ]

+

+        # For backward compatibility

+        if len(self.t_arrays) > 0:

+            self.t = self.t_arrays[0]  # Primary time array

+            self.x = self.x_arrays[0]  # Primary signal array

+            self.name = self.names[0]  # Primary name

+

+    def _standardize_inputs(

+        self,

+        t: Union[np.ndarray, List[np.ndarray]],

+        x: Union[np.ndarray, List[np.ndarray]],

+        name: Union[str, List[str]],

+        trace_colors: Optional[List[str]],

+    ) -> Tuple[List[np.ndarray], List[np.ndarray], List[str], List[str]]:

+        """

+        Standardize inputs to lists of arrays.

+

+        Parameters

+        ----------

+        t : Union[np.ndarray, List[np.ndarray]]

+            Time array(s).

+        x : Union[np.ndarray, List[np.ndarray]]

+            Signal array(s).

+        name : Union[str, List[str]]

+            Name(s) for identification.

+        trace_colors : Optional[List[str]]

+            Colors for each trace.

+

+        Returns

+        -------

+        Tuple[List[np.ndarray], List[np.ndarray], List[str], List[str]]

+            Standardized lists of time arrays, signal arrays, names, and colors.

+        """

+        # Default colors for traces

+        default_colors = [

+            "black",

+            "blue",

+            "red",

+            "green",

+            "purple",

+            "orange",

+            "brown",

+            "pink",

+            "gray",

+            "olive",

+        ]

+

+        # Handle time arrays

+        if isinstance(t, list):

+            t_arrays = [np.asarray(t_arr, dtype=np.float32) for t_arr in t]

+            n_traces = len(t_arrays)

+        else:

+            t_arr = np.asarray(t, dtype=np.float32)

+

+            # Check if x is 2D array or list

+            if isinstance(x, list):

+                n_traces = len(x)

+                t_arrays = [t_arr.copy() for _ in range(n_traces)]

+            elif x.ndim == 2:

+                n_traces = x.shape[0]

+                t_arrays = [t_arr.copy() for _ in range(n_traces)]

+            else:

+                n_traces = 1

+                t_arrays = [t_arr]

+

+        # Handle signal arrays

+        if isinstance(x, list):

+            if len(x) != n_traces:

+                raise ValueError(

+                    f"Number of signal arrays ({len(x)}) must match number of time arrays ({n_traces})"

+                )

+            x_arrays = [np.asarray(x_arr, dtype=np.float32) for x_arr in x]

+        elif x.ndim == 2:

+            if x.shape[0] != n_traces:

+                raise ValueError(

+                    f"First dimension of 2D signal array ({x.shape[0]}) must match number of time arrays ({n_traces})"

+                )

+            x_arrays = [np.asarray(x[i], dtype=np.float32) for i in range(n_traces)]

+        else:

+            if n_traces != 1:

+                raise ValueError(

+                    f"Single signal array provided but expected {n_traces} arrays"

+                )

+            x_arrays = [np.asarray(x, dtype=np.float32)]

+

+        # Handle names

+        if isinstance(name, list):

+            if len(name) != n_traces:

+                logger.warning(

+                    f"Number of names ({len(name)}) doesn't match number of traces ({n_traces}). Using defaults."

+                )

+                names = [f"Trace {i + 1}" for i in range(n_traces)]

+            else:

+                names = name

+        else:

+            if n_traces == 1:

+                names = [name]

+            else:

+                if (

+                    name == "Time Series"

+                ):  # Only use default naming if the default name was used

+                    names = [f"Trace {i + 1}" for i in range(n_traces)]

+                else:

+                    names = [f"{name} {i + 1}" for i in range(n_traces)]

+

+        # Handle colors

+        if trace_colors is not None:

+            if len(trace_colors) < n_traces:

+                logger.warning(

+                    f"Not enough colors provided ({len(trace_colors)}). Using defaults for remaining traces."

+                )

+                colors = trace_colors + [

+                    default_colors[i % len(default_colors)]

+                    for i in range(len(trace_colors), n_traces)

+                ]

+            else:

+                colors = trace_colors[:n_traces]

+        else:

+            colors = [default_colors[i % len(default_colors)] for i in range(n_traces)]

+

+        return t_arrays, x_arrays, names, colors

+

+    def _validate_core_data(

+        self, t: np.ndarray, x: np.ndarray, trace_idx: int = 0

+    ) -> None:

+        """

+        Validate core input data arrays for consistency and correctness.

+

+        Parameters

+        ----------

+        t : np.ndarray

+            Time array.

+        x : np.ndarray

+            Signal array.

+        trace_idx : int, default=0

+            Index of the trace being validated (for error messages).

+

+        Raises

+        ------

+        ValueError

+            If arrays have mismatched lengths or time array is not monotonic.

+        """

+        if len(t) != len(x):

+            raise ValueError(

+                f"Time and signal arrays for trace {trace_idx} must have the same length. Got t={len(t)}, x={len(x)}"

+            )

+        if len(t) == 0:

+            logger.warning(f"Initialising trace {trace_idx} with empty arrays.")

+            return

+

+        # Check time array is monotonic

+        if len(t) > 1:

+            # Use a small epsilon for floating-point comparison

+            tolerance = 1e-9

+            if not np.all(np.diff(t) > tolerance):

+                problematic_diffs = np.diff(t)[np.diff(t) <= tolerance]

+                logger.warning(

+                    f"Time array for trace {trace_idx} is not strictly monotonic increasing within tolerance {tolerance}. "

+                    f"Problematic diffs (first 10): {problematic_diffs[:10]}. "

+                    f"This may affect analysis results."

+                )

+

+            # Check for non-uniform sampling

+            self._check_uniform_sampling(t, trace_idx)

+

+    @property

+    def overlay_lines(self) -> List[Dict[str, Any]]:

+        """Get overlay lines data for the primary trace."""

+        return self._overlay_lines[0] if self._overlay_lines else []

+

+    def get_overlay_lines(self, trace_idx: int = 0) -> List[Dict[str, Any]]:

+        """Get overlay lines data for a specific trace."""

+        if trace_idx < 0 or trace_idx >= len(self.t_arrays):

+            raise ValueError(

+                f"Invalid trace index: {trace_idx}. Must be between 0 and {len(self.t_arrays) - 1}."

+            )

+        return self._overlay_lines[trace_idx]

+

+    @property

+    def num_traces(self) -> int:

+        """Get the number of traces."""

+        return len(self.t_arrays)

+

+    def get_trace_color(self, trace_idx: int = 0) -> str:

+        """Get the color for a specific trace."""

+        if trace_idx < 0 or trace_idx >= len(self.t_arrays):

+            raise ValueError(

+                f"Invalid trace index: {trace_idx}. Must be between 0 and {len(self.t_arrays) - 1}."

+            )

+        return self.colors[trace_idx]

+

+    def get_trace_name(self, trace_idx: int = 0) -> str:

+        """Get the name for a specific trace."""

+        if trace_idx < 0 or trace_idx >= len(self.t_arrays):

+            raise ValueError(

+                f"Invalid trace index: {trace_idx}. Must be between 0 and {len(self.t_arrays) - 1}."

+            )

+        return self.names[trace_idx]

+

+    def set_overlay_lines(

+        self,

+        overlay_lines: Union[List[Dict[str, Any]], List[List[Dict[str, Any]]]],

+        trace_idx: Optional[int] = None,

+    ) -> None:

+        """

+        Set overlay lines data.

+

+        Parameters

+        ----------

+        overlay_lines : Union[List[Dict[str, Any]], List[List[Dict[str, Any]]]]

+            List of dictionaries defining overlay lines, or list of lists for multiple traces.

+        trace_idx : Optional[int], default=None

+            If provided, set overlay lines only for the specified trace.

+            If None, set for all traces if a nested list is provided, or for the first trace if a flat list.

+        """

+        if trace_idx is not None:

+            # Set for specific trace

+            if trace_idx < 0 or trace_idx >= len(self.t_arrays):

+                raise ValueError(

+                    f"Invalid trace index: {trace_idx}. Must be between 0 and {len(self.t_arrays) - 1}."

+                )

+

+            # Ensure we have a list of dictionaries

+            if not isinstance(overlay_lines, list):

+                raise ValueError(

+                    f"overlay_lines must be a list of dictionaries. Got {type(overlay_lines)}."

+                )

+

+            # Check if it's a list of dictionaries (not a nested list)

+            if len(overlay_lines) > 0 and isinstance(overlay_lines[0], dict):

+                self._overlay_lines[trace_idx] = overlay_lines

+            else:

+                raise ValueError(

+                    "Expected a list of dictionaries for overlay_lines when trace_idx is specified."

+                )

+        else:

+            # Set for all traces or first trace

+            if len(overlay_lines) > 0 and isinstance(overlay_lines[0], list):

+                # Nested list provided - set for multiple traces

+                if len(overlay_lines) != len(self.t_arrays):

+                    raise ValueError(

+                        f"Number of overlay line lists ({len(overlay_lines)}) must match number of traces ({len(self.t_arrays)})."

+                    )

+

+                for i, lines in enumerate(overlay_lines):

+                    self._overlay_lines[i] = lines

+            else:

+                # Flat list provided - set for first trace

+                self._overlay_lines[0] = overlay_lines

+

+    def get_time_range(self, trace_idx: int = 0) -> Tuple[np.float32, np.float32]:

+        """

+        Get the full time range of the data.

+

+        Parameters

+        ----------

+        trace_idx : int, default=0

+            Index of the trace to get the time range for.

+

+        Returns

+        -------

+        Tuple[np.float32, np.float32]

+            Start and end time of the data.

+        """

+        if trace_idx < 0 or trace_idx >= len(self.t_arrays):

+            raise ValueError(

+                f"Invalid trace index: {trace_idx}. Must be between 0 and {len(self.t_arrays) - 1}."

+            )

+

+        t_arr = self.t_arrays[trace_idx]

+        if t_arr.size == 0:

+            return np.float32(0.0), np.float32(0.0)

+        return np.float32(t_arr[0]), np.float32(t_arr[-1])

+

+    def get_global_time_range(self) -> Tuple[np.float32, np.float32]:

+        """

+        Get the global time range across all traces.

+

+        Returns

+        -------

+        Tuple[np.float32, np.float32]

+            Global start and end time across all traces.

+        """

+        if len(self.t_arrays) == 0:

+            return np.float32(0.0), np.float32(0.0)

+

+        t_min = np.float32(

+            min(t_arr[0] if t_arr.size > 0 else np.inf for t_arr in self.t_arrays)

+        )

+        t_max = np.float32(

+            max(t_arr[-1] if t_arr.size > 0 else -np.inf for t_arr in self.t_arrays)

+        )

+

+        if np.isinf(t_min) or np.isinf(t_max):

+            return np.float32(0.0), np.float32(0.0)

+

+        return t_min, t_max

+

+    def get_data_in_range(

+        self, t_start: np.float32, t_end: np.float32, trace_idx: int = 0

+    ) -> Tuple[np.ndarray, np.ndarray]:

+        """

+        Extract data within a time range.

+

+        Parameters

+        ----------

+        t_start : np.float32

+            Start time in raw seconds.

+        t_end : np.float32

+            End time in raw seconds.

+        trace_idx : int, default=0

+            Index of the trace to get data for.

+

+        Returns

+        -------

+        Tuple[np.ndarray, np.ndarray]

+            Time and signal arrays.

+        """

+        if trace_idx < 0 or trace_idx >= len(self.t_arrays):

+            raise ValueError(

+                f"Invalid trace index: {trace_idx}. Must be between 0 and {len(self.t_arrays) - 1}."

+            )

+

+        t_arr = self.t_arrays[trace_idx]

+        x_arr = self.x_arrays[trace_idx]

+

+        mask = (t_arr >= t_start) & (t_arr <= t_end)

+        if not np.any(mask):

+            logger.debug(f"No data in range [{t_start}, {t_end}] for trace {trace_idx}")

+            return (

+                np.array([], dtype=np.float32),

+                np.array([], dtype=np.float32),

+            )

+

+        t_masked = t_arr[mask]

+        x_masked = x_arr[mask]

+

+        return t_masked, x_masked

+

+    def _check_uniform_sampling(self, t: np.ndarray, trace_idx: int = 0) -> None:

+        """

+        Check if time array is uniformly sampled and issue warnings if not.

+

+        Parameters

+        ----------

+        t : np.ndarray

+            Time array to check.

+        trace_idx : int, default=0

+            Index of the trace being checked (for warning messages).

+        """

+        if len(t) < 3:

+            return  # Not enough points to check uniformity

+

+        # Calculate time differences

+        dt = np.diff(t)

+

+        # Calculate statistics

+        dt_mean = np.mean(dt)

+        dt_std = np.std(dt)

+        dt_cv = dt_std / dt_mean if dt_mean > 0 else 0  # Coefficient of variation

+

+        # Check for significant non-uniformity

+        # CV > 0.01 (1%) indicates potentially problematic non-uniformity

+        if dt_cv > 0.01:

+            logger.warning(

+                f"Non-uniform sampling detected in trace {trace_idx}: "

+                f"mean dt={dt_mean:.3e}s, std={dt_std:.3e}s, CV={dt_cv:.2%}"

+            )

+

+            # More detailed warning for severe non-uniformity

+            if dt_cv > 0.05:  # 5% variation

+                # Find the most extreme deviations

+                dt_median = np.median(dt)

+                rel_deviations = np.abs(dt - dt_median) / dt_median

+                worst_indices = np.argsort(rel_deviations)[-5:]  # 5 worst points

+

+                worst_deviations = []

+                for idx in reversed(worst_indices):

+                    if (

+                        rel_deviations[idx] > 0.1

+                    ):  # Only report significant deviations (>10%)

+                        worst_deviations.append(

+                            f"at t={t[idx]:.3e}s: dt={dt[idx]:.3e}s ({rel_deviations[idx]:.1%} deviation)"

+                        )

+

+                if worst_deviations:

+                    logger.warning(

+                        f"Severe sampling irregularities detected in trace {trace_idx}. "

+                        f"Worst points: {'; '.join(worst_deviations)}"

+                    )

+                    logger.warning(

+                        "Non-uniform sampling may affect analysis results, especially for "

+                        "frequency-domain analysis or event detection."

+                    )

diff --git a/src/scopekit/decimation.py b/src/scopekit/decimation.py
new file mode 100644
index 0000000..16543b1
--- /dev/null
+++ b/src/scopekit/decimation.py
@@ -0,0 +1,671 @@
+from typing import Dict, Optional, Tuple

+

+import numpy as np

+from loguru import logger

+from numba import njit

+

+

+@njit

+def _decimate_time_numba(t: np.ndarray, step: int, n_bins: int) -> np.ndarray:

+    """

+    Numba-optimized time decimation using bin centers.

+

+    Parameters

+    ----------

+    t : np.ndarray

+        Input time array.

+    step : int

+        Step size for binning.

+    n_bins : int

+        Number of bins to create.

+

+    Returns

+    -------

+    np.ndarray

+        Decimated time array with center time of each bin.

+    """

+    t_decimated = np.zeros(n_bins, dtype=np.float32)

+

+    for i in range(n_bins):

+        start_idx = i * step

+        end_idx = min((i + 1) * step, len(t))

+        center_idx = start_idx + (end_idx - start_idx) // 2

+        t_decimated[i] = t[center_idx]

+

+    return t_decimated

+

+

+@njit

+def _decimate_mean_numba(x: np.ndarray, step: int, n_bins: int) -> np.ndarray:

+    """

+    Numba-optimized mean decimation.

+

+    Parameters

+    ----------

+    x : np.ndarray

+        Input signal array.

+    step : int

+        Step size for binning.

+    n_bins : int

+        Number of bins to create.

+

+    Returns

+    -------

+    np.ndarray

+        Decimated signal array with mean values.

+    """

+    x_decimated = np.zeros(n_bins, dtype=np.float32)

+

+    for i in range(n_bins):

+        start_idx = i * step

+        end_idx = min((i + 1) * step, len(x))

+

+        if end_idx > start_idx:

+            # Calculate mean manually for Numba compatibility

+            bin_sum = 0.0

+            bin_count = end_idx - start_idx

+            for j in range(start_idx, end_idx):

+                bin_sum += x[j]

+            x_decimated[i] = bin_sum / bin_count

+        else:

+            x_decimated[i] = x[start_idx] if start_idx < len(x) else 0.0

+

+    return x_decimated

+

+

+@njit

+def _decimate_envelope_standard_numba(

+    x: np.ndarray, step: int, n_bins: int

+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:

+    """

+    Numba-optimized standard envelope decimation.

+

+    Parameters

+    ----------

+    x : np.ndarray

+        Input signal array.

+    step : int

+        Step size for binning.

+    n_bins : int

+        Number of bins to create.

+

+    Returns

+    -------

+    Tuple[np.ndarray, np.ndarray, np.ndarray]

+        Decimated signal (mean), min envelope, max envelope arrays.

+    """

+    x_decimated = np.zeros(n_bins, dtype=np.float32)

+    x_min_envelope = np.zeros(n_bins, dtype=np.float32)

+    x_max_envelope = np.zeros(n_bins, dtype=np.float32)

+

+    for i in range(n_bins):

+        start_idx = i * step

+        end_idx = min((i + 1) * step, len(x))

+

+        if end_idx > start_idx:

+            # Find min and max manually for Numba compatibility

+            bin_min = x[start_idx]

+            bin_max = x[start_idx]

+            bin_sum = 0.0

+

+            for j in range(start_idx, end_idx):

+                val = x[j]

+                if val < bin_min:

+                    bin_min = val

+                if val > bin_max:

+                    bin_max = val

+                bin_sum += val

+

+            x_min_envelope[i] = bin_min

+            x_max_envelope[i] = bin_max

+            x_decimated[i] = bin_sum / (end_idx - start_idx)

+        else:

+            fallback_val = x[start_idx] if start_idx < len(x) else 0.0

+            x_min_envelope[i] = fallback_val

+            x_max_envelope[i] = fallback_val

+            x_decimated[i] = fallback_val

+

+    return x_decimated, x_min_envelope, x_max_envelope

+

+

+@njit

+def _decimate_envelope_highres_numba(

+    t: np.ndarray, x: np.ndarray, step: int, n_bins: int, envelope_window_samples: int

+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:

+    """

+    Numba-optimized high-resolution envelope decimation.

+

+    Parameters

+    ----------

+    t : np.ndarray

+        Input time array.

+    x : np.ndarray

+        Input signal array.

+    step : int

+        Step size for binning.

+    n_bins : int

+        Number of bins to create.

+    envelope_window_samples : int

+        Window size in samples for high-resolution envelope calculation.

+

+    Returns

+    -------

+    Tuple[np.ndarray, np.ndarray, np.ndarray]

+        Decimated signal (mean), min envelope, max envelope arrays.

+    """

+    x_decimated = np.zeros(n_bins, dtype=np.float32)

+    x_min_envelope = np.zeros(n_bins, dtype=np.float32)

+    x_max_envelope = np.zeros(n_bins, dtype=np.float32)

+

+    half_window = envelope_window_samples // 2

+

+    for i in range(n_bins):

+        start_idx = i * step

+        end_idx = min((i + 1) * step, len(t))

+        bin_center = start_idx + (end_idx - start_idx) // 2

+

+        # Define window around bin center

+        window_start = max(0, bin_center - half_window)

+        window_end = min(len(x), bin_center + half_window)

+

+        if window_end > window_start:

+            # Find min and max in window manually for Numba compatibility

+            window_min = x[window_start]

+            window_max = x[window_start]

+

+            for j in range(window_start, window_end):

+                val = x[j]

+                if val < window_min:

+                    window_min = val

+                if val > window_max:

+                    window_max = val

+

+            x_min_envelope[i] = window_min

+            x_max_envelope[i] = window_max

+            x_decimated[i] = (window_min + window_max) / 2.0

+        else:

+            fallback_val = x[bin_center] if bin_center < len(x) else 0.0

+            x_min_envelope[i] = fallback_val

+            x_max_envelope[i] = fallback_val

+            x_decimated[i] = fallback_val

+

+    return x_decimated, x_min_envelope, x_max_envelope

+

+

+class DecimationManager:

+    """

+    Handles data decimation and caching for efficient plotting.

+

+    Manages different decimation strategies and caches results to improve performance.

+    Pre-calculates decimated data at load time for faster zooming.

+    """

+

+    # Cache and performance constants

+    CACHE_MAX_SIZE = 10

+    MIN_VISIBLE_RANGE_DEFAULT = 1e-6  # Default if no global noise is provided

+    # Threshold for warning about too many points in detail mode

+    DETAIL_MODE_POINT_WARNING_THRESHOLD = 100000

+

+    def __init__(self, cache_max_size: int = CACHE_MAX_SIZE):

+        """

+        Initialise the decimation manager.

+

+        Parameters

+        ----------

+        cache_max_size : int, default=PlotConstants.CACHE_MAX_SIZE

+            Maximum number of cached decimation results.

+        """

+        self._cache: Dict[str, Tuple[np.ndarray, ...]] = {}

+        self._cache_max_size = cache_max_size

+        # Stores pre-decimated envelope data for the full dataset for each trace/line

+        # Structure: {trace_id: {'t': np.ndarray, 'x_min': np.ndarray, 'x_max': np.ndarray, ...}}

+        self._pre_decimated_envelopes: Dict[int, Dict[str, np.ndarray]] = {}

+

+    def _get_cache_key(

+        self,

+        xlim_raw: Tuple[np.float32, np.float32],

+        max_points: int,

+        use_envelope: bool,

+        trace_id: Optional[int] = None,

+    ) -> str:

+        """Generate cache key for decimated data."""

+        # Round to reasonable precision to improve cache hits

+        xlim_rounded = (round(float(xlim_raw[0]), 9), round(float(xlim_raw[1]), 9))

+

+        # Include trace_id in cache key for multi-trace support

+        trace_suffix = f"_t{trace_id}" if trace_id is not None else ""

+

+        return f"{xlim_rounded}_{max_points}_{use_envelope}{trace_suffix}"

+

+    def _manage_cache_size(self) -> None:

+        """Remove oldest cache entry if cache is full."""

+        if len(self._cache) >= self._cache_max_size:

+            # Remove oldest entry (simple FIFO)

+            oldest_key = next(iter(self._cache))

+            del self._cache[oldest_key]

+

+    def clear_cache(self) -> None:

+        """Clear the decimation cache."""

+        self._cache.clear()

+        # Do NOT clear _pre_decimated_envelopes here, as they are persistent for the full dataset

+

+    def _decimate_data(

+        self,

+        t: np.ndarray,

+        x: np.ndarray,

+        max_points: int,

+        use_envelope: bool = False,

+        envelope_window_samples: Optional[int] = None,

+        return_envelope_min_max: bool = False,  # New parameter

+    ) -> Tuple[np.ndarray, np.ndarray, Optional[np.ndarray], Optional[np.ndarray]]:

+        """

+        Unified decimation for time and multiple data arrays.

+

+        Parameters

+        ----------

+        t : np.ndarray

+            Time array.

+        x : np.ndarray

+            Signal array.

+        max_points : int, default=5000

+            Maximum number of points to display.

+        use_envelope : bool, default=False

+            Whether to use envelope decimation for the signal array.

+        envelope_window_samples : Optional[int], default=None

+            Window size in samples for high-resolution envelope calculation.

+        return_envelope_min_max : bool, default=False

+            If True, returns x_min_envelope and x_max_envelope. Otherwise, returns None for them.

+            If None, uses simple binning approach.

+

+        Returns

+        -------

+        Tuple[np.ndarray, np.ndarray, Optional[np.ndarray], Optional[np.ndarray]]

+            Decimated time, signal, signal min envelope, signal max envelope arrays.

+        """

+        # If input arrays are empty, return empty arrays immediately

+        if len(t) == 0:

+            return (

+                np.array([], dtype=np.float32),

+                np.array([], dtype=np.float32),

+                None,

+                None,

+            )

+

+        # If not using envelope, always return raw data for the view

+        if (

+            not use_envelope and not return_envelope_min_max

+        ):  # If not using envelope and not explicitly asking for min/max

+            return t, x, None, None  # No min/max envelope for raw data

+

+        # If using envelope and data is small enough, return raw data as envelope

+        if use_envelope and len(t) <= max_points and return_envelope_min_max:

+            return t, x, x, x  # x,x for min/max when no decimation

+

+        # Calculate step size for decimation based on max_points

+        step = max(1, len(t) // max_points)

+

+        # For envelope mode, calculate adaptive envelope window based on data density

+        adaptive_envelope_window = None

+        if use_envelope and len(t) > max_points:

+            # Calculate envelope window based on how much we're decimating

+            # This ensures envelope resolution matches display capability

+            adaptive_envelope_window = max(

+                1, step // 2

+            )  # Half the step size for smoother envelope

+            logger.debug(

+                f"Calculated adaptive envelope window: {adaptive_envelope_window} samples (step={step})"

+            )

+

+        # Ensure step is not zero, and calculate number of bins

+        if step == 0:  # Should not happen with max(1, ...) but as a safeguard

+            step = 1

+        n_bins = len(t) // step

+        if (

+            n_bins == 0

+        ):  # If data is too short for the calculated step, take at least one bin

+            n_bins = 1

+            step = len(t)  # Take all points in one bin

+

+        # Ensure arrays are contiguous and correct dtype for Numba

+        t_contiguous = np.ascontiguousarray(t, dtype=np.float32)

+        x_contiguous = np.ascontiguousarray(x, dtype=np.float32)

+

+        # Decimate time array using Numba-optimized function

+        t_decimated = _decimate_time_numba(t_contiguous, step, n_bins)

+

+        # Decimate signal (x) using appropriate Numba-optimized function

+        x_min_envelope: Optional[np.ndarray] = None

+        x_max_envelope: Optional[np.ndarray] = None

+

+        if use_envelope:  # This block handles the decimation logic (mean or envelope)

+            if adaptive_envelope_window is not None and adaptive_envelope_window > 1:

+                logger.debug(

+                    f"Using adaptive high-resolution envelope with window size {adaptive_envelope_window} samples"

+                )

+

+                # Use Numba-optimized high-resolution envelope decimation with adaptive window

+                x_decimated, x_min_envelope, x_max_envelope = (

+                    _decimate_envelope_highres_numba(

+                        t_contiguous,

+                        x_contiguous,

+                        step,

+                        n_bins,

+                        adaptive_envelope_window,

+                    )

+                )

+

+                envelope_thickness = np.mean(x_max_envelope - x_min_envelope)

+                logger.debug(

+                    f"Adaptive envelope thickness: mean={envelope_thickness:.3g}, min={np.min(x_max_envelope - x_min_envelope):.3g}, max={np.max(x_max_envelope - x_min_envelope):.3g}"

+                )

+            else:

+                logger.debug("Using standard bin-based envelope")

+

+                # Use Numba-optimized standard envelope decimation

+                x_decimated, x_min_envelope, x_max_envelope = (

+                    _decimate_envelope_standard_numba(x_contiguous, step, n_bins)

+                )

+

+                # If we are not returning min/max, then x_decimated should be the mean

+                # Otherwise, x_decimated is just the mean of the envelope for internal use

+                if not return_envelope_min_max:

+                    x_decimated = (x_min_envelope + x_max_envelope) / 2

+        else:  # This block is now reached if use_envelope is False AND len(t) > max_points

+            logger.debug("Using mean decimation for single line")

+

+            # Use Numba-optimized mean decimation

+            x_decimated = _decimate_mean_numba(x_contiguous, step, n_bins)

+

+        # If return_envelope_min_max is False, ensure min/max are None

+        if not return_envelope_min_max:

+            x_min_envelope = None

+            x_max_envelope = None

+

+        return t_decimated, x_decimated, x_min_envelope, x_max_envelope

+

+    def pre_decimate_data(

+        self,

+        data_id: int,  # Changed from trace_id to data_id to be more generic for custom lines

+        t: np.ndarray,

+        x: np.ndarray,

+        max_points: int,

+        envelope_window_samples: Optional[int] = None,  # This parameter is now ignored

+    ) -> None:

+        """

+        Pre-calculate decimated envelope data for the full dataset.

+        This is used for fast rendering in zoomed-out (envelope) mode.

+

+        Parameters

+        ----------

+        data_id : int

+            Unique identifier for this data set (e.g., trace_id or custom line ID).

+        t : np.ndarray

+            Time array (raw time in seconds).

+        x : np.ndarray

+            Signal array.

+        max_points : int

+            Maximum number of points for the pre-decimated data.

+        envelope_window_samples : Optional[int], default=None

+            Window size in samples for high-resolution envelope calculation.

+            This will primarily determine the bin size for pre-decimation.

+        """

+        if len(t) <= max_points:

+            # For small datasets, just store the original data as the "pre-decimated" envelope

+            # (min/max will be the same as x)

+            self._pre_decimated_envelopes[data_id] = {

+                "t": t,

+                "x": x,  # Store mean/center for consistency

+                "x_min": x,

+                "x_max": x,

+            }

+            logger.debug(

+                f"Data ID {data_id} is small enough, storing raw as pre-decimated envelope."

+            )

+            return

+

+        logger.debug(

+            f"Pre-decimating data for ID {data_id} to {max_points} points for envelope view."

+        )

+        # Perform the decimation using the _decimate_data method

+        # We force use_envelope=True here for pre-decimation to capture min/max

+        # envelope_window_samples is now calculated automatically based on max_points

+        t_decimated, x_decimated, x_min, x_max = self._decimate_data(

+            t,

+            x,

+            max_points=max_points,

+            use_envelope=True,  # Always pre-decimate with envelope

+            envelope_window_samples=None,  # Let _decimate_data calculate adaptive window

+            return_envelope_min_max=True,  # Pre-decimation always stores min/max

+        )

+

+        # Store pre-decimated envelope data

+        self._pre_decimated_envelopes[data_id] = {

+            "t": t_decimated,

+            "x": x_decimated,  # This is the mean/center of the envelope

+            "x_min": x_min,

+            "x_max": x_max,

+        }

+

+        logger.debug(

+            f"Pre-decimated envelope calculated for ID {data_id}: {len(t_decimated)} points."

+        )

+

+    def decimate_for_view(

+        self,

+        t_raw_full: np.ndarray,  # Full resolution time array

+        x_raw_full: np.ndarray,  # Full resolution signal array

+        xlim_raw: Tuple[np.float32, np.float32],

+        max_points: int,

+        use_envelope: bool = False,

+        data_id: Optional[int] = None,  # Changed from trace_id to data_id

+        envelope_window_samples: Optional[int] = None,  # This parameter is now ignored

+        mode_switch_threshold: Optional[

+            float

+        ] = None,  # New parameter for mode switching

+        return_envelope_min_max: bool = False,  # New parameter

+    ) -> Tuple[

+        np.ndarray,

+        np.ndarray,

+        Optional[np.ndarray],

+        Optional[np.ndarray],

+    ]:

+        """

+        Intelligently decimate data for current view with optional envelope mode.

+

+        Parameters

+        ----------

+        t_raw_full : np.ndarray

+            Full resolution time array (raw time in seconds).

+        x_raw_full : np.ndarray

+            Full resolution signal array.

+        xlim_raw : Tuple[np.float32, np.float32]

+            Current x-axis limits in raw time (seconds).

+        max_points : int

+            Maximum number of points to display.

+        use_envelope : bool, default=False

+            Whether the current display mode is envelope.

+        data_id : Optional[int], default=None

+            Unique identifier for this data set (e.g., trace_id or custom line ID).

+            Used to retrieve pre-decimated envelope data.

+        envelope_window_samples : Optional[int], default=None

+            Window size in samples for high-resolution envelope calculation.

+        return_envelope_min_max : bool, default=False

+            If True, returns x_min_envelope and x_max_envelope. Otherwise, returns None for them.

+        mode_switch_threshold : Optional[float], default=None

+            Time span threshold for switching between envelope and detail modes.

+            Used to decide whether to use pre-decimated envelope data.

+

+        Returns

+        -------

+        Tuple[np.ndarray, np.ndarray, Optional[np.ndarray], Optional[np.ndarray]]

+            Decimated time, signal, signal min envelope, signal max envelope arrays (all in raw time).

+        """

+        logger.debug(f"=== DecimationManager.decimate_for_view data_id={data_id} ===")

+        logger.debug(f"xlim_raw: {xlim_raw}")

+        logger.debug(f"use_envelope (requested): {use_envelope}")

+        logger.debug(f"max_points: {max_points}")

+        logger.debug(

+            f"Input data range: t=[{np.min(t_raw_full):.6f}, {np.max(t_raw_full):.6f}], x=[{np.min(x_raw_full):.6f}, {np.max(x_raw_full):.6f}]"

+        )

+

+        # Ensure xlim_raw values are valid

+        if (

+            not np.isfinite(xlim_raw[0])

+            or not np.isfinite(xlim_raw[1])

+            or xlim_raw[0] == xlim_raw[1]

+        ):

+            logger.warning(

+                f"Invalid xlim_raw values: {xlim_raw}. Using full data range."

+            )

+            xlim_raw = (np.min(t_raw_full), np.max(t_raw_full))

+

+        # Ensure xlim_raw is in ascending order

+        if xlim_raw[0] > xlim_raw[1]:

+            logger.warning(f"xlim_raw values out of order: {xlim_raw}. Swapping.")

+            xlim_raw = (xlim_raw[1], xlim_raw[0])

+

+        # Calculate current view span

+        current_view_span = xlim_raw[1] - xlim_raw[0]

+

+        # Check cache first

+        cache_key = self._get_cache_key(

+            xlim_raw, max_points, use_envelope, data_id

+        )  # Cache key doesn't need return_envelope_min_max

+        if cache_key in self._cache:

+            logger.debug(f"Using cached decimation for key: {cache_key}")

+            return self._cache[cache_key]

+

+        # --- Strategy: Use pre-decimated envelope if in envelope mode and view is wide ---

+        if (

+            use_envelope

+            and data_id is not None

+            and data_id in self._pre_decimated_envelopes

+        ):

+            pre_dec_data = self._pre_decimated_envelopes[data_id]

+            pre_dec_t = pre_dec_data["t"]

+

+            if len(pre_dec_t) > 1:

+                pre_dec_span = pre_dec_t[-1] - pre_dec_t[0]

+

+                # Calculate how much detail we would gain by re-decimating

+                # Find indices for current view in pre-decimated time

+                mask = (pre_dec_t >= xlim_raw[0]) & (pre_dec_t <= xlim_raw[1])

+                pre_dec_points_in_view = np.sum(mask)

+

+                # Estimate how many points we would get from dynamic decimation

+                t_view_mask = (t_raw_full >= xlim_raw[0]) & (t_raw_full <= xlim_raw[1])

+                raw_points_in_view = np.sum(t_view_mask)

+                potential_decimated_points = min(raw_points_in_view, max_points)

+

+                # Use pre-decimated data only if:

+                # 1. Current view span is very large (> 2x mode_switch_threshold), AND

+                # 2. Pre-decimated data provides reasonable detail (> max_points/4), AND

+                # 3. We wouldn't gain much detail from re-decimating (< 2x improvement)

+                use_pre_decimated = (

+                    mode_switch_threshold is not None

+                    and current_view_span >= 2 * mode_switch_threshold

+                    and pre_dec_points_in_view > max_points // 4

+                    and potential_decimated_points < 2 * pre_dec_points_in_view

+                )

+

+                if use_pre_decimated and np.any(mask):

+                    logger.debug(

+                        f"Using pre-decimated data for ID {data_id} (envelope mode, very wide view, {pre_dec_points_in_view} points, return_envelope_min_max={return_envelope_min_max})."

+                    )

+

+                    # If we need min/max, return them. Otherwise, return None.

+                    x_min_ret = (

+                        pre_dec_data["x_min"][mask] if return_envelope_min_max else None

+                    )

+                    x_max_ret = (

+                        pre_dec_data["x_max"][mask] if return_envelope_min_max else None

+                    )

+

+                    result = (

+                        pre_dec_t[mask],

+                        pre_dec_data["x"][mask],  # Center of envelope

+                        x_min_ret,

+                        x_max_ret,

+                    )

+                    self._manage_cache_size()

+                    self._cache[cache_key] = result

+                    return result

+                else:

+                    logger.debug(

+                        f"Re-decimating for better detail: view_span={current_view_span:.3e}, pre_dec_points={pre_dec_points_in_view}, potential_points={potential_decimated_points}"

+                    )

+            else:

+                logger.debug(

+                    f"Pre-decimated data for ID {data_id} has only one point, falling back to dynamic decimation."

+                )

+        else:

+            logger.debug(

+                f"Not using pre-decimated envelope for ID {data_id} (use_envelope={use_envelope}, data_id={data_id in self._pre_decimated_envelopes})."

+            )

+

+        # --- Fallback: Dynamic decimation from raw data ---

+        logger.debug("Performing dynamic decimation from raw data.")

+

+        # ADDED DEBUG LOGS

+        logger.debug(

+            f"  t_raw_full min/max: {t_raw_full.min():.6f}, {t_raw_full.max():.6f}"

+        )

+        logger.debug(f"  xlim_raw: {xlim_raw[0]:.6f}, {xlim_raw[1]:.6f}")

+

+        # Find indices for current view in raw time

+        mask = (t_raw_full >= xlim_raw[0]) & (t_raw_full <= xlim_raw[1])

+

+        # ADDED DEBUG LOG

+        logger.debug(f"  Mask result: {np.sum(mask)} points selected.")

+

+        if not np.any(mask):

+            logger.warning(

+                f"No data in view for xlim_raw: {xlim_raw}. Returning empty arrays."

+            )

+            empty_result = (

+                np.array([], dtype=np.float32),

+                np.array([], dtype=np.float32),

+                None,

+                None,

+            )

+            # Cache empty result for this view

+            self._manage_cache_size()

+            self._cache[cache_key] = empty_result

+            return empty_result

+

+        t_view = t_raw_full[mask]

+        x_view = x_raw_full[mask]

+

+        # Add warning for large number of points in detail mode

+        if not use_envelope and len(t_view) > self.DETAIL_MODE_POINT_WARNING_THRESHOLD:

+            logger.warning(

+                f"Plotting {len(t_view)} points in detail mode. "

+                f"Performance may be affected. Consider zooming in further."

+            )

+

+        # Use unified decimation approach

+        # envelope_window_samples is now calculated automatically based on max_points and data density

+        result = self._decimate_data(

+            t_view,

+            x_view,

+            max_points=max_points,

+            use_envelope=use_envelope,  # Use requested envelope mode for dynamic decimation

+            envelope_window_samples=None,  # Let _decimate_data calculate adaptive window

+            return_envelope_min_max=return_envelope_min_max,  # Pass through

+        )

+

+        # Cache the result (manage cache size)

+        self._manage_cache_size()

+        self._cache[cache_key] = result

+

+        # Log the final result

+        t_result, x_result, x_min_result, x_max_result = result

+        logger.debug(f"Returning result: t len={len(t_result)}, x len={len(x_result)}")

+        logger.debug(

+            f"Result ranges: t=[{np.min(t_result) if len(t_result) > 0 else 'empty':.6f}, {np.max(t_result) if len(t_result) > 0 else 'empty':.6f}], x=[{np.min(x_result) if len(x_result) > 0 else 'empty':.6f}, {np.max(x_result) if len(x_result) > 0 else 'empty':.6f}]"

+        )

+        logger.debug(

+            f"Envelope: x_min={'None' if x_min_result is None else f'len={len(x_min_result)}'}, x_max={'None' if x_max_result is None else f'len={len(x_max_result)}'}"

+        )

+

+        return result

diff --git a/src/scopekit/display_state.py b/src/scopekit/display_state.py
new file mode 100644
index 0000000..b66b556
--- /dev/null
+++ b/src/scopekit/display_state.py
@@ -0,0 +1,294 @@
+from typing import Optional, Tuple

+

+import numpy as np

+from loguru import logger

+from matplotlib.ticker import FuncFormatter

+

+# Time unit boundaries (hysteresis)

+PICOSECOND_BOUNDARY = 0.8e-9

+NANOSECOND_BOUNDARY = 0.8e-6

+MICROSECOND_BOUNDARY = 0.8e-3

+MILLISECOND_BOUNDARY = 0.8

+

+# Offset thresholds

+OFFSET_SPAN_MULTIPLIER = 10

+OFFSET_TIME_THRESHOLD = 1e-3  # 1ms

+

+

+def _get_optimal_time_unit_and_scale(

+    time_array_or_span: np.ndarray | float,

+) -> Tuple[str, np.float32]:

+    """

+    Determines the optimal time unit and scaling factor for a given time array or span.

+

+    Uses hysteresis boundaries to prevent oscillation near unit boundaries.

+

+    Parameters

+    ----------

+    time_array_or_span : np.ndarray | float

+        A NumPy array representing time in seconds, or a single float representing a time span in seconds.

+

+    Returns

+    -------

+    Tuple[str, np.float32]

+        A tuple containing the time unit string (e.g., "s", "ms", "us", "ns")

+        and the corresponding scaling factor (e.0, 1e3, 1e6, 1e9).

+    """

+    if isinstance(time_array_or_span, np.ndarray):

+        # Handle empty array case to prevent errors

+        if time_array_or_span.size == 0:

+            return "s", np.float32(1.0)  # Default to seconds if no data

+        max_val = np.max(time_array_or_span)

+    else:  # Assume it's a float representing a span

+        max_val = time_array_or_span

+

+    # Use hysteresis boundaries to prevent oscillation near unit boundaries

+    if max_val < PICOSECOND_BOUNDARY:

+        return "ps", np.float32(1e12)

+    elif max_val < NANOSECOND_BOUNDARY:

+        return "ns", np.float32(1e9)

+    elif max_val < MICROSECOND_BOUNDARY:

+        return "us", np.float32(1e6)

+    elif max_val < MILLISECOND_BOUNDARY:

+        return "ms", np.float32(1e3)

+    else:

+        return "s", np.float32(1.0)

+

+

+def _determine_offset_display_params(

+    xlim_raw: Tuple[np.float32, np.float32], time_span_raw: np.float32

+) -> Tuple[str, np.float32, Optional[np.float32], Optional[str]]:

+    """

+    Determine display parameters including offset for optimal readability.

+

+    Parameters

+    ----------

+    xlim_raw : Tuple[np.float32, np.float32]

+        Current x-axis limits in raw time (seconds).

+    time_span_raw : np.float32

+        Time span of current view in seconds.

+

+    Returns

+    -------

+    Tuple[str, np.float32, Optional[np.float32], Optional[str]]

+        Display unit, display scale, offset time (raw seconds), offset unit string.

+        If no offset is needed, offset_time and offset_unit will be None.

+    """

+    # Get optimal unit for the time span

+    display_unit, display_scale = _get_optimal_time_unit_and_scale(time_span_raw)

+

+    # Determine if we need an offset

+    # Use offset if the start time is significantly larger than the span

+    xlim_start = xlim_raw[0]

+

+    # Use offset if start time is more than threshold multiplier of the span, and span is small

+    use_offset = (abs(xlim_start) > OFFSET_SPAN_MULTIPLIER * time_span_raw) and (

+        time_span_raw < np.float32(OFFSET_TIME_THRESHOLD)

+    )

+

+    if use_offset:

+        # Choose appropriate unit for the offset

+        if abs(xlim_start) >= np.float32(1.0):  # >= 1 second

+            offset_unit = "s"

+            offset_scale = np.float32(1.0)

+        elif abs(xlim_start) >= np.float32(1e-3):  # >= 1 millisecond

+            offset_unit = "ms"

+            offset_scale = np.float32(1e3)

+        elif abs(xlim_start) >= np.float32(1e-6):  # >= 1 microsecond

+            offset_unit = "us"

+            offset_scale = np.float32(1e6)

+        else:

+            offset_unit = "ns"

+            offset_scale = np.float32(1e9)

+

+        return display_unit, display_scale, xlim_start, offset_unit

+    else:

+        return display_unit, display_scale, None, None

+

+

+def _create_time_formatter(

+    offset_time_raw: Optional[np.float32], display_scale: np.float32

+) -> FuncFormatter:

+    """

+    Create a FuncFormatter for time axis tick labels.

+

+    Parameters

+    ----------

+    offset_time_raw : Optional[np.float32]

+        Offset time in raw seconds. If None, no offset is applied.

+    display_scale : np.float32

+        Scale factor for display units.

+

+    Returns

+    -------

+    FuncFormatter

+        Matplotlib formatter for tick labels.

+    """

+

+    def formatter(x, pos):

+        # x is already in display units (relative to offset if applicable)

+        # Format with appropriate precision based on scale

+        if display_scale >= np.float32(1e9):  # nanoseconds or smaller

+            return f"{x:.0f}"

+        elif display_scale >= np.float32(1e6):  # microseconds

+            return f"{x:.0f}"

+        elif display_scale >= np.float32(1e3):  # milliseconds

+            return f"{x:.1f}"

+        else:  # seconds

+            return f"{x:.3f}"

+

+    return FuncFormatter(formatter)

+

+

+class DisplayState:

+    """

+    Manages display state and mode switching logic.

+

+    Centralises state management to reduce complexity and flag interactions.

+    """

+

+    def __init__(

+        self,

+        original_time_unit: str,

+        original_time_scale: np.float32,

+        envelope_limit: np.float32,

+    ):

+        """

+        Initialise display state.

+

+        Parameters

+        ----------

+        original_time_unit : str

+            Original time unit string.

+        original_time_scale : np.float32

+            Original time scaling factor.

+        envelope_limit : np.float32

+            Time span threshold for envelope mode.

+        """

+        # Time scaling

+        self.original_time_unit = original_time_unit

+        self.original_time_scale = original_time_scale

+        self.current_time_unit = original_time_unit

+        self.current_time_scale = original_time_scale

+

+        # Display mode

+        self.current_mode: Optional[str] = None

+        self.envelope_limit = envelope_limit

+

+        # Offset parameters

+        self.offset_time_raw: Optional[np.float32] = None

+        self.offset_unit: Optional[str] = None

+

+        # Single state flag - simplified

+        self._updating = False

+

+    def get_time_unit_and_scale(self, t: np.ndarray) -> Tuple[str, np.float32]:

+        """

+        Automatically select appropriate time unit and scale for plotting.

+

+        Parameters

+        ----------

+        t : np.ndarray

+            Time array.

+

+        Returns

+        -------

+        Tuple[str, np.float32]

+            Time unit string and scaling factor.

+        """

+        # Delegate to the new utility function

+        return _get_optimal_time_unit_and_scale(t)

+

+    def update_display_params(

+        self, xlim_raw: Tuple[np.float32, np.float32], time_span_raw: np.float32

+    ) -> bool:

+        """

+        Update display parameters including offset based on current view.

+

+        Parameters

+        ----------

+        xlim_raw : Tuple[np.float32, np.float32]

+            Current x-axis limits in raw time (seconds).

+        time_span_raw : np.float32

+            Time span of current view in seconds.

+

+        Returns

+        -------

+        bool

+            True if display parameters changed, False otherwise.

+        """

+        display_unit, display_scale, offset_time, offset_unit = (

+            _determine_offset_display_params(xlim_raw, time_span_raw)

+        )

+

+        # Check if anything changed

+        params_changed = (

+            display_unit != self.current_time_unit

+            or display_scale != self.current_time_scale

+            or offset_time != self.offset_time_raw

+            or offset_unit != self.offset_unit

+        )

+

+        if params_changed:

+            logger.info(

+                f"Display params changed: unit={display_unit}, scale={display_scale:.1e}, offset={offset_time}, offset_unit={offset_unit}"

+            )

+            self.current_time_unit = display_unit

+            self.current_time_scale = display_scale

+            self.offset_time_raw = offset_time

+            self.offset_unit = offset_unit

+            return True

+

+        return False

+

+    def should_use_envelope(self, time_span_raw: np.float32) -> bool:

+        """Determine if envelope mode should be used based on time span."""

+        return time_span_raw > self.envelope_limit

+

+    def should_show_thresholds(self, time_span_raw: np.float32) -> bool:

+        """Determine if threshold lines should be shown based on time span."""

+        return time_span_raw < self.envelope_limit

+

+    def update_time_scale(self, time_span_raw: np.float32) -> bool:

+        """

+        Update time scale based on current view span.

+

+        Returns True if scale changed, False otherwise.

+        """

+        # Delegate to the new utility function for span

+        new_unit, new_scale = _get_optimal_time_unit_and_scale(time_span_raw)

+

+        if new_scale != self.current_time_scale:

+            logger.info(

+                f"Time scale changed from {self.current_time_unit} ({self.current_time_scale:.1e}) to {new_unit} ({new_scale:.1e})"

+            )

+            self.current_time_unit = new_unit

+            self.current_time_scale = new_scale

+            return True

+

+        return False

+

+    def reset_to_original_scale(self) -> None:

+        """Reset time scale to original values."""

+        self.current_time_unit = self.original_time_unit

+        self.current_time_scale = self.original_time_scale

+        logger.info(

+            f"Reset to original scale: {self.current_time_unit} ({self.current_time_scale:.1e})"

+        )

+

+    def reset_to_initial_state(self) -> None:

+        """Reset all display parameters to initial values."""

+        self.current_time_unit = self.original_time_unit

+        self.current_time_scale = self.original_time_scale

+        self.offset_time_raw = None

+        self.offset_unit = None

+        self.current_mode = None

+        self._updating = False

+

+    def set_updating(self, value: bool = True) -> None:

+        """Set updating state to prevent recursion."""

+        self._updating = value

+

+    def is_updating(self) -> bool:

+        """Check if currently updating."""

+        return self._updating

diff --git a/src/scopekit/plot.py b/src/scopekit/plot.py
new file mode 100644
index 0000000..83c10bc
--- /dev/null
+++ b/src/scopekit/plot.py
@@ -0,0 +1,1829 @@
+from typing import Any, Dict, List, Optional, Tuple, Union

+

+import matplotlib as mpl

+import matplotlib.pyplot as plt

+import numpy as np

+from loguru import logger

+from matplotlib.ticker import MultipleLocator

+

+from .coordinate_manager import CoordinateManager

+from .data_manager import TimeSeriesDataManager

+from .decimation import DecimationManager

+from .display_state import (

+    DisplayState,

+    _create_time_formatter,

+    _get_optimal_time_unit_and_scale,

+)

+

+

+class OscilloscopePlot:

+    """

+    General-purpose plotting class for time-series data with zoom and decimation.

+

+    Uses separate managers for data, decimation, and state to reduce complexity.

+    Supports different visualization elements (lines, envelopes, ribbons, regions)

+    that can be displayed in different modes (envelope when zoomed out, detail when zoomed in).

+    """

+

+    # Mode constants

+    MODE_ENVELOPE = 1  # Zoomed out mode

+    MODE_DETAIL = 2  # Zoomed in mode

+    MODE_BOTH = 3  # Both modes

+

+    # Default styling constants

+    DEFAULT_MAX_PLOT_POINTS = 10000

+    DEFAULT_MODE_SWITCH_THRESHOLD = 10e-3  # 10 ms

+    DEFAULT_MIN_Y_RANGE_DEFAULT = 1e-9  # Default minimum Y-axis range (e.g., 1 nV)

+    DEFAULT_Y_MARGIN_FRACTION = 0.15

+    DEFAULT_SIGNAL_LINE_WIDTH = 1.0

+    DEFAULT_SIGNAL_ALPHA = 0.75

+    DEFAULT_ENVELOPE_ALPHA = 0.75

+    DEFAULT_REGION_ALPHA = 0.4

+    DEFAULT_REGION_ZORDER = -5

+

+    def __init__(

+        self,

+        t: Union[np.ndarray, List[np.ndarray]],

+        x: Union[np.ndarray, List[np.ndarray]],

+        name: Union[str, List[str]] = "Waveform",

+        trace_colors: Optional[List[str]] = None,

+        # Core display parameters

+        max_plot_points: int = DEFAULT_MAX_PLOT_POINTS,

+        mode_switch_threshold: float = DEFAULT_MODE_SWITCH_THRESHOLD,

+        min_y_range: Optional[float] = None,  # New parameter for minimum Y-axis range

+        y_margin_fraction: float = DEFAULT_Y_MARGIN_FRACTION,

+        signal_line_width: float = DEFAULT_SIGNAL_LINE_WIDTH,

+        signal_alpha: float = DEFAULT_SIGNAL_ALPHA,

+        envelope_alpha: float = DEFAULT_ENVELOPE_ALPHA,

+        region_alpha: float = DEFAULT_REGION_ALPHA,

+        region_zorder: int = DEFAULT_REGION_ZORDER,

+        envelope_window_samples: Optional[int] = None,

+    ):

+        """

+        Initialize the OscilloscopePlot with time series data.

+

+        Parameters

+        ----------

+        t : Union[np.ndarray, List[np.ndarray]]

+            Time array(s) (raw time in seconds). Can be a single array shared by all traces

+            or a list of arrays, one per trace.

+        x : Union[np.ndarray, List[np.ndarray]]

+            Signal array(s). If t is a single array, x can be a 2D array (traces x samples)

+            or a list of 1D arrays. If t is a list, x must be a list of equal length.

+        name : Union[str, List[str]], default="Waveform"

+            Name(s) for plot title. Can be a single string or a list of strings.

+        trace_colors : Optional[List[str]], default=None

+            Colors for each trace. If None, default colors will be used.

+        max_plot_points : int, default=10000

+            Maximum number of points to display on the plot. Data will be decimated if it exceeds this.

+        mode_switch_threshold : float, default=10e-3

+            Time span (in seconds) above which the plot switches to envelope mode.

+        min_y_range : Optional[float], default=None

+            Minimum Y-axis range to enforce. If None, a default small value is used.

+        y_margin_fraction : float, default=0.05

+            Fraction of data range to add as margin to Y-axis limits.

+        signal_line_width : float, default=1.0

+            Line width for the raw signal plot.

+        signal_alpha : float, default=0.75

+            Alpha (transparency) for the raw signal plot.

+        envelope_alpha : float, default=1.0

+            Alpha (transparency) for the envelope fill.

+        region_alpha : float, default=0.4

+            Alpha (transparency) for region highlight fills.

+        region_zorder : int, default=-5

+            Z-order for region highlight fills (lower means further back).

+        envelope_window_samples : Optional[int], default=None

+            DEPRECATED: Window size in samples for envelope calculation.

+            Envelope window is now calculated automatically based on max_plot_points and zoom level.

+            This parameter is ignored but kept for backward compatibility.

+        """

+        # Store styling parameters directly as instance attributes

+        self.max_plot_points = max_plot_points

+        self.mode_switch_threshold = np.float32(mode_switch_threshold)

+        self.min_y_range = (

+            np.float32(min_y_range)

+            if min_y_range is not None

+            else self.DEFAULT_MIN_Y_RANGE_DEFAULT

+        )

+        self.y_margin_fraction = np.float32(y_margin_fraction)

+        self.signal_line_width = signal_line_width

+        self.signal_alpha = signal_alpha

+        self.envelope_alpha = envelope_alpha

+        self.region_alpha = region_alpha

+        self.region_zorder = region_zorder

+        # envelope_window_samples is now deprecated - envelope window is calculated automatically

+        # Keep the parameter for backward compatibility but don't use it

+        if envelope_window_samples is not None:

+            logger.warning(

+                "envelope_window_samples parameter is deprecated. Envelope window is now calculated automatically based on zoom level."

+            )

+

+        # Initialize managers

+        self.data = TimeSeriesDataManager(t, x, name, trace_colors)

+        self.decimator = DecimationManager()

+

+        # Pre-decimate main signal data for envelope view

+        for i in range(self.data.num_traces):

+            self.decimator.pre_decimate_data(

+                data_id=i,  # Use trace_idx as data_id

+                t=self.data.t_arrays[i],

+                x=self.data.x_arrays[i],

+                max_points=self.max_plot_points,

+                envelope_window_samples=None,  # Envelope window calculated automatically

+            )

+

+        # Initialize display state using the first trace's time array

+        initial_time_unit, initial_time_scale = _get_optimal_time_unit_and_scale(

+            self.data.t_arrays[0]

+        )

+        self.state = DisplayState(

+            initial_time_unit, initial_time_scale, self.mode_switch_threshold

+        )

+

+        # Initialize matplotlib figure and axes to None

+        self.fig: Optional[mpl.figure.Figure] = None

+        self.ax: Optional[mpl.axes.Axes] = None

+

+        # Store visualization elements for each trace

+        self._signal_lines: List[mpl.lines.Line2D] = []

+        self._envelope_fills: List[Optional[mpl.collections.PolyCollection]] = [

+            None

+        ] * self.data.num_traces

+

+        # Visualization elements with mode control (definitions, not plot objects)

+        self._lines: List[List[Dict[str, Any]]] = [

+            [] for _ in range(self.data.num_traces)

+        ]

+        self._ribbons: List[List[Dict[str, Any]]] = [

+            [] for _ in range(self.data.num_traces)

+        ]

+        self._regions: List[List[Dict[str, Any]]] = [

+            [] for _ in range(self.data.num_traces)

+        ]

+        self._envelopes: List[List[Dict[str, Any]]] = [

+            [] for _ in range(self.data.num_traces)

+        ]

+

+        # Line objects for each trace (will be populated as needed during rendering)

+        self._line_objects: List[List[mpl.artist.Artist]] = [

+            [] for _ in range(self.data.num_traces)

+        ]  # Changed type hint to Artist

+        self._ribbon_objects: List[List[mpl.collections.PolyCollection]] = [

+            [] for _ in range(self.data.num_traces)

+        ]

+        self._region_objects: List[List[mpl.collections.PolyCollection]] = [

+            [] for _ in range(self.data.num_traces)

+        ]

+

+        # Store current plot data for access by other methods

+        self._current_plot_data = {}

+

+        # Initialize coordinate manager

+        self.coord_manager = CoordinateManager(self.state)

+

+        # Store initial view for home button (using global time range)

+        t_start, t_end = self.data.get_global_time_range()

+        self._initial_xlim_raw = (t_start, t_end)

+

+        # Legend state for optimization

+        self._current_legend_handles: List[mpl.artist.Artist] = []

+        self._current_legend_labels: List[str] = []

+        self._legend: Optional[mpl.legend.Legend] = None

+

+        # Track last mode for each trace to optimize element updates

+        self._last_mode: Dict[int, Optional[int]] = {

+            i: None for i in range(self.data.num_traces)

+        }

+

+        # Store original toolbar methods for restoration

+        self._original_home = None

+        self._original_push_current = None

+

+    def save(self, filepath: str) -> None:

+        """

+        Save the current plot to a file.

+

+        Parameters

+        ----------

+        filepath : str

+            Path to save the plot image.

+        """

+        if self.fig is None or self.ax is None:

+            raise RuntimeError("Plot has not been initialized yet.")

+        self.fig.savefig(filepath)

+        logger.info(f"Plot saved to {filepath}")

+

+    def add_line(

+        self,

+        t: Union[np.ndarray, List[np.ndarray]],

+        data: Union[np.ndarray, List[np.ndarray]],

+        label: str = "Line",

+        color: Optional[str] = None,

+        alpha: float = 0.75,

+        linestyle: str = "-",

+        linewidth: float = 1.0,

+        display_mode: int = MODE_BOTH,

+        trace_idx: int = 0,

+        zorder: int = 5,

+    ) -> None:

+        """

+        Add a line to the plot with mode control.

+

+        Parameters

+        ----------

+        t : Union[np.ndarray, List[np.ndarray]]

+            Time array(s) for the line data. Must match the length of data.

+        data : Union[np.ndarray, List[np.ndarray]]

+            Line data array(s). Can be a single array or a list of arrays.

+        label : str, default="Line"

+            Label for the legend.

+        color : Optional[str], default=None

+            Color for the line. If None, the trace color will be used.

+        alpha : float, default=0.75

+            Alpha (transparency) for the line.

+        linestyle : str, default="-"

+            Line style.

+        linewidth : float, default=1.0

+            Line width.

+        display_mode : int, default=MODE_BOTH

+            Which mode(s) to show this line in (MODE_ENVELOPE, MODE_DETAIL, or MODE_BOTH).

+        trace_idx : int, default=0

+            Index of the trace to add the line to.

+        zorder : int, default=5

+            Z-order for the line (higher values appear on top).

+        """

+        if trace_idx < 0 or trace_idx >= self.data.num_traces:

+            raise ValueError(

+                f"Invalid trace index: {trace_idx}. Must be between 0 and {self.data.num_traces - 1}."

+            )

+

+        # Validate data length

+        if isinstance(data, list):

+            if len(data) != len(t):

+                raise ValueError(

+                    f"Line data length ({len(data)}) must match time array length ({len(t)})."

+                )

+        else:

+            if len(data) != len(t):

+                raise ValueError(

+                    f"Line data length ({len(data)}) must match time array length ({len(t)})."

+                )

+

+        # Use trace color if none provided

+        if color is None:

+            color = self.data.get_trace_color(trace_idx)

+

+        # Convert inputs to numpy arrays

+        t_array = np.asarray(t, dtype=np.float32)

+        data_array = np.asarray(data, dtype=np.float32)

+

+        # Assign a unique ID for this custom line for pre-decimation caching

+        # We use a negative ID to distinguish from main traces (which use 0, 1, 2...)

+        # and ensure uniqueness across custom lines.

+        line_id = -(len(self._lines[trace_idx]) + 1)  # Negative, unique per trace

+

+        # Pre-decimate this custom line's data for envelope view

+        self.decimator.pre_decimate_data(

+            data_id=line_id,

+            t=t_array,

+            x=data_array,

+            max_points=self.max_plot_points,

+            envelope_window_samples=None,  # Envelope window calculated automatically

+        )

+

+        # Store line definition with raw data and its assigned ID

+        line_def = {

+            "id": line_id,  # Store the ID for retrieval from decimator

+            "t_raw": t_array,  # Store raw time array

+            "data_raw": data_array,  # Store raw data array

+            "label": label,

+            "color": color,

+            "alpha": alpha,

+            "linestyle": linestyle,

+            "linewidth": linewidth,

+            "display_mode": display_mode,

+            "zorder": zorder,

+        }

+

+        logger.debug(

+            f"Adding line '{label}' with display_mode={display_mode} (MODE_ENVELOPE={self.MODE_ENVELOPE}, MODE_DETAIL={self.MODE_DETAIL}, MODE_BOTH={self.MODE_BOTH})"

+        )

+        self._lines[trace_idx].append(line_def)

+

+    def add_ribbon(

+        self,

+        t: Union[np.ndarray, List[np.ndarray]],

+        center_data: Union[np.ndarray, List[np.ndarray]],

+        width: Union[float, np.ndarray],

+        label: str = "Ribbon",

+        color: str = "gray",

+        alpha: float = 0.6,

+        display_mode: int = MODE_DETAIL,

+        trace_idx: int = 0,

+        zorder: int = 2,

+    ) -> None:

+        """

+        Add a ribbon (center ± width) with mode control.

+

+        Parameters

+        ----------

+        t : Union[np.ndarray, List[np.ndarray]]

+            Time array(s) for the ribbon data. Must match the length of center_data.

+        center_data : Union[np.ndarray, List[np.ndarray]]

+            Center line data array(s). Can be a single array or a list of arrays.

+        width : Union[float, np.ndarray]

+            Width of the ribbon. Can be a single value or an array matching center_data.

+        label : str, default="Ribbon"

+            Label for the legend.

+        color : str, default="gray"

+            Color for the ribbon.

+        alpha : float, default=0.6

+            Alpha (transparency) for the ribbon.

+        display_mode : int, default=MODE_DETAIL

+            Which mode(s) to show this ribbon in (MODE_ENVELOPE, MODE_DETAIL, or MODE_BOTH).

+        trace_idx : int, default=0

+            Index of the trace to add the ribbon to.

+        """

+        if trace_idx < 0 or trace_idx >= self.data.num_traces:

+            raise ValueError(

+                f"Invalid trace index: {trace_idx}. Must be between 0 and {self.data.num_traces - 1}."

+            )

+

+        # Validate data length

+        if isinstance(center_data, list):

+            if len(center_data) != len(t):

+                raise ValueError(

+                    f"Ribbon center data length ({len(center_data)}) must match time array length ({len(t)})."

+                )

+        else:

+            if len(center_data) != len(t):

+                raise ValueError(

+                    f"Ribbon center data length ({len(center_data)}) must match time array length ({len(t)})."

+                )

+

+        # Convert center data to numpy array

+        center_data = np.asarray(center_data, dtype=np.float32)

+

+        # Handle width as scalar or array

+        if isinstance(width, (int, float, np.number)):

+            width_array = np.ones_like(center_data) * width

+        else:

+            if len(width) != len(center_data):

+                raise ValueError(

+                    f"Ribbon width array length ({len(width)}) must match center data length ({len(center_data)})."

+                )

+            width_array = np.asarray(width, dtype=np.float32)

+

+        # Assign a unique ID for this custom ribbon

+        ribbon_id = -(

+            len(self._ribbons[trace_idx]) + 1001

+        )  # Negative, unique per trace, offset from lines

+

+        # Pre-decimate this custom ribbon's center data for envelope view

+        # We only pre-decimate the center, as width is applied later

+        self.decimator.pre_decimate_data(

+            data_id=ribbon_id,

+            t=np.asarray(t, dtype=np.float32),

+            x=center_data,

+            max_points=self.max_plot_points,

+            envelope_window_samples=None,  # Envelope window calculated automatically

+        )

+

+        # Store ribbon definition

+        ribbon_def = {

+            "id": ribbon_id,

+            "t_raw": np.asarray(t, dtype=np.float32),

+            "center_data_raw": center_data,

+            "width_raw": width_array,

+            "label": label,

+            "color": color,

+            "alpha": alpha,

+            "display_mode": display_mode,

+            "zorder": zorder,

+        }

+

+        self._ribbons[trace_idx].append(ribbon_def)

+

+    def add_envelope(

+        self,

+        min_data: Union[np.ndarray, List[np.ndarray]],

+        max_data: Union[np.ndarray, List[np.ndarray]],

+        label: str = "Envelope",

+        color: Optional[str] = None,

+        alpha: float = 0.4,

+        display_mode: int = MODE_ENVELOPE,

+        trace_idx: int = 0,

+        zorder: int = 1,

+    ) -> None:

+        """

+        Add envelope data with mode control.

+

+        Parameters

+        ----------

+        min_data : Union[np.ndarray, List[np.ndarray]]

+            Minimum envelope data array(s). Can be a single array or a list of arrays.

+        max_data : Union[np.ndarray, List[np.ndarray]]

+            Maximum envelope data array(s). Can be a single array or a list of arrays.

+        label : str, default="Envelope"

+            Label for the legend.

+        color : Optional[str], default=None

+            Color for the envelope. If None, the trace color will be used.

+        alpha : float, default=0.4

+            Alpha (transparency) for the envelope.

+        display_mode : int, default=MODE_ENVELOPE

+            Which mode(s) to show this envelope in (MODE_ENVELOPE, MODE_DETAIL, or MODE_BOTH).

+        trace_idx : int, default=0

+            Index of the trace to add the envelope to.

+        """

+        if trace_idx < 0 or trace_idx >= self.data.num_traces:

+            raise ValueError(

+                f"Invalid trace index: {trace_idx}. Must be between 0 and {self.data.num_traces - 1}."

+            )

+

+        # Validate data length

+        if isinstance(min_data, list):

+            if len(min_data) != len(self.data.t_arrays[trace_idx]):

+                raise ValueError(

+                    f"Envelope min data length ({len(min_data)}) must match time array length ({len(self.data.t_arrays[trace_idx])})."

+                )

+        else:

+            if len(min_data) != len(self.data.t_arrays[trace_idx]):

+                raise ValueError(

+                    f"Envelope min data length ({len(min_data)}) must match time array length ({len(self.data.t_arrays[trace_idx])})."

+                )

+

+        if isinstance(max_data, list):

+            if len(max_data) != len(self.data.t_arrays[trace_idx]):

+                raise ValueError(

+                    f"Envelope max data length ({len(max_data)}) must match time array length ({len(self.data.t_arrays[trace_idx])})."

+                )

+        else:

+            if len(max_data) != len(self.data.t_arrays[trace_idx]):

+                raise ValueError(

+                    f"Envelope max data length ({len(max_data)}) must match time array length ({len(self.data.t_arrays[trace_idx])})."

+                )

+

+        # Use trace color if none provided

+        if color is None:

+            color = self.data.get_trace_color(trace_idx)

+

+        # Assign a unique ID for this custom envelope

+        envelope_id = -(

+            len(self._envelopes[trace_idx]) + 2001

+        )  # Negative, unique per trace, offset from ribbons

+

+        # Pre-decimate this custom envelope's data for envelope view

+        # We'll pre-decimate the average of min/max, and store min/max separately

+        t_raw = self.data.t_arrays[trace_idx]

+        avg_data = (

+            np.asarray(min_data, dtype=np.float32)

+            + np.asarray(max_data, dtype=np.float32)

+        ) / 2

+

+        self.decimator.pre_decimate_data(

+            data_id=envelope_id,

+            t=t_raw,

+            x=avg_data,  # Pass average for decimation

+            max_points=self.max_plot_points,

+            envelope_window_samples=None,  # Envelope window calculated automatically

+        )

+

+        # Store envelope definition

+        envelope_def = {

+            "id": envelope_id,

+            "t_raw": t_raw,

+            "min_data_raw": np.asarray(min_data, dtype=np.float32),

+            "max_data_raw": np.asarray(max_data, dtype=np.float32),

+            "label": label,

+            "color": color,

+            "alpha": alpha,

+            "display_mode": display_mode,

+            "zorder": zorder,

+        }

+

+        self._envelopes[trace_idx].append(envelope_def)

+

+    def add_regions(

+        self,

+        regions: np.ndarray,

+        label: str = "Regions",

+        color: str = "crimson",

+        alpha: float = 0.4,

+        display_mode: int = MODE_BOTH,

+        trace_idx: int = 0,

+        zorder: int = -5,

+    ) -> None:

+        """

+        Add region highlights with mode control.

+

+        Parameters

+        ----------

+        regions : np.ndarray

+            Region data array with shape (N, 2) where each row is [start_time, end_time].

+        label : str, default="Regions"

+            Label for the legend.

+        color : str, default="crimson"

+            Color for the regions.

+        alpha : float, default=0.4

+            Alpha (transparency) for the regions.

+        display_mode : int, default=MODE_BOTH

+            Which mode(s) to show these regions in (MODE_ENVELOPE, MODE_DETAIL, or MODE_BOTH).

+        trace_idx : int, default=0

+            Index of the trace to add the regions to.

+        """

+        if trace_idx < 0 or trace_idx >= self.data.num_traces:

+            raise ValueError(

+                f"Invalid trace index: {trace_idx}. Must be between 0 and {self.data.num_traces - 1}."

+            )

+

+        # Validate regions array

+        if regions.ndim != 2 or regions.shape[1] != 2:

+            raise ValueError(

+                f"Regions array must have shape (N, 2), got {regions.shape}."

+            )

+

+        # Store regions definition

+        region_def = {

+            "regions": np.asarray(regions, dtype=np.float32),

+            "label": label,

+            "color": color,

+            "alpha": alpha,

+            "display_mode": display_mode,

+            "zorder": zorder,

+        }

+

+        logger.debug(

+            f"Adding regions '{label}' with {len(regions)} entries, display_mode={display_mode}"

+        )

+        self._regions[trace_idx].append(region_def)

+

+    def _update_signal_display(

+        self,

+        trace_idx: int,

+        t_display: np.ndarray,

+        x_data: np.ndarray,

+        envelope_data: Optional[Tuple[np.ndarray, np.ndarray]] = None,

+    ) -> None:

+        """

+        Update signal display with envelope or raw data for a specific trace.

+

+        Parameters

+        ----------

+        trace_idx : int

+            Index of the trace to update.

+        t_display : np.ndarray

+            Display time array.

+        x_data : np.ndarray

+            Signal data array.

+        envelope_data : Optional[Tuple[np.ndarray, np.ndarray]], default=None

+            Tuple of (min, max) envelope data if in envelope mode.

+        """

+        logger.debug(f"=== _update_signal_display trace {trace_idx} ===")

+        logger.debug(

+            f"t_display: len={len(t_display)}, range=[{np.min(t_display) if len(t_display) > 0 else 'empty':.6f}, {np.max(t_display) if len(t_display) > 0 else 'empty':.6f}]"

+        )

+        logger.debug(

+            f"x_data: len={len(x_data)}, range=[{np.min(x_data) if len(x_data) > 0 else 'empty':.6f}, {np.max(x_data) if len(x_data) > 0 else 'empty':.6f}]"

+        )

+        logger.debug(f"envelope_data: {envelope_data is not None}")

+

+        if envelope_data is not None:

+            x_min, x_max = envelope_data

+            logger.debug(

+                f"envelope x_min: len={len(x_min)}, range=[{np.min(x_min) if len(x_min) > 0 else 'empty':.6f}, {np.max(x_min) if len(x_min) > 0 else 'empty':.6f}]"

+            )

+            logger.debug(

+                f"envelope x_max: len={len(x_max)}, range=[{np.max(x_max) if len(x_max) > 0 else 'empty':.6f}, {np.max(x_max) if len(x_max) > 0 else 'empty':.6f}]"

+            )

+            self._show_envelope_mode(trace_idx, t_display, envelope_data)

+        else:

+            logger.debug("Showing detail mode (raw signal)")

+            self._show_detail_mode(trace_idx, t_display, x_data)

+

+    def _show_envelope_mode(

+        self,

+        trace_idx: int,

+        t_display: np.ndarray,

+        envelope_data: Tuple[np.ndarray, np.ndarray],

+    ) -> None:

+        """

+        Show envelope display mode for a specific trace.

+

+        Parameters

+        ----------

+        trace_idx : int

+            Index of the trace to update.

+        t_display : np.ndarray

+            Display time array.

+        envelope_data : Tuple[np.ndarray, np.ndarray]

+            Tuple of (min, max) envelope data.

+        """

+        logger.debug(f"=== _show_envelope_mode trace {trace_idx} ===")

+        x_min, x_max = envelope_data

+        color = self.data.get_trace_color(trace_idx)

+        name = self.data.get_trace_name(trace_idx)

+

+        logger.debug(f"Envelope data: x_min len={len(x_min)}, x_max len={len(x_max)}")

+        logger.debug(

+            f"t_display range: [{np.min(t_display):.6f}, {np.max(t_display):.6f}]"

+        )

+        logger.debug(f"y_range: [{np.min(x_min):.6f}, {np.max(x_max):.6f}]")

+

+        # Clean up previous displays

+        if self._envelope_fills[trace_idx] is not None:

+            logger.debug("Removing previous envelope fill")

+            self._envelope_fills[trace_idx].remove()

+

+        logger.debug("Hiding signal line")

+        self._signal_lines[trace_idx].set_data([], [])

+        self._signal_lines[trace_idx].set_visible(False)

+

+        # Show built-in envelope

+        logger.debug(

+            f"Creating envelope fill with color={color}, alpha={self.envelope_alpha}"

+        )

+        self._envelope_fills[trace_idx] = self.ax.fill_between(

+            t_display,

+            x_min,

+            x_max,

+            alpha=self.envelope_alpha,

+            color=color,

+            lw=0.1,

+            label=f"Raw envelope ({name})"

+            if self.data.num_traces > 1

+            else "Raw envelope",

+            zorder=1,  # Keep default envelope at zorder=1

+        )

+

+        # Set current mode

+        self.state.current_mode = "envelope"

+        logger.debug("Set current_mode to 'envelope'")

+

+        # Show any custom elements for this mode

+        self._show_custom_elements(trace_idx, t_display, self.MODE_ENVELOPE)

+

+    def _show_detail_mode(

+        self, trace_idx: int, t_display: np.ndarray, x_data: np.ndarray

+    ) -> None:

+        """

+        Show detail display mode for a specific trace.

+

+        Parameters

+        ----------

+        trace_idx : int

+            Index of the trace to update.

+        t_display : np.ndarray

+            Display time array.

+        x_data : np.ndarray

+            Signal data array.

+        """

+        logger.debug(f"=== _show_detail_mode trace {trace_idx} ===")

+        logger.debug(

+            f"t_display: len={len(t_display)}, range=[{np.min(t_display) if len(t_display) > 0 else 'empty':.6f}, {np.max(t_display) if len(t_display) > 0 else 'empty':.6f}]"

+        )

+        logger.debug(

+            f"x_data: len={len(x_data)}, range=[{np.min(x_data) if len(x_data) > 0 else 'empty':.6f}, {np.max(x_data) if len(x_data) > 0 else 'empty':.6f}]"

+        )

+

+        # Clean up envelope

+        if self._envelope_fills[trace_idx] is not None:

+            logger.debug("Removing envelope fill")

+            self._envelope_fills[trace_idx].remove()

+            self._envelope_fills[trace_idx] = None

+

+        # Update signal line

+        line = self._signal_lines[trace_idx]

+        logger.debug(

+            f"Setting signal line data: linewidth={self.signal_line_width}, alpha={self.signal_alpha}"

+        )

+        line.set_data(t_display, x_data)

+        line.set_linewidth(self.signal_line_width)

+        line.set_alpha(self.signal_alpha)

+        line.set_visible(True)

+

+        # Set current mode

+        self.state.current_mode = "detail"

+        logger.debug("Set current_mode to 'detail'")

+

+        # Show any custom elements for this mode

+        self._show_custom_elements(trace_idx, t_display, self.MODE_DETAIL)

+

+    def _show_custom_elements(

+        self, trace_idx: int, t_display: np.ndarray, current_mode: int

+    ) -> None:

+        """

+        Show custom visualization elements for the current mode.

+

+        Parameters

+        ----------

+        trace_idx : int

+            Index of the trace to update.

+        t_display : np.ndarray

+            Display time array.

+        current_mode : int

+            Current display mode (MODE_ENVELOPE or MODE_DETAIL).

+        """

+        logger.debug(

+            f"=== _show_custom_elements trace {trace_idx}, current_mode={current_mode} ==="

+        )

+

+        last_mode = self._last_mode.get(trace_idx)

+        logger.debug(f"Last mode for trace {trace_idx}: {last_mode}")

+

+        # Always clear and recreate elements when view changes, regardless of mode change

+        # This ensures custom lines/ribbons are redrawn correctly with current view data

+        logger.debug(

+            f"Clearing and recreating elements for trace {trace_idx} (mode: {last_mode} -> {current_mode})"

+        )

+        self._clear_custom_elements(trace_idx)

+

+        # Get current raw x-limits from the main plot data

+        # This is crucial for decimating custom lines to the current view

+        current_xlim_raw = self.coord_manager.get_current_view_raw(self.ax)

+

+        # Show lines for current mode

+        line_objects = []

+        for i, line_def in enumerate(self._lines[trace_idx]):

+            logger.debug(

+                f"Processing line {i} ('{line_def['label']}'): display_mode={line_def['display_mode']}, current_mode={current_mode}"

+            )

+            if (

+                line_def["display_mode"] & current_mode

+            ):  # Bitwise check if mode is enabled

+                logger.debug(

+                    f"Line {i} ('{line_def['label']}') should be visible in mode {current_mode}"

+                )

+

+                # Dynamically decimate the line data for the current view

+                # Use the same max_plot_points as the main signal for consistency

+                # For custom lines, we want mean decimation if in envelope mode, not min/max envelope

+                t_line_raw, line_data, _, _ = self.decimator.decimate_for_view(

+                    line_def["t_raw"],

+                    line_def["data_raw"],

+                    current_xlim_raw,  # Decimate to current view

+                    self.max_plot_points,

+                    use_envelope=(current_mode == self.MODE_ENVELOPE),

+                    data_id=line_def[

+                        "id"

+                    ],  # Pass the custom line's ID for pre-decimated data lookup

+                    envelope_window_samples=None,  # Envelope window calculated automatically

+                    mode_switch_threshold=self.mode_switch_threshold,  # Pass mode switch threshold

+                    return_envelope_min_max=False,  # Custom lines never return min/max envelope

+                )

+

+                if len(t_line_raw) == 0 or len(line_data) == 0:

+                    logger.warning(

+                        f"Line {i} ('{line_def['label']}') has empty data after decimation for current view, skipping plot."

+                    )

+                    continue

+

+                # Make sure the time array is in display coordinates

+                t_line_display = self.coord_manager.raw_to_display(t_line_raw)

+

+                # Always plot as a regular line

+                (line,) = self.ax.plot(

+                    t_line_display,

+                    line_data,

+                    label=line_def["label"],

+                    color=line_def["color"],

+                    alpha=line_def["alpha"],

+                    linestyle=line_def["linestyle"],

+                    linewidth=line_def["linewidth"],

+                    zorder=line_def["zorder"],

+                )

+                line_objects.append(

+                    (line, line_def)

+                )  # Store both the line and its definition

+                logger.debug(f"Added line {i} ('{line_def['label']}') to plot")

+            else:

+                logger.debug(

+                    f"Line {i} ('{line_def['label']}') should NOT be visible in mode {current_mode}"

+                )

+

+        # Show ribbons for current mode

+        ribbon_objects = []

+        for ribbon_def in self._ribbons[trace_idx]:

+            logger.debug(

+                f"Processing ribbon ('{ribbon_def['label']}'): display_mode={ribbon_def['display_mode']}, current_mode={current_mode}"

+            )

+            if ribbon_def["display_mode"] & current_mode:

+                logger.debug(

+                    f"Ribbon ('{ribbon_def['label']}') should be visible in mode {current_mode}"

+                )

+

+                # Ribbons are always plotted as fills, so we need to decimate their center and width

+                # We'll treat the center_data as the 'signal' for decimation purposes

+                (

+                    t_ribbon_raw,

+                    center_data_decimated,

+                    min_center_envelope,

+                    max_center_envelope,

+                ) = self.decimator.decimate_for_view(

+                    ribbon_def["t_raw"],

+                    ribbon_def["center_data_raw"],

+                    current_xlim_raw,

+                    self.max_plot_points,

+                    use_envelope=(

+                        current_mode == self.MODE_ENVELOPE

+                    ),  # Use envelope for ribbons if in envelope mode

+                    data_id=ribbon_def[

+                        "id"

+                    ],  # Pass the custom ribbon's ID for pre-decimated data lookup

+                    return_envelope_min_max=True,  # Ribbons always need min/max to draw fill

+                    envelope_window_samples=None,  # Envelope window calculated automatically

+                    mode_switch_threshold=self.mode_switch_threshold,

+                )

+

+                # Decimate the width array as well, if it's an array

+                width_decimated = ribbon_def["width_raw"]

+                if len(ribbon_def["width_raw"]) > len(

+                    t_ribbon_raw

+                ):  # If raw width is longer than decimated time

+                    # For simplicity, we'll just take the mean of the width in each bin

+                    # A more robust solution might involve passing width as another data stream to decimate_for_view

+                    # For now, we'll manually decimate it based on the t_ribbon_raw indices

+                    # Find indices in raw data corresponding to decimated time points

+                    # This is a simplified approach and assumes uniform sampling for width

+                    indices = np.searchsorted(ribbon_def["t_raw"], t_ribbon_raw)

+                    indices = np.clip(indices, 0, len(ribbon_def["width_raw"]) - 1)

+                    width_decimated = ribbon_def["width_raw"][indices]

+

+                # If the ribbon was decimated to an envelope, use that for min/max

+                if (

+                    current_mode == self.MODE_ENVELOPE

+                    and min_center_envelope is not None

+                    and max_center_envelope is not None

+                ):

+                    lower_bound = min_center_envelope - width_decimated

+                    upper_bound = max_center_envelope + width_decimated

+                else:

+                    lower_bound = center_data_decimated - width_decimated

+                    upper_bound = center_data_decimated + width_decimated

+

+                if len(t_ribbon_raw) == 0 or len(lower_bound) == 0:

+                    logger.warning(

+                        f"Ribbon ('{ribbon_def['label']}') has empty data after decimation, skipping plot."

+                    )

+                    continue

+

+                # Make sure the time array is in display coordinates

+                t_ribbon_display = self.coord_manager.raw_to_display(t_ribbon_raw)

+

+                ribbon = self.ax.fill_between(

+                    t_ribbon_display,

+                    lower_bound,

+                    upper_bound,

+                    color=ribbon_def["color"],

+                    alpha=ribbon_def["alpha"],

+                    label=ribbon_def["label"],

+                    zorder=ribbon_def["zorder"],

+                )

+                ribbon_objects.append(

+                    (ribbon, ribbon_def)

+                )  # Store both the ribbon and its definition

+                logger.debug(f"Added ribbon ('{ribbon_def['label']}') to plot")

+            else:

+                logger.debug(

+                    f"Ribbon ('{ribbon_def['label']}') should NOT be visible in mode {current_mode}"

+                )

+

+        # Show custom envelopes for current mode

+        for envelope_def in self._envelopes[trace_idx]:

+            logger.debug(

+                f"Processing custom envelope ('{envelope_def['label']}'): display_mode={envelope_def['display_mode']}, current_mode={current_mode}"

+            )

+            if envelope_def["display_mode"] & current_mode:

+                logger.debug(

+                    f"Custom envelope ('{envelope_def['label']}') should be visible in mode {current_mode}"

+                )

+

+                # For custom envelopes, we need to handle min/max data specially

+                # We'll decimate the min and max data separately using the envelope's stored data

+                # Since we stored min/max in the pre-decimated data, we can retrieve them

+

+                # Get the pre-decimated envelope data for this custom envelope

+                if envelope_def["id"] in self.decimator._pre_decimated_envelopes:

+                    pre_dec_data = self.decimator._pre_decimated_envelopes[

+                        envelope_def["id"]

+                    ]

+                    # The min/max data was stored in bg_initial/bg_clean during pre-decimation

+                    t_envelope_raw, _, min_data_decimated, max_data_decimated = (

+                        self.decimator.decimate_for_view(

+                            envelope_def["t_raw"],

+                            (

+                                envelope_def["min_data_raw"]

+                                + envelope_def["max_data_raw"]

+                            )

+                            / 2,  # Average for decimation

+                            current_xlim_raw,

+                            self.max_plot_points,

+                            use_envelope=True,  # Always treat custom envelopes as envelopes

+                            data_id=envelope_def[

+                                "id"

+                            ],  # Pass the custom envelope's ID for pre-decimated data lookup

+                            return_envelope_min_max=True,  # Custom envelopes always need min/max to draw fill

+                            envelope_window_samples=None,  # Envelope window calculated automatically

+                            mode_switch_threshold=self.mode_switch_threshold,

+                        )

+                    )

+                    # For custom envelopes, the min/max are returned directly as the last two return values

+                else:

+                    # Fallback if no pre-decimated data

+                    logger.warning(

+                        f"No pre-decimated data for custom envelope {envelope_def['id']}, using raw decimation"

+                    )

+                    t_envelope_raw, _, min_data_decimated, max_data_decimated = (

+                        self.decimator.decimate_for_view(

+                            envelope_def["t_raw"],

+                            (

+                                envelope_def["min_data_raw"]

+                                + envelope_def["max_data_raw"]

+                            )

+                            / 2,

+                            current_xlim_raw,

+                            self.max_plot_points,

+                            use_envelope=True,

+                            data_id=None,  # No pre-decimated data available

+                            return_envelope_min_max=True,

+                            envelope_window_samples=None,  # Envelope window calculated automatically

+                            mode_switch_threshold=self.mode_switch_threshold,

+                        )

+                    )

+

+                if (

+                    len(t_envelope_raw) == 0

+                    or min_data_decimated is None

+                    or max_data_decimated is None

+                    or len(min_data_decimated) == 0

+                ):

+                    logger.warning(

+                        f"Custom envelope ('{envelope_def['label']}') has empty data after decimation, skipping plot."

+                    )

+                    continue

+

+                t_envelope_display = self.coord_manager.raw_to_display(t_envelope_raw)

+

+                envelope = self.ax.fill_between(

+                    t_envelope_display,

+                    min_data_decimated,

+                    max_data_decimated,

+                    color=envelope_def["color"],

+                    alpha=envelope_def["alpha"],

+                    label=envelope_def["label"],

+                    zorder=envelope_def["zorder"],

+                )

+                ribbon_objects.append(

+                    (envelope, envelope_def)

+                )  # Store in ribbon objects

+                logger.debug(

+                    f"Added custom envelope ('{envelope_def['label']}') to plot"

+                )

+            else:

+                logger.debug(

+                    f"Custom envelope ('{envelope_def['label']}') should NOT be visible in mode {current_mode}"

+                )

+

+        # Store objects with their definitions for future updates

+        self._line_objects[trace_idx] = line_objects

+        self._ribbon_objects[trace_idx] = ribbon_objects

+

+        # Update last mode AFTER processing

+        self._last_mode[trace_idx] = current_mode

+

+    def _update_element_visibility(self, trace_idx: int, current_mode: int) -> None:

+        """

+        Update visibility of existing custom elements based on current mode.

+

+        Parameters

+        ----------

+        trace_idx : int

+            Index of the trace to update.

+        current_mode : int

+            Current display mode (MODE_ENVELOPE or MODE_DETAIL).

+        """

+        logger.debug(

+            f"Updating element visibility for trace {trace_idx}, current_mode={current_mode}"

+        )

+        # Update line visibility

+        for line_obj, line_def in self._line_objects[trace_idx]:

+            should_be_visible = bool(line_def["display_mode"] & current_mode)

+            if line_obj.get_visible() != should_be_visible:

+                line_obj.set_visible(should_be_visible)

+                logger.debug(

+                    f"Set visibility of line '{line_def['label']}' to {should_be_visible}"

+                )

+

+        # Update ribbon visibility

+        for ribbon_obj, ribbon_def in self._ribbon_objects[trace_idx]:

+            should_be_visible = bool(ribbon_def["display_mode"] & current_mode)

+            if ribbon_obj.get_visible() != should_be_visible:

+                ribbon_obj.set_visible(should_be_visible)

+                logger.debug(

+                    f"Set visibility of ribbon '{ribbon_def['label']}' to {should_be_visible}"

+                )

+

+    def _clear_custom_elements(self, trace_idx: int) -> None:

+        """

+        Clear all custom visualization elements for a trace.

+

+        Parameters

+        ----------

+        trace_idx : int

+            Index of the trace to clear elements for.

+        """

+        logger.debug(f"Clearing custom elements for trace {trace_idx}")

+        # Clear lines

+        for line_obj, _ in self._line_objects[trace_idx]:

+            line_obj.remove()

+        self._line_objects[trace_idx].clear()

+

+        # Clear ribbons

+        for ribbon_obj, _ in self._ribbon_objects[trace_idx]:

+            ribbon_obj.remove()

+        self._ribbon_objects[trace_idx].clear()

+

+    def _update_tick_locator(self, time_span_raw: np.float32) -> None:

+        """Update tick locator based on current time scale and span."""

+        if self.state.current_time_scale >= np.float32(1e6):  # microseconds or smaller

+            # For microsecond scale, use reasonable intervals

+            tick_interval = max(

+                1, int(time_span_raw * self.state.current_time_scale / 10)

+            )

+            self.ax.xaxis.set_major_locator(MultipleLocator(tick_interval))

+        else:

+            # For larger scales, use matplotlib's default auto locator

+            self.ax.xaxis.set_major_locator(mpl.ticker.AutoLocator())

+

+    def _update_legend(self) -> None:

+        """Updates the plot legend, filtering out invisible elements and optimising rebuilds."""

+        logger.debug("Updating legend...")

+        handles, labels = self.ax.get_legend_handles_labels()

+

+        # Filter for unique and visible handles/labels

+        unique_labels = []

+        unique_handles = []

+        for h, l in zip(handles, labels):

+            # Check if the handle has a get_visible method and if it returns True

+            # For fill_between objects (ribbons, envelopes, regions), get_visible might not exist or behave differently

+            # For these, we assume they are visible if they are in the list of objects

+            is_visible = True

+            if hasattr(h, "get_visible"):

+                is_visible = h.get_visible()

+            elif isinstance(

+                h, mpl.collections.PolyCollection

+            ):  # For fill_between objects

+                # PolyCollection doesn't have get_visible, but its patches might.

+                # Or we can assume it's visible if it's part of the current plot.

+                # For now, assume it's visible if it's a PolyCollection and has data.

+                is_visible = len(h.get_paths()) > 0  # Check if it has any paths to draw

+

+            if l not in unique_labels and is_visible:

+                unique_labels.append(l)

+                unique_handles.append(h)

+

+        logger.debug(f"Unique visible legend items found: {unique_labels}")

+

+        # Create a hash of current handles/labels for efficient comparison

+        current_hash = hash(tuple(id(h) for h in unique_handles) + tuple(unique_labels))

+

+        # Check if legend content actually changed

+        if (

+            not hasattr(self, "_last_legend_hash")

+            or self._last_legend_hash != current_hash

+        ):

+            logger.debug("Legend content changed, rebuilding legend.")

+            if self._legend is not None:

+                self._legend.remove()  # Remove old legend to prevent duplicates

+

+            if unique_handles:  # Only create legend if there are handles to show

+                self._legend = self.ax.legend(

+                    unique_handles, unique_labels, loc="lower right"

+                )

+                logger.debug("New legend created.")

+            else:

+                self._legend = None  # No legend to show

+                logger.debug("No legend to show.")

+

+            self._current_legend_handles = unique_handles

+            self._current_legend_labels = unique_labels

+            self._last_legend_hash = current_hash

+        else:

+            logger.debug("Legend content unchanged, skipping rebuild.")

+

+    def _clear_navigation_history(self):

+        """Clear matplotlib's navigation history when coordinate system changes."""

+        if (

+            self.fig

+            and self.fig.canvas

+            and hasattr(self.fig.canvas, "toolbar")

+            and self.fig.canvas.toolbar

+        ):

+            toolbar = self.fig.canvas.toolbar

+            if hasattr(toolbar, "_nav_stack"):

+                toolbar._nav_stack.clear()

+

+    def _push_current_view(self):

+        """Push current view to navigation history as new base."""

+        if (

+            self.fig

+            and self.fig.canvas

+            and hasattr(self.fig.canvas, "toolbar")

+            and self.fig.canvas.toolbar

+        ):

+            toolbar = self.fig.canvas.toolbar

+            if hasattr(toolbar, "push_current"):

+                toolbar.push_current()

+

+    def _update_axis_formatting(self) -> None:

+        """Update axis labels and formatters."""

+        if self.state.offset_time_raw is not None:

+            offset_value = self.state.offset_time_raw * (

+                1e3

+                if self.state.offset_unit == "ms"

+                else 1e6

+                if self.state.offset_unit == "us"

+                else 1e9

+                if self.state.offset_unit == "ns"

+                else 1.0

+            )

+            xlabel = f"Time ({self.state.current_time_unit}) + {offset_value:.3g} {self.state.offset_unit}"

+        else:

+            xlabel = f"Time ({self.state.current_time_unit})"

+

+        self.ax.set_xlabel(xlabel)

+

+        formatter = _create_time_formatter(

+            self.state.offset_time_raw, self.state.current_time_scale

+        )

+        self.ax.xaxis.set_major_formatter(formatter)

+

+    def _update_overlay_lines(

+        self, plot_data: Dict[str, Any], show_overlays: bool

+    ) -> None:

+        """Update overlay lines based on zoom level and data availability."""

+        # Clear existing overlay lines from the plot

+        # This method is not currently used in the provided code, but if it were,

+        # it would need to be updated to use the new decimation strategy.

+        # For now, leaving it as is, assuming it's a placeholder or for future_use.

+        # If it were to be used, it would need to call decimate_for_view for each overlay line.

+        pass  # No _overlay_lines attribute in this class, this method is unused.

+

+    def _update_y_limits(self, plot_data: Dict[str, Any], use_envelope: bool) -> None:

+        """Update y-axis limits to fit current data."""

+        y_min_data = float("inf")

+        y_max_data = float("-inf")

+

+        # Process each trace

+        for trace_idx in range(self.data.num_traces):

+            x_new_key = f"x_new_{trace_idx}"

+            x_min_key = f"x_min_{trace_idx}"

+            x_max_key = f"x_max_{trace_idx}"

+

+            if x_new_key not in plot_data:

+                continue

+

+            # Include signal data

+            if len(plot_data[x_new_key]) > 0:

+                y_min_data = min(y_min_data, np.min(plot_data[x_new_key]))

+                y_max_data = max(y_max_data, np.max(plot_data[x_new_key]))

+

+            # Include envelope data if available

+            if use_envelope and x_min_key in plot_data and x_max_key in plot_data:

+                if (

+                    plot_data[x_min_key] is not None

+                    and plot_data[x_max_key] is not None

+                    and len(plot_data[x_min_key]) > 0

+                ):

+                    y_min_data = min(y_min_data, np.min(plot_data[x_min_key]))

+                    y_max_data = max(y_max_data, np.max(plot_data[x_max_key]))

+

+            # Include custom lines

+            for line_obj, _ in self._line_objects[trace_idx]:

+                # Check if line_obj is a Line2D or PolyCollection

+                if isinstance(line_obj, mpl.lines.Line2D):

+                    y_data = line_obj.get_ydata()

+                    if len(y_data) > 0:

+                        y_min_data = min(y_min_data, np.min(y_data))

+                        y_max_data = max(y_max_data, np.max(y_data))

+                elif isinstance(line_obj, mpl.collections.PolyCollection):

+                    # For fill_between objects, iterate through paths to get y-coordinates

+                    for path in line_obj.get_paths():

+                        vertices = path.vertices

+                        if len(vertices) > 0:

+                            y_min_data = min(y_min_data, np.min(vertices[:, 1]))

+                            y_max_data = max(y_max_data, np.max(vertices[:, 1]))

+

+            # Include ribbon data

+            for ribbon_obj, _ in self._ribbon_objects[trace_idx]:

+                # For fill_between objects, we need to get the paths

+                if hasattr(ribbon_obj, "get_paths") and len(ribbon_obj.get_paths()) > 0:

+                    for path in ribbon_obj.get_paths():

+                        vertices = path.vertices

+                        if len(vertices) > 0:

+                            y_min_data = min(y_min_data, np.min(vertices[:, 1]))

+                            y_max_data = max(y_max_data, np.max(vertices[:, 1]))

+

+        # Handle case where no data was found

+        if y_min_data == float("inf") or y_max_data == float("-inf"):

+            self.ax.set_ylim(0, 1)

+            return

+

+        data_range = y_max_data - y_min_data

+        data_mean = (y_min_data + y_max_data) / 2

+

+        # Use min_y_range to ensure a minimum visible range

+        min_visible_range = self.min_y_range

+

+        if data_range < min_visible_range:

+            y_min = data_mean - min_visible_range / 2

+            y_max = data_mean + min_visible_range / 2

+        else:

+            y_margin = self.y_margin_fraction * data_range

+            y_min = y_min_data - y_margin

+            y_max = y_max_data + y_margin

+

+        logger.debug(

+            f"Y-limit calculation details: data_range={data_range:.3g}, min_visible_range={min_visible_range:.3g}, data_mean={data_mean:.3g}"

+        )  # ADDED THIS LINE

+        logger.debug(

+            f"Pre-set Y-limits: y_min={y_min:.9f}, y_max={y_max:.9f}"

+        )  # ADDED THIS LINE

+        self.ax.set_ylim(y_min, y_max)

+

+    def _update_plot_data(self, ax_obj) -> None:

+        """Update plot based on current view."""

+        if self.state.is_updating():

+            return

+

+        self.state.set_updating(True)

+

+        try:

+            try:

+                # Add debug logging for current axis limits

+                display_xlim = ax_obj.get_xlim()

+                logger.debug(f"Current display xlim: {display_xlim}")

+

+                view_params = self._calculate_view_parameters(ax_obj)

+                logger.debug(

+                    f"Calculated view parameters: xlim_raw={view_params['xlim_raw']}, time_span_raw={view_params['time_span_raw']}, use_envelope={view_params['use_envelope']}"

+                )

+

+                plot_data = self._get_plot_data(view_params)

+

+                # Debug data availability

+                data_summary = {}

+                for trace_idx in range(self.data.num_traces):

+                    t_key = f"t_display_{trace_idx}"

+                    if t_key in plot_data:

+                        data_summary[t_key] = len(plot_data[t_key])

+                logger.debug(f"Plot data summary: {data_summary}")

+

+                self._render_plot_elements(plot_data, view_params)

+                self._update_regions_and_legend(view_params["xlim_display"])

+                self.fig.canvas.draw_idle()

+            except Exception as e:

+                logger.exception(f"Error updating plot: {e}")

+                # Try to recover by resetting to home view

+                logger.info("Attempting to recover by resetting to home view")

+                self.home()

+        finally:

+            self.state.set_updating(False)

+

+    def _calculate_view_parameters(self, ax_obj) -> Dict[str, Any]:

+        """Calculate view parameters from current axis state."""

+        try:

+            xlim_raw = self.coord_manager.get_current_view_raw(ax_obj)

+

+            # Validate xlim_raw values

+            if not np.isfinite(xlim_raw[0]) or not np.isfinite(xlim_raw[1]):

+                logger.warning(

+                    f"Invalid xlim_raw from axis: {xlim_raw}. Using initial view."

+                )

+                xlim_raw = self._initial_xlim_raw

+

+            # Ensure xlim_raw is in ascending order

+            if xlim_raw[0] > xlim_raw[1]:

+                logger.warning(f"xlim_raw values out of order: {xlim_raw}. Swapping.")

+                xlim_raw = (xlim_raw[1], xlim_raw[0])

+

+            time_span_raw = xlim_raw[1] - xlim_raw[0]

+            use_envelope = self.state.should_use_envelope(time_span_raw)

+            current_mode = self.MODE_ENVELOPE if use_envelope else self.MODE_DETAIL

+

+            logger.debug(f"=== _calculate_view_parameters ===")

+            logger.debug(f"xlim_raw: {xlim_raw}")

+            logger.debug(f"time_span_raw: {time_span_raw:.6e}s")

+            logger.debug(

+                f"envelope_limit: {self.mode_switch_threshold:.6e}s"

+            )  # Use mode_switch_threshold

+            logger.debug(f"use_envelope: {use_envelope}")

+            logger.debug(

+                f"current_mode: {current_mode} ({'ENVELOPE' if current_mode == self.MODE_ENVELOPE else 'DETAIL'})"

+            )

+

+            # Update coordinate system if needed

+            coordinate_system_changed = self.state.update_display_params(

+                xlim_raw, time_span_raw

+            )

+            if coordinate_system_changed:

+                logger.debug("Coordinate system changed, updating")

+                self._update_coordinate_system(xlim_raw, time_span_raw)

+

+            return {

+                "xlim_raw": xlim_raw,

+                "time_span_raw": time_span_raw,

+                "xlim_display": self.coord_manager.xlim_raw_to_display(xlim_raw),

+                "use_envelope": use_envelope,

+                "current_mode": current_mode,

+            }

+        except Exception as e:

+            logger.exception(f"Error calculating view parameters: {e}")

+            # Return safe default values

+            return {

+                "xlim_raw": self._initial_xlim_raw,

+                "time_span_raw": self._initial_xlim_raw[1] - self._initial_xlim_raw[0],

+                "xlim_display": self.coord_manager.xlim_raw_to_display(

+                    self._initial_xlim_raw

+                ),

+                "use_envelope": True,

+                "current_mode": self.MODE_ENVELOPE,

+            }

+

+    def _get_plot_data(self, view_params: Dict[str, Any]) -> Dict[str, Any]:

+        """Get decimated plot data for current view."""

+        logger.debug(f"=== _get_plot_data ===")

+        logger.debug(f"view_params: {view_params}")

+

+        plot_data = {}

+

+        # Process each trace

+        for trace_idx in range(self.data.num_traces):

+            logger.debug(f"--- Processing trace {trace_idx} ---")

+            t_arr = self.data.t_arrays[trace_idx]

+            x_arr = self.data.x_arrays[trace_idx]

+

+            logger.debug(f"Input data: t_arr len={len(t_arr)}, x_arr len={len(x_arr)}")

+

+            try:

+                t_raw, x_new, x_min, x_max = self.decimator.decimate_for_view(

+                    t_arr,

+                    x_arr,

+                    view_params["xlim_raw"],

+                    self.max_plot_points,

+                    view_params["use_envelope"],

+                    trace_idx,  # Pass trace_id to use pre-decimated data

+                    envelope_window_samples=None,  # Envelope window calculated automatically

+                    mode_switch_threshold=self.mode_switch_threshold,  # Pass mode switch threshold

+                    return_envelope_min_max=True,  # Main signal always returns envelope min/max if use_envelope is True

+                )

+

+                logger.debug(

+                    f"Decimated data: t_raw len={len(t_raw)}, x_new len={len(x_new)}"

+                )

+                logger.debug(

+                    f"Envelope data: x_min={'None' if x_min is None else f'len={len(x_min)}'}, x_max={'None' if x_max is None else f'len={len(x_max)}'}"

+                )

+

+                if len(t_raw) == 0:

+                    logger.warning(

+                        f"No data in current view for trace {trace_idx}. View range: {view_params['xlim_raw']}"

+                    )

+                    # Add empty arrays for this trace

+                    plot_data[f"t_display_{trace_idx}"] = np.array([], dtype=np.float32)

+                    plot_data[f"x_new_{trace_idx}"] = np.array([], dtype=np.float32)

+                    plot_data[f"x_min_{trace_idx}"] = None

+                    plot_data[f"x_max_{trace_idx}"] = None

+                    continue

+

+                t_display = self.coord_manager.raw_to_display(t_raw)

+                logger.debug(

+                    f"Converted to display coordinates: t_display range=[{np.min(t_display):.6f}, {np.max(t_display):.6f}]"

+                )

+

+                # Store data for this trace

+                plot_data[f"t_display_{trace_idx}"] = t_display

+                plot_data[f"x_new_{trace_idx}"] = x_new

+                plot_data[f"x_min_{trace_idx}"] = x_min

+                plot_data[f"x_max_{trace_idx}"] = x_max

+

+                logger.debug(f"Stored plot data for trace {trace_idx}")

+            except Exception as e:

+                logger.exception(f"Error getting plot data for trace {trace_idx}: {e}")

+                # Add empty arrays for this trace to prevent further errors

+                plot_data[f"t_display_{trace_idx}"] = np.array([], dtype=np.float32)

+                plot_data[f"x_new_{trace_idx}"] = np.array([], dtype=np.float32)

+                plot_data[f"x_min_{trace_idx}"] = None

+                plot_data[f"x_max_{trace_idx}"] = None

+

+        logger.debug(f"Final plot_data keys: {list(plot_data.keys())}")

+        return plot_data

+

+    def _render_plot_elements(

+        self, plot_data: Dict[str, Any], view_params: Dict[str, Any]

+    ) -> None:

+        """Render all plot elements with current data."""

+        logger.debug(f"=== _render_plot_elements ===")

+        logger.debug(f"view_params use_envelope: {view_params['use_envelope']}")

+

+        # Store the current plot data for use by other methods

+        self._current_plot_data = plot_data

+

+        # Check if we have any data to plot

+        has_data = False

+        data_summary = {}

+        for trace_idx in range(self.data.num_traces):

+            key = f"t_display_{trace_idx}"

+            if key in plot_data and len(plot_data[key]) > 0:

+                has_data = True

+                data_summary[f"trace_{trace_idx}"] = len(plot_data[key])

+            else:

+                data_summary[f"trace_{trace_idx}"] = 0

+

+        logger.debug(f"Data summary: {data_summary}, has_data: {has_data}")

+

+        if not has_data:

+            logger.warning("No data to plot, clearing all elements")

+            # If no data, clear all lines and return

+            for i in range(self.data.num_traces):

+                self._signal_lines[i].set_data([], [])

+                if self._envelope_fills[i] is not None:

+                    self._envelope_fills[i].remove()

+                    self._envelope_fills[i] = None

+

+                # Clear custom elements

+                self._clear_custom_elements(i)

+

+            self.ax.set_ylim(0, 1)  # Set a default y-limit

+            return

+

+        # Process each trace

+        for trace_idx in range(self.data.num_traces):

+            logger.debug(f"--- Rendering trace {trace_idx} ---")

+            t_display_key = f"t_display_{trace_idx}"

+            x_new_key = f"x_new_{trace_idx}"

+            x_min_key = f"x_min_{trace_idx}"

+            x_max_key = f"x_max_{trace_idx}"

+

+            if t_display_key not in plot_data or len(plot_data[t_display_key]) == 0:

+                logger.debug(f"No data for trace {trace_idx}, hiding elements")

+                # No data for this trace, hide its elements

+                self._signal_lines[trace_idx].set_data([], [])

+                if self._envelope_fills[trace_idx] is not None:

+                    self._envelope_fills[trace_idx].remove()

+                    self._envelope_fills[trace_idx] = None

+

+                # Clear custom elements

+                self._clear_custom_elements(trace_idx)

+                continue

+

+            # Update signal display

+            envelope_data = None

+            if (

+                view_params["use_envelope"]

+                and x_min_key in plot_data

+                and x_max_key in plot_data

+            ):

+                if (

+                    plot_data[x_min_key] is not None

+                    and plot_data[x_max_key] is not None

+                ):

+                    envelope_data = (plot_data[x_min_key], plot_data[x_max_key])

+                    logger.debug(f"Using envelope data for trace {trace_idx}")

+                else:

+                    logger.debug(

+                        f"Envelope mode requested but no envelope data for trace {trace_idx}"

+                    )

+            else:

+                logger.debug(f"Detail mode for trace {trace_idx}")

+

+            self._update_signal_display(

+                trace_idx, plot_data[t_display_key], plot_data[x_new_key], envelope_data

+            )

+

+        # Update y-limits

+        logger.debug("Updating y-limits")

+        self._update_y_limits(plot_data, view_params["use_envelope"])

+

+    def _update_coordinate_system(

+        self, xlim_raw: Tuple[np.float32, np.float32], time_span_raw: np.float32

+    ) -> None:

+        """Update coordinate system and axis formatting."""

+        self._clear_region_fills()

+        self._update_axis_formatting()

+        self._update_tick_locator(time_span_raw)

+

+        xlim_display = self.coord_manager.xlim_raw_to_display(xlim_raw)

+        self.ax.set_xlim(xlim_display)

+

+        self._clear_navigation_history()

+        self._push_current_view()

+

+    def _update_regions_and_legend(

+        self, xlim_display: Tuple[np.float32, np.float32]

+    ) -> None:

+        """Update regions and legend."""

+        self._refresh_region_display(xlim_display)

+        self._update_legend()

+

+    def _refresh_region_display(

+        self, xlim_display: Tuple[np.float32, np.float32]

+    ) -> None:

+        """Refresh region display for current view."""

+        logger.debug(f"=== _refresh_region_display ===")

+        self._clear_region_fills()

+

+        # Get current mode

+        current_mode = (

+            self.MODE_ENVELOPE

+            if self.state.current_mode == "envelope"

+            else self.MODE_DETAIL

+        )

+        logger.debug(f"Current display mode for regions: {current_mode}")

+

+        for trace_idx in range(self.data.num_traces):

+            logger.debug(f"Processing regions for trace {trace_idx}")

+            # Process each region definition

+            for region_def in self._regions[trace_idx]:

+                logger.debug(

+                    f"Region '{region_def['label']}': display_mode={region_def['display_mode']}, current_mode={current_mode}"

+                )

+                # Skip if not visible in current mode

+                if not (region_def["display_mode"] & current_mode):

+                    logger.debug(

+                        f"Region '{region_def['label']}' not visible in current mode {current_mode}, skipping."

+                    )

+                    continue

+

+                regions = region_def["regions"]

+                if regions is None or len(regions) == 0:

+                    logger.debug(

+                        f"No regions data for '{region_def['label']}', skipping."

+                    )

+                    continue

+

+                logger.debug(

+                    f"Displaying {len(regions)} regions for '{region_def['label']}' in mode {current_mode}"

+                )

+

+                color = region_def["color"]

+                label = region_def["label"]

+                alpha = region_def["alpha"]

+                first_visible_region = True

+

+                for t_start, t_end in regions:

+                    t_start_display = self.coord_manager.raw_to_display(t_start)

+                    t_end_display = self.coord_manager.raw_to_display(t_end)

+

+                    # Check if region overlaps with current view

+                    if not (

+                        t_end_display <= xlim_display[0]

+                        or t_start_display >= xlim_display[1]

+                    ):

+                        # Only show label for first visible region

+                        current_label = label if first_visible_region else ""

+                        if first_visible_region and len(regions) > 1:

+                            current_label = f"{label} ({len(regions)})"

+

+                        logger.debug(

+                            f"Adding region span from {t_start_display:.6f} to {t_end_display:.6f} (raw: {t_start:.6f} to {t_end:.6f}) for '{label}'"

+                        )

+                        fill = self.ax.axvspan(

+                            t_start_display,

+                            t_end_display,

+                            alpha=alpha,

+                            color=color,

+                            linewidth=0.5,

+                            label=current_label,

+                            zorder=region_def["zorder"],

+                        )

+                        self._region_objects[trace_idx].append((fill, region_def))

+                        first_visible_region = False

+                    else:

+                        logger.debug(

+                            f"Region span from {t_start_display:.6f} to {t_end_display:.6f} (raw: {t_start:.6f} to {t_end:.6f}) for '{label}' is outside current view {xlim_display}, skipping."

+                        )

+

+    def _clear_region_fills(self) -> None:

+        """Clear all region fills."""

+        logger.debug("Clearing region fills.")

+        for trace_fills in self._region_objects:

+            for fill_item in trace_fills:

+                # Handle both old format (just fill object) and new format (tuple)

+                if isinstance(fill_item, tuple):

+                    fill, _ = fill_item  # Extract the fill object from the tuple

+                    fill.remove()

+                else:

+                    fill_item.remove()  # Old format - direct fill object

+            trace_fills.clear()

+        logger.debug("Region fills cleared.")

+

+    def _setup_plot_elements(self) -> None:

+        """

+        Initialise matplotlib plot elements (lines, fills) for each trace.

+        This is called once during render().

+        """

+        if self.fig is None or self.ax is None:

+            raise RuntimeError(

+                "Figure and Axes must be created before setting up plot elements."

+            )

+

+        # Create initial signal line objects for each trace

+        for i in range(self.data.num_traces):

+            color = self.data.get_trace_color(i)

+            name = self.data.get_trace_name(i)

+

+            # Signal line

+            (line_signal,) = self.ax.plot(

+                [],

+                [],

+                label="Raw data" if self.data.num_traces == 1 else f"Raw data ({name})",

+                color=color,

+                alpha=self.signal_alpha,

+            )

+            self._signal_lines.append(line_signal)

+

+    def _connect_callbacks(self) -> None:

+        """Connect matplotlib callbacks."""

+        if self.ax is None:

+            raise RuntimeError("Axes must be created before connecting callbacks.")

+        self.ax.callbacks.connect("xlim_changed", self._update_plot_data)

+

+    def _setup_toolbar_overrides(self) -> None:

+        """Override matplotlib toolbar methods (e.g., home button)."""

+        if (

+            self.fig

+            and self.fig.canvas

+            and hasattr(self.fig.canvas, "toolbar")

+            and self.fig.canvas.toolbar

+        ):

+            toolbar = self.fig.canvas.toolbar

+

+            # Store original methods

+            self._original_home = getattr(toolbar, "home", None)

+            self._original_push_current = getattr(toolbar, "push_current", None)

+

+            # Create our custom home method

+            def custom_home(*args, **kwargs):

+                logger.debug("Toolbar home button pressed - calling custom home")

+                self.home()

+

+            # Override both the method and try to find the actual button

+            toolbar.home = custom_home

+

+            # For Qt backend, also override the action

+            if hasattr(toolbar, "actions"):

+                for action in toolbar.actions():

+                    if hasattr(action, "text") and hasattr(action, "objectName"):

+                        action_text = (

+                            action.text() if callable(action.text) else str(action.text)

+                        )

+                        action_name = (

+                            action.objectName()

+                            if callable(action.objectName)

+                            else str(action.objectName)

+                        )

+                        if action_text == "Home" or "home" in action_name.lower():

+                            if hasattr(action, "triggered"):

+                                action.triggered.disconnect()

+                                action.triggered.connect(custom_home)

+                                logger.debug("Connected custom home to Qt action")

+                                break

+

+            # For other backends, try to override the button callback

+            if hasattr(toolbar, "_buttons") and "Home" in toolbar._buttons:

+                home_button = toolbar._buttons["Home"]

+                if hasattr(home_button, "configure"):

+                    home_button.configure(command=custom_home)

+                    logger.debug("Connected custom home to Tkinter button")

+

+    def _set_initial_view_and_labels(self) -> None:

+        """Set initial axis limits, title, and labels."""

+        if self.ax is None:

+            raise RuntimeError(

+                "Axes must be created before setting initial view and labels."

+            )

+

+        # Create title based on number of traces

+        if self.data.num_traces == 1:

+            self.ax.set_title(f"{self.data.names[0]}")

+        else:

+            # Multiple traces - just show "Multiple Traces"

+            self.ax.set_title(f"Multiple Traces ({self.data.num_traces})")

+        self.ax.set_xlabel(f"Time ({self.state.current_time_unit})")

+        self.ax.set_ylabel("Signal")

+

+        # Set initial xlim

+        initial_xlim_display = self.coord_manager.xlim_raw_to_display(

+            self._initial_xlim_raw

+        )

+        self.ax.set_xlim(initial_xlim_display)

+

+    def render(self) -> None:

+        """

+        Renders the oscilloscope plot. This method must be called after all

+        data and visualization elements have been added.

+        """

+        if self.fig is not None or self.ax is not None:

+            logger.warning(

+                "Plot already rendered. Call `home()` to reset or create a new instance."

+            )

+            return

+

+        logger.info("Rendering plot...")

+        self.fig, self.ax = plt.subplots(figsize=(10, 5))

+

+        self._setup_plot_elements()

+        self._connect_callbacks()

+        self._setup_toolbar_overrides()

+        self._set_initial_view_and_labels()

+

+        # Calculate initial parameters for the full view

+        t_start, t_end = self.data.get_global_time_range()

+        full_time_span = t_end - t_start

+

+        logger.info(

+            f"Initial render: full time span={full_time_span:.3e}s, envelope_limit={self.mode_switch_threshold:.3e}s"

+        )

+

+        # Set initial display state based on full view

+        self.state.current_time_unit, self.state.current_time_scale = (

+            _get_optimal_time_unit_and_scale(full_time_span)

+        )

+        self.state.current_mode = (

+            "envelope" if self.state.should_use_envelope(full_time_span) else "detail"

+        )

+

+        # Force initial draw of all elements by calling _update_plot_data

+        # This will also update the legend and regions

+        self.state.set_updating(False)  # Ensure not in updating state for first call

+        self._update_plot_data(self.ax)

+        self.fig.canvas.draw_idle()

+        logger.info("Plot rendering complete.")

+

+    def home(self) -> None:

+        """Return to initial full view with complete state reset."""

+        if self.ax is None:  # Fix: Changed '===' to 'is'

+            logger.warning("Plot not rendered yet. Cannot go home.")

+            return

+

+        # Disconnect callback temporarily

+        callback_id = None

+        for cid, callback in self.ax.callbacks.callbacks["xlim_changed"].items():

+            if getattr(callback, "__func__", callback) == self._update_plot_data:

+                callback_id = cid

+                break

+

+        if callback_id is not None:

+            self.ax.callbacks.disconnect(callback_id)

+

+        try:

+            self.state.set_updating(True)

+            self.state.reset_to_initial_state()

+            self.decimator.clear_cache()

+            self._clear_region_fills()

+

+            # Clear all custom elements and reset _last_mode for each trace to force redraw

+            for trace_idx in range(self.data.num_traces):

+                self._clear_custom_elements(trace_idx)

+                self._last_mode[trace_idx] = None

+

+            # Reset axis formatting

+            self.ax.set_xlabel(f"Time ({self.state.original_time_unit})")

+            self.ax.xaxis.set_major_formatter(mpl.ticker.ScalarFormatter())

+            self.ax.xaxis.set_major_locator(mpl.ticker.AutoLocator())

+

+            # Reset view

+            self.coord_manager.set_view_raw(self.ax, self._initial_xlim_raw)

+

+            # Manually trigger update for the home view

+            # This will re-evaluate use_envelope, current_mode, and redraw everything

+            self._update_plot_data(self.ax)

+

+            self.state.set_updating(False)

+

+        finally:

+            self.ax.callbacks.connect("xlim_changed", self._update_plot_data)

+

+        self.fig.canvas.draw()

+        logger.info(f"Home view restored: {self.state.original_time_unit} scale")

+

+    def refresh(self) -> None:

+        """Force a complete refresh of the plot without changing the current view."""

+        if self.ax is None:

+            logger.warning("Plot not rendered yet. Cannot refresh.")

+            return

+

+        # Temporarily bypass the updating state for forced refresh

+        was_updating = self.state.is_updating()

+        self.state.set_updating(False)

+        try:

+            self._update_plot_data(self.ax)

+        finally:

+            self.state.set_updating(was_updating)

+        self.fig.canvas.draw_idle()

+

+    def show(self) -> None:

+        """Display the plot."""

+        if self.fig is None:

+            self.render()  # Render if not already rendered

+        plt.show()