@akonwi/mica 0.8.0 → 0.10.0

package/README.md

@@ -65,6 +65,11 @@ Every component states where its behavior comes from
   `select.js`, `toast.js`. Each is a tiny standalone module that enhances
   working markup — never renders it. There is no shared runtime.
 
+`m-avatar` accepts authored initials or a direct native `img`, both CSS-only.
+`avatar.js` is a separate opt-in visual enhancement: importing it locally
+derives deterministic color and features from the `blobatar` seed without a
+network request.
+
 ## Your CSS always wins
 
 All of mica ships inside `@layer mica.*`. Unlayered user CSS beats layered

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,28 @@
+# Third-party licenses
+
+## Blobatar 2.4.0
+
+Mica's optional `avatar.js` module incorporates code from
+[Blobatar](https://github.com/Alain00/blobatar).
+
+MIT License
+
+Copyright (c) 2026 Alain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/avatar.d.ts

@@ -0,0 +1,10 @@
+/* Type declarations for mica/avatar.js — side-effect module.
+ * Registers <m-avatar> and locally generates Blobatar-derived paint for its
+ * `blobatar` seed. Authored initials remain the no-module fallback.
+ */
+declare global {
+  interface HTMLElementTagNameMap {
+    "m-avatar": HTMLElement;
+  }
+}
+export {};

package/avatar.js

@@ -0,0 +1,301 @@
+/*! mica/avatar.js — generated by tools/build-avatar.ts.
+ * Includes Blobatar 2.4.0 (MIT); see THIRD_PARTY_LICENSES.md. */
+// node_modules/blobatar/dist/index.js
+function L({ l: t, c: n, h: e }) {
+  let o = e * Math.PI / 180, a = n * Math.cos(o), r = n * Math.sin(o), s = t + 0.3963377774 * a + 0.2158037573 * r, c = t - 0.1055613458 * a - 0.0638541728 * r, i = t - 0.0894841775 * a - 1.291485548 * r, m = s * s * s, l = c * c * c, u = i * i * i;
+  return [4.0767416621 * m - 3.3077115913 * l + 0.2309699292 * u, -1.2684380046 * m + 2.6097574011 * l - 0.3413193965 * u, -0.0041960863 * m - 0.7034186147 * l + 1.707614701 * u];
+}
+var q = (t) => t.every((n) => n >= -0.0001 && n <= 1.0001);
+function K(t) {
+  let n = L(t);
+  if (!q(n)) {
+    let e = 0, o = t.c;
+    for (let a = 0;a < 12; a++) {
+      let r = (e + o) / 2;
+      if (q(L({ ...t, c: r })))
+        e = r;
+      else
+        o = r;
+    }
+    n = L({ ...t, c: e });
+  }
+  return n.map((e) => Math.min(1, Math.max(0, e)));
+}
+function D(t) {
+  let [n, e, o] = K(t);
+  return 0.2126 * n + 0.7152 * e + 0.0722 * o;
+}
+function k(t, n) {
+  let e = D(t), o = D(n);
+  return (Math.max(e, o) + 0.05) / (Math.min(e, o) + 0.05);
+}
+function B(t, n, e) {
+  if (k(t, n) >= e)
+    return t;
+  let o = t.l >= n.l ? 1 : -1;
+  for (let s of [o, -o]) {
+    let c = { ...t };
+    for (let i = 0;i < 60; i++) {
+      if (c.l = Math.min(1, Math.max(0, c.l + s * 0.02)), k(c, n) >= e)
+        return c;
+      if (c.l === 0 || c.l === 1)
+        break;
+    }
+  }
+  let a = { ...t, l: 0, c: 0 }, r = { ...t, l: 1, c: 0 };
+  return k(a, n) >= k(r, n) ? a : r;
+}
+function P(t) {
+  return "#" + K(t).map((n) => {
+    let e = n <= 0.0031308 ? 12.92 * n : 1.055 * Math.pow(n, 0.4166666666666667) - 0.055;
+    return Math.round(e * 255).toString(16).padStart(2, "0");
+  }).join("");
+}
+var Z = [[0.2, { l: 0.86, c: 0.085 }], [0.36, { l: 0.9, c: 0.028 }], [0.62, { l: 0.73, c: 0.135 }], [0.8, { l: 0.62, c: 0.165 }], [0.93, { l: 0.87, c: 0.16 }], [1, { l: 0.34, c: 0.035 }]];
+var Et = (t) => Z.find(([n]) => t < n)?.[1] ?? Z[0][1];
+var U = { l: 0.145, c: 0, h: 0 };
+var Q = 1.5;
+var Lt = (t, n) => {
+  let e = Et(n), o = B({ l: e.l, c: e.c, h: t }, U, Q);
+  return { bg: { l: 0.965, c: 0.01, h: t }, head: o, eye: o.l >= 0.5 ? { l: 0.17, c: 0.02, h: t } : { l: 0.97, c: 0.012, h: t } };
+};
+var X = [["head", "bg", 1.25], ["eye", "head", 4.5]];
+function Y(t, n = true, e = 0) {
+  let o = Lt(t, e);
+  if (n)
+    for (let [a, r, s] of X)
+      o[a] = B(o[a], o[r], s);
+  return o;
+}
+function w(t, n = true, e = 0) {
+  let o = Y(t, n, e), a = {};
+  for (let r in o)
+    a[r] = P(o[r]);
+  return a;
+}
+var y = (t) => {
+  let n = Math.round(t * 100) / 100;
+  return Object.is(n, -0) ? "0" : String(n);
+};
+function T({ cx: t, cy: n, rx: e, ry: o, n: a = 4, rot: r = 0 }) {
+  let s = Math.min(1, (8 * Math.pow(2, -1 / a) - 4) / 3), c = e, i = o, m = c * s, l = i * s, u = [[c, 0], [c, l], [m, i], [0, i], [-m, i], [-c, l], [-c, 0], [-c, -l], [-m, -i], [0, -i], [m, -i], [c, -l], [c, 0]], x = r * Math.PI / 180, p = Math.cos(x), d = Math.sin(x), h = (b) => {
+    let [g, M] = u[b];
+    return `${y(t + g * p - M * d)} ${y(n + g * d + M * p)}`;
+  }, f = `M${h(0)}`;
+  for (let b = 1;b < 13; b += 3)
+    f += `C${h(b)} ${h(b + 1)} ${h(b + 2)}`;
+  return f + "Z";
+}
+function G(t, n, e, o, a, r = 0) {
+  let s = a.length, c = r * Math.PI / 180, i = a.map((u, x) => {
+    let p = c + 2 * Math.PI * x / s;
+    return [t + e * u * Math.cos(p), n + o * u * Math.sin(p)];
+  }), m = (u) => i[(u % s + s) % s], l = `M${y(m(0)[0])} ${y(m(0)[1])}`;
+  for (let u = 0;u < s; u++) {
+    let [x, p] = m(u - 1), [d, h] = m(u), [f, b] = m(u + 1), [g, M] = m(u + 2);
+    l += `C${y(d + (f - x) / 6)} ${y(h + (b - p) / 6)} ${y(f - (g - d) / 6)} ${y(b - (M - h) / 6)} ${y(f)} ${y(b)}`;
+  }
+  return l + "Z";
+}
+function J({ cx: t, cy: n, rx: e, ry: o, sides: a, round: r = 0.3, rot: s = 0 }) {
+  let c = r > 0 ? r < 1 ? r / 2 : 0.5 : 0, i = s * Math.PI / 180 - Math.PI / 2, m = Array.from({ length: a }, (p, d) => {
+    let h = i + 2 * Math.PI * d / a;
+    return [t + e * Math.cos(h), n + o * Math.sin(h)];
+  }), l = (p) => m[(p % a + a) % a], u = (p, d) => {
+    let [h, f] = l(p), [b, g] = l(d);
+    return `${y(h + (b - h) * c)} ${y(f + (g - f) * c)}`;
+  }, x = `M${u(0, -1)}`;
+  for (let p = 0;p < a; p++) {
+    let [d, h] = l(p);
+    if (x += `Q${y(d)} ${y(h)} ${u(p, p + 1)}`, c < 0.5)
+      x += `L${u(p + 1, p)}`;
+  }
+  return x + "Z";
+}
+function W(t, n, e, o) {
+  let a = y(t - e), r = y(t + e);
+  return `M${a} ${y(n - o)}H${r}V${y(n + o)}H${a}Z`;
+}
+function tt(t, n, e, o, a) {
+  let r = Math.max(1.05, a), s = e * Math.sqrt(1 - 1 / (r * r)), c = n - o / r, i = n - r * o, m = s * 0.14, l = c + 0.86 * (i - c);
+  return `M${y(t - s)} ${y(c)}L${y(t - m)} ${y(l)}Q${y(t)} ${y(i)} ${y(t + m)} ${y(l)}L${y(t + s)} ${y(c)}Z`;
+}
+function I(t, n) {
+  for (let e = 0;e < n.length; e++)
+    t = Math.imul(t ^ n[e], 3432918353), t = t << 13 | t >>> 19;
+  return t;
+}
+function wt(t) {
+  return t = Math.imul(t ^ t >>> 16, 2246822507), t = Math.imul(t ^ t >>> 13, 3266489909), (t ^ t >>> 16) >>> 0;
+}
+var nt = new TextEncoder;
+function et(t) {
+  return t.normalize("NFC").trim().toLowerCase();
+}
+function rt(t, n = true) {
+  let e = n ? et(t) : t;
+  return I(1779033703 ^ e.length, nt.encode(e));
+}
+function v(t, n) {
+  return wt(I(I(t, Uint8Array.of(255)), nt.encode(n))) / 4294967296;
+}
+function A(t, n = true, e) {
+  let o = rt(t, n), a = (r) => {
+    let s = e?.[r], c = Array.isArray(s) ? s[Math.floor(v(o, r) * s.length)] : s;
+    return c === undefined ? v(o, r) : c > 0 ? c < 1 ? c : 0.999999 : 0;
+  };
+  return a.num = (r, s, c) => s + a(r) * (c - s), a.int = (r, s, c) => s + Math.floor(a(r) * (c - s + 1)), a.pick = (r, s) => s[Math.floor(a(r) * s.length)], a.bool = (r, s = 0.5) => a(r) < s, a.jitter = (r, s) => (a(r) * 2 - 1) * s, a;
+}
+function ot(t, n, e) {
+  let o = n.expression;
+  if (e || !o)
+    return { l: t, wrap: "" };
+  return o.bake(t, o.p);
+}
+var It = (t, n) => n?.tint ? n.tint(t, n.p) : t;
+var at = (t, n) => n ? `<g transform="${n}">${t}</g>` : t;
+var vt = (t) => t.replace(/[&<>]/g, (n) => n === "&" ? "&amp;" : n === "<" ? "&lt;" : "&gt;");
+function S(t, n) {
+  let e = A(t, n.normalize ?? true, n.traits);
+  return { t: e, palette: { ...w(n.hue ?? e.num("hue", 0, 360), n.contrast ?? true, n.tone ?? e("tone")), ...n.palette } };
+}
+var At = (t) => t.title ? `<title>${vt(t.title)}</title>` : "";
+function st(t, n, e) {
+  let o = n.background ?? t.background;
+  if (o === false)
+    return;
+  return { d: o === "square" ? "M0 0H100V100H0Z" : T({ cx: 50, cy: 50, rx: 50, ry: 50, n: o === "circle" ? 2 : 6 }), fill: e.bg };
+}
+var Rt = (t) => t ? `<path d="${t.d}" fill="${t.fill}"/>` : "";
+function ct(t) {
+  return (n, e = {}) => {
+    let { t: o, palette: a } = S(n, e), r = It(a, e.expression), s = e.size ? ` width="${e.size}" height="${e.size}"` : "", c = ot(t.layout(o), e), i = At(e) + Rt(st(t, e, r)) + at(t.render(c.l, r), c.wrap);
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"${s}>${i}</svg>`;
+  };
+}
+var ut = (t, n, e) => {
+  let o = n.rx, a = t.num("eye.rx", 0.075, 0.105) * o, r = t.num("eye.ratio", 1.9, 3.2), s = t.num("eye.scale", 0.78, 1.24), c = t.num("eye.stretch", 0.85, 1.18), i = t.num("eye.gap", 0.1, 0.24) * o, m = a * Math.max(1, s), l = a * r * Math.max(1, s * c), u = m + o * 0.03 + i, x = t.jitter("gaze.x", 0.09) * e.rx, p = t.num("gaze.y", -0.2, 0.08) * e.ry, d = t.jitter("eye.dy", 0.04) * e.ry, h = Math.hypot(m, l), f = Math.hypot((Math.abs(x) + u + h) / e.rx, (Math.abs(p) + Math.abs(d) + h) / e.ry), b = f > 0.9 ? 0.9 / f : 1, g = a * b, M = g * r, F = u * b, Pt = Math.max(0, Math.min(1, i / l)), Tt = Math.min(12, Math.asin(Pt) * 180 / Math.PI), j = t.num("eye.lean", -1, 1) * Tt, Bt = Math.max(-12, Math.min(12, j + t.jitter("eye.lean2", 3.5))), z = e.cx + x * b, C = e.cy + p * b;
+  return [{ cx: z - F, cy: C, rx: g, ry: M, n: t.num("eye.n", 3.5, 6), rot: j }, { cx: z + F, cy: C + d * b, rx: g * s, ry: M * s * c, n: t.num("eye.n", 3.5, 6), rot: Bt }];
+};
+function mt(t, n) {
+  let e = (r) => (t.find(([, s]) => r < s) ?? t[t.length - 1])[0];
+  function o(r) {
+    let s = e(r("shape")), c = r.num("body.r", 31, 38) * s.core, i = { cx: 50 + r.jitter("body.x", 1.5), cy: 50 + r.jitter("body.y", 1.5), rx: c, ry: c * r.num("body.ratio", 0.92, 1.08), n: r.num("body.n", 1.9, 2.5), rot: 0, radii: Array.from({ length: r.int("body.pts", 6, 8) }, (u, x) => 1 + r.jitter(`body.r${x}`, 0.16)) };
+    s.body?.(r, i);
+    let m = s.face?.(i) ?? i, l = { petals: [], extra: [] };
+    return s.decorate?.(r, i, l), { shape: s.name, draw: s.path, body: i, face: m, petals: l.petals, extra: l.extra, eyes: n(r, i, m) };
+  }
+  function a(r, s, c) {
+    let i = (u) => Math.round(u * 100) / 100, m = (u, x) => {
+      let p = `<path d="${T(u)}"/>`;
+      return c ? `<g class="mo-eye" style="--mo-wrap:${x ? 1 : -1};--mo-lean:${i(u.rot)};transform-origin:${i(u.cx)}px ${i(u.cy)}px">${p}</g>` : p;
+    }, l = `<g fill="${s.head}">` + r.petals.map((u) => `<circle cx="${i(u.cx)}" cy="${i(u.cy)}" r="${i(u.r)}"/>`).join("") + r.extra.map((u) => `<path d="${u}"/>`).join("") + `<path d="${r.draw ? r.draw(r.body) : T(r.body)}"/></g><g fill="${s.eye}"${c ? ' class="mo-eyes"' : ""}>` + r.eyes.map(m).join("") + "</g>";
+    return c ? `<g class="mo-breathe"><g class="mo-bob">${l}</g></g>` : l;
+  }
+  return { layout: o, render: a, background: false };
+}
+var lt = (t) => J(t);
+var pt = (t) => G(t.cx, t.cy, t.rx, t.ry, t.radii, t.rot);
+var R = (t) => (n) => ({ cx: n.cx, cy: n.cy, rx: n.rx * t, ry: n.ry * t });
+var yt = (t) => R(Math.min(...t.radii) * 0.95)(t);
+var Ft = (t) => R(0.84)(t);
+var xt = { name: "round", core: 1 };
+var bt = { name: "organic", core: 0.98, path: pt, face: yt };
+var ht = { name: "boxy", core: 0.86, body: (t, n) => {
+  n.n = t.num("body.n", 3.4, 6), n.rot = t.num("body.rot", -20, 20);
+} };
+var dt = { name: "capsule", core: 1.02, body: (t, n) => {
+  n.ry *= t.num("capsule.squat", 0.55, 0.68);
+}, face: R(0.94), decorate: (t, n, e) => {
+  for (let o of [-1, 1])
+    e.petals.push({ cx: n.cx + o * (n.rx - n.ry), cy: n.cy, r: n.ry });
+}, path: (t) => W(t.cx, t.cy, t.rx - t.ry, t.ry) };
+var ft = { name: "nub", core: 0.88, decorate: (t, n, e) => {
+  let o = t.int("nub.n", 1, 2);
+  for (let a = 0;a < o; a++) {
+    let r = t.num(`nub.a${a}`, 0, 2 * Math.PI);
+    e.petals.push({ cx: n.cx + Math.cos(r) * n.rx * 0.88, cy: n.cy + Math.sin(r) * n.rx * 0.88, r: n.rx * t.num(`nub.r${a}`, 0.24, 0.4) });
+  }
+} };
+var gt = { name: "cloud", core: 0.78, face: yt, path: pt, decorate: (t, n, e) => {
+  let o = t.int("cloud.n", 4, 6);
+  for (let a = 0;a < o; a++) {
+    let r = Math.PI + Math.PI * (a + 0.5) / o;
+    e.petals.push({ cx: n.cx + Math.cos(r) * n.rx * 0.8, cy: n.cy + Math.sin(r) * n.rx * 0.5, r: n.rx * t.num(`cloud.r${a}`, 0.44, 0.62) });
+  }
+} };
+var Mt = { name: "droplet", core: 0.78, body: (t, n) => {
+  n.cy += 0.22 * n.ry, n.n = 2;
+}, face: (t) => ({ cx: t.cx, cy: t.cy + t.ry * 0.05, rx: t.rx * 0.88, ry: t.ry * 0.88 }), decorate: (t, n, e) => {
+  e.extra.push(tt(n.cx, n.cy, n.rx, n.ry, t.num("droplet.tip", 1.4, 1.65)));
+} };
+var $t = { name: "hexagon", core: 1.05, path: lt, face: Ft, body: (t, n) => {
+  n.sides = 6, n.rot = t.num("body.rot", -12, 12), n.round = t.num("poly.round", 0.24, 0.5);
+} };
+var kt = { name: "sun", core: 0.7, decorate: (t, n, e) => {
+  let o = t.int("sun.n", 6, 9), a = n.rx * t.num("sun.dist", 1, 1.08), r = n.rx * t.num("sun.r", 0.2, 0.26), s = t.num("sun.rot", 0, 2 * Math.PI);
+  for (let c = 0;c < o; c++) {
+    let i = s + 2 * Math.PI * c / o;
+    e.petals.push({ cx: n.cx + Math.cos(i) * a, cy: n.cy + Math.sin(i) * a, r });
+  }
+} };
+var Ot = { name: "triangle", core: 1.15, path: lt, body: (t, n) => {
+  n.sides = 3, n.rot = t.num("body.rot", -5, 5), n.round = t.num("poly.round", 0.24, 0.5);
+}, face: (t) => ({ cx: t.cx, cy: t.cy + t.ry * 0.1, rx: t.rx * 0.54, ry: t.ry * 0.36 }) };
+var jt = [[xt, 0.22], [bt, 0.48], [ht, 0.6], [dt, 0.7], [ft, 0.79], [gt, 0.86], [Mt, 0.915], [$t, 0.95], [kt, 0.98], [Ot, 1]];
+var E = mt(jt, ut);
+var zt = ct(E);
+
+// tools/avatar.js
+var PROPERTIES = [
+  "--m-avatar-content-color",
+  "--m-avatar-body-color",
+  "--m-avatar-eye-color",
+  "--m-avatar-body-inset-block",
+  "--m-avatar-body-inset-inline",
+  "--m-avatar-body-x",
+  "--m-avatar-body-y",
+  "--m-avatar-eye-top",
+  "--m-avatar-eye-left",
+  "--m-avatar-eye-width",
+  "--m-avatar-eye-height",
+  "--m-avatar-eye-gap",
+  "--m-avatar-eye-drop"
+];
+var percent = (value) => `${Math.round(value * 100) / 100}%`;
+
+class MAvatar extends HTMLElement {
+  static observedAttributes = ["blobatar"];
+  connectedCallback() {
+    this.#update();
+  }
+  attributeChangedCallback() {
+    if (this.isConnected)
+      this.#update();
+  }
+  #update() {
+    const seed = this.getAttribute("blobatar");
+    if (seed === null) {
+      for (const property of PROPERTIES)
+        this.style.removeProperty(property);
+      return;
+    }
+    const t = A(seed);
+    const colors = w(t.num("hue", 0, 360), true, t("tone"));
+    this.style.setProperty("--m-avatar-content-color", "transparent");
+    this.style.setProperty("--m-avatar-body-color", colors.head);
+    this.style.setProperty("--m-avatar-eye-color", colors.eye);
+    this.style.setProperty("--m-avatar-body-inset-block", percent(t.num("mica.body.block", 11, 16)));
+    this.style.setProperty("--m-avatar-body-inset-inline", percent(t.num("mica.body.inline", 10, 16)));
+    this.style.setProperty("--m-avatar-body-x", percent(t.jitter("mica.body.x", 2)));
+    this.style.setProperty("--m-avatar-body-y", percent(t.jitter("mica.body.y", 2)));
+    this.style.setProperty("--m-avatar-eye-top", percent(t.num("mica.eye.top", 42, 49)));
+    this.style.setProperty("--m-avatar-eye-left", percent(t.num("mica.eye.left", 36, 40)));
+    this.style.setProperty("--m-avatar-eye-width", percent(t.num("mica.eye.width", 2.5, 3.5)));
+    this.style.setProperty("--m-avatar-eye-height", percent(t.num("mica.eye.height", 7.5, 10)));
+    this.style.setProperty("--m-avatar-eye-gap", percent(t.num("mica.eye.gap", 19, 23)));
+    this.style.setProperty("--m-avatar-eye-drop", percent(t.jitter("mica.eye.drop", 2)));
+  }
+}
+if (!customElements.get("m-avatar"))
+  customElements.define("m-avatar", MAvatar);

package/drawer.d.ts

@@ -1,5 +1,6 @@
 /* Type declarations for mica/drawer.js — side-effect module.
- * Swipe-to-dismiss drag physics for dialog[data-drawer] bottom sheets.
- * No exports; sets :root[data-drawer-gestures] when active.
+ * Swipe-to-dismiss drag physics and a managed overlay scrim for
+ * dialog[data-drawer] bottom sheets. No exports; sets
+ * :root[data-drawer-gestures] when active.
  */
 export {};

package/drawer.js

@@ -1,12 +1,14 @@
-/* mica/drawer.js — JS-enhanced: swipe-to-dismiss for dialog[data-drawer]
- * bottom sheets on small screens.
+/* mica/drawer.js — JS-enhanced: swipe-to-dismiss and a managed scrim for
+ * dialog[data-drawer] bottom sheets on small screens.
  *
  * Enhances working markup, never replaces it: without this module the
  * drawer opens/closes via buttons and Esc; with it, the mobile sheet
  * grows a grab handle (CSS keys off :root[data-drawer-gestures] — an
  * affordance may only appear when the behavior exists) and vaul-style
  * drag physics: the sheet follows a downward drag, resists upward,
- * and dismisses past 1/3 of its height or on a flick.
+ * and dismisses past 1/3 of its height or on a flick. A fixed visual
+ * overlay replaces the CSS-only scrim so its dimming can follow the drag
+ * and fade on iOS, where ::backdrop disappears immediately on close.
  *
  * Drag surface: the handle / header strip. Drag-from-content is
  * deliberately out of scope — it requires scroll-vs-drag heuristics
@@ -18,7 +20,47 @@ const CLOSE_DISTANCE = 1 / 3; // of sheet height
 const CLOSE_VELOCITY = 0.6; // px/ms, downward flick
 const DRAWER = "dialog[data-drawer]";
 
+let overlay;
+const dismissCleanup = new WeakMap();
+
+const overlayElement = () => {
+  if (overlay) return overlay;
+  overlay = document.createElement("div");
+  overlay.setAttribute("data-mica-drawer-overlay", "");
+  overlay.setAttribute("aria-hidden", "true");
+  overlay.inert = true;
+  overlay.style.setProperty("--m-drawer-overlay-opacity", "0");
+  document.body.append(overlay);
+  // Commit the transparent state before the first open transition.
+  overlay.getBoundingClientRect();
+  return overlay;
+};
+
+const setOverlayOpacity = (value) => {
+  if (!overlay && value === 0) return;
+  overlayElement().style.setProperty(
+    "--m-drawer-overlay-opacity",
+    String(Math.max(0, Math.min(1, value))),
+  );
+};
+
+const syncOverlay = () => {
+  const openDrawer = document.querySelector(`${DRAWER}[open]`);
+  // iOS can drop the closed dialog before its translate transition runs,
+  // so transitionend never clears the drag-dismiss inline style. Clear a
+  // pending exit synchronously on reopen, before the next frame paints.
+  if (openDrawer) dismissCleanup.get(openDrawer)?.();
+  setOverlayOpacity(openDrawer ? 1 : 0);
+};
+
+new MutationObserver(syncOverlay).observe(document.documentElement, {
+  attributes: true,
+  attributeFilter: ["open"],
+  subtree: true,
+});
+
 document.documentElement.setAttribute("data-drawer-gestures", "");
+syncOverlay();
 
 document.addEventListener("pointerdown", (down) => {
   if (!SHEET.matches) return;
@@ -40,7 +82,10 @@ document.addEventListener("pointerdown", (down) => {
 
   dialog.setPointerCapture(down.pointerId);
   const baseTransition = dialog.style.transition;
+  const scrim = overlayElement();
+  const baseOverlayTransition = scrim.style.transition;
   dialog.style.transition = "none";
+  scrim.style.transition = "none";
 
   const move = (e) => {
     dy = e.clientY - down.clientY;
@@ -49,6 +94,9 @@ document.addEventListener("pointerdown", (down) => {
     lastT = e.timeStamp;
     // follow downward; resist upward
     dialog.style.translate = `0 ${dy > 0 ? dy : dy / 4}px`;
+    // Clear by half a sheet: a one-to-one distance mapping was too subtle
+    // against dark surfaces (a quarter pull only moved alpha .4 → .3).
+    setOverlayOpacity(1 - Math.max(0, dy) / (rect.height / 2));
   };
 
   const up = () => {
@@ -56,22 +104,38 @@ document.addEventListener("pointerdown", (down) => {
     dialog.removeEventListener("pointerup", up);
     dialog.removeEventListener("pointercancel", up);
     dialog.style.transition = baseTransition;
+    scrim.style.transition = baseOverlayTransition;
     if (dy > rect.height * CLOSE_DISTANCE || velocity > CLOSE_VELOCITY) {
       // continue the motion DOWNWARD off-screen. close() fires its exit
-      // (backdrop fade + display flip at the end via allow-discrete);
+      // (scrim fade + display flip at the end via allow-discrete);
       // the inline translate overrides the small CSS exit offset so the
       // sheet keeps sliding down instead of snapping back up into view
       // (the flash). Clear it only at transitionend — display:none by
-      // then, so clearing is invisible and the next open starts clean.
-      dialog.addEventListener(
-        "transitionend",
-        (e) => { if (e.propertyName === "translate") dialog.style.translate = ""; },
-        { once: true },
-      );
+      // then, so clearing is invisible. iOS may never fire that event,
+      // so a timeout clears it while closed and syncOverlay clears it if
+      // the drawer reopens first.
+      let cleanupTimer;
+      const onTransitionEnd = (e) => {
+        if (e.propertyName === "translate") clearDismiss();
+      };
+      const clearDismiss = () => {
+        if (dismissCleanup.get(dialog) !== clearDismiss) return;
+        clearTimeout(cleanupTimer);
+        dialog.removeEventListener("transitionend", onTransitionEnd);
+        dialog.style.translate = "";
+        dismissCleanup.delete(dialog);
+      };
+      dismissCleanup.set(dialog, clearDismiss);
+      dialog.addEventListener("transitionend", onTransitionEnd);
+      cleanupTimer = setTimeout(() => {
+        if (!dialog.open) clearDismiss();
+      }, 200);
+      setOverlayOpacity(0);
       requestAnimationFrame(() => { dialog.style.translate = "0 100dvh"; });
       dialog.close();
     } else {
       dialog.style.translate = ""; // spring back
+      setOverlayOpacity(1);
     }
   };
 

package/mica.css

@@ -771,6 +771,161 @@
     --m-badge-numerals: tabular-nums;
   }
 
+  /* --- avatar: authored initials, optionally Blobatar-painted -------- */
+  :where(m-avatar) {
+    display: inline-grid;
+    place-items: center;
+    position: relative;
+    flex: none;
+    box-sizing: border-box;
+    inline-size: var(--avatar-size, 3rem);
+    block-size: var(--avatar-size, 3rem);
+    overflow: hidden;
+    border-radius: var(--radius-md);
+    background: var(--color-surface-raised);
+    color: var(--m-avatar-content-color, var(--color-text));
+    font-size: calc(var(--avatar-size, 3rem) * 0.5);
+    font-weight: 600;
+    line-height: 1;
+    text-transform: uppercase;
+    vertical-align: middle;
+    white-space: nowrap;
+    user-select: none;
+  }
+
+  :where(m-avatar > img) {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+  }
+
+  /* Attribute selectors only transport values. The pseudo rules below
+     render them, so missing avatar.js leaves authored initials untouched. */
+  :where(m-avatar[blobatar]) {
+    --m-avatar-decoration: "";
+    --m-avatar-render-inset-block: 0;
+    --m-avatar-render-inset-inline: 0;
+    --m-avatar-render-x: 0;
+    --m-avatar-render-y: 0;
+  }
+
+  :where(m-avatar[blobatar][contained]) {
+    --m-avatar-render-inset-block: var(--m-avatar-body-inset-block);
+    --m-avatar-render-inset-inline: var(--m-avatar-body-inset-inline);
+    --m-avatar-render-x: var(--m-avatar-body-x);
+    --m-avatar-render-y: var(--m-avatar-body-y);
+  }
+
+  :where(m-avatar)::before {
+    content: var(--m-avatar-decoration, none);
+    position: absolute;
+    inset-block: var(--m-avatar-render-inset-block);
+    inset-inline: var(--m-avatar-render-inset-inline);
+    border-radius: inherit;
+    background: var(--m-avatar-body-color);
+    transform: translate(var(--m-avatar-render-x), var(--m-avatar-render-y));
+  }
+
+  :where(m-avatar)::after {
+    content: var(--m-avatar-decoration, none);
+    position: absolute;
+    inset: 0;
+    background:
+      radial-gradient(
+        ellipse var(--m-avatar-eye-width) var(--m-avatar-eye-height)
+        at var(--m-avatar-eye-left) var(--m-avatar-eye-top),
+        var(--m-avatar-eye-color) 98%, transparent 100%
+      ),
+      radial-gradient(
+        ellipse var(--m-avatar-eye-width) var(--m-avatar-eye-height)
+        at calc(var(--m-avatar-eye-left) + var(--m-avatar-eye-gap))
+          calc(var(--m-avatar-eye-top) + var(--m-avatar-eye-drop)),
+        var(--m-avatar-eye-color) 98%, transparent 100%
+      );
+  }
+
+  /* --- skeleton: quiet CSS-only loading placeholder ---------------- */
+  :where(m-skeleton) {
+    display: block;
+    flex: none;
+    inline-size: var(--skeleton-width, 100%);
+    block-size: var(--skeleton-height, 0.75rem);
+    overflow: hidden;
+    border-radius: var(--skeleton-radius, var(--radius-md));
+    background-color: var(--color-surface-raised);
+    animation: mica-skeleton-pulse 1.6s ease-in-out infinite alternate;
+  }
+
+  @keyframes mica-skeleton-pulse {
+    to {
+      background-color: var(--color-border);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :where(m-skeleton) {
+      animation: none;
+      background-color: var(--color-border);
+    }
+  }
+
+  /* --- stat grid: semantic summaries in a fused frame -------------- */
+  :where(dl.stat-grid) {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 1px;
+    margin-block: 0;
+    padding: 1px;
+    overflow: hidden;
+    border-radius: var(--radius-md);
+    background: var(--color-border);
+  }
+
+  :where(dl.stat-grid) > :where(div.stat) {
+    display: flex;
+    flex-direction: column;
+    flex: 1 1 min(100%, 8rem);
+    gap: var(--space-sm);
+    min-inline-size: 0;
+    padding: var(--space-md);
+    background: var(--color-surface);
+  }
+
+  :where(dl.stat-grid) > :where(div.stat) > :where(dt) {
+    color: var(--color-text-muted);
+    font-size: 0.75rem;
+    font-weight: 500;
+    line-height: 1.4;
+  }
+
+  :where(dl.stat-grid) > :where(div.stat) > :where(dd) {
+    display: flex;
+    flex-direction: column;
+    flex: 1 1 auto;
+    gap: var(--space-2xs);
+    min-inline-size: 0;
+    margin-block: 0;
+  }
+
+  :where(dl.stat-grid) > :where(div.stat) > :where(dd) > :first-child {
+    color: var(--color-text);
+    font-size: 1.5rem;
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    line-height: 1.2;
+    overflow-wrap: anywhere;
+  }
+
+  :where(dl.stat-grid) > :where(div.stat) > :where(dd) > :where(small) {
+    margin-block-start: auto;
+    color: var(--color-text-muted);
+    font-size: 0.75rem;
+    line-height: 1.4;
+  }
+
   /* --- content: tables, lists, code, quotes ------------------------ */
   :where(table) {
     inline-size: 100%;
@@ -907,6 +1062,71 @@
     background: var(--color-danger);
   }
 
+  /* --- stepper: framed sequence controls --------------------------- *
+   * Mica owns only the fused layout. Consumers own labels, disabled
+   * state, events, routing, and value changes. The frame deliberately does
+   * not clip overflow: native focus rings must remain fully visible.
+   * ------------------------------------------------------------------ */
+  :where(m-stepper) {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr) auto;
+    align-items: stretch;
+    min-inline-size: 0;
+    border: 1px solid var(--color-border-strong);
+    border-radius: var(--radius-md);
+    background: var(--color-surface);
+  }
+
+  :where(m-stepper:has(> [data-reset])) {
+    grid-template-columns: auto minmax(0, 1fr) auto auto;
+  }
+
+  :where(m-stepper) > :where(button) {
+    border: 0;
+    border-radius: 0;
+    background: transparent;
+
+    &:focus-visible {
+      z-index: 1;
+    }
+  }
+
+  :where(m-stepper) > :where(button:first-child) {
+    border-start-start-radius: inherit;
+    border-end-start-radius: inherit;
+  }
+
+  :where(m-stepper) > :where(button:last-child) {
+    border-start-end-radius: inherit;
+    border-end-end-radius: inherit;
+  }
+
+  :where(m-stepper) > :where([data-step]) {
+    inline-size: var(--control-height);
+    padding-inline: 0;
+  }
+
+  :where(m-stepper) > :where(:nth-child(2)) {
+    display: grid;
+    place-items: center;
+    min-inline-size: 0;
+    block-size: var(--control-height);
+    padding-inline: var(--space-sm);
+    overflow: hidden;
+    border-inline: 1px solid var(--color-border);
+    background: var(--color-surface-raised);
+    color: var(--color-text);
+    font-size: 0.875rem;
+    font-weight: 600;
+    text-align: center;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  :where(m-stepper) > :where([data-reset]) {
+    border-inline-start: 1px solid var(--color-border);
+  }
+
   /* --- dialog: modal + drawer --------------------------------------- *
    * The browser brings focus trapping, Esc, top layer, ::backdrop, and
    * form[method=dialog] closing. Invoker commands (commandfor/command)
@@ -1132,6 +1352,14 @@
     border-block-start: 0;
   }
 
+  /* Internal visual layer injected by drawer.js. It stays ordinary page
+     content beneath the dialog's transparent top-layer ::backdrop, so it
+     survives iOS removing that backdrop on close. Hidden outside the
+     mobile-sheet breakpoint; aria-hidden + inert are set by the module. */
+  :where([data-mica-drawer-overlay]) {
+    display: none;
+  }
+
   /* small screens: the drawer becomes a bottom sheet — shadcn's own
      mobile drawer (vaul/radix) is exactly this. Anchored to the bottom
      edge via auto top margin: bottom attachment is the one thing iOS
@@ -1148,7 +1376,7 @@
       max-inline-size: none;
       border-inline-start: 0;
       border-block-start: 1px solid var(--color-border);
-      /* Two box-shadows, both painted by the SHEET element so they
+      /* CSS-only fallback: two shadows painted by the SHEET so they
          persist through the exit (display:allow-discrete keeps the box
          rendered) — unlike ::backdrop, which iOS drops from the top
          layer the instant you close, cutting the scrim. So the dim
@@ -1184,8 +1412,28 @@
           0 0 0 100vmax oklch(0 0 0 / 0);
       }
     }
-    /* the box-shadow scrim replaces ::backdrop here; keep the native
-       backdrop clear so they don't double up or flash on the iOS cut. */
+    /* With drawer.js, keep only the bleed slab; its ordinary fixed
+       overlay owns the visible scrim and follows drag progress. */
+    :where(:root[data-drawer-gestures])
+      :where(dialog[data-drawer]) {
+      box-shadow: 0 4rem 0 0 var(--color-surface-overlay);
+    }
+
+    :where([data-mica-drawer-overlay]) {
+      display: block;
+      position: fixed;
+      inset: 0;
+      z-index: 50;
+      inline-size: 100lvw;
+      block-size: 100lvh;
+      background: oklch(0 0 0 / 0.4);
+      opacity: var(--m-drawer-overlay-opacity, 0);
+      pointer-events: none;
+      transition: opacity 0.15s;
+    }
+
+    /* The fallback shadow or managed overlay replaces ::backdrop here;
+       keep it clear so the scrims don't double up or flash on iOS. */
     :where(dialog[data-drawer][open])::backdrop {
       background: oklch(0 0 0 / 0);
     }
@@ -1431,38 +1679,136 @@
   /* --- tabs: m-tabs + tabs.js (JS-enhanced) ------------------------------ *
    * without the module: inert nav, all panels visible in order —
    * complete content. with it: tablist semantics + roving focus.
-   * shadcn segmented look: muted track, surface active tab.
+   * default: muted track + surface active tab. variant="underline":
+   * quiet rail + accent selection line; behavior stays identical.
    * ------------------------------------------------------------------ */
   :where(m-tabs) {
+    --m-tabs-rail-gap: var(--space-2xs);
+    --m-tabs-rail-padding: var(--space-2xs);
+    --m-tabs-rail-border: none;
+    --m-tabs-rail-radius: var(--radius-md);
+    --m-tabs-rail-background: var(--neutral-3);
+    --m-tabs-overflow-cover: var(--neutral-3);
+    --m-tabs-overflow-duration: 0.15s;
+    --m-tabs-overflow-marker: color-mix(in oklch, var(--color-text-muted) 70%, transparent);
+    --m-tabs-overflow-start-gutter: 0px;
+    --m-tabs-overflow-end-gutter: 0px;
+    --m-tabs-overflow-start: 0;
+    --m-tabs-overflow-end: 0;
+    --m-tabs-tab-radius: var(--radius-sm);
+    --m-tabs-tab-edge-padding: var(--space-sm);
+    --m-tabs-tab-focus-offset: var(--focus-ring-offset);
+    --m-tabs-tab-selected-background: var(--color-surface);
+    --m-tabs-tab-selected-shadow: 0 1px 2px oklch(0 0 0 / 0.08);
     display: block;
   }
 
+  :where(m-tabs[variant="underline"]) {
+    --m-tabs-rail-gap: 0;
+    --m-tabs-rail-padding: 0;
+    --m-tabs-rail-border: 1px solid var(--color-border);
+    --m-tabs-rail-radius: 0;
+    --m-tabs-rail-background: transparent;
+    --m-tabs-overflow-cover: var(--color-surface);
+    --m-tabs-tab-radius: 0;
+    --m-tabs-tab-edge-padding: 0;
+    --m-tabs-tab-focus-offset: -2px;
+    --m-tabs-tab-selected-background: transparent;
+    --m-tabs-tab-selected-shadow: inset 0 -2px var(--color-accent);
+  }
+
   :where(m-tabs) > :where(nav) {
     display: inline-flex;
-    gap: var(--space-2xs);
-    padding: var(--space-2xs);
-    background: var(--neutral-3);
-    border-radius: var(--radius-md);
+    gap: var(--m-tabs-rail-gap);
+    padding: var(--m-tabs-rail-padding);
+    border-block-end: var(--m-tabs-rail-border);
+    border-radius: var(--m-tabs-rail-radius);
+    background: var(--m-tabs-rail-background);
 
     /* Graceful collapse: labels never wrap inside a tab — when the rail
-       is narrower than its tabs it scrolls horizontally instead. The
-       thin scrollbar is the overflow affordance on platforms that show
-       one; scroll chaining stays contained. */
+       is narrower than its tabs it scrolls horizontally instead. Before
+       enhancement, the native scrollbar remains the overflow affordance.
+       tabs.js hides it, activates sticky direction markers in clear
+       gutters, and reveals a selected tab within those gutters. Scroll
+       chaining stays contained. */
     max-inline-size: 100%;
     overflow-x: auto;
     overscroll-behavior-x: contain;
     scrollbar-width: thin;
 
+    &[role="tablist"] {
+      scrollbar-width: none;
+    }
+
+    &::before,
+    &::after {
+      content: "";
+      position: sticky;
+      z-index: 1;
+      align-self: stretch;
+      background-color: var(--m-tabs-overflow-cover);
+      background-position: center;
+      background-size: 6px 10px;
+      background-repeat: no-repeat;
+      pointer-events: none;
+    }
+
+    &::before {
+      inset-inline-start: 0;
+      flex: 0 0 var(--space-md);
+      margin-inline-end: calc(var(--m-tabs-overflow-start-gutter) - var(--space-md));
+      opacity: var(--m-tabs-overflow-start);
+      background-image: conic-gradient(from 45deg at left center,
+        var(--m-tabs-overflow-marker) 0 25%, transparent 0);
+      transition:
+        opacity var(--m-tabs-overflow-duration),
+        margin-inline-end var(--m-tabs-overflow-duration);
+    }
+
+    &::after {
+      inset-inline-end: 0;
+      flex: 0 0 var(--space-md);
+      margin-inline-start: calc(var(--m-tabs-overflow-end-gutter) - var(--space-md));
+      opacity: var(--m-tabs-overflow-end);
+      background-image: conic-gradient(from 225deg at right center,
+        var(--m-tabs-overflow-marker) 0 25%, transparent 0);
+      transition:
+        opacity var(--m-tabs-overflow-duration),
+        margin-inline-start var(--m-tabs-overflow-duration);
+    }
+
+    &:dir(rtl)::before {
+      background-image: conic-gradient(from 225deg at right center,
+        var(--m-tabs-overflow-marker) 0 25%, transparent 0);
+    }
+
+    &:dir(rtl)::after {
+      background-image: conic-gradient(from 45deg at left center,
+        var(--m-tabs-overflow-marker) 0 25%, transparent 0);
+    }
+
     & > :where(button) {
       flex-shrink: 0;
       white-space: nowrap;
       block-size: var(--control-height-sm);
       padding-inline: var(--space-sm);
       border: 0;
-      border-radius: var(--radius-sm);
+      border-radius: var(--m-tabs-tab-radius);
       background: transparent;
       color: var(--color-text-muted);
 
+      &:first-of-type {
+        padding-inline-start: var(--m-tabs-tab-edge-padding);
+      }
+
+      &:last-of-type {
+        padding-inline-end: var(--m-tabs-tab-edge-padding);
+      }
+
+      &:focus-visible {
+        outline-offset: var(--m-tabs-tab-focus-offset);
+      }
+
       /* :not() guards mirror the base button states (house rule) */
       &:hover:not(:disabled, [aria-disabled="true"]),
       &:active:not(:disabled, [aria-disabled="true"]) {
@@ -1471,19 +1817,25 @@
       }
 
       &[aria-selected="true"] {
-        background: var(--color-surface);
+        background: var(--m-tabs-tab-selected-background);
         color: var(--color-text);
-        box-shadow: 0 1px 2px oklch(0 0 0 / 0.08);
+        box-shadow: var(--m-tabs-tab-selected-shadow);
 
         &:hover:not(:disabled, [aria-disabled="true"]),
         &:active:not(:disabled, [aria-disabled="true"]) {
-          background: var(--color-surface);
+          background: var(--m-tabs-tab-selected-background);
           color: var(--color-text);
         }
       }
     }
   }
 
+  /* Vendor pseudo gets its own rule: one unknown selector in a list
+     invalidates the whole list. */
+  :where(m-tabs) > :where(nav[role="tablist"])::-webkit-scrollbar {
+    display: none;
+  }
+
   :where(m-tabs) > :where(section) {
     padding-block: var(--space-md);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akonwi/mica",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Custom elements. Native behavior. Nearly no JavaScript.",
   "keywords": [
     "css",
@@ -21,6 +21,10 @@
   "exports": {
     ".": "./mica.css",
     "./mica.css": "./mica.css",
+    "./avatar.js": {
+      "types": "./avatar.d.ts",
+      "default": "./avatar.js"
+    },
     "./invoker.js": {
       "types": "./invoker.d.ts",
       "default": "./invoker.js"
@@ -55,6 +59,8 @@
   },
   "files": [
     "mica.css",
+    "avatar.js",
+    "avatar.d.ts",
     "invoker.js",
     "invoker.d.ts",
     "drawer.js",
@@ -69,16 +75,22 @@
     "toast.d.ts",
     "combobox.js",
     "combobox.d.ts",
-    "types/react.d.ts"
+    "types/react.d.ts",
+    "THIRD_PARTY_LICENSES.md"
   ],
   "sideEffects": true,
   "devDependencies": {
     "axe-core": "^4.12.1",
+    "blobatar": "2.4.0",
     "pixelmatch": "^7.2.0",
     "playwright": "^1.61.1",
     "pngjs": "^7.0.0"
   },
   "scripts": {
+    "build:avatar": "bun tools/build-avatar.ts",
+    "docs:build": "bun tools/build-docs.ts",
+    "docs:check": "bun tools/build-docs.ts --check",
+    "docs:serve": "bun run docs:build && bun tools/serve.ts",
     "snapshot": "bun tools/snapshot.ts",
     "snapshot:check": "bun tools/snapshot.ts --check",
     "snapshot:setup": "playwright install chromium webkit"

package/tabs.d.ts

@@ -1,5 +1,6 @@
 /* Type declarations for mica/tabs.js — side-effect module.
- * Registers <m-tabs>: roving tabindex, arrow keys, aria-selected wiring.
+ * Registers <m-tabs>: roving tabindex, arrow keys, aria-selected wiring,
+ * selected-tab reveal, and directional overflow markers.
  */
 declare global {
   interface HTMLElementTagNameMap {

package/tabs.js

@@ -3,7 +3,8 @@
  * Enhances working light-DOM markup; never renders it. Without this
  * module, the nav buttons are inert and every panel is visible in
  * order — complete, readable content. With it: real tablist semantics,
- * roving tabindex, arrow-key navigation, automatic activation.
+ * roving tabindex, arrow-key navigation, automatic activation, and
+ * selected-tab reveal with position-aware overflow markers.
  *
  *   <m-tabs>
  *     <nav>
@@ -23,10 +24,43 @@ let uid = 0;
 class MTabs extends HTMLElement {
   #tabs = [];
   #panels = [];
+  #nav = null;
+  #overflowing = false;
+  #resizeObserver = null;
+  #revealFrame = null;
+  #onScroll = () => this.#syncOverflow();
+  #cancelReveal = () => {
+    if (this.#revealFrame !== null) cancelAnimationFrame(this.#revealFrame);
+    this.#revealFrame = null;
+  };
+  #onClick = (event) => {
+    const tab = event.target instanceof Element ? event.target.closest("button") : null;
+    const index = this.#tabs.indexOf(tab);
+    if (index === -1) return;
+    this.select(index);
+    this.#reveal(index);
+  };
+  #onKeyDown = (event) => {
+    const n = this.#tabs.length;
+    const current = this.#tabs.findIndex(
+      (tab) => tab.getAttribute("aria-selected") === "true",
+    );
+    let next = null;
+    if (event.key === "ArrowRight") next = (current + 1) % n;
+    else if (event.key === "ArrowLeft") next = (current - 1 + n) % n;
+    else if (event.key === "Home") next = 0;
+    else if (event.key === "End") next = n - 1;
+    if (next === null) return;
+    event.preventDefault();
+    this.select(next); // automatic activation, radix-style
+    this.#tabs[next].focus({ preventScroll: true });
+    this.#reveal(next);
+  };
 
   connectedCallback() {
     const nav = this.querySelector(":scope > nav");
     if (!nav) return;
+    this.#nav = nav;
     this.#tabs = [...nav.querySelectorAll("button")];
     const sections = [...this.querySelectorAll(":scope > section")];
     this.#panels = this.#tabs.map((b, i) => {
@@ -44,29 +78,117 @@ class MTabs extends HTMLElement {
         panel.setAttribute("aria-labelledby", tab.id);
         panel.tabIndex = 0;
       }
-      tab.addEventListener("click", () => this.select(i));
     });
 
-    nav.addEventListener("keydown", (e) => {
-      const n = this.#tabs.length;
-      const current = this.#tabs.findIndex(
-        (t) => t.getAttribute("aria-selected") === "true",
-      );
-      let next = null;
-      if (e.key === "ArrowRight") next = (current + 1) % n;
-      else if (e.key === "ArrowLeft") next = (current - 1 + n) % n;
-      else if (e.key === "Home") next = 0;
-      else if (e.key === "End") next = n - 1;
-      if (next === null) return;
-      e.preventDefault();
-      this.select(next); // automatic activation, radix-style
-      this.#tabs[next].focus();
-    });
+    nav.addEventListener("click", this.#onClick);
+    nav.addEventListener("keydown", this.#onKeyDown);
+    nav.addEventListener("pointerdown", this.#cancelReveal, { passive: true });
+    nav.addEventListener("wheel", this.#cancelReveal, { passive: true });
 
     const initial = this.#tabs.findIndex(
       (t) => t.hasAttribute("selected") || t.getAttribute("aria-selected") === "true",
     );
     this.select(initial === -1 ? 0 : initial);
+
+    nav.addEventListener("scroll", this.#onScroll, { passive: true });
+    this.#resizeObserver = new ResizeObserver(() => this.#measureOverflow());
+    this.#resizeObserver.observe(nav);
+    this.#tabs.forEach((tab) => this.#resizeObserver.observe(tab));
+    this.#measureOverflow();
+  }
+
+  disconnectedCallback() {
+    this.#nav?.removeEventListener("click", this.#onClick);
+    this.#nav?.removeEventListener("keydown", this.#onKeyDown);
+    this.#nav?.removeEventListener("pointerdown", this.#cancelReveal);
+    this.#nav?.removeEventListener("wheel", this.#cancelReveal);
+    this.#nav?.removeEventListener("scroll", this.#onScroll);
+    this.#resizeObserver?.disconnect();
+    this.#cancelReveal();
+    for (const property of [
+      "--m-tabs-overflow-start-gutter",
+      "--m-tabs-overflow-end-gutter",
+      "--m-tabs-overflow-start",
+      "--m-tabs-overflow-end",
+    ]) this.#nav?.style.removeProperty(property);
+    this.#nav = null;
+    this.#resizeObserver = null;
+  }
+
+  #measureOverflow() {
+    const nav = this.#nav;
+    if (!nav) return;
+    const style = getComputedStyle(nav);
+    const gap = Number.parseFloat(style.columnGap) || 0;
+    const padding = (Number.parseFloat(style.paddingInlineStart) || 0) +
+      (Number.parseFloat(style.paddingInlineEnd) || 0);
+    const tabsWidth = this.#tabs.reduce(
+      (width, tab) => width + tab.getBoundingClientRect().width,
+      padding + gap * Math.max(0, this.#tabs.length - 1),
+    );
+    this.#overflowing = tabsWidth > nav.clientWidth + 1;
+    this.#syncOverflow();
+  }
+
+  #syncOverflow() {
+    const nav = this.#nav;
+    if (!nav) return;
+    const offset = Math.abs(nav.scrollLeft);
+    const max = nav.scrollWidth - nav.clientWidth;
+    const start = this.#overflowing && offset > 1;
+    const end = this.#overflowing && offset < max - 1;
+    nav.style.setProperty("--m-tabs-overflow-start", String(start ? 1 : 0));
+    nav.style.setProperty("--m-tabs-overflow-end", String(end ? 1 : 0));
+    nav.style.setProperty(
+      "--m-tabs-overflow-start-gutter",
+      start ? "var(--space-md)" : "0px",
+    );
+    nav.style.setProperty(
+      "--m-tabs-overflow-end-gutter",
+      end ? "var(--space-md)" : "0px",
+    );
+  }
+
+  #reveal(index) {
+    const nav = this.#nav;
+    if (!nav || !this.#tabs[index]) return;
+    this.#cancelReveal();
+    const durations = getComputedStyle(nav, "::before").transitionDuration.split(",");
+    const duration = durations.reduce((longest, value) => {
+      const time = Number.parseFloat(value) * (value.trim().endsWith("ms") ? 1 : 1000);
+      return Math.max(longest, time);
+    }, 0);
+    // Follow the moving gutters through their transition, plus two frames
+    // for the scroll event that activates the newly exposed marker.
+    const settleAt = performance.now() + duration + 34;
+    let firstFrame = true;
+    const reveal = (now) => {
+      const nav = this.#nav;
+      const tab = this.#tabs[index];
+      if (!nav || !tab) return;
+      const navRect = nav.getBoundingClientRect();
+      const tabRect = tab.getBoundingClientRect();
+      const beforeStyle = getComputedStyle(nav, "::before");
+      const afterStyle = getComputedStyle(nav, "::after");
+      const before = Math.max(0,
+        (Number.parseFloat(beforeStyle.inlineSize) || 0) +
+        (Number.parseFloat(beforeStyle.marginInlineEnd) || 0));
+      const after = Math.max(0,
+        (Number.parseFloat(afterStyle.inlineSize) || 0) +
+        (Number.parseFloat(afterStyle.marginInlineStart) || 0));
+      const rtl = getComputedStyle(nav).direction === "rtl";
+      const left = navRect.left + (rtl ? after : before);
+      const right = navRect.right - (rtl ? before : after);
+      if (tabRect.left < left) nav.scrollBy({ left: tabRect.left - left });
+      else if (tabRect.right > right) nav.scrollBy({ left: tabRect.right - right });
+      if (firstFrame) {
+        this.#syncOverflow();
+        firstFrame = false;
+      }
+      if (now < settleAt) this.#revealFrame = requestAnimationFrame(reveal);
+      else this.#revealFrame = null;
+    };
+    this.#revealFrame = requestAnimationFrame(reveal);
   }
 
   select(index) {

package/types/react.d.ts

@@ -51,11 +51,17 @@ declare module 'react' {
 
       // components
       'm-segmented': MicaElement
-      'm-tabs': MicaElement
+      'm-stepper': MicaElement
+      'm-tabs': MicaElement<{ variant?: 'underline' }>
       'm-badge': MicaElement<{
         variant?: 'primary' | 'success' | 'warning' | 'danger'
         count?: boolean
       }>
+      'm-avatar': MicaElement<{
+        blobatar?: string
+        contained?: boolean
+      }>
+      'm-skeleton': MicaElement
       'm-toast': MicaElement<{
         popover?: 'manual'
         variant?: 'success' | 'warning' | 'danger'