@leavepulse/ui 0.56.0 → 0.58.0

package/dist/index.js

@@ -1,24 +1,24 @@
-import { _ } from "./chunks/LayoutCanvas-BkaGXTjx.js";
-import { _ as _2 } from "./chunks/LpAddressInput-NUHmplCd.js";
-import { _ as _3 } from "./chunks/LpMapPicker-Cc84LaM3.js";
+import { _ } from "./chunks/LayoutCanvas-BcGLJVBq.js";
+import { _ as _2 } from "./chunks/LpAddressInput-Dio6Sqed.js";
+import { _ as _3 } from "./chunks/LpMapPicker-BH5csaBt.js";
 import { OSM_TILES, createNominatimProvider, emptyAddress, formatAddress, project, tileUrl, unproject } from "./components/address.js";
-import { _ as _4 } from "./chunks/LpActionBar-C3hkVsFz.js";
-import { _ as _5 } from "./chunks/LpAlert-B6ilrM7T.js";
-import { _ as _6 } from "./chunks/LpAppShell-BEGjSqFl.js";
-import { _ as _7 } from "./chunks/LpAutocomplete-C8IgSMsi.js";
-import { _ as _8 } from "./chunks/LpAvatar-LTvy0OkE.js";
+import { _ as _4 } from "./chunks/LpActionBar-DCN-_pZP.js";
+import { _ as _5 } from "./chunks/LpAlert-CXMn1GYE.js";
+import { _ as _6 } from "./chunks/LpAppShell-Be6T96td.js";
+import { _ as _7 } from "./chunks/LpAutocomplete-hJ_6CHlh.js";
+import { _ as _8 } from "./chunks/LpAvatar-BxNs23Xu.js";
 import { _ as _9 } from "./chunks/LpBadge-Fe0D1bYx.js";
-import { _ as _10 } from "./chunks/LpBreadcrumbs-D4TsoFju.js";
-import { _ as _11 } from "./chunks/LpButton-BdfZFNqi.js";
-import { _ as _12 } from "./chunks/LpCalendar-DrA2McTU.js";
-import { _ as _13 } from "./chunks/LpCard-DbjO5yaF.js";
+import { _ as _10 } from "./chunks/LpBreadcrumbs-BLzOEgAF.js";
+import { _ as _11 } from "./chunks/LpButton-vhlwmpBy.js";
+import { _ as _12 } from "./chunks/LpCalendar-BLoE8Qm7.js";
+import { _ as _13 } from "./chunks/LpCard-DhR7u0d8.js";
 import { default as default2 } from "./components/LpChart.vue.js";
 import { backgroundOf, csvField, downloadFile, fileStem, inlineSvg, resolveCssColor, svgToPng, toCsv } from "./components/exportData.js";
 import { CHART_PALETTE, axisTicks, chartSummary, formatTick, markerIndex, niceScale, resolveSlices } from "./components/chart.js";
-import { _ as _14 } from "./chunks/LpCheckbox-DvVYeOD-.js";
-import { _ as _15 } from "./chunks/LpCodeBlock-ca7ANFyW.js";
+import { _ as _14 } from "./chunks/LpCheckbox-B_C8sOoT.js";
+import { _ as _15 } from "./chunks/LpCodeBlock-CXsqJwDy.js";
 import { tokenizeLines } from "./components/codeHighlight.js";
-import { _ as _16 } from "./chunks/LpColorPicker-D1sQqtXS.js";
+import { _ as _16 } from "./chunks/LpColorPicker-DQ88niXq.js";
 import { DEFAULT_SWATCHES, clampHsv, formatColor, hsvToHsl, hsvToRgb, isLight, normalizeHue, opaqueCss, parseColor, parseHex, rgbToHex, rgbToHsv } from "./components/color.js";
 import { default as default3 } from "./components/LpCommandPalette.vue.js";
 import { applyQueryFilters, highlightParts, parseCommandQuery, parsePaletteQuery, rankCommandItems } from "./components/commandSearch.js";
@@ -30,46 +30,46 @@ import { default as default6 } from "./components/LpPaletteStats.vue.js";
 import { default as default7 } from "./components/LpPaletteSwatches.vue.js";
 import { default as default8 } from "./components/LpKeys.vue.js";
 import { comboKeys, comboSteps } from "./components/keys.js";
-import { _ as _18 } from "./chunks/LpConfirmDialog-CrbUZgJE.js";
-import { _ as _19 } from "./chunks/LpConfirmHost-BgMIV8r9.js";
+import { _ as _18 } from "./chunks/LpConfirmDialog-DxlSdjmk.js";
+import { _ as _19 } from "./chunks/LpConfirmHost-BcrmTNu_.js";
 import { confirm, useConfirm } from "./components/confirm.js";
-import { _ as _20 } from "./chunks/LpContextMenu-EF_90u3g.js";
-import { _ as _21 } from "./chunks/LpDatePicker-BrdFtSTy.js";
-import { _ as _22 } from "./chunks/LpDateRangePicker-Drd7EbIz.js";
-import { _ as _23 } from "./chunks/LpRangeCalendar-DZuaRV0W.js";
+import { _ as _20 } from "./chunks/LpContextMenu-B1NGfpp1.js";
+import { _ as _21 } from "./chunks/LpDatePicker-B-VMHMgy.js";
+import { _ as _22 } from "./chunks/LpDateRangePicker-B68KPKPl.js";
+import { _ as _23 } from "./chunks/LpRangeCalendar-D5sDID9W.js";
 import { clampRange, defaultRangePresets, formatRange, normalizeRange, sameRange } from "./components/dateRange.js";
-import { _ as _24 } from "./chunks/LpDisclosure-Cc23-JOT.js";
+import { _ as _24 } from "./chunks/LpDisclosure-Ct-VBHxt.js";
 import { _ as _25 } from "./chunks/LpDivider-CUX46KR0.js";
-import { _ as _26 } from "./chunks/LpDrawer-CBFVD624.js";
-import { _ as _27 } from "./chunks/LpDropdownMenu-DrpJJBp0.js";
+import { _ as _26 } from "./chunks/LpDrawer-DSknigxH.js";
+import { _ as _27 } from "./chunks/LpDropdownMenu-C7oHVlKY.js";
 import { default as default9 } from "./components/LpDropzone.vue.js";
-import { _ as _28 } from "./chunks/LpEmptyState-BJbZXC8D.js";
-import { _ as _29 } from "./chunks/LpFileTree-3E4w4Rjr.js";
+import { _ as _28 } from "./chunks/LpEmptyState-CBwwkkdA.js";
+import { _ as _29 } from "./chunks/LpFileTree-CMA0_rsB.js";
 import { ancestorIds, checkStateOf, checkedCount, computeStats, fileIcon, formatModified, formatSize, sortNodes, subtreeIds, subtreeSize } from "./components/fileTree.js";
-import { _ as _30 } from "./chunks/LpFieldNotice-wtieLUTj.js";
-import { _ as _31 } from "./chunks/LpFormField-CtVYj6tO.js";
-import { _ as _32 } from "./chunks/LpIcon-DYtaid0K.js";
-import { i, b, a, c } from "./chunks/icons-CkA0njzm.js";
+import { _ as _30 } from "./chunks/LpFieldNotice-9hH4ITZa.js";
+import { _ as _31 } from "./chunks/LpFormField-BpQ6WJPe.js";
+import { _ as _32 } from "./chunks/LpIcon-B5guGKrW.js";
+import { i, b, a, c } from "./chunks/icons-QqBscG5I.js";
 import { default as default10 } from "./components/LpImageEditor.vue.js";
 import { _ as _33 } from "./chunks/LpInfraNode-Ds_8SZgN.js";
-import { _ as _34 } from "./chunks/LpInput-D-YGQbEv.js";
-import { _ as _35 } from "./chunks/LpLightbox-EVXzAq62.js";
+import { _ as _34 } from "./chunks/LpInput-WvyP02ID.js";
+import { _ as _35 } from "./chunks/LpLightbox-Dq-e36uT.js";
 import { fileNameOf } from "./components/lightbox.js";
 import { _ as _36 } from "./chunks/LpLink-Krkjhe_y.js";
-import { _ as _37 } from "./chunks/LpLogViewer-BfgtXVKm.js";
+import { _ as _37 } from "./chunks/LpLogViewer-DwiYE32z.js";
 import { countLevels, matchPositions, matchesTerm, ringWindow, stepMatch } from "./components/logSearch.js";
-import { _ as _38 } from "./chunks/LpMediaGallery-BnlkN_1f.js";
-import { _ as _39 } from "./chunks/LpModal-JNa3B_Lr.js";
-import { _ as _40 } from "./chunks/LpModalNav-DXBilXr0.js";
-import { _ as _41 } from "./chunks/LpNotificationBell-DEL-RoHS.js";
-import { _ as _42 } from "./chunks/LpNumberField-B77O-z28.js";
-import { _ as _43 } from "./chunks/LpTimeField-Cqe7fXnh.js";
+import { _ as _38 } from "./chunks/LpMediaGallery-B1kDypJ-.js";
+import { _ as _39 } from "./chunks/LpModal-BxYssnXg.js";
+import { _ as _40 } from "./chunks/LpModalNav-Bn2ws64b.js";
+import { _ as _41 } from "./chunks/LpNotificationBell-DJfs4JjQ.js";
+import { _ as _42 } from "./chunks/LpNumberField-CJPjmoDz.js";
+import { _ as _43 } from "./chunks/LpTimeField-DvGXgdES.js";
 import { _ as _44 } from "./chunks/LpNumberFlow-z4WPZcZu.js";
 import { _ as _45 } from "./chunks/LpOtpInput-PbeNJ5In.js";
-import { _ as _46 } from "./chunks/LpPagination-BcDlo3r_.js";
-import { _ as _47 } from "./chunks/LpPasswordInput-eKzQhbQP.js";
-import { _ as _48 } from "./chunks/LpPie-B7ti5qCH.js";
-import { _ as _49 } from "./chunks/LpPhoneInput-BCbrrhgE.js";
+import { _ as _46 } from "./chunks/LpPagination-DehAaJLY.js";
+import { _ as _47 } from "./chunks/LpPasswordInput-Bg5uTZbx.js";
+import { _ as _48 } from "./chunks/LpPie-DeTkbbOK.js";
+import { _ as _49 } from "./chunks/LpPhoneInput-DStwcbnQ.js";
 import { filterCountries, flagEmoji, loadCountries, matchCountryByValue } from "./components/countries.js";
 import { _ as _50 } from "./chunks/LpPopover-DCKeqiVn.js";
 import { _ as _51 } from "./chunks/LpProgress-CBU1iI69.js";
@@ -77,36 +77,41 @@ import { _ as _52 } from "./chunks/LpRadio-CWA5Eb3M.js";
 import { _ as _53 } from "./chunks/LpRadioGroup-CCn-Q2_c.js";
 import { _ as _54 } from "./chunks/LpRollingText-DB7upf-5.js";
 import { _ as _55 } from "./chunks/LpScrollArea-Hz3-JWUG.js";
-import { _ as _56 } from "./chunks/LpSegmented-C09EEam2.js";
-import { _ as _57 } from "./chunks/LpSection-tKEH0jYf.js";
-import { _ as _58 } from "./chunks/LpSelect-DNIL6MB9.js";
+import { _ as _56 } from "./chunks/LpSegmented-D3Eam8sa.js";
+import { _ as _57 } from "./chunks/LpSection-B19VPYmr.js";
+import { _ as _58 } from "./chunks/LpSelect-DynjWK1A.js";
 import { _ as _59 } from "./chunks/LpServiceNode-D8uJ8sGk.js";
 import { _ as _60 } from "./chunks/LpShift-DXNsauQZ.js";
 import { default as default11 } from "./components/LpShortcutsDialog.vue.js";
-import { _ as _61 } from "./chunks/LpSidebar-C2oolgwy.js";
+import { _ as _61 } from "./chunks/LpSidebar-CshW0fqC.js";
 import { _ as _62 } from "./chunks/LpSkeleton-BB6XIV-w.js";
 import { _ as _63 } from "./chunks/LpSlider-Cuzmrd7p.js";
 import { _ as _64 } from "./chunks/LpRangeSlider-C1yF9-nP.js";
 import { _ as _65 } from "./chunks/LpVideoBackdrop-qWRYBOTQ.js";
 import { formatClipTime, isNativeLoop, planLoop, seamProgress, seamReached } from "./components/videoBackdrop.js";
 import { _ as _66 } from "./chunks/LpSparkline-CB80N8SJ.js";
-import { _ as _67 } from "./chunks/LpStat-B-7udBRP.js";
-import { _ as _68 } from "./chunks/LpStepper-C7XiVKZj.js";
+import { _ as _67 } from "./chunks/LpStat-BS2TEXYK.js";
+import { _ as _68 } from "./chunks/LpStepper-BSglWF45.js";
 import { _ as _69 } from "./chunks/LpSwitch-DG2AhXIL.js";
 import { default as default12 } from "./components/LpTable.vue.js";
 import { compareValues } from "./components/tableSort.js";
-import { _ as _70 } from "./chunks/LpTableOfContents-BUcAfGPQ.js";
-import { _ as _71 } from "./chunks/LpTabs-BMSBB78h.js";
-import { _ as _72 } from "./chunks/LpTagsInput-D1SuqbhB.js";
+import { _ as _70 } from "./chunks/LpTableOfContents-DYuqkByy.js";
+import { _ as _71 } from "./chunks/LpTabs-BBGRHY38.js";
+import { _ as _72 } from "./chunks/LpTagsInput-CHbQoAAA.js";
 import { addTags, splitTags } from "./components/tags.js";
-import { _ as _73 } from "./chunks/LpTextarea-uuScWo6-.js";
-import { _ as _74 } from "./chunks/LpThemeSwitcher-Fz85BCRS.js";
+import { _ as _73 } from "./chunks/LpTextarea-Bz2IWhTH.js";
+import { _ as _74 } from "./chunks/LpThemeSwitcher-B_qhSl7q.js";
 import { _ as _75 } from "./chunks/LpTilt-B7KHX1zH.js";
-import { _ as _76 } from "./chunks/LpToaster-DTtWuKvq.js";
-import { _ as _77 } from "./chunks/LpTooltip-CXVKcOXT.js";
-import { _ as _78 } from "./chunks/LpTooltipProvider-CftjV7Xc.js";
-import { _ as _79 } from "./chunks/LpTopologyCanvas-6ozNrQKh.js";
-import { _ as _80 } from "./chunks/LpUptimeBar-ugcv25xj.js";
+import { _ as _76 } from "./chunks/LpToaster-Bo9Q4QBP.js";
+import { _ as _77 } from "./chunks/LpTooltip-suFCM34F.js";
+import { _ as _78 } from "./chunks/LpTour-D7m9ZxNk.js";
+import { holeOf, openContextMenu, panelsAround } from "./components/tour.js";
+import { _ as _79 } from "./chunks/LpHintLayer-B5-6FyEf.js";
+import { _ as _80 } from "./chunks/LpHints-BqoZXHZk.js";
+import { createHintSystem, hintKey, hintSummary, localHintStorage, provideHintSystem, useHintSystem } from "./composables/useHintSystem.js";
+import { _ as _81 } from "./chunks/LpTooltipProvider-CftjV7Xc.js";
+import { _ as _82 } from "./chunks/LpTopologyCanvas-6ozNrQKh.js";
+import { _ as _83 } from "./chunks/LpUptimeBar-B4ltCfno.js";
 import { deserializeLayout, serializeLayout } from "./layout/tree.js";
 import { addLeaf, addTab, countBlocks, countLeaves, makeLayout, moveLeaf, removeBlock, removeLeaf, reorderTab, resizeAt, setActiveTab } from "./layout/tree.js";
 import { blockTitle, defineBlocks } from "./layout/registry.js";
@@ -127,6 +132,9 @@ import { LP_FIELD, fieldMessageId, provideField, useField, useFieldControl } fro
 import { FIELD_NOTICE_MS, useFieldNotice } from "./composables/useFieldNotice.js";
 import { easeOut, easeTravel, easingToken, prefersReducedMotion } from "./composables/easing.js";
 import { useReveal } from "./composables/useReveal.js";
+import { hints, vHint } from "./composables/useHints.js";
+import { scrollParent, scrollToElement } from "./composables/scroll.js";
+import { useMediaQuery } from "./composables/useMediaQuery.js";
 import { useAsyncTask } from "./composables/useAsyncTask.js";
 import { useRovingFocus } from "./composables/useRovingFocus.js";
 import { useFormDraft } from "./composables/useFormDraft.js";
@@ -137,7 +145,7 @@ import { useShift } from "./composables/useShift.js";
 import { useTilt } from "./composables/useTilt.js";
 import { useZoomPan } from "./composables/useZoomPan.js";
 import { useToast } from "./composables/useToast.js";
-import { _ as _81 } from "./chunks/LpThemeProvider-CQ2jC9TA.js";
+import { _ as _84 } from "./chunks/LpThemeProvider-CQ2jC9TA.js";
 import { isInternalHref, resolveLink } from "./components/link.js";
 function defineTheme(base, overrides = {}) {
   const src = typeof base === "string" ? presets[base] : base;
@@ -209,6 +217,8 @@ export {
   _30 as LpFieldNotice,
   _29 as LpFileTree,
   _31 as LpFormField,
+  _79 as LpHintLayer,
+  _80 as LpHints,
   _32 as LpIcon,
   default10 as LpImageEditor,
   _33 as LpInfraNode,
@@ -260,15 +270,16 @@ export {
   _71 as LpTabs,
   _72 as LpTagsInput,
   _73 as LpTextarea,
-  _81 as LpThemeProvider,
+  _84 as LpThemeProvider,
   _74 as LpThemeSwitcher,
   _75 as LpTilt,
   _43 as LpTimeField,
   _76 as LpToaster,
   _77 as LpTooltip,
-  _78 as LpTooltipProvider,
-  _79 as LpTopologyCanvas,
-  _80 as LpUptimeBar,
+  _81 as LpTooltipProvider,
+  _82 as LpTopologyCanvas,
+  _78 as LpTour,
+  _83 as LpUptimeBar,
   _65 as LpVideoBackdrop,
   N as NO_BACKDROP_ATTR,
   OSM_TILES,
@@ -306,6 +317,7 @@ export {
   countBlocks,
   countLeaves,
   countLevels,
+  createHintSystem,
   createNominatimProvider,
   csvField,
   g as dark,
@@ -336,6 +348,10 @@ export {
   formatSize,
   formatTick,
   highlightParts,
+  hintKey,
+  hintSummary,
+  hints,
+  holeOf,
   hotkeyConflicts,
   hotkeySteps,
   hsvToHsl,
@@ -351,6 +367,7 @@ export {
   l as light,
   j as lime,
   loadCountries,
+  localHintStorage,
   lpConfig,
   makeLayout,
   markerIndex,
@@ -370,6 +387,8 @@ export {
   normalizeRange,
   k as normalizeTheme,
   opaqueCss,
+  openContextMenu,
+  panelsAround,
   parseColor,
   parseCommandQuery,
   parseConfig,
@@ -385,6 +404,7 @@ export {
   project,
   provideField,
   provideGlass,
+  provideHintSystem,
   provideLpConfig,
   pushRecent,
   rankCommandItems,
@@ -405,6 +425,8 @@ export {
   ringWindow,
   o as rose,
   sameRange,
+  scrollParent,
+  scrollToElement,
   seamProgress,
   seamReached,
   sequenceProgress,
@@ -441,6 +463,7 @@ export {
   useFormDraft,
   useGamepadNav,
   useGlass,
+  useHintSystem,
   useHotkeys,
   useInputFilter,
   useInputMask,
@@ -448,6 +471,7 @@ export {
   useLayout,
   useLinkComponent,
   useLpConfig,
+  useMediaQuery,
   useMergedAttrs,
   useMergedClass,
   useModalLayer,
@@ -460,5 +484,6 @@ export {
   useTilt,
   useToast,
   useZoomPan,
+  vHint,
   y as violet
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leavepulse/ui",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "type": "module",
   "description": "LeavePulse token-driven Vue component kit.",
   "repository": {

package/src/component-names.ts

@@ -33,6 +33,8 @@ export const COMPONENT_NAMES = [
   "LpFieldNotice",
   "LpFileTree",
   "LpFormField",
+  "LpHintLayer",
+  "LpHints",
   "LpIcon",
   "LpImageEditor",
   "LpInfraNode",
@@ -92,6 +94,7 @@ export const COMPONENT_NAMES = [
   "LpTooltip",
   "LpTooltipProvider",
   "LpTopologyCanvas",
+  "LpTour",
   "LpUptimeBar",
   "LpVideoBackdrop"
 ] as const

package/src/components/LpDateRangePicker.vue

@@ -10,11 +10,12 @@ export default { inheritAttrs: false }
  * Two months sit side by side where there is room, one on a phone.
  */
 import { PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger } from "reka-ui"
-import { computed, onBeforeUnmount, onMounted, ref, useAttrs } from "vue"
+import { computed, ref, useAttrs } from "vue"
 import { useFieldControl } from "../composables/useField"
 import { useLocale } from "../composables/useLocale"
 import { useLabels } from "../composables/useLpConfig"
 import { mergeClass } from "../composables/useMergedClass"
+import { useMediaQuery } from "../composables/useMediaQuery"
 import {
   clampRange,
   type DateRange,
@@ -113,17 +114,7 @@ function presetFits(preset: DateRangePreset): boolean {
   return !!clampRange(preset.range(), props.min, props.max)
 }
 
-const wide = ref(false)
-let query: MediaQueryList | undefined
-const onQuery = () => {
-  wide.value = !!query?.matches
-}
-onMounted(() => {
-  query = window.matchMedia("(min-width: 640px)")
-  onQuery()
-  query.addEventListener("change", onQuery)
-})
-onBeforeUnmount(() => query?.removeEventListener("change", onQuery))
+const wide = useMediaQuery("(min-width: 640px)")
 
 const shellSize = {
   sm: "h-(--size-control-sm) text-xs",

package/src/components/LpDrawer.vue

@@ -34,6 +34,7 @@ import {
 } from "vaul-vue"
 import { computed, onBeforeUnmount, ref, useSlots, watch } from "vue"
 import { CLOSE_ICON } from "./dropdown"
+import { prefersReducedMotion } from "../composables/easing"
 import { useGlass } from "../composables/useGlass"
 import { useLabels } from "../composables/useLpConfig"
 import LpIcon from "./LpIcon.vue"
@@ -328,10 +329,6 @@ function edgeEnabled(): boolean {
 let track: { id: number; x: number; y: number; t: number; lastX: number; lastT: number; speed: number } | null = null
 const owner = Symbol("edge-pull")
 
-function reducedMotion(): boolean {
-  return typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
-}
-
 // A horizontally scrollable ancestor that can still move the way the finger
 // pulls (a carousel, a wide table) keeps the gesture: the pull only claims
 // what nothing under the finger wants.
@@ -414,7 +411,7 @@ function settle() {
             peek.value = 0
           }, 60),
         )
-      }, reducedMotion() ? 0 : 180),
+      }, prefersReducedMotion() ? 0 : 180),
     )
   } else {
     peek.value = 0
@@ -462,7 +459,7 @@ const previewStyle = computed(() => {
   const axis = dir.value === "right" ? off : -off
   return {
     transform: `translateX(${axis}%)`,
-    transition: peeking.value || reducedMotion() ? "none" : "transform 0.18s cubic-bezier(0.32, 0.72, 0, 1)",
+    transition: peeking.value || prefersReducedMotion() ? "none" : "transform 0.18s cubic-bezier(0.32, 0.72, 0, 1)",
     pointerEvents: "none" as const,
   }
 })
@@ -477,7 +474,7 @@ const previewStyle = computed(() => {
       v-show="peeking || peek > 0"
       class="lp-scrim pointer-events-none fixed inset-0"
       :class="{ 'lp-scrim--light': frosted, 'lp-scrim--nested': layer.nested }"
-      :style="{ zIndex: layer.scrim, opacity: peek, transition: peeking || reducedMotion() ? 'none' : 'opacity 0.18s ease-out' }"
+      :style="{ zIndex: layer.scrim, opacity: peek, transition: peeking || prefersReducedMotion() ? 'none' : 'opacity 0.18s ease-out' }"
     />
     <div
       v-show="peeking || peek > 0"

package/src/components/LpHintLayer.vue

@@ -0,0 +1,148 @@
+<script lang="ts">
+export interface HintNote {
+  title: string
+  text?: string
+}
+</script>
+
+<script setup lang="ts">
+/*
+ * Quiet "new" markers over `v-hint` elements, with a short note when the user
+ * reaches for one. Nothing pops up by itself: a dot sits on the control, and
+ * the note opens only when the pointer or focus lands on it. Reading the note
+ * (or simply using the control) is the app's cue to stop marking it.
+ *
+ * The layer only draws. Which ids are new, and when a read counts, is decided
+ * by the app from the registry's seen/used events.
+ */
+import { PopoverAnchor, PopoverContent, PopoverPortal, PopoverRoot } from "reka-ui"
+import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watch } from "vue"
+import { hints } from "../composables/useHints"
+import { useLabels } from "../composables/useLpConfig"
+import { PANEL_SURFACE, POPOVER_ANIM } from "./dropdown"
+import LpButton from "./LpButton.vue"
+
+const props = withDefaults(
+  defineProps<{
+    /** Ids to mark, most important first. */
+    fresh: string[]
+    notes: Record<string, HintNote>
+    /** At most this many dots at once, so a page full of news stays calm. */
+    limit?: number
+    labels?: Partial<typeof DEFAULT_LABELS>
+  }>(),
+  { limit: 3 },
+)
+
+const emit = defineEmits<{ (e: "read", id: string): void }>()
+
+const DEFAULT_LABELS = { gotIt: "Got it", badge: "New" }
+const labels = useLabels("hintLayer", DEFAULT_LABELS, () => props.labels)
+
+const OPEN_DELAY_MS = 350
+
+const shown = computed(() => props.fresh.filter((id) => hints.present(id) && props.notes[id]).slice(0, props.limit))
+const spots = ref<{ id: string; x: number; y: number }[]>([])
+const openId = ref<string | null>(null)
+const anchor = shallowRef<Element | null>(null)
+let frame = 0
+let timer: ReturnType<typeof setTimeout> | undefined
+
+function place() {
+  spots.value = shown.value.flatMap((id) => {
+    const el = hints.element(id)
+    if (!el) return []
+    const r = el.getBoundingClientRect()
+    return r.width || r.height ? [{ id, x: r.right, y: r.top }] : []
+  })
+  frame = shown.value.length ? requestAnimationFrame(place) : 0
+}
+
+watch(
+  shown,
+  (ids) => {
+    if (ids.length && !frame) frame = requestAnimationFrame(place)
+    if (openId.value && !ids.includes(openId.value)) openId.value = null
+  },
+  { immediate: true },
+)
+
+function reveal(id: string) {
+  clearTimeout(timer)
+  timer = setTimeout(() => {
+    if (!shown.value.includes(id)) return
+    anchor.value = hints.element(id)
+    openId.value = anchor.value ? id : null
+  }, OPEN_DELAY_MS)
+}
+
+function read() {
+  const id = openId.value
+  openId.value = null
+  if (id) emit("read", id)
+}
+
+let off: (() => void)[] = []
+onMounted(() => {
+  off = [
+    hints.on("hover", (id) => {
+      if (shown.value.includes(id)) reveal(id)
+    }),
+    hints.on("used", (id) => {
+      if (!shown.value.includes(id)) return
+      clearTimeout(timer)
+      if (openId.value === id) openId.value = null
+      emit("read", id)
+    }),
+  ]
+})
+
+onBeforeUnmount(() => {
+  cancelAnimationFrame(frame)
+  clearTimeout(timer)
+  for (const stop of off) stop()
+})
+
+const note = computed(() => (openId.value ? props.notes[openId.value] : undefined))
+</script>
+
+<template>
+  <Teleport to="body">
+    <button
+      v-for="spot in spots"
+      :key="spot.id"
+      type="button"
+      class="fixed z-(--z-popover) -translate-x-1/2 -translate-y-1/2 rounded-full p-1"
+      :style="{ left: `${spot.x}px`, top: `${spot.y}px` }"
+      :aria-label="`${labels.badge}: ${notes[spot.id]?.title ?? ''}`"
+      @pointerenter="reveal(spot.id)"
+      @focus="reveal(spot.id)"
+      @click="reveal(spot.id)"
+    >
+      <span class="relative flex size-2">
+        <span class="absolute inline-flex size-full animate-ping rounded-full bg-brand opacity-60 motion-reduce:animate-none" />
+        <span class="relative inline-flex size-2 rounded-full bg-brand ring-2 ring-surface" />
+      </span>
+    </button>
+    <PopoverRoot :open="!!openId" @update:open="(value) => !value && (openId = null)">
+      <PopoverAnchor v-if="anchor" :reference="anchor" />
+      <PopoverPortal>
+        <PopoverContent
+          side="bottom"
+          :side-offset="8"
+          :collision-padding="8"
+          :class="[PANEL_SURFACE, POPOVER_ANIM, 'z-(--z-popover) w-72 rounded-card p-3 text-sm text-ink outline-none']"
+        >
+          <p class="flex items-center gap-2 font-medium">
+            <span class="rounded-full bg-brand/15 px-1.5 text-[11px] text-brand">{{ labels.badge }}</span>
+            {{ note?.title }}
+          </p>
+          <p v-if="note?.text" class="mt-1.5 text-muted">{{ note.text }}</p>
+          <div class="mt-3 flex justify-end">
+            <LpButton size="sm" @click="read">{{ labels.gotIt }}</LpButton>
+          </div>
+        </PopoverContent>
+      </PopoverPortal>
+    </PopoverRoot>
+  </Teleport>
+</template>

package/src/components/LpHints.vue

@@ -0,0 +1,116 @@
+<script setup lang="ts">
+/*
+ * Drop-in onboarding: put it once next to the app's root, hand it a hint
+ * system, and the tour offer, the "new" dots, "what changed" and nudges all
+ * work. Nothing to wire per page beyond `v-hint` on the elements.
+ *
+ * It must never cost the page itself. Any error thrown inside (a tour step's
+ * `enter`, a storage that rejects, a target that misbehaves) switches the layer
+ * off for the session and is logged once; the page under it keeps working.
+ */
+import { computed, onBeforeUnmount, onErrorCaptured, onMounted, ref, unref, watch } from "vue"
+import { provideHintSystem, type HintSystem } from "../composables/useHintSystem"
+import { useLabels } from "../composables/useLpConfig"
+import LpActionBar, { type ActionBarAction } from "./LpActionBar.vue"
+import LpHintLayer from "./LpHintLayer.vue"
+import LpTour from "./LpTour.vue"
+
+const props = defineProps<{
+  system: HintSystem
+  labels?: Partial<typeof DEFAULT_LABELS>
+}>()
+
+const DEFAULT_LABELS = {
+  tourTitle: "New to {page}?",
+  tourText: "A one-minute look at what you can do here.",
+  assignedTitle: "You were asked to look at {page}",
+  assignedText: "A short tour of this page, about a minute.",
+  newsTitle: "What changed: {page}",
+  show: "Show me",
+  notNow: "Not now",
+  never: "Don't offer again",
+  gotIt: "Got it",
+  noThanks: "No thanks",
+}
+const labels = useLabels("hints", DEFAULT_LABELS, () => props.labels)
+
+provideHintSystem(props.system)
+
+const broken = ref(false)
+onErrorCaptured((error) => {
+  if (!broken.value) console.warn("[LpHints] disabled after an error:", error)
+  broken.value = true
+  props.system.stop()
+  return false
+})
+
+onMounted(() => {
+  try {
+    props.system.start()
+    if (!props.system.state.loaded) void props.system.load()
+  } catch (error) {
+    broken.value = true
+    console.warn("[LpHints] disabled after an error:", error)
+  }
+})
+onBeforeUnmount(() => props.system.stop())
+
+const state = props.system.state
+const fresh = computed(() => unref(props.system.fresh))
+const notes = computed(() => unref(props.system.notes))
+watch(() => [state.tour.open, state.tour.step] as const, ([open, step]) => open && props.system.tourShown(step))
+
+const offer = computed(() => state.offer)
+const page = computed(() => (offer.value ? props.system.pageTitle(offer.value.page) : ""))
+const fill = (text: string) => text.replace("{page}", page.value)
+
+const title = computed(() => {
+  const o = offer.value
+  if (!o) return ""
+  if (o.kind === "nudge") return notes.value[o.nudge.feature]?.title ?? ""
+  if (o.kind === "news") return fill(labels.value.newsTitle)
+  return fill(o.kind === "assigned" ? labels.value.assignedTitle : labels.value.tourTitle)
+})
+
+const description = computed(() => {
+  const o = offer.value
+  if (!o) return ""
+  if (o.kind === "nudge") return o.nudge.text
+  if (o.kind === "news") return o.items.map((n) => n.text).join(" ")
+  return o.kind === "assigned" ? labels.value.assignedText : labels.value.tourText
+})
+
+const actions = computed<ActionBarAction[]>(() => {
+  const o = offer.value
+  if (!o) return []
+  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 === "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") }] : []),
+    { label: labels.value.notNow, variant: "ghost", onClick: answer("later") },
+    show,
+  ]
+})
+</script>
+
+<template>
+  <template v-if="!broken">
+    <LpTour
+      v-model:open="state.tour.open"
+      v-model:step="state.tour.step"
+      :steps="state.tour.steps"
+      @finish="system.tourEnded(true)"
+      @dismiss="system.tourEnded(false)"
+    />
+    <LpHintLayer :fresh="fresh" :notes="notes" @read="system.readFresh" />
+    <LpActionBar
+      :open="!!offer"
+      :title="title"
+      :description="description"
+      :icon="offer?.kind === 'news' ? 'lucide:gift' : 'lucide:compass'"
+      :actions="actions"
+    />
+  </template>
+</template>