yapin.js-client 0.1.4 → 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/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 | |

package/docs/ui.md

@@ -44,6 +44,7 @@ ui.icon(svgMarkupOrImageURL)
 `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.
@@ -56,6 +57,35 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yapin.js-client",
-  "version": "0.1.4",
+  "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

@@ -54,16 +54,42 @@ 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,
@@ -223,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')))};`];
@@ -260,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') {

package/src/config/defaults.js

@@ -52,6 +52,13 @@ export const defaults = Object.freeze({
     },
   },
 
+  icons: {
+    // Every .svg in these folders is registered under its file name, so `icons/brand.svg` is `icon: 'brand'`.
+    dirs: ['icons'],
+    // Icons given inline as `{ name: '<svg…>' }`. A name that matches a built-in replaces it.
+    set: {},
+  },
+
   pages: {
     section: null,
     position: 'end',

package/src/config/load.js

@@ -8,7 +8,7 @@ import { idPattern } from '../shared/constants.js';
 export const CONFIG_FILES = ['yapin-client.config.js', 'yapin-client.config.mjs', 'yapin-client.config.json'];
 
 /** Sections that reach the running client app, so they must be JSON. */
-const RUNTIME_SECTIONS = ['settings', 'runtime', 'plugins', 'themes', 'pages', 'about', 'welcome', 'whatsNew', 'badges', 'api', 'host', 'desktop', 'origins', 'links'];
+const RUNTIME_SECTIONS = ['settings', 'runtime', 'plugins', 'themes', 'icons', 'pages', 'about', 'welcome', 'whatsNew', 'badges', 'api', 'host', 'desktop', 'origins', 'links'];
 
 export class ConfigError extends Error {
   constructor(problems, file) {
@@ -141,7 +141,7 @@ export function validateConfig(input, { root = process.cwd(), file = null } = {}
   });
   config.api.allowedOrigins = [...allowed];
 
-  for (const kind of ['plugins', 'themes']) {
+  for (const kind of ['plugins', 'themes', 'icons']) {
     config[kind].dirs = (config[kind].dirs ?? []).map((d) => (isAbsolute(d) ? d : resolve(root, d)));
   }
   if (config.entry) {

package/src/runtime/client.js

@@ -46,7 +46,7 @@ export class Client {
     this.host = new Host(config.host ?? {}, { win });
     this.dom = new DomWatcher({ onError: (error) => this.reportError(error, { where: 'dom' }) });
     this.styles = new StyleManager(win?.document);
-    this.ui = new UI({ host: this.host, openExternal: (url) => this.openExternal(url), onError: (error) => this.reportError(error, { where: 'ui' }) });
+    this.ui = new UI({ host: this.host, openExternal: (url) => this.openExternal(url), onError: (error) => this.reportError(error, { where: 'ui' }), icons: config.icons?.set });
     this.react = {
       fiberOf,
       propsOf,

package/src/runtime/ui.js

@@ -1,5 +1,5 @@
 import { SettingTypes } from './settings.js';
-import { builtinIcon } from '../shared/icons.js';
+import { builtinIcon, ICONS } from '../shared/icons.js';
 import { safeURL, toArray } from './util.js';
 
 /**
@@ -171,13 +171,45 @@ export const baseCSS = `
  */
 export class UI {
   #toastRoot = null;
+  #icons = new Map();
 
-  constructor({ host, openExternal, onError } = {}) {
+  constructor({ host, openExternal, onError, icons } = {}) {
     this.host = host;
     this.openExternal = openExternal ?? ((url) => globalThis.open?.(url, '_blank', 'noopener,noreferrer'));
     this.onError = onError ?? ((error) => console.error(error));
     this.h = h;
     this.svg = svg;
+    if (icons) this.registerIcons(icons);
+  }
+
+  /**
+   * Adds icons to this client app's set, as `{ name: '<svg…>' }`. They can be used by name anywhere an
+   * icon is accepted, exactly like the built-ins, and a name that matches a built-in replaces it, so a
+   * client app can swap the whole look without touching the framework. Markup is sanitized when drawn.
+   *
+   * The build registers `icons.dirs` and `icons.set` from the config automatically; plugins can call
+   * this to add their own. Names are matched case-insensitively in kebab-case or camelCase.
+   */
+  registerIcons(icons) {
+    for (const [name, markup] of Object.entries(icons ?? {})) {
+      if (typeof name !== 'string' || !name) continue;
+      if (typeof markup !== 'string' || !markup.includes('<svg')) {
+        this.onError(new TypeError(`Icon ${JSON.stringify(name)} must be SVG markup`));
+        continue;
+      }
+      this.#icons.set(name.replace(/-([a-z])/g, (_, c) => c.toUpperCase()), markup);
+    }
+    return this;
+  }
+
+  /** Every icon name this client app can use: the built-ins plus any registered ones. */
+  iconNames() {
+    return [...new Set([...Object.keys(ICONS), ...this.#icons.keys()])].sort();
+  }
+
+  /** Looks up an icon name: this client app's own icons first, then the built-ins. */
+  #lookupIcon(name) {
+    return this.#icons.get(name.replace(/-([a-z])/g, (_, c) => c.toUpperCase())) ?? builtinIcon(name);
   }
 
   #cls(...keys) {
@@ -213,11 +245,11 @@ export class UI {
     return h('div', { class: 'yc-empty' }, text);
   }
 
-  /** An icon: a built-in name ('rocket', 'puzzle', …), SVG markup (sanitized), an https/data image URL, or an element. */
+  /** An icon: a name ('rocket', 'puzzle', … or one registered by this client app), SVG markup (sanitized), an https/data image URL, or an element. */
   icon(source) {
     if (!source) return null;
     if (source instanceof Node) return h('span', { class: 'yc-icon' }, source);
-    if (typeof source === 'string' && !source.includes('<') && !/^(https?:|data:)/.test(source)) source = builtinIcon(source) ?? source;
+    if (typeof source === 'string' && !source.includes('<') && !/^(https?:|data:)/.test(source)) source = this.#lookupIcon(source) ?? source;
     const asSvg = svg(source);
     if (asSvg) return h('span', { class: 'yc-icon', attrs: { 'aria-hidden': 'true' } }, asSvg);
     const url = safeURL(source, { protocols: ['https:', 'data:'] });

package/src/shared/constants.js

@@ -1,5 +1,5 @@
 /** The framework version. Kept in step with package.json (a test checks it). */
-export const version = '0.1.4';
+export const version = '0.1.5';
 
 /**
  * The plugin API version. Plugins declare the one they were written for (`apiVersion`), and the

package/src/shared/icons.js

@@ -6,47 +6,75 @@
  *
  * Anywhere that takes an icon also still takes raw SVG markup, an https/data image URL, or an element;
  * names here are just a shortcut so client apps don't have to carry their own SVGs for common things.
+ *
+ * The icons are Lucide (https://lucide.dev), kept byte-for-byte as upstream draws them apart from the
+ * `width`/`height` attributes, which are dropped because CSS sizes them (`.yc-icon`). Lucide draws at
+ * a 2px stroke; to re-weight the whole set, set `stroke-width` on `.yc-icon svg` in CSS rather than
+ * editing the paths here, so the set stays easy to update from upstream.
+ *
+ * Lucide is ISC licensed, and the icons it inherits from Feather are MIT licensed. Both notices are
+ * reproduced in LICENSE, under "Third-party notices", and must be kept with any copy of this file.
+ *
+ * ISC: Copyright (c) 2026 Lucide Icons and Contributors.
+ * MIT: Copyright (c) 2013-present Cole Bemis (Feather).
+ *
+ * Generated from the upstream SVGs; see LICENSE for the full notices.
  */
 export const ICONS = Object.freeze({
   sparkles:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3v4M12 17v4M3 12h4M17 12h4M6.3 6.3l1.8 1.8M15.9 15.9l1.8 1.8M17.7 6.3l-1.8 1.8M8.1 15.9l-1.8 1.8"/><circle cx="12" cy="12" r="2.1"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z"/><path d="M20 2v4"/><path d="M22 4h-4"/><circle cx="4" cy="20" r="2"/></svg>',
   rocket:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M14.5 9.5c2-2 3-5 2.6-6.6-1.6-.4-4.6.6-6.6 2.6-1.8 1.8-4.3 5.2-5 7l2.9 3c1.9-.7 5.3-3.2 7-5Z"/><path d="M9 15l-3 3M13.5 6.5l4 4M8 16.5c0 1.5-1 2.5-3.5 3 .5-2.5 1.5-3.5 3-3.5Z"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5"/><path d="M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09"/><path d="M9 12a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.4 22.4 0 0 1-4 2z"/><path d="M9 12H4s.55-3.03 2-4c1.62-1.08 5 .05 5 .05"/></svg>',
   puzzle:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M9 4h3a1.5 1.5 0 0 1 0 3 1.5 1.5 0 0 0 0 3h3a1 1 0 0 1 1 1v3a1.5 1.5 0 0 1-3 0 1.5 1.5 0 0 0-3 0v3a1 1 0 0 1-1 1H6a1 1 0 0 1-1-1v-3a1.5 1.5 0 0 1 0-3 1.5 1.5 0 0 0 0-3V6a1 1 0 0 1 1-1h3V4Z"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15.39 4.39a1 1 0 0 0 1.68-.474 2.5 2.5 0 1 1 3.014 3.015 1 1 0 0 0-.474 1.68l1.683 1.682a2.414 2.414 0 0 1 0 3.414L19.61 15.39a1 1 0 0 1-1.68-.474 2.5 2.5 0 1 0-3.014 3.015 1 1 0 0 1 .474 1.68l-1.683 1.682a2.414 2.414 0 0 1-3.414 0L8.61 19.61a1 1 0 0 0-1.68.474 2.5 2.5 0 1 1-3.014-3.015 1 1 0 0 0 .474-1.68l-1.683-1.682a2.414 2.414 0 0 1 0-3.414L4.39 8.61a1 1 0 0 1 1.68.474 2.5 2.5 0 1 0 3.014-3.015 1 1 0 0 1-.474-1.68l1.683-1.682a2.414 2.414 0 0 1 3.414 0z"/></svg>',
   palette:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3a9 9 0 1 0 0 18c1.1 0 2-.9 2-2 0-.5-.2-1-.5-1.3-.3-.4-.5-.8-.5-1.3 0-1.1.9-2 2-2h2a4 4 0 0 0 4-4c0-4.4-4-7.4-9-7.4Z"/><circle cx="7.5" cy="12" r="1.1" fill="currentColor" stroke="none"/><circle cx="9.5" cy="8" r="1.1" fill="currentColor" stroke="none"/><circle cx="14.5" cy="8" r="1.1" fill="currentColor" stroke="none"/><circle cx="16.5" cy="12" r="1.1" fill="currentColor" stroke="none"/></svg>',
-  sliders:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 7h7M15 7h5M4 17h11M19 17h1M9 4.5v5M17 14.5v5"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 22a1 1 0 0 1 0-20 10 9 0 0 1 10 9 5 5 0 0 1-5 5h-2.25a1.75 1.75 0 0 0-1.4 2.8l.3.4a1.75 1.75 0 0 1-1.4 2.8z"/><circle cx="13.5" cy="6.5" r=".5" fill="currentColor"/><circle cx="17.5" cy="10.5" r=".5" fill="currentColor"/><circle cx="6.5" cy="12.5" r=".5" fill="currentColor"/><circle cx="8.5" cy="7.5" r=".5" fill="currentColor"/></svg>',
+  sliders: // lucide: sliders-horizontal
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 5H3"/><path d="M12 19H3"/><path d="M14 3v4"/><path d="M16 17v4"/><path d="M21 12h-9"/><path d="M21 19h-5"/><path d="M21 5h-7"/><path d="M8 10v4"/><path d="M8 12H3"/></svg>',
   info:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="M12 11v5"/><circle cx="12" cy="8" r=".2" fill="currentColor"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>',
   check:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M4.5 12.5l5 5 10-11"/></svg>',
-  x: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M6 6l12 12M18 6L6 18"/></svg>',
-  alertTriangle:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 4 3 20h18L12 4Z"/><path d="M12 10v4"/><circle cx="12" cy="17" r=".2" fill="currentColor"/></svg>',
-  alertCircle:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="M12 7.5v5.5"/><circle cx="12" cy="16.5" r=".2" fill="currentColor"/></svg>',
-  chevronRight:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M9 5l7 7-7 7"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>',
+  x:
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>',
+  alertTriangle: // lucide: triangle-alert
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>',
+  alertCircle: // lucide: circle-alert
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" x2="12" y1="8" y2="12"/><line x1="12" x2="12.01" y1="16" y2="16"/></svg>',
+  chevronRight: // lucide: chevron-right
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>',
   megaphone:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M3 11v2a2 2 0 0 0 2 2h1l9 4V5l-9 4H5a2 2 0 0 0-2 2Z"/><path d="M15 9.5a3.5 3.5 0 0 1 0 5"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M11 6a13 13 0 0 0 8.4-2.8A1 1 0 0 1 21 4v12a1 1 0 0 1-1.6.8A13 13 0 0 0 11 14H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2z"/><path d="M6 14a12 12 0 0 0 2.4 7.2 2 2 0 0 0 3.2-2.4A8 8 0 0 1 10 14"/><path d="M8 6v8"/></svg>',
   bell:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M6 10a6 6 0 1 1 12 0c0 3 1 4.5 2 5.5H4c1-1 2-2.5 2-5.5Z"/><path d="M10 19.5a2 2 0 0 0 4 0"/></svg>',
-  external:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M9 5H6a2 2 0 0 0-2 2v11a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2v-3"/><path d="M13 3h8v8"/><path d="M21 3 10 14"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10.268 21a2 2 0 0 0 3.464 0"/><path d="M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326"/></svg>',
+  external: // lucide: external-link
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 3h6v6"/><path d="M10 14 21 3"/><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/></svg>',
   heart:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20s-7.5-4.6-9.5-9.3C1.1 7.7 3 4.5 6.4 4.5c2 0 3.4 1.1 4.1 2.3.7-1.2 2.1-2.3 4.1-2.3 3.4 0 5.3 3.2 3.9 6.2C19.5 15.4 12 20 12 20Z"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5"/></svg>',
   copy:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><rect x="8.5" y="8.5" width="11.5" height="11.5" rx="2"/><path d="M15.5 8.5V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v7.5a2 2 0 0 0 2 2h2.5"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>',
   folder:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 7a2 2 0 0 1 2-2h4l2 2.5h7a2 2 0 0 1 2 2V17a2 2 0 0 1-2 2h-13a2 2 0 0 1-2-2V7Z"/></svg>',
-  shield:
-    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3l7 3v5c0 5-3.5 8-7 10-3.5-2-7-5-7-10V6l7-3Z"/><path d="M9 12l2 2 4-4.5"/></svg>',
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"/></svg>',
+  shield: // lucide: shield-check
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/><path d="m9 12 2 2 4-4"/></svg>',
+});
+
+/**
+ * Lucide's own names for icons whose key here differs, so `icon: 'triangle-alert'` works as well as
+ * `icon: 'alertTriangle'`. Keys are camelCase because names are camelised before lookup.
+ */
+const ALIASES = Object.freeze({
+  slidersHorizontal: 'sliders',
+  triangleAlert: 'alertTriangle',
+  circleAlert: 'alertCircle',
+  externalLink: 'external',
+  shieldCheck: 'shield',
+  close: 'x',
 });
 
-/** Looks up a built-in icon by name (case-insensitive). Returns raw SVG markup, or null. */
+/** Looks up a built-in icon by name (case-insensitive, kebab-case or camelCase). Returns raw SVG markup, or null. */
 export function builtinIcon(name) {
   if (typeof name !== 'string') return null;
-  return ICONS[name] ?? ICONS[name.replace(/-([a-z])/g, (_, c) => c.toUpperCase())] ?? null;
+  const camel = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  return ICONS[name] ?? ICONS[camel] ?? ICONS[ALIASES[camel]] ?? null;
 }

package/templates/init/yapin-client.config.js

@@ -22,6 +22,12 @@ export default defineConfig({
     dirs: ['./themes'],
   },
 
+  // Drop .svg files in ./icons to use them by name (icons/brand.svg -> icon: 'brand').
+  // A name matching a built-in replaces it. See docs/ui.md.
+  icons: {
+    dirs: ['./icons'],
+  },
+
   installer: {
     preset: 'default',
     marketing: './installer/marketing.json',

package/types/index.d.ts

@@ -96,6 +96,13 @@ export interface Config {
     customCSS?: { enabled?: boolean; title?: string; description?: string | null };
     user?: UserInstallConfig;
   };
+  /** Icons this client app adds to the built-in set, usable by name anywhere an `icon` is accepted. */
+  icons?: {
+    /** Folders with `.svg` icons; each is registered under its file name (`icons/brand.svg` -> `'brand'`). */
+    dirs?: string[];
+    /** Icons given inline as `{ name: '<svg…>' }`. Wins over a folder file of the same name, and a name matching a built-in replaces it. */
+    set?: Record<string, string>;
+  };
   pages?: {
     /** The nav label above the client app's pages (default: its name). */
     section?: string | null;
@@ -220,6 +227,8 @@ export interface BuildResult {
 export declare function build(config: Record<string, any>, options: { root: string; mode?: 'production' | 'development'; installer?: boolean; onStep?: (step: string) => void }): Promise<BuildResult>;
 export declare function findPlugins(dirs: string[]): string[];
 export declare function findThemes(dirs: string[]): string[];
+/** Every `.svg` in the folders, keyed by file name, with the root `<svg>` size stripped. */
+export declare function findIcons(dirs: string[]): Record<string, string>;
 export declare function runtimeConfig(config: Record<string, any>): Record<string, any>;
 
 export declare function pack(options: {

package/types/runtime.d.ts

@@ -84,6 +84,10 @@ export declare class UI {
   tag(text: string, variant?: 'warn' | 'danger'): HTMLElement;
   empty(text: string): HTMLElement;
   icon(source: string | Node): HTMLElement | null;
+  /** Adds icons to this client app's set as `{ name: '<svg…>' }`; a name matching a built-in replaces it. */
+  registerIcons(icons: Record<string, string>): this;
+  /** Every icon name available: the built-ins plus any registered. */
+  iconNames(): string[];
   button(options: { label: string; variant?: 'primary' | 'ghost' | 'danger'; small?: boolean; disabled?: boolean; title?: string; icon?: string; onClick?: (event: MouseEvent) => unknown }): HTMLButtonElement;
   link(options: { href: string; label?: string; title?: string }): HTMLElement;
   switch(options: { checked?: boolean; disabled?: boolean; label?: string; onChange?: (checked: boolean, event: Event) => void }): HTMLInputElement;