@cardstack/boxel-cli 0.13.0-unstable.4 → 0.13.0-unstable.5

package/bundled-realms/pretui/components/doc-report.gts

@@ -18,8 +18,8 @@ import { iconFor } from '../icon-registry';
 // The body is a slot, never a string: a report is markdown, tables, embedded
 // cards, whatever the run produced (Law 7). `Prose` supplies the reading
 // measure and the inline-code treatment; `Tooltip` supplies the pill preview
-// and, being CSS-only on hover AND focus-within, works from the keyboard —
-// which the design mirror's hover-only fit-preview did not.
+// and, since it opens on keyboard focus as well as hover, works from the
+// keyboard — which the design mirror's hover-only fit-preview did not.
 
 export interface DocCard {
   /** stable id — the {{#each}} key */

package/bundled-realms/pretui/components/doc-report.usage.gts

@@ -39,7 +39,7 @@ class DocReportUsage extends GlimmerComponent {
   <template>
     <FreestyleUsage
       @name='DocReport'
-      @description='The deliverable at the end of a research run: a document, not a chat message. Two things make it a component rather than a div of prose — it is capped, so a 4000-word report cannot swallow the transcript, and the cards it cites are pills you can preview without leaving the report. The cap is a mask gradient rather than a hard edge, so the reader can see that there IS more instead of guessing. The body is a slot, never a string, because a report is markdown, tables and embedded cards, whatever the run produced. Prose supplies the reading measure and the inline-code treatment; Tooltip supplies the pill preview, and being CSS-only on hover AND focus-within it works from the keyboard — which the design mirror’s hover-only fit-preview did not.'
+      @description='The deliverable at the end of a research run: a document, not a chat message. Two things make it a component rather than a div of prose — it is capped, so a 4000-word report cannot swallow the transcript, and the cards it cites are pills you can preview without leaving the report. The cap is a mask gradient rather than a hard edge, so the reader can see that there IS more instead of guessing. The body is a slot, never a string, because a report is markdown, tables and embedded cards, whatever the run produced. Prose supplies the reading measure and the inline-code treatment; Tooltip supplies the pill preview, and since it opens on keyboard focus as well as hover, it works from the keyboard — which the design mirror’s hover-only fit-preview did not.'
     >
       <:example>
         <DocReport
@@ -109,8 +109,8 @@ class DocReportUsage extends GlimmerComponent {
     </FreestyleUsage>
     <style scoped>
       .demo-log {
-        margin: var(--space-4, 11px) 0 0;
-        font-size: var(--text-ui-sm, 11.5px);
+        margin: var(--boxel-sp-sm) 0 0;
+        font-size: var(--boxel-font-size-xs);
         color: var(--muted-foreground);
       }
       .demo-log strong {

package/bundled-realms/pretui/components/form-field.md

@@ -51,7 +51,7 @@ What is right:
 Gaps and cautions:
 
 - **The wiring is yielded, not applied.** If `<:control>` ignores `ctx.describedBy` or `ctx.invalid`, nothing is wired and nothing warns. The component removes the _excuse_ for forgetting, not the possibility. A dev-mode assertion that the yielded `id` was consumed would close it.
-- **The help affordance is a Tooltip**, which inherits Tooltip's gaps — no Escape dismissal and `pointer-events: none`, both WCAG 1.4.13 failures. Because the help text is always in the DOM and referenced by id, the _semantic_ path is fine; the pointer path is not.
+- **The help affordance is a Tooltip**, which inherits Tooltip's remaining gaps (see `tooltip.md`).
 - `@labelHidden` keeps the label in the accessible tree, which is correct, but a visually hidden label plus a placeholder is still a WCAG 3.3.2 smell for sighted users.
 - `@static` produces no control at all, so `describedBy` describes nothing focusable — expected, but do not pass `@required` alongside it.
 - The `emptyText` default `'—'` is announced literally by some screen readers as "em dash"; consider a visually-hidden "not set" for record views.

package/bundled-realms/pretui/components/icon-button.md

@@ -65,7 +65,7 @@ What is right:
 Gaps and cautions:
 
 - **`title` is set to the same string as `aria-label`.** This is deliberate — it gives sighted mouse users a native tooltip — but it is a known double-announcement risk: some screen reader and browser combinations read the accessible name and then the `title` as a description. It is also a UA-controlled tooltip, which means no styling and, per WCAG 1.4.13's exception, no dismissible/hoverable obligation. For a styled hint, pass `@tooltip`: the button renders a **Tooltip** with that text, which names the button when it matches `@label` and describes it otherwise, and drops `title`, so the native tooltip doesn't show over it. Wrapping the button in **Tooltip** yourself keeps the `title` and shows both.
-- **`@tooltip` adds a wrapper.** The button sits inside Tooltip's `position: relative` inline-flex span, so a class passed to the IconButton styles the button, not the outer box: place or size it through a container instead. Adding or removing `@tooltip` builds a new button element: it loses focus and the caller's modifiers run again. A hint that comes and goes should keep `@tooltip` set and change its text instead.
+- **`@tooltip` adds a wrapper.** The button sits inside Tooltip's inline-flex span, so a class passed to the IconButton styles the button, not the outer box: place or size it through a container instead. Adding or removing `@tooltip` builds a new button element: it loses focus and the caller's modifiers run again. A hint that comes and goes should keep `@tooltip` set and change its text instead.
 - **A shown `@tooltip` takes the first Escape.** Tooltip hides on Escape and stops it there (WCAG 1.4.13), so while the tip is up from hover or keyboard focus, an Escape handler above the button needs a second press.
 - **Target size**: 28×28 CSS px at the default size clears WCAG 2.5.8's 24×24 minimum, but only just, and adjacent icon buttons in a toolbar with no gap will have touching targets.
 - **Focus-visible ring inherited from Button**: `outline: 2px solid var(--ring)` with a 2px offset, which matters more here because there is no text to underline or shift.

package/bundled-realms/pretui/components/popup.md

@@ -37,6 +37,6 @@ One structural note: because the panel is a descendant of the anchor wrapper rat
 
 ## Theming
 
-Almost nothing: `z-index: 60` and layout only. Every visual token belongs to the consumer's panel. Callers that need to re-layer overlays should note the kit's convention — 49/50 for Menu's backdrop and panel, 60 for `Popup` and `Tooltip`, and the native top layer (above everything) for `Dialog` and `Drawer`.
+Almost nothing: a z-index and layout only. Every visual token belongs to the consumer's panel. Callers that need to re-layer overlays should read the z tiers in `pretui-css.gts`; `Dialog`, `Drawer`, `CommandPalette` and an open `Tooltip` sit in the native top layer, above every tier.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/switch.gts

@@ -78,6 +78,19 @@ export class Switch extends Component<SwitchSignature> {
             var(--pretui-ease-snap, ease);
           flex: none;
         }
+        /* Stretches the hit area to the 24px minimum target of WCAG 2.5.8
+           on the short axis, leaving the drawn track as it is. The inset
+           reads the track's own height, so the target stays 24px tall if
+           that height changes. */
+        .pretui-switch::before {
+          content: '';
+          position: absolute;
+          inset: calc((100% - 24px) / 2) 0;
+        }
+        .pretui-switch:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
         .pretui-switch:active:not(:disabled) {
           box-shadow: var(
             --pretui-shadow-inset,

package/bundled-realms/pretui/components/switch.md

@@ -36,18 +36,20 @@ Governing pattern: APG **Switch**. `role="switch"` and `aria-checked` `'true'`/`
 
 Keyboard: it is a native `<button>`, so **Space and Enter both activate**. APG requires Space and permits Enter, so this passes.
 
+Focus: `:focus-visible` draws a 2px `--ring` outline 2px clear of the track, the same ring as Button and Checkbox. It stays visible on a checked track, whose `--primary` fill would hide a ring drawn flush against it.
+
+Target size: the drawn track is 30×18 CSS px, and a transparent `::before` stretches the hit area to 30×24, the minimum of WCAG 2.5.8. The extra 3px above and below sits outside the button's box, so a control placed closer than that to a Switch shares those pixels with it.
+
 Gaps:
 
 - **No accessible name of its own.** There is no `@label`, and the only content is an empty thumb `<span>`. A Switch outside `Field`/`FormField` and without an explicit `aria-label` is announced as "switch, off" with no indication of what it controls. This is the most likely real-world failure, because a Switch is visually self-evident and developers do not notice the omission.
 - **`@disabled` uses the native attribute**, so a disabled switch leaves the tab order entirely and cannot be discovered by a keyboard user scanning a settings panel. `aria-disabled` would keep it readable.
 - **`opacity: 0.45`** for disabled will fail contrast in most themes.
-- **No focus-visible ring is defined.** The track uses `background` and the thumb uses `box-shadow`; nothing paints `:focus-visible`, so the control relies on the UA outline around a 30×18 pill. Likely WCAG 2.4.7 failure.
-- **Target size is 30×18 CSS px**, below the 24×24 minimum of WCAG 2.5.8 on the short axis. Wrapping it in a larger label row (which `Field` does) resolves it in practice, but a bare Switch in a table row does not.
 - The label, if a wrapper supplies one, must not change with state — "Notifications", not "Notifications on". That is an APG requirement and a caller obligation.
 
 ## Theming
 
-Track: `--pretui-control-border` (falling back to `--line-strong`) when off, `--primary` when on. Thumb: `--card` with `--shadow-ink-mid`. Pressed: `--pretui-shadow-inset`. Motion: `--pretui-dur-snap`, `--pretui-ease-snap`.
+Track: `--pretui-control-border` (falling back to `--line-strong`) when off, `--primary` when on. Thumb: `--card` with `--shadow-ink-mid`. Pressed: `--pretui-shadow-inset`. Focus: `--ring`. Motion: `--pretui-dur-snap`, `--pretui-ease-snap`.
 
 The 30×18 track, 14px thumb and 12px travel are fixed — there is no size axis, so a theme cannot scale it alongside Button's `xs`–`xl`. That inconsistency is visible when a Switch sits next to an `xs` Button.
 

package/bundled-realms/pretui/components/theme-frame.gts

@@ -3,18 +3,18 @@ import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
 import { guidFor } from '@ember/object/internals';
-import { Switch } from '@cardstack/boxel-ui/components';
-import { themeScope, themeScopedCss } from '@cardstack/boxel-ui/helpers';
 import Moon from '@cardstack/boxel-icons/moon';
 import Sun from '@cardstack/boxel-icons/sun';
 import { realmURL } from '@cardstack/base/card-api';
+import { themeScope, themeScopedCss } from '../theme-scoped-css';
 import { Select } from './select';
+import { Switch } from './switch';
 
 // Wraps a page in a theme island with a dark mode switch, built the
 // way the monorepo's own theme cards preview themselves (see
 // base/default-templates/theme-dashboard.gts). No custom theming code: the
 // outer div stamps data-theme, which theme.css translates into the
-// inherited --boxel-color-scheme signal; inside it, boxel-ui's `themeScope`
+// inherited --boxel-color-scheme signal; inside it, Pret UI's `themeScope`
 // and `themeScopedCss` helpers re-declare the theme's variables under a
 // content-hashed scope, and their `.dark` block follows the signal through
 // the style container query those helpers emit.
@@ -61,8 +61,10 @@ export interface ThemeFrameSignature {
   Element: HTMLDivElement;
 }
 
-// The same switch the base ThemeDashboard's ModeToggle renders, so a theme
-// previews light and dark the way it does everywhere else in Boxel.
+// The dark mode control is Pret UI's Switch, named "Dark mode" for assistive
+// tech, between a sun and a moon: the glyph for the scheme in force reads in
+// the foreground color and the other one recedes. The glyphs are decorative,
+// since the switch's own state already says which scheme is on.
 interface ThemeControlsSignature {
   Args: { frame: ThemeFrame };
   Element: HTMLSpanElement;
@@ -76,15 +78,28 @@ const ThemeControls: TemplateOnlyComponent<ThemeControlsSignature> = <template>
     data-test-pretui-theme-bar
     ...attributes
   >
-    <Switch
-      @isEnabled={{@frame.isDarkMode}}
-      @onChange={{@frame.toggleDarkMode}}
-      @size='touch'
-      @checkedIcon={{Moon}}
-      @uncheckedIcon={{Sun}}
-      @label='Dark mode'
-      data-test-pretui-theme-mode
-    />
+    <span class='pretui-theme-mode'>
+      <Sun
+        class='pretui-theme-mode-icon'
+        data-active={{unless @frame.isDarkMode 'true'}}
+        width='14'
+        height='14'
+        aria-hidden='true'
+      />
+      <Switch
+        @checked={{@frame.isDarkMode}}
+        @onCheckedChange={{@frame.setDarkMode}}
+        aria-label='Dark mode'
+        data-test-pretui-theme-mode
+      />
+      <Moon
+        class='pretui-theme-mode-icon'
+        data-active={{if @frame.isDarkMode 'true'}}
+        width='14'
+        height='14'
+        aria-hidden='true'
+      />
+    </span>
     {{#if @frame.showThemeSelect}}
       <span class='pretui-theme-pick' data-test-pretui-theme-pick>
         <Select
@@ -110,6 +125,18 @@ const ThemeControls: TemplateOnlyComponent<ThemeControlsSignature> = <template>
         align-items: center;
         gap: var(--boxel-sp-xs);
       }
+      .pretui-theme-mode {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--boxel-sp-2xs);
+        color: var(--muted-foreground);
+      }
+      .pretui-theme-mode-icon {
+        flex: none;
+      }
+      .pretui-theme-mode-icon[data-active] {
+        color: var(--foreground);
+      }
       .pretui-theme-pick {
         min-width: var(--pretui-theme-pick-min-w);
       }
@@ -127,9 +154,7 @@ export class ThemeFrame extends Component<ThemeFrameSignature> {
   // has fixed colors, so the switch previews dark rather than following the OS.
   @tracked isDarkMode = false;
   @tracked selectedThemeId: string | undefined;
-  // a toggle, not a setter: the Switch in the CLI test harness passes its
-  // click event to @onChange, not a boolean
-  toggleDarkMode = () => (this.isDarkMode = !this.isDarkMode);
+  setDarkMode = (on: boolean) => (this.isDarkMode = on);
   pickTheme = (v: string) => (this.selectedThemeId = v);
 
   // All Theme instances in the linked theme's realm. Absent context
@@ -190,11 +215,13 @@ export class ThemeFrame extends Component<ThemeFrameSignature> {
   get themeCss() {
     return this.activeTheme?.cssVariables ?? undefined;
   }
-  // boxel-ui's own scope helper: theme id plus a content hash of the CSS.
-  // The hash matters because the emitted rules are page-global — two cached
-  // renders sharing a scope but carrying different theme CSS would restyle
-  // each other. A hand-rolled `${id}-frame` string could not tell two
-  // versions of one theme apart.
+  // Theme id plus a content hash of the CSS, from Pret UI's copy of the scope
+  // helper. It stays equal to boxel-ui's copy, which mints the enclosing
+  // card's scope (theme-scoped-css.gts says why that matters). The hash
+  // matters because the emitted rules are page-global — two cached renders
+  // sharing a scope but carrying different theme CSS would restyle each
+  // other. A hand-rolled `${id}-frame` string could not tell two versions of
+  // one theme apart.
   get themeScopeId() {
     return themeScope(this.activeThemeId, this.themeCss) ?? guidFor(this);
   }

package/bundled-realms/pretui/components/tooltip.gts

@@ -4,6 +4,12 @@ import { tracked } from '@glimmer/tracking';
 import { guidFor } from '@ember/object/internals';
 import { modifier } from 'ember-modifier';
 import { listen, listenDocumentCapture } from '../focus';
+import { positionPopup } from '../internal/overlay';
+
+// The trigger-to-bubble gap. The show modifier places the bubble this far
+// out and sets --_tip-gap to it, so the bridge in CSS spans exactly the gap
+// at any root font size.
+const TIP_GAP_REM = 0.375;
 
 // The element a Tooltip describes. The trigger arrives as a caller block, so
 // the component finds it rather than receiving it — the first thing in the
@@ -55,8 +61,10 @@ export interface TooltipSignature {
  *   cannot put the attribute there itself. It appends its id to a caller's
  *   own value, keeps it there when the caller's value changes, and removes
  *   only its id on teardown.
- * - **Presence.** Hidden state is `visibility: hidden`, not opacity alone, so
- *   the bubble leaves the accessibility tree between reveals. A directly
+ * - **Presence.** The bubble is a manual popover: hidden, it is
+ *   `display: none`, so it is out of the accessibility tree and takes no
+ *   space in any scroll container; shown, it sits in the top layer, placed
+ *   against the wrapper, where no `overflow` ancestor clips it. A directly
  *   referenced `aria-describedby` target is still announced while hidden —
  *   that is the accname rule this pattern is built on.
  * - **Dismissible.** Escape hides it, in the capture phase, while it is open.
@@ -74,6 +82,8 @@ export class Tooltip extends Component<TooltipSignature> {
   @tracked private focused = false;
   @tracked private dismissed = false;
   private pressed = false;
+  // False while the open tip is hidden because its trigger is out of view.
+  private inView = true;
   tipId = `${guidFor(this)}-tip`;
   get side() {
     return this.args.side ?? 'top';
@@ -117,6 +127,90 @@ export class Tooltip extends Component<TooltipSignature> {
       };
     },
   );
+  /** Shows the bubble in the top layer and keeps it on the wrapper. */
+  showTip = modifier(
+    (
+      el: HTMLElement,
+      [shown, side]: [boolean, 'top' | 'bottom' | 'left' | 'right'],
+    ) => {
+      let anchor = el.parentElement;
+      if (!shown || !anchor) {
+        // data-side is the side the tip prefers until it opens, then the
+        // side it opened on, which a flip can change.
+        el.dataset['side'] = side;
+        if (el.matches(':popover-open')) el.hidePopover();
+        return;
+      }
+      if (!el.matches(':popover-open')) {
+        // A trigger is in view when it opens its tip; the observer below
+        // hides the bubble again if it isn't.
+        this.inView = true;
+        el.style.visibility = '';
+        el.showPopover();
+      }
+      el.style.setProperty('--_tip-gap', `${TIP_GAP_REM}rem`);
+      let gap =
+        TIP_GAP_REM *
+        parseFloat(getComputedStyle(document.documentElement).fontSize);
+      let place = () => {
+        let r = el.getBoundingClientRect();
+        let p = positionPopup(
+          anchor.getBoundingClientRect(),
+          r.width,
+          r.height,
+          side,
+          gap,
+        );
+        el.style.top = `${p.top}px`;
+        el.style.left = `${p.left}px`;
+        el.dataset['side'] = p.side;
+      };
+      place();
+      // Placed again when the bubble or its trigger changes size, as with new
+      // @content. Moving the trigger in the DOM closes the popover without an
+      // event and takes focus off the trigger, which not every browser
+      // reports; the bubble's size changes with it, and the tip then closes
+      // as if dismissed.
+      let sizes = new ResizeObserver(() => {
+        if (el.matches(':popover-open')) {
+          place();
+        } else {
+          this.focused = false;
+          this.dismissed = true;
+        }
+      });
+      sizes.observe(el);
+      sizes.observe(anchor);
+      // The top layer escapes the trigger's clipping containers, so the
+      // bubble hides itself while the trigger is scrolled or clipped away.
+      let clip = new IntersectionObserver((entries) => {
+        let entry = entries[entries.length - 1];
+        if (!entry) return;
+        this.inView = entry.isIntersecting;
+        el.style.visibility = this.inView ? '' : 'hidden';
+      });
+      clip.observe(anchor);
+      // Only a scroll that can move the trigger moves the bubble. The target
+      // isn't checked with `instanceof Node`, which is false in some hosts
+      // (the realm test harness among them).
+      let onScroll = (e: Event) => {
+        let target = e.target as Node | null;
+        if (target?.contains && !target.contains(anchor)) return;
+        place();
+      };
+      window.addEventListener('scroll', onScroll, {
+        capture: true,
+        passive: true,
+      });
+      window.addEventListener('resize', place);
+      return () => {
+        sizes.disconnect();
+        clip.disconnect();
+        window.removeEventListener('scroll', onScroll, true);
+        window.removeEventListener('resize', place);
+      };
+    },
+  );
   onEnter = () => {
     this.hovered = true;
   };
@@ -132,6 +226,10 @@ export class Tooltip extends Component<TooltipSignature> {
     this.focused = false;
   };
   onFocusIn = () => {
+    // Keyboard focus starts fresh, even when no focusout cleared an earlier
+    // dismissal (as when the trigger moved in the DOM). A click's focus
+    // doesn't, so it never undoes an Escape.
+    if (!this.pressed) this.dismissed = false;
     this.focused = !this.pressed;
     this.pressed = false;
   };
@@ -144,7 +242,8 @@ export class Tooltip extends Component<TooltipSignature> {
   // means exactly one thing — hide THIS tip — and never also closes the
   // dialog the trigger happens to live in.
   onKey = (e: Event) => {
-    if (!this.shown) return;
+    // A tip hidden with its out-of-view trigger leaves Escape to the page.
+    if (!this.shown || !this.inView) return;
     if ((e as KeyboardEvent).key !== 'Escape') return;
     e.stopPropagation();
     this.dismissed = true;
@@ -152,13 +251,13 @@ export class Tooltip extends Component<TooltipSignature> {
   <template>
     <span
       class='pretui-tipwrap'
-      data-test-pretui-tooltip
       {{this.describeTrigger this.tipId @labels}}
       {{listen 'mouseenter' this.onEnter}}
       {{listen 'mouseleave' this.onLeave}}
       {{listen 'mousedown' this.onPress}}
       {{listen 'focusin' this.onFocusIn}}
       {{listen 'focusout' this.onFocusOut}}
+      data-test-pretui-tooltip
       ...attributes
     >
       {{yield}}
@@ -166,8 +265,10 @@ export class Tooltip extends Component<TooltipSignature> {
         role='tooltip'
         id={{this.tipId}}
         class='pretui-tooltip'
-        data-side={{this.side}}
+        popover='manual'
         data-open={{if this.shown 'true'}}
+        {{this.showTip this.shown this.side}}
+        data-test-pretui-tooltip-bubble
       >{{@content}}</span>
       {{#if this.shown}}
         <span
@@ -179,20 +280,23 @@ export class Tooltip extends Component<TooltipSignature> {
     <style scoped>
       @layer PretComponent {
         .pretui-tipwrap {
-          position: relative;
           display: inline-flex;
         }
         .pretui-tip-key {
           display: none;
         }
         .pretui-tooltip {
-          /* the space between trigger and bubble, which the bridge spans */
-          --_tip-gap: 0.375rem;
-          position: absolute;
-          /* kit stacking scale (pretui-css.gts): a tooltip describes whatever
-             is under the pointer, which may be an item inside a dropdown or a
-             popover, so it is the highest non-modal tier. */
-          z-index: var(--pretui-z-tooltip, 80);
+          /* a manual popover: the top layer is above every z-index, and the
+             show modifier writes top, left and --_tip-gap, the space the
+             bridge spans */
+          position: fixed;
+          inset: auto;
+          margin: 0;
+          border: 0;
+          /* the bubble's edge in forced-colors mode, which drops its shadow;
+             an outline, unlike a border, leaves the bridge's box alone */
+          outline: 1px solid transparent;
+          overflow: visible;
           background-color: var(--tooltip);
           color: var(--tooltip-foreground);
           font-size: var(--boxel-font-size-xs);
@@ -203,17 +307,32 @@ export class Tooltip extends Component<TooltipSignature> {
           white-space: nowrap;
           width: max-content;
           opacity: 0;
-          /* `visibility`, not opacity alone: an opacity-0 bubble is still in
-             the accessibility tree and still hit-testable. Hidden here means
-             hidden to everyone — while a DIRECT aria-describedby reference
-             still resolves its text, which is the whole point. */
-          visibility: hidden;
-          transition: opacity 120ms ease, visibility 0s linear 120ms;
+          --_tip-fade: 120ms;
+          transition: opacity var(--_tip-fade) ease;
         }
-        .pretui-tooltip[data-open='true'] {
+        /* display and overlay hold the bubble in the top layer until the
+           fade-out ends. A browser that can't transition overlay would drop
+           it from the top layer as the fade began, so there it closes at
+           once. */
+        @supports (overlay: auto) {
+          .pretui-tooltip {
+            transition:
+              opacity var(--_tip-fade) ease,
+              display var(--_tip-fade) allow-discrete,
+              overlay var(--_tip-fade) allow-discrete;
+          }
+        }
+        .pretui-tooltip:popover-open {
           opacity: 1;
-          visibility: visible;
-          transition: opacity 120ms ease, visibility 0s;
+        }
+        /* fading out, it no longer takes the pointer */
+        .pretui-tooltip:not(:popover-open) {
+          pointer-events: none;
+        }
+        @starting-style {
+          .pretui-tooltip:popover-open {
+            opacity: 0;
+          }
         }
         /* WCAG 1.4.13 "Hoverable": the pointer must be able to travel onto the
            bubble without it vanishing. The gap between trigger and bubble is
@@ -223,26 +342,6 @@ export class Tooltip extends Component<TooltipSignature> {
           position: absolute;
           inset: calc(-1 * var(--_tip-gap));
         }
-        .pretui-tooltip[data-side='top'] {
-          bottom: calc(100% + var(--_tip-gap));
-          left: 50%;
-          transform: translateX(-50%);
-        }
-        .pretui-tooltip[data-side='bottom'] {
-          top: calc(100% + var(--_tip-gap));
-          left: 50%;
-          transform: translateX(-50%);
-        }
-        .pretui-tooltip[data-side='left'] {
-          right: calc(100% + var(--_tip-gap));
-          top: 50%;
-          transform: translateY(-50%);
-        }
-        .pretui-tooltip[data-side='right'] {
-          left: calc(100% + var(--_tip-gap));
-          top: 50%;
-          transform: translateY(-50%);
-        }
       }
     </style>
   </template>

package/bundled-realms/pretui/components/tooltip.md

@@ -13,9 +13,9 @@ A short label that appears on hover or keyboard focus, positioned against the el
 
 That is the whole API, and the smallness is the point. Two decisions follow from it.
 
-**It is CSS-only.** There is no JavaScript, no timer, no state. The reveal is `:hover` / `:focus-within` on the wrapper toggling opacity. Consequences: it is prerender-safe (nothing to run before hydration), it cannot leak a timer, and it costs zero on a page with two hundred of them — which matters, because tooltips are what you sprinkle across a dense table. The cost is no show/hide delay, so tooltips flash as the pointer crosses a toolbar.
+**The bubble is a manual popover.** Hidden, it is `display: none`: it takes no space, so a tooltip that would open past a scroll container's edge never makes that container scroll. Shown, it sits in the top layer, so no `overflow: hidden` ancestor clips it and it paints over every z-index, the Toaster included. Placement runs only while it is open. The reveal is a 120ms opacity fade, with `@starting-style` on the way in and `allow-discrete` on `display` and `overlay` on the way out, where the browser can transition `overlay`; elsewhere it closes at once. There is no show/hide delay, so tooltips flash as the pointer crosses a toolbar.
 
-**Positioning is `position: absolute` against a `position: relative` wrapper, with no collision handling.** A tooltip on a control at the right edge of the viewport will overflow it. `@side` is a static choice, not a preference. This is a deliberate departure from the rest of the kit's overlays, which use the `anchorTo` measuring modifier — the trade is made for prerender safety and per-instance cost.
+**Positioning is measured against the wrapper on open**, with the same `positionPopup` math the kit's `anchorTo` uses, and placed again while open whenever the page scrolls or resizes, or the bubble or its trigger changes size, as when `@content` changes. While the trigger is scrolled or clipped out of view, the bubble hides with it. A trigger that moves for any other reason, such as content inserted above it, leaves an open tip where it was until the next scroll, resize or size change. A trigger moved in the DOM, as when a keyed list reorders, closes its tip as if dismissed; it opens again once the pointer or focus leaves and returns. `@side` is a preference: a tooltip without room on its side flips to the opposite one, and slides along its axis to stay on screen.
 
 The tooltip is **always dark**, in both light and dark modes — the kit calls this "the lining". It is a deliberate constant so the affordance reads identically everywhere.
 
@@ -23,7 +23,7 @@ The tooltip is **always dark**, in both light and dark modes — the kit calls t
 
 **Web Awesome `wa-tooltip`** is the fullest: `placement`, `distance`, `skidding`, `open`, `disabled`, `show-delay` (150ms) / `hide-delay`, `trigger` (`'hover focus'`, also `click`/`manual`), `without-arrow`, and a `for` attribute associating the tooltip to a trigger _by id_ rather than by wrapping it. **Radix `Tooltip`** requires a `Provider` so a group shares `delayDuration` and `skipDelayDuration` — cross the toolbar quickly and subsequent tooltips appear instantly, which is the single best tooltip detail in the ecosystem. **React Spectrum** adds warmup/cooldown timing and is explicit that tooltips must never contain interactive content.
 
-Pretui is smaller than all three on purpose, and it is worth being clear that here the kit is _behind_, not ahead: no delay, no group coordination, no collision flip, no arrow. What it buys is a component with no runtime at all.
+Pretui is smaller than all three on purpose, and it is worth being clear that here the kit is _behind_, not ahead: no delay, no group coordination, no arrow. What it buys is a component that measures nothing until it opens.
 
 One place Pretui is genuinely better: `@content` is a plain string, not a slot. Radix and Web Awesome accept arbitrary children, which invites people to put buttons and links inside tooltips — an accessibility disaster that every one of those libraries then documents against. Making the type `string` makes the mistake unrepresentable.
 
@@ -33,15 +33,13 @@ Governing rules: APG **Tooltip** pattern (still marked as under review upstream,
 
 Pretui's honest scorecard:
 
-- `role="tooltip"` is present on the bubble. **But the bubble is not associated with the trigger** — there is no `aria-describedby` and no `aria-labelledby`, and no id is generated. A screen-reader user focusing the trigger is told nothing. Since the tooltip is rendered unconditionally in the DOM (only opacity changes), the text is also read as ordinary adjacent content, at all times, whether or not the tooltip is showing. This is the component's most serious defect.
-- Worth noting what the field has learned here: `wa-tooltip` deliberately uses **`aria-labelledby`, not `aria-describedby`**, with a comment that it gives the most consistent screen-reader result — several readers only announce `describedby` on a genuinely focusable element, whereas `labelledby` reads on first focus. The APG recommends `describedby`. Whichever Pretui adopts, adopting _one_ is the fix.
-- **Not dismissible** (SC 1.4.13): no Escape handling.
-- **Not hoverable** (SC 1.4.13): `pointer-events: none` on the bubble means moving the pointer onto the tooltip is impossible. For a one-line label this rarely matters in practice, but it is a literal failure of the criterion.
-- Persistent: passes — there is no timeout.
-- `white-space: nowrap` means long content will not wrap and will overflow rather than reflow.
-- `:focus-within` correctly covers keyboard focus, so the _visual_ affordance is keyboard-reachable even though the semantic one is missing.
-
-Do not ship a tooltip as the only name for an icon button until the association gap is closed — give the button an `aria-label` as well.
+- **Associated:** `role="tooltip"` is on the bubble, which has a generated id. The trigger (the first focusable element in the wrapper) points at it with `aria-describedby`, as the APG recommends. Hidden, the bubble is `display: none`, so its text isn't read as adjacent content; a directly referenced description is still announced.
+- **`@labels` names instead:** `wa-tooltip` deliberately uses `aria-labelledby`, because several readers announce `describedby` inconsistently on a control that already has a name. Pass `@labels` when the tip is the control's only name, as on an icon-only button.
+- **Dismissible** (SC 1.4.13): Escape hides it, in the capture phase, so it never also closes the dialog the trigger is in.
+- **Hoverable** (SC 1.4.13): the bubble takes the pointer, and a transparent bridge spans the gap, so the pointer can move from the trigger onto it.
+- **Persistent:** passes — there is no timeout.
+- **Keyboard:** keyboard focus opens it; focus from a mouse press doesn't, so a clicked trigger doesn't keep its tip up after the pointer leaves.
+- `white-space: nowrap` means long content doesn't wrap, and a tip wider than the viewport runs past its edge.
 
 ## Theming
 

package/bundled-realms/pretui/components/tooltip.usage.gts

@@ -6,8 +6,6 @@ import { Tooltip } from './tooltip';
 import { Button } from './button';
 import { SIDE_OPTIONS } from '../demo-structure';
 
-// Note: Pretui Tooltip is CSS-only — it reveals on hover/focus-within, with
-// no floating-ui positioning or JS listeners (prerender-safe by design).
 // Dropped knobs: offset (fixed 0.375rem gap, no arg); variant (single always-dark
 // treatment — "the lining"); the six boxel-tooltip-* CSS-variable knobs
 // (CSS knob layer not yet ported).
@@ -24,7 +22,7 @@ class TooltipUsage extends GlimmerComponent {
   <template>
     <FreestyleUsage
       @name='Tooltip'
-      @description='Tooltips provide additional information when hovering over an element. Pretui Tooltip is CSS-only — it reveals on hover and focus-within, always dark in both modes, with no JS positioning.'
+      @description='Tooltips provide additional information when hovering over an element. Shown in the top layer; takes no space while hidden.'
     >
       <:example>
         <Tooltip
@@ -38,7 +36,7 @@ class TooltipUsage extends GlimmerComponent {
       <:api as |Args|>
         <Args.String
           @name='side'
-          @description='The positioning of the tooltip relative to the reference element.'
+          @description='The side the tooltip prefers; it flips when that side has no room.'
           @value={{this.side}}
           @options={{SIDE_OPTIONS}}
           @defaultValue='top'
@@ -59,7 +57,7 @@ class TooltipUsage extends GlimmerComponent {
           @onInput={{this.setDisabled}}
         />
         <Args.Yield
-          @description='The element the tooltip is attached to; the tooltip reveals on its hover and focus-within.'
+          @description='The element the tooltip is attached to; the tooltip opens on its hover and keyboard focus.'
           @hideControls={{true}}
         />
       </:api>

package/bundled-realms/pretui/docs/structure.md

@@ -4,5 +4,5 @@ Design notes shared by **Panel**, **Toolbar**, **Tooltip**, **Skeleton**, **Pagi
 
 Surfaces, the panel signature, navigation.
 Translated from pretui-design-system (components/structure + css/structure.css).
-Realm adaptations: Tooltip is CSS-only (hover/focus-within — prerender-safe);
+Realm adaptations: Tooltip is a manual popover, placed only while open;
 Menu closes via backdrop, not a document listener.

package/bundled-realms/pretui/internal/overlay.gts

@@ -151,7 +151,7 @@ const OPPOSITE: Record<Side, Side> = {
   right: 'left',
 };
 
-function positionPopup(
+export function positionPopup(
   a: DOMRect,
   w: number,
   h: number,
@@ -194,7 +194,9 @@ function positionPopup(
           : a.top + a.height / 2 - h / 2;
     top = Math.min(Math.max(top, GUTTER), Math.max(vh - h - GUTTER, GUTTER));
   }
-  return { top, left };
+  // `side` is the one it placed on: the opposite of the placement's when
+  // that side had no room.
+  return { top, left, side };
 }
 
 // Positions the popup against its anchor and keeps it placed across scroll/