@adia-ai/web-components 0.0.14 → 0.0.15

package/README.md

@@ -42,7 +42,9 @@ web-components/
 │   ├── provider.js      global provider registration + router-ui
 │   ├── anchor.js        popover + anchor-positioning
 │   ├── markdown.js      lightweight markdown renderer
-│   └── transport.js     SSE / streaming helpers for LLM adapters
+│   ├── transport.js     SSE / streaming helpers for LLM adapters
+│   └── data-stream.js   `data-stream-*` attribute trait (HTTP/SSE/WS,
+│                        signal-backed, refcounted shared transports)
 │
 ├── components/     — 80 *-ui custom elements
 │   └── <tag>/
@@ -159,6 +161,46 @@ Accepts the four A2UI message kinds: `updateComponents`,
 normalizes LLM-emitted aliases (e.g. `Carousel` → `swiper-ui`) so generated
 output is robust to name drift.
 
+## Data streaming via `data-stream-*` attributes
+
+Any element with a settable `.data` property — chart-ui, table-ui,
+heatmap-ui, stat-ui, list-ui, etc. — can be fed from a backing
+source via attributes alone. No per-component opt-in:
+
+```html
+<!-- HTTP one-shot fetch, JSON -->
+<chart-ui type="area" x="month" y="revenue"
+          data-stream-src="/api/revenue?range=3m"
+          data-stream-path="data"></chart-ui>
+
+<!-- HTTP polling every 5s -->
+<table-ui sortable striped
+          data-stream-src="/api/orders"
+          data-stream-interval="5000"></table-ui>
+
+<!-- Server-Sent Events, append on each message -->
+<heatmap-ui type="matrix" rows="7" cols="52"
+            data-stream-src="/sse/activity"
+            data-stream-mode="sse"
+            data-stream-merge="append"></heatmap-ui>
+
+<!-- Spread a multi-property response onto the element -->
+<stat-ui data-stream-src="/api/kpi"
+         data-stream-target="*"></stat-ui>
+```
+
+Modes: HTTP (one-shot or polling), `sse` (`EventSource`), `ws`
+(`WebSocket`). Formats: `json` (default), `csv`, `tsv`, `jsonl`,
+`text` — auto-detected from URL extension or content-type. Two
+elements with attribute-identical streams share one transport
+(refcounted, signal-backed); explicit `data-stream-id` lets
+unrelated configs share intentionally. Programmatic access via
+the `streams` registry export from `core/data-stream.js`.
+
+Implementation: `core/data-stream.js` (~360 lines). Full
+attribute table + live demos:
+[`/site/components/chart#data-stream`](./site/pages/components/chart/index.html).
+
 ## Build
 
 ```bash

package/components/chart/chart.js

@@ -885,15 +885,18 @@ class AdiaChart extends AdiaElement {
 
     try { this.#tipEl.showPopover(); } catch (_) { /* popover not supported */ }
 
-    /* Follow the cursor — offset up-right, clamp to viewport */
+    /* Follow the cursor — centered horizontally above, clamp to viewport
+       with an 8px edge-pad, flip below when there's no room above. */
     const gap = 12;
+    const edgePad = 8;
     const { clientX, clientY } = event;
     const tw = this.#tipEl.offsetWidth  || 0;
     const th = this.#tipEl.offsetHeight || 0;
-    let x = clientX + gap;
+    let x = clientX - tw / 2;
     let y = clientY - th - gap;
-    if (x + tw > window.innerWidth)  x = clientX - tw - gap;
-    if (y < 0)                       y = clientY + gap;
+    if (x < edgePad)                         x = edgePad;
+    if (x + tw > window.innerWidth - edgePad) x = window.innerWidth - tw - edgePad;
+    if (y < edgePad)                         y = clientY + gap;
     this.#tipEl.style.left = `${x}px`;
     this.#tipEl.style.top  = `${y}px`;
   }

package/components/index.js

@@ -3,6 +3,12 @@
  * Import this single file to register all custom elements.
  */
 
+/* Side-effect import — auto-attaches the document-level MutationObserver
+   that drives `data-stream-*` attribute behavior on any element with a
+   settable `.data` property (chart-ui, table-ui, heatmap-ui, stat-ui,
+   list-ui). See packages/web-components/core/data-stream.js. */
+import '../core/data-stream.js';
+
 export { AdiaIcon } from './icon/icon.js';
 export { AdiaButton } from './button/button.js';
 export { AdiaInput } from './input/input.js';

package/components/input/input.css

@@ -23,6 +23,7 @@
     --input-easing:          var(--a-easing);
 
     /* ── State: hover/focus ── */
+    --input-bg-hover:        var(--a-ui-bg-hover);
     --input-fg-hover:        var(--a-fg);
     --input-affix-fg-hover:  var(--a-fg-subtle);
     --input-fg-focus:        var(--a-fg);
@@ -72,6 +73,7 @@
     transition: border-color var(--input-duration) var(--input-easing);
   }
   :scope:not([disabled]) [slot="field"]:hover {
+    background: var(--input-bg-hover);
     border-color: var(--input-border-hover);
     color: var(--input-fg-hover);
   }

package/components/textarea/textarea.css

@@ -22,6 +22,7 @@
     --textarea-easing:          var(--a-easing);
 
     /* ── State ── */
+    --textarea-bg-hover:        var(--a-ui-bg-hover);
     --textarea-fg-hover:        var(--a-fg);
     --textarea-label-fg-focus:  var(--a-fg-subtle);
     --textarea-bg-disabled:     var(--a-ui-bg-disabled);
@@ -66,6 +67,7 @@
     transition: border-color var(--textarea-duration) var(--textarea-easing);
   }
   :scope:not([disabled]) [slot="text"]:hover {
+    background: var(--textarea-bg-hover);
     border-color: var(--textarea-border-hover);
     color: var(--textarea-fg-hover);
   }

package/components/tooltip/tooltip.js

@@ -256,6 +256,7 @@ class AdiaTooltip extends AdiaElement {
   #positionAtPointer(x, y) {
     if (!this.#popover || x == null || y == null) return;
     const gap = 12;
+    const edgePad = 8;
     const popover = this.#popover;
     popover.style.position = 'fixed';
     popover.style.left = '0';
@@ -263,10 +264,16 @@ class AdiaTooltip extends AdiaElement {
     /* Force reflow to read offset dimensions now that content changed */
     const tw = popover.offsetWidth  || 0;
     const th = popover.offsetHeight || 0;
-    let px = x + gap;
+    /* Default: centered horizontally above the cursor, gap px clear of
+       the cursor. Clamp horizontally to viewport with edgePad on each
+       side (short tooltips near the viewport edge scoot inward rather
+       than drifting off-screen). Flip vertically when there's not
+       enough room above. */
+    let px = x - tw / 2;
     let py = y - th - gap;
-    if (px + tw > window.innerWidth)  px = x - tw - gap;
-    if (py < 0)                       py = y + gap;
+    if (px < edgePad)                        px = edgePad;
+    if (px + tw > window.innerWidth - edgePad) px = window.innerWidth - tw - edgePad;
+    if (py < edgePad)                        py = y + gap;
     popover.style.left = `${px}px`;
     popover.style.top  = `${py}px`;
   }

package/core/data-stream.js

@@ -0,0 +1,465 @@
+/**
+ * data-stream — attribute-driven data ingestion, signal-backed.
+ *
+ * Architecture (signal-based, refcounted):
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │ STREAMS: Map<streamId, { signal, refs, transport, opts }>│
+ *   └──────────────────────────────────────────────────────────┘
+ *                  │ first ref creates transport
+ *                  │ each tick / message: signal.value = parsed
+ *                  │ last ref ends transport
+ *                  ▼
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │ Per-element effect:                                      │
+ *   │   effect(() => applyData(el, stream.signal.value, opts)) │
+ *   │ Subscribes to the shared signal — fires on every update. │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * Stream identity:
+ *   - Explicit `data-stream-id="..."` shares across elements.
+ *   - When unset, the id is a stable hash of (src, mode, interval,
+ *     method, body, headers, format, event). Two elements with
+ *     attribute-identical configs share one transport automatically.
+ *
+ * Universal applicability — any element with a settable property:
+ *   <chart-ui    data-stream-src="/api/series" data-stream-path="data">
+ *   <table-ui    data-stream-src="/api/orders" data-stream-interval="5000">
+ *   <stat-ui     data-stream-src="/api/kpi"    data-stream-target="*">
+ *   <text-ui     data-stream-src="/api/range"  data-stream-target="textContent">
+ *   <heatmap-ui  data-stream-src="/sse/cells"  data-stream-mode="sse">
+ *
+ * Programmatic access: `streams` is exported as a read-only Map of
+ * stream-id → signal so app code can subscribe with `effect()` or read
+ * `.value` directly.
+ *
+ * Events (all bubble from the element):
+ *   stream-load   — first signal value received for this element
+ *   stream-update — each subsequent value, detail.data = the new value
+ *   stream-error  — transport-level error, detail.error = message
+ */
+
+import { signal, effect, untracked } from './signals.js';
+
+const ATTRS = {
+  src:       'data-stream-src',
+  mode:      'data-stream-mode',
+  interval:  'data-stream-interval',
+  path:      'data-stream-path',
+  event:     'data-stream-event',
+  method:    'data-stream-method',
+  headers:   'data-stream-headers',
+  body:      'data-stream-body',
+  target:    'data-stream-target',
+  merge:     'data-stream-merge',
+  format:    'data-stream-format',
+  id:        'data-stream-id',
+};
+
+const STREAMS = new Map();           /* streamId → { signal, refs, transport, opts } */
+const ELEMENT_STREAMS = new WeakMap(); /* el → { streamId, dispose, loaded } */
+const WARNED = new WeakSet();
+
+/* Read-only public view of the streams registry. App code can do:
+   `import { streams } from '@adia-ai/web-components/core/data-stream';
+    streams.get('rev').signal.value` to read; subscribe via effect(). */
+export const streams = {
+  get(id) { return STREAMS.get(id); },
+  has(id) { return STREAMS.has(id); },
+  keys()  { return STREAMS.keys(); },
+  size()  { return STREAMS.size; },
+};
+
+function attr(el, key) { return el.getAttribute(ATTRS[key]) ?? ''; }
+function dispatch(el, name, detail) {
+  el.dispatchEvent(new CustomEvent(name, { bubbles: true, detail }));
+}
+function warnOnce(el, msg) {
+  if (WARNED.has(el)) return;
+  WARNED.add(el);
+  console.warn(`[data-stream] ${msg}`);
+}
+
+/* Stable string hash of a config for auto-id. djb2-style; collisions
+   would be benign (two streams share a transport that fetches the same
+   thing) but practically impossible for distinct configs. */
+function configHash(parts) {
+  const s = parts.join('|');
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return `auto:${(h >>> 0).toString(36)}`;
+}
+
+function streamIdFor(el) {
+  const explicit = attr(el, 'id');
+  if (explicit) return `id:${explicit}`;
+  return configHash([
+    attr(el, 'src'), attr(el, 'mode'), attr(el, 'interval'),
+    attr(el, 'method'), attr(el, 'body'), attr(el, 'headers'),
+    attr(el, 'format'), attr(el, 'event'),
+  ]);
+}
+
+function streamConfigFor(el) {
+  return {
+    src:      attr(el, 'src'),
+    mode:     (attr(el, 'mode') || 'http').toLowerCase(),
+    interval: parseInt(attr(el, 'interval'), 10) || 0,
+    method:   attr(el, 'method') || 'GET',
+    body:     attr(el, 'body') || undefined,
+    headers:  parseHeaders(attr(el, 'headers')),
+    format:   attr(el, 'format'),
+    event:    attr(el, 'event') || 'message',
+  };
+}
+
+function parseHeaders(raw) {
+  if (!raw) return undefined;
+  try { return JSON.parse(raw); } catch { return undefined; }
+}
+
+/* ── Format parsing (CSV / TSV / JSONL / text / json) ──────────────── */
+
+function detectFormat(src, contentType) {
+  const url = src.toLowerCase().split('?')[0];
+  if (url.endsWith('.csv'))   return 'csv';
+  if (url.endsWith('.tsv'))   return 'tsv';
+  if (url.endsWith('.jsonl') || url.endsWith('.ndjson')) return 'jsonl';
+  if (url.endsWith('.txt'))   return 'text';
+  const ct = (contentType || '').toLowerCase();
+  if (ct.includes('text/csv'))                  return 'csv';
+  if (ct.includes('text/tab-separated-values')) return 'tsv';
+  if (ct.includes('application/x-ndjson') ||
+      ct.includes('application/jsonl'))         return 'jsonl';
+  if (ct.includes('text/plain') && !ct.includes('json')) return 'text';
+  return 'json';
+}
+
+function parseDelimited(text, delimiter) {
+  const rows = []; let row = []; let cell = ''; let inQuote = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQuote) {
+      if (c === '"') { if (text[i + 1] === '"') { cell += '"'; i++; } else inQuote = false; }
+      else cell += c;
+    } else {
+      if (c === '"' && cell === '') inQuote = true;
+      else if (c === delimiter) { row.push(cell); cell = ''; }
+      else if (c === '\n') { row.push(cell); rows.push(row); row = []; cell = ''; }
+      else if (c === '\r') { /* skip */ }
+      else cell += c;
+    }
+  }
+  if (cell !== '' || row.length > 0) { row.push(cell); rows.push(row); }
+  if (rows.length === 0) return [];
+  const header = rows.shift();
+  return rows
+    .filter(r => !(r.length === 1 && r[0] === ''))
+    .filter(r => r.length === header.length)
+    .map(r => {
+      const obj = {};
+      for (let i = 0; i < header.length; i++) {
+        const v = r[i]; const n = +v;
+        obj[header[i]] = (v !== '' && Number.isFinite(n) && /^-?\d/.test(v)) ? n : v;
+      }
+      return obj;
+    });
+}
+
+function parseJSONL(text) {
+  const out = [];
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t || t.startsWith('//')) continue;
+    try { out.push(JSON.parse(t)); } catch { /* skip */ }
+  }
+  return out;
+}
+
+function parseBody(text, format) {
+  switch (format) {
+    case 'json':  return JSON.parse(text);
+    case 'csv':   return parseDelimited(text, ',');
+    case 'tsv':   return parseDelimited(text, '\t');
+    case 'jsonl': return parseJSONL(text);
+    case 'text':  return text;
+    default:      return JSON.parse(text);
+  }
+}
+
+/* ── Transports (HTTP / SSE / WS) — write to stream.signal ─────────── */
+
+function startTransport(stream) {
+  const { src, mode } = stream.opts;
+  if (!src) return { stop() {} };
+  if (mode === 'http') return startHTTP(stream);
+  if (mode === 'sse')  return startSSE(stream);
+  if (mode === 'ws' || mode === 'websocket') return startWS(stream);
+  console.warn(`[data-stream] Unknown mode "${mode}". Use http, sse, or ws.`);
+  return { stop() {} };
+}
+
+function startHTTP(stream) {
+  const { src, interval, method, body, headers, format: explicit } = stream.opts;
+  const abort = new AbortController();
+  let timer = null;
+  let stopped = false;
+
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      const r = await fetch(src, { method, headers, body, signal: abort.signal });
+      if (!r.ok) throw new Error(`HTTP ${r.status} ${r.statusText}`);
+      const text = await r.text();
+      if (stopped) return;
+      const ct = r.headers.get('content-type') || '';
+      const format = explicit || detectFormat(src, ct);
+      let data;
+      try { data = parseBody(text, format); }
+      catch (e) { stream.lastError = `Parse error (${format}): ${e.message}`; return; }
+      stream.signal.value = data;
+    } catch (e) {
+      if (e.name === 'AbortError') return;
+      stream.lastError = e.message;
+      stream.errorTick = (stream.errorTick || 0) + 1;
+      /* Bump error counter signal so subscribers see it too. */
+      if (stream.errorSignal) stream.errorSignal.value = stream.errorTick;
+    }
+  };
+
+  tick();
+  if (interval > 0) timer = setInterval(tick, interval);
+
+  return {
+    stop() {
+      stopped = true;
+      abort.abort();
+      if (timer) clearInterval(timer);
+    },
+  };
+}
+
+function startSSE(stream) {
+  const { src, event: eventName, format: explicit } = stream.opts;
+  if (typeof EventSource === 'undefined') {
+    console.warn('[data-stream] EventSource not available; SSE mode is a no-op here.');
+    return { stop() {} };
+  }
+  const es = new EventSource(src);
+  es.addEventListener(eventName, (e) => {
+    try {
+      const format = explicit || 'json';
+      stream.signal.value = parseBody(e.data, format);
+    } catch (err) {
+      stream.lastError = `SSE parse error: ${err.message}`;
+      stream.errorTick = (stream.errorTick || 0) + 1;
+      if (stream.errorSignal) stream.errorSignal.value = stream.errorTick;
+    }
+  });
+  es.addEventListener('error', () => {
+    stream.lastError = 'SSE connection error';
+    stream.errorTick = (stream.errorTick || 0) + 1;
+    if (stream.errorSignal) stream.errorSignal.value = stream.errorTick;
+  });
+  return { stop() { es.close(); } };
+}
+
+function startWS(stream) {
+  const { src, format: explicit } = stream.opts;
+  if (typeof WebSocket === 'undefined') {
+    console.warn('[data-stream] WebSocket not available; ws mode is a no-op here.');
+    return { stop() {} };
+  }
+  const ws = new WebSocket(src);
+  ws.addEventListener('message', (e) => {
+    try {
+      const format = explicit || 'json';
+      stream.signal.value = parseBody(typeof e.data === 'string' ? e.data : String(e.data), format);
+    } catch (err) {
+      stream.lastError = `WebSocket parse error: ${err.message}`;
+      stream.errorTick = (stream.errorTick || 0) + 1;
+      if (stream.errorSignal) stream.errorSignal.value = stream.errorTick;
+    }
+  });
+  ws.addEventListener('error', () => {
+    stream.lastError = 'WebSocket error';
+    stream.errorTick = (stream.errorTick || 0) + 1;
+    if (stream.errorSignal) stream.errorSignal.value = stream.errorTick;
+  });
+  return { stop() { ws.close(); } };
+}
+
+/* ── Stream registry ───────────────────────────────────────────────── */
+
+function acquireStream(id, opts) {
+  let stream = STREAMS.get(id);
+  if (stream) {
+    stream.refs++;
+    return stream;
+  }
+  stream = {
+    id,
+    opts,
+    signal: signal(null),
+    errorSignal: signal(0),  /* monotonic — bumps on each transport-level error */
+    refs: 1,
+    transport: null,
+    lastError: null,
+    errorTick: 0,
+  };
+  STREAMS.set(id, stream);
+  stream.transport = startTransport(stream);
+  return stream;
+}
+
+function releaseStream(stream) {
+  stream.refs--;
+  if (stream.refs <= 0) {
+    stream.transport?.stop();
+    STREAMS.delete(stream.id);
+  }
+}
+
+/* ── Apply incoming data to the element ────────────────────────────── */
+
+function resolvePath(obj, path) {
+  if (!path) return obj;
+  let cursor = obj;
+  for (const seg of path.split('.')) {
+    if (cursor == null) return null;
+    cursor = cursor[seg];
+  }
+  return cursor;
+}
+
+function applyData(el, raw, opts) {
+  let data = resolvePath(raw, opts.path);
+  if (data == null) return;
+
+  const target = opts.target || 'data';
+  const merge = opts.merge || 'replace';
+
+  if (target === '*') {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+      Object.assign(el, data);
+      dispatch(el, 'stream-update', { data });
+      return;
+    }
+    el.data = data;
+    dispatch(el, 'stream-update', { data });
+    return;
+  }
+
+  if ((merge === 'append' || merge === 'prepend') && Array.isArray(data) && Array.isArray(el[target])) {
+    el[target] = merge === 'append'
+      ? [...el[target], ...data]
+      : [...data, ...el[target]];
+  } else {
+    el[target] = data;
+  }
+  dispatch(el, 'stream-update', { data });
+}
+
+/* ── Per-element lifecycle ─────────────────────────────────────────── */
+
+export function start(el) {
+  stop(el);
+  if (!el.isConnected) return;
+  const src = attr(el, 'src');
+  if (!src) return;
+
+  const id = streamIdFor(el);
+  const opts = streamConfigFor(el);
+  const stream = acquireStream(id, opts);
+
+  /* Per-element apply options — read fresh each effect run so live attr
+     edits to path/target/merge take effect without restart. */
+  const elState = { streamId: id, loaded: false, dispose: null };
+  ELEMENT_STREAMS.set(el, elState);
+
+  /* Subscribe to data + error signals via two effects so each can dispose
+     independently. The data effect short-circuits on initial null. */
+  const dataDispose = effect(() => {
+    const value = stream.signal.value;
+    if (value == null) return;
+    untracked(() => {
+      if (!elState.loaded) {
+        elState.loaded = true;
+        dispatch(el, 'stream-load', {});
+      }
+      const applyOpts = {
+        path:   attr(el, 'path'),
+        target: attr(el, 'target') || 'data',
+        merge:  attr(el, 'merge')  || 'replace',
+      };
+      applyData(el, value, applyOpts);
+    });
+  });
+
+  const errorDispose = effect(() => {
+    const tick = stream.errorSignal.value;
+    if (tick === 0) return;
+    untracked(() => {
+      if (stream.lastError) dispatch(el, 'stream-error', { error: stream.lastError });
+    });
+  });
+
+  elState.dispose = () => { dataDispose(); errorDispose(); };
+}
+
+export function stop(el) {
+  const entry = ELEMENT_STREAMS.get(el);
+  if (!entry) return;
+  entry.dispose?.();
+  const stream = STREAMS.get(entry.streamId);
+  if (stream) releaseStream(stream);
+  ELEMENT_STREAMS.delete(el);
+}
+
+/* ── Document-level observer ───────────────────────────────────────── */
+
+const ATTR_FILTER = Object.values(ATTRS);
+
+function isStreamingEl(node) {
+  return node && node.nodeType === 1 && node.hasAttribute && node.hasAttribute(ATTRS.src);
+}
+
+function visitSubtree(root, fn) {
+  if (root.nodeType !== 1) return;
+  if (isStreamingEl(root)) fn(root);
+  if (root.querySelectorAll) {
+    root.querySelectorAll(`[${ATTRS.src}]`).forEach(fn);
+  }
+}
+
+const observer = new MutationObserver((mutations) => {
+  for (const m of mutations) {
+    if (m.type === 'attributes' && ATTR_FILTER.includes(m.attributeName)) {
+      const el = m.target;
+      if (isStreamingEl(el)) start(el);
+      else stop(el);
+      continue;
+    }
+    if (m.type === 'childList') {
+      m.addedNodes.forEach(n => visitSubtree(n, start));
+      m.removedNodes.forEach(n => visitSubtree(n, stop));
+    }
+  }
+});
+
+function bootstrap() {
+  if (typeof document === 'undefined') return;
+  observer.observe(document.documentElement, {
+    childList: true, subtree: true,
+    attributes: true, attributeFilter: ATTR_FILTER,
+  });
+  document.querySelectorAll(`[${ATTRS.src}]`).forEach(start);
+}
+
+if (typeof document !== 'undefined') {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', bootstrap, { once: true });
+  } else {
+    bootstrap();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-utils.",
   "type": "module",
   "exports": {

package/styles/colors/semantics.css

@@ -78,10 +78,14 @@
   /* Text on neutral surfaces — low shade steps = dark text for light mode.
      Dark-mode tint spread widened: text→subtle gap 25→35 steps,
      subtle→disabled gap 10→15 steps, for clearer visual hierarchy. */
+  /* Subtle + muted lifted one fine-step shade-side to clear WCAG AA
+     4.5:1 on canvas-0/1/2 in both schemes. Subtle ↔ muted gap
+     compresses from 10 to 5 step-fractions — visual hierarchy
+     leans more on font-weight + size and less on shade contrast. */
   --a-canvas-text-strong:   light-dark(var(--a-neutral-05-shade), var(--a-neutral-05-tint));
   --a-canvas-text:          light-dark(var(--a-neutral-30-shade), var(--a-neutral-30-tint));
-  --a-canvas-text-subtle:   light-dark(var(--a-neutral-40-shade), var(--a-neutral-40-tint));
-  --a-canvas-text-muted:    light-dark(var(--a-neutral-50-shade), var(--a-neutral-50-tint));
+  --a-canvas-text-subtle:   light-dark(var(--a-neutral-35-shade), var(--a-neutral-35-tint));
+  --a-canvas-text-muted:    light-dark(var(--a-neutral-40-shade), var(--a-neutral-40-tint));
   --a-canvas-text-disabled: light-dark(var(--a-neutral-60-shade), var(--a-neutral-60-tint));
   --a-canvas-text-inverse:  var(--a-neutral-10);
 
@@ -140,6 +144,15 @@
   --a-accent-active:   var(--a-accent-60);
   --a-accent-selected: var(--a-accent-50);
 
+  /* Link family — derived from accent steps deeper than --a-accent-strong
+     (step-50) so links clear WCAG AA 4.5:1 on canvas-0/1/2 in both
+     schemes. Anchor color in `typography.css` reads --a-link rather
+     than --a-accent-strong; emphasis on hover comes from a tighter
+     chroma + darker step rather than full saturation jump. */
+  --a-link:         light-dark(var(--a-accent-65-shade), var(--a-accent-65-tint));
+  --a-link-hover:   light-dark(var(--a-accent-70-shade), var(--a-accent-70-tint));
+  --a-link-visited: light-dark(var(--a-accent-75-shade), var(--a-accent-75-tint));
+
   /* Accent text on accent solid bg — needs light text on dark-ish accent */
   --a-accent-text-strong:   light-dark(var(--a-accent-05-shade), var(--a-accent-05-tint));
   --a-accent-text:          light-dark(var(--a-accent-10-shade), var(--a-accent-10-tint));
@@ -466,7 +479,7 @@
      ══════════════════════════════════════════════════════════════ */
 
   --a-ui-bg:               var(--a-canvas-0-scrim);
-  --a-ui-bg-hover:         var(--a-canvas-0-scrim);
+  --a-ui-bg-hover:         var(--a-canvas-2-scrim);
   --a-ui-bg-active:        var(--a-canvas-0);
   --a-ui-bg-selected:      var(--a-canvas-bright);
   --a-ui-bg-disabled:      var(--a-canvas-1);

package/styles/typography.css

@@ -600,15 +600,20 @@
 
 /* ── Links ── */
 :where(a) {
-  color: var(--a-accent-strong);
+  color: var(--a-link);
   text-decoration: none;
 }
 
 :where(a:hover) {
+  color: var(--a-link-hover);
   text-decoration: underline;
   text-underline-offset: 2px;
 }
 
+:where(a:visited) {
+  color: var(--a-link-visited);
+}
+
 /* ── Size wrappers — custom inline elements for relative sizing ── */
 :where(smaller) {
   font-size: 0.875em;