@leavepulse/ui 0.77.3 → 0.78.0

package/src/components/fileTree.ts

@@ -4,6 +4,7 @@
  * component-to-component cycle. Re-exported from LpFileTree.vue.
  */
 
+import { clamp } from "../composables/clamp"
 import type { ContextMenuItemDef } from "./LpContextMenu.vue"
 import { formatBytes } from "./format"
 
@@ -329,3 +330,217 @@ export function ancestorIds(nodes: FileNode[], id: string): string[] {
   walk(nodes, [])
   return path
 }
+
+/** What narrows the tree. Every field is optional; all that are set must hold. */
+export interface FileTreeFilter {
+  /** Case-insensitive, against the entry's name and its path from the root. */
+  query?: string
+  kind?: FileNode["kind"]
+  /** File extensions without the dot. A directory never matches one. */
+  extensions?: string[]
+  /** Bytes, inclusive. An entry with no `size` does not match. */
+  minSize?: number
+  maxSize?: number
+  /** Inclusive. An entry with no readable `modified` does not match. */
+  modifiedFrom?: Date | number
+  modifiedTo?: Date | number
+}
+
+const PATH_SEPARATOR = "/"
+
+/** A file's extension, lowercase. A leading dot starts a name, not an extension. */
+export function fileExtension(name: string): string {
+  const dot = name.lastIndexOf(".")
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : ""
+}
+
+function modifiedTime(value: FileNode["modified"]): number {
+  if (value === undefined) return Number.NaN
+  return value instanceof Date ? value.getTime() : typeof value === "number" ? value : Date.parse(value)
+}
+
+const timeOf = (value: Date | number) => (typeof value === "number" ? value : value.getTime())
+
+/** True when no field of the filter would narrow anything. */
+export function isFilterEmpty(filter: FileTreeFilter | undefined): boolean {
+  if (!filter) return true
+  return (
+    !filter.query?.trim() &&
+    filter.kind === undefined &&
+    !filter.extensions?.length &&
+    filter.minSize === undefined &&
+    filter.maxSize === undefined &&
+    filter.modifiedFrom === undefined &&
+    filter.modifiedTo === undefined
+  )
+}
+
+/** Whether one entry, at this path, passes the filter on its own. */
+export function matchesFilter(node: FileNode, path: string, filter: FileTreeFilter): boolean {
+  const needle = filter.query?.trim().toLowerCase()
+  if (needle && !node.name.toLowerCase().includes(needle) && !path.toLowerCase().includes(needle)) return false
+  if (filter.kind && node.kind !== filter.kind) return false
+  if (filter.extensions?.length) {
+    if (node.kind !== "file") return false
+    const wanted = filter.extensions.map((ext) => ext.replace(/^\./, "").toLowerCase())
+    if (!wanted.includes(fileExtension(node.name))) return false
+  }
+  if (filter.minSize !== undefined || filter.maxSize !== undefined) {
+    if (node.size === undefined) return false
+    if (filter.minSize !== undefined && node.size < filter.minSize) return false
+    if (filter.maxSize !== undefined && node.size > filter.maxSize) return false
+  }
+  if (filter.modifiedFrom !== undefined || filter.modifiedTo !== undefined) {
+    const time = modifiedTime(node.modified)
+    if (Number.isNaN(time)) return false
+    if (filter.modifiedFrom !== undefined && time < timeOf(filter.modifiedFrom)) return false
+    if (filter.modifiedTo !== undefined && time > timeOf(filter.modifiedTo)) return false
+  }
+  return true
+}
+
+export interface FilteredTree {
+  nodes: FileNode[]
+  /** Directories that hold a match: shown open while the filter is on. */
+  openIds: Set<string>
+}
+
+/**
+ * The tree with only the matches and the folders leading to them. A kept folder
+ * is a copy whose `children` are its kept entries, so what is ticked through it
+ * is what is shown. A folder that is not loaded keeps `children` undefined: only
+ * loaded entries can be searched.
+ */
+export function filterTree(nodes: FileNode[], filter: FileTreeFilter | undefined): FilteredTree {
+  const openIds = new Set<string>()
+  if (!filter || isFilterEmpty(filter)) return { nodes, openIds }
+  const active = filter
+
+  function walk(list: FileNode[], parentPath: string): FileNode[] {
+    const kept: FileNode[] = []
+    for (const node of list) {
+      const path = parentPath ? `${parentPath}${PATH_SEPARATOR}${node.name}` : node.name
+      const children = node.children && walk(node.children, path)
+      if (children?.length) {
+        openIds.add(node.id)
+        kept.push({ ...node, children })
+      } else if (matchesFilter(node, path, active)) {
+        kept.push(children ? { ...node, children } : node)
+      }
+    }
+    return kept
+  }
+
+  return { nodes: walk(nodes, ""), openIds }
+}
+
+/** The tree with children fetched by `load` put in place. The app's own `children` win. */
+export function withLoadedChildren(nodes: FileNode[], loaded: ReadonlyMap<string, FileNode[]>): FileNode[] {
+  if (!loaded.size) return nodes
+  return nodes.map((node) => {
+    if (node.kind !== "dir") return node
+    const children = node.children ?? loaded.get(node.id)
+    if (!children) return node
+    return { ...node, children: withLoadedChildren(children, loaded) }
+  })
+}
+
+/** One row of the flattened tree, with what a flat DOM cannot imply to assistive tech. */
+export interface FlatRow {
+  node: FileNode
+  depth: number
+  /** Siblings at this level, and this row's 1-based place among them. */
+  setSize: number
+  posInSet: number
+}
+
+/** The visible rows in render order: open directories followed by their children. */
+export function flattenVisible(nodes: FileNode[], open: ReadonlySet<string>, sort: boolean): FlatRow[] {
+  const rows: FlatRow[] = []
+  function walk(list: FileNode[], depth: number) {
+    const ordered = sort ? sortNodes(list) : list
+    ordered.forEach((node, index) => {
+      rows.push({ node, depth, setSize: ordered.length, posInSet: index + 1 })
+      if (node.kind === "dir" && open.has(node.id) && node.children?.length) walk(node.children, depth + 1)
+    })
+  }
+  walk(nodes, 0)
+  return rows
+}
+
+export interface RowWindow {
+  /** First row to render, and one past the last. */
+  start: number
+  end: number
+}
+
+/** Which rows a scroll position shows, with `overscan` extra on each side. */
+export function rowWindow(scrollTop: number, viewport: number, rowHeight: number, total: number, overscan: number): RowWindow {
+  const first = Math.floor(Math.max(0, scrollTop) / rowHeight)
+  const count = Math.ceil(Math.max(0, viewport) / rowHeight)
+  return {
+    start: clamp(first - overscan, 0, total),
+    end: Math.min(total, first + count + overscan),
+  }
+}
+
+/** Ids between two rows, inclusive, in row order; locked rows are left out. */
+export function rangeIds(rows: readonly FileNode[], anchor: string | undefined, target: string): string[] {
+  const to = rows.findIndex((node) => node.id === target)
+  if (to < 0) return []
+  const found = anchor === undefined ? -1 : rows.findIndex((node) => node.id === anchor)
+  const from = found < 0 ? to : found
+  return rows
+    .slice(Math.min(from, to), Math.max(from, to) + 1)
+    .filter((node) => !node.disabled)
+    .map((node) => node.id)
+}
+
+/** The chain from the root down to `id`, itself included. */
+export function nodeTrail(id: string, byId: ReadonlyMap<string, FileNode>, parentOf: ReadonlyMap<string, string>): FileNode[] {
+  const trail: FileNode[] = []
+  for (let at: string | undefined = id; at !== undefined; at = parentOf.get(at)) {
+    const node = byId.get(at)
+    if (node) trail.unshift(node)
+  }
+  return trail
+}
+
+/**
+ * Whether `sources` may land in `target`: a directory that is not one of them,
+ * not inside one of them, and not where all of them already are.
+ */
+export function canDrop(sources: readonly string[], target: FileNode, parentOf: ReadonlyMap<string, string>): boolean {
+  if (target.kind !== "dir" || target.disabled || !sources.length) return false
+  for (let at: string | undefined = target.id; at !== undefined; at = parentOf.get(at)) {
+    if (sources.includes(at)) return false
+  }
+  return sources.some((id) => parentOf.get(id) !== target.id)
+}
+
+/** Those of `ids` no other of them contains: a moved folder carries what is inside it. */
+export function topmostIds(ids: readonly string[], parentOf: ReadonlyMap<string, string>): string[] {
+  const all = new Set(ids)
+  return ids.filter((id) => {
+    for (let at = parentOf.get(id); at !== undefined; at = parentOf.get(at)) {
+      if (all.has(at)) return false
+    }
+    return true
+  })
+}
+
+export type RenameProblem = "empty" | "separator" | "duplicate"
+
+/** Why a new name cannot stand, or null. An unchanged name is the caller's no-op. */
+export function renameProblem(name: string, node: FileNode, siblings: readonly FileNode[]): RenameProblem | null {
+  const next = name.trim()
+  if (!next) return "empty"
+  if (/[/\\\0]/.test(next)) return "separator"
+  return siblings.some((other) => other.id !== node.id && other.name === next) ? "duplicate" : null
+}
+
+/** How much of a name to select for renaming: the stem, so the extension survives typing. */
+export function renameSelectionEnd(node: FileNode): number {
+  const dot = node.name.lastIndexOf(".")
+  return node.kind === "file" && dot > 0 ? dot : node.name.length
+}

package/src/components/identicon.ts

@@ -1,3 +1,5 @@
+import { clamp } from "../composables/clamp"
+
 /*
  * Identicons: a picture derived from a string, so something with no avatar
  * of its own (a new account, a server, an API key, a commit) still gets a
@@ -67,7 +69,7 @@ function generator(seed: number): () => number {
 
 /** The grid and colour for a seed. */
 export function identicon(seed: string, options: IdenticonOptions = {}): Identicon {
-  const size = Math.max(3, Math.min(12, Math.round(options.grid ?? 5)))
+  const size = clamp(Math.round(options.grid ?? 5), 3, 12)
   const [sMin, sMax] = options.saturation ?? [55, 72]
   const [lMin, lMax] = options.lightness ?? [48, 60]
   const next = generator(hashString(seed))
@@ -146,7 +148,7 @@ export interface IdenticonSvgOptions extends IdenticonOptions {
 export function identiconSvg(seed: string, options: IdenticonSvgOptions = {}): string {
   const { cells, color } = identicon(seed, options)
   const n = cells.length
-  const pad = n * Math.max(0, Math.min(0.4, options.padding ?? 0.12))
+  const pad = n * clamp(options.padding ?? 0.12, 0, 0.4)
   const view = n + pad * 2
   const px = options.size ?? 64
   const bg = options.background ? `<rect width="${view}" height="${view}" fill="${options.background}"/>` : ""

package/src/components/logTools.ts

@@ -0,0 +1,298 @@
+/*
+ * The log viewer's reading tools, free of the component so their rules can be
+ * tested alone: pattern search, time range, repeats, correlation ids, structured
+ * payloads and what a selection exports as.
+ */
+
+/*
+ * A pattern is typed by a person but runs over every line of a live stream, and
+ * JavaScript cannot interrupt a running match. So the guard is in what may reach
+ * the engine: a bounded pattern, none of the nested quantifiers that backtrack
+ * catastrophically, a bounded length of text per line, and a time budget per
+ * pass that stops starting new lines. A single match on one capped line is the
+ * longest it can block.
+ */
+export const MAX_PATTERN_LENGTH = 200
+export const MAX_MATCH_INPUT = 2000
+export const MATCH_BUDGET_MS = 50
+const NESTED_QUANTIFIER = /\((?:[^()\\]|\\.)*[+*](?:[^()\\]|\\.)*\)\s*(?:[+*]|\{\d+,\d*\})/
+
+export type PatternError = "too-long" | "unsafe" | "invalid"
+
+export interface LogPattern {
+  test(text: string): boolean
+  ranges(text: string): [number, number][]
+}
+
+export function compilePattern(source: string): { pattern: LogPattern | null; error: PatternError | null } {
+  if (source.length > MAX_PATTERN_LENGTH) return { pattern: null, error: "too-long" }
+  if (NESTED_QUANTIFIER.test(source)) return { pattern: null, error: "unsafe" }
+  let regex: RegExp
+  try {
+    regex = new RegExp(source, "giu")
+  } catch {
+    return { pattern: null, error: "invalid" }
+  }
+  const capped = (text: string) => (text.length > MAX_MATCH_INPUT ? text.slice(0, MAX_MATCH_INPUT) : text)
+  return {
+    error: null,
+    pattern: {
+      test(text) {
+        regex.lastIndex = 0
+        return regex.test(capped(text))
+      },
+      ranges(text) {
+        const out: [number, number][] = []
+        // matchAll starts from wherever the last `test` left the shared regex.
+        regex.lastIndex = 0
+        for (const match of capped(text).matchAll(regex)) {
+          // A zero-width match highlights nothing.
+          if (match[0]) out.push([match.index, match.index + match[0].length])
+        }
+        return out
+      },
+    },
+  }
+}
+
+/** Positions of the rows the pattern finds, giving up once the budget is spent. */
+export function patternPositions(
+  rows: readonly { message: string; source?: string }[],
+  pattern: LogPattern,
+  now: () => number = () => performance.now(),
+): number[] {
+  const out: number[] = []
+  const deadline = now() + MATCH_BUDGET_MS
+  for (let i = 0; i < rows.length; i++) {
+    if (now() > deadline) break
+    const row = rows[i]
+    if (pattern.test(row.message) || (row.source !== undefined && pattern.test(row.source))) out.push(i)
+  }
+  return out
+}
+
+/** Every occurrence of a plain term, case-insensitive. */
+export function termRanges(text: string, term: string): [number, number][] {
+  const needle = term.toLowerCase()
+  if (!needle) return []
+  const lower = text.toLowerCase()
+  const out: [number, number][] = []
+  for (let at = lower.indexOf(needle); at !== -1; at = lower.indexOf(needle, at + needle.length)) {
+    out.push([at, at + needle.length])
+  }
+  return out
+}
+
+/** A line's time as epoch ms; a pre-formatted label ("12:03:05") has none. */
+export function timeMs(time: number | string | undefined): number | null {
+  if (time == null) return null
+  if (typeof time === "number") return Number.isFinite(time) ? time : null
+  if (/^\d+$/.test(time)) return Number(time)
+  const parsed = Date.parse(time)
+  return Number.isNaN(parsed) ? null : parsed
+}
+
+export interface LogTimeRange {
+  from?: number | string
+  to?: number | string
+}
+
+/**
+ * Inclusive at both ends. A line with no readable time stays: most are the
+ * continuation of the entry above (a stack frame), and hiding them would cut
+ * the entries the range keeps in half.
+ */
+export function inTimeRange(time: number | string | undefined, range: LogTimeRange | undefined): boolean {
+  if (!range) return true
+  const at = timeMs(time)
+  if (at === null) return true
+  const from = timeMs(range.from)
+  const to = timeMs(range.to)
+  return (from === null || at >= from) && (to === null || at <= to)
+}
+
+/** The position of the row closest in time, -1 when none has a readable time. */
+export function nearestByTime(rows: readonly { time?: number | string }[], target: number | string): number {
+  const wanted = timeMs(target)
+  if (wanted === null) return -1
+  let best = -1
+  let distance = Infinity
+  rows.forEach((row, i) => {
+    const at = timeMs(row.time)
+    if (at === null) return
+    const gap = Math.abs(at - wanted)
+    if (gap < distance) {
+      best = i
+      distance = gap
+    }
+  })
+  return best
+}
+
+const VOLATILE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b|\b0x[0-9a-f]+\b|\b[0-9a-f]{16,}\b|\d+(?:\.\d+)*/gi
+
+/** A message with its volatile parts (numbers, ids, hashes) blanked, so repeats compare equal. */
+export function messageShape(message: string): string {
+  return message.replace(VOLATILE, "#")
+}
+
+export interface RepeatRow<L> {
+  line: L
+  n: number
+  count: number
+}
+
+/** Folds rows of the same level, source and shape into the first, wherever they sit. */
+export function groupRepeats<L extends { message: string; level?: string; source?: string }>(
+  rows: readonly { line: L; n: number }[],
+): RepeatRow<L>[] {
+  const groups = new Map<string, RepeatRow<L>>()
+  for (const { line, n } of rows) {
+    const key = [line.level ?? "", line.source ?? "", messageShape(line.message)].join("\0")
+    const group = groups.get(key)
+    if (group) group.count++
+    else groups.set(key, { line, n, count: 1 })
+  }
+  return [...groups.values()]
+}
+
+export type LogIdKind = "trace" | "request" | "span" | "correlation"
+
+export interface LogId {
+  kind: LogIdKind
+  value: string
+  start: number
+  end: number
+}
+
+const ID_PATTERN = /\b(trace|request|req|span|correlation|corr)[_-]?id["']?\s*[=:]\s*["']?([\w-]{6,})/gi
+const ID_KINDS: Record<string, LogIdKind> = {
+  trace: "trace",
+  request: "request",
+  req: "request",
+  span: "span",
+  correlation: "correlation",
+  corr: "correlation",
+}
+
+/** The correlation ids a message carries, as `trace_id=abc` or `"requestId": "abc"`. */
+export function findIds(message: string): LogId[] {
+  const out: LogId[] = []
+  for (const match of message.matchAll(ID_PATTERN)) {
+    const value = match[2]
+    const start = match.index + match[0].length - value.length
+    out.push({ kind: ID_KINDS[match[1].toLowerCase()], value, start, end: start + value.length })
+  }
+  return out
+}
+
+export interface MessagePart {
+  text: string
+  hit: boolean
+  id?: LogId
+}
+
+/** A message cut around its search hits and ids. An id wins where the two overlap. */
+export function messageParts(message: string, hits: readonly [number, number][], ids: readonly LogId[]): MessagePart[] {
+  const parts: MessagePart[] = []
+  const plain = (from: number, to: number) => {
+    let at = from
+    for (const [start, end] of hits) {
+      if (end <= at || start >= to) continue
+      if (start > at) parts.push({ text: message.slice(at, start), hit: false })
+      const stop = Math.min(end, to)
+      parts.push({ text: message.slice(Math.max(start, at), stop), hit: true })
+      at = stop
+    }
+    if (at < to) parts.push({ text: message.slice(at, to), hit: false })
+  }
+  let at = 0
+  for (const id of ids) {
+    plain(at, id.start)
+    parts.push({ text: message.slice(id.start, id.end), hit: false, id })
+    at = id.end
+  }
+  plain(at, message.length)
+  return parts.length ? parts : [{ text: message, hit: false }]
+}
+
+/** The object or array a message holds, whole or after a text prefix; null when it holds none. */
+export function structuredPayload(message: string): object | null {
+  const start = message.search(/[{[]/)
+  if (start < 0) return null
+  try {
+    const value: unknown = JSON.parse(message.slice(start))
+    return typeof value === "object" && value !== null ? value : null
+  } catch {
+    return null
+  }
+}
+
+export interface JsonRow {
+  path: string
+  depth: number
+  label: string
+  /** Rendered value; for an object or array its size, as `{3}` or `[3]`. */
+  value: string
+  kind: "object" | "array" | "string" | "number" | "boolean" | "null"
+  expandable: boolean
+}
+
+function kindOf(value: unknown): JsonRow["kind"] {
+  if (value === null) return "null"
+  if (Array.isArray(value)) return "array"
+  const type = typeof value
+  return type === "string" || type === "number" || type === "boolean" ? type : "object"
+}
+
+function holds(value: unknown, needle: string, label: string): boolean {
+  if (label.toLowerCase().includes(needle)) return true
+  if (value !== null && typeof value === "object") {
+    return Object.entries(value).some(([key, child]) => holds(child, needle, key))
+  }
+  return String(value).toLowerCase().includes(needle)
+}
+
+/**
+ * A payload as flat rows, skipping what is collapsed. With `filter`, only the
+ * fields whose name or value hold it, plus the parents leading to them.
+ */
+export function jsonRows(root: object, collapsed: ReadonlySet<string>, filter = ""): JsonRow[] {
+  const needle = filter.trim().toLowerCase()
+  const rows: JsonRow[] = []
+  const walk = (value: object, parent: string, depth: number) => {
+    for (const [label, child] of Object.entries(value)) {
+      if (needle && !holds(child, needle, label)) continue
+      const path = parent ? `${parent}.${label}` : label
+      const kind = kindOf(child)
+      const nested = kind === "object" || kind === "array"
+      const size = nested ? Object.keys(child as object).length : 0
+      const shown = kind === "array" ? `[${size}]` : kind === "object" ? `{${size}}` : kind === "string" ? (child as string) : String(child)
+      rows.push({ path, depth, label, value: shown, kind, expandable: nested && size > 0 })
+      if (nested && !collapsed.has(path)) walk(child as object, path, depth + 1)
+    }
+  }
+  walk(root, "", 0)
+  return rows
+}
+
+const STACK_FRAME = /^\s*(?:at\s+\S|File ".+", line \d+|#\d+\s|\S+\.\w+:\d+)/
+
+/** Text split into lines, with a stack's frames marked; null when it holds no stack. */
+export function stackLines(text: string): { text: string; frame: boolean }[] | null {
+  const lines = text.split(/\r?\n/).map((line) => ({ text: line, frame: STACK_FRAME.test(line) }))
+  return lines.length > 1 && lines.some((line) => line.frame) ? lines : null
+}
+
+export type LogExportFormat = "text" | "ndjson"
+
+/** Lines as a file: readable text, or one JSON object per line. */
+export function exportLines<L>(lines: readonly L[], format: LogExportFormat, asText: (line: L) => string): string {
+  const rows = format === "ndjson" ? lines.map((line) => JSON.stringify(line)) : lines.map(asText)
+  return rows.join("\n")
+}
+
+/** The inclusive run between two row numbers, whichever order they came in. */
+export function rowSpan(from: number, to: number): [number, number] {
+  return from <= to ? [from, to] : [to, from]
+}

package/src/components/meter.ts

@@ -5,6 +5,7 @@
  * disk agree on when it turns amber, instead of each picking its own breakpoints.
  * The colours themselves are tone.ts's: a meter tone is one of its aliases.
  */
+import { clamp } from "../composables/clamp"
 import { TONE_ALIASES, TONES, type ToneLook } from "./tone"
 
 /**
@@ -38,7 +39,7 @@ export const TONE_SOFT: Record<MeterTone, string> = byMeterTone((look) => look.s
 export function meterFraction(value: number, min: number, max: number): number {
   const span = max - min
   if (!(span > 0) || !Number.isFinite(value)) return 0
-  return Math.max(0, Math.min(1, (value - min) / span))
+  return clamp((value - min) / span, 0, 1)
 }
 
 /**

package/src/components/pipeline.ts

@@ -99,3 +99,9 @@ export function childProgress(step: PipelineStep): { done: number; total: number
 export function stepKey(step: Pick<PipelineStep, "key">, index: number): string {
   return step.key ?? String(index)
 }
+
+/** Keys used by more than one step, which would then share their open state. */
+export function duplicateStepKeys(steps: readonly Pick<PipelineStep, "key">[]): string[] {
+  const keys = steps.map(stepKey)
+  return [...new Set(keys.filter((key, i) => keys.indexOf(key) !== i))]
+}

package/src/components/relativeTime.ts

@@ -1,3 +1,4 @@
+import { clamp } from "../composables/clamp"
 import { toEpoch } from "./timeSpan"
 
 /*
@@ -114,5 +115,5 @@ export function formatRelativeTime(
 }
 
 function clampRefresh(ms: number): number {
-  return Math.min(MAX_REFRESH, Math.max(MIN_REFRESH, Math.ceil(ms)))
+  return clamp(Math.ceil(ms), MIN_REFRESH, MAX_REFRESH)
 }

package/src/components/reveal.ts

@@ -1,3 +1,5 @@
+import { clamp } from "../composables/clamp"
+
 /*
  * Keyframes and timing for LpRevealOnScroll, kept apart from the component so
  * they can be tested without a DOM.
@@ -52,5 +54,5 @@ export function revealTo(from: Keyframe): Keyframe {
  * last rows would still be invisible when the user starts reading them.
  */
 export function staggerDelay(index: number, delay: number, stagger: number, cap = 10): number {
-  return delay + Math.min(Math.max(0, index), cap) * Math.max(0, stagger)
+  return delay + clamp(index, 0, cap) * Math.max(0, stagger)
 }

package/src/components/select.ts

@@ -3,6 +3,20 @@
  * testable without a DOM.
  */
 
+/**
+ * Drop the oldest entries past `limit`, never one of `keep`. For a cache that
+ * must outlive the list it was read from, in a long session over a big catalog.
+ */
+export function evictOldest<K, V>(cache: Map<K, V>, keep: ReadonlySet<K>, limit: number): void {
+  let excess = cache.size - limit
+  for (const key of cache.keys()) {
+    if (excess <= 0) return
+    if (keep.has(key)) continue
+    cache.delete(key)
+    excess--
+  }
+}
+
 /**
  * How many chips of a multiple pick fit in one row before the rest collapse
  * into a "+N" chip.

package/src/components/sidebar.ts

@@ -48,6 +48,7 @@ export interface SidebarItem {
    * away without opening the section first. In a compact sidebar they open in
    * a card beside the icon.
    */
+  /** One level: search, the active row and the rail stop at these pages, nothing under them is drawn. */
   children?: SidebarItem[]
   /** A dot instead of a count: something new here that has no number to it. */
   dot?: boolean