yapin.js-client 0.1.0 → 0.1.5

package/LICENSE

@@ -19,3 +19,49 @@ 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.
+
+---
+
+Third-party notices
+
+The built-in icon set in src/shared/icons.js is taken from Lucide
+(https://lucide.dev). Lucide is ISC licensed, and the icons it inherits from
+Feather are MIT licensed. Both notices follow, and are reproduced as required.
+
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+MIT License
+
+Copyright (c) 2013-present Cole Bemis
+
+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

@@ -10,7 +10,7 @@ It's a framework, not a finished client. It provides the plumbing, so your clien
 - **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 single `setup.exe` on Windows (your icon, name and version, signable), 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.
+- **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).

package/docs/README.md

@@ -19,6 +19,7 @@
 | [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 |

package/docs/about-page.md

@@ -10,7 +10,20 @@ Every client app gets an About page in settings, filled in by the build:
 | `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`. |
 
-Under the rows are buttons: **Copy debug info** (`copy`), and on desktop **Open data folder** (`folder`) and **Restart in safe mode** (`safeMode`).
+## 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.
 
@@ -19,10 +32,12 @@ Under the rows are buttons: **Copy debug info** (`copy`), and on desktop **Open
 ```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
@@ -46,8 +61,10 @@ 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', run: (client) => client.openExternal('https://github.com/ada/nebula/issues/new') });
+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
 ```

package/docs/configuration.md

@@ -95,6 +95,17 @@ settings: {
 | `customCSS.title`, `customCSS.description` | | Its heading and hint. |
 | `user` | | Like `plugins.user`, with `maxBytes` 2000000. |
 
+## `icons`
+
+Icons your client app adds to the built-in set, usable by name anywhere an `icon` option is accepted. See [ui.md](ui.md#your-own-icons).
+
+| Option | Default | |
+| --- | --- | --- |
+| `dirs` | `['icons']` | Folders with `.svg` icons. Each is registered under its file name, so `icons/brand.svg` is `icon: 'brand'`. Names starting with `_` or `.` are skipped. |
+| `set` | `{}` | Icons given inline as `{ name: '<svg…>' }`. Wins over a folder file of the same name. |
+
+A name that matches a built-in replaces it. Markup is inlined into the payload at build time and sanitized when drawn; draw on a 24×24 `viewBox` with `stroke="currentColor"` and no `width`/`height` on the root `<svg>`.
+
 ## `pages`
 
 | Option | Default | |
@@ -113,13 +124,47 @@ settings: {
 | --- | --- | --- |
 | `title` | `About` | |
 | `order` | `0` | |
-| `intro` | none | A line under the heading. |
-| `sections` | | `{ git: false }` hides a section; `{ support: { title: 'Support', order: 35 } }` adds one. |
+| `logo` | the name's first letter | The tile in the header card: an icon name, SVG, or https/data image URL. |
+| `intro` | none | A line under the header. |
+| `sections` | | `{ git: false }` hides a section; `{ support: { title: 'Support', order: 35 } }` adds one; `{ links: { layout: 'rows' } }` changes how one looks (`rows`, `chips` or `header`). |
 | `fields` | | `{ 'git.remote': false }` hides a row; `{ 'support.email': { label: 'Email', value: 'help@example.com' } }` adds one. A string is a value. |
 | `actions` | | `{ safeMode: false }` removes a button (`copy`, `folder`, `safeMode`). |
 
 See [The About page](about-page.md) for every field id.
 
+## `welcome` and `whatsNew`
+
+A rounded, animated screen shown the first time the client app runs (`welcome`), and once after an update when there's something to say about it (`whatsNew`). Both are off with `enabled: false` or `welcome: false` / `whatsNew: false`, and both can be replayed at any time with `client.welcome.show()` / `client.whatsNew.show()`.
+
+| Option | Default | |
+| --- | --- | --- |
+| `enabled` | `true` | |
+| `icon` | `sparkles` / `rocket` | A built-in name, SVG markup, or an https/data image URL. See [UI kit](ui.md#icons). |
+| `title` | `Welcome to {name}` / `What's new in {name} {version}` | `{name}` and `{version}` are replaced. |
+| `subtitle` | none | A line under the title. |
+| `steps` (welcome) / `entries` (whatsNew) | `[]` | `{ icon, title, description }` rows. `whatsNew` only shows once it has at least one entry. |
+| `actionLabel` | `Get started` / `Got it` | The primary button. |
+| `dismissible` | `true` | `false` removes the Escape/backdrop/Skip ways out, leaving only the primary button. |
+| `dismissLabel` | `Skip` / none | The secondary button, when dismissible. |
+
+```js
+welcome: {
+  title: 'Welcome to {name}',
+  subtitle: "Here's what you get out of the box.",
+  steps: [
+    { icon: 'puzzle', title: 'Plugins', description: 'Turn features on and off from Settings.' },
+    { icon: 'palette', title: 'Themes', description: 'Apply a theme or write your own CSS.' },
+  ],
+},
+whatsNew: {
+  entries: [
+    { icon: 'sparkles', title: 'New in 1.2.0', description: 'A redesigned Settings page.' },
+  ],
+},
+```
+
+See [Welcome and what's new](welcome.md).
+
 ## `badges`
 
 | Option | Default | |

package/docs/getting-started.md

@@ -110,7 +110,7 @@ npm run build
 
 `dist/` now holds:
 
-- `nebula-1.0.0-setup.exe`: share this with Windows users. They double-click it and the installer opens in their browser.
+- `nebula-1.0.0-setup.exe`: share this with Windows users. They double-click it and a setup wizard walks them through it ([NSIS](installer.md#building-it) must be installed where you build).
 - `nebula-1.0.0-installer.zip`: for macOS (`Install Nebula.command`) and Linux (`./install.sh`).
 - `nebula.user.js`: the web version, for userscript managers ([The web version](web.md)).
 - `payload/`: what gets installed (used by `yapin-client install`).

package/docs/installer.md

@@ -23,13 +23,41 @@ Every launcher runs `installer.mjs` with the Node that's built into the Yapin’
 
 ## The Windows .exe
 
-`<id>-<version>-setup.exe` is a small launcher (about 13 kB, written in C#) with the whole installer folder compressed onto its end. When someone runs it, it:
+`<id>-<version>-setup.exe` is a setup wizard, the kind people know from other Windows programs. It's built with [NSIS](https://nsis.sourceforge.io) (the Nullsoft Scriptable Install System) and has its pages:
 
-1. unpacks the installer into a new private folder in their temp directory;
-2. finds the desktop app (the places in [Targets](#targets), plus any you add) and runs the installer with its Node, with no console window;
-3. waits, then deletes the folder. If the installer fails, the error is shown in a message box.
+1. **Welcome**, with your logo down the side, your description and the "unofficial modification" notice.
+2. **License**, when `marketing.terms` has text. With `requireAccept`, Next stays disabled until the box is ticked.
+3. **Choose an option**: the desktop install it found (a list, when there are several) and what's there, then Install, Update, Reinstall or Repair, and Uninstall (with "Also delete my installed plugins, themes and settings"). Next is labelled with what it will do. If Yapin’ is open it says so, and asks before closing it (see `installer.closeApp`).
+4. **Installing**, with a progress bar and **Show details** for each step. If something goes wrong, the error is shown and nothing is left half-done.
+5. **Finish**, with **Open Yapin’** (ticked unless `installer.launchAfter` is false).
 
-It runs as the current user (no administrator prompt), like the per-user desktop app it installs into.
+The wizard does the work with the same installer as everywhere else: it unpacks the installer folder to a temporary folder, runs it with the desktop app's Node (the places in [Targets](#targets), plus any you add) with no console window, and removes the folder when it closes. It runs as the current user (no administrator prompt), like the per-user desktop app it installs into.
+
+| Run as | Does |
+| --- | --- |
+| `nebula-setup.exe` | Opens the wizard. |
+| `nebula-setup.exe /S` | Silent: does what Next would (install, update, or repair) with no window. Exits with 0 when it worked. |
+| `nebula-setup.exe /S /UNINSTALL [/PURGE]` | Silent uninstall; `/PURGE` also deletes installed plugins, themes and settings. |
+
+The texts are in `marketing.strings` (the keys starting with `setup`, plus `install`, `launch`, `purge`, `accept` and the messages shared with the page), so they can be changed or translated.
+
+### Pictures, name, version and icon
+
+The side picture (164×314) is your `accent` colour with your logo on it, and the top-right picture (150×57) is your logo on white. The logo is `marketing.logo`, or the config's `icon`, as a PNG. To use your own pictures instead, set `installer.windows.sidebar` and `installer.windows.header` to `.bmp` files of those sizes.
+
+The .exe shows your name, description, version and authors in its file properties, and your icon (`installer.windows.icon`, or the config's `icon`: a PNG of at most 256×256 pixels, or an `.ico`) in Explorer and the taskbar.
+
+### Building it
+
+Building the wizard needs NSIS 3 on the machine that runs `yapin-client build`. It's found in the usual install folders, on the `PATH`, in the `MAKENSIS` environment variable, or at `installer.windows.nsis` (a path to `makensis`).
+
+| | |
+| --- | --- |
+| Windows | The installer from [nsis.sourceforge.io](https://nsis.sourceforge.io/Download), or `winget install NSIS.NSIS` |
+| macOS | `brew install makensis` |
+| Linux | `sudo apt install nsis` (or your distribution's `nsis` package) |
+
+Without NSIS, the build still makes a `setup.exe`, the simpler kind: a small launcher (written in C#) that opens the [installer page](#what-it-shows) in the browser. The build warns when that happens. Set `installer.windows.nsis` to `false` to always make that kind. It takes commands too:
 
 | Run as | Does |
 | --- | --- |
@@ -37,11 +65,7 @@ It runs as the current user (no administrator prompt), like the per-user desktop
 | `nebula-setup.exe install --yes` (or any command) | Runs that installer command with no window ([options](#in-the-terminal)). |
 | `nebula-setup.exe --extract [--to <dir>]` | Unpacks the installer folder (next to the .exe by default), for running `installer.mjs --cli` yourself. |
 
-### Name, version and icon
-
-Built on Windows, the launcher is compiled for your client app with `csc.exe`, the C# compiler that comes with the .NET Framework on every Windows 10 and 11 machine. The .exe then shows your name, description, version and authors in its file properties, and your icon in Explorer and the taskbar. The icon is `installer.windows.icon`, or the config's `icon`: a PNG of at most 256×256 pixels, or an `.ico`.
-
-Built on macOS or Linux, the .exe uses a prebuilt generic launcher instead (same behaviour, generic icon and details), and the build says so.
+Built on Windows, that launcher is compiled for your client app with `csc.exe`, the C# compiler that comes with the .NET Framework on every Windows 10 and 11 machine, so it has your name and icon. Built on macOS or Linux, it's a prebuilt generic launcher (same behaviour, generic icon and details).
 
 ### Signing
 
@@ -55,21 +79,24 @@ installer: {
 },
 ```
 
-`{file}` is replaced with the .exe's path. Any signing tool works. The launcher finds its bundle with or without a signature.
+`{file}` is replaced with the .exe's path. Any signing tool works, for either kind of .exe.
 
 ### Options
 
 | `installer.windows` | Default | |
 | --- | --- | --- |
 | `exe` | `true` | Build the .exe (it's skipped when `installer.gui` is false). |
+| `nsis` | `true` | Build the wizard when NSIS is found. `false` for the browser launcher, or the path to `makensis`. |
 | `fileName` | `<id>-<version>-setup.exe` | |
 | `icon` | the config's `icon` | PNG (at most 256 px) or `.ico`. |
+| `sidebar` | generated | A 164×314 `.bmp` for the Welcome and Finish pages. |
+| `header` | generated | A 150×57 `.bmp` for the top of the other pages. |
 | `company` | your authors | Shown in the file's properties. |
 | `sign` | none | A signing command containing `{file}`. |
 
 ## What it shows
 
-By default the installer opens a page in the browser, served from the person's own computer, built from your marketing config. It lists the desktop installs it found, with each one's state:
+On macOS and Linux (and from the Windows browser launcher), the installer opens a page in the browser, served from the person's own computer, built from your marketing config. It lists the desktop installs it found, with each one's state:
 
 | State | Shown as | Buttons |
 | --- | --- | --- |

package/docs/ui.md

@@ -39,6 +39,53 @@ ui.keyValue([{ label: 'Version', value: '1.0.0' }, { label: 'Link', value: ui.li
 ui.icon(svgMarkupOrImageURL)
 ```
 
+## Icons
+
+`ui.icon()`, and anywhere else an `icon` option is accepted (page icons, About fields, `ui.card`, `ui.button`, toasts, dialogs, the [welcome and what's new screens](welcome.md)), takes:
+
+- A built-in name: `'sparkles'`, `'rocket'`, `'puzzle'`, `'palette'`, `'sliders'`, `'info'`, `'check'`, `'x'`, `'alertTriangle'`, `'alertCircle'`, `'chevronRight'`, `'megaphone'`, `'bell'`, `'external'`, `'heart'`, `'copy'`, `'folder'`, `'shield'`.
+- A name your client app registered itself (see below).
+- SVG markup, sanitized (no scripts, event handlers, `foreignObject` or external links).
+- An https or `data:image/…` URL.
+- An element.
+
+```js
+ui.icon('rocket')
+ui.button({ label: 'Install', icon: 'puzzle' })
+client.pages.add({ id: 'tools', title: 'Tools', icon: 'sliders', render })
+```
+
+Every icon is a single colour that follows `currentColor`, so it matches whatever text colour it sits in, in any theme.
+
+The built-ins are [Lucide](https://lucide.dev), so Lucide's own names work too: `'triangle-alert'` is the same icon as `'alertTriangle'`, and names match in either kebab-case or camelCase. Lucide draws at a 2 px stroke; to re-weight the whole set, set `stroke-width` on `.yc-icon svg` in your `themes.css` rather than editing the markup.
+
+### Your own icons
+
+The built-in set is only a default: a client app can add to it, or replace any of it. The simplest way is a folder — every `.svg` in [`icons.dirs`](configuration.md#icons) is registered under its file name, so `icons/brand.svg` becomes `icon: 'brand'`. Give an icon the same name as a built-in and yours replaces it, which is how you swap the whole look without touching the framework:
+
+```
+icons/
+  brand.svg      → icon: 'brand'
+  rocket.svg     → replaces the built-in 'rocket'
+```
+
+Files starting with `_` or `.` are skipped. The markup is inlined into the payload at build time, so there's no loading to wait for, and it's sanitized when it's drawn.
+
+Icons can also be given inline in the config, which wins over a folder file of the same name:
+
+```js
+icons: { set: { brand: '<svg viewBox="0 0 24 24">…</svg>' } }
+```
+
+A plugin can register its own at runtime:
+
+```js
+client.ui.registerIcons({ sparkle: '<svg viewBox="0 0 24 24">…</svg>' });
+client.ui.iconNames();  // every name available, built-in and registered
+```
+
+Write icons on a 24×24 `viewBox` with `stroke="currentColor"` and no `width`/`height` on the root `<svg>` (CSS sizes them, from 13 px in About chips up to 26 px in the About logo tile), so they theme and scale like the built-ins. Markup that isn't SVG is reported through the client app's error handler rather than drawn.
+
 ## Controls
 
 ```js
@@ -72,10 +119,10 @@ One control per setting, saved as the person edits, with errors shown under the
 ## Toasts and dialogs
 
 ```js
-ui.toast('Saved', { type: 'success' });                       // info | success | warning | error
-ui.toast('Update available', { timeout: 0, action: { label: 'Restart', onClick: restart } });
+ui.toast('Saved', { type: 'success' });                       // info | success | warning | error — each type gets a matching icon
+ui.toast('Update available', { timeout: 0, action: { label: 'Restart', onClick: restart }, icon: 'rocket' });
 
-if (await ui.confirm({ title: 'Delete everything?', message: 'This can’t be undone.', confirmLabel: 'Delete', danger: true })) { … }
+if (await ui.confirm({ title: 'Delete everything?', message: 'This can’t be undone.', confirmLabel: 'Delete', danger: true })) { … }  // danger confirms get a warning icon automatically
 
 const name = await ui.prompt({ title: 'Rename', value: current, validate: (v) => v.trim() !== '' || 'Can’t be empty' });
 

package/docs/welcome.md

@@ -0,0 +1,63 @@
+# Welcome and what's new
+
+Two rounded, animated screens the framework can show on top of the app:
+
+- **Welcome**, the first time the client app runs with nothing saved yet — a rounded-corner hero icon, a title and subtitle, and a short list of steps with their own icons.
+- **What's new**, once after an update, when `whatsNew.entries` has something for the new version.
+
+Both fade and scale in, with the hero icon settling into place and each row sliding in in sequence; everything respects `prefers-reduced-motion`. Both are entirely optional and entirely yours to edit.
+
+## Turning them off
+
+```js
+welcome: false,     // no welcome screen, ever
+whatsNew: false,    // no what's new screen, ever
+```
+
+Or just for one: `welcome: { enabled: false }`. `whatsNew` also stays quiet on its own whenever `entries` is empty — ship a release with nothing to say and nothing shows.
+
+## Editing them
+
+```js
+welcome: {
+  icon: 'sparkles',                         // a built-in icon, SVG, or an image URL — see UI kit → Icons
+  title: 'Welcome to {name}',                // {name} and {version} are replaced
+  subtitle: "Here's what you get out of the box.",
+  steps: [
+    { icon: 'puzzle', title: 'Plugins', description: 'Turn features on and off from Settings.' },
+    { icon: 'palette', title: 'Themes', description: 'Apply a theme, or write your own CSS.' },
+  ],
+  actionLabel: 'Get started',
+  dismissible: true,                        // false removes Escape, the backdrop click, and the Skip button
+  dismissLabel: 'Skip',
+},
+whatsNew: {
+  icon: 'rocket',
+  title: "What's new in {name} {version}",
+  entries: [
+    { icon: 'sparkles', title: 'A redesigned Settings page', description: 'Find things faster.' },
+    { icon: 'puzzle', title: 'Three new plugins', description: 'Enable them from the Plugins page.' },
+  ],
+  actionLabel: 'Got it',
+},
+```
+
+A client app that only wants the hero and a message can leave `steps` / `entries` out (welcome still shows; what's new needs at least one entry to show at all).
+
+## Replaying them from code
+
+```js
+client.welcome.show();     // right now, regardless of whether it's been seen
+client.whatsNew.show();
+
+client.welcome.reset();    // clears the "seen" flag, so it shows again next start
+client.welcome.markSeen(); // marks it seen without showing it
+```
+
+A **Show welcome screen** / **Show what's new** button is added to the [About page](about-page.md) automatically whenever the screen is enabled (remove with `about: { actions: { welcome: false, whatsNew: false } }`).
+
+`client.welcome` and `client.whatsNew` are `null` when turned off with `welcome: false` / `whatsNew: false`.
+
+## How "seen" is tracked
+
+Each screen stores one value — the version it was last seen at — in the client app's own storage, under `onboarding`. Welcome only needs to know whether it's ever run; what's new compares the stored version against `client.version`, so it shows again after every update that has entries (and only once per version).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yapin.js-client",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "A zero-dependency framework for building Yapin’ client mods: plugins, themes, settings pages, badges, API access and a branded installer.",
   "repository": {
     "type": "git",

package/src/build/build.js

@@ -7,6 +7,7 @@ import { pack } from './pack.js';
 import { readGitInfo } from './git.js';
 import { zipDirectory } from './zip.js';
 import { compileLauncher, createSetupExe, findCsc, PREBUILT_LAUNCHER, signFile } from './windows.js';
+import { buildNsisExe, findMakensis } from './nsis.js';
 import { defaultTarget } from '../installer/paths.js';
 import { deepMerge } from '../runtime/util.js';
 import { apiVersion, version as frameworkVersion } from '../shared/constants.js';
@@ -53,18 +54,46 @@ export function findThemes(dirs) {
   return out;
 }
 
+/**
+ * Icons in a folder: every `.svg` (not starting with _ or .), registered under its file name, so
+ * `icons/brand.svg` becomes `icon: 'brand'`. The markup is inlined into the payload; `width` and
+ * `height` are dropped because CSS sizes icons, and it is sanitized when drawn.
+ */
+export function findIcons(dirs) {
+  const out = {};
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const name of readdirSync(dir).sort()) {
+      if (!/\.svg$/i.test(name) || /^[_.]/.test(name)) continue;
+      const markup = readFileSync(join(dir, name), 'utf8').trim();
+      if (!markup.includes('<svg')) throw new Error(`Icon ${join(dir, name)} is not an SVG`);
+      // Exports are pretty-printed; collapse them so the payload stays small. Only the root <svg> loses
+      // width/height: the same attributes on a shape (a <rect>, say) are geometry and must stay.
+      out[basename(name, extname(name))] = markup
+        .replace(/<svg\b[^>]*>/, (open) => open.replace(/\s+(width|height)="[^"]*"/g, '').replace(/\s+/g, ' ').replace(/ (\/?)>$/, '$1>'))
+        .replace(/>\s+</g, '><');
+    }
+  }
+  return out;
+}
+
 /** The part of the config the running client app gets (plain data, no build paths). */
-export function runtimeConfig(config) {
+export function runtimeConfig(config, { icons } = {}) {
   const { dirs: _pd, ...plugins } = config.plugins;
   const { dirs: _td, css: _css, ...themes } = config.themes;
+  const { dirs: _id, set, ...iconOptions } = config.icons ?? {};
   return {
     origins: config.origins,
     settings: config.settings,
     runtime: config.runtime,
     plugins,
     themes,
+    // Folder icons first, so an inline `icons.set` entry wins on a name clash.
+    icons: { ...iconOptions, set: { ...icons, ...set } },
     pages: config.pages,
     about: config.about,
+    welcome: config.welcome,
+    whatsNew: config.whatsNew,
     badges: config.badges,
     api: config.api,
     host: config.host,
@@ -121,32 +150,38 @@ exit 1
 }
 
 /**
- * The Windows installer: one .exe with the installer folder inside. On Windows the launcher is compiled
- * for this client app (its name, version and icon); elsewhere the prebuilt generic one is used.
+ * The Windows installer: one .exe with the installer folder inside. With NSIS available it's a setup
+ * wizard (see nsis.js). Otherwise it's the small launcher that opens the installer page in the browser,
+ * compiled for this client app on Windows (its name, version and icon), or the prebuilt generic one.
  */
-function buildSetupExe(config, { installerDir, outDir }) {
+function buildSetupExe(config, { settings, installerDir, outDir }) {
   const windows = config.installer.windows ?? {};
   const file = join(outDir, windows.fileName ?? `${config.id}-${config.version}-setup.exe`);
+  const icon = windows.icon ?? config.icon ?? null;
+  const exeIcon = icon && /\.(png|ico)$/i.test(icon) ? icon : null;
+  const company = windows.company ?? config.authors?.map((a) => a.name).join(', ') ?? '';
+  const target = deepMerge(structuredClone(defaultTarget), config.installer.target ?? {});
+  const exeName = target.executable?.win32 ?? 'Yapper.exe';
+  const exe = (target.locations?.win32 ?? []).map((location) => `${location.replace(/[\\/]+$/, '')}\\${exeName}`);
+
+  const makensis = windows.nsis === false ? null : findMakensis({ configured: windows.nsis });
+  if (makensis) {
+    buildNsisExe({ makensis, installer: settings, source: installerDir, out: file, icon: exeIcon, sidebar: windows.sidebar, header: windows.header, company, description: config.description, exeLocations: exe });
+    if (windows.sign) signFile(windows.sign, file);
+    return { file, kind: 'nsis', warning: null };
+  }
+
+  const warnings = [];
+  if (typeof windows.nsis === 'string') warnings.push(`installer.windows.nsis: ${windows.nsis} didn't run, so the Windows .exe opens the installer in the browser instead of the setup wizard.`);
+  else if (windows.nsis !== false) warnings.push("NSIS isn't installed, so the Windows .exe opens the installer in the browser instead of the setup wizard. Install NSIS (https://nsis.sourceforge.io, apt install nsis, or brew install makensis) for the wizard.");
   let launcher = PREBUILT_LAUNCHER;
-  let warning = null;
   const work = mkdtempSync(join(tmpdir(), 'yc-setup-'));
   try {
     if (findCsc()) {
-      const icon = windows.icon ?? config.icon ?? null;
-      launcher = compileLauncher({
-        out: join(work, 'launcher.exe'),
-        name: config.name,
-        version: config.version,
-        description: config.description,
-        company: windows.company ?? config.authors?.map((a) => a.name).join(', ') ?? '',
-        icon: icon && /\.(png|ico)$/i.test(icon) ? icon : null,
-      });
+      launcher = compileLauncher({ out: join(work, 'launcher.exe'), name: config.name, version: config.version, description: config.description, company, icon: exeIcon });
     } else {
-      warning = 'Built the Windows .exe with the generic launcher (no csc.exe here), so it has no custom icon or file details. Build on Windows for those.';
+      warnings.push('Built the Windows .exe with the generic launcher (no csc.exe here), so it has no custom icon or file details. Build on Windows for those.');
     }
-    const target = deepMerge(structuredClone(defaultTarget), config.installer.target ?? {});
-    const exeName = target.executable?.win32 ?? 'Yapper.exe';
-    const exe = (target.locations?.win32 ?? []).map((location) => `${location.replace(/[\\/]+$/, '')}\\${exeName}`);
     createSetupExe({
       launcher,
       installerDir,
@@ -158,7 +193,7 @@ function buildSetupExe(config, { installerDir, outDir }) {
     rmSync(work, { recursive: true, force: true });
   }
   if (windows.sign) signFile(windows.sign, file);
-  return { file, warning };
+  return { file, kind: 'launcher', warning: warnings.join(' ') || null };
 }
 
 function userscript(config, manifest, runtime) {
@@ -214,6 +249,7 @@ export async function build(config, { root, mode = 'production', onStep = () =>
   onStep('Collecting plugins and themes');
   const pluginFiles = findPlugins(config.plugins.dirs);
   const themeFiles = findThemes(config.themes.dirs);
+  const iconFiles = findIcons(config.icons?.dirs ?? []);
   const baseCSS = config.themes.css ? readFileSync(config.themes.css, 'utf8') : '';
 
   const imports = [`import { boot } from ${JSON.stringify(toPosix(join(SRC, 'runtime', 'boot.js')))};`];
@@ -251,7 +287,7 @@ export default (args) => boot(args, { entry, plugins, themes });
     build: { time: new Date().toISOString(), mode },
     git,
     baseCSS,
-    config: runtimeConfig(config),
+    config: runtimeConfig(config, { icons: iconFiles }),
     files: {},
   };
   if (mode === 'development') {
@@ -286,13 +322,15 @@ export default (args) => boot(args, { entry, plugins, themes });
   let installerDir = null;
   let zipFile = null;
   let exeFile = null;
+  let exeKind = null;
   if (installer) {
     onStep('Building the installer');
     installerDir = join(outDir, 'installer', config.id);
     mkdirSync(installerDir, { recursive: true });
     const installerBundle = pack({ entry: join(SRC, 'installer', 'main.js'), format: 'module', root: SRC });
     writeFileSync(join(installerDir, 'installer.mjs'), installerBundle.code);
-    writeFileSync(join(installerDir, 'installer.json'), JSON.stringify(installerConfig(config, manifest), null, 2));
+    const settings = installerConfig(config, manifest);
+    writeFileSync(join(installerDir, 'installer.json'), JSON.stringify(settings, null, 2));
     cpSync(payloadDir, join(installerDir, 'payload'), { recursive: true });
     const sh = launcherScript();
     const safeName = config.name.replace(/[^\w .-]+/g, '').trim() || config.id;
@@ -307,7 +345,7 @@ export default (args) => boot(args, { entry, plugins, themes });
     }
     writeFileSync(
       join(installerDir, 'README.txt'),
-      `${config.name} ${config.version}\r\n\r\nWindows: run ${config.id}-${config.version}-setup.exe instead of this folder.\r\nmacOS: double-click "Install ${safeName}.command".\r\nLinux: run ./install.sh\r\nAnywhere with Node: node installer.mjs (add --cli for the terminal version).\r\n\r\nThe installer opens in your browser. Close the Yapin' desktop app first, or the installer will offer to.\r\nTo remove ${config.name}, run the installer again and choose Uninstall.\r\n`,
+      `${config.name} ${config.version}\r\n\r\nWindows: run ${config.id}-${config.version}-setup.exe instead of this folder.\r\nmacOS: double-click "Install ${safeName}.command".\r\nLinux: run ./install.sh\r\nAnywhere with Node: node installer.mjs (add --cli for the terminal version).\r\n\r\nOn macOS and Linux the installer opens in your browser. Close the Yapin' desktop app first, or the installer will offer to.\r\nTo remove ${config.name}, run the installer again and choose Uninstall.\r\n`,
     );
     if (config.installer.zip !== false) {
       zipFile = join(outDir, `${config.id}-${config.version}-installer.zip`);
@@ -316,14 +354,15 @@ export default (args) => boot(args, { entry, plugins, themes });
     const windows = config.installer.windows ?? {};
     if (windows.exe !== false && config.installer.gui !== false) {
       onStep('Building the Windows setup .exe');
-      const built = buildSetupExe(config, { installerDir, outDir });
+      const built = buildSetupExe(config, { settings, installerDir, outDir });
       exeFile = built.file;
+      exeKind = built.kind;
       if (built.warning) warnings.push(built.warning);
     }
   }
 
   writeFileSync(join(outDir, 'build.json'), JSON.stringify({ id: config.id, version: config.version, mode, time: manifest.build.time, plugins: pluginFiles.map((f) => toPosix(relative(root, f))), themes: themeFiles.map((f) => toPosix(relative(root, f))), runtimeBytes: runtime.length, hash: bundled.hash }, null, 2));
-  return { outDir, payloadDir, installerDir, zipFile, exeFile, userscriptFile, manifest, plugins: pluginFiles, themes: themeFiles, files: bundled.files, warnings, ms: Date.now() - started };
+  return { outDir, payloadDir, installerDir, zipFile, exeFile, exeKind, userscriptFile, manifest, plugins: pluginFiles, themes: themeFiles, files: bundled.files, warnings, ms: Date.now() - started };
 }
 
 function camel(id) {