@adia-ai/web-components 0.0.26 → 0.0.27

package/components/agent-artifact/agent-artifact.a2ui.json

@@ -32,7 +32,7 @@
       "default": ""
     },
     "kind": {
-      "description": "Uppercase badge label.",
+      "description": "Badge label; value is normalized to uppercase before rendering.",
       "type": "string",
       "default": ""
     },

package/components/agent-artifact/agent-artifact.css

@@ -13,6 +13,7 @@
     --agent-artifact-fg-muted:          var(--a-fg-muted);
     --agent-artifact-border:            var(--a-border-subtle);
     --agent-artifact-header-bg:         var(--a-bg);
+    --agent-artifact-header-bg-hover:   var(--a-bg-hover);
 
     /* ── Typography ── */
     --agent-artifact-title-size:        var(--a-ui-md);
@@ -46,6 +47,16 @@
     cursor: pointer;
     user-select: none;
     min-width: 0;
+    transition: background var(--agent-artifact-duration);
+  }
+
+  [data-artifact-header]:hover {
+    background: var(--agent-artifact-header-bg-hover);
+  }
+
+  [data-artifact-header]:focus-visible {
+    outline: none;
+    box-shadow: var(--a-focus-ring) inset;
   }
 
   [data-artifact-icon] {

package/components/agent-artifact/agent-artifact.js

@@ -17,7 +17,8 @@
  *
  * Attributes:
  *   title       — header title (string)
- *   kind        — small uppercase badge, e.g. "A2UI", "JSON", "TICKET"
+ *   kind        — small badge, e.g. "A2UI", "JSON", "TICKET" (value is
+ *                 normalized to uppercase before rendering)
  *   icon        — icon-ui name for the header
  *   collapsed   — start collapsed (body hidden)
  *   tone        — neutral (default) | accent | warning | danger
@@ -59,6 +60,7 @@ class AdiaAgentArtifact extends AdiaElement {
 
   disconnected() {
     this.#headerEl?.removeEventListener('click', this.#onHeaderClick);
+    this.#headerEl?.removeEventListener('keydown', this.#onHeaderKey);
     this.#headerEl = this.#iconEl = this.#titleEl = null;
     this.#kindEl = this.#chevronEl = this.#bodyEl = null;
   }
@@ -73,6 +75,17 @@ class AdiaAgentArtifact extends AdiaElement {
     this.render();
   };
 
+  // Keyboard activation — Space/Enter toggle (matches role="button" semantics).
+  #onHeaderKey = (e) => {
+    if (e.key === ' ' || e.key === 'Enter') {
+      // Don't fire when the focus is on a slotted action button — let those
+      // handle their own activation.
+      if (e.target.closest('[slot="primary"], [slot="secondary"]')) return;
+      e.preventDefault();
+      this.#onHeaderClick(e);
+    }
+  };
+
   render() {
     if (!this.#headerEl) return;
 
@@ -95,6 +108,9 @@ class AdiaAgentArtifact extends AdiaElement {
     if (this.#bodyEl) {
       this.#bodyEl.hidden = this.collapsed;
     }
+    if (this.#headerEl) {
+      this.#headerEl.setAttribute('aria-expanded', String(!this.collapsed));
+    }
   }
 
   #build() {
@@ -120,10 +136,15 @@ class AdiaAgentArtifact extends AdiaElement {
 
     this.innerHTML = '';
 
-    // Header
+    // Header — keyboard-focusable button-style row that toggles collapsed.
+    // role/tabindex make Space/Enter activate it the same as click.
     this.#headerEl = document.createElement('div');
     this.#headerEl.setAttribute('data-artifact-header', '');
+    this.#headerEl.setAttribute('role', 'button');
+    this.#headerEl.setAttribute('tabindex', '0');
+    this.#headerEl.setAttribute('aria-expanded', String(!this.collapsed));
     this.#headerEl.addEventListener('click', this.#onHeaderClick);
+    this.#headerEl.addEventListener('keydown', this.#onHeaderKey);
 
     this.#iconEl = document.createElement('icon-ui');
     this.#iconEl.setAttribute('data-artifact-icon', '');

package/components/agent-artifact/agent-artifact.yaml

@@ -9,7 +9,7 @@ version: 1
 description: Inline container for structured agent artifacts (A2UI, JSON, tickets).
 props:
   kind:
-    description: Uppercase badge label.
+    description: Badge label; value is normalized to uppercase before rendering.
     type: string
     default: ""
   collapsed:

package/components/agent-reasoning/agent-reasoning.css

@@ -55,6 +55,17 @@
     user-select: none;
     padding-bottom: var(--a-space-1);
     color: var(--agent-reasoning-fg-muted);
+    border-radius: var(--a-radius-sm);
+    transition: color var(--agent-reasoning-duration) var(--agent-reasoning-easing);
+  }
+
+  [data-reasoning-summary]:hover {
+    color: var(--agent-reasoning-fg);
+  }
+
+  [data-reasoning-summary]:focus-visible {
+    outline: none;
+    box-shadow: var(--a-focus-ring);
   }
 
   [data-reasoning-summary] > [data-reasoning-check],

package/components/agent-reasoning/agent-reasoning.js

@@ -109,6 +109,7 @@ class AdiaAgentReasoning extends AdiaElement {
       this.#finishTimer = null;
     }
     this.#summaryEl?.removeEventListener('click', this.#onSummaryClick);
+    this.#summaryEl?.removeEventListener('keydown', this.#onSummaryKey);
     this.#bodyEl?.removeEventListener('timeline-toggle', this.#onStepToggle);
     this.#summaryEl = null;
     this.#bodyEl = null;
@@ -265,12 +266,26 @@ class AdiaAgentReasoning extends AdiaElement {
     this.#render();
   };
 
+  // Keyboard activation — Space/Enter toggle (matches role="button" semantics).
+  #onSummaryKey = (e) => {
+    if (e.key === ' ' || e.key === 'Enter') {
+      e.preventDefault();
+      this.#onSummaryClick();
+    }
+  };
+
   #buildShell() {
     this.innerHTML = '';
 
+    // Summary is a click-to-toggle row; mark up + key-activate so it
+    // behaves like a button under keyboard nav too.
     this.#summaryEl = document.createElement('div');
     this.#summaryEl.setAttribute('data-reasoning-summary', '');
+    this.#summaryEl.setAttribute('role', 'button');
+    this.#summaryEl.setAttribute('tabindex', '0');
+    this.#summaryEl.setAttribute('aria-expanded', String(!this.collapsed));
     this.#summaryEl.addEventListener('click', this.#onSummaryClick);
+    this.#summaryEl.addEventListener('keydown', this.#onSummaryKey);
     this.appendChild(this.#summaryEl);
 
     this.#bodyEl = document.createElement('div');
@@ -341,6 +356,7 @@ class AdiaAgentReasoning extends AdiaElement {
     `;
 
     this.#bodyEl.hidden = this.collapsed;
+    this.#summaryEl.setAttribute('aria-expanded', String(!this.collapsed));
     if (this.collapsed) return;
 
     // Body rendering: we group contiguous steps into timeline-ui blocks and

package/components/agent-trace/agent-trace.css

@@ -43,9 +43,23 @@
     gap: var(--agent-trace-inline-gap);
     cursor: pointer;
     white-space: nowrap;
+    border-radius: var(--a-radius-sm);
+    padding: var(--a-space-0-5) var(--a-space-1);
+    margin: calc(var(--a-space-0-5) * -1) calc(var(--a-space-1) * -1);
+    transition: background var(--agent-trace-chevron-dur);
+  }
+
+  [data-trace-root] > summary:hover {
+    background: var(--a-bg-subtle);
+  }
+
+  [data-trace-root] > summary:focus-visible {
+    outline: none;
+    box-shadow: var(--a-focus-ring);
   }
 
   [data-trace-root] > summary::-webkit-details-marker { display: none; }
+  [data-trace-root] > summary::marker { content: ''; }
 
   [data-trace-status] {
     flex: 1;
@@ -163,6 +177,11 @@
     background: var(--a-bg-subtle);
   }
 
+  details[data-trace-row] > summary:focus-visible {
+    outline: none;
+    box-shadow: var(--a-focus-ring);
+  }
+
   [data-trace-label] {
     color: var(--agent-trace-fg-subtle);
   }

package/components/alert/alert.a2ui.json

@@ -93,11 +93,17 @@
       "button"
     ],
     "slots": {
-      "default": {
-        "description": "Rich content for the alert body"
+      "action": {
+        "description": "Optional trailing action button (e.g. \"Refresh\", \"Status page\"). Right-aligned in the flex layout. See system-banners pattern for examples."
       },
-      "icon": {
-        "description": "Custom icon element"
+      "close": {
+        "description": "Close button. Stamped automatically when `closable` is set; the stamped element is `<button-ui slot=\"close\" icon=\"x\" variant=\"ghost\" size=\"sm\">`. Override by passing a custom `slot=\"close\"` button."
+      },
+      "content": {
+        "description": "Alert body. For single-line text use the `text=` attribute (alert.js stamps a `<span slot=\"content\">` automatically). For rich content with title + description, wrap in `<col-ui slot=\"content\">` — the alert root is `display: flex` row, so multiple bare children would lay out side-by-side instead of stacking."
+      },
+      "leading": {
+        "description": "Leading icon. Stamped automatically from the `icon=` attribute; consumers can override by passing a custom `<icon-ui slot=\"leading\">`."
       }
     },
     "states": [

package/components/alert/alert.css

@@ -65,6 +65,19 @@
     --alert-icon-fg: var(--a-danger-strong);
   }
 
+  /* `muted` and `neutral` are semantic aliases of the base — same tokens
+     as the default variant, declared explicitly so the yaml enum and the
+     CSS contract agree. Use cases: passive callouts (beta banners,
+     tertiary notes) where the alert should read as quiet chrome rather
+     than carrying tonal weight. */
+  :scope[variant="muted"],
+  :scope[variant="neutral"] {
+    --alert-bg:      var(--a-bg-muted);
+    --alert-fg:      var(--a-fg);
+    --alert-border:  var(--a-border-subtle);
+    --alert-icon-fg: var(--a-fg-muted);
+  }
+
   /* ── Slots ── */
   :scope [slot="leading"] {
     flex-shrink: 0;

package/components/alert/alert.js

@@ -4,7 +4,7 @@
  *
  * Inline alert banner with optional icon and close button.
  *
- * Variants: default, info, success, warning, danger
+ * Variants: default, info, success, warning, danger, muted, neutral
  * Slots: leading (icon), content (text), close (dismiss button)
  *
  * Events:

package/components/alert/alert.yaml

@@ -36,10 +36,27 @@ events:
   close:
     description: Fired when the close button is clicked
 slots:
-  default:
-    description: Rich content for the alert body
-  icon:
-    description: Custom icon element
+  content:
+    description: >-
+      Alert body. For single-line text use the `text=` attribute (alert.js
+      stamps a `<span slot="content">` automatically). For rich content
+      with title + description, wrap in `<col-ui slot="content">` — the
+      alert root is `display: flex` row, so multiple bare children would
+      lay out side-by-side instead of stacking.
+  leading:
+    description: >-
+      Leading icon. Stamped automatically from the `icon=` attribute;
+      consumers can override by passing a custom `<icon-ui slot="leading">`.
+  close:
+    description: >-
+      Close button. Stamped automatically when `closable` is set; the
+      stamped element is `<button-ui slot="close" icon="x" variant="ghost"
+      size="sm">`. Override by passing a custom `slot="close"` button.
+  action:
+    description: >-
+      Optional trailing action button (e.g. "Refresh", "Status page").
+      Right-aligned in the flex layout. See system-banners pattern for
+      examples.
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/badge/badge.a2ui.json

@@ -61,8 +61,6 @@
         "warning",
         "danger",
         "primary",
-        "soft",
-        "outline",
         "muted",
         "neutral"
       ],

package/components/badge/badge.css

@@ -74,5 +74,25 @@
     --badge-fg: var(--a-danger-text);
   }
 
+  /* `primary` is the accent-filled variant — solid bg + on-accent text,
+     used for "PRO"-style emphasis chips that should read as a brand
+     stamp rather than tinted-on-canvas. Uses the L3 primary-* surface
+     matrix so it tracks the same accent-strong source as button-ui's
+     primary variant. */
+  :scope[variant="primary"] {
+    --badge-bg: var(--a-primary-bg);
+    --badge-fg: var(--a-primary-fg);
+  }
+
+  /* `muted` and `neutral` are semantic aliases of the base — same tokens
+     as the default variant, declared explicitly so the yaml enum and the
+     CSS contract agree. Use cases: passive metadata chips (counts, IDs,
+     "Not set" states) where the badge should read as quiet chrome. */
+  :scope[variant="muted"],
+  :scope[variant="neutral"] {
+    --badge-bg: var(--a-bg-muted);
+    --badge-fg: var(--a-fg);
+  }
+
   /* Size handled by universal [size] attribute system. */
 }

package/components/badge/badge.js

@@ -6,7 +6,7 @@
  *
  * Inline badge / tag. Pill-shaped, text rendered via CSS attr().
  *
- * Variants: default, accent, info, success, warning, danger
+ * Variants: default, accent, info, success, warning, danger, primary, muted, neutral
  * Sizes: sm, md (default)
  * Icon: optional leading icon (any registered icon name; "dot" for legend
  *       markers). Inherits the variant's foreground color so legend chips

package/components/badge/badge.yaml

@@ -52,8 +52,6 @@ props:
       - warning
       - danger
       - primary
-      - soft
-      - outline
       - muted
       - neutral
 events: {}

package/components/calendar-picker/calendar-picker.css

@@ -180,6 +180,23 @@ calendar-picker-ui [slot="popover"] {
   font-family: inherit;
   font-size: var(--calendar-picker-font-size);
   color: var(--calendar-picker-popover-fg);
+  /* Fade + lift in on first paint via @starting-style. Same pattern
+     as menu/select/popover surfaces — see journal 2026-04-29 §18. */
+  opacity: 1;
+  translate: 0 0;
+  transition: opacity var(--a-duration-fast) var(--a-easing-out),
+              translate var(--a-duration-fast) var(--a-easing-out);
+}
+
+calendar-picker-ui [slot="popover"]:popover-open {
+  @starting-style {
+    opacity: 0;
+    translate: 0 -4px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  calendar-picker-ui [slot="popover"] { transition: none; }
 }
 
 /* Header row */

package/components/code/code.css

@@ -156,6 +156,47 @@
     color: inherit;
   }
 
+  /* ── Diff line states (static path) ──
+     Active when the block uses `language="diff"` (auto-parse +/- prefix)
+     or carries `data-line-states="..."` (explicit per-line). Each line is
+     a `[data-line-state]` row whose bg picks up the state token. The
+     CodeMirror path doesn't use these markers; line decorations there go
+     through CM extensions instead. */
+  > pre > code[data-line-state-mode] {
+    display: block;
+  }
+  > pre > code[data-line-state-mode] > [data-line-state] {
+    display: grid;
+    grid-template-columns: 1fr;
+    /* Bleed the row tint to the pre's padding edges so it reads as a
+       full-width line, not a gap-margined pill. */
+    margin-inline: calc(-1 * var(--code-px));
+    padding-inline: var(--code-px);
+  }
+  > pre > code[data-line-numbers] > [data-line-state] {
+    grid-template-columns: auto 1fr;
+    column-gap: var(--a-space-3);
+  }
+  > pre > code[data-line-state-mode] [data-line-num] {
+    color: var(--a-fg-subtle);
+    text-align: end;
+    user-select: none;
+    min-width: 1.5ch;
+  }
+  > pre > code[data-line-state-mode] [data-line-body] {
+    white-space: pre;
+  }
+  /* Empty lines still need height so the diff column counts line up. */
+  > pre > code[data-line-state-mode] [data-line-body]:empty::before {
+    content: " ";
+  }
+  > pre > code [data-line-state="added"] {
+    background: var(--a-success-muted);
+  }
+  > pre > code [data-line-state="removed"] {
+    background: var(--a-danger-muted);
+  }
+
   /* Footer — optional chrome band below the code block
      (line counts, byte size, language family, etc.) */
   > footer {

package/components/code/code.js

@@ -90,9 +90,12 @@ class AdiaCode extends AdiaElement {
     // Mount CodeMirror when the language is supported OR the element is
     // editable (editable plain-text is still useful). Inline instances
     // stay on the static <code> path. Mount failures leave the static
-    // fallback in place — it's already visible.
+    // fallback in place — it's already visible. Diff line-state mode
+    // (auto via `language="diff"` or explicit `data-line-states`) also
+    // stays on the static path — bg tinting lives on the wrapper spans.
     const lang = canonicalLanguage(this.language);
-    const shouldMount = !this.inline && (SUPPORTED_LANGUAGES.has(lang) || this.editable);
+    const useLineState = this.hasAttribute('data-line-states') || lang === 'diff';
+    const shouldMount = !this.inline && !useLineState && (SUPPORTED_LANGUAGES.has(lang) || this.editable);
     if (shouldMount) {
       this.#mountEditor();
     }
@@ -145,7 +148,45 @@ class AdiaCode extends AdiaElement {
     // Pre > Code — direct semantic elements, no slot attr
     const pre = document.createElement('pre');
     const code = document.createElement('code');
-    code.textContent = raw;
+
+    // Diff line-state mode — wrap each line so it can carry a state-driven
+    // bg tint and (when [line-numbers]) a leading line-number gutter.
+    // Triggered by `language="diff"` (auto-parses +/- prefix) or by an
+    // explicit `data-line-states` CSV that maps positionally onto lines.
+    const lang = canonicalLanguage(this.language);
+    const explicit = this.getAttribute('data-line-states');
+    const useLineState = explicit != null || lang === 'diff';
+    if (useLineState) {
+      code.setAttribute('data-line-state-mode', '');
+      if (this.lineNumbers) code.setAttribute('data-line-numbers', '');
+      const states = explicit?.split(',').map((s) => s.trim()) ?? null;
+      const lines = raw.split('\n');
+      lines.forEach((line, i) => {
+        let state = 'unchanged';
+        if (states && states[i]) {
+          state = states[i];
+        } else if (lang === 'diff') {
+          const head = line.charAt(0);
+          if (head === '+') state = 'added';
+          else if (head === '-') state = 'removed';
+        }
+        const row = document.createElement('span');
+        row.setAttribute('data-line-state', state);
+        if (this.lineNumbers) {
+          const num = document.createElement('span');
+          num.setAttribute('data-line-num', '');
+          num.textContent = String(i + 1);
+          row.appendChild(num);
+        }
+        const body = document.createElement('span');
+        body.setAttribute('data-line-body', '');
+        body.textContent = line;
+        row.appendChild(body);
+        code.appendChild(row);
+      });
+    } else {
+      code.textContent = raw;
+    }
     pre.appendChild(code);
 
     this.appendChild(pre);

package/components/empty-state/empty-state.js

@@ -24,10 +24,15 @@ class AdiaEmptyState extends AdiaElement {
   #headingEl = null;
   #descEl = null;
 
+  // Mark slot elements we create so render() never overrides consumer-provided ones.
+  // See ADR-0010 (slot content is source of truth).
+  #stampMark(el) { el.dataset.emptyStateStamped = '1'; return el; }
+  #wasStamped(el) { return el?.dataset?.emptyStateStamped === '1'; }
+
   connected() {
     this.#iconEl = this.querySelector(':scope > [slot="icon"]');
     if (!this.#iconEl) {
-      this.#iconEl = document.createElement('icon-ui');
+      this.#iconEl = this.#stampMark(document.createElement('icon-ui'));
       this.#iconEl.setAttribute('slot', 'icon');
       this.#iconEl.setAttribute('size', 'lg');
       this.insertBefore(this.#iconEl, this.firstChild);
@@ -35,14 +40,14 @@ class AdiaEmptyState extends AdiaElement {
 
     this.#headingEl = this.querySelector(':scope > [slot="heading"]');
     if (!this.#headingEl) {
-      this.#headingEl = document.createElement('span');
+      this.#headingEl = this.#stampMark(document.createElement('span'));
       this.#headingEl.setAttribute('slot', 'heading');
       this.insertBefore(this.#headingEl, this.querySelector('[slot="action"]'));
     }
 
     this.#descEl = this.querySelector(':scope > [slot="description"]');
     if (!this.#descEl) {
-      this.#descEl = document.createElement('span');
+      this.#descEl = this.#stampMark(document.createElement('span'));
       this.#descEl.setAttribute('slot', 'description');
       this.insertBefore(this.#descEl, this.querySelector('[slot="action"]'));
     }
@@ -51,28 +56,34 @@ class AdiaEmptyState extends AdiaElement {
   render() {
     if (!this.#iconEl) return;
 
-    // Icon
-    if (this.icon) {
-      this.#iconEl.setAttribute('name', this.icon);
-      this.#iconEl.hidden = false;
-    } else {
-      this.#iconEl.hidden = true;
+    // Icon — only mutate stamped elements; visibility follows the source of truth.
+    if (this.#wasStamped(this.#iconEl)) {
+      if (this.icon) {
+        this.#iconEl.setAttribute('name', this.icon);
+        this.#iconEl.hidden = false;
+      } else {
+        this.#iconEl.hidden = true;
+      }
     }
 
-    // Heading
-    if (this.heading) {
-      this.#headingEl.textContent = this.heading;
-      this.#headingEl.hidden = false;
-    } else {
-      this.#headingEl.hidden = true;
+    // Heading — same policy.
+    if (this.#wasStamped(this.#headingEl)) {
+      if (this.heading) {
+        this.#headingEl.textContent = this.heading;
+        this.#headingEl.hidden = false;
+      } else {
+        this.#headingEl.hidden = true;
+      }
     }
 
-    // Description
-    if (this.description) {
-      this.#descEl.textContent = this.description;
-      this.#descEl.hidden = false;
-    } else {
-      this.#descEl.hidden = true;
+    // Description — same policy.
+    if (this.#wasStamped(this.#descEl)) {
+      if (this.description) {
+        this.#descEl.textContent = this.description;
+        this.#descEl.hidden = false;
+      } else {
+        this.#descEl.hidden = true;
+      }
     }
   }
 

package/components/list/list.js

@@ -161,15 +161,19 @@ class AdiaListItem extends AdiaElement {
     return null;
   }
 
+  // Mark slot elements we create so render() never deletes consumer-provided ones.
+  #stampMark(el) { el.dataset.listStamped = '1'; return el; }
+  #wasStamped(el) { return el?.dataset?.listStamped === '1'; }
+
   #stamp() {
     if (this.#ownChild('[slot="content"]')) return;
 
     if (this.icon) {
       let iconEl = this.#ownChild('[slot="icon"]') || this.#ownChild('icon-ui');
       if (!iconEl) {
-        iconEl = document.createElement('icon-ui');
+        iconEl = this.#stampMark(document.createElement('icon-ui'));
         iconEl.setAttribute('slot', 'icon');
-        this.appendChild(iconEl);
+        this.prepend(iconEl);
       }
       iconEl.setAttribute('name', this.icon);
     }
@@ -177,56 +181,56 @@ class AdiaListItem extends AdiaElement {
     if (this.text) {
       let span = this.#ownChild('[slot="text"]');
       if (!span) {
-        span = document.createElement('span');
+        span = this.#stampMark(document.createElement('span'));
         span.setAttribute('slot', 'text');
         this.appendChild(span);
       }
-      span.textContent = this.text;
+      if (this.#wasStamped(span)) span.textContent = this.text;
     }
 
     if (this.description) {
       let desc = this.#ownChild('[slot="description"]');
       if (!desc) {
-        desc = document.createElement('span');
+        desc = this.#stampMark(document.createElement('span'));
         desc.setAttribute('slot', 'description');
         this.appendChild(desc);
       }
-      desc.textContent = this.description;
+      if (this.#wasStamped(desc)) desc.textContent = this.description;
     }
   }
 
   render() {
-    // Sync icon
+    // Sync icon — only touch elements we stamped.
     const iconEl = this.#ownChild('[slot="icon"]');
     if (this.icon) {
       if (iconEl) {
-        iconEl.setAttribute('name', this.icon);
+        if (this.#wasStamped(iconEl)) iconEl.setAttribute('name', this.icon);
       } else {
-        const el = document.createElement('icon-ui');
+        const el = this.#stampMark(document.createElement('icon-ui'));
         el.setAttribute('slot', 'icon');
         el.setAttribute('name', this.icon);
         this.prepend(el);
       }
-    } else if (iconEl) {
+    } else if (this.#wasStamped(iconEl)) {
       iconEl.remove();
     }
 
-    // Sync text
+    // Sync text — only touch elements we stamped.
     const textEl = this.#ownChild('[slot="text"]');
-    if (textEl) textEl.textContent = this.text;
+    if (this.#wasStamped(textEl)) textEl.textContent = this.text;
 
-    // Sync description
+    // Sync description — only touch elements we stamped.
     const descEl = this.#ownChild('[slot="description"]');
     if (this.description) {
       if (descEl) {
-        descEl.textContent = this.description;
+        if (this.#wasStamped(descEl)) descEl.textContent = this.description;
       } else {
-        const el = document.createElement('span');
+        const el = this.#stampMark(document.createElement('span'));
         el.setAttribute('slot', 'description');
         el.textContent = this.description;
         this.appendChild(el);
       }
-    } else if (descEl) {
+    } else if (this.#wasStamped(descEl)) {
       descEl.remove();
     }
   }