jsdom 31.0.0

v31.0.0

on Node.js NPM

Breaking changes

• Changed the optional canvas and image decoding backend from canvas to @napi-rs/canvas. Install @napi-rs/canvas v1.0.13 or later in the v1.x series alongside jsdom; installing canvas alone no longer enables this support. The new backend provides prebuilt Skia binaries on supported platforms, and rendering and encoded image bytes can differ. Projects using native canvas objects or custom font registration should follow the canvas migration guidance. Added WebP serialization through canvas.toDataURL() and canvas.toBlob(). Fixed image loading to wait for decoding before firing load, discard obsolete source requests, avoid refetching when dimensions change, and prevent failed images from drawing stale contents. Fixed canvas context and serialization behavior, including unsupported context types, read-only ctx.canvas, image-drawing exceptions, MIME type and quality normalization, and asynchronous null results from canvas.toBlob() for empty canvases or encoding failures. (@Brooooooklyn)
• Changed CSS parsing, selector matching, and computed styles to use a new integrated implementation, with substantially expanded support and faster selector queries and repeated style reads. This includes cascade layers, nesting, @scope, custom-property substitution and registration through @property and CSS.registerProperty(), typed attr(), conditional if(), shadow-tree styling with :host, ::slotted(), and ::part(), pseudo-element computed styles, and constructable stylesheets with document.adoptedStyleSheets and shadowRoot.adoptedStyleSheets. Fixed numerous cascade, shorthand, serialization, and default-style issues; computed declarations now stay live across DOM and stylesheet changes. CSS serialization and computed values can differ from previous releases.
• Changed HTML and XML parsing to pause at blocking scripts until their required resources are ready. The JSDOM constructor, JSDOM.fromURL(), and JSDOM.fromFile() can now return partially parsed documents. Wait for DOMContentLoaded for the finished tree, or the window's load event for load-delaying resources, checking document.readyState first in case the event has already fired. XML syntax errors encountered after asynchronous parsing resumes are reported through the virtual console as "xml-parsing" errors.

Other changes

• Added window.reportError(), which dispatches an error event and reports uncanceled errors to the virtual console. (@sarankumar1325)
• Added element.ariaBrailleLabel and element.ariaBrailleRoleDescription. (@Kjubikstronk)
• Fixed page-completion load events to fire only on the window. Use window.addEventListener("load", ...) or window.onload instead of listening on the document.
• Fixed document.open(), including implicit calls from document.write(), to clear event listeners and handlers from the document, its descendants, and its window when replacing the input stream.
• Fixed document.write() to process successive writes through the parser's input stream, preserve insertion points across nested scripts, and make completed text immediately visible. Script-created input streams now remain open until document.close().
• Fixed dynamically inserted scripts to respect script.async = false execution order, use their source text and document from preparation time, and avoid executing after adoption into another document. Scripts parsed through inert fragment APIs no longer execute when subsequently inserted.
• Fixed unrelated images, stylesheets, and frames being delayed behind scripts, and resource completion events firing before nested stylesheet imports finish. Cyclic imports no longer prevent completion, and <style> elements in shadow trees now fire load events.
• Fixed window.stop() to cancel pending subresource and XMLHttpRequest requests in descendant frames and suppress completion events for canceled loads, while allowing subsequent requests to proceed.
• Fixed repeated document.close() calls replaying readiness and load events, and incorrect iframe load events when reopening documents from event handlers.
• Fixed memory leaks where pending request interceptor promises retained closed windows, introduced in v28.0.0.
• Fixed focus remaining on elements that become non-focusable after DOM or style changes. Focus now moves asynchronously to the document's viewport, and element.blur() can release it immediately.
• Fixed document.hasFocus() returning false before an element is focused or during focus transitions within the document, including inside frames.
• Fixed <template> parsing and template.innerHTML serialization in XML documents, including templates with namespace prefixes. (@b84330808)
• Fixed rect.toJSON() and performance.toJSON() to create their result objects in the method's realm instead of the host Node.js realm.