dsh-drawai 0.4.1 → 0.4.3

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

@@ -1,157 +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()
+"""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

@@ -1,120 +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/`）会被跳过
-   并在输出里报告，不阻塞全量。
+# 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/`）会被跳过
+   并在输出里报告，不阻塞全量。