Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+trackio/assets/badge.png filter=lfs diff=lfs merge=lfs -text
+trackio/assets/trackio_logo_old.png filter=lfs diff=lfs merge=lfs -text

trackio/CHANGELOG.md

@@ -0,0 +1,400 @@
+# trackio
+
+## 0.31.4
+
+### Features
+
+- [#628](https://github.com/gradio-app/trackio/pull/628) [`3eeaa99`](https://github.com/gradio-app/trackio/commit/3eeaa99bd05bef69053b9a1b5c7af3abf56c360c) - let `logbook cell figure` embed image files directly.  Thanks @abidlabs!/n  `trackio logbook cell figure` now accepts an image path via a new `--image`/n  flag, and `--html <file>` transparently embeds the file when it points at an/n  image. Previously the only way to add a PNG/JPG figure was to hand-encode it/n  into an `<img>` data-URI, and passing an image path to `--html` crashed with a/n  `UnicodeDecodeError` (the binary file was read as UTF-8 text). Images are/n  embedded as responsive base64 data URIs. The Python API `add_figure_cell` gains/n  a matching `image=` parameter.
+
+## 0.31.3
+
+### Features
+
+- [#626](https://github.com/gradio-app/trackio/pull/626) [`174aecf`](https://github.com/gradio-app/trackio/commit/174aecff33e6d1cc8d71965a73538c0510abed46) - Fix logbook Markdown escaping and figure hotspot navigation.  Thanks @abidlabs!
+
+## 0.31.2
+
+### Features
+
+- [#624](https://github.com/gradio-app/trackio/pull/624) [`a0918ed`](https://github.com/gradio-app/trackio/commit/a0918edc7594bb211f9e6871546b9d36939f0658) - Fix poster hotspot navigation after iframe load.  Thanks @abidlabs!
+
+## 0.31.1
+
+### Features
+
+- [#621](https://github.com/gradio-app/trackio/pull/621) [`a40f1a4`](https://github.com/gradio-app/trackio/commit/a40f1a464c51652ecdeab04d999659d71b76047e) - add native fullscreen mode for logbook figures.  Thanks @abidlabs!
+- [#623](https://github.com/gradio-app/trackio/pull/623) [`31fd4d7`](https://github.com/gradio-app/trackio/commit/31fd4d7b4004f0c511484f089e6a550da1b4d71e) - let interactive logbook figures navigate to logbook pages.  Thanks @abidlabs!
+
+## 0.31.0
+
+### Features
+
+- [#601](https://github.com/gradio-app/trackio/pull/601) [`8c49140`](https://github.com/gradio-app/trackio/commit/8c491406c54685369d43f3a9c4d4a0e99108bc49) - browse artifacts from the UI.  Thanks @Saba9!
+- [#602](https://github.com/gradio-app/trackio/pull/602) [`1ae1558`](https://github.com/gradio-app/trackio/commit/1ae155803b5450b181a47767255421499074c70b) - feat: add Artifact.add_reference to reference external objects without copy.  Thanks @adrien-grl!
+
+## 0.30.4
+
+### Features
+
+- [#618](https://github.com/gradio-app/trackio/pull/618) [`64c18f6`](https://github.com/gradio-app/trackio/commit/64c18f65bf98d6f54040395a1ca0473347ba6a2b) - Logbook: share button on figures + `logbook pin` CLI.  Thanks @abidlabs!
+
+## 0.30.3
+
+### Features
+
+- [#616](https://github.com/gradio-app/trackio/pull/616) [`645498b`](https://github.com/gradio-app/trackio/commit/645498be37bafab28f884a36e80c5bc0eab06cd9) - Logbook single page.  Thanks @abidlabs!
+
+## 0.30.2
+
+### Features
+
+- [#614](https://github.com/gradio-app/trackio/pull/614) [`eba80c7`](https://github.com/gradio-app/trackio/commit/eba80c7464af250519a90b8ac3179ff6652b651a) - Render logbooks as single-page documents with section navigation and contextual resources.  Thanks @abidlabs!
+- [#612](https://github.com/gradio-app/trackio/pull/612) [`2c1b943`](https://github.com/gradio-app/trackio/commit/2c1b9436b093e9f9335c99c10fe4b6afa622e314) - Warn that logbook open is experimental.  Thanks @abidlabs!
+- [#611](https://github.com/gradio-app/trackio/pull/611) [`96b1d94`](https://github.com/gradio-app/trackio/commit/96b1d94def7596aa1302864cbfc57942dd63822b) - Logbook: auto-capture output artifacts and live-embedded dashboard cells.  Thanks @abidlabs!
+
+## 0.30.1
+
+### Features
+
+- [#609](https://github.com/gradio-app/trackio/pull/609) [`2ed1295`](https://github.com/gradio-app/trackio/commit/2ed12959c73aa9c04ca1096cf7a8315ce2886ed1) - Serve live logbook preview from open.  Thanks @abidlabs!
+
+## 0.30.0
+
+### Features
+
+- [#603](https://github.com/gradio-app/trackio/pull/603) [`a793fd8`](https://github.com/gradio-app/trackio/commit/a793fd88827482134bce295c6228e117de64566a) - Move default artifact downloads under `./.trackio/artifact-downloads/` so materialized files stay out of the project root.  Thanks @abidlabs!
+- [#604](https://github.com/gradio-app/trackio/pull/604) [`dd3b8ee`](https://github.com/gradio-app/trackio/commit/dd3b8eeef4e0da8bf0df6238617e20ae81f3e564) - docs: clarify artifact types.  Thanks @abidlabs!
+- [#586](https://github.com/gradio-app/trackio/pull/586) [`7db4c3b`](https://github.com/gradio-app/trackio/commit/7db4c3b6de6ff4903daf7dabed8842f212c8b7fd) - artifact tracking API — `log_artifact`, `use_artifact`, and an `Artifact` class for versioned, named file collections with aliases, content-addressed deduplication, and producer/consumer run lineage; works offline and syncs blobs to Hugging Face Spaces/Datasets.  Thanks @Saba9!
+- [#597](https://github.com/gradio-app/trackio/pull/597) [`5ba561e`](https://github.com/gradio-app/trackio/commit/5ba561e1b4023abdf63624f4fb396367ed6e9e76) - Add experiment logbooks: shareable static-Space lab notebooks.  Thanks @abidlabs!
+
+## 0.29.0
+
+### Features
+
+- [#593](https://github.com/gradio-app/trackio/pull/593) [`ca4722c`](https://github.com/gradio-app/trackio/commit/ca4722c19d2219a3a78b5977149873b9dff73f34) - Add CLI command to list Trackio Spaces.  Thanks @abidlabs!
+
+## 0.28.1
+
+### Features
+
+- [#589](https://github.com/gradio-app/trackio/pull/589) [`5e9905d`](https://github.com/gradio-app/trackio/commit/5e9905d7815bb063f2d9bb38aa76177405c5e2b4) - Reduce Metrics page log payloads by requesting scalar-only metrics and add URL x-axis initialization/fallback handling.  Thanks @evalstate!
+- [#590](https://github.com/gradio-app/trackio/pull/590) [`56493a6`](https://github.com/gradio-app/trackio/commit/56493a6e9a0114b8655ab44b8c3dec7bae2a5df5) - Use TRACKIO_WRITE_TOKEN for server write token.  Thanks @abidlabs!
+
+## 0.28.0
+
+### Features
+
+- [#582](https://github.com/gradio-app/trackio/pull/582) [`d9dabb5`](https://github.com/gradio-app/trackio/commit/d9dabb5bda8147ad7c9203646358bd0880fa6521) - Add JSONL inbox fragments: durable logging when the Space is unreachable and on network filesystems.  Thanks @abidlabs!
+
+## 0.27.0
+
+### Features
+
+- [#567](https://github.com/gradio-app/trackio/pull/567) [`8c0ce21`](https://github.com/gradio-app/trackio/commit/8c0ce21ff9746d7c6a250684b1b5f0f3f04e0520) - Add CPU, RAM, disk, network and sensor metrics monitoring for non-Apple devices.  Thanks @yannsadowski!
+- [#571](https://github.com/gradio-app/trackio/pull/571) [`57bc7df`](https://github.com/gradio-app/trackio/commit/57bc7df27ecd7b3ff543dbd2bff5c94182bfb69e) - Fix IndexError when importing CSV with no numeric metric columns.  Thanks @Ckal!
+- [#577](https://github.com/gradio-app/trackio/pull/577) [`db0e730`](https://github.com/gradio-app/trackio/commit/db0e730463103142688c1c0efef9ff68a52e281d) - Sort and paginate media items.  Thanks @abidlabs!
+- [#576](https://github.com/gradio-app/trackio/pull/576) [`6f635e2`](https://github.com/gradio-app/trackio/commit/6f635e22553ce2deaece6a0d6289475ab8683040) - Render plot/metric titles as searchable DOM text.  Thanks @abidlabs!
+- [#579](https://github.com/gradio-app/trackio/pull/579) [`cf7759e`](https://github.com/gradio-app/trackio/commit/cf7759efaab73ce1e98a8a2355dc1f65d54bc775) - Merge image viewer with current media page, credit to @catwell.  Thanks @abidlabs!
+
+## 0.26.0
+
+### Features
+
+- [#553](https://github.com/gradio-app/trackio/pull/553) [`06011ac`](https://github.com/gradio-app/trackio/commit/06011acc9c73341fd234f9cd8eaf96d5a34ad8ce) - fix: serve static-Space assets at /static/trackio.  Thanks @abidlabs!
+- [#563](https://github.com/gradio-app/trackio/pull/563) [`551569c`](https://github.com/gradio-app/trackio/commit/551569c16fb56ec63249ebdc28348d326ccf7126) - Fix Traces UI a bit.  Thanks @abidlabs!
+- [#550](https://github.com/gradio-app/trackio/pull/550) [`5690acd`](https://github.com/gradio-app/trackio/commit/5690acda5da303c63ad332451afeab3e9750fd1a) - fix: keep sparse metrics sparse through smoothing.  Thanks @abidlabs!
+- [#551](https://github.com/gradio-app/trackio/pull/551) [`0ef7266`](https://github.com/gradio-app/trackio/commit/0ef72660695cf932f3906ddbf33d41d087280a22) - add "group by" dropdown to sidebar.  Thanks @Saba9!
+- [#538](https://github.com/gradio-app/trackio/pull/538) [`a15c1a8`](https://github.com/gradio-app/trackio/commit/a15c1a8877c07514e0596630bb7c7299299994a9) - Subdue empty dashboard tabs.  Thanks @abidlabs!
+- [#559](https://github.com/gradio-app/trackio/pull/559) [`0b53a41`](https://github.com/gradio-app/trackio/commit/0b53a413909598f92138b6b6395a91c2d5034faf) - Store traces separately from metrics.  Thanks @abidlabs!
+- [#556](https://github.com/gradio-app/trackio/pull/556) [`d110001`](https://github.com/gradio-app/trackio/commit/d110001dbd9f6b262dfe41f2b702e3a71aa0cfc9) - fix: keep selected x-axis option in dropdown and dismiss dropdown on re-click.  Thanks @Saba9!
+- [#560](https://github.com/gradio-app/trackio/pull/560) [`aee2923`](https://github.com/gradio-app/trackio/commit/aee2923d3ada4f74d62d065c16f1f6a56a295e48) - Paginate Traces tab with step filter.  Thanks @abidlabs!
+
+### Fixes
+
+- [#540](https://github.com/gradio-app/trackio/pull/540) [`0b674ac`](https://github.com/gradio-app/trackio/commit/0b674ac6438738de89bc5b3fb700ccfd8a39368c) - raise default metrics sampling cap from 1500 to 3000 so client-side smoothing on the Metrics tab runs over higher-resolution data.  Thanks @edbeeching!
+
+## 0.25.1
+
+### Features
+
+- [#535](https://github.com/gradio-app/trackio/pull/535) [`d7f1b27`](https://github.com/gradio-app/trackio/commit/d7f1b27a98f185d2d97ef54975d5865e0b5243c9) - Avoid HF token leaks in static snapshots.  Thanks @abidlabs!
+
+## 0.25.0
+
+### Features
+
+- [#533](https://github.com/gradio-app/trackio/pull/533) [`08bc5eb`](https://github.com/gradio-app/trackio/commit/08bc5eb090525d3ff5f7fa4233c30c42162aa74c) - Fix Windows-only emoji mojibake when uploading Space README.  Thanks @tomaarsen!
+- [#518](https://github.com/gradio-app/trackio/pull/518) [`e7ed176`](https://github.com/gradio-app/trackio/commit/e7ed176da53d8b49290fddd890b3d18c0b9b958f) - Traces in Trackio.  Thanks @abidlabs!
+- [#531](https://github.com/gradio-app/trackio/pull/531) [`27a50a3`](https://github.com/gradio-app/trackio/commit/27a50a37362020304b774344b4c774ff548985b6) - Add configurable custom frontends for Trackio.  Thanks @abidlabs!
+
+## 0.24.2
+
+### Features
+
+- [#527](https://github.com/gradio-app/trackio/pull/527) [`7d1c0b9`](https://github.com/gradio-app/trackio/commit/7d1c0b9c37ce9a9845e6bbe6c083da9d36084caf) - Fix dashboard UX issues: smoothing in share URL, run selection, and run filtering.  Thanks @abidlabs!
+- [#526](https://github.com/gradio-app/trackio/pull/526) [`643878a`](https://github.com/gradio-app/trackio/commit/643878a82985fab9e6675f769ff0107cb46e042a) - Add emoji to README and deploy README content.  Thanks @qgallouedec!
+- [#529](https://github.com/gradio-app/trackio/pull/529) [`a77972b`](https://github.com/gradio-app/trackio/commit/a77972b68541ebe9e056824e69c9bbca3979ece4) - Remove pydub dependency.  Thanks @abidlabs!
+
+## 0.24.1
+
+### Features
+
+- [#524](https://github.com/gradio-app/trackio/pull/524) [`65a6897`](https://github.com/gradio-app/trackio/commit/65a6897561b465fc8f05550562f8da1ba3c99060) - Fix `trackio skills add`.  Thanks @abidlabs!
+- [#522](https://github.com/gradio-app/trackio/pull/522) [`05aaca7`](https://github.com/gradio-app/trackio/commit/05aaca7f166bf7667b60b40656d677532a4bdd6e) - relax `starlette` dependency and fix import style.  Thanks @abidlabs!
+- [#525](https://github.com/gradio-app/trackio/pull/525) [`32c05c5`](https://github.com/gradio-app/trackio/commit/32c05c5d5e3aa84ca7099a6fa08a9093ccd4b95f) - Restore sidebar share and embed snippets, and fix query parameter regression.  Thanks @abidlabs!
+
+## 0.24.0
+
+### Features
+
+- [#502](https://github.com/gradio-app/trackio/pull/502) [`3b397df`](https://github.com/gradio-app/trackio/commit/3b397dfbaff9de137b088f3cad528117e14faab1) - Add docs on SQL & Parquet schema / format, as well as a new CLI command: `trackio query project --project PROJECT --sql SQL_QUERY`.  Thanks @abidlabs!
+- [#506](https://github.com/gradio-app/trackio/pull/506) [`498bbc4`](https://github.com/gradio-app/trackio/commit/498bbc47f66cc90cc5776f363d001a5571941c00) - Scope bucket sync to trackio/ subtree to avoid walking the HF cache.  Thanks @abidlabs!
+- [#505](https://github.com/gradio-app/trackio/pull/505) [`8e26ab9`](https://github.com/gradio-app/trackio/commit/8e26ab93b5d9caa2f81334f6fff42fb9cefbb232) - Add an `id` field to `Run` which is used internally, allowing users to have multiple runs with the same run name.  Thanks @abidlabs!
+- [#517](https://github.com/gradio-app/trackio/pull/517) [`29e1034`](https://github.com/gradio-app/trackio/commit/29e1034b795567ec5ed6d19c5a946915a6498e2a) - Fix static exports, Space bucket handling, and other misc issues.  Thanks @abidlabs!
+- [#489](https://github.com/gradio-app/trackio/pull/489) [`1b96db3`](https://github.com/gradio-app/trackio/commit/1b96db39c8fd4326e621ee2336b0fca4f263a18a) - Remove `gradio` dependency in `trackio` -- only `gradio_client` is needed locally anymore. Also lazily import `pandas` and remove it as a dependency.  Thanks @abidlabs!
+- [#513](https://github.com/gradio-app/trackio/pull/513) [`d54d290`](https://github.com/gradio-app/trackio/commit/d54d290fcb1bb08358b558a43a962f78abe990ea) - Reduce HF Spaces 429s: polling tuning and batched metric logs API.  Thanks @abidlabs!
+- [#516](https://github.com/gradio-app/trackio/pull/516) [`afe2959`](https://github.com/gradio-app/trackio/commit/afe295988928a3ea3ded38bdb5bb05cca85d3c74) - Fix run list order and legend overflow.  Thanks @abidlabs!
+- [#515](https://github.com/gradio-app/trackio/pull/515) [`0a242b8`](https://github.com/gradio-app/trackio/commit/0a242b85127b02f532b24c7fd2bb046580cc7641) - Add Gradio-compatible /gradio_api routes on Spaces.  Thanks @abidlabs!
+- [#510](https://github.com/gradio-app/trackio/pull/510) [`60bbc86`](https://github.com/gradio-app/trackio/commit/60bbc86b4e7f880de72075e5bf31b093709bb5a4) - Add server_url and TRACKIO_SERVER_URL for self-hosted servers; space_id and TRACKIO_SPACE_ID take precedence when both are set.  Thanks @abidlabs!
+- [#509](https://github.com/gradio-app/trackio/pull/509) [`21c099a`](https://github.com/gradio-app/trackio/commit/21c099aa830a278973fab4c7c58a0139f417caa4) - Fix: Open browser with write_token so trackio show allows mutations.  Thanks @abidlabs!
+
+## 0.23.0
+
+### Features
+
+- [#494](https://github.com/gradio-app/trackio/pull/494) [`e8a897d`](https://github.com/gradio-app/trackio/commit/e8a897d2266d9b2558f72d768b0b21f4d0a8781b) - Add a settings/CLI page to Trackio.  Thanks @abidlabs!
+- [#481](https://github.com/gradio-app/trackio/pull/481) [`882647e`](https://github.com/gradio-app/trackio/commit/882647ec1599cf04500d03b5ca75ddc2733682e2) - Add multi-GPU system metrics support.  Thanks @Saba9!
+- [#485](https://github.com/gradio-app/trackio/pull/485) [`46a3cc3`](https://github.com/gradio-app/trackio/commit/46a3cc3758719e171417612efee102a487e71ebd) - Fix/remove flaky E2E space tests.  Thanks @abidlabs!
+- [#501](https://github.com/gradio-app/trackio/pull/501) [`06ea885`](https://github.com/gradio-app/trackio/commit/06ea8852f5e40ab3f1cf629a0a01af5c17f847a1) - Fix SQLite corruption on bucket-mounted Spaces.  Thanks @abidlabs!
+- [#496](https://github.com/gradio-app/trackio/pull/496) [`af23d74`](https://github.com/gradio-app/trackio/commit/af23d74438b146c4a3512ace15ea984656e943ed) - Prevent trackio errors from crashing the user's training loop.  Thanks @abidlabs!
+
+## 0.22.0
+
+### Features
+
+- [#484](https://github.com/gradio-app/trackio/pull/484) [`cc05ada`](https://github.com/gradio-app/trackio/commit/cc05ada8e89773f3a894af99b801ef680f64418f) - Fix duplicate columns in parquet export.  Thanks @abidlabs!
+- [#487](https://github.com/gradio-app/trackio/pull/487) [`853f764`](https://github.com/gradio-app/trackio/commit/853f7646a70d12633afaa4f69db86425aa665413) - Relax `PIL` dependency and remove `plotly` as it's no longer used.  Thanks @abidlabs!
+
+## 0.21.2
+
+### Features
+
+- [#482](https://github.com/gradio-app/trackio/pull/482) [`f62180a`](https://github.com/gradio-app/trackio/commit/f62180a0218bc99a259d5ca110a0384a6cae11c8) - Use server-side bucket copy when freezing Spaces.  Thanks @abidlabs!
+
+## 0.21.1
+
+### Features
+
+- [#475](https://github.com/gradio-app/trackio/pull/475) [`fcb476c`](https://github.com/gradio-app/trackio/commit/fcb476cd37a40923e9679aaf966f41d582a878a8) - Tweaks.  Thanks @abidlabs!
+- [#477](https://github.com/gradio-app/trackio/pull/477) [`7d52dfd`](https://github.com/gradio-app/trackio/commit/7d52dfdce5b6eff6a34501a6d5a620220663cf09) - Fix `.sync()` and add `.freeze()` as a separate methods.  Thanks @abidlabs!
+
+## 0.21.0
+
+### Features
+
+- [#467](https://github.com/gradio-app/trackio/pull/467) [`f357deb`](https://github.com/gradio-app/trackio/commit/f357debf78957e4c1f2b901bee4f77cf397298b4) - Allow logged metrics as x-axis choices.  Thanks @abidlabs!
+- [#474](https://github.com/gradio-app/trackio/pull/474) [`655673d`](https://github.com/gradio-app/trackio/commit/655673d4c6b7c8b7ee8f87f2589f2dbbc3d2ef91) - Fix file descriptor leak from `sqlite3.connect`.  Thanks @abidlabs!
+- [#470](https://github.com/gradio-app/trackio/pull/470) [`bea8c9d`](https://github.com/gradio-app/trackio/commit/bea8c9dcae0b59d071b6c779c97ee525c9bbf6e7) - Restores tooltips to line plots and fixes the call to uses TTL instead of OAuth.  Thanks @abidlabs!
+- [#471](https://github.com/gradio-app/trackio/pull/471) [`246fce0`](https://github.com/gradio-app/trackio/commit/246fce0a01619e1c2c538c67b3e460883334d500) - Deprecate dataset backend in favor of buckets.  Thanks @abidlabs!
+- [#465](https://github.com/gradio-app/trackio/pull/465) [`3e11174`](https://github.com/gradio-app/trackio/commit/3e1117438bb8168b802245a33059affa558ae519) - Use HF buckets as backend.  Thanks @abidlabs!
+- [#469](https://github.com/gradio-app/trackio/pull/469) [`915d170`](https://github.com/gradio-app/trackio/commit/915d17045133172b59195acfdcc70709229668aa) - Make static Spaces work with Buckets and also allow conversion from Gradio SDK to Static Spaces.  Thanks @abidlabs!
+
+## 0.20.2
+
+### Features
+
+- [#464](https://github.com/gradio-app/trackio/pull/464) [`c89ebb3`](https://github.com/gradio-app/trackio/commit/c89ebb3b50f695bc7f16cbc6f46dce86f79a01e9) - Improve rendering of curves.  Thanks @abidlabs!
+- [#462](https://github.com/gradio-app/trackio/pull/462) [`9160b78`](https://github.com/gradio-app/trackio/commit/9160b78ff6f258f0b87a4f34a24e7d0b5dfbf2fb) - Refactor plot title to display only the metric name without the path.  Thanks @qgallouedec!
+
+## 0.20.1
+
+### Features
+
+- [#454](https://github.com/gradio-app/trackio/pull/454) [`22881db`](https://github.com/gradio-app/trackio/commit/22881dbbbb6b81197a00a19853771007093d61e4) - Bar chart single point.  Thanks @abidlabs!
+- [#455](https://github.com/gradio-app/trackio/pull/455) [`f8db51a`](https://github.com/gradio-app/trackio/commit/f8db51a20ca61ef703f3f2c2ee1ebd9c4f239cf2) - Adds a static Trackio mode via `trackio.sync(sdk="static")` and support for the `TRACKIO_SPACE_ID` environment variable.  Thanks @abidlabs!
+
+## 0.20.0
+
+### Features
+
+- [#450](https://github.com/gradio-app/trackio/pull/450) [`b0571ef`](https://github.com/gradio-app/trackio/commit/b0571ef6207a1ce346696f858ad2b7b584dd194f) - Use Svelte source for Gradio components directly in Trackio dashboard.  Thanks @abidlabs!
+
+## 0.19.0
+
+### Features
+
+- [#445](https://github.com/gradio-app/trackio/pull/445) [`cef4a58`](https://github.com/gradio-app/trackio/commit/cef4a583cb76f4091fc6c0e5783124ee84f8e243) - Add remote HF Space support to CLI.  Thanks @abidlabs!
+- [#444](https://github.com/gradio-app/trackio/pull/444) [`358f2a9`](https://github.com/gradio-app/trackio/commit/358f2a9ca238ee8b90b5a8c96220da287e0698fb) - Fix alerts placeholder flashing on reports page.  Thanks @abidlabs!
+
+## 0.18.0
+
+### Features
+
+- [#435](https://github.com/gradio-app/trackio/pull/435) [`4a47112`](https://github.com/gradio-app/trackio/commit/4a471128e18a39e45fad48a67fd711c5ae9e4aed) - feat: allow hiding section header accordions.  Thanks @Saba9!
+- [#439](https://github.com/gradio-app/trackio/pull/439) [`18e9650`](https://github.com/gradio-app/trackio/commit/18e96503d5a3a7cf926e92782d457e23c19942bd) - Add alerts with webhooks, CLI, and documentation.  Thanks @abidlabs!
+- [#438](https://github.com/gradio-app/trackio/pull/438) [`0875ccd`](https://github.com/gradio-app/trackio/commit/0875ccd3d8a41b1376f64030f21cfe8cdcc73b05) - Add "share this view" functionality.  Thanks @qgallouedec!
+- [#409](https://github.com/gradio-app/trackio/pull/409) [`9282403`](https://github.com/gradio-app/trackio/commit/9282403d8896d48679b0f888208a7ba5bdd4271a) - Add Apple Silicon GPU and system monitoring support.  Thanks @znation!
+- [#434](https://github.com/gradio-app/trackio/pull/434) [`4193223`](https://github.com/gradio-app/trackio/commit/41932230a3a2e1c16405dba08ecba5a42f11d1a8) - fix: table slider crash.  Thanks @Saba9!
+
+### Fixes
+
+- [#441](https://github.com/gradio-app/trackio/pull/441) [`3a2d11d`](https://github.com/gradio-app/trackio/commit/3a2d11dab0b4b37c925abc30ef84b0e2910321ee) - preserve x-axis step when toggling run checkboxes.  Thanks @Saba9!
+
+## 0.17.0
+
+### Features
+
+- [#428](https://github.com/gradio-app/trackio/pull/428) [`f7dd1ce`](https://github.com/gradio-app/trackio/commit/f7dd1ce2dc8a1936f9983467fcbcf93bfef01e09) - feat: add ability to rename runs.  Thanks @Saba9!
+- [#437](https://github.com/gradio-app/trackio/pull/437) [`2727c0b`](https://github.com/gradio-app/trackio/commit/2727c0b0755f48f7f186162ea45185c98f6b5516) - Add markdown reports across Trackio.  Thanks @abidlabs!
+- [#427](https://github.com/gradio-app/trackio/pull/427) [`5aeb9ed`](https://github.com/gradio-app/trackio/commit/5aeb9edcfd2068d309d9d64f172dcbcc327be1ab) - Make Trackio logging much more robust.  Thanks @abidlabs!
+
+## 0.16.1
+
+### Features
+
+- [#431](https://github.com/gradio-app/trackio/pull/431) [`c7ce55b`](https://github.com/gradio-app/trackio/commit/c7ce55b14dd5eb0c2165fb15df17dd60721c9325) - Lazy load the UI when trackio is imported.  Thanks @abidlabs!
+
+## 0.16.0
+
+### Features
+
+- [#426](https://github.com/gradio-app/trackio/pull/426) [`ead4dc8`](https://github.com/gradio-app/trackio/commit/ead4dc8e74ee2d8e47d61bca0a7668456acf49be) - Fix redundant double rendering of group checkboxes.  Thanks @abidlabs!
+- [#413](https://github.com/gradio-app/trackio/pull/413) [`39c4750`](https://github.com/gradio-app/trackio/commit/39c4750951d554ba6eb4d58847c6bb444b2891a8) - Check `dist-packages` when checking for source installation.  Thanks @sergiopaniego!
+- [#423](https://github.com/gradio-app/trackio/pull/423) [`2e52ab3`](https://github.com/gradio-app/trackio/commit/2e52ab303e3041718a6a56fbf84d0848aca9ad67) - Fix legend outline visibility issue.  Thanks @Raghunath-Balaji!
+- [#407](https://github.com/gradio-app/trackio/pull/407) [`c8a384d`](https://github.com/gradio-app/trackio/commit/c8a384ddfe5a295cecf862a26178d40e48acb424) - Fix pytests that were failling locally on MacOS.  Thanks @abidlabs!
+- [#405](https://github.com/gradio-app/trackio/pull/405) [`35aae4e`](https://github.com/gradio-app/trackio/commit/35aae4e3aa3e2b2888887528478b9dc6a9808bda) - Add conditional padding for HF Space dashboard when not in iframe.  Thanks @znation!
+
+## 0.15.0
+
+### Features
+
+- [#397](https://github.com/gradio-app/trackio/pull/397) [`6b38ad0`](https://github.com/gradio-app/trackio/commit/6b38ad02e5d73a0df49c4eede7e91331282ece04) - Adds `--host` cli option support.  Thanks @abidlabs!
+- [#396](https://github.com/gradio-app/trackio/pull/396) [`4a4d1ab`](https://github.com/gradio-app/trackio/commit/4a4d1ab85e63d923132a3fa7afa5d90e16431bec) - Fix run selection issue.  Thanks @abidlabs!
+- [#394](https://github.com/gradio-app/trackio/pull/394) [`c47a3a3`](https://github.com/gradio-app/trackio/commit/c47a3a31f8c4b83bce1aa7fc22eeba3d9021ad3d) - Add wandb-compatible API for trackio.  Thanks @abidlabs!
+- [#378](https://github.com/gradio-app/trackio/pull/378) [`b02046a`](https://github.com/gradio-app/trackio/commit/b02046a5b0dad7c9854e099a87f884afba4aecb2) - Add JSON export button for line plots and upgrade gradio dependency.  Thanks @JamshedAli18!
+
+## 0.14.2
+
+### Features
+
+- [#386](https://github.com/gradio-app/trackio/pull/386) [`f9452cd`](https://github.com/gradio-app/trackio/commit/f9452cdb8f0819368f3610f7ac0ed08957305275) - Fixing some issues related to deployed Trackio Spaces.  Thanks @abidlabs!
+
+## 0.14.1
+
+### Features
+
+- [#382](https://github.com/gradio-app/trackio/pull/382) [`44fe9bb`](https://github.com/gradio-app/trackio/commit/44fe9bb264fb2aafb0ec302ff15227c045819a2c) - Fix app file path when Trackio is not installed from source.  Thanks @abidlabs!
+- [#380](https://github.com/gradio-app/trackio/pull/380) [`c3f4cff`](https://github.com/gradio-app/trackio/commit/c3f4cff74bc5676e812773d8571454894fcdc7cc) - Add CLI commands for querying projects, runs, and metrics.  Thanks @abidlabs!
+
+## 0.14.0
+
+### Features
+
+- [#377](https://github.com/gradio-app/trackio/pull/377) [`5c5015b`](https://github.com/gradio-app/trackio/commit/5c5015b68c85c5de51111dad983f735c27b9a05f) - fixed wrapping issue in Runs table.  Thanks @gaganchapa!
+- [#374](https://github.com/gradio-app/trackio/pull/374) [`388e26b`](https://github.com/gradio-app/trackio/commit/388e26b9e9f24cd7ad203affe9b709be885b3d24) - Save Optimized Parquet files.  Thanks @lhoestq!
+- [#371](https://github.com/gradio-app/trackio/pull/371) [`fbace9c`](https://github.com/gradio-app/trackio/commit/fbace9cd7732c166f34d268f54b05bb06846cc5d) - Add GPU metrics logging.  Thanks @kashif!
+- [#367](https://github.com/gradio-app/trackio/pull/367) [`862840c`](https://github.com/gradio-app/trackio/commit/862840c13e30fc960cbee5b9eac4d3c25beba9de) - Add option to only show latest run, and fix the double logo issue.  Thanks @abidlabs!
+
+## 0.13.1
+
+### Features
+
+- [#369](https://github.com/gradio-app/trackio/pull/369) [`767e9fe`](https://github.com/gradio-app/trackio/commit/767e9fe095d7c6ed102016caf927c1517fb8618c) - tiny pr removing unnecessary code.  Thanks @abidlabs!
+
+## 0.13.0
+
+### Features
+
+- [#358](https://github.com/gradio-app/trackio/pull/358) [`073715d`](https://github.com/gradio-app/trackio/commit/073715d1caf8282f68890117f09c3ac301205312) - Improvements to `trackio.sync()`.  Thanks @abidlabs!
+
+## 0.12.0
+
+### Features
+
+- [#357](https://github.com/gradio-app/trackio/pull/357) [`02ba815`](https://github.com/gradio-app/trackio/commit/02ba815358060f1966052de051a5bdb09702920e) - Redesign media and tables to show up on separate page.  Thanks @abidlabs!
+- [#359](https://github.com/gradio-app/trackio/pull/359) [`08fe9c9`](https://github.com/gradio-app/trackio/commit/08fe9c9ddd7fe99ee811555fdfb62df9ab88e939) - docs: Improve docstrings.  Thanks @qgallouedec!
+
+## 0.11.0
+
+### Features
+
+- [#355](https://github.com/gradio-app/trackio/pull/355) [`ea51f49`](https://github.com/gradio-app/trackio/commit/ea51f4954922f21be76ef828700420fe9a912c4b) - Color code run checkboxes and match with plot lines.  Thanks @abidlabs!
+- [#353](https://github.com/gradio-app/trackio/pull/353) [`8abe691`](https://github.com/gradio-app/trackio/commit/8abe6919aeefe21fc7a23af814883efbb037c21f) - Remove show_api from demo.launch.  Thanks @sergiopaniego!
+- [#351](https://github.com/gradio-app/trackio/pull/351) [`8a8957e`](https://github.com/gradio-app/trackio/commit/8a8957e530dd7908d1fef7f2df030303f808101f) - Add `trackio.save()`.  Thanks @abidlabs!
+
+## 0.10.0
+
+### Features
+
+- [#305](https://github.com/gradio-app/trackio/pull/305) [`e64883a`](https://github.com/gradio-app/trackio/commit/e64883a51f7b8b93f7d48b8afe55acdb62238b71) - bump to gradio 6.0, make `trackio` compatible, and fix related issues.  Thanks @abidlabs!
+
+## 0.9.1
+
+### Features
+
+- [#344](https://github.com/gradio-app/trackio/pull/344) [`7e01024`](https://github.com/gradio-app/trackio/commit/7e010241d9a34794e0ce0dc19c1a6f0cf94ba856) - Avoid redundant calls to /whoami-v2.  Thanks @Wauplin!
+
+## 0.9.0
+
+### Features
+
+- [#343](https://github.com/gradio-app/trackio/pull/343) [`51bea30`](https://github.com/gradio-app/trackio/commit/51bea30f2877adff8e6497466d3a799400a0a049) - Sync offline projects to Hugging Face spaces.  Thanks @candemircan!
+- [#341](https://github.com/gradio-app/trackio/pull/341) [`4fd841f`](https://github.com/gradio-app/trackio/commit/4fd841fa190e15071b02f6fba7683ef4f393a654) - Adds a basic UI test to `trackio`.  Thanks @abidlabs!
+- [#339](https://github.com/gradio-app/trackio/pull/339) [`011d91b`](https://github.com/gradio-app/trackio/commit/011d91bb6ae266516fd250a349285670a8049d05) - Allow customzing the trackio color palette.  Thanks @abidlabs!
+
+## 0.8.1
+
+### Features
+
+- [#336](https://github.com/gradio-app/trackio/pull/336) [`5f9f51d`](https://github.com/gradio-app/trackio/commit/5f9f51dac8677f240d7c42c3e3b2660a22aee138) - Support a list of `Trackio.Image` in a `trackio.Table` cell.  Thanks @abidlabs!
+
+## 0.8.0
+
+### Features
+
+- [#331](https://github.com/gradio-app/trackio/pull/331) [`2c02d0f`](https://github.com/gradio-app/trackio/commit/2c02d0fd0a5824160528782402bb0dd4083396d5) - Truncate table string values that are greater than 250 characters (configuirable via env variable).  Thanks @abidlabs!
+- [#324](https://github.com/gradio-app/trackio/pull/324) [`50b2122`](https://github.com/gradio-app/trackio/commit/50b2122e7965ac82a72e6cb3b7d048bc10a2a6b1) - Add log y-axis functionality to UI.  Thanks @abidlabs!
+- [#326](https://github.com/gradio-app/trackio/pull/326) [`61dc1f4`](https://github.com/gradio-app/trackio/commit/61dc1f40af2f545f8e70395ddf0dbb8aee6b60d5) - Fix: improve table rendering for metrics in Trackio Dashboard.  Thanks @vigneshwaran!
+- [#328](https://github.com/gradio-app/trackio/pull/328) [`6857cbb`](https://github.com/gradio-app/trackio/commit/6857cbbe557a59a4642f210ec42566d108294e63) - Support trackio.Table with trackio.Image columns.  Thanks @abidlabs!
+- [#323](https://github.com/gradio-app/trackio/pull/323) [`6857cbb`](https://github.com/gradio-app/trackio/commit/6857cbbe557a59a4642f210ec42566d108294e63) - add Trackio client implementations in Go, Rust, and JS.  Thanks @vaibhav-research!
+
+## 0.7.0
+
+### Features
+
+- [#277](https://github.com/gradio-app/trackio/pull/277) [`db35601`](https://github.com/gradio-app/trackio/commit/db35601b9c023423c4654c9909b8ab73e58737de) - fix: make grouped runs view reflect live updates.  Thanks @Saba9!
+- [#320](https://github.com/gradio-app/trackio/pull/320) [`24ae739`](https://github.com/gradio-app/trackio/commit/24ae73969b09fb3126acd2f91647cdfbf8cf72a1) - Add additional query parms for xmin, xmax, and smoothing.  Thanks @abidlabs!
+- [#270](https://github.com/gradio-app/trackio/pull/270) [`cd1dfc3`](https://github.com/gradio-app/trackio/commit/cd1dfc3dc641b4499ac6d4a1b066fa8e2b52c57b) - feature: add support for logging audio.  Thanks @Saba9!
+
+## 0.6.0
+
+### Features
+
+- [#309](https://github.com/gradio-app/trackio/pull/309) [`1df2353`](https://github.com/gradio-app/trackio/commit/1df23534d6c01938c8db9c0f584ffa23e8d6021d) - Add histogram support with wandb-compatible API.  Thanks @abidlabs!
+- [#315](https://github.com/gradio-app/trackio/pull/315) [`76ba060`](https://github.com/gradio-app/trackio/commit/76ba06055dc43ca8f03b79f3e72d761949bd19a8) - Add guards to avoid silent fails.  Thanks @Xmaster6y!
+- [#313](https://github.com/gradio-app/trackio/pull/313) [`a606b3e`](https://github.com/gradio-app/trackio/commit/a606b3e1c5edf3d4cf9f31bd50605226a5a1c5d0) - No longer prevent certain keys from being used. Instead, dunderify them to prevent collisions with internal usage.  Thanks @abidlabs!
+- [#317](https://github.com/gradio-app/trackio/pull/317) [`27370a5`](https://github.com/gradio-app/trackio/commit/27370a595d0dbdf7eebbe7159d2ba778f039da44) - quick fixes for trackio.histogram.  Thanks @abidlabs!
+- [#312](https://github.com/gradio-app/trackio/pull/312) [`aa0f3bf`](https://github.com/gradio-app/trackio/commit/aa0f3bf372e7a0dd592a38af699c998363830eeb) - Fix video logging by adding TRACKIO_DIR to allowed_paths.  Thanks @abidlabs!
+
+## 0.5.3
+
+### Features
+
+- [#300](https://github.com/gradio-app/trackio/pull/300) [`5e4cacf`](https://github.com/gradio-app/trackio/commit/5e4cacf2e7ce527b4ce60de3a5bc05d2c02c77fb) - Adds more environment variables to allow customization of Trackio dashboard.  Thanks @abidlabs!
+
+## 0.5.2
+
+### Features
+
+- [#293](https://github.com/gradio-app/trackio/pull/293) [`64afc28`](https://github.com/gradio-app/trackio/commit/64afc28d3ea1dfd821472dc6bf0b8ed35a9b74be) - Ensures that the TRACKIO_DIR environment variable is respected.  Thanks @abidlabs!
+- [#287](https://github.com/gradio-app/trackio/pull/287) [`cd3e929`](https://github.com/gradio-app/trackio/commit/cd3e9294320949e6b8b829239069a43d5d7ff4c1) - fix(sqlite): unify .sqlite extension, allow export when DBs exist, clean WAL sidecars on import.  Thanks @vaibhav-research!
+
+### Fixes
+
+- [#291](https://github.com/gradio-app/trackio/pull/291) [`3b5adc3`](https://github.com/gradio-app/trackio/commit/3b5adc3d1f452dbab7a714d235f4974782f93730) - Fix the wheel build.  Thanks @pngwn!
+
+## 0.5.1
+
+### Fixes
+
+- [#278](https://github.com/gradio-app/trackio/pull/278) [`314c054`](https://github.com/gradio-app/trackio/commit/314c05438007ddfea3383e06fd19143e27468e2d) - Fix row orientation of metrics plots.  Thanks @abidlabs!

trackio/__init__.py

@@ -0,0 +1,1216 @@
+import atexit
+import glob
+import json
+import logging
+import os
+import shutil
+import warnings
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+import huggingface_hub
+from gradio_client import handle_file
+from huggingface_hub import SpaceStorage
+from huggingface_hub.errors import LocalTokenNotFoundError
+
+from trackio import context_vars, deploy, utils
+from trackio.alerts import AlertLevel
+from trackio.api import Api
+from trackio.apple_gpu import apple_gpu_available
+from trackio.apple_gpu import log_apple_gpu as _log_apple_gpu
+from trackio.artifact import Artifact
+from trackio.cpu import cpu_available
+from trackio.cpu import log_cpu as _log_cpu
+from trackio.deploy import freeze, sync
+from trackio.frontend_config import resolve_frontend_dir
+from trackio.gpu import gpu_available
+from trackio.gpu import log_gpu as _log_nvidia_gpu
+from trackio.histogram import Histogram
+from trackio.imports import import_csv, import_tf_events
+from trackio.launch import launch_trackio_dashboard
+from trackio.markdown import Markdown
+from trackio.media import (
+    TrackioAudio,
+    TrackioImage,
+    TrackioVideo,
+    get_project_media_path,
+)
+from trackio.references import (
+    ReferenceHandler,
+    ResolvedReference,
+    register_reference_handler,
+)
+from trackio.remote_client import RemoteClient
+from trackio.run import Run
+from trackio.server import TrackioDashboardApp, build_starlette_app_only
+from trackio.sqlite_storage import SQLiteStorage
+from trackio.table import Table
+from trackio.trace import Trace
+from trackio.typehints import UploadEntry
+from trackio.utils import TRACKIO_DIR, TRACKIO_LOGO_DIR, _emit_nonfatal_warning
+
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
+__version__ = json.loads(Path(__file__).parent.joinpath("package.json").read_text())[
+    "version"
+]
+
+
+class _TupleNoPrint(tuple):
+    def __repr__(self) -> str:
+        return ""
+
+
+__all__ = [
+    "init",
+    "log",
+    "log_system",
+    "log_gpu",
+    "log_artifact",
+    "use_artifact",
+    "log_cpu",
+    "finish",
+    "alert",
+    "AlertLevel",
+    "show",
+    "sync",
+    "freeze",
+    "delete_project",
+    "import_csv",
+    "import_tf_events",
+    "save",
+    "Artifact",
+    "ReferenceHandler",
+    "ResolvedReference",
+    "register_reference_handler",
+    "Image",
+    "Video",
+    "Audio",
+    "Table",
+    "Trace",
+    "Histogram",
+    "Markdown",
+    "Api",
+    "TRACKIO_LOGO_DIR",
+]
+
+Audio = TrackioAudio
+Image = TrackioImage
+Video = TrackioVideo
+
+
+config = {}
+
+_atexit_registered = False
+_spaces_created_this_session: set[str] = set()
+_projects_notified_auto_log_hw: set[str] = set()
+
+
+def _cleanup_current_run():
+    run = context_vars.current_run.get()
+    if run is not None:
+        try:
+            run.finish()
+        except Exception:
+            pass
+
+
+def _safe_get_runs_for_init(
+    project: str,
+    space_id: str | None,
+    server_base_url: str | None,
+    write_token: str | None,
+    resume: str,
+    remote_client: RemoteClient | None = None,
+    check_existing_for_never: bool = False,
+) -> list[str]:
+    if space_id is not None or server_base_url is not None:
+        if resume == "never" and not check_existing_for_never:
+            return []
+        if remote_client is not None:
+            source = space_id or server_base_url
+            try:
+                runs = remote_client.predict(
+                    project=project, api_name="/get_runs_for_project"
+                )
+                return runs if isinstance(runs, list) else []
+            except Exception as e:
+                _emit_nonfatal_warning(
+                    f"trackio.init() could not inspect existing runs for project '{project}' on '{source}': {e}. Continuing without resume metadata."
+                )
+                return []
+    try:
+        return SQLiteStorage.get_runs(project)
+    except Exception as e:
+        _emit_nonfatal_warning(
+            f"trackio.init() could not inspect existing runs for project '{project}': {e}. Continuing without resume metadata."
+        )
+        return []
+
+
+def _safe_get_latest_run_for_init(
+    project: str,
+    name: str,
+    space_id: str | None = None,
+    server_base_url: str | None = None,
+    write_token: str | None = None,
+    remote_client: RemoteClient | None = None,
+) -> dict | None:
+    if (
+        space_id is not None or server_base_url is not None
+    ) and remote_client is not None:
+        source = space_id or server_base_url
+        try:
+            runs = remote_client.predict(
+                project=project, api_name="/get_runs_for_project"
+            )
+            if not isinstance(runs, list):
+                return None
+            matches = [r for r in runs if isinstance(r, dict) and r.get("name") == name]
+            if not matches:
+                return None
+            matches.sort(key=lambda r: r.get("created_at") or "", reverse=True)
+            return matches[0]
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not inspect existing runs for project '{project}' on '{source}': {e}. Continuing without resume metadata."
+            )
+            return None
+    try:
+        return SQLiteStorage.get_latest_run_record_by_name(project, name)
+    except Exception as e:
+        _emit_nonfatal_warning(
+            f"trackio.init() could not inspect existing runs for project '{project}': {e}. Continuing without resume metadata."
+        )
+        return None
+
+
+def _safe_get_last_step_for_init(
+    project: str,
+    run_name: str,
+    space_id: str | None,
+    server_base_url: str | None,
+    write_token: str | None,
+    resumed: bool,
+    run_id: str | None = None,
+    remote_client: RemoteClient | None = None,
+) -> int | None:
+    if not resumed:
+        return None
+    if (
+        space_id is not None or server_base_url is not None
+    ) and remote_client is not None:
+        source = space_id or server_base_url
+        try:
+            summary_kwargs: dict[str, Any] = {
+                "project": project,
+                "api_name": "/get_run_summary",
+            }
+            if run_id is not None:
+                summary_kwargs["run_id"] = run_id
+            else:
+                summary_kwargs["run"] = run_name
+            summary = remote_client.predict(**summary_kwargs)
+            if isinstance(summary, dict):
+                last_step = summary.get("last_step")
+                return last_step if isinstance(last_step, int) else None
+            return None
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not recover the previous step for run '{run_name}' on '{source}': {e}. Continuing from step 0."
+            )
+            return None
+    try:
+        return SQLiteStorage.get_max_step_for_run(project, run_name, run_id=run_id)
+    except Exception as e:
+        _emit_nonfatal_warning(
+            f"trackio.init() could not recover the previous step for run '{run_name}': {e}. Continuing from step 0."
+        )
+        return None
+
+
+def init(
+    project: str,
+    name: str | None = None,
+    group: str | None = None,
+    space_id: str | None = None,
+    server_url: str | None = None,
+    space_storage: SpaceStorage | None = None,
+    dataset_id: str | None = None,
+    bucket_id: str | None = None,
+    config: dict | None = None,
+    resume: str = "never",
+    settings: Any = None,
+    private: bool | None = None,
+    embed: bool = True,
+    auto_log_gpu: bool | None = None,
+    gpu_log_interval: float = 10.0,
+    auto_log_cpu: bool | None = None,
+    cpu_log_interval: float = 10.0,
+    webhook_url: str | None = None,
+    webhook_min_level: AlertLevel | str | None = None,
+) -> Run:
+    """
+    Creates a new Trackio project and returns a [`Run`] object.
+
+    Args:
+        project (`str`):
+            The name of the project (can be an existing project to continue tracking or
+            a new project to start tracking from scratch).
+        name (`str`, *optional*):
+            The name of the run (if not provided, a default name will be generated).
+        group (`str`, *optional*):
+            The name of the group which this run belongs to in order to help organize
+            related runs together. You can toggle the entire group's visibility in the
+            dashboard.
+        space_id (`str`, *optional*):
+            If provided, the project will be logged to a Hugging Face Space instead of
+            a local directory. Should be a complete Space name like
+            `"username/reponame"` or `"orgname/reponame"`, or just `"reponame"` in which
+            case the Space will be created in the currently-logged-in Hugging Face
+            user's namespace. If the Space does not exist, it will be created. If the
+            Space already exists, the project will be logged to it. Can also be set
+            via the `TRACKIO_SPACE_ID` environment variable. You cannot log to a
+            Space that has been **frozen** (converted to the static SDK); use
+            ``trackio.sync(..., sdk="static")`` only after you are done logging.
+            Takes precedence over `server_url` and `TRACKIO_SERVER_URL` when more than
+            one is set.
+        server_url (`str`, *optional*):
+            Base URL of a self-hosted Trackio server (``http://`` or ``https://``), or the
+            write-access URL from ``trackio.show()`` which may include a ``write_token`` query
+            parameter. The client sends that token on each request (``X-Trackio-Write-Token``);
+            you can also set ``TRACKIO_WRITE_TOKEN`` instead of embedding the token in the URL.
+            When set, metrics are sent to that server over HTTP instead of creating or syncing
+            to a Hugging Face Space. Can also be set via the ``TRACKIO_SERVER_URL`` environment
+            variable. Ignored when ``space_id`` or ``TRACKIO_SPACE_ID`` is set.
+        space_storage ([`~huggingface_hub.SpaceStorage`], *optional*):
+            Choice of persistent storage tier.
+        dataset_id (`str`, *optional*):
+            Deprecated. Use `bucket_id` instead.
+        bucket_id (`str`, *optional*):
+            The ID of the Hugging Face Bucket to use for metric persistence. By default,
+            when a `space_id` is provided and `bucket_id` is not explicitly set, a
+            bucket is auto-generated from the space_id. Buckets provide
+            S3-like storage without git overhead - the SQLite database is stored directly
+            via `hf-mount` in the Space. Specify a Bucket with name like
+            `"username/bucketname"` or just `"bucketname"`.
+        config (`dict`, *optional*):
+            A dictionary of configuration options. Provided for compatibility with
+            `wandb.init()`.
+        resume (`str`, *optional*, defaults to `"never"`):
+            Controls how to handle resuming a run. Can be one of:
+
+            - `"must"`: Must resume the run with the given name, raises error if run
+              doesn't exist
+            - `"allow"`: Resume the run if it exists, otherwise create a new run
+            - `"never"`: Never resume a run, always create a new one
+        private (`bool`, *optional*):
+            Whether to make the Space private. If None (default), the repo will be
+            public unless the organization's default is private. This value is ignored
+            if the repo already exists.
+        settings (`Any`, *optional*):
+            Not used. Provided for compatibility with `wandb.init()`.
+        embed (`bool`, *optional*, defaults to `True`):
+            If running inside a Jupyter/Colab notebook, whether the dashboard should
+            automatically be embedded in the cell when trackio.init() is called. For
+            local runs, this launches a local Trackio dashboard and embeds it. For Space runs,
+            this embeds the Space URL. In Colab, the local dashboard will be accessible
+            via a public share URL when `share=True`.
+        auto_log_gpu (`bool` or `None`, *optional*, defaults to `None`):
+            Controls automatic GPU metrics logging. If `None` (default), GPU logging
+            is automatically enabled when `nvidia-ml-py` is installed and an NVIDIA
+            GPU or Apple M series is detected. Set to `True` to force enable or
+            `False` to disable.
+        gpu_log_interval (`float`, *optional*, defaults to `10.0`):
+            The interval in seconds between automatic GPU metric logs.
+            Only used when `auto_log_gpu=True`.
+        auto_log_cpu (`bool` or `None`, *optional*, defaults to `None`):
+            Controls automatic CPU and RAM metrics logging (utilization, memory,
+            disk I/O, network I/O, and sensors). If `None` (default), CPU logging
+            is automatically enabled when `psutil` is installed. Set to `True` to
+            force enable or `False` to disable.
+        cpu_log_interval (`float`, *optional*, defaults to `10.0`):
+            The interval in seconds between automatic CPU metric logs.
+            Only used when CPU auto-logging is enabled.
+        webhook_url (`str`, *optional*):
+            A webhook URL to POST alert payloads to when `trackio.alert()` is
+            called. Supports Slack and Discord webhook URLs natively (payloads
+            are formatted automatically). Can also be set via the
+            `TRACKIO_WEBHOOK_URL` environment variable. Individual alerts can
+            override this URL by passing `webhook_url` to `trackio.alert()`.
+        webhook_min_level (`AlertLevel` or `str`, *optional*):
+            Minimum alert level that should trigger webhook delivery.
+            For example, `AlertLevel.WARN` sends only `WARN` and `ERROR`
+            alerts to the webhook destination. Can also be set via
+            `TRACKIO_WEBHOOK_MIN_LEVEL`.
+    Returns:
+        `Run`: A [`Run`] object that can be used to log metrics and finish the run.
+    """
+    SQLiteStorage.validate_project_name(project)
+
+    if settings is not None:
+        _emit_nonfatal_warning(
+            "* Warning: settings is not used. Provided for compatibility with wandb.init(). Please create an issue at: https://github.com/gradio-app/trackio/issues if you need a specific feature implemented."
+        )
+
+    previous_run = context_vars.current_run.get()
+    if previous_run is not None:
+        try:
+            previous_run.finish()
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not finish the previous run '{previous_run.name}': {e}. Continuing with new run."
+            )
+        context_vars.current_run.set(None)
+
+    bucket_id_was_explicit = bucket_id is not None
+    space_id, server_url = utils.resolve_space_id_and_server_url(space_id, server_url)
+    if bucket_id is None and utils.on_spaces():
+        bucket_id = os.environ.get("TRACKIO_BUCKET_ID")
+    if server_url is not None and not server_url.startswith(("http://", "https://")):
+        raise ValueError(
+            f"`server_url` must be a full URL starting with http:// or https://, got: {server_url!r}"
+        )
+    server_base_url: str | None = None
+    write_token_resolved: str | None = None
+    if server_url is not None:
+        server_base_url, tok = utils.parse_trackio_server_url(server_url)
+        write_token_resolved = tok or os.environ.get("TRACKIO_WRITE_TOKEN")
+        if not write_token_resolved:
+            raise ValueError(
+                "Self-hosted logging requires a write token: add write_token to the server URL, "
+                "or set the TRACKIO_WRITE_TOKEN environment variable."
+            )
+    if server_url is not None and (dataset_id is not None or bucket_id is not None):
+        raise ValueError(
+            "`dataset_id` and `bucket_id` are Hugging Face Spaces concepts and are not "
+            "compatible with `server_url`. Configure storage on the self-hosted server."
+        )
+    if space_id is None and dataset_id is not None:
+        raise ValueError("Must provide a `space_id` when `dataset_id` is provided.")
+    if dataset_id is not None and bucket_id is not None:
+        raise ValueError("Cannot provide both `dataset_id` and `bucket_id`.")
+    try:
+        space_id, dataset_id, bucket_id = utils.preprocess_space_and_dataset_ids(
+            space_id, dataset_id, bucket_id
+        )
+        if (
+            space_id is not None
+            and dataset_id is None
+            and bucket_id is not None
+            and not bucket_id_was_explicit
+            and not utils.on_spaces()
+        ):
+            bucket_id = deploy.resolve_auto_bucket_id(space_id, bucket_id)
+    except LocalTokenNotFoundError as e:
+        raise LocalTokenNotFoundError(
+            f"You must be logged in to Hugging Face locally when `space_id` is provided to deploy to a Space. {e}"
+        ) from e
+
+    if space_id is None and bucket_id is not None:
+        _emit_nonfatal_warning(
+            "trackio.init() has `bucket_id` set but `space_id` is None: metrics will be logged "
+            "locally only. Pass `space_id` to create or use a Hugging Face Space, which will be "
+            "attached to the Hugging Face Bucket.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    if space_id is not None:
+        deploy.raise_if_space_is_frozen_for_logging(space_id)
+
+    remote_source = space_id or server_base_url
+
+    if remote_source is not None:
+        url = remote_source
+        context_vars.current_server.set(url)
+        if space_id is not None:
+            context_vars.current_space_id.set(space_id)
+            context_vars.current_server_write_token.set(None)
+        else:
+            context_vars.current_space_id.set(None)
+            context_vars.current_server_write_token.set(write_token_resolved)
+    else:
+        url = None
+        context_vars.current_server.set(None)
+        context_vars.current_space_id.set(None)
+        context_vars.current_server_write_token.set(None)
+
+    _should_embed_local = False
+
+    newly_created_space = False
+    if space_id is not None and space_id in _spaces_created_this_session:
+        if deploy.space_is_running(space_id):
+            _spaces_created_this_session.discard(space_id)
+        else:
+            newly_created_space = True
+
+    if (
+        context_vars.current_project.get() is None
+        or context_vars.current_project.get() != project
+    ):
+        print(f"* Trackio project initialized: {project}")
+
+        if bucket_id is not None:
+            if utils.on_spaces():
+                os.environ["TRACKIO_BUCKET_ID"] = bucket_id
+            bucket_url = f"https://huggingface.co/buckets/{bucket_id}"
+            print(
+                f"* Trackio metrics will be synced to Hugging Face Bucket: {bucket_url}"
+            )
+        elif dataset_id is not None:
+            if utils.on_spaces():
+                os.environ["TRACKIO_DATASET_ID"] = dataset_id
+            print(
+                f"* Trackio metrics will be synced to Hugging Face Dataset: {dataset_id}"
+            )
+        if remote_source is None:
+            print(f"* Trackio metrics logged to: {TRACKIO_DIR}")
+            _should_embed_local = embed and utils.is_in_notebook()
+            if not _should_embed_local:
+                utils.print_dashboard_instructions(project)
+        elif server_base_url is not None:
+            print(
+                f"* Trackio metrics will be sent to self-hosted server: {server_base_url}"
+            )
+            if utils.is_in_notebook() and embed:
+                utils.embed_url_in_notebook(server_base_url)
+        else:
+            try:
+                if deploy.create_space_if_not_exists(
+                    space_id,
+                    space_storage,
+                    dataset_id,
+                    bucket_id,
+                    private,
+                ):
+                    _spaces_created_this_session.add(space_id)
+                    newly_created_space = True
+                user_name, space_name = space_id.split("/")
+                space_url = deploy.SPACE_HOST_URL.format(
+                    user_name=user_name, space_name=space_name
+                )
+                if utils.is_in_notebook() and embed:
+                    utils.embed_url_in_notebook(space_url)
+            except Exception as e:
+                _emit_nonfatal_warning(
+                    f"trackio.init() could not prepare Space '{space_id}': {e}. Logging will continue in local fallback mode until the Space is reachable."
+                )
+    context_vars.current_project.set(project)
+
+    remote_client = None
+    if space_id is not None and not newly_created_space:
+        try:
+            remote_client = RemoteClient(
+                space_id,
+                hf_token=huggingface_hub.utils.get_token(),
+                verbose=False,
+            )
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not create a remote client for Space '{space_id}': {e}. Continuing with local fallback metadata lookups."
+            )
+    elif server_base_url is not None:
+        try:
+            remote_client = RemoteClient(
+                server_base_url,
+                hf_token=None,
+                write_token=write_token_resolved,
+                verbose=False,
+            )
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not create a remote client for '{server_base_url}': {e}. Continuing with local fallback metadata lookups."
+            )
+
+    existing_run_records = _safe_get_runs_for_init(
+        project,
+        space_id,
+        server_base_url,
+        write_token_resolved,
+        resume,
+        remote_client=remote_client,
+        check_existing_for_never=name is not None,
+    )
+    existing_runs = [
+        r["name"] if isinstance(r, dict) else r for r in existing_run_records
+    ]
+
+    existing_run = (
+        _safe_get_latest_run_for_init(
+            project,
+            name,
+            space_id=space_id,
+            server_base_url=server_base_url,
+            write_token=write_token_resolved,
+            remote_client=remote_client,
+        )
+        if name is not None
+        else None
+    )
+    resolved_run_id = None
+
+    if resume == "must":
+        if name is None:
+            raise ValueError("Must provide a run name when resume='must'")
+        if existing_run is None:
+            raise ValueError(f"Run '{name}' does not exist in project '{project}'")
+        resumed = True
+        resolved_run_id = existing_run["id"]
+    elif resume == "allow":
+        resumed = existing_run is not None
+        if resumed:
+            resolved_run_id = existing_run["id"]
+    elif resume == "never":
+        resumed = False
+    else:
+        raise ValueError("resume must be one of: 'must', 'allow', or 'never'")
+
+    initial_last_step = (
+        _safe_get_last_step_for_init(
+            project,
+            name,
+            space_id,
+            server_base_url,
+            write_token_resolved,
+            resumed,
+            run_id=resolved_run_id,
+            remote_client=remote_client,
+        )
+        if name is not None
+        else None
+    )
+
+    auto_log_cpu_detected = False
+    if auto_log_cpu is None:
+        auto_log_cpu_detected = cpu_available()
+        auto_log_cpu = auto_log_cpu_detected
+
+    auto_log_gpu_detected = False
+    nvidia_available = False
+    apple_available = False
+    if auto_log_gpu is None:
+        nvidia_available = gpu_available()
+        apple_available = apple_gpu_available()
+        auto_log_gpu_detected = nvidia_available or apple_available
+        auto_log_gpu = auto_log_gpu_detected
+
+    if project not in _projects_notified_auto_log_hw:
+        if nvidia_available:
+            print("* NVIDIA GPU detected, enabling automatic GPU metrics logging")
+        elif apple_available:
+            print(
+                "* Apple Silicon detected, enabling automatic GPU/system metrics logging"
+            )
+        if auto_log_cpu_detected:
+            print("* psutil detected, enabling automatic CPU/system metrics logging")
+        if auto_log_gpu_detected or auto_log_cpu_detected:
+            _projects_notified_auto_log_hw.add(project)
+
+    run = Run(
+        url=url,
+        project=project,
+        client=None,
+        name=name,
+        run_id=resolved_run_id,
+        group=group,
+        config=config,
+        space_id=space_id,
+        bucket_id=bucket_id,
+        server_base_url=server_base_url,
+        write_token=write_token_resolved,
+        existing_runs=existing_runs,
+        initial_last_step=initial_last_step,
+        auto_log_gpu=auto_log_gpu,
+        gpu_log_interval=gpu_log_interval,
+        auto_log_cpu=auto_log_cpu,
+        cpu_log_interval=cpu_log_interval,
+        webhook_url=webhook_url,
+        webhook_min_level=webhook_min_level,
+    )
+
+    if space_id is not None:
+        try:
+            SQLiteStorage.set_project_metadata(project, "space_id", space_id)
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not persist Space metadata for project '{project}': {e}. Logging will continue."
+            )
+        try:
+            if SQLiteStorage.has_pending_data(project):
+                run._has_local_buffer = True
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not inspect pending buffered data for project '{project}': {e}. Logging will continue."
+            )
+
+    global _atexit_registered
+    if not _atexit_registered:
+        atexit.register(_cleanup_current_run)
+        _atexit_registered = True
+
+    if resumed:
+        print(f"* Resumed existing run: {run.name}")
+    else:
+        print(f"* Created new run: {run.name}")
+
+    context_vars.current_run.set(run)
+    globals()["config"] = run.config
+
+    if space_id is not None or server_url is None:
+        try:
+            from trackio import logbook as _logbook  # noqa: PLC0415
+
+            _logbook.auto_note_dashboard(project, space_id=space_id)
+        except Exception:
+            pass
+
+    if _should_embed_local:
+        try:
+            show(project=project, open_browser=False, block_thread=False)
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not auto-launch the dashboard: {e}. Logging will continue."
+            )
+
+    return run
+
+
+def log(metrics: dict, step: int | None = None) -> None:
+    """
+    Logs metrics to the current run.
+
+    Args:
+        metrics (`dict`):
+            A dictionary of metrics to log.
+        step (`int`, *optional*):
+            The step number. If not provided, the step will be incremented
+            automatically.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.log().")
+    run.log(
+        metrics=metrics,
+        step=step,
+    )
+
+
+def log_system(metrics: dict) -> None:
+    """
+    Logs system metrics (GPU, etc.) to the current run using timestamps instead of steps.
+
+    Args:
+        metrics (`dict`):
+            A dictionary of system metrics to log.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.log_system().")
+    run.log_system(metrics=metrics)
+
+
+def log_artifact(
+    artifact_or_path: Artifact | str | Path,
+    name: str | None = None,
+    type: str | None = None,
+    aliases: list[str] | None = None,
+) -> Artifact:
+    """
+    Logs an artifact as an output of the current run.
+
+    Args:
+        artifact_or_path (`Artifact`, `str`, or `Path`):
+            The artifact to log (must have at least one file added via
+            `add_file` or `add_dir`), or a path to a file or directory to
+            log as a new artifact.
+        name (`str`, *optional*):
+            Artifact name when logging a path. Defaults to
+            `run-<run_id>-<basename>`. Must not be passed with an `Artifact`.
+        type (`str`, *optional*):
+            Artifact type when logging a path (e.g. `"model"`, `"dataset"`).
+            Defaults to `"unspecified"`. Must not be passed with an
+            `Artifact`.
+        aliases (`list[str]`, *optional*):
+            Aliases to rotate onto the resulting version, alongside `latest`
+            (assigned automatically whenever a new version is created). Your
+            aliases rotate onto the version even when identical content is
+            de-duplicated.
+
+    Returns:
+        The logged `Artifact` instance, hydrated with `version`, `aliases`,
+        `size`, `manifest`, and `project` set.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.log_artifact().")
+    return run.log_artifact(artifact_or_path, name=name, type=type, aliases=aliases)
+
+
+def use_artifact(
+    artifact_or_name: Artifact | str,
+    type: str | None = None,
+) -> Artifact:
+    """
+    Fetches an artifact and records it as an input to the current run.
+
+    Args:
+        artifact_or_name (`Artifact` or `str`):
+            An already-logged `Artifact`, or an artifact name. A bare name
+            (`"my-model"`) resolves to `:latest`; you can also pin a version
+            (`"my-model:v3"`) or resolve an alias (`"my-model:prod"`).
+        type (`str`, *optional*):
+            If given, checked against the stored artifact type, raising if it
+            does not match.
+
+    Returns:
+        The fetched `Artifact`, hydrated and ready to `download()`.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.use_artifact().")
+    return run.use_artifact(artifact_or_name, type=type)
+
+
+def log_gpu(run: Run | None = None, device: int | None = None) -> dict:
+    """
+    Log GPU metrics to the current or specified run as system metrics.
+    Automatically detects whether an NVIDIA or Apple GPU is available and calls
+    the appropriate logging method.
+
+    Args:
+        run: Optional Run instance. If None, uses current run from context.
+        device: CUDA device index to collect metrics from (NVIDIA GPUs only).
+                If None, collects from all GPUs visible to this process.
+                This parameter is ignored for Apple GPUs.
+
+    Returns:
+        dict: The GPU metrics that were logged.
+
+    Example:
+        ```python
+        import trackio
+
+        run = trackio.init(project="my-project")
+        trackio.log({"loss": 0.5})
+        trackio.log_gpu()
+        trackio.log_gpu(device=0)
+        ```
+    """
+    if run is None:
+        run = context_vars.current_run.get()
+        if run is None:
+            raise RuntimeError("Call trackio.init() before trackio.log_gpu().")
+
+    if gpu_available():
+        return _log_nvidia_gpu(run=run, device=device)
+    elif apple_gpu_available():
+        return _log_apple_gpu(run=run)
+    else:
+        _emit_nonfatal_warning(
+            "No GPU detected. Install nvidia-ml-py for NVIDIA GPU support "
+            "or psutil for Apple Silicon support."
+        )
+        return {}
+
+
+def log_cpu(run: Run | None = None) -> dict:
+    """
+    Log CPU, RAM, disk, network, and sensor metrics to the current or specified run
+    as system metrics.
+
+    Args:
+        run: Optional Run instance. If None, uses current run from context.
+
+    Returns:
+        dict: The CPU and system metrics that were logged.
+
+    Example:
+        ```python
+        import trackio
+
+        run = trackio.init(project="my-project")
+        trackio.log({"loss": 0.5})
+        trackio.log_cpu()
+        ```
+    """
+    if run is None:
+        run = context_vars.current_run.get()
+        if run is None:
+            raise RuntimeError("Call trackio.init() before trackio.log_cpu().")
+
+    return _log_cpu(run=run)
+
+
+def finish():
+    """
+    Finishes the current run.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.finish().")
+    try:
+        run.finish()
+    finally:
+        context_vars.current_run.set(None)
+
+
+def alert(
+    title: str,
+    text: str | None = None,
+    level: AlertLevel = AlertLevel.WARN,
+    webhook_url: str | None = None,
+) -> None:
+    """
+    Fires an alert immediately on the current run. The alert is printed to the
+    terminal, stored in the database, and displayed in the dashboard. If a
+    webhook URL is configured (via `trackio.init()`, the `TRACKIO_WEBHOOK_URL`
+    environment variable, or the `webhook_url` parameter here), the alert is
+    also POSTed to that URL.
+
+    Args:
+        title (`str`):
+            A short title for the alert.
+        text (`str`, *optional*):
+            A longer description with details about the alert.
+        level (`AlertLevel`, *optional*, defaults to `AlertLevel.WARN`):
+            The severity level. One of `AlertLevel.INFO`, `AlertLevel.WARN`,
+            or `AlertLevel.ERROR`.
+        webhook_url (`str`, *optional*):
+            A webhook URL to send this specific alert to. Overrides any
+            URL set in `trackio.init()` or the `TRACKIO_WEBHOOK_URL`
+            environment variable. Supports Slack and Discord webhook
+            URLs natively.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.alert().")
+    run.alert(title=title, text=text, level=level, webhook_url=webhook_url)
+
+
+def delete_project(project: str, force: bool = False) -> bool:
+    """
+    Deletes a project by removing its local SQLite database.
+
+    Args:
+        project (`str`):
+            The name of the project to delete.
+        force (`bool`, *optional*, defaults to `False`):
+            If `True`, deletes the project without prompting for confirmation.
+            If `False`, prompts the user to confirm before deleting.
+
+    Returns:
+        `bool`: `True` if the project was deleted, `False` otherwise.
+    """
+    db_path = SQLiteStorage.get_project_db_path(project)
+
+    if not db_path.exists():
+        print(f"* Project '{project}' does not exist.")
+        return False
+
+    if not force:
+        response = input(
+            f"Are you sure you want to delete project '{project}'? "
+            f"This will permanently delete all runs and metrics. (y/N): "
+        )
+        if response.lower() not in ["y", "yes"]:
+            print("* Deletion cancelled.")
+            return False
+
+    try:
+        db_path.unlink()
+
+        for suffix in ("-wal", "-shm"):
+            sidecar = Path(str(db_path) + suffix)
+            if sidecar.exists():
+                sidecar.unlink()
+
+        for parquet_path in SQLiteStorage._project_parquet_paths(db_path):
+            if parquet_path.exists():
+                parquet_path.unlink()
+
+        for asset_dir in (
+            utils.project_artifacts_dir(project),
+            utils.project_media_dir(project),
+        ):
+            if asset_dir.exists():
+                shutil.rmtree(asset_dir, ignore_errors=True)
+
+        print(f"* Project '{project}' has been deleted.")
+        return True
+    except Exception as e:
+        print(f"* Error deleting project '{project}': {e}")
+        return False
+
+
+def save(
+    glob_str: str | Path,
+    project: str | None = None,
+) -> str:
+    """
+    Saves files to a project (not linked to a specific run). If Trackio is running
+    locally, the file(s) will be copied to the project's files directory. If Trackio is
+    running in a Space, the file(s) will be uploaded to the Space's files directory.
+
+    Args:
+        glob_str (`str` or `Path`):
+            The file path or glob pattern to save. Can be a single file or a pattern
+            matching multiple files (e.g., `"*.py"`, `"models/**/*.pth"`).
+        project (`str`, *optional*):
+            The name of the project to save files to. If not provided, uses the current
+            project from `trackio.init()`. If no project is initialized, raises an
+            error.
+
+    Returns:
+        `str`: The path where the file(s) were saved (project's files directory).
+
+    Example:
+        ```python
+        import trackio
+
+        trackio.init(project="my-project")
+        trackio.save("config.yaml")
+        trackio.save("models/*.pth")
+        ```
+    """
+    if project is None:
+        project = context_vars.current_project.get()
+        if project is None:
+            raise RuntimeError(
+                "No project specified. Either call trackio.init() first or provide a "
+                "project parameter to trackio.save()."
+            )
+
+    glob_str = Path(glob_str)
+    base_path = Path.cwd().resolve()
+
+    matched_files = []
+    if glob_str.is_file():
+        matched_files = [glob_str.resolve()]
+    else:
+        pattern = str(glob_str)
+        if not glob_str.is_absolute():
+            pattern = str((Path.cwd() / glob_str).resolve())
+        matched_files = [
+            Path(f).resolve()
+            for f in glob.glob(pattern, recursive=True)
+            if Path(f).is_file()
+        ]
+
+    if not matched_files:
+        raise ValueError(f"No files found matching pattern: {glob_str}")
+
+    current_run = context_vars.current_run.get()
+    is_local = (
+        current_run._is_local
+        if current_run is not None
+        else (
+            context_vars.current_space_id.get() is None
+            and context_vars.current_server.get() is None
+        )
+    )
+
+    if is_local:
+        for file_path in matched_files:
+            try:
+                relative_to_base = file_path.relative_to(base_path)
+            except ValueError:
+                relative_to_base = Path(file_path.name)
+
+            if current_run is not None:
+                current_run._queue_upload(
+                    file_path,
+                    step=None,
+                    relative_path=str(relative_to_base.parent),
+                    use_run_name=False,
+                )
+            else:
+                media_path = get_project_media_path(
+                    project=project,
+                    run=None,
+                    step=None,
+                    relative_path=str(relative_to_base),
+                )
+                shutil.copy(str(file_path), str(media_path))
+    else:
+        url = context_vars.current_server.get()
+
+        upload_entries = []
+        for file_path in matched_files:
+            try:
+                relative_to_base = file_path.relative_to(base_path)
+            except ValueError:
+                relative_to_base = Path(file_path.name)
+
+            if current_run is not None:
+                current_run._queue_upload(
+                    file_path,
+                    step=None,
+                    relative_path=str(relative_to_base.parent),
+                    use_run_name=False,
+                )
+            else:
+                upload_entry: UploadEntry = {
+                    "project": project,
+                    "run": None,
+                    "step": None,
+                    "relative_path": str(relative_to_base),
+                    "uploaded_file": handle_file(file_path),
+                }
+                upload_entries.append(upload_entry)
+
+        if upload_entries:
+            if url is None:
+                raise RuntimeError(
+                    "No server available. Call trackio.init() before trackio.save() to start the server."
+                )
+
+            try:
+                wt = context_vars.current_server_write_token.get()
+                if wt is not None:
+                    client = RemoteClient(
+                        url,
+                        hf_token=None,
+                        write_token=wt,
+                        httpx_kwargs={"timeout": 90},
+                    )
+                else:
+                    client = RemoteClient(
+                        url,
+                        hf_token=huggingface_hub.utils.get_token(),
+                        httpx_kwargs={"timeout": 90},
+                    )
+                client.predict(
+                    api_name="/bulk_upload_media",
+                    uploads=upload_entries,
+                    hf_token=huggingface_hub.utils.get_token() if wt is None else None,
+                )
+            except Exception as e:
+                _emit_nonfatal_warning(
+                    f"Failed to upload files: {e}. "
+                    "Files may not be available in the dashboard."
+                )
+
+    return str(utils.project_media_dir(project) / "files")
+
+
+def show(
+    project: str | None = None,
+    *,
+    theme: Any = None,
+    mcp_server: bool | None = None,
+    footer: bool = True,
+    color_palette: list[str] | None = None,
+    open_browser: bool = True,
+    block_thread: bool | None = None,
+    host: str | None = None,
+    share: bool | None = None,
+    server_port: int | None = None,
+    frontend_dir: str | Path | None = None,
+):
+    """
+    Launches the Trackio dashboard.
+
+    Args:
+        project (`str`, *optional*):
+            The name of the project whose runs to show. If not provided, all projects
+            will be shown and the user can select one.
+        theme (`Any`, *optional*):
+            Ignored. Kept for backward compatibility; Trackio no longer uses Gradio themes.
+        mcp_server (`bool`, *optional*):
+            If `True`, the dashboard exposes an MCP server at `/mcp` when the optional
+            `trackio[mcp]` dependency is installed. If `None` (default), the
+            `GRADIO_MCP_SERVER` environment variable is used (e.g. on Spaces).
+        footer (`bool`, *optional*, defaults to `True`):
+            Whether to include `footer=false` in the write-token URL when `False`.
+            This can also be controlled via the `footer` query parameter in the URL.
+        color_palette (`list[str]`, *optional*):
+            A list of hex color codes to use for plot lines. If not provided, the
+            `TRACKIO_COLOR_PALETTE` environment variable will be used (comma-separated
+            hex codes), or if that is not set, the default color palette will be used.
+            Example: `['#FF0000', '#00FF00', '#0000FF']`
+        open_browser (`bool`, *optional*, defaults to `True`):
+            If `True` and not in a notebook, a new browser tab will be opened with the
+            dashboard. If `False`, the browser will not be opened.
+        block_thread (`bool`, *optional*):
+            If `True`, the main thread will be blocked until the dashboard is closed.
+            If `None` (default behavior), then the main thread will not be blocked if the
+            dashboard is launched in a notebook, otherwise the main thread will be blocked.
+        host (`str`, *optional*):
+            The host to bind the server to. If not provided, defaults to `'127.0.0.1'`
+            (localhost only). Set to `'0.0.0.0'` to allow remote access.
+        share (`bool`, *optional*):
+            If `True`, creates a temporary public URL (Gradio-compatible tunnel). On Colab
+            or hosted notebooks, defaults to `True` unless overridden.
+        server_port (`int`, *optional*):
+            Port to bind. If not set, scans from `GRADIO_SERVER_PORT` (default 7860).
+        frontend_dir (`str | Path`, *optional*):
+            Directory containing a custom static frontend. Must contain `index.html`.
+            If not provided, Trackio checks `TRACKIO_FRONTEND_DIR`, then the persistent
+            Trackio config, then the bundled frontend. If an explicit `frontend_dir`
+            points to a missing or empty directory, Trackio copies in the starter
+            template and serves that directory.
+
+        Returns:
+            `app`: The dashboard handle (`.close()` stops the server).
+            `url`: The local URL of the dashboard.
+            `share_url`: The public share URL, if any.
+            `full_url`: The full URL including the write token (share URL when sharing, else local).
+    """
+    if theme is not None and theme != "default":
+        warnings.warn(
+            "The theme argument is ignored; Trackio no longer depends on Gradio themes.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    if color_palette is not None:
+        os.environ["TRACKIO_COLOR_PALETTE"] = ",".join(color_palette)
+
+    _mcp_server = (
+        mcp_server
+        if mcp_server is not None
+        else os.environ.get("GRADIO_MCP_SERVER", "False") == "True"
+    )
+
+    resolved_frontend = resolve_frontend_dir(frontend_dir, announce=True)
+    starlette_app, wt = build_starlette_app_only(
+        mcp_server=_mcp_server,
+        frontend_dir=str(resolved_frontend.path),
+    )
+    local_url, share_url, _local_api_url, uv_server = launch_trackio_dashboard(
+        starlette_app,
+        server_name=host,
+        server_port=server_port,
+        share=share,
+        mcp_server=_mcp_server,
+        quiet=True,
+    )
+    server = TrackioDashboardApp(starlette_app, uv_server, wt)
+
+    base_root = (share_url or local_url).rstrip("/")
+    base_url = base_root + "/"
+    dashboard_url = base_url
+    if project:
+        dashboard_url += f"?project={project}"
+    full_url = utils.get_full_url(
+        base_root,
+        project=project,
+        write_token=wt,
+        footer=footer,
+    )
+
+    if not utils.is_in_notebook():
+        print(f"\033[1m\033[38;5;208m* Trackio UI launched at: {dashboard_url}\033[0m")
+        utils.print_write_token_instructions(full_url)
+        if open_browser:
+            webbrowser.open(full_url)
+        block_thread = block_thread if block_thread is not None else True
+    else:
+        utils.embed_url_in_notebook(full_url)
+        block_thread = block_thread if block_thread is not None else False
+
+    if block_thread:
+        utils.block_main_thread_until_keyboard_interrupt()
+    return _TupleNoPrint((server, local_url, share_url, full_url))

trackio/_vendor/gradio_exceptions.py

@@ -0,0 +1,6 @@
+class ChecksumMismatchError(Exception):
+    pass
+
+
+class ShareCertificateWriteError(Exception):
+    pass

trackio/_vendor/networking.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import os
+import time
+import warnings
+from pathlib import Path
+from urllib.parse import urlparse, urlunparse
+
+import httpx
+
+from trackio._vendor.gradio_exceptions import ShareCertificateWriteError
+from trackio._vendor.tunneling import CERTIFICATE_PATH, Tunnel
+
+GRADIO_API_SERVER = "https://api.gradio.app/v3/tunnel-request"
+GRADIO_SHARE_SERVER_ADDRESS = os.getenv("GRADIO_SHARE_SERVER_ADDRESS")
+
+
+def setup_tunnel(
+    local_host: str,
+    local_port: int,
+    share_token: str,
+    share_server_address: str | None,
+    share_server_tls_certificate: str | None,
+) -> str:
+    share_server_address = (
+        GRADIO_SHARE_SERVER_ADDRESS
+        if share_server_address is None
+        else share_server_address
+    )
+    if share_server_address is None:
+        try:
+            response = httpx.get(GRADIO_API_SERVER, timeout=30)
+            payload = response.json()[0]
+            remote_host, remote_port = payload["host"], int(payload["port"])
+            certificate = payload["root_ca"]
+        except Exception as e:
+            raise RuntimeError(
+                "Could not get share link from Gradio API Server."
+            ) from e
+        try:
+            Path(CERTIFICATE_PATH).parent.mkdir(parents=True, exist_ok=True)
+            with open(CERTIFICATE_PATH, "w") as f:
+                f.write(certificate)
+        except Exception as e:
+            raise ShareCertificateWriteError(
+                f"{e}. This can happen if the current working directory is read-only."
+            ) from e
+        share_server_tls_certificate = CERTIFICATE_PATH
+
+    else:
+        remote_host, remote_port = share_server_address.split(":")
+        remote_port = int(remote_port)
+    tunnel = Tunnel(
+        remote_host,
+        remote_port,
+        local_host,
+        local_port,
+        share_token,
+        share_server_tls_certificate,
+    )
+    address = tunnel.start_tunnel()
+    return address
+
+
+def url_ok(url: str) -> bool:
+    try:
+        for _ in range(5):
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore")
+                r = httpx.head(url, timeout=3, verify=False)
+            if r.status_code in (200, 401, 302, 303, 307):
+                return True
+            time.sleep(0.500)
+    except (ConnectionError, httpx.ConnectError, httpx.TimeoutException):
+        return False
+    return False
+
+
+def normalize_share_url(share_url: str, share_server_protocol: str) -> str:
+    parsed_url = urlparse(share_url)
+    return urlunparse((share_server_protocol,) + parsed_url[1:])

trackio/_vendor/tunneling.py

@@ -0,0 +1,191 @@
+import atexit
+import hashlib
+import os
+import platform
+import re
+import stat
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+from huggingface_hub.constants import HF_HOME
+
+from trackio._vendor.gradio_exceptions import ChecksumMismatchError
+
+VERSION = "0.3"
+CURRENT_TUNNELS: list["Tunnel"] = []
+
+machine = platform.machine()
+if machine == "x86_64":
+    machine = "amd64"
+elif machine == "aarch64":
+    machine = "arm64"
+
+BINARY_REMOTE_NAME = f"frpc_{platform.system().lower()}_{machine.lower()}"
+EXTENSION = ".exe" if os.name == "nt" else ""
+BINARY_URL = f"https://cdn-media.huggingface.co/frpc-gradio-{VERSION}/{BINARY_REMOTE_NAME}{EXTENSION}"
+
+CHECKSUMS = {
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_windows_amd64.exe": "14bc0ea470be5d67d79a07412bd21de8a0a179c6ac1116d7764f68e942dc9ceb",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_amd64": "c791d1f047b41ff5885772fc4bf20b797c6059bbd82abb9e31de15e55d6a57c4",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_arm64": "823ced25104de6dc3c9f4798dbb43f20e681207279e6ab89c40e2176ccbf70cd",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_darwin_amd64": "930f8face3365810ce16689da81b7d1941fda4466225a7bbcbced9a2916a6e15",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_darwin_arm64": "dfac50c690aca459ed5158fad8bfbe99f9282baf4166cf7c410a6673fbc1f327",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_arm": "4b563beb2e36c448cc688174e20b53af38dc1ff2b5e362d4ddd1401f2affbfb7",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_freebsd_386": "cb0a56c764ecf96dd54ed601d240c564f060ee4e58202d65ffca17c1a51ce19c",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_freebsd_amd64": "516d9e6903513869a011ddcd1ec206167ad1eb5dd6640d21057acc258edecbbb",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_386": "4c2f2a48cd71571498c0ac8a4d42a055f22cb7f14b4b5a2b0d584220fd60a283",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_mips": "b309ecd594d4f0f7f33e556a80d4b67aef9319c00a8334648a618e56b23cb9e0",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_mips64": "0372ef5505baa6f3b64c6295a86541b24b7b0dbe4ef28b344992e21f47624b7b",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_riscv64": "1658eed7e8c14ea76e1d95749d58441ce24147c3d559381832c725c29cfc3df3",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_mipsle": "a2aaba16961d3372b79bd7a28976fcd0f0bbaebc2b50d5a7a71af2240747960f",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_windows_386.exe": "721b90550195a83e15f2176d8f85a48d5a25822757cb872e9723d4bccc4e5bb6",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_mips64le": "796481edd609f31962b45cc0ab4c9798d040205ae3bf354ed1b72fb432d796b8",
+}
+
+CHUNK_SIZE = 128
+
+BINARY_FILENAME = f"{BINARY_REMOTE_NAME}_v{VERSION}"
+BINARY_FOLDER = Path(HF_HOME) / "trackio" / "frpc"
+BINARY_PATH = str(BINARY_FOLDER / BINARY_FILENAME)
+
+TUNNEL_TIMEOUT_SECONDS = 30
+TUNNEL_ERROR_MESSAGE = (
+    "Could not create share URL. "
+    "Please check the appended log from frpc for more information:"
+)
+
+CERTIFICATE_PATH = ".trackio/certificate.pem"
+
+
+class Tunnel:
+    def __init__(
+        self,
+        remote_host: str,
+        remote_port: int,
+        local_host: str,
+        local_port: int,
+        share_token: str,
+        share_server_tls_certificate: str | None,
+    ):
+        self.proc = None
+        self.url = None
+        self.remote_host = remote_host
+        self.remote_port = remote_port
+        self.local_host = local_host
+        self.local_port = local_port
+        self.share_token = share_token
+        self.share_server_tls_certificate = share_server_tls_certificate
+
+    @staticmethod
+    def download_binary():
+        if not Path(BINARY_PATH).exists():
+            Path(BINARY_FOLDER).mkdir(parents=True, exist_ok=True)
+            resp = httpx.get(BINARY_URL, timeout=30)
+
+            if resp.status_code == 403:
+                raise OSError(
+                    f"Cannot set up a share link as this platform is incompatible. Please "
+                    f"create a GitHub issue with information about your platform: {platform.uname()}"
+                )
+
+            resp.raise_for_status()
+
+            with open(BINARY_PATH, "wb") as file:
+                file.write(resp.content)
+            st = os.stat(BINARY_PATH)
+            os.chmod(BINARY_PATH, st.st_mode | stat.S_IEXEC)
+
+            if BINARY_URL in CHECKSUMS:
+                sha = hashlib.sha256()
+                with open(BINARY_PATH, "rb") as f:
+                    for chunk in iter(lambda: f.read(CHUNK_SIZE * sha.block_size), b""):
+                        sha.update(chunk)
+                calculated_hash = sha.hexdigest()
+
+                if calculated_hash != CHECKSUMS[BINARY_URL]:
+                    raise ChecksumMismatchError()
+
+    def start_tunnel(self) -> str:
+        self.download_binary()
+        self.url = self._start_tunnel(BINARY_PATH)
+        return self.url
+
+    def kill(self):
+        if self.proc is not None:
+            print(f"Killing tunnel {self.local_host}:{self.local_port} <> {self.url}")
+            self.proc.terminate()
+            self.proc = None
+
+    def _start_tunnel(self, binary: str) -> str:
+        CURRENT_TUNNELS.append(self)
+        command = [
+            binary,
+            "http",
+            "-n",
+            self.share_token,
+            "-l",
+            str(self.local_port),
+            "-i",
+            self.local_host,
+            "--uc",
+            "--sd",
+            "random",
+            "--ue",
+            "--server_addr",
+            f"{self.remote_host}:{self.remote_port}",
+            "--disable_log_color",
+        ]
+        if self.share_server_tls_certificate is not None:
+            command.extend(
+                [
+                    "--tls_enable",
+                    "--tls_trusted_ca_file",
+                    self.share_server_tls_certificate,
+                ]
+            )
+        self.proc = subprocess.Popen(
+            command, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        )
+        atexit.register(self.kill)
+        return self._read_url_from_tunnel_stream()
+
+    def _read_url_from_tunnel_stream(self) -> str:
+        start_timestamp = time.time()
+
+        log = []
+        url = ""
+
+        def _raise_tunnel_error():
+            log_text = "\n".join(log)
+            print(log_text, file=sys.stderr)
+            raise ValueError(f"{TUNNEL_ERROR_MESSAGE}\n{log_text}")
+
+        while url == "":
+            if time.time() - start_timestamp >= TUNNEL_TIMEOUT_SECONDS:
+                _raise_tunnel_error()
+
+            assert self.proc is not None  # noqa: S101
+            if self.proc.stdout is None:
+                continue
+
+            line = self.proc.stdout.readline()
+            line = line.decode("utf-8")
+
+            if line == "":
+                continue
+
+            log.append(line.strip())
+
+            if "start proxy success" in line:
+                result = re.search("start proxy success: (.+)\n", line)
+                if result is None:
+                    _raise_tunnel_error()
+                else:
+                    url = result.group(1)
+            elif "login to server failed" in line:
+                _raise_tunnel_error()
+
+        return url

trackio/alerts.py

@@ -0,0 +1,184 @@
+import json
+import logging
+import ssl
+import urllib.request
+from enum import Enum
+
+try:
+    import certifi
+
+    _SSL_CONTEXT = ssl.create_default_context(cafile=certifi.where())
+except ImportError:
+    _SSL_CONTEXT = None
+
+logger = logging.getLogger(__name__)
+
+
+class AlertLevel(str, Enum):
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+
+
+ALERT_LEVEL_ORDER = {
+    AlertLevel.INFO: 0,
+    AlertLevel.WARN: 1,
+    AlertLevel.ERROR: 2,
+}
+
+ALERT_COLORS = {
+    AlertLevel.INFO: "\033[94m",
+    AlertLevel.WARN: "\033[93m",
+    AlertLevel.ERROR: "\033[91m",
+}
+RESET_COLOR = "\033[0m"
+
+LEVEL_EMOJI = {
+    AlertLevel.INFO: "ℹ️",
+    AlertLevel.WARN: "⚠️",
+    AlertLevel.ERROR: "🚨",
+}
+
+
+def format_alert_terminal(
+    level: AlertLevel, title: str, text: str | None, step: int | None
+) -> str:
+    color = ALERT_COLORS.get(level, "")
+    step_str = f" (step {step})" if step is not None else ""
+    if text:
+        return f"{color}[TRACKIO {level.value.upper()}]{RESET_COLOR} {title}: {text}{step_str}"
+    return f"{color}[TRACKIO {level.value.upper()}]{RESET_COLOR} {title}{step_str}"
+
+
+def _is_slack_url(url: str) -> bool:
+    return "hooks.slack.com" in url
+
+
+def _is_discord_url(url: str) -> bool:
+    return "discord.com/api/webhooks" in url or "discordapp.com/api/webhooks" in url
+
+
+def _build_slack_payload(
+    level: AlertLevel,
+    title: str,
+    text: str | None,
+    project: str,
+    run: str,
+    step: int | None,
+) -> dict:
+    emoji = LEVEL_EMOJI.get(level, "")
+    step_str = f"  •  Step {step}" if step is not None else ""
+    header = f"{emoji} *[{level.value.upper()}] {title}*"
+    context = f"Project: {project}  •  Run: {run}{step_str}"
+    blocks = [
+        {"type": "section", "text": {"type": "mrkdwn", "text": header}},
+    ]
+    if text:
+        blocks.append({"type": "section", "text": {"type": "mrkdwn", "text": text}})
+    blocks.append(
+        {"type": "context", "elements": [{"type": "mrkdwn", "text": context}]}
+    )
+    return {"blocks": blocks}
+
+
+def _build_discord_payload(
+    level: AlertLevel,
+    title: str,
+    text: str | None,
+    project: str,
+    run: str,
+    step: int | None,
+) -> dict:
+    color_map = {
+        AlertLevel.INFO: 3447003,
+        AlertLevel.WARN: 16776960,
+        AlertLevel.ERROR: 15158332,
+    }
+    emoji = LEVEL_EMOJI.get(level, "")
+    step_str = f"  •  Step {step}" if step is not None else ""
+    embed = {
+        "title": f"{emoji} [{level.value.upper()}] {title}",
+        "color": color_map.get(level, 0),
+        "footer": {"text": f"Project: {project}  •  Run: {run}{step_str}"},
+    }
+    if text:
+        embed["description"] = text
+    return {"embeds": [embed]}
+
+
+def _build_generic_payload(
+    level: AlertLevel,
+    title: str,
+    text: str | None,
+    project: str,
+    run: str,
+    step: int | None,
+    timestamp: str | None,
+) -> dict:
+    return {
+        "level": level.value,
+        "title": title,
+        "text": text,
+        "project": project,
+        "run": run,
+        "step": step,
+        "timestamp": timestamp,
+    }
+
+
+def parse_alert_level(level: AlertLevel | str) -> AlertLevel:
+    if isinstance(level, AlertLevel):
+        return level
+    normalized = level.lower().strip()
+    try:
+        return AlertLevel(normalized)
+    except ValueError as e:
+        allowed = ", ".join(lvl.value for lvl in AlertLevel)
+        raise ValueError(
+            f"Invalid alert level '{level}'. Expected one of: {allowed}."
+        ) from e
+
+
+def resolve_webhook_min_level(
+    webhook_min_level: AlertLevel | str | None,
+) -> AlertLevel | None:
+    if webhook_min_level is None:
+        return None
+    return parse_alert_level(webhook_min_level)
+
+
+def should_send_webhook(
+    level: AlertLevel, webhook_min_level: AlertLevel | None
+) -> bool:
+    if webhook_min_level is None:
+        return True
+    return ALERT_LEVEL_ORDER[level] >= ALERT_LEVEL_ORDER[webhook_min_level]
+
+
+def send_webhook(
+    url: str,
+    level: AlertLevel,
+    title: str,
+    text: str | None,
+    project: str,
+    run: str,
+    step: int | None,
+    timestamp: str | None = None,
+) -> None:
+    if _is_slack_url(url):
+        payload = _build_slack_payload(level, title, text, project, run, step)
+    elif _is_discord_url(url):
+        payload = _build_discord_payload(level, title, text, project, run, step)
+    else:
+        payload = _build_generic_payload(
+            level, title, text, project, run, step, timestamp
+        )
+
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data, headers={"Content-Type": "application/json"}
+    )
+    try:
+        urllib.request.urlopen(req, timeout=10, context=_SSL_CONTEXT)
+    except Exception as e:
+        logger.warning(f"Failed to send webhook to {url}: {e}")

trackio/api.py

@@ -0,0 +1,99 @@
+from typing import Iterator
+
+from trackio.sqlite_storage import SQLiteStorage
+
+
+class Run:
+    def __init__(self, project: str, name: str, run_id: str | None = None):
+        self.project = project
+        self.name = name
+        self._id = run_id or name
+        self._config = None
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def config(self) -> dict | None:
+        if self._config is None:
+            self._config = SQLiteStorage.get_run_config(
+                self.project, self.name, run_id=self.id
+            )
+        return self._config
+
+    def alerts(self, level: str | None = None, since: str | None = None) -> list[dict]:
+        return SQLiteStorage.get_alerts(
+            self.project, run_name=self.name, run_id=self.id, level=level, since=since
+        )
+
+    def delete(self) -> bool:
+        return SQLiteStorage.delete_run(self.project, self.name, run_id=self.id)
+
+    def move(self, new_project: str) -> bool:
+        success = SQLiteStorage.move_run(
+            self.project, self.name, new_project, run_id=self.id
+        )
+        if success:
+            self.project = new_project
+        return success
+
+    def rename(self, new_name: str) -> "Run":
+        SQLiteStorage.rename_run(self.project, self.name, new_name, run_id=self.id)
+        self.name = new_name
+        return self
+
+    def __repr__(self) -> str:
+        return f"<Run {self.name} in project {self.project}>"
+
+
+class Runs:
+    def __init__(self, project: str):
+        self.project = project
+        self._runs = None
+
+    def _load_runs(self):
+        if self._runs is None:
+            records = SQLiteStorage.get_run_records(self.project)
+            self._runs = [
+                Run(
+                    self.project,
+                    str(record["name"]),
+                    run_id=str(record["id"]) if record["id"] is not None else None,
+                )
+                for record in records
+            ]
+
+    def __iter__(self) -> Iterator[Run]:
+        self._load_runs()
+        return iter(self._runs)
+
+    def __getitem__(self, index: int) -> Run:
+        self._load_runs()
+        return self._runs[index]
+
+    def __len__(self) -> int:
+        self._load_runs()
+        return len(self._runs)
+
+    def __repr__(self) -> str:
+        self._load_runs()
+        return f"<Runs project={self.project} count={len(self._runs)}>"
+
+
+class Api:
+    def runs(self, project: str) -> Runs:
+        if not SQLiteStorage.get_project_db_path(project).exists():
+            raise ValueError(f"Project '{project}' does not exist")
+        return Runs(project)
+
+    def alerts(
+        self,
+        project: str,
+        run: str | None = None,
+        level: str | None = None,
+        since: str | None = None,
+    ) -> list[dict]:
+        if not SQLiteStorage.get_project_db_path(project).exists():
+            raise ValueError(f"Project '{project}' does not exist")
+        return SQLiteStorage.get_alerts(project, run_name=run, level=level, since=since)

trackio/apple_gpu.py

@@ -0,0 +1,206 @@
+import platform
+import subprocess
+import sys
+import threading
+import warnings
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from trackio.run import Run
+
+psutil: Any = None
+PSUTIL_AVAILABLE = False
+_monitor_lock = threading.Lock()
+
+
+def _ensure_psutil():
+    global PSUTIL_AVAILABLE, psutil
+    if PSUTIL_AVAILABLE:
+        return psutil
+    try:
+        import psutil as _psutil
+
+        psutil = _psutil
+        PSUTIL_AVAILABLE = True
+        return psutil
+    except ImportError:
+        raise ImportError(
+            "psutil is required for Apple Silicon monitoring. "
+            "Install it with: pip install psutil"
+        )
+
+
+def is_apple_silicon() -> bool:
+    """Check if running on Apple Silicon (M1/M2/M3/M4)."""
+    if platform.system() != "Darwin":
+        return False
+
+    try:
+        result = subprocess.run(
+            ["sysctl", "-n", "machdep.cpu.brand_string"],
+            capture_output=True,
+            text=True,
+            timeout=1,
+        )
+        cpu_brand = result.stdout.strip()
+        return "Apple" in cpu_brand
+    except Exception:
+        return False
+
+
+def get_gpu_info() -> dict[str, Any]:
+    """Get Apple GPU information using ioreg."""
+    try:
+        result = subprocess.run(
+            ["ioreg", "-r", "-d", "1", "-w", "0", "-c", "IOAccelerator"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+
+        if result.returncode == 0 and result.stdout:
+            lines = result.stdout.strip().split("\n")
+            for line in lines:
+                if "IOAccelerator" in line and "class" in line:
+                    return {"detected": True, "type": "Apple GPU"}
+        else:
+            print("Error collecting Apple GPU info. ioreg stdout was:", file=sys.stderr)
+            print(result.stdout, file=sys.stderr)
+            print("ioreg stderr was:", file=sys.stderr)
+            print(result.stderr, file=sys.stderr)
+
+        result = subprocess.run(
+            ["system_profiler", "SPDisplaysDataType"],
+            capture_output=True,
+            text=True,
+            timeout=3,
+        )
+
+        if result.returncode == 0 and "Apple" in result.stdout:
+            for line in result.stdout.split("\n"):
+                if "Chipset Model:" in line:
+                    model = line.split(":")[-1].strip()
+                    return {"detected": True, "type": model}
+
+    except Exception:
+        pass
+
+    return {"detected": False}
+
+
+def apple_gpu_available() -> bool:
+    """
+    Check if Apple GPU monitoring is available.
+
+    Returns True if running on Apple Silicon (M-series chips) and psutil is installed.
+    """
+    try:
+        _ensure_psutil()
+        return is_apple_silicon()
+    except ImportError:
+        return False
+    except Exception:
+        return False
+
+
+def collect_apple_metrics(include_cpu_metrics: bool = True) -> dict:
+    """
+    Collect system metrics for Apple Silicon.
+
+    Returns:
+        Dictionary of system metrics including CPU, memory, and GPU info.
+    """
+    metrics = {}
+
+    if include_cpu_metrics:
+        from trackio.cpu import collect_cpu_metrics
+
+        metrics.update(collect_cpu_metrics(include_static=True))
+
+    gpu_info = get_gpu_info()
+    if gpu_info.get("detected"):
+        metrics["gpu/detected"] = 1
+
+    return metrics
+
+
+class AppleGpuMonitor:
+    def __init__(
+        self, run: "Run", interval: float = 10.0, include_cpu_metrics: bool = True
+    ):
+        self._run = run
+        self._interval = interval
+        self._include_cpu_metrics = include_cpu_metrics
+        self._stop_flag = threading.Event()
+        self._thread: "threading.Thread | None" = None
+
+    def start(self):
+        if not is_apple_silicon():
+            warnings.warn(
+                "auto_log_gpu=True but not running on Apple Silicon. "
+                "Apple GPU logging disabled."
+            )
+            return
+
+        if not PSUTIL_AVAILABLE:
+            try:
+                _ensure_psutil()
+            except ImportError:
+                warnings.warn(
+                    "auto_log_gpu=True but psutil not installed. "
+                    "Install with: pip install psutil"
+                )
+                return
+
+        self._thread = threading.Thread(target=self._monitor_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_flag.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+
+    def _monitor_loop(self):
+        while not self._stop_flag.is_set():
+            try:
+                metrics = collect_apple_metrics(
+                    include_cpu_metrics=self._include_cpu_metrics
+                )
+                if metrics:
+                    self._run.log_system(metrics)
+            except Exception:
+                pass
+
+            self._stop_flag.wait(timeout=self._interval)
+
+
+def log_apple_gpu(run: "Run | None" = None) -> dict:
+    """
+    Log Apple Silicon system metrics to the current or specified run.
+
+    Args:
+        run: Optional Run instance. If None, uses current run from context.
+
+    Returns:
+        dict: The system metrics that were logged.
+
+    Example:
+        ```python
+        import trackio
+
+        run = trackio.init(project="my-project")
+        trackio.log({"loss": 0.5})
+        trackio.log_apple_gpu()
+        ```
+    """
+    from trackio import context_vars
+
+    if run is None:
+        run = context_vars.current_run.get()
+        if run is None:
+            raise RuntimeError("Call trackio.init() before trackio.log_apple_gpu().")
+
+    metrics = collect_apple_metrics()
+    if metrics:
+        run.log_system(metrics)
+    return metrics

trackio/artifact.py

@@ -0,0 +1,552 @@
+import os
+import shutil
+from pathlib import Path
+
+import httpx
+from huggingface_hub.utils import get_token
+
+from trackio import cas, references, utils
+from trackio.remote_client import _merge_client_headers, _resolve_src_url
+from trackio.typehints import ETag, Manifest, ManifestEntry, Sha256Digest, URIStr
+
+
+def _materialize(blob: Path, dst: Path, size: int) -> None:
+    """Copy `blob` to `dst` unless `dst` already matches the blob's size and
+    mtime.
+    """
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    blob_stat = blob.stat()
+    if dst.is_file():
+        dst_stat = dst.stat()
+        if dst_stat.st_size == size and dst_stat.st_mtime_ns == blob_stat.st_mtime_ns:
+            return
+    partial = dst.parent / cas.partial_blob_name(dst.name)
+    try:
+        shutil.copyfile(blob, partial)
+        os.utime(partial, ns=(blob_stat.st_atime_ns, blob_stat.st_mtime_ns))
+        os.replace(partial, dst)
+    except Exception:
+        partial.unlink(missing_ok=True)
+        raise
+
+
+def _fetch_blob_from_remote(
+    remote_source: dict,
+    project: str,
+    digest: Sha256Digest,
+    target_path: Path,
+) -> None:
+    space_id = remote_source.get("space_id")
+    src = space_id or remote_source.get("server_base_url")
+    if not src:
+        raise RuntimeError(
+            "Artifact has _remote_source set but neither space_id nor "
+            "server_base_url is populated."
+        )
+    base_url = _resolve_src_url(src).rstrip("/")
+    url = f"{base_url}/artifact_blob/{utils.canonical_project_name(project)}/{digest}"
+    headers = _merge_client_headers(
+        get_token() if space_id else None,
+        remote_source.get("write_token"),
+    )
+    with httpx.stream(
+        "GET",
+        url,
+        headers=headers,
+        timeout=httpx.Timeout(connect=10.0, read=300.0, write=10.0, pool=10.0),
+    ) as response:
+        if response.status_code == 404:
+            raise FileNotFoundError(
+                f"Artifact blob {digest} not available on remote at {url}"
+            )
+        response.raise_for_status()
+        cas.stage_blob_from_chunks(
+            response.iter_bytes(),
+            claimed_digest=digest,
+            target_path=target_path,
+        )
+
+
+def _materialize_reference(
+    uri: str, scheme: str, dest: Path, digest: Sha256Digest | ETag | URIStr
+) -> None:
+    """Fetch the object at `uri` into `dest`, idempotently and atomically.
+
+    If `dest` already exists it is left untouched and nothing is fetched:
+    reference digests are opaque, so a file already present is assumed current
+    (mirroring the size/mtime idempotence of `_materialize`), letting a repeated
+    `download()` skip references already on disk.
+
+    Otherwise, when a real checksum was recorded, the source is re-probed and
+    compared. When the digest doesn't exist, or when it cannot be re-probed,
+    the comparison is skipped and the artifact is still materialized.
+    """
+    if dest.is_file():
+        return
+    if len(digest) > 0 and digest != uri:
+        try:
+            resolved = references.resolve_reference(
+                uri, scheme, checksum=True, max_objects=1
+            )[0]
+        except Exception:
+            resolved = None
+        current_digest = resolved.digest if resolved is not None else None
+        if current_digest is not None and current_digest != digest:
+            utils._emit_nonfatal_warning(
+                f"Reference {uri!r} may have changed since it was logged "
+                f"(recorded digest {digest}, current {current_digest})."
+            )
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    partial = dest.parent / cas.partial_blob_name(dest.name)
+    try:
+        references.fetch_reference(uri, scheme, partial)
+        os.replace(partial, dest)
+    except Exception:
+        partial.unlink(missing_ok=True)
+        raise
+
+
+class Artifact:
+    """
+    A versioned, named bundle of files and references attached to a project.
+
+    Construct an `Artifact`, add files to it with `add_file` / `add_dir`
+    (bytes staged into content-addressed storage) or `add_reference` (an
+    external URI recorded without copying any bytes), then persist it with
+    `trackio.log_artifact`. Logging freezes the artifact and populates its
+    read-only `version`, `aliases`, `size`, and `manifest`.
+
+    Args:
+        name (`str`):
+            Artifact name, unique within the project. Must match
+            `^[A-Za-z0-9._-]+$` (letters, digits, dot, underscore, hyphen).
+        type (`str`):
+            Free-form category such as `"model"` or `"dataset"`, used to group
+            artifacts.
+        description (`str`, *optional*):
+            Human-readable description of the artifact.
+        metadata (`dict`, *optional*):
+            Arbitrary JSON-serializable metadata stored alongside the version.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        type: str,
+        description: str | None = None,
+        metadata: dict | None = None,
+    ):
+        cas.validate_artifact_name(name)
+        self._name = name
+        self._type = type
+        self._description = description
+        self._metadata: dict = dict(metadata) if metadata else {}
+        self._pending_files: list[tuple[Path, str]] = []
+        self._pending_references: list[
+            tuple[str, str, Sha256Digest | ETag | URIStr, int]
+        ] = []
+        self._logged = False
+        self._version: int | None = None
+        self._aliases: tuple[str, ...] = ()
+        self._size: int | None = None
+        self._manifest: Manifest | None = None
+        self._manifest_digest: Sha256Digest | None = None
+        self._project: str | None = None
+        self._remote_source: dict | None = None
+
+    @property
+    def name(self) -> str:
+        """Artifact name, unique within its project."""
+        return self._name
+
+    @property
+    def type(self) -> str:
+        """Free-form category such as `"model"` or `"dataset"`."""
+        return self._type
+
+    @property
+    def description(self) -> str | None:
+        """Human-readable description, or None if unset."""
+        return self._description
+
+    @description.setter
+    def description(self, value: str | None) -> None:
+        self._description = value
+
+    @property
+    def metadata(self) -> dict:
+        """Live, mutable metadata dict; assignments like `art.metadata["k"] = v`
+        made before logging are preserved."""
+        return self._metadata
+
+    @metadata.setter
+    def metadata(self, value: dict | None) -> None:
+        self._metadata = dict(value) if value else {}
+
+    @property
+    def version(self) -> str | None:
+        """Version string in `"v<N>"` form (e.g. `"v3"`), or None if the
+        artifact has not been logged or fetched yet."""
+        return None if self._version is None else f"v{self._version}"
+
+    @property
+    def aliases(self) -> tuple[str, ...]:
+        """Aliases pointing at this version, e.g. `("latest", "prod")`."""
+        return self._aliases
+
+    @property
+    def size(self) -> int | None:
+        """Total size in bytes of the artifact's files plus any referenced data
+        whose size is known, or None if not yet logged."""
+        return self._size
+
+    @property
+    def manifest(self) -> Manifest | None:
+        """List of manifest entries describing the artifact's contents, or None
+        if not yet logged or fetched. File entries carry `path`, `digest`, and
+        `size`; reference entries carry `path`, `ref` (a URI), `size`, and a
+        `digest` — a sha256 for local/LFS references, the provider's opaque ETag
+        for HTTP or object-store references, or the URI itself when no checksum
+        is available. Returns a fresh copy on each access."""
+        return None if self._manifest is None else [dict(e) for e in self._manifest]
+
+    @property
+    def manifest_digest(self) -> Sha256Digest | None:
+        """Digest over the manifest (file paths plus their content), used to
+        de-duplicate re-logged content; None until logged or fetched."""
+        return self._manifest_digest
+
+    @property
+    def digest(self) -> Sha256Digest | None:
+        """Alias of `manifest_digest`."""
+        return self._manifest_digest
+
+    @property
+    def qualified_name(self) -> str:
+        """`"<project>/<name>:v<N>"` for a logged or fetched artifact."""
+        if self._project is None or self._version is None:
+            raise RuntimeError(
+                "Artifact has no qualified name until it is logged or fetched."
+            )
+        return f"{self._project}/{self._name}:v{self._version}"
+
+    @property
+    def project(self) -> str | None:
+        """Project the artifact belongs to, or None until logged or fetched."""
+        return self._project
+
+    def wait(self, timeout: int | None = None) -> "Artifact":
+        """No-op: trackio logs artifacts synchronously, so the artifact is
+        already committed by the time `log_artifact` returns."""
+        if not self._logged:
+            raise RuntimeError(
+                "Cannot wait on an Artifact that has not been logged; "
+                "call log_artifact first."
+            )
+        return self
+
+    def add_file(self, local_path: str | Path, name: str | None = None) -> None:
+        """Stage a single file for inclusion in the artifact.
+
+        Args:
+            local_path (`str` or `Path`):
+                Path to an existing regular file to add.
+            name (`str`, *optional*):
+                Logical path the file is stored under inside the artifact.
+                Defaults to the file's basename.
+        """
+        if self._logged:
+            raise RuntimeError(
+                "Cannot add files to an Artifact that has already been logged or fetched."
+            )
+        src = Path(local_path).resolve()
+        if not src.is_file():
+            raise ValueError(f"Not a regular file: {local_path}")
+        logical = cas.validate_logical_path(name if name is not None else src.name)
+        self._pending_files.append((src, logical))
+
+    def add_dir(self, local_dir: str | Path, name: str | None = None) -> None:
+        """Stage every regular file under a directory, recursively.
+
+        Symlinks are skipped.
+
+        Args:
+            local_dir (`str` or `Path`):
+                Path to an existing directory whose files are added.
+            name (`str`, *optional*):
+                Logical path prefix for the added files. Defaults to no prefix,
+                so files keep their paths relative to `local_dir`.
+        """
+        if self._logged:
+            raise RuntimeError(
+                "Cannot add files to an Artifact that has already been logged or fetched."
+            )
+        root = Path(local_dir).resolve()
+        if not root.is_dir():
+            raise ValueError(f"Not a directory: {local_dir}")
+        prefix = cas.validate_logical_path(name.rstrip("/")) + "/" if name else ""
+        for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+            dirnames.sort()
+            for filename in sorted(filenames):
+                entry = Path(dirpath) / filename
+                if entry.is_symlink() or not entry.is_file():
+                    continue
+                rel = entry.relative_to(root).as_posix()
+                logical = cas.validate_logical_path(prefix + rel)
+                self._pending_files.append((entry, logical))
+
+    def add_reference(
+        self,
+        uri: str,
+        name: str | None = None,
+        checksum: bool = True,
+        max_objects: int | None = None,
+    ) -> None:
+        """Stage a reference to external data, without copying any bytes.
+
+        Unlike `add_file`/`add_dir`, a reference records the data's URI (plus,
+        when available, a size and checksum) *without staging the bytes into
+        the content-addressed store*. This is how you version and track
+        lineage over large or already-durably-stored datasets that must not be
+        duplicated.
+
+        A URI that denotes a directory (`file://`, `hf://`, or a prefix
+        expanded by a custom handler) is expanded into one entry per object,
+        capped by `max_objects`. Reference bytes are never uploaded to a Space
+        or bucket.
+
+        The URI is stored verbatim in the artifact manifest, and manifests may
+        be synced to a shared Hugging Face Dataset — so a signed URI triggers a
+        warning for security reasons; please prefer the object's canonical
+        unsigned URI (e.g. `s3://bucket/key`).
+
+        Args:
+            uri (`str`):
+                Location of the referenced data, percent-encoded (build local
+                URIs with `pathlib.Path.as_uri()`). `file://`, `http(s)://`,
+                and `hf://` are resolved and fetched natively; any other scheme
+                (`s3://`, `gs://`, Azure blob URLs, ...) requires a custom
+                `ReferenceHandler` registered via
+                `trackio.register_reference_handler` — see the artifacts
+                documentation for complete examples — and raises otherwise.
+            name (`str`, *optional*):
+                Logical path the reference is stored under. Defaults to the last
+                segment of `uri`; for an expanded prefix (ending with /) it is the
+                prefix under which each object's relative path is nested.
+            checksum (`bool`, *optional*, defaults to `True`):
+                When `True`, probes the source to derive its size and a
+                checksum (and to expand a directory/prefix): `file://` is
+                stream-hashed to a sha256, `hf://` uses its LFS sha256 or git
+                blob id, and `http(s)://` uses the server `ETag`. This may read
+                the filesystem or make network requests. When no checksum can
+                be obtained for a *remote* source (e.g. no ETag), the URI
+                itself is used as the `digest` and a warning is emitted. A
+                local `file://` path that does not exist instead raises. Pass
+                `checksum=False` to skip remote probing entirely.
+            max_objects (`int`, *optional*):
+                Cap on how many objects a directory/prefix expands into (default
+                10,000); exceeding it raises.
+        """
+        if self._logged:
+            raise RuntimeError(
+                "Cannot add references to an Artifact that has already been "
+                "logged or fetched."
+            )
+        scheme, normalized = references.validate_reference_uri(uri)
+        if references.looks_signed(normalized):
+            utils._emit_nonfatal_warning(
+                f"Reference {uri!r} looks like a signed URL, and the full URI "
+                "(embedded credential included) is stored in the artifact "
+                "manifest, which may be synced to a shared HF Dataset. Prefer "
+                "the object's canonical unsigned URI (e.g. s3://bucket/key or "
+                "the URL without its signed query string)."
+            )
+        cap = references.DEFAULT_MAX_OBJECTS if max_objects is None else max_objects
+        resolved = references.resolve_reference(normalized, scheme, checksum, cap)
+        if not resolved:
+            raise ValueError(f"Reference URI {uri!r} matched no objects.")
+        used_uri_fallback = False
+        name_prefix = f"{name.rstrip('/')}/" if name is not None else ""
+        for entry in resolved:
+            if entry.relkey is None:
+                logical = self._reference_logical_name(name, entry.uri, uri)
+            else:
+                logical = cas.validate_logical_path(name_prefix + entry.relkey)
+            ref_digest: Sha256Digest | ETag | URIStr | None = entry.digest
+            if ref_digest is None:
+                ref_digest = URIStr(entry.uri)
+                used_uri_fallback = True
+            ref_size = 0 if entry.size is None else entry.size
+            self._pending_references.append((logical, entry.uri, ref_digest, ref_size))
+        if checksum and used_uri_fallback:
+            utils._emit_nonfatal_warning(
+                f"Reference {uri!r} was recorded without a content checksum, so its "
+                "version identity is its URI; re-logging changed content at the same "
+                "location will reuse the existing version instead of creating a new "
+                f"one. {references.checksum_hint(scheme, normalized)}"
+            )
+
+    @staticmethod
+    def _reference_logical_name(name: str | None, resolved_uri: str, uri: str) -> str:
+        if name is not None:
+            return cas.validate_logical_path(name)
+        derived = references.default_reference_name(resolved_uri)
+        if not derived:
+            raise ValueError(
+                f"Could not derive a name from URI {uri!r}; pass name= explicitly."
+            )
+        return cas.validate_logical_path(derived)
+
+    def _build_manifest(self, project: str) -> Manifest:
+        if not self._pending_files and not self._pending_references:
+            raise ValueError(
+                f"Artifact {self._name!r} has no files or references; "
+                "call add_file/add_dir/add_reference first."
+            )
+        cas.assert_manifest_paths_compatible(
+            [logical for _, logical in self._pending_files]
+            + [logical for logical, *_ in self._pending_references]
+        )
+
+        entries: Manifest = []
+        for src, logical in self._pending_files:
+            digest, size = cas.stage_blob_into_project(src, project)
+            entries.append({"path": logical, "digest": digest, "size": size})
+        for logical, uri, ref_digest, ref_size in self._pending_references:
+            entry: ManifestEntry = {
+                "path": logical,
+                "ref": uri,
+                "digest": ref_digest,
+                "size": ref_size,
+            }
+            entries.append(entry)
+        return entries
+
+    def _hydrate_from_db(
+        self,
+        *,
+        project: str,
+        version: int,
+        aliases: list[str],
+        manifest: Manifest,
+        manifest_digest: Sha256Digest,
+        size_bytes: int,
+        description: str | None = None,
+        metadata: dict | None = None,
+    ) -> None:
+        if description is not None:
+            self._description = description
+        if metadata is not None:
+            self._metadata = dict(metadata)
+        self._project = project
+        self._version = version
+        self._aliases = tuple(aliases)
+        self._manifest = [dict(e) for e in manifest]
+        self._manifest_digest = manifest_digest
+        self._size = size_bytes
+        self._logged = True
+
+    def download(self, root: str | Path | None = None) -> str:
+        """Materialize the artifact's files into a local directory.
+
+        Files are copied from Trackio's content-addressed cache (and fetched
+        from the remote when missing locally), so repeated calls are cheap and
+        idempotent.
+
+        Reference entries added via `add_reference` are fetched here too: the
+        object at each reference URI is downloaded into the directory (via the
+        bundled `httpx` for `http(s)://`, `huggingface_hub` for `hf://`, and
+        the registered custom `ReferenceHandler` for any other scheme). Each
+        object is written atomically and calls are idempotent. Because reference digests
+        are opaque (a provider ETag or the URI itself), a present file is assumed
+        current and is not re-verified against the source, and a source whose
+        re-probed checksum no longer matches the recorded one is downloaded
+        anyway with a warning. Downloading can transfer a large amount of data;
+        to work with the URIs without downloading, read them from the `references`
+        property or `get_entry_uri` instead. A missing source, an unreachable
+        server, or a scheme with no registered handler raises.
+
+        Args:
+            root (`str` or `Path`, *optional*):
+                Directory to write the files into. Defaults to
+                `./.trackio/artifact-downloads/<project>/<name>_v<version>/`,
+                keyed by project so same-named artifacts from different projects
+                never collide, and by the resolved version so a moving alias
+                like `latest` never leaves behind stale files from a previous
+                version.
+
+        Returns:
+            The absolute path to the download directory, as a string.
+        """
+        if not self._logged:
+            raise RuntimeError(
+                "Cannot download an Artifact that has not been logged or fetched."
+            )
+        if self._manifest is None or self._project is None or self._version is None:
+            raise RuntimeError("Artifact is missing manifest, project, or version.")
+
+        if root is None:
+            project = utils.canonical_project_name(self._project)
+            root_path = (
+                Path.cwd()
+                / ".trackio"
+                / "artifact-downloads"
+                / project
+                / f"{self._name}_v{self._version}"
+            )
+        else:
+            root_path = Path(root)
+        root_path.mkdir(parents=True, exist_ok=True)
+
+        for entry in self._manifest:
+            logical = cas.validate_logical_path(entry["path"])
+            if references.is_reference_entry(entry):
+                scheme, uri = references.validate_reference_uri(entry["ref"])
+                _materialize_reference(
+                    uri, scheme, root_path / logical, entry["digest"]
+                )
+                continue
+            digest = cas.validate_digest(entry["digest"])
+            blob = cas.blob_path(self._project, digest)
+            if not blob.is_file():
+                if self._remote_source is None:
+                    raise FileNotFoundError(
+                        f"Artifact blob {digest} not available locally or "
+                        "remotely. The producer machine may not have shipped "
+                        "this blob yet."
+                    )
+                _fetch_blob_from_remote(
+                    self._remote_source, self._project, digest, blob
+                )
+            _materialize(blob, root_path / logical, entry["size"])
+
+        return str(root_path)
+
+    @property
+    def references(self) -> list[dict]:
+        """Reference entries (each with `path`, `ref`, `size`, and a `digest`)
+        recorded via `add_reference`. These point at external data not stored in
+        Trackio; read them to work with the URIs without downloading (unlike
+        `download()`, which fetches them). Returns a fresh copy on each access;
+        empty if the artifact has no references or has not been logged yet."""
+        if self._manifest is None:
+            return []
+        return [dict(e) for e in self._manifest if references.is_reference_entry(e)]
+
+    def get_entry_uri(self, name: str) -> str | None:
+        """Return the URI recorded for the reference entry at logical path
+        `name`, or None if there is no reference entry with that name."""
+        if self._manifest is None:
+            return None
+        for entry in self._manifest:
+            if entry.get("path") == name and references.is_reference_entry(entry):
+                return entry["ref"]
+        return None
+
+    def __repr__(self) -> str:
+        parts: list[str] = [f"name={self._name!r}", f"type={self._type!r}"]
+        if self._version is not None:
+            parts.append(f"version=v{self._version}")
+        if self._aliases:
+            parts.append(f"aliases={list(self._aliases)!r}")
+        return f"Artifact({', '.join(parts)})"

trackio/asgi_app.py

@@ -0,0 +1,531 @@
+from __future__ import annotations
+
+import inspect
+import json
+import logging
+import math
+import secrets
+import tempfile
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, get_args, get_origin
+from urllib.parse import unquote
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import FileResponse, JSONResponse, Response, StreamingResponse
+from starlette.routing import Route
+
+from trackio import utils
+from trackio.exceptions import TrackioAPIError
+from trackio.remote_client import HTTP_API_VERSION
+
+logger = logging.getLogger("trackio.asgi_app")
+
+_PACKAGE_JSON_PATH = Path(__file__).parent / "package.json"
+_TRACKIO_PACKAGE_VERSION = json.loads(_PACKAGE_JSON_PATH.read_text())["version"]
+
+
+def _normalize_allowed_file_roots(
+    allowed_file_roots: list[str | Path] | None,
+) -> tuple[Path, ...]:
+    roots = []
+    for root in allowed_file_roots or []:
+        roots.append(Path(root).resolve())
+    return tuple(roots)
+
+
+def _is_allowed_file_path(path: Path, allowed_roots: tuple[Path, ...]) -> bool:
+    resolved_path = path.resolve(strict=False)
+    for root in allowed_roots:
+        try:
+            resolved_path.relative_to(root)
+            return True
+        except ValueError:
+            continue
+    return False
+
+
+def _json_safe(data: Any) -> Any:
+    if data is None or isinstance(data, (str, bool, int)):
+        return data
+    if isinstance(data, float):
+        return data if math.isfinite(data) else None
+    if isinstance(data, dict):
+        return {k: _json_safe(v) for k, v in data.items()}
+    if isinstance(data, (list, tuple)):
+        return [_json_safe(v) for v in data]
+    if hasattr(data, "item"):
+        try:
+            return _json_safe(data.item())
+        except Exception:
+            pass
+    return str(data)
+
+
+def register_uploaded_temp_file(request: Request, file_path: str | Path) -> None:
+    resolved_path = Path(file_path).resolve(strict=False)
+    with request.app.state.uploaded_temp_files_lock:
+        request.app.state.uploaded_temp_files.add(resolved_path)
+
+
+def consume_uploaded_temp_file(request: Request, file_data: Any) -> Path:
+    file_path = file_data.get("path") if isinstance(file_data, dict) else None
+    if not isinstance(file_path, str) or not file_path:
+        raise TrackioAPIError("Expected uploaded file metadata with a valid path.")
+
+    resolved_path = Path(file_path).resolve(strict=False)
+    with request.app.state.uploaded_temp_files_lock:
+        if resolved_path not in request.app.state.uploaded_temp_files:
+            raise TrackioAPIError(
+                "Uploaded file was not created by this Trackio server."
+            )
+        request.app.state.uploaded_temp_files.remove(resolved_path)
+
+    if not resolved_path.is_file():
+        raise TrackioAPIError("Uploaded file is missing.")
+
+    return resolved_path
+
+
+def cleanup_uploaded_temp_file(file_path: str | Path) -> None:
+    try:
+        Path(file_path).unlink(missing_ok=True)
+    except Exception:
+        pass
+
+
+def _invoke_handler(
+    fn: Any,
+    request: Request,
+    args: list[Any] | None = None,
+    kwargs: dict[str, Any] | None = None,
+) -> Any:
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.values())
+    positional_args: list[Any] = []
+    keyword_args: dict[str, Any] = {}
+    args = list(args or [])
+    kwargs = dict(kwargs or {})
+    data_index = 0
+
+    for param in params:
+        if param.name == "request":
+            keyword_args["request"] = request
+        elif param.kind == inspect.Parameter.VAR_POSITIONAL:
+            positional_args.extend(args[data_index:])
+            data_index = len(args)
+        elif param.kind == inspect.Parameter.VAR_KEYWORD:
+            keyword_args.update(kwargs)
+            kwargs.clear()
+        elif param.name in kwargs:
+            keyword_args[param.name] = kwargs.pop(param.name)
+        elif param.kind in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        ) and data_index < len(args):
+            positional_args.append(args[data_index])
+            data_index += 1
+        elif param.default is inspect.Signature.empty and param.kind not in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            raise TrackioAPIError(f"Missing required parameter: {param.name}")
+
+    return fn(*positional_args, **keyword_args)
+
+
+async def version_handler(request: Request) -> Response:
+    mcp_enabled = bool(getattr(request.app.state, "mcp_enabled", False))
+    return JSONResponse(
+        {
+            "version": _TRACKIO_PACKAGE_VERSION,
+            "api_version": HTTP_API_VERSION,
+            "api_transport": "http",
+            "mcp_enabled": mcp_enabled,
+            "mcp_path": "/mcp" if mcp_enabled else None,
+        }
+    )
+
+
+def _json_schema_and_python_type(annotation: Any) -> tuple[dict[str, Any], str]:
+    if annotation is inspect.Parameter.empty:
+        return {"type": "object"}, "Any"
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    if origin is not None and args:
+        non_none = tuple(a for a in args if a is not type(None))
+        if len(non_none) == 1 and len(args) > 1:
+            return _json_schema_and_python_type(non_none[0])
+        if origin is list:
+            inner, py_inner = _json_schema_and_python_type(
+                args[0] if args else inspect.Parameter.empty
+            )
+            return {"type": "array", "items": inner}, f"list[{py_inner}]"
+        if origin is dict:
+            return {"type": "object"}, "dict"
+    if annotation in (str, bytes):
+        return {"type": "string"}, "str"
+    if annotation is int:
+        return {"type": "integer"}, "int"
+    if annotation is float:
+        return {"type": "number"}, "float"
+    if annotation is bool:
+        return {"type": "boolean"}, "bool"
+    name = getattr(annotation, "__name__", None)
+    if name:
+        return {"type": "object"}, name
+    return {"type": "object"}, "Any"
+
+
+def build_gradio_api_info(api_registry: dict[str, Any]) -> dict[str, Any]:
+    named_endpoints: dict[str, Any] = {}
+    for name in sorted(api_registry.keys()):
+        fn = api_registry[name]
+        if not callable(fn):
+            continue
+        sig = inspect.signature(fn)
+        parameters: list[dict[str, Any]] = []
+        for pname, param in sig.parameters.items():
+            if pname == "request":
+                continue
+            jtype, pytype = _json_schema_and_python_type(param.annotation)
+            has_default = param.default is not inspect.Parameter.empty
+            parameters.append(
+                {
+                    "label": pname,
+                    "parameter_name": pname,
+                    "parameter_has_default": has_default,
+                    "parameter_default": None if not has_default else param.default,
+                    "type": jtype,
+                    "python_type": {"type": pytype, "description": ""},
+                    "component": "Api",
+                    "example_input": None,
+                }
+            )
+        ret_ann = sig.return_annotation
+        if ret_ann is inspect.Signature.empty:
+            ret_ann = Any
+        rjtype, rpytype = _json_schema_and_python_type(ret_ann)
+        returns = [
+            {
+                "label": "result",
+                "type": rjtype,
+                "python_type": {"type": rpytype, "description": ""},
+                "component": "Api",
+            }
+        ]
+        named_endpoints[f"/{name}"] = {
+            "parameters": parameters,
+            "returns": returns,
+            "api_visibility": "public",
+        }
+    return {"named_endpoints": named_endpoints, "unnamed_endpoints": {}}
+
+
+_MAX_GRADIO_CALL_EVENTS = 256
+
+
+def _hf_token_value_is_unset(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, str) and value.strip() == "":
+        return True
+    return False
+
+
+def _authorization_bearer_token(request: Request) -> str | None:
+    auth = request.headers.get("authorization") or request.headers.get("Authorization")
+    if not auth:
+        return None
+    parts = auth.split()
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        return None
+    tok = parts[1].strip()
+    return tok or None
+
+
+def _maybe_apply_hf_token_from_authorization(
+    request: Request, fn: Any, args: list[Any], kwargs: dict[str, Any]
+) -> None:
+    if not utils.on_spaces():
+        return
+    token = _authorization_bearer_token(request)
+    if not token:
+        return
+    sig = inspect.signature(fn)
+    if "hf_token" not in sig.parameters:
+        return
+    params = [p for p in sig.parameters.values() if p.name != "request"]
+    names = [p.name for p in params]
+    if "hf_token" not in names:
+        return
+    idx = names.index("hf_token")
+    if "hf_token" in kwargs:
+        if _hf_token_value_is_unset(kwargs["hf_token"]):
+            kwargs["hf_token"] = token
+        return
+    if idx < len(args):
+        if _hf_token_value_is_unset(args[idx]):
+            args[idx] = token
+        return
+    kwargs["hf_token"] = token
+
+
+def _store_gradio_call_result(
+    request: Request, event_id: str, api_name: str, data: Any
+) -> None:
+    with request.app.state.gradio_call_events_lock:
+        d = request.app.state.gradio_call_events
+        while len(d) >= _MAX_GRADIO_CALL_EVENTS:
+            d.pop(next(iter(d)))
+        d[event_id] = {"api_name": api_name, "data": data}
+
+
+async def run_api_request(request: Request, api_name: str) -> Response:
+    api_registry = request.app.state.api_registry
+    fn = api_registry.get(api_name)
+    if fn is None:
+        return JSONResponse({"error": f"Unknown API: {api_name}"}, status_code=404)
+
+    try:
+        body = await request.json()
+    except Exception:
+        body = {}
+
+    args: list[Any] = []
+    kwargs: dict[str, Any] = {}
+    if isinstance(body, dict):
+        if "args" in body or "kwargs" in body:
+            args = body.get("args") or []
+            kwargs = body.get("kwargs") or {}
+        elif "data" in body and isinstance(body["data"], list):
+            args = body["data"]
+        else:
+            kwargs = body
+    elif isinstance(body, list):
+        args = body
+    elif body is not None:
+        args = [body]
+
+    if not isinstance(args, list):
+        args = [args]
+    if not isinstance(kwargs, dict):
+        kwargs = {}
+
+    _maybe_apply_hf_token_from_authorization(request, fn, args, kwargs)
+
+    try:
+        result = _invoke_handler(fn, request, args=args, kwargs=kwargs)
+        return JSONResponse({"data": _json_safe(result)})
+    except TrackioAPIError as e:
+        return JSONResponse({"error": str(e)}, status_code=400)
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+async def api_handler(request: Request) -> Response:
+    return await run_api_request(request, request.path_params["api_name"])
+
+
+async def gradio_api_info_handler(request: Request) -> Response:
+    return JSONResponse(
+        build_gradio_api_info(request.app.state.api_registry),
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+async def gradio_call_post_handler(request: Request) -> Response:
+    api_name = request.path_params["api_name"]
+    resp = await run_api_request(request, api_name)
+    if resp.status_code != 200:
+        return resp
+    body = json.loads(bytes(resp.body).decode())
+    event_id = secrets.token_urlsafe(16)
+    _store_gradio_call_result(request, event_id, api_name, body["data"])
+    return JSONResponse({"event_id": event_id})
+
+
+async def gradio_call_poll_handler(request: Request) -> Response:
+    api_name = request.path_params["api_name"]
+    event_id = request.path_params["event_id"]
+    with request.app.state.gradio_call_events_lock:
+        event = request.app.state.gradio_call_events.pop(event_id, None)
+    if event is None:
+        logger.info("gradio_api poll: unknown or expired event_id")
+        return JSONResponse({"error": "Unknown or expired event_id"}, status_code=404)
+    if event.get("api_name") != api_name:
+        logger.info(
+            "gradio_api poll: api_name mismatch (path=%r, stored=%r)",
+            api_name,
+            event.get("api_name"),
+        )
+        with request.app.state.gradio_call_events_lock:
+            d = request.app.state.gradio_call_events
+            while len(d) >= _MAX_GRADIO_CALL_EVENTS:
+                d.pop(next(iter(d)))
+            d[event_id] = event
+        return JSONResponse({"error": "Unknown or expired event_id"}, status_code=404)
+
+    data = event["data"]
+    payload = json.dumps(_json_safe([data]))
+
+    async def sse() -> Any:
+        yield f"event: complete\ndata: {payload}\n\n"
+
+    return StreamingResponse(
+        sse(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-store",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+async def upload_handler(request: Request) -> Response:
+    upload_authorizer = getattr(request.app.state, "upload_authorizer", None)
+    if callable(upload_authorizer):
+        try:
+            upload_authorizer(request)
+        except TrackioAPIError as e:
+            return JSONResponse({"error": str(e)}, status_code=400)
+
+    form = await request.form()
+    uploads = form.getlist("files")
+    saved_paths = []
+    for upload in uploads:
+        suffix = Path(getattr(upload, "filename", "") or "").suffix
+        with tempfile.NamedTemporaryFile(
+            delete=False,
+            prefix="trackio-upload-",
+            suffix=suffix,
+        ) as tmp:
+            tmp.write(await upload.read())
+            register_uploaded_temp_file(request, tmp.name)
+            saved_paths.append(tmp.name)
+    return JSONResponse({"paths": saved_paths})
+
+
+async def gradio_upload_alias_handler(request: Request) -> Response:
+    return await upload_handler(request)
+
+
+_DISALLOWED_FILE_SUFFIXES = frozenset(
+    {".db", ".db-journal", ".db-wal", ".db-shm", ".sqlite", ".sqlite3"}
+)
+
+
+async def file_handler(request: Request) -> Response:
+    fs_path = request.query_params.get("path")
+    if fs_path is None:
+        return Response("Missing path", status_code=400)
+    fp = Path(unquote(fs_path)).resolve(strict=False)
+    if fp.suffix.lower() in _DISALLOWED_FILE_SUFFIXES:
+        return Response("Not found", status_code=404)
+    if _is_allowed_file_path(fp, (utils.ARTIFACTS_DIR.resolve(),)):
+        return Response("Not found", status_code=404)
+    allowed_roots = getattr(request.app.state, "allowed_file_roots", ())
+    if fp.is_file() and _is_allowed_file_path(fp, allowed_roots):
+        return FileResponse(str(fp))
+    return Response("Not found", status_code=404)
+
+
+async def artifact_blob_handler(request: Request) -> Response:
+    from trackio import cas  # noqa: PLC0415
+    from trackio import server as _server  # noqa: PLC0415
+
+    project = request.path_params.get("project")
+    digest = request.path_params.get("digest")
+    try:
+        project = _server._validate_project_name(project)
+        digest = _server._validate_sha256_digest(digest)
+    except TrackioAPIError:
+        return Response("Not found", status_code=404)
+    blob = cas.blob_path(project, digest)
+    if not blob.is_file():
+        return Response("Not found", status_code=404)
+    return FileResponse(str(blob))
+
+
+def create_trackio_starlette_app(
+    oauth_routes: list[Route],
+    api_registry: dict[str, Any],
+    extra_routes: list[Any] | None = None,
+    mcp_lifespan: Any = None,
+    mcp_enabled: bool = False,
+    allowed_file_roots: list[str | Path] | None = None,
+    upload_authorizer: Callable[[Request], None] | None = None,
+) -> Starlette:
+    routes: list[Any] = list(oauth_routes)
+    routes.extend(
+        [
+            Route("/version", endpoint=version_handler, methods=["GET"]),
+            Route("/api/upload", endpoint=upload_handler, methods=["POST"]),
+            Route("/api/{api_name:str}", endpoint=api_handler, methods=["POST"]),
+            Route("/file", endpoint=file_handler, methods=["GET"]),
+            Route(
+                "/artifact_blob/{project:str}/{digest:str}",
+                endpoint=artifact_blob_handler,
+                methods=["GET"],
+            ),
+        ]
+    )
+    if utils.on_spaces():
+        routes.extend(
+            [
+                Route(
+                    "/gradio_api/info",
+                    endpoint=gradio_api_info_handler,
+                    methods=["GET"],
+                ),
+                Route(
+                    "/gradio_api/info/",
+                    endpoint=gradio_api_info_handler,
+                    methods=["GET"],
+                ),
+                Route(
+                    "/gradio_api/upload",
+                    endpoint=gradio_upload_alias_handler,
+                    methods=["POST"],
+                ),
+                Route(
+                    "/gradio_api/upload/",
+                    endpoint=gradio_upload_alias_handler,
+                    methods=["POST"],
+                ),
+                Route(
+                    "/gradio_api/call/{api_name:str}",
+                    endpoint=gradio_call_post_handler,
+                    methods=["POST"],
+                ),
+                Route(
+                    "/gradio_api/call/{api_name:str}/",
+                    endpoint=gradio_call_post_handler,
+                    methods=["POST"],
+                ),
+                Route(
+                    "/gradio_api/call/{api_name:str}/{event_id:str}",
+                    endpoint=gradio_call_poll_handler,
+                    methods=["GET"],
+                ),
+                Route(
+                    "/gradio_api/call/{api_name:str}/{event_id:str}/",
+                    endpoint=gradio_call_poll_handler,
+                    methods=["GET"],
+                ),
+            ]
+        )
+    routes.extend(extra_routes or [])
+    app = Starlette(routes=routes, lifespan=mcp_lifespan)
+    app.state.api_registry = api_registry
+    app.state.mcp_enabled = mcp_enabled
+    app.state.allowed_file_roots = _normalize_allowed_file_roots(allowed_file_roots)
+    app.state.upload_authorizer = upload_authorizer
+    app.state.uploaded_temp_files = set()
+    app.state.uploaded_temp_files_lock = threading.Lock()
+    if utils.on_spaces():
+        app.state.gradio_call_events = {}
+        app.state.gradio_call_events_lock = threading.Lock()
+    return app

trackio/bucket_storage.py

@@ -0,0 +1,208 @@
+import tempfile
+from pathlib import Path
+
+import huggingface_hub
+
+from trackio.cas import is_partial_blob
+from trackio.sqlite_storage import SQLiteStorage
+from trackio.utils import (
+    TRACKIO_DIR,
+    canonical_project_name,
+    project_artifacts_dir,
+    project_media_dir,
+)
+
+
+def create_bucket_if_not_exists(bucket_id: str, private: bool | None = None) -> None:
+    huggingface_hub.create_bucket(bucket_id, private=private, exist_ok=True)
+
+
+LOGBOOK_FILES_BUCKET_PREFIX = "logbook-files"
+
+
+def upload_logbook_path_artifacts_to_bucket(
+    bucket_id: str, entries: list[dict]
+) -> list[str]:
+    """Uploads local files referenced by path-artifact cells, preserving their
+    relative path under a stable bucket prefix. Returns the relative paths that
+    were actually uploaded (missing files are skipped)."""
+    additions: list[tuple[str, str]] = []
+    uploaded: list[str] = []
+    for entry in entries:
+        local_path = Path(entry["abs_path"])
+        if not local_path.is_file():
+            continue
+        remote_path = f"{LOGBOOK_FILES_BUCKET_PREFIX}/{entry['path']}"
+        additions.append((str(local_path), remote_path))
+        uploaded.append(entry["path"])
+    if additions:
+        huggingface_hub.batch_bucket_files(
+            bucket_id, add=additions, token=huggingface_hub.utils.get_token()
+        )
+    return uploaded
+
+
+def _list_bucket_file_paths(bucket_id: str, prefix: str | None = None) -> list[str]:
+    items = huggingface_hub.list_bucket_tree(bucket_id, prefix=prefix, recursive=True)
+    return [
+        item.path
+        for item in items
+        if getattr(item, "type", None) == "file" and getattr(item, "path", None)
+    ]
+
+
+def download_bucket_to_trackio_dir(bucket_id: str) -> None:
+    TRACKIO_DIR.mkdir(parents=True, exist_ok=True)
+    huggingface_hub.sync_bucket(
+        source=f"hf://buckets/{bucket_id}/trackio",
+        dest=str(TRACKIO_DIR),
+        quiet=True,
+    )
+
+
+def upload_project_to_bucket(project: str, bucket_id: str) -> None:
+    db_path = SQLiteStorage.get_project_db_path(project)
+    if not db_path.exists():
+        raise FileNotFoundError(f"No database found for project '{project}'")
+
+    with SQLiteStorage._get_connection(
+        db_path, configure_pragmas=False, row_factory=None
+    ) as conn:
+        conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+
+    files_to_add = [(str(db_path), f"trackio/{db_path.name}")]
+
+    media_dir = project_media_dir(project)
+    if media_dir.exists():
+        for media_file in media_dir.rglob("*"):
+            if media_file.is_file():
+                rel = media_file.relative_to(TRACKIO_DIR)
+                files_to_add.append((str(media_file), f"trackio/{rel.as_posix()}"))
+
+    artifacts_dir = project_artifacts_dir(project)
+    if artifacts_dir.exists():
+        for blob_file in artifacts_dir.rglob("*"):
+            if not blob_file.is_file():
+                continue
+            if is_partial_blob(blob_file.name):
+                continue
+            rel = blob_file.relative_to(TRACKIO_DIR)
+            files_to_add.append((str(blob_file), f"trackio/{rel.as_posix()}"))
+
+    huggingface_hub.batch_bucket_files(bucket_id, add=files_to_add)
+
+
+def _download_db_from_bucket(
+    project: str, bucket_id: str, dest_path: Path | None = None
+) -> bool:
+    db_filename = SQLiteStorage.get_project_db_filename(project)
+    remote_path = f"trackio/{db_filename}"
+    local_path = dest_path or SQLiteStorage.get_project_db_path(project)
+    local_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        huggingface_hub.download_bucket_files(
+            bucket_id,
+            files=[(remote_path, str(local_path))],
+            token=huggingface_hub.utils.get_token(),
+        )
+        return local_path.exists()
+    except Exception:
+        return False
+
+
+def _local_db_has_data(project: str) -> bool:
+    db_path = SQLiteStorage.get_project_db_path(project)
+    if not db_path.exists() or db_path.stat().st_size == 0:
+        return False
+    try:
+        with SQLiteStorage._get_connection(
+            db_path, configure_pragmas=False, row_factory=None
+        ) as conn:
+            count = conn.execute("SELECT COUNT(*) FROM metrics").fetchone()[0]
+            return count > 0
+    except Exception:
+        return False
+
+
+def _export_and_upload_static(
+    project: str,
+    dest_bucket_id: str,
+    db_path: Path,
+    media_dir: Path | None = None,
+    artifacts_dir: Path | None = None,
+) -> None:
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        output_dir = Path(tmp_dir)
+        SQLiteStorage.export_for_static_space(
+            project, output_dir, db_path_override=db_path
+        )
+
+        files_to_add = []
+        for f in output_dir.rglob("*"):
+            if f.is_file():
+                rel = f.relative_to(output_dir)
+                files_to_add.append((str(f), rel.as_posix()))
+
+        if media_dir and media_dir.exists():
+            for f in media_dir.rglob("*"):
+                if f.is_file():
+                    rel = f.relative_to(media_dir)
+                    files_to_add.append((str(f), f"media/{rel.as_posix()}"))
+
+        if artifacts_dir and artifacts_dir.exists():
+            for f in artifacts_dir.rglob("*"):
+                if f.is_file() and not is_partial_blob(f.name):
+                    rel = f.relative_to(artifacts_dir)
+                    files_to_add.append((str(f), f"artifacts/{rel.as_posix()}"))
+
+        huggingface_hub.batch_bucket_files(dest_bucket_id, add=files_to_add)
+
+
+def _copy_project_prefix_between_buckets(
+    source_bucket_id: str, dest_bucket_id: str, project: str, kind: str
+) -> None:
+    source_prefix = f"trackio/{kind}/{canonical_project_name(project)}/"
+    files_to_copy = _list_bucket_file_paths(source_bucket_id, prefix=source_prefix)
+    if not files_to_copy:
+        return
+
+    huggingface_hub.copy_files(
+        f"hf://buckets/{source_bucket_id}/{source_prefix}",
+        f"hf://buckets/{dest_bucket_id}/{kind}/",
+    )
+
+
+def upload_project_to_bucket_for_static(project: str, bucket_id: str) -> None:
+    if not _local_db_has_data(project):
+        _download_db_from_bucket(project, bucket_id)
+
+    db_path = SQLiteStorage.get_project_db_path(project)
+    _export_and_upload_static(
+        project,
+        bucket_id,
+        db_path,
+        project_media_dir(project),
+        project_artifacts_dir(project),
+    )
+
+
+def export_from_bucket_for_static(
+    source_bucket_id: str,
+    dest_bucket_id: str,
+    project: str,
+) -> None:
+    with tempfile.TemporaryDirectory() as work_dir:
+        work_path = Path(work_dir)
+        db_path = work_path / SQLiteStorage.get_project_db_filename(project)
+
+        if not _download_db_from_bucket(project, source_bucket_id, dest_path=db_path):
+            raise FileNotFoundError(
+                f"Could not download database for project '{project}' "
+                f"from bucket '{source_bucket_id}'."
+            )
+
+        _export_and_upload_static(project, dest_bucket_id, db_path)
+        for kind in ("media", "artifacts"):
+            _copy_project_prefix_between_buckets(
+                source_bucket_id, dest_bucket_id, project, kind
+            )

trackio/cas.py

@@ -0,0 +1,214 @@
+"""Content-addressed storage (CAS) helpers shared by the artifact client,
+server, and storage layers.
+"""
+
+import hashlib
+import os
+import re
+import uuid
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+
+from trackio import utils
+from trackio.typehints import Sha256Digest
+
+SHA256_DIGEST_RE = re.compile(r"^[0-9a-f]{64}$")
+ARTIFACT_VERSION_SPEC_RE = re.compile(r"^v(\d+)$")
+ARTIFACT_NAME_RE = re.compile(r"^[A-Za-z0-9._-]+\Z")
+HASH_CHUNK_SIZE = 1024 * 1024
+PARTIAL_BLOB_MARKER = ".partial."
+PARTIAL_BLOB_GLOB = f"*{PARTIAL_BLOB_MARKER}*"
+
+
+def partial_blob_name(base: str = "") -> str:
+    """Temp filename for an in-flight blob write, excluded from sync/export."""
+    return f"{base}{PARTIAL_BLOB_MARKER}{uuid.uuid4().hex}"
+
+
+def is_partial_blob(filename: str) -> bool:
+    return PARTIAL_BLOB_MARKER in filename
+
+
+def validate_artifact_name(name: str) -> str:
+    if not isinstance(name, str) or not ARTIFACT_NAME_RE.match(name):
+        raise ValueError(
+            f"Artifact name {name!r} must match ^[A-Za-z0-9._-]+$ "
+            "(letters, digits, dot, underscore, hyphen)."
+        )
+    return name
+
+
+def validate_aliases(aliases: list[str] | None) -> list[str]:
+    if aliases is None:
+        return []
+    if isinstance(aliases, str) or not isinstance(aliases, (list, tuple)):
+        raise ValueError(
+            f"aliases must be a list of strings, got {type(aliases).__name__}."
+        )
+    validated: list[str] = []
+    for alias in aliases:
+        if not isinstance(alias, str) or not alias:
+            raise ValueError(f"Alias {alias!r} must be a non-empty string.")
+        if not ARTIFACT_NAME_RE.match(alias):
+            raise ValueError(
+                f"Alias {alias!r} must match ^[A-Za-z0-9._-]+$ "
+                "(letters, digits, dot, underscore, hyphen)."
+            )
+        if ARTIFACT_VERSION_SPEC_RE.match(alias):
+            raise ValueError(
+                f"Alias {alias!r} is reserved for version pointers (vN); "
+                "choose another."
+            )
+        validated.append(alias)
+    return validated
+
+
+def _project_blobs_root(project: str) -> Path:
+    return utils.project_artifacts_dir(project) / "blobs" / "sha256"
+
+
+def blob_path(project: str, digest: Sha256Digest) -> Path:
+    return _project_blobs_root(project) / digest[:2] / digest
+
+
+def hash_file(path: Path) -> tuple[Sha256Digest, int]:
+    size = path.stat().st_size
+    file_digest = getattr(hashlib, "file_digest", None)
+    if file_digest is not None:
+        with path.open("rb") as f:
+            sha = file_digest(f, "sha256")
+    else:
+        sha = hashlib.sha256()
+        with path.open("rb") as f:
+            while chunk := f.read(HASH_CHUNK_SIZE):
+                sha.update(chunk)
+    return Sha256Digest(sha.hexdigest()), size
+
+
+def validate_logical_path(logical: str) -> str:
+    """Validate a manifest logical path: relative, no `.`/`..` segments, no
+    backslashes, no drive letters, non-empty. Returns the path unchanged.
+    """
+    if not isinstance(logical, str) or not logical:
+        raise ValueError(f"Invalid artifact path: {logical!r} (must be non-empty)")
+    if "\\" in logical or "\x00" in logical:
+        raise ValueError(
+            f"Invalid artifact path {logical!r}: backslashes and NUL are not allowed"
+        )
+    if logical.startswith("/") or re.match(r"^[A-Za-z]:", logical):
+        raise ValueError(f"Invalid artifact path {logical!r}: must be relative")
+    parts = logical.split("/")
+    if any(part in ("", ".", "..") for part in parts):
+        raise ValueError(
+            f"Invalid artifact path {logical!r}: "
+            "'.', '..', and empty segments are not allowed"
+        )
+    return logical
+
+
+def assert_manifest_paths_compatible(paths: Iterable[str]) -> None:
+    """Validate a manifest's logical paths as a set: reject exact duplicates and
+    file/directory prefix collisions. A path cannot be both a file and a
+    directory, so `sub` and `sub/x` (or `a/b` and `a/b/c`) cannot coexist;
+    siblings like `a/b` and `a/c` are fine.
+    """
+    seen: set[str] = set()
+    for p in paths:
+        if p in seen:
+            raise ValueError(f"Duplicate logical path in manifest: {p!r}")
+        seen.add(p)
+    for p in seen:
+        parts = p.split("/")
+        for i in range(1, len(parts)):
+            ancestor = "/".join(parts[:i])
+            if ancestor in seen:
+                raise ValueError(
+                    f"Artifact path {p!r} collides with {ancestor!r}: a path "
+                    "cannot be both a file and a directory in the same artifact."
+                )
+
+
+def validate_digest(digest: str) -> Sha256Digest:
+    """Validate that `digest` is a 64-char lowercase sha256 hex string and
+    return it unchanged.
+    """
+    if not isinstance(digest, str) or not SHA256_DIGEST_RE.match(digest):
+        raise ValueError(f"Invalid artifact blob digest: {digest!r}")
+    return Sha256Digest(digest)
+
+
+def stage_blob_from_chunks(
+    chunks: Iterable[bytes],
+    claimed_digest: Sha256Digest,
+    target_path: Path,
+) -> None:
+    """Stream `chunks` to `target_path`, verifying they hash to `claimed_digest`.
+    No-op if `target_path` already exists (the chunks are not consumed).
+    """
+    if target_path.is_file():
+        return
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    partial = target_path.parent / partial_blob_name(target_path.name)
+    sha = hashlib.sha256()
+    try:
+        with partial.open("wb") as dst:
+            for chunk in chunks:
+                if not chunk:
+                    continue
+                sha.update(chunk)
+                dst.write(chunk)
+        actual = sha.hexdigest()
+        if actual != claimed_digest:
+            raise ValueError(
+                f"Digest mismatch: claimed {claimed_digest}, computed {actual}"
+            )
+        os.replace(partial, target_path)
+    except Exception:
+        partial.unlink(missing_ok=True)
+        raise
+
+
+def stage_blob_from_file(
+    src_path: Path,
+    claimed_digest: Sha256Digest,
+    target_path: Path,
+) -> None:
+    """Copy `src_path` to `target_path`, verifying it hashes to `claimed_digest`."""
+    if target_path.is_file():
+        return
+
+    def _file_chunks() -> Iterator[bytes]:
+        with src_path.open("rb") as src:
+            while chunk := src.read(HASH_CHUNK_SIZE):
+                yield chunk
+
+    stage_blob_from_chunks(_file_chunks(), claimed_digest, target_path)
+
+
+def stage_blob_into_project(src_path: Path, project: str) -> tuple[Sha256Digest, int]:
+    """Copy `src_path` into the project's CAS in a single pass, computing its
+    sha256 and size while writing. Returns `(digest, size)`. If the blob is
+    already present, the copy is discarded.
+    """
+    blobs_root = _project_blobs_root(project)
+    blobs_root.mkdir(parents=True, exist_ok=True)
+    partial = blobs_root / partial_blob_name()
+    sha = hashlib.sha256()
+    size = 0
+    try:
+        with src_path.open("rb") as src, partial.open("wb") as dst:
+            while chunk := src.read(HASH_CHUNK_SIZE):
+                sha.update(chunk)
+                dst.write(chunk)
+                size += len(chunk)
+        digest = Sha256Digest(sha.hexdigest())
+        target = blob_path(project, digest)
+        if target.is_file():
+            partial.unlink(missing_ok=True)
+            return digest, size
+        target.parent.mkdir(parents=True, exist_ok=True)
+        os.replace(partial, target)
+        return digest, size
+    except Exception:
+        partial.unlink(missing_ok=True)
+        raise

trackio/cli.py

@@ -0,0 +1,2307 @@
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+import huggingface_hub
+
+import trackio
+from trackio import freeze, show, sync
+from trackio.cli_helpers import (
+    error_exit,
+    format_alerts,
+    format_artifact,
+    format_artifacts,
+    format_json,
+    format_list,
+    format_metric_values,
+    format_project_summary,
+    format_query_result,
+    format_run_summary,
+    format_snapshot,
+    format_spaces,
+    format_system_metric_names,
+    format_system_metrics,
+)
+from trackio.frontend_config import (
+    TRACKIO_CONFIG_PATH,
+    get_persisted_frontend_dir,
+    set_persisted_frontend_dir,
+    unset_persisted_frontend_dir,
+)
+from trackio.markdown import Markdown
+from trackio.server import get_project_summary, get_run_summary
+from trackio.sqlite_storage import SQLiteStorage
+
+
+def _get_space(args):
+    return getattr(args, "space", None)
+
+
+def _get_remote(args):
+    from trackio.remote_client import RemoteClient
+
+    space = _get_space(args)
+    if not space:
+        return None
+    hf_token = getattr(args, "hf_token", None)
+    return RemoteClient(space, hf_token=hf_token)
+
+
+def _handle_status():
+    print("Reading local Trackio projects...\n")
+    projects = SQLiteStorage.get_projects()
+    if not projects:
+        print("No Trackio projects found.")
+        return
+
+    local_projects = []
+    synced_projects = []
+    unsynced_projects = []
+
+    for project in projects:
+        space_id = SQLiteStorage.get_space_id(project)
+        if space_id is None:
+            local_projects.append(project)
+        elif SQLiteStorage.has_pending_data(project):
+            unsynced_projects.append(project)
+        else:
+            synced_projects.append(project)
+
+    print("Finished reading Trackio projects")
+    if local_projects:
+        print(f"  * {len(local_projects)} local trackio project(s) [OK]")
+    if synced_projects:
+        print(f"  * {len(synced_projects)} trackio project(s) synced to Spaces [OK]")
+    if unsynced_projects:
+        print(
+            f"  * {len(unsynced_projects)} trackio project(s) with unsynced changes [WARNING]:"
+        )
+        for p in unsynced_projects:
+            print(f"    - {p}")
+
+    if unsynced_projects:
+        print(
+            f"\nRun `trackio sync --project {unsynced_projects[0]}` to sync. "
+            "Or run `trackio sync --all` to sync all unsynced changes."
+        )
+
+
+def _handle_sync(args):
+    from trackio.deploy import sync_incremental
+
+    if args.sync_all and args.project:
+        error_exit("Cannot use --all and --project together.")
+    if not args.sync_all and not args.project:
+        error_exit("Must provide either --project or --all.")
+
+    if args.sync_all:
+        projects = SQLiteStorage.get_projects()
+        synced_any = False
+        for project in projects:
+            space_id = SQLiteStorage.get_space_id(project)
+            if space_id and SQLiteStorage.has_pending_data(project):
+                sync_incremental(
+                    project,
+                    space_id,
+                    private=args.private,
+                    pending_only=True,
+                    frontend_dir=args.frontend,
+                )
+                synced_any = True
+        if not synced_any:
+            print("No projects with unsynced data found.")
+    else:
+        space_id = args.space_id
+        if space_id is None:
+            space_id = SQLiteStorage.get_space_id(args.project)
+        sync(
+            project=args.project,
+            space_id=space_id,
+            private=args.private,
+            force=args.force,
+            sdk=args.sdk,
+            frontend_dir=args.frontend,
+        )
+
+
+def _handle_config(args):
+    if args.config_command == "get":
+        frontend_dir = get_persisted_frontend_dir()
+        if frontend_dir is None:
+            print("No Trackio frontend config is set.")
+            print(f"Config file: {TRACKIO_CONFIG_PATH}")
+            return
+        print(f"frontend: {frontend_dir}")
+        print(f"config: {TRACKIO_CONFIG_PATH}")
+        return
+
+    if args.config_command == "set":
+        try:
+            frontend_dir = set_persisted_frontend_dir(args.frontend)
+        except ValueError as e:
+            error_exit(str(e))
+        print(f"Saved Trackio default frontend: {frontend_dir}")
+        print("Reset with `trackio config unset frontend`.")
+        return
+
+    if args.config_command == "unset":
+        removed = unset_persisted_frontend_dir()
+        if removed:
+            print("Removed Trackio default frontend.")
+        else:
+            print("No Trackio default frontend was set.")
+        return
+
+
+def _extract_reports(
+    run: str, logs: list[dict], report_name: str | None = None
+) -> list[dict]:
+    reports = []
+    for log in logs:
+        timestamp = log.get("timestamp")
+        step = log.get("step")
+        for key, value in log.items():
+            if report_name is not None and key != report_name:
+                continue
+            if isinstance(value, dict) and value.get("_type") == Markdown.TYPE:
+                content = value.get("_value")
+                if isinstance(content, str):
+                    reports.append(
+                        {
+                            "run": run,
+                            "report": key,
+                            "step": step,
+                            "timestamp": timestamp,
+                            "content": content,
+                        }
+                    )
+    return reports
+
+
+def _handle_query(args):
+    remote = _get_remote(args)
+    try:
+        if remote:
+            result = remote.predict(args.project, args.sql, api_name="/query_project")
+        else:
+            result = SQLiteStorage.query_project(args.project, args.sql)
+    except FileNotFoundError as e:
+        error_exit(str(e))
+    except ValueError as e:
+        error_exit(str(e))
+
+    if args.json:
+        print(format_json(result))
+    else:
+        print(format_query_result(result))
+
+
+def _datetime_to_iso(value):
+    return value.isoformat() if value is not None else None
+
+
+def _space_url(space) -> str | None:
+    host = getattr(space, "host", None)
+    if host:
+        return host if host.startswith("http") else f"https://{host}"
+
+    subdomain = getattr(space, "subdomain", None)
+    if subdomain:
+        return f"https://{subdomain}.hf.space"
+
+    space_id = getattr(space, "id", None)
+    if not space_id:
+        return None
+    return f"https://huggingface.co/spaces/{space_id}"
+
+
+def _serialize_space(space) -> dict:
+    space_id = getattr(space, "id", "")
+    namespace, _, name = space_id.partition("/")
+    return {
+        "id": space_id,
+        "namespace": namespace,
+        "name": name or space_id,
+        "author": getattr(space, "author", None) or namespace,
+        "private": bool(getattr(space, "private", False)),
+        "sdk": getattr(space, "sdk", None),
+        "url": _space_url(space),
+        "last_modified": _datetime_to_iso(
+            getattr(space, "last_modified", None)
+            or getattr(space, "lastModified", None)
+        ),
+        "created_at": _datetime_to_iso(getattr(space, "created_at", None)),
+        "tags": getattr(space, "tags", None) or [],
+    }
+
+
+def _maybe_handle_logbook_run_argv() -> bool:
+    argv = sys.argv[1:]
+    try:
+        logbook_idx = argv.index("logbook")
+    except ValueError:
+        return False
+    if len(argv) <= logbook_idx + 1 or argv[logbook_idx + 1] != "run":
+        return False
+
+    run_argv = argv[logbook_idx + 2 :]
+
+    run_parser = argparse.ArgumentParser(
+        prog=f"{os.path.basename(sys.argv[0])} logbook run",
+        description=(
+            "Run a command; log the command, its scripts, and output to a page"
+        ),
+    )
+    run_parser.add_argument("--page", help="Page title or slug")
+    run_parser.add_argument("--title", help="Cell title")
+    run_parser.add_argument(
+        "--no-artifacts",
+        action="store_true",
+        help="Do not record output model/data files as artifact cells",
+    )
+    if "--" in run_argv:
+        sep = run_argv.index("--")
+        opts = run_parser.parse_args(run_argv[:sep])
+        command = run_argv[sep + 1 :]
+    else:
+        opts, command = run_parser.parse_known_args(run_argv)
+    if not command:
+        run_parser.error("No command provided. Use: trackio logbook run -- <command>")
+    args = argparse.Namespace(
+        logbook_action="run",
+        page=opts.page,
+        title=opts.title,
+        no_artifacts=opts.no_artifacts,
+        command=command,
+    )
+    _handle_logbook(args)
+    return True
+
+
+def _maybe_rewrite_logbook_read_argv() -> None:
+    argv = sys.argv
+    for i in range(1, len(argv) - 1):
+        if argv[i] == "logbook" and argv[i + 1] == "read":
+            j = i + 2
+            if (
+                j < len(argv)
+                and not argv[j].startswith("-")
+                and argv[j] not in ("pages", "page", "cell")
+            ):
+                argv[j : j + 1] = ["--path", argv[j]]
+            return
+
+
+def _trackio_space_namespaces(api, token: str | None, author: str | None) -> list[str]:
+    if author:
+        return [author]
+
+    if not token:
+        error_exit(
+            "Log in with `huggingface-cli login`, pass `--hf-token`, or provide `--author`."
+        )
+
+    try:
+        whoami = api.whoami(token=token, cache=True)
+    except Exception as e:
+        error_exit(f"Failed to read Hugging Face account information: {e}")
+
+    namespaces = [whoami["name"]]
+    for org in whoami.get("orgs", []):
+        org_name = org.get("name") if isinstance(org, dict) else org
+        if org_name:
+            namespaces.append(org_name)
+
+    return list(dict.fromkeys(namespaces))
+
+
+def _handle_list_spaces(args):
+    if _get_space(args):
+        error_exit("The 'list spaces' command does not support --space.")
+    if args.limit is not None and args.limit < 0:
+        error_exit("--limit must be zero or greater.")
+
+    token = args.hf_token or huggingface_hub.utils.get_token()
+    api = huggingface_hub.HfApi(token=token)
+    namespaces = _trackio_space_namespaces(api, token, args.author)
+
+    spaces_by_id = {}
+    try:
+        for namespace in namespaces:
+            spaces = api.list_spaces(
+                author=namespace,
+                filter="trackio",
+                full=True,
+                token=token,
+            )
+            for space in spaces:
+                space_id = getattr(space, "id", None)
+                if space_id:
+                    spaces_by_id[space_id] = _serialize_space(space)
+    except Exception as e:
+        error_exit(f"Failed to list Trackio Spaces: {e}")
+
+    spaces = sorted(
+        spaces_by_id.values(),
+        key=lambda space: space.get("last_modified") or "",
+        reverse=True,
+    )
+    if args.limit is not None:
+        spaces = spaces[: args.limit]
+
+    if args.json:
+        print(format_json({"spaces": spaces}))
+    else:
+        print(format_spaces(spaces))
+
+
+def main():
+    if _maybe_handle_logbook_run_argv():
+        return
+    _maybe_rewrite_logbook_read_argv()
+
+    parser = argparse.ArgumentParser(description="Trackio CLI")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"trackio {trackio.__version__}",
+    )
+    parser.add_argument(
+        "--space",
+        required=False,
+        help="HF Space ID (e.g. 'user/space') or Space URL to query remotely.",
+    )
+    parser.add_argument(
+        "--hf-token",
+        required=False,
+        help="HF token for accessing private Spaces.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    ui_parser = subparsers.add_parser(
+        "show", help="Show the Trackio dashboard UI for a project"
+    )
+    ui_parser.add_argument(
+        "--project", required=False, help="Project name to show in the dashboard"
+    )
+    ui_parser.add_argument(
+        "--theme",
+        required=False,
+        default="default",
+        help="A Gradio Theme to use for the dashboard instead of the default, can be a built-in theme (e.g. 'soft', 'citrus'), or a theme from the Hub (e.g. 'gstaff/xkcd').",
+    )
+    ui_parser.add_argument(
+        "--mcp-server",
+        action="store_true",
+        help="Enable MCP server functionality. The Trackio dashboard will be set up as an MCP server and certain functions will be exposed as MCP tools.",
+    )
+    ui_parser.add_argument(
+        "--footer",
+        action="store_true",
+        default=True,
+        help="Show the Gradio footer. Use --no-footer to hide it.",
+    )
+    ui_parser.add_argument(
+        "--no-footer",
+        dest="footer",
+        action="store_false",
+        help="Hide the Gradio footer.",
+    )
+    ui_parser.add_argument(
+        "--color-palette",
+        required=False,
+        help="Comma-separated list of hex color codes for plot lines (e.g. '#FF0000,#00FF00,#0000FF'). If not provided, the TRACKIO_COLOR_PALETTE environment variable will be used, or the default palette if not set.",
+    )
+    ui_parser.add_argument(
+        "--host",
+        required=False,
+        help="Host to bind the server to (e.g. '0.0.0.0' for remote access). If not provided, defaults to '127.0.0.1' (localhost only).",
+    )
+    ui_parser.add_argument(
+        "--frontend",
+        required=False,
+        help="Custom frontend directory to serve. Must contain index.html.",
+    )
+
+    subparsers.add_parser(
+        "status",
+        help="Show the status of all local Trackio projects, including sync status.",
+    )
+
+    sync_parser = subparsers.add_parser(
+        "sync",
+        help="Sync a local project's database to a Hugging Face Space. If the Space does not exist, it will be created.",
+    )
+    sync_parser.add_argument(
+        "--project",
+        required=False,
+        help="The name of the local project.",
+    )
+    sync_parser.add_argument(
+        "--space-id",
+        required=False,
+        help="The Hugging Face Space ID where the project will be synced (e.g. username/space_id). If not provided, uses the previously-configured Space.",
+    )
+    sync_parser.add_argument(
+        "--all",
+        action="store_true",
+        dest="sync_all",
+        help="Sync all projects that have unsynced data to their configured Spaces.",
+    )
+    sync_parser.add_argument(
+        "--private",
+        action="store_true",
+        help="Make the Hugging Face Space private if creating a new Space. By default, the repo will be public unless the organization's default is private. This value is ignored if the repo already exists.",
+    )
+    sync_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite the existing database without prompting for confirmation.",
+    )
+    sync_parser.add_argument(
+        "--sdk",
+        choices=["gradio", "static"],
+        default="gradio",
+        help="The type of Space to deploy. 'gradio' (default) deploys a live Gradio server. 'static' deploys a static Space that reads from an HF Bucket.",
+    )
+    sync_parser.add_argument(
+        "--frontend",
+        required=False,
+        help="Custom frontend directory to deploy. Must contain index.html.",
+    )
+
+    freeze_parser = subparsers.add_parser(
+        "freeze",
+        help="Create a one-time static Space snapshot from a project's data.",
+    )
+    freeze_parser.add_argument(
+        "--space-id",
+        required=True,
+        help="The source Gradio Space ID (e.g. username/space_id).",
+    )
+    freeze_parser.add_argument(
+        "--project",
+        required=True,
+        help="The name of the project to freeze into a static snapshot.",
+    )
+    freeze_parser.add_argument(
+        "--new-space-id",
+        required=False,
+        help="The Space ID for the new static Space. Defaults to {space_id}_static.",
+    )
+    freeze_parser.add_argument(
+        "--private",
+        action="store_true",
+        help="Make the new static Space private.",
+    )
+    freeze_parser.add_argument(
+        "--frontend",
+        required=False,
+        help="Custom frontend directory to deploy to the frozen static Space.",
+    )
+
+    config_parser = subparsers.add_parser(
+        "config",
+        help="Manage persistent Trackio configuration.",
+    )
+    config_subparsers = config_parser.add_subparsers(
+        dest="config_command",
+        required=True,
+    )
+    config_subparsers.add_parser("get", help="Show current Trackio config.")
+    config_set_parser = config_subparsers.add_parser(
+        "set",
+        help="Set a persistent Trackio config value.",
+    )
+    config_set_parser.add_argument(
+        "key",
+        choices=["frontend"],
+        help="Config key to set.",
+    )
+    config_set_parser.add_argument(
+        "frontend",
+        help="Frontend directory to persist.",
+    )
+    config_unset_parser = config_subparsers.add_parser(
+        "unset",
+        help="Unset a persistent Trackio config value.",
+    )
+    config_unset_parser.add_argument(
+        "key",
+        choices=["frontend"],
+        help="Config key to unset.",
+    )
+
+    list_parser = subparsers.add_parser(
+        "list",
+        help="List projects, runs, or metrics",
+    )
+    list_subparsers = list_parser.add_subparsers(dest="list_type", required=True)
+
+    list_projects_parser = list_subparsers.add_parser(
+        "projects",
+        help="List all projects",
+    )
+    list_projects_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_spaces_parser = list_subparsers.add_parser(
+        "spaces",
+        help="List Trackio Spaces for your Hugging Face account and organizations",
+    )
+    list_spaces_parser.add_argument(
+        "--author",
+        required=False,
+        help="Only list Trackio Spaces under this user or organization namespace.",
+    )
+    list_spaces_parser.add_argument(
+        "--limit",
+        type=int,
+        required=False,
+        help="Maximum number of Spaces to return.",
+    )
+    list_spaces_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_runs_parser = list_subparsers.add_parser(
+        "runs",
+        help="List runs for a project",
+    )
+    list_runs_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_runs_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_metrics_parser = list_subparsers.add_parser(
+        "metrics",
+        help="List metrics for a run",
+    )
+    list_metrics_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_metrics_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    list_metrics_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_system_metrics_parser = list_subparsers.add_parser(
+        "system-metrics",
+        help="List system metrics for a run",
+    )
+    list_system_metrics_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_system_metrics_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    list_system_metrics_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_alerts_parser = list_subparsers.add_parser(
+        "alerts",
+        help="List alerts for a project or run",
+    )
+    list_alerts_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_alerts_parser.add_argument(
+        "--run",
+        required=False,
+        help="Run name (optional)",
+    )
+    list_alerts_parser.add_argument(
+        "--level",
+        required=False,
+        help="Filter by alert level (info, warn, error)",
+    )
+    list_alerts_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+    list_alerts_parser.add_argument(
+        "--since",
+        required=False,
+        help="Only show alerts after this ISO 8601 timestamp",
+    )
+
+    list_reports_parser = list_subparsers.add_parser(
+        "reports",
+        help="List markdown reports for a project or run",
+    )
+    list_reports_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_reports_parser.add_argument(
+        "--run",
+        required=False,
+        help="Run name (optional)",
+    )
+    list_reports_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_artifacts_parser = list_subparsers.add_parser(
+        "artifacts",
+        help="List artifacts for a project",
+    )
+    list_artifacts_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_artifacts_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_parser = subparsers.add_parser(
+        "get",
+        help="Get project, run, or metric information",
+    )
+    get_subparsers = get_parser.add_subparsers(dest="get_type", required=True)
+
+    get_project_parser = get_subparsers.add_parser(
+        "project",
+        help="Get project summary",
+    )
+    get_project_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_project_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_run_parser = get_subparsers.add_parser(
+        "run",
+        help="Get run summary",
+    )
+    get_run_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_run_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_run_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_artifact_parser = get_subparsers.add_parser(
+        "artifact",
+        help="Get an artifact version (manifest, aliases, metadata)",
+    )
+    get_artifact_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_artifact_parser.add_argument(
+        "--name",
+        required=True,
+        help="Artifact name",
+    )
+    get_artifact_parser.add_argument(
+        "--version",
+        required=False,
+        help="Version or alias to resolve (e.g. 'v2' or 'best'). Defaults to latest.",
+    )
+    get_artifact_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_metric_parser = get_subparsers.add_parser(
+        "metric",
+        help="Get metric values for a run",
+    )
+    get_metric_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_metric_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_metric_parser.add_argument(
+        "--metric",
+        required=True,
+        help="Metric name",
+    )
+    get_metric_parser.add_argument(
+        "--step",
+        type=int,
+        required=False,
+        help="Get metric at exactly this step",
+    )
+    get_metric_parser.add_argument(
+        "--around",
+        type=int,
+        required=False,
+        help="Get metrics around this step (use with --window)",
+    )
+    get_metric_parser.add_argument(
+        "--at-time",
+        required=False,
+        help="Get metrics around this ISO 8601 timestamp (use with --window)",
+    )
+    get_metric_parser.add_argument(
+        "--window",
+        type=int,
+        required=False,
+        default=10,
+        help="Window size: ±steps for --around, ±seconds for --at-time (default: 10)",
+    )
+    get_metric_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_snapshot_parser = get_subparsers.add_parser(
+        "snapshot",
+        help="Get all metrics at/around a step or timestamp",
+    )
+    get_snapshot_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_snapshot_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_snapshot_parser.add_argument(
+        "--step",
+        type=int,
+        required=False,
+        help="Get all metrics at exactly this step",
+    )
+    get_snapshot_parser.add_argument(
+        "--around",
+        type=int,
+        required=False,
+        help="Get all metrics around this step (use with --window)",
+    )
+    get_snapshot_parser.add_argument(
+        "--at-time",
+        required=False,
+        help="Get all metrics around this ISO 8601 timestamp (use with --window)",
+    )
+    get_snapshot_parser.add_argument(
+        "--window",
+        type=int,
+        required=False,
+        default=10,
+        help="Window size: ±steps for --around, ±seconds for --at-time (default: 10)",
+    )
+    get_snapshot_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_system_metric_parser = get_subparsers.add_parser(
+        "system-metric",
+        help="Get system metric values for a run",
+    )
+    get_system_metric_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_system_metric_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_system_metric_parser.add_argument(
+        "--metric",
+        required=False,
+        help="System metric name (optional, if not provided returns all system metrics)",
+    )
+    get_system_metric_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_alerts_parser = get_subparsers.add_parser(
+        "alerts",
+        help="Get alerts for a project or run",
+    )
+    get_alerts_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_alerts_parser.add_argument(
+        "--run",
+        required=False,
+        help="Run name (optional)",
+    )
+    get_alerts_parser.add_argument(
+        "--level",
+        required=False,
+        help="Filter by alert level (info, warn, error)",
+    )
+    get_alerts_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+    get_alerts_parser.add_argument(
+        "--since",
+        required=False,
+        help="Only show alerts after this ISO 8601 timestamp",
+    )
+
+    get_report_parser = get_subparsers.add_parser(
+        "report",
+        help="Get markdown report entries for a run",
+    )
+    get_report_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_report_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_report_parser.add_argument(
+        "--report",
+        required=True,
+        help="Report metric name",
+    )
+    get_report_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    query_parser = subparsers.add_parser(
+        "query",
+        help="Run a read-only SQL query against a project database",
+    )
+    query_subparsers = query_parser.add_subparsers(dest="query_type", required=True)
+    query_project_parser = query_subparsers.add_parser(
+        "project",
+        help="Run a read-only SQL query against a project's SQLite database",
+    )
+    query_project_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    query_project_parser.add_argument(
+        "--sql",
+        required=True,
+        help="Read-only SQL query to execute",
+    )
+    query_project_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    skills_parser = subparsers.add_parser(
+        "skills",
+        help="Manage Trackio skills for AI coding assistants",
+    )
+    skills_subparsers = skills_parser.add_subparsers(
+        dest="skills_action", required=True
+    )
+    skills_add_parser = skills_subparsers.add_parser(
+        "add",
+        help=(
+            "Install the Trackio skill to the central .agents/skills location; "
+            "pass agent flags to also symlink it for specific assistants"
+        ),
+    )
+    skills_add_parser.add_argument(
+        "--cursor",
+        action="store_true",
+        help="Install for Cursor",
+    )
+    skills_add_parser.add_argument(
+        "--claude",
+        action="store_true",
+        help="Install for Claude Code",
+    )
+    skills_add_parser.add_argument(
+        "--codex",
+        action="store_true",
+        help="Install for Codex",
+    )
+    skills_add_parser.add_argument(
+        "--opencode",
+        action="store_true",
+        help="Install for OpenCode",
+    )
+    skills_add_parser.add_argument(
+        "--pi",
+        action="store_true",
+        help="Install for pi",
+    )
+    skills_add_parser.add_argument(
+        "--global",
+        dest="global_",
+        action="store_true",
+        help="Install globally (user-level) instead of in the current project directory",
+    )
+    skills_add_parser.add_argument(
+        "--dest",
+        type=str,
+        required=False,
+        help="Install into a custom destination (path to skills directory)",
+    )
+    skills_add_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing skill if it already exists",
+    )
+    skills_add_parser.add_argument(
+        "--no-command",
+        dest="no_command",
+        action="store_true",
+        help="Do not install the /logbook slash command alongside the skill",
+    )
+    skills_add_parser.add_argument(
+        "--no-hook",
+        dest="no_hook",
+        action="store_true",
+        help="Do not install the Claude Code hook that mirrors todos into the logbook",
+    )
+
+    logbook_parser = subparsers.add_parser(
+        "logbook",
+        help="Create and publish a shareable experiment logbook",
+    )
+    logbook_sub = logbook_parser.add_subparsers(
+        dest="logbook_action",
+        required=True,
+        metavar="{open,cell,run,page,read,serve,publish,sync}",
+    )
+
+    lb_open = logbook_sub.add_parser(
+        "open", help="Start or attach to the logbook in this directory"
+    )
+    lb_open.add_argument(
+        "space_id", nargs="?", help="Optional HF Space id to publish to"
+    )
+    lb_open.add_argument("--title", help="Logbook title (only when creating)")
+    lb_open.add_argument(
+        "--no-serve",
+        action="store_true",
+        help="Open or attach without launching the local logbook preview",
+    )
+    lb_open.add_argument("--port", type=int, default=7861)
+    lb_open.add_argument("--no-browser", action="store_true")
+
+    lb_cell = logbook_sub.add_parser(
+        "cell", help="Append a typed notebook-style cell to a logbook page"
+    )
+    lb_cell_sub = lb_cell.add_subparsers(dest="cell_type", required=True)
+
+    lb_cell_md = lb_cell_sub.add_parser("markdown", help="Append a markdown cell")
+    lb_cell_md.add_argument(
+        "body",
+        help="Markdown body (literal \\n escape sequences are converted to line breaks)",
+    )
+    lb_cell_md.add_argument("--title", help="Cell title")
+    lb_cell_md.add_argument("--page", help="Page title or slug")
+    lb_cell_art = lb_cell_sub.add_parser(
+        "artifact", help="Append an artifact cell referencing a Trackio artifact"
+    )
+    lb_cell_art.add_argument("name", help="Artifact reference project/name:vN")
+    lb_cell_art.add_argument("--title", help="Cell title")
+    lb_cell_art.add_argument("--page", help="Page title or slug")
+    lb_cell_art.add_argument(
+        "--type",
+        dest="artifact_type",
+        help='Artifact type, e.g. "dataset" or "model"',
+    )
+
+    lb_cell_code = lb_cell_sub.add_parser("code", help="Append a code cell")
+    lb_cell_code.add_argument("--title", help="Cell title")
+    lb_cell_code.add_argument("--page", help="Page title or slug")
+    lb_cell_code.add_argument(
+        "--code", action="append", default=[], help="Path to code/config to include"
+    )
+    lb_cell_code.add_argument("--code-text", help="Inline code to include")
+    lb_cell_code.add_argument("--language", help="Language for --code-text")
+    lb_cell_code.add_argument("--output", required=True, help="Output text")
+
+    lb_cell_figure = lb_cell_sub.add_parser("figure", help="Append a figure cell")
+    lb_cell_figure.add_argument("--title", help="Cell title")
+    lb_cell_figure.add_argument("--page", help="Page title or slug")
+    lb_cell_figure.add_argument(
+        "--html", help="Path to an HTML or image file, or inline HTML text"
+    )
+    lb_cell_figure.add_argument("--html-text", help="Inline HTML text")
+    lb_cell_figure.add_argument(
+        "--image", help="Path to an image file (PNG, JPG, GIF, WEBP, SVG, ...)"
+    )
+    lb_cell_figure.add_argument("--raw", help="Path/URL/text for raw data")
+    lb_cell_figure.add_argument("--raw-text", help="Inline raw data")
+
+    lb_cell_dash = lb_cell_sub.add_parser(
+        "dashboard", help="Embed a Trackio dashboard for a project"
+    )
+    lb_cell_dash.add_argument("project", help="Trackio project name")
+    lb_cell_dash.add_argument(
+        "--space",
+        dest="space_id",
+        help="HF Space id (owner/name) hosting the dashboard",
+    )
+    lb_cell_dash.add_argument("--title", help="Cell title")
+    lb_cell_dash.add_argument("--page", help="Page title or slug")
+
+    lb_run = logbook_sub.add_parser(
+        "run",
+        help="Run a command; log the command, its scripts, and output to a page",
+    )
+    lb_run.add_argument("--page", help="Page title or slug")
+    lb_run.add_argument("--title", help="Cell title")
+    lb_run.add_argument(
+        "--no-artifacts",
+        action="store_true",
+        help="Do not record output model/data files as artifact cells",
+    )
+    lb_run.add_argument("command", nargs="*")
+
+    lb_page = logbook_sub.add_parser(
+        "page", help="Create or select a page and make it the default target"
+    )
+    lb_page.add_argument("title", help="Page title")
+
+    lb_read = logbook_sub.add_parser(
+        "read", help="Read logbook pages/cells in an agent-friendly form"
+    )
+    lb_read.add_argument(
+        "--path",
+        help=(
+            "Logbook to read: local path, HF Space id, or URL "
+            "(can also be passed positionally: trackio logbook read <source>)"
+        ),
+    )
+    lb_read.add_argument("--json", action="store_true", help="Output JSON")
+    lb_read.add_argument(
+        "--head",
+        type=int,
+        default=None,
+        help="Lines of code shown per code cell (default 3; 0 hides code)",
+    )
+    lb_read.add_argument(
+        "--tail",
+        type=int,
+        default=None,
+        help="Lines of output shown per code cell (default 3; 0 hides output)",
+    )
+    lb_read.add_argument(
+        "--raw-limit",
+        type=int,
+        default=None,
+        help="Inline figure raw data up to this many chars (default 500; 0 disables)",
+    )
+    lb_read_sub = lb_read.add_subparsers(dest="read_target")
+    lb_read_pages = lb_read_sub.add_parser("pages", help="List logbook pages")
+    lb_read_pages.add_argument("--json", action="store_true", help="Output JSON")
+    lb_read_page = lb_read_sub.add_parser("page", help="Read a page for agents")
+    lb_read_page.add_argument("page", nargs="?", help="Page title or slug")
+    lb_read_page.add_argument("--json", action="store_true", help="Output JSON")
+    lb_read_page.add_argument(
+        "--head", type=int, default=argparse.SUPPRESS, help="Code lines per code cell"
+    )
+    lb_read_page.add_argument(
+        "--tail", type=int, default=argparse.SUPPRESS, help="Output lines per code cell"
+    )
+    lb_read_page.add_argument(
+        "--raw-limit",
+        type=int,
+        default=argparse.SUPPRESS,
+        help="Inline figure raw data up to this many chars",
+    )
+    lb_read_cell = lb_read_sub.add_parser("cell", help="Read one cell by id")
+    lb_read_cell.add_argument("cell_id", help="Cell id")
+    lb_read_cell.add_argument("--json", action="store_true", help="Output JSON")
+    lb_read_cell.add_argument("--full", action="store_true", help="Include full body")
+    lb_read_cell.add_argument(
+        "--raw", action="store_true", help="Include figure raw data"
+    )
+    lb_read_cell.add_argument("--html", action="store_true", help="Include figure HTML")
+
+    lb_serve = logbook_sub.add_parser("serve", help="Preview the logbook locally")
+    lb_serve.add_argument("path", nargs="?", help="Logbook workspace/path to serve")
+    lb_serve.add_argument("--port", type=int, default=7861)
+    lb_serve.add_argument("--no-browser", action="store_true")
+
+    lb_pub = logbook_sub.add_parser(
+        "publish", help="Publish to a static HF Space (first publish enables auto-sync)"
+    )
+    lb_pub.add_argument("space_id", nargs="?", help="HF Space id (username/space)")
+    lb_pub.add_argument(
+        "--private",
+        action="store_true",
+        help="Make the logbook and any promoted dashboards/buckets private",
+    )
+
+    lb_pin = logbook_sub.add_parser(
+        "pin",
+        help="Pin (or unpin) a cell so it surfaces on the logbook intro",
+    )
+    lb_pin.add_argument(
+        "cell_id",
+        nargs="?",
+        help="Cell id to pin (default: the most recent cell on the target page)",
+    )
+    lb_pin.add_argument(
+        "--page",
+        help="Page title or slug to scope the search / pick the last cell from",
+    )
+    lb_pin.add_argument(
+        "--unpin", action="store_true", help="Unpin the cell instead of pinning it"
+    )
+
+    logbook_sub.add_parser(
+        "sync", help="Push local edits to the Space now (after the first publish)"
+    )
+
+    logbook_sub.add_parser("_sync")
+    logbook_sub.add_parser("sync-todos")
+
+    args, unknown_args = parser.parse_known_args()
+    if unknown_args:
+        trailing_global_parser = argparse.ArgumentParser(add_help=False)
+        trailing_global_parser.add_argument("--space", required=False)
+        trailing_global_parser.add_argument("--hf-token", required=False)
+        trailing_globals, remaining_unknown = trailing_global_parser.parse_known_args(
+            unknown_args
+        )
+        if remaining_unknown:
+            parser.error(f"unrecognized arguments: {' '.join(remaining_unknown)}")
+        if trailing_globals.space is not None:
+            args.space = trailing_globals.space
+        if trailing_globals.hf_token is not None:
+            args.hf_token = trailing_globals.hf_token
+
+    if args.command in ("show", "status", "sync", "freeze", "skills") and _get_space(
+        args
+    ):
+        error_exit(
+            f"The '{args.command}' command does not support --space (remote mode)."
+        )
+
+    if args.command == "show":
+        color_palette = None
+        if args.color_palette:
+            color_palette = [color.strip() for color in args.color_palette.split(",")]
+        show(
+            project=args.project,
+            theme=args.theme,
+            mcp_server=args.mcp_server,
+            footer=args.footer,
+            color_palette=color_palette,
+            host=args.host,
+            frontend_dir=args.frontend,
+        )
+    elif args.command == "status":
+        _handle_status()
+    elif args.command == "sync":
+        _handle_sync(args)
+    elif args.command == "freeze":
+        freeze(
+            space_id=args.space_id,
+            project=args.project,
+            new_space_id=args.new_space_id,
+            private=args.private,
+            frontend_dir=args.frontend,
+        )
+    elif args.command == "config":
+        _handle_config(args)
+    elif args.command == "list":
+        if args.list_type == "spaces":
+            _handle_list_spaces(args)
+            return
+
+        remote = _get_remote(args)
+        if args.list_type == "projects":
+            if remote:
+                projects = remote.predict(api_name="/get_all_projects")
+            else:
+                projects = SQLiteStorage.get_projects()
+            if args.json:
+                print(format_json({"projects": projects}))
+            else:
+                print(format_list(projects, "Projects"))
+        elif args.list_type == "runs":
+            if remote:
+                run_records = remote.predict(
+                    args.project, api_name="/get_runs_for_project"
+                )
+                runs = [r["name"] if isinstance(r, dict) else r for r in run_records]
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+            if args.json:
+                print(format_json({"project": args.project, "runs": runs}))
+            else:
+                print(format_list(runs, f"Runs in '{args.project}'"))
+        elif args.list_type == "metrics":
+            if remote:
+                metrics = remote.predict(
+                    args.project, args.run, api_name="/get_metrics_for_run"
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                metrics = SQLiteStorage.get_all_metrics_for_run(args.project, args.run)
+            if args.json:
+                print(
+                    format_json(
+                        {"project": args.project, "run": args.run, "metrics": metrics}
+                    )
+                )
+            else:
+                print(
+                    format_list(
+                        metrics, f"Metrics for '{args.run}' in '{args.project}'"
+                    )
+                )
+        elif args.list_type == "system-metrics":
+            if remote:
+                system_metrics = remote.predict(
+                    args.project, args.run, api_name="/get_system_metrics_for_run"
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                system_metrics = SQLiteStorage.get_all_system_metrics_for_run(
+                    args.project, args.run
+                )
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "system_metrics": system_metrics,
+                        }
+                    )
+                )
+            else:
+                print(format_system_metric_names(system_metrics))
+        elif args.list_type == "alerts":
+            if remote:
+                alerts = remote.predict(
+                    args.project,
+                    args.run,
+                    args.level,
+                    args.since,
+                    api_name="/get_alerts",
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                alerts = SQLiteStorage.get_alerts(
+                    args.project,
+                    run_name=args.run,
+                    level=args.level,
+                    since=args.since,
+                )
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "level": args.level,
+                            "since": args.since,
+                            "alerts": alerts,
+                        }
+                    )
+                )
+            else:
+                print(format_alerts(alerts))
+        elif args.list_type == "reports":
+            if remote:
+                run_records = remote.predict(
+                    args.project, api_name="/get_runs_for_project"
+                )
+                runs = [r["name"] if isinstance(r, dict) else r for r in run_records]
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+            if args.run and args.run not in runs:
+                error_exit(f"Run '{args.run}' not found in project '{args.project}'.")
+
+            target_runs = [args.run] if args.run else runs
+            all_reports = []
+            for run_name in target_runs:
+                if remote:
+                    logs = remote.predict(args.project, run_name, api_name="/get_logs")
+                else:
+                    logs = SQLiteStorage.get_logs(args.project, run_name)
+                all_reports.extend(_extract_reports(run_name, logs))
+
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "reports": all_reports,
+                        }
+                    )
+                )
+            else:
+                report_lines = [
+                    f"{entry['run']} | {entry['report']} | step={entry['step']} | {entry['timestamp']}"
+                    for entry in all_reports
+                ]
+                if args.run:
+                    print(
+                        format_list(
+                            report_lines,
+                            f"Reports for '{args.run}' in '{args.project}'",
+                        )
+                    )
+                else:
+                    print(format_list(report_lines, f"Reports in '{args.project}'"))
+        elif args.list_type == "artifacts":
+            if remote:
+                artifacts = remote.predict(args.project, api_name="/get_artifacts")
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                artifacts = SQLiteStorage.get_artifacts(args.project)
+            if args.json:
+                print(format_json({"project": args.project, "artifacts": artifacts}))
+            else:
+                print(format_artifacts(artifacts, args.project))
+    elif args.command == "get":
+        remote = _get_remote(args)
+        if args.get_type == "artifact":
+            if remote:
+                record = remote.predict(
+                    args.project,
+                    args.name,
+                    args.version,
+                    api_name="/get_artifact_manifest",
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                record = SQLiteStorage.get_artifact_manifest(
+                    args.project, args.name, args.version
+                )
+            if record is None:
+                spec = f":{args.version}" if args.version else ""
+                error_exit(
+                    f"Artifact '{args.name}{spec}' not found in project "
+                    f"'{args.project}'."
+                )
+            if args.json:
+                print(format_json(record))
+            else:
+                print(format_artifact(record))
+        elif args.get_type == "project":
+            if remote:
+                summary = remote.predict(args.project, api_name="/get_project_summary")
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                summary = get_project_summary(args.project)
+            if args.json:
+                print(format_json(summary))
+            else:
+                print(format_project_summary(summary))
+        elif args.get_type == "run":
+            if remote:
+                summary = remote.predict(
+                    args.project, args.run, api_name="/get_run_summary"
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                summary = get_run_summary(args.project, args.run)
+            if args.json:
+                print(format_json(summary))
+            else:
+                print(format_run_summary(summary))
+        elif args.get_type == "metric":
+            at_time = getattr(args, "at_time", None)
+            if remote:
+                values = remote.predict(
+                    args.project,
+                    args.run,
+                    args.metric,
+                    args.step,
+                    args.around,
+                    at_time,
+                    args.window,
+                    api_name="/get_metric_values",
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                metrics = SQLiteStorage.get_all_metrics_for_run(args.project, args.run)
+                if args.metric not in metrics:
+                    error_exit(
+                        f"Metric '{args.metric}' not found in run '{args.run}' of project '{args.project}'."
+                    )
+                values = SQLiteStorage.get_metric_values(
+                    args.project,
+                    args.run,
+                    args.metric,
+                    step=args.step,
+                    around_step=args.around,
+                    at_time=at_time,
+                    window=args.window,
+                )
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "metric": args.metric,
+                            "values": values,
+                        }
+                    )
+                )
+            else:
+                print(format_metric_values(values))
+        elif args.get_type == "snapshot":
+            if not args.step and not args.around and not getattr(args, "at_time", None):
+                error_exit(
+                    "Provide --step, --around (with --window), or --at-time (with --window)."
+                )
+            at_time = getattr(args, "at_time", None)
+            if remote:
+                snapshot = remote.predict(
+                    args.project,
+                    args.run,
+                    args.step,
+                    args.around,
+                    at_time,
+                    args.window,
+                    api_name="/get_snapshot",
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                snapshot = SQLiteStorage.get_snapshot(
+                    args.project,
+                    args.run,
+                    step=args.step,
+                    around_step=args.around,
+                    at_time=at_time,
+                    window=args.window,
+                )
+            if args.json:
+                result = {
+                    "project": args.project,
+                    "run": args.run,
+                    "metrics": snapshot,
+                }
+                if args.step is not None:
+                    result["step"] = args.step
+                if args.around is not None:
+                    result["around"] = args.around
+                    result["window"] = args.window
+                if at_time is not None:
+                    result["at_time"] = at_time
+                    result["window"] = args.window
+                print(format_json(result))
+            else:
+                print(format_snapshot(snapshot))
+        elif args.get_type == "system-metric":
+            if remote:
+                system_metrics = remote.predict(
+                    args.project, args.run, api_name="/get_system_logs"
+                )
+                if args.metric:
+                    all_system_metric_names = remote.predict(
+                        args.project,
+                        args.run,
+                        api_name="/get_system_metrics_for_run",
+                    )
+                    if args.metric not in all_system_metric_names:
+                        error_exit(
+                            f"System metric '{args.metric}' not found in run '{args.run}' of project '{args.project}'."
+                        )
+                    filtered_metrics = [
+                        {
+                            k: v
+                            for k, v in entry.items()
+                            if k == "timestamp" or k == args.metric
+                        }
+                        for entry in system_metrics
+                        if args.metric in entry
+                    ]
+                    if args.json:
+                        print(
+                            format_json(
+                                {
+                                    "project": args.project,
+                                    "run": args.run,
+                                    "metric": args.metric,
+                                    "values": filtered_metrics,
+                                }
+                            )
+                        )
+                    else:
+                        print(format_system_metrics(filtered_metrics))
+                else:
+                    if args.json:
+                        print(
+                            format_json(
+                                {
+                                    "project": args.project,
+                                    "run": args.run,
+                                    "system_metrics": system_metrics,
+                                }
+                            )
+                        )
+                    else:
+                        print(format_system_metrics(system_metrics))
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                if args.metric:
+                    system_metrics = SQLiteStorage.get_system_logs(
+                        args.project, args.run
+                    )
+                    all_system_metric_names = (
+                        SQLiteStorage.get_all_system_metrics_for_run(
+                            args.project, args.run
+                        )
+                    )
+                    if args.metric not in all_system_metric_names:
+                        error_exit(
+                            f"System metric '{args.metric}' not found in run '{args.run}' of project '{args.project}'."
+                        )
+                    filtered_metrics = [
+                        {
+                            k: v
+                            for k, v in entry.items()
+                            if k == "timestamp" or k == args.metric
+                        }
+                        for entry in system_metrics
+                        if args.metric in entry
+                    ]
+                    if args.json:
+                        print(
+                            format_json(
+                                {
+                                    "project": args.project,
+                                    "run": args.run,
+                                    "metric": args.metric,
+                                    "values": filtered_metrics,
+                                }
+                            )
+                        )
+                    else:
+                        print(format_system_metrics(filtered_metrics))
+                else:
+                    system_metrics = SQLiteStorage.get_system_logs(
+                        args.project, args.run
+                    )
+                    if args.json:
+                        print(
+                            format_json(
+                                {
+                                    "project": args.project,
+                                    "run": args.run,
+                                    "system_metrics": system_metrics,
+                                }
+                            )
+                        )
+                    else:
+                        print(format_system_metrics(system_metrics))
+        elif args.get_type == "alerts":
+            if remote:
+                alerts = remote.predict(
+                    args.project,
+                    args.run,
+                    args.level,
+                    args.since,
+                    api_name="/get_alerts",
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                alerts = SQLiteStorage.get_alerts(
+                    args.project,
+                    run_name=args.run,
+                    level=args.level,
+                    since=args.since,
+                )
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "level": args.level,
+                            "since": args.since,
+                            "alerts": alerts,
+                        }
+                    )
+                )
+            else:
+                print(format_alerts(alerts))
+        elif args.get_type == "report":
+            if remote:
+                logs = remote.predict(args.project, args.run, api_name="/get_logs")
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                logs = SQLiteStorage.get_logs(args.project, args.run)
+
+            reports = _extract_reports(args.run, logs, report_name=args.report)
+            if not reports:
+                error_exit(
+                    f"Report '{args.report}' not found in run '{args.run}' of project '{args.project}'."
+                )
+
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "report": args.report,
+                            "values": reports,
+                        }
+                    )
+                )
+            else:
+                output = []
+                for idx, entry in enumerate(reports, start=1):
+                    output.append(
+                        f"Entry {idx} | step={entry['step']} | timestamp={entry['timestamp']}"
+                    )
+                    output.append(entry["content"])
+                    if idx < len(reports):
+                        output.append("-" * 80)
+                print("\n".join(output))
+    elif args.command == "query":
+        if args.query_type == "project":
+            _handle_query(args)
+    elif args.command == "skills":
+        if args.skills_action == "add":
+            _handle_skills_add(args)
+    elif args.command == "logbook":
+        _handle_logbook(args)
+    else:
+        parser.print_help()
+
+
+def _sync_suffix(lb, proj):
+    if lb.is_autosync(proj):
+        space = lb.read_metadata(proj).get("space_id")
+        return f" · syncing to {space}…"
+    return ""
+
+
+def _logbook_cell_target(lb, proj, args):
+    return lb.resolve_page(proj, getattr(args, "page", None))
+
+
+def _print_logbook_pages(pages):
+    if not pages:
+        print("No pages.")
+        return
+    print("Pages:")
+    for page in pages:
+        count = page["cell_count"]
+        print(
+            f"- {page['slug']} · {page['title']} · "
+            f"{count} cell{'' if count == 1 else 's'}"
+        )
+
+
+def _print_logbook_page_outline(page):
+    print(f"Page: {page['title']} ({page['slug']})")
+    if not page["cells"]:
+        print("No cells.")
+        return
+    for cell in page["cells"]:
+        created = (
+            f" · {cell['created_at'].replace('T', ' ')[:16]}"
+            if cell.get("created_at")
+            else ""
+        )
+        print(f"\n### {cell['title']} · {cell['type']} · {cell['id']}{created}")
+        if cell.get("preview"):
+            print(cell["preview"].rstrip())
+    print(
+        "\nFetch full payloads with: trackio logbook read cell <cell-id> "
+        "[--full|--raw|--html]"
+    )
+
+
+def _print_logbook_cell(cell):
+    print(f"Cell: {cell['title']} ({cell['id']})")
+    print(f"Page: {cell['page_title']} ({cell['page']})")
+    print(f"Type: {cell['type']}")
+    if cell.get("created_at"):
+        print(f"Created: {cell['created_at']}")
+    content_keys = [key for key in ("body", "raw", "html") if key in cell]
+    if not content_keys:
+        if cell["type"] == "code":
+            print("\nBody omitted. Use --full to include code/output.")
+        elif cell["type"] == "figure":
+            print("\nFigure content omitted. Use --raw, --html, or --full.")
+        return
+    for key in content_keys:
+        label = key.upper()
+        print(f"\n--- {label} ---\n")
+        print(cell[key])
+
+
+def _read_logbook_payload(path_or_text, inline_text):
+    if inline_text is not None:
+        return inline_text
+    if not path_or_text:
+        return ""
+    path = Path(path_or_text)
+    if path.is_file():
+        return path.read_text(encoding="utf-8")
+    return path_or_text
+
+
+def _handle_logbook(args):
+    from trackio import logbook as lb
+
+    action = args.logbook_action
+    try:
+        if action == "open":
+            print("Warning: Trackio Logbook is an experimental feature.")
+            proj = lb.find_project_dir()
+            if proj is not None:
+                if args.space_id:
+                    metadata = lb.read_metadata(proj)
+                    metadata["space_id"] = args.space_id
+                    lb.write_metadata(proj, metadata)
+                print(f"Attached to existing logbook at {lb.logbook_root(proj)}")
+                if args.title:
+                    print(
+                        "Note: --title was ignored because this logbook already "
+                        "exists. To retitle it, edit the '# ...' heading in "
+                        f"{lb.logbook_root(proj) / 'pages' / 'index.md'}."
+                    )
+            elif args.space_id:
+                proj = lb.clone_logbook(args.space_id)
+                if proj is not None:
+                    print(
+                        f"Cloned logbook from {args.space_id} into "
+                        f"{lb.logbook_root(proj)}"
+                    )
+            if proj is None:
+                proj = lb.create_logbook(
+                    args.title or os.path.basename(os.getcwd()), space_id=args.space_id
+                )
+                print(f"Opened logbook at {lb.logbook_root(proj)}")
+                if args.space_id:
+                    print(f"Will publish to: {args.space_id}")
+            if not args.no_serve:
+                lb.start_preview(proj, port=args.port, open_browser=not args.no_browser)
+        elif action == "run":
+            proj = lb.require_project_dir()
+            command = list(args.command or [])
+            if command and command[0] == "--":
+                command = command[1:]
+            if not command:
+                error_exit("No command provided. Use: trackio logbook run -- <command>")
+            rc = lb.run_and_log(
+                proj,
+                command,
+                page=args.page,
+                title=args.title,
+                capture_artifacts=not getattr(args, "no_artifacts", False),
+            )
+            slug = lb.read_metadata(proj).get("last_page", "?")
+            print(f"Logged run to page '{slug}'.{_sync_suffix(lb, proj)}")
+            sys.exit(rc)
+        elif action == "cell":
+            proj = lb.require_project_dir()
+            slug = _logbook_cell_target(lb, proj, args)
+            if args.cell_type == "markdown":
+                # Agent/tool callers often send a single argument containing
+                # escaped newlines. Treat those as Markdown line breaks while
+                # preserving normal shell-provided newlines unchanged.
+                body = args.body.replace("\\r\\n", "\n").replace("\\n", "\n")
+                lb.add_markdown_cell(proj, slug, body, title=args.title)
+            elif args.cell_type == "artifact":
+                lb.add_artifact_cell(
+                    proj,
+                    slug,
+                    args.name,
+                    title=args.title,
+                    artifact_type=args.artifact_type,
+                )
+            elif args.cell_type == "code":
+                lb.add_code_cell(
+                    proj,
+                    slug,
+                    args.output,
+                    title=args.title,
+                    code_paths=args.code,
+                    code_text=args.code_text,
+                    language=args.language,
+                )
+            elif args.cell_type == "figure":
+                if args.image:
+                    html = lb.figure_html_from_image(args.image)
+                elif (
+                    args.html
+                    and args.html_text is None
+                    and Path(args.html).is_file()
+                    and lb.is_figure_image_path(args.html)
+                ):
+                    # `--html plot.png` — embed the image instead of trying to
+                    # read a binary file as UTF-8 text.
+                    html = lb.figure_html_from_image(args.html)
+                else:
+                    html = _read_logbook_payload(args.html, args.html_text)
+                raw = _read_logbook_payload(args.raw, args.raw_text)
+                lb.add_figure_cell(
+                    proj,
+                    slug,
+                    html=html,
+                    raw=raw,
+                    title=args.title,
+                )
+            elif args.cell_type == "dashboard":
+                lb.add_dashboard_cell(
+                    proj,
+                    slug,
+                    args.project,
+                    space_id=args.space_id,
+                    title=args.title,
+                )
+            print(
+                f"Logged {args.cell_type} cell to page "
+                f"'{slug}'.{_sync_suffix(lb, proj)}"
+            )
+            lb.trigger_autosync(proj)
+        elif action == "page":
+            proj = lb.require_project_dir()
+            page_slug = lb.ensure_page(proj, args.title)
+            print(f"Selected page '{page_slug}' as default.{_sync_suffix(lb, proj)}")
+            lb.trigger_autosync(proj)
+        elif action == "pin":
+            proj = lb.require_project_dir()
+            cell_id = args.cell_id or lb.last_cell_id(proj, page=args.page)
+            if not cell_id:
+                error_exit(
+                    "No cell to pin. Pass a cell id, or add a cell first "
+                    "(optionally scope with --page)."
+                )
+            res = lb.set_cell_pinned(
+                proj, cell_id, pinned=not args.unpin, page=args.page
+            )
+            verb = "Unpinned" if args.unpin else "Pinned"
+            print(
+                f"{verb} cell {cell_id} on page "
+                f"'{res['page']}'.{_sync_suffix(lb, proj)}"
+            )
+            lb.trigger_autosync(proj)
+        elif action == "read":
+            proj = lb.resolve_read_source(args.path)
+            preview_opts = {
+                "head": lb.DEFAULT_HEAD
+                if getattr(args, "head", None) is None
+                else args.head,
+                "tail": lb.DEFAULT_TAIL
+                if getattr(args, "tail", None) is None
+                else args.tail,
+                "raw_limit": lb.DEFAULT_RAW_LIMIT
+                if getattr(args, "raw_limit", None) is None
+                else args.raw_limit,
+            }
+            if args.read_target is None:
+                if args.json:
+                    print(format_json(lb.read_logbook_data(proj, **preview_opts)))
+                else:
+                    print(lb.read_logbook(proj, **preview_opts))
+            elif args.read_target == "pages":
+                pages = lb.list_pages(proj)
+                if args.json:
+                    print(format_json({"pages": pages}))
+                else:
+                    _print_logbook_pages(pages)
+            elif args.read_target == "page":
+                page = lb.read_page_outline(proj, args.page, **preview_opts)
+                if args.json:
+                    print(format_json(page))
+                else:
+                    _print_logbook_page_outline(page)
+            elif args.read_target == "cell":
+                cell = lb.read_cell(
+                    proj,
+                    args.cell_id,
+                    include_full=args.full,
+                    include_raw=args.raw,
+                    include_html=args.html,
+                )
+                if args.json:
+                    print(format_json(cell))
+                else:
+                    _print_logbook_cell(cell)
+        elif action == "_sync":
+            lb.sync_worker()
+        elif action == "sync-todos":
+            lb.sync_todos_from_stdin()
+        elif action == "serve":
+            lb.serve(path=args.path, port=args.port, open_browser=not args.no_browser)
+        elif action == "publish":
+            url = lb.publish(space_id=args.space_id, private=args.private)
+            print(f"Published: {url}")
+            space_id = lb.read_metadata(lb.require_project_dir()).get("space_id")
+            if space_id:
+                subdomain = re.sub(r"[^a-z0-9]+", "-", space_id.lower()).strip("-")
+                print(f"Rendered at: https://{subdomain}.static.hf.space/")
+        elif action == "sync":
+            proj = lb.require_project_dir()
+            if not lb.is_autosync(proj):
+                error_exit("Publish first: trackio logbook publish <username/space>")
+            lb.trigger_autosync(proj)
+            print(f"Syncing to {lb.read_metadata(proj).get('space_id')}…")
+    except lb.LogbookError as e:
+        error_exit(str(e))
+
+
+def _handle_skills_add(args):
+    import shutil
+    from pathlib import Path
+
+    CENTRAL_LOCAL = Path(".agents/skills")
+    CENTRAL_GLOBAL = Path("~/.agents/skills")
+    CLAUDE_LOCAL = Path(".claude/skills")
+    CLAUDE_GLOBAL = Path("~/.claude/skills")
+
+    SKILL_ID = "trackio"
+    GITHUB_RAW = "https://raw.githubusercontent.com/gradio-app/trackio/main"
+    SKILL_PREFIX = ".agents/skills/trackio"
+    SKILL_FILES = [
+        "SKILL.md",
+        "alerts.md",
+        "logging_metrics.md",
+        "retrieving_metrics.md",
+        "storage_schema.md",
+        "logbook.md",
+    ]
+    COMMAND_PREFIX = ".agents/commands"
+    COMMAND_FILE = "logbook.md"
+
+    REPO_ROOT = Path(__file__).resolve().parent.parent
+    USE_LOCAL = (REPO_ROOT / SKILL_PREFIX / "SKILL.md").is_file()
+
+    if USE_LOCAL:
+        print(f"Using local Trackio source at {REPO_ROOT}")
+
+    def download(url: str) -> str:
+        from huggingface_hub.utils import get_session
+
+        try:
+            response = get_session().get(url)
+            response.raise_for_status()
+        except Exception as e:
+            error_exit(
+                f"Failed to download {url}\n{e}\n\n"
+                "Make sure you have internet access. The skill files are fetched from "
+                "the Trackio GitHub repository."
+            )
+        return response.text
+
+    def get_content(prefix: str, fname: str) -> str:
+        if USE_LOCAL:
+            local = REPO_ROOT / prefix / fname
+            if local.is_file():
+                return local.read_text(encoding="utf-8")
+        return download(f"{GITHUB_RAW}/{prefix}/{fname}")
+
+    def remove_existing(path: Path, force: bool):
+        if not (path.exists() or path.is_symlink()):
+            return
+        if not force:
+            error_exit(
+                f"Skill already exists at {path}.\nRe-run with --force to overwrite."
+            )
+        if path.is_dir() and not path.is_symlink():
+            shutil.rmtree(path)
+        else:
+            path.unlink()
+
+    def install_to(skills_dir: Path, force: bool) -> Path:
+        skills_dir = skills_dir.expanduser().resolve()
+        skills_dir.mkdir(parents=True, exist_ok=True)
+        dest = skills_dir / SKILL_ID
+        remove_existing(dest, force)
+        dest.mkdir()
+        for fname in SKILL_FILES:
+            (dest / fname).write_text(
+                get_content(SKILL_PREFIX, fname), encoding="utf-8"
+            )
+        return dest
+
+    def create_symlink(
+        agent_skills_dir: Path, central_skill_path: Path, force: bool
+    ) -> Path:
+        agent_skills_dir = agent_skills_dir.expanduser().resolve()
+        agent_skills_dir.mkdir(parents=True, exist_ok=True)
+        link_path = agent_skills_dir / SKILL_ID
+        remove_existing(link_path, force)
+        link_path.symlink_to(os.path.relpath(central_skill_path, agent_skills_dir))
+        return link_path
+
+    def install_command(
+        command_dir: Path, force: bool, strip_frontmatter: bool = False
+    ) -> Path:
+        import re
+
+        command_dir = command_dir.expanduser().resolve()
+        command_dir.mkdir(parents=True, exist_ok=True)
+        dest = command_dir / COMMAND_FILE
+        if dest.exists() and not force:
+            error_exit(
+                f"Command already exists at {dest}.\nRe-run with --force to overwrite."
+            )
+        content = get_content(COMMAND_PREFIX, COMMAND_FILE)
+        if strip_frontmatter:
+            content = re.sub(r"\A---\n.*?\n---\n+", "", content, flags=re.S)
+        dest.write_text(content, encoding="utf-8")
+        return dest
+
+    global_targets = {
+        "cursor": Path("~/.cursor/skills"),
+        "claude": CLAUDE_GLOBAL,
+        "codex": Path("~/.codex/skills"),
+        "opencode": Path("~/.opencode/skills"),
+        "pi": Path("~/.pi/agent/skills"),
+    }
+    local_targets = {
+        "cursor": Path(".cursor/skills"),
+        "claude": CLAUDE_LOCAL,
+        "codex": Path(".codex/skills"),
+        "opencode": Path(".opencode/skills"),
+        "pi": Path(".pi/skills"),
+    }
+    targets_dict = global_targets if args.global_ else local_targets
+
+    command_targets_global = {
+        "cursor": Path("~/.cursor/commands"),
+        "claude": Path("~/.claude/commands"),
+        "codex": Path("~/.codex/prompts"),
+        "opencode": Path("~/.config/opencode/commands"),
+        "pi": Path("~/.pi/agent/prompts"),
+    }
+    command_targets_local = {
+        "cursor": Path(".cursor/commands"),
+        "claude": Path(".claude/commands"),
+        "codex": Path("~/.codex/prompts"),
+        "opencode": Path(".opencode/commands"),
+        "pi": Path(".pi/prompts"),
+    }
+    command_dict = command_targets_global if args.global_ else command_targets_local
+    COMMAND_NOTES = {
+        "codex": " (Codex only reads ~/.codex/prompts; restart Codex to pick it up)"
+    }
+    STRIP_FRONTMATTER = {"pi"}
+
+    if args.dest:
+        if (
+            args.cursor
+            or args.claude
+            or args.codex
+            or args.opencode
+            or args.pi
+            or args.global_
+        ):
+            error_exit("--dest cannot be combined with agent flags or --global.")
+        skill_dest = install_to(Path(args.dest), args.force)
+        print(f"Installed '{SKILL_ID}' to {skill_dest}")
+        return
+
+    selected = [
+        name
+        for name, flag in (
+            ("cursor", args.cursor),
+            ("claude", args.claude),
+            ("codex", args.codex),
+            ("opencode", args.opencode),
+            ("pi", args.pi),
+        )
+        if flag
+    ]
+
+    central_path = CENTRAL_GLOBAL if args.global_ else CENTRAL_LOCAL
+    central_skill_path = install_to(central_path, args.force)
+    print(f"Installed '{SKILL_ID}' to central location: {central_skill_path}")
+
+    for name in selected:
+        link_path = create_symlink(targets_dict[name], central_skill_path, args.force)
+        print(f"Created symlink: {link_path}")
+
+    if not args.no_command:
+        for name in selected:
+            if name in command_dict:
+                cmd_path = install_command(
+                    command_dict[name],
+                    args.force,
+                    strip_frontmatter=name in STRIP_FRONTMATTER,
+                )
+                note = COMMAND_NOTES.get(name, "")
+                print(f"Installed '/logbook' command: {cmd_path}{note}")
+            else:
+                print(
+                    f"Skipped '/logbook' command for {name} "
+                    "(no slash-command directory convention)."
+                )
+
+    if args.claude and not args.no_hook:
+        hook_path = _install_claude_logbook_hook(args.global_)
+        if hook_path:
+            print(f"Installed logbook todo-sync hook: {hook_path}")
+
+
+def _install_claude_logbook_hook(global_: bool):
+    import json
+    from pathlib import Path
+
+    settings = (
+        Path("~/.claude/settings.json") if global_ else Path(".claude/settings.json")
+    ).expanduser()
+    settings.parent.mkdir(parents=True, exist_ok=True)
+    data = {}
+    if settings.exists():
+        try:
+            data = json.loads(settings.read_text(encoding="utf-8"))
+        except Exception:
+            print(f"Could not parse {settings}; skipping hook install.")
+            return None
+    command = "trackio logbook sync-todos"
+    hooks = data.setdefault("hooks", {})
+    post = hooks.setdefault("PostToolUse", [])
+    for entry in post:
+        for h in entry.get("hooks", []):
+            if h.get("command") == command:
+                return settings
+    post.append(
+        {
+            "matcher": "TodoWrite",
+            "hooks": [{"type": "command", "command": command}],
+        }
+    )
+    settings.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    return settings
+
+
+if __name__ == "__main__":
+    main()

trackio/cli_helpers.py

@@ -0,0 +1,268 @@
+import json
+import sys
+from typing import Any
+
+from trackio import references
+
+
+def format_json(data: Any) -> str:
+    """Format data as JSON."""
+    return json.dumps(data, indent=2)
+
+
+def format_list(items: list[str], title: str | None = None) -> str:
+    """Format a list of items in human-readable format."""
+    if not items:
+        return f"No {title.lower() if title else 'items'} found."
+
+    output = []
+    if title:
+        output.append(f"{title}:")
+
+    for item in items:
+        output.append(f"  - {item}")
+
+    return "\n".join(output)
+
+
+def format_artifacts(artifacts: list[dict], project: str | None = None) -> str:
+    """Format a project's artifacts in human-readable format."""
+    if not artifacts:
+        return "No artifacts found."
+
+    title = f"Artifacts in '{project}'" if project else "Artifacts"
+    output = [f"{title}:"]
+    for art in artifacts:
+        latest = art.get("latest_version")
+        version = f"v{latest}" if latest is not None else "(no versions)"
+        aliases = art.get("aliases") or []
+        alias_str = f" [{', '.join(aliases)}]" if aliases else ""
+        output.append(
+            f"  - {art['name']} ({art.get('type', '?')}) "
+            f"latest={version}{alias_str} "
+            f"versions={art.get('num_versions', 0)}"
+        )
+        if art.get("description"):
+            output.append(f"      {art['description']}")
+    return "\n".join(output)
+
+
+def format_artifact(record: dict) -> str:
+    """Format a single resolved artifact version in human-readable format."""
+    lines = [
+        f"Artifact: {record['name']} (v{record['version']})",
+        f"  type:        {record.get('type')}",
+    ]
+    if record.get("description"):
+        lines.append(f"  description: {record['description']}")
+    aliases = record.get("aliases") or []
+    if aliases:
+        lines.append(f"  aliases:     {', '.join(aliases)}")
+    if record.get("metadata"):
+        lines.append(f"  metadata:    {record['metadata']}")
+    lines.append(f"  size:        {record.get('size_bytes')} bytes")
+    lines.append(f"  digest:      {record.get('manifest_digest')}")
+    manifest = record.get("manifest") or []
+    lines.append(f"  files ({len(manifest)}):")
+    for entry in manifest:
+        if references.is_reference_entry(entry):
+            lines.append(f"    - {entry['path']} -> {entry['ref']} (reference)")
+        else:
+            lines.append(f"    - {entry['path']} ({entry['size']} bytes)")
+    return "\n".join(lines)
+
+
+def format_spaces(spaces: list[dict]) -> str:
+    """Format HF Spaces in human-readable format."""
+    if not spaces:
+        return "No Trackio Spaces found."
+
+    output = ["Trackio Spaces:"]
+    for space in spaces:
+        visibility = "private" if space.get("private") else "public"
+        output.append(f"  - {space['id']} ({visibility})")
+        if space.get("url"):
+            output.append(f"    {space['url']}")
+
+    return "\n".join(output)
+
+
+def format_project_summary(summary: dict) -> str:
+    """Format project summary in human-readable format."""
+    output = [f"Project: {summary['project']}"]
+    output.append(f"Number of runs: {summary['num_runs']}")
+
+    if summary["runs"]:
+        output.append("\nRuns:")
+        for run in summary["runs"]:
+            output.append(f"  - {run}")
+    else:
+        output.append("\nNo runs found.")
+
+    if summary.get("last_activity"):
+        output.append(f"\nLast activity (max step): {summary['last_activity']}")
+
+    return "\n".join(output)
+
+
+def format_run_summary(summary: dict) -> str:
+    """Format run summary in human-readable format."""
+    output = [f"Project: {summary['project']}"]
+    output.append(f"Run: {summary['run']}")
+    output.append(f"Number of logs: {summary['num_logs']}")
+
+    if summary.get("last_step") is not None:
+        output.append(f"Last step: {summary['last_step']}")
+
+    if summary.get("metrics"):
+        output.append("\nMetrics:")
+        for metric in summary["metrics"]:
+            output.append(f"  - {metric}")
+    else:
+        output.append("\nNo metrics found.")
+
+    config = summary.get("config")
+    if config:
+        output.append("\nConfig:")
+        config_display = {k: v for k, v in config.items() if not k.startswith("_")}
+        if config_display:
+            for key, value in config_display.items():
+                output.append(f"  {key}: {value}")
+        else:
+            output.append("  (no config)")
+    else:
+        output.append("\nConfig: (no config)")
+
+    return "\n".join(output)
+
+
+def format_metric_values(values: list[dict]) -> str:
+    """Format metric values in human-readable format."""
+    if not values:
+        return "No metric values found."
+
+    output = [f"Found {len(values)} value(s):\n"]
+    output.append("Step | Timestamp | Value")
+    output.append("-" * 50)
+
+    for value in values:
+        step = value.get("step", "N/A")
+        timestamp = value.get("timestamp", "N/A")
+        val = value.get("value", "N/A")
+        output.append(f"{step} | {timestamp} | {val}")
+
+    return "\n".join(output)
+
+
+def format_system_metrics(metrics: list[dict]) -> str:
+    """Format system metrics in human-readable format."""
+    if not metrics:
+        return "No system metrics found."
+
+    output = [f"Found {len(metrics)} system metric entry/entries:\n"]
+
+    for i, entry in enumerate(metrics):
+        timestamp = entry.get("timestamp", "N/A")
+        output.append(f"\nEntry {i + 1} (Timestamp: {timestamp}):")
+        for key, value in entry.items():
+            if key != "timestamp":
+                output.append(f"  {key}: {value}")
+
+    return "\n".join(output)
+
+
+def format_system_metric_names(names: list[str]) -> str:
+    """Format system metric names in human-readable format."""
+    return format_list(names, "System Metrics")
+
+
+def format_snapshot(snapshot: dict[str, list[dict]]) -> str:
+    """Format a metrics snapshot in human-readable format."""
+    if not snapshot:
+        return "No metrics found in the specified range."
+
+    output = []
+    for metric_name, values in sorted(snapshot.items()):
+        output.append(f"\n{metric_name}:")
+        output.append("  Step | Timestamp | Value")
+        output.append("  " + "-" * 48)
+        for v in values:
+            step = v.get("step", "N/A")
+            ts = v.get("timestamp", "N/A")
+            val = v.get("value", "N/A")
+            output.append(f"  {step} | {ts} | {val}")
+
+    return "\n".join(output)
+
+
+def format_alerts(alerts: list[dict]) -> str:
+    """Format alerts in human-readable format."""
+    if not alerts:
+        return "No alerts found."
+
+    output = [f"Found {len(alerts)} alert(s):\n"]
+    output.append("Timestamp | Run | Level | Title | Text | Step")
+    output.append("-" * 80)
+
+    for a in alerts:
+        ts = a.get("timestamp", "N/A")
+        run = a.get("run", "N/A")
+        level = a.get("level", "N/A").upper()
+        title = a.get("title", "")
+        text = a.get("text", "") or ""
+        step = a.get("step", "N/A")
+        output.append(f"{ts} | {run} | {level} | {title} | {text} | {step}")
+
+    return "\n".join(output)
+
+
+def format_query_result(result: dict[str, Any]) -> str:
+    """Format SQL query results in human-readable format."""
+    columns = result.get("columns", [])
+    rows = result.get("rows", [])
+    row_count = result.get("row_count", 0)
+
+    if not columns:
+        return f"Query returned {row_count} row(s)."
+
+    rendered_rows = []
+    for row in rows:
+        rendered_rows.append(
+            [
+                "" if row.get(column) is None else str(row.get(column))
+                for column in columns
+            ]
+        )
+
+    widths = []
+    for idx, column in enumerate(columns):
+        cell_width = max(
+            (len(rendered_row[idx]) for rendered_row in rendered_rows), default=0
+        )
+        widths.append(max(len(column), cell_width))
+
+    header = " | ".join(
+        column.ljust(width) for column, width in zip(columns, widths, strict=False)
+    )
+    separator = "-+-".join("-" * width for width in widths)
+    output = [f"Query returned {row_count} row(s).", header, separator]
+
+    if not rendered_rows:
+        output.append("(no rows)")
+        return "\n".join(output)
+
+    for rendered_row in rendered_rows:
+        output.append(
+            " | ".join(
+                value.ljust(width)
+                for value, width in zip(rendered_row, widths, strict=False)
+            )
+        )
+
+    return "\n".join(output)
+
+
+def error_exit(message: str, code: int = 1) -> None:
+    """Print error message and exit."""
+    print(f"Error: {message}", file=sys.stderr)
+    sys.exit(code)

trackio/commit_scheduler.py

@@ -0,0 +1,310 @@
+# Originally copied from https://github.com/huggingface/huggingface_hub/blob/d0a948fc2a32ed6e557042a95ef3e4af97ec4a7c/src/huggingface_hub/_commit_scheduler.py
+
+import atexit
+import logging
+import time
+from concurrent.futures import Future
+from dataclasses import dataclass
+from pathlib import Path
+from threading import Lock, Thread
+from typing import Callable, Dict, List, Union
+
+from huggingface_hub.hf_api import (
+    DEFAULT_IGNORE_PATTERNS,
+    CommitInfo,
+    CommitOperationAdd,
+    HfApi,
+)
+from huggingface_hub.utils import filter_repo_objects
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class _FileToUpload:
+    """Temporary dataclass to store info about files to upload. Not meant to be used directly."""
+
+    local_path: Path
+    path_in_repo: str
+    size_limit: int
+    last_modified: float
+
+
+class CommitScheduler:
+    """
+    Scheduler to upload a local folder to the Hub at regular intervals (e.g. push to hub every 5 minutes).
+
+    The recommended way to use the scheduler is to use it as a context manager. This ensures that the scheduler is
+    properly stopped and the last commit is triggered when the script ends. The scheduler can also be stopped manually
+    with the `stop` method. Checkout the [upload guide](https://huggingface.co/docs/huggingface_hub/guides/upload#scheduled-uploads)
+    to learn more about how to use it.
+
+    Args:
+        repo_id (`str`):
+            The id of the repo to commit to.
+        folder_path (`str` or `Path`):
+            Path to the local folder to upload regularly.
+        every (`int` or `float`, *optional*):
+            The number of minutes between each commit. Defaults to 5 minutes.
+        path_in_repo (`str`, *optional*):
+            Relative path of the directory in the repo, for example: `"checkpoints/"`. Defaults to the root folder
+            of the repository.
+        repo_type (`str`, *optional*):
+            The type of the repo to commit to. Defaults to `model`.
+        revision (`str`, *optional*):
+            The revision of the repo to commit to. Defaults to `main`.
+        private (`bool`, *optional*):
+            Whether to make the repo private. If `None` (default), the repo will be public unless the organization's default is private. This value is ignored if the repo already exists.
+        token (`str`, *optional*):
+            The token to use to commit to the repo. Defaults to the token saved on the machine.
+        allow_patterns (`List[str]` or `str`, *optional*):
+            If provided, only files matching at least one pattern are uploaded.
+        ignore_patterns (`List[str]` or `str`, *optional*):
+            If provided, files matching any of the patterns are not uploaded.
+        squash_history (`bool`, *optional*):
+            Whether to squash the history of the repo after each commit. Defaults to `False`. Squashing commits is
+            useful to avoid degraded performances on the repo when it grows too large.
+        hf_api (`HfApi`, *optional*):
+            The [`HfApi`] client to use to commit to the Hub. Can be set with custom settings (user agent, token,...).
+        on_before_commit (`Callable[[], None]`, *optional*):
+            If specified, a function that will be called before the CommitScheduler lists files to create a commit.
+
+    Example:
+    ```py
+    >>> from pathlib import Path
+    >>> from huggingface_hub import CommitScheduler
+
+    # Scheduler uploads every 10 minutes
+    >>> csv_path = Path("watched_folder/data.csv")
+    >>> CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path=csv_path.parent, every=10)
+
+    >>> with csv_path.open("a") as f:
+    ...     f.write("first line")
+
+    # Some time later (...)
+    >>> with csv_path.open("a") as f:
+    ...     f.write("second line")
+    ```
+
+    Example using a context manager:
+    ```py
+    >>> from pathlib import Path
+    >>> from huggingface_hub import CommitScheduler
+
+    >>> with CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path="watched_folder", every=10) as scheduler:
+    ...     csv_path = Path("watched_folder/data.csv")
+    ...     with csv_path.open("a") as f:
+    ...         f.write("first line")
+    ...     (...)
+    ...     with csv_path.open("a") as f:
+    ...         f.write("second line")
+
+    # Scheduler is now stopped and last commit have been triggered
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        repo_id: str,
+        folder_path: Union[str, Path],
+        every: Union[int, float] = 5,
+        path_in_repo: str | None = None,
+        repo_type: str | None = None,
+        revision: str | None = None,
+        private: bool | None = None,
+        token: str | None = None,
+        allow_patterns: list[str] | str | None = None,
+        ignore_patterns: list[str] | str | None = None,
+        squash_history: bool = False,
+        hf_api: HfApi | None = None,
+        on_before_commit: Callable[[], None] | None = None,
+    ) -> None:
+        self.api = hf_api or HfApi(token=token)
+        self.on_before_commit = on_before_commit
+
+        # Folder
+        self.folder_path = Path(folder_path).expanduser().resolve()
+        self.path_in_repo = path_in_repo or ""
+        self.allow_patterns = allow_patterns
+
+        if ignore_patterns is None:
+            ignore_patterns = []
+        elif isinstance(ignore_patterns, str):
+            ignore_patterns = [ignore_patterns]
+        self.ignore_patterns = ignore_patterns + DEFAULT_IGNORE_PATTERNS
+
+        if self.folder_path.is_file():
+            raise ValueError(
+                f"'folder_path' must be a directory, not a file: '{self.folder_path}'."
+            )
+        self.folder_path.mkdir(parents=True, exist_ok=True)
+
+        # Repository
+        repo_url = self.api.create_repo(
+            repo_id=repo_id, private=private, repo_type=repo_type, exist_ok=True
+        )
+        self.repo_id = repo_url.repo_id
+        self.repo_type = repo_type
+        self.revision = revision
+        self.token = token
+
+        self.last_uploaded: Dict[Path, float] = {}
+        self.last_push_time: float | None = None
+
+        if not every > 0:
+            raise ValueError(f"'every' must be a positive integer, not '{every}'.")
+        self.lock = Lock()
+        self.every = every
+        self.squash_history = squash_history
+
+        logger.info(
+            f"Scheduled job to push '{self.folder_path}' to '{self.repo_id}' every {self.every} minutes."
+        )
+        self._scheduler_thread = Thread(target=self._run_scheduler, daemon=True)
+        self._scheduler_thread.start()
+        atexit.register(self._push_to_hub)
+
+        self.__stopped = False
+
+    def stop(self) -> None:
+        """Stop the scheduler.
+
+        A stopped scheduler cannot be restarted. Mostly for tests purposes.
+        """
+        self.__stopped = True
+
+    def __enter__(self) -> "CommitScheduler":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        # Upload last changes before exiting
+        self.trigger().result()
+        self.stop()
+        return
+
+    def _run_scheduler(self) -> None:
+        """Dumb thread waiting between each scheduled push to Hub."""
+        while True:
+            self.last_future = self.trigger()
+            time.sleep(self.every * 60)
+            if self.__stopped:
+                break
+
+    def trigger(self) -> Future:
+        """Trigger a `push_to_hub` and return a future.
+
+        This method is automatically called every `every` minutes. You can also call it manually to trigger a commit
+        immediately, without waiting for the next scheduled commit.
+        """
+        return self.api.run_as_future(self._push_to_hub)
+
+    def _push_to_hub(self) -> CommitInfo | None:
+        if self.__stopped:  # If stopped, already scheduled commits are ignored
+            return None
+
+        logger.info("(Background) scheduled commit triggered.")
+        try:
+            value = self.push_to_hub()
+            if self.squash_history:
+                logger.info("(Background) squashing repo history.")
+                self.api.super_squash_history(
+                    repo_id=self.repo_id, repo_type=self.repo_type, branch=self.revision
+                )
+            return value
+        except Exception as e:
+            logger.error(
+                f"Error while pushing to Hub: {e}"
+            )  # Depending on the setup, error might be silenced
+            raise
+
+    def push_to_hub(self) -> CommitInfo | None:
+        """
+        Push folder to the Hub and return the commit info.
+
+        <Tip warning={true}>
+
+        This method is not meant to be called directly. It is run in the background by the scheduler, respecting a
+        queue mechanism to avoid concurrent commits. Making a direct call to the method might lead to concurrency
+        issues.
+
+        </Tip>
+
+        The default behavior of `push_to_hub` is to assume an append-only folder. It lists all files in the folder and
+        uploads only changed files. If no changes are found, the method returns without committing anything. If you want
+        to change this behavior, you can inherit from [`CommitScheduler`] and override this method. This can be useful
+        for example to compress data together in a single file before committing. For more details and examples, check
+        out our [integration guide](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload#scheduled-uploads).
+        """
+        # Check files to upload (with lock)
+        with self.lock:
+            if self.on_before_commit is not None:
+                self.on_before_commit()
+
+            logger.debug("Listing files to upload for scheduled commit.")
+
+            # List files from folder (taken from `_prepare_upload_folder_additions`)
+            relpath_to_abspath = {
+                path.relative_to(self.folder_path).as_posix(): path
+                for path in sorted(
+                    self.folder_path.glob("**/*")
+                )  # sorted to be deterministic
+                if path.is_file()
+            }
+            prefix = f"{self.path_in_repo.strip('/')}/" if self.path_in_repo else ""
+
+            # Filter with pattern + filter out unchanged files + retrieve current file size
+            files_to_upload: List[_FileToUpload] = []
+            for relpath in filter_repo_objects(
+                relpath_to_abspath.keys(),
+                allow_patterns=self.allow_patterns,
+                ignore_patterns=self.ignore_patterns,
+            ):
+                local_path = relpath_to_abspath[relpath]
+                stat = local_path.stat()
+                if (
+                    self.last_uploaded.get(local_path) is None
+                    or self.last_uploaded[local_path] != stat.st_mtime
+                ):
+                    files_to_upload.append(
+                        _FileToUpload(
+                            local_path=local_path,
+                            path_in_repo=prefix + relpath,
+                            size_limit=stat.st_size,
+                            last_modified=stat.st_mtime,
+                        )
+                    )
+
+        # Return if nothing to upload
+        if len(files_to_upload) == 0:
+            logger.debug("Dropping schedule commit: no changed file to upload.")
+            return None
+
+        # Convert `_FileToUpload` as `CommitOperationAdd` (=> compute file shas + limit to file size)
+        logger.debug("Removing unchanged files since previous scheduled commit.")
+        add_operations = [
+            CommitOperationAdd(
+                # TODO: Cap the file to its current size, even if the user append data to it while a scheduled commit is happening
+                # (requires an upstream fix for XET-535: `hf_xet` should support `BinaryIO` for upload)
+                path_or_fileobj=file_to_upload.local_path,
+                path_in_repo=file_to_upload.path_in_repo,
+            )
+            for file_to_upload in files_to_upload
+        ]
+
+        # Upload files (append mode expected - no need for lock)
+        logger.debug("Uploading files for scheduled commit.")
+        commit_info = self.api.create_commit(
+            repo_id=self.repo_id,
+            repo_type=self.repo_type,
+            operations=add_operations,
+            commit_message="Scheduled Commit",
+            revision=self.revision,
+        )
+
+        for file in files_to_upload:
+            self.last_uploaded[file.local_path] = file.last_modified
+
+        self.last_push_time = time.time()
+
+        return commit_info

trackio/compression.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import gzip
+import io
+from typing import NoReturn
+
+from starlette.datastructures import Headers, MutableHeaders
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+try:
+    import brotli
+
+    HAS_BROTLI = True
+except ImportError:
+    brotli = None
+    HAS_BROTLI = False
+
+COMPRESSIBLE_CONTENT_TYPES = (
+    "application/json",
+    "application/javascript",
+    "application/manifest+json",
+    "application/xml",
+    "application/xhtml+xml",
+    "image/svg+xml",
+    "text/",
+)
+
+
+class CompressionMiddleware:
+    """Negotiates Brotli, then gzip, then identity based on Accept-Encoding.
+
+    Only text-like content types are compressed, so already-compressed media
+    (images, audio, video) and zero-copy file sends pass through untouched.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        minimum_size: int = 512,
+        gzip_level: int = 6,
+        brotli_quality: int = 5,
+    ) -> None:
+        self.app = app
+        self.minimum_size = minimum_size
+        self.gzip_level = gzip_level
+        self.brotli_quality = brotli_quality
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        accept_encoding = Headers(scope=scope).get("Accept-Encoding", "")
+        responder: _CompressionResponder
+        if HAS_BROTLI and "br" in accept_encoding:
+            responder = _BrotliResponder(
+                self.app, self.minimum_size, self.brotli_quality
+            )
+        elif "gzip" in accept_encoding:
+            responder = _GZipResponder(self.app, self.minimum_size, self.gzip_level)
+        else:
+            responder = _CompressionResponder(self.app, self.minimum_size)
+
+        await responder(scope, receive, send)
+
+
+class _CompressionResponder:
+    content_encoding: str = ""
+
+    def __init__(self, app: ASGIApp, minimum_size: int) -> None:
+        self.app = app
+        self.minimum_size = minimum_size
+        self.send: Send = _unattached_send
+        self.initial_message: Message = {}
+        self.started = False
+        self.passthrough = True
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        self.send = send
+        await self.app(scope, receive, self.send_with_compression)
+
+    async def send_with_compression(self, message: Message) -> None:
+        message_type = message["type"]
+        if message_type == "http.response.start":
+            self.initial_message = message
+            headers = Headers(raw=message["headers"])
+            content_type = headers.get("content-type", "")
+            already_encoded = "content-encoding" in headers
+            self.passthrough = already_encoded or not content_type.startswith(
+                COMPRESSIBLE_CONTENT_TYPES
+            )
+        elif message_type == "http.response.body" and self.passthrough:
+            if not self.started:
+                self.started = True
+                await self.send(self.initial_message)
+            await self.send(message)
+        elif message_type == "http.response.body" and not self.started:
+            self.started = True
+            body = message.get("body", b"")
+            more_body = message.get("more_body", False)
+            if len(body) < self.minimum_size and not more_body:
+                await self.send(self.initial_message)
+                await self.send(message)
+            else:
+                compressed = self.apply_compression(body, more_body=more_body)
+                headers = MutableHeaders(raw=self.initial_message["headers"])
+                headers.add_vary_header("Accept-Encoding")
+                if compressed != body:
+                    headers["Content-Encoding"] = self.content_encoding
+                    if more_body:
+                        del headers["Content-Length"]
+                    else:
+                        headers["Content-Length"] = str(len(compressed))
+                    message["body"] = compressed
+                await self.send(self.initial_message)
+                await self.send(message)
+        elif message_type == "http.response.body":
+            body = message.get("body", b"")
+            more_body = message.get("more_body", False)
+            message["body"] = self.apply_compression(body, more_body=more_body)
+            await self.send(message)
+        elif message_type == "http.response.pathsend":
+            await self.send(self.initial_message)
+            await self.send(message)
+
+    def apply_compression(self, body: bytes, *, more_body: bool) -> bytes:
+        return body
+
+
+class _GZipResponder(_CompressionResponder):
+    content_encoding = "gzip"
+
+    def __init__(self, app: ASGIApp, minimum_size: int, compresslevel: int) -> None:
+        super().__init__(app, minimum_size)
+        self.buffer = io.BytesIO()
+        self.file = gzip.GzipFile(
+            mode="wb", fileobj=self.buffer, compresslevel=compresslevel
+        )
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        with self.buffer, self.file:
+            await super().__call__(scope, receive, send)
+
+    def apply_compression(self, body: bytes, *, more_body: bool) -> bytes:
+        self.file.write(body)
+        if not more_body:
+            self.file.close()
+        data = self.buffer.getvalue()
+        self.buffer.seek(0)
+        self.buffer.truncate()
+        return data
+
+
+class _BrotliResponder(_CompressionResponder):
+    content_encoding = "br"
+
+    def __init__(self, app: ASGIApp, minimum_size: int, quality: int) -> None:
+        super().__init__(app, minimum_size)
+        self.compressor = brotli.Compressor(quality=quality)
+
+    def apply_compression(self, body: bytes, *, more_body: bool) -> bytes:
+        data = self.compressor.process(body)
+        if not more_body:
+            data += self.compressor.finish()
+        return data
+
+
+async def _unattached_send(message: Message) -> NoReturn:
+    raise RuntimeError("send awaitable not set")

trackio/context_vars.py

@@ -0,0 +1,21 @@
+import contextvars
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from trackio.run import Run
+
+current_run: contextvars.ContextVar["Run | None"] = contextvars.ContextVar(
+    "current_run", default=None
+)
+current_project: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_project", default=None
+)
+current_server: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_server", default=None
+)
+current_space_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_space_id", default=None
+)
+current_server_write_token: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_server_write_token", default=None
+)

trackio/cpu.py

@@ -0,0 +1,303 @@
+import importlib
+import threading
+import time
+import warnings
+from typing import TYPE_CHECKING, Any
+
+from trackio import context_vars
+
+if TYPE_CHECKING:
+    from trackio.run import Run
+
+psutil: Any = None
+PSUTIL_AVAILABLE = False
+_psutil_lock = threading.Lock()
+
+
+def _ensure_psutil():
+    global PSUTIL_AVAILABLE, psutil
+    if PSUTIL_AVAILABLE:
+        return psutil
+    with _psutil_lock:
+        if PSUTIL_AVAILABLE:
+            return psutil
+        try:
+            psutil = importlib.import_module("psutil")
+            PSUTIL_AVAILABLE = True
+            return psutil
+        except ImportError:
+            raise ImportError(
+                "psutil is required for CPU and RAM monitoring. "
+                "Install it with: pip install psutil"
+            )
+
+
+def cpu_available() -> bool:
+    """
+    Check if CPU and RAM monitoring is available.
+
+    Returns True if psutil is installed.
+    """
+    try:
+        _ensure_psutil()
+        return True
+    except ImportError:
+        return False
+    except Exception:
+        return False
+
+
+def collect_cpu_metrics(
+    prev_disk_counters: Any = None,
+    prev_net_counters: Any = None,
+    elapsed: float | None = None,
+    include_static: bool = True,
+) -> dict:
+    """
+    Collect CPU, RAM, disk, network, and sensor metrics using psutil.
+
+    Args:
+        prev_disk_counters: Previous disk I/O counters for computing read/write rates.
+            If None, only cumulative values are reported.
+        prev_net_counters: Previous network I/O counters for computing send/recv rates.
+            If None, only cumulative values are reported.
+        elapsed: Seconds since prev_disk_counters and prev_net_counters were captured.
+            If None or non-positive, cumulative values are reported instead of rates.
+        include_static: Whether to include mostly static metrics such as CPU
+            frequency and core counts.
+
+    Returns:
+        Dictionary of system metrics.
+    """
+    if not PSUTIL_AVAILABLE:
+        try:
+            _ensure_psutil()
+        except ImportError:
+            return {}
+
+    metrics = {}
+
+    try:
+        per_core = psutil.cpu_percent(interval=0.1, percpu=True)
+        for i, pct in enumerate(per_core):
+            metrics[f"cpu/{i}/utilization"] = pct
+        if per_core:
+            metrics["cpu/utilization"] = sum(per_core) / len(per_core)
+    except Exception:
+        pass
+
+    if include_static:
+        try:
+            cpu_freq = psutil.cpu_freq()
+            if cpu_freq:
+                metrics["cpu/frequency"] = cpu_freq.current
+                if cpu_freq.max > 0:
+                    metrics["cpu/frequency_max"] = cpu_freq.max
+        except Exception:
+            pass
+
+        try:
+            cpu_count_logical = psutil.cpu_count(logical=True)
+            if cpu_count_logical is not None:
+                metrics["cpu/count_logical"] = cpu_count_logical
+            cpu_count_physical = psutil.cpu_count(logical=False)
+            if cpu_count_physical is not None:
+                metrics["cpu/count_physical"] = cpu_count_physical
+        except Exception:
+            pass
+
+    try:
+        mem = psutil.virtual_memory()
+        metrics["memory/used"] = mem.used / (1024**3)
+        metrics["memory/total"] = mem.total / (1024**3)
+        metrics["memory/available"] = mem.available / (1024**3)
+        metrics["memory/percent"] = mem.percent
+    except Exception:
+        pass
+
+    try:
+        swap = psutil.swap_memory()
+        metrics["swap/used"] = swap.used / (1024**3)
+        metrics["swap/total"] = swap.total / (1024**3)
+        metrics["swap/percent"] = swap.percent
+    except Exception:
+        pass
+
+    try:
+        disk = psutil.disk_io_counters()
+        if disk is not None:
+            if prev_disk_counters is not None and elapsed and elapsed > 0:
+                metrics["disk/read_mb_per_sec"] = (
+                    (disk.read_bytes - prev_disk_counters.read_bytes)
+                    / elapsed
+                    / (1024**2)
+                )
+                metrics["disk/write_mb_per_sec"] = (
+                    (disk.write_bytes - prev_disk_counters.write_bytes)
+                    / elapsed
+                    / (1024**2)
+                )
+                metrics["disk/read_iops"] = (
+                    disk.read_count - prev_disk_counters.read_count
+                ) / elapsed
+                metrics["disk/write_iops"] = (
+                    disk.write_count - prev_disk_counters.write_count
+                ) / elapsed
+            else:
+                metrics["disk/read_bytes"] = disk.read_bytes
+                metrics["disk/write_bytes"] = disk.write_bytes
+    except Exception:
+        pass
+
+    try:
+        net = psutil.net_io_counters()
+        if net is not None:
+            if prev_net_counters is not None and elapsed and elapsed > 0:
+                metrics["network/sent_mb_per_sec"] = (
+                    (net.bytes_sent - prev_net_counters.bytes_sent)
+                    / elapsed
+                    / (1024**2)
+                )
+                metrics["network/recv_mb_per_sec"] = (
+                    (net.bytes_recv - prev_net_counters.bytes_recv)
+                    / elapsed
+                    / (1024**2)
+                )
+            else:
+                metrics["network/sent_bytes"] = net.bytes_sent
+                metrics["network/recv_bytes"] = net.bytes_recv
+    except Exception:
+        pass
+
+    try:
+        sensors = psutil.sensors_temperatures()
+        if sensors:
+            for chip_name, entries in sensors.items():
+                for i, entry in enumerate(entries):
+                    label = (
+                        entry.label.strip()
+                        if entry.label and entry.label.strip()
+                        else f"{chip_name}_{i}"
+                    )
+                    metrics[f"temp/{label}"] = entry.current
+    except Exception:
+        pass
+
+    try:
+        battery = psutil.sensors_battery()
+        if battery is not None:
+            metrics["battery/percent"] = battery.percent
+            metrics["battery/power_plugged"] = int(battery.power_plugged)
+    except Exception:
+        pass
+
+    return metrics
+
+
+class CpuMonitor:
+    def __init__(self, run: "Run", interval: float = 10.0):
+        self._run = run
+        self._interval = interval
+        self._stop_flag = threading.Event()
+        self._thread: "threading.Thread | None" = None
+        self._last_disk_counters: Any = None
+        self._last_net_counters: Any = None
+        self._last_time: float | None = None
+        self._include_static_next = True
+
+    def start(self):
+        if not PSUTIL_AVAILABLE:
+            try:
+                _ensure_psutil()
+            except ImportError:
+                warnings.warn(
+                    "auto_log_cpu=True but psutil is not installed. "
+                    "CPU and RAM logging disabled. Install with: pip install psutil"
+                )
+                return
+
+        self._thread = threading.Thread(target=self._monitor_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_flag.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+
+    def _monitor_loop(self):
+        try:
+            self._last_disk_counters = psutil.disk_io_counters()
+        except Exception:
+            pass
+        try:
+            self._last_net_counters = psutil.net_io_counters()
+        except Exception:
+            pass
+        self._last_time = time.monotonic()
+
+        while not self._stop_flag.is_set():
+            self._stop_flag.wait(timeout=self._interval)
+            if self._stop_flag.is_set():
+                break
+            try:
+                now = time.monotonic()
+                elapsed = now - self._last_time if self._last_time is not None else None
+                metrics = collect_cpu_metrics(
+                    prev_disk_counters=self._last_disk_counters,
+                    prev_net_counters=self._last_net_counters,
+                    elapsed=elapsed,
+                    include_static=self._include_static_next,
+                )
+                self._include_static_next = False
+                try:
+                    self._last_disk_counters = psutil.disk_io_counters()
+                except Exception:
+                    self._last_disk_counters = None
+                try:
+                    self._last_net_counters = psutil.net_io_counters()
+                except Exception:
+                    self._last_net_counters = None
+                self._last_time = now
+                if metrics:
+                    self._run.log_system(metrics)
+            except Exception:
+                pass
+
+
+def log_cpu(run: "Run | None" = None) -> dict:
+    """
+    Log CPU, RAM, disk, network, and sensor metrics to the current or specified run
+    as system metrics.
+
+    Args:
+        run: Optional Run instance. If None, uses current run from context.
+
+    Returns:
+        dict: The system metrics that were logged.
+
+    Example:
+        ```python
+        import trackio
+
+        run = trackio.init(project="my-project")
+        trackio.log({"loss": 0.5})
+        trackio.log_cpu()
+        ```
+    """
+    if run is None:
+        run = context_vars.current_run.get()
+        if run is None:
+            raise RuntimeError("Call trackio.init() before trackio.log_cpu().")
+
+    try:
+        _ensure_psutil()
+    except ImportError:
+        warnings.warn(
+            "trackio.log_cpu() requires psutil. Install it with: pip install trackio[cpu]"
+        )
+        return {}
+
+    metrics = collect_cpu_metrics()
+    if metrics:
+        run.log_system(metrics)
+    return metrics

trackio/deploy.py

@@ -0,0 +1,1313 @@
+import importlib.metadata
+import io
+import json as json_mod
+import os
+import tempfile
+import threading
+import time
+import warnings
+from collections import Counter
+from importlib.resources import files
+from pathlib import Path
+
+import httpx
+import huggingface_hub
+from gradio_client import handle_file
+from httpx import ReadTimeout
+from huggingface_hub import Volume
+from huggingface_hub.errors import (
+    BucketNotFoundError,
+    HfHubHTTPError,
+    RepositoryNotFoundError,
+)
+
+import trackio
+from trackio.bucket_storage import (
+    create_bucket_if_not_exists,
+    export_from_bucket_for_static,
+    upload_project_to_bucket,
+    upload_project_to_bucket_for_static,
+)
+from trackio.cas import PARTIAL_BLOB_GLOB
+from trackio.frontend_config import resolve_frontend_dir
+from trackio.pending_uploads import replay_pending_uploads
+from trackio.remote_client import RemoteClient
+from trackio.sqlite_storage import SQLiteStorage
+from trackio.utils import (
+    get_or_create_project_hash,
+    on_spaces,
+    preprocess_space_and_dataset_ids,
+    project_artifacts_dir,
+    project_media_dir,
+)
+
+SPACE_HOST_URL = "https://{user_name}-{space_name}.hf.space/"
+SPACE_URL = "https://huggingface.co/spaces/{space_id}"
+_BOLD_ORANGE = "\033[1m\033[38;5;208m"
+_RESET = "\033[0m"
+
+
+def raise_if_space_is_frozen_for_logging(space_id: str) -> None:
+    try:
+        info = huggingface_hub.HfApi().space_info(space_id)
+    except RepositoryNotFoundError:
+        return
+    if getattr(info, "sdk", None) == "static":
+        raise RuntimeError(
+            f"Cannot log to Hugging Face Space '{space_id}' because it has been frozen "
+            f"(it uses the static SDK: a read-only dashboard with no live Trackio server).\n\n"
+            f"Use a different space_id for training, or create a new Gradio Trackio Space. "
+            f"Freezing converts a live Gradio Space to static after a run; a frozen Space "
+            f'cannot accept new logs. See trackio.sync(..., sdk="static") in the Trackio docs.'
+        )
+
+
+def _readme_linked_hub_yaml(dataset_id: str | None) -> str:
+    if dataset_id is not None:
+        return f"datasets:\n - {dataset_id}\n"
+    return ""
+
+
+_CUSTOM_SPACE_FRONTEND_DIR = "trackio_custom_frontend"
+
+
+def _space_app_py(frontend_dir: str | None = None) -> str:
+    if frontend_dir is None:
+        return "import trackio\ntrackio.show()\n"
+    return f'import trackio\ntrackio.show(frontend_dir="{frontend_dir}")\n'
+
+
+def _upload_frontend_folder(
+    hf_api: huggingface_hub.HfApi,
+    *,
+    repo_id: str,
+    repo_type: str,
+    folder_path: str | Path,
+    path_in_repo: str | None = None,
+) -> None:
+    kwargs = {
+        "repo_id": repo_id,
+        "repo_type": repo_type,
+        "folder_path": str(folder_path),
+    }
+    if path_in_repo is not None:
+        kwargs["path_in_repo"] = path_in_repo
+    hf_api.upload_folder(**kwargs)
+
+
+def _retry_hf_write(op_name: str, fn, retries: int = 4, initial_delay: float = 1.5):
+    delay = initial_delay
+    for attempt in range(1, retries + 1):
+        try:
+            return fn()
+        except ReadTimeout:
+            if attempt == retries:
+                raise
+            print(
+                f"* {op_name} timed out (attempt {attempt}/{retries}). Retrying in {delay:.1f}s..."
+            )
+            time.sleep(delay)
+            delay = min(delay * 2, 12)
+        except HfHubHTTPError as e:
+            status = e.response.status_code if e.response is not None else None
+            if status is None or status < 500 or attempt == retries:
+                raise
+            print(
+                f"* {op_name} failed with HTTP {status} (attempt {attempt}/{retries}). Retrying in {delay:.1f}s..."
+            )
+            time.sleep(delay)
+            delay = min(delay * 2, 12)
+
+
+def _get_space_volumes(
+    space_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> list[Volume]:
+    """
+    Return mounted volumes for a Space.
+
+    `HfApi.get_space_runtime()` does not always populate `volumes`, even when the
+    mount exists. Fall back to `space_info().runtime.volumes`, which currently
+    carries the volume metadata for running Spaces.
+    """
+    hf_api = hf_api or huggingface_hub.HfApi()
+    runtime = hf_api.get_space_runtime(space_id)
+    if runtime.volumes:
+        return list(runtime.volumes)
+
+    info = hf_api.space_info(space_id)
+    if info.runtime and info.runtime.volumes:
+        return list(info.runtime.volumes)
+
+    return []
+
+
+def _get_space_bucket_at_data_mount(
+    space_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> str | None:
+    for volume in _get_space_volumes(space_id, hf_api=hf_api):
+        if volume.type == "bucket" and volume.mount_path == "/data":
+            return volume.source
+    return None
+
+
+def _get_existing_space_bucket(
+    space_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> str | None:
+    """Return the Trackio bucket for a Space, preferring the canonical /data mount."""
+    bucket_at_data = _get_space_bucket_at_data_mount(space_id, hf_api=hf_api)
+    if bucket_at_data is not None:
+        return bucket_at_data
+
+    for volume in _get_space_volumes(space_id, hf_api=hf_api):
+        if volume.type == "bucket":
+            return volume.source
+    return None
+
+
+def _get_existing_static_space_bucket(
+    space_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> str | None:
+    hf_api = hf_api or huggingface_hub.HfApi()
+    try:
+        config_path = hf_api.hf_hub_download(
+            repo_id=space_id,
+            repo_type="space",
+            filename="config.json",
+        )
+    except (FileNotFoundError, HfHubHTTPError, OSError, ValueError):
+        return None
+
+    try:
+        with open(config_path, encoding="utf-8") as config_file:
+            config = json_mod.load(config_file)
+    except (OSError, ValueError, TypeError):
+        return None
+
+    bucket_id = config.get("bucket_id")
+    if isinstance(bucket_id, str) and bucket_id:
+        return bucket_id
+    return None
+
+
+def _ensure_bucket_mounted_at_data(
+    space_id: str,
+    bucket_id: str,
+    hf_api: huggingface_hub.HfApi | None = None,
+) -> None:
+    hf_api = hf_api or huggingface_hub.HfApi()
+    existing = _get_space_volumes(space_id, hf_api=hf_api)
+    already_mounted = any(
+        v.type == "bucket" and v.source == bucket_id and v.mount_path == "/data"
+        for v in existing
+    )
+    if not already_mounted:
+        preserved = [
+            v
+            for v in existing
+            if not (
+                v.type == "bucket"
+                and (v.source == bucket_id or v.mount_path == "/data")
+            )
+        ]
+        hf_api.set_space_volumes(
+            space_id,
+            preserved + [Volume(type="bucket", source=bucket_id, mount_path="/data")],
+        )
+        print(f"* Attached bucket {bucket_id} at '/data'")
+
+    existing_variables = hf_api.get_space_variables(space_id)
+    current_trackio_dir = getattr(existing_variables.get("TRACKIO_DIR"), "value", None)
+    if current_trackio_dir != "/data/trackio":
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_DIR", "/data/trackio")
+    current_bucket_id = getattr(
+        existing_variables.get("TRACKIO_BUCKET_ID"), "value", None
+    )
+    if current_bucket_id != bucket_id:
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_BUCKET_ID", bucket_id)
+
+
+def _bucket_exists(bucket_id: str, hf_api: huggingface_hub.HfApi | None = None) -> bool:
+    hf_api = hf_api or huggingface_hub.HfApi()
+    try:
+        hf_api.bucket_info(bucket_id)
+        return True
+    except BucketNotFoundError:
+        return False
+
+
+def _find_available_bucket_id(
+    preferred_bucket_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> str:
+    hf_api = hf_api or huggingface_hub.HfApi()
+    if not _bucket_exists(preferred_bucket_id, hf_api):
+        return preferred_bucket_id
+
+    suffix = 2
+    while True:
+        candidate = f"{preferred_bucket_id}-{suffix}"
+        if not _bucket_exists(candidate, hf_api):
+            return candidate
+        suffix += 1
+
+
+def resolve_auto_bucket_id(
+    space_id: str,
+    preferred_bucket_id: str,
+    hf_api: huggingface_hub.HfApi | None = None,
+) -> str:
+    """
+    Resolve the bucket to use for an auto-generated bucket ID.
+
+    Rules:
+    - Existing Space with a bucket mounted at /data -> reuse that bucket.
+    - Existing static Space with a bucket_id in config.json -> reuse that bucket.
+    - Otherwise -> use the preferred auto bucket ID if free, or a suffixed variant.
+    """
+    hf_api = hf_api or huggingface_hub.HfApi()
+    try:
+        info = hf_api.space_info(space_id)
+    except RepositoryNotFoundError:
+        pass
+    else:
+        existing_bucket_id = _get_existing_space_bucket(space_id, hf_api=hf_api)
+        if existing_bucket_id is None and getattr(info, "sdk", None) == "static":
+            existing_bucket_id = _get_existing_static_space_bucket(
+                space_id, hf_api=hf_api
+            )
+        if existing_bucket_id is not None:
+            return existing_bucket_id
+
+    bucket_id = _find_available_bucket_id(preferred_bucket_id, hf_api)
+    if bucket_id != preferred_bucket_id:
+        print(
+            f"* Auto-generated bucket {preferred_bucket_id} already exists; "
+            f"using {bucket_id} instead"
+        )
+    return bucket_id
+
+
+def _get_source_install_dependencies() -> str:
+    """Get trackio dependencies from pyproject.toml for source installs."""
+    try:
+        import tomllib  # noqa: PLC0415
+    except ModuleNotFoundError:
+        import tomli as tomllib  # noqa: PLC0415
+
+    trackio_path = files("trackio")
+    pyproject_path = Path(trackio_path).parent / "pyproject.toml"
+    with open(pyproject_path, "rb") as f:
+        pyproject = tomllib.load(f)
+    deps = pyproject["project"]["dependencies"]
+    spaces_deps = (
+        pyproject["project"].get("optional-dependencies", {}).get("spaces", [])
+    )
+    mcp_deps = pyproject["project"].get("optional-dependencies", {}).get("mcp", [])
+    return "\n".join(deps + spaces_deps + mcp_deps)
+
+
+def _get_space_install_requirement() -> str:
+    return f"trackio[spaces,mcp]=={trackio.__version__}"
+
+
+def _is_trackio_installed_from_source() -> bool:
+    """Check if trackio is installed from source/editable install vs PyPI."""
+    try:
+        trackio_file = trackio.__file__
+        if "site-packages" not in trackio_file and "dist-packages" not in trackio_file:
+            return True
+
+        dist = importlib.metadata.distribution("trackio")
+        if dist.files:
+            files = list(dist.files)
+            has_pth = any(".pth" in str(f) for f in files)
+            if has_pth:
+                return True
+
+        return False
+    except (
+        AttributeError,
+        importlib.metadata.PackageNotFoundError,
+        importlib.metadata.MetadataError,
+        ValueError,
+        TypeError,
+    ):
+        return True
+
+
+def deploy_as_space(
+    space_id: str,
+    space_storage: huggingface_hub.SpaceStorage | None = None,
+    dataset_id: str | None = None,
+    bucket_id: str | None = None,
+    private: bool | None = None,
+    frontend_dir: str | Path | None = None,
+):
+    if on_spaces():  # in case a repo with this function is uploaded to spaces
+        return
+
+    if dataset_id is not None and bucket_id is not None:
+        raise ValueError(
+            "Cannot use bucket volume options together with dataset_id; use one persistence mode."
+        )
+
+    trackio_path = files("trackio")
+
+    hf_api = huggingface_hub.HfApi()
+
+    try:
+        huggingface_hub.create_repo(
+            space_id,
+            private=private,
+            space_sdk="gradio",
+            space_storage=space_storage,
+            repo_type="space",
+            exist_ok=True,
+        )
+    except HfHubHTTPError as e:
+        if e.response.status_code in [401, 403]:  # unauthorized or forbidden
+            print("Need 'write' access token to create a Spaces repo.")
+            huggingface_hub.login(add_to_git_credential=False)
+            huggingface_hub.create_repo(
+                space_id,
+                private=private,
+                space_sdk="gradio",
+                space_storage=space_storage,
+                repo_type="space",
+                exist_ok=True,
+            )
+        else:
+            raise ValueError(f"Failed to create Space: {e}")
+
+    # We can assume huggingface-hub is available; requirements.txt pins trackio.
+    # Make sure necessary dependencies are installed by creating a requirements.txt.
+    is_source_install = _is_trackio_installed_from_source()
+    resolved_frontend = resolve_frontend_dir(frontend_dir, announce=True)
+
+    if bucket_id is not None:
+        create_bucket_if_not_exists(bucket_id, private=private)
+
+    with open(Path(trackio_path, "README.md"), "r", encoding="utf-8") as f:
+        readme_content = f.read()
+        readme_content = readme_content.replace("sdk_version: {GRADIO_VERSION}\n", "")
+        readme_content = readme_content.replace("{APP_FILE}", "app.py")
+        readme_content = readme_content.replace(
+            "{LINKED_HUB_METADATA}", _readme_linked_hub_yaml(dataset_id)
+        )
+        readme_buffer = io.BytesIO(readme_content.encode("utf-8"))
+        hf_api.upload_file(
+            path_or_fileobj=readme_buffer,
+            path_in_repo="README.md",
+            repo_id=space_id,
+            repo_type="space",
+        )
+
+    if is_source_install:
+        requirements_content = _get_source_install_dependencies()
+    else:
+        requirements_content = _get_space_install_requirement()
+
+    requirements_buffer = io.BytesIO(requirements_content.encode("utf-8"))
+    hf_api.upload_file(
+        path_or_fileobj=requirements_buffer,
+        path_in_repo="requirements.txt",
+        repo_id=space_id,
+        repo_type="space",
+    )
+
+    huggingface_hub.utils.disable_progress_bars()
+
+    if is_source_install:
+        dist_index = (
+            Path(trackio.__file__).resolve().parent / "frontend" / "dist" / "index.html"
+        )
+        if not dist_index.is_file() and not resolved_frontend.is_custom:
+            raise ValueError(
+                "The Trackio frontend build is missing. From the repository root run "
+                "`cd trackio/frontend && npm ci && npm run build`, then deploy again."
+            )
+        hf_api.upload_folder(
+            repo_id=space_id,
+            repo_type="space",
+            folder_path=trackio_path,
+            path_in_repo="trackio",
+            ignore_patterns=[
+                "README.md",
+                "frontend/node_modules/**",
+                "frontend/src/**",
+                "frontend/.gitignore",
+                "frontend/package.json",
+                "frontend/package-lock.json",
+                "frontend/vite.config.js",
+                "frontend/svelte.config.js",
+                "**/__pycache__/**",
+                "*.pyc",
+            ],
+        )
+
+    if resolved_frontend.is_custom:
+        _upload_frontend_folder(
+            hf_api,
+            repo_id=space_id,
+            repo_type="space",
+            folder_path=resolved_frontend.path,
+            path_in_repo=_CUSTOM_SPACE_FRONTEND_DIR,
+        )
+
+    app_file_content = _space_app_py(
+        _CUSTOM_SPACE_FRONTEND_DIR if resolved_frontend.is_custom else None
+    )
+    app_file_buffer = io.BytesIO(app_file_content.encode("utf-8"))
+    hf_api.upload_file(
+        path_or_fileobj=app_file_buffer,
+        path_in_repo="app.py",
+        repo_id=space_id,
+        repo_type="space",
+    )
+
+    if hf_token := huggingface_hub.utils.get_token():
+        huggingface_hub.add_space_secret(space_id, "HF_TOKEN", hf_token)
+    if bucket_id is not None:
+        _ensure_bucket_mounted_at_data(space_id, bucket_id, hf_api)
+    elif dataset_id is not None:
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_DATASET_ID", dataset_id)
+    if logo_light_url := os.environ.get("TRACKIO_LOGO_LIGHT_URL"):
+        huggingface_hub.add_space_variable(
+            space_id, "TRACKIO_LOGO_LIGHT_URL", logo_light_url
+        )
+    if logo_dark_url := os.environ.get("TRACKIO_LOGO_DARK_URL"):
+        huggingface_hub.add_space_variable(
+            space_id, "TRACKIO_LOGO_DARK_URL", logo_dark_url
+        )
+    if plot_order := os.environ.get("TRACKIO_PLOT_ORDER"):
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_PLOT_ORDER", plot_order)
+    if theme := os.environ.get("TRACKIO_THEME"):
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_THEME", theme)
+    huggingface_hub.add_space_variable(space_id, "GRADIO_MCP_SERVER", "True")
+
+
+def create_space_if_not_exists(
+    space_id: str,
+    space_storage: huggingface_hub.SpaceStorage | None = None,
+    dataset_id: str | None = None,
+    bucket_id: str | None = None,
+    private: bool | None = None,
+    frontend_dir: str | Path | None = None,
+) -> bool:
+    """
+    Creates a new Hugging Face Space if it does not exist. Returns True if a
+    new Space was created, False if an existing Space was found.
+
+    Args:
+        space_id (`str`):
+            The ID of the Space to create.
+        space_storage ([`~huggingface_hub.SpaceStorage`], *optional*):
+            Choice of persistent storage tier for the Space.
+        dataset_id (`str`, *optional*):
+            Deprecated. Use `bucket_id` instead.
+        bucket_id (`str`, *optional*):
+            Full Hub bucket id (`namespace/name`) to attach via the Hub volumes API (platform mount).
+            Sets `TRACKIO_DIR` to the mount path.
+        private (`bool`, *optional*):
+            Whether to make the Space private. If `None` (default), the repo will be
+            public unless the organization's default is private. This value is ignored
+            if the repo already exists.
+    """
+    if "/" not in space_id:
+        raise ValueError(
+            f"Invalid space ID: {space_id}. Must be in the format: username/reponame or orgname/reponame."
+        )
+    if dataset_id is not None and "/" not in dataset_id:
+        raise ValueError(
+            f"Invalid dataset ID: {dataset_id}. Must be in the format: username/datasetname or orgname/datasetname."
+        )
+    if bucket_id is not None and "/" not in bucket_id:
+        raise ValueError(
+            f"Invalid bucket ID: {bucket_id}. Must be in the format: username/bucketname or orgname/bucketname."
+        )
+    try:
+        huggingface_hub.repo_info(space_id, repo_type="space")
+        print(
+            f"* Found existing space: {_BOLD_ORANGE}{SPACE_URL.format(space_id=space_id)}{_RESET}"
+        )
+        if bucket_id is not None:
+            create_bucket_if_not_exists(bucket_id, private=private)
+            _ensure_bucket_mounted_at_data(space_id, bucket_id)
+        elif dataset_id is not None:
+            huggingface_hub.add_space_variable(
+                space_id, "TRACKIO_DATASET_ID", dataset_id
+            )
+        resolved_frontend = resolve_frontend_dir(frontend_dir, announce=False)
+        if resolved_frontend.is_custom:
+            deploy_as_space(
+                space_id,
+                space_storage,
+                dataset_id,
+                bucket_id,
+                private,
+                frontend_dir=frontend_dir,
+            )
+        return False
+    except RepositoryNotFoundError:
+        pass
+    except HfHubHTTPError as e:
+        if e.response.status_code in [401, 403]:  # unauthorized or forbidden
+            print("Need 'write' access token to create a Spaces repo.")
+            huggingface_hub.login(add_to_git_credential=False)
+        else:
+            raise ValueError(f"Failed to create Space: {e}")
+
+    print(
+        f"* Creating new space: {_BOLD_ORANGE}{SPACE_URL.format(space_id=space_id)}{_RESET}"
+    )
+    deploy_as_space(
+        space_id,
+        space_storage,
+        dataset_id,
+        bucket_id,
+        private,
+        frontend_dir=frontend_dir,
+    )
+    threading.Thread(
+        target=_warn_if_space_build_fails, args=(space_id,), daemon=True
+    ).start()
+    return True
+
+
+def space_is_running(space_id: str) -> bool:
+    try:
+        info = huggingface_hub.HfApi().space_info(space_id, timeout=30)
+        return bool(info.runtime) and str(info.runtime.stage) == "RUNNING"
+    except Exception:
+        return False
+
+
+def _warn_if_space_build_fails(space_id: str, timeout: int = 600) -> None:
+    hf_api = huggingface_hub.HfApi()
+    failure_stages = frozenset(
+        ("NO_APP_FILE", "CONFIG_ERROR", "BUILD_ERROR", "RUNTIME_ERROR")
+    )
+    start = time.time()
+    while time.time() - start < timeout:
+        try:
+            info = hf_api.space_info(space_id, timeout=30)
+            if info.runtime:
+                stage = str(info.runtime.stage)
+                if stage in failure_stages:
+                    print(
+                        f"\n* WARNING: Space {space_id} failed to build (stage: {stage}). "
+                        f"Logs are being saved to the Bucket and will appear once the Space "
+                        f"is fixed; see the build logs at {SPACE_URL.format(space_id=space_id)}"
+                    )
+                    return
+                if stage == "RUNNING":
+                    return
+        except Exception:
+            pass
+        time.sleep(10)
+
+
+def _wait_until_space_running(space_id: str, timeout: int = 300) -> None:
+    hf_api = huggingface_hub.HfApi()
+    start = time.time()
+    delay = 2
+    request_timeout = 45.0
+    failure_stages = frozenset(
+        ("NO_APP_FILE", "CONFIG_ERROR", "BUILD_ERROR", "RUNTIME_ERROR")
+    )
+    while time.time() - start < timeout:
+        try:
+            info = hf_api.space_info(space_id, timeout=request_timeout)
+            if info.runtime:
+                stage = str(info.runtime.stage)
+                if stage in failure_stages:
+                    raise RuntimeError(
+                        f"Space {space_id} entered terminal stage {stage}. "
+                        "Fix README.md or app files; see build logs on the Hub."
+                    )
+                if stage == "RUNNING":
+                    return
+        except RuntimeError:
+            raise
+        except (huggingface_hub.utils.HfHubHTTPError, httpx.RequestError):
+            pass
+        time.sleep(delay)
+        delay = min(delay * 1.5, 15)
+    raise TimeoutError(
+        f"Space {space_id} did not reach RUNNING within {timeout}s. "
+        "Check status and build logs on the Hub."
+    )
+
+
+def wait_until_space_exists(
+    space_id: str,
+) -> None:
+    """
+    Blocks the current thread until the Space exists.
+
+    Args:
+        space_id (`str`):
+            The ID of the Space to wait for.
+
+    Raises:
+        `TimeoutError`: If waiting for the Space takes longer than expected.
+    """
+    hf_api = huggingface_hub.HfApi()
+    delay = 1
+    for _ in range(30):
+        try:
+            hf_api.space_info(space_id)
+            return
+        except (huggingface_hub.utils.HfHubHTTPError, httpx.RequestError):
+            time.sleep(delay)
+            delay = min(delay * 2, 60)
+    raise TimeoutError("Waiting for space to exist took longer than expected")
+
+
+def upload_db_to_space(project: str, space_id: str, force: bool = False) -> None:
+    """
+    Uploads the database of a local Trackio project to a Hugging Face Space.
+
+    This uses the Trackio remote client so newer Trackio Spaces can speak the direct
+    HTTP API while older Gradio-based Spaces still work through `gradio_client`.
+
+    Args:
+        project (`str`):
+            The name of the project to upload.
+        space_id (`str`):
+            The ID of the Space to upload to.
+        force (`bool`, *optional*, defaults to `False`):
+            If `True`, overwrites the existing database without prompting. If `False`,
+            prompts for confirmation.
+    """
+    db_path = SQLiteStorage.get_project_db_path(project)
+    client = RemoteClient(
+        space_id,
+        hf_token=huggingface_hub.utils.get_token(),
+        httpx_kwargs={"timeout": 90},
+    )
+
+    if not force:
+        try:
+            existing_projects = client.predict(api_name="/get_all_projects")
+            if project in existing_projects:
+                response = input(
+                    f"Database for project '{project}' already exists on Space '{space_id}'. "
+                    f"Overwrite it? (y/N): "
+                )
+                if response.lower() not in ["y", "yes"]:
+                    print("* Upload cancelled.")
+                    return
+        except Exception as e:
+            print(f"* Warning: Could not check if project exists on Space: {e}")
+            print("* Proceeding with upload...")
+
+    client.predict(
+        api_name="/upload_db_to_space",
+        project=project,
+        uploaded_db=handle_file(db_path),
+        hf_token=huggingface_hub.utils.get_token(),
+    )
+
+
+SYNC_BATCH_SIZE = 500
+
+
+def _replay_pending_uploads(
+    project: str,
+    client: "RemoteClient",
+    hf_token: str | None,
+) -> None:
+    """Replay queued `pending_uploads` rows for `project` via `client` — the
+    out-of-Run sync path (`trackio sync`); see `replay_pending_uploads` for the
+    per-kind routing and clearing semantics.
+    """
+    pending_uploads = SQLiteStorage.get_pending_uploads(project)
+    if not pending_uploads:
+        return
+
+    def _warn_missing(count: int, sample: str) -> None:
+        print(
+            f"  Warning: dropping {count} pending upload(s) whose local files "
+            f"no longer exist (e.g. {sample!r})."
+        )
+
+    replay_pending_uploads(
+        pending_uploads,
+        project,
+        predict=client.predict,
+        hf_token=hf_token,
+        warn_missing=_warn_missing,
+        verbose=True,
+    )
+
+
+def sync_incremental(
+    project: str,
+    space_id: str,
+    private: bool | None = None,
+    pending_only: bool = False,
+    frontend_dir: str | Path | None = None,
+) -> None:
+    """
+    Syncs a local Trackio project to a Space via the bulk_log API endpoints
+    instead of uploading the entire DB file. Supports incremental sync.
+
+    Args:
+        project: The name of the project to sync.
+        space_id: The HF Space ID to sync to.
+        private: Whether to make the Space private if creating.
+        pending_only: If True, only sync rows tagged with space_id (pending data).
+    """
+    print(
+        f"* Syncing project '{project}' to: {SPACE_URL.format(space_id=space_id)} (please wait...)"
+    )
+    create_space_if_not_exists(space_id, private=private, frontend_dir=frontend_dir)
+    wait_until_space_exists(space_id)
+    hf_token = huggingface_hub.utils.get_token()
+    expected_run_counts: Counter[str] = Counter()
+
+    client = RemoteClient(
+        space_id,
+        hf_token=hf_token,
+        httpx_kwargs={"timeout": 90},
+    )
+
+    if pending_only:
+        pending_logs = SQLiteStorage.get_pending_logs(project)
+        if pending_logs:
+            logs = pending_logs["logs"]
+            expected_run_counts.update(log["run"] for log in logs)
+            for i in range(0, len(logs), SYNC_BATCH_SIZE):
+                batch = logs[i : i + SYNC_BATCH_SIZE]
+                print(
+                    f"  Syncing metrics: {min(i + SYNC_BATCH_SIZE, len(logs))}/{len(logs)}..."
+                )
+                client.predict(api_name="/bulk_log", logs=batch, hf_token=hf_token)
+            SQLiteStorage.clear_pending_logs(project, pending_logs["ids"])
+
+        pending_sys = SQLiteStorage.get_pending_system_logs(project)
+        if pending_sys:
+            logs = pending_sys["logs"]
+            for i in range(0, len(logs), SYNC_BATCH_SIZE):
+                batch = logs[i : i + SYNC_BATCH_SIZE]
+                print(
+                    f"  Syncing system metrics: {min(i + SYNC_BATCH_SIZE, len(logs))}/{len(logs)}..."
+                )
+                client.predict(
+                    api_name="/bulk_log_system", logs=batch, hf_token=hf_token
+                )
+            SQLiteStorage.clear_pending_system_logs(project, pending_sys["ids"])
+
+        _replay_pending_uploads(project, client, hf_token)
+    else:
+        all_logs = SQLiteStorage.get_all_logs_for_sync(project)
+        if all_logs:
+            expected_run_counts.update(log["run"] for log in all_logs)
+            for i in range(0, len(all_logs), SYNC_BATCH_SIZE):
+                batch = all_logs[i : i + SYNC_BATCH_SIZE]
+                print(
+                    f"  Syncing metrics: {min(i + SYNC_BATCH_SIZE, len(all_logs))}/{len(all_logs)}..."
+                )
+                client.predict(api_name="/bulk_log", logs=batch, hf_token=hf_token)
+
+        all_sys_logs = SQLiteStorage.get_all_system_logs_for_sync(project)
+        if all_sys_logs:
+            for i in range(0, len(all_sys_logs), SYNC_BATCH_SIZE):
+                batch = all_sys_logs[i : i + SYNC_BATCH_SIZE]
+                print(
+                    f"  Syncing system metrics: {min(i + SYNC_BATCH_SIZE, len(all_sys_logs))}/{len(all_sys_logs)}..."
+                )
+                client.predict(
+                    api_name="/bulk_log_system", logs=batch, hf_token=hf_token
+                )
+
+    _wait_for_remote_sync(client, project, expected_run_counts)
+    SQLiteStorage.set_project_metadata(project, "space_id", space_id)
+    print(
+        f"* Synced successfully to space: {_BOLD_ORANGE}{SPACE_URL.format(space_id=space_id)}{_RESET}"
+    )
+
+
+def _build_remote_client_with_retry(
+    space_id: str,
+    timeout: int = 360,
+    verbose: bool = False,
+) -> RemoteClient:
+    deadline = time.time() + timeout
+    delay = 2
+    last_error: Exception | None = None
+    while time.time() < deadline:
+        try:
+            return RemoteClient(
+                space_id,
+                hf_token=huggingface_hub.utils.get_token(),
+                verbose=verbose,
+                httpx_kwargs={"timeout": 90},
+            )
+        except (ValueError, ConnectionError) as e:
+            last_error = e
+            time.sleep(delay)
+            delay = min(delay * 1.5, 15)
+    raise ConnectionError(
+        f"Could not connect to Space '{space_id}' within {timeout}s: {last_error}"
+    )
+
+
+def _wait_for_remote_sync(
+    client: RemoteClient,
+    project: str,
+    expected_run_counts: Counter[str],
+    timeout: int = 180,
+) -> None:
+    if not expected_run_counts:
+        return
+
+    deadline = time.time() + timeout
+    delay = 2
+    last_error: Exception | None = None
+    pending = dict(expected_run_counts)
+
+    while time.time() < deadline and pending:
+        completed = []
+        for run_name, expected_num_logs in pending.items():
+            try:
+                summary = client.predict(
+                    project=project, run=run_name, api_name="/get_run_summary"
+                )
+                if summary.get("num_logs") == expected_num_logs:
+                    completed.append(run_name)
+            except Exception as e:
+                last_error = e
+        for run_name in completed:
+            pending.pop(run_name, None)
+        if pending:
+            time.sleep(delay)
+            delay = min(delay * 1.5, 15)
+
+    if pending:
+        raise TimeoutError(
+            f"Remote sync for project '{project}' did not become visible for runs "
+            f"{sorted(pending.items())} within {timeout}s. "
+            f"Last error: {last_error!r}"
+        )
+
+
+def upload_dataset_for_static(
+    project: str,
+    dataset_id: str,
+    private: bool | None = None,
+) -> None:
+    hf_api = huggingface_hub.HfApi()
+
+    try:
+        huggingface_hub.create_repo(
+            dataset_id,
+            private=private,
+            repo_type="dataset",
+            exist_ok=True,
+        )
+    except HfHubHTTPError as e:
+        if e.response.status_code in [401, 403]:
+            print("Need 'write' access token to create a Dataset repo.")
+            huggingface_hub.login(add_to_git_credential=False)
+            huggingface_hub.create_repo(
+                dataset_id,
+                private=private,
+                repo_type="dataset",
+                exist_ok=True,
+            )
+        else:
+            raise ValueError(f"Failed to create Dataset: {e}")
+
+    def _upload_folder(folder: Path, path_in_repo: str, ignore_patterns=None) -> None:
+        if not folder.exists():
+            return
+        _retry_hf_write(
+            f"Dataset {path_in_repo} upload",
+            lambda: hf_api.upload_folder(
+                repo_id=dataset_id,
+                repo_type="dataset",
+                folder_path=str(folder),
+                path_in_repo=path_in_repo,
+                ignore_patterns=ignore_patterns,
+            ),
+        )
+
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        output_dir = Path(tmp_dir)
+        SQLiteStorage.export_for_static_space(project, output_dir)
+
+        _upload_folder(project_media_dir(project), "media")
+        _upload_folder(project_artifacts_dir(project), "artifacts", [PARTIAL_BLOB_GLOB])
+
+        _retry_hf_write(
+            "Dataset upload",
+            lambda: hf_api.upload_folder(
+                repo_id=dataset_id,
+                repo_type="dataset",
+                folder_path=str(output_dir),
+            ),
+        )
+
+    print(f"* Dataset uploaded: https://huggingface.co/datasets/{dataset_id}")
+
+
+def deploy_as_static_space(
+    space_id: str,
+    dataset_id: str | None,
+    project: str,
+    bucket_id: str | None = None,
+    private: bool | None = None,
+    hf_token: str | None = None,
+    frontend_dir: str | Path | None = None,
+) -> None:
+    if on_spaces():
+        return
+
+    if private is True:
+        raise ValueError(
+            "private=True is not supported for static Trackio Spaces. Static Spaces "
+            "run entirely in the browser, so their snapshot data must be public. "
+            "Use sdk='gradio' for a private dashboard."
+        )
+    hf_api = huggingface_hub.HfApi()
+
+    try:
+        huggingface_hub.create_repo(
+            space_id,
+            private=False,
+            space_sdk="static",
+            repo_type="space",
+            exist_ok=True,
+        )
+    except HfHubHTTPError as e:
+        if e.response.status_code in [401, 403]:
+            print("Need 'write' access token to create a Spaces repo.")
+            huggingface_hub.login(add_to_git_credential=False)
+            huggingface_hub.create_repo(
+                space_id,
+                private=False,
+                space_sdk="static",
+                repo_type="space",
+                exist_ok=True,
+            )
+        else:
+            raise ValueError(f"Failed to create Space: {e}")
+
+    linked = _readme_linked_hub_yaml(dataset_id)
+    readme_content = (
+        f"---\nemoji: 🎯\nsdk: static\npinned: false\ntags:\n - trackio\n{linked}---\n"
+    )
+    _retry_hf_write(
+        "Static Space README upload",
+        lambda: hf_api.upload_file(
+            path_or_fileobj=io.BytesIO(readme_content.encode("utf-8")),
+            path_in_repo="README.md",
+            repo_id=space_id,
+            repo_type="space",
+        ),
+    )
+
+    resolved_frontend = resolve_frontend_dir(frontend_dir, announce=True)
+
+    _retry_hf_write(
+        "Static Space frontend upload",
+        lambda: hf_api.upload_folder(
+            repo_id=space_id,
+            repo_type="space",
+            folder_path=str(resolved_frontend.path),
+        ),
+    )
+
+    config = {
+        "mode": "static",
+        "project": project,
+        "private": bool(private),
+    }
+    if bucket_id is not None:
+        config["bucket_id"] = bucket_id
+    if dataset_id is not None:
+        config["dataset_id"] = dataset_id
+    if hf_token is not None:
+        warnings.warn(
+            "`hf_token` is ignored by deploy_as_static_space() for static Space "
+            "deployment and will be removed in a future release.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+    _retry_hf_write(
+        "Static Space config upload",
+        lambda: hf_api.upload_file(
+            path_or_fileobj=io.BytesIO(json_mod.dumps(config).encode("utf-8")),
+            path_in_repo="config.json",
+            repo_id=space_id,
+            repo_type="space",
+        ),
+    )
+
+    assets_dir = Path(trackio.__file__).resolve().parent / "assets"
+    if assets_dir.is_dir():
+        _retry_hf_write(
+            "Static Space assets upload",
+            lambda: hf_api.upload_folder(
+                repo_id=space_id,
+                repo_type="space",
+                folder_path=str(assets_dir),
+                path_in_repo="static/trackio",
+            ),
+        )
+
+    print(
+        f"* Static Space deployed: {_BOLD_ORANGE}{SPACE_URL.format(space_id=space_id)}{_RESET}"
+    )
+
+
+def sync(
+    project: str,
+    space_id: str | None = None,
+    private: bool | None = None,
+    force: bool = False,
+    run_in_background: bool = False,
+    sdk: str = "gradio",
+    dataset_id: str | None = None,
+    bucket_id: str | None = None,
+    frontend_dir: str | Path | None = None,
+) -> str:
+    """
+    Syncs a local Trackio project's database to a Hugging Face Space.
+    If the Space does not exist, it will be created. Local data is never deleted.
+
+    **Freezing:** Passing ``sdk="static"`` deploys a static Space backed by an HF Bucket
+    (read-only dashboard, no Gradio server). You can sync the same project again later to
+    refresh that static Space. If you want a one-time snapshot of an existing Gradio Space,
+    use ``freeze()`` instead.
+
+    Args:
+        project (`str`): The name of the project to upload.
+        space_id (`str`, *optional*): The ID of the Space to upload to (e.g., `"username/space_id"`).
+            If not provided, checks project metadata first, then generates a random space_id.
+        private (`bool`, *optional*):
+            Whether to make the Space private. If None (default), the repo will be
+            public unless the organization's default is private. This value is ignored
+            if the repo already exists. Not supported with ``sdk="static"`` because
+            static Trackio dashboards read snapshot data directly from the browser.
+        force (`bool`, *optional*, defaults to `False`):
+            If `True`, overwrite the existing database without prompting for confirmation.
+            If `False`, prompt the user before overwriting an existing database.
+        run_in_background (`bool`, *optional*, defaults to `False`):
+            If `True`, the Space creation and database upload will be run in a background thread.
+            If `False`, all the steps will be run synchronously.
+        sdk (`str`, *optional*, defaults to `"gradio"`):
+            The type of Space to deploy. `"gradio"` deploys a Gradio Space with a live
+            server. `"static"` freezes the Space: deploys a static Space that reads from an HF Bucket
+            (no server needed).
+        dataset_id (`str`, *optional*):
+            Deprecated. Use `bucket_id` instead.
+        bucket_id (`str`, *optional*):
+            The ID of the HF Bucket to sync to. By default, a bucket is auto-generated
+            from the space_id.
+    Returns:
+        `str`: The Space ID of the synced project.
+    """
+    if sdk not in ("gradio", "static"):
+        raise ValueError(f"sdk must be 'gradio' or 'static', got '{sdk}'")
+    if sdk == "static" and private is True:
+        raise ValueError(
+            "private=True is not supported for static Trackio Spaces. Static Spaces "
+            "run entirely in the browser, so their snapshot data must be public. "
+            "Use sdk='gradio' for a private dashboard."
+        )
+    bucket_id_was_explicit = bucket_id is not None
+
+    if space_id is None:
+        space_id = SQLiteStorage.get_space_id(project)
+    if space_id is None:
+        space_id = f"{project}-{get_or_create_project_hash(project)}"
+    space_id, dataset_id, bucket_id = preprocess_space_and_dataset_ids(
+        space_id, dataset_id, bucket_id
+    )
+    if dataset_id is None and bucket_id is not None and not bucket_id_was_explicit:
+        bucket_id = resolve_auto_bucket_id(space_id, bucket_id)
+
+    def _do_sync():
+        try:
+            info = huggingface_hub.HfApi().space_info(space_id)
+            existing_sdk = info.sdk
+            if existing_sdk and existing_sdk != sdk:
+                raise ValueError(
+                    f"Space '{space_id}' is a '{existing_sdk}' Space but sdk='{sdk}' was requested. "
+                    f"The sdk must match the existing Space type."
+                )
+        except RepositoryNotFoundError:
+            pass
+
+        if sdk == "static":
+            if dataset_id is not None:
+                upload_dataset_for_static(project, dataset_id, private=False)
+                deploy_as_static_space(
+                    space_id,
+                    dataset_id,
+                    project,
+                    private=False,
+                    frontend_dir=frontend_dir,
+                )
+            elif bucket_id is not None:
+                create_bucket_if_not_exists(bucket_id, private=False)
+                upload_project_to_bucket_for_static(project, bucket_id)
+                print(
+                    f"* Project data uploaded to bucket: https://huggingface.co/buckets/{bucket_id}"
+                )
+                deploy_as_static_space(
+                    space_id,
+                    None,
+                    project,
+                    bucket_id=bucket_id,
+                    private=False,
+                    frontend_dir=frontend_dir,
+                )
+        else:
+            if bucket_id is not None:
+                create_bucket_if_not_exists(bucket_id, private=private)
+                upload_project_to_bucket(project, bucket_id)
+                print(
+                    f"* Project data uploaded to bucket: https://huggingface.co/buckets/{bucket_id}"
+                )
+                create_space_if_not_exists(
+                    space_id,
+                    bucket_id=bucket_id,
+                    private=private,
+                    frontend_dir=frontend_dir,
+                )
+                _wait_until_space_running(space_id)
+                _wait_for_remote_sync(
+                    _build_remote_client_with_retry(space_id),
+                    project,
+                    Counter(
+                        log["run"]
+                        for log in SQLiteStorage.get_all_logs_for_sync(project)
+                    ),
+                )
+            else:
+                sync_incremental(
+                    project,
+                    space_id,
+                    private=private,
+                    pending_only=False,
+                    frontend_dir=frontend_dir,
+                )
+        SQLiteStorage.set_project_metadata(project, "space_id", space_id)
+
+    if run_in_background:
+        threading.Thread(target=_do_sync).start()
+    else:
+        _do_sync()
+    return space_id
+
+
+def _get_source_bucket(space_id: str) -> str:
+    bucket_id = _get_existing_space_bucket(space_id)
+    if bucket_id is not None:
+        _ensure_bucket_mounted_at_data(space_id, bucket_id)
+        return bucket_id
+    raise ValueError(
+        f"Space '{space_id}' has no bucket mounted at '/data'. "
+        f"freeze() requires the source Space to use bucket storage."
+    )
+
+
+def freeze(
+    space_id: str,
+    project: str,
+    new_space_id: str | None = None,
+    private: bool | None = None,
+    bucket_id: str | None = None,
+    frontend_dir: str | Path | None = None,
+) -> str:
+    """
+    Creates a new static Hugging Face Space containing a read-only snapshot of
+    the data for the specified project from the source Gradio Space. The data is
+    read from the bucket attached to the source Space at freeze time. The original
+    Space is not modified, and the new static Space does not automatically reflect
+    metrics uploaded to the original Gradio Space after the freeze completes.
+
+    Args:
+        space_id (`str`):
+            The ID of the source Gradio Space (e.g., `"username/my-space"` or a
+            short repo name with the logged-in namespace inferred, like `init()`).
+            Must be a Gradio Space with a bucket mounted at `/data`.
+        project (`str`):
+            The name of the project whose data to include in the frozen Space.
+        new_space_id (`str`, *optional*):
+            The ID for the new static Space. If not provided, defaults to
+            `"{space_id}_static"`.
+        private (`bool`, *optional*):
+            Not supported. Frozen static dashboards read snapshot data directly
+            from the browser, so the destination snapshot must be public.
+        bucket_id (`str`, *optional*):
+            The ID of the HF Bucket for the new static Space's data storage.
+            If not provided, one is auto-generated from the new Space ID.
+
+    Returns:
+        `str`: The Space ID of the newly created static Space.
+    """
+    if private is True:
+        raise ValueError(
+            "private=True is not supported for frozen static Trackio Spaces. Static "
+            "Spaces run entirely in the browser, so their snapshot data must be "
+            "public. Use a Gradio Space if the frozen dashboard must stay private."
+        )
+    space_id, _, _ = preprocess_space_and_dataset_ids(space_id, None, None)
+
+    try:
+        info = huggingface_hub.HfApi().space_info(space_id)
+        if info.sdk != "gradio":
+            raise ValueError(
+                f"Space '{space_id}' is not a Gradio Space (sdk='{info.sdk}'). "
+                f"freeze() requires a Gradio Space as the source."
+            )
+    except RepositoryNotFoundError:
+        raise ValueError(
+            f"Space '{space_id}' not found. Provide an existing Gradio Space ID."
+        )
+
+    source_bucket_id = _get_source_bucket(space_id)
+    print(f"* Reading project data from bucket: {source_bucket_id}")
+
+    bucket_id_was_explicit = bucket_id is not None
+
+    if new_space_id is None:
+        new_space_id = f"{space_id}_static"
+    new_space_id, _dataset_id, bucket_id = preprocess_space_and_dataset_ids(
+        new_space_id, None, bucket_id
+    )
+    if bucket_id is not None and not bucket_id_was_explicit:
+        bucket_id = resolve_auto_bucket_id(new_space_id, bucket_id)
+
+    hf_api = huggingface_hub.HfApi()
+    try:
+        dest_info = hf_api.space_info(new_space_id)
+        tags = dest_info.tags or []
+        if dest_info.sdk != "static" or "trackio" not in tags:
+            raise ValueError(
+                f"Space '{new_space_id}' already exists and is not a Trackio static Space "
+                f"(sdk='{dest_info.sdk}', tags={tags}). Choose a different new_space_id "
+                f"or delete the existing Space first."
+            )
+    except RepositoryNotFoundError:
+        pass
+
+    create_bucket_if_not_exists(bucket_id, private=False)
+    export_from_bucket_for_static(source_bucket_id, bucket_id, project)
+    print(
+        f"* Project data uploaded to bucket: https://huggingface.co/buckets/{bucket_id}"
+    )
+    deploy_as_static_space(
+        new_space_id,
+        None,
+        project,
+        bucket_id=bucket_id,
+        private=False,
+        frontend_dir=frontend_dir,
+    )
+    return new_space_id

trackio/dummy_commit_scheduler.py

@@ -0,0 +1,19 @@
+from concurrent.futures import Future
+
+
+class DummyCommitSchedulerLock:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, exception_type, exception_value, exception_traceback):
+        pass
+
+
+class DummyCommitScheduler:
+    def __init__(self):
+        self.lock = DummyCommitSchedulerLock()
+
+    def trigger(self) -> Future:
+        fut: Future = Future()
+        fut.set_result(None)
+        return fut

trackio/exceptions.py

@@ -0,0 +1,2 @@
+class TrackioAPIError(Exception):
+    pass

trackio/fragments.py

@@ -0,0 +1,368 @@
+"""Append-only JSONL fragments used as a durable fallback for metric logging.
+
+Fragments are immutable JSONL files, one writer (process) per subdirectory, so
+concurrent training processes never contend on a shared file. They are written
+either to a Hugging Face Bucket inbox (when a Space is unreachable) or to a
+local inbox directory (when SQLite is unsafe, e.g. on network filesystems), and
+are later imported into the project SQLite database by the process that owns it
+(the Space or the dashboard server). Records carry the same ``log_id``/
+``alert_id`` UUIDs as the HTTP logging endpoints, and imports use
+``INSERT OR IGNORE``, so importing a fragment is idempotent: fragments are
+deleted only after a successful import, and re-importing after a crash is
+harmless.
+"""
+
+import tempfile
+import threading
+import uuid
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import huggingface_hub
+import orjson
+
+from trackio import utils
+from trackio.typehints import AlertEntry, LogEntry, SystemLogEntry
+
+FRAGMENT_VERSION = 1
+INBOX_DIR_NAME = "inbox"
+BUCKET_INBOX_PREFIX = "trackio/inbox"
+BUCKET_MEDIA_PREFIX = "trackio/media"
+
+METRIC_KIND = "metric"
+SYSTEM_METRIC_KIND = "system_metric"
+ALERT_KIND = "alert"
+KINDS = {METRIC_KIND, SYSTEM_METRIC_KIND, ALERT_KIND}
+
+
+def local_inbox_dir() -> Path:
+    return utils.TRACKIO_DIR / INBOX_DIR_NAME
+
+
+def metric_record(entry: LogEntry | dict) -> dict:
+    return {
+        "v": FRAGMENT_VERSION,
+        "kind": METRIC_KIND,
+        "project": entry["project"],
+        "run": entry["run"],
+        "run_id": entry.get("run_id"),
+        "metrics": utils.serialize_values(entry.get("metrics") or {}),
+        "step": entry.get("step"),
+        "timestamp": entry.get("timestamp"),
+        "config": utils.serialize_values(entry.get("config"))
+        if entry.get("config")
+        else None,
+        "log_id": entry.get("log_id"),
+    }
+
+
+def system_metric_record(entry: SystemLogEntry | dict) -> dict:
+    return {
+        "v": FRAGMENT_VERSION,
+        "kind": SYSTEM_METRIC_KIND,
+        "project": entry["project"],
+        "run": entry["run"],
+        "run_id": entry.get("run_id"),
+        "metrics": utils.serialize_values(entry.get("metrics") or {}),
+        "timestamp": entry.get("timestamp"),
+        "log_id": entry.get("log_id"),
+    }
+
+
+def alert_record(entry: AlertEntry | dict) -> dict:
+    return {
+        "v": FRAGMENT_VERSION,
+        "kind": ALERT_KIND,
+        "project": entry["project"],
+        "run": entry["run"],
+        "run_id": entry.get("run_id"),
+        "title": entry["title"],
+        "text": entry.get("text"),
+        "level": entry.get("level"),
+        "step": entry.get("step"),
+        "timestamp": entry.get("timestamp"),
+        "alert_id": entry.get("alert_id"),
+    }
+
+
+def bucket_media_path(
+    project: str,
+    run: str | None,
+    step: int | None,
+    relative_path: str | None,
+    filename: str,
+) -> str:
+    parts = [BUCKET_MEDIA_PREFIX, utils.canonical_project_name(project)]
+    if run:
+        parts.append(run)
+        if step is not None:
+            parts.append(str(step))
+    else:
+        parts.append("files")
+        if relative_path:
+            parts.append(str(relative_path))
+    parts.append(filename)
+    return "/".join(parts)
+
+
+class FragmentWriter:
+    """Writes immutable JSONL fragments for a single writer (process)."""
+
+    def __init__(self, writer_id: str | None = None):
+        self.writer_id = writer_id or uuid.uuid4().hex[:16]
+        self._seq = 0
+        self._lock = threading.Lock()
+
+    def _next_fragment_name(self) -> str:
+        with self._lock:
+            name = f"{self._seq:08d}.jsonl"
+            self._seq += 1
+        return name
+
+    @staticmethod
+    def serialize_records(records: list[dict]) -> bytes:
+        return b"".join(orjson.dumps(record) + b"\n" for record in records)
+
+    def write_local(
+        self, records: list[dict], inbox_dir: Path | None = None
+    ) -> Path | None:
+        if not records:
+            return None
+        inbox = inbox_dir or local_inbox_dir()
+        writer_dir = inbox / self.writer_id
+        fragment_path = writer_dir / self._next_fragment_name()
+        data = self.serialize_records(records)
+        for attempt in range(3):
+            writer_dir.mkdir(parents=True, exist_ok=True)
+            try:
+                with tempfile.NamedTemporaryFile(
+                    mode="wb", dir=writer_dir, suffix=".tmp", delete=False
+                ) as tmp:
+                    tmp.write(data)
+                    tmp_path = Path(tmp.name)
+                tmp_path.replace(fragment_path)
+                return fragment_path
+            except FileNotFoundError:
+                if attempt == 2 or writer_dir.exists():
+                    raise
+
+    def write_to_bucket(self, records: list[dict], bucket_id: str) -> str | None:
+        if not records:
+            return None
+        remote_path = (
+            f"{BUCKET_INBOX_PREFIX}/{self.writer_id}/{self._next_fragment_name()}"
+        )
+        huggingface_hub.batch_bucket_files(
+            bucket_id,
+            add=[(self.serialize_records(records), remote_path)],
+            token=huggingface_hub.utils.get_token(),
+        )
+        return remote_path
+
+
+def parse_fragment_bytes(data: bytes) -> list[dict]:
+    records = []
+    for line in data.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            record = orjson.loads(line)
+        except orjson.JSONDecodeError:
+            continue
+        if isinstance(record, dict) and record.get("kind") in KINDS:
+            records.append(record)
+    return records
+
+
+def _group_by_run(records: list[dict]) -> dict[tuple, list[dict]]:
+    grouped: dict[tuple, list[dict]] = {}
+    for record in records:
+        key = (record.get("project"), record.get("run"), record.get("run_id"))
+        grouped.setdefault(key, []).append(record)
+    return grouped
+
+
+def import_records(records: list[dict]) -> int:
+    from trackio.sqlite_storage import SQLiteStorage  # noqa: PLC0415
+
+    metric_records = [r for r in records if r.get("kind") == METRIC_KIND]
+    system_records = [r for r in records if r.get("kind") == SYSTEM_METRIC_KIND]
+    alert_records = [r for r in records if r.get("kind") == ALERT_KIND]
+    imported = 0
+
+    for (project, run, run_id), group in _group_by_run(metric_records).items():
+        if not project or not run:
+            continue
+        config = next((r["config"] for r in group if r.get("config")), None)
+        has_timestamps = all(r.get("timestamp") for r in group)
+        SQLiteStorage.bulk_log(
+            project=project,
+            run=run,
+            run_id=run_id,
+            metrics_list=[r.get("metrics") or {} for r in group],
+            steps=[r.get("step") for r in group],
+            timestamps=[r["timestamp"] for r in group] if has_timestamps else None,
+            config=config,
+            log_ids=[r.get("log_id") for r in group],
+        )
+        imported += len(group)
+
+    for (project, run, run_id), group in _group_by_run(system_records).items():
+        if not project or not run:
+            continue
+        has_timestamps = all(r.get("timestamp") for r in group)
+        SQLiteStorage.bulk_log_system(
+            project=project,
+            run=run,
+            run_id=run_id,
+            metrics_list=[r.get("metrics") or {} for r in group],
+            timestamps=[r["timestamp"] for r in group] if has_timestamps else None,
+            log_ids=[r.get("log_id") for r in group],
+        )
+        imported += len(group)
+
+    for (project, run, run_id), group in _group_by_run(alert_records).items():
+        if not project or not run:
+            continue
+        has_timestamps = all(r.get("timestamp") for r in group)
+        SQLiteStorage.bulk_alert(
+            project=project,
+            run=run,
+            run_id=run_id,
+            titles=[r.get("title") or "" for r in group],
+            texts=[r.get("text") for r in group],
+            levels=[r.get("level") or "WARN" for r in group],
+            steps=[r.get("step") for r in group],
+            timestamps=[r["timestamp"] for r in group] if has_timestamps else None,
+            alert_ids=[r.get("alert_id") for r in group],
+        )
+        imported += len(group)
+
+    return imported
+
+
+def import_inbox_dir(inbox_dir: Path | None = None) -> int:
+    inbox = inbox_dir or local_inbox_dir()
+    if not inbox.exists():
+        return 0
+    imported = 0
+    for fragment_path in sorted(inbox.rglob("*.jsonl")):
+        try:
+            data = fragment_path.read_bytes()
+        except OSError:
+            continue
+        records = parse_fragment_bytes(data)
+        if records:
+            imported += import_records(records)
+        try:
+            fragment_path.unlink()
+        except OSError:
+            pass
+    for writer_dir in inbox.glob("*"):
+        if writer_dir.is_dir():
+            try:
+                writer_dir.rmdir()
+            except OSError:
+                pass
+    return imported
+
+
+def list_bucket_inbox_paths(bucket_id: str) -> list[str]:
+    try:
+        items = huggingface_hub.list_bucket_tree(
+            bucket_id,
+            prefix=BUCKET_INBOX_PREFIX,
+            recursive=True,
+            token=huggingface_hub.utils.get_token(),
+        )
+    except Exception:
+        return []
+    return sorted(
+        item.path
+        for item in items
+        if getattr(item, "type", None) == "file"
+        and getattr(item, "path", "").endswith(".jsonl")
+    )
+
+
+def import_inbox_from_bucket(bucket_id: str) -> int:
+    paths = list_bucket_inbox_paths(bucket_id)
+    if not paths:
+        return 0
+    imported = 0
+    consumed: list[str] = []
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        for i, remote_path in enumerate(paths):
+            local_path = Path(tmp_dir) / f"{i}.jsonl"
+            try:
+                huggingface_hub.download_bucket_files(
+                    bucket_id,
+                    files=[(remote_path, str(local_path))],
+                    token=huggingface_hub.utils.get_token(),
+                )
+                records = parse_fragment_bytes(local_path.read_bytes())
+            except Exception:
+                continue
+            if records:
+                imported += import_records(records)
+            consumed.append(remote_path)
+    if consumed:
+        try:
+            huggingface_hub.batch_bucket_files(
+                bucket_id,
+                delete=consumed,
+                token=huggingface_hub.utils.get_token(),
+            )
+        except Exception:
+            pass
+    return imported
+
+
+def _add_files_to_bucket(bucket_id: str, additions: list[tuple[str, str]]) -> None:
+    if additions:
+        huggingface_hub.batch_bucket_files(
+            bucket_id,
+            add=additions,
+            token=huggingface_hub.utils.get_token(),
+        )
+
+
+def _upload_files_to_bucket(
+    bucket_id: str,
+    uploads: list[dict[str, Any]],
+    remote_path: Callable[[dict[str, Any], Path], str],
+) -> None:
+    _add_files_to_bucket(
+        bucket_id,
+        [
+            (str(p), remote_path(upload, p))
+            for upload in uploads
+            if (p := Path(upload["file_path"])).exists()
+        ],
+    )
+
+
+def upload_media_files_to_bucket(bucket_id: str, uploads: list[dict[str, Any]]) -> None:
+    _upload_files_to_bucket(
+        bucket_id,
+        uploads,
+        lambda upload, p: bucket_media_path(
+            project=upload["project"],
+            run=upload.get("run"),
+            step=upload.get("step"),
+            relative_path=upload.get("relative_path"),
+            filename=p.name,
+        ),
+    )
+
+
+def upload_artifact_blobs_to_bucket(
+    bucket_id: str, uploads: list[dict[str, Any]]
+) -> None:
+    _upload_files_to_bucket(
+        bucket_id,
+        uploads,
+        lambda upload, p: f"trackio/{p.relative_to(utils.TRACKIO_DIR).as_posix()}",
+    )

trackio/frontend/dist/assets/index-m3jgYXoS.css

@@ -0,0 +1 @@
+:root{--primary-50: #fff7ed;--primary-100: #ffedd5;--primary-200: #fed7aa;--primary-300: #fdba74;--primary-400: #fb923c;--primary-500: #f97316;--primary-600: #ea580c;--primary-700: #c2410c;--primary-800: #9a3412;--primary-900: #7c2d12;--primary-950: #6c2e12;--secondary-50: #eff6ff;--secondary-100: #dbeafe;--secondary-200: #bfdbfe;--secondary-300: #93c5fd;--secondary-400: #60a5fa;--secondary-500: #3b82f6;--secondary-600: #2563eb;--secondary-700: #1d4ed8;--secondary-800: #1e40af;--secondary-900: #1e3a8a;--secondary-950: #1d3660;--neutral-50: #f9fafb;--neutral-100: #f3f4f6;--neutral-200: #e5e7eb;--neutral-300: #d1d5db;--neutral-400: #9ca3af;--neutral-500: #6b7280;--neutral-600: #4b5563;--neutral-700: #374151;--neutral-800: #1f2937;--neutral-900: #111827;--neutral-950: #0b0f19;--size-0-5: 2px;--size-1: 4px;--size-2: 8px;--size-3: 12px;--size-4: 16px;--size-5: 20px;--size-6: 24px;--size-8: 32px;--size-14: 56px;--size-16: 64px;--size-28: 112px;--size-full: 100%;--spacing-xxs: 1px;--spacing-xs: 2px;--spacing-sm: 4px;--spacing-md: 6px;--spacing-lg: 8px;--spacing-xl: 10px;--spacing-xxl: 16px;--radius-xxs: 1px;--radius-xs: 2px;--radius-sm: 3px;--radius-md: 4px;--radius-lg: 5px;--radius-xl: 8px;--radius-xxl: 12px;--text-xxs: 9px;--text-xs: 10px;--text-sm: 12px;--text-md: 14px;--text-lg: 16px;--text-xl: 22px;--text-xxl: 26px;--line-sm: 1.4;--background-fill-primary: white;--background-fill-secondary: var(--neutral-50);--body-text-color: var(--neutral-900);--body-text-color-subdued: var(--neutral-600);--border-color-primary: var(--neutral-200);--color-accent: var(--primary-500);--color-accent-soft: var(--primary-50);--shadow-drop: rgba(0, 0, 0, .05) 0px 1px 2px 0px;--shadow-drop-lg: 0 1px 3px 0 rgb(0 0 0 / .1), 0 1px 2px -1px rgb(0 0 0 / .1);--shadow-inset: rgba(0, 0, 0, .05) 0px 2px 4px 0px inset;--shadow-spread: 3px;--block-title-text-color: var(--neutral-500);--block-title-text-size: var(--text-md);--block-title-text-weight: 400;--block-info-text-color: var(--body-text-color-subdued);--block-info-text-size: var(--text-sm);--input-background-fill: white;--input-background-fill-focus: var(--primary-500);--input-border-color: var(--border-color-primary);--input-border-color-focus: var(--primary-300);--input-border-width: 1px;--input-padding: var(--spacing-xl);--input-placeholder-color: var(--neutral-400);--input-radius: var(--radius-lg);--input-shadow: 0 0 0 var(--shadow-spread) transparent, var(--shadow-inset);--input-shadow-focus: 0 0 0 var(--shadow-spread) var(--primary-50), var(--shadow-inset);--input-text-size: var(--text-md);--checkbox-background-color: var(--background-fill-primary);--checkbox-background-color-focus: var(--checkbox-background-color);--checkbox-background-color-hover: var(--checkbox-background-color);--checkbox-background-color-selected: var(--primary-600);--checkbox-border-color: var(--neutral-300);--checkbox-border-color-focus: var(--primary-500);--checkbox-border-color-hover: var(--neutral-300);--checkbox-border-color-selected: var(--primary-600);--checkbox-border-radius: var(--radius-sm);--checkbox-border-width: var(--input-border-width);--checkbox-label-gap: var(--spacing-lg);--checkbox-label-padding: var(--spacing-md) calc(2 * var(--spacing-md));--checkbox-label-text-size: var(--text-md);--checkbox-shadow: var(--input-shadow);--checkbox-check: url("data:image/svg+xml,%3csvg viewBox='0 0 16 16' fill='white' xmlns='http://www.w3.org/2000/svg'%3e%3cpath d='M12.207 4.793a1 1 0 010 1.414l-5 5a1 1 0 01-1.414 0l-2-2a1 1 0 011.414-1.414L6.5 9.086l4.293-4.293a1 1 0 011.414 0z'/%3e%3c/svg%3e");--slider-color: var(--primary-500);--container-radius: var(--radius-lg);--layer-top: 9999}.navbar.svelte-d8j1hi{display:flex;align-items:stretch;border-bottom:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, white);padding:0;flex-shrink:0;min-height:44px}.nav-spacer.svelte-d8j1hi{flex:1 1 0;min-width:0}.nav-tabs.svelte-d8j1hi{display:flex;gap:0;flex-shrink:0;padding-right:8px}.nav-link.svelte-d8j1hi{padding:10px 16px;border:none;background:none;color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-md, 14px);cursor:pointer;white-space:nowrap;border-bottom:2px solid transparent;transition:color .15s;font-weight:400}.nav-link.empty.svelte-d8j1hi:not(.active){color:var(--body-text-color-subdued, #9ca3af);opacity:.48}.nav-link.svelte-d8j1hi:hover{color:var(--body-text-color, #1f2937);opacity:1}.nav-link.active.svelte-d8j1hi{color:var(--body-text-color, #1f2937);border-bottom-color:var(--body-text-color, #1f2937);font-weight:500}.settings-btn.svelte-d8j1hi{display:flex;align-items:center;gap:6px}.settings-btn.svelte-d8j1hi svg:where(.svelte-d8j1hi){flex-shrink:0}.checkbox-group.svelte-17gmtkf{display:flex;flex-direction:column}.checkbox-item.svelte-17gmtkf{display:flex;align-items:center;gap:8px;padding:3px 0;cursor:pointer;font-size:13px}.checkbox-item.svelte-17gmtkf input[type=checkbox]:where(.svelte-17gmtkf){-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;margin:0;border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);box-shadow:var(--checkbox-shadow);cursor:pointer;flex-shrink:0;transition:background-color .15s,border-color .15s}.checkbox-item.svelte-17gmtkf input[type=checkbox]:where(.svelte-17gmtkf):checked{background-image:var(--checkbox-check);background-color:var(--checkbox-background-color-selected, #f97316);border-color:var(--checkbox-border-color-selected, #f97316)}.checkbox-item.svelte-17gmtkf input[type=checkbox]:where(.svelte-17gmtkf):hover{border-color:var(--checkbox-border-color-hover, #d1d5db)}.color-dot.svelte-17gmtkf{width:10px;height:10px;border-radius:50%;flex-shrink:0}.run-name.svelte-17gmtkf{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--body-text-color, #1f2937)}.dropdown-container.svelte-kgylqb{width:100%;margin-bottom:4px}.label.svelte-kgylqb{display:block;font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280);margin-bottom:6px}.info.svelte-kgylqb{display:block;font-size:12px;color:var(--body-text-color-subdued, #9ca3af);margin-bottom:4px}.wrap.svelte-kgylqb{position:relative;border-radius:var(--input-radius, 8px);background:var(--input-background-fill, white);border:1px solid var(--border-color-primary, #e5e7eb);transition:border-color .15s,box-shadow .15s}.wrap.focused.svelte-kgylqb{border-color:var(--input-border-color-focus, #fdba74);box-shadow:0 0 0 2px var(--primary-50, #fff7ed)}.wrap-inner.svelte-kgylqb{display:flex;position:relative;align-items:center;padding:0 10px}.secondary-wrap.svelte-kgylqb{display:flex;flex:1;align-items:center}input.svelte-kgylqb{margin:0;outline:none;border:none;background:inherit;width:100%;color:var(--body-text-color, #1f2937);font-size:13px;font-family:inherit;padding:7px 0}input.svelte-kgylqb::placeholder{color:var(--input-placeholder-color, #9ca3af)}input[readonly].svelte-kgylqb{cursor:pointer}.icon-wrap.svelte-kgylqb{color:var(--body-text-color-subdued, #9ca3af);width:16px;flex-shrink:0;pointer-events:none}.options.svelte-kgylqb{position:fixed;z-index:var(--layer-top, 9999);margin:0;padding:4px 0;box-shadow:0 4px 12px #0000001f;border-radius:var(--input-radius, 8px);border:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, white);min-width:fit-content;overflow:auto;color:var(--body-text-color, #1f2937);list-style:none}.item.svelte-kgylqb{display:flex;cursor:pointer;padding:6px 10px;font-size:13px;word-break:break-word}.item.svelte-kgylqb:hover,.item.active.svelte-kgylqb{background:var(--background-fill-secondary, #f9fafb)}.item.selected.svelte-kgylqb{font-weight:500}.check-mark.svelte-kgylqb{padding-right:6px;min-width:16px;font-size:12px}.check-mark.hide.svelte-kgylqb{visibility:hidden}.section-label.svelte-1kanzy0{font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280)}.locked-project.svelte-1kanzy0{margin-top:4px;font-size:13px;font-weight:500;color:var(--body-text-color, #1f2937);padding:8px 10px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);background:var(--background-fill-secondary, #f9fafb)}.logo-section.svelte-tssf2h{margin-bottom:20px}.logo.svelte-tssf2h{width:80%;max-width:200px}.checkbox-container.svelte-oj84db{display:flex;align-items:center;gap:8px;cursor:pointer;padding:3px 0}.label-text.svelte-oj84db{color:var(--body-text-color, #1f2937);font-size:13px;line-height:1.4}input[type=checkbox].svelte-oj84db{--ring-color: transparent;position:relative;-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;box-shadow:var(--checkbox-shadow);border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);flex-shrink:0;cursor:pointer;transition:background-color .15s,border-color .15s}input[type=checkbox].svelte-oj84db:checked,input[type=checkbox].svelte-oj84db:checked:hover,input[type=checkbox].svelte-oj84db:checked:focus{background-image:var(--checkbox-check);background-color:var(--checkbox-background-color-selected, #f97316);border-color:var(--checkbox-border-color-selected, #f97316)}input[type=checkbox].svelte-oj84db:hover{border-color:var(--checkbox-border-color-hover, #d1d5db);background-color:var(--checkbox-background-color-hover, white)}input[type=checkbox].svelte-oj84db:focus{border-color:var(--checkbox-border-color-focus, #f97316);background-color:var(--checkbox-background-color-focus, white);outline:none}.slider-wrap.svelte-wei6ev{display:flex;flex-direction:column;width:100%}.head.svelte-wei6ev{margin-bottom:4px;display:flex;justify-content:space-between;align-items:center;width:100%}.label.svelte-wei6ev{flex:1;font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280)}.info.svelte-wei6ev{display:block;font-size:12px;color:var(--body-text-color-subdued, #9ca3af);margin-bottom:4px}.slider-input-container.svelte-wei6ev{display:flex;align-items:center;gap:6px}input[type=range].svelte-wei6ev{-webkit-appearance:none;-moz-appearance:none;appearance:none;width:100%;cursor:pointer;outline:none;border-radius:var(--radius-xl, 12px);min-width:var(--size-28, 112px);background:transparent}input[type=range].svelte-wei6ev::-webkit-slider-runnable-track{height:6px;border-radius:var(--radius-xl, 12px);background:linear-gradient(to right,var(--slider-color, #f97316) var(--range_progress, 50%),var(--neutral-200, #e5e7eb) var(--range_progress, 50%))}input[type=range].svelte-wei6ev::-webkit-slider-thumb{-webkit-appearance:none;-moz-appearance:none;appearance:none;height:16px;width:16px;background-color:var(--slider-color, #f97316);border:2px solid var(--background-fill-primary, white);border-radius:50%;margin-top:-5px;box-shadow:0 0 0 1px var(--border-color-primary, rgba(0, 0, 0, .08)),0 1px 3px #0003}input[type=range].svelte-wei6ev::-moz-range-track{height:6px;background:var(--neutral-200, #e5e7eb);border-radius:var(--radius-xl, 12px)}input[type=range].svelte-wei6ev::-moz-range-thumb{-webkit-appearance:none;-moz-appearance:none;appearance:none;height:16px;width:16px;background-color:var(--slider-color, #f97316);border:2px solid var(--background-fill-primary, white);border-radius:50%;box-shadow:0 0 0 1px var(--border-color-primary, rgba(0, 0, 0, .08)),0 1px 3px #0003}input[type=range].svelte-wei6ev::-moz-range-progress{height:6px;background-color:var(--slider-color, #f97316);border-radius:var(--radius-xl, 12px)}.bound.svelte-wei6ev{font-size:11px;color:var(--body-text-color-subdued, #9ca3af);min-width:12px;text-align:center}.textbox-container.svelte-6yncpg{width:100%}.label.svelte-6yncpg{display:block;font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280);margin-bottom:6px}.info.svelte-6yncpg{display:block;font-size:12px;color:var(--body-text-color-subdued, #9ca3af);margin-bottom:4px}.input-wrap.svelte-6yncpg{border-radius:var(--input-radius, 8px);background:var(--input-background-fill, white);border:1px solid var(--border-color-primary, #e5e7eb);transition:border-color .15s,box-shadow .15s}.input-wrap.svelte-6yncpg:focus-within{border-color:var(--input-border-color-focus, #fdba74);box-shadow:0 0 0 2px var(--primary-50, #fff7ed)}input.svelte-6yncpg{width:100%;padding:7px 10px;outline:none;border:none;background:transparent;color:var(--body-text-color, #1f2937);font-size:13px;font-family:inherit;border-radius:var(--input-radius, 8px)}input.svelte-6yncpg::placeholder{color:var(--input-placeholder-color, #9ca3af)}.sidebar.svelte-181dlmc{width:290px;min-width:290px;background:var(--background-fill-primary, white);border-right:1px solid var(--border-color-primary, #e5e7eb);display:flex;flex-direction:column;position:relative;overflow:hidden;transition:width .2s,min-width .2s}.sidebar.collapsed.svelte-181dlmc{width:40px;min-width:40px}.toggle-btn.svelte-181dlmc{position:absolute;top:12px;right:8px;z-index:10;border:none;background:none;color:var(--body-text-color-subdued, #9ca3af);cursor:pointer;padding:4px;display:flex;align-items:center;justify-content:center;border-radius:var(--radius-sm, 4px);transition:color .15s,background-color .15s}.toggle-btn.svelte-181dlmc:hover{color:var(--body-text-color, #1f2937);background-color:var(--background-fill-secondary, #f9fafb)}.sidebar-content.svelte-181dlmc{padding:16px;flex:1;min-height:0;display:flex;flex-direction:column}.sidebar-scroll.svelte-181dlmc{overflow-y:auto;flex:1;min-height:0}.oauth-footer.svelte-181dlmc{flex-shrink:0;margin-top:12px;padding-top:12px;border-top:1px solid var(--border-color-primary, #e5e7eb)}.readonly-footer.svelte-181dlmc{flex-shrink:0;margin-top:12px;padding-top:12px;border-top:1px solid var(--border-color-primary, #e5e7eb);display:flex;align-items:center;gap:8px;flex-wrap:wrap}.readonly-badge.svelte-181dlmc{display:inline-flex;align-items:center;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:999px;padding:2px 8px;font-size:10px;letter-spacing:.06em;font-weight:600;color:var(--body-text-color-subdued, #6b7280);background:var(--background-fill-secondary, #f9fafb)}.readonly-link.svelte-181dlmc{font-size:12px;color:var(--body-text-color-subdued, #6b7280);text-decoration:none;max-width:100%;overflow-wrap:anywhere}.readonly-link.svelte-181dlmc:hover{color:var(--body-text-color, #1f2937);text-decoration:underline}.oauth-line.svelte-181dlmc{margin:0;font-size:12px;line-height:1.4;color:var(--body-text-color-subdued, #6b7280)}.oauth-warn.svelte-181dlmc{color:var(--body-text-color, #92400e)}.hf-login-btn.svelte-181dlmc{display:inline-flex;align-items:center;justify-content:center;gap:8px;width:100%;padding:8px 12px;font-size:13px;font-weight:600;color:#fff;background:#141c2e;border-radius:var(--radius-lg, 8px);text-decoration:none;border:none;cursor:pointer;box-sizing:border-box}.hf-login-btn.svelte-181dlmc:hover{background:#283042}.hf-logo.svelte-181dlmc{width:20px;height:20px;flex-shrink:0}.oauth-hint.svelte-181dlmc{margin:8px 0 0;font-size:11px;line-height:1.35;color:var(--body-text-color-subdued, #9ca3af)}.oauth-signed-in.svelte-181dlmc{margin:0;font-size:12px;color:var(--body-text-color-subdued, #6b7280)}.oauth-logout.svelte-181dlmc{font-size:12px;color:var(--body-text-color-subdued, #9ca3af);text-decoration:none;cursor:pointer}.oauth-logout.svelte-181dlmc:hover{text-decoration:underline;color:var(--body-text-color, #1f2937)}.section.svelte-181dlmc{margin-top:2px;margin-bottom:18px}.share-tabs.svelte-181dlmc{display:flex;gap:6px;margin-bottom:8px}.share-tab-btn.svelte-181dlmc{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);padding:4px 8px;font-size:12px;color:var(--body-text-color-subdued, #6b7280);background:var(--background-fill-primary, white);cursor:pointer}.share-tab-btn.active.svelte-181dlmc{color:var(--body-text-color, #1f2937);background:var(--background-fill-secondary, #f9fafb)}.share-field.svelte-181dlmc{display:flex;flex-direction:column;gap:6px}.share-input-row.svelte-181dlmc{display:flex;gap:6px;align-items:stretch}.share-input-row.svelte-181dlmc input:where(.svelte-181dlmc),.share-input-row.svelte-181dlmc textarea:where(.svelte-181dlmc){width:100%;min-width:0;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);padding:6px 8px;font-size:12px;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;color:var(--body-text-color, #1f2937);background:var(--background-fill-secondary, #f9fafb);resize:vertical}.copy-btn.svelte-181dlmc{box-sizing:border-box;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);padding:6px 10px;min-width:3.25rem;display:inline-flex;align-items:center;justify-content:center;font-size:12px;line-height:1;color:var(--body-text-color, #1f2937);background:var(--background-fill-primary, white);cursor:pointer;flex-shrink:0}.copy-btn-check.svelte-181dlmc{display:block;color:var(--color-accent, #f97316)}.share-hint.svelte-181dlmc{margin:0;font-size:12px;line-height:1.4;color:var(--body-text-color-subdued, #9ca3af)}.section-label.svelte-181dlmc{font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280)}.runs-header.svelte-181dlmc{display:flex;align-items:center;justify-content:space-between;margin-bottom:6px}.select-all-label.svelte-181dlmc{display:flex;align-items:center;gap:6px;cursor:pointer}.select-all-cb.svelte-181dlmc{-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);cursor:pointer;flex-shrink:0;position:relative;transition:background-color .15s,border-color .15s}.select-all-cb.svelte-181dlmc:checked{background-color:var(--checkbox-background-color-selected, var(--color-accent, #f97316));border-color:var(--checkbox-background-color-selected, var(--color-accent, #f97316));background-image:var(--checkbox-check)}.select-all-cb.svelte-181dlmc:indeterminate{background-color:var(--checkbox-background-color-selected, var(--color-accent, #f97316));border-color:var(--checkbox-background-color-selected, var(--color-accent, #f97316));background-image:url("data:image/svg+xml,%3Csvg viewBox='0 0 16 16' fill='white' xmlns='http://www.w3.org/2000/svg'%3E%3Crect x='3' y='7' width='10' height='2' rx='1'/%3E%3C/svg%3E");background-size:12px;background-position:center;background-repeat:no-repeat}.latest-toggle.svelte-181dlmc{display:flex;align-items:center;gap:6px;font-size:12px;color:var(--body-text-color-subdued, #6b7280);cursor:pointer}.latest-toggle.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc){-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;margin:0;border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);box-shadow:var(--checkbox-shadow);cursor:pointer;flex-shrink:0;transition:background-color .15s,border-color .15s}.latest-toggle.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc):checked{background-image:var(--checkbox-check);background-color:var(--checkbox-background-color-selected, #f97316);border-color:var(--checkbox-border-color-selected, #f97316)}.checkbox-list.svelte-181dlmc{max-height:300px;overflow-y:auto;margin-top:8px}.device-group.svelte-181dlmc{margin-top:14px;padding-top:12px;border-top:1px solid var(--border-color-primary, #e5e7eb)}.section-sublabel.svelte-181dlmc{font-size:12px;font-weight:600;color:var(--body-text-color-subdued, #6b7280)}.checkbox-group.svelte-181dlmc{display:flex;flex-direction:column;margin-top:8px}.checkbox-item.svelte-181dlmc{display:flex;align-items:center;gap:8px;padding:3px 0;cursor:pointer;font-size:13px}.checkbox-item.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc){-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;margin:0;border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);box-shadow:var(--checkbox-shadow);cursor:pointer;flex-shrink:0;transition:background-color .15s,border-color .15s}.checkbox-item.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc):checked{background-image:var(--checkbox-check);background-color:var(--checkbox-background-color-selected, #f97316);border-color:var(--checkbox-border-color-selected, #f97316)}.checkbox-item.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc):hover{border-color:var(--checkbox-border-color-hover, #d1d5db)}.run-name.svelte-181dlmc{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--body-text-color, #1f2937)}.group-by-row.svelte-181dlmc{margin-top:8px}.grouped-runs.svelte-181dlmc{margin-top:8px;display:flex;flex-direction:column;gap:6px}.run-group-section.svelte-181dlmc{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);overflow:hidden}.run-group-header.svelte-181dlmc{display:flex;align-items:center;padding:6px 10px;background:var(--background-fill-secondary, #f9fafb);border-bottom:1px solid var(--border-color-primary, #e5e7eb)}.run-group-label.svelte-181dlmc{font-size:12px;font-weight:600;color:var(--body-text-color, #1f2937);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:160px}.run-group-count.svelte-181dlmc{font-size:11px;color:var(--body-text-color-subdued, #9ca3af);margin-left:4px;flex-shrink:0}.group-checkbox-list.svelte-181dlmc{padding:4px 10px;max-height:none}.alert-panel.svelte-x5aqew{position:fixed;bottom:16px;right:16px;width:380px;max-height:400px;background:var(--background-fill-primary, white);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);box-shadow:var(--shadow-drop-lg);z-index:1000;overflow:hidden;display:flex;flex-direction:column}.alert-panel.collapsed.svelte-x5aqew{max-height:none}.alert-header.svelte-x5aqew{padding:10px 12px;border:none;border-bottom:1px solid var(--border-color-primary, #e5e7eb);background:none;width:100%;display:flex;align-items:center;justify-content:space-between;cursor:pointer;gap:8px}.alert-panel.collapsed.svelte-x5aqew .alert-header:where(.svelte-x5aqew){border-bottom:none}.collapse-icon.svelte-x5aqew{color:var(--body-text-color-subdued, #9ca3af);flex-shrink:0;transition:transform .15s}.collapse-icon.rotated.svelte-x5aqew{transform:rotate(-90deg)}.alert-title.svelte-x5aqew{font-size:13px;font-weight:600;color:var(--body-text-color, #1f2937)}.filter-pills.svelte-x5aqew{display:flex;gap:4px}.pill.svelte-x5aqew{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-xxl, 22px);padding:2px 8px;font-size:11px;background:var(--background-fill-secondary, #f9fafb);color:var(--body-text-color-subdued, #6b7280);cursor:pointer}.pill.active.svelte-x5aqew{background:var(--color-accent, #f97316);color:#fff;border-color:var(--color-accent, #f97316)}.alert-list.svelte-x5aqew{overflow-y:auto;flex:1}.alert-item.svelte-x5aqew{border-bottom:1px solid var(--neutral-100, #f3f4f6)}.alert-row.svelte-x5aqew{display:flex;align-items:center;gap:8px;width:100%;padding:8px 12px;border:none;background:none;text-align:left;cursor:pointer;font-size:var(--text-sm, 12px)}.alert-row.svelte-x5aqew:hover{background:var(--background-fill-secondary, #f9fafb)}.alert-text.svelte-x5aqew{flex:1;color:var(--body-text-color, #1f2937)}.alert-meta.svelte-x5aqew{font-size:var(--text-xs, 10px);color:var(--body-text-color-subdued, #9ca3af);white-space:nowrap}.alert-detail.svelte-x5aqew{padding:4px 12px 8px 32px;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.plot-container.svelte-9thu1j{min-width:350px;flex:1;background:var(--background-fill-primary, white);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);padding:12px;overflow:hidden;position:relative}.plot-container[draggable=true].svelte-9thu1j{cursor:grab}.plot-container[draggable=true].svelte-9thu1j:active{cursor:grabbing}.hidden-plot.svelte-9thu1j{visibility:hidden;height:0;padding:0;margin:0;border:none;overflow:hidden;pointer-events:none}.drag-handle.svelte-9thu1j{position:absolute;top:8px;left:8px;color:var(--body-text-color-subdued, #9ca3af);opacity:0;transition:opacity .15s;z-index:5}.plot-container.svelte-9thu1j:hover .drag-handle:where(.svelte-9thu1j){opacity:.5}.drag-handle.svelte-9thu1j:hover{opacity:1!important}.plot-toolbar.svelte-9thu1j{position:absolute;top:8px;right:8px;display:flex;gap:4px;z-index:5;opacity:0;transition:opacity .15s}.plot-container.svelte-9thu1j:hover .plot-toolbar:where(.svelte-9thu1j){opacity:1}.toolbar-btn.svelte-9thu1j{border:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, white);color:var(--body-text-color-subdued, #6b7280);cursor:pointer;padding:4px 6px;border-radius:var(--radius-sm, 4px);display:flex;align-items:center;justify-content:center}.toolbar-btn.svelte-9thu1j:hover{background:var(--neutral-100, #f3f4f6);color:var(--body-text-color, #1f2937)}.plot-chart-wrap.svelte-9thu1j{position:relative;width:100%}.plot-chart-wrap--fs.svelte-9thu1j{flex:1;min-height:0;display:flex;flex-direction:column}.reset-zoom-btn.svelte-9thu1j{position:absolute;bottom:1px;right:1px;z-index:6;display:inline-flex;align-items:center;justify-content:center;margin:0;min-width:52px;padding:5px 12px 5px 10px;border:none;border-radius:4px;background:transparent;color:var(--body-text-color-subdued, #334155);cursor:pointer;opacity:.92;transform:translateY(6px);transition:opacity .15s ease,color .15s ease,background .15s ease;box-shadow:none}.reset-zoom-btn.svelte-9thu1j:hover{opacity:1;color:var(--body-text-color, #0f172a);background:var(--background-fill-secondary, rgba(226, 232, 240, .85));transform:translateY(6px)}.reset-zoom-btn.svelte-9thu1j svg:where(.svelte-9thu1j){display:block;flex-shrink:0;filter:drop-shadow(0 0 .5px rgba(255,255,255,.95))}.plot-title.svelte-9thu1j{font-size:13px;font-weight:600;color:var(--body-text-color, #374151);text-align:center;padding:0 0 6px;word-break:break-word}.plot-title--fs.svelte-9thu1j{flex-shrink:0}.plot.svelte-9thu1j{width:100%}.plot.svelte-9thu1j .vega-embed{width:100%!important}.plot.svelte-9thu1j .vega-embed summary{display:none}.fullscreen-host.svelte-9thu1j{position:fixed;top:0;right:0;bottom:0;left:0;z-index:10000;box-sizing:border-box;display:flex;flex-direction:column;background:var(--background-fill-primary, white);padding:12px;gap:8px;pointer-events:auto}.fullscreen-host.svelte-9thu1j:fullscreen{width:100%;height:100%}.fullscreen-host.svelte-9thu1j:-webkit-full-screen{width:100%;height:100%}.fullscreen-toolbar.svelte-9thu1j{flex-shrink:0;display:flex;justify-content:flex-end;gap:4px;z-index:5}.fullscreen-chart-wrap.svelte-9thu1j{flex:1;min-height:0;display:flex;flex-direction:column}.fullscreen-legend.svelte-9thu1j{flex-shrink:0}.fullscreen-plot.svelte-9thu1j{flex:1;min-height:0;width:100%;overflow:hidden}.fullscreen-plot.svelte-9thu1j .vega-embed{width:100%!important;height:100%!important;min-height:0;display:flex;flex-direction:column}.fullscreen-plot.svelte-9thu1j .vega-embed .vega-view{flex:1;min-height:0}.fullscreen-plot.svelte-9thu1j .vega-embed summary{display:none}.custom-legend.svelte-9thu1j{display:flex;align-items:center;justify-content:center;gap:12px;padding:6px 0 0;flex-wrap:wrap}.legend-title.svelte-9thu1j{font-size:11px;color:var(--body-text-color-subdued, #6b7280);font-weight:600}.legend-item.svelte-9thu1j{display:flex;align-items:center;gap:4px}.legend-dot.svelte-9thu1j{width:10px;height:10px;border-radius:50%;flex-shrink:0}.legend-line-swatch.svelte-9thu1j{width:24px;height:10px;flex-shrink:0;color:var(--body-text-color, #1f2937)}.legend-label.svelte-9thu1j{font-size:11px;color:var(--body-text-color-subdued, #6b7280)}.legend-toggle.svelte-9thu1j{font-size:11px;color:var(--body-text-color-subdued, #6b7280);background:none;border:none;padding:0 4px;cursor:pointer;text-decoration:underline}.legend-toggle.svelte-9thu1j:hover{color:var(--body-text-color, #1f2937)}.plot-container.svelte-1swghqy{min-width:350px;flex:1;background:var(--background-fill-primary, white);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);padding:12px;overflow:hidden;position:relative}.plot-container[draggable=true].svelte-1swghqy{cursor:grab}.plot-container[draggable=true].svelte-1swghqy:active{cursor:grabbing}.hidden-plot.svelte-1swghqy{visibility:hidden;height:0;padding:0;margin:0;border:none;overflow:hidden;pointer-events:none}.drag-handle.svelte-1swghqy{position:absolute;top:8px;left:8px;color:var(--body-text-color-subdued, #9ca3af);opacity:0;transition:opacity .15s;z-index:5}.plot-container.svelte-1swghqy:hover .drag-handle:where(.svelte-1swghqy){opacity:.5}.drag-handle.svelte-1swghqy:hover{opacity:1!important}.plot-toolbar.svelte-1swghqy{position:absolute;top:8px;right:8px;display:flex;gap:4px;z-index:5;opacity:0;transition:opacity .15s}.plot-container.svelte-1swghqy:hover .plot-toolbar:where(.svelte-1swghqy){opacity:1}.toolbar-btn.svelte-1swghqy{border:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, white);color:var(--body-text-color-subdued, #6b7280);cursor:pointer;padding:4px 6px;border-radius:var(--radius-sm, 4px);display:flex;align-items:center;justify-content:center}.toolbar-btn.svelte-1swghqy:hover{background:var(--neutral-100, #f3f4f6);color:var(--body-text-color, #1f2937)}.plot-chart-wrap.svelte-1swghqy{position:relative;width:100%}.plot-chart-wrap--fs.svelte-1swghqy{flex:1;min-height:0;display:flex;flex-direction:column}.plot-title.svelte-1swghqy{font-size:13px;font-weight:600;color:var(--body-text-color, #374151);text-align:center;padding:0 0 6px;word-break:break-word}.plot-title--fs.svelte-1swghqy{flex-shrink:0}.plot.svelte-1swghqy{width:100%}.plot.svelte-1swghqy .vega-embed{width:100%!important}.plot.svelte-1swghqy .vega-embed summary{display:none}.fullscreen-host.svelte-1swghqy{position:fixed;top:0;right:0;bottom:0;left:0;z-index:10000;box-sizing:border-box;display:flex;flex-direction:column;background:var(--background-fill-primary, white);padding:12px;gap:8px;pointer-events:auto}.fullscreen-host.svelte-1swghqy:fullscreen{width:100%;height:100%}.fullscreen-host.svelte-1swghqy:-webkit-full-screen{width:100%;height:100%}.fullscreen-toolbar.svelte-1swghqy{flex-shrink:0;display:flex;justify-content:flex-end;gap:4px;z-index:5}.fullscreen-chart-wrap.svelte-1swghqy{flex:1;min-height:0;display:flex;flex-direction:column}.fullscreen-legend.svelte-1swghqy{flex-shrink:0}.fullscreen-plot.svelte-1swghqy{flex:1;min-height:0;width:100%;overflow:hidden}.fullscreen-plot.svelte-1swghqy .vega-embed{width:100%!important;height:100%!important;min-height:0;display:flex;flex-direction:column}.fullscreen-plot.svelte-1swghqy .vega-embed .vega-view{flex:1;min-height:0}.fullscreen-plot.svelte-1swghqy .vega-embed summary{display:none}.custom-legend.svelte-1swghqy{display:flex;align-items:center;justify-content:center;gap:12px;padding:6px 0 0;flex-wrap:wrap}.legend-item.svelte-1swghqy{display:flex;align-items:center;gap:4px}.legend-dot.svelte-1swghqy{width:10px;height:10px;border-radius:50%;flex-shrink:0}.legend-label.svelte-1swghqy{font-size:11px;color:var(--body-text-color-subdued, #6b7280)}.legend-toggle.svelte-1swghqy{font-size:11px;color:var(--body-text-color-subdued, #6b7280);background:none;border:none;padding:0 4px;cursor:pointer;text-decoration:underline}.legend-toggle.svelte-1swghqy:hover{color:var(--body-text-color, #1f2937)}.accordion.svelte-1jep0a{margin-bottom:12px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);background:var(--background-fill-primary, white);overflow:hidden}.accordion-hidden.svelte-1jep0a{margin-bottom:8px}.accordion-header.svelte-1jep0a{display:flex;align-items:center;gap:8px;width:100%;padding:10px 14px;border:none;background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:var(--text-md, 14px);font-weight:600;cursor:pointer;text-align:left}.accordion-header.svelte-1jep0a:hover{background:var(--background-fill-secondary, #f9fafb)}.arrow.svelte-1jep0a{font-size:14px;transition:transform .15s;color:var(--body-text-color, #1f2937);display:inline-block}.arrow.svelte-1jep0a:not(.rotated){transform:rotate(-90deg)}.accordion-body.svelte-1jep0a{padding:0 14px 14px}.trackio-loading.svelte-1kc6b2l{display:flex;align-items:center;justify-content:center;width:100%;min-height:min(70vh,640px);padding:32px 24px;box-sizing:border-box;background:transparent}.logo-stack.svelte-1kc6b2l{position:relative;width:min(100%,200px);max-width:min(92vw,200px);line-height:0;background:transparent;isolation:isolate}.logo-base.svelte-1kc6b2l{display:block;background:transparent}.logo-img.svelte-1kc6b2l{width:100%;height:auto;display:block;background:transparent}.logo-overlay.svelte-1kc6b2l{position:absolute;left:0;top:0;width:100%;animation:svelte-1kc6b2l-trackio-logo-sweep 4s linear infinite;pointer-events:none;background:transparent}.logo-overlay.svelte-1kc6b2l .logo-img:where(.svelte-1kc6b2l){width:100%;height:auto;object-position:left center}.logo-img--gray.svelte-1kc6b2l{filter:grayscale(1)}@keyframes svelte-1kc6b2l-trackio-logo-sweep{0%{clip-path:inset(0 0 0 0)}50%{clip-path:inset(0 0 0 100%)}to{clip-path:inset(0 0 0 0)}}@media(prefers-reduced-motion:reduce){.logo-overlay.svelte-1kc6b2l{display:none}}.sr-only.svelte-1kc6b2l{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.metrics-page.svelte-2bul55{padding:20px 24px;overflow-y:auto;flex:1;min-height:0}.plot-grid.svelte-2bul55{display:flex;flex-wrap:wrap;gap:16px}.subgroup-list.svelte-2bul55{margin-top:16px}.empty-state.svelte-2bul55{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-2bul55 h2:where(.svelte-2bul55){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-2bul55 p:where(.svelte-2bul55){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-2bul55 pre:where(.svelte-2bul55){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-2bul55 code:where(.svelte-2bul55){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-2bul55 pre:where(.svelte-2bul55) code:where(.svelte-2bul55){background:none;padding:0}.traces-page.svelte-1s32ifo{padding:20px 24px;overflow-y:auto;flex:1;background:var(--background-fill-primary, white)}.toolbar.svelte-1s32ifo{display:flex;align-items:center;gap:12px;margin-bottom:16px}.search-wrap.svelte-1s32ifo{flex:1}.search-wrap.svelte-1s32ifo input:where(.svelte-1s32ifo),.filter-wrap.svelte-1s32ifo select:where(.svelte-1s32ifo){width:100%;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:14px;padding:10px 12px;font-family:inherit}.filter-wrap.svelte-1s32ifo{display:flex;align-items:center;gap:8px;color:var(--body-text-color, #1f2937);font-size:14px;white-space:nowrap}.count.svelte-1s32ifo{margin-left:auto;color:var(--body-text-color-subdued, #6b7280);font-size:14px;white-space:nowrap}.traces-table-wrap.svelte-1s32ifo{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);overflow:hidden;transition:opacity .15s ease}.traces-table-wrap.dim.svelte-1s32ifo{opacity:.55}.traces-table.svelte-1s32ifo{width:100%;border-collapse:collapse;font-size:14px;table-layout:fixed}.trace-id-col.svelte-1s32ifo{width:140px}.request-col.svelte-1s32ifo{width:auto}.run-col.svelte-1s32ifo{width:180px}.step-col.svelte-1s32ifo{width:76px}.request-time-col.svelte-1s32ifo{width:150px}.traces-table.svelte-1s32ifo th:where(.svelte-1s32ifo){text-align:left;padding:10px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);font-weight:600;font-size:12px;text-transform:uppercase;letter-spacing:.05em;background:var(--background-fill-primary, white)}.traces-table.svelte-1s32ifo td:where(.svelte-1s32ifo){padding:10px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937);vertical-align:top}.trace-row.svelte-1s32ifo{cursor:pointer}.trace-row.svelte-1s32ifo:hover{background:var(--background-fill-secondary, #f9fafb)}.trace-id-chip.svelte-1s32ifo{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:13px;color:var(--body-text-color, #1f2937)}.request.svelte-1s32ifo{font-weight:500;margin-bottom:4px}.preview.svelte-1s32ifo{color:var(--body-text-color-subdued, #6b7280);font-size:13px;line-height:1.45;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}.expanded-row.svelte-1s32ifo td:where(.svelte-1s32ifo){padding:0;background:var(--background-fill-secondary, #fafafa)}.trace-detail.svelte-1s32ifo{padding:16px 18px 18px}.detail-meta.svelte-1s32ifo{display:flex;gap:16px;flex-wrap:wrap;color:var(--body-text-color-subdued, #6b7280);font-size:13px;margin-bottom:14px}.conversation.svelte-1s32ifo{display:flex;flex-direction:column;gap:12px}.message.svelte-1s32ifo{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);background:var(--background-fill-primary, white);padding:12px}.message-role.svelte-1s32ifo{margin-bottom:8px;color:var(--body-text-color-subdued, #6b7280);font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:.05em;display:flex;align-items:center;gap:8px;flex-wrap:wrap}.message-tag.svelte-1s32ifo{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:999px;padding:2px 8px;font-size:11px;font-weight:500;text-transform:none;letter-spacing:0}.message-content.svelte-1s32ifo,.tool-block.svelte-1s32ifo{margin:0;white-space:pre-wrap;word-break:break-word;font-family:inherit;color:var(--body-text-color, #1f2937);line-height:1.5}.message-details.svelte-1s32ifo summary:where(.svelte-1s32ifo){cursor:pointer;margin-bottom:8px;color:var(--body-text-color-subdued, #6b7280)}.tool-blocks.svelte-1s32ifo{display:flex;flex-direction:column;gap:8px;margin-top:10px}.tool-block.svelte-1s32ifo{background:var(--background-fill-secondary, #f9fafb);border-radius:var(--radius-md, 6px);padding:10px;overflow-x:auto}.message-parts.svelte-1s32ifo{display:flex;flex-direction:column;gap:10px}.trace-image.svelte-1s32ifo{max-width:100%;max-height:360px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px)}.empty-state.svelte-1s32ifo{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-1s32ifo h2:where(.svelte-1s32ifo){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-1s32ifo p:where(.svelte-1s32ifo){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.pagination.svelte-1s32ifo{display:flex;align-items:center;justify-content:center;gap:12px;padding:16px 0 4px}.pagination.svelte-1s32ifo button:where(.svelte-1s32ifo){border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:14px;padding:8px 14px;cursor:pointer;font-family:inherit}.pagination.svelte-1s32ifo button:where(.svelte-1s32ifo):hover:not(:disabled){background:var(--background-fill-secondary, #f9fafb)}.pagination.svelte-1s32ifo button:where(.svelte-1s32ifo):disabled{opacity:.5;cursor:not-allowed}.page-info.svelte-1s32ifo{color:var(--body-text-color-subdued, #6b7280);font-size:14px;min-width:120px;text-align:center}@media(max-width:1100px){.toolbar.svelte-1s32ifo{flex-wrap:wrap}.count.svelte-1s32ifo{margin-left:0}}.system-page.svelte-nv5os4{padding:20px 24px;overflow-y:auto;flex:1;min-height:0}.plot-grid.svelte-nv5os4{display:flex;flex-wrap:wrap;gap:12px}.subgroup-list.svelte-nv5os4{margin-top:16px}.empty-state.svelte-nv5os4{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-nv5os4 h2:where(.svelte-nv5os4){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-nv5os4 p:where(.svelte-nv5os4){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-nv5os4 pre:where(.svelte-nv5os4){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-nv5os4 ul:where(.svelte-nv5os4){list-style:disc;padding-left:20px;margin:4px 0 0}.empty-state.svelte-nv5os4 li:where(.svelte-nv5os4){margin:4px 0;color:var(--body-text-color, #1f2937)}.empty-state.svelte-nv5os4 code:where(.svelte-nv5os4){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-nv5os4 pre:where(.svelte-nv5os4) code:where(.svelte-nv5os4){background:none;padding:0}.wave-wrap.svelte-19wbodf{--wave-base: var(--body-text-color-subdued, #9ca3af);--wave-played: var(--color-accent, #f97316);display:flex;align-items:center;gap:8px;padding:8px 10px;background:var(--background-fill-secondary, #f9fafb);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);color:var(--body-text-color, #1f2937)}.play-btn.svelte-19wbodf{display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;border-radius:50%;background:var(--color-accent, #f97316);color:#fff;border:none;cursor:pointer;flex-shrink:0;padding:0}.play-btn.svelte-19wbodf:disabled{opacity:.4;cursor:not-allowed}.play-btn.svelte-19wbodf:hover:not(:disabled){filter:brightness(1.1)}.wave.svelte-19wbodf{flex:1;height:32px;min-width:0;cursor:pointer}.time.svelte-19wbodf{font-size:11px;color:var(--body-text-color-subdued, #6b7280);font-variant-numeric:tabular-nums;flex-shrink:0}audio.svelte-19wbodf{display:none}.media-page.svelte-outb32{padding:20px 24px;overflow-y:auto;flex:1}.section.svelte-outb32{margin:16px 0}.section-heading.svelte-outb32,.image-section-controls.svelte-outb32{display:flex;align-items:center;gap:8px}.image-section-summary.svelte-outb32{justify-content:space-between;gap:12px}.image-section-controls.svelte-outb32{flex:1;justify-content:flex-end}.media-control.svelte-outb32{display:flex;align-items:center;gap:8px;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.media-control.svelte-outb32 select:where(.svelte-outb32){height:30px;border:1px solid var(--border-color-primary, #d1d5db);border-radius:var(--radius-sm, 4px);background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:var(--text-sm, 12px);padding:0 28px 0 8px}.section-summary.svelte-outb32{display:flex;align-items:center;gap:6px;cursor:pointer;list-style:none;-webkit-user-select:none;user-select:none;padding:4px 0;margin-bottom:8px}.section-summary.svelte-outb32::-webkit-details-marker{display:none}.chevron.svelte-outb32{color:var(--body-text-color-subdued, #6b7280);transform:rotate(-90deg);transition:transform .15s ease;flex-shrink:0}details[open].svelte-outb32>.section-summary:where(.svelte-outb32) .chevron:where(.svelte-outb32){transform:rotate(0)}.section-title.svelte-outb32{font-size:var(--text-lg, 16px);font-weight:600;color:var(--body-text-color, #1f2937)}.media-label.svelte-outb32{font-size:var(--text-sm, 12px);font-weight:500;color:var(--body-text-color, #1f2937);word-break:break-word}.meta.svelte-outb32{display:flex;align-items:center;gap:3px;font-size:var(--text-xs, 11px);color:var(--body-text-color-subdued, #9ca3af);font-variant-numeric:tabular-nums}.meta.svelte-outb32 .run-dot:where(.svelte-outb32){width:8px;height:8px;border-radius:50%;flex-shrink:0;margin:0 2px}.meta-text.svelte-outb32{white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.table-header.svelte-outb32{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:6px}.runs-table.svelte-outb32{width:100%;border-collapse:collapse;font-size:var(--text-md, 14px)}.runs-table.svelte-outb32 th:where(.svelte-outb32){text-align:left;padding:8px 12px;border-bottom:2px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);font-weight:600;font-size:var(--text-sm, 12px);text-transform:uppercase;letter-spacing:.05em}.runs-table.svelte-outb32 td:where(.svelte-outb32){padding:8px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937)}.runs-table.svelte-outb32 tbody:where(.svelte-outb32) tr:where(.svelte-outb32):nth-child(odd){background:var(--table-odd-background-fill, var(--background-fill-primary, white))}.runs-table.svelte-outb32 tbody:where(.svelte-outb32) tr:where(.svelte-outb32):nth-child(2n){background:var(--table-even-background-fill, var(--background-fill-secondary, #f9fafb))}.runs-table.svelte-outb32 tr:where(.svelte-outb32):hover{background:var(--background-fill-secondary, #f3f4f6)}.table-image-frame.svelte-outb32{position:relative;display:inline-flex;width:120px;height:80px;align-items:center;justify-content:center;overflow:hidden;border:0;border-radius:var(--radius-sm, 4px);background:var(--background-fill-secondary, #f3f4f6);color:var(--body-text-color-subdued, #6b7280);cursor:zoom-in;font:inherit;padding:0;text-decoration:none;vertical-align:top}.table-image-placeholder.svelte-outb32{position:absolute;top:0;right:0;bottom:0;left:0;display:grid;place-items:center;font-size:var(--text-xs, 11px)}.table-image-frame.svelte-outb32.image-loaded .table-image-placeholder:where(.svelte-outb32){display:none}.table-image-frame.svelte-outb32.image-failed .table-image-placeholder:where(.svelte-outb32){color:var(--error-text-color, #b91c1c)}.table-image.svelte-outb32{position:relative;z-index:1;max-height:80px;max-width:120px;border-radius:var(--radius-sm, 4px);display:block;object-fit:contain}.table-image-list.svelte-outb32{display:flex;flex-wrap:wrap;gap:4px}.gallery.svelte-outb32{display:grid;grid-template-columns:repeat(auto-fill,minmax(200px,1fr));gap:12px}.gallery-item.svelte-outb32{display:flex;flex-direction:column;gap:6px;padding:8px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);background:var(--background-fill-secondary, #f9fafb);overflow:hidden}.image-frame.svelte-outb32{position:relative;display:block;width:100%;aspect-ratio:4 / 3;overflow:hidden;border:0;border-radius:var(--radius-sm, 4px);background:var(--background-fill-primary, #f3f4f6);color:var(--body-text-color-subdued, #6b7280);cursor:zoom-in;font:inherit;padding:0;text-decoration:none}.image-placeholder.svelte-outb32{position:absolute;top:0;right:0;bottom:0;left:0;display:grid;place-items:center;font-size:var(--text-sm, 12px)}.image-frame.svelte-outb32.image-loaded .image-placeholder:where(.svelte-outb32){display:none}.image-frame.svelte-outb32.image-failed .image-placeholder:where(.svelte-outb32){color:var(--error-text-color, #b91c1c)}.image-frame.svelte-outb32 img:where(.svelte-outb32){position:relative;z-index:1;width:100%;height:100%;display:block;object-fit:contain}.gallery-item.svelte-outb32 video:where(.svelte-outb32){width:100%;display:block;border-radius:var(--radius-sm, 4px)}.audio-gallery-item.svelte-outb32{justify-content:space-between}.caption.svelte-outb32{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #9ca3af)}.image-filter.svelte-outb32{width:min(320px,100%)}.image-filter.svelte-outb32 input:where(.svelte-outb32){width:100%;padding:7px 10px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--input-radius, 8px);background:var(--input-background-fill, white);color:var(--body-text-color, #1f2937);font-family:inherit;font-size:13px;outline:none;transition:border-color .15s,box-shadow .15s}.image-filter.svelte-outb32 input:where(.svelte-outb32):focus{border-color:var(--input-border-color-focus, #fdba74);box-shadow:0 0 0 2px var(--primary-50, #fff7ed)}.image-filter.svelte-outb32 input:where(.svelte-outb32)::placeholder{color:var(--input-placeholder-color, #9ca3af)}.empty-filter-state.svelte-outb32{padding:16px 0;color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 12px)}.image-modal-backdrop.svelte-outb32{position:fixed;top:0;right:0;bottom:0;left:0;z-index:1000;display:flex;align-items:center;justify-content:center;padding:32px;background:#000000bf}.image-modal.svelte-outb32{position:relative;display:flex;max-width:min(92vw,1200px);max-height:92vh;flex-direction:column;overflow:hidden;border-radius:var(--radius-lg, 8px);background:var(--background-fill-primary, white);box-shadow:0 20px 60px #00000059}.image-modal-close.svelte-outb32{position:absolute;top:8px;right:8px;z-index:2;width:32px;height:32px;border:0;border-radius:999px;background:#0000008c;color:#fff;cursor:pointer;font-size:24px;line-height:1}.image-modal-nav.svelte-outb32{position:absolute;top:50%;z-index:2;width:48px;height:48px;border:0;border-radius:999px;background:#00000059;color:#fff;cursor:pointer;font-size:40px;line-height:1;transform:translateY(-50%)}.image-modal-nav.svelte-outb32:hover{background:#0000008c}.image-modal-prev.svelte-outb32{left:12px}.image-modal-next.svelte-outb32{right:12px}.modal-image-frame.svelte-outb32{position:relative;display:grid;min-width:min(70vw,720px);min-height:min(65vh,520px);place-items:center;overflow:hidden;background:var(--background-fill-secondary, #f3f4f6);color:var(--body-text-color-subdued, #6b7280)}.modal-image-placeholder.svelte-outb32{position:absolute;top:0;right:0;bottom:0;left:0;display:grid;place-items:center;font-size:var(--text-sm, 12px)}.modal-image-frame.svelte-outb32.image-loaded .modal-image-placeholder:where(.svelte-outb32){display:none}.modal-image-frame.svelte-outb32.image-failed .modal-image-placeholder:where(.svelte-outb32){color:var(--error-text-color, #b91c1c)}.modal-image-frame.svelte-outb32 img:where(.svelte-outb32){position:relative;z-index:1;max-width:100%;max-height:calc(92vh - 96px);object-fit:contain}.image-modal-info.svelte-outb32{display:flex;flex-direction:column;gap:4px;padding:10px 14px 12px;text-align:center}.image-modal-title.svelte-outb32{font-size:var(--text-md, 14px);font-weight:600;color:var(--body-text-color, #1f2937)}.image-modal-caption.svelte-outb32{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.image-modal-meta.svelte-outb32{justify-content:center}.image-modal-count.svelte-outb32{margin-left:8px}.table-section.svelte-outb32{margin-bottom:16px;overflow-x:auto}.pagination-row.svelte-outb32{display:flex;justify-content:center;align-items:center;gap:12px;margin-top:12px;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.load-more-button.svelte-outb32{height:30px;border:1px solid var(--border-color-primary, #d1d5db);border-radius:var(--radius-sm, 4px);background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:var(--text-sm, 12px);font-weight:500;padding:0 10px;cursor:pointer}.load-more-button.svelte-outb32:hover{background:var(--background-fill-secondary, #f9fafb)}.empty-state.svelte-outb32{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-outb32 h2:where(.svelte-outb32){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-outb32 p:where(.svelte-outb32){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-outb32 pre:where(.svelte-outb32){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-outb32 code:where(.svelte-outb32){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-outb32 pre:where(.svelte-outb32) code:where(.svelte-outb32){background:none;padding:0}.reports-page.svelte-iufsej{padding:20px 24px;overflow-y:auto;flex:1}.controls.svelte-iufsej{display:flex;gap:16px;margin-bottom:16px;flex-wrap:wrap;align-items:flex-end}.control.svelte-iufsej{min-width:200px}.filter-pills.svelte-iufsej{display:flex;gap:4px}.pill.svelte-iufsej{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-xxl, 22px);padding:4px 12px;font-size:var(--text-sm, 12px);background:var(--background-fill-secondary, #f9fafb);color:var(--body-text-color-subdued, #6b7280);cursor:pointer;transition:background-color .15s,color .15s}.pill.svelte-iufsej:hover{background:var(--neutral-100, #f3f4f6)}.pill.active.svelte-iufsej{background:var(--color-accent, #f97316);color:#fff;border-color:var(--color-accent, #f97316)}.empty-state.svelte-iufsej{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-iufsej h2:where(.svelte-iufsej){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-iufsej p:where(.svelte-iufsej){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-iufsej pre:where(.svelte-iufsej){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-iufsej code:where(.svelte-iufsej){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-iufsej pre:where(.svelte-iufsej) code:where(.svelte-iufsej){background:none;padding:0}.alerts-table.svelte-iufsej{width:100%;border-collapse:collapse;font-size:var(--text-md, 14px)}.alerts-table.svelte-iufsej th:where(.svelte-iufsej){text-align:left;padding:8px 12px;border-bottom:2px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);font-weight:600;font-size:var(--text-sm, 12px);text-transform:uppercase;letter-spacing:.05em}.alerts-table.svelte-iufsej td:where(.svelte-iufsej){padding:8px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937)}.alerts-table.svelte-iufsej tbody:where(.svelte-iufsej) tr:where(.svelte-iufsej):nth-child(odd){background:var(--table-odd-background-fill, var(--background-fill-primary, white))}.alerts-table.svelte-iufsej tbody:where(.svelte-iufsej) tr:where(.svelte-iufsej):nth-child(2n){background:var(--table-even-background-fill, var(--background-fill-secondary, #f9fafb))}.alerts-table.svelte-iufsej tr:where(.svelte-iufsej):hover{background:var(--background-fill-secondary, #f3f4f6)}.section-title.svelte-iufsej{font-size:16px;font-weight:700;margin:0 0 12px;color:var(--body-text-color, #1f2937)}.reports-section.svelte-iufsej,.alerts-section.svelte-iufsej{margin-bottom:32px}.report-card.svelte-iufsej{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);padding:16px 20px;margin-bottom:12px;background:var(--background-fill-primary, white)}.report-meta.svelte-iufsej{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280);margin-bottom:8px}.report-content.svelte-iufsej{font-size:var(--text-md, 14px);color:var(--body-text-color, #1f2937);line-height:1.6}.report-content.svelte-iufsej h2{font-size:18px;font-weight:700;margin:0 0 8px}.report-content.svelte-iufsej h3{font-size:16px;font-weight:600;margin:12px 0 6px}.report-content.svelte-iufsej h4{font-size:14px;font-weight:600;margin:10px 0 4px}.report-content.svelte-iufsej code{background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.report-content.svelte-iufsej ul{margin:4px 0;padding-left:20px}.report-content.svelte-iufsej li{margin:2px 0}.report-content.svelte-iufsej p{margin:6px 0}.filter-empty.svelte-iufsej{color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-md, 14px)}.runs-page.svelte-1yb6d54{padding:20px 24px;overflow-y:auto;flex:1}.empty-state.svelte-1yb6d54{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-1yb6d54 h2:where(.svelte-1yb6d54){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-1yb6d54 p:where(.svelte-1yb6d54){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-1yb6d54 pre:where(.svelte-1yb6d54){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-1yb6d54 code:where(.svelte-1yb6d54){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-1yb6d54 pre:where(.svelte-1yb6d54) code:where(.svelte-1yb6d54){background:none;padding:0}.filter-count-row.svelte-1yb6d54{margin-bottom:12px}.filter-count.svelte-1yb6d54{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.runs-table.svelte-1yb6d54{width:100%;border-collapse:collapse;font-size:var(--text-md, 14px)}.runs-table.svelte-1yb6d54 th:where(.svelte-1yb6d54){text-align:left;padding:8px 12px;border-bottom:2px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);font-weight:600;font-size:var(--text-sm, 12px);text-transform:uppercase;letter-spacing:.05em}.runs-table.svelte-1yb6d54 td:where(.svelte-1yb6d54){padding:8px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937)}.runs-table.svelte-1yb6d54 tbody:where(.svelte-1yb6d54) tr:where(.svelte-1yb6d54):nth-child(odd){background:var(--table-odd-background-fill, var(--background-fill-primary, white))}.runs-table.svelte-1yb6d54 tbody:where(.svelte-1yb6d54) tr:where(.svelte-1yb6d54):nth-child(2n){background:var(--table-even-background-fill, var(--background-fill-secondary, #f9fafb))}.runs-table.svelte-1yb6d54 tr:where(.svelte-1yb6d54):hover{background:var(--background-fill-secondary, #f3f4f6)}.run-name-cell.svelte-1yb6d54{font-weight:500}.run-name-with-dot.svelte-1yb6d54{display:inline-flex;align-items:center;gap:8px;max-width:100%}.run-dot.svelte-1yb6d54{width:10px;height:10px;border-radius:50%;flex-shrink:0}.link-btn.svelte-1yb6d54{background:none;border:none;color:var(--color-accent, #f97316);cursor:pointer;font:inherit;font-weight:500;padding:0;text-align:left}.link-btn.svelte-1yb6d54:hover{text-decoration:underline}.rename-input.svelte-1yb6d54{font:inherit;padding:2px 6px;border:1px solid var(--color-accent, #f97316);border-radius:var(--radius-sm, 4px);outline:none;width:100%}.actions-wrap.svelte-1yb6d54{display:flex;gap:4px;align-items:center}.action-btn.svelte-1yb6d54{background:none;border:1px solid transparent;color:var(--body-text-color-subdued, #6b7280);cursor:pointer;padding:4px;border-radius:var(--radius-sm, 4px);display:flex;align-items:center}.action-btn.svelte-1yb6d54:hover{background:var(--background-fill-secondary, #f9fafb);border-color:var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937)}.delete-btn.svelte-1yb6d54:hover{color:#dc2626;border-color:#fecaca;background:#fef2f2}.action-btn.svelte-1yb6d54:disabled{opacity:.45;cursor:not-allowed;pointer-events:none}.artifact-counts.svelte-1yb6d54{display:inline-flex;gap:6px}.art-count.svelte-1yb6d54{display:inline-flex;align-items:center;gap:3px;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280);background:transparent;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:9px;padding:1px 8px;white-space:nowrap}.art-none.svelte-1yb6d54{color:var(--body-text-color-subdued, #9ca3af)}.indent.svelte-1l68cu5{display:flex;align-self:stretch;flex-shrink:0}.indent-guide.svelte-1l68cu5{width:16px;align-self:stretch;position:relative}.indent-guide.svelte-1l68cu5:before{content:"";position:absolute;left:6px;top:0;bottom:0;border-left:1px solid var(--border-color-primary, #e5e7eb)}.version-detail.svelte-pa6cr{border-top:1px solid var(--border-color-primary, #e5e7eb);padding:10px 14px 12px;background:var(--background-fill-secondary, #f9fafb)}.panel.svelte-pa6cr{padding:4px 4px 24px}.panel-header.svelte-pa6cr{border-bottom:1px solid var(--border-color-primary, #e5e7eb);padding-bottom:14px;margin-bottom:16px}.title-row.svelte-pa6cr{display:flex;align-items:center;flex-wrap:wrap;gap:8px}.art-name.svelte-pa6cr{font-size:18px;font-weight:700;color:var(--body-text-color, #1f2937);margin:0;word-break:break-word}.ver-badge.svelte-pa6cr{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:var(--text-sm, 12px);font-weight:600;color:var(--body-text-color-subdued, #6b7280);background:var(--background-fill-secondary, #f3f4f6);border-radius:var(--radius-sm, 4px);padding:2px 7px}.fact-row.svelte-pa6cr{display:flex;align-items:center;flex-wrap:wrap;gap:6px;margin-top:8px}.fact.svelte-pa6cr{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.type-chip.svelte-pa6cr{text-transform:uppercase;letter-spacing:.04em;font-weight:600}.dot.svelte-pa6cr{color:var(--body-text-color-subdued, #9ca3af)}.use-snippet.svelte-pa6cr{display:flex;align-items:center;gap:8px;margin-top:12px;background:var(--background-fill-secondary, #f9fafb);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);padding:6px 6px 6px 10px;width:fit-content;max-width:min(480px,100%);overflow:hidden}.use-snippet.svelte-pa6cr code:where(.svelte-pa6cr){font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:var(--text-sm, 12px);color:var(--body-text-color, #1f2937);white-space:nowrap;overflow-x:auto;flex:1 1 auto}.tok-mod.svelte-pa6cr{color:var(--body-text-color, #1f2937)}.tok-fn.svelte-pa6cr{color:#8957e5}.tok-str.svelte-pa6cr{color:#1a7f37}.tok-punc.svelte-pa6cr{color:var(--body-text-color-subdued, #6b7280)}.copy-btn.svelte-pa6cr{flex-shrink:0;border:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, #fff);color:var(--body-text-color, #374151);border-radius:var(--radius-sm, 4px);padding:3px 10px;font-size:var(--text-xs, 11px);cursor:pointer}.copy-btn.svelte-pa6cr:hover{border-color:var(--color-accent, #f97316);color:var(--color-accent, #f97316)}.copy-btn.small.svelte-pa6cr{padding:1px 8px}.detail-grid.svelte-pa6cr{display:grid;grid-template-columns:max-content 1fr;gap:6px 16px;margin-bottom:10px;align-items:start}.detail-key.svelte-pa6cr{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.detail-val.svelte-pa6cr{font-size:var(--text-sm, 12px);color:var(--body-text-color, #1f2937);word-break:break-word}.digest-val.svelte-pa6cr{display:flex;align-items:center;gap:8px}.digest-text.svelte-pa6cr{word-break:break-all}.mono.svelte-pa6cr{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}.run-link.svelte-pa6cr{background:none;border:none;padding:0;font-size:var(--text-sm, 12px);color:var(--color-accent, #f97316);cursor:pointer;text-align:left}.run-link.svelte-pa6cr:hover{text-decoration:underline}.meta-grid.svelte-pa6cr{display:grid;grid-template-columns:max-content 1fr;column-gap:16px;row-gap:0;align-items:stretch}.meta-key-cell.svelte-pa6cr{display:flex;align-items:stretch;min-width:0}.meta-grid.svelte-pa6cr .detail-val:where(.svelte-pa6cr){align-self:center;padding:3px 0}.meta-chevron-spacer.svelte-pa6cr{display:inline-block;width:16px;flex-shrink:0;align-self:center}.meta-leaf-key.svelte-pa6cr{align-self:center;padding:3px 0}.meta-key-row.svelte-pa6cr{display:inline-flex;align-items:center;align-self:center;background:none;border:none;padding:3px 0;margin:0;cursor:pointer;font:inherit;color:var(--body-text-color, #1f2937);text-align:left}.meta-chevron.svelte-pa6cr{display:inline-flex;align-items:center;justify-content:center;width:12px;height:12px;margin-right:4px;flex-shrink:0;color:var(--body-text-color-subdued, #9ca3af);transition:transform .15s}.meta-chevron.open.svelte-pa6cr{transform:rotate(90deg)}.meta-key-label.svelte-pa6cr{font-weight:400;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.meta-key-row.svelte-pa6cr:hover .meta-key-label:where(.svelte-pa6cr){color:var(--color-accent, #f97316)}.meta-node-count.svelte-pa6cr{margin-left:8px;font-size:var(--text-xs, 10px);font-weight:500;color:var(--body-text-color-subdued, #9ca3af)}.meta-preview.svelte-pa6cr{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:var(--text-xs, 11px);color:var(--body-text-color-subdued, #9ca3af);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.file-table.svelte-pa6cr{display:flex;flex-direction:column}.file-entry.svelte-pa6cr{display:flex;align-items:center;gap:12px;padding:6px 8px;margin:0 -8px;border-radius:var(--radius-sm, 4px);border-top:1px solid var(--border-color-primary, #e5e7eb);color:inherit;text-decoration:none;cursor:pointer}.file-entry.svelte-pa6cr:first-child{border-top:none}.file-entry.svelte-pa6cr:hover{background:var(--background-fill-secondary, #f9fafb);border-top-color:transparent}.spacer.svelte-pa6cr{flex:1 1 auto}.file-path.svelte-pa6cr{font-size:var(--text-sm, 12px);color:var(--body-text-color, #1f2937);word-break:break-all}.file-digest.svelte-pa6cr{font-size:var(--text-xs, 11px);color:var(--body-text-color-subdued, #9ca3af);white-space:nowrap;flex-shrink:0;text-align:right;min-width:88px}.file-size.svelte-pa6cr{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280);white-space:nowrap;flex-shrink:0;text-align:right;min-width:56px}.download-icon.svelte-pa6cr{display:flex;align-items:center;justify-content:center;width:20px;height:20px;flex-shrink:0;color:var(--body-text-color-subdued, #9ca3af);transition:color .15s}.file-entry.svelte-pa6cr:hover .download-icon:where(.svelte-pa6cr){color:var(--color-accent, #f97316)}.status.svelte-pa6cr{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280);padding:4px 0}.alias-pill.svelte-pa6cr{font-size:var(--text-xs, 11px);padding:1px 7px;border-radius:9px;border:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);background:var(--background-fill-secondary, #f3f4f6);white-space:nowrap}.alias-pill.latest.svelte-pa6cr{color:var(--color-accent, #f97316);border-color:var(--color-accent, #f97316);background:transparent}.run-detail-page.svelte-1bpgsx2{padding:20px 24px;overflow-y:auto;flex:1}.back-link.svelte-1bpgsx2{display:inline-flex;align-items:center;gap:6px;margin:0 0 12px;padding:0;border:0;background:none;color:var(--body-text-color-subdued, #6b7280);font:inherit;font-size:var(--text-sm, 12px);font-weight:500;cursor:pointer}.back-link.svelte-1bpgsx2:hover{color:var(--body-text-color, #1f2937);text-decoration:underline}.detail-card.svelte-1bpgsx2{background:var(--background-fill-primary, white);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);padding:24px;max-width:800px}.detail-card.svelte-1bpgsx2 h2:where(.svelte-1bpgsx2){color:var(--body-text-color, #1f2937);margin:0 0 16px;font-size:var(--text-xl, 22px)}.detail-card.svelte-1bpgsx2 h3:where(.svelte-1bpgsx2){color:var(--body-text-color, #1f2937);margin:20px 0 8px;font-size:var(--text-lg, 16px)}.detail-grid.svelte-1bpgsx2{display:grid;grid-template-columns:repeat(auto-fill,minmax(200px,1fr));gap:12px}.detail-item.svelte-1bpgsx2{display:flex;flex-direction:column;gap:2px}.detail-label.svelte-1bpgsx2{font-size:var(--text-xs, 10px);font-weight:600;color:var(--body-text-color-subdued, #9ca3af);text-transform:uppercase}.detail-value.svelte-1bpgsx2{font-size:var(--text-md, 14px);color:var(--body-text-color, #1f2937)}.config-block.svelte-1bpgsx2{background:var(--background-fill-secondary, #f9fafb);padding:12px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:var(--text-sm, 12px);color:var(--body-text-color, #1f2937);overflow-x:auto}.artifact-links.svelte-1bpgsx2{display:flex;flex-direction:column;gap:4px}.artifact-entry.svelte-1bpgsx2{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);overflow:hidden}.artifact-row.svelte-1bpgsx2{display:flex;align-items:center}.row-toggle.svelte-1bpgsx2{display:flex;align-items:center;gap:12px;flex:1;min-width:0;text-align:left;background:none;border:none;padding:8px 12px;cursor:pointer}.row-toggle.svelte-1bpgsx2:hover{background:var(--background-fill-secondary, #f9fafb)}.open-btn.svelte-1bpgsx2{flex-shrink:0;display:flex;align-items:center;justify-content:center;width:30px;height:30px;margin-right:6px;border:none;background:none;color:var(--body-text-color-subdued, #9ca3af);border-radius:var(--radius-sm, 4px);cursor:pointer;transition:color .15s,background-color .15s}.open-btn.svelte-1bpgsx2:hover{color:var(--color-accent, #f97316);background:var(--background-fill-secondary, #f9fafb)}.chevron.svelte-1bpgsx2{flex-shrink:0;display:inline-block;color:var(--body-text-color, #1f2937);font-size:14px;transition:transform .15s;transform:rotate(-90deg)}.chevron.open.svelte-1bpgsx2{transform:none}.art-name.svelte-1bpgsx2{font-weight:600;color:var(--body-text-color, #1f2937);font-size:var(--text-md, 14px)}.art-ver.svelte-1bpgsx2{font-weight:400;color:var(--body-text-color-subdued, #6b7280);font-family:ui-monospace,SFMono-Regular,Menlo,monospace}.art-type.svelte-1bpgsx2{font-size:var(--text-xs, 11px);text-transform:uppercase;letter-spacing:.04em;color:var(--body-text-color-subdued, #6b7280);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:9px;padding:1px 8px}.art-size.svelte-1bpgsx2{margin-left:auto;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-1bpgsx2{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-1bpgsx2 h2:where(.svelte-1bpgsx2){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-1bpgsx2 p:where(.svelte-1bpgsx2){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-1bpgsx2 pre:where(.svelte-1bpgsx2){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-1bpgsx2 code:where(.svelte-1bpgsx2){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-1bpgsx2 pre:where(.svelte-1bpgsx2) code:where(.svelte-1bpgsx2){background:none;padding:0}.files-page.svelte-1xvfk9n{padding:20px 24px;overflow-y:auto;flex:1}.page-title.svelte-1xvfk9n{color:var(--body-text-color, #1f2937);font-size:16px;font-weight:700;margin:0 0 4px}.page-subtitle.svelte-1xvfk9n{color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 12px);margin:0 0 16px}.file-list.svelte-1xvfk9n{display:flex;flex-direction:column;gap:4px}.file-item.svelte-1xvfk9n{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);background:var(--background-fill-primary, white);overflow:hidden}.file-item.expanded.svelte-1xvfk9n{border-color:var(--color-accent, #f97316)}.file-row.svelte-1xvfk9n{display:flex;align-items:center;justify-content:space-between;padding:10px 14px;gap:12px}.file-name.svelte-1xvfk9n{display:flex;align-items:center;gap:8px;background:none;border:none;padding:0;font-size:var(--text-md, 14px);color:var(--body-text-color, #1f2937);cursor:pointer;text-align:left}.file-name.svelte-1xvfk9n:hover{color:var(--color-accent, #f97316)}.file-icon.svelte-1xvfk9n{font-size:14px;flex-shrink:0}.file-actions.svelte-1xvfk9n{display:flex;align-items:center;gap:12px;flex-shrink:0}.file-size.svelte-1xvfk9n{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280);white-space:nowrap}.download-btn.svelte-1xvfk9n{display:flex;align-items:center;justify-content:center;width:28px;height:28px;border-radius:var(--radius-md, 6px);color:var(--body-text-color-subdued, #6b7280);transition:background-color .15s,color .15s}.download-btn.svelte-1xvfk9n:hover{background:var(--background-fill-secondary, #f3f4f6);color:var(--body-text-color, #1f2937)}.file-preview.svelte-1xvfk9n{border-top:1px solid var(--border-color-primary, #e5e7eb);padding:12px 14px;background:var(--background-fill-secondary, #f9fafb)}.preview-code.svelte-1xvfk9n{margin:0;font-size:12px;line-height:1.5;max-height:400px;overflow:auto;white-space:pre-wrap;word-break:break-all;color:var(--body-text-color, #1f2937)}.preview-loading.svelte-1xvfk9n,.preview-unavailable.svelte-1xvfk9n{color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 12px);padding:8px 0}.preview-unavailable.svelte-1xvfk9n a:where(.svelte-1xvfk9n){color:var(--color-accent, #f97316);text-decoration:none}.preview-unavailable.svelte-1xvfk9n a:where(.svelte-1xvfk9n):hover{text-decoration:underline}.empty-state.svelte-1xvfk9n{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-1xvfk9n h2:where(.svelte-1xvfk9n){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-1xvfk9n p:where(.svelte-1xvfk9n){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-1xvfk9n pre:where(.svelte-1xvfk9n){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-1xvfk9n code:where(.svelte-1xvfk9n){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-1xvfk9n pre:where(.svelte-1xvfk9n) code:where(.svelte-1xvfk9n){background:none;padding:0}.artifacts-sidebar.svelte-coehlr{width:300px;flex-shrink:0;display:flex;flex-direction:column;border-right:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, #fff);overflow:hidden}.tree-header.svelte-coehlr{padding:16px 16px 10px;flex-shrink:0}.tree-search.svelte-coehlr{margin-top:14px}.search-label.svelte-coehlr{display:block;font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280);margin-bottom:6px}.search-box.svelte-coehlr{position:relative;display:flex;align-items:center}.search-icon.svelte-coehlr{position:absolute;left:10px;color:var(--body-text-color-subdued, #9ca3af);pointer-events:none}.search-box.svelte-coehlr input:where(.svelte-coehlr){width:100%;padding:6px 26px 6px 30px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);background:var(--background-fill-secondary, #f9fafb);color:var(--body-text-color, #1f2937);font-size:var(--text-sm, 13px);outline:none}.search-box.svelte-coehlr input:where(.svelte-coehlr):focus{border-color:var(--color-accent, #f97316)}.clear-search.svelte-coehlr{position:absolute;right:8px;border:none;background:none;color:var(--body-text-color-subdued, #9ca3af);font-size:18px;line-height:1;cursor:pointer;padding:0 2px}.clear-search.svelte-coehlr:hover{color:var(--body-text-color, #1f2937)}.tree.svelte-coehlr{flex:1;overflow-y:auto;padding:6px 0 12px}.tree-empty.svelte-coehlr{padding:16px 14px;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.tree-row.svelte-coehlr{display:flex;align-items:center;width:100%;min-height:30px;background:none;border:none;cursor:pointer;text-align:left;color:var(--body-text-color, #1f2937);font-size:var(--text-sm, 13px);padding:0 12px;border-radius:0}.tree-row.svelte-coehlr:hover{background:var(--background-fill-secondary, #f3f4f6)}.tree-chevron-spacer.svelte-coehlr{display:inline-block;width:12px;margin-right:6px;flex-shrink:0}.chevron.svelte-coehlr{flex-shrink:0;display:inline-flex;align-items:center;justify-content:center;margin-right:6px;color:var(--body-text-color-subdued, #6b7280);width:12px;height:12px;transition:transform .15s}.chevron.open.svelte-coehlr{transform:rotate(90deg)}.type-label.svelte-coehlr{text-transform:uppercase;letter-spacing:.04em;font-size:var(--text-xs, 11px);font-weight:700;color:var(--body-text-color-subdued, #6b7280)}.artifact-label.svelte-coehlr{font-weight:500;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.version-label.svelte-coehlr{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-weight:600;flex-shrink:0}.version-row.svelte-coehlr .alias-pill:where(.svelte-coehlr){margin-left:6px}.spacer.svelte-coehlr{flex:1 1 auto}.node-count.svelte-coehlr{display:inline-flex;align-items:center;justify-content:center;min-width:18px;height:18px;padding:0 5px;border-radius:9px;background:var(--background-fill-secondary, #f3f4f6);color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-xs, 10px);flex-shrink:0}.version-row.selected.svelte-coehlr{background:var(--background-fill-secondary, #f3f4f6);box-shadow:inset 3px 0 0 var(--color-accent, #f97316)}.version-row.selected.svelte-coehlr .version-label:where(.svelte-coehlr){color:var(--color-accent, #f97316)}.alias-pill.svelte-coehlr{font-size:var(--text-xs, 10px);padding:0 6px;border-radius:9px;border:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);background:var(--background-fill-secondary, #f3f4f6);white-space:nowrap;line-height:16px}.alias-pill.latest.svelte-coehlr{color:var(--color-accent, #f97316);border-color:var(--color-accent, #f97316);background:transparent}.detail-pane.svelte-q8gppg{flex:1;min-width:0;overflow-y:auto;padding:20px 28px}.detail-empty.svelte-q8gppg{color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 13px);padding:12px 0}.empty-state.svelte-q8gppg{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-q8gppg h2:where(.svelte-q8gppg){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-q8gppg p:where(.svelte-q8gppg){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-q8gppg pre:where(.svelte-q8gppg){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-q8gppg code:where(.svelte-q8gppg){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-q8gppg pre:where(.svelte-q8gppg) code:where(.svelte-q8gppg){background:none;padding:0}.settings-page.svelte-1ozf5k3{padding:24px 32px;overflow-y:auto;flex:1}.page-title.svelte-1ozf5k3{color:var(--body-text-color, #1f2937);font-size:18px;font-weight:700;margin:0 0 24px}.two-col.svelte-1ozf5k3{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:32px;align-items:start}@media(max-width:900px){.two-col.svelte-1ozf5k3{grid-template-columns:1fr}}.settings-section.svelte-1ozf5k3{margin-bottom:32px}.section-title.svelte-1ozf5k3{color:var(--body-text-color, #1f2937);font-size:15px;font-weight:600;margin:0 0 4px}.section-desc.svelte-1ozf5k3{color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 12px);margin:0 0 12px;line-height:1.5}.section-desc.svelte-1ozf5k3 code:where(.svelte-1ozf5k3){background:var(--background-fill-secondary, #f3f4f6);padding:1px 5px;border-radius:var(--radius-sm, 3px);font-size:11px}.section-desc.svelte-1ozf5k3 strong:where(.svelte-1ozf5k3){color:var(--color-accent, #f97316)}.theme-switcher.svelte-1ozf5k3{display:inline-flex;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);overflow:hidden}.theme-option.svelte-1ozf5k3{display:inline-flex;align-items:center;gap:6px;padding:8px 20px;border:none;background:var(--background-fill-primary, white);color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-md, 14px);cursor:pointer;transition:all .15s;border-right:1px solid var(--border-color-primary, #e5e7eb)}.theme-option.svelte-1ozf5k3:last-child{border-right:none}.theme-option.svelte-1ozf5k3:hover{color:var(--body-text-color, #1f2937);background:var(--background-fill-secondary, #f9fafb)}.theme-option.selected.svelte-1ozf5k3{background:var(--color-accent, #f97316);color:#fff;font-weight:500}.project-selector.svelte-1ozf5k3{display:flex;align-items:center;gap:10px;margin-bottom:12px}.selector-label.svelte-1ozf5k3{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280);flex-shrink:0}.selector-select.svelte-1ozf5k3{padding:6px 10px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 4px);background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:var(--text-sm, 12px);min-width:160px;cursor:pointer}.selector-select.svelte-1ozf5k3:focus{outline:none;border-color:var(--color-accent, #f97316)}.commands-table.svelte-1ozf5k3{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);overflow:hidden}.command-row.svelte-1ozf5k3{display:flex;align-items:center;gap:16px;padding:10px 14px;border-bottom:1px solid var(--border-color-primary, #e5e7eb)}.command-row.svelte-1ozf5k3:last-child{border-bottom:none}.command-label.svelte-1ozf5k3{width:180px;flex-shrink:0;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.command-value.svelte-1ozf5k3{flex:1;display:flex;align-items:center;gap:8px;min-width:0}.command-value.svelte-1ozf5k3 code:where(.svelte-1ozf5k3){flex:1;font-family:SFMono-Regular,Consolas,Liberation Mono,Menlo,monospace;font-size:12px;color:var(--body-text-color, #1f2937);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.copy-btn.svelte-1ozf5k3{display:flex;align-items:center;justify-content:center;width:26px;height:26px;flex-shrink:0;border:none;background:none;border-radius:var(--radius-md, 4px);color:var(--body-text-color-subdued, #6b7280);cursor:pointer;transition:background-color .15s,color .15s}.copy-btn.svelte-1ozf5k3:hover{background:var(--background-fill-secondary, #f3f4f6);color:var(--body-text-color, #1f2937)}.copy-btn.copied.svelte-1ozf5k3{color:var(--color-accent, #f97316)}.agent-tabs.svelte-1ozf5k3{display:flex;border-bottom:1px solid var(--border-color-primary, #e5e7eb);gap:0;margin-bottom:0}.agent-tab.svelte-1ozf5k3{padding:8px 16px;border:none;background:none;color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 12px);cursor:pointer;border-bottom:2px solid transparent;transition:all .15s;white-space:nowrap}.agent-tab.svelte-1ozf5k3:hover{color:var(--body-text-color, #1f2937)}.agent-tab.active.svelte-1ozf5k3{color:var(--color-accent, #f97316);border-bottom-color:var(--color-accent, #f97316);font-weight:500}.agent-panel.svelte-1ozf5k3{border:1px solid var(--border-color-primary, #e5e7eb);border-top:none;border-radius:0 0 var(--radius-lg, 8px) var(--radius-lg, 8px);padding:16px}.install-block.svelte-1ozf5k3{margin-bottom:16px}.install-label.svelte-1ozf5k3{display:block;font-size:11px;font-weight:500;color:var(--body-text-color-subdued, #6b7280);text-transform:uppercase;letter-spacing:.04em;margin-bottom:6px}.install-cmd.svelte-1ozf5k3{display:flex;align-items:center;gap:8px;background:var(--background-fill-secondary, #f3f4f6);border-radius:var(--radius-md, 4px);padding:8px 10px}.install-cmd.svelte-1ozf5k3 code:where(.svelte-1ozf5k3){flex:1;font-family:SFMono-Regular,Consolas,Liberation Mono,Menlo,monospace;font-size:12px;color:var(--body-text-color, #1f2937);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.example-block.svelte-1ozf5k3{background:var(--background-fill-secondary, #f9fafb);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 4px);padding:12px}.example-header.svelte-1ozf5k3{display:flex;align-items:center;justify-content:space-between;margin-bottom:8px}.example-label.svelte-1ozf5k3{font-size:11px;font-weight:500;color:var(--body-text-color-subdued, #6b7280);text-transform:uppercase;letter-spacing:.04em}.example-text.svelte-1ozf5k3{margin:0;font-size:var(--text-sm, 12px);color:var(--body-text-color, #1f2937);line-height:1.6;font-style:italic}*{margin:0;padding:0;box-sizing:border-box}body{font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif;background:var(--background-fill-primary, #fff);color:var(--body-text-color, #1f2937);font-size:var(--text-md, 14px);-webkit-font-smoothing:antialiased}.app.svelte-1n46o8q{display:flex;height:100vh;overflow:hidden}.main.svelte-1n46o8q{flex:1;display:flex;flex-direction:column;overflow:hidden;min-width:0}.page-content.svelte-1n46o8q{flex:1;overflow:hidden;display:flex;background:var(--bg-primary)}

trackio/frontend/dist/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Trackio Dashboard</title>
+    <link rel="icon" type="image/png" href="/static/trackio/trackio_logo_light.png" />
+    <script type="module" crossorigin src="/assets/index-nILgi7uv.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-m3jgYXoS.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

trackio/frontend/eslint.config.js

@@ -0,0 +1,42 @@
+import js from "@eslint/js";
+import svelte from "eslint-plugin-svelte";
+import svelteParser from "svelte-eslint-parser";
+import globals from "globals";
+
+export default [
+  { ignores: ["dist/**", "node_modules/**"] },
+  {
+    files: ["**/*.js"],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.es2021,
+        $state: "readonly",
+        $derived: "readonly",
+        $effect: "readonly",
+        $props: "readonly",
+        $bindable: "readonly",
+        $inspect: "readonly",
+      },
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      "no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "no-empty": "off",
+    },
+  },
+  {
+    files: ["**/*.svelte"],
+    languageOptions: {
+      parser: svelteParser,
+      globals: { ...globals.browser, ...globals.es2021 },
+    },
+    plugins: { svelte },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...svelte.configs.recommended.rules,
+      "no-unused-vars": ["error", { argsIgnorePattern: "^_", varsIgnorePattern: "^\\$" }],
+      "no-empty": "off",
+    },
+  },
+];

trackio/frontend/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Trackio Dashboard</title>
+    <link rel="icon" type="image/png" href="/static/trackio/trackio_logo_light.png" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

trackio/frontend_config.py

@@ -0,0 +1,175 @@
+import json
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from huggingface_hub.constants import HF_HOME
+
+TRACKIO_USER_HOME = Path(HF_HOME) / "trackio"
+TRACKIO_CONFIG_PATH = TRACKIO_USER_HOME / "config.json"
+BUNDLED_FRONTEND_DIR = Path(__file__).parent / "frontend" / "dist"
+STARTER_FRONTEND_DIR = Path(__file__).parent / "frontend_templates" / "starter"
+
+
+@dataclass(frozen=True)
+class ResolvedFrontend:
+    path: Path
+    source: str
+    is_custom: bool
+    used_fallback: bool = False
+    requested_path: Path | None = None
+
+
+def _normalize_frontend_path(path: str | Path) -> Path:
+    return Path(path).expanduser().resolve()
+
+
+def is_valid_frontend_dir(path: str | Path | None) -> bool:
+    if path is None:
+        return False
+    frontend_dir = _normalize_frontend_path(path)
+    return frontend_dir.is_dir() and (frontend_dir / "index.html").is_file()
+
+
+def _is_empty_directory(path: Path) -> bool:
+    return path.is_dir() and not any(path.iterdir())
+
+
+def _copy_starter_template(destination: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    for child in STARTER_FRONTEND_DIR.iterdir():
+        target = destination / child.name
+        if child.is_dir():
+            shutil.copytree(child, target, dirs_exist_ok=True)
+        else:
+            shutil.copy2(child, target)
+
+
+def _materialize_argument_frontend_dir(candidate: Path) -> bool:
+    existed_before = candidate.exists()
+    if existed_before and not _is_empty_directory(candidate):
+        return False
+
+    _copy_starter_template(candidate)
+    state = "did not exist" if not existed_before else "was empty"
+    print(
+        f"* Trackio frontend directory from argument {state}: {candidate}. "
+        "Copied the starter template into it and serving that directory."
+    )
+    return True
+
+
+def load_trackio_config() -> dict:
+    if not TRACKIO_CONFIG_PATH.is_file():
+        return {}
+    try:
+        data = json.loads(TRACKIO_CONFIG_PATH.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save_trackio_config(config: dict) -> None:
+    TRACKIO_USER_HOME.mkdir(parents=True, exist_ok=True)
+    TRACKIO_CONFIG_PATH.write_text(json.dumps(config, indent=2, sort_keys=True) + "\n")
+
+
+def get_persisted_frontend_dir() -> Path | None:
+    frontend_dir = load_trackio_config().get("frontend_dir")
+    if not frontend_dir:
+        return None
+    return _normalize_frontend_path(frontend_dir)
+
+
+def set_persisted_frontend_dir(path: str | Path) -> Path:
+    frontend_dir = _normalize_frontend_path(path)
+    if not is_valid_frontend_dir(frontend_dir):
+        raise ValueError(
+            f"Invalid frontend directory: {frontend_dir}. Expected a directory containing index.html."
+        )
+    config = load_trackio_config()
+    config["frontend_dir"] = str(frontend_dir)
+    save_trackio_config(config)
+    return frontend_dir
+
+
+def unset_persisted_frontend_dir() -> bool:
+    config = load_trackio_config()
+    if "frontend_dir" not in config:
+        return False
+    del config["frontend_dir"]
+    if config:
+        save_trackio_config(config)
+    elif TRACKIO_CONFIG_PATH.exists():
+        TRACKIO_CONFIG_PATH.unlink()
+    return True
+
+
+def _configured_frontend_candidates(
+    frontend_dir: str | Path | None,
+) -> list[tuple[str, Path]]:
+    candidates: list[tuple[str, Path]] = []
+    if frontend_dir is not None:
+        candidates.append(("argument", _normalize_frontend_path(frontend_dir)))
+    env_dir = os.environ.get("TRACKIO_FRONTEND_DIR")
+    if env_dir:
+        candidates.append(("env", _normalize_frontend_path(env_dir)))
+    persisted_dir = get_persisted_frontend_dir()
+    if persisted_dir is not None:
+        candidates.append(("config", persisted_dir))
+    return candidates
+
+
+def _announce_config_frontend(frontend_dir: Path) -> None:
+    print(
+        f"* Using Trackio custom frontend from config: {frontend_dir}\n"
+        "  Reset with `trackio config unset frontend`."
+    )
+
+
+def resolve_frontend_dir(
+    frontend_dir: str | Path | None = None,
+    *,
+    announce: bool = False,
+) -> ResolvedFrontend:
+    for source, candidate in _configured_frontend_candidates(frontend_dir):
+        if source == "argument":
+            if not candidate.exists() or _is_empty_directory(candidate):
+                _materialize_argument_frontend_dir(candidate)
+
+        if is_valid_frontend_dir(candidate):
+            if source == "config" and announce:
+                _announce_config_frontend(candidate)
+            return ResolvedFrontend(
+                path=candidate,
+                source=source,
+                is_custom=True,
+            )
+        if source == "argument":
+            print(
+                f"* Trackio frontend from {source} is invalid: {candidate}. "
+                f"Falling back to starter template at {STARTER_FRONTEND_DIR}."
+            )
+            return ResolvedFrontend(
+                path=STARTER_FRONTEND_DIR,
+                source="starter",
+                is_custom=True,
+                used_fallback=True,
+                requested_path=candidate,
+            )
+        print(f"* Trackio frontend from {source} is invalid: {candidate}. Ignoring it.")
+
+    if is_valid_frontend_dir(BUNDLED_FRONTEND_DIR):
+        return ResolvedFrontend(
+            path=BUNDLED_FRONTEND_DIR,
+            source="bundled",
+            is_custom=False,
+        )
+
+    return ResolvedFrontend(
+        path=STARTER_FRONTEND_DIR,
+        source="starter",
+        is_custom=True,
+        used_fallback=True,
+    )

trackio/frontend_server.py

@@ -0,0 +1,175 @@
+"""Serves a static frontend alongside the Trackio HTTP API."""
+
+import hashlib
+import json
+import logging
+import re
+from pathlib import Path
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import FileResponse, HTMLResponse, JSONResponse
+from starlette.routing import Mount, Route, get_route_path
+from starlette.staticfiles import StaticFiles
+
+ASSETS_DIR = Path(__file__).parent / "assets"
+
+_logger = logging.getLogger(__name__)
+
+_ABSOLUTE_REF_RE = re.compile(r'(href|src)="(/(?:assets|static/trackio)/[^"]+)"')
+
+_LIVE_RELOAD_SCRIPT = """
+<script>
+(() => {
+  const endpoint = "__TRACKIO_ROOT_PATH__/__trackio/frontend_version";
+  let currentVersion = null;
+
+  async function poll() {
+    try {
+      const response = await fetch(endpoint, { cache: "no-store" });
+      const payload = await response.json();
+      if (currentVersion === null) {
+        currentVersion = payload.version;
+        return;
+      }
+      if (payload.version !== currentVersion) {
+        window.location.reload();
+      }
+    } catch (error) {
+      console.warn("Trackio live reload poll failed", error);
+    }
+  }
+
+  poll();
+  setInterval(poll, 1000);
+})();
+</script>
+""".strip()
+
+
+def _frontend_version(frontend_root: Path) -> str:
+    digest = hashlib.sha256()
+    for path in sorted(frontend_root.rglob("*")):
+        if not path.is_file():
+            continue
+        relative = path.relative_to(frontend_root)
+        digest.update(str(relative).encode("utf-8"))
+        stat = path.stat()
+        digest.update(str(stat.st_mtime_ns).encode("utf-8"))
+        digest.update(str(stat.st_size).encode("utf-8"))
+    return digest.hexdigest()
+
+
+def _inject_live_reload(html: str, root_path: str) -> str:
+    if "/__trackio/frontend_version" in html:
+        return html
+    script = _LIVE_RELOAD_SCRIPT.replace("__TRACKIO_ROOT_PATH__", root_path)
+    if "</body>" in html:
+        return html.replace("</body>", f"{script}\n  </body>")
+    return html + script
+
+
+def _prefix_absolute_refs(html: str, root_path: str) -> str:
+    if not root_path:
+        return html
+    return _ABSOLUTE_REF_RE.sub(
+        lambda m: f'{m.group(1)}="{root_path}{m.group(2)}"', html
+    )
+
+
+def _inject_base_script(html: str, root_path: str) -> str:
+    if not root_path:
+        return html
+    script = f"<script>window.__trackio_base = {json.dumps(root_path)};</script>"
+    if "<head>" in html:
+        return html.replace("<head>", f"<head>\n    {script}", 1)
+    return script + html
+
+
+def _render_index_html(path: Path, root_path: str = "") -> str:
+    html = path.read_text(encoding="utf-8")
+    html = _prefix_absolute_refs(html, root_path)
+    html = _inject_base_script(html, root_path)
+    return _inject_live_reload(html, root_path)
+
+
+def _html_response(path: Path, root_path: str = "") -> HTMLResponse:
+    return HTMLResponse(_render_index_html(path, root_path))
+
+
+class FrontendMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, frontend_root: Path, index_html_path: Path):
+        super().__init__(app)
+        self.frontend_root = frontend_root
+        self.index_html_path = index_html_path
+        self.reserved_prefixes = (
+            "/api/",
+            "/file",
+            "/version",
+            "/artifact_blob/",
+            "/static/trackio",
+            "/__trackio/frontend_version",
+            "/oauth/",
+            "/login/",
+            "/mcp",
+        )
+        self.reserved_exact = {
+            "/api",
+            "/oauth",
+            "/login",
+        }
+
+    async def dispatch(self, request, call_next):
+        if request.method not in {"GET", "HEAD"}:
+            return await call_next(request)
+
+        path = get_route_path(request.scope)
+        if path in self.reserved_exact or path.startswith(self.reserved_prefixes):
+            return await call_next(request)
+
+        root_path = request.scope.get("root_path", "")
+        relative_path = path.lstrip("/")
+        requested_path = (self.frontend_root / relative_path).resolve()
+        if (
+            relative_path
+            and requested_path.is_file()
+            and requested_path.is_relative_to(self.frontend_root)
+        ):
+            if requested_path.suffix.lower() == ".html":
+                return _html_response(requested_path, root_path)
+            return FileResponse(requested_path)
+
+        return _html_response(self.index_html_path, root_path)
+
+
+def mount_frontend(app, frontend_dir: str | Path):
+    frontend_root = Path(frontend_dir).resolve()
+    if not frontend_root.exists():
+        _logger.warning(
+            "Trackio dashboard UI was not mounted: %s is missing. "
+            "Build the frontend or provide a custom frontend directory.",
+            frontend_root,
+        )
+        return
+
+    index_html_path = frontend_root / "index.html"
+    if not index_html_path.exists():
+        _logger.warning(
+            "Trackio dashboard UI was not mounted: %s is missing.",
+            index_html_path,
+        )
+        return
+
+    async def frontend_version(_request):
+        return JSONResponse({"version": _frontend_version(frontend_root)})
+
+    static_assets = StaticFiles(directory=str(ASSETS_DIR))
+
+    app.add_middleware(
+        FrontendMiddleware,
+        frontend_root=frontend_root,
+        index_html_path=index_html_path,
+    )
+    app.routes.append(Mount("/static/trackio", app=static_assets))
+    app.routes.append(
+        Route("/__trackio/frontend_version", frontend_version, methods=["GET"])
+    )

trackio/frontend_templates/logbook/index.html

@@ -0,0 +1,54 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Trackio Logbook</title>
+    <link rel="stylesheet" href="./logbook.css" />
+  </head>
+  <body>
+    <div id="app">
+      <aside id="sidebar">
+        <div id="book-head">
+          <img id="book-wordmark" src="./trackio-wordmark-dark.png" alt="" />
+          <div id="book-title" class="sr-only">Logbook</div>
+        </div>
+        <nav id="tree"></nav>
+        <div id="sidebar-foot" hidden>
+          <button id="connect-btn" type="button">
+            <span class="ico">ⓘ</span> Collaborate with your agent
+          </button>
+        </div>
+      </aside>
+      <main id="content">
+        <div id="page"></div>
+      </main>
+    </div>
+
+    <div id="modal" hidden>
+      <div class="modal-backdrop"></div>
+      <div class="modal-card" role="dialog" aria-modal="true">
+        <div class="modal-head">
+          <div class="modal-title">
+            <img class="modal-logo" src="./trackio-logo.png" alt="" />
+            Collaborate with your agent
+          </div>
+          <div class="modal-actions">
+            <button id="copy-agent" class="btn">Copy for agent</button>
+            <button id="modal-close" class="btn icon" aria-label="Close">×</button>
+          </div>
+        </div>
+        <div class="modal-body">
+          <p class="modal-intro">
+            Point your coding agent at this logbook. It reads a compact,
+            token-efficient version — and if you've given it write access to this
+            Space, it can add findings that sync back automatically.
+          </p>
+          <ol id="connect-steps"></ol>
+        </div>
+      </div>
+    </div>
+
+    <script src="./logbook.js"></script>
+  </body>
+</html>

trackio/frontend_templates/logbook/logbook.css

@@ -0,0 +1,1602 @@
+:root {
+  --bg: #ffffff;
+  --paper: #fdfcf9;
+  --panel: #ffffff;
+  --ink: #1f2937;
+  --muted: #6b7280;
+  --line: #e5e7eb;
+  --accent: #f97316;
+  --accent-strong: #ea580c;
+  --accent-soft: #fff7ed;
+  --accent-line: rgba(249, 115, 22, 0.16);
+  --grid-line: rgba(31, 41, 55, 0.045);
+  --code-bg: #f3f4f6;
+  --radius: 12px;
+  --serif: ui-serif, "Iowan Old Style", "Palatino Linotype", Georgia, serif;
+  --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial,
+    sans-serif;
+  --mono: "SFMono-Regular", "Cascadia Mono", "JetBrains Mono", Menlo, Consolas,
+    ui-monospace, monospace;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  background: var(--bg);
+  color: var(--ink);
+  font-family: var(--sans);
+  font-size: 13px;
+  line-height: 1.65;
+  -webkit-font-smoothing: antialiased;
+}
+
+#app {
+  display: flex;
+  min-height: 100vh;
+}
+
+/* ---- sidebar (composition-book cover) ---- */
+#sidebar {
+  width: 280px;
+  flex: 0 0 280px;
+  background: #17181c;
+  color: #e7e7ea;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  overflow-y: auto;
+  padding: 22px 16px;
+  display: flex;
+  flex-direction: column;
+}
+
+#book-head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px;
+  margin-bottom: 12px;
+  border-radius: 10px;
+  cursor: pointer;
+  transition: background 0.12s;
+}
+#book-head:hover {
+  background: rgba(255, 255, 255, 0.05);
+}
+#book-wordmark {
+  width: 154px;
+  height: auto;
+  object-fit: contain;
+}
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+#tree {
+  flex: 1;
+  padding-top: 8px;
+}
+
+#tree a {
+  display: block;
+  padding: 6px 10px;
+  border-radius: 8px;
+  color: #c3c4cb;
+  text-decoration: none;
+  font-size: 14px;
+  transition: background 0.12s, color 0.12s;
+}
+
+#tree a:hover {
+  background: rgba(255, 255, 255, 0.06);
+  color: #ffffff;
+}
+
+#tree a.active {
+  background: rgba(249, 115, 22, 0.16);
+  color: #fdba74;
+  font-weight: 600;
+}
+
+#tree a .tree-mark {
+  color: #6b6d76;
+}
+
+#tree a:hover .tree-mark,
+#tree a.active .tree-mark {
+  color: inherit;
+  opacity: 0.6;
+}
+
+#tree .depth-1 {
+  padding-left: 22px;
+}
+#tree .depth-2 {
+  padding-left: 34px;
+}
+#tree .depth-3 {
+  padding-left: 46px;
+}
+
+
+/* ---- content ---- */
+#content {
+  flex: 1;
+  min-width: 0;
+  padding: 48px 40px 120px;
+  background-color: var(--paper);
+  background-image:
+    linear-gradient(var(--grid-line) 1px, transparent 1px),
+    linear-gradient(90deg, var(--grid-line) 1px, transparent 1px);
+  background-size: 26px 26px;
+  background-position: center top;
+}
+
+#page {
+  width: 100%;
+  min-width: 0;
+  max-width: 1052px;
+  margin: 0 auto;
+}
+
+.page-section {
+  scroll-margin-top: 40px;
+  padding: 0 0 35px;
+  margin: 0 0 32px;
+}
+
+.page-section:last-child {
+  margin-bottom: 0;
+}
+
+.page-layout {
+  display: grid;
+  grid-template-columns: minmax(0, 760px) 248px;
+  gap: 44px;
+  align-items: start;
+}
+
+.page-body {
+  min-width: 0;
+}
+
+.resource-anchor {
+  display: block;
+  height: 0;
+  overflow: hidden;
+}
+
+/* ---- pinned notes ---- */
+.pinned-notes {
+  margin: 30px 0 0;
+}
+.pinned-notes-list .cell {
+  margin: 0;
+  border-color: rgba(249, 115, 22, 0.55);
+}
+.pinned-notes-list .cell + .cell {
+  margin-top: 12px;
+}
+.cell.pinned-source {
+  border-color: rgba(249, 115, 22, 0.55);
+}
+.book-intro.has-pinned-notes {
+  border-bottom: none;
+  padding-bottom: 22px;
+  margin-bottom: 30px;
+}
+.book-intro.book-intro-tight {
+  border-bottom: none;
+  padding-bottom: 4px;
+  margin-bottom: 20px;
+}
+
+#page h1 {
+  font-family: var(--serif);
+  font-size: 34px;
+  line-height: 1.15;
+  letter-spacing: -0.02em;
+  margin: 0 0 8px;
+  overflow-wrap: anywhere;
+}
+
+#page .page-section:not(.book-intro) h1 {
+  font-size: 26px;
+}
+
+#page h2 {
+  font-family: var(--serif);
+  font-size: 24px;
+  margin: 36px 0 10px;
+}
+
+#page h3 {
+  font-size: 17px;
+  font-weight: 700;
+  margin: 26px 0 2px;
+  letter-spacing: -0.01em;
+}
+
+#page h3::before {
+  content: "";
+  display: inline-block;
+  width: 7px;
+  height: 7px;
+  border-radius: 2px;
+  background: var(--accent);
+  margin-right: 10px;
+  vertical-align: middle;
+  transform: translateY(-1px);
+}
+
+#page p {
+  margin: 10px 0;
+}
+
+#page blockquote {
+  margin: 14px 0;
+  padding: 2px 16px;
+  border-left: 3px solid #fdba74;
+  color: var(--muted);
+}
+
+#page hr {
+  display: none;
+}
+
+#page code {
+  font-family: var(--mono);
+  font-size: 0.86em;
+  background: var(--code-bg);
+  padding: 2px 6px;
+  border-radius: 6px;
+}
+
+#page pre {
+  max-width: 100%;
+  background: var(--code-bg);
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  padding: 14px 16px;
+  overflow-x: auto;
+}
+#page pre code {
+  background: none;
+  padding: 0;
+  font-size: 11.5px;
+}
+
+/* ---- code blocks + collapsible accordion ---- */
+#page pre.hl {
+  background: #17181c;
+  border: none;
+  color: #e7e7ea;
+  font-size: 13px;
+  line-height: 1.58;
+}
+#page pre.hl code {
+  color: inherit;
+  font-family: var(--mono);
+}
+.code-accordion {
+  border: 1px solid rgba(249, 115, 22, 0.2);
+  border-radius: 8px;
+  overflow: hidden;
+  margin: 12px 0;
+  background: #17181c;
+}
+.code-accordion summary {
+  list-style: none;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  padding: 9px 12px;
+  font-family: var(--mono);
+  font-size: 11.5px;
+  font-weight: 700;
+  color: #e7e7ea;
+  background: #1e2027;
+  user-select: none;
+  overflow-wrap: anywhere;
+}
+.code-accordion summary::-webkit-details-marker {
+  display: none;
+}
+.code-accordion summary::after {
+  content: "▸";
+  margin-left: auto;
+  color: var(--accent);
+  transition: transform 0.12s;
+  transform: rotate(180deg);
+}
+.code-accordion[open] summary::after {
+  transform: rotate(90deg);
+}
+.code-accordion .code-ico {
+  color: var(--accent);
+  font-weight: 700;
+}
+.code-accordion pre.hl {
+  margin: 0;
+  border-radius: 0;
+  border: none;
+  border-top: 1px solid rgba(249, 115, 22, 0.16);
+}
+.tok-comment {
+  color: #7a7d87;
+  font-style: italic;
+}
+.tok-string {
+  color: #a5d6a7;
+}
+.tok-keyword {
+  color: #fdba74;
+}
+.tok-number {
+  color: #7fd0e0;
+}
+
+#page a {
+  color: var(--accent);
+}
+
+#page ul {
+  padding-left: 20px;
+}
+
+.ts {
+  font-family: var(--mono);
+  font-size: 12px;
+  color: var(--muted);
+  background: none;
+  padding: 0;
+}
+
+/* ---- notebook-style cells ---- */
+.cell {
+  max-width: 100%;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: rgba(255, 255, 255, 0.86);
+  margin: 18px 0;
+  overflow: hidden;
+  box-shadow: 0 2px 10px rgba(31, 41, 55, 0.035);
+}
+.cell-head {
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+  align-items: center;
+  padding: 14px 18px;
+  background: rgba(255, 255, 255, 0.92);
+  border-bottom: 1px solid var(--line);
+}
+.cell-head.no-title {
+  justify-content: flex-end;
+  padding-top: 10px;
+  padding-bottom: 10px;
+}
+.cell-title {
+  flex: 1;
+  min-width: 0;
+  font-size: 13px;
+  font-weight: 650;
+  color: var(--ink);
+  line-height: 1.35;
+  overflow-wrap: anywhere;
+}
+.cell-meta {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-family: var(--sans);
+  font-size: 13px;
+  color: var(--muted);
+}
+.cell-open {
+  flex: 0 0 auto;
+  font-family: var(--mono);
+  font-size: 12px;
+  color: var(--accent);
+  text-decoration: none;
+}
+.cell-open:hover {
+  color: var(--accent-strong);
+}
+.cell-body {
+  min-width: 0;
+  padding: 14px 18px 18px;
+}
+.cell.dashboard .cell-body {
+  padding: 0;
+}
+#page .cell-body h1,
+#page .cell-body h2 {
+  font-family: var(--sans);
+  font-size: 17px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  line-height: 1.35;
+  margin: 22px 0 6px;
+}
+#page .cell-body > :first-child {
+  margin-top: 0;
+}
+#page .cell-body > :last-child {
+  margin-bottom: 0;
+}
+.cell.code .cell-head {
+  background: #fbfbfc;
+}
+.figure-fit {
+  position: relative;
+  overflow: hidden;
+  min-height: 160px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: #fff;
+}
+.figure-fit[hidden] {
+  display: none;
+}
+.figure-fit:fullscreen,
+.figure-fit:-webkit-full-screen {
+  width: 100%;
+  height: 100%;
+  border: none;
+  border-radius: 0;
+}
+.figure-frame {
+  display: block;
+  width: 100%;
+  min-height: 160px;
+  border: none;
+  background: #fff;
+}
+.figure-frame[hidden],
+.figure-raw[hidden] {
+  display: none;
+}
+.fig-switch {
+  position: relative;
+  display: inline-flex;
+  flex: 0 0 auto;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: var(--code-bg);
+  padding: 2px;
+}
+.fig-switch button {
+  position: relative;
+  z-index: 1;
+  flex: 1;
+  min-width: 62px;
+  border: none;
+  background: none;
+  font-family: var(--sans);
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--muted);
+  padding: 3px 12px;
+  border-radius: 999px;
+  cursor: pointer;
+  transition: color 0.15s;
+}
+.fig-switch button.active {
+  color: var(--accent-strong);
+}
+.fig-switch-thumb {
+  position: absolute;
+  top: 2px;
+  bottom: 2px;
+  left: 2px;
+  width: calc(50% - 2px);
+  border-radius: 999px;
+  background: var(--panel);
+  border: 1px solid rgba(249, 115, 22, 0.35);
+  box-shadow: 0 1px 4px rgba(31, 41, 55, 0.08);
+  transition: transform 0.18s ease;
+}
+.fig-switch.raw .fig-switch-thumb {
+  transform: translateX(100%);
+}
+#page .figure-raw pre {
+  margin: 0;
+  max-height: 420px;
+  overflow: auto;
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.55;
+  background: var(--code-bg);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 12px 14px;
+}
+/* ---- figure fullscreen ---- */
+.cell-fullscreen {
+  position: relative;
+  display: inline-flex;
+  flex: 0 0 auto;
+}
+.cell-fullscreen-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  padding: 0;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: var(--code-bg);
+  color: var(--muted);
+  cursor: pointer;
+  transition: color 0.15s, border-color 0.15s, background 0.15s;
+}
+.cell-fullscreen-btn:hover {
+  color: var(--accent-strong);
+  border-color: rgba(249, 115, 22, 0.35);
+  background: var(--accent-soft);
+}
+.cell-fullscreen-btn svg {
+  width: 14px;
+  height: 14px;
+}
+/* ---- copyable snippets ---- */
+.snippet {
+  position: relative;
+}
+.copy-snippet {
+  position: absolute;
+  top: 7px;
+  right: 8px;
+  width: 24px;
+  height: 24px;
+  border: none;
+  border-radius: 6px;
+  background: rgba(255, 255, 255, 0.08);
+  color: #9a9da8;
+  font-size: 12px;
+  line-height: 1;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.12s, color 0.12s, background 0.12s;
+}
+.snippet:hover .copy-snippet,
+.jp-out:hover .copy-snippet,
+.figure-raw:hover .copy-snippet,
+.code-accordion summary:hover .copy-snippet {
+  opacity: 1;
+}
+.copy-snippet:hover {
+  color: #ffffff;
+  background: rgba(255, 255, 255, 0.16);
+}
+.copy-snippet.copied {
+  color: #52d08a;
+  opacity: 1;
+}
+.code-accordion .code-name {
+  user-select: text;
+  cursor: text;
+}
+.jp-out,
+.figure-raw {
+  position: relative;
+}
+.jp-out .copy-snippet,
+.figure-raw .copy-snippet {
+  background: var(--code-bg);
+  color: var(--muted);
+  border: 1px solid var(--line);
+}
+.jp-out .copy-snippet:hover,
+.figure-raw .copy-snippet:hover {
+  color: var(--accent-strong);
+  background: var(--panel);
+}
+
+/* ---- jupyter-style code cells ---- */
+.jp {
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  overflow: hidden;
+  margin: 12px 0;
+  background: var(--panel);
+}
+.jp-gutter {
+  flex: 0 0 46px;
+  padding: 13px 0 0 13px;
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.07em;
+  text-transform: uppercase;
+  font-weight: 600;
+  user-select: none;
+}
+.jp-in {
+  display: flex;
+  background: #17181c;
+}
+.jp-in .jp-gutter {
+  color: #6f727d;
+}
+.jp-in-body {
+  flex: 1;
+  min-width: 0;
+}
+#page .jp-in-body pre.hl {
+  margin: 0;
+  border: none;
+  border-radius: 0;
+  background: none;
+  padding: 12px 16px 12px 0;
+}
+.jp-in-body .code-accordion {
+  margin: 0;
+  border: none;
+  border-top: 1px solid rgba(255, 255, 255, 0.09);
+  border-radius: 0;
+  background: none;
+}
+.jp-in-body .code-accordion summary {
+  background: none;
+  padding: 9px 16px 9px 0;
+}
+.jp-in-body .code-accordion pre.hl {
+  border-top: 1px solid rgba(255, 255, 255, 0.09);
+}
+.jp-meta {
+  padding: 5px 14px;
+  font-family: var(--mono);
+  font-size: 11.5px;
+  color: var(--muted);
+  background: #fbfbfc;
+  border-top: 1px solid var(--line);
+}
+.jp-out {
+  display: flex;
+  border-top: 1px solid var(--line);
+  background: var(--panel);
+}
+.jp-out .jp-gutter {
+  color: var(--accent-strong);
+}
+.jp-out-body {
+  flex: 1;
+  min-width: 0;
+}
+#page .jp-out-pre {
+  min-width: 0;
+  margin: 0;
+  border: none;
+  border-radius: 0;
+  background: none;
+  color: var(--ink);
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.55;
+  padding: 12px 16px 12px 0;
+  white-space: pre;
+  overflow-x: auto;
+  overflow-y: auto;
+  max-height: 26em;
+}
+.jp-artifacts {
+  display: flex;
+  flex-direction: column;
+}
+.jp-out-body .jp-out-pre + .jp-artifacts {
+  border-top: 1px solid var(--line);
+}
+.out-artifact {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  padding: 9px 16px 9px 0;
+  text-decoration: none;
+  color: inherit;
+}
+.out-artifact + .out-artifact {
+  border-top: 1px solid var(--line);
+}
+a.out-artifact:hover .out-artifact-name {
+  color: var(--accent-strong);
+}
+.out-artifact-ico {
+  flex: 0 0 auto;
+  font-size: 13px;
+}
+.out-artifact-name {
+  font-family: var(--mono);
+  font-size: 12.5px;
+  font-weight: 600;
+  color: var(--ink);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.out-artifact-meta {
+  flex: 0 0 auto;
+  margin-left: auto;
+  padding-left: 12px;
+  font-size: 12px;
+  color: var(--muted);
+  white-space: nowrap;
+}
+.out-artifact-state.open {
+  color: var(--accent);
+  font-weight: 600;
+}
+.trackio-embed {
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  overflow: hidden;
+  background: var(--panel);
+}
+.trackio-cell-meta {
+  display: flex;
+  gap: 6px;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+
+/* ---- unfurl cards ---- */
+.unfurl {
+  display: block;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: var(--panel);
+  margin: 12px 0;
+  overflow: hidden;
+  text-decoration: none;
+  color: inherit;
+  transition: border-color 0.14s, box-shadow 0.14s;
+}
+.unfurl:hover {
+  border-color: #cfcbe6;
+  box-shadow: 0 4px 18px rgba(30, 20, 80, 0.06);
+}
+
+.unfurl-body {
+  padding: 13px 16px;
+  display: flex;
+  gap: 12px;
+  align-items: flex-start;
+}
+
+.unfurl-ico {
+  font-size: 20px;
+  line-height: 1.3;
+  flex: 0 0 auto;
+}
+
+.unfurl-main {
+  min-width: 0;
+  flex: 1;
+}
+
+.unfurl-kind {
+  font-family: var(--mono);
+  font-size: 10.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--accent);
+  font-weight: 600;
+}
+
+.unfurl-title {
+  font-weight: 650;
+  font-size: 15px;
+  margin: 1px 0 2px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.unfurl-desc {
+  color: var(--muted);
+  font-size: 13.5px;
+  line-height: 1.45;
+}
+
+.unfurl-meta {
+  margin-top: 6px;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.chip {
+  font-size: 11.5px;
+  background: var(--code-bg);
+  border-radius: 999px;
+  padding: 2px 9px;
+  color: var(--muted);
+  font-family: var(--mono);
+}
+
+.unfurl-raw {
+  font-family: var(--mono);
+  font-size: 11px;
+  color: var(--muted);
+  border-top: 1px solid var(--line);
+  padding: 7px 16px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.unfurl.embed {
+  padding: 0;
+  overflow: hidden;
+}
+.embed-head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--line);
+}
+.embed-head .unfurl-kind {
+  flex: 0 0 auto;
+}
+.embed-title {
+  flex: 1;
+  min-width: 0;
+  font-weight: 650;
+  font-size: 14px;
+  color: var(--ink);
+  text-decoration: none;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.embed-title:hover {
+  color: var(--accent);
+}
+.embed-open {
+  flex: 0 0 auto;
+  font-family: var(--mono);
+  font-size: 12px;
+  color: var(--accent);
+  text-decoration: none;
+}
+.embed-frame {
+  display: block;
+  width: 100%;
+  height: 560px;
+  border: 0;
+  background: var(--code-bg);
+}
+
+.dashboard-shell {
+  display: block;
+}
+.dashboard-shell .dashboard-frame {
+  display: block;
+  width: 100%;
+  height: 900px;
+  border: 0;
+  background: var(--code-bg);
+}
+
+.unfurl.image {
+  padding: 0;
+}
+.unfurl.image img {
+  display: block;
+  width: 100%;
+  height: auto;
+  max-height: 460px;
+  object-fit: contain;
+  background: var(--code-bg);
+}
+
+.artifact-chip {
+  border: 1px solid var(--line);
+  background: var(--panel);
+  border-radius: var(--radius);
+  padding: 10px 14px;
+  margin: 8px 0;
+  font-size: 14px;
+}
+.cell.dashboard .artifact-chip {
+  margin: 14px 18px 18px;
+}
+.artifact-chip code {
+  color: var(--accent);
+}
+
+/* ---- task board ---- */
+.board-wrap {
+  overflow-x: auto;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  margin: 12px 0 20px;
+  background: var(--panel);
+}
+table.board {
+  border-collapse: collapse;
+  width: 100%;
+  font-size: 14px;
+}
+table.board th,
+table.board td {
+  text-align: left;
+  padding: 9px 14px;
+  border-bottom: 1px solid var(--line);
+  vertical-align: top;
+}
+table.board thead th {
+  background: var(--accent-soft);
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: #9a4a12;
+  font-weight: 600;
+  border-bottom: 1px solid var(--line);
+}
+table.board tbody tr:last-child td {
+  border-bottom: none;
+}
+table.board .col-check {
+  text-align: center;
+  width: 92px;
+  white-space: nowrap;
+}
+table.board tr.section-row td {
+  background: var(--accent-soft);
+  text-align: center;
+  font-weight: 700;
+  font-size: 13px;
+  color: var(--accent-strong);
+  padding: 7px 14px;
+  letter-spacing: 0.02em;
+}
+.box {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  border: 1.5px solid #cfcbe0;
+  border-radius: 5px;
+  font-size: 12px;
+  color: #fff;
+  line-height: 1;
+}
+.box.on {
+  background: var(--accent);
+  border-color: var(--accent);
+}
+.who-chip {
+  display: inline-block;
+  padding: 3px 12px;
+  border-radius: 999px;
+  font-size: 12.5px;
+  font-weight: 600;
+  white-space: nowrap;
+}
+.who-chip.muted {
+  background: var(--code-bg);
+  color: var(--muted);
+  font-weight: 500;
+}
+
+/* ---- status badges + clickable rows ---- */
+table.board .col-status {
+  width: 130px;
+  white-space: nowrap;
+}
+.badge {
+  display: inline-block;
+  padding: 3px 11px;
+  border-radius: 999px;
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+}
+.badge.gray {
+  background: var(--code-bg);
+  color: var(--muted);
+}
+.badge.amber {
+  background: var(--accent-soft);
+  color: #b45309;
+}
+.badge.green {
+  background: #e6f7ee;
+  color: #1a8a55;
+}
+.badge.red {
+  background: #fde8ec;
+  color: #c62a4b;
+}
+table.board tr.linked-row {
+  cursor: pointer;
+}
+table.board tr.linked-row:hover td {
+  background: var(--accent-soft);
+}
+table.board tr.linked-row a {
+  color: var(--ink);
+  font-weight: 600;
+  text-decoration: none;
+}
+table.board tr.linked-row:hover a {
+  color: var(--accent-strong);
+}
+
+/* ---- agent read hint ---- */
+.agent-hint {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin: 4px 0 22px;
+  font-size: 12.5px;
+  color: var(--muted);
+}
+#page .agent-hint code {
+  background: var(--code-bg);
+  padding: 2px 9px;
+  border-radius: 6px;
+  font-family: var(--mono);
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--ink);
+}
+.agent-hint .copy {
+  flex: 0 0 auto;
+  background: none;
+  color: var(--muted);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  width: 22px;
+  height: 22px;
+  font-size: 11px;
+  line-height: 1;
+  cursor: pointer;
+  transition: color 0.12s, border-color 0.12s;
+}
+.agent-hint .copy:hover {
+  color: var(--accent-strong);
+  border-color: var(--accent);
+}
+.agent-hint .copy.copied {
+  color: #1a8a55;
+  border-color: #1a8a55;
+}
+.agent-hint-note {
+  margin-left: auto;
+  font-size: 12px;
+  color: var(--muted);
+}
+
+/* ---- logbook summary stats ---- */
+.logbook-stats {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  margin: 0 0 28px;
+}
+.stat-tile {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 11px;
+  border: 1px solid var(--line);
+  background: var(--panel);
+  border-radius: var(--radius);
+  padding: 12px 23px;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  transition: border-color 0.12s, box-shadow 0.12s;
+}
+.stat-tile:hover:not([disabled]) {
+  border-color: rgba(249, 115, 22, 0.45);
+  box-shadow: 0 3px 12px rgba(31, 41, 55, 0.06);
+}
+.stat-tile:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+.stat-tile[disabled] {
+  cursor: default;
+  opacity: 0.7;
+}
+.stat-tile.open {
+  border-color: rgba(249, 115, 22, 0.6);
+  box-shadow: 0 3px 12px rgba(31, 41, 55, 0.08);
+}
+.stat-icon {
+  width: 24px;
+  height: 24px;
+  flex: 0 0 24px;
+  object-fit: contain;
+  align-self: center;
+}
+.stat-text {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  white-space: nowrap;
+  line-height: 1;
+}
+.stat-num {
+  font-family: var(--mono);
+  font-size: 20px;
+  font-weight: 600;
+  line-height: 1;
+  color: var(--accent-strong);
+}
+.stat-label {
+  font-size: 15px;
+  line-height: 1;
+  color: var(--muted);
+}
+.stat-caret {
+  margin-left: 2px;
+  font-size: 10px;
+  color: var(--muted);
+  align-self: center;
+  transition: transform 0.12s;
+}
+.stat-tile.open .stat-caret {
+  transform: rotate(180deg);
+}
+.stat-popover {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  margin-top: 6px;
+  min-width: 300px;
+  max-width: min(460px, 92vw);
+  max-height: 340px;
+  overflow-y: auto;
+  z-index: 20;
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  box-shadow: 0 8px 28px rgba(31, 41, 55, 0.12);
+  padding: 6px;
+}
+.stat-popover[hidden] {
+  display: none;
+}
+.stat-pop-head {
+  padding: 6px 10px 8px;
+  font-size: 11.5px;
+  font-weight: 700;
+  letter-spacing: 0.03em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+.stat-row {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 9px 11px;
+  border-radius: 9px;
+  border: 1px solid transparent;
+  text-decoration: none;
+  color: inherit;
+  cursor: pointer;
+}
+.stat-row:hover {
+  border-color: rgba(249, 115, 22, 0.4);
+  background: var(--accent-soft);
+}
+.stat-row-ico {
+  font-size: 15px;
+  line-height: 1.3;
+  flex: 0 0 auto;
+}
+.stat-row-main {
+  min-width: 0;
+  flex: 1;
+}
+.stat-row-title {
+  font-family: var(--mono);
+  font-size: 12.5px;
+  font-weight: 600;
+  color: var(--ink);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.stat-row-meta {
+  margin-top: 2px;
+  font-size: 12px;
+  color: var(--muted);
+}
+.stat-row-state.open {
+  color: var(--accent);
+  font-weight: 600;
+  border-radius: 5px;
+  padding: 1px 5px;
+  margin: -1px -2px;
+}
+.stat-row-state.open:hover {
+  background: rgba(249, 115, 22, 0.14);
+  text-decoration: underline;
+}
+.art-ico {
+  width: 1em;
+  height: 1em;
+  object-fit: contain;
+  vertical-align: -0.15em;
+}
+
+/* ---- scroll-to-resource highlight ---- */
+.res-flash {
+  animation: res-flash 1.5s ease;
+  border-radius: 8px;
+}
+@keyframes res-flash {
+  0%,
+  25% {
+    box-shadow: 0 0 0 3px var(--accent);
+  }
+  100% {
+    box-shadow: 0 0 0 3px rgba(249, 115, 22, 0);
+  }
+}
+
+/* ---- inline resource chips ---- */
+#page .res-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  max-width: 100%;
+  padding: 0 9px 0 6px;
+  margin: 0 1px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: var(--panel);
+  font-family: var(--mono);
+  font-size: 0.78em;
+  font-weight: 600;
+  color: var(--ink);
+  text-decoration: none;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  vertical-align: middle;
+  line-height: 1.65;
+  transform: translateY(-0.08em);
+  transition: border-color 0.12s, background 0.12s, color 0.12s;
+}
+.res-chip-ico {
+  font-size: 1.05em;
+  line-height: 1;
+}
+#page .res-chip:hover,
+#page .res-chip.res-hl {
+  border-color: var(--accent);
+  background: var(--accent-soft);
+  color: var(--accent-strong);
+}
+#page a.res-link.res-hl {
+  background: var(--accent-soft);
+  border-radius: 4px;
+}
+.rail-item.res-hl {
+  border-color: var(--accent);
+  background: var(--accent-soft);
+  box-shadow: 0 3px 12px rgba(249, 115, 22, 0.14);
+}
+.rail-item.res-hl .rail-title {
+  color: var(--accent-strong);
+}
+.rail-item.rail-local {
+  cursor: default;
+}
+.artifact-chip.res-hl {
+  border-color: var(--accent);
+  background: var(--accent-soft);
+}
+
+/* ---- contextual resources rail ---- */
+.context-rail {
+  position: relative;
+  width: 248px;
+}
+.context-rail[hidden] {
+  display: none;
+}
+.rail-kind {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  font-family: var(--mono);
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  font-weight: 600;
+  color: var(--accent);
+  margin-bottom: 4px;
+}
+.rail-item {
+  position: absolute;
+  left: 0;
+  right: 0;
+  display: block;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: var(--panel);
+  padding: 9px 12px;
+  margin-bottom: 8px;
+  text-decoration: none;
+  color: inherit;
+  transition: border-color 0.14s, box-shadow 0.14s;
+}
+.rail-item:hover {
+  border-color: rgba(249, 115, 22, 0.45);
+  box-shadow: 0 3px 12px rgba(31, 41, 55, 0.06);
+}
+.rail-title {
+  font-family: var(--mono);
+  font-size: 12.5px;
+  font-weight: 600;
+  color: var(--ink);
+  overflow-wrap: anywhere;
+  line-height: 1.4;
+}
+.rail-item:hover .rail-title {
+  color: var(--accent-strong);
+}
+.rail-meta {
+  font-size: 11.5px;
+  color: var(--muted);
+  margin-top: 2px;
+}
+
+@media (max-width: 1400px) {
+  .page-layout {
+    display: block;
+  }
+  .context-rail {
+    width: 100%;
+    margin-top: 28px;
+    position: static;
+    min-height: 0 !important;
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+    gap: 10px;
+  }
+  .context-rail[hidden] {
+    display: none;
+  }
+  .context-rail .rail-item {
+    position: static;
+    margin-bottom: 0;
+  }
+}
+
+/* ---- connect footer + modal ---- */
+#sidebar-foot {
+  margin-top: auto;
+  padding-top: 14px;
+  border-top: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+#connect-btn {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  background: rgba(255, 255, 255, 0.05);
+  color: #c3c4cb;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  border-radius: 9px;
+  padding: 9px 12px;
+  font-size: 13.5px;
+  font-family: var(--sans);
+  cursor: pointer;
+  transition: background 0.12s, color 0.12s, border-color 0.12s;
+}
+#connect-btn:hover {
+  background: rgba(249, 115, 22, 0.14);
+  border-color: rgba(249, 115, 22, 0.4);
+  color: #fdba74;
+}
+#connect-btn .ico {
+  font-size: 15px;
+}
+
+#modal[hidden] {
+  display: none;
+}
+#modal {
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+}
+.modal-backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(20, 18, 30, 0.5);
+  backdrop-filter: blur(2px);
+}
+.modal-card {
+  position: relative;
+  background: var(--panel);
+  border-radius: 16px;
+  width: 100%;
+  max-width: 620px;
+  max-height: 85vh;
+  overflow-y: auto;
+  box-shadow: 0 24px 70px rgba(20, 15, 50, 0.28);
+}
+.modal-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 18px 22px;
+  border-bottom: 1px solid var(--line);
+  position: sticky;
+  top: 0;
+  background: var(--panel);
+}
+.modal-title {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-family: var(--serif);
+  font-size: 21px;
+  letter-spacing: -0.01em;
+}
+.modal-logo {
+  width: 26px;
+  height: 26px;
+  object-fit: contain;
+}
+.modal-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.btn {
+  font-family: var(--sans);
+  font-size: 13.5px;
+  font-weight: 600;
+  border: 1px solid var(--line);
+  background: var(--panel);
+  color: var(--ink);
+  border-radius: 9px;
+  padding: 8px 13px;
+  cursor: pointer;
+  transition: background 0.12s, border-color 0.12s, color 0.12s;
+}
+.btn:hover {
+  border-color: var(--accent);
+  color: var(--accent-strong);
+}
+.btn.copied {
+  border-color: #1a8a55;
+  color: #1a8a55;
+}
+.btn.icon {
+  font-size: 18px;
+  line-height: 1;
+  padding: 6px 11px;
+  font-weight: 400;
+}
+.modal-body {
+  padding: 20px 22px 26px;
+}
+.modal-intro {
+  margin: 0 0 20px;
+  color: var(--muted);
+  line-height: 1.55;
+}
+#connect-steps {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+#connect-steps li {
+  margin-bottom: 18px;
+}
+.step-title {
+  font-weight: 600;
+  font-size: 14.5px;
+  margin-bottom: 8px;
+}
+.codeblock {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  background: #17181c;
+  border-radius: 10px;
+  padding: 11px 12px 11px 15px;
+}
+.codeblock code {
+  flex: 1;
+  min-width: 0;
+  overflow-x: auto;
+  white-space: nowrap;
+  font-family: var(--mono);
+  font-size: 13px;
+  color: #f0efff;
+  background: none;
+  padding: 0;
+}
+.codeblock .copy {
+  flex: 0 0 auto;
+  background: rgba(255, 255, 255, 0.08);
+  color: #c3c4cb;
+  border: 1px solid rgba(255, 255, 255, 0.14);
+  border-radius: 7px;
+  width: 30px;
+  height: 30px;
+  font-size: 14px;
+  cursor: pointer;
+  transition: background 0.12s, color 0.12s;
+}
+.codeblock .copy:hover {
+  background: rgba(249, 115, 22, 0.2);
+  color: #fdba74;
+}
+.codeblock .copy.copied {
+  color: #52d08a;
+}
+
+@media (max-width: 720px) {
+  #app {
+    flex-direction: column;
+  }
+  #sidebar {
+    width: 100%;
+    flex: none;
+    height: auto;
+    position: static;
+  }
+  #content {
+    display: block;
+    width: 100%;
+    padding: 28px 20px 80px;
+    overflow-x: hidden;
+  }
+  #page {
+    width: 100%;
+    max-width: 100%;
+  }
+  #page h1 {
+    font-size: 30px;
+  }
+  .cell-head {
+    align-items: flex-start;
+    flex-direction: column;
+    gap: 4px;
+  }
+}

trackio/frontend_templates/logbook/logbook.js

@@ -0,0 +1,2275 @@
+(function () {
+  "use strict";
+
+  let MANIFEST = null;
+  const PAGE_CACHE = {};
+  const UNFURL_CACHE = {};
+  const LIVE_RELOAD_MS = 1500;
+  const FIGURE_FRAME_WINDOWS = new Set();
+  let FIGURE_NAVIGATION_READY = false;
+
+  function esc(s) {
+    return String(s)
+      .replace(/&/g, "&")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;");
+  }
+
+  function flattenTree(node, depth, acc) {
+    acc.push({ node: node, depth: depth });
+    (node.children || []).forEach((c) => flattenTree(c, depth + 1, acc));
+    return acc;
+  }
+
+  function findNode(node, slug) {
+    if (node.slug === slug) return node;
+    for (const c of node.children || []) {
+      const hit = findNode(c, slug);
+      if (hit) return hit;
+    }
+    return null;
+  }
+
+  /* -------------------- minimal markdown -------------------- */
+
+  function inline(text) {
+    let t = esc(text);
+    t = t.replace(/`([^`]+)`/g, (_, c) => `<code>${c}</code>`);
+    t = t.replace(/\*\*([^*]+)\*\*/g, (_, c) => `<strong>${c}</strong>`);
+    t = t.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, txt, url) => {
+      const safe = esc(url);
+      const attrs = /^https?:/.test(url) ? ' target="_blank" rel="noopener"' : "";
+      const item = /^https?:/.test(url) ? classifyResource(url) : null;
+      const data = item
+        ? ` class="res-link" data-res-url="${esc(item.url)}"`
+        : "";
+      return `<a href="${safe}"${attrs}${data}>${txt}</a>`;
+    });
+    t = t.replace(/(^|[\s(])(https?:\/\/[^\s<>)"'`]+)/g, (m, pre, url) => {
+      let rest = "";
+      const cut = url.search(/&quot;|&#39;|&lt;|&gt;/);
+      if (cut !== -1) {
+        rest = url.slice(cut);
+        url = url.slice(0, cut);
+      }
+      const trailing = (url.match(/[.,;:!?`]+$/) || [""])[0];
+      const clean = trailing ? url.slice(0, -trailing.length) : url;
+      if (!clean) return m;
+      const item = classifyResource(clean);
+      if (item) return `${pre}${resChipHtml(item)}${trailing}${rest}`;
+      return `${pre}<a href="${clean}" target="_blank" rel="noopener">${clean}</a>${trailing}${rest}`;
+    });
+    return t;
+  }
+
+  function resChipHtml(item) {
+    return (
+      `<a class="res-chip" href="${esc(item.url)}" target="_blank" ` +
+      `rel="noopener" data-res-url="${esc(item.url)}">` +
+      `<span class="res-chip-ico">${RESOURCE_ICONS[item.kind]}</span>` +
+      `${esc(item.id)}</a>`
+    );
+  }
+
+  const URL_ONLY = /^(https?:\/\/[^\s]+)$/;
+  const DETECTED_URL =
+    /(https?:\/\/[^\s<>)\]"'`]+|trackio-local-dashboard:\/\/[^\s<>)\]"'`]+|trackio-artifact:\/\/[^\s<>)\]"'`]+|trackio-local-path:\/\/[^\s<>)\]"'`]+)/g;
+
+  function renderMarkdown(md, container) {
+    const cellRe = /(^|\n)---\n<!-- trackio-cell\n([\s\S]*?)\n-->\n([\s\S]*?)(?=\n---\n<!-- trackio-cell\n|\s*$)/g;
+    const tokens = [];
+    let pos = 0;
+    let found = false;
+    let match;
+    while ((match = cellRe.exec(md))) {
+      found = true;
+      tokens.push({
+        kind: "md",
+        text: md.slice(pos, match.index + match[1].length),
+      });
+      tokens.push({
+        kind: "cell",
+        meta: parseCellMeta(match[2]),
+        body: match[3],
+      });
+      pos = match.index + match[0].length;
+    }
+    tokens.push({ kind: "md", text: found ? md.slice(pos) : md });
+
+    for (let i = 0; i < tokens.length; i++) {
+      const t = tokens[i];
+      if (t.kind === "md") {
+        renderMarkdownPlain(t.text, container);
+        continue;
+      }
+      if (t.consumed) continue;
+      if (t.meta.type === "code") {
+        const arts = [];
+        for (let j = i + 1; j < tokens.length; j++) {
+          const n = tokens[j];
+          if (n.kind === "md") {
+            if (n.text.trim() === "") continue;
+            break;
+          }
+          if (n.meta.type === "artifact") {
+            arts.push(n);
+            n.consumed = true;
+            continue;
+          }
+          break;
+        }
+        renderCell(t.meta, t.body, container, arts);
+      } else {
+        renderCell(t.meta, t.body, container);
+      }
+    }
+  }
+
+  function parseCellMeta(raw) {
+    try {
+      return JSON.parse(raw);
+    } catch (e) {
+      return { type: "markdown", title: "Note" };
+    }
+  }
+
+  function renderMarkdownPlain(md, container) {
+    const lines = md.replace(/<!--[\s\S]*?-->/g, "").split("\n");
+    let i = 0;
+    let para = [];
+
+    function flushPara() {
+      if (!para.length) return;
+      const joined = para.join(" ").trim();
+      para = [];
+      if (!joined) return;
+      if (/^trackio-artifact:\/\/\S+$/.test(joined)) return;
+      if (/^trackio-local-path:\/\/\S+$/.test(joined)) return;
+      if (joined.indexOf("📦 Artifact") !== -1) {
+        const div = document.createElement("div");
+        div.className = "artifact-chip";
+        div.innerHTML = ARTIFACT_ICON_IMG + inline(joined.replace(/📦\s*/, ""));
+        container.appendChild(div);
+        return;
+      }
+      if (URL_ONLY.test(joined) || IMG_PATH.test(joined)) {
+        const el = renderStandaloneUrl(joined);
+        if (el) container.appendChild(el);
+        return;
+      }
+      const p = document.createElement("p");
+      p.innerHTML = inline(joined);
+      container.appendChild(p);
+    }
+
+    while (i < lines.length) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      if (trimmed === "") {
+        flushPara();
+        i++;
+        continue;
+      }
+      const fence = trimmed.match(/^(`{3,}|~{3,})(.*)$/);
+      if (fence) {
+        flushPara();
+        const marker = fence[1][0];
+        const closeRe = new RegExp("^" + marker + "{" + fence[1].length + ",}\\s*$");
+        const info = fence[2].trim();
+        const buf = [];
+        i++;
+        while (i < lines.length && !closeRe.test(lines[i].trim())) {
+          buf.push(lines[i]);
+          i++;
+        }
+        i++;
+        const lang = (info.split(/\s+/)[0] || "").toLowerCase();
+        const tm = info.match(/title=(\S+)/);
+        container.appendChild(
+          renderCode(buf.join("\n"), lang, tm ? tm[1] : null)
+        );
+        continue;
+      }
+      if (trimmed === "---") {
+        flushPara();
+        container.appendChild(document.createElement("hr"));
+        i++;
+        continue;
+      }
+      const h = trimmed.match(/^(#{1,4})\s+(.*)$/);
+      if (h) {
+        flushPara();
+        const el = document.createElement("h" + h[1].length);
+        el.innerHTML = inline(h[2]);
+        container.appendChild(el);
+        i++;
+        continue;
+      }
+      if (
+        trimmed.startsWith("|") &&
+        i + 1 < lines.length &&
+        /^\|?[\s:|-]*-{2,}[\s:|-]*\|?$/.test(lines[i + 1].trim())
+      ) {
+        flushPara();
+        const rows = [];
+        while (i < lines.length && lines[i].trim().startsWith("|")) {
+          rows.push(parseRow(lines[i].trim()));
+          i++;
+        }
+        renderTable(rows, container);
+        continue;
+      }
+      if (trimmed.startsWith("> ")) {
+        flushPara();
+        const bq = document.createElement("blockquote");
+        bq.innerHTML = inline(trimmed.slice(2));
+        container.appendChild(bq);
+        i++;
+        continue;
+      }
+      if (/^`[^`]+`$/.test(trimmed)) {
+        flushPara();
+        const el = document.createElement("div");
+        el.className = "ts";
+        el.textContent = trimmed.replace(/`/g, "");
+        container.appendChild(el);
+        i++;
+        continue;
+      }
+      if (trimmed.startsWith("- ")) {
+        flushPara();
+        const items = [];
+        while (i < lines.length && lines[i].trim().startsWith("- ")) {
+          items.push(lines[i].trim().slice(2).trim());
+          i++;
+        }
+        renderList(items, container);
+        continue;
+      }
+      para.push(trimmed);
+      i++;
+    }
+    flushPara();
+  }
+
+  function renderCell(meta, body, container, artifacts) {
+    const cell = document.createElement("section");
+    cell.className = `cell ${meta.type || "markdown"}`;
+    if (meta.id) cell.dataset.cellId = meta.id;
+    if (isPinned(meta)) cell.classList.add("pinned-source");
+
+    const head = document.createElement("div");
+    head.className = "cell-head";
+    const rawTitle = (meta.title || "").trim();
+    const title = rawTitle && rawTitle.toLowerCase() !== "untitled" ? esc(rawTitle) : "";
+    const when = meta.created_at ? `<span>${esc(formatTime(meta.created_at))}</span>` : "";
+    head.innerHTML =
+      (title ? `<div class="cell-title">${title}</div>` : "") +
+      `<div class="cell-meta">${when}</div>`;
+    if (!title) head.classList.add("no-title");
+    cell.appendChild(head);
+
+    const bodyEl = document.createElement("div");
+    bodyEl.className = "cell-body";
+    if (meta.type === "code") {
+      renderCodeCell(body, bodyEl, artifacts);
+    } else if (meta.type === "figure") {
+      cell.dataset.resUrl = `trackio-figure://${(meta.title || "Figure").trim()}`;
+      renderFigureCell(body, bodyEl, head);
+    } else if (meta.type === "artifact") {
+      renderMarkdownPlain(body, bodyEl);
+      const chip = bodyEl.querySelector(".artifact-chip");
+      const uri = body.match(
+        /(trackio-artifact:\/\/\S+|trackio-local-path:\/\/\S+|https:\/\/huggingface\.co\/buckets\/[^\s<)]+#\S+)/
+      );
+      if (chip && uri) chip.dataset.resUrl = uri[1];
+    } else if (meta.type === "dashboard") {
+      const sp = body.match(/https:\/\/huggingface\.co\/spaces\/[^\s<>)"'`]+/);
+      cell.dataset.resUrl = sp
+        ? sp[0]
+        : `trackio-local-dashboard://${(meta.dashboard_project || "").trim()}`;
+      renderDashboardCell(meta, body, bodyEl, head);
+    } else {
+      const cleaned = stripDuplicateTitle(body, meta.title);
+      renderMarkdownPlain(cleaned, bodyEl);
+      renderDetectedEmbeds(cleaned, bodyEl);
+    }
+    cell.appendChild(bodyEl);
+    container.appendChild(cell);
+    return cell;
+  }
+
+  function isPinned(meta) {
+    return Boolean(meta && (meta.pinned === true || meta.pinned === "true"));
+  }
+
+  function stripDuplicateTitle(body, title) {
+    if (!title) return body;
+    const m = body.match(/^\s*#{1,6}\s+([^\n]+)\n?/);
+    if (!m) return body;
+    const norm = (s) =>
+      s
+        .toLowerCase()
+        .replace(/[*_`#]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    return norm(m[1]) === norm(title) ? body.slice(m[0].length) : body;
+  }
+
+  function formatTime(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime())) return iso;
+    return d.toLocaleString(undefined, {
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  }
+
+  function parseFences(text) {
+    const fenceRe = /(`{3,4}|~{3,4})([^\n]*)\n([\s\S]*?)\n\1/g;
+    const parts = [];
+    let pos = 0;
+    let match;
+    while ((match = fenceRe.exec(text))) {
+      if (match.index > pos) {
+        parts.push({ kind: "text", text: text.slice(pos, match.index) });
+      }
+      const info = match[2].trim();
+      const lang = (info.split(/\s+/)[0] || "").toLowerCase();
+      const titleMatch = info.match(/title=(\S+)/);
+      parts.push({
+        kind: lang === "result" || lang === "output" ? "output" : "code",
+        lang,
+        title: titleMatch ? titleMatch[1] : null,
+        text: match[3],
+      });
+      pos = match.index + match[0].length;
+    }
+    if (pos < text.length) parts.push({ kind: "text", text: text.slice(pos) });
+    return parts;
+  }
+
+  function fitFigureFrame(frame, wrap) {
+    let doc;
+    try {
+      doc = frame.contentDocument;
+    } catch (e) {
+      return;
+    }
+    if (!doc || !doc.body) return;
+    frame.style.transform = "none";
+    frame.style.width = "100%";
+    frame.style.height = "auto";
+    frame.style.position = "";
+    frame.style.left = "";
+    frame.style.top = "";
+    const avail = wrap.clientWidth;
+    const isFullscreen =
+      document.fullscreenElement === wrap ||
+      document.webkitFullscreenElement === wrap;
+    const availHeight = isFullscreen ? wrap.clientHeight : Infinity;
+    const cw = Math.max(doc.body.scrollWidth, doc.documentElement.scrollWidth, 1);
+    const ch = Math.max(doc.body.scrollHeight, doc.documentElement.scrollHeight, 1);
+    const scale = Math.min(avail / cw, availHeight / ch);
+    if (avail && scale < 1 - 1e-3) {
+      frame.style.width = `${cw}px`;
+      frame.style.height = `${ch}px`;
+      frame.style.transformOrigin = "top left";
+      frame.style.transform = `scale(${scale})`;
+      if (isFullscreen) {
+        frame.style.position = "absolute";
+        frame.style.left = `${Math.max(0, (avail - cw * scale) / 2)}px`;
+        frame.style.top = `${Math.max(0, (availHeight - ch * scale) / 2)}px`;
+        wrap.style.height = "100%";
+      } else {
+        wrap.style.height = `${Math.ceil(ch * scale)}px`;
+      }
+    } else {
+      frame.style.width = "100%";
+      frame.style.height = `${ch}px`;
+      wrap.style.height = isFullscreen ? "100%" : `${ch}px`;
+    }
+  }
+
+  function attachFigureFit(frame, wrap) {
+    const refit = () => fitFigureFrame(frame, wrap);
+    frame.addEventListener("load", refit);
+    if (window.ResizeObserver) {
+      const ro = new ResizeObserver(() => refit());
+      ro.observe(wrap);
+    }
+  }
+
+  function renderFigureCell(text, container, head) {
+    const parts = parseFences(text);
+    const htmlPart = parts.find((part) => part.lang === "html");
+    const rawPart = parts.find((part) => part.lang === "raw");
+    if (!htmlPart || !htmlPart.text.trim()) {
+      const empty = document.createElement("p");
+      empty.className = "muted";
+      empty.textContent = "No figure HTML.";
+      container.appendChild(empty);
+      return;
+    }
+    const frame = document.createElement("iframe");
+    frame.className = "figure-frame";
+    frame.sandbox = "allow-scripts allow-same-origin";
+    frame.loading = "lazy";
+    frame.srcdoc = htmlPart.text;
+    registerFigureNavigation(frame);
+    const figWrap = document.createElement("div");
+    figWrap.className = "figure-fit";
+    figWrap.appendChild(frame);
+    attachFigureFit(frame, figWrap);
+    if (head) {
+      const metaEl = head.querySelector(".cell-meta");
+      if (metaEl)
+        metaEl.insertBefore(buildFullscreenControl(figWrap, frame), metaEl.firstChild);
+    }
+    if (!rawPart || !rawPart.text.trim()) {
+      container.appendChild(figWrap);
+      return;
+    }
+    const sw = document.createElement("div");
+    sw.className = "fig-switch";
+    const thumb = document.createElement("span");
+    thumb.className = "fig-switch-thumb";
+    const figBtn = document.createElement("button");
+    figBtn.type = "button";
+    figBtn.className = "active";
+    figBtn.textContent = "Figure";
+    const rawBtn = document.createElement("button");
+    rawBtn.type = "button";
+    rawBtn.textContent = "Raw";
+    sw.appendChild(thumb);
+    sw.appendChild(figBtn);
+    sw.appendChild(rawBtn);
+    const rawView = document.createElement("div");
+    rawView.className = "figure-raw";
+    rawView.hidden = true;
+    const pre = document.createElement("pre");
+    const code = document.createElement("code");
+    code.textContent = rawPart.text;
+    pre.appendChild(code);
+    rawView.appendChild(pre);
+    rawView.appendChild(copySnippetBtn(rawPart.text));
+    const select = (showRaw) => {
+      sw.classList.toggle("raw", showRaw);
+      figBtn.classList.toggle("active", !showRaw);
+      rawBtn.classList.toggle("active", showRaw);
+      figWrap.hidden = showRaw;
+      rawView.hidden = !showRaw;
+    };
+    figBtn.addEventListener("click", () => select(false));
+    rawBtn.addEventListener("click", () => select(true));
+    if (head) {
+      head.insertBefore(sw, head.querySelector(".cell-meta"));
+    } else {
+      container.appendChild(sw);
+    }
+    container.appendChild(figWrap);
+    container.appendChild(rawView);
+  }
+
+  // Poster embeds can send `{ type: "trackio-logbook:navigate", target: "..." }`
+  // from their iframe. Only accept messages from figure frames we created, and
+  // only route to pages that are present in this logbook's manifest.
+  function registerFigureNavigation(frame) {
+    const registerFrameWindow = () => {
+      if (frame.contentWindow) FIGURE_FRAME_WINDOWS.add(frame.contentWindow);
+    };
+    // `srcdoc` replaces the initial about:blank document. Register after that
+    // navigation as well, so messages come from the live figure document.
+    frame.addEventListener("load", registerFrameWindow);
+    registerFrameWindow();
+    if (FIGURE_NAVIGATION_READY) return;
+    FIGURE_NAVIGATION_READY = true;
+    window.addEventListener("message", (event) => {
+      if (!FIGURE_FRAME_WINDOWS.has(event.source)) return;
+      const message = event.data;
+      if (!message || message.type !== "trackio-logbook:navigate") return;
+      const target = String(message.target || "").replace(/^#?\//, "");
+      if (!target || !MANIFEST || !findNode(MANIFEST.root, target)) return;
+      const hash = "#/" + target;
+      if (location.hash === hash) scrollToHash();
+      else location.hash = hash;
+    });
+  }
+
+  const FULLSCREEN_ICON =
+    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" ' +
+    'stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+    '<path d="M8 3H3v5M16 3h5v5M21 16v5h-5M3 16v5h5"/>' +
+    '<path d="M3 8 8 3M16 3l5 5M21 16l-5 5M8 21l-5-5"/></svg>';
+
+  // Figures are rendered in same-origin iframes, so fullscreen the fitted
+  // wrapper rather than the iframe document. This uses the browser's native
+  // fullscreen UI and preserves the figure's existing responsive sizing.
+  function buildFullscreenControl(figWrap, frame) {
+    const wrap = document.createElement("span");
+    wrap.className = "cell-fullscreen";
+    const btn = document.createElement("button");
+    btn.type = "button";
+    btn.className = "cell-fullscreen-btn";
+    btn.setAttribute("aria-label", "Open figure in fullscreen");
+    btn.title = "Open figure in fullscreen";
+    btn.innerHTML = FULLSCREEN_ICON;
+    wrap.appendChild(btn);
+
+    btn.addEventListener("click", async () => {
+      const request = figWrap.requestFullscreen || figWrap.webkitRequestFullscreen;
+      if (!request) return;
+      try {
+        await request.call(figWrap);
+      } catch (_) {
+        // Fullscreen can be disabled by the embedding browser or policy.
+      }
+    });
+    document.addEventListener("fullscreenchange", () => {
+      if (document.fullscreenElement === figWrap) fitFigureFrame(frame, figWrap);
+    });
+    return wrap;
+  }
+
+  function extractUrls(text) {
+    const seen = new Set();
+    const urls = [];
+    let match;
+    while ((match = DETECTED_URL.exec(text))) {
+      const url = match[1].replace(/[.,;:!?'"`]+$/, "");
+      if (!seen.has(url)) {
+        seen.add(url);
+        urls.push(url);
+      }
+    }
+    DETECTED_URL.lastIndex = 0;
+    return urls;
+  }
+
+  const IMG_URL = /(\.(png|jpe?g|gif|svg|webp)(\?|$)|\/artifact_blob\/)/i;
+
+  function renderDetectedEmbeds(text, container) {
+    extractUrls(text).forEach((url) => {
+      if (url.startsWith("trackio-local-dashboard://")) {
+        const div = document.createElement("div");
+        div.className = "artifact-chip";
+        div.dataset.resUrl = url;
+        div.innerHTML =
+          "🎯 <strong>Local Trackio dashboard</strong> — publish the logbook to share it";
+        container.appendChild(div);
+      } else if (IMG_URL.test(url)) {
+        container.appendChild(renderImage(url));
+      } else if (/huggingface\.co\/spaces\//.test(url)) {
+        maybeEmbedTrackioSpace(url, container);
+      }
+    });
+  }
+
+  function renderStandaloneUrl(url) {
+    if (IMG_URL.test(url) || IMG_PATH.test(url)) return renderImage(url);
+    const item = classifyResource(url);
+    if (item) {
+      const marker = document.createElement("span");
+      marker.className = "resource-anchor";
+      marker.dataset.resUrl = item.url;
+      marker.setAttribute("aria-hidden", "true");
+      return marker;
+    }
+    const p = document.createElement("p");
+    p.innerHTML = inline(url);
+    return p;
+  }
+
+  function renderImage(url) {
+    const a = document.createElement("a");
+    a.className = "unfurl image";
+    a.href = url;
+    a.target = "_blank";
+    a.rel = "noopener";
+    const img = document.createElement("img");
+    img.loading = "lazy";
+    img.src = url;
+    img.alt = "artifact image";
+    a.appendChild(img);
+    return a;
+  }
+
+  function maybeEmbedTrackioSpace(url, container) {
+    const id = url.split("/spaces/")[1].split(/[?#]/)[0].replace(/\/$/, "");
+    const holder = document.createElement("div");
+    container.appendChild(holder);
+    getJSON(`https://huggingface.co/api/spaces/${id}`).then((d) => {
+      const tags = (d && d.tags) || [];
+      if (tags.some((t) => String(t).toLowerCase() === "trackio")) {
+        renderTrackioSpaceEmbed(holder, url, id);
+      } else {
+        holder.remove();
+      }
+    });
+  }
+
+  function jpGutter(label) {
+    const g = document.createElement("div");
+    g.className = "jp-gutter";
+    g.textContent = label;
+    return g;
+  }
+
+  function renderOutArtifact(info) {
+    const remote = !info.local && !!info.url;
+    const el = document.createElement(remote ? "a" : "div");
+    el.className = "out-artifact";
+    if (remote) {
+      el.href = info.url;
+      el.target = "_blank";
+      el.rel = "noopener";
+    }
+    el.dataset.resUrl = info.resUrl;
+    const parts = [info.type, info.size].filter(Boolean).map(esc);
+    const state = remote
+      ? `<span class="out-artifact-state open">Open ↗</span>`
+      : `<span class="out-artifact-state">publish to share</span>`;
+    const meta = parts.length ? `${parts.join(" · ")} · ${state}` : state;
+    el.innerHTML =
+      `<span class="out-artifact-ico">${ARTIFACT_ICON_IMG}</span>` +
+      `<span class="out-artifact-name">${esc(info.name)}</span>` +
+      `<span class="out-artifact-meta">${meta}</span>`;
+    return el;
+  }
+
+  function renderCodeCell(body, container, artifacts) {
+    const parts = parseFences(body);
+    const block = document.createElement("div");
+    block.className = "jp";
+    const input = document.createElement("div");
+    input.className = "jp-in";
+    const inputBody = document.createElement("div");
+    inputBody.className = "jp-in-body";
+    input.appendChild(jpGutter("In"));
+    input.appendChild(inputBody);
+    let metaEl = null;
+    let outputEl = null;
+    let outBody = null;
+    const ensureOut = () => {
+      if (outputEl) return;
+      outputEl = document.createElement("div");
+      outputEl.className = "jp-out";
+      outputEl.appendChild(jpGutter("Out"));
+      outBody = document.createElement("div");
+      outBody.className = "jp-out-body";
+      outputEl.appendChild(outBody);
+    };
+    const embedTexts = [];
+    parts.forEach((part) => {
+      if (part.kind === "text") {
+        const text = part.text.trim();
+        if (!text) return;
+        if (/^exit\s+\S+(\s|·)/.test(text)) {
+          metaEl = document.createElement("div");
+          metaEl.className = "jp-meta";
+          metaEl.textContent = text.replace(
+            /\s*·\s*[A-Z][a-z]{2} \d{1,2}, \d{4}.*$/,
+            ""
+          );
+        } else {
+          renderMarkdownPlain(text, container);
+          embedTexts.push(text);
+        }
+        return;
+      }
+      if (part.kind === "output") {
+        ensureOut();
+        const pre = document.createElement("pre");
+        pre.className = "jp-out-pre";
+        const c = document.createElement("code");
+        c.textContent = part.text;
+        pre.appendChild(c);
+        outBody.appendChild(pre);
+        outputEl.appendChild(copySnippetBtn(part.text));
+        embedTexts.push(part.text);
+        return;
+      }
+      inputBody.appendChild(renderCode(part.text, part.lang, part.title));
+    });
+    if (artifacts && artifacts.length) {
+      ensureOut();
+      const artWrap = document.createElement("div");
+      artWrap.className = "jp-artifacts";
+      artifacts.forEach((a) => {
+        artWrap.appendChild(
+          renderOutArtifact(artifactInfoFromCell(a.meta, a.body))
+        );
+      });
+      outBody.appendChild(artWrap);
+    }
+    if (inputBody.childNodes.length > 0) block.appendChild(input);
+    if (metaEl) block.appendChild(metaEl);
+    if (outputEl) block.appendChild(outputEl);
+    if (block.childNodes.length) container.appendChild(block);
+    embedTexts.forEach((text) => renderDetectedEmbeds(text, container));
+  }
+
+  function parseRow(line) {
+    let s = line.trim();
+    if (s.startsWith("|")) s = s.slice(1);
+    if (s.endsWith("|")) s = s.slice(0, -1);
+    return s.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, "|").trim());
+  }
+
+  const TRUTHY = ["x", "✓", "✔", "yes", "done", "true", "[x]"];
+  const CHIP_COLORS = [
+    ["#e7f0ff", "#2158d0"],
+    ["#fde8ec", "#c62a4b"],
+    ["#e6f7ee", "#1a8a55"],
+    ["#fdf0e0", "#b26a12"],
+    ["#efe9ff", "#5b3bd6"],
+    ["#e6f6f8", "#127b88"],
+  ];
+
+  function chipColor(name) {
+    let h = 0;
+    for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0;
+    return CHIP_COLORS[h % CHIP_COLORS.length];
+  }
+
+  const STATUS_MAP = {
+    "": ["Planned", "gray"],
+    planned: ["Planned", "gray"],
+    todo: ["Planned", "gray"],
+    "to do": ["Planned", "gray"],
+    backlog: ["Planned", "gray"],
+    "in progress": ["In progress", "amber"],
+    "in-progress": ["In progress", "amber"],
+    wip: ["In progress", "amber"],
+    running: ["In progress", "amber"],
+    active: ["In progress", "amber"],
+    done: ["Done", "green"],
+    complete: ["Done", "green"],
+    completed: ["Done", "green"],
+    blocked: ["Blocked", "red"],
+    failed: ["Failed", "red"],
+    abandoned: ["Abandoned", "gray"],
+  };
+
+  function statusBadge(val) {
+    const [label, tone] = STATUS_MAP[val.toLowerCase()] || [val || "—", "gray"];
+    return `<span class="badge ${tone}">${esc(label)}</span>`;
+  }
+
+  function renderTable(rows, container) {
+    if (rows.length < 2) return;
+    const header = rows[0];
+    const body = rows.slice(2);
+    const roles = header.map((h) => {
+      const t = h.toLowerCase();
+      if (t.includes("status") || t.includes("state")) return "status";
+      if (t.includes("progress") || t.includes("complete") || t.includes("done"))
+        return "check";
+      if (t === "who" || t.includes("assign") || t.includes("owner")) return "who";
+      return "text";
+    });
+    const table = document.createElement("table");
+    table.className = "board";
+    const thead = document.createElement("thead");
+    const htr = document.createElement("tr");
+    header.forEach((h, c) => {
+      const th = document.createElement("th");
+      th.textContent = h;
+      if (roles[c] === "check") th.className = "col-check";
+      htr.appendChild(th);
+    });
+    thead.appendChild(htr);
+    table.appendChild(thead);
+    const tbody = document.createElement("tbody");
+    body.forEach((cells) => {
+      const nonEmpty = cells.filter((x) => x !== "").length;
+      if (header.length > 1 && nonEmpty === 1 && cells[0]) {
+        const tr = document.createElement("tr");
+        tr.className = "section-row";
+        const td = document.createElement("td");
+        td.colSpan = header.length;
+        td.innerHTML = inline(cells[0]);
+        tr.appendChild(td);
+        tbody.appendChild(tr);
+        return;
+      }
+      const tr = document.createElement("tr");
+      header.forEach((_, c) => {
+        const td = document.createElement("td");
+        const val = (cells[c] || "").trim();
+        if (roles[c] === "status") {
+          td.className = "col-status";
+          td.innerHTML = statusBadge(val);
+        } else if (roles[c] === "check") {
+          td.className = "col-check";
+          const on = TRUTHY.indexOf(val.toLowerCase()) !== -1;
+          td.innerHTML = `<span class="box ${on ? "on" : ""}">${on ? "✓" : ""}</span>`;
+        } else if (roles[c] === "who") {
+          if (!val || /^to assign$/i.test(val)) {
+            td.innerHTML = `<span class="who-chip muted">${esc(val || "—")}</span>`;
+          } else {
+            const [bg, fg] = chipColor(val);
+            td.innerHTML = `<span class="who-chip" style="background:${bg};color:${fg}">${esc(val)}</span>`;
+          }
+        } else {
+          td.innerHTML = inline(val);
+        }
+        tr.appendChild(td);
+      });
+      const link = tr.querySelector('a[href^="#/"]');
+      if (link) {
+        tr.classList.add("linked-row");
+        tr.addEventListener("click", (e) => {
+          if (e.target.tagName !== "A") location.hash = link.getAttribute("href");
+        });
+      }
+      tbody.appendChild(tr);
+    });
+    table.appendChild(tbody);
+    const wrap = document.createElement("div");
+    wrap.className = "board-wrap";
+    wrap.appendChild(table);
+    container.appendChild(wrap);
+  }
+
+  const HL_RULES = {
+    python: [
+      ["comment", /#[^\n]*/],
+      ["string", /'''[\s\S]*?'''|"""[\s\S]*?"""|'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/],
+      [
+        "keyword",
+        /\b(?:def|class|return|if|elif|else|for|while|import|from|as|with|try|except|finally|raise|in|not|and|or|is|None|True|False|lambda|yield|global|nonlocal|assert|pass|break|continue|async|await|print)\b/,
+      ],
+      ["number", /\b\d[\d_.eE+-]*\b/],
+    ],
+    bash: [
+      ["comment", /#[^\n]*/],
+      ["string", /'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/],
+      ["keyword", /\b(?:if|then|else|fi|for|in|do|done|while|case|esac|function|export|source|echo|cd|return|local)\b/],
+      ["number", /(?<=\s)-{1,2}[a-zA-Z][\w-]*/],
+    ],
+    json: [
+      ["string", /"(?:\\.|[^"\\])*"/],
+      ["keyword", /\b(?:true|false|null)\b/],
+      ["number", /-?\b\d[\d.eE+-]*\b/],
+    ],
+    yaml: [
+      ["comment", /#[^\n]*/],
+      ["string", /'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/],
+      ["keyword", /\b(?:true|false|null|yes|no)\b/],
+      ["number", /-?\b\d[\d.eE+-]*\b/],
+    ],
+  };
+  HL_RULES.javascript = HL_RULES.python;
+  HL_RULES.typescript = HL_RULES.python;
+  HL_RULES.sql = [
+    ["comment", /--[^\n]*/],
+    ["string", /'(?:\\.|[^'\\])*'/],
+    [
+      "keyword",
+      /\b(?:SELECT|FROM|WHERE|JOIN|LEFT|RIGHT|INNER|OUTER|ON|GROUP|BY|ORDER|LIMIT|INSERT|INTO|VALUES|UPDATE|SET|DELETE|CREATE|TABLE|AS|AND|OR|NOT|NULL|COUNT|DISTINCT|IN)\b/i,
+    ],
+    ["number", /\b\d[\d.]*\b/],
+  ];
+
+  function highlightCode(code, lang) {
+    const rules = HL_RULES[lang];
+    if (!rules) return esc(code);
+    const combined = new RegExp(rules.map((r) => "(" + r[1].source + ")").join("|"), "g");
+    let out = "";
+    let last = 0;
+    let m;
+    while ((m = combined.exec(code))) {
+      if (m[0] === "") {
+        combined.lastIndex++;
+        continue;
+      }
+      out += esc(code.slice(last, m.index));
+      let gi = 1;
+      while (gi < m.length && m[gi] === undefined) gi++;
+      out += `<span class="tok-${rules[gi - 1][0]}">${esc(m[0])}</span>`;
+      last = m.index + m[0].length;
+    }
+    out += esc(code.slice(last));
+    return out;
+  }
+
+  function copySnippetBtn(text) {
+    const btn = document.createElement("button");
+    btn.type = "button";
+    btn.className = "copy-snippet";
+    btn.title = "Copy";
+    btn.textContent = "⧉";
+    btn.addEventListener("click", (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      copyText(text, btn, "⧉");
+    });
+    return btn;
+  }
+
+  function renderCode(code, lang, title) {
+    const pre = document.createElement("pre");
+    pre.className = "hl";
+    const c = document.createElement("code");
+    c.innerHTML = highlightCode(code, lang);
+    pre.appendChild(c);
+    if (!title) {
+      const wrap = document.createElement("div");
+      wrap.className = "snippet";
+      wrap.appendChild(pre);
+      wrap.appendChild(copySnippetBtn(code));
+      return wrap;
+    }
+    const det = document.createElement("details");
+    det.className = "code-accordion";
+    det.dataset.resUrl = `trackio-script://${title}`;
+    const sum = document.createElement("summary");
+    sum.innerHTML =
+      `<span class="code-ico">&lt;/&gt;</span>` +
+      `<span class="code-name">${esc(title)}</span>`;
+    sum
+      .querySelector(".code-name")
+      .addEventListener("click", (e) => e.preventDefault());
+    det.appendChild(sum);
+    const wrap = document.createElement("div");
+    wrap.className = "snippet";
+    wrap.appendChild(pre);
+    wrap.appendChild(copySnippetBtn(code));
+    det.appendChild(wrap);
+    return det;
+  }
+
+  const IMG_PATH = /^[^\s]+\.(png|jpe?g|gif|svg|webp)$/i;
+
+  function renderList(items, container) {
+    let ul = null;
+    items.forEach((item) => {
+      if (URL_ONLY.test(item) || IMG_PATH.test(item)) {
+        const el = renderStandaloneUrl(item);
+        if (el) {
+          ul = null;
+          container.appendChild(el);
+        }
+      } else if (item.indexOf("📦 Artifact") !== -1) {
+        ul = null;
+        const div = document.createElement("div");
+        div.className = "artifact-chip";
+        div.innerHTML = inline(item.replace("📦", "🪣"));
+        container.appendChild(div);
+      } else if (item.indexOf("trackio-local-dashboard://") !== -1) {
+        ul = null;
+        const uri = item.match(/trackio-local-dashboard:\/\/\S+/)?.[0] || "";
+        const div = document.createElement("div");
+        div.className = "artifact-chip";
+        if (uri) div.dataset.resUrl = uri;
+        div.innerHTML =
+          "🎯 <strong>Local dashboard</strong> — publish the logbook to share it";
+        container.appendChild(div);
+      } else {
+        if (!ul) {
+          ul = document.createElement("ul");
+          container.appendChild(ul);
+        }
+        const li = document.createElement("li");
+        li.innerHTML = inline(item);
+        ul.appendChild(li);
+      }
+    });
+  }
+
+  /* -------------------- resources rail -------------------- */
+
+  function fmt(n) {
+    if (n == null) return null;
+    if (n >= 1e6) return (n / 1e6).toFixed(1) + "M";
+    if (n >= 1e3) return (n / 1e3).toFixed(1) + "k";
+    return String(n);
+  }
+
+  const RESOURCE_SECTIONS = [
+    ["dashboard", "Dashboards", "🎯"],
+    ["model", "Models", "🤗"],
+    ["dataset", "Datasets", "📊"],
+    ["space", "Spaces", "🚀"],
+    ["artifact", "Artifacts", "🪣"],
+    ["paper", "Papers", "📄"],
+    ["repo", "Code", "🐙"],
+    ["job", "Jobs", "⚙️"],
+    ["bucket", "Buckets", "🪣"],
+  ];
+
+  const RESOURCE_ICONS = Object.fromEntries(
+    RESOURCE_SECTIONS.map(([kind, , icon]) => [kind, icon])
+  );
+
+  const ARTIFACT_ICON_IMG = `<img class="art-ico" src="./bucket-icon.svg" alt="" />`;
+  const DASHBOARD_ICON_IMG = `<img class="art-ico" src="./trackio-logo-light.png" alt="" />`;
+
+  const RESOURCE_DESC = {
+    dashboard: "Dashboard",
+    model: "Model",
+    dataset: "Dataset",
+    space: "Space",
+    artifact: "Artifact — in Bucket",
+    paper: "Paper",
+    repo: "Repository",
+    job: "Job — status & logs",
+    bucket: "Bucket — artifacts & data",
+  };
+
+  const HF_NON_MODEL_PREFIX =
+    /^(datasets|spaces|jobs|buckets|papers|blog|docs|api|posts|collections|organizations|settings|new|join|login|pricing|tasks|learn|chat|models)(\/|$)/;
+
+  function hfId(url, marker) {
+    return url.split(marker)[1].split(/[?#]/)[0].replace(/\/$/, "");
+  }
+
+  function classifyResource(url) {
+    if (IMG_URL.test(url)) {
+      return null;
+    }
+    let m;
+    if (url.startsWith("trackio-local-dashboard://")) {
+      return {
+        kind: "dashboard",
+        id: url.slice("trackio-local-dashboard://".length),
+        url,
+        local: true,
+      };
+    }
+    if (url.startsWith("trackio-artifact://")) {
+      return {
+        kind: "artifact",
+        id: url.slice("trackio-artifact://".length),
+        url,
+        local: true,
+      };
+    }
+    if (url.startsWith("trackio-local-path://")) {
+      return {
+        kind: "artifact",
+        id: url.slice("trackio-local-path://".length),
+        url,
+        local: true,
+      };
+    }
+    if ((m = url.match(/huggingface\.co\/buckets\/[^#\s]+#(.+)/))) {
+      return { kind: "artifact", id: decodeURIComponent(m[1]), url };
+    }
+    if (/huggingface\.co\/datasets\/[^/]+\/[^/]+/.test(url)) {
+      return { kind: "dataset", id: hfId(url, "/datasets/"), url };
+    }
+    if (/huggingface\.co\/spaces\/[^/]+\/[^/]+/.test(url)) {
+      return { kind: "space", id: hfId(url, "/spaces/"), url };
+    }
+    if (/huggingface\.co\/jobs\//.test(url)) {
+      const parts = hfId(url, "/jobs/").split("/");
+      const jid = parts[1] || "";
+      return {
+        kind: "job",
+        id: parts[0] + (jid ? ` · ${jid.slice(0, 12)}${jid.length > 12 ? "…" : ""}` : ""),
+        url,
+      };
+    }
+    if (/huggingface\.co\/buckets\//.test(url)) {
+      return { kind: "bucket", id: hfId(url, "/buckets/"), url };
+    }
+    if (/huggingface\.co\/papers\//.test(url)) {
+      return { kind: "paper", id: `Paper ${hfId(url, "/papers/")}`, url };
+    }
+    if ((m = url.match(/arxiv\.org\/(?:abs|pdf)\/([^?#\s]+)/))) {
+      return { kind: "paper", id: `arXiv:${m[1].replace(/\.pdf$/, "")}`, url };
+    }
+    if ((m = url.match(/github\.com\/([^/?#]+\/[^/?#]+)/))) {
+      return { kind: "repo", id: m[1], url };
+    }
+    if ((m = url.match(/huggingface\.co\/([^?#]+)/))) {
+      const rest = m[1].replace(/\/$/, "");
+      if (/^[^/]+\/[^/]+$/.test(rest) && !HF_NON_MODEL_PREFIX.test(rest)) {
+        return { kind: "model", id: rest, url };
+      }
+    }
+    return null;
+  }
+
+  async function fillRailMeta(item, el) {
+    if (item.local) return;
+    const meta = el.querySelector(".rail-meta");
+    const set = (parts) => {
+      const text = parts.filter(Boolean).join(" · ");
+      if (text) meta.textContent = text;
+    };
+    if (item.kind === "model") {
+      const d = await getJSON(`https://huggingface.co/api/models/${item.id}`);
+      if (d) set([d.pipeline_tag, `↓ ${fmt(d.downloads)}`, `♥ ${fmt(d.likes)}`]);
+    } else if (item.kind === "dataset") {
+      const d = await getJSON(`https://huggingface.co/api/datasets/${item.id}`);
+      if (d) set([`↓ ${fmt(d.downloads)}`, `♥ ${fmt(d.likes)}`]);
+    } else if (item.kind === "space" || item.kind === "dashboard") {
+      const d = await getJSON(`https://huggingface.co/api/spaces/${item.id}`);
+      if (d) set([d.sdk, `♥ ${fmt(d.likes)}`]);
+    } else if (item.kind === "repo") {
+      const d = await getJSON(`https://api.github.com/repos/${item.id}`);
+      if (d) set([`★ ${fmt(d.stargazers_count)}`, d.language]);
+    } else if (item.kind === "paper") {
+      const m = item.id.match(/^(?:arXiv:|Paper )(.+)$/);
+      if (!m) return;
+      const arxivId = m[1].replace(/v\d+$/, "");
+      const d = await getJSON(`https://huggingface.co/api/papers/${arxivId}`);
+      if (d && d.id) {
+        if (el.href) el.href = `https://huggingface.co/papers/${d.id}`;
+        const title =
+          d.title && d.title.length > 70 ? `${d.title.slice(0, 69)}…` : d.title;
+        set([title, d.upvotes ? `▲ ${fmt(d.upvotes)}` : null]);
+      }
+    }
+  }
+
+  const BARE_ID_SKIP_DIRS = new Set([
+    "scripts",
+    "configs",
+    "config",
+    "results",
+    "figures",
+    "data",
+    "datasets",
+    "src",
+    "tests",
+    "test",
+    "examples",
+    "pages",
+    "assets",
+    "docs",
+    "outputs",
+    "output",
+    "checkpoints",
+    "models",
+    "utils",
+    "lib",
+    "bin",
+    "tmp",
+    "node_modules",
+    "dist",
+    "build",
+  ]);
+  const FILE_EXT_RE =
+    /\.(py|pyc|js|ts|jsx|tsx|json|jsonl|yaml|yml|csv|tsv|md|txt|sh|bash|html|css|png|jpe?g|svg|gif|webp|ipynb|toml|cfg|ini|lock|pdf|whl|gz|zip|tar|pt|pth|bin|safetensors|db|sqlite)$/i;
+
+  async function detectBareModelIds(text, groups) {
+    const stripped = text.replace(DETECTED_URL, " ");
+    DETECTED_URL.lastIndex = 0;
+    const seen = new Set();
+    const candidates = [];
+    const re = /(^|[\s"'`(=[])([A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.-]*)/g;
+    let m;
+    while ((m = re.exec(stripped)) && candidates.length < 15) {
+      const id = m[2].replace(/[.:,]+$/, "");
+      if (seen.has(id)) continue;
+      seen.add(id);
+      if (FILE_EXT_RE.test(id)) continue;
+      if (BARE_ID_SKIP_DIRS.has(id.split("/")[0].toLowerCase())) continue;
+      candidates.push(id);
+    }
+    const results = await Promise.all(
+      candidates.map((id) => getJSON(`https://huggingface.co/api/models/${id}`))
+    );
+    let added = false;
+    const confirmed = [];
+    results.forEach((d, i) => {
+      if (!d || !d.id) return;
+      const id = candidates[i];
+      confirmed.push(id);
+      const url = `https://huggingface.co/${id}`;
+      if (!groups.has("model")) groups.set("model", new Map());
+      if (!groups.get("model").has(url)) {
+        groups.get("model").set(url, { kind: "model", id, url });
+        added = true;
+      }
+    });
+    return { added, confirmed };
+  }
+
+  function chipifyBareIds(ids, container) {
+    if (!ids.length) return;
+    const escaped = ids.map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    const pattern = new RegExp("(" + escaped.join("|") + ")");
+    const splitter = new RegExp(pattern.source, "g");
+    container
+      .querySelectorAll(".cell.markdown .cell-body")
+      .forEach((body) => {
+        const walker = document.createTreeWalker(body, NodeFilter.SHOW_TEXT, {
+          acceptNode(node) {
+            if (!pattern.test(node.nodeValue)) return NodeFilter.FILTER_REJECT;
+            for (
+              let el = node.parentElement;
+              el && el !== body;
+              el = el.parentElement
+            ) {
+              if (["A", "CODE", "PRE", "BUTTON"].indexOf(el.tagName) !== -1) {
+                return NodeFilter.FILTER_REJECT;
+              }
+            }
+            return NodeFilter.FILTER_ACCEPT;
+          },
+        });
+        const nodes = [];
+        while (walker.nextNode()) nodes.push(walker.currentNode);
+        nodes.forEach((node) => {
+          const frag = document.createDocumentFragment();
+          node.nodeValue.split(splitter).forEach((part) => {
+            if (ids.indexOf(part) !== -1) {
+              const holder = document.createElement("span");
+              holder.innerHTML = resChipHtml({
+                kind: "model",
+                id: part,
+                url: `https://huggingface.co/${part}`,
+              });
+              frag.appendChild(holder.firstChild);
+            } else if (part) {
+              frag.appendChild(document.createTextNode(part));
+            }
+          });
+          node.parentNode.replaceChild(frag, node);
+        });
+      });
+  }
+
+  let RAIL_TOKEN = 0;
+  const RAIL_EXCLUDE_KINDS = new Set(["paper", "repo", "artifact", "dashboard"]);
+
+  function railDashboardItem(it) {
+    return {
+      kind: "dashboard",
+      id: it.id,
+      url: it.local ? it.resUrl : it.url || it.resUrl,
+      local: it.local,
+      railLabel: "Dashboard",
+    };
+  }
+
+  function promoteTrackioSpacesInRail(groups, dashResUrls, body, rail, token) {
+    const spaceGroup = groups.get("space");
+    if (!spaceGroup || !spaceGroup.size) return;
+    spaceGroup.forEach((item, url) => {
+      getJSON(`https://huggingface.co/api/spaces/${item.id}`)
+        .then((d) => {
+          if (rail.dataset.renderToken !== token) return;
+          const tags = (d && d.tags) || [];
+          if (!tags.some((t) => String(t).toLowerCase() === "trackio")) return;
+          if (dashResUrls.has(url)) return;
+          spaceGroup.delete(url);
+          if (!spaceGroup.size) groups.delete("space");
+          if (!groups.has("dashboard")) groups.set("dashboard", new Map());
+          groups.get("dashboard").set(url, {
+            kind: "dashboard",
+            id: item.id,
+            url: item.url,
+            local: false,
+            railLabel: "Dashboard",
+          });
+          dashResUrls.add(url);
+          paintRail(groups, body, rail);
+        })
+        .catch(() => {});
+    });
+  }
+
+  function renderRail(md, body, rail) {
+    const token = String(++RAIL_TOKEN);
+    rail.dataset.renderToken = token;
+    const scanText = md.replace(
+      /(`{3,4}|~{3,4})(html|raw)[^\n]*\n[\s\S]*?\n\1/g,
+      " "
+    );
+    const groups = new Map();
+    const dashMap = new Map();
+    const dashResUrls = new Set();
+    cellDashboardItems(md).forEach((it) => {
+      if (dashMap.has(it.resUrl)) return;
+      dashMap.set(it.resUrl, railDashboardItem(it));
+      dashResUrls.add(it.resUrl);
+    });
+    if (dashMap.size) groups.set("dashboard", dashMap);
+    extractUrls(scanText).forEach((url) => {
+      const item = classifyResource(url);
+      if (!item) return;
+      if (RAIL_EXCLUDE_KINDS.has(item.kind)) return;
+      if (dashResUrls.has(url)) return;
+      if (!groups.has(item.kind)) groups.set(item.kind, new Map());
+      groups.get(item.kind).set(item.url, item);
+    });
+    const artMap = new Map();
+    cellArtifactItems(md).forEach((it) => {
+      if (artMap.has(it.resUrl)) return;
+      const label = it.type
+        ? it.type.charAt(0).toUpperCase() + it.type.slice(1)
+        : "Artifact";
+      artMap.set(it.resUrl, {
+        kind: "artifact",
+        id: it.name,
+        url: it.local ? it.resUrl : it.url || it.resUrl,
+        local: it.local,
+        railLabel: label,
+        size: it.size,
+      });
+    });
+    if (artMap.size) groups.set("artifact", artMap);
+    paintRail(groups, body, rail);
+    promoteTrackioSpacesInRail(groups, dashResUrls, body, rail, token);
+    detectBareModelIds(scanText, groups)
+      .then((result) => {
+        if (rail.dataset.renderToken !== token) return;
+        chipifyBareIds(result.confirmed, body);
+        if (result.added) paintRail(groups, body, rail);
+      })
+      .catch(() => {});
+  }
+
+  function paintRail(groups, body, rail) {
+    rail.innerHTML = "";
+    RESOURCE_SECTIONS.forEach(([kind, label, icon]) => {
+      const group = groups.get(kind);
+      if (!group || !group.size) return;
+      group.forEach((item) => {
+        const el = document.createElement(item.local ? "div" : "a");
+        el.className = item.local ? "rail-item rail-local" : "rail-item";
+        if (!item.local) {
+          el.href = item.url;
+          el.target = "_blank";
+          el.rel = "noopener";
+        }
+        el.dataset.resUrl = item.url;
+        let desc;
+        if (kind === "artifact") {
+          const state = item.local ? "publish to share" : "Open ↗";
+          desc = item.size ? `${item.size} · ${state}` : state;
+        } else if (kind === "dashboard") {
+          desc = item.local ? "publish to share" : "Open ↗";
+        } else {
+          desc = item.local ? "publish to share" : RESOURCE_DESC[kind];
+        }
+        const kindLabel = item.railLabel || label.replace(/s$/, "");
+        const iconHtml =
+          kind === "artifact"
+            ? ARTIFACT_ICON_IMG
+            : kind === "dashboard"
+              ? DASHBOARD_ICON_IMG
+              : `<span>${icon}</span>`;
+        el.innerHTML =
+          `<div class="rail-kind">${iconHtml}${esc(kindLabel)}</div>` +
+          `<div class="rail-title">${esc(item.id)}</div>` +
+          `<div class="rail-meta">${esc(desc)}</div>`;
+        rail.appendChild(el);
+        fillRailMeta(item, el)
+          .catch(() => {})
+          .finally(() => scheduleRailPosition(body, rail));
+      });
+    });
+    rail.hidden = !rail.childElementCount;
+    scheduleRailPosition(body, rail);
+  }
+
+  function resourceAnchor(body, url) {
+    return body.querySelector(`[data-res-url="${CSS.escape(url)}"]`);
+  }
+
+  function positionRail(body, rail) {
+    if (rail.hidden || !rail.isConnected) return;
+    const bodyRect = body.getBoundingClientRect();
+    const items = Array.from(rail.querySelectorAll(".rail-item")).map((el, index) => {
+      const anchor = resourceAnchor(body, el.dataset.resUrl);
+      return {
+        el,
+        index,
+        desired: anchor
+          ? Math.max(0, anchor.getBoundingClientRect().top - bodyRect.top)
+          : 0,
+      };
+    });
+    items.sort((a, b) => a.desired - b.desired || a.index - b.index);
+    let cursor = 0;
+    items.forEach(({ el, desired }) => {
+      const top = Math.max(desired, cursor);
+      el.style.top = `${top}px`;
+      cursor = top + el.offsetHeight + 10;
+    });
+    rail.style.minHeight = `${Math.max(body.offsetHeight, cursor)}px`;
+  }
+
+  function scheduleRailPosition(body, rail) {
+    cancelAnimationFrame(Number(rail.dataset.positionFrame || 0));
+    rail.dataset.positionFrame = String(
+      requestAnimationFrame(() => positionRail(body, rail))
+    );
+  }
+
+  function dashboardSubdomainFromUrl(url) {
+    return spaceIdFromUrl(url).toLowerCase().replace(/[^a-z0-9-]/g, "-");
+  }
+
+  function dashboardOpenLink(head, url) {
+    if (!head || !url) return;
+    const meta = head.querySelector(".cell-meta");
+    if (!meta) return;
+    let link = meta.querySelector(".cell-open");
+    if (!link) {
+      link = document.createElement("a");
+      link.className = "cell-open";
+      link.target = "_blank";
+      link.rel = "noopener";
+      meta.insertBefore(link, meta.firstChild);
+    }
+    link.href = url;
+    link.textContent = "Open ↗";
+  }
+
+  function dashboardFrame(src) {
+    const iframe = document.createElement("iframe");
+    iframe.className = "dashboard-frame";
+    iframe.src = src;
+    iframe.loading = "lazy";
+    iframe.allow = "clipboard-read; clipboard-write; fullscreen";
+    return iframe;
+  }
+
+  function renderDashboardCell(meta, body, container, head) {
+    const project = meta.dashboard_project || "";
+    const holder = document.createElement("div");
+    holder.className = "dashboard-shell";
+    container.appendChild(holder);
+    const space = body.match(/https:\/\/huggingface\.co\/spaces\/[^\s<>)"'`]+/);
+    if (space) {
+      const url = space[0];
+      dashboardOpenLink(head, url);
+      holder.appendChild(
+        dashboardFrame(
+          `https://${dashboardSubdomainFromUrl(url)}.hf.space/?sidebar=hidden&hide_empty_tabs=true`
+        )
+      );
+      return;
+    }
+    if (!isLocalPreview()) {
+      holder.className = "artifact-chip";
+      holder.dataset.resUrl = `trackio-local-dashboard://${project}`;
+      holder.innerHTML =
+        "🎯 <strong>Local Trackio dashboard</strong> — publish the logbook to share it";
+      return;
+    }
+    const open = "/dashboard/?project=" + encodeURIComponent(project);
+    dashboardOpenLink(head, open);
+    holder.appendChild(
+      dashboardFrame(open + "&sidebar=hidden&hide_empty_tabs=true"),
+    );
+  }
+
+  const CACHE_PREFIX = "trackio-logbook:";
+  const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+  const CACHE_MISS_TTL_MS = 60 * 60 * 1000;
+
+  function cacheGet(url) {
+    try {
+      const raw = localStorage.getItem(CACHE_PREFIX + url);
+      if (!raw) return undefined;
+      const entry = JSON.parse(raw);
+      const ttl = entry.d === null ? CACHE_MISS_TTL_MS : CACHE_TTL_MS;
+      if (Date.now() - entry.t > ttl) {
+        localStorage.removeItem(CACHE_PREFIX + url);
+        return undefined;
+      }
+      return entry.d;
+    } catch (e) {
+      return undefined;
+    }
+  }
+
+  function cacheSet(url, data) {
+    try {
+      localStorage.setItem(
+        CACHE_PREFIX + url,
+        JSON.stringify({ t: Date.now(), d: data })
+      );
+    } catch (e) {}
+  }
+
+  async function getJSON(url) {
+    if (UNFURL_CACHE[url] !== undefined) return UNFURL_CACHE[url];
+    const cached = cacheGet(url);
+    if (cached !== undefined) {
+      UNFURL_CACHE[url] = cached;
+      return cached;
+    }
+    try {
+      const r = await fetch(url);
+      if (!r.ok) throw new Error(r.status);
+      const j = await r.json();
+      UNFURL_CACHE[url] = j;
+      cacheSet(url, j);
+      return j;
+    } catch (e) {
+      UNFURL_CACHE[url] = null;
+      cacheSet(url, null);
+      return null;
+    }
+  }
+
+  /* -------------------- routing / render -------------------- */
+
+  function buildTree() {
+    const tree = document.getElementById("tree");
+    tree.innerHTML = "";
+    const nodes = [];
+    (MANIFEST.root.children || []).forEach((c) => flattenTree(c, 0, nodes));
+    nodes.forEach(({ node, depth }) => {
+      const a = document.createElement("a");
+      a.href = "#/" + node.slug;
+      a.className = "depth-" + depth;
+      a.dataset.slug = node.slug;
+      const mark = document.createElement("span");
+      mark.className = "tree-mark";
+      mark.textContent = "§";
+      a.appendChild(mark);
+      a.appendChild(document.createTextNode(" " + node.title));
+      tree.appendChild(a);
+    });
+  }
+
+  function highlight(slug) {
+    document
+      .querySelectorAll("#tree a")
+      .forEach((a) => a.classList.toggle("active", a.dataset.slug === slug));
+    document
+      .getElementById("book-head")
+      .classList.toggle("active", slug === MANIFEST.root.slug);
+  }
+
+  function clearPageCache() {
+    Object.keys(PAGE_CACHE).forEach((key) => {
+      delete PAGE_CACHE[key];
+    });
+  }
+
+  function isLocalPreview() {
+    return ["localhost", "127.0.0.1", "::1"].includes(location.hostname);
+  }
+
+  async function fetchManifest() {
+    const suffix = isLocalPreview() ? `?t=${Date.now()}` : "";
+    return await (await fetch("./logbook.json" + suffix, { cache: "no-store" })).json();
+  }
+
+  async function fetchPage(node) {
+    if (PAGE_CACHE[node.file]) return PAGE_CACHE[node.file];
+    try {
+      const suffix = isLocalPreview()
+        ? `?rev=${encodeURIComponent(MANIFEST.revision || "")}`
+        : "";
+      const r = await fetch("./" + node.file + suffix, { cache: "no-store" });
+      PAGE_CACHE[node.file] = await r.text();
+    } catch (e) {
+      PAGE_CACHE[node.file] = "# " + node.title + "\n\n_Could not load section._";
+    }
+    return PAGE_CACHE[node.file];
+  }
+
+  function allNodes() {
+    const nodes = [];
+    flattenTree(MANIFEST.root, 0, nodes);
+    return nodes.map(({ node }) => node);
+  }
+
+  function collectPinnedCells(markdown, nodes) {
+    const cells = [];
+    markdown.forEach((text, index) => {
+      const cellRe = /(^|\n)---\n<!-- trackio-cell\n([\s\S]*?)\n-->\n([\s\S]*?)(?=\n---\n<!-- trackio-cell\n|\s*$)/g;
+      let match;
+      let cellIndex = 0;
+      while ((match = cellRe.exec(text))) {
+        const meta = parseCellMeta(match[2]);
+        if (isPinned(meta)) {
+          cells.push({
+            meta,
+            body: match[3],
+            node: nodes[index],
+            index: cells.length,
+            order: meta.pinned_at || meta.created_at || "",
+            cellIndex,
+          });
+        }
+        cellIndex++;
+      }
+    });
+    return cells.sort(
+      (a, b) =>
+        a.order.localeCompare(b.order) ||
+        a.index - b.index ||
+        a.cellIndex - b.cellIndex
+    );
+  }
+
+  function renderPinnedNotes(cells, container) {
+    if (!cells.length) return;
+    const deck = document.createElement("section");
+    deck.className = "pinned-notes";
+    const list = document.createElement("div");
+    list.className = "pinned-notes-list";
+    cells.forEach(({ meta, body }) => {
+      const cell = renderCell(meta, body, list);
+      cell.classList.add("pinned-copy");
+    });
+    deck.appendChild(list);
+    const anchor =
+      container.querySelector(".logbook-stats") ||
+      container.querySelector(".agent-hint");
+    container.insertBefore(deck, anchor ? anchor.nextSibling : container.firstChild);
+    container.closest(".book-intro").classList.add("has-pinned-notes");
+  }
+
+  function removeIndexProse(body) {
+    const h1 = Array.from(body.children).find((el) => el.tagName === "H1");
+    if (!h1) return;
+    let current = h1.nextElementSibling;
+    while (current && current.tagName !== "H2") {
+      const next = current.nextElementSibling;
+      current.remove();
+      current = next;
+    }
+  }
+
+  function removePageDirectory(body) {
+    const heading = Array.from(body.children).find(
+      (el) => el.tagName === "H2" && el.textContent.trim().toLowerCase() === "pages"
+    );
+    if (!heading) return;
+    let current = heading;
+    while (current) {
+      const next = current.nextElementSibling;
+      current.remove();
+      if (next && ["H1", "H2"].includes(next.tagName)) break;
+      current = next;
+    }
+  }
+
+  const RAIL_OBSERVERS = [];
+
+  async function renderLogbook(opts = {}) {
+    const scrollY = window.scrollY;
+    const page = document.getElementById("page");
+    RAIL_OBSERVERS.splice(0).forEach((observer) => observer.disconnect());
+    page.innerHTML = "";
+    const nodes = allNodes();
+    const markdown = await Promise.all(nodes.map(fetchPage));
+    const pinnedCells = collectPinnedCells(markdown, nodes);
+    let bookIntroBody = null;
+    nodes.forEach((node, index) => {
+      const section = document.createElement("section");
+      section.className = "page-section";
+      section.id = "/" + node.slug;
+      section.dataset.slug = node.slug;
+
+      const layout = document.createElement("div");
+      layout.className = "page-layout";
+      const body = document.createElement("div");
+      body.className = "page-body";
+      const rail = document.createElement("aside");
+      rail.className = "context-rail";
+      rail.setAttribute("aria-label", `Resources for ${node.title}`);
+
+      renderMarkdown(markdown[index], body);
+      if (node.slug === MANIFEST.root.slug) {
+        section.classList.add("book-intro");
+        removeIndexProse(body);
+        removePageDirectory(body);
+        const hint = buildAgentHint();
+        const h1 = body.querySelector("h1");
+        if (h1 && h1.parentNode === body) {
+          body.insertBefore(hint, h1.nextSibling);
+        } else {
+          body.prepend(hint);
+        }
+        hint.after(buildLogbookStats(markdown));
+        bookIntroBody = body;
+      }
+      layout.appendChild(body);
+      layout.appendChild(rail);
+      section.appendChild(layout);
+      page.appendChild(section);
+      renderRail(markdown[index], body, rail);
+      if (window.ResizeObserver) {
+        const observer = new ResizeObserver(() => scheduleRailPosition(body, rail));
+        observer.observe(body);
+        observer.observe(rail);
+        RAIL_OBSERVERS.push(observer);
+      }
+    });
+    if (bookIntroBody) renderPinnedNotes(pinnedCells, bookIntroBody);
+    if (bookIntroBody) {
+      const section = bookIntroBody.closest(".book-intro");
+      const hasExtra = Array.from(bookIntroBody.children).some(
+        (el) =>
+          el.tagName !== "H1" &&
+          !el.classList.contains("agent-hint") &&
+          !el.classList.contains("logbook-stats") &&
+          !el.classList.contains("pinned-notes")
+      );
+      if (section && !section.classList.contains("has-pinned-notes") && !hasExtra) {
+        section.classList.add("book-intro-tight");
+      }
+    }
+    requestAnimationFrame(() => {
+      if (opts.preserveScroll) {
+        window.scrollTo(0, scrollY);
+      } else {
+        scrollToHash({ behavior: "auto" });
+      }
+      updateActiveSection();
+    });
+  }
+
+  function setupResourceHover() {
+    document.addEventListener("mouseover", (e) => {
+      const el = e.target.closest && e.target.closest("[data-res-url]");
+      if (!el || el.classList.contains("rail-item")) return;
+      const url = el.getAttribute("data-res-url");
+      const section = el.closest(".page-section");
+      const scope = section || document;
+      scope.querySelectorAll(".context-rail [data-res-url]").forEach((n) => {
+        n.classList.toggle("res-hl", n.getAttribute("data-res-url") === url);
+      });
+    });
+    document.addEventListener("mouseout", (e) => {
+      const el = e.target.closest && e.target.closest("[data-res-url]");
+      if (!el || el.classList.contains("rail-item")) return;
+      document.querySelectorAll(".context-rail .res-hl").forEach((n) => {
+        n.classList.remove("res-hl");
+      });
+    });
+  }
+
+  let STATS_TOKEN = 0;
+  let STATS_LISTENERS = false;
+
+  function fmtBytes(n) {
+    if (n == null || isNaN(n)) return null;
+    if (n < 1000) return `${n} B`;
+    const units = ["kB", "MB", "GB", "TB"];
+    let v = n;
+    let i = -1;
+    do {
+      v /= 1000;
+      i++;
+    } while (v >= 1000 && i < units.length - 1);
+    return `${v.toFixed(v < 10 ? 1 : 0)} ${units[i]}`;
+  }
+
+  function spaceIdFromUrl(url) {
+    return url.split("/spaces/")[1].split(/[?#]/)[0].replace(/\/$/, "");
+  }
+
+  const LB_CELL_RE = /(^|\n)---\n<!-- trackio-cell\n([\s\S]*?)\n-->\n([\s\S]*?)(?=\n---\n<!-- trackio-cell\n|\s*$)/g;
+
+  function cellDashboardItems(md) {
+    const re = new RegExp(LB_CELL_RE.source, "g");
+    const items = [];
+    let m;
+    while ((m = re.exec(md))) {
+      const meta = parseCellMeta(m[2]);
+      if (meta.type !== "dashboard") continue;
+      const body = m[3];
+      const project = meta.dashboard_project || "";
+      const sp = body.match(/https:\/\/huggingface\.co\/spaces\/[^\s<>)"'`]+/);
+      const local = !sp;
+      const url = sp ? sp[0] : "";
+      const resUrl = local ? `trackio-local-dashboard://${project}` : url;
+      items.push({
+        id: local ? project : spaceIdFromUrl(url),
+        local,
+        url,
+        resUrl,
+      });
+    }
+    return items;
+  }
+
+  function artifactInfoFromCell(meta, body) {
+    const name = meta.artifact || meta.path || "";
+    let size = null;
+    const sm = body.match(/·\s*([\d.]+\s*[kMGT]?B)\b/);
+    if (sm) size = sm[1].trim();
+    if (!size && meta.size != null) size = fmtBytes(meta.size);
+    const bucket = body.match(/https:\/\/huggingface\.co\/buckets\/[^\s<>)"'`]+/);
+    const artUri = body.match(/trackio-artifact:\/\/\S+/);
+    const pathUri = body.match(/trackio-local-path:\/\/\S+/);
+    const url = bucket ? bucket[0] : "";
+    const local = !bucket;
+    const resUrl =
+      url || (artUri ? artUri[0] : pathUri ? pathUri[0] : `trackio-artifact://${name}`);
+    return {
+      name,
+      type: meta.artifact_type || "",
+      size,
+      local,
+      isPathRef: !!meta.path,
+      url,
+      resUrl,
+    };
+  }
+
+  function cellArtifactItems(md) {
+    const re = new RegExp(LB_CELL_RE.source, "g");
+    const items = [];
+    let m;
+    while ((m = re.exec(md))) {
+      const meta = parseCellMeta(m[2]);
+      const body = m[3];
+      const order = meta.created_at || "";
+      if (meta.type === "artifact") {
+        const info = artifactInfoFromCell(meta, body);
+        if (info.name) items.push({ ...info, order });
+      }
+    }
+    return items;
+  }
+
+  function collectLogbookResources(markdownList) {
+    const re = new RegExp(LB_CELL_RE.source, "g");
+    const dashboards = new Map();
+    markdownList.forEach((md) => {
+      let m;
+      while ((m = re.exec(md))) {
+        const meta = parseCellMeta(m[2]);
+        const body = m[3];
+        if (meta.type !== "dashboard") continue;
+        const project = meta.dashboard_project || "";
+        const space = body.match(/https:\/\/huggingface\.co\/spaces\/[^\s<>)"'`]+/);
+        const local = !space;
+        const url = space ? space[0] : "";
+        const key = local ? `local:${project}` : `space:${spaceIdFromUrl(url)}`;
+        const resUrl = local ? `trackio-local-dashboard://${project}` : url;
+        if (!dashboards.has(key))
+          dashboards.set(key, { project, local, url, resUrl });
+      }
+    });
+    const artifacts = new Map();
+    markdownList.forEach((md) => {
+      cellArtifactItems(md).forEach((it) => {
+        const key = `${it.type}:${it.name}`;
+        const prev = artifacts.get(key);
+        if (!prev || it.order >= prev.order) artifacts.set(key, it);
+      });
+    });
+    return {
+      dashboards: Array.from(dashboards.values()).sort((a, b) =>
+        a.project.localeCompare(b.project)
+      ),
+      artifacts: Array.from(artifacts.values()).sort((a, b) =>
+        a.name.localeCompare(b.name)
+      ),
+    };
+  }
+
+  function closeStatPopovers() {
+    document
+      .querySelectorAll(".stat-popover")
+      .forEach((p) => (p.hidden = true));
+    document
+      .querySelectorAll(".stat-tile.open")
+      .forEach((t) => t.classList.remove("open"));
+  }
+
+  function ensureStatListeners() {
+    if (STATS_LISTENERS) return;
+    STATS_LISTENERS = true;
+    document.addEventListener("click", closeStatPopovers);
+    document.addEventListener("keydown", (e) => {
+      if (e.key === "Escape") closeStatPopovers();
+    });
+  }
+
+  function stateHtml(remote, url) {
+    return remote
+      ? `<a class="stat-row-state open" href="${esc(url)}" target="_blank" rel="noopener" title="Open in a new tab">Open ↗</a>`
+      : `<span class="stat-row-state">publish to share</span>`;
+  }
+
+  function scrollToResource(resUrl) {
+    closeStatPopovers();
+    if (!resUrl) return;
+    const el = document.querySelector(
+      `#page .page-body [data-res-url="${CSS.escape(resUrl)}"]:not(.stat-row)`
+    );
+    if (!el) return;
+    el.scrollIntoView({ behavior: "smooth", block: "center" });
+    el.classList.add("res-flash");
+    setTimeout(() => el.classList.remove("res-flash"), 1500);
+  }
+
+  function dashRowHtml(d) {
+    const inner =
+      `<span class="stat-row-ico">${DASHBOARD_ICON_IMG}</span>` +
+      `<div class="stat-row-main"><div class="stat-row-title">${esc(d.project)}</div>` +
+      `<div class="stat-row-meta">${stateHtml(!d.local, d.url)}</div></div>`;
+    return `<div class="stat-row" data-res-url="${esc(d.resUrl)}" title="Jump to it in the logbook">${inner}</div>`;
+  }
+
+  function artRowHtml(a) {
+    const remote = !a.local && !!a.url;
+    const parts = [a.type, a.size].filter(Boolean).map(esc);
+    const meta = parts.length
+      ? `${parts.join(" · ")} · ${stateHtml(remote, a.url)}`
+      : stateHtml(remote, a.url);
+    const inner =
+      `<span class="stat-row-ico">${ARTIFACT_ICON_IMG}</span>` +
+      `<div class="stat-row-main"><div class="stat-row-title">${esc(a.name)}</div>` +
+      `<div class="stat-row-meta">${meta}</div></div>`;
+    return `<div class="stat-row" data-res-url="${esc(a.resUrl)}" title="Jump to it in the logbook">${inner}</div>`;
+  }
+
+  function statTile(icon, alt, singular, plural, head, rowFn) {
+    const tile = document.createElement("button");
+    tile.type = "button";
+    tile.className = "stat-tile";
+    const render = (items) => {
+      const count = items.length;
+      const label = count === 1 ? singular : plural;
+      const caret = count > 0 ? `<span class="stat-caret">▾</span>` : "";
+      tile.innerHTML =
+        `<img class="stat-icon" src="${icon}" alt="${esc(alt)}" />` +
+        `<div class="stat-text"><div class="stat-num">${count}</div>` +
+        `<div class="stat-label">${esc(label)}</div></div>` +
+        caret;
+      tile.disabled = count === 0;
+      if (count > 0) {
+        const pop = document.createElement("div");
+        pop.className = "stat-popover";
+        pop.hidden = true;
+        pop.innerHTML =
+          `<div class="stat-pop-head">${esc(head)}</div>` +
+          items.map(rowFn).join("");
+        pop.addEventListener("click", (e) => {
+          if (e.target.closest("a.stat-row-state")) {
+            e.stopPropagation();
+            return;
+          }
+          e.stopPropagation();
+          const row = e.target.closest(".stat-row");
+          if (row) scrollToResource(row.dataset.resUrl);
+        });
+        tile.appendChild(pop);
+      }
+    };
+    tile.addEventListener("click", (e) => {
+      if (tile.disabled) return;
+      e.stopPropagation();
+      const pop = tile.querySelector(".stat-popover");
+      if (!pop) return;
+      const isOpen = !pop.hidden;
+      closeStatPopovers();
+      if (!isOpen) {
+        pop.hidden = false;
+        tile.classList.add("open");
+      }
+    });
+    return { tile, render };
+  }
+
+  function buildLogbookStats(markdownList) {
+    const token = ++STATS_TOKEN;
+    ensureStatListeners();
+    const { dashboards, artifacts } = collectLogbookResources(markdownList);
+
+    const el = document.createElement("div");
+    el.className = "logbook-stats";
+    const dash = statTile(
+      "./trackio-logo-light.png",
+      "Trackio",
+      "Trackio Dashboard",
+      "Trackio Dashboards",
+      "Dashboards created in this logbook",
+      dashRowHtml
+    );
+    const art = statTile(
+      "./bucket-icon.svg",
+      "Bucket",
+      "Artifact",
+      "Artifacts",
+      "Artifacts created in this logbook",
+      artRowHtml
+    );
+    dash.render(dashboards);
+    art.render(artifacts);
+    el.appendChild(dash.tile);
+    el.appendChild(art.tile);
+
+    const scanText = markdownList
+      .map((md) =>
+        md.replace(/(`{3,4}|~{3,4})(html|raw)[^\n]*\n[\s\S]*?\n\1/g, " ")
+      )
+      .join("\n");
+    const seen = new Set(
+      dashboards.map((d) =>
+        d.local ? `local:${d.project}` : `space:${spaceIdFromUrl(d.url)}`
+      )
+    );
+    const remoteSpaces = new Map();
+    extractUrls(scanText).forEach((url) => {
+      const item = classifyResource(url);
+      if (item && item.kind === "space" && !item.local) {
+        remoteSpaces.set(item.url, item);
+      }
+    });
+    remoteSpaces.forEach((s) => {
+      const key = `space:${s.id}`;
+      if (seen.has(key)) return;
+      getJSON(`https://huggingface.co/api/spaces/${s.id}`)
+        .then((d) => {
+          if (STATS_TOKEN !== token) return;
+          const tags = (d && d.tags) || [];
+          if (
+            !seen.has(key) &&
+            tags.some((t) => String(t).toLowerCase() === "trackio")
+          ) {
+            seen.add(key);
+            dashboards.push({
+              project: s.id,
+              local: false,
+              url: s.url,
+              resUrl: s.url,
+            });
+            dashboards.sort((a, b) => a.project.localeCompare(b.project));
+            dash.render(dashboards);
+          }
+        })
+        .catch(() => {});
+    });
+    return el;
+  }
+
+  function buildAgentHint() {
+    const onSpaces =
+      /\.hf\.space$/.test(location.hostname) ||
+      /(^|\.)huggingface\.co$/.test(location.hostname);
+    let source = "";
+    if (onSpaces && MANIFEST.space_id) {
+      source = ` ${MANIFEST.space_id}`;
+    } else if (/^https?:$/.test(location.protocol)) {
+      source = ` ${location.origin}/`;
+    }
+    const command = `trackio logbook read${source}`;
+    const tokens = MANIFEST.agent_view_tokens;
+    const div = document.createElement("div");
+    div.className = "agent-hint";
+    const label = document.createElement("span");
+    label.className = "agent-hint-label";
+    label.textContent = "Read from the CLI:";
+    const code = document.createElement("code");
+    code.textContent = command;
+    const copy = document.createElement("button");
+    copy.className = "copy";
+    copy.type = "button";
+    copy.title = "Copy";
+    copy.textContent = "⧉";
+    copy.addEventListener("click", () => copyText(command, copy, "⧉"));
+    const note = document.createElement("span");
+    note.className = "agent-hint-note";
+    note.textContent =
+      "compact view for agents" + (tokens ? ` · ~${fmt(tokens)} tokens` : "");
+    div.appendChild(label);
+    div.appendChild(code);
+    div.appendChild(copy);
+    div.appendChild(note);
+    return div;
+  }
+
+  function currentSlug() {
+    const slug = (location.hash || "").replace(/^#\//, "") || MANIFEST.root.slug;
+    return findNode(MANIFEST.root, slug) ? slug : MANIFEST.root.slug;
+  }
+
+  function scrollToHash(opts = {}) {
+    const slug = currentSlug();
+    if (!location.hash) {
+      window.scrollTo({ top: 0, behavior: opts.behavior || "auto" });
+      highlight(slug);
+      return;
+    }
+    const section = document.getElementById("/" + slug);
+    if (section) section.scrollIntoView({ behavior: opts.behavior || "smooth" });
+    highlight(slug);
+  }
+
+  function navigateToLogbookSlug(target) {
+    const slug = String(target || "").replace(/^#?\//, "").trim();
+    if (!slug || !findNode(MANIFEST.root, slug)) return;
+    const hash = "#/" + slug;
+    if (location.hash === hash) {
+      scrollToHash({ behavior: "smooth" });
+    } else {
+      location.hash = hash;
+    }
+  }
+
+  function setupFigureNavigation() {
+    window.addEventListener("message", (event) => {
+      const data = event.data;
+      if (!data || data.type !== "trackio-logbook:navigate") return;
+      // Only accept messages from one of this logbook's sandboxed figure
+      // iframes, rather than from an arbitrary same-origin page.
+      const isFigureFrame = Array.from(
+        document.querySelectorAll("iframe.figure-frame")
+      ).some((frame) => frame.contentWindow === event.source);
+      if (!isFigureFrame) return;
+      navigateToLogbookSlug(data.target);
+    });
+  }
+
+  let SCROLL_FRAME = 0;
+  function updateActiveSection() {
+    cancelAnimationFrame(SCROLL_FRAME);
+    SCROLL_FRAME = requestAnimationFrame(() => {
+      const sections = Array.from(document.querySelectorAll(".page-section"));
+      if (!sections.length) return;
+      const marker = Math.min(window.innerHeight * 0.28, 180);
+      let active = sections[0];
+      sections.forEach((section) => {
+        if (section.getBoundingClientRect().top <= marker) active = section;
+      });
+      if (
+        window.innerHeight + window.scrollY >=
+        document.documentElement.scrollHeight - 2
+      ) {
+        active = sections[sections.length - 1];
+      }
+      highlight(active.dataset.slug);
+    });
+  }
+
+  function startLiveReload() {
+    if (!isLocalPreview()) return;
+    setInterval(async () => {
+      try {
+        const next = await fetchManifest();
+        if (!next || next.revision === MANIFEST.revision) return;
+        MANIFEST = next;
+        clearPageCache();
+        document.title = MANIFEST.title + " · Trackio Logbook";
+        document.getElementById("book-title").textContent = MANIFEST.title;
+        document.getElementById("book-head").setAttribute("aria-label", MANIFEST.title);
+        buildTree();
+        renderLogbook({ preserveScroll: true });
+      } catch (e) {}
+    }, LIVE_RELOAD_MS);
+  }
+
+  function setupConnect() {
+    const space = MANIFEST.space_id;
+    if (!space) return;
+    const steps = [
+      { t: "Install Trackio, if you don't have it yet.", c: "uv tool install trackio" },
+      { t: "Add the Trackio skill for your agent, then reload it.", c: "trackio skills add" },
+      { t: "Connect to this logbook.", c: `trackio logbook open ${space}` },
+    ];
+    const ol = document.getElementById("connect-steps");
+    steps.forEach((s, i) => {
+      const li = document.createElement("li");
+      const title = document.createElement("div");
+      title.className = "step-title";
+      title.textContent = `${i + 1}. ${s.t}`;
+      const block = document.createElement("div");
+      block.className = "codeblock";
+      const code = document.createElement("code");
+      code.textContent = s.c;
+      const copy = document.createElement("button");
+      copy.className = "copy";
+      copy.type = "button";
+      copy.title = "Copy";
+      copy.textContent = "⧉";
+      copy.addEventListener("click", () => copyText(s.c, copy, "⧉"));
+      block.appendChild(code);
+      block.appendChild(copy);
+      li.appendChild(title);
+      li.appendChild(block);
+      ol.appendChild(li);
+    });
+
+    const agentPrompt =
+      `Read and help maintain this Trackio experiment logbook ("${MANIFEST.title}").\n\n` +
+      "1. If you don't have Trackio, install it:  uv tool install trackio\n" +
+      "2. Add the Trackio skill for your agent:   trackio skills add   (then reload)\n" +
+      `3. Connect to this logbook:                trackio logbook open ${space}\n\n` +
+      "Start with `trackio logbook read`; use `trackio logbook read page \"...\"` " +
+      "for a page-level view, then fetch relevant details with " +
+      "`trackio logbook read cell cell_<id>`. If I've given you " +
+      'write access to the Space, add findings with `trackio logbook cell markdown "..." ' +
+      '--page "..."` and they will sync back automatically.';
+
+    const foot = document.getElementById("sidebar-foot");
+    foot.hidden = false;
+    const modal = document.getElementById("modal");
+    const open = () => (modal.hidden = false);
+    const close = () => (modal.hidden = true);
+    document.getElementById("connect-btn").addEventListener("click", open);
+    document.getElementById("modal-close").addEventListener("click", close);
+    modal.querySelector(".modal-backdrop").addEventListener("click", close);
+    document.addEventListener("keydown", (e) => {
+      if (e.key === "Escape") close();
+    });
+    const agentBtn = document.getElementById("copy-agent");
+    agentBtn.addEventListener("click", () =>
+      copyText(agentPrompt, agentBtn, "Copy for agent")
+    );
+  }
+
+  function copyText(text, btn, restore) {
+    const done = () => {
+      const prev = btn.textContent;
+      btn.textContent = restore === "⧉" ? "✓" : "Copied!";
+      btn.classList.add("copied");
+      setTimeout(() => {
+        btn.textContent = restore;
+        btn.classList.remove("copied");
+      }, 1400);
+      void prev;
+    };
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(done, done);
+    } else {
+      const ta = document.createElement("textarea");
+      ta.value = text;
+      document.body.appendChild(ta);
+      ta.select();
+      try {
+        document.execCommand("copy");
+      } catch (e) {}
+      document.body.removeChild(ta);
+      done();
+    }
+  }
+
+  async function init() {
+    MANIFEST = await fetchManifest();
+    document.title = MANIFEST.title + " · Trackio Logbook";
+    document.getElementById("book-title").textContent = MANIFEST.title;
+    document.getElementById("book-head").setAttribute("aria-label", MANIFEST.title);
+    document.getElementById("book-head").addEventListener("click", () => {
+      const target = "#/" + MANIFEST.root.slug;
+      if (location.hash === target) scrollToHash();
+      else location.hash = target;
+    });
+    buildTree();
+    setupConnect();
+    setupResourceHover();
+    setupFigureNavigation();
+    window.addEventListener("hashchange", () => scrollToHash());
+    window.addEventListener("scroll", updateActiveSection, { passive: true });
+    await renderLogbook();
+    startLiveReload();
+  }
+
+  init();
+})();

trackio/frontend_templates/starter/app.js

@@ -0,0 +1,555 @@
+const projectSelectEl = document.querySelector("#project-select");
+const runListEl = document.querySelector("#run-list");
+const metricsTitleEl = document.querySelector("#metrics-title");
+const metricsSubtitleEl = document.querySelector("#metrics-subtitle");
+const metricsGridEl = document.querySelector("#metrics-grid");
+const tracesSubtitleEl = document.querySelector("#traces-subtitle");
+const tracesBodyEl = document.querySelector("#traces-body");
+const navButtons = Array.from(document.querySelectorAll(".nav-link"));
+const pages = Array.from(document.querySelectorAll(".page"));
+
+const state = {
+  projects: [],
+  selectedProject: null,
+  runs: [],
+  selectedRunIds: [],
+};
+
+/*
+Trackio routes used by this starter today:
+- /api/get_all_projects
+- /api/get_runs_for_project
+- /api/get_metrics_for_run
+- /api/get_metric_values
+- /api/get_traces
+
+Useful routes for expanding this starter toward the full dashboard:
+- /api/get_system_metrics_for_run
+- /api/get_system_logs
+- /api/get_system_logs_batch
+- /api/get_logs
+- /api/get_logs_batch
+- /api/get_snapshot
+- /api/get_alerts
+- /api/query_project
+- /api/get_project_summary
+- /api/get_run_summary
+- /api/get_project_files
+- /api/get_settings
+- /api/get_run_mutation_status
+- /api/delete_run
+- /api/rename_run
+- /api/force_sync
+- /api/bulk_upload_media
+- /api/upload
+
+File/media URLs:
+- /file?path=ABSOLUTE_PATH_FROM_API
+*/
+const RUN_COLORS = [
+  "#1f77b4",
+  "#ff7f0e",
+  "#2ca02c",
+  "#d62728",
+  "#9467bd",
+  "#8c564b",
+  "#e377c2",
+  "#7f7f7f",
+  "#bcbd22",
+  "#17becf",
+];
+
+async function api(name, payload = {}) {
+  const response = await fetch(`/api/${name}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const json = await response.json();
+  if (!response.ok || json.error) {
+    throw new Error(json.error || `Request failed for ${name}`);
+  }
+  return json.data;
+}
+
+function runKey(run) {
+  return run.id || run.name;
+}
+
+function colorForRun(run) {
+  const index = state.runs.findIndex((candidate) => runKey(candidate) === runKey(run));
+  return RUN_COLORS[((index >= 0 ? index : 0) % RUN_COLORS.length + RUN_COLORS.length) % RUN_COLORS.length];
+}
+
+function formatValue(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return String(value);
+  }
+  if (Math.abs(value) >= 1000 || Math.abs(value) < 0.01) {
+    return value.toExponential(2);
+  }
+  return value.toFixed(3);
+}
+
+function getQueryParams() {
+  return new URLSearchParams(window.location.search);
+}
+
+function setQueryParams(params) {
+  const next = new URL(window.location.href);
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null || value === "" || (Array.isArray(value) && value.length === 0)) {
+      next.searchParams.delete(key);
+      continue;
+    }
+    next.searchParams.set(key, Array.isArray(value) ? value.join(",") : value);
+  }
+  window.history.replaceState({}, "", next);
+}
+
+function setActivePage(pageName) {
+  navButtons.forEach((button) => {
+    button.classList.toggle("active", button.dataset.pageTarget === pageName);
+  });
+  pages.forEach((page) => {
+    page.classList.toggle("active", page.dataset.page === pageName);
+  });
+}
+
+function bindNavigation() {
+  navButtons.forEach((button) => {
+    button.addEventListener("click", () => setActivePage(button.dataset.pageTarget));
+  });
+}
+
+function pickInitialProject(projects) {
+  const params = getQueryParams();
+  const project = params.get("project");
+  if (project && projects.includes(project)) {
+    return project;
+  }
+  return projects[0] || null;
+}
+
+function pickInitialRunIds(runs) {
+  const params = getQueryParams();
+  const fromUrl = (params.get("run_ids") || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  const validIds = runs.map(runKey);
+  const selected = fromUrl.filter((id) => validIds.includes(id));
+  if (selected.length) {
+    return selected;
+  }
+  return runs.slice(0, 2).map(runKey);
+}
+
+function renderProjectSelect() {
+  projectSelectEl.innerHTML = "";
+  if (!state.projects.length) {
+    const option = document.createElement("option");
+    option.value = "";
+    option.textContent = "No projects";
+    projectSelectEl.appendChild(option);
+    projectSelectEl.disabled = true;
+    return;
+  }
+
+  projectSelectEl.disabled = false;
+  for (const project of state.projects) {
+    const option = document.createElement("option");
+    option.value = project;
+    option.textContent = project;
+    option.selected = project === state.selectedProject;
+    projectSelectEl.appendChild(option);
+  }
+}
+
+function renderRunList() {
+  runListEl.innerHTML = "";
+  if (!state.runs.length) {
+    const empty = document.createElement("div");
+    empty.className = "sidebar-empty";
+    empty.textContent = "No runs yet";
+    runListEl.appendChild(empty);
+    return;
+  }
+
+  for (const run of state.runs) {
+    const wrapper = document.createElement("label");
+    wrapper.className = "run-option";
+
+    const input = document.createElement("input");
+    input.type = "checkbox";
+    input.checked = state.selectedRunIds.includes(runKey(run));
+    input.addEventListener("change", async () => {
+      if (input.checked) {
+        state.selectedRunIds = [...new Set([...state.selectedRunIds, runKey(run)])];
+      } else {
+        state.selectedRunIds = state.selectedRunIds.filter((id) => id !== runKey(run));
+      }
+      setQueryParams({
+        project: state.selectedProject,
+        run_ids: state.selectedRunIds,
+      });
+      await renderDashboard();
+    });
+
+    const marker = document.createElement("span");
+    marker.className = "run-color-dot";
+    marker.style.backgroundColor = colorForRun(run);
+
+    const text = document.createElement("span");
+    text.className = "run-option-text";
+    text.innerHTML = `<strong>${run.name || "Unnamed run"}</strong>`;
+
+    wrapper.appendChild(input);
+    wrapper.appendChild(marker);
+    wrapper.appendChild(text);
+    runListEl.appendChild(wrapper);
+  }
+}
+
+function chartPoints(rows, width, height, padding, min, max) {
+  const span = max - min || 1;
+  return rows.map((row, index) => {
+    const x = padding + (index / Math.max(rows.length - 1, 1)) * (width - padding * 2);
+    const y = height - padding - ((row.value - min) / span) * (height - padding * 2);
+    return [x, y];
+  });
+}
+
+function pathFromPoints(points) {
+  return points.map(([x, y], index) => `${index === 0 ? "M" : "L"} ${x} ${y}`).join(" ");
+}
+
+function renderMetricCard(metricName, seriesByRun) {
+  const card = document.createElement("article");
+  card.className = "metric-card";
+  const nonEmptySeries = seriesByRun.filter((entry) => entry.rows.length);
+  if (!nonEmptySeries.length) {
+    card.innerHTML = `
+      <div class="metric-card-head">
+        <div>
+          <h3>${metricName}</h3>
+          <div class="metric-run">Selected runs</div>
+        </div>
+      </div>
+      <div class="metric-empty">No numeric values logged for this metric.</div>
+    `;
+    return card;
+  }
+
+  const width = 640;
+  const height = 220;
+  const padding = 20;
+  const values = nonEmptySeries.flatMap((entry) => entry.rows.map((row) => row.value));
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const lineMarkup = nonEmptySeries
+    .map((entry) => {
+      const points = chartPoints(entry.rows, width, height, padding, min, max);
+      const markers = points
+        .map(([x, y]) => `<circle class="plot-marker" cx="${x}" cy="${y}" r="3.5" style="stroke:${entry.color}"></circle>`)
+        .join("");
+      return `
+        <path class="plot-line" d="${pathFromPoints(points)}" stroke="${entry.color}"></path>
+        ${markers}
+      `;
+    })
+    .join("");
+  const legendMarkup = nonEmptySeries
+    .map(
+      (entry) => `
+        <span class="metric-legend-item">
+          <span class="metric-legend-dot" style="background:${entry.color}"></span>
+          ${entry.runName}
+        </span>
+      `,
+    )
+    .join("");
+  const latestSummary = nonEmptySeries
+    .map((entry) => `${entry.runName}: ${formatValue(entry.rows.at(-1).value)}`)
+    .join(" | ");
+
+  card.innerHTML = `
+    <div class="metric-card-head">
+      <div>
+        <h3>${metricName}</h3>
+        <div class="metric-run">${nonEmptySeries.length} run${nonEmptySeries.length === 1 ? "" : "s"} overlaid</div>
+      </div>
+      <div class="metric-latest">${latestSummary}</div>
+    </div>
+    <div class="plot-shell">
+      <svg viewBox="0 0 ${width} ${height}" role="img" aria-label="${metricName} line plot">
+        <line class="plot-axis" x1="${padding}" y1="${height - padding}" x2="${width - padding}" y2="${height - padding}"></line>
+        ${lineMarkup}
+      </svg>
+    </div>
+    <div class="metric-legend">${legendMarkup}</div>
+    <div class="metric-meta">Comparing ${nonEmptySeries.length} selected runs on the same metric scale.</div>
+  `;
+  return card;
+}
+
+function textFromContent(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (typeof part?.text === "string") return part.text;
+        if (typeof part?.content === "string") return part.content;
+        return "";
+      })
+      .filter(Boolean)
+      .join(" ");
+  }
+  if (typeof content?.text === "string") return content.text;
+  return "";
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function renderMessageContent(content) {
+  if (typeof content === "string") {
+    return `<div class="trace-message-text">${escapeHtml(content)}</div>`;
+  }
+  if (Array.isArray(content)) {
+    const items = content
+      .map((part) => {
+        if (typeof part === "string") {
+          return `<div class="trace-message-text">${escapeHtml(part)}</div>`;
+        }
+        if (typeof part?.text === "string") {
+          return `<div class="trace-message-text">${escapeHtml(part.text)}</div>`;
+        }
+        if (typeof part?.content === "string") {
+          return `<div class="trace-message-text">${escapeHtml(part.content)}</div>`;
+        }
+        return `<div class="trace-message-text trace-message-muted">[non-text content]</div>`;
+      })
+      .join("");
+    return items || '<div class="trace-message-text trace-message-muted">(empty)</div>';
+  }
+  if (typeof content?.text === "string") {
+    return `<div class="trace-message-text">${escapeHtml(content.text)}</div>`;
+  }
+  return '<div class="trace-message-text trace-message-muted">(empty)</div>';
+}
+
+function renderTraceDetail(trace) {
+  const messages = Array.isArray(trace.messages) ? trace.messages : [];
+  if (!messages.length) {
+    return '<div class="trace-message-text trace-message-muted">No trace messages.</div>';
+  }
+  return messages
+    .map((message) => {
+      const role = escapeHtml(message?.role || "unknown");
+      return `
+        <div class="trace-message">
+          <div class="trace-message-role">${role}</div>
+          ${renderMessageContent(message?.content)}
+        </div>
+      `;
+    })
+    .join("");
+}
+
+function formatTraceTime(timestamp) {
+  if (!timestamp) return "—";
+  const date = new Date(timestamp);
+  if (Number.isNaN(date.getTime())) {
+    return timestamp;
+  }
+  return date.toLocaleString();
+}
+
+function renderTraceRows(traces) {
+  tracesBodyEl.innerHTML = "";
+  if (!traces.length) {
+    const row = document.createElement("tr");
+    row.innerHTML = '<td colspan="5" class="empty-row">No traces for the selected runs.</td>';
+    tracesBodyEl.appendChild(row);
+    return;
+  }
+
+  for (const trace of traces) {
+    const request = textFromContent(
+      (trace.messages || []).find((message) => message?.role === "user")?.content,
+    ) || "(no user message)";
+    const row = document.createElement("tr");
+    row.className = "trace-summary-row";
+    row.setAttribute("role", "button");
+    row.setAttribute("tabindex", "0");
+    row.setAttribute("aria-expanded", "false");
+    row.innerHTML = `
+      <td><span class="trace-id">${trace.id}</span></td>
+      <td class="trace-request">${request}</td>
+      <td>${trace.run || "—"}</td>
+      <td>${trace.step ?? "—"}</td>
+      <td>${formatTraceTime(trace.timestamp)}</td>
+    `;
+    const detailRow = document.createElement("tr");
+    detailRow.className = "trace-detail-row";
+    detailRow.hidden = true;
+    detailRow.innerHTML = `
+      <td colspan="5">
+        <div class="trace-detail-shell">
+          <div class="trace-detail-head">
+            <div>
+              <strong>${escapeHtml(trace.id)}</strong>
+              <div class="trace-detail-meta">${escapeHtml(trace.run || "—")} | step ${escapeHtml(trace.step ?? "—")} | ${escapeHtml(formatTraceTime(trace.timestamp))}</div>
+            </div>
+          </div>
+          <div class="trace-message-list">
+            ${renderTraceDetail(trace)}
+          </div>
+        </div>
+      </td>
+    `;
+    const toggleRow = () => {
+      const expanded = row.getAttribute("aria-expanded") === "true";
+      row.setAttribute("aria-expanded", expanded ? "false" : "true");
+      row.classList.toggle("expanded", !expanded);
+      detailRow.hidden = expanded;
+    };
+    row.addEventListener("click", toggleRow);
+    row.addEventListener("keydown", (event) => {
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        toggleRow();
+      }
+    });
+    tracesBodyEl.appendChild(row);
+    tracesBodyEl.appendChild(detailRow);
+  }
+}
+
+async function loadRuns() {
+  if (!state.selectedProject) {
+    state.runs = [];
+    state.selectedRunIds = [];
+    renderRunList();
+    await renderDashboard();
+    return;
+  }
+
+  state.runs = await api("get_runs_for_project", { project: state.selectedProject });
+  state.selectedRunIds = pickInitialRunIds(state.runs);
+  renderRunList();
+  await renderDashboard();
+}
+
+async function renderDashboard() {
+  metricsGridEl.innerHTML = "";
+  tracesBodyEl.innerHTML = "";
+
+  const selectedRuns = state.runs.filter((run) => state.selectedRunIds.includes(runKey(run)));
+  metricsTitleEl.textContent = state.selectedProject || "Metrics";
+
+  if (!state.selectedProject) {
+    metricsSubtitleEl.textContent = "No Trackio projects found.";
+    tracesSubtitleEl.textContent = "No traces available.";
+    return;
+  }
+
+  if (!selectedRuns.length) {
+    metricsSubtitleEl.textContent = "Select one or more runs in the sidebar.";
+    tracesSubtitleEl.textContent = "Select one or more runs to load traces.";
+    metricsGridEl.innerHTML = '<div class="empty-panel">No runs selected.</div>';
+    renderTraceRows([]);
+    return;
+  }
+
+  metricsSubtitleEl.textContent = `Plot cards for ${selectedRuns.length} selected run${selectedRuns.length === 1 ? "" : "s"}.`;
+  tracesSubtitleEl.textContent = `Recent traces for ${selectedRuns.length} selected run${selectedRuns.length === 1 ? "" : "s"}.`;
+
+  const traceGroups = [];
+  const metricMap = new Map();
+
+  for (const run of selectedRuns) {
+    const metrics = await api("get_metrics_for_run", {
+      project: state.selectedProject,
+      run: run.name,
+      run_id: run.id,
+    });
+
+    const metricSeries = await Promise.all(
+      metrics.slice(0, 3).map(async (metricName) => ({
+        metricName,
+        rows: await api("get_metric_values", {
+          project: state.selectedProject,
+          run: run.name,
+          run_id: run.id,
+          metric_name: metricName,
+        }),
+      })),
+    );
+
+    metricSeries.forEach(({ metricName, rows }) => {
+      const numericRows = rows.filter((row) => typeof row.value === "number" && Number.isFinite(row.value));
+      if (!metricMap.has(metricName)) {
+        metricMap.set(metricName, []);
+      }
+      metricMap.get(metricName).push({
+        runName: run.name || "Unnamed run",
+        color: colorForRun(run),
+        rows: numericRows,
+      });
+    });
+
+    const runTraces = await api("get_traces", {
+      project: state.selectedProject,
+      run: run.name,
+      run_id: run.id,
+      sort: "request_time_desc",
+      limit: 6,
+    });
+    traceGroups.push(...runTraces);
+  }
+
+  for (const [metricName, seriesByRun] of metricMap.entries()) {
+    metricsGridEl.appendChild(renderMetricCard(metricName, seriesByRun));
+  }
+
+  if (!metricsGridEl.children.length) {
+    metricsGridEl.innerHTML = '<div class="empty-panel">No numeric metrics available.</div>';
+  }
+
+  traceGroups.sort((left, right) => String(right.timestamp || "").localeCompare(String(left.timestamp || "")));
+  renderTraceRows(traceGroups.slice(0, 12));
+}
+
+async function load() {
+  bindNavigation();
+  projectSelectEl.addEventListener("change", async () => {
+    state.selectedProject = projectSelectEl.value || null;
+    setQueryParams({ project: state.selectedProject, run_ids: null });
+    await loadRuns();
+    renderProjectSelect();
+  });
+  try {
+    state.projects = await api("get_all_projects");
+    state.selectedProject = pickInitialProject(state.projects);
+    renderProjectSelect();
+    await loadRuns();
+  } catch (error) {
+    projectSelectEl.innerHTML = '<option value="">Error</option>';
+    projectSelectEl.disabled = true;
+    metricsSubtitleEl.textContent = "Could not load Trackio data.";
+    metricsGridEl.innerHTML = '<div class="empty-panel">The starter could not reach the Trackio API.</div>';
+    tracesSubtitleEl.textContent = "Could not load traces.";
+    renderTraceRows([]);
+  }
+}
+
+load();

trackio/frontend_templates/starter/index.html

@@ -0,0 +1,135 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Starter</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <div class="app-shell">
+      <aside class="sidebar">
+        <div class="sidebar-scroll">
+          <div class="logo-section">
+            <img
+              src="/static/trackio/trackio_logo_type_light_transparent.png"
+              alt="Trackio"
+              class="logo"
+            />
+          </div>
+
+          <section class="sidebar-section">
+            <div class="section-label">Project</div>
+            <div class="dropdown-wrap">
+              <select id="project-select" class="project-select" aria-label="Project"></select>
+              <div class="dropdown-icon" aria-hidden="true">
+                <svg width="16" height="16" viewBox="0 0 18 18" fill="none">
+                  <path d="M5.25 7.5L9 11.25L12.75 7.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+                </svg>
+              </div>
+            </div>
+          </section>
+
+          <section class="sidebar-section">
+            <div class="section-label">Runs</div>
+            <div id="run-list" class="run-list"></div>
+          </section>
+
+          <section class="sidebar-section">
+            <div class="section-label">Notes</div>
+            <p class="sidebar-note">
+              This starter mirrors the Trackio dashboard structure, but stays plain
+              HTML, CSS, and JavaScript so you can replace pieces quickly.
+            </p>
+          </section>
+        </div>
+      </aside>
+
+      <main class="main-shell">
+        <nav class="navbar">
+          <div class="nav-spacer"></div>
+          <div class="nav-tabs">
+            <button class="nav-link active" data-page-target="metrics">Metrics</button>
+            <button class="nav-link" data-page-target="traces">Traces</button>
+            <!--
+            Trackio's full dashboard also includes tabs like these.
+            Uncomment them when you implement the corresponding page sections.
+
+            <button class="nav-link" data-page-target="system">System Metrics</button>
+            <button class="nav-link" data-page-target="media">Media & Tables</button>
+            <button class="nav-link" data-page-target="reports">Alerts & Reports</button>
+            <button class="nav-link" data-page-target="runs">Runs</button>
+            <button class="nav-link" data-page-target="files">Files</button>
+            <button class="nav-link" data-page-target="settings">Settings</button>
+            -->
+          </div>
+        </nav>
+
+        <section class="page active" data-page="metrics">
+          <header class="page-header">
+            <div>
+              <p class="eyebrow">Starter Dashboard</p>
+              <h1 id="metrics-title">Metrics</h1>
+              <p id="metrics-subtitle" class="page-subtitle">Loading Trackio data.</p>
+            </div>
+          </header>
+          <div id="metrics-grid" class="metrics-grid"></div>
+        </section>
+
+        <section class="page" data-page="traces">
+          <header class="page-header">
+            <div>
+              <p class="eyebrow">Starter Dashboard</p>
+              <h1>Traces</h1>
+              <p id="traces-subtitle" class="page-subtitle">Recent traces for the selected runs.</p>
+            </div>
+          </header>
+          <div class="traces-table-wrap">
+            <table class="traces-table">
+              <thead>
+                <tr>
+                  <th>Trace ID</th>
+                  <th>Request</th>
+                  <th>Run</th>
+                  <th>Step</th>
+                  <th>Request time</th>
+                </tr>
+              </thead>
+              <tbody id="traces-body"></tbody>
+            </table>
+          </div>
+        </section>
+
+        <!--
+        Future page shells you may want to add:
+
+        <section class="page" data-page="system">
+          Build this from /api/get_system_metrics_for_run and /api/get_system_logs.
+        </section>
+
+        <section class="page" data-page="media">
+          Build this from /api/get_logs, /api/get_snapshot, /api/get_project_files, and /file?path=...
+        </section>
+
+        <section class="page" data-page="reports">
+          Build this from /api/get_alerts and /api/query_project.
+        </section>
+
+        <section class="page" data-page="runs">
+          Build this from /api/get_runs_for_project, /api/get_run_summary, /api/delete_run, and /api/rename_run.
+        </section>
+
+        <section class="page" data-page="files">
+          Build this from /api/get_project_files and /file?path=...
+        </section>
+
+        <section class="page" data-page="settings">
+          Build this from /api/get_settings, /api/force_sync, and /api/get_run_mutation_status.
+        </section>
+        -->
+      </main>
+    </div>
+
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

trackio/frontend_templates/starter/styles.css

@@ -0,0 +1,467 @@
+:root {
+  color-scheme: light;
+  --background-fill-primary: #ffffff;
+  --background-fill-secondary: #f9fafb;
+  --background-fill-tertiary: #f3f4f6;
+  --border-color-primary: #e5e7eb;
+  --border-color-accent: #d1d5db;
+  --body-text-color: #111827;
+  --body-text-color-subdued: #6b7280;
+  --body-text-color-soft: #9ca3af;
+  --accent: #1d4ed8;
+  --shadow-soft: 0 1px 2px rgba(16, 24, 40, 0.04);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  min-height: 100%;
+  background: var(--background-fill-secondary);
+  color: var(--body-text-color);
+  font-family:
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+}
+
+button,
+input,
+select,
+table {
+  font: inherit;
+}
+
+.app-shell {
+  display: grid;
+  grid-template-columns: 320px minmax(0, 1fr);
+  min-height: 100vh;
+}
+
+.sidebar {
+  border-right: 1px solid var(--border-color-primary);
+  background: var(--background-fill-primary);
+}
+
+.sidebar-scroll {
+  height: 100vh;
+  overflow-y: auto;
+  padding: 18px 16px 28px;
+}
+
+.logo-section {
+  padding: 10px 10px 18px;
+  border-bottom: 1px solid var(--border-color-primary);
+}
+
+.logo {
+  display: block;
+  width: 138px;
+  max-width: 100%;
+}
+
+.sidebar-section {
+  padding: 18px 10px 0;
+}
+
+.section-label,
+.eyebrow {
+  margin: 0 0 10px;
+  color: var(--body-text-color-subdued);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.run-list {
+  display: grid;
+  gap: 8px;
+}
+
+.dropdown-wrap {
+  position: relative;
+}
+
+.project-select {
+  width: 100%;
+  padding: 10px 40px 10px 12px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 10px;
+  background: var(--background-fill-primary);
+  color: var(--body-text-color);
+  appearance: none;
+  -webkit-appearance: none;
+}
+
+.project-select:focus {
+  outline: none;
+  border-color: var(--border-color-accent);
+  box-shadow: 0 0 0 3px rgba(29, 78, 216, 0.08);
+}
+
+.dropdown-icon {
+  position: absolute;
+  top: 50%;
+  right: 12px;
+  transform: translateY(-50%);
+  color: var(--body-text-color-subdued);
+  pointer-events: none;
+}
+
+.run-option {
+  display: grid;
+  grid-template-columns: 18px 10px minmax(0, 1fr);
+  gap: 10px;
+  align-items: start;
+  padding: 10px 12px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 10px;
+  background: var(--background-fill-primary);
+  cursor: pointer;
+}
+
+.run-option input {
+  margin: 2px 0 0;
+  accent-color: var(--accent);
+}
+
+.run-color-dot {
+  width: 10px;
+  height: 10px;
+  margin-top: 5px;
+  border-radius: 999px;
+  background: var(--accent);
+}
+
+.run-option-text strong,
+.run-option-text span {
+  display: block;
+}
+
+.run-option-text strong {
+  color: var(--body-text-color);
+  font-size: 14px;
+  font-weight: 600;
+}
+
+.run-option-text span,
+.sidebar-note,
+.sidebar-empty {
+  color: var(--body-text-color-subdued);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.main-shell {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.navbar {
+  display: flex;
+  align-items: stretch;
+  min-height: 44px;
+  border-bottom: 1px solid var(--border-color-primary);
+  background: var(--background-fill-primary);
+}
+
+.nav-spacer {
+  flex: 1 1 0;
+}
+
+.nav-tabs {
+  display: flex;
+  padding-right: 8px;
+}
+
+.nav-link {
+  padding: 10px 16px;
+  border: none;
+  border-bottom: 2px solid transparent;
+  background: none;
+  color: var(--body-text-color-subdued);
+  cursor: pointer;
+}
+
+.nav-link.active {
+  border-bottom-color: var(--body-text-color);
+  color: var(--body-text-color);
+  font-weight: 500;
+}
+
+.page {
+  display: none;
+  min-width: 0;
+  padding: 24px 28px 36px;
+}
+
+.page.active {
+  display: block;
+}
+
+.page-header {
+  margin-bottom: 22px;
+}
+
+.page-header h1 {
+  margin: 0;
+  font-size: 32px;
+  line-height: 1.1;
+}
+
+.page-subtitle {
+  margin: 8px 0 0;
+  color: var(--body-text-color-subdued);
+  font-size: 15px;
+}
+
+.metrics-grid {
+  display: grid;
+  gap: 18px;
+}
+
+.metric-card {
+  padding: 18px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 14px;
+  background: var(--background-fill-primary);
+  box-shadow: var(--shadow-soft);
+}
+
+.metric-card-head {
+  display: flex;
+  align-items: start;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.metric-card h3 {
+  margin: 0;
+  font-size: 18px;
+}
+
+.metric-run,
+.metric-meta,
+.metric-empty,
+.metric-latest {
+  color: var(--body-text-color-subdued);
+  font-size: 13px;
+}
+
+.metric-latest {
+  color: var(--body-text-color);
+  max-width: 50%;
+  font-size: 13px;
+  font-weight: 600;
+  text-align: right;
+}
+
+.plot-shell {
+  margin-top: 14px;
+  padding: 10px 12px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 12px;
+  background: linear-gradient(180deg, #ffffff, #f9fafb);
+}
+
+.plot-shell svg {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
+.plot-axis {
+  stroke: var(--border-color-accent);
+  stroke-width: 1.2;
+}
+
+.plot-line {
+  fill: none;
+  stroke-width: 2.25;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.plot-marker {
+  fill: var(--background-fill-primary);
+  stroke: var(--body-text-color);
+  stroke-width: 1.5;
+}
+
+.metric-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px 14px;
+  margin-top: 12px;
+}
+
+.metric-legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--body-text-color-subdued);
+  font-size: 13px;
+}
+
+.metric-legend-dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 999px;
+}
+
+.traces-table-wrap {
+  overflow: auto;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 14px;
+  background: var(--background-fill-primary);
+  box-shadow: var(--shadow-soft);
+}
+
+.traces-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.traces-table thead {
+  background: var(--background-fill-secondary);
+}
+
+.traces-table th,
+.traces-table td {
+  padding: 14px 16px;
+  border-bottom: 1px solid var(--border-color-primary);
+  text-align: left;
+  vertical-align: top;
+  font-size: 14px;
+}
+
+.traces-table th {
+  color: var(--body-text-color-subdued);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.trace-summary-row {
+  cursor: pointer;
+}
+
+.trace-summary-row:hover {
+  background: var(--background-fill-secondary);
+}
+
+.trace-summary-row.expanded {
+  background: var(--background-fill-secondary);
+}
+
+.trace-id {
+  color: var(--body-text-color);
+  font-family:
+    ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    monospace;
+  font-size: 12px;
+}
+
+.trace-request {
+  max-width: 520px;
+  color: var(--body-text-color);
+}
+
+.trace-detail-row td {
+  padding: 0;
+  background: var(--background-fill-secondary);
+}
+
+.trace-detail-shell {
+  padding: 18px 20px;
+  border-top: 1px solid var(--border-color-primary);
+}
+
+.trace-detail-head strong {
+  display: block;
+  color: var(--body-text-color);
+  font-size: 14px;
+}
+
+.trace-detail-meta {
+  margin-top: 4px;
+  color: var(--body-text-color-subdued);
+  font-size: 12px;
+}
+
+.trace-message-list {
+  display: grid;
+  gap: 12px;
+  margin-top: 16px;
+}
+
+.trace-message {
+  padding: 12px 14px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 12px;
+  background: var(--background-fill-primary);
+}
+
+.trace-message-role {
+  margin-bottom: 8px;
+  color: var(--body-text-color-subdued);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.trace-message-text {
+  color: var(--body-text-color);
+  font-size: 14px;
+  line-height: 1.55;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.trace-message-muted {
+  color: var(--body-text-color-subdued);
+}
+
+.empty-row,
+.empty-panel {
+  color: var(--body-text-color-subdued);
+  text-align: center;
+}
+
+.empty-panel {
+  padding: 48px 20px;
+  border: 1px dashed var(--border-color-accent);
+  border-radius: 14px;
+  background: var(--background-fill-primary);
+}
+
+@media (max-width: 960px) {
+  .app-shell {
+    grid-template-columns: 1fr;
+  }
+
+  .sidebar {
+    border-right: none;
+    border-bottom: 1px solid var(--border-color-primary);
+  }
+
+  .sidebar-scroll {
+    height: auto;
+  }
+
+  .page {
+    padding: 18px;
+  }
+}

trackio/gpu.py

@@ -0,0 +1,381 @@
+import os
+import threading
+import warnings
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from trackio.run import Run
+
+pynvml: Any = None
+PYNVML_AVAILABLE = False
+_nvml_initialized = False
+_nvml_lock = threading.Lock()
+_energy_baseline: dict[int, float] = {}
+
+
+def _ensure_pynvml():
+    global PYNVML_AVAILABLE, pynvml
+    if PYNVML_AVAILABLE:
+        return pynvml
+    try:
+        import pynvml as _pynvml
+
+        pynvml = _pynvml
+        PYNVML_AVAILABLE = True
+        return pynvml
+    except ImportError:
+        raise ImportError(
+            "nvidia-ml-py is required for GPU monitoring. "
+            "Install it with: pip install nvidia-ml-py"
+        )
+
+
+def _init_nvml() -> bool:
+    global _nvml_initialized
+    with _nvml_lock:
+        if _nvml_initialized:
+            return True
+        try:
+            nvml = _ensure_pynvml()
+            nvml.nvmlInit()
+            _nvml_initialized = True
+            return True
+        except Exception:
+            return False
+
+
+def get_gpu_count() -> tuple[int, list[int]]:
+    """
+    Get the number of GPUs visible to this process and their physical indices.
+    Respects CUDA_VISIBLE_DEVICES environment variable.
+
+    Returns:
+        Tuple of (count, physical_indices) where:
+        - count: Number of visible GPUs
+        - physical_indices: List mapping logical index to physical GPU index.
+          e.g., if CUDA_VISIBLE_DEVICES=2,3 returns (2, [2, 3])
+          meaning logical GPU 0 = physical GPU 2, logical GPU 1 = physical GPU 3
+    """
+    if not _init_nvml():
+        return 0, []
+
+    cuda_visible = os.environ.get("CUDA_VISIBLE_DEVICES")
+    if cuda_visible is not None and cuda_visible.strip():
+        try:
+            indices = [int(x.strip()) for x in cuda_visible.split(",") if x.strip()]
+            return len(indices), indices
+        except ValueError:
+            pass
+
+    try:
+        total = pynvml.nvmlDeviceGetCount()
+        return total, list(range(total))
+    except Exception:
+        return 0, []
+
+
+def get_all_gpu_count() -> tuple[int, list[int]]:
+    """
+    Get the total number of physical GPUs on the machine, ignoring CUDA_VISIBLE_DEVICES.
+
+    Returns:
+        Tuple of (count, physical_indices) for ALL GPUs on the machine.
+        e.g., on a 4-GPU machine returns (4, [0, 1, 2, 3]) regardless of
+        CUDA_VISIBLE_DEVICES setting.
+    """
+    if not _init_nvml():
+        return 0, []
+
+    try:
+        total = pynvml.nvmlDeviceGetCount()
+        return total, list(range(total))
+    except Exception:
+        return 0, []
+
+
+def gpu_available() -> bool:
+    """
+    Check if GPU monitoring is available.
+
+    Returns True if nvidia-ml-py is installed and at least one NVIDIA GPU is detected.
+    This is used for auto-detection of GPU logging.
+    """
+    try:
+        _ensure_pynvml()
+        count, _ = get_gpu_count()
+        return count > 0
+    except ImportError:
+        return False
+    except Exception:
+        return False
+
+
+def reset_energy_baseline():
+    """Reset the energy baseline for all GPUs. Called when a new run starts."""
+    global _energy_baseline
+    _energy_baseline = {}
+
+
+def collect_gpu_metrics(device: int | None = None, all_gpus: bool = False) -> dict:
+    """
+    Collect GPU metrics for visible GPUs.
+
+    Args:
+        device: CUDA device index to collect metrics from. If None, collects
+                from all GPUs visible to this process (respects CUDA_VISIBLE_DEVICES).
+                The device index is the logical CUDA index (0, 1, 2...), not the
+                physical GPU index.
+        all_gpus: If True and device is None, collect metrics for ALL physical GPUs
+                  on the machine, ignoring CUDA_VISIBLE_DEVICES. Used by GpuMonitor
+                  to report system-wide GPU metrics in distributed training.
+
+    Returns:
+        Dictionary of GPU metrics. Keys use device indices (gpu/0/, gpu/1/, etc.).
+    """
+    if not _init_nvml():
+        return {}
+
+    if all_gpus and device is None:
+        gpu_count, visible_gpus = get_all_gpu_count()
+    else:
+        gpu_count, visible_gpus = get_gpu_count()
+    if gpu_count == 0:
+        return {}
+
+    if device is not None:
+        if device < 0 or device >= gpu_count:
+            return {}
+        gpu_indices = [(device, visible_gpus[device])]
+    else:
+        gpu_indices = list(enumerate(visible_gpus))
+
+    metrics = {}
+    total_util = 0.0
+    total_mem_used_gib = 0.0
+    total_power = 0.0
+    max_temp = 0.0
+    valid_util_count = 0
+
+    for logical_idx, physical_idx in gpu_indices:
+        prefix = f"gpu/{logical_idx}"
+        try:
+            handle = pynvml.nvmlDeviceGetHandleByIndex(physical_idx)
+
+            try:
+                util = pynvml.nvmlDeviceGetUtilizationRates(handle)
+                metrics[f"{prefix}/utilization"] = util.gpu
+                metrics[f"{prefix}/memory_utilization"] = util.memory
+                total_util += util.gpu
+                valid_util_count += 1
+            except Exception:
+                pass
+
+            try:
+                mem = pynvml.nvmlDeviceGetMemoryInfo(handle)
+                mem_used_gib = mem.used / (1024**3)
+                mem_total_gib = mem.total / (1024**3)
+                metrics[f"{prefix}/allocated_memory"] = mem_used_gib
+                metrics[f"{prefix}/total_memory"] = mem_total_gib
+                if mem.total > 0:
+                    metrics[f"{prefix}/memory_usage"] = mem.used / mem.total
+                total_mem_used_gib += mem_used_gib
+            except Exception:
+                pass
+
+            try:
+                power_mw = pynvml.nvmlDeviceGetPowerUsage(handle)
+                power_w = power_mw / 1000.0
+                metrics[f"{prefix}/power"] = power_w
+                total_power += power_w
+            except Exception:
+                pass
+
+            try:
+                power_limit_mw = pynvml.nvmlDeviceGetPowerManagementLimit(handle)
+                power_limit_w = power_limit_mw / 1000.0
+                metrics[f"{prefix}/power_limit"] = power_limit_w
+                if power_limit_w > 0 and f"{prefix}/power" in metrics:
+                    metrics[f"{prefix}/power_percent"] = (
+                        metrics[f"{prefix}/power"] / power_limit_w
+                    ) * 100
+            except Exception:
+                pass
+
+            try:
+                temp = pynvml.nvmlDeviceGetTemperature(
+                    handle, pynvml.NVML_TEMPERATURE_GPU
+                )
+                metrics[f"{prefix}/temp"] = temp
+                max_temp = max(max_temp, temp)
+            except Exception:
+                pass
+
+            try:
+                sm_clock = pynvml.nvmlDeviceGetClockInfo(handle, pynvml.NVML_CLOCK_SM)
+                metrics[f"{prefix}/sm_clock"] = sm_clock
+            except Exception:
+                pass
+
+            try:
+                mem_clock = pynvml.nvmlDeviceGetClockInfo(handle, pynvml.NVML_CLOCK_MEM)
+                metrics[f"{prefix}/memory_clock"] = mem_clock
+            except Exception:
+                pass
+
+            try:
+                fan_speed = pynvml.nvmlDeviceGetFanSpeed(handle)
+                metrics[f"{prefix}/fan_speed"] = fan_speed
+            except Exception:
+                pass
+
+            try:
+                pstate = pynvml.nvmlDeviceGetPerformanceState(handle)
+                metrics[f"{prefix}/performance_state"] = pstate
+            except Exception:
+                pass
+
+            try:
+                energy_mj = pynvml.nvmlDeviceGetTotalEnergyConsumption(handle)
+                if physical_idx not in _energy_baseline:
+                    _energy_baseline[physical_idx] = energy_mj
+                energy_consumed_mj = energy_mj - _energy_baseline[physical_idx]
+                metrics[f"{prefix}/energy_consumed"] = energy_consumed_mj / 1000.0
+            except Exception:
+                pass
+
+            try:
+                pcie_tx = pynvml.nvmlDeviceGetPcieThroughput(
+                    handle, pynvml.NVML_PCIE_UTIL_TX_BYTES
+                )
+                pcie_rx = pynvml.nvmlDeviceGetPcieThroughput(
+                    handle, pynvml.NVML_PCIE_UTIL_RX_BYTES
+                )
+                metrics[f"{prefix}/pcie_tx"] = pcie_tx / 1024.0
+                metrics[f"{prefix}/pcie_rx"] = pcie_rx / 1024.0
+            except Exception:
+                pass
+
+            try:
+                throttle = pynvml.nvmlDeviceGetCurrentClocksThrottleReasons(handle)
+                metrics[f"{prefix}/throttle_thermal"] = int(
+                    bool(throttle & pynvml.nvmlClocksThrottleReasonSwThermalSlowdown)
+                )
+                metrics[f"{prefix}/throttle_power"] = int(
+                    bool(throttle & pynvml.nvmlClocksThrottleReasonSwPowerCap)
+                )
+                metrics[f"{prefix}/throttle_hw_slowdown"] = int(
+                    bool(throttle & pynvml.nvmlClocksThrottleReasonHwSlowdown)
+                )
+                metrics[f"{prefix}/throttle_apps"] = int(
+                    bool(
+                        throttle
+                        & pynvml.nvmlClocksThrottleReasonApplicationsClocksSetting
+                    )
+                )
+            except Exception:
+                pass
+
+            try:
+                ecc_corrected = pynvml.nvmlDeviceGetTotalEccErrors(
+                    handle,
+                    pynvml.NVML_MEMORY_ERROR_TYPE_CORRECTED,
+                    pynvml.NVML_VOLATILE_ECC,
+                )
+                metrics[f"{prefix}/corrected_memory_errors"] = ecc_corrected
+            except Exception:
+                pass
+
+            try:
+                ecc_uncorrected = pynvml.nvmlDeviceGetTotalEccErrors(
+                    handle,
+                    pynvml.NVML_MEMORY_ERROR_TYPE_UNCORRECTED,
+                    pynvml.NVML_VOLATILE_ECC,
+                )
+                metrics[f"{prefix}/uncorrected_memory_errors"] = ecc_uncorrected
+            except Exception:
+                pass
+
+        except Exception:
+            continue
+
+    if valid_util_count > 0:
+        metrics["gpu/mean_utilization"] = total_util / valid_util_count
+    if total_mem_used_gib > 0:
+        metrics["gpu/total_allocated_memory"] = total_mem_used_gib
+    if total_power > 0:
+        metrics["gpu/total_power"] = total_power
+    if max_temp > 0:
+        metrics["gpu/max_temp"] = max_temp
+
+    return metrics
+
+
+class GpuMonitor:
+    def __init__(self, run: "Run", interval: float = 10.0):
+        self._run = run
+        self._interval = interval
+        self._stop_flag = threading.Event()
+        self._thread: "threading.Thread | None" = None
+
+    def start(self):
+        count, _ = get_all_gpu_count()
+        if count == 0:
+            warnings.warn(
+                "auto_log_gpu=True but no NVIDIA GPUs detected. GPU logging disabled."
+            )
+            return
+
+        reset_energy_baseline()
+        self._thread = threading.Thread(target=self._monitor_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_flag.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+
+    def _monitor_loop(self):
+        while not self._stop_flag.is_set():
+            try:
+                metrics = collect_gpu_metrics(all_gpus=True)
+                if metrics:
+                    self._run.log_system(metrics)
+            except Exception:
+                pass
+
+            self._stop_flag.wait(timeout=self._interval)
+
+
+def log_gpu(run: "Run | None" = None, device: int | None = None) -> dict:
+    """
+    Log GPU metrics to the current or specified run as system metrics.
+
+    Args:
+        run: Optional Run instance. If None, uses current run from context.
+        device: CUDA device index to collect metrics from. If None, collects
+                from all GPUs visible to this process (respects CUDA_VISIBLE_DEVICES).
+
+    Returns:
+        dict: The GPU metrics that were logged.
+
+    Example:
+        ```python
+        import trackio
+
+        run = trackio.init(project="my-project")
+        trackio.log({"loss": 0.5})
+        trackio.log_gpu()  # logs all visible GPUs
+        trackio.log_gpu(device=0)  # logs only CUDA device 0
+        ```
+    """
+    from trackio import context_vars
+
+    if run is None:
+        run = context_vars.current_run.get()
+        if run is None:
+            raise RuntimeError("Call trackio.init() before trackio.log_gpu().")
+
+    metrics = collect_gpu_metrics(device=device)
+    if metrics:
+        run.log_system(metrics)
+    return metrics