An SDK for Web Pages

An SDK for Web Pages

Automations can now fill in and drive web pages through a small, stable SDK: fields found by their labels, typing and clicks a page accepts as a person's, and every value read back. Your LLM agent can write them for you with the Tranquil Skill, which ships with the app.

Forms and pages

• Form methods. fields() lists a page's fields, each with a target checked to match it and nothing else. fill, clear, upload, click and press act on them; text and attr read the page; waitFor waits for a target; frame reaches a form inside an iframe. See Forms API.
• Real input. Typing, clicks and key presses arrive as trusted browser input, with a real focus and blur, so a site's validation treats them as a person's. Every fill is read back, and a value that didn't stick is an error.
• Targets by label, role or text, named the way browsers and screen readers name them (the W3C accessible-name rules). A target that matches nothing, or more than one field, fails with the closest candidates. The SDK never guesses.
• Errors you can act on. Every failure is a FieldError with one of nine codes, what was attempted, and the candidates to choose from.
• Custom parts. For a form not built to web standards, a script can say where a field shows its value, what opens it and its clear button, so the form methods still work. SDK: Map Custom Parts drafts that map from the page in the active tab. See Custom Parts.
• Page code gets page. tab.evaluate((page) => page.document.title): the callback's first argument is the page, typed, in place of the global DOM. See Page Code API.
• Results and questions. context.result(json) shows what a run found in the Automation Runs panel; ui.confirm asks before something that can't be undone.

Checking a script

• SDK: Check Custom Parts runs a script with its page actions held back: each fill, click and key press checks its target on the live page, and the parts a dropdown needs, and logs what it would have done. Nothing is typed, clicked or uploaded.
• Offline tests run the same field finder over saved HTML, with no browser: tranquil/automation/testing (fieldsOf, fieldOf, checkTargets). See Testing.
• Lint rules flag a CSS selector likely to break on the site's next build, a secret written into a script, and a script that may submit without asking first.
• An action log in the Runs panel lists every page action a run took: method, target, site and outcome, never the values it typed.

The Tranquil Skill

• Rules for LLM agents ship with the app, at ~/.tranquil/llm/writing-automations.md, refreshed on every start. Every automation's first line points there.
• Ask your LLM agent to read it, then describe the task. It asks you what your request leaves open, gives you a short script that lists the page's fields, writes the automation, and fixes it from the output you paste back. You check and run each version. See Automate with the Tranquil Skill.
• The Skill, and the rules for anyone working on Tranquil itself, live in the new public tranquil-llm repo.

Permissions

• browser splits into finer grants: tabs (open tabs and read pages), forms (type and click, never submit), submit, and page-js (your own code in the page). browser still grants all of them. See Permissions.
• sites= limits where a script acts. The SDK checks the page's address before every page action; a form in an iframe counts by its own site.
• Submitting needs submit. Without it, a click or key press that would submit a form is stopped and refused.
• The approval prompt says more: the grants, the sites a script is limited to (or that it has no limit), whether it may submit, and the sensitive page APIs its page code uses.
• Your own modules. An automation can import your own .ts files, declared in read=. There is still nothing to build or install.

Commands

• Built-in commands start with SDK: (SDK: Run Automation, SDK: Toggle Runs Panel), and registered scripts with Automation: (Automation: Flag Overdue, formerly Run: Flag Overdue). Command ids and key bindings are unchanged.
• SDK: Check Custom Parts and SDK: Map Custom Parts are new.
• Every command, with its key, is on the new Commands page.

Browser

• Page permissions are denied by default. Camera, microphone, location, notifications and the rest are refused; a page gets only fullscreen and writing to the clipboard, after a click.
• A closed window's browsing data is removed. When a window closes for good, its cookies, logins and cache are cleared, and anything left over is deleted at the next start.

Docs

• A new SDK section: SDK Overview, Tranquil Skill, Permissions, Tranquil API, Forms API, Page Code API, Custom Parts, Testing and Commands.
• A page for each example under Examples.
• Search finds the section that matches, not only the page.

Fixes

• Colors assigned to windows that no longer exist are dropped when a window starts.

What's changed for existing scripts

• tab.evaluate and tab.waitFor(fn) callbacks take page first, and the global DOM types are gone: document in a callback is now page.document. deno check finds every call to change.
• Registered commands are renamed from Run: to Automation:. A key bound to one keeps working.
• The examples are updated to the new grants and page. Pull tranquil-examples.

Known limitations

Native builds and the in-app updater remain in private beta. Forms built from web components (shadow DOM) can't be filled yet, and a script reaches cross-origin frames one level deep.

---

Found a bug? File it on GitHub.