@vibecuting/video-project-core 0.1.29 → 0.1.31

package/src/core/scene/slide/{default-slide-scene.tsx → default-slide-scene/default-slide-scene.tsx}

@@ -3,10 +3,10 @@ import { z } from 'zod'
 
 import { VideoComponent, defineScenePluginMetadata } from '@vibecuting/component-project-helper'
 
-import { defineSceneComponent } from '../../../plugins/scene-component'
-import { SceneMotionStack } from '../../../base'
-import { useRemotionSceneRuntime } from '../../../base'
-import { useSceneRootProps } from '../../../runtime/use-scene-root-props'
+import { defineSceneComponent } from '../../../../plugins/scene-component'
+import { SceneMotionStack } from '../../../../base'
+import { useRemotionSceneRuntime } from '../../../../base'
+import { useSceneRootProps } from '../../../../runtime/use-scene-root-props'
 
 export interface DefaultSlideSceneProps {
   sceneId?: string
@@ -19,7 +19,7 @@ export const componentMetadata = defineScenePluginMetadata({
   resourceKind: 'scene',
   name: 'DefaultSlideScene',
   description: 'Default remotion slide scene',
-  sourceFile: 'src/core/scene/slide/default-slide-scene.tsx',
+  sourceFile: 'src/core/scene/slide/default-slide-scene/default-slide-scene.tsx',
   pluginKey: 'core.slide',
   tags: ['scene', 'slide'],
   aspectRatio: '16:9',

package/src/core/scene/slide/index.ts

@@ -1,5 +1,5 @@
 export * from './_shared'
-export { DefaultSlideScene } from './default-slide-scene'
+export { DefaultSlideScene } from './default-slide-scene/default-slide-scene'
 
 export { DefaultAbstractBackgroundCoverSlide } from './abstract-background-cover'
 export { DefaultAgendaCardsSlide } from './agenda-cards'
@@ -85,8 +85,8 @@ export { DefaultTimelineCardsSlide } from './timeline-cards'
 export { DefaultTimelineSlide } from './timeline'
 export { DefaultTimelineSplitSlide } from './timeline-split'
 export { DefaultTitleWithImageSlide } from './title-with-image'
-export { DefaultSlideSceneLandscape, componentMetadata as DefaultSlideSceneLandscapeMetadata } from './default-slide-scene-Landscape'
-export { DefaultSlideSceneHorizontal, componentMetadata as DefaultSlideSceneHorizontalMetadata } from './default-slide-scene-Horizontal'
+export { DefaultSlideSceneLandscape, componentMetadata as DefaultSlideSceneLandscapeMetadata } from './default-slide-scene/default-slide-scene-Landscape'
+export { DefaultSlideSceneHorizontal, componentMetadata as DefaultSlideSceneHorizontalMetadata } from './default-slide-scene/default-slide-scene-Horizontal'
 
 const slideSceneMetadata = { sceneFamily: 'slide' as const }
 

package/src/core/scene/video/{default-video-scene-Horizontal.stories.tsx → default-video-scene/default-video-scene-Horizontal.stories.tsx}

@@ -4,7 +4,7 @@ const photoUrl = 'https://heyaai-statics-1342239856.cos.ap-guangzhou.myqcloud.co
 const frame = <img src={photoUrl} alt="Video preview" />
 
 const meta = {
-  title: 'core/scene/video/DefaultVideoSceneHorizontal',
+  title: 'core/scene/video/default-video-scene/DefaultVideoSceneHorizontal',
   component: DefaultVideoSceneHorizontal,
   args: {
     title: 'Launch Cut',

package/src/core/scene/video/{default-video-scene-Horizontal.tsx → default-video-scene/default-video-scene-Horizontal.tsx}

@@ -8,7 +8,7 @@ export const componentMetadata: ScenePluginMetadata = {
   ...baseComponentMetadata,
   name: 'DefaultVideoSceneHorizontal',
   description: 'Video preview scene (Portrait 9:16 variant)',
-  sourceFile: 'src/core/scene/video/default-video-scene-Horizontal.tsx',
+  sourceFile: 'src/core/scene/video/default-video-scene/default-video-scene-Horizontal.tsx',
   aspectRatio: '9:16',
   tags: Array.from(new Set([...(baseComponentMetadata.tags ?? []), 'horizontal'])),
 }

package/src/core/scene/video/{default-video-scene-Landscape.tsx → default-video-scene/default-video-scene-Landscape.tsx}

@@ -8,7 +8,7 @@ export const componentMetadata: ScenePluginMetadata = {
   ...baseComponentMetadata,
   name: 'DefaultVideoSceneLandscape',
   description: 'Video preview scene (Landscape 16:9 variant)',
-  sourceFile: 'src/core/scene/video/default-video-scene-Landscape.tsx',
+  sourceFile: 'src/core/scene/video/default-video-scene/default-video-scene-Landscape.tsx',
   aspectRatio: '16:9',
   tags: Array.from(new Set([...(baseComponentMetadata.tags ?? []), 'landscape'])),
 }

package/src/core/scene/video/{default-video-scene.stories.tsx → default-video-scene/default-video-scene.stories.tsx}

@@ -4,7 +4,7 @@ const photoUrl = 'https://heyaai-statics-1342239856.cos.ap-guangzhou.myqcloud.co
 const frame = <img src={photoUrl} alt="Video preview" />
 
 const meta = {
-  title: 'core/scene/video/DefaultVideoSceneLandscape',
+  title: 'core/scene/video/default-video-scene/DefaultVideoSceneLandscape',
   component: DefaultVideoSceneLandscape,
   args: {
     title: 'Launch Cut',

package/src/core/scene/video/{default-video-scene.tsx → default-video-scene/default-video-scene.tsx}

@@ -6,8 +6,8 @@ import { VideoComponent, defineScenePluginMetadata } from '@vibecuting/component
 import { cloneElement, isValidElement } from 'react'
 import { spring, useCurrentFrame, useVideoConfig } from 'remotion'
 
-import { BaseRemotionScene, SceneMotionLayer, type BaseRemotionSceneProps, useRemotionSceneRuntime, useSceneConfig } from '../../../base'
-import { defineSceneComponent } from '../../../plugins/scene-component'
+import { BaseRemotionScene, SceneMotionLayer, type BaseRemotionSceneProps, useRemotionSceneRuntime, useSceneConfig } from '../../../../base'
+import { defineSceneComponent } from '../../../../plugins/scene-component'
 
 export interface DefaultVideoSceneProps extends BaseRemotionSceneProps {
   sceneId?: string
@@ -29,7 +29,7 @@ export const componentMetadata = defineScenePluginMetadata({
   resourceKind: 'scene',
   name: 'DefaultVideoScene',
   description: 'Video-first scene with poster-led motion and editorial framing',
-  sourceFile: 'src/core/scene/video/default-video-scene.tsx',
+  sourceFile: 'src/core/scene/video/default-video-scene/default-video-scene.tsx',
   pluginKey: 'core.video.preview',
   tags: ['scene', 'video', 'preview', 'player'],
   aspectRatio: '16:9',

package/src/core/scene/video/{default-video-split-scene-Horizontal.tsx → default-video-split-scene/default-video-split-scene-Horizontal.tsx}

@@ -8,7 +8,7 @@ export const componentMetadata: ScenePluginMetadata = {
   ...baseComponentMetadata,
   name: 'DefaultVideoSplitSceneHorizontal',
   description: 'Video split preview scene (Portrait 9:16 variant)',
-  sourceFile: 'src/core/scene/video/default-video-split-scene-Horizontal.tsx',
+  sourceFile: 'src/core/scene/video/default-video-split-scene/default-video-split-scene-Horizontal.tsx',
   aspectRatio: '9:16',
   tags: Array.from(new Set([...(baseComponentMetadata.tags ?? []), 'horizontal'])),
 }

package/src/core/scene/video/{default-video-split-scene-Landscape.tsx → default-video-split-scene/default-video-split-scene-Landscape.tsx}

@@ -8,7 +8,7 @@ export const componentMetadata: ScenePluginMetadata = {
   ...baseComponentMetadata,
   name: 'DefaultVideoSplitSceneLandscape',
   description: 'Video split preview scene (Landscape 16:9 variant)',
-  sourceFile: 'src/core/scene/video/default-video-split-scene-Landscape.tsx',
+  sourceFile: 'src/core/scene/video/default-video-split-scene/default-video-split-scene-Landscape.tsx',
   aspectRatio: '16:9',
   tags: Array.from(new Set([...(baseComponentMetadata.tags ?? []), 'landscape'])),
 }

package/src/core/scene/video/{default-video-split-scene.stories.tsx → default-video-split-scene/default-video-split-scene.stories.tsx}

@@ -22,7 +22,7 @@ const args = {
 }
 
 const meta = {
-  title: 'core/scene/video/DefaultVideoSplitSceneLandscape',
+  title: 'core/scene/video/default-video-split-scene/DefaultVideoSplitSceneLandscape',
   component: DefaultVideoSplitSceneLandscape,
   args,
 }

package/src/core/scene/video/{default-video-split-scene.tsx → default-video-split-scene/default-video-split-scene.tsx}

@@ -2,13 +2,13 @@ import type { ComponentProps } from 'react'
 
 import { VideoComponent, type ScenePluginMetadata } from '@vibecuting/component-project-helper'
 
-import { DefaultVideoScene, componentMetadata as baseComponentMetadata } from './default-video-scene'
+import { DefaultVideoScene, componentMetadata as baseComponentMetadata } from '../default-video-scene/default-video-scene'
 
 export const componentMetadata: ScenePluginMetadata = {
   ...baseComponentMetadata,
   name: 'DefaultVideoSplitScene',
   description: 'Video split preview scene',
-  sourceFile: 'src/core/scene/video/default-video-split-scene.tsx',
+  sourceFile: 'src/core/scene/video/default-video-split-scene/default-video-split-scene.tsx',
   tags: Array.from(new Set([...(baseComponentMetadata.tags ?? []), 'split'])),
 }
 

package/src/core/scene/video/{default-video-wall-scene-Horizontal.tsx → default-video-wall-scene/default-video-wall-scene-Horizontal.tsx}

@@ -8,7 +8,7 @@ export const componentMetadata: ScenePluginMetadata = {
   ...baseComponentMetadata,
   name: 'DefaultVideoWallSceneHorizontal',
   description: 'Video wall preview scene (Portrait 9:16 variant)',
-  sourceFile: 'src/core/scene/video/default-video-wall-scene-Horizontal.tsx',
+  sourceFile: 'src/core/scene/video/default-video-wall-scene/default-video-wall-scene-Horizontal.tsx',
   aspectRatio: '9:16',
   tags: Array.from(new Set([...(baseComponentMetadata.tags ?? []), 'horizontal'])),
 }

package/src/core/scene/video/{default-video-wall-scene-Landscape.tsx → default-video-wall-scene/default-video-wall-scene-Landscape.tsx}

@@ -8,7 +8,7 @@ export const componentMetadata: ScenePluginMetadata = {
   ...baseComponentMetadata,
   name: 'DefaultVideoWallSceneLandscape',
   description: 'Video wall preview scene (Landscape 16:9 variant)',
-  sourceFile: 'src/core/scene/video/default-video-wall-scene-Landscape.tsx',
+  sourceFile: 'src/core/scene/video/default-video-wall-scene/default-video-wall-scene-Landscape.tsx',
   aspectRatio: '16:9',
   tags: Array.from(new Set([...(baseComponentMetadata.tags ?? []), 'landscape'])),
 }

package/src/core/scene/video/{default-video-wall-scene.stories.tsx → default-video-wall-scene/default-video-wall-scene.stories.tsx}

@@ -21,7 +21,7 @@ const args = {
 }
 
 const meta = {
-  title: 'core/scene/video/DefaultVideoWallSceneLandscape',
+  title: 'core/scene/video/default-video-wall-scene/DefaultVideoWallSceneLandscape',
   component: DefaultVideoWallSceneLandscape,
   args,
 }

package/src/core/scene/video/{default-video-wall-scene.tsx → default-video-wall-scene/default-video-wall-scene.tsx}

@@ -2,13 +2,13 @@ import type { ComponentProps } from 'react'
 
 import { VideoComponent, type ScenePluginMetadata } from '@vibecuting/component-project-helper'
 
-import { DefaultVideoScene, componentMetadata as baseComponentMetadata } from './default-video-scene'
+import { DefaultVideoScene, componentMetadata as baseComponentMetadata } from '../default-video-scene/default-video-scene'
 
 export const componentMetadata: ScenePluginMetadata = {
   ...baseComponentMetadata,
   name: 'DefaultVideoWallScene',
   description: 'Video wall preview scene',
-  sourceFile: 'src/core/scene/video/default-video-wall-scene.tsx',
+  sourceFile: 'src/core/scene/video/default-video-wall-scene/default-video-wall-scene.tsx',
   tags: Array.from(new Set([...(baseComponentMetadata.tags ?? []), 'wall', 'multi'])),
 }
 

package/src/core/scene/video/index.ts

@@ -1,9 +1,9 @@
-export { DefaultVideoScene, componentMetadata as DefaultVideoSceneMetadata } from './default-video-scene'
-export { DefaultVideoSceneLandscape, componentMetadata as DefaultVideoSceneLandscapeMetadata } from './default-video-scene-Landscape'
-export { DefaultVideoSceneHorizontal, componentMetadata as DefaultVideoSceneHorizontalMetadata } from './default-video-scene-Horizontal'
-export { DefaultVideoSplitScene, componentMetadata as DefaultVideoSplitSceneMetadata } from './default-video-split-scene'
-export { DefaultVideoSplitSceneLandscape, componentMetadata as DefaultVideoSplitSceneLandscapeMetadata } from './default-video-split-scene-Landscape'
-export { DefaultVideoSplitSceneHorizontal, componentMetadata as DefaultVideoSplitSceneHorizontalMetadata } from './default-video-split-scene-Horizontal'
-export { DefaultVideoWallScene, componentMetadata as DefaultVideoWallSceneMetadata } from './default-video-wall-scene'
-export { DefaultVideoWallSceneLandscape, componentMetadata as DefaultVideoWallSceneLandscapeMetadata } from './default-video-wall-scene-Landscape'
-export { DefaultVideoWallSceneHorizontal, componentMetadata as DefaultVideoWallSceneHorizontalMetadata } from './default-video-wall-scene-Horizontal'
+export { DefaultVideoScene, componentMetadata as DefaultVideoSceneMetadata } from './default-video-scene/default-video-scene'
+export { DefaultVideoSceneLandscape, componentMetadata as DefaultVideoSceneLandscapeMetadata } from './default-video-scene/default-video-scene-Landscape'
+export { DefaultVideoSceneHorizontal, componentMetadata as DefaultVideoSceneHorizontalMetadata } from './default-video-scene/default-video-scene-Horizontal'
+export { DefaultVideoSplitScene, componentMetadata as DefaultVideoSplitSceneMetadata } from './default-video-split-scene/default-video-split-scene'
+export { DefaultVideoSplitSceneLandscape, componentMetadata as DefaultVideoSplitSceneLandscapeMetadata } from './default-video-split-scene/default-video-split-scene-Landscape'
+export { DefaultVideoSplitSceneHorizontal, componentMetadata as DefaultVideoSplitSceneHorizontalMetadata } from './default-video-split-scene/default-video-split-scene-Horizontal'
+export { DefaultVideoWallScene, componentMetadata as DefaultVideoWallSceneMetadata } from './default-video-wall-scene/default-video-wall-scene'
+export { DefaultVideoWallSceneLandscape, componentMetadata as DefaultVideoWallSceneLandscapeMetadata } from './default-video-wall-scene/default-video-wall-scene-Landscape'
+export { DefaultVideoWallSceneHorizontal, componentMetadata as DefaultVideoWallSceneHorizontalMetadata } from './default-video-wall-scene/default-video-wall-scene-Horizontal'

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()
+  })
+})