npm: publish as one package waybetter (waybetter/runtime/*, waybetter/shell/*); @waybetter scope is taken

This commit is contained in:
CRTkafa 2026-09-28 05:54:03 +07:00
parent faf4e5909e
commit e5c91a1563
9 changed files with 197 additions and 906 deletions

View file

@ -0,0 +1,71 @@
# waybetter
The framework behind the wayBetter apps: apps that extend the apps you already use in place, the
way BetterDiscord extends Discord. A website gets a native window around it; a desktop app built
on web tech is extended from the inside. Both share this package.
- **`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.
- **`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.
## Install
```sh
npm install waybetter
```
## Usage
Every module is its own subpath export, so you only pull in what you use:
```ts
import { configureRuntime, type SiteAdapter } from 'waybetter/runtime/site';
import { watchDom } from 'waybetter/runtime/domHub';
import { buildColorModel, deriveColors } from 'waybetter/runtime/themeTokens';
import { parseAddress } from 'waybetter/shell/addressModel';
import { fuzzyScore, rankItems } from 'waybetter/shell/palette';
```
`runtime/site` is the composition root: an app is mostly one adapter object built from these
pieces. The source comments document each module's contract.
## Modules
**Runtime**
- `accountReport`: reports the signed-in account seen in the page's own UI.
- `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.
- `site`: the page-side composition root for an adapter.
- `themeTokens`: the OKLab color model themes are built on.
**Shell**
- `addressModel`: `parseAddress(url, site)` for the address bar's breadcrumb chips.
- `chrome`: layout constants for the custom titlebar and toolbar.
- `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.
## Projects using wayBetter
| Project | Target | What it is |
| --- | --- | --- |
| [wayBetter for X](https://waybetter.crt.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. |
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.
## License
GPL-3.0-or-later. See [LICENSE](./LICENSE).