yapin.js-client 0.0.0-stage → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yapin.js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# yapin.js-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A framework for building client apps for [Yapin’](https://www.yapin.gg): modified versions of the Yapin’ desktop app (and the web app, as a userscript) with your own pages, themes, plugins and badges.
+
+It's a framework, not a finished client. It provides the plumbing, so your client app only has to describe what makes it different:
+
+- **Plugins.** A full lifecycle with typed settings, dependencies, styles, DOM observers, patches and pages. Everything a plugin registers is undone automatically when it stops, and a plugin that keeps crashing is switched off on its own. Your users can install their own plugins, if you allow it.
+- **Themes.** CSS files with a metadata header. `@var` declarations become colour pickers and sliders in settings. There are also base styles, custom CSS, and themes added from code.
+- **Settings pages.** Add a page to Yapin’s own settings menu with one call. It looks native and leaves Yapin’s React tree untouched.
+- **An About page.** Version, build, git commit and environment, out of the box. Every row can be edited, hidden or removed, and so can the whole page.
+- **Badges.** Next to names on profile cards and messages, from a JSON file, your API, or code. Every badge is sanitised.
+- **API access.** Named services with retries, caching and secrets stored in the operating system's key store. On desktop, requests go through the main process, checked against an allowlist that's fixed at build time.
+- **A branded installer.** A setup wizard on Windows, built with NSIS: one signable `setup.exe` with your logo, icon, name and version, a zip for macOS and Linux. Configured from a JSON file with three presets. It runs on the Node built into the desktop app, so the people installing need nothing else. It handles install, update, repair after desktop updates, and uninstall.
+- **Zero dependencies.** It includes its own bundler, asar reader and writer, zip writer and test suite.
+
+> Client apps modify Yapin’. Check Yapin’s terms before you publish one, and make clear that yours is unofficial (the installer says so by default).
+
+## Quick start
+
+```sh
+npx yapin.js-client init my-client
+cd my-client
+npm install
+npm run dev
+```
+
+`npm run dev` builds your client app, installs it into the Yapin’ desktop app on your computer, and rebuilds and reloads every time you save. Open Yapin’, go to **Settings**, and your pages are at the bottom of the menu.
+
+`npm run build` produces everything you need to publish:
+
+| File | What it is |
+| --- | --- |
+| `dist/<id>-<version>-setup.exe` | The Windows installer: one file to share. |
+| `dist/<id>-<version>-installer.zip` | The installer for macOS and Linux. |
+| `dist/<id>.user.js` | The web version, for Tampermonkey or Violentmonkey. |
+| `dist/payload/` | What gets installed. |
+
+## What a client app looks like
+
+```text
+my-client/
+  yapin-client.config.js     name, options, installer
+  src/index.js               your code (runs in the page)
+  plugins/                   plugins built into your client app
+  themes/                    themes built into your client app
+  installer/marketing.json   what the installer page says
+```
+
+```js
+// src/index.js
+export default function setup(client) {
+  client.pages.add({
+    id: 'changelog',
+    title: 'Changelog',
+    render(root, { ui }) {
+      root.append(ui.heading('Changelog'), ui.hint('What changed in this version.'));
+    },
+  });
+
+  client.about.set('support.discord', { label: 'Community', value: 'https://example.com/chat', href: 'https://example.com/chat' });
+
+  client.badges.addProvider({ id: 'supporters', url: 'https://api.example.com/badges.json', refresh: '30m' });
+}
+```
+
+```js
+// plugins/compact.js
+import { definePlugin } from 'yapin.js-client/runtime';
+
+export default definePlugin({
+  id: 'compact',
+  name: 'Compact messages',
+  description: 'Less space between messages.',
+  settings: { gap: { type: 'slider', label: 'Gap', min: 0, max: 16, default: 4, unit: 'px' } },
+  styles: ({ gap }) => `.msg { margin-top: ${gap}px; }`,
+});
+```
+
+## Documentation
+
+Start with [Getting started](docs/getting-started.md), then [How it works](docs/architecture.md). Everything else is listed in [docs/](docs/README.md).
+
+## Requirements
+
+- Node 18.17 or newer to build. People installing your client app don't need Node.
+- The Yapin’ desktop app (Windows, macOS or Linux), or a userscript manager for the web version.
+
+## Testing
+
+```sh
+npm test               # offline: bundler, installer, runtime, build
+npm run test:browser   # needs Chrome or Edge: settings pages, badges, forms in a real browser
+```
+
+## License
+
+MIT

package/bin/yapin-client.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, watch, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { loadConfig } from '../src/config/load.js';
+import { build } from '../src/build/build.js';
+import { pack } from '../src/build/pack.js';
+import { findInstalls, install, inspect, repair, uninstall } from '../src/installer/patch.js';
+import { closeApp, isRunning, launchApp } from '../src/installer/processes.js';
+import { defaultTarget } from '../src/installer/paths.js';
+import { parseMeta } from '../src/runtime/meta.js';
+import { normalizeSchema } from '../src/runtime/settings.js';
+import { style } from '../src/installer/cli.js';
+import { deepMerge } from '../src/runtime/util.js';
+import { apiVersion, version } from '../src/shared/constants.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const HELP = `yapin-client ${version}: build Yapin’ client apps
+
+Usage: yapin-client <command> [options]
+
+Commands:
+  init [dir]             Start a new client app (config, entry, folders)
+  build                  Build the payload, installer, zip and userscript into dist/
+  dev                    Build in development mode, install into the desktop app, rebuild on save
+  install                Install the built client app into the desktop app on this computer
+  uninstall [--purge]    Remove it again (--purge deletes its data too)
+  repair                 Put it back after the desktop app updated
+  status                 Show desktop installs and what's installed in them
+  pack <file> [-o out]   Bundle a plugin with its imports into one file
+  validate <file>        Check a plugin (.js) or theme (.css) file
+  doctor                 Check the project and this computer for problems
+
+Options:
+  -c, --config <file>    Config file (default: yapin-client.config.js|.mjs|.json)
+  --mode <mode>          production (default) or development
+  --path <dir>           Desktop app folder, if it isn't found on its own
+  --close                Close the desktop app without asking when it's running
+  --no-installer         build: skip the installer and zip
+  -h, --help             Show this
+  -v, --version          Show the version`;
+
+const ok = (text) => console.log(style.green(`✔ ${text}`));
+const warn = (text) => console.log(style.yellow(`! ${text}`));
+const info = (text) => console.log(style.dim(`  ${text}`));
+
+function fail(error) {
+  console.error(style.red(`✖ ${error?.message ?? error}`));
+  if (error?.hint) console.error(`  ${error.hint}`);
+  if (process.env.DEBUG && error?.stack) console.error(style.dim(error.stack));
+  process.exitCode = 1;
+}
+
+async function load(values, mode) {
+  if (mode) process.env.YAPIN_CLIENT_MODE = mode;
+  const loaded = await loadConfig({ file: values.config });
+  for (const warning of loaded.warnings) warn(warning);
+  return loaded;
+}
+
+function target(config) {
+  return deepMerge(structuredClone(defaultTarget), config.installer.target ?? {});
+}
+
+function pickInstall(config, values) {
+  const list = findInstalls({ target: target(config), extra: values.path ?? [] });
+  if (!list.length) throw Object.assign(new Error("Couldn't find the desktop app"), { hint: 'Install it from https://www.yapin.gg, or pass --path <folder>.' });
+  const found = list[0];
+  if (!found.fuseCheck.ok) throw new Error(found.fuseCheck.reason);
+  return found;
+}
+
+async function ensureClosed(config, values) {
+  const t = target(config);
+  const name = t.processName?.[process.platform];
+  if (!name || !(await isRunning(name))) return false;
+  if (!values.close) throw Object.assign(new Error(`${t.productName} is running`), { hint: 'Close it, or pass --close to let yapin-client close it.' });
+  info(`Closing ${t.productName}…`);
+  if (!(await closeApp(name))) throw new Error(`Couldn't close ${t.productName}`);
+  return true;
+}
+
+async function runBuild(values, mode = values.mode ?? 'production') {
+  const { config, root } = await load(values, mode);
+  console.log(`${style.bold(style.accent(config.name))} ${style.dim(config.version)} ${style.dim(`(${mode})`)}`);
+  const result = await build(config, { root, mode, installer: !values['no-installer'], onStep: info });
+  for (const warning of result.warnings) warn(warning);
+  ok(`Built in ${result.ms} ms: ${result.plugins.length} bundled plugin(s), ${result.themes.length} bundled theme(s), ${Math.round(readFileSync(join(result.payloadDir, 'runtime.js')).length / 1024)} kB runtime`);
+  info(`payload     ${relative(process.cwd(), result.payloadDir)}`);
+  if (result.installerDir) info(`installer   ${relative(process.cwd(), result.installerDir)}`);
+  if (result.exeFile) info(`windows     ${relative(process.cwd(), result.exeFile)}`);
+  if (result.zipFile) info(`zip         ${relative(process.cwd(), result.zipFile)}`);
+  if (result.userscriptFile) info(`userscript  ${relative(process.cwd(), result.userscriptFile)}`);
+  return { config, root, result };
+}
+
+const commands = {
+  async init(values, [dir = '.']) {
+    const root = resolve(dir);
+    mkdirSync(root, { recursive: true });
+    const existing = readdirSync(root).filter((f) => !f.startsWith('.'));
+    if (existing.some((f) => f.startsWith('yapin-client.config'))) throw new Error(`${root} already has a yapin-client config`);
+    const id = basename(root).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'my-client';
+    const name = id.replace(/(^|-)([a-z])/g, (_, dash, c) => `${dash ? ' ' : ''}${c.toUpperCase()}`);
+    const templates = join(HERE, '..', 'templates', 'init');
+    cpSync(templates, root, { recursive: true, force: false, errorOnExist: false, filter: (src) => basename(src) !== 'gitignore' });
+    if (!existsSync(join(root, '.gitignore'))) writeFileSync(join(root, '.gitignore'), readFileSync(join(templates, 'gitignore')));
+    for (const file of ['yapin-client.config.js', 'installer/marketing.json', 'README.md', 'src/index.js']) {
+      const path = join(root, file);
+      if (existsSync(path)) writeFileSync(path, readFileSync(path, 'utf8').replaceAll('__ID__', id).replaceAll('__NAME__', name));
+    }
+    if (!existsSync(join(root, 'package.json'))) {
+      writeFileSync(
+        join(root, 'package.json'),
+        `${JSON.stringify({ name: id, version: '0.1.0', private: true, type: 'module', scripts: { build: 'yapin-client build', dev: 'yapin-client dev', status: 'yapin-client status' }, devDependencies: { 'yapin.js-client': `^${version}` } }, null, 2)}\n`,
+      );
+    }
+    ok(`Created ${name} in ${root}`);
+    info('Next: npm install, then npm run build (or npm run dev to try it in the desktop app)');
+  },
+
+  async build(values) {
+    await runBuild(values);
+  },
+
+  async dev(values) {
+    let { config, root, result } = await runBuild(values, 'development');
+    const found = pickInstall(config, values);
+    const wasRunning = await ensureClosed(config, values);
+    install({ resources: found.resources, payload: result.payloadDir, target: target(config), onStep: info });
+    ok(`Installed into ${found.location} (development build: the window reloads when you save)`);
+    if (wasRunning && found.executable) launchApp(found.executable);
+    const ignore = [config.outDir, join(root, 'node_modules'), join(root, '.git')];
+    let timer = null;
+    let building = false;
+    watch(root, { recursive: true }, (_event, file) => {
+      if (!file) return;
+      const full = join(root, file);
+      if (ignore.some((dir) => full.startsWith(dir))) return;
+      clearTimeout(timer);
+      timer = setTimeout(async () => {
+        if (building) return;
+        building = true;
+        try {
+          ({ config, root, result } = await runBuild({ ...values, 'no-installer': true }, 'development'));
+          install({ resources: found.resources, payload: result.payloadDir, target: target(config) });
+          ok('Reinstalled; the desktop app reloads');
+        } catch (error) {
+          fail(error);
+          process.exitCode = 0;
+        } finally {
+          building = false;
+        }
+      }, 200);
+    });
+    info('Watching for changes. Press Ctrl+C to stop.');
+  },
+
+  async install(values) {
+    const { config } = await load(values);
+    const payload = join(config.outDir, 'payload');
+    if (!existsSync(join(payload, 'manifest.json'))) throw Object.assign(new Error('Nothing built yet'), { hint: 'Run yapin-client build first.' });
+    const found = pickInstall(config, values);
+    const wasRunning = await ensureClosed(config, values);
+    const result = install({ resources: found.resources, payload, target: target(config), onStep: info });
+    ok(`${config.name} ${config.version} installed into ${found.location}`);
+    info(`data: ${result.dataDir}`);
+    if (wasRunning && found.executable) launchApp(found.executable);
+  },
+
+  async uninstall(values) {
+    const { config } = await load(values);
+    const found = pickInstall(config, values);
+    const wasRunning = await ensureClosed(config, values);
+    const result = uninstall({ resources: found.resources, target: target(config), id: config.id, purge: Boolean(values.purge), onStep: info });
+    if (result.removed) ok(`Removed${result.purged ? ' (data deleted too)' : ''}`);
+    else info(result.reason);
+    if (wasRunning && found.executable) launchApp(found.executable);
+  },
+
+  async repair(values) {
+    const { config } = await load(values);
+    const found = pickInstall(config, values);
+    const wasRunning = await ensureClosed(config, values);
+    const result = repair({ resources: found.resources, target: target(config), id: config.id, onStep: info });
+    if (result.repaired === false) info(result.reason);
+    else ok('Repaired');
+    if (wasRunning && found.executable) launchApp(found.executable);
+  },
+
+  async status(values) {
+    let t = defaultTarget;
+    try {
+      t = target((await load(values)).config);
+    } catch {
+      // no config here; show installs anyway
+    }
+    const list = findInstalls({ target: t, extra: values.path ?? [] });
+    if (!list.length) return warn("Couldn't find the desktop app");
+    for (const found of list) {
+      const s = found.status;
+      const what = s.state === 'installed' ? style.green(`${s.marker.name} ${s.marker.version}`) : s.state === 'clean' ? style.dim('nothing installed') : style.yellow(`${s.state}${s.reason ? `: ${s.reason}` : ''}`);
+      console.log(`${found.location} ${style.dim(s.version ?? '')}  ${what}`);
+      if (!found.fuseCheck.ok) warn(found.fuseCheck.reason);
+    }
+    const name = t.processName?.[process.platform];
+    if (name) info(`${t.productName} is ${(await isRunning(name)) ? 'running' : 'not running'}`);
+  },
+
+  async pack(values, [file]) {
+    if (!file) throw new Error('Usage: yapin-client pack <file> [-o out.js]');
+    const entry = resolve(file);
+    const out = resolve(values.out ?? join(dirname(entry), `${basename(entry).replace(/\.(m?js)$/, '')}.bundle.js`));
+    const header = readFileSync(entry, 'utf8').match(/^\s*\/\*\*?[\s\S]*?\*\//)?.[0] ?? '';
+    const result = pack({ entry, format: 'function', root: dirname(entry), alias: { 'yapin.js-client/runtime': join(HERE, '..', 'src', 'runtime', 'index.js') } });
+    writeFileSync(out, `${header}\n// Bundled by yapin-client pack. Edit the source, not this file.\nconst __bundle = ${result.code}();\nexport default __bundle.default;\n`);
+    ok(`${relative(process.cwd(), out)} (${result.files.length} files, ${Math.round(result.code.length / 1024)} kB)`);
+  },
+
+  async validate(_values, [file]) {
+    if (!file) throw new Error('Usage: yapin-client validate <plugin.js | theme.css>');
+    const text = readFileSync(resolve(file), 'utf8');
+    const { meta, vars } = parseMeta(text);
+    const problems = [];
+    if (!meta.id) problems.push('no @id in the header (the file name will be used)');
+    else if (!/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(meta.id)) problems.push(`@id "${meta.id}" must be lowercase letters, digits and dashes`);
+    if (!meta.name) problems.push('no @name');
+    if (!meta.version) problems.push('no @version');
+    if (!meta.authors?.length) problems.push('no @author');
+    if (meta.apiVersion && meta.apiVersion > apiVersion) problems.push(`@apiVersion ${meta.apiVersion} is newer than this framework's (${apiVersion})`);
+    if (/\.css$/i.test(file)) {
+      try {
+        const schema = Object.fromEntries(vars.map((v) => [v.variable.replace(/^--/, ''), { ...v, type: v.type === 'color' || v.type === 'number' || v.type === 'slider' || v.type === 'select' || v.type === 'switch' ? v.type : 'text', options: v.options ?? (v.type === 'select' ? [v.default] : undefined) }]));
+        normalizeSchema(schema, file);
+      } catch (error) {
+        problems.push(error.message);
+      }
+      let depth = 0;
+      for (const c of text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, '')) {
+        if (c === '{') depth++;
+        if (c === '}') depth--;
+        if (depth < 0) break;
+      }
+      if (depth !== 0) problems.push('unbalanced { } braces');
+    } else {
+      try {
+        pack({ entry: resolve(file), root: dirname(resolve(file)), alias: { 'yapin.js-client/runtime': join(HERE, '..', 'src', 'runtime', 'index.js') } });
+      } catch (error) {
+        problems.push(error.message);
+      }
+    }
+    if (problems.length) {
+      for (const p of problems) warn(p);
+      process.exitCode = 1;
+    } else ok(`${meta.name ?? file} looks good${vars.length ? ` (${vars.length} variables)` : ''}`);
+  },
+
+  async doctor(values) {
+    console.log(`yapin-client ${version} on Node ${process.versions.node} (${process.platform} ${process.arch})`);
+    let config = null;
+    try {
+      ({ config } = await load(values));
+      ok(`Config is valid: ${config.name} ${config.version}`);
+    } catch (error) {
+      fail(error);
+    }
+    const list = findInstalls({ target: config ? target(config) : defaultTarget, extra: values.path ?? [] });
+    if (!list.length) warn("Desktop app not found (pass --path if it's somewhere unusual)");
+    for (const found of list) {
+      ok(`Desktop app at ${found.location} (${found.status.version ?? 'unknown version'}, ${found.status.state})`);
+      if (!found.fuseCheck.ok) warn(found.fuseCheck.reason);
+      else if (found.fuses) info(`fuses: ${Object.entries(found.fuses.fuses).filter(([, on]) => on).map(([n]) => n).join(', ') || 'none on'}`);
+      if (found.status.state === 'installed') info(`installed: ${found.status.marker.name} ${found.status.marker.version}`);
+      const s = inspect(found.resources, { target: config ? target(config) : defaultTarget });
+      if (s.state === 'needs-repair') warn(`${s.reason}; run yapin-client repair`);
+    }
+    if (config) {
+      for (const origin of config.origins) {
+        try {
+          const res = await fetch(origin, { method: 'GET', redirect: 'follow' });
+          const csp = res.headers.get('content-security-policy');
+          if (csp) warn(`${origin} now sends a Content-Security-Policy; user plugins may need desktop.csp: "relax" (see docs/security.md)`);
+          else ok(`${origin} reachable, no Content-Security-Policy`);
+        } catch (error) {
+          warn(`${origin} not reachable: ${error.message}`);
+        }
+      }
+    }
+  },
+};
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      config: { type: 'string', short: 'c' },
+      mode: { type: 'string' },
+      path: { type: 'string', multiple: true },
+      close: { type: 'boolean' },
+      purge: { type: 'boolean' },
+      out: { type: 'string', short: 'o' },
+      'no-installer': { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+    },
+  });
+  if (values.version) return console.log(version);
+  const [command, ...rest] = positionals;
+  if (values.help || !command) return console.log(HELP);
+  const run = commands[command];
+  if (!run) throw new Error(`Unknown command "${command}". Run yapin-client --help`);
+  await run(values, rest);
+}
+
+main().catch(fail);

package/docs/README.md

@@ -0,0 +1,36 @@
+# Documentation
+
+## Building a client app
+
+| | |
+| --- | --- |
+| [Getting started](getting-started.md) | From `init` to a working client app in the desktop app |
+| [How it works](architecture.md) | The installer, the stub, the main process, the preload and the runtime |
+| [Configuration](configuration.md) | Every option in `yapin-client.config.js` |
+| [The client object](runtime.md) | Everything your entry file and plugins can use |
+| [Command line](cli.md) | `init`, `build`, `dev`, `install`, `pack`, `doctor` and friends |
+
+## Features
+
+| | |
+| --- | --- |
+| [Plugins](plugins.md) | Writing plugins, their lifecycle, user plugins |
+| [Settings](settings.md) | Typed settings for plugins, themes and your client app |
+| [Themes](themes.md) | Theme files, variables, base styles, custom CSS |
+| [Pages](pages.md) | Adding pages to Yapin’s settings menu |
+| [The About page](about-page.md) | Editing, extending and removing it |
+| [Welcome and what's new](welcome.md) | The first-run and update screens: editing, disabling, replaying |
+| [Badges](badges.md) | Badge providers, the JSON format, where badges appear |
+| [API access](api.md) | Services, the allowlist, secrets |
+| [UI kit](ui.md) | Native-looking controls, toasts and dialogs |
+| [Patching Yapin’](patching.md) | Finding Yapin’s modules, patching functions, reading React props |
+
+## Shipping
+
+| | |
+| --- | --- |
+| [The installer](installer.md) | Presets, marketing, launchers, update and repair |
+| [The web version](web.md) | The userscript build |
+| [Security](security.md) | What the framework protects, and what it can't |
+| [When Yapin’ changes](host-adapter.md) | Selectors, classes, and updating without a framework release |
+| [Troubleshooting](troubleshooting.md) | Logs, safe mode, common problems |

package/docs/about-page.md

@@ -0,0 +1,85 @@
+# The About page
+
+Every client app gets an About page in settings, filled in by the build:
+
+| Section | Field ids | |
+| --- | --- | --- |
+| `app` | `app.name`, `app.version`, `app.description`, `app.authors`, `app.safeMode` | From your config and package.json. `app.safeMode` only shows in safe mode. |
+| `build` (Build) | `build.date`, `build.mode`, `build.framework`, `build.pluginApi` | When and how it was built. |
+| `git` (Source) | `git.branch`, `git.commit`, `git.tag`, `git.date`, `git.dirty`, `git.remote` | Read from git at build time. The commit links to your host (GitHub, GitLab, Bitbucket, Codeberg, Gitea). Credentials in the remote URL are never included. Missing if the project isn't a git repository, or with `git: false`. |
+| `environment` (Environment) | `environment.platform`, `environment.desktop`, `environment.electron`, `environment.chrome`, `environment.node`, `environment.os` | Where it's running. |
+| `links` (Links) | `links.<key>` | One per entry in your config's `links`. |
+
+## How it's laid out
+
+- **A header card** for the `app` section: a logo tile, the name with a version tag (click the copy icon to copy it), and the description. Any other `app.*` field shows small underneath.
+- **A row of buttons**: **Copy debug info** (`copy`), **Welcome screen** (`welcome`) and **What's new** (`whatsNew`) when those are on, and on desktop **Data folder** (`folder`) and **Safe mode** (`safeMode`).
+- **A grid of compact cards**, one per other section, with labels and values side by side. Long values are cut short with the full text on hover, and copyable values get a copy icon.
+- **Links** as small chips that open in the browser.
+
+Each section's look is its `layout`, so any of them can be changed:
+
+| Layout | |
+| --- | --- |
+| `rows` | Label and value side by side. The default for new sections. |
+| `chips` | Compact pills: links show their label, other fields their value. The `links` section uses it. |
+| `header` | The card at the top. Its `name`, `version` and `description` fields become the title, the version tag and the line under it. The `app` section uses it. Only the first `header` section is drawn as the header; give it to another section to change what's at the top. |
+
+**Copy debug info** copies every row as text, plus enabled plugins and themes (with versions and sources) and the last 20 warnings and errors. It's what you want in bug reports.
+
+## Changing it from the config
+
+```js
+about: {
+  title: 'About Nebula',
+  logo: 'sparkles',                                  // the header tile: an icon name, SVG, or image URL (default: the first letter)
+  intro: 'Thanks for using Nebula!',
+  sections: {
+    environment: false,                              // hide a whole section
+    support: { title: 'Support', order: 35 },        // add one (built-in orders: 0, 10, 20, 30, 40)
+    links: { layout: 'rows' },                       // show links as rows instead of chips
+  },
+  fields: {
+    'git.remote': false,                             // hide a row
+    'build.mode': 'Release',                         // a string replaces the value
+    'app.version': { label: 'Release' },             // change only the label
+    'support.email': { label: 'Email', value: 'help@nebula.example', copy: true },
+    'support.chat': { label: 'Chat', value: 'nebula.example/chat', href: 'https://nebula.example/chat' },
+  },
+  actions: { safeMode: false },                      // remove a button
+},
+```
+
+`about: false` removes the page.
+
+## Changing it from code
+
+Your entry file and plugins can change it at any time. If the page is open, it redraws.
+
+```js
+client.about.set('app.version', { value: `${client.version} (beta)` });
+client.about.set('stats.plugins', { label: 'Plugins running', value: () => String(client.plugins.list().filter((p) => p.status === 'running').length) });
+client.about.remove('git.dirty');
+client.about.section('stats', { title: 'Stats', order: 25 });
+client.about.section('community', { title: 'Community', layout: 'chips' });
+client.about.sections();   // [{ id, title, order, layout }], in order
+client.about.removeSection('environment');
+client.about.action('report', { label: 'Report a bug', icon: 'alertCircle', run: (client) => client.openExternal('https://github.com/ada/nebula/issues/new') });
+client.about.removeAction('folder');
+client.about.debugInfo();   // the text Copy debug info copies
+```
+
+A field is `{ label, value, href, copy, code, order, hidden }`:
+
+| | |
+| --- | --- |
+| `value` | Text, or a function returning text (called whenever the page draws). |
+| `href` | Makes the value a link. Only https and mailto links are used. |
+| `copy` | Adds a Copy button: `true` copies the value, a string copies that string. |
+| `code` | Monospace. |
+| `order` | Position within its section. |
+| `hidden` | Kept but not shown. |
+
+`set` only changes the options you pass. Setting a field in a section that doesn't exist creates the section.
+
+To take the page out entirely from code: `client.pages.remove('about')`. To move it: `client.pages.update('about', { order: 50, title: 'Info' })`.

package/docs/api.md

@@ -0,0 +1,106 @@
+# API access
+
+`client.api` talks to HTTP APIs: your backend, a badge server, anything your client app needs. Requests go only to origins you've allowed.
+
+## Services
+
+Name your APIs in the config:
+
+```js
+api: {
+  services: {
+    backend: { baseURL: 'https://api.nebula.example/v1', timeout: 10_000, retries: 2 },
+    status: { baseURL: 'https://status.nebula.example', cache: '1m' },
+  },
+},
+```
+
+Then:
+
+```js
+const backend = client.api.service('backend');
+
+const me = await backend.get('/me');
+const page = await backend.get('/posts', { query: { page: 2, tags: ['a', 'b'] } });   // ?page=2&tags=a&tags=b
+await backend.post('/reports', { json: { reason: 'spam' } });
+await backend.delete(`/posts/${id}`);
+```
+
+Each service option can also be passed per request:
+
+| Option | Default | |
+| --- | --- | --- |
+| `baseURL` | required | https (or http for localhost). |
+| `headers` | | Sent with every request. From code, can be a function (also async). |
+| `query` | | Added to every request. |
+| `timeout` | `15000` | ms. |
+| `retries` | 2 for GET, HEAD, PUT, DELETE, OPTIONS; 0 for others | Retried on network errors, 429, 502, 503 and 504, with backoff. `Retry-After` is respected up to 30 s. If you give a POST or PATCH retries, it's retried only on 429, since the server didn't act on it. |
+| `cache` | none | `'30s'`, `'5m'`: reuse GET responses that long. |
+| `auth` | none | `{ secret: 'name' }` sends `Authorization: Bearer <secret>`; `{ secret, type: 'header', header: 'x-api-key' }` sends the secret in that header; `scheme` replaces `Bearer`. |
+
+Per request, there's also `json` (a body sent as JSON), `body` (a string), `headers`, and `responseType` (`json`, `text` or `auto`, which goes by the content type).
+
+Identical GET requests in flight at the same time share one call.
+
+## Results and errors
+
+A request resolves with the parsed body. Anything other than a 2xx rejects with an `ApiError`:
+
+```js
+import { ApiError } from 'yapin.js-client/runtime';
+
+try {
+  await backend.get('/thing');
+} catch (error) {
+  if (error instanceof ApiError && error.status === 404) { /* … */ }
+  error.body;   // the parsed body, if any; its "message" or "error" becomes the error message
+}
+```
+
+## The allowlist
+
+`client.api` reaches only:
+
+- the origins of your `api.services`;
+- the origins of your `badges.sources`;
+- anything in `api.allowedOrigins`.
+
+These are fixed when you build. On desktop the main process enforces the list too, and code in the page can't change it there, so even a malicious user plugin can't use your client app to send requests somewhere you didn't choose. Services added from code with `client.api.addService(name, config)` must also be on the list.
+
+Without a service:
+
+```js
+await client.api.request({ url: 'https://api.nebula.example/v1/ping' });
+client.api.isAllowed('https://elsewhere.example');   // false
+```
+
+## Desktop and web
+
+On desktop, requests are sent by the main process, so CORS doesn't apply and your API doesn't need CORS headers. Cookies are never sent or stored. Responses are capped at 5 MB (configurable per request up to 10 MB), and redirects are followed only to allowed origins.
+
+On the web, requests go straight from the page with `fetch` (`credentials: 'omit'`), so your API must send CORS headers for Yapin’s origins (`https://www.yapper.website` and `https://www.yapin.gg`).
+
+Neither ever includes the person's Yapin’ session. The API client is for your services, not for automating Yapin’ accounts (which breaks Yapin’s terms).
+
+## Secrets
+
+Tokens and keys for your services:
+
+```js
+await client.secrets.set('backend-token', token);
+await client.secrets.get('backend-token');
+await client.secrets.delete('backend-token');
+client.secrets.secure;   // true on desktop
+```
+
+On desktop, secrets are encrypted with the operating system's key store (Electron `safeStorage`: DPAPI on Windows, Keychain on macOS, libsecret on Linux) and kept in the main process; the page only ever sees the one it asks for. On the web there's no such thing: secrets are stored in `localStorage` and `secure` is false. Don't store anything there you couldn't afford to leak.
+
+Pair secrets with `auth`, and the token is added to requests without your code handling it:
+
+```js
+api: { services: { backend: { baseURL: 'https://api.nebula.example', auth: { secret: 'backend-token' } } } },
+```
+
+## Downloading
+
+`client.api.download(url, { maxBytes, allowedHosts })` fetches a text file from any https URL, outside the allowlist but size-limited. The framework uses it to install plugins and themes from links. It's limited by `plugins.user.install` and `themes.user.install`, and on desktop the main process only allows it when installing from links is enabled.