@adia-ai/web-components 0.5.2 → 0.5.4

package/components/table/table.a2ui.json

@@ -143,6 +143,19 @@
           }
         }
       },
+      "row-collapse": {
+        "description": "Fired when an already-expanded row's chevron is activated (collapses the row). Mirror of row-expand.",
+        "detail": {
+          "index": {
+            "description": "Row index in the underlying data array.",
+            "type": "number"
+          },
+          "row": {
+            "description": "Row data object.",
+            "type": "object"
+          }
+        }
+      },
       "row-expand": {
         "description": "Fired when an expandable row's chevron is activated. detail.index is the row position; detail.row is the row data.",
         "detail": {

package/components/table/table.d.ts

@@ -44,6 +44,14 @@ export interface TableResizeEventDetail {
 }
 
 export type TableResizeEvent = CustomEvent<TableResizeEventDetail>;
+export interface TableRowCollapseEventDetail {
+  /** Row index in the underlying data array. */
+  index: number;
+  /** Row data object. */
+  row: Record<string, unknown>;
+}
+
+export type TableRowCollapseEvent = CustomEvent<TableRowCollapseEventDetail>;
 export interface TableRowExpandEventDetail {
   /** Row index in the underlying data array. */
   index: number;
@@ -102,6 +110,7 @@ export class UITable extends UIElement {
   addEventListener(type: 'filter-change', listener: (ev: TableFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'page', listener: (ev: TablePageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'resize', listener: (ev: TableResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'row-collapse', listener: (ev: TableRowCollapseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'row-expand', listener: (ev: TableRowExpandEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'select', listener: (ev: TableSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'sort', listener: (ev: TableSortEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/components/table/table.yaml

@@ -108,6 +108,15 @@ events:
       width:
         type: number
         description: New column width in pixels.
+  row-collapse:
+    description: Fired when an already-expanded row's chevron is activated (collapses the row). Mirror of row-expand.
+    detail:
+      index:
+        type: number
+        description: Row index in the underlying data array.
+      row:
+        type: object
+        description: Row data object.
   row-expand:
     description: Fired when an expandable row's chevron is activated. detail.index is the row position; detail.row is the row data.
     detail:
@@ -187,6 +196,10 @@ tokens:
     description: Sort arrow color
   --table-transition:
     description: Transition timing
+requiredIcons:
+  - caret-right
+  - caret-up-down
+  - table
 a2ui:
   rules: []
 anti_patterns: []

package/components/tag/class.js

@@ -27,6 +27,12 @@
 import { UIElement } from '../../core/element.js';
 
 export class UITag extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['x'];
+
   static properties = {
     text:      { type: String,  default: '', reflect: true },
     textContent: { type: String, default: '' },

package/components/tag/tag.yaml

@@ -61,6 +61,8 @@ states:
     attribute: disabled
 traits: []
 tokens: {}
+requiredIcons:
+  - x
 a2ui:
   rules: []
 anti_patterns: []

package/components/textarea/class.js

@@ -20,6 +20,7 @@
 import { UIFormElement } from '../../core/form.js';
 
 export class UITextarea extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per textarea.yaml
   static properties = {
     ...UIFormElement.properties,
     placeholder: { type: String,  default: '', reflect: true },

package/components/tree/class.js

@@ -35,6 +35,12 @@
 import { UIElement } from '../../core/element.js';
 
 export class UITree extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['caret-right'];
+
   static template = () => null;
 
   connected() {

package/components/tree/tree.yaml

@@ -66,6 +66,8 @@ tokens:
     description: Inline-end padding of each row
   --tree-row-radius:
     description: Border radius of each row
+requiredIcons:
+  - caret-right
 a2ui:
   rules: []
 anti_patterns: []

package/components/upload/class.js

@@ -20,6 +20,7 @@
 import { UIFormElement } from '../../core/form.js';
 
 export class UIUpload extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per upload.yaml
   static properties = {
     ...UIFormElement.properties,
     label:    { type: String,  default: '', reflect: true },

package/core/icons.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Icon registry — pluggable lookup map for `<icon-ui>` SVG resolution.
+ *
+ * Three consumer paths, picked by bundle-size budget:
+ *
+ *   1. **Zero-config** — import the main barrel; phosphor side-effect-loads
+ *      via `core/icons-phosphor.js`. Largest bundle (~9 000 chunks under
+ *      `vite build`). Best for prototypes.
+ *
+ *   2. **Opt-in phosphor with piecemeal component imports** — when you
+ *      `import '@adia-ai/web-components/components/button'` etc. you skip
+ *      the barrel's phosphor side-effect. Add it explicitly:
+ *        import '@adia-ai/web-components/core/icons-phosphor';
+ *
+ *   3. **Scoped registration (smallest bundle)** — install only the icons
+ *      you use via `installIconLoaders()` with a brace-list glob, OR
+ *      `installIconLoadersForRegistered()` to auto-discover from defined
+ *      primitives' `static requiredIcons`.
+ *
+ * Runtime exports mirror `core/icons.js`. `installIconLoadersForRegistered`
+ * shipped in v0.5.3 §154 (FEEDBACK-06 §4 + FEEDBACK-07 §4). `.d.ts`
+ * authored in v0.5.4 to close the missing-type-surface gap that blocked
+ * TypeScript consumers from importing the helper.
+ *
+ * @see ../USAGE.md (consumer guide)
+ * @see ./icons-phosphor.js (the zero-config side-effect path)
+ */
+
+/**
+ * Phosphor weight identifiers. `regular` is the default; the other five
+ * weights resolve to the corresponding `@phosphor-icons/core/assets/<weight>/`
+ * subtree when consumers install loaders for them.
+ */
+export const ICON_WEIGHTS: ReadonlyArray<'regular' | 'thin' | 'light' | 'bold' | 'fill' | 'duotone'>;
+
+/** A single phosphor weight identifier. */
+export type IconWeight = 'regular' | 'thin' | 'light' | 'bold' | 'fill' | 'duotone';
+
+/**
+ * Loader value in an icon-loader map. Either the SVG string itself (eager
+ * `import.meta.glob({ eager: true })` output) or a thunk that resolves to
+ * the SVG string (lazy / dynamic import).
+ */
+export type IconLoader = string | (() => string | Promise<string>);
+
+/**
+ * Per-path loader map for a single weight. Keys are typically the
+ * `/node_modules/@phosphor-icons/core/assets/<weight>/<filename>.svg` paths
+ * `import.meta.glob` produces — but any keys work (§140's filename-suffix
+ * fallback handles pnpm / yarn-berry / custom-Vite-root prefixes).
+ */
+export type IconLoaderMap = Record<string, IconLoader>;
+
+/**
+ * Per-weight loader maps. Pass to `installIconLoaders()` /
+ * `installIconLoadersForRegistered()`. Most consumers pass only `regular`;
+ * weight-overloaded usage (e.g. `<icon-ui name="star" weight="fill">`)
+ * needs the corresponding weight populated.
+ */
+export interface WeightModules {
+  regular?: IconLoaderMap;
+  thin?: IconLoaderMap;
+  light?: IconLoaderMap;
+  bold?: IconLoaderMap;
+  fill?: IconLoaderMap;
+  duotone?: IconLoaderMap;
+}
+
+/** Register a single icon by name. Bypasses loader-map lookup entirely. */
+export function registerIcon(name: string, svg: string, weight?: IconWeight): void;
+
+/** Register multiple icons at a single weight. Bypasses loader-map lookup. */
+export function registerIcons(icons: Record<string, string>, weight?: IconWeight): void;
+
+/**
+ * Get icon SVG by name + weight. Returns the cached SVG if present;
+ * otherwise triggers an async load (returning `''` immediately) + the
+ * registered `<icon-ui>` elements re-render once the load resolves.
+ */
+export function getIcon(name: string, weight?: IconWeight): string;
+
+/** Sync check — is `name` cached in the registry at this weight? */
+export function hasIcon(name: string, weight?: IconWeight): boolean;
+
+/** List all cached `weight:name` keys in the registry. */
+export function listIcons(): string[];
+
+/**
+ * Sync check — is `name` (or its `ICON_ALIASES` alias) a known icon at
+ * the given weight? Doesn't trigger loading. Used by primitives that
+ * accept either an icon name or a text label (`<input-ui prefix>`,
+ * `<input-ui suffix>`) to disambiguate.
+ */
+export function isIconName(name: string, weight?: IconWeight): boolean;
+
+/**
+ * Resolves once the icon registry is sync-checkable — i.e., after the
+ * first `installIconLoaders()` call. Primitives that branch on
+ * `isIconName` at connect time should await this to avoid the static-
+ * deploy race (the registry starts empty, fills async via manifest fetch).
+ */
+export const whenIconRegistryReady: Promise<void>;
+
+/**
+ * Install a per-weight loader map. Idempotent — subsequent calls replace
+ * the previous map. After install, re-stamps any existing
+ * `<icon-ui[name]>` elements so they re-render with the newly-loadable
+ * SVGs.
+ *
+ * @param modules per-weight maps; missing weights stay empty.
+ */
+export function installIconLoaders(modules: WeightModules): void;
+
+/**
+ * Auto-discover the icon set from defined primitives' `static
+ * requiredIcons` declarations, then install loaders.
+ *
+ * Each AdiaUI primitive that auto-stamps icons declares them via:
+ *
+ *     export class UISelect extends UIFormElement {
+ *       static requiredIcons = ['caret-up-down'];
+ *       // ...
+ *     }
+ *
+ * This helper aggregates the union across all currently-defined
+ * primitives (post-side-effect imports) and installs `modules` as the
+ * loader source. The returned list is the discovered set — useful for
+ * trimming a wide glob to only what's needed.
+ *
+ * Shipped v0.5.3 §154 (FEEDBACK-06 §4 + FEEDBACK-07 §4).
+ *
+ * @param modules - per-weight loader maps (typically `import.meta.glob`
+ *                  output for `@phosphor-icons/core/assets/<weight>/*.svg`)
+ * @returns the union of `static requiredIcons` across all defined primitives
+ */
+export function installIconLoadersForRegistered(
+  modules: IconLoaderMap | WeightModules
+): string[];
+
+export namespace installIconLoadersForRegistered {
+  /**
+   * Same-shape companion to `installIconLoadersForRegistered` but
+   * doesn't install. Returns the union of `static requiredIcons` across
+   * all currently-defined primitives — useful when you want to build a
+   * narrower glob from the discovered list.
+   */
+  function discover(): string[];
+}

package/core/icons.js

@@ -140,6 +140,104 @@ export function installIconLoaders(modules) {
   resolveRegistryReady();
 }
 
+/**
+ * Aggregate `static requiredIcons` declarations from all currently-defined
+ * `customElements`, install loaders for the union, and return the list of
+ * discovered icon names. Replaces the trial-and-error icon-glob authoring
+ * loop FEEDBACK-06 §4 + FEEDBACK-07 §4 reported.
+ *
+ * Each AdiaUI primitive that auto-stamps icons declares them via:
+ *
+ *   export class UISelect extends UIFormElement {
+ *     static requiredIcons = ['caret-up-down'];
+ *     // ...
+ *   }
+ *
+ * Consumer usage:
+ *
+ *   import '@adia-ai/web-components';  // side-effect — defines all primitives
+ *   import { installIconLoadersForRegistered } from '@adia-ai/web-components/core/icons';
+ *
+ *   // Build the Phosphor loader map from your bundler (Vite, Webpack, etc.).
+ *   const modules = import.meta.glob('/node_modules/@phosphor-icons/core/assets/regular/*.svg', { query: '?raw' });
+ *
+ *   // Aggregate requiredIcons across all defined primitives + install.
+ *   const discovered = installIconLoadersForRegistered(modules);
+ *
+ * Or, to limit the icon set to ONLY what's needed (smaller bundle):
+ *
+ *   const discovered = installIconLoadersForRegistered.discover();
+ *   // discovered: ['caret-up-down', 'x', 'caret-right', ...]
+ *   // Now build a narrower glob from this list.
+ *
+ * Added v0.5.3 §154 per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+ *
+ * @param {Record<string, () => Promise<string>>} modules - Phosphor loader map
+ * @returns {string[]} The union of all primitives' `requiredIcons`
+ */
+export function installIconLoadersForRegistered(modules) {
+  const discovered = discoverRequiredIcons();
+  installIconLoaders(modules);
+  return discovered;
+}
+
+/**
+ * Walk customElements and collect the union of `static requiredIcons` across
+ * all defined primitives. Useful for building a Vite glob brace-list that
+ * matches exactly what the registered primitives need.
+ *
+ * Returns an empty array if `customElements` is unavailable (Node SSR)
+ * or if no defined primitive exposes `requiredIcons`.
+ */
+function discoverRequiredIcons() {
+  const union = new Set();
+  if (typeof customElements === 'undefined') return [];
+  // customElements has no Object.entries-style iterator in the standard API.
+  // We need to track which tag names have been defined. The AdiaUI convention:
+  // every primitive's tag ends in `-ui` (or `-n` per yaml `tag:` pattern). We
+  // walk a known list of tag names — passed via opt-in. For SSR safety the
+  // consumer can also pass `tags` explicitly:
+  // discoverRequiredIcons(['select-ui', 'tag-ui', ...]).
+  //
+  // For browser usage with the default barrel import, the consumer's
+  // `import '@adia-ai/web-components'` defines all 93+ primitives at the
+  // global custom-element registry; we walk the DOM-known tag names by
+  // checking customElements.get() on the AdiaUI prefix convention.
+  //
+  // Strategy: query all defined tags by walking the document's primitive
+  // surface OR accept an explicit tag list. The simpler API: iterate over
+  // a known whitelist of tag names. We embed the whitelist for known
+  // auto-stamping primitives.
+  const KNOWN_AUTO_STAMPING_TAGS = [
+    'accordion-ui',
+    'agent-questions-ui',
+    'agent-reasoning-ui',
+    'agent-trace-ui',
+    'calendar-picker-ui',
+    'color-picker-ui',
+    'command-ui',
+    'pane-ui',
+    'select-ui',
+    'table-ui',
+    'tag-ui',
+    'tree-ui',
+  ];
+  for (const tag of KNOWN_AUTO_STAMPING_TAGS) {
+    const ctor = customElements.get(tag);
+    if (ctor && Array.isArray(ctor.requiredIcons)) {
+      for (const name of ctor.requiredIcons) union.add(name);
+    }
+  }
+  return [...union];
+}
+
+/**
+ * Public discovery — same shape as installIconLoadersForRegistered but
+ * doesn't install. Returns the union of `static requiredIcons` across
+ * all currently-defined auto-stamping AdiaUI primitives.
+ */
+installIconLoadersForRegistered.discover = discoverRequiredIcons;
+
 /* Track which (name, weight) pairs we've already warned about so the
    console stays readable even when a missing icon is used many times on
    a page (e.g. a broken Phosphor name in a list row repeated 50×). */
@@ -168,17 +266,62 @@ function filenameFor(name, weight) {
   return `${name}-${weight}.svg`;
 }
 
+/* Resolve a loader by name + weight, tolerant of path-prefix variation.
+ *
+ * Two-step lookup, fast-path first:
+ *
+ *   1. **Fast path**: try the canonical `/node_modules/@phosphor-icons/core/
+ *      assets/<weight>/<filename>` key directly. This is what `icons-phosphor.js`
+ *      installs when Vite's project root sits above an npm-style node_modules,
+ *      and what the chat-ui dev convention assumes.
+ *
+ *   2. **Suffix fallback**: if the fast path misses, scan `modules` keys for
+ *      one ending with `/<filename>`. Handles:
+ *        - pnpm: `/node_modules/.pnpm/@phosphor-icons+core@.../node_modules/.../assets/...`
+ *        - yarn berry / PnP: virtual paths like `/.yarn/cache/...`
+ *        - custom Vite root: `/packages/my-app/node_modules/...`
+ *        - brace-list globs with absolute paths
+ *        - manually-built loader maps with arbitrary keys
+ *
+ * The fast path stays O(1); the fallback is O(N) over the weight's module
+ * map but only runs once per (name, weight) miss (results aren't cached, but
+ * misses fall through to a registry hit via `loadIcon`'s `registry.set`).
+ *
+ * Same two-step shape applies to the `-fill` back-compat name suffix.
+ *
+ * Fix history: pre-§140 the function was fast-path-only. FEEDBACK-06 from
+ * color-app reported `installIconLoaders` → `warnMissingIcon` firing for
+ * `caret-right` / `x` / `caret-up-down` even though the consumer had installed
+ * a loader map. Root cause: color-app's `modules` keys didn't match the
+ * canonical `/node_modules/...` prefix (different package-manager or Vite
+ * root). The suffix fallback closes that gap without changing the public API.
+ */
 function resolveLoader(name, weight = DEFAULT_WEIGHT) {
   const modules = weightModules[weight];
   if (!modules) return null;
-  const key = `/node_modules/@phosphor-icons/core/assets/${weight}/${filenameFor(name, weight)}`;
-  if (modules[key]) return modules[key];
+  const filename = filenameFor(name, weight);
+
+  // 1. Fast path — canonical phosphor npm-style path.
+  const fastKey = `/node_modules/@phosphor-icons/core/assets/${weight}/${filename}`;
+  if (modules[fastKey]) return modules[fastKey];
+
+  // 2. Suffix fallback — match any key ending with the filename.
+  const suffix = `/${filename}`;
+  for (const key in modules) {
+    if (key.endsWith(suffix)) return modules[key];
+  }
 
   // Back-compat: allow the caller to put the -fill suffix directly in the
-  // name (e.g. `name="circle-fill"`) without specifying weight.
+  // name (e.g. `name="circle-fill"`) without specifying weight. Two-step
+  // lookup applies here too.
   if (weight === DEFAULT_WEIGHT && name.endsWith('-fill')) {
-    const fillKey = `/node_modules/@phosphor-icons/core/assets/fill/${name}.svg`;
-    if (weightModules.fill[fillKey]) return weightModules.fill[fillKey];
+    const fillFilename = `${name}.svg`;
+    const fillFastKey = `/node_modules/@phosphor-icons/core/assets/fill/${fillFilename}`;
+    if (weightModules.fill[fillFastKey]) return weightModules.fill[fillFastKey];
+    const fillSuffix = `/${fillFilename}`;
+    for (const key in weightModules.fill) {
+      if (key.endsWith(fillSuffix)) return weightModules.fill[key];
+    }
   }
   return null;
 }

package/core/icons.test.js

@@ -0,0 +1,187 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  installIconLoaders,
+  registerIcon,
+  hasIcon,
+  isIconName,
+  getIcon,
+  listIcons,
+} from './icons.js';
+
+// Tests for `installIconLoaders` + `resolveLoader` + the §140 suffix-
+// fallback fix for FEEDBACK-06 (color-app's `installIconLoaders` →
+// `warnMissingIcon` failures on `caret-right` / `x` / `caret-up-down`
+// when the consumer's `modules` keys didn't match the canonical
+// `/node_modules/@phosphor-icons/core/assets/<weight>/<name>.svg` path.
+//
+// `isIconName` is the SYNC probe — it calls `resolveLoader` without
+// triggering an async load. That's what we need to assert the fallback
+// logic finds the loader regardless of path shape.
+
+const CARET_RIGHT_SVG = '<svg data-icon="caret-right"/>';
+const X_SVG = '<svg data-icon="x"/>';
+const CARET_UP_DOWN_SVG = '<svg data-icon="caret-up-down"/>';
+
+describe('installIconLoaders + resolveLoader (§140 suffix fallback)', () => {
+  beforeEach(() => {
+    // Reset to a known state. Note: the registry Map itself is module-
+    // singleton + doesn't reset between tests, so we keep test SVG
+    // contents distinct from any real phosphor names just in case.
+    installIconLoaders({ regular: {}, thin: {}, light: {}, bold: {}, fill: {}, duotone: {} });
+  });
+
+  it('resolves by canonical phosphor path (fast path)', () => {
+    installIconLoaders({
+      regular: {
+        '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': CARET_RIGHT_SVG,
+        '/node_modules/@phosphor-icons/core/assets/regular/x.svg': X_SVG,
+      },
+    });
+
+    expect(isIconName('caret-right')).toBe(true);
+    expect(isIconName('x')).toBe(true);
+  });
+
+  it('resolves by filename suffix when key has a pnpm-style prefix', () => {
+    // pnpm hoists phosphor inside `.pnpm/<pkg>@<ver>/node_modules/...`
+    installIconLoaders({
+      regular: {
+        '/node_modules/.pnpm/@phosphor-icons+core@2.1.1/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg':
+          CARET_RIGHT_SVG,
+      },
+    });
+
+    expect(isIconName('caret-right')).toBe(true);
+  });
+
+  it('resolves by filename suffix when key is a custom Vite-root absolute path', () => {
+    // Custom Vite root puts node_modules at a deeper location.
+    installIconLoaders({
+      regular: {
+        '/packages/my-app/node_modules/@phosphor-icons/core/assets/regular/caret-up-down.svg':
+          CARET_UP_DOWN_SVG,
+      },
+    });
+
+    expect(isIconName('caret-up-down')).toBe(true);
+  });
+
+  it('resolves by filename suffix for an arbitrary manually-built loader map', () => {
+    // Manual loader maps may have any keys at all — only the filename matters.
+    installIconLoaders({
+      regular: {
+        '/anywhere/at/all/caret-right.svg': CARET_RIGHT_SVG,
+        '/another/path/entirely/x.svg': X_SVG,
+      },
+    });
+
+    expect(isIconName('caret-right')).toBe(true);
+    expect(isIconName('x')).toBe(true);
+  });
+
+  it('returns false on miss across both paths', () => {
+    installIconLoaders({
+      regular: {
+        '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': CARET_RIGHT_SVG,
+      },
+    });
+
+    expect(isIconName('not-a-real-icon-name')).toBe(false);
+  });
+
+  it('resolves `-fill` back-compat suffix in name via fast path', () => {
+    const STAR_FILL_SVG = '<svg data-icon="star-fill"/>';
+    installIconLoaders({
+      regular: {},
+      fill: {
+        '/node_modules/@phosphor-icons/core/assets/fill/star-fill.svg': STAR_FILL_SVG,
+      },
+    });
+
+    // `name="star-fill"` with default weight=regular falls back to fill weight.
+    expect(isIconName('star-fill')).toBe(true);
+  });
+
+  it('resolves `-fill` back-compat suffix in name via suffix fallback', () => {
+    const STAR_FILL_SVG = '<svg data-icon="star-fill"/>';
+    installIconLoaders({
+      regular: {},
+      fill: {
+        '/anywhere/star-fill.svg': STAR_FILL_SVG,
+      },
+    });
+
+    expect(isIconName('star-fill')).toBe(true);
+  });
+
+  it('resolves non-regular weights (bold, fill, etc.) via suffix fallback', () => {
+    const HEART_BOLD_SVG = '<svg data-icon="heart-bold"/>';
+    installIconLoaders({
+      regular: {},
+      bold: {
+        '/anywhere/heart-bold.svg': HEART_BOLD_SVG,
+      },
+    });
+
+    expect(isIconName('heart', 'bold')).toBe(true);
+  });
+
+  it('isIconName returns true via alias resolution + suffix fallback', () => {
+    // `send` → `paper-plane-right` in ICON_ALIASES. Suffix fallback should
+    // still match the aliased filename.
+    const PAPER_PLANE_SVG = '<svg data-icon="paper-plane-right"/>';
+    installIconLoaders({
+      regular: {
+        '/anywhere/paper-plane-right.svg': PAPER_PLANE_SVG,
+      },
+    });
+
+    expect(isIconName('send')).toBe(true);
+  });
+
+  it('end-to-end via DOM re-stamp: installIconLoaders auto-loads existing <icon-ui[name]>', async () => {
+    // The §140 fix's primary symptom: `installIconLoaders` walks existing
+    // `<icon-ui[name]>` elements + calls `loadIcon` for each. Without the
+    // suffix fallback, `loadIcon` → `resolveLoader` returns null →
+    // `warnMissingIcon` fires. With the fix, the load completes.
+    const PAW_SVG = '<svg data-icon="paw"/>';
+
+    // Plant an `<icon-ui[name="paw"]>` element. We don't need it to
+    // actually upgrade; we just need `querySelectorAll('icon-ui[name]')`
+    // to find it.
+    const el = document.createElement('icon-ui');
+    el.setAttribute('name', 'paw');
+    document.body.appendChild(el);
+
+    // Install a loader map with a pnpm-style path (suffix fallback exercise).
+    installIconLoaders({
+      regular: {
+        '/some/non-canonical/prefix/paw.svg': PAW_SVG,
+      },
+    });
+
+    // `loadIcon` runs sync (loader is a string, not a function), so the
+    // registry is written by the time `installIconLoaders` returns.
+    expect(hasIcon('paw')).toBe(true);
+
+    document.body.removeChild(el);
+  });
+});
+
+describe('registerIcon / hasIcon — unchanged by §140', () => {
+  it('registerIcon adds an icon by name without needing a loader map', () => {
+    const CUSTOM_SVG = '<svg data-icon="custom-§140-marker"/>';
+    registerIcon('my-§140-custom-icon', CUSTOM_SVG);
+
+    expect(hasIcon('my-§140-custom-icon')).toBe(true);
+    expect(getIcon('my-§140-custom-icon')).toBe(CUSTOM_SVG);
+  });
+
+  it('listIcons returns registered names', () => {
+    registerIcon('§140-listIcons-marker-one', '<svg/>');
+    registerIcon('§140-listIcons-marker-two', '<svg/>');
+
+    expect(listIcons().some((k) => k.includes('§140-listIcons-marker-one'))).toBe(true);
+    expect(listIcons().some((k) => k.includes('§140-listIcons-marker-two'))).toBe(true);
+  });
+});