Fix 1.1 release audit findings and complete documentation follow-ups

[jeremymanning]

This PR fixes release-review regressions in forecasting, caching, feature preservation, fonts and plotting, and updates the tutorials and review tooling. Timestamped forecasts now use the training clock; Plotly 3D colors retain their hue under transparency; full-curve companion panels retain a moving current-time marker. All 25 tutorials have been re-executed.

Closes #284.
Closes #285.

The candidate is fa3e60e5670cabfc1cbbd282e122b9098cc6d1a3. Release publication, merging, tagging and public artifact updates remain subject to Jeremy's manual sign-off.

Findings fixed in the PR

Priority	Finding	Fix and evidence
High	Forecast backtests reused an instance fitted on dataset 1 for dataset 2. On a sine series followed by a positive quadratic series, AutoRegressor() produced negative quadratic forecasts and MAE 2551.68, versus 0.00246 when passing the class.	Deep-copy the model for each dataset; preserve caller state. Regression tests compare actual returned forecasts for class, instance, and dictionary forms.
High	Scoring accepted previously fitted forecasters/imputers even when their learned state could contain the held-out values. Imputation scoring also fitted caller-owned instances.	Require unfitted instances for scoring, copy them before fitting, and document the distinction from ordinary fitted-model replay. Real fitted/unfitted model tests cover both forms.
Medium	Delay silently lost features when distinct pandas column labels had identical string representations (1 and '1'); a 2-column, 2-lag input produced only 2 output columns.	Reject colliding labels with a renaming instruction; tests include mixed-type and duplicate labels.
Medium	URL-cache temporary names used only the process ID. Threads caching the same URL collided: 82 of 100 concurrent writes failed with FileNotFoundError.	Use a unique temporary file per write, clean it on error, and atomically replace the destination. Test 100 real writes across 12 threads and verify payload/metadata and cleanup.
Medium	System-installed Noto Sans took precedence over the bundled Regular face, contradicting deterministic font selection and failing the existing font regression test on this machine.	Register bundled faces ahead of equal-scoring system faces. A fresh interpreter with another real same-family font proves the bundled file wins.
Medium	Optional dependency minimums allowed gensim 4.3 and scikit-image 0.22, predating NumPy 2 support despite the library requiring NumPy>=2.	Raise floors to gensim>=4.4.0 and scikit-image>=0.23.2 in extras/dev/docs. Real minimum-version feature tests pass under NumPy 2.3.5.
Documentation	Public plotting/predict/impute docstrings described shipped features as 1.2; dependency prose implied ARIMA imputation.	Correct version labels and separate forecasting from imputation support.
Documentation	The “convert now” forecast example still hand-wrote URL download/cache logic after the native cache landed.	Use hyp.load(ARCHIVE, cache=True), regenerate and execute the tutorial. The tutorial and video are regenerated with the current code.
Tooling	The browser verifier expected docs-notebooks/master, searched highlighted HTML for contiguous pip install, and demanded an autoplay call in deliberately paused Plotly animations.	Validate versioned notebook links, rendered code text, loaded frames/play controls, and execute a real transition in Chromium. Allow evidence/build paths outside the checkout.

Source and regression-test map

• Forecast/imputation ownership: hypertools/predict/backtest.py, hypertools/impute/backtest.py; tests/test_predict_backtest.py, tests/test_impute_backtest.py.
• Cache atomicity: hypertools/io/sources.py; tests/test_load_url_cache.py.
• Delay collisions: hypertools/manip/delay.py; tests/test_manip_delay.py.
• Font precedence: hypertools/plot/fonts.py; tests/test_fonts_bold.py.
• Dependency compatibility: pyproject.toml, docs/doc_requirements.txt; real minimum-version runs of tests/test_gensim_text.py and tests/test_density.py, plus packaging/optional-import checks.
• Documentation: dispatcher docstrings, docs/optional_dependencies.rst, readme.md, CHANGELOG.md, examples/animate_forecast.py, and its executed tutorial notebook.
• Browser verification: scripts/verify_docs_playwright.py.

Timestamp-aware forecast follow-ups

Forecast fitting accounts for time-like indexes, including irregular/out-of-order observations and different clocks across datasets. The default future interval is the median positive gap between sorted timestamps, with an explicit step override. GaussianProcess uses actual observation times; regular-grid models use a documented interpolation policy. Real-model regression checks cover unsigned and large integer timestamp arithmetic as well as forecast scoring and fitted-model reuse.

Notebook and visual review follow-ups

Finding	Implemented resolution
Plotly legend/trajectory colors differ	Uniform 3D RGBA alpha is transferred to native trace opacity with RGB colors, including frame updates. Opaque frames explicitly reset earlier transparency. Real Chrome pixel tests supplement color/alpha parity tests; nonuniform alpha retains its original semantics.
Colab plots disappear during Run all	Each Plotly example retains a PNG preview and a standalone HTML artifact. A single final viewer opens one live iframe at a time; switching/closing disposes the previous iframe. Download payloads are prepared only on click, avoiding both cumulative live WebGL contexts and repeated multi-megabyte JavaScript payloads in saved cell outputs. Fresh Colab frontend verification remains a separate check.
Companion right marker freezes	Full-curve visibility is separated from current-time marker position and hue. The example visits all 30 input rows over five seconds and labels its trailing smooth. Tests check real artists, dates, full trends, hues and backward seeking, including unequal frame/sample counts. Existing serial-clock tests remain in force.
Visual failures disappear from reports	Attention tables and cross-run comparisons include visual verdicts and notes alongside automatic outcomes. Each rerun resets its visual verdict and receives a fresh execution identity.
Stale approvals/provenance	Reports carry notebook, inventory and case-source hashes, execution IDs, actual package source, optional dependency versions, settings, binaries and structured warnings. Changed checks are distinguished from changed outcomes.
Animation exports falsely pass	Every run uses fresh destinations. Image/movie decoders require multiple distinct frames and meaningful duration; single-frame GIF/APNG outputs fail. Export examples now have enough time and frames to demonstrate motion.
Nonportable downloads/playback	Colab uses its file-download API; local Jupyter prepares a downloadable data link only on request. Tutorial MP4-producing cells embed movie bytes on Colab while retaining relative media for local Jupyter/Sphinx.
Incomplete feature/behavior coverage	Tour expanded from 227 to 244 cases. Added multi-column series/date bounds, returned data/colors/metadata/panel bundles, fitted sklearn pipeline reuse, callback clocks and callable titles, CJK fonts, luminance controls, compressed/extensionless and legacy XLS input, smoothing warm-up, hosted fitted topic models and stronger hosted-data contracts. Every dispatcher family participates in registry coverage guards.
Optional-install claim lacked a real missing dependency	scripts/verify_optional_install.py creates an isolated base-only environment, verifies the friendly disabled-autoinstall error, then genuinely installs the missing XLSX dependency and verifies a round trip. The working environment is never stripped of dependencies.
Tutorial installer inconsistencies	All 25 tutorial installers require 1.1 or newer and preserve current local checkouts. Independent convokit/py7zr prerequisites still execute. Text tutorials demonstrate their stated on-demand policy; Kalman no longer requests the unrelated prediction extra. Successful prerequisite-only pip chatter is omitted from published outputs.
Executor skips configuration	Configuration and the tagged candidate installer are separate. The executor skips only HyperTools installers, preserving other setup and work.
Installation failure evidence	Colab candidate setup streams and retains its installer log; failure offers that log for download. Successful logs are included in the report ZIP. Local execution explicitly retains the selected checkout.
Native GUI case tests inline rendering	Desktop interaction runs in a separate Qt process and leaves the window available. It is an explicit optional manual case, not an inline-rendering PASS.
Remote pickle trust	Historical Drive/Dropbox pickle demonstrations require conspicuous, disabled-by-default trust opt-in. Built-in hosted fitted models retain their independent digest validation. No post-deserialization hash is presented as protection.
Documentation/maintenance	Corrected 1D inspection text, synchronized inventory/markdown, removed generated literal branches, strengthened expected-error assertions, documented XLSX writing, corrected candidate-versus-wheel release checks, and documented behavior evidence routes. Setup/playback additions are checked against exact templates without increasing the existing example-logic size budgets.

Windows and lint follow-up

The previous head passed all eight Linux/macOS matrix jobs but failed two notebook tests on every Windows version because UTF-8 files were decoded as CP1252. Notebook generation, the embedded viewer/export helpers and tests now explicitly use UTF-8. A real Unicode Plotly HTML regression opens/closes the actual ipywidgets viewer; no mocks are used. Equivalent Colab availability imports in 14 tutorials and their template now satisfy Ruff. Repository-wide lint passes and CI provisions Ruff 0.15.20 explicitly.

Verification

Current candidate: fa3e60e5670cabfc1cbbd282e122b9098cc6d1a3.

• Current local tour: 241 PASS, 3 SKIP, 0 FAIL/BLOCKED, all 244 cases. Reports record this exact commit and a clean tracked checkout. Source SHA-256: 10ff17a28db615994497a177dac75a58c2cb788f0a7b67fbdcbf41fb6535958b.
• Current focused notebook/install/support/visual/tutorial checks: 364 passed, 8 skipped; full repository Ruff and git diff --check pass.
• Opt-in end-to-end example smoke from an isolated checkout at this SHA: 6 passed, 338 deselected.
• Actual macOS QtAgg interaction: PASS. A real window opened; mouse press/move/release rotated the plot; it closed successfully. Screenshots and event results are retained. Qt was installed only in an isolated verification environment.
• Candidate wheel/sdist build and Twine metadata checks: PASS. Fresh wheel installation and pip check pass; public API/pipeline, three irregular-time forecasters, inferred future spacing, Matplotlib PNG and Plotly standalone HTML checks pass. Imports are from isolated site-packages, not the source checkout. Artifact digests, package versions, bundled fonts/config/licenses and exact candidate provenance are retained.
• Prior implementation evidence: all 25 tutorials executed, full default suite 5,936 passed, 20 skipped, 2 deselected, both opt-in large-data tests passed separately, and a real missing-extra installation/round trip passed. The current equivalent tutorial import edits are covered by the focused checks above.
• Prior browser/visual evidence: real Chrome color-pixel regressions and standalone animated HTML transitions passed. The companion movie has 30 H.264 frames over five seconds; its inspected middle frame shows both companion markers at sample 15 and the matching January 16 title. Local/standalone browser checks do not substitute for fresh Colab frontend acceptance.
• The current executed tour is about 6 MB, retaining PNG previews rather than live Plotly MIME outputs. Automated reports preserve warnings and leave unreviewed visual cases unapproved.

Current hosted CI: run 34558379385 completed successfully: 16 successful jobs, zero failures, one expected skipped release-only gate. All 12 matrix jobs passed, including all four Windows versions. Ubuntu Python 3.12 additionally passed repository lint, pandas 3, coverage (91% total line coverage) and screenshot generation. Clean docs executed all 51 gallery examples and 323 doctests with zero failures. Dataset gate: 33 passed; live-source gate: 43 passed, 1 deselected. Fresh wheel and sdist install gates passed. PR CI does not replace master/tag release gates.

The final review packet is ready locally in notes/notebook_critical_review_2026-09-10/START_HERE_FINAL_REVIEW.md, with detailed CI evidence in ci_final_status.md. The cleared Colab notebook and executed local reference have identical cell sources. All 104 tracked package Python files match the built candidate wheel byte-for-byte. No package or test changes were needed during this final verification pass.

Local evidence: notes/colab/feature_tour_preflight_fa3e60e5/; detailed follow-up report: notes/notebook_critical_review_2026-09-10/windows_preflight_report.md. These are local review files, not published documentation. The cleared Colab upload copy is notes/colab/hypertools_1.1_candidate_fa3e60e5.ipynb.

Remaining release checks

1. Run the pinned tour in a fresh Colab runtime. After Run all, inspect early previews, viewer switching/closing, legend/trajectory colors, companion playback/scrubbing/dates, movie playback and report/artifact downloads. Retain notebook/reports and record visual decisions.
2. Review remaining manual cases; macOS Qt interaction is verified, while native Windows GUI and explicitly trusted remote-pickle demonstrations remain separate acceptance decisions.
3. Obtain Jeremy's manual sign-off before merging, tagging or changing public release artifacts. From the approved final release commit, rebuild gallery/manifest and wheel/sdist, record digests, and require master and tag release-gate CI to pass. The current tag/draft/assets describe the older 96ac8b7f draft.
4. Publish only with explicit approval, then verify the actual published wheel, public documentation and Colab links, and conda-forge follow-up.

[jeremymanning]

Second review pass on this branch (2026-09-06): the cloud ultrareview of the PR diff, then nine local reviewers over the full v1.0.0..HEAD diff (plot, io/tools/manip, predict/impute/align/core, packaging/CI, documentation) and item-by-item verification of #284 and #285. Every confirmed finding is fixed on the branch with a regression test; the fixes are listed in the CHANGELOG's "Fixed during the release review" subsection. The commits since the original report:

• f116dd7 module-scope imports in the backtest loops (the ultrareview nit)
• f1a1e09 duplicate metrics=, holdout=True, t=0 message, warning attribution, ragged return_score
• e47968f three spy/fake-object tests rewritten against real observables; HypertoolsOfflineError exported
• a59f2e2 native-usage scanner covers every example and tutorial, with the ax= allowlist and output-cell gates the issue described
• ef887ca 32 plot/io/text fixes: offline=True was still opening connections, yahoo: dates east of UTC, synthetic seed types, short palette= lists (a 1.0 regression), dataset_fade= under a continuous hue, loop=True rotations, companion= under serial order, title_wrap on dynamic titles, plotly newline titles, text2mat on a flat list of strings
• 1be634d fit() returns self on the manipulator and aligner bases
• f0e56c9 documentation: changelog completeness and accuracy, readme floors, API exceptions, gallery edit links, tutorial prose and code
• 384fe99 ARIMA under animate= (per-model min_history), datetime t= inside plot, predict= collections on MultiIndex frames, panels= with truth=/labels/nested hue, series-mode fmt=/xlim=/y label, TimedeltaIndex
• 00e5a00, f775b37 eight tutorials re-executed on the reviewed library, home paths scrubbed from stored outputs
• 9340300 Windows: POSIX paths in the scanner, retrying os.replace in the URL cache
• 63aa9cf, d20fdde session and project notes

Local verification on the final library: full suite 5171 passed / 0 failed (after the two stale expectations were updated), ruff clean, sphinx -W over the full gallery with zero warnings, the example smoke gate 344 passed. PR CI on the branch head d20fdde: every job green (release-gate skipped by design on a branch).

After merge the release is re-cut from the merge commit; RELEASE_CHECKLIST.md now describes moving the draft tag, republishing the gallery namespace and replacing the draft release assets.