runtime: queue Video.play() before loadedmetadata instead of throwing

[TooTallNate]

Fixes #402

Problem

Video.play() rejected with InvalidStateError when called before the video's metadata had loaded, diverging from HTMLMediaElement.play() which never rejects for "not loaded yet". Because play() returns a promise, the common v.play().catch(() => {}) pattern silently swallowed the error, leaving the video frozen on its first frame with no visible failure.

Fix

play() now follows the HTML spec algorithm:

• Before metadata (or with no source at all): sets paused = false, fires play on the paused→false transition, and returns a promise that resolves once playback actually begins (started from load()'s metadata handler).
• Never throws synchronously. With no source the promise stays pending until a source arrives — verified empirically against headless Chromium (the resource selection algorithm waits; it does not reject NotSupportedError as the issue suggested).
• A pending play() is rejected with AbortError by pause() or a superseding load(), and with NotSupportedError on load failure.

Testing

Three new conformance fixtures in test/fixtures/video.ts, all verified passing in both nxjs-test and Chrome on natecube (video: nxjs-test vs Chrome ✓, 44 assertions):

• eager play() immediately after setting src — resolves and playback advances
• no-source play() — stays pending, paused flips to false
• pause() before metadata — pending play() rejects with AbortError

The no-source fixture caught my initial (wrong) NotSupportedError implementation diverging from Chrome, which is exactly what the conformance harness is for.

[changeset-bot]

🦋 Changeset detected

Latest commit: edf9ee3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@nx.js/runtime	Patch
@nx.js/nro	Patch
@nx.js/nsp	Patch
create-nxjs-app	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nx-js	Ready	Preview, Comment	Jul 8, 2026 8:40am

[github-actions]

📝 Runtime Type Changes

This PR modifies the public TypeScript API surface (packages/runtime/dist/index.d.ts):

View type diff

--- base: index.d.ts
+++ pr: index.d.ts
@@ -2836,7 +2836,7 @@
  * const video = new Video();
  * video.loop = true;
  * video.src = 'romfs:/attract.webm';
- * video.addEventListener('canplay', () => video.play());
+ * video.play(); // queued until metadata loads, like in browsers
  *
  * function render() {
  *   ctx.drawImage(video, 0, 0, screen.width, screen.height);

[Copilot]

Pull request overview

This PR updates the Video runtime API to align Video.play() behavior more closely with browser HTMLMediaElement.play(), specifically by queueing playback (instead of rejecting) when play() is called before loadedmetadata.

Changes:

• Implement queued play() requests via an internal pendingPlays list and settle them on metadata load, load failure, pause(), or superseding load().
• Update Video.play() to return a promise without synchronous throws (including the “no metadata yet” case).
• Add new conformance fixtures to cover eager play(), no-source pending play(), and aborting pending play via pause().

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
packages/runtime/src/video.ts	Implements pending play() queuing/settlement and adjusts load()/pause() interactions.
packages/runtime/test/fixtures/video.ts	Adds conformance tests for play() queuing and abort behavior.
.changeset/video-play-before-metadata.md	Adds a patch changeset describing the behavior change.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[waldhari1]

Steady Deployments @TooTallNate 🔥...keep up the good work.