@tmorrow/cre8-wc 2.3.5 → 2.3.9

package/a2ui/catalog-kg.json

@@ -10,7 +10,7 @@
     ],
     "catalog_id": "cre8-wc",
     "library": "@tmorrow/cre8-wc",
-    "library_version": "2.3.5",
+    "library_version": "2.3.9",
     "graphify_commit": "735ed2c2ff3caf037f8faf1b71e1ccdb85d80cae",
     "evidence": {
       "story_files": 72,

package/a2ui/catalog.compact.json

@@ -1,7 +1,7 @@
 {
   "contractVersion": 1,
-  "sourceCatalog": "https://cre8.dev/a2ui/catalogs/cre8-wc/2.3.5",
-  "libraryVersion": "2.3.5",
+  "sourceCatalog": "https://cre8.dev/a2ui/catalogs/cre8-wc/2.3.9",
+  "libraryVersion": "2.3.9",
   "componentCount": 88,
   "components": [
     {

package/a2ui/catalog.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cre8.dev/a2ui/catalogs/cre8-wc/2.3.5",
+  "$id": "https://cre8.dev/a2ui/catalogs/cre8-wc/2.3.9",
   "title": "cre8-wc A2UI Catalog",
   "description": "cre8 Web Components is a library of presentational UI web components to be consumed by # web applications.",
   "x-native-events": [
@@ -54,7 +54,7 @@
   "x-a2ui": {
     "catalogId": "cre8-wc",
     "library": "@tmorrow/cre8-wc",
-    "libraryVersion": "2.3.5",
+    "libraryVersion": "2.3.9",
     "tagPrefix": "cre8",
     "framework": "Lit 3.3.1"
   },

package/a2ui/check-layer-parity.mjs

@@ -23,6 +23,8 @@ import { readFileSync, existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { buildEmbeddingText, textHash } from './embedding-text.mjs';
+import { MODEL as EMBEDDING_MODEL, DIMENSIONS as EMBEDDING_DIMENSIONS } from './generate-embeddings.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const WC = join(HERE, '..');
@@ -266,6 +268,55 @@ check('the catalog matches the manifest it was generated from', () => {
   return `all at ${manifest.version}`;
 });
 
+check('semantic search vectors match current component text', () => {
+  const embeddingsPath = join(WC, 'a2ui', 'catalog-embeddings.json');
+  if (!existsSync(embeddingsPath)) {
+    return 'no catalog-embeddings.json yet — search_components falls back to lexical matching; ' +
+      'run `OPENAI_API_KEY=... node a2ui/generate-embeddings.mjs` to enable semantic search';
+  }
+
+  const kgPath = join(WC, 'a2ui', 'catalog-kg.json');
+  const kg = read(kgPath);
+  const embeddings = read(embeddingsPath);
+  const components = kg.nodes.filter((n) => n.type === 'component');
+
+  if (embeddings.meta?.library_version !== manifest.version) {
+    throw new Error(
+      `catalog-embeddings.json was built from version ${embeddings.meta?.library_version}, ` +
+        `manifest is ${manifest.version} — regenerate with generate-embeddings.mjs`
+    );
+  }
+
+  const missing = [];
+  const stale = [];
+  for (const c of components) {
+    const vector = embeddings.vectors?.[c.id];
+    if (!vector) {
+      missing.push(c.id);
+      continue;
+    }
+    const expectedHash = textHash(buildEmbeddingText(kg, c));
+    if (vector.text_hash !== expectedHash) stale.push(c.id);
+    else if (vector.model !== EMBEDDING_MODEL || vector.dims !== EMBEDDING_DIMENSIONS) stale.push(c.id);
+  }
+
+  const orphaned = Object.keys(embeddings.vectors ?? {}).filter(
+    (id) => !components.some((c) => c.id === id)
+  );
+
+  if (missing.length || stale.length || orphaned.length) {
+    const parts = [];
+    if (missing.length) parts.push(`missing vector(s): ${missing.join(', ')}`);
+    if (stale.length) parts.push(`stale vector(s) (component text changed): ${stale.join(', ')}`);
+    if (orphaned.length) parts.push(`orphaned vector(s) (component no longer in catalog): ${orphaned.join(', ')}`);
+    throw new Error(
+      `catalog-embeddings.json is out of sync with catalog-kg.json\n      ${parts.join('\n      ')}\n` +
+        '      Regenerate with: OPENAI_API_KEY=... node a2ui/generate-embeddings.mjs'
+    );
+  }
+  return `${components.length} vectors, all current`;
+});
+
 // ── Report ───────────────────────────────────────────────────────────
 
 for (const note of notes) console.log(note);

package/a2ui/check-skill-fidelity.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * Audits agent skills against the shipped catalog.
+ *
+ *   node a2ui/check-skill-fidelity.mjs [--json] [path ...]
+ *
+ * Skills are documentation that agents act on directly, so a skill that names
+ * a component the library no longer ships doesn't degrade gracefully - the
+ * agent writes it, and it renders nothing. Nothing regenerates skills at
+ * release, and nothing checked them, so drift accumulated invisibly across
+ * releases: by 2.3.6 the cre8-a2ui skill documented 83 components of which 38
+ * (46%) did not exist, plus 27 undeclared props and 16 out-of-range enum
+ * values, every one of them written out with a confident-looking example.
+ *
+ * A three-arm eval measured agents carrying that skill as *worse* than agents
+ * given no CRE8 knowledge at all (component_validity 0.865 against 0.922),
+ * because it taught them to reach for cre8-toast, cre8-toggle, cre8-avatar and
+ * 35 others that had been removed or never shipped.
+ *
+ * This does not fix skills; it makes the drift visible on every release, and
+ * exits non-zero when a skill claims something the catalog contradicts.
+ *
+ * Both syntaxes are read, since skills exist for the web components and for
+ * the React wrappers:
+ *
+ *   <cre8-button variant="primary">      web component, kebab tag
+ *   <Cre8Button variant="primary">       React wrapper, PascalCase
+ *
+ * Only claims that can be checked are checked. Prose is left alone; a skill
+ * that carries judgment rather than API tables is expected to report zero of
+ * everything here, and that is the intended end state - the catalog is the
+ * catalog's job, and restating it anywhere else guarantees exactly this drift.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const CATALOG = path.join(HERE, 'catalog.compact.json');
+
+// Attributes that belong to HTML/JSX rather than to a component's own API.
+const NOT_PROPS = new Set([
+  'slot', 'class', 'className', 'id', 'style', 'key', 'ref', 'children',
+  'hidden', 'title', 'role', 'tabindex', 'tabIndex', 'draggable', 'dir', 'lang',
+]);
+
+const pascalToKebab = (name) =>
+  'cre8-' + name.slice(4).replace(/(?<!^)(?=[A-Z])/g, '-').toLowerCase();
+
+function collectMarkdown(target) {
+  const stat = fs.statSync(target);
+  if (stat.isFile()) return [target];
+  const out = [];
+  for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+    const full = path.join(target, entry.name);
+    if (entry.isDirectory()) out.push(...collectMarkdown(full));
+    else if (entry.name.endsWith('.md')) out.push(full);
+  }
+  return out.sort();
+}
+
+function auditSkill(target, catalog) {
+  const components = new Map(catalog.components.map((c) => [c.name, c]));
+  const files = collectMarkdown(target);
+  const text = files.map((f) => fs.readFileSync(f, 'utf8')).join('\n');
+
+  const unknownComponents = new Set();
+  const knownUsed = new Set();
+  const undeclaredProps = new Map();   // "component.prop" -> count
+  const invalidEnums = new Map();      // "component.prop=value" -> {allowed, count}
+
+  // One pass over every opening tag in either syntax, capturing its attributes.
+  const tag = /<(cre8-[a-z0-9-]+|Cre8[A-Za-z0-9]*)((?:\s+[a-zA-Z][\w-]*(?:=(?:"[^"]*"|'[^']*'|\{[^}]*\}))?)*)\s*\/?>/g;
+  for (const match of text.matchAll(tag)) {
+    const raw = match[1];
+    const name = raw.startsWith('Cre8') ? pascalToKebab(raw) : raw;
+    const component = components.get(name);
+    if (!component) {
+      unknownComponents.add(name);
+      continue;
+    }
+    knownUsed.add(name);
+
+    const declared = component.props || {};
+    // Match declared props case-insensitively: the same prop is `fullHeight`
+    // in JSX and `fullheight` once the browser lowercases the attribute.
+    const byLower = new Map(Object.keys(declared).map((p) => [p.toLowerCase(), p]));
+
+    const attr = /\s([a-zA-Z][\w-]*)(?:="([^"]*)")?/g;
+    for (const a of match[2].matchAll(attr)) {
+      const [, prop, value] = a;
+      if (NOT_PROPS.has(prop) || prop.startsWith('data-') || prop.startsWith('aria-') || prop.startsWith('on')) continue;
+      const real = byLower.get(prop.toLowerCase());
+      if (!real) {
+        const key = `${name}.${prop}`;
+        undeclaredProps.set(key, (undeclaredProps.get(key) || 0) + 1);
+        continue;
+      }
+      const allowed = (declared[real] || {}).enum;
+      if (allowed && value !== undefined && !allowed.includes(value)) {
+        const key = `${name}.${real}="${value}"`;
+        const prev = invalidEnums.get(key);
+        invalidEnums.set(key, { allowed, count: (prev?.count || 0) + 1 });
+      }
+    }
+  }
+
+  const taught = unknownComponents.size + knownUsed.size;
+  return {
+    skill: path.basename(target),
+    path: target,
+    files: files.length,
+    componentsTaught: taught,
+    unknownComponents: [...unknownComponents].sort(),
+    undeclaredProps: [...undeclaredProps.entries()].sort(),
+    invalidEnums: [...invalidEnums.entries()].sort(),
+    neverMentioned: catalog.components.map((c) => c.name).filter((n) => !knownUsed.has(n)).length,
+  };
+}
+
+function report(result, catalog) {
+  const { unknownComponents: unknown, undeclaredProps: props, invalidEnums: enums } = result;
+  const defects = unknown.length + props.length + enums.length;
+  const pct = result.componentsTaught
+    ? Math.round((unknown.length / result.componentsTaught) * 100)
+    : 0;
+
+  console.log(`\n${result.skill}  (${result.files} file${result.files === 1 ? '' : 's'})`);
+  if (!result.componentsTaught) {
+    console.log('  no component API claims - nothing to contradict');
+    return 0;
+  }
+  console.log(`  components named: ${result.componentsTaught}   not in catalog: ${unknown.length} (${pct}%)`);
+  if (unknown.length) console.log(`    ${unknown.join(', ')}`);
+  if (props.length) {
+    console.log(`  props no component declares: ${props.length}`);
+    for (const [key, count] of props) console.log(`    ${key}${count > 1 ? `  (×${count})` : ''}`);
+  }
+  if (enums.length) {
+    console.log(`  values outside the declared enum: ${enums.length}`);
+    for (const [key, { allowed }] of enums) console.log(`    ${key}  allowed: ${allowed.join(', ')}`);
+  }
+  console.log(`  catalog components it never mentions: ${result.neverMentioned} of ${catalog.components.length}`);
+  return defects;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const asJson = args.includes('--json');
+  const targets = args.filter((a) => !a.startsWith('--'));
+
+  if (!fs.existsSync(CATALOG)) {
+    console.error(`catalog not found at ${CATALOG} - run \`pnpm run build:a2ui\` first`);
+    return 1;
+  }
+  const catalog = JSON.parse(fs.readFileSync(CATALOG, 'utf8'));
+
+  // Default to wherever skills actually live on this machine. Account-synced
+  // skills are included deliberately: they are the ones that drifted, and the
+  // ones no build step here can regenerate.
+  const candidates = targets.length ? targets : [
+    path.join(HERE, '..', '..', '..', '.claude', 'skills'),
+    path.join(process.env.HOME || '', '.claude', 'skills', 'synced'),
+  ];
+
+  const skillDirs = [];
+  for (const c of candidates) {
+    if (!fs.existsSync(c)) continue;
+    if (fs.existsSync(path.join(c, 'SKILL.md'))) { skillDirs.push(c); continue; }
+    for (const entry of fs.readdirSync(c, { withFileTypes: true })) {
+      if (entry.isDirectory() && fs.existsSync(path.join(c, entry.name, 'SKILL.md'))) {
+        skillDirs.push(path.join(c, entry.name));
+      }
+    }
+  }
+  if (!skillDirs.length) {
+    console.log('no skills found to audit');
+    return 0;
+  }
+
+  const results = skillDirs.map((d) => auditSkill(d, catalog));
+  // Only skills that make catalog claims are interesting either way.
+  const claiming = results.filter((r) => r.componentsTaught > 0);
+
+  if (asJson) {
+    console.log(JSON.stringify({ libraryVersion: catalog.libraryVersion, results: claiming }, null, 2));
+  } else {
+    console.log(`skill fidelity vs @tmorrow/cre8-wc ${catalog.libraryVersion} (${catalog.components.length} components)`);
+    if (!claiming.length) console.log('\nno skill makes checkable component API claims');
+    for (const r of claiming) report(r, catalog);
+  }
+
+  const total = claiming.reduce(
+    (sum, r) => sum + r.unknownComponents.length + r.undeclaredProps.length + r.invalidEnums.length,
+    0,
+  );
+  if (total && !asJson) {
+    console.log(`\n${total} claim${total === 1 ? '' : 's'} the catalog contradicts.`);
+    console.log('Skills are acted on verbatim: an agent writes what they say, and a component that');
+    console.log('does not exist fails silently at runtime. Either correct the claims, or move the');
+    console.log('API surface out of the skill and let the MCP answer it.');
+  }
+  return total ? 1 : 0;
+}
+
+process.exit(main());

package/a2ui/embedding-text.mjs

@@ -0,0 +1,58 @@
+/**
+ * Builds the text embedded for semantic component search (search_components).
+ *
+ * Component descriptions in the catalog are thin (mean ~70 chars) — not enough
+ * on their own to separate "shows a running count" from "confirms a
+ * destructive action" in embedding space. This fattens each component's text
+ * with its category, prop names/enums/descriptions, and slot descriptions
+ * pulled from the knowledge graph, so retrieval has real signal to match on.
+ *
+ * Shared by generate-embeddings.mjs (which calls the embedding API) and
+ * check-layer-parity.mjs (which re-derives this text with NO network call, to
+ * detect when committed vectors have gone stale against catalog-kg.json).
+ * Both must build byte-identical text for the same component, or the parity
+ * check's hash comparison is meaningless — that's why this lives in one file.
+ */
+import { createHash } from 'node:crypto';
+
+const clip = (text, max) => {
+  if (!text) return '';
+  const flat = String(text).replace(/\s+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+
+/**
+ * @param {{nodes: Array<Record<string, unknown>>}} kg - parsed catalog-kg.json
+ * @param {Record<string, unknown>} component - a KG node with type 'component'
+ * @returns {string}
+ */
+export function buildEmbeddingText(kg, component) {
+  const slotNodeById = new Map(
+    kg.nodes.filter((n) => n.type === 'slot').map((n) => [n.id, n])
+  );
+
+  const propLines = Object.entries(component.props ?? {}).map(([name, spec]) => {
+    const enumPart = spec?.enum ? ` (${spec.enum.join('/')})` : '';
+    const descPart = spec?.description ? ` — ${clip(spec.description, 90)}` : '';
+    return `${name}${enumPart}${descPart}`;
+  });
+
+  const slotLines = (component.slots ?? []).map((name) => {
+    const node = slotNodeById.get(`slot:${component.id}:${name}`);
+    const descPart = node?.description ? ` — ${clip(node.description, 90)}` : '';
+    return `${name}${descPart}`;
+  });
+
+  const parts = [
+    `${component.id} (${component.category ?? 'Uncategorized'})`,
+    clip(component.description, 300),
+  ];
+  if (propLines.length) parts.push(`Props: ${propLines.join('; ')}`);
+  if (slotLines.length) parts.push(`Slots: ${slotLines.join('; ')}`);
+
+  return parts.filter(Boolean).join('. ');
+}
+
+export function textHash(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}

package/a2ui/generate-embeddings.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Generates catalog-embeddings.json — the vectors search_components ranks
+ * against for semantic (query-time) search in cre8-mcp.
+ *
+ * Unlike the other a2ui/generate-*.mjs scripts, this one is NOT free or
+ * deterministic-by-recompute: it calls OpenAI's embeddings API and spends
+ * real (if tiny) money per changed component. It is therefore deliberately
+ * NOT wired into `build:a2ui` or CI — run it by hand, with OPENAI_API_KEY
+ * set, whenever catalog-kg.json's component text changes:
+ *
+ *   OPENAI_API_KEY=sk-... node a2ui/generate-embeddings.mjs
+ *
+ * Incremental: a component whose embedding text is unchanged since the last
+ * run (by hash) is reused rather than re-embedded, so editing one
+ * description costs one API call, not eighty-eight.
+ *
+ * check-layer-parity.mjs re-derives the same text hashes with no network
+ * call and fails the build if a committed vector has gone stale against
+ * catalog-kg.json — but only once this file exists at all. Until the first
+ * run, search_components just falls back to lexical matching; there is
+ * nothing to go stale.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { buildEmbeddingText, textHash } from './embedding-text.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const kgPath = resolve(__dirname, 'catalog-kg.json');
+const outPath = resolve(__dirname, 'catalog-embeddings.json');
+const pkgPath = resolve(__dirname, '..', 'package.json');
+
+export const MODEL = 'text-embedding-3-small';
+// Matryoshka-truncated from the model's native 1536 dims: keeps the committed
+// artifact ~180KB for 88 components instead of ~540KB, at a small recall cost
+// that doesn't matter for an 88-item catalog. OpenAI supports this via the
+// `dimensions` request param on text-embedding-3-* models.
+export const DIMENSIONS = 512;
+const BATCH_SIZE = 50;
+
+async function main() {
+  if (!existsSync(kgPath)) {
+    console.error('catalog-kg.json is missing — run `pnpm build:a2ui:kg` first.');
+    process.exit(1);
+  }
+
+  const kg = JSON.parse(readFileSync(kgPath, 'utf8'));
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  const components = kg.nodes.filter((n) => n.type === 'component');
+
+  if (!components.length) {
+    console.error('catalog-kg.json has no component nodes — run `pnpm build:a2ui:kg` first.');
+    process.exit(1);
+  }
+
+  const existing = existsSync(outPath) ? JSON.parse(readFileSync(outPath, 'utf8')) : { vectors: {} };
+
+  const wanted = components.map((c) => {
+    const text = buildEmbeddingText(kg, c);
+    return { id: c.id, text, hash: textHash(text) };
+  });
+
+  const reused = [];
+  const toEmbed = [];
+  for (const w of wanted) {
+    const prior = existing.vectors[w.id];
+    if (prior && prior.text_hash === w.hash && prior.model === MODEL && prior.dims === DIMENSIONS) {
+      reused.push(w.id);
+    } else {
+      toEmbed.push(w);
+    }
+  }
+
+  console.log(`${wanted.length} components: ${reused.length} unchanged (reused), ${toEmbed.length} to embed`);
+
+  const vectors = { ...existing.vectors };
+  const wantedIds = new Set(wanted.map((w) => w.id));
+  for (const id of Object.keys(vectors)) {
+    if (!wantedIds.has(id)) {
+      delete vectors[id]; // component removed from the catalog since the last run
+      console.log(`  dropped stale vector for removed component: ${id}`);
+    }
+  }
+
+  if (toEmbed.length) {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      console.error(
+        `OPENAI_API_KEY is not set. Cannot embed ${toEmbed.length} component(s).\n` +
+          'Set it and re-run: OPENAI_API_KEY=sk-... node a2ui/generate-embeddings.mjs'
+      );
+      process.exit(1);
+    }
+
+    for (let i = 0; i < toEmbed.length; i += BATCH_SIZE) {
+      const batch = toEmbed.slice(i, i + BATCH_SIZE);
+      console.log(`  embedding ${i + 1}-${i + batch.length} of ${toEmbed.length}...`);
+      const res = await fetch('https://api.openai.com/v1/embeddings', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model: MODEL,
+          dimensions: DIMENSIONS,
+          input: batch.map((b) => b.text),
+        }),
+      });
+      if (!res.ok) {
+        const body = await res.text();
+        console.error(`OpenAI embeddings request failed: ${res.status} ${res.statusText}\n${body}`);
+        process.exit(1);
+      }
+      const json = await res.json();
+      json.data.forEach((row, idx) => {
+        const w = batch[idx];
+        vectors[w.id] = {
+          text_hash: w.hash,
+          model: MODEL,
+          dims: DIMENSIONS,
+          vector: row.embedding,
+        };
+      });
+    }
+  }
+
+  const sortedVectors = Object.fromEntries(Object.keys(vectors).sort().map((id) => [id, vectors[id]]));
+
+  writeFileSync(
+    outPath,
+    JSON.stringify(
+      {
+        meta: {
+          generated_from: ['catalog-kg.json'],
+          library: pkg.name,
+          library_version: pkg.version,
+          model: MODEL,
+          dims: DIMENSIONS,
+          component_count: wanted.length,
+        },
+        vectors: sortedVectors,
+      },
+      null,
+      2
+    ) + '\n'
+  );
+
+  console.log(
+    `wrote ${outPath} (${wanted.length} vectors: ${reused.length} reused, ${toEmbed.length} newly embedded)`
+  );
+}
+
+// Only run when executed directly (`node generate-embeddings.mjs`) — this
+// module is also imported by check-layer-parity.mjs for MODEL/DIMENSIONS,
+// and that import must not trigger a live embedding run as a side effect.
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/a2ui/inert-props.json

@@ -1,6 +1,6 @@
 {
   "$comment": "Generated by a2ui/render-audit.mjs. Props that are declared in the catalog but never reach the DOM — confirmed twice, by rendering under jsdom and by reading the component source. Setting one validates cleanly and does nothing.",
-  "libraryVersion": "2.3.4",
+  "libraryVersion": "2.3.5",
   "components": {
     "cre8-link-list-item": {
       "text": {