vizcore 1.0.0 → 1.2.0

data/frontend/src/renderer/layer-manager.js

@@ -18,6 +18,7 @@ import {
   resolveShaderRenderer
 } from "../plugin-runtime.js";
 import { SpectrogramRenderer } from "../visuals/spectrogram-renderer.js";
+import { ShapeRenderer } from "../visuals/shape-renderer.js";
 import { TextRenderer } from "../visuals/text-renderer.js";
 import { getVJEffectShader } from "../visuals/vj-effects.js";
 import { FULLSCREEN_VERTEX_SHADER } from "./shader-manager.js";
@@ -57,6 +58,8 @@ const FULLSCREEN_VERTICES = new Float32Array([
   1.0, 1.0
 ]);
 const MAX_LAYER_TARGET_PIXELS = 4_194_304;
+const MIN_LAYER_RESOLUTION_SCALE = 0.1;
+const SHADER_CACHE_VERSION = "v2";
 
 export const coerceUniformNumber = (value) => {
   if (typeof value === "boolean") {
@@ -129,6 +132,36 @@ export const normalizeBlendMode = (mode) => {
   return "alpha";
 };
 
+export const resolveLayerResolutionScale = (params = {}, visualSettings = {}) => {
+  const rawValue = params?.resolution_scale
+    ?? params?.resolutionScale
+    ?? params?.target_resolution_scale
+    ?? params?.targetResolutionScale
+    ?? 1;
+  const layerScale = clamp(Number(rawValue), MIN_LAYER_RESOLUTION_SCALE, 1);
+  const safeScale = visualSettings?.safeModeActive
+    ? clamp(Number(visualSettings?.safeModeScale || 0.75), MIN_LAYER_RESOLUTION_SCALE, 1)
+    : 1;
+  const scale = layerScale * safeScale;
+  return Number.isFinite(scale) ? clamp(scale, MIN_LAYER_RESOLUTION_SCALE, 1) : 1;
+};
+
+export const shaderCacheKeyForLayer = (layer, shaderName, fragmentShader) => {
+  const customSource = typeof layer?.glsl_source === "string" ? layer.glsl_source : null;
+  const schemaSignature = stableHash(layer?.param_schema || layer?.params?.param_schema || []);
+  if (customSource) {
+    return [
+      "custom",
+      SHADER_CACHE_VERSION,
+      String(layer?.glsl || shaderName),
+      stableHash(fragmentShader),
+      schemaSignature,
+    ].join(":");
+  }
+
+  return ["builtin", SHADER_CACHE_VERSION, String(shaderName), schemaSignature].join(":");
+};
+
 export const normalizePaletteColors = (value) => {
   const input = Array.isArray(value) ? value : [];
   return input
@@ -150,10 +183,119 @@ export const parseHexColor = (value) => {
   return [0, 2, 4].map((offset) => parseInt(hex.slice(offset, offset + 2), 16) / 255);
 };
 
+const normalizePalettePosition = (value, paletteLength) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || !paletteLength) {
+    return 0;
+  }
+
+  const remainder = numeric % paletteLength;
+  return remainder >= 0 ? remainder : remainder + paletteLength;
+};
+
+const interpolatePaletteColor = (left, right, blend) => {
+  const ratio = clamp(blend, 0, 1);
+  const rgb = left.map((value, index) => {
+    const next = right[index];
+    return Math.round(clamp(value + (next - value) * ratio, 0, 1) * 255);
+  });
+  return `#${rgb.map((value) => value.toString(16).padStart(2, "0")).join("")}`;
+};
+
+const normalizeGradientStops = (stops, count) => {
+  if (!Array.isArray(stops)) {
+    return null;
+  }
+
+  const values = stops.map((value) => Number(value)).filter((value) => Number.isFinite(value));
+  if (values.length !== count) {
+    return null;
+  }
+
+  return values.map((value) => clamp(value, 0, 1)).sort((left, right) => left - right);
+};
+
+const resolveGradientColor = (value, paletteIndex = 0) => {
+  const gradient = value?.gradient || value;
+  if (!gradient || typeof gradient !== "object") {
+    return null;
+  }
+
+  const colors = normalizePaletteColors(gradient?.colors || gradient?.palette);
+  if (colors.length === 0) {
+    return null;
+  }
+
+  if (colors.length === 1) {
+    return colors[0];
+  }
+
+  const stops = normalizeGradientStops(gradient?.stops || gradient?.stopsPercent, colors.length);
+  const basePosition = Number.isFinite(Number(gradient?.position)) ? Number(gradient.position) : Number(paletteIndex);
+
+  let position;
+  if (stops) {
+    position = Number.isFinite(basePosition) ? clamp(basePosition, 0, 1) : 0;
+  } else {
+    const fractional = Number.isFinite(basePosition) ? basePosition - Math.floor(basePosition) : 0;
+    position = clamp(fractional, 0, 1);
+  }
+
+  if (position <= 0) {
+    return colors[0];
+  }
+  if (position >= 1) {
+    return colors[colors.length - 1];
+  }
+
+  if (!stops) {
+    const segmentLength = 1 / (colors.length - 1);
+    const segment = Math.min(Math.floor(position / segmentLength), colors.length - 2);
+    const blendBase = segment * segmentLength;
+    const blend = (position - blendBase) / segmentLength;
+    const left = parseHexColor(colors[segment]);
+    const right = parseHexColor(colors[segment + 1]);
+    if (!left || !right) {
+      return colors[segment];
+    }
+
+    return interpolatePaletteColor(left, right, blend);
+  }
+
+  const segment = Array.from({ length: colors.length - 1 }, (_, index) => index)
+    .find((index) => position <= stops[index + 1]);
+
+  if (segment === undefined) {
+    return colors[colors.length - 1];
+  }
+
+  if (segment <= 0 && position <= stops[0]) {
+    return colors[0];
+  }
+
+  const start = stops[segment];
+  const stop = stops[segment + 1];
+  const width = Math.max(stop - start, Number.EPSILON);
+  const blend = clamp((position - start) / width, 0, 1);
+  const left = parseHexColor(colors[segment]);
+  const right = parseHexColor(colors[segment + 1]);
+  if (!left || !right) {
+    return colors[segment];
+  }
+
+  return interpolatePaletteColor(left, right, blend);
+};
+
 export const resolveLayerCssColor = (params = {}, fallback = "#e5f3ff", paletteIndex = 0) => {
-  const explicitColor = String(params?.color || "").trim();
-  if (explicitColor) {
-    return explicitColor;
+  const explicitColor = params?.color;
+  const explicitHex = typeof explicitColor === "string" ? String(explicitColor || "").trim() : "";
+  if (explicitHex) {
+    return explicitHex;
+  }
+
+  const gradientColor = resolveGradientColor(explicitColor, paletteIndex);
+  if (gradientColor) {
+    return gradientColor;
   }
 
   const palette = normalizePaletteColors(params?.palette);
@@ -161,7 +303,24 @@ export const resolveLayerCssColor = (params = {}, fallback = "#e5f3ff", paletteI
     return fallback;
   }
 
-  return palette[Math.abs(Number(paletteIndex) || 0) % palette.length];
+  if (palette.length === 1) {
+    return palette[0];
+  }
+
+  const position = normalizePalettePosition(paletteIndex, palette.length);
+  const lowerIndex = Math.floor(position);
+  const blend = position - lowerIndex;
+  if (blend <= 0 || !Number.isFinite(blend)) {
+    return palette[lowerIndex];
+  }
+
+  const leftColor = parseHexColor(palette[lowerIndex]);
+  const rightColor = parseHexColor(palette[(lowerIndex + 1) % palette.length]);
+  if (!leftColor || !rightColor) {
+    return palette[lowerIndex];
+  }
+
+  return interpolatePaletteColor(leftColor, rightColor, blend);
 };
 
 export const resolveLayerRgbColor = (params = {}, fallback = null, paletteIndex = 0) => {
@@ -196,15 +355,19 @@ export class LayerManager {
 
     this.layerFramebuffer = null;
     this.layerTexture = null;
+    this.layerTextureSecondary = null;
     this.layerDepthRenderbuffer = null;
     this.layerTargetWidth = 0;
     this.layerTargetHeight = 0;
     this.layerTargetAvailable = true;
     this.layerErrorKeys = new Set();
+    this.lastGoodShaderPrograms = new Map();
+    this.activeShaderLayerKeys = null;
 
     this.particleSystem = new ParticleSystem(this.gl, this.shaderManager);
     this.textRenderer = new TextRenderer(this.gl, this.shaderManager);
     this.imageRenderer = new ImageRenderer(this.gl, this.shaderManager);
+    this.shapeRenderer = new ShapeRenderer(this.gl, this.shaderManager);
     this.spectrogramRenderer = new SpectrogramRenderer(this.gl, this.shaderManager);
 
     this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.fullscreenBuffer);
@@ -215,30 +378,35 @@ export class LayerManager {
     const layerList = Array.isArray(layers) && layers.length > 0 ? layers : [defaultLayer(audio)];
     const width = Math.max(1, Math.floor(Number(resolution?.[0] || 1)));
     const height = Math.max(1, Math.floor(Number(resolution?.[1] || 1)));
-    this.ensureLayerTarget(width, height);
+    const shaderLayerKeys = new Set();
+    this.activeShaderLayerKeys = shaderLayerKeys;
 
-    if (!this.layerTargetAvailable || !this.layerFramebuffer || !this.layerTexture) {
-      layerList.forEach((layer, index) => {
-        try {
+    layerList.forEach((layer, index) => {
+      try {
+        this.ensureLayerTarget(width, height, layer, visualSettings);
+        if (!this.layerTargetAvailable || !this.layerFramebuffer || !this.layerTexture) {
           const blend = String(layer?.params?.blend || "alpha").toLowerCase();
           this.setBlendMode(blend);
           this.renderLayer(layer, audio, time, rotation, [width, height], globals, visualSettings, index);
-        } catch (error) {
-          this.reportLayerError(layer, error, "direct-render");
+          return;
         }
-      });
-      this.setBlendMode("alpha");
-      return;
-    }
 
-    layerList.forEach((layer, index) => {
-      try {
         this.gl.bindFramebuffer(this.gl.FRAMEBUFFER, this.layerFramebuffer);
         this.gl.viewport(0, 0, this.layerTargetWidth, this.layerTargetHeight);
         this.gl.clearColor(0.0, 0.0, 0.0, 0.0);
         this.gl.clear(this.gl.COLOR_BUFFER_BIT | this.gl.DEPTH_BUFFER_BIT);
 
-        this.renderLayer(layer, audio, time, rotation, [this.layerTargetWidth, this.layerTargetHeight], globals, visualSettings, index);
+        this.renderLayer(
+          layer,
+          audio,
+          time,
+          rotation,
+          [this.layerTargetWidth, this.layerTargetHeight],
+          globals,
+          visualSettings,
+          index,
+          index
+        );
 
         this.gl.bindFramebuffer(this.gl.FRAMEBUFFER, null);
         this.gl.viewport(0, 0, width, height);
@@ -249,10 +417,22 @@ export class LayerManager {
         this.reportLayerError(layer, error, "layer-pass");
       }
     });
+    this.pruneLastGoodShaderPrograms(shaderLayerKeys);
+    this.activeShaderLayerKeys = null;
     this.setBlendMode("alpha");
   }
 
-  renderLayer(layer, audio, time, rotation, resolution, globals, visualSettings, paletteIndex = 0) {
+  renderLayer(
+    layer,
+    audio,
+    time,
+    rotation,
+    resolution,
+    globals,
+    visualSettings,
+    paletteIndex = 0,
+    layerIndex = null
+  ) {
     if (isParticleLayer(layer)) {
       this.renderParticleLayer(layer, audio, time, paletteIndex);
       return;
@@ -274,20 +454,40 @@ export class LayerManager {
       return;
     }
     if (isShapeLayer(layer)) {
-      this.renderShapeLayer(layer, audio, paletteIndex);
+      this.renderShapeLayer(layer, audio, time, resolution, paletteIndex);
       return;
     }
     if (isShaderLayer(layer)) {
-      this.renderShaderLayer(layer, audio, time, resolution, globals, visualSettings);
+      this.renderShaderLayer(layer, audio, time, resolution, globals, visualSettings, paletteIndex, layerIndex);
       return;
     }
-    if (this.renderPluginLayer(layer, audio, time, rotation, resolution, globals, visualSettings, paletteIndex)) {
+    if (this.renderPluginLayer(
+      layer,
+      audio,
+      time,
+      rotation,
+      resolution,
+      globals,
+      visualSettings,
+      paletteIndex,
+      layerIndex
+    )) {
       return;
     }
     this.renderGeometryLayer(layer, audio, rotation, time, paletteIndex);
   }
 
-  renderPluginLayer(layer, audio, time, rotation, resolution, globals, visualSettings, paletteIndex = 0) {
+  renderPluginLayer(
+    layer,
+    audio,
+    time,
+    rotation,
+    resolution,
+    globals,
+    visualSettings,
+    paletteIndex = 0,
+    layerIndex = null
+  ) {
     const context = {
       layer,
       audio,
@@ -300,19 +500,29 @@ export class LayerManager {
     };
 
     const renderer = resolveLayerRenderer(layer?.type);
-    if (renderer && this.renderPluginOutput(layer, renderer(context), audio, time, resolution, globals, visualSettings, paletteIndex)) {
+    if (renderer && this.renderPluginOutput(layer, renderer(context), audio, time, resolution, globals, visualSettings, paletteIndex, layerIndex)) {
       return true;
     }
 
     const shaderRenderer = resolveShaderRenderer(layer?.type);
-    if (shaderRenderer && this.renderPluginOutput(layer, shaderRenderer(context), audio, time, resolution, globals, visualSettings, paletteIndex)) {
+    if (shaderRenderer && this.renderPluginOutput(layer, shaderRenderer(context), audio, time, resolution, globals, visualSettings, paletteIndex, layerIndex)) {
       return true;
     }
 
     return false;
   }
 
-  renderPluginOutput(layer, output, audio, time, resolution, globals, visualSettings, paletteIndex = 0) {
+  renderPluginOutput(
+    layer,
+    output,
+    audio,
+    time,
+    resolution,
+    globals,
+    visualSettings,
+    paletteIndex = 0,
+    layerIndex = null
+  ) {
     const lines = normalizePluginLineOutput(output);
     if (lines) {
       const fallbackColor = resolveLayerRgbColor(layer?.params || {}, [0.82, 0.92, 1.0], paletteIndex);
@@ -330,42 +540,74 @@ export class LayerManager {
       shader: layer?.shader || "default",
       glsl: `plugin:${String(layer?.type || "layer")}:${shader.cacheKey}`,
       glsl_source: shader.fragmentShader
-    }, audio, time, resolution, globals, visualSettings);
+    }, audio, time, resolution, globals, visualSettings, paletteIndex, layerIndex);
     return true;
   }
 
-  renderShaderLayer(layer, audio, time, resolution, globals, visualSettings) {
+  renderShaderLayer(
+    layer,
+    audio,
+    time,
+    resolution,
+    globals,
+    visualSettings,
+    paletteIndex = 0,
+    layerIndex = null
+  ) {
     const shaderName = String(layer?.shader || "gradient_pulse");
     const customSource = typeof layer?.glsl_source === "string" ? layer.glsl_source : null;
     const fragmentShader = customSource || getBuiltinShader(shaderName);
-    const cacheKey = customSource
-      ? `custom:${String(layer?.glsl || shaderName)}:${hashString(customSource)}`
-      : `builtin:${shaderName}`;
+    const cacheKey = shaderCacheKeyForLayer(layer, shaderName, fragmentShader);
+    const layerCacheKey = this.shaderLayerCacheKey(layer, layerIndex, customSource);
+    if (layerCacheKey) {
+      this.activeShaderLayerKeys?.add(layerCacheKey);
+    }
+
     let program = null;
     try {
       program = this.shaderManager.getProgram(cacheKey, FULLSCREEN_VERTEX_SHADER, fragmentShader);
+      if (layerCacheKey) {
+        this.lastGoodShaderPrograms.set(layerCacheKey, {
+          program,
+          cacheKey,
+          createdAt: Date.now()
+        });
+      }
     } catch (error) {
       if (customSource) {
         this.reportShaderError(layer, error, "custom-shader");
         console.warn("Failed to compile custom GLSL, falling back to builtin shader", error);
+        const cached = layerCacheKey ? this.lastGoodShaderPrograms.get(layerCacheKey) : null;
+        if (cached && cached.program) {
+          program = cached.program;
+        }
+
         try {
-          program = this.shaderManager.getProgram(
-            `builtin:${shaderName}`,
-            FULLSCREEN_VERTEX_SHADER,
-            getBuiltinShader(shaderName)
-          );
+          if (!program) {
+            program = this.shaderManager.getProgram(
+              shaderCacheKeyForLayer(
+                { ...layer, glsl_source: null },
+                shaderName,
+                getBuiltinShader(shaderName)
+              ),
+              FULLSCREEN_VERTEX_SHADER,
+              getBuiltinShader(shaderName)
+            );
+          }
         } catch (builtinError) {
           this.reportShaderError(layer, builtinError, "builtin-shader-fallback");
           this.reportLayerError(layer, builtinError, "builtin-shader-fallback");
+          program = null;
         }
       } else {
         this.reportShaderError(layer, error, "builtin-shader");
         this.reportLayerError(layer, error, "builtin-shader");
+        program = null;
       }
 
       if (!program) {
         program = this.shaderManager.getProgram(
-          "builtin:default",
+          shaderCacheKeyForLayer({ shader: "default" }, "default", getBuiltinShader("default")),
           FULLSCREEN_VERTEX_SHADER,
           getBuiltinShader("default")
         );
@@ -381,6 +623,7 @@ export class LayerManager {
     gl.vertexAttribPointer(positionLocation, 2, gl.FLOAT, false, 0, 0);
 
     const bands = audio?.bands || {};
+    const bandPeaks = audio?.band_peaks || {};
     const onsets = audio?.onsets || {};
     const drums = audio?.drums || {};
     this.setUniform1f(program, "u_time", time);
@@ -389,8 +632,19 @@ export class LayerManager {
     this.setUniform1f(program, "u_bass", bands.low || 0);
     this.setUniform1f(program, "u_mid", bands.mid || 0);
     this.setUniform1f(program, "u_high", bands.high || 0);
+    this.setUniform1f(program, "u_bass_peak", bandPeaks.low || 0);
+    this.setUniform1f(program, "u_mid_peak", bandPeaks.mid || 0);
+    this.setUniform1f(program, "u_high_peak", bandPeaks.high || 0);
     this.setUniform1f(program, "u_beat", audio?.beat ? 1 : 0);
     this.setUniform1f(program, "u_beat_pulse", audio?.beat_pulse || (audio?.beat ? 1 : 0));
+    this.setUniform1f(program, "u_beat_phase", audio?.beat_phase || 0);
+    this.setUniform1f(program, "u_bar_phase", audio?.bar_phase || 0);
+    this.setUniform1f(program, "u_bar_count", audio?.bar_count || 0);
+    this.setUniform1f(program, "u_phrase_count", audio?.phrase_count || 0);
+    this.setUniform1f(program, "u_beat_2", audio?.beat_2 ? 1 : 0);
+    this.setUniform1f(program, "u_beat_4", audio?.beat_4 ? 1 : 0);
+    this.setUniform1f(program, "u_beat_8", audio?.beat_8 ? 1 : 0);
+    this.setUniform1f(program, "u_beat_triplet", audio?.beat_triplet ? 1 : 0);
     this.setUniform1f(program, "u_onset", audio?.onset || 0);
     this.setUniform1f(program, "u_sub_onset", onsets.sub || 0);
     this.setUniform1f(program, "u_low_onset", onsets.low || 0);
@@ -556,16 +810,28 @@ export class LayerManager {
     });
   }
 
-  renderShapeLayer(layer, audio, paletteIndex = 0) {
+  renderShapeLayer(layer, audio, time, resolution, paletteIndex = 0) {
     const params = layer?.params || {};
+    const amplitude = clamp(Number(audio?.amplitude || 0), 0, 1);
+    const fallbackColor = [0.85, 0.50 + amplitude * 0.24, 0.95];
+    const cssColor = resolveLayerCssColor(params, "#d98cff", paletteIndex);
+    const rendered = this.shapeRenderer.render({
+      params,
+      color: cssColor,
+      resolution,
+      audio,
+      time
+    });
+    if (rendered) {
+      return;
+    }
+
     const points = buildShapeLines({ params });
 
     if (points.length === 0) {
       return;
     }
 
-    const amplitude = clamp(Number(audio?.amplitude || 0), 0, 1);
-    const fallbackColor = [0.85, 0.50 + amplitude * 0.24, 0.95];
     const color = resolveLayerRgbColor(params, fallbackColor, paletteIndex);
     this.renderLinePoints(points, color);
   }
@@ -584,30 +850,96 @@ export class LayerManager {
   compositeLayer(layer, { audio, time, resolution }) {
     const gl = this.gl;
     const params = layer?.params || {};
-    const opacity = clamp(Number(params.opacity || 1), 0, 1);
+    const effects = this.resolvePostEffects(params);
+    if (effects.length === 0) {
+      this.drawLayerTexture(this.layerTexture, { layer, audio, time, resolution, opacity: params.opacity });
+      return;
+    }
+
     const blend = String(params.blend || "alpha").toLowerCase();
-    const effectName = String(params.effect || "");
-    const vjEffectName = String(params.vj_effect || "");
     const effectIntensity = clamp(Number(params.effect_intensity || audio?.amplitude || 0.35), 0, 1);
-    const effectShader = getPostEffectShader(effectName);
-    const vjShader = getVJEffectShader(vjEffectName);
-    const selectedShader = vjShader || effectShader;
-    const selectedEffectName = vjShader ? `vj:${vjEffectName}` : `post:${effectName}`;
-    let program = this.compositeProgram;
-    if (selectedShader) {
-      try {
-        program = this.shaderManager.getProgram(
-          selectedEffectName,
-          FULLSCREEN_VERTEX_SHADER,
-          selectedShader
-        );
-      } catch (error) {
-        this.reportLayerError(layer, error, selectedEffectName);
-        program = this.compositeProgram;
+    let sourceTexture = this.layerTexture;
+    let targetTexture = this.layerTextureSecondary;
+
+    this.setBlendMode(blend);
+    effects.forEach((effectName) => {
+      const resolvedName = String(effectName);
+      const vjShader = getVJEffectShader(resolvedName);
+      const effectShader = getPostEffectShader(resolvedName);
+      const selectedShader = vjShader || effectShader;
+      const selectedEffectName = vjShader ? `vj:${resolvedName}` : `post:${resolvedName}`;
+      let program = this.compositeProgram;
+
+      if (selectedShader) {
+        try {
+          program = this.shaderManager.getProgram(
+            selectedEffectName,
+            FULLSCREEN_VERTEX_SHADER,
+            selectedShader
+          );
+        } catch (error) {
+          this.reportLayerError(layer, error, selectedEffectName);
+          program = this.compositeProgram;
+        }
       }
+
+      this.applyEffectPass({
+        sourceTexture,
+        destinationTexture: targetTexture,
+        program,
+        time,
+        resolution: [this.layerTargetWidth, this.layerTargetHeight],
+        effectIntensity
+      });
+
+      [sourceTexture, targetTexture] = [targetTexture, sourceTexture];
+    });
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.viewport(0, 0, resolution[0], resolution[1]);
+    this.drawLayerTexture(sourceTexture, {
+      layer,
+      audio,
+      time,
+      resolution,
+      opacity: params.opacity
+    });
+  }
+
+  resolvePostEffects(params) {
+    const postEffects = Array.isArray(params?.post_effects)
+      ? params.post_effects
+          .map((value) => String(value || "").trim().toLowerCase())
+          .filter((value) => value.length > 0)
+      : [];
+    if (postEffects.length > 0) {
+      return postEffects;
     }
 
-    this.setBlendMode(blend);
+    const vjEffectName = String(params?.vj_effect || "").trim().toLowerCase();
+    if (vjEffectName) {
+      return [vjEffectName];
+    }
+
+    const effectName = String(params?.effect || "").trim().toLowerCase();
+    if (effectName) {
+      return [effectName];
+    }
+
+    return [];
+  }
+
+  applyEffectPass({ sourceTexture, destinationTexture, program, time, resolution, effectIntensity }) {
+    const gl = this.gl;
+    if (!sourceTexture || !destinationTexture) {
+      return;
+    }
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.layerFramebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, destinationTexture, 0);
+    gl.viewport(0, 0, this.layerTargetWidth, this.layerTargetHeight);
+    gl.clearColor(0.0, 0.0, 0.0, 0.0);
+    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
 
     gl.useProgram(program);
     gl.bindBuffer(gl.ARRAY_BUFFER, this.fullscreenBuffer);
@@ -616,22 +948,41 @@ export class LayerManager {
     gl.vertexAttribPointer(positionLocation, 2, gl.FLOAT, false, 0, 0);
 
     gl.activeTexture(gl.TEXTURE0);
-    gl.bindTexture(gl.TEXTURE_2D, this.layerTexture);
+    gl.bindTexture(gl.TEXTURE_2D, sourceTexture);
     this.setUniform1i(program, "u_texture", 0);
-    this.setUniform1f(program, "u_opacity", opacity);
     this.setUniform1f(program, "u_time", time);
     this.setUniform1f(program, "u_intensity", effectIntensity);
     this.setUniform2f(program, "u_resolution", resolution[0], resolution[1]);
+    this.setUniform1f(program, "u_opacity", 1);
 
     gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
   }
 
-  ensureLayerTarget(width, height) {
+  drawLayerTexture(texture, { layer, audio, time, resolution, opacity }) {
+    const gl = this.gl;
+    const params = layer?.params || {};
+    gl.useProgram(this.compositeProgram);
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.fullscreenBuffer);
+    gl.enableVertexAttribArray(this.compositePositionLocation);
+    gl.vertexAttribPointer(this.compositePositionLocation, 2, gl.FLOAT, false, 0, 0);
+
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    this.setUniform1i(this.compositeProgram, "u_texture", 0);
+    this.setUniform1f(this.compositeProgram, "u_opacity", clamp(Number(opacity || 1), 0, 1));
+    this.setUniform1f(this.compositeProgram, "u_time", time);
+    this.setUniform1f(this.compositeProgram, "u_intensity", params.effect_intensity || audio?.amplitude || 0.35);
+    this.setUniform2f(this.compositeProgram, "u_resolution", resolution[0], resolution[1]);
+
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+  }
+
+  ensureLayerTarget(width, height, layer = null, visualSettings = null) {
     if (!this.layerTargetAvailable) {
       return;
     }
 
-    const [targetWidth, targetHeight] = this.resolveLayerTargetSize(width, height);
+    const [targetWidth, targetHeight] = this.resolveLayerTargetSize(width, height, layer, visualSettings);
     if (this.layerFramebuffer && this.layerTargetWidth === targetWidth && this.layerTargetHeight === targetHeight) {
       return;
     }
@@ -642,16 +993,10 @@ export class LayerManager {
 
     const gl = this.gl;
     this.layerFramebuffer = gl.createFramebuffer();
-    this.layerTexture = gl.createTexture();
+    this.layerTexture = this.createLayerTexture(targetWidth, targetHeight);
+    this.layerTextureSecondary = this.createLayerTexture(targetWidth, targetHeight);
     this.layerDepthRenderbuffer = gl.createRenderbuffer();
 
-    gl.bindTexture(gl.TEXTURE_2D, this.layerTexture);
-    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, targetWidth, targetHeight, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
-
     gl.bindFramebuffer(gl.FRAMEBUFFER, this.layerFramebuffer);
     gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.layerTexture, 0);
 
@@ -673,11 +1018,27 @@ export class LayerManager {
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
   }
 
+  createLayerTexture(width, height) {
+    const gl = this.gl;
+    const texture = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    return texture;
+  }
+
   disposeLayerTarget() {
     if (this.layerTexture) {
       this.gl.deleteTexture(this.layerTexture);
       this.layerTexture = null;
     }
+    if (this.layerTextureSecondary) {
+      this.gl.deleteTexture(this.layerTextureSecondary);
+      this.layerTextureSecondary = null;
+    }
     if (this.layerDepthRenderbuffer) {
       this.gl.deleteRenderbuffer(this.layerDepthRenderbuffer);
       this.layerDepthRenderbuffer = null;
@@ -688,11 +1049,12 @@ export class LayerManager {
     }
   }
 
-  resolveLayerTargetSize(width, height) {
+  resolveLayerTargetSize(width, height, layer = null, visualSettings = null) {
     const gl = this.gl;
     const maxTextureSize = Number(gl.getParameter(gl.MAX_TEXTURE_SIZE) || 4096);
-    let targetWidth = clamp(Math.floor(width), 1, maxTextureSize);
-    let targetHeight = clamp(Math.floor(height), 1, maxTextureSize);
+    const scale = resolveLayerResolutionScale(layer?.params || {}, visualSettings || {});
+    let targetWidth = clamp(Math.floor(width * scale), 1, maxTextureSize);
+    let targetHeight = clamp(Math.floor(height * scale), 1, maxTextureSize);
 
     const pixels = targetWidth * targetHeight;
     if (pixels > MAX_LAYER_TARGET_PIXELS) {
@@ -704,6 +1066,23 @@ export class LayerManager {
     return [targetWidth, targetHeight];
   }
 
+  dispose() {
+    this.disposeLayerTarget();
+    this.particleSystem?.dispose?.();
+    this.textRenderer?.dispose?.();
+    this.imageRenderer?.dispose?.();
+    this.shapeRenderer?.dispose?.();
+    this.spectrogramRenderer?.dispose?.();
+    if (this.fullscreenBuffer) {
+      this.gl.deleteBuffer(this.fullscreenBuffer);
+      this.fullscreenBuffer = null;
+    }
+    if (this.geometryBuffer) {
+      this.gl.deleteBuffer(this.geometryBuffer);
+      this.geometryBuffer = null;
+    }
+  }
+
   setBlendMode(mode) {
     const blendMode = normalizeBlendMode(mode);
     this.gl.blendEquation(this.gl.FUNC_ADD);
@@ -780,6 +1159,27 @@ export class LayerManager {
       window.dispatchEvent(new CustomEvent(SHADER_ERROR_EVENT, { detail }));
     }
   }
+
+  pruneLastGoodShaderPrograms(activeKeys) {
+    const active = activeKeys instanceof Set ? activeKeys : null;
+    if (!active) {
+      return;
+    }
+    for (const key of this.lastGoodShaderPrograms.keys()) {
+      if (!active.has(key)) {
+        this.lastGoodShaderPrograms.delete(key);
+      }
+    }
+  }
+
+  shaderLayerCacheKey(layer, layerIndex, hasCustomSource) {
+    const name = String(layer?.name || "unnamed");
+    const type = String(layer?.type || "layer");
+    const sourceKind = hasCustomSource ? "custom" : "builtin";
+    const sourceId = String(layer?.glsl || layer?.shader || layer?.type || "default");
+    const index = Number.isFinite(layerIndex) ? layerIndex : "static";
+    return `shader-layer|${sourceKind}|${index}|${type}|${name}|${sourceId}`;
+  }
 }
 
 const isShaderLayer = (layer) => {
@@ -845,10 +1245,25 @@ const defaultLayer = (audio) => ({
 
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
 
+const stableHash = (value) => hashString(stableStringify(value));
+
+const stableStringify = (value) => {
+  if (value === null || typeof value !== "object") {
+    return String(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+
+  return `{${Object.keys(value).sort().map((key) => `${key}:${stableStringify(value[key])}`).join(",")}}`;
+};
+
 const hashString = (value) => {
+  const text = String(value || "");
   let hash = 0;
-  for (let index = 0; index < value.length; index += 1) {
-    hash = (hash * 31 + value.charCodeAt(index)) >>> 0;
+  for (let index = 0; index < text.length; index += 1) {
+    hash = (hash * 31 + text.charCodeAt(index)) >>> 0;
   }
   return hash.toString(16);
 };