From bf8fa96777f81de19faa83de9e8600dd21293296 Mon Sep 17 00:00:00 2001
From: Osei Fortune <fortune.osei@yahoo.com>
Date: Sun, 8 Nov 2026 01:33:40 -0400
Subject: [PATCH] docs: update for canvas 3.0.0

- New pages: OffscreenCanvas and Workers, Web API Compatibility, and
  canvas-svg Styling
- Windows and Linux in the platform and context tables, and across the
  svg, media, gamepad, audio-context and polyfill pages
- Performance: threaded 2D and WebGL rendering (what waits on the
  thread, how to opt out) and image/GPU memory behaviour
- Images: ImageAsset toImageSource() and toNativeImage(), and
  createImageBitmap rejecting undecodable bytes
- WebGPU: importExternalTexture on Android 10+, Windows and Linux
- canvas-svg: the stylesheet property, the error event, and CSS
  animations started by any selector
- Upgrading to 3.0: the late threading, WebGL, image and svg
  behaviour changes
---
 .vitepress/config.ts                          |   3 +
 .vitepress/theme/PluginsHome.vue              |   4 +-
 .vitepress/theme/components/AudioDocsHome.vue |   2 +-
 .../theme/components/CanvasDocsHome.vue       |   2 +-
 .vitepress/theme/components/CanvasHome.vue    |   2 +-
 content/audio-context/installation.md         |   3 +-
 content/canvas-svg/guides/animation.md        |   4 +-
 .../guides/properties-and-events.md           |   3 +
 content/canvas-svg/guides/styling.md          |  56 ++++++
 content/canvas-svg/index.md                   |   5 +-
 content/canvas/api.md                         |  21 +-
 content/canvas/compatibility.md               | 186 ++++++++++++++++++
 content/canvas/events.md                      |   3 +-
 content/canvas/guides/images-and-bitmaps.md   |  32 ++-
 content/canvas/guides/offscreen-canvas.md     | 155 +++++++++++++++
 content/canvas/guides/webgpu-recipes.md       |   3 +-
 content/canvas/installation.md                |  18 +-
 content/canvas/performance.md                 |  46 ++++-
 content/canvas/rendering-contexts.md          |   8 +
 content/canvas/upgrading.md                   |  22 ++-
 content/plugins/canvas-gamepad.md             |   3 +-
 content/plugins/canvas-media.md               |   4 +-
 content/plugins/canvas-polyfill.md            |   4 +-
 23 files changed, 563 insertions(+), 26 deletions(-)
 create mode 100644 content/canvas-svg/guides/styling.md
 create mode 100644 content/canvas/compatibility.md
 create mode 100644 content/canvas/guides/offscreen-canvas.md

diff --git a/.vitepress/config.ts b/.vitepress/config.ts
index f381039..fe5fee2 100644
--- a/.vitepress/config.ts
+++ b/.vitepress/config.ts
@@ -89,6 +89,7 @@ export default defineConfig({
             { text: 'WebGL Recipes', link: '/canvas/guides/webgl-recipes' },
             { text: 'WebGPU Recipes', link: '/canvas/guides/webgpu-recipes' },
             { text: 'Images and ImageBitmap', link: '/canvas/guides/images-and-bitmaps' },
+            { text: 'OffscreenCanvas and Workers', link: '/canvas/guides/offscreen-canvas' },
             { text: 'Fonts', link: '/canvas/guides/fonts' },
           ],
         },
@@ -99,6 +100,7 @@ export default defineConfig({
             { text: 'Events and Input', link: '/canvas/events' },
             { text: 'Performance', link: '/canvas/performance' },
             { text: 'API Overview', link: '/canvas/api' },
+            { text: 'Web API Compatibility', link: '/canvas/compatibility' },
             { text: 'Ecosystem Packages', link: '/canvas/ecosystem' },
           ],
         },
@@ -114,6 +116,7 @@ export default defineConfig({
           text: 'Guides',
           items: [
             { text: 'Properties and Events', link: '/canvas-svg/guides/properties-and-events' },
+            { text: 'Styling', link: '/canvas-svg/guides/styling' },
             { text: 'Building SVG with the DOM', link: '/canvas-svg/guides/dom' },
             { text: 'Animation', link: '/canvas-svg/guides/animation' },
             { text: 'Drawing SVG into a Canvas', link: '/canvas-svg/guides/canvas-integration' },
diff --git a/.vitepress/theme/PluginsHome.vue b/.vitepress/theme/PluginsHome.vue
index 621acab..25bf66b 100644
--- a/.vitepress/theme/PluginsHome.vue
+++ b/.vitepress/theme/PluginsHome.vue
@@ -13,7 +13,7 @@ const plugins = [
     stats: {
       contexts: '2D + WebGL + WebGPU',
       engine: 'Skia + WGPU',
-      platforms: 'iOS, tvOS, visionOS & Android',
+      platforms: 'Apple, Android & Windows',
     },
   },
   {
@@ -304,7 +304,7 @@ onBeforeUnmount(() => {
             </div>
             <div class="flex items-center gap-2">
               <div class="h-2 w-2 animate-pulse rounded-full bg-blue-500"></div>
-              <span>iOS, tvOS, visionOS & Android</span>
+              <span>Apple, Android & Windows</span>
             </div>
             <div class="flex items-center gap-2">
               <div class="h-2 w-2 animate-pulse rounded-full bg-orange-500"></div>
diff --git a/.vitepress/theme/components/AudioDocsHome.vue b/.vitepress/theme/components/AudioDocsHome.vue
index d1670cb..85bebb3 100644
--- a/.vitepress/theme/components/AudioDocsHome.vue
+++ b/.vitepress/theme/components/AudioDocsHome.vue
@@ -11,7 +11,7 @@ const rootRef = ref<HTMLElement | null>(null);
         <p class="audio-docs-kicker">Native audio graphs with a web-audio mental model</p>
         <h2>@nativescript/audio-context</h2>
         <p class="audio-docs-lede">
-          Build playback, synthesis, effects, routing, and offline rendering pipelines on iOS, tvOS, visionOS and Android with a familiar <code>AudioContext</code>-style API.
+          Build playback, synthesis, effects, routing, and offline rendering pipelines on iOS, tvOS, visionOS, Android and Windows with a familiar <code>AudioContext</code>-style API.
         </p>
 
         <div class="audio-docs-chip-row">
diff --git a/.vitepress/theme/components/CanvasDocsHome.vue b/.vitepress/theme/components/CanvasDocsHome.vue
index ca09f2a..cad8637 100644
--- a/.vitepress/theme/components/CanvasDocsHome.vue
+++ b/.vitepress/theme/components/CanvasDocsHome.vue
@@ -17,7 +17,7 @@ const rootRef = ref<HTMLElement | null>(null);
         </p>
 
         <div class="canvas-docs-chip-row">
-          <span>iOS, tvOS, visionOS + Android</span>
+          <span>iOS, tvOS, visionOS, Android + Windows</span>
           <span>Skia-backed rendering</span>
           <span>GPU-ready workflows</span>
           <span>Web API muscle memory</span>
diff --git a/.vitepress/theme/components/CanvasHome.vue b/.vitepress/theme/components/CanvasHome.vue
index 884b39b..55cd5c1 100644
--- a/.vitepress/theme/components/CanvasHome.vue
+++ b/.vitepress/theme/components/CanvasHome.vue
@@ -167,7 +167,7 @@ onBeforeUnmount(() => {
         </a>
         <a href="/canvas/" class="canvas-home-link-panel">
           <span>Canvas Docs</span>
-          <strong>Set up @nativescript/canvas and render with native iOS, tvOS, visionOS and Android surfaces.</strong>
+          <strong>Set up @nativescript/canvas and render with native iOS, tvOS, visionOS, Android and Windows surfaces.</strong>
         </a>
         <a href="/canvas/guides/webgl-recipes" class="canvas-home-link-panel">
           <span>Rendering Recipes</span>
diff --git a/content/audio-context/installation.md b/content/audio-context/installation.md
index 7442d81..d55bf32 100644
--- a/content/audio-context/installation.md
+++ b/content/audio-context/installation.md
@@ -20,7 +20,8 @@ npm install @nativescript/audio-context
 ## Requirements
 
 - `@nativescript/audio-context` 2.x requires **NativeScript 9.1 or later**. Pair it with `@nativescript/canvas` 3.x if you use both packages.
-- Supported platforms: iOS, tvOS, visionOS and Android. The tvOS simulator build is arm64 only, so use an Apple silicon Mac to run it in the simulator.
+- Supported platforms: iOS, tvOS, visionOS, Android, Windows and Linux. The tvOS simulator build is arm64 only, so use an Apple silicon Mac to run it in the simulator.
+- On Windows and Linux the graph is rendered by the [web-audio-api](https://github.com/orottier/web-audio-api-rs) engine, playing through WASAPI on Windows and ALSA on Linux (PulseAudio and PipeWire work through their ALSA plugins). `decodeAudioData` reads WAV, MP3, Ogg Vorbis, FLAC and AAC. A `WaveShaperNode` takes only one curve: assigning a second throws `InvalidStateError`.
 
 ## Verify setup
 
diff --git a/content/canvas-svg/guides/animation.md b/content/canvas-svg/guides/animation.md
index be38639..789f8de 100644
--- a/content/canvas-svg/guides/animation.md
+++ b/content/canvas-svg/guides/animation.md
@@ -38,7 +38,9 @@ A `begin` that waits for an event (such as `click`) never starts on its own.
 ```
 
 - Keyword easings and `cubic-bezier()` are supported. `steps()` runs as linear.
-- Only `#id` selectors are read, which is what SVG exporters produce.
+- Any selector that the [stylesheet](/canvas-svg/guides/styling#selectors) supports can start an animation, and so can an element's own `style="animation: …"`. `@keyframes` can be in any `<style>` block.
+- `translateX`, `translateY`, `scaleX` and `scaleY` animate a single axis. A `transform: none` keyframe is the identity.
+- To animate a document with CSS kept outside it, such as a CodePen's CSS panel, use the [`stylesheet`](/canvas-svg/guides/styling) property.
 
 ## Playback
 
diff --git a/content/canvas-svg/guides/properties-and-events.md b/content/canvas-svg/guides/properties-and-events.md
index 47785d7..6f8566a 100644
--- a/content/canvas-svg/guides/properties-and-events.md
+++ b/content/canvas-svg/guides/properties-and-events.md
@@ -10,6 +10,7 @@ description: Svg view properties, events and static helpers in @nativescript/can
 | Property | Default | Description |
 | --- | --- | --- |
 | `src` | | The path, URL or inline markup to render. |
+| `stylesheet` | | CSS for the document, as text or a `~/`, absolute or http path to a `.css` file. See [Styling](/canvas-svg/guides/styling). |
 | `gpu` | `true` | Rasterize on the GPU (Metal on Apple platforms, Vulkan or GL on Android). If no GPU context can be created, the view falls back to the CPU. |
 | `threaded` | `true` | Rasterize off the UI thread. See [Rendering and Performance](/canvas-svg/guides/performance). |
 | `shareSrc` | `true` | Views with the same `src` share one parsed document, one animation clock and one recording per frame. |
@@ -26,11 +27,13 @@ description: Svg view properties, events and static helpers in @nativescript/can
 | Event | Fires when |
 | --- | --- |
 | `animationEnd` | Every animation in the document has finished. It never fires for an animation that repeats forever. |
+| `error` | `src` could not be read, or is not a well-formed SVG document. `args.error` says why, and the view draws nothing. |
 | `contextLost` | The GPU context could not be rebuilt, and drawing has moved to the CPU. |
 | `contextRestored` | A lost GPU context was rebuilt, and GPU drawing has resumed. |
 
 ```ts
 view.on('animationEnd', () => console.log('done'));
+view.on('error', (args) => console.log('could not load:', args.error));
 view.on('contextLost', () => console.log('now drawing on the CPU'));
 ```
 
diff --git a/content/canvas-svg/guides/styling.md b/content/canvas-svg/guides/styling.md
new file mode 100644
index 0000000..0e06985
--- /dev/null
+++ b/content/canvas-svg/guides/styling.md
@@ -0,0 +1,56 @@
+---
+title: Styling
+description: Style an SVG document with the stylesheet property, and pass view styles such as color and fill through to it.
+---
+
+# Styling
+
+NativeScript CSS in `app.css` styles the `<Svg>` view itself, not the elements inside its document. There are two ways to reach those elements: the `stylesheet` property, and the view styles that the document inherits.
+
+## The `stylesheet` property
+
+`stylesheet` takes CSS text, or a `~/`, absolute or http path to a `.css` file. It works like a `<style>` element at the top of the SVG, so it supports full rules and `@keyframes`. Use it for CSS kept outside the SVG, such as a CodePen's CSS panel:
+
+```xml
+<svg:Svg src="~/assets/loader.svg" stylesheet="~/assets/loader.css" />
+```
+
+```ts
+view.stylesheet = `
+  @keyframes pulse { 50% { opacity: 0.3; } }
+  .dot { animation: pulse 1s ease-in-out infinite; }
+`;
+```
+
+- It is applied again every time `src` reloads.
+- Views that [share a `src`](/canvas-svg/guides/properties-and-events) share a document only if they also have the same `stylesheet`.
+- For a document built with the [DOM](/canvas-svg/guides/dom) rather than `src`, only its `@keyframes` apply.
+
+## View styles
+
+These styles on the view are inherited by the document, as they would be by an inline `<svg>` on the web:
+
+`color`, `fill`, `fill-rule`, `fill-opacity`, `stroke`, `stroke-width`, `stroke-linecap`, `stroke-linejoin` and `stroke-miterlimit`
+
+They can come from a class in `app.css` or from an inline `style`. `color` is what `currentColor` resolves to, which makes single-colour icons easy to theme:
+
+```xml
+<svg:Svg src="~/assets/icon.svg" style="color: #f43f5e; stroke-width: 2" />
+```
+
+Only the properties you set are passed on, so the document's own attributes apply otherwise.
+
+## Selectors
+
+Rules in `stylesheet`, and in the document's own `<style>` blocks, support:
+
+- type, `*`, `#id`, `.class` and attribute selectors
+- `:root`, `:first-child`, `:last-child` and `:only-child`
+- the descendant, `>`, `+` and `~` combinators
+
+Any of these selectors can start a CSS animation. See [Animation](/canvas-svg/guides/animation#css).
+
+## Related docs
+
+- [Properties and Events](/canvas-svg/guides/properties-and-events)
+- [Animation](/canvas-svg/guides/animation)
diff --git a/content/canvas-svg/index.md b/content/canvas-svg/index.md
index 420c173..217fa1a 100644
--- a/content/canvas-svg/index.md
+++ b/content/canvas-svg/index.md
@@ -5,11 +5,11 @@ description: Native SVG rendering for NativeScript with SMIL and CSS animation,
 
 # @nativescript/canvas-svg
 
-`@nativescript/canvas-svg` renders SVG natively on iOS, tvOS, visionOS and Android with Skia. Version 3.0 is a ground-up rewrite.
+`@nativescript/canvas-svg` renders SVG natively on iOS, tvOS, visionOS, Android, Windows and Linux with Skia. Version 3.0 is a ground-up rewrite.
 
 - **Animation included.** SMIL (`<animate>`, `<animateTransform>`, `<animateMotion>`, `<set>`) and CSS `@keyframes` play without any extra code.
 - **A real DOM.** When [`@nativescript/canvas-polyfill`](/plugins/canvas-polyfill) is installed, you can build and change an SVG with `document.createElementNS`, `setAttribute` and `appendChild`, as in a browser.
-- **GPU rasterization.** Metal on Apple platforms, and Vulkan or GL on Android. Drawing happens off the UI thread, and the view falls back to the CPU automatically.
+- **GPU rasterization.** Metal on Apple platforms, and Vulkan or GL on Android. Drawing happens off the UI thread, and the view falls back to the CPU automatically. Windows and Linux rasterize on the CPU.
 - **Works as a canvas image source.** You can pass an SVG to `drawImage`, `createPattern`, `createImageBitmap`, `texImage2D` and WebGPU's `copyExternalImageToTexture`.
 
 ## Installation
@@ -42,6 +42,7 @@ Any animations in the source start once the view is loaded, and pause while it i
 ## Guides
 
 - [Properties and Events](/canvas-svg/guides/properties-and-events)
+- [Styling](/canvas-svg/guides/styling)
 - [Building SVG with the DOM](/canvas-svg/guides/dom)
 - [Animation](/canvas-svg/guides/animation)
 - [Drawing SVG into a Canvas](/canvas-svg/guides/canvas-integration)
diff --git a/content/canvas/api.md b/content/canvas/api.md
index 6c8fe0c..e996357 100644
--- a/content/canvas/api.md
+++ b/content/canvas/api.md
@@ -14,9 +14,11 @@ description: API surface overview and compatibility notes for @nativescript/canv
 - WebGPU is aligned with modern WebGPU APIs.
 - `bitmaprenderer` follows the ImageBitmapRenderingContext spec.
 
+For the members that are no-ops or not available yet, see [Web API Compatibility](/canvas/compatibility).
+
 ## Globals
 
-Importing `@nativescript/canvas` installs these as globals: `CanvasRenderingContext2D`, `WebGLRenderingContext`, `WebGL2RenderingContext`, `ImageBitmapRenderingContext`, `CanvasGradient`, `CanvasPattern`, `Path2D`, `DOMMatrix`, `ImageData`, `ImageBitmap`, `ImageAsset`, `TextEncoder`, `TextDecoder`, `FontFace`, `fonts`, `TouchEvent`, `PointerEvent`, `CustomEvent`, and the WebGPU flag enums (`GPUBufferUsage`, `GPUTextureUsage`, `GPUMapMode`, `GPUShaderStage`).
+Importing `@nativescript/canvas` installs these as globals: `OffscreenCanvas`, `OffscreenCanvasRenderingContext2D`, `CanvasRenderingContext2D`, `WebGLRenderingContext`, `WebGL2RenderingContext`, `ImageBitmapRenderingContext`, `CanvasGradient`, `CanvasPattern`, `Path2D`, `DOMMatrix`, `ImageData`, `ImageBitmap`, `ImageAsset`, `TextEncoder`, `TextDecoder`, `FontFace`, `fonts`, `TouchEvent`, `PointerEvent`, `CustomEvent`, and the WebGPU flag enums (`GPUBufferUsage`, `GPUTextureUsage`, `GPUMapMode`, `GPUShaderStage`).
 
 For `window`, `document`, `navigator.gpu`, `createImageBitmap` and `Image`, add [`@nativescript/canvas-polyfill`](/plugins/canvas-polyfill).
 
@@ -34,9 +36,24 @@ For `window`, `document`, `navigator.gpu`, `createImageBitmap` and `Image`, add
 | Member | Description |
 | --- | --- |
 | `snapshot(flip?)` | Returns the current pixels as a `@nativescript/core` `ImageSource`. |
+| `transferControlToOffscreen()` | Standard. Returns an `OffscreenCanvas` that draws into this view. See [OffscreenCanvas and Workers](/canvas/guides/offscreen-canvas). |
+| `Canvas.threaded2D`, `Canvas.threadedWebGL` | Static. The default for the `threaded` context attribute: `true` on Android, iOS and Windows. Set them before calling `getContext`. See [Threaded rendering](/canvas/performance#threaded-rendering). |
 | `Canvas.forceGL` | Static. Use GL instead of Metal or Vulkan for 2D. Set it before calling `getContext`. |
 | `Canvas.useSurface` | Static, Android only. Use a `SurfaceView` instead of a `TextureView`. |
 
+## Workers
+
+In a Worker, import `@nativescript/canvas/worker` instead of `@nativescript/canvas`. It has the same API without the `Canvas` view. See [OffscreenCanvas and Workers](/canvas/guides/offscreen-canvas#rendering-in-a-worker).
+
+## ImageAsset extras
+
+| Method | Description |
+| --- | --- |
+| `toImageSource()`, `toImageSourceSync()` | Returns the pixels as a `@nativescript/core` `ImageSource`. |
+| `toNativeImage()`, `toNativeImageSync()` | Returns the pixels as the platform's image type: `Bitmap`, `UIImage`, `WriteableBitmap` or `GdkTexture`. |
+
+See [Images and ImageBitmap](/canvas/guides/images-and-bitmaps#showing-an-asset-in-an-image).
+
 ## Type imports
 
 For typed usage in TypeScript:
@@ -65,7 +82,9 @@ import type {
 - [Canvas 2D Recipes](/canvas/guides/canvas-2d-recipes)
 - [WebGL Recipes](/canvas/guides/webgl-recipes)
 - [WebGPU Recipes](/canvas/guides/webgpu-recipes)
+- [Web API Compatibility](/canvas/compatibility)
 - [Rendering Contexts](/canvas/rendering-contexts)
 - [Images and ImageBitmap](/canvas/guides/images-and-bitmaps)
+- [OffscreenCanvas and Workers](/canvas/guides/offscreen-canvas)
 - [Events and Input](/canvas/events)
 - [Ecosystem Packages](/canvas/ecosystem)
diff --git a/content/canvas/compatibility.md b/content/canvas/compatibility.md
new file mode 100644
index 0000000..b54bbcb
--- /dev/null
+++ b/content/canvas/compatibility.md
@@ -0,0 +1,186 @@
+---
+title: Web API Compatibility
+description: Which web Canvas APIs @nativescript/canvas 3.0 supports, which are no-ops, and which are not available yet.
+---
+
+# Web API Compatibility
+
+`@nativescript/canvas` 3.0 implements almost all of the modern Canvas API, so most web code runs without changes. This page lists every interface it provides and calls out anything that behaves differently from a browser.
+
+Each entry has one of three statuses:
+
+- **Supported**: behaves as on the web.
+- **No-op**: the member exists so web code doesn't throw, but it does nothing.
+- **Not yet**: not available in 3.0. Calling a missing method throws a `TypeError`. Assigning a missing property sets a plain JavaScript property that has no effect on drawing.
+
+## Not available yet
+
+Everything else on this page is supported. These are the exceptions:
+
+| API | Status | Workaround |
+| --- | --- | --- |
+| `postMessage(…, [offscreen])` on Android and iOS | Not yet | Send `OffscreenCanvas._toHandle(offscreen)` instead (see [OffscreenCanvas and Workers](/canvas/guides/offscreen-canvas#rendering-in-a-worker)). Windows supports the transfer list. |
+| A WebGPU canvas as a WebGL `texImage2D` / `texSubImage2D` source on iOS and Android | Not yet | Works on Windows and Linux. |
+| `canvas.toBlob()` | Not yet | Use `canvas.toDataURL()`, or `OffscreenCanvas.convertToBlob()`. |
+| 2D `fontKerning`, `fontStretch`, `fontVariantCaps`, `textRendering` | Not yet | Text is shaped with the font's default kerning and stretch. |
+| 2D `lang` | Not yet | |
+| 2D `isContextLost()` | Not yet | Listen for `contextlost` where the host fires it (see [Context loss](#context-loss)). |
+| `contextlost` / `webglcontextlost` events on iOS and Android | Not yet | They fire on Windows only. WebGL's `isContextLost()` works on every platform. |
+| `ImageData` `colorSpace` and `getImageData()` settings | Not yet | Pixel data is always `srgb`. |
+| `DOMMatrix`: `inverse()`, `invertSelf()`, `transformPoint()`, `flipX()`, `flipY()`, `isIdentity`, instance `multiply()`, `rotateAxisAngle()`, `rotateFromVector()`, `fromMatrix()`, `fromFloat32Array()`, `fromFloat64Array()`, `toFloat32Array()`, `toFloat64Array()` | Not yet | Use the static `DOMMatrix.multiply(a, b)`, or do the matrix maths in JavaScript. |
+| `DOMPoint`, `DOMMatrixReadOnly`, `DOMRect` | Not yet | |
+| `canvas.captureStream()` | Not planned | NativeScript has no `MediaStream`. |
+
+## Canvas element
+
+| Member | Status |
+| --- | --- |
+| `width`, `height` | Supported. These are pixels. CSS `width` / `height` set on the view are in dip. |
+| `getContext()` with `'2d'`, `'bitmaprenderer'`, `'webgl'`, `'experimental-webgl'`, `'webgl2'`, `'webgpu'` | Supported |
+| `toDataURL(type?, quality?)` | Supported |
+| `transferControlToOffscreen()` | Supported |
+| `getBoundingClientRect()`, `clientWidth`, `clientHeight` | Supported |
+| `addEventListener()`, `removeEventListener()`, `dispatchEvent()` | Supported. See [Events and Input](/canvas/events). |
+| `setPointerCapture()`, `releasePointerCapture()` | Supported |
+| `toBlob()` | Not yet |
+| `captureStream()` | Not planned |
+
+## CanvasRenderingContext2D
+
+### State, styles and compositing
+
+All supported:
+
+- `save()`, `restore()` and `reset()`
+- `fillStyle`, `strokeStyle`
+- `globalAlpha`, `globalCompositeOperation`
+- `filter`
+- `imageSmoothingEnabled`, `imageSmoothingQuality`
+- `shadowBlur`, `shadowColor`, `shadowOffsetX`, `shadowOffsetY`
+- `lineWidth`, `lineCap`, `lineJoin`, `miterLimit`
+- `setLineDash()`, `getLineDash()`, `lineDashOffset`
+- `getContextAttributes()`, `canvas`
+
+Colours accept every CSS colour syntax, including `hsl()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()` and `color()`.
+
+### Context attributes
+
+`alpha`, `colorSpace`, `willReadFrequently` and `desynchronized` are supported. `threaded` is a NativeScript extra. See [Rendering Contexts](/canvas/rendering-contexts) and [Threaded rendering](/canvas/performance#threaded-rendering).
+
+### Paths and drawing
+
+All supported:
+
+- `beginPath()`, `closePath()`, `moveTo()`, `lineTo()`
+- `bezierCurveTo()`, `quadraticCurveTo()`
+- `arc()`, `arcTo()`, `ellipse()`
+- `rect()`, `roundRect()`
+- `fill()`, `stroke()` and `clip()`, each with or without a `Path2D` and with a fill rule
+- `isPointInPath()`, `isPointInStroke()`
+- `fillRect()`, `strokeRect()`, `clearRect()`
+- `drawImage()`, in all three forms
+
+### Text
+
+| Member | Status |
+| --- | --- |
+| `fillText()`, `strokeText()`, `measureText()` | Supported |
+| `font`, `textAlign`, `textBaseline`, `direction` | Supported |
+| `letterSpacing`, `wordSpacing` | Supported |
+| `fontKerning`, `fontStretch`, `fontVariantCaps`, `textRendering` | Not yet |
+| `lang` | Not yet |
+
+`TextMetrics` returns every field: `width`, the `actualBoundingBox*` and `fontBoundingBox*` values, `emHeightAscent`, `emHeightDescent`, `hangingBaseline`, `alphabeticBaseline` and `ideographicBaseline`.
+
+### Gradients, patterns and transforms
+
+All supported:
+
+- `createLinearGradient()`, `createRadialGradient()`, `createConicGradient()` and `CanvasGradient.addColorStop()`
+- `createPattern()` and `CanvasPattern.setTransform()`
+- `translate()`, `rotate()`, `scale()`, `transform()`
+- `setTransform()`, `getTransform()`, `resetTransform()`
+
+### Pixels
+
+| Member | Status |
+| --- | --- |
+| `createImageData()`, `getImageData()`, `putImageData()` (including the dirty rect) | Supported |
+| `new ImageData(width, height)`, `new ImageData(data, width, height?)` | Supported |
+| `ImageData.colorSpace` and the `settings` argument | Not yet. Data is always `srgb`. |
+
+### No-ops
+
+| Member | Why |
+| --- | --- |
+| `drawFocusIfNeeded()`, `scrollPathIntoView()` | There is no DOM focus or scroll model. |
+| `addHitRegion()`, `removeHitRegion()`, `clearHitRegions()` | Removed from the specification. They exist only so older code doesn't throw. |
+
+### Context loss
+
+| Member | Status |
+| --- | --- |
+| `isContextLost()` | Not yet |
+| `contextlost` / `contextrestored` events | Windows only |
+
+## Path2D
+
+| Member | Status |
+| --- | --- |
+| `new Path2D()`, `new Path2D(path)`, `new Path2D(svgPathData)` | Supported |
+| `addPath()`, `moveTo()`, `lineTo()`, `closePath()`, `bezierCurveTo()`, `quadraticCurveTo()`, `arc()`, `arcTo()`, `ellipse()`, `rect()`, `roundRect()` | Supported |
+
+## DOMMatrix
+
+| Member | Status |
+| --- | --- |
+| `a`–`f`, `m11`–`m44`, `is2D` | Supported |
+| `translate()`, `scale()`, `scaleNonUniform()`, `rotate()`, `skewX()`, `skewY()` and their `*Self()` forms | Supported |
+| `multiplySelf()`, `preMultiplySelf()`, `setIdentity()`, `clone()` | Supported |
+| `toJSON()`, `toString()` | Supported |
+| Static `multiply()`, `translation()`, `scaling()`, `rotationX()`, `rotationY()`, `rotationZ()` | Supported. These are NativeScript extras. |
+| `inverse()`, `invertSelf()`, `transformPoint()`, `flipX()`, `flipY()`, `isIdentity`, `multiply()`, `rotateAxisAngle()`, `rotateFromVector()` | Not yet |
+| `fromMatrix()`, `fromFloat32Array()`, `fromFloat64Array()`, `toFloat32Array()`, `toFloat64Array()` | Not yet |
+
+## ImageBitmap
+
+| Member | Status |
+| --- | --- |
+| `createImageBitmap()` with every `ImageBitmapOptions` field (`imageOrientation`, `premultiplyAlpha`, `colorSpaceConversion`, `resizeWidth`, `resizeHeight`, `resizeQuality`) | Supported. The global `createImageBitmap` comes from [`@nativescript/canvas-polyfill`](/plugins/canvas-polyfill). |
+| `width`, `height`, `close()` | Supported |
+| `ImageBitmapRenderingContext.transferFromImageBitmap()` | Supported. Only the `alpha` attribute applies. |
+
+See [Images and ImageBitmap](/canvas/guides/images-and-bitmaps) for the sources you can create a bitmap from.
+
+## OffscreenCanvas
+
+| Member | Status |
+| --- | --- |
+| `new OffscreenCanvas(width, height)`, `width`, `height` | Supported |
+| `getContext()` with `'2d'`, `'bitmaprenderer'`, `'webgl'`, `'webgl2'`, `'webgpu'` | Supported |
+| `transferToImageBitmap()`, `convertToBlob()` | Supported |
+| `contextlost` / `contextrestored` events | Supported where the host fires them |
+| As an image source for `drawImage()`, `createPattern()`, `createImageBitmap()`, `texImage2D()`, `texSubImage2D()` and `copyExternalImageToTexture()` | Supported |
+| Moving to a Worker | Supported, with every context type. On Android and iOS, send a handle from `OffscreenCanvas._toHandle()`; Windows also takes a `postMessage` transfer list. See [OffscreenCanvas and Workers](/canvas/guides/offscreen-canvas). |
+
+## WebGL and WebGL 2
+
+The full WebGL 1 and WebGL 2 APIs are supported, including `isContextLost()`. iOS, tvOS, Android, Windows and Linux all provide them. visionOS doesn't.
+
+`getSupportedExtensions()` reports what the device offers. `getExtension()` returns an object for these:
+
+`ANGLE_instanced_arrays`, `EXT_blend_minmax`, `EXT_color_buffer_float`, `EXT_color_buffer_half_float`, `EXT_disjoint_timer_query`, `EXT_sRGB`, `EXT_shader_texture_lod`, `EXT_texture_filter_anisotropic`, `OES_element_index_uint`, `OES_standard_derivatives`, `OES_texture_float`, `OES_texture_float_linear`, `OES_texture_half_float`, `OES_texture_half_float_linear`, `OES_vertex_array_object`, `WEBGL_color_buffer_float`, `WEBGL_compressed_texture_atc`, `WEBGL_compressed_texture_etc`, `WEBGL_compressed_texture_etc1`, `WEBGL_compressed_texture_pvrtc`, `WEBGL_compressed_texture_s3tc`, `WEBGL_depth_texture`, `WEBGL_draw_buffers`, `WEBGL_lose_context`
+
+`EXT_disjoint_timer_query_webgl2` always returns `null`.
+
+## WebGPU
+
+The WebGPU API is supported through `navigator.gpu`, which comes from the polyfill: adapters, devices, buffers, textures, samplers, shader modules, render and compute pipelines, bind groups, command encoders, render bundles, query sets, `importExternalTexture()` and `copyExternalImageToTexture()`. It uses Metal on Apple platforms, Vulkan on Android (API 27+) and Linux, and Direct3D 12 on Windows. See [WebGPU Recipes](/canvas/guides/webgpu-recipes).
+
+## Related docs
+
+- [API Overview](/canvas/api)
+- [Rendering Contexts](/canvas/rendering-contexts)
+- [Images and ImageBitmap](/canvas/guides/images-and-bitmaps)
+- [Events and Input](/canvas/events)
+- [Upgrading to 3.0](/canvas/upgrading)
diff --git a/content/canvas/events.md b/content/canvas/events.md
index 34d8593..8e7d599 100644
--- a/content/canvas/events.md
+++ b/content/canvas/events.md
@@ -13,6 +13,7 @@ description: Canvas lifecycle events, pointer and touch input, Android surface e
 | `surfaceCreated` | Android | The surface was created. Only in SurfaceView mode (`Canvas.useSurface = true`). |
 | `surfaceResize` | Android | The surface changed size. The event carries `width` and `height`. |
 | `surfaceDestroyed` | Android | The surface was destroyed, for example when the app goes to the background. |
+| `contextlost`, `webglcontextlost` | Windows | The GPU device was lost (driver reset or update, GPU removed). A 2D context comes back cleared and fires `contextrestored`, unless a listener calls `preventDefault()`. A WebGL context stays lost. |
 
 ```ts
 canvas.on('ready', () => {
@@ -67,4 +68,4 @@ When the canvas is attached, it takes focus. Presses still continue up the respo
 
 ## Game controllers
 
-For full controller state (both sticks, analog triggers and every button) on iOS, tvOS, Android and Windows, use the web Gamepad API through [`@nativescript/canvas-gamepad`](/plugins/canvas-gamepad).
+For full controller state (both sticks, analog triggers and every button) on iOS, tvOS, Android, Windows and Linux, use the web Gamepad API through [`@nativescript/canvas-gamepad`](/plugins/canvas-gamepad).
diff --git a/content/canvas/guides/images-and-bitmaps.md b/content/canvas/guides/images-and-bitmaps.md
index 4acb0e6..b780419 100644
--- a/content/canvas/guides/images-and-bitmaps.md
+++ b/content/canvas/guides/images-and-bitmaps.md
@@ -28,6 +28,30 @@ ctx.drawImage(asset, 0, 0);
 
 To save an asset, use `save(path, ImageAssetSaveFormat.PNG)` or `saveSync`. The supported formats are `JPG`, `PNG`, `ICO`, `BMP` and `TIFF`.
 
+An asset loaded from a file, URL or encoded bytes keeps its compressed bytes and decodes them when needed, so it takes far less memory than its pixels would. It is still decoded once while loading, so a broken image fails at load time. See [Memory](/canvas/performance#memory).
+
+### Showing an asset in an `Image`
+
+`toImageSource()` returns a `@nativescript/core` `ImageSource`, which you can show in an `<Image>`:
+
+```ts
+const asset = new ImageAsset();
+await asset.fromUrl('https://example.com/photo.jpg');
+
+image.imageSource = await asset.toImageSource();
+```
+
+To get the platform's own image type instead, use `toNativeImage()`:
+
+| Platform | Returns |
+| --- | --- |
+| Android | `android.graphics.Bitmap` (ARGB_8888) |
+| iOS, tvOS, visionOS | `UIImage` |
+| Windows | `WriteableBitmap` |
+| Linux | `GdkTexture` |
+
+Both have sync versions, `toImageSourceSync()` and `toNativeImageSync()`. The async versions decode off the main thread. They return `null` if the asset has no pixels.
+
 ## createImageBitmap
 
 With [`@nativescript/canvas-polyfill`](/plugins/canvas-polyfill) installed, the global `createImageBitmap` works as it does on the web:
@@ -49,7 +73,7 @@ const cropped = await ImageBitmap.createFromRect(asset, 0, 0, 64, 64);
 
 ### Accepted sources
 
-- `Canvas` (any context type)
+- `Canvas` and `OffscreenCanvas` (any context type)
 - `ImageBitmap`, `ImageAsset` and `ImageData`
 - `Blob`, `ArrayBuffer` or a typed array holding encoded image bytes
 - The polyfill's `<img>` and `<canvas>` elements
@@ -65,18 +89,22 @@ const cropped = await ImageBitmap.createFromRect(asset, 0, 0, 64, 64);
 | `resizeWidth`, `resizeHeight` | number |
 | `resizeQuality` | `'pixelated'`, `'low'` (default), `'medium'`, `'high'` |
 
+The promise rejects if the source isn't recognised or its bytes can't be decoded, so you can catch the error and retry.
+
 Call `bitmap.close()` to release a bitmap early. After that, its `width` and `height` are `0`, and using it throws `InvalidStateError`.
 
 To show a bitmap without copying it, present it with a [`bitmaprenderer`](/canvas/rendering-contexts#bitmaprenderer) context.
 
 ## Canvas as an image source
 
-You can pass a canvas, or its context, anywhere an image is accepted: `drawImage`, `createPattern`, `createImageBitmap`, WebGL `texImage2D`, and WebGPU `copyExternalImageToTexture`. For example, you can render in WebGL and composite the result in 2D:
+You can pass a canvas, an [`OffscreenCanvas`](/canvas/guides/offscreen-canvas), or a context, anywhere an image is accepted: `drawImage`, `createPattern`, `createImageBitmap`, WebGL `texImage2D`, and WebGPU `copyExternalImageToTexture`. For example, you can render in WebGL and composite the result in 2D:
 
 ```ts
 ctx2d.drawImage(glCanvas, 0, 0, 200, 200);
 ```
 
+A WebGPU canvas works as a WebGL `texImage2D` / `texSubImage2D` source on Windows and Linux only, not yet on iOS or Android.
+
 `drawImage` and `createPattern` also accept `@nativescript/core` `ImageSource` and `ImageAsset`, as well as a native `UIImage` or `android.graphics.Bitmap`.
 
 ## Exporting pixels
diff --git a/content/canvas/guides/offscreen-canvas.md b/content/canvas/guides/offscreen-canvas.md
new file mode 100644
index 0000000..eb753e8
--- /dev/null
+++ b/content/canvas/guides/offscreen-canvas.md
@@ -0,0 +1,155 @@
+---
+title: OffscreenCanvas and Workers
+description: Draw without a view using OffscreenCanvas, hand a view's drawing to it, and move it to a Worker so rendering runs on another JavaScript thread.
+---
+
+# OffscreenCanvas and Workers
+
+`OffscreenCanvas` is a canvas with no view. It supports the same contexts as `Canvas`: `2d`, `bitmaprenderer`, `webgl`, `webgl2` and `webgpu`. You can use it in three ways:
+
+- Draw off screen, then use the result as an image.
+- Take over a view's drawing with `transferControlToOffscreen()`.
+- Move it to a Worker, so a whole render loop runs on another JavaScript thread while its frames still show in the view.
+
+## Drawing off screen
+
+```ts
+import { OffscreenCanvas } from '@nativescript/canvas';
+
+const sprite = new OffscreenCanvas(64, 64);
+const ctx = sprite.getContext('2d');
+ctx.fillStyle = 'tomato';
+ctx.fillRect(0, 0, 64, 64);
+
+// Later, on a visible canvas:
+visible.getContext('2d').drawImage(sprite, 0, 0);
+```
+
+An OffscreenCanvas works as an image source in every place that takes a `Canvas`: `drawImage`, `createPattern`, `createImageBitmap`, `texImage2D`, `texSubImage2D` and `copyExternalImageToTexture`.
+
+To get a frame out of it:
+
+```ts
+const bitmap = sprite.transferToImageBitmap(); // hands the frame over and clears the canvas
+const blob = await sprite.convertToBlob({ type: 'image/png' });
+```
+
+`OffscreenCanvas` and `OffscreenCanvasRenderingContext2D` are exported from `@nativescript/canvas`, and importing the package also installs them as globals.
+
+## Taking over a view
+
+`canvas.transferControlToOffscreen()` returns an OffscreenCanvas that draws into the view's own surface, so its frames appear in the view:
+
+```ts
+const offscreen = canvas.transferControlToOffscreen();
+const ctx = offscreen.getContext('2d');
+```
+
+As on the web:
+
+- The view must not have a context yet. Otherwise, and if it was already transferred, `transferControlToOffscreen()` throws `InvalidStateError`.
+- Once transferred, the view's `getContext()` and its `width` and `height` setters throw. Resize through the OffscreenCanvas instead.
+- `contextlost` and `contextrestored` from the view are forwarded to the OffscreenCanvas.
+
+## Rendering in a Worker
+
+A Worker that owns an OffscreenCanvas draws into it on its own thread. If the canvas came from a view, the view keeps showing the Worker's frames. This keeps a heavy render loop, and the JavaScript that drives it, off the UI thread.
+
+Inside the Worker, import `@nativescript/canvas/worker` before anything else. It is the canvas API without the `Canvas` view, which a Worker cannot create.
+
+### Sending the canvas
+
+**On Android and iOS**, the runtime can't transfer an OffscreenCanvas through `postMessage` yet, so send a handle instead:
+
+```ts
+// Main thread
+import { OffscreenCanvas } from '@nativescript/canvas';
+
+const worker = new Worker('./render.worker.ts');
+const offscreen = canvas.transferControlToOffscreen();
+worker.postMessage({ canvas: OffscreenCanvas._toHandle(offscreen) });
+```
+
+```ts
+// render.worker.ts
+import { OffscreenCanvas } from '@nativescript/canvas/worker';
+
+self.onmessage = ({ data }) => {
+  const canvas = OffscreenCanvas._fromHandle(data.canvas);
+  const ctx = canvas.getContext('2d');
+
+  const draw = () => {
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    // ...
+    requestAnimationFrame(draw);
+  };
+  requestAnimationFrame(draw);
+};
+```
+
+**On Windows**, it moves with a transfer list, as on the web:
+
+```ts
+// Main thread
+const offscreen = canvas.transferControlToOffscreen();
+worker.postMessage({ canvas: offscreen }, [offscreen]);
+```
+
+```ts
+// render.worker.ts
+import '@nativescript/canvas/worker';
+
+self.onmessage = ({ data }) => {
+  const canvas: OffscreenCanvas = data.canvas;
+  const ctx = canvas.getContext('webgl2');
+  // ...
+};
+```
+
+To write one version for every platform, check whether the runtime can transfer, and send whichever form it supports:
+
+```ts
+// Main thread
+const offscreen = canvas.transferControlToOffscreen();
+const transferable = typeof (global as any).__nsRegisterTransferable === 'function';
+if (transferable) {
+  worker.postMessage({ canvas: offscreen }, [offscreen]);
+} else {
+  worker.postMessage({ handle: OffscreenCanvas._toHandle(offscreen) });
+}
+```
+
+```ts
+// render.worker.ts
+import { OffscreenCanvas } from '@nativescript/canvas/worker';
+
+self.onmessage = ({ data }) => {
+  const canvas = data.canvas ?? OffscreenCanvas._fromHandle(data.handle);
+  // ...
+};
+```
+
+When Android and iOS add transfer support, this code takes the web path there without any change.
+
+### Rules
+
+- Sending a canvas, with a transfer list or `_toHandle`, detaches the OffscreenCanvas on the sending side. It must not have a context yet.
+- A handle can be received only once. If nothing will receive a handle, release it with `OffscreenCanvas._releaseHandle(handle)`.
+- All five context types work in a Worker.
+- A Worker can create its own canvas with `new OffscreenCanvas(width, height)`, and can transfer it back to the main thread.
+- Resizing the canvas in the Worker resizes the view on the UI thread a moment later.
+- `requestAnimationFrame` in a Worker is paced by that Worker's own canvases. A canvas that falls behind holds back only the Worker that owns it.
+- Terminating the Worker, or disposing of the view while the Worker is still drawing, is safe.
+
+## Do I need a Worker?
+
+Usually not. 2D and WebGL contexts already rasterize and present on their own threads by default (see [Performance](/canvas/performance#threaded-rendering)). That moves the GPU work off the UI thread, but your drawing code still runs there.
+
+Move rendering to a Worker when the JavaScript itself is the bottleneck: physics, scene updates, or thousands of draw calls per frame.
+
+## Related docs
+
+- [Rendering Contexts](/canvas/rendering-contexts)
+- [Images and ImageBitmap](/canvas/guides/images-and-bitmaps)
+- [Performance](/canvas/performance)
+- [Web API Compatibility](/canvas/compatibility)
diff --git a/content/canvas/guides/webgpu-recipes.md b/content/canvas/guides/webgpu-recipes.md
index f2065c1..989ce04 100644
--- a/content/canvas/guides/webgpu-recipes.md
+++ b/content/canvas/guides/webgpu-recipes.md
@@ -283,6 +283,7 @@ fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
 ```
 
 - **iOS, tvOS, visionOS (Metal):** the frame is imported on the GPU.
+- **Windows and Linux:** the decoder shares its frames with WebGPU on the GPU.
 - **Android:** this works only on API 29+, and only when the video decoder outputs RGB buffers. Most hardware decoders output YCbCr, and on those devices video frames cannot reach a WebGPU texture yet. On Android, use WebGL `texImage2D` or 2D `drawImage` for video.
 - Keep a single long-lived texture. If no new frame has been decoded since the last copy, the copy is skipped and the texture keeps the previous frame.
 - To sample the video directly in a shader, without a copy, use [`importExternalTexture`](#_11-sampling-video-with-importexternaltexture).
@@ -329,7 +330,7 @@ fn main(@location(0) uv: vec2f) -> @location(0) vec4f {
 
 - Import every frame, as on the web. If the decoder has no new frame yet, you get the previous one back.
 - `source` must be a video element, either from `document.createElement('video')` or a canvas-media `Video`. `VideoFrame` sources are not supported.
-- Supported on iOS, tvOS and visionOS. On Android it throws `NotSupportedError`; use [recipe 10](#_10-video-frames-as-a-texture) or WebGL there instead.
+- Supported on iOS, tvOS, visionOS, Windows and Linux. On Android it has the same limits as [recipe 10](#_10-video-frames-as-a-texture): API 29+, and a decoder that outputs RGB buffers. Where frames can't be imported, it throws `NotSupportedError`; use WebGL there instead.
 - Once `await video.play()` resolves, a frame is available, as on the web. Calling it before `play()` has resolved, or before the video has loaded, throws `InvalidStateError`.
 
 ## More guides
diff --git a/content/canvas/installation.md b/content/canvas/installation.md
index c01bfd1..986782a 100644
--- a/content/canvas/installation.md
+++ b/content/canvas/installation.md
@@ -19,8 +19,12 @@ npm install @nativescript/canvas
 
 `@nativescript/canvas` 3.x requires **NativeScript 9.1 or later** (`@nativescript/core`, `@nativescript/ios` and `@nativescript/android`). 3.x is built directly against the V8 engine in those runtimes, so older runtimes cannot load it. If you are on an older version, see [Upgrading to 3.0](/canvas/upgrading).
 
+Windows and Linux use the NativeScript runtime for that platform instead. See [Platform support](#platform-support).
+
 On iOS, tvOS and visionOS the native code is delivered through Swift Package Manager, and the plugin's own `nativescript.config.ts` sets this up. You don't need a Podfile, and your app doesn't need any extra configuration.
 
+On Windows and Linux the native code is a Node-API module (`canvasnative.node`) that ships inside the package, for x64 and arm64. There is nothing to configure here either.
+
 ## Platform support
 
 | Platform | Minimum | Notes |
@@ -29,15 +33,17 @@ On iOS, tvOS and visionOS the native code is delivered through Swift Package Man
 | tvOS | 13.0 | New in 3.0 |
 | visionOS | 1.0 | Metal only. `webgl` and `webgl2` are not available. |
 | Android | API 21 | The Vulkan 2D backend needs API 24. |
+| Windows | x64, arm64 | New in 3.0. Runs on the NativeScript Windows runtime (`@nativescript/windows`). |
+| Linux | GTK 4.6, x64, arm64 | New in 3.0. Runs on the NativeScript Linux runtime (`@nativescript/linux`). |
 
 ### Context support per platform
 
-| Context | iOS / tvOS | visionOS | Android |
-| --- | --- | --- | --- |
-| `2d` | Metal (GL with `Canvas.forceGL`) | Metal | Vulkan, or GL when Vulkan is unavailable |
-| `webgl`, `webgl2` | Yes | No | Yes |
-| `webgpu` | Yes (Metal) | Yes (Metal) | Yes (Vulkan, API 27+) |
-| `bitmaprenderer` | Yes | Yes | Yes |
+| Context | iOS / tvOS | visionOS | Android | Windows | Linux |
+| --- | --- | --- | --- | --- | --- |
+| `2d` | Metal (GL with `Canvas.forceGL`) | Metal | Vulkan, or GL when Vulkan is unavailable | Direct3D 12, or CPU if that fails | GL (EGL) |
+| `webgl`, `webgl2` | Yes | No | Yes | Yes (ANGLE) | Yes (EGL) |
+| `webgpu` | Yes (Metal) | Yes (Metal) | Yes (Vulkan, API 27+) | Yes (Direct3D 12) | Yes (Vulkan) |
+| `bitmaprenderer` | Yes | Yes | Yes | Yes | Yes |
 
 ## Core (XML)
 
diff --git a/content/canvas/performance.md b/content/canvas/performance.md
index 8dd146f..99678ac 100644
--- a/content/canvas/performance.md
+++ b/content/canvas/performance.md
@@ -9,6 +9,42 @@ description: What canvas operations cost on a real device, and the practices tha
 
 All numbers below were measured on a Galaxy A53, a mid-range Android phone.
 
+## Threaded rendering
+
+On Android, iOS and Windows, 2D and WebGL contexts do their GPU work on a separate thread by default. Your drawing code still runs on the JavaScript thread, and still looks synchronous:
+
+- **2D:** each call is recorded on the JavaScript thread. Once per frame the recording is handed to a shared render thread, which draws it with Skia on the GPU and presents it.
+- **WebGL:** calls are queued to a shared WebGL thread, which runs them and presents.
+
+Without threading, the GPU work of a busy 2D scene ran on the UI thread. In a test scene that drew 300 rotated rectangles with text, Skia's flush took about 6.3 ms of every frame on the UI thread. With threading, the hand-off takes about 0.19 ms. That scene went from 102 fps, with 77% of UI frames janky, to a steady 120 fps. The UI stays smooth even when the render thread can't keep up: frames are merged instead of blocking the UI thread.
+
+A few calls must wait for the thread to catch up, because they need its result:
+
+- 2D: `getImageData`, `toDataURL`, and using the canvas as an image source (`drawImage(canvas)`, `texImage2D(canvas)`, WebGPU copies).
+- WebGL: anything that returns a value, such as `getError`, `getParameter`, `getUniformLocation`, `checkFramebufferStatus` or `readPixels`. Each costs a round trip to the WebGL thread, so don't call `getError` after every draw in production code. `getParameter` for the current bindings is answered without a round trip.
+
+While any canvas has a frame that hasn't reached the screen yet, `requestAnimationFrame` holds back its callbacks by a frame, as a browser does when its compositor falls behind. This stops a slow scene from piling up frames.
+
+### Turning it off
+
+For one canvas, pass `threaded: false`:
+
+```ts
+const ctx = canvas.getContext('2d', { threaded: false });
+const gl = canvas.getContext('webgl2', { threaded: false });
+```
+
+For every canvas, set the static defaults before you create any context:
+
+```ts
+import { Canvas } from '@nativescript/canvas';
+
+Canvas.threaded2D = false;
+Canvas.threadedWebGL = false;
+```
+
+Linux doesn't use threaded rendering yet. If your drawing code itself is the bottleneck, move it off the UI thread with an [OffscreenCanvas in a Worker](/canvas/guides/offscreen-canvas#rendering-in-a-worker).
+
 ## What things cost
 
 | Operation | Approx. cost |
@@ -20,10 +56,12 @@ All numbers below were measured on a Galaxy A53, a mid-range Android phone.
 | `fillText` (repeated string) | ~1.1 µs |
 | `drawImage` | ~1.6 µs |
 | WebGL `drawArrays` / `drawElements` | ~0.8 µs |
-| WebGL `activeTexture`, `blendFunc`, `getError` | ~20 ns |
+| WebGL `activeTexture`, `blendFunc` | ~20 ns |
 | `getImageData` (64x64, GPU canvas) | ~412 µs |
 | WebGL `readPixels` (64x64) | ~188 µs |
 
+These are JavaScript-side costs, measured before threaded rendering became the default. With threading, WebGL calls that return a value add a round trip to the WebGL thread (see above).
+
 For comparison, the device's own WebView pays about the same for `measureText` and draws the same heavy particle scene at the same frame time. The remaining cost is the drawing itself, not the binding.
 
 ## Reading pixels back
@@ -56,6 +94,12 @@ The bottleneck in a slow scene is usually rasterization, not the number of calls
 - Cap particle counts. An array that grows on every touch event is the most common cause of a demo that "gets slower over time".
 - Don't redraw from touch handlers when a `requestAnimationFrame` loop is already running. Update state in the handler, and draw in the loop.
 
+## Memory
+
+- **Images stay encoded.** An `ImageAsset` loaded from a file, URL or encoded bytes keeps the compressed bytes, not the decoded pixels. 2D decodes it when uploading it to the GPU, and WebGL, WebGPU and `ImageBitmap` decode it for the call. Assets made from raw pixels keep their pixels.
+- **The garbage collector sees image memory.** On Android and Apple platforms, `ImageAsset` and `ImageBitmap` report their native size to V8, so images you drop are collected promptly. You don't need to force a GC. Drop your references, or call `bitmap.close()` to free a bitmap right away.
+- **GPU memory is trimmed.** A 2D canvas frees GPU resources it hasn't used for 5 seconds, such as a sprite sheet it no longer draws. Anything drawn every frame stays cached, so steady rendering pays nothing.
+
 ## Size canvases in device pixels
 
 For sharp output, set the backing size to the view size multiplied by the screen scale, then scale the context:
diff --git a/content/canvas/rendering-contexts.md b/content/canvas/rendering-contexts.md
index de1abd4..3f2831a 100644
--- a/content/canvas/rendering-contexts.md
+++ b/content/canvas/rendering-contexts.md
@@ -55,6 +55,7 @@ const gl = canvas.getContext('webgl2', { antialias: false, preserveDrawingBuffer
 | `failIfMajorPerformanceCaveat` | `false` | WebGL |
 | `desynchronized` | `false` | 2D, WebGL |
 | `willReadFrequently` | `false` | 2D. See [Performance](/canvas/performance#reading-pixels-back). |
+| `threaded` | `true` (Android, iOS, Windows) | 2D, WebGL. A NativeScript extra. See [Threaded rendering](/canvas/performance#threaded-rendering). |
 
 ## 2D backends
 
@@ -64,9 +65,15 @@ The 2D context is drawn by Skia on the GPU:
 | --- | --- | --- |
 | iOS, tvOS, visionOS | Metal | GL, if you set `Canvas.forceGL = true` before `getContext` (not on visionOS) |
 | Android | Vulkan (API 24+ with a supported driver) | GL |
+| Windows | Direct3D 12 | CPU |
+| Linux | GL (EGL) | |
 
 `willReadFrequently: true` switches that canvas to a CPU raster surface instead.
 
+## Canvases without a view
+
+`OffscreenCanvas` supports every context type above, and can move to a Worker. See [OffscreenCanvas and Workers](/canvas/guides/offscreen-canvas).
+
 ## bitmaprenderer
 
 `bitmaprenderer` presents an `ImageBitmap` without copying it. `transferFromImageBitmap` resizes the canvas to fit the bitmap and detaches the bitmap. Passing `null` clears the canvas.
@@ -97,3 +104,4 @@ The package follows web API behavior where possible:
 - [WebGL Recipes](/canvas/guides/webgl-recipes)
 - [WebGPU Recipes](/canvas/guides/webgpu-recipes)
 - [Images and ImageBitmap](/canvas/guides/images-and-bitmaps)
+- [OffscreenCanvas and Workers](/canvas/guides/offscreen-canvas)
diff --git a/content/canvas/upgrading.md b/content/canvas/upgrading.md
index 19e6e22..f142c48 100644
--- a/content/canvas/upgrading.md
+++ b/content/canvas/upgrading.md
@@ -31,16 +31,26 @@ npm install -D @nativescript/ios@~9.1 @nativescript/android@~9.1
 ## New in 3.0
 
 - [tvOS support](/canvas/installation#platform-support), with Siri Remote presses delivered as [keyboard events](/canvas/events#keyboard-and-tvos-remote).
+- [Windows and Linux support](/canvas/installation#platform-support).
+- [Threaded rendering](/canvas/performance#threaded-rendering): 2D and WebGL do their GPU work off the UI thread by default on Android, iOS and Windows.
+- [`OffscreenCanvas`](/canvas/guides/offscreen-canvas), including rendering in a Worker.
+- [`ImageAsset.toImageSource()` and `toNativeImage()`](/canvas/guides/images-and-bitmaps#showing-an-asset-in-an-image), to show an asset in an `<Image>`.
 - The [`bitmaprenderer` context](/canvas/rendering-contexts#bitmaprenderer), and [`createImageBitmap`](/canvas/guides/images-and-bitmaps#createimagebitmap) from any image, canvas, blob or SVG source.
 - Zero-copy [video frames in WebGPU](/canvas/guides/webgpu-recipes#_10-video-frames-as-a-texture) on iOS, tvOS and visionOS.
 - [`@nativescript/canvas-svg`](/canvas-svg/), rewritten: a live DOM, SMIL and CSS animation, and GPU rendering.
 - `ctx.reset()` and `ctx.getContextAttributes()` on the 2D context. `setTransform()` with no arguments resets the transform.
 - Large reductions in per-call cost for 2D text, fonts, `save`/`restore` and WebGL. See [Performance](/canvas/performance).
+- Lower image memory: encoded images stay encoded, V8 sees the native size of images, and unused GPU resources are freed. See [Memory](/canvas/performance#memory).
 
 ## Behaviour changes
 
 Most of these are spec fixes: the canvas now behaves like a browser where it previously did not. Check your app for each one.
 
+### Threading
+
+- **2D and WebGL run their GPU work on another thread by default** on Android, iOS and Windows. Your code doesn't change, but calls that need a result wait for that thread: 2D readbacks (`getImageData`, `toDataURL`, using the canvas as an image) and WebGL calls that return a value (`getError`, `getParameter`, `readPixels` and so on). Remove `getError` checks from hot paths. To go back to the 2.x behaviour, pass `threaded: false` to `getContext`, or set `Canvas.threaded2D` / `Canvas.threadedWebGL` to `false`. See [Threaded rendering](/canvas/performance#threaded-rendering).
+- **`requestAnimationFrame` waits for slow canvases.** While a canvas has a frame that hasn't reached the screen, callbacks are held back by a frame, as in a browser. A scene that can't keep up now runs at a lower, steady frame rate instead of queueing frames.
+
 ### Canvas 2D
 
 - **Invalid arguments now throw, as they do in browsers.** A negative radius in `arc`, `ellipse` or `createRadialGradient`, an `addColorStop` offset outside 0 to 1 or with an unparseable colour, and a zero-sized `getImageData` or `createImageData` all throw `IndexSizeError` or `SyntaxError`.
@@ -54,21 +64,30 @@ Most of these are spec fixes: the canvas now behaves like a browser where it pre
 - `createPattern(img, null)` and `createPattern(img, '')` mean `'repeat'`.
 - `measureText('')` returns a `TextMetrics` object instead of `undefined`.
 - On iOS, `getContext('2d')` returns `null` once the canvas already has a WebGPU context. Android already behaved this way.
+- On Android, a canvas you never clear keeps what it drew in earlier frames, as on the web. In 2.x it showed only the latest frame.
+- `putImageData` with a dirty rectangle reads the right rows, and `ctx.reset()` also drops clips and the save stack.
 
 ### WebGL
 
 - `clear()` respects the scissor rectangle.
 - `getFragDataLocation` returns `-1` rather than `null` for an unknown name. Update any `=== null` checks.
 - `getParameter` returns values for WebGL2-only parameters, where it used to return an object.
+- `getParameter(FRAMEBUFFER_BINDING)` (and `READ_FRAMEBUFFER_BINDING`, `PIXEL_PACK_BUFFER_BINDING`) returns the object you bound, or `null`. Saving and restoring a binding now works.
+- `deleteProgram` deletes the program. In 2.x it deleted a framebuffer with the same number, which could leave the canvas drawing into nothing.
+- `bindVertexArrayOES(null)` unbinds, `bindTransformFeedback` binds, and `clearBuffer*` takes the buffer enum.
+- iOS WebGL no longer uses a `GLKView`. If your native code reaches into the view, `CanvasGLKView` is now `CanvasGLView` and `NSCCanvas.getGlViewPtr()` is now `getGlLayerPtr()`. Depth and stencil are discarded after each frame unless `preserveDrawingBuffer` is set, as before.
 
 ### WebGPU
 
 - Missing depth and stencil load/store ops are no longer filled in. Give the ops for each aspect your format has: depth-only formats such as `depth24plus` take only `depthLoadOp` and `depthStoreOp`. This fixes the blank canvas that 2.x showed for depth-only formats. See [recipe 9](/canvas/guides/webgpu-recipes#_9-depth-attachments).
 - `setIndexBuffer` treats any format other than `'uint16'` as `'uint32'`.
+- The `subgroups` feature is no longer advertised, because the shader compiler can't enable it yet.
 
 ### Images
 
-- `createImageBitmap` rejects sources it does not recognise, instead of never resolving.
+- `createImageBitmap` rejects sources it does not recognise, and bytes it can't decode, instead of never resolving or resolving with an empty bitmap.
+- With the polyfill, an `<img>` whose bytes are not an image fires `error` instead of `load`.
+- Semi-transparent images drawn scaled in 2D are now filtered premultiplied, which removes a dark halo at their edges. Images with an embedded colour profile are colour-managed when drawn in 2D. Pixel data read back (`getImageData`, WebGL and WebGPU uploads) is unchanged.
 - `ImageBitmap.close()` detaches the bitmap, so its `width` and `height` become `0`.
 - `resizeHeight` is honoured. In 2.x it was overwritten with `resizeWidth`.
 - An `ImageAsset` is no longer kept alive forever once it has loaded. Hold a reference for as long as you need it.
@@ -88,3 +107,4 @@ Most of these are spec fixes: the canvas now behaves like a browser where it pre
 - `initialSVG` and the XMLSerializer-based internals have been removed.
 - A document without a `viewBox` no longer gets `viewBox="0 0 100 100"` invented for it. Percentage sizes resolve against the view, and a document larger than its view is scaled down to fit.
 - Views with the same `src` now share one document and one animation clock. Set `shareSrc="false"` on any view that needs its own copy.
+- CSS animations can be started by any selector, not only `#id`. CSS kept outside the SVG goes in the new [`stylesheet`](/canvas-svg/guides/styling) property.
diff --git a/content/plugins/canvas-gamepad.md b/content/plugins/canvas-gamepad.md
index a2addfc..d4112e0 100644
--- a/content/plugins/canvas-gamepad.md
+++ b/content/plugins/canvas-gamepad.md
@@ -1,6 +1,6 @@
 ---
 title: '@nativescript/canvas-gamepad'
-description: The web Gamepad API (navigator.getGamepads, gamepadconnected and gamepaddisconnected) for game controllers on iOS, Android and Windows.
+description: The web Gamepad API (navigator.getGamepads, gamepadconnected and gamepaddisconnected) for game controllers on iOS, Android, Windows and Linux.
 ---
 
 # @nativescript/canvas-gamepad
@@ -239,6 +239,7 @@ export function onUnloaded() {
 | iOS, tvOS, visionOS | GameController (`GCExtendedGamepad`) | The package sets `valueChangedHandler` on each controller, replacing any handler your own code set. |
 | Android | Gamepad and joystick `KeyEvent` / `MotionEvent` | Input from connected controllers is consumed at the activity window, so B no longer triggers Back while the API is in use. |
 | Windows | `Windows.Gaming.Input.Gamepad` | 16 buttons: there is no Guide button. |
+| Linux | evdev, through [gilrs](https://gitlab.com/gilrs-project/gilrs) and SDL's controller database | The app needs read access to `/dev/input/event*`. Desktop sessions normally grant it for gamepads; otherwise add the user to the `input` group or add a udev rule. |
 
 On tvOS the Siri Remote is not a gamepad. It keeps sending `keydown` and `keyup` events, as described in [Events and Input](/canvas/events#keyboard-and-tvos-remote).
 
diff --git a/content/plugins/canvas-media.md b/content/plugins/canvas-media.md
index aa94490..3d2edb2 100644
--- a/content/plugins/canvas-media.md
+++ b/content/plugins/canvas-media.md
@@ -11,6 +11,8 @@ Native `Video` and `Audio` elements with a web-like API. A video can also act as
 npm install @nativescript/canvas-media
 ```
 
+It plays through AVFoundation on Apple platforms, Media3 (ExoPlayer) on Android, Windows Media on Windows, and GStreamer on Linux. On Linux, video is decoded into GL textures where the system supports it, and falls back to CPU memory otherwise. Set `NS_CANVAS_MEDIA_CPU=1` to force the fallback.
+
 ## Video in a layout
 
 ```xml
@@ -57,7 +59,7 @@ await video.play();
 | 2D | `ctx.drawImage(video, 0, 0, w, h)` |
 | WebGL | `gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, video)` |
 | WebGL2 | `texImage2D` and `texImage3D` |
-| WebGPU | `device.queue.copyExternalImageToTexture({ source: video }, { texture }, [w, h])`. This is zero-copy on Apple platforms; Android support is limited. See the [WebGPU video recipe](/canvas/guides/webgpu-recipes#_10-video-frames-as-a-texture). |
+| WebGPU | `device.queue.copyExternalImageToTexture({ source: video }, { texture }, [w, h])`. This stays on the GPU on Apple platforms, Windows and Linux; Android support is limited. See the [WebGPU video recipe](/canvas/guides/webgpu-recipes#_10-video-frames-as-a-texture). |
 
 WebGL `texImage2D` and WebGPU also accept a `Video` view directly.
 
diff --git a/content/plugins/canvas-polyfill.md b/content/plugins/canvas-polyfill.md
index 70ead64..8cd4311 100644
--- a/content/plugins/canvas-polyfill.md
+++ b/content/plugins/canvas-polyfill.md
@@ -28,13 +28,13 @@ The [framework adapters](/plugins/adapters) (Three.js, Pixi, Phaser, Babylon) im
 | Timers | `setTimeout`, `setInterval` and `requestAnimationFrame`, with their cancel functions, on `window` |
 | Document | `document`, `document.fonts`, `document.createElement` (`canvas`, `img`, `video`, `audio`, `div`), `document.createElementNS` for SVG, `DOMParser`, `MutationObserver` |
 | Elements | `HTMLCanvasElement`, `HTMLImageElement`/`Image`, `HTMLVideoElement`, `HTMLAudioElement`, and the `SVG*` element classes |
-| Graphics | `navigator.gpu`, `createImageBitmap`, `ImageBitmap`, `ImageData`, `DOMPoint` |
+| Graphics | `navigator.gpu`, `createImageBitmap`, `ImageBitmap`, `ImageData`, `OffscreenCanvas`, `DOMPoint` |
 | Data | `XMLHttpRequest` (supports `file://`, `~/`, `blob:` and `data:` URLs), `Blob`, `FileReader`, `URL.createObjectURL`, `TextEncoder`, `TextDecoder`, `AbortController` |
 | Media | `VideoFrame`, `VideoColorSpace` |
 | Audio | If [`@nativescript/audio-context`](/audio-context/) is installed: `AudioContext`, `OfflineAudioContext` and every node type |
 | Gamepad | If [`@nativescript/canvas-gamepad`](/plugins/canvas-gamepad) is installed: `navigator.getGamepads()` and the `gamepadconnected` / `gamepaddisconnected` window events |
 
-`fetch` is not polyfilled here. It comes from `@nativescript/core`.
+`fetch` is not polyfilled here. It comes from `@nativescript/core`. On Linux, the polyfill adds support for local files (`~/`, `file://` and absolute paths) to it.
 
 ## Images