dsh-drawai 0.3.4 → 0.4.0

package/lib/motion/shotcraft/upstream/assets/scripts/smoke-render-demos.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""smoke-render-demos.py — demo 渲染冒烟测试。
+
+堵住"能编译不能运行"的漏洞：现有 CI 只做 tsc 编译，不验证 demo 能否
+真的渲染。本脚本扫描所有带时长导出（`_DURATION` / `_DUR`）的 demo，
+自动生成一个临时 Root 注册全部，然后逐个渲染首帧，断言输出文件非空、
+渲染不崩。
+
+用法（从仓库根）：
+    python3 assets/scripts/smoke-render-demos.py [--subset a,b,c] [--list]
+
+前置条件：
+    - template/ 已 `npm install`（remotion 4.0.484）
+    - demos/ 用到的 @remotion/motion-blur 已装到 template（CI 里临时装）
+    - 需要纹理的 demo：demos/_textures/ 的文件已复制到
+      template/public/textures/live/（脚本会自动复制缺失的）
+    - 需要素材 mp4 的 demo（如 clipcard-looping）：跳过并报告，不失败
+
+退出码：全通过 0；任一 demo 渲染失败 1（列出失败清单）。
+"""
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+TEMPLATE = ROOT / 'template'
+TEMPLATE_SRC = TEMPLATE / 'src'
+TEXTURES_SRC = ROOT / 'demos' / '_textures'
+TEXTURES_DST = TEMPLATE / 'public' / 'textures' / 'live'
+DUR_PAT = re.compile(r'export const (\w+_DURATION|\w+_DUR)\s*=')
+
+# demo 需要真实 mp4 素材、无法自动生成的（跳过，脚本只报告）
+MATERIAL_REQUIRED = {'ClipCardLooping'}
+
+
+def find_demos():
+    """返回 [(路径, 时长导出名, 组件名)], 按路径排序。"""
+    out = []
+    for f in sorted((ROOT / 'demos').rglob('*.tsx')):
+        # 下架镜头只为工作台旧工程保留，不重新成为当前镜头库的样片。
+        if '_legacy' in f.relative_to(ROOT / 'demos').parts:
+            continue
+        src = f.read_text(encoding='utf-8')
+        m = DUR_PAT.search(src)
+        if not m:
+            continue
+        durname = m.group(1)
+        stem = f.stem
+        # 组件导出必须真实存在（`export const <stem>` 且是组件而非常量）。
+        # 正则精确匹配，避免文件名出现在注释/字符串里造成的误判。
+        if not re.search(rf'export const {re.escape(stem)}\s*:\s*React\.FC\s*=', src):
+            continue
+        out.append((f, durname, stem))
+    return out
+
+
+def write_smoke_root(demos):
+    """生成 template/src/smoke-root.tsx 注册所有 demo。"""
+    lines = ["import { Composition, registerRoot } from 'remotion';"]
+    regs = []
+    for f, durname, stem in demos:
+        rel = os.path.relpath(f, TEMPLATE_SRC).replace('.tsx', '')
+        lines.append(f"import {{ {stem}, {durname} }} from '{rel}';")
+        regs.append(
+            f'  <Composition id="{stem}" component={{{stem}}} '
+            f'durationInFrames={{{durname}}} fps={{30}} width={{1920}} '
+            f'height={{1080}} />'
+        )
+    lines.append('export const Root: React.FC = () => (<>')
+    lines += regs
+    lines.append('</>);')
+    lines.append('registerRoot(Root);')
+    (TEMPLATE_SRC / 'smoke-root.tsx').write_text('\n'.join(lines) + '\n', encoding='utf-8')
+
+
+def ensure_textures():
+    """把 demos/_textures 的图片纹理复制到 template/public/textures/live。
+    只复制图片（.png/.jpg/.webp），跳过 layout.json 等数据文件——它们是
+    import 进 TS 的，不是运行时纹理。"""
+    if not TEXTURES_SRC.exists():
+        return 0
+    os.makedirs(TEXTURES_DST, exist_ok=True)
+    IMG_EXT = {'.png', '.jpg', '.jpeg', '.webp'}
+    copied = 0
+    for f in TEXTURES_SRC.iterdir():
+        if f.is_file() and f.suffix.lower() in IMG_EXT and not (TEXTURES_DST / f.name).exists():
+            shutil.copy2(f, TEXTURES_DST / f.name)
+            copied += 1
+    return copied
+
+
+def render_one(stem, out_dir):
+    """渲染单个 demo 首帧, 返回 (ok, 输出路径或错误信息)。"""
+    out = out_dir / f'{stem}.png'
+    r = subprocess.run(
+        ['npx', 'remotion', 'still', 'src/smoke-root.tsx', stem,
+         '--frame=0', str(out), '--log=error'],
+        cwd=TEMPLATE,
+        capture_output=True,
+        text=True,
+    )
+    if r.returncode != 0:
+        return False, r.stderr[-400:]
+    if not out.exists() or out.stat().st_size == 0:
+        return False, 'rendered but empty output'
+    return True, None
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument('--subset', help='逗号分隔的组件名, 只渲染这些')
+    ap.add_argument('--list', action='store_true', help='只列出可渲染 demo')
+    args = ap.parse_args()
+
+    demos = find_demos()
+    if args.list:
+        for _, _, stem in demos:
+            print(stem)
+        return 0
+
+    if args.subset:
+        wanted = set(args.subset.split(','))
+        available = {s for _, _, s in demos}
+        unknown = wanted - available
+        if unknown:
+            print(f'error: subset 含未找到的 demo: {sorted(unknown)}')
+            return 1
+        demos = [(f, d, s) for f, d, s in demos if s in wanted]
+
+    # 过滤需要素材的 demo
+    skip = [(f, d, s) for f, d, s in demos if s in MATERIAL_REQUIRED]
+    run = [(f, d, s) for f, d, s in demos if s not in MATERIAL_REQUIRED]
+
+    print(f'扫描到 {len(demos)} 个带时长导出的 demo; '
+          f'跳过(需素材) {len(skip)}; 将渲染 {len(run)} 个')
+    if skip:
+        print(f'  跳过: {", ".join(s for _, _, s in skip)}')
+
+    write_smoke_root(run)
+    ensure_textures()
+
+    with tempfile.TemporaryDirectory() as tmp:
+        out_dir = Path(tmp)
+        failed = []
+        for f, durname, stem in run:
+            ok, err = render_one(stem, out_dir)
+            if ok:
+                print(f'  ✓ {stem}')
+            else:
+                print(f'  ✗ {stem}: {err}')
+                failed.append(stem)
+
+    # 清理生成的 smoke-root
+    (TEMPLATE_SRC / 'smoke-root.tsx').unlink(missing_ok=True)
+
+    if failed:
+        print(f'\n失败 {len(failed)} 个: {failed}')
+        return 1
+    print(f'\n全部 {len(run)} 个 demo 首帧渲染通过 ✓')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/lib/motion/shotcraft/upstream/assets/scripts/test_sfx_source.py

@@ -0,0 +1,157 @@
+"""Offline behavior checks: python3 -m unittest discover -s assets/scripts -p 'test_sfx_source.py'."""
+
+import argparse
+from contextlib import redirect_stdout
+import importlib.util
+import io
+import json
+import math
+from pathlib import Path
+import shutil
+import struct
+import tempfile
+import unittest
+from unittest.mock import patch
+import wave
+
+spec = importlib.util.spec_from_file_location("sfx_source", Path(__file__).with_name("sfx-source.py"))
+sfx = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(sfx)
+
+
+def player(sid="123", duration="0.5"):
+    return (f'<div data-sound-id="{sid}" data-username="Recordist" data-title="Paper &amp; card" '
+            f'data-duration="{duration}" data-num-downloads="42" '
+            f'data-mp3="https://cdn.freesound.org/previews/0/{sid}_5-lq.mp3"></div>')
+
+
+def result(sid="123", duration="0.5", license="Creative Commons 0"):
+    return (f'<div class="extra bw-search__result">{player(sid, duration)}'
+            f'<a href="/people/Recordist/sounds/{sid}/">Paper</a>'
+            f'<div title="License: {license}"></div>'
+            '<div aria-label="Average rating of 4.5"></div><span class="bw-rating__count">(12)</span>'
+            '<div class="max-h-60px-md-50px"><b>Dry</b> paper recorded in a room.</div></div>')
+
+
+class SourceTests(unittest.TestCase):
+    def test_nested_search_metadata_and_optional_ratings(self):
+        rows = sfx.parse_search(sfx.Document(result()))
+        self.assertEqual(rows[0]["title"], "Paper & card")
+        self.assertEqual(rows[0]["rating_count"], 12)
+        self.assertEqual(rows[0]["duration_seconds"], 0.5)
+        self.assertIn("Dry paper", rows[0]["description"])
+        self.assertTrue(rows[0]["preview_url"].endswith("-hq.mp3"))
+        self.assertEqual(sfx.stats([]), {"rating": None, "rating_count": None})
+        detail = sfx.Document('<span class="bw-rating__count">Overall rating (21 ratings)</span>')
+        self.assertEqual(sfx.stats(list(detail.root.nodes()))["rating_count"], 21)
+
+    def test_empty_results_and_broken_page_are_distinct(self):
+        self.assertEqual(sfx.parse_search(sfx.Document("<p>No results found</p>")), [])
+        with self.assertRaises(ValueError):
+            sfx.parse_search(sfx.Document("<p>Temporarily unavailable</p>"))
+        with self.assertRaises(ValueError):
+            sfx.parse_search(sfx.Document('<div class="bw-search__result">markup changed</div>'))
+
+    def test_search_filters_locally_and_keeps_relevance(self):
+        html = result("123") + result("124", "8") + result("125", license="Attribution NonCommercial") + result("126") + result("123")
+        args = argparse.Namespace(query="paper", license="cc0", min_duration=0, max_duration=1, pages=1, limit=5, output=None)
+        with patch.object(sfx, "web_page", return_value=(sfx.Document(html), sfx.SITE)), redirect_stdout(io.StringIO()) as output:
+            self.assertEqual(sfx.search(args), 0)
+        self.assertEqual([r["id"] for r in json.loads(output.getvalue())["results"]], ["fs:123", "fs:126"])
+
+    def test_license_urls_versions_and_policy(self):
+        self.assertEqual(sfx.license_code("http://creativecommons.org/licenses/by/3.0/"), "CC-BY-3.0")
+        sfx.check_license("CC0-1.0", "cc0")
+        sfx.check_license("CC-BY-4.0", "by")
+        for url in ("https://creativecommons.org/licenses/by-nc/4.0/", "https://example.com/licenses/by/4.0/", "", "https://creativecommons.org/licenses/by-sa/4.0/"):
+            self.assertIsNone(sfx.license_code(url))
+        for code in (None, "CC-BY-4.0", "BY-NC"):
+            with self.assertRaises(ValueError):
+                sfx.check_license(code, "cc0")
+
+    def test_detail_records_actual_license_url(self):
+        url = "http://creativecommons.org/licenses/by/3.0/"
+        doc = sfx.Document(player().replace('data-username="Recordist"', 'data-username=""') + f'<a href="{url}">Attribution</a>')
+        with patch.object(sfx, "web_page", return_value=(doc, sfx.SITE + "/people/Recordist/sounds/123/")):
+            row = sfx.detail("123")
+        self.assertEqual(row["license"], "CC-BY-3.0")
+        self.assertEqual(row["license_url"], url)
+        self.assertEqual(row["author"], "Recordist")
+
+    def test_unsafe_or_incomplete_metadata_rejected(self):
+        for bad in ("../x", "fs:-2", "https://example.com/123"):
+            with self.assertRaises(ValueError):
+                sfx.sound_id(bad)
+        for html in (player().replace("cdn.freesound.org", "evil.example"), player(duration="nan")):
+            with self.assertRaises(ValueError):
+                sfx.player_data(next(n for n in sfx.Document(html).root.nodes() if n.tag == "div"))
+
+    def test_get_checks_license_before_fetching_audio(self):
+        with tempfile.TemporaryDirectory() as directory, patch.object(sfx, "detail", return_value={"license": "CC-BY-3.0"}), patch.object(sfx, "request") as request:
+            with self.assertRaises(ValueError):
+                sfx.download_one("123", Path(directory), "cc0", [])
+            request.assert_not_called()
+
+    def test_download_freezes_provenance_and_rejects_modified_files(self):
+        row = {"id": "fs:123", "license": "CC0-1.0", "preview_url": "https://cdn.freesound.org/previews/0/123_5-hq.mp3"}
+        with tempfile.TemporaryDirectory() as directory, patch.object(sfx, "detail", return_value=dict(row)), patch.object(sfx, "analyze", return_value={"codec": "mp3"}), patch.object(sfx, "request", return_value=(b"audio", row["preview_url"], "audio/mpeg")):
+            out = Path(directory)
+            record = sfx.download_one("123", out, "cc0", [])
+            self.assertTrue(record["is_preview"])
+            self.assertEqual(record["sha256"], sfx.digest(out / record["file"]))
+            (out / record["file"]).write_bytes(b"user edit")
+            with self.assertRaises(ValueError):
+                sfx.download_one("123", out, "cc0", [record])
+            self.assertEqual((out / record["file"]).read_bytes(), b"user edit")
+
+    def test_html_download_does_not_become_audio(self):
+        row = {"id": "fs:123", "license": "CC0-1.0", "preview_url": "https://cdn.freesound.org/previews/0/123_5-hq.mp3"}
+        with tempfile.TemporaryDirectory() as directory, patch.object(sfx, "detail", return_value=row), patch.object(sfx, "request", return_value=(b"<html>Error</html>", row["preview_url"], "text/html")):
+            with self.assertRaises(ValueError):
+                sfx.download_one("123", Path(directory), "cc0", [])
+            self.assertFalse((Path(directory) / "fs-123.mp3").exists())
+
+    def test_partial_failure_saves_success_and_returns_nonzero(self):
+        record = {"id": "fs:123", "file": "fs-123.mp3", "title": "Paper", "author": "Recordist", "page_url": "https://freesound.org/s/123/", "license": "CC0-1.0", "license_url": "https://creativecommons.org/publicdomain/zero/1.0/"}
+        def download(sid, *args):
+            if sid == "124":
+                raise ValueError("license unavailable")
+            return record
+        with tempfile.TemporaryDirectory() as directory, patch.object(sfx, "require_audio_tools"), patch.object(sfx, "download_one", side_effect=download), redirect_stdout(io.StringIO()):
+            args = argparse.Namespace(ids=["123", "124", "123"], out_dir=directory, license="cc0", workers=1)
+            self.assertEqual(sfx.get(args), 1)
+            manifest = json.loads((Path(directory) / sfx.MANIFEST).read_text())
+            self.assertEqual(manifest["assets"], [record])
+            self.assertIn(record["license_url"], (Path(directory) / sfx.CREDITS).read_text())
+            self.assertFalse((Path(directory) / ".freesound-download.lock").exists())
+
+    def test_concurrent_manifest_writer_is_rejected(self):
+        with tempfile.TemporaryDirectory() as directory, patch.object(sfx, "require_audio_tools"):
+            lock = Path(directory) / ".freesound-download.lock"
+            lock.touch()
+            args = argparse.Namespace(ids=["123"], out_dir=directory)
+            with self.assertRaises(ValueError):
+                sfx.get(args)
+            self.assertTrue(lock.exists())
+
+    @unittest.skipUnless(shutil.which("ffmpeg") and shutil.which("ffprobe"), "requires ffmpeg/ffprobe")
+    def test_measure_delayed_stereo_burst_without_downmix_cancellation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "burst.wav"
+            with wave.open(str(path), "wb") as audio:
+                audio.setparams((2, 2, 48000, 0, "NONE", "not compressed"))
+                values = []
+                for i in range(48000):
+                    value = int(16384 * math.sin(2 * math.pi * 1000 * i / 48000)) if 12000 <= i < 16800 else 0
+                    values.append(struct.pack("<hh", value, -value))
+                audio.writeframes(b"".join(values))
+            result = sfx.analyze(path)
+            self.assertAlmostEqual(result["duration_seconds"], 1)
+            self.assertAlmostEqual(result["sample_peak_dbfs"], -6.021, places=2)
+            self.assertTrue(0.25 <= result["energy_peak_seconds"] <= 0.35)
+            self.assertAlmostEqual(result["active_start_seconds"], 0.25)
+            self.assertAlmostEqual(result["active_end_seconds"], 0.35)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/lib/motion/shotcraft/upstream/demos/README.md

@@ -0,0 +1,120 @@
+# demos/ — 镜头卡参考实现源码
+
+多数镜头卡会在“参考实现”中指向本目录；必须先读卡片，再按其明确路径定位准确的
+demo 文件，不能只凭卡名假设目录结构。这里的组件是调校过的 Remotion 实现——
+**用卡先读准确源码**（SKILL.md 理念 5）。
+
+`_legacy/` 仅为工作台旧工程保留已下架镜头，不属于当前镜头库，也不供新片选卡；
+它不参与素材库、画廊与样片冒烟扫描，兼容说明见 [`_legacy/README.md`](_legacy/README.md)。
+
+使用方式：copy 需要的 .tsx 进你的 Remotion 项目（30fps / 1920×1080），
+注册成 Composition 即可跑。每个组件都 `export const <Stem>: React.FC` 并同时导出
+`<大写蛇形>_DURATION`（30fps 帧数），注册时直接用：
+
+```tsx
+import { BlurSlide, BLUR_SLIDE_DURATION } from './blur-slide/BlurSlide';
+<Composition id="BlurSlide" component={BlurSlide}
+  durationInFrames={BLUR_SLIDE_DURATION} fps={30} width={1920} height={1080} />
+```
+
+动画全部是帧的纯函数（无真随机 / 无 Date），逐帧确定性渲染。2026-10 全库做过两轮改版对照，
+每个镜头由作者在原版 / 第一版（质感打磨）/ 第二版（成片级重设计）里择一落版，并去掉了 66 个镜头
+（决策记录 `shot-polish/decisions.json`）。随后做了品牌替换：画面里出现的 logo / 品牌名统一是
+video-shotcraft，合适的文案换成它的宣传语——拿去给自己的产品用时，把 `Brand.tsx` 的件换成你的标志与文案即可。
+
+共享依赖（copy demo 时把用到的一并带上并改 import 路径）：
+
+- `_fixtures/Brand.tsx` — video-shotcraft 品牌件：「镜刻」标志 `<ShotcraftMark>`（可分段描出）、字标
+  `<ShotcraftWordmark>`、品牌色 `BRAND`、宣传文案库 `PITCH`（规范见 `assets/brand/BRAND.md`）。仅依赖 react。
+- `_fixtures/Look.tsx` — 第二轮的视觉系统：8 套调色板 `LOOKS`（暗场 midnight / aurora / ember / graphite / lime，
+  亮场 paper / porcelain / sand）、字号阶梯 `TYPE` 与 `type()`、带主光/余光/地平线光带/暗角/颗粒的
+  舞台 `<Stage>`、透视网格地面 `<GridFloor>`、确定性浮尘 `<Dust>`、单次扫光 `<Sheen>`、
+  逐字/词/行揭示 `<TextReveal>`、`stagger` / `springAt` / `glow`。第二版 demo 都 import 它；依赖 `./Polish`。
+- `_fixtures/Polish.tsx` — 质感工具件：贝塞尔缓动 `EASE` / `ramp` / `mix` / `velocity`、按速度的方向性模糊
+  `SpeedBlur`、`softShadow` / `hairline` / `surface` 材质 helper、`Grain` / `Vignette` / `Backdrop`。仅依赖 remotion + react。
+- `_fixtures/Fixtures.tsx` — 假 UI 场景件（FakeDashboard / Card / TitleBlock / G 调色板），侧栏/顶栏是
+  video-shotcraft 标志与名字（依赖 `./Brand`）。第一版 / 原版落版的 demo 里有二十来个在用。
+- `_fixtures/Motion.tsx` — 480×270 设计坐标的 `DesignStage` + E 缓动表 / seg / lerp / rand / useT。
+  原版 / 第一版落版的 Motion 系 demo 在用（fracture、bezier-source-converge-merge、radial-wave 等十几个）。
+- `_fixtures/PageCam2D.tsx` — 2.5D 页面相机（与 template 的 PageCam 同款坐标数学，self-contained）。
+  spotlight-hero-card / type-and-filter / row-embed / list-stack-press / outro-group-photo-launch 在用。
+- `_textures/` — 真实页面截图与 `live-layout.json`。用到 `staticFile('textures/live/xxx.png')` 的 demo
+  （crash-zoom-punch 两式 / depth-layer-moves / shot-transitions 急刹甩镜 / speed-ramp-freeze 定格标注 /
+  spotlight-hero-card / type-and-filter / deck-deal-flyin / row-embed / list-stack-press /
+  document-typewriter-reveal / page-waterfall-wall / outro-group-photo-launch）要求把 `_textures/` 下的同名文件
+  复制到你项目的 `public/textures/live/`。截图代表"产品既有页面"（审美准则 Q1）；页头站名已改成
+  video-shotcraft 标志 + 字标（周报页标题为 Shotcraft Weekly），其余页面内容未动。
+
+个别 demo 用到 `@remotion/motion-blur`（CameraMotionBlur），需
+`npm i @remotion/motion-blur`。名单（4 个文件 / 4 张卡）：
+
+- `camera/space-camera-moves/DroneDiveLanding.tsx`
+- `opening/crane-rise-reveal/CraneRiseReveal.tsx`
+- `opening/fracture/Fracture.tsx`
+- `opening/magician-card-flourish/MagicianCardFlourish.tsx`
+
+其余快速运动一律用按速度量自算的方向模糊（`SpeedBlur` 或局部实现）——CameraMotionBlur 多重采样
+代价高，且在近静止帧会把画面整体染灰/染黄。
+
+字体：只用系统字体栈（SF / Helvetica Neue / Iowan Old Style / Avenir Next Condensed / Futura 等 macOS 自带字），
+不依赖 `@remotion/google-fonts`。少数 demo 按本机 SF Pro 实测写死了字宽 / 字心坐标（如 letter-drop-physics、
+letterform-zoom、beat-step-list-theme-cycle、pill-chip-slot-cycle-handled），换字体或字号要按注释重测；
+可变字重动画（font-weight-pump）依赖系统可变字体，没有时退化为阶梯字重。
+
+## 真实视频素材（ClipCard，assets/lib/ClipCard.tsx）
+
+库内 152 张镜头卡原本都假设主体是 DOM/SVG 生成物或页面截图，没有一张能
+直接承载真实 mp4 素材。`assets/lib/ClipCard` 补上这个形态：把一段视频包进
+圆角"卡片"，让为矩形卡元素调校过的运镜骨架（spotlight-hero-card /
+magician-card-flourish / neon-frame-orbit-drop / quad-split-parallel-scenes）
+原样驱动真实 footage。copy `assets/lib/ClipCard.tsx` 进项目即可用。
+
+```tsx
+import { ClipCard } from './assets/lib/ClipCard';
+
+// 素材放 public/clips/demo.mp4；素材短于镜头时传 loopDurationInFrames 开启
+// 交叉淡化循环（OffthreadVideo 无 loop prop，播完会冻结）
+<ClipCard src="clips/demo.mp4" size={560} caption="AI generated"
+  loopDurationInFrames={60} durationInFrames={120} />
+```
+
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| `src` | 必填 | public/ 下视频路径（staticFile 解析） |
+| `caption` / `captionSize` | 无 / 17 | 卡片下方 mono 副行；小卡片/远机位 captionSize 提到 ≥32px（Q11） |
+| `size` / `radius` | 560 / 20 | 卡片边长（方形素材）/ 圆角 |
+| `muted` | true | `false` 时循环交叉淡化音频互补，不叠双全量音轨 |
+| `startFrom` | 0 | 从视频第几帧开始播（修剪） |
+| `loopDurationInFrames` | 无 | 视频可播放长度（合成帧）→ 开启循环 |
+| `loopCrossfadeInFrames` | 8 | 循环层重叠淡化帧数 |
+| `durationInFrames` | Composition 时长 | 包围 shot 时长——**务必传**，否则短 shot 嵌长工程会生成不可见层 |
+
+已知坑：
+- `durationInFrames` 不传时层数按 Composition 总时长算（短 shot 长工程问题）。
+- `startFrom` ≥ 可播放长度、或 step < crossfade 时自动回退单层播放（不循环）。
+- 循环素材建议 30fps、方形（运镜骨架按方形卡片标定）。
+
+参考 demo：`demos/ui-entrance/clipcard-looping/ClipCardLooping.tsx`
+（回归三场景：muted=false 循环、startFrom>0+循环、短 Sequence 长 Composition）。
+
+## 测试与验证
+
+1. **类型编译**（`pr-checks.yml` verify job）：`find demos -name '*.tsx'`
+   全部走 `tsc --noEmit --strict`。新增 demo 必须能通过严格编译。
+2. **渲染冒烟**（`assets/scripts/smoke-render-demos.py`）：扫描所有带时长
+   导出（`_DURATION` / `_DUR`）的 demo，自动生成 `template/src/smoke-root.tsx`
+   注册全部，逐个 `remotion still` 渲染首帧，断言输出非空、进程不崩——
+   堵住"能编译不能运行"的 demo（如 composition id 非法、运行时 import
+   缺失、纹理缺失）。本地跑全量：
+
+   ```bash
+   # 需要 template 依赖 + motion-blur（CI 里临时装）
+   cd template && npm ci && npm i --no-save "@remotion/motion-blur@$(node -p "require('./package.json').dependencies.remotion")"
+   cd .. && python3 assets/scripts/smoke-render-demos.py        # 全量
+   python3 assets/scripts/smoke-render-demos.py --subset BlurSlide,GlitchCycle  # 子集
+   python3 assets/scripts/smoke-render-demos.py --list          # 列出可渲染 demo
+   ```
+
+   `--subset` 指向不存在/未找到的 demo 时脚本退出码为 1（明确报错）。
+   需要真实 mp4 素材的 demo（如 ClipCardLooping 用 `public/clips/`）会被跳过
+   并在输出里报告，不阻塞全量。

package/lib/motion/shotcraft/upstream/demos/_fixtures/Brand.tsx

@@ -0,0 +1,112 @@
+// video-shotcraft 品牌件——demo 里出现 logo / 品牌名 / 宣传语时统一用这里：
+// 标志 <ShotcraftMark>（「镜刻 / Frame Chisel」：开口取景框 + 琥珀斜切，与 assets/brand/logo-mark.svg 同一组路径）、
+// 字标 <ShotcraftWordmark>、品牌色 BRAND、宣传文案库 PITCH。规范见 assets/brand/BRAND.md：
+// 字标全小写（不做全大写科技字标）；标志不旋转斜切、不加发光/渐变/描边/投影，琥珀是唯一强调色。
+// 纯 props 函数，只依赖 react；copy demo 时连同本文件一并带上并改 import 路径。
+import React from 'react';
+
+export const BRAND = {
+  name: 'video-shotcraft', // 正式名：全小写 + 连字符
+  short: 'Shotcraft', // 句中简称 / 空间受限时
+  repo: 'github.com/Vincentwei1021/video-shotcraft',
+  amber: '#D3923C', // 标志里的斜切色 = 品牌强调色
+  ink: '#171714', // 亮底上的取景框色
+  paper: '#F5F3EE', // 暗底上的取景框色（反白版）/ 浅色背景
+  slate: '#B5B0A5', // 次级文字（暗底）
+  font: '"Avenir Next", Avenir, Inter, "Helvetica Neue", "PingFang SC", Arial, sans-serif', // 字标字体
+} as const;
+
+// 标志的两段路径（viewBox 0 0 128 128）：frame = 开口取景框，cut = 斜切。分开导出，方便分段做动画
+// （框先画出 / 斜切后划入、斜切单独上光等）。
+export const MARK_PATHS = {
+  frame: 'M16 16h96v26H42v44h70v26H16V16Z',
+  cut: 'M92 48h28L84 84H56l36-36Z',
+} as const;
+
+// 标志。tone='dark' 用于暗底（取景框反白），'light' 用于亮底；frameColor / cutColor 可覆盖。
+// cutProgress 0→1：斜切沿自身方向从无到有划入（默认 1 = 完整）；frameProgress 同理按取景框描出比例裁切。
+export const ShotcraftMark: React.FC<{
+  size?: number; tone?: 'dark' | 'light'; frameColor?: string; cutColor?: string;
+  frameProgress?: number; cutProgress?: number; style?: React.CSSProperties;
+}> = ({ size = 96, tone = 'dark', frameColor, cutColor, frameProgress = 1, cutProgress = 1, style }) => {
+  const id = React.useId().replace(/[^a-zA-Z0-9]/g, '');
+  const fp = Math.max(0, Math.min(1, frameProgress));
+  const cp = Math.max(0, Math.min(1, cutProgress));
+  return (
+    <svg width={size} height={size} viewBox="0 0 128 128" style={{ display: 'block', overflow: 'visible', ...style }}>
+      <defs>
+        {/* 取景框：自左向右揭开 */}
+        <clipPath id={`f${id}`}><rect x={16} y={0} width={96 * fp} height={128} /></clipPath>
+        {/* 斜切：沿 45° 方向从左下划向右上 */}
+        <clipPath id={`c${id}`}><polygon points={`56,84 ${56 + 36 * cp},${84 - 36 * cp} ${84 + 36 * cp},${84 - 36 * cp} 84,84`} /></clipPath>
+      </defs>
+      {fp > 0 && <path d={MARK_PATHS.frame} fill={frameColor ?? (tone === 'dark' ? BRAND.paper : BRAND.ink)} clipPath={fp < 1 ? `url(#f${id})` : undefined} />}
+      {cp > 0 && <path d={MARK_PATHS.cut} fill={cutColor ?? BRAND.amber} clipPath={cp < 1 ? `url(#c${id})` : undefined} />}
+    </svg>
+  );
+};
+
+// 字标：标志 + video-shotcraft 横排（logo-lockup.svg 的比例：标志高 ≈ 字号 2.1 倍，700 字重，+0.03em 字距）。
+// size = 字号（px）；只要字不要标志时 mark={false}。
+export const ShotcraftWordmark: React.FC<{
+  size?: number; tone?: 'dark' | 'light'; color?: string; mark?: boolean;
+  markScale?: number; gap?: number; weight?: number; fontFamily?: string; style?: React.CSSProperties;
+}> = ({ size = 48, tone = 'dark', color, mark = true, markScale = 2.1, gap, weight, fontFamily, style }) => (
+  <div style={{ display: 'inline-flex', alignItems: 'center', gap: gap ?? size * 0.5, ...style }}>
+    {mark && <ShotcraftMark size={size * markScale} tone={tone} />}
+    <span style={{
+      fontFamily: fontFamily ?? BRAND.font,
+      fontSize: size, fontWeight: weight ?? 700, lineHeight: 1, letterSpacing: '0.03em', whiteSpace: 'nowrap',
+      color: color ?? (tone === 'dark' ? BRAND.paper : BRAND.ink),
+    }}>{BRAND.name}</span>
+  </div>
+);
+
+// 宣传文案库——要写口号 / 标题 / 副标题 / 评价时从这里挑或照这个口径改写，别编与事实不符的数字
+// （卡片数、star 数、用户数这类会变的数字不要写进画面）。
+export const PITCH = {
+  en: {
+    motto: 'Frame motion. Craft the shot.', // 品牌短句（BRAND.md）
+    taglines: [
+      'One prompt to a finished promo.',
+      'Cinematic product videos, crafted by your agent.',
+      'Every shot, tuned in one place.',
+      'Shot recipes for cinematic product films.',
+      'Storyboard. Animate. Sound-design. Deliver.',
+      'Your product, in motion.',
+      'From screenshot to showreel.',
+      'Direct the film. Let the agent shoot it.',
+    ],
+    features: [
+      'Shot recipe cards', 'Real page captures', '2.5D camera moves', 'Beat-synced cuts',
+      'Film-grade SFX', 'Motion workbench', 'Remotion render', 'JianYing export',
+    ],
+    praise: [
+      'Feels like a launch film from a real studio.',
+      'The first agent skill that actually understands pacing.',
+      'Our promo shipped the same afternoon.',
+      'Camera moves I would have keyframed for a week.',
+      'Motion design without the motion designer bill.',
+    ],
+    works: 'An agent skill for Claude Code & Codex · Built on Remotion',
+  },
+  zh: {
+    motto: '把运动，刻成镜头。', // 品牌短句（BRAND.md）
+    taglines: [
+      '一句话，出一支片。',
+      '镜头配方卡，宣传片一键直出。',
+      '让你的 agent 拍出电影感产品片。',
+      '每一个镜头，都调到了位。',
+      '分镜、动效、音效、交付，一条龙。',
+      '把截图拍成大片。',
+    ],
+    features: ['镜头配方卡', '真实页面实拍', '2.5D 运镜', '踩点剪辑', '电影级音效', '动效工作台', 'Remotion 渲染', '剪映工程导出'],
+    praise: [
+      '像专业工作室做的发布片。',
+      '第一个真正懂节奏的 agent 技能。',
+      '下午提需求，晚上片子就上线了。',
+      '这些运镜，我自己 K 帧要一周。',
+    ],
+    works: '适用于 Claude Code 与 Codex 的 agent 技能 · 基于 Remotion',
+  },
+} as const;