# waybetter The framework behind the wayBetter apps: the apps you already use in a light native (Tauri) window, extended in place the way BetterDiscord extends Discord. Websites and services that ship a heavy Electron client alike: every wayBetter app is the same shell, runtime and one small adapter. - **`waybetter/runtime/*`**: the page runtime. One DOM-mutation/animation-frame hub, one fetch/XHR hub, a plugin API core with a themed UI kit (toasts, alerts, confirmations, prompts, dialogs), a theme API, an OKLab theme color model, split-pane rail hiding, link routing and account change reporting. - **`waybetter/theme.schema.json`**: the JSON Schema of wayBetter theme files. - **`waybetter/shell/*`**: pure models for the app chrome around the pages: address bar chips, dock/split-pane rules, dragged links, account profiles, the update chip, command palette ranking and window controls. The Tauri window API is passed in by the caller, never imported. Plain ESM with `.d.ts` types. Zero dependencies. ## Install ```sh npm install waybetter ``` ## Usage Every module is its own subpath export, so you only pull in what you use: ```ts import { configureRuntime, type SiteAdapter } from 'waybetter/runtime/site'; import { watchDom } from 'waybetter/runtime/domHub'; import { buildColorModel, deriveColors } from 'waybetter/runtime/themeTokens'; import { parseAddress } from 'waybetter/shell/addressModel'; import { fuzzyScore, rankItems } from 'waybetter/shell/palette'; ``` `runtime/site` is the composition root: an app is mostly one adapter object built from these pieces. The source comments document each module's contract. ## Modules **Runtime** - `accountReport`: reports the signed-in account seen in the page's own UI. - `column`: a site tab as a narrow deck column: hides the site's chrome, lets its content fill the width, per-column filters (keywords, `/regex/`, replies, reposts, media only) and an unread count from what the site rendered. Makes no requests. - `domHub`: one `MutationObserver` and one animation frame shared by every DOM feature. - `linkRouting`: routes clicks on the app's own links per the "links to app pages" setting. - `netHub`: one shared fetch/XHR hook for URL rewrites, gates and passive JSON taps. - `paneNav`: hides a redundant navigation rail when two panes show the same account. - `pluginApi`: small helpers shared by user JS plugins, including `ui` and `theme`. - `site`: the page-side composition root for an adapter. - `themeApi`: the active theme as values (`ResolvedTheme`), `--wb-*` CSS variables, contrast helpers. - `themeTokens`: the OKLab color model themes are built on. - `ui`: the plugin UI kit (see below). **Shell** - `addressModel`: `parseAddress(url, site)` for the address bar's breadcrumb chips. - `chrome`: layout constants for the custom titlebar and toolbar. - `deckModel`: decks of site columns (TweetDeck-style): bounded model, paging layout (whole columns per page, parked off-page columns), focus moves, unread totals. - `linkDrop`: a dragged link dropped into the dock opens as a tab or split pane. - `palette`: command palette fuzzy scoring, ranking and selection movement. - `paneModel`: pane geometry: where a "beside" link opens, which panes keep the rail. - `profileModel`: the account profile model. - `updateModel`: the titlebar update chip model. - `windowControls`: native window calls for the titlebar, resize grips and caption buttons. ## Plugin UI kit (`runtime/ui`) Plugins get it as `api.ui` (and `scope.ui`, which closes whatever it opened on `scope.dispose()`). Everything is drawn in one Shadow DOM host, so the site's CSS cannot restyle it, and it takes its colors, corners and font from the active theme (`api.theme`), live. ```js const ui = this.scope.ui; ui.toast('Link copied'); // tones: neutral, info, success, warning, danger ui.toast('Post hidden', { action: { label: 'Undo', onClick: undo } }); await ui.alert({ title: 'Saved', message: 'Kept on this device only.', tone: 'success' }); if (await ui.confirm({ title: 'Delete this note?', confirmLabel: 'Delete', danger: true })) remove(); const name = await ui.prompt({ title: 'Rename', value: 'Reading', validate: v => v.trim() ? null : 'Required' }); const dialog = ui.dialog({ title: 'Settings', content: body => body.append(ui.h('label', { class: 'wb-check' }, ui.h('input', { type: 'checkbox' }), 'Hide trends')), actions: [{ label: 'Cancel' }, { label: 'Save', tone: 'primary', default: true, onClick: save }], }); ``` - `modal(options)` is the primitive under all of them; `dialog` is a `role="dialog"`, `alert` / `confirm` are `role="alertdialog"`. All are `aria-modal`, labelled by their title and described by their message. - Focus moves in, Tab/Shift+Tab wrap inside, and focus returns to where it was. Esc dismisses; Enter in a single-line field (Ctrl/Cmd+Enter in a textarea) runs the `default` action. A destructive `confirm` starts on Cancel. - Backdrop clicks dismiss alerts and confirmations only (a press that started in a field and ended on the backdrop does not count). Keys typed in a dialog never reach the page's own shortcuts. - Dialogs stack (lower ones become `inert`); toasts stack (four at most), pause while hovered or focused and are a polite live region (`role="alert"` for danger). - `prefers-reduced-motion` turns off the animations. Text is always set as text; `ui.h(tag, props, ...children)` builds content without `innerHTML`, string handlers or `javascript:` URLs. - Classes for content: `wb-field`, `wb-label`, `wb-hint`, `wb-check`, `wb-input`, `wb-mono`, `wb-divider`, `wb-row`, `wb-muted`; per-dialog CSS goes in `css`. `createUiKit(window, { theme })` builds a kit outside the plugin API; `theme` is a `ThemeApi` from `createThemeApi(window, source)`, where `source` is the site's `{ current(), onChange() }`. ## Themes `api.theme.current()` returns the active theme resolved: `colors` (`bg`, `surface`, `elevated`, `border`, `text`, `muted`, `accent`, `onAccent`, `inverse`, `onInverse`, `page`), `radius`, `buttonRadius`, `font`, `mode` and `siteDefault` (true when the site's own colors show). `api.theme.onChange(fn)` fires after it changes. The same values are CSS custom properties on `:root` (`--wb-bg`, `--wb-text`, `--wb-accent`, `--wb-radius`, `--wb-font`, …), so plugin CSS can use `var(--wb-accent)`. Theme files are JSON; `theme.schema.json` describes every field and its limits (the app clamps out-of-range values when it imports a file). Point a theme at it for editor completion and checks: ```json { "$schema": "https://unpkg.com/waybetter/theme.schema.json", "name": "Midnight Mint", "colors": { "bg": "#0b1110", "text": "#e8f3ef", "accent": "#3ddc97" } } ``` or, in a project that installs the package, `"$schema": "./node_modules/waybetter/theme.schema.json"`. ## Build your own ```sh npm create waybetter plugin # *.plugin.js (or --ts) using api.scope, storage, ui and theme npm create waybetter theme # theme JSON with "$schema" pointing at theme.schema.json npm create waybetter app -- --site youtube.com # a new wayBetter app (Tauri 2 + waybetter-host) ``` [`create-waybetter`](https://www.npmjs.com/package/create-waybetter) generates code against this package's real API and schema; `--help` lists every option. ## Projects using wayBetter | Project | Target | What it is | | --- | --- | --- | | [wayBetter for X](https://waybetter.fyi/twttr/) | 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. ## License GPL-3.0-or-later. See [LICENSE](./LICENSE).