docs: replace Arcade embeds with self-hosted videos by AbhishekDoshi26 · Pull Request #758 · shorebirdtech/docs

AbhishekDoshi26 · 2026-10-23T11:47:11Z

We're moving off Arcade, so this swaps every interactive Arcade demo in the docs for a plain video served from the docs site itself.

What changed

12 demo videos added under public/videos/, each with a poster image. They're exported from Arcade and re-encoded to H.264 at 30fps with faststart, so each is 1-3 MB (about 30 MB total). That keeps them well under the Cloudflare Pages 25 MiB per-file limit (the raw API key export was 26 MB).
New DemoVideo component (native <video> with controls and a poster, plus a "Watch the video" link under it that opens the MP4 directly). ArcadeEmbed is removed.
15 embeds across 12 pages now use DemoVideo: Getting Started, Code Push overview, Create, Initialize, Release (3), Rollback, Tracks, Staging patches guide, CI authentication, Billing, Orgs and API Keys.
The generated .md pages for agents now get a "Watch the video" link instead of an iframe.

Testing

npm run build (including astro check) passes.
Checked the pages locally with npm run dev.
The API key in the API key video is covered with a solid box in every frame it appears (checked frame by frame), and the key has been revoked.

Once this is live we can turn off Arcade.

We're moving off Arcade, so the interactive demos are now plain MP4s served from the docs site. - Add 12 demo videos (H.264, 30fps, faststart) and poster images under public/videos/. Each one is 1-3 MB, well under the Cloudflare Pages 25 MiB per-file limit. - Add a DemoVideo component (native <video> with controls, poster and a download link fallback) and remove ArcadeEmbed. - Swap every ArcadeEmbed usage across 12 pages for DemoVideo. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhkRAtjMDA7LEGPy1xJSsZ

AbhishekDoshi26

Review round 1. Five inline findings below. One more that has no line in the diff: public/_headers has no rule for /videos/*, so about 29 MB of MP4s and posters get Cloudflare Pages' default caching. Add a /videos/* block with a Cache-Control max-age.

- Cover the key field in create-api-key.mp4 with a solid box instead of a light blur. - Size each video from its poster so the page doesn't jump on load. - Move the video link into a figcaption so it shows when a video fails to load, and keep the <video> out of the agent .md pages. - Drop the duplicate title attribute. - Cache /videos/* for a week.

AbhishekDoshi26 · 2026-10-23T12:05:22Z

The public/_headers caching finding from the review is fixed in 30f4d0a: /videos/* is now served with Cache-Control: public, max-age=604800.

- Skip .mp4 in the Pages middleware, so video range requests are served as static assets (with the /videos/* cache rule) instead of running the Function. - Use preload="none": the poster and size are already set, so pages no longer fetch every video up front. - Fail the build if a DemoVideo's mp4 is missing.

AbhishekDoshi26

Review round 2 (fresh reviewer). Inline findings below. Two more without a diff line:

The old lightly blurred create-api-key.mp4 from 02486f4 stays reachable in this PR's history even after the replacement. That key has been revoked, so no change.
Commit 02486f4 has a Co-Authored-By trailer and a session link. The merge will use an explicit squash subject and body so neither lands on main.

…s-small - Read the video and poster from Astro's configured publicDir instead of process.cwd(), and fail the build with a clear message if either is missing. - Leave .demo-video out of llms-small.txt; a video link is no use there.

AbhishekDoshi26

Review round 3 (fresh reviewer). Three new inline findings below. It also raised again four points already settled in earlier threads, so they're not reposted: the old blurred video in 02486f4 (key revoked), the week-long /videos/* cache, the Arcade title-card posters, and committing the MP4s to git.

AbhishekDoshi26

Review round 4 (fresh reviewer). Four inline findings below, plus one with no diff line: send-ota-update.mp4's audio clips (decoded peak at the 16-bit maximum), and it is louder than the other 11 videos.

The titles now show on the page under each player, so they follow the docs' sentence case. DemoVideo also rejects a name that isn't lowercase kebab-case, so the file it checks is the one that's served.

AbhishekDoshi26

Review round 5 (fresh reviewer). Two new inline findings below. It also raised settled points again (old blurred video in 02486f4 with the key revoked, week-long cache, astro:assets instead of public/, Arcade title cards, captions/audio, MP4s in git), so those aren't reposted. It confirmed that every poster matches its video's aspect ratio and every MP4 is faststart.

… edits - Add _routes.json excluding /videos/*, so video requests never invoke the Function and the _headers cache rule applies. This replaces the mp4 entry in the middleware's SKIP_PATTERN. - Restore the 'Create a Release' LinkCard titles; they match the target page's title and aren't part of this change. - Check the DemoVideo name before building paths from it.

AbhishekDoshi26

Review round 6 (fresh reviewer). Four inline findings below. It also flagged again that 02486f4's attribution trailer must not reach main, which the merge's explicit squash message will handle.

AbhishekDoshi26

Review round 7 (fresh reviewer). It found no correctness issues. What it raised, and why none of it changes the PR:

Old video in 02486f4 and the attribution trailer in that commit's message: the key is revoked. The squash merge uses an explicit subject and body, so neither the old blob nor the trailer reaches main.
Add mp4 back to SKIP_PATTERN alongside _routes.json: no change. _routes.json is the one mechanism that keeps videos away from the Function. A second copy in the middleware never runs in production and could drift from it.
_routes.json replaces the generated routes: no change. The only function is the root _middleware.ts, and include: ["/*"] is what Pages would generate for it. Adding a function later doesn't need a routes change unless it lives under /videos/.
Memoize sharp/existsSync per name: no change. These are header reads of 12 small files, which cost nothing measurable in a build.
The poster existence check is redundant with sharp: no change. Round 3 asked for it so a missing poster fails with a DemoVideo message instead of sharp's generic error.
Captions and the week-long cache: settled in the round 2 and round 4 threads.

Cloudflare Pages answers a Range request for a static asset with the whole file and a 200, and Safari won't play an MP4 without 206 partial content, so the videos from #758 failed there. - Add a /videos/*.mp4 Pages Function that serves byte ranges: 206 with Content-Range (streamed when the asset declares its size), an uncacheable 416 when unsatisfiable, and the whole file for HEAD, multi-range, reversed ranges or a stale or weak If-Range. - Narrow _routes.json to exclude only the posters (/videos/*.jpg), and put mp4 back in the middleware's SKIP_PATTERN.