wayBetter for X

store/README.md

@@ -0,0 +1,93 @@
+# The Store's source
+
+Every item in the wayBetter Store is one folder here. A pull request that adds a folder adds an
+item; nothing else has to be written by hand. The catalog, the item's page on
+waybetter.fyi/store/, its card, search entry, link preview, structured data and sitemap entry are
+all generated from these folders.
+
+```
+store/
+  featured.json                  the storefront's "Featured" shelf: ["x/theme/nord", …]
+  x/                             one folder per app id ("x" = wayBetter for X)
+    plugins/<id>/
+      <name>.plugin.js           the plugin, exactly as it installs
+      item.json                  { "category": "tools", "tags": ["notes", "profiles"] }
+      preview.svg | preview.png  optional
+    areas/<id>/
+      item.json                  an area plugin's page: { "category", "tags", "license", "credits", media }
+    themes/<id>/
+      theme.json                 the theme, as Appearance → Export writes it
+      item.json                  { "version": "1.0.0" }
+      preview.svg | preview.png  optional
+    strings/<id>/
+      <name>.strings.json        a string pack (waybetter/docs/STRING-PACKS.md): name, authors, version,
+                                 description and language are the pack's own; every string must fit
+                                 the app's inventory (node scripts/check-store.mjs checks it)
+      item.json                  { "category": "language", "tags", "license", "credits" }
+```
+
+The folder name is the item's **id**: `a-z`, `0-9` and `-`, at most 40 characters, unique among
+the app's plugins (or themes). It is also the item's address: `/store/plugins/<id>/`.
+
+## What goes where
+
+Everything the app shows on its install screen comes from the item's own file, so the Store and
+the install screen can never disagree. `item.json` holds only what the file cannot say.
+
+| | Plugin | Theme |
+| --- | --- | --- |
+| Name, author, description | the header: `@name`, `@author`, `@description` | `name`, `author`, `description` in `theme.json` |
+| Version | the header: `@version` | `"version"` in `item.json` |
+| Permissions | the header: `@permissions` | none (a theme is data) |
+| Category | `"category"` in `item.json`: `reading`, `writing`, `filters`, `focus` or `tools` | `dark` or `light`, from the theme's `mode` (or `"category"`) |
+| Tags | `"tags"` in `item.json`: up to 12 search words | the same (default: the category) |
+| Preview | `preview.svg` or `preview.png`, else a card drawn from the name and category | the same, else a miniature drawn from the theme |
+
+Rules the checks enforce:
+
+- **Description**: at least 50 characters that say what it does. The app keeps the first 300 of a
+  plugin's; search engines show the first 160 or fewer, cut at a sentence.
+- **Plugins** start with a `/** … */` header that has `@name`, `@version`, `@description`,
+  `@author` and a `@permissions` line naming `network` or `network:none`. `network:none` is refused
+  when the code calls `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource` or `sendBeacon`. The
+  gated API (`api.storage`, `api.ui`, `api.toast`, `api.copyText`, `api.account`, `api.users`,
+  `api.commands`) must be declared. No `eval`, `new Function`, `import()` or added `<script>`
+  elements: the code that is read and signed is the code that runs. At most 2 MiB, UTF-8 text.
+- **Themes** are a JSON object with a `name` that the app's sanitizer accepts, at most 2 MiB. A
+  theme's optional `css` may not `@import` or load files from another server.
+- **Previews** are 16:10 (640×400 is the size the Store shows), at most 300 KB. An SVG may not
+  contain scripts, event handlers, `foreignObject` or links to other servers.
+
+## Area plugins
+
+Compose+, Reader+, Profile+, Chat+, Media+, Search+, Notifications+ and Navigation+ are built into
+wayBetter for X (docs/AREA-PLUGINS.md), so they are not catalog items and have no Install button.
+Each has a page on the site from `store/x/areas/<id>/item.json` (category, tags, `license`,
+`credits`, and the same optional cover, screenshots and video as an item). Its name, description
+and feature list come from the app's feature table and words. The bundled plugin files those
+features replaced stay in the app for the one-time move of an existing install and have no Store
+folder.
+
+`license` (1 to 60 characters, e.g. an SPDX id) and `credits` (up to 600) are optional on every
+item and go into the catalog as they are.
+
+## First-party items
+
+The plugins the app ships and its built-in themes are in the Store too, but their files stay where
+the app builds them, so the two copies cannot drift:
+
+- `"bundled": "<file>.plugin.js"` takes the plugin from `apps/desktop/src-tauri/bundled-plugins/`;
+  `"file"` is the name it is installed under (`bt-<file>`), so a bundled copy counts as installed.
+- `"builtin": true` exports the built-in theme whose id is the folder name, the way Appearance →
+  Export does.
+
+## Commands
+
+```sh
+bun run check:store          # check the folders and the published catalog (no key needed)
+node scripts/build-store.mjs # maintainers: rebuild apps/web/public/store/ from the folders
+node scripts/sign-store.mjs  # maintainers: sign it, on the machine that holds the Store key
+```
+
+How a contribution becomes a Store item, step by step:
+[docs/STORE.md](../docs/STORE.md#add-your-theme-or-plugin-with-a-pull-request).