> ## Documentation Index
> Fetch the complete documentation index at: https://ej3mplo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging and common mistakes

> See the errors, the theme's limits, and the most common failures.

## See the errors

* With **developer mode** on, uncaught errors from your theme show up as
  notices: "Theme: Uncaught SyntaxError: …".
* For the real **developer tools** (console, inspector, network):
  1. Quit ejGames completely (quick menu → **Quit ejGames**).
  2. Open it from a `cmd` window with remote debugging on:

     ```bat theme={null}
     set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222
     "%LOCALAPPDATA%\ejGames\ejgames.exe"
     ```

     (change the path if you installed it somewhere else).
  3. In Edge, open `edge://inspect` (if nothing appears, press **Configure…** and
     add `localhost:9222`) and press **inspect** on the iframe entry that starts
     with `http://ejg-theme.localhost/ejemplo/`. That is your theme's console:
     `console.log()` writes there. You can also inspect the page
     `http://tauri.localhost/` and pick the theme iframe in the console's context
     selector (where it says "top").

## What a theme cannot do

The theme lives in a closed box, for safety. This does **not** work:

| You want… | What happens | What to do |
| - | - | - |
| Data from the internet (`fetch`, an API) | blocked | Put everything you need inside the theme folder. |
| Fonts, images or scripts from the internet (Google Fonts, a CDN) | they do not load | Download them into the folder and use relative paths: `@font-face { src: url("fonts/my-font.woff2"); }` |
| Read your own files with `fetch("datos.json")` | also blocked: `fetch` only reaches library art (`http://ejg-media.localhost`) | Put the data in a JS module (`export default { … }`) and load it with `import datos from "./datos.js";`. The theme's images, CSS, fonts, audio and video do load in their tags. |
| `localStorage`, `sessionStorage`, `IndexedDB`, cookies | they throw `SecurityError` | `ejg.storage` (below). |
| `alert()`, `confirm()`, `prompt()` | they do nothing | `ejg.ui.toast("Text", "info" \| "ok" \| "error")` or your own HTML dialog. |
| Open websites | `window.open` is blocked, and an `<a href="https://…">` link opens the site **inside** the theme, which then disappears (after a few seconds ejGames loads the house theme) | Do not link out to websites. |
| Reach the disk, other programs, or Tauri | impossible | Only what `window.ejg` offers. |

To store things (the last game you opened, a filter…) use **`ejg.storage`**:
each theme has 512 KB per profile and can store any JSON value.

```js theme={null}
await ejg.storage.set("ultimo", 42);
const ultimo = await ejg.storage.get("ultimo"); // 42 (undefined if it does not exist)
const todo = await ejg.storage.getAll();        // { ultimo: 42, … }
```

Because of these limits, installing someone else's theme is safe. At most it can
launch games from your library or open launcher screens.

## Common mistakes

| Symptom | Likely cause |
| - | - |
| The theme does not appear in the gallery | `theme.json` has errors, or the `id` is not valid (see `logs\ejgames.log`). |
| I changed `theme.json` and nothing happened | It has an error (the theme keeps the previous version): see the log. |
| I save and it does not reload | Developer mode is off. Meanwhile, F5. |
| Blank screen | A JavaScript error (turn on developer mode), a bad `import` (kit paths start with `/_sdk/kit/`, yours with `./`), or the `<script>` is missing `type="module"` (without it, `await` and `import` fail). |
| "isn't responding. The house theme was loaded" | Your code blocks the page (a loop that never ends, a huge calculation at startup). |
| The controller never reaches a button | It is missing `data-focus`, or it is hidden or `disabled`. |
| The arrows escape a panel | Put `data-focus-trap` on the panel. |
| Esc closes your panel **and** ejGames also acts (in Big Picture, the quick menu opens) | Your `back` was not treated as handled. In `bindNav`, do not return `false` when you did use it. |
| After closing settings there is no focus | `ejg.on("focus-return", () => foco.restore())` is missing. |
| The focus ring is clipped | `content-visibility: auto` clips whatever sticks out. Leave `padding` on the card. |
| An element with `hidden` is still visible | Your CSS sets `display`. Add `[hidden] { display: none !important; }`. |
| A click at the top right does not land | That corner belongs to the launcher's window buttons (`windowControls: "host"`). |
| A CSS variable does not apply from `h()` | With `style` as an object you cannot set variables. Use a string, `style: "--tono: 120"`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.