@ultimat3/ui 1.2.0 → 3.0.0

package/src/debounce.ts

@@ -0,0 +1,55 @@
+// Trailing-edge debounce: the last call of a burst wins, `ms` after the burst stops.
+// One timer, always cancellable — a component that unmounts mid-burst must not fire
+// a filter into a tree that is gone, which is what a leaked timer does.
+
+import { invalidValueError } from './errors';
+
+export interface Debounced<A extends readonly unknown[]> {
+  (...args: A): void;
+  /** Drop the pending call. Wire it to the component's cleanup. */
+  cancel(): void;
+  /** Run the pending call now, if there is one. Blur and submit both need this. */
+  flush(): void;
+  /** True while a call is waiting. */
+  pending(): boolean;
+}
+
+export const DEBOUNCE_DEFAULT_MS = 250;
+
+export function debounce<A extends readonly unknown[]>(
+  fn: (...args: A) => void,
+  ms: number = DEBOUNCE_DEFAULT_MS,
+): Debounced<A> {
+  if (!Number.isFinite(ms) || ms < 0) {
+    throw invalidValueError('debounce', ms, 'a finite, non-negative delay in milliseconds');
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let queued: A | undefined;
+
+  const cancel = (): void => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+    queued = undefined;
+  };
+
+  const run = (): void => {
+    const args = queued;
+    // Cleared BEFORE the call: `fn` may schedule the next burst, and clearing after would
+    // discard the call it just queued.
+    cancel();
+    if (args !== undefined) fn(...args);
+  };
+
+  const debounced = (...args: A): void => {
+    queued = args;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(run, ms);
+  };
+
+  return Object.assign(debounced, {
+    cancel,
+    flush: run,
+    pending: (): boolean => timer !== undefined,
+  });
+}

package/src/errors.ts

@@ -1,7 +1,7 @@
 // @ultimat3/ui error codes. Every throw carries a stable code, the cause, and
 // the exact fix — identical in the terminal, the browser overlay, and `--json`.
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { registerErrorCodes, renderCauseValue, UltimateError } from '@ultimat3/core';
 
 export const UI_ERROR_CODES = {
   tokenUnknown: 'X_TOKEN_UNKNOWN',
@@ -66,7 +66,8 @@ export function invalidBrandTokenError(
 ): UiError {
   return new UiError({
     code: UI_ERROR_CODES.invalidValue,
-    cause: `defineTheme() override ${scope}.${name} is ${JSON.stringify(value)}, which is not ${expected}`,
+    // The override is the app's own object, so the value is unparsed app data at this point.
+    cause: `defineTheme() override ${scope}.${name} is ${renderCauseValue(value)}, which is not ${expected}`,
     fix: `pass ${expected} to defineTheme(), e.g. defineTheme({ colors: { light: { accent: '31 110 178' } } })`,
   });
 }
@@ -75,7 +76,7 @@ export function invalidBrandTokenError(
 export function invalidThemeError(value: unknown): UiError {
   return new UiError({
     code: UI_ERROR_CODES.themeInvalid,
-    cause: `theme must be "light" or "dark", received ${JSON.stringify(value)}`,
+    cause: `theme must be "light" or "dark", received ${renderCauseValue(value)}`,
     fix: "call setTheme('light') or setTheme('dark'), or clearTheme() to follow the OS",
   });
 }
@@ -89,11 +90,57 @@ export function runtimeMissingError(api: string, fix: string): UiError {
   });
 }
 
+/**
+ * `<UiProvider>` on a server render. No new code: a reactive runtime is absent, which is exactly
+ * what X_UI_RUNTIME_MISSING already names — and a code is stable forever once shipped. The throw
+ * is the point. A Provider in an inert tree reaches no descendant (they are walked outside every
+ * owner), so rendering the children anyway would drop the locale, zone, currency and translator it
+ * was handed while looking like it worked.
+ */
+export function providerNeedsRuntimeError(): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.runtimeMissing,
+    cause:
+      '<UiProvider> needs a registered Solid runtime; a server render has none, and its values would reach no component',
+    fix: 'delete <UiProvider> from the server tree — useUi() already reads the request locale and time zone; keep the provider in the client entry, after setSolidRuntime()',
+  });
+}
+
+/**
+ * `<Icon>` was handed glyph data it refuses to turn into markup. No new code: an unrenderable
+ * glyph is exactly what X_UI_INVALID_VALUE already names, and a code is stable forever once shipped
+ * — a second one for the same meaning is the thing the catalog exists to prevent.
+ */
+export function invalidGlyphError(found: string, expected: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.invalidValue,
+    cause: `<Icon> glyph carries ${found}, which is not renderable; expected ${expected}`,
+    // Command first, the alternative behind a `#`: the line runs verbatim and the shell drops the
+    // rest. A `fix:` that opens with `@ultimat3/ui/icons/<name>` is a redirect, not an instruction.
+    fix: 'bun run --filter @ultimat3/ui icons   # or import the glyph from @ultimat3/ui/icons/<name>',
+  });
+}
+
 /** A formatting component was handed a value it cannot render. */
 export function invalidValueError(kind: string, value: unknown, expected: string): UiError {
   return new UiError({
     code: UI_ERROR_CODES.invalidValue,
-    cause: `<${kind}> received ${JSON.stringify(value)}, which is not ${expected}`,
+    cause: `<${kind}> received ${renderCauseValue(value)}, which is not ${expected}`,
     fix: `pass ${expected} — parse or validate the value in the loader, not in the component`,
   });
 }
+
+/**
+ * The icon generator was handed upstream data it cannot turn into a glyph module. No new code:
+ * malformed data is exactly what X_UI_INVALID_VALUE already names, and a code is stable forever
+ * once shipped. It is NOT X_UI_RUNTIME_MISSING, which says a host capability is absent and sends
+ * an operator to audit their environment for a fault that is in the file they just downloaded.
+ * The generator's environment faults — no network, no biome binary — keep that code.
+ */
+export function invalidIconDataError(found: string, fix: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.invalidValue,
+    cause: `lucide icon data ${found}`,
+    fix,
+  });
+}

package/src/fake-dom.ts

@@ -0,0 +1,194 @@
+// TEST-ONLY. A DOM small enough to read and real enough to run this package's keyboard code
+// against: focus that a disabled control silently refuses, `document.activeElement`, `contains`,
+// and `querySelectorAll` for the selector grammar these helpers actually pass. Not exported from
+// `index.ts` — the alternative is a DOM dependency, and the bugs it catches are the ones that only
+// exist because nothing ever called `createRovingTabindex` with elements attached.
+
+/** The subset of a selector these helpers use: comma groups of tag + `[attr]` + `:not(...)`. */
+const PART = /\[[^\]]*\]|:not\([^)]*\)/g;
+
+function attrMatches(element: FakeElement, test: string): boolean {
+  const inner = test.slice(1, -1);
+  const eq = inner.indexOf('=');
+  if (eq === -1) return element.getAttribute(inner) !== null;
+  const name = inner.slice(0, eq);
+  const value = inner.slice(eq + 1).replace(/^["']|["']$/g, '');
+  return element.getAttribute(name) === value;
+}
+
+function compoundMatches(element: FakeElement, compound: string): boolean {
+  const tag = compound.split(/[[:]/, 1)[0] ?? '';
+  if (tag !== '' && tag !== element.tagName.toLowerCase()) return false;
+  for (const part of compound.slice(tag.length).match(PART) ?? []) {
+    const ok = part.startsWith(':not(')
+      ? !attrMatches(element, part.slice(5, -1))
+      : attrMatches(element, part);
+    if (!ok) return false;
+  }
+  return true;
+}
+
+/** Listener book shared by the element and the document: registration only, and NO bubbling — a
+ * listener on a node never sees an event dispatched somewhere else, which is the whole point of
+ * the question `createFocusTrap` gets wrong. */
+class Listeners {
+  readonly listeners = new Map<string, Set<(event: unknown) => void>>();
+
+  addEventListener(type: string, handler: (event: unknown) => void): void {
+    const set = this.listeners.get(type) ?? new Set();
+    set.add(handler);
+    this.listeners.set(type, set);
+  }
+
+  removeEventListener(type: string, handler: (event: unknown) => void): void {
+    this.listeners.get(type)?.delete(handler);
+  }
+
+  dispatch(type: string, event: unknown): void {
+    for (const handler of [...(this.listeners.get(type) ?? [])]) handler(event);
+  }
+}
+
+const NATIVELY_FOCUSABLE = new Set(['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY']);
+const LINK_TAGS = new Set(['A', 'AREA']);
+
+/** An element that behaves like the real thing in the two ways this package's bugs depend on. */
+export class FakeElement extends Listeners {
+  readonly tagName: string;
+  readonly children: FakeElement[] = [];
+  parent: FakeElement | null = null;
+  readonly attrs: Record<string, string>;
+  /** Test assertion surface: how many times focus actually landed here. */
+  focusCount = 0;
+  owner: FakeDocument | null = null;
+
+  constructor(tagName: string, attrs: Record<string, string> = {}) {
+    super();
+    this.tagName = tagName.toUpperCase();
+    this.attrs = { ...attrs };
+  }
+
+  get tabIndex(): number {
+    return Number.parseInt(this.attrs['tabindex'] ?? '-1', 10);
+  }
+
+  set tabIndex(value: number) {
+    this.attrs['tabindex'] = String(value);
+  }
+
+  getAttribute(name: string): string | null {
+    return this.attrs[name] ?? null;
+  }
+
+  append(...children: readonly FakeElement[]): FakeElement {
+    for (const child of children) {
+      child.parent = this;
+      this.children.push(child);
+    }
+    return this;
+  }
+
+  /** The bug's mechanism, faithfully: focusing a disabled control does NOTHING and reports nothing.
+   * A tag that is not natively focusable and carries no `tabindex` refuses in exactly the same
+   * silence — `<div>.focus()` is the no-op behind the focus trap's empty-panel fallback. */
+  focus(): void {
+    if (this.getAttribute('disabled') !== null) return;
+    // `tabindex="-1"` IS focusable programmatically; it is only out of the TAB order.
+    const declared = this.getAttribute('tabindex') !== null;
+    if (!declared && !this.nativelyFocusable()) return;
+    this.focusCount += 1;
+    const doc = this.document();
+    if (doc !== null) doc.activeElement = this;
+  }
+
+  contains(node: unknown): boolean {
+    for (let at = node as FakeElement | null; at !== null; at = at.parent) {
+      if (at === this) return true;
+    }
+    return false;
+  }
+
+  descendants(): FakeElement[] {
+    return this.children.flatMap((child) => [child, ...child.descendants()]);
+  }
+
+  querySelectorAll(selector: string): FakeElement[] {
+    const groups = selector.split(',').map((one) => one.trim());
+    return this.descendants().filter((el) => groups.some((one) => compoundMatches(el, one)));
+  }
+
+  // `focusableWithin` filters on visibility; nothing in a fake tree is laid out, so everything is
+  // visible — a hidden-element rule would be this harness inventing a fact, not testing one.
+  readonly offsetParent: unknown = null;
+
+  getClientRects(): readonly unknown[] {
+    return [{}];
+  }
+
+  /** Focusable with no `tabindex` at all. `A`/`AREA` only with an `href` — the same condition
+   * `FOCUSABLE_SELECTOR` spells `a[href]`. */
+  private nativelyFocusable(): boolean {
+    if (NATIVELY_FOCUSABLE.has(this.tagName)) return true;
+    return LINK_TAGS.has(this.tagName) && this.getAttribute('href') !== null;
+  }
+
+  private document(): FakeDocument | null {
+    for (let at: FakeElement | null = this; at !== null; at = at.parent) {
+      if (at.owner !== null) return at.owner;
+    }
+    return null;
+  }
+}
+
+export interface FakeKeyboardEvent {
+  readonly key: string;
+  readonly shiftKey: boolean;
+  defaultPrevented: boolean;
+  preventDefault(): void;
+}
+
+export function keydown(key: string, shiftKey = false): FakeKeyboardEvent {
+  return {
+    key,
+    shiftKey,
+    defaultPrevented: false,
+    preventDefault(): void {
+      this.defaultPrevented = true;
+    },
+  };
+}
+
+export class FakeDocument extends Listeners {
+  activeElement: FakeElement | null = null;
+}
+
+export interface InstalledDom {
+  readonly document: FakeDocument;
+  readonly restore: () => void;
+}
+
+/**
+ * Publish `document` and `HTMLElement` globally for the duration of one test. Both are needed:
+ * `createRovingTabindex` reads `document.activeElement` and narrows it with `instanceof
+ * HTMLElement`, so a fake that is not the global class is silently treated as "focus is nowhere".
+ * ALWAYS restored — `solid()` decides a render is a server render by `document` being absent, and
+ * a leaked one turns every later component test in the process into `X_UI_RUNTIME_MISSING`.
+ */
+export function installFakeDom(root: FakeElement): InstalledDom {
+  const document = new FakeDocument();
+  root.owner = document;
+  const hadDocument = 'document' in globalThis;
+  const hadElement = 'HTMLElement' in globalThis;
+  const previousDocument: unknown = Reflect.get(globalThis, 'document');
+  const previousElement: unknown = Reflect.get(globalThis, 'HTMLElement');
+  Object.assign(globalThis, { document, HTMLElement: FakeElement });
+  return {
+    document,
+    restore(): void {
+      if (hadDocument) Object.assign(globalThis, { document: previousDocument });
+      else Reflect.deleteProperty(globalThis, 'document');
+      if (hadElement) Object.assign(globalThis, { HTMLElement: previousElement });
+      else Reflect.deleteProperty(globalThis, 'HTMLElement');
+    },
+  };
+}

package/src/global.scss

@@ -1,5 +1,7 @@
 // One import for an app document shell: every custom property, then the reset.
 // Component modules add nothing global — they only ever emit their own classes.
+// Reach it from ONE file in the app (`apps/web/shared/global.scss`), imported for its side effect
+// by `shared/global.ts` — every module is its own Sass compilation, so a second @use duplicates it.
 
 @use 'tokens/theme';
 @use 'tokens/reset';

package/src/i18n-keys.ts

@@ -9,7 +9,10 @@ export const UI_KEYS = {
   dismiss: 'ui.dismiss',
   loading: 'ui.loading',
   empty: 'ui.empty',
-  error: 'ui.error',
+  // `ui.error` cannot be a leaf: `ui.error.code|cause|fix` are branches under it, and a catalog is
+  // authored nested — `parseNestedCatalog` refuses a dot inside a key, so a name is a leaf or a
+  // branch, never both. Same reason `theme` is `ui.theme.label`.
+  error: 'ui.error.title',
   retry: 'ui.retry',
   next: 'ui.next',
   previous: 'ui.previous',
@@ -25,11 +28,19 @@ export const UI_KEYS = {
   more: 'ui.more',
   required: 'ui.required',
   optional: 'ui.optional',
-  theme: 'ui.theme',
+  theme: 'ui.theme.label',
   themeLight: 'ui.theme.light',
   themeDark: 'ui.theme.dark',
   themeSystem: 'ui.theme.system',
   language: 'ui.language',
+  /** Combobox: how many suggestions the datalist currently offers. Takes `{ count }`. */
+  suggestions: 'ui.suggestions',
+  /** Combobox: the query matched nothing. */
+  noResults: 'ui.results.empty',
+  /** InfiniteScroll: the label on the next-page control. */
+  loadMore: 'ui.load.more',
+  /** InfiniteScroll: announced when the last page has arrived. */
+  endOfList: 'ui.load.end',
   errorCode: 'ui.error.code',
   errorCause: 'ui.error.cause',
   errorFix: 'ui.error.fix',

package/src/icons/LICENSE.lucide

@@ -0,0 +1,43 @@
+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.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+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/src/icons/build-icons.ts

@@ -0,0 +1,155 @@
+// Generates `src/icons/glyphs/<name>.ts` — one module per Lucide icon — from upstream
+// `lucide-static` data: `bun run --filter @ultimat3/ui icons`. We wrap Lucide, we do not draw
+// icons, so an upstream fix is a version bump plus a re-run and never a hand edit.
+
+import { rm } from 'node:fs/promises';
+import { renderCauseValue } from '@ultimat3/core';
+import type { IconGlyph } from '../components/icon-glyph';
+import { iconElements } from '../components/icon-glyph';
+import { invalidIconDataError, runtimeMissingError } from '../errors';
+
+/** Pinned: a floating version would silently redraw icons under an app that never asked. */
+export const LUCIDE_VERSION = '1.31.0';
+
+export const LUCIDE_ICON_NODES_URL = `https://cdn.jsdelivr.net/npm/lucide-static@${LUCIDE_VERSION}/icon-nodes.json`;
+
+export const GLYPHS_DIR = new URL('./glyphs/', import.meta.url).pathname;
+
+/** `circle-alert` → `iconCircleAlert`. Prefixed because `delete`, `import` and `package` are icons
+ * and reserved words — one uniform rule beats three exceptions an agent has to remember. */
+export function identifierFor(name: string): string {
+  const pascal = name.replace(/(^|-)(\w)/g, (_, __, letter: string) => letter.toUpperCase());
+  return `icon${pascal}`;
+}
+
+/**
+ * Upstream JSON in, validated glyphs out. `unknown` all the way down — the file is fetched over
+ * the network, so its shape is an assumption until it is checked.
+ */
+export function parseIconNodes(text: string): ReadonlyMap<string, IconGlyph> {
+  const parsed: unknown = JSON.parse(text);
+  // `typeof [] === 'object'`, and an array of icons is a different upstream format, not this one.
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw invalidIconDataError(
+      `parsed as ${renderCauseValue(parsed)}, not the object of name to nodes that icon-nodes.json publishes; ${LUCIDE_ICON_NODES_URL} served something else`,
+      'bun run --filter @ultimat3/ui icons',
+    );
+  }
+  const out = new Map<string, IconGlyph>();
+  for (const [name, value] of Object.entries(parsed as Record<string, unknown>)) {
+    out.set(name, toGlyph(name, value));
+  }
+  return out;
+}
+
+/**
+ * Glyph geometry, as characters: digits, the path-command letters, `currentColor`/`none`, and the
+ * separators between them. Deliberately not "anything that is not a quote" — an allowlist over a
+ * value bound for a code sink is the only shape that stays correct when the sink changes.
+ */
+export const SAFE_ATTR_VALUE = /^[\w\s.,+-]*$/;
+
+function toGlyph(name: string, value: unknown): IconGlyph {
+  const glyph: (readonly [string, Readonly<Record<string, string>>])[] = [];
+  for (const node of Array.isArray(value) ? (value as unknown[]) : []) {
+    if (!Array.isArray(node) || typeof node[0] !== 'string') continue;
+    const attrs: Record<string, string> = {};
+    for (const [key, item] of Object.entries((node[1] ?? {}) as Record<string, unknown>)) {
+      // Upstream keys an element for its diff tooling; it is not an SVG attribute.
+      if (key === 'key') continue;
+      const text = String(item);
+      // Defence in depth behind `moduleSource`'s escaping: geometry is digits, path commands and
+      // separators, so anything else in a value that is about to be written into a TYPESCRIPT
+      // module is refused here rather than escaped and shipped. Measured against the whole
+      // committed set — all 1767 glyphs pass (`build-icons.test.ts` asserts it), so this rejects
+      // no legitimate Lucide artwork.
+      if (!SAFE_ATTR_VALUE.test(text)) {
+        throw invalidIconDataError(
+          `for the icon "${name}" carries ${renderCauseValue(text)} as "${key}", which is not glyph geometry; lucide-static@${LUCIDE_VERSION} is the pin that published it, so a re-run against the same pin repeats this`,
+          'bun run --filter @ultimat3/ui icons   # after raising LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts',
+        );
+      }
+      attrs[key] = text;
+    }
+    glyph.push([node[0], attrs]);
+  }
+  // The same gate the component applies at render time, applied at generation time: a glyph that
+  // would throw in a page is a build failure here instead.
+  iconElements(glyph);
+  if (glyph.length === 0) {
+    throw invalidIconDataError(
+      `for the icon "${name}" carries no renderable node data; lucide-static@${LUCIDE_VERSION} is the pin that published it, so a re-run against the same pin repeats this`,
+      'bun run --filter @ultimat3/ui icons   # after raising LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts',
+    );
+  }
+  return glyph;
+}
+
+/**
+ * `JSON.stringify`, never `'${value}'`. The value is network-fetched data on its way into a
+ * TypeScript module that every app importing that icon will EXECUTE at import — a code sink, not
+ * an attribute sink. A raw quote in the value ends the string literal, and `');` after it starts
+ * a statement. `JSON.stringify` escapes quotes, backslashes and control characters, and Biome
+ * rewrites the quote style afterwards (`format()` below), so the committed output is unchanged.
+ * The key needs no escaping: `iconElements` has already refused every name off the allowlist.
+ */
+const attrsSource = (attrs: Readonly<Record<string, string>>): string =>
+  Object.entries(attrs)
+    .map(([key, value]) => `${/^[a-z]+$/.test(key) ? key : `'${key}'`}: ${JSON.stringify(value)}`)
+    .join(', ');
+
+/** One module's full text. Biome reformats it afterwards, so the layout here is only a seed. */
+export function moduleSource(name: string, glyph: IconGlyph): string {
+  const nodes = glyph.map(([tag, attrs]) => `  ['${tag}', { ${attrsSource(attrs)} }],`).join('\n');
+  return [
+    `// The Lucide "${name}" glyph as data. GENERATED by src/icons/build-icons.ts — do not edit.`,
+    `// Icon artwork © Lucide contributors, ISC (see src/icons/LICENSE.lucide).`,
+    '',
+    "import type { IconGlyph } from '../../components/icon-glyph';",
+    '',
+    `export const ${identifierFor(name)}: IconGlyph = [`,
+    nodes,
+    '];',
+    '',
+  ].join('\n');
+}
+
+/** Biome owns formatting in this repo, generated files included — so the generator asks it rather
+ * than imitating it, and a regenerated set never shows up as a lint diff. */
+async function format(): Promise<void> {
+  const biome = new URL('../../../../node_modules/.bin/biome', import.meta.url).pathname;
+  if (!(await Bun.file(biome).exists())) {
+    throw runtimeMissingError('the biome binary', 'bun install, then re-run this generator');
+  }
+  const result = Bun.spawnSync([biome, 'format', '--write', GLYPHS_DIR]);
+  if (result.exitCode !== 0) {
+    throw runtimeMissingError(
+      'a successful `biome format` over the generated glyphs',
+      `run: ${biome} format --write ${GLYPHS_DIR}`,
+    );
+  }
+}
+
+export async function buildIcons(): Promise<number> {
+  const response = await fetch(LUCIDE_ICON_NODES_URL);
+  if (!response.ok) {
+    throw runtimeMissingError(
+      `lucide-static@${LUCIDE_VERSION} icon data (HTTP ${response.status})`,
+      `check network access to ${LUCIDE_ICON_NODES_URL}, then re-run: bun run --filter @ultimat3/ui icons`,
+    );
+  }
+  const glyphs = parseIconNodes(await response.text());
+  // Cleared first: a renamed upstream icon must disappear, not linger as a second spelling.
+  await rm(GLYPHS_DIR, { recursive: true, force: true });
+  for (const [name, glyph] of [...glyphs].sort(([a], [b]) => a.localeCompare(b))) {
+    await Bun.write(`${GLYPHS_DIR}${name}.ts`, moduleSource(name, glyph));
+  }
+  await format();
+  return glyphs.size;
+}
+
+if (import.meta.main) {
+  const count = await buildIcons();
+  const json = { ok: true, icons: count, lucide: LUCIDE_VERSION, dir: GLYPHS_DIR };
+  console.log(Bun.argv.includes('--json') ? JSON.stringify(json) : `${count} icon modules written`);
+}

package/src/icons/glyphs/a-arrow-down.ts

@@ -0,0 +1,11 @@
+// The Lucide "a-arrow-down" glyph as data. GENERATED by src/icons/build-icons.ts — do not edit.
+// Icon artwork © Lucide contributors, ISC (see src/icons/LICENSE.lucide).
+
+import type { IconGlyph } from '../../components/icon-glyph';
+
+export const iconAArrowDown: IconGlyph = [
+  ['path', { d: 'm14 12 4 4 4-4' }],
+  ['path', { d: 'M18 16V7' }],
+  ['path', { d: 'm2 16 4.039-9.69a.5.5 0 0 1 .923 0L11 16' }],
+  ['path', { d: 'M3.304 13h6.392' }],
+];

package/src/icons/glyphs/a-arrow-up.ts

@@ -0,0 +1,11 @@
+// The Lucide "a-arrow-up" glyph as data. GENERATED by src/icons/build-icons.ts — do not edit.
+// Icon artwork © Lucide contributors, ISC (see src/icons/LICENSE.lucide).
+
+import type { IconGlyph } from '../../components/icon-glyph';
+
+export const iconAArrowUp: IconGlyph = [
+  ['path', { d: 'm14 11 4-4 4 4' }],
+  ['path', { d: 'M18 16V7' }],
+  ['path', { d: 'm2 16 4.039-9.69a.5.5 0 0 1 .923 0L11 16' }],
+  ['path', { d: 'M3.304 13h6.392' }],
+];

package/src/icons/glyphs/a-large-small.ts

@@ -0,0 +1,11 @@
+// The Lucide "a-large-small" glyph as data. GENERATED by src/icons/build-icons.ts — do not edit.
+// Icon artwork © Lucide contributors, ISC (see src/icons/LICENSE.lucide).
+
+import type { IconGlyph } from '../../components/icon-glyph';
+
+export const iconALargeSmall: IconGlyph = [
+  ['path', { d: 'm15 16 2.536-7.328a1.02 1.02 1 0 1 1.928 0L22 16' }],
+  ['path', { d: 'M15.697 14h5.606' }],
+  ['path', { d: 'm2 16 4.039-9.69a.5.5 0 0 1 .923 0L11 16' }],
+  ['path', { d: 'M3.304 13h6.392' }],
+];

package/src/icons/glyphs/accessibility.ts

@@ -0,0 +1,12 @@
+// The Lucide "accessibility" glyph as data. GENERATED by src/icons/build-icons.ts — do not edit.
+// Icon artwork © Lucide contributors, ISC (see src/icons/LICENSE.lucide).
+
+import type { IconGlyph } from '../../components/icon-glyph';
+
+export const iconAccessibility: IconGlyph = [
+  ['circle', { cx: '16', cy: '4', r: '1' }],
+  ['path', { d: 'm18 19 1-7-6 1' }],
+  ['path', { d: 'm5 8 3-3 5.5 3-2.36 3.5' }],
+  ['path', { d: 'M4.24 14.5a5 5 0 0 0 6.88 6' }],
+  ['path', { d: 'M13.76 17.5a5 5 0 0 0-6.88-6' }],
+];

package/src/icons/glyphs/activity.ts

@@ -0,0 +1,13 @@
+// The Lucide "activity" glyph as data. GENERATED by src/icons/build-icons.ts — do not edit.
+// Icon artwork © Lucide contributors, ISC (see src/icons/LICENSE.lucide).
+
+import type { IconGlyph } from '../../components/icon-glyph';
+
+export const iconActivity: IconGlyph = [
+  [
+    'path',
+    {
+      d: 'M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36a.25.25 0 0 1-.48 0L9.24 2.18a.25.25 0 0 0-.48 0l-2.35 8.36A2 2 0 0 1 4.49 12H2',
+    },
+  ],
+];

package/src/icons/glyphs/ad.ts

@@ -0,0 +1,16 @@
+// The Lucide "ad" glyph as data. GENERATED by src/icons/build-icons.ts — do not edit.
+// Icon artwork © Lucide contributors, ISC (see src/icons/LICENSE.lucide).
+
+import type { IconGlyph } from '../../components/icon-glyph';
+
+export const iconAd: IconGlyph = [
+  ['path', { d: 'M10 13H6' }],
+  ['path', { d: 'M10 15v-4a2 2 0 0 0-4 0v4' }],
+  [
+    'path',
+    {
+      d: 'M14 14.5a.5.5 0 0 0 .5.5h1a2.5 2.5 0 0 0 2.5-2.5v-1A2.5 2.5 0 0 0 15.5 9h-1a.5.5 0 0 0-.5.5z',
+    },
+  ],
+  ['rect', { x: '2', y: '5', width: '20', height: '14', rx: '2' }],
+];