LLM Wiki

scroll-world — 스크롤로 비행하는 3D 랜딩 페이지를 만드는 에이전트 스킬

Properties3
descriptionoso95/scroll-world의 Claude Code·Codex 호환 스킬, 프레임 고정형 영상 체인, vanilla JS 스크럽 엔진, 모바일·seam QA 절차를 고정 커밋 기준으로 정리한다.
tagsagent-skills, ai-coding, landing-page, scroll-animation, video, javascript, claude-code, codex, mobile-web, design
aliasesscroll-world, 스크롤 월드, 3D world landing page

16 min read

oso95/scroll-world는 브랜드·산업을 스크롤 기반의 3D world landing page로 바꾸는 에이전트 스킬이다. 에이전트가 브랜드와 장면을 인터뷰한 뒤, 일관된 diorama still과 프레임 고정형 camera-flight 영상을 생성하고, 스크롤 위치를 영상 시간으로 매핑하는 portable vanilla-JS 엔진을 연결한다.

한눈에 보기

  • 프로젝트 성격: Claude Code plugin/marketplace와 SKILL.md 호환 에이전트용 작업 절차.
  • 주 결과물: 장면별 still, 장면에 진입하는 dive/leg 영상, 장면 사이를 잇는 connector, 그리고 스크롤로 전체 영상을 탐색하는 landing page.
  • 고정 기준: main의 71cc36d3bb150248ae36a2c552f9cbf88802a79c (docs: seam QA calibration — judge composition, not raw PSNR, 2026-07-29).
  • 메타데이터 스냅샷: JavaScript 저장소, 7,759 stars, 880 forks, 9 open issues, GitHub API 라이선스 MIT License, 비아카이브 상태. 수치는 2026-08-08 KST의 변동 가능한 스냅샷이다.
  • 릴리스 메타데이터: plugin version 0.8.0, author cyw, license: MIT.
  • 라이선스: 루트 LICENSE와 plugin metadata 모두 MIT를 표시한다. 생성된 영상·이미지 asset과 외부 생성 서비스의 이용 조건까지 MIT라고 확장하지 않는다.
  • 구현 핵심: framework-agnostic vanilla JavaScript, zero runtime dependency, 자체 DOM/CSS 생성, Blob 기반 video seek, requestAnimationFrame 기반 currentTime scrub.
  • 검증 상태: source inspection과 정적 해시 검증은 완료했지만, plugin 설치, 외부 CLI 인증, 실제 이미지·영상 생성, 웹 페이지 실행, 모바일·seam QA는 하지 않았다.

저장소 구성

고정 커밋의 recursive tree는 총 15개 entry이며 11개 파일·4개 디렉터리다. 전용 tests/ 경로는 확인되지 않았다.

  • .claude-plugin/marketplace.json — marketplace metadata와 ./skills/scroll-world plugin 연결
  • .claude-plugin/plugin.json — plugin 이름, 설명, version, author, homepage, license, keywords
  • README.md — 설치법, 요구사항, 기능, 비용·운영 주의사항
  • LICENSE — MIT License
  • skills/scroll-world/SKILL.md — 전체 인터뷰·생성·체인·QA 절차와 gotchas
  • skills/scroll-world/references/prompts.md — intake checklist와 still/dive/connector prompt template
  • skills/scroll-world/references/pipeline.md — bash 3.2 호환 생성·프레임 추출·인코딩 스크립트
  • skills/scroll-world/references/scrub-engine.js — portable scroll-scrub engine
  • skills/scroll-world/references/index-template.html — 최소 standalone HTML mounting 예제
  • skills/scroll-world/references/knockout.py — 배경 연결 flood-fill 방식의 투명화 helper

전체 소스는 위키에 중복 저장하지 않고, fixed commit URL과 선별 파일 해시를 raw source: github-oso95-scroll-world에 기록했다.

에이전트 인터뷰와 산출물 계약

references/prompts.md와 SKILL.md의 intake는 생성 전에 다음을 수집하도록 설계되어 있다.

  • SUBJECT — 사업/브랜드와 한 줄 pitch
  • BRAND_NAME — 표시 이름
  • PALETTE — 4–6개의 색상과 장면 배경·primary accent
  • TONE, STYLE — 분위기와 미술 방향
  • SECTIONS[] — 장면 순서, 대상, eyebrow, title, body, tags. 마지막은 hero product와 CTA
  • CAMERA — fly-through(architecture B), walkthrough(architecture A), locked-isometric
  • MOBILE — native 9:16 portrait chain을 만들지 여부. 선택하면 영상 생성량이 대략 2배가 된다고 안내
  • VIDEO_TIER — Monid Seedance 2.0 기본 경로 또는 Higgsfield의 draft/standard/alternate 경로
  • STILLS_SOURCE — Higgsfield gpt_image_2 또는 Codex image_gen

비용과 생성 티어를 먼저 설명하고 사용자의 승인을 받은 뒤 외부 생성에 들어가도록 절차가 구성되어 있다. 이것은 skill의 설계 규칙이며, 이번 ingest에서 실제 비용·승인 UI·잔액 검증을 실행한 것은 아니다.

핵심 설계: seam을 프레임으로 고정하기

이 저장소의 핵심 규칙은 장면 설명이 아니라 실제로 렌더된 이웃 영상의 경계 프레임을 다음 영상의 입력으로 넘기는 것이다.

  • architecture A: 한 방향의 continuous forward take.
    • 첫 leg는 첫 장면 still에서 시작한다.
    • 다음 leg의 --start-image는 이전 leg의 실제 마지막 프레임이다.
    • --end-image와 connector 없이 legs 자체를 순차 연결한다.
    • 카메라가 seam을 가로질러 뒤로 되돌아가지 않도록 마지막 약 1초를 느리고 안정적인 forward drift로 마무리하고 다음 leg도 같은 drift로 시작한다.
  • architecture B: diorama/miniature world용 dive-in + aerial connector.
    • 각 dive의 실제 마지막 프레임을 connector의 start image로 사용한다.
    • 다음 dive의 실제 첫 프레임을 connector의 end image로 사용한다.
    • connector가 위로 빠져나와 다음 장면으로 이동하므로, grounded walkthrough에서는 forward dive 뒤의 pull-back이 rewind/stutter처럼 읽힐 수 있다고 경고한다.
  • connector가 없어도 engine은 null connector를 허용하고 두 dive를 직접 crossfade하여 페이지를 완성할 수 있다.
  • Seedance 계열의 end frame은 같은 구성을 가리켜도 pixel-perfect하지 않을 수 있으므로, 실제 frame handoff를 유지하면서 짧은 crossfade를 보험으로 사용한다.

이는 이미지 still을 반복해서 넘기는 단순 reference conditioning과 구분되는 설계다. 저장소는 seam을 유지하려면 모델이 start-image를 지원해야 하고 connector에는 end-image도 필요하다고 명시한다.

모델·백엔드 경로

저장소 문서가 제시하는 roster와 역할은 다음과 같다.

  • seedance_2_0 — 기본 chain 모델. start/end image를 지원하는 full-chain 경로.
  • kling3_0 — full-chain 대안. --resolution을 사용하지 않고 --sound off를 지정하는 별도 flag branch.
  • seedance_2_0_mini — frame-locking을 유지하는 저비용 previz tier.
  • kling3_0_turbo와 minimax_hailuo — connector를 만들 수 없거나 별도 wiring이 필요한 architecture-A 전용 후보로 설명된다.

문서상 default biller는 Monid의 bytedance /v1/video/seedance-2.0이다. 저장소는 2026-07-25 qualification probe에서 첫 frame의 PSNR, connector end composition, cost.value를 확인했다고 기록하고, Higgsfield를 fallback biller 또는 Higgsfield-only 모델 경로로 둔다. 이 수치·가격·endpoint schema는 외부 서비스의 현재 상태에 의존하므로 위키에서는 저장소 문서에 적힌 검증 이력으로만 기록한다.

Monid 경로의 I/O 규칙으로 문서는 다음을 강조한다.

  • 이미지 데이터를 inline base64로 보내지 않고 sfs 파일 시스템을 거쳐 public URL로 전달
  • desktop 16:9, mobile 9:16을 ratio로 명시
  • 각 run의 실제 비용을 cost.value로 확인
  • polling timeout은 서버 작업 중단과 다를 수 있으므로 run ID를 다시 poll
  • 결과 URL은 유효기간이 짧으므로 즉시 다운로드

생성 파이프라인

references/pipeline.md는 macOS 기본 bash 3.2에서도 동작하도록 작성된 copy-paste 스크립트를 제공한다.

  1. gpt_image_2 또는 Codex image_gen으로 장면 still 생성
  2. 필요하면 knockout.py로 단색 배경을 border-connected flood fill하여 투명화
  3. still을 webp로 변환하고 사이트용 poster로 보존
  4. 각 장면의 dive/leg 영상 생성
  5. 렌더된 영상에서 ffmpeg로 첫 프레임과 마지막 프레임 추출
  6. 인접 장면 사이 connector 생성
  7. 영상 인코딩
  8. engine config에 sections와 connectors 연결
  9. headless browser에서 seam과 seekability QA

desktop 인코딩 권장값은 native resolution, crf 20, -g 8, yuv420p, +faststart, audio 제거, 가벼운 unsharp다. all-intra로 파일을 크게 만들지 말고, HTTP byte-range 지원 여부에 scrub을 의존하지 않도록 engine이 Blob으로 전체 clip을 fetch한다.

모바일 경로

모바일을 선택한 경우 저장소가 권장하는 것은 landscape 영상의 단순 center crop이 아니라 완전한 native 9:16 chain이다.

  • 모든 dive와 connector를 9:16으로 다시 렌더링
  • portrait chain 자체의 실제 frame으로 seam을 고정
  • clipMobile, connectorsMobile, stillMobile을 config에 연결
  • portrait clip을 scale=720:-2, -g 4, crf 23 수준으로 인코딩
  • 각 portrait dive의 첫 frame을 portrait poster로 사용

pipeline의 centre-crop -m.mp4는 credits가 부족할 때의 fallback일 뿐이며, 그 경우 사용자에게 명시해야 한다고 적혀 있다.

scrub-engine.js 구현

mountScrollWorld(container, config)는 DOM과 CSS를 스스로 구성하며 다음 요소를 interleave한다.

  • section dive clip
  • 선택적인 connector clip
  • 다음 section의 still/poster
  • copy layer, route rail, top navigation, scrollbar, scroll hint, atmosphere/particles

설정은 brand, diveScroll, connScroll, crossfade, sections, connectors, connectorsMobile을 받는다. section은 still, clip, optional mobile variants, accent, copy text, tags, CTA, per-section scroll·linger를 가진다.

시간·스크롤 처리는 다음과 같다.

  • 각 segment에 viewport-height 기준 길이를 배정
  • scroll position을 segment local progress로 변환
  • linger가 있으면 seam의 0과 1은 보존한 채 중간 구간에 dwell을 배치
  • requestAnimationFrame loop가 target으로 cur를 보간
  • decoder가 이전 seek를 처리 중이면 새 currentTime을 큐에 쌓지 않음
  • 모바일에서는 더 큰 epsilon으로 seek 횟수를 줄임
  • 인접 scene을 lazy fetch하여 Blob object URL로 video 생성
  • 실제 frame이 paint되기 전에는 still poster를 계속 표시
  • 짧은 opacity crossfade로 seam을 완화

모바일과 접근성 처리는 별도 config 없이 기본 활성화된다.

  • coarse pointer 또는 860px 이하에서 clipMobile·connectorsMobile 사용, 없으면 desktop clip fallback
  • 빠른 flick에서 seek를 coalesce하여 decoder가 멈추지 않도록 함
  • 첫 touch에서 muted play→pause로 iOS video를 prime
  • prefers-reduced-motion이면 clip을 로드하지 않고 still만 사용
  • 모바일 URL bar에 따른 height-only resize를 무시해 scroll jump 방지
  • safe-area inset과 dvh로 copy가 notch/home indicator에 가려지지 않도록 함
  • 모바일에서는 particle을 제거하고 route rail의 touch target을 키움

문서의 esc()는 copy 필드를 HTML escape한 뒤 innerHTML을 구성한다. 다만 이 engine은 사용자의 project에 복사되는 portable 코드이므로, 실제 배포에서는 CTA URL·asset URL의 허용 scheme과 CSP/CORS를 애플리케이션 경계에서 별도로 검토하는 편이 안전하다. 이는 코드 inspection에 따른 운영 권고이며 취약점 재현 결과가 아니다.

QA 규칙

저장소가 가장 중요하게 보는 QA는 시각적 seam continuity다.

  • 각 seam 직전·직후를 headless browser로 캡처
  • dive 마지막 frame과 connector 첫 frame, connector 마지막 frame과 다음 dive 첫 frame의 composition을 비교
  • raw PSNR만으로 판정하지 말고 prop·구성·공간 관계가 바뀌었는지 확인
  • video.seekable.end(0) > 0과 console error를 확인
  • scroll band에서 currentTime이 실제로 따라오는지 확인
  • reduced-motion에서 영상·particle 없이 still fallback이 되는지 확인
  • mobile opt-in이면 CPU 4–6× throttling, 빠른 scroll, iOS Safari blank scene, native portrait videoWidth < videoHeight, URL-bar resize, rotation, safe-area를 확인

저장소의 고정 커밋 메시지도 seam QA calibration을 다루지만, 위키 ingest에서는 이 QA를 실행하지 않았다. 따라서 “seam QA 통과”나 “모바일 호환 확인”으로 표현하지 않는다.

운영·보안 검토 포인트

  • 외부 실행면: Monid CLI/API, Higgsfield CLI, optional Codex CLI, ffmpeg/ffprobe, curl, jq, Python/Pillow
  • README는 Monid API key와 balance, Higgsfield 인증 및 credits를 요구한다고 적는다. 인증값은 위키에 저장하지 않았다.
  • image/video generation은 실제 비용이 발생하며, mobile native chain은 생성량이 증가한다.
  • result URL과 signed public URL은 외부 서비스가 발급하는 단기 URL이므로 asset을 즉시 프로젝트 storage로 옮겨야 한다.
  • blob fetch 방식은 static host의 byte-range 미지원 문제를 피하지만, 실제 웹 배포에서는 asset URL의 CORS·Content-Type·용량·메모리 사용량을 검토해야 한다.
  • SKILL.md와 README에 표시된 외부 서비스 가격·모델 schema·성능 수치는 시점 의존적이다. 매 빌드 전 endpoint inspect와 cheap qualification probe를 다시 하라는 것이 저장소의 운영 규칙이다.
  • 생성된 .mp4/.webp는 저장소에 포함되지 않으므로, 이 repo 자체는 생성 asset repository가 아니라 생성 절차·engine template repository다.

공식 확인·해석·미검증 범위

고정 커밋에서 직접 확인한 것

  • Claude Code marketplace와 SKILL.md 설치 경로
  • plugin version/author/license metadata
  • intake checklist와 camera architecture A/B 규칙
  • actual rendered frame을 이용한 connector handoff 규칙
  • Monid/Higgsfield/Codex/ffmpeg 기반 pipeline 문서
  • scrub-engine.js의 Blob loading, lazy load, currentTime scrub, crossfade, reduced-motion, mobile hardening
  • index-template.html의 standalone mounting 구조
  • knockout.py의 이미지 배경 처리 목적
  • 고정 recursive tree에 dedicated tests 경로가 없다는 사실

저장소가 주장하지만 이번 환경에서 재현하지 않은 것

  • Monid/Higgsfield의 실제 frame-lock과 가격
  • 2026-07-25 qualification probe의 PSNR·비용 수치
  • 어떤 산업/브랜드에도 적용되는 생성 품질
  • seam이 시각적으로 seamless하다는 결과
  • iOS Safari·저사양 모바일의 scrub 성능
  • 외부 provider의 현재 schema와 credit race 처리

이번 ingest에서 하지 않은 것

  • npx skills add, Claude Code plugin install, Codex skill install
  • Monid/Higgsfield 로그인 및 API key 설정
  • 이미지·영상 generation과 실제 .mp4/.webp 다운로드
  • ffmpeg encoding pipeline 실행
  • 실제 HTML mounting, browser/Playwright/headless QA
  • mobile portrait QA와 seam screenshot 비교
  • benchmark, 비용 측정, 보안 테스트

관련 메모

백링크