@flighthq/video 0.5.0-next.1944.cd6b6e7 → 0.5.1-edge.638.d4dbd4e

package/README.md

@@ -13,5 +13,5 @@ Import the supported application-facing API from `@flighthq/video`. The `@flight
 This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
 
 - [Flight project](https://github.com/flighthq/flight)
-- [Source for @flighthq/video@0.5.0-next.1944.cd6b6e7](https://github.com/flighthq/flight/tree/cd6b6e71eb472b3a4249830a7743333f019fa7b7/packages/video)
-- [License](https://github.com/flighthq/flight/blob/cd6b6e71eb472b3a4249830a7743333f019fa7b7/LICENSE.md)
+- [Source for @flighthq/video@0.5.1-edge.638.d4dbd4e](https://github.com/flighthq/flight/tree/d4dbd4e347dc8be10b180c85a766ab50333dcb51/packages/video)
+- [License](https://github.com/flighthq/flight/blob/d4dbd4e347dc8be10b180c85a766ab50333dcb51/LICENSE.md)

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { canPlayVideoType, createVideoResource, createVideoResourceFromMediaStream, detectVideoMimeType, disposeVideoResource, getVideoResourceDuration, getVideoResourceHeight, getVideoResourceWidth, hasVideoResourceElement, inferVideoMimeType, isVideoResourceEmpty, isVideoResourceReady, loadVideoResourceFromBlob, loadVideoResourceFromUrl, loadVideoResourceFromUrls, selectVideoResourceUrl, } from './contract';
+export { canPlayVideoType, createVideoResource, createVideoResourceFromMediaStream, destroyVideoResource, detectVideoMimeType, disposeVideoResource, explainVideoCapabilityBackend, explainVideoCapabilityOperation, getVideoResourceDuration, getVideoResourceHeight, getVideoResourceWidth, hasVideoCapabilityOperation, hasVideoResourceElement, inferVideoMimeType, isVideoResourceEmpty, isVideoResourceReady, loadVideoResourceFromBlob, loadVideoResourceFromUrl, loadVideoResourceFromUrls, selectVideoResourceUrl, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,kCAAkC,EAClC,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,kCAAkC,EAClC,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,6BAA6B,EAC7B,+BAA+B,EAC/B,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { canPlayVideoType, createVideoResource, createVideoResourceFromMediaStream, detectVideoMimeType, disposeVideoResource, getVideoResourceDuration, getVideoResourceHeight, getVideoResourceWidth, hasVideoResourceElement, inferVideoMimeType, isVideoResourceEmpty, isVideoResourceReady, loadVideoResourceFromBlob, loadVideoResourceFromUrl, loadVideoResourceFromUrls, selectVideoResourceUrl, } from './contract';
+export { canPlayVideoType, createVideoResource, createVideoResourceFromMediaStream, destroyVideoResource, detectVideoMimeType, disposeVideoResource, explainVideoCapabilityBackend, explainVideoCapabilityOperation, getVideoResourceDuration, getVideoResourceHeight, getVideoResourceWidth, hasVideoCapabilityOperation, hasVideoResourceElement, inferVideoMimeType, isVideoResourceEmpty, isVideoResourceReady, loadVideoResourceFromBlob, loadVideoResourceFromUrl, loadVideoResourceFromUrls, selectVideoResourceUrl, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,kCAAkC,EAClC,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,kCAAkC,EAClC,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,6BAA6B,EAC7B,+BAA+B,EAC/B,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/videoFormat.d.ts

@@ -1,6 +1,15 @@
-import type { VideoResourceUrl } from '@flighthq/types/contract';
+import type { BackendExplanation, BackendOperationExplanation, VideoCapabilityBackend, VideoCapabilityOperation, VideoResourceUrl } from '@flighthq/types/contract';
 export declare function canPlayVideoType(mimeType: string): boolean;
 export declare function detectVideoMimeType(data: ArrayBuffer | Uint8Array): string | null;
+export declare function explainVideoCapabilityBackend(): BackendExplanation;
+export declare function explainVideoCapabilityOperation(operation: VideoCapabilityOperation): BackendOperationExplanation;
+export declare function getVideoCapabilityBackend(): VideoCapabilityBackend;
+export declare function hasVideoCapabilityHostBackend(): boolean;
+export declare function hasVideoCapabilityOperation(operation: VideoCapabilityOperation): boolean;
 export declare function inferVideoMimeType(url: string): string | null;
+export declare function installVideoCapabilityHostBackend(backend: VideoCapabilityBackend): void;
+export declare function observeVideoCapabilityHostResult(operation: VideoCapabilityOperation, succeeded: boolean): void;
+export declare function resetVideoCapabilityBackendForTest(): void;
 export declare function selectVideoResourceUrl(sources: Readonly<VideoResourceUrl[]>): VideoResourceUrl | null;
+export declare function setVideoCapabilityBackend(backend: VideoCapabilityBackend | null): void;
 //# sourceMappingURL=videoFormat.d.ts.map

package/dist/videoFormat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"videoFormat.d.ts","sourceRoot":"","sources":["../src/videoFormat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAKjE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG1D;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAcjF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwB7D;AAKD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,EAAE,CAAC,GAAG,gBAAgB,GAAG,IAAI,CAKrG"}
+{"version":3,"file":"videoFormat.d.ts","sourceRoot":"","sources":["../src/videoFormat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,2BAA2B,EAC3B,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAElC,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG1D;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAcjF;AAED,wBAAgB,6BAA6B,IAAI,kBAAkB,CAalE;AAED,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,wBAAwB,GAAG,2BAA2B,CAgBhH;AAED,wBAAgB,yBAAyB,IAAI,sBAAsB,CAElE;AAED,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD;AAED,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,wBAAwB,GAAG,OAAO,CAExF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwB7D;AAED,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAMvF;AAED,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,wBAAwB,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAK9G;AAED,wBAAgB,kCAAkC,IAAI,IAAI,CAKzD;AAKD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,EAAE,CAAC,GAAG,gBAAgB,GAAG,IAAI,CASrG;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,IAAI,CAEtF"}

package/dist/videoFormat.js

@@ -1,9 +1,7 @@
-// True when the current environment claims it can play the given MIME type (a non-empty canPlayType
-// result — 'maybe' or 'probably'). Returns false in headless environments (jsdom) where no codecs
-// are registered. This is the codec-probe primitive that source selection is built on.
 export function canPlayVideoType(mimeType) {
-    const probe = document.createElement('video');
-    return probe.canPlayType(mimeType) !== '';
+    if (mimeType === '')
+        return false;
+    return probeSelectedBackend(getVideoCapabilityBackend(), mimeType);
 }
 // Sniffs a container MIME type from the leading bytes of encoded video, or null when unrecognised.
 // Mirrors detectImageMimeType. mkv and webm share the Matroska/EBML signature (the DocType that
@@ -23,6 +21,46 @@ export function detectVideoMimeType(data) {
         return 'video/ogg';
     return null;
 }
+export function explainVideoCapabilityBackend() {
+    if (_custom !== null) {
+        return { conflict: _hostConflict, layer: 'custom', operation: null, viability: 'unobserved' };
+    }
+    if (_host !== null) {
+        return {
+            conflict: _hostConflict,
+            layer: 'host',
+            operation: _hostObservation !== null ? _hostObservation.operation : null,
+            viability: _hostObservation !== null ? _hostObservation.viability : 'unobserved',
+        };
+    }
+    return { conflict: false, layer: 'host-not-enabled', operation: null, viability: 'unobserved' };
+}
+export function explainVideoCapabilityOperation(operation) {
+    if (_custom !== null) {
+        return typeof _custom[operation] === 'function'
+            ? { implemented: true, layer: 'custom', operation }
+            : { implemented: false, layer: 'none', operation };
+    }
+    if (_host !== null) {
+        return typeof _host[operation] === 'function'
+            ? { implemented: true, layer: 'host', operation }
+            : { implemented: false, layer: 'none', operation };
+    }
+    return {
+        implemented: false,
+        layer: typeof _sentinel[operation] === 'function' ? 'sentinel' : 'none',
+        operation,
+    };
+}
+export function getVideoCapabilityBackend() {
+    return _custom ?? _host ?? _sentinel;
+}
+export function hasVideoCapabilityHostBackend() {
+    return _host !== null;
+}
+export function hasVideoCapabilityOperation(operation) {
+    return explainVideoCapabilityOperation(operation).implemented;
+}
 export function inferVideoMimeType(url) {
     const ext = url.split('?')[0].split('.').pop()?.toLowerCase();
     switch (ext) {
@@ -48,14 +86,64 @@ export function inferVideoMimeType(url) {
             return null;
     }
 }
+export function installVideoCapabilityHostBackend(backend) {
+    if (_host !== null) {
+        if (_host !== backend)
+            _hostConflict = true;
+        return;
+    }
+    _host = backend;
+}
+export function observeVideoCapabilityHostResult(operation, succeeded) {
+    _hostObservation = {
+        operation,
+        viability: succeeded ? 'available' : 'runtime-api-unavailable',
+    };
+}
+export function resetVideoCapabilityBackendForTest() {
+    _custom = null;
+    _host = null;
+    _hostConflict = false;
+    _hostObservation = null;
+}
 // Picks the first source the environment can play, resolving each source's MIME type from its
 // explicit `type` or, failing that, its URL extension. Returns null when none is playable — the
 // source-negotiation primitive behind loadVideoResourceFromUrls.
 export function selectVideoResourceUrl(sources) {
+    let backend = null;
     for (const source of sources) {
-        if (canPlayVideoType(source.type ?? inferVideoMimeType(source.url) ?? ''))
+        const mimeType = source.type ?? inferVideoMimeType(source.url) ?? '';
+        if (mimeType === '')
+            continue;
+        backend ??= getVideoCapabilityBackend();
+        if (probeSelectedBackend(backend, mimeType))
             return source;
     }
     return null;
 }
+export function setVideoCapabilityBackend(backend) {
+    _custom = backend;
+}
+function probeSelectedBackend(backend, mimeType) {
+    if (mimeType === '')
+        return false;
+    try {
+        return backend.canPlayType(mimeType) === true;
+    }
+    catch {
+        return false;
+    }
+}
+const _sentinel = {
+    canPlayType() {
+        return false;
+    },
+    createVideoElement() {
+        return null;
+    },
+};
+let _custom = null;
+let _host = null;
+let _hostConflict = false;
+let _hostObservation = null;
 //# sourceMappingURL=videoFormat.js.map

package/dist/videoFormat.js.map

@@ -1 +1 @@
-{"version":3,"file":"videoFormat.js","sourceRoot":"","sources":["../src/videoFormat.ts"],"names":[],"mappings":"AAEA,oGAAoG;AACpG,kGAAkG;AAClG,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO,KAAK,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;AAC5C,CAAC;AAED,mGAAmG;AACnG,gGAAgG;AAChG,qGAAqG;AACrG,MAAM,UAAU,mBAAmB,CAAC,IAA8B;IAChE,MAAM,CAAC,GAAG,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IACnE,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAElC,yEAAyE;IACzE,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IAE9G,4CAA4C;IAC5C,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC;IAE1F,6BAA6B;IAC7B,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IAEzF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,CAAC;IAC9D,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,KAAK,CAAC;QACX,KAAK,KAAK;YACR,OAAO,WAAW,CAAC;QACrB,KAAK,MAAM;YACT,OAAO,YAAY,CAAC;QACtB,KAAK,KAAK;YACR,OAAO,kBAAkB,CAAC;QAC5B,KAAK,KAAK,CAAC;QACX,KAAK,KAAK;YACR,OAAO,WAAW,CAAC;QACrB,KAAK,KAAK;YACR,OAAO,iBAAiB,CAAC;QAC3B,KAAK,KAAK;YACR,OAAO,YAAY,CAAC;QACtB,KAAK,MAAM;YACT,OAAO,+BAA+B,CAAC;QACzC,KAAK,KAAK;YACR,OAAO,sBAAsB,CAAC;QAChC;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,gGAAgG;AAChG,iEAAiE;AACjE,MAAM,UAAU,sBAAsB,CAAC,OAAqC;IAC1E,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,gBAAgB,CAAC,MAAM,CAAC,IAAI,IAAI,kBAAkB,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO,MAAM,CAAC;IAC3F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"videoFormat.js","sourceRoot":"","sources":["../src/videoFormat.ts"],"names":[],"mappings":"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"}

package/dist/videoResource.d.ts

@@ -1,5 +1,6 @@
 import type { VideoResource } from '@flighthq/types/contract';
-export declare function createVideoResource(element?: HTMLVideoElement, objectUrl?: string): VideoResource;
+export declare function createVideoResource(element?: HTMLVideoElement, objectUrl?: string, ownsElement?: boolean): VideoResource;
+export declare function destroyVideoResource(resource: VideoResource): void;
 export declare function disposeVideoResource(resource: VideoResource): void;
 export declare function getVideoResourceDuration(resource: Readonly<VideoResource>): number;
 export declare function getVideoResourceHeight(resource: Readonly<VideoResource>): number;

package/dist/videoResource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"videoResource.d.ts","sourceRoot":"","sources":["../src/videoResource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAO9D,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,gBAAgB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAEjG;AAQD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAalE;AAID,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAGlF;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAGhF;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAG/E;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAElF;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAG/E;AAID,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAG/E"}
+{"version":3,"file":"videoResource.d.ts","sourceRoot":"","sources":["../src/videoResource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAS9D,wBAAgB,mBAAmB,CACjC,OAAO,CAAC,EAAE,gBAAgB,EAC1B,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,OAAO,GACpB,aAAa,CAEf;AAMD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAgBlE;AAKD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAYlE;AAID,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAGlF;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAGhF;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAG/E;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAElF;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAG/E;AAID,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAG/E"}

package/dist/videoResource.js

@@ -1,30 +1,49 @@
 // No cloneVideoResource: a VideoResource is a thin carrier over a single HTMLVideoElement, and an
 // element cannot be duplicated (each carries its own decoder and playback position). Wrap the same
 // element in a second createVideoResource call if two carriers over one stream are truly wanted.
-// `objectUrl` transfers ownership of a blob object URL to the resource, so disposal revokes it. Pass
+// `objectUrl` transfers ownership of a blob object URL to the resource, so destruction revokes it. Pass
 // it only for a URL this resource should own — a caller-managed URL stays the caller's to revoke.
-export function createVideoResource(element, objectUrl) {
-    return { element: element ?? null, objectUrl: objectUrl ?? null };
-}
-// Releases the decoder the element holds: clearing the src and calling load() detaches the media
-// resource so the browser can free its buffers, then the element reference is dropped for GC. Also
-// revokes an owned object URL, whose blob-store entry is what keeps the underlying Blob reachable —
-// the revoke belongs here, at end of life, because the element fetches from that URL for as long as it
-// plays. Both are dispose*, not destroy*: each releases a reference so memory becomes GC-eligible,
-// rather than freeing a non-GC handle.
+// `ownsElement` true means this resource created the element and destroyVideoResource will release
+// its decoder; false means the caller supplied it and destruction only drops the reference.
+export function createVideoResource(element, objectUrl, ownsElement) {
+    return { element: element ?? null, objectUrl: objectUrl ?? null, ownsElement: ownsElement ?? false };
+}
+// Releases a video resource's non-GC state: for owned elements, detaches the media source so the
+// browser can free decoder buffers and drops MediaStream srcObject (without stopping caller-owned
+// tracks); for borrowed elements, only drops the reference. Revokes a held object URL in either case
+// since it is the resource's to manage regardless of element ownership.
+export function destroyVideoResource(resource) {
+    const element = resource.element;
+    if (element !== null && resource.ownsElement) {
+        // Detach a live MediaStream without stopping its tracks — those belong to the caller.
+        if (element.srcObject !== null) {
+            element.srcObject = null;
+        }
+        element.removeAttribute('src');
+        element.load();
+    }
+    if (resource.objectUrl !== null) {
+        URL.revokeObjectURL(resource.objectUrl);
+        resource.objectUrl = null;
+    }
+    resource.element = null;
+    resource.ownsElement = false;
+}
+// Legacy unconditional teardown — releases the decoder regardless of ownership. Callers that know
+// they own the element (e.g. loader error paths that just created it) can still use this; for
+// caller-provided elements, prefer destroyVideoResource which respects the ownership flag.
 export function disposeVideoResource(resource) {
     const element = resource.element;
     if (element !== null) {
         element.removeAttribute('src');
         element.load();
     }
-    // Revoked after the element has let go of the src, so the media resource is never detached from a
-    // URL the element is still reading through.
     if (resource.objectUrl !== null) {
         URL.revokeObjectURL(resource.objectUrl);
         resource.objectUrl = null;
     }
     resource.element = null;
+    resource.ownsElement = false;
 }
 // Duration in seconds of the loaded media, or 0 when no element is attached. May be NaN before
 // metadata has loaded and Infinity for open-ended live streams — both come straight from the element.

package/dist/videoResource.js.map

@@ -1 +1 @@
-{"version":3,"file":"videoResource.js","sourceRoot":"","sources":["../src/videoResource.ts"],"names":[],"mappings":"AAEA,kGAAkG;AAClG,mGAAmG;AACnG,iGAAiG;AACjG,qGAAqG;AACrG,kGAAkG;AAClG,MAAM,UAAU,mBAAmB,CAAC,OAA0B,EAAE,SAAkB;IAChF,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,SAAS,EAAE,SAAS,IAAI,IAAI,EAAE,CAAC;AACpE,CAAC;AAED,iGAAiG;AACjG,mGAAmG;AACnG,oGAAoG;AACpG,uGAAuG;AACvG,mGAAmG;AACnG,uCAAuC;AACvC,MAAM,UAAU,oBAAoB,CAAC,QAAuB;IAC1D,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAkC,CAAC;IAC5D,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAC/B,OAAO,CAAC,IAAI,EAAE,CAAC;IACjB,CAAC;IACD,kGAAkG;IAClG,4CAA4C;IAC5C,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAChC,GAAG,CAAC,eAAe,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACxC,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC;IAC5B,CAAC;IACD,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;AAC1B,CAAC;AAED,+FAA+F;AAC/F,sGAAsG;AACtG,MAAM,UAAU,wBAAwB,CAAC,QAAiC;IACxE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAkC,CAAC;IAC5D,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,QAAiC;IACtE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAkC,CAAC;IAC5D,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAAiC;IACrE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAkC,CAAC;IAC5D,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,QAAiC;IACvE,OAAO,QAAQ,CAAC,OAAO,KAAK,IAAI,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,QAAiC;IACpE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAkC,CAAC;IAC5D,OAAO,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC,IAAI,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;AACjF,CAAC;AAED,qGAAqG;AACrG,kGAAkG;AAClG,MAAM,UAAU,oBAAoB,CAAC,QAAiC;IACpE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAkC,CAAC;IAC5D,OAAO,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,UAAU,IAAI,iBAAiB,CAAC;AACrE,CAAC;AAED,4FAA4F;AAC5F,MAAM,iBAAiB,GAAG,CAAC,CAAC"}
+{"version":3,"file":"videoResource.js","sourceRoot":"","sources":["../src/videoResource.ts"],"names":[],"mappings":"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"}

package/dist/videoResourceFrom.d.ts

@@ -1,5 +1,5 @@
 import type { VideoResource, VideoResourceLoadOptions, VideoResourceUrl } from '@flighthq/types/contract';
-export declare function createVideoResourceFromMediaStream(stream: MediaStream): VideoResource;
+export declare function createVideoResourceFromMediaStream(stream: MediaStream): VideoResource | null;
 export declare function loadVideoResourceFromBlob(blob: Blob, options?: Readonly<VideoResourceLoadOptions>, signal?: AbortSignal): Promise<VideoResource>;
 export declare function loadVideoResourceFromUrl(url: string, options?: Readonly<VideoResourceLoadOptions>, signal?: AbortSignal): Promise<VideoResource>;
 export declare function loadVideoResourceFromUrls(sources: Readonly<VideoResourceUrl[]>, options?: Readonly<VideoResourceLoadOptions>, signal?: AbortSignal): Promise<VideoResource>;

package/dist/videoResourceFrom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"videoResourceFrom.d.ts","sourceRoot":"","sources":["../src/videoResourceFrom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAO1G,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAIrF;AAUD,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,QAAQ,CAAC,wBAAwB,CAAC,EAC5C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAWxB;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,QAAQ,CAAC,wBAAwB,CAAC,EAC5C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA4CxB;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,EAAE,CAAC,EACrC,OAAO,CAAC,EAAE,QAAQ,CAAC,wBAAwB,CAAC,EAC5C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAIxB"}
+{"version":3,"file":"videoResourceFrom.d.ts","sourceRoot":"","sources":["../src/videoResourceFrom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAO1G,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,GAAG,IAAI,CAK5F;AAUD,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,QAAQ,CAAC,wBAAwB,CAAC,EAC5C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAWxB;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,QAAQ,CAAC,wBAAwB,CAAC,EAC5C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA6CxB;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,EAAE,CAAC,EACrC,OAAO,CAAC,EAAE,QAAQ,CAAC,wBAAwB,CAAC,EAC5C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAIxB"}

package/dist/videoResourceFrom.js

@@ -1,11 +1,13 @@
-import { selectVideoResourceUrl } from './videoFormat';
+import { getVideoCapabilityBackend, selectVideoResourceUrl } from './videoFormat';
 import { createVideoResource, disposeVideoResource } from './videoResource';
 // Wraps a live MediaStream (camera, screen capture, canvas.captureStream) as a video resource by
-// assigning it to element.srcObject. Pure DOM, no load — the stream feeds frames as they arrive.
+// assigning it to element.srcObject. Returns null when the backend cannot create a video element.
 export function createVideoResourceFromMediaStream(stream) {
-    const element = document.createElement('video');
+    const element = (getVideoCapabilityBackend().createVideoElement?.() ?? null);
+    if (element === null)
+        return null;
     element.srcObject = stream;
-    return createVideoResource(element);
+    return createVideoResource(element, undefined, true);
 }
 // Loads from a Blob by wrapping it in an object URL, which the returned resource then owns: pass it to
 // disposeVideoResource to revoke it. The revoke deliberately does not happen when the load settles —
@@ -31,8 +33,10 @@ export async function loadVideoResourceFromBlob(blob, options, signal) {
 export function loadVideoResourceFromUrl(url, options, signal) {
     if (signal?.aborted)
         return Promise.reject(signal.reason);
+    const element = (getVideoCapabilityBackend().createVideoElement?.() ?? null);
+    if (element === null)
+        return Promise.reject(new Error('No video element backend available'));
     return new Promise((resolve, reject) => {
-        const element = document.createElement('video');
         element.preload = (options?.preload ?? 'auto');
         // crossOrigin must be set before assigning src so the fetched frames stay untainted for GPU upload.
         if (options?.crossOrigin !== undefined)
@@ -44,7 +48,7 @@ export function loadVideoResourceFromUrl(url, options, signal) {
         const readyEvent = readinessEventName(options?.readiness);
         const onReady = () => {
             cleanup();
-            resolve(createVideoResource(element));
+            resolve(createVideoResource(element, undefined, true));
         };
         // Both rejection paths abandon an element this function created, so both owe it the same decoder
         // release — routed through disposeVideoResource so the sequence has exactly one home. Assigning

package/dist/videoResourceFrom.js.map

@@ -1 +1 @@
-{"version":3,"file":"videoResourceFrom.js","sourceRoot":"","sources":["../src/videoResourceFrom.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"videoResourceFrom.js","sourceRoot":"","sources":["../src/videoResourceFrom.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/video",
-  "version": "0.5.0-next.1944.cd6b6e7",
+  "version": "0.5.1-edge.638.d4dbd4e",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.5.0-next.1944.cd6b6e7"
+    "@flighthq/types": "0.5.1-edge.638.d4dbd4e"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/videoFormat.test.ts

@@ -1,18 +1,56 @@
-import { canPlayVideoType, detectVideoMimeType, inferVideoMimeType, selectVideoResourceUrl } from './videoFormat';
+import type { VideoCapabilityBackend, VideoResourceUrl } from '@flighthq/types/contract';
+
+import {
+  canPlayVideoType,
+  detectVideoMimeType,
+  explainVideoCapabilityBackend,
+  explainVideoCapabilityOperation,
+  getVideoCapabilityBackend,
+  hasVideoCapabilityHostBackend,
+  hasVideoCapabilityOperation,
+  inferVideoMimeType,
+  installVideoCapabilityHostBackend,
+  observeVideoCapabilityHostResult,
+  resetVideoCapabilityBackendForTest,
+  selectVideoResourceUrl,
+  setVideoCapabilityBackend,
+} from './videoFormat';
 
 afterEach(() => {
+  resetVideoCapabilityBackendForTest();
   vi.restoreAllMocks();
 });
 
 describe('canPlayVideoType', () => {
-  it('is false in jsdom where no codecs are registered', () => {
+  it('is false when no backend is installed', () => {
     expect(canPlayVideoType('video/mp4')).toBe(false);
   });
 
-  it('is true when the element reports it can play the type', () => {
-    vi.spyOn(HTMLVideoElement.prototype, 'canPlayType').mockReturnValue('probably');
+  it('uses an installed custom backend', () => {
+    setVideoCapabilityBackend({ canPlayType: () => true });
     expect(canPlayVideoType('video/mp4')).toBe(true);
   });
+
+  it('rejects an empty MIME type without invoking the selected backend', () => {
+    const canPlayType = vi.fn(() => true);
+    setVideoCapabilityBackend({ canPlayType });
+    expect(canPlayVideoType('')).toBe(false);
+    expect(canPlayType).not.toHaveBeenCalled();
+  });
+
+  it('accepts only primitive true from an untyped backend', () => {
+    setVideoCapabilityBackend({ canPlayType: () => 'probably' } as unknown as VideoCapabilityBackend);
+    expect(canPlayVideoType('video/mp4')).toBe(false);
+  });
+
+  it('normalizes backend exceptions to false', () => {
+    setVideoCapabilityBackend({
+      canPlayType(): boolean {
+        throw new Error('unavailable');
+      },
+    });
+    expect(canPlayVideoType('video/mp4')).toBe(false);
+  });
 });
 
 describe('detectVideoMimeType', () => {
@@ -44,6 +82,78 @@ describe('detectVideoMimeType', () => {
   });
 });
 
+describe('explainVideoCapabilityBackend', () => {
+  it('reports host observations while custom selection remains unobserved', () => {
+    installVideoCapabilityHostBackend({ canPlayType: () => true });
+    observeVideoCapabilityHostResult('canPlayType', false);
+    expect(explainVideoCapabilityBackend()).toMatchObject({
+      layer: 'host',
+      operation: 'canPlayType',
+      viability: 'runtime-api-unavailable',
+    });
+    setVideoCapabilityBackend({ canPlayType: () => true });
+    expect(explainVideoCapabilityBackend()).toMatchObject({
+      layer: 'custom',
+      operation: null,
+      viability: 'unobserved',
+    });
+  });
+});
+
+describe('explainVideoCapabilityOperation', () => {
+  it('reports sentinel, host, and custom operation support structurally', () => {
+    expect(explainVideoCapabilityOperation('canPlayType')).toEqual({
+      implemented: false,
+      layer: 'sentinel',
+      operation: 'canPlayType',
+    });
+    expect(hasVideoCapabilityOperation('canPlayType')).toBe(false);
+
+    installVideoCapabilityHostBackend({ canPlayType: () => true });
+    expect(explainVideoCapabilityOperation('canPlayType').layer).toBe('host');
+    expect(hasVideoCapabilityOperation('canPlayType')).toBe(true);
+
+    setVideoCapabilityBackend({ canPlayType: 1 } as unknown as VideoCapabilityBackend);
+    expect(explainVideoCapabilityOperation('canPlayType')).toEqual({
+      implemented: false,
+      layer: 'none',
+      operation: 'canPlayType',
+    });
+    expect(hasVideoCapabilityOperation('canPlayType')).toBe(false);
+  });
+});
+
+describe('getVideoCapabilityBackend', () => {
+  it('uses custom over host and reveals the host again when custom is cleared', () => {
+    const host = { canPlayType: vi.fn(() => true) };
+    const custom = { canPlayType: vi.fn(() => false) };
+    installVideoCapabilityHostBackend(host);
+    setVideoCapabilityBackend(custom);
+    expect(getVideoCapabilityBackend()).toBe(custom);
+    expect(canPlayVideoType('video/mp4')).toBe(false);
+    setVideoCapabilityBackend(null);
+    expect(getVideoCapabilityBackend()).toBe(host);
+    expect(canPlayVideoType('video/mp4')).toBe(true);
+  });
+});
+
+describe('hasVideoCapabilityHostBackend', () => {
+  it('tracks host occupancy independently of a custom backend', () => {
+    setVideoCapabilityBackend({ canPlayType: () => true });
+    expect(hasVideoCapabilityHostBackend()).toBe(false);
+    installVideoCapabilityHostBackend({ canPlayType: () => false });
+    expect(hasVideoCapabilityHostBackend()).toBe(true);
+  });
+});
+
+describe('hasVideoCapabilityOperation', () => {
+  it('cannot diverge from the operation explanation', () => {
+    expect(hasVideoCapabilityOperation('canPlayType')).toBe(explainVideoCapabilityOperation('canPlayType').implemented);
+    setVideoCapabilityBackend({ canPlayType: () => true });
+    expect(hasVideoCapabilityOperation('canPlayType')).toBe(explainVideoCapabilityOperation('canPlayType').implemented);
+  });
+});
+
 describe('inferVideoMimeType', () => {
   it('returns "video/mp4" for .mp4 files', () => {
     expect(inferVideoMimeType('clip.mp4')).toBe('video/mp4');
@@ -98,6 +208,47 @@ describe('inferVideoMimeType', () => {
   });
 });
 
+describe('installVideoCapabilityHostBackend', () => {
+  it('keeps the first host and reports only a distinct second host as conflict', () => {
+    const first = { canPlayType: vi.fn(() => true) };
+    installVideoCapabilityHostBackend(first);
+    installVideoCapabilityHostBackend(first);
+    expect(explainVideoCapabilityBackend().conflict).toBe(false);
+    installVideoCapabilityHostBackend({ canPlayType: () => false });
+    expect(getVideoCapabilityBackend()).toBe(first);
+    expect(explainVideoCapabilityBackend().conflict).toBe(true);
+  });
+});
+
+describe('observeVideoCapabilityHostResult', () => {
+  it('records successful host viability', () => {
+    installVideoCapabilityHostBackend({ canPlayType: () => true });
+    observeVideoCapabilityHostResult('canPlayType', true);
+    expect(explainVideoCapabilityBackend()).toMatchObject({
+      operation: 'canPlayType',
+      viability: 'available',
+    });
+  });
+});
+
+describe('resetVideoCapabilityBackendForTest', () => {
+  it('reset clears custom, host, conflict, and observation state', () => {
+    installVideoCapabilityHostBackend({ canPlayType: () => true });
+    installVideoCapabilityHostBackend({ canPlayType: () => false });
+    observeVideoCapabilityHostResult('canPlayType', true);
+    setVideoCapabilityBackend({ canPlayType: () => true });
+    resetVideoCapabilityBackendForTest();
+    expect(hasVideoCapabilityHostBackend()).toBe(false);
+    expect(explainVideoCapabilityBackend()).toEqual({
+      conflict: false,
+      layer: 'host-not-enabled',
+      operation: null,
+      viability: 'unobserved',
+    });
+    expect(canPlayVideoType('video/mp4')).toBe(false);
+  });
+});
+
 describe('selectVideoResourceUrl', () => {
   it('returns null when no source is playable', () => {
     expect(selectVideoResourceUrl([{ url: 'clip.mp4' }])).toBeNull();
@@ -108,18 +259,86 @@ describe('selectVideoResourceUrl', () => {
   });
 
   it('picks the first source whose inferred type is playable', () => {
-    vi.spyOn(HTMLVideoElement.prototype, 'canPlayType').mockImplementation((type) =>
-      type === 'video/webm' ? 'probably' : '',
-    );
+    setVideoCapabilityBackend({ canPlayType: (type) => type === 'video/webm' });
     const selected = selectVideoResourceUrl([{ url: 'clip.mp4' }, { url: 'clip.webm' }]);
     expect(selected?.url).toBe('clip.webm');
   });
 
   it('honours an explicit type over the URL extension', () => {
-    vi.spyOn(HTMLVideoElement.prototype, 'canPlayType').mockImplementation((type) =>
-      type === 'video/mp4' ? 'maybe' : '',
-    );
+    setVideoCapabilityBackend({ canPlayType: (type) => type === 'video/mp4' });
     const selected = selectVideoResourceUrl([{ url: 'stream', type: 'video/mp4' }]);
     expect(selected?.url).toBe('stream');
   });
+
+  it('treats an explicit empty type as authoritative and does not read the URL', () => {
+    const canPlayType = vi.fn(() => true);
+    setVideoCapabilityBackend({ canPlayType });
+    const source = Object.defineProperties(
+      {},
+      {
+        type: { value: '', enumerable: true },
+        url: {
+          enumerable: true,
+          get(): string {
+            throw new Error('URL must remain unread');
+          },
+        },
+      },
+    ) as VideoResourceUrl;
+    expect(selectVideoResourceUrl([source])).toBeNull();
+    expect(canPlayType).not.toHaveBeenCalled();
+  });
+
+  it('skips unknown inferred types without invoking the backend', () => {
+    const canPlayType = vi.fn(() => true);
+    setVideoCapabilityBackend({ canPlayType });
+    expect(selectVideoResourceUrl([{ url: 'clip.avi' }])).toBeNull();
+    expect(canPlayType).not.toHaveBeenCalled();
+  });
+
+  it('pins one lazily resolved backend across a reentrant custom-backend change', () => {
+    const replacement = { canPlayType: vi.fn(() => false) };
+    const initial = {
+      canPlayType: vi.fn((type: string) => {
+        setVideoCapabilityBackend(replacement);
+        return type === 'video/webm';
+      }),
+    };
+    setVideoCapabilityBackend(initial);
+    expect(selectVideoResourceUrl([{ url: 'clip.mp4' }, { url: 'clip.webm' }])?.url).toBe('clip.webm');
+    expect(initial.canPlayType).toHaveBeenCalledTimes(2);
+    expect(replacement.canPlayType).not.toHaveBeenCalled();
+  });
+
+  it('continues after invalid truthy results and backend exceptions', () => {
+    const canPlayType = vi
+      .fn()
+      .mockReturnValueOnce('probably')
+      .mockImplementationOnce(() => {
+        throw new Error('unavailable');
+      })
+      .mockReturnValueOnce(true);
+    setVideoCapabilityBackend({ canPlayType } as VideoCapabilityBackend);
+    const selected = selectVideoResourceUrl([{ url: 'first.mp4' }, { url: 'second.webm' }, { url: 'third.ogv' }]);
+    expect(selected?.url).toBe('third.ogv');
+  });
+
+  it('does not swallow caller property-access exceptions', () => {
+    const source = Object.defineProperty({ url: 'clip.mp4' }, 'type', {
+      get(): string {
+        throw new Error('caller getter failed');
+      },
+    }) as VideoResourceUrl;
+    expect(() => selectVideoResourceUrl([source])).toThrow('caller getter failed');
+  });
+});
+
+describe('setVideoCapabilityBackend', () => {
+  it('selects and clears a custom backend', () => {
+    const custom = { canPlayType: () => true };
+    setVideoCapabilityBackend(custom);
+    expect(getVideoCapabilityBackend()).toBe(custom);
+    setVideoCapabilityBackend(null);
+    expect(getVideoCapabilityBackend()).not.toBe(custom);
+  });
 });

package/src/videoResource.test.ts

@@ -1,5 +1,6 @@
 import {
   createVideoResource,
+  destroyVideoResource,
   disposeVideoResource,
   getVideoResourceDuration,
   getVideoResourceHeight,
@@ -19,12 +20,135 @@ describe('createVideoResource', () => {
   it('returns a resource with null element when called with no arguments', () => {
     const resource = createVideoResource();
     expect(resource.element).toBeNull();
+    expect(resource.ownsElement).toBe(false);
   });
 
-  it('stores the provided video element', () => {
+  it('stores the provided video element as borrowed by default', () => {
     const element = document.createElement('video');
     const resource = createVideoResource(element);
     expect(resource.element).toBe(element);
+    expect(resource.ownsElement).toBe(false);
+  });
+
+  it('marks element as owned when explicitly requested', () => {
+    const element = document.createElement('video');
+    const resource = createVideoResource(element, undefined, true);
+    expect(resource.element).toBe(element);
+    expect(resource.ownsElement).toBe(true);
+  });
+});
+
+describe('destroyVideoResource', () => {
+  it('releases an owned element by detaching src and reloading to free the decoder', () => {
+    const removeAttribute = vi.fn();
+    const load = vi.fn();
+    const element = { removeAttribute, load, srcObject: null } as unknown as HTMLVideoElement;
+    const resource = createVideoResource(element, undefined, true);
+
+    destroyVideoResource(resource);
+
+    expect(removeAttribute).toHaveBeenCalledWith('src');
+    expect(load).toHaveBeenCalledOnce();
+    expect(resource.element).toBeNull();
+    expect(resource.ownsElement).toBe(false);
+  });
+
+  it('does not release a borrowed element — the caller manages its lifecycle', () => {
+    const removeAttribute = vi.fn();
+    const load = vi.fn();
+    const element = { removeAttribute, load, srcObject: null } as unknown as HTMLVideoElement;
+    const resource = createVideoResource(element);
+
+    destroyVideoResource(resource);
+
+    expect(removeAttribute).not.toHaveBeenCalled();
+    expect(load).not.toHaveBeenCalled();
+    expect(resource.element).toBeNull();
+    expect(resource.ownsElement).toBe(false);
+  });
+
+  it('clears srcObject on an owned MediaStream element without stopping caller-owned tracks', () => {
+    const track = { stop: vi.fn() } as unknown as MediaStreamTrack;
+    const stream = { getTracks: () => [track] } as unknown as MediaStream;
+    const element = {
+      removeAttribute: vi.fn(),
+      load: vi.fn(),
+      srcObject: stream,
+    } as unknown as HTMLVideoElement;
+    const resource = createVideoResource(element, undefined, true);
+
+    destroyVideoResource(resource);
+
+    expect(element.srcObject).toBeNull();
+    expect(track.stop).not.toHaveBeenCalled();
+  });
+
+  it('does not touch srcObject on a borrowed element', () => {
+    const stream = {} as MediaStream;
+    const element = {
+      removeAttribute: vi.fn(),
+      load: vi.fn(),
+      srcObject: stream,
+    } as unknown as HTMLVideoElement;
+    const resource = createVideoResource(element);
+
+    destroyVideoResource(resource);
+
+    expect(element.srcObject).toBe(stream);
+  });
+
+  it('revokes an owned object URL after the element has released its src', () => {
+    const order: string[] = [];
+    vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => void order.push('revoke'));
+    const element = {
+      removeAttribute: vi.fn(() => void order.push('removeAttribute')),
+      load: vi.fn(() => void order.push('load')),
+      srcObject: null,
+    } as unknown as HTMLVideoElement;
+
+    destroyVideoResource(createVideoResource(element, 'blob:owned', true));
+
+    expect(order).toEqual(['removeAttribute', 'load', 'revoke']);
+  });
+
+  it('revokes an object URL even when the element is borrowed', () => {
+    const revokeSpy = vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {});
+    const element = { srcObject: null } as unknown as HTMLVideoElement;
+    const resource = createVideoResource(element, 'blob:owned');
+
+    destroyVideoResource(resource);
+
+    expect(revokeSpy).toHaveBeenCalledWith('blob:owned');
+    expect(resource.objectUrl).toBeNull();
+  });
+
+  it('is idempotent — a second destruction is a no-op', () => {
+    const revokeSpy = vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {});
+    const element = {
+      removeAttribute: vi.fn(),
+      load: vi.fn(),
+      srcObject: null,
+    } as unknown as HTMLVideoElement;
+    const resource = createVideoResource(element, 'blob:owned', true);
+
+    destroyVideoResource(resource);
+    destroyVideoResource(resource);
+
+    expect(element.removeAttribute).toHaveBeenCalledTimes(1);
+    expect(revokeSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('nulls the element so VideoChannel queries degrade to sentinels', () => {
+    const element = {
+      removeAttribute: vi.fn(),
+      load: vi.fn(),
+      srcObject: null,
+    } as unknown as HTMLVideoElement;
+    const resource = createVideoResource(element, undefined, true);
+
+    destroyVideoResource(resource);
+
+    expect(resource.element).toBeNull();
   });
 });
 
@@ -40,6 +164,7 @@ describe('disposeVideoResource', () => {
     expect(removeAttribute).toHaveBeenCalledWith('src');
     expect(load).toHaveBeenCalledOnce();
     expect(resource.element).toBeNull();
+    expect(resource.ownsElement).toBe(false);
   });
 
   it('is a no-op on an already element-less resource', () => {

package/src/videoResourceFrom.test.ts

@@ -1,3 +1,8 @@
+import {
+  installVideoCapabilityHostBackend,
+  resetVideoCapabilityBackendForTest,
+  setVideoCapabilityBackend,
+} from './videoFormat';
 import {
   createVideoResourceFromMediaStream,
   loadVideoResourceFromBlob,
@@ -5,20 +10,23 @@ import {
   loadVideoResourceFromUrls,
 } from './videoResourceFrom';
 
-// Capture every <video> the loaders create so tests can drive its media events synchronously.
+// Capture every <video> the backend creates so tests can drive its media events synchronously.
 let created: HTMLVideoElement[];
 
 beforeEach(() => {
   created = [];
-  const original = document.createElement.bind(document);
-  vi.spyOn(document, 'createElement').mockImplementation(((tag: string, options?: ElementCreationOptions) => {
-    const element = original(tag, options);
-    if (tag === 'video') created.push(element as HTMLVideoElement);
-    return element;
-  }) as typeof document.createElement);
+  installVideoCapabilityHostBackend({
+    canPlayType: () => false,
+    createVideoElement() {
+      const element = document.createElement('video');
+      created.push(element);
+      return element;
+    },
+  });
 });
 
 afterEach(() => {
+  resetVideoCapabilityBackendForTest();
   vi.restoreAllMocks();
 });
 
@@ -27,11 +35,19 @@ function lastVideo(): HTMLVideoElement {
 }
 
 describe('createVideoResourceFromMediaStream', () => {
-  it('wraps a MediaStream by assigning it to srcObject', () => {
+  it('wraps a MediaStream by assigning it to srcObject and marks the element as owned', () => {
     const stream = {} as MediaStream;
     const resource = createVideoResourceFromMediaStream(stream);
-    expect(resource.element).not.toBeNull();
-    expect((resource.element as HTMLVideoElement).srcObject).toBe(stream);
+    expect(resource).not.toBeNull();
+    expect(resource!.element).not.toBeNull();
+    expect((resource!.element as HTMLVideoElement).srcObject).toBe(stream);
+    expect(resource!.ownsElement).toBe(true);
+  });
+
+  it('returns null when the backend cannot create a video element', () => {
+    resetVideoCapabilityBackendForTest();
+    const resource = createVideoResourceFromMediaStream({} as MediaStream);
+    expect(resource).toBeNull();
   });
 });
 
@@ -46,6 +62,7 @@ describe('loadVideoResourceFromBlob', () => {
     lastVideo().dispatchEvent(new Event('canplay'));
     const resource = await promise;
     expect(resource.objectUrl).toBe('blob:mock');
+    expect(resource.ownsElement).toBe(true);
     expect(revokeSpy).not.toHaveBeenCalled();
   });
 
@@ -97,6 +114,12 @@ describe('loadVideoResourceFromUrl', () => {
     element.dispatchEvent(new Event('canplay'));
     const resource = await promise;
     expect(resource.element).toBe(element);
+    expect(resource.ownsElement).toBe(true);
+  });
+
+  it('rejects when the backend cannot create a video element', async () => {
+    resetVideoCapabilityBackendForTest();
+    await expect(loadVideoResourceFromUrl('test.mp4')).rejects.toThrow('No video element backend available');
   });
 
   it('applies crossOrigin, muted, and preload from options', async () => {
@@ -185,7 +208,14 @@ describe('loadVideoResourceFromUrls', () => {
   });
 
   it('loads the first playable source', async () => {
-    vi.spyOn(HTMLVideoElement.prototype, 'canPlayType').mockReturnValue('probably');
+    setVideoCapabilityBackend({
+      canPlayType: () => true,
+      createVideoElement() {
+        const element = document.createElement('video');
+        created.push(element);
+        return element;
+      },
+    });
     const promise = loadVideoResourceFromUrls([{ url: 'clip.mp4' }]);
     const element = lastVideo();
     element.dispatchEvent(new Event('canplay'));