@adia-ai/web-components 0.6.14 → 0.6.16

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.16] — 2026-05-21
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the 9-package version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.6.16 work shipped in `@adia-ai/web-modules`: (1) `<admin-page>` selector relaxed to descendant combinator so router-wrapped layouts no longer collapse to `display: inline` at narrow viewports (was the root of the page-header/KPI overlap regression); (2) `--page-content-header-bg` rebased from `--a-canvas-2` to `--a-canvas-1` so the page-header reads as shell-chrome continuation. See `packages/web-modules/CHANGELOG.md#0616--2026-05-21` for details.
+
+## [0.6.15] — 2026-05-21
+
+### Fixed
+- **`installIconLoaders` / `installIconLoadersForRegistered` no longer silently accept a malformed shape (FB-07).** The previous behavior was `weightModules = { ...EMPTY_WEIGHTS, ...modules }` which spread any top-level keys verbatim. A flat path→svg glob (the documented quick-start shape; see FB-09) had its `/path/foo.svg` keys spread at the top level of `weightModules`, leaving every per-weight slot empty. Every `<icon-ui>` then rendered the icon NAME as visible text in its slot — confusing to debug because the per-icon `warnMissingIcon` console message points at name-resolution issues (Phosphor alias, `registerIcon`, etc.), not at loader-shape issues. The fix shape-detects three cases: (1) per-weight map keyed by `regular`/`thin`/`light`/`bold`/`fill`/`duotone` installs verbatim; (2) flat path→svg map auto-promotes to `{ regular: <flat> }` with a one-time `console.warn` so the caller knows to wrap explicitly (and so bold/fill/etc. aren't silently lost); (3) anything else logs `console.error` with the received key sample and aborts the install (registry stays unchanged). Net: the documented flat shape from `docs/guides/02-quick-start.md` continues to work but emits one diagnostic warn per install; consumers on prior versions writing the flat shape needed to wrap manually to get icons at all. Files: `packages/web-components/core/icons.js` (+59 LOC: `WEIGHT_KEYS` const, `isFlatGlobShape()`, `warnedShapes` WeakSet, three-branch dispatch inside `installIconLoaders`).
+- **`core/icons-phosphor.js` no longer silently swallows `import.meta.glob` failures (FB-08).** Two silent-fail paths fixed. (a) **Empty-glob path** — `import.meta.glob('/node_modules/@phosphor-icons/core/assets/<weight>/*.svg', …)` returns `{}` (not an error) when zero files match. This happens when the consumer's Vite root sits below `node_modules`, or with pnpm/yarn-berry virtual paths, or when this module is loaded from a published package directory (the absolute-style glob is resolved against the Vite root, not this file's directory). Previously `hasViteGlob` was set true and `installIconLoaders({ regular: {}, … })` ran anyway, leaving the registry empty with no diagnostic. The fix sums per-weight entry counts after the `try` block; if all six weights have zero entries, emits a `console.warn` with the canonical manual-install snippet. (b) **Caught-error path** — the bare `catch {}` was scoped to handle "no Vite at all" (`ReferenceError` because `import.meta.glob` doesn't exist in static serving), but it also swallowed every OTHER error type (plugin order issues, Vite-config misconfigs, etc.). The catch now logs non-`ReferenceError` failures via `console.warn` before falling back to the manifest fetch. Files: `packages/web-components/core/icons-phosphor.js` (+38 LOC, -2 LOC).
+
+### Docs
+- **Quick-start + migration guide examples corrected (FB-09).** `docs/guides/02-quick-start.md` lines ~76-81 (boot sequence) and ~126-131 (the dedicated `installIconLoadersForRegistered` section) both showed the flat-glob form passed directly to `installIconLoadersForRegistered`. Both now wrap the glob in `{ regular: … }` to match the canonical contract. New `### Pitfall: flat glob silently auto-promoted (v0.6.15+)` section explains the FB-07 auto-promote behavior and when the per-weight form is strictly required (bold/fill/etc.). `docs/MIGRATION GUIDE.md` lines ~279-282 (the v0.5.3 §154 recommended upgrade example) had the same flat-glob bug — corrected. The skill `adia-ui-kit` v2.9.0 ships the same scaffold-template correction.
+
+### Verification
+- `verify:traits` 56/56 clean.
+- `components.mjs --verify` clean (142 files up-to-date).
+- `smoke:engines` green; `smoke:register-engine` 11/11.
+- `npm run check` omnibus PASSES (LightningCSS minify, link check, primitive composes coverage, demo shell imports, phosphor wiring, MCP server smoke 3/3, register-engine 11/11, traits 56/56).
+- `eval:diff --engine zettel` cov=49% / avg=90 (baseline-identical).
+- Browser-verified four cases against `installIconLoaders`: flat glob → 1 warn + install; garbage shape → 1 error + abort; null → 1 error + abort; per-weight map → silent. Live `/site/examples/admin-dashboard` shows 406/412 icon-ui elements with rendered SVGs — same baseline as pre-fix; substrate change non-regressing.
+
 ## [0.6.14] — 2026-05-21
 
 ### Maintenance

package/core/icons-phosphor.js

@@ -65,11 +65,50 @@ try {
     duotone: import.meta.glob('/node_modules/@phosphor-icons/core/assets/duotone/*.svg', { query: '?raw', import: 'default' }),
   };
   hasViteGlob = true;
-} catch {
-  /* non-Vite static serving — manifest fetch below handles it */
+} catch (err) {
+  // FB-08: distinguish "no Vite at all" (expected, ReferenceError) from
+  // every other error (unexpected, worth logging). ReferenceError is the
+  // signal that `import.meta.glob` doesn't exist — i.e. non-Vite static
+  // serving, which is what the manifest-fetch fallback below was designed
+  // for. Anything else got swallowed silently by the previous bare catch.
+  if (err && !(err instanceof ReferenceError)) {
+    console.warn(
+      `[icons-phosphor] import.meta.glob threw an unexpected error ` +
+      `(not a vanilla ReferenceError): ${err.message}. ` +
+      `Falling back to manifest fetch. If you're using Vite, this likely ` +
+      `means a misconfigured plugin order or glob root.`
+    );
+  }
 }
 
 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. This happens when the consumer's Vite
+  // root sits below `node_modules`, or with pnpm/yarn-berry virtual paths,
+  // or when this file runs from inside a published package directory
+  // (its absolute-style glob is resolved relative to the Vite root, not
+  // this file's directory).
+  const totalIcons = Object.values(weightModules).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\`. ` +
+      `This usually means your Vite root sits below node_modules, you use ` +
+      `pnpm/yarn-berry virtual paths, or this module is loaded from a ` +
+      `published package directory. Install loaders manually from your app entry:\n` +
+      `  import { installIconLoaders } from '@adia-ai/web-components/core/icons';\n` +
+      `  installIconLoaders({\n` +
+      `    regular: import.meta.glob(\n` +
+      `      '../node_modules/@phosphor-icons/core/assets/regular/*.svg',\n` +
+      `      { query: '?raw', import: 'default', eager: true }\n` +
+      `    ),\n` +
+      `  });`
+    );
+  }
   installIconLoaders(weightModules);
 } else {
   // Non-Vite static serving: fetch the build-time manifest in the

package/core/icons.js

@@ -103,8 +103,27 @@ export function listIcons() {
 // `installIconLoaders` (called by `icons-phosphor.js` in the zero-config path).
 
 const EMPTY_WEIGHTS = { regular: {}, thin: {}, light: {}, bold: {}, fill: {}, duotone: {} };
+const WEIGHT_KEYS = new Set(['regular', 'thin', 'light', 'bold', 'fill', 'duotone']);
 let weightModules = EMPTY_WEIGHTS;
 
+/* Shape-detect a flat `import.meta.glob` result: zero recognized weight
+   keys (`regular`/`thin`/`light`/`bold`/`fill`/`duotone`) AND at least one
+   key that looks like an SVG path (`.svg` suffix). Used to auto-promote
+   the documented flat-glob form (FB-09) to `{ regular: <flat> }` so the
+   substrate stops silently failing on the most common malformed shape
+   (FB-07). */
+function isFlatGlobShape(modules) {
+  const keys = Object.keys(modules);
+  if (keys.length === 0) return false;
+  for (const k of keys) if (WEIGHT_KEYS.has(k)) return false;
+  for (const k of keys) if (k.endsWith('.svg')) return true;
+  return false;
+}
+
+/* Warn-once cache so the FB-07 auto-promote message doesn't spam in HMR
+   environments where `installIconLoaders` re-runs on every hot reload. */
+const warnedShapes = new WeakSet();
+
 /* `whenIconRegistryReady` lets a component defer icon-name decisions until
    the registry is sync-checkable. <icon-ui> doesn't need it — it owns the
    <name → svg> render and re-stamps elements when the loader map arrives.
@@ -128,7 +147,51 @@ export const whenIconRegistryReady = new Promise((r) => { resolveRegistryReady =
  * before loaders arrived. Idempotent — calling it twice replaces the map.
  */
 export function installIconLoaders(modules) {
-  weightModules = { ...EMPTY_WEIGHTS, ...modules };
+  // FB-07: validate shape before installing. The previous behavior was
+  // `weightModules = { ...EMPTY_WEIGHTS, ...modules }` which silently
+  // accepted any object — including the documented-but-broken flat
+  // path→svg glob (FB-09), which spread path keys at the top level
+  // and left every weight slot empty. Three shapes are now recognized:
+  //
+  //   1. Per-weight map { regular: { path: svg }, bold: { ... }, ... }
+  //      — canonical, installs verbatim.
+  //   2. Flat glob { '/path/foo.svg': '<svg>', ... } — auto-promoted to
+  //      { regular: <flat> } with a one-time warn so the caller knows
+  //      to wrap explicitly (and so bold/fill/etc. aren't silently lost).
+  //   3. Anything else — logged via console.error, install aborted.
+  if (!modules || typeof modules !== 'object') {
+    console.error(
+      `[icons] installIconLoaders: expected per-weight map { regular: { ... }, bold: { ... }, ... }, ` +
+      `got ${modules === null ? 'null' : typeof modules}. Install aborted; registry unchanged.`
+    );
+    return;
+  }
+  let installable = modules;
+  if (isFlatGlobShape(modules)) {
+    if (!warnedShapes.has(modules)) {
+      warnedShapes.add(modules);
+      console.warn(
+        `[icons] installIconLoaders received a flat path→svg map. ` +
+        `Auto-promoting to { regular: <flat> }. Wrap explicitly to silence ` +
+        `this warning and to load bold/fill/etc. weights:\n` +
+        `  installIconLoaders({ regular: import.meta.glob('.../regular/*.svg', { ... }) });`
+      );
+    }
+    installable = { regular: modules };
+  } else {
+    const hasAnyWeight = Object.keys(modules).some(k => WEIGHT_KEYS.has(k));
+    if (!hasAnyWeight) {
+      const sampleKeys = Object.keys(modules).slice(0, 5).join(', ');
+      console.error(
+        `[icons] installIconLoaders: shape unrecognized. ` +
+        `Expected per-weight map keyed by regular/thin/light/bold/fill/duotone, ` +
+        `or a flat path→svg map. Received keys: ${sampleKeys || '(empty)'}. ` +
+        `Install aborted; registry unchanged.`
+      );
+      return;
+    }
+  }
+  weightModules = { ...EMPTY_WEIGHTS, ...installable };
   registryReady = true;
   if (typeof document !== 'undefined') {
     for (const el of document.querySelectorAll('icon-ui[name]')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",