@vibecuting/video-project-core 0.1.25 → 0.1.27

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

@@ -0,0 +1,365 @@
+import type { ReactNode } from 'react'
+
+import { z } from 'zod'
+
+import { VideoComponent, defineScenePluginMetadata } from '@vibecuting/component-project-helper'
+
+import { defineSceneComponent } from '../../../../plugins/scene-component'
+import { SceneMotionLayer, useRemotionSceneRuntime } from '../../../../base'
+import type { DefaultSceneProps } from '../../../../scenes/default-scene-props'
+import { SlideFrame, getSlideTypographyScale } from '../_shared'
+
+export interface DefaultVideoShowcaseSlideProps extends DefaultSceneProps {
+  title: string
+  subtitle?: string
+  chapter?: string
+  runtimeLabel?: string
+  posterLabel?: string
+  posterCaption?: string
+  notes?: string[]
+  poster?: ReactNode
+}
+
+function VideoPoster({
+  poster,
+  posterLabel,
+  posterCaption,
+  runtimeLabel,
+  chapter,
+  isPortrait,
+  scale,
+}: {
+  poster?: ReactNode
+  posterLabel?: string
+  posterCaption?: string
+  runtimeLabel?: string
+  chapter?: string
+  isPortrait: boolean
+  scale: ReturnType<typeof getSlideTypographyScale>
+}) {
+  return (
+    <div
+      style={{
+        position: 'relative',
+        display: 'grid',
+        placeItems: 'center',
+        width: '100%',
+        minHeight: isPortrait ? 320 : 420,
+        aspectRatio: isPortrait ? '4 / 5' : '16 / 9',
+        overflow: 'hidden',
+        borderRadius: 0,
+        border: '1px solid rgba(148, 163, 184, 0.22)',
+        background: 'linear-gradient(135deg, rgba(15,23,42,0.96) 0%, rgba(30,41,59,0.94) 42%, rgba(37,99,235,0.7) 100%)',
+        boxShadow: '0 24px 60px rgba(15,23,42,0.22)',
+      }}
+    >
+      <div
+        style={{
+          position: 'absolute',
+          inset: 0,
+          background:
+            'radial-gradient(circle at 28% 20%, rgba(96,165,250,0.32), transparent 28%), radial-gradient(circle at 82% 26%, rgba(56,189,248,0.18), transparent 26%), linear-gradient(180deg, rgba(2,6,23,0.12) 0%, rgba(2,6,23,0.7) 100%)',
+        }}
+      />
+      <div
+        style={{
+          position: 'absolute',
+          inset: 16,
+          border: '1px solid rgba(255,255,255,0.12)',
+          pointerEvents: 'none',
+        }}
+      />
+      <div style={{ position: 'relative', zIndex: 1, width: '100%', height: '100%', padding: isPortrait ? 18 : 22, display: 'grid', gridTemplateRows: 'auto 1fr auto', gap: 16 }}>
+        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 12 }}>
+          <div
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              gap: 10,
+              padding: '8px 12px',
+              borderRadius: 0,
+              border: '1px solid rgba(255,255,255,0.16)',
+              background: 'rgba(15,23,42,0.46)',
+              color: '#f8fafc',
+              fontSize: scale.caption,
+              letterSpacing: '0.16em',
+              textTransform: 'uppercase',
+            }}
+          >
+            <span style={{ width: 8, height: 8, background: '#38bdf8', display: 'inline-block' }} />
+            {posterLabel ?? 'Poster'}
+          </div>
+          {runtimeLabel ? (
+            <div
+              style={{
+                display: 'inline-flex',
+                alignItems: 'center',
+                padding: '8px 12px',
+                borderRadius: 0,
+                border: '1px solid rgba(255,255,255,0.16)',
+                background: 'rgba(2,6,23,0.5)',
+                color: '#e2e8f0',
+                fontSize: scale.caption,
+                fontWeight: 600,
+              }}
+            >
+              {runtimeLabel}
+            </div>
+          ) : null}
+        </div>
+
+        <div style={{ display: 'grid', placeItems: 'center', minHeight: 0 }}>
+          {poster ?? (
+            <div style={{ display: 'grid', placeItems: 'center', gap: 14, textAlign: 'center', color: '#e2e8f0' }}>
+              <div
+                style={{
+                  width: isPortrait ? 84 : 96,
+                  height: isPortrait ? 84 : 96,
+                  display: 'grid',
+                  placeItems: 'center',
+                  borderRadius: '999px',
+                  background: 'rgba(15,23,42,0.64)',
+                  border: '1px solid rgba(255,255,255,0.18)',
+                  boxShadow: '0 12px 32px rgba(15,23,42,0.28)',
+                  fontSize: isPortrait ? 28 : 30,
+                }}
+              >
+                ▶
+              </div>
+              <div>
+                <div style={{ fontSize: isPortrait ? scale.body * 0.98 : scale.body, fontWeight: 700, letterSpacing: '-0.02em' }}>{posterLabel ?? 'Video poster'}</div>
+                <div style={{ marginTop: 8, fontSize: scale.caption, letterSpacing: '0.14em', textTransform: 'uppercase', opacity: 0.68 }}>{posterCaption ?? 'Use a frame grab, teaser art, or cover still.'}</div>
+              </div>
+            </div>
+          )}
+        </div>
+
+        <div style={{ display: 'flex', alignItems: 'end', justifyContent: 'space-between', gap: 16, color: '#e2e8f0' }}>
+          <div style={{ maxWidth: '72%' }}>
+            <div style={{ fontSize: scale.caption, letterSpacing: '0.2em', textTransform: 'uppercase', opacity: 0.72 }}>{chapter ?? 'Video showcase'}</div>
+            <div style={{ marginTop: 8, fontSize: isPortrait ? scale.body * 0.92 : scale.body, lineHeight: 1.35, opacity: 0.86 }}>{posterCaption ?? 'Poster-led composition for clips, trailers, and edit reviews.'}</div>
+          </div>
+          <div style={{ fontSize: scale.caption, letterSpacing: '0.18em', textTransform: 'uppercase', opacity: 0.58 }}>Video</div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function VideoNotes({
+  notes,
+  isPortrait,
+  scale,
+}: {
+  notes?: string[]
+  isPortrait: boolean
+  scale: ReturnType<typeof getSlideTypographyScale>
+}) {
+  const list = (notes ?? []).filter(Boolean).slice(0, 5)
+
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gap: isPortrait ? 10 : 12,
+        gridTemplateColumns: isPortrait ? '1fr' : 'repeat(2, minmax(0, 1fr))',
+      }}
+    >
+      {list.length > 0 ? (
+        list.map((note, index) => (
+          <article
+            key={`${index}-${note}`}
+            style={{
+              padding: isPortrait ? '14px 14px 15px' : '15px 16px 16px',
+              borderRadius: 0,
+              border: '1px solid rgba(148,163,184,0.18)',
+              background: 'rgba(15,23,42,0.3)',
+              color: '#e2e8f0',
+              minHeight: isPortrait ? 0 : 96,
+            }}
+          >
+            <div style={{ fontSize: scale.caption, letterSpacing: '0.24em', textTransform: 'uppercase', opacity: 0.58 }}>
+              Note {String(index + 1).padStart(2, '0')}
+            </div>
+            <p style={{ margin: '10px 0 0', fontSize: isPortrait ? scale.body * 0.88 : scale.body * 0.92, lineHeight: 1.45, opacity: 0.94 }}>{note}</p>
+          </article>
+        ))
+      ) : (
+        <article
+          style={{
+            padding: isPortrait ? '14px 14px 15px' : '15px 16px 16px',
+            borderRadius: 0,
+            border: '1px dashed rgba(148,163,184,0.22)',
+            background: 'rgba(15,23,42,0.18)',
+            color: '#cbd5e1',
+          }}
+        >
+          <div style={{ fontSize: scale.caption, letterSpacing: '0.24em', textTransform: 'uppercase', opacity: 0.58 }}>Supporting notes</div>
+          <p style={{ margin: '10px 0 0', fontSize: isPortrait ? scale.body * 0.88 : scale.body * 0.92, lineHeight: 1.45, opacity: 0.86 }}>
+            Add edit notes, chapter cues, or production reminders.
+          </p>
+        </article>
+      )}
+    </div>
+  )
+}
+
+export const componentMetadata = defineScenePluginMetadata({
+  resourceKind: 'scene',
+  name: 'DefaultVideoShowcaseSlide',
+  description: 'Video showcase slide',
+  sourceFile: 'src/core/scene/slide/video-showcase/default-video-showcase-slide.tsx',
+  pluginKey: 'core.slide.video-showcase',
+  tags: ['scene', 'slide', 'video', 'showcase'],
+  aspectRatio: '16:9',
+  sceneType: 'scene',
+  sceneFamily: 'slide',
+  rootLayout: 'absolute-fill',
+  propsTypeName: 'DefaultVideoShowcaseSlideProps',
+})
+
+export const DefaultVideoShowcaseSlide = VideoComponent(componentMetadata)(
+  defineSceneComponent({
+    family: 'slide',
+    propsSchema: z.object({
+      sceneId: z.string().optional(),
+      sceneName: z.string().optional(),
+      title: z.string().min(1),
+      subtitle: z.string().optional(),
+      chapter: z.string().optional(),
+      runtimeLabel: z.string().optional(),
+      posterLabel: z.string().optional(),
+      posterCaption: z.string().optional(),
+      notes: z.array(z.string().min(1)).max(5).optional(),
+      poster: z.any().optional(),
+    }),
+    component: function DefaultVideoShowcaseSlide({
+      sceneId,
+      sceneName,
+      title,
+      subtitle,
+      chapter,
+      runtimeLabel,
+      posterLabel,
+      posterCaption,
+      notes,
+      poster,
+    }: DefaultVideoShowcaseSlideProps) {
+      const runtime = useRemotionSceneRuntime()
+      const isPortrait = runtime.height > runtime.width
+      const scale = getSlideTypographyScale(runtime.height)
+
+      return (
+        <SlideFrame
+          pluginKey={componentMetadata.pluginKey}
+          sceneId={sceneId}
+          sceneName={sceneName ?? title}
+          background="linear-gradient(135deg, #020617 0%, #0f172a 58%, #1d4ed8 100%)"
+        >
+          <section
+            style={{
+              width: '100%',
+              height: '100%',
+              display: 'grid',
+              gridTemplateColumns: isPortrait ? '1fr' : '1.08fr 0.92fr',
+              gap: isPortrait ? 20 : 28,
+              padding: isPortrait ? '40px 28px 42px' : '64px 76px',
+              color: '#e2e8f0',
+              alignItems: 'stretch',
+            }}
+          >
+            <SceneMotionLayer variant="panel">
+              <VideoPoster
+                poster={poster}
+                posterLabel={posterLabel}
+                posterCaption={posterCaption}
+                runtimeLabel={runtimeLabel}
+                chapter={chapter}
+                isPortrait={isPortrait}
+                scale={scale}
+              />
+            </SceneMotionLayer>
+
+            <div style={{ display: 'grid', alignContent: 'start', gap: isPortrait ? 16 : 18, minWidth: 0 }}>
+              <SceneMotionLayer variant="hero-copy">
+                <div
+                  style={{
+                    display: 'inline-flex',
+                    alignItems: 'center',
+                    gap: 10,
+                    padding: '8px 12px',
+                    borderRadius: 0,
+                    border: '1px solid rgba(148,163,184,0.2)',
+                    background: 'rgba(15,23,42,0.42)',
+                    color: '#e2e8f0',
+                    fontSize: scale.caption,
+                    letterSpacing: '0.18em',
+                    textTransform: 'uppercase',
+                    width: 'fit-content',
+                  }}
+                >
+                  <span style={{ width: 8, height: 8, background: '#38bdf8', display: 'inline-block' }} />
+                  {chapter ?? 'Video showcase'}
+                </div>
+              </SceneMotionLayer>
+
+              <SceneMotionLayer variant="hero-title" delayIndex={1}>
+                <h1
+                  style={{
+                    margin: 0,
+                    maxWidth: isPortrait ? 620 : 700,
+                    fontSize: isPortrait ? scale.title * 0.78 : scale.title,
+                    lineHeight: 0.94,
+                    letterSpacing: '-0.06em',
+                  }}
+                >
+                  {title}
+                </h1>
+              </SceneMotionLayer>
+
+              {subtitle ? (
+                <SceneMotionLayer variant="hero-copy" delayIndex={2}>
+                  <p
+                    style={{
+                      margin: 0,
+                      maxWidth: isPortrait ? 620 : 620,
+                      fontSize: isPortrait ? scale.body * 0.92 : scale.body,
+                      lineHeight: 1.52,
+                      opacity: 0.82,
+                    }}
+                  >
+                    {subtitle}
+                  </p>
+                </SceneMotionLayer>
+              ) : null}
+
+              <SceneMotionLayer variant="panel" delayIndex={3}>
+                <div
+                  style={{
+                    display: 'grid',
+                    gridTemplateColumns: 'repeat(2, minmax(0, 1fr))',
+                    gap: 12,
+                    maxWidth: isPortrait ? 620 : 540,
+                  }}
+                >
+                  <article style={{ padding: '14px 16px', borderRadius: 0, border: '1px solid rgba(148,163,184,0.18)', background: 'rgba(15,23,42,0.22)' }}>
+                    <div style={{ fontSize: scale.caption, letterSpacing: '0.24em', textTransform: 'uppercase', opacity: 0.58 }}>Chapter</div>
+                    <div style={{ marginTop: 8, fontSize: isPortrait ? scale.body * 0.9 : scale.body, lineHeight: 1.35, fontWeight: 700 }}>{chapter ?? 'Opening sequence'}</div>
+                  </article>
+                  <article style={{ padding: '14px 16px', borderRadius: 0, border: '1px solid rgba(148,163,184,0.18)', background: 'rgba(15,23,42,0.22)' }}>
+                    <div style={{ fontSize: scale.caption, letterSpacing: '0.24em', textTransform: 'uppercase', opacity: 0.58 }}>Runtime</div>
+                    <div style={{ marginTop: 8, fontSize: isPortrait ? scale.body * 0.9 : scale.body, lineHeight: 1.35, fontWeight: 700 }}>{runtimeLabel ?? '02:34'}</div>
+                  </article>
+                </div>
+              </SceneMotionLayer>
+
+              <SceneMotionLayer variant="panel" delayIndex={4}>
+                <VideoNotes notes={notes} isPortrait={isPortrait} scale={scale} />
+              </SceneMotionLayer>
+            </div>
+          </section>
+        </SlideFrame>
+      )
+    },
+  }),
+)

package/src/core/scene/slide/video-showcase/index.ts

@@ -0,0 +1,5 @@
+export { DefaultVideoShowcaseSlide } from './default-video-showcase-slide'
+export { componentMetadata } from './default-video-showcase-slide'
+export { DefaultVideoShowcaseSlideLandscape, componentMetadata as DefaultVideoShowcaseSlideLandscapeMetadata } from './default-video-showcase-slide-Landscape'
+export { DefaultVideoShowcaseSlideHorizontal, componentMetadata as DefaultVideoShowcaseSlideHorizontalMetadata } from './default-video-showcase-slide-Horizontal'
+export { DefaultVideoShowcaseMultiSlide, componentMetadata as DefaultVideoShowcaseMultiSlideMetadata } from './default-video-showcase-multi-slide'

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

@@ -1,6 +1,7 @@
 import type { CSSProperties } from 'react'
 import { useId } from 'react'
 
+import { useSceneConfig, useResolvedSceneTheme } from '../base'
 import type { SceneTheme, SceneThemeStyle } from '../themes'
 
 export type SceneRootOptions = {
@@ -16,16 +17,23 @@ export function useSceneRootProps(options: SceneRootOptions): {
   id: string
   'data-scene-plugin': string
   'data-scene-name'?: string
+  'data-scene-display-mode': 'static' | 'animation'
+  'data-scene-token'?: string
   className: string
   style: CSSProperties
 } {
   const reactId = useId()
+  const sceneConfig = useSceneConfig()
+  const resolvedTheme = useResolvedSceneTheme()
+  const themeVariables = sceneConfig.sceneToken ? undefined : (options.theme ?? resolvedTheme)
   const id = options.sceneId ?? `${options.pluginKey}-${reactId.replace(/:/g, '')}`
 
   return {
     id,
     'data-scene-plugin': options.pluginKey,
     'data-scene-name': options.sceneName,
+    'data-scene-display-mode': sceneConfig.sceneType,
+    'data-scene-token': sceneConfig.sceneToken,
     className: [
       'box-border flex h-full w-full flex-col overflow-hidden',
       'bg-[var(--scene-bg)] text-[var(--scene-fg)]',
@@ -36,7 +44,7 @@ export function useSceneRootProps(options: SceneRootOptions): {
       .filter(Boolean)
       .join(' '),
     style: {
-      ...(options.theme?.variables ?? {}),
+      ...(themeVariables?.variables ?? {}),
       ...(options.style ?? {}),
     },
   }

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

@@ -20,8 +20,8 @@ export type DefaultSceneProps = {
   subtitle?: string
   description?: string
   eyebrow?: string
-  items?: SceneItem[]
-  media?: SceneMedia
+  items?: unknown[]
+  media?: unknown
   accent?: string
   theme?: SceneTheme
 }

package/src/storybook/SceneViewport.tsx

@@ -0,0 +1,179 @@
+import type { ReactNode } from 'react'
+import { useEffect, useMemo, useState } from 'react'
+
+import { AnimationSceneProvider, DEFAULT_SCENE_IN_FRAMES, StaticSceneProvider } from '../base'
+import { getSceneThemeOption } from './scene-theme-options'
+import { RemotionPreviewProvider } from './remotion-preview'
+
+type PreviewSize = {
+  width: number
+  height: number
+}
+
+type ScenePreviewMode = 'static' | 'animation' | 'both'
+type ScenePreviewAspectRatio = '16:9' | '9:16'
+
+function resolveBasePreviewSize(aspectRatio: ScenePreviewAspectRatio) {
+  return aspectRatio === '9:16'
+    ? { width: 720, height: 1280 }
+    : { width: 1280, height: 720 }
+}
+
+function fitPreviewSize(baseSize: PreviewSize, viewportWidth: number, viewportHeight: number) {
+  const safeWidth = Math.max(320, viewportWidth - 48)
+  const safeHeight = Math.max(240, viewportHeight - 48)
+  const widthScale = safeWidth / baseSize.width
+  const heightScale = safeHeight / baseSize.height
+  const scale = Math.min(1, widthScale, heightScale)
+
+  return {
+    width: Math.max(320, Math.floor(baseSize.width * scale)),
+    height: Math.max(240, Math.floor(baseSize.height * scale)),
+  }
+}
+
+function useViewportSize() {
+  const [viewportSize, setViewportSize] = useState(() => ({
+    width: typeof window === 'undefined' ? 1280 : window.innerWidth,
+    height: typeof window === 'undefined' ? 720 : window.innerHeight,
+  }))
+
+  useEffect(() => {
+    const updateSize = () => {
+      setViewportSize({
+        width: window.innerWidth,
+        height: window.innerHeight,
+      })
+    }
+
+    updateSize()
+    window.addEventListener('resize', updateSize)
+    return () => window.removeEventListener('resize', updateSize)
+  }, [])
+
+  return viewportSize
+}
+
+export function SceneViewport({
+  children,
+  width,
+  height,
+  mode = 'static',
+  aspectRatio = '16:9',
+  themeKey,
+}: {
+  children: ReactNode
+  width: number
+  height: number
+  mode?: ScenePreviewMode
+  aspectRatio?: ScenePreviewAspectRatio
+  themeKey?: string
+}) {
+  const viewportSize = useViewportSize()
+  const sceneTheme = useMemo(() => getSceneThemeOption(themeKey).theme, [themeKey])
+  const baseSize = useMemo(() => resolveBasePreviewSize(aspectRatio), [aspectRatio])
+  const fittedSize = useMemo(
+    () => fitPreviewSize({ width, height }, viewportSize.width, viewportSize.height),
+    [height, viewportSize.height, viewportSize.width, width],
+  )
+  const [animatedFrame, setAnimatedFrame] = useState(0)
+  const frame = mode === 'static' ? 0 : animatedFrame
+
+  useEffect(() => {
+    if (mode === 'static') return undefined
+
+    let raf = 0
+    let start = 0
+    const fps = 30
+
+    const loop = (time: number) => {
+      if (!start) {
+        start = time
+      }
+      const elapsedSeconds = (time - start) / 1000
+      const nextFrame = Math.floor(elapsedSeconds * fps) % DEFAULT_SCENE_IN_FRAMES
+      setAnimatedFrame(nextFrame)
+      raf = window.requestAnimationFrame(loop)
+    }
+
+    raf = window.requestAnimationFrame(loop)
+    return () => window.cancelAnimationFrame(raf)
+  }, [mode])
+
+  const renderScene = (sceneMode: 'static' | 'animation', content: ReactNode) => {
+    const SceneConfigWrapper = sceneMode === 'animation' ? AnimationSceneProvider : StaticSceneProvider
+    const availableWidth =
+      mode === 'both'
+        ? Math.max(320, Math.floor((viewportSize.width - 96 - 24) / 2))
+        : fittedSize.width
+    const availableHeight = mode === 'both' ? Math.max(240, viewportSize.height - 120) : fittedSize.height
+    const paneSize = fitPreviewSize(baseSize, availableWidth, availableHeight)
+
+    return (
+      <SceneConfigWrapper sceneInFrames={DEFAULT_SCENE_IN_FRAMES} sceneTheme={sceneTheme}>
+        <RemotionPreviewProvider
+          value={{
+            frame: sceneMode === 'animation' ? frame : 0,
+            fps: 30,
+            width: paneSize.width,
+            height: paneSize.height,
+            durationInFrames: DEFAULT_SCENE_IN_FRAMES,
+          }}
+        >
+          <div
+            style={{
+              width: paneSize.width,
+              height: paneSize.height,
+              boxShadow: '0 28px 80px rgba(15, 23, 42, 0.45)',
+              borderRadius: 0,
+              overflow: 'hidden',
+              background: '#020617',
+            }}
+          >
+            {content}
+          </div>
+        </RemotionPreviewProvider>
+      </SceneConfigWrapper>
+    )
+  }
+
+  return (
+    <div
+      style={{
+        width: '100vw',
+        height: '100vh',
+        overflow: 'hidden',
+        display: 'grid',
+        placeItems: 'center',
+        background:
+          'radial-gradient(circle at top, rgba(15, 23, 42, 0.96) 0%, rgba(2, 6, 23, 1) 60%, rgba(15, 23, 42, 1) 100%)',
+        padding: 24,
+        boxSizing: 'border-box',
+      }}
+    >
+      {mode === 'both' ? (
+        <div
+          style={{
+            width: '100%',
+            height: '100%',
+            display: 'grid',
+            gridTemplateColumns: 'repeat(2, minmax(0, 1fr))',
+            gap: 24,
+            alignItems: 'center',
+          }}
+        >
+          <div style={{ display: 'grid', gap: 12, justifyItems: 'center' }}>
+            <div style={{ color: '#e2e8f0', fontSize: 12, letterSpacing: '0.24em', textTransform: 'uppercase', opacity: 0.72 }}>Static</div>
+            {renderScene('static', children)}
+          </div>
+          <div style={{ display: 'grid', gap: 12, justifyItems: 'center' }}>
+            <div style={{ color: '#e2e8f0', fontSize: 12, letterSpacing: '0.24em', textTransform: 'uppercase', opacity: 0.72 }}>Animation</div>
+            {renderScene('animation', children)}
+          </div>
+        </div>
+      ) : (
+        renderScene(mode, children)
+      )}
+    </div>
+  )
+}

package/src/storybook/component-project-helper.ts

@@ -0,0 +1,94 @@
+type MetadataKind = 'scene' | 'theme' | 'transition'
+
+type BaseMetadata = {
+  resourceKind: MetadataKind
+  pluginKey: string
+}
+
+type SceneMetadata = BaseMetadata & {
+  resourceKind: 'scene'
+  sceneFamily?: string
+}
+
+type ThemeMetadata = BaseMetadata & {
+  resourceKind: 'theme'
+}
+
+type TransitionMetadata = BaseMetadata & {
+  resourceKind: 'transition'
+  transitionKind?: 'transition' | 'overlay'
+}
+
+const metadataStore = new WeakMap<object, BaseMetadata>()
+
+function attachMetadata<T extends object, M extends BaseMetadata>(target: T, metadata: M): T {
+  metadataStore.set(target, metadata)
+  return target
+}
+
+function getMetadata<T extends BaseMetadata>(target: unknown, kind?: MetadataKind): T | undefined {
+  if (!target || (typeof target !== 'object' && typeof target !== 'function')) {
+    return undefined
+  }
+
+  const metadata = metadataStore.get(target as object)
+  if (!metadata) {
+    return undefined
+  }
+
+  if (kind && metadata.resourceKind !== kind) {
+    return undefined
+  }
+
+  return metadata as T
+}
+
+function makeAnnotation<M extends BaseMetadata>(kind: MetadataKind) {
+  return (metadata: M) => {
+    const normalized = metadata
+
+    return function annotate<T extends object>(target: T) {
+      return attachMetadata(target, normalized)
+    }
+  }
+}
+
+export const VIDEO_RESOURCE_METADATA_KEY = Symbol.for(
+  '@vibecuting/video-project-core/storybook-video-resource-metadata',
+)
+
+export const VideoComponent = makeAnnotation<SceneMetadata>('scene')
+export const ThemeComponent = makeAnnotation<ThemeMetadata>('theme')
+export const TransitionComponent = makeAnnotation<TransitionMetadata>('transition')
+
+export function defineComponentProjectComponentMetadata<T>(metadata: T) {
+  return metadata
+}
+
+export function defineScenePluginMetadata<T extends SceneMetadata>(metadata: T) {
+  return metadata
+}
+
+export function defineThemePluginMetadata<T extends ThemeMetadata>(metadata: T) {
+  return metadata
+}
+
+export function defineTransitionPluginMetadata<T extends TransitionMetadata>(metadata: T) {
+  return metadata
+}
+
+export function getComponentProjectComponentMetadata(target: unknown) {
+  return getMetadata(target, 'scene')
+}
+
+export function getScenePluginMetadata(target: unknown) {
+  return getMetadata(target, 'scene')
+}
+
+export function getThemePluginMetadata(target: unknown) {
+  return getMetadata(target, 'theme')
+}
+
+export function getTransitionPluginMetadata(target: unknown) {
+  return getMetadata(target, 'transition')
+}