Deploy ChessTB Explorer on Hugging Face Spaces

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.gitignore
+.github
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.coverage
+htmlcov
+.vscode
+.idea
+.DS_Store
+Thumbs.db
+frontend/node_modules

.gitattributes

@@ -0,0 +1,53 @@
+# ChessTB Explorer: line-ending / diff attributes
+#
+# Every text file in this repo is normalized to LF, regardless of the
+# committer's or cloner's platform or local `core.autocrlf` setting - the
+# app is meant to run identically on Windows/Linux/macOS, and mixed line
+# endings across files (or within one file after a Windows edit) cause
+# noisy whole-file diffs and spurious merge conflicts for no functional
+# reason. Binary assets are marked explicitly so Git never attempts text
+# normalization or diffing on them.
+
+# Fallback: let Git auto-detect text vs binary for anything not matched
+# below, and normalize any text file's line endings to LF in the
+# repository (working-tree endings still follow core.autocrlf locally).
+* text=auto eol=lf
+
+# --- Source / config / docs - force LF explicitly -------------------------
+*.py       text eol=lf
+*.js       text eol=lf
+*.mjs      text eol=lf
+*.css      text eol=lf
+*.html     text eol=lf
+*.md       text eol=lf
+*.yml      text eol=lf
+*.yaml     text eol=lf
+*.txt      text eol=lf
+*.json     text eol=lf
+*.svg      text eol=lf
+.gitignore     text eol=lf
+.gitattributes text eol=lf
+LICENSE        text eol=lf
+
+# --- Binary assets - never touch, never diff as text -----------------------
+*.png    binary
+*.jpg    binary
+*.jpeg   binary
+*.woff2  binary
+*.woff   binary
+*.ttf    binary
+*.ico    binary
+
+# --- Vendored third-party code - exclude from GitHub's language stats and
+# from generated-diff/review noise; these files are never hand-edited here,
+# treated as vendored files and excluded from generated-diff noise.
+# See THIRD_PARTY_LICENSES.md for what's vendored and why.
+frontend/src/vendor/** linguist-vendored
+frontend/src/assets/fonts/** linguist-vendored
+
+# --- Generated build output - not hand-edited; excluded from language
+# stats and review diffs. static/dist/ is rebuilt from frontend/src/
+# by `vite build` (see README.md's "Frontend build"); package-lock.json is
+# written by npm.
+static/dist/** linguist-generated
+frontend/package-lock.json linguist-generated

.gitignore

@@ -0,0 +1,21 @@
+# Local environment files: this project doesn't use one (config.py reads
+# its two secrets, ADMIN_TOKEN and FLASK_SECRET_KEY, directly from the
+# process environment rather than a .env file - see config.py's "Admin"
+# section), but this stays as a no-cost safety net in case one is ever
+# added locally.
+.env
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,41 @@
+FROM python:3.11-slim
+
+# Git is required because requirements.txt installs
+# noobpwnftw/python-chess directly from GitHub.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Run as a non-root user rather than the image's default root. UID 1000 has
+# no special meaning to Render (it just needs to own /app below); it
+# matches Hugging Face Docker Spaces' convention, so the same image also
+# runs there.
+RUN useradd -m -u 1000 user
+
+WORKDIR /app
+
+# Install Python dependencies first so Docker can cache this layer.
+COPY --chown=user requirements.txt /app/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r /app/requirements.txt
+
+# Copy the actual application.
+COPY --chown=user . /app
+
+USER user
+
+ENV HOME=/home/user
+ENV PATH=/home/user/.local/bin:$PATH
+ENV PYTHONUNBUFFERED=1
+
+# Purely informational -- config.py's PORT reads the platform's own PORT
+# environment variable at runtime (falling back to 7860 only when it's
+# unset) and that's the port actually bound, regardless of this EXPOSE
+# value. Render assigns and injects PORT itself (see render.yaml /
+# README.md "Deploying to Render"), so nothing needs to change here to
+# match it; 7860 is the default for a local `docker run` with no PORT set,
+# and for Hugging Face Docker Spaces, which expects 7860 specifically.
+EXPOSE 7860
+
+CMD ["python", "app.py"]

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>.

README.md

@@ -0,0 +1,937 @@
+---
+title: ChessTB Explorer
+emoji: ♟️
+colorFrom: green
+colorTo: blue
+sdk: docker
+pinned: true
+app_port: 7860
+license: gpl-3.0
+short_description: "Interactive tablebase probing: WDL/DTZ/DTC/DTM/DTM50"
+---
+
+# ChessTB Explorer ♟️
+
+Interactive tablebase probing interface with WDL/DTZ/DTC/DTM/DTM50 metrics.
+
+This Hugging Face Space is deployed from
+[PunisherChess/ChessTB-Explorer-Render](https://github.com/PunisherChess/ChessTB-Explorer-Render)
+at commit `4969e401fa41ef1b86458cac4b6a31f9b11e08d0`.
+The original authors' license and third-party notices are retained.
+
+The application probes the public `chesstb/chesstb` bucket over HTTP byte
+ranges, using the explorer's existing bounded page cache. Sources are
+searched per table with raw generator output under `full/` preferred over
+shipping tables at the bucket root. Castling materials use `full/castling/`
+and `castling/`, respectively.
+Availability of each metric depends on the published tables for that material.
+
+`ADMIN_TOKEN` and `FLASK_SECRET_KEY` are configured as Space secrets.
+The probing library follows the maintained `add-chesstb-tablebases` branch
+of `noobpwnftw/python-chess`.
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://chesstb-explorer-render.onrender.com)
+
+A single-page web application for exploring **ChessTB** chess endgame
+tablebases. Paste or build any position on an interactive board and
+instantly see every legal move ranked by **Distance to Zeroing (DTZ)**,
+**Distance to Conversion (DTC)**, **Distance to Mate (DTM)**, and **DTM
+under the 50-move rule (DTM50)** - straight from the tablebase, with no
+chess engine involved.
+
+The backend is a small Flask application that probes the tablebase through
+a modified fork of [`python-chess`](https://github.com/noobpwnftw/python-chess/tree/add-chesstb-tablebases)
+(the `chess.chesstb` module - see [Installation](#installation)). The frontend is
+a React app built around
+[Chessground](https://github.com/lichess-org/chessground) (lichess.org's
+board component) and [chessops](https://github.com/niklasf/chessops) for
+move generation/validation, supporting both Standard chess and Chess960
+(Fischer Random).
+
+> This tool only *displays* tablebase results - it does not generate,
+> verify, or ship any tablebase data itself. See
+> [Getting the tablebase files](#getting-the-tablebase-files) below.
+
+> The probe endpoints are unauthenticated by design - evaluating a
+> position is this app's public functionality. The `/admin` cache
+> dashboard is gated behind `ADMIN_TOKEN`, a secret configured by the deployment
+> (see [Security notes](#security-notes)).
+
+---
+
+## Features
+
+- **Interactive board**: drag-and-drop moves, click-to-place pieces from
+  the spare-piece trays, pawn promotion dialog, board flip (orientation
+  persisted locally across visits), undo/redo.
+- **Chess960 (Fischer Random) support**: a **Chess960 Mode** switch in
+  the settings panel changes castling interpretation without altering the
+  current board position: dragging a king onto its own rook castles the
+  Chess960 way, and X-FEN/Shredder-FEN rook-file castling-rights letters
+  (e.g. `HAha`) are accepted in the FEN box. Carried through the shared
+  URL (`&variant=chess960`), the saved in-progress game, and PGN
+  import/export (`[Variant "Chess960"]`). Off by default.
+- **Lock**: a padlock button beside the FEN box that restricts board
+  interaction to legal moves only: dragging, click-to-move, and the
+  spare-piece trays are limited to the side to move's legal destinations,
+  and off-board drops are disabled. Unlocked by default; a manual toggle
+  is remembered locally across visits. Auto-play also engages Lock for
+  the duration of a run (unless already locked by hand), and disables the
+  padlock button until the run stops.
+- **Four ranked move tables side by side**: DTZ, DTC, DTM, and DTM50
+  columns, each independently sorted best-move-first. Exact metric ties
+  prefer immediate checkmate, then use SAN order with promotions along
+  the same path ordered queen, rook, bishop, knight. A better-scoring
+  underpromotion still ranks first. Includes:
+  - score text colour-coded by outcome (win / cursed win / draw /
+    blessed loss / loss)
+  - a **warning dot** on any move flagged cursed win or blessed loss,
+    with a hover tooltip explaining the 50-move-rule nuance; a DTZ score
+    that may still be a ply off after the moves are cross-checked shows a
+    second tooltip line
+  - an **info dot** on a draw by insufficient material, keeping the score
+    text itself reading as a plain "Draw"
+  - dot messages on touch or pen input: tapping a dot shows its tooltip
+    text as a notice and does not play the move
+  - an outcome summary (wins / draws / losses / unknown) across legal moves,
+    respecting the halfmove clock and 50-move rule. It uses DTM50 outcomes,
+    or DTC when DTM50 is unavailable. Without either, clock-independent
+    draws, cursed wins and blessed losses count as draws; unresolved
+    wins/losses count as unknown.
+  - an optional pinned **Root Row** above rank 1, showing the current
+    position's own score for each metric as a reference point - toggled
+    from the settings panel (**Show Root Row**, off by default) and
+    persisted locally
+- **Best-move arrows**: the top DTZ, DTC, DTM, and DTM50 moves are drawn
+  as colour-coded arrows directly on the board.
+- **Auto-play**: automatically plays the best move for any of the four
+  metrics on a timer. The per-move delay
+  is set from the settings panel (**Autoplay Delay**, 0s–2.5s in 50ms
+  steps, 1.25s by default). The countdown starts after the current
+  position's tablebase results are displayed, giving you the full delay
+  to read them before the next move. A metric's button is disabled when its
+  table isn't present for the current material, or when the position is
+  already a draw.
+- **PGN import/export**: paste a PGN to load its full move tree, including
+  variations, at the starting position. Step through it or click any move
+  in the PGN panel, or download the current game as a PGN file.
+- **CSV export** of the current move table, including the Root Row line
+  ahead of rank 1 when that setting is on.
+- **Move-list / PGN panel** with full undo/redo and click-to-jump - jumping
+  to an earlier point in the line re-uses the cached probe instead of
+  re-querying the tablebase.
+- **Shareable positions**: the FEN (and, in Chess960 Mode, the active
+  variant) is written to the URL hash on every move, so a link to the
+  page reproduces the exact position and ruleset.
+- **Session persistence**: the in-progress game (not just the position)
+  survives a trip to the admin dashboard and back.
+- **Board and piece set**: Libre Brown board, CBurnett piece set.
+- **Streaming probes**: `/probe/stream` reports progress via
+  Server-Sent Events while child positions are being probed, so the UI
+  shows a live progress bar instead of a blank pause on slower lookups.
+- **Hover pre-fetch**: hovering a move in the table warms the cache for
+  the resulting position before selection.
+- **Admin cache dashboard** (`/admin`, behind `ADMIN_TOKEN`) - live
+  hit-rate stats for both LRU caches, thread-pool configuration, and a
+  one-click cache-clear button.
+- **Machine-readable API**: the full HTTP API is described by an OpenAPI
+  3.0 document served at `/openapi.yaml`.
+- **Keyboard shortcuts**: `Enter` Apply, `F` Flip, `C` Clear, `←`/`→`
+  Back/Forward. The Board Settings panel lists them on devices with hover.
+
+---
+
+## Architecture at a glance
+
+```
+Browser (React app - see frontend/)
+  ├─ engine/board.js      - chessops-backed position/rules state, chessground
+  │                           wrapper (drag/drop, history, arrows), active variant
+  ├─ engine/tablebase.js  - talks to /probe/stream, exposes results as state
+  ├─ engine/theme.js      - board/piece-set theming
+  ├─ hooks/useExplorer.js - FEN box, PGN, auto-play, settings, keyboard shortcuts
+  └─ components/          - the rendered page (board, results table, PGN panel, dialogs)
+        │  HTTP (JSON) / SSE (text/event-stream) - {fen, variant}
+        ▼
+Flask app (app.py)
+  ├─ /probe, /probe/stream   - evaluate a FEN under a variant, rank every legal move
+  ├─ /admin, /admin/cache/*  - cache dashboard + stats API
+  └─ /openapi.yaml           - API specification
+        │
+        ▼
+tablebase_router.py - searches TABLEBASE_PATH in order for every material,
+including castling positions and recursive dependencies
+        │
+        ▼
+chesstb.open_tablebase(...) per source   (noobpwnftw's modified python-chess fork)
+        │
+        ▼
+ChessTB tablebase files - local disk, or a remote http(s) URL (probed
+in place over byte ranges by default, or downloaded and cached to local
+disk per material - see remote/remote_direct.py, remote/remote_fallback.py,
+and "Getting the tablebase files" below)
+```
+
+The React app is built with Vite into `static/dist/` (`app.js`,
+`app.css`), which the Flask template loads as same-origin assets, as the
+Content-Security-Policy (`script-src 'self'`) requires. See
+[Frontend build](#frontend-build) below.
+
+This covers the main explorer page's (`index.html`) module graph - see
+[Project structure](#project-structure) below for the complete file set,
+including `admin.js` (the `/admin` dashboard's client script, a plain
+server-rendered page with no build step).
+
+The Python modules and the frontend `engine/` modules carry a file-level
+docstring/header comment describing their responsibilities, and the
+move-ranking algorithm itself - including
+its treatment of the 50-move rule - is documented inline in `app.py`
+above `evaluate_all_moves()` and the `_effective_move_wdl`/
+`_effective_distance`/`_order_rank` helpers it calls.
+
+---
+
+## Frontend build
+
+The explorer page is a React app (`frontend/`) built with Vite into
+`static/dist/`, which the Flask app serves alongside its own
+static assets. The build output is checked in, so running the app needs
+no frontend server or build step. Rebuild after changing anything under
+`frontend/src/`:
+
+```bash
+cd frontend
+npm ci
+npm run build      # writes static/dist/app.js, app.css, admin.css, fonts/
+```
+
+`frontend/src/engine/` and `frontend/src/vendor/` hold the position/rules
+engine (chessops + Chessground) and the tablebase client, consumed by
+the React components in `frontend/src/components/`. Shared UI primitives
+(`Icon`, `Button`, `Segmented`, `Panel`) are in `frontend/src/components/ui/`.
+Piece SVGs and the piece-set stylesheet are in `static/` and are linked
+directly from the page template.
+
+### Styling
+
+Stylesheets are in `frontend/src/styles/` and are bundled by Vite into
+`static/dist/app.css` (explorer page) and `static/dist/admin.css` (`/admin`).
+`tokens.css` defines the colour, type, spacing, radius, elevation, motion,
+and control-size custom properties; other files reference them instead of
+literal values. Files are imported into the `reset`, `vendor`, and `app`
+cascade layers by `index.css` and `admin.css`.
+
+| Token group | Custom properties |
+|---|---|
+| Type scale | `--text-xs` 12 px, `--text-sm` 13 px, `--text-md` 14 px, `--text-lg` 16 px, `--text-xl` 20 px |
+| Spacing | `--space-1` to `--space-6` (4 px to 32 px) |
+| Controls | `--control-h`, `--control-h-sm` (44 px on touch-primary devices) |
+| Board | `--board-light`, `--board-dark`, `--board-highlight`, read by `engine/theme.js` |
+
+Sizes are authored in `rem`, so the large-screen root font size scaling
+applies to all text and controls.
+
+### Page layout
+
+| Viewport | Layout |
+|---|---|
+| Above 1180 px | Three-column CSS grid (board, results, PGN). The results and PGN columns take the board column's height and scroll internally. |
+| 768 to 1180 px | Board row above a results and PGN row; the page scrolls. |
+| Below 768 px | Three horizontally swipeable screens (board, results, PGN) with a bottom navigation bar (`ScreenNav`). Header and navigation heights include the device safe-area insets, and screen heights use `dvh`. The header shows the subtitle below the title, and the board is sized to the visible height so the whole board screen fits. |
+
+The side-to-move toggle and the board form one group (`.board-group`) as wide
+as the board, with a fixed small gap between them at every screen size. Free
+vertical space in the board column sits above the group.
+
+The results panel is a `results` size container. At 49 rem wide and above it
+shows the four metric columns; below that it shows one metric at a time,
+selected with the metric tabs, regardless of viewport width. The desktop
+layout reserves 50 rem for this panel before growing the board, so the
+four-metric view can appear as soon as the three columns fit. The results
+table is a fixed header table above a scrolling body table, so the scrollbar
+starts at the first moves row. The body reserves no scrollbar gutter: while
+its rows overflow, its table is widened by the scrollbar's measured width, so
+columns keep the header's position and width whether or not a scrollbar shows.
+The PGN move-number column width is set by `--pgn-rank-w` in `tokens.css`.
+
+### Display scaling
+
+Sizing is CSS-only and is defined in `frontend/src/styles/layout.css`.
+
+- **Text:** above 1180 px, the root font size of the explorer page
+  (`html.explorer`) is 100% of the browser default up to a 1536 x 780 window
+  and rises to at most 125% (20 px), following the window's width and
+  height. Browser zoom and the browser default font size apply.
+- **Board:** above 1180 px, `--board-size` fills the window height in
+  multiples of 8 px, from 20.5 rem up to `--board-size-max` (720 px, defined
+  in `tokens.css`), and leaves at least 40 rem for the results table. The
+  left column is as wide as the board, so it is capped at 720 px as well.
+  The width the board column does not use goes to the results column, so
+  the total content width stays constant.
+- **Tablet layout:** at 1180 px and below, the root font size is the
+  browser default and `--board-size` is `--board-size-cap`, defined in
+  `tokens.css` as
+  `min(720px, clamp(18.75rem, min(23.4375vw, 41.6667vh), 31.5rem))`.
+- **Phone layout:** below 768 px, `--board-size` is the smaller of
+  `--board-size-cap` (`min(360px, 88vw)` up to 480 px wide) and the height
+  that remains after the header, bottom navigation, and the controls
+  above the board, with a floor of 14 rem. The board screen therefore
+  fits the visible height regardless of browser toolbar size. Below the
+  floor, the screen scrolls from its top.
+- `--board-fit-h` includes the fixed height above the board in the left
+  column and requires an update when that height changes. This applies to
+  both the desktop definition in `layout.css` and the phone definition in
+  `responsive.css`.
+- `html.explorer` is set in `templates/index.html` and `frontend/index.html`.
+  `/admin` does not use it.
+
+---
+
+## Prerequisites
+
+- **Python 3.10+**
+- **Git**, available on `PATH` - `pip install -r requirements.txt` fetches the
+  `python-chess` fork directly from GitHub (`chess @ git+https://...`),
+  which requires `git` to be installed even though the package itself is
+  Python.
+- **A ChessTB tablebase directory or URL**: either a local directory on
+  disk, or an `http(s)://` base URL serving the same layout remotely with
+  no local download (see [Getting the tablebase files](#getting-the-tablebase-files)).
+  The app starts without one, but every probe will fail until
+  `TABLEBASE_PATH` points at the required sources. See
+  [Configuration reference](#configuration-reference).
+- A modern browser (the frontend uses `fetch`, `ReadableStream`, and CSS
+  container queries).
+
+---
+
+## Installation
+
+1. **Create and activate a virtual environment:**
+
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate      # Windows: .venv\Scripts\activate
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+   This pulls in the **modified `python-chess` fork** (not the plain
+   PyPI `chess` package; see the comments in `requirements.txt` for why
+   that distinction matters).
+
+3. **Get the tablebase files**: see the next section. When using the
+   remote (no-download) option requires no fetch; continue to step 4 and
+   point `TABLEBASE_PATH` at the URL.
+
+4. **Configure `config.py`**: open it and set `TABLEBASE_PATH` to the
+   directory (or URL) from step 3:
+
+   ```python
+   TABLEBASE_PATH = "/data/chesstb"
+   ```
+
+   or, for the remote option:
+
+   ```python
+   TABLEBASE_PATH = "https://huggingface.co/buckets/chesstb/chesstb/resolve"
+   ```
+
+   This alone covers every piece count. See
+   [Getting the tablebase files](#getting-the-tablebase-files) for
+   the ordered source list, which includes shipping tables for both ordinary
+   and castling materials.
+
+   Every other setting in `config.py` has a default and a comment
+   explaining what it does - see
+   [Configuration reference](#configuration-reference) for the complete
+   list. Edit the values directly. To enable the header's source repository button,
+   set `SOURCE_REPOSITORY_URL` there too.
+
+5. **Run the app:**
+
+   ```bash
+   python app.py
+   ```
+
+   By default (`DEBUG = False` in `config.py`) this serves the app via
+   **waitress**, a production-grade pure-Python WSGI server - see
+   [Running in production](#running-in-production) below. Set
+   `DEBUG = True` in `config.py` to use Flask's development server
+   (auto-reload, interactive debugger) for local development.
+
+6. Open **http://127.0.0.1:7860** in a browser.
+
+   The built frontend (`static/dist/`) is checked in; see
+   [Frontend build](#frontend-build) when changing `frontend/src/`.
+
+---
+
+## Getting the tablebase files
+
+Where the tablebase *data* lives is a separate question from where this
+*app* runs - Option A below points `TABLEBASE_PATH` at a plain
+`http(s)://` URL, so it works identically regardless of which platform
+serves the app itself (Render, Hugging Face Spaces, a local machine,
+etc.); `remote/remote_source.py` speaks plain HTTP byte-range requests,
+nothing more, and has no dependency on any one host. See
+[Deploying to Render](#deploying-to-render) for the app side of that
+distinction.
+
+ChessTB tablebase files are available two ways:
+
+### Option A: Remote, no local download (recommended)
+
+Tables are available in the [ChessTB bucket](https://huggingface.co/buckets/chesstb/chesstb).
+Shipping tables are grouped by metric; raw generator output is under `full/`.
+Both use `castling/` for tables with castling rights.
+WDL/DTZ cover 3–8 pieces; DTC/DTM/DTM50 cover 3–6 pieces.
+
+Set `TABLEBASE_PATH` to the bucket root:
+
+```python
+TABLEBASE_PATH = "https://huggingface.co/buckets/chesstb/chesstb/resolve"
+```
+
+The explorer prefers raw generator output under `full/`, falls back to
+shipping tables, and selects `castling/` paths automatically, including
+for recursive dependencies. This applies to Standard chess and Chess960.
+Local roots use the same layout. An explicit list of source directories
+is also supported.
+
+`REMOTE_MODE` selects the remote access mode, which stays fixed for the
+life of the process:
+
+- **`"direct"` (default)**: `remote/remote_direct.py` probes the remote
+  tables **in place**, fetching only the `REMOTE_PAGE_SIZE_BYTES`-sized
+  byte ranges each probe reads and keeping them in an in-memory
+  LRU bounded by `REMOTE_PAGE_CACHE_BYTES`. Nothing is written to disk.
+  This uses `chess.chesstb`'s table-source seam
+  (`Tablebase.WDL_FILE` / `_TableFile._open_source`), which the pinned
+  fork (see `requirements.txt`) provides.
+- **`"download"`**: `remote/remote_fallback.py` fetches each table
+  **in full** the first time a probe touches its material and caches it
+  in a temporary local directory (bounded by
+  `REMOTE_PAGE_CACHE_BYTES` as an on-disk budget, evicting
+  least-recently-used files, removed entirely when the app stops). Every
+  probe after the first is then a local mmap read.
+
+`"direct"` is the better default for browsing across many materials, which
+is what this app does. `"download"` is preferable when a long session
+repeatedly probes a small set of materials, or on a high-latency link: a
+ChessTB probe is not a narrow read - a dropped-frame table is reconstructed by walking
+its children, and pawn positions reach promotion sub-tables - so one cold
+probe can open several materials and issue several fetches against each.
+That is also why `REMOTE_PAGE_SIZE_BYTES` should stay large. See each
+module's docstring for the full design.
+
+Both remote modes cache successful signed CDN redirects until 60 seconds
+before expiry, allowing subsequent byte-range reads to bypass the resolver.
+A failed cached URL is retried through the original URL to obtain a fresh
+redirect. Resolver and CDN connection pools stay open for reuse.
+Complete cached responses are returned immediately by `/probe/stream`,
+without rebuilding the board or queuing child probes. Queued child work is
+cancelled when a stream disconnects or its pre-warm deadline expires;
+already running probes can finish and warm the shared cache.
+Table contents and paths are assumed to remain fixed; existence
+and size metadata stay cached for the process lifetime, including missing
+files. Restart the app after adding or moving tables.
+
+Remote access suits a machine without a couple of terabytes of local disk
+for the full tablebase set. Its costs are probe latency on first touch of
+any given material (depending on the connection to the CDN), temporary
+local disk usage in `"download"` mode, and the requirement of a network
+connection. Remote access uses the `requests` package (see
+`requirements.txt`).
+
+### Option B: Local directory, over FTP
+
+The same tables are also distributed over FTP for a fully local, offline
+setup:
+
+```
+ftp://chessdb:chessdb@ftp.chessdb.cn/pub/chesstb/
+```
+
+Any FTP client works, for example:
+
+```bash
+# lftp
+lftp -e "mirror --parallel=4 /pub/chesstb/ /data/chesstb; quit" \
+     ftp://chessdb:chessdb@ftp.chessdb.cn
+
+# curl (single file)
+curl "ftp://chessdb:chessdb@ftp.chessdb.cn/pub/chesstb/<path-to-file>" -o <local-file>
+```
+
+Tablebase sets are large and grow quickly with piece count - check
+available disk space before mirroring the full archive, and consider
+mirroring only the required subsets (piece counts). Point
+`TABLEBASE_PATH` at the selected directory.
+
+---
+
+Regardless of how it is configured, if `TABLEBASE_PATH` is unset, missing/unreachable, or
+points at a location with no usable tables, the app still starts (with a
+warning in the logs) - every `/probe` request will then return an error,
+and `/health` reports `"degraded"`.
+
+---
+
+## Configuration reference
+
+All configuration lives in **`config.py`**, as plain Python values. Open
+it and edit the settings directly - each one has a comment above it
+explaining what it does. The table below is the complete reference.
+
+The defaults target a single process on Hugging Face CPU Basic
+(2 vCPU, 16 GB RAM). The decoded-block cache has a shared 512 MiB
+budget, and each of the four default remote sources has a 2 GiB page
+cache budget, totaling 8.5 GiB of byte-cache budgets. Caches fill on
+demand; this is not a cap on process memory. Root-response and child-probe
+caches are limited by entry count, with memory use depending on response
+size. The remaining RAM accommodates those results, table/index metadata,
+Python object overhead, and active requests. Revisit the budgets if you
+add remote sources or run multiple application processes.
+
+| Setting                     | Default          | Description |
+|-----------------------------|-------------------|-------------|
+| `TABLEBASE_PATH`            | Public bucket root (also readable from a `TABLEBASE_PATH` env var) | Directory containing the ChessTB tablebase files, **or** an `http(s)://` base URL serving the same layout remotely (e.g. a Hugging Face storage bucket - see [Getting the tablebase files](#getting-the-tablebase-files)). Required for probing to work. A list of directories and URLs, tried left-to-right (a hybrid source), is accepted as a literal in `config.py` only. On Render, set this from the service's Environment tab (or `render.yaml`'s prompt) instead of editing the file. |
+| `DEBUG`                     | `False`           | `True` runs `app.py` via Flask's own dev server (auto-reload, detailed tracebacks) instead of waitress. Leave `False` - which serves via waitress - for anything reachable from another machine. See [Running in production](#running-in-production). |
+| `HOST`                      | `"0.0.0.0"`       | Interface the server (waitress, or the dev server if `DEBUG = True`) binds to. |
+| `PORT`                      | `7860` (also readable from a `PORT` env var) | Port the server listens on. Render injects its own `PORT` at deploy time and this picks it up automatically - nothing to set for a Render deployment. |
+| `WAITRESS_THREADS`          | `4`               | Worker threads in waitress's request-handling pool. Only relevant when `DEBUG = False`. Needs to be more than 1 so a long-lived `/probe/stream` connection can't block other requests. |
+| `PROBE_THREADS`             | `2`               | Worker threads in the probe thread pool for evaluating a position's legal moves in parallel. Set an explicit integer to match the host's CPU count, or `None` to scale automatically (`min(16, cpu*2)`). |
+| `PROBE_PARALLEL_THRESHOLD`  | `4`               | Minimum number of child positions before probing switches from sequential to the thread pool. |
+| `PROBE_TIMEOUT_SECS`        | `30`              | Wall-clock timeout for each probe phase. `/probe` gives the root probe and the child-move batch independent budgets, so worst-case `/probe` latency can approach `2 × PROBE_TIMEOUT_SECS`. Also bounds how long a request waits on another thread's in-flight probe of the same FEN before giving up with a retryable `probe_timeout` error. |
+| `EVALUATE_CACHE_SIZE`       | `16384`            | Max entries in the root-FEN result cache (full JSON responses). |
+| `PROBE_CACHE_SIZE`          | `262144`           | Max entries in the child-position probe cache (raw `chess.chesstb.ProbeResult` objects - WDL/DTZ/DTC/DTM/DTM50 together). |
+| `BLOCK_CACHE_BYTES`         | `536870912` (512 MiB) | Size, in bytes, of `chesstb`'s own internal cache of decoded/decompressed tablebase blocks (shared across the WDL/DTZ/DTC/DTM/DTM50 tables). Raising this trades RAM for fewer repeated disk reads/HTTP fetches + decompressions across a session - most worthwhile when `PROBE_PARALLEL_THRESHOLD` is set high enough that probing runs mostly serially. |
+| `REMOTE_MODE`               | `"direct"`        | **Remote tablebase entries only.** `"direct"` probes the remote tables in place over byte ranges (nothing written to disk); `"download"` fetches each table in full on first touch and caches it on local disk. See [Getting the tablebase files](#getting-the-tablebase-files). |
+| `REMOTE_PAGE_CACHE_BYTES`   | `2147483648` (2 GiB) | **Remote tablebase entries only.** Soft budget, in bytes, per remote source in `TABLEBASE_PATH`, shared across that source's tables: the in-memory page cache in `"direct"` mode, the on-disk cache of whole downloaded files in `"download"` mode. See [Getting the tablebase files](#getting-the-tablebase-files). |
+| `REMOTE_PAGE_SIZE_BYTES`    | `262144` (256 KiB) | **Remote tablebase entries only.** Size, in bytes, of one page. In `"direct"` mode this is the granularity of every fetch, so it trades over-fetching against round trips per probe; in `"download"` mode it is only the chunk size used while streaming a full file down. |
+| `REMOTE_TIMEOUT_SECS`       | `20`              | **Remote tablebase entries only.** Per-HTTP-request timeout for existence/size checks and the download itself. |
+| `REMOTE_MAX_RETRIES`        | `3`               | **Remote tablebase entries only.** Attempts for a single remote request before it's treated as failed. |
+| `REMOTE_POOL_MAXSIZE`       | `None`            | **Remote tablebase entries only.** Size of each remote backend's HTTP connection pool. `None` computes `max(PROBE_THREADS * 2, 20)`. |
+| `PROBE_RATE_LIMIT`          | `"60 per minute"` | Per-client-IP request limit on `/probe` and `/probe/stream`, using [flask-limiter](https://flask-limiter.readthedocs.io/)'s string syntax. Left empty, rate limiting is disabled entirely. See [Security notes](#security-notes). |
+| `ADMIN_LOGIN_RATE_LIMIT`    | `"5 per minute"`  | Per-client-IP request limit on `/admin/login`, same string syntax as `PROBE_RATE_LIMIT`, applied independently of it. Covers both failed and successful login attempts. Left empty, login attempts are not rate limited. See [Security notes](#security-notes). |
+| `PREFETCH_RATE_LIMIT`       | `"30 per minute"` | Per-client-IP request limit for hover prefetch requests marked with `X-Prefetch: 1`. Left empty, prefetch requests share `PROBE_RATE_LIMIT`. See [Security notes](#security-notes). |
+| `TRUSTED_PROXY_COUNT`       | `1` (also readable from a `TRUSTED_PROXY_COUNT` env var) | Number of trusted reverse-proxy hops in front of this app. In production this configures [waitress's own `trusted_proxy_count`](https://docs.pylonsproject.org/projects/waitress/en/stable/proxy-headers.html) (waitress parses `X-Forwarded-For`/`X-Forwarded-Proto` and corrects `REMOTE_ADDR`/`wsgi.url_scheme` itself, ahead of Flask); [Werkzeug's `ProxyFix`](https://werkzeug.palletsprojects.com/en/latest/middleware/proxy_fix/) makes the same correction for the `DEBUG = True` dev-server path, which doesn't run under waitress. Both rate limiters key on the corrected address, and `request.scheme`/`request.is_secure` read the corrected scheme. `1` matches this project's own `render.yaml` topology (Render's edge/load-balancer, once). Set it to match the deployment's reverse-proxy chain, or set it to `0` for a deployment with no reverse proxy in front of it at all. See [Security notes](#security-notes). |
+| `ADMIN_TOKEN`                | `""` (from `ADMIN_TOKEN` env var) | Shared secret required to reach `/admin` and `/admin/cache/*`. Read from the environment rather than hardcoded, so it can be set as a platform secret. Left unset, admin routes respond `503` rather than running unprotected. See [Security notes](#security-notes). |
+| `FLASK_SECRET_KEY`           | `""` (from `FLASK_SECRET_KEY` env var) | Key used to sign the admin session cookie. Read from the environment for the same reason as `ADMIN_TOKEN`. Left unset, a random key is generated at process startup instead, so every restart requires logging in again. |
+| `SESSION_COOKIE_SECURE`      | `False` (also readable from a `SESSION_COOKIE_SECURE` env var, `"true"`/anything else) | Whether the admin session cookie set by `/admin/login` requires HTTPS. Independent of `DEBUG`. Defaults `False` to match a plain-HTTP local installation; set to `"true"` for any deployment the browser reaches over HTTPS (including behind a TLS-terminating reverse proxy such as Render's - `render.yaml` already sets this explicitly for that deployment). See [Security notes](#security-notes). |
+| `SOURCE_REPOSITORY_URL`                 | `""` (also readable from a `SOURCE_REPOSITORY_URL` env var) | Repository URL for the source repository button shown in the header of every page. Edited directly like any other non-secret value here, or set as an env var on a given deployment. Left empty, the button is omitted. |
+
+Invalid values (wrong type, out of range) cause the app to log an error
+and exit at startup rather than run with a silently-wrong configuration.
+
+---
+
+## Running in production
+
+`python app.py` serves the app via **[waitress](https://docs.pylonsproject.org/projects/waitress/)**,
+a production-grade, pure-Python WSGI server, whenever `DEBUG` in
+`config.py` is `False` (the default) - no separate `gunicorn`/`waitress`
+command or extra process is needed on top of the app itself. Setting
+`DEBUG = True` in `config.py` switches `app.py` over to Flask's own dev
+server instead (auto-reload + interactive debugger), which is meant for
+local development only and should not be used for anything reachable
+from another machine.
+
+```bash
+# Production (default): DEBUG = False in config.py: serves via waitress
+python app.py
+
+# Local development: set DEBUG = True in config.py first, then run the
+# same command: Flask dev server, auto-reload + debugger
+python app.py
+```
+
+- `HOST` / `PORT` control the interface and port waitress binds to, same
+  as for the dev server. `PORT` is also readable from a `PORT`
+  environment variable (see [Configuration reference](#configuration-reference)),
+  which is what lets the same image bind correctly on Render - or any
+  other platform that assigns the port at deploy time - with no edits.
+- `WAITRESS_THREADS` (default `4`) sizes waitress's own pool of
+  request-handling threads. This needs to be more than 1 for the same
+  reason the dev server needs `threaded=True`: `/probe/stream` holds a
+  connection open via Server-Sent Events for the whole duration of a
+  probe, and a single-threaded server would let that one connection block
+  every other request - including the browser's own concurrent requests
+  for CSS/JS/piece images on first page load. It's independent of
+  `PROBE_THREADS`, which sizes the thread pool used internally to
+  parallelise tablebase probing rather than to serve HTTP requests.
+- `TRUSTED_PROXY_COUNT` (default `1`) configures waitress's own
+  `trusted_proxy_count`, so `request.remote_addr` and `request.scheme`
+  reflect the real client IP and scheme behind Render's edge/load-balancer
+  rather than that proxy's own address/hop - see
+  [Security notes](#security-notes).
+- Waitress handles `/probe/stream`'s streamed response natively; no
+  additional configuration is needed for SSE to work correctly.
+- The probe endpoints are unauthenticated by design; only `/admin` and
+  `/admin/cache/*` require a credential (see
+  [Security notes](#security-notes)).
+
+---
+
+## Deploying to Render
+
+This project deploys to [Render](https://render.com) as a single Docker
+web service, built straight from this GitHub repository. Render watches
+the connected branch and rebuilds/redeploys automatically on every push.
+
+There are two ways to set it up:
+
+### Option 1: Blueprint (`render.yaml`, recommended)
+
+This repository ships a [`render.yaml`](render.yaml) at its root
+describing the service (Docker runtime, health check, environment
+variables). Render finds it automatically:
+
+1. Push this repository to GitHub.
+2. In the [Render Dashboard](https://dashboard.render.com), click
+   **New → Blueprint** and connect the repo.
+3. Render reads `render.yaml` and requests the one setting required
+   before the first deploy can run: **`TABLEBASE_PATH`** - the
+   `http(s)://` base URL of the remote tablebase (see
+   [Getting the tablebase files](#getting-the-tablebase-files)).
+   `ADMIN_TOKEN` and `FLASK_SECRET_KEY` are generated automatically.
+4. Click **Apply** / **Create**. Render builds the image from this
+   repo's `Dockerfile` and deploys it.
+
+Every subsequent push to the connected branch redeploys automatically.
+To change `TABLEBASE_PATH`, `ADMIN_TOKEN`, or any other setting later,
+edit it from the service's **Environment** tab in the Render Dashboard;
+see [Configuration reference](#configuration-reference) for which
+settings are env-overridable this way versus which live only in
+`config.py`.
+
+### Option 2: Manual Web Service (no `render.yaml`)
+
+The service can also be configured manually without the Blueprint file:
+
+1. Push this repository to GitHub.
+2. In the Render Dashboard, click **New → Web Service** and connect the
+   repo.
+3. Set **Runtime** to **Docker** (Render should detect the `Dockerfile`
+   at the repo root automatically).
+4. Under **Environment**, add:
+   - `TABLEBASE_PATH`: required; same as Option 1 above.
+   - `ADMIN_TOKEN`: optional but recommended; any secret string, or
+     use Render's "Generate" button. While it is unset, `/admin`
+     responds `503`.
+   - `FLASK_SECRET_KEY`: optional; when omitted, a random key is
+     generated at process startup and admin sessions don't survive a
+     restart.
+   - `SESSION_COOKIE_SECURE`: set to `true`. Render always terminates
+     TLS at its edge, so the browser reaches this deployment over HTTPS
+     even though the app itself just speaks plain HTTP to Render's
+     proxy; `config.py`'s own default (`false`) is tuned for a local
+     plain-HTTP installation instead. (Option 1's `render.yaml` sets
+     this automatically - it is a manual step here because Option 2
+     skips that file.)
+   - `SOURCE_REPOSITORY_URL`: optional; the repository URL, which enables the
+     header's source repository button.
+   - Leave `PORT` alone - Render sets it itself, and `config.py` already
+     reads it (see [Configuration reference](#configuration-reference)).
+5. Under **Health Check Path**, set `/health` (matches the route in
+   `app.py`; Render won't mark a deploy healthy until this returns `200`,
+   which itself only happens once the sources in `TABLEBASE_PATH` have
+   opened successfully).
+6. Click **Create Web Service**.
+
+### Choosing a plan
+
+Probing is CPU-bound (block decompression on every request), so a
+dedicated vCPU - Render's **Starter** tier or above - gives lower probe
+latency than the **Free** tier's shared/limited CPU. Free works
+for casual or low-traffic use; the service spins down after inactivity
+(a slow first request after waking up) and probes are slower under load. Either way, `REMOTE_MODE = "direct"` (the default)
+means no persistent disk is needed regardless of plan - see
+`config.py`'s "Remote (URL) tablebase entries only" section and
+[Getting the tablebase files](#getting-the-tablebase-files).
+
+---
+
+## Usage guide
+
+- **Set a position**: type or paste a FEN into the FEN box and press
+  `Enter` or **Apply**. The move rankings and best-move arrows update
+  automatically. The castling-availability field accepts `-` or any
+  combination of `K`, `Q`, `k`, `q` (each requiring a matching king and
+  rook on their home squares); in **Chess960 Mode** it additionally
+  accepts X-FEN/Shredder-FEN rook-file letters (`a`-`h` / `A`-`H`). A
+  position with a castling right is evaluated the same as any other,
+  reported as not covered if the loaded tablebase set has no table for it
+  (see `TABLEBASE_PATH` in
+  [Configuration reference](#configuration-reference)).
+- **Chess960 (Fischer Random)**: toggle **Chess960 Mode** in the settings
+  panel to switch castling interpretation. This does not move any pieces
+  or randomize a new starting position - it only changes how castling
+  moves/rights on the *current* board are interpreted, and drops the
+  current move line the same way a board edit does (a line built under
+  one variant isn't reinterpreted as the other). With it on, drag a king
+  onto its own rook to castle; the destination square and resulting rook
+  position follow standard Chess960 rules regardless of where the king
+  and rook started. The setting is carried in the shared URL
+  (`&variant=chess960`), the saved in-progress game, and PGN
+  import/export (a `[Variant "Chess960"]` header).
+- **Edit the board directly**: drag pieces around the board, drag a piece
+  off the board to remove it, or click a spare piece in either tray and
+  then click a square to place it (click again / press `Esc` to cancel).
+  Board edits reset the current move line the same way **Clear** does.
+- **Lock the board**: click the padlock button beside the FEN box to
+  restrict drag-and-drop, click-to-move, and the spare-piece trays to
+  legal moves for the side to move; the button turns gold while active.
+  Click again to unlock. The choice is remembered locally across visits.
+  Starting auto-play locks the board automatically for the run (unless
+  already locked) and disables the padlock button until it stops.
+- **Play moves**: click any move in one of the four ranked tables to
+  play it, or drag a piece on the board through a legal move.
+- **Navigate history**: the Undo/Redo arrow buttons or `←`/`→`, or click
+  any move in the PGN panel to jump straight to that point in the line.
+- **Auto-play**: click the ▶ button above the DTZ, DTC, DTM, or DTM50
+  columns
+  to have the app play that metric's best move on a timer (delay set by
+  **Autoplay Delay** in settings, 1.25s by default); click again (the
+  button shows ■ while running) to stop. Any manual navigation stops auto-play.
+- **Import/export a game**: **Import** in the PGN panel opens a dialog to
+  paste PGN text. **Import Game** loads the full game and its variations
+  into the PGN panel, starting before the first move; **Export**
+  downloads the full game and its variations as `chesstb_game.pgn` with
+  standard headers.
+- **Export the move table**: the **CSV** button downloads the current
+  DTZ/DTC/DTM/DTM50 rankings as a CSV file.
+- **Share a position**: the URL updates live with `#fen=...`; sending
+  that link reproduces the exact position.
+- **Change settings**: the ⚙ button in the header opens a **Show Root
+  Row** switch for the results table, a **Chess960 Mode** switch, and an
+  **Autoplay Delay** slider; the choices are persisted across visits.
+- **Admin dashboard**: the gauge icon in the header opens `/admin`, prompting for the
+  `ADMIN_TOKEN` on first visit, then showing live hit-rate stats for both
+  caches and the thread-pool configuration, auto-refreshing every 5
+  seconds.
+
+---
+
+## API
+
+The full HTTP API - `/probe`, `/probe/stream`, `/health`,
+`/admin/cache/stats`, `/admin/cache/clear`, `/admin/login`,
+`/admin/logout` - is documented as an OpenAPI 3.0 specification served
+live by the running app at:
+
+```
+http://127.0.0.1:7860/openapi.yaml
+```
+
+`openapi.yaml` documents every endpoint's request/response shapes; the
+ranking algorithm behind `moves_dtz` / `moves_dtc` / `moves_dtm` /
+`moves_dtm50` is documented inline in `app.py`'s own module docstring and
+its `evaluate_all_moves()` function. `/admin/cache/*` require an
+`Authorization: Bearer <ADMIN_TOKEN>` header or an authenticated session
+cookie from `/admin/login` - see [Security notes](#security-notes).
+
+Quick example:
+
+```bash
+curl -X POST http://127.0.0.1:7860/probe \
+     -H "Content-Type: application/json" \
+     -d '{"fen": "4k3/8/8/8/8/8/8/4K2R w - - 0 1"}'
+```
+
+`variant` is optional and defaults to `"standard"` when omitted. It is
+never inferred from the FEN itself - the orthodox starting array is
+itself a legal Chess960 starting position, so the same FEN text is
+ambiguous without it:
+
+```bash
+curl -X POST http://127.0.0.1:7860/probe \
+     -H "Content-Type: application/json" \
+     -d '{"fen": "r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1", "variant": "chess960"}'
+```
+
+---
+
+## Project structure
+
+```
+.
+├── LICENSE                 # GPL-3.0-or-later license text for this project
+├── THIRD_PARTY_LICENSES.md # Licenses and attributions for bundled third-party code, fonts, and the piece set
+├── Dockerfile               # Container build used for Render (and any other Docker host)
+├── render.yaml              # Render Blueprint: service definition, health check, env vars
+├── app.py                  # Flask backend: routes, probing, caching
+├── config.py               # All configuration, as plain Python values - see "Configuration reference"
+├── openapi.yaml            # OpenAPI 3.0 specification, served at /openapi.yaml
+├── requirements.txt
+├── README.md
+├── .gitattributes, .gitignore, .dockerignore
+├── tablebase_router.py     # Ordered local/remote source lookup for every material
+├── tablebase_opening.py    # Per-material table-opening lock policy, shared by tablebase_router.py and both remote backends
+├── dtz_anchor.py           # Resolves rounded DTZ values by cross-checking the moves of a position
+├── remote/
+│   ├── remote_source.py     # Generic HTTP byte-range client shared by both remote backends - see its own module docstring
+│   ├── remote_direct.py     # REMOTE_MODE="direct": probe remote tables in place over byte ranges - see its own module docstring
+│   └── remote_fallback.py   # REMOTE_MODE="download": whole-file download, cached to local disk on first touch - see its own module docstring
+├── templates/
+│   ├── index.html          # Main explorer UI - mounts the React app (see frontend/)
+│   └── admin.html          # Cache dashboard
+├── frontend/                # React app for the explorer page - see "Frontend build"
+│   ├── package.json, package-lock.json
+│   ├── vite.config.js       # Builds into ../static/dist with fixed filenames (no cache-busting hash)
+│   ├── index.html, admin.html  # Build entries (script and stylesheet)
+│   └── src/
+│       ├── main.jsx, App.jsx
+│       ├── engine/          # Position/rules engine and tablebase client (chessops + Chessground)
+│       ├── vendor/          # Vendored Chessground (script and base stylesheet) + chessops, bundled by the build
+│       ├── hooks/useExplorer.js  # FEN box, PGN, auto-play, settings, keyboard shortcuts
+│       ├── components/      # Board, results table, PGN panel, dialogs, settings panel
+│       │   └── ui/          # Icon, Button, Segmented, Panel
+│       ├── styles/          # Tokens, base, layout, component and chess stylesheets - see "Styling"
+│       └── assets/fonts/    # Inter and JetBrains Mono (woff2)
+└── static/
+    ├── dist/                # Built frontend (see "Frontend build"): app.js, app.css, admin.css, fonts/
+    ├── css/
+    │   └── pieces-cburnett.css   # Piece-set stylesheet linked by templates/index.html
+    ├── js/
+    │   └── admin.js          # Admin dashboard client
+    └── pieces/cburnett/     # Piece-set SVGs
+```
+
+---
+
+## Security notes
+
+- The `/probe` and `/probe/stream` endpoints are intentionally
+  unauthenticated - evaluating a chess position is this app's public,
+  core functionality. `/admin` and `/admin/cache/*` are gated behind
+  `ADMIN_TOKEN` (see below); every other route requires no credential.
+- **Rate limiting** on `/probe` and `/probe/stream` is controlled by
+  `PROBE_RATE_LIMIT`, and on `/admin/login` separately by
+  `ADMIN_LOGIN_RATE_LIMIT` (both in `config.py`'s "Rate limiting"
+  section), each applied per client IP via
+  [flask-limiter](https://flask-limiter.readthedocs.io/). A client over
+  either limit gets a `429` with a JSON error body. `PROBE_RATE_LIMIT`'s
+  default, `"60 per minute"`, covers normal browsing and
+  autoplay at its default delay - raise it if legitimate autoplay at a
+  fast delay setting gets throttled, lower it if the deployment sees
+  abuse, or set either limit to `""` to disable it entirely.
+  `ADMIN_LOGIN_RATE_LIMIT` defaults to `"5 per minute"`, tight enough to
+  slow down repeated `ADMIN_TOKEN` guesses. Both limiters key on
+  `request.remote_addr` as corrected by `TRUSTED_PROXY_COUNT` (see
+  below) and their state lives in-process (`memory://`), which is
+  sufficient for a single-container deployment (e.g. one Render Web
+  Service instance) but isn't shared across multiple replicas.
+- **`TRUSTED_PROXY_COUNT`** (`config.py`'s "Rate limiting" section) is
+  what `request.remote_addr`, and therefore both rate limiters above,
+  is corrected against, so it reads the real client IP from
+  `X-Forwarded-For` rather than the address of the reverse proxy
+  in front of this app. The same setting also governs whether
+  `X-Forwarded-Proto` is trusted, correcting `request.scheme` /
+  `request.is_secure` (and any externally-generated URL) when TLS
+  terminates at that reverse proxy rather than at this app itself. In
+  production (`DEBUG = False`) this configures [waitress's own `trusted_proxy_count`](https://docs.pylonsproject.org/projects/waitress/en/stable/proxy-headers.html):
+  waitress parses both headers and corrects `REMOTE_ADDR`/`wsgi.url_scheme`
+  itself, before Flask ever sees the request, so it takes priority here.
+  [Werkzeug's `ProxyFix`](https://werkzeug.palletsprojects.com/en/latest/middleware/proxy_fix/)
+  makes the equivalent correction for the `DEBUG = True` Flask-dev-server
+  path, which doesn't run under waitress at all. Defaults to `1`,
+  matching this project's own `render.yaml` topology; set it to match
+  the deployment if that differs, or to `0` for a deployment with no
+  reverse proxy in front of it at all.
+- **Admin access** is controlled by `ADMIN_TOKEN` (`config.py`'s "Admin"
+  section), read from the environment rather than hardcoded - set it as
+  a platform secret (e.g. a Render environment variable, generated
+  automatically by `render.yaml`'s `generateValue: true`) rather than
+  committing it. Visiting `/admin` with no active session shows a login
+  form; a correct token there starts a signed, `HttpOnly`,
+  `SameSite=Lax` session cookie (`Secure` too, where configured - see
+  `SESSION_COOKIE_SECURE` below). API clients can instead send
+  `Authorization: Bearer <ADMIN_TOKEN>` directly, no session needed.
+  Token comparison uses `hmac.compare_digest` (constant-time, resistant
+  to timing attacks). Leaving `ADMIN_TOKEN` unset does **not** open the
+  admin panel to everyone - every admin route responds `503` instead.
+- **`SESSION_COOKIE_SECURE`** (`config.py`'s "Admin" section) controls
+  whether the admin session cookie above requires HTTPS, independently
+  of `DEBUG` - `DEBUG` is a development/runtime behavior switch, not a
+  reliable indicator of the deployment's transport security, so
+  `DEBUG = False` alone does not imply HTTPS is in front of this
+  app. Read from a `SESSION_COOKIE_SECURE` env var (`"true"` or anything
+  else, case-insensitive), defaulting `False` to match this project's own
+  plain-HTTP local installation - a browser won't send a
+  `Secure` cookie back over a plain HTTP connection, so `/admin/login`
+  would otherwise appear to succeed while every subsequent authenticated
+  `/admin/*` request came back `401`. Set to `"true"` for any deployment
+  the browser reaches over HTTPS (including behind a TLS-terminating
+  reverse proxy - the browser's own connection is what the `Secure`
+  attribute governs, not the internal hop between the proxy and this
+  process); `render.yaml` already sets this explicitly for the Render
+  deployment it configures, since Render always terminates TLS at its
+  edge.
+- The app serves via **waitress**, a production-grade WSGI server, by
+  default (`DEBUG = False` in `config.py`) - see [Running in production](#running-in-production).
+  Only set `DEBUG = True` (which switches to Flask's own dev server) for
+  local development, never for anything reachable from another machine.
+- A `Content-Security-Policy` is set on every response: scripts and fonts
+  are restricted to `'self'` (no inline scripts, no third-party sources);
+  styles allow `'self'` plus `'unsafe-inline'` (needed for inline
+  `style` attributes set by the React app and in `admin.html`); images
+  allow `'self'` plus `data:`; `connect-src`/`default-src` are `'self'`
+  too, so `fetch`/SSE calls can only reach this same origin. `object-src`,
+  `base-uri`, and `form-action` are locked to `'none'`/`'self'`/`'self'`,
+  and `frame-ancestors 'self' https://huggingface.co` allows the Hugging
+  Face Space page to embed the app. `X-Content-Type-Options:
+  nosniff` and `Referrer-Policy: strict-origin-when-cross-origin` are set
+  too. Request bodies are capped at 4 KB.
+- `config.py` itself holds no secrets - `ADMIN_TOKEN` and
+  `FLASK_SECRET_KEY` are the only two secrets, and they are read only from
+  the environment so the file stays safe to commit as-is. Every other
+  setting is a non-sensitive value.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| Every probe returns "Position not covered by the loaded tablebase." | Check `TABLEBASE_PATH` and the startup logs. Set the tablebase root; `full/` and `castling/` directories are resolved automatically. For an explicit source list, include every required directory. |
+| A FEN is rejected with "Invalid castling availability" | The submitted castling-availability field is something other than `-` or a combination of `K`, `Q`, `k`, `q` (or, in Chess960 Mode, rook-file letters `a`-`h`/`A`-`H`), or names a castling right without a matching king and rook on the board. |
+| A FEN with `a`-`h`/`A`-`H` castling-rights letters is rejected even though the position looks fine | Those letters are only accepted with **Chess960 Mode** on (settings panel, or `variant: "chess960"` on the API) - Standard mode only accepts `K`, `Q`, `k`, `q`, matching Standard chess's fixed castling-rook squares. |
+| Dragging a king onto its own rook doesn't castle | **Chess960 Mode** is off - enable it in the settings panel (or send `variant: "chess960"` on the API) for Chess960-style king-onto-rook castling; in Standard mode a king can only reach its rook's square by regular king movement. |
+| `/health` returns `503 degraded` | The tablebase failed to open - check `TABLEBASE_PATH` and file permissions. |
+| `ModuleNotFoundError: No module named 'chess.chesstb'` | Plain PyPI `chess` was installed instead of the fork. Re-run `pip install -r requirements.txt` and confirm it pulled `chess` from `noobpwnftw/python-chess` (the `add-chesstb-tablebases` branch) rather than plain PyPI `chess` - see the note at the top of `requirements.txt`. |
+| `ModuleNotFoundError: No module named 'config'` | `config.py` is missing from alongside `app.py`. It ships with the repository - if it was deleted or moved, restore it from the repo (or re-clone) and re-apply any edits, such as `TABLEBASE_PATH`. |
+| App logs `Configuration error: ...` and exits immediately | A value in `config.py` is the wrong type or out of range for that setting (e.g. a string where an integer is expected, or a negative cache size) - the error message names which setting and why. Fix it in `config.py` and re-run `python app.py`. |
+| Admin dashboard panels stuck on "Loading…" | Check the browser console for a CSP violation and verify that the app is running and reachable at the `/admin` URL. |
+| A drag, drop, or spare-piece placement on the board is silently rejected | The board is Locked - the padlock button beside the FEN box is highlighted gold. Lock restricts board interaction to legal moves and disables the spare-piece trays and off-board drops; click the padlock again to unlock and edit freely. |
+| Probing feels slow on positions with many legal moves, or doesn't scale with `PROBE_THREADS` | Confirm `lz4` is installed (`pip show lz4`, or `python -c "import lz4"`) - without it, `chess.chesstb`'s block decompression runs in pure Python and holds the GIL, so `PROBE_THREADS` can't achieve real parallelism. `pip install lz4` (already in `requirements.txt`) and restart. Otherwise, tune `PROBE_THREADS`, `PROBE_PARALLEL_THRESHOLD`, and `PROBE_TIMEOUT_SECS` in `config.py`. Note that `tablebase_router.py` guards each material's first open with a lock keyed by `(kind, material)`, so two threads racing to open the *same* never-before-seen material collapse onto one read, while distinct materials of the same kind open concurrently. If any configured tier uses `REMOTE_MODE="download"`, opens fall back to one lock shared per kind, so several distinct never-before-seen materials of that kind then open one at a time instead - either way, this only affects the very first probe against any given material. |
+| `ModuleNotFoundError: No module named 'waitress'` | The active environment's dependencies are out of date - re-run `pip install -r requirements.txt` to pick up `waitress`. `app.py` imports it unconditionally at the top of the file, before `config.DEBUG` is even read, so setting `DEBUG = True` does **not** avoid this - waitress has to be installed either way. |
+| Every probe on a remote `TABLEBASE_PATH` returns "Position not covered..." or `/health` is `degraded` | Confirm the URL is reachable and correct (try opening `TABLEBASE_PATH/wdl/KQK.lzw` - or any small material's `.lzw` - directly in a browser). Check the startup log's "TABLEBASE_PATH opened remotely at: ..." line (or a warning in its place) for the actual failure. |
+| A probe occasionally returns `503` with `error_code: "probe_timeout"` | Another concurrent request was already probing the same position and didn't finish within `PROBE_TIMEOUT_SECS`. This is transient and retryable - the original probe has usually landed in the child-probe cache before a retry, so the retry is inexpensive. Frequent occurrences suggest raising `PROBE_TIMEOUT_SECS`, or that a slow remote `TABLEBASE_PATH` is the underlying bottleneck. |
+| Remote probing feels slow, or repeated probes against the same material keep hitting the network | Check `REMOTE_TIMEOUT_SECS`/`REMOTE_MAX_RETRIES` aren't causing retries on a slow link, and consider raising `REMOTE_PAGE_CACHE_BYTES` - a too-small budget evicts cached pages (`"direct"`) or downloaded files (`"download"`) before later probes can reuse them. `GET /admin/cache/stats` surfaces this per tier as `tablebase_cache.<low|high|castling>.remote_page_cache` or `.remote_disk_cache` respectively. On a high-latency link also try raising `REMOTE_PAGE_SIZE_BYTES`, or `REMOTE_MODE = "download"`. See [Configuration reference](#configuration-reference). |
+| On Render, the deploy never goes live / stays stuck "deploying" | Render's health check (`healthCheckPath: /health` in `render.yaml`, or the equivalent field on a manually-created service - see [Deploying to Render](#deploying-to-render)) only passes once `/health` returns `200`, which itself requires the sources in `TABLEBASE_PATH` to have opened successfully. Check the service's **Logs** tab for the same "opened remotely at: ..." / warning line described above. |
+| On Render, the service responds but the page never loads / connection refused | Typically a `PORT` mismatch. Confirm `config.py` reads `PORT` from the environment (see [Configuration reference](#configuration-reference)) and that nothing else in a custom start command overrides `HOST`/`PORT`. |
+
+---
+
+## Credits
+
+- Tablebase data & format: [ChessTB / chessdb.cn](https://www.chessdb.cn/)
+- Tablebase probing support: [noobpwnftw/python-chess (`add-chesstb-tablebases` branch)](https://github.com/noobpwnftw/python-chess/tree/add-chesstb-tablebases), a fork of [niklasf/python-chess](https://github.com/niklasf/python-chess)
+- Remote (URL) tablebase support for the fork's `chess.chesstb` module - see `remote/remote_source.py`, `remote/remote_direct.py` and `remote/remote_fallback.py`
+- Board UI: [Chessground](https://github.com/lichess-org/chessground)
+- Move generation/validation on the client, for both Standard chess and
+  Chess960: [chessops](https://github.com/niklasf/chessops)
+- Production WSGI server: [waitress](https://docs.pylonsproject.org/projects/waitress/)
+- Piece set: [cburnett](https://github.com/lichess-org/lila/blob/master/COPYING.md), a commonly-used community set found in most web chess UIs.
+
+## License
+
+ChessTB Explorer is licensed under `GPL-3.0-or-later`; see [`LICENSE`](LICENSE).
+Bundled third-party components and their licenses are listed in
+[`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md).

THIRD_PARTY_LICENSES.md

@@ -0,0 +1,133 @@
+# Third-Party Notices
+
+This project bundles or depends on the third-party components listed
+below. Each entry states the component, version, SPDX license
+identifier, and source. This document is provided for attribution and
+license-compliance purposes only and does not constitute legal advice;
+consult qualified counsel before distributing, selling, or publicly
+deploying this software.
+
+Every file in this repository not listed in the tables below - including
+`app.py`, `config.py`, `dtz_anchor.py`, `tablebase_opening.py`,
+`tablebase_router.py`, `static/js/admin.js`,
+`static/css/*.css`, `templates/*.html`,
+`frontend/src/engine/`, `frontend/src/hooks/`, `frontend/src/components/`,
+`frontend/src/styles/`, `frontend/src/*.jsx`, and `remote/`, `Dockerfile`, `render.yaml`,
+`.dockerignore`, `requirements.txt`, and `openapi.yaml` - is original and
+licensed under the terms in [`LICENSE`](LICENSE) (`GPL-3.0-or-later`).
+
+## Summary
+
+| Component | Version | License (SPDX) | Category |
+|---|---|---|---|
+| [React](https://github.com/facebook/react) | 18.3.1 | `MIT` | Frontend |
+| [React DOM](https://github.com/facebook/react) | 18.3.1 | `MIT` | Frontend |
+| [Scheduler](https://github.com/facebook/react) | 0.23.2 | `MIT` | Frontend |
+| [Chessground](https://github.com/lichess-org/chessground) | 10.1.1 | `GPL-3.0-or-later` | Frontend |
+| [chessops](https://github.com/niklasf/chessops) | 0.15.1 | `GPL-3.0-or-later` | Frontend |
+| [@badrap/result](https://github.com/badrap/result) | 0.3.1 | `MIT` | Frontend |
+| [Inter](https://rsms.me/inter/) | — | `OFL-1.1` | Font |
+| [JetBrains Mono](https://www.jetbrains.com/lp/mono/) | — | `OFL-1.1` | Font |
+| cburnett piece set | — | `GPL-2.0-or-later` | Asset |
+| [chess](https://github.com/noobpwnftw/python-chess) (`add-chesstb-tablebases` fork) | latest on branch | `GPL-3.0-or-later` | Python |
+| [Flask](https://github.com/pallets/flask) | `>=3.0,<4.0` | `BSD-3-Clause` | Python |
+| [lz4](https://github.com/python-lz4/python-lz4) | `>=4.0,<5.0` | `BSD-3-Clause` | Python |
+| [waitress](https://github.com/Pylons/waitress) | `>=3.0,<4.0` | `ZPL-2.1` | Python |
+| [requests](https://github.com/psf/requests) | `>=2.31,<3.0` | `Apache-2.0` | Python |
+| [Flask-Limiter](https://github.com/alisaifee/flask-limiter) | `>=4.0,<5.0` | `MIT` | Python |
+
+## Notices
+
+This project is licensed as a whole under `GPL-3.0-or-later` - see
+[`LICENSE`](LICENSE).
+
+The following bundled components carry their own `GPL` license terms:
+
+- **`chess` / `chess.chesstb`** (`GPL-3.0-or-later`): imported
+  directly by `app.py`.
+- **Chessground** (`GPL-3.0-or-later`): vendored in
+  `frontend/src/vendor/`, bundled into `static/dist/app.js`, and served
+  to every client.
+- **chessops** (`GPL-3.0-or-later`): vendored in
+  `frontend/src/vendor/chessops/`, bundled into `static/dist/app.js`,
+  and served to every client.
+- **cburnett piece set** (`GPL-2.0-or-later`): bundled in
+  `static/pieces/cburnett/` and served to every client.
+
+React, React DOM, Scheduler, and `@badrap/result` (`MIT`) are also
+bundled into `static/dist/app.js` - see
+[React / build dependencies](#react--build-dependencies-frontend) below.
+
+## Frontend engine libraries: `frontend/src/vendor/`
+
+| File | Component | Version | License | Source |
+|---|---|---|---|---|
+| `chessground.min.js` | Chessground | 10.1.1 | `GPL-3.0-or-later` | [lichess-org/chessground](https://github.com/lichess-org/chessground) |
+| `chessops/*.js` (excl. `badrap-result.js`) | chessops | 0.15.1 | `GPL-3.0-or-later` | [niklasf/chessops](https://github.com/niklasf/chessops) |
+| `chessops/badrap-result.js` | @badrap/result | 0.3.1 | `MIT` | [badrap/result](https://github.com/badrap/result) |
+| `chessground.base.css` | Chessground stylesheet | 10.1.1 | `GPL-3.0-or-later` | [lichess-org/chessground](https://github.com/lichess-org/chessground) |
+
+`frontend/src/vendor/` holds the pinned ESM distribution and its
+`@badrap/result` runtime dependency; `vite build` bundles them into
+`static/dist/app.js` together with the frontend's own code. They are
+not fetched from a CDN at request time. `chessground.base.css` is
+bundled into `static/dist/app.css`.
+
+## React / build dependencies: `frontend/`
+
+| Component | Version | License | Source |
+|---|---|---|---|
+| React | 18.3.1 | `MIT` | [facebook/react](https://github.com/facebook/react) |
+| React DOM | 18.3.1 | `MIT` | [facebook/react](https://github.com/facebook/react) |
+| Scheduler | 0.23.2 | `MIT` | [facebook/react](https://github.com/facebook/react) (React DOM's runtime dependency) |
+
+Installed via `npm install` from `frontend/package.json` and bundled
+into `static/dist/app.js` by `vite build`; not present anywhere else in
+the served application. Vite and `@vitejs/plugin-react` are build-time
+only and are not distributed to clients.
+
+## Fonts: `frontend/src/assets/fonts/`
+
+| File(s) | Typeface | License | Author |
+|---|---|---|---|
+| `Inter-Regular.woff2`, `Inter-Medium.woff2`, `Inter-SemiBold.woff2` | Inter | `OFL-1.1` | [Rasmus Andersson](https://rsms.me/inter/) |
+| `JetBrainsMono-Regular.woff2`, `JetBrainsMono-Medium.woff2` | JetBrains Mono | `OFL-1.1` | [JetBrains](https://www.jetbrains.com/lp/mono/) |
+
+The build copies the fonts to `static/dist/fonts/`.
+
+## Chess piece set: `static/pieces/` (via lichess.org)
+
+| Directory | License | Author | Source |
+|---|---|---|---|
+| `cburnett/` | `GPL-2.0-or-later` | Colin M.L. Burnett | [lila COPYING.md](https://github.com/lichess-org/lila/blob/master/COPYING.md) |
+
+## Python dependencies: `requirements.txt`
+
+| Package | License | Notes |
+|---|---|---|
+| `chess` (installed from `noobpwnftw/python-chess`, `add-chesstb-tablebases` branch) | `GPL-3.0-or-later` | Fork of [niklasf/python-chess](https://github.com/niklasf/python-chess). Both the base `chess` package and `chess.chesstb` are imported directly by `app.py`. |
+| Flask | `BSD-3-Clause` | [pallets/flask](https://github.com/pallets/flask) |
+| lz4 | `BSD-3-Clause` | [python-lz4/python-lz4](https://github.com/python-lz4/python-lz4). Optional but recommended: `chess.chesstb` picks it up itself at import time to accelerate its own block decompression, falling back to its own pure-Python decoder if not present. `app.py` doesn't import or reference it directly. |
+| waitress | `ZPL-2.1` | [Pylons/waitress](https://github.com/Pylons/waitress) |
+| requests | `Apache-2.0` | [psf/requests](https://github.com/psf/requests). Imported only when `TABLEBASE_PATH` is a remote `http(s)://` URL (`remote/remote_source.py`, `remote/remote_fallback.py`). |
+| Flask-Limiter | `MIT` | [alisaifee/flask-limiter](https://github.com/alisaifee/flask-limiter). Provides the per-IP rate limiting on `/probe` and `/probe/stream` - see `config.py`'s `PROBE_RATE_LIMIT`. |
+
+## License texts
+
+| SPDX identifier | Text |
+|---|---|
+| `GPL-3.0-or-later` | <https://www.gnu.org/licenses/gpl-3.0.txt> |
+| `GPL-2.0-or-later` | <https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt> |
+| `BSD-2-Clause` | <https://spdx.org/licenses/BSD-2-Clause.html> |
+| `BSD-3-Clause` | <https://spdx.org/licenses/BSD-3-Clause.html> |
+| `OFL-1.1` | <https://scripts.sil.org/OFL> |
+| `ZPL-2.1` | <https://opensource.org/license/zpl-2-1/> |
+| `Apache-2.0` | <https://www.apache.org/licenses/LICENSE-2.0.txt> |
+| `MIT` | <https://spdx.org/licenses/MIT.html> |
+
+## Tablebase data
+
+Not covered by this document. This project only displays results from
+ChessTB tablebase files supplied by the user (see `README.md` →
+"Getting the tablebase files"). No tablebase data is bundled with the
+app.

app.py

@@ -0,0 +1,2048 @@
+"""
+app.py: ChessTB Explorer back-end
+
+A single-file Flask application that probes a ChessTB endgame tablebase
+for a submitted FEN position and returns every legal move ranked by
+Distance to Zeroing (DTZ), Distance to Conversion (DTC), Distance to
+Mate (DTM), and DTM under the 50-move rule (DTM50).
+
+DTC is 50-move-rule-aware in the same way DTM50 is (it is always probed
+at the position's own halfmove clock), but unlike DTM50 it has no
+"flat"/clock-independent sibling column of its own -- there is only ever
+one DTC value for a position. A ``.lzdtc`` table only exists for material
+with at least one pawn; for pawnless material `chess.chesstb` derives an
+equivalent answer from DTZ/WDL instead (see chess.chesstb.ProbeResult),
+so `has_dtc` is False only when a pawnful material's own
+`.lzdtc` file genuinely hasn't been generated/shipped.
+
+Routes
+------
+  POST /probe              - evaluate a FEN position (JSON)
+  POST /probe/stream       - evaluate with SSE streaming progress
+  GET  /                   - main UI
+  GET  /health             - readiness check
+  GET  /admin              - cache dashboard HTML page, or a login form if not authenticated
+  POST /admin/login        - start an admin session (JSON {token})
+  POST /admin/logout       - end the admin session
+  POST /admin/cache/clear  - purge both LRU caches
+  GET  /admin/cache/stats  - cache hit-rate statistics
+  GET  /openapi.yaml       - OpenAPI 3.0 specification
+
+/admin and /admin/cache/* require admin authentication -- either a
+session cookie started via /admin/login, or an "Authorization: Bearer
+<ADMIN_TOKEN>" header. See config.py's "Admin" section and README.md's
+"Security notes" for how ADMIN_TOKEN is configured.
+
+/probe and /probe/stream are rate-limited per client IP (config.py's
+PROBE_RATE_LIMIT); a client over the limit gets a 429 with a JSON body.
+/admin/login has its own, separate limit (config.py's
+ADMIN_LOGIN_RATE_LIMIT), covering both failed and successful attempts.
+
+Each move entry includes a child_fen so the client can pre-fetch the next
+probe, and each response includes a summary of wins/draws/losses/unknown
+across all legal moves. A position not covered by the loaded tablebase
+raises MissingTableError, which is returned as structured JSON
+({error_code, piece_count}). Root-JSON and child-probe cache sizes are set
+by config.EVALUATE_CACHE_SIZE / config.PROBE_CACHE_SIZE.
+
+Every request to /probe and /probe/stream carries an explicit "variant"
+field ("standard" or "chess960", defaulting to "standard" when omitted)
+alongside "fen" -- the two rulesets are never inferred from a FEN's
+contents, since the orthodox starting arrangement is itself a legal
+Chess960 starting position and would otherwise be ambiguous. A submitted
+FEN's castling-availability field accepts "-" or any combination of "K",
+"Q", "k", "q" for variant="standard", plus rook-file letters ("a"-"h" /
+"A"-"H") for variant="chess960"; a right with no matching king/rook pair
+is rejected as invalid input before the board is ever probed (see
+_validate_and_build_board). A position with castling rights is otherwise
+probed like any other: `chess.chesstb` resolves it when the loaded
+tablebase set carries a table for that material (see config.py's
+TABLEBASE_PATH and tablebase_router.py -- unaffected by variant,
+since a Chess960 board's clean_castling_rights() reports the same way a
+Standard board's does), and reports it as not covered when it doesn't.
+
+Running this file directly (`python app.py`) serves the app via waitress
+(a production-grade WSGI server) by default. Set DEBUG = True in
+config.py to use Flask's own dev server instead (auto-reload +
+interactive debugger) for local development. See README.md
+"Installation" / "Running in production" for details.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict, namedtuple
+from concurrent.futures import (
+    ThreadPoolExecutor,
+    wait as futures_wait,
+    ALL_COMPLETED,
+    FIRST_COMPLETED,
+)
+from dataclasses import dataclass
+from flask import (
+    Flask, render_template, request, jsonify, Response,
+    stream_with_context, send_file, session,
+)
+from flask_limiter import Limiter
+from flask_limiter.util import get_remote_address
+from functools import lru_cache, wraps
+from typing import TypedDict
+from waitress import serve as waitress_serve
+from werkzeug.middleware.proxy_fix import ProxyFix
+import atexit
+import chess
+import config
+import dtz_anchor
+import hmac
+import json
+import os
+import re
+import logging
+import secrets
+import tablebase_router
+import threading
+import time
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+log = logging.getLogger(__name__)
+
+
+# ── ChessTB backend ──────────────────────���────────────────────────────────────
+
+# chess.chesstb comes from noobpwnftw's add-chesstb-tablebases fork of
+# python-chess (see requirements.txt) - open_tablebase, ProbeResult's raw
+# wdl/dtz/dtc/dtm/dtm50 fields, MissingTableError, and the WIN/CURSED_WIN/
+# DRAW/BLESSED_LOSS/LOSE constants all come from that module.
+import chess.chesstb as chesstb
+
+log.info("chess.chesstb backend: noobpwnftw/python-chess (add-chesstb-tablebases)")
+
+# Remote (HTTP) tablebase support, in two flavours -- config.REMOTE_MODE
+# picks one (see tablebase_router.open_one):
+#   remote/remote_direct.py   ("direct")   probe in place over byte ranges
+#   remote/remote_fallback.py ("download") whole-file download, disk-cached
+# See each file's module docstring for the design and the trade-off.
+# looks_like_remote()/RemoteSourceError come from remote/remote_source.py.
+from remote import remote_direct, remote_fallback, remote_source
+
+
+# ── Type aliases ──────────────────────────────────────────────────────────────
+
+class MoveEntry(TypedDict):
+    san:         str
+    plies:       int
+    order:       int         # DTC only: pawn pushes still owed before a conversion (0 for every other metric)
+    is_mate:     bool
+    outcome:     str         # "win"|"cursed_win"|"draw"|"blessed_loss"|"loss"|"unknown"|"not_available"
+    available:   bool        # False when this move's own metric table isn't present (outcome is then "not_available")
+    child_fen:   str | None  # FEN after this move; None for terminal / unknown
+    draw_reason: str | None  # "stalemate"|"insufficient_material"|None
+
+
+class DtzMoveEntry(MoveEntry, total=False):
+    rounded: bool  # DTZ rows only, when available: plies may be a ply off
+
+
+@dataclass
+class _DtzMove:
+    row: int  # index into the DTZ rows
+    my_wdl: int
+    keeps_class: bool
+    option: dtz_anchor.MoveOption
+
+
+MoveList = list[MoveEntry]
+
+
+# ── Config validation helpers ─────────────────────────────────────────────────
+# Centralise the "read a config.py value, check its type, validate range"
+# pattern that AppConfig.from_config() below needs once per setting.
+
+def _validated_int(name: str, value, *, min_val: int = 1, max_val: int | None = None) -> int:
+    if isinstance(value, str):
+        # PORT and TRUSTED_PROXY_COUNT are the two config.py settings read
+        # as a raw string rather than pre-converted at import time (see
+        # config.py's own comments on each) -- specifically so a bad
+        # value raises here, inside AppConfig.from_config()'s try/except,
+        # rather than as an uncaught ValueError from a bare int() call
+        # during module import, before this module has an exception handler
+        # in place for it.
+        try:
+            value = int(value.strip())
+        except ValueError:
+            raise ValueError(f"config.{name} must be an integer, got {value!r}") from None
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ValueError(f"config.{name} must be an integer, got {value!r}")
+    if max_val is None:
+        if value < min_val:
+            raise ValueError(f"config.{name} must be >= {min_val}, got {value}")
+    elif not (min_val <= value <= max_val):
+        raise ValueError(f"config.{name} must be {min_val}-{max_val}, got {value}")
+    return value
+
+
+def _validated_float(name: str, value) -> float:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        raise ValueError(f"config.{name} must be a number, got {value!r}")
+    value = float(value)
+    if value <= 0:
+        raise ValueError(f"config.{name} must be > 0, got {value}")
+    return value
+
+
+def _validated_str(name: str, value) -> str:
+    if not isinstance(value, str):
+        raise ValueError(f"config.{name} must be a string, got {value!r}")
+    return value
+
+
+def _validated_path_spec(name: str, value) -> str | list[str]:
+    """TABLEBASE_PATH: a
+    single path (local directory or http(s):// URL) or a list of them for
+    a hybrid source (see tablebase_router.py). Each list entry must
+    itself be a string -- a nested list isn't a valid hybrid source."""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (list, tuple)) and all(isinstance(v, str) for v in value):
+        return list(value)
+    raise ValueError(f"config.{name} must be a string or a list of strings, got {value!r}")
+
+
+def _validated_choice(name: str, value, allowed: tuple) -> str:
+    if value not in allowed:
+        raise ValueError(
+            f"config.{name} must be one of {', '.join(map(repr, allowed))}, got {value!r}")
+    return value
+
+
+def _validated_bool(name: str, value) -> bool:
+    if not isinstance(value, bool):
+        raise ValueError(f"config.{name} must be True or False, got {value!r}")
+    return value
+
+
+# ── Validated configuration ───────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class AppConfig:
+    tablebase_path:      str | list[str]
+    probe_threads:       int
+    parallel_threshold:  int
+    probe_timeout:       float
+    host:                str
+    port:                int
+    evaluate_cache_size: int
+    probe_cache_size:    int
+    block_cache_bytes:   int
+    debug:               bool
+    waitress_threads:    int
+    # Only used for an http(s):// URL entry in tablebase_path (see "ChessTB
+    # backend" above and remote/remote_source.py) -- ignored entirely for
+    # a local-directory entry. Bounds an on-disk LRU of whole downloaded
+    # table files cached by remote/remote_fallback.py (see that file's
+    # module docstring for the full design).
+    remote_mode:             str
+    remote_page_cache_bytes: int
+    remote_page_size_bytes:  int
+    remote_timeout_secs:     float
+    remote_max_retries:      int
+    remote_pool_maxsize:     int
+    admin_token:             str
+    secret_key:              str
+    source_repository_url:              str
+    probe_rate_limit:        str
+    prefetch_rate_limit:     str
+    admin_login_rate_limit:  str
+    trusted_proxy_count:     int
+    session_cookie_secure:   bool
+    # Hard-coded limit, not one of config.py's settings -- kept as a
+    # dataclass field (rather than a bare module constant) so it reads
+    # alongside every other request-validation knob above.
+    max_fen_length:      int   = 100
+
+    @classmethod
+    def from_config(cls) -> "AppConfig":
+        # PROBE_THREADS is the one setting with a computed (not literal)
+        # default, so a None left in config.py falls back to a
+        # CPU-count-based figure instead of going through _validated_int.
+        threads = (
+            _validated_int("PROBE_THREADS", config.PROBE_THREADS)
+            if config.PROBE_THREADS is not None
+            else min(16, (os.cpu_count() or 4) * 2)
+        )
+        # Same "None means auto" shape as PROBE_THREADS above, computed
+        # from it: a connection pool smaller than the probe thread count
+        # gives up connection reuse for whichever requests land once the
+        # pool is exhausted (see remote/remote_source.py).
+        pool_maxsize = (
+            _validated_int("REMOTE_POOL_MAXSIZE", config.REMOTE_POOL_MAXSIZE)
+            if config.REMOTE_POOL_MAXSIZE is not None
+            else max(threads * 2, 20)
+        )
+
+        return cls(
+            tablebase_path=_validated_path_spec("TABLEBASE_PATH", config.TABLEBASE_PATH),
+            probe_threads=threads,
+            parallel_threshold=_validated_int("PROBE_PARALLEL_THRESHOLD", config.PROBE_PARALLEL_THRESHOLD),
+            probe_timeout=_validated_float("PROBE_TIMEOUT_SECS", config.PROBE_TIMEOUT_SECS),
+            host=_validated_str("HOST", config.HOST),
+            port=_validated_int("PORT", config.PORT, max_val=65535),
+            evaluate_cache_size=_validated_int("EVALUATE_CACHE_SIZE", config.EVALUATE_CACHE_SIZE),
+            probe_cache_size=_validated_int("PROBE_CACHE_SIZE", config.PROBE_CACHE_SIZE),
+            block_cache_bytes=_validated_int("BLOCK_CACHE_BYTES", config.BLOCK_CACHE_BYTES),
+            # DEBUG also selects the server used by
+            # `if __name__ == "__main__"` below: the Flask dev server when
+            # True, waitress otherwise (see README.md "Running in production").
+            debug=_validated_bool("DEBUG", config.DEBUG),
+            waitress_threads=_validated_int("WAITRESS_THREADS", config.WAITRESS_THREADS),
+            remote_mode=_validated_choice("REMOTE_MODE", config.REMOTE_MODE, ("direct", "download")),
+            remote_page_cache_bytes=_validated_int(
+                "REMOTE_PAGE_CACHE_BYTES", config.REMOTE_PAGE_CACHE_BYTES),
+            remote_page_size_bytes=_validated_int(
+                "REMOTE_PAGE_SIZE_BYTES", config.REMOTE_PAGE_SIZE_BYTES),
+            remote_timeout_secs=_validated_float("REMOTE_TIMEOUT_SECS", config.REMOTE_TIMEOUT_SECS),
+            remote_max_retries=_validated_int("REMOTE_MAX_RETRIES", config.REMOTE_MAX_RETRIES),
+            remote_pool_maxsize=pool_maxsize,
+            admin_token=_validated_str("ADMIN_TOKEN", config.ADMIN_TOKEN),
+            secret_key=_validated_str("FLASK_SECRET_KEY", config.FLASK_SECRET_KEY),
+            source_repository_url=_validated_str("SOURCE_REPOSITORY_URL", config.SOURCE_REPOSITORY_URL),
+            probe_rate_limit=_validated_str("PROBE_RATE_LIMIT", config.PROBE_RATE_LIMIT),
+            prefetch_rate_limit=_validated_str("PREFETCH_RATE_LIMIT", config.PREFETCH_RATE_LIMIT),
+            admin_login_rate_limit=_validated_str("ADMIN_LOGIN_RATE_LIMIT", config.ADMIN_LOGIN_RATE_LIMIT),
+            trusted_proxy_count=_validated_int(
+                "TRUSTED_PROXY_COUNT", config.TRUSTED_PROXY_COUNT, min_val=0, max_val=10),
+            session_cookie_secure=_validated_bool("SESSION_COOKIE_SECURE", config.SESSION_COOKIE_SECURE),
+        )
+
+
+try:
+    cfg = AppConfig.from_config()
+except (ValueError, AttributeError) as e:
+    log.error("Configuration error: %s — fix config.py and restart.", e)
+    raise SystemExit(1) from e
+
+# Exception type to treat as "couldn't reach the remote tablebase" in the
+# /probe and /probe/stream handlers below.
+_REMOTE_SOURCE_ERROR = remote_source.RemoteSourceError
+
+if not cfg.tablebase_path:
+    log.warning("TABLEBASE_PATH is not set — tablebase lookups will fail.")
+
+if not cfg.admin_token:
+    log.warning(
+        "ADMIN_TOKEN is not set — /admin and /admin/cache/* will respond "
+        "503 until it's configured (see config.py's \"Admin\" section)."
+    )
+
+
+# ── Flask app ─────────────────────────────────────────────────────────────────
+
+app = Flask(__name__)
+app.config["MAX_CONTENT_LENGTH"] = 4 * 1024   # 4 KB
+
+# secrets.token_hex(32) generated fresh at process startup when
+# FLASK_SECRET_KEY isn't set (see config.py) -- every admin session is then
+# invalidated by a restart, requiring a new login; it never
+# breaks anything the app itself depends on, since sessions here hold
+# nothing but the admin_ok flag set by /admin/login.
+app.secret_key = cfg.secret_key or secrets.token_hex(32)
+app.config["SESSION_COOKIE_HTTPONLY"] = True
+app.config["SESSION_COOKIE_SAMESITE"] = "Lax"
+# Independent of cfg.debug -- see config.py's SESSION_COOKIE_SECURE for
+# why: DEBUG is a development/runtime behavior switch, not a reliable
+# indicator of whether the browser reaches this deployment over HTTPS.
+app.config["SESSION_COOKIE_SECURE"] = cfg.session_cookie_secure
+
+# Without this, request.remote_addr -- and therefore get_remote_address()
+# below, which keys both rate limiters -- is whichever host made the TCP
+# connection to this process. Behind a reverse proxy (Render's own
+# edge/load-balancer in front of the render.yaml deployment this project
+# ships with, or any other reverse proxy placed in front of it) that's the
+# proxy's own address, not the actual client's, so every client sharing
+# that proxy would collapse onto one rate-limit key. ProxyFix instead
+# trusts exactly cfg.trusted_proxy_count X-Forwarded-For hops closest to
+# this app and reads the real client IP from ahead of them -- set to 0
+# this is a no-op, appropriate only for a deployment with no reverse proxy
+# in front of it at all (an untrusted client's own X-Forwarded-For header
+# would otherwise be trusted, letting it spoof its rate-limit key).
+#
+# x_proto does the equivalent correction for X-Forwarded-Proto, which a
+# TLS-terminating reverse proxy sets to tell this app the scheme the
+# client actually connected with -- without it, request.scheme /
+# request.is_secure (and any URL this app builds with
+# url_for(..., _external=True)) would read as plain http:// even when the
+# client's own connection was https://, since Flask only ever sees the
+# proxy's own (typically-HTTP) hop to this app. Same trusted-hop count as
+# x_for, for the same reason: a value here that doesn't match the real
+# proxy chain either misreads the scheme or lets a client spoof it.
+#
+# This only actually matters for cfg.debug's Flask-dev-server path below --
+# under waitress (cfg.debug False, the production path), waitress parses
+# X-Forwarded-For and corrects REMOTE_ADDR itself before this app ever
+# sees the request, taking priority over -- and making redundant, but
+# harmlessly so -- the correction this makes. See the waitress_serve(...)
+# call below for that side of it.
+if cfg.trusted_proxy_count > 0:
+    app.wsgi_app = ProxyFix(
+        app.wsgi_app, x_for=cfg.trusted_proxy_count, x_proto=cfg.trusted_proxy_count)
+
+
+@app.errorhandler(413)
+def request_too_large(e: Exception) -> tuple:
+    return jsonify({"error": "Request body too large (max 4 KB)."}), 413
+
+
+# ── Rate limiting ────────────────────────────────────────────────────────────
+# Per-IP limits on /probe, /probe/stream (config.py's PROBE_RATE_LIMIT, or
+# PREFETCH_RATE_LIMIT for a request tagged "X-Prefetch: 1" -- see
+# _request_probe_limit below) and, separately, /admin/login (config.py's
+# ADMIN_LOGIN_RATE_LIMIT -- see README.md's "Security notes").
+# default_limits=[] means nothing is limited except the routes explicitly
+# decorated with @_probe_rate_limit / @_admin_login_rate_limit below; the
+# in-memory storage is per-process, which is enough for a single-container
+# deployment but doesn't share state across multiple replicas. key_func
+# reads request.remote_addr, which ProxyFix (see the Flask app section
+# above) has already corrected for cfg.trusted_proxy_count reverse-proxy
+# hops.
+limiter = Limiter(
+    key_func=get_remote_address, app=app, default_limits=[], storage_uri="memory://",
+    headers_enabled=True)
+
+
+def _request_probe_limit() -> str:
+    # X-Prefetch is client-asserted and therefore untrusted as a basis for
+    # relaxing enforcement -- it only ever selects a separate, tighter
+    # budget than the default, never bypasses PROBE_RATE_LIMIT. A request
+    # without the header, or when PREFETCH_RATE_LIMIT is unset, always
+    # falls back to the normal probe budget.
+    if request.headers.get("X-Prefetch") == "1" and cfg.prefetch_rate_limit:
+        return cfg.prefetch_rate_limit
+    return cfg.probe_rate_limit
+
+
+def _probe_rate_limit(view):
+    # A plain pass-through when neither limit is configured, rather than
+    # a zero/near-zero limiter.limit() call, so "disabled" actually means
+    # unlimited rather than "limited to approximately nothing." A
+    # callable limit_value (rather than the plain string
+    # _admin_login_rate_limit below uses) is what lets a single decorator
+    # route a hover-prefetch request to its own, tighter budget -- see
+    # _request_probe_limit above -- flask-limiter re-evaluates it on
+    # every request rather than once at decoration time.
+    if not cfg.probe_rate_limit and not cfg.prefetch_rate_limit:
+        return view
+    return limiter.limit(_request_probe_limit)(view)
+
+
+def _admin_login_rate_limit(view):
+    # Independent of _probe_rate_limit above -- /admin/login is a
+    # brute-forceable shared-secret check, not a CPU-bound probe, so it
+    # gets its own (much tighter) limit rather than reusing or being
+    # covered by PROBE_RATE_LIMIT.
+    if not cfg.admin_login_rate_limit:
+        return view
+    return limiter.limit(cfg.admin_login_rate_limit)(view)
+
+
+@app.errorhandler(429)
+def rate_limit_exceeded(e: Exception) -> tuple:
+    return jsonify({
+        "error": "Too many requests. Please slow down and try again shortly.",
+    }), 429
+
+
+# ── Tablebase + thread pool ───────────────────────────────────────────────────
+# All material, including castling and recursive dependencies, uses the
+# same ordered source list. The adapter shares one decoded-block cache.
+try:
+    _tb_source = tablebase_router.open_many(
+        cfg.tablebase_path, label="TABLEBASE_PATH", cfg=cfg,
+        remote_source=remote_source, remote_direct=remote_direct,
+        remote_download=remote_fallback,
+    )
+except Exception as e:
+    log.warning("Failed to open TABLEBASE_PATH: %s", e)
+    _tb_source = None
+
+TB = (
+    tablebase_router.SourcedTablebase(
+        _tb_source, remote_source=remote_source,
+        block_cache_bytes=cfg.block_cache_bytes,
+    )
+    if _tb_source is not None else None
+)
+
+_executor = ThreadPoolExecutor(max_workers=cfg.probe_threads, thread_name_prefix="tb_probe")
+log.info(
+    "Thread pool: %d workers, parallel_threshold=%d, timeout=%.0fs, "
+    "eval_cache=%d, probe_cache=%d, block_cache_bytes=%d",
+    cfg.probe_threads, cfg.parallel_threshold, cfg.probe_timeout,
+    cfg.evaluate_cache_size, cfg.probe_cache_size, cfg.block_cache_bytes,
+)
+
+
+@atexit.register
+def _close_tb() -> None:
+    try:
+        if TB is not None:
+            TB.close()
+    except Exception as e:
+        log.warning("Error closing tablebase: %s", e)
+
+
+@atexit.register
+def _shutdown_executor() -> None:
+    try:
+        _executor.shutdown(wait=True, cancel_futures=True)
+    except Exception as e:
+        log.warning("Error shutting down thread pool: %s", e)
+
+
+# ── Security headers ──────────────────────────────────────────────────────────
+
+@app.after_request
+def set_security_headers(response: Response) -> Response:
+    # base-uri and form-action are set explicitly since default-src doesn't
+    # cover them; object-src, though covered, is set to 'none' since the app
+    # has no use for <object>/<embed>. Allow Hugging Face's Space page
+    # to embed the application; CSP controls the permitted ancestors.
+    response.headers["Content-Security-Policy"] = (
+        "default-src 'self'; script-src 'self'; "
+        "style-src 'self' 'unsafe-inline'; "
+        "font-src 'self'; img-src 'self' data:; connect-src 'self'; "
+        "object-src 'none'; base-uri 'self'; form-action 'self'; "
+        "frame-ancestors 'self' https://huggingface.co;"
+    )
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+    return response
+
+
+# ── Admin authentication ────────────────────────────────────────────────────
+# Gates /admin and /admin/cache/* behind cfg.admin_token (see config.py's
+# "Admin" section). Two ways to authenticate:
+#   - Browser: POST /admin/login with the token starts a signed session
+#     cookie (see app.secret_key above); subsequent requests from the same
+#     browser are authenticated via that cookie automatically.
+#   - API client: send "Authorization: Bearer <ADMIN_TOKEN>" directly,
+#     no session/cookie needed.
+# If cfg.admin_token is empty, every admin route responds 503 rather than
+# running with no password -- there is no "admin panel open to everyone"
+# fallback.
+
+def _admin_token_matches(candidate: str) -> bool:
+    # hmac.compare_digest for constant-time comparison -- a plain `==`
+    # would leak the token's length/prefix through response-timing
+    # differences to an attacker making repeated guesses.
+    return bool(cfg.admin_token) and hmac.compare_digest(candidate, cfg.admin_token)
+
+
+def _is_admin_authenticated() -> bool:
+    if session.get("admin_ok"):
+        return True
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        return _admin_token_matches(auth_header[len("Bearer "):])
+    return False
+
+
+def _require_admin(view):
+    @wraps(view)
+    def wrapped(*args, **kwargs):
+        if not cfg.admin_token:
+            return jsonify({
+                "error": "Admin panel disabled: ADMIN_TOKEN is not configured.",
+            }), 503
+        if not _is_admin_authenticated():
+            return jsonify({"error": "Admin authentication required."}), 401
+        return view(*args, **kwargs)
+    return wrapped
+
+
+# ── FEN normalisation ─────────────────────────────────────────────────────────
+
+_FEN_FIELD_DEFAULTS = ("8/8/8/8/8/8/8/8", "w", "-", "-", "0", "1")
+
+
+def _normalize_fen(fen: str) -> str:
+    parts = fen.split()
+    while len(parts) < 6:
+        parts.append(_FEN_FIELD_DEFAULTS[len(parts)])
+    return " ".join(parts[:6])
+
+
+# ── Sort helpers ──────────────────────────────────────────────────────────────
+
+_OUTCOME_RANK: dict[int, int] = {2: 0, 1: 1, 0: 2, -1: 3, -2: 4}
+_PROMOTION_RANK = {"Q": 0, "R": 1, "B": 2, "N": 3}
+
+
+def _move_tiebreak(san: str) -> tuple[int, str, int, str]:
+    """Prefer immediate mate, then SAN order with Q/R/B/N promotions.
+
+    The SAN prefix groups promotions along the same path. This key is
+    used only after the metric's outcome, DTC order, and distance, so a
+    better underpromotion still beats a worse queen promotion. Immediate
+    mate must beat a tied zeroing/conversion move (DTZ/DTC can score both
+    as one ply), including when the mating move is an underpromotion.
+    """
+    mate_rank = 0 if san.endswith("#") else 1
+    prefix, separator, promotion = san.partition("=")
+    if separator:
+        return mate_rank, prefix, _PROMOTION_RANK[promotion[0]], promotion[1:]
+    return mate_rank, san, 0, ""
+
+
+def _outcome_rank(wdl_val: int) -> int:
+    return _OUTCOME_RANK[wdl_val]
+
+
+def _ply_rank(wdl_val: int, eff_val: int) -> int:
+    if wdl_val > 0:  return eff_val
+    if wdl_val < 0:  return -abs(eff_val)
+    return 0
+
+
+def _order_rank(wdl_val: int, order: int) -> int:
+    """Sort key for DTC's "pushes still owed" component. DTC's own notion
+    of a better line is pushes first, then plies (see ProbeResult's
+    docstring in chess.chesstb): fewer pushes owed is better while
+    winning, more is better while losing (it's more delay bought before
+    the opponent's own clock forces a conversion). order is already an
+    unsigned count, so - unlike _ply_rank - there's no magnitude to
+    unwrap, only a direction to apply."""
+    if wdl_val > 0:  return order
+    if wdl_val < 0:  return -order
+    return 0
+
+
+_WDL_TO_OUTCOME_LABEL: dict[int, str] = {
+    2: "win", 1: "cursed_win", 0: "draw", -1: "blessed_loss", -2: "loss",
+}
+
+
+def _outcome_label(wdl_val: int) -> str:
+    return _WDL_TO_OUTCOME_LABEL[wdl_val]
+
+
+def _effective_move_wdl(move_wdl: int, root_wdl: int, eff_distance: int) -> int:
+    """The win/cursed-win (or loss/blessed-loss) bucket a move belongs in,
+    used for both its outcome label and its sort-key rank. A raw win/loss
+    (move_wdl 2/-2) downgrades to cursed_win/blessed_loss (1/-1) when its
+    own eff_distance exceeds chesstb.MAX_NON_CURSED_DTZ. The result is then capped
+    at root_wdl, since a move can never be better than the root position's
+    own optimal value - this cap is one-directional, as a move can be
+    worse than root_wdl (e.g. a blunder turning a blessed_loss root into a
+    pure -2 loss). Draws pass through unchanged."""
+    if abs(eff_distance) > chesstb.MAX_NON_CURSED_DTZ:
+        if move_wdl == 2:
+            move_wdl = 1
+        elif move_wdl == -2:
+            move_wdl = -1
+    return _capped_wdl(move_wdl, root_wdl)
+
+
+def _effective_distance(wdl: int, raw_distance: int) -> int:
+    if wdl != 0 and raw_distance == 0:
+        return 1 if wdl > 0 else -1
+    if raw_distance > 0:
+        return raw_distance + 1
+    if raw_distance < 0:
+        return raw_distance - 1
+    return 0
+
+
+def _is_cursed_exit(parent: chess.Board, child: chess.Board, child_wdl: int) -> bool:
+    """True when a move into a cursed or blessed child (signed child_wdl)
+    gives up castling rights."""
+    return (abs(child_wdl) == 1
+            and chess.popcount(child.clean_castling_rights())
+            < chess.popcount(parent.clean_castling_rights()))
+
+
+def _capped_wdl(move_wdl: int, root_wdl: int) -> int:
+    """move_wdl capped at root_wdl: a move can never be better than the root
+    position's own optimal value (see _effective_move_wdl). Used by the
+    clock-independent DTZ/DTM columns."""
+    return root_wdl if move_wdl > root_wdl else move_wdl
+
+
+# ── Variant ────────────────────────────────────────────────────────────────
+#
+# "standard" | "chess960". Chess960 changes only the interpretation of
+# castling rights/moves -- board geometry, piece movement, and tablebase
+# material selection are unaffected (see tablebase_router.py, unchanged by
+# variant). The two rulesets are never inferred from a FEN's contents: the
+# orthodox starting array is itself one of the 960 legal Chess960 starting
+# arrangements, so the same FEN text is genuinely ambiguous without this
+# explicit field. An omitted variant defaults to "standard".
+_ALLOWED_VARIANTS = frozenset({"standard", "chess960"})
+
+
+def _normalize_variant(value: object) -> str:
+    if value is None:
+        return "standard"
+    if not isinstance(value, str):
+        raise ValueError("variant must be a string.")
+    normalized = value.strip().lower()
+    if normalized not in _ALLOWED_VARIANTS:
+        raise ValueError("Unsupported variant: expected 'standard' or 'chess960'.")
+    return normalized
+
+
+def _build_board(variant: str, fen: str) -> chess.Board:
+    """The single place a chess.Board is constructed from a request- or
+    move-generation-supplied FEN string. chess960=True changes only how
+    the fork parses/serializes the castling field and how it represents
+    castling moves -- everything else about the resulting Board (piece
+    movement, check/mate detection, piece_map, etc.) behaves identically
+    to the variant="standard" path."""
+    return chess.Board(fen, chess960=(variant == "chess960"))
+
+
+# ── FEN pre-validation ────────────────────────────────────────────────────────
+
+_EP_PATTERN = re.compile(r"^(-|[a-h][36])$")
+_CASTLING_PATTERN_STANDARD = re.compile(r"^K?Q?k?q?$")
+# Chess960 castling rights use conventional K/Q/k/q where applicable and
+# rook-file letters for explicit rook identification. Semantic validity is
+# checked after board construction.
+_CASTLING_PATTERN_CHESS960 = re.compile(r"^[A-Ha-hKQkq]{1,4}$")
+
+
+def _validate_fen_parts(variant: str, parts: list[str]) -> str | None:
+    if len(parts) < 2:
+        return "FEN must have at least a piece-placement field and a side-to-move field."
+    if parts[1] not in ("w", "b"):
+        return f"Invalid side to move: '{parts[1]}' (expected 'w' or 'b')."
+    if len(parts) >= 3 and parts[2] != "-":
+        if variant == "chess960":
+            if not _CASTLING_PATTERN_CHESS960.match(parts[2]):
+                return (
+                    f"Invalid castling availability: '{parts[2]}' (expected some combination "
+                    "of 'K', 'Q', 'k', 'q', rook-file letters 'a'-'h'/'A'-'H', or '-')."
+                )
+        elif not _CASTLING_PATTERN_STANDARD.match(parts[2]):
+            return (
+                f"Invalid castling availability: '{parts[2]}' "
+                "(expected some combination of 'K', 'Q', 'k', 'q', or '-')."
+            )
+    if len(parts) >= 4 and not _EP_PATTERN.match(parts[3]):
+        return (
+            f"Invalid en-passant square: '{parts[3]}' "
+            "(expected '-' or a valid target square such as 'e3' or 'd6')."
+        )
+    if len(parts) >= 5:
+        try:
+            hmc = int(parts[4])
+            if hmc < 0:
+                return "Halfmove clock must be a non-negative integer."
+        except ValueError:
+            return f"Invalid halfmove clock: '{parts[4]}' (expected a non-negative integer)."
+    if len(parts) >= 6:
+        try:
+            fmc = int(parts[5])
+            if fmc < 1:
+                return "Fullmove number must be a positive integer."
+        except ValueError:
+            return f"Invalid fullmove number: '{parts[5]}' (expected a positive integer)."
+    return None
+
+
+# ── Signed-value helpers ──────────────────────────────────────────────────────
+#
+# WIN/CURSED_WIN/DRAW/BLESSED_LOSS/LOSE -> +2/+1/0/-1/-2, matching
+# chess.syzygy's convention -- built from chess.chesstb's public class
+# constants rather than its private _WDL_SIGNED, since this app has no
+# reason to depend on a leading-underscore upstream symbol for a five-entry
+# map it can just as easily own. This is what _probe_board below builds its
+# signed wdl/dtc_wdl/dtm50_wdl fields on.
+
+_SIGNED_WDL: dict[int, int] = {
+    chesstb.WIN: 2, chesstb.CURSED_WIN: 1, chesstb.DRAW: 0,
+    chesstb.BLESSED_LOSS: -1, chesstb.LOSE: -2,
+}
+
+
+def _signed_wdl(wdl: int) -> int | None:
+    """Signed WDL for a raw wdl/dtc_wdl/dtm50_wdl class value."""
+    return _SIGNED_WDL.get(wdl)
+
+
+# ── Raw probe ─────────────────────────────────────────────────────────────────
+
+def _probe_board(board: chess.Board) -> chesstb.ProbeResult | None:
+    # A single combined probe() call computes WDL + DTZ + DTC + DTM + DTM50
+    # together. The raw ProbeResult is returned as-is: its constructor
+    # zero-initialises dtz/dtc_order/dtc/dtm/dtm50 and sets
+    # wdl/dtc_wdl/dtm50_wdl to ILLEGAL whenever the matching has_* flag is
+    # False, and _signed_wdl() maps ILLEGAL to None. WDL is the only metric
+    # required - a position whose WDL can't be resolved is not probeable and
+    # returns None. DTZ, DTC, DTM, and DTM50 are each independently
+    # optional; has_dtz/has_dtc/has_dtm/has_dtm50 report which of the four
+    # the loaded tables answered for this position.
+    r = TB.probe(board)
+    if r.status != "ok" or _signed_wdl(r.wdl) is None:
+        return None
+    return r
+
+
+# ── Child-position probe cache ────────────────────────────────────────────────
+
+class ProbeInFlightTimeout(Exception):
+    """A probe of this FEN was already running and didn't finish in time.
+    Retryable, exactly like the probe having timed out directly."""
+
+
+class _InFlightProbe:
+    """Slot for one probe in progress. The thread that creates it does the
+    probing; every other thread asking for the same FEN waits on it."""
+
+    __slots__ = ("done", "result", "error")
+
+    def __init__(self) -> None:
+        self.done   = threading.Event()
+        self.result: chesstb.ProbeResult | None = None
+        self.error:  BaseException | None = None
+
+
+_inflight_lock = threading.Lock()
+_inflight: dict[tuple[str, str], _InFlightProbe] = {}   # (variant, fen) -> slot
+
+# Set (per calling thread) by _probe_fen_with_deadline below, so
+# _probe_fen_deduped's in-flight wait can use a request's own remaining
+# deadline instead of a fresh cfg.probe_timeout -- see that function's
+# docstring for why a plain module-level value wouldn't work here. .board
+# is set the same way, for the same reason, when the caller already has a
+# chess.Board built from this exact fen in scope -- see
+# _probe_fen_with_deadline's board parameter.
+_probe_tls = threading.local()
+
+
+def _probe_fen_deduped(variant: str, fen: str) -> chesstb.ProbeResult | None:
+    """Runs at most one probe per (variant, fen) at a time, however many
+    callers ask.
+
+    _probe_fen's lru_cache only dedupes probes that have already finished:
+    concurrent callers all miss it and all probe the same position. That
+    happens routinely: /probe/stream pre-warms a child FEN that
+    evaluate_all_moves then asks for again, and a retry after a timeout
+    re-asks for a FEN whose first probe is still running. Each duplicate costs
+    a full remote probe and occupies a pool worker.
+
+    A non-owner's wait is bounded by the calling thread's own remaining
+    deadline (see _probe_fen_with_deadline) so one hung probe can't pin a
+    waiter beyond its own request's budget -- falling back to a fresh
+    cfg.probe_timeout when no deadline was set, for a caller reached
+    outside a deadline-aware path. The wait expiring raises, which reads
+    downstream as a retryable failure just like the probe itself timing out.
+
+    The owner builds the chess.Board to probe from (variant, fen) itself
+    unless the calling thread already left one in _probe_tls.board (see
+    _probe_fen_with_deadline's board parameter) -- for a root-fen probe,
+    the caller has usually already built one anyway (to validate the FEN,
+    render the board, etc.), and re-parsing the same string a second time
+    here is pure waste. variant is required even when board is supplied,
+    since it is also this function's in-flight/dedup key -- the same FEN
+    text probes to a different (and possibly incompatible) result under
+    Standard vs Chess960 rules (see the module-level variant comment), so
+    a key of fen alone would let one variant's probe be served to the
+    other's caller.
+    """
+    deadline = getattr(_probe_tls, "deadline", None)
+    if deadline is not None and time.monotonic() >= deadline:
+        raise ProbeInFlightTimeout("Probe deadline expired before work started")
+    key = (variant, fen)
+    with _inflight_lock:
+        slot = _inflight.get(key)
+        if slot is None:
+            slot = _inflight[key] = _InFlightProbe()
+            owner = True
+        else:
+            owner = False
+
+    if not owner:
+        deadline = getattr(_probe_tls, "deadline", None)
+        timeout = (deadline - time.monotonic()) if deadline is not None else cfg.probe_timeout
+        if timeout <= 0 or not slot.done.wait(max(0, timeout)):
+            raise ProbeInFlightTimeout(f"Timed out waiting on an in-flight probe of variant={variant} {fen}")
+        if slot.error is not None:
+            raise slot.error
+        return slot.result
+
+    try:
+        board = getattr(_probe_tls, "board", None)
+        slot.result = _probe_board(board if board is not None else _build_board(variant, fen))
+        return slot.result
+    except BaseException as exc:
+        slot.error = exc
+        raise
+    finally:
+        # Drop the slot before waking the waiters, so a caller arriving in
+        # between starts a fresh probe rather than joining a finished one.
+        with _inflight_lock:
+            _inflight.pop(key, None)
+        slot.done.set()
+
+
+@lru_cache(maxsize=cfg.probe_cache_size)
+def _probe_fen(variant: str, fen: str) -> chesstb.ProbeResult | None:
+    return _probe_fen_deduped(variant, fen)
+
+
+def _probe_fen_with_deadline(
+    variant: str, fen: str, deadline: float | None, board: chess.Board | None = None,
+) -> chesstb.ProbeResult | None:
+    """Calls _probe_fen(variant, fen), but first makes `deadline` (and,
+    optionally, `board`) visible to _probe_fen_deduped's in-flight wait /
+    owner branch on this thread.
+
+    _probe_fen must stay a (variant, fen)-only lru_cache -- adding deadline
+    as a real parameter would make it part of the cache key, and since a
+    deadline is different on every call, that would turn the cache into a
+    permanent miss. A plain thread-local set by the caller doesn't work
+    either when this runs via _executor.submit(_probe_fen_with_deadline,
+    variant, fen, ...): submit() runs the call on a pool worker thread, not
+    the submitting thread, so a thread-local the submitter set wouldn't be
+    visible there. Passing deadline as a real argument to this wrapper --
+    called either directly or as the submitted callable itself -- sidesteps
+    both problems: it's a normal argument up to here, then becomes this
+    worker thread's own thread-local for the duration of the call.
+
+    board is optional and exists purely to avoid re-parsing a FEN this
+    thread already has a chess.Board for -- pass it only when `board` was
+    itself built from this exact (variant, fen) pair, right here, in this
+    same function call's caller, moments before this call. _probe_fen_deduped
+    has no way to verify the two actually match (board.fen() isn't
+    reliably equal to a shortened/unpadded input fen string, so comparing
+    them isn't a safety net either), so passing a board that doesn't
+    correspond to (variant, fen) silently returns a wrong probe result.
+    Child boards copied by _collect_move_info() satisfy the same contract.
+    """
+    _probe_tls.deadline = deadline
+    _probe_tls.board = board
+    try:
+        return _probe_fen(variant, fen)
+    finally:
+        _probe_tls.deadline = None
+        _probe_tls.board = None
+
+
+
+# ── Move evaluation ───────────────────────────────────────────────────────────
+
+def _apply_sign(magnitude: int, sign_wdl: int) -> int:
+    """Gives an unsigned ply magnitude the sign implied by a signed WDL
+    value: positive for a winning sign_wdl, negative for a losing one,
+    zero for a draw. Shared by every DTZ/DTC/DTM/DTM50 assembly step in
+    evaluate_all_moves below, so the four metrics can't drift apart on
+    how a magnitude gets its sign."""
+    if sign_wdl > 0:
+        return magnitude
+    if sign_wdl < 0:
+        return -magnitude
+    return 0
+
+
+def _collect_move_info(board: chess.Board) -> list[tuple[str, bool, bool, bool, str | None, str | None, chess.Board | None]]:
+    move_info: list[tuple[str, bool, bool, bool, str | None, str | None, chess.Board | None]] = []
+    for move in board.legal_moves:
+        san = board.san(move)
+        # Bypasses expensive Board.is_checkmate() checks by parsing the SAN string directly
+        move_is_mate = san.endswith("#")
+        move_is_zeroing = board.is_zeroing(move)
+        # DTC's own notion of "conversion" (a capture or a promotion) is
+        # narrower than move_is_zeroing (capture OR any pawn move): a quiet
+        # pawn push zeroes the clock too, but chess.chesstb.Tablebase.
+        # _dtc_move_kind does not treat it as a conversion, only as one of
+        # the pushes the winning side still owes (see the DTC row below,
+        # this field's only consumer). is_capture() rather than a bare
+        # to-square occupancy check so an
+        # en passant capture - whose destination square is empty - still
+        # counts as a conversion here.
+        move_is_conversion = board.is_capture(move) or move.promotion is not None
+        draw_reason: str | None = None
+        child_board: chess.Board | None = None
+        board.push(move)
+        try:
+            if not move_is_mate:
+                # Bypasses Board.is_stalemate() by stopping at the first legal move found
+                if not any(board.generate_legal_moves()):
+                    draw_reason = "stalemate"
+                elif board.is_insufficient_material():
+                    draw_reason = "insufficient_material"
+            child_fen: str | None = None if (move_is_mate or draw_reason) else board.fen()
+            if child_fen is not None:
+                # Upstream probes positions, not repetition history. Preserve
+                # the clock, en passant and Chess960 state without the stack.
+                child_board = board.copy(stack=False)
+        finally:
+            board.pop()
+        move_info.append((san, move_is_mate, move_is_zeroing, move_is_conversion, draw_reason, child_fen, child_board))
+    return move_info
+
+
+def evaluate_all_moves(
+    board: chess.Board,
+    root_wdl: int,
+    variant: str = "standard",
+    bypass_parallel: bool = False,
+    precomputed_move_info: list[tuple[str, bool, bool, bool, str | None, str | None, chess.Board | None]] | None = None,
+    deadline: float | None = None,
+    root_dtz: int | None = None,
+    root_dtz_rounded: bool = False,
+) -> tuple[MoveList, MoveList, MoveList, MoveList, bool, dict[str, int], int | None]:
+    """Returns the four ranked move lists (DTZ, DTC, DTM, DTM50, in that
+    order), a "complete" flag: False when at least one move shows "unknown"
+    for a retryable reason (probe timeout or error) rather than because its
+    table is genuinely absent (callers use it to decide whether the result
+    is worth caching - see evaluate_fen()), the wins/draws/losses/unknown
+    summary across all legal moves, and the root's exact DTZ when
+    cross-checking the moves resolved it (None otherwise).
+
+    root_dtz/root_dtz_rounded are the root's own DTZ, None when its material
+    has no DTZ table. The DTZ rows' rounded values are resolved against them
+    by dtz_anchor.resolve().
+
+    variant applies to every child position probed below, matching the
+    ruleset `board` itself was built under (see _build_board) -- board.push()/
+    pop() inside _collect_move_info already preserves board.chess960 for
+    move generation and child.fen() serialization for free, since it's the
+    same Board object throughout; variant only needs to be threaded through
+    explicitly here because child positions are (re-)probed from their FEN
+    string, not from the Board object itself (see _probe_fen_with_deadline).
+
+    deadline is an absolute time.monotonic() value bounding child probing."""
+    effective_deadline = deadline if deadline is not None else time.monotonic() + cfg.probe_timeout
+
+    # Phase 1: collect move metadata (no TB calls) - reuses the caller's own
+    # pass over board.legal_moves() when one is supplied, instead of
+    # re-walking every legal move a second time for the same board.
+    move_info = precomputed_move_info if precomputed_move_info is not None else _collect_move_info(board)
+
+    # Phase 2: probe child positions
+    unique_fens: set[str] = {child_fen for _, _, _, _, _, child_fen, _ in move_info if child_fen is not None}
+    probe_cache: dict[str, chesstb.ProbeResult | None] = {}
+    child_boards: dict[str, chess.Board] = {
+        child_fen: child_board
+        for _, _, _, _, _, child_fen, child_board in move_info
+        if child_fen is not None and child_board is not None
+    }
+
+    # Child FENs that failed for a retryable reason. A probe that timed out is
+    # still running in the pool and will populate _probe_fen's own cache, so a
+    # later attempt at this position resolves it; a probe that raised may
+    # succeed on a retry too. Neither is the same as _probe_fen returning None,
+    # which means tb_not_found and won't change however often it's re-probed.
+    transient_failures: set[str] = set()
+
+    # Probe sufficiently large uncached batches through the thread pool.
+    if len(unique_fens) >= cfg.parallel_threshold and not bypass_parallel:
+        futures = {
+            fen: _executor.submit(
+                _probe_fen_with_deadline, variant, fen, effective_deadline, child_boards.get(fen)
+            )
+            for fen in unique_fens
+        }
+        remaining = max(0.0, effective_deadline - time.monotonic())
+        done, _ = futures_wait(
+            futures.values(), timeout=remaining, return_when=ALL_COMPLETED
+        )
+        for fen, fut in futures.items():
+            if fut in done:
+                try:
+                    probe_cache[fen] = fut.result()
+                except Exception as exc:
+                    log.warning("Probe error for variant=%s %s: %s", variant, fen, exc)
+                    probe_cache[fen] = None
+                    transient_failures.add(fen)
+            else:
+                fut.cancel()  # Drop queued work; running probes can still warm the cache.
+                log.warning("Probe timed out for variant=%s %s", variant, fen)
+                probe_cache[fen] = None
+                transient_failures.add(fen)
+    else:
+        # Probe smaller batches, and batches whose children are already cached,
+        # sequentially to avoid unnecessary thread-pool overhead.
+        for fen in unique_fens:
+            try:
+                probe_cache[fen] = _probe_fen_with_deadline(
+                    variant, fen, effective_deadline, child_boards.get(fen)
+                )
+            except Exception as exc:
+                log.warning("Probe error for variant=%s %s: %s", variant, fen, exc)
+                probe_cache[fen] = None
+                transient_failures.add(fen)
+
+    # Phase 3: assemble and sort
+    dtz_rows:   list[tuple] = []
+    dtc_rows:   list[tuple] = []
+    dtm_rows:   list[tuple] = []
+    dtm50_rows: list[tuple] = []
+
+    # Summary outcomes respect each child's halfmove clock. DTM50 and DTC
+    # already resolve the rule; clock-independent WDL cannot establish a
+    # rule50 win or loss when both of those metrics are unavailable.
+    move_outcomes: list[str] = []
+
+    # Sort key/entry pair for a move whose own metric table doesn't cover
+    # it: flatly "Not Available", the same shape for DTZ, DTC, DTM, and
+    # DTM50 alike rather than a value borrowed from another metric.
+    # has_order adds DTC's extra pushes-owed slot to the sort key.
+    def _not_available(
+        san: str, child_fen: str | None, move_is_mate: bool,
+        draw_reason: str | None, has_order: bool = False,
+    ) -> tuple[tuple, MoveEntry]:
+        key = (
+            (_outcome_rank(0) + 10, 0, 0, _move_tiebreak(san)) if has_order
+            else (_outcome_rank(0) + 10, 0, _move_tiebreak(san))
+        )
+        entry: MoveEntry = {
+            "san": san, "plies": 0, "order": 0, "is_mate": move_is_mate, "available": False,
+            "outcome": "not_available", "child_fen": child_fen, "draw_reason": draw_reason,
+        }
+        return key, entry
+
+    def _dtz_row(
+        san: str, my_wdl: int, eff_dtz: int, rounded: bool, move_is_mate: bool,
+        child_fen: str | None, draw_reason: str | None,
+    ) -> tuple[tuple, DtzMoveEntry, int]:
+        eff_wdl = _effective_move_wdl(my_wdl, root_wdl, eff_dtz)
+        key = (_outcome_rank(eff_wdl), _ply_rank(eff_wdl, eff_dtz), _move_tiebreak(san))
+        entry: DtzMoveEntry = {
+            "san": san, "plies": abs(eff_dtz), "order": 0, "is_mate": move_is_mate, "available": True,
+            "outcome": _outcome_label(eff_wdl), "child_fen": child_fen, "draw_reason": draw_reason,
+            "rounded": rounded,
+        }
+        return key, entry, eff_wdl
+
+    dtz_moves: list[_DtzMove] = []
+    dtz_complete = True
+
+    for san, move_is_mate, move_is_zeroing, move_is_conversion, draw_reason, child_fen, child_board in move_info:
+
+        if move_is_mate:
+            opp_wdl = opp_dtc_wdl = opp_dtm50_wdl = -2
+            opp_dtz = opp_dtc = opp_dtc_order = opp_dtm = opp_dtm50 = 0
+            opp_has_dtz = opp_has_dtc = opp_has_dtm = opp_has_dtm50 = True
+            opp_dtz_rounded = False
+
+        elif draw_reason:
+            opp_wdl = opp_dtc_wdl = opp_dtm50_wdl = 0
+            opp_dtz = opp_dtc = opp_dtc_order = opp_dtm = opp_dtm50 = 0
+            opp_has_dtz = opp_has_dtc = opp_has_dtm = opp_has_dtm50 = True
+            opp_dtz_rounded = False
+
+        else:
+            probe_result = probe_cache.get(child_fen)
+            if probe_result is None:
+                log.warning("No probe result for %s (%s); showing unknown.", child_fen, san)
+                stub: MoveEntry = {
+                    "san": san, "plies": 0, "order": 0, "is_mate": False, "available": False,
+                    "outcome": "unknown", "child_fen": child_fen, "draw_reason": None,
+                }
+                stub_key = (_outcome_rank(0) + 10, 0, _move_tiebreak(san))
+                dtc_stub_key = (_outcome_rank(0) + 10, 0, 0, _move_tiebreak(san))
+                dtz_rows.append((stub_key, stub))
+                dtc_rows.append((dtc_stub_key, stub))
+                dtm_rows.append((stub_key, stub))
+                dtm50_rows.append((stub_key, stub))
+                move_outcomes.append("unknown")
+                dtz_complete = False
+                continue
+            opp_wdl = _signed_wdl(probe_result.wdl)
+            opp_has_dtz, opp_dtz = probe_result.has_dtz, probe_result.dtz
+            opp_dtz_rounded = probe_result.dtz_rounded
+            opp_has_dtc = probe_result.has_dtc
+            opp_dtc_wdl = _signed_wdl(probe_result.dtc_wdl)
+            opp_dtc_order, opp_dtc = probe_result.dtc_order, probe_result.dtc
+            opp_has_dtm, opp_dtm = probe_result.has_dtm, probe_result.dtm
+            opp_has_dtm50 = probe_result.has_dtm50
+            opp_dtm50_wdl = _signed_wdl(probe_result.dtm50_wdl)
+            opp_dtm50 = probe_result.dtm50
+
+        my_wdl = -opp_wdl
+        if opp_has_dtm50:
+            summary_wdl = -opp_dtm50_wdl
+        elif opp_has_dtc:
+            summary_wdl = -opp_dtc_wdl
+        else:
+            # Draws, cursed wins and blessed losses are draws under the
+            # rule even without a clock-aware table. True wins/losses
+            # need one of those tables to resolve the remaining budget.
+            summary_wdl = 0 if abs(my_wdl) <= 1 else None
+        move_outcomes.append(
+            "win" if summary_wdl == 2 else
+            "loss" if summary_wdl == -2 else
+            "unknown" if summary_wdl is None else "draw"
+        )
+
+        # DTZ row.
+        if opp_has_dtz:
+            my_dtz = _apply_sign(opp_dtz, my_wdl)
+            # If this move is itself a zeroing move (capture/pawn-push/
+            # promotion), it is the zeroing move, so its DTZ is 1 ply - not
+            # 1 + the child position's own distance to its next
+            # zeroing move, which is what feeding my_dtz straight into
+            # _effective_distance would compute (double-counting a second
+            # zeroing event nobody asked for). _effective_distance
+            # already has a branch for exactly this ("no further distance
+            # needed, the move itself resolves it"), so call it with
+            # raw_distance=0 instead of reimplementing that branch here.
+            cursed_exit = (not move_is_zeroing and child_board is not None
+                           and _is_cursed_exit(board, child_board, opp_wdl))
+            option = dtz_anchor.move_option(opp_dtz, opp_dtz_rounded, move_is_zeroing, cursed_exit)
+            if move_is_zeroing:
+                eff_dtz = _effective_distance(my_wdl, 0)
+            elif cursed_exit:
+                # CORRECTNESS.md Theorem 12.15: a rounded derived child
+                # can be even. Its true exit values then span y+1..y+3;
+                # report y+2 so the displayed error stays within one ply.
+                # option.value still carries the possible true distances
+                # for the anchor, rather than this representative value.
+                exit_dtz = opp_dtz + 2 if opp_dtz_rounded else option.value[0]
+                eff_dtz = _apply_sign(exit_dtz, my_wdl)
+            else:
+                eff_dtz = _effective_distance(my_wdl, my_dtz)
+            dtz_key, dtz_entry, eff_wdl = _dtz_row(
+                san, my_wdl, eff_dtz, len(set(option.value)) > 1, move_is_mate, child_fen, draw_reason,
+            )
+            outcome = dtz_entry["outcome"]
+            dtz_rows.append((dtz_key, dtz_entry))
+            dtz_moves.append(_DtzMove(len(dtz_rows) - 1, my_wdl, eff_wdl == root_wdl, option))
+        else:
+            dtz_rows.append(_not_available(san, child_fen, move_is_mate, draw_reason))
+            dtz_complete = False
+
+        # DTC row. DTC's own notion of a better move is pushes-owed first, then
+        # plies (see _order_rank's docstring), so the sort key carries both,
+        # unlike DTZ/DTM/DTM50 above and below which only ever compare
+        # plies.
+        #
+        # A capture or a promotion (move_is_conversion) is the conversion,
+        # at this move: 0 pushes still owed, 1 ply to get there - the
+        # child's own pushes/plies describe its next, later conversion,
+        # which is irrelevant once this one has already happened.
+        #
+        # A quiet pawn push zeroes the clock too (move_is_zeroing) but is
+        # not a conversion - chess.chesstb.Tablebase._dtc_move_kind treats
+        # it as spending one of the pushes still owed rather than settling
+        # the count, so the wait still resets to 1 ply the same way a
+        # conversion's does, but pushes owed does not reset to 0.
+        #
+        # The child is probed at its own halfmove clock (see _probe_board)
+        # and its dtc_order counts pushes owed from that position onward,
+        # so it does not include the push spent getting there. For a root
+        # reporting dtc_order=N whose best move is a push, the child
+        # reports dtc_order=N-1; the +1 below restores the push this move
+        # spent.
+        #
+        # Whether the +1 applies depends on which side is pushing: dtc_order
+        # counts the pushes still owed by whichever side is winning, and
+        # only the WINNING side's own push spends one of them. A defensive
+        # push by the losing side leaves that budget untouched, so it
+        # carries the child's order over unchanged, same as a quiet move;
+        # hence the my_dtc_wdl > 0 guard below.
+        if opp_has_dtc:
+            my_dtc_wdl = -opp_dtc_wdl
+            if move_is_mate or draw_reason or move_is_conversion:
+                # A capture, a promotion, checkmate, or an immediate draw
+                # are all fully resolved right here: 0 pushes still owed,
+                # 1 ply to get there. move_is_mate/draw_reason already
+                # hardwire opp_dtc_order/opp_dtc to 0 above, so this is a
+                # no-op arithmetically for those in the ordinary case - it
+                # matters for the case where the move is also a quiet
+                # pawn push, e.g. checkmate delivered by discovered check
+                # from a pawn advance that neither captures nor promotes.
+                # Without this guard that would fall into the push branch
+                # below and pick up a spurious +1: mate ends the game, so
+                # nothing is owed no matter how the pawn got there.
+                raw_order = 0
+                eff_dtc = _effective_distance(my_dtc_wdl, 0)
+            elif move_is_zeroing:  # a quiet pawn push, not a conversion
+                raw_order = opp_dtc_order + (1 if my_dtc_wdl > 0 else 0)
+                eff_dtc = _effective_distance(my_dtc_wdl, 0)
+            else:
+                raw_order = opp_dtc_order
+                my_dtc = _apply_sign(opp_dtc, my_dtc_wdl)
+                eff_dtc = _effective_distance(my_dtc_wdl, my_dtc)
+            # A draw has nothing owed regardless of the raw push count
+            # above - e.g. a defensive push into a dead draw (stalemate,
+            # insufficient material, or a budget that no longer fits the
+            # clock) must not report a nonzero push count just because it
+            # happened to be a push; _order_rank sorts it correctly either
+            # way (it treats wdl_val == 0 as rank 0 regardless), but the
+            # value shown to the client should read 0 like plies does.
+            eff_order = raw_order if my_dtc_wdl != 0 else 0
+            dtc_key = (
+                _outcome_rank(my_dtc_wdl),
+                _order_rank(my_dtc_wdl, eff_order),
+                _ply_rank(my_dtc_wdl, eff_dtc),
+                _move_tiebreak(san),
+            )
+            dtc_rows.append((dtc_key, {
+                "san": san, "plies": abs(eff_dtc), "order": eff_order, "is_mate": move_is_mate,
+                "available": True, "outcome": _outcome_label(my_dtc_wdl),
+                "child_fen": child_fen, "draw_reason": draw_reason,
+            }))
+        else:
+            dtc_rows.append(_not_available(san, child_fen, move_is_mate, draw_reason, has_order=True))
+
+        # DTM row.
+        if opp_has_dtm:
+            my_dtm = _apply_sign(opp_dtm, my_wdl)
+            eff_dtm = _effective_distance(my_wdl, my_dtm)
+            if opp_has_dtz:
+                # DTZ and DTM share the same win/cursed-win (loss/blessed-
+                # loss) bucket and label as the DTZ row above, since that
+                # status is a single fact about eff_dtz and root_wdl rather
+                # than a separate one per metric.
+                dtm_key = (_outcome_rank(eff_wdl), _ply_rank(eff_wdl, eff_dtm), _move_tiebreak(san))
+                dtm_outcome = outcome
+            else:
+                # Without DTZ the bucket comes from WDL alone.
+                dtm_eff_wdl = _capped_wdl(my_wdl, root_wdl)
+                dtm_key = (_outcome_rank(dtm_eff_wdl), _ply_rank(dtm_eff_wdl, eff_dtm), _move_tiebreak(san))
+                dtm_outcome = _outcome_label(dtm_eff_wdl)
+            dtm_rows.append((dtm_key, {
+                "san": san, "plies": abs(eff_dtm), "order": 0, "is_mate": move_is_mate, "available": True,
+                "outcome": dtm_outcome, "child_fen": child_fen, "draw_reason": draw_reason,
+            }))
+        else:
+            dtm_rows.append(_not_available(san, child_fen, move_is_mate, draw_reason))
+
+        # DTM50 row.
+        if opp_has_dtm50:
+            my_dtm50_wdl = -opp_dtm50_wdl
+            my_dtm50 = _apply_sign(opp_dtm50, my_dtm50_wdl)
+            eff_dtm50 = _effective_distance(my_dtm50_wdl, my_dtm50)
+            dtm50_key = (_outcome_rank(my_dtm50_wdl), _ply_rank(my_dtm50_wdl, eff_dtm50), _move_tiebreak(san))
+            dtm50_rows.append((dtm50_key, {
+                "san": san, "plies": abs(eff_dtm50), "order": 0, "is_mate": move_is_mate, "available": True,
+                "outcome": _outcome_label(my_dtm50_wdl), "child_fen": child_fen, "draw_reason": draw_reason,
+            }))
+        else:
+            dtm50_rows.append(_not_available(san, child_fen, move_is_mate, draw_reason))
+
+    # Cross-check rounded DTZ values against each other; skipped when any move
+    # lacks a DTZ, since that move could be the one supplying the root's value.
+    resolved_dtz: int | None = None
+    if dtz_complete and root_dtz is not None and root_wdl != 0:
+        keepers = [m for m in dtz_moves if m.keeps_class]
+        if root_dtz_rounded or any(len(set(m.option.value)) > 1 for m in keepers):
+            resolution = dtz_anchor.resolve(
+                root_dtz, root_dtz_rounded, [m.option for m in keepers], root_wdl > 0,
+            )
+            resolved_dtz = resolution.root
+            for k, value in resolution.pinned.items():
+                move = keepers[k]
+                row = dtz_rows[move.row][1]
+                dtz_rows[move.row] = _dtz_row(
+                    row["san"], move.my_wdl, _apply_sign(value, move.my_wdl), False,
+                    row["is_mate"], row["child_fen"], row["draw_reason"],
+                )[:2]
+
+    dtz_rows.sort(key=lambda r: r[0])
+    dtc_rows.sort(key=lambda r: r[0])
+    dtm_rows.sort(key=lambda r: r[0])
+    dtm50_rows.sort(key=lambda r: r[0])
+
+    summary = {
+        "wins":    sum(1 for o in move_outcomes if o in ("win", "cursed_win")),
+        "draws":   sum(1 for o in move_outcomes if o == "draw"),
+        "losses":  sum(1 for o in move_outcomes if o in ("loss", "blessed_loss")),
+        "unknown": sum(1 for o in move_outcomes if o == "unknown"),
+    }
+
+    return (
+        [r[1] for r in dtz_rows],
+        [r[1] for r in dtc_rows],
+        [r[1] for r in dtm_rows],
+        [r[1] for r in dtm50_rows],
+        not transient_failures,
+        summary,
+        resolved_dtz,
+    )
+
+
+# ── Root Probe Calculation ────────────────────────────────────────────────────
+
+_evaluate_tls = threading.local()
+
+
+def _validate_and_build_board(variant: str, fen: str) -> chess.Board:
+    """
+    Single authoritative implementation of root-FEN validation, shared by
+    /probe (via evaluate_fen) and /probe/stream (which needs a validated
+    board up front, before it can start emitting SSE progress events).
+    Raises RuntimeError if the tablebase isn't loaded, or ValueError for any
+    FEN/board problem - callers are expected to catch and format those.
+
+    Legality (castling rights matching an actual king/rook pair, no pawns
+    on the back rank, exactly one king per side, etc.) is entirely
+    delegated to board.is_valid() for both variants -- this function adds
+    no Standard-only assumptions of its own (e.g. requiring castling rooks
+    on a1/h1/a8/h8) that would misclassify a legal Chess960 position as
+    invalid. See _build_board for how the variant affects construction.
+    """
+    if TB is None:
+        raise RuntimeError(
+            "Tablebase not initialised. Check TABLEBASE_PATH.")
+
+    parts = fen.split()
+    fmt_error = _validate_fen_parts(variant, parts)
+    if fmt_error:
+        raise ValueError(fmt_error)
+
+    try:
+        board = _build_board(variant, fen)
+    except ValueError as e:
+        raise ValueError(f"Malformed FEN: {e}") from e
+
+    castling_field = parts[2] if len(parts) >= 3 else "-"
+    if variant == "chess960" and castling_field != "-":
+        if board.castling_rights.bit_count() != len(castling_field):
+            raise ValueError("Invalid castling availability: duplicate castling rights.")
+
+    if not board.is_valid():
+        raise ValueError(
+            "Invalid board position (missing kings, adjacent kings, pawn on "
+            "back rank, a castling right with no matching king/rook pair, etc.)."
+        )
+
+    return board
+
+
+def _missing_table_error_payload(variant: str, fen: str) -> dict:
+    """
+    Single authoritative shape for the "position not covered by the loaded
+    tablebase" error, shared by /probe and /probe/stream so the two
+    transports (plain JSON vs SSE) can't drift out of sync on wording,
+    error_code, or how piece_count is computed.
+    """
+    try:
+        piece_count = len(_build_board(variant, fen).piece_map())
+    except Exception:
+        piece_count = None
+    return {
+        "error":       "Position not covered by the loaded tablebase.",
+        "error_code":  "missing_table",
+        "piece_count": piece_count,
+    }
+
+
+class _IncompleteResult(Exception):
+    """Carries a probe result that must not be cached - see evaluate_fen()."""
+
+    def __init__(self, json_str: str) -> None:
+        super().__init__("probe incomplete")
+        self.json_str = json_str
+
+
+def _evaluate_fen_impl(variant: str, fen: str) -> str:
+    """
+    Probes the tablebase for a root FEN and returns a pre-serialized JSON string.
+    Routes the root probe through the same shared _probe_fen cache used for
+    child positions, so a position that was just probed as a child (e.g. the
+    position the user just moved into) is served from cache instead of
+    re-hitting the tablebase.
+
+    (variant, fen) are the cache key, so a caller that already built a
+    board/move_info for this exact pair -- e.g. probe_stream()'s SSE handler,
+    which needs both up front to size its progress bar -- hands them over via _evaluate_tls
+    instead, letting this call skip redoing that work. Ignored on a cache
+    hit, since the function body below never runs in that case.
+
+    Raises _IncompleteResult (carrying the same JSON) when a move came back
+    unknown for a retryable reason, so evaluate_fen() can serve it without
+    caching it.
+    """
+    precomputed_board     = getattr(_evaluate_tls, "board", None)
+    precomputed_move_info = getattr(_evaluate_tls, "move_info", None)
+    board = precomputed_board if precomputed_board is not None else _validate_and_build_board(variant, fen)
+
+    # A fresh cfg.probe_timeout-sized budget for the root probe alone,
+    # independent of how long any earlier phase of the same request (e.g.
+    # probe_stream()'s own pre-warm step) already took, so a slow earlier
+    # phase cannot erode the time this one gets. The child batch below
+    # carries its own equally-sized fresh budget (see child_deadline),
+    # matching the independent-budget-per-phase pattern probe_stream()
+    # applies between its pre-warm step and the root probe above it. The
+    # two independently-budgeted phases put a single /probe request's
+    # worst case at up to 2 * cfg.probe_timeout.
+    root_deadline = time.monotonic() + cfg.probe_timeout
+
+    if board.is_checkmate():
+        return json.dumps({
+            "wdl": -2, "dtz": 0, "dtz_rounded": False, "dtc": [-2, 0, 0], "dtm": 0, "dtm50": [-2, 0],
+            "dtz_available": True, "dtc_available": True, "dtm_available": True, "dtm50_available": True,
+            "moves_dtz": [], "moves_dtc": [], "moves_dtm": [], "moves_dtm50": [],
+            "summary": {"wins": 0, "draws": 0, "losses": 0, "unknown": 0},
+            "draw_reason": None,
+        })
+
+    if board.is_stalemate() or board.is_insufficient_material():
+        return json.dumps({
+            "wdl": 0, "dtz": 0, "dtz_rounded": False, "dtc": [0, 0, 0], "dtm": 0, "dtm50": [0, 0],
+            "dtz_available": True, "dtc_available": True, "dtm_available": True, "dtm50_available": True,
+            "moves_dtz": [], "moves_dtc": [], "moves_dtm": [], "moves_dtm50": [],
+            "summary": {"wins": 0, "draws": 0, "losses": 0, "unknown": 0},
+            "draw_reason": "stalemate" if board.is_stalemate() else "insufficient_material",
+        })
+
+    # Route the root probe through the shared child-probe cache. board was
+    # either handed over via _evaluate_tls or just built above from this
+    # exact fen, so it's passed through here too rather than making
+    # _probe_fen_deduped re-parse the same string a second time.
+    root = _probe_fen_with_deadline(variant, fen, root_deadline, board)
+    if root is None:
+        raise chesstb.MissingTableError(f"Position not in tablebase: variant={variant} {fen}")
+
+    bypass_parallel = getattr(_evaluate_tls, "bypass_parallel", False)
+    # Own fresh budget, not the remainder of root_deadline -- see the
+    # comment above root_deadline.
+    child_deadline = time.monotonic() + cfg.probe_timeout
+    moves_dtz, moves_dtc, moves_dtm, moves_dtm50, complete, summary, resolved_dtz = evaluate_all_moves(
+        board, _signed_wdl(root.wdl), variant, bypass_parallel=bypass_parallel,
+        precomputed_move_info=precomputed_move_info, deadline=child_deadline,
+        root_dtz=root.dtz if root.has_dtz else None, root_dtz_rounded=root.dtz_rounded,
+    )
+    root_dtz, root_dtz_rounded = (
+        (root.dtz, root.dtz_rounded) if resolved_dtz is None else (resolved_dtz, False)
+    )
+
+    # dtz/dtc/dtm/dtm50 are the root's own metrics, each independently
+    # unavailable when this material has no DTZ/DTC/DTM/DTM50 table - see
+    # _probe_board. The paired *_available flag is the authoritative signal
+    # for that; the value fields fall back to null/[null, null(, null)]
+    # rather than being omitted, so every response has the same fixed shape
+    # regardless of coverage. dtc is a 3-tuple [wdl, pushes_owed, plies]
+    # rather than dtm50's pair, since - unlike dtm50 - its distance is
+    # priced in two components, not one; see chess.chesstb.ProbeResult and
+    # the DTC row comment in evaluate_all_moves. root is the raw
+    # ProbeResult _probe_board returns, so its wdl/dtc_wdl/dtm50_wdl are
+    # still the unsigned chess.chesstb class values here - each goes
+    # through _signed_wdl() below, same as every other consumer of a raw
+    # ProbeResult in this file.
+    json_str = json.dumps({
+        "wdl":              _signed_wdl(root.wdl),
+        "dtz":              root_dtz if root.has_dtz else None,
+        "dtz_available":    root.has_dtz,
+        "dtz_rounded":      root_dtz_rounded if root.has_dtz else None,
+        "dtc":              [_signed_wdl(root.dtc_wdl), root.dtc_order, root.dtc] if root.has_dtc else [None, None, None],
+        "dtc_available":    root.has_dtc,
+        "dtm":              root.dtm if root.has_dtm else None,
+        "dtm_available":    root.has_dtm,
+        "dtm50":            [_signed_wdl(root.dtm50_wdl), root.dtm50] if root.has_dtm50 else [None, None],
+        "dtm50_available":  root.has_dtm50,
+        "moves_dtz":        moves_dtz,
+        "moves_dtc":        moves_dtc,
+        "moves_dtm":        moves_dtm,
+        "moves_dtm50":      moves_dtm50,
+        "summary":          summary,
+        "draw_reason":      None,   # root always has legal moves here, so never terminal
+    })
+    if not complete:
+        raise _IncompleteResult(json_str)
+    return json_str
+
+
+# An explicit LRU lets SSE check for a complete response before building
+# boards, walking legal moves or submitting child probes. Failed/incomplete
+# evaluations never enter this cache. Computation stays outside the lock.
+_evaluation_cache: OrderedDict[tuple[str, str], str] = OrderedDict()
+_evaluation_cache_lock = threading.Lock()
+_evaluation_hits = _evaluation_misses = 0
+_EvaluationCacheInfo = namedtuple("CacheInfo", "hits misses maxsize currsize")
+
+
+def _cached_evaluation(variant: str, fen: str, *, count_miss: bool = True) -> str | None:
+    global _evaluation_hits, _evaluation_misses
+    with _evaluation_cache_lock:
+        key = (variant, fen)
+        result = _evaluation_cache.get(key)
+        if result is not None:
+            _evaluation_cache.move_to_end(key)
+            _evaluation_hits += 1
+        elif count_miss:
+            _evaluation_misses += 1
+        return result
+
+
+def evaluate_fen(variant: str, fen: str) -> str:
+    cached = _cached_evaluation(variant, fen)
+    if cached is not None:
+        return cached
+    try:
+        result = _evaluate_fen_impl(variant, fen)
+    except _IncompleteResult as incomplete:
+        return incomplete.json_str
+    with _evaluation_cache_lock:
+        key = (variant, fen)
+        _evaluation_cache[key] = result
+        _evaluation_cache.move_to_end(key)
+        while len(_evaluation_cache) > cfg.evaluate_cache_size:
+            _evaluation_cache.popitem(last=False)
+    return result
+
+
+def _clear_evaluation_cache() -> None:
+    global _evaluation_hits, _evaluation_misses
+    with _evaluation_cache_lock:
+        _evaluation_cache.clear()
+        _evaluation_hits = _evaluation_misses = 0
+
+
+def _evaluation_cache_info():
+    with _evaluation_cache_lock:
+        return _EvaluationCacheInfo(
+            _evaluation_hits, _evaluation_misses, cfg.evaluate_cache_size, len(_evaluation_cache),
+        )
+
+
+evaluate_fen.cache_clear = _clear_evaluation_cache  # type: ignore[attr-defined]
+evaluate_fen.cache_info = _evaluation_cache_info  # type: ignore[attr-defined]
+
+
+# ── Common (variant, FEN) extraction + validation helper ──────────────────────
+
+def _extract_probe_request(data: dict | None) -> tuple[str, str, Response | tuple[Response, int] | None]:
+    """Single authoritative request-body parser shared by /probe and
+    /probe/stream, so the two transports can't drift on what counts as a
+    valid variant/FEN or how each is rejected. Returns (variant, fen,
+    error_response); error_response is None on success and variant/fen are
+    both "" when it isn't."""
+    if not data or "fen" not in data:
+        return "", "", (jsonify({"error": "Missing FEN in request body."}), 400)
+    fen_raw = data["fen"]
+    if not isinstance(fen_raw, str):
+        return "", "", (jsonify({"error": "FEN must be a string."}), 400)
+    fen = fen_raw.strip()
+    if not fen:
+        return "", "", (jsonify({"error": "FEN string is empty."}), 400)
+    if len(fen) > cfg.max_fen_length:
+        return "", "", (jsonify({"error": f"FEN string too long (max {cfg.max_fen_length})."}), 400)
+
+    try:
+        variant = _normalize_variant(data.get("variant"))
+    except ValueError as e:
+        return "", "", (jsonify({"error": str(e)}), 400)
+
+    return variant, _normalize_fen(fen), None
+
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+
+@app.route("/")
+def index() -> str:
+    return render_template("index.html", source_repository_url=cfg.source_repository_url)
+
+
+@app.route("/probe", methods=["POST"])
+@_probe_rate_limit
+def probe() -> Response | tuple[Response, int]:
+    body = request.get_json(silent=True)
+    variant, fen, err = _extract_probe_request(body)
+    if err:
+        return err
+
+    try:
+        json_str = evaluate_fen(variant, fen)
+        return app.response_class(json_str, status=200, mimetype="application/json")
+
+    except chesstb.MissingTableError:
+        return jsonify(_missing_table_error_payload(variant, fen)), 400
+
+    except RuntimeError as e:
+        # Tablebase not initialised (TABLEBASE_PATH failed to load) --
+        # same condition and status code as /health's own "degraded"
+        # response for this, and the same message _validate_and_build_board
+        # raises for /probe/stream to report over SSE.
+        return jsonify({"error": str(e)}), 503
+
+    except ValueError as e:
+        return jsonify({"error": str(e)}), 400
+
+    except _REMOTE_SOURCE_ERROR as e:
+        log.warning("Remote tablebase fetch failed probing variant=%s FEN %s: %s", variant, fen, e)
+        return jsonify({
+            "error": "Could not reach the remote tablebase. Try again shortly.",
+            "error_code": "remote_unavailable",
+        }), 502
+
+    except ProbeInFlightTimeout as e:
+        log.warning("%s", e)
+        return jsonify({
+            "error": "Probe timed out. Try again shortly.",
+            "error_code": "probe_timeout",
+        }), 503
+
+    except Exception:
+        log.exception("Unhandled error probing variant=%s FEN: %s", variant, fen)
+        return jsonify({"error": "Internal server error."}), 500
+
+
+def _stream_error_payload(variant: str, fen: str, exc: BaseException) -> dict:
+    """SSE error payload for an exception raised while probing (variant, fen),
+    keeping wording, error_code, and logging identical no matter which probe
+    step inside probe_stream() raised it."""
+    if isinstance(exc, chesstb.MissingTableError):
+        return {"status": "error", **_missing_table_error_payload(variant, fen)}
+    if isinstance(exc, _REMOTE_SOURCE_ERROR):
+        log.warning("Remote tablebase fetch failed in probe/stream for variant=%s %s: %s", variant, fen, exc)
+        return {
+            "status": "error",
+            "error": "Could not reach the remote tablebase. Try again shortly.",
+            "error_code": "remote_unavailable",
+        }
+    if isinstance(exc, ProbeInFlightTimeout):
+        log.warning("%s", exc)
+        return {
+            "status": "error",
+            "error": "Probe timed out. Try again shortly.",
+            "error_code": "probe_timeout",
+        }
+    log.exception("Error in probe/stream for variant=%s %s", variant, fen)
+    return {"status": "error", "error": str(exc)}
+
+
+@app.route("/probe/stream", methods=["POST"])
+@_probe_rate_limit
+def probe_stream() -> Response | tuple[Response, int]:
+    body = request.get_json(silent=True)
+    variant, fen, err = _extract_probe_request(body)
+    if err:
+        return err
+
+    def _sse(obj: dict) -> str:
+        return f"data: {json.dumps(obj)}\n\n"
+
+    def generate():
+        cached = _cached_evaluation(variant, fen, count_miss=False)
+        if cached is not None:
+            yield 'data: {"status":"done",' + cached[1:] + '\n\n'
+            return
+        # Validated up front (rather than only inside evaluate_fen below) so
+        # the validation error can be reported immediately over SSE instead of
+        # only finding out after pre-warming child positions. Uses the same
+        # _validate_and_build_board() that evaluate_fen() itself calls, so
+        # there's one authoritative implementation of "what makes a FEN
+        # probeable" instead of two hand-written copies that could disagree.
+        try:
+            root_board = _validate_and_build_board(variant, fen)
+        except (RuntimeError, ValueError) as e:
+            yield _sse({"status": "error", "error": str(e)})
+            return
+
+        # A terminal root (checkmate, stalemate, insufficient material) never
+        # reaches the tablebase - see evaluate_fen()'s own early return for
+        # these - so only a non-terminal root needs its coverage confirmed
+        # here. Checking the root before pre-warming any child means a root
+        # the tablebase doesn't cover is caught immediately: no child of an
+        # uncovered root is coverable either, so pre-warming first would only
+        # probe the entire move list to discover that after the fact. This
+        # reads through the same cache evaluate_fen() itself reads below, so
+        # a covered root costs nothing extra downstream.
+        terminal = (
+            root_board.is_checkmate()
+            or root_board.is_stalemate()
+            or root_board.is_insufficient_material()
+        )
+        if not terminal:
+            try:
+                # root_board was just built above from this exact (variant,
+                # fen), so it's passed through here too rather than making
+                # _probe_fen_deduped re-parse the same string a second
+                # time -- see _probe_fen_with_deadline's board parameter.
+                root_probe = _probe_fen_with_deadline(
+                    variant, fen, time.monotonic() + cfg.probe_timeout, root_board,
+                )
+            except Exception as e:
+                yield _sse(_stream_error_payload(variant, fen, e))
+                return
+            if root_probe is None:
+                yield _sse({"status": "error", **_missing_table_error_payload(variant, fen)})
+                return
+
+        # Insufficient-material draws can still have legal moves, but
+        # evaluate_fen returns a terminal response without using children.
+        move_info = [] if terminal else _collect_move_info(root_board)
+        child_fens: set[str] = {
+            child_fen for _, _, _, _, _, child_fen, _ in move_info if child_fen is not None
+        }
+        child_boards: dict[str, chess.Board] = {
+            child_fen: child_board
+            for _, _, _, _, _, child_fen, child_board in move_info
+            if child_fen is not None and child_board is not None
+        }
+
+        total = len(child_fens)
+        yield _sse({"status": "probing", "completed": 0, "total": total})
+
+        # Pre-warm child FENs in parallel using the native non-blocking cache.
+        # Always via the thread pool (regardless of cfg.parallel_threshold, which
+        # only governs evaluate_all_moves' own sequential/parallel choice below):
+        # a bare sequential loop here would have no way to bound a single hung
+        # _probe_fen_with_deadline() call, since there'd be no worker thread to
+        # poll against; only a background thread lets this deadline actually
+        # cut the wait short. This budget is independent of the root probe's
+        # own, above - a slow root probe doesn't eat into pre-warm's time.
+        deadline = time.monotonic() + cfg.probe_timeout
+        futures = {
+            cf: _executor.submit(
+                _probe_fen_with_deadline, variant, cf, deadline, child_boards.get(cf)
+            )
+            for cf in child_fens
+        }
+        remaining = set(futures.values())
+        done_count = 0
+        prewarm_complete = True
+        last_event = time.monotonic()
+        try:
+            while done_count < total:
+                time_left = deadline - time.monotonic()
+                if time_left <= 0:
+                    log.warning(
+                        "Probe pre-warm timed out for variant=%s %s (%d/%d child positions still pending)",
+                        variant, fen, total - done_count, total,
+                    )
+                    prewarm_complete = False
+                    break
+                newly_done, remaining = futures_wait(
+                    remaining, timeout=min(0.3, time_left), return_when=FIRST_COMPLETED
+                )
+                if any(f.cancelled() or f.exception() is not None for f in newly_done):
+                    prewarm_complete = False
+                if newly_done:
+                    done_count += len(newly_done)
+                    yield _sse({"status": "probing", "completed": done_count, "total": total})
+                    last_event = time.monotonic()
+                elif time.monotonic() - last_event >= 1.0:
+                    # Keep the stream live and detect disconnects without
+                    # making the browser render identical progress updates.
+                    yield ": keep-alive\n\n"
+                    last_event = time.monotonic()
+        finally:
+            # Also runs when the streaming client disconnects. Running probes
+            # may finish, but queued work should not delay newer requests.
+            for future in remaining:
+                future.cancel()
+
+        # If pre-warming above finished, every child FEN is already cached, so
+        # evaluate_fen() below can fetch them all as cache hits sequentially,
+        # without the overhead of resubmitting each one to the thread pool. If
+        # pre-warming timed out instead, skip that shortcut: evaluate_all_moves()
+        # inside evaluate_fen() then takes its own parallel path, with its own
+        # fresh cfg.probe_timeout budget (see _evaluate_fen_impl), and reports
+        # "unknown" for whatever's still unresolved once that budget passes.
+        _evaluate_tls.bypass_parallel = prewarm_complete
+        # Already built above (root_board, move_info) to size the progress
+        # bar and know which child FENs to pre-warm - handing them to
+        # evaluate_fen() here means a cache-miss FEN doesn't pay for a
+        # second board build + legal-move walk right after this one.
+        _evaluate_tls.board     = root_board
+        _evaluate_tls.move_info = move_info
+        try:
+            json_str = evaluate_fen(variant, fen)
+            yield 'data: {"status":"done",' + json_str[1:] + '\n\n'
+
+        except Exception as e:
+            yield _sse(_stream_error_payload(variant, fen, e))
+        finally:
+            _evaluate_tls.bypass_parallel = False
+            _evaluate_tls.board     = None
+            _evaluate_tls.move_info = None
+
+    return Response(
+        stream_with_context(generate()),
+        content_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )
+
+
+@app.route("/health")
+def health() -> Response:
+    if TB is None:
+        return jsonify({"status": "degraded", "reason": "Tablebase not initialised"}), 503
+    return jsonify({"status": "ok"}), 200
+
+
+def _cache_info_dict(info) -> dict:
+    hits, misses       = info.hits, info.misses
+    maxsize, currsize  = info.maxsize, info.currsize
+    total = hits + misses
+    return {
+        "hits":     hits,
+        "misses":   misses,
+        "hit_rate": round(hits / total, 4) if total else 0.0,
+        "maxsize":  maxsize,
+        "currsize": currsize,
+    }
+
+
+@app.route("/admin/cache/clear", methods=["POST"])
+@_require_admin
+def clear_cache() -> Response:
+    evaluate_fen.cache_clear()
+    _probe_fen.cache_clear()
+    # The two LRUs above are app.py-level caches keyed on (variant, FEN)
+    # pairs. They are not the only cache in the probing pipeline: each tier's
+    # underlying tablebase can keep its own internal decoded-block cache
+    # and, in remote mode, a downloaded-file cache (remote/remote_fallback.py).
+    # SourcedTablebase.clear_caches()/cache_stats() are exposed on TB
+    # itself, but only actually clear/report something for a tier backed
+    # by a remote/remote_fallback.py Tablebase -- a plain local-directory
+    # Tablebase has no such cache. cache_stats() coming back empty is what
+    # distinguishes "nothing to clear" from "cleared something", since
+    # every tier is asked unconditionally either way.
+    tb_cache_info: dict = {}
+    if TB is not None:
+        TB.clear_caches()
+        tb_cache_info = TB.cache_stats()
+    tb_cache_cleared = bool(tb_cache_info)
+    log.info(
+        "All probe caches cleared (tablebase-internal cache %s).",
+        "cleared" if tb_cache_cleared else "not applicable for this tablebase",
+    )
+    response = {
+        "status":             "ok",
+        "message":            "All probe caches cleared (root JSON cache + child probe cache"
+                               + (" + tablebase-internal caches)." if tb_cache_cleared else ")."),
+        "evaluate_fen_cache": _cache_info_dict(evaluate_fen.cache_info()),
+        "probe_fen_cache":    _cache_info_dict(_probe_fen.cache_info()),
+        "tablebase_internal_cache_cleared": tb_cache_cleared,
+    }
+    if tb_cache_info:
+        response["tablebase_cache"] = tb_cache_info
+    return jsonify(response)
+
+
+@app.route("/admin/cache/stats", methods=["GET"])
+@_require_admin
+def cache_stats() -> Response:
+    stats = {
+        "evaluate_fen_cache": _cache_info_dict(evaluate_fen.cache_info()),
+        "probe_fen_cache":    _cache_info_dict(_probe_fen.cache_info()),
+        "thread_pool": {
+            "max_workers":        cfg.probe_threads,
+            "parallel_threshold": cfg.parallel_threshold,
+            "probe_timeout_secs": cfg.probe_timeout,
+        },
+        "config": {
+            "evaluate_cache_size": cfg.evaluate_cache_size,
+            "probe_cache_size":    cfg.probe_cache_size,
+            "block_cache_bytes":   cfg.block_cache_bytes,
+        },
+        "tablebase": {
+            "configured": TB is not None,
+        },
+    }
+    # SourcedTablebase.cache_stats() is exposed on TB and reports the configured source
+    # -- a source contributes no key when it has no remote-backed cache to
+    # report (see clear_cache() above for why a plain local-directory
+    # Tablebase has none).
+    if TB is not None:
+        tb_cache = TB.cache_stats()
+        if tb_cache:
+            stats["tablebase_cache"] = tb_cache
+    return jsonify(stats)
+
+
+@app.route("/admin/login", methods=["POST"])
+@_admin_login_rate_limit
+def admin_login() -> Response:
+    if not cfg.admin_token:
+        return jsonify({"error": "Admin panel disabled: ADMIN_TOKEN is not configured."}), 503
+    body = request.get_json(silent=True) or {}
+    token = body.get("token", "")
+    if not isinstance(token, str) or not _admin_token_matches(token):
+        return jsonify({"error": "Incorrect admin token."}), 401
+    session["admin_ok"] = True
+    return jsonify({"status": "ok"})
+
+
+@app.route("/admin/logout", methods=["POST"])
+def admin_logout() -> Response:
+    session.pop("admin_ok", None)
+    return jsonify({"status": "ok"})
+
+
+@app.route("/admin", methods=["GET"])
+def admin_dashboard() -> str | tuple[str, int]:
+    # Renders the dashboard once authenticated (session cookie from
+    # /admin/login); a login form otherwise. Unlike /admin/cache/* below,
+    # this route can't just use _require_admin -- a browser visiting /admin
+    # needs the login form itself, not a bare 401/503 JSON body. Matches
+    # /admin/login and /admin/cache/*'s own 503 when ADMIN_TOKEN is unset,
+    # rather than serving the dashboard shell with a 200.
+    if not cfg.admin_token:
+        return render_template(
+            "admin.html", authenticated=False, admin_configured=False,
+            source_repository_url=cfg.source_repository_url,
+        ), 503
+    return render_template(
+        "admin.html",
+        authenticated=_is_admin_authenticated(),
+        admin_configured=True,
+        source_repository_url=cfg.source_repository_url,
+    )
+
+
+# ── OpenAPI specification ─────────────────────────────────────────────────────
+# The specification is maintained in openapi.yaml (project root).
+
+_OPENAPI_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "openapi.yaml")
+
+
+@app.route("/openapi.yaml")
+def openapi_spec() -> Response:
+    return send_file(_OPENAPI_PATH, mimetype="application/yaml")
+
+
+if __name__ == "__main__":
+    if cfg.debug:
+        # Flask's own dev server: auto-reload + interactive debugger, for
+        # local development only. `threaded=True` is what lets a long-lived
+        # /probe/stream SSE connection coexist with other concurrent
+        # requests on this single-process server (see README.md "Running in
+        # production").
+        log.info("DEBUG = True (config.py) — starting Flask development server on %s:%s", cfg.host, cfg.port)
+        app.run(debug=True, host=cfg.host, port=cfg.port, threaded=True)
+    else:
+        # Production: serve via waitress, a pure-Python production-grade
+        # WSGI server. `threads` gives waitress its own pool of
+        # request-handling threads, playing the same role `threaded=True`
+        # plays for the Flask dev server above - without it, a single
+        # open /probe/stream connection could starve every other request
+        # (see README.md "Running in production").
+        #
+        # trusted_proxy=* / trusted_proxy_count / trusted_proxy_headers:
+        # waitress parses X-Forwarded-For and X-Forwarded-Proto and
+        # rewrites REMOTE_ADDR / wsgi.url_scheme itself, before the
+        # request ever reaches the Flask app object -- so it sits in front
+        # of, and takes priority over, the ProxyFix layer wired onto
+        # app.wsgi_app above. Without this, waitress's default
+        # (trusted_proxy=None) strips both headers entirely as untrusted,
+        # silently discarding them before ProxyFix could ever see them --
+        # ProxyFix alone is not sufficient here. `"*"` trusts whichever
+        # peer connects, rather than one specific IP, because Render's
+        # edge/load-balancer's own address isn't a fixed, documented
+        # value; this is safe under the same assumption
+        # TRUSTED_PROXY_COUNT's docstring already states -- that nothing
+        # but that one proxy hop can reach this process directly. Skipped
+        # entirely when cfg.trusted_proxy_count is 0 (no reverse proxy in
+        # front at all), leaving waitress's own default in place.
+        log.info(
+            "Starting waitress production server on %s:%s (threads=%s)",
+            cfg.host, cfg.port, cfg.waitress_threads,
+        )
+        waitress_kwargs = {}
+        if cfg.trusted_proxy_count > 0:
+            waitress_kwargs.update(
+                trusted_proxy="*",
+                trusted_proxy_count=cfg.trusted_proxy_count,
+                trusted_proxy_headers={"x-forwarded-for", "x-forwarded-proto"},
+            )
+        waitress_serve(
+            app, host=cfg.host, port=cfg.port, threads=cfg.waitress_threads, **waitress_kwargs)

config.py

@@ -0,0 +1,313 @@
+"""
+config.py: ChessTB Explorer configuration
+
+Edit the values below directly, then run `python app.py`. This file
+contains the primary application configuration. A subset of settings is
+also readable from the process environment, with the literal value below
+used when the environment variable is unset, allowing one committed
+configuration file to serve multiple deployment platforms.
+
+  - ADMIN_TOKEN / FLASK_SECRET_KEY: always from the environment only
+    (no literal fallback below) so they can be set as platform secrets
+    (e.g. a Render "Environment Variable" marked secret, or a Hugging
+    Face Space "Secret") without ever committing them - see the "Admin"
+    section below.
+  - PORT: read from the environment with a literal fallback, because
+    platforms like Render assign the port dynamically per-deployment
+    (via the platform's PORT variable) rather than using a fixed value;
+    see the "Server" section below.
+  - TABLEBASE_PATH / SOURCE_REPOSITORY_URL: read from the environment with a literal fallback,
+    to allow a deployment (for example, a Render Web Service) to select a
+    different tablebase location or repository URL without modifying the
+    source file; editing the literal value below remains supported.
+
+Invalid values (wrong type, out of range) make the app log an error and
+exit at startup rather than run with a silently-wrong configuration;
+see AppConfig.from_config() in app.py.
+"""
+
+import os
+
+# ── Tablebase location ──────────────────────────────────────────────────────
+
+# Bucket URL or local tablebase root. Full tables are preferred over shipping
+# tables; castling directories are selected automatically for each material.
+# A list of explicit source directories is also supported.
+TABLEBASE_PATH = os.environ.get(
+    "TABLEBASE_PATH", "https://huggingface.co/buckets/chesstb/chesstb/resolve",
+)
+
+# ── Server ───────────────────────────────────────────────────────────────────
+
+# Set to True to run the app via Flask's own dev server (auto-reload,
+# detailed error pages, interactive debugger) instead of waitress. Leave
+# False for any deployment reachable from other machines - False is what
+# makes `python app.py` serve via waitress, the production WSGI server
+# this app ships with.
+DEBUG = False
+
+# Interface the server (waitress, or the Flask dev server if DEBUG is
+# True) binds to. Set to "0.0.0.0" so the server accepts connections
+# arriving at the container's network interface, as required by Render,
+# Hugging Face Spaces, and any other containerized deployment. Use
+# "127.0.0.1" instead only for single-machine local use with no other
+# access control in front of it - see README.md's "Security notes".
+HOST = "0.0.0.0"
+
+# Port the server listens on - applies whether app.py ends up serving via
+# waitress (DEBUG=False) or the Flask dev server (DEBUG=True).
+#
+# Read from a PORT environment variable first, falling back to 7860
+# (Hugging Face Docker Spaces' default routed port) when unset. This
+# matters specifically for Render: a Render web service is assigned its
+# externally-routed port at deploy time via its own PORT variable
+# (commonly 10000, but not guaranteed) rather than a fixed value. The
+# container reads and binds to the injected port. Running locally with no
+# PORT set uses 7860.
+PORT = os.environ.get("PORT", "7860")
+
+# Number of worker threads waitress uses to handle concurrent requests
+# (only relevant when DEBUG=False). Needs to be more than 1 so that a
+# long-lived /probe/stream SSE connection can't block every other request;
+# see README.md's "Running in production" section. This is separate
+# from PROBE_THREADS below, which sizes the pool used internally to
+# parallelise tablebase probing, not to serve HTTP requests.
+WAITRESS_THREADS = 4
+
+# ── Probing ──────────────────────────────────────────────────────────────────
+
+# Worker threads in the probe thread pool for evaluating a position's
+# legal moves in parallel. Set to match a 2-vCPU host (e.g. Hugging
+# Face's cpu-basic tier); raise it on a larger host, or leave as None to
+# scale automatically instead (min(16, cpu_count() * 2)).
+PROBE_THREADS = 2
+
+# Minimum number of not-yet-cached child positions before a probe batch
+# switches from sequential to the PROBE_THREADS thread pool. Lower this
+# (or set to 1 to always parallelize) for workloads with many legal moves
+# or when profiling shows sequential probing is a bottleneck. Raise it
+# when thread hand-off overhead outweighs the benefit for the workload.
+PROBE_PARALLEL_THRESHOLD = 4
+
+# Wall-clock timeout, in seconds, for each probe phase. /probe gives the
+# root probe and the child-move batch independent budgets, so a worst-case
+# request can consume up to two PROBE_TIMEOUT_SECS intervals. /probe/stream
+# uses the same setting for its root probe and child pre-warm/evaluation
+# phases. Remaining probes are treated as unknown when a phase reaches its
+# deadline rather than blocking the request indefinitely.
+PROBE_TIMEOUT_SECS = 30
+
+# ── Caching ──────────────────────────────────────────────────────────────────
+
+# Defaults target one process on Hugging Face CPU Basic (2 vCPU, 16 GB
+# RAM). With the four default remote sources, byte-cache budgets total
+# 8.5 GiB: four 2 GiB page caches plus one shared 512 MiB block cache.
+# These fill on demand. Leave the remaining RAM for result caches,
+# table/index metadata, Python object overhead, and active requests.
+
+# Max entries in the root-FEN result cache (full JSON responses served by
+# evaluate_fen()). Raising this keeps more distinct root positions warm
+# across a session at the cost of memory.
+EVALUATE_CACHE_SIZE = 16384
+
+# Max entries in the child-position probe cache (raw WDL/DTZ/DTC/DTM/DTM50
+# tuples served by _probe_fen()), shared between root probes and every
+# child position probed while ranking moves.
+PROBE_CACHE_SIZE = 262144
+
+# Size (in bytes) of chess.chesstb's own internal cache of decoded/
+# decompressed tablebase blocks, shared across the WDL/DTZ/DTC/DTM/DTM50
+# tables.
+# One cache is shared across every source. Keep 512 MiB of decoded
+# blocks to reduce repeated decompression on the 2-vCPU host.
+BLOCK_CACHE_BYTES = 512 * 1024 * 1024
+
+# ── Remote (URL) tablebase entries only ─────────────────────────────────────
+# Everything below is ignored for a local-directory entry; it applies to
+# every http(s):// entry in TABLEBASE_PATH (including entries inside
+# a hybrid list - see
+# above). See the module docstrings of remote/remote_direct.py and
+# remote/remote_fallback.py for the full design.
+
+# How a remote table's bytes reach the prober:
+#
+#   "direct"   -- probe the remote tables in place, fetching only the
+#                 page-sized byte ranges each probe reads, nothing written
+#                 to disk (remote/remote_direct.py).
+#   "download" -- fetch each table file in full on first touch and cache it
+#                 on local disk (remote/remote_fallback.py). Slower first
+#                 touch of a material and real disk usage, but every read
+#                 after it is a local mmap read.
+#
+# "direct" is the preferred mode for browsing across many materials.
+# "download" is preferable when a small set of materials is accessed
+# repeatedly for a long session or when per-request network latency is high.
+#
+# "direct" is also the right choice for a PaaS deployment (e.g. Render)
+# fronting a multi-terabyte tablebase set: it needs no persistent disk at
+# all, so it sidesteps both the platform's per-GB disk cost at that scale
+# and the fact that most platforms' single-service disks aren't sized for
+# terabytes in the first place. "download" would need a disk (or enough
+# ephemeral local storage) large enough for the materials probed during a
+# session. Storage requirements therefore grow with the number and size of
+# materials accessed.
+REMOTE_MODE = "direct"
+
+# Soft budget, in bytes, PER remote source in TABLEBASE_PATH, shared
+# across that source's tables: bounds the in-memory page cache in
+# "direct" mode, and the on-disk whole-file cache in "download" mode.
+# Four default sources can retain 8 GiB of pages in total. Revisit this
+# budget when adding sources or running multiple application processes.
+REMOTE_PAGE_CACHE_BYTES = 2 * 1024 * 1024 * 1024
+
+# Size, in bytes, of one page. In "direct" mode this is the granularity of
+# every fetch, so it sets the trade between over-fetching (too large) and
+# many round trips per probe (too small) -- 256 KiB keeps a table's whole
+# header + index region within a page or two, which is what makes later
+# probes of the same table cheap. In "download" mode it is only the chunk
+# size used while streaming a full file down, and has no effect on which
+# bytes end up fetched.
+REMOTE_PAGE_SIZE_BYTES = 256 * 1024
+
+# Per-HTTP-request timeout, in seconds, for both existence/size checks and
+# the download itself against a remote tablebase.
+REMOTE_TIMEOUT_SECS = 20.0
+
+# Number of attempts for a single remote request before giving up (the
+# request that triggered it then fails, surfacing as a probe error).
+REMOTE_MAX_RETRIES = 3
+
+# Max size of the HTTP connection pool each remote backend's session
+# keeps open against its entry's host. Left as None so it scales
+# with PROBE_THREADS automatically (max(PROBE_THREADS * 2, 20)) - set an
+# explicit integer to override. Too small a pool under-serves concurrent
+# probing (connections stop being reused once PROBE_THREADS exceeds it);
+# too large rarely hurts beyond a handful of idle sockets, so there's
+# little reason to set this below the auto-computed value.
+REMOTE_POOL_MAXSIZE = None
+
+# ── Rate limiting ────────────────────────────────────────────────────────────
+
+# Per-client-IP request limit applied to /probe and /probe/stream - the
+# two public, unauthenticated, CPU-bound endpoints - using flask-limiter's
+# string syntax (e.g. "60 per minute", "10 per second"; multiple limits
+# can be combined with ";"). Backed by an in-process memory store, which
+# is enough for a single-container deployment (e.g. one Render Web
+# Service instance) but does not share state across multiple replicas.
+# Left empty, rate limiting is disabled entirely.
+#
+# 60 per minute comfortably covers normal browsing and autoplay at its
+# default 1.25s delay; raise it if legitimate autoplay at a fast delay
+# setting gets throttled, or lower it if the deployment sees abuse.
+PROBE_RATE_LIMIT = "60 per minute"
+
+# Per-client-IP limit applied only to requests that identify themselves as
+# background hover-prefetch via the "X-Prefetch: 1" request header (see
+# frontend/src/engine/tablebase.js's hover-prefetch). Deliberately separate from,
+# and tighter than, PROBE_RATE_LIMIT -- a client-supplied header is not
+# trusted enough to exempt a request from limiting altogether (any
+# client could tag every request "prefetch" to bypass PROBE_RATE_LIMIT),
+# only to route it to its own, smaller budget, so a sustained hover sweep
+# can burn through this budget and start getting silently-dropped 429s on
+# prefetches without ever touching the user's own click budget above.
+# Left empty, prefetch-tagged requests fall back to sharing
+# PROBE_RATE_LIMIT with everything else, as if this setting didn't exist.
+PREFETCH_RATE_LIMIT = "30 per minute"
+
+# Per-client-IP limit on /admin/login (config.py's ADMIN_TOKEN check),
+# same string syntax as PROBE_RATE_LIMIT above and backed by the same
+# in-process memory store. Separate from PROBE_RATE_LIMIT because
+# /admin/login is a brute-forceable shared-secret check, not a CPU-bound
+# probe -- it needs a tighter limit than "comfortably covers normal
+# browsing" calls for. Applies to both failed and successful login
+# attempts. Left empty, login attempts are not rate limited at all.
+ADMIN_LOGIN_RATE_LIMIT = "5 per minute"
+
+# Number of trusted reverse-proxy hops in front of this application.
+# PROBE_RATE_LIMIT and ADMIN_LOGIN_RATE_LIMIT above both key on the
+# client's IP address (request.remote_addr) -- behind a reverse proxy
+# that's the proxy's own address unless it's corrected for, which would
+# collapse every client behind that proxy onto one shared rate-limit key.
+# The same trusted-hop count also governs whether X-Forwarded-Proto is
+# trusted, which corrects request.scheme / request.is_secure (and any
+# externally-generated URL) when TLS terminates at that reverse proxy
+# rather than at this app itself.
+#
+# In production (DEBUG = False), app.py passes this to waitress's own
+# trusted_proxy_count, since waitress -- the actual production WSGI
+# server -- parses X-Forwarded-For/X-Forwarded-Proto and corrects
+# REMOTE_ADDR/wsgi.url_scheme itself, before Flask ever sees the request.
+# app.py also applies Werkzeug's ProxyFix with the same count, which
+# makes the equivalent correction for the DEBUG = True Flask-dev-server
+# path (waitress isn't involved there at all); under waitress it is
+# redundant, since waitress performs the same correction itself.
+#
+# 1 is correct for this project's own render.yaml / "Deploying to Render"
+# topology: Render's platform edge/load-balancer sits in front of a web
+# service exactly once. Increase it when an additional reverse proxy is
+# present in front of the service. Set to 0 when no reverse proxy is present
+# -- a value that does not match the actual proxy chain
+# leaves the rate limiter keying on the wrong address (or the scheme
+# misdetected), or (set too high for no proxy at all) trusting a
+# client-supplied X-Forwarded-For/X-Forwarded-Proto header directly,
+# letting a client spoof its own rate-limit key or apparent scheme.
+TRUSTED_PROXY_COUNT = os.environ.get("TRUSTED_PROXY_COUNT", "1")
+
+# ── Admin ────────────────────────────────────────────────────────────────────
+
+# Shared secret required to reach /admin, /admin/cache/stats, and
+# /admin/cache/clear. Read from the ADMIN_TOKEN environment variable
+# rather than hardcoded here - set it as a platform secret (e.g. a
+# Render "Environment Variable" marked secret, generated automatically by
+# render.yaml's generateValue: true) rather than committing it here.
+# Left unset, every admin route responds 503 rather than running without
+# a password. Visiting /admin with no active session shows a login form;
+# a correct token there starts a signed session cookie. API clients may
+# instead send "Authorization: Bearer <ADMIN_TOKEN>" directly.
+ADMIN_TOKEN = os.environ.get("ADMIN_TOKEN", "")
+
+# Key Flask uses to sign the admin session cookie. Read from the
+# FLASK_SECRET_KEY environment variable for the same reason as
+# ADMIN_TOKEN above. Left unset, a random key is generated at process
+# startup instead - sessions still work, but every restart invalidates
+# existing ones, requiring the admin to log in again. Set an explicit,
+# persistent value if that's undesirable (e.g. behind a load balancer
+# with multiple replicas, or to survive routine restarts).
+FLASK_SECRET_KEY = os.environ.get("FLASK_SECRET_KEY", "")
+
+# Whether the admin session cookie set by /admin/login requires HTTPS.
+# Independent of DEBUG above -- DEBUG is a development/runtime behavior
+# switch, not a reliable indicator of the deployment's transport security,
+# so a deployment can legitimately run DEBUG=False (production-like
+# behavior) while still being served over plain HTTP. Leaving this True
+# for such a deployment sets the cookie Secure, which a browser then
+# won't send back over a plain HTTP connection -- /admin/login would
+# appear to succeed while every subsequent authenticated /admin/* request
+# came back 401.
+#
+# Read from the environment, like TRUSTED_PROXY_COUNT above, so a
+# deployment (e.g. render.yaml's Render blueprint, which sets this to
+# "true" explicitly) can configure it without editing this file. Defaults
+# to False (via SESSION_COOKIE_SECURE unset or anything other than
+# "true") because that's what a local installation needs (README.md's
+# "Installation"): `python app.py` served over http://127.0.0.1:7860 --
+# plain HTTP -- after editing only TABLEBASE_PATH above, with DEBUG and
+# this setting both left at their defaults.
+#
+# Set this to "true" for any deployment the browser reaches over HTTPS,
+# including one behind a TLS-terminating reverse proxy such as Render's
+# (the browser's own connection is what the Secure attribute governs, not
+# the internal hop between the proxy and this process).
+SESSION_COOKIE_SECURE = os.environ.get("SESSION_COOKIE_SECURE", "false").strip().lower() == "true"
+
+# ── Links ────────────────────────────────────────────────────────────────────
+
+# Repository URL for the source repository button shown in the header of every page.
+# Left empty, the button is omitted entirely. Also readable from a
+# SOURCE_REPOSITORY_URL environment variable (falling back to the literal string
+# below when unset), so a platform deployment can set it from its own
+# dashboard without a commit - see render.yaml.
+SOURCE_REPOSITORY_URL = os.environ.get(
+    "SOURCE_REPOSITORY_URL",
+    "https://huggingface.co/spaces/chesstb/explorer/tree/main",
+)

dtz_anchor.py

@@ -0,0 +1,72 @@
+"""Resolves rounded DTZ values by cross-checking a position's moves.
+
+A rounded DTZ stands for a few candidate values. The root's DTZ is the best
+value among the moves that keep its class (smallest when winning, largest
+when losing), so root candidates that no consistent set of move values can
+produce are discarded, and a move that must supply the root's value is pinned.
+"""
+
+from __future__ import annotations
+
+import operator
+from typing import NamedTuple, Sequence
+
+
+class MoveOption(NamedTuple):
+    child: tuple[int, ...]  # candidate DTZ values of the position after the move
+    value: tuple[int, ...]  # the move's DTZ for each candidate in `child`
+
+
+class Resolution(NamedTuple):
+    root: int | None  # exact root DTZ, or None when it cannot be determined
+    pinned: dict[int, int]  # option index -> exact DTZ of that move
+
+
+def candidates(dtz: int, rounded: bool) -> tuple[int, ...]:
+    """True values allowed by CORRECTNESS.md Theorem 12.15.
+
+    Rounded derived values can be even. An overestimate of one is only
+    possible at an odd true value, so an odd report cannot stand for the
+    preceding even value. Unrounded reports are exact.
+    """
+    if not rounded:
+        return (dtz,)
+    if dtz % 2 == 1:
+        return (dtz, dtz + 1)
+    return (dtz - 1, dtz, dtz + 1)
+
+
+def move_option(child_dtz: int, child_rounded: bool, zeroing: bool,
+                cursed_exit: bool) -> MoveOption:
+    """A zeroing move is worth 1. A quiet move is worth one more than its
+    child, forced odd when it is a cursed exit."""
+    if zeroing:
+        return MoveOption((), (1,))
+    child = candidates(child_dtz, child_rounded)
+    value = tuple(((c + 1) | 1) if cursed_exit else c + 1 for c in child)
+    return MoveOption(child, value)
+
+
+def resolve(root_dtz: int, root_rounded: bool, options: Sequence[MoveOption],
+            winning: bool) -> Resolution:
+    """`options` are the moves that keep the root's class."""
+    at_least_as_good = operator.ge if winning else operator.le
+    feasible = [
+        x for x in candidates(root_dtz, root_rounded)
+        if all(any(at_least_as_good(v, x) for v in o.value) for o in options)
+        and any(x in o.value for o in options)
+    ]
+    if len(feasible) != 1:
+        return Resolution(None, {})
+    x = feasible[0]
+    pinned: dict[int, int] = {}
+    for k, option in enumerate(options):
+        if len(set(option.value)) < 2:
+            continue
+        others_attain = any(x in other.value
+                            for j, other in enumerate(options) if j != k)
+        kept = {v for v in option.value
+                if at_least_as_good(v, x) and (v == x or others_attain)}
+        if len(kept) == 1:
+            pinned[k] = kept.pop()
+    return Resolution(x, pinned)

frontend/.gitignore

@@ -0,0 +1 @@
+node_modules/

frontend/admin.html

@@ -0,0 +1,7 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <link rel="stylesheet" href="/src/styles/admin.css" />
+  </head>
+  <body></body>
+</html>

frontend/index.html

@@ -0,0 +1,7 @@
+<!doctype html>
+<html lang="en" class="explorer">
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

frontend/package-lock.json

@@ -0,0 +1,1698 @@
+{
+  "name": "chesstb-explorer-frontend",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "chesstb-explorer-frontend",
+      "version": "1.0.0",
+      "dependencies": {
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1"
+      },
+      "devDependencies": {
+        "@vitejs/plugin-react": "^4.3.4",
+        "vite": "^5.4.11"
+      }
+    },
+    "node_modules/@babel/code-frame": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.7.tgz",
+      "integrity": "sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-validator-identifier": "^7.29.7",
+        "js-tokens": "^4.0.0",
+        "picocolors": "^1.1.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/compat-data": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.7.tgz",
+      "integrity": "sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/core": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.7.tgz",
+      "integrity": "sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.7",
+        "@babel/generator": "^7.29.7",
+        "@babel/helper-compilation-targets": "^7.29.7",
+        "@babel/helper-module-transforms": "^7.29.7",
+        "@babel/helpers": "^7.29.7",
+        "@babel/parser": "^7.29.7",
+        "@babel/template": "^7.29.7",
+        "@babel/traverse": "^7.29.7",
+        "@babel/types": "^7.29.7",
+        "@jridgewell/remapping": "^2.3.5",
+        "convert-source-map": "^2.0.0",
+        "debug": "^4.1.0",
+        "gensync": "^1.0.0-beta.2",
+        "json5": "^2.2.3",
+        "semver": "^6.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/babel"
+      }
+    },
+    "node_modules/@babel/generator": {
+      "version": "7.29.8",
+      "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.8.tgz",
+      "integrity": "sha512-gZbepsdh3WDtgZKWL+vTPh71LSBrm/Y4/QDZBVCcYfmeTEEuoOYwlSy+G1StfJg+/Zy550u/3TATbm7qDbbMtg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.29.8",
+        "@babel/types": "^7.29.8",
+        "@jridgewell/gen-mapping": "^0.3.12",
+        "@jridgewell/trace-mapping": "^0.3.28",
+        "jsesc": "^3.0.2"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-compilation-targets": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.29.7.tgz",
+      "integrity": "sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/compat-data": "^7.29.7",
+        "@babel/helper-validator-option": "^7.29.7",
+        "browserslist": "^4.24.0",
+        "lru-cache": "^5.1.1",
+        "semver": "^6.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-globals": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.29.7.tgz",
+      "integrity": "sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-module-imports": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.29.7.tgz",
+      "integrity": "sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/traverse": "^7.29.7",
+        "@babel/types": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-module-transforms": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.29.7.tgz",
+      "integrity": "sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-module-imports": "^7.29.7",
+        "@babel/helper-validator-identifier": "^7.29.7",
+        "@babel/traverse": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0"
+      }
+    },
+    "node_modules/@babel/helper-plugin-utils": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.29.7.tgz",
+      "integrity": "sha512-G7sHYigPY17oO5SYWnfD/0MTBwVR781S/JI643e/JhUYgVgWE/61SoW3NH9KWUKyKq5LVh3npif99Wkt6j86Jw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-string-parser": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz",
+      "integrity": "sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-identifier": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz",
+      "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-option": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.29.7.tgz",
+      "integrity": "sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helpers": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.29.7.tgz",
+      "integrity": "sha512-1k2lAGRMfHTcwuNYcCNUmaUffmQv8KWMfh2iJUUeRlwlwH4FdNG7mfPI10NPfLHJFThE4Tyr4mv7kTNZOiPuBg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/template": "^7.29.7",
+        "@babel/types": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/parser": {
+      "version": "7.29.8",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.8.tgz",
+      "integrity": "sha512-E8lTAYNB1KW+FH+VGJuZM1ioAx2E6oVlvQFRrf5P8ZZmsiJXYAD9vTFV7yyEURNzgh1dFqMZuO6tUwcARbqFCA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.29.8"
+      },
+      "bin": {
+        "parser": "bin/babel-parser.js"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@babel/plugin-transform-react-jsx-self": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-self/-/plugin-transform-react-jsx-self-7.29.7.tgz",
+      "integrity": "sha512-TL0hMc9xzy86VD31nUiwzd5otRAcyEPcsegCxolO0PvcXuH1v0kECe/UIznYFihpkvU5wg/jk4v0TTEFfm53fw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-plugin-utils": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@babel/plugin-transform-react-jsx-source": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-source/-/plugin-transform-react-jsx-source-7.29.7.tgz",
+      "integrity": "sha512-06IyK09H3wi4cGbhDBwp5gUGo0IKtnYa8tyTiephirPCK6fbobVGiXMMI5zLQ4aKEYP3wZ3ArU44o+8KMrSG/Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-plugin-utils": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@babel/template": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.29.7.tgz",
+      "integrity": "sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.7",
+        "@babel/parser": "^7.29.7",
+        "@babel/types": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/traverse": {
+      "version": "7.29.8",
+      "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.8.tgz",
+      "integrity": "sha512-I5z7H3bf/41ktsNVLtpN0wAa336HkqIHQ5BuPLEhTkt1jVSyZpeNKIzTgEWmlxjdg81R0IgUCcaE+Ok3NvrfZg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.7",
+        "@babel/generator": "^7.29.8",
+        "@babel/helper-globals": "^7.29.7",
+        "@babel/parser": "^7.29.8",
+        "@babel/template": "^7.29.7",
+        "@babel/types": "^7.29.8",
+        "debug": "^4.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/types": {
+      "version": "7.29.8",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.8.tgz",
+      "integrity": "sha512-Vj1jF3cPfxg7OAfoI7QnVKLoILlm2JF9pnVHrX8qx7AHMiYWT+NDAA7jChlNgRS4WTLc/fD1lXLmPixluj+3Gg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-string-parser": "^7.29.7",
+        "@babel/helper-validator-identifier": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz",
+      "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz",
+      "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz",
+      "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz",
+      "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz",
+      "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz",
+      "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz",
+      "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz",
+      "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz",
+      "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz",
+      "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz",
+      "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz",
+      "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz",
+      "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz",
+      "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz",
+      "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
+      "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz",
+      "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz",
+      "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz",
+      "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@jridgewell/gen-mapping": {
+      "version": "0.3.13",
+      "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
+      "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.0",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/remapping": {
+      "version": "2.3.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/remapping/-/remapping-2.3.5.tgz",
+      "integrity": "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/gen-mapping": "^0.3.5",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz",
+      "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.31",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.1.0",
+        "@jridgewell/sourcemap-codec": "^1.4.14"
+      }
+    },
+    "node_modules/@napi-rs/lzma-linux-x64-gnu": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/@napi-rs/lzma-linux-x64-gnu/-/lzma-linux-x64-gnu-1.5.1.tgz",
+      "integrity": "sha512-oTXEIha4SsuXdTA4Iyskj0kpdx2yVXdhd75c2v3xGrHFfVMsbhTPZU/nMPL4sWKo4pBHm3aucLaqGlF696dTyQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^22.20 || ^24.12 || >=25"
+      }
+    },
+    "node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-beta.27",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz",
+      "integrity": "sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.63.3.tgz",
+      "integrity": "sha512-w3Jnvi1ocaVm/c7yVPpfB98XeSRBMyzp6njL5MVVbGyXjpmUkN+s6Hp4t0PqhGCCaI1ZHMKXt/w0lA1RCaLVcw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.63.3.tgz",
+      "integrity": "sha512-uI/ESiaIbbRYAEhzy8PCUWDp1hB0bjAqM06mW9flOoNO4Q8DQpeoREhBR5Hegfl+wpXiguyJv6XSPzEN7OxyHQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.63.3.tgz",
+      "integrity": "sha512-oxhrd1jmXLwWZ83eQYDXxuqRdkqkzrjR3JobKeuUyfdNZo11FuQIvqEOZhyIT7OBHxXoGslDDjN0cQcM6T0TqQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.63.3.tgz",
+      "integrity": "sha512-7/YiIMghVE8DrxKvNdorAaJVdriOFgOIpdStnPx8ppx5zfTwC3jBCSEAIzB7JD5404m65THl6H93UTTVUvypmg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.63.3.tgz",
+      "integrity": "sha512-GXFZRRoMAytaI5z6N3Zhfw0WL18Q0M8r95D5hlC4GqE/lGk8pbSJNUBoOWDfbm6dTciqHj2nU87tI5f6XhQiOg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.63.3.tgz",
+      "integrity": "sha512-77W+8X3ddYgPxUpB8nZFQs2Mq+wc4HVlcSRtApXLjYBcnPMkttrSnU8VwKQjeWYhMsITHFs5cWBQ8vz1Q+5RHQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.63.3.tgz",
+      "integrity": "sha512-FVkwK+iUC+mq+GipVK46rRVticfAPtvPUNlqlGXUDxdVk/UGjQiiiUVPUrEXdSpU2ufU0XxLGyTqDtBidDOVmg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.63.3.tgz",
+      "integrity": "sha512-+aGU1t3398yQOVj1Bz8o3e+KtswxAPvO+mtxtNdfXYMkXIHu7XhhkCD7/DEH9q8tF8uhDnMWvfpUKI8y1sZJsg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.63.3.tgz",
+      "integrity": "sha512-cR0kjpRXR2KJ2oQK8E2KTPtphs+b9hZ8IhTZubNryt/RsqgdOZBQ2Zq0q5UedtiIi0rs3jVhJh55RE1ZHUVGUA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.63.3.tgz",
+      "integrity": "sha512-y1RYi4Q3/9ByVWSSt9kX2ustE0B7kFYbJ6zZdVZVyqopZs3yhCTwRfrjIX4vezUJInma/Gs6BOFDJg7yZmJ0IQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.63.3.tgz",
+      "integrity": "sha512-DNhEA5viIj3Z5bZLE4z4oV8N5ozWqDwyt7T6KG7VdLDJ0nW+rNOYlphBl4/3HQkK75qipPLsVOfStHHOwN9WSg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.63.3.tgz",
+      "integrity": "sha512-17gQCqrIpXBX2Cmi9/TygnVOqGbzsba/iaqcYSL8FY7lNugg+7AiYNs5c5nKWD+NRQha36Sa0CqkJqH4XVHwnQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.63.3.tgz",
+      "integrity": "sha512-6LwVnZRIyINpdku/yOcI8Tm9YqLmhHK5emmlOOnW9tO0SYEm1FmKPcsSAGp0NBlqR2P04xaND4jvN6sTHqhq8A==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.63.3.tgz",
+      "integrity": "sha512-xMUqkTXlEUtI/p5AAukMwBRr1enU3efsTeF+bskeFfk8t1C9rcC8sLREcZXmTfAXEbvRdJVSonVJez3TMlbR3w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.63.3.tgz",
+      "integrity": "sha512-S3E94co9F9WRRqEaUoQZ38K1gCz6KiM+nL7/3ijq7fDGF3OznjS5TasgYITlvl27GQKtu4lOAOsr5MFwkijvOA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.63.3.tgz",
+      "integrity": "sha512-1QtRDwG42x5BJI3s9mxu5rEjDnfbSnk20HQ9/ylTAYnSwYwxMVb+Vgu34wzzTQ7ogqBybebgQNUDAvZVQ38DbA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.63.3.tgz",
+      "integrity": "sha512-BQhejF6ZXOpxbngiNTP12GCGQeaDVL2QXGeBVViKIYzFHM5RKxTxwUMB1fr1BeNFphFMpnRqC5QSXFSa4z6UQw==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.63.3.tgz",
+      "integrity": "sha512-SXagRwnI2Wlwlitllu59UK/nGVbD1CKPcNqDplHwIC4BqJcpXFjD32d1R/RbuISa95HdQrZM3/7v4bKiowFaLA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.63.3.tgz",
+      "integrity": "sha512-2IPozoEALRCziGqE8O9KMK60PMu5TS1huv4fwoeCexj+WjmcwFtX9CTOVbfXCUqcELAubEwRFPYlzb/WvwY2HQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.63.3.tgz",
+      "integrity": "sha512-AoxqosUHT9IX54hFn2TiN6A7d6ZKTtE6pd2bqWtqkkNJ6HJGaU6FRouGX8L1O7R/ZwsnCnpQrHzb4pDEx+UHRQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.63.3.tgz",
+      "integrity": "sha512-d+CaftKgmkFBzCwezMqqy1d0QNNYugqLCMcYVQWBy5SS2YfeMP8Q8ripkgx9O8IyBXXLHrJ+aaCV4U96usv6Yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.63.3.tgz",
+      "integrity": "sha512-xXlDF6nR1eOuXbdDy5Hl5fmtY7teUDevF/k0O7IPoZe4Tpmdv+lgdE5JRsnhQtt37ql9P0VF2kAN9a0OCZdo+Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.63.3.tgz",
+      "integrity": "sha512-YtXAgLN+JP7Ay6qG3eWhc7IHMQPzLc8r3uvhAvlJIoCz/4Q32+Bl9Fmnywidh8v1GOIMmymjovfqY9ETAtysvA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.63.3.tgz",
+      "integrity": "sha512-WuWtSJRNo549vzcfZyEgfqb6zeSgn1F+UE5kQ+BCjzz0W4MGCjntUHkZVc1VRuAM7+ULaSyhiPxD1spyewFvkQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.63.3.tgz",
+      "integrity": "sha512-+lIKX7O0+IGe7WuhATaAMMeT7B76vfhXH/l9wLQL+nvyhbw2ohYCKIdWL56JfDu75CWt5oKRP4QFH/jkMtBquA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@types/babel__core": {
+      "version": "7.20.5",
+      "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz",
+      "integrity": "sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.20.7",
+        "@babel/types": "^7.20.7",
+        "@types/babel__generator": "*",
+        "@types/babel__template": "*",
+        "@types/babel__traverse": "*"
+      }
+    },
+    "node_modules/@types/babel__generator": {
+      "version": "7.27.0",
+      "resolved": "https://registry.npmjs.org/@types/babel__generator/-/babel__generator-7.27.0.tgz",
+      "integrity": "sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.0.0"
+      }
+    },
+    "node_modules/@types/babel__template": {
+      "version": "7.4.4",
+      "resolved": "https://registry.npmjs.org/@types/babel__template/-/babel__template-7.4.4.tgz",
+      "integrity": "sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.1.0",
+        "@babel/types": "^7.0.0"
+      }
+    },
+    "node_modules/@types/babel__traverse": {
+      "version": "7.28.0",
+      "resolved": "https://registry.npmjs.org/@types/babel__traverse/-/babel__traverse-7.28.0.tgz",
+      "integrity": "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.28.2"
+      }
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@vitejs/plugin-react": {
+      "version": "4.7.0",
+      "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-4.7.0.tgz",
+      "integrity": "sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.28.0",
+        "@babel/plugin-transform-react-jsx-self": "^7.27.1",
+        "@babel/plugin-transform-react-jsx-source": "^7.27.1",
+        "@rolldown/pluginutils": "1.0.0-beta.27",
+        "@types/babel__core": "^7.20.5",
+        "react-refresh": "^0.17.0"
+      },
+      "engines": {
+        "node": "^14.18.0 || >=16.0.0"
+      },
+      "peerDependencies": {
+        "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
+      }
+    },
+    "node_modules/baseline-browser-mapping": {
+      "version": "2.11.25",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.25.tgz",
+      "integrity": "sha512-gMmEShwwq7FJqMwvfRwvCl00v4kN+KOfJqXn+f4nrufak5gNHJOksd/60Dvjuz7sI8Y5WiSFBa8FEYr+zoyqCw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "baseline-browser-mapping": "dist/cli.cjs"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/browserslist": {
+      "version": "4.29.0",
+      "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.29.0.tgz",
+      "integrity": "sha512-3GSvyjvDI4Dur1Meg2BekJquu5uF+9R9a1+5M1Mde192eZoXbeXjzgOsgqPS2V8D5wrrip0gR5Hf/GhWQ9ZzaA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "baseline-browser-mapping": "^2.11.23",
+        "caniuse-lite": "^1.0.30001810",
+        "electron-to-chromium": "^1.5.427",
+        "node-releases": "^2.0.55",
+        "update-browserslist-db": "^1.3.3"
+      },
+      "bin": {
+        "browserslist": "cli.js"
+      },
+      "engines": {
+        "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
+      }
+    },
+    "node_modules/caniuse-lite": {
+      "version": "1.0.30001810",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001810.tgz",
+      "integrity": "sha512-TITQPUkaz+aVk5GL6NhOdwk1aEaNTSDPsGFWrTuhKGtjTF70jL/Oht2W4c6rXUe5fu7Ie19VIahAXHIIiWWNeg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/caniuse-lite"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "CC-BY-4.0"
+    },
+    "node_modules/convert-source-map": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
+      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/electron-to-chromium": {
+      "version": "1.5.430",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.430.tgz",
+      "integrity": "sha512-e1QEj72Y4zd8RlNZVmoTg+iCOSVwpk05IOiiQwdrkwCSVlZfPthevErhE+nckGd2YbsXfp1SkisznhGVIXP2NQ==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/esbuild": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz",
+      "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.21.5",
+        "@esbuild/android-arm": "0.21.5",
+        "@esbuild/android-arm64": "0.21.5",
+        "@esbuild/android-x64": "0.21.5",
+        "@esbuild/darwin-arm64": "0.21.5",
+        "@esbuild/darwin-x64": "0.21.5",
+        "@esbuild/freebsd-arm64": "0.21.5",
+        "@esbuild/freebsd-x64": "0.21.5",
+        "@esbuild/linux-arm": "0.21.5",
+        "@esbuild/linux-arm64": "0.21.5",
+        "@esbuild/linux-ia32": "0.21.5",
+        "@esbuild/linux-loong64": "0.21.5",
+        "@esbuild/linux-mips64el": "0.21.5",
+        "@esbuild/linux-ppc64": "0.21.5",
+        "@esbuild/linux-riscv64": "0.21.5",
+        "@esbuild/linux-s390x": "0.21.5",
+        "@esbuild/linux-x64": "0.21.5",
+        "@esbuild/netbsd-x64": "0.21.5",
+        "@esbuild/openbsd-x64": "0.21.5",
+        "@esbuild/sunos-x64": "0.21.5",
+        "@esbuild/win32-arm64": "0.21.5",
+        "@esbuild/win32-ia32": "0.21.5",
+        "@esbuild/win32-x64": "0.21.5"
+      }
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/gensync": {
+      "version": "1.0.0-beta.2",
+      "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz",
+      "integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/js-tokens": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
+      "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
+      "license": "MIT"
+    },
+    "node_modules/jsesc": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
+      "integrity": "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "jsesc": "bin/jsesc"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/json5": {
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz",
+      "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "json5": "lib/cli.js"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/loose-envify": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
+      "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^3.0.0 || ^4.0.0"
+      },
+      "bin": {
+        "loose-envify": "cli.js"
+      }
+    },
+    "node_modules/lru-cache": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
+      "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "yallist": "^3.0.2"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.19",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.19.tgz",
+      "integrity": "sha512-Y2tUNy4ouw6tq5oDSKeQYGOyhkUBhNOcGV/02KC+6kd9eDGqdZd++mjMiIDilrBYvjEnCYvVtsuHCuP+okSfug==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/node-releases": {
+      "version": "2.0.56",
+      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.56.tgz",
+      "integrity": "sha512-x0InOIyzgdk+eyaWaRJFH5snEtiImgBgblZ2CyPrLmqqcuMQkEvcDPHbzqbD8eDsSeJbVOjn+crzyzHaM4D+/A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/postcss": {
+      "version": "8.5.28",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.28.tgz",
+      "integrity": "sha512-RRuzqDtt5Y9h3quz5hWhK+TPnsmVs6WwSU6LkJMeY4HstUEDuYTG8UJSdawMRzmzAtV+KEoG8N3Qg2qLy5vM/A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.18",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/react": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
+      "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
+      "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0",
+        "scheduler": "^0.23.2"
+      },
+      "peerDependencies": {
+        "react": "^18.3.1"
+      }
+    },
+    "node_modules/react-refresh": {
+      "version": "0.17.0",
+      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.17.0.tgz",
+      "integrity": "sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/rollup": {
+      "version": "4.63.3",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.63.3.tgz",
+      "integrity": "sha512-1i2XreiAoMMXuPGD6Msj2xWrMMkHojNRKivInxGQcg7/1KuPuYlfUutLyh4drnOxUTHX9cHI4wFoat8D/NKaBw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.9"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@napi-rs/lzma-linux-x64-gnu": "1.5.1",
+        "@rollup/rollup-android-arm-eabi": "4.63.3",
+        "@rollup/rollup-android-arm64": "4.63.3",
+        "@rollup/rollup-darwin-arm64": "4.63.3",
+        "@rollup/rollup-darwin-x64": "4.63.3",
+        "@rollup/rollup-freebsd-arm64": "4.63.3",
+        "@rollup/rollup-freebsd-x64": "4.63.3",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.63.3",
+        "@rollup/rollup-linux-arm-musleabihf": "4.63.3",
+        "@rollup/rollup-linux-arm64-gnu": "4.63.3",
+        "@rollup/rollup-linux-arm64-musl": "4.63.3",
+        "@rollup/rollup-linux-loong64-gnu": "4.63.3",
+        "@rollup/rollup-linux-loong64-musl": "4.63.3",
+        "@rollup/rollup-linux-ppc64-gnu": "4.63.3",
+        "@rollup/rollup-linux-ppc64-musl": "4.63.3",
+        "@rollup/rollup-linux-riscv64-gnu": "4.63.3",
+        "@rollup/rollup-linux-riscv64-musl": "4.63.3",
+        "@rollup/rollup-linux-s390x-gnu": "4.63.3",
+        "@rollup/rollup-linux-x64-gnu": "4.63.3",
+        "@rollup/rollup-linux-x64-musl": "4.63.3",
+        "@rollup/rollup-openbsd-x64": "4.63.3",
+        "@rollup/rollup-openharmony-arm64": "4.63.3",
+        "@rollup/rollup-win32-arm64-msvc": "4.63.3",
+        "@rollup/rollup-win32-ia32-msvc": "4.63.3",
+        "@rollup/rollup-win32-x64-gnu": "4.63.3",
+        "@rollup/rollup-win32-x64-msvc": "4.63.3",
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.23.2",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
+      "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      }
+    },
+    "node_modules/semver": {
+      "version": "6.3.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/update-browserslist-db": {
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.3.3.tgz",
+      "integrity": "sha512-pJ2sYawQS0R/WI928Gj5GlPhTGzbMelq0+4INtSYNDV9ErKJcX6xjGWkoG/VnB3dpUm00zALaqkrUD77pO5TDQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "escalade": "^3.2.0",
+        "picocolors": "^1.1.1"
+      },
+      "bin": {
+        "update-browserslist-db": "cli.js"
+      },
+      "peerDependencies": {
+        "browserslist": ">= 4.21.0"
+      }
+    },
+    "node_modules/vite": {
+      "version": "5.4.21",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
+      "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.21.3",
+        "postcss": "^8.4.43",
+        "rollup": "^4.20.0"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^18.0.0 || >=20.0.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
+        "terser": "^5.4.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/yallist": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
+      "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
+      "dev": true,
+      "license": "ISC"
+    }
+  }
+}

frontend/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "chesstb-explorer-frontend",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^5.4.11"
+  }
+}

frontend/src/App.jsx

@@ -0,0 +1,43 @@
+import { useExplorer } from './hooks/useExplorer.js';
+import Header from './components/Header.jsx';
+import FenBar from './components/FenBar.jsx';
+import BoardArea from './components/BoardArea.jsx';
+import ResultsPanel from './components/ResultsPanel.jsx';
+import PgnPanel from './components/PgnPanel.jsx';
+import PgnDialog from './components/PgnDialog.jsx';
+import SettingsPanel from './components/SettingsPanel.jsx';
+import Toasts from './components/Toasts.jsx';
+import PromotionDialog from './components/PromotionDialog.jsx';
+import ScreenNav from './components/ScreenNav.jsx';
+
+export default function App({ sourceRepositoryUrl }) {
+    const explorer = useExplorer();
+
+    return (
+        <>
+            <Header sourceRepositoryUrl={sourceRepositoryUrl} setSettingsOpen={explorer.setSettingsOpen} />
+
+            <main className="content" role="main">
+                <div className="left-col">
+                    <FenBar explorer={explorer} />
+                    <BoardArea explorer={explorer} />
+                </div>
+
+                <div className="right-col">
+                    <ResultsPanel explorer={explorer} />
+                </div>
+
+                <div className="pgn-col">
+                    <PgnPanel explorer={explorer} />
+                </div>
+            </main>
+
+            <ScreenNav />
+
+            <PromotionDialog />
+            <PgnDialog explorer={explorer} />
+            <SettingsPanel explorer={explorer} />
+            <Toasts toasts={explorer.toasts} />
+        </>
+    );
+}

frontend/src/components/BoardArea.jsx

@@ -0,0 +1,41 @@
+import Segmented from './ui/Segmented.jsx';
+
+const SPARE_BLACK = ['bP', 'bN', 'bB', 'bR', 'bQ', 'bK'];
+const SPARE_WHITE = ['wP', 'wN', 'wB', 'wR', 'wQ', 'wK'];
+
+export default function BoardArea({ explorer }) {
+    const { fen, actions } = explorer;
+    const turn = fen.split(' ')[1] === 'b' ? 'b' : 'w';
+
+    return (
+        <div className="board-group">
+            <Segmented
+                className="turn-row" itemClassName="turn-btn" label="Side to move"
+                value={turn} onChange={actions.setTurn}
+                options={[
+                    { value: 'w', id: 'turn-white', title: 'White to move', content: <><span className="turn-pip turn-pip--w" aria-hidden="true"></span>White to move</> },
+                    { value: 'b', id: 'turn-black', title: 'Black to move', content: <><span className="turn-pip turn-pip--b" aria-hidden="true"></span>Black to move</> },
+                ]}
+            />
+            <div className="board-wrap" aria-label="Chess board">
+                <div id="board-wrap-inner" className="board-wrap-inner">
+                    <div className="spare-tray spare-tray--black" data-color="b">
+                        {SPARE_BLACK.map(code => (
+                            <button key={code} className="spare-piece" data-piece={code} type="button">
+                                <img src="" draggable="false" alt="" />
+                            </button>
+                        ))}
+                    </div>
+                    <div id="board"></div>
+                    <div className="spare-tray spare-tray--white" data-color="w">
+                        {SPARE_WHITE.map(code => (
+                            <button key={code} className="spare-piece" data-piece={code} type="button">
+                                <img src="" draggable="false" alt="" />
+                            </button>
+                        ))}
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}

frontend/src/components/FenBar.jsx

@@ -0,0 +1,60 @@
+import Button from './ui/Button.jsx';
+import Icon from './ui/Icon.jsx';
+
+export default function FenBar({ explorer }) {
+    const { fenInputRef, actions, ready, fen, locked, lockAutoplayDisabled, canBack, canForward, fenError, tb } = explorer;
+    const errorMessage = fenError ?? tb.error?.message ?? '';
+    const isCoverageError = !fenError && !!tb.error?.isCoverage;
+
+    function onFenKeyDown(e) {
+        if (e.key === 'Enter') { e.preventDefault(); actions.applyFen(e.currentTarget.value.trim()); }
+    }
+    function onApplyClick() {
+        const v = fenInputRef.current?.value.trim();
+        if (v) actions.applyFen(v);
+    }
+    function onLockClick(e) {
+        if (e.currentTarget.getAttribute('aria-disabled') === 'true') return;
+        actions.setLockedAction(!locked);
+    }
+
+    return (
+        <>
+            <div className="fen-block">
+                <div className="fen-input-wrap">
+                    <span className="fen-input-wrap__label" aria-hidden="true">FEN</span>
+                    <input
+                        id="fen-input" className="fen-input" type="text"
+                        ref={fenInputRef} defaultValue={fen}
+                        placeholder="Paste FEN here…" disabled={!ready}
+                        autoComplete="off" autoCorrect="off" autoCapitalize="off" spellCheck="false"
+                        aria-label="FEN position string"
+                        onKeyDown={onFenKeyDown}
+                    />
+                    <button id="lock-btn" type="button"
+                            className={`btn btn--icon-only btn--lock${locked ? ' is-locked' : ''}${lockAutoplayDisabled ? ' is-autoplay-disabled' : ''}`}
+                            aria-pressed={locked} aria-disabled={lockAutoplayDisabled}
+                            aria-label="Lock board to legal moves only"
+                            title={lockAutoplayDisabled ? 'Stop auto-play to change Lock' : (locked ? 'Unlock board' : 'Lock board (legal moves only)')}
+                            onClick={onLockClick}>
+                        <Icon name="lockOpen" className="btn__icon lock-icon lock-icon--unlocked" />
+                        <Icon name="lockClosed" className="btn__icon lock-icon lock-icon--locked" />
+                    </button>
+                </div>
+
+                <div className="fen-actions" role="toolbar" aria-label="Board actions">
+                    <Button id="apply-btn" variant="primary" grow icon="check" title="Apply FEN (Enter)" disabled={!ready} onClick={onApplyClick}>Apply</Button>
+                    <Button id="flip-btn" grow icon="flip" title="Flip board (F)" onClick={() => actions.flip()}>Flip</Button>
+                    <Button id="clear-btn" grow icon="trash" title="Clear board (C)" onClick={() => actions.clearBoard()}>Clear</Button>
+                    <Button id="copy-btn" grow icon="copy" title="Copy FEN to clipboard" aria-label="Copy FEN to clipboard" onClick={() => actions.copyFen()}>Copy</Button>
+                    <Button id="back-btn" iconOnly icon="arrowLeft" title="Undo (←)" aria-label="Undo" disabled={!canBack} onClick={() => actions.goBack()} />
+                    <Button id="forward-btn" iconOnly icon="arrowRight" title="Redo (→)" aria-label="Redo" disabled={!canForward} onClick={() => actions.goForward()} />
+                </div>
+            </div>
+
+            <div id="error-line" className={`error-line${isCoverageError ? ' is-coverage-error' : ''}`} role="alert" aria-live="polite">
+                {errorMessage}
+            </div>
+        </>
+    );
+}

frontend/src/components/Header.jsx

@@ -0,0 +1,51 @@
+import Icon from './ui/Icon.jsx';
+
+function Logo() {
+    return (
+        <svg className="site-header__logo" viewBox="0 0 24 24" aria-hidden="true">
+            <circle cx="12" cy="12" r="12" fill="var(--gold)" />
+            <g fill="var(--bg)">
+                <circle cx="12" cy="8.3" r="2.6" />
+                <path d="M10.4 11.2h3.2c.2 2 .9 3.3 2.2 5.4H8.2c1.3-2.1 2-3.4 2.2-5.4z" />
+                <rect x="7.2" y="16.6" width="9.6" height="1.9" rx="0.95" />
+            </g>
+        </svg>
+    );
+}
+
+export default function Header({ sourceRepositoryUrl, setSettingsOpen }) {
+    return (
+        <header className="site-header" role="banner">
+            <Logo />
+
+            <div className="site-header__brand">
+                <a href="https://noobpwnftw.github.io/chesstb/" className="site-header__title"
+                   title="Project home — code and downloads">ChessTB</a>
+                <span className="site-header__sep" aria-hidden="true">·</span>
+                <span className="site-header__sub">Explorer</span>
+            </div>
+
+            <nav className="site-header__nav" aria-label="Site links">
+                {sourceRepositoryUrl && (
+                    <a href={sourceRepositoryUrl} className="site-header__link site-header__link--icon"
+                       title="Source repository" aria-label="Source repository" target="_blank" rel="noopener noreferrer">
+                        <Icon name="repository" />
+                    </a>
+                )}
+                <a href="/admin" className="site-header__link site-header__link--icon"
+                   title="Cache dashboard" aria-label="Admin cache dashboard">
+                    <Icon name="gauge" />
+                </a>
+                <a href="/openapi.yaml" className="site-header__link site-header__link--icon"
+                   title="API specification" aria-label="API specification" target="_blank" rel="noopener noreferrer">
+                    <Icon name="code" />
+                </a>
+                <button id="settings-btn" className="site-header__link site-header__link--icon"
+                        title="Board settings" aria-label="Open board settings"
+                        onClick={(e) => { e.stopPropagation(); setSettingsOpen(o => !o); }}>
+                    <Icon name="settings" />
+                </button>
+            </nav>
+        </header>
+    );
+}

frontend/src/components/PgnDialog.jsx

@@ -0,0 +1,46 @@
+import { useEffect, useRef } from 'react';
+import Button from './ui/Button.jsx';
+
+export default function PgnDialog({ explorer }) {
+    const { pgnDialogOpen, pgnError, actions } = explorer;
+    const textareaRef = useRef(null);
+
+    useEffect(() => {
+        if (pgnDialogOpen) textareaRef.current?.focus();
+    }, [pgnDialogOpen]);
+
+    useEffect(() => {
+        if (!pgnDialogOpen) return;
+        function onKeydown(e) {
+            if (e.key === 'Escape') { e.preventDefault(); actions.closePgnDialog(); }
+        }
+        document.addEventListener('keydown', onKeydown);
+        return () => document.removeEventListener('keydown', onKeydown);
+    }, [pgnDialogOpen, actions]);
+
+    function onBackdropClick(e) {
+        if (e.target.id === 'pgn-dialog') actions.closePgnDialog();
+    }
+    function onParseClick() {
+        actions.parsePgnAction(textareaRef.current?.value || '');
+    }
+
+    return (
+        <div id="pgn-dialog" className={`pgn-dialog${pgnDialogOpen ? ' is-open' : ''}`}
+             role="dialog" aria-modal="true" aria-label="Import PGN" onClick={onBackdropClick}>
+            <div className="pgn-dialog__inner">
+                <div className="pgn-dialog__header">
+                    <h2 className="pgn-dialog__title">Import PGN</h2>
+                    <button id="pgn-close-btn" className="pgn-dialog__close" aria-label="Close" onClick={() => actions.closePgnDialog()}>✕</button>
+                </div>
+                <textarea id="pgn-input" className="pgn-dialog__textarea" ref={textareaRef}
+                          placeholder="Paste PGN here… e.g.  1. e4 e5 2. Nf3 Nc6 3. Bc4"
+                          rows={7} spellCheck="false" />
+                <div id="pgn-error" className="pgn-dialog__error" role="alert" aria-live="polite">{pgnError}</div>
+                <div className="pgn-dialog__actions">
+                    <Button id="pgn-parse-btn" onClick={onParseClick}>Import Game</Button>
+                </div>
+            </div>
+        </div>
+    );
+}

frontend/src/components/PgnPanel.jsx

@@ -0,0 +1,92 @@
+import { useEffect, useRef } from 'react';
+import { parseFenMeta } from '../engine/pgnFormat.js';
+import { buildMoveListItems, buildVariation } from '../engine/moveLine.js';
+import { scrollIntoViewWithin } from '../engine/scroll.js';
+import Button from './ui/Button.jsx';
+import Panel from './ui/Panel.jsx';
+
+function MoveButton({ node, isCurrent, chip, onGoTo }) {
+    const cls = `move-line__move${chip ? ' move-line__move--chip' : ''}${isCurrent ? ' is-current' : ''}`;
+    return <button className={cls} onClick={onGoTo ? () => onGoTo(node.id) : undefined}>{node.san}</button>;
+}
+
+function renderItems(items, nodes, rootChildren, currentId, onGoTo, keyPrefix) {
+    return items.flatMap((item, idx) => {
+        const key = `${keyPrefix}-${idx}`;
+        if (item.kind === 'row') {
+            const whiteEmpty = !item.white || item.white.placeholder;
+            return [
+                <div className="move-line__row" key={key}>
+                    <span className="move-line__num">{item.num}.</span>
+                    <span
+                        className={`move-line__cell move-line__cell--white${whiteEmpty ? ' move-line__cell--empty' : ''}${item.white?.placeholder ? ' move-line__cell--placeholder' : ''}${item.white?.isCurrent ? ' is-current' : ''}`}
+                        onClick={item.white && !item.white.placeholder ? () => onGoTo(item.white.node.id) : undefined}
+                    >
+                        {item.white?.placeholder ? '...' : null}
+                        {item.white && !item.white.placeholder && <MoveButton node={item.white.node} isCurrent={item.white.isCurrent} />}
+                    </span>
+                    <span
+                        className={`move-line__cell move-line__cell--black${!item.black ? ' move-line__cell--empty' : ''}${item.black?.isCurrent ? ' is-current' : ''}`}
+                        onClick={item.black ? () => onGoTo(item.black.node.id) : undefined}
+                    >
+                        {item.black && <MoveButton node={item.black.node} isCurrent={item.black.isCurrent} />}
+                    </span>
+                </div>,
+            ];
+        }
+        if (item.kind === 'para') {
+            return [
+                <div className="move-line__variation" key={key} style={{ paddingLeft: `${1.5 * item.depth}rem` }}>
+                    {item.chips.map((chip, ci) => chip.kind === 'num'
+                        ? <span className="move-line__num move-line__num--inline" key={ci}>{chip.text}</span>
+                        : <MoveButton key={ci} node={chip.node} isCurrent={chip.isCurrent} chip onGoTo={onGoTo} />)}
+                </div>,
+            ];
+        }
+        // 'variation' marker - expand lazily so nested forks don't need to
+        // be walked until they're actually reached.
+        const varItems = buildVariation(nodes, rootChildren, item.nodeIds, item.whiteToMove, item.moveNum, currentId, item.depth);
+        return renderItems(varItems, nodes, rootChildren, currentId, onGoTo, `${key}-v`);
+    });
+}
+
+export default function PgnPanel({ explorer }) {
+    const { moveHistory, startFen, historyInitialized, actions } = explorer;
+    const { nodes, rootChildren, currentId } = moveHistory;
+    const scrollRef = useRef(null);
+
+    useEffect(() => {
+        const container = scrollRef.current;
+        const current = container?.querySelector('.is-current');
+        scrollIntoViewWithin(current, container);
+    }, [currentId, nodes]);
+
+    let content = null;
+    if (!historyInitialized) {
+        content = null;   // no render until Board reports its first move-tree change
+    } else if (!rootChildren || rootChildren.length === 0) {
+        content = <span className="move-line__empty">No moves yet</span>;
+    } else {
+        const { turn, fullmove } = parseFenMeta(startFen);
+        const items = buildMoveListItems(nodes, rootChildren, currentId, turn, fullmove);
+        content = renderItems(items, nodes, rootChildren, currentId, actions.goToNode, 'm');
+    }
+
+    return (
+        <Panel
+            className="pgn-panel" label="Game PGN" title="PGN"
+            end={
+                <>
+                    <Button id="pgn-btn" compact icon="upload" title="Import PGN game" onClick={() => actions.openPgnDialog()}>Import</Button>
+                    <Button id="pgn-export-btn" compact icon="download" title="Download game as PGN" onClick={() => actions.exportPgn()}>Export</Button>
+                </>
+            }
+        >
+            <div className="pgn-moves-scroll" role="region" aria-label="Move history" tabIndex={0} ref={scrollRef}>
+                <div id="move-line" className="move-line" role="list" aria-label="Played moves">
+                    {content}
+                </div>
+            </div>
+        </Panel>
+    );
+}

frontend/src/components/PromotionDialog.jsx

@@ -0,0 +1,23 @@
+export default function PromotionDialog() {
+    return (
+        <div id="promotion-dialog" className="promotion-dialog" role="dialog" aria-modal="true" aria-label="Choose promotion piece">
+            <div className="promotion-tray">
+                <span className="promotion-tray__title">Promote pawn to:</span>
+                <div className="promotion-tray__pieces">
+                    <button className="promotion-piece-btn" data-piece="q" aria-label="Queen">
+                        <img src="" alt="Queen" draggable="false" />
+                    </button>
+                    <button className="promotion-piece-btn" data-piece="r" aria-label="Rook">
+                        <img src="" alt="Rook" draggable="false" />
+                    </button>
+                    <button className="promotion-piece-btn" data-piece="b" aria-label="Bishop">
+                        <img src="" alt="Bishop" draggable="false" />
+                    </button>
+                    <button className="promotion-piece-btn" data-piece="n" aria-label="Knight">
+                        <img src="" alt="Knight" draggable="false" />
+                    </button>
+                </div>
+            </div>
+        </div>
+    );
+}

frontend/src/components/ResultsPanel.jsx

@@ -0,0 +1,183 @@
+import { useEffect, useRef } from 'react';
+import { Tablebase } from '../engine/tablebase.js';
+import { initMovesGutterSync } from '../engine/scroll.js';
+import Button from './ui/Button.jsx';
+import Panel from './ui/Panel.jsx';
+import Segmented from './ui/Segmented.jsx';
+
+const METRICS = ['dtz', 'dtc', 'dtm', 'dtm50'];
+const METRIC_LABEL = { dtz: 'DTZ', dtc: 'DTC', dtm: 'DTM', dtm50: 'DTM50' };
+const METRIC_OPTIONS = METRICS.map(m => ({ value: m, label: METRIC_LABEL[m] }));
+
+const COLUMN_CLASSES = [
+    'col-rank',
+    'group-dtz col-move', 'group-dtz col-score',
+    'group-dtc col-move', 'group-dtc col-score',
+    'group-dtm col-move', 'group-dtm col-score',
+    'group-dtm50 col-move', 'group-dtm50 col-score',
+];
+
+function MetricColGroup() {
+    return (
+        <colgroup>
+            {COLUMN_CLASSES.map(cls => <col key={cls} className={cls} />)}
+        </colgroup>
+    );
+}
+
+function DotIcon({ prefix }) {
+    return (
+        <svg viewBox="0 0 16 16" aria-hidden="true" className={`${prefix}__icon`}>
+            <circle cx="8" cy="8" r="8" className={`${prefix}__bg`} />
+            <circle cx="8" cy="4.3" r="1.05" className={`${prefix}__mark`} />
+            <rect x="7.1" y="6.5" width="1.8" height="6.2" rx="0.9" className={`${prefix}__mark`} />
+        </svg>
+    );
+}
+
+function Cell({ cell, idx }) {
+    const props = { key: idx, className: cell.className };
+    if (cell.title) props.title = cell.title;
+    if (cell.headers) props.headers = cell.headers;
+    if (cell.interactive) {
+        props['data-san'] = cell.dataSan;
+        props['data-child-fen'] = cell.dataChildFen || '';
+        props.tabIndex = 0;
+        props.role = 'button';
+        props['aria-label'] = cell.kind === 'score'
+            ? `${cell.title}; Play ${cell.dataSan}` : `Play ${cell.dataSan}`;
+    } else if (cell.kind === 'score' && cell.title) {
+        props['aria-label'] = cell.title;
+    }
+    if (cell.outcome !== undefined) props['data-outcome'] = cell.outcome;
+    return (
+        <td {...props}>
+            {cell.text}
+            {cell.warning && <span className="warning-dot" title={cell.warning}><DotIcon prefix="warning-dot" /></span>}
+            {cell.info && <span className="info-dot" title={cell.info}><DotIcon prefix="info-dot" /></span>}
+        </td>
+    );
+}
+
+function AutoplayButton({ metric, explorer }) {
+    const { autoplayMetric, autoplayAvailability, actions } = explorer;
+    const info = autoplayAvailability[metric];
+    const isPlaying = autoplayMetric === metric;
+    return (
+        <button id={`autoplay-btn-${metric}`} className={`btn btn--col-autoplay${isPlaying ? ' is-playing' : ''}`}
+                disabled={info.disabled}
+                title={isPlaying ? `Stop ${METRIC_LABEL[metric]} auto-play` : info.title}
+                aria-label={`Auto-play best ${METRIC_LABEL[metric]} move`}
+                onClick={() => actions.toggleAutoPlay(metric)}>
+            <svg className="autoplay-icon autoplay-icon--play" viewBox="0 0 12 12" aria-hidden="true">
+                <path d="M3 2.1 L9.6 6 L3 9.9 Z" />
+            </svg>
+            <svg className="autoplay-icon autoplay-icon--stop" viewBox="0 0 12 12" aria-hidden="true">
+                <rect x="2.4" y="2.4" width="7.2" height="7.2" rx="1" />
+            </svg>
+        </button>
+    );
+}
+
+export default function ResultsPanel({ explorer }) {
+    const { tb, activeMetric, actions } = explorer;
+    const tbodyRef = useRef(null);
+    const cleanupRef = useRef(null);
+
+    useEffect(() => {
+        cleanupRef.current = Tablebase.attachTableEvents(tbodyRef.current);
+        return () => cleanupRef.current?.();
+    }, []);
+
+    useEffect(() => initMovesGutterSync(), []);
+
+    useEffect(() => {
+        Tablebase.notifyTableRendered();
+    }, [tb.rows, tb.rootRow]);
+
+    return (
+        <Panel
+            className={`results-panel${tb.pending ? ' is-pending' : ''}${tb.loading ? ' is-loading' : ''}`}
+            label="Tablebase results" title="Tablebase Result"
+            start={
+                <div className="probe-status" style={{ display: tb.progress.visible ? 'flex' : 'none' }}>
+                    <span id="probe-progress-label" className="probe-progress-label" aria-live="polite">{tb.progress.label}</span>
+                    <div id="probe-progress" className={`probe-progress${tb.progress.pct === null ? ' is-indeterminate' : ''}`} aria-hidden="true">
+                        <div className="probe-progress__fill" style={{ width: tb.progress.pct === null ? undefined : `${tb.progress.pct}%` }}></div>
+                    </div>
+                </div>
+            }
+            end={
+                <>
+                    <span id="move-count" className="panel-header__count" aria-live="polite" aria-atomic="true">{tb.moveCount}</span>
+                    <Button id="export-btn" compact iconOnly icon="download" title="Download move table as CSV" onClick={() => actions.exportCsv()}>CSV</Button>
+                </>
+            }
+        >
+            <Segmented
+                className="metric-tabs" itemClassName="metric-tab" variant="tabs" label="Tablebase metric"
+                options={METRIC_OPTIONS} value={activeMetric} onChange={actions.setActiveMetric}
+            />
+
+            <div className="moves-view">
+                <div className="moves-head">
+                    <table className="moves-table moves-table--head" data-active-metric={activeMetric}>
+                        <MetricColGroup />
+                        <thead>
+                            <tr className="group-row">
+                                <th></th>
+                                {METRICS.map(m => (
+                                    <th key={m} id={`th-${m}-grp`} className={`group-${m}`} colSpan={2}>
+                                        <span className="group-row-inner">
+                                            <span className="group-label">{METRIC_LABEL[m]}</span>
+                                            <AutoplayButton metric={m} explorer={explorer} />
+                                        </span>
+                                    </th>
+                                ))}
+                            </tr>
+                            <tr className="col-row">
+                                <th id="th-rank" className="col-rank" scope="col" aria-label="Rank">#</th>
+                                <th id="th-dtz-move" className="group-dtz col-move" scope="col">Move</th>
+                                <th id="th-dtz-score" className="group-dtz col-score" scope="col">Score</th>
+                                <th id="th-dtc-move" className="group-dtc col-move" scope="col">Move</th>
+                                <th id="th-dtc-score" className="group-dtc col-score" scope="col">Score/Order</th>
+                                <th id="th-dtm-move" className="group-dtm col-move" scope="col">Move</th>
+                                <th id="th-dtm-score" className="group-dtm col-score" scope="col">Score</th>
+                                <th id="th-dtm50-move" className="group-dtm50 col-move" scope="col">Move</th>
+                                <th id="th-dtm50-score" className="group-dtm50 col-score" scope="col">Score</th>
+                            </tr>
+                            <tr id="root-row" className={`root-row${tb.rootRow ? '' : ' is-hidden'}`}>
+                                <td className="col-rank"></td>
+                                {(tb.rootRow?.cells ?? []).map((cell, idx) => <Cell key={idx} cell={cell} idx={idx} />)}
+                            </tr>
+                        </thead>
+                    </table>
+                </div>
+
+                <div className="moves-body-scroll" role="region" aria-label="Move rankings" tabIndex={0}>
+                    <table className="moves-table moves-table--body" data-active-metric={activeMetric} aria-label="Moves ranked by tablebase metric">
+                        <caption className="sr-only">
+                            When Show Root Row is enabled in Settings, the current position&apos;s own score is shown
+                            first, followed by legal moves ranked by Distance to Zeroing, Distance to Conversion,
+                            Distance to Mate, and Distance to Mate with the 50-move rule
+                        </caption>
+                        <MetricColGroup />
+                        <tbody id="moves-tbody" ref={tbodyRef}>
+                            {tb.rows.map(row => (
+                                <tr key={row.rank}>
+                                    <td className="col-rank" headers="th-rank">{row.rank}</td>
+                                    {row.cells.map((cell, idx) => <Cell key={idx} cell={cell} idx={idx} />)}
+                                </tr>
+                            ))}
+                        </tbody>
+                    </table>
+
+                    <div id="moves-empty-state" className="moves-empty-state" style={{ display: tb.emptyState ? 'flex' : 'none' }} aria-live="polite">
+                        <span className="moves-empty-state__icon" aria-hidden="true">♟</span>
+                        <p>{tb.emptyMessage}</p>
+                    </div>
+                </div>
+            </div>
+        </Panel>
+    );
+}

frontend/src/components/ScreenNav.jsx

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'react';
+
+const SCREENS = ['Board', 'Results', 'Moves'];
+
+export default function ScreenNav() {
+    const [current, setCurrent] = useState(0);
+
+    useEffect(() => {
+        const content = document.querySelector('.content');
+        if (!content) return undefined;
+        const onScroll = () => setCurrent(Math.round(content.scrollLeft / content.clientWidth));
+        content.addEventListener('scroll', onScroll, { passive: true });
+        return () => content.removeEventListener('scroll', onScroll);
+    }, []);
+
+    function goTo(index) {
+        const content = document.querySelector('.content');
+        if (!content) return;
+        const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        content.scrollTo({ left: index * content.clientWidth, behavior: reduced ? 'auto' : 'smooth' });
+    }
+
+    return (
+        <nav className="screen-nav" aria-label="Screens">
+            {SCREENS.map((label, i) => (
+                <button key={label} type="button" className="screen-nav__item"
+                        aria-current={i === current ? 'page' : undefined} onClick={() => goTo(i)}>
+                    {label}
+                </button>
+            ))}
+        </nav>
+    );
+}

frontend/src/components/SettingsPanel.jsx

@@ -0,0 +1,91 @@
+import { useEffect, useRef } from 'react';
+import { formatAutoPlayDelay } from '../hooks/useExplorer.js';
+import Button from './ui/Button.jsx';
+
+const SHORTCUTS = [['Enter', 'Apply'], ['F', 'Flip'], ['C', 'Clear'], ['←', 'Back'], ['→', 'Forward']];
+
+const DELAY_MIN = 0;
+const DELAY_MAX = 2500;
+
+export default function SettingsPanel({ explorer }) {
+    const { settingsOpen, setSettingsOpen, showRootRow, variant, autoplayDelayMs, actions } = explorer;
+    const panelRef = useRef(null);
+    const chess960 = variant === 'chess960';
+
+    useEffect(() => {
+        if (!settingsOpen) return;
+        function onDocClick(e) {
+            if (panelRef.current && !panelRef.current.contains(e.target) && !e.target.closest('#settings-btn')) {
+                setSettingsOpen(false);
+            }
+        }
+        function onKeydown(e) {
+            if (e.key === 'Escape') { e.preventDefault(); setSettingsOpen(false); }
+        }
+        document.addEventListener('click', onDocClick);
+        document.addEventListener('keydown', onKeydown);
+        return () => {
+            document.removeEventListener('click', onDocClick);
+            document.removeEventListener('keydown', onKeydown);
+        };
+    }, [settingsOpen, setSettingsOpen]);
+
+    const pct = ((autoplayDelayMs - DELAY_MIN) / (DELAY_MAX - DELAY_MIN)) * 100;
+
+    return (
+        <div id="settings-panel" ref={panelRef} className={`settings-panel${settingsOpen ? ' is-open' : ''}`}
+             role="dialog" aria-modal="false" aria-label="Board settings">
+            <div className="settings-panel__header">
+                <span className="settings-panel__title">Board Settings</span>
+                <Button id="settings-close-btn" compact iconOnly icon="close" aria-label="Close settings"
+                        onClick={() => setSettingsOpen(false)} />
+            </div>
+
+            <div className="settings-row settings-row--toggle">
+                <label className="settings-toggle" htmlFor="show-root-row-toggle">
+                    <span className="settings-toggle__label">Show Root Row</span>
+                    <span className="toggle-switch">
+                        <input type="checkbox" id="show-root-row-toggle" className="toggle-switch__input" role="switch"
+                               checked={showRootRow} onChange={(e) => actions.setShowRootRowAction(e.target.checked)} />
+                        <span className="toggle-switch__track" aria-hidden="true"></span>
+                    </span>
+                </label>
+            </div>
+
+            <div className="settings-row settings-row--toggle">
+                <label className="settings-toggle" htmlFor="chess960-mode-toggle">
+                    <span className="settings-toggle__label">Chess960 Mode</span>
+                    <span className="toggle-switch">
+                        <input type="checkbox" id="chess960-mode-toggle" className="toggle-switch__input" role="switch"
+                               checked={chess960} onChange={(e) => actions.setChess960Action(e.target.checked)} />
+                        <span className="toggle-switch__track" aria-hidden="true"></span>
+                    </span>
+                </label>
+            </div>
+
+            <div className="settings-row settings-row--slider">
+                <span className="settings-slider__label">Autoplay Delay</span>
+                <div className="settings-slider__control">
+                    <input type="range" id="autoplay-delay-slider" className="range-slider"
+                           min={DELAY_MIN} max={DELAY_MAX} step={50} value={autoplayDelayMs}
+                           style={{ '--range-fill': `${pct}%` }}
+                           aria-label="Autoplay delay" aria-valuetext={formatAutoPlayDelay(autoplayDelayMs)}
+                           onChange={(e) => actions.setAutoplayDelayAction(parseInt(e.target.value, 10))} />
+                    <div className="range-slider__ticks" aria-hidden="true">
+                        <span>0s</span><span>1.25s</span><span>2.5s</span>
+                    </div>
+                </div>
+                <span className="settings-slider__value" id="autoplay-delay-value">{formatAutoPlayDelay(autoplayDelayMs)}</span>
+            </div>
+
+            <div className="settings-row settings-row--shortcuts">
+                <span className="settings-shortcuts__title">Keyboard Shortcuts</span>
+                <ul className="settings-shortcuts__list">
+                    {SHORTCUTS.map(([key, action]) => (
+                        <li key={key}><kbd>{key}</kbd> {action}</li>
+                    ))}
+                </ul>
+            </div>
+        </div>
+    );
+}

frontend/src/components/Toasts.jsx

@@ -0,0 +1,9 @@
+export default function Toasts({ toasts }) {
+    return (
+        <div id="toast-container" className="toast-container" aria-live="polite" aria-atomic="false">
+            {toasts.map(t => (
+                <div key={t.id} className={`toast${t.leaving ? ' is-out' : ''}`}>{t.message}</div>
+            ))}
+        </div>
+    );
+}

frontend/src/components/ui/Button.jsx

@@ -0,0 +1,18 @@
+import Icon from './Icon.jsx';
+
+export default function Button({ variant, compact, grow, iconOnly, icon, className = '', children, ...rest }) {
+    const cls = [
+        'btn',
+        variant === 'primary' && 'btn--apply',
+        compact && 'btn--compact',
+        grow && 'btn--grow',
+        iconOnly && 'btn--icon-only',
+        className,
+    ].filter(Boolean).join(' ');
+    return (
+        <button type="button" className={cls} {...rest}>
+            {icon && <Icon name={icon} className="btn__icon" />}
+            {children}
+        </button>
+    );
+}

frontend/src/components/ui/Icon.jsx

@@ -0,0 +1,43 @@
+const STROKE_WIDTH = { check: 2.5, close: 2.5 };
+
+const PATHS = {
+    repository: <><path d="M7 8.5v7m10-7V10a4 4 0 0 1-4 4H7" /><circle cx="7" cy="6" r="2.5" /><circle cx="7" cy="18" r="2.5" /><circle cx="17" cy="6" r="2.5" /></>,
+    check: <polyline points="20 6 9 17 4 12" />,
+    close: <><line x1="18" y1="6" x2="6" y2="18" /><line x1="6" y1="6" x2="18" y2="18" /></>,
+    flip: <><path d="M7 16V4m0 0L3 8m4-4 4 4" /><path d="M17 8v12m0 0 4-4m-4 4-4-4" /></>,
+    trash: <><path d="M3 6h18" /><path d="M8 6V4h8v2" /><path d="M19 6l-1 14H6L5 6" /></>,
+    copy: <><rect x="9" y="9" width="13" height="13" rx="2" /><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" /></>,
+    arrowLeft: <><path d="M19 12H5" /><polyline points="12 19 5 12 12 5" /></>,
+    arrowRight: <><path d="M5 12h14" /><polyline points="12 5 19 12 12 19" /></>,
+    download: <><path d="M12 3v12" /><polyline points="7 10 12 15 17 10" /><path d="M4 19h16" /></>,
+    upload: <><path d="M12 21V9" /><polyline points="7 14 12 9 17 14" /><path d="M4 5h16" /></>,
+    lockOpen: <><rect x="5" y="11" width="14" height="10" rx="2" /><path d="M8 11V7a4 4 0 0 1 8 0" /></>,
+    lockClosed: <><rect x="5" y="11" width="14" height="10" rx="2" /><path d="M8 11V7a4 4 0 0 1 8 0v4" /></>,
+    gauge: <><path d="M12 14a2 2 0 1 0 0-4 2 2 0 0 0 0 4Z" /><path d="M12 14 16 8" /><path d="M5 19a9 9 0 1 1 14 0" /></>,
+    code: <><polyline points="16 18 22 12 16 6" /><polyline points="8 6 2 12 8 18" /></>,
+    settings: (
+        <>
+            <circle cx="12" cy="12" r="3" />
+            <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" />
+        </>
+    ),
+};
+
+const GITHUB_PATH = 'M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12Z';
+
+export default function Icon({ name, className = '' }) {
+    const cls = `icon${className ? ` ${className}` : ''}`;
+    if (name === 'github') {
+        return (
+            <svg className={cls} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+                <path fillRule="evenodd" clipRule="evenodd" d={GITHUB_PATH} />
+            </svg>
+        );
+    }
+    return (
+        <svg className={cls} viewBox="0 0 24 24" fill="none" stroke="currentColor"
+             strokeWidth={STROKE_WIDTH[name] ?? 2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+            {PATHS[name]}
+        </svg>
+    );
+}

frontend/src/components/ui/Panel.jsx

@@ -0,0 +1,14 @@
+export default function Panel({ label, title, start, end, className = '', children }) {
+    return (
+        <section className={`panel${className ? ` ${className}` : ''}`} aria-label={label}>
+            <div className="panel-header">
+                <div className="panel-header__start">
+                    <span className="panel-header__title">{title}</span>
+                    {start}
+                </div>
+                <div className="panel-header__end">{end}</div>
+            </div>
+            {children}
+        </section>
+    );
+}

frontend/src/components/ui/Segmented.jsx

@@ -0,0 +1,38 @@
+import { useRef } from 'react';
+
+export default function Segmented({ label, options, value, onChange, variant = 'radio', className = '', itemClassName = '' }) {
+    const groupRef = useRef(null);
+    const tabs = variant === 'tabs';
+
+    function onKeyDown(e) {
+        const step = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }[e.key];
+        if (!step) return;
+        e.preventDefault();
+        e.stopPropagation();
+        const i = options.findIndex(o => o.value === value);
+        const next = options[(i + step + options.length) % options.length];
+        onChange(next.value);
+        groupRef.current?.querySelector(`[data-value="${next.value}"]`)?.focus();
+    }
+
+    return (
+        <div ref={groupRef} className={className} role={tabs ? 'tablist' : 'radiogroup'} aria-label={label} onKeyDown={onKeyDown}>
+            {options.map(o => {
+                const active = o.value === value;
+                return (
+                    <button
+                        key={o.value} id={o.id} type="button" data-value={o.value}
+                        className={`${itemClassName}${active ? ' is-active' : ''}`}
+                        role={tabs ? 'tab' : 'radio'}
+                        {...(tabs ? { 'aria-selected': active } : { 'aria-checked': active })}
+                        tabIndex={active ? 0 : -1}
+                        title={o.title}
+                        onClick={() => onChange(o.value)}
+                    >
+                        {o.content ?? o.label}
+                    </button>
+                );
+            })}
+        </div>
+    );
+}

frontend/src/engine/board.js

@@ -0,0 +1,1282 @@
+/**
+ * board.js: Chessground wrapper
+ *
+ * Wraps the vendor Chessground() instance and a chessops position, and owns:
+ *   - A branching move tree (_nodes/_rootChildren) used by the PGN panel:
+ *     playing a move after navigating back adds a variation instead of
+ *     overwriting the continuation from that point. A plain
+ *     undo/redo FEN stack (_history/_future) sits alongside it as a
+ *     fallback for Back/Forward once navigation walks off the tree (e.g.
+ *     past a board edit that started a fresh one).
+ *   - Best-move arrows for DTZ/DTC/DTM/DTM50, drawn via chessground's
+ *     native drawable.autoShapes.
+ *   - Click-to-place editing: click a spare piece, then click a square to
+ *     place it. Drag-from-tray is also supported (chessground's
+ *     dragNewPiece()).
+ *   - goToNode() - jump to any node in the current move tree (used by
+ *     the PGN panel, including variation moves) without resetting the tree
+ *     or re-triggering a probe for a position that's already been evaluated.
+ *   - Board/piece theming: the piece image path is owned by theme.js
+ *     (Theme.pieceThemeFn()). reconstruct() updates the piece
+ *     CSS <link> and repopulates the spare-tray/promotion-dialog images;
+ *     chessground is never destroyed and rebuilt for theming, since piece
+ *     images are plain CSS.
+ *   - The active rules variant (Standard / Chess960) and the FEN protocol
+ *     boundary between them. chessops's own `Chess` class implements both
+ *     rulesets' move generation/legality/SAN identically and has no
+ *     variant concept of its own - castling legality, paths, and rook
+ *     squares are computed the same way regardless of variant (see
+ *     chessgroundDests() below for the one place chessops is told which
+ *     variant is active, purely to choose which destinations chessground
+ *     is offered). The application's Standard-vs-Chess960 FEN contract is
+ *     stricter than chessops's generic one: chessops's FEN parser resolves
+ *     a 'K'/'Q'/'k'/'q' castling letter to whichever rook sits on the
+ *     correct side of the king wherever the king happens to be (needed for
+ *     Chess960, where the king isn't always on the e-file) and also accepts
+ *     Shredder-FEN/X-FEN rook-file letters unconditionally - neither of
+ *     which is a legal Standard-chess castling encoding. _buildPosition()
+ *     below enforces the application's Standard-mode castling contract
+ *     (only 'K'/'Q'/'k'/'q', each requiring the king on its e1/e8 home
+ *     square and the resolved rook on its exact a1/h1/a8/h8 home square)
+ *     before trusting chessops's more permissive parse, so the frontend
+ *     and the backend (see app.py's _validate_fen_parts and python-chess's
+ *     own chess960=False castling validation) agree on whether a given FEN
+ *     is valid for the active variant.
+ *
+ * Every position-changing action - setPosition(), clear(), playMove(),
+ * goBack()/goForward(), board edits (off-board drop, board-setup drag,
+ * click-to-place), setVariant() - records itself (in the tree or the
+ * undo/redo stack, whichever applies) and invokes the onPositionChange
+ * callback itself, so callers never need to remember to do either one
+ * manually.
+ *
+ * The chessops position (_position) is the single source of truth for
+ * position/legality - chessground is a dumb, controlled rendering surface.
+ * Every position-changing function ends with a call to _syncChessground(),
+ * which pushes _position's current FEN (plus turn colour, check state, and
+ * last-move squares) into chessground in one shot. The core mutation
+ * handler (_handleBoardMutation) is idempotent rather than tracking which
+ * of chessground's several event hooks handled a given user action,
+ * because chessground fires multiple, differently-scoped events for what
+ * is logically one move. For an ordinary relocation, events.move fires
+ * first, then events.change, then movable.events.after (see board.ts's
+ * baseMove()/userMove()). events.change carries no orig/dest, so if it won
+ * the idempotency race it would take the generic "board edit" branch and
+ * leave movable.events.after's orig/dest with nothing left to act on.
+ * events.move is therefore the primary handler: it fires before
+ * events.change and, unlike movable.events.after, carries orig/dest (plus
+ * capture info), so it wins the idempotency race with enough information
+ * to classify the move correctly. events.change and movable.events.after
+ * are wired as idempotent fallbacks, and events.change is the only hook
+ * that fires for an off-board deletion (drag.ts's deleteOnDropOff branch
+ * calls it directly, with no accompanying events.move/
+ * movable.events.after).
+ */
+
+import { Chessground } from '../vendor/chessground.min.js';
+import { Theme }       from './theme.js';
+import * as Storage    from './storage.js';
+
+import { Chess, Castles, castlingSide } from '../vendor/chessops/chess.js';
+import { parseFen, makeFen }       from '../vendor/chessops/fen.js';
+import { chessgroundDests }        from '../vendor/chessops/compat.js';
+import { parseSan, makeSan }       from '../vendor/chessops/san.js';
+import { parseSquare, makeSquare } from '../vendor/chessops/util.js';
+
+// ── Variant ──────────────────────────────────────────────────────────────
+// The application's rules-mode state. Distinct from chessops's own `rules`
+// property (always 'chess' for both Standard and Chess960 - see the
+// module doc comment above): this is application metadata that travels
+// alongside the position, never derived from it.
+const VARIANTS = Object.freeze({ STANDARD: 'standard', CHESS960: 'chess960' });
+
+const Board = (() => {
+
+    let cg     = null;   // Chessground instance
+    let _position = null;   // chessops Chess position - see module doc comment
+    let _variant  = VARIANTS.STANDARD;
+    let _onPositionChange    = null;
+    let _onMoveHistoryChange = null;
+
+    let _pendingPromotion = null;
+
+    // ── Lock mode ────────────────────────────────────────────────────────────
+    // When true, the board only accepts legal moves for the side to move;
+    // spare-piece placement and off-board deletion are disabled. Toggled via
+    // setLocked(). Moves played through the ranked-moves table, auto-play, or
+    // the PGN panel are unaffected, since those are already always legal.
+    let _locked = false;
+
+    // [orig, dest] of the most recently played/navigated-to move, or
+    // undefined. Fed into chessground's `lastMove` config on every sync.
+    // Tracked separately from the move tree because Back/Forward/goToNode
+    // land on a node that already has its own from/to squares recorded;
+    // this variable is what lets _syncChessground() highlight the right
+    // squares for those navigations too, not just for a freshly played move.
+    let _lastMoveKeys = undefined;
+
+    // ── Undo / redo stacks ────────────────────────────────────────────────────
+    // Plain chronological FEN log, used only as a Back/Forward fallback once
+    // navigation walks off the current move tree entirely (e.g. past a board
+    // edit - edits aren't part of the tree, see _resetMoveLine below). While
+    // the current position is inside the tree, goBack()/goForward() use the
+    // tree's parent/activeChild pointers instead (see below).
+    let _history = [];
+    let _future  = [];
+    const _MAX_HISTORY = 100;
+
+    function _pushHistory(fen) {
+        _history.push(fen);
+        if (_history.length > _MAX_HISTORY) _history.shift();
+        _future = [];   // any new position discards the redo stack
+    }
+
+    // ── Move tree ──────────────────────────────────────────────────────────────
+    // Only legal moves via playMove() (and the promotion/drag-move
+    // equivalents) are recorded here. setPosition() / clear() / board edits /
+    // setVariant() reset the tree.
+    //
+    // Each node is {id, san, fen, from, to, parentId, children, activeChild}.
+    // `id` is also the node's index in _nodes. parentId === ROOT (-1) means
+    // the node replies to the tree's start position (_startFen). `children`
+    // lists every move tried from that node - children[0] renders as the
+    // "main" continuation, children[1+] as parenthesised variations.
+    // `activeChild` is whichever child Forward should follow from that node
+    // (whichever branch was most recently played/clicked into) - not
+    // necessarily children[0]. `from`/`to` are the move's origin/destination
+    // squares exactly as played (for a Chess960 castle, the king's origin
+    // and whichever destination square chessground/chessops reported,
+    // never assumed to be a fixed c/g-file square), recorded alongside
+    // san/fen so lastMove highlighting works when navigating the tree, not
+    // just on a freshly-played move.
+    //
+    // The PGN panel and PGN export walk this tree recursively so alternate
+    // moves are preserved as variations instead of overwriting history.
+    const ROOT = -1;
+
+    let _nodes           = [];   // [{id, san, fen, from, to, parentId, children:[], activeChild}]
+    let _rootChildren    = [];   // ids of moves played directly from _startFen
+    let _rootActiveChild = null;
+    let _currentId        = ROOT; // id of the node currently shown, or ROOT for _startFen itself
+    let _startFen         = null; // FEN the current tree began from (for PGN formatting)
+
+    function _childrenOf(id) { return id === ROOT ? _rootChildren : _nodes[id].children; }
+    function _activeChildOf(id) { return id === ROOT ? _rootActiveChild : _nodes[id].activeChild; }
+    function _setActiveChild(id, childId) {
+        if (id === ROOT) _rootActiveChild = childId;
+        else _nodes[id].activeChild = childId;
+    }
+
+    function _resetMoveLine() {
+        _nodes            = [];
+        _rootChildren     = [];
+        _rootActiveChild  = null;
+        _currentId        = ROOT;
+        _future           = [];
+        _startFen         = _position ? currentFen() : null;
+        if (_onMoveHistoryChange) _emitHistory();
+    }
+
+    function _emitHistory() {
+        if (_onMoveHistoryChange) {
+            _onMoveHistoryChange({
+                nodes: _nodes, rootChildren: _rootChildren,
+                rootActiveChild: _rootActiveChild, currentId: _currentId,
+            }, _startFen);
+        }
+    }
+
+    // Records a played move as a child of the current node. If the current
+    // node already has a child with this exact SAN (the user replayed a move
+    // already tried from this point), that existing node is reused instead
+    // of creating a duplicate. Otherwise a new node is created and appended
+    // to the end of the children list, so an already-explored continuation
+    // stays the main line and the newly-played move is recorded as a
+    // parenthesised variation.
+    function _addMove(san, fen, from, to) {
+        _future = [];   // starting a fresh line invalidates any pre-tree redo
+        const kids = _childrenOf(_currentId);
+        let childId = kids.find(id => _nodes[id].san === san);
+        if (childId === undefined) {
+            childId = _nodes.length;
+            _nodes.push({ id: childId, san, fen, from, to, parentId: _currentId, children: [], activeChild: null });
+            kids.push(childId);
+        }
+        // (else: reused an existing child - same SAN replayed from this node)
+        _setActiveChild(_currentId, childId);
+        _currentId = childId;
+        return childId;
+    }
+
+    // ── Piece theme ───────────────────────────────────────────────────────────
+    // Delegates to theme.js, which owns the active piece set. Kept as a local
+    // wrapper (rather than calling Theme.pieceThemeFn() inline everywhere)
+    // so callers below don't need to know theme.js exists. Resolved once on
+    // first use rather than re-fetched from Theme on every call.
+    let _pieceThemeFn = null;
+    function _pieceTheme(piece) {
+        if (!_pieceThemeFn) _pieceThemeFn = Theme.pieceThemeFn();
+        return _pieceThemeFn(piece);
+    }
+
+    // ── chessops adapter ─────────────────────────────────────────────────────
+    // Small translation layer between this file's FEN-string/algebraic-key
+    // vocabulary and chessops's Setup/Position/numeric-square vocabulary.
+    // Contains no chess rules of its own - every legality, castling, and
+    // check/mate determination below is delegated to chessops.
+
+    function currentFen() { return makeFen(_position.toSetup()); }
+    function _turnChar(pos) { return pos.turn === 'white' ? 'w' : 'b'; }
+
+    function _fenErrorMessage(err) {
+        switch (err && err.message) {
+            case 'ERR_CASTLING':
+                return "Invalid castling availability: expected some combination of 'K', 'Q', 'k', 'q', rook-file letters 'a'-'h'/'A'-'H', or '-'.";
+            case 'ERR_TURN':      return 'Invalid FEN: side to move must be "w" or "b".';
+            case 'ERR_EP_SQUARE': return 'Invalid FEN: en passant target square is not valid.';
+            case 'ERR_HALFMOVES': return 'Invalid FEN: halfmove clock is not valid.';
+            case 'ERR_FULLMOVES': return 'Invalid FEN: fullmove number is not valid.';
+            case 'ERR_BOARD':     return 'Invalid FEN: board part is not valid.';
+            default:               return 'Invalid FEN: position violates chess rules.';
+        }
+    }
+    function _positionErrorMessage(err) {
+        switch (err && err.message) {
+            case 'ERR_KINGS':            return 'Position must have exactly one king per side.';
+            case 'ERR_OPPOSITE_CHECK':   return 'Invalid position: the side not to move is already in check.';
+            case 'ERR_PAWNS_ON_BACKRANK': return 'Invalid position: a pawn is on the back rank.';
+            case 'ERR_EMPTY':            return 'Position has no pieces.';
+            default:                      return 'Invalid FEN: position violates chess rules.';
+        }
+    }
+
+    // A castling-availability letter with no matching king/rook pair on the
+    // board (e.g. "K" with no white king and rook on their home squares) is
+    // syntactically valid but not a legal right - chessops's own parser
+    // silently drops it rather than rejecting the FEN (see parseCastlingFen
+    // in fen.js), so that has to be checked here by comparing what was
+    // requested against what the constructed position actually granted.
+    // This works the same way for Standard 'KQkq' and Chess960 file-letter
+    // rights, since both are resolved by chessops before this comparison;
+    // no Standard-only assumption is made about which squares are valid.
+    function _missingCastlingRights(setup, pos) {
+        const missing = [];
+        for (const square of setup.castlingRights) {
+            if (!pos.castles.castlingRights.has(square)) missing.push(makeSquare(square));
+        }
+        return missing;
+    }
+
+    // Standard chess's castling letters mean something fixed: 'K'/'Q' is
+    // the White rook on h1/a1, with the White king on e1 - never "whichever
+    // rook is right/left of the king" (chessops's own, Chess960-capable,
+    // resolution rule; see the module doc comment). A right that chessops
+    // resolves to any other square is a Chess960-only reading of the same
+    // letter and must be rejected here, in Standard mode, even though
+    // chessops itself parsed it without complaint. Chess960 mode has no
+    // "home square" of its own - any resolved king/rook pair is
+    // acceptable there, which _missingCastlingRights above already covers.
+    const _HOME_SQUARES = {
+        white: { king: parseSquare('e1'), rook: { a: parseSquare('a1'), h: parseSquare('h1') } },
+        black: { king: parseSquare('e8'), rook: { a: parseSquare('a8'), h: parseSquare('h8') } },
+    };
+    function _nonOrthodoxCastlingRights(pos) {
+        const offending = [];
+        for (const color of ['white', 'black']) {
+            const kingSquare = pos.board.kingOf(color);
+            for (const side of ['a', 'h']) {
+                const rookSquare = pos.castles.rook[color][side];
+                if (rookSquare === undefined) continue;
+                if (kingSquare !== _HOME_SQUARES[color].king || rookSquare !== _HOME_SQUARES[color].rook[side]) {
+                    offending.push(makeSquare(rookSquare));
+                }
+            }
+        }
+        return offending;
+    }
+
+    // Standard mode accepts only 'K'/'Q'/'k'/'q' (each optional, in that
+    // order) or '-'; Chess960 additionally accepts Shredder-FEN/X-FEN
+    // rook-file letters. Mirrors app.py's _validate_fen_parts exactly:
+    // same accepted grammar, same rejected input, so a FEN the frontend
+    // accepts is never one the backend then rejects, or vice versa.
+    const _CASTLING_SYNTAX_STANDARD = /^K?Q?k?q?$/;
+    const _CASTLING_SYNTAX_CHESS960 = /^[A-Ha-hKQkq]{1,4}$/;
+    function _castlingSyntaxError(variant, field) {
+        if (field === '-') return null;
+        const pattern = variant === VARIANTS.CHESS960 ? _CASTLING_SYNTAX_CHESS960 : _CASTLING_SYNTAX_STANDARD;
+        if (pattern.test(field)) return null;
+        const expected = variant === VARIANTS.CHESS960
+            ? "some combination of 'K', 'Q', 'k', 'q', rook-file letters 'a'-'h'/'A'-'H', or '-'"
+            : "some combination of 'K', 'Q', 'k', 'q', or '-'";
+        return `Invalid castling availability: '${field}' (expected ${expected}).`;
+    }
+
+    // Parses and fully validates a FEN into a chessops position under the
+    // given variant (defaulting to the currently-active one), or returns a
+    // user-facing reason it was rejected. Rejects a syntactically-valid
+    // chessops parse that isn't actually a legal encoding for the
+    // requested variant (see the two checks above and the module doc
+    // comment) - the same FEN text can be accepted under one variant and
+    // rejected under the other.
+    function _buildPosition(fen, variant = _variant) {
+        const fields = fen.split(' ');
+        if (fields.length >= 3) {
+            const syntaxError = _castlingSyntaxError(variant, fields[2]);
+            if (syntaxError) return { ok: false, reason: syntaxError };
+        }
+        const parsed = parseFen(fen);
+        if (parsed.isErr) return { ok: false, reason: _fenErrorMessage(parsed.error) };
+        const setup = parsed.value;
+        const built = Chess.fromSetup(setup);
+        if (built.isErr) return { ok: false, reason: _positionErrorMessage(built.error) };
+        const pos = built.value;
+        const missing = _missingCastlingRights(setup, pos);
+        if (missing.length) {
+            return { ok: false, reason: `Invalid castling availability: no matching king and rook for ${missing.join(', ')}.` };
+        }
+        if (variant !== VARIANTS.CHESS960) {
+            const nonOrthodox = _nonOrthodoxCastlingRights(pos);
+            if (nonOrthodox.length) {
+                return {
+                    ok: false,
+                    reason: `Invalid castling availability: Standard chess requires the king and rook on their home squares (${nonOrthodox.join(', ')} is not one).`,
+                };
+            }
+        }
+        return { ok: true, pos };
+    }
+
+    function _pieceCodeOf(piece) {
+        if (!piece) return null;
+        const letter = piece.role === 'knight' ? 'N' : piece.role[0].toUpperCase();
+        return (piece.color === 'white' ? 'w' : 'b') + letter;
+    }
+
+    // Total legal move count, counting each underpromotion choice as a
+    // separate move (matching the count a full legal-move generator would
+    // report) rather than one destination square per promoting pawn move.
+    // Includes Chess960 castling moves - they're just another destination
+    // chessops's own move generation supplies (see chessgroundDests below).
+    function _countLegalMoves(pos) {
+        const ctx = pos.ctx();
+        let count = 0;
+        for (const [from, squares] of pos.allDests(ctx)) {
+            const promotes = pos.board.pawn.has(from);
+            for (const to of squares) {
+                const isPromotion = promotes && (to < 8 || to >= 56);
+                count += isPromotion ? 4 : 1;
+            }
+        }
+        return count;
+    }
+
+    // Builds chessground's `movable.dests` shape from the active position,
+    // using the variant-aware compatibility bridge. Standard mode exposes
+    // orthodox king-destination castling only; Chess960 exposes the
+    // king-to-rook destination.
+    function _legalDestsMap() {
+        if (!_position) return new Map();
+        const dests = chessgroundDests(_position, { chess960: _variant === VARIANTS.CHESS960 });
+        if (_variant === VARIANTS.CHESS960) return dests;
+
+        const filtered = new Map();
+        for (const [from, squares] of dests) {
+            const fromSquare = parseSquare(from);
+            const allowed = squares.filter(to => {
+                const toSquare = parseSquare(to);
+                const side = castlingSide(_position, { from: fromSquare, to: toSquare });
+                if (!side) return true;
+                return toSquare !== _position.castles.rook[_position.turn][side];
+            });
+            if (allowed.length) filtered.set(from, allowed);
+        }
+        return filtered;
+    }
+
+    // ── Chessground sync ──────────────────────────────────────────────────────
+    // The single point where _position's state is pushed into chessground.
+    // Called unconditionally after every position-changing action - even a
+    // "legal move" one, since chessground's own baseMove() has no concept of
+    // en passant, promotion, or Chess960 castling and can leave its internal
+    // state briefly chess-wise-incorrect (e.g. not removing the captured
+    // pawn on an en passant capture, leaving a pawn on the back rank instead
+    // of the promoted piece, or leaving the rook wherever it was dragged
+    // from instead of its final castled square) until this call corrects
+    // it. Chessground's internal state is not authoritative;
+    // this call always overwrites it from _position.
+    function _syncChessground() {
+        if (!cg || !_position) return;
+        cg.set({
+            fen:       currentFen(),
+            turnColor: _position.turn,
+            check:     _position.isCheck() ? _position.turn : false,
+            lastMove:  _lastMoveKeys,
+            // Locked: restrict dragging/click-move to the side to move's
+            // legal destinations. Unlocked: free editing.
+            movable: {
+                free:  !_locked,
+                color: _locked ? _position.turn : 'both',
+                dests: _locked ? _legalDestsMap() : undefined,
+            },
+            // Off-board drop-to-delete is disabled while locked, same as the
+            // spare trays below.
+            draggable: { deleteOnDropOff: !_locked },
+        });
+    }
+
+    // ── Promotion ─────────────────────────────────────────────────────────────
+    // pieceCode is a two-letter code like 'wP' (colour + uppercase type),
+    // matching the shape the rest of this file (and theme.js) already uses.
+    function _isPromotionMove(target, pieceCode) {
+        if (!pieceCode || pieceCode[1] !== 'P') return false;
+        const color = pieceCode[0], rank = target[1];
+        return (color === 'w' && rank === '8') || (color === 'b' && rank === '1');
+    }
+    // Maps the promotion dialog's single-letter piece codes to chessops's
+    // full role names.
+    const ROLE_OF = { P: 'pawn', N: 'knight', B: 'bishop', R: 'rook', Q: 'queen', K: 'king' };
+
+    function _showPromotionDialog(source, target, color) {
+        _pendingPromotion = { source, target };
+        const dialog = document.getElementById('promotion-dialog');
+        ['q','r','b','n'].forEach(p => {
+            const btn = dialog.querySelector(`.promotion-piece-btn[data-piece="${p}"]`);
+            const img = btn && btn.querySelector('img');
+            if (img) img.src = _pieceTheme(color + p.toUpperCase());
+        });
+        dialog.classList.add('is-visible');
+        dialog.querySelector('.promotion-piece-btn')?.focus();
+    }
+    function _hidePromotionDialog() {
+        document.getElementById('promotion-dialog').classList.remove('is-visible');
+    }
+    // Cancelling (Escape / backdrop click) needs to resync, since
+    // chessground has already visually relocated the pawn to the target
+    // square by the time the dialog is showing (its own drag/drop already
+    // moved the piece before this handler ever runs). This call reverts
+    // that visual relocation by pushing _position's still-unchanged state
+    // back into chessground.
+    function _cancelPromotion() {
+        _hidePromotionDialog();
+        _pendingPromotion = null;
+        _syncChessground();
+    }
+    function _onPromotionSelect(pieceLetter) {
+        _hidePromotionDialog();
+        if (!_pendingPromotion) return;
+        const { source, target } = _pendingPromotion;
+        _pendingPromotion = null;
+        const move = { from: parseSquare(source), to: parseSquare(target), promotion: ROLE_OF[pieceLetter.toUpperCase()] };
+        if (!_position.isLegal(move)) { _syncChessground(); return; }   // revert the visual pawn-on-back-rank relocation
+        const san = makeSan(_position, move);
+        _position.play(move);
+        _lastMoveKeys = [source, target];
+        _addMove(san, currentFen(), source, target);
+        _emitHistory();
+        _syncChessground();
+        // immediate=true: a completed promotion is a single, definite move
+        // (see playMove()'s own comment on this parameter), not part of a
+        // rapid-fire stream of changes the debounce below it is meant to
+        // guard against.
+        if (_onPositionChange) _onPositionChange(currentFen(), true);
+    }
+
+    // ── Core sync algorithm ──────────────────────────────────────────────────
+    // Chessground fires multiple, differently-scoped callbacks for what a
+    // user experiences as a single action (events.move, events.change,
+    // movable.events.after, events.dropNewPiece), so rather than track
+    // which-callback-handled-what with suppression flags, this handler is
+    // idempotent: it compares chessground's current placement against
+    // _position's, and no-ops if they already match.
+    //
+    // events.move is wired as the informative hook (the one that passes
+    // origHint/destHint below) rather than movable.events.after, because of
+    // chessground's event-firing order for an ordinary relocation:
+    // events.move fires first (scheduled from within board.ts's baseMove()),
+    // then events.change (also scheduled by baseMove(), immediately after),
+    // then movable.events.after (scheduled later by userMove()) - all via
+    // setTimeout(fn,1), so same-delay-timer FIFO ordering makes this
+    // deterministic. events.change carries no orig/dest, so if it were the
+    // informative hook it would always take the generic "board edit" branch
+    // below first, leaving movable.events.after's real orig/dest with
+    // nothing left to act on once it fires - the idempotency guard would
+    // already see the position as synced. events.move fires before
+    // events.change and, unlike movable.events.after, carries orig/dest
+    // (plus capture info), so it reliably wins the idempotency race with
+    // enough information to classify the move correctly.
+    // events.change and movable.events.after are wired below as idempotent
+    // fallbacks/no-ops for a relocation; events.change is load-bearing for
+    // the one case with no orig/dest-carrying hook at all - an off-board
+    // deletion (drag.ts's deleteOnDropOff branch).
+    //
+    // Standard mode accepts only the orthodox king-destination castle;
+    // Chess960 accepts the king-to-rook representation.
+    function _handleBoardMutation(origHint, destHint) {
+        if (!cg || !_position) return;
+        const cgPlacement  = cg.getFen();                 // chessground's own current placement-only FEN
+        const ourPlacement = currentFen().split(' ')[0];
+        if (cgPlacement === ourPlacement) return;          // already synced by another callback this tick
+
+        if (origHint && destHint) {
+            // _position hasn't moved yet at this point - only chessground
+            // has - so the piece that was at origHint is still readable
+            // from _position.
+            const pieceCode = _pieceCodeOf(_position.board.get(parseSquare(origHint)));
+            if (pieceCode && _isPromotionMove(destHint, pieceCode)) {
+                _showPromotionDialog(origHint, destHint, pieceCode[0]);
+                return;   // resolved later by _onPromotionSelect()/_cancelPromotion()
+            }
+            const move = { from: parseSquare(origHint), to: parseSquare(destHint) };
+            if (_variant === VARIANTS.STANDARD) {
+                const side = castlingSide(_position, move);
+                if (side && move.to === _position.castles.rook[_position.turn][side]) {
+                    _syncChessground();
+                    return;
+                }
+            }
+            if (_position.isLegal(move)) {
+                const san = makeSan(_position, move);
+                _position.play(move);
+                _lastMoveKeys = [origHint, destHint];
+                _addMove(san, currentFen(), origHint, destHint);
+                _emitHistory();
+                _syncChessground();
+                // immediate=true: see the comment on the equivalent call in
+                // _onPromotionSelect() above - a completed drag-and-drop
+                // move is a single, definite move too.
+                if (_onPositionChange) _onPositionChange(currentFen(), true);
+                return;
+            }
+            // Not legal - fall through to the generic edit path below, which
+            // reads the placement chessground already committed rather than
+            // origHint/destHint.
+        }
+
+        // Board-edit path: spare-piece drop, off-board delete, or an
+        // illegal relocation. Castling rights and the en passant square are
+        // always dropped here because an edited placement's rights can no
+        // longer be assumed valid.
+        const prevFen = currentFen();
+        const nextFen = `${cgPlacement} ${_turnChar(_position)} - - 0 1`;
+        const built = _buildPosition(nextFen);
+        if (!built.ok) { _syncChessground(); return; }   // invalid resulting position - snap back
+        _position = built.pos;
+        _pushHistory(prevFen);
+        _lastMoveKeys = undefined;
+        _resetMoveLine();
+        _syncChessground();
+        if (_onPositionChange) _onPositionChange(currentFen());
+    }
+
+    function _onCgSelect(key) {
+        if (!_clickPlacePiece) return;         // not in placement mode - let chessground handle the click normally
+        cg.selectSquare(null);                  // clear any selection chessground itself may have started,
+                                                 // so a piece "armed" for placement never gets relocated
+                                                 // by chessground's own click-to-move instead
+        const role  = ROLE_OF[_clickPlacePiece[1]];
+        const color = _clickPlacePiece[0] === 'w' ? 'white' : 'black';
+        const square = parseSquare(key);
+        if (role === 'king') {
+            const existing = _position.board.kingOf(color);
+            if (existing !== undefined && existing !== square) return;   // rejected - a king of this colour already exists elsewhere
+        }
+        const prevFen = currentFen();
+        // Trial-mutate a clone rather than _position directly, so an
+        // illegal result (e.g. two kings adjacent, or leaving the side not
+        // to move in check) can be refused before anything commits - the
+        // same validate-then-commit gate _handleBoardMutation's edit path
+        // below already runs every other board edit through.
+        const trial = _position.clone();
+        trial.board.set(square, { role, color, promoted: false });
+        // Re-derive castling rights from the edited board rather than
+        // leaving stale rook/king square references behind (e.g. a right
+        // pointing at a square this edit just overwrote).
+        trial.castles = Castles.fromSetup({ board: trial.board, castlingRights: _position.castles.castlingRights });
+        const nextFen = makeFen(trial.toSetup());
+        if (nextFen === prevFen) return;   // identity placement (e.g. re-placing the same piece already there) - nothing to record
+        const built = _buildPosition(nextFen);
+        if (!built.ok) { setClickPlacePiece(null); return; }   // illegal result - refuse, board stays as it was
+        _position = built.pos;
+        _pushHistory(prevFen);
+        _lastMoveKeys = undefined;
+        _resetMoveLine();
+        _syncChessground();
+        if (_onPositionChange) _onPositionChange(currentFen());
+    }
+
+    // ── Best-move arrows (DTZ / DTC / DTM / DTM50) ────────────────────────────
+    // Native chessground feature (drawable.autoShapes) - square keys, not
+    // pixel coordinates, so chessground handles orientation/resizing itself.
+    // bestMoves: { dtz: entry|null, dtc: entry|null, dtm: entry|null,
+    // dtm50: entry|null } - the top-ranked move for each metric (any of
+    // which may be missing, e.g. for a terminal or not-yet-probed position).
+    function drawArrows(bestMoves) {
+        if (!cg) return;
+        if (!bestMoves) { cg.setAutoShapes([]); return; }
+        const shapes = [];
+        ['dtz', 'dtc', 'dtm', 'dtm50'].forEach(metric => {
+            const entry = bestMoves[metric];
+            if (!entry) return;
+            const move = parseSan(_position, entry.san);
+            if (!move) return;
+            const side = _variant === VARIANTS.STANDARD ? castlingSide(_position, move) : undefined;
+            const dest = side
+                ? `${side === 'a' ? 'c' : 'g'}${_position.turn === 'white' ? '1' : '8'}`
+                : makeSquare(move.to);
+            shapes.push({ orig: makeSquare(move.from), dest, brush: metric });
+        });
+        cg.setAutoShapes(shapes);
+    }
+    function clearArrows() {
+        if (!cg) return;
+        cg.setAutoShapes([]);
+    }
+
+    // ��─ Click-to-place + spare-piece trays ───────────────────────────────────
+    let _clickPlacePiece = null;   // e.g. 'wQ', 'bK', or null
+
+    function _toCgPiece(code /* e.g. 'wQ' */) {
+        return { color: code[0] === 'w' ? 'white' : 'black', role: ROLE_OF[code[1]] };
+    }
+
+    function _populateTrayImages() {
+        document.querySelectorAll('.spare-piece').forEach(btn => {
+            const code = btn.dataset.piece;
+            const img  = btn.querySelector('img');
+            if (img && code) img.src = _pieceTheme(code);
+        });
+    }
+
+    // Two interaction paths, both needed: click-to-place (click a tray
+    // piece, then click a destination square) and drag-from-tray (native
+    // HTML5 drag onto the board, handled via chessground's dragNewPiece()).
+    // The spare-piece trays are expected to support both at once, so
+    // neither wiring below can assume the other is absent.
+    function _initSpareTrays() {
+        document.querySelectorAll('.spare-piece').forEach(btn => {
+            const code = btn.dataset.piece;
+
+            // Path 1: click tray piece, then click a square - handled by
+            // this click listener (arms _clickPlacePiece) plus _onCgSelect()
+            // (does the actual placement), wired in init()'s Config.events.select.
+            // Disabled while locked (tray is also dimmed - see setLocked()).
+            btn.addEventListener('click', () => {
+                if (_locked) return;
+                setClickPlacePiece(_clickPlacePiece === code ? null : code);
+            });
+
+            // Path 2: drag a tray piece directly onto the board. `force:
+            // true` is required - cg.dragNewPiece() without it refuses to
+            // overwrite an occupied square, and dropping a spare piece onto
+            // an occupied square is expected to replace it. Disabled while locked.
+            btn.addEventListener('pointerdown', e => {
+                if (_locked) return;
+                if (e.button !== undefined && e.button !== 0) return;   // primary pointer only
+                cg.dragNewPiece(_toCgPiece(code), e, /* force */ true);
+            });
+        });
+
+        // Escape clears click-to-place selection
+        document.addEventListener('keydown', e => {
+            if (e.key === 'Escape' && _clickPlacePiece) setClickPlacePiece(null);
+        });
+    }
+
+    function setClickPlacePiece(piece) {
+        _clickPlacePiece = piece;
+        // Visual feedback
+        document.querySelectorAll('.spare-piece.cp-selected').forEach(el => el.classList.remove('cp-selected'));
+        if (piece) {
+            document.querySelectorAll(`.spare-piece[data-piece="${piece}"]`).forEach(el => el.classList.add('cp-selected'));
+        }
+        // Update cursor on board
+        const boardEl = document.getElementById('board');
+        if (boardEl) {
+            boardEl.classList.toggle('cp-active', !!piece);
+        }
+    }
+
+    // ── Public API ────────────────────────────────────────────────────────────
+
+    function _restoredOrientation() {
+        return Storage.read('chesstb_orientation') === 'black' ? 'black' : 'white';
+    }
+
+    function _restoredLocked() {
+        return Storage.read('chesstb_locked') === 'true';
+    }
+
+    // variant, if given, must be VARIANTS.STANDARD or VARIANTS.CHESS960 and
+    // takes precedence over any caller-independent default - callers that
+    // already know the intended variant (a URL share-link, a restored saved
+    // game) pass it explicitly so the position below is constructed under
+    // the correct ruleset context from the very first render, per this
+    // file's variant-before-position invariant. Omitted or invalid values
+    // fall back to Standard.
+    function init(onPositionChange, initialFen, variant) {
+        _onPositionChange = onPositionChange;
+        _variant = (variant === VARIANTS.CHESS960) ? VARIANTS.CHESS960 : VARIANTS.STANDARD;
+
+        // Same validation setPosition() applies to every later position
+        // change - an invalid initialFen (bad king count, unusable castling
+        // rights, or anything else chessops rejects) falls back to the
+        // default reset position, and the reason is returned below so the
+        // caller can tell the user, instead of silently substituting a
+        // different position with no feedback.
+        const built = _buildPosition(initialFen);
+        let loadError = null;
+        if (built.ok) {
+            _position = built.pos;
+        } else {
+            loadError = built.reason;
+            _position = Chess.default();
+        }
+        _startFen = currentFen();
+
+        // Built from _startFen (the validated/fallback position), not the
+        // raw initialFen - otherwise an invalid initialFen leaves the
+        // visible board showing the rejected placement while _position
+        // already holds the fallback, a desync baked in right at startup.
+        cg = Chessground(document.getElementById('board'), {
+            fen:                  _startFen,
+            orientation:          _restoredOrientation(),
+            turnColor:            _position.turn,
+            check:                _position.isCheck() ? _position.turn : false,
+            lastMove:             undefined,
+            coordinates:          true,
+            // coordinatesOnSquares stays false: that mode prints a combined
+            // "a8"-style label on all 64 squares, whereas this app wants the
+            // classic look - a rank number down the left column and a file
+            // letter along the bottom row only, both sitting inset at the
+            // board's edges. Chessground's native coords.ranks/coords.files
+            // strips (one rank-only label per row, one file-only label per
+            // column) already produce that layout once repositioned via CSS
+            // (see chess/board.css) to sit inside the board edge instead of outside
+            // it, so the combined per-square mode isn't needed here.
+            coordinatesOnSquares: false,
+            // Castling is driven by the chessops position (_position), not
+            // chessground's own king-two-squares heuristic, so chessground
+            // should never second-guess or auto-correct a king move into a
+            // castle itself - this also holds for Chess960's king-to-rook
+            // representation, which chessground has no native concept of.
+            autoCastle:           false,
+            viewOnly:             false,
+            disableContextMenu:   true,
+            highlight:            { lastMove: true, check: true },
+            animation:            { enabled: true, duration: 200 },
+            movable: {
+                // Any drag is provisionally accepted here and classified
+                // afterward by _handleBoardMutation, rather than gating
+                // drags up front with a separate edit-mode toggle.
+                free:  true,
+                color: 'both',
+                showDests: true,
+                events: { after: (orig, dest) => _handleBoardMutation(orig, dest) },
+            },
+            premovable:  { enabled: false },
+            draggable: {
+                enabled:         true,
+                showGhost:       true,
+                deleteOnDropOff: true,
+            },
+            selectable: { enabled: true },
+            events: {
+                move:         (orig, dest) => _handleBoardMutation(orig, dest),
+                change:       () => _handleBoardMutation(),
+                dropNewPiece: () => _handleBoardMutation(),
+                select:       (key) => _onCgSelect(key),
+            },
+            drawable: {
+                enabled: true,
+                visible: true,
+                brushes: {
+                    dtz:   { key: 'dtz',   color: '#2451c4', opacity: 0.80, lineWidth: 10 },
+                    dtc:   { key: 'dtc',   color: '#d113c6', opacity: 0.80, lineWidth: 10 },
+                    dtm:   { key: 'dtm',   color: '#8b93a1', opacity: 0.80, lineWidth: 10 },
+                    dtm50: { key: 'dtm50', color: '#e1453a', opacity: 0.80, lineWidth: 10 },
+                },
+            },
+        });
+
+        const dialog = document.getElementById('promotion-dialog');
+        dialog.querySelectorAll('.promotion-piece-btn').forEach(btn => {
+            btn.addEventListener('click', () => _onPromotionSelect(btn.dataset.piece));
+        });
+        dialog.addEventListener('click', e => {
+            if (e.target === dialog) _cancelPromotion();
+        });
+        document.addEventListener('keydown', e => {
+            if (e.key !== 'Escape' || !dialog.classList.contains('is-visible')) return;
+            _cancelPromotion();
+            // The promotion dialog sits on top of everything else - stop
+            // this Escape from also reaching the PGN dialog/settings-panel
+            // handlers (see PgnDialog.jsx, SettingsPanel.jsx), which would otherwise close those too
+            // if either happened to be open underneath it.
+            e.stopImmediatePropagation();
+        });
+
+        _populateTrayImages();
+        _initSpareTrays();
+        _syncTrayOrientation();
+
+        // Restored the same way orientation is above - persist:false since
+        // this is a stored preference being applied on load, not a new one
+        // being set, so it's not written straight back to the same key.
+        setLocked(_restoredLocked(), false);
+
+        return loadError ? { ok: false, reason: loadError } : { ok: true };
+    }
+
+    /**
+     * Set the piece-set CSS <link> and populate the spare-tray and
+     * promotion-dialog images. Registered with theme.js via
+     * Theme.init(reconstruct) and invoked once at bootstrap, after theme.js
+     * injects the board's theme <style> tag.
+     *
+     * This never touches the Chessground instance itself - piece images are
+     * plain CSS (`.cg-wrap piece.<role>.<color>`), not baked into a
+     * constructor closure.
+     */
+    function reconstruct() {
+        if (!cg || !_position) return;
+        const link = document.getElementById('chesstb-piece-css');
+        if (link) link.href = `/static/css/pieces-${Theme.currentPieceSet()}.css`;
+        _populateTrayImages();
+    }
+
+    function setPosition(fen) {
+        const prevFen = _position ? currentFen() : null;
+        // Re-submitting the FEN already on the board (e.g. pressing Enter in
+        // the FEN box without editing it) is a no-op - skip the undo-stack
+        // push and tree reset so the current move line survives it.
+        if (fen === prevFen) return { ok: true };
+        const built = _buildPosition(fen);
+        if (!built.ok) return { ok: false, reason: built.reason };
+        _position = built.pos;
+        if (prevFen !== null) _pushHistory(prevFen);
+        _hidePromotionDialog();
+        _pendingPromotion = null;
+        _lastMoveKeys = undefined;
+        _resetMoveLine();
+        _syncChessground();
+        // Position-change callback, as in playMove()/goBack()/goForward()/
+        // goToNode()/clear().
+        const nextFen = currentFen();
+        if (_onPositionChange) _onPositionChange(nextFen);
+        return { ok: true };
+    }
+
+    // Sets a new FEN and variant together in a single step - for a caller
+    // that is replacing the position anyway (a shared URL, PGN import,
+    // restoreTree()'s fallback path), so there is no "current position"
+    // to preserve or validate against the new variant; the new FEN is
+    // validated directly against the new variant instead (see
+    // _buildPosition). Use setVariant() instead when the FEN is meant to
+    // stay exactly as it is and only its interpretation should change
+    // (e.g. the settings-panel toggle).
+    function setPositionAndVariant(fen, variant) {
+        const next = (variant === VARIANTS.CHESS960) ? VARIANTS.CHESS960 : VARIANTS.STANDARD;
+        const prevFen = _position ? currentFen() : null;
+        if (fen === prevFen && next === _variant) return { ok: true };   // true no-op
+        const built = _buildPosition(fen, next);
+        if (!built.ok) return { ok: false, reason: built.reason };
+        _variant = next;
+        _position = built.pos;
+        if (prevFen !== null) _pushHistory(prevFen);
+        _hidePromotionDialog();
+        _pendingPromotion = null;
+        _lastMoveKeys = undefined;
+        _resetMoveLine();
+        _syncChessground();
+        if (_onPositionChange) _onPositionChange(currentFen());
+        return { ok: true };
+    }
+
+    function clear() {
+        const prevFen  = currentFen();
+        const resetFen = '4k3/8/8/8/8/8/8/4K3 w - - 0 1';
+        const built = _buildPosition(resetFen);
+        console.assert(built.ok, 'clear(): resetFen must always be valid');
+        _pushHistory(prevFen);
+        _position = built.pos;
+        _hidePromotionDialog();
+        _pendingPromotion = null;
+        _lastMoveKeys = undefined;
+        _resetMoveLine();
+        _syncChessground();
+        if (_onPositionChange) _onPositionChange(resetFen);
+        return resetFen;
+    }
+
+    // Mirrors chessground's own orientation as a class on #board-wrap-inner;
+    // chess/board.css uses it to flip flex-direction so the spare-piece trays swap
+    // sides visually without moving them in the DOM.
+    function _syncTrayOrientation() {
+        const wrapEl = document.getElementById('board-wrap-inner');
+        if (wrapEl) wrapEl.classList.toggle('orientation-black', cg.state.orientation === 'black');
+    }
+
+    function flip() {
+        cg.toggleOrientation();
+        _syncTrayOrientation();
+        Storage.write('chesstb_orientation', cg.state.orientation);
+        clearArrows();   // arrows are orientation-dependent; caller (useExplorer.js) redraws right after flip
+    }
+
+    // ── Lock mode (public) ───────────────────────────────────────────────────
+    // Toggles legal-moves-only board interaction. Persisted to localStorage
+    // the same way orientation is (see flip()) when persist defaults to
+    // true; callers applying an already-known value (init() restoring on
+    // load, or useExplorer.js's auto-play engaging/releasing Lock) pass persist:false.
+    function setLocked(locked, persist = true) {
+        _locked = !!locked;
+        if (_locked) setClickPlacePiece(null);   // drop any armed spare piece
+        document.querySelectorAll('.spare-tray').forEach(el => {
+            el.classList.toggle('is-locked', _locked);
+            if (_locked) el.setAttribute('title', 'Board is locked');
+            else el.removeAttribute('title');
+        });
+        if (persist) Storage.write('chesstb_locked', _locked);
+        _syncChessground();
+    }
+    function isLocked() { return _locked; }
+
+    // ── Variant (public) ─────────────────────────��───────────────────────────
+    // Persistence and toggle-panel wiring live in useExplorer.js and
+    // SettingsPanel.jsx (Chess960 Mode is a Settings-panel item, alongside
+    // Autoplay Delay and Show Root Row) - this module only holds the
+    // current value and reacts to it changing.
+    function setVariant(variant) {
+        const next = (variant === VARIANTS.CHESS960) ? VARIANTS.CHESS960 : VARIANTS.STANDARD;
+        if (next === _variant) return { ok: true };
+        // This reinterprets the current position under a different
+        // variant - the FEN itself is not changing (see
+        // setPositionAndVariant() above for the "also loading a new
+        // position" case) - so unlike every other _buildPosition() call in
+        // this file, failure here must not fall back to a default
+        // position or otherwise change what's on the board: the position
+        // simply isn't representable under the requested variant's
+        // castling rules (e.g. Chess960-only castling rights present, or
+        // Chess960 castling rights on non-home squares - see
+        // _nonOrthodoxCastlingRights), and the switch is refused outright,
+        // leaving variant and position exactly as they were.
+        if (_position) {
+            const trial = _buildPosition(currentFen(), next);
+            if (!trial.ok) {
+                const modeName = next === VARIANTS.CHESS960 ? 'Chess960' : 'Standard';
+                return { ok: false, reason: `Can't switch to ${modeName} mode: ${trial.reason}` };
+            }
+        }
+        _variant = next;
+        // The move tree belongs to the active variant; changing variants
+        // starts a fresh tree from the current position.
+        _lastMoveKeys = undefined;
+        _resetMoveLine();
+        _syncChessground();
+        // Position change with no actual FEN change - still routed through
+        // onPositionChange so callers re-probe under the new variant and
+        // (via onPositionChange's own guard) auto-play is stopped rather
+        // than left running against a variant it started under.
+        if (_onPositionChange) _onPositionChange(currentFen());
+        return { ok: true };
+    }
+    function getVariant()  { return _variant; }
+    function isChess960()  { return _variant === VARIANTS.CHESS960; }
+
+    // Legal move count for the current position, counting each
+    // underpromotion choice separately (see _countLegalMoves above) and
+    // including Chess960 castling.
+    function legalMoveCount() { return _position ? _countLegalMoves(_position) : 0; }
+    function isInsufficientMaterial() { return !!_position && _position.isInsufficientMaterial(); }
+
+    // Result token for an arbitrary FEN, independent of the live board
+    // state - used by pgnFormat.js's PGN-result detection. Returns '*'
+    // (unknown/in progress) for a FEN that fails to parse.
+    function outcomeFromFen(fen) {
+        const built = _buildPosition(fen);
+        if (!built.ok) return '*';
+        const pos = built.pos;
+        if (pos.isCheckmate()) return pos.turn === 'white' ? '0-1' : '1-0';
+        if (pos.isStalemate() || pos.isInsufficientMaterial()) return '1/2-1/2';
+        return '*';
+    }
+
+    function playMove(san) {
+        if (!_position) return false;
+        const move = parseSan(_position, san);
+        if (!move) return false;
+        const fromKey = makeSquare(move.from), toKey = makeSquare(move.to);
+        const playedSan = makeSan(_position, move);
+        _position.play(move);
+
+        _lastMoveKeys = [fromKey, toKey];
+
+        // Track in the move tree (branches instead of overwriting if the
+        // user had navigated back before playing this move).
+        _addMove(playedSan, currentFen(), fromKey, toKey);
+        _emitHistory();
+        _syncChessground();
+
+        // immediate=true: this is a single, definite move (played by
+        // auto-play or by clicking a move in the ranked-moves table, the
+        // two callers of playMove() - see useExplorer.js), not part of a
+        // rapid-fire stream of changes the 300ms debounce guards against.
+        if (_onPositionChange) _onPositionChange(currentFen(), true);
+        return true;
+    }
+
+    // Back/Forward walk the move tree directly (parent / activeChild) so
+    // stepping through a line that includes variations works the same as
+    // stepping through the main line. The plain _history/_future FEN stack
+    // is only consulted once navigation reaches the tree's root (id ROOT)
+    // and goes further back than the tree itself - i.e. undoing past
+    // whatever move/edit started the current tree (see _resetMoveLine).
+    function goBack() {
+        if (_currentId !== ROOT) {
+            const parentId = _nodes[_currentId].parentId;
+            const fen = parentId === ROOT ? _startFen : _nodes[parentId].fen;
+            const built = _buildPosition(fen);
+            if (!built.ok) { _syncChessground(); return false; }
+            _position = built.pos;
+            _lastMoveKeys = parentId === ROOT ? undefined : [_nodes[parentId].from, _nodes[parentId].to];
+            _currentId = parentId;
+        } else {
+            if (_history.length === 0) return false;
+            const prevFen = _history.pop();
+            _future.push(currentFen());
+            const built = _buildPosition(prevFen);
+            if (!built.ok) {
+                _future.pop();
+                _history.push(prevFen);
+                _syncChessground();
+                return false;
+            }
+            _position = built.pos;
+            // The plain _history/_future stack holds FENs only, with no
+            // accompanying from/to squares (unlike tree nodes), so there's
+            // nothing to highlight as the last move here.
+            _lastMoveKeys = undefined;
+            // The loaded position does not match the tree's _startFen, so
+            // the tree is reset. _resetMoveLine() also clears _future, so the
+            // stack is saved and restored around the reset.
+            const _pendingFuture = _future.slice();
+            _resetMoveLine();
+            _future = _pendingFuture;
+        }
+        _hidePromotionDialog();
+        _pendingPromotion = null;
+        _syncChessground();
+        _emitHistory();
+        if (_onPositionChange) _onPositionChange(currentFen());
+        return true;
+    }
+
+    function goForward() {
+        const activeChildId = _activeChildOf(_currentId);
+        if (activeChildId !== null && activeChildId !== undefined) {
+            const node = _nodes[activeChildId];
+            const built = _buildPosition(node.fen);
+            if (!built.ok) { _syncChessground(); return false; }
+            _position = built.pos;
+            _lastMoveKeys = [node.from, node.to];
+            _currentId = activeChildId;
+        } else if (_currentId === ROOT && _future.length > 0) {
+            const nextFen = _future.pop();
+            const built = _buildPosition(nextFen);
+            if (!built.ok) {
+                _future.push(nextFen);
+                _syncChessground();
+                return false;
+            }
+            _history.push(currentFen());
+            _position = built.pos;
+            _lastMoveKeys = undefined;
+            // Mirrors the goBack() fallback above: the position just loaded
+            // isn't described by the current (already-reset) tree either, so
+            // restart the tree here too and preserve any remaining redo
+            // entries across the reset.
+            const _pendingFuture = _future.slice();
+            _resetMoveLine();
+            _future = _pendingFuture;
+        } else {
+            return false;
+        }
+        _hidePromotionDialog();
+        _pendingPromotion = null;
+        _syncChessground();
+        _emitHistory();
+        if (_onPositionChange) _onPositionChange(currentFen());
+        return true;
+    }
+
+    // goToNode() jumps to an arbitrary node in the current move tree (used
+    // by the PGN panel - including variation moves, not just the main line).
+    // Unlike setPosition(), this never calls _resetMoveLine(). targetId ===
+    // ROOT (-1) means "start of the tree" (the position before any move was
+    // played). Clicking any node marks it - and every ancestor on the path
+    // to it - as its parent's activeChild, so Forward continues along
+    // whichever branch was just brought into view.
+    function goToNode(targetId) {
+        if (targetId !== ROOT && !_nodes[targetId]) return false;
+        if (targetId === _currentId) return true;
+
+        // Walked before touching _position/_syncChessground, and bounded to
+        // at most one hop per node, so a corrupt parentId chain (see
+        // _isValidTree) refuses the jump instead of looping forever.
+        const chain = [];
+        let walk  = targetId;
+        let guard = _nodes.length + 1;
+        while (walk !== ROOT) {
+            if (guard-- <= 0 || !_nodes[walk]) return false;
+            chain.unshift(walk);
+            walk = _nodes[walk].parentId;
+        }
+
+        const fen = targetId === ROOT ? _startFen : _nodes[targetId].fen;
+        const built = _buildPosition(fen);
+        if (!built.ok) return false;
+        _position = built.pos;
+
+        let parent = ROOT;
+        chain.forEach(id => { _setActiveChild(parent, id); parent = id; });
+        _currentId = targetId;
+        _lastMoveKeys = targetId === ROOT ? undefined : [_nodes[targetId].from, _nodes[targetId].to];
+
+        _hidePromotionDialog();
+        _pendingPromotion = null;
+        _syncChessground();
+        _emitHistory();
+        if (_onPositionChange) _onPositionChange(currentFen());
+        return true;
+    }
+
+    // A legitimately-built tree (see _addMove above) only ever gives a node
+    // a parentId that's ROOT or an already-existing, strictly smaller id,
+    // and only ever lists children/activeChild with a strictly larger one,
+    // so parentId chains and children references can never cycle or dangle.
+    // Persisted state coming back out of localStorage bypasses that
+    // construction path entirely; this re-checks the same invariant before
+    // trusting it, since violating it would let goToNode()'s parentId walk
+    // (or moveLine.js's tree walk) loop forever or index past the array.
+    function _isValidNodeRef(id, nodesLength) {
+        return typeof id === 'number' && Number.isInteger(id) && id >= 0 && id < nodesLength;
+    }
+    function _isValidTree(nodes, rootChildren) {
+        if (!Array.isArray(nodes) || !Array.isArray(rootChildren)) return false;
+        for (let id = 0; id < nodes.length; id++) {
+            const node = nodes[id];
+            if (!node || typeof node.san !== 'string' || typeof node.fen !== 'string') return false;
+            if (node.parentId !== ROOT && !(_isValidNodeRef(node.parentId, nodes.length) && node.parentId < id)) {
+                return false;
+            }
+            if (!Array.isArray(node.children)) return false;
+            for (const childId of node.children) {
+                if (!_isValidNodeRef(childId, nodes.length) || childId <= id) return false;
+            }
+            if (node.activeChild !== null && node.activeChild !== undefined &&
+                !(_isValidNodeRef(node.activeChild, nodes.length) && node.activeChild > id)) {
+                return false;
+            }
+        }
+        return rootChildren.every(childId => _isValidNodeRef(childId, nodes.length));
+    }
+
+    // restoreTree() rehydrates a full move tree (start position + every
+    // node + current node) from persisted state in a single board update,
+    // without replaying each move or triggering individual probes.
+    // The active variant must already be established (via init()'s variant
+    // argument) before this is called - this function only restores
+    // position/tree data, never variant.
+    function restoreTree(startFen, nodes, rootChildren, rootActiveChild, currentId) {
+        if (!_position || !startFen) return false;
+        const validTree        = _isValidTree(nodes, rootChildren);
+        const safeNodes        = validTree ? nodes : [];
+        const safeRootChildren = validTree ? rootChildren : [];
+        const safeCurrentId    = (currentId === ROOT || (validTree && _isValidNodeRef(currentId, safeNodes.length)))
+            ? currentId : ROOT;
+
+        const loadFen = safeCurrentId === ROOT ? startFen : safeNodes[safeCurrentId].fen;
+        const built = _buildPosition(loadFen);
+        if (!built.ok) {
+            // Saved state doesn't parse (e.g. corrupted storage) - fall back
+            // to just the start position with an empty tree.
+            const fallback = _buildPosition(startFen);
+            _position = fallback.ok ? fallback.pos : Chess.default();
+            _startFen         = currentFen();
+            _nodes            = [];
+            _rootChildren     = [];
+            _rootActiveChild  = null;
+            _currentId        = ROOT;
+            _history          = [];
+            _future           = [];
+            _lastMoveKeys     = undefined;
+            if (cg) {
+                _hidePromotionDialog();
+                _syncChessground();
+            }
+            _emitHistory();
+            return false;
+        }
+        _position = built.pos;
+
+        _startFen        = startFen;
+        _nodes            = safeNodes;
+        _rootChildren     = safeRootChildren;
+        _rootActiveChild  = _isValidNodeRef(rootActiveChild, safeNodes.length) ? rootActiveChild : null;
+        _currentId        = safeCurrentId;
+        _history          = [];
+        _future           = [];
+        _lastMoveKeys     = (safeCurrentId === ROOT || !safeNodes[safeCurrentId])
+            ? undefined
+            : [safeNodes[safeCurrentId].from, safeNodes[safeCurrentId].to];
+
+        _hidePromotionDialog();
+        _pendingPromotion = null;
+        if (cg) _syncChessground();
+        _emitHistory();
+        return true;
+    }
+
+    // Install a parsed PGN in one update. Only the displayed start position
+    // is probed; every imported move stays available for navigation/export.
+    function importGame(tree, variant) {
+        const next = variant === VARIANTS.CHESS960 ? VARIANTS.CHESS960 : VARIANTS.STANDARD;
+        const built = _buildPosition(tree.startFen, next);
+        if (!built.ok) return { ok: false, reason: built.reason };
+        if (!_isValidTree(tree.nodes, tree.rootChildren)) {
+            return { ok: false, reason: 'Invalid move tree in PGN.' };
+        }
+        _variant = next;
+        _position = built.pos;
+        restoreTree(tree.startFen, tree.nodes, tree.rootChildren, tree.rootActiveChild, ROOT);
+        if (_onPositionChange) _onPositionChange(currentFen(), true);
+        return { ok: true };
+    }
+
+    function canGoBack()    { return _currentId !== ROOT || _history.length > 0; }
+    function canGoForward() {
+        const activeChildId = _activeChildOf(_currentId);
+        return (activeChildId !== null && activeChildId !== undefined) || (_currentId === ROOT && _future.length > 0);
+    }
+
+    function getMoveHistory() {
+        return { nodes: _nodes, rootChildren: _rootChildren, rootActiveChild: _rootActiveChild, currentId: _currentId };
+    }
+    function getStartFen() { return _startFen; }       // PGN formatting
+    function setOnMoveHistoryChange(fn) {
+        _onMoveHistoryChange = fn;
+    }
+
+    return {
+        init, reconstruct, setPosition, setPositionAndVariant, clear, flip, currentFen,
+        playMove, goBack, goForward, goToNode, restoreTree, importGame, canGoBack, canGoForward,
+        getMoveHistory, getStartFen, setOnMoveHistoryChange,
+        drawArrows, clearArrows,
+        setLocked, isLocked,
+        setVariant, getVariant, isChess960, legalMoveCount, isInsufficientMaterial, outcomeFromFen,
+    };
+
+})();
+
+export { Board, VARIANTS };

frontend/src/engine/gameState.js

@@ -0,0 +1,76 @@
+/**
+ * gameState.js: URL-hash sharing and persisted game state
+ *
+ * The hash is rewritten on every position change so the address bar stays
+ * share-able, and is read back on load (and on hashchange) to restore a
+ * shared link. Persisting the full move tree to localStorage additionally
+ * lets a round-trip through a different route (e.g. /admin, which has no
+ * #fen= of its own) restore the board position and PGN panel together.
+ */
+
+import { VARIANTS } from './board.js';
+import * as Storage from './storage.js';
+
+export function writeHash(fen, variant) {
+    try {
+        let hash = '#fen=' + encodeURIComponent(fen);
+        if (variant === VARIANTS.CHESS960) hash += '&variant=' + VARIANTS.CHESS960;
+        history.replaceState(null, '', hash);
+    } catch { /* sandboxed context */ }
+}
+
+export function readHashFen() {
+    try {
+        const m = location.hash.match(/[#&]fen=([^&]+)/);
+        return m ? decodeURIComponent(m[1]) : null;
+    } catch { return null; }
+}
+
+// Returns VARIANTS.CHESS960 / VARIANTS.STANDARD, or null (Standard) if the
+// hash has no (or an unrecognized) variant param. Never inferred from the
+// FEN itself.
+export function readHashVariant() {
+    try {
+        const m = location.hash.match(/[#&]variant=([^&]+)/);
+        if (!m) return null;
+        const v = decodeURIComponent(m[1]);
+        if (v === VARIANTS.CHESS960) return VARIANTS.CHESS960;
+        if (v === VARIANTS.STANDARD) return VARIANTS.STANDARD;
+        return null;
+    } catch { return null; }
+}
+
+const _LS_GAME = 'chesstb_last_game';
+
+export function saveGameState(history, startFen, variant) {
+    Storage.writeJson(_LS_GAME, {
+        variant,
+        startFen,
+        nodes:           history.nodes,
+        rootChildren:    history.rootChildren,
+        rootActiveChild: history.rootActiveChild,
+        currentId:       history.currentId,
+    });
+}
+
+export function readLastGame() {
+    const parsed = Storage.readJson(_LS_GAME);
+    if (!parsed || typeof parsed.startFen !== 'string' || !Array.isArray(parsed.nodes)) {
+        return null;
+    }
+    parsed.variant = parsed.variant === VARIANTS.CHESS960 ? VARIANTS.CHESS960 : VARIANTS.STANDARD;
+    const node = parsed.nodes[parsed.currentId];
+    parsed.currentFen = (!node || typeof node.fen !== 'string') ? parsed.startFen : node.fen;
+    return parsed;
+}
+
+// Client-side mirror of the backend's own FEN padding (app.py's
+// _normalize_fen): pads a partial FEN out to all six fields with the
+// standard defaults.
+export function normalizeFen(s) {
+    const trimmed = s.trim();
+    const defaults = ['8/8/8/8/8/8/8/8', 'w', '-', '-', '0', '1'];
+    const parts = trimmed ? trimmed.split(/\s+/) : [];
+    while (parts.length < 6) parts.push(defaults[parts.length]);
+    return parts.slice(0, 6).join(' ');
+}

frontend/src/engine/moveLine.js

@@ -0,0 +1,103 @@
+/**
+ * moveLine.js: move-tree → render items
+ *
+ * Walks the branching move tree the same way the PGN exporter does (see
+ * pgnFormat.js's childrenOf/collectMainPath) and produces a flat list of
+ * render items for the move-list panel: 'row' items for the main line's
+ * Rank/White/Black grid, and 'variation' items for parenthesised
+ * alternatives, each carrying enough to expand into its own paragraph
+ * without re-walking the tree.
+ */
+
+import { ROOT_ID, childrenOf, collectMainPath } from './pgnFormat.js';
+
+// Builds the main line as row items: one full move per row. A move with
+// alternatives gets a 'variation' item right after it instead of packed
+// into its own cell - since a variation spans the full row width, the
+// next row after it always starts fresh.
+export function buildMainLine(nodes, rootChildren, nodeIds, parentId, whiteToMove, moveNum, currentId) {
+    const items = [];
+    let row = { kind: 'row', num: moveNum, white: whiteToMove ? null : { placeholder: true }, black: null };
+    items.push(row);
+
+    nodeIds.forEach((id, i) => {
+        const node = nodes[id];
+        const parentForThis = i === 0 ? parentId : nodeIds[i - 1];
+        const kids          = childrenOf(nodes, rootChildren, parentForThis);
+        const hasVariation  = kids.length > 1;
+
+        if (whiteToMove) row.white = { node, isCurrent: node.id === currentId };
+        else row.black = { node, isCurrent: node.id === currentId };
+
+        const wasWhite    = whiteToMove;
+        const thisMoveNum = moveNum;
+        if (!whiteToMove) moveNum++;
+        whiteToMove = !whiteToMove;
+
+        if (hasVariation) {
+            for (let v = 1; v < kids.length; v++) {
+                const varPath = collectMainPath(nodes, kids[v]);
+                items.push({ kind: 'variation', nodeIds: varPath, whiteToMove: wasWhite, moveNum: thisMoveNum, depth: 1 });
+            }
+        }
+
+        if (i !== nodeIds.length - 1) {
+            if (wasWhite && !hasVariation) {
+                // continues into this row's still-empty black cell
+            } else {
+                row = { kind: 'row', num: moveNum, white: whiteToMove ? null : { placeholder: true }, black: null };
+                items.push(row);
+            }
+        }
+    });
+    return items;
+}
+
+// Builds one variation's body as a sequence of paragraphs (chip lists):
+// a move within it that itself has alternatives interrupts the paragraph:
+// the nested variation(s) become their own, more deeply indented items,
+// and this variation's remaining moves continue in a fresh paragraph at
+// the same depth.
+export function buildVariation(nodes, rootChildren, nodeIds, whiteToMove, moveNum, currentId, depth) {
+    const items = [];
+    let para = { kind: 'para', depth, chips: [] };
+    items.push(para);
+
+    nodeIds.forEach((id, i) => {
+        const node = nodes[id];
+        // i === 0 is the move that spawned this variation body - its
+        // siblings were already enumerated by the caller as separate
+        // variation items, so this doesn't re-derive them here.
+        const parentForThis = i === 0 ? null : nodeIds[i - 1];
+        const kids          = parentForThis !== null ? childrenOf(nodes, rootChildren, parentForThis) : null;
+        const hasVariation  = !!(kids && kids.length > 1);
+
+        if (whiteToMove || i === 0) {
+            para.chips.push({ kind: 'num', text: moveNum + (whiteToMove ? '.' : '…') });
+        }
+        para.chips.push({ kind: 'move', node, isCurrent: node.id === currentId });
+
+        const wasWhite    = whiteToMove;
+        const thisMoveNum = moveNum;
+        if (!whiteToMove) moveNum++;
+        whiteToMove = !whiteToMove;
+
+        if (hasVariation) {
+            for (let v = 1; v < kids.length; v++) {
+                const varPath = collectMainPath(nodes, kids[v]);
+                items.push({ kind: 'variation', nodeIds: varPath, whiteToMove: wasWhite, moveNum: thisMoveNum, depth: depth + 1 });
+            }
+            if (i !== nodeIds.length - 1) {
+                para = { kind: 'para', depth, chips: [] };
+                items.push(para);
+            }
+        }
+    });
+    return items;
+}
+
+export function buildMoveListItems(nodes, rootChildren, currentId, turn, fullmove) {
+    if (!rootChildren || rootChildren.length === 0) return [];
+    const mainPath = collectMainPath(nodes, rootChildren[0]);
+    return buildMainLine(nodes, rootChildren, mainPath, ROOT_ID, turn === 'w', fullmove, currentId);
+}

frontend/src/engine/pgnFormat.js

@@ -0,0 +1,198 @@
+/**
+ * pgnFormat.js: move-tree helpers, PGN export text, and PGN import parsing
+ *
+ * The tree-walking helpers (childrenOf/collectMainPath) are shared by the
+ * move-list panel and the PGN exporter so the two can't disagree about
+ * where a variation forks.
+ */
+
+import { Board, VARIANTS } from './board.js';
+import { Chess } from '../vendor/chessops/chess.js';
+import { parseFen, makeFen } from '../vendor/chessops/fen.js';
+import { parsePgnStrict, PgnError } from '../vendor/chessops/pgn.js';
+import { parseSan, makeSan } from '../vendor/chessops/san.js';
+import { makeSquare } from '../vendor/chessops/util.js';
+
+export const ROOT_ID = -1;
+
+export function childrenOf(nodes, rootChildren, id) {
+    return id === ROOT_ID ? rootChildren : nodes[id].children;
+}
+
+// Follows children[0] repeatedly from startId - one line's worth of node
+// ids (its own "main" continuation).
+export function collectMainPath(nodes, startId) {
+    const ids = [];
+    let cur = startId;
+    while (cur !== null && cur !== undefined) {
+        ids.push(cur);
+        const kids = nodes[cur].children;
+        cur = kids.length ? kids[0] : null;
+    }
+    return ids;
+}
+
+// Derives {turn, fullmove} from a FEN's 2nd/6th fields, for numbering a
+// move line that doesn't start from a fresh game.
+export function parseFenMeta(fen) {
+    const parts = String(fen || '').trim().split(/\s+/);
+    const turn     = parts[1] === 'b' ? 'b' : 'w';
+    const fullmove = parseInt(parts[5], 10);
+    return { turn, fullmove: Number.isFinite(fullmove) && fullmove > 0 ? fullmove : 1 };
+}
+
+// Same recursive shape as the move-list panel's own rendering - builds PGN
+// movetext tokens (including variations, in "(...)" notation) instead of
+// DOM/JSX nodes.
+function buildMoveTokens(nodes, rootChildren, nodeIds, parentId, whiteToMove, moveNum, skipFirstFork) {
+    const tokens = [];
+    nodeIds.forEach((id, i) => {
+        const node = nodes[id];
+        if (whiteToMove) {
+            tokens.push(`${moveNum}.`, node.san);
+        } else if (i === 0) {
+            tokens.push(`${moveNum}...`, node.san);
+        } else {
+            tokens.push(node.san);
+        }
+        if (!(i === 0 && skipFirstFork)) {
+            const parentForThis = i === 0 ? parentId : nodeIds[i - 1];
+            const kids = childrenOf(nodes, rootChildren, parentForThis);
+            for (let v = 1; v < kids.length; v++) {
+                const varPath = collectMainPath(nodes, kids[v]);
+                const varTokens = buildMoveTokens(nodes, rootChildren, varPath, parentForThis, whiteToMove, moveNum, true);
+                tokens.push(`(${varTokens.join(' ')})`);
+            }
+        }
+        if (!whiteToMove) moveNum++;
+        whiteToMove = !whiteToMove;
+    });
+    return tokens;
+}
+
+// Builds a PGN export: the standard tag-roster header block (plus
+// FEN/SetUp, since the explorer's starting position is rarely the default
+// array) followed by movetext ending in a result token.
+export function buildPgnText() {
+    const { nodes, rootChildren } = Board.getMoveHistory();
+    if (!rootChildren || rootChildren.length === 0) return '';
+
+    const startFen = Board.getStartFen();
+    const mainPath = collectMainPath(nodes, rootChildren[0]);
+    const finalFen = nodes[mainPath[mainPath.length - 1]].fen;
+    const result   = Board.outcomeFromFen(finalFen);
+
+    const today   = new Date();
+    const pad     = n => String(n).padStart(2, '0');
+    const dateStr = `${today.getFullYear()}.${pad(today.getMonth() + 1)}.${pad(today.getDate())}`;
+
+    const headers = [
+        ['Event',  'ChessTB Explorer'],
+        ['Site',   '?'],
+        ['Date',   dateStr],
+        ['Round',  '?'],
+        ['White',  '?'],
+        ['Black',  '?'],
+        ['Result', result],
+    ];
+    if (Board.isChess960()) headers.push(['Variant', 'Chess960']);
+    headers.push(['FEN', startFen], ['SetUp', '1']);
+    const headerBlock = headers.map(([k, v]) => `[${k} "${v}"]`).join('\n');
+
+    const { turn, fullmove } = parseFenMeta(startFen);
+    const tokens = buildMoveTokens(nodes, rootChildren, mainPath, ROOT_ID, turn === 'w', fullmove, false);
+    tokens.push(result);
+
+    return `${headerBlock}\n\n${tokens.join(' ')}`;
+}
+
+// Case-insensitive PGN tag lookup - chessops preserves whatever case the
+// source PGN used.
+function pgnHeaderValue(headers, name) {
+    const wanted = name.toLowerCase();
+    for (const key of headers.keys()) {
+        if (key.toLowerCase() === wanted) return headers.get(key);
+    }
+    return null;
+}
+
+// chessops's own PGN Variant parsing maps every Chess960-like name to the
+// same generic rules Standard uses, so Chess960 identity is read from the
+// raw header text instead.
+function isChess960VariantHeader(value) {
+    return /chess\s*960|fischer\s*random/i.test(value || '');
+}
+
+// Parses and validates the entire game tree, including variations, into
+// Board's move-history format and the variant declared by its header.
+// Returns { ok: false, error } on any rejection.
+export function parsePgn(text) {
+    const trimmed = text.trim();
+    if (!trimmed) return { ok: false, error: '' };
+
+    let games = [];
+    try {
+        games = parsePgnStrict(trimmed);
+    } catch (error) {
+        const msg = (error instanceof PgnError && error.message === 'ERR_PGN_MULTIPLE_GAMES')
+            ? 'PGN contains multiple games. Paste one game at a time.'
+            : 'Could not parse PGN. Check the format and try again.';
+        return { ok: false, error: msg };
+    }
+    const game = games[0];
+    const moves = game ? [...game.moves.mainline()] : [];
+    if (!game || (game.headers.size === 0 && moves.length === 0)) {
+        return { ok: false, error: 'Could not parse PGN. Check the format and try again.' };
+    }
+
+    const variant = isChess960VariantHeader(pgnHeaderValue(game.headers, 'Variant'))
+        ? VARIANTS.CHESS960 : VARIANTS.STANDARD;
+
+    const fenHeader = pgnHeaderValue(game.headers, 'FEN');
+    if (variant === VARIANTS.CHESS960 && !fenHeader) {
+        return { ok: false, error: 'Chess960 PGN requires a FEN starting position.' };
+    }
+    let pos = null;
+    if (fenHeader) {
+        const parsed = parseFen(fenHeader);
+        const built  = parsed.isErr ? null : Chess.fromSetup(parsed.value);
+        pos = (built && !built.isErr) ? built.value : null;
+        if (!pos) return { ok: false, error: 'Invalid FEN starting position in PGN.' };
+    }
+    if (!pos) pos = Chess.default();
+    const startFen = makeFen(pos.toSetup());
+
+    const tree = { startFen, nodes: [], rootChildren: [], rootActiveChild: null, currentId: ROOT_ID };
+    const pending = [{ source: game.moves, parentId: ROOT_ID, pos }];
+    // An explicit stack handles long lines without recursion limits.
+    while (pending.length) {
+        const frame = pending.pop();
+        const children = frame.source.children;
+        const next = [];
+        for (const child of children) {
+            const childPos = frame.pos.clone();
+            const move = parseSan(childPos, child.data.san);
+            if (!move) return { ok: false, error: `Invalid move in PGN: ${child.data.san}` };
+            const san = makeSan(childPos, move);
+            childPos.play(move);
+            const id = tree.nodes.length;
+            tree.nodes.push({
+                id, san, fen: makeFen(childPos.toSetup()),
+                from: makeSquare(move.from), to: makeSquare(move.to),
+                parentId: frame.parentId, children: [], activeChild: null,
+            });
+            if (frame.parentId === ROOT_ID) {
+                tree.rootChildren.push(id);
+                if (tree.rootActiveChild === null) tree.rootActiveChild = id;
+            } else {
+                const parent = tree.nodes[frame.parentId];
+                parent.children.push(id);
+                if (parent.activeChild === null) parent.activeChild = id;
+            }
+            next.push({ source: child, parentId: id, pos: childPos });
+        }
+        // Visit the main continuation first, preserving source branch order.
+        pending.push(...next.reverse());
+    }
+    return { ok: true, tree, variant };
+}

frontend/src/engine/scroll.js

@@ -0,0 +1,49 @@
+// Scrolls `el` into view within `container` only - never any ancestor
+// beyond it (unlike Element.scrollIntoView(), which would also drag the
+// mobile screen-carousel over to whichever panel is calling this).
+export function scrollIntoViewWithin(el, container) {
+    if (!el || !container) return;
+    const elRect = el.getBoundingClientRect();
+    const containerRect = container.getBoundingClientRect();
+    if (elRect.top < containerRect.top) {
+        container.scrollTop -= (containerRect.top - elRect.top);
+    } else if (elRect.bottom > containerRect.bottom) {
+        container.scrollTop += (elRect.bottom - containerRect.bottom);
+    }
+    if (elRect.left < containerRect.left) {
+        container.scrollLeft -= (containerRect.left - elRect.left);
+    } else if (elRect.right > containerRect.right) {
+        container.scrollLeft += (elRect.right - containerRect.right);
+    }
+}
+
+// While .moves-body-scroll overflows vertically, its scrollbar narrows the
+// content box. The body table is widened by the scrollbar's measured width
+// so its columns keep the same pixel widths as the header table's.
+export function syncMovesGutter() {
+    const scroller = document.querySelector('.moves-body-scroll');
+    if (!scroller) return;
+    if (scroller.scrollHeight <= scroller.clientHeight + 1) {
+        scroller.classList.remove('has-vscroll');
+        scroller.style.removeProperty('--moves-vscroll-width');
+        return;
+    }
+    const scrollbarWidth = Math.max(0, scroller.offsetWidth - scroller.clientWidth);
+    scroller.style.setProperty('--moves-vscroll-width', `${scrollbarWidth}px`);
+    scroller.classList.add('has-vscroll');
+}
+
+export function initMovesGutterSync() {
+    const scroller = document.querySelector('.moves-body-scroll');
+    const tbody = document.getElementById('moves-tbody');
+    if (!scroller || !tbody) return () => {};
+    syncMovesGutter();
+    const observer = new ResizeObserver(syncMovesGutter);
+    observer.observe(scroller);
+    observer.observe(tbody);
+    window.addEventListener('resize', syncMovesGutter, { passive: true });
+    return () => {
+        observer.disconnect();
+        window.removeEventListener('resize', syncMovesGutter);
+    };
+}

frontend/src/engine/storage.js

@@ -0,0 +1,36 @@
+/**
+ * storage.js: localStorage helpers
+ *
+ * Every read/write goes through try/catch, since localStorage can throw in
+ * a sandboxed or private-browsing context. A failed read returns `fallback`;
+ * a failed write is silently ignored - callers treat persistence as
+ * best-effort.
+ */
+
+export function read(key, fallback = null) {
+    try {
+        const raw = localStorage.getItem(key);
+        return raw === null ? fallback : raw;
+    } catch (_) {
+        return fallback;
+    }
+}
+
+export function write(key, value) {
+    try { localStorage.setItem(key, String(value)); } catch (_) { /* unavailable or full */ }
+}
+
+export function readJson(key, fallback = null) {
+    try {
+        const raw = localStorage.getItem(key);
+        if (raw === null) return fallback;
+        const parsed = JSON.parse(raw);
+        return parsed === null || parsed === undefined ? fallback : parsed;
+    } catch (_) {
+        return fallback;
+    }
+}
+
+export function writeJson(key, value) {
+    try { localStorage.setItem(key, JSON.stringify(value)); } catch (_) { /* unavailable or full */ }
+}

frontend/src/engine/tablebase.js

@@ -0,0 +1,735 @@
+/**
+ * tablebase.js - /probe/stream SSE client and results state
+ *
+ * Owns the SSE client for /probe/stream and all state for the four ranked
+ * move tables (DTZ / DTC / DTM / DTM50):
+ *   - setResultHandler(fn) - callback after each successful probe, used for
+ *     auto-play.
+ *   - setNoteHandler(fn) - callback with the message of a warning or info
+ *     dot tapped with touch or pen input.
+ *   - setViewStateHandler(fn) - callback with a plain object describing
+ *     everything the results panel needs to render (loading/progress/error,
+ *     the Root row, and the ranked move rows). Rendering itself is the
+ *     caller's responsibility; this module never touches the DOM to draw
+ *     the table.
+ *   - attachTableEvents(tbody) - wires click-to-play, hover pairing, and
+ *     hover-triggered prefetch onto the actual rendered <tbody>. Returns a
+ *     cleanup function.
+ *   - Prefetch on hover: warms the cache for the child position of a
+ *     hovered move.
+ *   - The Root row: the current position's own score for each metric,
+ *     included in the view state ahead of the ranked child moves when the
+ *     "Show Root Row" setting is on (see setShowRootRow/getShowRootRow).
+ *   - A coverage indicator: distinct state when error_code === "missing_table".
+ *   - An info flag on draws by insufficient material, and a warning flag on
+ *     a cursed win / blessed loss outcome - both carry a tooltip string for
+ *     the caller to render. The warning tooltip has a second line when the
+ *     DTZ score is rounded.
+ *   - CSV export of the current move table.
+ *   - A result cache keyed by (variant, FEN), so revisiting an already-
+ *     probed position reuses the cached result instead of issuing a new
+ *     /probe/stream call.
+ */
+
+import { Board, VARIANTS } from './board.js';
+import * as Storage        from './storage.js';
+
+// ── Bounded LRU cache ────────────────────────────────────────────────────
+const _MAX_CACHE_ENTRIES = 500;
+
+class _BoundedCache {
+    constructor(maxSize) {
+        this._maxSize = maxSize;
+        this._map = new Map();
+    }
+    has(key) { return this._map.has(key); }
+    get(key) {
+        if (!this._map.has(key)) return undefined;
+        const value = this._map.get(key);
+        this._map.delete(key);
+        this._map.set(key, value);   // refresh recency
+        return value;
+    }
+    set(key, value) {
+        this._map.delete(key);
+        this._map.set(key, value);
+        if (this._map.size > this._maxSize) {
+            this._map.delete(this._map.keys().next().value);   // evict oldest
+        }
+    }
+    delete(key) { this._map.delete(key); }
+}
+
+const Tablebase = (() => {
+
+    let _currentController = null;
+    let _probeSeq    = 0;
+    let _loadingTimer = null;
+    let _pendingProgress = null;
+    let _onMoveSelect = null;
+    let _onNote       = null;
+    let _onResult     = null;
+    let _onViewState  = null;
+    let _lastData     = null;
+    let _lastFen      = null;     // FEN of the currently-applied results
+    let _lastVariant  = null;     // variant the currently-applied results were probed under
+    let _prefetchCache = new _BoundedCache(_MAX_CACHE_ENTRIES);   // (variant,child_fen) → probe result data
+    let _resultCache   = new _BoundedCache(_MAX_CACHE_ENTRIES);   // (variant,fen) → last probe result
+
+    // Hover-prefetch state - module-scoped so probe() can see and cancel an
+    // in-flight prefetch for the exact position it's about to probe itself.
+    let _prefetchTimer      = null;
+    let _prefetchController = null;   // in-flight prefetch fetch, if any
+    let _prefetchKey        = null;   // cache key for the timer/fetch above
+    let _prefetchRun        = null;   // identity token for the current pending/in-flight run
+    let _prefetchPromise    = null;   // current run's eventual { ok, data|error, aborted } outcome
+    let _prefetchAttached   = false;  // true while a probe() call is awaiting _prefetchPromise
+
+    function _cancelPrefetch() {
+        clearTimeout(_prefetchTimer);
+        _prefetchTimer = null;
+        if (_prefetchAttached) return;
+        if (_prefetchController) { _prefetchController.abort(); _prefetchController = null; }
+        _prefetchKey = null;
+        _prefetchRun = null;
+        _prefetchPromise = null;
+    }
+
+    function _cacheKey(fen, variant) { return `${variant || VARIANTS.STANDARD}\u0000${fen}`; }
+
+    // ── Show Root Row setting ────────────────────────────────────────────
+    const _LS_SHOW_ROOT_ROW = 'chesstb_show_root_row';
+    function _readShowRootRowPref() { return Storage.read(_LS_SHOW_ROOT_ROW) === 'true'; }
+    let _showRootRow = _readShowRootRowPref();
+
+    const _ROOT_LABEL = 'Root';
+
+    // ── WDL / formatting helpers ─────────────────────────────────────────
+    function _wdlToOutcome(wdl) {
+        return { 2:'win', 1:'cursed_win', 0:'draw', '-1':'blessed_loss', '-2':'loss' }[wdl] ?? 'unknown';
+    }
+    function _plural(n) { return Math.abs(n) === 1 ? 'ply' : 'plies'; }
+    function _pliesText(n) {
+        const a = Math.abs(n);
+        return `${a} ${_plural(a)}`;
+    }
+    function _dtcRootRaw(data) {
+        return {
+            san: _ROOT_LABEL,
+            plies: data.dtc_available ? data.dtc[2] : 0,
+            order: data.dtc_available ? data.dtc[1] : 0,
+            outcome: data.dtc_available ? _wdlToOutcome(data.dtc[0]) : 'not_available',
+            available: data.dtc_available,
+        };
+    }
+    function _csvPlies(entry) { return entry.available === false ? 'N/A' : entry.plies; }
+
+    function _isPawnless(fen) {
+        if (!fen) return false;
+        return !/[Pp]/.test(fen.split(' ')[0]);
+    }
+
+    function _dtcDisplayEntry(entry, ownFen) {
+        if (!entry) return null;
+        if (!entry.available) return { ...entry, orderText: 'N/A' };
+        return _isPawnless(ownFen)
+            ? { ...entry, orderText: '-' }
+            : { ...entry, orderText: String(entry.order) };
+    }
+
+    function _dtcScoreText(entry) {
+        const n = Math.abs(entry.plies);
+        return `${n} ${_plural(n)}/${entry.orderText}`;
+    }
+
+    const _ROUNDED_NOTE = 'Rounded Score — this could be off by 1 ply.';
+
+    function _warningText(entry) {
+        const text = entry.outcome === 'cursed_win'
+            ? 'Cursed Win — a win in principle, but a draw under the 50-move rule.'
+            : entry.outcome === 'blessed_loss'
+                ? 'Blessed Loss — a loss in principle, but a draw under the 50-move rule.'
+                : null;
+        return text && entry.rounded ? `${text}\n${_ROUNDED_NOTE}` : text;
+    }
+
+    // ── Cell descriptors ──────────────────────────────────────────────────
+    // Same shape/formatting rules as a rendered <td> pair, as plain data;
+    // the caller renders these into cells (see ResultsPanel). `metric` and
+    // `groupClass` drive the CSS grouping; `interactive` gates whether the
+    // cell is clickable/prefetchable (false for the Root row).
+    function _createMoveCells(entry, groupClass, interactive = true, dtcFormat = false) {
+        const metric  = groupClass.slice('group-'.length);
+        const headers = interactive
+            ? { move: `th-${metric}-grp th-${metric}-move`, score: `th-${metric}-grp th-${metric}-score` }
+            : null;
+        if (!entry) {
+            return [
+                { kind: 'move',  className: `${groupClass} col-move is-empty-cell`, headers: headers?.move ?? null, text: '—', title: null, interactive: false },
+                { kind: 'score', className: `${groupClass} col-score is-empty-cell`, headers: headers?.score ?? null, text: '—', title: null, interactive: false },
+            ];
+        }
+
+        let scoreText;
+        if (entry.is_mate)                                    scoreText = 'Checkmate';
+        else if (entry.draw_reason === 'stalemate')           scoreText = 'Stalemate';
+        else if (entry.outcome === 'draw')                    scoreText = 'Draw';
+        else if (entry.outcome === 'unknown')                 scoreText = 'Unknown';
+        else if (entry.outcome === 'not_available')           scoreText = 'Not Available';
+        else if (dtcFormat)                                    scoreText = _dtcScoreText(entry);
+        else                                                   scoreText = _pliesText(entry.plies);
+
+        const outcomeLabel = {
+            win: 'Win', loss: 'Loss', cursed_win: 'Cursed win', blessed_loss: 'Blessed loss',
+        }[entry.outcome];
+        const scoreLabel = outcomeLabel && !entry.is_mate
+            ? `${outcomeLabel}: ${scoreText}` : scoreText;
+
+        const moveCell = {
+            kind: 'move',
+            className: `${groupClass} col-move${interactive ? '' : ' is-root'}`,
+            headers: headers?.move ?? null,
+            text: entry.san,
+            title: entry.san,
+            interactive,
+            dataSan: interactive ? entry.san : null,
+            dataChildFen: interactive ? (entry.child_fen || '') : null,
+        };
+        const scoreCell = {
+            kind: 'score',
+            className: `${groupClass} col-score${entry.is_mate ? ' is-mate' : ''}`,
+            headers: headers?.score ?? null,
+            text: scoreText,
+            title: scoreLabel,
+            interactive,
+            dataSan: interactive ? entry.san : null,
+            dataChildFen: interactive ? (entry.child_fen || '') : null,
+            outcome: entry.outcome,
+            warning: _warningText(entry),
+            info: entry.draw_reason === 'insufficient_material' ? 'Draw by Insufficient Material' : null,
+        };
+        return [moveCell, scoreCell];
+    }
+
+    // ── Root row entries ──────────────────────────────────────────────────
+    function _rootEntries(data, fen) {
+        const maxRows = Math.max(
+            (data.moves_dtz   || []).length,
+            (data.moves_dtc   || []).length,
+            (data.moves_dtm   || []).length,
+            (data.moves_dtm50 || []).length,
+        );
+        const rootIsMate = maxRows === 0 && data.wdl !== 0;
+
+        const dtzEntry = {
+            san: _ROOT_LABEL, plies: data.dtz_available ? data.dtz : 0,
+            outcome: data.dtz_available ? _wdlToOutcome(data.wdl) : 'not_available',
+            available: data.dtz_available,
+            rounded: data.dtz_rounded === true,
+            is_mate: rootIsMate, draw_reason: data.draw_reason, child_fen: null,
+        };
+        const dtcRaw = {
+            ..._dtcRootRaw(data),
+            is_mate: rootIsMate, draw_reason: data.draw_reason, child_fen: null,
+        };
+        const dtcEntry = _dtcDisplayEntry(dtcRaw, fen);
+        const dtmEntry = {
+            san: _ROOT_LABEL, plies: data.dtm_available ? data.dtm : 0,
+            outcome: data.dtm_available ? _wdlToOutcome(data.wdl) : 'not_available',
+            available: data.dtm_available,
+            is_mate: rootIsMate, draw_reason: data.draw_reason, child_fen: null,
+        };
+        const dtm50Entry = {
+            san: _ROOT_LABEL, plies: data.dtm50_available ? data.dtm50[1] : 0,
+            outcome: data.dtm50_available ? _wdlToOutcome(data.dtm50[0]) : 'not_available',
+            available: data.dtm50_available,
+            is_mate: rootIsMate, draw_reason: data.draw_reason, child_fen: null,
+        };
+        return { dtzEntry, dtcEntry, dtmEntry, dtm50Entry };
+    }
+
+    // ── View state ────────────────────────────────────────────────────────
+    // Single object describing everything the results panel renders.
+    // Rebuilt on every meaningful change and pushed to _onViewState.
+    let _viewState = {
+        pending: false,
+        loading: false,
+        progress: { visible: false, pct: 0, label: '' },
+        error: null,               // { message, isCoverage } | null
+        moveCount: '',
+        showRootRow: _showRootRow,
+        rootRow: null,             // { cells: [...] } | null
+        rows: [],                  // [{ rank, cells: [...] }]
+        emptyState: true,
+        emptyMessage: 'Choose a position to see its best moves.',
+    };
+    function _publish(patch) {
+        _viewState = { ..._viewState, ...patch };
+        if (_onViewState) _onViewState(_viewState);
+    }
+
+    function _beginLoading(mySeq) {
+        clearTimeout(_loadingTimer);
+        _pendingProgress = { visible: true, pct: null, label: 'Checking position…' };
+        // Fast and cached responses should not flash through an empty table.
+        // Disable old move actions immediately, then show loading if needed.
+        _publish({ pending: true, error: null, ...(_viewState.loading ? { progress: _pendingProgress } : {}) });
+        _loadingTimer = setTimeout(() => {
+            if (mySeq !== _probeSeq) return;
+            _blankResults();
+            _publish({ loading: true, progress: _pendingProgress });
+        }, 180);
+    }
+
+    function _rootRowState(data, fen) {
+        if (!_showRootRow) return null;
+        if (!data) {
+            const cells = ['group-dtz', 'group-dtc', 'group-dtm', 'group-dtm50']
+                .flatMap(g => _createMoveCells(null, g));
+            return { cells };
+        }
+        const { dtzEntry, dtcEntry, dtmEntry, dtm50Entry } = _rootEntries(data, fen);
+        const cells = [
+            ..._createMoveCells(dtzEntry,   'group-dtz',   false),
+            ..._createMoveCells(dtcEntry,   'group-dtc',   false, true),
+            ..._createMoveCells(dtmEntry,   'group-dtm',   false),
+            ..._createMoveCells(dtm50Entry, 'group-dtm50', false),
+        ];
+        return { cells };
+    }
+
+    function _rowsState(movesDtz, movesDtc, movesDtm, movesDtm50) {
+        const maxRows = Math.max(movesDtz.length, movesDtc.length, movesDtm.length, movesDtm50.length);
+        const rows = [];
+        for (let i = 0; i < maxRows; i++) {
+            const dtcEntry = _dtcDisplayEntry(movesDtc[i] || null, (movesDtc[i] || {}).child_fen);
+            const cells = [
+                ..._createMoveCells(movesDtz[i]   || null, 'group-dtz'),
+                ..._createMoveCells(dtcEntry,               'group-dtc',   true, true),
+                ..._createMoveCells(movesDtm[i]   || null, 'group-dtm'),
+                ..._createMoveCells(movesDtm50[i] || null, 'group-dtm50'),
+            ];
+            rows.push({ rank: i + 1, cells });
+        }
+        return rows;
+    }
+
+    function _blankResults() {
+        _publish({
+            rootRow: _rootRowState(null, _lastFen),
+            rows: [],
+            emptyState: false,
+            moveCount: _viewState.moveCount,   // set client-side from the FEN - untouched here
+        });
+    }
+
+    function _isComplete(data) {
+        return !(data && data.summary && data.summary.unknown > 0);
+    }
+
+    function _applyResults(data, fen, variant) {
+        clearTimeout(_loadingTimer);
+        _lastData    = data;
+        _lastFen     = fen;
+        _lastVariant = variant;
+        if (_isComplete(data)) _resultCache.set(_cacheKey(fen, variant), data);
+
+        const movesDtz   = data.moves_dtz   || [];
+        const movesDtc   = data.moves_dtc   || [];
+        const movesDtm   = data.moves_dtm   || [];
+        const movesDtm50 = data.moves_dtm50 || [];
+        const rows = _rowsState(movesDtz, movesDtc, movesDtm, movesDtm50);
+        const maxRows = rows.length;
+
+        _publish({
+            pending: false,
+            loading: false,
+            progress: { visible: false, pct: 0, label: '' },
+            error: null,
+            rootRow: _rootRowState(data, fen),
+            rows,
+            emptyState: maxRows === 0,
+            emptyMessage: data.draw_reason === 'insufficient_material'
+                ? 'Draw by insufficient material.'
+                : data.draw_reason === 'stalemate'
+                    ? 'Stalemate. No legal moves.'
+                    : data.wdl === -2 && maxRows === 0
+                        ? 'Checkmate. No legal moves.'
+                        : data.wdl === 0
+                            ? 'Draw.'
+                            : 'No ranked moves for this position.',
+            moveCount: maxRows > 0 ? `${maxRows} legal move${maxRows === 1 ? '' : 's'}` : '',
+        });
+        if (_onResult) _onResult(data);
+    }
+
+    function _applyCachedResult(data, fen, variant, mySeq) {
+        clearTimeout(_loadingTimer);
+        Promise.resolve().then(() => {
+            if (mySeq !== _probeSeq) return;
+            _applyResults(data, fen, variant);
+        });
+    }
+
+    function _reset() {
+        clearTimeout(_loadingTimer);
+        _publish({ pending: false, loading: false, progress: { visible: false, pct: 0, label: '' }, rootRow: _rootRowState(null, _lastFen), rows: [], emptyState: false, error: null });
+        _lastData    = null;
+        _lastFen     = null;
+        _lastVariant = null;
+    }
+
+    function _showCoverageError(errData) {
+        const pc   = errData.piece_count;
+        const note = pc ? ` (position has ${pc} pieces)` : '';
+        _publish({ error: { message: `Not in tablebase${note} — load a tablebase with more piece coverage.`, isCoverage: true } });
+    }
+
+    function _handleError(errData, onError) {
+        const msg = errData.error || 'Unknown error.';
+        const isCoverageError = errData.error_code === 'missing_table';
+        if (isCoverageError) {
+            _showCoverageError(errData);
+        } else {
+            _publish({ error: { message: msg, isCoverage: false } });
+        }
+        if (onError) onError(msg, isCoverageError);
+    }
+
+    // ── SSE streaming client ──────────────────────────────────────────────
+    async function* _sseEvents(response) {
+        if (!response.body) throw { error: 'Network error.' };
+        const reader  = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const events = buffer.split('\n\n');
+            buffer = events.pop() || '';
+            for (const rawEvent of events) {
+                const line = rawEvent.trim();
+                if (!line.startsWith('data: ')) continue;
+                try { yield JSON.parse(line.slice(6)); } catch { /* skip malformed frame */ }
+            }
+        }
+    }
+
+    async function _probeStream(fen, variant, signal, mySeq) {
+        const response = await fetch('/probe/stream', {
+            method:  'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body:    JSON.stringify({ fen, variant }),
+            signal,
+        });
+        if (!response.ok) {
+            const err = await response.json().catch(() => ({ error: 'Network error.' }));
+            throw err;
+        }
+        for await (const evtData of _sseEvents(response)) {
+            if (signal.aborted || mySeq !== _probeSeq) throw new DOMException('Cancelled', 'AbortError');
+            if (evtData.status === 'probing') {
+                const total = evtData.total;
+                _pendingProgress = {
+                    visible: true,
+                    pct: total > 0 ? Math.round((evtData.completed / total) * 100) : null,
+                    label: total > 0 ? `Evaluating moves · ${evtData.completed}/${total}` : 'Preparing result…',
+                };
+                if (_viewState.loading) _publish({ progress: _pendingProgress });
+            } else if (evtData.status === 'done') {
+                return evtData;
+            } else if (evtData.status === 'error') {
+                throw evtData;
+            }
+        }
+        throw { error: 'Stream ended unexpectedly.' };
+    }
+
+    function probe(fen, variant, onError) {
+        const mySeq = ++_probeSeq;
+        clearTimeout(_loadingTimer);
+        if (_currentController) { _currentController.abort(); _currentController = null; }
+        const key = _cacheKey(fen, variant);
+
+        if (_prefetchKey === key) {
+            if (_prefetchController && _prefetchPromise) {
+                _prefetchAttached = true;
+                const waitingOn = _prefetchPromise;
+                _beginLoading(mySeq);
+                waitingOn.then(outcome => {
+                    _prefetchAttached = false;
+                    if (mySeq !== _probeSeq) return;
+                    if (outcome.ok) {
+                        _applyResults(outcome.data, fen, variant);
+                    } else {
+                        _reset();
+                        if (!outcome.aborted) _handleError(outcome.error && outcome.error.error ? outcome.error : { error: 'Cannot reach backend.' }, onError);
+                    }
+                });
+                return;
+            }
+            _cancelPrefetch();
+        }
+
+        if (_prefetchCache.has(key)) {
+            const cached = _prefetchCache.get(key);
+            _prefetchCache.delete(key);
+            _applyCachedResult(cached, fen, variant, mySeq);
+            return;
+        }
+        if (_resultCache.has(key)) {
+            _applyCachedResult(_resultCache.get(key), fen, variant, mySeq);
+            return;
+        }
+
+        _currentController = new AbortController();
+        const myController = _currentController;
+        const signal       = myController.signal;
+
+        _beginLoading(mySeq);
+
+        _probeStream(fen, variant, signal, mySeq)
+            .then(data => {
+                if (mySeq !== _probeSeq) return;
+                if (_currentController === myController) _currentController = null;
+                if (data.error) {
+                    _reset();
+                    _handleError(data, onError);
+                } else {
+                    _applyResults(data, fen, variant);
+                }
+            })
+            .catch(err => {
+                if (err && err.name === 'AbortError') return;
+                if (mySeq !== _probeSeq) return;
+                if (_currentController === myController) _currentController = null;
+                _reset();
+                _handleError(err && err.error ? err : { error: 'Cannot reach backend.' }, onError);
+                console.error('[Tablebase]', err);
+            });
+    }
+
+    // ── CSV export ────────────────────────────────────────────────────────
+    function _csvField(value) {
+        const s = String(value);
+        return /[",\n]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+    }
+
+    function exportCsv() {
+        if (!_lastData) return;
+        const dtz   = _lastData.moves_dtz   || [];
+        const dtc   = _lastData.moves_dtc   || [];
+        const dtm   = _lastData.moves_dtm   || [];
+        const dtm50 = _lastData.moves_dtm50 || [];
+        const rows  = Math.max(dtz.length, dtc.length, dtm.length, dtm50.length);
+        const lines = [];
+        if (_lastFen) lines.push(`[FEN "${_lastFen}"]`);
+        lines.push('Rank,DTZ Move,DTZ Plies,DTZ Outcome,DTC Move,DTC Plies,DTC Order,DTC Outcome,DTM Move,DTM Plies,DTM Outcome,DTM50 Move,DTM50 Plies,DTM50 Outcome');
+        if (_showRootRow) {
+            const { dtzEntry, dtcEntry, dtmEntry, dtm50Entry } = _rootEntries(_lastData, _lastFen);
+            lines.push([
+                '',
+                _ROOT_LABEL, _csvPlies(dtzEntry),   dtzEntry.outcome,
+                _ROOT_LABEL, _csvPlies(dtcEntry),   dtcEntry.orderText, dtcEntry.outcome,
+                _ROOT_LABEL, _csvPlies(dtmEntry),   dtmEntry.outcome,
+                _ROOT_LABEL, _csvPlies(dtm50Entry), dtm50Entry.outcome,
+            ].map(_csvField).join(','));
+        }
+        for (let i = 0; i < rows; i++) {
+            const d0 = dtz[i],   d2 = dtm[i],   d3 = dtm50[i];
+            const d1 = _dtcDisplayEntry(dtc[i] || null, (dtc[i] || {}).child_fen);
+            lines.push([
+                i + 1,
+                d0 ? d0.san : '', d0 ? _csvPlies(d0) : '', d0 ? d0.outcome : '',
+                d1 ? d1.san : '', d1 ? _csvPlies(d1) : '', d1 ? d1.orderText : '', d1 ? d1.outcome : '',
+                d2 ? d2.san : '', d2 ? _csvPlies(d2) : '', d2 ? d2.outcome : '',
+                d3 ? d3.san : '', d3 ? _csvPlies(d3) : '', d3 ? d3.outcome : '',
+            ].map(_csvField).join(','));
+        }
+        const blob = new Blob(['\ufeff' + lines.join('\n')], { type: 'text/csv' });
+        const a = document.createElement('a');
+        a.href = URL.createObjectURL(blob);
+        a.download = 'chesstb_moves.csv';
+        a.click();
+        URL.revokeObjectURL(a.href);
+    }
+
+    // ── Public API ────────────────────────────────────────────────────────
+    function setMoveSelectHandler(fn)  { _onMoveSelect = fn; }
+    function setNoteHandler(fn)        { _onNote = fn; }
+    function setResultHandler(fn)      { _onResult = fn; }
+    function setViewStateHandler(fn)   { _onViewState = fn; if (fn) fn(_viewState); }
+    function getViewState()            { return _viewState; }
+    function getLastData()             { return _lastData; }
+    function getLastFen()              { return _lastFen; }
+    function getLastVariant()          { return _lastVariant; }
+
+    function setShowRootRow(show) {
+        _showRootRow = !!show;
+        Storage.write(_LS_SHOW_ROOT_ROW, _showRootRow);
+        _publish({ showRootRow: _showRootRow, rootRow: _rootRowState(_lastData, _lastFen) });
+    }
+    function getShowRootRow() { return _showRootRow; }
+
+    function clearErrorLine() { _publish({ error: null }); }
+
+    // Sets the legal-move count text ahead of any probe result - the count
+    // is computed client-side from the FEN, not from probe data.
+    function setMoveCount(text) { _publish({ moveCount: text }); }
+
+    // ── Table DOM wiring (hover pairing + prefetch + click-to-play) ───────
+    // Attached to the rendered <tbody> by the results panel component.
+    // Pointer position is tracked so a table rebuild under a stationary
+    // pointer (e.g. a probe result arriving mid-hover) can re-evaluate
+    // what is underneath it.
+    function attachTableEvents(tbody) {
+        if (!tbody) return () => {};
+        let hoveredPair  = [];
+        let lastPointerX = null;
+        let lastPointerY = null;
+        let lastPointerType = '';
+
+        function pairCells(cell) {
+            if (cell.classList.contains('col-move')) {
+                const next = cell.nextElementSibling;
+                return next && next.dataset.san ? [cell, next] : [cell];
+            }
+            if (cell.classList.contains('col-score')) {
+                const prev = cell.previousElementSibling;
+                return prev && prev.dataset.san ? [prev, cell] : [cell];
+            }
+            return [cell];
+        }
+        function updatePairHover(target) {
+            const cell = target.closest('td[data-san]');
+            hoveredPair.forEach(c => c.classList.remove('is-pair-hover'));
+            hoveredPair = [];
+            if (cell) {
+                hoveredPair = pairCells(cell);
+                hoveredPair.forEach(c => c.classList.add('is-pair-hover'));
+            }
+        }
+        function updatePrefetch(target) {
+            const cell = target.closest('td[data-child-fen]');
+            if (!cell || !cell.dataset.childFen) { _cancelPrefetch(); return; }
+            const childFen = cell.dataset.childFen;
+            const variant = Board.getVariant() || VARIANTS.STANDARD;
+            const key = _cacheKey(childFen, variant);
+            if (key === _prefetchKey) return;
+            _cancelPrefetch();
+            if (_prefetchCache.has(key) || _resultCache.has(key)) return;
+            _prefetchKey = key;
+            const run = {};
+            _prefetchRun = run;
+            _prefetchTimer = setTimeout(() => {
+                const controller = new AbortController();
+                _prefetchController = controller;
+                _prefetchPromise = fetch('/probe/stream', {
+                    method:  'POST',
+                    headers: { 'Content-Type': 'application/json', 'X-Prefetch': '1' },
+                    body:    JSON.stringify({ fen: childFen, variant }),
+                    signal:  controller.signal,
+                })
+                .then(async r => {
+                    if (!r.ok) {
+                        const err = await r.json().catch(() => ({ error: 'Network error.' }));
+                        return { ok: false, error: err };
+                    }
+                    for await (const d of _sseEvents(r)) {
+                        if (d.status === 'done') {
+                            if (_isComplete(d)) _prefetchCache.set(key, d);
+                            return { ok: true, data: d };
+                        }
+                        if (d.status === 'error') return { ok: false, error: d };
+                    }
+                    return { ok: false, error: { error: 'Stream ended unexpectedly.' } };
+                })
+                .catch(err => ({ ok: false, error: err, aborted: err && err.name === 'AbortError' }))
+                .finally(() => {
+                    if (_prefetchRun === run) {
+                        _prefetchController = null; _prefetchKey = null;
+                        _prefetchRun = null; _prefetchPromise = null;
+                    }
+                });
+            }, 400);
+        }
+        function reapplyHoverAtPointer() {
+            if (lastPointerX === null) return;
+            const el = document.elementFromPoint(lastPointerX, lastPointerY);
+            if (!el || !tbody.contains(el)) {
+                hoveredPair.forEach(c => c.classList.remove('is-pair-hover'));
+                hoveredPair = [];
+                return;
+            }
+            updatePairHover(el);
+            updatePrefetch(el);
+        }
+
+        function onPointerdown(e) { lastPointerType = e.pointerType; }
+        function onClick(e) {
+            if (_viewState.pending) return;
+            const type = e.pointerType || lastPointerType;
+            lastPointerType = '';
+            const dot = e.target.closest('.warning-dot, .info-dot');
+            if (dot && (type === 'touch' || type === 'pen')) {
+                if (_onNote && dot.title) _onNote(dot.title);
+                return;
+            }
+            const cell = e.target.closest('td[data-san]');
+            if (cell && _onMoveSelect) _onMoveSelect(cell.dataset.san);
+        }
+        function onKeydown(e) {
+            if (_viewState.pending) return;
+            if (e.key !== 'Enter' && e.key !== ' ') return;
+            const cell = e.target.closest('td[data-san]');
+            if (cell && _onMoveSelect) { e.preventDefault(); _onMoveSelect(cell.dataset.san); }
+        }
+        function onMousemove(e) { lastPointerX = e.clientX; lastPointerY = e.clientY; }
+        function onMouseover(e) {
+            lastPointerX = e.clientX; lastPointerY = e.clientY;
+            updatePairHover(e.target); updatePrefetch(e.target);
+        }
+        function onMouseleave() {
+            lastPointerX = null; lastPointerY = null;
+            hoveredPair.forEach(c => c.classList.remove('is-pair-hover'));
+            hoveredPair = [];
+            _cancelPrefetch();
+        }
+
+        tbody.addEventListener('pointerdown', onPointerdown);
+        tbody.addEventListener('click', onClick);
+        tbody.addEventListener('keydown', onKeydown);
+        tbody.addEventListener('mousemove', onMousemove);
+        tbody.addEventListener('mouseover', onMouseover);
+        tbody.addEventListener('mouseleave', onMouseleave);
+
+        // The pointer may already be sitting over a cell that just
+        // (re)appeared without itself moving - re-check on every render.
+        reapplyHoverAtPointer();
+        _reapplyOnNextRender = reapplyHoverAtPointer;
+
+        return () => {
+            tbody.removeEventListener('pointerdown', onPointerdown);
+            tbody.removeEventListener('click', onClick);
+            tbody.removeEventListener('keydown', onKeydown);
+            tbody.removeEventListener('mousemove', onMousemove);
+            tbody.removeEventListener('mouseover', onMouseover);
+            tbody.removeEventListener('mouseleave', onMouseleave);
+            if (_reapplyOnNextRender === reapplyHoverAtPointer) _reapplyOnNextRender = () => {};
+        };
+    }
+    let _reapplyOnNextRender = () => {};
+    // Called by the results panel after each render commits, so hover
+    // state re-syncs against the freshly-rendered cells.
+    function notifyTableRendered() { _reapplyOnNextRender(); }
+
+    return {
+        probe, setMoveSelectHandler, setNoteHandler, setResultHandler, getLastData, getLastFen, getLastVariant,
+        setShowRootRow, getShowRootRow, clearErrorLine, setMoveCount, exportCsv,
+        setViewStateHandler, getViewState, attachTableEvents, notifyTableRendered,
+    };
+
+})();
+
+export { Tablebase };

frontend/src/engine/theme.js

@@ -0,0 +1,158 @@
+/**
+ * theme.js: Board and piece theming module
+ *
+ * Owns the chess board's visual styling: square colours, rank/file label
+ * colours, last-move highlight colour, and the piece-set image path. Colours
+ * are read from the --board-* tokens in styles/tokens.css. The board uses
+ * Libre Brown and the piece set uses CBurnett.
+ * Exposes a small public API consumed by board.js and useExplorer.js.
+ *
+ * The CSS-generation function below targets chessground's DOM/class model
+ * (`cg-board`, `coords.ranks`/`coords.files`) - see the comment above
+ * _coordLabelCss() for how coordinate-label positioning and colouring are
+ * derived against that model.
+ *
+ * Public API:
+ *   Theme.init(reconstructBoard)   - register board reconstruction callback
+ *   Theme.apply()                  - inject the board's theme <style> tag
+ *   Theme.currentPieceSet()        - return the active piece set id string
+ *   Theme.pieceThemeFn()           - return piece-code → image-path function
+ *                                     (used by board.js's spare trays and
+ *                                     promotion dialog)
+ */
+
+function _token(name) {
+    return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+}
+
+function _boardColors() {
+    const light = _token('--board-light');
+    const dark  = _token('--board-dark');
+    return {
+        id:          'libre-brown',
+        lightSquare: light,
+        darkSquare:  dark,
+        labelLight:  dark,    // label colour on light-square corners
+        labelDark:   light,   // label colour on dark-square corners
+        highlight:   _token('--board-highlight'),
+    };
+}
+
+const PIECE_SET = 'cburnett';
+
+let _reconstructBoard = null;  // callback registered via init()
+
+// ── Private: CSS generation ───────────────────────────────────────────────
+//
+// Chessground has no per-square light/dark CSS classes - the checkerboard
+// pattern is a single background-image on `cg-board`. It is rendered here
+// as a tiny tiled SVG data URI (_checkerboardDataUri). Rank/file labels
+// are chessground's own `coords.ranks`/`coords.files` elements, positioned
+// by static CSS in chess/board.css to sit inset at the board's corners
+// rather than chessground's default outside-the-board placement. Colour is
+// done with :nth-child selectors scoped by orientation, not the
+// `.coord-light`/`.coord-dark` classes renderCoords() (wrap.ts) puts on
+// each label: those classes don't correspond to the actual square each
+// label overlays once repositioned this way (chessground's own official
+// theme CSS doesn't use them for coords.ranks/coords.files either, for the
+// same reason: they're only meaningful for chessground's default
+// outside-the-board placement). See the matching comment in
+// chess/board.css for the full derivation.
+
+function _checkerboardDataUri(light, dark) {
+    const svg = `<svg xmlns='http://www.w3.org/2000/svg' width='2' height='2'>
+<rect width='1' height='1' fill='${light}'/>
+<rect x='1' width='1' height='1' fill='${dark}'/>
+<rect y='1' width='1' height='1' fill='${dark}'/>
+<rect x='1' y='1' width='1' height='1' fill='${light}'/>
+</svg>`;
+    return `data:image/svg+xml;base64,${btoa(svg)}`;
+}
+
+// A light-square label gets c.labelLight, a dark-square label gets
+// c.labelDark. class + type + type + :nth-child, matched on all four
+// orientation/parity combinations, carries the specificity needed to
+// override chess/board.css's own default coord-label rule (see the comment there
+// for why .coord-light/.coord-dark aren't used) regardless of source
+// order. For white orientation the odd nth-child positions land on the
+// a-file's dark squares (a1/a3/a5/a7, per chess/board.css's comment) and so take
+// c.labelDark; the even positions (a2/a4/a6/a8, light squares) take
+// c.labelLight. No text-shadow: the label colour itself carries enough
+// contrast against its own square.
+function _coordLabelCss(c) {
+    return `.orientation-white coords.ranks coord:nth-child(odd),
+.orientation-white coords.files coord:nth-child(odd) { color: ${c.labelDark} !important; }
+.orientation-white coords.ranks coord:nth-child(even),
+.orientation-white coords.files coord:nth-child(even) { color: ${c.labelLight} !important; }
+.orientation-black coords.ranks coord:nth-child(odd),
+.orientation-black coords.files coord:nth-child(odd) { color: ${c.labelLight} !important; }
+.orientation-black coords.ranks coord:nth-child(even),
+.orientation-black coords.files coord:nth-child(even) { color: ${c.labelDark} !important; }`;
+}
+
+function _cssForBoard(c) {
+    return `/* chesstb-theme: ${c.id} */
+cg-board {
+    background-image: url("${_checkerboardDataUri(c.lightSquare, c.darkSquare)}");
+    /* _checkerboardDataUri() returns a 2x2 tile (2 squares per axis).
+       25% 25% sizes it to 2/8 of the board per axis, so the tile repeats
+       4x4 (background-repeat's default) to fill all 64 squares; matches
+       the base checkerboard sizing in chess/board.css. */
+    background-size: 25% 25%;
+}
+${_coordLabelCss(c)}
+cg-board square.last-move { background-color: ${c.highlight} !important; }`;
+}
+
+function _applyCSS() {
+    let tag = document.getElementById('chesstb-theme');
+    if (!tag) {
+        tag = document.createElement('style');
+        tag.id = 'chesstb-theme';
+        document.head.appendChild(tag);
+    }
+    tag.textContent = `@layer app {\n${_cssForBoard(_boardColors())}\n}`;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Register the board reconstruction callback from board.js.
+ * Must be called before Board.init().
+ */
+function init(reconstructBoard) {
+    _reconstructBoard = reconstructBoard;
+}
+
+/**
+ * Inject the board's theme <style> tag and populate the piece-set-dependent
+ * tray/promotion images.
+ */
+function apply() {
+    _applyCSS();
+    if (_reconstructBoard) _reconstructBoard();
+}
+
+/** Return the active piece set id string. */
+function currentPieceSet() { return PIECE_SET; }
+
+// Built once - pieceThemeFn() below always returns this same function,
+// rather than allocating a fresh closure per call.
+function _pieceThemePath(piece) {
+    return `/static/pieces/${PIECE_SET}/${piece}.svg`;
+}
+
+/**
+ * Return the piece-code → image-path function for the active piece set
+ * (e.g. 'wQ' -> '/static/pieces/cburnett/wQ.svg'). Called by board.js to
+ * populate the spare-tray and promotion-dialog images.
+ */
+function pieceThemeFn() {
+    return _pieceThemePath;
+}
+
+export const Theme = {
+    init, apply,
+    currentPieceSet,
+    pieceThemeFn,
+};

frontend/src/engine/utils.js

@@ -0,0 +1,22 @@
+/**
+ * utils.js: Shared helpers
+ */
+
+/**
+ * Returns a debounced version of fn that fires after `delay` ms of inactivity.
+ * The returned function also exposes cancel(), so a caller that's about to
+ * issue an equivalent call immediately (bypassing the debounce) can drop any
+ * pending trailing call instead of leaving it to fire later against a
+ * position that's no longer current.
+ * @param {Function} fn
+ * @param {number} delay
+ */
+export function debounce(fn, delay) {
+    let timer;
+    const debounced = function (...args) {
+        clearTimeout(timer);
+        timer = setTimeout(() => fn.apply(this, args), delay);
+    };
+    debounced.cancel = () => clearTimeout(timer);
+    return debounced;
+}

frontend/src/hooks/useExplorer.js

@@ -0,0 +1,491 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Board, VARIANTS } from '../engine/board.js';
+import { Tablebase } from '../engine/tablebase.js';
+import { Theme } from '../engine/theme.js';
+import * as Storage from '../engine/storage.js';
+import { debounce } from '../engine/utils.js';
+import {
+    writeHash, readHashFen, readHashVariant, readLastGame, saveGameState, normalizeFen,
+} from '../engine/gameState.js';
+import { buildPgnText, parsePgn } from '../engine/pgnFormat.js';
+
+const DEFAULT_FEN = '4k3/8/8/8/8/8/8/4K2R w - - 0 1';
+
+const METRIC_CONFIG = {
+    dtz:   { dataKey: 'moves_dtz',   label: 'DTZ'   },
+    dtc:   { dataKey: 'moves_dtc',   label: 'DTC'   },
+    dtm:   { dataKey: 'moves_dtm',   label: 'DTM'   },
+    dtm50: { dataKey: 'moves_dtm50', label: 'DTM50' },
+};
+const AUTO_PLAY_METRICS = Object.keys(METRIC_CONFIG);
+
+const AUTO_PLAY_DELAY_MIN_MS  = 0;
+const AUTO_PLAY_DELAY_MAX_MS  = 2500;
+const AUTO_PLAY_DELAY_STEP_MS = 50;
+const AUTO_PLAY_DELAY_DEFAULT_MS = 1250;
+const LS_AUTOPLAY_DELAY_MS = 'chesstb_autoplay_delay_ms';
+
+function clampAutoPlayDelayMs(ms) {
+    if (!Number.isFinite(ms)) return AUTO_PLAY_DELAY_DEFAULT_MS;
+    const snapped = Math.round(ms / AUTO_PLAY_DELAY_STEP_MS) * AUTO_PLAY_DELAY_STEP_MS;
+    return Math.min(AUTO_PLAY_DELAY_MAX_MS, Math.max(AUTO_PLAY_DELAY_MIN_MS, snapped));
+}
+function readAutoPlayDelayMs() {
+    const raw = Storage.read(LS_AUTOPLAY_DELAY_MS);
+    const ms = raw === null ? NaN : parseInt(raw, 10);
+    return Number.isFinite(ms) ? clampAutoPlayDelayMs(ms) : AUTO_PLAY_DELAY_DEFAULT_MS;
+}
+export function formatAutoPlayDelay(ms) {
+    return ms === 0 ? '0s' : `${parseFloat((ms / 1000).toFixed(2))}s`;
+}
+
+let _nextToastId = 1;
+const NOTE_MS = 4500;
+
+export function useExplorer() {
+    const [ready, setReady]     = useState(false);
+    const [fen, setFen]         = useState(DEFAULT_FEN);
+    const [variant, setVariant] = useState(VARIANTS.STANDARD);
+    const [locked, setLockedState] = useState(false);
+    const [canBack, setCanBack] = useState(false);
+    const [canForward, setCanForward] = useState(false);
+    const [moveHistory, setMoveHistory] = useState({ nodes: [], rootChildren: [], rootActiveChild: null, currentId: -1 });
+    const [startFen, setStartFen] = useState(DEFAULT_FEN);
+    // The PGN panel stays blank (not even "No moves yet") until Board
+    // reports a move-tree change for the first time - a fresh session
+    // with nothing restored from a link or localStorage never fires that
+    // callback until the player's first action.
+    const [historyInitialized, setHistoryInitialized] = useState(false);
+    const [fenError, setFenError] = useState(null);
+
+    const [tb, setTb] = useState(() => Tablebase.getViewState());
+    const [autoplayMetric, setAutoplayMetric] = useState(null);
+    const [autoplayAvailability, setAutoplayAvailability] = useState(
+        () => Object.fromEntries(AUTO_PLAY_METRICS.map(m => [m, { disabled: false, title: `Auto-play best ${METRIC_CONFIG[m].label} move` }]))
+    );
+    const [lockAutoplayDisabled, setLockAutoplayDisabled] = useState(false);
+
+    const [showRootRow, setShowRootRowState] = useState(() => Tablebase.getShowRootRow());
+    const [autoplayDelayMs, setAutoplayDelayMsState] = useState(() => readAutoPlayDelayMs());
+
+    const [settingsOpen, setSettingsOpen] = useState(false);
+    const [pgnDialogOpen, setPgnDialogOpen] = useState(false);
+    const [pgnError, setPgnError] = useState('');
+    const [toasts, setToasts] = useState([]);
+    const [activeMetric, setActiveMetric] = useState('dtz');
+
+    const fenInputRef = useRef(null);
+    const tbodyRef    = useRef(null);
+    const actionsRef  = useRef({});
+    const bootedRef   = useRef(false);
+
+    // ── Toasts ──────────────────────────────────────────────────────────
+    function toast(message, durationMs = 1800) {
+        const id = _nextToastId++;
+        setToasts(prev => [...prev, { id, message, leaving: false }]);
+        setTimeout(() => {
+            setToasts(prev => prev.map(t => (t.id === id ? { ...t, leaving: true } : t)));
+            setTimeout(() => setToasts(prev => prev.filter(t => t.id !== id)), 400);
+        }, durationMs);
+    }
+
+    const activeNotesRef = useRef(new Set());
+
+    // ── One-time bootstrap ────────────────────────────────────────────────
+    useEffect(() => {
+        if (bootedRef.current) return;
+        bootedRef.current = true;
+
+        const hashFen     = readHashFen();
+        const hashVariant = readHashVariant();
+        const lastGame    = readLastGame();
+
+        let initialFen, initialVariant, restoreGame;
+        if (lastGame && hashFen &&
+            normalizeFen(hashFen) === lastGame.currentFen &&
+            (hashVariant || VARIANTS.STANDARD) === lastGame.variant) {
+            initialFen = normalizeFen(lastGame.startFen);
+            initialVariant = lastGame.variant;
+            restoreGame = lastGame;
+        } else if (hashFen) {
+            initialFen = normalizeFen(hashFen);
+            initialVariant = hashVariant || VARIANTS.STANDARD;
+            restoreGame = null;
+        } else if (lastGame) {
+            initialFen = normalizeFen(lastGame.startFen);
+            initialVariant = lastGame.variant;
+            restoreGame = lastGame;
+        } else {
+            initialFen = DEFAULT_FEN;
+            initialVariant = VARIANTS.STANDARD;
+            restoreGame = null;
+        }
+
+        const debouncedProbe = debounce(Tablebase.probe, 300);
+
+        // ── Auto-play state (refs - pure bookkeeping, no re-render needed) ──
+        const autoPlayTimerRef = { current: null };
+        const autoPlayCycleIdRef = { current: 0 };
+        const autoPlayPacingReadyRef = { current: false };
+        const autoPlayDataReadyRef = { current: false };
+        const autoPlayMoveInFlightRef = { current: false };
+        const autoPlayLockEngagedRef = { current: false };
+        const autoPlayMetricRef = { current: null };   // mirrors autoplayMetric state for synchronous checks
+
+        function bestMovesForArrows(data) {
+            return {
+                dtz:   data?.dtz_available   ? (data.moves_dtz   || [])[0] || null : null,
+                dtc:   data?.dtc_available   ? (data.moves_dtc   || [])[0] || null : null,
+                dtm:   data?.dtm_available   ? (data.moves_dtm   || [])[0] || null : null,
+                dtm50: data?.dtm50_available ? (data.moves_dtm50 || [])[0] || null : null,
+            };
+        }
+
+        function applySetLocked(next, persist = true) {
+            Board.setLocked(next, persist);
+            setLockedState(next);
+        }
+
+        function stopAutoPlay() {
+            const prevMetric = autoPlayMetricRef.current;
+            autoPlayMetricRef.current = null;
+            setAutoplayMetric(null);
+            autoPlayCycleIdRef.current++;
+            clearTimeout(autoPlayTimerRef.current);
+            autoPlayTimerRef.current = null;
+            autoPlayPacingReadyRef.current = false;
+            autoPlayDataReadyRef.current = false;
+            if (autoPlayLockEngagedRef.current) {
+                autoPlayLockEngagedRef.current = false;
+                applySetLocked(false, false);
+            }
+            setLockAutoplayDisabled(false);
+            return prevMetric;
+        }
+
+        function armAutoPlayWait(dataAlreadyReady) {
+            const cycleId = ++autoPlayCycleIdRef.current;
+            autoPlayPacingReadyRef.current = false;
+            autoPlayDataReadyRef.current = dataAlreadyReady;
+            clearTimeout(autoPlayTimerRef.current);
+            autoPlayTimerRef.current = null;
+            if (!dataAlreadyReady) return;
+            autoPlayTimerRef.current = setTimeout(() => {
+                if (cycleId !== autoPlayCycleIdRef.current) return;
+                autoPlayPacingReadyRef.current = true;
+                tryPlayAutoPlayMove(cycleId);
+            }, actionsRef.current.getAutoplayDelayMs());
+        }
+
+        function tryPlayAutoPlayMove(cycleId) {
+            if (cycleId !== autoPlayCycleIdRef.current) return;
+            if (!autoPlayMetricRef.current) return;
+            if (!autoPlayPacingReadyRef.current || !autoPlayDataReadyRef.current) return;
+
+            const metric = autoPlayMetricRef.current;
+            const data = Tablebase.getLastData();
+            if (!data) return;
+            const moves = data[METRIC_CONFIG[metric].dataKey] || [];
+            const best = moves.find(m => m.outcome !== 'unknown' && m.available !== false);
+            if (!best) { stopAutoPlay(); return; }
+            autoPlayMoveInFlightRef.current = true;
+            const played = Board.playMove(best.san);
+            autoPlayMoveInFlightRef.current = false;
+            if (!played) { stopAutoPlay(); return; }
+            if (best.is_mate || best.outcome === 'draw') { stopAutoPlay(); return; }
+            armAutoPlayWait(false);
+        }
+
+        function onAutoPlayResult() {
+            if (!autoPlayMetricRef.current || autoPlayDataReadyRef.current) return;
+            armAutoPlayWait(true);
+        }
+
+        function startAutoPlay(metric) {
+            if (!METRIC_CONFIG[metric]) return;
+            stopAutoPlay();
+            autoPlayMetricRef.current = metric;
+            setAutoplayMetric(metric);
+            if (!Board.isLocked()) {
+                autoPlayLockEngagedRef.current = true;
+                applySetLocked(true, false);
+            }
+            setLockAutoplayDisabled(true);
+            const dataAlreadyReady = Tablebase.getLastFen() === Board.currentFen() &&
+                                      Tablebase.getLastVariant() === Board.getVariant();
+            armAutoPlayWait(dataAlreadyReady);
+        }
+
+        function updateAutoplayAvailability(data) {
+            const availableByMetric = {
+                dtz: data?.dtz_available, dtc: data?.dtc_available,
+                dtm: data?.dtm_available, dtm50: data?.dtm50_available,
+            };
+            const rootWdlByMetric = {
+                dtz: data?.wdl,
+                dtc: Array.isArray(data?.dtc) ? data.dtc[0] : null,
+                dtm: data?.wdl,
+                dtm50: Array.isArray(data?.dtm50) ? data.dtm50[0] : null,
+            };
+            const next = {};
+            AUTO_PLAY_METRICS.forEach(metric => {
+                const unavailable = availableByMetric[metric] === false;
+                const isDraw = !unavailable && rootWdlByMetric[metric] === 0;
+                if (unavailable || isDraw) {
+                    if (autoPlayMetricRef.current === metric) stopAutoPlay();
+                    next[metric] = {
+                        disabled: true,
+                        title: unavailable
+                            ? `Auto-play unavailable — no ${METRIC_CONFIG[metric].label} table for this material`
+                            : `${METRIC_CONFIG[metric].label} auto-play unavailable — position is a draw`,
+                    };
+                } else {
+                    next[metric] = { disabled: false, title: `Auto-play best ${METRIC_CONFIG[metric].label} move` };
+                }
+            });
+            setAutoplayAvailability(next);
+        }
+
+        // ── Position-change callback ────────────────────────────────────
+        function onPositionChange(nextFen, immediate) {
+            if (autoPlayMetricRef.current && !autoPlayMoveInFlightRef.current) stopAutoPlay();
+
+            if (fenInputRef.current) {
+                fenInputRef.current.value = nextFen;
+                fenInputRef.current.classList.remove('is-invalid');
+            }
+            setFenError(null);
+            Tablebase.clearErrorLine();
+            setFen(nextFen);
+            setVariant(Board.getVariant());
+            setCanBack(Board.canGoBack());
+            setCanForward(Board.canGoForward());
+            writeHash(nextFen, Board.getVariant());
+            Board.clearArrows();
+
+            const count = Board.isInsufficientMaterial() ? 0 : Board.legalMoveCount();
+            Tablebase.setMoveCount(count > 0 ? `${count} legal move${count === 1 ? '' : 's'}` : '');
+
+            const onProbeError = () => setReady(true);
+            const activeVariant = Board.getVariant();
+            if (immediate) {
+                debouncedProbe.cancel();
+                Tablebase.probe(nextFen, activeVariant, onProbeError);
+            } else {
+                debouncedProbe(nextFen, activeVariant, onProbeError);
+            }
+        }
+
+        Board.setOnMoveHistoryChange((history, sFen) => {
+            setMoveHistory(history);
+            setStartFen(sFen);
+            setHistoryInitialized(true);
+            setCanBack(Board.canGoBack());
+            setCanForward(Board.canGoForward());
+            saveGameState(history, sFen, Board.getVariant());
+        });
+
+        Tablebase.setResultHandler(data => {
+            Board.drawArrows(bestMovesForArrows(data));
+            updateAutoplayAvailability(data);
+            setReady(true);
+        });
+        Tablebase.setMoveSelectHandler(san => {
+            const played = Board.playMove(san);
+            if (!played) toast('Illegal move — this position may have changed.');
+        });
+        Tablebase.setNoteHandler(message => {
+            const active = activeNotesRef.current;
+            if (active.has(message)) return;
+            active.add(message);
+            setTimeout(() => active.delete(message), NOTE_MS + 400);
+            toast(message, NOTE_MS);
+        });
+        Tablebase.setViewStateHandler(setTb);
+
+        // ── Board bootstrap ──────────────────────────────────────────────
+        Theme.init(Board.reconstruct);
+        setReady(false);
+        const boardInit = Board.init(onPositionChange, initialFen, initialVariant);
+        if (!boardInit.ok) toast(boardInit.reason || 'Invalid starting position — loaded the default position instead.');
+        if (restoreGame) {
+            Board.restoreTree(restoreGame.startFen, restoreGame.nodes, restoreGame.rootChildren, restoreGame.rootActiveChild, restoreGame.currentId);
+        }
+        Theme.apply();
+
+        setVariant(Board.getVariant());
+        setLockedState(Board.isLocked());
+        setFen(Board.currentFen());
+        setStartFen(Board.getStartFen());
+        setCanBack(Board.canGoBack());
+        setCanForward(Board.canGoForward());
+        if (fenInputRef.current) fenInputRef.current.value = Board.currentFen();
+
+        // ── Public actions ───────────────────────────────────────────────
+        function applyFen(rawFen) {
+            const norm = normalizeFen(rawFen);
+            const result = Board.setPosition(norm);
+            if (!result.ok) {
+                if (fenInputRef.current) fenInputRef.current.classList.add('is-invalid');
+                setFenError(result.reason || 'Invalid position.');
+                return;
+            }
+            if (fenInputRef.current) fenInputRef.current.classList.remove('is-invalid');
+            setFenError(null);
+            Tablebase.clearErrorLine();
+        }
+
+        function setTurn(turnChar) {
+            const parts = Board.currentFen().split(' ');
+            if (parts[1] === turnChar) return;
+            parts[1] = turnChar;
+            applyFen(parts.join(' '));
+        }
+
+        function copyFen() {
+            navigator.clipboard.writeText(Board.currentFen())
+                .then(() => toast('FEN copied!'))
+                .catch(() => {
+                    fenInputRef.current?.select();
+                    document.execCommand('copy');
+                    toast('FEN copied!');
+                });
+        }
+
+        function exportPgn() {
+            const text = buildPgnText();
+            if (!text) { toast('Play a move to export a PGN.'); return; }
+            const url = URL.createObjectURL(new Blob([text + '\n'], { type: 'application/x-chess-pgn;charset=utf-8' }));
+            const link = document.createElement('a');
+            link.href = url;
+            link.download = 'chesstb_game.pgn';
+            document.body.appendChild(link);
+            link.click();
+            link.remove();
+            setTimeout(() => URL.revokeObjectURL(url), 1000);
+        }
+
+        function flip() {
+            Board.flip();
+            Board.drawArrows(bestMovesForArrows(Tablebase.getLastData()));
+        }
+
+        function clearBoard() { Board.clear(); }
+        function goBack() { Board.goBack(); }
+        function goForward() { Board.goForward(); }
+        function goToNode(id) { Board.goToNode(id); }
+
+        function setLockedAction(next) {
+            if (autoPlayMetricRef.current !== null) return;   // soft-disabled during auto-play
+            applySetLocked(next);
+        }
+
+        function toggleAutoPlay(metric) {
+            if (autoPlayMetricRef.current === metric) stopAutoPlay();
+            else startAutoPlay(metric);
+        }
+
+        function setShowRootRowAction(next) { Tablebase.setShowRootRow(next); setShowRootRowState(next); }
+
+        function setChess960Action(next) {
+            const result = Board.setVariant(next ? VARIANTS.CHESS960 : VARIANTS.STANDARD);
+            if (!result.ok) { toast(result.reason || "Can't switch modes for this position.", 3000); return; }
+            setVariant(Board.getVariant());
+        }
+
+        function setAutoplayDelayAction(ms) {
+            const clamped = clampAutoPlayDelayMs(ms);
+            Storage.write(LS_AUTOPLAY_DELAY_MS, clamped);
+            setAutoplayDelayMsState(clamped);
+        }
+        function getAutoplayDelayMs() { return actionsRef.current.autoplayDelayMsLive; }
+
+        function openPgnDialog() { setPgnDialogOpen(true); setPgnError(''); }
+        function closePgnDialog() { setPgnDialogOpen(false); }
+        function parsePgnAction(text) {
+            const result = parsePgn(text);
+            if (!result.ok) { setPgnError(result.error); return; }
+            const loaded = Board.importGame(result.tree, result.variant);
+            if (!loaded.ok) { setPgnError(loaded.reason); return; }
+            setPgnError('');
+            closePgnDialog();
+        }
+
+        // Exposed to components via the stable actionsRef object.
+        Object.assign(actionsRef.current, {
+            applyFen, setTurn, copyFen, exportPgn, flip, clearBoard, goBack, goForward, goToNode,
+            setLockedAction, toggleAutoPlay, setShowRootRowAction, setChess960Action,
+            setAutoplayDelayAction, getAutoplayDelayMs, onAutoPlayResult, openPgnDialog, closePgnDialog,
+            parsePgnAction, toast, setActiveMetric,
+            exportCsv: Tablebase.exportCsv,
+            autoplayDelayMsLive: readAutoPlayDelayMs(),
+        });
+
+        // Very first probe of the session runs immediately (no debounce).
+        onPositionChange(Board.currentFen(), true);
+    }, []);
+
+    // Wait for the results to commit and paint before starting the delay.
+    // Two frames also let a zero-delay run show each position's results.
+    useEffect(() => {
+        if (!autoplayMetric || tb.loading) return;
+        let frame = requestAnimationFrame(() => {
+            frame = requestAnimationFrame(() => actionsRef.current.onAutoPlayResult());
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [tb, autoplayMetric]);
+
+    // Keep the ref mirror of autoplayDelayMs current for armAutoPlayWait's
+    // synchronous read (it can't see React state directly from inside a
+    // closure captured once at bootstrap).
+    useEffect(() => {
+        actionsRef.current.autoplayDelayMsLive = autoplayDelayMs;
+    }, [autoplayDelayMs]);
+
+    // ── Keyboard shortcuts ───────────���──────────────────────────────────
+    useEffect(() => {
+        function onKeydown(e) {
+            const tag = document.activeElement?.tagName;
+            if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+            if (document.activeElement?.isContentEditable) return;
+            if (document.getElementById('promotion-dialog')?.classList.contains('is-visible')) return;
+            if (pgnDialogOpen) return;
+            if (settingsOpen) return;
+
+            if (e.key === 'ArrowLeft' && !e.shiftKey && !e.ctrlKey && !e.metaKey) { e.preventDefault(); actionsRef.current.goBack(); }
+            if (e.key === 'ArrowRight' && !e.shiftKey && !e.ctrlKey && !e.metaKey) { e.preventDefault(); actionsRef.current.goForward(); }
+            if (e.key.toLowerCase() === 'f' && !e.ctrlKey && !e.metaKey) { e.preventDefault(); actionsRef.current.flip(); }
+            if (e.key.toLowerCase() === 'c' && !e.ctrlKey && !e.metaKey) { e.preventDefault(); actionsRef.current.clearBoard(); }
+        }
+        document.addEventListener('keydown', onKeydown);
+        return () => document.removeEventListener('keydown', onKeydown);
+    }, [pgnDialogOpen, settingsOpen]);
+
+    // ── hashchange (shared links opened while the tab is open) ───────────
+    useEffect(() => {
+        function onHashChange() {
+            const newFen = readHashFen();
+            if (!newFen) return;
+            const newVariant = readHashVariant() || VARIANTS.STANDARD;
+            const result = Board.setPositionAndVariant(normalizeFen(newFen), newVariant);
+            if (!result.ok) {
+                actionsRef.current.toast(result.reason || 'Invalid position in URL.');
+                writeHash(Board.currentFen(), Board.getVariant());
+            }
+        }
+        window.addEventListener('hashchange', onHashChange);
+        return () => window.removeEventListener('hashchange', onHashChange);
+    }, []);
+
+    const actions = useMemo(() => new Proxy({}, {
+        get: (_t, prop) => (...args) => actionsRef.current[prop]?.(...args),
+    }), []);
+
+    return {
+        ready, fen, variant, locked, canBack, canForward, moveHistory, startFen, historyInitialized, fenError,
+        tb, autoplayMetric, autoplayAvailability, lockAutoplayDisabled,
+        showRootRow, autoplayDelayMs, settingsOpen, setSettingsOpen,
+        pgnDialogOpen, pgnError, toasts, activeMetric,
+        fenInputRef, tbodyRef, actions,
+    };
+}

frontend/src/main.jsx

@@ -0,0 +1,8 @@
+import './styles/index.css';
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+
+const rootEl = document.getElementById('root');
+const sourceRepositoryUrl = rootEl?.dataset.sourceRepositoryUrl || '';
+
+createRoot(rootEl).render(<App sourceRepositoryUrl={sourceRepositoryUrl} />);

frontend/src/styles/admin-page.css

@@ -0,0 +1,158 @@
+/* ── Admin page ────────────────────────────────────────────────────────
+   The dashboard is an ordinary scrolling document. Selectors are scoped
+   under `.admin-page` on the page's <body>. */
+
+body.admin-page {
+    height: auto;
+    min-height: 100vh;
+    overflow: auto;
+    padding: var(--space-6);
+}
+
+.admin-page h1 {
+    font-size: var(--text-xl);
+    color: var(--text);
+    margin-bottom: var(--space-5);
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+/* Colour and hover come from the global `a` rule in base.css. Targeted by
+   class rather than `h1 a` because h1 may also hold the GitHub icon
+   button (site-header__link--icon). */
+.admin-page__back-link { font-size: var(--text-sm); margin-left: auto; }
+
+/* Card-section labels, sized to match the app's other panel-title rows
+   (`.pgn-panel-title`, `.panel-header__title`) rather than a one-off
+   value. */
+.admin-page h2 {
+    font-size: var(--text-xs);
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--text-muted);
+    margin-bottom: var(--space-3);
+}
+
+.admin-page .grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: var(--space-4);
+    margin-bottom: var(--space-4);
+}
+
+/* Same background/border/radius recipe as `.pgn-panel` / `.results-panel`. */
+.admin-page .card {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--r-lg);
+    padding: 20px;
+}
+
+.admin-page .stat {
+    display: flex;
+    justify-content: space-between;
+    padding: 6px 0;
+    border-bottom: 1px solid var(--border);
+    font-size: var(--text-sm);
+}
+.admin-page .stat:last-child { border-bottom: none; }
+.admin-page .stat .label { color: var(--text-dim); }
+.admin-page .stat .value {
+    color: var(--text);
+    font-variant-numeric: tabular-nums;
+    font-family: var(--font-mono);
+}
+
+.admin-page .bar-wrap {
+    height: 8px;
+    background: var(--border);
+    border-radius: 4px;
+    overflow: hidden;
+    margin: var(--space-2) 0 var(--space-3);
+}
+/* Same gradient as the results panel's `.probe-progress__fill`. */
+.admin-page .bar-fill {
+    height: 100%;
+    background: linear-gradient(90deg, var(--progress-from), var(--progress-to));
+    border-radius: 4px;
+    transition: width 0.4s;
+}
+
+.admin-page .toolbar-row {
+    display: flex;
+    gap: var(--space-2);
+    margin-bottom: 20px;
+}
+
+/* Destructive-action modifier for the shared `.btn` component (the
+   Refresh button next to it needs no modifier - plain `.btn` already
+   matches). Follows the same pattern as `.btn--apply`'s gold accent,
+   using the `--loss-glow` token for the hover fill. */
+.admin-page .btn.danger { border-color: var(--loss); color: var(--loss); }
+.admin-page .btn.danger:hover { background: var(--loss-glow); border-color: var(--loss); }
+
+.admin-page .status {
+    font-size: var(--text-xs);
+    color: var(--text-muted);
+    margin-top: 10px;
+    min-height: 18px;
+}
+.admin-page .status.ok  { color: var(--win); }
+.admin-page .status.err { color: var(--loss); }
+
+.admin-page .refresh-row {
+    display: flex;
+    align-items: center;
+    gap: var(--space-3);
+    margin-bottom: 20px;
+    font-size: var(--text-xs);
+    color: var(--text-muted);
+}
+
+/* Login card for GET /admin without a valid session. Centered fixed-width
+   panel; reuses `.card`'s background, border and radius. */
+.admin-page .login-card {
+    max-width: 320px;
+    margin: 15vh auto 0;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--r-lg);
+    padding: 28px;
+    text-align: center;
+}
+.admin-page .login-card h1 { justify-content: center; margin-bottom: var(--space-2); }
+.admin-page .login-card__hint {
+    font-size: var(--text-xs);
+    color: var(--text-muted);
+    margin-bottom: var(--space-4);
+}
+.admin-page .login-card__back { display: block; margin-top: var(--space-4); font-size: var(--text-sm); }
+
+/* Same recipe as FenBar.jsx's `.fen-input`, minus the icon padding;
+   this field has no leading icon. */
+.admin-page .login-input {
+    width: 100%;
+    height: 34px;
+    padding: 0 10px;
+    margin-bottom: var(--space-3);
+    font-family: var(--font-mono);
+    font-size: var(--text-xs);
+    color: var(--text);
+    background: var(--surface-2);
+    border: 1px solid var(--border);
+    border-radius: var(--r-md);
+    outline: none;
+    text-align: center;
+    transition: border-color var(--tr), box-shadow var(--tr);
+}
+.admin-page .login-input:focus { border-color: var(--gold-dim); box-shadow: 0 0 0 2px var(--gold-glow); }
+
+@media (max-width: 640px) {
+    .admin-page .grid { grid-template-columns: 1fr; }
+}
+::-webkit-scrollbar-thumb:hover { background: var(--text-muted); }
+
+@media (hover: none) and (pointer: coarse) {
+    .admin-page .login-input { font-size: var(--text-lg); }
+}

frontend/src/styles/admin.css

@@ -0,0 +1,8 @@
+@layer reset, vendor, app;
+@import "./reset.css" layer(reset);
+@import "./fonts.css";
+@import "./tokens.css" layer(app);
+@import "./base.css" layer(app);
+@import "./components/button.css" layer(app);
+@import "./components/header.css" layer(app);
+@import "./admin-page.css" layer(app);

frontend/src/styles/base.css

@@ -0,0 +1,44 @@
+/* Reading-text baseline: the browser's default font size. Layout sizing
+   (e.g. --board-size above) responds to the viewport separately. */
+html { font-size: 100%; }
+
+/* Body fills the viewport height at minimum and scrolls if its content
+   ever needs more room than that. */
+html, body { height: 100%; }
+body {
+    min-height: 100%;
+    overflow-y: auto;
+    overflow-x: hidden;
+    font-family: var(--font-ui);
+    font-size: var(--text-lg);
+    line-height: 1.5;
+    background: var(--bg);
+    color: var(--text);
+    -webkit-font-smoothing: antialiased;
+}
+
+button { cursor: pointer; font: inherit; touch-action: manipulation; }
+a      { color: var(--text-dim); text-decoration: none; }
+a:hover { color: var(--text); }
+:focus-visible { outline: 2px solid var(--gold); outline-offset: 2px; }
+
+/* Suppress the tap flash Android/iOS draw on touch, and the ~300ms
+   delay before a tap registers as a click, on every interactive
+   control. touch-action: manipulation still allows scrolling - only
+   double-tap-to-zoom is disabled. */
+button, .btn, a { -webkit-tap-highlight-color: transparent; }
+
+/* ── Screen-reader utility ──────────────────────────────────────────── */
+.sr-only {
+    position: absolute; width: 0.0625rem; height: 0.0625rem;
+    padding: 0; margin: -0.0625rem; overflow: hidden;
+    clip: rect(0,0,0,0); white-space: nowrap; border: 0;
+}
+
+/* ── Scrollbars ─────────────────────────────────────────────────────── */
+* { scrollbar-width: thin; scrollbar-color: var(--border-2) transparent; }
+::-webkit-scrollbar       { width: 0.375rem; height: 0.375rem; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--border-2); border-radius: 0.1875rem; }
+
+.icon { width: 1rem; height: 1rem; flex-shrink: 0; }

frontend/src/styles/chess/board.css

@@ -0,0 +1,245 @@
+/* ── Board group ────────────────────────────────────────────────────── */
+/* Keep the side-to-move toggle and board directly below the FEN controls. */
+.board-group {
+    margin-top: 0;
+    width: var(--board-size);
+    flex-shrink: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.375rem;
+}
+
+/* ── Board wrap ─────────────────────────────────────────────────────── */
+.board-wrap {
+    border-radius: var(--r-md);
+    overflow: hidden;
+    box-shadow: var(--shadow-board);
+    width: var(--board-size);
+    flex-shrink: 0;
+}
+.board-wrap-inner {
+    position: relative;
+    width: var(--board-size);
+    display: flex;
+    flex-direction: column;
+}
+/* Set by board.js's _syncTrayOrientation() to mirror chessground's own
+   orientation. column-reverse visually swaps the black/white trays around
+   #board without moving them in the DOM. */
+.board-wrap-inner.orientation-black {
+    flex-direction: column-reverse;
+}
+
+/* ── Chessground sizing ─────────────────────────────────────────────── */
+/* Chessground's own CSS (chessground.base.css) sizes cg-wrap/cg-board/
+   piece/square as percentages of their container. #board is the
+   percentage-sizing root; height is set explicitly here since chessground
+   doesn't compute it from width in JS. Both dimensions come from the
+   shared --board-size custom property (see tokens.css), so the board resizes
+   together with .left-col/.board-wrap/.board-wrap-inner/.spare-tray
+   without drifting out of alignment with them.
+
+   Chessground has its own rounding step one DOM layer deeper: render.ts's
+   updateBounds() reads #board's rendered width, then deliberately snaps
+   cg-container's width down to a whole number of device pixels evenly
+   divisible by 8 (so all 8 squares render crisply, with no anti-aliased
+   sub-pixel square boundaries),
+   `Math.floor((bounds.width * devicePixelRatio) / 8) * 8 / devicePixelRatio`,
+   and sets that as an inline style on cg-container. At integer device
+   pixel ratios (1x, 2x) this is a no-op whenever #board's current rendered
+   width happens to divide evenly by 8, but at fractional ratios (1.5x is
+   common on Windows displays) it usually doesn't: at --board-size's
+   ceiling (31.5rem = 504px), 504 * 1.5 = 756, 756 / 8 = 94.5,
+   floor'd to 94 * 8 = 752, back to 752 / 1.5 ≈ 501.3px - about 2.7px short
+   of #board's actual width on the right/bottom edge. Squares/pieces are
+   plain CSS percentages with no JS-computed inline style of their own, so
+   pinning cg-container's own width and height with !important (overriding
+   chessground's inline style) to the same --board-size as #board is
+   enough to keep the whole board exact and stable regardless of device
+   pixel ratio or the current viewport size. */
+#board {
+    width: var(--board-size);
+    height: var(--board-size);
+}
+cg-container, cg-board {
+    width: var(--board-size) !important;
+    height: var(--board-size) !important;
+}
+
+/* ── Board square colours - Lichess brown ───────────────────────────── */
+/* Fallback board colours. theme.js overrides these values after the board
+   is initialized, while the defaults prevent an unthemed initial render. */
+cg-board {
+    background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPScyJyBoZWlnaHQ9JzInPgo8cmVjdCB3aWR0aD0nMScgaGVpZ2h0PScxJyBmaWxsPScjZjBkOWI1Jy8+CjxyZWN0IHg9JzEnIHdpZHRoPScxJyBoZWlnaHQ9JzEnIGZpbGw9JyNiNTg4NjMnLz4KPHJlY3QgeT0nMScgd2lkdGg9JzEnIGhlaWdodD0nMScgZmlsbD0nI2I1ODg2MycvPgo8cmVjdCB4PScxJyB5PScxJyB3aWR0aD0nMScgaGVpZ2h0PScxJyBmaWxsPScjZjBkOWI1Jy8+Cjwvc3ZnPg==");
+    /* The SVG above is a 2x2 tile (2 squares per axis). 25% 25% sizes it
+       to 2/8 of the board per axis, so the tile repeats 4x4
+       (background-repeat's default) to fill all 64 squares. */
+    background-size: 25% 25%;
+}
+/* ── Rank/file coordinate labels - inset onto board edges ─────────── */
+/* board.js sets coordinatesOnSquares: false, which uses chessground's
+   native coords.ranks/coords.files strips - one rank-only label per row,
+   one file-only label per column - rather than a combined "a8"-style
+   label rendered on all 64 squares. Chessground positions these outside
+   the board by default (which .board-wrap's overflow:hidden would clip
+   anyway), so they're repositioned here to sit inset at the board's own
+   edges, at a small (0.125rem) corner inset.
+
+   Colour is not done via renderCoords()'s own .coord-light/.coord-dark
+   classes (chessground's source, wrap.ts): those classes don't
+   correspond to the actual square each label overlays once repositioned
+   this way, and chessground's own official theme CSS
+   (chessground.brown.css) doesn't use them for coords.ranks/coords.files
+   either - it uses structural :nth-child selectors scoped by an
+   .orientation-white/.orientation-black class on the wrap element
+   instead (that class exists for lichess's own outside-the-board label
+   rhythm, not square-accurate contrast, so its odd/even color pairing
+   isn't reusable here - only the selector structure is). ranks/files are fixed
+   DOM arrays ['1'..'8']/['a'..'h'] (types.ts), so :nth-child parity is
+   deterministic; the odd/even -> colour mapping below follows the board
+   square colours (a1 dark, a8 light, etc.) for each orientation rather than
+   chessground's coordinate colour convention. */
+.orientation-white coords.ranks coord:nth-child(odd),
+.orientation-white coords.files coord:nth-child(odd) {
+    color: var(--board-light) !important;   /* light text - these sit on dark squares */
+}
+.orientation-white coords.ranks coord:nth-child(even),
+.orientation-white coords.files coord:nth-child(even) {
+    color: var(--board-dark) !important;   /* dark text - these sit on light squares */
+}
+.orientation-black coords.ranks coord:nth-child(odd),
+.orientation-black coords.files coord:nth-child(odd) {
+    color: var(--board-dark) !important;   /* flipped board: parity-to-square-colour swaps */
+}
+.orientation-black coords.ranks coord:nth-child(even),
+.orientation-black coords.files coord:nth-child(even) {
+    color: var(--board-light) !important;
+}
+coords.ranks coord, coords.files coord {
+    font-size: max(0.5625rem, calc(var(--board-size) / 56)) !important;
+    font-weight: 600 !important;
+    font-family: var(--font-ui) !important;
+}
+.cg-wrap coords.ranks {
+    left: 0 !important;
+    top: 0 !important;
+    width: max(0.875rem, calc(var(--board-size) / 38)) !important;
+    height: 100% !important;
+    padding-left: 0.125rem !important;   /* safe on this axis: one 0.875rem-wide column, not tiled horizontally */
+    opacity: 1 !important;
+}
+.cg-wrap coords.ranks coord {
+    transform: none !important;
+    /* Chessground's own coord rule is `flex: 1 1 auto` - each cell's
+       basis comes from its own glyph's content width/height, so 8 cells
+       sharing the board's row/column don't land on exact one-square (1/8)
+       multiples; the shortfall accumulates top-to-bottom (or left-to-right
+       for files), and since labels are aligned within their own cell, that
+       accumulating error reads as the label drifting further from the
+       square's true edge the further along the row/column it is (barely
+       visible at '1'/'2', a couple of px off by '8'). flex:0 0 12.5% pins
+       every cell to exactly one square-width (12.5% of the board)
+       regardless of its glyph's own size, eliminating that drift.
+       The corner inset itself is deliberately per-cell padding (below),
+       not container padding: padding on the container would shrink the
+       width available for the 8 tiled cells, so flex:0 0 12.5% would land
+       on smaller, still-uneven cells instead of a true one-eighth each. */
+    flex: 0 0 12.5% !important;
+    padding-top: 0.125rem !important;
+}
+.cg-wrap coords.files {
+    left: 0 !important;
+    bottom: 0 !important;
+    width: 100% !important;
+    height: max(0.875rem, calc(var(--board-size) / 38)) !important;
+    text-align: right !important;
+    text-transform: none !important;
+    /* align-items:flex-end, not padding-bottom on this container: files is
+       a row-direction flex container, so vertical is its cross axis, and
+       container padding on the cross axis doesn't push each cell's own
+       content toward the bottom the way main-axis padding does.
+       flex-end makes each cell
+       shrink-to-content and sit at the bottom of the row; the actual
+       corner inset is per-cell padding-bottom below, mirroring how
+       coords.ranks coord's padding-top is per-cell (its main axis, where
+       per-item padding works predictably). */
+    align-items: flex-end !important;
+    opacity: 1 !important;
+}
+.cg-wrap coords.files coord {
+    flex: 0 0 12.5% !important;   /* see the fuller comment on coords.ranks coord above */
+    padding-right: 0.125rem !important;
+    padding-bottom: 0.125rem !important;
+}
+
+/* ── Last-move highlight ──────────────────────────────────────────────── */
+cg-board square.last-move {
+    background-color: var(--board-highlight);
+}
+
+/* ── Check / checkmate halo ──────────────────────────────────────────── */
+cg-board square.check {
+    background-image: radial-gradient(
+        ellipse at center,
+        rgba(255, 0, 0, 0.90)   0%,
+        rgba(231, 0, 0, 0.70)  25%,
+        rgba(169, 0, 0, 0.00)  89%,
+        rgba(158, 0, 0, 0.00) 100%
+    );
+}
+
+/* ── Spare-piece trays ───────────────────────────────��───────────── */
+.spare-tray {
+    background-color: var(--tray-bg);
+    border: none;
+    padding: 0.3125rem 0;
+    margin: 0;
+    display: flex;
+    justify-content: center;
+    gap: 0;
+    width: var(--board-size);
+    box-sizing: border-box;
+}
+/* Each tray's border sits on whichever edge faces the board. By default
+   (white orientation) that's the black tray's bottom edge and the white
+   tray's top edge. .board-wrap-inner.orientation-black (set by board.js's
+   _syncTrayOrientation() to mirror chessground's orientation) reverses
+   the trays' stacking order via flex-direction: column-reverse, so the
+   rules below mirror which edge faces the board in that orientation. */
+.spare-tray--black { border-bottom: 2px solid var(--tray-border); }
+.spare-tray--white { border-top: 2px solid var(--tray-border); }
+.board-wrap-inner.orientation-black .spare-tray--black {
+    border-bottom: none;
+    border-top: 2px solid var(--tray-border);
+}
+.board-wrap-inner.orientation-black .spare-tray--white {
+    border-top: none;
+    border-bottom: 2px solid var(--tray-border);
+}
+.spare-piece {
+    width: var(--spare-size);
+    height: var(--spare-size);
+    border: 0;
+    padding: 0;
+    margin: 0;
+    background: none;
+    cursor: grab;
+}
+.spare-piece img {
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+}
+.spare-piece.cp-selected {
+    outline: 2px solid var(--gold);
+    outline-offset: 1px;
+    border-radius: 0.125rem;
+}
+/* Crosshair cursor on the board while a spare piece is armed for placement */
+#board.cp-active { cursor: crosshair; }
+#board.cp-active square { cursor: crosshair; }
+
+/* Drag ghost and arrow overlay: no CSS needed here - both are native
+   chessground features (draggable.showGhost / drawable.autoShapes),
+   styled via chessground.base.css + the drawable.brushes config in
+   board.js. */