@mui/x-charts-premium 9.6.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/internals/plugins/allPlugins.d.mts

@@ -1,5 +1,5 @@
-import { type ChartSeriesType, type ConvertSignaturesIntoPlugins, type UseChartCartesianAxisSignature, type UseChartTooltipSignature, type UseChartInteractionSignature, type UseChartZAxisSignature, type UseChartHighlightSignature, type UseChartPolarAxisSignature, type UseChartBrushSignature, type UseChartVisibilityManagerSignature, type UseProgressiveRenderingSignature } from '@mui/x-charts/internals';
-import { type UseChartProExportSignature, type UseChartProZoomSignature } from '@mui/x-charts-pro/plugins';
+import type { ChartSeriesType, ConvertSignaturesIntoPlugins, UseChartCartesianAxisSignature, UseChartTooltipSignature, UseChartInteractionSignature, UseChartZAxisSignature, UseChartHighlightSignature, UseChartPolarAxisSignature, UseChartBrushSignature, UseChartVisibilityManagerSignature, UseProgressiveRenderingSignature } from '@mui/x-charts/internals';
+import type { UseChartProExportSignature, UseChartProZoomSignature } from '@mui/x-charts-pro/plugins';
 export type AllPluginSignatures<SeriesType extends ChartSeriesType = ChartSeriesType> = [UseChartZAxisSignature, UseChartBrushSignature, UseChartTooltipSignature<SeriesType>, UseChartInteractionSignature, UseChartCartesianAxisSignature<SeriesType>, UseChartPolarAxisSignature<SeriesType>, UseChartHighlightSignature<SeriesType>, UseChartVisibilityManagerSignature<SeriesType>, UseChartProZoomSignature, UseChartProExportSignature, UseProgressiveRenderingSignature];
 export type AllPluginsType<SeriesType extends ChartSeriesType = ChartSeriesType> = ConvertSignaturesIntoPlugins<AllPluginSignatures<SeriesType>>;
 export declare const ALL_PLUGINS: (import("@mui/x-charts/internals").ChartPlugin<UseChartZAxisSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartBrushSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartInteractionSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartProZoomSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartProExportSignature> | import("@mui/x-charts/internals").ChartPlugin<UseProgressiveRenderingSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartTooltipSignature<any>> | import("@mui/x-charts/internals").ChartPlugin<UseChartCartesianAxisSignature<any>> | import("@mui/x-charts/internals").ChartPlugin<UseChartPolarAxisSignature<any>> | import("@mui/x-charts/internals").ChartPlugin<UseChartHighlightSignature<any>> | import("@mui/x-charts/internals").ChartPlugin<UseChartVisibilityManagerSignature<any>>)[];

package/internals/plugins/allPlugins.d.ts

@@ -1,5 +1,5 @@
-import { type ChartSeriesType, type ConvertSignaturesIntoPlugins, type UseChartCartesianAxisSignature, type UseChartTooltipSignature, type UseChartInteractionSignature, type UseChartZAxisSignature, type UseChartHighlightSignature, type UseChartPolarAxisSignature, type UseChartBrushSignature, type UseChartVisibilityManagerSignature, type UseProgressiveRenderingSignature } from '@mui/x-charts/internals';
-import { type UseChartProExportSignature, type UseChartProZoomSignature } from '@mui/x-charts-pro/plugins';
+import type { ChartSeriesType, ConvertSignaturesIntoPlugins, UseChartCartesianAxisSignature, UseChartTooltipSignature, UseChartInteractionSignature, UseChartZAxisSignature, UseChartHighlightSignature, UseChartPolarAxisSignature, UseChartBrushSignature, UseChartVisibilityManagerSignature, UseProgressiveRenderingSignature } from '@mui/x-charts/internals';
+import type { UseChartProExportSignature, UseChartProZoomSignature } from '@mui/x-charts-pro/plugins';
 export type AllPluginSignatures<SeriesType extends ChartSeriesType = ChartSeriesType> = [UseChartZAxisSignature, UseChartBrushSignature, UseChartTooltipSignature<SeriesType>, UseChartInteractionSignature, UseChartCartesianAxisSignature<SeriesType>, UseChartPolarAxisSignature<SeriesType>, UseChartHighlightSignature<SeriesType>, UseChartVisibilityManagerSignature<SeriesType>, UseChartProZoomSignature, UseChartProExportSignature, UseProgressiveRenderingSignature];
 export type AllPluginsType<SeriesType extends ChartSeriesType = ChartSeriesType> = ConvertSignaturesIntoPlugins<AllPluginSignatures<SeriesType>>;
 export declare const ALL_PLUGINS: (import("@mui/x-charts/internals").ChartPlugin<UseChartZAxisSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartBrushSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartInteractionSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartProZoomSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartProExportSignature> | import("@mui/x-charts/internals").ChartPlugin<UseProgressiveRenderingSignature> | import("@mui/x-charts/internals").ChartPlugin<UseChartTooltipSignature<any>> | import("@mui/x-charts/internals").ChartPlugin<UseChartCartesianAxisSignature<any>> | import("@mui/x-charts/internals").ChartPlugin<UseChartPolarAxisSignature<any>> | import("@mui/x-charts/internals").ChartPlugin<UseChartHighlightSignature<any>> | import("@mui/x-charts/internals").ChartPlugin<UseChartVisibilityManagerSignature<any>>)[];

package/internals/plugins/useGeoProjection/useGeoProjection.d.mts

@@ -1,3 +1,3 @@
 import type { ChartPlugin } from '@mui/x-charts/internals';
-import { type UseGeoProjectionSignature } from "./useGeoProjection.types.mjs";
+import type { UseGeoProjectionSignature } from "./useGeoProjection.types.mjs";
 export declare const useGeoProjection: ChartPlugin<UseGeoProjectionSignature>;

package/internals/plugins/useGeoProjection/useGeoProjection.d.ts

@@ -1,3 +1,3 @@
 import type { ChartPlugin } from '@mui/x-charts/internals';
-import { type UseGeoProjectionSignature } from "./useGeoProjection.types.js";
+import type { UseGeoProjectionSignature } from "./useGeoProjection.types.js";
 export declare const useGeoProjection: ChartPlugin<UseGeoProjectionSignature>;

package/internals/plugins/useGeoProjection/useGeoProjection.types.d.mts

@@ -1,2 +1,2 @@
-import { type useGeoProjectionTypes } from '@mui/x-charts/internals';
+import type { useGeoProjectionTypes } from '@mui/x-charts/internals';
 export type UseGeoProjectionSignature = useGeoProjectionTypes.UseGeoProjectionSignature;

package/internals/plugins/useGeoProjection/useGeoProjection.types.d.ts

@@ -1,2 +1,2 @@
-import { type useGeoProjectionTypes } from '@mui/x-charts/internals';
+import type { useGeoProjectionTypes } from '@mui/x-charts/internals';
 export type UseGeoProjectionSignature = useGeoProjectionTypes.UseGeoProjectionSignature;

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/models/seriesType/ohlc.d.mts

@@ -1,6 +1,6 @@
 import type { ChartsColor } from '@mui/x-charts/colorPalettes';
-import { type CommonSeriesType, type CartesianSeriesType, type SeriesId, type CommonDefaultizedProps, type DatasetElementType } from '@mui/x-charts/internals';
-import { type DefaultizedProps } from '@mui/x-internals/types';
+import type { CommonSeriesType, CartesianSeriesType, SeriesId, CommonDefaultizedProps, DatasetElementType } from '@mui/x-charts/internals';
+import type { DefaultizedProps } from '@mui/x-internals/types';
 /**
  * Type representing the values of a single OHLC element.
  * The array contains four numbers in the following order:

package/models/seriesType/ohlc.d.ts

@@ -1,6 +1,6 @@
 import type { ChartsColor } from '@mui/x-charts/colorPalettes';
-import { type CommonSeriesType, type CartesianSeriesType, type SeriesId, type CommonDefaultizedProps, type DatasetElementType } from '@mui/x-charts/internals';
-import { type DefaultizedProps } from '@mui/x-internals/types';
+import type { CommonSeriesType, CartesianSeriesType, SeriesId, CommonDefaultizedProps, DatasetElementType } from '@mui/x-charts/internals';
+import type { DefaultizedProps } from '@mui/x-internals/types';
 /**
  * Type representing the values of a single OHLC element.
  * The array contains four numbers in the following order:

package/models/seriesType/rangeBar.d.mts

@@ -1,5 +1,5 @@
-import { type CartesianSeriesType, type CommonDefaultizedProps, type CommonSeriesType, type SeriesId, type DatasetElementType } from '@mui/x-charts/internals';
-import { type DefaultizedProps } from '@mui/x-internals/types';
+import type { CartesianSeriesType, CommonDefaultizedProps, CommonSeriesType, SeriesId, DatasetElementType } from '@mui/x-charts/internals';
+import type { DefaultizedProps } from '@mui/x-internals/types';
 /** [start, end] */
 export type RangeBarValueType = [number, number];
 export interface RangeBarSeriesType extends CommonSeriesType<'rangeBar'>, CartesianSeriesType {

package/models/seriesType/rangeBar.d.ts

@@ -1,5 +1,5 @@
-import { type CartesianSeriesType, type CommonDefaultizedProps, type CommonSeriesType, type SeriesId, type DatasetElementType } from '@mui/x-charts/internals';
-import { type DefaultizedProps } from '@mui/x-internals/types';
+import type { CartesianSeriesType, CommonDefaultizedProps, CommonSeriesType, SeriesId, DatasetElementType } from '@mui/x-charts/internals';
+import type { DefaultizedProps } from '@mui/x-internals/types';
 /** [start, end] */
 export type RangeBarValueType = [number, number];
 export interface RangeBarSeriesType extends CommonSeriesType<'rangeBar'>, CartesianSeriesType {

package/moduleAugmentation/rangeBarOnClick.d.mts

@@ -1,4 +1,4 @@
-import { type RangeBarValueType } from "../models/index.mjs";
+import type { RangeBarValueType } from "../models/index.mjs";
 declare module '@mui/x-charts/models' {
   interface ChartsTypeFeatureFlags {
     seriesValuesOverride: RangeBarValueType | number | null | undefined;

package/moduleAugmentation/rangeBarOnClick.d.ts

@@ -1,4 +1,4 @@
-import { type RangeBarValueType } from "../models/index.js";
+import type { RangeBarValueType } from "../models/index.js";
 declare module '@mui/x-charts/models' {
   interface ChartsTypeFeatureFlags {
     seriesValuesOverride: RangeBarValueType | number | null | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/x-charts-premium",
-  "version": "9.6.0",
+  "version": "9.8.0",
   "author": "MUI Team",
   "description": "The Premium plan edition of the MUI X Charts components.",
   "license": "SEE LICENSE IN LICENSE",
@@ -28,14 +28,14 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.29.7",
-    "@mui/utils": "^9.0.1",
+    "@mui/utils": "^9.1.1",
     "clsx": "^2.1.1",
     "prop-types": "^15.8.1",
-    "@mui/x-charts": "^9.6.0",
-    "@mui/x-license": "^9.6.0",
-    "@mui/x-internals": "^9.6.0",
     "@mui/x-charts-vendor": "^9.4.0",
-    "@mui/x-charts-pro": "^9.6.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/plugins/selectors/useChartCandlestickPosition.selectors.d.mts

@@ -1,4 +1,4 @@
-import { type OHLCItemIdentifier } from "../../models/index.mjs";
+import type { OHLCItemIdentifier } from "../../models/index.mjs";
 export declare const selectorCandlestickItemAtPosition: (args_0: import("@mui/x-charts/internals/plugins/corePlugins/useChartId/useChartId.types").UseChartIdState & import("@mui/x-charts/internals/plugins/corePlugins/useChartSeriesConfig/useChartSeriesConfig.types").UseChartSeriesConfigState<keyof import("@mui/x-charts/internals").ChartsSeriesConfig> & import("@mui/x-charts/internals/plugins/corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types").UseChartExperimentalFeaturesState & import("@mui/x-charts/internals/plugins/corePlugins/useChartDimensions/useChartDimensions.types").UseChartDimensionsState & import("@mui/x-charts/internals/plugins/corePlugins/useChartSeries/useChartSeries.types").UseChartSeriesState<keyof import("@mui/x-charts/internals").ChartsSeriesConfig> & import("@mui/x-charts/internals/plugins/corePlugins/useChartAnimation/useChartAnimation.types").UseChartAnimationState & import("@mui/x-charts/internals").UseChartInteractionListenerState & Partial<{}> & {
   cacheKey: import("@mui/x-charts/internals").ChartStateCacheKey;
 }, svgPoint: Pick<DOMPoint, "y" | "x">) => OHLCItemIdentifier | undefined;

package/plugins/selectors/useChartCandlestickPosition.selectors.d.ts

@@ -1,4 +1,4 @@
-import { type OHLCItemIdentifier } from "../../models/index.js";
+import type { OHLCItemIdentifier } from "../../models/index.js";
 export declare const selectorCandlestickItemAtPosition: (args_0: import("@mui/x-charts/internals/plugins/corePlugins/useChartId/useChartId.types").UseChartIdState & import("@mui/x-charts/internals/plugins/corePlugins/useChartSeriesConfig/useChartSeriesConfig.types").UseChartSeriesConfigState<keyof import("@mui/x-charts/internals").ChartsSeriesConfig> & import("@mui/x-charts/internals/plugins/corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types").UseChartExperimentalFeaturesState & import("@mui/x-charts/internals/plugins/corePlugins/useChartDimensions/useChartDimensions.types").UseChartDimensionsState & import("@mui/x-charts/internals/plugins/corePlugins/useChartSeries/useChartSeries.types").UseChartSeriesState<keyof import("@mui/x-charts/internals").ChartsSeriesConfig> & import("@mui/x-charts/internals/plugins/corePlugins/useChartAnimation/useChartAnimation.types").UseChartAnimationState & import("@mui/x-charts/internals").UseChartInteractionListenerState & Partial<{}> & {
   cacheKey: import("@mui/x-charts/internals").ChartStateCacheKey;
 }, svgPoint: Pick<DOMPoint, "y" | "x">) => OHLCItemIdentifier | undefined;

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;