@adia-ai/web-components 0.8.31 → 0.8.33

package/components/tag/tag.yaml

@@ -46,35 +46,46 @@ props:
     type: string
     dynamic: true
   variant:
-    description: Semantic variant — `default | accent | info | success | warning | danger`.
-      `accent` is brand-primary emphasis for non-semantic labels — a filter chip
+    description: Semantic variant — `default | info | success | warning | danger | primary`.
+      `primary` is brand emphasis for non-semantic labels — a filter chip
       or taxonomy tag that shouldn't imply a success/warning/danger state. Mirrors
-      <badge-ui>'s `accent` variant token-for-token.
+      <badge-ui>'s `primary` variant token-for-token (`accent` retired, gh#874 —
+      the capability survives renamed, sibling parity with badge preserved).
     type: string
     default: default
     enum:
       - default
-      - accent
       - info
       - success
       - warning
       - danger
+      - primary
   tone:
     description: |
       Fill style — orthogonal to [variant]. Three values:
-        - `solid` (default for family variants) — saturated bg + on-strong
-          (near-white) text. The chip IS the state.
-        - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s
-          default look. Use on metadata chips in dense lists where the
-          saturated default would compete for attention.
+        - `muted` (default for the family variants — info/success/warning/
+          danger/primary — gh#864: tag and badge were swapped relative to
+          their reported default formulas; this restores tag's own)
+          — tinted bg with scheme-paired text. Matches <badge-ui>'s
+          `[tone="muted"]` look. Use on metadata / citation chips in dense
+          lists or tables where a saturated fill would compete for
+          attention (gh#778's oversized-pill concern). Does NOT apply to
+          the family-less `default` variant, which stays solid
+          unconditionally (gh#794, unaffected by gh#864) — a bare
+          `<tag-ui text="…">` still renders that solid look with no
+          attributes at all.
+        - `solid` — saturated bg + on-strong (near-white) text. The chip
+          IS the state. Opt in explicitly for a family variant (gh#864),
+          or it's already the unconditional look for the family-less
+          `default` variant (gh#794).
         - `outline` — transparent bg + family-colored border + family-colored
           text. The lightest visual weight; good in dense data tables or
           faceted filter rows where multiple chips would otherwise compete.
-      The `default` variant (no family) stays quiet chrome regardless of
-      tone unless `tone="solid"` is set explicitly (high-contrast neutral
-      inverse), or `tone="outline"` (fg-muted text + subtle border).
+      `tone` is a declarative presentational attribute (not a reactive
+      prop — see tag.class.js) so its schema `default` here is documentation
+      of the rendered-by-default look, not a reflected attribute value.
     type: string
-    default: solid
+    default: muted
     enum:
       - solid
       - muted
@@ -127,6 +138,17 @@ a2ui:
       Group multiple tags inside a <row-ui gap="2"> — never stack them
       vertically; vertical lists of dismissable items are an
       <action-list-ui> use case, not <tag-ui>.
+    - >-
+      A family-less <tag-ui text="…"> (no [variant], no [tone]) renders
+      the high-contrast solid pill by default (gh#794). In dense tables,
+      tight metadata rows, or citation/footnote strips where many tags
+      sit close together, set [tone="muted"] to keep the quieter tinted
+      look instead — a wall of solid pills reads as visual noise there
+      (gh#778).
+    - >-
+      A family [variant] (info/success/warning/danger/primary) with no
+      [tone] renders the tinted-container look by default (gh#864). Set
+      [tone="solid"] for a saturated status stamp instead.
 anti_patterns: []
 examples:
   - name: basic-tag

package/components/tags-input/tags-input.d.ts

@@ -108,13 +108,13 @@ replaces the rendered chips. Reflection skipped — array values
 do not round-trip through attribute strings. */
   value: string;
 
+  addEventListener(type: 'change', listener: (ev: TagsInputChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'commit', listener: (ev: TagsInputCommitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: TagsInputInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'invalid', listener: (ev: TagsInputInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITagsInput, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'change', listener: (ev: TagsInputChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'commit', listener: (ev: TagsInputCommitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'input', listener: (ev: TagsInputInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'invalid', listener: (ev: TagsInputInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/timeline/timeline.d.ts

@@ -25,12 +25,12 @@ export class UITimeline extends UIElement {
   /** Rail size preset — use `sm` for agent-reasoning/pipeline views; `md` is the default. */
   size: 'sm' | 'md';
 
+  addEventListener(type: 'timeline-toggle', listener: (ev: TimelineToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITimeline, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'timeline-toggle', listener: (ev: TimelineToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UITimelineItem extends UIElement {

package/components/toast/toast.a2ui.json

@@ -40,7 +40,7 @@
       "default": ""
     },
     "variant": {
-      "description": "Semantic variant — `default | info | success | warning | danger`. `primary` and `muted` are style hints; canonical \"neutral but interesting\" tone is `info`.",
+      "description": "Semantic variant — `default | info | success | warning | danger | primary`. `primary` is the brand-emphasis fill (mirrors badge-ui/button-ui's `primary`); canonical \"neutral but interesting\" tone is `info`.",
       "type": "string",
       "enum": [
         "default",
@@ -48,9 +48,7 @@
         "success",
         "warning",
         "danger",
-        "primary",
-        "muted",
-        "neutral"
+        "primary"
       ],
       "default": "info"
     }

package/components/toast/toast.css

@@ -148,18 +148,6 @@ toast-ui[data-closing][position="top-left"] {
     --toast-border: var(--md-sys-color-primary-outline-variant);
   }
 
-  /* `muted` and `neutral` are semantic aliases of the base canvas
-     surface — same tokens as the unstyled `:scope`, declared explicitly
-     so the yaml enum and the CSS contract agree. Use cases: quiet
-     status nudges that shouldn't carry tonal weight (e.g. "Draft
-     saved" without success-green). Mirrors alert-ui's pattern. */
-  :where(:scope[variant="muted"]),
-  :where(:scope[variant="neutral"]) {
-    --toast-bg:     var(--a-bg-subtle);
-    --toast-fg:     var(--md-sys-color-neutral-on-surface);
-    --toast-border: var(--md-sys-color-neutral-outline-variant);
-  }
-
   /* ── Message slot ── */
 
   [slot="message"] {

package/components/toast/toast.yaml

@@ -37,8 +37,9 @@ props:
     default: ""
   variant:
     description: >-
-      Semantic variant — `default | info | success | warning | danger`.
-      `primary` and `muted` are style hints; canonical "neutral but
+      Semantic variant — `default | info | success | warning | danger |
+      primary`. `primary` is the brand-emphasis fill (mirrors
+      badge-ui/button-ui's `primary`); canonical "neutral but
       interesting" tone is `info`.
     type: string
     default: info
@@ -49,8 +50,6 @@ props:
       - warning
       - danger
       - primary
-      - muted
-      - neutral
 events: {}
 usage: |-
   §224 (v0.5.9): `UIToast.show()` routes through `UIFeed.post()` — the

package/components/toc/toc.d.ts

@@ -52,10 +52,10 @@ scans the toc-ui's parent element. Set to `#article` /
  */
   target: string;
 
+  addEventListener(type: 'section-change', listener: (ev: TableOfContentsSectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITableOfContents, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'section-change', listener: (ev: TableOfContentsSectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/toggle-group/toggle-group.d.ts

@@ -25,12 +25,12 @@ export class UIToggleGroup extends UIElement {
   /** Comma-separated selected values */
   value: string;
 
+  addEventListener(type: 'change', listener: (ev: ToggleGroupChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIToggleGroup, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'change', listener: (ev: ToggleGroupChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UIToggleOption extends UIElement {

package/components/toggle-scheme/toggle-scheme.d.ts

@@ -49,10 +49,10 @@ export class UIToggleScheme extends UIElement {
   /** Visual style forwarded to the internal <button-ui>. Defaults to "ghost" (matches app practice). */
   variant: 'default' | 'solid' | 'outline' | 'ghost' | 'primary' | 'secondary' | 'soft';
 
+  addEventListener(type: 'scheme-change', listener: (ev: ToggleSchemeSchemeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIToggleScheme, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'scheme-change', listener: (ev: ToggleSchemeSchemeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/tour/tour.d.ts

@@ -48,15 +48,15 @@ tour to that step (updating spotlight + popover position).
  */
   step: number;
 
+  addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-start', listener: (ev: TourStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-step-change', listener: (ev: TourStepChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITour, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'tour-start', listener: (ev: TourStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'tour-step-change', listener: (ev: TourStepChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UITourStep extends UIElement {

package/components/tree/tree.d.ts

@@ -31,12 +31,12 @@ export type TreeSelectEvent = CustomEvent<TreeSelectEventDetail>;
 
 export class UITree extends UIElement {
 
+  addEventListener(type: 'tree-select', listener: (ev: TreeSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITree, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'tree-select', listener: (ev: TreeSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UITreeItem extends UIElement {

package/core/icons-phosphor.js

@@ -37,36 +37,48 @@
  *   });
  *
  * Brace-list globs are statically analyzed; only the named files are
- * emitted as chunks (or inlined when `eager: true`). Use the `../node_modules/...`
- * form shown here, not `/node_modules/...` — see "Why the glob is entry-relative,
- * not root-relative" below; the same reasoning applies to a hand-written
- * scoped glob as to the auto-discovery globs this file installs by default.
+ * emitted as chunks (or inlined when `eager: true`). Better yet, in your OWN
+ * source you can skip globs entirely and use plain bare-specifier `?raw`
+ * imports (see `icons.js`'s JSDoc, loading path 3) — module resolution finds
+ * the package under any layout. If you do hand-write a glob, note it resolves
+ * by literal path join from YOUR file, not module resolution — see "Why there
+ * are three candidate globs" below.
  *
- * ## Why the glob is entry-relative, not root-relative
+ * ## Why there are three candidate globs, not one (gh#287 · gh#340 · gh#786)
  *
  * `import.meta.glob` only accepts a small set of static forms (`/`-rooted,
  * `./`, `../`, `**\/`, or a `#`-subpath with a literal `*`), and each resolves
  * via a literal path join, not module resolution (confirmed against Vite 8's
- * `toAbsoluteGlob`, gh#287). A `/`-rooted glob joins to Vite's CONFIGURED
- * PROJECT ROOT — for a consumer app, that only reaches `@phosphor-icons/core`
- * when it's ALSO hoisted to that exact root. Under pnpm's default
- * (non-hoisted, symlinked) linking, a package you depend on only
- * TRANSITIVELY — `@phosphor-icons/core` is a dependency of THIS package, not
- * necessarily your app's — is linked only inside that package's own
- * resolution scope, never flattened into your app's top-level `node_modules`.
- * A root-rooted glob then silently matches zero files.
- *
- * A `../`-prefixed glob instead joins to THIS FILE'S OWN directory
- * (`core/`), one level inside `@adia-ai/web-components` — so `../node_modules`
- * reaches `@adia-ai/web-components`'s own local `node_modules`, which pnpm
- * always populates with a package's own direct dependencies (a symlink into
- * the pnpm store) regardless of whether your app also hoists them. This
- * holds for the published package too — `core/icons-phosphor.js` ships at
- * the same one-level depth (see `package.json`'s `files` field). Verified
- * empirically against a real hoisting-gap install (a pnpm workspace where
- * `@phosphor-icons/core` is declared only by a nested package, not the
- * workspace root): the root-rooted form matches zero files; the
- * entry-relative form matches the full set with real content.
+ * `toAbsoluteGlob`, gh#287). No single literal path exists that reaches
+ * `@phosphor-icons/core` under every package manager's `node_modules` layout,
+ * so this file probes THREE entry-relative candidates (resolved from this
+ * file's own directory, `core/`, one level inside `@adia-ai/web-components` —
+ * the published package ships at the same depth) and installs the first that
+ * matches anything:
+ *
+ *   1. `../node_modules/@phosphor-icons/core/…` — pnpm's nested layout.
+ *      pnpm always populates a package's OWN local `node_modules` with its
+ *      direct dependencies (a symlink into the store), regardless of what the
+ *      consumer app hoists. gh#287's original fix; still first preference.
+ *   2. `../../../@phosphor-icons/core/…` — npm / yarn-classic hoisting in a
+ *      consumer install. `core/` sits at
+ *      `node_modules/@adia-ai/web-components/core/`, so three levels up IS
+ *      the consumer's (or workspace root's) `node_modules`, where hoisting
+ *      flattens transitive deps as siblings. This is the layout gh#786's
+ *      npm-workspace consumer has — candidate 1 is structurally guaranteed
+ *      to match zero files there.
+ *   3. `../../../node_modules/@phosphor-icons/core/…` — THIS repo's own
+ *      checkout when `node_modules` is npm-shaped (gh#340: `npm ci` /
+ *      `npm install` re-shape it). `core/` sits at
+ *      `packages/web-components/core/`, so three levels up is the repo root
+ *      and the hoisted copy lives in its `node_modules/`.
+ *
+ * A `/`-rooted glob is NOT among the candidates: it joins to Vite's
+ * CONFIGURED PROJECT ROOT, which only reaches `@phosphor-icons/core` when
+ * it happens to be hoisted to that exact root — the original gh#287 failure.
+ * Globs that match zero files are free: `import.meta.glob` returns `{}`
+ * without touching the filesystem at runtime, so the losing candidates cost
+ * nothing.
  *
  * ## Vite dep-optimizer pre-bundling (gh#287, second independent failure mode)
  *
@@ -104,19 +116,50 @@
  *     to the manifest fetch below
  */
 
-import { installIconLoaders } from './icons.js';
+import { installIconLoaders, iconRegistryUnwired } from './icons.js';
 
-let weightModules;
+let candidates;
 let hasViteGlob = false;
 try {
-  weightModules = {
-    regular: import.meta.glob('../node_modules/@phosphor-icons/core/assets/regular/*.svg', { query: '?raw', import: 'default' }),
-    thin:    import.meta.glob('../node_modules/@phosphor-icons/core/assets/thin/*.svg',    { query: '?raw', import: 'default' }),
-    light:   import.meta.glob('../node_modules/@phosphor-icons/core/assets/light/*.svg',   { query: '?raw', import: 'default' }),
-    bold:    import.meta.glob('../node_modules/@phosphor-icons/core/assets/bold/*.svg',    { query: '?raw', import: 'default' }),
-    fill:    import.meta.glob('../node_modules/@phosphor-icons/core/assets/fill/*.svg',    { query: '?raw', import: 'default' }),
-    duotone: import.meta.glob('../node_modules/@phosphor-icons/core/assets/duotone/*.svg', { query: '?raw', import: 'default' }),
-  };
+  // Three node_modules layouts, probed in order — see the JSDoc section
+  // "Why there are three candidate globs" above. Every glob string and its
+  // options object must stay a static literal (Vite's macro constraint), so
+  // the 18 calls can't be generated from a loop.
+  candidates = [
+    {
+      layout: 'pnpm-nested `../node_modules/@phosphor-icons/core`',
+      weights: {
+        regular: import.meta.glob('../node_modules/@phosphor-icons/core/assets/regular/*.svg', { query: '?raw', import: 'default' }),
+        thin:    import.meta.glob('../node_modules/@phosphor-icons/core/assets/thin/*.svg',    { query: '?raw', import: 'default' }),
+        light:   import.meta.glob('../node_modules/@phosphor-icons/core/assets/light/*.svg',   { query: '?raw', import: 'default' }),
+        bold:    import.meta.glob('../node_modules/@phosphor-icons/core/assets/bold/*.svg',    { query: '?raw', import: 'default' }),
+        fill:    import.meta.glob('../node_modules/@phosphor-icons/core/assets/fill/*.svg',    { query: '?raw', import: 'default' }),
+        duotone: import.meta.glob('../node_modules/@phosphor-icons/core/assets/duotone/*.svg', { query: '?raw', import: 'default' }),
+      },
+    },
+    {
+      layout: 'npm/yarn-hoisted sibling `../../../@phosphor-icons/core`',
+      weights: {
+        regular: import.meta.glob('../../../@phosphor-icons/core/assets/regular/*.svg', { query: '?raw', import: 'default' }),
+        thin:    import.meta.glob('../../../@phosphor-icons/core/assets/thin/*.svg',    { query: '?raw', import: 'default' }),
+        light:   import.meta.glob('../../../@phosphor-icons/core/assets/light/*.svg',   { query: '?raw', import: 'default' }),
+        bold:    import.meta.glob('../../../@phosphor-icons/core/assets/bold/*.svg',    { query: '?raw', import: 'default' }),
+        fill:    import.meta.glob('../../../@phosphor-icons/core/assets/fill/*.svg',    { query: '?raw', import: 'default' }),
+        duotone: import.meta.glob('../../../@phosphor-icons/core/assets/duotone/*.svg', { query: '?raw', import: 'default' }),
+      },
+    },
+    {
+      layout: 'workspace-root `../../../node_modules/@phosphor-icons/core` (npm-shaped monorepo checkout)',
+      weights: {
+        regular: import.meta.glob('../../../node_modules/@phosphor-icons/core/assets/regular/*.svg', { query: '?raw', import: 'default' }),
+        thin:    import.meta.glob('../../../node_modules/@phosphor-icons/core/assets/thin/*.svg',    { query: '?raw', import: 'default' }),
+        light:   import.meta.glob('../../../node_modules/@phosphor-icons/core/assets/light/*.svg',   { query: '?raw', import: 'default' }),
+        bold:    import.meta.glob('../../../node_modules/@phosphor-icons/core/assets/bold/*.svg',    { query: '?raw', import: 'default' }),
+        fill:    import.meta.glob('../../../node_modules/@phosphor-icons/core/assets/fill/*.svg',    { query: '?raw', import: 'default' }),
+        duotone: import.meta.glob('../../../node_modules/@phosphor-icons/core/assets/duotone/*.svg', { query: '?raw', import: 'default' }),
+      },
+    },
+  ];
   hasViteGlob = true;
 } catch (err) {
   // FB-08: distinguish "no Vite at all" (expected, ReferenceError) from
@@ -135,45 +178,60 @@ try {
 }
 
 if (hasViteGlob) {
-  // FB-08: detect the silent-empty-glob case — `import.meta.glob` returns
-  // `{}` when zero files match (it does NOT throw). The previous behavior
-  // installed empty per-weight maps and the consumer saw an empty icon
-  // registry with no diagnostic. gh#287 names two independent causes, both
-  // producing this same empty-map symptom:
-  //   1. A packaging/bundler step re-nested this file at a different depth
-  //      than it ships at (breaks the `../`-relative glob's one-level-inside
-  //      assumption — see "Why the glob is entry-relative" above), a Yarn
-  //      Berry PnP install (virtual/zip filesystem), or @phosphor-icons/core
-  //      missing entirely.
-  //   2. Vite's dev-server `optimizeDeps` pre-bundled this package (see
-  //      "Vite dep-optimizer pre-bundling" above) — confirmed empirically to
-  //      transform the glob into a literal empty object, no exception.
-  const totalIcons = Object.values(weightModules).reduce(
+  // Install the first candidate layout whose globs matched anything.
+  // `import.meta.glob` returns `{}` when zero files match (it does NOT
+  // throw), so the losing layouts cost nothing.
+  const candidateTotal = (c) => Object.values(c.weights).reduce(
     (sum, weight) => sum + Object.keys(weight).length, 0
   );
-  if (totalIcons === 0) {
-    console.warn(
-      `[icons-phosphor] No Phosphor icons matched the auto-install glob ` +
-      `\`../node_modules/@phosphor-icons/core/assets/<weight>/*.svg\` (resolved ` +
-      `relative to this file's own directory — hoisting-safe under pnpm, gh#287). ` +
-      `Two known causes: (1) this package got pre-bundled by Vite's dev-server ` +
-      `optimizeDeps, which empties the glob — add it to optimizeDeps.exclude in ` +
-      `your Vite config:\n` +
-      `  optimizeDeps: { exclude: ['@adia-ai/web-components', '@adia-ai/web-modules'] }\n` +
-      `(2) @phosphor-icons/core is missing, or this file was re-nested to a ` +
-      `different depth by a packaging step (Yarn PnP, a custom bundler). If ` +
-      `neither fix applies, install loaders manually instead:\n` +
-      `  import { installIconLoaders } from '@adia-ai/web-components/core/icons';\n` +
-      `  import caretRight from '@phosphor-icons/core/assets/regular/caret-right.svg?raw';\n` +
-      `  installIconLoaders({\n` +
-      `    regular: {\n` +
-      `      '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': caretRight,\n` +
-      `    },\n` +
-      `  });\n` +
-      `See the JSDoc header of icons-phosphor.js for the full recipe.`
-    );
+  const matched = candidates.find(c => candidateTotal(c) > 0);
+  if (matched) {
+    installIconLoaders(matched.weights);
+  } else {
+    // Every candidate matched zero files. Two possibilities remain, and
+    // only one is a failure:
+    //   - The consumer registers icons manually (installIconLoaders /
+    //     registerIcon) and never wanted the auto-install path — gh#786's
+    //     reporter. Their registration runs later in the same startup, so
+    //     defer the verdict and stay silent once the registry is wired.
+    //   - The registry genuinely ends up empty: Vite's dev-server
+    //     optimizeDeps pre-bundled this package (esbuild rewrites the globs
+    //     to empty literals, gh#287), @phosphor-icons/core is missing, or
+    //     the install layout is one this file doesn't probe (e.g. Yarn PnP's
+    //     virtual filesystem). Zero icons will render — fail loudly, once,
+    //     naming the fix (gh#340's acceptance).
+    // Deliberately NOT calling installIconLoaders with empty maps here:
+    // that would mark the registry "ready", suppressing <icon-ui>'s own
+    // unwired-registry diagnostic and clobbering nothing-yet for manual
+    // consumers.
+    setTimeout(() => {
+      if (!iconRegistryUnwired()) return; // manual registration landed — working setup, no noise
+      console.error(
+        `[icons-phosphor] Zero-config icon auto-install failed: no Phosphor ` +
+        `SVGs found under any known node_modules layout (probed pnpm-nested ` +
+        `\`../node_modules/\`, npm/yarn-hoisted \`../../../\`, and workspace-root ` +
+        `\`../../../node_modules/\` — all relative to icons-phosphor.js), and no ` +
+        `icons were registered manually. Every <icon-ui> will render blank. ` +
+        `Fixes, most likely first:\n` +
+        `(1) Vite dev-server pre-bundling emptied the globs — exclude this ` +
+        `package from optimizeDeps in vite.config.js:\n` +
+        `  optimizeDeps: { exclude: ['@adia-ai/web-components', '@adia-ai/web-modules'] }\n` +
+        `(2) @phosphor-icons/core is not installed, or your package manager ` +
+        `lays out node_modules somewhere this file doesn't probe (Yarn PnP is ` +
+        `not supported by the zero-config path).\n` +
+        `(3) Register the icons you use manually — this also silences this ` +
+        `error permanently:\n` +
+        `  import { installIconLoaders } from '@adia-ai/web-components/core/icons';\n` +
+        `  import caretRight from '@phosphor-icons/core/assets/regular/caret-right.svg?raw';\n` +
+        `  installIconLoaders({\n` +
+        `    regular: {\n` +
+        `      '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': caretRight,\n` +
+        `    },\n` +
+        `  });\n` +
+        `See the JSDoc header of icons-phosphor.js for the full recipe (gh#786).`
+      );
+    }, 0);
   }
-  installIconLoaders(weightModules);
 } else {
   // Non-Vite static serving: fetch the build-time manifest in the
   // background. No top-level await — module finishes loading immediately;