# Toolaby popup

> The popup — or side panel — the wiring puts in front of yours, and the paywall it shows.

Which surfaces to give your extension, and how to start each one, is [Surfaces](https://toolaby.app/docs/surfaces.md). This page is what the platform's own page does once it is there.

The wiring sets `toolaby-popup.html` as the extension's action popup. At every open it reads the tool's policy and the device's state, then either opens your own popup (`appPopup` in `toolaby.config.js`) or shows the paywall. Your popup is unchanged. An extension with a side panel gets the same in front of that — see [The side panel](#the-side-panel).

## When it opens your popup

How it decides depends on whether your code counts its own uses, which `countOpens` in `toolaby.config.js` says. `wire` and `upgrade` write it from your code.

|                  | Your code calls `toolaby.gate()` (`countOpens: false`)                                                                             | Your code calls no `gate()` (`countOpens: true`)                                                                   |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Opens your popup | At once, unless the person may not use the extension yet: nothing free and no plan held, or an account required and none signed in | When `gate()` allows: the Free plan holds everything, free uses remain, or the device holds a plan, trial or grant |
| A free use       | Spent by your `gate()` at the paid action, never by opening                                                                        | Spent by each open, when the Free plan counts uses                                                                 |
| Free uses spent  | Your popup opens; the paywall shows at the paid action                                                                             | The panel shows the meter and the plans                                                                            |

Either way, a change under **Access** in the dashboard shows at the next open: switched to *Nothing free*, the plans show before your popup.

To count at the action instead, put your popup first: your popup is the action popup, `appPopup: ''`, and your code calls `gate()` at the action and `showPaywall()` when it refuses. The paywall then opens in this same page, on request. See [Gate your extension](https://toolaby.app/docs/gating.md#1-choose-what-opens-first).

## The paywall

When the device may not continue, the popup shows one of:

| Refusal        | Shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sign_in`      | The tool needs an account (Pricing → Access) and there is none, and there is something free to use once they have one: the title, one line, and the doors — **Continue with Google** (it opens your sign-in page already going to Google), a hairline *or*, **Continue with email**. Google sign-in is on for every workspace, through Toolaby's Google client or your own from **Configure → Sign-in**. Nothing else: the header above it already carries your mark and the tool's name, and who sells it belongs where money is asked for. |
| `limit`        | The device's free-use meter — *Free uses · 7 / 10* and a bar — then the plan to buy.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `paid`         | Nothing is free: the plan to buy — name, price, the *Recommended* badge and the first three lines of what it includes, as on the checkout page — one button that opens its checkout, the other plans as rows below, and *Already bought it? Sign in* at the foot. This is what a tool that also needs an account shows a stranger: the price first, the account at the checkout.                                                                                                                                                             |
| `feature`      | *Export is in Team*, and only the plans that hold the feature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `past_due`     | The account's subscription is past due: *Payment failed — update your card*, and the way to the account page. See [Subscriptions](https://toolaby.app/docs/subscriptions.md).                                                                                                                                                                                                                                                                                                                                                                                      |
| `device_limit` | The account holds a plan, and this device is past its device limit: *In use on 2 devices already*, and the way to the account page.                                                                                                                                                                                                                                                                                                                                                                                                          |
| `blocked`      | Your message from Versions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

Under it: *Already bought it? Sign in*, and who sells the tool. Once the device is unlocked, the same panel shows the plan held and how it stands — *Renews 22 Oct · €3 / month*, *Ends 22 Oct · €3 / month*, *Lifetime licence · since 4 Mar*, *Trial until 29 Sep* — the account it is on, and the way to the account page. Bought while the popup is open, it turns without a reload.

The header carries the extension's own icon, from its manifest, and the tool's name. The panel is drawn in your brand — accent, corners, colour mode from **Configure → Branding** — in system type, no font shipped, and in the buyer's language. Its facts come from the tool's public endpoint, `GET /api/tools/<tool-id>?lang=<code>`, and are cached on the device for a day, so it opens offline and at once. The signed manifest the client checks at every open carries a stamp of the brand and the pricing; when it moves, the popup fetches its facts again at that open and redraws. So a change under Branding or Pricing is in every popup at its next open, not a day later.

**Configure → Branding** has a **Popup** tab, and a tool's **Pricing** page has **Preview**: the panel drawn by the very files the extension ships, in your brand, one state at a time — *Free uses*, *Limit reached*, *Sign in*, *Paid tool*, *Feature*, *Unlocked · your popup*, *Payment failed*, *Update needed*. *Feature* is offered once a plan sells a feature, and *Payment failed* once the tool has a subscription plan. What you see there is what buyers get.

The panel lives inside `toolaby.js`, the one file the wiring writes beside your code — the client and the popup UI together, minified, with its stylesheet inside. Do not edit it; style your own popup in your own files. `npx -y toolaby@latest upgrade <tool-id>` replaces it.

## The account bar

Once a device is through, the Toolaby popup hands over to yours and the buyer never sees it again — so your popup is where they look for who is signed in, their plan, their account and sign out. (The Branding page's preview shows this state as your popup's stand-in with the bar at its foot, since the Toolaby popup is not what they see.) **Sign out** in the bar signs the device out on the account too: it leaves the account page's Devices at once. `toolaby.js` defines it as one tag:

```html
<script type="module" src="toolaby.js"></script>
<toolaby-account></toolaby-account>
```

One line. On the left, where the person stands: the free uses left, with a ring that fills as they are spent and turns amber when they are gone; signed in, their initial or picture and address, with the uses, the plan held, or a failed payment under it. On the right, the actions: **Upgrade** while there is a plan to buy, **Sign in** or their account page and sign out. At most one button is filled, in your accent: Upgrade, or **Update card** after a failed payment.

Upgrade opens the Toolaby popup's panel with the plans and a Back button, as `showPaywall()` does, and comes back by itself once a plan is held; from a page open in a tab, the checkout page opens in a new tab. It takes the colour scheme of the page it sits in (from your popup's background), so it belongs to your popup; only the accent is the brand's. It talks to the background over messages, so it works in any popup however it is built, and reads the same cached facts the panel does.

The wiring puts it there for you. In a plain extension, `wire` and `upgrade` write it flush at the foot of your popup and side panel (`data-dock`), between `<!-- toolaby: account bar -->` markers, and write it again at every upgrade; in a WXT project the module adds it as it builds. Place the tag yourself to put it elsewhere, and the wiring leaves your page as it is. Set `accountBar: false` in `toolaby.config.js` to keep it out: the next `upgrade` takes it out. A CRXJS or Plasmo popup takes the tag by hand.

| Attribute or method |                                                                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scheme`            | `light` or `dark`: the bar's colours. Without it, they follow your page's background, read again at each redraw. Set it when your page switches themes by a class.                       |
| `data-dock`         | Flush at the foot of its container: no border but the top one, no corners.                                                                                                               |
| `refresh()`         | Draws the bar again now. It already redraws the moment the device's account changes (signed in or out, bought, refreshed) or a free use is spent, so this is for a change it cannot see. |

The popup's **Sign in** opens the workspace's sign-in page in a tab, titled &#x2A;Sign in to connect \<tool>* — the one-time link by email, and Continue with Google — and the page hands the extension its credential when it is done.

## The side panel

An extension with a side panel gets Toolaby there too. The wiring sets `toolaby-sidepanel.html` as `side_panel.default_path` (and adds the `sidePanel` permission), and at every open it gates exactly as the popup does, then hands over to yours — `appSidePanel` in `toolaby.config.js` — or shows the panel at the side panel's width. It is the same page and the same files: a two-line shell that calls `mountSidePanel()` from `toolaby.js`. The account bar goes in your side panel as it does in your popup: written by the wiring in a plain extension, from the module in a WXT project, with the tag anywhere else.

One warning worth having: Chrome refuses to **load** an extension whose `side_panel.default_path` names a file that is not there — the whole extension, not just the panel. Remove a side panel and you remove the key and the `sidePanel` permission with it.

Chrome opens **one** surface from the toolbar button, never both, and a popup, when the manifest names one, wins. With a side panel and no popup, the client sets the panel to open on the click (`sidePanel.setPanelBehavior`), so the button does what it did before you wired it. With both, the popup keeps the click and your side panel opens from wherever you open it — a button in the popup, a command, a context menu, the browser's side panel menu — and Toolaby's stands in front of it there too.

The panel is drawn for the surface it is on: 336px wide in a popup; in a side panel it fills the width up to a readable column, centred, with what it has to say — the sign-in doors, the meter, the plans — sitting in the middle of the column rather than stranded at the top of a tall empty one. A state taller than the panel simply fills it and scrolls.

A side panel of your own — one that draws the panel itself with `loadPaywall` and the renderers, instead of putting Toolaby's in front — needs one attribute:

```html
<html data-toolaby-surface="sidepanel">
```

`ensureStyles()` sizes a page as a 336px popup unless that says otherwise, so without it your side panel would sit in a 336px column. Nothing else differs between the two surfaces.

Firefox is not supported yet. See [Frameworks](https://toolaby.app/docs/frameworks.md#other-bundlers).

**Branding → Popup**, and **Preview** on a tool's **Pricing** page, show the panel at either width.

## Without the Toolaby popup

A framework that cannot put a page in front of yours (Plasmo), or a tool that wants its own paywall, decides at the open from `getUser()`, as the Toolaby popup does, and draws the paywall only when the person may not use the extension yet, with `loadPaywall`, `applyBrand`, `renderMark`, `renderPaywall`, `renderUnlocked`, `renderNotice` and `refusalOf` from `toolaby.js`. See [Frameworks](https://toolaby.app/docs/frameworks.md#plasmo) for the code, and [Panel](https://toolaby.app/docs/reference/panel.md) for each function.
