@vibecuting/video-project-core 0.1.30 → 0.1.31

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@vibecuting/video-project-core",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./storybook": "./src/storybook/index.ts",
+    "./storybook/remotion-preview": "./src/storybook/remotion-preview.tsx",
+    "./lint": "./src/lint/index.ts"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -22,7 +25,7 @@
     "test": "pnpm exec vitest run"
   },
   "dependencies": {
-    "@vibecuting/component-project-helper": "0.1.30",
+    "@vibecuting/component-project-helper": "0.1.31",
     "@remotion/transitions": "4.0.473",
     "mermaid": "^11.12.2",
     "react": "^19.0.0",

package/src/base/utils/background-audio-layer.tsx

@@ -79,7 +79,7 @@ export const VideoBackgroundAudioLayer = ({
         >
           <Audio
             src={resolveVideoLayerAssetSource(cue.source)}
-            volume={(frame) => getVideoLayerCueVolume(cue, frame)}
+            volume={(frame: number) => getVideoLayerCueVolume(cue, frame)}
           />
         </Sequence>
       ))}

package/src/base/utils/voice-captions-foreground.tsx

@@ -123,7 +123,6 @@ export const VideoVoiceCaptionsForeground = ({
                 key={`${caption.startMs}-${index}`}
                 from={startFrame}
                 durationInFrames={durationInFrames}
-                layout="none"
               >
                 <div
                   style={{

package/src/core/scene/photo/3dvr-photo/default-3dvr-photo-scene/default-3dvr-photo-scene.tsx

@@ -89,7 +89,7 @@ export const Default3DVRPhotoScene = VideoComponent(componentMetadata)(
       const { fps } = useVideoConfig()
       const portrait = runtime.height > runtime.width
       const animated = sceneConfig.sceneType === 'animation'
-      const entrance = sceneConfig.sceneType === 'animation' ? spring({ frame, fps, delay: 4, config: { damping: 18, mass: 0.8, stiffness: 120 } }) : 1
+      const entrance = sceneConfig.sceneType === 'animation' ? spring({ frame: Math.max(0, frame - 4), fps, config: { damping: 18, mass: 0.8, stiffness: 120 } }) : 1
       const orbit = animated ? Math.sin((frame / fps) * Math.PI * 0.55) : 0
       const cameraYaw = yaw + orbit * 4 + (1 - entrance) * (portrait ? -3 : -4)
       const cameraPitch = pitch + Math.sin((frame / fps) * Math.PI * 0.35) * 1.5 + (1 - entrance) * 1.6

package/src/core/scene/photo/effects-photo/default-effects-photo-scene/default-effects-photo-scene.tsx

@@ -149,7 +149,7 @@ export const DefaultEffectsPhotoScene = VideoComponent(componentMetadata)(
               config: { damping: 22, mass: 0.8, stiffness: 130 },
             })
           : 1
-      const reveal = sceneConfig.sceneType === 'animation' ? spring({ frame, fps, delay: 6, config: { damping: 20, mass: 0.7, stiffness: 150 } }) : 1
+      const reveal = sceneConfig.sceneType === 'animation' ? spring({ frame: Math.max(0, frame - 6), fps, config: { damping: 20, mass: 0.7, stiffness: 150 } }) : 1
       const focusDrift = sceneConfig.sceneType === 'animation' ? Math.sin((frame / fps) * Math.PI * 0.75) : 0
       const scale = 1.01 + (1 - animationProgress) * 0.06 + focusDrift * 0.008
       const translateX = (1 - animationProgress) * (portrait ? -8 : -12) + focusDrift * (portrait ? 8 : 12)

package/src/lint/index.ts

@@ -0,0 +1,2 @@
+export { lintSceneConvention } from './scene-convention-lint'
+export type { SceneConventionLintOptions, SceneConventionLintResult } from './scene-convention-lint'

package/src/lint/scene-convention-lint.test.ts

@@ -0,0 +1,86 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+import { lintSceneConvention } from './scene-convention-lint'
+
+function writeSceneFixture(rootDir: string) {
+  const folder = path.join(rootDir, 'src/components/default-component-scene')
+  const sharedFolder = path.join(rootDir, 'src/components/_shared')
+  fs.mkdirSync(folder, { recursive: true })
+  fs.mkdirSync(sharedFolder, { recursive: true })
+
+  fs.writeFileSync(
+    path.join(folder, 'default-component-scene.tsx'),
+    [
+      "import { z } from 'zod'",
+      "export const componentMetadata = { sourceFile: 'src/components/default-component-scene/default-component-scene.tsx' }",
+      "export const DefaultComponentScene = defineSceneComponent({ propsSchema: z.object({ title: z.string() }), component: function DefaultComponentScene() { useRemotionSceneRuntime(); return <SceneMotionLayer /> } })",
+      '',
+    ].join('\n'),
+  )
+  fs.writeFileSync(
+    path.join(folder, 'default-component-scene-Landscape.tsx'),
+    "export const componentMetadata = { sourceFile: 'src/components/default-component-scene/default-component-scene-Landscape.tsx', aspectRatio: '16:9' }\n",
+  )
+  fs.writeFileSync(
+    path.join(folder, 'default-component-scene-Horizontal.tsx'),
+    "export const componentMetadata = { sourceFile: 'src/components/default-component-scene/default-component-scene-Horizontal.tsx', aspectRatio: '9:16' }\n",
+  )
+  fs.writeFileSync(
+    path.join(folder, 'default-component-scene.stories.tsx'),
+    "const meta = { title: 'components/default-component-scene/DefaultComponentSceneLandscape' }\nexport default meta\nexport const Default = { parameters: { scenePreviewAspectRatio: '16:9' } }\n",
+  )
+  fs.writeFileSync(
+    path.join(folder, 'default-component-scene.animated.stories.tsx'),
+    "const meta = { title: 'components/default-component-scene/DefaultComponentSceneLandscape' }\nexport default meta\nexport const Animated = { parameters: { scenePreviewAspectRatio: '16:9', scenePreviewMode: 'animation' } }\n",
+  )
+  fs.writeFileSync(
+    path.join(folder, 'default-component-scene-Horizontal.stories.tsx'),
+    "const meta = { title: 'components/default-component-scene/DefaultComponentSceneHorizontal' }\nexport default meta\nexport const Default = { parameters: { scenePreviewAspectRatio: '9:16' } }\n",
+  )
+  fs.writeFileSync(
+    path.join(folder, 'default-component-scene-Horizontal.animated.stories.tsx'),
+    "const meta = { title: 'components/default-component-scene/DefaultComponentSceneHorizontal' }\nexport default meta\nexport const Animated = { parameters: { scenePreviewAspectRatio: '9:16', scenePreviewMode: 'animation' } }\n",
+  )
+  fs.writeFileSync(path.join(folder, 'default-component-scene.test.tsx'), "import test from 'node:test'\ntest('ok', () => {})\n")
+  fs.writeFileSync(path.join(folder, 'index.ts'), "export * from './default-component-scene'\n")
+  fs.writeFileSync(path.join(sharedFolder, 'scene-frame.tsx'), 'export function SceneFrame() { return null }\n')
+}
+
+describe('scene convention lint', () => {
+  it('passes on the expected folder structure', () => {
+    const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scene-convention-lint-'))
+    writeSceneFixture(rootDir)
+
+    const result = lintSceneConvention({
+      rootDir,
+      sourceRoot: 'src/components',
+      titleRoot: 'components',
+      sharedFolderName: '_shared',
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.checkedSceneFolders).toContain('src/components/default-component-scene')
+  })
+
+  it('reports missing animation mode', () => {
+    const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scene-convention-lint-missing-animation-'))
+    writeSceneFixture(rootDir)
+    fs.writeFileSync(
+      path.join(rootDir, 'src/components/default-component-scene/default-component-scene.animated.stories.tsx'),
+      "const meta = { title: 'components/default-component-scene/DefaultComponentSceneLandscape' }\nexport default meta\nexport const Animated = { parameters: { scenePreviewAspectRatio: '16:9' } }\n",
+    )
+
+    const result = lintSceneConvention({
+      rootDir,
+      sourceRoot: 'src/components',
+      titleRoot: 'components',
+      sharedFolderName: '_shared',
+    })
+
+    expect(result.errors.some((error) => error.includes("scenePreviewMode: 'animation'"))).toBe(true)
+  })
+})

package/src/lint/scene-convention-lint.ts

@@ -0,0 +1,247 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export type SceneConventionLintOptions = {
+  rootDir: string
+  sourceRoot: string
+  titleRoot: string
+  checkedFolderPrefix?: string
+  sharedFolderName?: string
+  fix?: boolean
+}
+
+export type SceneConventionLintResult = {
+  checkedSceneFolders: string[]
+  checkedStoryFiles: string[]
+  errors: string[]
+}
+
+const toPosix = (value: string) => value.split(path.sep).join('/')
+
+function toRootRelative(rootDir: string, file: string) {
+  if (path.isAbsolute(file)) {
+    return toPosix(path.relative(rootDir, file))
+  }
+
+  return toPosix(file).replace(/^\.\//, '')
+}
+
+function resolveRootPath(rootDir: string, file: string) {
+  return path.resolve(rootDir, toRootRelative(rootDir, file))
+}
+
+function readText(rootDir: string, file: string) {
+  return fs.readFileSync(resolveRootPath(rootDir, file), 'utf8')
+}
+
+function writeText(rootDir: string, file: string, text: string) {
+  fs.writeFileSync(resolveRootPath(rootDir, file), text)
+}
+
+function readStoryTitle(text: string) {
+  const titleMatch = text.match(/const\s+meta\s*=\s*{[\s\S]*?title:\s*['"`]([^'"`]+)['"`]/m)
+  return titleMatch?.[1] ?? ''
+}
+
+function replaceStoryTitlePrefix(text: string, expectedPrefix: string) {
+  return text.replace(
+    /(const\s+meta\s*=\s*{[\s\S]*?title:\s*['"`])([^'"`]+)(['"`])/m,
+    (_match, before: string, currentTitle: string, after: string) => {
+      const titleLabel = currentTitle.includes('/') ? currentTitle.split('/').filter(Boolean).at(-1) : currentTitle
+      return `${before}${expectedPrefix}${titleLabel}${after}`
+    },
+  )
+}
+
+function collectFiles(rootDir: string, dir: string, suffix: string) {
+  const absoluteDir = resolveRootPath(rootDir, dir)
+  const results: string[] = []
+  const stack = [absoluteDir]
+
+  while (stack.length > 0) {
+    const current = stack.pop()
+    if (!current || !fs.existsSync(current)) {
+      continue
+    }
+
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name)
+      if (entry.isDirectory()) {
+        stack.push(fullPath)
+        continue
+      }
+      if (entry.isFile() && entry.name.endsWith(suffix)) {
+        results.push(toRootRelative(rootDir, fullPath))
+      }
+    }
+  }
+
+  return results.sort()
+}
+
+function collectSceneFolders(options: SceneConventionLintOptions) {
+  const sourceRootPath = resolveRootPath(options.rootDir, options.sourceRoot)
+  const sharedFolderName = options.sharedFolderName ?? '_shared'
+
+  if (!fs.existsSync(sourceRootPath)) {
+    return []
+  }
+
+  return fs
+    .readdirSync(sourceRootPath, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => entry.name !== sharedFolderName)
+    .filter((entry) => !options.checkedFolderPrefix || entry.name.startsWith(options.checkedFolderPrefix))
+    .map((entry) => toRootRelative(options.rootDir, path.join(sourceRootPath, entry.name)))
+    .sort()
+}
+
+function lintSceneFolder(options: SceneConventionLintOptions, folder: string) {
+  const slug = path.posix.basename(folder)
+  const errors: string[] = []
+  const requiredFiles = [
+    `${slug}.tsx`,
+    `${slug}-Landscape.tsx`,
+    `${slug}-Horizontal.tsx`,
+    `${slug}.stories.tsx`,
+    `${slug}.animated.stories.tsx`,
+    `${slug}-Horizontal.stories.tsx`,
+    `${slug}-Horizontal.animated.stories.tsx`,
+    `${slug}.test.tsx`,
+    'index.ts',
+  ]
+
+  for (const fileName of requiredFiles) {
+    const requiredPath = `${folder}/${fileName}`
+    if (!fs.existsSync(resolveRootPath(options.rootDir, requiredPath))) {
+      errors.push(`${folder}: missing ${fileName}`)
+    }
+  }
+
+  const filesToCheck = [
+    `${folder}/${slug}.tsx`,
+    `${folder}/${slug}-Landscape.tsx`,
+    `${folder}/${slug}-Horizontal.tsx`,
+  ]
+
+  for (const file of filesToCheck) {
+    if (!fs.existsSync(resolveRootPath(options.rootDir, file))) {
+      continue
+    }
+
+    const text = readText(options.rootDir, file)
+    const sourceFileMatch = text.match(/sourceFile:\s*['"`]([^'"`]+)['"`]/)
+    if (!sourceFileMatch) {
+      errors.push(`${file}: missing componentMetadata.sourceFile`)
+    } else if (sourceFileMatch[1] !== file) {
+      errors.push(`${file}: sourceFile must be "${file}", got "${sourceFileMatch[1]}"`)
+    }
+  }
+
+  const baseFile = `${folder}/${slug}.tsx`
+  if (fs.existsSync(resolveRootPath(options.rootDir, baseFile))) {
+    const text = readText(options.rootDir, baseFile)
+    if (!/defineSceneComponent\s*\(/.test(text)) {
+      errors.push(`${baseFile}: base scene must use defineSceneComponent(...)`)
+    }
+    if (!/propsSchema:\s*z\.object\s*\(/.test(text)) {
+      errors.push(`${baseFile}: base scene must colocate propsSchema with z.object(...)`)
+    }
+    if (!/useRemotionSceneRuntime\s*\(/.test(text)) {
+      errors.push(`${baseFile}: base scene must use useRemotionSceneRuntime()`)
+    }
+    if (!/SceneMotionLayer|SceneMotionStack|useSceneMotion/.test(text)) {
+      errors.push(`${baseFile}: scene animation must use SceneMotionLayer, SceneMotionStack, or useSceneMotion`)
+    }
+  }
+
+  const landscapeFile = `${folder}/${slug}-Landscape.tsx`
+  if (
+    fs.existsSync(resolveRootPath(options.rootDir, landscapeFile)) &&
+    !/aspectRatio:\s*['"]16:9['"]/.test(readText(options.rootDir, landscapeFile))
+  ) {
+    errors.push(`${landscapeFile}: Landscape variant must set aspectRatio: '16:9'`)
+  }
+
+  const horizontalFile = `${folder}/${slug}-Horizontal.tsx`
+  if (
+    fs.existsSync(resolveRootPath(options.rootDir, horizontalFile)) &&
+    !/aspectRatio:\s*['"]9:16['"]/.test(readText(options.rootDir, horizontalFile))
+  ) {
+    errors.push(`${horizontalFile}: Horizontal variant must set aspectRatio: '9:16'`)
+  }
+
+  return errors
+}
+
+function lintStoryFile(options: SceneConventionLintOptions, storyFile: string) {
+  const normalized = toRootRelative(options.rootDir, storyFile)
+  const text = readText(options.rootDir, normalized)
+  const errors: string[] = []
+  const storyDir = path.posix.dirname(normalized.slice(`${options.sourceRoot}/`.length))
+  const expectedPrefix = `${options.titleRoot}/${storyDir}/`
+  const title = readStoryTitle(text)
+  const isAnimatedStory = normalized.endsWith('.animated.stories.tsx')
+  const isHorizontalStory = /-Horizontal(\.animated)?\.stories\.tsx$/.test(normalized)
+  const isLandscapeStory = !isHorizontalStory
+
+  if (!title.startsWith(expectedPrefix)) {
+    if (options.fix) {
+      writeText(options.rootDir, normalized, replaceStoryTitlePrefix(text, expectedPrefix))
+    } else {
+      errors.push(`${normalized}: story title must start with "${expectedPrefix}"`)
+    }
+  }
+
+  if (isAnimatedStory && !/scenePreviewMode:\s*['"]animation['"]/.test(text)) {
+    errors.push(`${normalized}: animated stories must set scenePreviewMode: 'animation'`)
+  }
+
+  if (isLandscapeStory && !/scenePreviewAspectRatio:\s*['"]16:9['"]/.test(text)) {
+    errors.push(`${normalized}: landscape stories must set scenePreviewAspectRatio: '16:9'`)
+  }
+
+  if (isHorizontalStory && !/scenePreviewAspectRatio:\s*['"]9:16['"]/.test(text)) {
+    errors.push(`${normalized}: horizontal stories must set scenePreviewAspectRatio: '9:16'`)
+  }
+
+  return errors
+}
+
+function lintSharedFolder(options: SceneConventionLintOptions) {
+  const sharedFolderName = options.sharedFolderName ?? '_shared'
+  const sharedRoot = `${options.sourceRoot}/${sharedFolderName}`
+  const sharedRootPath = resolveRootPath(options.rootDir, sharedRoot)
+  const errors: string[] = []
+
+  if (!fs.existsSync(sharedRootPath)) {
+    return errors
+  }
+
+  for (const file of collectFiles(options.rootDir, sharedRoot, '.tsx')) {
+    const text = readText(options.rootDir, file)
+    if (/componentMetadata|defineComponentProjectComponentMetadata|defineScenePluginMetadata/.test(text)) {
+      errors.push(`${file}: shared files must not declare publishable component metadata`)
+    }
+  }
+
+  return errors
+}
+
+export function lintSceneConvention(options: SceneConventionLintOptions): SceneConventionLintResult {
+  const sceneFolders = collectSceneFolders(options)
+  const storyFiles = collectFiles(options.rootDir, options.sourceRoot, '.stories.tsx').filter(
+    (file) => !file.includes(`/${options.sharedFolderName ?? '_shared'}/`),
+  )
+  const errors = [
+    ...sceneFolders.flatMap((folder) => lintSceneFolder(options, folder)),
+    ...storyFiles.flatMap((file) => lintStoryFile(options, file)),
+    ...lintSharedFolder(options),
+  ]
+
+  return {
+    checkedSceneFolders: sceneFolders,
+    checkedStoryFiles: storyFiles,
+    errors,
+  }
+}

package/src/storybook/index.ts

@@ -0,0 +1,19 @@
+export { SceneViewport } from './SceneViewport'
+export { createSceneStoryVariants } from './scene-story'
+export {
+  AbsoluteFill,
+  Audio,
+  Easing,
+  HtmlInCanvas,
+  Img,
+  RemotionPreviewProvider,
+  Sequence,
+  interpolate,
+  isHtmlInCanvasSupported,
+  random,
+  spring,
+  staticFile,
+  useCurrentFrame,
+  useVideoConfig,
+} from './remotion-preview'
+export type { RemotionPreviewValue } from './remotion-preview'

package/src/storybook/remotion-preview.test.tsx

@@ -0,0 +1,53 @@
+import { render } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import {
+  AbsoluteFill,
+  Easing,
+  Img,
+  RemotionPreviewProvider,
+  Sequence,
+  interpolate,
+  random,
+  spring,
+  staticFile,
+  useCurrentFrame,
+  useVideoConfig,
+} from './remotion-preview'
+
+describe('storybook remotion preview shim', () => {
+  it('exports spring, interpolate and helpers', () => {
+    expect(spring({ frame: 30, fps: 30 })).toBeGreaterThan(0)
+    expect(interpolate(0.5, [0, 1], [10, 20])).toBe(15)
+    expect(random('seed')).toBeGreaterThanOrEqual(0)
+    expect(staticFile('/foo.png')).toBe('/foo.png')
+    expect(Easing.linear(0.5)).toBe(0.5)
+    expect(AbsoluteFill).toBeTypeOf('function')
+    expect(Sequence).toBeTypeOf('function')
+    expect(Img).toBeTypeOf('function')
+  })
+
+  it('provides frame and video config through the provider', () => {
+    const Probe = () => {
+      const frame = useCurrentFrame()
+      const config = useVideoConfig()
+      return (
+        <div>
+          frame:{frame}
+          width:{config.width}
+          height:{config.height}
+        </div>
+      )
+    }
+
+    const { getByText } = render(
+      <RemotionPreviewProvider value={{ frame: 12, fps: 30, width: 720, height: 1280, durationInFrames: 150 }}>
+        <Probe />
+      </RemotionPreviewProvider>,
+    )
+
+    expect(getByText(/frame:12/)).toBeTruthy()
+    expect(getByText(/width:720/)).toBeTruthy()
+    expect(getByText(/height:1280/)).toBeTruthy()
+  })
+})

package/src/storybook/remotion-preview.tsx

@@ -1,7 +1,7 @@
 import type { CSSProperties, ReactNode } from 'react'
 import { createContext, useContext } from 'react'
 
-type RemotionPreviewValue = {
+export type RemotionPreviewValue = {
   frame: number
   fps: number
   width: number
@@ -60,9 +60,9 @@ type SpringConfig = {
   delay?: number
 }
 
-function clamp01(value: number) {
-  if (value < 0) return 0
-  if (value > 1) return 1
+function clamp(value: number, min: number, max: number) {
+  if (value < min) return min
+  if (value > max) return max
   return value
 }
 
@@ -84,19 +84,13 @@ export function spring({
   const eased = 1 - Math.exp(-progress * (damping / Math.max(0.001, mass)))
   const wobble = Math.sin(progress * Math.PI * (stiffness / 55)) * 0.015
 
-  return clamp01(eased + wobble)
+  return clamp(eased + wobble, 0, 1)
 }
 
 type Extrapolate = 'clamp' | 'extend' | 'identity'
 
 type EasingFunction = (value: number) => number
 
-function clamp(value: number, min: number, max: number) {
-  if (value < min) return min
-  if (value > max) return max
-  return value
-}
-
 function wrapInOut(easing: EasingFunction): EasingFunction {
   return (value) => {
     if (value <= 0.5) {
@@ -197,6 +191,22 @@ export function Img({
   return <img {...rest} src={src} alt={alt} style={style} />
 }
 
+export function Audio({
+  src,
+  volume,
+  style,
+  ...rest
+}: {
+  src: string
+  volume?: number | ((frame: number) => number)
+  style?: CSSProperties
+  [key: string]: unknown
+}) {
+  void volume
+
+  return <audio {...rest} src={src} style={style} />
+}
+
 export const HTML_IN_CANVAS_UNSUPPORTED_MESSAGE =
   'HtmlInCanvas is not available in Storybook preview, falling back to the DOM renderer.'
 
@@ -216,10 +226,7 @@ type HtmlInCanvasProps = {
   style?: CSSProperties
 }
 
-function HtmlInCanvasFallback({
-  children,
-  style,
-}: HtmlInCanvasProps) {
+function HtmlInCanvasFallback({ children, style }: HtmlInCanvasProps) {
   return (
     <div
       style={{
@@ -264,3 +271,26 @@ export function AbsoluteFill({
     </div>
   )
 }
+
+export function Sequence({
+  children,
+}: {
+  from?: number
+  durationInFrames?: number
+  children?: ReactNode
+}) {
+  return <>{children}</>
+}
+
+export function random(seed?: string | number) {
+  const value = String(seed ?? 0)
+  let hash = 0
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 31 + value.charCodeAt(index)) >>> 0
+  }
+  return (hash % 10000) / 10000
+}
+
+export function staticFile(path: string) {
+  return path
+}