@adia-ai/a2ui-retrieval 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -9,13 +9,61 @@ _Nothing yet._
 
 ---
 
+## [0.2.2] - 2026-05-02
+
+**Lockstep cut + `detectReferences` brand-only filter.** All 8 published `@adia-ai/*` packages bump 0.2.1 → 0.2.2 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Patch cut — no breaking changes.
+
+### Changed
+
+- `version`: `0.2.1` → `0.2.2`.
+- `dependencies["@adia-ai/a2ui-corpus"]`: `^0.2.0` (covers `0.2.2`).
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.2.0` (covers `0.2.2`).
+- `authoring/web-research.js` is the surface that gained the EXPLICIT/IMPLICIT pattern split; no other retrieval subdirs touched.
+
+### Fixed — `detectReferences` brand-only filter (2026-05-02)
+
+`authoring/web-research.js` regex patterns were capturing generic nouns as brand references. For the intent `"tier pricing page"`, the pattern `\b(\w+)\s+(?:pricing|dashboard|landing|login|settings|profile)\s+page\b` captured `"tier"` and seeded a research query for `"tier pricing UI design components"` — useless, since `"tier"` is a generic noun, not a brand reference.
+
+Fix: split `REFERENCE_PATTERNS` into two tiers by signal strength:
+
+- **`EXPLICIT_PATTERNS`** — the surrounding language declares the captured token IS a brand reference (`"like X"`, `"X-style"`, `"similar to X"`, `"clone X"`). Captures accepted as references.
+- **`IMPLICIT_PATTERNS`** — the surrounding language is a UI-shape verb (`"X pricing page"`). Captures accepted ONLY if in `KNOWN_REFERENCES` (Stripe, Notion, Figma, …); generic nouns dropped.
+
+Verified:
+- `"tier pricing page"` → no refs (was: `["tier"]`)
+- `"fancy pricing page"` → no refs
+- `"Stripe pricing page"` → `["stripe"]` ✓
+- `"Notion-style sidebar"` → `["notion"]` ✓
+- `"like Figma"` → `["figma"]` ✓
+
+Per memory `feedback_panel_label_reliability.md`. Companion fix in `@adia-ai/a2ui-compose` Unreleased (generator.js panel emissions). Both surfaces feed the same reasoning-panel deception class — five distinct bugs caught + fixed in commit `9986c71e`.
+
+---
+
+## [0.2.1] - 2026-05-02
+
+**Lockstep cut.** All 8 published `@adia-ai/*` packages bump 0.2.0 → 0.2.1 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Patch cut — no breaking changes.
+
+### Changed
+
+- `version`: `0.2.0` → `0.2.1`.
+- `dependencies["@adia-ai/a2ui-corpus"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.2.0` (covers `0.2.1`).
+- `embedding/chunk-embedding-retriever.js` + `embedding/embedding-retriever.js` — defensive resolution path: when the `chunk-embeddings.json` / `pattern-embeddings.json` indexes aren't reachable (e.g. inside a `node_modules/@adia-ai/a2ui-corpus/` install layout where the `files:` array now excludes them), the retriever falls back to keyword-only retrieval gracefully instead of throwing on `ENOENT`. Aligns with the `@adia-ai/a2ui-corpus` 0.2.0 tarball-trim decision.
+
+### No source-behavior changes
+
+Public API of `a2ui-retrieval` is byte-identical to `0.2.0`. The above embedding-retriever updates only affect the failure path (`ENOENT` graceful fallback) and don't change the contract for callers passing valid index files. The cut bumps version + tracks dep ranges + softens the embedding-index-missing failure mode.
+
+---
+
 ## [0.2.0] - 2026-05-02
 
 **Lockstep cut + boundary reorganization.** All 8 published
 `@adia-ai/*` packages now share one version, governed by
 [`docs/specs/package-architecture.md` § 15 (Versioning Policy)](../../../docs/specs/package-architecture.md#15-versioning-policy).
 This release also lands the boundary cleanup from T4 of the
-[`docs/plans/packages-architecture-fixes-2026-05-02.md`](../../../docs/plans/packages-architecture-fixes-2026-05-02.md)
+[`docs/plans/packages-architecture-fixes-2026-05-02.md`](../../../.brain/archive/2026-Q2/PLAN-packages-architecture-fixes-2026-05-02.md)
 plan.
 
 ### Changed
@@ -71,8 +119,6 @@ The top-level `index.js` still re-exports the previously-public surface
 
 ---
 
----
-
 ## [0.0.1] - 2026-04-24
 
 First public release. Extracted from

package/authoring/web-research.js

@@ -13,8 +13,25 @@
 
 // ── Reference detection ──────────────────────────────────────────────────
 
-/** Patterns that indicate the user is referencing a specific product/design */
-const REFERENCE_PATTERNS = [
+/**
+ * Patterns split by signal strength:
+ *
+ *   EXPLICIT_PATTERNS — the surrounding language declares the captured
+ *     token IS a brand reference ("like X", "X-style", "similar to X").
+ *     The capture is accepted as a reference even if not in KNOWN_REFERENCES.
+ *
+ *   IMPLICIT_PATTERNS — the surrounding language is a UI-shape verb
+ *     ("X pricing page"); the capture COULD be a brand or COULD be a
+ *     generic noun. Accept ONLY if in KNOWN_REFERENCES, otherwise drop.
+ *
+ * Splitting this way fixes the 2026-05-02 bug where "tier pricing page"
+ * extracted "tier" as a reference and seeded a research query for it. The
+ * regex was working as designed — `\w+ pricing page` captures the prefix
+ * word — but a generic noun like "tier" or "subscription" or "fancy"
+ * isn't a brand reference, so research and downstream prompt enrichment
+ * shouldn't act on it.
+ */
+const EXPLICIT_PATTERNS = [
   /\blike\s+(\w[\w\s]*?)(?:\s*['']s|\s+style|\s+design|\s*$)/i,
   /\b(\w[\w\s]*?)[\s-]style\b/i,
   /\b(\w[\w\s]*?)[\s-]inspired\b/i,
@@ -22,6 +39,9 @@ const REFERENCE_PATTERNS = [
   /\bbased\s+on\s+(\w[\w\s]*?)(?:\s|$|,)/i,
   /\bcopy\s+(\w[\w\s]*?)(?:\s|$|,)/i,
   /\bclone\s+(\w[\w\s]*?)(?:\s|$|,)/i,
+];
+
+const IMPLICIT_PATTERNS = [
   /\b(\w+)\s+(?:pricing|dashboard|landing|login|settings|profile)\s+page\b/i,
 ];
 
@@ -44,12 +64,11 @@ export function detectReferences(intent) {
   const references = [];
   const lower = intent.toLowerCase();
 
-  // Pattern matching
-  for (const pattern of REFERENCE_PATTERNS) {
+  // Explicit-signal patterns — accept the capture as a reference.
+  for (const pattern of EXPLICIT_PATTERNS) {
     const match = intent.match(pattern);
     if (match) {
       let ref = (match[1] || '').trim();
-      // Strip leading articles
       ref = ref.replace(/^(the|a|an)\s+/i, '');
       if (ref && ref.length > 1 && ref.length < 30) {
         references.push(ref);
@@ -57,6 +76,19 @@ export function detectReferences(intent) {
     }
   }
 
+  // Implicit-signal patterns — gate by KNOWN_REFERENCES so generic nouns
+  // ("tier", "fancy", "simple") don't get treated as brands.
+  for (const pattern of IMPLICIT_PATTERNS) {
+    const match = intent.match(pattern);
+    if (match) {
+      let ref = (match[1] || '').trim();
+      ref = ref.replace(/^(the|a|an)\s+/i, '');
+      if (ref && ref.length > 1 && ref.length < 30 && KNOWN_REFERENCES.has(ref.toLowerCase())) {
+        references.push(ref);
+      }
+    }
+  }
+
   // Direct brand name detection (only as whole words)
   for (const brand of KNOWN_REFERENCES) {
     const re = new RegExp(`\\b${brand}\\b`, 'i');
@@ -65,7 +97,9 @@ export function detectReferences(intent) {
     }
   }
 
-  // Filter out non-brand captures (e.g., "inspired" from "X-inspired")
+  // Filter out non-brand captures from the explicit patterns — words like
+  // "inspired" can sneak through when the intent is "X-inspired" with no
+  // X (e.g. "is this AI-inspired?"). Belt and suspenders.
   const NON_BRANDS = new Set(['inspired', 'style', 'based', 'like', 'similar', 'the']);
   for (let i = references.length - 1; i >= 0; i--) {
     if (NON_BRANDS.has(references[i].toLowerCase())) references.splice(i, 1);

package/catalog.js

@@ -89,52 +89,57 @@ const categoryMap = {
 };
 
 // ── Trait registry ──
-const traitRegistry = [
-  { name: 'pressable',      category: 'input-interaction',    description: 'Normalizes click/tap/keyboard into a single "press" event' },
-  { name: 'focusable',      category: 'input-interaction',    description: 'Keyboard-only focus ring, ignores pointer focus' },
-  { name: 'hoverable',      category: 'input-interaction',    description: 'Pointer hover enter/leave state tracking' },
-  { name: 'active-state',   category: 'input-interaction',    description: 'Tracks pointer down / active interaction state' },
-  { name: 'disabled-state', category: 'input-interaction',    description: 'Enforces disabled behavior and interaction blocking' },
-  { name: 'keyboard-nav',     category: 'keyboard-navigation', description: 'Arrow keys, Enter, Escape — semantic navigation events' },
-  { name: 'roving-tabindex',  category: 'keyboard-navigation', description: 'Focus management within composite widgets' },
-  { name: 'typeahead',        category: 'keyboard-navigation', description: 'Incremental search within a collection' },
-  { name: 'hotkey',           category: 'keyboard-navigation', description: 'Global or scoped keyboard shortcuts' },
-  { name: 'focus-trap',       category: 'keyboard-navigation', description: 'Traps Tab/Shift+Tab within a container' },
-  { name: 'form-associated', category: 'forms-data', description: 'ElementInternals integration for form participation' },
-  { name: 'validation',      category: 'forms-data', description: 'Validation rules: required, minlength, pattern, email' },
-  { name: 'value-sync',      category: 'forms-data', description: 'Syncs value between attribute/property/controller' },
-  { name: 'dirty-state',     category: 'forms-data', description: 'Tracks modified vs initial value' },
-  { name: 'resettable',      category: 'forms-data', description: 'Responds to form reset events' },
-  { name: 'resize-observer-trait',       category: 'layout-measurement', description: 'Reacts to element size changes' },
-  { name: 'intersection-observer-trait', category: 'layout-measurement', description: 'Visibility detection (viewport)' },
-  { name: 'anchor-positioning',          category: 'layout-measurement', description: 'Positions relative to an anchor element' },
-  { name: 'portal',                      category: 'layout-measurement', description: 'Renders content in a different DOM root' },
-  { name: 'scroll-lock',                 category: 'layout-measurement', description: 'Disables background scrolling' },
-  { name: 'draggable',    category: 'motion-positioning', description: 'Pointer drag to reposition' },
-  { name: 'tossable',     category: 'motion-positioning', description: 'Flick with momentum + viewport bounce' },
-  { name: 'resizable',    category: 'motion-positioning', description: 'Drag edges/corners to resize' },
-  { name: 'inertia-drag', category: 'motion-positioning', description: 'Momentum-based dragging, smooth deceleration' },
-  { name: 'snap-to-grid', category: 'motion-positioning', description: 'Snaps position to configurable grid' },
-  { name: 'drag-ghost',   category: 'motion-positioning', description: 'Ghost clone at origin during drag' },
-  { name: 'ripple',         category: 'animation-feedback', description: 'Material-style press ripple effect' },
-  { name: 'spring-animate', category: 'animation-feedback', description: 'Spring-based motion transitions' },
-  { name: 'fade-presence',  category: 'animation-feedback', description: 'Enter/exit fade with lifecycle' },
-  { name: 'scale-press',    category: 'animation-feedback', description: 'Subtle scale transform on press' },
-  { name: 'tilt-hover',     category: 'animation-feedback', description: 'Tilt based on pointer position' },
-  { name: 'glow-focus',       category: 'visual-dynamics', description: 'Animated pulsing glow on focus' },
-  { name: 'gradient-shift',   category: 'visual-dynamics', description: 'Animated rainbow gradient backgrounds' },
-  { name: 'parallax',         category: 'visual-dynamics', description: 'Layered motion relative to pointer' },
-  { name: 'shimmer-loading',  category: 'visual-dynamics', description: 'Skeleton shimmer effect' },
-  { name: 'noise-texture',    category: 'visual-dynamics', description: 'Procedural grain overlay' },
-  { name: 'magnetic-hover',  category: 'interaction-delight', description: 'Element subtly follows cursor' },
-  { name: 'confetti',        category: 'interaction-delight', description: 'Radial particle burst on press' },
-  { name: 'confetti-burst',  category: 'interaction-delight', description: 'Upward fountain particle burst' },
-  { name: 'sound-feedback',  category: 'audio-haptics-sensory', description: 'Synthesized tones via Web Audio API' },
-  { name: 'haptic-feedback', category: 'audio-haptics-sensory', description: 'Vibration API feedback' },
-  { name: 'typewriter',      category: 'audio-haptics-sensory', description: 'Animated text reveal character by character' },
-  { name: 'count-up',        category: 'audio-haptics-sensory', description: 'Animated numeric transitions' },
-  { name: 'attention-pulse', category: 'audio-haptics-sensory', description: 'Periodic pulse to draw attention' },
-];
+//
+// Loaded from packages/web-components/traits/_catalog.json — generated
+// by `node scripts/build/traits-catalog.mjs` from the live defineTrait()
+// metadata. Hand-edits here will be overwritten. Treat the trait file
+// itself as the single source of truth.
+let traitRegistry = [];
+
+async function loadTraitRegistry() {
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    try {
+      const { readFile } = await import(/* @vite-ignore */ 'node:fs/promises');
+      const { fileURLToPath } = await import(/* @vite-ignore */ 'node:url');
+      const { dirname, join } = await import(/* @vite-ignore */ 'node:path');
+      const path = join(dirname(fileURLToPath(import.meta.url)), '../../web-components/traits/_catalog.json');
+      const raw = await readFile(path, 'utf8');
+      const data = JSON.parse(raw);
+      traitRegistry = data.traits.map(t => ({
+        name: t.name,
+        category: t.category,
+        description: t.description,
+        attributes: [...t.attributes],
+        events: [...t.events],
+        config: [...t.config],
+      }));
+    } catch (err) {
+      console.warn('[a2ui-corpus] could not load trait catalog:', err.message);
+    }
+  } else {
+    // Browser branch — fetch via HTTP, not `import('… .json', { with: { type: 'json' } })`.
+    // Vite's dev server transforms JSON imports into JS modules and serves them
+    // with `Content-Type: text/javascript`; Chrome's strict MIME check rejects
+    // that when the spec-correct `with: { type: 'json' }` attribute is present.
+    // (Site pages already use fetch() for the same file — see
+    //  site/pages/traits/_api-table.js + site/pages/traits/catalog/index.setup.js.)
+    try {
+      const res = await fetch('/packages/web-components/traits/_catalog.json');
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      traitRegistry = data.traits.map(t => ({
+        name: t.name,
+        category: t.category,
+        description: t.description,
+        attributes: [...t.attributes],
+        events: [...t.events],
+        config: [...t.config],
+      }));
+    } catch { /* trait catalog not present in this build context */ }
+  }
+}
+
+await loadTraitRegistry();
 
 // ── Alias tracking ──
 const aliases = new Set([

package/embedding/chunk-embedding-retriever.js

@@ -32,9 +32,20 @@ async function _loadIndex() {
         const fs = await import(/* @vite-ignore */ 'node:fs/promises');
         const path = await import(/* @vite-ignore */ 'node:path');
         const url = await import(/* @vite-ignore */ 'node:url');
-        // packages/a2ui/retrieval/embedding → up 2 → packages/a2ui → corpus/chunk-embeddings.json
-        const here = path.dirname(url.fileURLToPath(import.meta.url));
-        const p = path.resolve(here, '../../corpus/chunk-embeddings.json');
+        // Try the package-import path first (works under node_modules
+        // install layout — `@adia-ai/a2ui-corpus` exports
+        // `./chunk-embeddings`). Fall back to the relative source-tree
+        // path so a source-checkout monorepo without symlinked deps
+        // still resolves.
+        let p = null;
+        try {
+          const { createRequire } = await import(/* @vite-ignore */ 'node:module');
+          const require = createRequire(import.meta.url);
+          p = require.resolve('@adia-ai/a2ui-corpus/chunk-embeddings');
+        } catch {
+          const here = path.dirname(url.fileURLToPath(import.meta.url));
+          p = path.resolve(here, '../../corpus/chunk-embeddings.json');
+        }
         const raw = await fs.readFile(p, 'utf8');
         _index = JSON.parse(raw);
       } else {

package/embedding/embedding-retriever.js

@@ -32,9 +32,20 @@ async function _loadIndex() {
         const fs = await import(/* @vite-ignore */ 'node:fs/promises');
         const path = await import(/* @vite-ignore */ 'node:path');
         const url = await import(/* @vite-ignore */ 'node:url');
-        // packages/a2ui/retrieval/embedding → up 2 → packages/a2ui → corpus/pattern-embeddings.json
-        const here = path.dirname(url.fileURLToPath(import.meta.url));
-        const p = path.resolve(here, '../../corpus/pattern-embeddings.json');
+        // Try the package-import path first (works under node_modules
+        // install layout — `@adia-ai/a2ui-corpus` exports
+        // `./pattern-embeddings`). Fall back to the relative source-tree
+        // path so a source-checkout monorepo without symlinked deps
+        // still resolves.
+        let p = null;
+        try {
+          const { createRequire } = await import(/* @vite-ignore */ 'node:module');
+          const require = createRequire(import.meta.url);
+          p = require.resolve('@adia-ai/a2ui-corpus/pattern-embeddings');
+        } catch {
+          const here = path.dirname(url.fileURLToPath(import.meta.url));
+          p = path.resolve(here, '../../corpus/pattern-embeddings.json');
+        }
         const raw = await fs.readFile(p, 'utf8');
         _index = JSON.parse(raw);
       } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-retrieval",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "AdiaUI A2UI retrieval layer — catalog lookup, intent classification, domain routing, pattern + anti-pattern matching, clarity + context assembly. Consumed by the compose engine and any A2UI-protocol tooling that needs to reason about user intent against the catalog.",
   "type": "module",
   "main": "./index.js",
@@ -37,5 +37,8 @@
   },
   "dependencies": {
     "@adia-ai/a2ui-utils": "^0.2.0"
+  },
+  "optionalDependencies": {
+    "@adia-ai/a2ui-corpus": "^0.2.0"
   }
 }