READMEs for strangers: overview, three layers, a real minimal adapter, security model; the long reference moves to docs/ARCHITECTURE.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
ca46210e53
commit
593ce46bd7
5 changed files with 717 additions and 518 deletions
652
README.md
652
README.md
|
|
@ -1,294 +1,56 @@
|
||||||
# waybetter
|
# waybetter
|
||||||
|
|
||||||
The framework behind the wayBetter apps: apps that extend the apps you already use in place, the
|
A framework for desktop apps that run one website (or a web app you would otherwise use through a
|
||||||
way BetterDiscord extends Discord. The first app is **wayBetter for X**; more are being built on
|
heavy Electron client) in a small native window and extend it in place, the way BetterDiscord
|
||||||
the same core.
|
extends Discord. You get tabs, split panes, several signed-in accounts side by side, themes,
|
||||||
|
plugins, a signed store for them, backups and updates. You write a small adapter that says what
|
||||||
```sh
|
the site is.
|
||||||
npm install waybetter
|
|
||||||
```
|
|
||||||
|
|
||||||
[npm](https://www.npmjs.com/package/waybetter) · [waybetter.fyi](https://waybetter.fyi)
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
## One system for every app
|
|
||||||
|
|
||||||
Every wayBetter app is the same system: the Tauri window above (shell + page runtime) plus one
|
|
||||||
small adapter. That holds for websites like x.com and just as much for services that ship their
|
|
||||||
own Electron desktop client, such as WhatsApp or Discord: wayBetter runs their web app in its own
|
|
||||||
light Tauri window instead of the heavy client, and gives it the same tabs, split panes, real
|
|
||||||
accounts side by side, themes, plugins and signed updates. There is no second kind of host.
|
|
||||||
|
|
||||||
|
The first app built on it is [wayBetter for X](https://git.crt.fyi/CRT/waybetter-for-x).
|
||||||
License: GPL-3.0-or-later.
|
License: GPL-3.0-or-later.
|
||||||
|
|
||||||
## Projects using wayBetter
|
|
||||||
|
|
||||||
| Project | Target | What it is |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| [wayBetter for X](https://waybetter.fyi/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.
|
|
||||||
|
|
||||||
## Build your own
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
npm create waybetter plugin # a *.plugin.js (or --ts: a TypeScript project) on the real plugin API
|
npm install waybetter # page runtime, shell, CLI tools
|
||||||
npm create waybetter theme # a theme JSON with "$schema", a derived palette and font roles
|
npm create waybetter # scaffold a plugin, a theme or a whole app
|
||||||
npm create waybetter app -- --site kick.com # a whole app: Tauri 2 + waybetter-host + runtime + shell
|
|
||||||
```
|
```
|
||||||
|
|
||||||
`create-waybetter` (in `packages/create-waybetter`) asks for what it needs in a terminal, and
|
Links: [source](https://git.crt.fyi/CRT/waybetter) · [npm](https://www.npmjs.com/package/waybetter) · [waybetter.fyi](https://waybetter.fyi)
|
||||||
takes every answer as a flag (`--help`). The app skeleton is this README in code: the native
|
|
||||||
`SiteSpec`, the page `SiteAdapter`, the app on `waybetter_host::app` (its config, site hooks and
|
|
||||||
its own commands), the three capability files and a `tests/security.rs` on `waybetter_host::testkit`,
|
|
||||||
the shell (the framework's shell frame through `createShell`, with the site's pages and a plugins
|
|
||||||
panel), the plugin store, one site-only command, the
|
|
||||||
runtime bundled with `waybetter/build` and a `waybetter.release.json` for `waybetter release`, with presets for
|
|
||||||
youtube.com, kick.com and twitch.tv and every site selector marked as a placeholder. Its tests
|
|
||||||
generate each kind into a temp folder and check it against the real contracts: plugin headers with
|
|
||||||
`plugins::parse_meta`, plugin code against `createCorePluginApi`'s members, themes against
|
|
||||||
`theme.schema.json`, the app's TypeScript with `tsc` against the built package and its Rust with
|
|
||||||
`cargo check`/`cargo test` against this crate.
|
|
||||||
|
|
||||||
## Layout
|
## The three layers
|
||||||
|
|
||||||
```
|
A wayBetter app is one Tauri 2 window with several webviews. The framework has one piece for each
|
||||||
crates/waybetter-host/ Rust: security policy, profiles, plugin store, hotfix, updates, tab payloads,
|
layer and does not need to know which site you wrap.
|
||||||
and the generic native features every app gets (below)
|
|
||||||
tab-bridge.js the tab bridge every tab gets (served by src/bridge.rs)
|
|
||||||
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/plugins/commands.rs palette commands site tabs report, and the script that runs one
|
|
||||||
src/settings.rs the shell's settings (home page, where links open, session restore) and the
|
|
||||||
page's feature flags, as validated data and the scripts that deliver them
|
|
||||||
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,
|
|
||||||
deck ColumnConfig bounds and unread caps
|
|
||||||
src/bridge.rs the tab bridge script (reports; shortcut/link-drag forwarding opt-in)
|
|
||||||
src/backup.rs settings backup envelope, secret scrubbing, plugin/account sections
|
|
||||||
src/sync.rs encrypted folder sync (Argon2id + XChaCha20-Poly1305 snapshots)
|
|
||||||
src/workspaces.rs saved tab/pane/deck layouts, bounded and well-formed
|
|
||||||
src/devmode.rs developer mode: debounced file watcher, reload order, error positions
|
|
||||||
src/alerts.rs keyword alerts: keywords, snippets, rate limits; native notifications
|
|
||||||
src/media.rs gallery folders (path containment), clipboard history, PNG encoding
|
|
||||||
src/media/clipboard.rs (feature "tauri") opt-in clipboard polling, private copies skipped
|
|
||||||
src/gfonts.rs self-hosted Google Fonts: CSS parsing, URL/woff2 checks, cache format
|
|
||||||
src/fonts.rs (feature "net") font downloads and the font cache
|
|
||||||
src/updater.rs (features "tauri" + "net") signed native updates and the hotfix channel
|
|
||||||
src/store/ install links, download allow-list, signed multi-app store catalog, staging
|
|
||||||
and installs; downloads with feature "net" (docs/STORE.md)
|
|
||||||
src/host.rs (feature "tauri") webview helpers, shell events, system menu
|
|
||||||
src/app.rs (feature "app") the whole app around a site: run_app / App, AppConfig,
|
|
||||||
SiteHooks, the window, shell and tab webviews, the generic commands
|
|
||||||
(tabs, profiles, language, plugins and custom CSS, feature flags, settings)
|
|
||||||
src/commands.rs the commands the host serves and who may call them; manifest() for build.rs
|
|
||||||
src/testkit.rs capability/caller-check assertions for an app's tests/security.rs
|
|
||||||
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 (incl. ui and theme)
|
|
||||||
ui.ts plugin UI kit: toasts, alert/confirm/prompt, dialogs (shadow DOM, themed)
|
|
||||||
themeApi.ts the active theme as values + --wb-* CSS variables (api.theme)
|
|
||||||
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
|
|
||||||
column.ts deck columns: hide site chrome, fill the width, filters, unread count
|
|
||||||
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
|
|
||||||
siteRuntime.ts the runtime's composition: the IPC bridge, flag-controlled parts with a deck
|
|
||||||
column's overrides, the runtime object under its window names, native queues
|
|
||||||
pageStrings.ts the page's language: English built in, native deliveries checked as data
|
|
||||||
stringPacks.ts string packs (docs/STRING-PACKS.md): pack and inventory formats, validator,
|
|
||||||
ordered engine, coverage, drift report
|
|
||||||
stringPackHook.ts the per-site catalog hook adapter, its self-check, a webpack chunk array hook
|
|
||||||
textNet.ts DOM safety net for labels no catalog hook reaches
|
|
||||||
panelButton.ts the way into the panel from the page (navigation entry or floating button)
|
|
||||||
commandReport.ts the palette command report and developer-mode start errors
|
|
||||||
packages/shell/src/ shell core (TypeScript) and the shell frame (React)
|
|
||||||
addressModel.ts address bar chips (site pages named by the adapter)
|
|
||||||
paneModel.ts beside-pane reuse, redundant rails, navRedundant for tabs_sync
|
|
||||||
deckModel.ts decks of site columns: bounded storage model, paging layout, focus
|
|
||||||
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)
|
|
||||||
storeModel.ts storeMessages.ts Store wire types, item states, permission words; wb.store/install/permission.*
|
|
||||||
installController.ts the install screen's state machine (links, drops, store items, confirm)
|
|
||||||
InstallDialog.tsx StoreView.tsx store.css the install screen and the Store view (React peer, --wb-* tokens)
|
|
||||||
frame/ the shell frame: createShell(site) (see "The shell frame" below)
|
|
||||||
panel/ the panel: createPanel(site), the app's own tab (see "The panel" below)
|
|
||||||
installerMessages.ts the Windows installer's words (wb.installer.*)
|
|
||||||
packages/waybetter/ the published npm package (runtime + shell as ESM + .d.ts, theme.schema.json,
|
|
||||||
store-catalog.schema.json, the `waybetter store build|sign|verify`,
|
|
||||||
`waybetter release windows|macos`, `waybetter i18n check|extract`,
|
|
||||||
`waybetter privacy-scan` and `waybetter build-env` commands, `waybetter/build`, locales/ (51 catalogs and translator notes),
|
|
||||||
windows/ (the installer template and its language files))
|
|
||||||
dev-tools/ development harnesses for a running or built app (perf probes, close and
|
|
||||||
stress checks); not published (dev-tools/README.md)
|
|
||||||
docs/STORE.md the Store: shared catalog format, signing and keys, tooling, trust model, how to add it
|
|
||||||
packages/create-waybetter/ `npm create waybetter`: plugin, theme and app scaffolds (no dependencies)
|
|
||||||
```
|
|
||||||
|
|
||||||
Both TypeScript packages are plain source (`.ts`, ESM, `type: module`) with no runtime
|
| Layer | Where | What it does |
|
||||||
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, the shell frame) takes it as a
|
| Native host | `crates/waybetter-host` (Rust) | Builds the window, the trusted `shell` webview and one child webview per tab, keeps profiles (each with its own WebView data folder), the plugin store, settings, backups, encrypted sync, updates, fonts, the store install rules, and decides which webview may call which command. |
|
||||||
parameter. The React parts (the Store screens, the shell frame) have React, and the frame dockview,
|
| Page runtime | `packages/runtime` (TypeScript, no dependencies) | Injected into tabs that are on the site's exact origin: one DOM hub and one fetch/XHR hub, the plugin API and its themed UI kit, the theme engine, split-view navigation, link routing, account reporting, deck columns, string packs. |
|
||||||
as optional peers: the app's copies are used.
|
| Shell | `packages/shell` (TypeScript and React) | The local UI around the tabs: `createShell(site)` gives tabs in the titlebar, split panes, address bar, command palette, account switcher, decks and workspaces; `createPanel(site)` gives the app's own settings tab (appearance, theme builder, plugins, store, backup, developer mode). |
|
||||||
|
|
||||||
## The shell frame
|
Both TypeScript packages ship as the npm package `waybetter` (plain ESM with `.d.ts`). The Rust
|
||||||
|
crate is used from source, as a git submodule or a path dependency. Details of every module are in
|
||||||
|
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
||||||
|
|
||||||
`packages/shell/src/frame` (`waybetter/shell/frame`) is the whole shell of a wayBetter app. An app
|
## A minimal adapter
|
||||||
describes its site and gets tabs in the titlebar row, split panes and link drags into the dock, the
|
|
||||||
smart address bar, the new-tab page, the command palette, the account switcher, decks of site
|
|
||||||
columns, workspaces, the developer-mode and sync chips, the gallery/clipboard panel, pane themes,
|
|
||||||
its own panel tab, keyboard shortcuts, overlays that raise the shell above the tab webviews, the
|
|
||||||
one-layout-in-flight `tabs_sync` and session restore:
|
|
||||||
|
|
||||||
```tsx
|
An adapter is three small things. This is what `npm create waybetter app` writes for `kick.com`
|
||||||
import { invoke } from '@tauri-apps/api/core'; // or window.__TAURI__ (withGlobalTauri)
|
(selectors are placeholders you replace after looking at the real site).
|
||||||
import { listen } from '@tauri-apps/api/event';
|
|
||||||
import { getCurrentWindow } from '@tauri-apps/api/window';
|
|
||||||
import { createShell, type ShellSite } from 'waybetter/shell/frame';
|
|
||||||
|
|
||||||
const site: ShellSite = { name: 'Kick', product: 'wayBetter for Kick', homeUrl, loginUrl, logoutUrl,
|
**1. Native: which webviews are site tabs, and what an account looks like** (`src-tauri/src/site.rs`)
|
||||||
isSiteUrl, accounts, searchUrl, address, panel: { id, title, component }, newTab, palette,
|
|
||||||
deck, media, themes, overlays, features, start };
|
|
||||||
const Shell = createShell(site, { native: { invoke, listen, currentWindow: getCurrentWindow }, i18n });
|
|
||||||
createRoot(root).render(<Shell/>);
|
|
||||||
```
|
|
||||||
|
|
||||||
What the site supplies (`frame/site.ts`, every field documented there):
|
|
||||||
|
|
||||||
- names and pages: `name` (in messages as `{site}`), `product`, `logo`, `homeUrl`, `loginUrl`,
|
|
||||||
`logoutUrl`, `isSiteUrl`, the account rules, `searchUrl` for typed text;
|
|
||||||
- the address bar: `address(url)` (chips, usually `parseAddress` with an `AddressSite`) and an
|
|
||||||
optional `addressCompleter` (inline completions, e.g. search operators);
|
|
||||||
- slots: `panel` (the app's own tab and its sections), `newTab` (search label, quick links),
|
|
||||||
`palette` (placeholder, the literal search, completions, the panel's sections, the site's pages),
|
|
||||||
`deck` (column kinds with labels and icons, the page each loads, titles, value parsing and
|
|
||||||
completions, column flags and presets, an optional compose dock), `media` (which pages have a
|
|
||||||
composer), `themes` (a `createThemeStore(adapter)`: the app's theme documents, chrome colors via
|
|
||||||
`chromeVars`, pane themes), `overlays` (the app's own dialogs), `start()` (read site settings,
|
|
||||||
call `siteChanged()` when site text changes);
|
|
||||||
- `features`: the native features the app wires up (workspaces, sync, developer mode, plugin
|
|
||||||
palette commands); an app without them shows nothing of them.
|
|
||||||
|
|
||||||
The frame's words are `wb.*` messages in the framework catalogs (51 languages; English source in
|
|
||||||
`frame/frameMessages.ts`): the app passes its i18n instance with the framework catalogs merged in.
|
|
||||||
Styles come with the components (dockview's, then `shell.css`, `deck.css`, `workspaces.css`,
|
|
||||||
`accountSwitcher.css`, `paneTheme.css`); colors are `--wb-c-*` tokens with Night Ink fallbacks,
|
|
||||||
set by the theme store (the chrome and each pane group) and cached for the first frame:
|
|
||||||
`bootScript()` (`frame/boot.ts`) is the `boot.js` an app serves before its modules (a Vite plugin or
|
|
||||||
a build step writes it). `installPreviewMocks(handlers)` answers native commands from memory, so
|
|
||||||
the real shell renders in a plain browser for development previews and screenshots.
|
|
||||||
|
|
||||||
Native commands the frame calls: the host's (`tabs_sync`, `tab_navigate`, `tab_action`,
|
|
||||||
`shell_focus`, `shell_raise`, `open_external_url`, `window_system_menu`, `profiles_*`), and for the
|
|
||||||
features an app turns on `settings_get`, `column_configure`, `workspaces_*`, `sync_*`, `dev_*`,
|
|
||||||
`plugins_list`, `tab_run_command`, `media_get`/`gallery_*`/`clip_*`/`tab_attach_image`/
|
|
||||||
`tab_insert_text`, `theme_scopes_*` and `gfonts_*`, `app_ready`/`update_status`/`apply_update`. It
|
|
||||||
listens to `tab-state`, `tab-open`, `tab-shortcut`, `link-drag`, `open-panel`, `profiles-changed`,
|
|
||||||
`tab-commands`, `dev-event`, `update-status`, `tab-still` and `clipboard-changed`.
|
|
||||||
|
|
||||||
## The panel
|
|
||||||
|
|
||||||
`packages/shell/src/panel` (`waybetter/shell/panel`) is an app's own tab in the shell: a home page,
|
|
||||||
Appearance (the theme gallery, customization, account and pane themes, downloaded fonts, theme
|
|
||||||
import/export) and the Theme Builder (undo/redo, a palette from three colors, a contrast report, a
|
|
||||||
font per role with the Google Fonts browser), plugins and custom CSS, the Store, Make (example
|
|
||||||
plugins, the plugin UI kit, the theme API, bundled docs), accounts, Power User (deck settings),
|
|
||||||
settings (language, links and session, keyword alerts, the media panel), backup and sync, developer
|
|
||||||
mode, updates, and a search across every setting. It lives in the shell package, next to the frame
|
|
||||||
it renders in: it uses the frame's stores (profiles, decks, themes, sync, developer mode), its
|
|
||||||
native bridge and its language, so `createShell` comes first.
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
import { createPanel, type PanelSite } from 'waybetter/shell/panel';
|
|
||||||
|
|
||||||
const panel: PanelSite = { brand: { name: 'wayBetter', logo }, home, themes, sections, order, make,
|
|
||||||
store, languages, settings, power, backup: true, updates: true };
|
|
||||||
const Panel = createPanel(panel);
|
|
||||||
const Shell = createShell({ ...site, panel: { id: 'app', title: 'wayBetter', component: Panel } }, options);
|
|
||||||
```
|
|
||||||
|
|
||||||
What the app supplies (`panel/site.ts`, every field documented there):
|
|
||||||
|
|
||||||
- `brand` and `home`: the header and the home page's words (kicker, title, lede, chips, actions,
|
|
||||||
highlight cards, the About block), `version()` for its chip;
|
|
||||||
- `sections` and `order`: its own sections (a label, an icon path, a component that gets `notify`
|
|
||||||
and `openSection`; `searchable` ones also show in the settings search), placed among the built-in
|
|
||||||
ones. X adds Tweaks and Drafts;
|
|
||||||
- `themes`: its theme store and catalog (`createThemeStore`, `createThemeCatalog`), accent swatches,
|
|
||||||
the **preview** component (a miniature of the site drawn from a theme document, used by the gallery
|
|
||||||
and the builder), the site font's name, the palette a draft starts from, and for Make's theme view
|
|
||||||
`resolved(choice, mode)` with the site's own display modes;
|
|
||||||
- `make`: example plugins, an example theme file and bundled Markdown docs;
|
|
||||||
- `store`: the install controller (the Store section, and removing a plugin from the list);
|
|
||||||
- `languages`: the language list and state (`createLanguage`, `frame/language.ts`);
|
|
||||||
- `settings`, `power`, `cssExamples`: keyword alerts, extra settings rows, which column flags and
|
|
||||||
which memory measure Power User lists, placeholder CSS with the site's selectors.
|
|
||||||
|
|
||||||
A built-in section shows only when the app serves what it needs: Appearance, the Theme Builder and
|
|
||||||
the Store with `themes` (and `store`), Make with `make`, Power User with `site.deck`, backup with
|
|
||||||
`backup` (its sync half with the frame's `sync` feature), Developer with the frame's `developer`
|
|
||||||
feature, Updates with `updates`. An app with nothing but plugins gets Home, Plugins, Accounts and
|
|
||||||
Settings (this is what `npm create waybetter app` generates).
|
|
||||||
|
|
||||||
Building blocks for the app's own sections: the panel's controls (`Section`, `Row`, `Toggle`,
|
|
||||||
`Segmented`, `Select`, `Slider`, `ColorField`, `Button`, `Badge`, ...; `panel/controls`), the
|
|
||||||
feature toggles (`useFeatures` + `FeatureGroups` over `features_get/set`: the app names its flags
|
|
||||||
and groups, its catalog has `features.<flag>.label` and `.description`), and `compareLines`.
|
|
||||||
|
|
||||||
The panel's words are `wb.*` messages too (English source in `panel/panelMessages.ts`, translator
|
|
||||||
notes in `locales/en.meta.json`). Three families of keys stay the app's, by convention, because
|
|
||||||
they name its own things: `plugin.<file>.name|description` (its bundled plugins),
|
|
||||||
`theme.<id>.description` (its built-in themes) and `features.*` (its tweaks).
|
|
||||||
|
|
||||||
Native commands the panel calls: the host's `plugins_list`, `plugin_set_enabled`,
|
|
||||||
`plugins_open_folder`, `custom_css_get/set`, `features_get/set`, `settings_get/set`,
|
|
||||||
`profiles_*` and `open_external_url`, and for what the app turns on `alerts_get/set`,
|
|
||||||
`media_get/set`/`gallery_add_folder`/`clip_remove`, `backup_*`, `sync_*`, `dev_*`, the theme
|
|
||||||
store's commands and `gfonts_*`, `install_records`/`install_forget`/`plugin_remove`/`store_catalog`,
|
|
||||||
`app_ready`/`update_status`/`apply_update`.
|
|
||||||
|
|
||||||
The Google Fonts list the font browser shows is an offline snapshot
|
|
||||||
(`panel/fonts/googleFontsCatalog.json`; `packages/shell/scripts/google-fonts-catalog.mjs`
|
|
||||||
regenerates it). The app never fetches the list, only the font files the owner picks (natively).
|
|
||||||
|
|
||||||
## The site adapter
|
|
||||||
|
|
||||||
A site adapter is three small, explicit things.
|
|
||||||
|
|
||||||
### 1. Native: `SiteSpec` (Rust)
|
|
||||||
|
|
||||||
```rust
|
```rust
|
||||||
use waybetter_host::site::{AccountRules, SiteSpec};
|
use waybetter_host::site::{AccountRules, SiteSpec};
|
||||||
|
|
||||||
fn kick_handle(value: &str) -> bool {
|
pub fn valid_handle(handle: &str) -> bool {
|
||||||
(3..=25).contains(&value.len()) && value.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_')
|
(3..=25).contains(&handle.len()) && handle.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_')
|
||||||
}
|
}
|
||||||
|
|
||||||
pub static SITE: SiteSpec = SiteSpec {
|
pub static SITE: SiteSpec = SiteSpec {
|
||||||
product: "wayBetter for Kick",
|
product: "wayBetter for Kick",
|
||||||
hosts: &["kick.com"], // exact https origin(s) of site tabs
|
hosts: &["kick.com"], // exact https origin(s): the only definition of a site tab
|
||||||
runtime_global: "WayBetterKick", // window.<global> of the page runtime
|
runtime_global: "WayBetterForKick", // window.<global> of the page runtime
|
||||||
accounts: AccountRules {
|
accounts: AccountRules {
|
||||||
valid_handle: kick_handle,
|
valid_handle,
|
||||||
avatar_prefixes: &["https://files.kick.com/"],
|
avatar_prefixes: &["https://files.kick.com/"],
|
||||||
max_name_chars: 50,
|
max_name_chars: 50,
|
||||||
max_avatar_len: 512,
|
max_avatar_len: 512,
|
||||||
|
|
@ -296,269 +58,137 @@ pub static SITE: SiteSpec = SiteSpec {
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
`SiteSpec::is_origin` is the only definition of "a site tab". Site-only commands check
|
**2. Page: what the runtime needs to know about the markup** (`src/site.ts`, shortened)
|
||||||
`policy::require_site_tab(&SITE, label, url)` (or `host::site_tab_only`), which also requires a
|
|
||||||
`tab-*` label.
|
|
||||||
|
|
||||||
### 2. Page: `SiteAdapter` (TypeScript)
|
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import { configureRuntime, type SiteAdapter } from 'waybetter/packages/runtime/src/site.ts';
|
import type { SiteAdapter } from 'waybetter/runtime/site';
|
||||||
|
|
||||||
export const KICK: SiteAdapter = {
|
export const SITE: SiteAdapter = {
|
||||||
product: 'wayBetter for Kick',
|
product: 'wayBetter for Kick',
|
||||||
hosts: ['kick.com'],
|
hosts: ['kick.com'],
|
||||||
runtimeGlobal: 'WayBetterKick',
|
runtimeGlobal: 'WayBetterForKick',
|
||||||
heavyPath: null, // pages where offOnHeavy DOM features pause
|
heavyPath: null,
|
||||||
apiMarks: ['/api/'], // request URLs the net hub stages may see
|
apiMarks: ['/api/'], // request URLs the net hub may inspect
|
||||||
xhrMarks: [],
|
xhrMarks: [],
|
||||||
plugins: { name: 'WayBetterKick', product: 'wayBetter for Kick', storagePrefix: 'wbk-plugin:',
|
plugins: { name: 'WayBetterForKick', product: 'wayBetter for Kick', storagePrefix: 'wb-kick-plugin:',
|
||||||
styleDataKey: 'wbkPlugin', toastId: 'wbk-toast', toastBackground: '#53fc18',
|
styleDataKey: 'wbKickPlugin', toastId: 'wb-kick-ui', toastBackground: '#53fc18',
|
||||||
itemSelector: '[data-chat-entry]', chordKeys: [] },
|
itemSelector: '[data-chat-entry]', chordKeys: [] },
|
||||||
rail: { prefix: 'wbk', rail: '#sidebar-wrapper', anchor: 'a[href="/"]', main: 'main',
|
account: { read: readAccount, signedOut: root => !!root.querySelector('button[data-testid="login"]') },
|
||||||
modalOpen: '[role="dialog"]', menuOpen: '[role="menu"]',
|
links: { configKey: 'site', clickedUrl },
|
||||||
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!)`,
|
**3. Capabilities: who may call what** (`src-tauri/capabilities/*.json`, keyed by webview label).
|
||||||
`installLinkRouting(window, KICK.links!)`, `installAccountReport(window, KICK.account!, invoke)`,
|
The scaffold writes `shell`, `tab-chrome` and `site-tab`; the last one is granted only on the
|
||||||
`createCorePluginApi(window, KICK.plugins)`), so a site without a rail simply does not install it.
|
site's own URLs:
|
||||||
|
|
||||||
What every runtime entry does the same way is composed by `runtime/siteRuntime`:
|
|
||||||
`pageInvoke(window, product)` (the IPC bridge, read at call time), `createFeatureFlags({ defaults,
|
|
||||||
installers, apply })` (parts that install on enable and dispose on disable; a deck column's flag
|
|
||||||
overrides sit on top of the owner's) and `installSiteRuntime({ win, site, version, plugins, strings,
|
|
||||||
features, theme, fonts, pane, links, column, extra, queues })`, which builds the runtime object
|
|
||||||
(`features.apply`, `i18n.set`, `links.configure`, `pane.set`, `fonts.provide`, `column.set`,
|
|
||||||
`open()`, `api`, `withPlugin`, `devError`), publishes it as `window.wayBetter` and the app's own
|
|
||||||
names, takes over what native code queued before it existed and starts the palette command report.
|
|
||||||
`createPageStrings` (`runtime/pageStrings`) is the page's language and `installPanelButton`
|
|
||||||
(`runtime/panelButton`) keeps the way into the panel on the page: the adapter's `mountNav` puts
|
|
||||||
an entry into the site's own navigation, and where the page has none a floating button stands in.
|
|
||||||
|
|
||||||
### 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) | the app's own commands and the host's `commands::SHELL` (`tabs_sync`, `tab_navigate`, `tab_action`, `shell_raise`, `profiles_*`, `i18n_*`, `plugins_*`, `custom_css_*`, `features_*`, `settings_*`, ...) |
|
|
||||||
| `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, and the host's `commands::SITE` (`open_panel`) |
|
|
||||||
| other local webviews (`popover-*`, ...) | their own narrow capability |
|
|
||||||
|
|
||||||
```json
|
|
||||||
{ "identifier": "tab-chrome", "webviews": ["tab-*"], "local": false,
|
|
||||||
"remote": { "urls": ["https://*/*", "http://*/*"] },
|
|
||||||
"permissions": ["allow-tab-report", "allow-tab-shortcut", "allow-tab-link-drag"] }
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{ "identifier": "site-tab", "webviews": ["tab-*"], "local": false,
|
{ "identifier": "site-tab", "webviews": ["tab-*"], "local": false,
|
||||||
"remote": { "urls": ["https://kick.com/*"] },
|
"remote": { "urls": ["https://kick.com/*"] },
|
||||||
"permissions": ["allow-open-panel"] }
|
"permissions": ["allow-site-ready", "allow-open-panel"] }
|
||||||
```
|
```
|
||||||
|
|
||||||
Native code re-checks every one of these (the capability file alone is not the boundary): the
|
The app itself is `waybetter_host::app` configured with an `AppConfig` and a `SiteHooks`
|
||||||
caller's label, the webview's own URL (never the page's claim), payload bounds. A tab can speak only
|
implementation (what only your site knows: page scripts, legacy domains, link routing). Anything
|
||||||
about itself; the account it reports is recorded only for its own profile, only while it is on the
|
else the app needs is an ordinary `#[tauri::command]` in your crate.
|
||||||
site, and a shell save can never change it (`ProfileSettings::keep_accounts_from`).
|
|
||||||
|
|
||||||
`waybetter_host::testkit` checks this in an app's own tests: `Capabilities::from_dir` reads every
|
## Start a project
|
||||||
capability file, `assert_host_commands` keeps the host's commands shell-only / tab-only,
|
|
||||||
`assert_shell_only` / `assert_tab_only` do the same for the app's, `assert_site_only(command, &SITE)`
|
|
||||||
checks that a site command is granted only on the site's own URLs, `assert_no_plugin_apis` refuses
|
|
||||||
Tauri plugin JS APIs, and `assert_guarded` / `assert_host_guards` check that each command's first
|
|
||||||
statement checks its caller.
|
|
||||||
|
|
||||||
## What the host gives an app
|
|
||||||
|
|
||||||
- `app` (feature `app`): the whole app. `App::new(AppConfig, hooks).setup(..).run(context,
|
|
||||||
handler)` (or `run_app`) registers single-instance, deep-link (opt-in), window-state, opener,
|
|
||||||
updater (opt-in), process, notification and dialog; makes the app-data folder (0700 on Unix),
|
|
||||||
loads the profiles and the language, runs the app's setup, then builds the window (frameless
|
|
||||||
with the shell's titlebar, or the OS frame), restores its geometry (lost geometry reset),
|
|
||||||
routes helper-window closes (Windows), follows window resizes natively and adds the shell
|
|
||||||
webview (transparent: it can rise above the tabs; macOS needs the `macos-private-api` feature).
|
|
||||||
It serves `commands::SHELL` (`tabs_sync`, `tab_navigate`, `tab_action`, `open_external_url`,
|
|
||||||
`shell_focus`, `shell_ready`, `tab_still_ready`, `shell_raise`, `window_system_menu`, `profiles_get`/`profiles_set`,
|
|
||||||
`i18n_get`/`i18n_set`, `plugins_list`, `plugin_set_enabled`, `plugins_open_folder`,
|
|
||||||
`custom_css_get`/`custom_css_set`, `features_get`/`features_set`, `settings_get`/`settings_set`),
|
|
||||||
`commands::TAB` (`tab_shortcut`, `tab_link_drag`) and `commands::SITE` (`open_panel`), each
|
|
||||||
checking its caller first, and dispatches every other command to the app's handler. It keeps
|
|
||||||
the page state those commands read and save (`PageState`: the plugin store in app data
|
|
||||||
`plugins`, made from the `PluginHost` in `AppConfig::new(site, title, plugins)`; the feature flags
|
|
||||||
in `features.json`; `ShellSettings` in `settings.json`): the app reads it with `page(app)`, gets a
|
|
||||||
loaded document's scripts from `page_scripts(app)` (flags, links, custom CSS, plugins) and writes
|
|
||||||
it with `set_features`, `set_settings` and `set_custom_css` (a backup import). Tab webviews get their
|
|
||||||
profile's data folder, the app's document-start scripts, navigation/pop-up/load/title/download
|
|
||||||
handling, stills and memory targets; `SiteHooks` is where the app says what only it knows (page
|
|
||||||
scripts, legacy domains, link routing, per-tab state, what a finished site page gets). Helpers:
|
|
||||||
`profiles`, `tab_profile`, `account_seen`, `tr`/`trf`, `i18n_page_script`, `notify`,
|
|
||||||
`open_external`.
|
|
||||||
To show the first window only after restored panes are placed, opt in on both sides:
|
|
||||||
`AppConfig::defer_window_show = true` and `ShellSite.deferWindowShow = true`, and grant the
|
|
||||||
shell `allow-shell-ready`. The default still shows the window immediately. An opted-in app
|
|
||||||
shows it after initial `tabs_sync`, with a three-second fallback if shell startup fails.
|
|
||||||
- `commands`: the host's command lists (`SHELL`, `TAB`, `SITE`) and `manifest(&[..])` for the app's `build.rs`.
|
|
||||||
- `settings`: `ShellSettings` (home page, where links to other sites and to the site's own pages
|
|
||||||
open, session restore; missing fields take the defaults), `links_script`, and the feature flags'
|
|
||||||
validation (a small map of booleans) and `features_script`.
|
|
||||||
- `testkit`: see the capabilities section.
|
|
||||||
- `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.
|
|
||||||
- `bridge`: the tab bridge (`SOURCE`, or `script(BridgeOptions)` to leave shortcut and link-drag
|
|
||||||
forwarding off when the shell does not handle them).
|
|
||||||
- `backup` + `sync`: the `.waybetter` settings backup (the app registers its sections and files;
|
|
||||||
secret-looking keys are scrubbed both ways) and encrypted snapshots in a folder the owner syncs.
|
|
||||||
- `workspaces`: validation of saved layouts (slug ids, known tab kinds, http(s) URLs, size caps).
|
|
||||||
- `devmode`: the live-reload watcher (plugins, `custom.css`, one theme file; the app turns the theme
|
|
||||||
document into its own state through a callback).
|
|
||||||
- `alerts`: keyword settings, snippets, `Throttle`, `AlertGate` over any `KeywordMatch`;
|
|
||||||
`alerts::notify` (feature `tauri`) shows a native notification.
|
|
||||||
- `media`: gallery folders and the opt-in clipboard history; `media::clipboard::watch` (feature
|
|
||||||
`tauri`) polls the OS clipboard and never reads a copy a password manager marked private.
|
|
||||||
- `gfonts` + `fonts` (feature `net`): Google Fonts downloaded natively from the two Google hosts
|
|
||||||
only, cached with a sha256 manifest and handed to site pages as bytes (`page_script(&SITE, ..)`).
|
|
||||||
- `updater` (features `tauri` + `net`): the update loop, the signed hotfix channel and
|
|
||||||
`status`/`apply`/`ready` for the app's commands, configured by an `UpdaterConfig`.
|
|
||||||
- `plugins::commands`: palette commands a site tab reports, and `run_script(&SITE, id)`.
|
|
||||||
- `store`: the wayBetter Store for any app from a `StoreConfig` (app id, link scheme, store URL,
|
|
||||||
public keys with rotation, download hosts): `waybetter://install` link parsing, the allow-list,
|
|
||||||
size caps, catalog verification (Ed25519, strict schema, each app sees only its items), `Store`
|
|
||||||
(pending links, staged installs, commit of exactly the staged bytes, records, offline catalog),
|
|
||||||
and with feature `net` no-redirect/no-cookie downloads. The shell half is `waybetter/shell`'s
|
|
||||||
`InstallHost`, `StoreView` and install controller; the tooling is `waybetter store`
|
|
||||||
(docs/STORE.md).
|
|
||||||
- `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 for everything else, and its capability files;
|
|
||||||
its `build.rs` lists its commands through `commands::manifest`, which adds the host's.
|
|
||||||
|
|
||||||
The npm package adds the app-side tooling:
|
|
||||||
|
|
||||||
- `waybetter/build`: `buildRuntime({ entry, outfile, catalog, prefixes, ... })` bundles a page
|
|
||||||
runtime into one IIFE with the app's esbuild (`?inline` CSS as text, other CSS dropped, only the
|
|
||||||
runtime's own catalog prefixes compiled in).
|
|
||||||
- `waybetter release windows|macos`: signed native releases and the update manifest from the
|
|
||||||
app's `waybetter.release.json` (product and file names, key folder, CDN and API URLs, an optional
|
|
||||||
manifest validator). Windows: the signed NSIS build, the installer and `.sig` in
|
|
||||||
`<outDir>/upload`, `latest.json` (other platforms of the version kept); macOS: signs a universal
|
|
||||||
build's updater bundle and adds both darwin platforms. It never uploads: it prints the steps.
|
|
||||||
The key is read only into the build's environment or handed to the Tauri signer by path.
|
|
||||||
- `waybetter build-env -- <command>` and `waybetter privacy-scan`: nothing an app publishes may
|
|
||||||
name the person who built it. A Rust binary embeds the absolute paths of its sources (the Cargo
|
|
||||||
registry, the rustup toolchain, the workspace: about 1,400 strings holding the account name in
|
|
||||||
one app), so `build-env` runs a build with those roots remapped to `/home`, `/src`, `/cargo`,
|
|
||||||
`/rustup` and `/target` (`--remap-path-prefix` appended to the flags already set,
|
|
||||||
`/PDBALTPATH:%_PDB%` on MSVC, `-ffile-prefix-map` for C sources on gcc and clang). MSVC has no
|
|
||||||
prefix map, so there the C and C++ a build script compiles (a CMake library, the cc crate) lose
|
|
||||||
the same roots through `/d1trimfile:<root>` in the `CL` variable, and any PDB they link through
|
|
||||||
`/PDBALTPATH` in `LINK`; cl.exe and link.exe read both themselves, whatever runs them:
|
|
||||||
`waybetter build-env -- tauri build`, on every platform. `privacy-scan` is the proof: it searches
|
|
||||||
files, binaries (UTF-8, UTF-16), archives (npm tarballs, zip, tar, .deb, DMG; NSIS installers and
|
|
||||||
AppImages through 7-Zip), git-tracked files and, with `--history`, every blob, path, commit
|
|
||||||
message and identity of a repository for the terms in a file kept outside every repository
|
|
||||||
(`"forbiddenTerms"` in `waybetter.release.json`, or `WAYBETTER_FORBIDDEN_TERMS`) plus the
|
|
||||||
machine's account name, and prints hits masked (`m***`). `waybetter release` builds with
|
|
||||||
`build-env` and refuses to release an artifact with a hit or one it could not open. The `.pdb`
|
|
||||||
next to a Windows binary still holds every path: never publish it.
|
|
||||||
- `waybetter strings check <pack>`: a string pack (data that replaces the wrapped site's own UI
|
|
||||||
strings) against the site's string inventory: only inventory keys, parameter names, plural and
|
|
||||||
select kinds, no markup; prints the coverage. See docs/STRING-PACKS.md.
|
|
||||||
- `waybetter i18n check|extract`: an app's locale catalogs against the framework's rules (file
|
|
||||||
shape, keys English lacks, ICU syntax, placeholder parity, plural forms, no markup), the
|
|
||||||
framework's catalogs in the same languages, the generated `languages.json` and native
|
|
||||||
localization files (macOS `Info.plist` and `InfoPlist.strings`, the Linux `.desktop` template),
|
|
||||||
bundled plugins' inline English, and the keys the code looks up; configured by the app's
|
|
||||||
`waybetter.i18n.json`.
|
|
||||||
- `waybetter/windows/languages/<Language>.nsh`: the installer's messages for the 17 languages
|
|
||||||
Tauri does not ship itself, generated from the framework catalogs (`wb.installer.*`;
|
|
||||||
`node packages/waybetter/scripts/installer-languages.mjs --write`). An app lists them under
|
|
||||||
`bundle.windows.nsis.customLanguageFiles`.
|
|
||||||
- `waybetter/windows/installer.nsi`: the Windows installer, a template for Tauri's NSIS bundler
|
|
||||||
(`bundle.windows.nsis.template`). No wizard and no UAC: it installs for the current user, makes
|
|
||||||
the Desktop and Start menu shortcuts and opens the app. Run again by hand, it only installs when
|
|
||||||
it is newer than what is installed (an upgrade in place, app data untouched); otherwise it opens
|
|
||||||
the installed app and exits 0, so an old setup left in Downloads never replaces or downgrades an
|
|
||||||
install the updater has moved on. `/FORCE` reinstalls the same version (repair), `/NORUN` does
|
|
||||||
not open the app, `/UPDATE` is the updater's path and always installs. An app renamed after its
|
|
||||||
first release keeps its registry keys by defining `WAYBETTER_LEGACY_NAME` in its installer hooks
|
|
||||||
(`bundle.windows.nsis.installerHooks`).
|
|
||||||
|
|
||||||
## 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 = ["app", "net", "macos-private-api"]` enabled by the app's desktop feature (and
|
|
||||||
as a build-dependency for `commands::manifest`).
|
|
||||||
- TypeScript: relative imports of `waybetter/packages/*/src/*.ts`: the X site for the shell frame
|
|
||||||
(`src/shell/site.tsx`), the page runtime's adapter and a few X modules. Its Vite config dedupes
|
|
||||||
React, dockview and the Tauri API (the frame's imports use the app's copies) and serves
|
|
||||||
`bootScript()` as `/boot.js`. 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.
|
|
||||||
|
|
||||||
## Dev loop
|
|
||||||
|
|
||||||
`waybetter dev [--stable] --watch "<build watcher>"...` starts the app's watchers, waits for their
|
|
||||||
first build and runs `tauri dev` (`--stable` adds `--no-watch`: a Rust file saved by someone else
|
|
||||||
does not restart the app; restart it yourself after Rust changes). Debug builds only:
|
|
||||||
|
|
||||||
- The app names its page scripts with `waybetter_host::page_script!(include_str!("../x.js"), "x.js")`
|
|
||||||
in `SiteHooks::init_scripts`. A debug build reads the file from disk (path relative to the app
|
|
||||||
crate, falling back to the embedded copy) each time a tab's init scripts are built and watches it
|
|
||||||
(`devloop`, using `devmode`'s debounced signature watcher). When it changes, every tab webview is
|
|
||||||
rebuilt on its current URL through `tabs_sync`, because a webview's document-start scripts are
|
|
||||||
fixed at creation. Route is kept, scroll is not. About 1 s from save to visible.
|
|
||||||
- `buildRuntime({ watch: watchRequested(), ... })` (`waybetter/build`) keeps esbuild rebuilding the
|
|
||||||
file; a failed build leaves the last good one.
|
|
||||||
- The shell reloads through the frontend dev server (`beforeDevCommand`), instantly.
|
|
||||||
- Restart needed: Rust, `tauri.conf.json`, capabilities, bundled plugin sources (`include_str!` in the
|
|
||||||
plugin table; installed plugin files reload with developer mode as before).
|
|
||||||
- Release builds contain none of it: `devloop` is `cfg(debug_assertions)`, the macro's release arm is
|
|
||||||
`$embedded.to_owned()` and the path literal is never expanded. `release_guard` (lib.rs) checks that
|
|
||||||
every mention is gated; `cargo test --release` also runs `release_page_script_is_the_embedded_copy`.
|
|
||||||
- `.taurignore` the watched output files (`observer.js`, `x-runtime.js`), or plain `tauri dev` restarts
|
|
||||||
on every rebuild. `create-waybetter` apps get `npm run dev` and `npm run dev:stable`.
|
|
||||||
|
|
||||||
## Scripts (no CI)
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
bun install # typescript + @types/node for the checks
|
npm create waybetter plugin -- --name "Hide Trends"
|
||||||
bun run typecheck # tsc over both packages and their tests, and create-waybetter (checkJs)
|
npm create waybetter theme -- --name "Midnight Mint" --accent "#3ddc97"
|
||||||
bun run test # node --test (runtime + shell), cargo test (headless host), create-waybetter
|
npm create waybetter app kickapp -- --site kick.com --name "wayBetter for Kick" --yes
|
||||||
bun run test:ts
|
|
||||||
bun run test:rust
|
|
||||||
bun run test:create # scaffolds into temp dirs; its cargo check of an app is ~1 min cold
|
|
||||||
# (WAYBETTER_SKIP_CARGO_CHECK=1 skips it; needs the local crate cache)
|
|
||||||
bun run check # typecheck + build:packages + test
|
|
||||||
bun run check:tauri # cargo check with the app feature (slow: builds Tauri and its plugins)
|
|
||||||
bun run build # typecheck + cargo build
|
|
||||||
bun run pack:check # npm pack --dry-run of waybetter and create-waybetter
|
|
||||||
node packages/waybetter/scripts/installer-languages.mjs [--write] # windows/languages/*.nsh from the catalogs
|
|
||||||
node packages/shell/scripts/google-fonts-catalog.mjs # the font browser's offline list
|
|
||||||
```
|
```
|
||||||
|
|
||||||
`dev-tools/` has the harnesses for a running or built app (perf probes, the graceful-close check,
|
The app scaffold adds the framework as a git submodule at `waybetter/` by default (`--host-source
|
||||||
tab and webview stress); see its README.
|
path` and `--host-source git` are the alternatives). Its next steps, as the tool prints them:
|
||||||
|
`git init && git submodule add https://git.crt.fyi/CRT/waybetter.git waybetter`, then
|
||||||
|
`npm install`, `npm run build`, `npm run tauri dev`, then replace the placeholder selectors in
|
||||||
|
`src/site.ts` and `src-tauri/src/site.rs`. Flags: `npm create waybetter -- --help`.
|
||||||
|
See [packages/create-waybetter](packages/create-waybetter/README.md).
|
||||||
|
|
||||||
Requires Bun 1.4.2+, Node 24+ and Rust 1.88+.
|
## The dev loop
|
||||||
|
|
||||||
|
In a scaffolded app, `npm run dev` runs `waybetter dev --watch "node scripts/build.mjs --watch"`:
|
||||||
|
it starts your watchers, waits for their first build and runs `tauri dev`. In debug builds the page
|
||||||
|
runtime file is read from disk and watched; when it changes, every tab webview is rebuilt on its
|
||||||
|
current URL (about a second from save to visible, the route is kept, the scroll position is not).
|
||||||
|
The shell reloads through the frontend dev server. Rust, `tauri.conf.json`, capabilities and
|
||||||
|
bundled plugin sources need a restart. `npm run dev:stable` adds `--no-watch` so a Rust file saved
|
||||||
|
elsewhere does not restart the app. Release builds contain none of this. There is also a developer
|
||||||
|
mode in the panel (Settings, Developer) that reloads installed plugins, custom CSS and one theme
|
||||||
|
file in every tab as you save.
|
||||||
|
|
||||||
|
## Security model
|
||||||
|
|
||||||
|
The site's page is not trusted, and neither is a plugin. The rules:
|
||||||
|
|
||||||
|
- Capabilities are keyed by webview label and each command re-checks its caller in Rust: the
|
||||||
|
capability file is not the boundary. A `tab-*` webview may only report about itself
|
||||||
|
(`tab_report`, `tab_shortcut`, `tab_link_drag`); on the site's exact origin it also gets the
|
||||||
|
app's short, reviewed list of site commands and `open_panel`. Everything else (tab layout,
|
||||||
|
settings, plugins, backup, install) is callable from the local `shell` webview only.
|
||||||
|
- `SiteSpec::is_origin` is the single definition of "a site tab": exact https origin, no
|
||||||
|
credentials in the URL.
|
||||||
|
- The account a tab reports is recorded only for that tab's own profile, only while it is on the
|
||||||
|
site, validated by your `AccountRules`, and a settings save can never change it.
|
||||||
|
- Installs (themes, plugins) come from a dropped file, a `waybetter://install` link or the signed
|
||||||
|
store, and are written only after the owner confirms in the shell. The store catalog is verified
|
||||||
|
with Ed25519; downloads use an allow-list, no redirects, no cookies and size caps. Plugins may
|
||||||
|
declare `@permissions`; the runtime gives each an API view that throws on undeclared members.
|
||||||
|
That is a guard rail, not a sandbox. A plugin without the line is labelled legacy and gets the
|
||||||
|
full API.
|
||||||
|
- Backups and sync snapshots never contain cookies, WebView profile folders, tokens or signing
|
||||||
|
keys. Sync is encrypted with the owner's passphrase (Argon2id and XChaCha20-Poly1305).
|
||||||
|
- `waybetter_host::testkit` lets your `tests/security.rs` read every capability file and assert
|
||||||
|
that host commands stay shell-only or tab-only, that site commands are granted only on the
|
||||||
|
site's URLs, and that each command's first statement checks its caller. The scaffold includes
|
||||||
|
such a test.
|
||||||
|
- `waybetter privacy-scan` and `waybetter build-env` keep a build free of the builder's paths and
|
||||||
|
names; `waybetter release` refuses to release an artifact with a hit.
|
||||||
|
|
||||||
|
## What is in the host and what is still yours
|
||||||
|
|
||||||
|
The host owns the logic for settings backup, encrypted folder sync, saved workspaces, the
|
||||||
|
developer-mode watcher, keyword alerts, the gallery and clipboard history, Google Fonts download
|
||||||
|
and cache, the store install rules and the update loop. In today's apps some of the Tauri command
|
||||||
|
wrappers around those modules are still written by the app (wayBetter for X has them). If you
|
||||||
|
build an app on the scaffold, expect to add the wrapper commands for the features you turn on.
|
||||||
|
Moving those wrappers into the host is planned.
|
||||||
|
|
||||||
|
## Repository layout
|
||||||
|
|
||||||
|
```
|
||||||
|
crates/waybetter-host/ Rust host crate (features: tauri, net, app)
|
||||||
|
packages/runtime/ page runtime (published inside `waybetter`)
|
||||||
|
packages/shell/ shell models, shell frame, panel, store screens (published inside `waybetter`)
|
||||||
|
packages/waybetter/ the npm package: built runtime and shell, JSON Schemas, locales,
|
||||||
|
and the `waybetter` command (store, release, i18n, strings, privacy-scan,
|
||||||
|
build-env, dev)
|
||||||
|
packages/create-waybetter/ `npm create waybetter`
|
||||||
|
docs/ ARCHITECTURE.md, STORE.md, STRING-PACKS.md
|
||||||
|
dev-tools/ harnesses for a running or built app (not published)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
```sh
|
||||||
|
bun install
|
||||||
|
bun run typecheck # tsc over both packages, their tests and create-waybetter
|
||||||
|
bun run test:ts # node --test: runtime and shell
|
||||||
|
bun run test:rust # cargo test of the host crate (headless, feature net)
|
||||||
|
bun run test:create # scaffolds each kind into temp folders and checks them against the real contracts
|
||||||
|
```
|
||||||
|
|
||||||
|
`test:create` also runs `cargo check` on a generated app (about a minute cold);
|
||||||
|
`WAYBETTER_SKIP_CARGO_CHECK=1` skips that step. Requires Bun 1.4.2+, Node 24+ and Rust 1.88+.
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Issues and pull requests go to [git.crt.fyi/CRT/waybetter](https://git.crt.fyi/CRT/waybetter).
|
||||||
|
Keep the split: generic mechanisms belong here, site-specific ones in the app. If you built
|
||||||
|
something on wayBetter, add it to the list below with a pull request.
|
||||||
|
|
||||||
|
| Project | Target | What it is |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| [wayBetter for X](https://git.crt.fyi/CRT/waybetter-for-x) | x.com | Tabs, split panes, real accounts side by side, themes, plugins, drafts and fixes for X's own bugs. |
|
||||||
|
|
|
||||||
557
docs/ARCHITECTURE.md
Normal file
557
docs/ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,557 @@
|
||||||
|
# Architecture reference
|
||||||
|
|
||||||
|
Every module of the host, the runtime and the shell, and what an app supplies. The overview is in
|
||||||
|
the [README](../README.md); this is the long form.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## One system for every app
|
||||||
|
|
||||||
|
Every wayBetter app is the same system: the Tauri window above (shell + page runtime) plus one
|
||||||
|
small adapter. That holds for websites like x.com and just as much for services that ship their
|
||||||
|
own Electron desktop client, such as WhatsApp or Discord: wayBetter runs their web app in its own
|
||||||
|
light Tauri window instead of the heavy client, and gives it the same tabs, split panes, real
|
||||||
|
accounts side by side, themes, plugins and signed updates. There is no second kind of host.
|
||||||
|
|
||||||
|
License: GPL-3.0-or-later.
|
||||||
|
|
||||||
|
## Projects using wayBetter
|
||||||
|
|
||||||
|
| Project | Target | What it is |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| [wayBetter for X](https://waybetter.fyi/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.
|
||||||
|
|
||||||
|
## Build your own
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm create waybetter plugin # a *.plugin.js (or --ts: a TypeScript project) on the real plugin API
|
||||||
|
npm create waybetter theme # a theme JSON with "$schema", a derived palette and font roles
|
||||||
|
npm create waybetter app -- --site kick.com # a whole app: Tauri 2 + waybetter-host + runtime + shell
|
||||||
|
```
|
||||||
|
|
||||||
|
`create-waybetter` (in `packages/create-waybetter`) asks for what it needs in a terminal, and
|
||||||
|
takes every answer as a flag (`--help`). The app skeleton is this README in code: the native
|
||||||
|
`SiteSpec`, the page `SiteAdapter`, the app on `waybetter_host::app` (its config, site hooks and
|
||||||
|
its own commands), the three capability files and a `tests/security.rs` on `waybetter_host::testkit`,
|
||||||
|
the shell (the framework's shell frame through `createShell`, with the site's pages and a plugins
|
||||||
|
panel), the plugin store, one site-only command, the
|
||||||
|
runtime bundled with `waybetter/build` and a `waybetter.release.json` for `waybetter release`, with presets for
|
||||||
|
youtube.com, kick.com and twitch.tv and every site selector marked as a placeholder. Its tests
|
||||||
|
generate each kind into a temp folder and check it against the real contracts: plugin headers with
|
||||||
|
`plugins::parse_meta`, plugin code against `createCorePluginApi`'s members, themes against
|
||||||
|
`theme.schema.json`, the app's TypeScript with `tsc` against the built package and its Rust with
|
||||||
|
`cargo check`/`cargo test` against this crate.
|
||||||
|
|
||||||
|
## Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
crates/waybetter-host/ Rust: security policy, profiles, plugin store, hotfix, updates, tab payloads,
|
||||||
|
and the generic native features every app gets (below)
|
||||||
|
tab-bridge.js the tab bridge every tab gets (served by src/bridge.rs)
|
||||||
|
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/plugins/commands.rs palette commands site tabs report, and the script that runs one
|
||||||
|
src/settings.rs the shell's settings (home page, where links open, session restore) and the
|
||||||
|
page's feature flags, as validated data and the scripts that deliver them
|
||||||
|
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,
|
||||||
|
deck ColumnConfig bounds and unread caps
|
||||||
|
src/bridge.rs the tab bridge script (reports; shortcut/link-drag forwarding opt-in)
|
||||||
|
src/backup.rs settings backup envelope, secret scrubbing, plugin/account sections
|
||||||
|
src/sync.rs encrypted folder sync (Argon2id + XChaCha20-Poly1305 snapshots)
|
||||||
|
src/workspaces.rs saved tab/pane/deck layouts, bounded and well-formed
|
||||||
|
src/devmode.rs developer mode: debounced file watcher, reload order, error positions
|
||||||
|
src/alerts.rs keyword alerts: keywords, snippets, rate limits; native notifications
|
||||||
|
src/media.rs gallery folders (path containment), clipboard history, PNG encoding
|
||||||
|
src/media/clipboard.rs (feature "tauri") opt-in clipboard polling, private copies skipped
|
||||||
|
src/gfonts.rs self-hosted Google Fonts: CSS parsing, URL/woff2 checks, cache format
|
||||||
|
src/fonts.rs (feature "net") font downloads and the font cache
|
||||||
|
src/updater.rs (features "tauri" + "net") signed native updates and the hotfix channel
|
||||||
|
src/store/ install links, download allow-list, signed multi-app store catalog, staging
|
||||||
|
and installs; downloads with feature "net" (docs/STORE.md)
|
||||||
|
src/host.rs (feature "tauri") webview helpers, shell events, system menu
|
||||||
|
src/app.rs (feature "app") the whole app around a site: run_app / App, AppConfig,
|
||||||
|
SiteHooks, the window, shell and tab webviews, the generic commands
|
||||||
|
(tabs, profiles, language, plugins and custom CSS, feature flags, settings)
|
||||||
|
src/commands.rs the commands the host serves and who may call them; manifest() for build.rs
|
||||||
|
src/testkit.rs capability/caller-check assertions for an app's tests/security.rs
|
||||||
|
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 (incl. ui and theme)
|
||||||
|
ui.ts plugin UI kit: toasts, alert/confirm/prompt, dialogs (shadow DOM, themed)
|
||||||
|
themeApi.ts the active theme as values + --wb-* CSS variables (api.theme)
|
||||||
|
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
|
||||||
|
column.ts deck columns: hide site chrome, fill the width, filters, unread count
|
||||||
|
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
|
||||||
|
siteRuntime.ts the runtime's composition: the IPC bridge, flag-controlled parts with a deck
|
||||||
|
column's overrides, the runtime object under its window names, native queues
|
||||||
|
pageStrings.ts the page's language: English built in, native deliveries checked as data
|
||||||
|
stringPacks.ts string packs (docs/STRING-PACKS.md): pack and inventory formats, validator,
|
||||||
|
ordered engine, coverage, drift report
|
||||||
|
stringPackHook.ts the per-site catalog hook adapter, its self-check, a webpack chunk array hook
|
||||||
|
textNet.ts DOM safety net for labels no catalog hook reaches
|
||||||
|
panelButton.ts the way into the panel from the page (navigation entry or floating button)
|
||||||
|
commandReport.ts the palette command report and developer-mode start errors
|
||||||
|
packages/shell/src/ shell core (TypeScript) and the shell frame (React)
|
||||||
|
addressModel.ts address bar chips (site pages named by the adapter)
|
||||||
|
paneModel.ts beside-pane reuse, redundant rails, navRedundant for tabs_sync
|
||||||
|
deckModel.ts decks of site columns: bounded storage model, paging layout, focus
|
||||||
|
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)
|
||||||
|
storeModel.ts storeMessages.ts Store wire types, item states, permission words; wb.store/install/permission.*
|
||||||
|
installController.ts the install screen's state machine (links, drops, store items, confirm)
|
||||||
|
InstallDialog.tsx StoreView.tsx store.css the install screen and the Store view (React peer, --wb-* tokens)
|
||||||
|
frame/ the shell frame: createShell(site) (see "The shell frame" below)
|
||||||
|
panel/ the panel: createPanel(site), the app's own tab (see "The panel" below)
|
||||||
|
installerMessages.ts the Windows installer's words (wb.installer.*)
|
||||||
|
packages/waybetter/ the published npm package (runtime + shell as ESM + .d.ts, theme.schema.json,
|
||||||
|
store-catalog.schema.json, the `waybetter store build|sign|verify`,
|
||||||
|
`waybetter release windows|macos`, `waybetter i18n check|extract`,
|
||||||
|
`waybetter privacy-scan` and `waybetter build-env` commands, `waybetter/build`, locales/ (51 catalogs and translator notes),
|
||||||
|
windows/ (the installer template and its language files))
|
||||||
|
dev-tools/ development harnesses for a running or built app (perf probes, close and
|
||||||
|
stress checks); not published (dev-tools/README.md)
|
||||||
|
docs/STORE.md the Store: shared catalog format, signing and keys, tooling, trust model, how to add it
|
||||||
|
packages/create-waybetter/ `npm create waybetter`: plugin, theme and app scaffolds (no dependencies)
|
||||||
|
```
|
||||||
|
|
||||||
|
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, the shell frame) takes it as a
|
||||||
|
parameter. The React parts (the Store screens, the shell frame) have React, and the frame dockview,
|
||||||
|
as optional peers: the app's copies are used.
|
||||||
|
|
||||||
|
## The shell frame
|
||||||
|
|
||||||
|
`packages/shell/src/frame` (`waybetter/shell/frame`) is the whole shell of a wayBetter app. An app
|
||||||
|
describes its site and gets tabs in the titlebar row, split panes and link drags into the dock, the
|
||||||
|
smart address bar, the new-tab page, the command palette, the account switcher, decks of site
|
||||||
|
columns, workspaces, the developer-mode and sync chips, the gallery/clipboard panel, pane themes,
|
||||||
|
its own panel tab, keyboard shortcuts, overlays that raise the shell above the tab webviews, the
|
||||||
|
one-layout-in-flight `tabs_sync` and session restore:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { invoke } from '@tauri-apps/api/core'; // or window.__TAURI__ (withGlobalTauri)
|
||||||
|
import { listen } from '@tauri-apps/api/event';
|
||||||
|
import { getCurrentWindow } from '@tauri-apps/api/window';
|
||||||
|
import { createShell, type ShellSite } from 'waybetter/shell/frame';
|
||||||
|
|
||||||
|
const site: ShellSite = { name: 'Kick', product: 'wayBetter for Kick', homeUrl, loginUrl, logoutUrl,
|
||||||
|
isSiteUrl, accounts, searchUrl, address, panel: { id, title, component }, newTab, palette,
|
||||||
|
deck, media, themes, overlays, features, start };
|
||||||
|
const Shell = createShell(site, { native: { invoke, listen, currentWindow: getCurrentWindow }, i18n });
|
||||||
|
createRoot(root).render(<Shell/>);
|
||||||
|
```
|
||||||
|
|
||||||
|
What the site supplies (`frame/site.ts`, every field documented there):
|
||||||
|
|
||||||
|
- names and pages: `name` (in messages as `{site}`), `product`, `logo`, `homeUrl`, `loginUrl`,
|
||||||
|
`logoutUrl`, `isSiteUrl`, the account rules, `searchUrl` for typed text;
|
||||||
|
- the address bar: `address(url)` (chips, usually `parseAddress` with an `AddressSite`) and an
|
||||||
|
optional `addressCompleter` (inline completions, e.g. search operators);
|
||||||
|
- slots: `panel` (the app's own tab and its sections), `newTab` (search label, quick links),
|
||||||
|
`palette` (placeholder, the literal search, completions, the panel's sections, the site's pages),
|
||||||
|
`deck` (column kinds with labels and icons, the page each loads, titles, value parsing and
|
||||||
|
completions, column flags and presets, an optional compose dock), `media` (which pages have a
|
||||||
|
composer), `themes` (a `createThemeStore(adapter)`: the app's theme documents, chrome colors via
|
||||||
|
`chromeVars`, pane themes), `overlays` (the app's own dialogs), `start()` (read site settings,
|
||||||
|
call `siteChanged()` when site text changes);
|
||||||
|
- `features`: the native features the app wires up (workspaces, sync, developer mode, plugin
|
||||||
|
palette commands); an app without them shows nothing of them.
|
||||||
|
|
||||||
|
The frame's words are `wb.*` messages in the framework catalogs (51 languages; English source in
|
||||||
|
`frame/frameMessages.ts`): the app passes its i18n instance with the framework catalogs merged in.
|
||||||
|
Styles come with the components (dockview's, then `shell.css`, `deck.css`, `workspaces.css`,
|
||||||
|
`accountSwitcher.css`, `paneTheme.css`); colors are `--wb-c-*` tokens with Night Ink fallbacks,
|
||||||
|
set by the theme store (the chrome and each pane group) and cached for the first frame:
|
||||||
|
`bootScript()` (`frame/boot.ts`) is the `boot.js` an app serves before its modules (a Vite plugin or
|
||||||
|
a build step writes it). `installPreviewMocks(handlers)` answers native commands from memory, so
|
||||||
|
the real shell renders in a plain browser for development previews and screenshots.
|
||||||
|
|
||||||
|
Native commands the frame calls: the host's (`tabs_sync`, `tab_navigate`, `tab_action`,
|
||||||
|
`shell_focus`, `shell_raise`, `open_external_url`, `window_system_menu`, `profiles_*`), and for the
|
||||||
|
features an app turns on `settings_get`, `column_configure`, `workspaces_*`, `sync_*`, `dev_*`,
|
||||||
|
`plugins_list`, `tab_run_command`, `media_get`/`gallery_*`/`clip_*`/`tab_attach_image`/
|
||||||
|
`tab_insert_text`, `theme_scopes_*` and `gfonts_*`, `app_ready`/`update_status`/`apply_update`. It
|
||||||
|
listens to `tab-state`, `tab-open`, `tab-shortcut`, `link-drag`, `open-panel`, `profiles-changed`,
|
||||||
|
`tab-commands`, `dev-event`, `update-status`, `tab-still` and `clipboard-changed`.
|
||||||
|
|
||||||
|
## The panel
|
||||||
|
|
||||||
|
`packages/shell/src/panel` (`waybetter/shell/panel`) is an app's own tab in the shell: a home page,
|
||||||
|
Appearance (the theme gallery, customization, account and pane themes, downloaded fonts, theme
|
||||||
|
import/export) and the Theme Builder (undo/redo, a palette from three colors, a contrast report, a
|
||||||
|
font per role with the Google Fonts browser), plugins and custom CSS, the Store, Make (example
|
||||||
|
plugins, the plugin UI kit, the theme API, bundled docs), accounts, Power User (deck settings),
|
||||||
|
settings (language, links and session, keyword alerts, the media panel), backup and sync, developer
|
||||||
|
mode, updates, and a search across every setting. It lives in the shell package, next to the frame
|
||||||
|
it renders in: it uses the frame's stores (profiles, decks, themes, sync, developer mode), its
|
||||||
|
native bridge and its language, so `createShell` comes first.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { createPanel, type PanelSite } from 'waybetter/shell/panel';
|
||||||
|
|
||||||
|
const panel: PanelSite = { brand: { name: 'wayBetter', logo }, home, themes, sections, order, make,
|
||||||
|
store, languages, settings, power, backup: true, updates: true };
|
||||||
|
const Panel = createPanel(panel);
|
||||||
|
const Shell = createShell({ ...site, panel: { id: 'app', title: 'wayBetter', component: Panel } }, options);
|
||||||
|
```
|
||||||
|
|
||||||
|
What the app supplies (`panel/site.ts`, every field documented there):
|
||||||
|
|
||||||
|
- `brand` and `home`: the header and the home page's words (kicker, title, lede, chips, actions,
|
||||||
|
highlight cards, the About block), `version()` for its chip;
|
||||||
|
- `sections` and `order`: its own sections (a label, an icon path, a component that gets `notify`
|
||||||
|
and `openSection`; `searchable` ones also show in the settings search), placed among the built-in
|
||||||
|
ones. X adds Tweaks and Drafts;
|
||||||
|
- `themes`: its theme store and catalog (`createThemeStore`, `createThemeCatalog`), accent swatches,
|
||||||
|
the **preview** component (a miniature of the site drawn from a theme document, used by the gallery
|
||||||
|
and the builder), the site font's name, the palette a draft starts from, and for Make's theme view
|
||||||
|
`resolved(choice, mode)` with the site's own display modes;
|
||||||
|
- `make`: example plugins, an example theme file and bundled Markdown docs;
|
||||||
|
- `store`: the install controller (the Store section, and removing a plugin from the list);
|
||||||
|
- `languages`: the language list and state (`createLanguage`, `frame/language.ts`);
|
||||||
|
- `settings`, `power`, `cssExamples`: keyword alerts, extra settings rows, which column flags and
|
||||||
|
which memory measure Power User lists, placeholder CSS with the site's selectors.
|
||||||
|
|
||||||
|
A built-in section shows only when the app serves what it needs: Appearance, the Theme Builder and
|
||||||
|
the Store with `themes` (and `store`), Make with `make`, Power User with `site.deck`, backup with
|
||||||
|
`backup` (its sync half with the frame's `sync` feature), Developer with the frame's `developer`
|
||||||
|
feature, Updates with `updates`. An app with nothing but plugins gets Home, Plugins, Accounts and
|
||||||
|
Settings (this is what `npm create waybetter app` generates).
|
||||||
|
|
||||||
|
Building blocks for the app's own sections: the panel's controls (`Section`, `Row`, `Toggle`,
|
||||||
|
`Segmented`, `Select`, `Slider`, `ColorField`, `Button`, `Badge`, ...; `panel/controls`), the
|
||||||
|
feature toggles (`useFeatures` + `FeatureGroups` over `features_get/set`: the app names its flags
|
||||||
|
and groups, its catalog has `features.<flag>.label` and `.description`), and `compareLines`.
|
||||||
|
|
||||||
|
The panel's words are `wb.*` messages too (English source in `panel/panelMessages.ts`, translator
|
||||||
|
notes in `locales/en.meta.json`). Three families of keys stay the app's, by convention, because
|
||||||
|
they name its own things: `plugin.<file>.name|description` (its bundled plugins),
|
||||||
|
`theme.<id>.description` (its built-in themes) and `features.*` (its tweaks).
|
||||||
|
|
||||||
|
Native commands the panel calls: the host's `plugins_list`, `plugin_set_enabled`,
|
||||||
|
`plugins_open_folder`, `custom_css_get/set`, `features_get/set`, `settings_get/set`,
|
||||||
|
`profiles_*` and `open_external_url`, and for what the app turns on `alerts_get/set`,
|
||||||
|
`media_get/set`/`gallery_add_folder`/`clip_remove`, `backup_*`, `sync_*`, `dev_*`, the theme
|
||||||
|
store's commands and `gfonts_*`, `install_records`/`install_forget`/`plugin_remove`/`store_catalog`,
|
||||||
|
`app_ready`/`update_status`/`apply_update`.
|
||||||
|
|
||||||
|
The Google Fonts list the font browser shows is an offline snapshot
|
||||||
|
(`panel/fonts/googleFontsCatalog.json`; `packages/shell/scripts/google-fonts-catalog.mjs`
|
||||||
|
regenerates it). The app never fetches the list, only the font files the owner picks (natively).
|
||||||
|
|
||||||
|
## The site adapter
|
||||||
|
|
||||||
|
A site adapter is three small, explicit things.
|
||||||
|
|
||||||
|
### 1. Native: `SiteSpec` (Rust)
|
||||||
|
|
||||||
|
```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)
|
||||||
|
|
||||||
|
```ts
|
||||||
|
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.
|
||||||
|
|
||||||
|
What every runtime entry does the same way is composed by `runtime/siteRuntime`:
|
||||||
|
`pageInvoke(window, product)` (the IPC bridge, read at call time), `createFeatureFlags({ defaults,
|
||||||
|
installers, apply })` (parts that install on enable and dispose on disable; a deck column's flag
|
||||||
|
overrides sit on top of the owner's) and `installSiteRuntime({ win, site, version, plugins, strings,
|
||||||
|
features, theme, fonts, pane, links, column, extra, queues })`, which builds the runtime object
|
||||||
|
(`features.apply`, `i18n.set`, `links.configure`, `pane.set`, `fonts.provide`, `column.set`,
|
||||||
|
`open()`, `api`, `withPlugin`, `devError`), publishes it as `window.wayBetter` and the app's own
|
||||||
|
names, takes over what native code queued before it existed and starts the palette command report.
|
||||||
|
`createPageStrings` (`runtime/pageStrings`) is the page's language and `installPanelButton`
|
||||||
|
(`runtime/panelButton`) keeps the way into the panel on the page: the adapter's `mountNav` puts
|
||||||
|
an entry into the site's own navigation, and where the page has none a floating button stands in.
|
||||||
|
|
||||||
|
### 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) | the app's own commands and the host's `commands::SHELL` (`tabs_sync`, `tab_navigate`, `tab_action`, `shell_raise`, `profiles_*`, `i18n_*`, `plugins_*`, `custom_css_*`, `features_*`, `settings_*`, ...) |
|
||||||
|
| `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, and the host's `commands::SITE` (`open_panel`) |
|
||||||
|
| other local webviews (`popover-*`, ...) | their own narrow capability |
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "identifier": "tab-chrome", "webviews": ["tab-*"], "local": false,
|
||||||
|
"remote": { "urls": ["https://*/*", "http://*/*"] },
|
||||||
|
"permissions": ["allow-tab-report", "allow-tab-shortcut", "allow-tab-link-drag"] }
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "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`).
|
||||||
|
|
||||||
|
`waybetter_host::testkit` checks this in an app's own tests: `Capabilities::from_dir` reads every
|
||||||
|
capability file, `assert_host_commands` keeps the host's commands shell-only / tab-only,
|
||||||
|
`assert_shell_only` / `assert_tab_only` do the same for the app's, `assert_site_only(command, &SITE)`
|
||||||
|
checks that a site command is granted only on the site's own URLs, `assert_no_plugin_apis` refuses
|
||||||
|
Tauri plugin JS APIs, and `assert_guarded` / `assert_host_guards` check that each command's first
|
||||||
|
statement checks its caller.
|
||||||
|
|
||||||
|
## What the host gives an app
|
||||||
|
|
||||||
|
- `app` (feature `app`): the whole app. `App::new(AppConfig, hooks).setup(..).run(context,
|
||||||
|
handler)` (or `run_app`) registers single-instance, deep-link (opt-in), window-state, opener,
|
||||||
|
updater (opt-in), process, notification and dialog; makes the app-data folder (0700 on Unix),
|
||||||
|
loads the profiles and the language, runs the app's setup, then builds the window (frameless
|
||||||
|
with the shell's titlebar, or the OS frame), restores its geometry (lost geometry reset),
|
||||||
|
routes helper-window closes (Windows), follows window resizes natively and adds the shell
|
||||||
|
webview (transparent: it can rise above the tabs; macOS needs the `macos-private-api` feature).
|
||||||
|
It serves `commands::SHELL` (`tabs_sync`, `tab_navigate`, `tab_action`, `open_external_url`,
|
||||||
|
`shell_focus`, `shell_ready`, `tab_still_ready`, `shell_raise`, `window_system_menu`, `profiles_get`/`profiles_set`,
|
||||||
|
`i18n_get`/`i18n_set`, `plugins_list`, `plugin_set_enabled`, `plugins_open_folder`,
|
||||||
|
`custom_css_get`/`custom_css_set`, `features_get`/`features_set`, `settings_get`/`settings_set`),
|
||||||
|
`commands::TAB` (`tab_shortcut`, `tab_link_drag`) and `commands::SITE` (`open_panel`), each
|
||||||
|
checking its caller first, and dispatches every other command to the app's handler. It keeps
|
||||||
|
the page state those commands read and save (`PageState`: the plugin store in app data
|
||||||
|
`plugins`, made from the `PluginHost` in `AppConfig::new(site, title, plugins)`; the feature flags
|
||||||
|
in `features.json`; `ShellSettings` in `settings.json`): the app reads it with `page(app)`, gets a
|
||||||
|
loaded document's scripts from `page_scripts(app)` (flags, links, custom CSS, plugins) and writes
|
||||||
|
it with `set_features`, `set_settings` and `set_custom_css` (a backup import). Tab webviews get their
|
||||||
|
profile's data folder, the app's document-start scripts, navigation/pop-up/load/title/download
|
||||||
|
handling, stills and memory targets; `SiteHooks` is where the app says what only it knows (page
|
||||||
|
scripts, legacy domains, link routing, per-tab state, what a finished site page gets). Helpers:
|
||||||
|
`profiles`, `tab_profile`, `account_seen`, `tr`/`trf`, `i18n_page_script`, `notify`,
|
||||||
|
`open_external`.
|
||||||
|
To show the first window only after restored panes are placed, opt in on both sides:
|
||||||
|
`AppConfig::defer_window_show = true` and `ShellSite.deferWindowShow = true`, and grant the
|
||||||
|
shell `allow-shell-ready`. The default still shows the window immediately. An opted-in app
|
||||||
|
shows it after initial `tabs_sync`, with a three-second fallback if shell startup fails.
|
||||||
|
- `commands`: the host's command lists (`SHELL`, `TAB`, `SITE`) and `manifest(&[..])` for the app's `build.rs`.
|
||||||
|
- `settings`: `ShellSettings` (home page, where links to other sites and to the site's own pages
|
||||||
|
open, session restore; missing fields take the defaults), `links_script`, and the feature flags'
|
||||||
|
validation (a small map of booleans) and `features_script`.
|
||||||
|
- `testkit`: see the capabilities section.
|
||||||
|
- `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.
|
||||||
|
- `bridge`: the tab bridge (`SOURCE`, or `script(BridgeOptions)` to leave shortcut and link-drag
|
||||||
|
forwarding off when the shell does not handle them).
|
||||||
|
- `backup` + `sync`: the `.waybetter` settings backup (the app registers its sections and files;
|
||||||
|
secret-looking keys are scrubbed both ways) and encrypted snapshots in a folder the owner syncs.
|
||||||
|
- `workspaces`: validation of saved layouts (slug ids, known tab kinds, http(s) URLs, size caps).
|
||||||
|
- `devmode`: the live-reload watcher (plugins, `custom.css`, one theme file; the app turns the theme
|
||||||
|
document into its own state through a callback).
|
||||||
|
- `alerts`: keyword settings, snippets, `Throttle`, `AlertGate` over any `KeywordMatch`;
|
||||||
|
`alerts::notify` (feature `tauri`) shows a native notification.
|
||||||
|
- `media`: gallery folders and the opt-in clipboard history; `media::clipboard::watch` (feature
|
||||||
|
`tauri`) polls the OS clipboard and never reads a copy a password manager marked private.
|
||||||
|
- `gfonts` + `fonts` (feature `net`): Google Fonts downloaded natively from the two Google hosts
|
||||||
|
only, cached with a sha256 manifest and handed to site pages as bytes (`page_script(&SITE, ..)`).
|
||||||
|
- `updater` (features `tauri` + `net`): the update loop, the signed hotfix channel and
|
||||||
|
`status`/`apply`/`ready` for the app's commands, configured by an `UpdaterConfig`.
|
||||||
|
- `plugins::commands`: palette commands a site tab reports, and `run_script(&SITE, id)`.
|
||||||
|
- `store`: the wayBetter Store for any app from a `StoreConfig` (app id, link scheme, store URL,
|
||||||
|
public keys with rotation, download hosts): `waybetter://install` link parsing, the allow-list,
|
||||||
|
size caps, catalog verification (Ed25519, strict schema, each app sees only its items), `Store`
|
||||||
|
(pending links, staged installs, commit of exactly the staged bytes, records, offline catalog),
|
||||||
|
and with feature `net` no-redirect/no-cookie downloads. The shell half is `waybetter/shell`'s
|
||||||
|
`InstallHost`, `StoreView` and install controller; the tooling is `waybetter store`
|
||||||
|
(docs/STORE.md).
|
||||||
|
- `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 for everything else, and its capability files;
|
||||||
|
its `build.rs` lists its commands through `commands::manifest`, which adds the host's.
|
||||||
|
|
||||||
|
The npm package adds the app-side tooling:
|
||||||
|
|
||||||
|
- `waybetter/build`: `buildRuntime({ entry, outfile, catalog, prefixes, ... })` bundles a page
|
||||||
|
runtime into one IIFE with the app's esbuild (`?inline` CSS as text, other CSS dropped, only the
|
||||||
|
runtime's own catalog prefixes compiled in).
|
||||||
|
- `waybetter release windows|macos`: signed native releases and the update manifest from the
|
||||||
|
app's `waybetter.release.json` (product and file names, key folder, CDN and API URLs, an optional
|
||||||
|
manifest validator). Windows: the signed NSIS build, the installer and `.sig` in
|
||||||
|
`<outDir>/upload`, `latest.json` (other platforms of the version kept); macOS: signs a universal
|
||||||
|
build's updater bundle and adds both darwin platforms. It never uploads: it prints the steps.
|
||||||
|
The key is read only into the build's environment or handed to the Tauri signer by path.
|
||||||
|
- `waybetter build-env -- <command>` and `waybetter privacy-scan`: nothing an app publishes may
|
||||||
|
name the person who built it. A Rust binary embeds the absolute paths of its sources (the Cargo
|
||||||
|
registry, the rustup toolchain, the workspace: about 1,400 strings holding the account name in
|
||||||
|
one app), so `build-env` runs a build with those roots remapped to `/home`, `/src`, `/cargo`,
|
||||||
|
`/rustup` and `/target` (`--remap-path-prefix` appended to the flags already set,
|
||||||
|
`/PDBALTPATH:%_PDB%` on MSVC, `-ffile-prefix-map` for C sources on gcc and clang). MSVC has no
|
||||||
|
prefix map, so there the C and C++ a build script compiles (a CMake library, the cc crate) lose
|
||||||
|
the same roots through `/d1trimfile:<root>` in the `CL` variable, and any PDB they link through
|
||||||
|
`/PDBALTPATH` in `LINK`; cl.exe and link.exe read both themselves, whatever runs them:
|
||||||
|
`waybetter build-env -- tauri build`, on every platform. `privacy-scan` is the proof: it searches
|
||||||
|
files, binaries (UTF-8, UTF-16), archives (npm tarballs, zip, tar, .deb, DMG; NSIS installers and
|
||||||
|
AppImages through 7-Zip), git-tracked files and, with `--history`, every blob, path, commit
|
||||||
|
message and identity of a repository for the terms in a file kept outside every repository
|
||||||
|
(`"forbiddenTerms"` in `waybetter.release.json`, or `WAYBETTER_FORBIDDEN_TERMS`) plus the
|
||||||
|
machine's account name, and prints hits masked (`m***`). `waybetter release` builds with
|
||||||
|
`build-env` and refuses to release an artifact with a hit or one it could not open. The `.pdb`
|
||||||
|
next to a Windows binary still holds every path: never publish it.
|
||||||
|
- `waybetter strings check <pack>`: a string pack (data that replaces the wrapped site's own UI
|
||||||
|
strings) against the site's string inventory: only inventory keys, parameter names, plural and
|
||||||
|
select kinds, no markup; prints the coverage. See docs/STRING-PACKS.md.
|
||||||
|
- `waybetter i18n check|extract`: an app's locale catalogs against the framework's rules (file
|
||||||
|
shape, keys English lacks, ICU syntax, placeholder parity, plural forms, no markup), the
|
||||||
|
framework's catalogs in the same languages, the generated `languages.json` and native
|
||||||
|
localization files (macOS `Info.plist` and `InfoPlist.strings`, the Linux `.desktop` template),
|
||||||
|
bundled plugins' inline English, and the keys the code looks up; configured by the app's
|
||||||
|
`waybetter.i18n.json`.
|
||||||
|
- `waybetter/windows/languages/<Language>.nsh`: the installer's messages for the 17 languages
|
||||||
|
Tauri does not ship itself, generated from the framework catalogs (`wb.installer.*`;
|
||||||
|
`node packages/waybetter/scripts/installer-languages.mjs --write`). An app lists them under
|
||||||
|
`bundle.windows.nsis.customLanguageFiles`.
|
||||||
|
- `waybetter/windows/installer.nsi`: the Windows installer, a template for Tauri's NSIS bundler
|
||||||
|
(`bundle.windows.nsis.template`). No wizard and no UAC: it installs for the current user, makes
|
||||||
|
the Desktop and Start menu shortcuts and opens the app. Run again by hand, it only installs when
|
||||||
|
it is newer than what is installed (an upgrade in place, app data untouched); otherwise it opens
|
||||||
|
the installed app and exits 0, so an old setup left in Downloads never replaces or downgrades an
|
||||||
|
install the updater has moved on. `/FORCE` reinstalls the same version (repair), `/NORUN` does
|
||||||
|
not open the app, `/UPDATE` is the updater's path and always installs. An app renamed after its
|
||||||
|
first release keeps its registry keys by defining `WAYBETTER_LEGACY_NAME` in its installer hooks
|
||||||
|
(`bundle.windows.nsis.installerHooks`).
|
||||||
|
|
||||||
|
## 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 = ["app", "net", "macos-private-api"]` enabled by the app's desktop feature (and
|
||||||
|
as a build-dependency for `commands::manifest`).
|
||||||
|
- TypeScript: relative imports of `waybetter/packages/*/src/*.ts`: the X site for the shell frame
|
||||||
|
(`src/shell/site.tsx`), the page runtime's adapter and a few X modules. Its Vite config dedupes
|
||||||
|
React, dockview and the Tauri API (the frame's imports use the app's copies) and serves
|
||||||
|
`bootScript()` as `/boot.js`. 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.
|
||||||
|
|
||||||
|
## Dev loop
|
||||||
|
|
||||||
|
`waybetter dev [--stable] --watch "<build watcher>"...` starts the app's watchers, waits for their
|
||||||
|
first build and runs `tauri dev` (`--stable` adds `--no-watch`: a Rust file saved by someone else
|
||||||
|
does not restart the app; restart it yourself after Rust changes). Debug builds only:
|
||||||
|
|
||||||
|
- The app names its page scripts with `waybetter_host::page_script!(include_str!("../x.js"), "x.js")`
|
||||||
|
in `SiteHooks::init_scripts`. A debug build reads the file from disk (path relative to the app
|
||||||
|
crate, falling back to the embedded copy) each time a tab's init scripts are built and watches it
|
||||||
|
(`devloop`, using `devmode`'s debounced signature watcher). When it changes, every tab webview is
|
||||||
|
rebuilt on its current URL through `tabs_sync`, because a webview's document-start scripts are
|
||||||
|
fixed at creation. Route is kept, scroll is not. About 1 s from save to visible.
|
||||||
|
- `buildRuntime({ watch: watchRequested(), ... })` (`waybetter/build`) keeps esbuild rebuilding the
|
||||||
|
file; a failed build leaves the last good one.
|
||||||
|
- The shell reloads through the frontend dev server (`beforeDevCommand`), instantly.
|
||||||
|
- Restart needed: Rust, `tauri.conf.json`, capabilities, bundled plugin sources (`include_str!` in the
|
||||||
|
plugin table; installed plugin files reload with developer mode as before).
|
||||||
|
- Release builds contain none of it: `devloop` is `cfg(debug_assertions)`, the macro's release arm is
|
||||||
|
`$embedded.to_owned()` and the path literal is never expanded. `release_guard` (lib.rs) checks that
|
||||||
|
every mention is gated; `cargo test --release` also runs `release_page_script_is_the_embedded_copy`.
|
||||||
|
- `.taurignore` the watched output files (`observer.js`, `x-runtime.js`), or plain `tauri dev` restarts
|
||||||
|
on every rebuild. `create-waybetter` apps get `npm run dev` and `npm run dev:stable`.
|
||||||
|
|
||||||
|
## Scripts (no CI)
|
||||||
|
|
||||||
|
```sh
|
||||||
|
bun install # typescript + @types/node for the checks
|
||||||
|
bun run typecheck # tsc over both packages and their tests, and create-waybetter (checkJs)
|
||||||
|
bun run test # node --test (runtime + shell), cargo test (headless host), create-waybetter
|
||||||
|
bun run test:ts
|
||||||
|
bun run test:rust
|
||||||
|
bun run test:create # scaffolds into temp dirs; its cargo check of an app is ~1 min cold
|
||||||
|
# (WAYBETTER_SKIP_CARGO_CHECK=1 skips it; needs the local crate cache)
|
||||||
|
bun run check # typecheck + build:packages + test
|
||||||
|
bun run check:tauri # cargo check with the app feature (slow: builds Tauri and its plugins)
|
||||||
|
bun run build # typecheck + cargo build
|
||||||
|
bun run pack:check # npm pack --dry-run of waybetter and create-waybetter
|
||||||
|
node packages/waybetter/scripts/installer-languages.mjs [--write] # windows/languages/*.nsh from the catalogs
|
||||||
|
node packages/shell/scripts/google-fonts-catalog.mjs # the font browser's offline list
|
||||||
|
```
|
||||||
|
|
||||||
|
`dev-tools/` has the harnesses for a running or built app (perf probes, the graceful-close check,
|
||||||
|
tab and webview stress); see its README.
|
||||||
|
|
||||||
|
Requires Bun 1.4.2+, Node 24+ and Rust 1.88+.
|
||||||
|
|
@ -6,7 +6,9 @@ npm create waybetter
|
||||||
|
|
||||||
Scaffolds something for [wayBetter](https://waybetter.fyi), the framework behind wayBetter for X:
|
Scaffolds something for [wayBetter](https://waybetter.fyi), the framework behind wayBetter for X:
|
||||||
a **plugin**, a **theme**, or a whole new **wayBetter app** for another site. It asks what it needs
|
a **plugin**, a **theme**, or a whole new **wayBetter app** for another site. It asks what it needs
|
||||||
when run in a terminal; every answer is also a flag. No dependencies, Node 18.3+.
|
when run in a terminal; every answer is also a flag. No dependencies, Node 18.3+. Source: [git.crt.fyi/CRT/waybetter](https://git.crt.fyi/CRT/waybetter)
|
||||||
|
(`packages/create-waybetter`); its tests scaffold each kind into a temporary folder and check the
|
||||||
|
result against the framework's real contracts.
|
||||||
|
|
||||||
## Plugin
|
## Plugin
|
||||||
|
|
||||||
|
|
@ -40,10 +42,14 @@ Presets: `midnight`, `paper`, `dusk`. Import it in **wayBetter → Appearance
|
||||||
## App
|
## App
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
npm create waybetter app -- --site kick.com
|
npm create waybetter app kickapp -- --site kick.com --name "wayBetter for Kick" --yes
|
||||||
npm create waybetter app -- --site youtube.com --name "wayBetter for YouTube"
|
npm create waybetter app ytapp -- --site youtube.com --name "wayBetter for YouTube"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
The first argument after `app` is the folder to create. The tool then prints its next steps:
|
||||||
|
`git init && git submodule add https://git.crt.fyi/CRT/waybetter.git waybetter`, `npm install`,
|
||||||
|
`npm run build`, `npm run tauri dev`, and replacing the placeholder selectors.
|
||||||
|
|
||||||
A wayBetter app skeleton, the same system as wayBetter for X: a Tauri 2 window with a trusted
|
A wayBetter app skeleton, the same system as wayBetter for X: a Tauri 2 window with a trusted
|
||||||
local shell and one native child webview per site tab (`waybetter-host`), the page runtime and
|
local shell and one native child webview per site tab (`waybetter-host`), the page runtime and
|
||||||
shell models from the `waybetter` package, and the site adapter in its three parts:
|
shell models from the `waybetter` package, and the site adapter in its three parts:
|
||||||
|
|
|
||||||
|
|
@ -2,8 +2,8 @@
|
||||||
|
|
||||||
Sources of `waybetter/shell/*`: the shell models, the Store screens, the shell frame (`src/frame`,
|
Sources of `waybetter/shell/*`: the shell models, the Store screens, the shell frame (`src/frame`,
|
||||||
`createShell`) and the panel (`src/panel`, `createPanel`: the app's own tab). Published as part of
|
`createShell`) and the panel (`src/panel`, `createPanel`: the app's own tab). Published as part of
|
||||||
the [`waybetter`](../waybetter/README.md) package; not published on its own. The repository README's
|
the [`waybetter`](../waybetter/README.md) package; not published on its own. The repository's
|
||||||
"The shell frame" and "The panel" sections describe what an app supplies.
|
`docs/ARCHITECTURE.md` ("The shell frame" and "The panel") describes what an app supplies.
|
||||||
|
|
||||||
The panel is here rather than in a package of its own because it is drawn inside the frame and
|
The panel is here rather than in a package of its own because it is drawn inside the frame and
|
||||||
shares its state: the frame's profile, deck, theme, sync and developer-mode stores, its native
|
shares its state: the frame's profile, deck, theme, sync and developer-mode stores, its native
|
||||||
|
|
|
||||||
|
|
@ -4,6 +4,12 @@ The framework behind the wayBetter apps: the apps you already use in a light nat
|
||||||
window, extended in place the way BetterDiscord extends Discord. Websites and services that ship a
|
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.
|
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
|
- **`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,
|
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
|
dialogs), a theme API, an OKLab theme color model, split-pane rail hiding, link routing and
|
||||||
|
|
@ -180,7 +186,7 @@ or, in a project that installs the package, `"$schema": "./node_modules/waybette
|
||||||
```sh
|
```sh
|
||||||
npm create waybetter plugin # *.plugin.js (or --ts) using api.scope, storage, ui and theme
|
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 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)
|
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
|
[`create-waybetter`](https://www.npmjs.com/package/create-waybetter) generates code against this
|
||||||
|
|
@ -190,7 +196,7 @@ package's real API and schema; `--help` lists every option.
|
||||||
|
|
||||||
| Project | Target | What it is |
|
| Project | Target | What it is |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| [wayBetter for X](https://waybetter.fyi/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. |
|
| [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.
|
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.
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue