@effindomv2/runtime 0.1.0

package/src/bridge/interaction.ts

@@ -0,0 +1,86 @@
+import type {
+  BridgeRuntime,
+  ClipboardWritePayload,
+  EffinDomCallbacks,
+  PointerEventLog,
+  ScrollEventLog,
+} from '../core-types';
+import { enrichClipboardPayload, writeClipboardPayload } from '../clipboard';
+import { createEditorSession, type EditorSession } from './interaction/editor-session';
+import { createBridgeLogs } from './interaction/logs';
+import { handleToString } from './utils/encoding';
+
+export function installCallbacks(runtimeRef: { current: BridgeRuntime | null }): EditorSession {
+  const logs = createBridgeLogs();
+  const editorSession = createEditorSession(runtimeRef, logs);
+
+  const callbacks: EffinDomCallbacks = {
+    onPointerEvent: (handle, eventType) => {
+      const { x, y } = editorSession.getLastPointerPosition();
+      const modifiers = editorSession.getLastPointerModifiers();
+      const entry: PointerEventLog = { handle: handleToString(handle), eventType };
+      logs.pointerEvents.push(entry);
+      window.__effindomCallbacks?.onPointerEventWithCoords?.(
+        eventType,
+        handle,
+        x,
+        y,
+        modifiers,
+      );
+    },
+    onFocusChanged: editorSession.handleFocusChanged,
+    onTextChanged: editorSession.handleTextChanged,
+    onRequestSemanticAnnouncement: editorSession.handleRequestSemanticAnnouncement,
+    onTextReplaced: editorSession.handleTextReplaced,
+    onSelectionChanged: editorSession.handleSelectionChanged,
+    onScroll: (handle, offsetX, offsetY, contentWidth, contentHeight, viewportWidth, viewportHeight) => {
+      const entry: ScrollEventLog = {
+        handle: handleToString(handle),
+        offsetX,
+        offsetY,
+        contentWidth,
+        contentHeight,
+        viewportWidth,
+        viewportHeight,
+      };
+      logs.scrollEvents.push(entry);
+    },
+    onCrossSelectionChanged: (areaHandle, text) => {
+      logs.crossSelectionChanges.push({ areaHandle: handleToString(areaHandle), text });
+    },
+    onClipboardWrite: (payload: ClipboardWritePayload) => {
+      logs.clipboardWrites.push(payload.plainText);
+      const runtime = runtimeRef.current;
+      const enrichedPayload =
+        runtime === null
+          ? payload
+          : enrichClipboardPayload(payload, (fontId) => runtime.getClipboardFontUrl(fontId));
+      void writeClipboardPayload(enrichedPayload).catch(() => undefined);
+    },
+    onClipboardRead: editorSession.handleClipboardRead,
+    onRequestFontLoad: (fontId, url) => {
+      const runtime = runtimeRef.current;
+      if (runtime === null || url.length === 0) {
+        return;
+      }
+      void runtime.loadFont(fontId, url).catch((error: unknown) => {
+        window.__bridgeError = error instanceof Error ? error.message : String(error);
+      });
+    },
+    onMissingFontCoverage: (fontId, coverageKind, sampleText) => {
+      const runtime = runtimeRef.current;
+      if (runtime === null) {
+        return;
+      }
+      logs.missingFontCoverageRequests.push({
+        fontId,
+        coverageKind,
+        sampleText,
+      });
+      runtime.handleMissingFontCoverage(fontId, coverageKind, sampleText);
+    },
+  };
+
+  window.__effindomCallbacks = callbacks;
+  return editorSession;
+}

package/src/bridge/local-types.ts

@@ -0,0 +1,105 @@
+import type { BridgeLoaderInfo, BridgeLogs } from '../core-types';
+
+export type WasmArchitecture = 'auto' | 'wasm32' | 'wasm32-simd' | 'wasm64' | 'wasm64-simd';
+export type RequestedRendererBackend = 'auto' | 'webgpu' | 'webgl2' | 'cpu';
+
+export interface BundleAssetDescriptor {
+  readonly js: string;
+  readonly js_integrity?: string | null;
+  readonly wasm: string;
+  readonly wasm_integrity?: string | null;
+}
+
+export interface SharedAssetDescriptor {
+  readonly url: string;
+  readonly integrity?: string | null;
+}
+
+export interface RuntimeManifest {
+  readonly version: string;
+  readonly manifest_hash?: string | null;
+  readonly architectures: Partial<Record<Exclude<WasmArchitecture, 'auto'>, {
+    readonly core: BundleAssetDescriptor;
+    readonly ui: BundleAssetDescriptor;
+  }>>;
+  readonly assets?: {
+    readonly icu?: SharedAssetDescriptor;
+  };
+}
+
+export interface ArchitectureSelection {
+  readonly requestedArchitecture: WasmArchitecture;
+  readonly selectedArchitecture: Exclude<WasmArchitecture, 'auto'>;
+  readonly availableArchitectures: readonly string[];
+  readonly memory64Supported: boolean;
+  readonly simdSupported: boolean;
+  readonly selectionReason: string;
+  readonly manifestEntry: {
+    readonly core: BundleAssetDescriptor;
+    readonly ui: BundleAssetDescriptor;
+  };
+}
+
+export interface PreparedWasmAsset {
+  readonly url: string;
+  readonly integrity: string | null;
+  readonly bytesPromise: Promise<ArrayBuffer>;
+  readonly modulePromise: Promise<WebAssembly.Module>;
+}
+
+export interface PreparedBinaryAsset {
+  readonly url: string;
+  readonly integrity: string | null;
+  readonly bytesPromise: Promise<Uint8Array>;
+}
+
+export interface PreparedRuntimeAssets {
+  readonly manifest: RuntimeManifest;
+  readonly selection: ArchitectureSelection;
+  readonly loaderInfo: BridgeLoaderInfo;
+  readonly coreBundle: BundleAssetDescriptor;
+  readonly uiBundle: BundleAssetDescriptor;
+  readonly coreWasm: PreparedWasmAsset;
+  readonly uiWasm: PreparedWasmAsset;
+  readonly icu: PreparedBinaryAsset;
+}
+
+export interface BridgeInteractionState {
+  readonly logs: BridgeLogs;
+  readonly textByHandle: Record<string, string>;
+  readonly selectionsByHandle: Record<string, { start: number; end: number }>;
+  hasPendingTextMutations(): boolean;
+  materializePendingTextMutations(): boolean;
+  getActiveTextEditable(): boolean;
+  getActiveTextHandle(): bigint | null;
+  getActiveTextMultiline(): boolean;
+  getCapturedPointerHandle(): bigint | null;
+  getLastPointerClientPosition(): { x: number | null; y: number | null };
+  getLastPointerPosition(): { x: number; y: number };
+  getLastPointerModifiers(): number;
+  getLastInteractivePointerHandle(): bigint | null;
+  isActiveTextInputFocused(): boolean;
+  isPointerInsideCanvas(): boolean;
+  applyActiveTextDeletion(forward: boolean): boolean;
+  beginTouchTextFocusDeferral(handle: bigint): void;
+  cancelTouchTextFocusDeferral(): void;
+  commitTouchTextFocusDeferral(handle: bigint): void;
+  refocusActiveTextInput(): void;
+  resetAppSession(): void;
+  consumePendingSemanticAnnouncements(): readonly string[];
+  getFocusedHandle(): string | null;
+  setCapturedPointerHandle(handle: bigint | null): void;
+  setLastPointerClientPosition(x: number, y: number): void;
+  setLastPointerModifiers(modifiers: number): void;
+  setLastPointerPosition(x: number, y: number): void;
+  setLastInteractivePointerHandle(handle: bigint | null): void;
+  setPointerInsideCanvas(flag: boolean): void;
+}
+
+export interface SoftwarePresenter {
+  canvas: HTMLCanvasElement;
+  ctx: CanvasRenderingContext2D;
+  imageData: ImageData | null;
+  width: number;
+  height: number;
+}

package/src/bridge/platform.ts

@@ -0,0 +1,68 @@
+export enum PlatformFamily {
+  Unknown = 0,
+  Apple = 1,
+  Windows = 2,
+  Linux = 3,
+}
+
+export function isMobileBrowser(): boolean {
+  const navigatorWithUserAgentData = navigator as Navigator & {
+    userAgentData?: {
+      mobile?: boolean;
+    };
+  };
+  if (navigatorWithUserAgentData.userAgentData?.mobile === true) {
+    return true;
+  }
+  if (/Android|iPhone|iPad|iPod|Mobile/i.test(navigator.userAgent)) {
+    return true;
+  }
+  return navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1;
+}
+
+export function detectPlatformFamily(): PlatformFamily {
+  const navigatorWithUserAgentData = navigator as Navigator & {
+    userAgentData?: {
+      platform?: string;
+    };
+  };
+  const platform = (
+    navigatorWithUserAgentData.userAgentData?.platform ??
+    navigator.platform ??
+    navigator.userAgent
+  ).toLowerCase();
+  if (
+    platform.includes('mac') ||
+    platform.includes('iphone') ||
+    platform.includes('ipad') ||
+    platform.includes('ipod') ||
+    platform.includes('ios')
+  ) {
+    return PlatformFamily.Apple;
+  }
+  if (platform.includes('win')) {
+    return PlatformFamily.Windows;
+  }
+  if (
+    platform.includes('linux') ||
+    platform.includes('android') ||
+    platform.includes('x11') ||
+    platform.includes('cros')
+  ) {
+    return PlatformFamily.Linux;
+  }
+  return PlatformFamily.Unknown;
+}
+
+export function isPlatformShortcutKey(
+  event: Pick<KeyboardEvent, 'ctrlKey' | 'metaKey' | 'altKey'>,
+  platformFamily = detectPlatformFamily(),
+): boolean {
+  if (event.altKey) {
+    return false;
+  }
+  if (platformFamily === PlatformFamily.Apple) {
+    return event.metaKey && !event.ctrlKey;
+  }
+  return event.ctrlKey && !event.metaKey;
+}

package/src/bridge/pointer-move-coalescer.ts

@@ -0,0 +1,41 @@
+export class PointerMoveCoalescer<T> {
+  private pendingMove: T | null = null;
+  private frameScheduled = false;
+
+  constructor(private readonly flushMove: (move: T) => void) {}
+
+  enqueue(move: T): void {
+    this.pendingMove = move;
+    this.scheduleFlush();
+  }
+
+  takePending(): T | null {
+    const pending = this.pendingMove;
+    this.pendingMove = null;
+    return pending;
+  }
+
+  clear(): void {
+    this.pendingMove = null;
+  }
+
+  private scheduleFlush(): void {
+    if (this.frameScheduled) {
+      return;
+    }
+    this.frameScheduled = true;
+    requestAnimationFrame(() => {
+      this.frameScheduled = false;
+      const pending = this.pendingMove;
+      this.pendingMove = null;
+      if (pending === null) {
+        return;
+      }
+      this.flushMove(pending);
+      if (this.pendingMove !== null) {
+        this.scheduleFlush();
+      }
+    });
+  }
+}
+

package/src/bridge/pull-to-refresh.ts

@@ -0,0 +1,124 @@
+const PULL_TO_REFRESH_ID = 'effindom-pull-to-refresh';
+const PULL_TO_REFRESH_TRIGGER_DISTANCE = 88;
+const PULL_TO_REFRESH_MAX_TRAVEL = 78;
+
+export const PULL_TO_REFRESH_THRESHOLD = PULL_TO_REFRESH_TRIGGER_DISTANCE;
+
+interface PullToRefreshElements {
+  readonly root: HTMLDivElement;
+  readonly icon: HTMLSpanElement;
+}
+
+function ensurePullToRefreshElements(): PullToRefreshElements {
+  const existing = document.getElementById(PULL_TO_REFRESH_ID);
+  if (existing instanceof HTMLDivElement) {
+    const icon = existing.firstElementChild;
+    if (icon instanceof HTMLSpanElement) {
+      return { root: existing, icon };
+    }
+    existing.remove();
+  }
+
+  const root = document.createElement('div');
+  const icon = document.createElement('span');
+  root.id = PULL_TO_REFRESH_ID;
+  root.hidden = true;
+  root.dataset.visible = 'false';
+  root.dataset.armed = 'false';
+  root.setAttribute('aria-hidden', 'true');
+  root.style.position = 'fixed';
+  root.style.left = '50%';
+  root.style.top = '12px';
+  root.style.width = '48px';
+  root.style.height = '48px';
+  root.style.display = 'flex';
+  root.style.alignItems = 'center';
+  root.style.justifyContent = 'center';
+  root.style.borderRadius = '999px';
+  root.style.background = 'rgba(248, 250, 252, 0.96)';
+  root.style.color = '#0f172a';
+  root.style.boxShadow = '0 10px 28px rgba(15, 23, 42, 0.22)';
+  root.style.backdropFilter = 'blur(12px)';
+  root.style.pointerEvents = 'none';
+  root.style.opacity = '0';
+  root.style.transform = 'translate(-50%, -18px)';
+  root.style.transition = 'opacity 120ms ease, transform 120ms ease';
+  root.style.zIndex = '2147483647';
+
+  icon.textContent = '↻';
+  icon.style.display = 'block';
+  icon.style.font = '600 24px/1 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif';
+  icon.style.transform = 'rotate(0deg)';
+  icon.style.transition = 'transform 90ms linear';
+  root.appendChild(icon);
+  (document.body ?? document.documentElement).appendChild(root);
+  return { root, icon };
+}
+
+export interface PullToRefreshOverlay {
+  show(pullDistance: number): void;
+  hide(immediate?: boolean): void;
+  destroy(): void;
+}
+
+export function createPullToRefreshOverlay(): PullToRefreshOverlay {
+  const { root, icon } = ensurePullToRefreshElements();
+  let visible = false;
+  let hideTimer = 0;
+
+  return {
+    show(pullDistance: number): void {
+      if (hideTimer !== 0) {
+        window.clearTimeout(hideTimer);
+        hideTimer = 0;
+      }
+      visible = true;
+      const distance = Math.max(0, pullDistance);
+      const normalized = Math.max(0, Math.min(distance / PULL_TO_REFRESH_TRIGGER_DISTANCE, 1));
+      const travel = Math.min(distance * 0.75, PULL_TO_REFRESH_MAX_TRAVEL);
+      root.hidden = false;
+      root.dataset.visible = 'true';
+      root.dataset.armed = normalized >= 1 ? 'true' : 'false';
+      root.style.transition = 'none';
+      root.style.opacity = distance <= 0 ? '0' : `${0.15 + (normalized * 0.85)}`;
+      root.style.transform = `translate(-50%, ${travel - 18}px)`;
+      root.style.background = normalized >= 1 ? 'rgba(219, 234, 254, 0.98)' : 'rgba(248, 250, 252, 0.96)';
+      icon.style.transform = `rotate(${Math.round(normalized * 360)}deg)`;
+    },
+    hide(immediate = false): void {
+      if (!visible && root.hidden) {
+        return;
+      }
+      visible = false;
+      root.dataset.visible = 'false';
+      root.dataset.armed = 'false';
+      root.style.transition = immediate
+        ? 'none'
+        : 'opacity 90ms ease-out, transform 90ms ease-out, background 90ms ease-out';
+      root.style.opacity = '0';
+      root.style.transform = 'translate(-50%, -18px)';
+      root.style.background = 'rgba(248, 250, 252, 0.96)';
+      icon.style.transform = 'rotate(0deg)';
+      if (immediate) {
+        if (hideTimer !== 0) {
+          window.clearTimeout(hideTimer);
+          hideTimer = 0;
+        }
+        root.hidden = true;
+        return;
+      }
+      hideTimer = window.setTimeout(() => {
+        if (root.dataset.visible === 'false') {
+          root.hidden = true;
+        }
+        hideTimer = 0;
+      }, 100);
+    },
+    destroy(): void {
+      if (hideTimer !== 0) {
+        window.clearTimeout(hideTimer);
+      }
+      root.remove();
+    },
+  };
+}

package/src/bridge/render-loop.ts

@@ -0,0 +1,268 @@
+import { EdBackendType, EdDeviceState } from '../core-types';
+import type { BridgeLoaderInfo, BridgeRuntime, EdBackendType as EdBackendTypeValue, CoreModule } from '../core-types';
+import type { SoftwarePresenter } from './local-types';
+import { normalizeBackendType, normalizeDeviceState, normalizePointerForWasm, pointerToHeapOffset } from './utils/encoding';
+import { backendLabel, DEFAULT_BACKEND_LADDER, setActiveRenderer, tryReviveBackend } from './utils/backends';
+import { delay } from './utils/assets';
+
+const DEVICE_LOST_RETRY_DELAYS_MS = [500, 1_000, 2_000, 4_000] as const;
+
+function ensureSoftwarePresenter(
+  presenter: SoftwarePresenter | null,
+  canvas: HTMLCanvasElement,
+): SoftwarePresenter {
+  if (presenter !== null) {
+    return presenter;
+  }
+  const overlay = document.createElement('canvas');
+  overlay.dataset.effindomSoftwareOverlay = 'true';
+  overlay.setAttribute('aria-hidden', 'true');
+  overlay.style.position = 'absolute';
+  overlay.style.pointerEvents = 'none';
+  overlay.style.display = 'none';
+  overlay.style.zIndex = '1';
+
+  const parent = canvas.parentElement;
+  if (parent !== null) {
+    if (getComputedStyle(parent).position === 'static') {
+      parent.style.position = 'relative';
+    }
+    parent.appendChild(overlay);
+  } else {
+    document.body.appendChild(overlay);
+  }
+
+  const ctx = overlay.getContext('2d');
+  if (ctx === null) {
+    throw new Error('Canvas 2D context is unavailable for software rendering.');
+  }
+  return {
+    canvas: overlay,
+    ctx,
+    imageData: null,
+    width: 0,
+    height: 0,
+  };
+}
+
+function presentSoftwareFrame(
+  core: CoreModule,
+  canvas: HTMLCanvasElement,
+  presenter: SoftwarePresenter,
+): void {
+  const ptr = normalizePointerForWasm(core, core._ed_get_sw_framebuffer());
+  const offset = pointerToHeapOffset(ptr);
+  if (offset === 0) {
+    return;
+  }
+  presenter.canvas.style.left = `${String(canvas.offsetLeft)}px`;
+  presenter.canvas.style.top = `${String(canvas.offsetTop)}px`;
+  presenter.canvas.style.width = canvas.style.width || `${String(canvas.clientWidth)}px`;
+  presenter.canvas.style.height = canvas.style.height || `${String(canvas.clientHeight)}px`;
+  presenter.canvas.style.borderRadius = getComputedStyle(canvas).borderRadius;
+  presenter.canvas.style.display = '';
+  if (presenter.imageData === null || presenter.width !== canvas.width || presenter.height !== canvas.height) {
+    presenter.canvas.width = canvas.width;
+    presenter.canvas.height = canvas.height;
+    presenter.imageData = presenter.ctx.createImageData(canvas.width, canvas.height);
+    presenter.width = canvas.width;
+    presenter.height = canvas.height;
+  }
+  const byteLength = canvas.width * canvas.height * 4;
+  const src = core.HEAPU8.subarray(offset, offset + byteLength);
+  presenter.imageData.data.set(src);
+  presenter.ctx.putImageData(presenter.imageData, 0, 0);
+}
+
+export function installRenderLoop(
+  runtime: BridgeRuntime,
+  loaderInfo: BridgeLoaderInfo,
+  fallbackLadder: readonly EdBackendTypeValue[] = DEFAULT_BACKEND_LADDER,
+): () => void {
+  const { core, canvas } = runtime;
+  let activeBackend = normalizeBackendType(core._ed_get_backend_type());
+  let softwarePresenter: SoftwarePresenter | null = null;
+  let frameScheduled = false;
+  let disposed = false;
+
+  // Recovery state:
+  // - lastAttemptedBackend  the backend we're trying to revive (set on first loss,
+  //                         kept after a permanent fallback so wake-up can try again)
+  // - recoveryAttempts      how many retries of lastAttemptedBackend have been tried
+  // - recoveryExhausted     true after all retries failed and we permanently fell back
+  // - recoveryPromise       non-null while an async recovery cycle is in progress
+  let lastAttemptedBackend: EdBackendTypeValue = activeBackend;
+  let recoveryAttempts = 0;
+  let recoveryExhausted = false;
+  let recoveryPromise: Promise<void> | null = null;
+
+  // Retry the same backend with exponential backoff, then permanently fall back.
+  // Mutates recoveryAttempts, recoveryExhausted, activeBackend.
+  async function runRecovery(): Promise<void> {
+    const dpr = Math.max(1, window.devicePixelRatio || 1);
+
+    while (recoveryAttempts < DEVICE_LOST_RETRY_DELAYS_MS.length) {
+      const delayMs = DEVICE_LOST_RETRY_DELAYS_MS[recoveryAttempts] as number;
+      await delay(delayMs);
+
+      if (await tryReviveBackend(core, canvas, dpr, lastAttemptedBackend)) {
+        recoveryAttempts = 0;
+        recoveryExhausted = false;
+        activeBackend = lastAttemptedBackend;
+        loaderInfo.deviceRecoveryCount += 1;
+        setActiveRenderer(loaderInfo, lastAttemptedBackend);
+        await runtime.replayLoadedAssets();
+        console.info(`RENDERER RECOVERY: ${backendLabel(lastAttemptedBackend)} recovered successfully.`);
+        runtime.commitFrame();
+        return;
+      }
+
+      recoveryAttempts += 1;
+    }
+
+    // All retries exhausted — permanently fall to the next available backend.
+    recoveryExhausted = true;
+    const nextIndex = fallbackLadder.indexOf(lastAttemptedBackend) + 1;
+    for (let i = nextIndex; i < fallbackLadder.length; i += 1) {
+      const fallback = fallbackLadder[i]!;
+      if (await tryReviveBackend(core, canvas, dpr, fallback)) {
+        activeBackend = fallback;
+        loaderInfo.deviceRecoveryCount += 1;
+        setActiveRenderer(loaderInfo, fallback);
+        await runtime.replayLoadedAssets();
+        if (fallback === EdBackendType.CPU) {
+          console.error(
+            `RENDERER FALLBACK: ${backendLabel(lastAttemptedBackend)} device lost and recovery failed!` +
+            ' Fell back to Software/Raster - performance will be painfully slow',
+          );
+        } else {
+          console.warn(
+            `RENDERER FALLBACK: ${backendLabel(lastAttemptedBackend)} device lost and recovery failed!` +
+            ` Fell back to ${backendLabel(fallback)}`,
+          );
+        }
+        runtime.commitFrame();
+        return;
+      }
+    }
+
+    throw new Error(
+      `Renderer recovery failed: all backends exhausted after ${backendLabel(lastAttemptedBackend)} device loss.`,
+    );
+  }
+
+  function scheduleRecovery(lostBackend: EdBackendTypeValue): void {
+    if (recoveryPromise !== null) return;
+    lastAttemptedBackend = lostBackend;
+    recoveryAttempts = 0;
+    recoveryExhausted = false;
+    setActiveRenderer(loaderInfo, EdBackendType.NONE);
+    recoveryPromise = runRecovery()
+      .catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error);
+        window.__bridgeError = message;
+      })
+      .finally(() => {
+        recoveryPromise = null;
+      });
+  }
+
+  const scheduleFrame = (): void => {
+    if (disposed) {
+      return;
+    }
+    if (frameScheduled) {
+      return;
+    }
+    frameScheduled = true;
+    requestAnimationFrame(frame);
+  };
+
+  runtime.setFrameRequester(scheduleFrame);
+
+  const handleWebGlContextLost = (event: Event): void => {
+    event.preventDefault();
+    core._ed_notify_webgl_context_lost?.();
+    scheduleRecovery(activeBackend);
+    scheduleFrame();
+  };
+  canvas.addEventListener('webglcontextlost', handleWebGlContextLost, false);
+
+  // When the page becomes visible after being hidden (e.g. lid open after sleep),
+  // the GPU may have recovered. If a previous recovery cycle exhausted all retries
+  // and permanently fell back, optimistically try to revive the original backend.
+  const handleVisibilityChange = (): void => {
+    if (disposed) return;
+    if (document.visibilityState !== 'visible') return;
+    if (!recoveryExhausted) return;
+    if (recoveryPromise !== null) return;
+    console.info(
+      `RENDERER RECOVERY: Page visible — attempting to revive ${backendLabel(lastAttemptedBackend)} after sleep/wake.`,
+    );
+    recoveryAttempts = 0;
+    recoveryPromise = runRecovery()
+      .catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error);
+        window.__bridgeError = message;
+      })
+      .finally(() => {
+        recoveryPromise = null;
+      });
+  };
+  document.addEventListener('visibilitychange', handleVisibilityChange);
+
+  const frame = (now: number): void => {
+    if (disposed) {
+      frameScheduled = false;
+      return;
+    }
+    frameScheduled = false;
+    if (recoveryPromise !== null) {
+      scheduleFrame();
+      return;
+    }
+    // Rebuild heap views from the live WebAssembly.Memory buffer each frame.
+    // Emscripten updates closure-scoped heap vars on memory growth but not
+    // Module['HEAPU8'], leaving it pointing to a detached ArrayBuffer.
+    // Reading module.wasmMemory.buffer always returns the current live buffer.
+    core.refreshHeapViews?.();
+    runtime.ui.refreshHeapViews?.();
+    runtime.runAppFrameHandler(now);
+    if (!runtime.hasPendingCommit() && runtime.uiNeedsAnimationFrame() && runtime.uiHasPendingVisualWork()) {
+      runtime.commitFrame();
+    }
+    runtime.flushPendingCommit();
+    core._ed_render_frame(now);
+    core.refreshHeapViews?.();   // Ensure heap views are up‑to‑date after potential memory growth
+    const deviceState = normalizeDeviceState(core._ed_get_device_state());
+    const backendType = normalizeBackendType(core._ed_get_backend_type());
+    if (deviceState === EdDeviceState.LOST) {
+      scheduleRecovery(activeBackend);
+      scheduleFrame();
+      return;
+    }
+    activeBackend = backendType;
+    setActiveRenderer(loaderInfo, backendType);
+    if (backendType === EdBackendType.CPU) {
+      softwarePresenter = ensureSoftwarePresenter(softwarePresenter, canvas);
+      presentSoftwareFrame(core, canvas, softwarePresenter);
+    } else if (softwarePresenter !== null) {
+      softwarePresenter.canvas.style.display = 'none';
+    }
+    if (runtime.hasPendingCommit() || runtime.uiNeedsAnimationFrame()) {
+      scheduleFrame();
+    }
+  };
+  scheduleFrame();
+  return () => {
+    disposed = true;
+    frameScheduled = false;
+    runtime.setFrameRequester(null);
+    canvas.removeEventListener('webglcontextlost', handleWebGlContextLost, false);
+    document.removeEventListener('visibilitychange', handleVisibilityChange);
+    if (softwarePresenter !== null) {
+      softwarePresenter.canvas.remove();
+      softwarePresenter = null;
+    }
+  };
+}