@profpowell/vb-project-planning 0.1.0

package/src/lib/vb-store.js

@@ -0,0 +1,200 @@
+/**
+ * VBStore — unified client-side storage for Vanilla Breeze components.
+ *
+ * Static async API over a pluggable backend. Default backend is localStorage.
+ * Keys are namespaced (`vb:{namespace}:{key}`); values are wrapped in an
+ * envelope `{ data, timestamp }` so `get()` can enforce expiry via maxAge.
+ *
+ * Async (await) even though localStorage is synchronous — this lets the
+ * backend swap to IndexedDB or a network store later without touching
+ * component code.
+ *
+ * @example
+ *   import { VBStore } from './lib/vb-store.js';
+ *
+ *   await VBStore.set('notifications', 'dismissed-v3', { by: 'user' });
+ *   const val = await VBStore.get('notifications', 'dismissed-v3');
+ *   const fresh = await VBStore.get('consent', 'banner', { maxAge: 365 * 86400_000 });
+ *   await VBStore.clear('notifications');
+ *   await VBStore.clearAll();
+ *
+ * Spec: admin/plans/april13-plan/vb-store.md
+ */
+
+const PREFIX = 'vb:';
+
+/** @typedef {{ data: unknown, timestamp: number }} Envelope */
+
+/**
+ * @typedef {object} Backend
+ * @property {(key: string) => Promise<string | null>} getRaw
+ * @property {(key: string, value: string) => Promise<void>} setRaw
+ * @property {(key: string) => Promise<void>} removeRaw
+ * @property {(prefix: string) => Promise<string[]>} keys
+ */
+
+/** @returns {Backend} */
+function createLocalStorageBackend() {
+  const storage = globalThis.localStorage;
+  if (!storage) {
+    throw new Error('VBStore: localStorage is not available in this environment');
+  }
+  return {
+    async getRaw(key) {
+      return storage.getItem(key);
+    },
+    async setRaw(key, value) {
+      storage.setItem(key, value);
+    },
+    async removeRaw(key) {
+      storage.removeItem(key);
+    },
+    async keys(prefix) {
+      const out = [];
+      for (let i = 0; i < storage.length; i++) {
+        const k = storage.key(i);
+        if (k && k.startsWith(prefix)) out.push(k);
+      }
+      return out;
+    },
+  };
+}
+
+/** @type {Backend | null} */
+let backend = null;
+
+function getBackend() {
+  if (!backend) backend = createLocalStorageBackend();
+  return backend;
+}
+
+function fullKey(namespace, key) {
+  if (typeof namespace !== 'string' || !namespace) {
+    throw new TypeError('VBStore: namespace must be a non-empty string');
+  }
+  if (typeof key !== 'string' || !key) {
+    throw new TypeError('VBStore: key must be a non-empty string');
+  }
+  return `${PREFIX}${namespace}:${key}`;
+}
+
+function namespacePrefix(namespace) {
+  if (typeof namespace !== 'string' || !namespace) {
+    throw new TypeError('VBStore: namespace must be a non-empty string');
+  }
+  return `${PREFIX}${namespace}:`;
+}
+
+/**
+ * @param {string} raw
+ * @returns {Envelope | null}
+ */
+function parseEnvelope(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && typeof parsed.timestamp === 'number') {
+      return /** @type {Envelope} */ (parsed);
+    }
+  } catch {
+    /* fall through to null */
+  }
+  return null;
+}
+
+export const VBStore = {
+  /**
+   * Swap the backend. Testing helper; not intended for normal use.
+   * Pass `null` to reset to the default localStorage backend.
+   * @param {{ backend?: Backend | null }} [config]
+   */
+  configure(config = {}) {
+    backend = config.backend ?? null;
+  },
+
+  /**
+   * Persist a value under `namespace:key`. Always stamps a timestamp.
+   * @param {string} namespace
+   * @param {string} key
+   * @param {unknown} value
+   */
+  async set(namespace, key, value) {
+    /** @type {Envelope} */
+    const envelope = { data: value, timestamp: Date.now() };
+    await getBackend().setRaw(fullKey(namespace, key), JSON.stringify(envelope));
+  },
+
+  /**
+   * Read a value under `namespace:key`. Returns `null` if missing, unparseable,
+   * or older than `options.maxAge` milliseconds.
+   * @param {string} namespace
+   * @param {string} key
+   * @param {{ maxAge?: number }} [options]
+   * @returns {Promise<unknown | null>}
+   */
+  async get(namespace, key, options) {
+    const raw = await getBackend().getRaw(fullKey(namespace, key));
+    if (raw == null) return null;
+    const envelope = parseEnvelope(raw);
+    if (!envelope) return null;
+    if (options?.maxAge != null && Date.now() - envelope.timestamp > options.maxAge) {
+      return null;
+    }
+    return envelope.data;
+  },
+
+  /**
+   * Delete a single key.
+   * @param {string} namespace
+   * @param {string} key
+   */
+  async remove(namespace, key) {
+    await getBackend().removeRaw(fullKey(namespace, key));
+  },
+
+  /**
+   * List every `{ key, data, timestamp }` entry in a namespace.
+   * Unparseable entries are skipped silently.
+   * @param {string} namespace
+   * @returns {Promise<Array<{ key: string, data: unknown, timestamp: number }>>}
+   */
+  async list(namespace) {
+    const prefix = namespacePrefix(namespace);
+    const keys = await getBackend().keys(prefix);
+    const out = [];
+    for (const full of keys) {
+      const raw = await getBackend().getRaw(full);
+      if (raw == null) continue;
+      const env = parseEnvelope(raw);
+      if (!env) continue;
+      out.push({ key: full.slice(prefix.length), data: env.data, timestamp: env.timestamp });
+    }
+    return out;
+  },
+
+  /**
+   * Remove every key under a namespace.
+   * @param {string} namespace
+   */
+  async clear(namespace) {
+    const prefix = namespacePrefix(namespace);
+    const keys = await getBackend().keys(prefix);
+    for (const k of keys) await getBackend().removeRaw(k);
+  },
+
+  /** Remove every `vb:*` key. Leaves unrelated storage alone. */
+  async clearAll() {
+    const keys = await getBackend().keys(PREFIX);
+    for (const k of keys) await getBackend().removeRaw(k);
+  },
+
+  /**
+   * Persist many entries under the same namespace.
+   * @param {string} namespace
+   * @param {Array<[string, unknown]>} entries
+   */
+  async setMany(namespace, entries) {
+    for (const [key, value] of entries) {
+      await VBStore.set(namespace, key, value);
+    }
+  },
+};

package/src/lib/vb-view-transition.js

@@ -0,0 +1,44 @@
+/**
+ * viewTransitionSwap — wrap a DOM mutation in document.startViewTransition
+ * so the swap crossfades instead of flashing.
+ *
+ * Falls back to a plain swap when:
+ *   - the host is not connected,
+ *   - startViewTransition is unavailable (e.g. Firefox today),
+ *   - prefers-reduced-motion is set.
+ *
+ * Same pattern used inline by diagram-wc, flow-diagram, gantt-chart,
+ * and site-map (vanilla-breeze-4tsb); extracted for the components
+ * covered by vanilla-breeze-7ixr.
+ *
+ * @param {HTMLElement} host - Element to pin the transition to. The browser
+ *   snapshots the host's painted area (including shadow content) and uses
+ *   the unique view-transition-name to pair the old and new snapshots.
+ * @param {() => void} swap - Synchronous DOM mutation. Runs before the
+ *   browser captures the "new" snapshot.
+ * @param {string} [prefix='vb-vt'] - Name prefix; aids debugging in DevTools.
+ * @returns {ViewTransition | null} The live transition, or null when the
+ *   fallback path was taken.
+ */
+let counter = 0;
+
+export function viewTransitionSwap(host, swap, prefix = 'vb-vt') {
+  if (
+    !host?.isConnected
+    || typeof document === 'undefined'
+    || !('startViewTransition' in document)
+    || matchMedia('(prefers-reduced-motion: reduce)').matches
+  ) {
+    swap();
+    return null;
+  }
+  const name = `${prefix}-${++counter}`;
+  host.style.viewTransitionName = name;
+  const tx = document.startViewTransition(swap);
+  tx.finished.finally(() => {
+    if (host.style.viewTransitionName === name) {
+      host.style.viewTransitionName = '';
+    }
+  });
+  return tx;
+}

package/src/utils/copy-init.js

@@ -0,0 +1,287 @@
+/**
+ * copy-init: Clipboard copy + paste via data attributes + programmatic helpers
+ *
+ * Enhances buttons with data-copy / data-copy-target / data-paste-target
+ * to interact with the clipboard. Also exports copyText(), copyRich(),
+ * and pasteFromClipboard() for components that need clipboard access
+ * with VB's standard a11y + feedback semantics.
+ *
+ * @attr {string} data-copy - Static text to copy
+ * @attr {string} data-copy-target - CSS selector for element whose textContent to copy
+ * @attr {string} data-copy-attr - When paired with data-copy-target, copy the named
+ *                                 attribute of the target instead of its textContent
+ * @attr {string} data-paste-target - CSS selector for element to receive pasted clipboard text
+ *
+ * @example Static text
+ * <button data-copy="npm install vanilla-breeze">Copy</button>
+ *
+ * @example Target element
+ * <button data-copy-target="#code-block">Copy code</button>
+ *
+ * @example Target attribute
+ * <output id="swatch" value="#3366cc">#3366cc</output>
+ * <button data-copy-target="#swatch" data-copy-attr="value">Copy hex</button>
+ *
+ * @example Paste into a target
+ * <input id="dest" type="text">
+ * <button data-paste-target="#dest">Paste</button>
+ *
+ * @example Programmatic
+ * import { copyText, copyRich, pasteFromClipboard } from '/src/utils/copy-init.js';
+ * await copyText('hello', { button: myButton });
+ * await copyRich({ text: '#3366cc', blob: pngBlob }, { button: myButton });
+ * await pasteFromClipboard(inputEl, { button: myButton });
+ */
+
+const COPIED_DURATION = 1500;
+const ANNOUNCE_DURATION = 1000;
+const SELECTOR = '[data-copy], [data-copy-target], [data-paste-target]';
+const DEFAULT_ANNOUNCE = 'Copied to clipboard';
+const DEFAULT_PASTE_ANNOUNCE = 'Pasted from clipboard';
+
+const resetTimers = new WeakMap();
+
+/**
+ * Copy text to the clipboard with VB's standard feedback semantics.
+ *
+ * Performs writeText, sets data-state="copied" on the button (if given),
+ * announces to screen readers, and dispatches a `copy` CustomEvent from
+ * the button. Safe to call when the Clipboard API is unavailable or
+ * permission is denied — returns false silently.
+ *
+ * @param {string} text - The text to copy.
+ * @param {object} [options]
+ * @param {HTMLElement} [options.button] - Button to receive data-state and dispatch the event.
+ * @param {string} [options.announceMessage] - Screen-reader message. Defaults to "Copied to clipboard".
+ * @param {number} [options.duration] - Milliseconds to hold data-state="copied". Defaults to 1500.
+ * @returns {Promise<boolean>} True if the write succeeded.
+ */
+async function copyText(text, options = {}) {
+  if (text == null || text === '') return false;
+  const { button, announceMessage = DEFAULT_ANNOUNCE, duration = COPIED_DURATION } = options;
+
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch {
+    return false;
+  }
+
+  applyFeedback({ button, duration, announceMessage, eventDetail: { text } });
+  return true;
+}
+
+/**
+ * Copy a multi-format payload to the clipboard.
+ *
+ * Writes a ClipboardItem with any combination of text/plain, text/html,
+ * and a binary blob (typically image/png). When ClipboardItem is
+ * unsupported or the browser rejects the specific MIME types, falls
+ * back to text-only copy via copyText.
+ *
+ * Common use cases: copying a color as hex text + a swatch PNG so it
+ * can be pasted into design tools as an actual color, or copying a
+ * QR code as an image alongside its encoded URL.
+ *
+ * @param {object} payload
+ * @param {string} [payload.text] - text/plain content
+ * @param {string} [payload.html] - text/html content
+ * @param {Blob}   [payload.blob] - Arbitrary blob (e.g. image/png). MIME type comes from blob.type.
+ * @param {object} [options]
+ * @param {HTMLElement} [options.button]
+ * @param {string} [options.announceMessage]
+ * @param {number} [options.duration]
+ * @returns {Promise<boolean>} True if any clipboard write succeeded (rich or text fallback).
+ */
+async function copyRich(payload, options = {}) {
+  const { text, html, blob } = payload ?? {};
+  if (!text && !html && !blob) return false;
+  const { button, announceMessage = DEFAULT_ANNOUNCE, duration = COPIED_DURATION } = options;
+
+  const richSupported = typeof ClipboardItem !== 'undefined' && typeof navigator.clipboard?.write === 'function';
+
+  if (richSupported) {
+    /** @type {Record<string, Blob>} */
+    const items = {};
+    if (text) items['text/plain'] = new Blob([text], { type: 'text/plain' });
+    if (html) items['text/html'] = new Blob([html], { type: 'text/html' });
+    if (blob) items[blob.type] = blob;
+
+    try {
+      await navigator.clipboard.write([new ClipboardItem(items)]);
+      applyFeedback({ button, duration, announceMessage, eventDetail: { payload } });
+      return true;
+    } catch {
+      // Browser may support ClipboardItem but reject some MIME types
+      // (Safari historically restricts image types). Fall through to text.
+    }
+  }
+
+  if (text) return copyText(text, options);
+  return false;
+}
+
+/**
+ * Apply the VB-standard post-write feedback: data-state, screen-reader
+ * announce, and a CustomEvent from the button.
+ * @param {{ button?: HTMLElement, duration: number, announceMessage: string, eventDetail: object, state?: string, eventName?: string }} args
+ */
+function applyFeedback({ button, duration, announceMessage, eventDetail, state = 'copied', eventName = 'copy' }) {
+  if (button) {
+    button.dataset.state = state;
+    const prior = resetTimers.get(button);
+    if (prior) clearTimeout(prior);
+    resetTimers.set(button, setTimeout(() => {
+      delete button.dataset.state;
+      resetTimers.delete(button);
+    }, duration));
+
+    button.dispatchEvent(new CustomEvent(eventName, {
+      bubbles: true,
+      detail: eventDetail,
+    }));
+  }
+
+  announce(announceMessage, button ?? document.body);
+}
+
+/**
+ * Read text from the clipboard and write it into a target element.
+ *
+ * Form controls (input, textarea, select) receive `.value`; other
+ * elements receive `.textContent`. After writing, an `input` event
+ * is dispatched on the target so framework listeners notice the change.
+ * Sets data-state="pasted" on the button, announces to screen readers,
+ * and dispatches a `paste` CustomEvent from the button.
+ *
+ * Safe to call when the Clipboard API is unavailable or the user
+ * denies permission — returns null silently.
+ *
+ * @param {Element | null | undefined} target - Element to receive the pasted text.
+ * @param {object} [options]
+ * @param {HTMLElement} [options.button]
+ * @param {string} [options.announceMessage]
+ * @param {number} [options.duration]
+ * @returns {Promise<string | null>} The text that was pasted, or null on failure.
+ */
+async function pasteFromClipboard(target, options = {}) {
+  const { button, announceMessage = DEFAULT_PASTE_ANNOUNCE, duration = COPIED_DURATION } = options;
+
+  let text;
+  try {
+    text = await navigator.clipboard.readText();
+  } catch {
+    return null;
+  }
+
+  if (target) {
+    if ('value' in target && (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement)) {
+      target.value = text;
+    } else {
+      target.textContent = text;
+    }
+    target.dispatchEvent(new Event('input', { bubbles: true }));
+  }
+
+  applyFeedback({
+    button,
+    duration,
+    announceMessage,
+    eventDetail: { text },
+    state: 'pasted',
+    eventName: 'paste',
+  });
+  return text;
+}
+
+/**
+ * Initialize copy/paste buttons within a root element
+ * @param {Element|Document} root - Root element to search within
+ */
+function initCopyButtons(root = document) {
+  root.querySelectorAll(SELECTOR).forEach(enhanceButton);
+}
+
+/**
+ * Enhance a single button with copy or paste behavior
+ * @param {HTMLElement} button - The button element to enhance
+ */
+function enhanceButton(button) {
+  if (button.hasAttribute('data-copy-init')) return;
+  button.setAttribute('data-copy-init', '');
+
+  button.addEventListener('click', () => {
+    if (button.dataset.pasteTarget) {
+      const target = document.querySelector(button.dataset.pasteTarget);
+      if (!target) return;
+      pasteFromClipboard(target, { button });
+      return;
+    }
+
+    const text = getText(button);
+    if (!text) return;
+    copyText(text, { button });
+  });
+}
+
+/**
+ * Get text to copy from a button's data attributes
+ * @param {HTMLElement} button
+ * @returns {string}
+ */
+function getText(button) {
+  if (button.dataset.copy) return button.dataset.copy;
+
+  if (button.dataset.copyTarget) {
+    const target = document.querySelector(button.dataset.copyTarget);
+    if (!target) return '';
+    const attr = button.dataset.copyAttr;
+    if (attr) return target.getAttribute(attr) ?? '';
+    return target.textContent ?? '';
+  }
+
+  return '';
+}
+
+/**
+ * Announce a message to screen readers
+ * @param {string} message
+ * @param {Element} context - Element to append announcement to
+ */
+function announce(message, context) {
+  const el = document.createElement('div');
+  el.setAttribute('role', 'status');
+  el.setAttribute('aria-live', 'polite');
+  el.className = 'visually-hidden';
+  el.textContent = message;
+  context.appendChild(el);
+  setTimeout(() => el.remove(), ANNOUNCE_DURATION);
+}
+
+// Auto-init on DOMContentLoaded
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', () => initCopyButtons());
+} else {
+  initCopyButtons();
+}
+
+// Watch for dynamically added copy buttons
+const observer = new MutationObserver((mutations) => {
+  for (const mutation of mutations) {
+    for (const node of mutation.addedNodes) {
+      if (node.nodeType !== Node.ELEMENT_NODE) continue;
+
+      // Check the node itself
+      const el = /** @type {Element} */ (node);
+      if (el.matches(SELECTOR)) {
+        enhanceButton(/** @type {HTMLElement} */ (el));
+      }
+
+      // Check descendants
+      el.querySelectorAll(SELECTOR).forEach(child => enhanceButton(/** @type {HTMLElement} */ (child)));
+    }
+  }
+});
+
+observer.observe(document.documentElement, { childList: true, subtree: true });
+
+export { initCopyButtons, copyText, copyRich, pasteFromClipboard };

package/src/web-components/_ux-base.js

@@ -0,0 +1,106 @@
+/**
+ * Shared utilities for UX planning web components
+ * (user-persona, user-story, user-journey, empathy-map, impact-effort, story-map)
+ *
+ * Shadow DOM components extend HTMLElement directly.
+ * Light DOM components (impact-effort, story-map) extend VBElement.
+ */
+
+/**
+ * HTML-escape a string to prevent XSS in shadow DOM innerHTML.
+ * @param {string} s
+ * @returns {string}
+ */
+export function esc(s) {
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Extract up to 2 initials from a name.
+ * @param {string} name
+ * @returns {string}
+ */
+export function initials(name) {
+  return name
+    .split(' ')
+    .map(n => n[0])
+    .join('')
+    .toUpperCase()
+    .slice(0, 2);
+}
+
+/**
+ * Generate a deterministic HSL color from a name string.
+ * @param {string} name
+ * @returns {string} HSL color string
+ */
+export function hashColor(name) {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = name.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  const hue = ((hash % 360) + 360) % 360;
+  return `hsl(${hue}, 65%, 55%)`;
+}
+
+/**
+ * Emotion metadata used by user-journey (and potentially other planning components).
+ * Maps emotion names to emoji, normalized score (0–1), and color.
+ */
+/**
+ * Build a Lucide-style inline SVG string (24x24, stroke-based).
+ * @param {string} inner - SVG child elements (path, circle, line, etc.)
+ * @returns {string}
+ */
+export function lucideSvg(inner) {
+  return `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${inner}</svg>`;
+}
+
+/** Shared Lucide SVG fragments for reuse across UX components. */
+export const UX_ICONS = {
+  user:          '<path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"/><circle cx="12" cy="7" r="4"/>',
+  pencil:        '<path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/><path d="m15 5 4 4"/>',
+  check:         '<path d="M20 6 9 17l-5-5"/>',
+  target:        '<circle cx="12" cy="12" r="10"/><circle cx="12" cy="12" r="6"/><circle cx="12" cy="12" r="2"/>',
+  alertTriangle: '<path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/>',
+  messageCircle: '<path d="M2.992 16.342a2 2 0 0 1 .094 1.167l-1.065 3.29a1 1 0 0 0 1.236 1.168l3.413-.998a2 2 0 0 1 1.099.092 10 10 0 1 0-4.777-4.719"/>',
+  lightbulb:     '<path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/>',
+  wrench:        '<path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.106-3.105c.32-.322.863-.22.983.218a6 6 0 0 1-8.259 7.057l-7.91 7.91a1 1 0 0 1-2.999-3l7.91-7.91a6 6 0 0 1 7.057-8.259c.438.12.54.662.219.984z"/>',
+  heart:         '<path d="M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5"/>',
+  mapPin:        '<path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0"/><circle cx="12" cy="10" r="3"/>',
+  checkCircle:   '<path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><path d="m9 11 3 3L22 4"/>',
+  x:             '<path d="M18 6 6 18"/><path d="m6 6 12 12"/>',
+  download:      '<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" x2="12" y1="15" y2="3"/>',
+  send:          '<path d="M14.536 21.686a.5.5 0 0 0 .937-.024l6.5-19a.496.496 0 0 0-.635-.635l-19 6.5a.5.5 0 0 0-.024.937l7.93 3.18a2 2 0 0 1 1.112 1.11z"/><path d="m21.854 2.147-10.94 10.939"/>',
+};
+
+/**
+ * Empathy map quadrant metadata used by empathy-map.
+ * Maps quadrant keys to label, Lucide SVG icon inner content, and accent color.
+ */
+export const QUADRANT_META = {
+  says:   { label: 'Says',   icon: UX_ICONS.messageCircle, color: '#3b82f6' },
+  thinks: { label: 'Thinks', icon: UX_ICONS.lightbulb,     color: '#8b5cf6' },
+  does:   { label: 'Does',   icon: UX_ICONS.wrench,        color: '#f59e0b' },
+  feels:  { label: 'Feels',  icon: UX_ICONS.heart,         color: '#ef4444' },
+};
+
+/**
+ * Emotion metadata used by user-journey (and potentially other planning components).
+ * Maps emotion names to emoji, normalized score (0–1), and color.
+ */
+export const EMOTION_META = {
+  delighted:  { emoji: '😄', score: 0.95, color: '#16a34a' },
+  satisfied:  { emoji: '😊', score: 0.80, color: '#22c55e' },
+  hopeful:    { emoji: '🙂', score: 0.68, color: '#84cc16' },
+  curious:    { emoji: '🤔', score: 0.55, color: '#eab308' },
+  neutral:    { emoji: '😐', score: 0.50, color: '#94a3b8' },
+  uncertain:  { emoji: '😕', score: 0.40, color: '#f97316' },
+  confused:   { emoji: '😵', score: 0.30, color: '#fb923c' },
+  frustrated: { emoji: '😤', score: 0.18, color: '#ef4444' },
+  angry:      { emoji: '😠', score: 0.05, color: '#dc2626' },
+};