flock.js

// Flock - Creative coding in 3D
// Dr Tracy Gardner - https://github.com/tracygardner
// Flip Computing Limited - flipcomputing.com

import * as acorn from 'acorn';
import * as walk from 'acorn-walk';
import HavokPhysics from '@babylonjs/havok';
import * as BABYLON from '@babylonjs/core';
import * as BABYLON_GUI from '@babylonjs/gui/2D/index.js';
import * as BABYLON_LOADER from '@babylonjs/loaders';
import { GradientMaterial } from '@babylonjs/materials';
import * as BABYLON_EXPORT from '@babylonjs/serializers';

// Point Babylon’s Draco loader at local folder for offline use
BABYLON.DracoCompression.Configuration = {
  decoder: {
    wasmUrl: './draco/draco_wasm_wrapper_gltf.js',
    wasmBinaryUrl: './draco/draco_decoder_gltf.wasm',
    fallbackUrl: './draco/draco_decoder_gltf.js',
  },
};
import earcut from 'earcut';
import '@fontsource/atkinson-hyperlegible-next';
import '@fontsource/atkinson-hyperlegible-next/500.css';
import '@fontsource/atkinson-hyperlegible-next/600.css';

import '@fontsource/asap';
import '@fontsource/asap/500.css';
import '@fontsource/asap/600.css';
import { characterNames, getModelDisplayName } from './config';

import { FlowGraphLog10Block } from '@babylonjs/core';
const optionalBabylonDeps = { earcut, FlowGraphLog10Block };
const globalEarcutTarget = typeof globalThis !== 'undefined' ? globalThis : undefined;
if (globalEarcutTarget) {
  Object.assign(globalEarcutTarget, optionalBabylonDeps);
}
import { flockCSG, setFlockReference as setFlockCSG } from './api/csg';
import { flockAnimate, setFlockReference as setFlockAnimate } from './api/animate';
import { flockSound, setFlockReference as setFlockSound } from './api/sound';
import { flockUI, setFlockReference as setFlockUI } from './api/ui';
import { flockMovement, setFlockReference as setFlockMovement } from './api/movement';
import { flockModels, setFlockReference as setFlockModels } from './api/models';
import { flockShapes, getManifold, setFlockReference as setFlockShapes } from './api/shapes';
import { flockTransform, setFlockReference as setFlockTransform } from './api/transform';
import { flockMaterial, setFlockReference as setFlockMaterial } from './api/material';
import { flockEffects, setFlockReference as setFlockEffects } from './api/effects';
import { flockPhysics, setFlockReference as setFlockPhysics } from './api/physics';
import { flockXR, setFlockReference as setFlockXR } from './api/xr';
import { flockControl, setFlockReference as setFlockControl } from './api/control';
import { flockScene, setFlockReference as setFlockScene } from './api/scene';
import { flockMesh, setFlockReference as setFlockMesh } from './api/mesh';
import { flockCamera, setFlockReference as setFlockCamera } from './api/camera';
import { flockEvents, setFlockReference as setFlockEvents } from './api/events';
import { flockMicrobit, setFlockReference as setFlockMicrobit } from './api/microbit';
import {
  getMicrobitManager,
  setFlockReference as setFlockMicrobitManager,
} from './microbit/manager.js';
import { flockMath, setFlockReference as setFlockMath } from './api/math';
import { flockSensing, setFlockReference as setFlockSensing } from './api/sensing';
import { translate } from './main/translation.js';
import { handleError, dismissBanner, showBanner, markReported } from './ui/notifications.js';
import { attachInteractIndicator, detachInteractIndicator } from './ui/interactIndicator.js';
import { InputManager } from './input/inputManager.js';
import { KeyboardSource } from './input/keyboardSource.js';
import { OnScreenSource } from './input/onScreenSource.js';
import { GamepadSource } from './input/gamepadSource.js';
import { CameraControls } from './input/cameraControls.js';
import { XRSource } from './input/xrSource.js';
import { getBoundKeys } from './input/bindings.js';

import {
  enableSceneDescription,
  announceSayText,
  announceObjectSay,
  getObjectLabel,
  recordObjectPromptText,
  recordObjectSayText,
  setTransientSayText,
  recordWorldInstructionText,
} from './accessibility/accessibility.js';
import { initUIAccessibility, clearUIControls } from './accessibility/uiA11y.js';

export const flock = {
  blockDebug: false,
  separateAnimations: true,
  memoryDebug: false,
  memoryMonitorInterval: 5000,
  materialsDebug: false,
  meshDebug: false,
  performanceOverlay: false,
  maxMeshes: 5000,
  maxClonesPerSource: 500,
  meshLimitEnabled: false,
  meshRecyclingEnabled: false,
  console: console,
  havokAbortHandled: false,
  triggerHandlingDebug: false,
  soundDebug: false,
  modelPath: './models/',
  soundPath: './sounds/',
  imagePath: './images/',
  texturePath: './textures/',
  // Keep optional Babylon dependencies referenced so bundlers include them.
  optionalBabylonDeps,
  engine: null,
  engineReady: false,
  eventDebug: false,
  modelReadyPromises: new Map(),
  pendingMeshCreations: 0,
  pendingTriggers: new Map(),
  pendingIntersections: new Map(),
  _nameRegistry: new Map(),
  _liveNameCache: new Map(),
  _animationFileCache: {},
  _ambiguousLiveNames: new Set(),
  getModelDisplayName,
  characterNames: characterNames,
  alert: alert,
  BABYLON: BABYLON,
  BABYLON_LOADER: BABYLON_LOADER,
  GradientMaterial: GradientMaterial,
  scene: null,
  highlighter: null,
  glowLayer: null,
  mainLight: null,
  shadowLight: null,
  shadowGenerator: null,
  shadowCasters: new Set(),
  xrFramebufferScale: 1.2,
  xrFixedFoveation: 0.5,
  hk: null,
  havokInstance: null,
  initialClearColor: null,
  ground: null,
  sky: null,
  GUI: null,
  EXPORT: null,
  controlsTexture: null,
  inputManager: null,
  canvas: null,
  abortController: null,
  _renderLoop: null,
  _renderLoopStopped: false,
  _contextLostAt: null,
  _escalationTimer: null,
  _webglVisibilityListenerAdded: false,
  _webglContextLostListenerAdded: false,
  _audioVisibilityListenerAdded: false,
  _audioSuspendedByVisibility: false,
  document: document,
  disposed: null,
  events: {},
  modelCache: {},
  globalSounds: [],
  originalModelTransformations: {},
  modelsBeingLoaded: {},
  geometryCache: {},
  materialCache: {},
  physicsShapeCache: {},
  flockNotReady: true,
  // Diagnostic flag like memoryDebug: logs raw micro:bit serial lines and
  // WebUSB status chatter to the console (debug level) while true.
  microbitDebug: false,
  lastFrameTime: 0,
  savedCamera: null,
  ...flockCSG,
  ...flockAnimate,
  ...flockSound,
  ...flockUI,
  ...flockMovement,
  ...flockModels,
  ...flockShapes,
  ...flockTransform,
  ...flockMaterial,
  ...flockEffects,
  ...flockPhysics,
  ...flockScene,
  ...flockMesh,
  ...flockCamera,
  ...flockXR,
  ...flockControl,
  ...flockEvents,
  ...flockMicrobit,
  ...flockSensing,
  ...flockMath,
  // onBlockError lets the UI show a translated message from key + values.
  onBlockError: null,
  _debugLogging: undefined,
  // Testing phase: warnings ON by default (?debug=false silences).
  // TODO: revert to opt-in (`=== 'true'`, default false) after testing.
  isDebugLoggingEnabled() {
    if (flock._debugLogging === undefined) {
      try {
        flock._debugLogging = new URLSearchParams(window.location.search).get('debug') !== 'false';
      } catch {
        flock._debugLogging = true;
      }
    }
    return flock._debugLogging;
  },
  reportBlockError({ key, values = {}, api, error } = {}) {
    // A caught value can come straight from user code, so classify and report
    // through safe primitives rather than its own getters.
    const safe = error == null ? undefined : flock.sanitizeError(error);
    if (safe?.name === 'AbortError') return;
    // A stack overflow is nearly always runaway user recursion; report it as
    // such. Message differs by engine (V8 "call stack", Firefox "recursion").
    if (
      (safe?.name === 'RangeError' || safe?.name === 'InternalError') &&
      /call stack|recursion/i.test(safe.message)
    ) {
      key = 'recursion_too_deep';
    }
    // One fault can fire in a burst — a stack-overflow cascade surfaces several
    // times, and a per-frame loop error repeats endlessly. Collapse identical
    // reports within a short window.
    const now = Date.now();
    const sig = `${key}\0${api ?? ''}\0${safe?.message ?? ''}`;
    if (sig === flock._lastErrorSig && now - flock._lastErrorAt < 1000) {
      return;
    }
    flock._lastErrorSig = sig;
    flock._lastErrorAt = now;
    if (flock.isDebugLoggingEnabled()) {
      console.warn(`[flock] ${api ?? 'block'}: ${key}`, values, safe ?? '');
    }
    try {
      flock.onBlockError?.({ key, values, api, error: safe });
    } catch {
      // a broken listener must not break the swallow path
    }
  },
  // User code can throw any value, including an object whose name/message/stack
  // getters throw or return non-strings. Read each once, defensively, into a
  // plain Error so host handlers touch only safe primitives. (A getter that
  // hangs rather than throws can't be defended against — that's a self-inflicted
  // hang, like any infinite loop in user code.)
  sanitizeError(error) {
    const read = (get) => {
      try {
        const v = get();
        return v == null ? '' : String(v);
      } catch {
        return '';
      }
    };
    // A thrown primitive (e.g. `throw "bad input"`) has no .message, so use the
    // value itself rather than losing the text.
    const isPrimitive = error == null || (typeof error !== 'object' && typeof error !== 'function');
    const safe = new Error(isPrimitive ? read(() => error) : read(() => error?.message));
    safe.name = isPrimitive ? 'Error' : read(() => error?.name) || 'Error';
    safe.stack = isPrimitive ? '' : read(() => error?.stack);
    return safe;
  },
  requireMesh(target, { api, name } = {}) {
    if (target instanceof flock.BABYLON.AbstractMesh) return true;
    flock.reportBlockError({
      key: target == null ? 'object_not_found' : 'target_not_a_mesh',
      api,
      values: { object: name },
    });
    return false;
  },
  // Enhanced error reporting with block context
  createEnhancedError(error, code) {
    const lines = code.split('\n');
    const errorContext = {
      message: error.message,
      stack: error.stack,
      codeSnippet: null,
      suggestion: null,
    };

    // Try to extract line number from error
    const lineMatch = error.stack?.match(/at .*:(\d+):\d+/);
    if (lineMatch) {
      const lineNum = parseInt(lineMatch[1]) - 1;
      if (lineNum >= 0 && lineNum < lines.length) {
        const start = Math.max(0, lineNum - 2);
        const end = Math.min(lines.length, lineNum + 3);
        errorContext.codeSnippet = lines
          .slice(start, end)
          .map((line, idx) => {
            const actualLine = start + idx;
            const marker = actualLine === lineNum ? '>>> ' : '    ';
            return `${marker}${actualLine + 1}: ${line}`;
          })
          .join('\n');
      }
    }

    // Add common error suggestions
    if (error.message.includes('is not defined')) {
      errorContext.suggestion =
        'Check if the variable or function name is spelled correctly and has been declared.';
    } else if (error.message.includes('Cannot read property')) {
      errorContext.suggestion = 'Check if the object exists before accessing its properties.';
    }

    return errorContext;
  },
  // Prune disposed entries and auto-recycle the oldest live instance
  // when the per-key cap is hit. Used by all mesh creation paths.
  // Only active when flock.meshRecyclingEnabled is true.
  _recycleOldestByKey(key) {
    if (!flock.meshRecyclingEnabled) return;
    if (!flock._modelInstances) flock._modelInstances = Object.create(null);
    const current = Array.isArray(flock._modelInstances[key]) ? flock._modelInstances[key] : [];
    flock._modelInstances[key] = current.filter((name) => {
      const m = flock.scene?.getMeshByName(name);
      return m && !m.isDisposed();
    });
    const max = flock.maxClonesPerSource ?? 500;
    if (flock._modelInstances[key].length >= max) {
      const oldestName = flock._modelInstances[key][0];
      const oldest = flock.scene?.getMeshByName(oldestName);
      if (oldest) flock.disposeMesh(oldest);
      flock._modelInstances[key] = flock._modelInstances[key].slice(1);
    }
  },
  _registerInstance(key, meshName) {
    if (!flock._modelInstances) flock._modelInstances = Object.create(null);
    const current = Array.isArray(flock._modelInstances[key]) ? flock._modelInstances[key] : [];
    flock._modelInstances[key] = current.concat(meshName);
  },
  maxMeshesReached() {
    if (!flock.meshLimitEnabled) return false;
    const scene = flock?.scene;
    if (!scene || typeof flock.maxMeshes !== 'number') return false;

    const meshCount = scene.meshes.length;
    const max = flock.maxMeshes;

    if (meshCount >= max) {
      flock.printText?.({
        text: translate('max_mesh_limit_reached').replace('{max}', max),
        duration: 30,
        color: '#ff0000',
      });

      return true;
    }

    return false;
  },
  _resetCameraInputState(camera = flock.scene?.activeCamera) {
    if (!camera) return;

    // ArcRotateCamera inertial offsets can keep rotating after input ends.
    if ('inertialAlphaOffset' in camera) camera.inertialAlphaOffset = 0;
    if ('inertialBetaOffset' in camera) camera.inertialBetaOffset = 0;
    if ('inertialRadiusOffset' in camera) camera.inertialRadiusOffset = 0;
    if ('inertialPanningX' in camera) camera.inertialPanningX = 0;
    if ('inertialPanningY' in camera) camera.inertialPanningY = 0;

    // Free/Universal camera deltas can persist when pointer state desyncs.
    if (camera.cameraDirection?.set) {
      camera.cameraDirection.set(0, 0, 0);
    }
    if (camera.cameraRotation?.set) {
      camera.cameraRotation.set(0, 0);
    } else if (camera.cameraRotation) {
      camera.cameraRotation.x = 0;
      camera.cameraRotation.y = 0;
    }
  },
  _hardResetCameraControls(
    camera = flock.scene?.activeCamera,
    { reattachDelayMs = 0, noPreventDefault = true } = {}
  ) {
    if (!camera || !flock.canvas) return;
    if (typeof camera.detachControl !== 'function') return;
    if (typeof camera.attachControl !== 'function') return;

    camera.detachControl(flock.canvas);
    flock._resetCameraInputState(camera);

    if (flock._cameraControlReattachTimer) {
      clearTimeout(flock._cameraControlReattachTimer);
      flock._cameraControlReattachTimer = null;
    }

    const reattach = () => {
      if (!flock.scene || flock.scene.activeCamera !== camera) return;
      if (flock._canvasControlsEnabled === false) return;
      flock._resetCameraInputState(camera);
      camera.attachControl(flock.canvas, noPreventDefault);
      flock._cameraControlReattachTimer = null;
    };

    if (reattachDelayMs > 0) {
      flock._cameraControlReattachTimer = setTimeout(reattach, reattachDelayMs);
      return;
    }

    reattach();
  },
  getTotalSceneVertices() {
    return flock.scene.meshes.reduce((total, mesh) => {
      return total + mesh.getTotalVertices();
    }, 0);
  },
  checkMemoryUsage() {
    if (!performance.memory) {
      return; // Not available in all browsers
    }

    const used = performance.memory.usedJSHeapSize / 1024 / 1024;
    const total = performance.memory.totalJSHeapSize / 1024 / 1024;
    const limit = performance.memory.jsHeapSizeLimit / 1024 / 1024;

    console.log(
      `Memory: ${used.toFixed(1)}MB used / ${total.toFixed(1)}MB allocated / ${limit.toFixed(1)}MB limit`
    );

    // Warn if approaching limits
    const usagePercent = (used / limit) * 100;
    if (usagePercent > 80) {
      console.warn(`High memory usage: ${usagePercent.toFixed(1)}% of limit`);
      // Show user warning in UI
      this.printText({
        text: translate('high_memory_usage_warning').replace('{percent}', usagePercent.toFixed(1)),
        duration: 3,
        color: '#ff9900',
      });
    }

    // Count Babylon.js objects for more specific monitoring
    if (flock.scene) {
      const counts = {
        meshes: flock.scene.meshes.length,
        geometries: Object.keys(flock.geometryCache).length,
        vertices: flock.getTotalSceneVertices(),
        materials: flock.scene.materials.length,
        cachedMaterials: Object.keys(flock.materialCache).length,
        textures: flock.scene.textures.length,
        animationGroups: flock.scene.animationGroups.length,
      };
      console.log('Scene objects:', counts);
    }
  },
  startMemoryMonitoring() {
    console.log('Starting memory monitoring...');
    // Clear any existing monitoring
    if (flock.memoryMonitorInterval) {
      clearInterval(flock.memoryMonitorInterval);
    }

    // Get the abort signal
    const signal = flock.abortController?.signal;

    if (signal?.aborted) {
      return; // Don't start if already aborted
    }

    // Monitor every 5 seconds
    flock.memoryMonitorInterval = setInterval(() => {
      // Check if aborted before each check
      if (signal?.aborted) {
        clearInterval(flock.memoryMonitorInterval);
        flock.memoryMonitorInterval = null;
        return;
      }

      flock.checkMemoryUsage();
    }, 5000);

    // Clean up when aborted
    signal?.addEventListener('abort', () => {
      if (flock.memoryMonitorInterval) {
        clearInterval(flock.memoryMonitorInterval);
        flock.memoryMonitorInterval = null;
      }
    });
  },
  // Havok's wasm needs WebAssembly SIMD, which iOS Safari only has from 16.4.
  // Older engines can't parse the v128 return type in this module's type
  // section, so validate() is false there and true everywhere Havok can run.
  isWasmSimdSupported() {
    if (flock._wasmSimdSupported === undefined) {
      try {
        flock._wasmSimdSupported =
          typeof WebAssembly !== 'undefined' &&
          WebAssembly.validate(
            new Uint8Array([
              0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 123, 3, 2, 1, 0, 10, 10, 1, 8, 0, 65,
              0, 253, 15, 253, 98, 11,
            ])
          );
      } catch {
        // A throwing validate() means the engine can't handle the module at all.
        flock._wasmSimdSupported = false;
      }
    }
    return flock._wasmSimdSupported;
  },
  isPhysicsMemoryAbort(error) {
    const message = `${error?.message ?? error}`.toLowerCase();
    const isWasmRuntimeError =
      typeof WebAssembly !== 'undefined' && error instanceof WebAssembly.RuntimeError;
    // Emscripten wraps a wasm parse failure as "Aborted(CompileError: …)".
    // That's a missing capability, not memory pressure.
    if (message.includes('compileerror') || !flock.isWasmSimdSupported()) {
      return false;
    }
    return message.includes('out of memory') || (isWasmRuntimeError && message.includes('abort'));
  },
  // Loader is injectable so tests can assert the wasm is never fetched when
  // the device can't run it.
  async ensurePhysicsInstance(loadHavok = HavokPhysics) {
    if (!flock.isWasmSimdSupported()) {
      const error = new Error('WebAssembly SIMD is unavailable, so Havok physics cannot start.');
      handleError(error, { source: 'physics-unsupported' });
      throw markReported(error);
    }

    // Callers that arrive together share one in-flight load, so a second
    // caller can't start a duplicate wasm instance and leak the loser.
    if (!flock.havokInstance) {
      flock._havokInstancePromise ??= loadHavok();
      try {
        flock.havokInstance = await flock._havokInstancePromise;
      } finally {
        flock._havokInstancePromise = undefined;
      }
    }

    return flock.havokInstance;
  },
  handlePhysicsOutOfMemory(error) {
    if (flock.havokAbortHandled) {
      return;
    }

    flock.havokAbortHandled = true;

    try {
      flock._renderLoopStopped = true;
      if (flock._renderLoop) {
        flock.engine?.stopRenderLoop(flock._renderLoop);
      } else {
        flock.engine?.stopRenderLoop();
      }
      flock.abortController?.abort();
    } catch (e) {
      console.log('Failed to stop render loop during physics OOM handling:', e);
    }

    try {
      flock.hk?.dispose?.();
    } catch (e) {
      console.log('Failed to dispose Havok instance during physics OOM handling:', e);
    }

    handleError(error, { source: 'physics-oom', fatal: true });
  },
  validateCode(code) {
    if (typeof code !== 'string') {
      throw new Error('Code must be a string');
    }

    // Length check (reasonable)
    if (code.length > 100000) {
      throw new Error('Code too long (max 100KB)');
    }

    // Basic syntax check
    try {
      new Function(code); // Just check if it parses
    } catch (e) {
      throw new Error(`Syntax error: ${e.message}`);
    }

    // Optional: Warn about patterns (don't block)
    const warnings = [];
    if (/eval\s*\(/.test(code)) {
      warnings.push("Warning: eval() detected - this won't work in the sandbox");
    }

    if (warnings.length > 0) {
      console.warn(warnings.join('\n'));
    }

    return true;
  },
  validateUserCodeAST(src) {
    // 1) Very broad identifier blocklist (names anywhere in user code)
    const REJECT_IDENTIFIERS = new Set([
      // dynamic code / reflection
      'eval',
      'Function',
      'AsyncFunction',
      'GeneratorFunction',
      'Proxy',
      'Reflect',
      // frames & globals
      'window',
      'document',
      'globalThis',
      'self',
      'parent',
      'top',
      'frames',
      'frameElement',
      // navigation & env
      'location',
      'history',
      'navigator',
      'opener',
      // network / ipc
      'fetch',
      'XMLHttpRequest',
      'WebSocket',
      'EventSource',
      'postMessage',
      'MessageChannel',
      'MessagePort',
      'BroadcastChannel',
      // workers & worklets
      'Worker',
      'SharedWorker',
      'ServiceWorker',
      'Worklet',
      'importScripts',
      // storage / persistence
      'localStorage',
      'sessionStorage',
      'indexedDB',
      'caches',
      'cookieStore',
      // file/blob/crypto
      'Blob',
      'File',
      'FileReader',
      'crypto',
      // urls & media constructors
      'URL',
      'URLSearchParams',
      'Image',
      'Audio',
      'RTCPeerConnection',
      'MediaDevices',
      'Notification',
      // popups / UI
      'open',
      'alert',
      'confirm',
      'prompt',
      'print',
      'showModalDialog',
      // timers (we’ll also do special checks)
      'setTimeout',
      'setInterval',
      'setImmediate',
      'queueMicrotask',
      // module-ish
      'require',
    ]);

    // 2) Callees we never allow (even if shadowed)
    const REJECT_CALLEES = new Set([
      'eval',
      'Function',
      'AsyncFunction',
      'GeneratorFunction',
      'setTimeout',
      'setInterval',
      'setImmediate',
      'queueMicrotask',
      'open',
      'alert',
      'confirm',
      'prompt',
      'print',
    ]);

    // 3) Member/property names that are escape hatches
    const REJECT_PROPERTIES = new Set([
      'constructor',
      '__proto__',
      'prototype',
      'caller',
      'callee',
      'arguments',
    ]);
    const ast = acorn.parse(src, {
      ecmaVersion: 'latest',
      sourceType: 'script',
      allowAwaitOutsideFunction: true,
      locations: false,
    });

    walk.simple(ast, {
      // Syntax we never allow
      WithStatement() {
        throw new Error('with() not allowed');
      },
      DebuggerStatement() {
        throw new Error('debugger not allowed');
      },
      ImportDeclaration() {
        throw new Error('import declarations not allowed');
      },
      ExportNamedDeclaration() {
        throw new Error('export not allowed');
      },
      ExportDefaultDeclaration() {
        throw new Error('export not allowed');
      },
      ImportExpression() {
        throw new Error('dynamic import() not allowed');
      },
      MetaProperty(n) {
        if (n.meta?.name === 'import') throw new Error('import.meta not allowed');
      },

      // Any usage of these identifiers anywhere
      Identifier(n) {
        if (REJECT_IDENTIFIERS.has(n.name)) {
          throw new Error(`Identifier '${n.name}' is not allowed`);
        }
      },

      // Ban .constructor / .__proto__ / .prototype / .caller / .callee / .arguments
      MemberExpression(n) {
        // foo.bar
        if (
          !n.computed &&
          n.property?.type === 'Identifier' &&
          REJECT_PROPERTIES.has(n.property.name)
        ) {
          throw new Error(`Access to '.${n.property.name}' is not allowed`);
        }
        // foo["constructor"]
        if (
          n.computed &&
          n.property?.type === 'Literal' &&
          typeof n.property.value === 'string' &&
          REJECT_PROPERTIES.has(n.property.value)
        ) {
          throw new Error(`Access to '["${n.property.value}"]' is not allowed`);
        }
      },

      // Disallow dangerous callees; forbid string-eval timers
      CallExpression(n) {
        const callee = n.callee;
        const name =
          callee?.type === 'Identifier'
            ? callee.name
            : callee?.type === 'MemberExpression' &&
                !callee.computed &&
                callee.property?.type === 'Identifier'
              ? callee.property.name
              : null;

        if (name && REJECT_CALLEES.has(name)) {
          // Special case: timers with string as first arg (string-eval)
          if (
            (name === 'setTimeout' || name === 'setInterval') &&
            n.arguments[0]?.type === 'Literal' &&
            typeof n.arguments[0].value === 'string'
          ) {
            throw new Error('String-eval timers are not allowed');
          }
          // Block all the listed callees regardless
          throw new Error(`Call to '${name}()' is not allowed`);
        }
      },

      // new Function(), new Worker(), etc.
      NewExpression(n) {
        const callee = n.callee;
        const name = callee?.type === 'Identifier' ? callee.name : null;
        if (name && (REJECT_CALLEES.has(name) || REJECT_IDENTIFIERS.has(name))) {
          throw new Error(`'new ${name}()' is not allowed`);
        }
      },
    });
  },
  async runCode(code, options = {}) {
    const { focusCanvas = true } = options;

    try {
      flock.validateUserCodeAST(code);
      await flock.disposeOldScene();

      // --- remove any existing iframe ---
      const oldIframe = document.getElementById('flock-iframe');
      if (oldIframe) {
        try {
          await oldIframe.contentWindow?.flock?.disposeOldScene?.();
        } catch {
          /* ignore cleanup errors */
        }
        try {
          oldIframe.onload = oldIframe.onerror = null;
        } catch {
          /* ignore cleanup errors */
        }
        try {
          oldIframe.src = 'about:blank';
        } catch {
          /* ignore cleanup errors */
        }
        try {
          oldIframe.remove();
        } catch {
          /* ignore cleanup errors */
        }
      }

      // --- create fresh same-origin iframe ---
      const { win, doc } = await flock.replaceSandboxIframe({
        id: 'flock-iframe',
        sameOrigin: true,
      });

      // --- load SES text in parent and inject inline into iframe (CSP allows inline) ---
      const sesResp = await fetch('vendor/ses/lockdown.umd.min.js');
      if (!sesResp.ok) throw new Error(`Failed to fetch SES: ${sesResp.status}`);
      const sesText = await sesResp.text();
      const sesScript = doc.createElement('script');
      sesScript.type = 'text/javascript';
      sesScript.text = sesText;
      doc.head.appendChild(sesScript);

      // Re-wraps a host-realm fn into this realm; lockdown only tames this
      // realm, so a raw host fn would leak the untamed Function via
      // `.constructor` (sandbox escape). Must run before lockdown.
      const wrapScript = doc.createElement('script');
      wrapScript.type = 'text/javascript';
      wrapScript.text = 'window.__flockWrapHostFn = (fn) => (...args) => fn(...args);';
      doc.head.appendChild(wrapScript);

      // Lock down the iframe realm. Disable SES's own unhandled-rejection
      // reporter (the SES_UNHANDLED_REJECTION console dump); the win backstop
      // below handles those and routes them to the friendly warn path.
      win.lockdown({ unhandledRejectionTrapping: 'none' });

      // initialise scene
      await this.initializeNewScene?.();
      if (this.memoryDebug) this.startMemoryMonitoring?.();

      // abort plumbing
      this.__runToken = (this.__runToken || 0) + 1;
      const runToken = this.__runToken;
      this.abortController?.abort?.();
      this.abortController = new AbortController();
      const signal = this.abortController.signal;
      const guard =
        (fn) =>
        (...args) => {
          if (signal.aborted || runToken !== this.__runToken) return;
          return fn(...args);
        };

      const whitelist = this.createWhitelist({
        win,
        signal,
        guard,
      });

      // Create an endowments object in the iframe's realm
      const endowments = new win.Object();

      for (const [key, value] of Object.entries(whitelist)) {
        const t = typeof value;
        if (t === 'function') {
          // Wrap into the iframe realm: a host-realm fn leaks the untamed host
          // Function via `.constructor` (sandbox escape). bind(null) drops host `this`.
          endowments[key] = win.__flockWrapHostFn(value.bind(null));
        } else if (value == null || (t !== 'object' && t !== 'symbol')) {
          // primitives only
          endowments[key] = value;
        } else {
          // skip complex objects (meshes, DOM nodes, etc). Expose via functions instead.
        }
      }

      // win.Object, not a host `{}`: a host literal leaks host Function via
      // obj.constructor.constructor.
      endowments.performance = new win.Object();
      endowments.performance.now = win.performance.now.bind(win.performance);

      // Host window, not the display:none iframe: Firefox never fires rAF for
      // an unpainted document, so loop yields would hang. The host window
      // outlives the iframe, so guard the callback (which iframe teardown used
      // to cancel implicitly) or a stale run's frames fire into the next run.
      // Wrapped so the endowment carries no host `.constructor`.
      const hostRequestAnimationFrame = window.requestAnimationFrame.bind(window);
      endowments.requestAnimationFrame = win.__flockWrapHostFn((callback) =>
        hostRequestAnimationFrame(guard(callback))
      );

      endowments.Date = new win.Object();
      endowments.Date.now = win.Date.now.bind(win.Date);

      // Undefine unwanted globals
      // --- shadow unsafe / unneeded globals ---
      const toUndefine = [
        // Host / DOM / cross-frame
        'flock',
        'window',
        'self',
        'globalThis',
        'parent',
        'top',
        'frames',
        'opener',
        'frameElement',
        'document',

        // SES meta
        'lockdown',
        'harden',
        'Compartment',

        // Legacy / GC / crypto
        'escape',
        'unescape',
        'FinalizationRegistry',
        'WeakRef',
        'crypto',

        // Dynamic code creation
        'eval',
        'Function',
        'AsyncFunction',
        'GeneratorFunction',
        'AsyncGeneratorFunction',

        // Threads / native
        'SharedArrayBuffer',
        'Atomics',
        'WebAssembly',

        // Workers & messaging
        'Worker',
        'SharedWorker',
        'MessageChannel',
        'BroadcastChannel',
        'queueMicrotask',

        // Network / storage / env
        'fetch',
        'XMLHttpRequest',
        'navigator',
        'location',
        'localStorage',
        'sessionStorage',
        'indexedDB',
        'caches',

        // UX
        'Notification',

        //Events
        'addEventListener',
        'removeEventListener',
        'dispatchEvent',
      ];

      for (const k of toUndefine) endowments[k] = undefined;

      for (const key of toUndefine) {
        endowments[key] = undefined;
      }

      Object.freeze(endowments);

      const wrapped =
        '(async function () {\n"use strict";\n' +
        code +
        '\n}).call(undefined)\n//# sourceURL=user-code.js';

      // Compartment errors surface on `win` (the iframe realm), not the parent;
      // preventDefault stops SES double-reporting.
      win.addEventListener('unhandledrejection', (ev) => {
        ev.preventDefault?.();
        const error = flock.sanitizeError(ev.reason);
        if (error.name === 'AbortError') return;
        flock.reportBlockError({ key: 'unhandled_rejection', api: 'user-code', error });
      });
      win.addEventListener('error', (ev) => {
        ev.preventDefault?.();
        const error = flock.sanitizeError(ev.error ?? ev.message);
        if (error.name === 'AbortError') return;
        flock.reportBlockError({ key: 'uncaught_error', api: 'user-code', error });
      });

      // Evaluate in SES Compartment
      const c = new win.Compartment(endowments);

      const MAX_MS = 5000;
      const hostSetTimeout = window.setTimeout.bind(window);
      await Promise.race([
        c.evaluate(wrapped),
        new Promise((_, rej) =>
          hostSetTimeout(() => rej(new Error('User code timed out')), MAX_MS)
        ),
      ]);

      if (focusCanvas === true) {
        // focus canvas if present
        (document.getElementById('renderCanvas') || doc.getElementById('renderCanvas'))?.focus();
      }
    } catch (error) {
      // Read the (possibly user-thrown) error through safe primitives here;
      // re-throw the original so downstream identity checks (e.g. isBenignAbort's
      // WebAssembly.RuntimeError test for physics OOM) still work.
      const safe = this.sanitizeError?.(error) ?? error;
      const enhancedError = this.createEnhancedError?.(safe, code) ?? safe;
      console.error('Enhanced error details:', enhancedError);

      try {
        // Abort first: start-block timers otherwise outlive the teardown.
        this.abortController?.abort?.();
        // stopAllSounds honours the context ownership rules; close() does not.
        this.stopAllSounds?.();
        this.engine?.stopRenderLoop?.();
        this.removeEventListeners?.();
      } catch (cleanupError) {
        console.error('Error during cleanup:', cleanupError);
      }

      throw error;
    }
  },
  createWhitelist({ guard } = {}) {
    const api = {
      // Flock API methods — bound to host `this`
      playAnimation: this.playAnimation?.bind(this),
      playSound: guard(this.playSound?.bind(this)),
      stopAllSounds: this.stopAllSounds?.bind(this),
      playNotes: guard(this.playNotes?.bind(this)),
      playMusic: guard(this.playMusic?.bind(this)),
      setBPM: guard(this.setBPM?.bind(this)),
      setMusicSpeed: guard(this.setMusicSpeed?.bind(this)),
      createInstrument: this.createInstrument?.bind(this),
      speak: guard(this.speak?.bind(this)),
      switchAnimation: this.switchAnimation?.bind(this),
      highlight: this.highlight?.bind(this),
      glow: this.glow?.bind(this),
      createCharacter: this.createCharacter?.bind(this),
      createObject: this.createObject?.bind(this),
      createParticleEffect: this.createParticleEffect?.bind(this),
      create3DText: this.create3DText?.bind(this),
      createModel: this.createModel?.bind(this),
      createBox: this.createBox?.bind(this),
      createSphere: this.createSphere?.bind(this),
      createCylinder: this.createCylinder?.bind(this),
      createCapsule: this.createCapsule?.bind(this),
      createPlane: this.createPlane?.bind(this),
      cloneMesh: this.cloneMesh?.bind(this),
      parentChild: this.parentChild?.bind(this),
      setParent: this.setParent?.bind(this),
      mergeMeshes: this.mergeMeshes?.bind(this),
      subtractMeshes: this.subtractMeshes?.bind(this),
      intersectMeshes: this.intersectMeshes?.bind(this),
      createHull: this.createHull?.bind(this),
      hold: this.hold?.bind(this),
      attach: this.attach?.bind(this),
      drop: this.drop?.bind(this),
      makeFollow: this.makeFollow?.bind(this),
      stopFollow: this.stopFollow?.bind(this),
      removeParent: this.removeParent?.bind(this),
      createMap: this.createMap?.bind(this),
      setSky: this.setSky?.bind(this),
      lightIntensity: this.lightIntensity?.bind(this),
      lightColor: this.lightColor?.bind(this),
      enableShadows: this.enableShadows?.bind(this),
      setShadow: this.setShadow?.bind(this),
      buttonControls: this.buttonControls?.bind(this),
      onScreenControls: this.onScreenControls?.bind(this),
      getCamera: this.getCamera?.bind(this),
      getMainLight: this.getMainLight?.bind(this),
      cameraControl: this.cameraControl?.bind(this),
      setCameraBackground: this.setCameraBackground?.bind(this),
      setXRMode: this.setXRMode?.bind(this),
      applyForce: this.applyForce?.bind(this),
      setSpeed: this.setSpeed?.bind(this),
      setBounciness: this.setBounciness?.bind(this),
      moveByVector: this.moveByVector?.bind(this),
      glideTo: this.glideTo?.bind(this),
      glideToObject: this.glideToObject?.bind(this),
      glideDirection: this.glideDirection?.bind(this),
      rotateToObject: this.rotateToObject?.bind(this),
      wait: this.wait?.bind(this),
      createAnimation: this.createAnimation?.bind(this),
      animateFrom: this.animateFrom?.bind(this),
      playAnimationGroup: this.playAnimationGroup?.bind(this),
      pauseAnimationGroup: this.pauseAnimationGroup?.bind(this),
      stopAnimationGroup: this.stopAnimationGroup?.bind(this),
      startParticleSystem: this.startParticleSystem?.bind(this),
      stopParticleSystem: this.stopParticleSystem?.bind(this),
      resetParticleSystem: this.resetParticleSystem?.bind(this),
      animateKeyFrames: this.animateKeyFrames?.bind(this),
      setAnchor: this.setAnchor?.bind(this),
      rotate: this.rotate?.bind(this),
      lookAt: this.lookAt?.bind(this),
      moveTo: this.moveTo?.bind(this),
      rotateTo: this.rotateTo?.bind(this),
      rotateAnim: this.rotateAnim?.bind(this),
      animateProperty: this.animateProperty?.bind(this),
      positionAt: this.positionAt?.bind(this),
      positionAtSingleCoordinate: this.positionAtSingleCoordinate?.bind(this),
      distanceTo: this.distanceTo?.bind(this),
      waitUntil: this.waitUntil?.bind(this),
      show: this.show?.bind(this),
      hide: this.hide?.bind(this),
      clearEffects: this.clearEffects?.bind(this),
      stopAnimations: this.stopAnimations?.bind(this),
      tint: this.tint?.bind(this),
      setAlpha: this.setAlpha?.bind(this),
      dispose: this.dispose?.bind(this),
      setFog: this.setFog?.bind(this),
      keyPressed: this.keyPressed?.bind(this),
      setActionKey: this.setActionKey?.bind(this),
      actionPressed: this.actionPressed?.bind(this),
      isTouchingSurface: this.isTouchingSurface?.bind(this),
      meshExists: this.meshExists?.bind(this),
      seededRandom: this.seededRandom?.bind(this),
      randomColour: this.randomColour?.bind(this),
      scale: this.scale?.bind(this),
      resize: this.resize?.bind(this),
      changeColor: this.changeColor?.bind(this),
      changeMaterial: this.changeMaterial?.bind(this),
      setMaterial: this.setMaterial?.bind(this),
      moveForward: this.moveForward?.bind(this),
      moveSideways: this.moveSideways?.bind(this),
      strafe: this.strafe?.bind(this),
      jump: this.jump?.bind(this),
      attachCamera: this.attachCamera?.bind(this),
      canvasControls: this.canvasControls?.bind(this),
      interactIndicator: this.interactIndicator?.bind(this),
      setPhysics: this.setPhysics?.bind(this),
      setPhysicsShape: this.setPhysicsShape?.bind(this),
      showPhysics: this.showPhysics?.bind(this),
      checkMeshesTouching: this.checkMeshesTouching?.bind(this),
      say: this.say?.bind(this),
      describeMesh: this.describeMesh?.bind(this),
      onTrigger: this.onTrigger?.bind(this),
      onEvent: this.onEvent?.bind(this),
      broadcastEvent: this.broadcastEvent?.bind(this),
      addMicrobit: this.addMicrobit?.bind(this),
      onMicrobitEvent: this.onMicrobitEvent?.bind(this),
      microbitShowImage: this.microbitShowImage?.bind(this),
      microbitScrollText: this.microbitScrollText?.bind(this),
      start: this.start?.bind(this),
      forever: this.forever?.bind(this),
      whenActionEvent: this.whenActionEvent?.bind(this),
      whenKeyEvent: this.whenKeyEvent?.bind(this),
      randomInteger: this.randomInteger?.bind(this),
      printText: this.printText?.bind(this),
      enableSubtitles: this.enableSubtitles?.bind(this),
      showSubtitle: this.showSubtitle?.bind(this),
      UIText: this.UIText?.bind(this),
      UIButton: this.UIButton?.bind(this),
      UIInput: this.UIInput?.bind(this),
      UISlider: this.UISlider?.bind(this),
      onIntersect: this.onIntersect?.bind(this),
      getProperty: this.getProperty?.bind(this),
      getTime: this.getTime?.bind(this),
      exportMesh: this.exportMesh?.bind(this),
      createVector3: this.createVector3?.bind(this),
    };

    // Guard side-effecting APIs so stale runs no-op
    const SIDE_EFFECT_APIS = [
      'printText',
      'enableSubtitles',
      'showSubtitle',
      'UIText',
      'UIButton',
      'UIInput',
      'UISlider',
      'say',
      'highlight',
      'glow',
      'createParticleEffect',
      'startParticleSystem',
      'stopParticleSystem',
      'resetParticleSystem',
      'playSound',
      'stopAllSounds',
      'speak',
      'broadcastEvent',
      'onEvent',
      'addMicrobit',
      'onMicrobitEvent',
      'microbitShowImage',
      'microbitScrollText',
      'onTrigger',
      'start',
      'forever',
      'canvasControls',
      'interactIndicator',
      'buttonControls',
      'onScreenControls',
      'setActionKey',
      'cameraControl',
      'attachCamera',
      'setSky',
      'setFog',
      'setCameraBackground',
      'lightIntensity',
      'lightColor',
      'enableShadows',
      'setShadow',
      'create3DText',
      'createModel',
      'createBox',
      'createSphere',
      'createCylinder',
      'createCapsule',
      'createPlane',
      'mergeMeshes',
      'subtractMeshes',
      'intersectMeshes',
      'createHull',
      'describeMesh',
      'dispose',
      'clearEffects',
      'stopAnimations',
    ];
    for (const name of SIDE_EFFECT_APIS) {
      if (typeof api[name] === 'function') api[name] = guard(api[name]);
    }

    // Avoid hard errors if freezing fails in some environments
    try {
      return Object.freeze(api);
    } catch {
      return api;
    }
  },
  async replaceSandboxIframe({ id = 'flock-iframe', sameOrigin = true, srcdocHtml } = {}) {
    const old = document.getElementById(id);

    // --- 1) Hard teardown of the old iframe (if any) ---
    if (old) {
      try {
        // Detach handlers first
        old.onload = null;
        old.onerror = null;

        // Best-effort stop inside the old realm
        const w = old.contentWindow;
        try {
          w?.cancelAnimationFrame?.(w.__raf);
        } catch {
          /* ignore teardown errors */
        }
        try {
          w?.stop?.();
        } catch {
          /* ignore teardown errors */
          // stops loading
        }
        try {
          w?.close?.();
        } catch {
          /* ignore teardown errors */
          // some browsers free resources
        }

        // Navigate to a harmless page to break references, then remove
        try {
          old.src = 'about:blank';
        } catch {
          /* ignore teardown errors */
        }
      } finally {
        // Remove from DOM to release the realm
        old.remove?.();
      }
    }

    // --- 2) Create a brand-new iframe (fresh realm) ---
    const iframe = document.createElement('iframe');
    iframe.id = id;
    iframe.style.display = 'none';

    // Keep same-origin only if you need to touch iframe DOM/Canvas/WebGL from parent
    iframe.sandbox = `allow-scripts${sameOrigin ? ' allow-same-origin' : ''}`;

    // Prefer srcdoc so CSP is present before any script runs
    const csp = `default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline' 'unsafe-eval'`;
    const html =
      srcdocHtml ??
      `<!doctype html>
        <meta http-equiv="Content-Security-Policy" content="${csp}">
        <canvas id="renderCanvas"></canvas>`;

    // Attach to DOM before setting src/srcdoc to ensure load events fire consistently
    document.body.appendChild(iframe);

    // Load and await readiness
    await new Promise((resolve, reject) => {
      iframe.onload = () => {
        iframe.onload = iframe.onerror = null;
        resolve();
      };
      iframe.onerror = () => {
        iframe.onload = iframe.onerror = null;
        reject(new Error('iframe failed to load'));
      };
      // Use srcdoc when possible; fallback to about:blank + injected head if needed
      try {
        iframe.srcdoc = html;
      } catch {
        iframe.src = 'about:blank';
      }
    });

    // If we fell back to about:blank, inject CSP meta now (runs before user code anyway)
    if (!('srcdoc' in document.createElement('iframe')) || !iframe.srcdoc) {
      const doc = iframe.contentDocument || iframe.contentWindow?.document;
      if (!doc.head) doc.documentElement.appendChild(doc.createElement('head'));
      const meta = doc.createElement('meta');
      meta.httpEquiv = 'Content-Security-Policy';
      meta.content = csp;
      doc.head.appendChild(meta);
    }

    const win = iframe.contentWindow;
    const doc = iframe.contentDocument || win?.document;
    if (!win || !doc) throw new Error('New iframe is unavailable');

    return { iframe, win, doc };
  },
  async initialize() {
    flock.BABYLON = BABYLON;
    flock.GUI = BABYLON_GUI;
    flock.EXPORT = BABYLON_EXPORT;
    flock.document = document;
    flock.canvas = flock.document.getElementById('renderCanvas');
    // Make canvas focusable for keyboard events
    flock.canvas.tabIndex = -1;
    initUIAccessibility(flock.canvas);
    //flock.canvas.setAttribute("aria-label", "Flock 3D world canvas");
    flock.scene = null;
    flock.ground = null;
    flock.sky = null;
    flock.engineReady = false;
    flock.inputManager = new InputManager();
    flock._onScreenSource = new OnScreenSource(flock.inputManager, { target: flock.canvas });

    // micro:bit events also pulse the key pipeline as a momentary edge, so
    // "any"-device micro:bit blocks (and legacy projects, which generate
    // whenKeyEvent) respond to boards connected over WebUSB.
    if (!flock._microbitKeySinkAttached) {
      flock._microbitKeySinkAttached = true;
      setFlockMicrobitManager(flock); // lets the manager read flock.microbitDebug
      const microbitManager = getMicrobitManager();
      microbitManager.onAnyEvent((char) => {
        flock.inputManager?._setKey(char, true);
        flock.inputManager?._setKey(char, false);
      });
      // Silently reconnect known boards (navigator.usb.getDevices) and watch
      // for replugs. No-op where WebUSB is unavailable.
      microbitManager.init();
    }
    flock.displayScale = (window.devicePixelRatio || 1) * 0.75;
    flock.BABYLON.Database.IDBStorageEnabled = true;
    flock.BABYLON.Engine.CollisionsEpsilon = 0.00005;
    await flock.document.fonts.ready; // Wait for all fonts to be loaded
    flock.abortController = new AbortController();

    try {
      const manifoldWasm = await getManifold();
      await flock.BABYLON.InitializeCSG2Async({
        manifoldInstance: manifoldWasm.Manifold,
        manifoldMeshInstance: manifoldWasm.Mesh,
      });
    } catch (error) {
      // CSG2 powers only boolean mesh blocks; the rest of the app still works.
      console.warn('CSG2 unavailable; mesh boolean blocks are disabled.', error);
    }

    flock.canvas.addEventListener(
      'touchend',
      (event) => {
        if (event.touches.length === 0) {
          // Canvas is touchable before the first run and after disposal, when
          // there is no scene yet.
          const camera = flock.scene?.activeCamera;
          const input = camera?.inputs?.attached?.pointers;
          if (
            input &&
            (input._pointA !== null || input._pointB !== null || input._isMultiTouch === true)
          ) {
            flock._hardResetCameraControls(camera, {
              reattachDelayMs: 100,
              noPreventDefault: true,
            });
          }
        }
      },
      { passive: false }
    );

    // Block synthetic on-screen key events from reaching Babylon camera plugins
    // when an ArcRotateCamera is active — physical arrow keys still work for
    // keyboard accessibility; only __flockSynthetic events are stopped.
    const _blockSyntheticForArcRotate = (e) => {
      if (
        e.__flockSynthetic &&
        flock.scene?.activeCamera instanceof flock.BABYLON.ArcRotateCamera
      ) {
        e.stopImmediatePropagation();
      }
    };
    flock.canvas.addEventListener('keydown', _blockSyntheticForArcRotate, true);
    flock.canvas.addEventListener('keyup', _blockSyntheticForArcRotate, true);

    flock._keyboardSource = new KeyboardSource(flock.inputManager, {
      target: flock.canvas,
      onBlur: () => flock._hardResetCameraControls(flock.scene?.activeCamera),
    });
    flock._keyboardSource.start();

    // Hardening for rare pointer/input desync where camera keeps moving
    // after input ends or browser focus changes.
    window.addEventListener('blur', () => {
      flock._gamepadSource?.releaseAllKeys();
      // Babylon.js bug: camera drifts after window blur; force-reset to stop it.
      flock._hardResetCameraControls(flock.scene?.activeCamera);
    });

    window.addEventListener('pointerup', () => {
      flock._hardResetCameraControls(flock.scene?.activeCamera);
    });

    // macOS suppresses keyup for keys released while ⌘ is held; Babylon's
    // camera keyboard input keeps them in _keys, so the camera would drift
    // until the next blur. Clear its held keys when ⌘ comes up.
    flock.canvas.addEventListener('keyup', (e) => {
      if (e.key !== 'Meta') return;
      const kb = flock.scene?.activeCamera?.inputs?.attached?.keyboard;
      if (kb?._keys) kb._keys.length = 0;
    });

    flock.engineReady = true;
  },
  _scheduleContextEscalation() {
    clearTimeout(flock._escalationTimer);
    flock._escalationTimer = setTimeout(() => {
      flock._escalationTimer = null;
      if (flock.engine?.isContextLost?.()) {
        handleError(new Error('WebGL context restore timeout'), {
          source: 'webgl-lost',
          fatal: true,
        });
      }
    }, 8000);
  },
  createEngine() {
    flock.engine?.dispose();
    flock.engine = null;

    try {
      flock.engine = new flock.BABYLON.Engine(flock.canvas, true, {
        preserveDrawingBuffer: true,
        stencil: true,
        powerPreference: 'default',
      });
    } catch (error) {
      // WebGL unavailable or blacklisted: a device problem, not the project's.
      handleError(error, { source: 'webgl-lost', fatal: true });
      throw markReported(error);
    }

    flock.engine.disableUniformBuffers = true; // Meshes with alpha black on Samsung A14

    // Set on the engine, not the element: Babylon reapplies its default on every pointer move.
    flock.engine.canvasTabIndex = 0;

    if (!flock._webglContextLostListenerAdded) {
      flock._webglContextLostListenerAdded = true;
      // Call preventDefault() on the raw event so the browser is willing to restore.
      flock.canvas.addEventListener('webglcontextlost', (event) => {
        event.preventDefault();
      });
    }

    flock.engine.onContextLostObservable.add(() => {
      flock._contextLostAt = Date.now();
      showBanner('webgl-lost', {
        message: translate('error_webgl_restoring'),
      });
      if (document.visibilityState === 'visible') {
        flock._scheduleContextEscalation();
      }
    });

    flock.engine.onContextRestoredObservable.add(() => {
      clearTimeout(flock._escalationTimer);
      flock._escalationTimer = null;
      flock._contextLostAt = null;
      dismissBanner('webgl-lost');
      flock.engine.resize();
      // Don't resume behind the stopped overlay if Stop was pressed while the
      // context was lost.
      if (flock._renderLoop && !flock._renderLoopStopped) {
        flock.engine.runRenderLoop(flock._renderLoop);
      }
    });

    if (!flock._webglVisibilityListenerAdded) {
      flock._webglVisibilityListenerAdded = true;
      document.addEventListener('visibilitychange', () => {
        if (document.visibilityState === 'visible' && flock._contextLostAt) {
          flock.engine?.resize();
          if (!flock._escalationTimer) {
            flock._scheduleContextEscalation();
          }
        }
      });
    }

    if (!flock._audioVisibilityListenerAdded) {
      flock._audioVisibilityListenerAdded = true;
      document.addEventListener('visibilitychange', () => {
        flock.syncAudioWithPageState?.();
      });
    }

    if (!flock._gameClockVisibilityListenerAdded) {
      flock._gameClockVisibilityListenerAdded = true;
      flock._hiddenAccumMs = 0;
      flock._hiddenAt = document.visibilityState === 'hidden' ? Date.now() : null;
      document.addEventListener('visibilitychange', () => {
        if (document.visibilityState === 'hidden') {
          flock._hiddenAt ??= Date.now();
        } else if (flock._hiddenAt != null) {
          flock._hiddenAccumMs += Date.now() - flock._hiddenAt;
          flock._hiddenAt = null;
        }
      });
    }

    flock.engine.enableOfflineSupport = false;
    flock.engine.setHardwareScalingLevel(1 / window.devicePixelRatio);
  },
  async disposeOldScene() {
    flock.flockNotReady = true;

    if (flock.memoryDebug)
      if (flock.hk) {
        const [, stats] = flock.hk._hknp.HP_GetStatistics();

        const [
          numBodies,
          numShapes,
          numConstraints,
          numDebugGeometries,
          numWorlds,
          numQueryCollectors,
        ] = stats;

        console.log('Havok bodies:', numBodies);
        console.log('Havok shapes:', numShapes);
        console.log('Havok constraints:', numConstraints);
        console.log('Havok debug geometries:', numDebugGeometries);
        console.log('Havok worlds:', numWorlds);
        console.log('Havok query collectors:', numQueryCollectors);
        console.log(
          'Havok heap memory:',
          (flock.havokInstance.HEAPU8.buffer.byteLength / (1024 * 1024)).toFixed(2),
          'MB'
        );
      }

    if (flock.scene) {
      try {
        // Stop all sounds and animations first
        flock.stopAllSounds();
        flock.engine?.stopRenderLoop();

        if (flock.ground?.metadata) {
          const md = flock.ground.metadata;
          try {
            if (md.heightmapBody?._pluginData?.hpBodyId && flock.hk?.world) {
              flock.hk._hknp.HP_World_RemoveBody(
                flock.hk.world,
                md.heightmapBody._pluginData.hpBodyId
              );
            }
          } catch {
            /* ignore */
          }
          try {
            md.heightmapBody?.dispose();
          } catch {
            /* already disposed */
          }
          try {
            md.heightmapShape?.dispose();
          } catch {
            /* already disposed */
          }
          md.heightmapBody = null;
          md.heightmapShape = null;
        }

        flock._cameraControlBindings = null;
        flock._onScreenSource?.releaseAll();
        flock._onScreenSource?.stop();
        flock._joystickSource?.stop();
        flock._joystickSource = null;
        flock._gamepadSource?.stop();
        flock._gamepadSource = null;
        flock._xrSource?.stop();
        flock._xrSource = null;
        try {
          flock.xrHelper?.dispose?.();
        } catch (error) {
          console.warn('Error disposing xrHelper:', error);
        }
        flock.xrHelper = null;
        flock.inputManager.resetActionKeys();
        detachInteractIndicator();

        flock._cameraControls?.stop();
        flock._cameraControls = null;

        if (flock._gamepadButtonObserver) {
          flock.scene.onBeforeRenderObservable.remove(flock._gamepadButtonObserver);
          flock._gamepadButtonObserver = null;
        }

        try {
          const canvas = flock.engine?.getRenderingCanvas?.();
          flock.scene?.activeCamera?.detachControl?.(canvas);
          flock.scene?.detachControl?.();
        } catch {
          /* ignore scene cleanup errors */
        }

        // Abort any ongoing operations
        if (flock.abortController) {
          flock.abortController.abort();
        }

        // Stop all animations and dispose animation groups
        flock.scene.stopAllAnimations();

        // Dispose animatables
        if (flock.scene.animatables) {
          [...flock.scene.animatables].forEach((animatable) => {
            try {
              animatable.stop();
              animatable.dispose?.();
            } catch (error) {
              console.warn('Error disposing animatable:', error);
            }
          });
        }

        // Dispose animation groups
        if (flock.scene.animationGroups) {
          [...flock.scene.animationGroups].forEach((group) => {
            if (group) {
              try {
                group.stop();
                group.dispose();
              } catch (error) {
                console.warn('Error disposing animation group:', error);
              }
            }
          });
        }

        // Clear all observables and event listeners
        flock.removeEventListeners();

        // Dispose UI elements
        flock.controlsTexture?.dispose();
        flock.controlsTexture = null;

        // Clear main UI texture and all its controls
        if (flock.scene.UITexture) {
          flock.scene.UITexture.dispose();
          flock.scene.UITexture = null;
        }

        // Clear advanced texture and stack panel
        if (flock.advancedTexture) {
          flock.advancedTexture.dispose();
          flock.advancedTexture = null;
        }

        if (flock.stackPanel) {
          flock.stackPanel.dispose();
          flock.stackPanel = null;
        }

        // Dispose sound tracks
        if (flock.scene.mainSoundTrack) {
          flock.scene.mainSoundTrack.dispose();
        }
        if (flock.scene.soundTracks) {
          flock.scene.soundTracks.forEach((track) => track?.dispose());
        }

        // Dispose post-processing effects
        if (flock.scene.postProcesses) {
          [...flock.scene.postProcesses].forEach((pp) => pp?.dispose());
        }
        flock.scene.postProcessRenderPipelineManager?.dispose();

        // Dispose effects
        flock.highlighter?.dispose();
        flock.highlighter = null;
        flock.glowLayer?.dispose();
        flock.glowLayer = null;

        // Dispose lighting
        flock.mainLight?.dispose();
        flock.mainLight = null;

        // Dispose particle systems first (before meshes they might be attached to)
        const particleSystems = flock.scene.particleSystems ? [...flock.scene.particleSystems] : [];
        particleSystems.forEach((system) => {
          if (system?.dispose) {
            try {
              system.dispose();
            } catch (error) {
              console.warn('Error disposing particle system:', error);
            }
          }
        });

        if (flock.scene.meshes) {
          for (const mesh of flock.scene.meshes) {
            const c = mesh?.metadata?.uprightConstraint;
            if (c) {
              try {
                c.dispose();
              } catch (e) {
                console.warn('Error disposing constraint:', e);
              }
              mesh.metadata.uprightConstraint = null;
            }
          }
        }

        // Dispose all meshes and their action managers
        const meshesToDispose = flock.scene.meshes ? [...flock.scene.meshes] : [];
        meshesToDispose.forEach((mesh) => {
          if (mesh?.actionManager) {
            try {
              mesh.actionManager.dispose();
            } catch (error) {
              console.warn('Error disposing action manager:', error);
            }
          }
          if (mesh?.material?.dispose && typeof mesh.material.dispose === 'function') {
            try {
              mesh.material.dispose();
            } catch (error) {
              console.warn('Error disposing mesh material:', error);
            }
          }
          if (mesh?.dispose && typeof mesh.dispose === 'function') {
            try {
              // Shared shapes are disposed via physicsShapeCache below
              if (!mesh.physics?.shape?._isShared) {
                mesh.physics?.shape?.dispose();
              }
              mesh.physics?.dispose();

              mesh.dispose();
            } catch (error) {
              console.warn('Error disposing mesh:', error);
            }
          }
        });

        // Dispose transform nodes
        const transformNodes = flock.scene.transformNodes ? [...flock.scene.transformNodes] : [];
        transformNodes.forEach((node) => {
          if (node?.dispose) {
            try {
              node.dispose();
            } catch (error) {
              console.warn('Error disposing transform node:', error);
            }
          }
        });

        // Dispose geometries (after meshes)
        const geometries = flock.scene.geometries ? [...flock.scene.geometries] : [];
        geometries.forEach((geometry) => {
          if (geometry?.dispose) {
            try {
              geometry.dispose();
            } catch (error) {
              console.warn('Error disposing geometry:', error);
            }
          }
        });

        // Clear camera
        if (flock.scene.activeCamera) {
          flock.scene.activeCamera.inputs?.clear();
          flock.scene.activeCamera.dispose();
        }

        // Dispose textures
        const textures = flock.scene.textures ? [...flock.scene.textures] : [];
        textures.forEach((texture) => {
          if (texture?.dispose && typeof texture.dispose === 'function') {
            try {
              texture.dispose();
            } catch (error) {
              console.warn('Error disposing texture:', error);
            }
          }
        });

        // Dispose materials that weren't caught earlier
        const materials = flock.scene.materials ? [...flock.scene.materials] : [];
        materials.forEach((material) => {
          if (material?.dispose && typeof material.dispose === 'function') {
            try {
              material.dispose();
            } catch (error) {
              console.warn('Error disposing material:', error);
            }
          }
        });

        // Clear all scene observables
        flock.scene.onActiveCameraChanged?.remove(flock._audioListenerObserver);
        flock._audioListenerObserver = null;
        flock.scene.onBeforeRenderObservable?.clear();
        flock.scene.onAfterRenderObservable?.clear();
        flock.scene.onBeforeAnimationsObservable?.clear();
        flock.scene.onAfterAnimationsObservable?.clear();
        flock.scene.onReadyObservable?.clear();
        flock.scene.onDataLoadedObservable?.clear();
        flock.scene.onDisposedObservable?.clear();
        flock.scene.onPointerObservable?.clear();
        flock.scene.onKeyboardObservable?.clear();

        // Wait for async operations to complete
        await new Promise((resolve) => setTimeout(resolve, 100));

        // Dispose any shapes still in the cache (e.g. from models disposed mid-scene
        // whose cache entry was never cleaned up). Must happen before hk.dispose().
        for (const shape of Object.values(flock.physicsShapeCache)) {
          if (!shape?._isDisposed) {
            try {
              shape.dispose();
            } catch {
              /* already disposed */
            }
          }
        }

        // Dispose physics engine and release WASM heap
        try {
          flock.hk?.dispose(); // Babylon's HavokPlugin wrapper
        } catch (error) {
          console.warn('Error disposing HavokPlugin:', error);
        }
        flock.hk = null;

        // Dispose of the scene
        flock.scene.dispose();
        flock.scene = null;

        // Dispose the Babylon.js engine
        //flock.engine?.dispose();
        //flock.engine = null;

        // Dispose Babylon audio engine, then close the underlying context.
        // Capture the context reference now — stopAllSounds() (called earlier) nulls
        // flock.audioContext without closing it when Babylon owns it, so we must
        // grab _audioContext directly before dispose clears the engine reference.
        // Closing the context kills all scheduled oscillators from playMidiNote that
        // are not tracked in globalSounds.
        const audioContextToClose = flock.audioEngine?._audioContext ?? flock.audioContext;
        try {
          flock.audioEngine?.dispose?.();
        } catch (error) {
          console.warn('Error disposing audioEngine:', error);
        }
        flock.audioEngine = null;
        flock.audioEnginePromise = null;

        if (audioContextToClose && audioContextToClose.state !== 'closed') {
          try {
            await audioContextToClose.close();
          } catch (error) {
            console.warn('AudioContext was already closed or closing:', error);
          }
        }
        flock.audioContext = null;
        flock._audioStopped = false;

        // Clear all references
        flock.events = {};
        flock.modelCache = {};
        flock.globalSounds = [];
        flock.modelsBeingLoaded = {};
        flock.originalModelTransformations = {};
        flock.geometryCache = {};
        flock.materialCache = {};
        flock.physicsShapeCache = {};
        flock.pendingTriggers = new Map();
        flock.pendingIntersections = new Map();
        flock.pendingSelfIntersections = new Map();
        flock._nameRegistry = new Map();
        flock._liveNameCache = new Map();
        flock._ambiguousLiveNames = new Set();
        flock._animationFileCache = {};
        flock.ground = null;
        flock.sky = null;

        // Clear abort controller
        flock.abortController = null;

        // Force garbage collection in development (if available)
        if (typeof window !== 'undefined' && window.gc) {
          setTimeout(() => {
            try {
              window.gc();
              console.log('Forced garbage collection');
            } catch {
              // Silently fail if gc is not available
            }
          }, 100);
        }
      } catch (error) {
        console.error('Error during scene disposal:', error);
        // Even if disposal fails, clear critical references
        flock.scene = null;
        flock.engine = null;
        flock.flockNotReady = true;
      }
    } else {
      console.log('No scene to dispose');
      if (flock.abortController) {
        flock.abortController.abort();
        flock.abortController = null;
      }
    }
  },
  ensureAudio() {
    if (!flock.audioEnginePromise) {
      // iOS Safari polyfill — must run before Babylon calls new AudioContext().
      if (typeof window !== 'undefined' && !window.AudioContext && window.webkitAudioContext) {
        window.AudioContext = window.webkitAudioContext;
      }
      try {
        // Capture the promise reference so the .then() handler can detect if
        // cleanup ran (set audioEnginePromise to null) or a new scene replaced
        // it before this async init resolved — and dispose the stale engine.
        let enginePromise;
        enginePromise = flock.BABYLON.CreateAudioEngineAsync({
          volume: 1,
          listenerAutoUpdate: true,
          listenerEnabled: true,
          resumeOnInteraction: true,
        })
          .then((audioEngine) => {
            if (flock.audioEnginePromise !== enginePromise) {
              try {
                audioEngine.dispose?.();
              } catch {
                /* best-effort */
              }
              return;
            }
            flock.audioEngine = audioEngine;
            dismissBanner('audio');
            flock.audioContext = audioEngine._audioContext ?? flock.audioContext;
            flock.globalStartTime = flock.audioContext?.currentTime ?? 0;
            if (flock.scene?.activeCamera) {
              audioEngine.listener.attach(flock.scene.activeCamera);
            }
            flock._audioListenerObserver = flock.scene?.onActiveCameraChanged?.add(() => {
              if (flock.scene?.activeCamera) {
                audioEngine.listener.attach(flock.scene.activeCamera);
              }
            });
          })
          .catch((err) => {
            console.warn('[flock] Audio engine unavailable:', err);
            flock.audioEngine = null;
            showBanner('audio', { message: translate('error_audio') });
          });
        flock.audioEnginePromise = enginePromise;
      } catch (err) {
        console.warn('[flock] Audio engine unavailable:', err);
        flock.audioEngine = null;
        flock.audioEnginePromise = Promise.resolve();
        showBanner('audio', { message: translate('error_audio') });
      }
    }
    return flock.audioEnginePromise;
  },
  async initializeNewScene() {
    // Wait a bit more to ensure all disposal operations are complete
    await new Promise((resolve) => setTimeout(resolve, 200));

    // Stop existing render loop or create a new engine
    flock.engine ? flock.engine.stopRenderLoop() : flock.createEngine();

    // Reset scene-wide state
    flock.events = {};
    flock.modelCache = {};
    flock.globalSounds = [];
    flock.modelsBeingLoaded = {};
    flock.originalModelTransformations = {};
    flock.geometryCache = {};
    flock.pendingTriggers = new Map();
    flock.pendingIntersections = new Map();
    flock.pendingSelfIntersections = new Map();
    flock._nameRegistry = new Map();
    flock._liveNameCache = new Map();
    flock.modelReadyPromises = new Map();
    flock._animationFileCache = {};
    flock.materialCache = {};
    flock.physicsShapeCache = {};
    flock.havokAbortHandled = false;
    flock.disposed = false;

    // Clear any error banner from a previous run now that we're starting fresh.
    dismissBanner('physics-oom');
    dismissBanner('project-run');

    // Create the new scene
    flock.scene = new flock.BABYLON.Scene(flock.engine);

    //Enable accessibility layer
    clearUIControls();
    enableSceneDescription(flock.scene, flock.inputManager);
    // Announce "say" and "printText" outputs so NVDA reads Blockly say blocks reliably.
    if (!flock._a11yTextWrapped) {
      // Wrap say(text, ...)
      if (typeof flock.say === 'function') {
        const originalSay = flock.say.bind(flock);
        flock.say = (...args) => {
          const result = originalSay(...args);

          const targetName = args?.[0];
          const options = args?.[1];
          const text = options && typeof options.text === 'string' ? options.text : '';
          const rawDuration = options?.duration;
          const duration =
            isFinite(Number(rawDuration)) && Number(rawDuration) > 0 ? Number(rawDuration) : 0;

          if (text.trim()) {
            if (duration > 0) {
              // Transient say: announce immediately and show in Ctrl+J while visible
              const mesh = flock.scene?.getMeshByName(targetName);
              const label = mesh ? getObjectLabel(mesh) : targetName;
              announceObjectSay(`${label} says: ${text}`);
              setTransientSayText(targetName, text, duration);
            } else {
              // Persistent say: store for Ctrl+J nearest-object reading
              recordObjectPromptText(targetName, text);
              recordObjectSayText(targetName, text);
            }
          }

          return result;
        };
      }

      // Wrap printText({ text: "..." })
      if (typeof flock.printText === 'function') {
        const originalPrintText = flock.printText.bind(flock);
        flock.printText = (...args) => {
          const result = originalPrintText(...args);

          const payload = args?.[0];
          const text =
            typeof payload === 'string'
              ? payload
              : payload && typeof payload.text === 'string'
                ? payload.text
                : '';

          if (text && text.trim()) {
            recordWorldInstructionText(text);
            announceSayText(text);
          }
          return result;
        };
      }

      flock._a11yTextWrapped = true;
    }

    flock._renderLoop = () => {
      try {
        flock.scene.render();
      } catch (error) {
        if (flock.isPhysicsMemoryAbort(error)) {
          flock.handlePhysicsOutOfMemory(error);
          return;
        }
        // Stop the loop so a crash doesn't re-fire every frame.
        flock._renderLoopStopped = true;
        flock.engine?.stopRenderLoop(flock._renderLoop);
        handleError(error, { source: 'project-run', fatal: false });
      }
    };

    // Apply and remember the app's default clear colour so it can be
    // restored if the user removes their sky/background blocks later.
    const defaultClearColor = flock.BABYLON.Color3.FromHexString('#33334c');
    flock.scene.clearColor = defaultClearColor.clone?.() ?? defaultClearColor;
    flock.initialClearColor = defaultClearColor.clone?.() ?? defaultClearColor;

    // Abort controller for clean-up
    flock.abortController = new AbortController();
    flock._canvasControlsEnabled = undefined;
    // Subtitles default off each run; the enable_subtitles block opts in.
    flock.subtitlesEnabled = false;
    flock._subtitleControl = null;
    flock._subtitleToken = 0;
    flock._subtitleTimer = null;

    // Enable physics
    await flock.ensurePhysicsInstance();
    flock.hk = new flock.BABYLON.HavokPlugin(true, flock.havokInstance);
    flock.scene.enablePhysics(new flock.BABYLON.Vector3(0, -9.81, 0), flock.hk);
    setFlockCSG(flock);
    setFlockAnimate(flock);
    setFlockSound(flock);
    setFlockUI(flock);
    setFlockMovement(flock);
    setFlockModels(flock);
    setFlockShapes(flock);
    setFlockTransform(flock);
    setFlockMaterial(flock);
    setFlockEffects(flock);
    setFlockPhysics(flock);
    setFlockScene(flock);
    setFlockMesh(flock);
    setFlockCamera(flock);
    setFlockXR(flock);
    setFlockMath(flock);
    setFlockControl(flock);
    setFlockEvents(flock);
    setFlockMicrobit(flock);
    setFlockSensing(flock);

    // Add highlight layer
    flock.highlighter = new flock.BABYLON.HighlightLayer('highlighter', flock.scene);

    // Set up a new camera
    const camera = new flock.BABYLON.FreeCamera(
      'camera',
      new flock.BABYLON.Vector3(0, 3, -10),
      flock.scene
    );
    flock.savedCamera = camera;
    camera.minZ = 0;
    camera.setTarget(flock.BABYLON.Vector3.Zero());
    camera.rotation.x = flock.BABYLON.Tools.ToRadians(0);
    camera.angularSensibilityX = 2000;
    camera.angularSensibilityY = 2000;
    camera.speed = 0.25;
    flock.scene.activeCamera = camera;
    camera.attachControl(flock.canvas, false);

    // Extend the fly camera's vertical keyboard bindings to match the
    // on-screen button layout: BUTTON1 keys + PageUp for up,
    // BUTTON3 keys + PageDown for down. Babylon's native input handles
    // these with its built-in inertia/smoothing, keeping it consistent
    // with gamepad button movement.
    const KEY_CODE = { PageUp: 33, PageDown: 34, r: 82, 1: 49, f: 70, 3: 51 };
    const toKeyCodes = (keys) => keys.map((k) => KEY_CODE[k]).filter(Boolean);
    const kbInput = camera.inputs?.attached?.keyboard;
    if (kbInput) {
      kbInput.keysUpward = toKeyCodes([...getBoundKeys('BUTTON1'), 'PageUp']);
      kbInput.keysDownward = toKeyCodes([...getBoundKeys('BUTTON3'), 'PageDown']);
    }

    // An engine created while the canvas was hidden keeps a 1x buffer until
    // something resizes it.
    if (flock.canvas?.clientWidth > 0 && flock.canvas?.clientHeight > 0) {
      flock.engine.resize();
    }

    // Start the render loop now that a camera exists
    flock._renderLoopStopped = false;
    flock.engine.runRenderLoop(flock._renderLoop);
    flock._gamepadSource = new GamepadSource(flock.inputManager, {
      scene: flock.scene,
      canvas: flock.canvas,
    });
    flock._gamepadSource.start();
    flock._onScreenSource.start(flock.scene);
    flock._cameraControls = new CameraControls(flock);
    flock._cameraControls.start();
    // Set up lighting
    const hemisphericLight = new flock.BABYLON.HemisphericLight(
      'hemisphericLight',
      new flock.BABYLON.Vector3(0, 3, 0),
      flock.scene
    );
    hemisphericLight.intensity = 1.0;
    hemisphericLight.diffuse = new flock.BABYLON.Color3(1, 1, 1);
    hemisphericLight.groundColor = new flock.BABYLON.Color3(0.5, 0.5, 0.5);

    flock.mainLight = hemisphericLight;

    // Directional light that drives the ShadowGenerator. A shadow is the
    // absence of this light's contribution where it's blocked, so it must
    // actually illuminate. It starts at intensity 0 (no effect, flat
    // hemispheric look by default); enableShadows() raises it so the "sun"
    // shading and cast shadows only appear while shadows are turned on.
    const shadowLight = new flock.BABYLON.DirectionalLight(
      'shadowLight',
      // Near-overhead angle keeps shadows small and tucked under objects for
      // a cartoony look (a shallower angle stretches them out). A slight
      // offset is kept so vertical faces still get some directional shading.
      new flock.BABYLON.Vector3(-0.15, -1, -0.15),
      flock.scene
    );
    shadowLight.position = new flock.BABYLON.Vector3(20, 40, 20);
    shadowLight.intensity = 0;
    flock.shadowLight = shadowLight;
    flock.shadowGenerator = null;
    flock.shadowCasters.clear();

    // Enable collisions
    flock.scene.collisionsEnabled = true;

    flock.onScreenControls('ARROWS', 'YES', 'AUTO', '#ffffff');

    // Create the UI
    flock.advancedTexture = flock.GUI.AdvancedDynamicTexture.CreateFullscreenUI('UI');

    // Stack panel for text
    flock.stackPanel = new flock.GUI.StackPanel();
    flock.stackPanel.width = '100%'; // Fixed width for the panel
    flock.stackPanel.horizontalAlignment = flock.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT; // Align to the left
    flock.stackPanel.verticalAlignment = flock.GUI.Control.VERTICAL_ALIGNMENT_TOP; // Align to the top

    flock.stackPanel.isVertical = true;
    flock.advancedTexture.addControl(flock.stackPanel);

    // Keep the listener up to date while sounds are playing, but don't
    // create a new AudioContext just because a frame rendered.
    flock.scene.onBeforeRenderObservable.add(() => {
      // When Babylon's audio engine is active it owns context.listener via
      // listener.attach(camera) + listenerAutoUpdate:true. Setting .value on
      // the same AudioParams would throw NotSupportedError (setValueAtTime
      // overlapping setValueCurveAtTime). Skip our manual update in that case.
      if (flock.audioEngine) return;
      const context = flock.audioContext;
      if (context && context.state !== 'closed' && flock.scene.activeCamera) {
        flock.updateListenerPositionAndOrientation(context, flock.scene.activeCamera);
      }
    });

    attachInteractIndicator(flock.scene, flock.inputManager);

    // Mark scene as ready
    flock.flockNotReady = false;

    // Reset XR helper
    flock.xrHelper = null;
  },
  _xrTuning(param, fallback, min, max) {
    let raw = null;
    try {
      raw = new URLSearchParams(window.location.search).get(param);
    } catch {
      // No location (tests, workers): use the default.
    }
    if (raw === null || raw.trim() === '') return fallback;
    const value = Number(raw);
    if (!Number.isFinite(value)) return fallback;
    return Math.min(max, Math.max(min, value));
  },
  _xrCanvasOptions() {
    const defaults = flock.BABYLON.WebXRManagedOutputCanvasOptions.GetDefaults(flock.engine);
    return {
      ...defaults,
      canvasOptions: {
        ...defaults.canvasOptions,
        framebufferScaleFactor: flock._xrTuning('xs', flock.xrFramebufferScale, 0.5, 2),
      },
    };
  },
  async initializeXR(mode) {
    if (flock.xrHelper) return; // Avoid reinitializing

    if (mode === 'VR') {
      flock.xrHelper = await flock.scene.createDefaultXRExperienceAsync({
        outputCanvasOptions: flock._xrCanvasOptions(),
      });
    } else if (mode === 'AR') {
      flock.xrHelper = await flock.scene.createDefaultXRExperienceAsync({
        outputCanvasOptions: flock._xrCanvasOptions(),
        uiOptions: {
          sessionMode: 'immersive-ar',
        },
      });
    } else if (mode === 'MAGIC_WINDOW') {
      let camera = flock.scene.activeCamera;
      if (!camera.inputs.attached.deviceOrientation) {
        camera.inputs.addDeviceOrientation();
      }
    }

    // Create a UI plane for the wrist
    flock.uiPlane = flock.BABYLON.MeshBuilder.CreatePlane('uiPlane', { size: 0.4 }, flock.scene); // Smaller size for wrist UI
    flock.uiPlane.isVisible = false; // Start hidden

    const planeMaterial = new flock.BABYLON.StandardMaterial('uiPlaneMaterial', flock.scene);
    planeMaterial.disableDepthWrite = true;
    flock.uiPlane.material = planeMaterial;

    flock.meshTexture = flock.GUI.AdvancedDynamicTexture.CreateForMesh(flock.uiPlane);

    // Ensure the UI plane follows the wrist (using a controller or camera offset)
    flock.xrHelper.input.onControllerAddedObservable.add((controller) => {
      if (controller.inputSource.handedness === 'left') {
        // Attach the UI plane to the left-hand controller
        flock.uiPlane.parent = controller.grip || controller.pointer;

        // Position the UI plane to simulate a watch
        flock.uiPlane.position.set(0.1, -0.05, 0); // Slightly to the side, closer to the wrist
        flock.uiPlane.rotation.set(Math.PI / 2, 0, 0); // Rotate to face the user
      }
    });

    flock._xrSource = new XRSource(flock.inputManager, {
      xrHelper: flock.xrHelper,
      scene: flock.scene,
    });
    flock._xrSource.start();

    // Handle XR state changes
    flock.xrHelper.baseExperience.onStateChangedObservable.add((state) => {
      if (state === flock.BABYLON.WebXRState.ENTERING_XR) {
        flock._xrSource?.start();
        flock.advancedTexture.removeControl(flock.stackPanel);
        flock.meshTexture.addControl(flock.stackPanel);
        flock.uiPlane.isVisible = true;

        // Update alignment for wrist UI
        flock.stackPanel.horizontalAlignment = flock.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT;
        flock.stackPanel.verticalAlignment = flock.GUI.Control.VERTICAL_ALIGNMENT_TOP;

        flock.advancedTexture.isVisible = false; // Hide fullscreen UI
      } else if (state === flock.BABYLON.WebXRState.IN_XR) {
        // Base layer only exists once IN_XR; setting it at ENTERING_XR no-ops.
        flock.xrHelper.baseExperience.sessionManager.fixedFoveation = flock._xrTuning(
          'xf',
          flock.xrFixedFoveation,
          0,
          1
        );
      } else if (state === flock.BABYLON.WebXRState.EXITING_XR) {
        flock._xrSource?.stop();
        flock.meshTexture.removeControl(flock.stackPanel);
        flock.advancedTexture.addControl(flock.stackPanel);
        flock.uiPlane.isVisible = false;

        // Restore alignment for non-XR
        flock.stackPanel.width = '100%';
        flock.stackPanel.horizontalAlignment = flock.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT;
        flock.stackPanel.verticalAlignment = flock.GUI.Control.VERTICAL_ALIGNMENT_TOP;

        flock.advancedTexture.rootContainer.isVisible = true;
      }
    });
  },
  removeEventListeners() {},
  whenModelReady(id, callback) {
    // Capture the current run's abort signal now. Guards must check this
    // captured signal, never flock.abortController re-read at settle time:
    // stopping a run aborts and replaces the controller, so a late-settling
    // promise from the old run would see the new run's (unaborted) signal
    // and run its stale callback into the new scene.
    const signal = flock.abortController?.signal;

    // --- Registry fast path ---
    // Steady-state O(1): once a name has resolved to a live mesh it is
    // cached in _liveNameCache (by announceMeshReady or a previous call
    // here). A miss — or a stale entry whose mesh was disposed — falls
    // through to the full lookup below, so worst case is the existing
    // behaviour. Sentinel ids (__active_camera__/__main_light__) are never
    // cached, so they take the normal path.
    const cached = flock._ambiguousLiveNames?.has(id) ? null : flock._liveNameCache.get(id);
    if (cached) {
      if (cached.isDisposed()) {
        flock._liveNameCache.delete(id);
      } else if (signal?.aborted) {
        // Match the locate() hit path below: when aborted the callback is
        // not run and the returned promise never settles.
        return new Promise(() => {});
      } else {
        // Run the callback inline and resolve once it completes (awaiting
        // async callbacks) — same contract as settle on the hit path.
        try {
          const result = typeof callback === 'function' ? callback(cached) : undefined;
          return result && typeof result.then === 'function'
            ? Promise.resolve(result).then(() => cached)
            : Promise.resolve(cached);
        } catch (error) {
          return Promise.reject(error);
        }
      }
    }

    // --- Promise that resolves when ready (or undefined on abort/dispose) ---
    let settled = false;
    let resolveP;
    let rejectP;
    const promise = new Promise((resolve, reject) => {
      resolveP = resolve;
      rejectP = reject;
    });

    // The callback often does async setup (e.g. awaiting materials,
    // loading textures, or chaining other whenModelReady calls).
    // Await it so the readiness promise only resolves once that
    // user-provided async work is finished.
    const settle = async (val) => {
      if (settled) return;
      settled = true;
      try {
        // Cache the resolved target (meshes only) so subsequent lookups of
        // this id — including pre-sanitization aliases — skip the scans
        // below and take the registry fast path.
        flock._registerLiveName(id, val);
        // Await the callback so the readiness promise doesn't resolve
        // before user async work completes (premature resolution).
        if (typeof callback === 'function') await callback(val);
        resolveP(val);
      } catch (error) {
        rejectP(error);
      }
    };

    // Helper: locate current object
    const locate = () => {
      const scene = flock.scene;
      if (!scene) return null;
      if (id === '__active_camera__') return scene.activeCamera ?? null;
      if (id === '__main_light__') return flock.mainLight ?? null;

      let t = scene.getMeshByName?.(id) ?? null;
      if (!t && scene.UITexture) t = scene.UITexture.getControlByName?.(id) ?? null;
      if (!t && Array.isArray(scene.animationGroups))
        t = scene.animationGroups.find((g) => g.name === id) ?? null;
      if (!t && Array.isArray(scene.particleSystems))
        t = scene.particleSystems.find((s) => s.name === id) ?? null;
      return t ?? null;
    };

    // --- Fast paths ---
    // Runs at call time and again when a late-arriving scene appears (the
    // rAF wait below), since the target may already be present by then.
    // Returns true when a path claimed the lookup and will settle.
    const tryFastPaths = () => {
      // Check if there's a pending promise for this mesh first
      // This ensures we wait for geometry to be attached before returning
      if (flock.modelReadyPromises.has(id)) {
        const pendingPromise = flock.modelReadyPromises.get(id);
        pendingPromise
          .then((resolvedMesh) => {
            // Re-locate after promise resolves to get mesh with geometry.
            // Fall back to the resolved mesh value for alias lookups where
            // id is the pre-sanitization name (e.g. "dimnnd monkey") but
            // the actual mesh is named differently ("dimnndmonkey").
            const meshWithGeometry = locate() ?? resolvedMesh ?? null;
            if (!signal?.aborted) void settle(meshWithGeometry);
          })
          .catch(() => {
            // On error, still try to return what we can find
            const meshWithGeometry = locate();
            if (!signal?.aborted) void settle(meshWithGeometry);
          });
        return true;
      }

      if (flock.scene) {
        const existing = locate();
        if (existing) {
          if (!signal?.aborted) void settle(existing);
          return true;
        }
      }

      // --- Normalize-as-fallback for createCharacter/createObject names ---
      // createCharacter and createObject strip special characters from names
      // (e.g. "dimnnd monkey" → "dimnndmonkey"). createBox/createSphere etc.
      // do NOT sanitize, so "centre platform" stays "centre platform". We must
      // NOT apply normalization upfront or those box lookups break.
      // Instead: only redirect to the normalized id when the exact id is absent
      // but the normalized form IS present in modelReadyPromises or the scene.
      // This also handles the stale-alias case (after the 5s TTL cleanup).
      if (id && !id.startsWith('__')) {
        let norm = id.includes('__') ? id.split('__')[0] : id;
        norm = norm.replace(/[^a-zA-Z0-9._-]/g, '');
        if (norm && norm !== id) {
          if (flock.modelReadyPromises.has(norm)) {
            const pendingPromise = flock.modelReadyPromises.get(norm);
            pendingPromise
              .then((resolvedMesh) => {
                const meshWithGeometry = flock.scene?.getMeshByName(norm) ?? resolvedMesh ?? null;
                if (!signal?.aborted) void settle(meshWithGeometry);
              })
              .catch(() => {
                if (!signal?.aborted) void settle(null);
              });
            return true;
          }
          const existing = flock.scene?.getMeshByName(norm);
          if (existing) {
            if (!signal?.aborted) void settle(existing);
            return true;
          }
        }
      }

      return false;
    };

    if (tryFastPaths()) return promise;

    // --- Observer path ---
    const attachObservers = () => {
      const scene = flock.scene;
      if (!scene) return;

      const disposers = [];
      let done = false;
      const finish = async (target /*, source */) => {
        if (done) return;
        done = true;
        try {
          if (!signal?.aborted) await settle(target);
        } finally {
          while (disposers.length) {
            try {
              disposers.pop()();
            } catch {
              /* ignore disposer errors */
            }
          }
        }
      };

      // active camera
      if (id === '__active_camera__') {
        const camNow = scene.activeCamera;
        if (camNow) {
          finish(camNow);
          return;
        }
        if (scene.onActiveCameraChanged) {
          const cb = () => {
            if (scene.activeCamera) finish(scene.activeCamera);
          };
          scene.onActiveCameraChanged.add(cb);
          disposers.push(() => scene.onActiveCameraChanged.removeCallback(cb));
        }
        if (scene.onDisposeObservable) {
          const h = scene.onDisposeObservable.add(() => finish(undefined));
          disposers.push(() => scene.onDisposeObservable.remove(h));
        }
        if (signal) {
          const onAbort = () => finish(undefined);
          signal.addEventListener('abort', onAbort, { once: true });
          disposers.push(() => signal.removeEventListener('abort', onAbort));
        }
        return;
      }

      // main light — a plain flock property with no assignment event, so
      // check per frame until it appears (mirrors the attachGui pattern).
      // Mesh/GUI observers below could never match a light, so without
      // this a waiter would pend until scene dispose.
      if (id === '__main_light__') {
        const lightNow = flock.mainLight;
        if (lightNow) {
          finish(lightNow);
          return;
        }
        const tick = scene.onBeforeRenderObservable.add(() => {
          if (flock.mainLight) finish(flock.mainLight);
        });
        disposers.push(() => scene.onBeforeRenderObservable.remove(tick));
        if (scene.onDisposeObservable) {
          const h = scene.onDisposeObservable.add(() => finish(undefined));
          disposers.push(() => scene.onDisposeObservable.remove(h));
        }
        if (signal) {
          const onAbort = () => finish(undefined);
          signal.addEventListener('abort', onAbort, { once: true });
          disposers.push(() => signal.removeEventListener('abort', onAbort));
        }
        return;
      }

      // meshes
      if (scene.onNewMeshAddedObservable) {
        const h = scene.onNewMeshAddedObservable.add((mesh) => {
          if (done) return;
          if (mesh?.name === id) {
            finish(mesh);
            return;
          }
          // Handle the case where this observer was set up before
          // createCharacter ran. createCharacter registers the
          // pre-sanitization name (e.g. "dimnnd monkey") in
          // modelReadyPromises pointing to the same promise as the
          // sanitized name ("dimnndmonkey"). When any mesh is added
          // to the scene (triggering this callback), check whether id
          // is now in modelReadyPromises and if so switch to waiting
          // for that promise instead.
          if (flock.modelReadyPromises?.has(id)) {
            done = true;
            while (disposers.length) {
              try {
                disposers.pop()();
              } catch {
                /* ignore */
              }
            }
            flock.modelReadyPromises
              .get(id)
              .then((resolvedMesh) => {
                const m = locate() ?? resolvedMesh ?? null;
                if (!signal?.aborted) void settle(m);
              })
              .catch(() => {
                if (!signal?.aborted) void settle(undefined);
              });
          }
        });
        disposers.push(() => scene.onNewMeshAddedObservable.remove(h));
      }

      // animation groups
      if (scene.onAnimationGroupAddedObservable) {
        const h = scene.onAnimationGroupAddedObservable.add((group) => {
          if (!done && group?.name === id) finish(group);
        });
        disposers.push(() => scene.onAnimationGroupAddedObservable.remove(h));
      }

      // particle systems
      if (scene.onNewParticleSystemAddedObservable) {
        const h = scene.onNewParticleSystemAddedObservable.add((ps) => {
          if (!done && ps?.name === id) finish(ps);
        });
        disposers.push(() => scene.onNewParticleSystemAddedObservable.remove(h));
      }

      // GUI controls (attach when UITexture exists)
      const attachGui = () => {
        const tex = scene.UITexture;
        if (!tex) return false;
        // The texture (and the target control) may have been created since
        // the last check — a control added before we subscribe below would
        // otherwise be missed.
        const existing = tex.getControlByName?.(id) ?? null;
        if (existing) {
          finish(existing);
          return true;
        }
        if (!tex.onControlAddedObservable) return false;
        const h = tex.onControlAddedObservable.add((ctrl) => {
          if (!done && ctrl?.name === id) finish(ctrl);
        });
        disposers.push(() => tex.onControlAddedObservable.remove(h));
        return true;
      };
      if (!attachGui()) {
        const tick = scene.onBeforeRenderObservable.add(() => {
          if (attachGui()) scene.onBeforeRenderObservable.remove(tick);
        });
        disposers.push(() => scene.onBeforeRenderObservable.remove(tick));
      }

      // scene dispose / abort
      if (scene.onDisposeObservable) {
        const h = scene.onDisposeObservable.add(() => finish(undefined));
        disposers.push(() => scene.onDisposeObservable.remove(h));
      }
      if (signal) {
        const onAbort = () => finish(undefined);
        signal.addEventListener('abort', onAbort, { once: true });
        disposers.push(() => signal.removeEventListener('abort', onAbort));
      }
    };

    // wait for scene if needed
    if (!flock.scene) {
      let rafId = 0;
      const check = () => {
        if (signal?.aborted) return;
        if (flock.scene) {
          cancelAnimationFrame(rafId);
          // The scene may already contain the target — its addition event
          // fired before any observer could attach — so re-run the fast
          // paths first or the promise would pend forever.
          if (!tryFastPaths()) attachObservers();
          return;
        }
        rafId = requestAnimationFrame(check);
      };
      rafId = requestAnimationFrame(check);
      if (signal) {
        const onAbort = () => cancelAnimationFrame(rafId);
        signal.addEventListener('abort', onAbort, { once: true });
      }
      return promise; // <— still return the promise
    }

    attachObservers();
    return promise;
  },
  announceMeshReady(meshName, groupName) {
    flock._registerLiveName(meshName, flock.scene?.getMeshByName(meshName));

    const getGroupRoot = (name) => (name.includes('__') ? name.split('__')[0] : name.split('_')[0]);

    groupName = getGroupRoot(groupName);

    if (flock.pendingTriggers.has(groupName)) {
      const triggers = flock.pendingTriggers.get(groupName);
      const remaining = [];

      for (const pending of triggers) {
        const { meshName: pendingMeshName, trigger, callback, mode, applyToGroup } = pending;
        const targetMeshName = pendingMeshName ?? meshName;

        if (applyToGroup) {
          // Register trigger only on the newly announced mesh; keep pending for future siblings.
          flock.onTrigger(meshName, {
            trigger,
            callback,
            mode,
            applyToGroup: false,
          });
          remaining.push(pending);
        } else {
          const guiControl = flock.scene?.UITexture?.getControlByName?.(targetMeshName) ?? null;
          const targetExists = flock.scene?.getMeshByName(targetMeshName) || guiControl;

          if (targetExists) {
            // ✅ Apply to the original target this pending registration was created for.
            flock.onTrigger(targetMeshName, {
              trigger,
              callback,
              mode,
              applyToGroup: false,
            });
          } else {
            remaining.push(pending);
          }
        }
      }

      flock.pendingTriggers.set(groupName, remaining);
    }

    if (flock.pendingIntersections.has(groupName)) {
      const intersections = flock.pendingIntersections.get(groupName);
      for (const pending of intersections) {
        if (meshName !== pending.meshName && !pending.registeredOthers.has(meshName)) {
          pending.registeredOthers.add(meshName);
          flock.onIntersect(pending.meshName, meshName, {
            trigger: pending.trigger,
            callback: pending.callback,
            applyToGroupOther: false,
          });
        }
      }
    }

    if (flock.pendingSelfIntersections.has(groupName)) {
      const newMesh = flock.scene?.getMeshByName(meshName);
      if (newMesh) {
        for (const pending of flock.pendingSelfIntersections.get(groupName)) {
          const existing = flock.scene.meshes.filter(
            (m) => getGroupRoot(m.name) === groupName && m.name !== meshName
          );
          for (const existingMesh of existing) {
            const meshA = existingMesh.uniqueId < newMesh.uniqueId ? existingMesh : newMesh;
            const meshB = meshA === existingMesh ? newMesh : existingMesh;
            const pairKey = `${meshA.uniqueId}|${meshB.uniqueId}`;
            if (!pending.registeredPairs.has(pairKey)) {
              pending.registeredPairs.add(pairKey);
              flock.onIntersect(meshA.name, meshB.name, {
                trigger: pending.trigger,
                callback: pending.callback,
                applyToGroupOther: false,
              });
            }
          }
        }
      }
    }
  },
  /** Reserve a unique name. If desired is taken or pending, suffix it. */
  _reserveName(desired) {
    const has = (n) => flock._nameRegistry.has(n) || !!flock.scene?.getMeshByName(n);
    let name = desired;
    while (has(name)) {
      name = `${desired}_${flock.scene.getUniqueId()}`;
    }
    flock._nameRegistry.set(name, { pending: true, exists: false });
    return name;
  },

  /** Mark a reserved name as created (exists in scene). */
  _markNameCreated(name) {
    const rec = flock._nameRegistry.get(name);
    if (rec) {
      rec.pending = false;
      rec.exists = true;
    }
  },

  /** Release a reservation on failure/disposal. */
  _releaseName(name) {
    flock._nameRegistry.delete(name);
  },

  /**
   * Cache a resolved name → live mesh so whenModelReady can skip per-call
   * scene scans. Meshes only: other target types (GUI controls, animation
   * groups, particle systems) keep using the fallback lookup. Entries are
   * evicted when the mesh is disposed (via onDisposeObservable here, plus
   * a lazy isDisposed check on read) and when a run starts or ends.
   */
  _registerLiveName(name, target) {
    if (!name || !(target instanceof flock.BABYLON.AbstractMesh) || target.isDisposed()) return;
    const cached = flock._liveNameCache.get(name);
    if (cached === target) return; // Already registered with observer
    if (cached && !cached.isDisposed()) {
      flock._liveNameCache.delete(name);
      flock._ambiguousLiveNames ??= new Set();
      flock._ambiguousLiveNames.add(name);
      return;
    }
    if (flock._ambiguousLiveNames?.has(name)) return;
    flock._liveNameCache.set(name, target);
    target.onDisposeObservable.addOnce(() => {
      if (flock._liveNameCache.get(name) === target) {
        flock._liveNameCache.delete(name);
      }
    });
  },

  // Runtime helper
  describeMesh(meshName, text) {
    const safeText = flock.sanitizeInlineText(String(text ?? '').substring(0, 256));
    if (!safeText) return;

    return flock.whenModelReady(meshName, (mesh) => {
      if (!mesh) return;
      const root = mesh.metadata?.boundingBox ?? mesh;
      if (root.metadata) {
        root.metadata.displayName = safeText;
      }
      const setOnChildren = (m) => {
        if (m.metadata) {
          m.metadata.displayName = safeText;
        }
      };
      if (typeof root.getChildMeshes === 'function') {
        root.getChildMeshes(false).forEach(setOnChildren);
      }
    });
  },

  sanitizeInlineText(input) {
    return String(input)
      .replace(/\r?\n/g, ' ')
      .replace(/\*\//g, '*∕')
      .replace(/\/\//g, '∕∕')
      .replace(/`/g, 'ˋ');
  },

  download(filename, data, mimeType) {
    const blob = new Blob([data], { type: mimeType });
    const url = URL.createObjectURL(blob);
    const a = flock.document.createElement('a');
    a.href = url;
    a.download = filename;
    flock.document.body.appendChild(a);
    a.click();
    flock.document.body.removeChild(a);
    URL.revokeObjectURL(url);
  },
};

export function initializeFlock() {
  const scriptElement = flock.document.getElementById('flock');
  if (scriptElement) {
    flock
      .initialize()
      .then(() => {
        flock.modelPath = 'https://flipcomputing.github.io/flock/models/';
        flock.soundPath = 'https://flipcomputing.github.io/flock/sounds/';
        flock.imagePath = 'https://flipcomputing.github.io/flock/images/';
        flock.texturePath = 'https://flipcomputing.github.io/flock/textures/';
        const userCode = scriptElement.textContent;

        flock.runCode(userCode);
      })
      .catch((error) => {
        console.error('Error initializing flock:', error);
      });
  }
}

window.setBPM = flockSound.setBPM;
window.updateListenerPositionAndOrientation = flockSound.updateListenerPositionAndOrientation;
window.speak = flockSound.speak;

document.addEventListener('DOMContentLoaded', () => {
  const scriptElement = document.getElementById('flock');
  if (scriptElement) {
    console.log('Standalone Flock 🐦');
    initializeFlock();

    if (window.hideLoadingScreen && typeof window.hideLoadingScreen === 'function') {
      setTimeout(window.hideLoadingScreen, 1000);
    }
  }
});