waybetter 0.5.0: docs for the host's page commands, the runtime composition, the i18n command and dev-tools

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
CRTkafa 2026-09-30 14:48:06 +07:00
parent 4eecc0ffe0
commit 75c8ad7482
5 changed files with 70 additions and 11 deletions

View file

@ -72,6 +72,8 @@ crates/waybetter-host/ Rust: security policy, profiles, plugin store, hotfi
src/profiles.rs profiles, per-profile data dirs, native-owned accounts src/profiles.rs profiles, per-profile data dirs, native-owned accounts
src/plugins.rs *.plugin.js store, custom CSS, bundled-plugin upgrades 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/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/hotfix.rs signed data-only hotfix channel (minisign)
src/update.rs silent-update scheduling and crash handshake src/update.rs silent-update scheduling and crash handshake
src/tabs.rs TabLayout/TabState/OpenRequest, link modes, shortcut and drag validation, src/tabs.rs TabLayout/TabState/OpenRequest, link modes, shortcut and drag validation,
@ -92,6 +94,7 @@ crates/waybetter-host/ Rust: security policy, profiles, plugin store, hotfi
src/host.rs (feature "tauri") webview helpers, shell events, system menu 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, 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 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/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 src/testkit.rs capability/caller-check assertions for an app's tests/security.rs
packages/runtime/src/ page runtime core (TypeScript, no dependencies) packages/runtime/src/ page runtime core (TypeScript, no dependencies)
@ -105,6 +108,11 @@ packages/runtime/src/ page runtime core (TypeScript, no dependencies)
column.ts deck columns: hide site chrome, fill the width, filters, unread count 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 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 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
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) packages/shell/src/ shell core (TypeScript) and the shell frame (React)
addressModel.ts address bar chips (site pages named by the adapter) addressModel.ts address bar chips (site pages named by the adapter)
paneModel.ts beside-pane reuse, redundant rails, navRedundant for tabs_sync paneModel.ts beside-pane reuse, redundant rails, navRedundant for tabs_sync
@ -119,9 +127,15 @@ packages/shell/src/ shell core (TypeScript) and the shell frame (React)
installController.ts the install screen's state machine (links, drops, store items, confirm) 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) 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) 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, 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` and store-catalog.schema.json, the `waybetter store build|sign|verify`,
`waybetter release windows|macos` commands, `waybetter/build`) `waybetter release windows|macos` and `waybetter i18n check|extract`
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 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) packages/create-waybetter/ `npm create waybetter`: plugin, theme and app scaffolds (no dependencies)
``` ```
@ -311,15 +325,27 @@ Each runtime module takes only its piece (`installPaneNav(window, KICK.rail!)`,
`installLinkRouting(window, KICK.links!)`, `installAccountReport(window, KICK.account!, invoke)`, `installLinkRouting(window, KICK.links!)`, `installAccountReport(window, KICK.account!, invoke)`,
`createCorePluginApi(window, KICK.plugins)`), so a site without a rail simply does not install it. `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) ### 3. Capabilities (Tauri JSON, keyed by webview label)
The security model is the same for every app and must stay keyed by webview label: The security model is the same for every app and must stay keyed by webview label:
| webview | may call | | webview | may call |
| --- | --- | | --- | --- |
| `shell` (local assets only) | app, settings, vault, and the host's `commands::SHELL` (`tabs_sync`, `tab_navigate`, `tab_action`, `shell_raise`, `profiles_*`, `i18n_*`, ...) | | `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-*` (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 | | `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 | | other local webviews (`popover-*`, ...) | their own narrow capability |
```json ```json
@ -341,7 +367,8 @@ 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 `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, 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_no_plugin_apis` refuses `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 Tauri plugin JS APIs, and `assert_guarded` / `assert_host_guards` check that each command's first
statement checks its caller. statement checks its caller.
@ -356,8 +383,15 @@ statement checks its caller.
webview (transparent: it can rise above the tabs; macOS needs the `macos-private-api` feature). 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`, 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`, `shell_focus`, `shell_ready`, `tab_still_ready`, `shell_raise`, `window_system_menu`, `profiles_get`/`profiles_set`,
`i18n_get`/`i18n_set`) and `commands::TAB` (`tab_shortcut`, `tab_link_drag`), each checking its `i18n_get`/`i18n_set`, `plugins_list`, `plugin_set_enabled`, `plugins_open_folder`,
caller first, and dispatches every other command to the app's handler. Tab webviews get their `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 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 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: scripts, legacy domains, link routing, per-tab state, what a finished site page gets). Helpers:
@ -367,7 +401,10 @@ statement checks its caller.
`AppConfig::defer_window_show = true` and `ShellSite.deferWindowShow = true`, and grant the `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 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. shows it after initial `tabs_sync`, with a three-second fallback if shell startup fails.
- `commands`: the host's command list and `manifest(&[..])` for the app's `build.rs`. - `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. - `testkit`: see the capabilities section.
- `policy`: `SHELL_LABEL`, `tab_id`, `require_local`, `require_site_tab`, `clamp_tab_rect` (tabs never - `policy`: `SHELL_LABEL`, `tab_id`, `require_local`, `require_site_tab`, `clamp_tab_rect` (tabs never
cover the titlebar or, while restored, the resize band). cover the titlebar or, while restored, the resize band).
@ -420,6 +457,16 @@ The npm package adds the app-side tooling:
`<outDir>/upload`, `latest.json` (other platforms of the version kept); macOS: signs a universal `<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. 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. The key is read only into the build's environment or handed to the Tauri signer by path.
- `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 - `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 (`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 the Desktop and Start menu shortcuts and opens the app. Run again by hand, it only installs when
@ -460,6 +507,11 @@ 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 check:tauri # cargo check with the app feature (slow: builds Tauri and its plugins)
bun run build # typecheck + cargo build bun run build # typecheck + cargo build
bun run pack:check # npm pack --dry-run of waybetter and create-waybetter 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+. Requires Bun 1.4.2+, Node 24+ and Rust 1.88+.

View file

@ -30,7 +30,7 @@
}, },
"packages/waybetter": { "packages/waybetter": {
"name": "waybetter", "name": "waybetter",
"version": "0.4.0", "version": "0.5.0",
"bin": { "bin": {
"waybetter": "bin/waybetter.mjs", "waybetter": "bin/waybetter.mjs",
}, },

View file

@ -1153,7 +1153,7 @@ export function appFiles(o) {
release: 'waybetter release windows', release: 'waybetter release windows',
'release:macos': 'waybetter release macos', 'release:macos': 'waybetter release macos',
}, },
dependencies: { dockview: '^4.0.0', react: '^19.0.0', 'react-dom': '^19.0.0', waybetter: '^0.4.0' }, dependencies: { dockview: '^4.0.0', react: '^19.0.0', 'react-dom': '^19.0.0', waybetter: '^0.5.0' },
devDependencies: { '@tauri-apps/cli': '^2.0.0', '@types/react': '^19.0.0', '@types/react-dom': '^19.0.0', esbuild: '^0.25.0', typescript: '^5.9.0' }, devDependencies: { '@tauri-apps/cli': '^2.0.0', '@types/react': '^19.0.0', '@types/react-dom': '^19.0.0', esbuild: '^0.25.0', typescript: '^5.9.0' },
}; };
const tsconfig = { const tsconfig = {

View file

@ -50,6 +50,10 @@ pieces. The source comments document each module's contract.
**Runtime** **Runtime**
- `accountReport`: reports the signed-in account seen in the page's own UI. - `accountReport`: reports the signed-in account seen in the page's own UI.
- `siteRuntime`: composes a runtime entry: `pageInvoke`, `createFeatureFlags` (flag-controlled parts, a deck column's overrides), `installSiteRuntime` (the runtime object under `window.wayBetter` and the app's names, the members native code calls, queued native deliveries, the palette command report).
- `pageStrings`: the page's language (English built in; native deliveries are checked as data).
- `panelButton`: the way into the app's panel from the page: the adapter's navigation entry, or a floating button.
- `commandReport`: reports plugin palette commands to the shell; developer-mode start errors.
- `column`: a site tab as a narrow deck column: hides the site's chrome, lets its content fill the width, per-column filters (keywords, `/regex/`, replies, reposts, media only) and an unread count from what the site rendered. Makes no requests. - `column`: a site tab as a narrow deck column: hides the site's chrome, lets its content fill the width, per-column filters (keywords, `/regex/`, replies, reposts, media only) and an unread count from what the site rendered. Makes no requests.
- `domHub`: one `MutationObserver` and one animation frame shared by every DOM feature. - `domHub`: one `MutationObserver` and one animation frame shared by every DOM feature.
- `linkRouting`: routes clicks on the app's own links per the "links to app pages" setting. - `linkRouting`: routes clicks on the app's own links per the "links to app pages" setting.
@ -108,6 +112,8 @@ const Shell = createShell({ ...site, panel: { id: 'app', title: 'wayBetter', com
- `waybetter store build --config store.config.mjs`: builds an app's part of the shared store folder (its items only, validated with the apps' own rules). - `waybetter store build --config store.config.mjs`: builds an app's part of the shared store folder (its items only, validated with the apps' own rules).
- `waybetter store sign [--init] --key <private key>` / `waybetter store verify --pub <key file>`: Ed25519 signature over the exact catalog bytes; any listed public key verifies (rotation). The private key is never printed or copied. - `waybetter store sign [--init] --key <private key>` / `waybetter store verify --pub <key file>`: Ed25519 signature over the exact catalog bytes; any listed public key verifies (rotation). The private key is never printed or copied.
- `waybetter i18n check [--write] [--verbose] [locale…]`: checks an app's catalogs (and the framework's in the same languages) with the `waybetter/i18n/check` rules, bundled plugins' inline English and the generated files; `--write` regenerates `languages.json` and the native localization files (macOS, Linux). `waybetter i18n extract [--missing]`: keys the code looks up that English lacks, and English keys without a literal lookup. Both read `waybetter.i18n.json` in the app's root (`locales`, `sources`, `nativeSources`, `bundledPlugins`, `runtimeKeys`, `native`).
- `windows/languages/<Language>.nsh`: the Windows installer's messages for the languages Tauri does not ship, next to the installer template (`windows/installer.nsi`).
## Plugin UI kit (`runtime/ui`) ## Plugin UI kit (`runtime/ui`)

View file

@ -1,6 +1,6 @@
{ {
"name": "waybetter", "name": "waybetter",
"version": "0.4.0", "version": "0.5.0",
"license": "GPL-3.0-or-later", "license": "GPL-3.0-or-later",
"type": "module", "type": "module",
"description": "wayBetter: the framework for apps that run the apps you already use in a light native (Tauri) window and extend them in place. Page runtime (DOM/request hubs, plugins, plugin UI kit with themed dialogs and toasts, theme API and theme JSON Schema, theme color model, link routing, account reporting, deck columns, i18n: ICU-lite messages, locale fallback, plugin strings, catalog checks and JSON Schemas), shell models (address bar, panes, decks, profiles, palette, updates), the shell frame (createShell: tabs, splits, address bar, titlebar, palette, account switcher, decks, workspaces, overlays, the language state; React + dockview peers), the panel (createPanel: an app's own tab with Appearance and the Theme Builder, plugins and custom CSS, the Store, Make, accounts, settings, backup and sync, developer mode, updates; the app adds its sections) and the Store: install screen and Store view React components (optional React peer), their state and catalog models, the store catalog JSON Schema and the `waybetter store build|sign|verify` command, `waybetter release windows|macos` (signed native releases and the update manifest, configured by waybetter.release.json) and `waybetter/build` (the page runtime bundle, with an optional esbuild peer). No dependencies.", "description": "wayBetter: the framework for apps that run the apps you already use in a light native (Tauri) window and extend them in place. Page runtime (DOM/request hubs, plugins, plugin UI kit with themed dialogs and toasts, theme API and theme JSON Schema, theme color model, link routing, account reporting, deck columns, i18n: ICU-lite messages, locale fallback, plugin strings, catalog checks and JSON Schemas), shell models (address bar, panes, decks, profiles, palette, updates), the shell frame (createShell: tabs, splits, address bar, titlebar, palette, account switcher, decks, workspaces, overlays, the language state; React + dockview peers), the panel (createPanel: an app's own tab with Appearance and the Theme Builder, plugins and custom CSS, the Store, Make, accounts, settings, backup and sync, developer mode, updates; the app adds its sections) and the Store: install screen and Store view React components (optional React peer), their state and catalog models, the store catalog JSON Schema and the `waybetter store build|sign|verify` command, `waybetter release windows|macos` (signed native releases and the update manifest, configured by waybetter.release.json) and `waybetter/build` (the page runtime bundle, with an optional esbuild peer). No dependencies.",
@ -186,6 +186,7 @@
"./store-catalog.schema.json": "./store-catalog.schema.json", "./store-catalog.schema.json": "./store-catalog.schema.json",
"./cli/store": "./cli/store.mjs", "./cli/store": "./cli/store.mjs",
"./cli/release": "./cli/release.mjs", "./cli/release": "./cli/release.mjs",
"./cli/i18n": "./cli/i18n.mjs",
"./build": "./build/runtime.mjs", "./build": "./build/runtime.mjs",
"./package.json": "./package.json" "./package.json": "./package.json"
}, },