vizcore 0.1.0 → 1.1.0

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/midi-learn.js

@@ -0,0 +1,194 @@
+export const MIDI_LEARN_BINDINGS_KEY = "vizcore.midiLearnBindings.v1";
+
+const ACTION_TYPES = new Set(["switch_scene", "live_control", "visual_setting"]);
+const LIVE_CONTROLS = new Set(["blackout", "freeze"]);
+const VISUAL_SETTING_KEYS = new Set(["visualGain", "bassBoost", "smoothing", "beatHoldMs", "wobbleAmount"]);
+
+export const loadMidiLearnBindings = (storage, {
+  key = MIDI_LEARN_BINDINGS_KEY,
+} = {}) => {
+  if (!storage) {
+    return {};
+  }
+
+  try {
+    return normalizeMidiLearnBindings(JSON.parse(storage.getItem(key) || "{}"));
+  } catch {
+    return {};
+  }
+};
+
+export const saveMidiLearnBindings = (storage, bindings, {
+  key = MIDI_LEARN_BINDINGS_KEY,
+} = {}) => {
+  const normalized = normalizeMidiLearnBindings(bindings);
+  if (!storage) {
+    return normalized;
+  }
+
+  try {
+    storage.setItem(key, JSON.stringify(normalized));
+  } catch {
+    // Ignore storage failures; learned bindings still work for this session.
+  }
+  return normalized;
+};
+
+export const normalizeMidiLearnBindings = (bindings) => {
+  const input = bindings && typeof bindings === "object" ? bindings : {};
+  const normalized = {};
+
+  for (const [signature, action] of Object.entries(input)) {
+    const safeSignature = normalizeMidiSignature(signature);
+    const safeAction = normalizeMidiAction(action);
+    if (!safeSignature || !safeAction) {
+      continue;
+    }
+    normalized[safeSignature] = safeAction;
+  }
+
+  return normalized;
+};
+
+export const upsertMidiLearnBinding = (bindings, signature, action) => {
+  const safeSignature = normalizeMidiSignature(signature);
+  const safeAction = normalizeMidiAction(action);
+  const next = normalizeMidiLearnBindings(bindings);
+
+  if (safeSignature && safeAction) {
+    next[safeSignature] = safeAction;
+  }
+
+  return next;
+};
+
+export const midiMessageSignature = (data) => {
+  const bytes = normalizeMidiBytes(data);
+  if (!bytes.length) {
+    return null;
+  }
+
+  const status = bytes[0];
+  const command = status & 0xf0;
+  const channel = (status & 0x0f) + 1;
+  if (command === 0x80 || command === 0x90) {
+    return `note:${channel}:${bytes[1] ?? 0}`;
+  }
+  if (command === 0xb0) {
+    return `cc:${channel}:${bytes[1] ?? 0}`;
+  }
+  if (command === 0xc0) {
+    return `pc:${channel}:${bytes[1] ?? 0}`;
+  }
+  return `raw:${channel}:${status}:${bytes[1] ?? 0}`;
+};
+
+export const midiMessageActive = (data) => {
+  const bytes = normalizeMidiBytes(data);
+  if (!bytes.length) {
+    return false;
+  }
+
+  const command = bytes[0] & 0xf0;
+  if (command === 0x80) {
+    return false;
+  }
+  if (command === 0x90) {
+    return Number(bytes[2] || 0) > 0;
+  }
+  return true;
+};
+
+export const midiMessageUnitValue = (data) => {
+  const bytes = normalizeMidiBytes(data);
+  if (!bytes.length) {
+    return 0;
+  }
+
+  const command = bytes[0] & 0xf0;
+  if (command === 0xb0 || command === 0x90 || command === 0x80) {
+    return clampUnit(Number(bytes[2] || 0) / 127);
+  }
+  if (command === 0xc0) {
+    return clampUnit(Number(bytes[1] || 0) / 127);
+  }
+  return 1;
+};
+
+export const midiLearnActionLabel = (action) => {
+  const safeAction = normalizeMidiAction(action);
+  if (!safeAction) {
+    return "Unknown";
+  }
+
+  if (safeAction.type === "switch_scene") {
+    return `Switch scene: ${safeAction.scene}`;
+  }
+  if (safeAction.type === "live_control") {
+    return `Toggle ${safeAction.control}`;
+  }
+  return `Control ${visualSettingLabel(safeAction.key)}`;
+};
+
+export const midiSignatureLabel = (signature) => {
+  const [kind, channel, value] = String(signature || "").split(":");
+  if (kind === "note") return `Note ${value} ch ${channel}`;
+  if (kind === "cc") return `CC ${value} ch ${channel}`;
+  if (kind === "pc") return `Program ${value} ch ${channel}`;
+  return signature || "unknown";
+};
+
+const normalizeMidiAction = (action) => {
+  if (!action || typeof action !== "object") {
+    return null;
+  }
+
+  const type = String(action.type || "");
+  if (!ACTION_TYPES.has(type)) {
+    return null;
+  }
+
+  if (type === "switch_scene") {
+    const scene = String(action.scene || "").trim();
+    return scene ? { type, scene } : null;
+  }
+
+  if (type === "live_control") {
+    const control = String(action.control || "").trim();
+    return LIVE_CONTROLS.has(control) ? { type, control } : null;
+  }
+
+  const key = String(action.key || "").trim();
+  return VISUAL_SETTING_KEYS.has(key) ? { type, key } : null;
+};
+
+const normalizeMidiSignature = (signature) => {
+  const value = String(signature || "").trim().toLowerCase();
+  return value.includes(":") ? value : null;
+};
+
+const normalizeMidiBytes = (data) => {
+  if (Array.isArray(data) || ArrayBuffer.isView(data)) {
+    return Array.from(data).map((value) => Number(value) || 0);
+  }
+  return [];
+};
+
+const visualSettingLabel = (key) => {
+  switch (key) {
+    case "visualGain":
+      return "Visual Gain";
+    case "bassBoost":
+      return "Bass Boost";
+    case "smoothing":
+      return "Smoothing";
+    case "beatHoldMs":
+      return "Beat Hold";
+    case "wobbleAmount":
+      return "Wobble";
+    default:
+      return key;
+  }
+};
+
+const clampUnit = (value) => Math.min(Math.max(Number(value) || 0, 0), 1);

data/frontend/src/performance-monitor.js

@@ -0,0 +1,183 @@
+const DEFAULT_EXPECTED_FRAME_MS = 1000 / 60;
+const FPS_WINDOW_MS = 500;
+
+export const createPerformanceMonitorState = () => ({
+  audioLatencyMs: null,
+  clockOffsetMs: null,
+  droppedFrames: 0,
+  fps: 0,
+  frameMs: 0,
+  lastRenderAtMs: null,
+  lastSocketTimestampMs: null,
+  reconnects: 0,
+  renderWindowFrames: 0,
+  renderWindowStartedAtMs: null,
+  rttMs: null,
+  shaderCompileMs: null,
+  wsLatencyMs: null,
+});
+
+export const recordRenderFrame = (state, nowMs) => {
+  const now = Number(nowMs);
+  if (!Number.isFinite(now)) {
+    return { ...state };
+  }
+
+  const previousRenderAt = Number.isFinite(state?.lastRenderAtMs) ? state.lastRenderAtMs : null;
+  const frameMs = previousRenderAt === null ? 0 : Math.max(0, now - previousRenderAt);
+  const windowStartedAt = Number.isFinite(state?.renderWindowStartedAtMs)
+    ? state.renderWindowStartedAtMs
+    : now;
+  const windowFrames = Number(state?.renderWindowFrames || 0) + 1;
+  const windowMs = now - windowStartedAt;
+
+  if (windowMs >= FPS_WINDOW_MS) {
+    return {
+      ...state,
+      fps: roundOneDecimal((windowFrames * 1000) / windowMs),
+      frameMs: roundOneDecimal(frameMs),
+      lastRenderAtMs: now,
+      renderWindowFrames: 0,
+      renderWindowStartedAtMs: now,
+    };
+  }
+
+  return {
+    ...state,
+    frameMs: roundOneDecimal(frameMs),
+    lastRenderAtMs: now,
+    renderWindowFrames: windowFrames,
+    renderWindowStartedAtMs: windowStartedAt,
+  };
+};
+
+export const recordSocketFrame = (
+  state,
+  frame,
+  receivedAtMs,
+  expectedFrameMs = DEFAULT_EXPECTED_FRAME_MS,
+) => {
+  const timestampMs = Number(frame?.timestamp) * 1000;
+  const receivedAt = Number(receivedAtMs);
+  if (!Number.isFinite(timestampMs) || timestampMs <= 0 || !Number.isFinite(receivedAt)) {
+    return { ...state };
+  }
+
+  const previousTimestamp = Number.isFinite(state?.lastSocketTimestampMs)
+    ? state.lastSocketTimestampMs
+    : null;
+  const frameGapMs = previousTimestamp === null ? 0 : Math.max(0, timestampMs - previousTimestamp);
+  const droppedFrames = Number(state?.droppedFrames || 0) + estimateDroppedFrames(frameGapMs, expectedFrameMs);
+  const audioLatencyMs = audioLatencyFromMetrics(frame?.metrics, state?.audioLatencyMs);
+  const clockOffsetMs = Number.isFinite(state?.clockOffsetMs) ? Number(state.clockOffsetMs) : 0;
+  const browserTimestampMs = timestampMs - clockOffsetMs;
+
+  return {
+    ...state,
+    audioLatencyMs,
+    droppedFrames,
+    lastSocketTimestampMs: timestampMs,
+    wsLatencyMs: Math.max(0, Math.round(receivedAt - browserTimestampMs)),
+  };
+};
+
+export const recordLatencyProbe = (state, payload, receivedAtMs) => {
+  const clientSentAtMs = Number(payload?.client_sent_at_ms);
+  const serverReceivedAtMs = Number(payload?.server_received_at_ms);
+  const serverSentAtMs = Number(payload?.server_sent_at_ms);
+  const browserReceivedAtMs = Number(receivedAtMs);
+
+  if (
+    !Number.isFinite(clientSentAtMs) ||
+    !Number.isFinite(serverReceivedAtMs) ||
+    !Number.isFinite(serverSentAtMs) ||
+    !Number.isFinite(browserReceivedAtMs) ||
+    browserReceivedAtMs < clientSentAtMs ||
+    serverSentAtMs < serverReceivedAtMs
+  ) {
+    return { ...state };
+  }
+
+  const serverProcessingMs = serverSentAtMs - serverReceivedAtMs;
+  const rttMs = Math.max(0, browserReceivedAtMs - clientSentAtMs - serverProcessingMs);
+  const clockOffsetMs = ((serverReceivedAtMs - clientSentAtMs) + (serverSentAtMs - browserReceivedAtMs)) / 2;
+
+  return {
+    ...state,
+    clockOffsetMs: Math.round(clockOffsetMs),
+    rttMs: Math.round(rttMs),
+  };
+};
+
+export const recordConnectionStatus = (state, status) => {
+  if (status !== "reconnecting") {
+    return { ...state };
+  }
+
+  return {
+    ...state,
+    reconnects: Number(state?.reconnects || 0) + 1,
+  };
+};
+
+export const recordShaderCompile = (state, detail) => {
+  const compileMs = coerceMetric(detail?.compileMs);
+  if (compileMs === null) {
+    return { ...state };
+  }
+
+  return {
+    ...state,
+    shaderCompileMs: compileMs,
+  };
+};
+
+export const formatPerformanceMonitorText = (state) => {
+  const fps = Number(state?.fps || 0) > 0 ? Number(state.fps).toFixed(1) : "--";
+  const frameMs = Number(state?.frameMs || 0) > 0 ? `${Number(state.frameMs).toFixed(1)}ms` : "--";
+  const wsLatency = Number.isFinite(state?.wsLatencyMs) ? `${Math.round(state.wsLatencyMs)}ms` : "--";
+  const rtt = Number.isFinite(state?.rttMs) ? `${Math.round(state.rttMs)}ms` : "--";
+  const clockOffset = Number.isFinite(state?.clockOffsetMs) ? `${formatSignedInteger(state.clockOffsetMs)}ms` : "--";
+  const audioLatency = Number.isFinite(state?.audioLatencyMs) ? `${Number(state.audioLatencyMs).toFixed(1)}ms` : "--";
+  const shaderCompile = Number.isFinite(state?.shaderCompileMs) ? `${Number(state.shaderCompileMs).toFixed(1)}ms` : "--";
+  const droppedFrames = Math.max(0, Number(state?.droppedFrames || 0));
+  const reconnects = Math.max(0, Number(state?.reconnects || 0));
+
+  return `Perf: ${fps} FPS | Frame ${frameMs} | WS ${wsLatency} | RTT ${rtt} | Clock ${clockOffset} | Drop ${droppedFrames} | Audio ${audioLatency} | Shader ${shaderCompile} | Reconnect ${reconnects}`;
+};
+
+export const estimateDroppedFrames = (frameGapMs, expectedFrameMs = DEFAULT_EXPECTED_FRAME_MS) => {
+  const gap = Number(frameGapMs);
+  const expected = Number(expectedFrameMs);
+  if (!Number.isFinite(gap) || !Number.isFinite(expected) || gap <= expected * 1.75) {
+    return 0;
+  }
+
+  return Math.max(0, Math.round(gap / expected) - 1);
+};
+
+const audioLatencyFromMetrics = (metrics, fallback) => {
+  const captureMs = coerceMetric(metrics?.audio_capture_ms);
+  const analysisMs = coerceMetric(metrics?.audio_analysis_ms);
+  if (captureMs === null && analysisMs === null) {
+    return fallback ?? null;
+  }
+
+  return (captureMs || 0) + (analysisMs || 0);
+};
+
+const coerceMetric = (value) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return null;
+  }
+
+  return Math.max(0, numeric);
+};
+
+const roundOneDecimal = (value) => Math.round(value * 10) / 10;
+
+const formatSignedInteger = (value) => {
+  const rounded = Math.round(Number(value) || 0);
+  return rounded > 0 ? `+${rounded}` : `${rounded}`;
+};

data/frontend/src/plugin-runtime.js

@@ -0,0 +1,130 @@
+export const VIZCORE_PLUGIN_API_VERSION = 1;
+
+const layerRenderers = new Map();
+const shaderRenderers = new Map();
+
+export const registerLayerRenderer = (type, renderer) => {
+  const key = normalizeLayerType(type);
+  if (!key || typeof renderer !== "function") {
+    return false;
+  }
+
+  layerRenderers.set(key, renderer);
+  return true;
+};
+
+export const unregisterLayerRenderer = (type) => {
+  const key = normalizeLayerType(type);
+  return key ? layerRenderers.delete(key) : false;
+};
+
+export const resolveLayerRenderer = (type) => {
+  return layerRenderers.get(normalizeLayerType(type)) || null;
+};
+
+export const registeredLayerRendererTypes = () => Array.from(layerRenderers.keys()).sort();
+
+export const registerShaderRenderer = (type, renderer) => {
+  const key = normalizeLayerType(type);
+  if (!key || typeof renderer !== "function") {
+    return false;
+  }
+
+  shaderRenderers.set(key, renderer);
+  return true;
+};
+
+export const unregisterShaderRenderer = (type) => {
+  const key = normalizeLayerType(type);
+  return key ? shaderRenderers.delete(key) : false;
+};
+
+export const resolveShaderRenderer = (type) => {
+  return shaderRenderers.get(normalizeLayerType(type)) || null;
+};
+
+export const registeredShaderRendererTypes = () => Array.from(shaderRenderers.keys()).sort();
+
+export const normalizePluginLineOutput = (output) => {
+  const input = output && typeof output === "object" ? output : {};
+  const kind = String(input.kind || "lines").toLowerCase();
+  if (kind !== "lines") {
+    return null;
+  }
+
+  const points = Array.isArray(input.points) || ArrayBuffer.isView(input.points)
+    ? Array.from(input.points).map((value) => Number(value)).filter(Number.isFinite)
+    : [];
+  if (points.length < 4) {
+    return null;
+  }
+
+  return {
+    kind: "lines",
+    points: points.length % 2 === 0 ? points : points.slice(0, -1),
+    color: normalizeRgb(input.color),
+  };
+};
+
+export const normalizePluginShaderOutput = (output) => {
+  const input = typeof output === "string"
+    ? { kind: "shader", fragmentShader: output }
+    : output && typeof output === "object" ? output : {};
+  const kind = String(input.kind || "shader").toLowerCase();
+  if (kind !== "shader") {
+    return null;
+  }
+
+  const fragmentShader = String(input.fragmentShader || input.source || input.glsl || "").trim();
+  if (!fragmentShader) {
+    return null;
+  }
+
+  return {
+    kind: "shader",
+    fragmentShader,
+    cacheKey: String(input.cacheKey || input.name || "plugin-shader"),
+  };
+};
+
+export const installGlobalPluginRuntime = (target = globalThis) => {
+  if (!target || typeof target !== "object") {
+    return null;
+  }
+
+  const runtime = {
+    apiVersion: VIZCORE_PLUGIN_API_VERSION,
+    registerLayerRenderer,
+    unregisterLayerRenderer,
+    resolveLayerRenderer,
+    registeredLayerRendererTypes,
+    registerShaderRenderer,
+    unregisterShaderRenderer,
+    resolveShaderRenderer,
+    registeredShaderRendererTypes,
+  };
+  target.VizcorePlugins = {
+    ...(target.VizcorePlugins || {}),
+    ...runtime,
+  };
+  if (typeof target.dispatchEvent === "function" && typeof target.Event === "function") {
+    target.dispatchEvent(new target.Event("vizcore:plugins-ready"));
+  }
+  return target.VizcorePlugins;
+};
+
+const normalizeLayerType = (type) => String(type || "").trim().toLowerCase();
+
+const normalizeRgb = (value) => {
+  const values = Array.isArray(value) ? value : [];
+  if (values.length < 3) {
+    return null;
+  }
+
+  const rgb = values.slice(0, 3).map((entry) => Number(entry));
+  return rgb.every(Number.isFinite)
+    ? rgb.map((entry) => Math.min(Math.max(entry, 0), 1))
+    : null;
+};
+
+installGlobalPluginRuntime();

data/frontend/src/projector-mode.js

@@ -0,0 +1,56 @@
+export const resolveProjectorMode = ({ body, current = false, location, runtime } = {}) => {
+  if (controlModeFromBody(body) || controlModeFromLocation(location)) {
+    return false;
+  }
+
+  return current
+    || projectorModeFromBody(body)
+    || projectorModeFromLocation(location)
+    || projectorModeFromRuntime(runtime);
+};
+
+export const applyProjectorMode = (body, enabled) => {
+  if (!body) {
+    return;
+  }
+
+  const active = !!enabled;
+  if (body.classList && typeof body.classList.toggle === "function") {
+    body.classList.toggle("is-projector", active);
+  }
+
+  if (body.dataset) {
+    body.dataset.projectorMode = active ? "true" : "false";
+  }
+};
+
+export const projectorModeFromRuntime = (runtime) => truthyValue(runtime?.projector_mode);
+
+export const projectorModeFromBody = (body) => truthyValue(body?.dataset?.projectorMode);
+
+export const controlModeFromBody = (body) => body?.dataset?.displayMode === "control";
+
+export const projectorModeFromLocation = (location) => {
+  const search = String(location?.search || "");
+  if (!search) {
+    return false;
+  }
+
+  const params = new URLSearchParams(search);
+  return truthyValue(params.get("projector")) || params.get("mode") === "projector";
+};
+
+export const controlModeFromLocation = (location) => {
+  const search = String(location?.search || "");
+  if (!search) {
+    return false;
+  }
+
+  const params = new URLSearchParams(search);
+  return truthyValue(params.get("control")) || params.get("mode") === "control";
+};
+
+const truthyValue = (value) => {
+  const normalized = String(value || "").trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+};