@wippy-fe/theme 0.0.47 → 0.0.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wippy-fe/theme",
-  "version": "0.0.47",
+  "version": "0.0.49",
   "description": "Theme variables, shared Tailwind config, and PrimeVue styling for Wippy web components.",
   "type": "module",
   "main": "theme-config.css",
@@ -10,11 +10,16 @@
     "./tailwind.config": "./tailwind.config.ts",
     "./primevue-plugin": "./primevue-plugin.ts",
     "./tokens.json": "./tokens.json",
+    "./effective-contract.json": "./effective-contract.json",
+    "./tailwind-contract.json": "./tailwind-contract.json",
     "./primevue/*": "./primevue/*"
   },
   "files": [
     "theme-config.css",
     "tokens.json",
+    "effective-contract.json",
+    "tailwind-contract.json",
+    "contracts/",
     "tailwind.config.ts",
     "primevue-plugin.ts",
     "primevue/",

package/primevue/button.css

@@ -144,17 +144,6 @@
         focus-visible:outline-help-500 dark:focus-visible:outline-help-400
 }
 
-.p-button-help {
-    @apply bg-help-500 enabled:hover:bg-help-600 enabled:active:bg-help-700
-        border-help-500 enabled:hover:border-help-600 enabled:active:border-help-700
-        text-white enabled:hover:text-white enabled:active:text-white
-        dark:bg-help-400 dark:enabled:hover:bg-help-300 dark:enabled:active:bg-help-200
-        dark:border-help-400 dark:enabled:hover:border-help-300 dark:enabled:active:border-help-200
-        dark:text-help-950 dark:enabled:hover:text-help-950 dark:enabled:active:text-help-950
-        focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2
-        focus-visible:outline-help-500 dark:focus-visible:outline-help-400
-}
-
 .p-button-danger {
     @apply bg-danger-500 enabled:hover:bg-danger-600 enabled:active:bg-danger-700
         border-danger-500 enabled:hover:border-danger-600 enabled:active:border-danger-700

package/primevue/inputtext.css

@@ -1,42 +1,42 @@
-.p-inputtext {
-    @apply appearance-none
-        border border-surface-300 dark:border-surface-700
-        enabled:hover:border-surface-400 dark:enabled:hover:border-surface-600
-        enabled:focus:border-primary dark:enabled:focus:border-primary
-        bg-surface-0 dark:bg-surface-800
-        text-surface-700 dark:text-surface-0
-        disabled:bg-surface-200 disabled:text-surface-500 dark:disabled:bg-surface-700 dark:disabled:text-surface-400 disabled:opacity-100
-        placeholder:text-surface-500 dark:placeholder:text-surface-400
-        transition-colors
-        outline-none;
-    border-radius: var(--p-form-field-border-radius);
-    padding: var(--p-form-field-padding-y) var(--p-form-field-padding-x);
-    transition-duration: var(--p-form-field-transition-duration);
-    box-shadow: var(--p-form-field-shadow);
-}
-
-.p-inputtext.p-invalid {
-    @apply border-danger-400 dark:border-danger-300
-}
-
-.p-inputtext.p-variant-filled {
-    @apply bg-surface-50 dark:bg-surface-800
-}
-
-.p-inputtext-sm {
-    @apply text-sm;
-    padding: var(--p-form-field-sm-padding-y) var(--p-form-field-sm-padding-x);
-}
-
-.p-inputtext-xs {
-    @apply text-xs px-2 py-1
-}
-
-.p-inputtext-lg {
-    @apply text-lg;
-    padding: var(--p-form-field-lg-padding-y) var(--p-form-field-lg-padding-x);
-}
-
-.p-inputtext-fluid {
-    @apply w-full
-}
+.p-inputtext {
+    @apply appearance-none
+        border border-surface-300 dark:border-surface-700
+        enabled:hover:border-surface-400 dark:enabled:hover:border-surface-600
+        enabled:focus:border-primary dark:enabled:focus:border-primary
+        bg-surface-0 dark:bg-surface-800
+        text-surface-700 dark:text-surface-0
+        disabled:bg-surface-200 disabled:text-surface-500 dark:disabled:bg-surface-700 dark:disabled:text-surface-400 disabled:opacity-100
+        placeholder:text-surface-500 dark:placeholder:text-surface-400
+        transition-colors
+        outline-none;
+    border-radius: var(--p-form-field-border-radius);
+    padding: var(--p-form-field-padding-y) var(--p-form-field-padding-x);
+    transition-duration: var(--p-form-field-transition-duration);
+    box-shadow: var(--p-form-field-shadow);
+}
+
+.p-inputtext.p-invalid {
+    @apply border-danger-400 dark:border-danger-300
+}
+
+.p-inputtext.p-variant-filled {
+    @apply bg-surface-50 dark:bg-surface-800
+}
+
+.p-inputtext-sm {
+    @apply text-sm;
+    padding: var(--p-form-field-sm-padding-y) var(--p-form-field-sm-padding-x);
+}
+
+.p-inputtext-xs {
+    @apply text-xs px-2 py-1
+}
+
+.p-inputtext-lg {
+    @apply text-lg;
+    padding: var(--p-form-field-lg-padding-y) var(--p-form-field-lg-padding-x);
+}
+
+.p-inputtext-fluid {
+    @apply w-full
+}

package/primevue-plugin.ts

@@ -5,6 +5,9 @@ import { createCommentVNode, h, renderSlot, Teleport } from 'vue'
 
 const LAYER_ATTR = 'data-wippy-overlay-layer'
 
+/** A per-overlay layer div carrying its overlay's trigger anchor-name for the observer. */
+interface LayerWithAnchor extends HTMLElement { __wippyAnchorName?: string }
+
 /**
  * Client (browser) guard, equivalent to `@primeuix/utils`' `isClient` — inlined so
  * this plugin (which ships as raw `.ts` that every consumer typechecks) takes no
@@ -15,6 +18,135 @@ function isClient(): boolean {
   return typeof window !== 'undefined' && typeof window.document !== 'undefined'
 }
 
+/**
+ * The browser Popover API (and thus the top layer) is available.
+ *
+ * We promote each overlay's own layer into the document's **top layer**
+ * so overlays escape every ancestor stacking context in that document — nested
+ * shadow hosts, sticky toolbars, a later sibling's positive `z-index` — for BOTH
+ * paint and hit-testing, with no `z-index` anywhere. The overlay stays inside its
+ * owning shadow root, so module-local CSS and inherited `--p-*` tokens are
+ * untouched (inheritance follows the flat tree, not the top-layer position). Widely
+ * available in modern engines (Chrome/Edge 114+, Firefox 125+, Safari 17+); older
+ * engines fall back to the pinned-layer-only behavior below (stacking imperfect,
+ * everything else unchanged). Evaluated lazily so SSR never touches `HTMLElement`.
+ */
+function supportsTopLayer(): boolean {
+  return (
+    isClient()
+    && typeof HTMLElement !== 'undefined'
+    && Object.hasOwn(HTMLElement.prototype, 'popover')
+  )
+}
+
+/**
+ * CSS anchor positioning is available (S2). Implies the top layer. Lets a promoted
+ * overlay anchor to its trigger with pure CSS — no JS reposition loop — for the
+ * SELF-ANCHORED overlay families whose PrimeVue panel aligns to the component root,
+ * which is the Portal placeholder's DOM parent (`Select`, `MultiSelect`, `TreeSelect`,
+ * `CascadeSelect` — live-verified on `Select`; the others share the same align-to-root
+ * shape. `AutoComplete` is excluded — see {@link SELF_ANCHORED_OVERLAY}). Chrome/Edge
+ * 125+, Firefox 147+, Safari 26+. Anything else (older engine, or menus / popovers that
+ * align to an arbitrary caller-supplied target) keeps S1's pinned-layer positioning. S2 runs
+ * only behind this feature gate, and `applyAnchor` restores PrimeVue's own inline positioning
+ * verbatim (S1) if a promoted overlay can't enter the top layer — so the stacking fix always
+ * holds and positioning never regresses.
+ * (Tooltips never reach this plugin at all: PrimeVue's Tooltip is a directive that
+ * appends to `document.body`, outside `primevue/portal`.)
+ */
+function supportsAnchor(): boolean {
+  return (
+    supportsTopLayer()
+    && typeof CSS !== 'undefined'
+    && typeof CSS.supports === 'function'
+    && CSS.supports('anchor-name: --a')
+    && CSS.supports('top', 'anchor(--a bottom)')
+  )
+}
+
+/**
+ * Overlay classes whose panel aligns to the COMPONENT ROOT — the Portal placeholder's
+ * DOM parent — so a unique `anchor-name` stamped on that root is the correct CSS anchor.
+ * `AutoComplete` is deliberately EXCLUDED: it aligns its panel to an inner element
+ * (`$refs.focusInput`/`multiContainer`), not the root, so anchoring to the root would
+ * offset it; it keeps S1 (PrimeVue's own positioning against the correct element).
+ */
+const SELF_ANCHORED_OVERLAY = /\bp-(?:select|multiselect|treeselect|cascadeselect)-overlay\b/
+
+/** Sequential id for per-trigger `anchor-name`s — collision-free and readable (Math.random isn't). */
+let anchorSeq = 0
+
+/** Per-overlay observer that re-applies S2 styles when PrimeVue re-aligns the overlay. */
+const anchorStyleObservers = new WeakMap<HTMLElement, MutationObserver>()
+
+/** Write the S2 positioning declarations that make the overlay a fixed, anchored popover. */
+function setAnchorStyles(overlay: HTMLElement, anchorName: string): void {
+  const s = overlay.style
+  // Own `position:fixed` top-layer popover: promotion needs a popover, and `fixed` gives
+  // the viewport containing block that `anchor()` and the top layer resolve against
+  // (instead of the pinned 0×0 layer). PrimeVue's theme border/background/padding still
+  // win over the UA `[popover]` box (author > UA); we override only positioning.
+  s.setProperty('position', 'fixed', 'important')
+  s.setProperty('inset', 'auto', 'important')
+  s.setProperty('margin', '0', 'important')
+  s.setProperty('position-anchor', anchorName)
+  s.setProperty('top', `anchor(${anchorName} bottom)`, 'important')
+  s.setProperty('left', `anchor(${anchorName} left)`, 'important')
+  s.setProperty('position-try-fallbacks', 'flip-block')
+}
+
+/**
+ * S2: make a self-anchored overlay its own fixed, CSS-anchored top-layer popover (no-op
+ * for other overlays — they keep S1).
+ *
+ * PrimeVue keeps RE-aligning the overlay while it is open (`alignOverlay()` on every
+ * filter keystroke), plain-writing `top`/`margin` on the same
+ * inline `style`. Since an inline style has ONE slot per property, that plain write
+ * REPLACES our `!important` value+priority — so a one-shot write is not durable. We
+ * therefore also watch the overlay's own `style` and re-apply whenever PrimeVue clobbers
+ * it; the guard (`top` is no longer `!important`) makes the re-apply idempotent (never a
+ * loop). The observer is released when the overlay leaves its layer ({@link releaseAnchor}).
+ */
+function applyAnchor(overlay: HTMLElement, anchorName: string): void {
+  if (!SELF_ANCHORED_OVERLAY.test(overlay.className))
+    return
+  const restore = overlay.style.cssText
+  setAnchorStyles(overlay, anchorName)
+  if (overlay.getAttribute('popover') !== 'manual')
+    overlay.setAttribute('popover', 'manual')
+  try {
+    if (!overlay.matches(':popover-open'))
+      overlay.showPopover()
+  }
+  catch { /* not connected / already open */ }
+  if (!overlay.matches(':popover-open')) {
+    // Promotion didn't take — restore PrimeVue's ORIGINAL inline styles verbatim (rather
+    // than clearing the S2 properties piecemeal, which would also wipe the top/left/margin
+    // PrimeVue computed for the overlay), so it degrades to a correctly-positioned S1
+    // overlay inside the layer.
+    overlay.removeAttribute('popover')
+    overlay.style.cssText = restore
+    return
+  }
+  if (!anchorStyleObservers.has(overlay)) {
+    const obs = new MutationObserver(() => {
+      if (overlay.style.getPropertyPriority('top') !== 'important')
+        setAnchorStyles(overlay, anchorName)
+    })
+    obs.observe(overlay, { attributes: true, attributeFilter: ['style'] })
+    anchorStyleObservers.set(overlay, obs)
+  }
+}
+
+/** Detach an overlay's S2 style observer once it leaves its layer (closed) or unmounts. */
+function releaseAnchor(overlay: HTMLElement): void {
+  const obs = anchorStyleObservers.get(overlay)
+  if (obs) {
+    obs.disconnect()
+    anchorStyleObservers.delete(overlay)
+  }
+}
+
 /** The `ShadowRoot` a node lives in, or null (light DOM). */
 function shadowRootOf(el: Node | null): ShadowRoot | null {
   const root = el && typeof el.getRootNode === 'function' ? el.getRootNode() : null
@@ -40,7 +172,10 @@ function shadowRootOf(el: Node | null): ShadowRoot | null {
  * origin; we then offset by it plus the scroll. This holds for any
  * TRANSLATION-only containing block and any window scroll.
  *
- * Residuals (documented):
+ * Residuals (documented) — these apply ONLY to the degraded, non-top-layer fallback
+ * (older engines, {@link supportsTopLayer} false). Once the layer is promoted (the
+ * primary path), its containing block is unconditionally the viewport, so the measured
+ * rect at `top:0;left:0` is (0,0) and none of these arise:
  *  - SCALE / ROTATE / SKEW containing block: compensating via CSS `top`/`left`
  *    only cancels the containing block's translation, not a non-identity linear
  *    transform, so a `scale()`/`rotate()`/`skew()` ancestor mispositions the
@@ -67,10 +202,11 @@ function syncLayer(layer: HTMLElement): void {
   layer.style.left = `${-window.scrollX - rect.left}px`
 }
 
-// A SINGLE viewport-driven resync loop shared by every shadow-root layer — not a
-// listener pair per layer. When a `view.component` unmounts, its layer detaches with
-// the shadow root; this loop prunes detached layers on the next scroll/resize, so a
-// mount/unmount cycle leaks no window listeners, observers, or detached subtree.
+// A SINGLE viewport-driven resync loop shared by every per-overlay layer — not a
+// listener pair per layer. Layers are removed by `teardownOverlayLayer` (on unmount or a
+// switch to inline); this loop is the backstop that also prunes any layer whose shadow
+// root detached out from under it (e.g. a `view.component` torn down), so a cycle leaks
+// no window listener, observer, or detached subtree.
 const activeLayers = new Set<HTMLElement>()
 const layerObservers = new WeakMap<HTMLElement, MutationObserver>()
 let viewportListenersAttached = false
@@ -80,6 +216,12 @@ function syncActiveLayers(): void {
   viewportSyncScheduled = false
   for (const layer of activeLayers) {
     if (!layer.isConnected) {
+      // Backstop for a layer whose shadow root detached without the Portal's `unmounted`
+      // running: release any overlay's S2 observer too (symmetry with `unmounted`).
+      for (const child of Array.from(layer.children)) {
+        if (child instanceof HTMLElement)
+          releaseAnchor(child)
+      }
       activeLayers.delete(layer)
       layerObservers.get(layer)?.disconnect()
       continue
@@ -97,19 +239,60 @@ function onViewportChange(): void {
 }
 
 /**
- * Get (or create) the per-shadow-root overlay layer, pinned to viewport origin and
- * kept in sync as overlays open (a per-layer `MutationObserver`) and as the page
- * scrolls/resizes (the one shared listener pair over {@link activeLayers}).
+ * Create a fresh per-OVERLAY layer (one per Portal instance, NOT shared per shadow root),
+ * pinned to viewport origin and kept in sync as its overlay opens (a per-layer
+ * `MutationObserver`) and as the page scrolls/resizes (the one shared listener pair over
+ * {@link activeLayers}). One overlay per layer keeps S2 anchor routing unambiguous even
+ * for components that open several overlays at once; {@link teardownOverlayLayer} removes
+ * it on unmount or a switch to inline.
  */
-function ensureLayer(root: ShadowRoot): HTMLElement {
-  const existing = root.querySelector<HTMLElement>(`[${LAYER_ATTR}]`)
-  if (existing)
-    return existing
-
+function createLayer(root: ShadowRoot): HTMLElement {
   const layer = document.createElement('div')
   layer.setAttribute(LAYER_ATTR, '')
-  layer.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;'
+  const topLayer = supportsTopLayer()
+  // Inline reset of the UA `[popover]` styling — scoped to this one private element,
+  // NEVER a global rule that could leak across modules. A shown popover gets the UA
+  // box (position:fixed; inset:0; margin:auto; width/height:fit-content; border:solid;
+  // padding; background:Canvas; color:CanvasText). Left unreset, our empty 0×0 layer
+  // paints as a small white BORDERED box centered in the viewport (margin:auto + inset:0),
+  // and recolors the teleported overlay's text through inheritance. We zero every UA-set
+  // box property (including margin, so our syncLayer-owned top/left position it at origin);
+  // `color:inherit` restores the shadow-host inheritance chain for the teleported
+  // overlay; `overflow:visible` lets the absolutely-positioned overlay paint outside
+  // the 0×0 box. `!important` guards against a non-compliant theme's `[popover]` rule.
+  // `top`/`left` are deliberately OMITTED and left author-normal — syncLayer owns them,
+  // and its plain setProperty must keep winning (so we also never set `inset`, whose
+  // longhands would otherwise fight syncLayer's top/left).
+  layer.style.cssText = topLayer
+    ? 'position:fixed;width:0 !important;height:0 !important;margin:0 !important;border:0 !important;padding:0 !important;background:transparent !important;color:inherit !important;overflow:visible !important;'
+    : 'position:fixed;top:0;left:0;width:0;height:0;'
+  if (topLayer)
+    layer.setAttribute('popover', 'manual')
   root.appendChild(layer)
+  if (topLayer) {
+    // Enter the top layer. `manual` never light-dismisses, so PrimeVue stays the sole
+    // controller of open/close, Escape, and outside-click; focus stays untouched too, since
+    // neither the bare layer div nor PrimeVue's overlay markup carries an `autofocus` target
+    // for the popover focusing steps to act on (those run regardless of popover type).
+    // `teardownOverlayLayer` removes the layer (on unmount or a switch to inline),
+    // evicting it from the top layer; syncActiveLayers is the backstop if the shadow root
+    // detaches first.
+    try {
+      layer.showPopover()
+    }
+    catch {
+      // showPopover only throws if disconnected/already-open; the degrade below covers
+      // a layer that ended up not promoted regardless of throw-vs-silent-noop.
+    }
+    if (!layer.matches(':popover-open')) {
+      // Promotion did not take. NEVER leave `popover` set on a not-open element: the
+      // UA rule `[popover]:not(:popover-open){display:none}` would hide the layer AND
+      // every overlay teleported into it — silently worse than the original bug.
+      // Degrade cleanly to the pinned-layer-only behavior (syncLayer still positions).
+      layer.removeAttribute('popover')
+      layer.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;'
+    }
+  }
   syncLayer(layer)
 
   // Re-pin whenever an overlay is inserted — it may open after the page scrolled or
@@ -117,7 +300,23 @@ function ensureLayer(root: ShadowRoot): HTMLElement {
   // the layer's own style, so it never re-triggers this childList observer. The
   // observer is referenced only via the WeakMap, so it is disconnected when the layer
   // detaches (in syncActiveLayers) and otherwise GC'd with the layer.
-  const observer = new MutationObserver(() => {
+  const observer = new MutationObserver((records) => {
+    // S2: this layer serves exactly ONE overlay (one Portal instance), so its
+    // `__wippyAnchorName` — the trigger anchor-name stamped by `setupOverlayLayer` — is unambiguous.
+    // Anchor the overlay when it teleports in; release its style observer when it leaves.
+    const anchorName = (layer as LayerWithAnchor).__wippyAnchorName
+    for (const rec of records) {
+      if (anchorName) {
+        for (const node of Array.from(rec.addedNodes)) {
+          if (node instanceof HTMLElement)
+            applyAnchor(node, anchorName)
+        }
+      }
+      for (const node of Array.from(rec.removedNodes)) {
+        if (node instanceof HTMLElement)
+          releaseAnchor(node)
+      }
+    }
     if (layer.isConnected && layer.childElementCount > 0)
       syncLayer(layer)
   })
@@ -143,6 +342,7 @@ interface PortalOptions {
   computed?: Record<string, (this: PortalInstance) => unknown>
   data?: (this: PortalInstance) => Record<string, unknown>
   mounted?: (this: PortalInstance) => void
+  unmounted?: (this: PortalInstance) => void
   render?: (this: PortalInstance) => VNode
 }
 
@@ -157,7 +357,54 @@ interface PortalInstance {
   mounted: boolean
   /** The shadow root this overlay lives in (captured once on mount), or null. */
   hostRoot: ShadowRoot | null
+  /** This overlay's OWN layer div (one per Portal instance); null in light DOM or while inline. */
+  layer: HTMLElement | null
+  /** Unique `anchor-name` wired onto this overlay's trigger for S2, or null. */
+  anchorName: string | null
+  /** The trigger element the anchor-name was stamped on (to clear it on teardown). */
+  anchorTrigger: HTMLElement | null
   resolvedTarget: Element | string | null
+  /** Vue instance watcher — used to react to `inline` toggling after mount. */
+  $watch: (source: string, cb: (value: boolean) => void) => () => void
+}
+
+/** Create this overlay's layer and wire its S2 anchor. Idempotent per instance. */
+function setupOverlayLayer(inst: PortalInstance): void {
+  if (!inst.hostRoot || inst.layer)
+    return
+  // Eager: the layer is promoted to the top layer BEFORE the overlay opens, so PrimeVue
+  // never measures a not-yet-promoted box.
+  inst.layer = createLayer(inst.hostRoot)
+  // S2: stamp a unique `anchor-name` on the trigger (the placeholder's parent is the
+  // component root the self-anchored families align to) and hand it to this layer.
+  if (supportsAnchor()) {
+    const trigger = inst.$el ? (inst.$el as Node).parentElement : null
+    if (trigger) {
+      inst.anchorName = `--wippy-a-${++anchorSeq}`
+      inst.anchorTrigger = trigger
+      trigger.style.setProperty('anchor-name', inst.anchorName)
+      ;(inst.layer as LayerWithAnchor).__wippyAnchorName = inst.anchorName
+    }
+  }
+}
+
+/** Remove this overlay's layer and undo its S2 wiring (on unmount or a switch to inline). */
+function teardownOverlayLayer(inst: PortalInstance): void {
+  if (inst.anchorTrigger) {
+    inst.anchorTrigger.style.removeProperty('anchor-name')
+    inst.anchorTrigger = null
+  }
+  inst.anchorName = null
+  if (inst.layer) {
+    for (const child of Array.from(inst.layer.children)) {
+      if (child instanceof HTMLElement)
+        releaseAnchor(child)
+    }
+    activeLayers.delete(inst.layer)
+    layerObservers.get(inst.layer)?.disconnect()
+    inst.layer.remove()
+    inst.layer = null
+  }
 }
 
 let patched = false
@@ -169,8 +416,8 @@ let patched = false
  * PrimeVue 4 has no global `appendTo` config, and the `@primeuix/utils` positioning
  * helpers are immutable ESM bindings. But every overlay teleports through the ONE
  * shared `primevue/portal`, whose options object is a mutable singleton. We rewrite it
- * so the DEFAULT `appendTo` (`'body'`, or null/undefined) teleports to a per-shadow-root
- * layer ({@link ensureLayer}) that is measured-and-pinned to true viewport origin
+ * so the DEFAULT `appendTo` (`'body'`, or null/undefined) teleports to a per-overlay
+ * layer ({@link createLayer}) that is measured-and-pinned to true viewport origin
  * ({@link syncLayer}) instead of `document.body`.
  *
  * Because `appendTo` is then not `'self'`, PrimeVue positions with `absolutePosition`
@@ -194,44 +441,68 @@ export function patchOverlayPortal(): void {
   portal.computed.inline = function (this: PortalInstance) {
     return Boolean(this.disabled) || this.appendTo === 'self'
   }
-  // Reactive to `appendTo`: the default ('body'/null) resolves to the shadow-root
+  // Reactive to `appendTo`: the default ('body'/null) resolves to this overlay's own
   // layer (or document.body in light DOM); an explicit target passes through.
   portal.computed.resolvedTarget = function (this: PortalInstance) {
     if (this.appendTo == null || this.appendTo === 'body')
-      return this.hostRoot ? ensureLayer(this.hostRoot) : document.body
+      return this.hostRoot ? this.layer : document.body
     return this.appendTo as Element | string
   }
 
   portal.data = function (this: PortalInstance) {
-    return { mounted: false, hostRoot: null }
+    return { mounted: false, hostRoot: null, layer: null, anchorName: null, anchorTrigger: null }
   }
 
   portal.mounted = function (this: PortalInstance) {
     // Match upstream Portal: teleport is client-only. Guards DOM access below
-    // (ensureLayer → createElement) if this ever runs without a document.
+    // (createLayer → createElement) if this ever runs without a document.
     if (!isClient())
       return
     // `$el` here is the placeholder comment node — capture its shadow root once.
     this.hostRoot = shadowRootOf(this.$el)
     this.mounted = true
-    // Ensure the layer (and its resync observers) exist before the first render.
-    // The per-open re-pin is driven by the layer's MutationObserver, not here —
-    // this hook fires when the overlay component mounts, not when it opens.
-    if (this.hostRoot)
-      ensureLayer(this.hostRoot)
+    // Light DOM (no shadow root) always teleports to document.body — no layer, ever.
+    if (!this.hostRoot)
+      return
+    // Create the layer now if this overlay teleports; skip it while inline
+    // (`appendTo:'self'`/`disabled`) so nothing is allocated unused.
+    if (!this.inline)
+      setupOverlayLayer(this)
+    // `inline` is a computed over reactive props, and consumers DO flip `appendTo`
+    // ('body'↔'self') after mount (e.g. `use-shadow-append-to`). Mirror the layer
+    // lifecycle on that toggle: a switch to inline tears down the now-unused layer
+    // instead of orphaning it; a switch back re-creates it (else `resolvedTarget` would
+    // fall back to document.body, breaking out of the shadow root). Auto-cleaned on unmount.
+    this.$watch('inline', (nowInline) => {
+      if (nowInline)
+        teardownOverlayLayer(this)
+      else
+        setupOverlayLayer(this)
+    })
   }
 
   portal.render = function (this: PortalInstance) {
-    // Keys mirror upstream's `key: 0`/`key: 1` so Vue replaces (never patches)
-    // across the inline↔teleport branches if `inline` ever toggles reactively.
+    // The inline / teleport / not-yet-mounted branches return different vnode TYPES
+    // (slot fragment vs Teleport vs comment), so Vue replaces (never patches) across them
+    // if `inline` toggles reactively; the `key`s mirror upstream Portal's for parity.
     if (this.inline)
       return renderSlot(this.$slots as never, 'default', { key: 0 }) as unknown as VNode
     if (!this.mounted)
       return createCommentVNode('', true)
+    // Teleport the overlay AS-IS, a direct child of this overlay's own layer. Its
+    // anchor-name rides on the layer (set by `setupOverlayLayer`), so the observer anchors
+    // it — no per-render vnode surgery, so PrimeVue's overlay markup is untouched.
     return h(Teleport, { key: 1, to: this.resolvedTarget || document.body } as never, [
       renderSlot(this.$slots as never, 'default'),
     ])
   }
+
+  portal.unmounted = function (this: PortalInstance) {
+    // Each overlay OWNS its layer, so it removes it (and undoes its S2 wiring) on unmount
+    // — no orphaned 0×0 popovers, observers, listeners, or stale `anchor-name` across
+    // mount/unmount cycles. (The old shared per-root layer detached with the shadow root.)
+    teardownOverlayLayer(this)
+  }
 }
 
 export const PrimeVuePlugin = {