pal inside other web apps
A web app can show pal inside its own pages: the bar's items across the top with their popovers, and the panel (search, palettes, live views, forms) over the page on a key. The pal is the one you run (Settings › General › Remote serves it to other devices); the page frames its pages and hears what happens in them. Nothing about your extensions changes, and they keep running on the machine pal runs on.
One tag
<script type="module" src="https://pal.lan/__pal/embed.js"></script>
That is all a page needs. It loads from the pal you run, so it always matches it, and does the rest itself:
- The bar across the top of the page, fixed, the page's own background
behind it. Its height is published on
<html>as--pal-bar-h(0px while it is not shown), and<html>has the classpal-barwhile it is, so the page reserves the room:body { padding-top: var(--pal-bar-h, 0px); }. - The panel in an overlay: a scrim, the panel in a dialog, focus moved into it and back where it was when it closes; Escape, a click on the scrim, or a pick that would hide pal closes it.
- Keys, pal's own and the same on every site: shift P opens and
closes the panel, shift B shows and hides the bar. Never while
someone types in a field or an editable element, and never a key the page
already handled (
preventDefault). - Which bar items show, per device: a right-click on the strip (a long press on a phone) lists every item to tick on or off. The pick is kept in the page's own storage, so per site and per browser; until a device picks, the site's default from pal's config shows (Settings, below).
- Light or dark as the page is: the page's background decides, else
its
color-scheme, else the device's; a page that flips its theme flips pal with it. - A link a pick opens opens in a new tab, unless the page handles
pal-openitself and callspreventDefault(). - Silent when pal is not there: unreachable, the site not allowed, or the device not signed in, it draws nothing and throws nothing.
The tag's data-* change that:
| attribute | what |
|---|---|
data-token |
This site's token (Settings › Copy snippet), for a device outside your tailnet. |
data-bar |
none: no bar (and no bar key). A CSS selector (#top): the strip goes inside that element, in its flow, instead of fixed to the top; no --pal-bar-h. |
data-keys |
panel:<keys> bar:<keys>, e.g. panel:ctrl+k bar:none; none for no keys at all. Keys are ctrl, alt, shift, meta and a key name joined by +. |
data-theme |
light or dark always; pal: pal's own theme, not the page's. |
window.pal
So a page can put pal in its own command palette or menu:
| what | |
|---|---|
pal.toggle() |
The panel opened, or closed when open. |
pal.open(palette?) |
The panel opened, in ext/palette when given. |
pal.close() |
The panel closed. |
pal.bar(on?) |
The bar shown or hidden (flipped without on), remembered for this site on this device. |
pal.theme(tokens) |
Theme tokens over those the page's CSS sets (below): { accent: "#0a7", radius_row: "3px" }, keys as in a theme file or as --pal- names; null clears them. |
pal.ready |
A promise: true once pal is up on the page, false when it will not be. A page can hide its own pal entry on false. |
The module is also @zcag/pal-web/embed for a build that bundles it; it
then asks the pal at its own address, so serving it from pal is the usual way.
Match your site
pal draws itself in its own theme unless the page says otherwise. A page
says it with the tokens of a theme file, set as
custom properties on <html>, --pal-<key> with _ as -:
:root { --pal-accent: #1d1d1b; --pal-bg: #f4f4f1; --pal-fg: #1d1d1b; --pal-font-ui: Recursive, sans-serif; --pal-radius-row: 3px; }
:root[data-theme="dark"] { --pal-accent: #ececea; --pal-bg: #18181a; --pal-fg: #ececea; }
The tag reads them on load and again whenever <html> or <body>
changes an attribute (a class, a style, a data- flag) or the device
flips between light and dark, so tokens set inside the page's own
dark-mode rules make a matching pal with no script. pal.theme({...})
sets them from code instead, over the CSS ones.
| tokens | kind |
|---|---|
accent, accent-fg, accent-soft, bg, bg-glass, bg-elevated, bg-sunken, fg, fg-muted, fg-faint, line, line-strong, selection, scrim, match, knob, destructive(-soft), success(-soft), the tag-* and brand-* colours, tile-fg, tile-ring |
a colour: anything the browser reads (oklch() and names are passed on as rgba()) |
radius-panel, radius-popover, radius-hud, radius-tile, radius-row, radius-icon, radius-control, radius-tag, radius-kbd |
pixels (3px) |
font-ui, font-mono |
a font stack. A family the page loads itself (@font-face in one of its stylesheets) is loaded in pal's frames from the same files, which pal's origin fetches: the page's server answers those font files with Access-Control-Allow-Origin (pal's address, or *) |
Theme file says what each one colours. pal checks
every value as it checks a theme file's; one it cannot use is dropped with
a console warning on the page naming the token (pal: --pal-radius-row: ignored: expected a number of pixels), and the rest apply. Only that
page's frames change; pal elsewhere keeps its own theme. A page that sets
none looks as it did before.
What the page still does
- Content-Security-Policy, if it sends one:
script-srcandframe-srcfor pal's address,connect-srctoo (the tag asks pal whether the site is allowed:/__pal/embed.json). - Reserve the bar's room with
--pal-bar-h, as above. - To match pal to its look, its
--pal-*tokens, and CORS on the font files they name ("Match your site"). - Nothing else; the elements below are for a page that wants to place them itself.
Allowing a site
The first time a page with the tag is opened, pal lists it in Settings › General › Remote as "https://app.example wants to show pal", with Allow and Deny. Allow is a decision made in pal, never by the site: a site's token can do what your extensions can on that machine, like the main token, so allow only sites you trust with that. A denied site is not asked about again (Settings lists it with an Allow to undo that). Nothing shows on the page until it is allowed; a reload then shows pal.
Settings › General › Remote › Inside other sites also takes addresses
typed by hand (https://app.example, scheme, host and port only). Each
allowed site gets its own token, and a row of its own: Copy snippet
copies the tag with its token, and its bar items are the default for
that site, the items a device sees until it picks its own. In the config
file these are [remote] embed_origins, embed_denied and
embed_bar_hide (Config).
- A site not on the list cannot show pal at all: every page pal serves
says who may frame it (
Content-Security-Policy: frame-ancestors), pal itself and the listed sites, and the browser refuses everyone else. - A site's token works only while the site is listed: taking it off signs it out. Replace on the main token changes every site's token too.
- On one of your own tailnet devices the token is not needed, as for the remote page itself.
The elements
The tag above is built on two custom elements, which a page can use
directly to place pal itself (in its own header, its own dialog).
@zcag/pal-web (this repo's web/) defines them; it has no framework
dependency, so it works in a plain page, React, Vue or anything else.
Load it from the pal you frame, which serves the copy that matches it at
/__pal/web.js (one module, no sign-in, readable cross-origin by the
allowed sites, so import() works too); the npm package is the same code
for a build that bundles it.
<script type="module" src="https://pal.lan/__pal/web.js"></script>
<pal-bar server="https://pal.lan" token="…"></pal-bar>
<pal-panel server="https://pal.lan" token="…" links="host"></pal-panel>
<script type="module">
const panel = document.querySelector("pal-panel");
panel.addEventListener("pal-pick", (e) => console.log("picked", e.detail.name));
panel.addEventListener("pal-open", (e) => router.go(e.detail.url));
panel.focus();
</script>
Or from a bundler: npm i @zcag/pal-web, then import "@zcag/pal-web".
<pal-panel>: the panel. It is never hidden: a pick that would hide
the panel in the app leaves it at its start instead. Its height is yours
(440px unless you style it).
<pal-bar>: the bar's items as a quiet strip, live, each item on the
side its position in [bar.items] says, in its order: left, then
sketchybar's q and e (the notch's sides; a page has no notch, so they
follow the left items), center in the middle, and anything else on the
right, as the menu bar draws it. A strip wider than the
element scrolls sideways (a mouse wheel too). The element's height is the
strip's, which pal tells it (26px today), so your page needs no number.
A click opens the item's popover under it, drawn over your page, and a
click outside the popover or Escape closes it. A right-click on the strip (a long
press on a phone) opens the item picker: it changes hide and tells
pal-bar-hide, for your page to keep.
| attribute | on | what |
|---|---|---|
server |
both | pal's address, as Settings shows it. |
token |
both | This site's token, for a device outside your tailnet. |
palette |
panel | ext/palette: the panel starts there and goes back there after a pick. |
theme |
both | light or dark over pal's own theme. Changing it applies at once. |
links |
both | host: a URL a pick opens is only told (pal-open), for your app to open; otherwise pal opens it in a new tab and still tells. |
transparent |
panel | The panel draws no background of its own. |
hide |
bar | Item keys, comma-separated, as pal bar list prints them (hide="dpi/bypass,audio/volume"), that leave the strip; any other item, a new one included, shows. Changing it applies at once, without reloading the frame. |
| method | on | what |
|---|---|---|
tokens(map) |
both | Theme tokens over pal's own in this frame ({ "--pal-accent": "#0a7" }, "Match your site" above), kept across reloads; {} clears them. |
focus() |
both | The search field focused. |
reset() |
both | Back to the start (the root, or palette). |
open(palette) |
panel | Straight into a palette (ext/palette). |
query(text) |
panel | The search field set to text. |
close() |
bar | The open popover closed. |
Events are CustomEvents that bubble out of the element (cancelable, so a
listener can preventDefault() what the one-tag layer would do next), with this detail:
| event | detail |
|---|---|
pal-pick |
{ id, name, subtitle?, palette?, action? }: a row was picked, in the panel or a popover. Never the row's data. |
pal-hud |
{ text, large? }: a HUD line (or Large Type) pal showed. |
pal-copy |
{ text }: what a pick put on the clipboard. |
pal-open |
{ url }: a URL a pick opens. |
pal-bar-open |
{ key, title }: an item's popover opened. |
pal-bar-close |
{}: it closed. |
pal-bar-items |
[{ key, title }]: every item the bar has, those hide leaves out included, once the strip is up and again whenever the set changes; for a picker of your own that writes hide. |
pal-bar-hide |
{ keys }: someone picked which items show, in the strip's own picker; the element has already taken keys as its hide. |
pal-dismiss |
{ reason: "escape" | "pick" }: where the app would hide pal. escape: Escape with nothing left to back out of (a level, the query, the actions), or in <pal-bar> with no sheet open; pick: a pick that hides the panel (a copy, an open). A host showing pal in an overlay closes it. |
What a pick does on the machine (pasting, moving windows, opening a file or an app) still happens there, as on the remote page (design, "Where an effect lands").
Signing in inside a frame
A page framed by another site gets no ordinary cookie, so the element
puts the token on the frame's address and pal keeps it in a partitioned
cookie (SameSite=None; Secure; Partitioned), one the browser keeps for
that site's frames only. That needs pal served over https (it has to be
anyway: an https page cannot frame an http one), and a browser that keeps
partitioned cookies (Chrome, Edge and Firefox do). On a tailnet device
none of this is needed.
The demo
web/demo/index.html is a host app with an event log, in two ways: as
it is, the one tag from the pal it names; with &elements, both elements
placed by the page itself. Serve web/ on some origin (for the elements,
build the package first: cd web && npm run build), open
/demo/?server=https://pal.lan&token=<the site's token>, and Allow the
origin when pal asks.
Rendered from docs/embed.md in the pal repo, 2026-11-22.