feat(tldraw): add allowVideoAutoplay option to TldrawOptions (tldraw#8943)

In order to let SDK consumers disable video autoplay across the board
without subclassing `VideoShapeUtil`, this PR adds a top-level
`allowVideoAutoplay` option to `TldrawOptions`. The host opt-out acts as
a ceiling, not a floor: when `false`, no video autoplays regardless of
its per-shape `autoplay` prop; when `true` (the default, preserving
existing behavior), each shape's per-shape `autoplay` prop is respected.
The `prefers-reduced-motion` check at the render site continues to apply
independently.

```tsx
<Tldraw options={{ allowVideoAutoplay: false }} />
```

### Behavior matrix

| `TldrawOptions.allowVideoAutoplay` | `shape.props.autoplay` | Result |
| ---------------------------------- | ---------------------- |
--------------- |
| `true` (default) | `true` | Autoplays |
| `true` (default) | `false` | Does not play |
| `false` | `true` | Does not play |
| `false` | `false` | Does not play |

So `allowVideoAutoplay: false` is a global opt-out for the host app — it
never forces every video to play. The per-shape prop remains the way
users opt individual shapes in or out when autoplay is allowed at the
host level.

Closes [tldraw#8915](tldraw#8915).

### Change type

- [x] \`feature\`

### Test plan

1. Create a tldraw editor with \`<Tldraw options={{ allowVideoAutoplay:
false }} />\`.
2. Drop a video file onto the canvas — confirm it does not start playing
automatically.
3. Click into the video to edit, press play — confirm the user can still
play it manually.
4. With the default option (or \`allowVideoAutoplay: true\`), drop a
video and confirm it still autoplays as before.
5. With the default option, set \`shape.props.autoplay = false\` on an
individual video — confirm only that shape stops autoplaying while
others still autoplay.

### Release notes

- Add an \`allowVideoAutoplay\` option to \`TldrawOptions\`. When set to
\`false\`, no video shape autoplays regardless of its per-shape
\`autoplay\` prop — including pasted and restored shapes. Defaults to
\`true\`.

### API changes

- Added \`TldrawOptions.allowVideoAutoplay: boolean\` (default
\`true\`).

### Code changes

| Section         | LOC change |
| --------------- | ---------- |
| Core code       | +18 / -1   |
| Automated files | +2 / -0    |
| Documentation   | +7 / -0    |

---------

Co-authored-by: Max Drake <maxdrake46@gmail.com>

Author: frolic

apps/docs/content/sdk-features/default-shapes.mdx

@@ -324,6 +324,12 @@ const ConfiguredVideoUtil = VideoShapeUtil.configure({
 })
 ```
 
+To disable autoplay across the board — including for pasted or restored shapes — set the editor-level `allowVideoAutoplay` option to `false` instead:
+
+```tsx
+<Tldraw options={{ allowVideoAutoplay: false }} />
+```
+
 ### Bookmark
 
 The bookmark shape displays a URL as a card with metadata including title, description, and preview image. Bookmarks are created when you paste URLs onto the canvas. The editor fetches metadata from the URL and stores it in an associated asset record. Bookmark shapes have fixed dimensions and can't be resized.

apps/docs/content/sdk-features/options.mdx

@@ -201,6 +201,7 @@ When `debouncedZoom` is enabled and the page has more shapes than `debouncedZoom
 | `laserDelayMs`                   | 1200      | Duration laser pointer remains visible         |
 | `laserFadeoutMs`                 | 500       | Duration for laser pointer fadeout animation   |
 | `quickZoomPreservesScreenBounds` | true      | Whether quick zoom brush keeps viewport scale  |
+| `allowVideoAutoplay`             | true      | Whether video shapes are allowed to autoplay   |
 | `branding`                       | undefined | App name for accessibility labels              |
 | `nonce`                          | undefined | CSP nonce for inline styles                    |
 

packages/editor/api-report.api.md

@@ -718,6 +718,7 @@ export const DefaultSvgDefs: () => null;
 export const defaultTldrawOptions: {
     readonly actionShortcutsLocation: "swap";
     readonly adjacentShapeMargin: 10;
+    readonly allowVideoAutoplay: true;
     readonly animationMediumMs: 320;
     readonly camera: TLCameraOptions;
     readonly cameraMovingTimeoutMs: 64;
@@ -3754,6 +3755,7 @@ export interface TldrawOptions {
     readonly actionShortcutsLocation: 'menu' | 'swap' | 'toolbar';
     // (undocumented)
     readonly adjacentShapeMargin: number;
+    readonly allowVideoAutoplay: boolean;
     // (undocumented)
     readonly animationMediumMs: number;
     readonly branding?: string;

packages/editor/src/lib/options.ts

@@ -209,6 +209,17 @@ export interface TldrawOptions {
 	 * viewport's page dimensions regardless of overview zoom changes.
 	 */
 	readonly quickZoomPreservesScreenBounds: boolean
+	/**
+	 * Whether video shapes are allowed to autoplay. When `true` (the default), each
+	 * video respects its own `shape.props.autoplay` value. When `false`, no video
+	 * autoplays regardless of its shape prop — useful for host apps that want to
+	 * disable autoplay across the board, including for pasted or restored shapes.
+	 *
+	 * This does not change the per-shape `autoplay` prop on new video shapes — that
+	 * default is controlled by `VideoShapeOptions.autoplay` on `VideoShapeUtil`. The
+	 * `prefers-reduced-motion` media query continues to suppress autoplay independently.
+	 */
+	readonly allowVideoAutoplay: boolean
 	/**
 	 * Called before content is written to the clipboard during a copy or cut operation.
 	 * Receives the serialized content (shapes, bindings, assets) and can filter or transform
@@ -347,6 +358,7 @@ export const defaultTldrawOptions = {
 	text: {},
 	deepLinks: undefined,
 	quickZoomPreservesScreenBounds: true,
+	allowVideoAutoplay: true,
 	onBeforeCopyToClipboard: undefined,
 	onBeforePasteFromClipboard: undefined,
 	onClipboardPasteRaw: undefined,

packages/tldraw/src/lib/shapes/video/VideoShapeUtil.tsx

@@ -210,7 +210,11 @@ const VideoShape = memo(function VideoShape({ shape }: { shape: TLVideoShape })
 									height="100%"
 									draggable={false}
 									playsInline
-									autoPlay={shape.props.autoplay && !prefersReducedMotion}
+									autoPlay={
+										shape.props.autoplay &&
+										editor.options.allowVideoAutoplay &&
+										!prefersReducedMotion
+									}
 									muted
 									loop
 									disableRemotePlayback