vizcore 1.0.0 → 1.1.0

data/frontend/src/main.js

@@ -31,10 +31,24 @@ import {
 import { applyProjectorMode, resolveProjectorMode } from "./projector-mode.js";
 import { Engine } from "./renderer/engine.js";
 import { SHADER_COMPILE_EVENT } from "./renderer/shader-manager.js";
+import {
+  customShapeParamControlEntries,
+  customShapeParamMessage,
+  pruneCustomShapeParamOverrides
+} from "./custom-shape-param-controls.js";
+import {
+  mappingTargetOptions,
+  mappingTargetSignature
+} from "./mapping-target-selector.js";
 import {
   pruneShaderParamOverrides,
   shaderParamControlEntries
 } from "./shader-param-controls.js";
+import {
+  normalizeShapeEditorPatch,
+  pruneShapeEditorOverrides,
+  shapeEditorEntries
+} from "./shape-editor-controls.js";
 import { normalizeRuntimeControlPreset } from "./runtime-control-preset.js";
 import { SHADER_ERROR_EVENT, formatShaderErrorMessage, formatShaderErrorTitle } from "./shader-error-overlay.js";
 import {
@@ -91,6 +105,9 @@ const reactivityStatusElement = document.querySelector("#reactivity-status");
 const midiLearnStatusElement = document.querySelector("#midi-learn-status");
 const midiLearnButtons = Array.from(document.querySelectorAll("[data-midi-learn-action]"));
 const shaderParamControlsElement = document.querySelector("#shader-param-controls");
+const shapeEditorControlsElement = document.querySelector("#shape-editor-controls");
+const customShapeParamControlsElement = document.querySelector("#custom-shape-param-controls");
+const mappingTargetSelectorElement = document.querySelector("#mapping-target-selector");
 const shaderErrorOverlay = document.querySelector("#shader-error-overlay");
 const shaderErrorTitleElement = document.querySelector("#shader-error-title");
 const shaderErrorMessageElement = document.querySelector("#shader-error-message");
@@ -119,6 +136,12 @@ let runtimeControlPresetApplied = false;
 let controlPresetSaveUrl = null;
 let shaderParamOverrides = {};
 let shaderParamControlsSignature = "";
+let shapeEditorOverrides = {};
+let shapeEditorControlsSignature = "";
+let customShapeParamOverrides = {};
+let customShapeParamControlsSignature = "";
+let mappingTargetSelectorSignature = "";
+let selectedMappingTarget = "";
 let midiAccess = null;
 let pendingMidiLearnAction = null;
 applyProjectorMode(document.body, projectorMode);
@@ -180,8 +203,14 @@ const client = new WebSocketClient(websocketUrl, {
     currentSceneName = sceneName;
     if (sceneChanged) {
       shaderParamControlsSignature = "";
+      shapeEditorControlsSignature = "";
+      customShapeParamControlsSignature = "";
+      mappingTargetSelectorSignature = "";
     }
     updateShaderParamControls(frame?.scene?.layers);
+    updateShapeEditorControls(frame?.scene?.layers);
+    updateCustomShapeParamControls(frame?.scene?.layers);
+    updateMappingTargetSelector(frame?.scene?.layers);
     const amplitude = Number(frame?.audio?.amplitude || 0).toFixed(4);
     const bpm = Number(frame?.audio?.bpm || 0);
     const beat = !!frame?.audio?.beat;
@@ -218,7 +247,13 @@ const client = new WebSocketClient(websocketUrl, {
       sceneStatusElement.textContent = `Scene: ${currentSceneName}`;
       renderSceneButtons();
       shaderParamControlsSignature = "";
+      shapeEditorControlsSignature = "";
+      customShapeParamControlsSignature = "";
+      mappingTargetSelectorSignature = "";
       updateShaderParamControls(payload?.scene?.layers);
+      updateShapeEditorControls(payload?.scene?.layers);
+      updateCustomShapeParamControls(payload?.scene?.layers);
+      updateMappingTargetSelector(payload?.scene?.layers);
     }
     if (Object.prototype.hasOwnProperty.call(payload || {}, "tap_tempo_key")) {
       updateTapTempoKey(payload?.tap_tempo_key);
@@ -494,6 +529,239 @@ function formatShaderParamValue(value) {
   return Math.abs(numeric) >= 10 ? numeric.toFixed(1) : numeric.toFixed(2);
 }
 
+function updateShapeEditorControls(layers) {
+  const entries = shapeEditorEntries(layers, shapeEditorOverrides);
+  const signature = shapeEditorControlsSignatureFor(entries);
+  if (signature === shapeEditorControlsSignature) {
+    return;
+  }
+
+  shapeEditorControlsSignature = signature;
+  shapeEditorOverrides = pruneShapeEditorOverrides(shapeEditorOverrides, entries);
+  engine.setShapeEditorOverrides(shapeEditorOverrides);
+  renderShapeEditorControls(entries);
+}
+
+function shapeEditorControlsSignatureFor(entries) {
+  return entries.map((entry) => (
+    `${entry.key}:${entry.kind}:${JSON.stringify(entry.values)}`
+  )).join("|");
+}
+
+function renderShapeEditorControls(entries) {
+  if (!shapeEditorControlsElement) {
+    return;
+  }
+
+  if (!entries.length) {
+    shapeEditorControlsElement.hidden = true;
+    shapeEditorControlsElement.replaceChildren();
+    return;
+  }
+
+  const title = document.createElement("p");
+  title.className = "shader-param-controls__title";
+  title.textContent = "Shape Editor";
+  const controls = entries.map((entry) => createShapeEditorControl(entry));
+  shapeEditorControlsElement.replaceChildren(title, ...controls);
+  shapeEditorControlsElement.hidden = false;
+}
+
+function createShapeEditorControl(entry) {
+  const section = document.createElement("details");
+  const summary = document.createElement("summary");
+  summary.textContent = entry.label;
+  section.append(summary);
+  section.append(
+    createShapeKindControl(entry),
+    createShapeNumberControl(entry, "translateX", "Move X", -640, 640, 1),
+    createShapeNumberControl(entry, "translateY", "Move Y", -360, 360, 1),
+    createShapeNumberControl(entry, "rotate", "Rotate", -180, 180, 1),
+    createShapeNumberControl(entry, "scaleX", "Scale X", -4, 4, 0.05),
+    createShapeNumberControl(entry, "scaleY", "Scale Y", -4, 4, 0.05),
+    createShapeNumberControl(entry, "opacity", "Opacity", 0, 1, 0.05),
+    createShapeColorControl(entry, "fill", "Fill"),
+    createShapeColorControl(entry, "strokeColor", "Stroke"),
+    createShapeNumberControl(entry, "strokeWidth", "Stroke W", 0, 24, 0.5)
+  );
+  return section;
+}
+
+function createShapeKindControl(entry) {
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const select = document.createElement("select");
+  name.textContent = "Kind";
+  ["circle", "line", "rect", "polygon", "polyline", "path", "star"].forEach((kind) => {
+    const option = document.createElement("option");
+    option.value = kind;
+    option.textContent = kind;
+    select.append(option);
+  });
+  select.value = entry.kind;
+  select.addEventListener("change", () => {
+    writeShapeEditorOverride(entry, { ...entry.values, kind: select.value });
+  });
+  label.append(name, select);
+  return label;
+}
+
+function createShapeNumberControl(entry, key, labelText, min, max, step) {
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const input = document.createElement("input");
+  const value = document.createElement("output");
+  name.textContent = labelText;
+  input.type = "range";
+  input.min = String(min);
+  input.max = String(max);
+  input.step = String(step);
+  input.value = String(entry.values[key]);
+  value.value = formatShaderParamValue(entry.values[key]);
+  input.addEventListener("input", () => {
+    const numeric = Number(input.value);
+    writeShapeEditorOverride(entry, { ...entry.values, [key]: numeric });
+    value.value = formatShaderParamValue(numeric);
+  });
+  label.append(name, input, value);
+  return label;
+}
+
+function createShapeColorControl(entry, key, labelText) {
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const input = document.createElement("input");
+  const value = document.createElement("output");
+  name.textContent = labelText;
+  input.type = "color";
+  input.value = entry.values[key];
+  value.value = entry.values[key];
+  input.addEventListener("input", () => {
+    writeShapeEditorOverride(entry, { ...entry.values, [key]: input.value, [`${key}Enabled`]: true });
+    value.value = input.value;
+  });
+  label.append(name, input, value);
+  return label;
+}
+
+function writeShapeEditorOverride(entry, values) {
+  shapeEditorOverrides[entry.layerKey] ||= {};
+  shapeEditorOverrides[entry.layerKey][entry.shapeIndex] = normalizeShapeEditorPatch(values);
+  engine.setShapeEditorOverrides(shapeEditorOverrides);
+}
+
+function updateCustomShapeParamControls(layers) {
+  const entries = customShapeParamControlEntries(layers, customShapeParamOverrides);
+  const signature = customShapeParamControlsSignatureFor(entries);
+  if (signature === customShapeParamControlsSignature) {
+    return;
+  }
+
+  customShapeParamControlsSignature = signature;
+  customShapeParamOverrides = pruneCustomShapeParamOverrides(customShapeParamOverrides, entries);
+  renderCustomShapeParamControls(entries);
+}
+
+function customShapeParamControlsSignatureFor(entries) {
+  return entries.map((entry) => (
+    `${entry.key}:${entry.min}:${entry.max}:${entry.step}:${entry.value}`
+  )).join("|");
+}
+
+function renderCustomShapeParamControls(entries) {
+  if (!customShapeParamControlsElement) {
+    return;
+  }
+
+  if (!entries.length) {
+    customShapeParamControlsElement.hidden = true;
+    customShapeParamControlsElement.replaceChildren();
+    return;
+  }
+
+  const title = document.createElement("p");
+  title.className = "shader-param-controls__title";
+  title.textContent = "Custom Shape Params";
+  const controls = entries.map((entry) => createCustomShapeParamControl(entry));
+  customShapeParamControlsElement.replaceChildren(title, ...controls);
+  customShapeParamControlsElement.hidden = false;
+}
+
+function createCustomShapeParamControl(entry) {
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const input = document.createElement("input");
+  const value = document.createElement("output");
+  name.textContent = entry.label;
+  input.type = "range";
+  input.min = String(entry.min);
+  input.max = String(entry.max);
+  input.step = String(entry.step);
+  input.value = String(entry.value);
+  value.value = formatShaderParamValue(entry.value);
+  input.addEventListener("input", () => {
+    const numeric = Number(input.value);
+    customShapeParamOverrides[entry.layerKey] ||= {};
+    customShapeParamOverrides[entry.layerKey][entry.customShapeIndex] ||= {};
+    customShapeParamOverrides[entry.layerKey][entry.customShapeIndex][entry.paramName] = numeric;
+    client.send("custom_shape_param", customShapeParamMessage(entry, numeric));
+    value.value = formatShaderParamValue(numeric);
+  });
+  label.append(name, input, value);
+  return label;
+}
+
+function updateMappingTargetSelector(layers) {
+  const options = mappingTargetOptions(layers);
+  const signature = mappingTargetSignature(options);
+  if (signature === mappingTargetSelectorSignature) {
+    return;
+  }
+
+  mappingTargetSelectorSignature = signature;
+  renderMappingTargetSelector(options);
+}
+
+function renderMappingTargetSelector(options) {
+  if (!mappingTargetSelectorElement) {
+    return;
+  }
+
+  if (!options.length) {
+    selectedMappingTarget = "";
+    mappingTargetSelectorElement.hidden = true;
+    mappingTargetSelectorElement.replaceChildren();
+    return;
+  }
+
+  const title = document.createElement("p");
+  title.className = "shader-param-controls__title";
+  title.textContent = "Mapping Targets";
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const select = document.createElement("select");
+  const output = document.createElement("output");
+  name.textContent = "Target";
+  options.forEach((option) => {
+    const item = document.createElement("option");
+    item.value = option.target;
+    item.textContent = option.label;
+    select.append(item);
+  });
+  if (!options.some((option) => option.target === selectedMappingTarget)) {
+    selectedMappingTarget = options[0].target;
+  }
+  select.value = selectedMappingTarget;
+  output.value = selectedMappingTarget;
+  select.addEventListener("change", () => {
+    selectedMappingTarget = select.value;
+    output.value = select.value;
+  });
+  label.append(name, select, output);
+  mappingTargetSelectorElement.replaceChildren(title, label);
+  mappingTargetSelectorElement.hidden = false;
+}
+
 function requestSceneSwitch(sceneName) {
   if (!sceneName || sceneName === currentSceneName) {
     return;

data/frontend/src/mapping-target-selector.js

@@ -0,0 +1,109 @@
+const SHAPE_TARGETS = {
+  circle: ["x", "y", "radius", "segments", "count"],
+  line: ["x1", "y1", "x2", "y2"],
+  rect: ["x", "y", "width", "height", "radius"],
+  polygon: [],
+  polyline: [],
+  path: ["detail", "tolerance", "max_segments"],
+  star: ["x", "y", "points", "radius", "inner_radius", "rotation"],
+};
+
+const COMMON_SHAPE_TARGETS = [
+  "opacity",
+  "stroke_width",
+  "transform.translate.x",
+  "transform.translate.y",
+  "transform.rotate",
+  "transform.scale",
+  "transform.scale.x",
+  "transform.scale.y",
+  "transform.origin.x",
+  "transform.origin.y",
+];
+
+export const mappingTargetOptions = (layers) => {
+  const options = [];
+  const seen = new Set();
+  const layerList = Array.isArray(layers) ? layers : [];
+
+  layerList.forEach((layer, layerIndex) => {
+    const layerName = String(layer?.name || `layer_${layerIndex + 1}`);
+    appendLayerParamTargets(options, seen, layer, layerName);
+    appendShapeTargets(options, seen, layer, layerName);
+    appendCustomShapeTargets(options, seen, layer, layerName);
+  });
+
+  return options;
+};
+
+export const mappingTargetSignature = (options) => (
+  (Array.isArray(options) ? options : []).map((option) => `${option.layerName}:${option.target}`).join("|")
+);
+
+const appendLayerParamTargets = (options, seen, layer, layerName) => {
+  const schema = Array.isArray(layer?.param_schema) ? layer.param_schema : [];
+  schema.forEach((entry) => {
+    const paramName = normalizeName(entry?.name);
+    if (!paramName) return;
+
+    appendOption(options, seen, {
+      layerName,
+      target: paramName,
+      label: `${layerName}.${paramName}`,
+      scope: "layer",
+    });
+  });
+};
+
+const appendShapeTargets = (options, seen, layer, layerName) => {
+  const shapes = Array.isArray(layer?.params?.shapes) ? layer.params.shapes : [];
+  shapes.forEach((shape, shapeIndex) => {
+    const kind = String(shape?.kind || shape?.type || "").toLowerCase();
+    const shapeName = normalizeName(shape?.id) || `shape_${shapeIndex + 1}`;
+    const targets = [...COMMON_SHAPE_TARGETS, ...(SHAPE_TARGETS[kind] || [])];
+    targets.forEach((target) => {
+      appendOption(options, seen, {
+        layerName,
+        target: `shapes.${shapeIndex}.${target}`,
+        label: `${layerName}.${shapeName}.${target}`,
+        scope: "shape",
+      });
+    });
+  });
+};
+
+const appendCustomShapeTargets = (options, seen, layer, layerName) => {
+  const controls = Array.isArray(layer?.params?.custom_shape_controls) ? layer.params.custom_shape_controls : [];
+  controls.forEach((control, fallbackIndex) => {
+    const index = finiteIndex(control?.index, fallbackIndex);
+    const customShapeName = normalizeName(control?.name) || `custom_shape_${index + 1}`;
+    const params = control?.params && typeof control.params === "object" ? Object.keys(control.params) : [];
+    const schemaNames = (Array.isArray(control?.param_schema) ? control.param_schema : []).map((entry) => normalizeName(entry?.name)).filter(Boolean);
+    [...new Set([...schemaNames, ...params])].sort().forEach((paramName) => {
+      appendOption(options, seen, {
+        layerName,
+        target: `custom_shapes.${index}.params.${paramName}`,
+        label: `${layerName}.${customShapeName}.${paramName}`,
+        scope: "custom_shape",
+      });
+    });
+  });
+};
+
+const appendOption = (options, seen, option) => {
+  const key = `${option.layerName}:${option.target}`;
+  if (seen.has(key)) return;
+
+  seen.add(key);
+  options.push({ ...option, key });
+};
+
+const normalizeName = (value) => {
+  const name = String(value || "").trim();
+  return name || null;
+};
+
+const finiteIndex = (value, fallback) => {
+  const numeric = Number(value);
+  return Number.isInteger(numeric) && numeric >= 0 ? numeric : fallback;
+};

data/frontend/src/renderer/engine.js

@@ -1,6 +1,7 @@
 import { LayerManager } from "./layer-manager.js";
 import { ShaderManager } from "./shader-manager.js";
 import { applyShaderParamOverrides } from "../shader-param-controls.js";
+import { applyShapeEditorOverrides } from "../shape-editor-controls.js";
 
 export class Engine {
   constructor(canvas) {
@@ -27,6 +28,7 @@ export class Engine {
     };
     this.runtimeGlobals = {};
     this.shaderParamOverrides = {};
+    this.shapeEditorOverrides = {};
     this.beatHoldUntil = 0;
     this.frame = {
       audio: {
@@ -98,6 +100,10 @@ export class Engine {
     this.shaderParamOverrides = overrides && typeof overrides === "object" ? overrides : {};
   }
 
+  setShapeEditorOverrides(overrides = {}) {
+    this.shapeEditorOverrides = overrides && typeof overrides === "object" ? overrides : {};
+  }
+
   start() {
     this.lastTime = performance.now();
     requestAnimationFrame((time) => this.render(time));
@@ -156,7 +162,10 @@ export class Engine {
     });
     this.visualAudioState = audio;
     const rawLayers = Array.isArray(this.frame?.scene?.layers) ? this.frame.scene.layers : [];
-    const layers = applyShaderParamOverrides(rawLayers, this.shaderParamOverrides);
+    const layers = applyShapeEditorOverrides(
+      applyShaderParamOverrides(rawLayers, this.shaderParamOverrides),
+      this.shapeEditorOverrides
+    );
     const amplitude = clamp(Number(audio.amplitude || 0), 0, 1);
     const rotationSpeed = resolveRotationSpeed(layers, amplitude);
     this.currentRotationSpeed += (rotationSpeed - this.currentRotationSpeed) * 0.1;

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";
@@ -205,6 +206,7 @@ export class LayerManager {
     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);
@@ -274,7 +276,7 @@ export class LayerManager {
       return;
     }
     if (isShapeLayer(layer)) {
-      this.renderShapeLayer(layer, audio, paletteIndex);
+      this.renderShapeLayer(layer, audio, time, resolution, paletteIndex);
       return;
     }
     if (isShaderLayer(layer)) {
@@ -556,16 +558,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);
   }

data/frontend/src/shape-editor-controls.js

@@ -0,0 +1,157 @@
+const SHAPE_KINDS = ["circle", "line", "rect", "polygon", "polyline", "path", "star"];
+
+export const shapeEditorLayerKey = (layer, index) => `${index}:${String(layer?.name || "layer")}`;
+
+export const shapeEditorEntries = (layers, overrides = {}) => {
+  const entries = [];
+  const layerList = Array.isArray(layers) ? layers : [];
+
+  layerList.forEach((layer, layerIndex) => {
+    const shapes = Array.isArray(layer?.params?.shapes) ? layer.params.shapes : [];
+    if (!shapes.length) return;
+
+    const layerKey = shapeEditorLayerKey(layer, layerIndex);
+    const layerName = String(layer?.name || `layer_${layerIndex + 1}`);
+    shapes.forEach((shape, shapeIndex) => {
+      const edited = applyShapePatch(shape, overrides?.[layerKey]?.[shapeIndex]);
+      const id = String(edited?.id || `shape_${shapeIndex + 1}`);
+      const kind = normalizeKind(edited?.kind || edited?.type);
+      entries.push({
+        key: `${layerKey}:shapes.${shapeIndex}`,
+        layerKey,
+        layerName,
+        shapeIndex,
+        shapeId: id,
+        label: `${layerName}.${id}`,
+        kind,
+        values: shapeEditorValues(edited, kind),
+      });
+    });
+  });
+
+  return entries;
+};
+
+export const applyShapeEditorOverrides = (layers, overrides = {}) => {
+  const layerList = Array.isArray(layers) ? layers : [];
+
+  return layerList.map((layer, layerIndex) => {
+    const shapes = Array.isArray(layer?.params?.shapes) ? layer.params.shapes : null;
+    if (!shapes) return layer;
+
+    const layerKey = shapeEditorLayerKey(layer, layerIndex);
+    const layerOverrides = overrides?.[layerKey];
+    if (!layerOverrides || typeof layerOverrides !== "object") return layer;
+
+    return {
+      ...layer,
+      params: {
+        ...(layer?.params || {}),
+        shapes: shapes.map((shape, shapeIndex) => applyShapePatch(shape, layerOverrides[shapeIndex])),
+      },
+    };
+  });
+};
+
+export const pruneShapeEditorOverrides = (overrides = {}, entries = []) => {
+  const validKeys = new Set(entries.map((entry) => `${entry.layerKey}:${entry.shapeIndex}`));
+  const next = {};
+
+  Object.entries(overrides || {}).forEach(([layerKey, layerOverrides]) => {
+    if (!layerOverrides || typeof layerOverrides !== "object") return;
+
+    Object.entries(layerOverrides).forEach(([shapeIndex, patch]) => {
+      if (!validKeys.has(`${layerKey}:${shapeIndex}`) || !patch || typeof patch !== "object") return;
+
+      next[layerKey] ||= {};
+      next[layerKey][shapeIndex] = patch;
+    });
+  });
+
+  return next;
+};
+
+export const normalizeShapeEditorPatch = (values = {}) => {
+  const kind = normalizeKind(values.kind);
+  const output = {
+    kind,
+    opacity: clamp(finiteNumber(values.opacity, 1), 0, 1),
+    stroke_width: Math.max(0, finiteNumber(values.strokeWidth ?? values.stroke_width, 1)),
+    transform: {
+      translate: {
+        x: finiteNumber(values.translateX, 0),
+        y: finiteNumber(values.translateY, 0),
+      },
+      rotate: finiteNumber(values.rotate, 0),
+      scale: {
+        x: clamp(finiteNumber(values.scaleX, 1), -8, 8),
+        y: clamp(finiteNumber(values.scaleY, 1), -8, 8),
+      },
+    },
+  };
+  if (values.fillEnabled !== false && validColor(values.fill)) output.fill = values.fill;
+  if (values.strokeColorEnabled !== false && validColor(values.strokeColor ?? values.stroke_color)) {
+    output.stroke_color = values.strokeColor ?? values.stroke_color;
+  }
+  return output;
+};
+
+const shapeEditorValues = (shape, kind) => {
+  const transform = shape?.transform || {};
+  const translate = vectorValue(transform.translate ?? shape?.translate, { x: 0, y: 0 });
+  const scale = vectorValue(transform.scale ?? shape?.scale, { x: 1, y: 1 });
+  return {
+    kind,
+    translateX: translate.x,
+    translateY: translate.y,
+    rotate: finiteNumber(transform.rotate ?? shape?.rotate ?? shape?.rotation, 0),
+    scaleX: scale.x,
+    scaleY: scale.y,
+    opacity: clamp(finiteNumber(shape?.opacity, 1), 0, 1),
+    fill: validColor(shape?.fill) ? shape.fill : "#000000",
+    fillEnabled: validColor(shape?.fill),
+    strokeColor: validColor(shape?.stroke_color ?? shape?.strokeColor) ? (shape.stroke_color ?? shape.strokeColor) : "#ffffff",
+    strokeColorEnabled: validColor(shape?.stroke_color ?? shape?.strokeColor),
+    strokeWidth: Math.max(0, finiteNumber(shape?.stroke_width ?? shape?.strokeWidth ?? shape?.stroke, 1)),
+  };
+};
+
+const applyShapePatch = (shape, patch) => {
+  if (!patch || typeof patch !== "object") return shape;
+
+  return {
+    ...(shape || {}),
+    ...patch,
+    transform: {
+      ...((shape || {}).transform || {}),
+      ...(patch.transform || {}),
+    },
+  };
+};
+
+const vectorValue = (value, fallback) => {
+  if (Array.isArray(value)) {
+    return { x: finiteNumber(value[0], fallback.x), y: finiteNumber(value[1], fallback.y) };
+  }
+
+  if (value && typeof value === "object") {
+    return { x: finiteNumber(value.x, fallback.x), y: finiteNumber(value.y, fallback.y) };
+  }
+
+  const numeric = finiteNumber(value, null);
+  return numeric === null ? fallback : { x: numeric, y: numeric };
+};
+
+const normalizeKind = (value) => {
+  const kind = String(value || "circle").trim().toLowerCase();
+  return SHAPE_KINDS.includes(kind) ? kind : "circle";
+};
+
+const validColor = (value) => /^#[0-9a-f]{6}$/i.test(String(value || ""));
+
+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);