@solidtv/renderer 1.5.3 → 1.5.5

package/src/core/CoreNode.ts

@@ -829,6 +829,14 @@ export class CoreNode extends EventEmitter {
   private hasColorProps = false;
   public textureLoaded = false;
 
+  /**
+   * Last ownership value sent to the current texture via
+   * {@link updateTextureOwnership}. Per (node, texture) pair — must reset to
+   * `false` whenever the texture is swapped or released, or a stale `true`
+   * would skip the re-registration that triggers `Texture.load()`.
+   */
+  private textureOwnership = false;
+
   /**
    * True while this node should render its `placeholderColor` instead of its
    * texture: `placeholderColor` is non-zero, a texture is set, and that
@@ -1085,6 +1093,7 @@ export class CoreNode extends EventEmitter {
     texture.off('failed', this.onTextureFailed);
     texture.off('freed', this.onTextureFreed);
     texture.setRenderableOwner(this._id, false);
+    this.textureOwnership = false;
   }
 
   protected onTextureLoaded: TextureLoadedEventHandler = (_, dimensions) => {
@@ -1918,6 +1927,10 @@ export class CoreNode extends EventEmitter {
    * Changes the renderable state of the node.
    */
   updateTextureOwnership(isRenderable: boolean) {
+    if (this.textureOwnership === isRenderable) {
+      return;
+    }
+    this.textureOwnership = isRenderable;
     this.texture?.setRenderableOwner(this._id, isRenderable);
   }
 
@@ -3100,6 +3113,7 @@ export class CoreNode extends EventEmitter {
         this.autosizer.setMode(AutosizeMode.Texture); // Set to texture size mode
       }
       value.setRenderableOwner(this._id, this.isRenderable);
+      this.textureOwnership = this.isRenderable;
       this.loadTexture();
     }
 

package/src/core/CoreShaderManager.contextLoss.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Tests for CoreShaderManager's behavior when shader creation fails.
+ *
+ * A lost GL context makes shader creation throw synchronously (see
+ * WebGlRenderer.createShaderProgram, which trips `stage.isContextLost`). On a
+ * lost context we must fail soft — returning the default shader node so the
+ * throw does not propagate through the consumer's reactive layer (recovery is
+ * an app reload via the `contextLost` event). A genuine compile error (context
+ * not lost) must still surface loudly.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { CoreShaderManager } from './CoreShaderManager.js';
+import type { Stage } from './Stage.js';
+
+function makeManager(opts: { isContextLost: boolean; throwOnCreate: Error }) {
+  const defShaderNode = { __default: true };
+  const createShaderProgram = vi.fn(() => {
+    throw opts.throwOnCreate;
+  });
+  const stage = {
+    isContextLost: opts.isContextLost,
+    defShaderNode,
+    renderer: {
+      mode: 'webgl',
+      createShaderProgram,
+    },
+  } as unknown as Stage;
+
+  const mgr = Object.create(CoreShaderManager.prototype) as CoreShaderManager;
+  (mgr as unknown as { stage: Stage }).stage = stage;
+  (mgr as unknown as { shTypes: Record<string, unknown> }).shTypes = {
+    TestShader: { props: undefined },
+  };
+  (mgr as unknown as { shCache: Map<string, unknown> }).shCache = new Map();
+
+  return { mgr, defShaderNode, createShaderProgram };
+}
+
+describe('CoreShaderManager.createShader — context loss', () => {
+  it('returns the default shader node when the context is lost', () => {
+    const { mgr, defShaderNode } = makeManager({
+      isContextLost: true,
+      throwOnCreate: new Error(
+        'Unable to create the shader: VERTEX_SHADER. WebGlContext Error: 37442',
+      ),
+    });
+
+    const result = mgr.createShader('TestShader' as never);
+
+    expect(result).toBe(defShaderNode);
+  });
+
+  it('rethrows when the failure is not a lost context (genuine compile error)', () => {
+    const err = new Error('Vertex shader creation failed');
+    const { mgr } = makeManager({ isContextLost: false, throwOnCreate: err });
+
+    expect(() => mgr.createShader('TestShader' as never)).toThrow(err);
+  });
+
+  it('does not cache a failed program', () => {
+    const { mgr, createShaderProgram } = makeManager({
+      isContextLost: true,
+      throwOnCreate: new Error('boom'),
+    });
+
+    mgr.createShader('TestShader' as never);
+    mgr.createShader('TestShader' as never);
+
+    // Cache miss both times — the failure was never stored.
+    expect(createShaderProgram).toHaveBeenCalledTimes(2);
+  });
+});

package/src/core/CoreShaderManager.ts

@@ -103,8 +103,21 @@ export class CoreShaderManager {
      * if shaderProgram was not found create a new one
      */
     if (shProgram === undefined) {
-      shProgram = this.stage.renderer.createShaderProgram(shType, props)!;
-      this.shCache.set(shaderKey, shProgram);
+      try {
+        shProgram = this.stage.renderer.createShaderProgram(shType, props)!;
+        this.shCache.set(shaderKey, shProgram);
+      } catch (e) {
+        // The renderer trips `isContextLost` when shader creation fails due to
+        // a lost GL context. That is unrecoverable in-place (the consumer
+        // reloads on the `contextLost` event), so fall back to the default
+        // shader node instead of letting the throw propagate through the app's
+        // reactive layer. A genuine GLSL compile error (context not lost) is a
+        // real bug and is rethrown so it surfaces loudly.
+        if (this.stage.isContextLost === true) {
+          return this.stage.defShaderNode;
+        }
+        throw e;
+      }
     }
 
     return this.stage.renderer.createShaderNode(

package/src/core/CoreTextNode.ts

@@ -266,8 +266,9 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
         this.setRenderable(false);
 
         if (this.renderState > CoreNodeRenderState.OutOfBounds) {
-          // We do want the texture to load immediately
-          this.texture.setRenderableOwner(this._id, true);
+          // We do want the texture to load immediately. Routed through
+          // updateTextureOwnership so the ownership cache stays in sync.
+          this.updateTextureOwnership(true);
         }
       }
     }

package/src/core/CoreTextureManager.ts

@@ -409,9 +409,9 @@ export class CoreTextureManager extends EventEmitter {
 
     // Anything that arrived before initialization completed is now safe to
     // process. Without this, queued textures would sit until the next frame
-    // tick happens to call processSome().
+    // tick happens to drain them.
     if (this.uploadTextureQueue.size > 0) {
-      this.processSome(Infinity).catch((err) => {
+      this.processUntil(Infinity).catch((err) => {
         console.error('Failed to drain pre-init texture queue:', err);
       });
     }
@@ -587,11 +587,41 @@ export class CoreTextureManager extends EventEmitter {
   }
 
   /**
-   * Process a limited number of uploads.
+   * Upload a single queued texture to the GPU.
    *
-   * @param maxProcessingTime - The maximum processing time in milliseconds
+   * @remarks
+   * Used while animations are running so uploads don't steal time from the
+   * animation. If the dequeued texture already died (failed/freed), nothing is
+   * uploaded this frame and the next call handles the following one.
+   */
+  async processOne(): Promise<void> {
+    if (this.initialized === false) {
+      return;
+    }
+
+    const texture = this.uploadTextureQueue.shift();
+    if (texture === undefined) {
+      return;
+    }
+
+    await this.uploadQueued(texture);
+  }
+
+  /**
+   * Upload queued textures to the GPU until the per-frame time budget runs out.
+   *
+   * @remarks
+   * Called once per frame when idle. Textures are uploaded one-by-one; after
+   * each, the elapsed time is rechecked and processing stops once it exceeds
+   * `maxProcessingTime`, leaving the rest queued for the next frame.
+   *
+   * In normal operation a queued texture's data is already decoded
+   * (`loadTexture` awaits `getTextureData` before enqueuing), so this budgets
+   * GPU upload time. Pass `Infinity` to drain the whole queue.
+   *
+   * @param maxProcessingTime - The time budget for this frame, in milliseconds
    */
-  async processSome(maxProcessingTime: number): Promise<void> {
+  async processUntil(maxProcessingTime: number): Promise<void> {
     if (this.initialized === false) {
       return;
     }
@@ -599,79 +629,54 @@ export class CoreTextureManager extends EventEmitter {
     const platform = this.platform;
     const startTime = platform.getTimeStamp();
 
-    // Decode / fetch ("getTextureData") is IO-bound and parallelisable across
-    // image workers, while GPU upload is effectively serial. Keep a small
-    // sliding window of in-flight data fetches so the next decode runs while
-    // we're uploading the current one.
-    const prefetchLimit = Math.max(1, this.numImageWorkers);
-    const pending: Array<{ texture: Texture; data: Promise<unknown> }> = [];
-
-    // Helper avoids TS narrowing `texture.state` permanently after the first
-    // discriminated check — the property is mutable and can transition across
-    // awaits, so we need to re-read it freshly each time.
-    const isDead = (texture: Texture): boolean =>
-      texture.state === 'failed' || texture.state === 'freed';
-
-    const fillPrefetch = () => {
-      while (pending.length < prefetchLimit) {
-        const texture = this.uploadTextureQueue.shift();
-        if (texture === undefined) break;
-
-        if (isDead(texture)) {
-          continue;
-        }
-
-        // Swallow the rejection here so an early failure doesn't surface as
-        // an unhandled promise rejection while it sits in the prefetch
-        // window; we re-check state after awaiting.
-        const data =
-          texture.textureData === null
-            ? texture.getTextureData().catch((err) => {
-                console.error('Failed to fetch texture data:', err);
-                return null;
-              })
-            : Promise.resolve(texture.textureData);
-
-        pending.push({ texture, data });
+    while (platform.getTimeStamp() - startTime < maxProcessingTime) {
+      const texture = this.uploadTextureQueue.shift();
+      if (texture === undefined) {
+        // Queue drained.
+        break;
       }
-    };
 
-    fillPrefetch();
+      await this.uploadQueued(texture);
+    }
+  }
 
-    while (
-      pending.length > 0 &&
-      platform.getTimeStamp() - startTime < maxProcessingTime
-    ) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const next = pending.shift()!;
-      // Top up the prefetch window before awaiting — the next decode starts
-      // now and overlaps with this upload.
-      fillPrefetch();
+  /**
+   * Decode (if needed) and upload a single already-dequeued texture.
+   *
+   * @remarks
+   * Shared by {@link processOne} and {@link processUntil}. Dead (failed/freed)
+   * textures and upload failures are skipped without throwing.
+   */
+  private async uploadQueued(texture: Texture): Promise<void> {
+    if (this.isTextureDead(texture)) {
+      return;
+    }
 
-      if (isDead(next.texture)) {
-        continue;
+    try {
+      if (texture.textureData === null) {
+        await texture.getTextureData();
       }
-
-      try {
-        await next.data;
-        if (isDead(next.texture)) {
-          continue;
-        }
-        await this.uploadTexture(next.texture);
-      } catch (error) {
-        console.error('Failed to upload texture:', error);
-        // Continue with next texture instead of stopping entire queue
+      if (this.isTextureDead(texture)) {
+        return;
       }
+      await this.uploadTexture(texture);
+    } catch (error) {
+      console.error('Failed to upload texture:', error);
+      // Skip this texture instead of stalling the queue.
     }
+  }
 
-    // Time ran out before we got to these. Put them back so we don't lose
-    // them — their getTextureData() is already in flight and will populate
-    // `textureData` for the next tick.
-    for (const { texture } of pending) {
-      if (!isDead(texture)) {
-        this.uploadTextureQueue.add(texture);
-      }
-    }
+  /**
+   * A texture is "dead" once it has failed or been freed — both terminal for
+   * the upload pipeline.
+   *
+   * @remarks
+   * Kept as a method rather than an inline check so TypeScript doesn't
+   * permanently narrow `state` after the first comparison: the property is
+   * mutable and can transition across the awaits in {@link uploadQueued}.
+   */
+  private isTextureDead(texture: Texture): boolean {
+    return texture.state === 'failed' || texture.state === 'freed';
   }
 
   public hasUpdates(): boolean {

package/src/core/Stage.ts

@@ -595,11 +595,16 @@ export class Stage {
     // Process some textures asynchronously but don't block the frame
     // Use a background task to prevent frame drops
     if (this.txManager.hasUpdates() === true) {
-      const timeLimit = hasActiveAnimations
-        ? this.options.textureProcessingTimeLimit / 2
-        : this.options.textureProcessingTimeLimit;
+      // While animating, upload at most one texture per frame so uploads don't
+      // steal time from the animation; otherwise fill the per-frame time budget.
+      const processing =
+        hasActiveAnimations === true
+          ? this.txManager.processOne()
+          : this.txManager.processUntil(
+              this.options.textureProcessingTimeLimit,
+            );
 
-      this.txManager.processSome(timeLimit).catch((err) => {
+      processing.catch((err) => {
         console.error('Error processing textures:', err);
       });
     }

package/src/core/TextureMemoryManager.test.ts

@@ -175,7 +175,7 @@ function freedCachedTexture(cacheKey: string): Texture & {
     state: 'freed',
     type: TextureType.image,
     preventCleanup: false,
-    renderableOwners: [],
+    renderableOwners: new Set<string | number>(),
     cacheKey,
     free: vi.fn(),
     destroy: vi.fn(),
@@ -206,7 +206,7 @@ describe('TextureMemoryManager — orphaned freed texture eviction', () => {
   it('keeps a freed texture that still has renderable owners', () => {
     const { mgr, keyCache } = makeManager();
     const texture = freedCachedTexture('img:poster.png');
-    (texture.renderableOwners as unknown[]).push(1);
+    texture.renderableOwners.add(1);
     keyCache.set('img:poster.png', texture);
 
     mgr.cleanup();

package/src/core/TextureMemoryManager.ts

@@ -349,7 +349,7 @@ export class TextureMemoryManager {
       if (
         evictable === true &&
         texture.preventCleanup === false &&
-        texture.renderableOwners.length === 0 &&
+        texture.renderableOwners.size === 0 &&
         texture.hasListeners() === false
       ) {
         this.destroyTexture(texture);

package/src/core/lib/WebGlContextWrapper.ts

@@ -1190,6 +1190,22 @@ export class WebGlContextWrapper {
     return this.gl.getError();
   }
 
+  /**
+   * ```
+   * gl.isContextLost();
+   * ```
+   *
+   * @remarks
+   * Reports the current lost state directly and is not consumed like
+   * `getError()` (whose `CONTEXT_LOST_WEBGL` flag is cleared on first read).
+   * Use this to detect a lost context after a GL call has already failed.
+   *
+   * @returns
+   */
+  isContextLost() {
+    return this.gl.isContextLost();
+  }
+
   /**
    * ```
    * gl.getAttribLocation(program, name);

package/src/core/renderers/canvas/CanvasRenderer.ts

@@ -260,6 +260,26 @@ export class CanvasRenderer extends CoreRenderer {
     }
   }
 
+  /**
+   * Renders a node's content (texture or color rect) into an arbitrary 2D
+   * context instead of the main canvas. Used by shaders that need to
+   * composite the node's content offscreen (e.g. EdgeFade alpha masks).
+   *
+   * The content is drawn at the node's global position — the caller is
+   * responsible for setting a transform on `target` that maps it to the
+   * desired location.
+   */
+  renderNodeContent(node: CoreNode, target: CanvasRenderingContext2D): void {
+    let texture = node.props.texture;
+    if (node.placeholderActive === true || texture === null) {
+      texture = this.stage.defaultTexture as Texture;
+    }
+    const prev = this.context;
+    this.context = target;
+    this.renderContext(node, texture);
+    this.context = prev;
+  }
+
   createShaderNode(
     shaderKey: string,
     shaderType: Readonly<CanvasShaderType>,

package/src/core/renderers/webgl/WebGlCtxTexture.ts

@@ -161,10 +161,11 @@ export class WebGlCtxTexture extends CoreContextTexture {
       );
     }
 
-    // Set to a 1x1 transparent texture
-    glw.texImage2D(0, glw.RGBA, 1, 1, 0, glw.RGBA, glw.UNSIGNED_BYTE, null);
-    this.setTextureMemUse(TRANSPARENT_TEXTURE_DATA.byteLength);
-
+    // No placeholder upload here: every branch below fully (re)uploads the
+    // texture before this method returns, and there is no `await` in between,
+    // so no frame can render an intermediate 1x1. The empty-texture case
+    // (`tdata === null`) does its own 1x1 upload. Uploading a throwaway 1x1
+    // first would be a wasted texImage2D + setTextureMemUse per texture.
     let w = 0;
     let h = 0;
 

package/src/core/renderers/webgl/WebGlRenderer.contextLoss.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Tests for WebGlRenderer.createShaderProgram's context-loss handling.
+ *
+ * When the GL context is lost, gl.createShader() returns null and getError()
+ * reports CONTEXT_LOST_WEBGL (0x9242 / 37442). That can happen on the app's
+ * reactive stack before the async `webglcontextlost` event fires, so the
+ * renderer trips `stage.setContextLost()` itself when it detects a lost
+ * context — but only then; genuine compile errors are rethrown untouched.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { WebGlRenderer } from './WebGlRenderer.js';
+import type { WebGlShaderType } from './WebGlShaderNode.js';
+
+function makeRenderer(isContextLost: boolean) {
+  const setContextLost = vi.fn();
+  // Minimal glw that drives the WebGlShaderProgram constructor straight to the
+  // "Unable to create the shader" throw (createShader returns null).
+  const glw = {
+    VERTEX_SHADER: 0x8b31,
+    getExtension: () => ({}),
+    createShader: () => null,
+    getError: () => 37442,
+    isContextLost: () => isContextLost,
+  };
+  const renderer = Object.create(WebGlRenderer.prototype) as WebGlRenderer;
+  (renderer as unknown as { glw: unknown }).glw = glw;
+  (renderer as unknown as { stage: unknown }).stage = { setContextLost };
+
+  const config = { vertex: 'v', fragment: 'f' } as unknown as WebGlShaderType;
+  return { renderer, config, setContextLost };
+}
+
+describe('WebGlRenderer.createShaderProgram — context loss', () => {
+  it('trips setContextLost and rethrows when the context is lost', () => {
+    const { renderer, config, setContextLost } = makeRenderer(true);
+
+    expect(() => renderer.createShaderProgram(config, {})).toThrow(
+      /Unable to create the shader/,
+    );
+    expect(setContextLost).toHaveBeenCalledTimes(1);
+  });
+
+  it('rethrows without tripping setContextLost when the context is healthy', () => {
+    const { renderer, config, setContextLost } = makeRenderer(false);
+
+    expect(() => renderer.createShaderProgram(config, {})).toThrow();
+    expect(setContextLost).not.toHaveBeenCalled();
+  });
+});

package/src/core/renderers/webgl/WebGlRenderer.ts

@@ -385,7 +385,19 @@ export class WebGlRenderer extends CoreRenderer {
     shaderType: WebGlShaderType,
     props: Record<string, unknown>,
   ): WebGlShaderProgram {
-    return new WebGlShaderProgram(this, shaderType, props);
+    try {
+      return new WebGlShaderProgram(this, shaderType, props);
+    } catch (e) {
+      // A lost GL context makes shader creation/compilation fail synchronously
+      // (gl.createShader returns null -> CONTEXT_LOST_WEBGL). This can run on
+      // the app's reactive stack before the async `webglcontextlost` event is
+      // processed, so trip the flag here too. setContextLost() is idempotent
+      // and emits `contextLost` for consumers (recovery is an app reload).
+      if (this.glw.isContextLost() === true) {
+        this.stage.setContextLost();
+      }
+      throw e;
+    }
   }
 
   createShaderNode(

package/src/core/shaders/canvas/EdgeFade.ts

@@ -0,0 +1,105 @@
+import type { CanvasShaderType } from '../../renderers/canvas/CanvasShaderNode.js';
+import type { CanvasRenderer } from '../../renderers/canvas/CanvasRenderer.js';
+import {
+  EdgeFadeTemplate,
+  type EdgeFadeProps,
+} from '../templates/EdgeFadeTemplate.js';
+
+// Shared scratch canvas, grown on demand and reused across all EdgeFade nodes.
+// Rendering is single-threaded and non-reentrant so one scratch is enough.
+let scratchCanvas: HTMLCanvasElement | null = null;
+let scratchCtx: CanvasRenderingContext2D | null = null;
+
+/**
+ * Canvas2D implementation of {@link EdgeFade}: the node's content is drawn
+ * into an offscreen canvas, the edge ramps are erased with destination-out
+ * gradients, and the result is composited onto the main canvas. This keeps
+ * the background behind the node intact, which a destination-out pass on the
+ * main canvas could not.
+ */
+export const EdgeFade: CanvasShaderType<EdgeFadeProps> = {
+  props: EdgeFadeTemplate.props,
+  render(ctx, node, renderContext) {
+    const props = this.props!;
+    const left = props.left;
+    const top = props.top;
+    const right = props.right;
+    const bottom = props.bottom;
+
+    if (left <= 0 && top <= 0 && right <= 0 && bottom <= 0) {
+      renderContext();
+      return;
+    }
+
+    const w = node.props.w;
+    const h = node.props.h;
+    if (w <= 0 || h <= 0) {
+      return;
+    }
+
+    const pr = this.stage.pixelRatio;
+    const sw = w * pr;
+    const sh = h * pr;
+
+    if (scratchCanvas === null) {
+      scratchCanvas = document.createElement('canvas');
+      scratchCtx = scratchCanvas.getContext('2d') as CanvasRenderingContext2D;
+    }
+    const sctx = scratchCtx!;
+
+    if (scratchCanvas.width < sw || scratchCanvas.height < sh) {
+      // Growing the canvas implicitly clears it
+      scratchCanvas.width = Math.ceil(sw);
+      scratchCanvas.height = Math.ceil(sh);
+    } else {
+      sctx.setTransform(1, 0, 0, 1, 0, 0);
+      sctx.clearRect(0, 0, sw, sh);
+    }
+
+    // Draw the node's content at the scratch origin
+    const tx = node.globalTransform!.tx;
+    const ty = node.globalTransform!.ty;
+    sctx.setTransform(pr, 0, 0, pr, -tx * pr, -ty * pr);
+    (this.stage.renderer as CanvasRenderer).renderNodeContent(node, sctx);
+    sctx.setTransform(1, 0, 0, 1, 0, 0);
+
+    // Erase each edge with a linear ramp. Sequential destination-out passes
+    // multiply: dst *= (1 - g), matching the WebGL ramp product.
+    sctx.globalCompositeOperation = 'destination-out';
+    if (left > 0) {
+      const d = left * pr;
+      const g = sctx.createLinearGradient(0, 0, d, 0);
+      g.addColorStop(0, 'rgba(0,0,0,1)');
+      g.addColorStop(1, 'rgba(0,0,0,0)');
+      sctx.fillStyle = g;
+      sctx.fillRect(0, 0, d, sh);
+    }
+    if (top > 0) {
+      const d = top * pr;
+      const g = sctx.createLinearGradient(0, 0, 0, d);
+      g.addColorStop(0, 'rgba(0,0,0,1)');
+      g.addColorStop(1, 'rgba(0,0,0,0)');
+      sctx.fillStyle = g;
+      sctx.fillRect(0, 0, sw, d);
+    }
+    if (right > 0) {
+      const d = right * pr;
+      const g = sctx.createLinearGradient(sw - d, 0, sw, 0);
+      g.addColorStop(0, 'rgba(0,0,0,0)');
+      g.addColorStop(1, 'rgba(0,0,0,1)');
+      sctx.fillStyle = g;
+      sctx.fillRect(sw - d, 0, d, sh);
+    }
+    if (bottom > 0) {
+      const d = bottom * pr;
+      const g = sctx.createLinearGradient(0, sh - d, 0, sh);
+      g.addColorStop(0, 'rgba(0,0,0,0)');
+      g.addColorStop(1, 'rgba(0,0,0,1)');
+      sctx.fillStyle = g;
+      sctx.fillRect(0, sh - d, sw, d);
+    }
+    sctx.globalCompositeOperation = 'source-over';
+
+    ctx.drawImage(scratchCanvas, 0, 0, sw, sh, tx, ty, w, h);
+  },
+};

package/src/core/shaders/canvas/LinearGradient.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { LinearGradient } from './LinearGradient.js';
+import { normalizeCanvasColor } from '../../lib/colorCache.js';
+
+/**
+ * Invoke the canvas LinearGradient `update()` with a minimal fake shader node
+ * and return the computed CSS color strings.
+ */
+function computeColors(colors: number[]): string[] {
+  const ctx = {
+    props: { colors, stops: [0, 1], angle: 0 },
+    computed: undefined as unknown,
+    toColorString: (value: number) => normalizeCanvasColor(value, true),
+  };
+  // Colors are RGBA encoded (alpha in the low byte) — see parseToRgbaString.
+  LinearGradient.update!.call(ctx as never, { w: 100, h: 100 } as never);
+  return (ctx.computed as { colors: string[] }).colors;
+}
+
+describe('canvas LinearGradient color mapping', () => {
+  it('preserves per-stop alpha (no opaque fallback)', () => {
+    // 0x00ff0080 is a half-transparent green stop. The previous
+    // "nearest opaque RGB" workaround mis-read the high byte as alpha
+    // (it is actually red in RGBA) and overwrote the low byte, turning
+    // transparent stops solid. The faithful mapping must keep alpha ~0.5.
+    const [opaqueRed, halfGreen] = computeColors([0xff0000ff, 0x00ff0080]);
+
+    expect(opaqueRed).toBe('rgba(255,0,0,1)');
+    expect(halfGreen).toBe(`rgba(0,255,0,${0x80 / 255})`);
+  });
+
+  it('keeps fully transparent stops transparent', () => {
+    const [, transparent] = computeColors([0x000000ff, 0x00000000]);
+    expect(transparent).toBe('rgba(0,0,0,0)');
+  });
+
+  it('maps every stop straight through toColorString', () => {
+    const colors = [0xff0000ff, 0x00ff00ff, 0x0000ffff];
+    expect(computeColors(colors)).toEqual([
+      'rgba(255,0,0,1)',
+      'rgba(0,255,0,1)',
+      'rgba(0,0,255,1)',
+    ]);
+  });
+});