tesseract.js

/* Copyright 2026 Michael Pilosov. All rights reserved. */
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { installSkyboxLibrary } from './viewer-skyboxes.js';
import { installVisualMusic } from './visual-music.js';

// Main Three.js scene setup
let scene, camera, renderer, controls;
const physicalLights = [];
let shadowState = '';
let tesseract;
let visualMusic;
let restoredMusicSettings = null;
let currentShape = 'tesseract';
let rotationSpeed = 0.005;
let time = 0;
let animationPaused = true;
let timelineFrame = 0;
let exportFps = 60;
let videoExportWidth = 1920;
let videoExportHeight = 1080;
let videoExportQuality = 'standard';
let videoExportRunning = false;
let activeVideoExportJob = null;
let activeVideoExportPlan = null;
let cancelVideoExportRequested = false;
let videoExportAbort = null;
let videoExportStopAction = null;
let videoExportStopPromise = null;
let videoExportStopJobId = null;
let videoCaptureSurface = null;
let videoCaptureContext = null;
let videoCaptureFallback = false;
let loopTiming = { period: 0, frameCount: 1, timeStep: 0, exact: true };
let lastAnimationTimestamp = null;
let frameAccumulator = 0;
// Track object references
let vertices = [];
let edges = [];
let faces = [];
// Rotation coefficients
let rotationCoefficients = {
    xw: 0.0,
    yw: 0.0,
    zw: 0.0
};
// Shader options
let currentShader = 'chrome';
// Lighting options
let currentLighting = 'diagonal';
let lightDistance = 0.1;
// UI elements
let controlPanel;
let showVertices = false;
// Chrome's per-pixel grain re-randomizes as the projection moves, so every
// frame carries fresh noise that dominates video bitrate.
let surfaceGrain = true;
// Aged edge grime and dust fixed to each face: texture that moves with the
// glass, so it compresses far better than per-frame grain.
let dirtyMirrors = false;
let mirrorReflections = false;
let mirrorTraceState = null;
let showOverlay = true;
let cameraInfoDisplay;
let motionStepSlider;
let motionStepLabel;
let loopInfoDisplay;
let timelineSlider;
let timelineFrameDisplay;
let timelineFrameInput;
let exportFpsSelect;
let videoExportButton;
let videoExportDialog;
let soundToggle;
let videoExportDialogRequest = 0;
let videoResumeJobsRequest = 0;
let panelExpanded = true;
let videoTimingExpanded = false;
let savedCameraPosition = { x: 3, y: 3, z: 3 };
let savedCameraTarget = { x: 0, y: 0, z: 0 };
const VIEWER_SETTINGS_KEY = 'tesseract.viewer-settings.v1';
const VIDEO_EXPORT_INTERRUPTED_KEY = 'tesseract.video-export-interrupted';
let videoExportWasInterrupted = false;
try {
    videoExportWasInterrupted = sessionStorage.getItem(VIDEO_EXPORT_INTERRUPTED_KEY) === 'yes';
    sessionStorage.removeItem(VIDEO_EXPORT_INTERRUPTED_KEY);
} catch {
    // Session storage is optional; navigation protection still works without it.
}
let publication = null;
try {
    const text = document.getElementById('piece-config')?.textContent.trim();
    if (text) publication = JSON.parse(text);
} catch (error) {
    console.error('Invalid published piece configuration', error);
}
if (publication?.schemaVersion === 1 && publication.title) document.title = publication.title;

function viewerSettings() {
    return {
        shape: currentShape,
        rotationSpeed,
        rotationCoefficients: { ...rotationCoefficients },
        shader: currentShader,
        lighting: currentLighting,
        lightDistance,
        showVertices,
        surfaceGrain,
        dirtyMirrors,
        mirrorReflections,
        animationPaused,
        exportFps,
        videoExportWidth,
        videoExportHeight,
        videoExportQuality,
        timelineFrame,
        panelExpanded,
        videoTimingExpanded,
        music: visualMusic?.settings ?? restoredMusicSettings,
        camera: {
            position: camera ? { x: camera.position.x, y: camera.position.y, z: camera.position.z } : { ...savedCameraPosition },
            target: controls ? { x: controls.target.x, y: controls.target.y, z: controls.target.z } : { ...savedCameraTarget }
        }
    };
}

function defaultViewerSettings() {
    return {
        shape: 'tesseract',
        rotationSpeed: 0.005,
        rotationCoefficients: { xw: 0, yw: 0, zw: 0 },
        shader: 'chrome',
        lighting: 'diagonal',
        lightDistance: 0.1,
        showVertices: false,
        surfaceGrain: true,
        dirtyMirrors: false,
        mirrorReflections: false,
        animationPaused: true,
        exportFps: 60,
        videoExportWidth: 1920,
        videoExportHeight: 1080,
        videoExportQuality: 'standard',
        timelineFrame: 0,
        panelExpanded: true,
        videoTimingExpanded: false,
        music: visualMusic?.defaultSettings ?? { enabled: false },
        camera: {
            position: { x: 3, y: 3, z: 3 },
            target: { x: 0, y: 0, z: 0 }
        }
    };
}

function applyViewerSettings(saved) {
    if (!saved || typeof saved !== 'object') return;
    const clamp = (value, min, max, fallback) => {
        const number = Number(value);
        return Number.isFinite(number) ? Math.min(max, Math.max(min, number)) : fallback;
    };
    setViewerShape(saved.shape || 'tesseract');
    rotationSpeed = clamp(saved.rotationSpeed, 0, 0.01, rotationSpeed);
    lightDistance = clamp(saved.lightDistance, 0.1, 20, lightDistance);
    for (const axis of ['xw', 'yw', 'zw']) {
        rotationCoefficients[axis] = clamp(saved.rotationCoefficients?.[axis], -1, 1, rotationCoefficients[axis]);
    }
    if (['rough', 'iridescent', 'chrome'].includes(saved.shader)) currentShader = saved.shader;
    if (['diagonal', 'topdown', 'quad'].includes(saved.lighting)) currentLighting = saved.lighting;
    if ([24, 25, 30, 50, 60].includes(Number(saved.exportFps))) exportFps = Number(saved.exportFps);
    const videoWidth = Number(saved.videoExportWidth);
    const videoHeight = Number(saved.videoExportHeight);
    if ([[1280, 720], [1920, 1080], [2560, 1440], [3840, 2160], [1080, 1080]].some(([width, height]) => width === videoWidth && height === videoHeight)) {
        videoExportWidth = videoWidth;
        videoExportHeight = videoHeight;
    }
    if (['draft', 'standard', 'high', 'capped', 'master'].includes(saved.videoExportQuality)) videoExportQuality = saved.videoExportQuality;
    if (typeof saved.showVertices === 'boolean') showVertices = saved.showVertices;
    if (typeof saved.surfaceGrain === 'boolean') surfaceGrain = saved.surfaceGrain;
    if (typeof saved.dirtyMirrors === 'boolean') dirtyMirrors = saved.dirtyMirrors;
    if (typeof saved.mirrorReflections === 'boolean') mirrorReflections = saved.mirrorReflections;
    if (typeof saved.animationPaused === 'boolean') animationPaused = saved.animationPaused;
    if (typeof saved.panelExpanded === 'boolean') panelExpanded = saved.panelExpanded;
    if (typeof saved.videoTimingExpanded === 'boolean') videoTimingExpanded = saved.videoTimingExpanded;
    if (saved.music && typeof saved.music === 'object') {
        restoredMusicSettings = saved.music;
        visualMusic?.setSettings(saved.music);
    }
    const vector = (value, fallback) => {
        if (!value || !['x', 'y', 'z'].every(axis => Number.isFinite(Number(value[axis])))) return fallback;
        return { x: Number(value.x), y: Number(value.y), z: Number(value.z) };
    };
    savedCameraPosition = vector(saved.camera?.position, savedCameraPosition);
    savedCameraTarget = vector(saved.camera?.target, savedCameraTarget);
    timelineFrame = Math.max(0, Math.trunc(Number(saved.timelineFrame) || 0));
}

function loadViewerSettings() {
    if (publication?.schemaVersion === 1) {
        applyViewerSettings(publication.viewer);
        // Published work opens as artwork first; controls remain available
        // behind the small corner button.
        panelExpanded = false;
        return;
    }
    try {
        applyViewerSettings(JSON.parse(localStorage.getItem(VIEWER_SETTINGS_KEY)));
    } catch {
        // Keep defaults when local storage is unavailable or contains invalid data.
    }
}

function persistViewerSettings() {
    if (publication?.schemaVersion === 1) return;
    try {
        localStorage.setItem(VIEWER_SETTINGS_KEY, JSON.stringify(viewerSettings()));
    } catch {
        // The viewer remains usable when local storage is blocked or full.
    }
}

loadViewerSettings();
window.addEventListener('beforeunload', event => {
    // Once cancel is requested, don't trap the tab. The in-flight upload is
    // aborted and pagehide tells the server to drop the job.
    if (!videoExportRunning || cancelVideoExportRequested) return;
    event.preventDefault();
    event.returnValue = '';
});
window.addEventListener('pagehide', () => {
    if (activeVideoExportJob && videoExportStopAction !== 'discard') {
        try { sessionStorage.setItem(VIDEO_EXPORT_INTERRUPTED_KEY, 'yes'); } catch { /* Optional. */ }
        const body = new Blob([JSON.stringify({
            id: activeVideoExportJob.id,
            lease: activeVideoExportJob.lease
        })], { type: 'text/plain' });
        navigator.sendBeacon('/api/video/pause', body);
    }
});
window.addEventListener('pageshow', event => {
    // A back/forward-cache restore would otherwise revive a frozen progress UI.
    if (event.persisted && videoExportRunning) location.reload();
});
document.addEventListener('visibilitychange', () => {
    if (document.visibilityState === 'hidden' && !videoExportRunning) persistViewerSettings();
});
// File drop zone
let dropZone;
let dropZoneVisible = false;
// Environment map for reflections
let envMap;
let skyboxLibrary;

// Bound both ends of the view, including restored and programmatic camera changes.
function clampCameraCoordinates() {
    camera.position.clampScalar(-3, 3);
    controls.target.clampScalar(-3, 3);
    camera.lookAt(controls.target);
}

function updatePhysicalLighting() {
    const quad = currentLighting === 'quad';
    const radius = lightDistance;
    physicalLights.forEach((light, index) => {
        light.intensity = quad ? Math.PI : index === 0 ? 4 * Math.PI : 0;
        light.visible = light.castShadow = light.intensity > 0;
        if (quad) {
            light.position.set(index === 0 ? radius : index === 1 ? -radius : 0, 0,
                index === 2 ? radius : index === 3 ? -radius : 0);
        } else if (currentLighting === 'topdown') {
            light.position.set(0, radius, 0);
        } else {
            light.position.setScalar(radius / Math.sqrt(3));
        }
        // scene.onBeforeRender runs after the renderer's matrix traversal.
        light.updateMatrixWorld();
    });
    // Camera movement alone does not invalidate world-space shadow maps.
    const state = `${time}/${currentShape}/${currentLighting}/${lightDistance}/${showVertices}`;
    if (state !== shadowState) {
        renderer.shadowMap.needsUpdate = true;
        shadowState = state;
    }
}

// Initialize the scene
function init() {
    console.log("Initializing...");
    
    // Create scene
    scene = new THREE.Scene();
    for (let i = 0; i < 4; i++) {
        const light = new THREE.PointLight(0xffffff, 0, 0, 2);
        light.shadow.mapSize.set(256, 256);
        light.shadow.camera.near = 0.01;
        light.shadow.camera.far = 40;
        light.shadow.bias = -0.00005;
        light.shadow.normalBias = 0; // Receiver-plane correction handles either side without a normal offset.
        physicalLights.push(light);
        scene.add(light);
    }
    // Runs for live view, screenshots, soundtrack sampling, and video alike.
    scene.onBeforeRender = updatePhysicalLighting;
    
    // Create camera
    camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.01, 1000);
    camera.position.set(savedCameraPosition.x, savedCameraPosition.y, savedCameraPosition.z);
    
    // Create renderer
    renderer = new THREE.WebGLRenderer({ antialias: true });
    // Compress HDR highlights before sRGB encoding instead of clipping them flat.
    renderer.toneMapping = THREE.ACESFilmicToneMapping;
    renderer.toneMappingExposure = 1;
    renderer.shadowMap.enabled = true;
    renderer.shadowMap.type = THREE.PCFShadowMap;
    renderer.shadowMap.autoUpdate = false;
    renderer.setSize(window.innerWidth, window.innerHeight);
    document.body.appendChild(renderer.domElement);
    
    // Add orbit controls
    controls = new OrbitControls(camera, renderer.domElement);
    controls.enableDamping = true;
    controls.dampingFactor = 0.05;
    controls.minDistance = 0.01; // Hard stop for scroll/pinch zoom toward the target.
    controls.target.set(savedCameraTarget.x, savedCameraTarget.y, savedCameraTarget.z);
    controls.addEventListener('change', clampCameraCoordinates);
    clampCameraCoordinates();
    controls.addEventListener('end', persistViewerSettings);
    
    // Create the tesseract
    createTesseract();
    
    // Handle window resize
    window.addEventListener('resize', onWindowResize, false);
    
    // Add keyboard controls
    window.addEventListener('keydown', onKeyDown, false);
    
    // Add UI controls, then connect the soundtrack and export library to the scene.
    createControls();
    visualMusic = installVisualMusic({
        mount: document.getElementById('controlPanelContent'),
        canvas: renderer.domElement,
        sampleFrame: sampleLiveSoundFrame,
        initialSettings: restoredMusicSettings,
        onStateChange: persistViewerSettings,
        onPlaybackChange: updateSoundToggle
    });
    if (publication?.schemaVersion === 1 && publication.viewer?.musicAutoplay === true) {
        visualMusic.requestAutoplay();
    }
    createEnvironmentMap();
    
    // Initialize file upload for loading views
    initFileUpload();
    
    // Create drop zone for file dropping
    createDropZone();
    
    // Setup drag and drop handlers
    setupDragAndDropHandlers();
    
    // Start on a real frame timestamp. A direct call has none, and the first
    // delta would otherwise become NaN and freeze playback until a manual seek.
    requestAnimationFrame(animate);
    
    console.log("Initialization complete");
}

const SOUND_ICONS = {
    on: '<path d="M15.5 8.5a5 5 0 0 1 0 7M18.5 5.5a9 9 0 0 1 0 13"/>',
    off: '<path d="m16 9 6 6m0-6-6 6"/>'
};

function updateSoundToggle(playing) {
    if (!soundToggle) return;
    const label = playing ? 'Mute soundtrack' : 'Play soundtrack';
    soundToggle.setAttribute('aria-label', label);
    soundToggle.setAttribute('aria-pressed', String(playing));
    soundToggle.title = label;
    soundToggle.innerHTML = `<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" style="display:block;margin:auto"><path d="M11 5 6 9H3v6h3l5 4z" fill="currentColor"/>${SOUND_ICONS[playing ? 'on' : 'off']}</svg>`;
    Object.assign(soundToggle.style, {
        flex: 'none',
        width: '30px',
        height: '30px',
        padding: '0',
        background: 'rgba(0, 0, 0, 0.18)',
        color: playing ? 'rgba(255, 255, 255, 0.86)' : 'rgba(255, 255, 255, 0.68)',
        border: '1px solid rgba(255, 255, 255, 0.16)',
        cursor: 'pointer'
    });
}

// Create environment map for reflections
function createEnvironmentMap() {
    skyboxLibrary = installSkyboxLibrary({
        mount: document.getElementById('controlPanelContent'),
        renderer,
        publication,
        getViewerState: viewerSettings,
        getDefaultViewerState: defaultViewerSettings,
        getShader: () => currentShader,
        onTexture: texture => {
            const previous = envMap;
            envMap = texture;
            updateMaterialsWithEnvMap();
            previous?.dispose();
        },
        onStateChange: refreshVideoEnvironmentState,
        confirmAction,
        onSwitchChrome: () => {
            const select = document.getElementById('viewer-shader');
            select.value = 'chrome';
            select.dispatchEvent(new Event('change', { bubbles: true }));
        }
    });
}

// Setup drag and drop handlers for loading views
function setupDragAndDropHandlers() {
    const dropZone = document.getElementById('drop-zone');
    if (!dropZone) return;
    
    let dragDepth = 0;
    let dragTimeout = null;
    const hideDropZone = () => {
        dragDepth = 0;
        clearTimeout(dragTimeout);
        dragTimeout = null;
        dropZone.style.display = 'none';
    };
    const showDropZone = () => {
        dropZone.style.display = 'block';
        clearTimeout(dragTimeout);
        // External drags cancelled by the OS may send no dragleave/dragend.
        // Active drags keep sending dragover, including while stationary.
        dragTimeout = setTimeout(hideDropZone, 1200);
    };
    window.addEventListener('dragenter', () => {
        dragDepth += 1;
        showDropZone();
    });
    window.addEventListener('dragover', function(e) {
        e.preventDefault();
        e.stopPropagation();
        showDropZone();
    });
    window.addEventListener('dragleave', function(e) {
        e.preventDefault();
        e.stopPropagation();
        dragDepth = Math.max(0, dragDepth - 1);
        if (dragDepth === 0 || e.clientX <= 0 || e.clientX >= window.innerWidth ||
            e.clientY <= 0 || e.clientY >= window.innerHeight) hideDropZone();
    });
    window.addEventListener('dragend', hideDropZone);
    window.addEventListener('blur', hideDropZone);
    window.addEventListener('keydown', e => {
        if (e.key === 'Escape') hideDropZone();
    }, true);
    document.addEventListener('visibilitychange', () => {
        if (document.hidden) hideDropZone();
    });
    
    // Handle drop
    window.addEventListener('drop', function(e) {
        e.preventDefault();
        e.stopPropagation();
        hideDropZone();
        
        if (e.dataTransfer.files.length > 0) {
            const file = e.dataTransfer.files[0];
            if (file.type === 'image/png') {
                readMetadataFromPNG(file);
            } else {
                alert('Please drop a PNG image file.');
            }
        }
    });
}

// Create a visual drop zone for dragging and dropping files
function createDropZone() {
    const dropZone = document.createElement('div');
    dropZone.id = 'drop-zone';
    dropZone.innerHTML = 'Drop PNG here to load view';
    dropZone.style.display = 'none';
    dropZone.style.position = 'absolute';
    dropZone.style.top = '0';
    dropZone.style.left = '0';
    dropZone.style.width = '100%';
    dropZone.style.height = '100%';
    dropZone.style.backgroundColor = 'rgba(0, 0, 0, 0.5)';
    dropZone.style.color = 'white';
    dropZone.style.textAlign = 'center';
    dropZone.style.paddingTop = '45vh';
    dropZone.style.fontSize = '24px';
    dropZone.style.zIndex = '1000';
    dropZone.style.pointerEvents = 'none';
    document.body.appendChild(dropZone);
}

// Read metadata from a PNG file
function readMetadataFromPNG(file) {
    console.log("Reading metadata from PNG file:", file.name);
    
    const reader = new FileReader();
    
    reader.onload = function(event) {
        const img = new Image();
        
        img.onload = function() {
            let metadataSource = "embedded";
            let success = false;
            
            try {
                // Create a canvas to read the PNG data
                const canvas = document.createElement('canvas');
                canvas.width = img.width;
                canvas.height = img.height;
                
                const ctx = canvas.getContext('2d');
                ctx.drawImage(img, 0, 0);
                
                // Try to extract metadata - first from pixel data
                let metadata = null;
                
                try {
                    // Method 1: Try to read from pixel data
                    const metadataRows = Math.min(canvas.height, 16);
                    const imgData = ctx.getImageData(0, 0, canvas.width, metadataRows);
                    const pixelData = imgData.data;
                    
                    // Check for our marker pixel
                    if (pixelData[0] === 254 && pixelData[1] === 0 && pixelData[2] === 254) {
                        console.log("Found marker pixel, trying to extract metadata from pixels");
                        
                        // Reconstruct string from pixel data
                        let dataString = "";
                        for (let i = 1; i < pixelData.length / 4; i++) { // Read the bounded metadata area
                            const pixelIndex = i * 4;
                            if (pixelIndex >= pixelData.length) break;
                            
                            const charCode = pixelData[pixelIndex];
                            if (charCode === 0) break; // End of data
                            dataString += String.fromCharCode(charCode);
                        }
                        
                        console.log("Extracted data string:", dataString);
                        
                        // Check if we found our metadata marker
                        const marker = "tESSdata=";
                        if (dataString.startsWith(marker)) {
                            const jsonStr = dataString.substring(marker.length);
                            try {
                                // Extract only the valid JSON part by finding the last closing brace
                                let jsonEnd = jsonStr.lastIndexOf('}');
                                if (jsonEnd > 0) {
                                    const cleanJsonStr = jsonStr.substring(0, jsonEnd + 1);
                                    metadata = JSON.parse(cleanJsonStr);
                                    console.log("Successfully extracted metadata from pixels:", metadata);
                                } else {
                                    console.error("Failed to find valid JSON end delimiter in pixel data");
                                }
                            } catch (e) {
                                console.error("Failed to parse pixel metadata JSON:", e);
                            }
                        }
                    }
                } catch (pixelError) {
                    console.error("Error reading pixel data:", pixelError);
                }
                
                // If we have valid metadata, apply it
                if (metadata) {
                    console.log("Applying extracted metadata from PNG");
                    success = applyViewSettings(metadata);
                    if (success) {
                        alert("Successfully loaded view settings from embedded metadata!");
                        return;
                    }
                }
                
                // Fallback to filename parsing if no metadata found
                console.log("No embedded metadata found, falling back to filename parsing");
                metadataSource = "filename";
                success = parseMetadataFromFilename(file.name);
                if (success) {
                    alert("Successfully loaded view settings from filename!");
                } else {
                    alert("Could not load view settings from either embedded metadata or filename.");
                }
                
            } catch (error) {
                console.error('Error reading PNG metadata:', error);
                
                // Fallback to filename parsing
                console.log("Error reading PNG, falling back to filename parsing");
                metadataSource = "filename (after error)";
                success = parseMetadataFromFilename(file.name);
                
                if (success) {
                    alert("Successfully loaded view settings from filename (after error)!");
                } else {
                    alert("Failed to load view settings from either method.\nError: " + error.message);
                }
            }
        };
        
        img.onerror = function() {
            alert('Failed to load the image.');
        };
        
        img.src = event.target.result;
    };
    
    reader.onerror = function() {
        alert('Failed to read the file.');
    };
    
    reader.readAsDataURL(file);
}

// Parse metadata from filename for backward compatibility
function parseMetadataFromFilename(filename) {
    console.log("Parsing metadata from filename:", filename);
    
    try {
        // First, remove any file extension
        const cleanName = filename.replace(/\.png$/i, '');
        
        // Expected format: tesseract_TIMESTAMP_pos_X_Y_Z_rot_XW_YW_ZW_time_T_target_TX_TY_TZ
        const parts = cleanName.split('_');
        console.log("Filename parts:", parts);
        
        // Extract data from filename parts
        let metadata = {
            camera: { position: {} },
            rotation: {},
            time: 0, // Default time value
            target: { x: 0, y: 0, z: 0 } // Default target at origin
        };
        
        // Find position values
        const posIndex = parts.indexOf('pos');
        if (posIndex > 0 && posIndex + 3 < parts.length) {
            metadata.camera.position.x = parseFloat(parts[posIndex + 1]);
            metadata.camera.position.y = parseFloat(parts[posIndex + 2]);
            metadata.camera.position.z = parseFloat(parts[posIndex + 3]);
            console.log("Found position:", metadata.camera.position);
        }
        
        // Find rotation values
        const rotIndex = parts.indexOf('rot');
        if (rotIndex > 0 && rotIndex + 3 < parts.length) {
            metadata.rotation.xw = parseFloat(parts[rotIndex + 1]);
            metadata.rotation.yw = parseFloat(parts[rotIndex + 2]);
            metadata.rotation.zw = parseFloat(parts[rotIndex + 3]);
            console.log("Found rotation:", metadata.rotation);
        }
        
        // Find time value
        const timeIndex = parts.indexOf('time');
        if (timeIndex > 0 && timeIndex + 1 < parts.length) {
            metadata.time = parseFloat(parts[timeIndex + 1]);
            console.log("Found time:", metadata.time);
        }
        
        // Find target values
        const targetIndex = parts.indexOf('target');
        if (targetIndex > 0 && targetIndex + 3 < parts.length) {
            metadata.target.x = parseFloat(parts[targetIndex + 1]);
            metadata.target.y = parseFloat(parts[targetIndex + 2]);
            metadata.target.z = parseFloat(parts[targetIndex + 3]);
            console.log("Found target:", metadata.target);
        }
        
        console.log("Extracted metadata from filename:", metadata);
        
        // Apply the extracted settings
        return applyViewSettings(metadata);
    } catch (error) {
        console.error("Error parsing metadata from filename:", error);
        return false;
    }
}

// Apply view settings from extracted metadata
function applyViewSettings(metadata) {
    console.log("Applying view settings from metadata:", metadata);
    
    try {
        setViewerShape(metadata.shape || metadata.render?.shape || 'tesseract');
        if (metadata.music) {
            restoredMusicSettings = metadata.music;
            visualMusic?.setSettings(metadata.music);
        }
        if (metadata.render) {
            const { camera: renderCamera, ...renderSettings } = metadata.render;
            restoreVideoRenderSettings({
                ...renderSettings,
                shape: metadata.shape || metadata.render.shape || 'tesseract',
                exportFps: metadata.render.fps,
                videoExportWidth: metadata.video?.width,
                videoExportHeight: metadata.video?.height,
                videoExportQuality: metadata.video?.quality
            });
        }
        // Set camera position
        if (metadata.camera && metadata.camera.position) {
            camera.position.set(
                parseFloat(metadata.camera.position.x),
                parseFloat(metadata.camera.position.y),
                parseFloat(metadata.camera.position.z)
            );
            console.log("Set camera position to:", camera.position);
        }
        
        // Set rotation coefficients
        if (metadata.rotation) {
            rotationCoefficients.xw = parseFloat(metadata.rotation.xw) || 0;
            rotationCoefficients.yw = parseFloat(metadata.rotation.yw) || 0;
            rotationCoefficients.zw = parseFloat(metadata.rotation.zw) || 0;
            console.log("Set rotation coefficients to:", rotationCoefficients);
            
            // Update UI sliders if they exist
            updateRotationSliders();
        }
        
        // Restore video timing before mapping the saved time onto the deterministic timeline.
        if (metadata.animation?.fps) {
            exportFps = parseInt(metadata.animation.fps, 10) || exportFps;
            if (exportFpsSelect) exportFpsSelect.value = String(exportFps);
        }
        if (metadata.animation?.motionStep !== undefined) {
            rotationSpeed = Math.max(0, parseFloat(metadata.animation.motionStep) || 0);
            if (motionStepSlider) motionStepSlider.value = String(rotationSpeed * 1000);
            if (motionStepLabel) motionStepLabel.textContent = `Motion Step: ${rotationSpeed.toFixed(3)} / frame`;
        }
        refreshLoopTiming({ preserveTime: false });
        if (metadata.animation?.frame !== undefined) {
            setTimelineFrame(parseInt(metadata.animation.frame, 10) || 0);
        } else if (metadata.time !== undefined) {
            setTimelineTime(parseFloat(metadata.time) || 0);
        }
        console.log("Set animation time to:", time);
        
        // Set camera target
        if (metadata.target) {
            controls.target.set(
                parseFloat(metadata.target.x) || 0,
                parseFloat(metadata.target.y) || 0,
                parseFloat(metadata.target.z) || 0
            );
            console.log("Set camera target to:", controls.target);
        }
        
        // Update controls and camera
        controls.update();
        camera.updateProjectionMatrix();
        
        // Ensure all material uniforms are updated correctly
        // For backward compatibility - reapply current lighting parameters
        const materials = [];
        faces.forEach(face => {
            if (face.material && !materials.includes(face.material)) {
                materials.push(face.material);
            }
        });
        
        vertices.forEach(vertex => {
            if (vertex.material && !materials.includes(vertex.material)) {
                materials.push(vertex.material);
            }
        });
        
        // Convert lighting type to integer for shader
        let lightingTypeInt;
        switch(currentLighting) {
            case 'topdown':
                lightingTypeInt = 1;
                break;
            case 'quad':
                lightingTypeInt = 2;
                break;
            case 'diagonal':
            default:
                lightingTypeInt = 0;
                break;
        }
        
        // Update the uniform values in all materials
        materials.forEach(material => {
            if (material.uniforms) {
                if (material.uniforms.lightDistance) {
                    material.uniforms.lightDistance.value = lightDistance;
                }
                if (material.uniforms.lightingType) {
                    material.uniforms.lightingType.value = lightingTypeInt;
                }
                // Without this, a restored "grain off" only unticks the checkbox while
                // the existing faces keep rendering grain (and exports record it as off).
                if (material.uniforms.surfaceGrain) {
                    material.uniforms.surfaceGrain.value = surfaceGrain ? 1 : 0;
                }
                if (material.uniforms.dirtyMirrors) {
                    material.uniforms.dirtyMirrors.value = dirtyMirrors ? 1 : 0;
                }
                if (material.uniforms.mirrorReflections) {
                    material.uniforms.mirrorReflections.value = mirrorReflections ? 1 : 0;
                }
            }
        });
        
        // If no materials were found, create new ones
        if (materials.length === 0) {
            updateMaterials();
        }
        
        // Pause animation when a view is restored
        pauseAnimation();
        persistViewerSettings();
        
        console.log("Successfully applied view settings");
        return true;
    } catch (error) {
        console.error("Error applying view settings:", error);
        return false;
    }
}

// Update rotation sliders in the UI
function updateRotationSliders() {
    console.log("Updating rotation sliders to:", rotationCoefficients);
    
    try {
        // Look specifically for the rotation sliders in the rotationControls container
        const rotationControls = document.getElementById('rotationControls');
        if (!rotationControls) {
            console.warn("Could not find rotation controls container - skipping slider update");
            return;
        }
        
        const sliders = rotationControls.querySelectorAll('input[type="range"]');
        if (sliders.length < 3) {
            console.warn("Could not find enough rotation sliders, found:", sliders.length);
            return;
        }
        
        // The sliders are now directly identified by their index in the rotation controls section
        const xwSlider = sliders[0]; 
        const ywSlider = sliders[1];
        const zwSlider = sliders[2];
        
        console.log("Found rotation sliders");
        
        // Set slider values - using 20 as the multiplier for a step of 0.05 (1/20 = 0.05)
        xwSlider.value = rotationCoefficients.xw * 20;
        ywSlider.value = rotationCoefficients.yw * 20;
        zwSlider.value = rotationCoefficients.zw * 20;
        
        console.log("Set slider values to:", xwSlider.value, ywSlider.value, zwSlider.value);
        
        // Update displayed values - with two decimal places
        const valueDisplays = rotationControls.querySelectorAll('span');
        if (valueDisplays.length >= 3) {
            // Values are now directly targeted
            valueDisplays[0].textContent = rotationCoefficients.xw.toFixed(2);
            valueDisplays[1].textContent = rotationCoefficients.yw.toFixed(2);
            valueDisplays[2].textContent = rotationCoefficients.zw.toFixed(2);
            console.log("Updated value displays");
        } else {
            console.warn("Could not find enough value display elements, found:", valueDisplays.length);
        }
        
        // Force the slider input event to ensure any attached handlers run
        try {
            const event = new Event('input', { bubbles: true });
            xwSlider.dispatchEvent(event);
            ywSlider.dispatchEvent(event);
            zwSlider.dispatchEvent(event);
        } catch (e) {
            console.warn("Could not dispatch events to sliders:", e);
        }
    } catch (error) {
        console.warn("Error updating rotation sliders:", error);
        // Continue execution, this is not a critical error
    }
}

function syncRangeStepper(slider) {
    const buttons = slider.closest('.range-stepper')?.querySelectorAll('button');
    buttons?.forEach(button => { button.disabled = slider.disabled; });
}

function addRangeStepper(slider) {
    if (slider.closest('.range-stepper')) return;
    const wrapper = document.createElement('div');
    wrapper.className = 'range-stepper';
    const decrease = document.createElement('button');
    const increase = document.createElement('button');
    decrease.type = increase.type = 'button';
    decrease.textContent = '−';
    increase.textContent = '+';
    decrease.title = 'Decrease by one step';
    increase.title = 'Increase by one step';
    decrease.setAttribute('aria-label', decrease.title);
    increase.setAttribute('aria-label', increase.title);
    slider.before(wrapper);
    wrapper.append(decrease, slider, increase);
    const step = direction => {
        if (slider.disabled) return;
        direction < 0 ? slider.stepDown() : slider.stepUp();
        slider.dispatchEvent(new Event('input', { bubbles: true }));
        slider.dispatchEvent(new Event('change', { bubbles: true }));
    };
    decrease.addEventListener('click', () => step(-1));
    increase.addEventListener('click', () => step(1));
    syncRangeStepper(slider);
}

// Create UI controls
function createControls() {
    controlPanel = document.createElement('div');
    controlPanel.id = 'controlPanel';
    controlPanel.style.position = 'absolute';
    controlPanel.style.top = '10px';
    controlPanel.style.left = '10px';
    controlPanel.style.width = 'min(290px, calc(100vw - 20px))';
    controlPanel.style.boxSizing = 'border-box';
    controlPanel.style.backgroundColor = 'rgba(0, 0, 0, 0.5)';
    controlPanel.style.color = 'white';
    controlPanel.style.padding = '10px';
    controlPanel.style.borderRadius = '0';
    controlPanel.style.fontFamily = 'Arial, sans-serif';
    controlPanel.style.fontSize = '14px';
    controlPanel.style.zIndex = '100';
    controlPanel.style.maxHeight = 'calc(100vh - 20px)';
    controlPanel.style.overflowY = 'auto';
    
    // Create camera info display
    cameraInfoDisplay = document.createElement('div');
    cameraInfoDisplay.id = 'viewer-camera-info';
    cameraInfoDisplay.style.marginBottom = '10px';
    controlPanel.appendChild(cameraInfoDisplay);
    
    // Create speed control
    const speedContainer = document.createElement('div');
    speedContainer.style.marginBottom = '10px';
    
    motionStepLabel = document.createElement('label');
    motionStepLabel.htmlFor = 'viewer-motion-step';
    motionStepLabel.style.display = 'block';
    motionStepLabel.textContent = `Motion Step: ${rotationSpeed.toFixed(3)} / frame`;
    motionStepLabel.style.marginBottom = '5px';
    speedContainer.appendChild(motionStepLabel);
    
    motionStepSlider = document.createElement('input');
    motionStepSlider.id = 'viewer-motion-step';
    motionStepSlider.type = 'range';
    motionStepSlider.min = '0';
    motionStepSlider.max = '10';
    motionStepSlider.step = '1';
    motionStepSlider.value = rotationSpeed * 1000;
    motionStepSlider.style.width = '100%';
    
    motionStepSlider.addEventListener('input', function() {
        rotationSpeed = this.value / 1000;
        motionStepLabel.textContent = `Motion Step: ${rotationSpeed.toFixed(3)} / frame`;
        refreshLoopTiming();
    });
    
    speedContainer.appendChild(motionStepSlider);
    controlPanel.appendChild(speedContainer);
    
    // Create vertex visibility toggle (moved above rotation controls)
    const vertexToggle = document.createElement('div');
    vertexToggle.style.marginBottom = '10px';
    
    const vertexCheckbox = document.createElement('input');
    vertexCheckbox.type = 'checkbox';
    vertexCheckbox.id = 'vertexToggle';
    vertexCheckbox.checked = showVertices;
    
    vertexCheckbox.addEventListener('change', function() {
        showVertices = this.checked;
        vertices.forEach(vertex => {
            vertex.visible = showVertices;
        });
    });
    
    const vertexLabel = document.createElement('label');
    vertexLabel.htmlFor = 'vertexToggle';
    vertexLabel.textContent = 'Show Vertices';
    vertexLabel.style.marginLeft = '5px';
    
    vertexToggle.appendChild(vertexCheckbox);
    vertexToggle.appendChild(vertexLabel);
    controlPanel.appendChild(vertexToggle);

    const grainToggle = document.createElement('div');
    grainToggle.style.marginBottom = '10px';
    const grainCheckbox = document.createElement('input');
    grainCheckbox.type = 'checkbox';
    grainCheckbox.id = 'grainToggle';
    grainCheckbox.checked = surfaceGrain;
    grainCheckbox.addEventListener('change', function() {
        surfaceGrain = this.checked;
        faces.forEach(face => {
            if (face.material?.uniforms?.surfaceGrain) face.material.uniforms.surfaceGrain.value = surfaceGrain ? 1 : 0;
        });
    });
    const grainLabel = document.createElement('label');
    grainLabel.htmlFor = 'grainToggle';
    grainLabel.textContent = 'Chrome surface grain';
    grainLabel.title = 'Shimmering per-frame grain; turning it off makes video exports far smaller';
    grainLabel.style.marginLeft = '5px';
    grainToggle.appendChild(grainCheckbox);
    grainToggle.appendChild(grainLabel);
    controlPanel.appendChild(grainToggle);

    const dirtyToggle = document.createElement('div');
    dirtyToggle.style.marginBottom = '10px';
    const dirtyCheckbox = document.createElement('input');
    dirtyCheckbox.type = 'checkbox';
    dirtyCheckbox.id = 'dirtyMirrorsToggle';
    dirtyCheckbox.checked = dirtyMirrors;
    dirtyCheckbox.addEventListener('change', function() {
        dirtyMirrors = this.checked;
        faces.forEach(face => {
            if (face.material?.uniforms?.dirtyMirrors) face.material.uniforms.dirtyMirrors.value = dirtyMirrors ? 1 : 0;
        });
    });
    const dirtyLabel = document.createElement('label');
    dirtyLabel.htmlFor = 'dirtyMirrorsToggle';
    dirtyLabel.textContent = 'Dirty mirrors';
    dirtyLabel.title = 'Subtle aged-mirror haze, dust and accumulated edge grime that stay on each face; no scratches';
    dirtyLabel.style.marginLeft = '5px';
    dirtyToggle.appendChild(dirtyCheckbox);
    dirtyToggle.appendChild(dirtyLabel);
    controlPanel.appendChild(dirtyToggle);

    const reflectionToggle = document.createElement('label');
    reflectionToggle.style.cssText = 'display:block;margin-bottom:10px';
    const reflectionCheckbox = document.createElement('input');
    reflectionCheckbox.type = 'checkbox';
    reflectionCheckbox.id = 'viewer-mirror-reflections';
    reflectionCheckbox.checked = mirrorReflections;
    reflectionCheckbox.addEventListener('change', () => {
        mirrorReflections = reflectionCheckbox.checked;
        for (const object of [...faces, ...vertices]) {
            if (object.material?.uniforms?.mirrorReflections) object.material.uniforms.mirrorReflections.value = mirrorReflections ? 1 : 0;
        }
        persistViewerSettings();
    });
    reflectionToggle.append(reflectionCheckbox, ' Face-to-face reflections · 1 bounce');
    reflectionToggle.title = 'Experimental: trace one additional reflection against faces, then the skybox. Turn off to compare performance.';
    controlPanel.appendChild(reflectionToggle);
    
    const shapeLabel = document.createElement('label');
    shapeLabel.textContent = '4D shape: ';
    const shapeSelect = document.createElement('select');
    shapeSelect.id = 'viewer-shape';
    for (const [value, label] of [['tesseract', 'Tesseract'], ['rectified-5-cell', 'Rectified 5-cell · all triangles']]) {
        const option = document.createElement('option');
        option.value = value;
        option.textContent = label;
        shapeSelect.appendChild(option);
    }
    shapeSelect.value = currentShape;
    shapeSelect.addEventListener('change', () => {
        setViewerShape(shapeSelect.value);
        shapeSelect.value = currentShape;
        persistViewerSettings();
    });
    shapeLabel.appendChild(shapeSelect);
    shapeLabel.style.display = 'block';
    shapeLabel.style.marginBottom = '10px';
    controlPanel.appendChild(shapeLabel);

    // Create shader selection
    const shaderContainer = document.createElement('div');
    shaderContainer.style.marginBottom = '10px';
    
    const shaderLabel = document.createElement('label');
    shaderLabel.htmlFor = 'viewer-shader';
    shaderLabel.style.display = 'block';
    shaderLabel.textContent = 'Shader Type:';
    shaderLabel.style.marginBottom = '5px';
    shaderContainer.appendChild(shaderLabel);
    
    const shaderSelect = document.createElement('select');
    shaderSelect.id = 'viewer-shader';
    shaderSelect.style.width = '100%';
    shaderSelect.style.padding = '3px';
    shaderSelect.style.backgroundColor = '#222';
    shaderSelect.style.color = 'white';
    shaderSelect.style.border = '1px solid #555';
    
    // Add shader options
    const roughOption = document.createElement('option');
    roughOption.value = 'rough';
    roughOption.textContent = 'Rough (debug)';
    roughOption.selected = currentShader === 'rough';
    shaderSelect.appendChild(roughOption);
    
    const iridescientOption = document.createElement('option');
    iridescientOption.value = 'iridescent';
    iridescientOption.textContent = 'Iridescent (debug)';
    iridescientOption.selected = currentShader === 'iridescent';
    shaderSelect.appendChild(iridescientOption);
    
    const chromeOption = document.createElement('option');
    chromeOption.value = 'chrome';
    chromeOption.textContent = 'Reflective Chrome';
    chromeOption.selected = currentShader === 'chrome';
    shaderSelect.appendChild(chromeOption);
    
    // Handle shader changes
    shaderSelect.addEventListener('change', function() {
        currentShader = this.value;
        updateMaterials();
        skyboxLibrary?.refreshShaderHint();
    });
    
    shaderContainer.appendChild(shaderSelect);
    controlPanel.appendChild(shaderContainer);
    
    // Create lighting control
    const lightingContainer = document.createElement('div');
    lightingContainer.style.marginBottom = '10px';
    
    const lightingLabel = document.createElement('label');
    lightingLabel.htmlFor = 'viewer-lighting';
    lightingLabel.style.display = 'block';
    lightingLabel.textContent = 'Lighting:';
    lightingLabel.style.marginBottom = '5px';
    lightingContainer.appendChild(lightingLabel);
    
    // Lighting type selector
    const lightingSelect = document.createElement('select');
    lightingSelect.id = 'viewer-lighting';
    lightingSelect.style.width = '100%';
    lightingSelect.style.padding = '3px';
    lightingSelect.style.backgroundColor = '#222';
    lightingSelect.style.color = 'white';
    lightingSelect.style.border = '1px solid #555';
    lightingSelect.style.marginBottom = '5px';
    
    // Add lighting options
    const diagonalOption = document.createElement('option');
    diagonalOption.value = 'diagonal';
    diagonalOption.textContent = 'Diagonal (1,1,1)';
    diagonalOption.selected = currentLighting === 'diagonal';
    lightingSelect.appendChild(diagonalOption);
    
    const topdownOption = document.createElement('option');
    topdownOption.value = 'topdown';
    topdownOption.textContent = 'Top-Down';
    topdownOption.selected = currentLighting === 'topdown';
    lightingSelect.appendChild(topdownOption);
    
    const quadOption = document.createElement('option');
    quadOption.value = 'quad';
    quadOption.textContent = 'Spot Quadrants (4)';
    quadOption.selected = currentLighting === 'quad';
    lightingSelect.appendChild(quadOption);
    
    // Light distance control
    const distanceLabel = document.createElement('label');
    distanceLabel.id = 'viewer-light-distance-label';
    distanceLabel.htmlFor = 'viewer-light-distance';
    distanceLabel.style.display = 'block';
    distanceLabel.textContent = `Light Distance: ${lightDistance.toFixed(1)}`;
    distanceLabel.style.marginTop = '5px';
    distanceLabel.style.marginBottom = '5px';
    
    const distanceSlider = document.createElement('input');
    distanceSlider.id = 'viewer-light-distance';
    distanceSlider.type = 'range';
    distanceSlider.min = '0.1';
    distanceSlider.max = '20';
    distanceSlider.step = '0.1';
    distanceSlider.value = lightDistance;
    distanceSlider.style.width = '100%';
    
    // Handle lighting changes
    lightingSelect.addEventListener('change', function() {
        currentLighting = this.value;
        
        // Convert lighting type to integer for shader
        let lightingTypeInt;
        switch(currentLighting) {
            case 'topdown':
                lightingTypeInt = 1;
                break;
            case 'quad':
                lightingTypeInt = 2;
                break;
            case 'diagonal':
            default:
                lightingTypeInt = 0;
                break;
        }
        
        // Update existing materials' uniforms directly
        const materials = [];
        faces.forEach(face => {
            if (face.material && !materials.includes(face.material)) {
                materials.push(face.material);
            }
        });
        
        vertices.forEach(vertex => {
            if (vertex.material && !materials.includes(vertex.material)) {
                materials.push(vertex.material);
            }
        });
        
        // Update the uniform value in all materials
        materials.forEach(material => {
            if (material.uniforms && material.uniforms.lightingType) {
                material.uniforms.lightingType.value = lightingTypeInt;
            }
        });
        
        // If there are no existing materials or the update fails, create new ones
        if (materials.length === 0) {
            updateMaterials();
        }
    });
    
    distanceSlider.addEventListener('input', function() {
        lightDistance = parseFloat(this.value);
        distanceLabel.textContent = `Light Distance: ${lightDistance.toFixed(1)}`;
        
        // Update existing materials' uniforms directly
        const materials = [];
        faces.forEach(face => {
            if (face.material && !materials.includes(face.material)) {
                materials.push(face.material);
            }
        });
        
        vertices.forEach(vertex => {
            if (vertex.material && !materials.includes(vertex.material)) {
                materials.push(vertex.material);
            }
        });
        
        // Update the uniform value in all materials
        materials.forEach(material => {
            if (material.uniforms && material.uniforms.lightDistance) {
                material.uniforms.lightDistance.value = lightDistance;
            }
        });
        
        // If there are no existing materials or the update fails, create new ones
        if (materials.length === 0) {
            updateMaterials();
        }
    });
    
    lightingContainer.appendChild(lightingSelect);
    lightingContainer.appendChild(distanceLabel);
    lightingContainer.appendChild(distanceSlider);
    controlPanel.appendChild(lightingContainer);
    
    // Add rotation controls
    const rotationControls = document.createElement('div');
    rotationControls.id = 'rotationControls';
    rotationControls.innerHTML = `
        <h3>4D Rotation</h3>
        <div class="rotation-row">
            <label for="rotation-xw">XW: <span>${rotationCoefficients.xw.toFixed(2)}</span></label>
            <input id="rotation-xw" type="range" min="-20" max="20" value="${rotationCoefficients.xw * 20}" step="1">
        </div>
        <div class="rotation-row">
            <label for="rotation-yw">YW: <span>${rotationCoefficients.yw.toFixed(2)}</span></label>
            <input id="rotation-yw" type="range" min="-20" max="20" value="${rotationCoefficients.yw * 20}" step="1">
        </div>
        <div class="rotation-row">
            <label for="rotation-zw">ZW: <span>${rotationCoefficients.zw.toFixed(2)}</span></label>
            <input id="rotation-zw" type="range" min="-20" max="20" value="${rotationCoefficients.zw * 20}" step="1">
        </div>
    `;
    rotationControls.querySelectorAll('.rotation-row').forEach(row => {
        Object.assign(row.style, {
            display: 'grid',
            gridTemplateColumns: '6em minmax(0, 1fr)',
            alignItems: 'center',
            gap: '6px'
        });
        row.querySelector('label').style.fontVariantNumeric = 'tabular-nums';
        row.querySelector('input').style.width = '100%';
        row.querySelector('input').style.minWidth = '0';
    });
    
    // Update rotation coefficient when sliders change
    const rotationSliders = rotationControls.querySelectorAll('input[type="range"]');
    rotationSliders[0].addEventListener('input', function() {
        rotationCoefficients.xw = this.value / 20; // Divide by 20 for a step of 0.05
        rotationControls.querySelectorAll('span')[0].textContent = rotationCoefficients.xw.toFixed(2);
        refreshLoopTiming();
        updateCameraInfo();
    });
    
    rotationSliders[1].addEventListener('input', function() {
        rotationCoefficients.yw = this.value / 20; // Divide by 20 for a step of 0.05
        rotationControls.querySelectorAll('span')[1].textContent = rotationCoefficients.yw.toFixed(2);
        refreshLoopTiming();
        updateCameraInfo();
    });
    
    rotationSliders[2].addEventListener('input', function() {
        rotationCoefficients.zw = this.value / 20; // Divide by 20 for a step of 0.05
        rotationControls.querySelectorAll('span')[2].textContent = rotationCoefficients.zw.toFixed(2);
        refreshLoopTiming();
        updateCameraInfo();
    });
    controlPanel.appendChild(rotationControls);

    // Keep video-oriented controls collapsed until they are needed.
    const videoTimingDetails = document.createElement('details');
    videoTimingDetails.open = videoTimingExpanded;
    videoTimingDetails.addEventListener('toggle', () => {
        videoTimingExpanded = videoTimingDetails.open;
        persistViewerSettings();
    });
    videoTimingDetails.style.marginTop = '10px';
    videoTimingDetails.style.paddingTop = '8px';
    videoTimingDetails.style.borderTop = '1px solid #555';

    const videoTimingSummary = document.createElement('summary');
    videoTimingSummary.textContent = 'Video timing';
    videoTimingSummary.style.cursor = 'pointer';
    videoTimingDetails.appendChild(videoTimingSummary);

    const videoTimingContent = document.createElement('div');
    videoTimingContent.style.marginTop = '8px';

    const fpsRow = document.createElement('label');
    fpsRow.style.display = 'flex';
    fpsRow.style.justifyContent = 'space-between';
    fpsRow.style.alignItems = 'center';
    fpsRow.textContent = 'FPS';

    exportFpsSelect = document.createElement('select');
    exportFpsSelect.style.background = '#222';
    exportFpsSelect.style.color = 'white';
    exportFpsSelect.style.border = '1px solid #555';
    [24, 25, 30, 50, 60].forEach(fps => {
        const option = document.createElement('option');
        option.value = String(fps);
        option.textContent = String(fps);
        option.selected = fps === exportFps;
        exportFpsSelect.appendChild(option);
    });
    exportFpsSelect.addEventListener('change', function() {
        exportFps = parseInt(this.value, 10);
        lastAnimationTimestamp = null;
        frameAccumulator = 0;
        updateLoopTimingUI();
    });
    fpsRow.appendChild(exportFpsSelect);
    videoTimingContent.appendChild(fpsRow);

    loopInfoDisplay = document.createElement('div');
    loopInfoDisplay.style.marginTop = '7px';
    loopInfoDisplay.style.fontSize = '11px';
    loopInfoDisplay.style.lineHeight = '1.45';
    loopInfoDisplay.style.color = '#c5cfdb';
    videoTimingContent.appendChild(loopInfoDisplay);

    timelineSlider = document.createElement('input');
    timelineSlider.type = 'range';
    timelineSlider.setAttribute('aria-label', 'Timeline frame');
    timelineSlider.min = '0';
    timelineSlider.max = '0';
    timelineSlider.step = '1';
    timelineSlider.value = '0';
    timelineSlider.style.width = '100%';
    timelineSlider.style.marginTop = '7px';
    timelineSlider.addEventListener('input', function() {
        pauseAnimation();
        setTimelineFrame(parseInt(this.value, 10));
    });
    videoTimingContent.appendChild(timelineSlider);

    timelineFrameDisplay = document.createElement('div');
    timelineFrameDisplay.style.fontSize = '11px';
    timelineFrameDisplay.style.textAlign = 'center';
    videoTimingContent.appendChild(timelineFrameDisplay);

    const frameJump = document.createElement('form');
    frameJump.style.display = 'flex';
    frameJump.style.alignItems = 'center';
    frameJump.style.gap = '5px';
    frameJump.style.marginTop = '6px';

    const frameJumpLabel = document.createElement('label');
    frameJumpLabel.htmlFor = 'timeline-frame-input';
    frameJumpLabel.textContent = 'Go to frame';
    frameJumpLabel.style.whiteSpace = 'nowrap';
    frameJump.appendChild(frameJumpLabel);

    timelineFrameInput = document.createElement('input');
    timelineFrameInput.id = 'timeline-frame-input';
    timelineFrameInput.type = 'number';
    timelineFrameInput.min = '0';
    timelineFrameInput.max = '0';
    timelineFrameInput.step = '1';
    timelineFrameInput.value = '0';
    timelineFrameInput.style.width = '0';
    timelineFrameInput.style.minWidth = '60px';
    timelineFrameInput.style.flex = '1';
    timelineFrameInput.addEventListener('focus', pauseAnimation);
    frameJump.appendChild(timelineFrameInput);

    const frameJumpButton = document.createElement('button');
    frameJumpButton.type = 'submit';
    frameJumpButton.textContent = 'Go';
    frameJumpButton.style.padding = '4px 8px';
    frameJump.appendChild(frameJumpButton);

    frameJump.addEventListener('submit', event => {
        event.preventDefault();
        pauseAnimation();
        const requestedFrame = Number(timelineFrameInput.value);
        if (Number.isInteger(requestedFrame)) {
            setTimelineFrame(Math.min(loopTiming.frameCount - 1, Math.max(0, requestedFrame)));
            persistViewerSettings();
        } else {
            timelineFrameInput.value = String(timelineFrame);
        }
        timelineFrameInput.select();
    });
    videoTimingContent.appendChild(frameJump);

    const frameButtons = document.createElement('div');
    frameButtons.style.display = 'flex';
    frameButtons.style.gap = '5px';
    frameButtons.style.marginTop = '6px';
    [['− Frame', -1, 'Previous frame'], ['+ Frame', 1, 'Next frame']].forEach(([label, direction, name]) => {
        const button = document.createElement('button');
        button.type = 'button';
        button.textContent = label;
        button.setAttribute('aria-label', name);
        button.style.flex = '1';
        button.style.padding = '4px';
        button.addEventListener('click', () => {
            pauseAnimation();
            setTimelineFrame(timelineFrame + direction);
            persistViewerSettings();
        });
        frameButtons.appendChild(button);
    });
    videoTimingContent.appendChild(frameButtons);

    // Published works are static: video export needs studio/server.py.
    if (publication?.schemaVersion !== 1) {
        videoExportButton = document.createElement('button');
        videoExportButton.id = 'open-video-export';
        videoExportButton.type = 'button';
        videoExportButton.textContent = 'Export video…';
        videoExportButton.style.width = '100%';
        videoExportButton.style.padding = '6px';
        videoExportButton.style.marginTop = '8px';
        videoExportButton.addEventListener('click', openVideoExportDialog);
        videoTimingContent.appendChild(videoExportButton);

        const videoTimingHint = document.createElement('div');
        videoTimingHint.textContent = videoExportWasInterrupted
            ? 'The previous video export was cancelled because this page was left. Start it again when you can leave this page loaded.'
            : 'Frames render here and stream to the local server. This window can sit in the background. Leaving the page cancels the export.';
        videoTimingHint.style.marginTop = '7px';
        videoTimingHint.style.fontSize = '10px';
        videoTimingHint.style.color = '#9cadc3';
        videoTimingContent.appendChild(videoTimingHint);
    }

    videoTimingDetails.appendChild(videoTimingContent);
    controlPanel.appendChild(videoTimingDetails);
    
    // Add control buttons below rotation sliders
    const buttonContainer = document.createElement('div');
    buttonContainer.style.marginTop = '10px';
    buttonContainer.style.marginBottom = '10px';
    
    // First row of buttons: Play/Pause and Reset Time
    const buttonRow1 = document.createElement('div');
    buttonRow1.style.display = 'flex';
    buttonRow1.style.justifyContent = 'space-between';
    buttonRow1.style.marginBottom = '5px';
    
    // Play/Pause button
    const playPauseButton = document.createElement('button');
    playPauseButton.textContent = 'Play/Pause';
    playPauseButton.style.flex = '1';
    playPauseButton.style.marginRight = '5px';
    playPauseButton.style.padding = '5px';
    playPauseButton.addEventListener('click', function() {
        animationPaused = !animationPaused;
        lastAnimationTimestamp = null;
        frameAccumulator = 0;
        persistViewerSettings();
    });
    
    // Reset Time button
    const resetTimeButton = document.createElement('button');
    resetTimeButton.textContent = 'Reset Time';
    resetTimeButton.style.flex = '1';
    resetTimeButton.style.padding = '5px';
    resetTimeButton.addEventListener('click', function() {
        setTimelineFrame(0);
        updateCameraInfo();
        persistViewerSettings();
    });
    
    buttonRow1.appendChild(playPauseButton);
    buttonRow1.appendChild(resetTimeButton);
    buttonContainer.appendChild(buttonRow1);
    
    // Second row of buttons: Reset Position and Reset Target
    const buttonRow2 = document.createElement('div');
    buttonRow2.style.display = 'flex';
    buttonRow2.style.justifyContent = 'space-between';
    buttonRow2.style.marginBottom = '5px';
    
    // Reset Position button
    const resetPositionButton = document.createElement('button');
    resetPositionButton.textContent = 'Reset Camera';
    resetPositionButton.style.flex = '1';
    resetPositionButton.style.marginRight = '5px';
    resetPositionButton.style.padding = '5px';
    resetPositionButton.addEventListener('click', async function() {
        if (!await confirmAction({
            title: 'RESET CAMERA',
            message: 'Reset the camera to its starting position? The current view will be lost.',
            confirmLabel: 'Reset camera'
        })) return;
        camera.position.set(3, 3, 3);
        updateCameraInfo();
        controls.update();
        persistViewerSettings();
    });
    
    // Reset Target button
    const resetTargetButton = document.createElement('button');
    resetTargetButton.textContent = 'Reset Target';
    resetTargetButton.style.flex = '1';
    resetTargetButton.style.padding = '5px';
    resetTargetButton.addEventListener('click', async function() {
        if (!await confirmAction({
            title: 'RESET TARGET',
            message: 'Reset the orbit target to the origin? The current target will be lost.',
            confirmLabel: 'Reset target'
        })) return;
        controls.target.set(0, 0, 0);
        updateCameraInfo();
        controls.update();
        persistViewerSettings();
    });
    
    buttonRow2.appendChild(resetPositionButton);
    buttonRow2.appendChild(resetTargetButton);
    buttonContainer.appendChild(buttonRow2);
    
    // Third row: Save button on its own
    const buttonRow3 = document.createElement('div');
    buttonRow3.style.display = 'flex';
    buttonRow3.style.justifyContent = 'center';
    
    // Save button
    const saveButton = document.createElement('button');
    saveButton.textContent = 'Save';
    saveButton.style.width = '100%';
    saveButton.style.padding = '5px';
    saveButton.addEventListener('click', function() {
        saveScreenshot();
    });
    
    buttonRow3.appendChild(saveButton);
    buttonContainer.appendChild(buttonRow3);
    
    controlPanel.appendChild(buttonContainer);
    
    // Create controls info
    const controlsInfo = document.createElement('div');
    controlsInfo.style.marginTop = '15px';
    controlsInfo.style.fontSize = '12px';
    controlsInfo.innerHTML = `
        <div>Space: Play/Pause</div>
        <div>R: Reset Time</div>
        <div>O: Toggle UI</div>
        <div>S: Save Screenshot</div>
    `;
    controlPanel.appendChild(controlsInfo);
    
    const panelContent = document.createElement('div');
    panelContent.id = 'controlPanelContent';
    while (controlPanel.firstChild) {
        panelContent.appendChild(controlPanel.firstChild);
    }

    const panelToggle = document.createElement('button');
    panelToggle.type = 'button';
    panelToggle.setAttribute('aria-controls', panelContent.id);
    // The soundtrack toggle stays beside the gear so music never needs the full panel,
    // and gives touch visitors a first tap that does not move the camera.
    soundToggle = document.createElement('button');
    soundToggle.type = 'button';
    soundToggle.id = 'sound-toggle';
    soundToggle.addEventListener('click', () => {
        if (!visualMusic) return;
        if (visualMusic.playing) visualMusic.stop();
        else void visualMusic.start();
    });
    updateSoundToggle(false);
    const panelHeader = document.createElement('div');
    panelHeader.id = 'controlPanelHeader';
    Object.assign(panelHeader.style, { display: 'flex', alignItems: 'center', gap: '6px' });
    const updatePanelAppearance = () => {
        panelContent.hidden = !panelExpanded;
        panelToggle.setAttribute('aria-expanded', String(panelExpanded));
        panelToggle.setAttribute('aria-label', panelExpanded ? 'Collapse controls' : 'Open controls');
        panelToggle.title = panelExpanded ? 'Collapse controls' : 'Open controls';
        panelToggle.textContent = panelExpanded ? '▾ Controls' : '⚙︎';
        panelHeader.style.marginBottom = panelExpanded ? '10px' : '0';
        Object.assign(controlPanel.style, panelExpanded ? {
            width: 'min(290px, calc(100vw - 20px))',
            backgroundColor: 'rgba(0, 0, 0, 0.5)',
            padding: '10px',
            overflowY: 'auto'
        } : {
            width: '66px',
            backgroundColor: 'transparent',
            padding: '0',
            overflowY: 'hidden'
        });
        Object.assign(panelToggle.style, panelExpanded ? {
            flex: '1',
            width: 'auto',
            height: 'auto',
            background: 'transparent',
            color: 'inherit',
            border: 'none',
            padding: '0',
            textAlign: 'left',
            font: 'inherit',
            fontWeight: 'bold',
            cursor: 'pointer'
        } : {
            flex: 'none',
            width: '30px',
            height: '30px',
            background: 'rgba(0, 0, 0, 0.18)',
            color: 'rgba(255, 255, 255, 0.68)',
            border: '1px solid rgba(255, 255, 255, 0.16)',
            padding: '0',
            textAlign: 'center',
            font: '16px/28px Arial, sans-serif',
            fontWeight: 'normal',
            cursor: 'pointer'
        });
    };
    updatePanelAppearance();
    panelToggle.addEventListener('click', () => {
        panelExpanded = !panelExpanded;
        updatePanelAppearance();
        persistViewerSettings();
    });
    panelHeader.append(panelToggle, soundToggle);
    controlPanel.append(panelHeader, panelContent);
    controlPanel.querySelectorAll('input[type="range"]').forEach(addRangeStepper);
    document.body.appendChild(controlPanel);
    if (publication?.schemaVersion !== 1) createVideoExportDialog();

    // Input handlers update the application state first; bubbling then saves it.
    controlPanel.addEventListener('input', persistViewerSettings);
    controlPanel.addEventListener('change', persistViewerSettings);
    
    // Initialize the exact loop timeline and camera display.
    const restoredTimelineFrame = timelineFrame;
    refreshLoopTiming({ preserveTime: false });
    setTimelineFrame(restoredTimelineFrame);
    updateCameraInfo();
}

function updateMaterials() {
    const previousMaterials = new Set([...faces, ...vertices].map(object => object.material).filter(Boolean));
    const newMaterial = createShaderMaterial();
    faces.forEach(face => { face.material = newMaterial; });
    vertices.forEach(vertex => { vertex.material = newMaterial; });
    previousMaterials.forEach(material => {
        if (material !== newMaterial) material.dispose();
    });
}

function restoreVideoRenderSettings(saved) {
    // Restoring render settings should not collapse the current controls or
    // change the user's preview play/pause preference.
    const {panelExpanded, videoTimingExpanded, animationPaused, ...renderSettings} = saved || {};
    applyViewerSettings(renderSettings);
}

function syncViewerControlsFromState() {
    const shape = document.getElementById('viewer-shape');
    if (shape) shape.value = currentShape;
    if (motionStepSlider) motionStepSlider.value = String(rotationSpeed * 1000);
    if (motionStepLabel) motionStepLabel.textContent = `Motion Step: ${rotationSpeed.toFixed(3)} / frame`;
    const rotationControls = document.getElementById('rotationControls');
    if (rotationControls) {
        const sliders = rotationControls.querySelectorAll('input[type="range"]');
        const values = rotationControls.querySelectorAll('span');
        ['xw', 'yw', 'zw'].forEach((axis, index) => {
            if (sliders[index]) sliders[index].value = String(rotationCoefficients[axis] * 20);
            if (values[index]) values[index].textContent = rotationCoefficients[axis].toFixed(2);
        });
    }
    const shader = document.getElementById('viewer-shader');
    if (shader) shader.value = currentShader;
    const lighting = document.getElementById('viewer-lighting');
    if (lighting) lighting.value = currentLighting;
    const distance = document.getElementById('viewer-light-distance');
    if (distance) distance.value = String(lightDistance);
    const distanceLabel = document.getElementById('viewer-light-distance-label');
    if (distanceLabel) distanceLabel.textContent = `Light Distance: ${lightDistance.toFixed(1)}`;
    const vertexToggle = document.getElementById('vertexToggle');
    if (vertexToggle) vertexToggle.checked = showVertices;
    const grainToggle = document.getElementById('grainToggle');
    if (grainToggle) grainToggle.checked = surfaceGrain;
    const dirtyToggle = document.getElementById('dirtyMirrorsToggle');
    if (dirtyToggle) dirtyToggle.checked = dirtyMirrors;
    const reflectionToggle = document.getElementById('viewer-mirror-reflections');
    if (reflectionToggle) reflectionToggle.checked = mirrorReflections;
    if (exportFpsSelect) exportFpsSelect.value = String(exportFps);
    const resolution = document.getElementById('video-export-resolution');
    if (resolution) resolution.value = `${videoExportWidth}x${videoExportHeight}`;
    const quality = document.getElementById('video-export-quality');
    if (quality) quality.value = videoExportQuality;
}

const COEFFICIENT_SCALE = 1000000;

function greatestCommonDivisor(a, b) {
    a = Math.abs(a);
    b = Math.abs(b);
    while (b !== 0) {
        [a, b] = [b, a % b];
    }
    return a;
}

function calculateLoopPeriod() {
    const scaledCoefficients = Object.values(rotationCoefficients).map(value => {
        const scaled = Math.round(value * COEFFICIENT_SCALE);
        return Math.abs(value - scaled / COEFFICIENT_SCALE) < 1e-10 ? Math.abs(scaled) : null;
    });

    if (scaledCoefficients.some(value => value === null)) return null;
    const activeCoefficients = scaledCoefficients.filter(value => value !== 0);
    if (activeCoefficients.length === 0) return 0;

    const divisor = activeCoefficients.reduce(greatestCommonDivisor);
    return 2 * Math.PI * COEFFICIENT_SCALE / divisor;
}

function refreshLoopTiming({ preserveTime = true } = {}) {
    const previousTime = preserveTime ? time : 0;
    const period = calculateLoopPeriod();

    if (period === null) {
        loopTiming = { period: null, frameCount: 1, timeStep: 0, exact: false };
    } else if (period === 0 || rotationSpeed === 0) {
        loopTiming = { period, frameCount: 1, timeStep: 0, exact: true };
    } else {
        const frameCount = Math.max(1, Math.round(period / rotationSpeed));
        loopTiming = {
            period,
            frameCount,
            timeStep: period / frameCount,
            exact: true
        };
    }

    setTimelineTime(previousTime);
}

function setTimelineTime(requestedTime) {
    if (loopTiming.frameCount <= 1 || !loopTiming.timeStep) {
        timelineFrame = 0;
        time = 0;
    } else {
        setTimelineFrame(Math.round(requestedTime / loopTiming.timeStep));
        return;
    }
    updateLoopTimingUI();
}

function pauseAnimation() {
    animationPaused = true;
    lastAnimationTimestamp = null;
    frameAccumulator = 0;
}

function confirmAction({ title, message, confirmLabel }) {
    let dialog = document.getElementById('confirm-action-dialog');
    if (!dialog) {
        dialog = document.createElement('dialog');
        dialog.id = 'confirm-action-dialog';
        dialog.innerHTML = `
            <form method="dialog">
                <div class="library-heading"><strong id="confirm-action-title"></strong></div>
                <p id="confirm-action-message"></p>
                <div class="video-export-actions">
                    <button type="submit" value="cancel">Cancel</button>
                    <button type="submit" value="confirm" id="confirm-action-accept"></button>
                </div>
            </form>`;
        document.body.appendChild(dialog);
    }
    dialog.querySelector('#confirm-action-title').textContent = title;
    dialog.querySelector('#confirm-action-message').textContent = message;
    dialog.querySelector('#confirm-action-accept').textContent = confirmLabel;
    return new Promise(resolve => {
        dialog.addEventListener('close', function onClose() {
            dialog.removeEventListener('close', onClose);
            resolve(dialog.returnValue === 'confirm');
        });
        dialog.showModal();
        dialog.querySelector('button[value="cancel"]').focus();
    });
}

function setTimelineFrame(requestedFrame) {
    const count = loopTiming.frameCount;
    timelineFrame = count > 1 ? ((requestedFrame % count) + count) % count : 0;
    time = timelineFrame * loopTiming.timeStep;
    updateLoopTimingUI();
}

function formatDuration(seconds) {
    if (!Number.isFinite(seconds)) return '—';
    if (seconds < 60) return `${seconds.toFixed(2)} s`;
    const hours = Math.floor(seconds / 3600);
    const minutes = Math.floor((seconds % 3600) / 60);
    const remainingSeconds = seconds % 60;
    return hours
        ? `${hours}:${String(minutes).padStart(2, '0')}:${remainingSeconds.toFixed(2).padStart(5, '0')}`
        : `${minutes}:${remainingSeconds.toFixed(2).padStart(5, '0')}`;
}

function updateLoopTimingUI() {
    if (timelineSlider) {
        timelineSlider.max = String(Math.max(0, loopTiming.frameCount - 1));
        timelineSlider.value = String(timelineFrame);
        timelineSlider.disabled = loopTiming.frameCount <= 1;
        syncRangeStepper(timelineSlider);
    }
    if (timelineFrameDisplay) {
        timelineFrameDisplay.textContent = `Frame ${timelineFrame} / ${loopTiming.frameCount - 1}`;
    }
    if (timelineFrameInput) {
        timelineFrameInput.max = String(Math.max(0, loopTiming.frameCount - 1));
        timelineFrameInput.value = String(timelineFrame);
        timelineFrameInput.disabled = loopTiming.frameCount <= 1;
    }
    if (!loopInfoDisplay) return;

    if (!loopTiming.exact) {
        loopInfoDisplay.textContent = 'No practical exact loop for these coefficients.';
        return;
    }
    if (loopTiming.period === 0) {
        loopInfoDisplay.textContent = 'Stationary · 1 frame';
        return;
    }
    if (rotationSpeed === 0) {
        loopInfoDisplay.textContent = 'Speed is zero · 1 frame';
        return;
    }

    const duration = loopTiming.frameCount / exportFps;
    loopInfoDisplay.innerHTML = `
        <div>${loopTiming.frameCount.toLocaleString()} frames · ${formatDuration(duration)}</div>
        <div>Loop period ${loopTiming.period.toFixed(4)} · Δt ${loopTiming.timeStep.toFixed(6)}</div>
    `;
}

// Master is content-dependent CRF encoding. Its conservative value is used
// only for preflight size/disk planning, never as an encoder bitrate ceiling.
const VIDEO_QUALITY_BITS_PER_PIXEL = { draft: 0.035, standard: 0.07, high: 0.12, capped: 0.8, master: 0.8 };

function formatBytes(bytes) {
    if (!Number.isFinite(bytes)) return '—';
    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
    let value = bytes;
    let unit = 0;
    while (value >= 1000 && unit < units.length - 1) {
        value /= 1000;
        unit++;
    }
    return `${value.toFixed(value >= 100 || unit === 0 ? 0 : value >= 10 ? 1 : 2)} ${units[unit]}`;
}

function formatBitRate(bitsPerSecond) {
    return bitsPerSecond >= 1000000
        ? `${(bitsPerSecond / 1000000).toFixed(2)} Mb/s`
        : `${Math.round(bitsPerSecond / 1000)} kb/s`;
}

function formatTimeInput(seconds) {
    const hours = Math.floor(seconds / 3600);
    const minutes = Math.floor((seconds % 3600) / 60);
    const remainder = seconds % 60;
    return hours
        ? `${hours}:${String(minutes).padStart(2, '0')}:${remainder.toFixed(3).padStart(6, '0')}`
        : `${minutes}:${remainder.toFixed(3).padStart(6, '0')}`;
}

function parseTimeInput(value) {
    const parts = String(value).trim().split(':');
    if (!parts.length || parts.length > 3 || parts.some(part => part === '' || !Number.isFinite(Number(part)) || Number(part) < 0)) return NaN;
    return parts.reduce((total, part) => total * 60 + Number(part), 0);
}

function videoRenderSignature() {
    return JSON.stringify({
        sourceUrl: location.pathname + location.search,
        // Keep existing tesseract signatures compatible; non-default shapes
        // must be distinguished so resumed frames cannot mix geometries.
        ...(currentShape === 'tesseract' ? {} : {shape: currentShape}),
        rotationSpeed,
        rotationCoefficients,
        shader: currentShader,
        lighting: currentLighting,
        lightDistance,
        showVertices,
        // Omitted when on so signatures from before the toggle stay valid.
        ...(surfaceGrain ? {} : {surfaceGrain}),
        // Omitted when off so signatures from before dirty mirrors stay valid.
        ...(dirtyMirrors ? {dirtyMirrors} : {}),
        ...(mirrorReflections ? {mirrorReflections: 1} : {}),
        camera: {
            position: ['x', 'y', 'z'].map(axis => Number(camera.position[axis].toFixed(9))),
            target: ['x', 'y', 'z'].map(axis => Number(controls.target[axis].toFixed(9)))
        },
        fps: exportFps,
        music: visualMusic?.settings ?? restoredMusicSettings,
        environment: skyboxLibrary?.getRenderState().identity || null
    });
}

function createVideoExportDialog() {
    videoExportDialog = document.createElement('dialog');
    videoExportDialog.id = 'video-export-dialog';
    videoExportDialog.innerHTML = `
        <form id="video-export-form">
            <div class="library-heading">
                <strong>EXPORT VIDEO</strong>
                <button id="close-video-export" type="button">Close</button>
            </div>
            <p>Render deterministic frames from the current camera, geometry, shader and skybox, then stream them to the local server for H.264 encoding. An enabled generative soundtrack is rendered from the same visual timeline.</p>
            <div class="video-export-grid">
                <label>File name<input id="video-export-name" maxlength="60" value="tesseract"></label>
                <label>Resolution<select id="video-export-resolution">
                    <option value="1280x720">1280 × 720 · 720p</option>
                    <option value="1920x1080">1920 × 1080 · 1080p</option>
                    <option value="2560x1440">2560 × 1440 · 1440p</option>
                    <option value="3840x2160">3840 × 2160 · 4K</option>
                    <option value="1080x1080">1080 × 1080 · square</option>
                </select></label>
                <label>Container<select id="video-export-format">
                    <option value="mp4">MP4</option>
                    <option value="mkv">MKV · Matroska</option>
                </select></label>
                <label>Quality<select id="video-export-quality">
                    <option value="draft">Draft</option>
                    <option value="standard">Standard</option>
                    <option value="high">High</option>
                    <option value="capped">Capped master · streaming</option>
                    <option value="master">Master · dark detail</option>
                </select></label>
                <label>Range<select id="video-export-range">
                    <option value="full">Whole loop</option>
                    <option value="clip">Clip window</option>
                </select></label>
                <label>Checkpoint every (seconds; 0 = none)<input id="video-export-checkpoint" type="number" min="0" max="3600" step="1" value="60"></label>
                <label>Scratch folder (optional)<input id="video-export-scratch" placeholder="Default: videos/.checkpoints"></label>
            </div>
            <div id="video-export-clip-fields" class="video-export-grid" hidden style="margin-top:10px">
                <label>Start in loop<input id="video-export-start" inputmode="decimal" placeholder="HH:MM:SS or seconds"></label>
                <label>Clip duration<input id="video-export-duration" inputmode="decimal" placeholder="HH:MM:SS or seconds"></label>
            </div>
            <div id="video-export-summary" role="status"></div>
            <progress id="video-export-progress" value="0" max="1" hidden></progress>
            <p id="video-export-status" role="status"></p>
            <p id="video-export-result"></p>
            <section id="video-resume-jobs" hidden>
                <strong>INTERRUPTED EXPORTS</strong>
                <div id="video-resume-job-list"></div>
            </section>
            <div class="video-export-actions">
                <button id="cancel-video-export" type="button" hidden>Pause export</button>
                <button id="discard-active-video-export" type="button" hidden>Cancel export</button>
                <button id="confirm-video-export" type="submit">Start export</button>
            </div>
        </form>`;
    document.body.appendChild(videoExportDialog);

    const resolution = document.getElementById('video-export-resolution');
    resolution.value = `${videoExportWidth}x${videoExportHeight}`;
    document.getElementById('video-export-quality').value = videoExportQuality;
    for (const id of ['video-export-resolution', 'video-export-format', 'video-export-quality', 'video-export-range', 'video-export-start', 'video-export-duration', 'video-export-checkpoint', 'video-export-scratch']) {
        document.getElementById(id).addEventListener('input', updateVideoExportSummary);
        document.getElementById(id).addEventListener('change', updateVideoExportSummary);
    }
    document.getElementById('close-video-export').addEventListener('click', () => {
        if (videoExportRunning) requestVideoExportCancellation();
        else videoExportDialog.close();
    });
    document.getElementById('cancel-video-export').addEventListener('click', requestVideoExportCancellation);
    document.getElementById('discard-active-video-export').addEventListener('click', requestVideoExportDiscard);
    document.getElementById('video-export-form').addEventListener('submit', async event => {
        event.preventDefault();
        const plan = videoExportPlan();
        if (!plan || plan.error) return;
        const label = videoExportLabel(document.getElementById('video-export-name').value);
        const existing = JSON.parse(videoExportDialog.dataset.clips || '[]');
        if (existing.includes(label)) {
            const confirmed = await confirmAction({
                title: 'CLIP NAME EXISTS',
                message: `A clip named “${label}” is already in videos/. This export adds another file and does not replace the existing one.`,
                confirmLabel: 'Export another'
            });
            if (!confirmed) return;
        }
        runVideoExport(plan);
    });
    videoExportDialog.addEventListener('cancel', event => {
        if (videoExportRunning) {
            event.preventDefault();
            requestVideoExportCancellation();
        }
    });
    videoExportDialog.addEventListener('close', () => {
        videoExportDialogRequest += 1;
    });
}

async function openVideoExportDialog() {
    const requestId = ++videoExportDialogRequest;
    const fullDuration = loopTiming.frameCount / exportFps;
    const startSeconds = timelineFrame / exportFps;
    const clipSeconds = Math.min(30, Math.max(1 / exportFps, fullDuration - startSeconds));
    document.getElementById('video-export-range').value = 'clip';
    document.getElementById('video-export-start').value = formatTimeInput(startSeconds);
    document.getElementById('video-export-duration').value = formatTimeInput(clipSeconds);
    document.getElementById('video-export-result').replaceChildren();
    const status = document.getElementById('video-export-status');
    status.textContent = 'Checking the local video encoder…';
    status.classList.remove('error');
    videoExportDialog.dataset.statusMode = 'checking';
    videoExportDialog.dataset.serverAvailable = '';
    videoExportDialog.dataset.freeBytes = '';
    videoExportDialog.dataset.musicAvailable = '';
    videoExportDialog.dataset.musicReason = '';
    videoExportDialog.dataset.encoderRecovery = JSON.stringify({
        recovered: 0, alreadyExited: 0, refused: 0, skippedActive: 0, failed: 0, indexFailed: false
    });
    videoExportDialog.dataset.renderSignature = videoRenderSignature();
    videoExportDialog.showModal();
    updateVideoExportSummary();
    try {
        const value = await videoControlApi('/api/video/capabilities', { cache: 'no-store' });
        if (requestId !== videoExportDialogRequest || !videoExportDialog.open) return;
        if (!value.available && !value.canManage) throw new Error(value.reason || 'Video service is unavailable');
        videoExportDialog.dataset.serverAvailable = value.available ? 'yes' : 'no';
        videoExportDialog.dataset.videoMode = value.videoMode || 'resumable';
        videoExportDialog.dataset.musicAvailable = value.musicAvailable === false ? 'no' : 'yes';
        videoExportDialog.dataset.musicReason = value.musicReason || '';
        const simpleMode = videoExportDialog.dataset.videoMode === 'simple';
        for (const id of ['video-export-checkpoint', 'video-export-scratch']) {
            const label = document.getElementById(id)?.closest?.('label');
            if (label) {
                label.hidden = simpleMode;
                label.style.display = simpleMode ? 'none' : '';
            }
        }
        document.getElementById('cancel-video-export').textContent = simpleMode ? 'Cancel export' : 'Pause export';
        if (!value.available) {
            status.textContent = `${value.reason || 'H.264 encoding is unavailable'}. Completed checkpoints can still be finalized or discarded.`;
            status.classList.add('error');
        }
        videoExportDialog.dataset.freeBytes = String(value.freeBytes);
        videoExportDialog.dataset.clips = JSON.stringify(value.clips || []);
        videoExportDialog.dataset.encoder = value.encoder;
        videoExportDialog.dataset.encoderRecovery = JSON.stringify(
            value.encoderRecovery || {
                recovered: 0, alreadyExited: 0, refused: 0, skippedActive: 0, failed: 0, indexFailed: false
            });
        videoExportDialog.dataset.statusMode = 'ready';
        await loadVideoResumeJobs();
        if (requestId !== videoExportDialogRequest || !videoExportDialog.open) return;
    } catch (error) {
        if (requestId !== videoExportDialogRequest || !videoExportDialog.open) return;
        status.textContent = `Video export requires the local application server and ffmpeg. ${error.message}`;
        status.classList.add('error');
        videoExportDialog.dataset.statusMode = 'error';
    }
    updateVideoExportSummary();
}

function refreshVideoEnvironmentState() {
    if (!videoExportDialog) return;
    updateVideoExportSummary();
    if (videoExportDialog.open && !videoExportRunning) {
        videoExportDialog.dataset.renderSignature = videoRenderSignature();
        if (videoExportDialog.dataset.statusMode === 'ready') loadVideoResumeJobs();
    }
}

function videoResumeCompatibility(job, currentSignature, currentSource, encodingAvailable = true) {
    const request = job.request || {};
    const sourceMatches = request.sourceUrl === currentSource;
    const settingsMatch = request.renderSignature === currentSignature;
    const fullyRendered = job.nextFrame === job.frames;
    let saved = null, current = null;
    try { saved = JSON.parse(request.renderSignature); } catch { /* Old/invalid signature. */ }
    try { current = JSON.parse(currentSignature); } catch { /* Not yet ready. */ }
    const verified = Boolean(saved?.environment);
    const environmentMatches = verified && saved.environment === current?.environment;
    let reason = '';
    if (job.state === 'unavailable') reason = job.reason;
    else if (job.state === 'active') reason = 'The server still marks this export active; discard it or retry after recovery.';
    else if (job.state === 'finalizing') reason = 'This export is being finalized in another request. Wait for it to complete.';
    else if (!fullyRendered && !encodingAvailable) reason = 'H.264 encoding is unavailable; discard this job or restore the encoder to render its remaining frames.';
    else if (!fullyRendered && !verified) reason = 'This export predates verified skybox identity. Resume with the previous viewer runtime, or start a new export; settings restoration cannot verify its original environment.';
    else if (!fullyRendered && !sourceMatches) reason = 'Open the original viewer URL and load its saved skybox before resuming.';
    else if (!fullyRendered && !environmentMatches) reason = 'Load the original skybox and wait for content verification before restoring settings or resuming.';
    else if (!fullyRendered && !settingsMatch) reason = 'Current render settings do not match.';
    const usable = !['unavailable', 'active', 'finalizing'].includes(job.state);
    return {
        available: usable && (fullyRendered || (encodingAvailable && verified && sourceMatches && settingsMatch)),
        restore: usable && encodingAvailable && !fullyRendered && sourceMatches && environmentMatches && !settingsMatch && Boolean(request.viewerState),
        fullyRendered, reason
    };
}

async function resolveVideoPauseError(job, error) {
    if (error?.message !== 'Video export lease is no longer active') return error;
    try {
        const value = await videoControlApi('/api/video/jobs', { cache: 'no-store' });
        const current = (value.jobs || []).find(candidate => candidate.id === job.id);
        // Encoder failure cleanup may already have consumed the lease. Confirm
        // durable idle state; do not hide a stale lease owned by another renderer.
        if (current && ['paused', 'ready'].includes(current.state)) return null;
    } catch { /* Keep the original failure if state cannot be verified. */ }
    return error;
}

async function loadVideoResumeJobs() {
    const requestId = videoExportDialogRequest;
    const jobsRequest = ++videoResumeJobsRequest;
    const section = document.getElementById('video-resume-jobs');
    const list = document.getElementById('video-resume-job-list');
    list.replaceChildren();
    if (videoExportDialog.dataset.videoMode === 'simple') {
        section.hidden = true;
        return;
    }
    try {
        const value = await videoControlApi('/api/video/jobs', { cache: 'no-store' });
        if (requestId !== videoExportDialogRequest || jobsRequest !== videoResumeJobsRequest || !videoExportDialog.open) return;
        for (const job of value.jobs || []) {
            const card = document.createElement('div');
            card.className = 'video-resume-job';
            card.dataset.jobId = job.id;
            const request = job.request || {};
            const {available, restore: canRestore, fullyRendered, reason} = videoResumeCompatibility(
                job, videoRenderSignature(), location.pathname + location.search,
                videoExportDialog.dataset.serverAvailable === 'yes'
            );
            const description = document.createElement('span');
            const diagnostic = job.reason && job.reason !== reason ? job.reason : '';
            description.textContent = `${request.name || 'Video'} · ${job.nextFrame || 0} / ${job.frames || request.frames || 0} durable frames${reason ? ` · ${reason}` : ''}${diagnostic ? ` · ${diagnostic}` : ''}`;
            const resume = document.createElement('button');
            resume.type = 'button';
            resume.className = 'resume-video-export';
            resume.textContent = fullyRendered ? 'Finalize' : 'Resume';
            resume.disabled = !available;
            resume.addEventListener('click', () => {
                if (videoExportRunning) return;
                const plan = videoExportPlanFromRequest(request);
                if (plan) runVideoExport(plan, job);
            });
            const discard = document.createElement('button');
            discard.type = 'button';
            discard.className = 'discard-video-export';
            discard.textContent = 'Discard';
            discard.addEventListener('click', async () => {
                if (videoExportRunning) return;
                const confirmed = await confirmAction({
                    title: 'DISCARD VIDEO EXPORT',
                    message: 'Delete this interrupted export and all of its checkpoints?',
                    confirmLabel: 'Discard'
                });
                if (!confirmed || videoExportRunning) return;
                await videoControlApi('/api/video/cancel', {
                    method: 'POST', headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({ id: job.id })
                });
                await loadVideoResumeJobs();
            });
            card.append(description, resume);
            if (canRestore) {
                const restore = document.createElement('button');
                restore.type = 'button';
                restore.className = 'restore-video-export';
                restore.textContent = 'Restore export settings';
                restore.addEventListener('click', async () => {
                    if (videoExportRunning) return;
                    restoreVideoRenderSettings({
                        ...request.viewerState,
                        exportFps: Number(request.fps),
                        videoExportWidth: Number(request.width),
                        videoExportHeight: Number(request.height),
                        videoExportQuality: request.quality
                    });
                    const restoredFrame = timelineFrame;
                    camera.position.set(savedCameraPosition.x, savedCameraPosition.y, savedCameraPosition.z);
                    controls.target.set(savedCameraTarget.x, savedCameraTarget.y, savedCameraTarget.z);
                    controls.update();
                    vertices.forEach(vertex => { vertex.visible = showVertices; });
                    syncViewerControlsFromState();
                    updateMaterials();
                    skyboxLibrary?.refreshShaderHint();
                    refreshLoopTiming({ preserveTime: false });
                    setTimelineFrame(restoredFrame);
                    restoreVideoExportForm(request);
                    updateVideoExportSummary();
                    updateCameraInfo();
                    persistViewerSettings();
                    videoExportDialog.dataset.renderSignature = videoRenderSignature();
                    await loadVideoResumeJobs();
                });
                card.append(restore);
            }
            card.append(discard);
            list.appendChild(card);
        }
        section.hidden = !list.children.length;
    } catch (error) {
        if (requestId !== videoExportDialogRequest || jobsRequest !== videoResumeJobsRequest || !videoExportDialog.open) return;
        section.hidden = false;
        list.textContent = `Could not inspect interrupted exports: ${error.message}`;
    }
}

function videoExportPlanFromRequest(request) {
    const width = Number(request.width);
    const height = Number(request.height);
    const frames = Number(request.frames);
    const duration = frames / Number(request.fps);
    if (![width, height, frames, duration].every(Number.isFinite)) return null;
    return {
        width, height, frames, duration, fps: Number(request.fps),
        format: request.format,
        quality: request.quality,
        range: !Number(request.startFrame) && frames === Number(request.loopFrameCount || loopTiming.frameCount)
            ? 'full' : 'clip',
        startFrame: Number(request.startFrame) || 0,
        bitRate: Number(request.bitRate) || 0,
        estimatedBytes: Number(request.estimatedBytes) || 0,
        checkpointSeconds: Number.isFinite(Number(request.checkpointSeconds))
            ? Number(request.checkpointSeconds) : 60,
        scratchPath: request.scratchPath || '',
        music: request.music || null,
        error: ''
    };
}

// Export controls describe the saved request, not whichever new-export defaults
// happened to be visible when Restore or Resume was clicked.
function restoreVideoExportForm(request) {
    const plan = videoExportPlanFromRequest(request);
    if (!plan) return;
    const resolution = document.getElementById('video-export-resolution');
    const size = `${plan.width}x${plan.height}`;
    if (!Array.from(resolution.options).some(option => option.value === size)) {
        const option = document.createElement('option');
        option.value = size;
        option.textContent = `${plan.width} × ${plan.height} · saved export`;
        resolution.appendChild(option);
    }
    const values = {
        'video-export-name': request.name || 'tesseract',
        'video-export-resolution': size,
        'video-export-format': plan.format,
        'video-export-quality': plan.quality,
        'video-export-range': plan.range,
        'video-export-checkpoint': String(plan.checkpointSeconds),
        'video-export-scratch': plan.scratchPath,
        'video-export-start': formatTimeInput(plan.startFrame / plan.fps),
        'video-export-duration': formatTimeInput(plan.duration)
    };
    for (const [id, value] of Object.entries(values)) document.getElementById(id).value = value;
}

function videoExportPlan() {
    if (!videoExportDialog) return null;
    const [width, height] = document.getElementById('video-export-resolution').value.split('x').map(Number);
    const format = document.getElementById('video-export-format').value;
    const quality = document.getElementById('video-export-quality').value;
    const range = document.getElementById('video-export-range').value;
    let startFrame = 0;
    let frames = loopTiming.frameCount;
    let error = '';
    const simpleMode = videoExportDialog?.dataset?.videoMode === 'simple';
    const checkpointSeconds = simpleMode ? 0 : Number(document.getElementById('video-export-checkpoint').value);
    const scratchPath = simpleMode ? '' : document.getElementById('video-export-scratch').value.trim();

    if (!loopTiming.exact || loopTiming.frameCount < 1) error = 'The current motion does not have an exportable timeline.';
    const renderState = skyboxLibrary?.getRenderState();
    if (!renderState?.ready) error = 'Wait for the selected skybox to finish loading before exporting.';
    else if (!renderState.identity) error = 'Skybox verification requires HTTPS or localhost before exporting video.';
    if (!Number.isInteger(checkpointSeconds) || checkpointSeconds < 0 || checkpointSeconds > 3600) error = 'Checkpoint duration must be between 0 and 3,600 seconds.';
    if (range === 'clip') {
        const startSeconds = parseTimeInput(document.getElementById('video-export-start').value);
        const durationSeconds = parseTimeInput(document.getElementById('video-export-duration').value);
        startFrame = Math.round(startSeconds * exportFps);
        frames = Math.round(durationSeconds * exportFps);
        if (!Number.isFinite(startSeconds) || !Number.isFinite(durationSeconds)) error = 'Enter start and duration as seconds, MM:SS, or HH:MM:SS.';
        else if (frames < 1) error = 'Clip duration must include at least one frame.';
        else if (startFrame < 0 || startFrame >= loopTiming.frameCount) error = 'Clip start must be inside the full loop.';
        else if (startFrame + frames > loopTiming.frameCount) error = 'The clip window must end within the full loop.';
    }

    const duration = frames / exportFps;
    if (typeof visualMusic !== 'undefined' && visualMusic?.settings.enabled && duration > 900) error = 'Generative soundtrack exports are currently limited to 15 minutes.';
    if (typeof visualMusic !== 'undefined' && visualMusic?.settings.enabled && videoExportDialog.dataset.musicAvailable === 'no') {
        error = videoExportDialog.dataset.musicReason || 'The local ffmpeg does not provide AAC soundtrack encoding.';
    }
    const bitRate = width * height * exportFps * VIDEO_QUALITY_BITS_PER_PIXEL[quality];
    const estimatedBytes = bitRate * duration / 8 * 1.03;
    return { width, height, format, quality, range, startFrame, frames, duration, bitRate, estimatedBytes, checkpointSeconds, scratchPath,
        music: typeof visualMusic !== 'undefined' && visualMusic?.settings.enabled ? {enabled: true} : null, error };
}

function updateVideoExportSummary() {
    if (!videoExportDialog) return;
    const plan = activeVideoExportPlan || videoExportPlan();
    const isClip = plan?.range === 'clip';
    document.getElementById('video-export-clip-fields').hidden = !isClip;
    const summary = document.getElementById('video-export-summary');
    const confirm = document.getElementById('confirm-video-export');
    const freeBytes = Number(videoExportDialog.dataset.freeBytes);
    const spaceError = !videoExportRunning && plan && Number.isFinite(freeBytes) && freeBytes > 0 && plan.estimatedBytes > freeBytes * 0.9;
    if (!plan || plan.error || spaceError) {
        summary.textContent = spaceError
            ? `Estimated output ${formatBytes(plan.estimatedBytes)} exceeds available server disk space (${formatBytes(freeBytes)} free).`
            : plan?.error || 'Video settings are invalid.';
        summary.classList.add('error');
    } else {
        const rangeText = plan.range === 'full'
            ? `Whole loop · frames 0–${plan.frames - 1}`
            : `Clip · frames ${plan.startFrame}–${plan.startFrame + plan.frames - 1}`;
        const checkpointText = videoExportDialog.dataset.videoMode === 'simple'
            ? 'SIMPLE MODE: one-shot encoding, no checkpoints or resume. Cancellation/interruption discards partial output; restart from frame 0.'
            : plan.checkpointSeconds === 0
            ? 'No checkpoints. Pausing or interruption restarts from frame 0.'
            : `Durable progress is saved every ${plan.checkpointSeconds} seconds.`;
        const qualityText = plan.quality === 'master'
            ? 'Master · CRF 12 · slow · grain-tuned dark-detail AQ'
            : plan.quality === 'capped'
            ? `Capped master · CRF 12 · grain-tuned dark-detail AQ · ${formatBitRate(plan.bitRate)} ceiling`
            : `${plan.quality[0].toUpperCase() + plan.quality.slice(1)} quality · ${formatBitRate(plan.bitRate)} target`;
        const estimateText = plan.quality === 'master'
            ? 'conservative preflight allowance'
            : plan.quality === 'capped'
            ? `maximum ${plan.format.toUpperCase()} size`
            : `estimated ${plan.format.toUpperCase()} size`;
        summary.innerHTML = `
            <strong>${plan.resumed ? 'Resuming saved export · ' : ''}${rangeText}</strong><br>
            ${plan.width} × ${plan.height} · ${plan.fps || exportFps} FPS · ${plan.frames.toLocaleString()} frames<br>
            H.264 ${plan.format.toUpperCase()} · ${qualityText} · ${plan.music?.enabled ? 'generative AAC soundtrack' : 'no audio'} · current ${currentShader} shader<br>
            Duration ${formatDuration(plan.duration)} · ${estimateText} <strong>about ${formatBytes(plan.estimatedBytes)}</strong><br>
            <small>Saved under <code>videos/</code>. ${checkpointText} ${plan.quality === 'master' ? 'Master has no bitrate ceiling; actual size follows visual complexity.' : plan.quality === 'capped' ? 'Matches Master until grain or detail would exceed the ceiling; simpler footage comes in smaller.' : 'Visual complexity can change the final file size.'}${plan.music?.enabled ? ` Soundtrack preparation replays the full loop (${formatDuration(loopTiming.frameCount / (plan.fps || exportFps))}) and needs at least ${formatBytes(loopTiming.frameCount / (plan.fps || exportFps) * 48000 * 8 + plan.duration * 48000 * 4 + 44)} for PCM, plus the audio graph.` : ''}${Number.isFinite(freeBytes) && freeBytes > 0 ? ` Server has ${formatBytes(freeBytes)} free.` : ''} Progress appears after Start.</small>`;
        summary.classList.remove('error');
    }
    confirm.disabled = videoExportRunning || videoExportDialog.dataset.serverAvailable !== 'yes' || !plan || Boolean(plan.error) || spaceError;
    if (!videoExportRunning && videoExportDialog.dataset.serverAvailable === 'yes' && videoExportDialog.dataset.statusMode === 'ready') {
        const selection = plan && !plan.error
            ? `${formatDuration(plan.duration)} ${plan.range === 'full' ? 'whole loop' : 'clip'} is selected. `
            : '';
        const recovery = JSON.parse(videoExportDialog.dataset.encoderRecovery || '{}');
        const recoveryText = recovery.recovered
            ? `Startup safely cleaned ${recovery.recovered} interrupted encoder${recovery.recovered === 1 ? '' : 's'}. `
            : recovery.refused
                ? `${recovery.refused} stale PID${recovery.refused === 1 ? '' : 's'} belonged to unrelated processes and were left untouched. `
                : recovery.failed
                    ? `${recovery.failed} older video job${recovery.failed === 1 ? '' : 's'} could not be inspected; new exports remain available. `
                : '';
        document.getElementById('video-export-status').textContent =
            `${videoExportDialog.dataset.encoder} encoder ready. ${recoveryText}${selection}${videoExportDialog.dataset.videoMode === 'simple' ? 'Simple mode: leaving the page cancels the export; no partial progress is kept.' : 'Leaving the page pauses the export at its latest checkpoint.'}`;
    }
}

function videoExportLabel(name) {
    const label = String(name || '').trim().replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60);
    return label || 'tesseract';
}

function ensureVideoExportStopRequest() {
    if (!activeVideoExportJob || !videoExportStopAction) return null;
    if (videoExportStopPromise && videoExportStopJobId === activeVideoExportJob.id) {
        return videoExportStopPromise;
    }
    const job = activeVideoExportJob;
    const discard = videoExportStopAction === 'discard';
    videoExportStopJobId = job.id;
    videoExportStopPromise = videoControlApi(discard ? '/api/video/cancel' : '/api/video/pause', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ id: job.id, lease: job.lease })
    }).then(() => null, error => error);
    return videoExportStopPromise;
}

function requestVideoExportCancellation() {
    if (!videoExportRunning || videoExportStopAction) return;
    videoExportStopAction = videoExportDialog.dataset.videoMode === 'simple' ? 'discard' : 'pause';
    cancelVideoExportRequested = true;
    videoExportAbort?.abort();
    ensureVideoExportStopRequest();
    const button = document.getElementById('cancel-video-export');
    button.disabled = true;
    document.getElementById('discard-active-video-export').disabled = true;
    document.getElementById('video-export-status').textContent = videoExportStopAction === 'discard' ? 'Cancelling…' : 'Pausing…';
}

async function requestVideoExportDiscard() {
    if (!videoExportRunning || videoExportStopAction) return;
    const confirmed = await confirmAction({
        title: 'CANCEL VIDEO EXPORT',
        message: videoExportDialog.dataset.videoMode === 'simple' ? 'Cancel this one-shot export and discard its partial output?' : 'Permanently delete this export, its poster, and every saved checkpoint?',
        confirmLabel: 'Cancel export'
    });
    if (!confirmed || !videoExportRunning || videoExportStopAction) return;
    videoExportStopAction = 'discard';
    cancelVideoExportRequested = true;
    videoExportAbort?.abort();
    ensureVideoExportStopRequest();
    document.getElementById('cancel-video-export').disabled = true;
    document.getElementById('discard-active-video-export').disabled = true;
    document.getElementById('video-export-status').textContent = 'Cancelling and discarding…';
}

async function videoApi(path, options = {}) {
    const response = await fetch(path, options);
    let value = {};
    try { value = await response.json(); } catch { /* Replace non-JSON server errors below. */ }
    if (!response.ok) throw new Error(value.error || `Video server returned HTTP ${response.status}`);
    return value;
}

async function videoControlApi(path, options = {}) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 10000);
    try {
        return await videoApi(path, { ...options, signal: controller.signal });
    } catch (error) {
        if (error.name === 'AbortError') {
            throw new Error('The local video server did not respond within 10 seconds');
        }
        throw error;
    } finally {
        clearTimeout(timeout);
    }
}

function dataUrlToBlob(dataUrl) {
    return new Blob([dataUrlToBytes(dataUrl)], { type: 'image/png' });
}

function dataUrlToBytes(dataUrl) {
    const comma = dataUrl.indexOf(',');
    if (comma < 0) throw new Error('Could not capture the WebGL frame');
    const binary = atob(dataUrl.slice(comma + 1));
    const bytes = new Uint8Array(binary.length);
    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
    return bytes;
}

async function canvasPNG(canvas) {
    // Snapshot synchronously into a reusable offscreen surface, then let its
    // promise-based encoder work without creating a large Base64 string. Unlike
    // HTMLCanvasElement.toBlob(), OffscreenCanvas.convertToBlob() does not rely on
    // a document callback that browsers may drop while the page is hidden.
    if (!videoCaptureFallback && typeof OffscreenCanvas !== 'undefined') {
        let timeout;
        try {
            if (!videoCaptureSurface || videoCaptureSurface.width !== canvas.width || videoCaptureSurface.height !== canvas.height) {
                videoCaptureSurface = new OffscreenCanvas(canvas.width, canvas.height);
                videoCaptureContext = videoCaptureSurface.getContext('2d', { alpha: false });
            }
            if (!videoCaptureContext || typeof videoCaptureSurface.convertToBlob !== 'function') {
                throw new Error('Offscreen PNG capture is unavailable');
            }
            videoCaptureContext.drawImage(canvas, 0, 0);
            const bytes = await Promise.race([
                videoCaptureSurface.convertToBlob({ type: 'image/png' }).then(async blob => {
                    if (!blob?.size) throw new Error('Offscreen PNG capture returned an empty frame');
                    // Chromium can spill an encoder Blob to inaccessible backing
                    // storage after many captures. size remains nonzero, while
                    // reading/uploading it fails. Materialize bytes here so that
                    // failure is caught before upload and activates sticky fallback.
                    return new Uint8Array(await blob.arrayBuffer());
                }),
                new Promise((_, reject) => {
                    timeout = setTimeout(() => reject(new Error('Offscreen PNG capture timed out')), 30000);
                })
            ]);
            if (bytes.length < 24 || [137, 80, 78, 71, 13, 10, 26, 10].some((value, index) => bytes[index] !== value)) {
                throw new Error('Offscreen PNG capture returned invalid PNG bytes');
            }
            return bytes;
        } catch (error) {
            // Never accumulate timed-out full-frame encodes or repeat the 30s
            // wait on every frame. Retry offscreen capture only in the next job.
            videoCaptureFallback = true;
            videoCaptureSurface = videoCaptureContext = null;
            console.warn('Offscreen video capture failed; using the compatibility path for this export', error);
            renderer.render(scene, camera);
        } finally {
            clearTimeout(timeout);
        }
    }
    return dataUrlToBytes(canvas.toDataURL('image/png'));
}

// The soundtrack hears a small offscreen render, never the visible canvas, so
// live playback and video exports analyze frames the same way. Only the frame's
// shape matters (64 px wide, height from the aspect ratio), not its resolution.
function soundAnalysisSize(aspect) {
    const width = 64;
    return { width, height: Math.max(24, Math.min(64, Math.round(width / aspect))) };
}

// Hidden ?soundframe= lets the live soundtrack hear the frame an export would,
// e.g. 16:9 or 1080p, without changing what viewers see. Absent, it follows the window.
const SOUND_FRAME_ALIASES = { square: 1, '720p': 16 / 9, '1080p': 16 / 9, '1440p': 16 / 9, '4k': 16 / 9 };
function parseSoundFrame(search) {
    const value = new URLSearchParams(search).get('soundframe')?.trim().toLowerCase();
    if (!value) return null;
    if (Object.hasOwn(SOUND_FRAME_ALIASES, value)) return SOUND_FRAME_ALIASES[value];
    const ratio = value.match(/^(\d+(?:\.\d+)?)\s*[:x]\s*(\d+(?:\.\d+)?)$/);
    return ratio && Number(ratio[1]) > 0 && Number(ratio[2]) > 0 ? Number(ratio[1]) / Number(ratio[2]) : null;
}
const soundFrameAspect = parseSoundFrame(location.search);
let liveSoundTarget = null;
let soundAnalysisMaterial = null;

// The score always hears chrome with grain and aging enabled, regardless of
// display toggles. Never mutate the live materials or saved viewer settings.
function withSoundAnalysisMaterial(render) {
    soundAnalysisMaterial ??= createShaderMaterial('chrome');
    const uniforms = soundAnalysisMaterial.uniforms;
    uniforms.envMap.value = envMap;
    soundAnalysisMaterial.envMap = envMap;
    uniforms.surfaceGrain.value = 1;
    uniforms.dirtyMirrors.value = 1;
    if (uniforms.mirrorReflections) uniforms.mirrorReflections.value = mirrorReflections ? 1 : 0;
    uniforms.faceSides.value = currentShape === 'rectified-5-cell' ? 3 : 4;
    uniforms.lightDistance.value = lightDistance;
    uniforms.lightingType.value = currentLighting === 'topdown' ? 1 : currentLighting === 'quad' ? 2 : 0;
    const previous = scene.overrideMaterial;
    try {
        scene.overrideMaterial = soundAnalysisMaterial;
        return render();
    } finally {
        scene.overrideMaterial = previous;
    }
}

function sampleLiveSoundFrame(frame) {
    const aspect = soundFrameAspect ?? renderer.domElement.width / renderer.domElement.height;
    const { width, height } = soundAnalysisSize(aspect);
    if (liveSoundTarget?.width !== width || liveSoundTarget?.height !== height) {
        liveSoundTarget?.dispose();
        liveSoundTarget = new THREE.WebGLRenderTarget(width, height, { depthBuffer: true, stencilBuffer: false });
    }
    const previousTarget = renderer.getRenderTarget();
    const previousAspect = camera.aspect;
    const previousFrame = timelineFrame;
    try {
        // Render the exact analysis frame, not whichever frame is on screen.
        setTimelineFrame(frame);
        updateTesseractProjection();
        camera.aspect = aspect;
        camera.updateProjectionMatrix();
        renderer.setRenderTarget(liveSoundTarget);
        withSoundAnalysisMaterial(() => renderer.render(scene, camera));
        const data = new Uint8Array(width * height * 4);
        renderer.readRenderTargetPixels(liveSoundTarget, 0, 0, width, height, data);
        return { data, width, height };
    } finally {
        renderer.setRenderTarget(previousTarget);
        camera.aspect = previousAspect;
        camera.updateProjectionMatrix();
        setTimelineFrame(previousFrame);
        updateTesseractProjection();
    }
}

async function prepareMusicExport(plan, status) {
    if (!visualMusic?.settings.enabled) return null;
    const originalFrame = timelineFrame;
    const originalAspect = camera.aspect;
    const previousTarget = renderer.getRenderTarget();
    const { width: analysisWidth, height: analysisHeight } = soundAnalysisSize(plan.width / plan.height);
    const target = new THREE.WebGLRenderTarget(analysisWidth, analysisHeight, {
        depthBuffer: true,
        stencilBuffer: false
    });
    try {
        camera.aspect = plan.width / plan.height;
        camera.updateProjectionMatrix();
        renderer.setRenderTarget(target);
        return await visualMusic.prepareExport({
            startFrame: plan.startFrame,
            frames: plan.frames,
            fps: exportFps,
            timelineFrames: loopTiming.frameCount,
            signal: videoExportAbort.signal,
            samplePixels: async frame => {
                setTimelineFrame(frame);
                updateTesseractProjection();
                withSoundAnalysisMaterial(() => renderer.render(scene, camera));
                const data = new Uint8Array(analysisWidth * analysisHeight * 4);
                renderer.readRenderTargetPixels(target, 0, 0, analysisWidth, analysisHeight, data);
                return {data, width: analysisWidth, height: analysisHeight};
            },
            onProgress: ({phase, progress: amount}) => {
                const labels = {analyze: 'Reading visual score', synthesize: 'Synthesizing soundtrack', encode: 'Preparing soundtrack'};
                status.textContent = `${labels[phase]}… ${Math.round(amount * 100)}%`;
            }
        });
    } finally {
        renderer.setRenderTarget(previousTarget);
        target.dispose();
        camera.aspect = originalAspect;
        camera.updateProjectionMatrix();
        setTimelineFrame(originalFrame);
        updateTesseractProjection();
    }
}

function screenshotMetadata(extra = {}) {
    return {
        shape: currentShape,
        camera: {
            position: {
                x: camera.position.x,
                y: camera.position.y,
                z: camera.position.z
            }
        },
        rotation: {
            xw: rotationCoefficients.xw,
            yw: rotationCoefficients.yw,
            zw: rotationCoefficients.zw
        },
        time: time,
        animation: {
            frame: timelineFrame,
            frameCount: loopTiming.frameCount,
            fps: exportFps,
            motionStep: rotationSpeed
        },
        target: {
            x: controls.target.x,
            y: controls.target.y,
            z: controls.target.z
        },
        music: visualMusic?.settings ?? restoredMusicSettings,
        ...extra
    };
}

function embedMetadataInPngDataUrl(imageData, metadata = {}) {
    const metadataStr = JSON.stringify(screenshotMetadata(metadata));
    return new Promise((resolve, reject) => {
        const canvas = document.createElement('canvas');
        const img = new Image();
        img.onload = function() {
            canvas.width = img.width;
            canvas.height = img.height;
            const ctx = canvas.getContext('2d');
            ctx.drawImage(img, 0, 0);
            try {
                const marker = 'tESSdata=';
                const fullData = marker + metadataStr;
                const metadataRows = Math.ceil((fullData.length + 2) / canvas.width);
                if (metadataRows > Math.min(canvas.height, 16)) {
                    throw new Error('Screenshot metadata is too large for the image');
                }
                const imgData = ctx.getImageData(0, 0, canvas.width, metadataRows);
                const pixelData = imgData.data;
                pixelData[0] = 254;
                pixelData[1] = 0;
                pixelData[2] = 254;
                pixelData[3] = 255;
                for (let i = 0; i < fullData.length; i++) {
                    const charCode = fullData.charCodeAt(i);
                    const pixelIndex = (i + 1) * 4;
                    pixelData[pixelIndex] = charCode;
                    pixelData[pixelIndex + 1] = 0;
                    pixelData[pixelIndex + 2] = 0;
                    pixelData[pixelIndex + 3] = 255;
                }
                // Stop the reader before it reaches ordinary image pixels.
                const terminator = (fullData.length + 1) * 4;
                if (terminator < pixelData.length) pixelData[terminator] = 0;
                ctx.putImageData(imgData, 0, 0);
                resolve(canvas.toDataURL('image/png'));
            } catch (error) {
                reject(error);
            }
        };
        img.onerror = () => reject(new Error('Could not prepare screenshot metadata'));
        img.src = imageData;
    });
}

async function saveVideoExportPoster(plan, job) {
    const overlayWasVisible = showOverlay;
    const overlayDisplay = controlPanel.style.display;
    let png;
    try {
        if (overlayWasVisible) controlPanel.style.display = 'none';
        setTimelineFrame(plan.startFrame);
        updateTesseractProjection();
        renderer.render(scene, camera);
        png = dataUrlToBlob(await embedMetadataInPngDataUrl(
            renderer.domElement.toDataURL('image/png'),
            {
                kind: 'video-export-poster',
                render: JSON.parse(videoRenderSignature()),
                video: {
                    width: plan.width,
                    height: plan.height,
                    format: plan.format,
                    quality: plan.quality,
                    startFrame: plan.startFrame,
                    frames: plan.frames,
                    checkpointSeconds: plan.checkpointSeconds
                }
            }
        ));
    } finally {
        controlPanel.style.display = overlayDisplay;
    }
    return videoApi(`/api/video/poster?id=${job.id}&lease=${job.lease}`, {
        method: 'POST', headers: { 'Content-Type': 'image/png' }, body: png, signal: videoExportAbort.signal
    });
}

function videoExportFailureMessage(error, stopError, stopAction, hadJob, finishAttempted = false) {
    // Finish consumes its lease before concat. Its expected stale-lease response
    // to our best-effort pause is not a second failure. Keep the pause attempt for
    // network errors or early validation failures that still own a live lease.
    if (finishAttempted && !stopAction && stopError?.message === 'Video export lease is no longer active') stopError = null;
    if (stopError) return `${error.message} Could not ${stopAction === 'discard' ? 'cancel' : 'pause'} the export: ${stopError.message}. Check the interrupted export below.`;
    if (finishAttempted && !stopAction && hadJob) return `${error.message} Finalization failed; checkpoints retained. Check the interrupted export below.`;
    return hadJob ? `${error.message} Export paused and can be resumed.` : error.message;
}

async function runVideoExport(plan, resumableJob = null) {
    if (videoExportRunning) return;
    if (resumableJob) restoreVideoExportForm(resumableJob.request);
    activeVideoExportPlan = {...plan, fps: resumableJob ? Number(resumableJob.request.fps) : exportFps,
                             resumed: Boolean(resumableJob)};
    videoExportRunning = true;
    document.getElementById('video-resume-jobs').inert = true;
    cancelVideoExportRequested = false;
    videoExportAbort = new AbortController();
    videoExportStopAction = null;
    videoExportStopPromise = null;
    videoExportStopJobId = null;
    videoExportWidth = plan.width;
    videoExportHeight = plan.height;
    videoExportQuality = plan.quality;
    persistViewerSettings();
    updateVideoExportSummary();
    const status = document.getElementById('video-export-status');
    const progress = document.getElementById('video-export-progress');
    const cancel = document.getElementById('cancel-video-export');
    const discard = document.getElementById('discard-active-video-export');
    const result = document.getElementById('video-export-result');
    const fields = videoExportDialog.querySelectorAll('input, select');
    fields.forEach(field => { field.disabled = true; });
    document.getElementById('viewer-shape').disabled = true;
    const simpleMode = videoExportDialog.dataset.videoMode === 'simple';
    cancel.hidden = false;
    cancel.disabled = false;
    discard.hidden = simpleMode;
    discard.disabled = false;
    progress.hidden = false;
    progress.max = plan.frames;
    progress.value = resumableJob?.nextFrame || 0;
    result.replaceChildren();
    status.classList.remove('error');
    videoExportDialog.dataset.statusMode = 'running';
    status.textContent = 'Starting encoder…';

    const originalFrame = timelineFrame;
    const originalPaused = animationPaused;
    const originalPixelRatio = renderer.getPixelRatio();
    let lastProgressUpdate = 0;
    let exportStartedAt = 0;
    let releaseEnvironmentLock = null;
    let finishAttempted = false;

    try {
        const prepareCapture = () => {
            releaseEnvironmentLock = skyboxLibrary.acquireRenderLock();
            const gpuLimit = renderer.getContext().getParameter(renderer.getContext().MAX_RENDERBUFFER_SIZE);
            if (plan.width > gpuLimit || plan.height > gpuLimit) throw new Error(`This GPU can render video up to ${gpuLimit}px per side`);
        };
        // A complete checkpoint job only needs server-side concatenation, not
        // a verified current environment or the ability to render its resolution.
        if (!resumableJob || resumableJob.nextFrame < plan.frames) prepareCapture();
        const soundtrack = resumableJob ? null : await prepareMusicExport(plan, status);
        if (resumableJob) {
            activeVideoExportJob = await videoApi('/api/video/resume', {
                method: 'POST', headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    id: resumableJob.id,
                    sourceUrl: location.pathname + location.search,
                    renderSignature: videoRenderSignature()
                })
            });
        } else {
            const name = document.getElementById('video-export-name').value.trim() || 'tesseract';
            activeVideoExportJob = await videoApi('/api/video/start', {
                method: 'POST', headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ name, width: plan.width, height: plan.height, fps: exportFps,
                    frames: plan.frames, quality: plan.quality, format: plan.format, startFrame: plan.startFrame,
                    checkpointSeconds: plan.checkpointSeconds, scratchPath: plan.scratchPath,
                    sourceUrl: location.pathname + location.search, renderSignature: videoRenderSignature(),
                    loopFrameCount: loopTiming.frameCount, loopPeriod: loopTiming.period,
                    timeStep: loopTiming.timeStep, viewerState: viewerSettings(),
                    ...(soundtrack ? {music: soundtrack.metadata} : {}) })
            });
        }

        if (soundtrack) {
            status.textContent = 'Uploading soundtrack…';
            await videoApi(`/api/video/audio?id=${activeVideoExportJob.id}&lease=${activeVideoExportJob.lease}`, {
                method: 'POST', headers: {'Content-Type': 'audio/wav'}, body: soundtrack.wav, signal: videoExportAbort.signal
            });
        }

        const firstFrame = activeVideoExportJob.nextFrame || 0;
        if (firstFrame < plan.frames) {
            // Resume re-verifies checkpoint hashes and can roll back damaged
            // segments. Never render replacements against a changed signature.
            if (!releaseEnvironmentLock) {
                prepareCapture();
                if (resumableJob?.request.renderSignature !== videoRenderSignature()) {
                    throw new Error('Current render settings do not match the repaired export');
                }
            }
            animationPaused = true;
            exportStartedAt = performance.now();
            renderer.setPixelRatio(1);
            renderer.setSize(plan.width, plan.height, false);
            camera.aspect = plan.width / plan.height;
            camera.updateProjectionMatrix();
        }
        if (firstFrame === 0) {
            status.textContent = 'Saving reproducibility frame…';
            await saveVideoExportPoster(plan, activeVideoExportJob);
        }
        for (let frame = firstFrame; frame < plan.frames; frame++) {
            await new Promise(resolve => setTimeout(resolve, 0));
            if (cancelVideoExportRequested) throw new DOMException('Video export cancelled', 'AbortError');
            if (renderer.getContext().isContextLost()) throw new Error('WebGL context was lost before this frame could be captured');
            setTimelineFrame(plan.startFrame + frame);
            updateTesseractProjection();
            renderer.render(scene, camera);
            const png = await canvasPNG(renderer.domElement);
            await new Promise(resolve => setTimeout(resolve, 0));
            if (cancelVideoExportRequested) throw new DOMException('Video export cancelled', 'AbortError');
            const frameResult = await videoApi(`/api/video/frame?id=${activeVideoExportJob.id}&frame=${frame}&lease=${activeVideoExportJob.lease}`, {
                method: 'POST', headers: { 'Content-Type': 'image/png' }, body: png, signal: videoExportAbort.signal
            });
            progress.value = frame + 1;
            const now = performance.now();
            if (now - lastProgressUpdate > 150 || frame + 1 === plan.frames) {
                const elapsedSeconds = Math.max(0.001, (now - exportStartedAt) / 1000);
                const renderRate = (frame - firstFrame + 1) / elapsedSeconds;
                const remainingSeconds = (plan.frames - frame - 1) / renderRate;
                status.textContent = `Rendering + encoding ${(frame + 1).toLocaleString()} / ${plan.frames.toLocaleString()} frames · ${Math.round((frame + 1) / plan.frames * 100)}%${simpleMode ? '' : ` · checkpoint ${frameResult.durableFrame.toLocaleString()}`} · ${renderRate.toFixed(1)} fps · ETA ${formatDuration(remainingSeconds)}`;
                lastProgressUpdate = now;
            }
        }

        status.textContent = `Finalizing ${plan.format.toUpperCase()}…`;
        finishAttempted = true;
        const completed = await videoApi('/api/video/finish', {
            method: 'POST', headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ id: activeVideoExportJob.id })
        });
        activeVideoExportJob = null;
        videoExportDialog.dataset.statusMode = 'complete';
        status.textContent = `Export complete · ${formatBytes(completed.bytes)}`;
        const link = document.createElement('a');
        link.href = completed.url;
        link.download = completed.filename;
        link.textContent = `Download ${completed.filename}`;
        result.replaceChildren(link);
    } catch (error) {
        let stopError = null;
        const hadJob = Boolean(activeVideoExportJob);
        if (activeVideoExportJob) {
            if (videoExportStopAction) {
                ensureVideoExportStopRequest();
                stopError = videoExportStopPromise ? await videoExportStopPromise : null;
            } else {
                try {
                    await videoControlApi('/api/video/pause', {
                        method: 'POST', headers: { 'Content-Type': 'application/json' },
                        body: JSON.stringify({
                            id: activeVideoExportJob.id,
                            lease: activeVideoExportJob.lease,
                            reason: String(error.message || error).slice(0, 500)
                        })
                    });
                } catch (pauseError) { stopError = await resolveVideoPauseError(activeVideoExportJob, pauseError); }
            }
            activeVideoExportJob = null;
        }
        if (videoExportStopAction === 'discard' && !stopError) {
            videoExportDialog.dataset.statusMode = 'cancelled';
            status.textContent = 'Export cancelled and discarded.';
            status.classList.remove('error');
        } else if (videoExportStopAction && !stopError && !hadJob) {
            // Stopped while preparing the soundtrack, before the server job existed.
            videoExportDialog.dataset.statusMode = 'cancelled';
            status.textContent = 'Export cancelled.';
            status.classList.remove('error');
        } else if (videoExportStopAction === 'pause' && !stopError && hadJob) {
            videoExportDialog.dataset.statusMode = 'paused';
            status.textContent = 'Video export paused. You can resume it from its latest checkpoint.';
            status.classList.remove('error');
        } else {
            videoExportDialog.dataset.statusMode = 'error';
            status.textContent = simpleMode
                ? `${error.message} ${stopError ? `Could not stop the export: ${stopError.message}.` : 'Simple export stopped; restart from frame 0.'}`
                : videoExportFailureMessage(error, stopError, videoExportStopAction, hadJob, finishAttempted);
            status.classList.add('error');
        }
    } finally {
        renderer.setPixelRatio(originalPixelRatio);
        renderer.setSize(window.innerWidth, window.innerHeight);
        camera.aspect = window.innerWidth / window.innerHeight;
        camera.updateProjectionMatrix();
        setTimelineFrame(originalFrame);
        updateTesseractProjection();
        renderer.render(scene, camera);
        animationPaused = originalPaused;
        releaseEnvironmentLock?.();
        videoExportRunning = false;
        activeVideoExportPlan = null;
        document.getElementById('video-resume-jobs').inert = false;
        cancelVideoExportRequested = false;
        videoExportAbort = null;
        videoCaptureSurface = null;
        videoCaptureContext = null;
        videoCaptureFallback = false;
        videoExportStopPromise = null;
        videoExportStopJobId = null;
        fields.forEach(field => { field.disabled = false; });
        document.getElementById('viewer-shape').disabled = false;
        cancel.hidden = true;
        discard.hidden = true;
        persistViewerSettings();
        await loadVideoResumeJobs();
        updateVideoExportSummary();
        videoExportStopAction = null;
    }
}

// Function to update camera information display
function updateCameraInfo() {
    if (!cameraInfoDisplay) return;
    
    const pos = camera.position;
    // const rot = camera.rotation;
    const target = controls.target;
    
    // Calculate time in units of π
    const timeInPi = time / Math.PI;
    const timeInPiDisplay = timeInPi.toFixed(2) + "π";
    
    cameraInfoDisplay.innerHTML = `
        <div style="display: grid; grid-template-columns: auto auto; grid-gap: 5px;">
            <div style="text-align: right;">Camera:</div>
            <div style="text-align: right;">${pos.x.toFixed(2)}, ${pos.y.toFixed(2)}, ${pos.z.toFixed(2)}</div>
            
            <div style="text-align: right;">Target:</div>
            <div style="text-align: right;">${target.x.toFixed(2)}, ${target.y.toFixed(2)}, ${target.z.toFixed(2)}</div>
            
            <div style="text-align: right;">Time:</div>
            <div style="text-align: right;">${time.toFixed(2)} (${timeInPiDisplay})</div>
        </div>
    `;
}

// Create sliders for rotation coefficients
function createRotationSliders() {
    const container = document.createElement('div');
    container.style.display = 'grid';
    container.style.gridTemplateColumns = 'auto 1fr auto';
    container.style.gridGap = '5px';
    container.style.alignItems = 'center';
    container.style.marginBottom = '5px';
    
    // Create slider for XW rotation
    const xwLabel = document.createElement('span');
    xwLabel.textContent = 'XW:';
    xwLabel.style.gridColumn = '1';
    
    const xwSlider = document.createElement('input');
    xwSlider.type = 'range';
    xwSlider.min = '-10';
    xwSlider.max = '10';
    xwSlider.step = '0.1';
    xwSlider.value = (rotationCoefficients.xw * 10).toString();
    xwSlider.style.gridColumn = '2';
    xwSlider.style.width = '100%';
    
    const xwValue = document.createElement('span');
    xwValue.textContent = rotationCoefficients.xw.toFixed(1);
    xwValue.style.gridColumn = '3';
    xwValue.style.minWidth = '30px';
    xwValue.style.textAlign = 'right';
    
    xwSlider.addEventListener('input', (e) => {
        rotationCoefficients.xw = parseFloat(e.target.value) / 10;
        xwValue.textContent = rotationCoefficients.xw.toFixed(1);
        updateCameraInfo();
    });
    
    // Create slider for YW rotation
    const ywLabel = document.createElement('span');
    ywLabel.textContent = 'YW:';
    ywLabel.style.gridColumn = '1';
    
    const ywSlider = document.createElement('input');
    ywSlider.type = 'range';
    ywSlider.min = '-10';
    ywSlider.max = '10';
    ywSlider.step = '0.1';
    ywSlider.value = (rotationCoefficients.yw * 10).toString();
    ywSlider.style.gridColumn = '2';
    ywSlider.style.width = '100%';
    
    const ywValue = document.createElement('span');
    ywValue.textContent = rotationCoefficients.yw.toFixed(1);
    ywValue.style.gridColumn = '3';
    ywValue.style.minWidth = '30px';
    ywValue.style.textAlign = 'right';
    
    ywSlider.addEventListener('input', (e) => {
        rotationCoefficients.yw = parseFloat(e.target.value) / 10;
        ywValue.textContent = rotationCoefficients.yw.toFixed(1);
        updateCameraInfo();
    });
    
    // Create slider for ZW rotation
    const zwLabel = document.createElement('span');
    zwLabel.textContent = 'ZW:';
    zwLabel.style.gridColumn = '1';
    
    const zwSlider = document.createElement('input');
    zwSlider.type = 'range';
    zwSlider.min = '-10';
    zwSlider.max = '10';
    zwSlider.step = '0.1';
    zwSlider.value = (rotationCoefficients.zw * 10).toString();
    zwSlider.style.gridColumn = '2';
    zwSlider.style.width = '100%';
    
    const zwValue = document.createElement('span');
    zwValue.textContent = rotationCoefficients.zw.toFixed(1);
    zwValue.style.gridColumn = '3';
    zwValue.style.minWidth = '30px';
    zwValue.style.textAlign = 'right';
    
    zwSlider.addEventListener('input', (e) => {
        rotationCoefficients.zw = parseFloat(e.target.value) / 10;
        zwValue.textContent = rotationCoefficients.zw.toFixed(1);
        updateCameraInfo();
    });
    
    // Add all sliders to the container
    container.appendChild(xwLabel);
    container.appendChild(xwSlider);
    container.appendChild(xwValue);
    
    container.appendChild(ywLabel);
    container.appendChild(ywSlider);
    container.appendChild(ywValue);
    
    container.appendChild(zwLabel);
    container.appendChild(zwSlider);
    container.appendChild(zwValue);
    
    return container;
}

// Save screenshot with embedded metadata
function saveScreenshot() {
    const overlayWasVisible = showOverlay;
    if (overlayWasVisible) controlPanel.style.display = 'none';
    renderer.render(scene, camera);
    const imageData = renderer.domElement.toDataURL('image/png');
    embedMetadataInPngDataUrl(imageData).then(modifiedImageData => {
        const pos = camera.position;
        const target = controls.target;
        const posStr = `pos_${pos.x.toFixed(2)}_${pos.y.toFixed(2)}_${pos.z.toFixed(2)}`;
        const rotStr = `rot_${rotationCoefficients.xw.toFixed(2)}_${rotationCoefficients.yw.toFixed(2)}_${rotationCoefficients.zw.toFixed(2)}`;
        const timeStr = `time_${time.toFixed(2)}`;
        const targetStr = `target_${target.x.toFixed(2)}_${target.y.toFixed(2)}_${target.z.toFixed(2)}`;
        const timestamp = new Date().toISOString().replace(/:/g, '-').replace(/\..+/, '');
        const filename = `tesseract_${timestamp}_${posStr}_${rotStr}_${timeStr}_${targetStr}.png`;
        const link = document.createElement('a');
        link.href = modifiedImageData;
        link.download = filename;
        link.click();
        if (overlayWasVisible) controlPanel.style.display = 'block';
    }).catch(error => {
        console.error('Error embedding metadata, falling back to basic screenshot:', error);
        const link = document.createElement('a');
        link.href = imageData;
        link.download = 'tesseract.png';
        link.click();
        if (overlayWasVisible) controlPanel.style.display = 'block';
    });
}

// Handle keyboard input without stealing keystrokes from dialogs or focused controls.
function onKeyDown(event) {
    const target = event.target;
    if (document.querySelector('dialog[open]') || (target instanceof Element && target.closest('input, textarea, select, button, a, [contenteditable="true"]'))) return;
    switch (event.code) {
        case 'Space':
            // Toggle animation pause
            animationPaused = !animationPaused;
            lastAnimationTimestamp = null;
            frameAccumulator = 0;
            persistViewerSettings();
            break;
        case 'KeyR':
            // Reset animation time
            setTimelineFrame(0);
            persistViewerSettings();
            break;
        case 'KeyO':
            // Toggle overlay visibility
            showOverlay = !showOverlay;
            controlPanel.style.display = showOverlay ? 'block' : 'none';
            break;
        case 'KeyV':
            // Toggle vertex visibility
            showVertices = !showVertices;
            vertices.forEach(vertex => {
                vertex.visible = showVertices;
            });
            const vertexToggle = document.getElementById('vertexToggle');
            if (vertexToggle) vertexToggle.checked = showVertices;
            persistViewerSettings();
            break;
        case 'KeyS':
            // Save screenshot
            saveScreenshot();
            break;
    }
}

// Create vertex and fragment shaders based on the selected type
function createShaderMaterial(shaderType = currentShader) {
    // Common vertex shader for all types
    const vertexShader = `
        varying vec3 vNormal;
        varying vec3 vPosition;
        varying vec3 vViewPosition;
        varying vec3 vWorldPosition;
        // Face-local coordinates (xy) and per-face seed (z); vertex spheres lack it.
        attribute vec3 surface;
        varying vec3 vSurface;
        
        void main() {
            vNormal = normalize(normalMatrix * normal);
            vPosition = position;
            vSurface = surface;
            
            vec4 worldPosition = modelMatrix * vec4(position, 1.0);
            vWorldPosition = worldPosition.xyz;
            
            vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
            vViewPosition = -mvPosition.xyz;
            
            gl_Position = projectionMatrix * mvPosition;
        }
    `;
    
    let fragmentShader;
    
    // Select fragment shader based on current type
    switch(shaderType) {
        case 'iridescent':
            fragmentShader = createIridescentShader();
            break;
        case 'chrome':
            // Built-in PBR supplies the metal BRDF, filtered environment,
            // energy accounting, world-space lights, and two-sided normals.
            break;
        case 'rough':
        default:
            fragmentShader = createRoughShader();
            break;
    }
    
    // Convert lighting type to integer for shader
    let lightingTypeInt;
    switch(currentLighting) {
        case 'topdown':
            lightingTypeInt = 1;
            break;
        case 'quad':
            lightingTypeInt = 2;
            break;
        case 'diagonal':
        default:
            lightingTypeInt = 0;
            break;
    }
    
    const uniforms = {
        lightingType: { value: lightingTypeInt },
        lightDistance: { value: lightDistance },
        surfaceGrain: { value: surfaceGrain ? 1 : 0 },
        dirtyMirrors: { value: dirtyMirrors ? 1 : 0 },
        mirrorReflections: { value: mirrorReflections ? 1 : 0 },
        faceSides: { value: currentShape === 'rectified-5-cell' ? 3 : 4 }
    };
    
    // Add environment map for chrome shader
    if (shaderType === 'chrome') {
        uniforms.envMap = { value: envMap };
        return createPhysicalChromeMaterial(uniforms);
    }
    
    return new THREE.ShaderMaterial({
        vertexShader: vertexShader,
        fragmentShader: fragmentShader,
        wireframe: false,
        side: THREE.DoubleSide,
        uniforms: uniforms
    });
}

// Common shader utility functions
function shaderUtilities() {
    return `
        // Utility function for noise
        float random(vec2 st) {
            return fract(sin(dot(st.xy, vec2(12.9898, 78.233))) * 43758.5453123);
        }

        // Triangular +/-1/255 dither, fixed in screen space so it adds no
        // frame-to-frame noise. Breaks up the 8-bit steps that make dark
        // gradients band, before video's limited-range conversion removes more.
        float viewerDitherNoise(vec2 p) {
            return fract(52.9829189 * fract(dot(p, vec2(0.06711056, 0.00583715))));
        }
        vec3 outputDither(vec3 color) {
            vec2 p = gl_FragCoord.xy;
            float d = viewerDitherNoise(p) + viewerDitherNoise(p + vec2(37.0, 17.0)) - 1.0;
            return color + d / 255.0;
        }
        
        // Utility to calculate fresnel effect
        float fresnel(vec3 viewDirection, vec3 normal, float power) {
            return pow(1.0 - clamp(dot(viewDirection, normal), 0.0, 1.0), power);
        }
        
        // An opaque sheet has two independently lit sides. Orient the normal
        // toward the visible side, not toward a particular light.
        vec3 visibleNormal(vec3 interpolatedNormal) {
            return normalize(interpolatedNormal) * (gl_FrontFacing ? 1.0 : -1.0);
        }

        // Lambertian reflection: rho / pi * I / r^2 * cos(theta).
        // Intensity is in scene-relative units; total I = 4*pi, rho = 0.9.
        // The epsilon only regularizes the point-source singularity.
        float pointIllumination(vec3 worldNormal, vec3 worldPosition, vec3 lightPosition, float share) {
            vec3 delta = lightPosition - worldPosition;
            float distanceSquared = max(dot(delta, delta), 0.000001);
            vec3 lightDirection = delta * inversesqrt(distanceSquared);
            float cosine = max(dot(worldNormal, lightDirection), 0.0);
            return 0.9 * 4.0 * share * cosine / distanceSquared;
        }

        vec3 calculateLighting(vec3 normal, vec3 worldPosition, float lightDist, int lightingType) {
            // normalMatrix supplies view-space normals; undo the camera rotation.
            vec3 worldNormal = normalize((vec4(normal, 0.0) * viewMatrix).xyz);
            // Approximate uniform indirect illumination, not computed light bounce.
            float illumination = 0.02;
            if (lightingType == 2) {
                illumination += pointIllumination(worldNormal, worldPosition, vec3(lightDist, 0.0, 0.0), 0.25);
                illumination += pointIllumination(worldNormal, worldPosition, vec3(-lightDist, 0.0, 0.0), 0.25);
                illumination += pointIllumination(worldNormal, worldPosition, vec3(0.0, 0.0, lightDist), 0.25);
                illumination += pointIllumination(worldNormal, worldPosition, vec3(0.0, 0.0, -lightDist), 0.25);
            } else {
                vec3 direction = lightingType == 1 ? vec3(0.0, 1.0, 0.0) : normalize(vec3(1.0));
                illumination += pointIllumination(worldNormal, worldPosition, direction * lightDist, 1.0);
            }
            return vec3(illumination);
        }
    `;
}

// Create the original rough black and white shader
function createRoughShader() {
    return `
        uniform int lightingType;
        uniform float lightDistance;
        varying vec3 vNormal;
        varying vec3 vPosition;
        varying vec3 vViewPosition;
        varying vec3 vWorldPosition;
        
        ${shaderUtilities()}
        
        void main() {
            vec3 normal = visibleNormal(vNormal);
            
            // Lighting is evaluated at the actual world-space surface point.
            vec3 lighting = calculateLighting(normal, vWorldPosition, lightDistance, lightingType);
            
            // Add rough texture
            float noise = random(vPosition.xy * 10.0) * 0.15;
            lighting *= (1.0 - noise);
            
            // Black and white shader
            gl_FragColor = vec4(lighting, 1.0);
            #include <tonemapping_fragment>
            #include <colorspace_fragment>
            gl_FragColor.rgb = outputDither(gl_FragColor.rgb);
        }
    `;
}

// Create iridescent shader (formerly reflective mirror)
function createIridescentShader() {
    return `
        uniform int lightingType;
        uniform float lightDistance;
        varying vec3 vNormal;
        varying vec3 vPosition;
        varying vec3 vViewPosition;
        varying vec3 vWorldPosition;
        
        ${shaderUtilities()}
        
        void main() {
            vec3 normal = visibleNormal(vNormal);
            vec3 viewDir = normalize(vViewPosition);
            vec3 reflection = reflect(-viewDir, normal);
            
            // Calculate base lighting
            vec3 lighting = calculateLighting(normal, vWorldPosition, lightDistance, lightingType);
            
            // Create iridescent color effect
            vec3 reflectionColor = normalize(reflection) * 0.5 + 0.5;
            
            // Add color shifts based on viewing angle for iridescence
            float fresnelFactor = fresnel(viewDir, normal, 2.0);
            vec3 iridescence = mix(
                vec3(0.4, 0.6, 1.0),  // Blue base
                vec3(1.0, 0.4, 0.8),  // Pink/purple highlight
                fresnelFactor
            );
            
            // Apply iridescent effect with lighting
            vec3 baseColor = mix(reflectionColor, iridescence, 0.7);
            vec3 final = baseColor * lighting;
            
            gl_FragColor = vec4(final, 1.0);
            #include <tonemapping_fragment>
            #include <colorspace_fragment>
            gl_FragColor.rgb = outputDither(gl_FragColor.rgb);
        }
    `;
}

// Spatial masks only: dirt changes material parameters, never emitted light.
function chromeSurfaceShader() {
    return `
        // Dirty mirrors, fixed to each face (vSurface.xy: face coordinates,
        // vSurface.z: per-face seed) so they move with the glass and stay put
        // frame to frame. Fine dust is filtered out as faces become small.
        float valueNoise(vec2 p) {
            vec2 i = floor(p), f = fract(p);
            f = f * f * (3.0 - 2.0 * f);
            return mix(mix(random(i), random(i + vec2(1.0, 0.0)), f.x),
                       mix(random(i + vec2(0.0, 1.0)), random(i + vec2(1.0, 1.0)), f.x), f.y);
        }
        float fbm(vec2 p) {
            float value = 0.0, amplitude = 0.5;
            for (int octave = 0; octave < 4; octave++) {
                value += amplitude * valueNoise(p);
                p *= 2.03;
                amplitude *= 0.5;
            }
            return value;
        }
        float mirrorDirt(vec3 surface) {
            vec2 uv = surface.xy;
            vec2 seed = vec2(surface.z * 37.0, surface.z * 53.0);

            // Distance to the actual polygon boundary, not the UV bounding box:
            // square faces are diamonds here, and the other shape has triangles.
            vec2 p = uv - 0.5;
            float edgeDistance = 1.0;
            float apothem = 0.5 * cos(3.14159265 / faceSides);
            for (int k = 0; k < 4; k++) {
                if (float(k) < faceSides) {
                    float angle = (float(k) + 0.5) * 6.2831853 / faceSides;
                    edgeDistance = min(edgeDistance, apothem - dot(p, vec2(cos(angle), sin(angle))));
                }
            }
            edgeDistance = max(edgeDistance, 0.0);
            float mottling = fbm(uv * 18.0 + seed);
            float deposits = fbm(uv * 47.0 + seed + 9.3);
            // Uneven soft buildup, rather than a uniform painted border.
            float edgeWidth = mix(0.03, 0.13, mottling);
            float edge = exp(-edgeDistance / edgeWidth);
            float rim = exp(-edgeDistance / 0.018);
            float grime = clamp(edge * (0.22 + 0.52 * mottling + 0.22 * deposits)
                + rim * deposits * 0.22, 0.0, 0.9);
            // Settled dusty film softens reflections without obscuring the center.
            float haze = (0.05 + 0.10 * mottling + edge * 0.16) * (0.5 + deposits);

            // Tiny irregular dust flecks, denser near edges. Fade them out under
            // minification instead of turning subpixel specks into bright dots.
            vec2 dustUV = uv * 180.0 + seed;
            vec2 cell = floor(dustUV);
            vec2 center = cell + 0.25 + 0.5 * vec2(random(cell), random(cell + 3.1));
            float radius = mix(0.015, 0.0425, random(cell + 7.7));
            float distance_ = length(dustUV - center);
            float footprint = max(length(fwidth(dustUV)), 0.0001);
            float speck = (1.0 - smoothstep(radius, radius + footprint, distance_))
                * step(0.97 - edge * 0.10, random(cell + 11.3))
                * (1.0 - smoothstep(0.35, 1.2, footprint));
            return clamp(grime + haze + speck * 0.42, 0.0, 1.0);
        }
    `;
}

// Sample shadow-map texel centers, comparing against the receiving plane at
// each center. A single depth comparison at the fragment's position otherwise
// makes a sloping face shadow itself in bands (especially with coarse maps).
function receiverPlaneShadowShader() {
    return `
    #if defined(USE_SHADOWMAP) && NUM_POINT_LIGHT_SHADOWS > 0 && defined(SHADOWMAP_TYPE_PCF)
        vec3 shadowTexelDirection(vec3 d, float size) {
            vec3 a = abs(d);
            vec2 uv;
            if (a.x >= a.y && a.x >= a.z) uv = vec2(d.x > 0.0 ? -d.z : d.z, -d.y) / a.x;
            else if (a.y >= a.z) uv = vec2(d.x, d.y > 0.0 ? d.z : -d.z) / a.y;
            else uv = vec2(d.z > 0.0 ? d.x : -d.x, -d.y) / a.z;
            uv = (floor(clamp(uv * 0.5 + 0.5, 0.0, 0.999999) * size) + 0.5) / size * 2.0 - 1.0;
            if (a.x >= a.y && a.x >= a.z) return vec3(sign(d.x), -uv.y, d.x > 0.0 ? -uv.x : uv.x);
            if (a.y >= a.z) return vec3(uv.x, sign(d.y), d.y > 0.0 ? uv.y : -uv.y);
            return vec3(d.z > 0.0 ? uv.x : -uv.x, -uv.y, sign(d.z));
        }
        float viewerPointShadow(samplerCubeShadow map, vec2 size, float intensity, float bias,
                float radius, vec4 coord, float nearPlane, float farPlane, vec3 worldNormal) {
            vec3 p = coord.xyz;
            float z = max(max(abs(p.x), abs(p.y)), abs(p.z));
            if (z < nearPlane || z > farPlane) return 1.0;
            vec3 direction = normalize(p);
            vec3 tangent = normalize(cross(direction, abs(direction.x) > abs(direction.z) ? vec3(0.0,1.0,0.0) : vec3(1.0,0.0,0.0)));
            vec3 bitangent = cross(direction,tangent);
            float angle = viewerDitherNoise(gl_FragCoord.xy) * 6.28318530718;
            float planeDistance = dot(worldNormal,p);
            float visibility = 0.0;
            for (int i = 0; i < 5; i++) {
                vec2 offset = vogelDiskSample(i,5,angle) * radius / size.x;
                vec3 ray = shadowTexelDirection(direction + tangent * offset.x + bitangent * offset.y, size.x);
                float denominator = dot(worldNormal,ray);
                // A neighboring ray beyond the plane's horizon cannot occlude this point.
                if (abs(denominator) < 0.000001 || planeDistance * denominator <= 0.0) {
                    visibility += 1.0;
                    continue;
                }
                float depth = planeDistance / denominator;
                if (depth < nearPlane || depth > farPlane) { visibility += 1.0; continue; }
                float reference = farPlane * (depth - nearPlane) / (depth * (farPlane - nearPlane));
                #ifdef USE_REVERSED_DEPTH_BUFFER
                    reference = 1.0 - reference;
                    reference -= bias;
                #else
                    reference += bias;
                #endif
                visibility += texture(map,vec4(ray,reference));
            }
            return mix(1.0,visibility * 0.2,intensity);
        }
    #endif
    `;
}

// Current polytopes have at most 48 triangles. A small shared float texture
// avoids fragment-uniform limits and is updated in place with the animation.
function createMirrorTraceState() {
    const data = new Float32Array(6 * 48 * 4);
    const texture = new THREE.DataTexture(data, 6, 48, THREE.RGBAFormat, THREE.FloatType);
    texture.minFilter = texture.magFilter = THREE.NearestFilter;
    texture.generateMipmaps = false;
    texture.needsUpdate = true;
    return {data, texture, count:{value:0}, frame:null};
}

function mirrorTraceShader() {
    return `
    #ifdef ENVMAP_TYPE_CUBE_UV
        vec4 mirrorData(int triangle, int column) {
            return texelFetch(mirrorTriangles,ivec2(column,triangle),0);
        }
        vec3 mirrorSource(vec3 direction, float roughness, vec3 dx, vec3 dy) {
            direction = envMapRotation * direction;
            if (roughness <= 0.06) {
                direction.x = -direction.x;
                dx=envMapRotation*dx; dy=envMapRotation*dy;
                dx.x=-dx.x; dy.x=-dy.x;
                // Never infer texture detail from neighboring rays that may
                // have hit completely different mirrors. That makes dotted seams.
                return textureGrad(mirrorEnvironment,direction,dx,dy).rgb;
            }
            return textureCubeUV(envMap,direction,roughness).rgb;
        }
        vec3 traceMirrorRay(vec3 origin, vec3 direction, float roughness, vec3 dx, vec3 dy, out float hitId) {
            hitId = -1.0;
            float nearest = 1.0e20;
            int closest = -1;
            vec2 barycentric = vec2(0.0);
            vec3 hitNormal = vec3(0.0);
            for(int i=0;i<48;i++) {
                if(i>=mirrorTriangleCount)break;
                // Exclude the originating polygon explicitly, not a finite
                // distance strip around every intersection with another sheet.
                int faceIndex = faceSides > 3.5 ? i/2 : i;
                if(vMirrorFace >= 0.0 && faceIndex == int(vMirrorFace+0.5))continue;
                vec4 av=mirrorData(i,0),bv=mirrorData(i,1),cv=mirrorData(i,2);
                vec3 n=vec3(av.w,bv.w,cv.w);
                float denominator=dot(n,direction);
                if(abs(denominator)<0.0000001)continue;
                float planeDistance=dot(n,av.xyz-origin);
                float distance_=planeDistance/denominator;
                // Other sheets may genuinely meet this one at zero distance.
                // A large near-hit epsilon punches bright seams into those joints.
                if(distance_<=0.0000001 || distance_>=nearest)continue;
                vec3 a=av.xyz;
                vec3 e1=bv.xyz-a;
                vec3 e2=cv.xyz-a;
                vec3 p = cross(direction,e2);
                float determinant = dot(e1,p);
                if (abs(determinant) < 0.0000001) continue;
                float inverse = 1.0 / determinant;
                vec3 s = origin - a;
                float u = dot(s,p) * inverse;
                // A shared edge must not fall through both triangles due to
                // opposite roundoff signs in their barycentric coordinates.
                if (u < -0.000001 || u > 1.000001) continue;
                vec3 q = cross(s,e1);
                float v = dot(direction,q) * inverse;
                if (v < -0.000001 || u+v > 1.000001) continue;
                nearest = distance_;
                closest = i;
                barycentric = vec2(u,v);
                hitNormal = n;
            }
            if (closest < 0) return mirrorSource(direction,roughness,dx,dy);
            hitId = float(closest);
            if (dot(hitNormal,direction) > 0.0) hitNormal = -hitNormal;
            float w = 1.0-barycentric.x-barycentric.y;
            vec3 surface = mirrorData(closest,3).xyz*w + mirrorData(closest,4).xyz*barycentric.x + mirrorData(closest,5).xyz*barycentric.y;
            float coverage = dirtyMirrors > 0.5 ? 0.45 * mirrorDirt(surface) : 0.0;
            vec3 tint = mix(vec3(0.55,0.56,0.58),vec3(0.22,0.19,0.14),coverage);
            float metal = 1.0 - 0.2*coverage;
            vec3 f0 = mix(vec3(0.04),tint,metal);
            vec3 fresnel_ = f0 + (1.0-f0)*pow(1.0-max(dot(-direction,hitNormal),0.0),5.0);
            float secondaryRoughness = mix(0.005,0.12,coverage);
            // Bounded transport: secondary reflection ends at the environment.
            vec3 reflected = mirrorSource(reflect(direction,hitNormal),max(roughness,secondaryRoughness),reflect(dx,hitNormal),reflect(dy,hitNormal));
            vec3 diffuse = textureCubeUV(envMap,envMapRotation*hitNormal,1.0).rgb * tint * (1.0-metal) * (1.0-fresnel_);
            return fresnel_*reflected + diffuse;
        }
        vec3 reflectedScene(vec3 direction, float roughness) {
            // Derivatives are evaluated before any divergent tracing branches.
            vec3 dx=dFdx(direction),dy=dFdy(direction);
            if (mirrorReflections < 0.5 || mirrorTriangleCount == 0) return mirrorSource(direction,roughness,dx,dy);
            vec3 origin = vMirrorWorldPosition;
            vec3 ox=dFdx(origin),oy=dFdy(origin);
            float hitId;
            vec3 color=traceMirrorRay(origin,direction,roughness,dx,dy,hitId);
            // Adjacent rays hit different sheets (or the environment): integrate
            // four subpixel rays only along those reflected boundaries.
            if (fwidth(hitId)>0.5) {
                float ignored;
                color = traceMirrorRay(origin-0.25*ox-0.25*oy,normalize(direction-0.25*dx-0.25*dy),roughness,dx,dy,ignored);
                color += traceMirrorRay(origin+0.25*ox-0.25*oy,normalize(direction+0.25*dx-0.25*dy),roughness,dx,dy,ignored);
                color += traceMirrorRay(origin-0.25*ox+0.25*oy,normalize(direction-0.25*dx+0.25*dy),roughness,dx,dy,ignored);
                color += traceMirrorRay(origin+0.25*ox+0.25*oy,normalize(direction+0.25*dx+0.25*dy),roughness,dx,dy,ignored);
                color *= 0.25;
            }
            return color;
        }
    #endif
    `;
}

function createPhysicalChromeMaterial(uniforms) {
    const material = new THREE.MeshStandardMaterial({
        // Approximate chromium normal-incidence reflectance, in linear RGB.
        color: new THREE.Color().setRGB(0.55, 0.56, 0.58),
        metalness: 1,
        roughness: 0.005,
        envMap: uniforms.envMap.value,
        envMapIntensity: 1,
        side: THREE.DoubleSide
    });
    // Preserve the existing UI and soundtrack's per-material controls.
    material.uniforms = uniforms;
    mirrorTraceState ??= createMirrorTraceState();
    material.userData.mirrorTraceState = mirrorTraceState;
    material.onBeforeCompile = shader => {
        for (const name of ['surfaceGrain', 'dirtyMirrors', 'faceSides', 'mirrorReflections']) shader.uniforms[name] = uniforms[name];
        shader.uniforms.mirrorEnvironment = uniforms.envMap;
        shader.uniforms.mirrorTriangles = {value: mirrorTraceState.texture};
        shader.uniforms.mirrorTriangleCount = mirrorTraceState.count;
        // MSAA shades covered samples even when the pixel center is outside
        // the triangle. Centroid interpolation keeps ray origins on the sheet.
        shader.vertexShader = 'attribute vec3 surface; attribute float mirrorFace; centroid varying float vMirrorFace; centroid varying vec3 vSurface; centroid varying vec3 vGrainPosition; centroid varying vec3 vMirrorWorldPosition;\n' + shader.vertexShader;
        shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>', '#include <begin_vertex>\nvSurface = surface; vMirrorFace = mirrorFace; vGrainPosition = position; vMirrorWorldPosition = (modelMatrix * vec4(position,1.0)).xyz;');
        shader.fragmentShader = `uniform samplerCube mirrorEnvironment;
            uniform sampler2D mirrorTriangles; uniform int mirrorTriangleCount;
            uniform float mirrorReflections;
            centroid varying vec3 vMirrorWorldPosition;
            centroid varying float vMirrorFace;
            uniform float surfaceGrain; uniform float dirtyMirrors; uniform float faceSides;
            centroid varying vec3 vSurface;
            centroid varying vec3 vGrainPosition;
            ${shaderUtilities()}
            ${chromeSurfaceShader()}
        ` + shader.fragmentShader;
        // Standard PBR clamps roughness to 0.0525 and uses a prefiltered map.
        // For polished surfaces, retain source resolution instead. Dust still
        // uses the filtered map; the BRDF/Fresnel and direct lights stay standard.
        const environmentShader = THREE.ShaderChunk.envmap_physical_pars_fragment.replace(
            'vec4 envMapColor = textureCubeUV( envMap, envMapRotation * reflectVec, roughness );',
            'vec4 envMapColor = vec4(reflectedScene(reflectVec,roughness),1.0);'
        );
        shader.fragmentShader = shader.fragmentShader.replace('#include <envmap_physical_pars_fragment>', mirrorTraceShader() + environmentShader);
        shader.fragmentShader = shader.fragmentShader.replace('#include <shadowmap_pars_fragment>', '#include <shadowmap_pars_fragment>\n' + receiverPlaneShadowShader());
        const shadowLighting = THREE.ShaderChunk.lights_fragment_begin
            .replace('getPointShadow( pointShadowMap[ i ],', 'viewerPointShadow( pointShadowMap[ i ],')
            .replace('pointLightShadow.shadowCameraFar )', 'pointLightShadow.shadowCameraFar, transformDirectionByInverseViewMatrix(geometryNormal,viewMatrix) )');
        shader.fragmentShader = shader.fragmentShader.replace('#include <lights_fragment_begin>', shadowLighting);
        shader.fragmentShader = shader.fragmentShader.replace('#include <roughnessmap_fragment>', `
            #include <roughnessmap_fragment>
            float coverage = 0.0;
            if (dirtyMirrors > 0.5) coverage = 0.45 * mirrorDirt(vSurface);
            // Thin deposits tint/attenuate the reflection without replacing the
            // mirror with matte dust. Grain is a separate artistic image effect.
            roughnessFactor = mix(roughnessFactor, 0.12, coverage);
            diffuseColor.rgb = mix(diffuseColor.rgb, vec3(0.22, 0.19, 0.14), coverage);
        `);
        shader.fragmentShader = shader.fragmentShader.replace('#include <metalnessmap_fragment>', '#include <metalnessmap_fragment>\nmetalnessFactor *= 1.0 - 0.2 * coverage;');
        // Restore the original deterministic, face-position grain. Both the
        // visible render and forced-on music analysis use this exact treatment.
        shader.fragmentShader = shader.fragmentShader.replace('#include <opaque_fragment>', `
            #include <opaque_fragment>
            if (surfaceGrain > 0.5) gl_FragColor.rgb = max(vec3(0.0), gl_FragColor.rgb - vec3(random(vGrainPosition.xy * 20.0) * 0.05));
        `);
        shader.fragmentShader = shader.fragmentShader.replace('#include <dithering_fragment>', 'gl_FragColor.rgb = outputDither(gl_FragColor.rgb);');
    };
    material.customProgramCacheKey = () => 'physical-chrome-v9-one-bounce-explicit-gradients';
    return material;
}

// Function to project 4D to 3D using simple projection
function project4Dto3D(vertex4D, w_factor = 0.5) {
    const distance = 2 + vertex4D.w * w_factor;
    const scale = 1 / distance;
    
    return {
        x: vertex4D.x * scale,
        y: vertex4D.y * scale,
        z: vertex4D.z * scale
    };
}

// Regular tesseract and rectified regular 4-simplex.
function polytopeTopology(shape = 'tesseract') {
    if (shape === 'rectified-5-cell') {
        // Rectify a regular 4-simplex: its ten edge midpoints become vertices.
        // Scale so every resulting edge has length 2, matching the tesseract.
        const h = 1 / Math.sqrt(5);
        const simplex = [[1,1,1,-h],[1,-1,-1,-h],[-1,1,-1,-h],[-1,-1,1,-h],[0,0,0,4*h]];
        const pairs = [], vertices = [], edges = [], faces = [];
        for (let a = 0; a < 5; a++) for (let b = a + 1; b < 5; b++) {
            pairs.push([a,b]);
            const coordinates = simplex[a].map((value, axis) => (value + simplex[b][axis]) / Math.sqrt(2));
            vertices.push(Object.fromEntries(['x','y','z','w'].map((axis, index) => [axis, coordinates[index]])));
        }
        const adjacent = (a,b) => pairs[a].some(index => pairs[b].includes(index));
        for (let a = 0; a < 10; a++) for (let b = a + 1; b < 10; b++) {
            if (!adjacent(a,b)) continue;
            edges.push([a,b]);
            for (let c = b + 1; c < 10; c++) {
                if (adjacent(a,c) && adjacent(b,c)) faces.push([a,b,c]);
            }
        }
        return {vertices, edges, faces};
    }
    const points = [];
    const factors = [];
    for (const x of [-1, 1]) for (const y of [-1, 1])
        for (const z of [-1, 1]) for (const w of [-1, 1]) {
            points.push({x, y, z, w});
            factors.push([x, y, z, w]);
        }
    const edgeList = [], neighbors = points.map(() => []);
    for (let a = 0; a < points.length; a++) for (let b = a + 1; b < points.length; b++) {
        if (factors[a].filter((value, axis) => value !== factors[b][axis]).length === 1) {
            edgeList.push([a, b]);neighbors[a].push(b);neighbors[b].push(a);
        }
    }
    // The cube's 4-cycles are precisely its square 2-faces.
    // Preserve the original cube ordering.
    const faceList = [], seen = new Set();
    const addFace = indices => {
        const key = [...indices].sort((a,b) => a-b).join('-');
        if (!seen.has(key)) {seen.add(key);faceList.push(indices);}
    };
    for (let a = 0; a < points.length; a++) for (const b of neighbors[a])
        for (const c of neighbors[b]) {
            if (c === a) continue;
            for (const d of neighbors[c]) {
                if (d !== a && d !== b && neighbors[d].includes(a)) addFace([a,b,c,d]);
            }
        }
    return {vertices: points, edges: edgeList, faces: faceList};
}

function setViewerShape(shape) {
    if (!['tesseract', 'rectified-5-cell'].includes(shape) || videoExportRunning) return;
    if (shape === currentShape) return;
    currentShape = shape;
    if (scene && tesseract) {
        const geometries = new Set(), materials = new Set();
        tesseract.traverse(object => {
            if (object.geometry) geometries.add(object.geometry);
            if (object.material) materials.add(object.material);
        });
        scene.remove(tesseract);
        geometries.forEach(geometry => geometry.dispose());
        materials.forEach(material => material.dispose());
        createTesseract();
        updateTesseractProjection();
    }
    const select = document.getElementById('viewer-shape');
    if (select) select.value = currentShape;
}

// Each corner sits on a unit regular polygon in the face's own coordinates, with a
// per-face seed, fan-triangulated in the same order as facePositionArray.
function faceSurfaceArray(indices, faceIndex) {
    const seed = (faceIndex * 0.6180339887) % 1;
    const corner = k => [0.5 + 0.5 * Math.cos(2 * Math.PI * k / indices.length),
                         0.5 + 0.5 * Math.sin(2 * Math.PI * k / indices.length), seed];
    const surface = [];
    for (let i = 1; i + 1 < indices.length; i++) {
        for (const k of [0, i, i + 1]) surface.push(...corner(k));
    }
    return new Float32Array(surface);
}

function facePositionArray(indices) {
    const positions = [];
    for (let i = 1; i + 1 < indices.length; i++) {
        for (const index of [indices[0], indices[i], indices[i + 1]]) {
            const point = vertices[index].position;
            positions.push(point.x, point.y, point.z);
        }
    }
    return new Float32Array(positions);
}

// Build the currently selected 4D polytope using the existing renderer/shaders.
function createTesseract() {
    // A tesseract is the 4D analog of a cube - we'll visualize it as a projection to 3D
    tesseract = new THREE.Group();
    tesseract.name = currentShape;
    scene.add(tesseract);
    
    const material = createShaderMaterial();
    
    const topology = polytopeTopology(currentShape);
    const vertices4D = topology.vertices;
    
    // First create vertex objects
    vertices = [];
    for (let i = 0; i < vertices4D.length; i++) {
        const vertex3D = project4Dto3D(vertices4D[i]);
        
        // Create a small sphere to visually represent the vertex
        const vertexGeometry = new THREE.SphereGeometry(0.03, 8, 8);
        vertexGeometry.setAttribute('mirrorFace', new THREE.BufferAttribute(new Float32Array(vertexGeometry.getAttribute('position').count).fill(-1), 1));
        const vertexMesh = new THREE.Mesh(vertexGeometry, material);
        vertexMesh.castShadow = vertexMesh.receiveShadow = true;
        
        vertexMesh.position.set(vertex3D.x, vertex3D.y, vertex3D.z);
        vertexMesh.userData = { vertexIndex: i, vertex4D: {...vertices4D[i]} };
        vertexMesh.visible = showVertices;
        
        tesseract.add(vertexMesh);
        vertices.push(vertexMesh);
    }
    
    // Faces meet directly; separate line geometry caused intermittent white
    // outlines where coplanar edges competed with faces in the depth buffer.
    edges = [];
    
    // Create faces for the tesseract
    faces = [];
    for (const indices of topology.faces) {
        const geometry = new THREE.BufferGeometry();
        const surface = faceSurfaceArray(indices, faces.length);
        geometry.setAttribute('position', new THREE.BufferAttribute(facePositionArray(indices), 3));
        geometry.setAttribute('surface', new THREE.BufferAttribute(surface, 3));
        geometry.setAttribute('mirrorFace', new THREE.BufferAttribute(new Float32Array(geometry.getAttribute('position').count).fill(faces.length), 1));
        geometry.computeVertexNormals();
        const face = new THREE.Mesh(geometry, material);
        face.receiveShadow = true;
        face.userData = {vertices: indices, surface};
        tesseract.add(face);
        faces.push(face);
    }
    // One merged caster: six draws per point light, not six per face.
    // It is never drawn in a color pass, including scene.overrideMaterial passes.
    const shadowGeometry = new THREE.BufferGeometry();
    const count = faces.reduce((sum, face) => sum + face.geometry.getAttribute('position').array.length, 0);
    shadowGeometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array(count), 3));
    const shadowMesh = new THREE.Mesh(shadowGeometry, new THREE.MeshBasicMaterial({ side: THREE.DoubleSide, colorWrite: false, depthWrite: false }));
    shadowMesh.castShadow = true;
    shadowMesh.onBeforeRender = () => shadowGeometry.setDrawRange(0, 0);
    shadowMesh.onAfterRender = () => shadowGeometry.setDrawRange(0, Infinity);
    tesseract.userData.shadowMesh = shadowMesh;
    tesseract.add(shadowMesh);
    updateTesseractProjection();
}

// Project the 4D tesseract to 3D dynamically
function updateTesseractProjection() {
    // Apply rotation coefficients to current time
    const w_rotation1 = time * rotationCoefficients.xw;  // XW rotation
    const w_rotation2 = time * rotationCoefficients.yw;  // YW rotation
    const w_rotation3 = time * rotationCoefficients.zw;  // ZW rotation
    
    // First update vertex positions
    for (let i = 0; i < vertices.length; i++) {
        const vertex = vertices[i];
        const vertex4D = vertex.userData.vertex4D;
        const rotated4D = rotate4D(vertex4D, w_rotation1, w_rotation2, w_rotation3);
        const projected3D = project4Dto3D(rotated4D);
        
        // Update vertex position
        vertex.position.set(projected3D.x, projected3D.y, projected3D.z);
    }
    
    // Then update edges
    for (let i = 0; i < edges.length; i++) {
        const edge = edges[i];
        const startIdx = edge.userData.startIdx;
        const endIdx = edge.userData.endIdx;
        
        // Get the updated vertex positions
        const startPos = vertices[startIdx].position;
        const endPos = vertices[endIdx].position;
        
        // Update the edge geometry
        const points = [
            new THREE.Vector3(startPos.x, startPos.y, startPos.z),
            new THREE.Vector3(endPos.x, endPos.y, endPos.z)
        ];
        
        // Replace the old geometry
        if (edge.geometry) edge.geometry.dispose();
        edge.geometry = new THREE.BufferGeometry().setFromPoints(points);
    }
    
    // Finally update face geometries
    for (let i = 0; i < faces.length; i++) {
        const face = faces[i];
        const faceVertices = face.userData.vertices;
        
        // Topology is fixed during animation. Reuse GPU buffers rather than
        // disposing/reallocating every face on every displayed/exported frame.
        const geometry = face.geometry;
        const position = geometry.getAttribute('position');
        let offset = 0;
        for (let triangle = 1; triangle < faceVertices.length - 1; triangle++) {
            for (const index of [faceVertices[0], faceVertices[triangle], faceVertices[triangle + 1]]) {
                const point = vertices[index].position;
                position.array[offset++] = point.x;
                position.array[offset++] = point.y;
                position.array[offset++] = point.z;
            }
        }
        position.needsUpdate = true;
        geometry.computeVertexNormals();
        geometry.computeBoundingSphere();
    }
    const shadowMesh = tesseract?.userData.shadowMesh;
    if (shadowMesh) {
        const position = shadowMesh.geometry.getAttribute('position');
        let offset = 0;
        for (const face of faces) {
            const array = face.geometry.getAttribute('position').array;
            position.array.set(array, offset);
            offset += array.length;
        }
        position.needsUpdate = true;
        shadowMesh.geometry.computeBoundingSphere();
    }
    if (mirrorTraceState) {
        const frame = `${currentShape}/${time}`;
        if (mirrorTraceState.frame !== frame) {
            let triangle = 0;
            for (const face of faces) {
                const position = face.geometry.getAttribute('position').array;
                const surface = face.geometry.getAttribute('surface').array;
                // Faces store projected world coordinates (their mesh/group
                // transforms are identity), as does the merged shadow caster.
                for (let offset=0; offset<position.length; offset+=9) {
                    if (triangle >= 48) throw new Error('Mirror triangle capacity exceeded');
                    const ax=position[offset+3]-position[offset],ay=position[offset+4]-position[offset+1],az=position[offset+5]-position[offset+2];
                    const bx=position[offset+6]-position[offset],by=position[offset+7]-position[offset+1],bz=position[offset+8]-position[offset+2];
                    const nx=ay*bz-az*by,ny=az*bx-ax*bz,nz=ax*by-ay*bx;
                    const length=Math.hypot(nx,ny,nz);
                    for (let corner=0; corner<3; corner++) {
                        const src = offset + corner*3;
                        const dst = (triangle*6 + corner)*4;
                        mirrorTraceState.data[dst] = position[src];
                        mirrorTraceState.data[dst+1] = position[src+1];
                        mirrorTraceState.data[dst+2] = position[src+2];
                        mirrorTraceState.data[dst+3] = length>0.0000001 ? (corner===0 ? nx : corner===1 ? ny : nz)/length : 0;
                        const uv = dst+12;
                        mirrorTraceState.data[uv] = surface[src];
                        mirrorTraceState.data[uv+1] = surface[src+1];
                        mirrorTraceState.data[uv+2] = surface[src+2];
                    }
                    triangle++;
                }
            }
            mirrorTraceState.count.value = triangle;
            mirrorTraceState.texture.needsUpdate = true;
            mirrorTraceState.frame = frame;
        }
    }
}

// 4D rotation functions
function rotate4D(point4D, angleXW, angleYW, angleZW) {
    // Clone the point to avoid modifying the original
    const p = {x: point4D.x, y: point4D.y, z: point4D.z, w: point4D.w};
    
    // Rotate in XW plane
    const xw_x = p.x * Math.cos(angleXW) - p.w * Math.sin(angleXW);
    const xw_w = p.x * Math.sin(angleXW) + p.w * Math.cos(angleXW);
    p.x = xw_x;
    p.w = xw_w;
    
    // Rotate in YW plane
    const yw_y = p.y * Math.cos(angleYW) - p.w * Math.sin(angleYW);
    const yw_w = p.y * Math.sin(angleYW) + p.w * Math.cos(angleYW);
    p.y = yw_y;
    p.w = yw_w;
    
    // Rotate in ZW plane
    const zw_z = p.z * Math.cos(angleZW) - p.w * Math.sin(angleZW);
    const zw_w = p.z * Math.sin(angleZW) + p.w * Math.cos(angleZW);
    p.z = zw_z;
    p.w = zw_w;
    
    return p;
}

// Function to handle window resize
function onWindowResize() {
    if (videoExportRunning) return;
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
}

// Animation loop. Time is derived from an integer frame so frame 0 follows the
// final frame exactly, without accumulating floating-point additions.
function animate(timestamp) {
    requestAnimationFrame(animate);
    // The export loop owns the canvas. A live present here fights the frame
    // readback and can block once this window is no longer visible.
    if (videoExportRunning) return;

    // Update controls
    controls.update();
    
    if (!animationPaused && loopTiming.frameCount > 1) {
        if (Number.isFinite(timestamp)) {
            if (Number.isFinite(lastAnimationTimestamp)) {
                const delta = timestamp - lastAnimationTimestamp;
                if (delta > 0) {
                    frameAccumulator += delta * exportFps / 1000;
                    const framesToAdvance = Math.floor(frameAccumulator);
                    if (framesToAdvance > 0) {
                        setTimelineFrame(timelineFrame + framesToAdvance);
                        frameAccumulator -= framesToAdvance;
                    }
                }
            }
            lastAnimationTimestamp = timestamp;
        }
    } else {
        lastAnimationTimestamp = null;
        frameAccumulator = 0;
    }

    // Update camera information
    updateCameraInfo();
    
    // Update the tesseract projection
    updateTesseractProjection();
    
    // Render the scene, then let the soundtrack inspect the actual final pixels.
    renderer.render(scene, camera);
    visualMusic?.tick({frame: timelineFrame, fps: exportFps, paused: animationPaused});
}

// Initialize file upload handler for loading views
function initFileUpload() {
    const fileInput = document.createElement('input');
    fileInput.type = 'file';
    fileInput.setAttribute('aria-label', 'Load saved view (PNG screenshot)');
    fileInput.accept = 'image/png';
    fileInput.style.display = 'none';
    document.body.appendChild(fileInput);
    
    fileInput.addEventListener('change', function(event) {
        if (event.target.files.length > 0) {
            const file = event.target.files[0];
            console.log("Loading view from file:", file.name);
            
            // Read the metadata from the PNG file
            readMetadataFromPNG(file);
        }
    });
    
    // Create a load button container
    const loadButtonContainer = document.createElement('div');
    loadButtonContainer.style.marginTop = '10px';
    loadButtonContainer.style.marginBottom = '10px';
    loadButtonContainer.style.textAlign = 'center';
    
    // Add a load view button to the control panel
    const loadButton = document.createElement('button');
    loadButton.textContent = 'Load';
    loadButton.style.width = '100%';
    loadButton.style.padding = '5px';
    loadButton.addEventListener('click', function() {
        fileInput.click();
    });
    
    loadButtonContainer.appendChild(loadButton);
    document.getElementById('controlPanelContent').appendChild(loadButtonContainer);
}

// Start the visualization
init(); 

// Update materials with the new environment map
function updateMaterialsWithEnvMap() {
    // Only needed for the chrome shader which uses environment mapping
    if (currentShader === 'chrome') {
        const materials = [];
        faces.forEach(face => {
            if (face.material && !materials.includes(face.material)) {
                materials.push(face.material);
            }
        });
        
        vertices.forEach(vertex => {
            if (vertex.material && !materials.includes(vertex.material)) {
                materials.push(vertex.material);
            }
        });
        
        materials.forEach(material => {
            if (material.uniforms && material.uniforms.envMap) {
                material.uniforms.envMap.value = envMap;
                material.envMap = envMap;
                material.needsUpdate = true;
            }
        });
    }
    if (soundAnalysisMaterial) {
        soundAnalysisMaterial.envMap = envMap;
        soundAnalysisMaterial.needsUpdate = true;
    }
}

// Scriptable API for automation and AI agents (window.viewer). Settings are applied through
// the same controls a person uses, so the panel, scene and saved settings stay in sync.
function installViewerAPI() {
    const SETTINGS = {
        shape: { control: 'viewer-shape', values: ['tesseract', 'rectified-5-cell'] },
        shader: { control: 'viewer-shader', values: ['chrome', 'rough', 'iridescent'] },
        lighting: { control: 'viewer-lighting', values: ['diagonal', 'topdown', 'quad'] },
        lightDistance: { control: 'viewer-light-distance', min: 0.1, max: 20, step: 0.1 },
        rotationSpeed: { min: 0, max: 0.01, step: 0.001 },
        rotationCoefficients: { axes: ['xw', 'yw', 'zw'], min: -1, max: 1, step: 0.05 },
        showVertices: { type: 'boolean' },
        surfaceGrain: { type: 'boolean', note: 'chrome shader only' },
        dirtyMirrors: { type: 'boolean', note: 'chrome shader only' },
        mirrorReflections: { type: 'boolean', note: 'chrome: one additional face reflection; disable for performance comparison' },
        exportFps: { values: [24, 25, 30, 50, 60] },
        animationPaused: { type: 'boolean' },
        timelineFrame: { type: 'integer', note: 'wraps around the loop length' },
        camera: { shape: '{position: {x, y, z}, target: {x, y, z}}', note: 'default position is (3, 3, 3), target (0, 0, 0)' }
    };
    const require = (condition, message) => {
        if (!condition) throw new Error(message);
    };
    const unlocked = () => require(!videoExportRunning, 'The viewer is locked while a video export renders.');
    const setControl = (element, value) => {
        element.value = String(value);
        element.dispatchEvent(new Event('input', { bubbles: true }));
        element.dispatchEvent(new Event('change', { bubbles: true }));
    };
    const number = (key, value) => {
        require(Number.isFinite(Number(value)), `${key} must be a number`);
        return Number(value);
    };
    const vector = (key, value) => {
        require(value && ['x', 'y', 'z'].every(axis => Number.isFinite(Number(value[axis]))), `${key} must be {x, y, z} numbers`);
        return { x: Number(value.x), y: Number(value.y), z: Number(value.z) };
    };

    function setState(changes) {
        unlocked();
        require(changes && typeof changes === 'object', 'setState takes an object of settings; see describe()');
        const unknown = Object.keys(changes).filter(key => !(key in SETTINGS));
        require(!unknown.length, `Unknown setting ${unknown.join(', ')}. Valid: ${Object.keys(SETTINGS).join(', ')}`);
        for (const key of ['shape', 'shader', 'lighting', 'exportFps']) {
            if (key in changes) require(SETTINGS[key].values.includes(changes[key]), `${key} must be one of ${SETTINGS[key].values.join(', ')}`);
        }
        for (const [key, value] of Object.entries(changes)) {
            switch (key) {
                case 'shape': case 'shader': case 'lighting':
                    setControl(document.getElementById(SETTINGS[key].control), value);
                    break;
                case 'lightDistance':
                    setControl(document.getElementById('viewer-light-distance'), number(key, value));
                    break;
                case 'rotationSpeed':
                    setControl(motionStepSlider, Math.round(number(key, value) * 1000));
                    break;
                case 'rotationCoefficients':
                    require(value && typeof value === 'object', 'rotationCoefficients must be {xw, yw, zw}');
                    for (const [axis, coefficient] of Object.entries(value)) {
                        require(SETTINGS.rotationCoefficients.axes.includes(axis), `Unknown rotation axis ${axis}; use xw, yw or zw`);
                        setControl(document.getElementById(`rotation-${axis}`), Math.round(number(axis, coefficient) * 20));
                    }
                    break;
                case 'showVertices': {
                    require(typeof value === 'boolean', 'showVertices must be true or false');
                    const checkbox = document.getElementById('vertexToggle');
                    checkbox.checked = value;
                    checkbox.dispatchEvent(new Event('change', { bubbles: true }));
                    break;
                }
                case 'surfaceGrain': {
                    require(typeof value === 'boolean', 'surfaceGrain must be true or false');
                    const checkbox = document.getElementById('grainToggle');
                    checkbox.checked = value;
                    checkbox.dispatchEvent(new Event('change', { bubbles: true }));
                    break;
                }
                case 'dirtyMirrors': {
                    require(typeof value === 'boolean', 'dirtyMirrors must be true or false');
                    const checkbox = document.getElementById('dirtyMirrorsToggle');
                    checkbox.checked = value;
                    checkbox.dispatchEvent(new Event('change', { bubbles: true }));
                    break;
                }
                case 'mirrorReflections': {
                    require(typeof value === 'boolean', 'mirrorReflections must be true or false');
                    const checkbox = document.getElementById('viewer-mirror-reflections');
                    checkbox.checked = value;
                    checkbox.dispatchEvent(new Event('change', { bubbles: true }));
                    break;
                }
                case 'exportFps':
                    setControl(exportFpsSelect, value);
                    break;
                case 'animationPaused':
                    require(typeof value === 'boolean', 'animationPaused must be true or false');
                    animationPaused = value;
                    lastAnimationTimestamp = null;
                    frameAccumulator = 0;
                    break;
                case 'timelineFrame':
                    require(Number.isInteger(value), 'timelineFrame must be a whole number');
                    pauseAnimation();
                    setTimelineFrame(value);
                    break;
                case 'camera':
                    if (value?.position) camera.position.set(...Object.values(vector('camera.position', value.position)));
                    if (value?.target) controls.target.set(...Object.values(vector('camera.target', value.target)));
                    controls.update();
                    updateCameraInfo();
                    break;
            }
        }
        persistViewerSettings();
        return getState();
    }

    function getState() {
        return {
            ...viewerSettings(),
            skybox: skyboxLibrary?.activeFolder?.() ?? null,
            skyboxStatus: skyboxLibrary?.statusMessage?.() ?? '',
            ready: !!skyboxLibrary?.getRenderState?.().ready,
            loop: { frameCount: loopTiming.frameCount, exact: loopTiming.exact },
            videoExportRunning,
            published: publication?.schemaVersion === 1
        };
    }

    const api = {
        ready: Promise.resolve(skyboxLibrary?.initialLoad).then(() => undefined),
        describe: () => ({
            about: 'Tesseract viewer: a 4D polytope rendered in three.js, reflecting a six-face skybox. Changes show live and are saved in this browser.',
            guidance: [
                'Settings persist in this browser, exactly like changes made in the panel.',
                'Use screenshot() to see the scene; the canvas is not readable as text.',
                'Ask the user before loadSkybox() replaces their current environment.'
            ],
            settings: SETTINGS,
            methods: {
                'ready': 'promise: the first skybox load has finished',
                'getState()': 'current settings, active skybox and loop length',
                'setState(changes)': 'partial settings (see settings); sliders snap to their steps; returns getState()',
                'play() / pause()': 'start or stop the animation',
                'listExports()': 'completed Studio exports [{folder, name, createdAt, size, ...}]',
                'loadSkybox(folder)': '"default" or "exports/<name>"; rejects with the reason if it cannot load',
                'screenshot({maxSize})': 'PNG data URL of the 3D view (no control panel), longest side at most maxSize (default 1024)'
            }
        }),
        getState,
        setState,
        play: () => setState({ animationPaused: false }),
        pause: () => setState({ animationPaused: true }),
        async listExports() {
            const response = await fetch('/api/exports', { cache: 'no-store' });
            require(response.ok, 'The export library needs studio/server.py');
            return (await response.json()).exports;
        },
        async loadSkybox(folder) {
            unlocked();
            require(typeof folder === 'string', 'loadSkybox takes "default" or "exports/<name>"');
            const loaded = await skyboxLibrary.loadSelection(folder);
            require(loaded, skyboxLibrary.statusMessage?.() || 'The skybox could not be loaded');
            return getState();
        },
        screenshot({ maxSize = 1024 } = {}) {
            renderer.render(scene, camera);
            const source = renderer.domElement;
            const scale = Math.min(1, number('maxSize', maxSize) / Math.max(source.width, source.height));
            const output = document.createElement('canvas');
            output.width = Math.max(1, Math.round(source.width * scale));
            output.height = Math.max(1, Math.round(source.height * scale));
            output.getContext('2d').drawImage(source, 0, 0, output.width, output.height);
            return output.toDataURL('image/png');
        }
    };
    if (publication?.schemaVersion === 1) {
        // Published works are static: the export library needs studio/server.py.
        const describe = api.describe;
        delete api.listExports;
        delete api.loadSkybox;
        api.describe = () => {
            const description = describe();
            delete description.methods['listExports()'];
            delete description.methods['loadSkybox(folder)'];
            return description;
        };
    }
    window.viewer = Object.freeze(api);
    if (publication?.schemaVersion !== 1) announceAgentAPI('viewer');
}

// One visually hidden sentence so browser agents discover the API from the DOM or accessibility tree.
function announceAgentAPI(name) {
    const note = document.createElement('p');
    note.id = 'agent-note';
    note.textContent = `For AI agents: this page has a JavaScript API. Run await ${name}.ready; ${name}.describe() instead of clicking.`;
    Object.assign(note.style, { position: 'absolute', width: '1px', height: '1px', overflow: 'hidden', clipPath: 'inset(50%)', whiteSpace: 'nowrap', margin: '-1px' });
    document.body.prepend(note);
    console.info(note.textContent);
}

installViewerAPI();