@solidtv/renderer 1.5.4 → 1.5.6

package/src/core/platforms/web/WebPlatform.ts

@@ -64,47 +64,73 @@ export class WebPlatform extends Platform {
         lastFrameTime = currentTime;
       }
 
-      stage.updateFrameTime();
-      const hasActiveAnimations = stage.updateAnimations();
-
-      if (!stage.hasSceneUpdates()) {
-        // We still need to calculate the fps else it looks like the app is frozen
-        stage.calculateFps();
-
-        // We use 15ms instead of 16.6ms to provide a safety buffer.
-        // This ensures we wake up slightly before the next frame to check for updates,
-        // preventing us from missing a frame due to timer variances.
-        setTimeout(requestLoop, Math.max(targetFrameTime, 15));
-
-        if (isIdle === false) {
-          // The render burst has settled. Probe for a GPU out-of-memory now
-          // rather than every frame: GL errors accumulate and persist until
-          // drained, so a single check here still catches any OOM raised during
-          // the active frames, without paying the getError() CPU/GPU sync on
-          // every frame. Queues the `outOfMemory` event, flushed below.
-          if (stage.renderer.checkForOutOfMemory() === true) {
-            stage.txMemManager.handleOutOfMemory();
+      // From here on the frame runs client-supplied code: synchronous event
+      // subscribers (`frameTick`, `idle`, and the queued events drained by
+      // `flushFrameEvents`) and animation steps. A throw in any of these would
+      // otherwise propagate out of the rAF callback and permanently stop the
+      // render loop — the whole app freezes until reload. Guard the body and
+      // always keep the loop alive: hand the error to `handleLoopError` (a
+      // no-op by default; the app can override it to log/report) and reschedule.
+      // `scheduled` tracks whether the next tick was already queued before the
+      // throw so we never double-schedule (which would compound into runaway
+      // frames if it threw every frame).
+      let scheduled = false;
+      try {
+        stage.updateFrameTime();
+        const hasActiveAnimations = stage.updateAnimations();
+
+        if (!stage.hasSceneUpdates()) {
+          // We still need to calculate the fps else it looks like the app is frozen
+          stage.calculateFps();
+
+          // We use 15ms instead of 16.6ms to provide a safety buffer.
+          // This ensures we wake up slightly before the next frame to check for updates,
+          // preventing us from missing a frame due to timer variances.
+          setTimeout(requestLoop, Math.max(targetFrameTime, 15));
+          scheduled = true;
+
+          if (isIdle === false) {
+            // The render burst has settled. Probe for a GPU out-of-memory now
+            // rather than every frame: GL errors accumulate and persist until
+            // drained, so a single check here still catches any OOM raised during
+            // the active frames, without paying the getError() CPU/GPU sync on
+            // every frame. Queues the `outOfMemory` event, flushed below.
+            if (stage.renderer.checkForOutOfMemory() === true) {
+              stage.txMemManager.handleOutOfMemory();
+            }
+            stage.shManager.cleanup();
+            stage.cleanupTextRenderers();
+            stage.eventBus.emit('idle');
+            isIdle = true;
+          }
+
+          if (stage.txMemManager.checkCleanup() === true) {
+            stage.txMemManager.cleanup();
           }
-          stage.shManager.cleanup();
-          stage.cleanupTextRenderers();
-          stage.eventBus.emit('idle');
-          isIdle = true;
-        }
 
-        if (stage.txMemManager.checkCleanup() === true) {
-          stage.txMemManager.cleanup();
+          stage.flushFrameEvents();
+          return;
         }
 
+        isIdle = false;
+        stage.drawFrame(hasActiveAnimations);
         stage.flushFrameEvents();
-        return;
-      }
-
-      isIdle = false;
-      stage.drawFrame(hasActiveAnimations);
-      stage.flushFrameEvents();
 
-      // Schedule next frame
-      requestAnimationFrame(runLoop);
+        // Schedule next frame
+        requestAnimationFrame(runLoop);
+        scheduled = true;
+      } catch (error: unknown) {
+        // Report the error (default handler is a no-op), then keep the loop
+        // alive — a single bad frame must never freeze the app. Skip the
+        // reschedule if this frame already queued the next tick before throwing.
+        const handleLoopError = stage.options.handleLoopError;
+        if (handleLoopError !== undefined) {
+          handleLoopError(error);
+        }
+        if (scheduled === false) {
+          requestAnimationFrame(runLoop);
+        }
+      }
     };
 
     const requestLoop = () => requestAnimationFrame(runLoop);

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/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)',
+    ]);
+  });
+});

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

@@ -31,24 +31,7 @@ export const LinearGradient: CanvasShaderType<
       y0: line * Math.sin(angle) + nHeight * 0.5,
       x1: line * Math.cos(angle + Math.PI) + nWidth * 0.5,
       y1: line * Math.sin(angle + Math.PI) + nHeight * 0.5,
-      colors: this.props!.colors.map((value, i, arr) => {
-        const alpha = (value >>> 24) & 0xff;
-        if (alpha === 0) {
-          let nearestRGB = value & 0x00ffffff;
-          for (let step = 1; step < arr.length; step++) {
-            if (i - step >= 0 && ((arr[i - step]! >>> 24) & 0xff) > 0) {
-              nearestRGB = arr[i - step]! & 0x00ffffff;
-              break;
-            }
-            if (i + step < arr.length && ((arr[i + step]! >>> 24) & 0xff) > 0) {
-              nearestRGB = arr[i + step]! & 0x00ffffff;
-              break;
-            }
-          }
-          value = (value & 0xff000000) | nearestRGB;
-        }
-        return this.toColorString(value);
-      }),
+      colors: this.props!.colors.map((value) => this.toColorString(value)),
     };
   },
   render(ctx, node, renderContext) {

package/src/core/shaders/templates/EdgeFadeTemplate.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { EdgeFadeTemplate, type EdgeFadeProps } from './EdgeFadeTemplate.js';
+import { resolveShaderProps } from '../../renderers/CoreShaderNode.js';
+
+function resolve(input: Partial<EdgeFadeProps>): EdgeFadeProps {
+  const props = { ...input } as Record<string, unknown>;
+  resolveShaderProps(props, EdgeFadeTemplate.props as never);
+  return props as unknown as EdgeFadeProps;
+}
+
+describe('EdgeFadeTemplate', () => {
+  it('defaults all edges to 0 (no fade)', () => {
+    const props = resolve({});
+    expect(props.left).toBe(0);
+    expect(props.top).toBe(0);
+    expect(props.right).toBe(0);
+    expect(props.bottom).toBe(0);
+  });
+
+  it('passes through a single edge, leaving others at 0', () => {
+    const props = resolve({ right: 420 });
+    expect(props.right).toBe(420);
+    expect(props.left).toBe(0);
+    expect(props.top).toBe(0);
+    expect(props.bottom).toBe(0);
+  });
+
+  it('passes through all edges', () => {
+    const props = resolve({ left: 10, top: 20, right: 30, bottom: 40 });
+    expect(props.left).toBe(10);
+    expect(props.top).toBe(20);
+    expect(props.right).toBe(30);
+    expect(props.bottom).toBe(40);
+  });
+});

package/src/core/shaders/templates/EdgeFadeTemplate.ts

@@ -0,0 +1,41 @@
+import type { CoreShaderType } from '../../renderers/CoreShaderNode.js';
+
+/**
+ * Properties of the {@link EdgeFade} shader
+ */
+export interface EdgeFadeProps {
+  /**
+   * Fade distance in pixels from the left edge. Alpha ramps 0 → 1 over this
+   * distance. 0 disables the fade for this edge.
+   *
+   * @default 0
+   */
+  left: number;
+  /**
+   * Fade distance in pixels from the top edge.
+   *
+   * @default 0
+   */
+  top: number;
+  /**
+   * Fade distance in pixels from the right edge.
+   *
+   * @default 0
+   */
+  right: number;
+  /**
+   * Fade distance in pixels from the bottom edge.
+   *
+   * @default 0
+   */
+  bottom: number;
+}
+
+export const EdgeFadeTemplate: CoreShaderType<EdgeFadeProps> = {
+  props: {
+    left: 0,
+    top: 0,
+    right: 0,
+    bottom: 0,
+  },
+};

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

@@ -0,0 +1,84 @@
+import type { WebGlShaderType } from '../../renderers/webgl/WebGlShaderNode.js';
+import {
+  EdgeFadeTemplate,
+  type EdgeFadeProps,
+} from '../templates/EdgeFadeTemplate.js';
+
+/**
+ * Multiplies the node's alpha by a linear ramp inward from each edge with a
+ * non-zero fade distance, revealing whatever is rendered behind the node.
+ * Unlike {@link LinearGradient} this masks the texture's own alpha instead of
+ * blending a gradient color over its RGB.
+ */
+export const EdgeFade: WebGlShaderType<EdgeFadeProps> = {
+  props: EdgeFadeTemplate.props,
+  update() {
+    const props = this.props!;
+    // Reciprocals are uploaded so the fragment shader needs no division and
+    // no zero-guard branch: 1e6 saturates clamp(px * recip) to 1.0 within a
+    // fraction of a pixel, which is exactly "no fade on this edge".
+    this.uniform4f(
+      'u_fadeRecip',
+      props.left > 0 ? 1 / props.left : 1e6,
+      props.top > 0 ? 1 / props.top : 1e6,
+      props.right > 0 ? 1 / props.right : 1e6,
+      props.bottom > 0 ? 1 / props.bottom : 1e6,
+    );
+  },
+  vertex: `
+    # ifdef GL_FRAGMENT_PRECISION_HIGH
+    precision highp float;
+    # else
+    precision mediump float;
+    # endif
+
+    attribute vec2 a_position;
+    attribute vec2 a_textureCoords;
+    attribute vec4 a_color;
+    attribute vec2 a_nodeCoords;
+
+    uniform vec2 u_resolution;
+    uniform float u_pixelRatio;
+
+    varying vec4 v_color;
+    varying vec2 v_textureCoords;
+    varying vec2 v_nodeCoords;
+
+    void main() {
+      vec2 normalized = a_position * u_pixelRatio / u_resolution;
+      vec2 zero_two = normalized * 2.0;
+      vec2 clip_space = zero_two - 1.0;
+
+      v_color = a_color;
+      v_textureCoords = a_textureCoords;
+      v_nodeCoords = a_nodeCoords;
+
+      gl_Position = vec4(clip_space * vec2(1.0, -1.0), 0, 1);
+    }
+  `,
+  fragment: `
+    # ifdef GL_FRAGMENT_PRECISION_HIGH
+    precision highp float;
+    # else
+    precision mediump float;
+    # endif
+
+    uniform vec2 u_dimensions;
+    uniform sampler2D u_texture;
+    uniform vec4 u_fadeRecip;
+
+    varying vec4 v_color;
+    varying vec2 v_textureCoords;
+    varying vec2 v_nodeCoords;
+
+    void main() {
+      vec4 color = v_color * texture2D(u_texture, v_textureCoords);
+      vec2 px = v_nodeCoords * u_dimensions;
+      float fade = clamp(px.x * u_fadeRecip.x, 0.0, 1.0)
+        * clamp(px.y * u_fadeRecip.y, 0.0, 1.0)
+        * clamp((u_dimensions.x - px.x) * u_fadeRecip.z, 0.0, 1.0)
+        * clamp((u_dimensions.y - px.y) * u_fadeRecip.w, 0.0, 1.0);
+      gl_FragColor = color * fade;
+    }
+  `,
+};

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

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { LinearGradient } from './LinearGradient.js';
+
+interface GradUniforms {
+  a: [number, number];
+  b: number;
+}
+
+/**
+ * Invoke the WebGL LinearGradient `update()` with a fake shader node that
+ * captures the gradient uniforms (`u_grad_a` / `u_grad_b`). The fragment
+ * shader computes `dist = dot(v_textureCoords, u_grad_a) + u_grad_b`, so these
+ * uniforms fully define the gradient ramp.
+ */
+function computeGrad(angle: number, w: number, h: number): GradUniforms {
+  const out: GradUniforms = { a: [0, 0], b: 0 };
+  const ctx = {
+    props: { colors: [0x000000ff, 0xffffffff], stops: [0, 1], angle },
+    uniform2f: (name: string, v0: number, v1: number) => {
+      if (name === 'u_grad_a') out.a = [v0, v1];
+    },
+    uniform1f: (name: string, v: number) => {
+      if (name === 'u_grad_b') out.b = v;
+    },
+    uniform1fv: () => undefined,
+    uniform4fv: () => undefined,
+  };
+  LinearGradient.update!.call(ctx as never, { w, h } as never);
+  return out;
+}
+
+const distAt = (g: GradUniforms, tx: number, ty: number) =>
+  tx * g.a[0] + ty * g.a[1] + g.b;
+
+describe('webgl LinearGradient gradient uniforms', () => {
+  it('angle 0 ramps top -> bottom across the node-local box', () => {
+    const g = computeGrad(0, 200, 100);
+    expect(g.a[0]).toBeCloseTo(0, 5);
+    expect(g.a[1]).toBeCloseTo(1, 5);
+    expect(g.b).toBeCloseTo(0, 5);
+    // dist runs 0 (top) -> 1 (bottom)
+    expect(distAt(g, 0.5, 0)).toBeCloseTo(0, 5);
+    expect(distAt(g, 0.5, 1)).toBeCloseTo(1, 5);
+  });
+
+  it('angle 90deg ramps horizontally', () => {
+    const g = computeGrad(Math.PI / 2, 200, 100);
+    expect(g.a[0]).toBeCloseTo(-1, 5);
+    expect(g.a[1]).toBeCloseTo(0, 5);
+    expect(distAt(g, 0, 0.5)).toBeCloseTo(1, 5);
+    expect(distAt(g, 1, 0.5)).toBeCloseTo(0, 5);
+  });
+
+  it('endpoints stay within [0,1] for an arbitrary angle', () => {
+    const g = computeGrad(Math.PI / 4, 640, 360);
+    // Box corners must map into the clampable [0,1] ramp range.
+    const corners = [
+      distAt(g, 0, 0),
+      distAt(g, 1, 0),
+      distAt(g, 0, 1),
+      distAt(g, 1, 1),
+    ];
+    for (let i = 0; i < corners.length; i++) {
+      expect(corners[i]).toBeGreaterThanOrEqual(-1e-6);
+      expect(corners[i]).toBeLessThanOrEqual(1 + 1e-6);
+    }
+    // The gradient axis is symmetric about the box center -> dist = 0.5 there.
+    expect(distAt(g, 0.5, 0.5)).toBeCloseTo(0.5, 5);
+  });
+});