Repository navigation
admin ui
The admin page is how a person watches and tidies what agents do. It lists the workspaces, opens
one, and shows its browser, files, flows, site data, history, capture and live screen. It is a
Svelte 5 app under ui/, built into one script and one stylesheet that the server inlines into a
page it serves at its own root. This file holds how the page is built and served, how it signs in,
how it stays current, the conventions every tab follows, and the design it is drawn from. What each
tab's routes do is in the area files named below.
- A person opens the server's URL, signs in with the token or the issuer, and sees every workspace with its browser state.
- A person opens a workspace, watches its browser, takes a screenshot out of Files, ends the browser, or edits a saved flow.
- A person leaves the page open and sees a browser appear, a file land or a recording finish without reloading.
UI-1. The sign-in checks and the admin door are in auth-and-roles.md. The routes behind each tab are in:
- workspaces-and-sessions.md: End and the record;
- workspace-files.md: Files;
- saved-flows.md: Flows (FLOW-45 to FLOW-47);
- site-data.md: Site data and History;
- capture.md: Console and Network;
- live-view-and-control.md: Live;
- secrets-and-scope.md: Secrets;
- config.md: Settings.
The tool that draws a resource in the MCP App is in surfaces.md. This file does not restate them.
UI-2. The source is ui/: Svelte 5, TypeScript, Vite. Its runtime dependencies are marked (the app's
document view), noVNC (the live view) and @modelcontextprotocol/ext-apps (the MCP App). It holds
no router or state library: routing is a small module of its own and shared state is classes using
Svelte runes.
UI-3. npm --prefix ui run build makes three bundles into kubed/selenium_flow/http/static/,
which is gitignored and never committed. The files have fixed names:
| Surface | Files | Loaded |
|---|---|---|
admin |
admin.html, admin.js, admin.css
|
inlined into the page |
app |
app.html, app.js, app.css
|
inlined into the MCP App shell |
live |
live.js, live.js.LICENSE.txt
|
fetched by the page when the Live tab opens |
UI-4. The admin and app builds each produce one script and one stylesheet with no shared
chunk, because the server inlines them. live.js is separate so the page loads without noVNC. The
admin build alone copies the two shells from ui/public/. npm run build empties the output
folder first.
UI-6. A surface is built when all three of <name>.html, .css and .js exist. The server logs one
INFO line at start when the admin surface is not built.
UI-7. GET <mount>/ answers the page with no credential, since it is the sign-in form and
every datum it shows is fetched with a credential afterwards. GET <mount>/admin answers a 301 to
./, so the page has one address.
UI-8. The server builds the page from admin.html once per set of substitutions and per version of
the three files (their mtime and size). It removes the shell's own HTML comments, inlines the
stylesheet and script, and fills three placeholders, which land as data-mount, data-console and
data-oidc on the root element and are read once at boot:
-
__MOUNT__, the mount prefix; -
__CONSOLE__,grid.console_url(default/); -
__OIDC__(AUTH-33).
Substitutions are HTML escaped, nothing inside the bundle is substituted, and a literal </script
in the script is escaped.
UI-10. The page is sent with Cache-Control: no-cache and a strong ETag of the built HTML. A
request whose If-None-Match names it gets a 304. A rebuilt UI is served on the next load.
UI-11. The page is sent with the headers AUTH-33 lists: Content-Security-Policy: frame-ancestors,
X-Content-Type-Options and Referrer-Policy. The placeholder page of UI-13 carries the same.
UI-12. GET <mount>/live.js serves the live bundle with no credential, no-cache, an ETag
and text/javascript, and a 304 on a matching If-None-Match. Without a build it is a 404 with
an error.
UI-13. When the admin surface is not built, GET <mount>/ answers 200 with a page whose title
and only heading are Selenium Flow. The rest of the server is unaffected.
UI-14. When the app surface is not built, the MCP App is not registered and the file tools and
show behave as with mcp.apps off: they return their data.
UI-15. The page works at a root mount and behind an ingress that strips a prefix. Its base is its own path with trailing slashes removed. Server-issued URLs already carry the mount, so the app resolves them against that path with the mount taken off.
UI-16. The page is one header (the name selenium-flow and, once signed in, Sign out) over one of two
things: the sign-in card or the signed-in page.
UI-17. The signed-in page has four top tabs: Workspaces, Secrets, Settings and Grid console. The
Grid console tab is hidden when grid.console_url resolves to the page itself, and then no frame is
made, since framing the page nests it without end. Otherwise the console frame is mounted once and
hidden when another tab is up, so switching tabs does not reload the Grid's console.
UI-18. Routes are the address's hash, so no route reaches the server. The hash is read at boot
and on every hashchange:
| Hash | View |
|---|---|
#/ and anything unknown |
the workspace list |
#/console, #/secrets, #/settings
|
that top tab |
#/workspaces/<key> |
a workspace, on Session |
#/workspaces/<key>/<tab> |
a workspace tab: session, files, flows, site-data, history, console, network or live
|
#/workspaces/<key>/flows/<name> |
Flows with that flow open |
#/workspaces/<key>/site-data/<host> |
Site data with that host open |
#/workspaces/<key>/network/<id> |
Network with that request open |
An unknown tab reads as Session. A key or segment that does not decode reads as the list.
UI-19. Opening a workspace builds its detail view afresh and destroys the previous one, with its loads, lightbox and modal. Nothing started for one workspace can land on another's screen.
UI-20. The card shows a password field MCP token, an Enter button, and, when data-oidc is set, a
Sign in with OIDC button below. A refused token shows That token was refused.; any other message
the app has to say shows in the same place.
UI-21. The token's life on the page, its probe and sessionStorage['sf-token'] are AUTH-34. The token
is never written to localStorage.
UI-22. Every call sends the credential as a bearer. A 401 on a token sign-in signs out (AUTH-34), and Sign out is AUTH-44. The OIDC steps (PKCE, the reply checks, renewal, the messages) are AUTH-35 to AUTH-43.
UI-24. The list heads with Workspaces and a connection indicator (UI-33), and shows
Loading… until the first answer, the error text when the load failed, and No workspaces yet.
when there are none.
UI-25. Each workspace is one card, in the server's order (most recently used first), and a click anywhere on it opens the workspace. A card shows:
- the browser's mark (a glyph for Chrome, Firefox, Edge and Safari, a globe otherwise);
- the name pill: the workspace's name, else its owner, else
workspace; - the Grid session id, or
no browser; - a state pill:
open,idleorunknown(a browser the Grid's listing could not confirm); - a capture pill when capture was asked for:
● capturewhile entries are arriving,capture pausedotherwise; - a meta line: browser and version, counts per file kind (zero counts left out), the age of the
start, the node, and
by <opener>(tokenor the OIDC username); - the last page's URL.
UI-26. A workspace opens on a masthead and a row of tabs. The masthead repeats the mark,
the name, the state pill, a ● REC pill while a recording runs, the capture pill, and the last page
as a link only when it starts http:// or https:// (else as text, or nowhere yet). It is blank
until the workspace's row arrives.
UI-27. The detail view has a Back button to the list and an End browser button, disabled unless a
browser is attached. It asks through the browser's confirm, then sends
DELETE /admin/workspaces/{key}/session (WS-17). The workspace and its context stay. A failure
alerts Could not end the browser: <error>. A success closes the overlays about the browser's
downloads and reloads Files and Flows.
UI-28. The tabs, in order, each routed by UI-18:
| Tab | What it is for | Count | Routes and rules |
|---|---|---|---|
| Session | What the workspace asks for, what the Grid gave, and every capability the last open sent | none | the pushed row |
| Files | Downloads, Screenshots, Recordings and Files | files in the row | workspace-files.md |
| Flows | The saved flows and the open one | flows, or off
|
saved-flows.md |
| Site data | What is saved per host | hosts | site-data.md |
| History | Where the workspace has been | hosts | site-data.md |
| Console | The page's console | entries | capture.md |
| Network | The page's requests | requests | capture.md |
| Live | The browser's screen | none | live-view-and-control.md |
UI-30. Console and Network are disabled (aria-disabled, muted, with a title) when the row says
capture is off, and their pane then says Capture is off for this workspace. Open the browser with open_session(capture=true). Live is disabled with a title that gives the first reason that holds,
in this order: no live view · switched off, no live view · grid not answering, no live view · no browser, no live view · headless, no live view · this Grid has no VNC.
UI-31. The Session tab shows a workspace group and, once a browser has been opened, a Grid group, then a Capabilities section that starts closed. A fact with no value is left out.
- The workspace group: the key and who holds it (only for an unnamed workspace), the browser asked
for with its version (
latestwhen none), the window, insecure, headless, record and capture (the last two only while a browser is up). Each setting a caller or the server chose carries a pill naming where it came from. - The Grid group: the browser and version, the session id, the node, the start time, the idle
timeout, and then
grid: not answering, orlive view: yes/no, or how the last session ended (ended by the admin,ended by the caller,reaped after N s idle,gone from the Grid). - The Capabilities section lists each capability the last open sent with its source pills. A
vendor block (
goog:chromeOptions,moz:firefoxOptions) shows what it holds by count (args 3 · prefs 6), never its values. With none sent it saysNothing sent yet: no browser has been opened in this workspace since this server kept it.
UI-32. Which panes stay mounted: Session, Files, Flows, Site data and History stay mounted and are hidden when another tab is up, so a folded section stays folded. Live, Console and Network are mounted only while shown, so leaving the tab closes a live socket or stream.
UI-33. The workspace list is pushed. GET /admin/workspaces answers the rows, live_enabled and
events_url, a signed path for the stream because EventSource cannot send a header (AUTH-29).
The page opens events_url once, resolved against the page's base, and applies every message as
the new list. The indicator is a dot while the stream is live, connecting… before it opens and
reconnecting… after an error.
UI-34. One server task computes the list every 2 seconds for all connected pages, and only while a page is connected. A page receives a message when the payload differs from its last. A keepalive comment goes out after 20 seconds of no change. A route that changes what the list shows (End, Forget, Clear, Keep, Delete, and a flow's save, move or delete) discards the last computation so the next one is fresh.
UI-35. A fallback runs every 30 seconds. When nothing has arrived for 45 seconds the indicator
reads polling, the page refetches GET /admin/workspaces, applies it, and reopens the stream on
the freshly signed events_url, because the signed URL expires.
UI-37. A pushed row carries revisions: files_rev, flows_rev, site_data_rev and history_rev. An
open workspace reloads a tab's data only when that tab's revision moved, so a push that changed
nothing for the tab costs nothing:
- Files reloads when
files_rev, which also holds the browser id, changes. - Flows reloads when
flows_revchanges, which covers the workspace's flows and the shared ones. - Site data and History both reload when either revision changes, since each reads the other.
UI-38. When a push shows a different browser id, or live flipped, the page closes the
lightbox and any confirm that acts on the browser's downloads, blanks the Downloads grid, and forces
a reload of Files. A different browser is a different download store.
UI-40. Loads for one panel overlap safely. Each new load aborts the one before it, only the newest paints, and an awaiting caller can wait until the newest has settled. A load tied to a workspace is aborted when its view is destroyed.
UI-42. A tab that has loaded nothing says Loading…. A failed load shows the server's error
text (error of the response, else request failed (<status>)) where the data would be. A tab with
nothing to show says so in one sentence. The sentences:
| Where | Text |
|---|---|
| Workspaces | No workspaces yet. |
| Downloads |
No downloads., or No browser — downloads go with it. when none is attached |
| Screenshots, Recordings |
No screenshots yet., No recordings yet.
|
| Files | Nothing here yet — prints land here, and anything you keep. |
| Flows |
Flows are off: this server was started with no DATA_DIR., No flows yet.
|
| Site data | Nothing saved — an agent calls save_site_data after signing in. |
| Secrets | No secrets are configured on this server. |
| Console, Network |
No messages since the last navigation, No requests since the last navigation
|
UI-43. A destructive action opens one confirm box, never two. The box names what goes and,
where it matters, what stays. Its confirm button is the verb and the count (Clear 3 files,
Delete 2 screenshots, Forget, Clear, Delete), is danger-coloured, and is disabled while the
action runs. Cancel, Escape and a click on the backdrop all cancel. A failed confirm leaves the box
open and shows the error in an alert, so an edit is not lost. Only one box is open at a time.
UI-44. A confirm opens for each of these, with a body that says:
- Clear downloads: lists each download with
— gone, or— copy in Files stayswhen Files holds one of that name, or says there is nothing to clear. - Clear screenshots, Clear recordings: the count, and that anything kept in Files stays.
- Delete a file (Files): that it goes for good and has no undo.
- Forget site data, Clear site data, Clear history: which entries go and which stay, as
goesandstaysrows. - Delete a flow: that it is removed from the folder it lives in, and that a global flow goes for every workspace.
- Move a flow: which library it moves to and that other workspaces stop or start seeing it.
End browser uses the browser's confirm, not the box.
UI-45. A button that acts is disabled when it cannot: End browser with no browser attached; Clear downloads unless the browser is running, this workspace's files have loaded and no load is in flight; Clear screenshots and Clear recordings when there are none or a load is in flight; Paste unless Control is held.
UI-46. A section is an accordion: a button with aria-expanded and aria-controls, a caret, a count
pill and its actions. All start open except Capabilities and every Site data and History row past
the first. A fold is remembered by id for the life of the page, so a section that remounts keeps
its state.
UI-47. The page writes data as text. It renders no HTML from data: {@html} is forbidden by
lint, and captured console text, requests, cookies and flow arguments are shown as text nodes. A URL
is a link only when it starts http:// or https://.
UI-48. A value is shown as a word or a mark where one will do. The Settings tab shows ●●●● for
a sensitive value that is set and — for one that is not. A connected stream is a dot with no words,
and Secrets and Settings show no value a person could paste.
UI-49. Motion is polish only. A transition lasts at most 150 ms, runs only on a change within the
page (not on first paint or a route change), and is zero under prefers-reduced-motion.
UI-51. The Secrets tab shows GET /admin/secrets under a heading and one sentence, one card per
secret: its name, warning pills (unusable until fixed, key unresolved, inline value), its
description, the reason it is refused, its key pills with their source when not a file, its
allowed leash (— when none) and from, where its definition came from. The catalogue is in
secrets-and-scope.md.
UI-52. The Settings tab shows GET /admin/settings: a card per section, a row per setting with
its name, value and a source pill (default, config, env or args, weakest first, which is the
order of precedence), and an i that shows the setting's description. It is read-only and links to
the wiki's Configuration page. What it lists is in config.md.
UI-53. The Flows tab is a list and a panel side by side. A list row shows the flow's name, its step count and a globe when the flow is shared. Picking a row, even the open one, loads the flow document and puts its name in the hash without adding a history entry.
UI-54. The panel shows the name, a 🌐 global pill when shared, the description, and three
buttons: edit, move and delete. Move is hidden in the global workspace. Below sit Params, then
Steps, and a detail pane that reads Pick a parameter or a step to see what it holds. Params say
This flow takes nothing. when none.
UI-55. A parameter row shows a type glyph and a required marker. A step row shows its action's
glyph (❓ for a name the runner does not run), its id chip and a lock when the step types a secret.
Clicking a row shows its detail, and clicking the shown one hides it. A step's detail shows its
number, tool, note, arguments (a selector as css … or xpath …, a secret as name / key) and
onError and return only when set. A parameter's detail shows its type, required or optional,
description, default and the steps that read it, each a link to the step.
UI-56. Edit reads the flow again before it opens, so the editor holds the raw file with its
comments and not the copy on screen. A failed read alerts Could not read that flow: <error>. Save
sends the text as PUT {yaml}, and the box stays open with an alert on error.
UI-57. Move sends POST …/move {to} and delete sends DELETE. Afterwards the flow closes, the hash
returns to …/flows and the list reloads. A listing that does not hold the open flow closes it and
resets the hash; otherwise the listing reload also reloads the open flow. A deep link to a flow
opens it only once the listing says it exists.
UI-58. A flow file's shape is never trusted. A steps that is not a list, a parameters that is
not a mapping, a null step or a key such as constructor does not break the panel; the editor is the
way to fix it.
UI-60. The MCP App is the app surface. It draws one view by the component name in a show result
(context, console, network, request, file, files, folder, flows, flow, sites,
site, secrets, document), from the data the result carries. The views are read-only: no
clear, keep or delete. The table from URI to component is in mcp/show.py (surfaces.md).
UI-66. The shell drills down by calling show through callServerTool, never sendMessage.
UI-67. The shell shares the shown URI with updateModelContext, best effort. Nothing depends on
it.
UI-68. claude.ai ignores size-changed and reads the document's height, so the app sets
documentElement.style.height as well as letting autoResize report it.
UI-69. read_resource carries no app. It is the model's reading tool, and an app on it would be
drawn on every read.
UI-62. The design is a Penpot file named Admin UI, whose Admin page holds the top-level views.
UI-63. (proposed) Where the drawing and the code differ, the code is the truth, and the drawing is redrawn in the round that notices. A change to a view edits the drawing, and a change to behaviour edits this file.
Not built. The reasoning, and the questions still open, are in the multiplayer design.
UI-64. (proposed) A workspace with more than one session shows a dropdown of its sessions in
the row with ← Workspaces (UI-27). With one session there is no dropdown. Picking a session
refocuses the session's tabs (UI-65) on it.
UI-65. (proposed) Session, Console, Network and Live are the picked session's tabs. Files and Flows are the workspace's. Replaces, when built, UI-28's table for those six tabs. Where Site data and History belong is open.
Not built. See the flow tags design and the workspace config design.
UI-70. (proposed) The Flows tab filters its list by tag (FLOW-52).
UI-71. (proposed) The admin UI edits a workspace's config (WS-61), and a change takes effect without a restart.
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network