app.js

// SPDX-License-Identifier: AGPL-3.0-or-later
// app.js
  import { BrowserApp } from './browser.js';
  import { instrumentBrowserApp } from './browser-debug.js';
  import { BrowserBoxClient } from './browserbox-client.js';
  import { networkExplorerAppDefinition } from './network-explorer.js';
  import { notepadAppDefinition } from './notepad.js';
  import { calculatorAppDefinition } from './calculator.js';
  import { recycleBinAppDefinition } from './recycle-bin.js';
  import { soundManager } from './sound-manager.js';
  import { sessionTimer } from './session-timer.js';

  const imageViewerAppDefinition = {
      title: "Image Viewer",
      icon: "./template_world-4.png",
      defaultWidth: 500,
      defaultHeight: 420,
      content: () => `
          <div style="display:flex; flex-direction:column; height:100%; background:#c0c0c0;">
              <div class="image-viewer-caption" style="padding:4px 6px; border-bottom:1px solid #808080; font-size:11px;">
                  No image loaded.
              </div>
              <div style="flex:1; margin:4px; border:2px inset #808080; background:#fff; display:flex; align-items:center; justify-content:center; overflow:auto;">
                  <img class="image-viewer-image" alt="" style="max-width:100%; max-height:100%; image-rendering:auto; display:none;">
                  <div class="image-viewer-empty" style="font-size:11px; color:#555;">No image data available.</div>
              </div>
          </div>
      `,
      initApp: (windowEl, windowInstanceId, webviewId, appDefinition, appInstanceSpecificData, launchData) => {
          const imageEl = windowEl.querySelector('.image-viewer-image');
          const emptyEl = windowEl.querySelector('.image-viewer-empty');
          const captionEl = windowEl.querySelector('.image-viewer-caption');
          const titleEl = windowEl.querySelector('.window-title');
          const imageUrl = launchData && typeof launchData.imageUrl === 'string' ? launchData.imageUrl : '';
          const fileName = launchData && typeof launchData.fileName === 'string' && launchData.fileName.trim()
              ? launchData.fileName.trim()
              : 'Bitmap Image';

          if (captionEl) captionEl.textContent = fileName;
          if (titleEl) titleEl.textContent = `${fileName} - Image Viewer`;

          if (!imageEl || !emptyEl || !imageUrl) {
              return;
          }

          imageEl.onload = () => {
              imageEl.style.display = 'block';
              emptyEl.style.display = 'none';
          };
          imageEl.onerror = () => {
              imageEl.style.display = 'none';
              emptyEl.style.display = 'block';
              emptyEl.textContent = 'Could not load this image.';
          };
          imageEl.src = imageUrl;
      },
  };

  const wavePlayerAppDefinition = {
      title: "Wave Player",
      icon: "./loudspeaker_rays-1.png",
      defaultWidth: 420,
      defaultHeight: 170,
      content: () => `
          <div style="display:flex; flex-direction:column; height:100%; background:#c0c0c0; padding:8px; box-sizing:border-box;">
              <div class="wave-player-caption" style="font-size:11px; margin-bottom:8px;">No wave loaded.</div>
              <div style="border:2px inset #808080; background:#fff; padding:8px;">
                  <audio class="wave-player-audio" controls style="width:100%;"></audio>
                  <div class="wave-player-empty" style="font-size:11px; color:#555; margin-top:6px;">No audio data available.</div>
              </div>
          </div>
      `,
      initApp: (windowEl, windowInstanceId, webviewId, appDefinition, appInstanceSpecificData, launchData) => {
          const audioEl = windowEl.querySelector('.wave-player-audio');
          const emptyEl = windowEl.querySelector('.wave-player-empty');
          const captionEl = windowEl.querySelector('.wave-player-caption');
          const titleEl = windowEl.querySelector('.window-title');
          const audioUrl = launchData && typeof launchData.audioUrl === 'string' ? launchData.audioUrl : '';
          const fileName = launchData && typeof launchData.fileName === 'string' && launchData.fileName.trim()
              ? launchData.fileName.trim()
              : 'Wave Sound';

          if (captionEl) captionEl.textContent = fileName;
          if (titleEl) titleEl.textContent = `${fileName} - Wave Player`;

          if (!audioEl || !emptyEl || !audioUrl) {
              return;
          }

          audioEl.src = audioUrl;
          emptyEl.style.display = 'none';
          audioEl.addEventListener('error', () => {
              emptyEl.style.display = 'block';
              emptyEl.textContent = 'Could not load this wave file.';
          });
      },
  };

  const FOLDER_VIEW_LAYOUT_POSITIONS_KEY = 'folderViewLayoutPositions_win9x_v1';
  const FOLDER_VIEW_GRID_SIZE_X = 85;
  const FOLDER_VIEW_GRID_SIZE_Y = 87;
  const FOLDER_VIEW_GRID_PADDING = 8;
  const FOLDER_CONTEXT_NEW_TYPES = [
      { type: 'folder', label: 'Folder', icon: './directory_closed_cool-0.png' },
      { type: 'shortcut', label: 'Shortcut', icon: './file_win_shortcut-0.png' },
      { type: 'textDocument', label: 'Text Document', icon: './document-0.png' },
      { type: 'bitmapImage', label: 'Bitmap Image', icon: './paint_file-2.png' },
      { type: 'waveSound', label: 'Wave Sound', icon: './loudspeaker_wave-0.png' },
  ];

  const folderViewerAppDefinition = {
      title: "Folder",
      icon: "./directory_closed_cool-0.png",
      defaultWidth: 500,
      defaultHeight: 340,
      content: () => `
          <div style="display:flex; flex-direction:column; height:100%; background:#c0c0c0;">
              <div class="folder-viewer-caption" style="padding:4px 6px; border-bottom:1px solid #808080; font-size:11px;">Folder</div>
              <div style="padding:4px 6px; border-bottom:1px solid #a0a0a0;">
                  <button class="win95-button folder-viewer-refresh-btn" style="min-width:72px;">Refresh</button>
                  <button class="win95-button folder-viewer-rename-btn" style="min-width:72px;">Rename</button>
              </div>
              <div class="folder-viewer-list desktop-slice-canvas desktop-slice-canvas-positioned" style="flex:1; margin:4px; border:2px inset #808080; background:#fff; overflow:auto;"></div>
              <div class="folder-viewer-status" style="padding:3px 6px; border-top:1px solid #808080; font-size:11px;">0 item(s)</div>
          </div>
      `,
      initApp: (windowEl, windowInstanceId, webviewId, appDefinition, appInstanceSpecificData, launchData) => {
          const captionEl = windowEl.querySelector('.folder-viewer-caption');
          const listEl = windowEl.querySelector('.folder-viewer-list');
          const statusEl = windowEl.querySelector('.folder-viewer-status');
          const refreshBtn = windowEl.querySelector('.folder-viewer-refresh-btn');
          const renameBtn = windowEl.querySelector('.folder-viewer-rename-btn');
          const titleEl = windowEl.querySelector('.window-title');
          const folderId = launchData && typeof launchData.folderId === 'string' ? launchData.folderId : null;
          const desktopEl = document.getElementById('desktop');
          const recycleBinApi = window.APP_DEFINITIONS?.recycleBin?.api || null;
          const selectedItemIds = new Set();
          let activeSurfaceDrag = null;
          let activeFolderDropTarget = null;
          let activeRenameSession = null;
          let isMarqueeSelecting = false;
          let marqueeElement = null;
          let marqueeStartX = 0;
          let marqueeStartY = 0;
          let marqueePointerId = null;
          let listRectCache = null;
          let activeDragGhostEl = null;
          let folderArrangeMode = 'name';
          let lastRenderedItemCount = 0;
          const FOLDER_DRAG_AUTO_SCROLL_EDGE = 24;
          const FOLDER_DRAG_AUTO_SCROLL_STEP = 18;
          const preventNativeImageDragStart = (event) => {
              if (event && event.target && event.target.closest && event.target.closest('.folder-viewer-item img')) {
                  event.preventDefault();
              }
          };
          const handleDesktopItemsChanged = () => {
              renderItems();
          };

          function getFolderLayoutStore() {
              try {
                  const raw = localStorage.getItem(FOLDER_VIEW_LAYOUT_POSITIONS_KEY);
                  const parsed = raw ? JSON.parse(raw) : {};
                  return (parsed && typeof parsed === 'object') ? parsed : {};
              } catch (error) {
                  console.error('FolderViewer: failed to load layout store:', error);
                  return {};
              }
          }

          function saveFolderLayoutStore(store) {
              try {
                  localStorage.setItem(FOLDER_VIEW_LAYOUT_POSITIONS_KEY, JSON.stringify(store));
              } catch (error) {
                  console.error('FolderViewer: failed to save layout store:', error);
              }
          }

          function getLayoutForFolder(targetFolderId) {
              if (!targetFolderId) return {};
              const store = getFolderLayoutStore();
              const folderLayout = store[targetFolderId];
              return (folderLayout && typeof folderLayout === 'object') ? { ...folderLayout } : {};
          }

          function saveLayoutForFolder(targetFolderId, layout) {
              if (!targetFolderId) return;
              const store = getFolderLayoutStore();
              store[targetFolderId] = { ...(layout || {}) };
              saveFolderLayoutStore(store);
          }

          function removeLayoutEntry(targetFolderId, itemId) {
              if (!targetFolderId || !itemId) return;
              const store = getFolderLayoutStore();
              const folderLayout = store[targetFolderId];
              if (!folderLayout || typeof folderLayout !== 'object' || !folderLayout[itemId]) return;
              delete folderLayout[itemId];
              store[targetFolderId] = folderLayout;
              saveFolderLayoutStore(store);
          }

          function buildOccupiedCells(layout, excludedItemId = null) {
              const occupied = new Set();
              Object.entries(layout || {}).forEach(([itemId, pos]) => {
                  if (excludedItemId && itemId === excludedItemId) return;
                  if (!pos || typeof pos.x !== 'number' || typeof pos.y !== 'number') return;
                  const col = Math.max(0, Math.round((pos.x - FOLDER_VIEW_GRID_PADDING) / FOLDER_VIEW_GRID_SIZE_X));
                  const row = Math.max(0, Math.round((pos.y - FOLDER_VIEW_GRID_PADDING) / FOLDER_VIEW_GRID_SIZE_Y));
                  occupied.add(`${row}_${col}`);
              });
              return occupied;
          }

          function getFolderGridMetrics() {
              const innerWidth = Math.max(1, listEl.clientWidth - (2 * FOLDER_VIEW_GRID_PADDING));
              const maxCols = Math.max(1, Math.floor(innerWidth / FOLDER_VIEW_GRID_SIZE_X));
              return { maxCols };
          }

          function findNextFreeCell(startRow, startCol, occupied, maxCols) {
              const initialRow = Math.max(0, startRow);
              const initialCol = Math.max(0, Math.min(maxCols - 1, startCol));
              const maxScanRows = Math.max(300, Math.ceil((occupied.size + 24) / maxCols) + 120);

              for (let depth = 0; depth < maxScanRows; depth += 1) {
                  for (let colOffset = 0; colOffset < maxCols; colOffset += 1) {
                      const col = (initialCol + colOffset) % maxCols;
                      const row = depth + (colOffset === 0 ? initialRow : 0);
                      const key = `${row}_${col}`;
                      if (!occupied.has(key)) {
                          return { row, col };
                      }
                  }
              }

              return { row: initialRow, col: initialCol };
          }

          function snapFolderPosition(rawX, rawY, layout, excludedItemId = null) {
              const { maxCols } = getFolderGridMetrics();
              const preferredCol = Math.max(0, Math.min(maxCols - 1, Math.round((rawX - FOLDER_VIEW_GRID_PADDING) / FOLDER_VIEW_GRID_SIZE_X)));
              const preferredRow = Math.max(0, Math.round((rawY - FOLDER_VIEW_GRID_PADDING) / FOLDER_VIEW_GRID_SIZE_Y));
              const occupied = buildOccupiedCells(layout, excludedItemId);
              const cell = findNextFreeCell(preferredRow, preferredCol, occupied, maxCols);
              return {
                  x: FOLDER_VIEW_GRID_PADDING + (cell.col * FOLDER_VIEW_GRID_SIZE_X),
                  y: FOLDER_VIEW_GRID_PADDING + (cell.row * FOLDER_VIEW_GRID_SIZE_Y),
              };
          }

          function applySliceSelectionVisuals(iconEl) {
              if (!iconEl) return;
              iconEl.classList.add('selected');
              const iconImg = iconEl.querySelector('img');
              if (iconImg && window.IconSelectionEffect && typeof window.IconSelectionEffect.applySelectionEffect === 'function') {
                  window.IconSelectionEffect.applySelectionEffect(iconImg);
              }
          }

          function removeSliceSelectionVisuals(iconEl) {
              if (!iconEl) return;
              iconEl.classList.remove('selected');
              const iconImg = iconEl.querySelector('img');
              if (iconImg && window.IconSelectionEffect && typeof window.IconSelectionEffect.removeSelectionEffect === 'function') {
                  window.IconSelectionEffect.removeSelectionEffect(iconImg);
              }
          }

          function getVisibleFolderIcons() {
              return Array.from(listEl.querySelectorAll('.folder-viewer-item[data-item-id]'));
          }

          function formatItemCount(count) {
              return `${count} item${count === 1 ? '' : 's'}`;
          }

          function updateStatusSummary(totalCount = null) {
              if (!statusEl) return;
              const total = typeof totalCount === 'number' ? totalCount : lastRenderedItemCount;
              const selected = selectedItemIds.size;
              if (selected > 0 && total > 0) {
                  statusEl.textContent = `${formatItemCount(total)}, ${selected} selected`;
              } else {
                  statusEl.textContent = formatItemCount(total);
              }
          }

          function clearFolderDropTargetHighlight() {
              if (window.Win9xDesktopUtils && typeof window.Win9xDesktopUtils.clearDropTargetHighlight === 'function') {
                  activeFolderDropTarget = window.Win9xDesktopUtils.clearDropTargetHighlight(activeFolderDropTarget, {
                      removeSelectionVisual: removeSliceSelectionVisuals,
                      isSelected: (target) => {
                          if (!target || !target.element) return false;
                          if (target.kind === 'folder-viewer-item') {
                              return !!target.itemId && selectedItemIds.has(target.itemId);
                          }
                          return target.element.classList.contains('selected');
                      },
                  });
                  return;
              }

              if (!activeFolderDropTarget || !activeFolderDropTarget.element) {
                  activeFolderDropTarget = null;
                  return;
              }

              const target = activeFolderDropTarget;
              target.element.classList.remove('folder-drop-target');
              if (target.kind === 'desktop-folder-icon' || target.kind === 'recycle-bin-icon') {
                  target.element.classList.remove('drop-target');
              }
              if (
                  target.appliedSelectionVisual &&
                  !(target.kind === 'folder-viewer-item' && target.itemId && selectedItemIds.has(target.itemId))
              ) {
                  removeSliceSelectionVisuals(target.element);
                  if (target.kind === 'desktop-folder-icon' || target.kind === 'recycle-bin-icon') {
                      target.element.classList.remove('selected');
                  }
              }
              activeFolderDropTarget = null;
          }

          function setFolderDropTargetHighlight(nextTarget) {
              if (window.Win9xDesktopUtils && typeof window.Win9xDesktopUtils.setDropTargetHighlight === 'function') {
                  activeFolderDropTarget = window.Win9xDesktopUtils.setDropTargetHighlight(activeFolderDropTarget, nextTarget, {
                      applySelectionVisual: applySliceSelectionVisuals,
                      removeSelectionVisual: removeSliceSelectionVisuals,
                      isSelected: (target) => {
                          if (!target || !target.element) return false;
                          if (target.kind === 'folder-viewer-item') {
                              return !!target.itemId && selectedItemIds.has(target.itemId);
                          }
                          return target.element.classList.contains('selected');
                      },
                      // Keep folder-list as implicit drop region only (no visual block highlight).
                      highlightKinds: ['folder-viewer-item', 'desktop-folder-icon', 'recycle-bin-icon'],
                      selectionKinds: ['folder-viewer-item', 'desktop-folder-icon', 'recycle-bin-icon'],
                  });
                  return;
              }

              if (
                  activeFolderDropTarget &&
                  nextTarget &&
                  activeFolderDropTarget.element === nextTarget.element &&
                  activeFolderDropTarget.folderId === nextTarget.folderId &&
                  activeFolderDropTarget.kind === nextTarget.kind
              ) {
                  return;
              }

              clearFolderDropTargetHighlight();
              if (!nextTarget || !nextTarget.element) {
                  return;
              }

              if (nextTarget.kind !== 'folder-list') {
                  nextTarget.element.classList.add('folder-drop-target');
              }
              if (nextTarget.kind === 'desktop-folder-icon' || nextTarget.kind === 'recycle-bin-icon') {
                  nextTarget.element.classList.add('drop-target');
              }
              if (nextTarget.kind === 'folder-viewer-item' || nextTarget.kind === 'desktop-folder-icon' || nextTarget.kind === 'recycle-bin-icon') {
                  const alreadySelected = nextTarget.kind === 'folder-viewer-item'
                      ? !!nextTarget.itemId && selectedItemIds.has(nextTarget.itemId)
                      : nextTarget.element.classList.contains('selected');
                  if (!alreadySelected) {
                      applySliceSelectionVisuals(nextTarget.element);
                      nextTarget.appliedSelectionVisual = true;
                  } else {
                      nextTarget.appliedSelectionVisual = false;
                  }
              }
              activeFolderDropTarget = nextTarget;
          }

          function getFolderIconByItemId(itemId) {
              const icons = listEl.querySelectorAll('.folder-viewer-item[data-item-id]');
              for (const iconEl of icons) {
                  if (iconEl.dataset.itemId === itemId) {
                      return iconEl;
                  }
              }
              return null;
          }

          function getSingleSelectedItemId() {
              if (selectedItemIds.size !== 1) return null;
              for (const itemId of selectedItemIds) {
                  return itemId;
              }
              return null;
          }

          function clearSelection() {
              selectedItemIds.forEach((itemId) => {
                  const iconEl = getFolderIconByItemId(itemId);
                  if (iconEl) {
                      removeSliceSelectionVisuals(iconEl);
                  }
              });
              selectedItemIds.clear();
              syncRenameButtonState();
              updateStatusSummary();
          }

          function selectIcon(iconEl, isAdditive = false) {
              if (!iconEl) return;
              const itemId = iconEl.dataset.itemId;
              if (!itemId) return;
              if (!isAdditive) {
                  clearSelection();
              }
              if (!selectedItemIds.has(itemId)) {
                  selectedItemIds.add(itemId);
                  applySliceSelectionVisuals(iconEl);
              }
              syncRenameButtonState();
              updateStatusSummary();
          }

          function toggleSelectIcon(iconEl) {
              if (!iconEl) return;
              const itemId = iconEl.dataset.itemId;
              if (!itemId) return;
              if (selectedItemIds.has(itemId)) {
                  selectedItemIds.delete(itemId);
                  removeSliceSelectionVisuals(iconEl);
              } else {
                  selectedItemIds.add(itemId);
                  applySliceSelectionVisuals(iconEl);
              }
              syncRenameButtonState();
              updateStatusSummary();
          }

          function syncRenameButtonState() {
              if (!renameBtn) return;
              const selectedItemId = getSingleSelectedItemId();
              const canRename = !!selectedItemId && !(activeRenameSession && activeRenameSession.itemId === selectedItemId);
              renameBtn.disabled = !canRename;
          }

          function finalizeActiveRename(shouldCommit = true) {
              if (!activeRenameSession) return;
              const session = activeRenameSession;
              activeRenameSession = null;

              const { iconEl, labelEl, inputEl, itemId, originalName } = session;
              if (!iconEl || !labelEl || !inputEl) {
                  syncRenameButtonState();
                  return;
              }

              let finalName = originalName;
              if (shouldCommit && window.Win9xDesktopItems && typeof window.Win9xDesktopItems.renameItem === 'function') {
                  const proposedName = (inputEl.value || '').trim();
                  if (proposedName) {
                      const renamed = window.Win9xDesktopItems.renameItem(itemId, proposedName);
                      if (typeof renamed === 'string' && renamed.trim()) {
                          finalName = renamed.trim();
                      } else {
                          finalName = proposedName;
                      }
                  }
              }

              if (inputEl.parentNode) {
                  inputEl.parentNode.removeChild(inputEl);
              }
              labelEl.style.display = '';
              labelEl.textContent = finalName;
              iconEl.classList.remove('renaming');
              syncRenameButtonState();
          }

          function beginRenameSelectedItem() {
              const selectedItemId = getSingleSelectedItemId();
              if (!selectedItemId || !listEl || activeSurfaceDrag || isMarqueeSelecting) return;
              const iconEl = getFolderIconByItemId(selectedItemId);
              if (!iconEl) return;
              if (activeRenameSession && activeRenameSession.itemId === selectedItemId) return;

              finalizeActiveRename(true);
              const labelEl = iconEl.querySelector('span');
              if (!labelEl) return;

              const inputEl = document.createElement('input');
              inputEl.type = 'text';
              inputEl.className = 'desktop-icon-rename-input';
              inputEl.value = labelEl.textContent || '';
              inputEl.maxLength = 128;

              iconEl.classList.add('renaming');
              labelEl.style.display = 'none';
              iconEl.appendChild(inputEl);

              activeRenameSession = {
                  iconEl,
                  labelEl,
                  inputEl,
                  itemId: selectedItemId,
                  originalName: labelEl.textContent || '',
              };

              inputEl.addEventListener('pointerdown', (e) => e.stopPropagation());
              inputEl.addEventListener('click', (e) => e.stopPropagation());
              inputEl.addEventListener('keydown', (e) => {
                  if (e.key === 'Enter') {
                      e.preventDefault();
                      e.stopPropagation();
                      finalizeActiveRename(true);
                  } else if (e.key === 'Escape') {
                      e.preventDefault();
                      e.stopPropagation();
                      finalizeActiveRename(false);
                  }
              });
              inputEl.addEventListener('blur', () => finalizeActiveRename(true));

              requestAnimationFrame(() => {
                  if (!activeRenameSession || activeRenameSession.inputEl !== inputEl) return;
                  inputEl.focus();
                  inputEl.select();
              });
              syncRenameButtonState();
          }

          function resolveFolderDropTargetAtPoint(clientX, clientY, draggedIcons = null) {
              if (window.Win9xDesktopUtils && typeof window.Win9xDesktopUtils.resolveFolderDropTargetAtPoint === 'function') {
                  return window.Win9xDesktopUtils.resolveFolderDropTargetAtPoint(clientX, clientY, draggedIcons, {
                      includeRecycleBin: true,
                      recycleBinApi,
                  });
              }

              const draggedIconSet = new Set(
                  Array.from(draggedIcons || []).filter((icon) => !!icon && icon.nodeType === 1)
              );
              const draggedItemIds = new Set(
                  Array.from(draggedIconSet)
                      .map((icon) => icon.dataset ? (icon.dataset.desktopItemId || icon.dataset.itemId || null) : null)
                      .filter((itemId) => typeof itemId === 'string' && itemId)
              );
              const hitStack = typeof document.elementsFromPoint === 'function'
                  ? document.elementsFromPoint(clientX, clientY)
                  : [document.elementFromPoint(clientX, clientY)];
              const hitElement = hitStack.find((candidate) => {
                  if (!candidate) return false;
                  const hitsDraggedIcon = Array.from(draggedIconSet).some((draggedIcon) => draggedIcon.contains(candidate));
                  if (hitsDraggedIcon) return false;
                  return true;
              });
              if (!hitElement) {
                  return null;
              }

              const folderRow = hitElement.closest('.folder-viewer-item[data-item-id]');
              if (folderRow && folderRow.dataset && folderRow.dataset.itemType === 'folder') {
                  const targetFolderId = folderRow.dataset.itemId;
                  if (targetFolderId && !draggedItemIds.has(targetFolderId)) {
                      return {
                          folderId: targetFolderId,
                          element: folderRow,
                          itemId: targetFolderId,
                          kind: 'folder-viewer-item',
                      };
                  }
              }

              const folderList = hitElement.closest('.folder-viewer-list[data-folder-id]');
              if (folderList && folderList.dataset) {
                  const targetFolderId = folderList.dataset.folderId;
                  if (targetFolderId && !draggedItemIds.has(targetFolderId)) {
                      return { folderId: targetFolderId, element: folderList, kind: 'folder-list' };
                  }
              }

              const folderIcon = hitElement.closest('.desktop-icon[data-item-type="folder"][data-desktop-item-id]');
              if (folderIcon && folderIcon.dataset) {
                  const targetFolderId = folderIcon.dataset.desktopItemId;
                  if (targetFolderId && !draggedItemIds.has(targetFolderId)) {
                      return {
                          folderId: targetFolderId,
                          element: folderIcon,
                          itemId: targetFolderId,
                          kind: 'desktop-folder-icon',
                      };
                  }
              }

              const recycleBinIcon = hitElement.closest('.desktop-icon[data-app-id="recycleBin"]');
              if (recycleBinIcon && recycleBinApi && typeof recycleBinApi.addItem === 'function') {
                  return {
                      folderId: null,
                      element: recycleBinIcon,
                      kind: 'recycle-bin-icon',
                  };
              }

              return null;
          }

          function updateFolderCanvasExtent(layout, children) {
              const maxRight = children.reduce((acc, item) => {
                  const pos = layout[item.id];
                  if (!pos || typeof pos.x !== 'number') return acc;
                  return Math.max(acc, pos.x + 75 + FOLDER_VIEW_GRID_PADDING);
              }, listEl.clientWidth);
              const maxBottom = children.reduce((acc, item) => {
                  const pos = layout[item.id];
                  if (!pos || typeof pos.y !== 'number') return acc;
                  return Math.max(acc, pos.y + 75 + FOLDER_VIEW_GRID_PADDING);
              }, listEl.clientHeight);

              const spacer = document.createElement('div');
              spacer.className = 'desktop-slice-canvas-spacer';
              spacer.style.width = `${Math.max(maxRight, listEl.clientWidth)}px`;
              spacer.style.height = `${Math.max(maxBottom, listEl.clientHeight)}px`;
              listEl.appendChild(spacer);
          }

          function ensureLayoutForChildren(children) {
              const layout = getLayoutForFolder(folderId);
              const validChildIds = new Set(children.map((item) => item.id));
              let changed = false;

              Object.keys(layout).forEach((itemId) => {
                  if (!validChildIds.has(itemId)) {
                      delete layout[itemId];
                      changed = true;
                  }
              });

              children.forEach((item) => {
                  const current = layout[item.id];
                  if (current && typeof current.x === 'number' && typeof current.y === 'number') {
                      return;
                  }
                  const snapped = snapFolderPosition(FOLDER_VIEW_GRID_PADDING, FOLDER_VIEW_GRID_PADDING, layout, item.id);
                  layout[item.id] = snapped;
                  changed = true;
              });

              if (changed) {
                  saveLayoutForFolder(folderId, layout);
              }
              return layout;
          }

          function isPointInsideFolderCanvas(clientX, clientY) {
              const rect = listEl.getBoundingClientRect();
              return clientX >= rect.left && clientX <= rect.right && clientY >= rect.top && clientY <= rect.bottom;
          }

          function isDesktopRootDropPoint(clientX, clientY) {
              if (!desktopEl) {
                  return false;
              }

              const hitElement = document.elementFromPoint(clientX, clientY);
              if (!hitElement || !desktopEl.contains(hitElement)) {
                  return false;
              }

              if (hitElement.closest('.window') || hitElement.closest('.desktop-icon')) {
                  return false;
              }

              return true;
          }

          function isIntersecting(rectA, rectB) {
              return !(rectA.right < rectB.left || rectA.left > rectB.right || rectA.bottom < rectB.top || rectA.top > rectB.bottom);
          }

          function startMarqueeSelection(event) {
              if (event.button !== 0) return;
              isMarqueeSelecting = true;
              marqueePointerId = event.pointerId;
              listRectCache = listEl.getBoundingClientRect();
              marqueeStartX = event.clientX - listRectCache.left + listEl.scrollLeft;
              marqueeStartY = event.clientY - listRectCache.top + listEl.scrollTop;

              marqueeElement = document.createElement('div');
              marqueeElement.className = 'marquee-select-box';
              Object.assign(marqueeElement.style, {
                  left: `${marqueeStartX}px`,
                  top: `${marqueeStartY}px`,
                  width: '0px',
                  height: '0px',
              });
              listEl.appendChild(marqueeElement);

              if (!event.ctrlKey && !event.shiftKey) {
                  clearSelection();
              }
              listEl.setPointerCapture(event.pointerId);
              document.body.classList.add('no-select');
          }

          function updateMarqueeSelection(event) {
              if (!isMarqueeSelecting || !marqueeElement || event.pointerId !== marqueePointerId) return;
              const currentX = event.clientX - listRectCache.left + listEl.scrollLeft;
              const currentY = event.clientY - listRectCache.top + listEl.scrollTop;
              const newLeft = Math.min(marqueeStartX, currentX);
              const newTop = Math.min(marqueeStartY, currentY);
              const newWidth = Math.abs(currentX - marqueeStartX);
              const newHeight = Math.abs(currentY - marqueeStartY);
              Object.assign(marqueeElement.style, {
                  left: `${newLeft}px`,
                  top: `${newTop}px`,
                  width: `${newWidth}px`,
                  height: `${newHeight}px`,
              });

              const marqueeRect = marqueeElement.getBoundingClientRect();
              getVisibleFolderIcons().forEach((iconEl) => {
                  const itemId = iconEl.dataset.itemId;
                  if (!itemId) return;
                  const iconRect = iconEl.getBoundingClientRect();
                  const isSelected = selectedItemIds.has(itemId);
                  if (isIntersecting(marqueeRect, iconRect)) {
                      if (!isSelected) {
                          selectedItemIds.add(itemId);
                          applySliceSelectionVisuals(iconEl);
                      }
                  } else if (isSelected && !(event.ctrlKey || event.shiftKey)) {
                      selectedItemIds.delete(itemId);
                      removeSliceSelectionVisuals(iconEl);
                  }
              });
              syncRenameButtonState();
          }

          function endMarqueeSelection(event) {
              if (!isMarqueeSelecting) return;
              if (marqueePointerId !== null && event.pointerId !== marqueePointerId) return;
              if (event.pointerId !== undefined && listEl.hasPointerCapture(event.pointerId)) {
                  listEl.releasePointerCapture(event.pointerId);
              }
              if (marqueeElement) {
                  marqueeElement.remove();
                  marqueeElement = null;
              }
              marqueePointerId = null;
              isMarqueeSelecting = false;
              document.body.classList.remove('no-select');
          }

          function updateDragHover(clientX, clientY) {
              if (!activeSurfaceDrag || !activeSurfaceDrag.dragging) {
                  return;
              }
              const target = resolveFolderDropTargetAtPoint(clientX, clientY, activeSurfaceDrag.dragIcons);
              activeSurfaceDrag.hoverTarget = target;
              setFolderDropTargetHighlight(target);
          }

          function clearDragGhost() {
              if (activeDragGhostEl && activeDragGhostEl.parentNode) {
                  activeDragGhostEl.parentNode.removeChild(activeDragGhostEl);
              }
              activeDragGhostEl = null;
          }

          function createDragGhostFromIcon(sourceIcon, offsetX, offsetY) {
              clearDragGhost();
              if (!sourceIcon) return;

              const ghostEl = sourceIcon.cloneNode(true);
              ghostEl.classList.remove('selected');
              ghostEl.classList.remove('folder-viewer-item');
              ghostEl.classList.add('desktop-slice-drag-ghost');
              ghostEl.style.position = 'fixed';
              ghostEl.style.left = '0px';
              ghostEl.style.top = '0px';
              ghostEl.style.margin = '0';
              ghostEl.style.zIndex = '60000';
              ghostEl.style.pointerEvents = 'none';
              ghostEl.style.opacity = '0.9';
              ghostEl.style.width = `${sourceIcon.offsetWidth || 75}px`;
              ghostEl.style.height = `${sourceIcon.offsetHeight || 75}px`;

              activeDragGhostEl = ghostEl;
              document.body.appendChild(ghostEl);

              if (activeSurfaceDrag) {
                  activeSurfaceDrag.ghostOffsetX = Math.max(0, Math.min(offsetX, sourceIcon.offsetWidth || 75));
                  activeSurfaceDrag.ghostOffsetY = Math.max(0, Math.min(offsetY, sourceIcon.offsetHeight || 75));
              }
          }

          function updateDragGhostPosition(clientX, clientY) {
              if (!activeSurfaceDrag || !activeSurfaceDrag.dragging || !activeDragGhostEl) return;
              const ghostOffsetX = typeof activeSurfaceDrag.ghostOffsetX === 'number'
                  ? activeSurfaceDrag.ghostOffsetX
                  : 16;
              const ghostOffsetY = typeof activeSurfaceDrag.ghostOffsetY === 'number'
                  ? activeSurfaceDrag.ghostOffsetY
                  : 16;
              activeDragGhostEl.style.left = `${clientX - ghostOffsetX}px`;
              activeDragGhostEl.style.top = `${clientY - ghostOffsetY}px`;
          }

          function autoScrollFolderCanvas(clientX, clientY) {
              const rect = listEl.getBoundingClientRect();
              let deltaX = 0;
              let deltaY = 0;

              if (clientX < rect.left + FOLDER_DRAG_AUTO_SCROLL_EDGE) {
                  deltaX = -FOLDER_DRAG_AUTO_SCROLL_STEP;
              } else if (clientX > rect.right - FOLDER_DRAG_AUTO_SCROLL_EDGE) {
                  deltaX = FOLDER_DRAG_AUTO_SCROLL_STEP;
              }
              if (clientY < rect.top + FOLDER_DRAG_AUTO_SCROLL_EDGE) {
                  deltaY = -FOLDER_DRAG_AUTO_SCROLL_STEP;
              } else if (clientY > rect.bottom - FOLDER_DRAG_AUTO_SCROLL_EDGE) {
                  deltaY = FOLDER_DRAG_AUTO_SCROLL_STEP;
              }

              if (deltaX === 0 && deltaY === 0) {
                  return;
              }

              const maxScrollLeft = Math.max(0, listEl.scrollWidth - listEl.clientWidth);
              const maxScrollTop = Math.max(0, listEl.scrollHeight - listEl.clientHeight);
              listEl.scrollLeft = Math.max(0, Math.min(maxScrollLeft, listEl.scrollLeft + deltaX));
              listEl.scrollTop = Math.max(0, Math.min(maxScrollTop, listEl.scrollTop + deltaY));
          }

          function cleanupActiveDragState(pointerId = null) {
              clearFolderDropTargetHighlight();
              if (activeSurfaceDrag && activeSurfaceDrag.dragIcons) {
                  activeSurfaceDrag.dragIcons.forEach((iconEl) => {
                      iconEl.classList.remove('dragging');
                      const state = activeSurfaceDrag.initialStates.get(iconEl);
                      if (state) {
                          iconEl.style.zIndex = state.zIndex;
                      }
                  });
              }
              if (activeSurfaceDrag && listEl && pointerId !== null && listEl.hasPointerCapture(pointerId)) {
                  listEl.releasePointerCapture(pointerId);
              }
              clearDragGhost();
              activeSurfaceDrag = null;
              document.body.classList.remove('no-select');
          }

          function startIconDrag(event, iconEl) {
              if (event.button !== 0 || !iconEl) return;
              listRectCache = listEl.getBoundingClientRect();

              const clickedItemId = iconEl.dataset.itemId;
              if (!clickedItemId) return;

              if (event.ctrlKey) {
                  toggleSelectIcon(iconEl);
              } else if (event.shiftKey) {
                  if (!selectedItemIds.has(clickedItemId)) {
                      clearSelection();
                      selectIcon(iconEl, true);
                  }
              } else if (!selectedItemIds.has(clickedItemId)) {
                  clearSelection();
                  selectIcon(iconEl, true);
              }

              const dragItemIds = selectedItemIds.has(clickedItemId)
                  ? new Set(selectedItemIds)
                  : new Set([clickedItemId]);
              const dragIcons = Array.from(dragItemIds)
                  .map((itemId) => getFolderIconByItemId(itemId))
                  .filter((candidate) => !!candidate);
              if (dragIcons.length === 0) {
                  return;
              }

              const clickedRect = iconEl.getBoundingClientRect();
              const initialStates = new Map();
              dragIcons.forEach((dragIcon) => {
                  initialStates.set(dragIcon, {
                      x: parseFloat(dragIcon.style.left) || FOLDER_VIEW_GRID_PADDING,
                      y: parseFloat(dragIcon.style.top) || FOLDER_VIEW_GRID_PADDING,
                      zIndex: dragIcon.style.zIndex || '',
                  });
                  dragIcon.style.zIndex = '1000';
                  dragIcon.classList.add('dragging');
              });

              activeSurfaceDrag = {
                  pointerId: event.pointerId,
                  startX: event.clientX,
                  startY: event.clientY,
                  primaryIcon: iconEl,
                  primaryItemId: clickedItemId,
                  dragItemIds,
                  dragIcons,
                  initialStates,
                  dragOffsetX: event.clientX - clickedRect.left,
                  dragOffsetY: event.clientY - clickedRect.top,
                  dragging: false,
                  hoverTarget: null,
                  ghostOffsetX: null,
                  ghostOffsetY: null,
              };
              createDragGhostFromIcon(iconEl, event.clientX - clickedRect.left, event.clientY - clickedRect.top);
              document.body.classList.add('no-select');
              listEl.setPointerCapture(event.pointerId);
          }

          function processIconDrag(event) {
              if (!activeSurfaceDrag || event.pointerId !== activeSurfaceDrag.pointerId) return;
              if (!activeSurfaceDrag.dragging) {
                  const deltaX = Math.abs(event.clientX - activeSurfaceDrag.startX);
                  const deltaY = Math.abs(event.clientY - activeSurfaceDrag.startY);
                  if (deltaX > 3 || deltaY > 3) {
                      activeSurfaceDrag.dragging = true;
                  }
              }
              if (!activeSurfaceDrag.dragging) return;

              autoScrollFolderCanvas(event.clientX, event.clientY);

              const primaryState = activeSurfaceDrag.initialStates.get(activeSurfaceDrag.primaryIcon);
              if (!primaryState) return;

              const listRect = listEl.getBoundingClientRect();
              let newPrimaryX = event.clientX - listRect.left + listEl.scrollLeft - activeSurfaceDrag.dragOffsetX;
              let newPrimaryY = event.clientY - listRect.top + listEl.scrollTop - activeSurfaceDrag.dragOffsetY;
              newPrimaryX = Math.max(FOLDER_VIEW_GRID_PADDING, newPrimaryX);
              newPrimaryY = Math.max(FOLDER_VIEW_GRID_PADDING, newPrimaryY);

              const deltaX = newPrimaryX - primaryState.x;
              const deltaY = newPrimaryY - primaryState.y;

              activeSurfaceDrag.dragIcons.forEach((dragIcon) => {
                  const state = activeSurfaceDrag.initialStates.get(dragIcon);
                  if (!state) return;
                  const nextX = Math.max(FOLDER_VIEW_GRID_PADDING, state.x + deltaX);
                  const nextY = Math.max(FOLDER_VIEW_GRID_PADDING, state.y + deltaY);
                  dragIcon.style.left = `${nextX}px`;
                  dragIcon.style.top = `${nextY}px`;
              });
              updateDragGhostPosition(event.clientX, event.clientY);
              updateDragHover(event.clientX, event.clientY);
          }

          function recycleDraggedItem(itemId) {
              if (!recycleBinApi || typeof recycleBinApi.addItem !== 'function' || !window.Win9xDesktopItems || typeof window.Win9xDesktopItems.getItemById !== 'function') {
                  return false;
              }
              const item = window.Win9xDesktopItems.getItemById(itemId);
              if (!item) return false;
              recycleBinApi.addItem({
                  id: `item:${item.id}`,
                  name: item.name || 'Item',
                  iconSrc: item.icon || './html-0.png',
                  originalAppId: null,
              });
              return true;
          }

          function snapDraggedItemsToGrid(itemIds) {
              const layout = getLayoutForFolder(folderId);
              itemIds.forEach((itemId) => {
                  const iconEl = getFolderIconByItemId(itemId);
                  const rawX = iconEl ? (parseFloat(iconEl.style.left) || FOLDER_VIEW_GRID_PADDING) : FOLDER_VIEW_GRID_PADDING;
                  const rawY = iconEl ? (parseFloat(iconEl.style.top) || FOLDER_VIEW_GRID_PADDING) : FOLDER_VIEW_GRID_PADDING;
                  const snapped = snapFolderPosition(rawX, rawY, layout, itemId);
                  layout[itemId] = snapped;
                  if (iconEl) {
                      iconEl.style.left = `${snapped.x}px`;
                      iconEl.style.top = `${snapped.y}px`;
                  }
              });
              saveLayoutForFolder(folderId, layout);
          }

          function lineUpFolderIcons() {
              if (!folderId || !window.Win9xDesktopItems || typeof window.Win9xDesktopItems.getItemsByParentId !== 'function') {
                  return;
              }
              const children = window.Win9xDesktopItems.getItemsByParentId(folderId);
              snapDraggedItemsToGrid(children.map((item) => item.id));
              renderItems();
          }

          function arrangeFolderIcons(mode = null) {
              if (!folderId || !window.Win9xDesktopItems || typeof window.Win9xDesktopItems.getItemsByParentId !== 'function') {
                  return;
              }
              if (mode) {
                  folderArrangeMode = mode;
              }

              const children = window.Win9xDesktopItems.getItemsByParentId(folderId);
              if (children.length === 0) return;

              const typeOrderMap = {
                  application: 0,
                  folder: 1,
                  shortcut: 2,
                  textdocument: 3,
                  bitmapimage: 4,
                  wavesound: 5,
              };

              children.sort((a, b) => {
                  const nameA = (a.name || '').toLowerCase();
                  const nameB = (b.name || '').toLowerCase();
                  const typeA = (a.type || '').toLowerCase();
                  const typeB = (b.type || '').toLowerCase();
                  const typeOrderA = Object.prototype.hasOwnProperty.call(typeOrderMap, typeA) ? typeOrderMap[typeA] : 99;
                  const typeOrderB = Object.prototype.hasOwnProperty.call(typeOrderMap, typeB) ? typeOrderMap[typeB] : 99;
                  const sizeA = typeof a.size === 'number' ? a.size : 0;
                  const sizeB = typeof b.size === 'number' ? b.size : 0;
                  const dateA = typeof a.createdAt === 'number' ? a.createdAt : 0;
                  const dateB = typeof b.createdAt === 'number' ? b.createdAt : 0;

                  if (folderArrangeMode === 'type') {
                      if (typeOrderA !== typeOrderB) return typeOrderA - typeOrderB;
                      return nameA.localeCompare(nameB);
                  }
                  if (folderArrangeMode === 'size') {
                      if (sizeA !== sizeB) return sizeB - sizeA;
                      return nameA.localeCompare(nameB);
                  }
                  if (folderArrangeMode === 'date') {
                      if (dateA !== dateB) return dateB - dateA;
                      return nameA.localeCompare(nameB);
                  }
                  return nameA.localeCompare(nameB);
              });

              const { maxCols } = getFolderGridMetrics();
              const layout = getLayoutForFolder(folderId);
              children.forEach((item, index) => {
                  const col = index % maxCols;
                  const row = Math.floor(index / maxCols);
                  layout[item.id] = {
                      x: FOLDER_VIEW_GRID_PADDING + (col * FOLDER_VIEW_GRID_SIZE_X),
                      y: FOLDER_VIEW_GRID_PADDING + (row * FOLDER_VIEW_GRID_SIZE_Y),
                  };
              });
              saveLayoutForFolder(folderId, layout);
              renderItems();
          }

          function createNewItemInFolder(type) {
              if (!folderId || !window.Win9xDesktopItems || typeof window.Win9xDesktopItems.createItem !== 'function') {
                  return;
              }
              try {
                  const created = window.Win9xDesktopItems.createItem(type, { parentId: folderId });
                  if (created && created.id) {
                      clearSelection();
                      const iconEl = getFolderIconByItemId(created.id);
                      if (iconEl) {
                          selectIcon(iconEl, true);
                      } else {
                          selectedItemIds.add(created.id);
                      }
                  }
              } catch (error) {
                  console.error('FolderViewer: failed to create new item from context menu:', error);
              }
          }

          function deleteSelectedItems() {
              if (!window.Win9xDesktopItems || typeof window.Win9xDesktopItems.deleteItem !== 'function') {
                  return;
              }
              const itemIds = Array.from(selectedItemIds);
              if (itemIds.length === 0) return;
              itemIds.forEach((itemId) => {
                  const deleted = window.Win9xDesktopItems.deleteItem(itemId);
                  if (deleted) {
                      removeLayoutEntry(folderId, itemId);
                  }
              });
              clearSelection();
          }

          function openSelectedItems() {
              if (!window.Win9xDesktopItems || typeof window.Win9xDesktopItems.openItem !== 'function') {
                  return;
              }
              const itemIds = Array.from(selectedItemIds);
              itemIds.forEach((itemId) => {
                  window.Win9xDesktopItems.openItem(itemId);
              });
          }

          function getFolderIconContextMenuModel() {
              const hasSelection = selectedItemIds.size > 0;
              const canRename = !!getSingleSelectedItemId();
              return [
                  { text: '<u>O</u>pen', action: openSelectedItems, disabled: !hasSelection },
                  { text: '<u>R</u>ename', action: beginRenameSelectedItem, disabled: !canRename },
                  { separator: true },
                  { text: '<u>D</u>elete', action: deleteSelectedItems, disabled: !hasSelection },
                  { separator: true },
                  { text: 'P<u>r</u>operties', disabled: true },
              ];
          }

          function getFolderCanvasContextMenuModel() {
              const newItems = FOLDER_CONTEXT_NEW_TYPES.map((entry) => ({
                  text: entry.label,
                  icon: entry.icon,
                  action: () => createNewItemInFolder(entry.type),
              }));
              return [
                  {
                      text: '<u>A</u>rrange Icons',
                      submenu: [
                          { text: 'by <u>N</u>ame', action: () => arrangeFolderIcons('name') },
                          { text: 'by <u>T</u>ype', action: () => arrangeFolderIcons('type') },
                          { text: 'by <u>S</u>ize', action: () => arrangeFolderIcons('size') },
                          { text: 'by <u>D</u>ate', action: () => arrangeFolderIcons('date') },
                          { separator: true },
                          { text: '<u>L</u>ine Up Icons', action: lineUpFolderIcons },
                      ],
                  },
                  { separator: true },
                  { text: '<u>R</u>efresh', action: renderItems },
                  { separator: true },
                  { text: '<u>N</u>ew', submenu: newItems },
                  { separator: true },
                  { text: 'P<u>r</u>operties', disabled: true },
              ];
          }

          function showFolderContextMenu(event, iconEl = null) {
              if (!window.DesktopContextMenu || typeof window.DesktopContextMenu.showCustom !== 'function') {
                  return;
              }

              if (iconEl) {
                  const itemId = iconEl.dataset.itemId;
                  if (itemId && !selectedItemIds.has(itemId)) {
                      clearSelection();
                      selectIcon(iconEl, true);
                  }
                  window.DesktopContextMenu.showCustom(event, getFolderIconContextMenuModel());
                  return;
              }

              clearSelection();
              window.DesktopContextMenu.showCustom(event, getFolderCanvasContextMenuModel());
          }

          function commitIconDrop(clientX, clientY) {
              if (!activeSurfaceDrag || !activeSurfaceDrag.dragging || !window.Win9xDesktopItems || typeof window.Win9xDesktopItems.moveItem !== 'function') {
                  return;
              }

              const target = activeSurfaceDrag.hoverTarget;
              const draggedItemIds = Array.from(activeSurfaceDrag.dragItemIds);
              let movedBetweenContainers = false;
              let recycled = false;

              if (target && target.kind === 'recycle-bin-icon') {
                  draggedItemIds.forEach((itemId) => {
                      const recycledItem = recycleDraggedItem(itemId);
                      if (recycledItem) {
                          recycled = true;
                          removeLayoutEntry(folderId, itemId);
                      }
                  });
              } else if (target && typeof target.folderId === 'string' && target.folderId) {
                  if (target.folderId !== folderId) {
                      draggedItemIds.forEach((itemId) => {
                          if (itemId === target.folderId) return;
                          const moved = window.Win9xDesktopItems.moveItem(itemId, target.folderId);
                          if (moved) {
                              movedBetweenContainers = true;
                              removeLayoutEntry(folderId, itemId);
                          }
                      });
                  } else if (isPointInsideFolderCanvas(clientX, clientY)) {
                      snapDraggedItemsToGrid(draggedItemIds);
                  }
              } else if (isDesktopRootDropPoint(clientX, clientY)) {
                  draggedItemIds.forEach((itemId) => {
                      const moved = window.Win9xDesktopItems.moveItem(itemId, null);
                      if (moved) {
                          movedBetweenContainers = true;
                          removeLayoutEntry(folderId, itemId);
                      }
                  });
              } else if (isPointInsideFolderCanvas(clientX, clientY)) {
                  snapDraggedItemsToGrid(draggedItemIds);
              } else {
                  draggedItemIds.forEach((itemId) => {
                      const moved = window.Win9xDesktopItems.moveItem(itemId, null);
                      if (moved) {
                          movedBetweenContainers = true;
                          removeLayoutEntry(folderId, itemId);
                      }
                  });
              }

              if (movedBetweenContainers || recycled) {
                  draggedItemIds.forEach((itemId) => selectedItemIds.delete(itemId));
                  syncRenameButtonState();
                  updateStatusSummary();
              }
          }

          function endIconDrag(event) {
              if (!activeSurfaceDrag) return;
              if (activeSurfaceDrag.dragging) {
                  commitIconDrop(event.clientX, event.clientY);
              }
              cleanupActiveDragState(event.pointerId);
          }

          function renderItems() {
              if (!listEl || !statusEl) return;
              if (activeRenameSession) {
                  finalizeActiveRename(false);
              }

              if (!folderId || !window.Win9xDesktopItems || typeof window.Win9xDesktopItems.getItemById !== 'function') {
                  listEl.innerHTML = '<div class="desktop-slice-empty-message">Folder is unavailable.</div>';
                  lastRenderedItemCount = 0;
                  updateStatusSummary(0);
                  syncRenameButtonState();
                  return;
              }

              const folder = window.Win9xDesktopItems.getItemById(folderId);
              if (!folder || folder.type !== 'folder') {
                  listEl.innerHTML = '<div class="desktop-slice-empty-message">Folder not found.</div>';
                  lastRenderedItemCount = 0;
                  updateStatusSummary(0);
                  if (titleEl) titleEl.textContent = 'Folder';
                  syncRenameButtonState();
                  return;
              }

              const folderName = folder.name || 'Folder';
              if (titleEl) titleEl.textContent = `${folderName} - Folder`;
              if (captionEl) captionEl.textContent = folderName;
              if (listEl) {
                  listEl.dataset.folderId = folderId;
                  listEl.dataset.dropTargetType = 'folder-viewer-list';
              }

              const children = (typeof window.Win9xDesktopItems.getItemsByParentId === 'function')
                  ? window.Win9xDesktopItems.getItemsByParentId(folderId)
                  : [];
              const visibleChildIds = new Set(children.map((item) => item.id));
              Array.from(selectedItemIds).forEach((itemId) => {
                  if (!visibleChildIds.has(itemId)) {
                      selectedItemIds.delete(itemId);
                  }
              });

              if (children.length === 0) {
                  listEl.innerHTML = '<div class="desktop-slice-empty-message">This folder is empty.</div>';
                  lastRenderedItemCount = 0;
                  updateStatusSummary(0);
                  syncRenameButtonState();
                  return;
              }

              const layout = ensureLayoutForChildren(children);
              listEl.innerHTML = '';
              children.forEach((item) => {
                  const iconEl = document.createElement('div');
                  iconEl.className = 'desktop-slice-icon folder-viewer-item';
                  iconEl.dataset.itemId = item.id;
                  iconEl.dataset.desktopItemId = item.id;
                  iconEl.dataset.itemType = item.type;
                  iconEl.style.position = 'absolute';
                  iconEl.style.margin = '0';

                  const pos = layout[item.id] || { x: FOLDER_VIEW_GRID_PADDING, y: FOLDER_VIEW_GRID_PADDING };
                  iconEl.style.left = `${pos.x}px`;
                  iconEl.style.top = `${pos.y}px`;

                  const iconImg = document.createElement('img');
                  iconImg.src = item.icon || './html-0.png';
                  iconImg.alt = '';
                  iconImg.draggable = false;
                  iconEl.appendChild(iconImg);

                  const nameEl = document.createElement('span');
                  nameEl.textContent = item.name;
                  iconEl.appendChild(nameEl);

                  if (selectedItemIds.has(item.id)) {
                      applySliceSelectionVisuals(iconEl);
                  }

                  listEl.appendChild(iconEl);
              });
              updateFolderCanvasExtent(layout, children);
              lastRenderedItemCount = children.length;
              updateStatusSummary(children.length);
              syncRenameButtonState();
          }

          if (refreshBtn) {
              refreshBtn.addEventListener('click', () => {
                  renderItems();
              });
          }
          if (renameBtn) {
              renameBtn.addEventListener('click', () => {
                  beginRenameSelectedItem();
              });
          }

          if (listEl) {
              listEl.setAttribute('tabindex', '0');
              listEl.addEventListener('dragstart', preventNativeImageDragStart);

              listEl.addEventListener('dblclick', (event) => {
                  const iconEl = event.target.closest('.folder-viewer-item[data-item-id]');
                  if (!iconEl || !listEl.contains(iconEl)) return;
                  const itemId = iconEl.dataset.itemId;
                  if (itemId && window.Win9xDesktopItems && typeof window.Win9xDesktopItems.openItem === 'function') {
                      window.Win9xDesktopItems.openItem(itemId);
                  }
              });

              listEl.addEventListener('contextmenu', (event) => {
                  if (activeRenameSession) {
                      finalizeActiveRename(true);
                  }
                  const iconEl = event.target.closest('.folder-viewer-item[data-item-id]');
                  if (iconEl && listEl.contains(iconEl)) {
                      showFolderContextMenu(event, iconEl);
                      return;
                  }
                  showFolderContextMenu(event, null);
              });

              listEl.addEventListener('pointerdown', (event) => {
                  if (event.button !== 0) return;
                  if (event.target && event.target.closest && event.target.closest('.desktop-icon-rename-input')) return;
                  if (activeRenameSession) {
                      const clickedRenameInput = event.target && event.target.closest
                          ? event.target.closest('.desktop-icon-rename-input')
                          : null;
                      if (!clickedRenameInput) {
                          finalizeActiveRename(true);
                      }
                  }
                  const iconEl = event.target.closest('.folder-viewer-item[data-item-id]');
                  listEl.focus({ preventScroll: true });
                  if (iconEl && listEl.contains(iconEl)) {
                      startIconDrag(event, iconEl);
                      return;
                  }
                  startMarqueeSelection(event);
              });

              listEl.addEventListener('pointermove', (event) => {
                  if (isMarqueeSelecting) {
                      updateMarqueeSelection(event);
                      return;
                  }
                  processIconDrag(event);
              });

              listEl.addEventListener('pointerup', (event) => {
                  if (isMarqueeSelecting) {
                      endMarqueeSelection(event);
                      return;
                  }
                  if (activeSurfaceDrag && event.pointerId === activeSurfaceDrag.pointerId) {
                      endIconDrag(event);
                  }
              });

              listEl.addEventListener('pointercancel', (event) => {
                  if (isMarqueeSelecting) {
                      endMarqueeSelection(event);
                  }
                  if (activeSurfaceDrag && event.pointerId === activeSurfaceDrag.pointerId) {
                      cleanupActiveDragState(event.pointerId);
                  }
              });

              listEl.addEventListener('keydown', (event) => {
                  const singleSelectedItemId = getSingleSelectedItemId();
                  if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'a') {
                      event.preventDefault();
                      clearSelection();
                      getVisibleFolderIcons().forEach((iconEl) => {
                          const itemId = iconEl.dataset.itemId;
                          if (!itemId) return;
                          selectedItemIds.add(itemId);
                          applySliceSelectionVisuals(iconEl);
                      });
                      syncRenameButtonState();
                      updateStatusSummary();
                      return;
                  }
                  if (event.key === 'F5') {
                      event.preventDefault();
                      renderItems();
                      return;
                  }
                  if (event.key === 'F2') {
                      if (singleSelectedItemId) {
                          event.preventDefault();
                          beginRenameSelectedItem();
                      }
                      return;
                  }
                  if (event.key === 'Enter' && singleSelectedItemId && !activeRenameSession) {
                      event.preventDefault();
                      if (window.Win9xDesktopItems && typeof window.Win9xDesktopItems.openItem === 'function') {
                          window.Win9xDesktopItems.openItem(singleSelectedItemId);
                      }
                      return;
                  }
                  if (event.key === 'Delete' && selectedItemIds.size > 0 && !activeRenameSession) {
                      event.preventDefault();
                      deleteSelectedItems();
                      return;
                  }
                  if (event.key === 'Escape' && activeRenameSession) {
                      event.preventDefault();
                      finalizeActiveRename(false);
                      return;
                  }
                  if (event.key === 'Escape' && selectedItemIds.size > 0) {
                      event.preventDefault();
                      clearSelection();
                  }
              });
          }

          window.addEventListener('win9x:desktop-items-changed', handleDesktopItemsChanged);

          renderItems();
          return {
              refresh: renderItems,
              destroy: () => {
                  finalizeActiveRename(false);
                  if (isMarqueeSelecting) {
                      endMarqueeSelection({ pointerId: marqueePointerId });
                  }
                  cleanupActiveDragState();
                  if (listEl) {
                      listEl.removeEventListener('dragstart', preventNativeImageDragStart);
                  }
                  window.removeEventListener('win9x:desktop-items-changed', handleDesktopItemsChanged);
              },
          };
      },
  };

  function showMsdosModeErrorDialog() {
      const overlayId = 'msdosModeErrorOverlay';
      const existingOverlay = document.getElementById(overlayId);
      if (existingOverlay) return existingOverlay;

      const overlay = document.createElement('div');
      overlay.id = overlayId;
      overlay.style.cssText = `
          position: fixed; inset: 0; z-index: 100000;
          background: transparent;
          display: flex; align-items: center; justify-content: center;
          padding: 8px;
      `;

      const dialog = document.createElement('div');
      dialog.style.cssText = `
          background: #c0c0c0; border: 2px outset #dfdfdf;
          width: min(314px, calc(100vw - 16px));
          max-width: calc(100vw - 16px);
          box-shadow: 2px 2px 0 rgba(0,0,0,0.45);
          font-family: "MS Sans Serif", Tahoma, Arial, sans-serif;
      `;

      const titleBar = document.createElement('div');
      titleBar.style.cssText = `
          background: #000080;
          color: #fff; padding: 2px 3px; font-weight: bold; font-size: 11px;
          display: flex; align-items: center; justify-content: space-between;
          line-height: 1;
      `;
      const titleText = document.createElement('span');
      titleText.style.cssText = 'white-space: nowrap; overflow: hidden; text-overflow: ellipsis; padding-right: 4px;';
      titleText.textContent = 'C:\\WINDOWS.002\\Desktop\\TGVXMPXMP.exe';

      const closeBtn = document.createElement('button');
      closeBtn.type = 'button';
      closeBtn.textContent = 'r';
      closeBtn.title = 'Close';
      closeBtn.style.cssText = `
          min-width: 16px; width: 16px; height: 14px; padding: 0; margin: 0;
          border: 1px outset #dfdfdf; background: #c0c0c0; color: #000;
          font-family: "MarlettCustom", "Marlett", "Webdings", sans-serif; font-size: 10px;
          line-height: 1; cursor: pointer;
      `;
      closeBtn.addEventListener('pointerdown', () => {
          closeBtn.style.borderStyle = 'inset';
      });
      closeBtn.addEventListener('pointerup', () => {
          closeBtn.style.borderStyle = 'outset';
      });
      closeBtn.addEventListener('click', () => overlay.remove());
      titleBar.appendChild(titleText);
      titleBar.appendChild(closeBtn);

      const content = document.createElement('div');
      content.style.cssText = 'padding: 14px 12px 10px 12px; font-size: 11px;';

      const row = document.createElement('div');
      row.style.cssText = 'display:flex; gap:12px; align-items:flex-start;';

      const icon = document.createElement('img');
      icon.src = './msg_error-0.png';
      icon.alt = '';
      icon.style.cssText = 'width:32px; height:32px; flex-shrink:0; margin-top:2px; image-rendering: pixelated;';

      const textWrap = document.createElement('div');
      textWrap.style.cssText = 'line-height:1.45; word-break: break-word; padding-top:1px;';
      textWrap.innerHTML = `
          <div style="margin-bottom:8px;">C:\\WINDOWS.002\\Desktop\\TGVXMPXMP.exe</div>
          <div>A device attached to the system is not functioning.</div>
      `;

      row.appendChild(icon);
      row.appendChild(textWrap);
      content.appendChild(row);

      const actions = document.createElement('div');
      actions.style.cssText = 'display:flex; justify-content:center; margin-top:12px;';

      const okButton = document.createElement('button');
      okButton.className = 'win95-button';
      okButton.type = 'button';
      okButton.textContent = 'OK';
      okButton.style.minWidth = '80px';
      okButton.addEventListener('click', () => overlay.remove());

      actions.appendChild(okButton);
      content.appendChild(actions);

      dialog.appendChild(titleBar);
      dialog.appendChild(content);
      overlay.appendChild(dialog);
      document.body.appendChild(overlay);

      return overlay;
  }

  const APP_DEFINITIONS = {
      networkExplorer: networkExplorerAppDefinition,
      notepad: notepadAppDefinition,
      recycleBin: recycleBinAppDefinition,
      calculator: calculatorAppDefinition,
      imageViewer: imageViewerAppDefinition,
      wavePlayer: wavePlayerAppDefinition,
      folderViewer: folderViewerAppDefinition,
      helpCenter: {
          title: 'Windows Help',
          icon: './help_book_cool-0.png',
          titlebarIcon: './help_question_mark-0.png',
          taskbarIcon: './help_book_cool-0.png',
          defaultWidth: 860,
          defaultHeight: 610,
          generateContent: () => `
              <style>
                  .bbx-help-window {
                      height: 100%;
                      display: flex;
                      flex-direction: column;
                      background: #bdbebd;
                      font-family: "MS Sans Serif", Tahoma, Arial, sans-serif;
                      font-size: 11px;
                      color: #000;
                  }
                  .bbx-help-toolbar {
                      display: flex;
                      align-items: flex-start;
                      gap: 6px;
                      padding: 4px 6px 2px 6px;
                      background: #bdbebd;
                      border-bottom: 1px solid #808080;
                      box-shadow: inset 0 -1px #fff;
                  }
                  .bbx-help-toolbtn {
                      min-width: 88px;
                      border: 1px solid transparent;
                      background: transparent;
                      color: #000;
                      padding: 1px 2px 0 2px;
                      margin: 0;
                      display: flex;
                      flex-direction: column;
                      align-items: center;
                      justify-content: flex-start;
                      gap: 1px;
                      cursor: default;
                  }
                  .bbx-help-toolbtn img {
                      width: 26px;
                      height: 26px;
                      image-rendering: pixelated;
                      flex: 0 0 auto;
                  }
                  .bbx-help-toolbtn span {
                      font-size: 14px;
                      line-height: 1.05;
                  }
                  .bbx-help-toolbtn[disabled] {
                      color: #9a9a9a;
                      opacity: 1;
                      filter: grayscale(0.15);
                  }
                  .bbx-help-toolbtn.options span {
                      text-decoration: underline;
                      text-underline-offset: 1px;
                  }
                  .bbx-help-tabs {
                      display: flex;
                      align-items: flex-end;
                      gap: 2px;
                      padding: 4px 4px 0 4px;
                      background: #bdbebd;
                      border-bottom: 1px solid #808080;
                  }
                  .bbx-help-tab {
                      border: 1px solid #808080;
                      border-bottom: none;
                      background: #bcbcbc;
                      padding: 3px 12px 2px 12px;
                      color: #000;
                      margin: 0;
                  }
                  .bbx-help-tab.active {
                      background: #cfcfcf;
                      box-shadow: inset 1px 1px #fff;
                  }
                  .bbx-help-tab[disabled] {
                      color: #808080;
                  }
                  .bbx-help-main {
                      flex: 1;
                      min-height: 0;
                      display: flex;
                      align-items: stretch;
                      padding: 4px;
                      gap: 0;
                  }
                  .bbx-help-contents-pane {
                      width: 280px;
                      min-width: 180px;
                      max-width: 360px;
                      border: 1px inset #808080;
                      background: #fff;
                      display: flex;
                      min-height: 0;
                  }
                  .bbx-help-splitter {
                      width: 5px;
                      margin: 0 3px;
                      border-left: 1px solid #808080;
                      border-right: 1px solid #fff;
                      background: #bdbebd;
                  }
                  .bbx-help-content-pane {
                      flex: 1;
                      min-width: 0;
                      min-height: 0;
                      border: 1px inset #808080;
                      background: #fff;
                      display: flex;
                  }
                  .bbx-help-scroll {
                      overflow: auto;
                      min-height: 0;
                      min-width: 0;
                      scrollbar-color: #808080 #c0c0c0;
                      scrollbar-width: auto;
                  }
                  .bbx-help-scroll::-webkit-scrollbar {
                      width: 16px;
                      height: 16px;
                      background: #c0c0c0;
                  }
                  .bbx-help-scroll::-webkit-scrollbar-thumb {
                      border: 1px solid #808080;
                      box-shadow: inset 1px 1px #ffffff, inset -1px -1px #404040;
                      background: #c0c0c0;
                  }
                  .bbx-help-scroll::-webkit-scrollbar-track {
                      background: #d4d0c8;
                  }
                  .bbx-help-topics {
                      width: 100%;
                      min-height: 0;
                      padding: 2px;
                      box-sizing: border-box;
                  }
                  .bbx-help-topic-btn {
                      width: 100%;
                      margin: 0;
                      min-height: 22px;
                      padding: 0 4px 0 2px;
                      border: 1px solid transparent;
                      background: transparent;
                      color: #000;
                      text-align: left;
                      display: flex;
                      align-items: center;
                      gap: 6px;
                      line-height: 1;
                      white-space: nowrap;
                      cursor: pointer;
                  }
                  .bbx-help-topic-btn img {
                      width: 22px;
                      height: 22px;
                      flex: 0 0 auto;
                      margin-top: 1px;
                      margin-bottom: -1px;
                      image-rendering: pixelated;
                  }
                  .bbx-help-topic-btn span {
                      display: flex;
                      align-items: center;
                      min-height: 22px;
                      line-height: 13px;
                  }
                  .bbx-help-topic-btn.active {
                      background: #000080;
                      color: #fff;
                  }
                  .bbx-help-page {
                      width: 100%;
                      min-height: 0;
                      cursor: text;
                  }
                  .bbx-help-page * {
                      cursor: text;
                  }
                  .bbx-help-page-inner {
                      min-width: 500px;
                      max-width: 760px;
                      padding-bottom: 12px;
                  }
                  .bbx-help-hero {
                      background: linear-gradient(180deg, #9bc1e7 0%, #dce8f4 65%, #f4f4f4 100%);
                      border-bottom: 1px solid #b4b4b4;
                      padding: 10px 12px;
                  }
                  .bbx-help-brand {
                      display: flex;
                      align-items: center;
                      gap: 8px;
                      font-weight: bold;
                      font-size: 26px;
                      line-height: 1;
                  }
                  .bbx-help-brand img {
                      width: 24px;
                      height: 24px;
                      image-rendering: pixelated;
                  }
                  .bbx-help-brand-line {
                      height: 2px;
                      background: linear-gradient(90deg, #e33 0 33%, #ec0 33% 66%, #3a3 66% 100%);
                      margin-top: 6px;
                  }
                  .bbx-help-body {
                      padding: 14px 18px 0 18px;
                      line-height: 1.45;
                  }
                  .bbx-help-body h2 {
                      margin: 0 0 8px 0;
                      font-size: 38px;
                      line-height: 1;
                      font-weight: normal;
                  }
                  .bbx-help-body h3 {
                      margin: 12px 0 8px 0;
                      font-size: 16px;
                      line-height: 1.1;
                  }
                  .bbx-help-body p {
                      margin: 0 0 10px 0;
                  }
                  .bbx-help-body ul {
                      margin: 0 0 10px 20px;
                      padding: 0;
                      list-style: disc;
                  }
                  .bbx-help-body li {
                      margin: 0 0 8px 0;
                  }
                  .bbx-help-copyright {
                      margin-top: 22px;
                      font-size: 12px;
                  }
                  .bbx-help-body a {
                      color: #0000ff;
                      text-decoration: underline;
                  }
                  .bbx-help-body a:visited {
                      color: #551a8b;
                  }
                  @media screen and (max-width: 760px) {
                      .bbx-help-toolbar {
                          flex-wrap: nowrap;
                          align-items: center;
                          overflow-x: auto;
                          gap: 2px;
                      }
                      .bbx-help-main {
                          flex-direction: column;
                          gap: 4px;
                      }
                      .bbx-help-contents-pane {
                          width: auto;
                          max-width: none;
                          height: 180px;
                      }
                      .bbx-help-splitter {
                          display: none;
                      }
                      .bbx-help-content-pane {
                          min-height: 240px;
                      }
                      .bbx-help-page-inner {
                          min-width: 0;
                          width: 100%;
                      }
                      .bbx-help-body h2 {
                          font-size: 28px;
                      }
                  }
              </style>
              <div class="bbx-help-window">
                  <div class="bbx-help-toolbar">
                      <button class="bbx-help-toolbtn" disabled>
                          <img src="./help_toolbar_hide.png" alt="">
                          <span>Hide</span>
                      </button>
                      <button class="bbx-help-toolbtn" disabled>
                          <img src="./help_toolbar_back.png" alt="">
                          <span>Back</span>
                      </button>
                      <button class="bbx-help-toolbtn" disabled>
                          <img src="./help_toolbar_forward.png" alt="">
                          <span>Forward</span>
                      </button>
                      <button class="bbx-help-toolbtn options" disabled>
                          <img src="./help_toolbar_options.png" alt="">
                          <span><u>O</u>ptions</span>
                      </button>
                      <button class="bbx-help-toolbtn" disabled>
                          <img src="./help_toolbar_web_help.png" alt="">
                          <span>Web Help</span>
                      </button>
                  </div>
                  <div class="bbx-help-tabs">
                      <button class="bbx-help-tab active" type="button">Contents</button>
                      <button class="bbx-help-tab" type="button" disabled>Index</button>
                      <button class="bbx-help-tab" type="button" disabled>Search</button>
                  </div>
                  <div class="bbx-help-main">
                      <aside class="bbx-help-contents-pane">
                          <div class="bbx-help-topics bbx-help-scroll">
                              <button class="bbx-help-topic-btn active" type="button" data-topic-id="welcome"><img src="./help_sheet-0.png" alt=""><span>Welcome to Help</span></button>
                              <button class="bbx-help-topic-btn" type="button" data-topic-id="intro1"><img src="./help_book_small-4.png" alt=""><span>Introducing Windows 98½ (Part 1)</span></button>
                              <button class="bbx-help-topic-btn" type="button" data-topic-id="intro2"><img src="./help_book_small-4.png" alt=""><span>Introducing Windows 98½ (Part 2)</span></button>
                              <button class="bbx-help-topic-btn" type="button" data-topic-id="payment"><img src="./help_book_small-4.png" alt=""><span>BrowserBox HQ</span></button>
                              <button class="bbx-help-topic-btn" type="button" data-topic-id="bbxOverview"><img src="./help_book_small-4.png" alt=""><span>BrowserBox Overview</span></button>
                              <button class="bbx-help-topic-btn" type="button" data-topic-id="embedderApi"><img src="./help_book_small-4.png" alt=""><span>BrowserBox Embedder API</span></button>
                              <button class="bbx-help-topic-btn" type="button" data-topic-id="sessionsApi"><img src="./help_book_small-4.png" alt=""><span>BrowserBox Sessions API</span></button>
                              <button class="bbx-help-topic-btn" type="button" data-topic-id="repos"><img src="./help_book_small-4.png" alt=""><span>BrowserBox Repositories</span></button>
                              <button class="bbx-help-topic-btn" type="button" data-topic-id="licensing"><img src="./help_book_small-4.png" alt=""><span>Licensing (AGPL-3.0)</span></button>
                          </div>
                      </aside>
                      <div class="bbx-help-splitter" aria-hidden="true"></div>
                      <section class="bbx-help-content-pane">
                          <div class="bbx-help-page bbx-help-scroll" data-help-page></div>
                      </section>
                  </div>
              </div>
          `,
          initApp: (windowEl) => {
              const topicButtons = Array.from(windowEl.querySelectorAll('.bbx-help-topic-btn[data-topic-id]'));
              const pageEl = windowEl.querySelector('[data-help-page]');
              if (!pageEl) return null;
              const titlebarEl = windowEl.querySelector('.window-titlebar');
              const titlebarIconEl = windowEl.querySelector('.window-titlebar-icon');
              if (titlebarEl) {
                  titlebarEl.style.paddingLeft = '0';
              }
              if (titlebarIconEl) {
                  titlebarIconEl.src = './help_question_mark-0.png';
                  titlebarIconEl.style.marginRight = '4px';
              }

              const pages = {
                  welcome: `
                      <div class="bbx-help-page-inner">
                          <div class="bbx-help-hero">
                              <div class="bbx-help-brand"><img src="./windows-0.png" alt="">Windows98½</div>
                              <div class="bbx-help-brand-line"></div>
                          </div>
                          <div class="bbx-help-body">
                              <h2>Welcome to Help</h2>
                              <p>Use this Help system to learn about BrowserBox in a Windows 98½ style workspace.</p>
                              <ul>
                                  <li>Open the BrowserBox HQ desktop tool for Buy Minutes and waitlist links.</li>
                                  <li>Review BrowserBox API sections for embedding and session control.</li>
                                  <li>Open the <a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">BrowserBox Embedder API documentation</a> and <a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">BrowserBox Sessions API documentation</a>.</li>
                                  <li>Open BrowserBox repositories and product sites from this help view.</li>
                              </ul>
                              <p class="bbx-help-copyright">Windows is (c) Microsoft. BrowserBox is (c) DOSAYGO. No affiliation exists.</p>
                          </div>
                      </div>
                  `,
                  intro1: `
                      <div class="bbx-help-page-inner">
                          <div class="bbx-help-body">
                              <h3>Introducing Windows 98½ (Part 1)</h3>
                              <p>The Windows 98½ desktop combines taskbar access, quick launch, and context menus for fast workflows.</p>
                              <ul>
                                  <li>Use the Start menu to launch programs and system tools.</li>
                                  <li>Right-click items to access context actions and submenu commands.</li>
                                  <li>Use Quick Launch for one-click access to frequent tools.</li>
                              </ul>
                              <p>BrowserBox reproduces these patterns while embedding cloud browser sessions.</p>
                          </div>
                      </div>
                  `,
                  intro2: `
                      <div class="bbx-help-page-inner">
                          <div class="bbx-help-body">
                              <h3>Introducing Windows 98½ (Part 2)</h3>
                              <p>Desktop behavior in BrowserBox follows classic interaction rules while adapting for modern viewport sizes.</p>
                              <ul>
                                  <li>Menus reverse direction near screen edges to avoid clipping.</li>
                                  <li>Taskbar controls stay compact on smaller displays.</li>
                                  <li>System dialogs keep action buttons visible on mobile screens.</li>
                              </ul>
                              <p>For full session behavior details, continue to the BrowserBox sections in this Contents panel.</p>
                          </div>
                      </div>
                  `,
                  payment: `
                      <div class="bbx-help-page-inner">
                          <div class="bbx-help-body">
                              <h3>BrowserBox HQ</h3>
                              <p>The BrowserBox HQ desktop tool exposes purchase, waitlist, and API links immediately.</p>
                              <ul>
                                  <li><a href="/pricing/" target="_blank" rel="noopener noreferrer">Buy Minutes</a> for immediate continuation.</li>
                                  <li><a href="/pricing/#persistent-waitlist" target="_blank" rel="noopener noreferrer">Persistent Session Waitlist</a> for longer-lived environments.</li>
                                  <li><a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">BrowserBox Embedder API documentation</a> and <a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">BrowserBox Sessions API documentation</a>.</li>
                                  <li>Use this tool as the primary call-to-action surface on desktop and mobile layouts.</li>
                              </ul>
                          </div>
                      </div>
                  `,
                  bbxOverview: `
                      <div class="bbx-help-page-inner">
                          <div class="bbx-help-body">
                              <h3>BrowserBox Overview</h3>
                              <p>BrowserBox provides cloud browser sessions, controllable via direct UI use or APIs.</p>
                              <ul>
                                  <li>Session startup, reconnect, and timeout handling are exposed in SaaS UI flows.</li>
                                  <li>Purchase paths and waitlist entry points are linked where disconnection events occur.</li>
                                  <li>Reusable session containers can be managed with explicit clean-slate startup behavior.</li>
                              </ul>
                              <p>Browse <a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">BrowserBox Embedder API documentation</a> and <a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">BrowserBox Sessions API documentation</a>.</p>
                          </div>
                      </div>
                  `,
                  embedderApi: `
                      <div class="bbx-help-page-inner">
                          <div class="bbx-help-body">
                              <h3>BrowserBox Embedder API</h3>
                              <p>The Embedder API is used when BrowserBox is hosted in a parent product or dashboard.</p>
                              <ul>
                                  <li>Control launch URLs, UI mode, and message bridge behavior.</li>
                                  <li>Handle modal and permission prompts at the host layer.</li>
                                  <li>Integrate purchase calls from host-side business logic.</li>
                              </ul>
                              <p><a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">Open BrowserBox Embedder API documentation.</a></p>
                              <p><a href="https://github.com/BrowserBox/browserbox-api" target="_blank" rel="noopener noreferrer">Open BrowserBox Embedder API repository.</a></p>
                          </div>
                      </div>
                  `,
                  sessionsApi: `
                      <div class="bbx-help-page-inner">
                          <div class="bbx-help-body">
                              <h3>BrowserBox Sessions API</h3>
                              <p>The Sessions API supports creating and managing disposable or reusable browser sessions.</p>
                              <ul>
                                  <li>Create, inspect, and terminate sessions.</li>
                                  <li>Wire reconnect behavior into retry flows.</li>
                                  <li>Track session lifecycle to trigger upgrade or waitlist offers.</li>
                              </ul>
                              <p><a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">Open BrowserBox Sessions API documentation.</a></p>
                              <p>To expand session capacity, <a href="/pricing/" target="_blank" rel="noopener noreferrer">open pricing and minute packs.</a></p>
                          </div>
                      </div>
                  `,
                  repos: `
                      <div class="bbx-help-page-inner">
                          <div class="bbx-help-body">
                              <h3>BrowserBox Repositories</h3>
                              <p>Primary BrowserBox references:</p>
                              <ul>
                                  <li><a href="https://github.com/BrowserBox/browserbox-api" target="_blank" rel="noopener noreferrer">BrowserBox API</a></li>
                                  <li><a href="https://github.com/BrowserBox/BrowserBox-Demo" target="_blank" rel="noopener noreferrer">BrowserBox Demo</a></li>
                                  <li><a href="https://browserbox.io" target="_blank" rel="noopener noreferrer">browserbox.io</a></li>
                                  <li><a href="https://dosaygo.com" target="_blank" rel="noopener noreferrer">dosaygo.com</a></li>
                              </ul>
                          </div>
                      </div>
                  `,
                  licensing: `
                      <div class="bbx-help-page-inner">
                          <div class="bbx-help-body">
                              <h3>Licensing (AGPL-3.0)</h3>
                              <p>The BrowserBox SaaS desktop client-side app and the BrowserBox Webview API JavaScript are licensed as AGPL-3.0-or-later.</p>
                              <ul>
                                  <li><a href="https://www.gnu.org/licenses/agpl-3.0.html" target="_blank" rel="noopener noreferrer">GNU AGPL-3.0 license text</a></li>
                                  <li><a href="https://github.com/BrowserBox/browserbox-api" target="_blank" rel="noopener noreferrer">BrowserBox API repository</a></li>
                                  <li><a href="https://github.com/BrowserBox/BrowserBox-Demo" target="_blank" rel="noopener noreferrer">BrowserBox Demo repository</a></li>
                              </ul>
                          </div>
                      </div>
                  `,
              };

              const renderTopic = (topicId) => {
                  const html = pages[topicId] || pages.welcome;
                  pageEl.innerHTML = html;
                  topicButtons.forEach((button) => {
                      button.classList.toggle('active', button.dataset.topicId === topicId);
                  });
                  pageEl.scrollTop = 0;
                  pageEl.scrollLeft = 0;
              };

              topicButtons.forEach((button) => {
                  button.addEventListener('click', () => {
                      const topicId = button.dataset.topicId || 'welcome';
                      renderTopic(topicId);
                  });
              });

              renderTopic('welcome');
              return null;
          },
      },
      paymentTool: {
          title: 'BrowserBox HQ',
          icon: './tree-0.png',
          defaultWidth: 430,
          defaultHeight: 300,
          generateContent: () => `
              <div style="height:100%;display:flex;flex-direction:column;background:#c0c0c0;padding:10px;box-sizing:border-box;font-family:'MS Sans Serif',Tahoma,Arial,sans-serif;font-size:11px;">
                  <div style="margin-bottom:8px;font-weight:bold;">BrowserBox HQ</div>
                  <div style="margin-bottom:10px;line-height:1.35;">Open pricing, waitlist, and BrowserBox API documentation in a new tab.</div>
                  <div style="display:flex;flex-direction:column;gap:6px;border:1px inset #808080;background:#fff;padding:8px;overflow:auto;">
                      <a href="/pricing/" target="_blank" rel="noopener noreferrer">Buy Minutes</a>
                      <a href="/pricing/#persistent-waitlist" target="_blank" rel="noopener noreferrer">Persistent Session Waitlist</a>
                      <a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">BrowserBox Embedder API documentation</a>
                      <a href="https://win9-5.com/api/" target="_blank" rel="noopener noreferrer">BrowserBox Sessions API documentation</a>
                      <a href="https://github.com/BrowserBox/browserbox-api" target="_blank" rel="noopener noreferrer">BrowserBox API Repository</a>
                      <a href="https://github.com/BrowserBox/BrowserBox-Demo" target="_blank" rel="noopener noreferrer">BrowserBox Demo Repository</a>
                  </div>
              </div>
          `,
      },
      shutdownDialog: {
          title: "Shut Down Windows",
          isDialog: true,
          defaultWidth: 380,
          defaultHeight: 230,
          content: () => `
              <div class="shutdown-dialog-body" style="padding: 14px 16px 10px 16px; background:#c0c0c0; height:100%; display:flex; flex-direction:column; justify-content:space-between; box-sizing:border-box; font-family:'MS Sans Serif',Tahoma,Arial,sans-serif;">
                  <div style="display:flex; flex-direction:row; gap:12px; align-items:flex-start;">
                      <img src="./shut_down_with_computer-0.png" alt="" style="width:32px; height:32px; flex-shrink:0; margin-top:2px;">
                      <div style="flex:1;">
                          <p style="margin:2px 0 12px 0; font-size:11px; line-height:1.3;">What do you want the computer to do?</p>
                          <label style="display:block; margin-bottom:8px; font-size:11px; line-height:1;"><input type="radio" name="shutdownAction" value="shutdown" checked style="margin-right:6px; vertical-align:middle;"> Shut down</label>
                          <label style="display:block; margin-bottom:8px; font-size:11px; line-height:1;"><input type="radio" name="shutdownAction" value="restart" style="margin-right:6px; vertical-align:middle;"> Restart</label>
                          <label style="display:block; font-size:11px; line-height:1;"><input type="radio" name="shutdownAction" value="msdos" style="margin-right:6px; vertical-align:middle;"> Restart in MS-DOS mode</label>
                      </div>
                  </div>
                  <div style="display:flex; justify-content:flex-end; gap:10px; padding-top:14px;">
                      <button class="win95-button shutdown-ok-btn">OK</button>
                      <button class="win95-button shutdown-cancel-btn">Cancel</button>
                      <button class="win95-button shutdown-help-btn">Help</button>
                  </div>
              </div>
          `,
          initApp: (windowEl) => {
              const okBtn = windowEl.querySelector('.shutdown-ok-btn');
              const cancelBtn = windowEl.querySelector('.shutdown-cancel-btn');
              const helpBtn = windowEl.querySelector('.shutdown-help-btn');
              const closeBtn = windowEl.querySelector('.window-close-btn');

              const removeOverlay = () => {
                  const overlay = document.querySelector('.shutdown-overlay');
                  if (overlay) overlay.remove();
              };

              cancelBtn.addEventListener('click', () => {
                  removeOverlay();
                  closeBtn.click();
              });

              // Also remove overlay when closed via X button
              closeBtn.addEventListener('click', removeOverlay);

              helpBtn.addEventListener('click', () => {
                  alert('This dialog box enables you to shut down or restart your computer.');
              });

              okBtn.addEventListener('click', () => {
                  const selected = windowEl.querySelector('input[name="shutdownAction"]:checked');
                  const action = selected ? selected.value : 'shutdown';
                  removeOverlay();
                  closeBtn.click();
                  if (action === 'shutdown') {
                      document.open();
                      document.write('<html><body style="background:black;width:100vw;height:100vh;margin:0;"></body></html>');
                      document.close();
                  } else if (action === 'restart') {
                      location.reload();
                  } else if (action === 'msdos') {
                      soundManager.play('chord');
                      setTimeout(() => {
                          showMsdosModeErrorDialog();
                      }, 300);
                  }
              });
          }
      },
      internetConnectionWizard: {
          title: "Install New Modem",
          icon: "./internet_connection_wiz-0.png",
          isDialog: true,
          defaultWidth: 480,
          defaultHeight: 400,
          generateContent: () => `
              <style>
                  .modem-wizard { display:flex; flex-direction:column; height:100%; background:#d4d0c8; padding:0; font-family:"MS Sans Serif",Tahoma,Arial,sans-serif; font-size:11px; }
                  .modem-wizard .wizard-phase { min-height:0; background:#d4d0c8; display:none; flex-direction:column; flex:1; }
                  .modem-wizard .wizard-phase-1 { display:flex; }
                  .modem-wizard .wizard-body { display:flex; flex:1; min-height:0; overflow:hidden; background:#d4d0c8; }
                  .modem-wizard .wizard-hero {
                      width:164px;
                      min-width:164px;
                      border-top:1px solid #8f8f8f;
                      border-left:1px solid #8f8f8f;
                      border-right:1px solid #f3f3f3;
                      border-bottom:1px solid #f3f3f3;
                      background:#d4d0c8;
                      display:flex;
                      align-items:stretch;
                      justify-content:center;
                      margin:10px 0 0 10px;
                      box-sizing:border-box;
                  }
                  .modem-wizard .wizard-hero img { width:100%; height:100%; object-fit:cover; display:block; }
                  .modem-wizard .wizard-right { flex:1; padding:14px 14px 0 14px; display:flex; flex-direction:column; min-height:0; overflow-y:auto; background:#d4d0c8; }
                  .modem-wizard .wizard-copy { font-size:11px; color:#222; line-height:1.5; }
                  .modem-wizard .wizard-copy-list { margin-top:8px; margin-left:12px; line-height:1.7; }
                  .modem-wizard .wizard-copy-hint { margin-top:12px; }
                  .modem-wizard .wizard-optout { margin-top:auto; padding-bottom:6px; }
                  .modem-wizard .wizard-optout-label { font-size:11px; color:#808080; cursor:not-allowed; }
                  .modem-wizard .wizard-optout-checkbox { margin-right:4px; vertical-align:middle; }
                  .modem-wizard .wizard-copy-detect { margin-bottom:12px; }
                  .modem-wizard .wizard-inset-static { flex:0 0 auto; }
                  .modem-wizard .wizard-field-row { display:flex; align-items:center; }
                  .modem-wizard .wizard-field-row-spaced { margin-bottom:6px; }
                  .modem-wizard .wizard-label { width:60px; font-size:11px; }
                  .modem-wizard .wizard-copy-found { margin-bottom:10px; }
                  .modem-wizard .wizard-found-inset {
                      display:flex;
                      align-items:center;
                      gap:10px;
                      padding:14px 13px;
                      margin-top:14px;
                      background:#d4d0c8;
                      border:none;
                      box-shadow: inset 1px 1px #8f8f8f, inset -1px -1px #f6f6f6;
                  }
                  .modem-wizard .wizard-modem-icon { width:32px; height:32px; }
                  .modem-wizard .wizard-modem-name { font-weight:bold; font-size:11px; }
                  .modem-wizard .wizard-region-text { font-size:10px; color:#606060; margin-top:3px; }
                  .modem-wizard .wizard-dialing-status { display:none; margin-top:10px; font-size:11px; }
                  .modem-wizard .wizard-sep { height:1px; background:#808080; border-bottom:1px solid #dfdfdf; margin:8px 10px 0 10px; flex-shrink:0; }
                  .modem-wizard .wizard-buttons { display:flex; justify-content:flex-end; gap:6px; padding:8px 10px 10px 10px; flex-shrink:0; }
                  .modem-wizard .wizard-buttons .win95-button {
                      min-width:75px;
                      padding:2px 12px;
                      font-size:11px;
                      font-family:inherit;
                      box-shadow: inset -1px -1px #353535, inset 1px 1px #ffffff, inset -2px -2px #767676, inset 2px 2px #f4f4f4;
                  }
                  .modem-wizard .wizard-buttons .win95-button:disabled { color:#808080; }
                  .modem-wizard .wizard-inset { border:none; background:transparent; padding:0; }
                  .modem-wizard .wizard-field {
                      border-top:1px solid #8f8f8f;
                      border-left:1px solid #8f8f8f;
                      border-right:1px solid #f3f3f3;
                      border-bottom:1px solid #f3f3f3;
                      background:#d4d0c8;
                      padding:2px 4px;
                      font-size:11px;
                      flex:1;
                      box-sizing:border-box;
                  }
                  .modem-wizard .wizard-progress-container {
                      border-top:1px solid #8f8f8f;
                      border-left:1px solid #8f8f8f;
                      border-right:1px solid #f3f3f3;
                      border-bottom:1px solid #f3f3f3;
                      background:#d4d0c8;
                      height:20px;
                      padding:2px;
                      margin-top:0;
                      box-sizing:border-box;
                  }
                  .modem-wizard .wizard-progress-bottom { margin-top:auto; }
                  .modem-wizard .wizard-progress-bar {
                      height:100%;
                      width:100%;
                      display:flex;
                      align-items:stretch;
                      gap:1px;
                      background:#d4d0c8;
                  }
                  .modem-wizard .wizard-progress-block {
                      flex:1 1 0;
                      min-width:0;
                      background:#d4d0c8;
                  }
                  .modem-wizard .wizard-progress-block.active {
                      background:#000080;
                  }
                  @media screen and (max-width: 480px) {
                      .modem-wizard .wizard-hero { display:none; }
                  }
              </style>
              <div class="modem-wizard">
                  <!-- Phase 1: Pre-detection prompt -->
                  <div class="wizard-phase wizard-phase-1">
                      <div class="wizard-body">
                          <div class="wizard-hero"><img src="./modem-hero-inset.png" alt=""></div>
                          <div class="wizard-right">
                              <div class="wizard-copy">
                                  Windows will now try to detect your modem. Before continuing, you should:
                              </div>
                              <div class="wizard-copy wizard-copy-list">
                                  1. If the modem is attached to your<br>&nbsp;&nbsp;&nbsp;computer, make sure it is turned on.<br>
                                  2. Quit any programs that may be using<br>&nbsp;&nbsp;&nbsp;the modem.
                              </div>
                              <div class="wizard-copy wizard-copy-hint">
                                  Click Next when you are ready to continue.
                              </div>
                              <div class="wizard-optout">
                                  <label class="wizard-optout-label">
                                      <input class="wizard-optout-checkbox" type="checkbox" disabled>
                                      Don't detect my modem; I will select it from a list
                                  </label>
                              </div>
                          </div>
                      </div>
                      <div class="wizard-sep"></div>
                      <div class="wizard-buttons">
                          <button class="win95-button" disabled>&lt; Back</button>
                          <button class="win95-button wizard-next-btn">Next &gt;</button>
                          <button class="win95-button wizard-cancel-btn">Cancel</button>
                      </div>
                  </div>

                  <!-- Phase 2: Detection in progress -->
                  <div class="wizard-phase wizard-phase-2">
                      <div class="wizard-body">
                          <div class="wizard-hero"><img src="./modem-hero-inset.png" alt=""></div>
                          <div class="wizard-right">
                              <div class="wizard-copy wizard-copy-detect">
                                  Please wait while Windows attempts to detect your modem. This may take several minutes.
                              </div>
                              <div class="wizard-inset wizard-inset-static">
                                  <div class="wizard-field-row wizard-field-row-spaced">
                                      <span class="wizard-label">Checking:</span>
                                      <span class="wizard-field wizard-port-name">Communications Port (COM1)</span>
                                  </div>
                                  <div class="wizard-field-row">
                                      <span class="wizard-label">Status:</span>
                                      <span class="wizard-field wizard-status-text">Looking for a modem...</span>
                                  </div>
                              </div>
                              <div class="wizard-progress-container wizard-progress-bottom">
                                  <div class="wizard-progress-bar"></div>
                              </div>
                          </div>
                      </div>
                      <div class="wizard-sep"></div>
                      <div class="wizard-buttons">
                          <button class="win95-button" disabled>&lt; Back</button>
                          <button class="win95-button" disabled>Next &gt;</button>
                          <button class="win95-button wizard-cancel-btn">Cancel</button>
                      </div>
                  </div>

                  <!-- Phase 3: Modem found -->
                  <div class="wizard-phase wizard-phase-3">
                      <div class="wizard-body">
                          <div class="wizard-hero"><img src="./modem-hero-inset.png" alt=""></div>
                          <div class="wizard-right">
                              <div class="wizard-copy wizard-copy-found">
                                  Windows found the following modem attached to your computer:
                              </div>
                              <div class="wizard-inset wizard-found-inset">
                                  <img class="wizard-modem-icon" src="./modem-4.png" alt="">
                                  <div>
                                      <div class="wizard-modem-name">DoSayGo BrowserBox HighSpeed 28800 bps Modem</div>
                                      <div class="wizard-region-text">Connected via us-central1</div>
                                  </div>
                              </div>
                              <div class="wizard-dialing-status">
                                  <span class="wizard-dialing-text">Dialing...</span>
                              </div>
                          </div>
                      </div>
                      <div class="wizard-sep"></div>
                      <div class="wizard-buttons">
                          <button class="win95-button" disabled>&lt; Back</button>
                          <button class="win95-button wizard-finish-btn">Connect</button>
                          <button class="win95-button wizard-cancel-btn">Cancel</button>
                      </div>
                  </div>
              </div>
          `
      },
      internetBrowser: {
          // netscape: true, // This was in your provided app.js, BrowserApp constructor now has netscapeFlag_unused
          title: "Internet Browser",
          icon: "./search_web-0.png",
          defaultWidth: 700,
          defaultHeight: 500,
          generateContent: (windowInstanceId, webviewId, launchData) => BrowserApp.generateInitialHTML(webviewId, launchData),
          initApp: (windowEl, windowInstanceId, webviewId, appDefinition) => {
              // Assuming BrowserApp's 4th param is netscape-like flag.
              // For "Internet Browser", let's assume it's NOT Netscape-styled.
              const app = new BrowserApp(windowEl, windowInstanceId, webviewId, false, appDefinition);
              instrumentBrowserApp(app);
              return app;
          }
      },
      internetExplorer: {
          // netscape: false, // This was in your provided app.js
          title: "Internet Explorer",
          icon: "./msie2-0.png",
          defaultWidth: 700,
          defaultHeight: 500,
          generateContent: (windowInstanceId, webviewId, launchData) => BrowserApp.generateInitialHTML(webviewId, launchData),
          initApp: (windowEl, windowInstanceId, webviewId, appDefinition) => {
              const app = new BrowserApp(windowEl, windowInstanceId, webviewId, false, appDefinition);
              instrumentBrowserApp(app);
              return app;
          }
      },
      netscapeNavigator: {
          // netscape: true, // This was in your provided app.js
          title: "Netscape Navigator",
          icon: "./n2-2.png",
          defaultWidth: 700,
          defaultHeight: 500,
          generateContent: (windowInstanceId, webviewId, launchData) => BrowserApp.generateInitialHTML(webviewId, launchData),
          initApp: (windowEl, windowInstanceId, webviewId, appDefinition) => {
              const app = new BrowserApp(windowEl, windowInstanceId, webviewId, true, appDefinition); // Pass true for Netscape style
              instrumentBrowserApp(app);
              return app;
          }
      },
  };
  window.APP_DEFINITIONS = APP_DEFINITIONS;
  const BROWSER_APP_IDS = new Set(['internetBrowser', 'internetExplorer', 'netscapeNavigator']);

  function debounce(func, wait) { /* ... (same as your latest) ... */
      let timeout;
      return function executedFunction(...args) {
          const context = this;
          const later = () => { timeout = null; func.apply(context, args); };
          clearTimeout(timeout);
          timeout = setTimeout(later, wait);
      };
  }
  function getLuminance(hexColor) { /* ... (same as your latest) ... */
      if (!hexColor) return 0;
      hexColor = hexColor.replace('#', '');
      if (hexColor.length === 3) hexColor = hexColor.split('').map(char => char + char).join('');
      if (hexColor.length !== 6) return 0;
      const r = parseInt(hexColor.substring(0, 2), 16);
      const g = parseInt(hexColor.substring(2, 4), 16);
      const b = parseInt(hexColor.substring(4, 6), 16);
      return 0.2126 * r + 0.7152 * g + 0.0722 * b;
  }
  function updateThemeForDesktopBackground(desktopBgColor) { /* ... (same as your latest) ... */
      const rootStyle = document.documentElement.style;
      rootStyle.setProperty('--desktop-bg-color', desktopBgColor);
      const luminance = getLuminance(desktopBgColor);
      const newIconTextColor = (luminance > 128) ? 'black' : 'white';
      rootStyle.setProperty('--desktop-icon-text-color', newIconTextColor);
  }
  window.updateThemeForDesktopBackground = updateThemeForDesktopBackground;

  function updateStartMenuItemsState() { /* ... (same as your latest) ... */
    const startMenu = document.getElementById('startMenu');
    if (!startMenu) return;
    const startMenuItems = startMenu.querySelectorAll('.start-menu-item[data-app-id]');
    startMenuItems.forEach(item => {
        item.style.display = '';
        item.classList.remove('disabled');
        item.style.opacity = '1';
        item.style.pointerEvents = 'auto';
    });
  }
  window.Win9xSystem = window.Win9xSystem || {};
  window.Win9xSystem.updateStartMenuItemsState = updateStartMenuItemsState;

  async function preloadAppImages(onProgress) {
      const imageUrls = [];
      Object.values(window.APP_DEFINITIONS || {}).forEach(appDef => {
          if (appDef.icon && !imageUrls.includes(appDef.icon)) imageUrls.push(appDef.icon);
          if (appDef.iconFull && !imageUrls.includes(appDef.iconFull)) imageUrls.push(appDef.iconFull);
          if (appDef.menuBar) {
              appDef.menuBar.forEach(menu => {
                  menu.items.forEach(item => {
                      if (item.icon && !imageUrls.includes(item.icon)) imageUrls.push(item.icon);
                  });
              });
          }
      });
      // Use your refined list of icons
      const explicitIconUrls = [
          './internet_connection_wiz-0.png', './browser-toolbar-icons-color.png', './browser-toolbar-icons-gray.png',
          './calculator-0.png', './channels-4.png', './computer_2-1.png',
          // './computer_explorer-0.png', // My Computer icon, removed
          './directory_closed_cool-0.png', './directory_open_cool-0.png',
          './entire_network_globe-0.png',
          './globe_map-0.png', './globe_map-1.png', './help_book_cool-0.png', './help_book_small-1.png', './help_book_cool_small-1.png',
          './html-0.png', './file_win_shortcut-0.png', './document-0.png', './paint_file-2.png', './loudspeaker_wave-0.png',
          './msie2-0.png', './Internet_Explorer_gif.webp', './n1.png', './n2-2.png', './n2.png', './n3.png', './n4.png',
          './msn2-1.png',
          './netscape-frame.gif', './netscape.gif', './network_cool_2pcs-4.png',
          './network_normal_two_pcs-0.png', './network_three_pcs-0.png', './notepad-0.png',
          './windows_update_old-0.png', './directory_open_cabinet_fc-1.png', './file_program_group-1.png',
          './directory_favorites_small-1.png', './directory_open_file_mydocs_small-1.png',
          './settings_gear-1.png', './search_web-1.png', './application_hourglass-1.png',
          './key_win_alt-0.png', './outlook_express-1.png', './desktop_old-4.png',
          './directory_folder_options-1.png', './netshow_arrow-1.png',
          './recycle_bin_empty-0.png', './recycle_bin_empty_cool-0.png',
          './recycle_bin_full_cool-0.png', './search_web-0.png', './settings_gear-0.png',
          './tree-0.png', './help_sheet-0.png', './help_book_small-4.png', './help_question_mark-0.png',
          './shut_down_normal-0.png', './template_world-4.png', './shut_down_with_computer-0.png',
          './windows-0.png',
      ];
      explicitIconUrls.forEach(url => { if (!imageUrls.includes(url)) imageUrls.push(url); });

      let loadedCount = 0;
      const totalAssets = imageUrls.length;
      if (totalAssets === 0) {
          if (typeof onProgress === 'function') onProgress(100);
          return Promise.resolve();
      }
      const promises = imageUrls.map(src => {
          return new Promise((resolve) => {
              if (src.startsWith('http://') || src.startsWith('https://')) {
                  loadedCount++;
                  if (typeof onProgress === 'function') onProgress((loadedCount / totalAssets) * 100);
                  resolve(); return;
              }
              const img = new Image();
              img.onload = img.onerror = () => {
                  if (img.onerror && !img.onload && !img.src.endsWith('.gif')) {
                       console.warn(`Failed to preload image: ${src}`);
                  }
                  loadedCount++;
                  if (typeof onProgress === 'function') onProgress((loadedCount / totalAssets) * 100);
                  resolve();
              };
              img.src = src;
          });
      });
      return Promise.all(promises);
  }

  document.addEventListener('DOMContentLoaded', async () => {
      console.log("DOM fully loaded and parsed. Starting app initialization...");
      if (window.SPLASH_API) window.SPLASH_API.setProgress(5);
      if (new URLSearchParams(window.location.search).has('debugsplash') && window.SPLASH_API && window.SPLASH_API.showDebugControls) {
          window.SPLASH_API.showDebugControls();
      }

      const clockElement = document.getElementById('clock');
      const startButton = document.getElementById('startButton');
      const startMenu = document.getElementById('startMenu');
      const desktop = document.getElementById('desktop');
      const windowTemplate = document.getElementById('windowTemplate');
      const taskbarWindows = document.getElementById('taskbarWindows');
      const quickLaunch = document.getElementById('quickLaunch');

      let highestZIndex = 100;
      const openWindows = {};
      let windowIdCounter = 0;
      window.openWindows = openWindows;
      window.focusWindow = focusWindow;
      const browserSessionClient = new BrowserBoxClient();
      const browserSessionState = {
          phase: 'idle', // idle | launching | ready
          pending: null,
          session: null,
          canceled: false,
          heartbeatTimer: null,
          connectivityProbeTimer: null,
          connectivityProbeInFlight: false,
          connectivityProbeFailures: 0,
          pendingAppId: 'internetExplorer', // Which browser app to launch
      };
      const HEARTBEAT_INTERVAL_MS = 5000;
      const CONNECTIVITY_PROBE_INTERVAL_MS = 12000;
      const CONNECTIVITY_PROBE_TIMEOUT_MS = 8000;
      const CONNECTIVITY_PROBE_FAILURE_THRESHOLD = 2;
      const CONNECTIVITY_WARNING_MIN_REMAINING_MS = 45000;
      let handlingSessionExpiry = false;

      // --- Heartbeat lifecycle management ---
      function startHeartbeat(sessionId) {
          stopHeartbeat();
          if (!sessionId) return;

          const sendHeartbeat = () => {
              browserSessionClient.sendHeartbeat(sessionId).catch(err => {
                  if (err?.code === 'SESSION_EXPIRED') {
                      console.warn('[heartbeat] Session expired/unauthorized; ending local session.');
                      handleSessionExpired();
                      return;
                  }
                  console.warn('[heartbeat] Failed:', err);
              });
          };

          sendHeartbeat();
          browserSessionState.heartbeatTimer = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL_MS);
          startConnectivityProbe();

          document.addEventListener('visibilitychange', onVisibilityChange);
          window.addEventListener('beforeunload', onBeforeUnload);
          window.addEventListener('pagehide', onBeforeUnload);
      }

      function stopHeartbeat() {
          if (browserSessionState.heartbeatTimer) {
              clearInterval(browserSessionState.heartbeatTimer);
              browserSessionState.heartbeatTimer = null;
          }
          stopConnectivityProbe();
          document.removeEventListener('visibilitychange', onVisibilityChange);
          window.removeEventListener('beforeunload', onBeforeUnload);
          window.removeEventListener('pagehide', onBeforeUnload);
      }

      function startConnectivityProbe() {
          stopConnectivityProbe();
          browserSessionState.connectivityProbeTimer = setInterval(() => {
              void runConnectivityProbe();
          }, CONNECTIVITY_PROBE_INTERVAL_MS);
          void runConnectivityProbe();
      }

      function stopConnectivityProbe() {
          if (browserSessionState.connectivityProbeTimer) {
              clearInterval(browserSessionState.connectivityProbeTimer);
              browserSessionState.connectivityProbeTimer = null;
          }
          browserSessionState.connectivityProbeInFlight = false;
          browserSessionState.connectivityProbeFailures = 0;
      }

      async function runConnectivityProbe() {
          if (handlingSessionExpiry || browserSessionState.connectivityProbeInFlight) return;
          if (browserSessionState.phase !== 'ready' || !browserSessionState.session?.sessionId) return;
          if (document.getElementById('sessionExpiredOverlay') || document.getElementById('connectionFailedOverlay')) return;

          const remainingMs = sessionTimer.getRemainingMs();
          if (remainingMs > 0 && remainingMs <= CONNECTIVITY_WARNING_MIN_REMAINING_MS) {
              return;
          }

          const openBrowserWindow = findExistingBrowserWindow();
          if (!openBrowserWindow || !openBrowserWindow.element) return;

          const webviewEl = openBrowserWindow.element.querySelector('browserbox-webview');
          if (
              !webviewEl
              || (typeof webviewEl.health !== 'function' && typeof webviewEl.getTabCount !== 'function')
          ) return;

          browserSessionState.connectivityProbeInFlight = true;

          try {
              if (typeof webviewEl.health === 'function') {
                  await webviewEl.health({ timeoutMs: CONNECTIVITY_PROBE_TIMEOUT_MS });
              } else {
                  await Promise.race([
                      webviewEl.getTabCount(),
                      new Promise((_, reject) => {
                          setTimeout(() => {
                              reject(new Error(`Connectivity probe timed out after ${CONNECTIVITY_PROBE_TIMEOUT_MS}ms`));
                          }, CONNECTIVITY_PROBE_TIMEOUT_MS);
                      }),
                  ]);
              }
              browserSessionState.connectivityProbeFailures = 0;
              return;
          } catch (error) {
              browserSessionState.connectivityProbeFailures += 1;
              if (browserSessionState.connectivityProbeFailures < CONNECTIVITY_PROBE_FAILURE_THRESHOLD) {
                  return;
              }

              const status = await browserSessionClient.checkStatus().catch(() => null);
              if (!status?.activeSession) {
                  handleSessionExpired();
                  return;
              }

              const statusRemainingMs = Number(status.activeSession.remainingMs) || 0;
              if (statusRemainingMs > 0 && statusRemainingMs <= CONNECTIVITY_WARNING_MIN_REMAINING_MS) {
                  return;
              }

              if (typeof webviewEl.stopReconnectAttempts === 'function') {
                  webviewEl.stopReconnectAttempts('connectivity-probe');
              }
              showConnectionFailedDialog(openBrowserWindow.appId || browserSessionState.pendingAppId || 'internetExplorer');
              browserSessionState.connectivityProbeFailures = 0;
          } finally {
              browserSessionState.connectivityProbeInFlight = false;
          }
      }

      function onVisibilityChange() {
          if (!browserSessionState.session?.sessionId) return;
          if (!document.hidden) {
              browserSessionClient.sendHeartbeat(browserSessionState.session.sessionId).catch(() => {});
          }
      }

      function onBeforeUnload() {
          if (!browserSessionState.session?.sessionId) return;
          browserSessionClient.notifyDisconnect(browserSessionState.session.sessionId);
      }

      function handleSessionExpired() {
          if (handlingSessionExpiry) return;
          handlingSessionExpiry = true;
          soundManager.play('chord');

          // Stop heartbeat
          stopHeartbeat();
          sessionTimer.stop();

          // Stop auto-reconnect loops in embedded BrowserBox webviews.
          Object.values(openWindows).forEach(winData => {
              if (!winData || !BROWSER_APP_IDS.has(winData.appId)) return;
              const webviewEl = winData.element?.querySelector?.('browserbox-webview');
              if (typeof webviewEl?.stopReconnectAttempts === 'function') {
                  webviewEl.stopReconnectAttempts('session-expired');
              }
          });

          // Reset session state
          browserSessionState.phase = 'idle';
          browserSessionState.session = null;
          document.getElementById('connectionFailedOverlay')?.remove();

          // Show expiry dialog
          showSessionExpiredDialog();
          handlingSessionExpiry = false;
      }

      function closeAllBrowserWindows() {
          Object.values(openWindows).forEach(winData => {
              if (winData && BROWSER_APP_IDS.has(winData.appId)) {
                  closeWindow(winData.element);
              }
          });
      }

      class DesktopSystemDialog {
          static show({
              overlayId,
              title,
              iconSrc,
              leadText,
              bodyText,
              buttons = [],
          }) {
              const existingOverlay = document.getElementById(overlayId);
              if (existingOverlay) {
                  return existingOverlay;
              }

              const overlay = document.createElement('div');
              overlay.id = overlayId;
              overlay.style.cssText = `
                  position: fixed; top: 0; left: 0; right: 0; bottom: 0;
                  background: rgba(0,0,0,0.5); z-index: 100000;
                  display: flex; align-items: center; justify-content: center;
              `;

              const dialog = document.createElement('div');
              dialog.style.cssText = `
                  background: #c0c0c0; border: 2px outset #dfdfdf;
                  padding: 0; min-width: min(280px, calc(100vw - 24px)); width: min(680px, calc(100vw - 24px));
                  max-width: calc(100vw - 24px); box-shadow: 4px 4px 10px rgba(0,0,0,0.3);
              `;

              const titleBar = document.createElement('div');
              titleBar.style.cssText = 'background: linear-gradient(to right, #000080, #1084d0); color: white; padding: 3px 6px; font-weight: bold; font-size: 12px;';
              titleBar.textContent = title;

              const content = document.createElement('div');
              content.style.cssText = 'padding: 16px; text-align: center;';

              const row = document.createElement('div');
              row.style.cssText = 'display: flex; gap: 15px; align-items: flex-start; margin-bottom: 16px; min-width: 0;';

              const icon = document.createElement('img');
              icon.src = iconSrc;
              icon.alt = '';
              icon.style.cssText = 'width: 32px; height: 32px;';

              const textWrap = document.createElement('div');
              textWrap.style.cssText = 'text-align: left; font-size: 12px; line-height: 1.5; flex: 1 1 auto; min-width: 0; overflow-wrap: anywhere;';

              const lead = document.createElement('p');
              lead.style.cssText = 'margin: 0 0 8px 0; font-weight: bold;';
              lead.textContent = leadText;

              const body = document.createElement('p');
              body.style.cssText = 'margin: 0; color: #444;';
              body.textContent = bodyText;

              textWrap.appendChild(lead);
              textWrap.appendChild(body);
              row.appendChild(icon);
              row.appendChild(textWrap);
              content.appendChild(row);

              const actions = document.createElement('div');
              actions.style.cssText = 'display: flex; gap: 8px 10px; justify-content: center; flex-wrap: wrap; width: 100%;';

              buttons.forEach(buttonDef => {
                  const button = document.createElement('button');
                  button.className = 'win95-button';
                  button.style.minWidth = '96px';
                  button.style.maxWidth = '180px';
                  button.style.flex = '1 1 110px';
                  button.style.margin = '2px 0';
                  button.textContent = buttonDef.label;
                  button.addEventListener('click', () => buttonDef.onClick?.(overlay));
                  actions.appendChild(button);
              });

              content.appendChild(actions);
              dialog.appendChild(titleBar);
              dialog.appendChild(content);
              overlay.appendChild(dialog);
              document.body.appendChild(overlay);

              return overlay;
          }
      }

      function showSessionExpiredDialog() {
          const overlay = DesktopSystemDialog.show({
              overlayId: 'sessionExpiredOverlay',
              title: 'Session Ended',
              iconSrc: './application_hourglass-0.png',
              leadText: 'This browser session has ended.',
              bodyText: 'Start another session, buy minute packs, or join the persistent-session waitlist.',
              buttons: [
                  {
                      label: 'Start Another',
                      onClick: (activeOverlay) => {
                          activeOverlay.remove();
                          openApplication('internetExplorer');
                      },
                  },
                  {
                      label: 'Buy Minutes',
                      onClick: (activeOverlay) => {
                          activeOverlay.remove();
                          openPricingSurface();
                      },
                  },
                  {
                      label: 'Waitlist',
                      onClick: (activeOverlay) => {
                          activeOverlay.remove();
                          openPricingSurface('persistent-waitlist');
                      },
                  },
                  {
                      label: 'Close',
                      onClick: (activeOverlay) => {
                          activeOverlay.remove();
                      },
                  },
              ],
          });
          if (!overlay) return;

          closeAllBrowserWindows();
      }

      function showConnectionFailedDialog(appId = 'internetExplorer') {
          if (document.getElementById('sessionExpiredOverlay')) {
              return;
          }
          DesktopSystemDialog.show({
              overlayId: 'connectionFailedOverlay',
              title: 'Connection Failed',
              iconSrc: './network_normal_two_pcs-0.png',
              leadText: 'Could not connect to BrowserBox.',
              bodyText: 'Retry to reconnect, or open pricing/waitlist options if you need longer or persistent access.',
              buttons: [
                  {
                      label: 'Retry',
                      onClick: (activeOverlay) => {
                          activeOverlay.remove();
                          closeAllBrowserWindows();
                          openApplication(appId);
                      },
                  },
                  {
                      label: 'Create New',
                      onClick: (activeOverlay) => {
                          activeOverlay.remove();
                          openApplication(appId);
                      },
                  },
                  {
                      label: 'Buy Minutes',
                      onClick: (activeOverlay) => {
                          activeOverlay.remove();
                          openPricingSurface();
                      },
                  },
                  {
                      label: 'Waitlist',
                      onClick: (activeOverlay) => {
                          activeOverlay.remove();
                          openPricingSurface('persistent-waitlist');
                      },
                  },
                  {
                      label: 'Close',
                      onClick: (activeOverlay) => {
                          activeOverlay.remove();
                      },
                  },
              ],
          });
      }

      function openPricingSurface(hash = '') {
          const pricingUrl = new URL('/pricing/', window.location.origin);
          if (hash) pricingUrl.hash = hash;
          const opened = window.open(pricingUrl.toString(), '_blank', 'noopener,noreferrer');
          if (!opened) {
              setTimeout(() => {
                  window.location.assign(pricingUrl.toString());
              }, 150);
          }
      }

      function findOpenWindowByAppId(appId) {
          return Object.values(openWindows).find((winData) => (
              winData &&
              winData.appId === appId &&
              winData.element &&
              document.body.contains(winData.element)
          )) || null;
      }

      function findExistingBrowserWindow(appId = null) {
          return Object.values(openWindows).find((winData) => (
              winData &&
              BROWSER_APP_IDS.has(winData.appId) &&
              (!appId || winData.appId === appId) &&
              winData.element &&
              document.body.contains(winData.element)
          )) || null;
      }

      function closeConnectionWizard() {
          const existingWizard = findOpenWindowByAppId('internetConnectionWizard');
          if (existingWizard && existingWizard.element) {
              closeWindow(existingWizard.element);
          }
      }

      function showConnectionWizard() {
          let wizardWindow = findOpenWindowByAppId('internetConnectionWizard');
          if (!wizardWindow) {
              const wizardElement = createWindow('internetConnectionWizard');
              if (!wizardElement) {
                  return null;
              }
              wizardWindow = openWindows[wizardElement.dataset.instanceId];
          } else {
              focusWindow(wizardWindow.element);
          }

          const wizardEl = wizardWindow.element;
          const phase1 = wizardEl.querySelector('.wizard-phase-1');
          const phase2 = wizardEl.querySelector('.wizard-phase-2');
          const phase3 = wizardEl.querySelector('.wizard-phase-3');
          const portNameEl = wizardEl.querySelector('.wizard-port-name');
          const statusTextEl = wizardEl.querySelector('.wizard-status-text');
          const regionTextEl = wizardEl.querySelector('.wizard-region-text');
          const dialingStatusEl = wizardEl.querySelector('.wizard-dialing-status');
          const progressBarEl = wizardEl.querySelector('.wizard-progress-bar');
          const PROGRESS_TOTAL_BLOCKS = 18;
          const PROGRESS_TOTAL_MS = 45000;
          const PROGRESS_NORMAL_DELAY_MS = Math.max(100, Math.round(PROGRESS_TOTAL_MS / PROGRESS_TOTAL_BLOCKS));
          const PROGRESS_SPEEDRUN_DELAY_MS = 100;
          const DIALING_DOT_INTERVAL_MS = 700;
          let progressBlocks = [];
          let progressBlockIndex = 0;
          let progressDelayMs = PROGRESS_NORMAL_DELAY_MS;
          let progressWaiters = [];

          // Wire cancel buttons
          wizardEl.querySelectorAll('.wizard-cancel-btn').forEach(btn => {
              if (!btn.dataset.wired) {
                  btn.dataset.wired = '1';
                  btn.addEventListener('click', () => {
                      stopDialingDots();
                      stopPortCyclingTimers();
                      resolveProgressWaiters();
                      if (browserSessionState.phase === 'launching') {
                          browserSessionState.canceled = true;
                      }
                      closeConnectionWizard();
                  });
              }
          });

          const closeBtn = wizardEl.querySelector('.window-close-btn');
          if (closeBtn && !closeBtn.dataset.wizardWired) {
              closeBtn.dataset.wizardWired = '1';
              closeBtn.addEventListener('click', () => {
                  stopDialingDots();
                  stopPortCyclingTimers();
                  resolveProgressWaiters();
                  if (browserSessionState.phase === 'launching') {
                      browserSessionState.canceled = true;
                  }
              });
          }

          const ports = [
              'Communications Port (COM1)',
              'Communications Port (COM2)',
              'Serial Port (COM3)',
              'USB Bus (COM4)'
          ];
          const statuses = [
              'Looking for a modem...',
              'Querying device...',
              'Reading configuration...',
              'Checking baud rate...'
          ];
          let portCycleTimer = null;
          let progressTimer = null;
          let dialingDotsTimer = null;

          function renderProgressBlocks() {
              if (!progressBarEl) return;
              progressBarEl.textContent = '';
              progressBlocks = [];
              for (let i = 0; i < PROGRESS_TOTAL_BLOCKS; i++) {
                  const block = document.createElement('div');
                  block.className = 'wizard-progress-block';
                  progressBarEl.appendChild(block);
                  progressBlocks.push(block);
              }
          }

          function resolveProgressWaiters() {
              progressWaiters.forEach((resolve) => resolve());
              progressWaiters = [];
          }

          function waitForProgressComplete() {
              if (progressBlockIndex >= PROGRESS_TOTAL_BLOCKS) {
                  return Promise.resolve();
              }
              return new Promise((resolve) => {
                  progressWaiters.push(resolve);
              });
          }

          function setProgressBlockCount(count) {
              const boundedCount = Math.max(0, Math.min(PROGRESS_TOTAL_BLOCKS, count));
              progressBlockIndex = boundedCount;
              progressBlocks.forEach((block, index) => {
                  block.classList.toggle('active', index < boundedCount);
              });
              if (progressBlockIndex >= PROGRESS_TOTAL_BLOCKS) {
                  if (statusTextEl) statusTextEl.textContent = 'Verifying modem response...';
                  if (portCycleTimer) {
                      clearInterval(portCycleTimer);
                      portCycleTimer = null;
                  }
                  resolveProgressWaiters();
              }
          }

          function scheduleProgressTick() {
              if (progressTimer) {
                  clearTimeout(progressTimer);
                  progressTimer = null;
              }
              if (progressBlockIndex >= PROGRESS_TOTAL_BLOCKS) {
                  return;
              }
              progressTimer = setTimeout(() => {
                  if (!wizardEl || !document.body.contains(wizardEl)) {
                      stopPortCyclingTimers();
                      resolveProgressWaiters();
                      progressTimer = null;
                      return;
                  }
                  setProgressBlockCount(progressBlockIndex + 1);
                  progressTimer = null;
                  if (progressBlockIndex < PROGRESS_TOTAL_BLOCKS) {
                      scheduleProgressTick();
                  }
              }, progressDelayMs);
          }

          function stopPortCyclingTimers() {
              if (portCycleTimer) {
                  clearInterval(portCycleTimer);
                  portCycleTimer = null;
              }
              if (progressTimer) {
                  clearTimeout(progressTimer);
                  progressTimer = null;
              }
          }

          function stopDialingDots() {
              if (dialingDotsTimer) {
                  clearInterval(dialingDotsTimer);
                  dialingDotsTimer = null;
              }
          }

          // Convert an IPv4 address to a (xxx) xxx-xxxx phone number
          function ipToPhone(ip) {
              const parts = (ip || '0.0.0.0').split('.').map(Number);
              const num = ((parts[0] << 24) + (parts[1] << 16) + (parts[2] << 8) + parts[3]) >>> 0;
              const digits = String(num).padStart(10, '0').slice(-10);
              return `(${digits.slice(0,3)}) ${digits.slice(3,6)}-${digits.slice(6)}`;
          }

          // Fetch user IP and cache it on the wizard element
          async function fetchUserIP() {
              if (wizardEl._cachedPhone) return wizardEl._cachedPhone;
              try {
                  const params = new URLSearchParams(window.location.search);
                  const hintedIP = params.get('client_ip') || params.get('ip');
                  if (hintedIP) {
                      wizardEl._cachedPhone = ipToPhone(hintedIP);
                      return wizardEl._cachedPhone;
                  }
                  const resp = await fetch('https://api.ipify.org?format=json');
                  const data = await resp.json();
                  wizardEl._cachedPhone = ipToPhone(data.ip);
              } catch {
                  wizardEl._cachedPhone = '(555) 019-8100';
              }
              return wizardEl._cachedPhone;
          }

          // Fire-and-forget IP fetch so it's ready by phase 3
          fetchUserIP();
          renderProgressBlocks();

          return {
              showPhase(phaseNum) {
                  if (phase1) phase1.style.display = phaseNum === 1 ? 'flex' : 'none';
                  if (phase2) phase2.style.display = phaseNum === 2 ? 'flex' : 'none';
                  if (phase3) phase3.style.display = phaseNum === 3 ? 'flex' : 'none';
              },

              startPortCycling() {
                  stopDialingDots();
                  stopPortCyclingTimers();
                  let portIndex = 0;
                  let statusIndex = 0;
                  progressDelayMs = PROGRESS_NORMAL_DELAY_MS;
                  setProgressBlockCount(1);
                  scheduleProgressTick();

                  const cycle = () => {
                      if (!wizardEl || !document.body.contains(wizardEl)) {
                          stopPortCyclingTimers();
                          resolveProgressWaiters();
                          return;
                      }

                      if (portNameEl) portNameEl.textContent = ports[portIndex];
                      if (statusTextEl) statusTextEl.textContent = statuses[statusIndex];

                      statusIndex = (statusIndex + 1) % statuses.length;
                      if (statusIndex === 0) {
                          portIndex = (portIndex + 1) % ports.length;
                      }
                  };

                  cycle();
                  portCycleTimer = setInterval(cycle, 800);
              },

              async completePortCycling() {
                  if (progressBlockIndex < PROGRESS_TOTAL_BLOCKS) {
                      progressDelayMs = PROGRESS_SPEEDRUN_DELAY_MS;
                      scheduleProgressTick();
                  }
                  await waitForProgressComplete();
              },

              stopPortCycling() {
                  stopPortCyclingTimers();
                  resolveProgressWaiters();
              },

              showModemFound(region) {
                  this.stopPortCycling();
                  if (regionTextEl) regionTextEl.textContent = `Connected via ${region || 'auto'}`;
                  this.showPhase(3);
              },

              async showDialing() {
                  stopDialingDots();
                  const phone = await fetchUserIP();
                  const dialingTextEl = wizardEl.querySelector('.wizard-dialing-text');
                  if (dialingTextEl) {
                      let dotCount = 1;
                      dialingTextEl.textContent = `Dialing ${phone}${'.'.repeat(dotCount)}`;
                      dialingDotsTimer = setInterval(() => {
                          if (!wizardEl || !document.body.contains(wizardEl)) {
                              stopDialingDots();
                              return;
                          }
                          dotCount = dotCount >= 3 ? 1 : dotCount + 1;
                          dialingTextEl.textContent = `Dialing ${phone}${'.'.repeat(dotCount)}`;
                      }, DIALING_DOT_INTERVAL_MS);
                  }
                  if (dialingStatusEl) dialingStatusEl.style.display = 'block';
                  const finishBtn = wizardEl.querySelector('.wizard-finish-btn');
                  if (finishBtn) finishBtn.disabled = true;
              },

              showError(message) {
                  stopDialingDots();
                  this.stopPortCycling();
                  if (statusTextEl) statusTextEl.textContent = `Error: ${message}`;
                  if (portNameEl) portNameEl.textContent = 'Detection failed';
              },

              getElement() {
                  return wizardEl;
              }
          };
      }

      async function ensureBrowserSession() {
          if (browserSessionState.phase === 'ready' && browserSessionState.session?.loginUrl) {
              return browserSessionState.session;
          }
          if (browserSessionState.pending) {
              return browserSessionState.pending;
          }

          browserSessionState.phase = 'launching';
          browserSessionState.canceled = false;

          // Show wizard Phase 1
          const wizardUi = showConnectionWizard();
          if (!wizardUi) {
              browserSessionState.phase = 'idle';
              throw new Error('Failed to show wizard');
          }
          wizardUi.showPhase(1);

          // Return a promise that resolves when user completes the wizard
          return new Promise((resolve, reject) => {
              const wizardEl = wizardUi.getElement();
              const nextBtn = wizardEl.querySelector('.wizard-next-btn');
              const finishBtn = wizardEl.querySelector('.wizard-finish-btn');
              let sessionData = null;
              let sessionPromise = null;

              // Phase 1 -> Phase 2: User clicks Next
              if (nextBtn && !nextBtn.dataset.wired) {
                  nextBtn.dataset.wired = '1';
                  nextBtn.addEventListener('click', async () => {
                      wizardUi.showPhase(2);
                      wizardUi.startPortCycling();

                      // Start session creation in background
                      sessionPromise = (async () => {
                          try {
                              const params = new URLSearchParams(window.location.search);
                              const status = await browserSessionClient.checkStatus();

                              if (browserSessionState.canceled) {
                                  throw new Error('Connection canceled.');
                              }

                              if (status?.activeSession?.loginUrl) {
                                  return {
                                      loginUrl: status.activeSession.loginUrl,
                                      region: status.activeSession.region || 'auto',
                                      sessionId: status.activeSession.sessionId || null,
                                      remainingMs: Number(status.activeSession.remainingMs) || 0,
                                      reused: true,
                                  };
                              } else {
                                  const hintedIP = params.get('client_ip') || params.get('ip') || null;
                                  return await browserSessionClient.createSession({ clientIP: hintedIP });
                              }
                          } catch (err) {
                              wizardUi.showError(err?.message || 'Connection failed');
                              throw err;
                          }
                      })();

                      try {
                          sessionData = await sessionPromise;

                          if (browserSessionState.canceled) {
                              throw new Error('Connection canceled.');
                          }

                          if (!sessionData?.loginUrl) {
                              throw new Error('No login link returned');
                          }

                          await wizardUi.completePortCycling();
                          if (browserSessionState.canceled) {
                              throw new Error('Connection canceled.');
                          }

                          // Transition to Phase 3
                          wizardUi.showModemFound(sessionData.region);
                      } catch (err) {
                          browserSessionState.phase = 'idle';
                          browserSessionState.session = null;
                          reject(err);
                      }
                  });
              }

              // Phase 3 -> Complete: User clicks Connect
              if (finishBtn && !finishBtn.dataset.wired) {
                  finishBtn.dataset.wired = '1';
                  finishBtn.addEventListener('click', async () => {
                      if (!sessionData) return;

                      wizardUi.showDialing();

                      // Play modem dialup sound (28.5s total)
                      // Browser window created hidden, shown at 61.8% (~17.6s)
                      const skipDialup = new URLSearchParams(window.location.search).has('skip_dialup');
                      const DIALUP_DURATION_MS = skipDialup ? 0 : 28572;
                      const GOLDEN_RATIO = 0.618;
                      const CONNECT_TIME_MS = Math.round(DIALUP_DURATION_MS * GOLDEN_RATIO);

                      if (!skipDialup) soundManager.play('dialup');

                      // Set session state immediately so browser can launch
                      browserSessionState.session = sessionData;
                      browserSessionState.phase = 'ready';

                      if (sessionData.sessionId) {
                          startHeartbeat(sessionData.sessionId);
                      }

                      // Start session countdown timer
                      if (sessionData.remainingMs) {
                          sessionTimer.start(sessionData.remainingMs, () => {
                              handleSessionExpired();
                          });
                      }

                      // Create browser window HIDDEN and start loading immediately
                      const launchData = {
                          loginLink: sessionData.loginUrl,
                          navigateToUrl: null,
                          hidden: true, // Signal to create hidden
                      };
                      const browserWindow = createWindow(browserSessionState.pendingAppId || 'internetExplorer', launchData);

                      // Wait for golden ratio point, then reveal
                      await new Promise(r => setTimeout(r, CONNECT_TIME_MS));

                      if (browserWindow) {
                          browserWindow.style.opacity = '1';
                          browserWindow.style.pointerEvents = '';
                          focusWindow(browserWindow);
                      }

                      closeConnectionWizard();
                      resolve(sessionData);
                  });
              }
          });
      }

      async function launchBrowserApplication(appId, dataForApp = null) {
          // Show timer whenever a browser window is being opened/focused
          sessionTimer.show();

          const existingBrowser = findExistingBrowserWindow(appId);
          if (existingBrowser && existingBrowser.element) {
              if (existingBrowser.isMinimized) {
                  toggleMinimizeWindow(existingBrowser.element);
              } else {
                  focusWindow(existingBrowser.element);
              }

              if (dataForApp?.navigateToUrl && existingBrowser.appInstance && typeof existingBrowser.appInstance.navigateTo === 'function') {
                  existingBrowser.appInstance.navigateTo(dataForApp.navigateToUrl);
              }
              return existingBrowser.element;
          }

          try {
              // Track which browser app we're launching
              browserSessionState.pendingAppId = appId;
              const session = await ensureBrowserSession();
              let browserAfterConnect = findExistingBrowserWindow(appId);

              // If session exists but no window found (e.g. user closed it), create new window
              if (!browserAfterConnect && session && session.loginUrl) {
                  createWindow(appId, {
                      loginLink: session.loginUrl,
                      navigateToUrl: dataForApp?.navigateToUrl
                  });
                  browserAfterConnect = findExistingBrowserWindow(appId);
              }

              if (browserAfterConnect && browserAfterConnect.element) {
                  if (browserAfterConnect.isMinimized) {
                      toggleMinimizeWindow(browserAfterConnect.element);
                  } else {
                      focusWindow(browserAfterConnect.element);
                  }
                  if (dataForApp?.navigateToUrl && browserAfterConnect.appInstance && typeof browserAfterConnect.appInstance.navigateTo === 'function') {
                      browserAfterConnect.appInstance.navigateTo(dataForApp.navigateToUrl);
                  }
                  return browserAfterConnect.element;
              }
              // Window is already created by wizard, just return
              return findExistingBrowserWindow(appId)?.element || null;
          } catch (error) {
              console.warn('Browser launch aborted:', error?.message || error);
              return null;
          }
      }

      async function openApplication(appId, dataForApp = null) {
          if (BROWSER_APP_IDS.has(appId)) {
              return launchBrowserApplication(appId, dataForApp);
          }
          return createWindow(appId, dataForApp);
      }
      window.Win9xSystem = window.Win9xSystem || {};
      window.Win9xSystem.openApplication = openApplication;

      // Defer heavy asset preloading until user clicks Start (or proceed
      // immediately if there's no lock screen). This keeps the lock screen
      // snappy and lets the user see the splash loading animation.
      async function runAssetPreload() {
          // Fetch assets into browser cache (link rel=preload gets purged if not used quickly)
          const deferredPreloads = [
              { href: './PressStart2P-Regular.ttf' },
              { href: './marlett.woff' },
              { href: './modem-hero-inset.png' },
              { href: './sounds/startup.wav' },
              { href: './sounds/ding.wav' },
              { href: './sounds/chord.wav' },
              { href: './sounds/dialup.wav' },
              { href: './sounds/tada.wav' },
              { href: './sounds/start.wav' },
          ];
          await Promise.all(deferredPreloads.map(p =>
              fetch(p.href).catch(() => {})
          ));
          if (window.SPLASH_API) {
              console.log("Starting asset preloading...");
              await preloadAppImages((percentage) => {
                  window.SPLASH_API.setProgress(5 + (percentage * 0.80));
              });
              console.log("Asset preloading complete.");
              window.SPLASH_API.setProgress(85);
          }
      }

      if (window.__unlockPromise) {
          // Wait for user to click Start before heavy preloading
          await window.__unlockPromise;
      }
      // Show the loading state for at least 1.5s so the user sees feedback
      const minLoadingDelay = new Promise(r => setTimeout(r, 1500));
      await Promise.all([runAssetPreload(), minLoadingDelay]);

      // --- Core Function Definitions (from your latest app.js) ---
      function keepAllWindowsOnScreen() { /* ... (same as your latest) ... */
          if (!desktop) return;
          const desktopWidth = desktop.clientWidth;
          const desktopHeight = desktop.clientHeight;
          Object.values(openWindows).forEach(winData => {
              if (!winData || !winData.element || winData.isMinimized || winData.isMaximized) return;
              const windowEl = winData.element;
              const currentLeft = windowEl.offsetLeft, currentTop = windowEl.offsetTop;
              const currentWidth = windowEl.offsetWidth, currentHeight = windowEl.offsetHeight;
              let newLeft = currentLeft, newTop = currentTop;
              if (newLeft + currentWidth > desktopWidth) newLeft = desktopWidth - currentWidth;
              if (newTop + currentHeight > desktopHeight) newTop = desktopHeight - currentHeight;
              if (newLeft < 0) newLeft = 0;
              if (newTop < 0) newTop = 0;
              if (newLeft !== currentLeft || newTop !== currentTop) {
                  windowEl.style.left = newLeft + 'px';
                  windowEl.style.top = newTop + 'px';
                  if (winData.originalRect) {
                      winData.originalRect.left = windowEl.style.left;
                      winData.originalRect.top = windowEl.style.top;
                  }
              }
          });
      }
      const debouncedKeepOnScreen = debounce(keepAllWindowsOnScreen, 250);
      if (typeof ResizeObserver !== 'undefined') {
          const resizeObserver = new ResizeObserver(debouncedKeepOnScreen);
          resizeObserver.observe(desktop);
      } else {
          window.addEventListener('resize', debouncedKeepOnScreen);
      }

      function updateClock() { /* ... (same as your latest) ... */
          const now = new Date();
          const hours = now.getHours();
          const minutes = now.getMinutes().toString().padStart(2, '0');
          const ampm = hours >= 12 ? 'PM' : 'AM';
          const displayHours = (hours % 12) || 12;
          clockElement.textContent = `${displayHours}:${minutes} ${ampm}`;
          clockElement.title = now.toLocaleDateString(undefined, {
              weekday: 'long',
              year: 'numeric',
              month: 'long',
              day: 'numeric',
          });
      }
      setInterval(updateClock, 1000); updateClock();

      startButton.addEventListener('click', (event) => { /* ... (same as your latest) ... */
          event.stopPropagation();
          const isVisible = startMenu.style.display === 'flex';
          startMenu.style.display = isVisible ? 'none' : 'flex';
          startButton.style.borderStyle = isVisible ? 'outset' : 'inset';
          if (!isVisible) {
              startMenu.focus();
              soundManager.play('start');
          }
      });
      document.addEventListener('click', (event) => { /* ... (same as your latest for Start Menu) ... */
          if (startMenu.style.display === 'flex' && !startMenu.contains(event.target) && !startButton.contains(event.target)) {
              startMenu.style.display = 'none';
              startButton.style.borderStyle = 'outset';
          }
          // Desktop icon deselection is handled by desktop-icons.js
      }, {capture: true});

      function minimizeAllOpenWindows() {
          Object.values(openWindows).forEach((winData) => {
              if (!winData || !winData.element || winData.isMinimized) return;
              const minimizeButton = winData.element.querySelector('.window-minimize-btn');
              const canMinimize = !!minimizeButton && window.getComputedStyle(minimizeButton).display !== 'none';
              if (!canMinimize) return;
              toggleMinimizeWindow(winData.element);
          });
      }

      if (quickLaunch) {
          quickLaunch.addEventListener('click', (event) => {
              const button = event.target.closest('.quick-launch-btn');
              if (!button || !quickLaunch.contains(button)) return;
              event.stopPropagation();

              const action = button.dataset.action;
              if (action === 'showDesktop') {
                  minimizeAllOpenWindows();
                  return;
              }

              const appId = button.dataset.appId;

              if (appId) {
                  void openApplication(appId);
              }
          });
      }

      // --- Window Management Functions (from your latest app.js) ---
      function createWindow(appId, dataForApp) { /* ... (same as your latest) ... */
          startMenu.style.display = 'none';
          startButton.style.borderStyle = 'outset';
          const appDef = APP_DEFINITIONS[appId];
          if (!appDef) { console.error("App definition not found for:", appId); return; }

          if (!appDef.isDialog) {
              const existingInstance = Object.values(openWindows).find(ow => ow.appId === appId && ow.element && document.body.contains(ow.element));
              if (existingInstance) {
                  if (existingInstance.isMinimized) toggleMinimizeWindow(existingInstance.element);
                  else focusWindow(existingInstance.element);
                  return;
              }
          }

          let appInstanceSpecificData = null;
          if (appId === 'networkExplorer' && typeof openApplication === 'function') {
              appInstanceSpecificData = openApplication;
          }

          const windowInstanceId = `window-${appId}-${windowIdCounter++}`;
          const windowEl = windowTemplate.content.firstElementChild.cloneNode(true);
          windowEl.dataset.appId = appId;
          windowEl.dataset.instanceId = windowInstanceId;
          const titlebarIconSrc = appDef.titlebarIcon || appDef.icon;
          if ( titlebarIconSrc ) {
            windowEl.querySelector('.window-titlebar-icon').src = titlebarIconSrc;
            windowEl.querySelector('.window-titlebar-icon').style.display = 'inline-block';
          } else {
            windowEl.querySelector('.window-titlebar-icon').style.display = 'none';
          }
          windowEl.querySelector('.window-titlebar-icon').alt = appDef.title;
          windowEl.querySelector('.window-title').textContent = appDef.title;

          if (appDef.activeTitleBarColor) {
              windowEl.dataset.customActiveTitlebarColor = appDef.activeTitleBarColor;
              if (appDef.activeTitleBarTextColor) {
                  windowEl.dataset.customActiveTitlebarTextColor = appDef.activeTitleBarTextColor;
              }
          }

          let webviewId = null;
          const isBrowserApp = BROWSER_APP_IDS.has(appId);
          if (isBrowserApp) webviewId = `webview-${windowInstanceId}`;

          if (appDef.generateContent) {
              windowEl.querySelector('.window-content').innerHTML = appDef.generateContent(windowInstanceId, webviewId, dataForApp);
          } else {
              windowEl.querySelector('.window-content').innerHTML = typeof appDef.content === 'function' ? appDef.content() : appDef.content;
          }

          if (isBrowserApp && dataForApp?.loginLink && webviewId) {
              const webviewEl = windowEl.querySelector(`#${webviewId}`);
              if (webviewEl) {
                  // Append &ui=false to hide BrowserBox's own UI — only retro chrome shows
                  const loginUrl = new URL(dataForApp.loginLink);
                  loginUrl.searchParams.set('ui', 'false');
                  webviewEl.setAttribute('login-link', loginUrl.href);
                  if (!webviewEl.dataset.connectFailWired) {
                      webviewEl.dataset.connectFailWired = '1';
                      webviewEl.addEventListener('connect-failed', async () => {
                          const status = await browserSessionClient.checkStatus().catch(() => null);
                          if (!status?.activeSession) {
                              handleSessionExpired();
                              return;
                          }
                          if (typeof webviewEl.stopReconnectAttempts === 'function') {
                              webviewEl.stopReconnectAttempts('connect-failed');
                          }
                          showConnectionFailedDialog(appId);
                      });
                  }
              }
          }

          const maxAllowedWidth = desktop.clientWidth - 20;
          const maxAllowedHeight = desktop.clientHeight - 20;
          let defaultWidth = appDef.defaultWidth || (appDef.isDialog ? 380 : 600);
          let defaultHeight = appDef.defaultHeight || (appDef.isDialog ? 220 : 450);
          defaultWidth = Math.min(defaultWidth, maxAllowedWidth);
          defaultHeight = Math.min(defaultHeight, maxAllowedHeight);
          const minW = parseInt(window.getComputedStyle(windowEl).minWidth) || 150;
          const minH = parseInt(window.getComputedStyle(windowEl).minHeight) || 100;
          defaultWidth = Math.max(defaultWidth, minW);
          defaultHeight = Math.max(defaultHeight, minH);
          windowEl.style.width = `${defaultWidth}px`;
          windowEl.style.height = `${defaultHeight}px`;

          if (appDef.isDialog) {
              windowEl.style.left = `${Math.max(0, (desktop.offsetWidth - defaultWidth) / 2)}px`;
              windowEl.style.top = `${Math.max(0, (desktop.offsetHeight - defaultHeight) / 3)}px`;
          } else {
              const randomOffsetX = Math.max(0, desktop.offsetWidth - defaultWidth - 40);
              const randomOffsetY = Math.max(0, desktop.offsetHeight - defaultHeight - 40);
              windowEl.style.left = `${Math.floor(Math.random() * randomOffsetX) + 20}px`;
              windowEl.style.top = `${Math.floor(Math.random() * randomOffsetY) + 20}px`;
          }

          highestZIndex++;
          windowEl.style.zIndex = highestZIndex;

          // If hidden flag set, use opacity:0 (not visibility:hidden) so iframe still loads
          if (dataForApp?.hidden) {
              windowEl.style.opacity = '0';
              windowEl.style.pointerEvents = 'none';
          }

          desktop.appendChild(windowEl);
          Object.values(openWindows).forEach(ow => { if (ow.element) ow.element.classList.add('inactive'); });

          const newWindowData = {
              element: windowEl, taskbarButton: null, appId: appId,
              originalRect: { left: windowEl.style.left, top: windowEl.style.top, width: windowEl.style.width, height: windowEl.style.height },
              isMinimized: false, isMaximized: false, appInstance: null
          };
          openWindows[windowInstanceId] = newWindowData;

          if (appDef.initApp) {
              newWindowData.appInstance = appDef.initApp(windowEl, windowInstanceId, webviewId, appDef, appInstanceSpecificData, dataForApp);
          }

          if (!appDef.isDialog) {
              makeDraggable(windowEl);
              makeResizable(windowEl);
              const taskbarIconSrc = appDef.taskbarIcon || appDef.icon;
              addWindowToTaskbar(windowEl, appDef.title, taskbarIconSrc, windowInstanceId);
              windowEl.querySelector('.window-minimize-btn').addEventListener('click', () => toggleMinimizeWindow(windowEl));
              windowEl.querySelector('.window-maximize-btn').addEventListener('click', () => toggleMaximizeWindow(windowEl));
          } else {
              windowEl.querySelector('.window-minimize-btn').style.display = 'none';
              windowEl.querySelector('.window-maximize-btn').style.display = 'none';
              makeDraggable(windowEl);
          }
          windowEl.querySelector('.window-close-btn').addEventListener('click', () => closeWindow(windowEl));
          windowEl.addEventListener('pointerdown', (event) => {
              const target = event.target && typeof event.target.closest === 'function'
                  ? event.target
                  : null;
              focusWindow(windowEl, { skipDomFocus: shouldPreserveTextFocus(target) });
          }, true);
          focusWindow(windowEl);
          if (!newWindowData.isMinimized && !newWindowData.isMaximized) keepSingleWindowOnScreen(windowEl, newWindowData);

          if (dataForApp && dataForApp.navigateToUrl && isBrowserApp) {
              const checkBrowserReadyAndNavigate = () => {
                  const winData = openWindows[windowInstanceId];
                  if (winData && winData.appInstance && typeof winData.appInstance.navigateTo === 'function') {
                      winData.appInstance.navigateTo(dataForApp.navigateToUrl);
                  } else if (winData && newWindowData.element && document.body.contains(newWindowData.element)) {
                      setTimeout(checkBrowserReadyAndNavigate, 200);
                  }
              };
              setTimeout(checkBrowserReadyAndNavigate, 100);
          }
          return windowEl;
      }
      function keepSingleWindowOnScreen(windowEl, winData) { /* ... (same as your latest) ... */
          if (!desktop || !windowEl || !winData || winData.isMinimized || winData.isMaximized) return;
          const desktopWidth = desktop.clientWidth, desktopHeight = desktop.clientHeight;
          const currentLeft = windowEl.offsetLeft, currentTop = windowEl.offsetTop;
          const currentWidth = windowEl.offsetWidth, currentHeight = windowEl.offsetHeight;
          let newLeft = currentLeft, newTop = currentTop;
          if (newLeft + currentWidth > desktopWidth) newLeft = desktopWidth - currentWidth;
          if (newTop + currentHeight > desktopHeight) newTop = desktopHeight - currentHeight;
          if (newLeft < 0) newLeft = 0;
          if (newTop < 0) newTop = 0;
          if (newLeft !== currentLeft || newTop !== currentTop) {
              windowEl.style.left = newLeft + 'px';
              windowEl.style.top = newTop + 'px';
              if (winData.originalRect) {
                  winData.originalRect.left = windowEl.style.left;
                  winData.originalRect.top = windowEl.style.top;
              }
          }
      }
      function makeResizable(element) { /* ... (same as your latest - with element-specific listeners) ... */
          const handles = element.querySelectorAll('.resize-handle');
          let isResizing = false, currentHandle = null;
          let startX, startY, startWidth, startHeight, startLeft, startTop;
          const minWidth = parseInt(window.getComputedStyle(element).minWidth) || 150;
          const minHeight = parseInt(window.getComputedStyle(element).minHeight) || 100;

          handles.forEach(handle => {
              handle.addEventListener('pointerdown', (e) => {
                  const windowData = openWindows[element.dataset.instanceId];
                  if (windowData && windowData.isMaximized) return;
                  e.stopPropagation(); isResizing = true; currentHandle = handle;
                  startX = e.clientX; startY = e.clientY;
                  startWidth = element.offsetWidth; startHeight = element.offsetHeight;
                  startLeft = element.offsetLeft; startTop = element.offsetTop;
                  focusWindow(element);
                  document.body.style.cursor = window.getComputedStyle(currentHandle).cursor;
                  document.body.classList.add('no-select');
                  element.setPointerCapture(e.pointerId);
              });
          });

          element.addEventListener('pointermove', (e) => {
              if (!isResizing || !currentHandle) return;
              const dx = e.clientX - startX, dy = e.clientY - startY;
              let newWidth = startWidth, newHeight = startHeight, newLeft = startLeft, newTop = startTop;

              if (currentHandle.classList.contains('resize-handle-e')) newWidth = Math.max(minWidth, startWidth + dx);
              else if (currentHandle.classList.contains('resize-handle-w')) { newWidth = Math.max(minWidth, startWidth - dx); newLeft = startLeft + dx; if (newWidth === minWidth) newLeft = startLeft + (startWidth - minWidth); }
              if (currentHandle.classList.contains('resize-handle-s')) newHeight = Math.max(minHeight, startHeight + dy);
              else if (currentHandle.classList.contains('resize-handle-n')) { newHeight = Math.max(minHeight, startHeight - dy); newTop = startTop + dy; if (newHeight === minHeight) newTop = startTop + (startHeight - minHeight); }
              if (currentHandle.classList.contains('resize-handle-se')) { newWidth = Math.max(minWidth, startWidth + dx); newHeight = Math.max(minHeight, startHeight + dy); }
              else if (currentHandle.classList.contains('resize-handle-sw')) { newWidth = Math.max(minWidth, startWidth - dx); newHeight = Math.max(minHeight, startHeight + dy); newLeft = startLeft + dx; if (newWidth === minWidth) newLeft = startLeft + (startWidth - minWidth); }
              else if (currentHandle.classList.contains('resize-handle-ne')) { newWidth = Math.max(minWidth, startWidth + dx); newHeight = Math.max(minHeight, startHeight - dy); newTop = startTop + dy; if (newHeight === minHeight) newTop = startTop + (startHeight - minHeight); }
              else if (currentHandle.classList.contains('resize-handle-nw')) { newWidth = Math.max(minWidth, startWidth - dx); newHeight = Math.max(minHeight, startHeight - dy); newLeft = startLeft + dx; newTop = startTop + dy; if (newWidth === minWidth) newLeft = startLeft + (startWidth - minWidth); if (newHeight === minHeight) newTop = startTop + (startHeight - minHeight); }

              const desktopRect = desktop.getBoundingClientRect();
              if (newLeft < 0) { newWidth += newLeft; newLeft = 0; }
              if (newTop < 0) { newHeight += newTop; newTop = 0; }
              if (newLeft + newWidth > desktopRect.width) newWidth = desktopRect.width - newLeft;
              if (newTop + newHeight > desktopRect.height) newHeight = desktopRect.height - newTop;

              element.style.width = `${newWidth}px`; element.style.height = `${newHeight}px`;
              element.style.left = `${newLeft}px`; element.style.top = `${newTop}px`;
          });

          element.addEventListener('pointerup', (e) => {
              if (isResizing) {
                  isResizing = false; currentHandle = null;
                  document.body.style.cursor = 'default';
                  document.body.classList.remove('no-select');
                  if (element.hasPointerCapture(e.pointerId)) element.releasePointerCapture(e.pointerId);
                  const windowData = openWindows[element.dataset.instanceId];
                  if (windowData && !windowData.isMaximized) {
                      windowData.originalRect = { left: element.style.left, top: element.style.top, width: element.style.width, height: element.style.height };
                  }
                  if (windowData && !windowData.isMinimized && !windowData.isMaximized) keepSingleWindowOnScreen(element, windowData);
              }
          });
          element.addEventListener('pointercancel', (e) => {
              if (isResizing) {
                  isResizing = false; currentHandle = null;
                  document.body.style.cursor = 'default';
                  document.body.classList.remove('no-select');
                  if (element.hasPointerCapture(e.pointerId)) element.releasePointerCapture(e.pointerId);
              }
          });
      }
      function shouldPreserveTextFocus(targetEl) {
          if (!targetEl || typeof targetEl.closest !== 'function') return false;
          return Boolean(targetEl.closest('input, textarea, select, [contenteditable="true"]'));
      }

      function focusWindow(windowEl, options = {}) { /* ... (same as your latest) ... */
          if (!windowEl || !document.body.contains(windowEl)) return;
          const instanceId = windowEl.dataset.instanceId;
          const windowData = openWindows[instanceId];
          if (!windowData) return;
          if (windowData.isMinimized) { toggleMinimizeWindow(windowEl); return; }
          const { skipDomFocus = false } = options;

          const titleBarEl = windowEl.querySelector('.window-titlebar');
          const titleTextEl = windowEl.querySelector('.window-title');
          const titleIconEl = windowEl.querySelector('.window-titlebar-icon');

          windowEl.classList.remove('inactive');
          if (windowEl.dataset.customActiveTitlebarColor) {
              titleBarEl.style.backgroundColor = windowEl.dataset.customActiveTitlebarColor;
              if (windowEl.dataset.customActiveTitlebarTextColor) {
                  titleTextEl.style.color = windowEl.dataset.customActiveTitlebarTextColor;
              }
              if (titleIconEl) titleIconEl.style.opacity = '1';
          } else {
              titleBarEl.style.backgroundColor = '';
              titleTextEl.style.color = '';
              if (titleIconEl) titleIconEl.style.opacity = '';
          }

          Object.values(openWindows).forEach(ow => {
              if (ow.element && ow.element !== windowEl) {
                  ow.element.classList.add('inactive');
                  const otherTitleBar = ow.element.querySelector('.window-titlebar');
                  const otherTitleText = ow.element.querySelector('.window-title');
                  const otherIcon = otherTitleBar ? otherTitleBar.querySelector('.window-titlebar-icon') : null;
                  if (otherTitleBar) otherTitleBar.style.backgroundColor = '';
                  if (otherTitleText) otherTitleText.style.color = '';
                  if (otherIcon) otherIcon.style.opacity = '';
              }
          });

          if (!skipDomFocus && windowEl.hasAttribute('tabindex') && document.activeElement !== windowEl) {
              windowEl.focus({ preventScroll: true });
          }
          highestZIndex++;
          windowEl.style.zIndex = highestZIndex;
          document.querySelectorAll('.taskbar-button').forEach(btn => btn.classList.remove('active'));
          if (windowData.taskbarButton) {
              windowData.taskbarButton.classList.add('active');
              windowData.taskbarButton.classList.remove('minimized');
          }
          // No deselectAllDesktopIcons() here, as desktop-icons.js handles selection.
      }
      function closeWindow(windowEl) { /* ... (same as your latest) ... */
          const instanceId = windowEl.dataset.instanceId;
          const closingAppId = openWindows[instanceId] ? openWindows[instanceId].appId : null;
          if (openWindows[instanceId]) {
              if (openWindows[instanceId].taskbarButton) openWindows[instanceId].taskbarButton.remove();
              if (openWindows[instanceId].appInstance && typeof openWindows[instanceId].appInstance.destroy === 'function') {
                  try {
                      openWindows[instanceId].appInstance.destroy();
                  } catch (error) {
                      console.error('[closeWindow] app destroy failed', {
                          appId: closingAppId,
                          instanceId,
                          error,
                      });
                  }
              }
              delete openWindows[instanceId];
          }
          windowEl.remove();

          if (closingAppId === 'shutdownDialog') {
              const overlay = document.querySelector('.shutdown-overlay');
              if (overlay) overlay.remove();
          }

          // Hide session timer when all browser windows are closed
          if (closingAppId && BROWSER_APP_IDS.has(closingAppId)) {
              const anyBrowserOpen = Object.values(openWindows).some(ow => ow.appId && BROWSER_APP_IDS.has(ow.appId));
              if (!anyBrowserOpen) {
                  sessionTimer.hide();
              }
          }
          const remainingWindows = Object.values(openWindows).filter(ow => ow.element && !ow.isMinimized);
          if (remainingWindows.length > 0) {
              let topWin = null, maxZ = -1;
              remainingWindows.forEach(rw => { const z = parseInt(rw.element.style.zIndex) || 0; if (z > maxZ) { maxZ = z; topWin = rw.element; } });
              if (topWin) focusWindow(topWin);
          } else {
              desktop.focus();
          }
      }
      function addWindowToTaskbar(windowEl, title, iconSrc, instanceId) { /* ... (same as your latest) ... */
          const taskbarButton = document.createElement('button');
          taskbarButton.className = 'taskbar-button';
          taskbarButton.dataset.windowInstanceId = instanceId;
          taskbarButton.setAttribute('tabindex', '-1');
          taskbarButton.title = title;
          const img = document.createElement('img');
          img.src = iconSrc; img.alt = ""; taskbarButton.appendChild(img);
          taskbarButton.appendChild(document.createTextNode(title.length > 18 ? title.substring(0,15) + '...' : title));
          taskbarButton.addEventListener('click', () => {
              const winData = openWindows[instanceId];
              if (winData) {
                  if (winData.taskbarButton.classList.contains('active') && !winData.isMinimized) toggleMinimizeWindow(winData.element);
                  else focusWindow(winData.element);
              }
          });
          taskbarWindows.appendChild(taskbarButton);
          openWindows[instanceId].taskbarButton = taskbarButton;
      }
      function makeDraggable(element) {
          const titleBar = element.querySelector('.window-titlebar');
          let offsetX, offsetY, isDragging = false;
          let lastClickTime = 0;

          // Double-click title bar to toggle maximize/restore
          titleBar.addEventListener('pointerup', (e) => {
              const inWindowControls = e.target && typeof e.target.closest === 'function'
                  ? e.target.closest('.window-controls button')
                  : null;
              if (inWindowControls) return;
              const now = Date.now();
              if (now - lastClickTime < 400) {
                  const maximizeBtn = element.querySelector('.window-maximize-btn');
                  if (maximizeBtn && window.getComputedStyle(maximizeBtn).display !== 'none') {
                      toggleMaximizeWindow(element);
                  }
                  lastClickTime = 0;
              } else {
                  lastClickTime = now;
              }
          });

          titleBar.addEventListener('pointerdown', (e) => {
              const windowData = openWindows[element.dataset.instanceId];
              const inWindowControls = e.target && typeof e.target.closest === 'function'
                  ? e.target.closest('.window-controls button')
                  : null;
              if ((windowData && windowData.isMaximized) || inWindowControls) return;
              isDragging = true;
              const rect = element.getBoundingClientRect();
              offsetX = e.clientX - rect.left; offsetY = e.clientY - rect.top;
              document.body.classList.add('no-select');
              titleBar.setPointerCapture(e.pointerId);
          });
          titleBar.addEventListener('pointermove', (e) => {
              if (!isDragging) return;
              let newX = e.clientX - offsetX, newY = e.clientY - offsetY;
              const desktopRect = desktop.getBoundingClientRect(), winRect = element.getBoundingClientRect();
              const titleBarHeight = titleBar.offsetHeight;
              newX = Math.max(-winRect.width + titleBarHeight + 20, Math.min(newX, desktopRect.width - (titleBarHeight + 20)));
              newY = Math.max(0, Math.min(newY, desktopRect.height - titleBarHeight));
              element.style.left = `${newX}px`; element.style.top = `${newY}px`;
          });
          titleBar.addEventListener('pointerup', (e) => {
              if (isDragging) {
                  isDragging = false;
                  document.body.classList.remove('no-select');
                  if (titleBar.hasPointerCapture(e.pointerId)) {
                      titleBar.releasePointerCapture(e.pointerId);
                  }
                  const windowData = openWindows[element.dataset.instanceId];
                  if (windowData && !windowData.isMaximized) {
                      windowData.originalRect.left = element.style.left;
                      windowData.originalRect.top = element.style.top;
                  }
                  if (windowData && !windowData.isMinimized && !windowData.isMaximized) keepSingleWindowOnScreen(element, windowData);
              }
          });
          titleBar.addEventListener('pointercancel', (e) => {
              if (isDragging) {
                  isDragging = false;
                  document.body.classList.remove('no-select');
                  if (titleBar.hasPointerCapture(e.pointerId)) {
                      titleBar.releasePointerCapture(e.pointerId);
                  }
              }
          });
      }
      function toggleMinimizeWindow(windowEl) { /* ... (same as your latest) ... */
          const instanceId = windowEl.dataset.instanceId;
          const windowData = openWindows[instanceId];
          if (!windowData) return;
          windowData.isMinimized = !windowData.isMinimized;
          if (windowData.isMinimized) {
              if (!windowData.isMaximized) {
                   windowData.originalRectBeforeMinimize = { left: windowEl.style.left, top: windowEl.style.top, width: windowEl.style.width, height: windowEl.style.height };
              }
              windowEl.style.display = 'none';
              if (windowData.taskbarButton) { windowData.taskbarButton.classList.add('minimized'); windowData.taskbarButton.classList.remove('active'); }
              const remainingWindows = Object.values(openWindows).filter(ow => ow.element && !ow.isMinimized && ow.element !== windowEl);
              if (remainingWindows.length > 0) {
                  let topWin = null, maxZ = -1;
                  remainingWindows.forEach(rw => { const z = parseInt(rw.element.style.zIndex) || 0; if (z > maxZ) { maxZ = z; topWin = rw.element; } });
                  if (topWin) focusWindow(topWin);
              } else { desktop.focus(); }
          } else {
              windowEl.style.display = 'flex';
              if (!windowData.isMaximized && windowData.originalRectBeforeMinimize) {
                  Object.assign(windowEl.style, windowData.originalRectBeforeMinimize);
              }
              focusWindow(windowEl);
          }
      }
      function toggleMaximizeWindow(windowEl) { /* ... (same as your latest) ... */
          const instanceId = windowEl.dataset.instanceId;
          const windowData = openWindows[instanceId];
          if (!windowData || windowData.isMinimized) return;
          const maximizeBtn = windowEl.querySelector('.window-maximize-btn');
          const titleBar = windowEl.querySelector('.window-titlebar');
          const appDef = APP_DEFINITIONS[windowData.appId];

          if (windowData.isMaximized) {
              if (windowData.originalRect) Object.assign(windowEl.style, windowData.originalRect);
              else {
                  const tempW = (appDef && appDef.defaultWidth) || 450, tempH = (appDef && appDef.defaultHeight) || 300;
                  windowEl.style.left = `${(desktop.clientWidth - tempW) / 2}px`; windowEl.style.top = `${(desktop.clientHeight - tempH) / 3}px`;
                  windowEl.style.width = `${tempW}px`; windowEl.style.height = `${tempH}px`;
              }
              windowData.isMaximized = false; windowEl.classList.remove('maximized');
              maximizeBtn.textContent = '1'; maximizeBtn.title = 'Maximize'; titleBar.style.cursor = 'grab';
          } else {
              windowData.originalRect = { left: windowEl.style.left, top: windowEl.style.top, width: windowEl.style.width || `${windowEl.offsetWidth}px`, height: windowEl.style.height || `${windowEl.offsetHeight}px` };
              Object.assign(windowEl.style, { left: '0px', top: '0px', width: `${desktop.clientWidth}px`, height: `${desktop.clientHeight}px` });
              windowData.isMaximized = true; windowEl.classList.add('maximized');
              maximizeBtn.textContent = '2'; maximizeBtn.title = 'Restore'; titleBar.style.cursor = 'default';
          }
          focusWindow(windowEl);
          if (!windowData.isMinimized && !windowData.isMaximized) keepSingleWindowOnScreen(windowEl, windowData);
          else if (windowData.isMaximized) {
              Object.assign(windowEl.style, { left: '0px', top: '0px', width: `${desktop.clientWidth}px`, height: `${desktop.clientHeight}px` });
          }
      }

      // Desktop icon open routing is delegated so both built-in and dynamic icons work
      // even when icons are re-rendered after initial load.
      desktop.addEventListener('dblclick', (event) => {
          const icon = event.target.closest('.desktop-icon');
          if (!icon || !desktop.contains(icon)) return;
          const appId = icon.dataset.appId;
          if (appId) {
              void openApplication(appId);
              return;
          }
          const desktopItemId = icon.dataset.desktopItemId;
          if (desktopItemId && window.Win9xDesktopItems && typeof window.Win9xDesktopItems.openItem === 'function') {
              window.Win9xDesktopItems.openItem(desktopItemId);
          }
      });


      document.querySelectorAll('.start-menu-item').forEach(item => { /* ... (same as your latest) ... */
          item.addEventListener('click', () => {
              if (item.classList.contains('disabled')) return;
              const appId = item.dataset.appId;
              if (item.id === 'shutdownButtonTrigger') {
                  // Add Win98 dithered dark overlay behind the shutdown dialog
                  if (!document.querySelector('.shutdown-overlay')) {
                      const overlay = document.createElement('div');
                      overlay.className = 'shutdown-overlay';
                      const overlayZIndex = highestZIndex + 1;
                      overlay.style.cssText = `position:fixed;inset:0;z-index:${overlayZIndex};background-color:rgba(0,0,0,0.68);background-image:repeating-conic-gradient(rgba(255,255,255,0.06) 0% 25%, transparent 0% 50%);background-size:2px 2px;pointer-events:auto;`;
                      overlay.addEventListener('pointerdown', () => {
                          const shutdownWindow = findOpenWindowByAppId('shutdownDialog');
                          if (shutdownWindow && shutdownWindow.element) {
                              focusWindow(shutdownWindow.element);
                          }
                      });
                      document.body.appendChild(overlay);
                      highestZIndex = overlayZIndex;
                  }
                  createWindow("shutdownDialog");
              }
              else if (appId) void openApplication(appId);
              startMenu.style.display = 'none'; startButton.style.borderStyle = 'outset';
          });
      });

      const initialBgColor = window.getComputedStyle(document.documentElement).getPropertyValue('--desktop-bg-color').trim();
      if (initialBgColor) updateThemeForDesktopBackground(initialBgColor);
      if (window.Win9xSystem && typeof window.Win9xSystem.updateStartMenuItemsState === 'function') {
        window.Win9xSystem.updateStartMenuItemsState();
      }

      // Ensure desktop icons are laid out after all other scripts (like desktop-icons.js) have run
      // and potentially modified the DOM or icon states.
      if (window.Win9xDesktopUtils && typeof window.Win9xDesktopUtils.forceRelayoutAllIcons === 'function') {
          console.log("Ensuring desktop icons are laid out before hiding splash...");
          window.Win9xDesktopUtils.forceRelayoutAllIcons();
      } else {
          console.warn("Win9xDesktopUtils.forceRelayoutAllIcons not found. Desktop icons might not be positioned correctly before splash hides.");
          // Fallback: if desktop-icons.js didn't run or its utils aren't ready,
          // we might need a simpler way to ensure icons are at least somewhat positioned.
          // However, this should ideally be handled by desktop-icons.js's init.
      }
      if (window.SPLASH_API) window.SPLASH_API.setProgress(95);

      // Wait for user to unlock before showing splash/desktop
      const lockScreen = document.getElementById('lock-screen');
      const unlockButton = document.getElementById('unlock-button');
      const taskbar = document.querySelector('.taskbar');
      const soundPreloadPromise = typeof soundManager.whenPreloaded === 'function'
          ? soundManager.whenPreloaded().catch(() => {})
          : Promise.resolve();
      const waitForSoundPreload = () => Promise.race([
          soundPreloadPromise,
          new Promise(resolve => setTimeout(resolve, 1000)),
      ]);

      async function handleUnlock() {
          // Hide lock screen - reveals splash underneath
          lockScreen.classList.add('hidden');

          await waitForSoundPreload();
          // Play startup sound (now allowed after user interaction)
          soundManager.play('startup');

          // Remove lock screen from DOM after transition
          setTimeout(() => lockScreen.remove(), 500);

          // Let splash complete its animation, then show desktop
          console.log("App setup complete. Hiding splash screen.");
          if (window.SPLASH_API) {
              await window.SPLASH_API.completeAndHide({
                  minVisibleMs: 800,
                  raceDurationMs: 700,
              });
          } else {
              const desktopEl = document.getElementById('desktop');
              if(desktopEl) desktopEl.style.visibility = 'visible';
          }

          // Show taskbar after splash has fully hidden.
          if (taskbar) taskbar.classList.add('visible');
      }

      if (unlockButton) {
          if (window.__unlockClicked) {
              // User already clicked while we were initializing — proceed now
              handleUnlock();
          } else if (window.__unlockPromise) {
              // Early handler registered in HTML — wait for it, then proceed
              window.__unlockPromise.then(() => handleUnlock());
          } else {
              // Fallback: no early handler (shouldn't happen), register directly
              unlockButton.addEventListener('click', handleUnlock, { once: true });
          }
      } else {
          // No lock screen, proceed normally
          console.log("App setup complete. Hiding splash screen.");
          if (window.SPLASH_API) {
              await window.SPLASH_API.completeAndHide({
                  minVisibleMs: 800,
                  raceDurationMs: 700,
              });
          } else {
              const desktopEl = document.getElementById('desktop');
              if(desktopEl) desktopEl.style.visibility = 'visible';
          }
          if (taskbar) taskbar.classList.add('visible');
          await waitForSoundPreload();
          soundManager.play('startup');
      }
  });

  window.addEventListener('message', ({isTrusted, data}) => { /* ... (same as your latest) ... */
    if (!isTrusted || !data || !data.type) return;
    const topOffset = window.screen.availHeight - window.visualViewport.height;
    const leftOffset = window.screen.availWidth - window.visualViewport.width;
    switch(data.type) {
      case "pointermove": {
        // Your latest app.js uses globalThis.updateDragMoveGlobalListener
        // Ensure this matches how makeResizable sets up its listener.
        // My previous correction changed makeResizable to use element-specific listeners,
        // which is generally safer than a single global listener for this.
        // If you stick with globalThis.updateDragMoveGlobalListener, ensure makeResizable sets it.
        // If makeResizable uses element.addEventListener, this message listener might not be needed for resize.
        if (globalThis.updateDragMoveGlobalListener && data.pointermove) {
            const {pointermove} = data;
            pointermove.screenX -= window.screenX + leftOffset;
            pointermove.screenY -= window.screenY + topOffset;
            pointermove.clientX = pointermove.screenX;
            pointermove.clientY = pointermove.screenY;
            pointermove.preventDefault = () => void 0;
            pointermove.stopPropagation = () => void 0;
            globalThis.updateDragMoveGlobalListener(pointermove);
        }
      }; break;
      default: break;
    }
  });