@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/app/composables/useOnboardingService.ts

@@ -0,0 +1,106 @@
+import type { InjectionKey } from 'vue'
+import type { OnboardingAnswersDraft } from '../components/element/onboarding-answers'
+import { inject, reactive } from 'vue'
+
+/**
+ * The onboarding wizard's data layer as a swappable service, so the wizard +
+ * step components stay dumb (render state, call methods — no RPC). The brand-kit
+ * showcase drives the flow against `createInMemoryOnboardingService()`: it keeps
+ * its own reactive state and resolves everything locally, so the whole wizard
+ * runs e2e with zero network / no DB. The live app keeps its own RPC wiring; if
+ * it ever adopts this seam it provides an RPC-backed impl of the same interface.
+ *
+ * Pure data shapes + an in-memory impl — no runtime services — so it's safe in
+ * design-system and importable by brand-kit.
+ */
+export interface OnboardingSite {
+  id: string
+  url: string
+}
+
+export interface OnboardingInvite {
+  email: string
+  role: string
+}
+
+export interface OnboardingState {
+  workspaceId: string | null
+  workspaceName: string | null
+  /** The "About you" Onboarding Answers. */
+  answers: OnboardingAnswersDraft
+  sites: OnboardingSite[]
+  connectedProviders: string[]
+  invites: OnboardingInvite[]
+}
+
+export interface OnboardingService {
+  readonly state: OnboardingState
+  createWorkspace: (name: string) => Promise<{ id: string }>
+  validateSite: (url: string) => Promise<{ valid: boolean, normalizedUrl?: string, error?: string }>
+  addSites: (urls: string[]) => Promise<{ ids: string[] }>
+  saveAnswers: (answers: OnboardingAnswersDraft) => Promise<void>
+  connectProvider: (provider: string, payload?: Record<string, unknown>) => Promise<void>
+  isConnected: (provider: string) => boolean
+  invite: (email: string, role: string) => Promise<void>
+  finish: () => Promise<void>
+}
+
+export const ONBOARDING_SERVICE: InjectionKey<OnboardingService> = Symbol('onboarding-service')
+
+/** Injected service, or `null` when not inside an onboarding wizard. */
+export function useOnboardingService(): OnboardingService | null {
+  return inject(ONBOARDING_SERVICE, null)
+}
+
+function emptyState(): OnboardingState {
+  return { workspaceId: null, workspaceName: null, answers: { intents: [], other: '' }, sites: [], connectedProviders: [], invites: [] }
+}
+
+/**
+ * In-memory implementation: mutates its own reactive state, no network. The
+ * counter (not Math.random) keeps ids stable across SSR/hydration.
+ */
+export function createInMemoryOnboardingService(): OnboardingService {
+  const state = reactive<OnboardingState>(emptyState())
+  let seq = 0
+  const nextId = (prefix: string) => `${prefix}_mock_${++seq}`
+
+  return {
+    state,
+    async createWorkspace(name) {
+      state.workspaceName = name
+      state.workspaceId = nextId('team')
+      return { id: state.workspaceId }
+    },
+    async validateSite(url) {
+      const trimmed = url.trim()
+      if (!trimmed)
+        return { valid: false, error: 'Enter a URL' }
+      return { valid: true, normalizedUrl: /^https?:\/\//.test(trimmed) ? trimmed : `https://${trimmed}` }
+    },
+    async addSites(urls) {
+      const ids = urls.map((url) => {
+        const id = nextId('site')
+        state.sites.push({ id, url })
+        return id
+      })
+      return { ids }
+    },
+    async saveAnswers(answers) {
+      state.answers = { ...answers, intents: [...answers.intents] }
+    },
+    async connectProvider(provider) {
+      if (!state.connectedProviders.includes(provider))
+        state.connectedProviders.push(provider)
+    },
+    isConnected(provider) {
+      return state.connectedProviders.includes(provider)
+    },
+    async invite(email, role) {
+      state.invites.push({ email, role })
+    },
+    async finish() {
+      // no-op: the showcase flow ends in place rather than navigating away.
+    },
+  }
+}

package/app/composables/useOpenedOnce.ts

@@ -0,0 +1,19 @@
+import type { Ref, WatchSource } from 'vue'
+import { readonly, ref, watch } from 'vue'
+
+/**
+ * True from the first time `open` reads true, and true after that.
+ *
+ * An open-on-demand overlay mounts its Lazy component behind this latch. Its
+ * chunk then stays out of the page's boot graph and the server render. After
+ * the first open the overlay stays mounted, so its leave transition plays and
+ * its own state survives a reopen.
+ */
+export function useOpenedOnce(open: WatchSource<boolean>): Readonly<Ref<boolean>> {
+  const opened = ref(false)
+  watch(open, (value) => {
+    if (value)
+      opened.value = true
+  }, { immediate: true, flush: 'sync' })
+  return readonly(opened)
+}

package/app/composables/useScrollSpy.ts

@@ -0,0 +1,178 @@
+import type { MaybeRefOrGetter, Ref } from 'vue'
+import { defaultWindow, useEventListener, useThrottleFn, useTimeoutFn } from '@vueuse/core'
+import { nextTick, onMounted, ref, toValue } from 'vue'
+
+// Define types for the sections
+type SectionId = string
+
+interface Section {
+  id: SectionId
+  label?: string
+
+  [key: string]: unknown
+}
+
+type SectionInput = SectionId | Section
+
+interface ScrollSpyOptions {
+  offsetPx?: number
+  throttleMs?: number
+}
+
+// Return type of the composable
+interface ScrollSpyReturn {
+  activeSection: Ref<SectionId>
+  scrollToSection: (sectionId: SectionId) => void
+}
+
+/**
+ * A composable for tracking which sections are currently visible in the viewport
+ * and providing navigation functionality.
+ *
+ * `sections` accepts a ref/getter so a dynamic section list (e.g. derived from
+ * async content) stays live — it is read via `toValue` on every recalculation
+ * rather than captured once at call time.
+ *
+ * @param sections  The sections to track (reactive)
+ * @param options   Configuration options
+ * @returns Active section and navigation methods
+ */
+export function useScrollSpy(sections: MaybeRefOrGetter<SectionInput[]>, options: ScrollSpyOptions = {}): ScrollSpyReturn {
+  const {
+    offsetPx = -10, // Offset from the top (e.g., for fixed headers)
+    throttleMs = 100, // Throttle milliseconds
+  } = options
+
+  const activeSection = ref<SectionId>('')
+  const isUserScrolling = ref(true) // Assume initial scroll is from user
+
+  /**
+   * Get section ID from either string or object
+   */
+  function getSectionId(section: SectionInput): SectionId {
+    return typeof section === 'string' ? section : section.id
+  }
+
+  // Re-arm the "programmatic scroll done" flag after a smooth scroll settles.
+  // useTimeoutFn auto-cancels on scope dispose so it never fires into a torn-down instance.
+  const { start: startResetUserScrolling, stop: stopResetUserScrolling } = useTimeoutFn(() => {
+    isUserScrolling.value = true
+  }, 1000, { immediate: false })
+
+  /**
+   * Scrolls the page to the selected section
+   */
+  function scrollToSection(sectionId: SectionId): void {
+    // Set active section immediately on click
+    activeSection.value = sectionId
+
+    // Flag that next scrolls will be programmatic (not user-initiated)
+    isUserScrolling.value = false
+
+    const element = document.getElementById(sectionId)
+    if (element) {
+      // Get element position
+      const rect = element.getBoundingClientRect()
+      const absoluteTop = window.scrollY + rect.top - offsetPx
+
+      // Scroll smoothly, unless the user prefers reduced motion (then jump).
+      const prefersReduced = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true
+      window.scrollTo({
+        top: absoluteTop,
+        behavior: prefersReduced ? 'auto' : 'smooth',
+      })
+
+      // Reset the flag after the smooth scroll is likely complete
+      stopResetUserScrolling()
+      startResetUserScrolling()
+    }
+  }
+
+  /**
+   * Calculates which section should be active based on scroll position
+   */
+  function calculateActiveSection(): void {
+    // Only calculate if this is user scrolling, not programmatic
+    if (!isUserScrolling.value) {
+      return
+    }
+
+    const sectionList = toValue(sections)
+
+    // Get all sections and their positions
+    const sectionElements: { id: string, top: number }[] = []
+
+    sectionList.forEach((section) => {
+      const id = getSectionId(section)
+      const element = document.getElementById(id)
+      if (element) {
+        const rect = element.getBoundingClientRect()
+        sectionElements.push({
+          id,
+          top: rect.top,
+        })
+      }
+    })
+
+    // Sort sections by position (top to bottom)
+    sectionElements.sort((a, b) => a.top - b.top)
+
+    // Find the first section that is active
+    let activeSectionId: string | null
+
+    // First check sections that are in the viewport
+    const inViewport = sectionElements.filter(
+      section => section.top <= offsetPx && section.top > -100,
+    )
+
+    if (inViewport[0]) {
+      // If sections are in viewport, select the first one
+      activeSectionId = inViewport[0].id
+    }
+    else {
+      // Otherwise, select the last section that's above the viewport
+      const aboveViewport = sectionElements.filter(section => section.top <= 0)
+      activeSectionId = aboveViewport.at(-1)?.id ?? sectionElements[0]?.id ?? null
+    }
+
+    if (activeSectionId) {
+      activeSection.value = activeSectionId
+    }
+    else if (sectionList[0]) {
+      // Fallback to first section if nothing else is active
+      activeSection.value = getSectionId(sectionList[0])
+    }
+  }
+
+  // Throttled version of calculateActiveSection
+  const throttledCalculateActiveSection = useThrottleFn(calculateActiveSection, throttleMs)
+
+  // Handle user interaction with the page
+  function handleUserInteraction() {
+    isUserScrolling.value = true
+  }
+
+  // Bind listeners synchronously at setup so useEventListener registers its
+  // cleanup against the active effect scope (binding inside the async nextTick
+  // below would lose the scope and leak the listeners).
+  useEventListener(defaultWindow, 'scroll', throttledCalculateActiveSection, { passive: true })
+  useEventListener(defaultWindow, 'mousedown', handleUserInteraction, { passive: true })
+  useEventListener(defaultWindow, 'keydown', handleUserInteraction, { passive: true })
+  useEventListener(defaultWindow, 'touchstart', handleUserInteraction, { passive: true })
+
+  // Recalculate shortly after mount to catch dynamic content that shifts offsets.
+  const { start: startDeferredRecalc } = useTimeoutFn(calculateActiveSection, 300, { immediate: false })
+
+  onMounted(() => {
+    // Wait for DOM to be fully rendered before the first measurement
+    void nextTick(() => {
+      calculateActiveSection()
+      startDeferredRecalc()
+    })
+  })
+
+  return {
+    activeSection,
+    scrollToSection,
+  }
+}

package/app/composables/useSquircleFallback.ts

@@ -0,0 +1,21 @@
+import { onMounted, ref } from 'vue'
+
+/**
+ * Squircle fallback gate. Native CSS `corner-shape: squircle` (Chrome 139+)
+ * renders the squircle at SSR with a native border and zero hydration morph
+ * (see the `@supports` rule in global.css), so it needs no JS. Only where
+ * `corner-shape` is unsupported (Safari/Firefox) do consumers fall back to a
+ * generated `clip-path` + SVG-border overlay.
+ *
+ * `enabled` stays `false` on the server and through hydration (SSR can't
+ * feature-detect), then flips to `true` after mount on non-supporting
+ * browsers — so the fallback is a post-hydration enhancement, never a
+ * hydration mismatch.
+ */
+export function useSquircleFallback() {
+  const enabled = ref(false)
+  onMounted(() => {
+    enabled.value = !(typeof CSS !== 'undefined' && CSS.supports?.('corner-shape', 'squircle'))
+  })
+  return { enabled }
+}

package/app/composables/useWizardRoute.ts

@@ -0,0 +1,123 @@
+import type { MaybeRefOrGetter, Ref, WritableComputedRef } from 'vue'
+import type { LocationQuery } from 'vue-router'
+import { navigateTo, useRoute, useRouter } from 'nuxt/app'
+import { computed, onMounted, onScopeDispose, toValue, watch } from 'vue'
+import { useOpenedOnce } from './useOpenedOnce'
+
+export interface WizardRoute {
+  /** True while `?setup=<flowId>` is in the query and the flow is allowed. False strips `setup` and `step`; true restores the last step. */
+  open: WritableComputedRef<boolean>
+  /** `?step=<id>` while this flow is open. Set while closed, it is the step the next open starts at. */
+  step: WritableComputedRef<string | undefined>
+  /** True from the first open. Mount the Lazy flow behind it. */
+  opened: Readonly<Ref<boolean>>
+  /** The current path and query, plus `setup=<flowId>&step=<stepId>`. An OAuth flow returns here. */
+  returnTo: (stepId: string) => string
+}
+
+const FLOW_KEYS = ['setup', 'step'] as const
+const HISTORY_MARK = 'setupFlow'
+
+function withoutFlow(query: LocationQuery): LocationQuery {
+  const rest = { ...query }
+  for (const key of FLOW_KEYS)
+    delete rest[key]
+  return rest
+}
+
+/**
+ * Backs a `UiWizardModal` with the query: `?setup=<flowId>&step=<id>`.
+ *
+ * A link, a notification, or an OAuth return can then open a flow at a step.
+ * An open from the page pushes one marked history entry, so Back closes the
+ * flow, on a phone too. A close goes back over a marked entry. Step changes
+ * replace it, so stepping through a flow adds no history entries.
+ *
+ * `allowed` gates write flows. If it is false, the flow never opens and an
+ * incoming `?setup=<flowId>` is stripped. If it is undefined, the answer is
+ * still loading: the flow stays closed and the deep link stays in the query.
+ */
+export function useWizardRoute(flowId: string, options: { allowed?: MaybeRefOrGetter<boolean | undefined> } = {}): WizardRoute {
+  const route = useRoute()
+  const router = useRouter()
+
+  const allowed = computed(() => 'allowed' in options ? toValue(options.allowed) : true)
+  const requested = computed(() => route.query.setup === flowId)
+
+  // An open from the page marks its history entry in history.state. A close
+  // then goes back over it, also after a reload or Forward. A deep link opens
+  // without the mark, and closes with a replace.
+  const onPushedEntry = () => (router.options.history.state as Record<string, unknown> | null)?.[HISTORY_MARK] === flowId
+  function replaceQuery(query: LocationQuery): void {
+    // A step change keeps the mark on the entry it replaces.
+    const state = onPushedEntry() ? { [HISTORY_MARK]: flowId } : undefined
+    void navigateTo({ query, hash: route.hash, state }, { replace: true })
+  }
+
+  // True from a close until a navigation settles. A second close in that time,
+  // such as Esc after Done, is dropped, so it cannot go back twice.
+  let closing = false
+  onScopeDispose(router.afterEach(() => {
+    closing = false
+  }))
+  // The step a reopen resumes, beside the form state the modal kept.
+  let lastStep: string | undefined
+  const open = computed<boolean>({
+    get: () => requested.value && allowed.value === true,
+    set: (value) => {
+      if (value === open.value || (value && allowed.value !== true))
+        return
+      if (!value) {
+        if (closing)
+          return
+        closing = true
+        if (onPushedEntry())
+          router.back()
+        else
+          replaceQuery(withoutFlow(route.query))
+        return
+      }
+      void navigateTo({
+        query: { ...withoutFlow(route.query), setup: flowId, ...(lastStep ? { step: lastStep } : {}) },
+        hash: route.hash,
+        state: { [HISTORY_MARK]: flowId },
+      })
+    },
+  })
+
+  const step = computed<string | undefined>({
+    get: () => open.value && typeof route.query.step === 'string' ? route.query.step : undefined,
+    set: (id) => {
+      if (!open.value) {
+        lastStep = id
+        return
+      }
+      if (id === step.value)
+        return
+      const { step: _step, ...rest } = route.query
+      replaceQuery(id === undefined ? rest : { ...rest, step: id })
+    },
+  })
+  // Every way out, the Close button, Back, or a link, keeps the step the user
+  // was on.
+  watch(step, (id) => {
+    if (id !== undefined)
+      lastStep = id
+  }, { immediate: true, flush: 'sync' })
+  // A denied deep link leaves the query, so a reload or a shared URL cannot
+  // open it. On the client only: a server-side replace would redirect.
+  const denied = computed(() => requested.value && allowed.value === false)
+  const strip = () => {
+    if (denied.value)
+      replaceQuery(withoutFlow(route.query))
+  }
+  onMounted(strip)
+  watch(denied, strip)
+
+  return {
+    open,
+    step,
+    opened: useOpenedOnce(open),
+    returnTo: stepId => router.resolve({ path: route.path, query: { ...withoutFlow(route.query), setup: flowId, step: stepId } }).fullPath,
+  }
+}

package/app/plugins/favicon.ts

@@ -0,0 +1,15 @@
+import { defineNuxtPlugin, useAppConfig, useHead } from 'nuxt/app'
+import { useColorMode } from '#imports'
+import { appFaviconLinks } from '../utils/app-favicon'
+
+// Emits the favicon and touch icon links that app.config's `favicon` names,
+// and swaps them with the colour mode. The layer ships no brand images, so an
+// app that sets no `favicon` gets no links from here.
+export default defineNuxtPlugin(() => {
+  const { favicon } = useAppConfig()
+  const colorMode = useColorMode()
+
+  useHead(() => ({
+    link: appFaviconLinks(favicon, colorMode.value === 'dark'),
+  }))
+})

package/app/plugins/lazy-motion.ts

@@ -0,0 +1,22 @@
+import { domAnimation, LazyMotion } from 'motion-v'
+import { defineNuxtPlugin } from 'nuxt/app'
+
+/**
+ * Animation features for every `m.*` component the layer renders, so an app
+ * that extends the layer needs no `<LazyMotion>` wrapper of its own.
+ *
+ * `vue:setup` runs inside the setup of NuxtRoot, the component above both
+ * `app.vue` and `error.vue`. Running LazyMotion's own setup there provides its
+ * features context from that component, as the wrapper would. motion-v does not
+ * export the context key, so the component's setup is the public way to
+ * provide it. A nested `<LazyMotion :features="domMax">` still overrides it for
+ * its subtree.
+ */
+export default defineNuxtPlugin({
+  name: 'design-system:lazy-motion',
+  setup(nuxtApp) {
+    nuxtApp.hook('vue:setup', () => {
+      LazyMotion.setup!({ features: domAnimation, strict: false }, { slots: {}, attrs: {}, emit: () => {}, expose: () => {} } as never)
+    })
+  },
+})

package/app/plugins/selection-highlight.client.ts

@@ -0,0 +1,176 @@
+import { useEventListener } from '@vueuse/core'
+import { defineNuxtPlugin } from 'nuxt/app'
+
+/**
+ * Highlighter text selection. Replaces the native highlight bar with a hand-drawn
+ * violet marker swipe. `::selection` can't do gradients / slanted ends / rough
+ * edges, so instead of styling the selection we paint an OVERLAY of `.mark` divs
+ * over the selection's per-line client-rects (`global.css` blanks the native
+ * highlight, gated on the `selection-hl-ready` class this plugin adds).
+ *
+ * Unlike a wrap-the-text-nodes approach, the overlay never mutates the document:
+ * the real selection, copy, keyboard extension and live Vue-rendered surfaces are
+ * all untouched, and the marker paints live during the drag. Marks are grouped
+ * into per-theme isolated sub-layers so a selection spanning a light→dark boundary
+ * blends correctly on both sides, and overlapping line-marks (which close the
+ * vertical gaps) never double-darken.
+ */
+export default defineNuxtPlugin(() => {
+  // Reduced motion: leave the native selection fully intact (no class, no overlay).
+  if (window.matchMedia('(prefers-reduced-motion: reduce)').matches)
+    return
+
+  // Regions the overlay must skip: form controls + editable text (no stable text
+  // rects / shouldn't be marked) and code (keeps its own rangi styling). These
+  // keep the native highlight via the re-assert rules in global.css.
+  const EXCLUDE = 'input, textarea, [contenteditable], pre, code, .rangi'
+  const OX = 5 // horizontal overshoot (px) each side, so the swipe reads hand-drawn
+  const HFRAC = 1.06 // mark height vs line-box: >1 so adjacent lines meet
+  const TOPFRAC = -0.03 // nudge up so marks overlap and close the white gaps
+
+  const html = document.documentElement
+  html.classList.add('selection-hl-ready')
+
+  // The rough-edge filter can't live in CSS — inject it once, hidden.
+  const defs = document.createElement('div')
+  defs.style.cssText = 'position:absolute;width:0;height:0;overflow:hidden'
+  defs.setAttribute('aria-hidden', 'true')
+  defs.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg">'
+    + '<filter id="selection-hl-rough" x="-15%" y="-60%" width="130%" height="220%" color-interpolation-filters="sRGB">'
+    + '<feTurbulence type="fractalNoise" baseFrequency="0.018 0.13" numOctaves="2" seed="7" result="n"/>'
+    + '<feDisplacementMap in="SourceGraphic" in2="n" scale="3" xChannelSelector="R" yChannelSelector="G"/>'
+    + '</filter></svg>'
+  document.body.appendChild(defs)
+
+  const layer = document.createElement('div')
+  layer.id = 'selection-hl-layer'
+  document.body.appendChild(layer)
+
+  let frame = 0
+  let settle = 0
+
+  // Deterministic per-line tilt so the marks don't reshuffle every repaint.
+  const tilt = (i: number): number => ((Math.sin(i * 12.9898) * 43758.5453) % 1) * 0.7 - 0.35
+
+  function isExcluded(node: Node | null): boolean {
+    const el = node instanceof Element ? node : node?.parentElement ?? null
+    return !!el?.closest(EXCLUDE)
+  }
+
+  interface LineRect { left: number, right: number, top: number, bottom: number, ctx: Element | null }
+
+  /**
+   * One merged rect per line of selected text (never block/margin rects), each
+   *  tagged with the element it sits over so it can be themed correctly.
+   */
+  function lineRects(range: Range): LineRect[] {
+    const scope = range.commonAncestorContainer
+    const root = scope.nodeType === Node.TEXT_NODE ? scope.parentNode! : scope
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+      acceptNode(node) {
+        return (!node.nodeValue?.trim() || isExcluded(node) || !range.intersectsNode(node))
+          ? NodeFilter.FILTER_REJECT
+          : NodeFilter.FILTER_ACCEPT
+      },
+    })
+    const lines = new Map<number, LineRect>()
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+      const text = n as Text
+      const start = text === range.startContainer ? range.startOffset : 0
+      const end = text === range.endContainer ? range.endOffset : text.length
+      if (end <= start)
+        continue
+      const sub = document.createRange()
+      sub.setStart(text, start)
+      sub.setEnd(text, end)
+      for (const r of sub.getClientRects()) {
+        if (r.width < 1 || r.height < 2)
+          continue
+        const key = Math.round((r.top + r.bottom) / 2 / 3)
+        const cur = lines.get(key)
+        if (!cur) {
+          lines.set(key, { left: r.left, right: r.right, top: r.top, bottom: r.bottom, ctx: text.parentElement })
+        }
+        else {
+          cur.left = Math.min(cur.left, r.left)
+          cur.right = Math.max(cur.right, r.right)
+          cur.top = Math.min(cur.top, r.top)
+          cur.bottom = Math.max(cur.bottom, r.bottom)
+        }
+      }
+    }
+    return [...lines.values()]
+  }
+
+  interface Group { blend: string, op: string, hl: string, hl2: string, pool: string, streak: string, lines: LineRect[] }
+
+  function paint(): void {
+    layer.replaceChildren()
+    const sel = window.getSelection()
+    if (!sel || sel.isCollapsed || sel.rangeCount === 0)
+      return
+    const range = sel.getRangeAt(0)
+    if (isExcluded(range.commonAncestorContainer))
+      return
+
+    // Theme each line by the element it sits over, then group same-theme lines
+    // into one isolated, blended sub-layer.
+    const groups = new Map<string, Group>()
+    for (const ln of lineRects(range)) {
+      const cs = getComputedStyle(ln.ctx ?? html)
+      const blend = cs.getPropertyValue('--selection-blend').trim() || 'multiply'
+      const op = cs.getPropertyValue('--selection-op').trim() || '0.56'
+      const hl = cs.getPropertyValue('--selection-hl').trim()
+      const hl2 = cs.getPropertyValue('--selection-hl2').trim() || hl
+      const pool = cs.getPropertyValue('--selection-pool').trim()
+      const streak = cs.getPropertyValue('--selection-streak').trim()
+      const sig = `${blend}|${op}|${hl}|${hl2}|${pool}|${streak}`
+      let g = groups.get(sig)
+      if (!g) {
+        g = { blend, op, hl, hl2, pool, streak, lines: [] }
+        groups.set(sig, g)
+      }
+      g.lines.push(ln)
+    }
+
+    for (const g of groups.values()) {
+      const cont = document.createElement('div')
+      cont.className = 'group'
+      cont.style.mixBlendMode = g.blend
+      cont.style.opacity = g.op
+      let i = 0
+      for (const r of g.lines) {
+        const rh = r.bottom - r.top
+        const rw = r.right - r.left
+        const d = document.createElement('div')
+        d.className = 'mark'
+        d.style.setProperty('--mk-hl', g.hl)
+        d.style.setProperty('--mk-hl2', g.hl2)
+        d.style.setProperty('--mk-pool', g.pool)
+        d.style.setProperty('--mk-streak', g.streak)
+        d.style.left = `${r.left - OX}px`
+        d.style.top = `${r.top + rh * TOPFRAC}px`
+        d.style.width = `${rw + OX * 2}px`
+        d.style.height = `${rh * HFRAC}px`
+        d.style.transform = `rotate(${tilt(i)}deg)`
+        cont.appendChild(d)
+        i++
+      }
+      layer.appendChild(cont)
+    }
+  }
+
+  function schedule(): void {
+    cancelAnimationFrame(frame)
+    frame = requestAnimationFrame(paint)
+    // Smooth (no rough filter) while the selection is actively changing; snap the
+    // hand-drawn edge back in once it's been still for a beat.
+    layer.classList.remove('rough')
+    clearTimeout(settle)
+    settle = window.setTimeout(() => layer.classList.add('rough'), 150)
+  }
+
+  useEventListener(document, 'selectionchange', schedule)
+  useEventListener(window, 'scroll', schedule, { capture: true, passive: true })
+  useEventListener(window, 'resize', schedule)
+})

package/app/shared/cli.ts

@@ -0,0 +1,10 @@
+/**
+ * How a printed command invokes the CLI on a machine that may not have it.
+ *
+ * The package is `@nuxtseo/cli` (bin `nuxtseo`); nothing is published as
+ * `nuxtseo`, so `npx nuxtseo` is a 404. Every surface that prints a command
+ * with no install step above it spells the invocation this way so the line
+ * runs as written. A quick start that already installed the CLI may print the
+ * bare `nuxtseo` on the lines after the install.
+ */
+export const CLI_INVOCATION = 'npx @nuxtseo/cli'