@lincyaw/viewer 0.0.0-stage → 1.0.0-rc.0

package/src/code.ts

@@ -0,0 +1,235 @@
+import { currentLocale, OPERATIONS, usePrefersReducedMotion, useService, useStartReport } from '@lincyaw/host'
+import type { Operations } from '@lincyaw/host'
+import { blockState, EXECUTOR, errorMessage, failedRun } from '@lincyaw/kernel'
+import type { CodeNode, IRBlock, RecordedRun, RunRequest, RunResult } from '@lincyaw/kernel'
+import { ShikiMagicMove } from '@shikijs/magic-move/vue'
+import '@shikijs/magic-move/style.css'
+import type { Element, ElementContent, Root } from 'hast'
+import { toHtml } from 'hast-util-to-html'
+import type { PropType, VNode, VNodeChild } from 'vue'
+import { computed, defineComponent, h, inject, onBeforeUnmount, onMounted, ref, shallowRef, watch } from 'vue'
+import { IN_COMPONENT, useSectionContext } from './context.ts'
+import { useDark } from './dark.ts'
+import { codeColumns, originParts } from './domain/index.ts'
+import type { OriginPart } from './domain/index.ts'
+import { highlighterFor, THEMES } from './highlight.ts'
+import { messages } from './i18n.ts'
+import { proseOnly, runOutput } from './outputs.ts'
+
+type Loaded = Awaited<ReturnType<typeof highlighterFor>>
+
+function useHighlighter(lang: () => string) {
+  const shiki = shallowRef<Loaded>()
+  const load = async () => {
+    const wanted = lang()
+    const loaded = await highlighterFor(wanted).catch(() => undefined)
+    if (wanted === lang()) shiki.value = loaded
+  }
+  onMounted(load)
+  watch(lang, load)
+  return shiki
+}
+
+function lineElements(tree: Root): Element[] {
+  const pre = tree.children.find((node): node is Element => node.type === 'element')
+  const code = pre?.children.find((node): node is Element => node.type === 'element' && node.tagName === 'code')
+  return (code?.children ?? []).filter((node: ElementContent): node is Element => node.type === 'element')
+}
+
+export const CodeView = defineComponent({
+  name: 'PmCodeView',
+  props: {
+    lang: { type: String, default: '' },
+    value: { type: String, required: true },
+    highlight: { type: Array as PropType<number[]>, default: undefined },
+  },
+  setup(props) {
+    const shiki = useHighlighter(() => props.lang)
+    const code = computed(() => props.value.replace(/\n$/, ''))
+    const lines = computed(() => new Set(props.highlight ?? []))
+    const tree = computed(() => shiki.value && shiki.value.highlighter.codeToHast(code.value, { lang: shiki.value.lang, themes: THEMES, defaultColor: false }))
+    const html = computed(() => {
+      if (!tree.value) return undefined
+      const marked = lines.value
+      lineElements(tree.value).forEach((line, i) => {
+        line.properties.class = marked.has(i + 1) ? 'line highlighted' : 'line'
+      })
+      return toHtml(tree.value)
+    })
+    const columns = computed(() => codeColumns(code.value))
+    return () => {
+      const attrs = {
+        'class': ['pm-code', { 'pm-code--highlight': lines.value.size > 0 }],
+        'style': { '--pm-code-columns': columns.value },
+        'data-lang': props.lang || undefined,
+      }
+      if (html.value) return h('div', { ...attrs, key: 'shiki', innerHTML: html.value })
+      const rows = code.value.split('\n').flatMap((text, i) => [h('span', { class: ['line', { highlighted: lines.value.has(i + 1) }] }, text), '\n'])
+      return h('div', { ...attrs, key: 'plain' }, [h('pre', { class: 'shiki' }, [h('code', rows.slice(0, -1))])])
+    }
+  },
+})
+
+const VariantView = defineComponent({
+  name: 'PmCodeVariant',
+  props: {
+    lang: { type: String, default: '' },
+    value: { type: String, required: true },
+  },
+  setup(props) {
+    const shiki = useHighlighter(() => props.lang)
+    const reduced = usePrefersReducedMotion()
+    const dark = useDark()
+    const code = computed(() => props.value.replace(/\n$/, ''))
+    return () => {
+      const loaded = shiki.value
+      if (!loaded || reduced.value) return h(CodeView, { lang: props.lang, value: props.value })
+      return h('div', { 'class': 'pm-code pm-code--magic-move', 'style': { '--pm-code-columns': codeColumns(code.value) }, 'data-lang': props.lang || undefined }, [
+        h(ShikiMagicMove, { highlighter: loaded.highlighter, lang: loaded.lang, theme: dark.value ? THEMES.dark : THEMES.light, code: code.value, options: { duration: 500 } }),
+      ])
+    }
+  },
+})
+
+function link(className: string, href: string | undefined, text: string, attrs: Record<string, unknown> = {}): VNode {
+  return href
+    ? h('a', { ...attrs, class: className, href, target: '_blank', rel: 'noopener' }, text)
+    : h('span', { ...attrs, class: className }, text)
+}
+
+function originPart(part: OriginPart, k: number): VNode {
+  return link(`pm-code-origin__${part.kind}`, part.href, part.text, {
+    'key': `${part.kind}:${k}`,
+    'title': part.title,
+    'data-active': part.active ? '' : undefined,
+    'data-status': part.status,
+    'data-drift': part.drift,
+  })
+}
+
+function originBar(node: CodeNode, shown: number | undefined): VNodeChild {
+  const bar = originParts(node, shown, currentLocale())
+  return bar ? h('div', { 'class': 'pm-code-origin', 'data-anchor': bar.anchor }, bar.parts.map(originPart)) : null
+}
+
+const replays = new Set<(data: Record<string, unknown>) => void>()
+const followed = new WeakSet<Operations>()
+
+function followRuns(operations: Operations): void {
+  if (followed.has(operations)) return
+  followed.add(operations)
+  operations.onReplay('run', { apply: data => replays.forEach(replay => replay(data)) })
+}
+
+export const CodeBlockView = defineComponent({
+  name: 'PmCodeBlock',
+  props: {
+    block: { type: Object as PropType<IRBlock>, required: true },
+    step: { type: Number, required: true },
+    expanded: Boolean,
+  },
+  setup(props) {
+    const owned = inject(IN_COMPONENT, false)
+    const executor = useService(EXECUTOR)
+    const operations = useService(OPERATIONS)
+    const section = useSectionContext()
+    const report = useStartReport()
+    const live = shallowRef<RunResult>()
+    const fallback = ref<string>()
+    const running = ref(false)
+    const mounted = ref(false)
+    let current: AbortController | undefined
+    const stop = () => {
+      current?.abort()
+      current = undefined
+      running.value = false
+    }
+    onMounted(() => {
+      mounted.value = true
+    })
+    onBeforeUnmount(stop)
+    const show = (result: RunResult | undefined) => {
+      const node = props.block.node as CodeNode
+      const recorded = result && !result.ok && result.exitCode === null && node.outputs?.length
+      fallback.value = recorded ? result.stderr.trim() || messages().code.unavailable : undefined
+      live.value = recorded ? undefined : result
+    }
+    const run = async () => {
+      const node = props.block.node as CodeNode
+      const router = executor.value
+      if (!node.run || !router || running.value) return
+      stop()
+      const controller = new AbortController()
+      current = controller
+      running.value = true
+      const { lang, args, stdin, timeoutMs, executor: named, session } = node.run
+      const request: RunRequest = { lang, code: node.value, args, stdin, timeoutMs, executor: named, session }
+      const started = Date.now()
+      let result: RunResult
+      try {
+        result = await router.run(request, controller.signal)
+      } catch (error) {
+        result = failedRun(router.id, messages().code.executorFailed(router.id, errorMessage(error)), Date.now() - started)
+      }
+      if (controller.signal.aborted) return
+      show(result)
+      current = undefined
+      running.value = false
+      const recording = node.outputs?.[0] as RecordedRun | undefined
+      operations.value?.report({ type: 'run', data: { section: section?.section.value.id, block: props.block.id, result: fallback.value && recording ? `freeze:${recording.cacheKey}` : 'live' } })
+    }
+    const reset = async () => {
+      const node = props.block.node as CodeNode
+      if (!node.run?.session) return
+      stop()
+      await executor.value?.endSession?.(node.run.session)
+      show(undefined)
+    }
+    const replay = (data: Record<string, unknown>) => {
+      if (data.block !== props.block.id || (data.section !== undefined && data.section !== section?.section.value.id)) return
+      stop()
+      show(undefined)
+    }
+    watch(operations, (ops) => {
+      if (ops) followRuns(ops)
+    }, { immediate: true })
+    onMounted(() => replays.add(replay))
+    onBeforeUnmount(() => replays.delete(replay))
+    watch(() => (props.block.node as CodeNode).value, () => {
+      stop()
+      show(undefined)
+    })
+
+    return () => {
+      const node = props.block.node as CodeNode
+      const state = blockState(props.block, props.step)
+      const variants = node.variants ?? []
+      const shown = variants.length && !props.expanded ? Math.min(state, variants.length - 1) : undefined
+      const listings = variants.length === 0
+        ? [h(CodeView, { lang: node.lang, value: node.value, highlight: props.expanded ? undefined : node.highlight?.[state] })]
+        : shown === undefined
+          ? variants.map(v => h('div', { key: v.label, class: 'pm-code-block__variant' }, [h('p', { class: 'pm-code-block__label' }, v.label), h(CodeView, { lang: node.lang, value: v.value })]))
+          : [h(VariantView, { key: 'variant', lang: node.lang, value: variants[shown]!.value })]
+      const echo = node.echo !== false
+      const runnable = !owned && echo && node.run && node.run.when !== 'compile'
+      const t = messages().code
+      const available = mounted.value && executor.value
+      const controls = runnable
+        ? h('div', { class: 'pm-code-block__run' }, [
+            h('button', { type: 'button', disabled: running.value || !available, onClick: run }, running.value ? t.running : live.value ? t.rerun : t.run),
+            node.run!.session ? h('button', { 'type': 'button', 'class': 'pm-code-block__reset', 'disabled': !available, 'data-session': node.run!.session, 'onClick': reset }, t.resetSession) : null,
+            mounted.value && !executor.value && report.value ? h('span', { class: 'pm-code-block__hint' }, t.unavailable) : null,
+          ])
+        : null
+      const runs = owned ? [] : live.value ? [live.value] : node.outputs ?? []
+      const prose = !echo && !live.value && runs.length > 0 && runs.every(proseOnly)
+      const prefix = section?.section.value.id ?? props.block.id
+      const outputs = runs.length
+        ? h('div', { 'class': ['pm-outputs', { 'pm-outputs--prose': prose }], 'data-source': live.value ? 'live' : 'recorded' }, runs.map((r, i) => runOutput(r, (r as RecordedRun).cacheKey || i, prefix, { prose, note: fallback.value })))
+        : null
+      return h('div', { 'class': ['pm-code-block', { 'pm-code-block--output-only': !echo }], 'data-state': props.expanded ? undefined : state, 'data-run': runnable ? node.run!.when : undefined, 'data-session': node.run?.session }, echo
+        ? [originBar(node, shown), ...listings, controls, outputs]
+        : [outputs])
+    }
+  },
+})

package/src/context.ts

@@ -0,0 +1,16 @@
+import type { IRSection } from '@lincyaw/kernel'
+import type { InjectionKey, Ref } from 'vue'
+import { inject } from 'vue'
+
+export interface SectionContext {
+  section: Readonly<Ref<IRSection>>
+  step: Readonly<Ref<number>>
+  view: Readonly<Ref<string>>
+}
+
+export const SECTION_CONTEXT: InjectionKey<SectionContext> = Symbol('presmium.viewer.section')
+export const IN_COMPONENT: InjectionKey<boolean> = Symbol('presmium.viewer.inComponent')
+
+export function useSectionContext(): SectionContext | undefined {
+  return inject(SECTION_CONTEXT, undefined)
+}

package/src/dark.ts

@@ -0,0 +1,5 @@
+import { useTheme } from '@lincyaw/host'
+
+export function useDark() {
+  return useTheme().dark
+}

package/src/domain/clicks.ts

@@ -0,0 +1,38 @@
+import { stepStateAt } from '@lincyaw/kernel/contracts'
+
+export interface ClickSpec {
+  kind: 'click' | 'after'
+  at?: unknown
+  hide?: boolean
+}
+
+export interface ClickRange {
+  from: number
+  to?: number
+  hide: boolean
+}
+
+function isRelative(at: unknown): at is string {
+  return typeof at === 'string' && /^[+-]\d+$/.test(at.trim())
+}
+
+export function resolveClicks(specs: readonly ClickSpec[]): ClickRange[] {
+  let last = 0
+  const position = (at: unknown, base: number): number => {
+    if (isRelative(at)) return base + Number(at.trim())
+    const value = Number(at)
+    return Number.isFinite(value) ? value : base + 1
+  }
+  return specs.map((spec) => {
+    const at = spec.kind === 'after' ? '+0' : spec.at ?? '+1'
+    const [enter, leave] = Array.isArray(at) ? at : [at]
+    const from = position(enter, last)
+    if (isRelative(enter) || !Number.isFinite(Number(enter))) last = from
+    const to = leave === undefined ? undefined : position(leave, from)
+    return { from, to, hide: spec.hide ?? false }
+  })
+}
+
+export function clickVisible(range: ClickRange, step: number): boolean {
+  return stepStateAt(range, step).active !== range.hide
+}

package/src/domain/follow.ts

@@ -0,0 +1,32 @@
+import { stepTrail, trailStep } from '@lincyaw/kernel'
+import type { IRSection, StepKeys } from '@lincyaw/kernel'
+
+export { stepKeys, stepTrail, trailStep } from '@lincyaw/kernel'
+export type { StepKeys } from '@lincyaw/kernel'
+
+export interface FollowAnchor {
+  section?: string
+  trail?: string[]
+  back?: string
+}
+
+const LEARNERS = 'student'
+
+export function backSection(sections: readonly Pick<IRSection, 'id' | 'audience'>[], id: string): string | undefined {
+  const at = sections.findIndex(section => section.id === id)
+  const audience = sections[at]?.audience
+  if (!audience?.length) return undefined
+  const learners = !audience.includes(LEARNERS)
+  return sections.slice(0, at).findLast(section => !section.audience?.length || (learners && section.audience.includes(LEARNERS)))?.id
+}
+
+export function followedPlace(position: FollowAnchor & { step: number }, keysOf: (id: string) => StepKeys | undefined): { section: string, step: number } | undefined {
+  const { section, trail, back, step } = position
+  const keys = section === undefined ? undefined : keysOf(section)
+  if (keys) {
+    const other = trail !== undefined && stepTrail(keys, step).join('\n') !== trail.join('\n')
+    return { section: section!, step: other ? trailStep(keys, trail) : step }
+  }
+  const before = back === undefined ? undefined : keysOf(back)
+  return before && { section: back!, step: before.length - 1 }
+}

package/src/domain/index.ts

@@ -0,0 +1,21 @@
+export { clickVisible, resolveClicks } from './clicks.ts'
+export type { ClickRange, ClickSpec } from './clicks.ts'
+export { backSection, followedPlace, stepKeys, stepTrail, trailStep } from './follow.ts'
+export type { FollowAnchor, StepKeys } from './follow.ts'
+export { applyUpdate, diffDocuments, sectionDiagnostics } from './live.ts'
+export type { LiveUpdate } from './live.ts'
+export { VIEWER_MESSAGES } from './messages.ts'
+export type { Messages } from './messages.ts'
+export { ORIGIN_MESSAGES, originParts, outputNotes } from './origin.ts'
+export type { OriginBar, OriginMessages, OriginPart } from './origin.ts'
+export {
+  clampPosition,
+  FINAL_STEP,
+  itemVisible,
+  keepPosition,
+  nextPosition,
+  prevPosition,
+  stepAtLine,
+} from './steps.ts'
+export type { Position } from './steps.ts'
+export { codeColumns, footnoteSections } from './text.ts'

package/src/domain/live.ts

@@ -0,0 +1,43 @@
+import type { Finding, IRDocument, IRSection } from '@lincyaw/kernel'
+
+export interface LiveUpdate {
+  order: string[]
+  sections: IRSection[]
+  diagnostics: Finding[]
+  meta?: IRDocument['meta']
+  config?: IRDocument['config']
+}
+
+function key(value: unknown): string {
+  return JSON.stringify(value)
+}
+
+export function diffDocuments(prev: IRDocument, next: IRDocument): LiveUpdate | undefined {
+  const old = new Map(prev.sections.map(s => [s.id, key(s)]))
+  const sections = next.sections.filter(s => old.get(s.id) !== key(s))
+  const order = next.sections.map(s => s.id)
+  const update: LiveUpdate = { order, sections, diagnostics: next.diagnostics }
+  if (key(prev.meta) !== key(next.meta)) update.meta = next.meta
+  if (key(prev.config) !== key(next.config)) update.config = next.config
+  const reordered = key(order) !== key(prev.sections.map(s => s.id))
+  const changed = sections.length > 0 || reordered || update.meta || update.config || key(prev.diagnostics) !== key(next.diagnostics)
+  return changed ? update : undefined
+}
+
+export function applyUpdate(doc: IRDocument, update: LiveUpdate): IRDocument {
+  const known = new Map(doc.sections.map(s => [s.id, s]))
+  for (const section of update.sections) known.set(section.id, section)
+  return {
+    ...doc,
+    meta: update.meta ?? doc.meta,
+    config: update.config ?? doc.config,
+    sections: update.order.flatMap(id => known.get(id) ?? []),
+    diagnostics: update.diagnostics,
+  }
+}
+
+export function sectionDiagnostics(section: IRSection, diagnostics: readonly Finding[]): Finding[] {
+  const ranges = [section.source, ...section.blocks.map(b => b.source)]
+  return diagnostics.filter(({ source }) => source?.line !== undefined && ranges.some(range =>
+    range.file === source.file && source.line! >= range.line && source.line! <= (range.endLine ?? range.line)))
+}

package/src/domain/messages.ts

@@ -0,0 +1,115 @@
+import type { Locale } from '@lincyaw/kernel/contracts'
+
+const zhStep = (step: number, steps: number) => `第 ${step + 1} 步，共 ${steps + 1} 步`
+
+const zh = {
+  views: { document: '文档', scrolly: '滚动叙事', present: '放映', presenter: '演讲者' },
+  present: {
+    region: '放映',
+    counter: (index: number, total: number, step: number, steps: number) => `${index} / ${total}${steps > 0 ? ` · ${zhStep(step, steps)}` : ''}`,
+    prev: '上一步',
+    next: '下一步',
+    overview: '总览',
+    presenter: '演讲者窗口',
+    fullscreen: '全屏',
+    exit: '退出放映',
+  },
+  presenter: {
+    step: (step: number, steps: number) => (steps > 0 ? zhStep(step, steps) : ''),
+    timer: '计时',
+    restart: '重新计时',
+    notes: '讲解',
+    noNotes: '本节没有讲解',
+    upcoming: '下一步',
+    end: '已到结尾',
+    nextSection: (title: string) => `下一节：${title}`,
+    nextStep: (step: number) => `第 ${step + 1} 步`,
+  },
+  section: {
+    anchor: (title: string) => `链接到“${title}”`,
+    openSource: '在编辑器中打开源码',
+    sourceTitle: (where: string) => `${where}（Alt+单击任一块，打开该块的源码）`,
+  },
+  code: {
+    executorFailed: (id: string, message: string) => `执行器 ${id} 出错：${message}`,
+    run: '运行',
+    rerun: '重跑',
+    running: '运行中…',
+    unavailable: '执行服务不可用',
+    resetSession: '重置会话',
+  },
+  markdown: {
+    admonitions: {
+      note: '注意',
+      tip: '提示',
+      hint: '提示',
+      important: '重要',
+      warning: '警告',
+      caution: '小心',
+      attention: '注意',
+      danger: '危险',
+      error: '错误',
+      seealso: '另请参阅',
+    } as Record<string, string>,
+    footnote: (label: string) => `脚注 ${label}`,
+  },
+  missingComponent: (name: string) => `未注册的组件 ${name}`,
+}
+
+export type Messages = typeof zh
+
+const en: Messages = {
+  views: { document: 'Document', scrolly: 'Scrollytelling', present: 'Present', presenter: 'Presenter' },
+  present: {
+    region: 'Presentation',
+    counter: (index, total, step, steps) => `${index} / ${total}${steps > 0 ? ` · step ${step + 1} of ${steps + 1}` : ''}`,
+    prev: 'Previous',
+    next: 'Next',
+    overview: 'Overview',
+    presenter: 'Presenter window',
+    fullscreen: 'Full screen',
+    exit: 'Exit presentation',
+  },
+  presenter: {
+    step: (step, steps) => (steps > 0 ? `Step ${step + 1} of ${steps + 1}` : ''),
+    timer: 'Timer',
+    restart: 'Restart timer',
+    notes: 'Narration',
+    noNotes: 'No narration in this section',
+    upcoming: 'Next',
+    end: 'End of the document',
+    nextSection: title => `Next section: ${title}`,
+    nextStep: step => `Step ${step + 1}`,
+  },
+  section: {
+    anchor: title => `Link to "${title}"`,
+    openSource: 'Open the source in the editor',
+    sourceTitle: where => `${where} (Alt+click a block to open its source)`,
+  },
+  code: {
+    executorFailed: (id, message) => `Executor ${id} failed: ${message}`,
+    run: 'Run',
+    rerun: 'Run again',
+    running: 'Running…',
+    unavailable: 'Execution service unavailable',
+    resetSession: 'Reset session',
+  },
+  markdown: {
+    admonitions: {
+      note: 'Note',
+      tip: 'Tip',
+      hint: 'Hint',
+      important: 'Important',
+      warning: 'Warning',
+      caution: 'Caution',
+      attention: 'Attention',
+      danger: 'Danger',
+      error: 'Error',
+      seealso: 'See also',
+    },
+    footnote: label => `Footnote ${label}`,
+  },
+  missingComponent: name => `Unregistered component ${name}`,
+}
+
+export const VIEWER_MESSAGES: Record<Locale, Messages> = { 'zh-CN': zh, 'en': en }

package/src/domain/origin.ts

@@ -0,0 +1,93 @@
+import type { CodeNode, ResolutionStatus, RunResult } from '@lincyaw/kernel'
+import type { Locale } from '@lincyaw/kernel/contracts'
+
+const zh = {
+  workingTree: '工作区',
+  status: { moved: '已移动', fuzzy: '待确认', lost: '已失效' } as Partial<Record<ResolutionStatus, string>>,
+  statusTitle: {
+    moved: '引用的代码在文件中移动了位置，显示的是移动后的代码',
+    fuzzy: '引用的代码有改动，找到的位置有待确认；运行 presmium check 查看',
+    lost: '找不到引用的代码；运行 presmium check 查看',
+  } as Partial<Record<ResolutionStatus, string>>,
+  drifted: '已漂移',
+  driftedTitle: '工作区中的代码已改变，运行 presmium check 查看差异',
+  synced: '已锁定',
+  syncedTitle: '锁定的代码与工作区一致',
+  openFile: (file: string) => `在仓库中打开 ${file}`,
+  timedOut: '超时',
+  exitCode: (code: number) => `退出码 ${code}`,
+  recorded: '预录输出',
+}
+
+export type OriginMessages = typeof zh
+
+const en: OriginMessages = {
+  workingTree: 'working tree',
+  status: { moved: 'Moved', fuzzy: 'Unconfirmed', lost: 'Lost' },
+  statusTitle: {
+    moved: 'The referenced code moved in its file; this is the code where it is now',
+    fuzzy: 'The referenced code changed and the place found is uncertain; run presmium check to see it',
+    lost: 'The referenced code is no longer found; run presmium check to see why',
+  },
+  drifted: 'Drifted',
+  driftedTitle: 'The code changed in the working tree; run presmium check to see the difference',
+  synced: 'Pinned',
+  syncedTitle: 'The pinned code matches the working tree',
+  openFile: file => `Open ${file} in the repository`,
+  timedOut: 'Timed out',
+  exitCode: code => `Exit code ${code}`,
+  recorded: 'Recorded output',
+}
+
+export const ORIGIN_MESSAGES: Record<Locale, OriginMessages> = { 'zh-CN': zh, 'en': en }
+
+export interface OriginPart {
+  kind: 'file' | 'variant' | 'commit' | 'badge'
+  text: string
+  href?: string
+  title?: string
+  active?: boolean
+  status?: ResolutionStatus
+  drift?: 'synced' | 'drifted'
+}
+
+export interface OriginBar {
+  anchor?: string
+  parts: OriginPart[]
+}
+
+function lines(start: number, end = start): string {
+  return end > start ? `${start}-${end}` : `${start}`
+}
+
+export function originParts(node: CodeNode, shown: number | undefined, locale: Locale): OriginBar | undefined {
+  const t = ORIGIN_MESSAGES[locale]
+  const { origin } = node
+  if (!origin) return node.title ? { parts: [{ kind: 'file', text: node.title }] } : undefined
+  const variants = node.variants ?? []
+  const version = shown === undefined ? undefined : variants[shown]
+  const href = version ? version.permalink : origin.permalink
+  const [start, end] = version?.startLine !== undefined ? [version.startLine, version.endLine] : [origin.startLine, origin.endLine]
+  const parts: OriginPart[] = [{ kind: 'file', text: `${node.title ?? origin.file}:${lines(start, end)}`, href, title: href ? t.openFile(origin.file) : origin.anchor }]
+  if (variants.length) {
+    variants.forEach((variant, k) => parts.push({ kind: 'variant', text: variant.label, href: variant.permalink, active: k === shown }))
+  } else {
+    parts.push({ kind: 'commit', text: origin.pin ? `@ ${origin.pin.slice(0, 7)}` : t.workingTree, title: origin.pin })
+  }
+  const status = t.status[origin.status]
+  if (status) parts.push({ kind: 'badge', text: status, title: t.statusTitle[origin.status], status: origin.status })
+  else if (origin.pin && !variants.length && origin.drift) {
+    const drifted = origin.drift === 'drifted'
+    parts.push({ kind: 'badge', text: drifted ? t.drifted : t.synced, title: drifted ? t.driftedTitle : t.syncedTitle, drift: origin.drift })
+  }
+  return { anchor: origin.anchor, parts }
+}
+
+export function outputNotes(run: RunResult, locale: Locale): string[] {
+  const t = ORIGIN_MESSAGES[locale]
+  return [
+    run.timedOut ? t.timedOut : '',
+    run.exitCode !== null && run.exitCode !== 0 ? t.exitCode(run.exitCode) : '',
+    run.source === 'recorded' ? t.recorded : '',
+  ].filter(Boolean)
+}

package/src/domain/steps.ts

@@ -0,0 +1,45 @@
+import type { IRBlock, IRDocument } from '@lincyaw/kernel'
+
+export const FINAL_STEP = Number.POSITIVE_INFINITY
+
+export interface Position {
+  section: string
+  step: number
+}
+
+export function itemVisible(block: IRBlock, item: number, step: number): boolean {
+  return step >= block.at + item
+}
+
+export function stepAtLine(markers: readonly { step: number, top: number }[], line: number): number {
+  return markers.reduce((step, marker) => (marker.top <= line ? Math.max(step, marker.step) : step), 0)
+}
+
+export function clampPosition(doc: IRDocument, position: Position): Position {
+  const section = doc.sections.find(s => s.id === position.section) ?? doc.sections[0]
+  if (!section) return position
+  const step = Number.isFinite(position.step) ? Math.min(Math.max(Math.round(position.step), 0), section.steps) : section.steps
+  return { section: section.id, step }
+}
+
+export function keepPosition(prev: IRDocument, next: IRDocument, position: Position): Position {
+  if (next.sections.some(s => s.id === position.section) || next.sections.length === 0) return clampPosition(next, position)
+  const at = prev.sections.findIndex(s => s.id === position.section)
+  const section = next.sections[Math.min(Math.max(at, 0), next.sections.length - 1)]!
+  return clampPosition(next, { section: section.id, step: position.step })
+}
+
+export function nextPosition(doc: IRDocument, position: Position): Position | undefined {
+  const i = doc.sections.findIndex(s => s.id === position.section)
+  const section = doc.sections[i]
+  if (section && position.step < section.steps) return { section: section.id, step: position.step + 1 }
+  const next = doc.sections[i + 1]
+  return next ? { section: next.id, step: 0 } : undefined
+}
+
+export function prevPosition(doc: IRDocument, position: Position): Position | undefined {
+  const i = doc.sections.findIndex(s => s.id === position.section)
+  if (i >= 0 && position.step > 0) return { section: position.section, step: position.step - 1 }
+  const prev = doc.sections[i - 1]
+  return prev ? { section: prev.id, step: prev.steps } : undefined
+}