Free local lab · learn cross-domain tab orchestration on allowed hosts · understand the browser model before the full API reference
SDK How it works
Remote Tab Opener

Advanced API Lab

This page is a practical training lab. Goal: understand when to use openTab, navigate and command, see the expected message shape, and recognize common failures quickly without relying on outdated habits.

Status: unknown
How to use

What you learn in 3 minutes

  • Step 1: verify extension connectivity and open a controlled tab.
  • Step 2: build messages for 3 useful cases (open, navigate, DOM action).
  • Step 3-5: understand errors, logs, and how to encode a small workflow.
Recommended order: do Step 1 first, then Step 2 (Case A then Case B), and only after that use Steps 3–5. If Step 1 is red, the rest of the page is mostly theoretical.
Modern allowlist note: page-side allowlist additions should use the request/confirmation flow. Treat direct page-side allowlistAdd as legacy compatibility, not the normal path.
Step 0

Required helper files

This lab uses only official helpers from ../RTO_helpers/. The mandatory file is RTO_form_api.js.

RTO_form_api.js RTO_detector.js RTO_connector.js RTO_tabsList.js RTO_openTab_button.js RTO_visible_when_tab.js
Step 1

Check connection and control one tab

v?

Why this step exists

Remote actions only work if the extension is detected and this host is authorized. This step validates your environment before you spend time debugging selectors.

If this host is not allowlisted in the extension popup, detection can fail with timeout.

Checking…

Extension detected. You can open and control a remote tab using tabKey.
Expected result: green status + version badge + buttons visible.
If it fails: check extension installation, enable it, then allowlist this domain.
Step 2

Build useful messages (real use cases)

Pick one case below and click Build JSON. This is the most useful part of the page.

How to read this section

  • Case A: openTab to open/focus a remote tab.
  • Case B: command:setValue to fill a field.
  • Case C: command:domExtractBlock to read a DOM section.
Practical rule: start from a known-good message, then change only one field at a time (for example: selector, timeout, or tabKey). This avoids “silent” multi-cause failures.
Choose intent first, then add optional parameters.
The remote tab identifier.
Keep this ID to match request and response in logs.
Parsed as JSON and merged into the payload below. Useful to experiment with arbitrary fields.
Generated message (copy/paste ready) 
{/* click “Build JSON” to generate a sample message */}

The generated object follows the current helper envelope used by RTOForm.

Common mistakes: wrong tabKey, invalid selector, expecting navigate behavior from a command action, or forgetting that some actions require a controlled tab first.

Step 3

Understand success vs error responses

Use this to train yourself to read failures fast. In real projects, time is lost when developers only check ok and ignore error.code and requestId.

Overrides the default code for the selected scenario. 
{/* choose a scenario and click “Generate sample response” */}

Expected pattern: { ok:true, data } or { ok:false, error:{code,message} } with the same requestId.

Tip: classify errors by category first: connectivity (EXT_NOT_DETECTED), policy (DOMAIN_NOT_ALLOWED), timing (TIMEOUT), selector/data issues.

Step 4

Read logs like a debugger

Logs are your timeline. Keep them concise and structured: when, action, tabKey, requestId, result. 

[log console ready]

Recommended level: info for normal runs, debug only while diagnosing.

Step 5

Encode a mini workflow (advanced)

This section helps you represent a multi-step flow as JSON. It is not auto-executed here.

Think of this as “design before coding”: if your scenario JSON is unclear, your implementation will also be unclear.

1 Open/adopt tab A (focus).
2 Wait for #result-note on tab A with a timeout of 8 s.
3 Extract a JSON recap from #result-json on tab A.
4 Send this recap to tab B as an INGEST_RESULT command. 
{/* click “Build scenario JSON” to see a structured version of the steps */}

The lab doesn’t execute this scenario; it shows how you might encode it as data and feed it to an orchestrator that processes steps with retries and error handling.

Good practice: each step should declare its input, expected output, and retry policy.