Script runtime

A Script result is a small page created by your JavaScript. This article explains when the code runs, which changes restart it, what survives after it closes, and which browser features you can use.

When the code runs

Definer runs the code once when the Script result opens. Buttons, event listeners, timers, pending promises, and response streams continue working while that result remains open.

The code runs as a classic JavaScript function with top-level await. Top-level import and export statements are not supported.

The result restarts when you change:

• the lookup query;
• the active result language;
• the Script code; or
• the Source itself.

Closing the result stops its timers, listeners, streams, and requests. Theme changes can update the open result without rerunning the code. A later call to definer.lookup.getVariable() can also read an updated lookup variable, but a value you copied into a JavaScript variable earlier does not change automatically.

Choose what survives

HTML, CSS, JavaScript variables, and event listeners belong to the open result only. Recreate them each time the Script runs.

Use definer.result.setData() or definer.result.patchData() for JSON data that should stay with the lookup result. Read that data when the Script starts and rebuild the interface from it.

Content	Available after the result restarts?
Data saved through definer.result	Yes
HTML and CSS	No
JavaScript variables and DOM elements	No
Timers, listeners, streams, and pending requests	No
localStorage, sessionStorage, and IndexedDB	No

See Result data for the supported methods and JSON rules.

Reopen a saved Script result

A lookup saved in History keeps the Script configuration used at that time. Editing the current Source does not rewrite an older saved result.

When you open a saved Script result, Definer asks you to reveal it before running the saved code. Data previously saved through definer.result remains available to that result.

Editing the Source changes new results, but does not rewrite the saved result.

Know what a Script can access

A Script can:

• build and update its own HTML interface;
• use promises, timers, events, and animation frames;
• open modal dialogs inside its result;
• use the public definer API; and
• request HTTP or HTTPS resources with fetch().

A Script cannot directly access:

• the surrounding website's DOM or JavaScript;
• Definer's extension APIs or internal messages;
• browser extension APIs such as chrome.* or browser.*;
• stable browser storage such as localStorage or IndexedDB;
• popups, downloads, form navigation, or top-level page navigation; or
• remote scripts and remote stylesheets.

window.location describes the Script result, not the page where the lookup began. Use the page address Lookup variables when you need the original page URL.

Keep executable code in the Script Source itself. Use Fetch for remote data and definer.output.setCss() or an inline style for result styling.

Fix a runtime error

Definer shows errors from invalid JavaScript, rejected promises, unsupported result data, failed language changes, and other uncaught failures.

1. Read the error shown over the result.
2. Correct the Script or its input.
3. Select Retry, use Preview, or run another lookup after correcting the Script.

If the result becomes unresponsive, close it and review loops, repeated dialogs, or other work that never yields. Test long tasks with a small representative input first.

Write safer Scripts

• Use textContent for lookup text, page variables, saved data, and remote text unless you deliberately create trusted HTML.
• Review every endpoint before sending lookup or page data to it.
• Use credentials: 'include' only when the request intentionally needs the reader's signed-in session.
• Do not place private API keys in a Script you plan to share.
• Handle loading, empty, error, and cancellation states for remote requests.