@notis_ai/cli 0.2.18 → 0.2.19

package/dist/sdk/src/ui/engine/hooks.ts

@@ -0,0 +1,195 @@
+/**
+ * React hooks of the keyboard engine (toolkit spec 2.1). Every hook works without a mounted `<KeyboardEngine>`
+ * (unit tests, a bare preview): registrations land in the shared core, which listens only once an engine mounts or
+ * `core.attach(document)` is called, and settings fall back to the document language and the browser platform.
+ */
+
+import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useSyncExternalStore } from 'react';
+import { keyList, type Locale, type Platform } from '../../words';
+import { ESCAPE_PRIORITY, detectLocale, detectPlatform, type KeyboardEngineCore } from './core';
+import { getSharedInstance } from './instance';
+import type { EngineSettings, OwnerKind, ScopeHandle, ShortcutDef } from './types';
+
+const useIsoLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
+/** The engine core in effect here: an injected one, else the shared one. */
+export function useEngineCore(): KeyboardEngineCore {
+  const shared = getSharedInstance();
+  return useContext(shared.EngineContext) ?? shared.core;
+}
+
+/** The owner shortcuts register under: the nearest `<ShortcutScope>`, else 'notis'. */
+export function useShortcutOwner(): string {
+  return useContext(getSharedInstance().OwnerContext);
+}
+
+function useSetting<V>(read: (core: KeyboardEngineCore) => V): V {
+  const core = useEngineCore();
+  const getSnapshot = () => read(core);
+  return useSyncExternalStore(useCallback((listener) => core.subscribe(listener), [core]), getSnapshot, getSnapshot);
+}
+
+/** Toolkit language. Without a mounted engine: the document's `lang` ('fr...' gives 'fr', else 'en'). */
+export function useToolkitLocale(): Locale {
+  return useSetting((core) => (core.mounted > 0 ? core.settings.locale : detectLocale()));
+}
+
+/** 'mac' or 'other'. Without a mounted engine: detected from the browser. */
+export function useToolkitPlatform(): Platform {
+  return useSetting((core) => (core.mounted > 0 ? core.settings.platform : detectPlatform()));
+}
+
+/** Host, locale, platform and strict mode. */
+export function useToolkitSettings(): Readonly<EngineSettings> {
+  const locale = useToolkitLocale();
+  const platform = useToolkitPlatform();
+  const core = useEngineCore();
+  const host = useSetting((c) => c.settings.host);
+  const strict = useSetting((c) => c.settings.strict);
+  return { host, locale, platform, strict, onClash: core.settings.onClash };
+}
+
+// ---- shortcuts ----
+
+function defKey(def: ShortcutDef, owner: string): string {
+  return JSON.stringify([
+    def.id, keyList(def.keys), def.scope, def.owner ?? owner, def.group ?? '', !!def.hidden, !!def.repeat,
+    !!def.allowInFields, def.boost ?? 0, def.label.en, def.label.fr,
+  ]);
+}
+
+/** A def whose `run` and `when` always read the latest render's def, so handlers never go stale. */
+function liveDef(ref: { readonly current: ShortcutDef }): ShortcutDef {
+  const def = ref.current;
+  return {
+    ...def,
+    when: () => { const when = ref.current.when; return when ? when() : true; },
+    run: (event) => ref.current.run(event),
+  };
+}
+
+/**
+ * Registers one shortcut while mounted. Re-registers only when its id, keys, scope, owner, words or flags change
+ * (or `deps` change); `run` and `when` are read live.
+ */
+export function useShortcut(def: ShortcutDef, deps: readonly unknown[] = []): void {
+  const core = useEngineCore();
+  const owner = useShortcutOwner();
+  const ref = useRef(def);
+  ref.current = def;
+  const key = defKey(def, owner);
+  useEffect(() => {
+    const unregister = core.register(liveDef(ref), ref.current.owner ?? owner);
+    return () => { unregister?.(); };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [core, owner, key, ...deps]);
+}
+
+/** Registers several shortcuts while mounted (same rules as `useShortcut`). */
+export function useShortcuts(defs: readonly ShortcutDef[], deps: readonly unknown[] = []): void {
+  const core = useEngineCore();
+  const owner = useShortcutOwner();
+  const ref = useRef(defs);
+  ref.current = defs;
+  const key = defs.map((def) => defKey(def, owner)).join('\n');
+  useEffect(() => {
+    const unregisters = ref.current.map((def, index) => {
+      const live = { get current() { return ref.current[index] ?? def; } };
+      return core.register(liveDef(live), def.owner ?? owner);
+    });
+    return () => { for (const unregister of unregisters) unregister?.(); };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [core, owner, key, ...deps]);
+}
+
+// ---- owners ----
+
+export interface ShortcutScopeOptions {
+  /** False for a hidden retained view or a Space in the background: all its shortcuts go silent. */
+  available: boolean;
+  /** 'space' (default under the root) for Space code, 'host' for Notis pages. Inherited from the parent owner. */
+  kind?: OwnerKind;
+}
+
+/**
+ * Declares a Space or a retained view as an owner, nested under the current owner. Its shortcuts are those
+ * registered under a `<ShortcutScope owner>` with the same id (or with `def.owner`).
+ */
+export function useShortcutScope(owner: string, options: ShortcutScopeOptions): ScopeHandle {
+  const core = useEngineCore();
+  const parent = useShortcutOwner();
+  const { available, kind } = options;
+  const availableRef = useRef(available);
+  availableRef.current = available;
+  // Layout effect: owners exist before their children's shortcuts register (passive effects).
+  useIsoLayoutEffect(
+    () => core.defineOwner(owner, { parent, kind, available: availableRef.current }),
+    [core, owner, parent, kind],
+  );
+  useIsoLayoutEffect(() => { core.setOwnerAvailable(owner, available); }, [core, owner, available]);
+  return { owner, available, isAvailable: () => core.isOwnerAvailable(owner) };
+}
+
+// ---- escape ----
+
+export interface EscapeLayerOptions {
+  /** Chain position (ESCAPE_PRIORITY). Default overlay. */
+  priority?: number;
+  /** False keeps the hook mounted without a layer. Default true. */
+  enabled?: boolean;
+}
+
+/**
+ * Adds a step to the Escape chain while mounted. `onEscape` returns true when it handled the key (the chain
+ * stops), false to let the next step run. Higher priority runs first; the latest wins within a priority. It gets the
+ * keydown when a key press runs the chain (none from `runEscapeChain()` without an event).
+ */
+export function useEscapeLayer(id: string, onEscape: (event?: KeyboardEvent) => boolean,
+  options: EscapeLayerOptions = {}): void {
+  const core = useEngineCore();
+  const owner = useShortcutOwner();
+  const ref = useRef(onEscape);
+  ref.current = onEscape;
+  const priority = options.priority ?? ESCAPE_PRIORITY.overlay;
+  const enabled = options.enabled ?? true;
+  useEffect(() => {
+    if (!enabled) return undefined;
+    return core.addEscapeLayer(id, (event) => core.isOwnerAvailable(owner) && ref.current(event), priority);
+  }, [core, owner, id, priority, enabled]);
+}
+
+/**
+ * Stops the Escape chain below `priority` while `active` (the composer holds text). Default priority sits between
+ * the detail panel and selection clear, so Escape still clears a selection but never leaves the page.
+ */
+export function useEscapeBlocker(active: boolean, options: { priority?: number } = {}): void {
+  const core = useEngineCore();
+  const owner = useShortcutOwner();
+  const priority = options.priority ?? ESCAPE_PRIORITY.detail + 50;
+  useEffect(() => (active ? core.addEscapeBlocker(priority, () => core.isOwnerAvailable(owner)) : undefined), [core, owner, active, priority]);
+}
+
+// ---- help sheet ----
+
+export interface HelpSheetControls {
+  open(): void;
+  close(): void;
+  toggle(): void;
+  isOpen: boolean;
+}
+
+export function useHelpSheet(): HelpSheetControls {
+  const core = useEngineCore();
+  const isOpen = useSetting((c) => c.isHelpOpen());
+  return {
+    open: useCallback(() => core.openHelp(), [core]),
+    close: useCallback(() => core.closeHelp(), [core]),
+    toggle: useCallback(() => core.toggleHelp(), [core]),
+    isOpen,
+  };
+}
+
+/** Re-renders on every registry change (the help sheet, dev overlays). */
+export function useRegistryVersion(): number {
+  return useSetting((core) => core.getVersion());
+}

package/dist/sdk/src/ui/engine/instance.ts

@@ -0,0 +1,63 @@
+/**
+ * One engine per page, even when two copies of the toolkit load (a Space bundle that inlined `@notis/sdk/ui` by
+ * mistake). The first copy stores its core and React contexts on `globalThis` under a registered symbol; a second
+ * copy logs once and reuses them, so its shortcuts land in the same registry and its hooks read the same contexts.
+ */
+
+import { createContext, type Context } from 'react';
+import { KeyboardEngineCore } from './core';
+import { ROOT_OWNER } from './registry';
+import type { KeycapOn } from './keycapContext';
+
+export interface SharedInstance {
+  readonly version: 1;
+  readonly core: KeyboardEngineCore;
+  /** An injected core (tests, preview) overrides the shared one below it. */
+  readonly EngineContext: Context<KeyboardEngineCore | null>;
+  /** The nearest `<ShortcutScope>` owner. */
+  readonly OwnerContext: Context<string>;
+  /** Keycap `on` default for a subtree (SelectionBar: pill, Menu and HelpSheet: discreet). */
+  readonly KeycapContext: Context<KeycapOn | null>;
+}
+
+const KEY = Symbol.for('notis.sdk.ui.instance');
+
+type Slot = { [KEY]?: SharedInstance };
+
+function create(): SharedInstance {
+  return Object.freeze({
+    version: 1 as const,
+    core: new KeyboardEngineCore(),
+    EngineContext: createContext<KeyboardEngineCore | null>(null),
+    OwnerContext: createContext<string>(ROOT_OWNER),
+    KeycapContext: createContext<KeycapOn | null>(null),
+  });
+}
+
+let local: SharedInstance | null = null;
+
+export function getSharedInstance(): SharedInstance {
+  if (local) return local;
+  const slot = globalThis as Slot;
+  const existing = slot[KEY];
+  if (existing && existing.version === 1) {
+    if (typeof console !== 'undefined') {
+      console.warn('[notis keys] A second copy of the Notis toolkit loaded. It shares the first keyboard engine.');
+    }
+    local = existing;
+    return local;
+  }
+  local = create();
+  try {
+    Object.defineProperty(slot, KEY, { value: local, configurable: true, enumerable: false, writable: false });
+  } catch {
+    // A frozen global: this copy keeps its own instance.
+  }
+  return local;
+}
+
+/** Tests only: forget this module's cached instance (the global slot stays). */
+export function __resetSharedInstanceForTests(): void {
+  local = null;
+  try { delete (globalThis as Slot)[KEY]; } catch { /* non-configurable */ }
+}

package/dist/sdk/src/ui/engine/keycapContext.ts

@@ -0,0 +1,2 @@
+/** Keycap surfaces (toolkit spec 2.2). */
+export type KeycapOn = 'surface' | 'chrome' | 'pill' | 'discreet' | 'tooltip';

package/dist/sdk/src/ui/engine/registry.ts

@@ -0,0 +1,262 @@
+/**
+ * The shortcut registry: owners, availability, clash checks and dispatch order. Pure (no DOM, no React), so it runs
+ * under node in tests and in the design check.
+ */
+
+import {
+  SCOPE_ORDER,
+  keyList,
+  pairClashes,
+  parseKeySpec,
+  selfClashes,
+  type ChordSequence,
+  type Clash,
+  type ClashCandidate,
+  type KeySpec,
+  type Locale,
+} from '../../words';
+import type { HelpEntry, OwnerKind, ShortcutDef, ShortcutGroup } from './types';
+
+export const ROOT_OWNER = 'notis';
+
+/** Thrown in dev and by the design check when two defs clash or a Space takes a host key. */
+export class NotisKeyClash extends Error {
+  readonly clash: Clash;
+  constructor(clash: Clash) {
+    super(clash.message.startsWith('NotisKeyClash') ? clash.message : `NotisKeyClash: ${clash.message}`);
+    this.name = 'NotisKeyClash';
+    this.clash = clash;
+  }
+}
+
+export interface RegisteredShortcut {
+  def: ShortcutDef;
+  owner: string;
+  ownerKind: OwnerKind;
+  /** Registration order; later wins within a scope. */
+  seq: number;
+  /** Scope order plus boost. */
+  rank: number;
+  /** Parsed alternatives. */
+  chords: ChordSequence[];
+}
+
+interface OwnerRecord {
+  id: string;
+  kind: OwnerKind;
+  parent: string;
+  available: boolean;
+  refs: number;
+}
+
+export interface RegistryOptions {
+  strict: boolean;
+  onClash?: (message: string) => void;
+}
+
+export interface DefineOwnerOptions {
+  parent?: string;
+  kind?: OwnerKind;
+  available?: boolean;
+}
+
+const MAX_BOOST = 99;
+
+export class ShortcutRegistry {
+  private entries: RegisteredShortcut[] = [];
+  private owners = new Map<string, OwnerRecord>();
+  private seq = 0;
+  private version = 0;
+  private listeners = new Set<() => void>();
+  private warned = new Set<string>();
+  options: RegistryOptions;
+
+  constructor(options: Partial<RegistryOptions> = {}) {
+    this.options = { strict: options.strict ?? true, onClash: options.onClash };
+  }
+
+  // ---- change notification (useSyncExternalStore) ----
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  getVersion(): number {
+    return this.version;
+  }
+
+  notify(): void {
+    this.version += 1;
+    for (const listener of [...this.listeners]) listener();
+  }
+
+  // ---- owners ----
+
+  /** Declares a Space or a retained view. Ref counted: the last release removes it. */
+  defineOwner(id: string, options: DefineOwnerOptions = {}): () => void {
+    if (id === ROOT_OWNER) return () => {};
+    const parent = options.parent ?? ROOT_OWNER;
+    const existing = this.owners.get(id);
+    if (existing) {
+      existing.refs += 1;
+      existing.parent = parent;
+      if (options.kind) existing.kind = options.kind;
+      if (options.available !== undefined && existing.available !== options.available) {
+        existing.available = options.available;
+      }
+    } else {
+      this.owners.set(id, {
+        id,
+        parent,
+        kind: options.kind ?? this.inheritedKind(parent),
+        available: options.available ?? true,
+        refs: 1,
+      });
+    }
+    this.notify();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const record = this.owners.get(id);
+      if (!record) return;
+      record.refs -= 1;
+      if (record.refs <= 0) this.owners.delete(id);
+      this.notify();
+    };
+  }
+
+  setOwnerAvailable(id: string, available: boolean): void {
+    const record = this.owners.get(id);
+    if (!record || record.available === available) return;
+    record.available = available;
+    this.notify();
+  }
+
+  private inheritedKind(parent: string): OwnerKind {
+    if (parent === ROOT_OWNER) return 'space';
+    return this.owners.get(parent)?.kind ?? 'space';
+  }
+
+  ownerKind(id: string): OwnerKind {
+    if (id === ROOT_OWNER) return 'host';
+    // An owner not declared yet (its scope mounts after the def) counts as a Space.
+    return this.owners.get(id)?.kind ?? 'space';
+  }
+
+  /** Available when it and every owner above it are available. Unknown owners count as available. */
+  isOwnerAvailable(id: string): boolean {
+    let current: string | undefined = id;
+    const seen = new Set<string>();
+    while (current && current !== ROOT_OWNER && !seen.has(current)) {
+      seen.add(current);
+      const record = this.owners.get(current);
+      if (!record) return true;
+      if (!record.available) return false;
+      current = record.parent;
+    }
+    return true;
+  }
+
+  // ---- shortcuts ----
+
+  /**
+   * Registers a def. Returns an unregister function, or null when the def was dropped (production clash).
+   * Strict mode throws NotisKeyClash instead of dropping.
+   */
+  register(def: ShortcutDef, owner: string = def.owner ?? ROOT_OWNER): (() => void) | null {
+    const ownerKind = this.ownerKind(owner);
+    const candidate = this.candidate(def, owner, ownerKind);
+    const errors = selfClashes(candidate).filter((clash) => clash.severity === 'error');
+    if (errors.length) {
+      this.reject(errors[0]!);
+      return null;
+    }
+    if (this.isOwnerAvailable(owner)) {
+      for (const entry of this.entries) {
+        if (entry.owner !== owner || entry.def.scope !== def.scope) continue;
+        if (!this.isOwnerAvailable(entry.owner)) continue;
+        const duplicate = pairClashes(this.candidate(entry.def, entry.owner, entry.ownerKind), candidate)
+          .find((clash) => clash.kind === 'duplicate');
+        if (duplicate) {
+          this.reject(duplicate);
+          return null;
+        }
+      }
+    }
+    const boost = Math.max(0, Math.min(MAX_BOOST, def.boost ?? 0));
+    const entry: RegisteredShortcut = {
+      def,
+      owner,
+      ownerKind,
+      seq: ++this.seq,
+      rank: SCOPE_ORDER[def.scope] + boost,
+      chords: keyList(def.keys).map((spec) => parseKeySpec(spec)),
+    };
+    this.entries.push(entry);
+    this.notify();
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      const index = this.entries.indexOf(entry);
+      if (index !== -1) this.entries.splice(index, 1);
+      this.notify();
+    };
+  }
+
+  private candidate(def: ShortcutDef, owner: string, ownerKind: OwnerKind): ClashCandidate {
+    return { id: def.id, keys: def.keys, scope: def.scope, owner, ownerKind, available: true };
+  }
+
+  private reject(clash: Clash): void {
+    if (this.options.strict) throw new NotisKeyClash(clash);
+    if (this.warned.has(clash.message)) return;
+    this.warned.add(clash.message);
+    const log = this.options.onClash ?? ((message: string) => {
+      if (typeof console !== 'undefined') console.warn(`[notis keys] ${message} The later shortcut was ignored.`);
+    });
+    log(clash.message);
+  }
+
+  /** All registered entries, registration order. */
+  all(): readonly RegisteredShortcut[] {
+    return this.entries;
+  }
+
+  /**
+   * Entries that may answer a key now: owner available, `when` passing, highest rank first, latest first within a
+   * rank. `modalOnly` keeps only the modal scope (an open dialog or menu).
+   */
+  active(options: { modalOnly?: boolean } = {}): RegisteredShortcut[] {
+    return this.entries
+      .filter((entry) => (!options.modalOnly || entry.def.scope === 'modal') && this.isOwnerAvailable(entry.owner))
+      .sort((a, b) => b.rank - a.rank || b.seq - a.seq);
+  }
+
+  /** Help sheet rows: available, not hidden, `when` passing, latest def per id. Space group first, then Notis. */
+  helpEntries(): HelpEntry[] {
+    const byId = new Map<string, HelpEntry>();
+    const ordered = [...this.entries].sort((a, b) => a.seq - b.seq);
+    for (const entry of ordered) {
+      const { def } = entry;
+      if (def.hidden || def.scope === 'modal' || !this.isOwnerAvailable(entry.owner)) continue;
+      if (def.when && !safeWhen(def.when)) continue;
+      const group: ShortcutGroup = def.group ?? (entry.ownerKind === 'space' ? 'space' : 'notis');
+      byId.delete(def.id);
+      byId.set(def.id, { id: def.id, keys: keyList(def.keys), label: def.label, group, scope: def.scope, owner: entry.owner });
+    }
+    const rows = [...byId.values()];
+    return [...rows.filter((row) => row.group === 'space'), ...rows.filter((row) => row.group === 'notis')];
+  }
+
+  /** Labels for the help sheet in one language, for tests and text hosts. */
+  helpText(locale: Locale): Array<{ group: ShortcutGroup; label: string; keys: KeySpec[] }> {
+    return this.helpEntries().map((row) => ({ group: row.group, label: row.label[locale], keys: row.keys }));
+  }
+}
+
+export function safeWhen(when: () => boolean): boolean {
+  try { return when() !== false; } catch { return false; }
+}

package/dist/sdk/src/ui/engine/types.ts

@@ -0,0 +1,62 @@
+import type { KeySpec, Locale, Platform, Scope, Words } from '../../words';
+
+export type { KeySpec, Locale, Platform, Scope, Words };
+
+export type ShortcutGroup = 'space' | 'notis';
+
+export interface ShortcutDef {
+  /** Stable id: 'list.next', 'space:tickets.triage'. */
+  id: string;
+  /** One spec or alternatives. */
+  keys: KeySpec | KeySpec[];
+  scope: Scope;
+  label: Words;
+  /** Help sheet group. Default 'space' under a Space owner, 'notis' otherwise. */
+  group?: ShortcutGroup;
+  /** Extra gate, evaluated at dispatch (and when the help sheet opens). */
+  when?: () => boolean;
+  /** Fire on key repeat (a held key). Default false. */
+  repeat?: boolean;
+  /** Fire while focus is in a text field. Default false. */
+  allowInFields?: boolean;
+  /** Not listed in the help sheet. */
+  hidden?: boolean;
+  /**
+   * Added to the scope order (0 to 99). The selection bar registers its actions at `collection` with
+   * `boost: 25` while something is selected, so they win over row keys.
+   */
+  boost?: number;
+  /** Owner override. Default: the nearest `<ShortcutScope>` (or `useShortcutScope`) above, else 'notis'. */
+  owner?: string;
+  /** Return false when not handled: the engine keeps looking. */
+  run: (event: KeyboardEvent) => void | boolean;
+}
+
+export type OwnerKind = 'space' | 'host';
+
+export interface ScopeHandle {
+  owner: string;
+  available: boolean;
+  isAvailable(): boolean;
+}
+
+export type EngineHost = 'portal' | 'preview';
+
+export interface EngineSettings {
+  host: EngineHost;
+  locale: Locale;
+  platform: Platform;
+  /** Dev and design check: clashes throw. Production: the later def is dropped and logged once. */
+  strict: boolean;
+  /** Production clash log (telemetry). Default console.warn, once per message. */
+  onClash?: (message: string) => void;
+}
+
+export interface HelpEntry {
+  id: string;
+  keys: KeySpec[];
+  label: Words;
+  group: ShortcutGroup;
+  scope: Scope;
+  owner: string;
+}

package/dist/sdk/src/ui/icons.tsx

@@ -0,0 +1,91 @@
+/**
+ * The toolkit's built-in icons: a small inline SVG set under the Phosphor names the action catalogue uses, so the
+ * toolkit has no icon dependency. Every `icon` prop also takes any ReactNode (a Phosphor component, for example).
+ */
+
+import React, { type ReactNode } from 'react';
+
+type Shape = ReactNode;
+
+const S = { fill: 'none', stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round', strokeLinejoin: 'round' } as const;
+const F = { fill: 'currentColor', stroke: 'none' } as const;
+
+const SHAPES: Record<string, Shape> = {
+  'arrow-left': <path {...S} d="M13 8H3m4-4L3 8l4 4" />,
+  x: <path {...S} d="M4 4l8 8M12 4l-8 8" />,
+  'caret-up': <path {...S} d="M4 10l4-4 4 4" />,
+  'caret-down': <path {...S} d="M4 6l4 4 4-4" />,
+  'caret-right': <path {...S} d="M6 4l4 4-4 4" />,
+  'caret-left': <path {...S} d="M10 4L6 8l4 4" />,
+  'arrows-out': <path {...S} d="M9.5 2.5h4v4M13.5 2.5L9 7M6.5 13.5h-4v-4M2.5 13.5L7 9" />,
+  'dots-three': <g {...F}><circle cx="3.5" cy="8" r="1.25" /><circle cx="8" cy="8" r="1.25" /><circle cx="12.5" cy="8" r="1.25" /></g>,
+  'sidebar-simple': <g {...S}><rect x="2" y="3" width="12" height="10" rx="1.5" /><path d="M9.5 3v10" /></g>,
+  'square-center': <g {...S}><rect x="2" y="3" width="12" height="10" rx="1.5" /><rect x="5" y="5.5" width="6" height="5" rx=".75" /></g>,
+  'corners-out': <path {...S} d="M2.5 6V2.5H6M10 2.5h3.5V6M13.5 10v3.5H10M6 13.5H2.5V10" />,
+  check: <path {...S} d="M3 8.5l3 3 7-7" />,
+  archive: <g {...S}><rect x="2" y="3" width="12" height="3" rx=".75" /><path d="M3 6v6.5a.5.5 0 00.5.5h9a.5.5 0 00.5-.5V6M6.5 8.5h3" /></g>,
+  'tray-arrow-up': <path {...S} d="M2.5 9.5v3a.5.5 0 00.5.5h10a.5.5 0 00.5-.5v-3h-3l-1 1.5h-3l-1-1.5h-3M8 8V2.5M5.5 5L8 2.5 10.5 5" />,
+  star: <path {...S} d="M8 2l1.8 3.8 4.2.5-3.1 2.9.8 4.1L8 11.3l-3.7 2 .8-4.1L2 6.3l4.2-.5z" />,
+  'star-fill': <path fill="currentColor" stroke="currentColor" strokeWidth={0.8} strokeLinejoin="round" d="M8 1.6l1.95 3.95 4.36.64-3.16 3.07.75 4.34L8 11.55 4.1 13.6l.75-4.34L1.69 6.19l4.36-.64z" />,
+  clock: <g {...S}><circle cx="8" cy="8" r="6" /><path d="M8 4.5V8h3" /></g>,
+  'arrow-bend-up-right': <path {...S} d="M10 3l3 3-3 3M13 6H7a4 4 0 00-4 4v3" />,
+  'user-plus': <g {...S}><circle cx="6.5" cy="5.5" r="2.75" /><path d="M1.5 13.5c.8-2.2 2.7-3.5 5-3.5s4.2 1.3 5 3.5M12.5 4v4M10.5 6h4" /></g>,
+  'envelope-open': <path {...S} d="M2 6.5v6a.5.5 0 00.5.5h11a.5.5 0 00.5-.5v-6L8 2.5zM2 6.5l6 4 6-4" />,
+  'envelope-simple': <g {...S}><rect x="2" y="3.5" width="12" height="9" rx="1" /><path d="M2 4.5l6 4.5 6-4.5" /></g>,
+  'pencil-simple': <path {...S} d="M10.8 2.7l2.5 2.5L5.6 12.9 2.5 13.5l.6-3.1zM9.3 4.2l2.5 2.5" />,
+  'file-text': <path {...S} d="M9.5 2H4a.5.5 0 00-.5.5v11a.5.5 0 00.5.5h8a.5.5 0 00.5-.5V5zM9.5 2v3h3M6 8.5h4M6 11h4" />,
+  flask: <path {...S} d="M6 2h4M6.8 2v4.3l-3.6 6.2a1 1 0 00.9 1.5h7.8a1 1 0 00.9-1.5L9.2 6.3V2M4.6 10.2h6.8" />,
+  copy: <path {...S} d="M6.5 5.5h5a1 1 0 011 1v5a1 1 0 01-1 1h-5a1 1 0 01-1-1v-5a1 1 0 011-1zM10.5 5.5v-1a1 1 0 00-1-1h-5a1 1 0 00-1 1v5a1 1 0 001 1h1" />,
+  'chat-circle-text': <path {...S} d="M4.7 13.1A5.8 5.8 0 102.9 11.3L2.3 13.7zM6 7h4M6 9.3h3" />,
+  trash: <path {...S} d="M2.5 4h11M6.5 2.5h3M4 4l.6 9a.5.5 0 00.5.5h5.8a.5.5 0 00.5-.5L12 4M6.5 6.5v4.5M9.5 6.5v4.5" />,
+  'circle-half': <g><circle {...S} cx="8" cy="8" r="6" /><path {...F} d="M8 2a6 6 0 010 12z" /></g>,
+  'circle-three-quarter': <g><circle {...S} cx="8" cy="8" r="6" /><path {...F} d="M8 8V2a6 6 0 11-6 6z" /></g>,
+  pause: <path {...S} d="M5.5 3v10M10.5 3v10" />,
+  play: <path {...S} d="M4.5 2.5v11L13 8z" />,
+  'toggle-right': <g {...S}><rect x="1.5" y="4" width="13" height="8" rx="4" /><circle cx="10.5" cy="8" r="2" /></g>,
+  'toggle-left': <g {...S}><rect x="1.5" y="4" width="13" height="8" rx="4" /><circle cx="5.5" cy="8" r="2" /></g>,
+  hourglass: <path {...S} d="M4 2.5h8M4 13.5h8M5 2.5c0 3 6 3.5 6 5.5s-6 2.5-6 5.5M11 2.5c0 3-6 3.5-6 5.5s6 2.5 6 5.5" />,
+  'arrow-counter-clockwise': <path {...S} d="M4.5 6H2V3.5M2.3 6A6 6 0 112 9" />,
+  'arrow-clockwise': <path {...S} d="M11.5 6H14V3.5M13.7 6A6 6 0 1 0 14 9" />,
+  'arrows-clockwise': <path {...S} d="M3 6a5.4 5.4 0 0110 0M13 3v3h-3M13 10a5.4 5.4 0 01-10 0M3 13v-3h3" />,
+  plus: <path {...S} d="M8 3v10M3 8h10" />,
+  'circle-dashed': <circle {...S} cx="8" cy="8" r="6" strokeDasharray="2.2 2.2" />,
+  circle: <circle {...S} cx="8" cy="8" r="6" />,
+  'clock-countdown': <g {...S}><path d="M8 2a6 6 0 11-6 6" strokeDasharray="0" /><path d="M8 5v3l2 1.5M2.6 5.3l.1-.1M4.6 3.1l.1-.1" /></g>,
+  'check-circle-fill': <g><circle {...F} cx="8" cy="8" r="6.5" /><path d="M5 8.2l2 2 4-4" fill="none" stroke="hsl(var(--background))" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" /></g>,
+  'minus-circle': <g {...S}><circle cx="8" cy="8" r="6" /><path d="M5.5 8h5" /></g>,
+  'paper-plane-right': <path {...S} d="M2.5 2.8l11 5.2-11 5.2 1.8-5.2zM4.3 8h4.7" />,
+  paperclip: <path {...S} d="M10.5 5l-4.6 4.6a1.1 1.1 0 001.6 1.6l5-5a2.3 2.3 0 00-3.2-3.2l-5 5a3.4 3.4 0 004.8 4.8L13 8.9" />,
+  'clipboard-text': <g {...S}><path d="M10.5 3h2a.5.5 0 01.5.5v10a.5.5 0 01-.5.5h-9a.5.5 0 01-.5-.5v-10a.5.5 0 01.5-.5h2" /><rect x="5.5" y="2" width="5" height="2.5" rx=".75" /><path d="M6 8h4M6 10.5h4" /></g>,
+  'x-circle-fill': <g><circle {...F} cx="8" cy="8" r="6.5" /><path d="M5.8 5.8l4.4 4.4M10.2 5.8l-4.4 4.4" fill="none" stroke="hsl(var(--background))" strokeWidth={1.5} strokeLinecap="round" /></g>,
+  'magnifying-glass-plus': <path {...S} d="M7 12A5 5 0 107 2a5 5 0 000 10zM10.6 10.6L14 14M5 7h4M7 5v4" />,
+  'magnifying-glass-minus': <path {...S} d="M7 12A5 5 0 107 2a5 5 0 000 10zM10.6 10.6L14 14M5 7h4" />,
+  'download-simple': <path {...S} d="M8 2.5v7.5M4.5 6.5L8 10l3.5-3.5M2.5 10v3a.5.5 0 00.5.5h10a.5.5 0 00.5-.5v-3" />,
+  link: <path {...S} d="M6.8 9.2l2.4-2.4M7.6 4.6l1.2-1.2a2.8 2.8 0 014 4l-1.2 1.2M8.4 11.4l-1.2 1.2a2.8 2.8 0 01-4-4l1.2-1.2" />,
+  file: <path {...S} d="M9.5 2H4a.5.5 0 00-.5.5v11a.5.5 0 00.5.5h8a.5.5 0 00.5-.5V5zM9.5 2v3h3" />,
+  'file-image': <g {...S}><path d="M9.5 2H4a.5.5 0 00-.5.5v11a.5.5 0 00.5.5h8a.5.5 0 00.5-.5V5zM9.5 2v3h3" /><path d="M3.5 12l3-3 2 2 1.5-1.5 2.5 2.5" /><circle cx="6.5" cy="6.75" r=".75" /></g>,
+  'file-video': <g {...S}><path d="M9.5 2H4a.5.5 0 00-.5.5v11a.5.5 0 00.5.5h8a.5.5 0 00.5-.5V5zM9.5 2v3h3" /><path d="M6.5 8v3.5L9.5 9.75z" /></g>,
+  'file-audio': <g {...S}><path d="M9.5 2H4a.5.5 0 00-.5.5v11a.5.5 0 00.5.5h8a.5.5 0 00.5-.5V5zM9.5 2v3h3" /><path d="M6 9.5v1.5h1.25L9 12.25v-4.5L7.25 9H6M10.5 8.5a1.8 1.8 0 010 2.5" /></g>,
+};
+
+export function hasIcon(name: string): boolean {
+  return Object.prototype.hasOwnProperty.call(SHAPES, name);
+}
+
+/** A built-in icon by name; an unknown name renders nothing. Decorative: the control carries the label. */
+export function Icon({ name, className }: { name: string; className?: string }) {
+  const shape = SHAPES[name];
+  if (!shape) return null;
+  return (
+    <svg className={className ? `nui-icon ${className}` : 'nui-icon'} viewBox="0 0 16 16" aria-hidden="true" focusable="false">
+      {shape}
+    </svg>
+  );
+}
+
+/** Renders an `icon` prop: a name from the set, or any node the caller passes. */
+export function renderIcon(icon: ReactNode | string | undefined, className?: string): ReactNode {
+  if (icon === undefined || icon === null || icon === false) return null;
+  if (typeof icon === 'string') return <Icon name={icon} className={className} />;
+  return icon;
+}