@adia-ai/web-components 0.8.4 → 0.8.5

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

@@ -232,14 +232,22 @@ calendar-picker-ui [data-cal-title] {
   color: var(--calendar-picker-title-fg);
 }
 
-calendar-picker-ui [data-cal-prev],
-calendar-picker-ui [data-cal-next] {
+/* Stamped <button-ui variant="ghost" size="xs" icon="caret-…"> (gh issue 276
+   wave 4) — icon-only (no [text], no child text) so button-ui's own
+   [data-icon-only] rule already squares it to --button-height; pointing
+   --button-height at the nav size (not just literal height below) avoids
+   the min-width/min-height floor trap. Literal background/color below
+   out-specify button.css's own via the `button-ui` type-selector bump
+   (same technique as swiper's dots). */
+calendar-picker-ui button-ui[data-cal-prev],
+calendar-picker-ui button-ui[data-cal-next] {
+  --button-height: var(--calendar-picker-nav-size);
+  --a-icon-size: var(--calendar-picker-nav-icon-size);
+
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: var(--calendar-picker-nav-size);
   height: var(--calendar-picker-nav-size);
-  padding: 0;
   border: none;
   border-radius: var(--calendar-picker-nav-radius);
   background: var(--calendar-picker-nav-bg);
@@ -248,10 +256,9 @@ calendar-picker-ui [data-cal-next] {
   transition:
     background var(--calendar-picker-duration) var(--calendar-picker-easing),
     color var(--calendar-picker-duration) var(--calendar-picker-easing);
-  --a-icon-size: var(--calendar-picker-nav-icon-size);
 }
-calendar-picker-ui [data-cal-prev]:hover,
-calendar-picker-ui [data-cal-next]:hover {
+calendar-picker-ui button-ui[data-cal-prev]:hover,
+calendar-picker-ui button-ui[data-cal-next]:hover {
   background: var(--calendar-picker-nav-bg-hover);
   color: var(--calendar-picker-nav-fg-hover);
 }
@@ -281,8 +288,18 @@ calendar-picker-ui [data-cal-grid] {
   gap: var(--calendar-picker-day-grid-gap);
 }
 
-/* Day buttons */
-calendar-picker-ui [data-cal-day] {
+/* Day buttons — stamped <button-ui variant="ghost" text="…"> (gh issue 276
+   wave 4). button-ui floors min-width/min-height at --button-height — point
+   it at the day-cell size (not just the literal width/height below) so the
+   floor never clamps a smaller [size] tier. The literal geometry/color
+   declarations below out-specify button-ui's own equivalents via the
+   `button-ui` type-selector bump (same technique as swiper's dots).
+   button-ui renders its label via `::after { content: attr(text) }` — the
+   today-indicator dot below therefore uses `::before` (kept free), not
+   `::after`, to avoid the two fighting over the same pseudo-element. */
+calendar-picker-ui button-ui[data-cal-day] {
+  --button-height: var(--calendar-picker-day-size);
+
   display: flex;
   align-items: center;
   justify-content: center;
@@ -304,25 +321,25 @@ calendar-picker-ui [data-cal-day] {
 }
 
 /* ── State: hover ── */
-calendar-picker-ui [data-cal-day]:not([disabled]):not([data-outside]):hover {
+calendar-picker-ui button-ui[data-cal-day]:not([disabled]):not([data-outside]):hover {
   background: var(--calendar-picker-day-bg-hover);
   color: var(--calendar-picker-day-fg-hover);
 }
 
 /* ── State: focus ── */
-calendar-picker-ui [data-cal-day]:not([disabled]):not([data-outside]):focus-visible,
-calendar-picker-ui [data-cal-day][data-focused] {
+calendar-picker-ui button-ui[data-cal-day]:not([disabled]):not([data-outside]):focus-visible,
+calendar-picker-ui button-ui[data-cal-day][data-focused] {
   outline: none;
   box-shadow: var(--calendar-picker-day-focus-ring);
 }
 
 /* ── State: selected ── */
-calendar-picker-ui [data-cal-day][data-selected] {
+calendar-picker-ui button-ui[data-cal-day][data-selected] {
   background: var(--calendar-picker-day-bg-selected);
   color: var(--calendar-picker-day-fg-selected);
   font-weight: var(--calendar-picker-selected-weight);
 }
-calendar-picker-ui [data-cal-day][data-selected]:not([disabled]):hover {
+calendar-picker-ui button-ui[data-cal-day][data-selected]:not([disabled]):hover {
   background: var(--calendar-picker-day-bg-selected-hover);
   color: var(--calendar-picker-day-fg-selected);
 }
@@ -330,12 +347,12 @@ calendar-picker-ui [data-cal-day][data-selected]:not([disabled]):hover {
 /* ── State: today (unselected) ──
    Use a small bottom dot so it does not compete with the rounded
    focus-ring box-shadow (that looked like a double outline). */
-calendar-picker-ui [data-cal-day][data-today]:not([data-selected]) {
+calendar-picker-ui button-ui[data-cal-day][data-today]:not([data-selected]) {
   position: relative;
   color: var(--calendar-picker-day-today-border);
   font-weight: var(--calendar-picker-today-weight);
 }
-calendar-picker-ui [data-cal-day][data-today]:not([data-selected])::after {
+calendar-picker-ui button-ui[data-cal-day][data-today]:not([data-selected])::before {
   content: "";
   position: absolute;
   left: 50%;
@@ -349,13 +366,16 @@ calendar-picker-ui [data-cal-day][data-today]:not([data-selected])::after {
 }
 
 /* ── State: outside month ── */
-calendar-picker-ui [data-cal-day][data-outside] {
+calendar-picker-ui button-ui[data-cal-day][data-outside] {
   color: var(--calendar-picker-day-fg-outside);
   cursor: default;
 }
 
-/* ── State: disabled ── */
-calendar-picker-ui [data-cal-day]:disabled:not([data-outside]) {
+/* ── State: disabled ──
+   `[disabled]` — NOT the `:disabled` pseudo-class, which only matches
+   native form controls; button-ui is a custom element, so `:disabled`
+   silently never matches it. */
+calendar-picker-ui button-ui[data-cal-day][disabled]:not([data-outside]) {
   color: var(--calendar-picker-day-fg-disabled);
   cursor: not-allowed;
 }

package/components/calendar-picker/calendar-picker.yaml

@@ -11,6 +11,11 @@ description: >-
   supports min/max and disabled-date masks. Use for single-date input in
   forms; for date ranges compose two pickers or use a dedicated range
   component.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# in their render() do NOT auto-import them. Consumer (or demo shell) must
+# explicitly import each composed primitive.
+composes:
+  - button-ui  # day cells + month nav (gh issue 276 wave 4)
 props:
   name:
     description: Form field name

package/components/chart/chart.class.js

@@ -341,21 +341,24 @@ export class UIChart extends UIElement {
     this.addEventListener('pointerdown',  this.#onPointerDown);
     this.addEventListener('click',        this.#onClick);
 
-    this.#resizeObs = new ResizeObserver((entries) => {
-      const { inlineSize: w, blockSize: h } = entries[0].contentBoxSize[0];
-      if (!this.#data.length) return;
-      const rw = Math.round(w);
-      const rh = Math.round(h);
-      if (rw === this.#lastW && (!this.hasAttribute('resize') || rh === this.#lastH)) return;
-      this.#lastW = rw;
-      this.#lastH = rh;
-      if (this.#resizeRaf) return;
-      this.#resizeRaf = requestAnimationFrame(() => {
-        this.#resizeRaf = null;
-        this.#renderChart();
+    // gh#285 — SSR DOM shims (linkedom) have no ResizeObserver global.
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#resizeObs = new ResizeObserver((entries) => {
+        const { inlineSize: w, blockSize: h } = entries[0].contentBoxSize[0];
+        if (!this.#data.length) return;
+        const rw = Math.round(w);
+        const rh = Math.round(h);
+        if (rw === this.#lastW && (!this.hasAttribute('resize') || rh === this.#lastH)) return;
+        this.#lastW = rw;
+        this.#lastH = rh;
+        if (this.#resizeRaf) return;
+        this.#resizeRaf = requestAnimationFrame(() => {
+          this.#resizeRaf = null;
+          this.#renderChart();
+        });
       });
-    });
-    this.#resizeObs.observe(this);
+      this.#resizeObs.observe(this);
+    }
   }
 
   render() {

package/components/color-input/color-input.class.js

@@ -169,11 +169,14 @@ export class UIColorInput extends UIFormElement {
     // Store the observer in a #field so disconnected() can clean it up
     // — without the explicit reference, the observer survives the host
     // element across mount/unmount cycles (audit-lifecycle-leak).
-    this.#popoverObserver = new MutationObserver(sync);
-    this.#popoverObserver.observe(this.#popover, {
-      attributes: true,
-      attributeFilter: ['open'],
-    });
+    // gh#285 — SSR DOM shims (linkedom) have no MutationObserver global.
+    if (typeof MutationObserver !== 'undefined') {
+      this.#popoverObserver = new MutationObserver(sync);
+      this.#popoverObserver.observe(this.#popover, {
+        attributes: true,
+        attributeFilter: ['open'],
+      });
+    }
   }
 
   #onPickerChange = (e) => {

package/components/color-picker/color-picker.class.js

@@ -362,9 +362,12 @@ export class UIColorPicker extends UIFormElement {
 
     this.#hueTrack.addEventListener('keydown', this.#onHueKeydown);
 
-    // Observe area resize to redraw canvas
-    this.#areaResizeObs = new ResizeObserver(() => this.#drawArea());
-    this.#areaResizeObs.observe(this.#areaEl);
+    // Observe area resize to redraw canvas.
+    // gh#285 — SSR DOM shims (linkedom) have no ResizeObserver global.
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#areaResizeObs = new ResizeObserver(() => this.#drawArea());
+      this.#areaResizeObs.observe(this.#areaEl);
+    }
   }
 
   disconnected() {

package/components/field/field.class.js

@@ -95,13 +95,16 @@ export class UIField extends UIElement {
     this.#bindForToControl();
     this.#bindErrorListener();
     this.#labelEl?.addEventListener('click', this.#onLabelClick);
-    this.#mo = new MutationObserver(() => {
-      this.#bindForToControl();
-      this.#bindErrorListener();
-      this.#wireAriaDescribedBy();
-      this.#syncErrorMessage();
-    });
-    this.#mo.observe(this, { childList: true });
+    // gh#285 — SSR DOM shims (linkedom) have no MutationObserver global.
+    if (typeof MutationObserver !== 'undefined') {
+      this.#mo = new MutationObserver(() => {
+        this.#bindForToControl();
+        this.#bindErrorListener();
+        this.#wireAriaDescribedBy();
+        this.#syncErrorMessage();
+      });
+      this.#mo.observe(this, { childList: true });
+    }
     this.#syncErrorMessage();
   }
 

package/components/fields/fields.class.js

@@ -51,19 +51,22 @@ export class UIFields extends UIElement {
 
   connected() {
     this.#syncInline();
-    this.#mo = new MutationObserver((records) => {
-      // Only re-sync on childList changes that involve direct <field-ui>
-      // children — attribute mutations on grandchildren aren't ours to
-      // care about.
-      for (const r of records) {
-        if (r.type !== 'childList') continue;
-        if (this.#hasFieldChild(r.addedNodes) || this.#hasFieldChild(r.removedNodes)) {
-          this.#syncInline();
-          return;
+    // gh#285 — SSR DOM shims (linkedom) have no MutationObserver global.
+    if (typeof MutationObserver !== 'undefined') {
+      this.#mo = new MutationObserver((records) => {
+        // Only re-sync on childList changes that involve direct <field-ui>
+        // children — attribute mutations on grandchildren aren't ours to
+        // care about.
+        for (const r of records) {
+          if (r.type !== 'childList') continue;
+          if (this.#hasFieldChild(r.addedNodes) || this.#hasFieldChild(r.removedNodes)) {
+            this.#syncInline();
+            return;
+          }
         }
-      }
-    });
-    this.#mo.observe(this, { childList: true });
+      });
+      this.#mo.observe(this, { childList: true });
+    }
   }
 
   disconnected() {

package/components/icon/icon.class.js

@@ -30,13 +30,17 @@ function warnIfIconRegistryUnwired() {
     // eslint-disable-next-line no-console
     console.error(
       `[icon-ui] No icons are registered and no icon loaders were installed — every <icon-ui> renders blank.\n` +
-      `  The zero-config import.meta.glob path does not work from inside a published dependency under Vite 8 / rolldown.\n` +
-      `  Fix — from your APP entry (where import.meta.glob is transformed):\n` +
+      `  Two known causes (gh#287): (1) Vite's dev-server optimizeDeps pre-bundled this package, which empties\n` +
+      `  the auto-discovery glob — add to your Vite config:\n` +
+      `    optimizeDeps: { exclude: ['@adia-ai/web-components', '@adia-ai/web-modules'] }\n` +
+      `  (2) @phosphor-icons/core is missing or this file was re-nested by a packaging step (Yarn PnP, a custom\n` +
+      `  bundler). If neither applies, install loaders manually with plain imports from your APP entry:\n` +
       `    npm i @phosphor-icons/core\n` +
       `    import { installIconLoaders } from '@adia-ai/web-components/core/icons';\n` +
-      `    installIconLoaders({ regular: import.meta.glob(\n` +
-      `      '/node_modules/@phosphor-icons/core/assets/regular/*.svg',\n` +
-      `      { query: '?raw', import: 'default', eager: true }) });\n` +
+      `    import caretRight from '@phosphor-icons/core/assets/regular/caret-right.svg?raw';\n` +
+      `    installIconLoaders({ regular: {\n` +
+      `      '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': caretRight,\n` +
+      `    } });\n` +
       `  See USAGE.md § Icons.`,
     );
   }, 0);

package/components/index.js

@@ -58,6 +58,7 @@ export { UISwiper } from './swiper/swiper.js';
 export { UIUpload } from './upload/upload.js';
 export { UICard } from './card/card.js';
 export { UIAvatar, UIAvatarGroup } from './avatar/avatar.js';
+export { UIAdiaMark } from './adia-mark/adia-mark.js';
 export { UIProgress } from './progress/progress.js';
 export { UIStepProgress } from './step-progress/step-progress.js';
 export { UISkeleton } from './skeleton/skeleton.js';

package/components/nav/nav.class.js

@@ -61,7 +61,8 @@ export class UINav extends UIElement {
     this.addEventListener('click', this.#onClick);
 
     // ResizeObserver only meaningful for primary variant — section is static.
-    if (this.variant !== 'section') {
+    // gh#285 — SSR DOM shims (linkedom) have no ResizeObserver global.
+    if (this.variant !== 'section' && typeof ResizeObserver !== 'undefined') {
       this.#ro = new ResizeObserver(() => this.#updateTooltips());
       this.#ro.observe(this);
     }

package/components/noodles/noodles.class.js

@@ -108,19 +108,23 @@ export class UINoodles extends UIElement {
     this.#svg.setAttribute('data-noodle-svg', '');
     this.prepend(this.#svg);
 
-    // Observers for child layout changes
-    this.#resizeObs = new ResizeObserver(() => this.#scheduleUpdate());
-    this.#mutationObs = new MutationObserver(() => {
-      this.#rebuildPortIndicators();
-      this.#scheduleUpdate();
-    });
-
-    this.#resizeObs.observe(this);
+    // Observers for child layout changes.
+    // gh#285 — SSR DOM shims (linkedom) have neither observer global.
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#resizeObs = new ResizeObserver(() => this.#scheduleUpdate());
+      this.#resizeObs.observe(this);
+    }
+    if (typeof MutationObserver !== 'undefined') {
+      this.#mutationObs = new MutationObserver(() => {
+        this.#rebuildPortIndicators();
+        this.#scheduleUpdate();
+      });
+    }
     this.#observeMutations();
 
     // Observe each port-bearing child
     for (const child of this.#getPortChildren()) {
-      this.#resizeObs.observe(child);
+      this.#resizeObs?.observe(child);
     }
 
     this.#rebuildPortIndicators();
@@ -181,7 +185,7 @@ export class UINoodles extends UIElement {
     // Sync resize observer with current port children
     const portChildren = this.#getPortChildren();
     for (const child of portChildren) {
-      this.#resizeObs.observe(child);
+      this.#resizeObs?.observe(child);
     }
 
     // Update port indicator positions

package/components/page/page.class.js

@@ -78,13 +78,14 @@ export class UIPage extends UIElement {
       header.insertAdjacentElement('beforebegin', this.#sentinel);
     }
 
-    if (!this.#observer) {
+    // gh#285 — SSR DOM shims (linkedom) have no IntersectionObserver global.
+    if (!this.#observer && typeof IntersectionObserver !== 'undefined') {
       this.#observer = new IntersectionObserver((entries) => {
         this.toggleAttribute('data-header-stuck', !entries[0].isIntersecting);
       }, { threshold: 0 });
     }
 
-    this.#observer.observe(this.#sentinel);
+    this.#observer?.observe(this.#sentinel);
   }
 
   #teardownSticky() {

package/components/select/select.class.js

@@ -381,7 +381,8 @@ export class UISelect extends UIFormElement {
     // options are already parsed/set, and skip unless there's a real
     // <option>/<optgroup> to parse — so the component's own listbox/empty-state
     // renders (and #parseOptions's own option removals) don't re-enter or loop.
-    if (!this.#optionObserver) {
+    // gh#285 — SSR DOM shims (linkedom) have no MutationObserver global.
+    if (!this.#optionObserver && typeof MutationObserver !== 'undefined') {
       this.#optionObserver = new MutationObserver(() => {
         if (this.#options.length) return;
         const kids = this.#logicalOptionChildren();
@@ -394,7 +395,7 @@ export class UISelect extends UIFormElement {
         }
       });
     }
-    this.#optionObserver.observe(this, { childList: true, subtree: true });
+    this.#optionObserver?.observe(this, { childList: true, subtree: true });
   }
 
   render() {

package/components/swatch/swatch.class.js

@@ -208,31 +208,34 @@ export class UISwatch extends UIElement {
     // the canonical post-tile region. MutationObserver closes this gap for
     // every arrival path: single-template ordering skew, separate render
     // cycle, or imperative host.appendChild().
-    this.#chromeObserver = new MutationObserver((mutations) => {
-      let hasChrome = false;
-      for (const m of mutations) {
-        for (const n of m.addedNodes) {
-          if (n.nodeType !== 1) continue;
-          // Direct chrome child OR a display:contents wrapper-span carrying chrome.
-          if (n.getAttribute?.('slot') === 'chrome') { hasChrome = true; break; }
-          if (
-            n.tagName === 'SPAN' &&
-            n.style?.display === 'contents' &&
-            n.querySelector?.('[slot="chrome"]')
-          ) { hasChrome = true; break; }
+    // gh#285 — SSR DOM shims (linkedom) have no MutationObserver global.
+    if (typeof MutationObserver !== 'undefined') {
+      this.#chromeObserver = new MutationObserver((mutations) => {
+        let hasChrome = false;
+        for (const m of mutations) {
+          for (const n of m.addedNodes) {
+            if (n.nodeType !== 1) continue;
+            // Direct chrome child OR a display:contents wrapper-span carrying chrome.
+            if (n.getAttribute?.('slot') === 'chrome') { hasChrome = true; break; }
+            if (
+              n.tagName === 'SPAN' &&
+              n.style?.display === 'contents' &&
+              n.querySelector?.('[slot="chrome"]')
+            ) { hasChrome = true; break; }
+          }
+          if (hasChrome) break;
         }
-        if (hasChrome) break;
-      }
-      if (!hasChrome) return;
-      // Re-entrancy guard: #absorbChromeSlot() calls insertBefore() which itself
-      // generates childList mutations on the host. Without this guard, every
-      // absorb pass would re-trigger the observer indefinitely. takeRecords()
-      // drains the queue without dispatch so the next observation cycle starts
-      // clean.
-      this.#absorbChromeSlot();
-      this.#chromeObserver.takeRecords();
-    });
-    this.#chromeObserver.observe(this, { childList: true });
+        if (!hasChrome) return;
+        // Re-entrancy guard: #absorbChromeSlot() calls insertBefore() which itself
+        // generates childList mutations on the host. Without this guard, every
+        // absorb pass would re-trigger the observer indefinitely. takeRecords()
+        // drains the queue without dispatch so the next observation cycle starts
+        // clean.
+        this.#absorbChromeSlot();
+        this.#chromeObserver.takeRecords();
+      });
+      this.#chromeObserver.observe(this, { childList: true });
+    }
   }
 
   render() {

package/components/swiper/swiper.class.js

@@ -436,7 +436,10 @@ export class UISwiper extends UIElement {
     if (dots.children.length !== desired) {
       while (dots.firstChild) dots.removeChild(dots.firstChild);
       for (let i = 0; i < desired; i++) {
-        const dot = document.createElement('button');
+        // button-ui, not a native <button> (gh issue 276 wave 4) — it
+        // respects the consumer-set role, so the tab semantics survive.
+        const dot = document.createElement('button-ui');
+        dot.setAttribute('variant', 'ghost');
         dot.setAttribute('role', 'tab');
         dot.setAttribute('aria-label', `Page ${i + 1}`);
         dot.addEventListener('click', () => this.goTo(this.#pageToSlideIndex(i)));

package/components/swiper/swiper.css

@@ -191,7 +191,16 @@
      `--swiper-dot-size` for idle dots and `--swiper-dot-size-active`
      for the active one (one space token larger). Padding is computed
      from the size so the dot stays centered in the hitbox. */
-  :scope [data-swiper-dots] > button {
+  :scope [data-swiper-dots] > button-ui {
+    /* Stamped <button-ui variant="ghost" role="tab"> (gh issue 276 wave 4).
+       The dot look is bespoke (content-box clip keeps a 1rem hitbox around
+       a --swiper-dot-size circle) — these host declarations out-specify
+       button-ui's token-driven chrome; the ghost variant keeps its own
+       hover fill out of the way. */
+    /* button-ui floors min-width/height at --button-height — point it at
+       the VISIBLE circle so the padding (not the min-floor) builds the
+       1rem hitbox, exactly like the native dot did. */
+    --button-height: var(--swiper-dot-size);
     width: var(--swiper-dot-size);
     height: var(--swiper-dot-size);
     border-radius: var(--swiper-dot-radius);
@@ -208,18 +217,18 @@
      `background-clip: content-box` from the base rule isn't reset to
      its initial `border-box` value — the colored area would otherwise
      fill the full 1rem hitbox and turn into a huge circle. */
-  :scope [data-swiper-dots] > button:hover {
+  :scope [data-swiper-dots] > button-ui:hover {
     background-color: var(--swiper-dot-bg-active);
   }
 
   /* Focus ring is rendered INSIDE the padding area (inset shadow), so
      the dot's visual footprint stays the size of every other dot. */
-  :scope [data-swiper-dots] > button:focus-visible {
+  :scope [data-swiper-dots] > button-ui:focus-visible {
     outline: none;
     box-shadow: inset 0 0 0 var(--a-focus-width) var(--a-focus-color);
   }
 
-  :scope [data-swiper-dots] > button[aria-current="true"] {
+  :scope [data-swiper-dots] > button-ui[aria-current="true"] {
     background-color: var(--swiper-dot-bg-active);
     width: var(--swiper-dot-size-active);
     height: var(--swiper-dot-size-active);

package/components/toolbar/toolbar.class.js

@@ -114,12 +114,17 @@ export class UIToolbar extends UIElement {
   connected() {
     this.setAttribute('role', 'toolbar');
     this.#ensureSpillover();
-    this.#ro = new ResizeObserver(() => this.#queueReflow());
-    this.#ro.observe(this);
-    this.#mo = new MutationObserver(() => {
-      if (this.#measuring) return;
-      this.#queueReflow();
-    });
+    // gh#285 — SSR DOM shims (linkedom) have neither observer global.
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#ro = new ResizeObserver(() => this.#queueReflow());
+      this.#ro.observe(this);
+    }
+    if (typeof MutationObserver !== 'undefined') {
+      this.#mo = new MutationObserver(() => {
+        if (this.#measuring) return;
+        this.#queueReflow();
+      });
+    }
     this.#moObserve();
     this.#queueReflow();
   }

package/components/tree/tree.class.js

@@ -324,8 +324,11 @@ export class UITreeItem extends UIElement {
     // role=button child of the group/tree (axe `aria-required-children`). Adopt
     // what's present now, then observe for the late arrivals.
     this.#adoptSlotted();
-    this.#slotObserver = new MutationObserver(() => this.#adoptSlotted());
-    this.#slotObserver.observe(this, { childList: true, subtree: true });
+    // gh#285 — SSR DOM shims (linkedom) have no MutationObserver global.
+    if (typeof MutationObserver !== 'undefined') {
+      this.#slotObserver = new MutationObserver(() => this.#adoptSlotted());
+      this.#slotObserver.observe(this, { childList: true, subtree: true });
+    }
   }
 
   #stamp() {

package/core/data-stream.js

@@ -453,24 +453,30 @@ function visitSubtree(root, 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));
-    }
-  }
-});
+// gh#285 — SSR DOM shims (linkedom) have no MutationObserver global.
+// Constructed lazily so import-time evaluation never throws; bootstrap()
+// no-ops the document-level watch when the global is missing (existing
+// stream elements found via querySelectorAll still get started once).
+const observer = typeof MutationObserver !== 'undefined'
+  ? 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));
+        }
+      }
+    })
+  : null;
 
 function bootstrap() {
   if (typeof document === 'undefined') return;
-  observer.observe(document.documentElement, {
+  observer?.observe(document.documentElement, {
     childList: true, subtree: true,
     attributes: true, attributeFilter: ATTR_FILTER,
   });