@webjsdev/ui 0.3.6 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "type": "module",
   "description": "An AI-first component library - class-helper functions for visuals, custom elements only where state matters. Source-copied into your repo, you own it. Works with any Tailwind v4 project.",
   "bin": {
@@ -19,7 +19,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "test:e2e:touch": "node test/e2e/touch.e2e.mjs"
   },
   "dependencies": {
     "commander": "^14.0.0",

package/packages/registry/components/alert-dialog.ts

@@ -66,6 +66,7 @@
 import { WebComponent, html, prop } from '@webjsdev/core';
 import { ref, createRef } from '@webjsdev/core/directives';
 import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { buttonClass, type ButtonVariant, type ButtonSize } from './button.ts';
 
 export const alertDialogContentClass = (): string =>
@@ -87,7 +88,10 @@ ui-alert-dialog:not([open]) ui-alert-dialog-content { display: none !important;
 ui-alert-dialog-content { display: grid; }
 `;
 
-const NATIVE_DIALOG_CLASS = 'border-0 bg-transparent p-0 m-0 w-0 h-0 max-w-none max-h-none overflow-visible text-inherit backdrop:bg-black/50';
+// Fills the viewport (fixed inset-0), NOT 0x0 (#730): WebKit makes a
+// top-layer <dialog> the containing block for its position:fixed descendants,
+// so a 0x0 host collapsed the fixed content panel to 0x0 (invisible on iOS).
+const NATIVE_DIALOG_CLASS = 'fixed inset-0 border-0 bg-transparent p-0 m-0 max-w-none max-h-none overflow-visible text-inherit backdrop:bg-black/50';
 
 function installStyles(): void {
   if (typeof document === 'undefined') return;
@@ -140,16 +144,22 @@ export class UiAlertDialog extends WebComponent({
     this.open = false;
   }
 
+  _disposeBeforeCache?: () => void;
+
   connectedCallback(): void {
     installStyles();
     // Legacy <ui-alert-dialog-overlay> isn't supported anymore; the native
     // ::backdrop pseudo replaces it. Strip it if a stale doc uses it.
     this.querySelector<HTMLElement>(':scope > ui-alert-dialog-overlay')?.remove();
     super.connectedCallback?.();
+    // Close before a back/forward snapshot: a modal restored half-open (the
+    // `open` attr without the native showModal top-layer state) is broken (#766).
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
   }
 
   disconnectedCallback(): void {
     if (this.open) this._teardown();
+    this._disposeBeforeCache?.();
     super.disconnectedCallback?.();
   }
 
@@ -234,9 +244,17 @@ export class UiAlertDialogContent extends WebComponent({
     this.size = 'default';
   }
 
+  // Query the native <dialog> rather than the #dialog ref: the ref's `.value`
+  // came back null on iOS WebKit (the binding did not populate through SSR
+  // hydration), so showModal() never ran (#730). querySelector is robust on
+  // every engine.
+  _native(): HTMLDialogElement | null {
+    return this.querySelector<HTMLDialogElement>('dialog[data-slot="alert-dialog-native"]');
+  }
+
   showModal(): void {
     this._wireLabels();
-    const native = this.#dialog.value;
+    const native = this._native();
     if (native && !native.open) native.showModal();
   }
 
@@ -263,7 +281,7 @@ export class UiAlertDialogContent extends WebComponent({
   }
 
   close(): void {
-    const native = this.#dialog.value;
+    const native = this._native();
     if (native?.open) native.close();
   }
 

package/packages/registry/components/dialog.ts

@@ -66,6 +66,7 @@
 import { WebComponent, html, unsafeHTML, prop } from '@webjsdev/core';
 import { ref, createRef } from '@webjsdev/core/directives';
 import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { buttonClass } from './button.ts';
 
 // Wires a dialog panel's accessible name + description to its title /
@@ -133,7 +134,16 @@ ui-dialog-content { display: grid; }
 // Clears the UA defaults on <dialog> so it becomes an invisible top-layer
 // host. The visible box is rendered by <ui-dialog-content>. The
 // backdrop: variant styles the ::backdrop pseudo-element.
-const NATIVE_DIALOG_CLASS = 'border-0 bg-transparent p-0 m-0 w-0 h-0 max-w-none max-h-none overflow-visible text-inherit backdrop:bg-black/50';
+//
+// The host FILLS THE VIEWPORT (fixed inset-0) rather than collapsing to
+// 0x0 (#730): WebKit makes a top-layer <dialog> the containing block for
+// its position:fixed descendants, so a 0x0 host collapsed the fixed content
+// panel (w-full) to 0x0 and the dialog was invisible on iOS (Blink resolves
+// the same fixed panel against the viewport, so it worked on Android). A
+// viewport-sized transparent host gives the panel a correct containing block
+// on both engines; the panel still centers itself and the ::backdrop covers
+// the screen.
+const NATIVE_DIALOG_CLASS = 'fixed inset-0 border-0 bg-transparent p-0 m-0 max-w-none max-h-none overflow-visible text-inherit backdrop:bg-black/50';
 
 function installStyles(): void {
   if (typeof document === 'undefined') return;
@@ -188,16 +198,22 @@ export class UiDialog extends WebComponent({
     this.open = false;
   }
 
+  _disposeBeforeCache?: () => void;
+
   connectedCallback(): void {
     installStyles();
     // Legacy <ui-dialog-overlay> isn't supported anymore; the native
     // ::backdrop pseudo replaces it. Strip it if a stale doc uses it.
     this.querySelector<HTMLElement>(':scope > ui-dialog-overlay')?.remove();
     super.connectedCallback?.();
+    // Close before a back/forward snapshot: a modal restored half-open (the
+    // `open` attr without the native showModal top-layer state) is broken (#766).
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
   }
 
   disconnectedCallback(): void {
     if (this.open) this._teardown();
+    this._disposeBeforeCache?.();
     super.disconnectedCallback?.();
   }
 
@@ -290,14 +306,23 @@ export class UiDialogContent extends WebComponent({
     this.showCloseButton = 'true';
   }
 
+  // Resolve the native <dialog> by query, NOT the #dialog ref: on iOS WebKit
+  // the ref's `.value` came back null (the ref binding did not populate through
+  // SSR hydration), so showModal() was never called and the dialog never opened
+  // (#730). A direct querySelector is robust on every engine, and matches what
+  // the tooltip / popover components already do.
+  _native(): HTMLDialogElement | null {
+    return this.querySelector<HTMLDialogElement>('dialog[data-slot="dialog-native"]');
+  }
+
   showModal(): void {
     wireDialogLabels(this, '[data-slot="dialog-content"]');
-    const native = this.#dialog.value;
+    const native = this._native();
     if (native && !native.open) native.showModal();
   }
 
   close(): void {
-    const native = this.#dialog.value;
+    const native = this._native();
     if (native?.open) native.close();
   }
 

package/packages/registry/components/dropdown-menu.ts

@@ -79,6 +79,7 @@
  */
 import { WebComponent, html, unsafeHTML, signal, prop } from '@webjsdev/core';
 import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // --------------------------------------------------------------------------
@@ -135,8 +136,11 @@ export class UiDropdownMenu extends WebComponent({
     this.open = false;
   }
 
+  _disposeBeforeCache?: () => void;
+
   disconnectedCallback(): void {
     if (this.open) this._teardown();
+    this._disposeBeforeCache?.();
     super.disconnectedCallback?.();
   }
 
@@ -165,6 +169,9 @@ export class UiDropdownMenu extends WebComponent({
     if (typeof requestAnimationFrame === 'function') {
       requestAnimationFrame(() => this._wireAria());
     }
+    // Close (and tear down) before a back/forward snapshot so the menu does not
+    // restore open (#766). Closing the root also hides any open submenu.
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
   }
 
   _afterRender(): void {
@@ -564,7 +571,13 @@ export class UiDropdownMenuSub extends WebComponent({
   }
 
   _cancelCloseHandler = (): void => this._cancelClose();
-  _scheduleCloseHandler = (): void => this._scheduleClose();
+  // Hover-close is a mouse affordance. On touch, lifting the finger fires
+  // pointerleave; without this guard a tap-opened submenu would close itself
+  // ~200ms after the tap. On touch the submenu stays open until tapped again.
+  _scheduleCloseHandler = (e: Event): void => {
+    if ((e as PointerEvent).pointerType === 'touch') return;
+    this._scheduleClose();
+  };
 
   _scheduleClose(): void {
     this._cancelClose();
@@ -635,6 +648,10 @@ export class UiDropdownMenuSubTrigger extends WebComponent({ inset: Boolean }) {
   };
 
   _onPointerEnter = (e: Event): void => {
+    // Hover-open is a mouse affordance. On touch there is no hover: a tap
+    // fires pointerenter on finger-down, which would open the submenu only for
+    // the following click to toggle it shut. On touch, @click is the opener.
+    if ((e as PointerEvent).pointerType === 'touch') return;
     const el = e.currentTarget as HTMLElement;
     if (el.hasAttribute('data-disabled')) return;
     el.focus();

package/packages/registry/components/hover-card.ts

@@ -40,6 +40,7 @@
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
 import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // `fixed m-0` opts out of the UA `[popover]` auto-centering margin so
@@ -70,6 +71,8 @@ export class UiHoverCard extends WebComponent({
     this.closeDelay = 300;
   }
 
+  _disposeBeforeCache?: () => void;
+
   connectedCallback(): void {
     super.connectedCallback?.();
     // webjs projects slotted light-DOM children after the first render, so
@@ -78,6 +81,14 @@ export class UiHoverCard extends WebComponent({
     if (typeof requestAnimationFrame === 'function') {
       requestAnimationFrame(() => this._wireAria());
     }
+    // Close before the page is cached for back/forward so a restored snapshot
+    // does not come back frozen open (#766).
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
+  }
+
+  disconnectedCallback(): void {
+    this._disposeBeforeCache?.();
+    super.disconnectedCallback?.();
   }
 
   // The trigger also opens on focus (see the @focusin handler), so it is
@@ -114,6 +125,25 @@ export class UiHoverCard extends WebComponent({
     this._hideTimer = window.setTimeout(() => { this.open = false; }, this.closeDelay);
   }
 
+  // Touch open: there is no hover delay and no mouseleave to close it, so open
+  // immediately and arm a one-shot outside-tap dismiss (a tap anywhere outside
+  // this card closes it). Deferred a tick so the opening tap itself does not
+  // immediately dismiss it.
+  openByTouch(): void {
+    clearTimeout(this._showTimer);
+    clearTimeout(this._hideTimer);
+    this.open = true;
+    const onOutside = (ev: Event): void => {
+      // Close on an outside tap; also self-remove if the card was already
+      // closed by other means (a re-tap toggle), so the listener never lingers.
+      if (!this.open || !this.contains(ev.target as Node)) {
+        this.open = false;
+        document.removeEventListener('pointerdown', onOutside, true);
+      }
+    };
+    setTimeout(() => document.addEventListener('pointerdown', onOutside, true), 0);
+  }
+
   render() {
     return html`<div
       data-slot="hover-card"
@@ -179,11 +209,41 @@ export class UiHoverCardTrigger extends WebComponent {
       @mouseleave=${this._onLeave}
       @focusin=${this._onEnter}
       @focusout=${this._onLeave}
+      @click=${this._onClick}
     ><slot></slot></div>`;
   }
 
-  _onEnter = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
-  _onLeave = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+  // Hover/focus open + close are MOUSE affordances. On a no-hover (touch)
+  // device, iOS Safari still fires SYNTHETIC mouseenter/mouseleave (and
+  // focusin/focusout from the inner link) around a tap, which would otherwise
+  // immediately re-close a tap-opened card. Gate the hover handlers to pointer
+  // devices so on touch the card is driven only by the tap path (#745).
+  _noHover = (): boolean => !!window.matchMedia?.('(hover: none)').matches;
+  _onEnter = (): void => {
+    if (this._noHover()) return;
+    (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
+  };
+  _onLeave = (): void => {
+    if (this._noHover()) return;
+    (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+  };
+
+  // Touch path. A touch device has no `mouseenter`, so a tap would fall through
+  // to the inner `<a href>` and navigate. On a no-hover device the trigger tap
+  // TOGGLES the card and NEVER navigates (the real link is reachable inside the
+  // opened card). It must ALWAYS preventDefault, including while open: the
+  // client router pushState()s on any bubble-phase `<a>` click that is not
+  // defaultPrevented, so a re-tap that fell through would push a history entry
+  // every time and Back would need N presses (#745).
+  _onClick = (e: Event): void => {
+    if (!window.matchMedia?.('(hover: none)').matches) return;
+    const card = this.closest('ui-hover-card') as UiHoverCard | null;
+    if (!card) return;
+    e.preventDefault();
+    e.stopPropagation();
+    if (card.open) card.open = false;
+    else card.openByTouch();
+  };
 }
 UiHoverCardTrigger.register('ui-hover-card-trigger');
 
@@ -206,7 +266,19 @@ export class UiHoverCardContent extends WebComponent {
     ><slot></slot></div>`;
   }
 
-  _onEnter = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
-  _onLeave = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+  // Hover/focus open + close are MOUSE affordances. On a no-hover (touch)
+  // device, iOS Safari still fires SYNTHETIC mouseenter/mouseleave (and
+  // focusin/focusout from the inner link) around a tap, which would otherwise
+  // immediately re-close a tap-opened card. Gate the hover handlers to pointer
+  // devices so on touch the card is driven only by the tap path (#745).
+  _noHover = (): boolean => !!window.matchMedia?.('(hover: none)').matches;
+  _onEnter = (): void => {
+    if (this._noHover()) return;
+    (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
+  };
+  _onLeave = (): void => {
+    if (this._noHover()) return;
+    (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+  };
 }
 UiHoverCardContent.register('ui-hover-card-content');

package/packages/registry/components/sonner.ts

@@ -44,6 +44,7 @@
  * Design tokens used: --popover, --popover-foreground, --border, --radius.
  */
 import { WebComponent, html, repeat, unsafeHTML, signal, prop } from '@webjsdev/core';
+import { onBeforeCache } from '../lib/dom.ts';
 
 type ToastType = 'default' | 'success' | 'error' | 'info' | 'warning' | 'loading';
 
@@ -61,13 +62,28 @@ interface ToastItem extends ToastOptions {
 }
 
 let nextId = 1;
-const toaster: { add(t: ToastItem): void; remove(id: string | number): void } = {
-  add() {},
-  remove() {},
-};
+
+interface ToastBus {
+  add(t: ToastItem): void;
+  remove(id: string | number): void;
+}
+
+// The toast bus lives on `globalThis`, NOT in module scope, so the global
+// `toast()` still reaches a mounted <ui-sonner> when the module is loaded
+// under two different URLs. The app registers the element from the
+// version-hashed `sonner.ts?v=<hash>` (asset-hash, #243), while a caller may
+// do a bare `import('/components/ui/sonner.ts')`: those are distinct module
+// instances with distinct module-scope state, but they share one `window`.
+// Last-mounted viewport wins (it overwrites `bus().add`), matching the prior
+// singleton semantics. Without this, toasts published from a different module
+// instance silently went to a no-op bus (#745).
+function bus(): ToastBus {
+  const g = globalThis as unknown as { __webjsSonnerBus?: ToastBus };
+  return (g.__webjsSonnerBus ??= { add() {}, remove() {} });
+}
 
 function publish(item: ToastItem): string | number {
-  toaster.add(item);
+  bus().add(item);
   return item.id;
 }
 
@@ -92,7 +108,7 @@ toast.warning = (msg: string, o?: ToastOptions) => makeToast(msg, o, 'warning');
 toast.loading = (msg: string, o?: ToastOptions) => makeToast(msg, o, 'loading');
 toast.dismiss = (id?: string | number) => {
   if (id == null) return;
-  toaster.remove(id);
+  bus().remove(id);
 };
 toast.promise = <T,>(p: Promise<T>, opts: { loading: string; success: string; error: string }) => {
   const id = toast.loading(opts.loading);
@@ -139,24 +155,40 @@ export class UiSonner extends WebComponent({
 }) {
   items = signal<ToastItem[]>([]);
 
+  _disposeBeforeCache?: () => void;
+
   constructor() {
     super();
     this.position = 'bottom-right';
   }
 
+  connectedCallback(): void {
+    super.connectedCallback?.();
+    // Clear pending toasts before a back/forward snapshot so a restored page
+    // does not show stale toasts that should have auto-dismissed (#766).
+    this._disposeBeforeCache = onBeforeCache(() => this.items.set([]));
+  }
+
+  disconnectedCallback(): void {
+    this._disposeBeforeCache?.();
+    super.disconnectedCallback?.();
+  }
+
   // Routing the global toast() function to this viewport. Runs in
   // firstUpdated rather than the constructor because tests can mount
   // multiple <ui-sonner> instances and the most recently mounted wins
-  // (matches the existing semantics).
+  // (matches the existing semantics). The bus lives on globalThis so this
+  // routing is visible to a toast() called from another module instance.
   firstUpdated(): void {
-    toaster.add = (t) => this._add(t);
-    toaster.remove = (id) => this._remove(id);
+    const b = bus();
+    b.add = (t) => this._add(t);
+    b.remove = (id) => this._remove(id);
   }
 
   /**
    * Publish a toast directly to THIS viewport. Use when you have a
-   * specific <ui-sonner> reference and want to bypass the singleton
-   * `toaster.add` routing (which always points to the last-mounted
+   * specific <ui-sonner> reference and want to bypass the global
+   * `bus().add` routing (which always points to the last-mounted
    * viewport). Primary use case: docs demos that mount one viewport
    * per position and want each demo button to fire into its own
    * viewport. App code should normally call the global `toast()` /

package/packages/registry/components/tabs.ts

@@ -105,6 +105,16 @@ export class UiTabs extends WebComponent({
     this.orientation = 'horizontal';
   }
 
+  // Assign the scope id BEFORE render so it is serialized onto this host's
+  // opening tag at SSR (willUpdate now runs server-side). Without this, the id
+  // was minted lazily during a CHILD trigger's render, AFTER this host's tag
+  // was already serialized without an id, so the host shipped no id; on
+  // hydration the client re-minted a DIFFERENT counter id and the trigger /
+  // panel ids mismatched SSR vs client, breaking hydration (#730).
+  willUpdate(): void {
+    ensureId(this, 'ui-tabs');
+  }
+
   // Stable per-instance scope so a trigger and its panel agree on the
   // shared id stem (`<scope>-trigger-<value>` / `<scope>-panel-<value>`)
   // even when several tab sets reuse the same `value` names on one page.

package/packages/registry/components/tooltip.ts

@@ -42,6 +42,7 @@
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
 import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // UA `[popover]` defaults paint a bordered, padded panel centered with
@@ -79,6 +80,8 @@ export class UiTooltip extends WebComponent({
     this.skipDelayDuration = 300;
   }
 
+  _disposeBeforeCache?: () => void;
+
   connectedCallback(): void {
     super.connectedCallback?.();
     // webjs projects slotted light-DOM children in a pass after the first
@@ -88,6 +91,13 @@ export class UiTooltip extends WebComponent({
     if (typeof requestAnimationFrame === 'function') {
       requestAnimationFrame(() => this._wireAria());
     }
+    // Close before a back/forward snapshot so it does not restore open (#766).
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
+  }
+
+  disconnectedCallback(): void {
+    this._disposeBeforeCache?.();
+    super.disconnectedCallback?.();
   }
 
   // APG tooltip wiring: the focusable trigger references the tip via

package/packages/registry/lib/dom.ts

@@ -0,0 +1,18 @@
+// Client-only DOM helpers. Kept SEPARATE from lib/utils.ts because these
+// reference `document`: any module that references a client global is treated
+// as client-effecting by the elision analyzer, so bundling this with the pure
+// `cn()` would pin every page that imports `cn` to the browser (#819). Import
+// these ONLY from components (which ship anyway), never from a page/layout.
+
+/**
+ * Run `reset` just before the webjs client router snapshots the page into its
+ * back/forward cache (the `webjs:before-cache` event). Transient overlays use
+ * this to close themselves so a restored snapshot is clean. SSR-safe (a no-op
+ * when there is no `document`). Wire it in `connectedCallback` and call the
+ * returned disposer in `disconnectedCallback` so it never leaks across navs.
+ */
+export function onBeforeCache(reset: () => void): () => void {
+  if (typeof document === 'undefined') return () => {};
+  document.addEventListener('webjs:before-cache', reset);
+  return () => document.removeEventListener('webjs:before-cache', reset);
+}

package/packages/registry/lib/utils.ts

@@ -127,95 +127,12 @@ export function ensureId(el: { id: string }, prefix = 'ui'): string {
   return el.id;
 }
 
-// ---------------------------------------------------------------------------
-// Custom-element base: SSR-safe. In the browser `Base = HTMLElement`. On
-// the server (Node, during SSR) `HTMLElement` is undefined; we substitute
-// a stub class so that `class Foo extends Base { … }` doesn't throw at
-// module-load time. The stub's methods are never actually called server-side
-// because connectedCallback/lifecycle hooks only run when the element is
-// inserted into a live DOM, which doesn't happen during webjs SSR.
-// ---------------------------------------------------------------------------
-
-const HasHTMLElement = typeof HTMLElement !== 'undefined';
-
-class ServerHTMLElementStub {
-  // Minimal surface so attribute reads/writes inside synchronous code paths
-  // that DO execute during SSR (e.g. attribute reflection) don't throw.
-  _ssrAttrs: Record<string, string> = {};
-  getAttribute(name: string): string | null {
-    return this._ssrAttrs[name] ?? null;
-  }
-  setAttribute(name: string, value: string): void {
-    this._ssrAttrs[name] = String(value);
-  }
-  hasAttribute(name: string): boolean {
-    return name in this._ssrAttrs;
-  }
-  removeAttribute(name: string): void {
-    delete this._ssrAttrs[name];
-  }
-  toggleAttribute(name: string, force?: boolean): boolean {
-    const want = force === undefined ? !this.hasAttribute(name) : force;
-    if (want) this.setAttribute(name, '');
-    else this.removeAttribute(name);
-    return want;
-  }
-  addEventListener(): void {}
-  removeEventListener(): void {}
-  dispatchEvent(): boolean {
-    return true;
-  }
-  // Tree-walk APIs no-op into null: components that call them server-side
-  // simply see "no children / no siblings", which is acceptable for SSR.
-  closest(): null {
-    return null;
-  }
-  querySelector(): null {
-    return null;
-  }
-  querySelectorAll(): never[] {
-    return [];
-  }
-  focus(): void {}
-  blur(): void {}
-  contains(): boolean {
-    return false;
-  }
-  insertBefore<T>(node: T): T {
-    return node;
-  }
-  appendChild<T>(node: T): T {
-    return node;
-  }
-  replaceChildren(): void {}
-  get firstChild(): null {
-    return null;
-  }
-  get classList() {
-    return { add: () => {}, remove: () => {}, toggle: () => false, contains: () => false };
-  }
-  get className(): string {
-    return this._ssrAttrs.class ?? '';
-  }
-  set className(v: string) {
-    this._ssrAttrs.class = v;
-  }
-  get style(): Record<string, string> {
-    return {};
-  }
-}
-
-/** SSR-safe base class: `HTMLElement` in browser, a thin stub in Node. */
-export const Base: typeof HTMLElement = (HasHTMLElement
-  ? HTMLElement
-  : (ServerHTMLElementStub as unknown as typeof HTMLElement)) as typeof HTMLElement;
-
-/** Register a custom element. No-op on server (no `customElements` global). */
-export function defineElement(name: string, cls: CustomElementConstructor): void {
-  if (typeof customElements === 'undefined') return;
-  if (customElements.get(name)) return; // already defined (HMR / double-import)
-  customElements.define(name, cls);
-}
+// NOTE: the old `HTMLElement`-era `Base` / `defineElement` / SSR-stub helpers
+// were removed. The ui registry components extend `WebComponent` from
+// `@webjsdev/core` now, so those helpers were dead code, and referencing
+// `HTMLElement` / `customElements` at module scope marked this util (and any
+// page that imports `cn`) as client-effecting. Everything below is pure or
+// SSR-safe, so importing `cn` no longer pins a page to the browser (#819).
 
 // ---------------------------------------------------------------------------
 // Layout helpers: encode the design-system rhythm (spacing between label /

package/packages/registry/registry.json

@@ -15,6 +15,18 @@
         }
       ]
     },
+    {
+      "name": "lib-dom",
+      "type": "registry:lib",
+      "description": "onBeforeCache() client-router cache hook",
+      "files": [
+        {
+          "path": "lib/dom.ts",
+          "type": "registry:lib",
+          "target": "lib/dom.ts"
+        }
+      ]
+    },
     {
       "name": "theme-neutral",
       "type": "registry:theme",
@@ -59,7 +71,8 @@
       "type": "registry:ui",
       "registryDependencies": [
         "button",
-        "dialog"
+        "dialog",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -189,7 +202,8 @@
       "type": "registry:ui",
       "registryDependencies": [
         "lib-utils",
-        "button"
+        "button",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -205,7 +219,8 @@
       "name": "dropdown-menu",
       "type": "registry:ui",
       "registryDependencies": [
-        "popover"
+        "popover",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -221,7 +236,8 @@
       "name": "hover-card",
       "type": "registry:ui",
       "registryDependencies": [
-        "popover"
+        "popover",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -381,6 +397,9 @@
     {
       "name": "sonner",
       "type": "registry:ui",
+      "registryDependencies": [
+        "lib-dom"
+      ],
       "dependencies": [
         "@webjsdev/core"
       ],
@@ -476,7 +495,8 @@
       "name": "tooltip",
       "type": "registry:ui",
       "registryDependencies": [
-        "popover"
+        "popover",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"

package/src/commands/add.js

@@ -76,31 +76,51 @@ async function writeRegistryFile(cwd, config, item, file, opts) {
 }
 
 /**
- * Rewrite the registry-relative `'../lib/utils.ts'` import to the path
- * that resolves correctly from the file's target location to the user's
- * cn() helper.
+ * Rewrite the registry-relative `'../lib/utils.ts'` and `'../lib/dom.ts'`
+ * imports to the paths that resolve correctly from the file's target
+ * location to the user's cn() helper and onBeforeCache() DOM helper.
  *
  * The registry source assumes its own layout (`<registry>/components/<x>.ts`
- * imports `'../lib/utils.ts'`). When that file lands in the user's
- * components/ui/<x>.ts, the literal `'../lib/utils.ts'` resolves to
- * `components/lib/utils.ts`, which doesn't exist. We compute the actual
- * relative path from the target directory to `config.resolvedPaths.utils`
- * (an absolute path the user has already configured via components.json's
- * aliases.utils) and substitute it in.
+ * imports `'../lib/utils.ts'` / `'../lib/dom.ts'`). When that file lands in
+ * the user's components/ui/<x>.ts, the literal `'../lib/utils.ts'` resolves
+ * to `components/lib/utils.ts`, which doesn't exist. We compute the actual
+ * relative path from the target directory to the user's configured helper
+ * (`config.resolvedPaths.utils`, from components.json's aliases.utils) and
+ * substitute it in. The DOM helper is written as a SIBLING of the utils
+ * file (the scaffold puts it at `lib/utils/dom.ts`, next to `cn.ts`), so its
+ * absolute target is `dom.ts` in the utils file's directory. sonner imports
+ * ONLY the DOM helper, so both specifiers are handled independently and
+ * neither presence gates the other.
  *
  * @param {string} content raw file content from the registry
  * @param {string} target absolute path where the file will be written
  * @param {{ resolvedPaths: { utils: string } }} config parsed components.json
  */
 export function rewriteUtilsImport(content, target, config) {
-  if (!content.includes('../lib/utils.ts')) return content;
   const utilsAbs = config?.resolvedPaths?.utils;
   if (!utilsAbs) return content;
-  let rel = relPath(dirname(target), utilsAbs).split(/[\\/]/).join('/');
+  let out = replaceImportSpecifier(content, '../lib/utils.ts', utilsAbs, target);
+  const domAbs = join(dirname(utilsAbs), 'dom.ts');
+  out = replaceImportSpecifier(out, '../lib/dom.ts', domAbs, target);
+  return out;
+}
+
+/**
+ * Replace a single registry-relative import specifier with the relative path
+ * from `target`'s directory to `destAbs`. No-op when `spec` is absent.
+ *
+ * @param {string} content
+ * @param {string} spec the registry-relative specifier to replace
+ * @param {string} destAbs absolute path of the destination file
+ * @param {string} target absolute path where the importing file is written
+ */
+function replaceImportSpecifier(content, spec, destAbs, target) {
+  if (!content.includes(spec)) return content;
+  let rel = relPath(dirname(target), destAbs).split(/[\\/]/).join('/');
   if (!rel.startsWith('.')) rel = './' + rel;
   return content
-    .replaceAll("'../lib/utils.ts'", `'${rel}'`)
-    .replaceAll('"../lib/utils.ts"', `"${rel}"`);
+    .replaceAll(`'${spec}'`, `'${rel}'`)
+    .replaceAll(`"${spec}"`, `"${rel}"`);
 }
 
 function resolveTarget(cwd, config, item, file) {

package/src/commands/init.js

@@ -75,21 +75,45 @@ export const init = new Command()
   });
 
 async function writeLibUtils(cwd, utilsAlias, registryUrl) {
+  // `utils` alias points at e.g. "lib/utils" so we write to lib/utils.ts
+  const utilsRel = utilsAlias.replace(/^@\//, '') + '.ts';
+  const utilsTarget = join(cwd, utilsRel);
   try {
     const item = await fetchRegistryItem('lib-utils', registryUrl);
+    if (item.files) {
+      for (const f of item.files) {
+        ensureDir(dirname(utilsTarget));
+        writeFileSync(utilsTarget, f.content || '', 'utf8');
+        logger.success(`Wrote ${utilsAlias}.ts`);
+      }
+    }
+  } catch (e) {
+    logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write lib/utils.ts manually.`);
+  }
+
+  // The onBeforeCache() DOM helper lives in a SEPARATE module (#819) because
+  // it references `document`, so keeping it out of cn()'s file prevents the
+  // elision analyzer pinning every page that imports cn to the browser.
+  // Overlay components import it from `../lib/dom.ts`, so write it as a
+  // sibling of the utils file (e.g. lib/utils/dom.ts next to cn.ts).
+  const domTarget = join(dirname(utilsTarget), 'dom.ts');
+  try {
+    const item = await fetchRegistryItem('lib-dom', registryUrl);
     if (!item.files) return;
     for (const f of item.files) {
-      // `utils` alias points at e.g. "lib/utils" → we write to lib/utils.ts
-      const target = join(cwd, utilsAlias.replace(/^@\//, '') + '.ts');
-      ensureDir(dirname(target));
-      writeFileSync(target, f.content || '', 'utf8');
-      logger.success(`Wrote ${utilsAlias}.ts`);
+      ensureDir(dirname(domTarget));
+      writeFileSync(domTarget, f.content || '', 'utf8');
+      logger.success(`Wrote ${relative(cwd, domTarget)}`);
     }
   } catch (e) {
-    logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write lib/utils.ts manually.`);
+    logger.warn(`Could not fetch lib-dom from registry (${e.message}). You may need to write lib/dom.ts manually.`);
   }
 }
 
+function relative(cwd, p) {
+  return p.startsWith(cwd) ? p.slice(cwd.length + 1) : p;
+}
+
 async function writeTheme(cwd, baseColor, cssPath, registryUrl) {
   try {
     const item = await fetchRegistryItem(`theme-${baseColor}`, registryUrl);

package/src/utils/detect-project.js

@@ -34,7 +34,9 @@ export function defaultsForProject(cwd = process.cwd()) {
   switch (type) {
     case 'webjs':
       return {
-        tailwindCss: 'app/globals.css',
+        // styles/globals.css, NOT app/globals.css: in webjs, app/ is routing-only,
+        // so a non-routing stylesheet lives outside it.
+        tailwindCss: 'styles/globals.css',
         aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
       };
     case 'next':