vizcore 0.1.0 → 1.0.0

data/frontend/src/visual-settings-preset.js

@@ -0,0 +1,103 @@
+export const VISUAL_SETTINGS_PRESET_KEY = "vizcore.visualSettings.v1";
+export const VISUAL_SETTINGS_PRESET_VERSION = 1;
+
+export const DEFAULT_VISUAL_SETTINGS = Object.freeze({
+  visualGain: 2.5,
+  bassBoost: 1.4,
+  smoothing: 0.25,
+  beatHoldMs: 180,
+  wobbleAmount: 1.0,
+});
+
+export const VISUAL_SETTING_LIMITS = Object.freeze({
+  visualGain: [1, 8],
+  bassBoost: [0, 4],
+  smoothing: [0, 0.9],
+  beatHoldMs: [50, 400],
+  wobbleAmount: [0.25, 3],
+});
+
+export const normalizeVisualSettings = (value, fallback = DEFAULT_VISUAL_SETTINGS) => {
+  const input = value && typeof value === "object" ? value : {};
+
+  return Object.fromEntries(
+    Object.entries(DEFAULT_VISUAL_SETTINGS).map(([key, defaultValue]) => {
+      const [min, max] = VISUAL_SETTING_LIMITS[key];
+      const fallbackValue = Number(fallback?.[key] ?? defaultValue);
+      return [key, clampNumber(input[key], min, max, fallbackValue)];
+    })
+  );
+};
+
+export const loadVisualSettingsPreset = (storage, {
+  key = VISUAL_SETTINGS_PRESET_KEY,
+  fallback = DEFAULT_VISUAL_SETTINGS,
+} = {}) => {
+  if (!storage) {
+    return normalizeVisualSettings(fallback);
+  }
+
+  try {
+    const rawValue = storage.getItem(key);
+    if (!rawValue) {
+      return normalizeVisualSettings(fallback);
+    }
+    return normalizeVisualSettings(JSON.parse(rawValue), fallback);
+  } catch {
+    return normalizeVisualSettings(fallback);
+  }
+};
+
+export const saveVisualSettingsPreset = (storage, settings, {
+  key = VISUAL_SETTINGS_PRESET_KEY,
+} = {}) => {
+  const normalized = normalizeVisualSettings(settings);
+  if (!storage) {
+    return normalized;
+  }
+
+  try {
+    storage.setItem(key, JSON.stringify(normalized));
+  } catch {
+    // Ignore storage failures; the active in-memory settings still apply.
+  }
+  return normalized;
+};
+
+export const exportVisualSettingsPreset = (settings) => {
+  return JSON.stringify({
+    version: VISUAL_SETTINGS_PRESET_VERSION,
+    visual_settings: normalizeVisualSettings(settings),
+  }, null, 2);
+};
+
+export const importVisualSettingsPreset = (rawValue, {
+  fallback = DEFAULT_VISUAL_SETTINGS,
+} = {}) => {
+  try {
+    const parsed = typeof rawValue === "string" ? JSON.parse(rawValue) : rawValue;
+    const settings = parsed?.visual_settings || parsed?.settings || parsed;
+    return normalizeVisualSettings(settings, fallback);
+  } catch {
+    return normalizeVisualSettings(fallback);
+  }
+};
+
+export const visualSettingFromUnit = (key, unitValue, fallback = DEFAULT_VISUAL_SETTINGS[key]) => {
+  const limits = VISUAL_SETTING_LIMITS[key];
+  if (!limits) {
+    return Number(fallback ?? 0);
+  }
+
+  const [min, max] = limits;
+  const amount = clampNumber(unitValue, 0, 1, 0);
+  return clampNumber(min + (max - min) * amount, min, max, fallback);
+};
+
+const clampNumber = (value, min, max, fallback) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return fallback;
+  }
+  return Math.min(Math.max(numeric, min), max);
+};

data/frontend/src/visuals/geometry.js

@@ -15,6 +15,58 @@ const EDGES = [
   [0, 4], [1, 5], [2, 6], [3, 7]
 ];
 
+const TETRAHEDRON_VERTICES = [
+  [1, 1, 1],
+  [-1, -1, 1],
+  [-1, 1, -1],
+  [1, -1, -1]
+].map(([x, y, z]) => [x / Math.sqrt(3), y / Math.sqrt(3), z / Math.sqrt(3)]);
+
+const TETRAHEDRON_EDGES = [
+  [0, 1], [0, 2], [0, 3],
+  [1, 2], [1, 3], [2, 3]
+];
+
+const OCTAHEDRON_VERTICES = [
+  [1, 0, 0], [-1, 0, 0],
+  [0, 1, 0], [0, -1, 0],
+  [0, 0, 1], [0, 0, -1]
+];
+
+const OCTAHEDRON_EDGES = [
+  [0, 2], [0, 3], [0, 4], [0, 5],
+  [1, 2], [1, 3], [1, 4], [1, 5],
+  [2, 4], [2, 5], [3, 4], [3, 5]
+];
+
+const PHI = (1 + Math.sqrt(5)) / 2;
+const ICOSAHEDRON_SCALE = 1 / Math.sqrt(1 + PHI * PHI);
+const ICOSAHEDRON_VERTICES = [
+  [-1, PHI, 0], [1, PHI, 0], [-1, -PHI, 0], [1, -PHI, 0],
+  [0, -1, PHI], [0, 1, PHI], [0, -1, -PHI], [0, 1, -PHI],
+  [PHI, 0, -1], [PHI, 0, 1], [-PHI, 0, -1], [-PHI, 0, 1]
+].map(([x, y, z]) => [x * ICOSAHEDRON_SCALE, y * ICOSAHEDRON_SCALE, z * ICOSAHEDRON_SCALE]);
+
+const ICOSAHEDRON_EDGES = [
+  [0, 1], [0, 5], [0, 7], [0, 10], [0, 11],
+  [1, 5], [1, 7], [1, 8], [1, 9],
+  [2, 3], [2, 4], [2, 6], [2, 10], [2, 11],
+  [3, 4], [3, 6], [3, 8], [3, 9],
+  [4, 5], [4, 9], [4, 11],
+  [5, 9], [5, 11],
+  [6, 7], [6, 8], [6, 10],
+  [7, 8], [7, 10],
+  [8, 9],
+  [10, 11]
+];
+
+const MESH_PRESETS = {
+  cube: { vertices: BASE_VERTICES.map(([x, y, z]) => [x * 0.62, y * 0.62, z * 0.62]), edges: EDGES },
+  tetrahedron: { vertices: TETRAHEDRON_VERTICES, edges: TETRAHEDRON_EDGES },
+  octahedron: { vertices: OCTAHEDRON_VERTICES, edges: OCTAHEDRON_EDGES },
+  icosahedron: { vertices: ICOSAHEDRON_VERTICES, edges: ICOSAHEDRON_EDGES }
+};
+
 export const buildWireframeLines = ({ rotationY, rotationX, deform }) => {
   const amount = clamp(Number(deform || 0), 0, 1);
   const projected = BASE_VERTICES.map((vertex) => {
@@ -34,6 +86,34 @@ export const buildWireframeLines = ({ rotationY, rotationX, deform }) => {
   return lines;
 };
 
+export const buildPresetMeshLines = ({ rotationY = 0, rotationX = 0, deform = 0, params = {} } = {}) => {
+  const geometry = normalizeMeshGeometry(params.geometry);
+  const mesh = MESH_PRESETS[geometry] || MESH_PRESETS.icosahedron;
+  const scale = clamp(finiteNumber(params.scale, 1), 0.1, 3.0);
+  const amount = clamp(finiteNumber(deform, 0), 0, 1);
+
+  const projected = mesh.vertices.map((vertex, index) => {
+    const radialPulse = 1 + amount * (0.12 + (index % 3) * 0.05);
+    const twist = Math.sin(index * 1.618 + amount * Math.PI) * amount * 0.08;
+    return projectVertex(
+      [
+        (vertex[0] + vertex[1] * twist) * scale * radialPulse,
+        (vertex[1] + vertex[2] * twist) * scale * (1 + amount * 0.08),
+        (vertex[2] + vertex[0] * twist) * scale * radialPulse
+      ],
+      rotationY,
+      rotationX
+    );
+  });
+
+  const lines = [];
+  for (const [start, end] of mesh.edges) {
+    lines.push(projected[start][0], projected[start][1]);
+    lines.push(projected[end][0], projected[end][1]);
+  }
+  return lines;
+};
+
 export const estimateDeformFromSpectrum = (value) => {
   if (Array.isArray(value)) {
     if (value.length === 0) {
@@ -46,6 +126,183 @@ export const estimateDeformFromSpectrum = (value) => {
   return clamp(Number(value || 0), 0, 1);
 };
 
+export const buildRadialBlobLines = ({ time, params = {}, audio = {} }) => {
+  const segments = clampInt(params.segments || 160, 24, 512);
+  const baseRadius = clamp(Number(params.radius ?? 0.46), 0.05, 1.4);
+  const wobble = clamp(Number(params.wobble ?? audio?.amplitude ?? 0), 0, 3);
+  const spectrum = Array.isArray(params.spectrum) ? params.spectrum : Array.isArray(audio?.fft) ? audio.fft : [];
+  const bass = clamp(Number(audio?.bands?.low || 0), 0, 1);
+  const mid = clamp(Number(audio?.bands?.mid || 0), 0, 1);
+  const pulse = clamp(Number(audio?.beat_pulse || (audio?.beat ? 1 : 0)), 0, 1);
+  const points = [];
+
+  const sample = (index) => {
+    if (!spectrum.length) return 0;
+    return clamp(Number(spectrum[index % spectrum.length] || 0), 0, 1);
+  };
+
+  for (let index = 0; index < segments; index += 1) {
+    const next = (index + 1) % segments;
+    appendRadialPoint(points, index, segments, baseRadius, wobble, bass, mid, pulse, time, sample(index));
+    appendRadialPoint(points, next, segments, baseRadius, wobble, bass, mid, pulse, time, sample(next));
+  }
+
+  return points;
+};
+
+export const normalizeWaveformStyle = (value) => {
+  const style = String(value || "line").trim().toLowerCase();
+  if (style === "mirror" || style === "ribbon") return style;
+  return "line";
+};
+
+export const buildWaveformLines = ({ time = 0, params = {}, audio = {} } = {}) => {
+  const detail = clampInt(params.detail || 96, 16, 256);
+  const height = clamp(finiteNumber(params.height ?? 0.46, 0.46), 0.05, 1.1);
+  const amplitude = clamp(finiteNumber(audio?.amplitude, 0), 0, 1);
+  const spectrum = Array.isArray(params.spectrum) ? params.spectrum : Array.isArray(audio?.fft) ? audio.fft : [];
+  const style = normalizeWaveformStyle(params.style);
+  const samples = buildWaveformSamples({ detail, height, amplitude, spectrum, time });
+  const points = [];
+
+  appendLineSegments(points, samples);
+
+  if (style === "mirror" || style === "ribbon") {
+    const mirrored = samples.map(([x, y]) => [x, -y]);
+    appendLineSegments(points, mirrored);
+  }
+
+  if (style === "ribbon") {
+    const stride = Math.max(4, Math.round(detail / 16));
+    for (let index = 0; index < samples.length; index += stride) {
+      const [x, y] = samples[index];
+      points.push(x, y, x, -y);
+    }
+  }
+
+  return points;
+};
+
+export const buildShapeLines = ({ params = {} } = {}) => {
+  const shapes = Array.isArray(params.shapes) ? params.shapes : [];
+  const points = [];
+
+  shapes.forEach((shape) => {
+    const kind = String(shape?.kind || shape?.type || "").toLowerCase();
+    if (kind === "circle") {
+      appendCircleShape(points, shape);
+    } else if (kind === "line") {
+      appendLineShape(points, shape);
+    }
+  });
+
+  return points;
+};
+
+const buildWaveformSamples = ({ detail, height, amplitude, spectrum, time }) => {
+  const samples = [];
+  const safeTime = finiteNumber(time, 0);
+
+  for (let index = 0; index < detail; index += 1) {
+    const progress = detail === 1 ? 0 : index / (detail - 1);
+    const x = -0.92 + progress * 1.84;
+    const fftValue = sampleSpectrum(spectrum, progress);
+    const carrier = Math.sin(index * 0.55 + safeTime * (2.4 + amplitude * 2.0));
+    const harmonic = Math.sin(index * 0.13 + safeTime * 1.1);
+    const energy = 0.12 + amplitude * 0.35 + fftValue * 0.55;
+    const y = clamp((carrier * 0.72 + harmonic * 0.28) * energy * height, -0.92, 0.92);
+    samples.push([x, y]);
+  }
+
+  return samples;
+};
+
+const appendLineSegments = (points, samples) => {
+  for (let index = 1; index < samples.length; index += 1) {
+    points.push(samples[index - 1][0], samples[index - 1][1], samples[index][0], samples[index][1]);
+  }
+};
+
+const appendCircleShape = (points, shape) => {
+  const count = clampInt(shape.count || 1, 1, 64);
+  const segments = clampInt(shape.segments || 96, 12, 256);
+  const radius = normalizeShapeRadius(shape.radius ?? 100);
+  const x = normalizeShapeCoordinate(shape.x ?? 0, "x");
+  const y = normalizeShapeCoordinate(shape.y ?? 0, "y");
+
+  for (let ring = 0; ring < count; ring += 1) {
+    const ringRadius = radius * ((ring + 1) / count);
+    for (let index = 0; index < segments; index += 1) {
+      appendCirclePoint(points, x, y, ringRadius, index, segments);
+      appendCirclePoint(points, x, y, ringRadius, index + 1, segments);
+    }
+  }
+};
+
+const appendCirclePoint = (points, x, y, radius, index, segments) => {
+  const angle = (index / segments) * Math.PI * 2;
+  points.push(
+    clamp(x + Math.cos(angle) * radius, -1.2, 1.2),
+    clamp(y + Math.sin(angle) * radius, -1.2, 1.2)
+  );
+};
+
+const appendLineShape = (points, shape) => {
+  points.push(
+    normalizeShapeCoordinate(shape.x1 ?? -0.8, "x"),
+    normalizeShapeCoordinate(shape.y1 ?? 0, "y"),
+    normalizeShapeCoordinate(shape.x2 ?? 0.8, "x"),
+    normalizeShapeCoordinate(shape.y2 ?? 0, "y")
+  );
+};
+
+const normalizeShapeRadius = (value) => {
+  const numeric = finiteNumber(value, 100);
+  const radius = Math.abs(numeric) <= 2 ? Math.abs(numeric) : Math.abs(numeric) / 360;
+  return clamp(radius, 0.005, 1.4);
+};
+
+const normalizeShapeCoordinate = (value, axis) => {
+  const numeric = finiteNumber(value, 0);
+  if (Math.abs(numeric) <= 1.5) {
+    return clamp(numeric, -1.2, 1.2);
+  }
+
+  if (axis === "y") {
+    return clamp(1 - numeric / 360, -1.2, 1.2);
+  }
+
+  return clamp(numeric / 640 - 1, -1.2, 1.2);
+};
+
+const sampleSpectrum = (spectrum, progress) => {
+  if (!spectrum.length) return 0;
+
+  const position = progress * (spectrum.length - 1);
+  const left = Math.floor(position);
+  const right = Math.min(left + 1, spectrum.length - 1);
+  const mix = position - left;
+  const from = finiteNumber(spectrum[left], 0);
+  const to = finiteNumber(spectrum[right], 0);
+  return clamp(from + (to - from) * mix, 0, 1);
+};
+
+const appendRadialPoint = (points, index, segments, baseRadius, wobble, bass, mid, pulse, time, fftValue) => {
+  const angle = (index / segments) * Math.PI * 2;
+  const organic = Math.sin(angle * (3.0 + mid * 5.0) + time * (1.2 + bass * 2.0));
+  const radius = baseRadius
+    + bass * 0.14
+    + pulse * 0.10
+    + fftValue * (0.10 + wobble * 0.12)
+    + organic * wobble * 0.035;
+
+  points.push(Math.cos(angle) * radius, Math.sin(angle) * radius);
+};
+
+const normalizeMeshGeometry = (value) => {
+  return String(value || "icosahedron").trim().toLowerCase();
+};
+
 const projectVertex = (vertex, angleY, angleX) => {
   const [x, y, z] = vertex;
 
@@ -63,4 +320,15 @@ const projectVertex = (vertex, angleY, angleX) => {
   return [x1 * perspectiveScale, y1 * perspectiveScale];
 };
 
+const clampInt = (value, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return min;
+  return Math.round(Math.min(Math.max(numeric, min), max));
+};
+
+const finiteNumber = (value, fallback) => {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+};
+
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);

data/frontend/src/visuals/image-renderer.js

@@ -0,0 +1,291 @@
+const IMAGE_VERTEX_SHADER = `#version 300 es
+in vec2 a_position;
+in vec2 a_uv;
+out vec2 v_uv;
+void main() {
+  v_uv = a_uv;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}
+`;
+
+const IMAGE_FRAGMENT_SHADER = `#version 300 es
+precision mediump float;
+in vec2 v_uv;
+uniform sampler2D u_texture;
+uniform float u_intensity;
+uniform float u_invert;
+out vec4 outColor;
+
+void main() {
+  vec4 texel = texture(u_texture, v_uv);
+  vec3 color = mix(texel.rgb, vec3(1.0) - texel.rgb, clamp(u_invert, 0.0, 1.0));
+  outColor = vec4(color, texel.a * u_intensity);
+}
+`;
+
+const QUAD_VERTICES = new Float32Array([
+  -1.0, -1.0, 0.0, 1.0,
+  1.0, -1.0, 1.0, 1.0,
+  -1.0, 1.0, 0.0, 0.0,
+  1.0, 1.0, 1.0, 0.0
+]);
+
+export class ImageRenderer {
+  constructor(gl, shaderManager) {
+    this.gl = gl;
+    this.shaderManager = shaderManager;
+    this.program = this.shaderManager.getProgram("image-renderer", IMAGE_VERTEX_SHADER, IMAGE_FRAGMENT_SHADER);
+    this.positionLocation = this.gl.getAttribLocation(this.program, "a_position");
+    this.uvLocation = this.gl.getAttribLocation(this.program, "a_uv");
+    this.textureLocation = this.gl.getUniformLocation(this.program, "u_texture");
+    this.intensityLocation = this.gl.getUniformLocation(this.program, "u_intensity");
+    this.invertLocation = this.gl.getUniformLocation(this.program, "u_invert");
+    this.media = new Map();
+
+    this.buffer = this.gl.createBuffer();
+    this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.buffer);
+    this.gl.bufferData(this.gl.ARRAY_BUFFER, QUAD_VERTICES, this.gl.STATIC_DRAW);
+
+    this.canvas = document.createElement("canvas");
+    this.canvas.width = 1024;
+    this.canvas.height = 1024;
+    this.ctx = this.canvas.getContext("2d");
+
+    this.texture = this.gl.createTexture();
+    this.gl.bindTexture(this.gl.TEXTURE_2D, this.texture);
+    this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_MIN_FILTER, this.gl.LINEAR);
+    this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_MAG_FILTER, this.gl.LINEAR);
+    this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_WRAP_S, this.gl.CLAMP_TO_EDGE);
+    this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_WRAP_T, this.gl.CLAMP_TO_EDGE);
+  }
+
+  render({ src, audio, fit, scale, rotation, playbackRate, invert }) {
+    const source = resolveMediaSource(src);
+    if (!source) return;
+
+    const media = this.loadMedia(source);
+    this.ensureVideoPlayback(media, playbackRate);
+    const dimensions = resolveMediaDimensions(media);
+    if (!isRenderableMedia(media, dimensions)) {
+      return;
+    }
+
+    this.syncCanvasSize();
+    const amplitude = clamp(Number(audio?.amplitude || 0), 0, 1);
+    const pulse = clamp(Number(audio?.beat_pulse || 0), 0, 1);
+    this.drawImageToCanvas({
+      media,
+      dimensions,
+      fit,
+      scale: normalizeScale(scale) * (1 + amplitude * 0.04 + pulse * 0.03),
+      rotation: normalizeRotation(rotation)
+    });
+    this.uploadTexture();
+    this.drawQuad({ intensity: 0.9 + amplitude * 0.1, invert: normalizeInvert(invert) });
+  }
+
+  loadMedia(src) {
+    return isVideoSource(src) ? this.loadVideo(src) : this.loadImage(src);
+  }
+
+  loadImage(src) {
+    if (this.media.has(src)) {
+      return this.media.get(src);
+    }
+
+    const image = new Image();
+    if (!src.startsWith("data:")) {
+      image.crossOrigin = "anonymous";
+    }
+    image.decoding = "async";
+    image.src = src;
+    this.media.set(src, image);
+    return image;
+  }
+
+  loadVideo(src) {
+    if (this.media.has(src)) {
+      return this.media.get(src);
+    }
+
+    const video = document.createElement("video");
+    if (!src.startsWith("data:")) {
+      video.crossOrigin = "anonymous";
+    }
+    video.muted = true;
+    video.loop = true;
+    video.playsInline = true;
+    video.preload = "auto";
+    video.src = src;
+    this.media.set(src, video);
+    return video;
+  }
+
+  ensureVideoPlayback(media, playbackRate) {
+    if (!isVideoElement(media)) {
+      return;
+    }
+
+    const rate = normalizePlaybackRate(playbackRate);
+    if (media.playbackRate !== rate) {
+      media.playbackRate = rate;
+    }
+
+    if (!media.paused) {
+      return;
+    }
+
+    const playback = media.play();
+    if (playback?.catch) {
+      playback.catch(() => {});
+    }
+  }
+
+  drawImageToCanvas({ media, dimensions, fit, scale, rotation }) {
+    const ctx = this.ctx;
+    ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    const rect = resolveImageRect({
+      canvasWidth: this.canvas.width,
+      canvasHeight: this.canvas.height,
+      imageWidth: dimensions.width,
+      imageHeight: dimensions.height,
+      fit,
+      scale
+    });
+
+    ctx.save();
+    ctx.translate(this.canvas.width / 2, this.canvas.height / 2);
+    ctx.rotate(rotation);
+    ctx.drawImage(media, -rect.width / 2, -rect.height / 2, rect.width, rect.height);
+    ctx.restore();
+  }
+
+  syncCanvasSize() {
+    const width = clamp(Math.floor(this.gl.drawingBufferWidth || 1024), 640, 2048);
+    const height = clamp(Math.floor(this.gl.drawingBufferHeight || 1024), 360, 2048);
+    if (this.canvas.width === width && this.canvas.height === height) {
+      return;
+    }
+    this.canvas.width = width;
+    this.canvas.height = height;
+  }
+
+  uploadTexture() {
+    this.gl.bindTexture(this.gl.TEXTURE_2D, this.texture);
+    this.gl.texImage2D(
+      this.gl.TEXTURE_2D,
+      0,
+      this.gl.RGBA,
+      this.gl.RGBA,
+      this.gl.UNSIGNED_BYTE,
+      this.canvas
+    );
+  }
+
+  drawQuad({ intensity, invert }) {
+    const gl = this.gl;
+    gl.useProgram(this.program);
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
+    gl.enableVertexAttribArray(this.positionLocation);
+    gl.vertexAttribPointer(this.positionLocation, 2, gl.FLOAT, false, 16, 0);
+    gl.enableVertexAttribArray(this.uvLocation);
+    gl.vertexAttribPointer(this.uvLocation, 2, gl.FLOAT, false, 16, 8);
+
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    gl.uniform1i(this.textureLocation, 0);
+    gl.uniform1f(this.intensityLocation, clamp(Number(intensity || 1), 0, 1));
+    gl.uniform1f(this.invertLocation, normalizeInvert(invert));
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+  }
+}
+
+export const resolveMediaSource = (value) => {
+  const source = String(value || "").trim();
+  return source || null;
+};
+
+export const normalizeImageFit = (value) => {
+  const fit = String(value || "contain").trim().toLowerCase();
+  if (fit === "cover" || fit === "stretch") return fit;
+  return "contain";
+};
+
+export const normalizeScale = (value) => {
+  const scale = Number(value);
+  if (!Number.isFinite(scale)) return 1;
+  return clamp(scale, 0.01, 8);
+};
+
+export const normalizeRotation = (value) => {
+  const rotation = Number(value);
+  return Number.isFinite(rotation) ? rotation : 0;
+};
+
+export const normalizePlaybackRate = (value) => {
+  const rate = Number(value);
+  if (!Number.isFinite(rate)) return 1;
+  return clamp(rate, 0.1, 4);
+};
+
+export const normalizeInvert = (value) => {
+  const amount = Number(value);
+  if (!Number.isFinite(amount)) return 0;
+  return clamp(amount, 0, 1);
+};
+
+export const isVideoSource = (value) => {
+  const source = resolveMediaSource(value);
+  if (!source) return false;
+  if (/^data:video\//i.test(source)) return true;
+  return /\.(mp4|webm|ogv|ogg)(?:[?#].*)?$/i.test(source);
+};
+
+export const resolveMediaDimensions = (media) => {
+  if (isVideoElement(media)) {
+    return {
+      width: Number(media.videoWidth || 0),
+      height: Number(media.videoHeight || 0)
+    };
+  }
+
+  return {
+    width: Number(media?.naturalWidth || 0),
+    height: Number(media?.naturalHeight || 0)
+  };
+};
+
+export const resolveImageRect = ({ canvasWidth, canvasHeight, imageWidth, imageHeight, fit, scale = 1 }) => {
+  const width = Math.max(Number(canvasWidth) || 0, 1);
+  const height = Math.max(Number(canvasHeight) || 0, 1);
+  const sourceWidth = Math.max(Number(imageWidth) || 0, 1);
+  const sourceHeight = Math.max(Number(imageHeight) || 0, 1);
+  const resolvedScale = normalizeScale(scale);
+  const resolvedFit = normalizeImageFit(fit);
+
+  if (resolvedFit === "stretch") {
+    return { width: width * resolvedScale, height: height * resolvedScale };
+  }
+
+  const multiplier = resolvedFit === "cover"
+    ? Math.max(width / sourceWidth, height / sourceHeight)
+    : Math.min(width / sourceWidth, height / sourceHeight);
+  return {
+    width: sourceWidth * multiplier * resolvedScale,
+    height: sourceHeight * multiplier * resolvedScale
+  };
+};
+
+const isRenderableMedia = (media, dimensions) => {
+  if (isVideoElement(media)) {
+    return media.readyState >= 2 && dimensions.width > 0 && dimensions.height > 0;
+  }
+
+  return !!media?.complete && dimensions.width > 0 && dimensions.height > 0;
+};
+
+const isVideoElement = (media) => {
+  return media?.tagName === "VIDEO" || (typeof media?.play === "function" && "videoWidth" in media);
+};
+
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);