docs: run_app, commands/testkit, waybetter release and waybetter/build

This commit is contained in:
CRTkafa 2026-09-29 11:51:25 +07:00
parent 6eb1dd496a
commit af1b240179

View file

@ -50,8 +50,10 @@ npm create waybetter app -- --site kick.com # a whole app: Tauri 2 + waybetter
`create-waybetter` (in `packages/create-waybetter`) asks for what it needs in a terminal, and `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 takes every answer as a flag (`--help`). The app skeleton is this README in code: the native
`SiteSpec`, the page `SiteAdapter`, the three capability files, a shell that reports the tab `SiteSpec`, the page `SiteAdapter`, the app on `waybetter_host::app` (its config, site hooks and
rectangle (`tabs_sync`), the plugin store and one site-only command, with presets for its own commands), the three capability files and a `tests/security.rs` on `waybetter_host::testkit`,
a shell that reports the tab rectangle (`tabs_sync`), 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 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 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 `plugins::parse_meta`, plugin code against `createCorePluginApi`'s members, themes against
@ -87,6 +89,10 @@ crates/waybetter-host/ Rust: security policy, profiles, plugin store, hotfi
src/store/ install links, download allow-list, signed multi-app store catalog, staging src/store/ install links, download allow-list, signed multi-app store catalog, staging
and installs; downloads with feature "net" (docs/STORE.md) and installs; downloads with feature "net" (docs/STORE.md)
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,
SiteHooks, the window, shell and tab webviews, the generic commands
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) packages/runtime/src/ page runtime core (TypeScript, no dependencies)
site.ts SiteAdapter (the page half of the adapter) + configureRuntime site.ts SiteAdapter (the page half of the adapter) + configureRuntime
domHub.ts netHub.ts one MutationObserver/frame, one fetch/XHR hook per page domHub.ts netHub.ts one MutationObserver/frame, one fetch/XHR hook per page
@ -112,7 +118,8 @@ packages/shell/src/ shell core (TypeScript, no dependencies)
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)
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` command) store-catalog.schema.json, the `waybetter store build|sign|verify` and
`waybetter release windows|macos` commands, `waybetter/build`)
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)
``` ```
@ -186,7 +193,7 @@ The security model is the same for every app and must stay keyed by webview labe
| webview | may call | | webview | may call |
| --- | --- | | --- | --- |
| `shell` (local assets only) | app, settings, vault, tab management (`tabs_sync`, `tab_navigate`, `tab_action`, ...) | | `shell` (local assets only) | app, settings, vault, and the host's `commands::SHELL` (`tabs_sync`, `tab_navigate`, `tab_action`, `shell_raise`, `profiles_*`, `i18n_*`, ...) |
| `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 |
| other local webviews (`popover-*`, ...) | their own narrow capability | | other local webviews (`popover-*`, ...) | their own narrow capability |
@ -208,8 +215,32 @@ caller's label, the webview's own URL (never the page's claim), payload bounds.
about itself; the account it reports is recorded only for its own profile, only while it is on the 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`). 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_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 ## 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_raise`, `window_system_menu`, `profiles_get`/`profiles_set`,
`i18n_get`/`i18n_set`) and `commands::TAB` (`tab_shortcut`, `tab_link_drag`), each checking its
caller first, and dispatches every other command to the app's handler. 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`.
- `commands`: the host's command list and `manifest(&[..])` for the app's `build.rs`.
- `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).
- `profiles`: `ProfileSettings` (validated, default profile required, profiles with open tabs cannot be - `profiles`: `ProfileSettings` (validated, default profile required, profiles with open tabs cannot be
@ -247,15 +278,28 @@ site, and a shell save can never change it (`ProfileSettings::keep_accounts_from
`read_json`/`write_json`, `remove_profile_dirs`, `prune_profile_dirs`, `migrate_identifier`, `read_json`/`write_json`, `remove_profile_dirs`, `prune_profile_dirs`, `migrate_identifier`,
`system_menu`. `system_menu`.
The app keeps its own `#[tauri::command]` wrappers, so IPC command names, the build-time command The app keeps its own `#[tauri::command]` wrappers for everything else, and its capability files;
manifest and the capability files stay in the app. 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.
## Consuming it ## Consuming it
wayBetter for X adds this repository as a git submodule at `waybetter/` and consumes it from source: 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" }`, - Rust: a path dependency, `waybetter-host = { path = "../../../waybetter/crates/waybetter-host" }`,
with `features = ["tauri", "net"]` enabled by the app's desktop feature. 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` from a few adapter modules. The - TypeScript: relative imports of `waybetter/packages/*/src/*.ts` from a few adapter modules. The
packages are not Bun workspace members of the app on purpose: the app's server CI clones without 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 submodules and runs `bun i`, which fails when a declared workspace package is missing; and Node's
@ -273,7 +317,7 @@ bun run test:rust
bun run test:create # scaffolds into temp dirs; its cargo check of an app is ~1 min cold 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) # (WAYBETTER_SKIP_CARGO_CHECK=1 skips it; needs the local crate cache)
bun run check # typecheck + build:packages + test bun run check # typecheck + build:packages + test
bun run check:tauri # cargo check with the tauri feature (slow: builds Tauri) 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
``` ```