gladly-plot 0.0.5 → 0.0.7

package/src/core/Plot.js

@@ -1,7 +1,7 @@
-import reglInit from "regl"
-import * as d3 from "d3-selection"
-import { AXES, AxisRegistry } from "../axes/AxisRegistry.js"
-import { Axis } from "../axes/Axis.js"
+import { AXES, AXES_2D, AXIS_GEOMETRY, AxisRegistry } from "../axes/AxisRegistry.js"
+import { Camera } from "../axes/Camera.js"
+import { TickLabelAtlas } from "../axes/TickLabelAtlas.js"
+import { mat4Identity, mat4Multiply } from "../math/mat4.js"
 import { ColorAxisRegistry } from "../axes/ColorAxisRegistry.js"
 import { FilterAxisRegistry } from "../axes/FilterAxisRegistry.js"
 import { ZoomController } from "../axes/ZoomController.js"
@@ -9,14 +9,76 @@ import { getLayerType, getRegisteredLayerTypes } from "./LayerTypeRegistry.js"
 import { getAxisQuantityKind, getScaleTypeFloat } from "../axes/AxisQuantityKindRegistry.js"
 import { getRegisteredColorscales, getRegistered2DColorscales } from "../colorscales/ColorscaleRegistry.js"
 import { Float } from "../floats/Float.js"
-
-function buildPlotSchema(data) {
+import { computationSchema, buildTransformSchema, getComputedData } from "../compute/ComputationRegistry.js"
+import { DataGroup, normalizeData } from "../data/Data.js"
+import { enqueueRegl, compileEnqueuedShaders } from "./ShaderQueue.js"
+import { GlBase } from "./GlBase.js"
+
+// If a single compute step (ComputedData refresh or TextureColumn refresh) takes
+// longer than this on the CPU, yield to the browser before the next step.
+// This prevents submitting an unbounded burst of GPU commands in one synchronous
+// block, which can trigger the Windows TDR watchdog (~2 s GPU timeout).
+const TDR_STEP_MS = 500
+
+// Throttle linked-plot renders when the source plot's "blocked lag" is high.
+// Blocked lag = max(0, RAF_wait - own_render_time): high when other plots' renders
+// are delaying the source's frames, but near zero for fast plots (colorbars, filterbars).
+const LINK_THROTTLE_MS      = 150   // ms between renders of a throttled linked plot
+const BLOCKED_LAG_THRESHOLD = 30    // ms: throttle kicks in above this blocked lag
+const BLOCKED_LAG_ALPHA     = 0.5   // EMA weight — reacts within ~2 samples
+
+function buildPlotSchema(data, config) {
   const layerTypes = getRegisteredLayerTypes()
+  // Normalise once — always a DataGroup (or null). Columns are e.g. "input.x1".
+  const wrappedData = normalizeData(data)
+
+  // Build fullSchemaData: the normalised DataGroup plus lightweight stubs for each
+  // declared transform so that layer schemas enumerate transform output columns.
+  // Stubs only need columns() — getData/getQuantityKind/getDomain return null (schema only).
+  const transforms = config?.transforms ?? []
+  let fullSchemaData = wrappedData
+  if (wrappedData && transforms.length > 0) {
+    const group = new DataGroup({})
+    group._children = { ...wrappedData._children }
+    for (const { name, transform: spec } of transforms) {
+      const entries = Object.entries(spec)
+      if (entries.length !== 1) continue
+      const [className] = entries[0]
+      const cd = getComputedData(className)
+      if (!cd) continue
+      group._children[name] = {
+        columns: () => cd.columns(),
+        getData: () => null,
+        getQuantityKind: () => null,
+        getDomain: () => null,
+      }
+    }
+    fullSchemaData = group
+  }
+
+  const { '$defs': compDefs } = computationSchema(fullSchemaData)
+
+  // wrappedData is already the correctly-shaped DataGroup (columns "input.x1" etc.)
+  const { '$defs': transformDefs } = buildTransformSchema(wrappedData)
 
   return {
     $schema: "https://json-schema.org/draft/2020-12/schema",
+    $defs: { ...compDefs, ...transformDefs },
     type: "object",
     properties: {
+      transforms: {
+        type: "array",
+        description: "Named data transforms applied before layers. Each item is a { name, transform: { ClassName: params } } object.",
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            transform: { '$ref': '#/$defs/transform_expression' }
+          },
+          required: ["name", "transform"],
+          additionalProperties: false
+        }
+      },
       layers: {
         type: "array",
         items: {
@@ -26,7 +88,7 @@ function buildPlotSchema(data) {
             return {
               title: typeName,
               properties: {
-                [typeName]: layerType.schema(data)
+                [typeName]: layerType.schema(fullSchemaData)
               },
               required: [typeName],
               additionalProperties: false
@@ -127,7 +189,7 @@ function buildPlotSchema(data) {
   }
 }
 
-export class Plot {
+export class Plot extends GlBase {
   // Registry of float factories keyed by type name.
   // Each entry: { factory(parentPlot, container, opts) → widget, defaultSize(opts) → {width,height} }
   // Populated by Colorbar.js, Filterbar.js, Colorbar2d.js at module load time.
@@ -138,6 +200,7 @@ export class Plot {
   }
 
   constructor(container, { margin } = {}) {
+    super()
     this.container = container
     this.margin = margin ?? { top: 60, right: 60, bottom: 60, left: 60 }
 
@@ -147,33 +210,31 @@ export class Plot {
     this.canvas.style.position = 'absolute'
     this.canvas.style.top = '0'
     this.canvas.style.left = '0'
-    this.canvas.style.zIndex = '1'
     container.appendChild(this.canvas)
 
-    // Create SVG element
-    this.svg = d3.select(container)
-      .append('svg')
-      .style('position', 'absolute')
-      .style('top', '0')
-      .style('left', '0')
-      .style('z-index', '2')
-      .style('user-select', 'none')
-
     this.currentConfig = null
-    this.currentData = null
-    this.regl = null
+    this._lastRawDataArg = undefined
     this.layers = []
     this.axisRegistry = null
     this.colorAxisRegistry = null
-    this.filterAxisRegistry = null
     this._renderCallbacks = new Set()
     this._zoomEndCallbacks = new Set()
     this._dirty = false
     this._rafId = null
-
-    // Stable Axis instances keyed by axis name — persist across update() calls
-    this._axisCache = new Map()
-    this._axesProxy = null
+    this._rendering = false
+    this._lastRenderEnd = performance.now()
+    this._throttleTimerId = null
+    this._pendingSourcePlot = null   // source plot of pending linked render (for throttle check)
+    this._blockedLag = 0             // EMA of (RAF wait - own render time); high when blocked by others
+    this._is3D = false
+    this._camera = null
+    this._tickLabelAtlas = null
+    this._axisLineCmd = null
+    this._axisBillboardCmd = null
+
+    // Compiled regl draw commands keyed by vert+frag shader source.
+    // Persists across update() calls so shader recompilation is avoided.
+    this._shaderCache = new Map()
 
     // Auto-managed Float widgets keyed by a config-derived tag string.
     // Covers 1D colorbars, 2D colorbars, and filterbars in a single unified Map.
@@ -182,85 +243,86 @@ export class Plot {
     this._setupResizeObserver()
   }
 
-  update({ config, data } = {}) {
-    const previousConfig = this.currentConfig
-    const previousData = this.currentData
+  // Stores new config/data and re-initialises the plot. No link validation.
+  // Called directly by PlotGroup so it can validate all plots together after
+  // all have been updated.
+  async _applyUpdate({ config, data } = {}) {
+    if (config !== undefined) this.currentConfig = config
+    if (data !== undefined) {
+      this._rawData = normalizeData(data)  // normalise once; kept immutable
+    }
 
-    try {
-      if (config !== undefined) {
-        this.currentConfig = config
-      }
-      if (data !== undefined) {
-        this.currentData = data
-      }
+    if (!this.currentConfig || !this._rawData) return
 
-      if (!this.currentConfig || !this.currentData) {
-        return
-      }
+    const width = this.container.clientWidth
+    const height = this.container.clientHeight
+    const plotWidth = width - this.margin.left - this.margin.right
+    const plotHeight = height - this.margin.top - this.margin.bottom
 
-      const width = this.container.clientWidth
-      const height = this.container.clientHeight
-      const plotWidth = width - this.margin.left - this.margin.right
-      const plotHeight = height - this.margin.top - this.margin.bottom
+    // Container is hidden, not yet laid out, or too small to fit the margins.
+    // Store config/data and return; ResizeObserver will call forceUpdate() once
+    // the container gets real dimensions.
+    if (width === 0 || height === 0 || plotWidth <= 0 || plotHeight <= 0) return
 
-      // Container is hidden, not yet laid out, or too small to fit the margins.
-      // Store config/data and return; ResizeObserver will call forceUpdate() once
-      // the container gets real dimensions.
-      if (width === 0 || height === 0 || plotWidth <= 0 || plotHeight <= 0) {
-        return
-      }
+    this.canvas.width = width
+    this.canvas.height = height
+
+    this.width = width
+    this.height = height
+    this.plotWidth = plotWidth
+    this.plotHeight = plotHeight
 
-      this.canvas.width = width
-      this.canvas.height = height
-      this.svg.attr('width', width).attr('height', height)
+    this._warnedMissingDomains = false
+    await this._initialize()
+    this._syncFloats()
+  }
 
-      this.width = width
-      this.height = height
-      this.plotWidth = plotWidth
-      this.plotHeight = plotHeight
+  // Validates that all axes on this plot that are linked to axes on other plots
+  // still share the same quantity kind. Throws if any mismatch is found.
+  _validateLinks() {
+    for (const [name, axis] of this._axisCache) {
+      const qk = axis.quantityKind
+      if (!qk) continue
+      for (const other of axis._linkedAxes) {
+        const otherQk = other.quantityKind
+        if (otherQk && otherQk !== qk) {
+          throw new Error(
+            `Axis '${name}' (quantity kind '${qk}') is linked to axis '${other._name}' ` +
+            `with incompatible quantity kind '${otherQk}'. ` +
+            `Unlink the axes before changing their quantity kinds, or update both plots atomically via PlotGroup.`
+          )
+        }
+      }
+    }
+  }
 
-      if (this.regl) {
-        this.regl.destroy()
+  async update({ config, data } = {}) {
+    // Skip expensive _initialize() if nothing actually changed.
+    if (config !== undefined || data !== undefined) {
+      const configSame = config === undefined || JSON.stringify(config) === JSON.stringify(this.currentConfig)
+      const dataSame   = data  === undefined || data === this._lastRawDataArg
+      if (configSame && dataSame) {
+        this.scheduleRender()
+        return
       }
+    }
 
-      this.svg.selectAll('*').remove()
+    if (data !== undefined) this._lastRawDataArg = data
 
-      this._initialize()
-      this._syncFloats()
+    const previousConfig = this.currentConfig
+    const previousRawData = this._rawData
+    try {
+      await this._applyUpdate({ config, data })
+      this._validateLinks()
     } catch (error) {
       this.currentConfig = previousConfig
-      this.currentData = previousData
+      this._rawData = previousRawData
       throw error
     }
   }
 
-  forceUpdate() {
-    this.update({})
-  }
-
-  /**
-   * Returns a stable Axis instance for the given axis name.
-   * Works for spatial axes (e.g. "xaxis_bottom") and quantity-kind axes (color/filter).
-   * The same instance is returned across plot.update() calls, so links survive updates.
-   *
-   * Usage: plot.axes.xaxis_bottom, plot.axes["velocity_ms"], etc.
-   */
-  get axes() {
-    if (!this._axesProxy) {
-      this._axesProxy = new Proxy(this._axisCache, {
-        get: (cache, name) => {
-          if (typeof name !== 'string') return undefined
-          if (!cache.has(name)) cache.set(name, new Axis(this, name))
-          return cache.get(name)
-        }
-      })
-    }
-    return this._axesProxy
-  }
-
-  _getAxis(name) {
-    if (!this._axisCache.has(name)) this._axisCache.set(name, new Axis(this, name))
-    return this._axisCache.get(name)
+  async forceUpdate() {
+    await this.update({})
   }
 
   getConfig() {
@@ -271,7 +333,7 @@ export class Plot {
         const scale = this.axisRegistry.getScale(axisId)
         if (scale) {
           const [min, max] = scale.domain()
-          const qk = this.axisRegistry.axisQuantityKinds[axisId]
+          const qk    = this.axisRegistry.axisQuantityKinds[axisId]
           const qkDef = qk ? getAxisQuantityKind(qk) : {}
           axes[axisId] = { ...qkDef, ...(axes[axisId] ?? {}), min, max }
         }
@@ -307,38 +369,64 @@ export class Plot {
       }
     }
 
-    return { colorbars: [], ...this.currentConfig, axes}
+    return { transforms: [], colorbars: [], ...this.currentConfig, axes}
   }
 
-  _initialize() {
-    const { layers = [], axes = {}, colorbars = [] } = this.currentConfig
-
-    this.regl = reglInit({
-      canvas: this.canvas,
-      extensions: [
-        'ANGLE_instanced_arrays',
-        'OES_texture_float',
-        'OES_texture_float_linear',
-      ],
-      optionalExtensions: [
-        // WebGL1: render to float framebuffers (needed by compute passes)
-        'WEBGL_color_buffer_float',
-        // WebGL2: render to float framebuffers (standard but must be opted in)
-        'EXT_color_buffer_float',
-      ]
-    })
+  async _initialize() {
+    const epoch = ++this._initEpoch
+    const { layers = [], axes = {}, colorbars = [], transforms = [] } = this.currentConfig
 
-    this.layers = []
+    if (!this.regl) {
+      this._initRegl(this.canvas)
+    } else {
+      // Notify regl of any canvas dimension change so its internal state stays
+      // consistent (e.g. default framebuffer size used by regl.clear).
+      this.regl.poll()
+    }
 
-    AXES.forEach(a => this.svg.append("g").attr("class", a))
+    // Destroy GPU buffers owned by the previous layer set before rebuilding.
+    for (const layer of this.layers) {
+      for (const buf of Object.values(layer._bufferProps ?? {})) {
+        if (buf && typeof buf.destroy === 'function') buf.destroy()
+      }
+    }
+
+    this.layers = []
+    this._dataTransformNodes = []
+
+    // Restore original user data before applying transforms (handles re-initialization).
+    // Create a fresh shallow copy of _rawData's children so _rawData is never mutated
+    // and transform nodes from previous runs don't carry over.
+    if (this._rawData != null) {
+      const fresh = new DataGroup({})
+      fresh._children = { ...this._rawData._children }
+      this.currentData = fresh
+    }
 
     this.axisRegistry = new AxisRegistry(this.plotWidth, this.plotHeight)
     this.colorAxisRegistry = new ColorAxisRegistry()
     this.filterAxisRegistry = new FilterAxisRegistry()
 
-    this._processLayers(layers, this.currentData)
+    await this._processTransforms(transforms, epoch)
+    if (this._initEpoch !== epoch) return
+    await this._processLayers(layers, this.currentData, epoch)
+    if (this._initEpoch !== epoch) return
     this._setDomains(axes)
 
+    // Detect 3D mode: any axis outside the 4 standard 2D positions has a scale.
+    this._is3D = AXES.some(a => !AXES_2D.includes(a) && this.axisRegistry.getScale(a) !== null)
+
+    // Camera (recreated each _initialize so aspect ratio and 3D flag stay in sync).
+    this._camera = new Camera(this._is3D)
+    this._camera.resize(this.plotWidth, this.plotHeight)
+
+    // Shared atlas for tick and title labels.
+    if (this._tickLabelAtlas) this._tickLabelAtlas.destroy()
+    this._tickLabelAtlas = new TickLabelAtlas(this.regl)
+
+    // Compile shared axis draw commands (once per regl context; cached on Plot).
+    if (!this._axisLineCmd) this._initAxisCommands()
+
     // Apply colorscale overrides from top-level colorbars entries. These override any
     // per-axis colorscale from config.axes or quantity kind registry. Applying after
     // _setDomains ensures they take effect last. For 2D colorbars both axes receive the
@@ -351,8 +439,108 @@ export class Plot {
       if (entry.yAxis) this.colorAxisRegistry.ensureColorAxis(entry.yAxis, entry.colorscale)
     }
 
-    new ZoomController(this)
-    this.render()
+    if (!this._zoomController) this._zoomController = new ZoomController(this)
+    this.scheduleRender()
+  }
+
+  // Compile the two regl commands shared across all axis rendering.
+  // Called once after the first regl context is created.
+  _initAxisCommands() {
+    const regl = this.regl
+
+    // Axis lines and tick marks (simple 3D line segments).
+    this._axisLineCmd = regl({
+      vert: `#version 300 es
+precision highp float;
+in vec3 a_position;
+uniform mat4 u_mvp;
+void main() { gl_Position = u_mvp * vec4(a_position, 1.0); }`,
+      frag: `#version 300 es
+precision highp float;
+uniform vec4 u_color;
+out vec4 fragColor;
+void main() { fragColor = u_color; }`,
+      attributes: { a_position: regl.prop('positions') },
+      uniforms: {
+        u_mvp:   regl.prop('mvp'),
+        u_color: regl.prop('color'),
+      },
+      primitive: 'lines',
+      count:     regl.prop('count'),
+      viewport:  regl.prop('viewport'),
+      depth: {
+        enable: regl.prop('depthEnable'),
+        mask:   true,
+      },
+    })
+
+    // Billboard quads for tick labels and axis titles.
+    // a_anchor:    vec3 — label centre in model space
+    // a_offset_px: vec2 — corner offset in HTML pixels (x right, y down)
+    // a_uv:        vec2 — atlas UV (v=0 = canvas top)
+    this._axisBillboardCmd = regl({
+      vert: `#version 300 es
+precision highp float;
+in vec3 a_anchor;
+in vec2 a_offset_px;
+in vec2 a_uv;
+uniform mat4 u_mvp;
+uniform vec2 u_canvas_size;
+out vec2 v_uv;
+void main() {
+  vec4 clip = u_mvp * vec4(a_anchor, 1.0);
+  // Project anchor from NDC to HTML-pixel space (x right, y down).
+  vec2 ndc_anchor = clip.xy / clip.w;
+  vec2 anchor_px  = vec2(
+     ndc_anchor.x * 0.5 + 0.5,
+    -ndc_anchor.y * 0.5 + 0.5) * u_canvas_size;
+  // a_offset_px is in HTML pixels (x right, y down).
+  // abs(a_offset_px) = (hw, hh) for every corner; top-left = anchor - (hw, hh).
+  // Snap the top-left corner to an integer pixel with floor() so that
+  // each pixel maps to exactly one atlas texel and the label is never
+  // shifted right by the round-half-up behaviour of round().
+  vec2 hw_vec  = abs(a_offset_px);
+  vec2 tl_px   = floor(anchor_px - hw_vec);    // snap top-left (always left)
+  vec2 vert_px = tl_px + hw_vec + a_offset_px; // reconstruct this corner
+  // Convert HTML pixels back to NDC.
+  vec2 ndc = vec2(
+     vert_px.x / u_canvas_size.x * 2.0 - 1.0,
+    -(vert_px.y / u_canvas_size.y * 2.0 - 1.0));
+  gl_Position = vec4(ndc, clip.z / clip.w, 1.0);
+  v_uv = a_uv;
+}`,
+      frag: `#version 300 es
+precision highp float;
+uniform sampler2D u_atlas;
+in vec2 v_uv;
+out vec4 fragColor;
+void main() {
+  ivec2 tc = ivec2(v_uv * vec2(textureSize(u_atlas, 0)));
+  fragColor = texelFetch(u_atlas, tc, 0);
+  if (fragColor.a < 0.05) discard;
+}`,
+      attributes: {
+        a_anchor:    regl.prop('anchors'),
+        a_offset_px: regl.prop('offsetsPx'),
+        a_uv:        regl.prop('uvs'),
+      },
+      uniforms: {
+        u_mvp:         regl.prop('mvp'),
+        u_canvas_size: regl.prop('canvasSize'),
+        u_atlas:       regl.prop('atlas'),
+      },
+      primitive: 'triangles',
+      count:     regl.prop('count'),
+      viewport:  regl.prop('viewport'),
+      depth: {
+        enable: regl.prop('depthEnable'),
+        mask:   false,   // depth test but don't write — labels don't occlude each other
+      },
+      blend: {
+        enable: true,
+        func: { srcRGB: 'src alpha', dstRGB: 'one minus src alpha', srcAlpha: 0, dstAlpha: 1 },
+      },
+    })
   }
 
   _setupResizeObserver() {
@@ -361,11 +549,23 @@ export class Plot {
         // Defer to next animation frame so the ResizeObserver callback exits
         // before any DOM/layout changes happen, avoiding the "loop completed
         // with undelivered notifications" browser error.
-        requestAnimationFrame(() => this.forceUpdate())
+        requestAnimationFrame(async () => {
+          try {
+            await this.forceUpdate()
+          } catch (e) {
+            console.error('[gladly] Error during resize-triggered update():', e)
+          }
+        })
       })
       this.resizeObserver.observe(this.container)
     } else {
-      this._resizeHandler = () => this.forceUpdate()
+      this._resizeHandler = async () => {
+        try {
+          await this.forceUpdate()
+        } catch (e) {
+          console.error('[gladly] Error during resize-triggered update():', e)
+        }
+      }
       window.addEventListener('resize', this._resizeHandler)
     }
   }
@@ -373,7 +573,7 @@ export class Plot {
   // Returns the quantity kind for any axis ID (spatial or color axis).
   // For color axes, the axis ID IS the quantity kind.
   getAxisQuantityKind(axisId) {
-    if (AXES.includes(axisId)) {
+    if (Object.prototype.hasOwnProperty.call(AXIS_GEOMETRY, axisId)) {
       return this.axisRegistry ? this.axisRegistry.axisQuantityKinds[axisId] : null
     }
     return axisId
@@ -381,7 +581,7 @@ export class Plot {
 
   // Unified domain getter for spatial, color, and filter axes.
   getAxisDomain(axisId) {
-    if (AXES.includes(axisId)) {
+    if (Object.prototype.hasOwnProperty.call(AXIS_GEOMETRY, axisId)) {
       const scale = this.axisRegistry?.getScale(axisId)
       return scale ? scale.domain() : null
     }
@@ -395,9 +595,16 @@ export class Plot {
 
   // Unified domain setter for spatial, color, and filter axes.
   setAxisDomain(axisId, domain) {
-    if (AXES.includes(axisId)) {
+    if (Object.prototype.hasOwnProperty.call(AXIS_GEOMETRY, axisId)) {
       const scale = this.axisRegistry?.getScale(axisId)
-      if (scale) scale.domain(domain)
+      if (scale) {
+        scale.domain(domain)
+        // Keep currentConfig in sync so update() skips _initialize() when only domains changed.
+        if (this.currentConfig) {
+          const axes = this.currentConfig.axes ?? {}
+          this.currentConfig = { ...this.currentConfig, axes: { ...axes, [axisId]: { ...(axes[axisId] ?? {}), min: domain[0], max: domain[1] } } }
+        }
+      }
     } else if (this.colorAxisRegistry?.hasAxis(axisId)) {
       this.colorAxisRegistry.setRange(axisId, domain[0], domain[1])
     } else if (this.filterAxisRegistry?.hasAxis(axisId)) {
@@ -500,16 +707,24 @@ export class Plot {
       this._rafId = null
     }
 
+    if (this._tickLabelAtlas) {
+      this._tickLabelAtlas.destroy()
+      this._tickLabelAtlas = null
+    }
+
+    this._shaderCache.clear()
+
     if (this.regl) {
       this.regl.destroy()
+      this.regl = null
     }
 
     this._renderCallbacks.clear()
     this.canvas.remove()
-    this.svg.remove()
   }
 
-  _processLayers(layersConfig, data) {
+  async _processLayers(layersConfig, data, epoch) {
+    const TDR_STEP_MS = 500
     for (let configLayerIndex = 0; configLayerIndex < layersConfig.length; configLayerIndex++) {
       const layerSpec = layersConfig[configLayerIndex]
       const entries = Object.entries(layerSpec)
@@ -519,6 +734,7 @@ export class Plot {
 
       const [layerTypeName, parameters] = entries[0]
       const layerType = getLayerType(layerTypeName)
+      if (!layerType) throw new Error(`Unknown layer type '${layerTypeName}'`)
 
       // Resolve axis config once per layer spec for registration (independent of draw call count).
       const ac = layerType.resolveAxisConfig(parameters, data)
@@ -528,24 +744,112 @@ export class Plot {
       // Pass any scale override from config (e.g. "log") so the D3 scale is created correctly.
       if (ac.xAxis) this.axisRegistry.ensureAxis(ac.xAxis, ac.xAxisQuantityKind, axesConfig[ac.xAxis]?.scale ?? axesConfig[ac.xAxisQuantityKind]?.scale)
       if (ac.yAxis) this.axisRegistry.ensureAxis(ac.yAxis, ac.yAxisQuantityKind, axesConfig[ac.yAxis]?.scale ?? axesConfig[ac.yAxisQuantityKind]?.scale)
+      if (ac.zAxis) this.axisRegistry.ensureAxis(ac.zAxis, ac.zAxisQuantityKind, axesConfig[ac.zAxis]?.scale ?? axesConfig[ac.zAxisQuantityKind]?.scale)
 
       // Register color axes (colorscale comes from config or quantity kind registry, not from here)
-      for (const quantityKind of ac.colorAxisQuantityKinds) {
+      for (const quantityKind of Object.values(ac.colorAxisQuantityKinds)) {
         this.colorAxisRegistry.ensureColorAxis(quantityKind)
       }
 
       // Register filter axes
-      for (const quantityKind of ac.filterAxisQuantityKinds) {
+      for (const quantityKind of Object.values(ac.filterAxisQuantityKinds)) {
         this.filterAxisRegistry.ensureFilterAxis(quantityKind)
       }
 
       // Create one draw command per GPU config returned by the layer type.
-      for (const layer of layerType.createLayer(parameters, data)) {
+      let gpuLayers
+      try {
+        gpuLayers = await layerType.createLayer(this.regl, parameters, data, this)
+      } catch (e) {
+        throw new Error(`Layer '${layerTypeName}' (index ${configLayerIndex}) failed to create: ${e.message}`, { cause: e })
+      }
+      if (this._initEpoch !== epoch) return
+      for (const layer of gpuLayers) {
         layer.configLayerIndex = configLayerIndex
-        layer.draw = layer.type.createDrawCommand(this.regl, layer, this)
+        const stepStart = performance.now()
+        try {
+          layer.draw = await this._compileLayerDraw(layer)
+        } catch (e) {
+          throw new Error(`Layer '${layerTypeName}' (index ${configLayerIndex}) failed to build draw command: ${e.message}`, { cause: e })
+        }
+        if (this._initEpoch !== epoch) return
+        if (performance.now() - stepStart > TDR_STEP_MS)
+          await new Promise(r => requestAnimationFrame(r))
+        if (this._initEpoch !== epoch) return
         this.layers.push(layer)
       }
     }
+    if (this._initEpoch !== epoch) return
+    compileEnqueuedShaders(this.regl)
+  }
+
+  async _compileLayerDraw(layer) {
+    const drawConfig = await layer.type.createDrawCommand(this.regl, layer, this)
+
+    // Layer types that fully override createDrawCommand (e.g. TileLayer) return
+    // a ready-to-call function instead of a plain drawConfig object. Pass through.
+    if (typeof drawConfig === 'function') return drawConfig
+
+    const shaderKey = drawConfig.vert + '\0' + drawConfig.frag
+
+    if (!this._shaderCache.has(shaderKey)) {
+      // Build a version of the draw config where all layer-specific data
+      // (attribute buffers and texture closures) is replaced with regl.prop()
+      // references. This compiled command can then be reused for any layer
+      // that produces the same shader source, regardless of its data.
+      const propAttrs = {}
+      for (const [key, val] of Object.entries(drawConfig.attributes)) {
+        const rawBuf = val?.buffer instanceof Float32Array ? val.buffer
+          : val instanceof Float32Array ? val : null
+        if (rawBuf !== null) {
+          const propKey = `attr_${key}`
+          const divisor = val?.divisor
+          propAttrs[key] = divisor !== undefined
+            ? { buffer: this.regl.prop(propKey), divisor }
+            : this.regl.prop(propKey)
+        } else {
+          propAttrs[key] = val
+        }
+      }
+
+      const propUniforms = {}
+      for (const [key, val] of Object.entries(drawConfig.uniforms)) {
+        propUniforms[key] = typeof val === 'function' ? this.regl.prop(key) : val
+      }
+
+      const propConfig = { ...drawConfig, attributes: propAttrs, uniforms: propUniforms }
+      this._shaderCache.set(shaderKey, enqueueRegl(this.regl, propConfig))
+    }
+
+    const cmd = this._shaderCache.get(shaderKey)
+
+    // Extract per-layer data: GPU buffers for Float32Array attributes,
+    // and texture closures for sampler uniforms.
+    const bufferProps = {}
+    for (const [key, val] of Object.entries(drawConfig.attributes)) {
+      const rawBuf = val?.buffer instanceof Float32Array ? val.buffer
+        : val instanceof Float32Array ? val : null
+      if (rawBuf !== null) {
+        bufferProps[`attr_${key}`] = this.regl.buffer(rawBuf)
+      }
+    }
+
+    const textureClosures = {}
+    for (const [key, val] of Object.entries(drawConfig.uniforms)) {
+      if (typeof val === 'function') textureClosures[key] = val
+    }
+
+    layer._bufferProps = bufferProps
+    layer._textureClosures = textureClosures
+
+    return (runtimeProps) => {
+      // Resolve texture closures at draw time so live texture swaps are picked up.
+      const textureProps = {}
+      for (const [key, fn] of Object.entries(textureClosures)) {
+        textureProps[key] = fn()
+      }
+      cmd({ ...bufferProps, ...textureProps, ...runtimeProps })
+    }
   }
 
   _setDomains(axesOverrides) {
@@ -561,26 +865,99 @@ export class Plot {
     return getScaleTypeFloat(quantityKind, this.currentConfig?.axes)
   }
 
-  static schema(data) {
-    return buildPlotSchema(data)
+  static schema(data, config) {
+    return buildPlotSchema(data, config)
   }
 
-  scheduleRender() {
+  scheduleRender(sourcePlot = null) {
+    if (!this.regl) return
     this._dirty = true
-    if (this._rafId === null) {
-      this._rafId = requestAnimationFrame(() => {
-        this._rafId = null
-        if (this._dirty) {
-          this._dirty = false
-          this.render()
-        }
-      })
+    // Track source plot — sticky until RAF is committed so timer/vsync re-entries
+    // can still check whether throttling is warranted.
+    if (sourcePlot) this._pendingSourcePlot = sourcePlot
+    if (this._rafId !== null || this._rendering || this._throttleTimerId !== null) return
+
+    // Throttle only when the source plot is being blocked by slow linked renders.
+    // blocked lag = RAF wait − own render time; near zero for fast plots (colorbars,
+    // filterbars) so those never throttle this plot's renders.
+    const source = this._pendingSourcePlot
+    if (source && source._blockedLag > BLOCKED_LAG_THRESHOLD) {
+      const delay = LINK_THROTTLE_MS - (performance.now() - this._lastRenderEnd)
+      if (delay > 0) {
+        this._throttleTimerId = setTimeout(() => {
+          this._throttleTimerId = null
+          if (this._dirty) this.scheduleRender()
+        }, delay)
+        return
+      }
     }
+    this._pendingSourcePlot = null  // commit: reset now that we're queuing the RAF
+
+    const schedTime = performance.now()
+    const _st0 = schedTime
+    setTimeout(() => {
+      const _stLag = performance.now() - _st0
+      if (_stLag > 20) console.warn(`[gladly] setTimeout(0) lag ${_stLag.toFixed(0)}ms`)
+    }, 0)
+    this._rafId = requestAnimationFrame(async (rafTime) => {
+      this._rafId = null
+      const now = performance.now()
+      const lag = now - schedTime
+      const postVsync = now - rafTime  // time from vsync to our callback executing
+      if (lag > 50) console.warn(`[gladly] RAF lag ${lag.toFixed(0)}ms  (vsync-to-callback: ${postVsync.toFixed(1)}ms)`)
+      if (this._dirty) {
+        this._dirty = false
+        const t0 = performance.now()
+        this._rendering = true
+        try {
+          await this.render()
+        } catch (e) {
+          console.error('[gladly] Error during render():', e)
+        } finally {
+          this._rendering = false
+        }
+        const dt = performance.now() - t0
+        if (dt > 10) console.warn(`[gladly] render ${dt.toFixed(0)}ms`)
+        // Update blocked-lag EMA: how long were we waiting for others vs rendering ourselves?
+        const blockedLag = Math.max(0, lag - dt)
+        this._blockedLag = this._blockedLag * (1 - BLOCKED_LAG_ALPHA) + blockedLag * BLOCKED_LAG_ALPHA
+        this._lastRenderEnd = performance.now()
+        // After submitting GPU work, hold _rafId so no new render can be queued
+        // until the compositor is ready for the next frame (browser waits for GPU).
+        // Any state changes that arrive during GPU execution are captured then.
+        this._rafId = requestAnimationFrame(() => {
+          this._rafId = null
+          if (this._dirty) this.scheduleRender()
+        })
+      }
+    })
   }
 
-  render() {
+  async render() {
     this._dirty = false
-    this.regl.clear({ color: [1,1,1,1], depth:1 })
+
+    // Validate axis domains once per render (warn only when domain is still
+    // the D3 default, i.e. was never set — indicates a missing ensureAxis call)
+    if (!this._warnedMissingDomains && this.axisRegistry) {
+      for (const axisId of AXES) {
+        const scale = this.axisRegistry.getScale(axisId)
+        if (!scale) continue
+        const [lo, hi] = scale.domain()
+        if (!isFinite(lo) || !isFinite(hi)) {
+          console.warn(
+            `[gladly] Axis '${axisId}': domain [${lo}, ${hi}] is non-finite at render time. ` +
+            `All data on this axis will be invisible.`
+          )
+          this._warnedMissingDomains = true
+        } else if (lo === hi) {
+          console.warn(
+            `[gladly] Axis '${axisId}': domain is degenerate [${lo}] at render time. ` +
+            `Data on this axis will collapse to a single line.`
+          )
+          this._warnedMissingDomains = true
+        }
+      }
+    }
     const viewport = {
       x: this.margin.left,
       y: this.margin.bottom,
@@ -589,18 +966,69 @@ export class Plot {
     }
     const axesConfig = this.currentConfig?.axes
 
+    // Camera MVP for data layers (maps unit cube to NDC within the plot-area viewport).
+    const cameraMvp = this._camera ? this._camera.getMVP() : mat4Identity()
+
+    // Axis MVP maps the unit cube to full-canvas NDC so axis lines and labels
+    // can extend into the margin area outside the plot viewport.
+    //   sx = plotWidth/width,  sy = plotHeight/height
+    //   cx = (marginLeft - marginRight) / width  (NDC centre offset x)
+    //   cy = (marginBottom - marginTop)  / height
+    const sx = this.plotWidth  / this.width
+    const sy = this.plotHeight / this.height
+    const cx = (this.margin.left   - this.margin.right)  / this.width
+    const cy = (this.margin.bottom - this.margin.top)    / this.height
+    // Column-major viewport scale+translate matrix
+    const Mvp = new Float32Array([
+      sx, 0, 0, 0,
+      0, sy, 0, 0,
+      0,  0, 1, 0,
+      cx, cy, 0, 1,
+    ])
+    const axisMvp = mat4Multiply(Mvp, cameraMvp)
+
+    // Phase 1 — async compute: refresh all transforms and data columns before touching the canvas.
+    // Any TDR-yield RAF pauses happen here while the previous frame is still visible.
+    // Yield between steps when a step is expensive to avoid triggering the Windows TDR watchdog.
+    for (const node of this._dataTransformNodes) {
+      const stepStart = performance.now()
+      try {
+        await node.refreshIfNeeded(this)
+      } catch (e) {
+        throw new Error(`Transform refresh failed: ${e.message}`, { cause: e })
+      }
+      if (performance.now() - stepStart > TDR_STEP_MS)
+        await new Promise(r => requestAnimationFrame(r))
+    }
+
     for (const layer of this.layers) {
-      if (layer._axisUpdaters) {
-        for (const updater of layer._axisUpdaters) updater.refreshIfNeeded(this)
+      for (const col of layer._dataColumns ?? []) {
+        const stepStart = performance.now()
+        await col.refresh(this)
+        if (performance.now() - stepStart > TDR_STEP_MS)
+          await new Promise(r => requestAnimationFrame(r))
       }
+    }
 
+    // Phase 2 — synchronous draw: all data is ready; clear once then draw every layer.
+    // No async yields from here to the end of render() so the canvas is never blank mid-frame.
+    this.regl.clear({ color: [1,1,1,1], depth:1 })
+
+    for (const layer of this.layers) {
       const xIsLog = layer.xAxis ? this.axisRegistry.isLogScale(layer.xAxis) : false
       const yIsLog = layer.yAxis ? this.axisRegistry.isLogScale(layer.yAxis) : false
+      const zIsLog = layer.zAxis ? this.axisRegistry.isLogScale(layer.zAxis) : false
+      const zScale = layer.zAxis ? this.axisRegistry.getScale(layer.zAxis) : null
+      const zDomain = zScale ? zScale.domain() : [0, 1]
       const props = {
         xDomain: layer.xAxis ? (this.axisRegistry.getScale(layer.xAxis)?.domain() ?? [0, 1]) : [0, 1],
         yDomain: layer.yAxis ? (this.axisRegistry.getScale(layer.yAxis)?.domain() ?? [0, 1]) : [0, 1],
+        zDomain,
         xScaleType: xIsLog ? 1.0 : 0.0,
         yScaleType: yIsLog ? 1.0 : 0.0,
+        zScaleType: zIsLog ? 1.0 : 0.0,
+        u_is3D:    this._is3D ? 1.0 : 0.0,
+        u_mvp:     cameraMvp,
         viewport: viewport,
         count: layer.vertexCount ?? Object.values(layer.attributes).find(v => v instanceof Float32Array)?.length ?? 0,
         u_pickingMode: 0.0,
@@ -611,22 +1039,54 @@ export class Plot {
         props.instances = layer.instanceCount
       }
 
-      for (const qk of layer.colorAxes) {
-        props[`colorscale_${qk}`] = this.colorAxisRegistry.getColorscaleIndex(qk)
+      // Warn once if this draw call will produce no geometry
+      if (!layer._warnedZeroCount && !layer.type?.suppressWarnings) {
+        const drawCount = props.instances ?? props.count
+        if (drawCount === 0) {
+          console.warn(
+            `[gladly] Layer '${layer.type?.name ?? 'unknown'}' (config index ${layer.configLayerIndex}): ` +
+            `draw count is 0 — nothing will be rendered`
+          )
+          layer._warnedZeroCount = true
+        }
+      }
+
+      for (const qk of Object.values(layer.colorAxes)) {
+        const pk = qk.replace(/\./g, '_')
+        props[`colorscale_${pk}`] = this.colorAxisRegistry.getColorscaleIndex(qk)
         const range = this.colorAxisRegistry.getRange(qk)
-        props[`color_range_${qk}`] = range ?? [0, 1]
-        props[`color_scale_type_${qk}`] = this._getScaleTypeFloat(qk)
+        props[`color_range_${pk}`] = range ?? [0, 1]
+        props[`color_scale_type_${pk}`] = this._getScaleTypeFloat(qk)
+        props[`alpha_blend_${pk}`] = this.colorAxisRegistry.getAlphaBlend(qk)
       }
 
-      for (const qk of layer.filterAxes) {
-        props[`filter_range_${qk}`] = this.filterAxisRegistry.getRangeUniform(qk)
-        props[`filter_scale_type_${qk}`] = this._getScaleTypeFloat(qk)
+      for (const qk of Object.values(layer.filterAxes)) {
+        const pk = qk.replace(/\./g, '_')
+        props[`filter_range_${pk}`] = this.filterAxisRegistry.getRangeUniform(qk)
+        props[`filter_scale_type_${pk}`] = this._getScaleTypeFloat(qk)
       }
 
       layer.draw(props)
     }
 
-    for (const axisId of AXES) this._getAxis(axisId).render()
+    // Render all registered spatial axes via WebGL (axis lines + tick marks + labels).
+    if (this._axisLineCmd && this._axisBillboardCmd && this._tickLabelAtlas) {
+      // Pre-pass: mark all labels needed this frame, then flush the atlas once.
+      for (const axisId of AXES) {
+        if (!this.axisRegistry.getScale(axisId)) continue
+        this._getAxis(axisId).prepareAtlas(this._tickLabelAtlas, axisMvp, this.width, this.height)
+      }
+      this._tickLabelAtlas.flush()
+
+      for (const axisId of AXES) {
+        if (!this.axisRegistry.getScale(axisId)) continue
+        this._getAxis(axisId).render(
+          this.regl, axisMvp, this.width, this.height,
+          this._is3D, this._tickLabelAtlas,
+          this._axisLineCmd, this._axisBillboardCmd,
+        )
+      }
+    }
     for (const cb of this._renderCallbacks) cb()
   }
 
@@ -663,19 +1123,33 @@ export class Plot {
     return { remove: () => window.removeEventListener(eventType, handler, { capture: true }) }
   }
 
-  pick(x, y) {
+  async pick(x, y) {
     if (!this.regl || !this.layers.length) return null
 
+    const glX = Math.round(x)
+    const glY = this.height - Math.round(y) - 1
+
+    if (glX < 0 || glX >= this.width || glY < 0 || glY >= this.height) return null
+
     const fbo = this.regl.framebuffer({
       width: this.width, height: this.height,
       colorFormat: 'rgba', colorType: 'uint8', depth: false,
     })
 
-    const glX = Math.round(x)
-    const glY = this.height - Math.round(y) - 1
     const axesConfig = this.currentConfig?.axes
 
+    // Refresh transform nodes before picking (same as render)
+    for (const node of this._dataTransformNodes) {
+      await node.refreshIfNeeded(this)
+    }
+
+    // Refresh data columns outside the synchronous regl() callback
+    for (const layer of this.layers) {
+      for (const col of layer._dataColumns ?? []) await col.refresh(this)
+    }
+
     let result = null
+    try {
     this.regl({ framebuffer: fbo })(() => {
       this.regl.clear({ color: [0, 0, 0, 0] })
       const viewport = {
@@ -684,32 +1158,39 @@ export class Plot {
       }
       for (let i = 0; i < this.layers.length; i++) {
         const layer = this.layers[i]
-        if (layer._axisUpdaters) {
-          for (const updater of layer._axisUpdaters) updater.refreshIfNeeded(this)
-        }
 
         const xIsLog = layer.xAxis ? this.axisRegistry.isLogScale(layer.xAxis) : false
         const yIsLog = layer.yAxis ? this.axisRegistry.isLogScale(layer.yAxis) : false
+        const zIsLog = layer.zAxis ? this.axisRegistry.isLogScale(layer.zAxis) : false
+        const zScale = layer.zAxis ? this.axisRegistry.getScale(layer.zAxis) : null
+        const camMvp = this._camera ? this._camera.getMVP() : mat4Identity()
         const props = {
           xDomain: layer.xAxis ? (this.axisRegistry.getScale(layer.xAxis)?.domain() ?? [0, 1]) : [0, 1],
           yDomain: layer.yAxis ? (this.axisRegistry.getScale(layer.yAxis)?.domain() ?? [0, 1]) : [0, 1],
+          zDomain: zScale ? zScale.domain() : [0, 1],
           xScaleType: xIsLog ? 1.0 : 0.0,
           yScaleType: yIsLog ? 1.0 : 0.0,
+          zScaleType: zIsLog ? 1.0 : 0.0,
+          u_is3D:    this._is3D ? 1.0 : 0.0,
+          u_mvp:     camMvp,
           viewport,
           count: layer.vertexCount ?? Object.values(layer.attributes).find(v => v instanceof Float32Array)?.length ?? 0,
           u_pickingMode: 1.0,
           u_pickLayerIndex: i,
         }
         if (layer.instanceCount !== null) props.instances = layer.instanceCount
-        for (const qk of layer.colorAxes) {
-          props[`colorscale_${qk}`] = this.colorAxisRegistry.getColorscaleIndex(qk)
+        for (const qk of Object.values(layer.colorAxes)) {
+          const pk = qk.replace(/\./g, '_')
+          props[`colorscale_${pk}`] = this.colorAxisRegistry.getColorscaleIndex(qk)
           const range = this.colorAxisRegistry.getRange(qk)
-          props[`color_range_${qk}`] = range ?? [0, 1]
-          props[`color_scale_type_${qk}`] = this._getScaleTypeFloat(qk)
+          props[`color_range_${pk}`] = range ?? [0, 1]
+          props[`color_scale_type_${pk}`] = this._getScaleTypeFloat(qk)
+          props[`alpha_blend_${pk}`] = this.colorAxisRegistry.getAlphaBlend(qk)
         }
-        for (const qk of layer.filterAxes) {
-          props[`filter_range_${qk}`] = this.filterAxisRegistry.getRangeUniform(qk)
-          props[`filter_scale_type_${qk}`] = this._getScaleTypeFloat(qk)
+        for (const qk of Object.values(layer.filterAxes)) {
+          const pk = qk.replace(/\./g, '_')
+          props[`filter_range_${pk}`] = this.filterAxisRegistry.getRangeUniform(qk)
+          props[`filter_scale_type_${pk}`] = this._getScaleTypeFloat(qk)
         }
         layer.draw(props)
       }
@@ -728,8 +1209,9 @@ export class Plot {
         result = { layerIndex, configLayerIndex: layer.configLayerIndex, dataIndex, layer }
       }
     })
-
-    fbo.destroy()
+    } finally {
+      fbo.destroy()
+    }
     return result
   }
 }