@adia-ai/web-components 0.8.30 → 0.8.32

package/components/tabs/tabs.d.ts

@@ -27,12 +27,12 @@ export class UITabs extends UIElement {
   /** Visual variant — `default` (underline strip) or `bordered`. */
   variant: 'default' | 'bordered';
 
+  addEventListener(type: 'change', listener: (ev: TabsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITabs, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'change', listener: (ev: TabsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UITab extends UIElement {

package/components/tag/tag.a2ui.json

@@ -46,7 +46,7 @@
       "$ref": "common_types.json#/$defs/DynamicString"
     },
     "tone": {
-      "description": "Fill style — orthogonal to [variant]. Three values:\n  - `solid` (default for family variants) — saturated bg + on-strong\n    (near-white) text. The chip IS the state.\n  - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s\n    default look. Use on metadata chips in dense lists where the\n    saturated default would compete for attention.\n  - `outline` — transparent bg + family-colored border + family-colored\n    text. The lightest visual weight; good in dense data tables or\n    faceted filter rows where multiple chips would otherwise compete.\nThe `default` variant (no family) stays quiet chrome regardless of\ntone unless `tone=\"solid\"` is set explicitly (high-contrast neutral\ninverse), or `tone=\"outline\"` (fg-muted text + subtle border).\n",
+      "description": "Fill style — orthogonal to [variant]. Three values:\n  - `solid` (default — for EVERY variant, including the family-less\n    `default`, since gh#794) — saturated bg + on-strong (near-white)\n    text. The chip IS the state. A bare `<tag-ui text=\"…\">` renders\n    this look with no attributes at all.\n  - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s\n    default look, and is the pre-gh#794 look for the family-less\n    `default` variant. Use on metadata / citation chips in dense\n    lists or tables where the saturated default would compete for\n    attention (gh#778's oversized-pill concern).\n  - `outline` — transparent bg + family-colored border + family-colored\n    text. The lightest visual weight; good in dense data tables or\n    faceted filter rows where multiple chips would otherwise compete.\n`tone` is a declarative presentational attribute (not a reactive\nprop — see tag.class.js) so its schema `default` here is documentation\nof the rendered-by-default look, not a reflected attribute value.\n",
       "type": "string",
       "enum": [
         "solid",

package/components/tag/tag.css

@@ -6,15 +6,43 @@ tag-ui[removable]:not([disabled]):hover {
 
 @scope (tag-ui) {
   :where(:scope) {
-    /* ── Tokens ── */
-    --tag-bg:           var(--a-bg-muted);
-    --tag-fg:           var(--md-sys-color-neutral-on-surface);
+    /* ── Tokens ──
+       gh#794: the real bare-tag default lives HERE, not in the
+       `:scope[variant="default"]` rule below — `variant` is a reflect:true
+       prop (tag.class.js), and `installProps()`'s reflect() only fires on
+       a property SET, never for a value that equals its declared class
+       default at construction time. A bare `<tag-ui text="…">` therefore
+       never gets a physical `variant="default"` attribute; these
+       `:where(:scope)` zero-specificity tokens are what it actually
+       renders. Solid neutral inverse (was `--a-bg-muted` quiet chrome
+       pre-#794) — same pair the family variants and the redundant
+       `:scope[variant="default"]` rule below carry, for the rare case
+       `variant="default"` IS reflected explicitly (SSR/a2ui-producer
+       markup). Opt out via `[tone="muted"]`. */
+    --tag-bg:           var(--md-sys-color-neutral-on-surface);
+    --tag-fg:           var(--md-sys-color-neutral-background);
     --tag-border:       transparent;
     --tag-radius:       var(--a-radius-full);
     --tag-px:           var(--a-space-1-5);
-    --tag-py:           0.125rem;
+    --tag-py:           var(--a-space-0-5);
     --tag-gap:          var(--a-space-1);
     --tag-font:         var(--a-ui-sm);
+
+    /* ── Size tiers (gh#779) — md (above) is the pixel-identical default;
+       [size="sm"|"lg"] below re-point the active tokens. Component-owned
+       ladder, NOT a direct alias of the universal --a-ui-px/--a-ui-size
+       tokens (styles/api/sizing.css) — tag-ui's own md baseline predates
+       and differs from that system's md (6px/12px here vs 8px/13px
+       there), so aliasing directly would shift every default tag's
+       geometry (gh#778 is exactly this failure mode — an inflated
+       default). Instead sm/lg step off tag's OWN md baseline by the
+       same rung spacing the space/type scales already use. */
+    --tag-px-sm:  var(--a-space-1);
+    --tag-px-lg:  var(--a-space-2);
+    --tag-py-sm:  var(--a-space-px);
+    --tag-py-lg:  var(--a-space-1);
+    --tag-font-sm: var(--a-ui-xs);
+    --tag-font-lg: var(--a-ui-md);
     --tag-font-family:  var(--a-font-family-ui);
     --tag-dismiss-size: 1rem;
     --tag-bg-hover:     var(--a-bg-hover);
@@ -134,12 +162,16 @@ tag-ui[removable]:not([disabled]):hover {
     --tag-fg: var(--md-sys-color-danger-on-danger);
   }
 
-  /* `default` (no family) stays as quiet chrome — a stark fg/bg-inverse
-     would be too loud for the no-variant case. Opt in to the inverse
-     stamp via `[tone="solid"]` when you want a high-contrast neutral pill. */
+  /* `default` (no family) is solid by default (gh#794) — the same
+     high-contrast neutral inverse the family variants already carry.
+     A bare `<tag-ui text="…">` is now a stamped pill, not quiet chrome.
+     Opt OUT to the pre-#794 quiet-chrome look via `[tone="muted"]`
+     (below) on metadata/citation chips in dense lists or tables where
+     the saturated look competes for attention (gh#778's oversized-pill
+     complaint) — same escape hatch the family variants already use. */
   :scope[variant="default"] {
-    --tag-bg: var(--a-bg-muted);
-    --tag-fg: var(--md-sys-color-neutral-on-surface);
+    --tag-bg: var(--md-sys-color-neutral-on-surface);
+    --tag-fg: var(--md-sys-color-neutral-background);
   }
 
   /* ── Tone modifier — orthogonal to [variant] ──
@@ -170,10 +202,26 @@ tag-ui[removable]:not([disabled]):hover {
     --tag-bg: var(--md-sys-color-primary-container);
     --tag-fg: var(--md-sys-color-primary-on-surface);
   }
+  /* gh#794: the pre-#794 quiet-chrome look for the variant-less default —
+     same values the `:where(:scope)` base tokens carried before the
+     solid-default flip. This is the explicit opt-out for bare tags that
+     need the old quiet register (dense-list metadata/citation chips,
+     gh#778's oversized-pill concern) instead of the new stamped-pill
+     default. `:not([variant=…])` (not `[variant="default"]`) because
+     `variant` is a reflect:true prop whose class default ("default")
+     never gets a physical attribute reflected on a bare tag (the
+     `installProps()` reflect() path only fires on a property SET) —
+     the same reason the `[tone="solid"]` fallback below uses this same
+     `:not()` shape instead of `[variant="default"]`. */
+  :scope[tone="muted"]:not([variant="info"]):not([variant="success"]):not([variant="warning"]):not([variant="danger"]):not([variant="accent"]) {
+    --tag-bg: var(--a-bg-muted);
+    --tag-fg: var(--md-sys-color-neutral-on-surface);
+  }
 
-  /* `[tone="solid"]` on the neutral default (or no variant) inverts the
-     chrome — solid fg-color bg with bg-color text. High-contrast neutral
-     stamp. Explicit opt-in; the variant-less default stays quiet chrome.
+  /* `[tone="solid"]` explicit opt-in — redundant with the bare default
+     since gh#794 (the variant-less default is solid unconditionally
+     above) but kept so `tone="solid"` stays a valid, harmless, explicit
+     statement of intent for consumers who set it directly.
      [variant="accent"] is excluded — it already has an explicit solid
      pair above (the plain [variant="accent"] rule) that this higher-
      specificity fallback would otherwise clobber when tone="solid" is
@@ -220,7 +268,24 @@ tag-ui[removable]:not([disabled]):hover {
     --tag-border: var(--md-sys-color-neutral-outline);
   }
 
-  /* Size handled by universal [size] attribute system. */
+  /* ── Size tiers (gh#779) — re-point the active tokens to the matching
+     tier; the token defaults at :where(:scope) above ARE the md tier, so
+     [size="md"] is declared only for explicitness (mirrors kbd.css). */
+  :scope[size="sm"] {
+    --tag-px:  var(--tag-px-sm);
+    --tag-py:  var(--tag-py-sm);
+    --tag-font: var(--tag-font-sm);
+  }
+  :scope[size="md"] {
+    --tag-px:  var(--a-space-1-5);
+    --tag-py:  var(--a-space-0-5);
+    --tag-font: var(--a-ui-sm);
+  }
+  :scope[size="lg"] {
+    --tag-px:  var(--tag-px-lg);
+    --tag-py:  var(--tag-py-lg);
+    --tag-font: var(--tag-font-lg);
+  }
 
   /* hover rule moved outside @scope — see Safari 17.x bug note at top. */
 

package/components/tag/tag.d.ts

@@ -41,26 +41,30 @@ export class UITag extends UIElement {
   /** Tag label. Renderer routes this to the `text` attribute, rendered via CSS attr(text) on ::after. */
   textContent: string;
   /** Fill style — orthogonal to [variant]. Three values:
-  - `solid` (default for family variants) — saturated bg + on-strong
-    (near-white) text. The chip IS the state.
+  - `solid` (default — for EVERY variant, including the family-less
+    `default`, since gh#794) — saturated bg + on-strong (near-white)
+    text. The chip IS the state. A bare `<tag-ui text="…">` renders
+    this look with no attributes at all.
   - `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.
+    default look, and is the pre-gh#794 look for the family-less
+    `default` variant. Use on metadata / citation chips in dense
+    lists or tables where the saturated default would compete for
+    attention (gh#778's oversized-pill concern).
   - `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.
  */
   tone: 'solid' | 'muted' | 'outline';
   /** Semantic variant — `default | accent | info | success | warning | danger`. `accent` is brand-primary 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. */
   variant: 'default' | 'accent' | 'info' | 'success' | 'warning' | 'danger';
 
+  addEventListener(type: 'remove', listener: (ev: TagRemoveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITag, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'remove', listener: (ev: TagRemoveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/tag/tag.examples.md

@@ -6,14 +6,14 @@
 <tag-ui text="Default"></tag-ui>
 ```
 
-## tone
+## size
 
 ```html
-<tag-ui text="Default" tone="solid"></tag-ui>
+<tag-ui text="Small" size="sm"></tag-ui>
 ```
 
-## size
+## removable
 
 ```html
-<tag-ui text="Small" size="sm"></tag-ui>
+<tag-ui text="Removable" removable></tag-ui>
 ```

package/components/tag/tag.yaml

@@ -62,17 +62,21 @@ props:
   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.
+        - `solid` (default — for EVERY variant, including the family-less
+          `default`, since gh#794) — saturated bg + on-strong (near-white)
+          text. The chip IS the state. A bare `<tag-ui text="…">` renders
+          this look with no attributes at all.
         - `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.
+          default look, and is the pre-gh#794 look for the family-less
+          `default` variant. Use on metadata / citation chips in dense
+          lists or tables where the saturated default would compete for
+          attention (gh#778's oversized-pill concern).
         - `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
     enum:
@@ -127,6 +131,13 @@ 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>.
+    - >-
+      Bare <tag-ui text="…"> (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).
 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/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;