@mui/x-charts-premium 9.7.0 → 9.8.0

package/internals/createGetVisibleCoordinate.mjs

@@ -0,0 +1,60 @@
+// A `GeoStream` sink that only records whether a point passed through (and where),
+// so a projection/clip pipeline can be probed one point at a time.
+
+function createPointSink() {
+  const sink = {
+    hit: false,
+    x: 0,
+    y: 0,
+    point(x, y) {
+      sink.hit = true;
+      sink.x = x;
+      sink.y = y;
+    },
+    lineStart() {},
+    lineEnd() {},
+    polygonStart() {},
+    polygonEnd() {}
+  };
+  return sink;
+}
+
+/**
+ * Builds a test that maps a device pixel to its `[lon, lat]`, or `null` when the
+ * pixel is not part of the visible map. It combines two clips that `projection.invert`
+ * alone misses:
+ *
+ * - the **post-clip** (cartesian) stream rejects device pixels outside the clip
+ *   rectangle — relevant once the map is panned/zoomed with a `clipExtent`;
+ * - streaming the inverted coordinate **back** through the projection applies the
+ *   pre-clip (spherical) boundary and checks the round trip: azimuthal projections
+ *   clamp `invert` outside the visible disk to the limb, and those clamped points do
+ *   not project back to the pixel they came from.
+ */
+export function createGetVisibleCoordinate(projection) {
+  const invert = projection.invert;
+  const forwardSink = createPointSink();
+  const forwardStream = projection.stream(forwardSink);
+  const postClip = projection.postclip?.();
+  const clipSink = createPointSink();
+  const clipStream = postClip?.(clipSink);
+  return ([deviceX, deviceY]) => {
+    if (clipStream) {
+      clipSink.hit = false;
+      clipStream.point(deviceX, deviceY);
+      if (!clipSink.hit) {
+        return null;
+      }
+    }
+    const coordinates = invert([deviceX, deviceY]);
+    if (!coordinates) {
+      return null;
+    }
+    forwardSink.hit = false;
+    forwardStream.point(coordinates[0], coordinates[1]);
+    if (!forwardSink.hit || Math.abs(forwardSink.x - deviceX) > 0.5 || Math.abs(forwardSink.y - deviceY) > 0.5) {
+      return null;
+    }
+    return coordinates;
+  };
+}

package/models/seriesType/mapShape.d.mts

@@ -94,7 +94,7 @@ export interface MapShapeSeriesType extends Omit<CommonSeriesType<'mapShape'>, '
 export type MapShapeItemIdentifier = {
   type: 'mapShape';
   seriesId: SeriesId;
-  dataIndex: number;
+  name: string;
 };
 export type DefaultizedMapShapeValueType = MapShapeValueType & {
   hidden: boolean;
@@ -102,4 +102,5 @@ export type DefaultizedMapShapeValueType = MapShapeValueType & {
 export interface DefaultizedMapShapeSeriesType extends Omit<DefaultizedProps<MapShapeSeriesType, CommonDefaultizedProps | 'color'>, 'data'> {
   hidden: boolean;
   data: ReadonlyArray<DefaultizedMapShapeValueType>;
+  lookupByName: ReadonlyMap<string, number>;
 }

package/models/seriesType/mapShape.d.ts

@@ -94,7 +94,7 @@ export interface MapShapeSeriesType extends Omit<CommonSeriesType<'mapShape'>, '
 export type MapShapeItemIdentifier = {
   type: 'mapShape';
   seriesId: SeriesId;
-  dataIndex: number;
+  name: string;
 };
 export type DefaultizedMapShapeValueType = MapShapeValueType & {
   hidden: boolean;
@@ -102,4 +102,5 @@ export type DefaultizedMapShapeValueType = MapShapeValueType & {
 export interface DefaultizedMapShapeSeriesType extends Omit<DefaultizedProps<MapShapeSeriesType, CommonDefaultizedProps | 'color'>, 'data'> {
   hidden: boolean;
   data: ReadonlyArray<DefaultizedMapShapeValueType>;
+  lookupByName: ReadonlyMap<string, number>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/x-charts-premium",
-  "version": "9.7.0",
+  "version": "9.8.0",
   "author": "MUI Team",
   "description": "The Premium plan edition of the MUI X Charts components.",
   "license": "SEE LICENSE IN LICENSE",
@@ -31,11 +31,11 @@
     "@mui/utils": "^9.1.1",
     "clsx": "^2.1.1",
     "prop-types": "^15.8.1",
-    "@mui/x-charts": "^9.7.0",
-    "@mui/x-charts-pro": "^9.7.0",
     "@mui/x-charts-vendor": "^9.4.0",
-    "@mui/x-license": "^9.7.0",
-    "@mui/x-internals": "^9.7.0"
+    "@mui/x-internals": "^9.8.0",
+    "@mui/x-license": "^9.8.0",
+    "@mui/x-charts": "^9.8.0",
+    "@mui/x-charts-pro": "^9.8.0"
   },
   "peerDependencies": {
     "@emotion/react": "^11.9.0",

package/utils/webgl/glsl.d.mts

@@ -0,0 +1,15 @@
+/**
+ * GLSL snippet: signed distance field for a rounded box with per-corner radii.
+ *
+ * Convention:
+ *   - `pos` and `halfSize` are in the same pixel-space coordinates.
+ *   - `r` carries corner radii in CSS order: top-left, top-right, bottom-right, bottom-left.
+ *   - For uniform-radius use cases pass `vec4(scalar)`.
+ *
+ * Screen-space conventions (after the y-flip in the vertex stage):
+ *   pos.y < 0 -> top,   pos.y > 0 -> bottom
+ *   pos.x < 0 -> left,  pos.x > 0 -> right
+ *
+ * Reference: Inigo Quilez, "Distance to a rounded box".
+ */
+export declare const ROUNDED_BOX_SDF_GLSL = "\n    float roundedBoxSDF(vec2 pos, vec2 halfSize, vec4 r) {\n      float radius;\n      if (pos.x < 0.0) {\n        radius = pos.y < 0.0 ? r.x : r.w;\n      } else {\n        radius = pos.y < 0.0 ? r.y : r.z;\n      }\n\n      vec2 q = abs(pos) - halfSize + radius;\n      return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - radius;\n    }\n  ";

package/utils/webgl/glsl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GLSL snippet: signed distance field for a rounded box with per-corner radii.
+ *
+ * Convention:
+ *   - `pos` and `halfSize` are in the same pixel-space coordinates.
+ *   - `r` carries corner radii in CSS order: top-left, top-right, bottom-right, bottom-left.
+ *   - For uniform-radius use cases pass `vec4(scalar)`.
+ *
+ * Screen-space conventions (after the y-flip in the vertex stage):
+ *   pos.y < 0 -> top,   pos.y > 0 -> bottom
+ *   pos.x < 0 -> left,  pos.x > 0 -> right
+ *
+ * Reference: Inigo Quilez, "Distance to a rounded box".
+ */
+export declare const ROUNDED_BOX_SDF_GLSL = "\n    float roundedBoxSDF(vec2 pos, vec2 halfSize, vec4 r) {\n      float radius;\n      if (pos.x < 0.0) {\n        radius = pos.y < 0.0 ? r.x : r.w;\n      } else {\n        radius = pos.y < 0.0 ? r.y : r.z;\n      }\n\n      vec2 q = abs(pos) - halfSize + radius;\n      return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - radius;\n    }\n  ";

package/utils/webgl/glsl.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ROUNDED_BOX_SDF_GLSL = void 0;
+/**
+ * GLSL snippet: signed distance field for a rounded box with per-corner radii.
+ *
+ * Convention:
+ *   - `pos` and `halfSize` are in the same pixel-space coordinates.
+ *   - `r` carries corner radii in CSS order: top-left, top-right, bottom-right, bottom-left.
+ *   - For uniform-radius use cases pass `vec4(scalar)`.
+ *
+ * Screen-space conventions (after the y-flip in the vertex stage):
+ *   pos.y < 0 -> top,   pos.y > 0 -> bottom
+ *   pos.x < 0 -> left,  pos.x > 0 -> right
+ *
+ * Reference: Inigo Quilez, "Distance to a rounded box".
+ */
+// language=Glsl
+const ROUNDED_BOX_SDF_GLSL = exports.ROUNDED_BOX_SDF_GLSL = /* glsl */`
+    float roundedBoxSDF(vec2 pos, vec2 halfSize, vec4 r) {
+      float radius;
+      if (pos.x < 0.0) {
+        radius = pos.y < 0.0 ? r.x : r.w;
+      } else {
+        radius = pos.y < 0.0 ? r.y : r.z;
+      }
+
+      vec2 q = abs(pos) - halfSize + radius;
+      return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - radius;
+    }
+  `;

package/utils/webgl/glsl.mjs

@@ -0,0 +1,28 @@
+/**
+ * GLSL snippet: signed distance field for a rounded box with per-corner radii.
+ *
+ * Convention:
+ *   - `pos` and `halfSize` are in the same pixel-space coordinates.
+ *   - `r` carries corner radii in CSS order: top-left, top-right, bottom-right, bottom-left.
+ *   - For uniform-radius use cases pass `vec4(scalar)`.
+ *
+ * Screen-space conventions (after the y-flip in the vertex stage):
+ *   pos.y < 0 -> top,   pos.y > 0 -> bottom
+ *   pos.x < 0 -> left,  pos.x > 0 -> right
+ *
+ * Reference: Inigo Quilez, "Distance to a rounded box".
+ */
+// language=Glsl
+export const ROUNDED_BOX_SDF_GLSL = /* glsl */`
+    float roundedBoxSDF(vec2 pos, vec2 halfSize, vec4 r) {
+      float radius;
+      if (pos.x < 0.0) {
+        radius = pos.y < 0.0 ? r.x : r.w;
+      } else {
+        radius = pos.y < 0.0 ? r.y : r.z;
+      }
+
+      vec2 q = abs(pos) - halfSize + radius;
+      return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - radius;
+    }
+  `;

package/utils/webgl/instancedAttribute.d.mts

@@ -0,0 +1,28 @@
+import type { GrowableBuffer } from "./utils.mjs";
+export interface InstancedAttribute {
+  buffer: GrowableBuffer;
+  location: number;
+  size: number;
+  glType: GLenum;
+  normalized: boolean;
+}
+/**
+ * Creates a per-instance vertex attribute backed by a fresh grow-only GPU buffer.
+ *
+ * The caller MUST have the owning VAO bound when calling this — the
+ * vertexAttribPointer + vertexAttribDivisor calls register the binding into
+ * that VAO and the program then references it on each draw.
+ */
+export declare function createInstancedAttribute(gl: WebGL2RenderingContext, program: WebGLProgram, name: string, size: number, glType?: GLenum, normalized?: boolean): InstancedAttribute;
+/**
+ * Wires up a per-instance vertex attribute that reads from an existing GrowableBuffer.
+ * Use this when the same buffer must back the same-named attribute in multiple
+ * VAOs (e.g. two shader-program variants over the same data).
+ *
+ * The caller MUST have the owning VAO bound when calling this.
+ *
+ * If the attribute is missing from the program (typo, or optimized out by the
+ * compiler), `getAttribLocation` returns -1. We skip the GL setup in that case to
+ * avoid `INVALID_VALUE` errors from `enableVertexAttribArray(-1)` and warn in dev.
+ */
+export declare function bindInstancedAttribute(gl: WebGL2RenderingContext, program: WebGLProgram, name: string, buffer: GrowableBuffer, size: number, glType?: GLenum, normalized?: boolean): InstancedAttribute;

package/utils/webgl/instancedAttribute.d.ts

@@ -0,0 +1,28 @@
+import type { GrowableBuffer } from "./utils.js";
+export interface InstancedAttribute {
+  buffer: GrowableBuffer;
+  location: number;
+  size: number;
+  glType: GLenum;
+  normalized: boolean;
+}
+/**
+ * Creates a per-instance vertex attribute backed by a fresh grow-only GPU buffer.
+ *
+ * The caller MUST have the owning VAO bound when calling this — the
+ * vertexAttribPointer + vertexAttribDivisor calls register the binding into
+ * that VAO and the program then references it on each draw.
+ */
+export declare function createInstancedAttribute(gl: WebGL2RenderingContext, program: WebGLProgram, name: string, size: number, glType?: GLenum, normalized?: boolean): InstancedAttribute;
+/**
+ * Wires up a per-instance vertex attribute that reads from an existing GrowableBuffer.
+ * Use this when the same buffer must back the same-named attribute in multiple
+ * VAOs (e.g. two shader-program variants over the same data).
+ *
+ * The caller MUST have the owning VAO bound when calling this.
+ *
+ * If the attribute is missing from the program (typo, or optimized out by the
+ * compiler), `getAttribLocation` returns -1. We skip the GL setup in that case to
+ * avoid `INVALID_VALUE` errors from `enableVertexAttribArray(-1)` and warn in dev.
+ */
+export declare function bindInstancedAttribute(gl: WebGL2RenderingContext, program: WebGLProgram, name: string, buffer: GrowableBuffer, size: number, glType?: GLenum, normalized?: boolean): InstancedAttribute;

package/utils/webgl/instancedAttribute.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.bindInstancedAttribute = bindInstancedAttribute;
+exports.createInstancedAttribute = createInstancedAttribute;
+var _utils = require("./utils");
+/**
+ * Creates a per-instance vertex attribute backed by a fresh grow-only GPU buffer.
+ *
+ * The caller MUST have the owning VAO bound when calling this — the
+ * vertexAttribPointer + vertexAttribDivisor calls register the binding into
+ * that VAO and the program then references it on each draw.
+ */
+function createInstancedAttribute(gl, program, name, size, glType = gl.FLOAT, normalized = false) {
+  const buffer = (0, _utils.createGrowableBuffer)(gl);
+  return bindInstancedAttribute(gl, program, name, buffer, size, glType, normalized);
+}
+
+/**
+ * Wires up a per-instance vertex attribute that reads from an existing GrowableBuffer.
+ * Use this when the same buffer must back the same-named attribute in multiple
+ * VAOs (e.g. two shader-program variants over the same data).
+ *
+ * The caller MUST have the owning VAO bound when calling this.
+ *
+ * If the attribute is missing from the program (typo, or optimized out by the
+ * compiler), `getAttribLocation` returns -1. We skip the GL setup in that case to
+ * avoid `INVALID_VALUE` errors from `enableVertexAttribArray(-1)` and warn in dev.
+ */
+function bindInstancedAttribute(gl, program, name, buffer, size, glType = gl.FLOAT, normalized = false) {
+  const location = gl.getAttribLocation(program, name);
+  if (location === -1) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(`WebGL attribute "${name}" not found in shader program (misspelled or optimized out).`);
+    }
+    return {
+      buffer,
+      location,
+      size,
+      glType,
+      normalized
+    };
+  }
+  gl.bindBuffer(gl.ARRAY_BUFFER, buffer.buffer);
+  gl.enableVertexAttribArray(location);
+  gl.vertexAttribPointer(location, size, glType, normalized, 0, 0);
+  gl.vertexAttribDivisor(location, 1);
+  return {
+    buffer,
+    location,
+    size,
+    glType,
+    normalized
+  };
+}

package/utils/webgl/instancedAttribute.mjs

@@ -0,0 +1,50 @@
+import { createGrowableBuffer } from "./utils.mjs";
+/**
+ * Creates a per-instance vertex attribute backed by a fresh grow-only GPU buffer.
+ *
+ * The caller MUST have the owning VAO bound when calling this — the
+ * vertexAttribPointer + vertexAttribDivisor calls register the binding into
+ * that VAO and the program then references it on each draw.
+ */
+export function createInstancedAttribute(gl, program, name, size, glType = gl.FLOAT, normalized = false) {
+  const buffer = createGrowableBuffer(gl);
+  return bindInstancedAttribute(gl, program, name, buffer, size, glType, normalized);
+}
+
+/**
+ * Wires up a per-instance vertex attribute that reads from an existing GrowableBuffer.
+ * Use this when the same buffer must back the same-named attribute in multiple
+ * VAOs (e.g. two shader-program variants over the same data).
+ *
+ * The caller MUST have the owning VAO bound when calling this.
+ *
+ * If the attribute is missing from the program (typo, or optimized out by the
+ * compiler), `getAttribLocation` returns -1. We skip the GL setup in that case to
+ * avoid `INVALID_VALUE` errors from `enableVertexAttribArray(-1)` and warn in dev.
+ */
+export function bindInstancedAttribute(gl, program, name, buffer, size, glType = gl.FLOAT, normalized = false) {
+  const location = gl.getAttribLocation(program, name);
+  if (location === -1) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(`WebGL attribute "${name}" not found in shader program (misspelled or optimized out).`);
+    }
+    return {
+      buffer,
+      location,
+      size,
+      glType,
+      normalized
+    };
+  }
+  gl.bindBuffer(gl.ARRAY_BUFFER, buffer.buffer);
+  gl.enableVertexAttribArray(location);
+  gl.vertexAttribPointer(location, size, glType, normalized, 0, 0);
+  gl.vertexAttribDivisor(location, 1);
+  return {
+    buffer,
+    location,
+    size,
+    glType,
+    normalized
+  };
+}

package/utils/webgl/utils.d.mts

@@ -1,7 +1,6 @@
 export declare function compileShader(gl: WebGL2RenderingContext, shaderSource: string, shaderType: WebGL2RenderingContext['FRAGMENT_SHADER'] | WebGL2RenderingContext['VERTEX_SHADER']): WebGLShader;
 export declare function uploadQuadBuffer(gl: WebGL2RenderingContext): WebGLBuffer;
 export declare function bindQuadBuffer(gl: WebGL2RenderingContext, program: WebGLProgram, quadBuffer: WebGLBuffer): void;
-export declare function attachShader(gl: WebGL2RenderingContext, program: WebGLProgram, shaderSource: string, shaderType: WebGL2RenderingContext['FRAGMENT_SHADER'] | WebGL2RenderingContext['VERTEX_SHADER']): WebGLShader;
 export type GrowableBuffer = {
   buffer: WebGLBuffer;
   capacity: number;
@@ -18,4 +17,24 @@ export declare function uploadGrowableBuffer(gl: WebGL2RenderingContext, target:
 /**
  * Logs WebGL errors to the console in development mode.
  */
-export declare function logWebGLErrors(gl: WebGL2RenderingContext): void;
+export declare function logWebGLErrors(gl: WebGL2RenderingContext): void;
+/** Enables the standard non-premultiplied src-alpha blending used by all premium WebGL renderers. */
+export declare function setupStandardBlending(gl: WebGL2RenderingContext): void;
+/**
+ * Returns `existing` when it's large enough to hold `length` elements, otherwise
+ * allocates a fresh typed array via `Ctor`. Lets consumers keep one ref per
+ * pool and short-circuit growth checks inline.
+ */
+export declare function ensurePool<T extends {
+  length: number;
+}>(existing: T | null | undefined, length: number, Ctor: new (length: number) => T): T;
+export interface LinkedProgram {
+  program: WebGLProgram;
+  /** The vertex + fragment shaders that were attached. Hold them so dispose() can delete them. */
+  shaders: WebGLShader[];
+}
+/**
+ * Compiles vertex + fragment shaders, attaches them, links the program, and returns
+ * both the program and its shaders. Logs link/compile diagnostics in dev when linking fails.
+ */
+export declare function linkProgram(gl: WebGL2RenderingContext, vertexShaderSource: string, fragmentShaderSource: string): LinkedProgram;

package/utils/webgl/utils.d.ts

@@ -1,7 +1,6 @@
 export declare function compileShader(gl: WebGL2RenderingContext, shaderSource: string, shaderType: WebGL2RenderingContext['FRAGMENT_SHADER'] | WebGL2RenderingContext['VERTEX_SHADER']): WebGLShader;
 export declare function uploadQuadBuffer(gl: WebGL2RenderingContext): WebGLBuffer;
 export declare function bindQuadBuffer(gl: WebGL2RenderingContext, program: WebGLProgram, quadBuffer: WebGLBuffer): void;
-export declare function attachShader(gl: WebGL2RenderingContext, program: WebGLProgram, shaderSource: string, shaderType: WebGL2RenderingContext['FRAGMENT_SHADER'] | WebGL2RenderingContext['VERTEX_SHADER']): WebGLShader;
 export type GrowableBuffer = {
   buffer: WebGLBuffer;
   capacity: number;
@@ -18,4 +17,24 @@ export declare function uploadGrowableBuffer(gl: WebGL2RenderingContext, target:
 /**
  * Logs WebGL errors to the console in development mode.
  */
-export declare function logWebGLErrors(gl: WebGL2RenderingContext): void;
+export declare function logWebGLErrors(gl: WebGL2RenderingContext): void;
+/** Enables the standard non-premultiplied src-alpha blending used by all premium WebGL renderers. */
+export declare function setupStandardBlending(gl: WebGL2RenderingContext): void;
+/**
+ * Returns `existing` when it's large enough to hold `length` elements, otherwise
+ * allocates a fresh typed array via `Ctor`. Lets consumers keep one ref per
+ * pool and short-circuit growth checks inline.
+ */
+export declare function ensurePool<T extends {
+  length: number;
+}>(existing: T | null | undefined, length: number, Ctor: new (length: number) => T): T;
+export interface LinkedProgram {
+  program: WebGLProgram;
+  /** The vertex + fragment shaders that were attached. Hold them so dispose() can delete them. */
+  shaders: WebGLShader[];
+}
+/**
+ * Compiles vertex + fragment shaders, attaches them, links the program, and returns
+ * both the program and its shaders. Logs link/compile diagnostics in dev when linking fails.
+ */
+export declare function linkProgram(gl: WebGL2RenderingContext, vertexShaderSource: string, fragmentShaderSource: string): LinkedProgram;

package/utils/webgl/utils.js

@@ -3,11 +3,13 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.attachShader = attachShader;
 exports.bindQuadBuffer = bindQuadBuffer;
 exports.compileShader = compileShader;
 exports.createGrowableBuffer = createGrowableBuffer;
+exports.ensurePool = ensurePool;
+exports.linkProgram = linkProgram;
 exports.logWebGLErrors = logWebGLErrors;
+exports.setupStandardBlending = setupStandardBlending;
 exports.uploadGrowableBuffer = uploadGrowableBuffer;
 exports.uploadQuadBuffer = uploadQuadBuffer;
 function compileShader(gl, shaderSource, shaderType) {
@@ -29,13 +31,6 @@ function bindQuadBuffer(gl, program, quadBuffer) {
   gl.enableVertexAttribArray(aPosition);
   gl.vertexAttribPointer(aPosition, 2, gl.FLOAT, false, 0, 0);
 }
-function attachShader(gl, program, shaderSource, shaderType) {
-  const shader = gl.createShader(shaderType);
-  gl.shaderSource(shader, shaderSource);
-  gl.compileShader(shader);
-  gl.attachShader(program, shader);
-  return shader;
-}
 function createGrowableBuffer(gl) {
   return {
     buffer: gl.createBuffer(),
@@ -77,4 +72,45 @@ function logWebGLErrors(gl) {
       error = gl.getError();
     }
   }
+}
+
+/** Enables the standard non-premultiplied src-alpha blending used by all premium WebGL renderers. */
+function setupStandardBlending(gl) {
+  gl.enable(gl.BLEND);
+  gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+}
+
+/**
+ * Returns `existing` when it's large enough to hold `length` elements, otherwise
+ * allocates a fresh typed array via `Ctor`. Lets consumers keep one ref per
+ * pool and short-circuit growth checks inline.
+ */
+function ensurePool(existing, length, Ctor) {
+  if (existing != null && existing.length >= length) {
+    return existing;
+  }
+  return new Ctor(length);
+}
+/**
+ * Compiles vertex + fragment shaders, attaches them, links the program, and returns
+ * both the program and its shaders. Logs link/compile diagnostics in dev when linking fails.
+ */
+function linkProgram(gl, vertexShaderSource, fragmentShaderSource) {
+  const program = gl.createProgram();
+  const vertexShader = compileShader(gl, vertexShaderSource, gl.VERTEX_SHADER);
+  const fragmentShader = compileShader(gl, fragmentShaderSource, gl.FRAGMENT_SHADER);
+  gl.attachShader(program, vertexShader);
+  gl.attachShader(program, fragmentShader);
+  gl.linkProgram(program);
+  if (process.env.NODE_ENV !== 'production' && !gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    // WebGL best-practices: consult compile/link status only in dev mode
+    // https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL_best_practices#dont_check_shader_compile_status_unless_linking_fails
+    console.error(`Program linking failed: ${gl.getProgramInfoLog(program)}`);
+    console.error(`Vertex shader info-log: ${gl.getShaderInfoLog(vertexShader)}`);
+    console.error(`Fragment shader info-log: ${gl.getShaderInfoLog(fragmentShader)}`);
+  }
+  return {
+    program,
+    shaders: [vertexShader, fragmentShader]
+  };
 }

package/utils/webgl/utils.mjs

@@ -17,13 +17,6 @@ export function bindQuadBuffer(gl, program, quadBuffer) {
   gl.enableVertexAttribArray(aPosition);
   gl.vertexAttribPointer(aPosition, 2, gl.FLOAT, false, 0, 0);
 }
-export function attachShader(gl, program, shaderSource, shaderType) {
-  const shader = gl.createShader(shaderType);
-  gl.shaderSource(shader, shaderSource);
-  gl.compileShader(shader);
-  gl.attachShader(program, shader);
-  return shader;
-}
 export function createGrowableBuffer(gl) {
   return {
     buffer: gl.createBuffer(),
@@ -65,4 +58,45 @@ export function logWebGLErrors(gl) {
       error = gl.getError();
     }
   }
+}
+
+/** Enables the standard non-premultiplied src-alpha blending used by all premium WebGL renderers. */
+export function setupStandardBlending(gl) {
+  gl.enable(gl.BLEND);
+  gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+}
+
+/**
+ * Returns `existing` when it's large enough to hold `length` elements, otherwise
+ * allocates a fresh typed array via `Ctor`. Lets consumers keep one ref per
+ * pool and short-circuit growth checks inline.
+ */
+export function ensurePool(existing, length, Ctor) {
+  if (existing != null && existing.length >= length) {
+    return existing;
+  }
+  return new Ctor(length);
+}
+/**
+ * Compiles vertex + fragment shaders, attaches them, links the program, and returns
+ * both the program and its shaders. Logs link/compile diagnostics in dev when linking fails.
+ */
+export function linkProgram(gl, vertexShaderSource, fragmentShaderSource) {
+  const program = gl.createProgram();
+  const vertexShader = compileShader(gl, vertexShaderSource, gl.VERTEX_SHADER);
+  const fragmentShader = compileShader(gl, fragmentShaderSource, gl.FRAGMENT_SHADER);
+  gl.attachShader(program, vertexShader);
+  gl.attachShader(program, fragmentShader);
+  gl.linkProgram(program);
+  if (process.env.NODE_ENV !== 'production' && !gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    // WebGL best-practices: consult compile/link status only in dev mode
+    // https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL_best_practices#dont_check_shader_compile_status_unless_linking_fails
+    console.error(`Program linking failed: ${gl.getProgramInfoLog(program)}`);
+    console.error(`Vertex shader info-log: ${gl.getShaderInfoLog(vertexShader)}`);
+    console.error(`Fragment shader info-log: ${gl.getShaderInfoLog(fragmentShader)}`);
+  }
+  return {
+    program,
+    shaders: [vertexShader, fragmentShader]
+  };
 }