205 lines
17 KiB
Markdown
205 lines
17 KiB
Markdown
# 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.
|
|
|
|
This package is the TypeScript half and the command line. The native half is the Rust crate
|
|
`waybetter-host`, which is not on npm: an app takes it from the
|
|
[repository](https://git.crt.fyi/CRT/waybetter) as a git submodule or a path dependency. The
|
|
repository README explains how the three layers fit together and shows a minimal adapter;
|
|
`docs/ARCHITECTURE.md` there lists every module.
|
|
|
|
- **`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.
|
|
And the wayBetter Store: the install screen and the Store view as React components (React is an
|
|
optional peer; everything else has no dependencies), their controller and models.
|
|
- **`waybetter/shell/frame`**: the whole shell of an app, `createShell(site, { native, i18n })`:
|
|
tabs in the titlebar, split panes, the smart address bar, the new-tab page, the command palette,
|
|
the account switcher, decks of site columns, workspaces, pane themes, overlays and the native
|
|
layout sync. The app describes its site (pages, address chips, palette items, column kinds, its
|
|
own panel tab); React, React DOM and dockview are optional peers, the Tauri API is passed in.
|
|
- **`waybetter store build|sign|verify`** and **`waybetter/store-catalog.schema.json`**: the tooling
|
|
and JSON Schema of the shared, signed wayBetter Store catalog.
|
|
|
|
Plain ESM with `.d.ts` types. Zero dependencies (the React parts use your React; the shell frame also dockview).
|
|
|
|
## 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.
|
|
- `siteRuntime`: composes a runtime entry: `pageInvoke`, `createFeatureFlags` (flag-controlled parts, a deck column's overrides), `installSiteRuntime` (the runtime object under `window.wayBetter` and the app's names, the members native code calls, queued native deliveries, the palette command report).
|
|
- `pageStrings`: the page's language (English built in; native deliveries are checked as data).
|
|
- `panelButton`: the way into the app's panel from the page: the adapter's navigation entry, or a floating button.
|
|
- `commandReport`: reports plugin palette commands to the shell; developer-mode start errors.
|
|
- `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.
|
|
- `storeModel`, `storeMessages`: Store wire types, item states (install, update, changed locally, built in), permission badges, search; the English of every `wb.store.*`, `wb.install.*`, `wb.permission.*` message (translations in `waybetter/locales/*.json`).
|
|
- `installController`: the install screen's state (install links, dropped files, store items, confirm), given the app's native bridge and theme adapter.
|
|
- `InstallDialog` (`InstallHost`), `StoreView`, `store.css`: the install screen, the window drop target and the Store view, themed with `--wb-*` tokens. See docs/STORE.md in the repository.
|
|
|
|
**Shell frame** (`waybetter/shell/frame`, modules also as `waybetter/shell/frame/*`, styles as `waybetter/shell/frame/*.css`)
|
|
|
|
```tsx
|
|
import { createShell, type ShellSite } from 'waybetter/shell/frame';
|
|
const Shell = createShell(site, { native: { invoke, listen, currentWindow: getCurrentWindow }, i18n });
|
|
createRoot(document.getElementById('root')!).render(<Shell/>);
|
|
```
|
|
|
|
- `ShellSite` (`frame/site`): the site's names and pages, `address(url)` chips, slots for the app's panel tab, the new-tab page, palette items, deck column kinds, the media panel, themes (`createThemeStore`) and overlays, and the native `features` the app serves.
|
|
- `i18n`: the app's `createI18n` instance with `waybetter/locales/*.json` merged in; the frame's words are `wb.*` messages in 51 languages.
|
|
- `bootScript()` (`frame/boot`): the first-frame `boot.js` (the last theme's chrome colors before the modules load).
|
|
- `installPreviewMocks(handlers)`: native commands answered from memory, for development previews in a plain browser.
|
|
- `createLanguage(options)` (`frame/language`): which language the app speaks (follow the site, follow the system, or one language), switched live and handed to native code and site tabs (`i18n_set`); `createAppI18n(options)` (`frame/appI18n`): the app's i18n instance with typed keys, `useT`, dates and numbers.
|
|
- Everything else is exported for apps that build their own settings on it: the shared state (`shell`, `setOverlay`, `scheduleSync`), stores (decks, workspaces, sync, developer mode), models (palette, accounts, workspaces, backup, media) and hooks.
|
|
|
|
**Panel** (`waybetter/shell/panel`, modules also as `waybetter/shell/panel/*`, styles as `waybetter/shell/panel/*.css`)
|
|
|
|
```tsx
|
|
import { createPanel, type PanelSite } from 'waybetter/shell/panel';
|
|
const Panel = createPanel({ brand: { name: 'wayBetter', logo }, home, themes, sections, make, languages });
|
|
const Shell = createShell({ ...site, panel: { id: 'app', title: 'wayBetter', component: Panel } }, options);
|
|
```
|
|
|
|
- The app's own tab: home, Appearance and the Theme Builder (with the Google Fonts browser), plugins and custom CSS, the Store, Make, accounts, Power User, settings, backup and sync, developer mode, updates, and a search across every setting. Each section shows only when the app serves what it needs.
|
|
- `PanelSite` (`panel/site`): the brand and the home page's words, the app's own `sections` and their `order`, `themes` (the theme store and catalog, the preview component a theme document is drawn in, the site font), `make` (example plugins, an example theme, bundled docs), `store`, `languages`, and what its native side serves (`settings.alerts`, `backup`, `updates`).
|
|
- For the app's own sections: the panel's controls (`panel/controls`: `Section`, `Row`, `Toggle`, `Segmented`, `Select`, `Slider`, `ColorField`, `Button`, ...), `useFeatures` and `FeatureGroups` (`panel/FeatureToggles`: on/off rows over the host's `features_get/set`), `compareLines`.
|
|
- The panel's words are `wb.*` messages in 51 languages (`waybetter/locales/*.json`; translator notes in `waybetter/locales/en.meta.json`).
|
|
|
|
**Command line**
|
|
|
|
- `waybetter store build --config store.config.mjs`: builds an app's part of the shared store folder (its items only, validated with the apps' own rules).
|
|
- `waybetter store sign [--init] --key <private key>` / `waybetter store verify --pub <key file>`: Ed25519 signature over the exact catalog bytes; any listed public key verifies (rotation). The private key is never printed or copied.
|
|
- `waybetter strings check <pack> [--inventory <file>] [--verbose]`: validates a string pack (data that replaces the wrapped site's own UI strings: `waybetter/runtime/stringPacks`, `waybetter/runtime/stringPackHook`, `waybetter/runtime/textNet`) against the site's string inventory and prints its coverage; the inventories otherwise come from `waybetter.strings.json` in the app's root.
|
|
- `waybetter i18n check [--write] [--verbose] [locale…]`: checks an app's catalogs (and the framework's in the same languages) with the `waybetter/i18n/check` rules, bundled plugins' inline English and the generated files; `--write` regenerates `languages.json` and the native localization files (macOS, Linux). `waybetter i18n extract [--missing]`: keys the code looks up that English lacks, and English keys without a literal lookup. Both read `waybetter.i18n.json` in the app's root (`locales`, `sources`, `nativeSources`, `bundledPlugins`, `runtimeKeys`, `supported`, `native`; schema: `i18n-config.schema.json`). `supported` lists the languages in the supported tier; every other catalog gets `tier: "community"` in the generated `languages.json` (`languages.schema.json`), and an app resolves its automatic language choices only to supported ones (`createLanguage({ supported })`).
|
|
- `waybetter release windows|macos`: signed native releases and the update manifest (`waybetter.release.json`). The Windows build runs path-free (below) and every artifact must pass the privacy scan before anything is copied or signed.
|
|
- `waybetter build-env -- <command>`: runs a build (`tauri build`, `cargo build`) so the binary holds none of the machine's paths: the home folder, the workspace, `CARGO_HOME`, `RUSTUP_HOME` and `CARGO_TARGET_DIR` become `/home`, `/src`, `/cargo`, `/rustup` and `/target` (`--remap-path-prefix` appended to the flags already in `RUSTFLAGS`/`CARGO_ENCODED_RUSTFLAGS`, `/PDBALTPATH` on MSVC; for C and C++ a build script compiles, `-ffile-prefix-map` on gcc and clang and, on MSVC, `/d1trimfile:<root>` in `CL` and `/PDBALTPATH` in `LINK`, which reach the cc crate, CMake and MSBuild alike). Without a command it prints that environment (`--json`).
|
|
- `waybetter privacy-scan <paths…> [--terms <file>] [--tracked] [--history]`: searches files, binaries (UTF-8 and UTF-16), archives (zip, tar, gzip, zstd, .deb, DMG; NSIS installers, AppImages and xz with 7-Zip or the matching tool), git-tracked files and a repository's whole history for forbidden terms: the lines of a file kept outside every repository (`--terms`, `WAYBETTER_FORBIDDEN_TERMS`, or `"forbiddenTerms"` in `waybetter.release.json`) plus this machine's account name. A name is a hit as a whole word in any case; a name of three characters or fewer only in a path or as the capitalized word. Output shows file and line or offset with the term masked (`m***`); exit 1 on a hit, 2 when a container could not be opened. Reviewed false positives: `"privacyAllowlist"`, lines of `<file glob>: <regex over the context, the term written <term>>`.
|
|
- `windows/languages/<Language>.nsh`: the Windows installer's messages for the languages Tauri does not ship, next to the installer template (`windows/installer.nsi`).
|
|
|
|
## 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 myapp -- --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://git.crt.fyi/CRT/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.
|
|
|
|
## License
|
|
|
|
GPL-3.0-or-later. See [LICENSE](./LICENSE).
|