docs: the shell frame in the framework (what a site supplies, styles, words, native commands)

README: "The shell frame" (createShell, the ShellSite slots and features, frame words and styles,
bootScript, preview mocks, the native commands and events it uses), the layout, the create-waybetter
app, how wayBetter for X consumes it. npm README: waybetter/shell/frame.
This commit is contained in:
CRTkafa 2026-09-29 12:47:19 +07:00
parent 9ac8ab8767
commit 0f281f13b6
2 changed files with 86 additions and 5 deletions

View file

@ -14,10 +14,15 @@ heavy Electron client alike: every wayBetter app is the same shell, runtime and
ranking and window controls. The Tauri window API is passed in by the caller, never imported.
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.
Plain ESM with `.d.ts` types. Zero dependencies (the React parts use your React; the shell frame also dockview).
## Install
@ -71,6 +76,20 @@ pieces. The source comments document each module's contract.
- `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.
- 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.
**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).