waybetter/README.md

11 KiB

waybetter

The framework behind the wayBetter apps: desktop apps that extend one website in place, the way BetterDiscord extends Discord. The first app is wayBetter for X; wayBetter for WhatsApp and wayBetter for Kick are meant to be built on the same core.

A wayBetter app is one native window (Tauri 2, multiwebview) with:

  • a trusted local shell webview: tab strip, split panes (dockview), address bar, titlebar and window controls, command palette, account switcher, the app's own settings;
  • one native child webview per browser tab, positioned over the pane rectangles the shell reports (tabs_sync), each in an account profile with its own WebView data directory;
  • a page runtime injected into tabs that are on the app's site: shared DOM/request hubs, plugins, themes, split-view rail hiding, link routing and account reporting.

This repository holds the parts that do not depend on which site the app extends. An app is mostly a site adapter plus its own features.

Two kinds of targets

wayBetter extends the apps people already use, not only websites:

  • Web target (built): a website such as x.com or kick.com. The app is the Tauri window above; the shell supplies tabs, split panes, profiles, link routing and updates.
  • Desktop target (planned): a desktop app that is itself built on web tech (Electron or a system webview), e.g. WhatsApp or Discord. The app already has its own window and session, so there is no wayBetter shell: a small loader puts the same page runtime (themes on one color foundation, plugins, DOM/request hubs) inside the app's renderer, the way BetterDiscord does for Discord. Updates of the target app must not break it: the loader re-applies itself and degrades to "unchanged app" when it cannot.

The runtime and the adapter contract are shared by both; only the host differs (Tauri shell vs. loader). Keep runtime code free of Tauri assumptions (invoke is injected, never imported) so a desktop target can supply its own bridge.

License: GPL-3.0-or-later. Private until the owner decides otherwise.

Projects using wayBetter

Project Target What it is
wayBetter for X x.com (website) Desktop app around the live X: tabs, split panes, real accounts side by side, themes, plugins, drafts and fixes for X's own bugs. The first wayBetter app.

Built something on wayBetter? Add it to this list with a pull request: name and link, what it extends, one line on what it does.

Layout

crates/waybetter-host/      Rust: security policy, profiles, plugin store, hotfix, updates, tab payloads
  src/site.rs               SiteSpec + AccountRules (the native half of the adapter)
  src/policy.rs             webview labels, origin checks, tab rect clamp
  src/profiles.rs           profiles, per-profile data dirs, native-owned accounts
  src/plugins.rs            *.plugin.js store, custom CSS, bundled-plugin upgrades
  src/hotfix.rs             signed data-only hotfix channel (minisign)
  src/update.rs             silent-update scheduling and crash handshake
  src/tabs.rs               TabLayout/TabState/OpenRequest, link modes, shortcut and drag validation
  src/host.rs               (feature "tauri") webview helpers, shell events, system menu
packages/runtime/src/       page runtime core (TypeScript, no dependencies)
  site.ts                   SiteAdapter (the page half of the adapter) + configureRuntime
  domHub.ts netHub.ts       one MutationObserver/frame, one fetch/XHR hook per page
  pluginApi.ts              core of window.<Runtime>.api for plugins
  themeTokens.ts            OKLab color model: maps the site's palette onto a theme's axis
  paneNav.ts                split view: park the site's navigation rail in redundant panes
  linkRouting.ts            divert in-page clicks to a pane/tab/browser per setting
  accountReport.ts          report the signed-in account of this tab's profile
packages/shell/src/         shell core (TypeScript, no dependencies)
  addressModel.ts           address bar chips (site pages named by the adapter)
  paneModel.ts              beside-pane reuse, redundant rails, navRedundant for tabs_sync
  linkDrop.ts               dropping links into the dock
  profileModel.ts           profiles and account labels
  palette.ts                command palette scoring/ranking
  updateModel.ts            titlebar update chip
  windowControls.ts         caption buttons, resize grips, system menu (Tauri API injected)
  chrome.ts                 titlebar/toolbar/resize-border sizes (match policy.rs)

Both TypeScript packages are plain source (.ts, ESM, type: module) with no runtime dependencies, so an app can bundle them with esbuild/Vite and run their tests with Node's type stripping. Anything that needs the Tauri API (window controls) takes it as a parameter.

The site adapter

A site adapter is three small, explicit things.

1. Native: SiteSpec (Rust)

use waybetter_host::site::{AccountRules, SiteSpec};

fn kick_handle(value: &str) -> bool {
    (3..=25).contains(&value.len()) && value.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_')
}

pub static SITE: SiteSpec = SiteSpec {
    product: "wayBetter for Kick",
    hosts: &["kick.com"],                     // exact https origin(s) of site tabs
    runtime_global: "WayBetterKick",          // window.<global> of the page runtime
    accounts: AccountRules {
        valid_handle: kick_handle,
        avatar_prefixes: &["https://files.kick.com/"],
        max_name_chars: 50,
        max_avatar_len: 512,
    },
};

SiteSpec::is_origin is the only definition of "a site tab". Site-only commands check policy::require_site_tab(&SITE, label, url) (or host::site_tab_only), which also requires a tab-* label.

2. Page: SiteAdapter (TypeScript)

import { configureRuntime, type SiteAdapter } from 'waybetter/packages/runtime/src/site.ts';

export const KICK: SiteAdapter = {
  product: 'wayBetter for Kick',
  hosts: ['kick.com'],
  runtimeGlobal: 'WayBetterKick',
  heavyPath: null,                          // pages where offOnHeavy DOM features pause
  apiMarks: ['/api/'],                      // request URLs the net hub stages may see
  xhrMarks: [],
  plugins: { name: 'WayBetterKick', product: 'wayBetter for Kick', storagePrefix: 'wbk-plugin:',
    styleDataKey: 'wbkPlugin', toastId: 'wbk-toast', toastBackground: '#53fc18',
    itemSelector: '[data-chat-entry]', chordKeys: [] },
  rail: { prefix: 'wbk', rail: '#sidebar-wrapper', anchor: 'a[href="/"]', main: 'main',
    modalOpen: '[role="dialog"]', menuOpen: '[role="menu"]',
    paint: { width: 64, background: '#0b0e0f', line: 'rgba(255,255,255,.12)', accent: '#53fc18', rtl: false } },
  account: { read: readKickAccount, signedOut: root => !!root.querySelector('[data-test="login"]') },
  links: { configKey: 'site', clickedUrl: kickClickedUrl },
  themeSources: { dark: KICK_DARK_AXIS },
};
configureRuntime(KICK);

Each runtime module takes only its piece (installPaneNav(window, KICK.rail!), installLinkRouting(window, KICK.links!), installAccountReport(window, KICK.account!, invoke), createCorePluginApi(window, KICK.plugins)), so a site without a rail simply does not install it.

3. Capabilities (Tauri JSON, keyed by webview label)

The security model is the same for every app and must stay keyed by webview label:

webview may call
shell (local assets only) app, settings, vault, tab management (tabs_sync, tab_navigate, tab_action, ...)
tab-* (any site) only tab chrome about itself: tab_report, tab_shortcut, tab_link_drag
tab-* on the exact site origin the app's short, reviewed list of site-only commands
other local webviews (popover-*, ...) their own narrow capability
{ "identifier": "tab-chrome", "webviews": ["tab-*"], "local": false,
  "remote": { "urls": ["https://*/*", "http://*/*"] },
  "permissions": ["allow-tab-report", "allow-tab-shortcut", "allow-tab-link-drag"] }
{ "identifier": "site-tab", "webviews": ["tab-*"], "local": false,
  "remote": { "urls": ["https://kick.com/*"] },
  "permissions": ["allow-open-panel"] }

Native code re-checks every one of these (the capability file alone is not the boundary): the caller's label, the webview's own URL (never the page's claim), payload bounds. A tab can speak only about itself; the account it reports is recorded only for its own profile, only while it is on the site, and a shell save can never change it (ProfileSettings::keep_accounts_from).

What the host gives an app

  • policy: SHELL_LABEL, tab_id, require_local, require_site_tab, clamp_tab_rect (tabs never cover the titlebar or, while restored, the resize band).
  • profiles: ProfileSettings (validated, default profile required, profiles with open tabs cannot be removed), data_dir (ids cannot escape profiles/), orphan_dirs, store_identifier (macOS).
  • plugins: PluginStore with a PluginHost (runtime global, origin, product, bundled plugins). Bundled plugins are written disabled and upgraded only while untouched.
  • hotfix: minisign-verified, schema-checked, monotonic, expiring data; delivered frozen as data.
  • update: check schedule with jitter, crash handshake (automatic apply off after two failed boots).
  • tabs: shell payloads and validation; deliver_script hands JSON to a runtime member or parks it.
  • host (feature tauri): shell_only, tab_only, site_tab_only, emit_shell, tab_webview, eval_in_site_tabs, navigate_tab, tab_action, forward_shortcut, forward_link_drag, read_json/write_json, remove_profile_dirs, prune_profile_dirs, migrate_identifier, system_menu.

The app keeps its own #[tauri::command] wrappers, so IPC command names, the build-time command manifest and the capability files stay in the app.

Consuming it

wayBetter for X adds this repository as a git submodule at waybetter/ and consumes it from source:

  • Rust: a path dependency, waybetter-host = { path = "../../../waybetter/crates/waybetter-host" }, with features = ["tauri"] enabled by the app's desktop feature.
  • TypeScript: relative imports of waybetter/packages/*/src/*.ts from a few adapter modules. The packages are not Bun workspace members of the app on purpose: the app's server CI clones without submodules and runs bun i, which fails when a declared workspace package is missing; and Node's type stripping refuses .ts files under node_modules, while sources outside it work with Bun's isolated linker on Windows.

Scripts (no CI)

bun install            # typescript + @types/node for the checks
bun run typecheck      # tsc over both packages and their tests
bun run test           # node --test (runtime + shell) and cargo test (headless host)
bun run test:ts
bun run test:rust
bun run check:tauri    # cargo check with the tauri feature (slow: builds Tauri)
bun run build          # typecheck + cargo build

Requires Bun 1.4.2+, Node 24+ and Rust 1.88+.