docs: replace Arcade embeds with self-hosted videos

astro.config.mjs

@@ -280,7 +280,11 @@ Developer & Agent Interfaces:
           pageSeparator: llmsPageSeparator,
           // Strip heading anchor links from llms-full.txt and llms-small.txt
           // (see src/utils/heading-anchor.ts).
-          customSelectors: { all: [HEADING_ANCHOR_LINK_SELECTOR] },
+          customSelectors: {
+            all: [HEADING_ANCHOR_LINK_SELECTOR],
+            // Video links are no use in the minified bundle.
+            small: ['.demo-video'],
+          },
           // `exclude` only affects `llms-small.txt`, and `demote` lines
           // unlisted pages up for `stripUnlistedFromLlmsFull`.
           exclude: [...unlistedPages],

public/_headers

@@ -66,3 +66,7 @@
 /humans.txt
   Content-Type: text/plain; charset=utf-8
   Access-Control-Allow-Origin: *
+
+# Demo videos and their posters. Cached for a week, so a re-export shows up within that.
+/videos/*
+  Cache-Control: public, max-age=604800

public/_routes.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "include": ["/*"],
+  "exclude": ["/videos/*"]
+}

src/components/DemoVideo.astro

@@ -0,0 +1,74 @@
+---
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { publicDir } from 'astro:config/server';
+import sharp from 'sharp';
+
+interface Props {
+  /** File name (without extension) of the video in `public/videos/`. */
+  name: string;
+  title: string;
+}
+
+const { name, title } = Astro.props;
+
+// Keep `name` URL-safe so the file checked below is the one that's served.
+if (!/^[a-z0-9-]+$/.test(name)) {
+  throw new Error(`DemoVideo: name "${name}" must be lowercase kebab-case`);
+}
+
+const src = `/videos/${name}.mp4`;
+const poster = `/videos/${name}.jpg`;
+
+const fileIn = (file: string) => new URL(`.${file}`, publicDir);
+
+// Fail the build on a missing video or poster instead of shipping a player
+// that 404s.
+for (const file of [src, poster]) {
+  if (!existsSync(fileIn(file))) {
+    throw new Error(`DemoVideo: public${file} does not exist`);
+  }
+}
+
+// The poster is a frame of the video, so its size reserves the right box
+// before anything loads and the page doesn't jump.
+const { width, height } = await sharp(
+  fileURLToPath(fileIn(poster)),
+).metadata();
+---
+
+<figure class="demo-video">
+  <video
+    controls
+    playsinline
+    preload="none"
+    poster={poster}
+    width={width}
+    height={height}
+    aria-label={title}
+    data-mdast="ignore"
+  >
+    <source src={src} type="video/mp4" />
+  </video>
+  <figcaption><a href={src}>Watch the video: {title}</a></figcaption>
+</figure>
+
+<style>
+  .demo-video {
+    margin-inline: 0;
+  }
+
+  .demo-video video {
+    display: block;
+    width: 100%;
+    height: auto;
+    border-radius: 0.5rem;
+    border: 1px solid var(--sl-color-gray-5);
+    background-color: var(--sl-color-black);
+  }
+
+  .demo-video figcaption {
+    margin-top: 0.5rem;
+    font-size: var(--sl-text-sm);
+  }
+</style>

src/content/docs/account/api-keys.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 4
 ---
 
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 
 API keys let you authenticate with Shorebird from CI systems and other automated
 environments. You can create, view, and revoke API keys from the
@@ -19,10 +19,7 @@ allows.
 
 ## Creating an API key
 
-<ArcadeEmbed
-  src="https://demo.arcade.software/TQUMnX2QwuCRzEV1e8kN?embed&embed_mobile=tab&embed_desktop=inline&show_copy_link=true"
-  title="Create Shorebird API Key"
-/>
+<DemoVideo name="create-api-key" title="Create a Shorebird API key" />
 
 1. Open **Account → API Keys** in the console.
 2. Click **Create API Key**.

src/content/docs/account/billing.mdx

@@ -6,7 +6,7 @@ sidebar:
 ---
 
 import { Image } from 'astro:assets';
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 import viewBillingPortal from '~/assets/view_billing_portal.png';
 import accountMonthlySpendingLimit from '~/assets/account_monthly_spending_limit.png';
 import setSpendingLimitDialog from '~/assets/set_spending_limit_dialog.png';
@@ -32,10 +32,7 @@ same, but you can change them to be different.
 If you'd like invoices sent to a different email address than the one you use to
 log in, you can change this in Stripe:
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/7dMbiP2AbiyF2HzWgjd2"
-  title="Edit Billing Email"
-/>
+<DemoVideo name="update-billing-contact" title="Edit the billing email" />
 
 1. Navigate to your "Account" panel within Shorebird.
 2. Click on the drop-down menu on the right side.

src/content/docs/account/orgs.mdx

@@ -6,7 +6,7 @@ sidebar:
 ---
 
 import { Image } from 'astro:assets';
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 import addMemberToOrg from '~/assets/add_member_to_org.png';
 import completedAddMemberToOrg from '~/assets/completed_add_member_to_org.png';
 import transferAppToDifferentOrg from '~/assets/transfer_app_to_different_org.png';
@@ -83,9 +83,9 @@ You can also transfer an app from the command line with
 
 ### Add a member
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/Cl6LTDv4A3TKhJJOdJse"
-  title="Adding Members to the Organization"
+<DemoVideo
+  name="manage-org-collaborators"
+  title="Add members to an organization"
 />
 
 To add one or more members to your organization, visit the organization's

src/content/docs/code-push/ci/_authentication.mdx

@@ -1,13 +1,10 @@
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 
 Most Shorebird functionality, like creating releases and patches, requires
 authentication. To authenticate in your CI, create an API key from the
 [Shorebird Console](https://console.shorebird.dev):
 
-<ArcadeEmbed
-  src="https://demo.arcade.software/TQUMnX2QwuCRzEV1e8kN?embed&embed_mobile=tab&embed_desktop=inline&show_copy_link=true"
-  title="Create Shorebird API Key"
-/>
+<DemoVideo name="create-api-key" title="Create a Shorebird API key" />
 
 1. Go to **Account → API Keys**.
 2. Click **Create API Key**.

src/content/docs/code-push/create.mdx

@@ -6,7 +6,7 @@ sidebar:
   order: 2
 ---
 
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 
 :::note
 
@@ -21,9 +21,9 @@ To create a new Flutter project with Shorebird, use `shorebird create`:
 shorebird create my_app
 ```
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/iw81avmZ8dfoqfNzQN2P"
-  title="Create a new flutter project with Shorebird"
+<DemoVideo
+  name="create-flutter-project"
+  title="Create a Flutter project with Shorebird"
 />
 
 This does several things:

src/content/docs/code-push/guides/staging-patches.mdx

@@ -9,12 +9,9 @@ import { CodeTabs, LinkCard } from 'starlight-theme-nova/components';
 import { Image } from 'astro:assets';
 import goLive from '~/assets/staging_patches_change_track_dropdown.png';
 import switchTrack from '~/assets/staging_patches_patch_context_menu.png';
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/n22dgnzUR0qwvjNciQ2i"
-  title="Pushing a patch to staging track"
-/>
+<DemoVideo name="staging-patch" title="Push a patch to the staging track" />
 
 This guide will walk you through how to validate a patch in Shorebird's staging
 environment before promoting the patch to production.

src/content/docs/code-push/index.mdx

@@ -6,13 +6,13 @@ sidebar:
   order: 1
 ---
 
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 
 For a quick overview, check out the demo below.
 
-<ArcadeEmbed
-  src="https://demo.arcade.software/x5ifkvJ8yFZh63hYJF0g?embed&embed_mobile=tab&embed_desktop=inline&show_copy_link=true"
-  title="Send over the air updates to Flutter app"
+<DemoVideo
+  name="send-ota-update"
+  title="Send over-the-air updates to a Flutter app"
 />
 
 ## What is Code Push?

src/content/docs/code-push/initialize.mdx

@@ -7,7 +7,7 @@ sidebar:
 ---
 
 import { LinkCard } from 'starlight-theme-nova/components';
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 
 :::note
 
@@ -17,9 +17,9 @@ Shorebird.
 
 :::
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/5w5LiD8ODdaGhb6554X9"
-  title="Initializing Shorebird in an existing Flutter project"
+<DemoVideo
+  name="initialize-shorebird"
+  title="Initialize Shorebird in an existing Flutter project"
 />
 
 To configure an existing Flutter project to use Shorebird, use `shorebird init`

src/content/docs/code-push/release.mdx

@@ -9,18 +9,15 @@ sidebar:
 {/* cspell:words armeabi abiFilters v7a */}
 
 import { Tabs, TabItem } from '@astrojs/starlight/components';
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 import { LinkCard } from 'starlight-theme-nova/components';
 import { Image } from 'astro:assets';
 import releaseDeleteDialog from '~/assets/release_delete_dialog.png';
 import listReleases from '~/assets/list_releases.png';
 
 In order to start pushing updates, you will need to create a release.
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/h8ywz1NWeFq3dC2iRQBU"
-  title="Create a Release"
-/>
+<DemoVideo name="create-release" title="Create a release" />
 
 `shorebird release` is a drop-in replacement for `flutter build`. It builds your
 app and uploads the compiled Dart artifacts to Shorebird's servers as a baseline
@@ -488,9 +485,9 @@ you can manage your app's releases directly from the command line using the
 
 ### List releases
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/CtBj7r9AA5Xm0p0tIJYX"
-  title="Viewing releases from CLI and console"
+<DemoVideo
+  name="view-releases"
+  title="View releases from the CLI and console"
 />
 
 #### Via the Shorebird CLI
@@ -546,10 +543,7 @@ afterwards, use `--target-platform` as described in
 
 ### Delete releases
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/1eUps58NpU5sFkTxljGu"
-  title="Delete a Release"
-/>
+<DemoVideo name="delete-release" title="Delete a release" />
 
 :::caution[Deleting a release is permanent]
 

src/content/docs/code-push/rollback.mdx

@@ -8,7 +8,7 @@ sidebar:
 
 import { LinkCard } from 'starlight-theme-nova/components';
 import { Image } from 'astro:assets';
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 import rollbackButton from '~/assets/rollback_button.png';
 import rollbackPatch2Active from '~/assets/rollback_patch2_active.png';
 import rollbackPatch2RolledBack from '~/assets/rollback_patch2_rolled_back.png';
@@ -46,10 +46,7 @@ Roll back requires a minimum Flutter version of 3.27.4.
 
 :::
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/GlHfzbxcicw61ux4NCHx"
-  title="Roll Back a Patch"
-/>
+<DemoVideo name="rollback-patch" title="Roll back a patch" />
 
 ## Active and superseded patches
 

src/content/docs/code-push/tracks.mdx

@@ -8,7 +8,7 @@ sidebar:
 ---
 
 import { CodeTabs, LinkCard } from 'starlight-theme-nova/components';
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 
 **Tracks** are named deployment channels that control which devices receive a
 patch. Every Shorebird app has a built-in `stable` track, which is the default
@@ -62,10 +62,7 @@ built-in names, so those tracks can't be deleted.
 
 ## Publishing a patch to a track
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/n22dgnzUR0qwvjNciQ2i"
-  title="Pushing a patch to staging track"
-/>
+<DemoVideo name="staging-patch" title="Push a patch to the staging track" />
 
 Pass the `--track` flag to any `shorebird patch` command. If you omit the flag,
 the patch is published to `stable` by default. With Shorebird 1.6.130 or newer,

src/content/docs/getting-started/index.mdx

@@ -11,12 +11,9 @@ import {
   LinkCard,
 } from 'starlight-theme-nova/components';
 import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
-import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
+import DemoVideo from '~/components/DemoVideo.astro';
 
-<ArcadeEmbed
-  src="https://app.arcade.software/share/rwhPDRat2tGYHouo8cO6"
-  title="Getting Started with Shorebird"
-/>
+<DemoVideo name="getting-started" title="Get started with Shorebird" />
 
 This guide walks you through installing Shorebird and integrating it into your
 Flutter app.