@napi-rs/webcodecs 1.4.2 → 1.5.0

package/LICENSES.md

@@ -0,0 +1,40 @@
+# Licenses and binary distribution
+
+The original source code of `@napi-rs/webcodecs` is licensed under the MIT
+license in [LICENSE](LICENSE). That license and its copyright notice remain
+unchanged. It does not replace the licenses of bundled third-party code.
+
+## Native packages
+
+The `@napi-rs/webcodecs-*` platform packages contain native addons that statically
+link FFmpeg and codec libraries. The checked-in build recipes enable
+`--enable-gpl`, `--enable-version3`, `--enable-libx264`, and `--enable-libx265`.
+FFmpeg describes this configuration as GPL version 3 or later; see its
+[licensing explanation](licenses/ffmpeg-LICENSE.md.txt) and
+[GPLv3 text](licenses/ffmpeg-COPYING.GPLv3.txt).
+
+These addons cannot be described as MIT-only distributions. Distribution of
+the combined GPL-covered work must satisfy GPLv3, including the applicable
+Corresponding Source requirements. The original MIT grant for this project's
+own source remains available; it does not provide an exception to those
+requirements for the combined binaries. The root JavaScript package selects
+these addons through optional dependencies, so installing it normally also
+installs a native package with these obligations.
+
+The npm `license` field points here to distinguish the original source license
+from the conditions on the binary distribution. It is not a dual-license offer
+allowing a recipient to select MIT for the bundled native addon.
+
+## Third-party material and source status
+
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) lists the configured dependencies
+and reference license texts. Preserve their copyright, license, patent, and
+other required notices when redistributing them. See
+[SOURCE_DISTRIBUTION.md](SOURCE_DISTRIBUTION.md) for the source-material gaps
+identified in the 1.4.2 distribution and the work required before the next
+binary release. The repository URL and these notice files alone are not a
+complete Corresponding Source distribution or a written source offer.
+
+This notice correction does not certify compliance of existing releases,
+change codec features, or relicense the project's original source. Custom
+builds require an inventory of the libraries actually linked into them.

package/README.md

@@ -348,6 +348,33 @@ frame.close()
 
 **Note:** Canvas pixel data is copied as RGBA format with sRGB color space.
 
+### Native float canvas interop
+
+Native canvas providers can retain RGBA16Float images with
+`createVideoFrameFromRGBA16Float(data, init)`. `data` contains tightly packed
+RGBA half-float bit patterns in a `Uint16Array`, with four
+components per coded pixel. The native frame copies the input once; clones share
+immutable storage, and closing one frame leaves its clones usable. Supply the
+image color space in `init.colorSpace`; the default is full-range sRGB.
+
+These frames have `format === null`. Public `allocationSize()` throws and
+`copyTo()` rejects with `NotSupportedError`, including requests for an explicit
+eight-bit format. `copyVideoFrameRGBA16Float(frame)` gives native image consumers
+an independent copy of the half-float bits without changing that public contract.
+It returns the whole coded image (`codedWidth * codedHeight * 4` values) and
+ignores `visibleRect`.
+These functions are module exports rather than additions to `VideoFrame.prototype`.
+Native GPU consumers can use `registerVideoFrameCloseObserver(frame, callback)`
+to expire their retained textures synchronously when that frame is explicitly
+closed. Clones have independent observers. Collecting a frame wrapper releases
+its observers while independently retained GPU images remain usable.
+
+The FFmpeg encoder cannot consume this opaque image resource. `encode()` queues
+the input normally, then reports a native `OperationError`, rejects pending
+`flush()` calls with the same error, and closes the encoder without output.
+This interop does not implement WebGPU external-texture import or cross-worker
+frame transport.
+
 ## Supported Codecs
 
 ### Video
@@ -589,7 +616,9 @@ frame.close()
 
 Per WPT `videoFrame-copyTo-rgb.any.js`, RGB-to-YUV conversion throws `NotSupportedError`.
 
-Custom layouts with overflow-inducing values (e.g., `offset: 2³²-2`) throw `TypeError` via checked arithmetic. Rect alignment is validated against the source format during conversion.
+Like Chrome, `copyTo()` accepts an explicit `format` only for RGBA, RGBX, BGRA and BGRX. Any other `format`, even the frame's own, rejects with `NotSupportedError`; leave `format` out to copy in the frame's own format. `allocationSize()` still accepts the frame's own format. Invalid arguments and options make `copyTo()` reject the returned promise (with `TypeError` or `NotSupportedError`) instead of throwing. Only a call on an object that is not a `VideoFrame` still throws.
+
+Custom layouts with overflow-inducing values (e.g., `offset: 2³²-2`) throw `TypeError` via checked arithmetic. The copy `rect` is validated against the output format. For YUV-to-RGB conversion, the read origin is then aligned down to the source chroma grid, as Chrome does.
 
 ### ImageDecoder Options
 
@@ -597,15 +626,13 @@ ImageDecoder supports all W3C spec options:
 
 | Option                 | Status | Notes                                                                             |
 | ---------------------- | ------ | --------------------------------------------------------------------------------- |
-| `desiredWidth/Height`  | ✅     | Scales decoded frames to specified dimensions                                     |
-| `preferAnimation`      | ✅     | When `false`, only decodes first frame for animated formats                       |
+| `desiredWidth/Height`  | ✅     | Like Chrome: scales JPEG only, to M/8 of its size; other formats stay full size   |
+| `preferAnimation`      | ✅     | `false`: GIF first frame only, AVIF still image; APNG/WebP ignore it, like Chrome |
 | `colorSpaceConversion` | ✅     | `"default"` extracts color space metadata, `"none"` ignores it (Chromium-aligned) |
 
-**Note:** Per W3C spec, `desiredWidth` and `desiredHeight` must both be specified or both omitted.
+**Note:** `desiredWidth` and `desiredHeight` follow Chrome, not the spec. A missing one, or a 0, is no error: the desired size is then ignored. Chrome decodes a JPEG at M/8 of its size (rounded up), where M = ⌊8 × √(desired area / image area)⌋, or 8 when the desired area is at least the image's. A JPEG scaled this way is BGRX. When even 1/8 is too large (M = 0), `tracks.ready` rejects with `InvalidStateError` and the decoder closes. Like Chrome, libjpeg-turbo scales the JPEG while it decodes it.
 
-### Platform-Specific Notes
-
-- **ImageDecoder GIF animation**: FFmpeg may return only the first frame. Use `VideoDecoder` with GIF codec for full animation.
+**Note:** GIF and BMP are not decoded by FFmpeg, but by decoders that follow Chrome: Wuffs' rules for GIF, the `image` crate's for BMP. Every GIF frame is decoded; it lasts its delay (0 too) and starts when the frames before it end. A frame that fails to decode rejects with `RangeError`; once every frame failed, `decode()` rejects with `EncodingError` and the decoder closes.
 
 ### Per-Frame Quantizer Control
 
@@ -694,6 +721,9 @@ For full API documentation, see the [W3C WebCodecs specification](https://w3c.gi
 - Rust (latest stable)
 - Node.js 18+
 - pnpm
+- NASM 2.15.05 or newer, for x86_64 builds (libjpeg-turbo's SIMD code): `brew install nasm`,
+  `apt-get install nasm` (Ubuntu 22.04 or Debian 11 and newer) or `choco install nasm` (then
+  add `C:\Program Files\NASM` to `PATH`), or set `NASM` to its path
 
 The build downloads the pinned FFmpeg 9.0 release by default. If you opt out
 of that download or set `FFMPEG_DIR`, the supplied FFmpeg headers and libraries
@@ -722,4 +752,11 @@ cargo clippy
 
 ## License
 
-MIT
+The original project source is [MIT licensed](LICENSE). The prebuilt native
+addons statically link GPL-enabled FFmpeg, x264, x265, and other libraries;
+their distribution is subject to additional terms, including GPLv3.
+
+Read [LICENSES.md](LICENSES.md), [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md),
+and the outstanding [Corresponding Source work](SOURCE_DISTRIBUTION.md) before
+redistributing the prebuilt packages. The MIT source license alone does not
+cover the bundled native binaries.

package/SOURCE_DISTRIBUTION.md

@@ -0,0 +1,111 @@
+# Corresponding Source: release work still required
+
+Status: notice and packaging corrections only. No complete source bundle has
+been reconstructed, verified, or published by this change. Do not treat the
+presence of these files or a passing packaging check as release clearance.
+
+## What was checked for 1.4.2
+
+The `v1.4.2` tag resolves to
+`3eb6525afb643baadcbe628f536e30265404d818`, also the root npm package's
+`gitHead`. The registry tarballs for the root and all nine native packages were
+downloaded and checked against their npm SHA-512 integrity values.
+
+- The root tarball contains eight files, including the original MIT `LICENSE`.
+- Each native tarball contains only `package.json`, `README.md`, and its `.node`
+  binary. All ten manifests advertise `MIT`. The native packages contain no
+  license, notice, or Corresponding Source files.
+- x264-identifying strings are present in every native binary. This supports
+  the build-recipe evidence but does not identify all linked revisions.
+  The final addons did not retain a discoverable FFmpeg configure/license
+  string in this inspection; no complete binary dependency attestation has
+  been established.
+- `build.rs` pins nine digests for the `ffmpeg-n9.0.2` static-library release.
+  That release lists nine binary/install archives and no dedicated third-party
+  source archive. Its automatic GitHub repository source snapshot contains the
+  wrapper and build scripts, not the downloaded upstream source trees.
+- The macOS arm64 and both Windows static-library archives were downloaded and
+  their SHA-256 values verified against the release metadata. Their file lists
+  contain headers/libraries but no license, copyright, notice, or source tree.
+  Inspection of their `avutil` static libraries confirms `n9.0.2` and the
+  `--enable-gpl`, `--enable-version3`, `--enable-libx264`, and
+  `--enable-libx265` configure options. The other six static-library archives
+  have not been inspected in this audit.
+
+References: [npm root metadata](https://registry.npmjs.org/@napi-rs%2fwebcodecs/1.4.2),
+[1.4.2 source](https://github.com/Brooooooklyn/webcodecs-node/tree/3eb6525afb643baadcbe628f536e30265404d818),
+[FFmpeg static-library release](https://github.com/Brooooooklyn/webcodecs-node/releases/tag/ffmpeg-n9.0.2).
+
+## Requirements to implement for the existing GPL build
+
+[GPLv3](licenses/ffmpeg-COPYING.GPLv3.txt) sections 1, 4, 5, and 6 cover the
+source and object-code distribution conditions. Section 1 covers the source
+needed to generate, install, run, and modify the work, including the controlling
+scripts; its System Library and general-purpose-tool exclusions require a
+component-specific assessment. Preserve applicable notices and identify changes
+and their dates. Distribution of the combined covered work must satisfy GPLv3
+as a whole while retaining compatible upstream notices, including MIT.
+
+For npm/network distribution, section 6(d) provides a route: equivalent access
+to Corresponding Source at no extra charge, with clear directions beside the
+object code. A different source server is permitted under that section, but
+the distributor remains responsible for source availability. A generic link to
+upstream or an unimplemented promise to provide source is insufficient. The
+physical-product written-offer route in section 6(b) is not a generic substitute
+for the npm download route. Installation Information may also be required when
+the section 6 User Product conditions apply.
+
+Before another release using this configuration:
+
+1. Recover the actual source inputs for each old binary where available. Record
+   package version, target, addon hash, FFmpeg archive hash, build run, source
+   commits, tarball hashes, dependency lockfiles, and toolchain versions. Do not
+   use today's dependency HEAD as evidence of the 1.4.2 inputs.
+2. Retain all source trees required for the combined addon, including this
+   project's Rust/C/JS sources, third-party code, relevant generated/interface
+   inputs, and build/install scripts. Include transitive components unless a
+   documented exclusion applies; a directory of static `.a`/`.lib` files and
+   headers is not Corresponding Source.
+3. Capture exact revisions and modifications. Unix x264 is unpinned; most
+   dependency clones reuse an existing directory without revision validation.
+   LAME's archive has no input checksum. The build script modifies x265 CMake
+   policy settings and FFmpeg's generated `config.h` for Zig, emits compiler
+   wrappers/toolchain files, and rewrites pkg-config files. Preserve those
+   instructions and the actual patches/configuration, with change notices.
+   libjpeg-turbo is vendored in `vendor/libjpeg-turbo` as an unmodified copy
+   of Chromium's tree; Chromium's changes are listed in its `README.chromium`,
+   `CHROMIUM_PIN` records the Chromium revision, and `build.rs` holds the
+   compile flags (symbol prefix, 12/16-bit objects, SIMD defines, NASM flags).
+4. For Windows, retain the pinned vcpkg ports, resolved source archives and
+   patches, triplets, feature selections, installed copyright files, and the
+   source/build dependencies for the separately downloaded rav1e staticlib.
+   Keep the x265 alpha/multilib build instructions as well.
+5. Recover the release's resolved Cargo dependencies and toolchains where
+   possible. For future releases, record lockfiles, immutable source identities,
+   build environment and the actual linked library list alongside each binary.
+   Byte-for-byte reproducibility is useful verification, not itself the GPL's
+   definition of Corresponding Source.
+6. Assemble the source materials and notices, test rebuilding each target from
+   them, and resolve differences. Check upstream embedded subcomponent notices
+   and runtime terms; the reference notice inventory is not complete evidence.
+7. Choose and maintain a version-specific source distribution location. Put
+   working links and checksums beside npm binaries and FFmpeg downloads and in
+   every platform package; verify access without credentials. Do not invent
+   source URLs or publish placeholders. Existing 1.4.2 tarballs cannot be fixed
+   by editing the next version's package files alone.
+
+## Maintainer decision
+
+The original MIT license is preserved. Choose the future binary distribution
+approach before publishing:
+
+- Retain the GPL-enabled codecs and meet the combined-work GPLv3 distribution
+  requirements, including complete corresponding-source delivery and notices.
+- Design and rebuild a distribution without GPL components. This requires an
+  actual codec/build/dependency review, removing GPL configure options and
+  affected code, capability tests, and continued satisfaction of applicable
+  LGPL and other dependency terms. It is not an MIT-only shortcut; static
+  LGPL linking has its own requirements.
+
+This patch makes neither choice and removes no codecs. It provides an
+engineering inventory of the evidence and gaps, not a legal determination.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,87 @@
+# Third-party notices
+
+The native addon uses FFmpeg and the dependencies below. Version entries are
+build-recipe references, not a verified bill of materials for each released
+binary. All platforms receive this combined notice bundle; inclusion of a
+license text does not mean that component is present on every platform.
+
+Full reference texts, copyright notices, and patent notices are in `licenses/`.
+[licenses/manifest.json](licenses/manifest.json) records where each text was
+obtained and its SHA-256 digest. A source-file header excerpt is explicitly
+marked there. Those digests identify notice files, not source archives or
+binaries. Original project source remains under [MIT](LICENSE); see
+[LICENSES.md](LICENSES.md) for the combined binary distribution.
+
+## Configured dependencies
+
+The Unix versions come from `tools/build-ffmpeg/src/main.rs`. Windows uses
+vcpkg commit `74e6536215718009aae747d86d84b78376bf9e09` plus separately built
+x265 and, on x64, a downloaded rav1e static library. The vcpkg baseline is pinned;
+its port patches and actual resolved build inputs must also be retained.
+
+| Component                  | Build reference                                                                                  | Reference terms and files in `licenses/`                                                                               |
+| -------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| FFmpeg                     | `n9.0.2`, all targets                                                                            | GPL-3.0-or-later for the configured build; `ffmpeg-LICENSE.md.txt`, `ffmpeg-COPYING.*.txt`                             |
+| x264                       | Unix: unpinned shallow clone; Windows: `0.164.3108` / `31e19f92f00c7003fa115047ce50978bc98c3a0d` | GPL-2.0-or-later; `x264-COPYING.txt`, `x264-x264.h.txt`                                                                |
+| x265                       | `Release_4.1`, multilib with alpha                                                               | GPL-2.0-or-later; `x265-COPYING.txt`, `x265-source-x265.h.txt`                                                         |
+| libvpx                     | `v1.15.2`                                                                                        | BSD-3-Clause and patent grant; `libvpx-LICENSE.txt`, `libvpx-PATENTS.txt`                                              |
+| libaom                     | `v3.13.1`; excluded from Windows x64 recipe                                                      | BSD-2-Clause and AOM patent license; `aom-LICENSE.txt`, `aom-PATENTS.txt`                                              |
+| rav1e                      | `v0.8.1`, Windows x64 prebuilt archive                                                           | BSD-2-Clause and patent grant; `rav1e-LICENSE.txt`, `rav1e-PATENTS.txt`; transitive dependencies require inventory     |
+| dav1d                      | Windows vcpkg `1.5.1`                                                                            | BSD-2-Clause; `dav1d-COPYING.txt`                                                                                      |
+| Opus                       | `v1.5.2`                                                                                         | BSD-style notice and patent references; `opus-COPYING.txt`                                                             |
+| LAME / libmp3lame / mpghip | `3.100`                                                                                          | GNU Library GPL v2 text and upstream guidance; `lame-COPYING.txt`, `lame-LICENSE.txt`; retain component-level headers  |
+| libogg                     | Unix `v1.3.5`; Windows `v1.3.6`                                                                  | BSD-3-Clause; `ogg-COPYING.txt`, `ogg-windows-COPYING.txt`                                                             |
+| libvorbis                  | `v1.3.7`                                                                                         | BSD-3-Clause; `vorbis-COPYING.txt`                                                                                     |
+| libwebp / libsharpyuv      | `v1.6.0`                                                                                         | BSD-3-Clause and patent grant; `libwebp-COPYING.txt`, `libwebp-PATENTS.txt`                                            |
+| zlib                       | `v1.3.1`                                                                                         | zlib license; `zlib-LICENSE.txt`                                                                                       |
+| JPEG XL / libjxl           | `v0.11.1`                                                                                        | BSD-3-Clause and patent grant; `libjxl-LICENSE.txt`, `libjxl-PATENTS.txt`                                              |
+| Highway                    | `1.3.0`                                                                                          | Apache-2.0 / BSD-3-Clause reference texts; `highway-LICENSE.txt`, `highway-LICENSE-BSD3.txt`; inspect file-level terms |
+| Brotli                     | `v1.1.1`                                                                                         | MIT; `brotli-LICENSE.txt`                                                                                              |
+| Little CMS 2               | Unix `lcms2.16`; Windows `lcms2.17`                                                              | MIT; `lcms2-LICENSE.txt`, `lcms2-windows-LICENSE.txt`                                                                  |
+| NVIDIA codec headers       | Linux recipe `n13.0.19.0`, except armv7                                                          | MIT; `nv-codec-headers-nvEncodeAPI.h.txt`                                                                              |
+| libjpeg-turbo              | `3.1.0` from Chrome `155.0.8059.79` DEPS, in `vendor/libjpeg-turbo`, all targets                 | IJG License, BSD-3-Clause and zlib; `libjpeg-turbo-LICENSE.md.txt`, `libjpeg-turbo-README.ijg.txt`; see below          |
+| Blink JPEG decoder         | `jpeg_image_decoder.cc` from Chrome `155.0.8059.79`, rewritten as `src/ffi/jpeg_blink.c`         | LGPL-2.1-or-later, MPL-1.1 or GPL-2.0; notice in `src/ffi/jpeg_blink.c`; `ffmpeg-COPYING.LGPLv2.1.txt`                 |
+
+This software is based in part on the work of the Independent JPEG Group.
+FFmpeg's licensing explanation identifies IJG-derived codec files requiring
+this attribution, and so does the IJG License of libjpeg-turbo. The checked-in
+build recipe does not modify FFmpeg's files. `vendor/libjpeg-turbo` is an
+unmodified copy of files from Chromium's libjpeg-turbo tree, and `build.rs`
+compiles it as is. Chromium's own changes to libjpeg-turbo (`jpeglibmangler.h`,
+included from `jpeglib.h`, and the hand-edited `jconfig.h` and `jconfigint.h`)
+are listed in `vendor/libjpeg-turbo/README.chromium`; `CHROMIUM_LICENSE` and
+`simd/nasm/jsimdext.inc` there hold the notices that `jpeglibmangler.h`,
+`jsimd.h`, `jsimddct.h` and most SIMD files refer to (the Neon files hold their
+zlib notice themselves). Byte-for-byte copies are packaged as
+`licenses/libjpeg-turbo-CHROMIUM_LICENSE.txt` and
+`licenses/libjpeg-turbo-jsimdext.inc.txt`. The SIMD code bears the zlib License,
+which `LICENSE.md` says the IJG License subsumes in the built library. Other
+builds must document any changes to these files.
+
+`src/ffi/jpeg_blink.c` is a C rewrite of Blink's `jpeg_image_decoder.cc`:
+Copyright (C) 2006 Apple Computer, Inc.; portions Copyright (C) 2001-6
+mozilla.org. A recipient may use it under the LGPL 2.1 or later, the MPL 1.1 or
+the GPL 2.0; its header holds the full notice.
+
+## Inventory still required for release
+
+These reference texts are an initial notice inventory. They do not establish
+that every upstream subcomponent notice or actual linked dependency has been
+captured. In particular:
+
+- Capture the exact x264 revision for every Unix build; the reference header in
+  this bundle is identified by its own commit, not asserted to be the binary's.
+- Preserve vcpkg port patches and installed `share/*/copyright` files, checking
+  their contents against the exact source trees and transitive dependencies.
+- Inventory Rust dependencies (including rav1e's), the Rust standard library,
+  statically linked C/C++/compiler runtimes, and any platform-specific notices.
+  `Cargo.lock` is currently ignored and release toolchains are not all pinned.
+- `build.rs` searches local library paths and may link additional optional
+  libraries. These custom builds need their own notice and source inventory.
+- Resolve and publish the matching source materials described in
+  [SOURCE_DISTRIBUTION.md](SOURCE_DISTRIBUTION.md).
+
+Upstream entry points: [FFmpeg](https://ffmpeg.org/legal.html),
+[x264](https://code.videolan.org/videolan/x264),
+[x265](https://bitbucket.org/multicoreware/x265_git), and
+[vcpkg baseline](https://github.com/microsoft/vcpkg/tree/74e6536215718009aae747d86d84b78376bf9e09/ports).

package/index.d.ts

@@ -96,7 +96,7 @@ export interface MuxerVideoTrackConfig {
   /** Video height */
   height: number
   /** Codec description (e.g., avcC for H.264) */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
 }
 
 /** Audio track config for muxer */
@@ -108,7 +108,7 @@ export interface MuxerAudioTrackConfig {
   /** Number of channels */
   numberOfChannels: number
   /** Codec description */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
 }
 
 // ============================================================================
@@ -178,6 +178,14 @@ export type TypedArray =
   | BigInt64Array
   | BigUint64Array
 
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
 /**
  * AudioData - represents uncompressed audio data
  *
@@ -425,13 +433,19 @@ export declare class AudioEncoder {
  * Used for codedRect and visibleRect properties
  */
 export declare class DOMRectReadOnly {
-  /** Create a new DOMRectReadOnly */
+  /**
+   * Create a new DOMRectReadOnly
+   *
+   * Arguments convert like WebIDL `unrestricted double` (ToNumber), as in browsers.
+   */
   constructor(
     x?: number | undefined | null,
     y?: number | undefined | null,
     width?: number | undefined | null,
     height?: number | undefined | null,
   )
+  /** Create a DOMRectReadOnly from a DOMRectInit dictionary (Geometry Interfaces `fromRect`) */
+  static fromRect(other?: DOMRectInit): DOMRectReadOnly
   /** X coordinate */
   get x(): number
   /** Y coordinate */
@@ -440,16 +454,16 @@ export declare class DOMRectReadOnly {
   get width(): number
   /** Height */
   get height(): number
-  /** Top edge (same as y) */
+  /** Top edge: min(y, y + height), NaN if either is NaN */
   get top(): number
-  /** Right edge (x + width) */
+  /** Right edge: max(x, x + width), NaN if either is NaN */
   get right(): number
-  /** Bottom edge (y + height) */
+  /** Bottom edge: max(y, y + height), NaN if either is NaN */
   get bottom(): number
-  /** Left edge (same as x) */
+  /** Left edge: min(x, x + width), NaN if either is NaN */
   get left(): number
   /** Convert to JSON (W3C spec uses toJSON) */
-  toJSON(): DOMRectInit
+  toJSON(): DOMRectJSON
 }
 
 /**
@@ -517,7 +531,7 @@ export declare class EncodedVideoChunk {
 export declare class ImageDecoder {
   /**
    * Create a new ImageDecoder
-   * Supports both Uint8Array and ReadableStream as data source per W3C spec.
+   * Supports a BufferSource (copied here) or a ReadableStream as data source per W3C spec.
    * ReadableStream input is buffered without a fixed size limit.
    */
   constructor(init: ImageDecoderInit)
@@ -606,8 +620,8 @@ export declare class MkvDemuxer {
   /**
    * Load an MKV from a buffer
    *
-   * This method uses zero-copy buffer loading - the Uint8Array data is passed
-   * directly to the demuxer without an intermediate copy.
+   * The bytes are copied when this is called, so the caller may reuse,
+   * detach or resize the buffer afterwards.
    */
   loadBuffer(data: Uint8Array): Promise<void>
   get tracks(): Array<DemuxerTrackInfo>
@@ -727,8 +741,8 @@ export declare class Mp4Demuxer {
   /**
    * Load an MP4 from a buffer
    *
-   * This method uses zero-copy buffer loading - the Uint8Array data is passed
-   * directly to the demuxer without an intermediate copy.
+   * The bytes are copied when this is called, so the caller may reuse,
+   * detach or resize the buffer afterwards.
    */
   loadBuffer(data: Uint8Array): Promise<void>
   /** Get all tracks */
@@ -1086,15 +1100,15 @@ export declare class VideoFrame {
   /**
    * Get the coded rect (the region containing valid pixel data)
    * Returns DOMRectReadOnly per W3C WebCodecs spec
-   * Throws InvalidStateError if the VideoFrame is closed
+   * Returns null after the resource is closed.
    */
-  get codedRect(): DOMRectReadOnly
+  get codedRect(): DOMRectReadOnly | null
   /**
    * Get the visible rect (the region of coded data that should be displayed)
    * Returns DOMRectReadOnly per W3C WebCodecs spec
-   * Throws InvalidStateError if the VideoFrame is closed
+   * Returns null after the resource is closed.
    */
-  get visibleRect(): DOMRectReadOnly
+  get visibleRect(): DOMRectReadOnly | null
   /**
    * Get the presentation timestamp in microseconds
    * Per W3C spec: "The timestamp getter steps are to return [[timestamp]]"
@@ -1120,9 +1134,15 @@ export declare class VideoFrame {
    * - I420A, I422A, I444A: 4 planes
    */
   get numberOfPlanes(): number
-  /** Get the rotation in degrees clockwise (0, 90, 180, 270) - W3C WebCodecs spec */
+  /**
+   * Get the rotation in degrees clockwise (0, 90, 180, 270) - W3C WebCodecs spec
+   * Returns 0 after close (Close VideoFrame resets [[rotation]]).
+   */
   get rotation(): number
-  /** Get whether horizontal flip is applied - W3C WebCodecs spec */
+  /**
+   * Get whether horizontal flip is applied - W3C WebCodecs spec
+   * Returns false after close (Close VideoFrame resets [[flip]]).
+   */
   get flip(): boolean
   /**
    * Get the metadata associated with this VideoFrame - W3C WebCodecs spec
@@ -1136,8 +1156,9 @@ export declare class VideoFrame {
    *
    * Returns a Promise that resolves with an array of PlaneLayout objects.
    * Options can specify target format and rect for cropped copy.
+   * Like Chrome, the bytes are written before this call returns.
    */
-  copyTo(destination: Uint8Array, options?: VideoFrameCopyToOptions | undefined | null): Promise<Array<PlaneLayout>>
+  copyTo(destination: Uint8Array, options?: VideoFrameCopyToOptions | undefined | null): Promise<PlaneLayout[]>
   /**
    * Clone this VideoFrame
    *
@@ -1150,7 +1171,9 @@ export declare class VideoFrame {
    * Per W3C spec "Close VideoFrame" algorithm:
    * 1. Assign null to frame's [[resource reference]]
    * 2. Assign true to frame's [[Detached]]
-   * Note: Metadata (timestamp, duration, etc.) remains accessible after close
+   * Note: timestamp and duration remain accessible after close; rotation becomes 0,
+   * flip false, codedRect and visibleRect null, every colorSpace field becomes null,
+   * and callbacks registered with registerVideoFrameCloseObserver run synchronously.
    */
   close(): void
 }
@@ -1171,8 +1194,8 @@ export declare class WebMDemuxer {
   /**
    * Load a WebM from a buffer
    *
-   * This method uses zero-copy buffer loading - the Uint8Array data is passed
-   * directly to the demuxer without an intermediate copy.
+   * The bytes are copied when this is called, so the caller may reuse,
+   * detach or resize the buffer afterwards.
    */
   loadBuffer(data: Uint8Array): Promise<void>
   get tracks(): Array<DemuxerTrackInfo>
@@ -1299,7 +1322,7 @@ export interface AudioDecoderConfigJs {
   /** Number of channels */
   numberOfChannels?: number
   /** Codec-specific description */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
 }
 
 /** Decoder configuration output (for passing to decoder) */
@@ -1371,6 +1394,24 @@ export type CodecState = 'unconfigured' | 'configured' | 'closed'
 /** ColorSpaceConversion for ImageDecoder (W3C WebCodecs spec) */
 export type ColorSpaceConversion = 'default' | 'none'
 
+/**
+ * Native image-consumer interop: copies the half-float bits of an RGBA16Float frame into a new
+ * `Uint16Array`. Returns the whole coded image; `visibleRect` is ignored. Throws a TypeError if
+ * `frame` is not a VideoFrame, InvalidStateError if it is closed, and NotSupportedError if it does
+ * not hold an RGBA16Float image.
+ */
+export declare function copyVideoFrameRGBA16Float(frame: VideoFrame): Uint16Array
+
+/** Native canvas-provider interop, separate from the browser VideoFrame interface. */
+export declare function createVideoFrameFromRGBA16Float(
+  data: Uint16Array,
+  init: Omit<VideoFrameBufferInit, 'format' | 'layout' | 'transfer'> & {
+    rotation?: number
+    flip?: boolean
+    alpha?: 'keep' | 'discard'
+  },
+): VideoFrame
+
 /** Audio decoder configuration exposed to JavaScript */
 export interface DemuxerAudioDecoderConfig {
   /** Codec string */
@@ -1423,6 +1464,18 @@ export interface DOMRectInit {
   height?: number
 }
 
+/** Result of DOMRectReadOnly.toJSON() */
+export interface DOMRectJSON {
+  x: number
+  y: number
+  width: number
+  height: number
+  top: number
+  right: number
+  bottom: number
+  left: number
+}
+
 /** Output callback metadata for audio */
 export interface EncodedAudioChunkMetadata {
   /** Decoder configuration for this chunk */
@@ -1535,7 +1588,7 @@ export interface MkvAudioTrackConfig {
   /** Number of audio channels */
   numberOfChannels: number
   /** Codec-specific description data */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
 }
 
 /** MKV muxer options */
@@ -1557,7 +1610,7 @@ export interface MkvVideoTrackConfig {
   /** Frame rate (frames per second) */
   framerate?: number
   /** Codec-specific description data */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
 }
 
 /** Audio track configuration for MP4 muxer */
@@ -1569,7 +1622,7 @@ export interface Mp4AudioTrackConfig {
   /** Number of audio channels */
   numberOfChannels: number
   /** Codec-specific description data (esds for AAC, etc.) */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
 }
 
 /** MP4 muxer options */
@@ -1599,7 +1652,7 @@ export interface Mp4VideoTrackConfig {
   /** Frame rate (frames per second) */
   framerate?: number
   /** Codec-specific description data (avcC/hvcC/av1C from encoder metadata) */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
   /**
    * HEVC sample-entry override. Default picks "hvc1" when the hvcC
    * description is well-formed, single-layer, and complete; "hev1" permits
@@ -1649,6 +1702,12 @@ export interface PlaneLayout {
   stride: number
 }
 
+/** predefined RGB target color spaces. */
+export type PredefinedColorSpace = 'srgb' | 'display-p3'
+
+/** Native image consumers subscribe to explicit close without changing the browser interface. */
+export declare function registerVideoFrameCloseObserver(frame: VideoFrame, callback: () => void): void
+
 /**
  * Reset all hardware fallback state.
  *
@@ -1696,7 +1755,7 @@ export interface VideoDecoderConfigJs {
   /** Codec string */
   codec?: string
   /** Codec-specific description */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
   /** Coded width */
   codedWidth?: number
   /** Coded height */
@@ -1787,8 +1846,10 @@ export interface VideoEncoderSupport {
   config: VideoEncoderConfig
 }
 
-/** Options for copyTo operation */
+/** options for copyTo operation. */
 export interface VideoFrameCopyToOptions {
+  /** target RGB color space. */
+  colorSpace?: PredefinedColorSpace
   /** Target pixel format (for format conversion) */
   format?: VideoPixelFormat
   /** Region to copy (not yet implemented) */
@@ -1872,7 +1933,7 @@ export interface WebMAudioTrackConfig {
   /** Number of audio channels */
   numberOfChannels: number
   /** Codec-specific description data */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
 }
 
 /** WebM muxer options */
@@ -1894,7 +1955,7 @@ export interface WebMVideoTrackConfig {
   /** Frame rate (frames per second) */
   framerate?: number
   /** Codec-specific description data */
-  description?: Uint8Array
+  description?: AllowSharedBufferSource
   /** Whether the video has alpha channel (VP9 alpha support) */
   alpha?: boolean
 }