@leavepulse/ui 0.58.1 → 0.60.0

package/src/components/LpContextMenu.vue

@@ -8,6 +8,8 @@
  */
 import { ContextMenuContent, ContextMenuPortal, ContextMenuRoot, ContextMenuTrigger } from "reka-ui"
 import { computed } from "vue"
+import { hints } from "../composables/useHints"
+import { HINT_SIGNALS } from "../composables/useHintSystem"
 import ContextMenuItems from "./ContextMenuItems.vue"
 import MenuTitle from "./MenuTitle.vue"
 import { POPOVER_PANEL } from "./dropdown"
@@ -52,6 +54,11 @@ const props = defineProps<{
   /** An icon beside the title, or `titleImage` for a picture (an avatar, a logo). */
   titleIcon?: string
   titleImage?: string
+  /**
+   * Do not count this element as "has a right-click menu" for hint tips: for
+   * menus that only hold generic items (a whole table without row actions).
+   */
+  noHint?: boolean
 }>()
 
 // With no items the trigger is disabled, so the element keeps the browser's
@@ -59,6 +66,7 @@ const props = defineProps<{
 // per element. `always` overrides this so a late-populated menu is ready on the
 // very first click.
 const enabled = computed(() => props.always || props.items.length > 0)
+const hinted = computed(() => enabled.value && !props.noHint)
 
 const PANEL = `${POPOVER_PANEL} z-(--z-popover) min-w-48 p-1 outline-none`
 
@@ -91,6 +99,14 @@ function keepContextMenu(event: Event) {
   if (enabled.value) event.stopPropagation()
 }
 
+function opened(open: boolean) {
+  if (open) hints.use(HINT_SIGNALS.contextMenu)
+}
+
+function leftClick() {
+  if (hinted.value) hints.use(HINT_SIGNALS.contextTarget)
+}
+
 function returnFocus(event: Event) {
   const saved = field
   field = null
@@ -106,10 +122,12 @@ function returnFocus(event: Event) {
        the reka trigger remounted the wrapped content whenever items arrived
        late, losing its state and focus. A disabled trigger leaves the browser's
        own menu in place. -->
-  <ContextMenuRoot>
+  <ContextMenuRoot @update:open="opened">
     <ContextMenuTrigger
       as-child
       :disabled="!enabled"
+      :data-lp-context-menu="hinted ? '' : undefined"
+      @click.capture="leftClick"
       @contextmenu.capture="rememberField"
       @contextmenu="keepContextMenu"
     >

package/src/components/LpDrawer.vue

@@ -552,7 +552,7 @@ const previewStyle = computed(() => {
             </DrawerDescription>
           </div>
           <DrawerClose
-            class="group flex shrink-0 items-center rounded-md p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
+            class="group flex shrink-0 items-center rounded-inner p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
             :aria-label="text.close"
           >
             <LpIcon

package/src/components/LpDropdownMenu.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { hints } from "../composables/useHints"
+import { HINT_SIGNALS } from "../composables/useHintSystem"
 import {
   DropdownMenuContent,
   DropdownMenuItem,
@@ -20,18 +22,27 @@ export interface MenuItem {
   onSelect?: () => void
 }
 
-defineProps<{
+const props = defineProps<{
   items: MenuItem[]
   /** A heading naming what the menu acts on; see LpContextMenu's `title`. */
   title?: string
   subtitle?: string
   titleIcon?: string
   titleImage?: string
+  /**
+   * The same items are also on a right click (a row's "…" next to its context
+   * menu). Opening it then counts toward the hint system's right-click tip.
+   */
+  rightClickToo?: boolean
 }>()
+
+function opened(open: boolean) {
+  if (open && props.rightClickToo) hints.use(HINT_SIGNALS.menuButton)
+}
 </script>
 
 <template>
-  <DropdownMenuRoot>
+  <DropdownMenuRoot @update:open="opened">
     <DropdownMenuTrigger as-child>
       <slot name="trigger" />
     </DropdownMenuTrigger>
@@ -47,7 +58,7 @@ defineProps<{
         <template v-for="(item, i) in items" :key="i">
           <DropdownMenuSeparator v-if="item.separatorBefore" class="my-1 h-px bg-line" />
           <DropdownMenuItem
-            class="group/item flex cursor-pointer items-center gap-2 rounded-md px-2.5 py-1.5 text-sm outline-none transition-[background-color,color] duration-[var(--duration-fast)] data-[disabled]:pointer-events-none data-[disabled]:opacity-45 data-[highlighted]:bg-brand-soft"
+            class="group/item flex cursor-pointer items-center gap-2 rounded-inner px-2.5 py-1.5 text-sm outline-none transition-[background-color,color] duration-[var(--duration-fast)] data-[disabled]:pointer-events-none data-[disabled]:opacity-45 data-[highlighted]:bg-brand-soft"
             :class="item.danger ? 'text-danger data-[highlighted]:bg-danger-soft data-[highlighted]:text-danger' : 'text-ink data-[highlighted]:text-brand'"
             :disabled="item.disabled"
             @select="item.onSelect?.()"

package/src/components/LpHints.vue

@@ -68,6 +68,7 @@ const title = computed(() => {
   const o = offer.value
   if (!o) return ""
   if (o.kind === "nudge") return notes.value[o.nudge.feature]?.title ?? ""
+  if (o.kind === "tip") return o.tip.title
   if (o.kind === "news") return fill(labels.value.newsTitle)
   return fill(o.kind === "assigned" ? labels.value.assignedTitle : labels.value.tourTitle)
 })
@@ -76,6 +77,7 @@ const description = computed(() => {
   const o = offer.value
   if (!o) return ""
   if (o.kind === "nudge") return o.nudge.text
+  if (o.kind === "tip") return o.tip.keys ? `${o.tip.text} ${o.tip.keys}` : o.tip.text
   if (o.kind === "news") return o.items.map((n) => n.text).join(" ")
   return o.kind === "assigned" ? labels.value.assignedText : labels.value.tourText
 })
@@ -86,6 +88,10 @@ const actions = computed<ActionBarAction[]>(() => {
   const answer = (choice: "show" | "later" | "never") => () => props.system.answer(choice)
   const show: ActionBarAction = { label: labels.value.show, icon: "lucide:sparkles", onClick: answer("show") }
   if (o.kind === "nudge") return [{ label: labels.value.noThanks, variant: "ghost", onClick: answer("never") }, show]
+  if (o.kind === "tip") {
+    const later: ActionBarAction = { label: labels.value.gotIt, variant: o.tip.step ? "ghost" : undefined, onClick: answer("later") }
+    return [{ label: labels.value.never, variant: "ghost", onClick: answer("never") }, later, ...(o.tip.step ? [show] : [])]
+  }
   if (o.kind === "news") return [{ label: labels.value.gotIt, variant: "ghost", onClick: answer("later") }, show]
   return [
     ...(o.kind === "tour" ? [{ label: labels.value.never, variant: "ghost" as const, onClick: answer("never") }] : []),
@@ -109,7 +115,7 @@ const actions = computed<ActionBarAction[]>(() => {
       :open="!!offer"
       :title="title"
       :description="description"
-      :icon="offer?.kind === 'news' ? 'lucide:gift' : 'lucide:compass'"
+      :icon="offer?.kind === 'news' ? 'lucide:gift' : offer?.kind === 'tip' ? 'lucide:lightbulb' : 'lucide:compass'"
       :actions="actions"
     />
   </template>

package/src/components/LpModal.vue

@@ -350,7 +350,7 @@ watch(
                and last in usefulness. Still reachable by Tab and Escape. -->
           <DialogClose
             data-lp-dialog-close
-            class="group flex shrink-0 items-center rounded-md p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
+            class="group flex shrink-0 items-center rounded-inner p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
             :aria-label="text.close"
           >
             <LpIcon

package/src/components/LpNotificationBell.vue

@@ -321,7 +321,7 @@ function timeAgo(iso?: string): string {
         <button
           v-if="items.length && handlesClear"
           type="button"
-          class="rounded-md px-1.5 py-0.5 text-xs font-medium text-muted outline-none transition-colors hover:bg-surface-soft hover:text-ink focus-visible:bg-surface-soft"
+          class="rounded-inner px-1.5 py-0.5 text-xs font-medium text-muted outline-none transition-colors hover:bg-surface-soft hover:text-ink focus-visible:bg-surface-soft"
           @click="emit('clear')"
         >
           {{ l.clear }}
@@ -329,7 +329,7 @@ function timeAgo(iso?: string): string {
         <button
           v-if="hasUnread"
           type="button"
-          class="rounded-md px-1.5 py-0.5 text-xs font-medium text-brand outline-none transition-colors hover:bg-brand-soft focus-visible:bg-brand-soft"
+          class="rounded-inner px-1.5 py-0.5 text-xs font-medium text-brand outline-none transition-colors hover:bg-brand-soft focus-visible:bg-brand-soft"
           @click="emit('markAllRead')"
         >
           {{ l.markAllRead }}

package/src/components/LpPasswordInput.vue

@@ -53,7 +53,7 @@ defineExpose({
     <template #trailing>
       <button
         type="button"
-        class="group rounded-md p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:text-ink"
+        class="group rounded-inner p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:text-ink"
         :aria-label="visible ? text.hide : text.show"
         @click="visible = !visible"
       >

package/src/components/LpPhoneInput.vue

@@ -398,7 +398,7 @@ const inputAttrs = computed(() => {
               :model-value="query"
               :placeholder="searchPlaceholder"
               auto-focus
-              class="h-(--size-control-sm) w-full rounded-md border border-line bg-surface-soft px-2.5 text-sm text-ink outline-none placeholder:text-muted focus:border-brand"
+              class="h-(--size-control-sm) w-full rounded-inner border border-line bg-surface-soft px-2.5 text-sm text-ink outline-none placeholder:text-muted focus:border-brand"
               @input="query = ($event.target as HTMLInputElement).value"
             />
           </div>

package/src/components/LpPie.vue

@@ -835,7 +835,7 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
             v-for="(a, i) in arcs"
             :key="`${i}-${a.label}`"
             type="button"
-            class="group flex cursor-pointer items-center gap-2 rounded-md px-1 py-0.5 text-xs outline-none transition-[opacity,background-color] duration-fast focus-visible:ring-2 focus-visible:ring-ring"
+            class="group flex cursor-pointer items-center gap-2 rounded-inner px-1 py-0.5 text-xs outline-none transition-[opacity,background-color] duration-fast focus-visible:ring-2 focus-visible:ring-ring"
             :class="[dimmed(i) ? 'opacity-45' : '', isSelected(i) ? 'bg-surface-soft' : '']"
             :aria-pressed="isSelected(i)"
             @pointerenter="onSlicePointerEnter(i)"

package/src/components/LpSegmented.vue

@@ -95,7 +95,7 @@ const pillTransition = usePillTransition()
       :key="opt.value"
       :value="opt.value"
       :aria-label="opt.ariaLabel ?? (opt.label ? undefined : opt.value)"
-      class="relative inline-flex h-full items-center justify-center gap-1.5 rounded-md px-3 font-medium outline-none transition-colors duration-[var(--duration-fast)] ease-[var(--ease-emphasized)] focus-visible:ring-2 focus-visible:ring-ring data-[state=on]:text-ink data-[state=off]:text-muted data-[state=off]:hover:text-ink disabled:cursor-not-allowed disabled:opacity-55"
+      class="relative inline-flex h-full items-center justify-center gap-1.5 rounded-inner px-3 font-medium outline-none transition-colors duration-[var(--duration-fast)] ease-[var(--ease-emphasized)] focus-visible:ring-2 focus-visible:ring-ring data-[state=on]:text-ink data-[state=off]:text-muted data-[state=off]:hover:text-ink disabled:cursor-not-allowed disabled:opacity-55"
       :class="block ? 'flex-1' : ''"
     >
       <!-- Sliding pill behind the active segment. -->
@@ -103,7 +103,7 @@ const pillTransition = usePillTransition()
         v-if="opt.value === modelValue"
         :layout-id="pillId"
         :transition="pillTransition"
-        class="absolute inset-0 z-0 rounded-md border border-line bg-surface-raised shadow-sm"
+        class="absolute inset-0 z-0 rounded-inner border border-line bg-surface-raised shadow-sm"
       />
       <LpIcon v-if="opt.icon" :name="opt.icon" :size="14" class="relative z-10 shrink-0" />
       <span v-if="opt.label" class="relative z-10">{{ opt.label }}</span>

package/src/components/LpSidebarNav.vue

@@ -103,8 +103,8 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
     <div v-if="skeletonHeader" class="flex items-center gap-3 px-1">
       <div class="size-10 shrink-0 animate-pulse rounded-pill bg-surface-soft" />
       <div class="flex-1 space-y-2">
-        <div class="h-3.5 w-24 animate-pulse rounded bg-surface-soft" />
-        <div class="h-3 w-16 animate-pulse rounded bg-surface-soft/60" />
+        <div class="h-3.5 w-24 animate-pulse rounded-small bg-surface-soft" />
+        <div class="h-3 w-16 animate-pulse rounded-small bg-surface-soft/60" />
       </div>
     </div>
     <div class="space-y-1">

package/src/components/LpTable.vue

@@ -1157,7 +1157,7 @@ const barInsetTop = computed(() =>
     <!-- The table-wide menu, which is what a right-click on empty header space
          reaches: rows and headers carry their own and take the event first, so
          this is the fallback rather than a competitor. -->
-    <LpContextMenu :items="contextMenu" always>
+    <LpContextMenu :items="contextMenu" always :no-hint="!rowMenu">
     <table ref="tableEl" class="w-full border-collapse text-sm">
       <!-- The background belongs on `thead` itself, not only on its row:
            `border-collapse` collapses the borders, and with a sticky header the
@@ -1201,7 +1201,7 @@ const barInsetTop = computed(() =>
             <LpContextMenu v-if="col.sortable || col.filterable" :items="headerMenu(col)">
             <button
               type="button"
-              class="group/sort -mx-1 inline-flex items-center gap-1 rounded px-1 outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
+              class="group/sort -mx-1 inline-flex items-center gap-1 rounded-small px-1 outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
               :class="[
                 col.align === 'right' ? 'flex-row-reverse' : '',
                 activeSort?.key === col.key ? 'text-ink' : '',
@@ -1232,7 +1232,7 @@ const barInsetTop = computed(() =>
               <template #trigger>
                 <button
                   type="button"
-                  class="ml-0.5 inline-grid size-5 place-items-center rounded align-middle outline-none transition-colors duration-fast hover:bg-surface-raised hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
+                  class="ml-0.5 inline-grid size-5 place-items-center rounded-small align-middle outline-none transition-colors duration-fast hover:bg-surface-raised hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
                   :class="hiddenValues[col.key]?.size ? 'text-brand' : 'opacity-60'"
                   :aria-label="text.filterColumn.replace('{column}', col.label)"
                   :data-lp-filter="col.key"

package/src/components/LpTabs.vue

@@ -38,8 +38,14 @@ const props = withDefaults(
     block?: boolean
     /** Accessible name of the tab list, e.g. "Main" for an app's navigation. */
     label?: string
+    /**
+     * The marker glides under the hovered tab and springs back on leave (the
+     * default). False pins it to the selected tab: calmer for a dense header
+     * where the pointer crosses the bar on its way elsewhere.
+     */
+    hoverFollow?: boolean
   }>(),
-  { variant: "contained", accent: false, block: false },
+  { variant: "contained", accent: false, block: false, hoverFollow: true },
 )
 
 const bottom = computed(() => props.variant === "bottom")
@@ -154,12 +160,12 @@ function releaseFocusAfterPointer(event: PointerEvent) {
             ? 'min-h-14 min-w-0 flex-col gap-0.5 px-1 py-1.5 text-[11px] font-medium focus-visible:ring-inset'
             : 'shrink-0 gap-1.5 whitespace-nowrap text-sm',
           block && !bottom ? 'flex-1' : '',
-          variant === 'underline' ? 'rounded-t-md px-3 pt-1.5 pb-2' : '',
-          variant === 'contained' || variant === 'plain' ? 'rounded-md px-3 py-1.5' : '',
+          variant === 'underline' ? 'rounded-t-inner px-3 pt-1.5 pb-2' : '',
+          variant === 'contained' || variant === 'plain' ? 'rounded-inner px-3 py-1.5' : '',
           accent ? 'data-[state=active]:text-brand' : 'data-[state=active]:text-ink',
           hovered === item.value && !bottom ? 'text-ink' : 'text-muted',
         ]"
-        @pointerenter="hovered = item.value"
+        @pointerenter="hoverFollow && (hovered = item.value)"
         @pointerup="releaseFocusAfterPointer"
       >
         <!-- Active marker: a bar under the tab in "underline", over it in
@@ -180,7 +186,7 @@ function releaseFocusAfterPointer(event: PointerEvent) {
                   accent ? 'bg-brand' : 'bg-ink',
                 ]
               : [
-                  'absolute inset-0 z-0 rounded-md shadow-sm',
+                  'absolute inset-0 z-0 rounded-inner shadow-sm',
                   accent
                     ? 'border border-brand/35 bg-brand/12'
                     : 'border border-line bg-surface-raised',

package/src/components/LpToaster.vue

@@ -305,7 +305,7 @@ function runAction(t: ToastItem, action: NonNullable<ToastItem["actions"]>[numbe
         <button
           v-if="copyable(t)"
           type="button"
-          class="-mt-1 rounded-md p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
+          class="-mt-1 rounded-inner p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
           :aria-label="copiedId === tag(t) ? text.copied : text.copy"
           :title="copiedId === tag(t) ? text.copied : text.copy"
           @click.stop="copyToast(t)"
@@ -314,7 +314,7 @@ function runAction(t: ToastItem, action: NonNullable<ToastItem["actions"]>[numbe
         </button>
         <button
           type="button"
-          class="group -mr-1 -mt-1 rounded-md p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink"
+          class="group -mr-1 -mt-1 rounded-inner p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink"
           :aria-label="text.dismiss"
           @click.stop="beginClose(t)"
         >

package/src/components/LpTour.vue

@@ -270,10 +270,12 @@ watch(
     if (value) {
       direction = 1
       document.addEventListener("click", onTargetClick, true)
+      document.addEventListener("contextmenu", onTargetClick, true)
       frame ||= requestAnimationFrame(track)
       void show()
     } else {
       document.removeEventListener("click", onTargetClick, true)
+      document.removeEventListener("contextmenu", onTargetClick, true)
       end()
     }
   },
@@ -286,6 +288,7 @@ watch(index, () => {
 
 onBeforeUnmount(() => {
   document.removeEventListener("click", onTargetClick, true)
+  document.removeEventListener("contextmenu", onTargetClick, true)
   if (open.value) end()
 })
 

package/src/components/MenuTitle.vue

@@ -18,10 +18,10 @@ defineProps<{
 
 <template>
   <div class="flex max-w-72 min-w-0 items-center gap-2 px-2.5 pt-1.5 pb-2" aria-hidden="true">
-    <img v-if="image" :src="image" alt="" class="size-7 shrink-0 rounded-md object-cover" />
+    <img v-if="image" :src="image" alt="" class="size-7 shrink-0 rounded-inner object-cover" />
     <span
       v-else-if="icon"
-      class="grid size-7 shrink-0 place-items-center rounded-md bg-surface-soft text-muted"
+      class="grid size-7 shrink-0 place-items-center rounded-inner bg-surface-soft text-muted"
     >
       <LpIcon :name="icon" :size="15" />
     </span>

package/src/components/dropdown.ts

@@ -49,7 +49,7 @@ export const POPOVER_PANEL = PANEL_SURFACE + " " + POPOVER_ANIM
  * stagger. `flex` + gap are included; add justify/extra layout if needed.
  */
 export const OPTION_ITEM =
-  "flex cursor-pointer items-center gap-2 rounded-md px-2.5 py-1.5 text-sm text-ink outline-none " +
+  "flex cursor-pointer items-center gap-2 rounded-inner px-2.5 py-1.5 text-sm text-ink outline-none " +
   "animate-[option-in_180ms_var(--ease-emphasized)_both] " +
   "group-data-[side=top]:animate-[option-in-up_180ms_var(--ease-emphasized)_both] " +
   "data-[highlighted]:bg-brand-soft data-[highlighted]:text-brand"

package/src/composables/useHintSystem.ts

@@ -1,4 +1,4 @@
-import { computed, inject, provide, reactive, watch, type ComputedRef, type InjectionKey, type WatchStopHandle } from "vue"
+import { computed, inject, onBeforeUnmount, provide, reactive, shallowRef, watch, type ComputedRef, type InjectionKey, type WatchStopHandle } from "vue"
 import type { HintNote } from "../components/LpHintLayer.vue"
 import type { TourContext, TourStep } from "../components/LpTour.vue"
 import { anyModalOpen } from "../components/modalDepth"
@@ -76,6 +76,69 @@ export interface HintNudge {
   text: string
 }
 
+/**
+ * A better way to do something the user keeps doing the slow way: shown now
+ * and then (at most `max` times, `nudgeAgain` apart) and never again once the
+ * better way is used. `when` reads usage counters — kit components report
+ * their own (see HINT_SIGNALS), and `hints.use(name)` adds any of the app's.
+ */
+export interface HintTip {
+  id: string
+  title: string
+  text: string
+  keys?: string
+  max?: number
+  when: (count: (signal: string) => number) => boolean
+  /** What "show me" lights up on the current screen; without it the tip only informs. */
+  step?: () => TourStep | null
+}
+
+/** Usage the kit reports by itself. */
+export const HINT_SIGNALS = {
+  /** A context menu was opened (right click or long press). */
+  contextMenu: "lp.context-menu",
+  /** A "…" menu marked `rightClickToo` was opened: its items were one right click away. */
+  menuButton: "lp.menu-button",
+  /** A left click on something that also has a context menu. */
+  contextTarget: "lp.context-target",
+  /** The command palette was opened. */
+  palette: "lp.palette",
+  /** The current hint page changed: a navigation. */
+  navigate: "lp.navigate",
+  /** An item's actions were opened in the palette (Tab). */
+  paletteActions: "lp.palette-actions",
+} as const
+
+/** Right click instead of the "…" button. */
+export function contextMenuTip(text: Partial<Pick<HintTip, "title" | "text"> & { stepText: string }> = {}): HintTip {
+  return {
+    id: "lp.tip.context-menu",
+    title: text.title ?? "Right-click works here",
+    text: text.text ?? "Rows and cards open their actions on right-click, even where no … button shows it.",
+    when: (count) =>
+      count(HINT_SIGNALS.contextMenu) === 0
+      && (count(HINT_SIGNALS.menuButton) >= 5 || count(HINT_SIGNALS.contextTarget) >= 25),
+    step: () => {
+      const target = [...document.querySelectorAll("[data-lp-context-menu]")].find((el) => {
+        const box = el.getBoundingClientRect()
+        return box.width > 0 && box.bottom > 0 && box.top < window.innerHeight
+      })
+      return target ? { target, title: text.title ?? "Right-click works here", text: text.stepText ?? "Right-click this to see what it can do.", try: true } : null
+    },
+  }
+}
+
+/** The palette instead of walking the menu. */
+export function paletteTip(keys = "Ctrl+K", text: Partial<Pick<HintTip, "title" | "text">> = {}): HintTip {
+  return {
+    id: "lp.tip.palette",
+    title: text.title ?? "Jump anywhere",
+    text: text.text ?? "Search pages, people and settings from anywhere instead of the menu.",
+    keys,
+    when: (count) => count(HINT_SIGNALS.navigate) >= 15 && count(HINT_SIGNALS.palette) === 0,
+  }
+}
+
 export type HintLevel = "seen" | "explained" | "used"
 
 export interface HintRecord {
@@ -113,6 +176,7 @@ export interface HintSystemOptions {
   features: Record<string, HintFeature>
   pages?: Record<string, HintPage>
   news?: HintNews[]
+  tips?: HintTip[]
   storage?: HintStorage
   /** The current page id, read reactively (map your route to it). */
   page: () => string
@@ -124,6 +188,7 @@ export type HintOffer =
   | { kind: "tour" | "assigned"; page: string }
   | { kind: "news"; page: string; items: HintNews[] }
   | { kind: "nudge"; page: string; nudge: HintNudge }
+  | { kind: "tip"; page: string; tip: HintTip }
 
 const RANK: Record<HintLevel, number> = { seen: 0, explained: 1, used: 2 }
 const DAY = 24 * 3600 * 1000
@@ -217,6 +282,8 @@ export function createHintSystem(options: HintSystemOptions) {
   const features = options.features
   const pages = options.pages ?? {}
   const news = options.news ?? []
+  const tips = options.tips ?? []
+  const TIP_MAX = 3
   const storage = options.storage ?? localHintStorage()
   const sessionKey = options.sessionKey ?? "lp-hints:interrupted"
 
@@ -224,6 +291,7 @@ export function createHintSystem(options: HintSystemOptions) {
     records: new Map<string, HintRecord>(),
     loaded: false,
     page: "",
+    overlay: null as string | null,
     tour: { open: false, step: 0, steps: [] as TourStep[], ids: [] as string[], page: "" },
     offer: null as HintOffer | null,
     candidate: null as (HintNudge & { page: string }) | null,
@@ -238,6 +306,9 @@ export function createHintSystem(options: HintSystemOptions) {
   const pageKey = hintKey.page
   const newsKey = hintKey.news
   const nudgeKey = hintKey.nudge
+  const signalKey = (name: string) => `u:${name}`
+  const tipKey = (id: string) => `p:${id}`
+  const count = (name: string) => state.records.get(signalKey(name))?.count ?? 0
 
   function interrupted(): boolean {
     try {
@@ -390,14 +461,28 @@ export function createHintSystem(options: HintSystemOptions) {
       return
     }
     const n = state.candidate
-    if (!n || n.page !== page) return
-    const seen = state.records.get(nudgeKey(n.id))
-    if (seen?.dismissed || state.records.get(featureKey(n.feature))?.state === "used" || !hints.present(n.feature)) return
-    if (seen && Date.now() - Date.parse(seen.updatedAt) < timing.nudgeAgain) return
-    state.candidate = null
-    spend()
-    record(nudgeKey(n.id), { add: 1 })
-    state.offer = { kind: "nudge", page, nudge: n }
+    if (n && n.page === page) {
+      const seen = state.records.get(nudgeKey(n.id))
+      const f = features[n.feature]
+      const visible = !!f && (!!f.target || !!f.enter || hints.present(n.feature))
+      if (!seen?.dismissed && state.records.get(featureKey(n.feature))?.state !== "used" && visible
+        && !(seen && Date.now() - Date.parse(seen.updatedAt) < timing.nudgeAgain)) {
+        state.candidate = null
+        spend()
+        record(nudgeKey(n.id), { add: 1 })
+        state.offer = { kind: "nudge", page, nudge: n }
+        return
+      }
+    }
+    for (const tip of tips) {
+      const seen = state.records.get(tipKey(tip.id))
+      if (seen?.dismissed || (seen?.count ?? 0) >= (tip.max ?? TIP_MAX)) continue
+      if (seen && Date.now() - Date.parse(seen.updatedAt) < timing.nudgeAgain) continue
+      if (!tip.when(count)) continue
+      spend()
+      state.offer = { kind: "tip", page, tip }
+      return
+    }
   }
 
   let stops: (() => void)[] = []
@@ -405,8 +490,9 @@ export function createHintSystem(options: HintSystemOptions) {
   function start(): void {
     if (stops.length) return
     const stopPage: WatchStopHandle = watch(
-      options.page,
-      (page) => {
+      () => state.overlay ?? options.page(),
+      (page, previous) => {
+        if (previous !== undefined && page !== previous && !state.overlay) record(signalKey(HINT_SIGNALS.navigate), { add: 1 })
         state.page = page
         state.settledAt = Date.now()
         if (state.offer && state.offer.page !== page) state.offer = null
@@ -428,6 +514,7 @@ export function createHintSystem(options: HintSystemOptions) {
       stopPage,
       hints.on("used", (id) => {
         if (features[id]) record(featureKey(id), { state: "used", add: 1 })
+        if (id.startsWith("lp.") || !features[id]) record(signalKey(id), { add: 1 })
       }),
       () => clearInterval(poll),
       () => window.removeEventListener("pagehide", flushOnLeave),
@@ -460,6 +547,16 @@ export function createHintSystem(options: HintSystemOptions) {
     nudge(n: HintNudge): void {
       state.candidate = { ...n, page: state.page }
     },
+    /**
+     * A dialog acts as its own page while open (its dots and tour), then hands
+     * back. Pass null on close, and on unmount: a dialog left open by a route
+     * change would otherwise keep the page.
+     */
+    overlay(page: string | null): void {
+      state.overlay = page
+    },
+    /** How many times a signal was reported (for an app's own tips or reports). */
+    count,
     /** The user navigated on purpose (palette, notification): do not interrupt this arrival. */
     markIntent(): void {
       state.intent = true
@@ -475,6 +572,7 @@ export function createHintSystem(options: HintSystemOptions) {
       if (id) record(featureKey(id), { state: "explained" })
     },
     tourEnded(finished: boolean): void {
+      if (!state.tour.ids.length) return
       record(pageKey(state.tour.page), finished ? { state: "explained" } : { add: 1 })
       baseline(state.tour.page)
     },
@@ -486,6 +584,10 @@ export function createHintSystem(options: HintSystemOptions) {
         const ids = offer.items.map((n) => n.feature).filter((id): id is string => !!id)
         readNews(offer.page)
         if (choice === "show" && ids.length) startTour(offer.page, ids)
+      } else if (offer.kind === "tip") {
+        record(tipKey(offer.tip.id), { add: 1, dismissed: choice === "never" })
+        const step = choice === "show" ? offer.tip.step?.() : null
+        if (step) Object.assign(state.tour, { open: true, step: 0, page: offer.page, ids: [], steps: [step] })
       } else if (offer.kind === "nudge") {
         if (choice === "show") startTour(features[offer.nudge.feature]!.page, [offer.nudge.feature])
         else record(nudgeKey(offer.nudge.id), { dismissed: true })
@@ -503,10 +605,26 @@ export type HintSystem = ReturnType<typeof createHintSystem>
 
 const HINT_SYSTEM: InjectionKey<HintSystem> = Symbol.for("lp-hint-system")
 
+/*
+ * Overlays (the palette, menus) are portalled siblings of the host, not its
+ * descendants, so injection alone would never reach them: the mounted host is
+ * also kept here.
+ */
+const running = shallowRef<HintSystem | null>(null)
+
 export function provideHintSystem(system: HintSystem): void {
   provide(HINT_SYSTEM, system)
+  running.value = system
+  onBeforeUnmount(() => {
+    if (running.value === system) running.value = null
+  })
 }
 
 export function useHintSystem(): HintSystem | null {
-  return inject(HINT_SYSTEM, null)
+  return inject(HINT_SYSTEM, null) ?? running.value
+}
+
+/** The mounted host's system, read reactively from anywhere. */
+export function runningHintSystem(): HintSystem | null {
+  return running.value
 }

package/src/index.ts

@@ -212,7 +212,7 @@ export type { TourContext, TourStep } from "./components/LpTour.vue"
 export { holeOf, openContextMenu, panelsAround } from "./components/tour"
 export { default as LpHintLayer } from "./components/LpHintLayer.vue"
 export { default as LpHints } from "./components/LpHints.vue"
-export { createHintSystem, hintKey, hintSummary, localHintStorage, provideHintSystem, useHintSystem } from "./composables/useHintSystem"
+export { HINT_SIGNALS, contextMenuTip, createHintSystem, hintKey, hintSummary, localHintStorage, paletteTip, provideHintSystem, runningHintSystem, useHintSystem } from "./composables/useHintSystem"
 export type {
   HintDelta,
   HintFeature,
@@ -225,6 +225,7 @@ export type {
   HintStorage,
   HintSummary,
   HintSystem,
+  HintTip,
   HintSystemOptions,
   HintTiming,
 } from "./composables/useHintSystem"