yapin.js-client 0.1.0 → 0.1.4

package/src/runtime/about.js

@@ -26,11 +26,11 @@ export class AboutPage {
     const c = this.client;
     const { build = {}, git = null } = c.manifest;
     const env = c.environment;
-    this.section('app', { title: null, order: 0 });
+    this.section('app', { title: null, order: 0, layout: 'header' });
     this.section('build', { title: 'Build', order: 10 });
     this.section('git', { title: 'Source', order: 20 });
     this.section('environment', { title: 'Environment', order: 30 });
-    this.section('links', { title: 'Links', order: 40 });
+    this.section('links', { title: 'Links', order: 40, layout: 'chips' });
 
     this.set('app.name', { label: 'Name', value: c.name, order: 0 });
     this.set('app.version', { label: 'Version', value: c.version, copy: true, order: 1 });
@@ -67,16 +67,20 @@ export class AboutPage {
 
     this.action('copy', {
       label: 'Copy debug info',
+      icon: 'copy',
       order: 0,
       run: async () => {
         await navigator.clipboard.writeText(this.debugInfo());
         c.ui.toast('Debug info copied', { type: 'success' });
       },
     });
+    if (c.welcome?.enabled) this.action('welcome', { label: 'Welcome screen', icon: 'sparkles', order: 3, variant: 'ghost', run: () => c.welcome.show() });
+    if (c.whatsNew?.enabled && c.whatsNew.config.entries?.length) this.action('whatsNew', { label: "What's new", icon: 'rocket', order: 4, variant: 'ghost', run: () => c.whatsNew.show() });
     if (c.native) {
-      this.action('folder', { label: 'Open data folder', order: 1, run: () => c.native.openFolder('data') });
+      this.action('folder', { label: 'Data folder', icon: 'folder', order: 1, variant: 'ghost', run: () => c.native.openFolder('data') });
       this.action('safeMode', {
-        label: c.safeMode ? 'Restart normally' : 'Restart in safe mode',
+        label: c.safeMode ? 'Restart normally' : 'Safe mode',
+        icon: 'shield',
         order: 2,
         variant: 'ghost',
         run: async () => {
@@ -103,14 +107,29 @@ export class AboutPage {
     }
   }
 
-  /** Adds or changes a section: section('support', { title: 'Support', order: 35 }). */
-  section(id, { title, order } = {}) {
+  /**
+   * Adds or changes a section: section('support', { title: 'Support', order: 35, layout: 'rows' }).
+   * Layouts: 'rows' (label and value, the default), 'chips' (compact pills, for links) and 'header'
+   * (the card at the top: its `name`, `version` and `description` fields become the title, a version
+   * tag and the line under it; any other field is shown small underneath).
+   */
+  section(id, { title, order, layout } = {}) {
     const existing = this.#sections.get(id);
-    this.#sections.set(id, { id, title: title === undefined ? existing?.title ?? id : title, order: order ?? existing?.order ?? 100 });
+    this.#sections.set(id, {
+      id,
+      title: title === undefined ? existing?.title ?? id : title,
+      order: order ?? existing?.order ?? 100,
+      layout: LAYOUTS.has(layout) ? layout : existing?.layout ?? 'rows',
+    });
     this.#changed();
     return this;
   }
 
+  /** The sections, in order: [{ id, title, order, layout }]. */
+  sections() {
+    return this.#sortedSections().map((s) => ({ ...s }));
+  }
+
   removeSection(id) {
     this.#sections.delete(id);
     for (const key of [...this.#fields.keys()]) if (key.startsWith(`${id}.`)) this.#fields.delete(key);
@@ -148,10 +167,10 @@ export class AboutPage {
     return [...this.#fields.values()].map((f) => ({ ...f }));
   }
 
-  /** A button at the bottom of the page: action('report', { label, run, variant, order }). */
-  action(id, { label, run, variant = 'primary', order = 100 } = {}) {
+  /** A button under the header: action('report', { label, icon, run, variant, order }). */
+  action(id, { label, icon = null, run, variant = 'primary', order = 100 } = {}) {
     if (typeof run !== 'function') throw new ClientError(ErrorCodes.InvalidDefinition, `About action "${id}" needs a run function`);
-    this.#actions.set(id, { id, label: label ?? id, run, variant, order });
+    this.#actions.set(id, { id, label: label ?? id, icon, run, variant, order });
     this.#changed();
     return this;
   }
@@ -196,16 +215,22 @@ export class AboutPage {
   render(root, ctx) {
     const { ui } = this.client;
     const draw = () => {
-      const parts = [ui.heading(this.config.title ?? 'About')];
-      if (this.config.intro) parts.push(ui.hint(this.config.intro));
-      for (const section of this.#sortedSections()) {
-        const fields = this.#sortedFields(section.id);
-        if (!fields.length) continue;
-        parts.push(ui.section({ title: section.title, children: [ui.keyValue(fields.map((f) => ({ label: f.label, value: this.#value(f) })))] }));
-      }
-      const actions = [...this.#actions.values()].sort((a, b) => a.order - b.order);
-      if (actions.length) parts.push(h('div', { class: 'yc-row', style: { marginTop: '16px' } }, actions.map((a) => ui.button({ label: a.label, variant: a.variant, small: true, onClick: () => a.run(this.client) }))));
-      root.replaceChildren(...parts);
+      const sections = this.#sortedSections()
+        .map((section) => ({ ...section, fields: this.#sortedFields(section.id) }))
+        .filter((section) => section.fields.length);
+      const header = sections.find((s) => s.layout === 'header');
+      const cards = sections.filter((s) => s !== header);
+      root.replaceChildren(
+        ui.heading(this.config.title ?? 'About'),
+        h(
+          'div',
+          { class: 'yc-about' },
+          header && this.#header(header),
+          this.config.intro && ui.hint(this.config.intro),
+          this.#actionBar(),
+          cards.length > 0 && h('div', { class: 'yc-about-grid' }, cards.map((s) => this.#card(s))),
+        ),
+      );
     };
     this.onChange = draw;
     draw();
@@ -214,29 +239,94 @@ export class AboutPage {
     });
   }
 
-  #value(field) {
+  #header(section) {
     const { ui } = this.client;
-    const text = valueText(field);
-    const content = field.href ? ui.link({ href: field.href, label: text }) : field.code ? h('code', null, text) : text;
-    if (!field.copy) return content;
-    const copyText = field.copy === true ? text : String(field.copy);
+    const field = (name) => section.fields.find((f) => f.id === `${section.id}.${name}`);
+    const [name, version, description] = [field('name'), field('version'), field('description')];
+    const rest = section.fields.filter((f) => f !== name && f !== version && f !== description);
+    const title = name ? valueText(name) : this.client.name;
+    const logo = this.config.logo ? ui.icon(this.config.logo) : null;
     return h(
-      'span',
-      { class: 'yc-row' },
-      content,
-      ui.button({
-        label: 'Copy',
-        small: true,
-        variant: 'ghost',
-        onClick: async () => {
-          await navigator.clipboard.writeText(copyText);
-          ui.toast('Copied', { type: 'success', timeout: 1500 });
-        },
+      'div',
+      { class: 'yc-about-header', dataset: { section: section.id } },
+      h('div', { class: 'yc-about-logo', attrs: { 'aria-hidden': 'true' } }, logo ?? title.trim().charAt(0).toUpperCase()),
+      h(
+        'div',
+        { class: 'yc-grow' },
+        h('div', { class: 'yc-about-title' }, title, version && h('span', { class: 'yc-about-version' }, `v${valueText(version).replace(/^v/, '')}`, version.copy && this.#copyButton(version))),
+        description && h('div', { class: 'yc-about-desc' }, valueText(description)),
+        rest.length > 0 && h('div', { class: 'yc-about-meta' }, rest.map((f) => h('span', null, h('span', { class: 'yc-about-label' }, f.label), ' ', this.#value(f)))),
+      ),
+    );
+  }
+
+  #actionBar() {
+    const { ui } = this.client;
+    const actions = [...this.#actions.values()].sort((a, b) => a.order - b.order);
+    if (!actions.length) return null;
+    return h('div', { class: 'yc-about-actions' }, actions.map((a) => ui.button({ label: a.label, icon: a.icon, variant: a.variant, small: true, onClick: () => a.run(this.client) })));
+  }
+
+  #card(section) {
+    return h(
+      'section',
+      { class: 'yc-about-card', dataset: { section: section.id, layout: section.layout } },
+      section.title && h('div', { class: 'yc-section-title' }, section.title),
+      section.layout === 'chips' ? this.#chips(section.fields) : this.#rows(section.fields),
+    );
+  }
+
+  #rows(fields) {
+    return h(
+      'dl',
+      { class: 'yc-about-rows' },
+      fields.flatMap((f) => [h('dt', null, f.label), h('dd', null, this.#value(f))]),
+    );
+  }
+
+  #chips(fields) {
+    const { ui } = this.client;
+    return h(
+      'div',
+      { class: 'yc-about-chips' },
+      fields.map((f) => {
+        if (f.href) return h(ui.link({ href: f.href, label: f.label, title: valueText(f) }), { class: 'yc-about-chip' }, ui.icon('external'));
+        return h('span', { class: 'yc-about-chip', title: f.label }, this.#value(f));
       }),
     );
   }
+
+  #value(field) {
+    const { ui } = this.client;
+    const text = valueText(field);
+    const content = field.href ? ui.link({ href: field.href, label: text }) : field.code ? h('code', null, text) : text;
+    return h('span', { class: 'yc-about-value', title: text }, h('span', { class: 'yc-about-text' }, content), field.copy && this.#copyButton(field));
+  }
+
+  #copyButton(field) {
+    const { ui } = this.client;
+    const text = field.copy === true ? valueText(field) : String(field.copy);
+    const button = h('button', {
+      type: 'button',
+      class: 'yc-about-copy',
+      title: `Copy ${field.label.toLowerCase()}`,
+      attrs: { 'aria-label': `Copy ${field.label.toLowerCase()}` },
+      onClick: async () => {
+        try {
+          await navigator.clipboard.writeText(text);
+          button.replaceChildren(ui.icon('check'));
+          setTimeout(() => button.isConnected && button.replaceChildren(ui.icon('copy')), 1200);
+        } catch (error) {
+          ui.toast(`Couldn't copy: ${error?.message ?? error}`, { type: 'error' });
+        }
+      },
+    }, ui.icon('copy'));
+    return button;
+  }
 }
 
+const LAYOUTS = new Set(['rows', 'chips', 'header']);
+
 function valueText(field) {
   try {
     const value = typeof field.value === 'function' ? field.value() : field.value;

package/src/runtime/builtin-pages.js

@@ -27,7 +27,7 @@ export function pluginsPage(client, config = {}) {
     id: 'plugins',
     title: config.title ?? 'Plugins',
     order: config.order ?? 10,
-    icon: config.icon ?? null,
+    icon: config.icon ?? 'puzzle',
     render(root, ctx) {
       const { ui } = client;
       let query = '';
@@ -142,7 +142,7 @@ export function themesPage(client, config = {}) {
     id: 'themes',
     title: config.title ?? 'Themes',
     order: config.order ?? 20,
-    icon: config.icon ?? null,
+    icon: config.icon ?? 'palette',
     render(root, ctx) {
       const { ui } = client;
       let query = '';

package/src/runtime/client.js

@@ -7,6 +7,7 @@ import { Emitter } from './events.js';
 import { Host } from './host.js';
 import { Logger } from './logger.js';
 import { ModuleFinder } from './modules.js';
+import { Welcome, WhatsNew, onboardingCSS } from './onboarding.js';
 import { PageManager } from './pages.js';
 import { Patcher } from './patcher.js';
 import { PluginManager } from './plugins.js';
@@ -63,6 +64,8 @@ export class Client {
     this.plugins = new PluginManager(this, config.plugins ?? {}, { loadModule });
     this.badges = new BadgeManager(this, config.badges ?? {});
     this.userContent = new UserContent(this, { plugins: config.plugins ?? {}, themes: config.themes ?? {} });
+    this.welcome = config.welcome === false ? null : new Welcome(this, config.welcome ?? {});
+    this.whatsNew = config.whatsNew === false ? null : new WhatsNew(this, config.whatsNew ?? {});
     this.about = config.about === false ? null : new AboutPage(this, config.about ?? {});
     this.ready = new Promise((resolve) => {
       this.#readyResolve = resolve;
@@ -99,6 +102,7 @@ export class Client {
   async start(bundle = {}) {
     const config = this.config;
     this.styles.add(baseCSS, { id: 'framework', order: StyleOrder.framework });
+    this.styles.add(onboardingCSS, { id: 'framework-onboarding', order: StyleOrder.framework });
     for (const theme of bundle.themes ?? []) {
       try {
         this.themes.add(this.themes.parse(theme.text, { file: theme.file, source: 'bundled' }), { source: 'bundled', file: theme.file });
@@ -146,6 +150,11 @@ export class Client {
     this.badges.start();
     await this.plugins.startAll();
     if (this.safeMode) this.ui.toast(`${this.name} is in safe mode: plugins and themes are off.`, { type: 'warning', timeout: 8000 });
+    try {
+      this.#maybeShowOnboarding();
+    } catch (error) {
+      this.reportError(error, { where: 'welcome/what\'s new' });
+    }
     this.isReady = true;
     this.#readyResolve(this);
     this.events.emit('ready', this);
@@ -156,7 +165,7 @@ export class Client {
   #addBuiltinPages() {
     const pages = this.config.pages ?? {};
     if (this.about) {
-      this.pages.add({ id: 'about', title: this.config.about?.title ?? 'About', order: this.config.about?.order ?? 0, icon: this.config.about?.icon ?? null, render: (root, ctx) => this.about.render(root, ctx) });
+      this.pages.add({ id: 'about', title: this.config.about?.title ?? 'About', order: this.config.about?.order ?? 0, icon: this.config.about?.icon ?? 'info', render: (root, ctx) => this.about.render(root, ctx) });
     }
     if (pages.plugins !== false) this.pages.add(pluginsPage(this, pages.plugins ?? {}));
     if (pages.themes !== false) this.pages.add(themesPage(this, pages.themes ?? {}));
@@ -166,6 +175,7 @@ export class Client {
         id: 'settings',
         title: options.title ?? 'Settings',
         order: options.order ?? 5,
+        icon: options.icon ?? 'sliders',
         render: (root, ctx) => {
           const form = this.ui.form(this.settings, { context: this });
           root.append(this.ui.heading(options.title ?? 'Settings'), form.element);
@@ -175,6 +185,16 @@ export class Client {
     }
   }
 
+  /** First run shows the welcome screen (and skips what's new for that first run); otherwise an update shows what's new. */
+  #maybeShowOnboarding() {
+    if (this.welcome?.shouldShow()) {
+      this.welcome.show();
+      this.whatsNew?.markSeen();
+    } else {
+      this.whatsNew?.maybeShow();
+    }
+  }
+
   /** Stops plugins, removes styles and flushes storage. Mostly for tests and development reloads. */
   stop() {
     this.plugins.stopAll();

package/src/runtime/onboarding.js

@@ -0,0 +1,196 @@
+import { h } from './ui.js';
+
+/**
+ * The rounded-corner "Welcome" screen a client app shows the first time it runs with no saved state,
+ * and the "What's new" screen it shows after an update. Both are entirely optional (`welcome: false` /
+ * `whatsNew: false`), entirely editable from the config (title, icon, steps/entries, labels), and can
+ * be replayed at any time with `client.welcome.show()` / `client.whatsNew.show()`.
+ */
+const SEEN_NAMESPACE = 'onboarding';
+
+function fill(text, client) {
+  if (typeof text !== 'string') return text;
+  return text.replace(/\{name\}/g, client.name).replace(/\{version\}/g, client.version);
+}
+
+/** Builds the shared rounded, animated panel. Returns the backdrop element; caller appends it. */
+function panel(client, { icon, title, subtitle, rows = [], actionLabel, dismissLabel, dismissable = true, onAction, onDismiss, onClose }) {
+  const { ui } = client;
+  const doc = globalThis.document;
+  let settled = false;
+  const finish = (fn) => {
+    if (settled) return;
+    settled = true;
+    backdrop.classList.add('yc-onboard-leave');
+    doc.removeEventListener('keydown', onKey, true);
+    setTimeout(() => backdrop.remove(), 180);
+    fn?.();
+    onClose?.();
+  };
+  const onKey = (event) => {
+    if (event.key === 'Escape' && dismissable) {
+      event.stopPropagation();
+      finish(onDismiss);
+    }
+  };
+  const rowsEl = rows.map((row, index) =>
+    h(
+      'div',
+      { class: 'yc-onboard-row', style: { '--yc-i': String(index) } },
+      row.icon !== false && h('div', { class: 'yc-onboard-row-icon' }, ui.icon(row.icon ?? 'sparkles')),
+      h('div', { class: 'yc-onboard-row-body' }, h('div', { class: 'yc-onboard-row-title' }, row.title), row.description && h('div', { class: 'yc-onboard-row-desc' }, row.description)),
+    ),
+  );
+  const buttons = [];
+  if (dismissable && dismissLabel) buttons.push(ui.button({ label: dismissLabel, variant: 'ghost', onClick: () => finish(onDismiss) }));
+  buttons.push(ui.button({ label: actionLabel, variant: 'primary', onClick: () => finish(onAction) }));
+  const dialog = h(
+    'div',
+    { class: 'yc-onboard', attrs: { role: 'dialog', 'aria-modal': 'true' } },
+    dismissable && h('button', { type: 'button', class: 'yc-onboard-close', attrs: { 'aria-label': 'Dismiss' }, onClick: () => finish(onDismiss) }, ui.icon('x')),
+    h('div', { class: 'yc-onboard-hero' }, h('div', { class: 'yc-onboard-hero-glow' }), h('div', { class: 'yc-onboard-hero-icon' }, ui.icon(icon ?? 'sparkles'))),
+    h('h2', { class: 'yc-onboard-title' }, title),
+    subtitle && h('p', { class: 'yc-onboard-subtitle' }, subtitle),
+    rowsEl.length ? h('div', { class: 'yc-onboard-rows' }, rowsEl) : null,
+    h('div', { class: 'yc-onboard-actions' }, buttons),
+  );
+  const backdrop = h('div', { class: 'yc-onboard-backdrop', onMousedown: (event) => event.target === backdrop && dismissable && finish(onDismiss) }, dialog);
+  doc.addEventListener('keydown', onKey, true);
+  return backdrop;
+}
+
+class OnboardingScreen {
+  constructor(client, config, storageKey) {
+    this.client = client;
+    this.config = config ?? {};
+    this.storageKey = storageKey;
+  }
+
+  get enabled() {
+    return this.config !== false && this.config?.enabled !== false;
+  }
+
+  #store() {
+    return this.client.storage.namespace(SEEN_NAMESPACE);
+  }
+
+  /** Marks the screen as seen without showing it, so it won't appear next time either. */
+  markSeen() {
+    this.#store().set(this.storageKey, this.client.version);
+  }
+
+  /** Clears the seen flag so it shows again next time the client app starts (or call show() now). */
+  reset() {
+    this.#store().delete(this.storageKey);
+  }
+}
+
+/** Shown the first time the client app runs (nothing saved yet). `welcome: false` turns it off. */
+export class Welcome extends OnboardingScreen {
+  constructor(client, config) {
+    super(client, config, 'welcomeSeenVersion');
+  }
+
+  shouldShow() {
+    return this.enabled && !this.#store().has(this.storageKey);
+  }
+
+  #store() {
+    return this.client.storage.namespace(SEEN_NAMESPACE);
+  }
+
+  /** Shows the welcome screen right now, regardless of whether it's been seen. */
+  show() {
+    const doc = globalThis.document;
+    if (!doc?.body) return () => {};
+    const { client, config } = this;
+    const backdrop = panel(client, {
+      icon: config.icon ?? 'sparkles',
+      title: fill(config.title ?? 'Welcome to {name}', client),
+      subtitle: fill(config.subtitle ?? null, client),
+      rows: (config.steps ?? []).map((s) => ({ icon: s.icon, title: fill(s.title, client), description: fill(s.description, client) })),
+      actionLabel: config.actionLabel ?? 'Get started',
+      dismissLabel: config.dismissible === false ? null : config.dismissLabel ?? 'Skip',
+      dismissable: config.dismissible !== false,
+      onAction: () => this.markSeen(),
+      onDismiss: () => this.markSeen(),
+    });
+    doc.body.appendChild(backdrop);
+    return () => backdrop.remove();
+  }
+
+  maybeShow() {
+    if (this.shouldShow()) this.show();
+  }
+}
+
+/** Shown after an update, once, when there are entries configured. `whatsNew: false` turns it off. */
+export class WhatsNew extends OnboardingScreen {
+  constructor(client, config) {
+    super(client, config, 'whatsNewSeenVersion');
+  }
+
+  shouldShow() {
+    if (!this.enabled || !(this.config.entries ?? []).length) return false;
+    return this.#store().get(this.storageKey) !== this.client.version;
+  }
+
+  #store() {
+    return this.client.storage.namespace(SEEN_NAMESPACE);
+  }
+
+  /** Shows the what's new screen right now, regardless of version. */
+  show() {
+    const doc = globalThis.document;
+    if (!doc?.body) return () => {};
+    const { client, config } = this;
+    const backdrop = panel(client, {
+      icon: config.icon ?? 'rocket',
+      title: fill(config.title ?? "What's new in {name} {version}", client),
+      subtitle: fill(config.subtitle ?? null, client),
+      rows: (config.entries ?? []).map((e) => ({ icon: e.icon, title: fill(e.title, client), description: fill(e.description, client) })),
+      actionLabel: config.actionLabel ?? 'Got it',
+      dismissLabel: config.dismissible === false ? null : config.dismissLabel ?? null,
+      dismissable: config.dismissible !== false,
+      onAction: () => this.markSeen(),
+      onDismiss: () => this.markSeen(),
+    });
+    doc.body.appendChild(backdrop);
+    return () => backdrop.remove();
+  }
+
+  maybeShow() {
+    if (this.shouldShow()) this.show();
+  }
+}
+
+export const onboardingCSS = `
+.yc-onboard-backdrop{position:fixed;inset:0;z-index:2147483100;background:#0009;display:flex;align-items:center;justify-content:center;padding:20px;animation:yc-onboard-fade .18s ease-out}
+.yc-onboard-backdrop.yc-onboard-leave{animation:yc-onboard-fade .18s ease-in reverse}
+.yc-onboard-backdrop.yc-onboard-leave .yc-onboard{animation:yc-onboard-in .18s ease-in reverse}
+.yc-onboard{position:relative;background:var(--bg-float,#1b1c21);color:var(--text,#ececf1);border:1px solid var(--border);border-radius:20px;box-shadow:var(--shadow,0 20px 60px #0008);width:min(440px,100%);max-height:90vh;overflow:auto;padding:28px 26px 24px;text-align:center;animation:yc-onboard-in .22s cubic-bezier(.2,.8,.2,1)}
+.yc-onboard-close{position:absolute;top:14px;right:14px;width:28px;height:28px;border-radius:999px;border:none;background:var(--bg-active,#2a2b31);color:var(--text-muted);display:flex;align-items:center;justify-content:center;cursor:pointer;padding:0}
+.yc-onboard-close:hover{background:var(--bg-hover,#34353c);color:var(--text)}
+.yc-onboard-close .yc-icon{width:14px;height:14px}
+.yc-onboard-hero{position:relative;width:64px;height:64px;margin:0 auto 14px;display:flex;align-items:center;justify-content:center}
+.yc-onboard-hero-glow{position:absolute;inset:0;border-radius:999px;background:radial-gradient(circle,var(--accent) 0%,transparent 70%);opacity:.35;animation:yc-onboard-pulse 2.4s ease-in-out infinite}
+.yc-onboard-hero-icon{position:relative;width:64px;height:64px;border-radius:999px;background:var(--bg-active,#2a2b31);border:1px solid var(--border);display:flex;align-items:center;justify-content:center;color:var(--accent);animation:yc-onboard-pop .4s cubic-bezier(.2,.8,.2,1) .05s backwards}
+.yc-onboard-hero-icon .yc-icon{width:28px;height:28px}
+.yc-onboard-title{margin:0 0 6px;font-size:20px;font-weight:700}
+.yc-onboard-subtitle{margin:0 0 18px;color:var(--text-muted);font-size:14px;line-height:1.5}
+.yc-onboard-rows{display:flex;flex-direction:column;gap:12px;text-align:left;margin-bottom:20px}
+.yc-onboard-row{display:flex;gap:12px;align-items:flex-start;opacity:0;animation:yc-onboard-row-in .35s ease-out forwards;animation-delay:calc(120ms + var(--yc-i) * 70ms)}
+.yc-onboard-row-icon{flex-shrink:0;width:34px;height:34px;border-radius:10px;background:var(--bg-active,#2a2b31);display:flex;align-items:center;justify-content:center;color:var(--accent)}
+.yc-onboard-row-icon .yc-icon{width:18px;height:18px}
+.yc-onboard-row-title{font-weight:600;font-size:14px}
+.yc-onboard-row-desc{color:var(--text-muted);font-size:13px;margin-top:2px;line-height:1.4}
+.yc-onboard-actions{display:flex;justify-content:center;gap:10px}
+@keyframes yc-onboard-fade{from{opacity:0}to{opacity:1}}
+@keyframes yc-onboard-in{from{opacity:0;transform:translateY(14px) scale(.96)}to{opacity:1;transform:none}}
+@keyframes yc-onboard-pop{from{opacity:0;transform:scale(.6)}to{opacity:1;transform:none}}
+@keyframes yc-onboard-pulse{0%,100%{opacity:.25;transform:scale(1)}50%{opacity:.45;transform:scale(1.15)}}
+@keyframes yc-onboard-row-in{from{opacity:0;transform:translateX(-6px)}to{opacity:1;transform:none}}
+@media (prefers-reduced-motion:reduce){
+  .yc-onboard-backdrop,.yc-onboard,.yc-onboard-hero-icon,.yc-onboard-hero-glow,.yc-onboard-row{animation:none!important;opacity:1!important;transform:none!important}
+}
+`;

package/src/runtime/ui.js

@@ -1,4 +1,5 @@
 import { SettingTypes } from './settings.js';
+import { builtinIcon } from '../shared/icons.js';
 import { safeURL, toArray } from './util.js';
 
 /**
@@ -57,7 +58,10 @@ const SVG_ALLOWED = new Set([
  */
 export function svg(markup) {
   if (typeof markup !== 'string' || !markup.includes('<svg')) return null;
-  const parsed = new DOMParser().parseFromString(markup, 'image/svg+xml');
+  // Parsed as XML, an <svg> without xmlns is a plain element that draws nothing; inline-HTML markup often leaves it out.
+  let source = /<svg\b[^>]*\sxmlns=/.test(markup) ? markup : markup.replace(/<svg\b/, '<svg xmlns="http://www.w3.org/2000/svg"');
+  if (source.includes('xlink:') && !/\sxmlns:xlink=/.test(source)) source = source.replace(/<svg\b/, '<svg xmlns:xlink="http://www.w3.org/1999/xlink"');
+  const parsed = new DOMParser().parseFromString(source, 'image/svg+xml');
   const root = parsed.documentElement;
   if (!root || root.nodeName.toLowerCase() !== 'svg' || parsed.querySelector('parsererror')) return null;
   const clean = (node) => {
@@ -77,6 +81,8 @@ export function svg(markup) {
   return globalThis.document.importNode(root, true);
 }
 
+const TOAST_ICONS = { info: 'info', success: 'check', warning: 'alertTriangle', error: 'alertCircle' };
+
 export const baseCSS = `
 .yc-page{display:flex;flex-direction:column;gap:4px;min-width:0}
 .yc-page h2{margin:0 0 12px}
@@ -89,7 +95,33 @@ export const baseCSS = `
 .yc-kv{display:grid;grid-template-columns:minmax(120px,max-content) 1fr;gap:8px 16px;align-items:baseline;padding:10px 0;border-bottom:1px solid var(--border)}
 .yc-kv dt{color:var(--text-muted);font-size:13px}
 .yc-kv dd{margin:0;word-break:break-word;font-size:14px}
-.yc-kv code,.yc-code{font-family:ui-monospace,SFMono-Regular,Consolas,monospace;font-size:12.5px;background:var(--bg-input);border-radius:6px;padding:1px 6px}
+.yc-about{display:flex;flex-direction:column;gap:12px}
+.yc-about-header{display:flex;gap:14px;align-items:center;background:var(--bg-elev);border:1px solid var(--border);border-radius:var(--radius,10px);padding:14px 16px}
+.yc-about-logo{width:48px;height:48px;border-radius:12px;flex-shrink:0;display:flex;align-items:center;justify-content:center;background:color-mix(in srgb,var(--accent) 18%,transparent);color:var(--accent);font-size:22px;font-weight:700}
+.yc-about-logo .yc-icon{width:26px;height:26px}
+.yc-about-title{display:flex;align-items:center;gap:8px;flex-wrap:wrap;font-size:17px;font-weight:700}
+.yc-about-version{display:inline-flex;align-items:center;gap:2px;font-size:11.5px;font-weight:600;padding:1px 4px 1px 8px;border-radius:999px;background:var(--bg-active);color:var(--text-muted)}
+.yc-about-desc{color:var(--text-muted);font-size:13px;margin-top:2px}
+.yc-about-meta{display:flex;flex-wrap:wrap;gap:2px 14px;font-size:12.5px;margin-top:6px}
+.yc-about-label{color:var(--text-muted)}
+.yc-about-actions{display:flex;flex-wrap:wrap;gap:6px}
+.yc-about-actions .yc-icon{width:15px;height:15px;margin-right:4px}
+.yc-about-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(250px,1fr));gap:10px}
+.yc-about-card{background:var(--bg-elev);border:1px solid var(--border);border-radius:var(--radius,10px);padding:10px 14px;min-width:0}
+.yc-about-rows{display:grid;grid-template-columns:max-content minmax(0,1fr);gap:4px 12px;margin:0;font-size:13px;align-items:center}
+.yc-about-rows dt{color:var(--text-muted)}
+.yc-about-rows dd{margin:0;min-width:0}
+.yc-about-value{display:inline-flex;align-items:center;gap:2px;max-width:100%;min-width:0;vertical-align:middle}
+.yc-about-text{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;min-width:0}
+.yc-about-copy{display:inline-flex;flex-shrink:0;border:0;background:none;color:var(--text-muted);cursor:pointer;padding:2px;border-radius:5px}
+.yc-about-copy:hover{background:var(--bg-hover);color:var(--text)}
+.yc-about-copy .yc-icon{width:14px;height:14px}
+.yc-about-chips{display:flex;flex-wrap:wrap;gap:6px}
+.yc-about-chip{display:inline-flex;align-items:center;gap:5px;max-width:100%;padding:3px 10px;border-radius:999px;background:var(--bg-active);font-size:12.5px;color:var(--text)}
+.yc-page a.yc-about-chip{color:var(--text)}
+.yc-page a.yc-about-chip:hover{text-decoration:none;background:var(--bg-hover)}
+.yc-about-chip .yc-icon{width:13px;height:13px;color:var(--text-muted)}
+.yc-kv code,.yc-about code,.yc-code{font-family:ui-monospace,SFMono-Regular,Consolas,monospace;font-size:12.5px;background:var(--bg-input);border-radius:6px;padding:1px 6px}
 .yc-card{background:var(--bg-elev);border:1px solid var(--border);border-radius:var(--radius,10px);padding:12px 14px;margin:8px 0}
 .yc-card-head{display:flex;align-items:center;gap:10px}
 .yc-card-title{font-weight:600}
@@ -111,10 +143,18 @@ export const baseCSS = `
 .yc-toasts{position:fixed;z-index:2147483000;bottom:20px;left:50%;transform:translateX(-50%);display:flex;flex-direction:column;gap:8px;align-items:center;pointer-events:none}
 .yc-toast{pointer-events:auto;background:var(--bg-float,#1b1c21);color:var(--text,#ececf1);border:1px solid var(--border);box-shadow:var(--shadow);border-radius:var(--radius,10px);padding:10px 14px;font-size:14px;max-width:min(520px,90vw);display:flex;gap:10px;align-items:center;animation:yc-in .15s ease-out}
 .yc-toast[data-type=success]{border-left:3px solid var(--success,#3fcf82)}
+.yc-toast[data-type=success] .yc-icon{color:var(--success,#3fcf82)}
 .yc-toast[data-type=error]{border-left:3px solid var(--danger,#f2555a)}
+.yc-toast[data-type=error] .yc-icon{color:var(--danger,#f2555a)}
 .yc-toast[data-type=warning]{border-left:3px solid var(--warning,#f5b544)}
+.yc-toast[data-type=warning] .yc-icon{color:var(--warning,#f5b544)}
+.yc-toast[data-type=info] .yc-icon{color:var(--accent)}
 .yc-backdrop{position:fixed;inset:0;z-index:2147482000;background:#0009;display:flex;align-items:center;justify-content:center;padding:16px;animation:yc-in .12s ease-out}
 .yc-dialog{background:var(--bg-float,#1b1c21);color:var(--text,#ececf1);border:1px solid var(--border);border-radius:calc(var(--radius,10px) + 4px);box-shadow:var(--shadow);width:min(460px,100%);max-height:90vh;overflow:auto;padding:20px}
+.yc-dialog-head{display:flex;align-items:center;gap:10px}
+.yc-dialog-head .yc-icon{width:22px;height:22px;color:var(--accent);flex-shrink:0}
+.yc-dialog-head.yc-danger .yc-icon{color:var(--danger,#f2555a)}
+.yc-dialog-head h3{margin:0 0 8px;font-size:18px}
 .yc-dialog h3{margin:0 0 8px;font-size:18px}
 .yc-dialog p{margin:0 0 12px;color:var(--text-muted);white-space:pre-wrap}
 .yc-dialog-actions{display:flex;justify-content:flex-end;gap:8px;margin-top:16px}
@@ -173,10 +213,11 @@ export class UI {
     return h('div', { class: 'yc-empty' }, text);
   }
 
-  /** An icon from SVG markup (sanitized), an https/data image URL, or an element. */
+  /** An icon: a built-in name ('rocket', 'puzzle', …), 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;
     const asSvg = svg(source);
     if (asSvg) return h('span', { class: 'yc-icon', attrs: { 'aria-hidden': 'true' } }, asSvg);
     const url = safeURL(source, { protocols: ['https:', 'data:'] });
@@ -392,22 +433,22 @@ export class UI {
   }
 
   /** Shows a short message at the bottom of the window. type: info | success | warning | error. */
-  toast(message, { type = 'info', timeout = 4000, action } = {}) {
+  toast(message, { type = 'info', timeout = 4000, action, icon = TOAST_ICONS[type] } = {}) {
     const doc = globalThis.document;
     if (!doc?.body) return () => {};
     if (!this.#toastRoot?.isConnected) {
       this.#toastRoot = h('div', { class: 'yc-toasts', attrs: { role: 'status', 'aria-live': 'polite' } });
       doc.body.appendChild(this.#toastRoot);
     }
-    const element = h('div', { class: 'yc-toast', dataset: { type } }, h('span', { class: 'yc-grow' }, message), action && this.button({ label: action.label, small: true, variant: 'ghost', onClick: () => (close(), action.onClick()) }));
+    const element = h('div', { class: 'yc-toast', dataset: { type } }, this.icon(icon), h('span', { class: 'yc-grow' }, message), action && this.button({ label: action.label, small: true, variant: 'ghost', onClick: () => (close(), action.onClick()) }));
     const close = () => element.remove();
     this.#toastRoot.appendChild(element);
     if (timeout > 0) setTimeout(close, timeout);
     return close;
   }
 
-  /** A modal dialog. Resolves with the value of the button pressed, or null when dismissed. */
-  dialog({ title, message, content, buttons = [{ label: 'OK', value: true }], dismissable = true } = {}) {
+  /** A modal dialog. Resolves with the value of the button pressed, or null when dismissed. `icon` shows next to the title. */
+  dialog({ title, icon, message, content, buttons = [{ label: 'OK', value: true }], dismissable = true } = {}) {
     const doc = globalThis.document;
     if (!doc?.body) return Promise.resolve(null);
     return new Promise((resolve) => {
@@ -426,7 +467,8 @@ export class UI {
         }
       };
       const actions = buttons.map((b) => this.button({ label: b.label, variant: b.variant ?? 'primary', onClick: async () => finish(typeof b.value === 'function' ? await b.value() : b.value) }));
-      const dialog = h('div', { class: 'yc-dialog', attrs: { role: 'dialog', 'aria-modal': 'true' } }, title && h('h3', null, title), message && h('p', null, message), content, h('div', { class: 'yc-dialog-actions' }, actions));
+      const head = title && (icon ? h('div', { class: ['yc-dialog-head', buttons.some((b) => b.variant === 'danger') && 'yc-danger'] }, this.icon(icon), h('h3', null, title)) : h('h3', null, title));
+      const dialog = h('div', { class: 'yc-dialog', attrs: { role: 'dialog', 'aria-modal': 'true' } }, head, message && h('p', null, message), content, h('div', { class: 'yc-dialog-actions' }, actions));
       const backdrop = h('div', { class: 'yc-backdrop', onMousedown: (event) => event.target === backdrop && dismissable && finish(null) }, dialog);
       doc.addEventListener('keydown', onKey, true);
       doc.body.appendChild(backdrop);
@@ -434,9 +476,10 @@ export class UI {
     });
   }
 
-  async confirm({ title = 'Are you sure?', message, confirmLabel = 'Confirm', cancelLabel = 'Cancel', danger = false, content } = {}) {
+  async confirm({ title = 'Are you sure?', message, confirmLabel = 'Confirm', cancelLabel = 'Cancel', danger = false, icon = danger ? 'alertTriangle' : null, content } = {}) {
     const value = await this.dialog({
       title,
+      icon,
       message,
       content,
       buttons: [