waybetter 0.1.1 → 0.6.0

package/README.md

@@ -4,14 +4,31 @@ 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
 heavy Electron client alike: every wayBetter app is the same shell, runtime and one small adapter.
 
+This package is the TypeScript half and the command line. The native half is the Rust crate
+`waybetter-host`, which is not on npm: an app takes it from the
+[repository](https://git.crt.fyi/CRT/waybetter) as a git submodule or a path dependency. The
+repository README explains how the three layers fit together and shows a minimal adapter;
+`docs/ARCHITECTURE.md` there lists every module.
+
 - **`waybetter/runtime/*`**: the page runtime. One DOM-mutation/animation-frame hub, one
-  fetch/XHR hub, a plugin API core, an OKLab theme color model, split-pane rail hiding, link
-  routing and account change reporting.
+  fetch/XHR hub, a plugin API core with a themed UI kit (toasts, alerts, confirmations, prompts,
+  dialogs), a theme API, an OKLab theme color model, split-pane rail hiding, link routing and
+  account change reporting.
+- **`waybetter/theme.schema.json`**: the JSON Schema of wayBetter theme files.
 - **`waybetter/shell/*`**: pure models for the app chrome around the pages: address bar chips,
   dock/split-pane rules, dragged links, account profiles, the update chip, command palette
   ranking and window controls. The Tauri window API is passed in by the caller, never imported.
-
-Plain ESM with `.d.ts` types. Zero dependencies.
+  And the wayBetter Store: the install screen and the Store view as React components (React is an
+  optional peer; everything else has no dependencies), their controller and models.
+- **`waybetter/shell/frame`**: the whole shell of an app, `createShell(site, { native, i18n })`:
+  tabs in the titlebar, split panes, the smart address bar, the new-tab page, the command palette,
+  the account switcher, decks of site columns, workspaces, pane themes, overlays and the native
+  layout sync. The app describes its site (pages, address chips, palette items, column kinds, its
+  own panel tab); React, React DOM and dockview are optional peers, the Tauri API is passed in.
+- **`waybetter store build|sign|verify`** and **`waybetter/store-catalog.schema.json`**: the tooling
+  and JSON Schema of the shared, signed wayBetter Store catalog.
+
+Plain ESM with `.d.ts` types. Zero dependencies (the React parts use your React; the shell frame also dockview).
 
 ## Install
 
@@ -39,30 +56,147 @@ pieces. The source comments document each module's contract.
 **Runtime**
 
 - `accountReport`: reports the signed-in account seen in the page's own UI.
+- `siteRuntime`: composes a runtime entry: `pageInvoke`, `createFeatureFlags` (flag-controlled parts, a deck column's overrides), `installSiteRuntime` (the runtime object under `window.wayBetter` and the app's names, the members native code calls, queued native deliveries, the palette command report).
+- `pageStrings`: the page's language (English built in; native deliveries are checked as data).
+- `panelButton`: the way into the app's panel from the page: the adapter's navigation entry, or a floating button.
+- `commandReport`: reports plugin palette commands to the shell; developer-mode start errors.
+- `column`: a site tab as a narrow deck column: hides the site's chrome, lets its content fill the width, per-column filters (keywords, `/regex/`, replies, reposts, media only) and an unread count from what the site rendered. Makes no requests.
 - `domHub`: one `MutationObserver` and one animation frame shared by every DOM feature.
 - `linkRouting`: routes clicks on the app's own links per the "links to app pages" setting.
 - `netHub`: one shared fetch/XHR hook for URL rewrites, gates and passive JSON taps.
 - `paneNav`: hides a redundant navigation rail when two panes show the same account.
-- `pluginApi`: small helpers shared by user JS plugins.
+- `pluginApi`: small helpers shared by user JS plugins, including `ui` and `theme`.
 - `site`: the page-side composition root for an adapter.
+- `themeApi`: the active theme as values (`ResolvedTheme`), `--wb-*` CSS variables, contrast helpers.
 - `themeTokens`: the OKLab color model themes are built on.
+- `ui`: the plugin UI kit (see below).
 
 **Shell**
 
 - `addressModel`: `parseAddress(url, site)` for the address bar's breadcrumb chips.
 - `chrome`: layout constants for the custom titlebar and toolbar.
+- `deckModel`: decks of site columns (TweetDeck-style): bounded model, paging layout (whole columns per page, parked off-page columns), focus moves, unread totals.
 - `linkDrop`: a dragged link dropped into the dock opens as a tab or split pane.
 - `palette`: command palette fuzzy scoring, ranking and selection movement.
 - `paneModel`: pane geometry: where a "beside" link opens, which panes keep the rail.
 - `profileModel`: the account profile model.
 - `updateModel`: the titlebar update chip model.
 - `windowControls`: native window calls for the titlebar, resize grips and caption buttons.
+- `storeModel`, `storeMessages`: Store wire types, item states (install, update, changed locally, built in), permission badges, search; the English of every `wb.store.*`, `wb.install.*`, `wb.permission.*` message (translations in `waybetter/locales/*.json`).
+- `installController`: the install screen's state (install links, dropped files, store items, confirm), given the app's native bridge and theme adapter.
+- `InstallDialog` (`InstallHost`), `StoreView`, `store.css`: the install screen, the window drop target and the Store view, themed with `--wb-*` tokens. See docs/STORE.md in the repository.
+
+**Shell frame** (`waybetter/shell/frame`, modules also as `waybetter/shell/frame/*`, styles as `waybetter/shell/frame/*.css`)
+
+```tsx
+import { createShell, type ShellSite } from 'waybetter/shell/frame';
+const Shell = createShell(site, { native: { invoke, listen, currentWindow: getCurrentWindow }, i18n });
+createRoot(document.getElementById('root')!).render(<Shell/>);
+```
+
+- `ShellSite` (`frame/site`): the site's names and pages, `address(url)` chips, slots for the app's panel tab, the new-tab page, palette items, deck column kinds, the media panel, themes (`createThemeStore`) and overlays, and the native `features` the app serves.
+- `i18n`: the app's `createI18n` instance with `waybetter/locales/*.json` merged in; the frame's words are `wb.*` messages in 51 languages.
+- `bootScript()` (`frame/boot`): the first-frame `boot.js` (the last theme's chrome colors before the modules load).
+- `installPreviewMocks(handlers)`: native commands answered from memory, for development previews in a plain browser.
+- `createLanguage(options)` (`frame/language`): which language the app speaks (follow the site, follow the system, or one language), switched live and handed to native code and site tabs (`i18n_set`); `createAppI18n(options)` (`frame/appI18n`): the app's i18n instance with typed keys, `useT`, dates and numbers.
+- Everything else is exported for apps that build their own settings on it: the shared state (`shell`, `setOverlay`, `scheduleSync`), stores (decks, workspaces, sync, developer mode), models (palette, accounts, workspaces, backup, media) and hooks.
+
+**Panel** (`waybetter/shell/panel`, modules also as `waybetter/shell/panel/*`, styles as `waybetter/shell/panel/*.css`)
+
+```tsx
+import { createPanel, type PanelSite } from 'waybetter/shell/panel';
+const Panel = createPanel({ brand: { name: 'wayBetter', logo }, home, themes, sections, make, languages });
+const Shell = createShell({ ...site, panel: { id: 'app', title: 'wayBetter', component: Panel } }, options);
+```
+
+- The app's own tab: home, Appearance and the Theme Builder (with the Google Fonts browser), plugins and custom CSS, the Store, Make, accounts, Power User, settings, backup and sync, developer mode, updates, and a search across every setting. Each section shows only when the app serves what it needs.
+- `PanelSite` (`panel/site`): the brand and the home page's words, the app's own `sections` and their `order`, `themes` (the theme store and catalog, the preview component a theme document is drawn in, the site font), `make` (example plugins, an example theme, bundled docs), `store`, `languages`, and what its native side serves (`settings.alerts`, `backup`, `updates`).
+- For the app's own sections: the panel's controls (`panel/controls`: `Section`, `Row`, `Toggle`, `Segmented`, `Select`, `Slider`, `ColorField`, `Button`, ...), `useFeatures` and `FeatureGroups` (`panel/FeatureToggles`: on/off rows over the host's `features_get/set`), `compareLines`.
+- The panel's words are `wb.*` messages in 51 languages (`waybetter/locales/*.json`; translator notes in `waybetter/locales/en.meta.json`).
+
+**Command line**
+
+- `waybetter store build --config store.config.mjs`: builds an app's part of the shared store folder (its items only, validated with the apps' own rules).
+- `waybetter store sign [--init] --key <private key>` / `waybetter store verify --pub <key file>`: Ed25519 signature over the exact catalog bytes; any listed public key verifies (rotation). The private key is never printed or copied.
+- `waybetter strings check <pack> [--inventory <file>] [--verbose]`: validates a string pack (data that replaces the wrapped site's own UI strings: `waybetter/runtime/stringPacks`, `waybetter/runtime/stringPackHook`, `waybetter/runtime/textNet`) against the site's string inventory and prints its coverage; the inventories otherwise come from `waybetter.strings.json` in the app's root.
+- `waybetter i18n check [--write] [--verbose] [locale…]`: checks an app's catalogs (and the framework's in the same languages) with the `waybetter/i18n/check` rules, bundled plugins' inline English and the generated files; `--write` regenerates `languages.json` and the native localization files (macOS, Linux). `waybetter i18n extract [--missing]`: keys the code looks up that English lacks, and English keys without a literal lookup. Both read `waybetter.i18n.json` in the app's root (`locales`, `sources`, `nativeSources`, `bundledPlugins`, `runtimeKeys`, `supported`, `native`; schema: `i18n-config.schema.json`). `supported` lists the languages in the supported tier; every other catalog gets `tier: "community"` in the generated `languages.json` (`languages.schema.json`), and an app resolves its automatic language choices only to supported ones (`createLanguage({ supported })`).
+- `waybetter release windows|macos`: signed native releases and the update manifest (`waybetter.release.json`). The Windows build runs path-free (below) and every artifact must pass the privacy scan before anything is copied or signed.
+- `waybetter build-env -- <command>`: runs a build (`tauri build`, `cargo build`) so the binary holds none of the machine's paths: the home folder, the workspace, `CARGO_HOME`, `RUSTUP_HOME` and `CARGO_TARGET_DIR` become `/home`, `/src`, `/cargo`, `/rustup` and `/target` (`--remap-path-prefix` appended to the flags already in `RUSTFLAGS`/`CARGO_ENCODED_RUSTFLAGS`, `/PDBALTPATH` on MSVC; for C and C++ a build script compiles, `-ffile-prefix-map` on gcc and clang and, on MSVC, `/d1trimfile:<root>` in `CL` and `/PDBALTPATH` in `LINK`, which reach the cc crate, CMake and MSBuild alike). Without a command it prints that environment (`--json`).
+- `waybetter privacy-scan <paths…> [--terms <file>] [--tracked] [--history]`: searches files, binaries (UTF-8 and UTF-16), archives (zip, tar, gzip, zstd, .deb, DMG; NSIS installers, AppImages and xz with 7-Zip or the matching tool), git-tracked files and a repository's whole history for forbidden terms: the lines of a file kept outside every repository (`--terms`, `WAYBETTER_FORBIDDEN_TERMS`, or `"forbiddenTerms"` in `waybetter.release.json`) plus this machine's account name. A name is a hit as a whole word in any case; a name of three characters or fewer only in a path or as the capitalized word. Output shows file and line or offset with the term masked (`m***`); exit 1 on a hit, 2 when a container could not be opened. Reviewed false positives: `"privacyAllowlist"`, lines of `<file glob>: <regex over the context, the term written <term>>`.
+- `windows/languages/<Language>.nsh`: the Windows installer's messages for the languages Tauri does not ship, next to the installer template (`windows/installer.nsi`).
+
+## Plugin UI kit (`runtime/ui`)
+
+Plugins get it as `api.ui` (and `scope.ui`, which closes whatever it opened on `scope.dispose()`).
+Everything is drawn in one Shadow DOM host, so the site's CSS cannot restyle it, and it takes its
+colors, corners and font from the active theme (`api.theme`), live.
+
+```js
+const ui = this.scope.ui;
+ui.toast('Link copied');                                   // tones: neutral, info, success, warning, danger
+ui.toast('Post hidden', { action: { label: 'Undo', onClick: undo } });
+await ui.alert({ title: 'Saved', message: 'Kept on this device only.', tone: 'success' });
+if (await ui.confirm({ title: 'Delete this note?', confirmLabel: 'Delete', danger: true })) remove();
+const name = await ui.prompt({ title: 'Rename', value: 'Reading', validate: v => v.trim() ? null : 'Required' });
+const dialog = ui.dialog({
+  title: 'Settings',
+  content: body => body.append(ui.h('label', { class: 'wb-check' }, ui.h('input', { type: 'checkbox' }), 'Hide trends')),
+  actions: [{ label: 'Cancel' }, { label: 'Save', tone: 'primary', default: true, onClick: save }],
+});
+```
+
+- `modal(options)` is the primitive under all of them; `dialog` is a `role="dialog"`, `alert` /
+  `confirm` are `role="alertdialog"`. All are `aria-modal`, labelled by their title and described
+  by their message.
+- Focus moves in, Tab/Shift+Tab wrap inside, and focus returns to where it was. Esc dismisses;
+  Enter in a single-line field (Ctrl/Cmd+Enter in a textarea) runs the `default` action. A
+  destructive `confirm` starts on Cancel.
+- Backdrop clicks dismiss alerts and confirmations only (a press that started in a field and ended
+  on the backdrop does not count). Keys typed in a dialog never reach the page's own shortcuts.
+- Dialogs stack (lower ones become `inert`); toasts stack (four at most), pause while hovered or
+  focused and are a polite live region (`role="alert"` for danger).
+- `prefers-reduced-motion` turns off the animations. Text is always set as text; `ui.h(tag,
+  props, ...children)` builds content without `innerHTML`, string handlers or `javascript:` URLs.
+- Classes for content: `wb-field`, `wb-label`, `wb-hint`, `wb-check`, `wb-input`, `wb-mono`,
+  `wb-divider`, `wb-row`, `wb-muted`; per-dialog CSS goes in `css`.
+
+`createUiKit(window, { theme })` builds a kit outside the plugin API; `theme` is a `ThemeApi` from
+`createThemeApi(window, source)`, where `source` is the site's `{ current(), onChange() }`.
+
+## Themes
+
+`api.theme.current()` returns the active theme resolved: `colors` (`bg`, `surface`, `elevated`,
+`border`, `text`, `muted`, `accent`, `onAccent`, `inverse`, `onInverse`, `page`), `radius`,
+`buttonRadius`, `font`, `mode` and `siteDefault` (true when the site's own colors show).
+`api.theme.onChange(fn)` fires after it changes. The same values are CSS custom properties on
+`:root` (`--wb-bg`, `--wb-text`, `--wb-accent`, `--wb-radius`, `--wb-font`, …), so plugin CSS can
+use `var(--wb-accent)`.
+
+Theme files are JSON; `theme.schema.json` describes every field and its limits (the app clamps
+out-of-range values when it imports a file). Point a theme at it for editor completion and checks:
+
+```json
+{ "$schema": "https://unpkg.com/waybetter/theme.schema.json", "name": "Midnight Mint", "colors": { "bg": "#0b1110", "text": "#e8f3ef", "accent": "#3ddc97" } }
+```
+
+or, in a project that installs the package, `"$schema": "./node_modules/waybetter/theme.schema.json"`.
+
+## Build your own
+
+```sh
+npm create waybetter plugin      # *.plugin.js (or --ts) using api.scope, storage, ui and theme
+npm create waybetter theme       # theme JSON with "$schema" pointing at theme.schema.json
+npm create waybetter app myapp -- --site youtube.com   # a new wayBetter app (Tauri 2 + waybetter-host)
+```
+
+[`create-waybetter`](https://www.npmjs.com/package/create-waybetter) generates code against this
+package's real API and schema; `--help` lists every option.
 
 ## Projects using wayBetter
 
 | Project | Target | What it is |
 | --- | --- | --- |
-| [wayBetter for X](https://waybetter.fyi/twttr/) | 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.
 

package/bin/waybetter.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// The `waybetter` command: `waybetter store build|sign|verify` (cli/store.mjs),
+// `waybetter release windows|macos|linux` (cli/release.mjs), `waybetter manifests` (cli/manifests.mjs), `waybetter i18n check|extract`
+// (cli/i18n.mjs), `waybetter privacy-scan` (cli/privacy.mjs) and `waybetter build-env`
+// (cli/buildenv.mjs), `waybetter dev` (cli/dev.mjs: watchers + tauri dev), `waybetter strings check`
+// (cli/strings.mjs).
+import { readFileSync } from 'node:fs';
+import { BUILD_ENV_USAGE, buildEnvCommand } from '../cli/buildenv.mjs';
+import { DEV_USAGE, devCommand } from '../cli/dev.mjs';
+import { MANIFESTS_USAGE, manifestsCommand } from '../cli/manifests.mjs';
+import { I18N_USAGE, i18nCommand } from '../cli/i18n.mjs';
+import { PRIVACY_USAGE, privacyCommand } from '../cli/privacy.mjs';
+import { STORE_USAGE, storeCommand } from '../cli/store.mjs';
+import { STRINGS_USAGE, stringsCommand } from '../cli/strings.mjs';
+import { RELEASE_USAGE, releaseCommand } from '../cli/release.mjs';
+
+const [area, ...rest] = process.argv.slice(2);
+try {
+  if (area === 'store') {
+    for (const line of await storeCommand(rest)) console.log(line);
+  } else if (area === 'release') {
+    await releaseCommand(rest);
+  } else if (area === 'manifests') {
+    process.exitCode = manifestsCommand(rest);
+  } else if (area === 'i18n') {
+    process.exitCode = await i18nCommand(rest);
+  } else if (area === 'strings') {
+    process.exitCode = await stringsCommand(rest);
+  } else if (area === 'privacy-scan') {
+    process.exitCode = privacyCommand(rest);
+  } else if (area === 'build-env') {
+    process.exitCode = buildEnvCommand(rest);
+  } else if (area === 'dev') {
+    process.exitCode = await devCommand(rest);
+  } else if (area === '--version' || area === '-v') {
+    console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+  } else {
+    console.log(`${STORE_USAGE}\n\n${RELEASE_USAGE}\n\n${MANIFESTS_USAGE}\n\n${I18N_USAGE}\n\n${STRINGS_USAGE}\n\n${PRIVACY_USAGE}\n\n${BUILD_ENV_USAGE}
+
+${DEV_USAGE}`);
+    if (area && area !== '--help' && area !== '-h') process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(`waybetter: ${error instanceof Error ? error.message : error}`);
+  process.exitCode = 1;
+}

package/build/runtime.mjs

@@ -0,0 +1,105 @@
+// `waybetter/build`: bundles an app's page runtime (or any script native code injects into site
+// tabs) into one self-contained IIFE with esbuild, the way every wayBetter app ships it:
+//
+//   import { buildRuntime } from 'waybetter/build';
+//   await buildRuntime({
+//     entry: 'src/inject/entry.tsx',
+//     outfile: 'src-tauri/x-runtime.js',
+//     catalog: 'locales/en.json',          // the app's English catalog ({ "messages": { ... } })
+//     prefixes: ['x.', 'plugin.'],          // only these strings are compiled in (others arrive natively)
+//     jsx: 'automatic',                     // any other esbuild option passes through
+//   });
+//
+// `watch: true` (an app's build script passes `watchRequested()`) keeps esbuild watching and
+// rebuilding `outfile`; a failed rebuild leaves the last good file in place.
+// - `?inline` CSS imports become strings (Vite semantics); other CSS side-effect imports are
+//   dropped, because injected UI adopts its stylesheet into a shadow root explicitly
+//   (`inlineCss: false` turns this off).
+// - Imports of `catalog` load only the keys starting with one of `prefixes`: the runtime ships
+//   English for its own strings; the owner's language arrives natively (i18n_set).
+// - esbuild is the app's own dependency (resolved from `cwd`, or pass `esbuild`).
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+/** The CSS plugin: `?inline` imports as text, other CSS imports dropped. */
+export const inlineCssPlugin = {
+  name: 'waybetter-css',
+  setup(api) {
+    api.onResolve({ filter: /\.css(\?inline)?$/ }, args => ({
+      path: path.resolve(args.resolveDir, args.path.replace(/\?inline$/, '')),
+      namespace: args.path.endsWith('?inline') ? 'css-inline' : 'css-drop',
+    }));
+    api.onLoad({ filter: /.*/, namespace: 'css-inline' }, async args => ({ contents: await readFile(args.path, 'utf8'), loader: 'text' }));
+    api.onLoad({ filter: /.*/, namespace: 'css-drop' }, () => ({ contents: '', loader: 'js' }));
+  },
+};
+
+/** The catalog plugin: `catalog` (absolute path) loads as `{ messages }` with only `prefixes` keys. */
+export function catalogPlugin(catalog, prefixes) {
+  const target = path.resolve(catalog);
+  return {
+    name: 'waybetter-strings',
+    setup(api) {
+      api.onLoad({ filter: /\.json$/ }, async args => {
+        if (path.resolve(args.path) !== target) return undefined;
+        const { messages = {} } = JSON.parse(await readFile(args.path, 'utf8'));
+        const kept = Object.fromEntries(Object.entries(messages).filter(([key]) => prefixes.some(prefix => key.startsWith(prefix))));
+        return { contents: JSON.stringify({ messages: kept }), loader: 'json' };
+      });
+    },
+  };
+}
+
+/**
+ * Builds `entry` into `outfile` (paths relative to `cwd`). Defaults: bundled IIFE, es2022,
+ * minified, no source map, no legal comments. Returns esbuild's result.
+ * @param {{ entry: string, outfile: string, watch?: boolean, catalog?: string, prefixes?: string[], cwd?: string,
+ *   inlineCss?: boolean, esbuild?: { build: Function }, plugins?: object[], [option: string]: unknown }} options
+ */
+export async function buildRuntime(options) {
+  const { entry, outfile, catalog, prefixes = [], cwd = process.cwd(), inlineCss = true, esbuild, plugins = [], watch = false, ...rest } = options;
+  if (!entry || !outfile) throw new Error('buildRuntime: entry and outfile are required');
+  if (catalog && !prefixes.length) throw new Error('buildRuntime: a catalog needs the key prefixes the runtime ships');
+  const bundler = esbuild ?? createRequire(path.join(path.resolve(cwd), 'package.json'))('esbuild');
+  const config = {
+    absWorkingDir: path.resolve(cwd),
+    entryPoints: [entry],
+    outfile,
+    bundle: true,
+    format: 'iife',
+    target: 'es2022',
+    minify: true,
+    sourcemap: false,
+    legalComments: 'none',
+    ...rest,
+    plugins: [
+      ...(inlineCss ? [inlineCssPlugin] : []),
+      ...(catalog ? [catalogPlugin(path.resolve(cwd, catalog), prefixes)] : []),
+      ...plugins,
+    ],
+  };
+  if (!watch) return bundler.build(config);
+  // Dev loop: rebuild `outfile` whenever a source changes (a debug host reloads its tabs when the
+  // file changes). The first build is done when this resolves; the returned context keeps watching.
+  const context = await bundler.context({
+    ...config,
+    plugins: [
+      ...config.plugins,
+      {
+        name: 'waybetter-watch-log',
+        setup(api) {
+          api.onEnd(result => {
+            const stamp = new Date().toTimeString().slice(0, 8);
+            console.log(result.errors.length ? `[${stamp}] ${outfile}: build failed, keeping the last good file` : `[${stamp}] rebuilt ${outfile}`);
+          });
+        },
+      },
+    ],
+  });
+  await context.watch();
+  return context;
+}
+
+/** True when the calling script was started with `--watch`. */
+export const watchRequested = (argv = process.argv) => argv.includes('--watch');

package/cli/buildenv.mjs

@@ -0,0 +1,130 @@
+// `waybetter build-env`: the environment of a path-free native build.
+//
+// A Rust binary embeds the absolute paths of its sources (panic locations, `file!()`, debug info):
+// the Cargo registry, the rustup toolchain and the workspace, which on a developer's machine all
+// hold the account name. This computes the flags that replace those roots with neutral ones
+//
+//   <home>          -> /home        <workspace root>   -> /src
+//   $CARGO_HOME     -> /cargo       $RUSTUP_HOME       -> /rustup     $CARGO_TARGET_DIR -> /target
+//
+// (`--remap-path-prefix`, added to CARGO_ENCODED_RUSTFLAGS after the flags RUSTFLAGS or
+// CARGO_ENCODED_RUSTFLAGS already hold), keeps the PDB's name but not its folder on MSVC
+// (`/PDBALTPATH:%_PDB%`) and gives C and C++ sources compiled by build scripts the same treatment:
+// `-ffile-prefix-map` in CFLAGS/CXXFLAGS on gcc and clang; on MSVC `/d1trimfile:<root>` in the CL
+// variable and `/PDBALTPATH:%_PDB%` in the LINK variable, which cl.exe and link.exe read themselves,
+// so the cc crate, CMake and MSBuild are all covered (`__FILE__` in a library a build script
+// compiles: there a root is cut off, not renamed, and the path stays relative).
+//
+//   waybetter build-env -- tauri build        run a command with that environment
+//   waybetter build-env [--json]              show it
+//
+// `waybetter release windows` builds with it. It is not a proof: `waybetter privacy-scan` is.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, posix, resolve, win32 } from 'node:path';
+
+export const BUILD_ENV_USAGE = `Usage:
+  waybetter build-env -- <command...>
+      Runs the command (tauri build, cargo build, ...) so the binary holds no build path: the home
+      folder, the workspace, CARGO_HOME, RUSTUP_HOME and CARGO_TARGET_DIR become /home, /src,
+      /cargo, /rustup and /target. Flags already in RUSTFLAGS or CARGO_ENCODED_RUSTFLAGS are kept.
+      C and C++ compiled by build scripts: -ffile-prefix-map (gcc, clang), /d1trimfile in CL (MSVC).
+  waybetter build-env [--json] [--root <dir>]
+      Prints that environment. The workspace root is --root, else the folder of the nearest
+      waybetter.release.json, else the git work tree, else the working directory.`;
+
+const SEPARATOR = '\x1f';
+
+/** The folder that stands for "the sources": config folder, else git work tree, else `cwd`. */
+export function workspaceRoot(cwd) {
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'waybetter.release.json'))) return dir;
+    if (dirname(dir) === dir) break;
+  }
+  const git = spawnSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', windowsHide: true });
+  return git.status === 0 && git.stdout.trim() ? resolve(git.stdout.trim()) : resolve(cwd);
+}
+
+/**
+ * The environment additions of a path-free build: `{ env, maps, notes }`. `env` holds only the
+ * variables to set (merge it over the process environment); `maps` lists [from, to].
+ */
+export function pathFreeBuildEnv({ root, env = process.env, platform = process.platform, home = homedir(), msvc = platform === 'win32' && !/gnu/.test(env.CARGO_BUILD_TARGET ?? '') } = {}) {
+  const path = platform === 'win32' ? win32 : posix;
+  const at = value => (platform === 'win32' ? value.replace(/[\\/]+$/, '') : value.replace(/\/+$/, '') || '/');
+  // General first: when several prefixes match, rustc applies the last one given.
+  const roots = [
+    [home, '/home'],
+    [root, '/src'],
+    [env.CARGO_TARGET_DIR && path.resolve(env.CARGO_TARGET_DIR), '/target'],
+    [env.CARGO_HOME || (home && path.join(home, '.cargo')), '/cargo'],
+    [env.RUSTUP_HOME || (home && path.join(home, '.rustup')), '/rustup'],
+  ].filter(([from]) => from).map(([from, to]) => [at(from), to]);
+  const maps = [];
+  for (const [from, to] of roots) {
+    maps.push([from, to]);
+    // Paths Windows hands out in verbatim form (canonicalized by build scripts and cargo).
+    if (platform === 'win32' && /^[A-Za-z]:/.test(from)) maps.push([`\\\\?\\${from}`, to]);
+  }
+
+  const notes = [];
+  const flags = env.CARGO_ENCODED_RUSTFLAGS ? env.CARGO_ENCODED_RUSTFLAGS.split(SEPARATOR) : (env.RUSTFLAGS ?? '').split(/\s+/).filter(Boolean);
+  const add = flag => { if (!flags.includes(flag)) flags.push(flag); };
+  for (const [from, to] of maps) add(`--remap-path-prefix=${from}=${to}`);
+  if (msvc) add('-Clink-arg=/PDBALTPATH:%_PDB%');
+  const out = { CARGO_ENCODED_RUSTFLAGS: flags.join(SEPARATOR) };
+
+  if (msvc) {
+    // cl.exe takes the first /d1trimfile prefix that matches (any case, either slash), so the
+    // longest root goes first. Quoted, and closed with a slash: a backslash would escape the quote.
+    const trims = roots.map(([from]) => from).filter(from => !from.includes('"')).sort((a, b) => b.length - a.length).map(from => `"/d1trimfile:${from}/"`);
+    out.CL = [...new Set([env.CL, ...trims])].filter(Boolean).join(' ');
+    // C and C++ linked with debug info (a CMake RelWithDebInfo library) name their PDB the same way.
+    out.LINK = [...new Set([env.LINK, '/PDBALTPATH:%_PDB%'])].filter(Boolean).join(' ');
+  } else {
+    // gcc and clang (cc crate: sqlite, ring and other bundled C). A flag cannot hold a space there.
+    const prefixMaps = maps.filter(([from]) => !/\s/.test(from)).map(([from, to]) => `-ffile-prefix-map=${from}=${to}`);
+    if (prefixMaps.length < maps.length) notes.push('a build path contains a space: C sources keep it (CFLAGS cannot express it)');
+    for (const name of ['CFLAGS', 'CXXFLAGS']) {
+      const current = (env[name] ?? '').split(/\s+/).filter(Boolean);
+      out[name] = [...current, ...prefixMaps.filter(flag => !current.includes(flag))].join(' ');
+    }
+  }
+  for (const dir of [root && join(root, '.cargo'), env.CARGO_HOME || (home && join(home, '.cargo'))]) {
+    for (const name of ['config.toml', 'config']) {
+      if (dir && existsSync(join(dir, name)) && !env.RUSTFLAGS && !env.CARGO_ENCODED_RUSTFLAGS) {
+        notes.push(`${name} in ${dir === root ? '<workspace>' : '<cargo home>'}/.cargo: rustflags set there are replaced by the environment's; copy them into RUSTFLAGS if the build needs them`);
+      }
+    }
+  }
+  return { env: out, maps, notes };
+}
+
+const quote = arg => (/^[A-Za-z0-9_@%+=:,./\\-]+$/.test(arg) ? arg : `"${arg.replaceAll('"', '\\"')}"`);
+
+/** `waybetter build-env ...`; returns the exit code. */
+export function buildEnvCommand(argv, { cwd = process.cwd(), env = process.env, log = console.log } = {}) {
+  const split = argv.indexOf('--');
+  const own = split >= 0 ? argv.slice(0, split) : argv;
+  const command = split >= 0 ? argv.slice(split + 1) : [];
+  if (own.includes('--help') || own.includes('-h')) { log(BUILD_ENV_USAGE); return 0; }
+  const rootAt = own.indexOf('--root');
+  const root = rootAt >= 0 && own[rootAt + 1] ? resolve(cwd, own[rootAt + 1]) : workspaceRoot(cwd);
+  const result = pathFreeBuildEnv({ root, env });
+  if (command.length) {
+    for (const note of result.notes) console.error(`waybetter build-env: ${note}`);
+    // The caller's own command line, run through the shell so .cmd shims (bun, tauri) resolve.
+    const run = spawnSync(command.map(quote).join(' '), { cwd, stdio: 'inherit', shell: true, env: { ...env, ...result.env } });
+    return run.status ?? 1;
+  }
+  if (own.includes('--json')) {
+    log(JSON.stringify(result.env, null, 2));
+    return 0;
+  }
+  log('Path-free build environment (waybetter build-env -- <command> runs a command with it):');
+  for (const [name, value] of Object.entries(result.env)) log(`  ${name}=${value.replaceAll(SEPARATOR, ' ')}`);
+  if (result.env.CARGO_ENCODED_RUSTFLAGS.includes(SEPARATOR)) log('  (CARGO_ENCODED_RUSTFLAGS separates its flags with the 0x1f character, shown as a space; --json has the exact value)');
+  for (const note of result.notes) log(`  note: ${note}`);
+  return 0;
+}

package/cli/dev.mjs

@@ -0,0 +1,97 @@
+// `waybetter dev`: the dev loop in one command. Starts the app's build watchers, waits until each
+// has built once, then runs `tauri dev`. In a debug build the host reads the page scripts from disk
+// and rebuilds its tabs when a watcher rewrites one (`waybetter_host::page_script!`), and the
+// shell hot-reloads through the frontend dev server (`beforeDevCommand`, e.g. vite).
+//
+//   waybetter dev [--stable] [--watch "<command>"]... [-- <tauri dev args>]
+//
+// `--stable` adds `--no-watch`: Rust changes do not restart the app (restart it yourself); page
+// script and shell changes still reload live. Every `--watch` command must keep running and print
+// a line containing "watching" once its first build is done (`buildRuntime({ watch: true })`
+// scripts print one); it is stopped with the app.
+import { spawn, spawnSync } from 'node:child_process';
+import { delimiter, join, resolve } from 'node:path';
+
+export const DEV_USAGE = `Usage:
+  waybetter dev [--stable] [--watch "<command>"]... [-- <tauri dev args>]
+      Starts each --watch command (esbuild watchers), waits for its first build ("watching" on a
+      line of its output, at most 120 s), then runs \`tauri dev\`. --stable passes --no-watch so a
+      Rust file saved by someone else does not restart the app; Rust changes then need a manual
+      restart, page-script and shell changes reload live either way.`;
+
+const READY = /watching/i;
+const READY_TIMEOUT_MS = 120_000;
+
+/** `waybetter dev` arguments: `{ stable, watch: string[], tauriArgs: string[] }`. */
+export function parseDevArgs(args) {
+  const out = { stable: false, watch: [], tauriArgs: [] };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--') {
+      out.tauriArgs = args.slice(index + 1);
+      break;
+    }
+    if (arg === '--stable') out.stable = true;
+    else if (arg === '--watch') {
+      const command = args[(index += 1)];
+      if (!command) throw new Error('--watch needs a command');
+      out.watch.push(command);
+    } else throw new Error(`unknown argument: ${arg}`);
+  }
+  return out;
+}
+
+/** The `tauri dev` arguments. */
+export function tauriDevArgs({ stable, tauriArgs }) {
+  return ['dev', ...(stable && !tauriArgs.includes('--no-watch') ? ['--no-watch'] : []), ...tauriArgs];
+}
+
+function stop(child) {
+  if (!child.pid || child.exitCode !== null) return;
+  if (process.platform === 'win32') spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+  else child.kill('SIGTERM');
+}
+
+export async function devCommand(args, cwd = process.cwd()) {
+  const options = parseDevArgs(args);
+  // Local tools (tauri, esbuild) the way an npm script finds them.
+  const env = { ...process.env, PATH: [join(cwd, 'node_modules', '.bin'), resolve(cwd, '..', 'node_modules', '.bin'), resolve(cwd, '..', '..', 'node_modules', '.bin'), process.env.PATH].join(delimiter) };
+  const children = [];
+  const stopAll = () => children.forEach(stop);
+  process.on('exit', stopAll);
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => process.exit(130));
+
+  for (const command of options.watch) {
+    const child = spawn(command, { cwd, env, shell: true, stdio: ['ignore', 'pipe', 'inherit'] });
+    children.push(child);
+    await new Promise((done, fail) => {
+      const timer = setTimeout(() => fail(new Error(`watcher did not report "watching" in time: ${command}`)), READY_TIMEOUT_MS);
+      let ready = false;
+      child.stdout.on('data', chunk => {
+        process.stdout.write(chunk);
+        if (!ready && READY.test(String(chunk))) {
+          ready = true;
+          clearTimeout(timer);
+          done();
+        }
+      });
+      child.on('exit', code => {
+        clearTimeout(timer);
+        if (!ready) fail(new Error(`watcher exited (${code}) before its first build: ${command}`));
+        else console.error(`waybetter dev: a watcher stopped (${code}): ${command}`);
+      });
+    }).catch(error => {
+      stopAll();
+      throw error;
+    });
+  }
+
+  const tauri = spawn('tauri', tauriDevArgs(options), { cwd, env, shell: true, stdio: 'inherit' });
+  children.push(tauri);
+  return new Promise(done =>
+    tauri.on('exit', code => {
+      stopAll();
+      done(code ?? 0);
+    }),
+  );
+}