dsh-drawai 0.3.3 → 0.4.0

package/lib/motion/scene-kit.js

@@ -0,0 +1,183 @@
+// 场景层脚手架：建工程时把这三件拷进 <工程>/scene-kit/。
+//
+// 为什么是「拷贝」不是「引用」：Remotion 的 bundle 只解析工程目录里的相对路径，
+// 跨包 import 会在打包期炸掉；而这三件又必须每个工程都能改。
+//
+// 为什么值得有：画质的一半不在插件里，在场景怎么写。同一件事（亚像素抖动到底
+// 是居中抖还是右下角抖、弹簧是 9% 过冲还是 30% 过冲）让每个片子自己发明，
+// 结果就是 14 种风格长出 14 种错法。放在这里 = 只有一份实现。
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+const DET = `// 确定性随机：同一个 (frame, salt, index) 永远得到同一个值。
+// 禁 Math.random()：帧渲染可能被并行、被重跑、被预取，随机数会让同一 t 出两种画面。
+// 用法：const dx = detBetween(frame, 7, 0, -0.5, 0.5)
+
+export function hash32(seed: number): number {
+  let x = seed | 0
+  x = (x ^ 61) ^ (x >>> 16)
+  x = x + (x << 3)
+  x = x ^ (x >>> 4)
+  x = Math.imul(x, 0x27d4eb2d)
+  x = x ^ (x >>> 15)
+  return (x >>> 0) / 4294967296
+}
+
+export const det = (frame: number, salt = 0, index = 0): number =>
+  hash32(Math.imul(frame + 1, 73856093) ^ Math.imul(salt + 1, 19349663) ^ Math.imul(index + 1, 83492791))
+
+export const detBetween = (frame: number, salt: number, index: number, min: number, max: number): number =>
+  min + (max - min) * det(frame, salt, index)
+
+// 低差异序列：累积采样要用 Halton(2,3) 而不是均匀随机，
+// 否则 8 个样本会扎堆，边缘反而更脏。
+export function halton(index: number, base: number): number {
+  let result = 0
+  let fraction = 1 / base
+  let i = index + 1
+  while (i > 0) {
+    result += (i % base) * fraction
+    i = Math.floor(i / base)
+    fraction /= base
+  }
+  return result
+}
+
+// 亚像素抖动偏移（单位：像素），居中在 [-0.5, 0.5]。
+export const jitter = (sample: number, index: number): [number, number] =>
+  [halton(index, 2) - 0.5, halton(index, 3) - 0.5]
+`
+
+const GROW = `// 等轴生长曲线：底面落位 → 立面 scaleY 拉起 → 屋顶延迟盖上。
+// 三种曲线都是闭式解：给定 t 就能算，不依赖历史帧，所以任意帧可独立渲染。
+
+export const clamp01 = (value: number): number => (value < 0 ? 0 : value > 1 ? 1 : value)
+
+export const easeOutCubic = (value: number): number => 1 - Math.pow(1 - clamp01(value), 3)
+export const easeInOutCubic = (value: number): number => {
+  const t = clamp01(value)
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2
+}
+export const easeOutBack = (value: number, overshoot = 1.70158): number => {
+  const t = clamp01(value) - 1
+  return 1 + (overshoot + 1) * t * t * t + overshoot * t * t
+}
+
+// 阻尼弹簧的闭式解。zeta=0.61 时过冲约 9%（e^(-pi*zeta/sqrt(1-zeta^2))≈0.089），
+// 正好是「有生命、但不像卡通」的那一档；要更弹就降 zeta，要更硬就升。
+export function spring(t: number, duration = 0.6, zeta = 0.61): number {
+  if (t <= 0) return 0
+  const wn = 10 / Math.max(duration, 0.01)
+  const wd = wn * Math.sqrt(1 - zeta * zeta)
+  return 1 - Math.exp(-zeta * wn * t) * (Math.cos(wd * t) + ((zeta * wn) / wd) * Math.sin(wd * t))
+}
+
+// 落体：加速下坠，触地一帧内挤压回弹（sy 从 0.7 弹回 1，40rad/s 的快振）。
+export function drop(t: number, duration = 0.3): { y: number; sy: number; landed: boolean } {
+  if (t <= 0) return { y: 1, sy: 1, landed: false }
+  if (t < duration) {
+    const x = clamp01(t / duration)
+    return { y: 1 - x * x, sy: 1, landed: false }
+  }
+  const tau = t - duration
+  return { y: 0, sy: 1 - 0.3 * Math.exp(-tau / 0.05) * Math.cos(40 * tau), landed: true }
+}
+
+// 立面：底座先落位，之后 scaleY 从 base 拉到 1。
+export function wallScale(t: number, base = 0.1, duration = 0.6): number {
+  if (t <= 0) return 0
+  return base + (1 - base) * spring(t, duration)
+}
+
+// 屋顶：比墙晚 lag 秒盖上，用 3 帧的快速 pop。
+export function roofAt(t: number, lag = 0.375, duration = 0.12): number {
+  return clamp01((t - lag) / duration)
+}
+
+// 错峰：第 index 个物体晚 stagger 秒开始，整个梯队铺满 spread 秒。
+export const stagger = (index: number, stagger = 0.04): number => index * stagger
+
+// 冲击波：半径随 t 线性扩散（pulse_speed=15 是等轴岛上「刚好扫过半个岛」的速度）。
+export const pulseRadius = (t: number, speed = 15, from = 1): number => from + speed * Math.max(0, t)
+`
+
+const LOOK = `// 画面质感三件：SSAA、软阴影、色调映射，外加一层确定性颗粒。
+// 放在 <ThreeCanvas> 里面（Grain 放外面，覆盖在整幅画面上）。
+//
+// 关键：等轴场景满屏都是 30°/60° 斜边，1× 渲染出来的阶梯肉眼可见。
+// 把绘制缓冲放大到 2× 再让浏览器缩小，就是最便宜的 SSAA —— 比任何 CSS 滤镜都真实。
+
+import * as THREE from 'three'
+import { useThree } from '@react-three/fiber'
+import { useLayoutEffect } from 'react'
+import { AbsoluteFill, useCurrentFrame } from 'remotion'
+
+type LookProps = {
+  ssaa?: number          // 1 = 关；2 = 推荐；>2 收益递减
+  shadow?: 'soft' | 'pcf' | 'basic'
+  exposure?: number
+  toneMapping?: 'aces' | 'neutral' | 'none'
+}
+
+export function Look({ ssaa = 2, shadow = 'soft', exposure = 1, toneMapping = 'aces' }: LookProps) {
+  const { gl } = useThree()
+  useLayoutEffect(() => {
+    const ratio = gl.getPixelRatio()
+    const type = gl.shadowMap.type
+    const mode = gl.toneMapping
+    const previousExposure = gl.toneMappingExposure
+    gl.setPixelRatio(Math.min(2, Math.max(1, ssaa)))
+    gl.shadowMap.type = shadow === 'basic' ? THREE.BasicShadowMap : shadow === 'pcf' ? THREE.PCFShadowMap : THREE.PCFSoftShadowMap
+    gl.shadowMap.needsUpdate = true
+    gl.toneMapping = toneMapping === 'none' ? THREE.NoToneMapping : toneMapping === 'neutral' ? THREE.NeutralToneMapping : THREE.ACESFilmicToneMapping
+    gl.toneMappingExposure = exposure
+    return () => {
+      gl.setPixelRatio(ratio)
+      gl.shadowMap.type = type
+      gl.toneMapping = mode
+      gl.toneMappingExposure = previousExposure
+    }
+  }, [gl, ssaa, shadow, exposure, toneMapping])
+  return null
+}
+
+// 颗粒：feTurbulence 是确定性的（同 seed 同图），不消耗逐帧随机数，
+// 用来打散 8bit 渐变的色带——色带是被「平」出来的，颗粒就是把它重新打碎。
+export function Grain({ opacity = 0.05, seed = 7 }: { opacity?: number; seed?: number }) {
+  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="160" height="160"><filter id="n" x="0" y="0"><feTurbulence type="fractalNoise" baseFrequency="0.9" numOctaves="3" seed="' + seed + '"/><feColorMatrix type="saturate" values="0"/></filter><rect width="160" height="160" filter="url(#n)" opacity="1"/></svg>'
+  return (
+    <AbsoluteFill style={{ pointerEvents: 'none', opacity, mixBlendMode: 'multiply',
+      backgroundImage: 'url("data:image/svg+xml;utf8,' + encodeURIComponent(svg) + '")',
+      backgroundSize: '160px 160px' }} />
+  )
+}
+
+// 暗角：只压四角，中间不动。等轴画面四角是空的，压下去反而更聚。
+export function Vignette({ strength = 0.18 }: { strength?: number }) {
+  return (
+    <AbsoluteFill style={{ pointerEvents: 'none',
+      background: 'radial-gradient(ellipse at 50% 48%, rgba(0,0,0,0) 52%, rgba(20,16,48,' + strength + ') 100%)' }} />
+  )
+}
+`
+
+export const SCENE_KIT = { 'det.ts': DET, 'grow.ts': GROW, 'look.tsx': LOOK }
+
+export function sceneKitFiles() {
+  return Object.keys(SCENE_KIT)
+}
+
+// 只写缺的文件：agent 改过的 scene-kit 不该在下一次 create 时被覆盖。
+export function writeSceneKit(dir, options = {}) {
+  const io = options.io || { join, dirname, existsSync, mkdirSync, writeFileSync }
+  const written = []
+  for (const [name, source] of Object.entries(SCENE_KIT)) {
+    const file = io.join(dir, 'scene-kit', name)
+    io.mkdirSync(io.dirname(file), { recursive: true })
+    if (io.existsSync(file) && !options.overwrite) continue
+    io.writeFileSync(file, source, 'utf8')
+    written.push('scene-kit/' + name)
+  }
+  return written
+}

package/lib/motion/sfx.js

@@ -0,0 +1,232 @@
+// 音效搜索与下载；来源信息保存在单一素材索引，不做许可证审批。
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+import { decodePcm } from './beats.js'
+import { parseProjectJson } from './json.js'
+
+const SITE = 'https://freesound.org'
+const MANIFEST = 'audio-manifest.json'
+const MAX_BYTES = 32 * 1024 * 1024
+const UA = 'dsh-drawai/1.0 (Freesound SFX sourcing)'
+
+function decodeAttr(value) {
+  return String(value || '')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+}
+
+function attr(chunk, name) {
+  const match = new RegExp('\\b' + name + '="([^"]*)"').exec(chunk)
+  return match ? decodeAttr(match[1]) : ''
+}
+
+export function licenseCode(url) {
+  if (!url) return null
+  let parsed
+  try { parsed = new URL(url) } catch { return null }
+  if (!/^(www\.)?creativecommons\.org$/.test(parsed.hostname)) return null
+  const path = parsed.pathname.replace(/\/+$/, '')
+  if (path === '/publicdomain/zero/1.0') return 'CC0-1.0'
+  const by = /^\/licenses\/by\/(1\.0|2\.0|2\.5|3\.0|4\.0)$/.exec(path)
+  return by ? 'CC-BY-' + by[1] : null
+}
+
+async function fetchText(url, signal) {
+  const response = await fetch(url, { headers: { 'user-agent': UA }, redirect: 'follow', signal })
+  if (!response.ok) throw new Error('Freesound 请求失败：HTTP ' + response.status)
+  const type = response.headers.get('content-type') || ''
+  if (!type.includes('text/html')) throw new Error('Freesound 返回的不是网页：' + type)
+  return { text: await response.text(), url: response.url }
+}
+
+async function fetchBytes(url, signal) {
+  const response = await fetch(url, { headers: { 'user-agent': UA }, redirect: 'follow', signal })
+  if (!response.ok) throw new Error('下载失败：HTTP ' + response.status)
+  const type = response.headers.get('content-type') || ''
+  if (!/audio\/mpeg|audio\/mp3|octet-stream/.test(type)) throw new Error('下载到的不是 mp3：' + type)
+  const length = Number(response.headers.get('content-length') || 0)
+  if (length > MAX_BYTES) throw new Error('音效超过 32MB，换一个更短的')
+  return { bytes: Buffer.from(await response.arrayBuffer()), url: response.url }
+}
+
+// Freesound 搜索结果页：每个结果块里有一个 data-player，带着 id/标题/时长/预览地址。
+export function parseSearch(html) {
+  const rows = []
+  const chunks = String(html).split(/class="[^"]*\bbw-search__result\b/)
+  for (const chunk of chunks.slice(1)) {
+    const id = attr(chunk, 'data-sound-id')
+    const preview = attr(chunk, 'data-mp3')
+    const duration = Number(attr(chunk, 'data-duration'))
+    if (!id || !preview || !Number.isFinite(duration) || duration <= 0) continue
+    const licenseLabel = (/(?:title="License: )([^"]+)/.exec(chunk) || [])[1] || 'unknown'
+    const page = new RegExp('href="([^"]*?/people/[^"]*?/sounds/' + id + '/)"').exec(chunk)
+    rows.push({
+      id: 'fs:' + id,
+      title: attr(chunk, 'data-title') || 'untitled',
+      author: attr(chunk, 'data-username') || 'unknown',
+      seconds: duration,
+      preview: preview.replace('-lq.mp3', '-hq.mp3'),
+      pageUrl: page ? new URL(decodeAttr(page[1]), SITE).href : SITE + '/s/' + id + '/',
+      licenseLabel,
+    })
+  }
+  return rows
+}
+
+export async function searchSfx(options = {}) {
+  const query = String(options.query || '').trim()
+  if (!query) throw new Error('query 必填，例如 "paper whoosh"')
+  const min = Math.max(0, Number(options.minDuration) || 0)
+  const max = options.maxDuration === undefined || options.maxDuration === null || options.maxDuration === ''
+    ? null : Number(options.maxDuration)
+  if (max !== null && (!Number.isFinite(max) || max <= min)) throw new Error('maxDuration 要大于 minDuration')
+  const limit = Math.max(1, Math.min(20, Math.round(Number(options.limit) || 8)))
+  const filter = 'duration:[' + min + ' TO ' + (max === null ? '*' : max) + ']'
+  const url = SITE + '/search/?' + new URLSearchParams({ q: query, f: filter, page: '1', s: 'Automatic by relevance' })
+  const { text } = await fetchText(url, options.signal)
+  const rows = parseSearch(text).filter((row) => {
+    if (row.seconds < min) return false
+    if (max !== null && row.seconds > max) return false
+    return true
+  })
+  if (!rows.length && /no (?:sounds|results)|0 sounds|couldn't find|did not match/i.test(text)) {
+    return { query, results: [], note: 'Freesound 没有匹配结果，换个更短的查询词' }
+  }
+  if (!rows.length) throw new Error('没解析出结果：Freesound 页面结构可能变了')
+  return { query, results: rows.slice(0, limit) }
+}
+
+export async function fetchSound(id, signal) {
+  const sid = String(id).replace(/^fs:/, '')
+  if (!/^[1-9][0-9]*$/.test(sid)) throw new Error('音效 id 形如 fs:12345')
+  const { text, url } = await fetchText(SITE + '/s/' + sid + '/', signal)
+  const chunk = String(text).split('data-sound-id="' + sid + '"')
+  if (chunk.length < 2) throw new Error('详情页没有这个音效：fs:' + sid)
+  const body = chunk[1].slice(0, 8000)
+  const preview = attr(body, 'data-mp3')
+  const duration = Number(attr(body, 'data-duration'))
+  if (!preview || !Number.isFinite(duration) || duration <= 0) throw new Error('详情页缺少预览或时长：fs:' + sid)
+  const canonical = /\/people\/([^/]+)\/sounds\/[0-9]+\//.exec(new URL(url).pathname)
+  if (!canonical) throw new Error('详情页不是规范的音效页：fs:' + sid)
+  const licenses = new Set()
+  for (const match of String(text).matchAll(/href="(https?:\/\/(?:www\.)?creativecommons\.org\/[^"]+)"/g)) licenses.add(match[1])
+  const licenseUrl = [...licenses][0] || null
+  const license = licenseCode(licenseUrl) || 'unknown'
+  return {
+    id: 'fs:' + sid,
+    title: attr(body, 'data-title') || 'untitled',
+    author: decodeURIComponent(canonical[1]),
+    seconds: duration,
+    preview: preview.replace('-lq.mp3', '-hq.mp3'),
+    pageUrl: url,
+    license,
+    licenseUrl,
+  }
+}
+
+// 10ms 窗的 RMS / 峰值 / 有效起止，跟上游 analyze 的口径一致（不是 LUFS）
+async function measure(file) {
+  const { pcm, sampleRate } = await decodePcm(file)
+  const samples = pcm.length / 2
+  if (!samples) throw new Error('音效是空的')
+  const block = Math.max(1, Math.round(sampleRate * 0.01))
+  const energies = []
+  let peak = 0
+  let squares = 0
+  let sum = 0
+  let count = 0
+  for (let index = 0; index < samples; index++) {
+    const value = pcm.readInt16LE(index * 2) / 32768
+    const energy = value * value
+    squares += energy
+    sum += energy
+    count += 1
+    if (Math.abs(value) > peak) peak = Math.abs(value)
+    if (count === block || index === samples - 1) {
+      energies.push(Math.sqrt(sum / count))
+      sum = 0
+      count = 0
+    }
+  }
+  const loudest = Math.max(...energies)
+  const active = energies.map((value, index) => ({ value, index })).filter((item) => item.value >= loudest * 0.01)
+  const seconds = samples / sampleRate
+  const rmsDb = Math.round(20 * Math.log10(Math.max(Math.sqrt(squares / samples), 1e-6)) * 100) / 100
+  const peakDb = Math.round(20 * Math.log10(Math.max(peak, 1e-6)) * 100) / 100
+  return {
+    sampleRate, channels: 1, seconds: Math.round(seconds * 1000) / 1000,
+    peakDb, rmsDb,
+    suggestedGainDb: Math.max(-6, Math.min(24, Math.round(-16 - rmsDb))),
+    energyWindowSeconds: 0.01,
+    energyPeakSeconds: Math.round((energies.indexOf(loudest) + 0.5) * 0.01 * 1000) / 1000,
+    activeStartSeconds: Math.round(active[0].index * 0.01 * 1000) / 1000,
+    activeEndSeconds: Math.round((active[active.length - 1].index + 1) * 0.01 * 1000) / 1000,
+  }
+}
+
+export function readManifest(dir) {
+  const file = join(dir, 'assets', MANIFEST)
+  if (!existsSync(file)) return { version: 1, assets: [] }
+  const raw = parseProjectJson(readFileSync(file, 'utf8'))
+  if (raw.version !== 1 || !Array.isArray(raw.assets)) throw new Error('audio-manifest.json 结构不支持，换一个工程目录')
+  return raw
+}
+
+function writeManifest(dir, manifest) {
+  writeFileSync(join(dir, 'assets', MANIFEST), JSON.stringify(manifest, null, 2) + '\n', 'utf8')
+}
+
+export async function getSfx(dir, ids, options = {}) {
+  const list = (Array.isArray(ids) ? ids : [ids]).map((id) => String(id)).filter(Boolean)
+  if (!list.length) throw new Error('ids 必填，形如 ["fs:12345"]')
+  const sfxDir = join(dir, 'assets', 'sfx')
+  mkdirSync(sfxDir, { recursive: true })
+  const manifest = options.persist === false ? { version: 1, assets: [] } : readManifest(dir)
+  const results = []
+  for (const id of list) {
+    try {
+      const sound = await fetchSound(id, options.signal)
+      const file = 'fs-' + sound.id.replace(/^fs:/, '') + '.mp3'
+      const target = join(sfxDir, file)
+      if (!existsSync(target)) {
+        const { bytes } = await fetchBytes(sound.preview, options.signal)
+        writeFileSync(target, bytes)
+      }
+      const analysis = await measure(target)
+      const row = {
+        ...sound,
+        provider: 'freesound',
+        file: 'sfx/' + file,
+        bytes: statSync(target).size,
+        sha256: createHash('sha256').update(readFileSync(target)).digest('hex'),
+        downloadKind: 'mp3-preview-hq',
+        isPreview: true,
+        downloadedAt: new Date().toISOString(),
+        changes: [],
+        analysis,
+      }
+      manifest.assets = manifest.assets.filter((item) => item.id !== row.id).concat(row)
+      if (options.persist !== false) writeManifest(dir, manifest)
+      results.push({ ok: true, asset: row })
+    } catch (error) {
+      results.push({ ok: false, id, error: String(error.message || error) })
+    }
+  }
+  return { dir: sfxDir, results }
+}
+
+export function listSfx(dir) {
+  const manifest = readManifest(dir)
+  return manifest.assets.map((asset) => {
+    const gain = asset.analysis?.suggestedGainDb
+      ?? (typeof asset.analysis?.rmsDb === 'number' ? Math.max(-6, Math.min(24, Math.round(-16 - asset.analysis.rmsDb))) : 0)
+    return {
+      id: asset.id, file: asset.file, title: asset.title, author: asset.author,
+      license: asset.license, seconds: asset.analysis?.seconds, peakDb: asset.analysis?.peakDb,
+      suggestedGainDb: gain,
+      use: 'motion_audio {action:"add", file:"' + asset.file + '", role:"sfx", gainDb:' + gain + '}',
+    }
+  })
+}

package/lib/motion/shotcraft/ClipCard.tsx

@@ -0,0 +1,204 @@
+import React from 'react';
+import {
+  OffthreadVideo,
+  Sequence,
+  interpolate,
+  staticFile,
+  useCurrentFrame,
+  useVideoConfig,
+} from 'remotion';
+
+// ClipCard — wraps an external video clip (mp4) into a "card hero" that shot
+// recipes designed for DOM/SVG subjects (spotlight-hero-card,
+// magician-card-flourish, neon-frame-orbit-drop, quad-split-parallel-scenes…)
+// can drive directly. Fills the library gap where every card assumes generated
+// DOM content or page screenshots, never real footage.
+//
+// Battle-tested in a delivered 39s promo (spotlight push-in at zoom 1.7 on a
+// 512×512 clip; 3-up quad-split with 32px captions after a Q11 readability
+// review finding — small cards need captionSize raised to keep ≥32px on-screen).
+//
+// Crossfade loop: OffthreadVideo (as of 4.0.484) has no `loop` prop and freezes
+// past media end. Pass `loopDurationInFrames` to enable a seamless dissolve
+// loop — each next pass fades in over the previous tail. The effective step is
+// `loopDurationInFrames - startFrom` (a `startFrom` trim shortens the playable
+// media), and layer count is derived from the enclosing shot's duration, not
+// the Composition's, so a short shot inside a long composition doesn't spawn
+// invisible layers. Layer audio is crossfaded with complementary `volume`
+// curves so an unmuted loop doesn't stack two full-volume tracks.
+
+const ACCENT = '#4da3ff';
+
+// Each loop layer crossfades BOTH its audio and its opacity at its edges:
+// an incoming fade 0→1 over `fadeIn` frames at the layer start, a steady body,
+// then an outgoing fade 1→0 over `fadeOut` frames ending at `step` — the frame
+// where the NEXT layer starts. Adjacent layers therefore overlap for exactly
+// `crossfade` frames and their envelopes are complementary (sum to 1), so an
+// unmuted loop never stacks two full-volume tracks; visual dissolve and audio
+// crossfade stay in sync since they share the same envelope.
+const LoopLayer: React.FC<{
+  src: string;
+  size: number;
+  muted: boolean;
+  startFrom: number;
+  fadeIn: number;
+  fadeOut: number;
+  step: number;
+  fit: React.CSSProperties['objectFit'];
+}> = ({ src, size, muted, startFrom, fadeIn, fadeOut, step, fit }) => {
+  const frame = useCurrentFrame();
+
+  // envelope(f): 0 at f=0 (unless fadeIn=0 → 1), 1 through the body, 0 at
+  // f=step+fadeOut. Adjacent layers are spaced `step` apart and each fades
+  // out over `fadeOut` into the next one's `fadeIn` window.
+  let envelope: number;
+  if (frame <= fadeIn) {
+    envelope = fadeIn === 0 ? 1 : interpolate(frame, [0, fadeIn], [0, 1], { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' });
+  } else if (frame <= step) {
+    envelope = 1;
+  } else {
+    envelope = interpolate(frame, [step, step + fadeOut], [1, 0], { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' });
+  }
+
+  const opacity = Math.max(0, Math.min(1, envelope));
+  const volume = muted ? 1 : opacity;
+
+  return (
+    <OffthreadVideo
+      src={staticFile(src)}
+      muted={muted}
+      volume={volume}
+      startFrom={startFrom}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        width: size,
+        height: size,
+        objectFit: fit,
+        opacity,
+      }}
+    />
+  );
+};
+
+export const ClipCard: React.FC<{
+  src: string; // path under public/
+  caption?: string; // monospace caption bar under the clip
+  size?: number; // card edge (square clips)
+  radius?: number;
+  muted?: boolean;
+  captionSize?: number; // default 17 — raise on small/far cards to keep ≥32px on-screen text
+  startFrom?: number; // trim: play the clip from this frame
+  style?: React.CSSProperties;
+  fit?: React.CSSProperties['objectFit']; // DrawAI: preserve the full reference frame when requested.
+  loopDurationInFrames?: number; // playable clip length in comp frames → enables crossfade loop
+  loopCrossfadeInFrames?: number; // default 8
+  durationInFrames?: number; // enclosing shot duration — loop layer count is derived from this,
+  // not the Composition duration (a short shot in a long composition)
+}> = ({
+  src,
+  caption,
+  size = 560,
+  radius = 20,
+  muted = true,
+  startFrom = 0,
+  style,
+  fit = 'cover',
+  captionSize = 17,
+  loopDurationInFrames,
+  loopCrossfadeInFrames = 8,
+  durationInFrames,
+}) => {
+  const { durationInFrames: compDuration } = useVideoConfig();
+  const capH = caption ? Math.round(captionSize * 2.6) : 0;
+
+  let video: React.ReactNode;
+  // Guard: a startFrom trim that reaches or exceeds the playable media (or any
+  // degenerate step) must NOT loop — falling back to a plain single pass keeps
+  // a visible, audible clip instead of a layer that instantly fades to 0.
+  // step must also be >= crossfade, else >2 layers overlap at once and the
+  // complementary envelopes no longer sum to 1 (visual/audio stack past full).
+  const step = loopDurationInFrames
+    ? loopDurationInFrames - startFrom - loopCrossfadeInFrames
+    : 0;
+  const canLoop =
+    !!loopDurationInFrames &&
+    loopDurationInFrames > loopCrossfadeInFrames &&
+    step >= loopCrossfadeInFrames;
+  if (canLoop) {
+    const shotFrames = durationInFrames ?? compDuration;
+    const n = Math.max(1, Math.ceil(shotFrames / step));
+    video = (
+      <div style={{ position: 'relative', width: size, height: size }}>
+        {Array.from({ length: n }, (_, i) => (
+          <Sequence
+            key={i}
+            from={i * step}
+            durationInFrames={loopDurationInFrames}
+            layout="none"
+          >
+            <LoopLayer
+              src={src}
+              fit={fit}
+              size={size}
+              muted={muted}
+              startFrom={startFrom}
+              fadeIn={i === 0 ? 0 : loopCrossfadeInFrames}
+              fadeOut={loopCrossfadeInFrames}
+              step={step}
+            />
+          </Sequence>
+        ))}
+      </div>
+    );
+  } else {
+    video = (
+      <OffthreadVideo
+        src={staticFile(src)}
+        muted={muted}
+        startFrom={startFrom}
+        style={{
+          width: size,
+          height: size,
+          objectFit: fit,
+          display: 'block',
+        }}
+      />
+    );
+  }
+
+  return (
+    <div
+      style={{
+        width: size,
+        height: size + capH,
+        borderRadius: radius,
+        background: '#111116',
+        border: '1px solid rgba(255,255,255,0.10)',
+        boxShadow: '0 24px 80px rgba(0,0,0,0.55)',
+        overflow: 'hidden',
+        ...style,
+      }}
+    >
+      {video}
+      {caption ? (
+        <div
+          style={{
+            height: capH,
+            display: 'flex',
+            alignItems: 'center',
+            padding: '0 18px',
+            fontFamily: 'ui-monospace, Menlo, monospace',
+            fontSize: captionSize,
+            color: 'rgba(255,255,255,0.72)',
+            letterSpacing: 0.5,
+            borderTop: '1px solid rgba(255,255,255,0.10)',
+          }}
+        >
+          <span style={{ color: ACCENT, marginRight: 10 }}>▸</span>
+          {caption}
+        </div>
+      ) : null}
+    </div>
+  );
+};