1. 确定职责 → 这个 scene 只做什么？（一句话说清，超过一句就该拆）
2. 确定比例 + 类别 → 创建目录
3. 写 index.js（meta 全字段 → render → screenshots → lint）
4. 写 preview.html（自包含，file:// 可打开，不依赖服务器）
5. ⛔ 打开 preview.html 自己看 → 确认视觉正确
6. validate-scene.js 全绿
7. 测试 lint 拦截（故意传错参数）
8. 做一个 demo timeline 验证组合效果（和其他 scene 叠加）
9. 提交

src/nf-core/scenes/{ratio}/{category}/{sceneName}/
├── index.js        ← 必须：meta + render + screenshots + lint
└── preview.html    ← 必须：自包含，file:// 直接打开

export const meta = {
  // ─── 身份 ───
  id: "sceneName",              // 唯一 ID
  version: 1,                   // 改接口就 +1
  ratio: "9:16",                // 必填，禁止 null，和目录一致

  // ─── 分类与发现 ───
  category: "backgrounds",      // 小写
  label: "Scene Name",          // 英文名
  description: "中文描述，说清楚视觉效果和动画行为",
  tags: ["tag1", "tag2", "tag3"], // 至少 3 个搜索标签
  mood: ["calm", "energetic"],    // 情绪标签
  theme: ["tech", "business"],    // 适用主题

  // ─── 渲染 ───
  tech: "canvas2d",             // canvas2d | webgl | svg | dom | video | lottie
  duration_hint: 12,            // 建议时长（秒）
  loopable: true,               // 能否循环
  z_hint: "bottom",             // bottom | middle | top

  // ─── 主题预设（至少 3 个）───
  default_theme: "theme-name",
  themes: {
    "theme-name": { /* params 子集 */ },
    // 至少 3 个预设
  },

  // ─── 参数 ───
  params: {
    paramName: {
      type: "number",           // number | string | boolean | color | enum | array | object | file
      default: 270,             // 必须有（除非 required: true）
      range: [0, 360],          // number 必须有
      step: 1,                  // number 必须有
      label: "中文名",          // 必须有
      semantic: "english desc for AI", // 必须有，写清楚含义和取值范围的效果
      group: "color",           // content | color | style | animation | shape
    },
  },

  // ─── AI 指南（全字段必填）───
  ai: {
    when: "什么场景适合用，中文",
    how: "怎么在 timeline 里用，中文",
    example: { /* 完整 params 示例 */ },
    theme_guide: "每个 theme 的中文一句话说明",
    avoid: "什么情况不要用",
    pairs_with: ["scene-id-1", "scene-id-2"],
  },
};

export function render(t, params, vp) {
  const { width, height } = vp; // 画布尺寸（像素）
  // 返回 HTML 片段
}

export function screenshots() {
  return [
    { t: 0,   label: "开始" },
    { t: 2.5, label: "动画中" },
    { t: 4.5, label: "完成" },
  ];
}

export function lint(params, vp) {
  const errors = [];
  // 必须检查：
  // 1. 文字溢出安全区（viewport × 0.9）
  // 2. 数组长度合理
  // 3. required 参数非空
  // 4. 数值在 range 内
  // 5. theme 名字在 themes{} 里存在
  // 每个 error 格式："描述。Fix: 修复建议"
  return { ok: errors.length === 0, errors };
}

// timeline 里用法（3 种）：
// 1. 只选 theme（AI 安全选择）
{ "scene": "auroraGradient", "theme": "ocean-teal" }

// 2. theme + 微调
{ "scene": "auroraGradient", "theme": "ocean-teal", "params": { "intensity": 1.5 } }

// 3. 纯自定义
{ "scene": "auroraGradient", "params": { "hueA": 150 } }

# 验证单个（16 项检查）
node src/nf-core/scenes/validate-scene.js <scene-dir>

# 验证全部
for d in $(find src/nf-core/scenes -name "index.js" -exec dirname {} \;); do
  node src/nf-core/scenes/validate-scene.js "$d"
done

# 测试 lint 拦截
node src/nf-core/scenes/validate-scene.js <dir> --params '{"text":"超长文字..."}'

# 预览
open <scene-dir>/preview.html

# 做 demo timeline 测试组合
# 参考 output/demo-9x16.html