@leavepulse/ui 0.77.3 → 0.78.1

package/src/composables/useLinkedView.ts

@@ -0,0 +1,222 @@
+import { computed, inject, provide, ref, shallowRef, toValue, watch, type InjectionKey, type MaybeRefOrGetter, type Ref, type ShallowRef } from "vue"
+import type { ChartAnnotation } from "../components/chart"
+import type { ChartRange } from "../components/chartWindow"
+import { inTimeRange, nearestByTime, type LogId, type LogTimeRange } from "../components/logTools"
+import { stepKey, type PipelineStep } from "../components/pipeline"
+
+/*
+ * What a monitoring screen shares: which thing is selected, which stretch of
+ * time is on show, which request is being followed. The table, the graph, the
+ * log and the chart each keep their own API; a `link*` binder turns this state
+ * into the props and listeners of one of them, for `v-bind`:
+ *
+ *   const view = provideLinkedView()
+ *   const table = linkTable(view, { kind: "server" })
+ *   const log = linkLog(view, { kind: "server" })
+ *
+ *   <LpTable v-bind="table" :rows row-key="id" selectable />
+ *   <LpLogViewer v-bind="log" :lines selectable />
+ *
+ * Set a kind when a screen holds several sorts of thing: a binder only answers
+ * to its own, so picking a deployment leaves the server graph where it was.
+ */
+export type LinkedId = string | number
+
+export interface LinkedEntity {
+  id: LinkedId
+  kind?: string
+}
+
+/** A point of interest on the shared timeline, such as a log line. */
+export interface LinkedMoment {
+  time: number | string
+  label: string
+}
+
+export interface LinkedView {
+  entity: ShallowRef<LinkedEntity | null>
+  timeRange: ShallowRef<LogTimeRange | null>
+  moment: ShallowRef<LinkedMoment | null>
+  traceId: Ref<string | null>
+  select(entity: LinkedEntity | null): void
+  clear(): void
+}
+
+export function createLinkedView(): LinkedView {
+  const entity = shallowRef<LinkedEntity | null>(null)
+  const timeRange = shallowRef<LogTimeRange | null>(null)
+  const moment = shallowRef<LinkedMoment | null>(null)
+  const traceId = ref<string | null>(null)
+  return {
+    entity,
+    timeRange,
+    moment,
+    traceId,
+    // The same thing again is no change, so a binder echoing a selection back
+    // (a focused node reports itself selected) cannot start a loop.
+    select(next) {
+      const now = entity.value
+      if (next?.id !== now?.id || next?.kind !== now?.kind) entity.value = next
+    },
+    clear() {
+      entity.value = null
+      timeRange.value = null
+      moment.value = null
+      traceId.value = null
+    },
+  }
+}
+
+const LP_LINKED_VIEW: InjectionKey<LinkedView> = Symbol.for("lp-linked-view")
+
+/** Shares a view with everything below the calling component. */
+export function provideLinkedView(view: LinkedView = createLinkedView()): LinkedView {
+  provide(LP_LINKED_VIEW, view)
+  return view
+}
+
+/** The view provided above; a private one with none, so a panel works alone. */
+export function useLinkedView(): LinkedView {
+  return inject(LP_LINKED_VIEW, null) ?? createLinkedView()
+}
+
+interface LinkOptions {
+  /** The sort of entity this component shows. Unset answers to any. */
+  kind?: string
+}
+
+const answersTo = (entity: LinkedEntity | null, kind: string | undefined): entity is LinkedEntity =>
+  !!entity && (kind === undefined || entity.kind === kind)
+
+/** v-bind for LpTable: single selection, whatever the table's `selected` held before. */
+export function linkTable(view: LinkedView, options: LinkOptions = {}) {
+  return computed(() => {
+    const entity = view.entity.value
+    const current = answersTo(entity, options.kind) ? entity.id : null
+    return {
+      selected: current === null ? [] : [current],
+      "onUpdate:selected": (keys: LinkedId[]) => {
+        const picked = keys.find((key) => key !== current) ?? keys[0]
+        view.select(picked === undefined ? null : { id: picked, kind: options.kind })
+      },
+    }
+  })
+}
+
+/** What linkTopology drives: LpTopologyCanvas's exposed `focusNode`. */
+export interface LinkedCanvas {
+  focusNode(id: string, options?: { keepFocus?: boolean }): Promise<boolean>
+}
+
+/** v-bind for LpTopologyCanvas; `canvas` is its template ref, focused on a selection from elsewhere. */
+export function linkTopology(view: LinkedView, canvas: Ref<LinkedCanvas | null>, options: LinkOptions = {}) {
+  watch(
+    view.entity,
+    (entity) => {
+      if (answersTo(entity, options.kind)) void canvas.value?.focusNode(String(entity.id), { keepFocus: true })
+    },
+    { flush: "post" },
+  )
+  return computed(() => ({
+    onNodeSelect: (id: string) => view.select({ id, kind: options.kind }),
+  }))
+}
+
+export interface LinkLogOptions extends LinkOptions {
+  /** The log sources of an entity. Defaults to its id. */
+  sourcesOf?: (entity: LinkedEntity) => string[]
+}
+
+/**
+ * v-bind for LpLogViewer. The filters the selection and the trace set stay
+ * local, so the viewer's own chips and search box go on working; typing over a
+ * followed trace stops following it. Picking a line marks it on the timeline.
+ */
+export function linkLog(view: LinkedView, options: LinkLogOptions = {}) {
+  const sourcesOf = options.sourcesOf ?? ((entity: LinkedEntity) => [String(entity.id)])
+  const sources = shallowRef<string[]>([])
+  const search = ref("")
+  watch(view.entity, (entity) => (sources.value = answersTo(entity, options.kind) ? sourcesOf(entity) : []))
+  watch(view.traceId, (id, old) => {
+    if (id !== null) search.value = id
+    else if (search.value === old) search.value = ""
+  })
+  return computed(() => ({
+    sources: sources.value,
+    search: search.value,
+    // A viewer with no toolbar reads its term from here instead.
+    highlight: search.value,
+    // A search only marks its hits; a followed trace is meant to leave just its lines.
+    filterMatches: view.traceId.value !== null,
+    timeRange: view.timeRange.value ?? undefined,
+    "onUpdate:sources": (next: string[]) => (sources.value = next),
+    "onUpdate:search": (next: string) => {
+      search.value = next
+      if (next !== view.traceId.value) view.traceId.value = null
+    },
+    onSelect: ({ line }: { line: { time?: number | string; message: string } }) => {
+      view.moment.value = line.time === undefined ? null : { time: line.time, label: line.message }
+    },
+    onIdClick: ({ value }: { kind: LogId["kind"]; value: string }) => (view.traceId.value = value),
+  }))
+}
+
+export interface LinkChartOptions {
+  /** The time of each point, oldest first, in step with the chart's `labels`. */
+  times: MaybeRefOrGetter<readonly (number | string)[]>
+  /** The chart's own annotations, kept beside the linked one. */
+  annotations?: MaybeRefOrGetter<readonly ChartAnnotation[] | undefined>
+}
+
+/** v-bind for LpChart: the shared time range is its window, the marked moment an annotation. */
+export function linkChart(view: LinkedView, options: LinkChartOptions) {
+  const rows = computed(() => toValue(options.times).map((time) => ({ time })))
+  return computed(() => {
+    const times = toValue(options.times)
+    const last = times.length - 1
+    const shared = view.timeRange.value
+    const moment = view.moment.value
+    const onChart = !!moment && last >= 0 && inTimeRange(moment.time, { from: times[0], to: times[last] })
+    const range: ChartRange | null = shared && last >= 0
+      ? {
+          start: shared.from === undefined ? 0 : Math.max(0, nearestByTime(rows.value, shared.from)),
+          end: shared.to === undefined ? last : Math.max(0, nearestByTime(rows.value, shared.to)),
+        }
+      : null
+    return {
+      range,
+      annotations: [
+        ...(toValue(options.annotations) ?? []),
+        ...(onChart ? [{ at: nearestByTime(rows.value, moment.time), label: moment.label }] : []),
+      ],
+      "onUpdate:range": (next: ChartRange | null) => {
+        view.timeRange.value = next && { from: times[next.start], to: times[next.end] }
+      },
+    }
+  })
+}
+
+export interface LinkPipelineOptions extends LinkOptions {
+  /** The steps on show; a getter, as they usually follow the selection. */
+  steps: MaybeRefOrGetter<readonly PipelineStep[]>
+}
+
+/** v-bind for LpPipeline: selecting opens what failed, and the rows stay the reader's to toggle. */
+export function linkPipeline(view: LinkedView, options: LinkPipelineOptions) {
+  const expanded = shallowRef<string[]>([])
+  const failedKeys = (): string[] =>
+    toValue(options.steps).flatMap((step, index) => (step.status === "failed" ? [stepKey(step, index)] : []))
+  watch(
+    [view.entity, () => failedKeys().join("\0")],
+    ([entity]) => {
+      if (!answersTo(entity, options.kind)) return
+      expanded.value = [...new Set([...expanded.value, ...failedKeys()])]
+    },
+    { flush: "post" },
+  )
+  return computed(() => ({
+    expanded: expanded.value,
+    "onUpdate:expanded": (next: string[]) => (expanded.value = next),
+  }))
+}
+

package/src/composables/useOptimisticToggle.ts

@@ -17,7 +17,12 @@ type ToggleEmit = {
  * Shared by LpSwitch and LpCheckbox so a setting saved from either behaves
  * the same.
  */
-export function useOptimisticToggle(action: () => ((value: boolean) => unknown) | undefined, emit: ToggleEmit) {
+export function useOptimisticToggle(
+  action: () => ((value: boolean) => unknown) | undefined,
+  emit: ToggleEmit,
+  /** Puts back what a boolean cannot say: a checkbox's mixed state. */
+  rolledBack?: () => void,
+) {
   const toast = useToast()
   const instance = getCurrentInstance()
   const pending = ref(false)
@@ -33,6 +38,7 @@ export function useOptimisticToggle(action: () => ((value: boolean) => unknown)
       emit("done", value)
     } catch (error) {
       emit("update:modelValue", !value)
+      rolledBack?.()
       if (instance?.vnode.props?.onError) emit("error", error)
       else toast.error(error instanceof Error ? error : String(error))
     } finally {

package/src/composables/useOverlayHistory.ts

@@ -77,6 +77,26 @@ export interface OverlayHistoryOptions {
 }
 
 /** Wire an overlay's `open` to a history entry. */
+/** The wiring of an overlay driven by a v-model: closing asks its guard first. */
+export function useModelOverlayHistory(options: {
+  mode: OverlayHistoryOptions["mode"]
+  open: () => boolean
+  setOpen: (open: boolean) => void
+  allowClose: () => Promise<boolean>
+}): void {
+  useOverlayHistory({
+    mode: options.mode,
+    open: options.open,
+    close: async () => {
+      if (!(await options.allowClose())) return false
+      options.setOpen(false)
+      return true
+    },
+    reopen: () => options.setOpen(true),
+    navigated: () => options.setOpen(false),
+  })
+}
+
 export function useOverlayHistory(options: OverlayHistoryOptions): void {
   const inherited = inject(MODE, false)
   const mode = computed<OverlayHistoryMode>(() => options.mode() ?? toValue(inherited))

package/src/composables/usePaintSelect.ts

@@ -1,6 +1,7 @@
 import { onBeforeUnmount, onMounted, readonly, ref, toValue, type MaybeRefOrGetter, type Ref } from "vue"
 import { useHotkeys, type HotkeyHelp } from "./useHotkeys"
 import { scrollParent } from "./scroll"
+import { nodeWindow } from "./useView"
 
 /*
  * Paint selection: press on one item's tick and sweep across the others, and
@@ -76,8 +77,11 @@ export function usePaintSelect<K = string>(options: UsePaintSelectOptions<K>) {
     return out
   }
 
+  // Inside an LpFrame the pointer's events stay in the frame's window.
+  const hostWindow = (): Window => (options.root.value ? nodeWindow(options.root.value) : window)
+
   function keyAt(x: number, y: number): K | undefined {
-    const item = document.elementFromPoint(x, y)?.closest<HTMLElement>("[data-paint-key]")
+    const item = options.root.value?.ownerDocument.elementFromPoint(x, y)?.closest<HTMLElement>("[data-paint-key]")
     if (!item || !options.root.value?.contains(item)) return undefined
     return resolve(item.dataset.paintKey ?? "")
   }
@@ -100,11 +104,11 @@ export function usePaintSelect<K = string>(options: UsePaintSelectOptions<K>) {
   function tick() {
     frame = 0
     if (!stroke) return
-    const box = stroke.scroller?.getBoundingClientRect() ?? { top: 0, bottom: window.innerHeight }
+    const box = stroke.scroller?.getBoundingClientRect() ?? { top: 0, bottom: hostWindow().innerHeight }
     const delta = stroke.y > box.bottom - EDGE_PX ? SCROLL_STEP : stroke.y < box.top + EDGE_PX ? -SCROLL_STEP : 0
     if (delta) {
       if (stroke.scroller) stroke.scroller.scrollTop += delta
-      else window.scrollBy(0, delta)
+      else hostWindow().scrollBy(0, delta)
       extend()
     }
     frame = requestAnimationFrame(tick)
@@ -119,7 +123,7 @@ export function usePaintSelect<K = string>(options: UsePaintSelectOptions<K>) {
     painting.value = true
     // A sweep over text would otherwise select it, and a hold that started
     // before the stroke may already have.
-    window.getSelection()?.removeAllRanges()
+    hostWindow().getSelection()?.removeAllRanges()
     if (options.root.value) options.root.value.style.userSelect = "none"
     extend()
     if (!frame) frame = requestAnimationFrame(tick)
@@ -213,22 +217,24 @@ export function usePaintSelect<K = string>(options: UsePaintSelectOptions<K>) {
     { scope: options.root },
   )
 
+  let listening: Window | null = null
   onMounted(() => {
-    window.addEventListener("pointermove", onMove)
-    window.addEventListener("pointerup", onUp)
-    window.addEventListener("pointercancel", onUp)
-    window.addEventListener("click", onClickCapture, true)
-    window.addEventListener("contextmenu", onContextMenu, true)
+    listening = hostWindow()
+    listening.addEventListener("pointermove", onMove)
+    listening.addEventListener("pointerup", onUp)
+    listening.addEventListener("pointercancel", onUp)
+    listening.addEventListener("click", onClickCapture, true)
+    listening.addEventListener("contextmenu", onContextMenu, true)
     options.root.value?.addEventListener("touchmove", onTouchMove, { passive: false })
   })
   onBeforeUnmount(() => {
     onUp()
     swallowClick = false
-    window.removeEventListener("pointermove", onMove)
-    window.removeEventListener("pointerup", onUp)
-    window.removeEventListener("pointercancel", onUp)
-    window.removeEventListener("click", onClickCapture, true)
-    window.removeEventListener("contextmenu", onContextMenu, true)
+    listening?.removeEventListener("pointermove", onMove)
+    listening?.removeEventListener("pointerup", onUp)
+    listening?.removeEventListener("pointercancel", onUp)
+    listening?.removeEventListener("click", onClickCapture, true)
+    listening?.removeEventListener("contextmenu", onContextMenu, true)
     options.root.value?.removeEventListener("touchmove", onTouchMove)
   })
 

package/src/composables/usePaletteCommands.ts

@@ -1,5 +1,7 @@
 import { computed, getCurrentInstance, h, inject, onMounted, onUpdated, onScopeDispose, provide, ref, shallowReactive, shallowRef, toValue, useId, type Component, type Directive, type InjectionKey, type MaybeRefOrGetter } from "vue"
+import { menuPaletteCommands } from "../components/commandPalette"
 import type { Command } from "../components/LpCommandPalette.vue"
+import type { ContextMenuItemDef } from "../components/LpContextMenu.vue"
 import { provideField, useField } from "./useField"
 import { useLabels } from "./useLpConfig"
 
@@ -104,6 +106,17 @@ export function usePaletteCommands(commands: MaybeRefOrGetter<readonly Command[]
 }
 
 /** Manual definitions override a discovered command without changing its place. */
+/** A titled menu as one command of the palette, with its items inside. */
+export function useMenuPalette(menu: { palette?: PaletteControlOptions; title?: string; items: ContextMenuItemDef[] }) {
+  const scope = usePaletteScope()
+  const generated = useId()
+  usePaletteCommands(() => {
+    if (menu.palette === false || !menu.title || !menu.items.length) return []
+    const id = `${scope?.id}/${menu.palette?.id ?? generated}`
+    return [{ id, label: menu.palette?.label ?? menu.title, children: menuPaletteCommands(menu.items, id) }]
+  }, { automatic: true })
+}
+
 export function mergePaletteCommands(discovered: readonly Command[], manual: readonly Command[]): Command[] {
   const overrides = new Map(manual.map(command => [command.id, command]))
   return uniqueCommands([...discovered.map(command => overrides.get(command.id) ?? command), ...manual])
@@ -205,8 +218,11 @@ export function usePaletteControl(options: {
           h(raw.label ? "h3" : "label", { id: `${editorId}-label`, for: raw.label ? undefined : editorId, class: "text-sm font-semibold text-ink" }, label()),
           h(instance.type as Component, {
             ...raw, id: undefined, name: undefined, form: undefined, autofocus: undefined, palette: false,
-            disabled: options.disabled?.() || !writable(), invalid: options.invalid?.(),
-            required: field?.value.required ?? instance.props.required,
+            disabled: options.disabled?.() || !writable(),
+            // Only to a control that declares them: elsewhere they fell through
+            // as attributes onto its root (a switch's button took `required`).
+            ...("invalid" in instance.props ? { invalid: options.invalid?.() } : {}),
+            ...("required" in instance.props ? { required: field?.value.required ?? instance.props.required } : {}),
             "aria-label": label(), class: "w-full", style: undefined,
           }, instance.slots),
           error() || hint() ? h("p", { id: `${editorId}-message`, class: error() ? "text-xs text-danger" : "text-xs text-muted", role: error() ? "alert" : undefined }, error() || hint()) : null,

package/src/composables/usePersisted.ts

@@ -59,6 +59,16 @@ export interface PersistedOptions<T> {
  *
  * A changed key reads the new key's value, so one component instance can
  * follow the thing it shows (a drawer per record).
+ *
+ * Made for small preferences, and this is the contract:
+ * - JSON values only, `initial` included. A Map, Set or Date does not survive
+ *   the round trip, a key holding `undefined` is dropped, and a BigInt or a
+ *   cycle throws here, however `T` reads.
+ * - Every change walks the value and rewrites it whole, synchronously. A large
+ *   document wants its own saving: debounced, with dirty state and versions.
+ * - One owner per key. Two refs on one key do not see each other's writes
+ *   (the `storage` event only reaches other tabs) and the last write wins, so
+ *   share the ref instead.
  */
 export function usePersisted<T>(
   key: MaybeRefOrGetter<string | false | null | undefined>,

package/src/composables/usePillTransition.ts

@@ -22,15 +22,18 @@ import { usePrefersReducedMotion } from "./useReducedMotion"
  */
 export type PillTransition =
   | { duration: number }
-  | { type: "spring"; stiffness: number; damping: number; mass?: number }
+  | Readonly<{ type: "spring"; stiffness: number; damping: number; mass?: number }>
 
 export type PillFeel = "pill" | "float" | "layout"
 
-const SPRING: Record<PillFeel, { type: "spring"; stiffness: number; damping: number; mass?: number }> = {
-  pill: { type: "spring", stiffness: 520, damping: 40 },
-  float: { type: "spring", stiffness: 210, damping: 26 },
-  layout: { type: "spring", stiffness: 520, damping: 42, mass: 0.9 },
-}
+type Spring = Readonly<{ type: "spring"; stiffness: number; damping: number; mass?: number }>
+
+// Frozen: every consumer holds the same object, so one write would retune them all.
+const SPRING: Readonly<Record<PillFeel, Spring>> = Object.freeze({
+  pill: Object.freeze({ type: "spring", stiffness: 520, damping: 40 }),
+  float: Object.freeze({ type: "spring", stiffness: 210, damping: 26 }),
+  layout: Object.freeze({ type: "spring", stiffness: 520, damping: 42, mass: 0.9 }),
+})
 
 export function usePillTransition(feel: PillFeel = "pill"): ComputedRef<PillTransition> {
   const reduceMotion = usePrefersReducedMotion()

package/src/composables/useResizeObserver.ts

@@ -1,3 +1,4 @@
+import { nodeWindow } from "./realm"
 import { onScopeDispose, toValue, watch, type MaybeRefOrGetter } from "vue"
 
 /*
@@ -41,7 +42,7 @@ export function useResizeObserver(
       if (!el) return
       if (immediate) callback(undefined, el)
       if (typeof ResizeObserver === "undefined") return
-      observer = new ResizeObserver((entries) => {
+      observer = new (nodeWindow(el).ResizeObserver)((entries) => {
         const entry = entries[entries.length - 1]
         if (entry) callback(entry, el)
       })

package/src/composables/useReveal.ts

@@ -1,3 +1,4 @@
+import { nodeWindow } from "./realm"
 import { onBeforeUnmount, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from "vue"
 import { prefersReducedMotion } from "./easing"
 
@@ -102,7 +103,7 @@ export function useReveal(options: UseRevealOptions = {}): UseReveal {
         return
       }
 
-      observer = new IntersectionObserver(
+      observer = new (nodeWindow(node).IntersectionObserver)(
         (entries) => {
           if (entries.some((entry) => entry.isIntersecting)) reveal()
         },

package/src/composables/useRovingFocus.ts

@@ -1,6 +1,9 @@
 import { computed, ref, watch, type MaybeRefOrGetter, toValue } from "vue"
+import { isTextEntry } from "./textEntry"
+import { isHTMLElement } from "./useView"
 
 const NON_TEXT_INPUTS = new Set(["checkbox", "radio", "button", "submit", "reset", "range", "color", "file", "image"])
+const ROW_FIELD = { select: true, inputType: (type: string) => !NON_TEXT_INPUTS.has(type) }
 
 /*
  * Arrow-key navigation over a list, with a roving tabindex.
@@ -40,9 +43,9 @@ export interface UseRovingFocusOptions {
   /**
    * Which axis the arrows follow. `vertical` (default) uses ↑↓, `horizontal`
    * uses ←→, `both` accepts either — for a grid whose wrapping the caller
-   * cannot describe here.
+   * cannot describe here. A ref or getter follows a list that changes axis.
    */
-  orientation?: "vertical" | "horizontal" | "both"
+  orientation?: MaybeRefOrGetter<"vertical" | "horizontal" | "both">
   /** Wrap around at the ends instead of stopping. Default true. */
   loop?: boolean
   /** Jump to an item by typing its first letters. Default true. */
@@ -154,18 +157,13 @@ export function useRovingFocus(
     }
   }
 
-  function isTextEntry(target: EventTarget | null): boolean {
-    if (!(target instanceof HTMLElement)) return false
-    if (target.isContentEditable || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) return true
-    return target instanceof HTMLInputElement && !NON_TEXT_INPUTS.has(target.type)
-  }
-
   function onKeydown(event: KeyboardEvent) {
     // A field inside a row (an inline rename, a filter) owns its keys: the list
     // taking letters for typeahead or Space for activation made it untypeable.
-    if (event.isComposing || isTextEntry(event.target)) return
-    const vertical = orientation === "vertical" || orientation === "both"
-    const horizontal = orientation === "horizontal" || orientation === "both"
+    if (event.isComposing || isTextEntry(event.target, ROW_FIELD)) return
+    const axis = toValue(orientation)
+    const vertical = axis === "vertical" || axis === "both"
+    const horizontal = axis === "horizontal" || axis === "both"
 
     switch (event.key) {
       case "ArrowDown":
@@ -234,9 +232,8 @@ export function useRovingFocus(
    * narrowed the rows would yank the user out of the field they are typing in.
    */
   watch(activeId, (id) => {
-    if (!id || typeof document === "undefined") return
     const container = containerEl.value
-    if (!container || !container.contains(document.activeElement)) return
+    if (!id || !container || !container.contains(container.ownerDocument.activeElement)) return
     const target = container.querySelector<HTMLElement>(
       `[data-roving-id="${CSS.escape(id)}"]`,
     )
@@ -254,7 +251,7 @@ export function useRovingFocus(
 
   /** Bind on the element wrapping the rows. */
   const containerProps = computed(() => ({
-    ref: (el: unknown) => setContainer(el instanceof HTMLElement ? el : null),
+    ref: (el: unknown) => setContainer(isHTMLElement(el) ? el : null),
     onKeydown,
   }))
 

package/src/composables/useScramble.ts

@@ -65,15 +65,26 @@ export interface UseScramble {
   settle: () => void
 }
 
+const SEED_MULTIPLIER = 16807
+const SEED_MODULUS = 2147483647
+
+/* A small Lehmer generator: the same numbers in every render. */
+function seededRandom(seed = 1): () => number {
+  return () => (seed = (seed * SEED_MULTIPLIER) % SEED_MODULUS) / SEED_MODULUS
+}
+
 export function useScramble(source: MaybeRefOrGetter<string>, options: UseScrambleOptions = {}): UseScramble {
   const random = options.random ?? Math.random
+  // The masked first frame is drawn on the server too, so it may not differ
+  // from the client's: it rolls a fixed sequence, the animation a live one.
+  const firstRoll = options.random ?? seededRandom()
   const tick = options.tick ?? 50
   const glyphs = () => toValue(options.glyphs) || SCRAMBLE_GLYPHS
 
   const initial = toValue(source)
   const cells = shallowRef<ScrambleFrameCell[]>(
     options.start === "masked"
-      ? scrambleFrame(planScramble(initial, initial, { duration: 1, keep: options.keep }, random), 0, random, glyphs())
+      ? scrambleFrame(planScramble(initial, initial, { duration: 1, keep: options.keep }, firstRoll), 0, firstRoll, glyphs())
       : settledCells(initial),
   )
   const running = shallowRef(false)

package/src/composables/useShift.ts

@@ -1,3 +1,4 @@
+import { isElement, nodeWindow } from "./useView"
 import { nextTick, onBeforeUnmount, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from "vue"
 import { prefersReducedMotion } from "./easing"
 
@@ -118,7 +119,7 @@ export function useShift(
   const scrolled = new Set<Element>()
   const rememberScroll = (event: Event) => {
     const target = event.target
-    if (target instanceof Element) scrolled.add(target)
+    if (isElement(target)) scrolled.add(target)
   }
   function readScroll(): Map<Element, number> {
     const tops = new Map<Element, number>()
@@ -221,7 +222,7 @@ export function useShift(
     tweenStart = performance.now()
     resizing.value = true
     clearTimeout(settleTimer)
-    const wait = prefersReducedMotion() ? 0 : (toValue(options.duration) ?? TWEEN_MS)
+    const wait = prefersReducedMotion(nodeWindow(node)) ? 0 : (toValue(options.duration) ?? TWEEN_MS)
     settleTimer = setTimeout(() => {
       inFlight = false
       resizing.value = false
@@ -303,12 +304,13 @@ export function useShift(
         ro.disconnect()
         for (const child of Array.from(node.children)) ro.observe(child)
       }
-      if (typeof ResizeObserver !== "undefined") {
-        ro = new ResizeObserver(() => retune())
+      const win = nodeWindow(node)
+      if (typeof win.ResizeObserver !== "undefined") {
+        ro = new win.ResizeObserver(() => retune())
         watchChildren()
       }
-      if (typeof MutationObserver !== "undefined") {
-        mo = new MutationObserver(() => {
+      if (typeof win.MutationObserver !== "undefined") {
+        mo = new win.MutationObserver(() => {
           watchChildren()
           retune()
         })

package/src/composables/useTilt.ts

@@ -1,3 +1,4 @@
+import { isHTMLElement } from "./useView"
 import { computed, ref, toValue, type ComputedRef, type CSSProperties, type MaybeRefOrGetter, type Ref } from "vue"
 import { usePointerFrame } from "./usePointerFrame"
 import { usePrefersReducedMotion } from "./useReducedMotion"
@@ -67,7 +68,7 @@ export function useTilt(source: MaybeRefOrGetter<UseTiltOptions> = {}): UseTilt
   })
 
   function onPointerMove(e: PointerEvent): void {
-    if (e.currentTarget instanceof HTMLElement) target = e.currentTarget
+    if (isHTMLElement(e.currentTarget)) target = e.currentTarget
     pointer.move(e)
   }
 

package/src/composables/useTween.ts

@@ -1,4 +1,6 @@
-import { onScopeDispose, shallowRef, toValue, watch, type MaybeRefOrGetter, type ShallowRef } from "vue"
+import { clamp } from "./clamp"
+import { useView } from "./useView"
+import { hasInjectionContext, type MaybeRefOrGetter, onScopeDispose, shallowRef, type ShallowRef, toValue, watch } from "vue"
 import { durationToken, prefersReducedMotion, tokenEase } from "./easing"
 
 /*
@@ -47,6 +49,8 @@ export function useTween<T>(
   mix: (from: T, to: T, t: number) => T,
   options: TweenOptions<T> = {},
 ): Readonly<ShallowRef<T>> {
+  // Reads tokens where it animates; a store outside setup has only the page.
+  const view = hasInjectionContext() ? useView() : null
   const shown = shallowRef(source())
   let target = shown.value
   let frame = 0
@@ -59,11 +63,12 @@ export function useTween<T>(
   watch(source, (to) => {
     if (options.equal?.(target, to)) return
     target = to
-    const ms = toValue(options.duration) ?? durationToken("duration-medium")
+    const scope = view?.value?.document
+    const ms = toValue(options.duration) ?? durationToken("duration-medium", undefined, scope)
     if (
       toValue(options.enabled) === false ||
       ms <= 0 ||
-      prefersReducedMotion() ||
+      prefersReducedMotion(view?.value?.window) ||
       typeof requestAnimationFrame === "undefined"
     ) {
       stop()
@@ -72,12 +77,12 @@ export function useTween<T>(
     }
 
     const from = shown.value
-    const ease = options.ease ?? tokenEase("ease-emphasized")
+    const ease = options.ease ?? tokenEase("ease-emphasized", scope)
     const started = performance.now()
     stop()
     const step = (now: number) => {
       // rAF stamps the frame's start, which can precede the watcher by a few ms.
-      const t = Math.min(1, Math.max(0, (now - started) / ms))
+      const t = clamp((now - started) / ms, 0, 1)
       // The last frame is the target itself, not a mix that rounds near it, so
       // whatever the mix carried for the journey (ghosts, resampled points)
       // is gone once it lands.