AgentBuild: 30명의 AI 에이전트가 방문자 앞에서 페이지를 구축합니다
페이지 진입 효과: 페이지의 각 블록이 와이어프레임 뒤에 숨겨지고, 이름이 있는 커서 무리가 날아와 선택 프레임을 끌어 블록을 '구축'합니다. DOM과 CSS transition만 사용(Canvas 없음, 라이브러리 없음), 30개의 커서도 거의 리소스를 소모하지 않습니다.
assets/ 디렉토리 내 파일:
| 파일 | 사용 시기 |
|---|---|
agent-build.js | 코어. <script> 태그로 사용(window.AgentBuild 생성) 또는 번들러에서 import(CommonJS). |
agent-build.css | 필수, 코어와 함께 제공. --ab-* 변수로 색상 변경. |
agent-build.d.ts | 코어용 TypeScript 타입 정의. |
AgentBuild.tsx | React/Next 래퍼(클라이언트 컴포넌트). |
demo.html | 브라우저에서 바로 열어 실행할 수 있는 데모 페이지. |
적용 방법
일반 HTML 웹
agent-build.js와agent-build.css를 프로젝트에 복사합니다.- CSS는
<head>에, 스크립트는<body>끝에 삽입한 후, DOM에 콘텐츠가 존재한 후에start를 호출합니다:
<link rel="stylesheet" href="agent-build.css" />
<script src="agent-build.js"></script>
<script>
AgentBuild.start({
root: "main", // 구축할 영역; 커서 레이어는 이 영역 내에 위치
targets: "main h1, main p, .card", // 구축할 블록들, 우선순위 순서
seenKey: "home", // 페이지별 고유 키
labels: { status: "{agents} 에이전트 · {edits} 편집 중", building: "페이지 구축 중", done: "구축 완료", skip: "건너뛰기" },
});
</script>
React / Next.js (App Router)
agent-build.js,agent-build.d.ts,AgentBuild.tsx를 동일한 디렉토리(예:src/components/agent-build/)에 복사합니다.- 공통 스타일시트에서
agent-build.css를 한 번 임포트합니다(@import "../components/agent-build/agent-build.css";). - 컴포넌트를 구축하려는 영역의 첫 번째 자식으로 배치합니다. 컴포넌트는 부모 요소를 root로 사용합니다:
<div className="landing">
<AgentBuild targets=".landing h1, .landing p, .card" seenKey="landing" />
...
</div>
서버에서 렌더링된 페이지도 문제없이 동작합니다. 컴포넌트는 클라이언트에서만 실행되며, useLayoutEffect(첫 번째 페인트 전)에서 블록을 숨기므로 콘텐츠가 번쩍이는 현상이 없습니다.
targets 올바르게 선택하기
이 부분이 효과의 퀄리티를 결정합니다.
- 의미 있는 블록을 선택하세요: 제목, 문단, 버튼, 카드, 이미지. 섹션 전체를 감싸는
div는 선택하지 마세요. 거대한 프레임 하나가 버그처럼 보입니다. - 우선순위 순서대로 나열하세요. 이미 선택된 요소 내부에 있는 요소는 자동으로 무시됩니다. 예를 들어
.card를 선택했다면 카드 내부의p는 별도로 구축되지 않습니다. 카드 전체를 구축하려면.card를p보다 먼저 배치하세요. - 개별 효과(스크롤 따라 움직이는 텍스트, Canvas)가 이미 있는 영역은
skipInside: ".tagline"으로 제외하세요. - 시작 시 너비나 높이가 0인 요소는 자동으로 건너뜁니다.
- 약 30~140개의 블록이 적당합니다.
maxTargets기본값은 140입니다. - 프로젝트에 '스크롤 시 서서히 나타나는' 효과가 이미 있다면, 에이전트 실행 중에는 해당 효과를 비활성화하세요. 그렇지 않으면 두 효과가 겹칩니다. 예:
[data-agent-build] .reveal { opacity: 1; transform: none; transition: none; }(data-agent-build속성은 실행 중 root에 추가됩니다).
옵션
| 옵션 | 기본값 | 설명 |
|---|---|---|
root | document.body | 요소 또는 선택자. 실행 중 position: relative가 적용됩니다. |
targets | h1, h2, h3, p, img, figure, li, button, .card | 블록 목록. |
count | 30 (화면 너비 640px 미만이면 16) | 에이전트 수. |
once / seenKey | true / "agent-build" | 탭당 한 번만 실행합니다. |
forceParam | "agents" | URL에 ?agents를 추가하면 항상 재실행됩니다. 비디오 녹화 시 유용합니다. |
respectReducedMotion | true | 사용자가 동작 줄이기 설정을 켜면 실행하지 않습니다. |
pill | true | 상태 표시줄에 '건너뛰기' 버튼을 표시합니다. |
labels | 영어 | status ({agents}, {edits} 포함 가능), building, done, skip. |
colors, roles | 8가지 색상, 10가지 역할 | 에이전트 색상 및 이름(layout-07). |
start()는 { skip(), destroy(), started }를 반환합니다. destroy()는 페이지를 원래 상태로 복원합니다. SPA에서 페이지를 떠날 때나 컴포넌트가 언마운트될 때 호출하세요.
CSS 변수로 인터페이스를 변경하세요: --ab-wire(와이어프레임 색상), --ab-pill-bg, --ab-pill-text, --ab-pill-muted, --ab-mono, --ab-ease.
스크린샷 없이 수치로 테스트하기
Playwright로 ?agents가 추가된 페이지를 열고 다음을 확인합니다:
({
cursors: document.querySelectorAll(".ab-cursor:not([data-hidden])").length, // 초기에는 약 30
waiting: document.querySelectorAll('[data-ab="wait"]').length, // 스크롤 시 감소
on: !!document.querySelector("[data-agent-build]"), // 완료되면 false
})
window.scrollTo를 단계별로 호출하여 스크롤하고(페이지에 Lenis smooth scroll이 있다면 mouse.wheel 사용 금지), 몇 초 기다립니다. 올바른 결과: waiting이 0이 되고 on이 false가 됩니다. '건너뛰기' 버튼 테스트: .ab-skip을 클릭한 후 [data-ab]가 더 이상 없어야 합니다. 시각적 평가가 필요한 경우에만 한 장의 스크린샷을 찍습니다.
알려진 문제
- 프레임 또는 커서 위치가 어긋남: root가 모든 블록을 포함하지 않습니다. 모든
targets를 포함하는 요소를 root로 선택하세요. fill속성 이미지(Next/Image)가 페이지 전체를 덮음: 이 스킬의 버그가 아닙니다.fill이미지의 부모 컨테이너에position: relative를 설정해야 합니다.- 효과가 재실행되지 않음: 탭에서 이미 한 번 실행되었습니다. URL에
?agents를 추가하거나 새 탭을 여세요. - React StrictMode(개발 환경에서 효과가 두 번 실행됨): 코어는 1.2초 후에 '실행됨'으로 기록하므로, 두 번째 마운트 시에도 정상적으로 실행됩니다.