+
You bring a site and a small adapter that says what the site is. wayBetter gives you the rest: a
Tauri 2 window with tabs, split panes and every account signed in side by side; a page runtime with
a plugin API, a theme engine and string packs; a signed Store with a safe install screen; backups,
@@ -29,8 +35,6 @@ encrypted sync and signed updates; and the tooling to scaffold, sign, scan and r
## How it fits together
-
-
A wayBetter app is one Tauri 2 window with several webviews. The framework has one piece for each
layer and does not need to know which site you wrap.
@@ -48,7 +52,7 @@ Details of every module are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
npm create waybetter app kickapp -- --site kick.com --name "wayBetter for Kick" --yes
```
-
+
The same tool starts a plugin or a theme:
@@ -57,6 +61,8 @@ npm create waybetter plugin -- --name "Hide Trends" # add --ts for Ty
npm create waybetter theme -- --name "Midnight Mint" --accent "#3ddc97"
```
+
+
The app scaffold adds the framework as a git submodule at `waybetter/` by default (`--host-source
path` and `--host-source git` are the alternatives). After `npm run tauri dev`, replace the
placeholder selectors in `src/site.ts` and `src-tauri/src/site.rs`. All flags:
@@ -65,7 +71,7 @@ placeholder selectors in `src/site.ts` and `src-tauri/src/site.rs`. All flags:
Inside an app, plugins and themes are plain files, the docs and examples are built in, and developer
mode reloads them as you save:
-
+
## Packages
@@ -81,8 +87,8 @@ mode reloads them as you save:
-
-
+
+
wayBetter for X (x.com; macOS, Windows, Linux). Tabs, split panes,
@@ -241,6 +247,9 @@ bun run test:create # scaffolds each kind into temp folders and checks them a
`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+.
+The README's terminal images are real output: `node tools/readme-term-shots.mjs` runs the commands and
+redraws `assets/readme/term/` (Google Chrome and cwebp).
+
## Docs
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): every module of the host, runtime and shell
diff --git a/assets/readme/architecture.svg b/assets/readme/architecture.svg
deleted file mode 100644
index 9d64aef..0000000
--- a/assets/readme/architecture.svg
+++ /dev/null
@@ -1,127 +0,0 @@
-
diff --git a/assets/readme/create-terminal.svg b/assets/readme/create-terminal.svg
deleted file mode 100644
index 1878c88..0000000
--- a/assets/readme/create-terminal.svg
+++ /dev/null
@@ -1,29 +0,0 @@
-
diff --git a/assets/readme/hero.webp b/assets/readme/hero.webp
index ecb0081..3a86e23 100644
Binary files a/assets/readme/hero.webp and b/assets/readme/hero.webp differ
diff --git a/assets/readme/make.mp4 b/assets/readme/make.mp4
deleted file mode 100644
index 1681e1b..0000000
Binary files a/assets/readme/make.mp4 and /dev/null differ
diff --git a/assets/readme/make.webp b/assets/readme/make.webp
index 313a2b4..40d0740 100644
Binary files a/assets/readme/make.webp and b/assets/readme/make.webp differ
diff --git a/assets/readme/showcase-panes.webp b/assets/readme/showcase-panes.webp
deleted file mode 100644
index ac4baaa..0000000
Binary files a/assets/readme/showcase-panes.webp and /dev/null differ
diff --git a/assets/readme/showcase-themes.webp b/assets/readme/showcase-themes.webp
index 7f932c4..0700528 100644
Binary files a/assets/readme/showcase-themes.webp and b/assets/readme/showcase-themes.webp differ
diff --git a/assets/readme/showcase-windows98.webp b/assets/readme/showcase-windows98.webp
new file mode 100644
index 0000000..f0896c9
Binary files /dev/null and b/assets/readme/showcase-windows98.webp differ
diff --git a/assets/readme/term/create-app.txt b/assets/readme/term/create-app.txt
new file mode 100644
index 0000000..6468a2d
--- /dev/null
+++ b/assets/readme/term/create-app.txt
@@ -0,0 +1,11 @@
+$ npm create waybetter app kickapp -- --site kick.com --name "wayBetter for Kick" --yes
+
+Created a wayBetter app in kickapp (32 files).
+
+Next:
+ cd kickapp
+ git init && git submodule add https://git.crt.fyi/CRT/waybetter.git waybetter
+ npm install
+ npm run build
+ npm run tauri dev
+ then replace the PLACEHOLDER selectors in src/site.ts and src-tauri/src/site.rs
diff --git a/assets/readme/term/create-app.webp b/assets/readme/term/create-app.webp
new file mode 100644
index 0000000..1d5e274
Binary files /dev/null and b/assets/readme/term/create-app.webp differ
diff --git a/assets/readme/term/create-plugin.txt b/assets/readme/term/create-plugin.txt
new file mode 100644
index 0000000..8de0d1d
--- /dev/null
+++ b/assets/readme/term/create-plugin.txt
@@ -0,0 +1,7 @@
+$ npm create waybetter plugin -- --name "Hide Trends"
+
+Created a wayBetter plugin in hide-trends (2 files).
+
+Next:
+ cd hide-trends
+ copy hide-trends.plugin.js into wayBetter → Plugins → Open folder, then Rescan
diff --git a/assets/readme/term/create-plugin.webp b/assets/readme/term/create-plugin.webp
new file mode 100644
index 0000000..bb5bacd
Binary files /dev/null and b/assets/readme/term/create-plugin.webp differ
diff --git a/crates/waybetter-host/src/app.rs b/crates/waybetter-host/src/app.rs
index f91d0b6..dd47131 100644
--- a/crates/waybetter-host/src/app.rs
+++ b/crates/waybetter-host/src/app.rs
@@ -1046,8 +1046,9 @@ async fn open_panel(webview: Webview, app: AppHandle, section: Option) -
// ---------------------------------------------------------------------------------------------
// Tab webviews
-/// Linux: the page-level part of a tab's `on_navigation`, run when the main frame starts loading
-/// `url` (WebKitGTK's navigation callback cannot tell iframes from the page). Returns false when
+/// Linux and macOS: the page-level part of a tab's `on_navigation`, run when the main frame starts
+/// loading `url` (WebKitGTK's navigation callback, and wry's WKWebView one, cannot tell iframes from
+/// the page). Returns false when
/// the load was redirected (a legacy domain) or stopped and handed to the browser.
fn main_frame_started(app: &AppHandle, site: &SiteSpec, hooks: &dyn SiteHooks, tab: &Webview, url: &Url) -> bool {
static ON_SITE: std::sync::OnceLock>> = std::sync::OnceLock::new();
@@ -1105,8 +1106,8 @@ fn tab_builder(app: &AppHandle, hooks: &Arc, tab: &NewTab, url: U
if url.scheme() == "about" {
return true;
}
- // WebKitGTK: possibly an iframe's own document (see below).
- if cfg!(target_os = "linux") && matches!(url.scheme(), "blob" | "data") {
+ // WebKit (GTK and macOS): possibly an iframe's own document (see below).
+ if cfg!(any(target_os = "linux", target_os = "macos")) && matches!(url.scheme(), "blob" | "data") {
return true;
}
open_external(app, url);
@@ -1116,7 +1117,10 @@ fn tab_builder(app: &AppHandle, hooks: &Arc, tab: &NewTab, url: U
// asks only for the page): a signed-out page embedding a sign-in iframe would get that
// iframe's URL as the tab's address. On Linux the page-level work below runs from
// on_page_load (Started), which is the main frame only.
- if cfg!(target_os = "linux") {
+ // macOS: wry asks this for every WKNavigationAction, iframes included (no targetFrame
+ // check), so an embedded player's URL became the tab's address and its loading flag never
+ // cleared (found 2026-10-11 with Chat+ link previews' YouTube frame). Same treatment.
+ if cfg!(any(target_os = "linux", target_os = "macos")) {
return true;
}
if let Some(site_url) = nav_hooks.canonical_url(url) {
@@ -1157,7 +1161,7 @@ fn tab_builder(app: &AppHandle, hooks: &Arc, tab: &NewTab, url: U
})
.on_page_load(move |tab, payload| {
let app = &load_app;
- if cfg!(target_os = "linux")
+ if cfg!(any(target_os = "linux", target_os = "macos"))
&& matches!(payload.event(), PageLoadEvent::Started)
&& !main_frame_started(app, site, &*load_hooks, &tab, payload.url())
{
diff --git a/crates/waybetter-host/src/profiles.rs b/crates/waybetter-host/src/profiles.rs
index 92210bb..e077e72 100644
--- a/crates/waybetter-host/src/profiles.rs
+++ b/crates/waybetter-host/src/profiles.rs
@@ -241,19 +241,19 @@ mod tests {
}
fn account(handle: &str) -> Account {
- Account { handle: handle.into(), name: "Fishies".into(), avatar: Some("https://pbs.twimg.com/profile_images/1/a_normal.jpg".into()), signed_in: false }
+ Account { handle: handle.into(), name: "Sample".into(), avatar: Some("https://pbs.twimg.com/profile_images/1/a_normal.jpg".into()), signed_in: false }
}
#[test]
fn a_seen_login_names_the_profile_and_persists_a_sign_out() {
let mut settings = ProfileSettings { profiles: vec![profile("default"), profile("p1")], active: "default".into() };
- assert!(settings.observe("p1", AccountSeen::SignedIn(account("@playfishies")), RULES));
+ assert!(settings.observe("p1", AccountSeen::SignedIn(account("@otheraccount")), RULES));
let seen = settings.profiles[1].account.clone().unwrap();
- assert_eq!((seen.handle.as_str(), seen.signed_in, settings.profiles[1].name.as_str()), ("playfishies", true, "Fishies"));
+ assert_eq!((seen.handle.as_str(), seen.signed_in, settings.profiles[1].name.as_str()), ("otheraccount", true, "Sample"));
// The same report again changes nothing (no disk write).
- assert!(!settings.observe("p1", AccountSeen::SignedIn(account("playfishies")), RULES));
+ assert!(!settings.observe("p1", AccountSeen::SignedIn(account("otheraccount")), RULES));
assert!(settings.observe("p1", AccountSeen::SignedOut, RULES));
- assert_eq!(settings.profiles[1].account.as_ref().map(|a| (a.handle.as_str(), a.signed_in)), Some(("playfishies", false)));
+ assert_eq!(settings.profiles[1].account.as_ref().map(|a| (a.handle.as_str(), a.signed_in)), Some(("otheraccount", false)));
assert!(!settings.observe("nope", AccountSeen::SignedOut, RULES));
}
@@ -266,7 +266,7 @@ mod tests {
bare.avatar = None;
settings.observe("default", AccountSeen::SignedIn(bare), RULES);
let kept = settings.profiles[0].account.clone().unwrap();
- assert_eq!((kept.name.as_str(), kept.avatar.is_some()), ("Fishies", true));
+ assert_eq!((kept.name.as_str(), kept.avatar.is_some()), ("Sample", true));
}
#[test]
@@ -284,12 +284,12 @@ mod tests {
#[test]
fn a_shell_save_keeps_the_native_accounts() {
let mut current = ProfileSettings { profiles: vec![profile("default"), profile("p1")], active: "default".into() };
- current.observe("p1", AccountSeen::SignedIn(account("playfishies")), RULES);
+ current.observe("p1", AccountSeen::SignedIn(account("otheraccount")), RULES);
let mut incoming = ProfileSettings { profiles: vec![profile("default"), profile("p1")], active: "p1".into() };
incoming.profiles[0].account = Some(account("forged"));
let kept = incoming.keep_accounts_from(¤t);
assert_eq!(kept.profiles[0].account, None);
- assert_eq!(kept.profiles[1].account.as_ref().map(|a| a.handle.as_str()), Some("playfishies"));
+ assert_eq!(kept.profiles[1].account.as_ref().map(|a| a.handle.as_str()), Some("otheraccount"));
}
#[test]
diff --git a/packages/shell/src/panel/make.css b/packages/shell/src/panel/make.css
index 2a25c1b..04d3142 100644
--- a/packages/shell/src/panel/make.css
+++ b/packages/shell/src/panel/make.css
@@ -4,10 +4,11 @@
.bmk-intro p { margin: 0 0 10px; max-width: 70ch; line-height: 1.55; }
.bmk-muted, .bmk-intro .bmk-muted { color: var(--c-muted); font-size: 12px; }
.bmk-commands { display: grid; gap: 6px; margin: 0 0 10px; padding: 0; list-style: none; }
-.bmk-commands li { display: grid; grid-template-columns: minmax(120px, 190px) 1fr auto; align-items: center; gap: 10px; padding-block: 6px; padding-inline: 12px 6px; border: 1px solid var(--c-line-soft); border-radius: calc(10px * var(--bt-rs, 1)); background: var(--c-card); }
+.bmk-commands li { display: grid; grid-template-columns: minmax(120px, 190px) minmax(0, 1fr) auto; align-items: center; gap: 10px; padding-block: 6px; padding-inline: 12px 6px; border: 1px solid var(--c-line-soft); border-radius: calc(10px * var(--bt-rs, 1)); background: var(--c-card); }
.bmk-commands li > span { color: var(--c-muted); font-size: 12px; }
-.bmk-commands li > code { overflow-x: auto; white-space: nowrap; background: transparent; border: 0; padding: 0; color: var(--c-text); scrollbar-width: none; }
-@container panel (max-width: 560px) { .bmk-commands li { grid-template-columns: 1fr auto; } .bmk-commands li > span { grid-column: 1 / -1; } }
+/* The whole command stays visible: it wraps (a hidden scrollbar used to cut it off with no sign more was there). */
+.bmk-commands li > code { min-width: 0; white-space: pre-wrap; overflow-wrap: anywhere; background: transparent; border: 0; padding: 0; color: var(--c-text); }
+@container panel (max-width: 560px) { .bmk-commands li { grid-template-columns: minmax(0, 1fr) auto; } .bmk-commands li > span { grid-column: 1 / -1; } }
.bmk-tabs { margin: 0 2px 16px; }
.bmk-doc-link { display: inline; padding: 0; border: 0; background: none; color: var(--c-accent); font: inherit; cursor: pointer; text-decoration: underline; text-decoration-color: rgb(var(--c-accent-rgb) / .35); text-underline-offset: 2px; }
.bmk-doc-link:hover { text-decoration-color: currentColor; }
diff --git a/tools/readme-term-shots.mjs b/tools/readme-term-shots.mjs
new file mode 100644
index 0000000..6a4ee43
--- /dev/null
+++ b/tools/readme-term-shots.mjs
@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Terminal shots for the README: runs real `create-waybetter` commands in a throwaway folder and saves, per shot,
+// assets/readme/term/.txt the cleaned output (first line "$ ", no ANSI, temp paths made short)
+// assets/readme/term/.webp that text drawn as a terminal (dark), rendered by headless Google Chrome and
+// encoded with cwebp (the smaller of lossy q80 and lossless)
+// Fails when a command exits non-zero, its output lacks its expected marker, or Chrome / cwebp hang.
+// node tools/readme-term-shots.mjs all shots
+// node tools/readme-term-shots.mjs --text only the .txt files (no browser)
+// node tools/readme-term-shots.mjs app only these shots
+// Needs Google Chrome (or CHROME=) and cwebp on PATH for the images.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const CLI = join(ROOT, 'packages', 'create-waybetter', 'bin', 'create-waybetter.js');
+const OUT = join(ROOT, 'assets', 'readme', 'term');
+const CHROME = process.env.CHROME || '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+const TIMEOUT_MS = 60_000;
+const log = m => console.log(`${new Date().toISOString().slice(11, 19)} [term-shots] ${m}`);
+
+const SHOTS = [
+ { name: 'create-app', title: 'npm create waybetter', marker: 'Created a wayBetter app',
+ shown: 'npm create waybetter app kickapp -- --site kick.com --name "wayBetter for Kick" --yes',
+ argv: ['app', 'kickapp', '--site', 'kick.com', '--name', 'wayBetter for Kick', '--yes'] },
+ { name: 'create-plugin', title: 'npm create waybetter', marker: 'hide-trends',
+ shown: 'npm create waybetter plugin -- --name "Hide Trends"',
+ argv: ['plugin', '--name', 'Hide Trends'] },
+];
+
+const esc = s => s.replace(/&/g, '&').replace(//g, '>');
+function lineHtml(l) {
+ if (l.startsWith('$ ')) return `$${esc(l.slice(2))}`;
+ let h = esc(l);
+ h = h.replace(/\b(error|ERROR|failed)\b/g, m => `${m}`);
+ h = h.replace(/^(\s*)(Created|Wrote)\b/, (m, a, b) => `${a}${b}`);
+ h = h.replace(/^(\s{2,})(cd |npm |git |then )/, (m, a, b) => `${a}${b}`);
+ return h;
+}
+const page = (title, lines) => `