@mini-agent-harness/code-surfer-anything

pomb.us 风格的滚动驱动代码讲解轨道：每个阶段（stage）一块独立的 sticky 代码面板，段落滚动切换代码焦点，阶段交界处自然换页——任何长度的源码都不会把整个文件塞进一块面板。

基于 @code-surfer/standalone 的代码 diff 动画，外层补齐了分阶段 sticky 布局、课时（lesson）寻址与主题令牌。

安装

npm install @mini-agent-harness/code-surfer-anything

要求 React 18+（peerDependency，宿主自带，不会重复安装）。

使用

import { CodeSurferAnythingStaged, type CodeSurferAnythingLesson } from '@mini-agent-harness/code-surfer-anything'

interface Lesson extends CodeSurferAnythingLesson {
  title: string
  text: string
}

const stages = [
  {
    id: 'session',
    label: 'Session',
    lessons: [
      {
        id: 'session/log',
        label: '1.1',
        file: 'session.js',
        language: 'js',
        source: 'export class MiniSession { /* ... */ }',
        focus: { start: 1, end: 3 },
        title: '日志是唯一事实源',
        text: '模型看到的对话每次从日志投影……',
      },
    ],
  },
]

export function Walkthrough() {
  return (
    <CodeSurferAnythingStaged
      stages={stages}
      theme={{ accent: '#6799fe', panel: '#0f0f0f', codeHeight: '60vh' }}
      renderLesson={(lesson, state) => (
        <div data-active={state.active}>
          <h2>{lesson.title}</h2>
          <p>{lesson.text}</p>
        </div>
      )}
    />
  )
}

组件渲染整个滚动区（课时文案 + 代码面板），外层只需给一个容器宽度。

API

<CodeSurferAnythingStaged>（推荐）

| Prop | 类型 | 说明 | |---|---|---| | stages | readonly Stage[] | 阶段列表；每个阶段一块 sticky 面板与自己的源码切片 | | renderLesson | (lesson, state) => ReactNode | 课时讲解区渲染；state = { active, index, panelSticky } | | className | string? | 附加到滚动区根节点 | | theme | Theme? | 主题令牌（见下） |

数据形状

• Lesson：{ id, label, file, source, focus: { start, end }, language? }——focus 是该课时的源码行区间
• Stage：{ id, label, lessons }——共享一块面板的课时组

<CodeSurferAnything>（单面板退化形态）

传扁平 lessons 列表、单块面板的旧形态，等价于只有一个 stage。新代码建议直接用 Staged。

Theme 令牌

accent（强调色）· background（滚动区底色）· panel（代码面板底色）· text（讲解区正文）· muted（次要文字）· codeHeight（面板高度，默认 60vh）

行为约定

• 焦点切换走 CodeSurfer 的 diff tween；prefers-reduced-motion 时禁用弹性动画
• 面板钉住偏移单一来源（STICKY_TOP_PX），CSS 与 JS 不会漂移
• stages 为空数组渲染 null

测试

pnpm run test        # 帧选择与课时可见性
pnpm run typecheck