symbion: a keyboard-first NiceGUI PWA over a coding agent's tickets, and what we tripped over

[phreakocious]

Hi all. symbion is a notebook and ticket registry that a person shares with their coding agents (Claude Code, Codex): bugs, tasks, questions and test results, kept as dated entries in a git repo beside the project. The agent works it through a CLI. symbion serve is the NiceGUI app where the person reads it and answers.

• Live demo, read-only, on a one-vCPU VPS, so the first page takes a few seconds: https://symbion.nullphase.net/
• Repo, MIT: https://github.com/phreakocious/symbion. The GUI is in src/symbion/gui/.
• pipx install 'symbion[gui]'

What the app does

• It opens on what waits on you: the agent's questions, each with a button for every answer the agent offered.
• It is keyboard first. j/k peek at entries in a drawer beside the page; x resolves, a answers, e edits. n writes a new entry from any page. ⌘K opens a palette that also searches every other store a serve runs on.
• It notices other writers. A ui.timer checks the store file's mtime and size, and a button counts the entries an agent wrote since the page was drawn. Installed as an app, the icon's badge counts them (navigator.setAppBadge).
• It installs as a PWA, one app per store. An @app.get route serves the manifest, which registers a web+symbion: protocol handler, so a URL router can send links from a terminal into the app.
• A file dropped on any page starts an entry about it.
• --read-only serves a public demo: every control answers with a notice.

Things we tripped over

1. #esm-fallback ~ * made every style pass quadratic. The page template hides what follows its ES-module notice with that rule, and the rule stays after the notice is gone, so every element is tested against each of its earlier siblings. A 200 KB source file in our file viewer (27,000 spans in one <code>) took 4.5 s per style pass and 24 s to first paint in headless Chrome. With the rule deleted, a pass took 90 ms and the paint 2.2 s. Reported in #6411 and fixed in #6426 within four days; thank you. Until a release carries the fix, we delete the rule at load:

document.addEventListener('DOMContentLoaded', () => {
  for (const s of document.styleSheets) {
    let rules;
    try { rules = s.cssRules; } catch { continue; }   // another origin's sheet
    for (let i = rules.length - 1; i >= 0; i--)
      if (rules[i].selectorText === '#esm-fallback ~ *') s.deleteRule(i);
  }
});

2. A script blocker reads "Your browser does not support ES modules." That notice shows whenever scripts do not run, including when a blocker turned them off. A <noscript> says what is really missing. The template styles the notice after ui.add_body_html's HTML, so only !important hides it:

ui.add_body_html('<noscript><style>#esm-fallback{display:none!important}</style>'
                 '<p>This app needs JavaScript. Allow scripts for this site, then reload.</p></noscript>')

3. ui.on('a-b', …) registers as aB. NiceGUI camelCases a global event's type. In a browser, Vue maps an emitted a-b to the same handler, so only the user fixture's trigger('a-b') misses it. We name page events in camelCase everywhere.

4. ui.notify before ui.navigate.reload() never shows. It dies with the page. A notice before a refreshable's redraw lives. The user fixture shows both, so only a browser catches it. We put the text in app.storage.tab and show it on the next load.

5. A ui.timer in a shared page shell wants immediate=False. With an immediate first tick that ran run.io_bound, every test's teardown waited for it, and our GUI suite went from 16 s to 115 s.

6. The user fixture without a main.py. By default it runs ./main.py to find the pages. Our pages are registered by a function against a store, so main_file = "" under [tool.pytest.ini_options] turns that off, and each test registers the pages it needs.

7. On macOS, setAppBadge can go quiet. Once Chrome attributes the PWA's notifications to the app, the dock badge needs notification permission, and without it nothing shows and nothing fails.

An open question

A card is about 25 NiceGUI elements, built on the server and mounted by Vue, so a page of a hundred cards is a couple of thousand elements. On the demo's one vCPU that costs seconds to render, and more seconds to mount in the browser. We have not cut elements per card yet. If you have kept a page of a thousand-plus elements fast without paginating, I'd like to hear how.

[falkoschindler]

Thanks for this write-up, @phreakocious! It's rare to get such a careful list of rough edges, each with the workaround already worked out. Funny coincidence, too: we're building a very similar app in-house right now, a NiceGUI dashboard where a person and their coding agents share tickets, drafts and decisions. It's closed source for now, so it's great to see someone else arrive at much the same shape in the open.

Going through your list:

1. #esm-fallback ~ *: fixed in Fix slow style recalculation caused by the ES module fallback rule #6426, as you say, and the next release will carry it. Then you can drop the stylesheet loop.
2. "Your browser does not support ES modules.": Agreed, that's misleading when a blocker turned scripts off. A <noscript> message (or wording that covers both cases) in index.html would fix it.
3. trigger('a-b') misses ui.on('a-b', …): That's a bug in the user simulation. UserInteraction.trigger compares the raw event type with the listener's camelCased one (user_interaction.py), so it should pass the type through helpers.event_type_to_camel_case first, like Element.on does.
4. ui.notify before ui.navigate.reload(): This is expected. The notification goes to the page that is about to be replaced. Carrying it over via app.storage.tab is the right way.
5. Immediate timer and slow teardown: Interesting. If you can narrow it down to a minimal test, we'd like to see whether the teardown waits longer than it has to.
6. main_file = "": This is supported but not documented. The testing docs only list the three ways to set a main file, so a sentence on switching it off belongs there.
7. setAppBadge on macOS: That's on Chrome's side, but it's good to know.

Points 2, 3 and 6 are each a small, self-contained change. Would you like to open pull requests for them? You've already found the problems and the fixes, so they'd make nice first contributions. If you'd rather not, just say so and we'll take care of them.

About your open question: when a page has a thousand or more elements, the cost is in having that many server-side elements at all. Each one is created, serialized and mounted separately. What has worked for us:

• Render static parts as one element. Parts of a card that never change or react can be a single ui.html (or ui.markdown) instead of a dozen nested rows, labels and icons.
• Render the cards in the browser. A custom Vue component that takes the list of cards as one prop and draws them itself replaces about 25 × 100 elements with a single one. It can emit events like resolve or answer with the entry ID. A ui.table in grid mode with a custom item slot is a lighter version of the same idea.
• Defer what's not visible. Build the drawer contents or the details of a card only when they are opened.

※

[phreakocious]

Sure, I'll open the three PRs and get back to you on the teardown, and thanks for the large-page advice. We'll try counting elements per card first, then fold the static parts into one element and defer what is closed.

[phreakocious]

Chucked #6442 on the pile for item number 5.