Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(knowledge): rework the parse timeline panel's layout and failure card

wizardchena163bab32f75
diff --git a/frontend/src/components/knowledge-processing-timeline.vue b/frontend/src/components/knowledge-processing-timeline.vue
index e87d62b7f..e9c89079a 100644
--- a/frontend/src/components/knowledge-processing-timeline.vue
+++ b/frontend/src/components/knowledge-processing-timeline.vue
@@ -11,6 +11,7 @@ import {
type KnowledgeTraceNode,
} from '@/utils/knowledgeTrace'
import { resolveTimelineHeaderStatus } from '@/utils/knowledgeProcessingStatus'
+import { axisGridStepPct, buildAxisTicks, computeTraceAxis } from '@/utils/traceAxis'
import type { KnowledgeProcessOverrides } from '@/types/knowledgeProcess'
type SpanNode = KnowledgeTraceNode
@@ -92,6 +93,10 @@ const refreshing = ref(false)
const selectedAttempt = ref<number | undefined>(undefined)
const expandedRows = ref<Set<string>>(new Set(['__root__']))
const selectedSpanId = ref<string | null>(null)
+// Guards the one-shot auto-selection below. Cleared once the panel has
+// opened itself, or the moment the user closes it — a 2s poll must never
+// reopen a panel the user just dismissed.
+const autoSelectPending = ref(true)
const expandedJsonKeys = ref<Set<string>>(new Set())
const nowTick = ref(Date.now())
const detailTab = ref<'overview' | 'input' | 'output' | 'metadata' | 'raw'>('overview')
@@ -385,6 +390,9 @@ async function fetchSpans(opts: { manual?: boolean } = {}) {
attemptStatuses.set(data.value.attempt, tabStatus)
ensureAttemptStatuses()
emit('update:hasSpans', knowledgeSpansPayloadHasTrace(data.value))
+ // flatRows is derived from data.value; wait for it to recompute
+ // before picking a row out of it.
+ nextTick(autoSelectSpan)
} else {
emit('update:hasSpans', false)
}
@@ -462,6 +470,7 @@ async function onRetry() {
selectedAttempt.value = undefined
attemptStatuses.clear()
selectedSpanId.value = null
+ autoSelectPending.value = true
await fetchSpans()
} catch {
// ignore
@@ -503,6 +512,7 @@ function onAttemptChange(n: number) {
if (Number.isNaN(n)) return
selectedAttempt.value = n
selectedSpanId.value = null
+ autoSelectPending.value = true
// New attempt: forget per-row user choices so the auto-expand
// rule re-evaluates cleanly against the new attempt's tree.
userToggledRows.value = new Set()
@@ -519,6 +529,7 @@ watch(
currentKnowledgeFileType.value = ''
expandedRows.value = new Set(['__root__'])
selectedSpanId.value = null
+ autoSelectPending.value = true
attemptStatuses.clear()
userToggledRows.value = new Set()
fetchSpans()
@@ -528,7 +539,7 @@ watch(
function onKeydown(ev: KeyboardEvent) {
if (ev.key === 'Escape' && selectedSpanId.value) {
- selectedSpanId.value = null
+ closeDetail()
}
}
@@ -686,25 +697,21 @@ const totalMs = computed<number>(() => {
const showRuler = computed(() => totalMs.value >= 50)
-const rulerTicks = computed(() => {
- if (!showRuler.value) return [] as { left: string; label: string }[]
- const total = totalMs.value
- const fmt = (ms: number) => formatDuration(ms)
- return [
- { left: '0%', label: fmt(0) },
- { left: '25%', label: fmt(total * 0.25) },
- { left: '50%', label: fmt(total * 0.5) },
- { left: '75%', label: fmt(total * 0.75) },
- { left: '100%', label: fmt(total) },
- ]
-})
+// ---------- Time axis ----------
+// See utils/traceAxis: the ruler is a rounded 1/2/2.5/5 axis, and every
+// bar is positioned against axis.maxMs rather than the raw total so the
+// bars and the ruler above them cannot disagree.
+const timeAxis = computed(() => computeTraceAxis(totalMs.value))
+const axisMaxMs = computed(() => timeAxis.value.maxMs)
+const gridStepPct = computed(() => axisGridStepPct(timeAxis.value))
+const rulerTicks = computed(() => (showRuler.value ? buildAxisTicks(timeAxis.value) : []))
// "Now" position on the waterfall scale, used to draw the live cursor
// while polling so the user can see time advancing even when the running
// stage's bar grows slowly toward the right edge.
const nowMarkerPct = computed<number | null>(() => {
- if (!isLive.value || !t0.value || !totalMs.value) return null
- const pct = ((nowTick.value - t0.value) / totalMs.value) * 100
+ if (!isLive.value || !t0.value || !axisMaxMs.value) return null
+ const pct = ((nowTick.value - t0.value) / axisMaxMs.value) * 100
return Math.max(0, Math.min(100, pct))
})
@@ -781,7 +788,7 @@ const selectedRow = computed<FlatRow | null>(() => {
const detailOpen = computed(() => selectedSpanId.value !== null && selectedRow.value !== null)
function barStyle(node: SpanNode): Record<string, string> {
- const total = totalMs.value
+ const total = axisMaxMs.value
if (!total || t0.value === null) return { display: 'none' }
const start = nodeStart(node)
if (start === null) return { display: 'none' }
@@ -816,7 +823,7 @@ function descendantMaxEnd(node: SpanNode): number | null {
}
function wrapStyle(node: SpanNode): Record<string, string> | null {
- const total = totalMs.value
+ const total = axisMaxMs.value
if (!total || t0.value === null) return null
const start = nodeStart(node)
if (start === null) return null
@@ -843,7 +850,7 @@ function wrapDurationMs(node: SpanNode): number {
}
function barOffsetPct(node: SpanNode): number | null {
- const total = totalMs.value
+ const total = axisMaxMs.value
if (!total || t0.value === null) return null
const start = nodeStart(node)
if (start === null) return null
@@ -866,6 +873,20 @@ function isPlaceholder(node: SpanNode): boolean {
return !node.span_id && !node.started_at
}
+// The trace has reached a terminal state and nothing is still ticking.
+const traceTerminal = computed<boolean>(
+ () => isHardTerminal(data.value?.parse_status) && !traceActive.value,
+)
+
+// A synthesized stage still marked 'pending' on a finished trace never
+// ran and never will — docreader failed, so chunking/embedding/... were
+// abandoned. v1 rendered them as ordinary pending rows with a dashed
+// stub pinned to the right edge of the track, which reads as leftover
+// rendering junk. Say "not run" in words and let the row recede.
+function isNotRun(node: SpanNode): boolean {
+ return traceTerminal.value && node.status === 'pending' && isPlaceholder(node)
+}
+
function isRowExpanded(key: string): boolean {
return expandedRows.value.has(key)
}
@@ -921,6 +942,22 @@ function selectRow(row: FlatRow) {
function closeDetail() {
selectedSpanId.value = null
+ autoSelectPending.value = false
+}
+
+// v1 opened with nothing selected, so a short trace showed a handful of
+// rows above half a panel of white space, and nothing suggested the rows
+// were clickable at all. Open on the span the reader came for: the one
+// that failed, or the root (whose detail is the stage breakdown).
+function autoSelectSpan() {
+ if (props.compact) return
+ if (!autoSelectPending.value || selectedSpanId.value) return
+ const rows = flatRows.value
+ if (rows.length === 0) return
+ const failed = rows.find((r) => !r.isRoot && r.node.status === 'failed')
+ selectedSpanId.value = (failed || rows[0]).key
+ detailTab.value = 'overview'
+ autoSelectPending.value = false
}
function isObjectWithKeys(v: any): boolean {
@@ -957,10 +994,13 @@ function rowLabel(row: FlatRow): string {
return row.node.name
}
+// v1 stamped ROOT / STAGE / SPAN on every row and flung the label to the
+// far right of the name column with margin-left:auto, which opened a
+// ~200px gap mid-row and told the reader nothing that indentation hadn't
+// already said. Only `generation` (an LLM/VLM call) is worth a chip.
function rowKindLabel(row: FlatRow): string {
- if (row.isRoot) return 'root'
- if (row.isStage) return 'stage'
- return row.node.kind || 'span'
+ if (row.isRoot || row.isStage) return ''
+ return row.node.kind === 'generation' ? 'generation' : ''
}
function jsonExpandKey(section: string, key: string): string {
@@ -1178,6 +1218,38 @@ const showLastError = computed(() =>
Boolean(data.value?.last_error && data.value?.parse_status === 'failed'),
)
+const failedStage = computed<SpanNode | null>(
+ () => stages.value.find((s) => s.status === 'failed') || null,
+)
+
+// v1's headline was localizedErrorTitle(code), which falls back to the
+// raw code when no translation exists — so the card printed
+// DOCREADER_PARSE_FAILED as its title AND again as the chip beside it,
+// while the one line that actually explains the failure
+// ("Unsupported file type: htm") sat at the bottom in 11px grey mono.
+// The headline now says WHERE it broke, the code appears exactly once,
+// and the message is promoted to the card's primary line.
+const errorHeadline = computed(() => {
+ const err = data.value?.last_error
+ const localized = localizedErrorTitle(err?.error_code)
+ if (localized && localized !== err?.error_code) return localized
+ // Prefer a stage row that actually carries the failure; fall back to
+ // the span name the backend recorded on last_error, which covers a
+ // failure raised before any stage span opened.
+ const name = failedStage.value?.name
+ || (STAGES as readonly string[]).find((n) => n === err?.name)
+ if (name) {
+ return t('knowledgeStages.stageFailed', { stage: t(`knowledgeStages.stage.${name}`) })
+ }
+ return t('knowledgeStages.status.failed')
+})
+
+// Retry stays reachable from the toolbar when a failure has no
+// last_error payload to hang the in-card button off.
+const showToolbarRetry = computed(
+ () => data.value?.parse_status === 'failed' && !showLastError.value,
+)
+
const stagesStatDisplay = computed(() => {
const total = stages.value.length
const completedCount = stages.value.filter(
@@ -1202,38 +1274,70 @@ const postprocessTaskStats = computed(() =>
summarizePostprocessTasks(data.value?.trace),
)
-const headMetaParts = computed(() => {
+interface HeadStat {
+ key: string
+ label: string
+ value: string
+ mono: boolean
+ note?: boolean
+}
+
+// v1 glued five unrelated facts into one dot-separated grey sentence —
+// "处理流水线 · 总耗时 494ms · 当前阶段 1/5 · 第 1 次尝试" — which reads
+// as a run-on and buries the numbers among the words. Label/value pairs
+// with the numbers in tabular mono scan in one pass instead. The panel's
+// own name moves out of the sentence and onto the overline above the
+// title, where it belongs.
+const headStats = computed<HeadStat[]>(() => {
if (!data.value) return []
- const parts: string[] = [t('knowledgeStages.title')]
+ const out: HeadStat[] = []
if (totalMs.value > 0) {
- parts.push(t('knowledgeStages.total', { d: formatDuration(totalMs.value) }))
+ out.push({
+ key: 'duration',
+ label: t('knowledgeStages.stat.duration'),
+ value: formatDuration(totalMs.value),
+ mono: true,
+ })
}
const st = stagesStatDisplay.value
- parts.push(`${st.label} ${st.value}`)
+ out.push({ key: 'stages', label: st.label, value: st.value, mono: true })
+
const postprocess = postprocessTaskStats.value
if (postprocess.total > 0) {
- parts.push(t('knowledgeStages.head.postprocessTasks', {
- running: postprocess.running,
- failed: postprocess.failed,
- completed: postprocess.completed,
- }))
- }
- if (data.value.parse_status === 'completed' && postprocess.running > 0) {
- parts.push(t('knowledgeStages.head.completedWithActiveTrace', {
- n: postprocess.running,
- }))
+ out.push({
+ key: 'tasks',
+ label: t('knowledgeStages.stat.tasks'),
+ value: t('knowledgeStages.stat.tasksValue', {
+ running: postprocess.running,
+ failed: postprocess.failed,
+ completed: postprocess.completed,
+ }),
+ mono: false,
+ note: postprocess.running > 0 || postprocess.failed > 0,
+ })
}
if (attemptTabs.value.length === 0 && data.value.current_attempt) {
- parts.push(t('knowledgeStages.attempt', { n: data.value.current_attempt }))
+ out.push({
+ key: 'attempt',
+ label: t('knowledgeStages.stat.attempt'),
+ value: `#${data.value.current_attempt}`,
+ mono: true,
+ })
}
if (lastFetchedAt.value && isLive.value) {
let updated = formatRelativeTime(lastFetchedAt.value)
if (!lastFetchOk.value) {
updated += ` (${t('knowledgeStages.fetchFailedShort')})`
}
- parts.push(`${t('knowledgeStages.head.updated')} ${updated}`)
+ out.push({
+ key: 'updated',
+ label: t('knowledgeStages.head.updated'),
+ value: updated,
+ mono: false,
+ note: !lastFetchOk.value,
+ })
}
- return parts
+ return out
})
const primaryHeadTitle = computed(() => props.docTitle || t('knowledgeStages.title'))
@@ -1430,21 +1534,26 @@ const processConfigLines = computed<string[]>(() => {
<!-- ============== HEADER ============== -->
<div class="kp-head">
<div class="kp-head-toolbar">
- <h2 class="kp-head-doc-title" :title="primaryHeadTitle">{{ primaryHeadTitle }}</h2>
- <t-tag v-if="data && headerStatusText" size="small" :theme="headerStatusTheme" variant="light"
- class="kp-head-status-tag">
- {{ headerStatusText }}
- </t-tag>
- <span v-if="isLive" class="kp-live-badge" :title="t('knowledgeStages.liveTooltip')">
- <span class="kp-live-dot" />
- <span class="kp-live-text">{{ t('knowledgeStages.live') }}</span>
- </span>
+ <div class="kp-head-titles">
+ <div class="kp-head-overline">{{ t('knowledgeStages.title') }}</div>
+ <div class="kp-head-title-row">
+ <h2 class="kp-head-doc-title" :title="primaryHeadTitle">{{ primaryHeadTitle }}</h2>
+ <t-tag v-if="data && headerStatusText" size="small" :theme="headerStatusTheme" variant="light"
+ class="kp-head-status-tag">
+ {{ headerStatusText }}
+ </t-tag>
+ <span v-if="isLive" class="kp-live-badge" :title="t('knowledgeStages.liveTooltip')">
+ <span class="kp-live-dot" />
+ <span class="kp-live-text">{{ t('knowledgeStages.live') }}</span>
+ </span>
+ </div>
+ </div>
<div class="kp-head-actions">
<t-popup trigger="hover" placement="bottom-right" :overlay-style="{ maxWidth: '340px' }">
<button type="button" class="kp-icon-btn"
:title="t('knowledgeStages.processConfig.title')"
:aria-label="t('knowledgeStages.processConfig.title')">
- <t-icon name="info-circle" size="14px" />
+ <t-icon name="info-circle" size="16px" />
</button>
<template #content>
<div class="kp-proccfg-pop">
@@ -1460,7 +1569,7 @@ const processConfigLines = computed<string[]>(() => {
:title="isLive ? t('knowledgeStages.autoRefreshOn') : t('knowledgeStages.refresh')"
:aria-label="isLive ? t('knowledgeStages.autoRefreshOn') : t('knowledgeStages.refresh')"
@click="onManualRefresh">
- <t-icon name="refresh" size="14px" />
+ <t-icon name="refresh" size="16px" />
</button>
<t-popconfirm
v-if="canCancelParse"
@@ -1478,8 +1587,7 @@ const processConfigLines = computed<string[]>(() => {
<t-icon :name="cancelling ? 'loading' : 'close-circle'" size="15px" />
</button>
</t-popconfirm>
- <t-button v-if="data?.parse_status === 'failed'" size="small" theme="primary" variant="outline"
- @click="onRetry">
+ <t-button v-if="showToolbarRetry" size="small" theme="danger" variant="outline" @click="onRetry">
<t-icon name="refresh" size="14px" />
<span style="margin-left: 4px">{{ t('knowledgeStages.retry') }}</span>
</t-button>
@@ -1490,12 +1598,13 @@ const processConfigLines = computed<string[]>(() => {
</div>
</div>
- <p v-if="headMetaParts.length > 0" class="kp-head-meta">
- <template v-for="(part, idx) in headMetaParts" :key="idx">
- <span v-if="idx > 0" class="kp-head-meta-sep" aria-hidden="true">·</span>
- <span class="kp-head-meta-part">{{ part }}</span>
- </template>
- </p>
+ <div v-if="headStats.length > 0" class="kp-stat-strip">
+ <span v-for="stat in headStats" :key="stat.key" class="kp-stat">
+ <span class="kp-stat-label">{{ stat.label }}</span>
+ <span class="kp-stat-value"
+ :class="{ 'kp-stat-value-text': !stat.mono, 'kp-stat-note': stat.note }">{{ stat.value }}</span>
+ </span>
+ </div>
<div v-if="attemptTabs.length > 0" class="kp-attempts">
<button v-for="tab in attemptTabs" :key="tab.n" type="button" class="kp-attempt"
@@ -1507,18 +1616,24 @@ const processConfigLines = computed<string[]>(() => {
</div>
<div v-if="showLastError && data?.last_error" class="kp-last-error" role="alert">
- <div class="kp-last-error-bar" />
- <div class="kp-last-error-body">
- <div class="kp-last-error-row">
- <span class="kp-last-error-glyph">!</span>
- <span class="kp-last-error-title">{{ localizedErrorTitle(data.last_error.error_code) }}</span>
- <span v-if="data.last_error.error_code" class="kp-last-error-code kp-mono">{{ data.last_error.error_code
- }}</span>
- </div>
- <div class="kp-last-error-suggestion">{{ localizedErrorSuggestion(data.last_error.error_code) }}</div>
- <div v-if="data.last_error.error_message" class="kp-last-error-raw kp-mono">{{
- data.last_error.error_message }}
- </div>
+ <div class="kp-err-top">
+ <span class="kp-err-glyph" aria-hidden="true">!</span>
+ <span class="kp-err-where">{{ errorHeadline }}</span>
+ <span v-if="data.last_error.error_code" class="kp-err-code kp-mono">{{ data.last_error.error_code }}</span>
+ <button type="button" class="kp-err-copy" :title="t('knowledgeStages.copyError')"
+ :aria-label="t('knowledgeStages.copyError')" @click="copyValue(data.last_error)">
+ <t-icon name="copy" size="14px" />
+ </button>
+ </div>
+ <div v-if="data.last_error.error_message" class="kp-err-message">{{ data.last_error.error_message }}</div>
+ <div v-if="localizedErrorSuggestion(data.last_error.error_code)" class="kp-err-hint">
+ {{ localizedErrorSuggestion(data.last_error.error_code) }}
+ </div>
+ <div class="kp-err-actions">
+ <button type="button" class="kp-err-btn" @click="onRetry">
+ <t-icon name="refresh" size="14px" />
+ <span>{{ t('knowledgeStages.retry') }}</span>
+ </button>
</div>
</div>
</div>
@@ -1549,17 +1664,20 @@ const processConfigLines = computed<string[]>(() => {
</div>
<div ref="scrollRef" class="kp-scroll">
- <div class="kp-rows">
+ <div class="kp-rows" :class="{ 'kp-rows-gridless': !showRuler }"
+ :style="{ '--kp-grid-step': gridStepPct }">
<div v-for="row in flatRows" :key="row.key" class="kp-row" :data-span-key="row.key" :class="{
'kp-row-active': selectedSpanId === row.key,
'kp-row-root': row.isRoot,
'kp-row-stage': row.isStage,
'kp-row-span': !row.isRoot && !row.isStage,
'kp-row-expandable': row.hasChildren && !row.isRoot,
+ 'kp-row-inert': isNotRun(row.node),
}" :title="row.hasChildren && !row.isRoot ? t('knowledgeStages.rowSelectHint') : undefined"
@click="selectRow(row)">
<div class="kp-cell-name">
- <div class="kp-name-inner" :style="{ paddingLeft: row.depth * 16 + 'px' }">
+ <div class="kp-name-inner">
+ <span v-for="d in row.depth" :key="d" class="kp-name-guide" aria-hidden="true" />
<button v-if="row.hasChildren && !row.isRoot" type="button" class="kp-tree-toggle"
:aria-expanded="isRowExpanded(row.key)" :aria-label="treeToggleAriaLabel(row)"
@click="toggleTree(row, $event)">
@@ -1568,15 +1686,18 @@ const processConfigLines = computed<string[]>(() => {
<span v-else class="kp-tree-toggle-spacer" />
<span class="kp-status-dot"
:class="['kp-dot-' + row.node.status, { 'kp-dot-placeholder': isPlaceholder(row.node) }]" />
- <span class="kp-name-text"
+ <span class="kp-name-text" :title="rowLabel(row)"
:class="{ 'kp-name-root': row.isRoot, 'kp-name-mono': !row.isRoot && !row.isStage }">{{
rowLabel(row) }}</span>
- <span class="kp-name-kind">{{ rowKindLabel(row) }}</span>
+ <span v-if="rowKindLabel(row)" class="kp-name-kind">{{ rowKindLabel(row) }}</span>
</div>
</div>
- <div class="kp-cell-dur kp-mono">
- <template v-if="row.node.status === 'running'">
+ <div class="kp-cell-dur" :class="isNotRun(row.node) ? 'kp-dur-inert' : 'kp-mono'">
+ <template v-if="isNotRun(row.node)">
+ {{ t('knowledgeStages.notRun') }}
+ </template>
+ <template v-else-if="row.node.status === 'running'">
<span class="kp-running-time">{{ formatDuration(liveElapsedMs(row.node)) }}</span>
</template>
<template v-else>
@@ -1587,7 +1708,7 @@ const processConfigLines = computed<string[]>(() => {
<div class="kp-cell-bar">
<span v-if="nowMarkerPct !== null && row.isRoot" class="kp-now-marker"
:style="{ left: nowMarkerPct + '%' }" />
- <div v-if="isPlaceholder(row.node)" class="kp-bar kp-bar-placeholder" />
+ <div v-if="isPlaceholder(row.node) && !isNotRun(row.node)" class="kp-bar kp-bar-placeholder" />
<template v-else>
<!-- Wrapping outline: descendants extend past this
span's own end (e.g. async postprocess subspans
@@ -1883,7 +2004,7 @@ const processConfigLines = computed<string[]>(() => {
/* ============== HEADER ============== */
.kp-head {
flex: 0 0 auto;
- padding: 14px 20px 10px;
+ padding: 12px 20px;
border-bottom: 1px solid var(--td-component-stroke);
background: var(--td-bg-color-container);
}
@@ -1895,13 +2016,39 @@ const processConfigLines = computed<string[]>(() => {
min-width: 0;
}
-.kp-head-doc-title {
+.kp-head-titles {
flex: 1;
min-width: 0;
+}
+
+/* The panel's own name. It used to be the first crumb of the grey meta
+ sentence below the title, where it read as just another fact about the
+ document rather than as the label for the view you are looking at. */
+.kp-head-overline {
+ margin-bottom: 3px;
+ font-size: var(--app-text-2xs);
+ font-weight: 600;
+ letter-spacing: 0.08em;
+ line-height: 1.2;
+ color: var(--td-text-color-placeholder);
+}
+
+.kp-head-title-row {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ min-width: 0;
+}
+
+/* Natural width, so the status tag sits against the filename instead of
+ being pushed across the header to sit among the toolbar buttons. */
+.kp-head-doc-title {
+ flex: 0 1 auto;
+ min-width: 0;
margin: 0;
- font-size: var(--app-text-lg);
+ font-size: var(--app-text-xl);
font-weight: 600;
- line-height: 1.35;
+ line-height: 1.3;
color: var(--td-text-color-primary);
overflow: hidden;
text-overflow: ellipsis;
@@ -1963,29 +2110,53 @@ const processConfigLines = computed<string[]>(() => {
margin-left: auto;
}
-.kp-head-meta {
- margin: 8px 0 0;
+/* Label/value pairs in place of the old dot-joined run-on sentence.
+ Values are tabular mono so successive polls don't jiggle the row. */
+.kp-stat-strip {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: baseline;
+ gap: 4px 18px;
+ margin-top: 9px;
+}
+
+.kp-stat {
+ display: inline-flex;
+ align-items: baseline;
+ gap: 5px;
+ min-width: 0;
+}
+
+.kp-stat-label {
+ font-size: var(--app-text-xs);
+ color: var(--td-text-color-placeholder);
+ white-space: nowrap;
+}
+
+.kp-stat-value {
+ font-family: var(--app-font-family-mono);
font-size: var(--app-text-sm);
- line-height: 1.5;
+ font-weight: 600;
color: var(--td-text-color-secondary);
- word-break: break-word;
+ font-variant-numeric: tabular-nums;
}
-.kp-head-meta-sep {
- margin: 0 6px;
- color: var(--td-text-color-placeholder);
+/* Prose values (task counts, "just now") read badly in tabular mono. */
+.kp-stat-value-text {
+ font-family: var(--app-font-family);
+ font-weight: 500;
}
-.kp-head-meta-part {
- display: inline;
+.kp-stat-note {
+ color: var(--td-warning-color);
}
.kp-icon-btn {
display: inline-flex;
align-items: center;
justify-content: center;
- width: 26px;
- height: 26px;
+ width: 28px;
+ height: 28px;
border: none;
background: transparent;
color: var(--td-text-color-placeholder);
@@ -2119,6 +2290,12 @@ const processConfigLines = computed<string[]>(() => {
background: var(--td-bg-color-container);
}
+/* Sized by its rows once the detail panel is open — see .kp-detail. */
+.kp-body-with-detail {
+ flex: 0 0 auto;
+ max-height: 60%;
+}
+
.kp-scroll {
flex: 1 1 auto;
min-height: 0;
@@ -2142,10 +2319,10 @@ const processConfigLines = computed<string[]>(() => {
.kp-ruler {
flex: 0 0 auto;
display: grid;
- grid-template-columns: minmax(220px, 42%) 64px 1fr;
+ grid-template-columns: minmax(210px, 32%) 76px 1fr;
height: 24px;
align-items: end;
- padding: 12px 20px 6px;
+ padding: 10px 20px 6px;
background: var(--td-bg-color-container);
border-bottom: 1px dashed var(--td-component-stroke);
box-shadow: 0 4px 8px -6px rgba(0, 0, 0, 0.12);
@@ -2203,9 +2380,9 @@ const processConfigLines = computed<string[]>(() => {
.kp-row {
display: grid;
- grid-template-columns: minmax(220px, 42%) 64px 1fr;
+ grid-template-columns: minmax(210px, 32%) 76px 1fr;
align-items: center;
- height: 32px;
+ height: 34px;
cursor: pointer;
position: relative;
padding: 0 20px;
@@ -2236,16 +2413,18 @@ const processConfigLines = computed<string[]>(() => {
background: var(--td-brand-color);
}
+/* v1 painted three near-identical tints (root / stage / subspan) that
+ read as banding artifacts rather than as hierarchy, and fought the
+ hover tint on top of them. Depth is carried by the indent guides in
+ the name cell; background is reserved for hover and selection. */
.kp-row-root {
font-weight: 600;
+ border-bottom: 1px solid var(--td-component-stroke);
}
-.kp-row-stage:not(.kp-row-active) {
- background: color-mix(in srgb, var(--td-bg-color-secondarycontainer) 55%, transparent);
-}
-
-.kp-row-span:not(.kp-row-active):not(:hover) {
- background: color-mix(in srgb, var(--td-bg-color-container) 92%, var(--td-bg-color-secondarycontainer));
+/* Stages that never ran because an upstream stage failed. */
+.kp-row-inert {
+ opacity: 0.45;
}
.kp-row-expandable:hover .kp-tree-toggle {
@@ -2263,6 +2442,18 @@ const processConfigLines = computed<string[]>(() => {
align-items: center;
gap: 7px;
min-width: 0;
+ height: 100%;
+}
+
+/* One hairline per depth level, replacing v1's blind left padding. It
+ costs the same horizontal space but actually shows which parent a
+ nested subspan belongs to. */
+.kp-name-guide {
+ width: 1px;
+ align-self: stretch;
+ flex-shrink: 0;
+ margin-right: 8px;
+ background: var(--td-component-stroke);
}
.kp-tree-toggle {
@@ -2321,15 +2512,21 @@ const processConfigLines = computed<string[]>(() => {
font-size: var(--app-text-md);
}
+/* Only rendered for `generation` spans now. v1 pushed a ROOT / STAGE /
+ SPAN label to the far right of the name column with margin-left:auto,
+ which opened a wide empty gap in every single row. */
.kp-name-kind {
+ flex-shrink: 0;
+ margin-left: 6px;
+ padding: 1px 4px;
+ border-radius: var(--td-radius-small);
font-family: var(--app-font-family-mono);
font-size: var(--app-text-2xs);
+ font-weight: 600;
text-transform: uppercase;
- letter-spacing: 0.5px;
- color: var(--td-text-color-placeholder);
- margin-left: auto;
- padding-left: 8px;
- flex-shrink: 0;
+ letter-spacing: 0.04em;
+ color: var(--td-text-color-secondary);
+ background: var(--td-bg-color-component);
}
/* Duration cell */
@@ -2337,8 +2534,15 @@ const processConfigLines = computed<string[]>(() => {
font-size: var(--app-text-xs);
color: var(--td-text-color-secondary);
text-align: right;
- padding-right: 12px;
+ padding-right: 14px;
letter-spacing: 0.02em;
+ font-variant-numeric: tabular-nums;
+}
+
+/* "Never ran" beats an em dash the reader has to decode. */
+.kp-dur-inert {
+ font-family: var(--app-font-family);
+ color: var(--td-text-color-placeholder);
}
.kp-running-time {
@@ -2349,8 +2553,22 @@ const processConfigLines = computed<string[]>(() => {
/* Bar cell */
.kp-cell-bar {
position: relative;
- height: 32px;
+ height: 34px;
margin-right: 16px;
+ /* Gridlines on every ruler tick. An 8px bar floating in 600px of
+ white cannot be read against an axis that only exists at the top of
+ a scrolling list; --kp-grid-step is set from the axis step. */
+ background-image: repeating-linear-gradient(to right,
+ var(--td-component-stroke) 0 1px,
+ transparent 1px var(--kp-grid-step, 25%));
+ border-right: 1px solid var(--td-component-stroke);
+}
+
+/* No ruler (sub-50ms trace) means no axis for the gridlines to line up
+ with, so they would just be decoration. */
+.kp-rows-gridless .kp-cell-bar {
+ background-image: none;
+ border-right: none;
}
/* Vertical "now" cursor — animates left during polling so the user can
@@ -2382,7 +2600,7 @@ const processConfigLines = computed<string[]>(() => {
.kp-bar {
position: absolute;
- top: 12px;
+ top: 13px;
height: 8px;
border-radius: var(--td-radius-small);
background: var(--td-text-color-placeholder);
@@ -2645,36 +2863,32 @@ const processConfigLines = computed<string[]>(() => {
background: var(--td-text-color-placeholder);
}
-/* Last error block — pinned in the header so long trace trees don't bury it */
+/* ============== LAST ERROR ==============
+ Pinned in the header so long trace trees don't bury it.
+
+ v1 stacked this the wrong way up: the headline was the error code, a
+ solid red pill repeated that same code on the right, the generic
+ "check the logs" filler sat in the middle at body size, and the one
+ line that actually explains the failure — the backend's message —
+ was last, smallest and greyest. v2 leads with the message, states the
+ code once quietly, and puts the recovery action in the card. */
.kp-last-error {
- margin: 10px 0 0;
- display: flex;
+ margin-top: 12px;
+ padding: 12px 14px;
background: var(--td-error-color-light);
- border-radius: var(--td-radius-medium);
- overflow: hidden;
border: 1px solid var(--td-error-color-3);
+ border-left: 3px solid var(--td-error-color);
+ border-radius: var(--td-radius-medium);
}
-.kp-last-error-bar {
- width: 3px;
- background: var(--td-error-color);
- flex-shrink: 0;
-}
-
-.kp-last-error-body {
- flex: 1;
- padding: 10px 14px;
- min-width: 0;
-}
-
-.kp-last-error-row {
+.kp-err-top {
display: flex;
align-items: center;
gap: 8px;
- margin-bottom: 4px;
+ min-width: 0;
}
-.kp-last-error-glyph {
+.kp-err-glyph {
display: inline-flex;
align-items: center;
justify-content: center;
@@ -2685,38 +2899,111 @@ const processConfigLines = computed<string[]>(() => {
border-radius: 50%;
font-size: var(--app-text-xs);
font-weight: 700;
+ line-height: 1;
flex-shrink: 0;
}
-.kp-last-error-title {
- font-weight: 600;
+/* Says WHERE it broke ("文档解析阶段失败"), which the raw code never did.
+ Deliberately NOT --td-error-color: that tone lands around 3:1 against
+ the card's own error tint in both themes. The red bar, glyph and
+ border already say "error"; the words just have to be readable. */
+.kp-err-where {
font-size: var(--app-text-sm);
- color: var(--td-error-color);
+ font-weight: 600;
+ color: var(--td-text-color-primary);
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
}
-.kp-last-error-code {
- font-size: var(--app-text-2xs);
- background: var(--td-error-color);
- color: var(--td-text-color-anti);
- padding: 1px 6px;
- border-radius: var(--td-radius-small);
+.kp-err-code {
margin-left: auto;
+ flex-shrink: 0;
+ padding: 2px 6px;
+ border-radius: var(--td-radius-small);
+ font-size: var(--app-text-2xs);
+ color: var(--td-error-color-7);
+ background: color-mix(in srgb, var(--td-error-color) 12%, transparent);
+ white-space: nowrap;
}
-.kp-last-error-suggestion {
- font-size: var(--app-text-sm);
- color: var(--td-text-color-secondary);
- margin-bottom: 4px;
+.kp-err-copy {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 22px;
+ height: 22px;
+ flex-shrink: 0;
+ border: none;
+ background: transparent;
+ color: var(--td-error-color);
+ opacity: 0.7;
+ border-radius: var(--td-radius-default);
+ cursor: pointer;
+ transition: opacity var(--app-motion-fast) ease, background var(--app-motion-fast) ease;
}
-.kp-last-error-raw {
- font-size: var(--app-text-xs);
- color: var(--td-text-color-placeholder);
+.kp-err-copy:hover {
+ opacity: 1;
+ background: color-mix(in srgb, var(--td-error-color) 12%, transparent);
+}
+
+/* The actual diagnostic, promoted from 11px grey to the card's primary
+ line. Stays mono because it is verbatim backend output, and stays
+ selectable because people paste it into bug reports. */
+.kp-err-message {
+ margin-top: 7px;
+ font-family: var(--app-font-family-mono);
+ font-size: var(--app-text-md);
+ line-height: 1.5;
+ color: var(--td-text-color-primary);
white-space: pre-wrap;
word-break: break-word;
+ user-select: text;
+}
+
+.kp-err-hint {
+ margin-top: 5px;
+ font-size: var(--app-text-sm);
+ line-height: 1.5;
+ color: var(--td-text-color-secondary);
+}
+
+.kp-err-actions {
+ display: flex;
+ gap: 8px;
+ margin-top: 10px;
+}
+
+/* Recovery, not destruction — hence the outline rather than a solid
+ danger fill. It also replaces v1's brand-green outline button, which
+ sat in the toolbar glowing green against a red failure. */
+.kp-err-btn {
+ display: inline-flex;
+ align-items: center;
+ gap: 5px;
+ height: 28px;
+ padding: 0 12px;
+ border: 1px solid var(--td-error-color);
+ border-radius: var(--td-radius-default);
+ background: var(--td-bg-color-container);
+ color: var(--td-error-color-7);
+ font-size: var(--app-text-sm);
+ cursor: pointer;
+ transition: background var(--app-motion-fast) ease, color var(--app-motion-fast) ease;
}
-/* ============== DETAIL PANEL ============== */
+.kp-err-btn:hover {
+ background: var(--td-error-color);
+ color: var(--td-text-color-anti);
+}
+
+/* ============== DETAIL PANEL ==============
+ v1 gave the waterfall flex:1 and the detail a fixed 50% / 320px. On a
+ short trace that meant ~55% of the panel was blank whenever nothing
+ was selected, and rows got clipped mid-height as soon as something
+ was. Now the waterfall is content-sized (capped at 60% so a long
+ trace still leaves room) and the detail absorbs whatever is left. */
.kp-detail {
flex: 0 0 auto;
display: flex;
@@ -2725,12 +3012,28 @@ const processConfigLines = computed<string[]>(() => {
background: var(--td-bg-color-container);
height: 0;
overflow: hidden;
- transition: height 240ms cubic-bezier(0.2, 0.8, 0.2, 1);
}
+/* flex-basis 0 (not auto) so the detail claims the remaining space
+ instead of its own content height — otherwise a tall detail body
+ squeezes the waterfall back out of view. */
.kp-detail-open {
- height: 50%;
- min-height: 320px;
+ flex: 1 1 0;
+ height: auto;
+ min-height: 220px;
+ animation: kpDetailIn var(--app-motion-base) ease both;
+}
+
+@keyframes kpDetailIn {
+ from {
+ opacity: 0;
+ transform: translateY(6px);
+ }
+
+ to {
+ opacity: 1;
+ transform: none;
+ }
}
.kp-detail-head {
diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts
index c0ebdd421..9f6d5c1fb 100755
--- a/frontend/src/i18n/locales/en-US.ts
+++ b/frontend/src/i18n/locales/en-US.ts
@@ -892,6 +892,15 @@ export default {
},
attempt: 'Attempt {n}',
retry: 'Retry parsing',
+ notRun: 'Not run',
+ stageFailed: '{stage} failed',
+ copyError: 'Copy error details',
+ stat: {
+ duration: 'Duration',
+ attempt: 'Attempt',
+ tasks: 'Background tasks',
+ tasksValue: '{running} running · {failed} failed · {completed} done'
+ },
refresh: 'Refresh now',
copy: 'Copy',
copyDetails: 'Copy details',
@@ -911,12 +920,9 @@ export default {
minutesAgo: '{n}m ago',
noActivity: 'No parsing activity yet',
totalDuration: 'Total: {d}',
- total: 'Total {d}',
head: {
stagesDone: 'Main stages',
stagesProgress: 'Current stage',
- postprocessTasks: 'Postprocess: {running} running / {failed} failed / {completed} completed',
- completedWithActiveTrace: 'Processing completed, but {n} trace task(s) remain active',
attempt: 'Attempt',
updated: 'Updated'
},
diff --git a/frontend/src/i18n/locales/ja-JP.ts b/frontend/src/i18n/locales/ja-JP.ts
index 85424eaba..c5b3f6eea 100644
--- a/frontend/src/i18n/locales/ja-JP.ts
+++ b/frontend/src/i18n/locales/ja-JP.ts
@@ -892,6 +892,15 @@ export default {
},
attempt: '{n}回目の試行',
retry: '再解析',
+ notRun: '未実行',
+ stageFailed: '{stage}が失敗しました',
+ copyError: 'エラー情報をコピー',
+ stat: {
+ duration: '所要時間',
+ attempt: '試行',
+ tasks: 'バックグラウンドタスク',
+ tasksValue: '実行中 {running} · 失敗 {failed} · 完了 {completed}'
+ },
refresh: '今すぐ更新',
copy: 'コピー',
copyDetails: '詳細をコピー',
@@ -911,12 +920,9 @@ export default {
minutesAgo: '{n}分前',
noActivity: '解析の記録はまだありません',
totalDuration: '合計: {d}',
- total: '合計{d}',
head: {
stagesDone: '主要ステージ',
stagesProgress: '現在のステージ',
- postprocessTasks: '後処理: 実行中{running}件/失敗{failed}件/完了{completed}件',
- completedWithActiveTrace: '処理は完了しましたが、{n}件のトレースタスクがまだ実行中です',
attempt: '試行',
updated: '更新'
},
diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts
index 3d2c3f064..165c1f5a0 100755
--- a/frontend/src/i18n/locales/ko-KR.ts
+++ b/frontend/src/i18n/locales/ko-KR.ts
@@ -6576,6 +6576,15 @@ export default {
root: '지식 처리',
attempt: '{n}번째 시도',
retry: '다시 파싱',
+ notRun: '실행 안 됨',
+ stageFailed: '{stage} 단계 실패',
+ copyError: '오류 정보 복사',
+ stat: {
+ duration: '소요 시간',
+ attempt: '시도',
+ tasks: '백그라운드 작업',
+ tasksValue: '실행 중 {running} · 실패 {failed} · 완료 {completed}'
+ },
refresh: '지금 새로고침',
copy: '복사',
copyDetails: '세부정보 복사',
@@ -6595,7 +6604,6 @@ export default {
minutesAgo: '{n}분 전',
noActivity: '파싱 활동 없음',
totalDuration: '총 소요시간: {d}',
- total: '총 {d}',
errorCode: {
UNKNOWN_SUGGESTION: '자세한 내용은 애플리케이션 로그를 확인하세요.'
},
@@ -6650,8 +6658,6 @@ export default {
head: {
stagesDone: '주요 단계',
stagesProgress: '현재 단계',
- postprocessTasks: '후처리: 실행 중 {running} / 실패 {failed} / 완료 {completed}',
- completedWithActiveTrace: '처리는 완료되었지만 {n}개의 Trace 작업이 아직 활성 상태입니다',
attempt: '시도',
updated: '갱신'
},
diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts
index a758e4d59..55b9d1fe9 100755
--- a/frontend/src/i18n/locales/ru-RU.ts
+++ b/frontend/src/i18n/locales/ru-RU.ts
@@ -6576,6 +6576,15 @@ export default {
root: 'Обработка знаний',
attempt: 'Попытка {n}',
retry: 'Повторить парсинг',
+ notRun: 'Не выполнялся',
+ stageFailed: 'Этап «{stage}» завершился с ошибкой',
+ copyError: 'Скопировать детали ошибки',
+ stat: {
+ duration: 'Длительность',
+ attempt: 'Попытка',
+ tasks: 'Фоновые задачи',
+ tasksValue: 'выполняется {running} · с ошибкой {failed} · готово {completed}'
+ },
refresh: 'Refresh now',
copy: 'Copy',
copyDetails: 'Скопировать детали',
@@ -6595,7 +6604,6 @@ export default {
minutesAgo: '{n}m ago',
noActivity: 'Нет активности парсинга',
totalDuration: 'Всего: {d}',
- total: 'Всего {d}',
errorCode: {
UNKNOWN_SUGGESTION: 'Проверьте логи приложения для подробностей.'
},
@@ -6650,8 +6658,6 @@ export default {
head: {
stagesDone: 'Main stages',
stagesProgress: 'Current stage',
- postprocessTasks: 'Postprocess: {running} running / {failed} failed / {completed} completed',
- completedWithActiveTrace: 'Processing completed, but {n} trace task(s) remain active',
attempt: 'Attempt',
updated: 'Updated'
},
diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts
index 225744533..82c10bc6b 100755
--- a/frontend/src/i18n/locales/zh-CN.ts
+++ b/frontend/src/i18n/locales/zh-CN.ts
@@ -6578,6 +6578,15 @@ export default {
root: '知识处理',
attempt: '第 {n} 次尝试',
retry: '重新解析',
+ notRun: '未执行',
+ stageFailed: '{stage}阶段失败',
+ copyError: '复制错误信息',
+ stat: {
+ duration: '耗时',
+ attempt: '尝试',
+ tasks: '后台任务',
+ tasksValue: '运行中 {running} · 失败 {failed} · 已完成 {completed}'
+ },
refresh: '立即刷新',
copy: '复制',
copyDetails: '复制详情',
@@ -6597,7 +6606,6 @@ export default {
minutesAgo: '{n} 分钟前',
noActivity: '暂无解析记录',
totalDuration: '总耗时:{d}',
- total: '总耗时 {d}',
errorCode: {
UNKNOWN_SUGGESTION: '请查看应用日志获取详细信息。'
},
@@ -6652,8 +6660,6 @@ export default {
head: {
stagesDone: '主流程阶段',
stagesProgress: '当前阶段',
- postprocessTasks: '后台任务:运行中 {running} / 失败 {failed} / 已完成 {completed}',
- completedWithActiveTrace: '处理已完成,但仍有 {n} 个 Trace 任务处于活动状态',
attempt: '尝试',
updated: '更新于'
},
diff --git a/frontend/src/utils/traceAxis.test.ts b/frontend/src/utils/traceAxis.test.ts
new file mode 100644
index 000000000..a10ee8d68
--- /dev/null
+++ b/frontend/src/utils/traceAxis.test.ts
@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import {
+ axisGridStepPct,
+ buildAxisTicks,
+ computeTraceAxis,
+ formatAxisLabel,
+ niceAxisStep,
+} from './traceAxis.ts'
+
+test('rounds rough intervals onto the 1 / 2 / 2.5 / 5 ladder', () => {
+ assert.equal(niceAxisStep(98.8), 100)
+ assert.equal(niceAxisStep(1), 1)
+ assert.equal(niceAxisStep(1.4), 2)
+ assert.equal(niceAxisStep(2.4), 2.5)
+ assert.equal(niceAxisStep(4), 5)
+ assert.equal(niceAxisStep(7), 10)
+ assert.equal(niceAxisStep(6000), 10000)
+})
+
+test('degenerate durations produce an empty axis rather than NaN', () => {
+ for (const bad of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+ assert.deepEqual(computeTraceAxis(bad), { stepMs: 0, maxMs: 0 })
+ assert.deepEqual(buildAxisTicks(computeTraceAxis(bad)), [])
+ }
+ assert.equal(axisGridStepPct({ stepMs: 0, maxMs: 0 }), '25%')
+})
+
+test('the axis maximum is a whole number of steps and covers the total', () => {
+ for (const total of [494, 1, 51, 4200, 42300, 300000, 987654]) {
+ const { stepMs, maxMs } = computeTraceAxis(total)
+ assert.ok(maxMs >= total, `${total}: axis ${maxMs} clips the trace`)
+ assert.ok(
+ Math.abs(maxMs / stepMs - Math.round(maxMs / stepMs)) < 1e-9,
+ `${total}: axis ${maxMs} is not a whole number of ${stepMs} steps`,
+ )
+ }
+})
+
+test('the 494ms failure case rules to round hundreds', () => {
+ const axis = computeTraceAxis(494)
+ assert.deepEqual(axis, { stepMs: 100, maxMs: 500 })
+ assert.deepEqual(
+ buildAxisTicks(axis).map((t) => t.label),
+ ['0ms', '100ms', '200ms', '300ms', '400ms', '500ms'],
+ )
+ assert.deepEqual(
+ buildAxisTicks(axis).map((t) => t.left),
+ ['0%', '20%', '40%', '60%', '80%', '100%'],
+ )
+ assert.equal(axisGridStepPct(axis), '20%')
+})
+
+test('one unit for the whole ruler, picked from the axis maximum', () => {
+ assert.equal(formatAxisLabel(0, 500), '0ms')
+ assert.equal(formatAxisLabel(250, 500), '250ms')
+ // Seconds once the axis reaches 1s — including the zero tick, which
+ // would otherwise read "0ms" next to "10s".
+ assert.equal(formatAxisLabel(0, 50000), '0s')
+ assert.equal(formatAxisLabel(10000, 50000), '10s')
+ assert.equal(formatAxisLabel(2500, 12500), '2.5s')
+ // Minutes past a minute, with a carry so nothing reads "1m60s".
+ assert.equal(formatAxisLabel(0, 300000), '0m00s')
+ assert.equal(formatAxisLabel(75000, 300000), '1m15s')
+ assert.equal(formatAxisLabel(119999, 300000), '2m00s')
+})
+
+test('tick count stays bounded and labelled in one unit', () => {
+ for (const total of [494, 42300, 300000, 7_200_000]) {
+ const axis = computeTraceAxis(total)
+ const ticks = buildAxisTicks(axis)
+ assert.ok(ticks.length >= 2 && ticks.length <= 12, `${total}: ${ticks.length} ticks`)
+ const units = new Set(ticks.map((t) => t.label.replace(/[\d.]/g, '')))
+ assert.equal(units.size, 1, `${total}: mixed units ${[...units].join(' / ')}`)
+ }
+})
diff --git a/frontend/src/utils/traceAxis.ts b/frontend/src/utils/traceAxis.ts
new file mode 100644
index 000000000..6ad1d5d39
--- /dev/null
+++ b/frontend/src/utils/traceAxis.ts
@@ -0,0 +1,83 @@
+/**
+ * Time axis for the knowledge-processing waterfall.
+ *
+ * The timeline used to divide the raw trace duration into four equal
+ * parts, so a 494ms trace was ruled 0 / 124 / 247 / 371 / 494ms. Those
+ * are exact and useless: you cannot eyeball a bar against them, and the
+ * numbers change on every poll while a trace is live.
+ *
+ * Instead, round the tick interval to a 1 / 2 / 2.5 / 5 x 10^n step and
+ * extend the axis maximum up to a whole number of steps. Bars are then
+ * positioned against `maxMs` — never the raw total — so what the bars
+ * show and what the ruler claims always agree.
+ */
+
+export interface AxisTick {
+ left: string
+ label: string
+}
+
+export interface TraceAxis {
+ stepMs: number
+ maxMs: number
+}
+
+const DEFAULT_TARGET_INTERVALS = 5
+const MAX_TICKS = 12
+
+/** Round a rough interval up to the nearest 1 / 2 / 2.5 / 5 x 10^n. */
+export function niceAxisStep(roughStep: number): number {
+ if (!Number.isFinite(roughStep) || roughStep <= 0) return 1
+ const base = Math.pow(10, Math.floor(Math.log10(roughStep)))
+ const n = roughStep / base
+ const mult = n <= 1 ? 1 : n <= 2 ? 2 : n <= 2.5 ? 2.5 : n <= 5 ? 5 : 10
+ return mult * base
+}
+
+export function computeTraceAxis(
+ totalMs: number,
+ targetIntervals = DEFAULT_TARGET_INTERVALS,
+): TraceAxis {
+ if (!Number.isFinite(totalMs) || totalMs <= 0) return { stepMs: 0, maxMs: 0 }
+ const stepMs = niceAxisStep(totalMs / targetIntervals)
+ return { stepMs, maxMs: Math.max(stepMs, Math.ceil(totalMs / stepMs) * stepMs) }
+}
+
+/**
+ * One unit for the whole ruler, chosen from the axis maximum. Per-value
+ * formatting would print "0ms / 10.00s / 20.00s" on a single axis.
+ */
+export function formatAxisLabel(ms: number, maxMs: number): string {
+ if (maxMs >= 60000) {
+ let mins = Math.floor(ms / 60000)
+ let secs = Math.round((ms % 60000) / 1000)
+ // Carry, so 119_999ms reads 2m00s rather than 1m60s.
+ if (secs >= 60) {
+ mins += 1
+ secs -= 60
+ }
+ return `${mins}m${String(secs).padStart(2, '0')}s`
+ }
+ if (maxMs >= 1000) {
+ const secs = ms / 1000
+ return `${Number.isInteger(secs) ? secs : secs.toFixed(1)}s`
+ }
+ return `${Math.round(ms)}ms`
+}
+
+export function buildAxisTicks(axis: TraceAxis): AxisTick[] {
+ const { stepMs, maxMs } = axis
+ if (!stepMs || !maxMs) return []
+ const ticks: AxisTick[] = []
+ // `stepMs / 1000` absorbs float drift so the closing tick isn't dropped.
+ for (let v = 0; v <= maxMs + stepMs / 1000 && ticks.length < MAX_TICKS; v += stepMs) {
+ ticks.push({ left: `${(v / maxMs) * 100}%`, label: formatAxisLabel(v, maxMs) })
+ }
+ return ticks
+}
+
+/** Gap between gridlines, as a CSS percentage of the bar track. */
+export function axisGridStepPct(axis: TraceAxis): string {
+ if (!axis.maxMs || !axis.stepMs) return '25%'
+ return `${(axis.stepMs / axis.maxMs) * 100}%`
+}