@vibecuting/video-project-core 0.1.16 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecuting/video-project-core",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "main": "src/index.ts",
@@ -14,12 +14,14 @@
   },
   "scripts": {
     "lint": "node ../../../scripts/run-eslint.mjs .",
-    "typecheck": "node ../../../node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
-    "test": "node ../../../node_modules/vitest/vitest.mjs run"
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run"
   },
   "dependencies": {
-    "@vibecuting/component-project-helper": "0.1.16",
-    "react": "^19.0.0"
+    "@vibecuting/component-project-helper": "0.1.18",
+    "@remotion/transitions": "4.0.473",
+    "react": "^19.0.0",
+    "zod": "4.1.12"
   },
   "peerDependencies": {
     "remotion": "^4.0.0"
@@ -27,6 +29,10 @@
   "devDependencies": {
     "@types/react": "18.2.20",
     "@types/react-dom": "18.2.7",
-    "remotion": "4.0.473"
+    "remotion": "4.0.473",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.0",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@types/node": "20.12.2"
   }
 }

package/src/composer/index.ts

@@ -0,0 +1,2 @@
+export * from './resolve-video-plugin-timeline'
+export * from './video-plugin-composer'

package/src/composer/resolve-video-plugin-timeline.ts

@@ -0,0 +1,103 @@
+import type { SceneThemeRegistry } from '../themes'
+import type { SceneTheme } from '../themes'
+import type { DefaultSceneProps } from '../scenes/default-scene-props'
+import type { ScenePluginRegistryEntry } from '../plugins/scene-component'
+import type { TransitionPlugin } from '../transitions/transition-plugin'
+
+export type VideoSceneSelection = {
+  id: string
+  chapterId: string
+  pluginKey: string
+  durationInFrames: number
+  themePreset?: string
+  props: unknown
+}
+
+export type VideoBoundarySelection = {
+  afterSceneId: string
+  pluginKey: string
+  props: unknown
+}
+
+export type ResolvedVideoTimeline = {
+  durationInFrames: number
+  scenes: Array<{
+    id: string
+    chapterId: string
+    durationInFrames: number
+    pluginKey: string
+    props: unknown
+    theme?: SceneTheme
+    plugin: ScenePluginRegistryEntry<DefaultSceneProps>
+  }>
+  boundaries: Array<{
+    afterSceneId: string
+    pluginKey: string
+    props: unknown
+    plugin: TransitionPlugin<unknown>
+  }>
+}
+
+export type ResolveVideoPluginTimelineInput = {
+  fps: number
+  scenes: VideoSceneSelection[]
+  boundaries: VideoBoundarySelection[]
+  scenePluginRegistry: { get(key: string): ScenePluginRegistryEntry<DefaultSceneProps> }
+  transitionPluginRegistry: { get(key: string): TransitionPlugin<unknown> }
+  sceneThemeRegistry: SceneThemeRegistry
+}
+
+export function resolveVideoPluginTimeline(
+  input: ResolveVideoPluginTimelineInput,
+): ResolvedVideoTimeline {
+  const scenes = input.scenes.map((scene) => ({
+    ...scene,
+    plugin: input.scenePluginRegistry.get(scene.pluginKey),
+    theme: scene.themePreset ? input.sceneThemeRegistry.get(scene.themePreset) : undefined,
+  }))
+
+  const boundaries = input.boundaries.map((boundary) => ({
+    ...boundary,
+    plugin: input.transitionPluginRegistry.get(boundary.pluginKey),
+  }))
+
+  const boundaryBySceneId = new Map<string, typeof boundaries[number]>()
+  for (const boundary of boundaries) {
+    if (boundaryBySceneId.has(boundary.afterSceneId)) {
+      throw new Error(`duplicate boundary after scene: ${boundary.afterSceneId}`)
+    }
+    boundaryBySceneId.set(boundary.afterSceneId, boundary)
+  }
+
+  let durationInFrames = 0
+  scenes.forEach((scene, index) => {
+    const boundary = boundaryBySceneId.get(scene.id)
+    durationInFrames += scene.durationInFrames
+
+    if (!boundary) {
+      return
+    }
+
+    const boundaryDuration = boundary.plugin.getBoundaryDurationInFrames(boundary.props, input.fps)
+    const overlap = boundary.plugin.getTimelineOverlapInFrames(boundary.props, input.fps)
+
+    if (boundary.plugin.kind === 'transition') {
+      durationInFrames -= overlap
+    }
+
+    if (index === scenes.length - 1) {
+      throw new Error(`boundary cannot follow last scene: ${scene.id}`)
+    }
+
+    const nextScene = scenes[index + 1]
+    if (boundaryDuration > scene.durationInFrames || boundaryDuration > nextScene.durationInFrames) {
+      throw new Error(`transition duration exceeds adjacent scenes: ${boundary.afterSceneId}`)
+    }
+  })
+
+  return {
+    durationInFrames,
+    scenes,
+    boundaries,
+  }
+}

package/src/composer/video-plugin-composer.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react'
+import { createElement, Fragment } from 'react'
+
+import type { ResolvedVideoTimeline } from './resolve-video-plugin-timeline'
+
+type TransitionSeriesProps = {
+  children: ReactNode
+}
+
+type TransitionSeriesSequenceProps = {
+  durationInFrames: number
+  premountFor?: number
+  children: ReactNode
+}
+
+type TransitionSeriesBoundaryProps = {
+  children?: ReactNode
+}
+
+function TransitionSeries({ children }: TransitionSeriesProps) {
+  return createElement(Fragment, null, children)
+}
+
+TransitionSeries.Sequence = function TransitionSeriesSequence({
+  children,
+}: TransitionSeriesSequenceProps) {
+  return createElement(Fragment, null, children)
+}
+
+TransitionSeries.Transition = function TransitionSeriesBoundary({
+  children,
+}: TransitionSeriesBoundaryProps) {
+  return createElement(Fragment, null, children)
+}
+
+export function VideoPluginComposer({
+  timeline,
+}: {
+  timeline: ResolvedVideoTimeline
+}) {
+  return (
+    <TransitionSeries>
+      {timeline.scenes.map((scene) => (
+        <TransitionSeries.Sequence
+          key={scene.id}
+          durationInFrames={scene.durationInFrames}
+          premountFor={Math.min(30, scene.durationInFrames)}
+        >
+          {scene.plugin.render(scene.props)}
+        </TransitionSeries.Sequence>
+      ))}
+    </TransitionSeries>
+  )
+}

package/src/core/scene/2dscene/default-2d-scene.tsx

@@ -1,52 +1,76 @@
-import {
-  BaseRemotionScene,
-  type BaseRemotionSceneProps,
-  useRemotionSceneRuntime,
-} from '../../../base'
-import {
-  VideoComponent,
-  defineComponentProjectComponentMetadata,
-} from '@vibecuting/component-project-helper'
+import { AbsoluteFill } from 'remotion'
+import { z } from 'zod'
 
-export interface Default2DSceneProps extends BaseRemotionSceneProps {
+import { VideoComponent, defineScenePluginMetadata } from '@vibecuting/component-project-helper'
+
+import { defineSceneComponent } from '../../../plugins/scene-component'
+import { useRemotionSceneRuntime } from '../../../base'
+import { useSceneRootProps } from '../../../runtime/use-scene-root-props'
+
+export interface Default2DSceneProps {
+  sceneId?: string
+  sceneName?: string
   title: string
   subtitle?: string
 }
 
-export const componentMetadata = defineComponentProjectComponentMetadata({
+export const componentMetadata = defineScenePluginMetadata({
+  resourceKind: 'scene',
   name: 'Default2DScene',
   description: 'Default remotion 2D scene',
   sourceFile: 'src/core/scene/2dscene/default-2d-scene.tsx',
+  pluginKey: 'core.canvas-2d',
+  tags: ['scene', '2d'],
   aspectRatio: '16:9',
   sceneType: 'scene',
-  tags: ['scene', '2d'],
+  sceneFamily: 'canvas-2d',
+  rootLayout: 'absolute-fill',
   propsTypeName: 'Default2DSceneProps',
 })
 
-export function Default2DScene({ id, name, title, subtitle }: Default2DSceneProps) {
-  const runtime = useRemotionSceneRuntime()
-  const titleFontSize = Math.round(runtime.height * 0.062)
-  const subtitleFontSize = Math.round(runtime.height * 0.024)
-
-  return (
-    <BaseRemotionScene
-      id={id}
-      name={name}
-      style={{
-        backgroundColor: '#111827',
-        color: '#f8fafc',
-        display: 'flex',
-        alignItems: 'center',
-        justifyContent: 'flex-start',
-        padding: Math.round(runtime.height * 0.06),
-      }}
-    >
-      <div style={{ width: '100%', maxWidth: Math.round(runtime.width * 0.72) }}>
-        <h1 style={{ margin: 0, fontSize: titleFontSize, lineHeight: 1.05 }}>{title}</h1>
-        {subtitle ? <p style={{ margin: '16px 0 0', fontSize: subtitleFontSize }}>{subtitle}</p> : null}
-      </div>
-    </BaseRemotionScene>
-  )
-}
+export const Default2DScene = VideoComponent(componentMetadata)(
+  defineSceneComponent({
+    family: 'canvas-2d',
+    propsSchema: z.object({
+      sceneId: z.string().optional(),
+      sceneName: z.string().optional(),
+      title: z.string().min(1),
+      subtitle: z.string().optional(),
+    }),
+    component: function Default2DScene({
+      sceneId,
+      sceneName,
+      title,
+      subtitle,
+    }: Default2DSceneProps) {
+      const runtime = useRemotionSceneRuntime()
+      const rootProps = useSceneRootProps({
+        pluginKey: componentMetadata.pluginKey,
+        sceneId,
+        sceneName: sceneName ?? title,
+      })
+      const titleFontSize = Math.round(runtime.height * 0.062)
+      const subtitleFontSize = Math.round(runtime.height * 0.024)
 
-VideoComponent(componentMetadata)(Default2DScene)
+      return (
+        <AbsoluteFill
+          {...rootProps}
+          style={{
+            ...rootProps.style,
+            backgroundColor: '#111827',
+            color: '#f8fafc',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'flex-start',
+            padding: Math.round(runtime.height * 0.06),
+          }}
+        >
+          <div style={{ width: '100%', maxWidth: Math.round(runtime.width * 0.72) }}>
+            <h1 style={{ margin: 0, fontSize: titleFontSize, lineHeight: 1.05 }}>{title}</h1>
+            {subtitle ? <p style={{ margin: '16px 0 0', fontSize: subtitleFontSize }}>{subtitle}</p> : null}
+          </div>
+        </AbsoluteFill>
+      )
+    },
+  }),
+)

package/src/core/scene/3dscene/default-3d-scene.tsx

@@ -1,54 +1,78 @@
-import {
-  BaseRemotionScene,
-  type BaseRemotionSceneProps,
-  useRemotionSceneRuntime,
-} from '../../../base'
-import {
-  VideoComponent,
-  defineComponentProjectComponentMetadata,
-} from '@vibecuting/component-project-helper'
+import { AbsoluteFill } from 'remotion'
+import { z } from 'zod'
 
-export interface Default3DSceneProps extends BaseRemotionSceneProps {
+import { VideoComponent, defineScenePluginMetadata } from '@vibecuting/component-project-helper'
+
+import { defineSceneComponent } from '../../../plugins/scene-component'
+import { useRemotionSceneRuntime } from '../../../base'
+import { useSceneRootProps } from '../../../runtime/use-scene-root-props'
+
+export interface Default3DSceneProps {
+  sceneId?: string
+  sceneName?: string
   title: string
   depth?: number
 }
 
-export const componentMetadata = defineComponentProjectComponentMetadata({
+export const componentMetadata = defineScenePluginMetadata({
+  resourceKind: 'scene',
   name: 'Default3DScene',
   description: 'Default remotion 3D scene',
   sourceFile: 'src/core/scene/3dscene/default-3d-scene.tsx',
+  pluginKey: 'core.three-3d',
+  tags: ['scene', '3d'],
   aspectRatio: '16:9',
   sceneType: 'scene',
-  tags: ['scene', '3d'],
+  sceneFamily: 'three-3d',
+  rootLayout: 'absolute-fill',
   propsTypeName: 'Default3DSceneProps',
 })
 
-export function Default3DScene({ id, name, title, depth = 240 }: Default3DSceneProps) {
-  const runtime = useRemotionSceneRuntime()
-  const titleFontSize = Math.round(runtime.height * 0.062)
-
-  return (
-    <BaseRemotionScene
-      id={id}
-      name={name}
-      style={{
-        backgroundColor: '#020617',
-        color: '#e2e8f0',
-        display: 'flex',
-        alignItems: 'center',
-        justifyContent: 'flex-start',
-        padding: Math.round(runtime.height * 0.06),
-        perspective: 1200,
-      }}
-    >
-      <div style={{ transform: `translateZ(${depth / 8}px) rotateY(-18deg)` }}>
-        <h1 style={{ margin: 0, fontSize: titleFontSize, lineHeight: 1.05 }}>{title}</h1>
-        <p style={{ margin: '16px 0 0', fontSize: Math.round(runtime.height * 0.024), opacity: 0.8 }}>
-          Depth {depth}
-        </p>
-      </div>
-    </BaseRemotionScene>
-  )
-}
+export const Default3DScene = VideoComponent(componentMetadata)(
+  defineSceneComponent({
+    family: 'three-3d',
+    propsSchema: z.object({
+      sceneId: z.string().optional(),
+      sceneName: z.string().optional(),
+      title: z.string().min(1),
+      depth: z.number().optional(),
+    }),
+    component: function Default3DScene({
+      sceneId,
+      sceneName,
+      title,
+      depth = 240,
+    }: Default3DSceneProps) {
+      const runtime = useRemotionSceneRuntime()
+      const rootProps = useSceneRootProps({
+        pluginKey: componentMetadata.pluginKey,
+        sceneId,
+        sceneName: sceneName ?? title,
+      })
+      const titleFontSize = Math.round(runtime.height * 0.062)
 
-VideoComponent(componentMetadata)(Default3DScene)
+      return (
+        <AbsoluteFill
+          {...rootProps}
+          style={{
+            ...rootProps.style,
+            backgroundColor: '#020617',
+            color: '#e2e8f0',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'flex-start',
+            padding: Math.round(runtime.height * 0.06),
+            perspective: 1200,
+          }}
+        >
+          <div style={{ transform: `translateZ(${depth / 8}px) rotateY(-18deg)` }}>
+            <h1 style={{ margin: 0, fontSize: titleFontSize, lineHeight: 1.05 }}>{title}</h1>
+            <p style={{ margin: '16px 0 0', fontSize: Math.round(runtime.height * 0.024), opacity: 0.8 }}>
+              Depth {depth}
+            </p>
+          </div>
+        </AbsoluteFill>
+      )
+    },
+  }),
+)

package/src/core/scene/slide/default-slide-scene.tsx

@@ -1,51 +1,75 @@
-import {
-  BaseRemotionScene,
-  type BaseRemotionSceneProps,
-  useRemotionSceneRuntime,
-} from '../../../base'
-import {
-  VideoComponent,
-  defineComponentProjectComponentMetadata,
-} from '@vibecuting/component-project-helper'
+import { AbsoluteFill } from 'remotion'
+import { z } from 'zod'
 
-export interface DefaultSlideSceneProps extends BaseRemotionSceneProps {
+import { VideoComponent, defineScenePluginMetadata } from '@vibecuting/component-project-helper'
+
+import { defineSceneComponent } from '../../../plugins/scene-component'
+import { useRemotionSceneRuntime } from '../../../base'
+import { useSceneRootProps } from '../../../runtime/use-scene-root-props'
+
+export interface DefaultSlideSceneProps {
+  sceneId?: string
+  sceneName?: string
   title: string
   body?: string
 }
 
-export const componentMetadata = defineComponentProjectComponentMetadata({
+export const componentMetadata = defineScenePluginMetadata({
+  resourceKind: 'scene',
   name: 'DefaultSlideScene',
   description: 'Default remotion slide scene',
   sourceFile: 'src/core/scene/slide/default-slide-scene.tsx',
+  pluginKey: 'core.slide',
+  tags: ['scene', 'slide'],
   aspectRatio: '16:9',
   sceneType: 'scene',
-  tags: ['scene', 'slide'],
+  sceneFamily: 'slide',
+  rootLayout: 'absolute-fill',
   propsTypeName: 'DefaultSlideSceneProps',
 })
 
-export function DefaultSlideScene({ id, name, title, body }: DefaultSlideSceneProps) {
-  const runtime = useRemotionSceneRuntime()
-  const titleFontSize = Math.round(runtime.height * 0.062)
-
-  return (
-    <BaseRemotionScene
-      id={id}
-      name={name}
-      style={{
-        backgroundColor: '#f8fafc',
-        color: '#0f172a',
-        display: 'flex',
-        alignItems: 'flex-start',
-        justifyContent: 'flex-start',
-        padding: Math.round(runtime.height * 0.06),
-      }}
-    >
-      <aside style={{ maxWidth: Math.round(runtime.width * 0.72) }}>
-        <h1 style={{ margin: 0, fontSize: titleFontSize, lineHeight: 1.05 }}>{title}</h1>
-        {body ? <p style={{ margin: '16px 0 0', fontSize: Math.round(runtime.height * 0.024) }}>{body}</p> : null}
-      </aside>
-    </BaseRemotionScene>
-  )
-}
+export const DefaultSlideScene = VideoComponent(componentMetadata)(
+  defineSceneComponent({
+    family: 'slide',
+    propsSchema: z.object({
+      sceneId: z.string().optional(),
+      sceneName: z.string().optional(),
+      title: z.string().min(1),
+      body: z.string().optional(),
+    }),
+    component: function DefaultSlideScene({
+      sceneId,
+      sceneName,
+      title,
+      body,
+    }: DefaultSlideSceneProps) {
+      const runtime = useRemotionSceneRuntime()
+      const rootProps = useSceneRootProps({
+        pluginKey: componentMetadata.pluginKey,
+        sceneId,
+        sceneName: sceneName ?? title,
+      })
+      const titleFontSize = Math.round(runtime.height * 0.062)
 
-VideoComponent(componentMetadata)(DefaultSlideScene)
+      return (
+        <AbsoluteFill
+          {...rootProps}
+          style={{
+            ...rootProps.style,
+            backgroundColor: '#f8fafc',
+            color: '#0f172a',
+            display: 'flex',
+            alignItems: 'flex-start',
+            justifyContent: 'flex-start',
+            padding: Math.round(runtime.height * 0.06),
+          }}
+        >
+          <aside style={{ maxWidth: Math.round(runtime.width * 0.72) }}>
+            <h1 style={{ margin: 0, fontSize: titleFontSize, lineHeight: 1.05 }}>{title}</h1>
+            {body ? <p style={{ margin: '16px 0 0', fontSize: Math.round(runtime.height * 0.024) }}>{body}</p> : null}
+          </aside>
+        </AbsoluteFill>
+      )
+    },
+  }),
+)

package/src/index.ts

@@ -1,2 +1,9 @@
-export * from './core';
-export * from './base';
+export * from './base'
+export * from './core'
+export * from './composer'
+export * from './layouts'
+export * from './plugins/scene-component'
+export * from './plugins/scene-plugin-registry'
+export * from './scenes'
+export * from './themes'
+export * from './transitions'

package/src/layouts/SceneSlots.tsx

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react'
+
+export type SceneSlotsProps = {
+  header?: ReactNode
+  body?: ReactNode
+  footer?: ReactNode
+  debug?: ReactNode
+}
+
+export function SceneSlots({ header, body, footer, debug }: SceneSlotsProps) {
+  return (
+    <>
+      {header}
+      {body}
+      {footer}
+      {debug}
+    </>
+  )
+}

package/src/layouts/index.ts

@@ -0,0 +1 @@
+export * from './SceneSlots'

package/src/plugins/scene-component.tsx

@@ -0,0 +1,111 @@
+import type { ComponentType, ReactElement } from 'react'
+import { createElement } from 'react'
+import { z } from 'zod'
+
+import {
+  VideoComponent,
+  defineScenePluginMetadata,
+  getScenePluginMetadata,
+  type ScenePluginMetadata,
+} from '@vibecuting/component-project-helper'
+
+import type { DefaultSceneProps } from '../scenes/default-scene-props'
+
+export type SceneFamily = 'slide' | 'canvas-2d' | 'game-2d' | 'three-3d' | 'custom'
+
+export type SceneComponentDefinition<TProps> = {
+  family: SceneFamily
+  propsSchema: z.ZodType<TProps>
+  component: ComponentType<TProps>
+}
+
+export const SCENE_COMPONENT_DEFINITION_KEY = Symbol.for(
+  '@vibecuting/video-project-core/scene-component-definition',
+)
+
+export type RegisteredSceneComponent<TProps extends DefaultSceneProps> = ComponentType<TProps> & {
+  readonly [SCENE_COMPONENT_DEFINITION_KEY]: SceneComponentDefinition<TProps>
+}
+
+export function defineSceneComponent<TProps extends DefaultSceneProps>(
+  definition: SceneComponentDefinition<TProps>,
+): RegisteredSceneComponent<TProps> {
+  const component = definition.component as RegisteredSceneComponent<TProps>
+  Object.defineProperty(component, SCENE_COMPONENT_DEFINITION_KEY, {
+    value: definition,
+    enumerable: false,
+  })
+  return component
+}
+
+export type ScenePluginRegistryEntry<TProps extends DefaultSceneProps> = {
+  key: string
+  family: SceneFamily
+  metadata: ScenePluginMetadata
+  component: RegisteredSceneComponent<TProps>
+  parseProps(input: unknown): TProps
+  render(input: unknown): ReactElement
+}
+
+export function createScenePluginRegistry<TProps extends DefaultSceneProps>(
+  plugins: readonly RegisteredSceneComponent<TProps>[],
+) {
+  const entries = new Map<string, ScenePluginRegistryEntry<TProps>>()
+
+  for (const component of plugins) {
+    const metadata = getScenePluginMetadata(component)
+    if (!metadata) {
+      throw new Error(`scene plugin is missing VideoComponent annotation: ${component.name}`)
+    }
+
+    const definition = component[SCENE_COMPONENT_DEFINITION_KEY]
+    if (!definition) {
+      throw new Error(`scene plugin is missing scene definition: ${component.name}`)
+    }
+
+    if (definition.family !== metadata.sceneFamily) {
+      throw new Error(`scene family mismatch: ${metadata.pluginKey}`)
+    }
+
+    if (entries.has(metadata.pluginKey)) {
+      throw new Error(`duplicate scene plugin key: ${metadata.pluginKey}`)
+    }
+
+    entries.set(metadata.pluginKey, {
+      key: metadata.pluginKey,
+      family: definition.family,
+      metadata,
+      component,
+      parseProps(input) {
+        return definition.propsSchema.parse(input) as TProps
+      },
+      render(input) {
+        return createElement(component, definition.propsSchema.parse(input) as TProps)
+      },
+    })
+  }
+
+  return {
+    get(key: string) {
+      const entry = entries.get(key)
+      if (!entry) {
+        throw new Error(`unknown scene plugin: ${key}`)
+      }
+      return entry
+    },
+    list() {
+      return [...entries.values()]
+    },
+  }
+}
+
+export function annotateSceneComponent<TProps extends DefaultSceneProps>(
+  metadata: ScenePluginMetadata,
+  component: ComponentType<TProps>,
+) {
+  return VideoComponent(metadata)(component)
+}
+
+export function defineScenePluginMetadataForComponent(metadata: ScenePluginMetadata) {
+  return defineScenePluginMetadata(metadata)
+}

package/src/plugins/scene-plugin-registry.ts

@@ -0,0 +1,11 @@
+export {
+  createScenePluginRegistry,
+  defineSceneComponent,
+  annotateSceneComponent,
+  defineScenePluginMetadataForComponent as defineScenePluginMetadata,
+  SCENE_COMPONENT_DEFINITION_KEY,
+  type RegisteredSceneComponent,
+  type SceneComponentDefinition,
+  type SceneFamily,
+  type ScenePluginRegistryEntry,
+} from './scene-component'

package/src/runtime/use-scene-root-props.ts

@@ -0,0 +1,43 @@
+import type { CSSProperties } from 'react'
+import { useId } from 'react'
+
+import type { SceneTheme, SceneThemeStyle } from '../themes'
+
+export type SceneRootOptions = {
+  pluginKey: string
+  sceneId?: string
+  sceneName?: string
+  theme?: SceneTheme
+  className?: string
+  style?: SceneThemeStyle
+}
+
+export function useSceneRootProps(options: SceneRootOptions): {
+  id: string
+  'data-scene-plugin': string
+  'data-scene-name'?: string
+  className: string
+  style: CSSProperties
+} {
+  const reactId = useId()
+  const id = options.sceneId ?? `${options.pluginKey}-${reactId.replace(/:/g, '')}`
+
+  return {
+    id,
+    'data-scene-plugin': options.pluginKey,
+    'data-scene-name': options.sceneName,
+    className: [
+      'box-border flex h-full w-full flex-col overflow-hidden',
+      'bg-[var(--scene-bg)] text-[var(--scene-fg)]',
+      'px-[var(--scene-page-x)] py-[var(--scene-page-y)]',
+      'gap-[var(--scene-section-gap)]',
+      options.className ?? '',
+    ]
+      .filter(Boolean)
+      .join(' '),
+    style: {
+      ...(options.theme?.variables ?? {}),
+      ...(options.style ?? {}),
+    },
+  }
+}

package/src/scenes/default-scene-props.ts

@@ -0,0 +1,27 @@
+import type { SceneTheme } from '../themes'
+
+export type SceneItem = {
+  title: string
+  description?: string
+  value?: string
+  imageSrc?: string
+}
+
+export type SceneMedia = {
+  type: 'image' | 'video'
+  src: string
+  alt?: string
+}
+
+export type DefaultSceneProps = {
+  sceneId?: string
+  sceneName?: string
+  title?: string
+  subtitle?: string
+  description?: string
+  eyebrow?: string
+  items?: SceneItem[]
+  media?: SceneMedia
+  accent?: string
+  theme?: SceneTheme
+}

package/src/scenes/index.ts

@@ -0,0 +1 @@
+export * from './default-scene-props'

package/src/themes/index.ts

@@ -0,0 +1,3 @@
+export * from './scene-theme'
+export * from './scene-themes'
+export * from './scene-theme-registry'

package/src/themes/scene-theme-registry.ts

@@ -0,0 +1,57 @@
+import { getThemePluginMetadata, type ThemePluginMetadata } from '@vibecuting/component-project-helper'
+
+import type { SceneTheme } from './scene-theme'
+
+export type SceneThemeRegistryEntry = SceneTheme & {
+  metadata: ThemePluginMetadata
+}
+
+export type SceneThemeRegistry = {
+  get(key: string): SceneThemeRegistryEntry
+  list(): SceneThemeRegistryEntry[]
+}
+
+export function createSceneThemeRegistry(themes: readonly SceneTheme[]): SceneThemeRegistry {
+  const entries = new Map<string, SceneThemeRegistryEntry>()
+
+  for (const theme of themes) {
+    const metadata = getThemePluginMetadata(theme)
+    if (!metadata) {
+      throw new Error(`theme is missing ThemeComponent annotation: ${theme.key}`)
+    }
+
+    if (theme.key !== metadata.pluginKey) {
+      throw new Error(`theme key mismatch: ${theme.key}`)
+    }
+
+    if (entries.has(theme.key)) {
+      throw new Error(`duplicate scene theme key: ${theme.key}`)
+    }
+
+    const declaredVariables = [...Object.keys(theme.variables)].sort()
+    const metadataVariables = [...metadata.cssVariables].sort()
+
+    if (declaredVariables.join(',') !== metadataVariables.join(',')) {
+      throw new Error(`theme cssVariables mismatch: ${theme.key}`)
+    }
+
+    entries.set(theme.key, {
+      ...theme,
+      metadata,
+    })
+  }
+
+  return {
+    get(key: string) {
+      const entry = entries.get(key)
+      if (!entry) {
+        throw new Error(`unknown scene theme: ${key}`)
+      }
+
+      return entry
+    },
+    list() {
+      return [...entries.values()]
+    },
+  }
+}

package/src/themes/scene-theme.ts

@@ -0,0 +1,41 @@
+import type { CSSProperties } from 'react'
+
+import {
+  ThemeComponent,
+  defineThemePluginMetadata,
+  type ThemePluginMetadata,
+} from '@vibecuting/component-project-helper'
+
+export type SceneThemeVariables = {
+  '--scene-bg': string
+  '--scene-fg': string
+  '--scene-muted': string
+  '--scene-accent': string
+  '--scene-panel': string
+  '--scene-border': string
+  '--scene-page-x': string
+  '--scene-page-y': string
+  '--scene-content-max': string
+  '--scene-radius': string
+  '--scene-section-gap': string
+}
+
+export type SceneTheme = {
+  key: string
+  name: string
+  variables: SceneThemeVariables
+}
+
+export type SceneThemeStyle = CSSProperties & Partial<SceneThemeVariables>
+
+export function defineSceneTheme(theme: SceneTheme): SceneTheme {
+  return theme
+}
+
+export function annotateSceneTheme(theme: SceneTheme, metadata: ThemePluginMetadata) {
+  return ThemeComponent(metadata)(theme)
+}
+
+export function defineSceneThemeMetadata(input: ThemePluginMetadata): ThemePluginMetadata {
+  return defineThemePluginMetadata(input)
+}

package/src/themes/scene-themes.ts

@@ -0,0 +1,44 @@
+import { ThemeComponent, defineThemePluginMetadata } from '@vibecuting/component-project-helper'
+
+import { defineSceneTheme } from './scene-theme'
+
+export const editorialDarkTheme = ThemeComponent(
+  defineThemePluginMetadata({
+    resourceKind: 'theme',
+    name: 'Editorial Dark',
+    description: 'Default dark theme for slide scenes',
+    sourceFile: 'src/themes/scene-themes.ts',
+    pluginKey: 'core.editorial-dark',
+    supportedSceneFamilies: ['slide', 'custom'],
+    cssVariables: [
+      '--scene-bg',
+      '--scene-fg',
+      '--scene-muted',
+      '--scene-accent',
+      '--scene-panel',
+      '--scene-border',
+      '--scene-page-x',
+      '--scene-page-y',
+      '--scene-content-max',
+      '--scene-radius',
+      '--scene-section-gap',
+    ],
+    tags: ['builtin', 'theme'],
+  }),
+)(defineSceneTheme({
+  key: 'core.editorial-dark',
+  name: 'Editorial Dark',
+  variables: {
+    '--scene-bg': '#020617',
+    '--scene-fg': '#f8fafc',
+    '--scene-muted': '#94a3b8',
+    '--scene-accent': '#38bdf8',
+    '--scene-panel': '#0f172a',
+    '--scene-border': '#1e293b',
+    '--scene-page-x': '64px',
+    '--scene-page-y': '56px',
+    '--scene-content-max': '1200px',
+    '--scene-radius': '24px',
+    '--scene-section-gap': '24px',
+  },
+}))

package/src/transitions/index.ts

@@ -0,0 +1,2 @@
+export * from './transition-plugin'
+export * from './transition-plugin-registry'

package/src/transitions/transition-plugin-registry.ts

@@ -0,0 +1,10 @@
+export {
+  annotateTransitionPlugin,
+  createTransitionPluginRegistry,
+  defineTransitionPlugin,
+  defineTransitionPluginMetadataForPlugin as defineTransitionPluginMetadata,
+  type TransitionPlugin,
+  type TransitionPluginDefinition,
+  type TransitionPluginKind,
+  type TransitionPluginRegistryEntry,
+} from './transition-plugin'

package/src/transitions/transition-plugin.tsx

@@ -0,0 +1,89 @@
+import type { ReactElement } from 'react'
+import { z } from 'zod'
+
+import {
+  TransitionComponent,
+  defineTransitionPluginMetadata,
+  getTransitionPluginMetadata,
+  type TransitionPluginMetadata,
+} from '@vibecuting/component-project-helper'
+
+export type TransitionPluginKind = 'transition' | 'overlay'
+
+export type TransitionPluginDefinition<TProps> = {
+  key: string
+  kind: TransitionPluginKind
+  metadata: TransitionPluginMetadata
+  propsSchema: z.ZodType<TProps>
+  renderBoundary: (props: TProps) => ReactElement
+  getBoundaryDurationInFrames: (props: TProps, fps: number) => number
+  getTimelineOverlapInFrames: (props: TProps, fps: number) => number
+}
+
+export type TransitionPlugin<TProps> = TransitionPluginDefinition<TProps> & {
+  parseProps(input: unknown): TProps
+}
+
+export function defineTransitionPlugin<TProps>(
+  definition: TransitionPluginDefinition<TProps>,
+): TransitionPlugin<TProps> {
+  return {
+    ...definition,
+    parseProps(input) {
+      return definition.propsSchema.parse(input) as TProps
+    },
+  }
+}
+
+export type TransitionPluginRegistryEntry<TProps> = TransitionPlugin<TProps>
+
+export function createTransitionPluginRegistry<TProps>(
+  plugins: readonly TransitionPlugin<TProps>[],
+) {
+  const entries = new Map<string, TransitionPlugin<TProps>>()
+
+  for (const plugin of plugins) {
+    const metadata = getTransitionPluginMetadata(plugin)
+    if (!metadata) {
+      throw new Error(`transition plugin is missing TransitionComponent annotation: ${plugin.key}`)
+    }
+
+    if (plugin.key !== metadata.pluginKey) {
+      throw new Error(`transition plugin key mismatch: ${plugin.key}`)
+    }
+
+    if (plugin.kind !== metadata.transitionKind) {
+      throw new Error(`transition plugin kind mismatch: ${plugin.key}`)
+    }
+
+    if (entries.has(plugin.key)) {
+      throw new Error(`duplicate transition plugin key: ${plugin.key}`)
+    }
+
+    entries.set(plugin.key, plugin)
+  }
+
+  return {
+    get(key: string) {
+      const entry = entries.get(key)
+      if (!entry) {
+        throw new Error(`unknown transition plugin: ${key}`)
+      }
+      return entry
+    },
+    list() {
+      return [...entries.values()]
+    },
+  }
+}
+
+export function annotateTransitionPlugin<TProps>(
+  metadata: TransitionPluginMetadata,
+  plugin: TransitionPlugin<TProps>,
+) {
+  return TransitionComponent(metadata)(plugin)
+}
+
+export function defineTransitionPluginMetadataForPlugin(metadata: TransitionPluginMetadata) {
+  return defineTransitionPluginMetadata(metadata)
+}

package/tsconfig.json

@@ -1,5 +1,8 @@
 {
   "extends": "../../../tsconfig.packages.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": true
+  },
   "include": ["src/**/*.ts", "src/**/*.tsx"],
   "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"]
 }