Feat/embed advantagescope

.github/workflows/ci.yml

@@ -30,6 +30,17 @@ jobs:
           restore-keys: ${{ runner.os }}-pnpm-
 
       - run: pnpm install --frozen-lockfile
+
+      # Cache the AS Lite tarball across runs -- 61 MB pulled from a GH
+      # release on every run otherwise. Key on the pinned version +
+      # checksum so a bundle bump invalidates the cache automatically.
+      - name: Cache AdvantageScope Lite bundle
+        uses: actions/cache@v4
+        with:
+          path: packages/web/.advantagescope-cache
+          key: advantagescope-${{ hashFiles('packages/web/advantagescope/version.txt', 'packages/web/advantagescope/checksums.txt') }}
+      - run: pnpm fetch:advantagescope
+
       - run: pnpm typecheck
       - run: pnpm build  # web must build before worker (worker bundles web/dist via [assets])
       - run: pnpm test

.github/workflows/deploy.yml

@@ -37,6 +37,17 @@ jobs:
           restore-keys: ${{ runner.os }}-pnpm-
 
       - run: pnpm install --frozen-lockfile
+
+      # Cache the AS Lite tarball across deploys -- 61 MB pulled from a
+      # GH release on every run otherwise. Key on the pinned version +
+      # checksum so a bundle bump invalidates the cache automatically.
+      - name: Cache AdvantageScope Lite bundle
+        uses: actions/cache@v4
+        with:
+          path: packages/web/.advantagescope-cache
+          key: advantagescope-${{ hashFiles('packages/web/advantagescope/version.txt', 'packages/web/advantagescope/checksums.txt') }}
+      - run: pnpm fetch:advantagescope
+
       - run: pnpm typecheck
       - run: pnpm test
       - run: pnpm lint

.gitignore

@@ -18,6 +18,12 @@ package-lock.json
 # setup.sh backs up wrangler.toml on first successful run
 wrangler.toml.bak
 
+# AdvantageScope Lite bundle is fetched at install time from a tarball
+# produced by packages/web/scripts/publish-advantagescope-bundle.mjs.
+# Pinned by packages/web/advantagescope/version.txt + checksums.txt.
+packages/web/public/advantagescope/
+packages/web/.advantagescope-cache/
+
 # Local agent / review artifacts (session-scoped worktrees + per-run
 # reviewer JSON dumps).
 .claude/

ATTRIBUTION.md

@@ -0,0 +1,81 @@
+# Attribution
+
+RavenScope embeds and redistributes third-party software. Full notices
+below.
+
+## AdvantageScope (embedded viewer)
+
+The in-browser session viewer under `/sessions/:id/view` is
+**AdvantageScope Lite**, served verbatim as a static bundle at
+`/v/:id/*`. Source: <https://github.com/Mechanical-Advantage/AdvantageScope>.
+
+AdvantageScope is distributed under a BSD-3-Clause-style license:
+
+> Copyright (c) 2021-2025 Littleton Robotics. All rights reserved.
+>
+> Redistribution and use in source and binary forms, with or without
+> modification, are permitted provided that the following conditions are met:
+>
+> - Redistributions of source code must retain the above copyright
+>   notice, this list of conditions and the following disclaimer.
+> - Redistributions in binary form must reproduce the above copyright
+>   notice, this list of conditions and the following disclaimer in the
+>   documentation and/or other materials provided with the distribution.
+> - Neither the name of Littleton Robotics, FRC 6328 ("Mechanical Advantage"),
+>   AdvantageScope, nor the names of other AdvantageScope contributors may be
+>   used to endorse or promote products derived from this software without
+>   specific prior written permission.
+>
+> THIS SOFTWARE IS PROVIDED BY LITTLETON ROBOTICS AND OTHER ADVANTAGESCOPE
+> CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
+> NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY NONINFRINGEMENT
+> AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+> LITTLETON ROBOTICS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+> INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+> NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+> DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+> OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+> NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+> EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+### Local modifications
+
+RavenScope applies one ~8-line patch to AdvantageScope's source during
+the bundle build, committed at
+[`packages/web/advantagescope/main.ts.patch`](packages/web/advantagescope/main.ts.patch).
+The patch adds a `?log=<name>` URL query parameter to AdvantageScope
+Lite's `initHub()` so that the session viewer can deep-link directly
+into a single log without the user interacting with the download
+popup. Applied at build time by
+[`packages/web/scripts/publish-advantagescope-bundle.mjs`](packages/web/scripts/publish-advantagescope-bundle.mjs).
+
+The patch is non-invasive and upstreamable; when AdvantageScope ships
+native URL-based auto-open support, the patch will be removed.
+
+The pinned AdvantageScope release is recorded in
+[`packages/web/advantagescope/version.txt`](packages/web/advantagescope/version.txt).
+
+### Bundled third-party dependencies
+
+AdvantageScope in turn redistributes numerous npm packages. The
+complete transitive notice file is generated during AdvantageScope's
+own build by `getLicenses.mjs` and lands at
+`lite/static/docs/build/licenses.html` within the bundle. That file
+ships verbatim to `/advantagescope/docs/build/licenses.html` on the
+RavenScope origin when the bundle is deployed.
+
+## AdvantageScopeAssets (field and robot 3D models, joystick layouts)
+
+AdvantageScope's bundled default assets (field models, robot models,
+joystick layouts) are downloaded from the
+[`AdvantageScopeAssets`](https://github.com/Mechanical-Advantage/AdvantageScopeAssets)
+`archive-v1` release by AdvantageScope's
+[`bundleLiteAssets.mjs`](https://github.com/Mechanical-Advantage/AdvantageScope/blob/main/bundleLiteAssets.mjs)
+during AdvantageScope's install step. RavenScope then redistributes
+these assets unchanged under
+`packages/web/public/advantagescope/bundledAssets/`.
+
+Licenses for individual asset files are carried per-asset in their
+respective `config.json` (field `sourceUrl`) or alongside each asset
+in the AdvantageScopeAssets repository. See that repository for the
+authoritative notices.

README.md

@@ -4,8 +4,9 @@ Lightweight hosted telemetry bucket for FRC teams, built as a stripped-down
 alternative to [`RavenBrain`](https://github.com/RunnymedeRobotics1310/RavenBrain).
 Runs entirely on Cloudflare (Workers, D1, R2, Durable Objects) with magic-link
 email auth. Sign in with an email, mint an API key, point RavenLink at it,
-and your match telemetry streams into a hosted session list. Download any
-session as a `.wpilog` and open it in AdvantageScope.
+and your match telemetry streams into a hosted session list. Open any
+session directly in an embedded AdvantageScope Lite viewer, or download
+it as a `.wpilog` for use with the desktop app.
 
 - No passwords. No FRC-API calls. No database to host.
 - Free-tier friendly: one Worker, one D1, one R2, two Durable Object classes,
@@ -269,9 +270,39 @@ sign-in.
   the user/workspace on request, then the address signs up fresh.
 - **30-day cookie TTL, no server-side revocation.** A stolen cookie is
   valid until it expires, or until `SESSION_SECRET` is rotated.
-- **No AdvantageScope deep-link.** v1 ships with `.wpilog` download
-  only. A future initiative may add an `advantagescope://` launch
-  button or an in-browser AdvantageScope port.
+- **Embedded AdvantageScope Lite is beta-track.** The viewer binds to
+  AdvantageScope's `v27.x` (2027-targeted) Lite build. The pinned tag
+  lives in [`packages/web/advantagescope/version.txt`](packages/web/advantagescope/version.txt)
+  and is bumped via the workflow below. Video tab, Phoenix
+  Diagnostics, Hoot log format, XR, pop-out windows, and tab-layout
+  JSON export are inherited omissions. See
+  [`ATTRIBUTION.md`](ATTRIBUTION.md) for license + patch details.
+
+### Embedded viewer: bump AdvantageScope versions
+
+Clicking "Open viewer" on a session loads AdvantageScope Lite in an
+iframe at `/v/:id/`. The Lite bundle is built from a pinned
+AdvantageScope tag by a local developer ritual (not in CI — the full
+build needs Emscripten 4.0.12). To bump:
+
+```bash
+# one-time per machine: install emsdk 4.0.12
+git clone https://github.com/emscripten-core/emsdk.git ~/src/emsdk
+cd ~/src/emsdk && ./emsdk install 4.0.12 && ./emsdk activate 4.0.12
+source ~/src/emsdk/emsdk_env.sh
+
+# edit packages/web/advantagescope/version.txt, set `as=` and `bundle=`
+
+# build + tar + update checksums.txt
+AS_PATH=~/src/1310/AdvantageScope pnpm publish:advantagescope-bundle
+
+# sanity: re-fetch from local cache and verify
+pnpm fetch:advantagescope
+pnpm -F @ravenscope/web build
+
+# optionally: publish the tarball to a RavenScope GitHub release and
+# set release-url in version.txt so CI / fresh clones can download it.
+```
 
 ## Ergonomic target: R8 measurement