Recipes

Copy/paste patterns for common workflows.
Docs updated: 2025-12-17

Status banner (detect + allow-list)

<div id="rtoStatus"></div>

<script src="../RTO_helpers/RTO_form_api.js"></script>
<script src="../RTO_helpers/RTO_domainList.js"></script>
<script src="../RTO_helpers/RTO_status_ui.js"></script>
<script>
  RTOStatusUI.mount({ containerId: "rtoStatus" });
</script>

Open or focus a tab

// Open-or-focus pattern
async function openOrFocus(tabKey, url){
  try{
    await RTOForm.openTab({ tabKey, url, focus:true}, { timeoutMs: 20000 });
  }catch(e){
    // If open fails, try focus as a fallback
    await RTOForm.focusTab(tabKey);
  }
}

openOrFocus("billing", "https://example.com/billing");

List open controlled tabs (UI)

This uses RTO_openTabsListing.js to fill a table body.

<table class="table table-sm">
  <thead><tr><th>tabKey</th><th>URL</th></tr></thead>
  <tbody id="openTabsBoby"></tbody>
</table>

<script src="../RTO_helpers/RTO_form_api.js"></script>
<script src="../RTO_helpers/RTO_connector.js"></script>
<script src="../RTO_helpers/RTO_tabsList.js"></script>
<script src="../RTO_helpers/RTO_openTabsListing.js"></script>

Edit remote HTML with a local textarea

Wire buttons with RTO_DOM_actions.js:

<textarea id="localHtml" data-rto-mark-dirty="1" style="width:100%;min-height:140px"></textarea>

<button data-rto-action="read-block"  data-rto-tabKey="app" data-rto-selector="#content" data-rto-target="#localHtml">
  Read remote HTML
</button>

<button data-rto-action="write-block" data-rto-tabKey="app" data-rto-selector="#content" data-rto-target="#localHtml">
  Write remote HTML
</button>

<script src="../RTO_helpers/RTO_form_api.js"></script>
<script src="../RTO_helpers/RTO_DOM_actions.js"></script>

Allow-list needed banner

Show this when you catch DOMAIN_NOT_ALLOWED from an RTO call:

// Minimal "allow-list needed" banner
function showAllowBanner(host){
  const el = document.createElement("div");
  el.style.cssText = "position:fixed;bottom:12px;left:12px;right:12px;padding:12px;background:#111;color:#fff;border-radius:12px;z-index:9999;";
  el.innerHTML = `
    <div style="display:flex;gap:10px;align-items:center;justify-content:space-between;flex-wrap:wrap">
      <div>
        <b>RTO:</b> This host is not allow-listed: <code>${host}</code>
      </div>
      <button id="allowBtn" style="padding:6px 10px;border-radius:10px;border:1px solid rgba(255,255,255,.25);background:#222;color:#fff">
        Allow host
      </button>
    </div>`;
  document.body.appendChild(el);

  el.querySelector("#allowBtn").addEventListener("click", async () => {
    try{
      const ok = await RTOAllowlist.add(host, 4000);
      el.remove();
      alert(ok ? "Allowed ✓" : "Not allowed");
    }catch(_){
      el.remove();
    }
  });
}

Next