metapages/framejs.io

framejs

framejs는 ES6 JavaScript 모듈을 브라우저에서 실행합니다. frame은 앱입니다. 안정적이고 공유 가능한 framejs.app/j/<uuid> URL에 있으며, 내용은 변경 가능합니다. hash 매개변수를 POST하여 앱을 그 자리에서 업데이트합니다. 여러분의 역할은 사용자의 요청을 브라우저 JavaScript로 변환하고, 환경에 맞는 올바른 방법으로 전달하는 것입니다.

전달 모드 선택

요청이 아니라 여러분이 할 수 있는 것에 따라 선택하세요:

• 자동화 모드 — 셸 / node를 실행할 수 있는 경우: JavaScript를 생성한 후, 세션의 framejs.app frame을 생성하거나 업데이트하고, /j/<uuid> URL을 출력한 후 브라우저에서 엽니다. 셸을 사용할 수 있을 때 기본값입니다.
• 코드 블록 모드 — 채팅 / API 전용, 셸 없음: 오직 하나의 펜싱된 JavaScript 코드 블록만 응답으로 보내고(열 때 javascript 정보 문자열 사용), 그 외에는 아무것도 보내지 않습니다. 주변 설명, 파일, URL이 없습니다. 사용자가 framejs.io 편집기에 붙여넣습니다.

두 모드 모두 작성하는 JavaScript는 동일한 규칙을 따릅니다. references/coding-guide.md를 읽으세요.

요청의 종류

1. 프롬프트로 생성 — "튕기는 공 애니메이션", "y = sin(x) 그래프"와 같은 요청.
2. 기존 앱 수정 — 요청에 frame URL이 포함되어 있습니다. https://framejs.app/j/<uuid> 또는 https://framejs.io/j/<uuid>?token=… URL(framejs.io 런타임 폼을 복사하는 "AI 세션용 frame 복사" 동작), 32자 16진수 id, 또는 레거시 https://framejs.io/j/<sha256> / 64자 id 스냅샷일 수 있습니다. framejs URL을 볼 때마다 /j/<uuid> 경로에서 uuid를 추출하여 해당 frame을 대상으로 합니다(URL을 --id에 바로 전달하면 도우미가 framejs.io URL이더라도 앱 계층으로 업데이트를 라우팅합니다). 먼저 기존 코드를 가져와서 수정해야 합니다. — references/short-url-api.md (§ 수정)을 참조하세요. URL에 ?token=<key> 쿼리 매개변수(앱의 "AI 세션용 frame 복사" 동작에서)가 있는 경우, 전체 URL을 --id에 전달하거나 키를 --token에 전달하세요. 도우미가 이를 저장하고 bearer 자격 증명으로 보내므로 frame 소유자가 frame을 클레임한 후에도 업데이트가 계속 작동합니다. 전체 URL을 전달하면 URL이 지정하는 백엔드를 대상으로 하므로, 개발 또는 자체 호스팅 frame URL(예: https://framejs-app.localhost:13747/j/<uuid>?token=<key>)은 사전 구성된 env 없이 자체 스택을 업데이트합니다. --app-origin <url> / --io-origin <url>은 백엔드를 명시적으로 설정합니다. references/short-url-api.md (§ 로컬 / 개발 origin)을 참조하세요.
3. 로컬 파일 시각화 — 요청이 파일 경로(./data.csv, /tmp/results.json)를 참조합니다. 파일을 업로드하여 입력으로 전달하세요. — references/file-inputs.md를 참조하세요.

자동화 모드 — 전달 방법

코드를 생성한 후, 번들된 도우미(권장) 또는 references/short-url-api.md의 인라인-node 대체 방법을 사용하세요:

cat << 'JSCODE' | node scripts/framejs.mjs create --state "${SCRATCHPAD}/framejs-frame.json" --title "<짧은 제목>" --description "<한 문장 요약>" --screenshot
// 여기에 생성된 브라우저 JS를 작성하세요 — $vars, 백틱, 모든 특수 문자는 heredoc 내에서 안전합니다
JSCODE

도우미는 (stdout으로) 두 개의 URL을 출력합니다. — 기본 https://framejs.app/j/<uuid> 페이지 URL과 불변 snapshot: https://framejs.io/j/<sha256> URL입니다. 또한 (stderr로) 사용자에게 반드시 전달해야 하는 공유 링크 수명 주기 고지를 출력합니다:

• /j/<uuid> 페이지는 편집 가능하고 실시간 업데이트되지만, 익명(클레임되지 않은) frame은 임시적이며 만료됩니다 — 사용자에게 페이지를 열고 클레임(무료 계정)하여 영구적으로 유지하라고 알리세요.
• /j/<sha256> 스냅샷은 현재 앱의 불변 복사본으로, 마지막으로 열린 후 약 30일 후에 만료됩니다 — 안정적인 공유/백업 링크이지만 이후 편집 내용을 반영하지 않습니다.

클래식 스크립트에는 --module <url>을, 입력에는 --input name=value를 추가하세요.

세션당 하나의 frame, 그 자리에서 업데이트. 항상 --state "<스크래치패드 경로>/framejs-frame.json"(쓰기 가능한 파일 경로)을 전달하세요. 첫 번째 create가 frame을 만듭니다. 동일한 --state로 create를 다시 실행하면 동일한 frame이 업데이트됩니다 — /j/<uuid> URL은 일정하게 유지되며 열려 있는 모든 framejs.app 페이지가 실시간으로 업데이트되므로, 사용자에게 URL을 한 번만 알려주세요. 사용자가 동일한 세션에서 별도의 앱을 원할 때만 --new를 추가하여 새 frame을 시작합니다(이후 업데이트는 새 frame을 대상으로 함). 상태와 관계없이 특정 frame을 업데이트하려면 --id <uuid>를 전달하세요. 이러한 제자리 업데이트 시, --og/--title/--description을 전달하지 않으면 도우미가 기존 Open Graph 데이터를 자동으로 유지하므로, 재실행 시 제목/설명이 손실되지 않으며(og.image가 유지되므로 중복 스크린샷을 건너뜁니다). 미리보기 복사본을 _변경_하려는 경우에만 --title/--description을 다시 전달하세요.

브라우저는 frame이 처음 생성될 때만 자동으로 열립니다(건너뛰려면 --no-open 사용). 동일한 frame을 나중에 업데이트할 때(동일한 --state 또는 명시적 --id)는 브라우저가 다시 열리지 않습니다. 이미 열린 페이지가 동일한 frame 구독을 통해 실시간으로 업데이트를 수신하므로, 다시 열면 중복 탭만 생성됩니다.

로컬 개발 체크아웃이 있는 경우 도우미가 자동으로 .env를 로드하고 개발 스택(FRAMEJS_APP_ORIGIN / FRAMEJS_IO_ORIGIN)을 대상으로 합니다. — 추가 조치가 필요하지 않습니다.

도우미가 out of date 업데이트 알림을 출력하면(stderr, 최대 1시간 간격), 사용자에게 그대로 한 번 전달하세요. 설치된 스킬이 최신 버전보다 뒤쳐져 있으며 알림에 업데이트 명령어가 포함되어 있습니다.

항상 --screenshot을 전달하세요. 도우미가 완성된 앱을 렌더링하고 og:image 미리보기로 저장합니다. 자체 보호 기능이 있습니다. 앱에 og.image가 아직 없는 경우에만 캡처하므로, 이전 실행(또는 사용자)이 이미 설정한 이미지를 덮어쓰지 않으며, 렌더러를 사용할 수 없는 경우 이미지 없는 URL로 자동 폴백됩니다. 캡처는 Playwright를 가져올 수 있을 때 선호합니다(진정한 network-idle 대기 — 입력을 가져오는 앱에 가장 좋음). 그 외에는 시스템 headless Chrome을 사용합니다. Playwright는 선택 사항입니다. 더 안정적인 경로를 위해 설치하거나(npm i -g playwright && npx playwright install chromium), $FRAMEJS_PLAYWRIGHT를 node_modules가 있는 디렉토리로 설정하세요. --screenshot-wait <ms>(기본값 6000 — 느리게 로드되는 앱은 값을 높이세요)와 --screenshot-size <w,h>(기본값 1200,630)로 조정하세요. Chrome 바이너리는 $CHROME_PATH로 재정의하세요.

scripts/framejs.mjs는 현재 작업 디렉토리가 아닌 이 스킬의 디렉토리를 기준으로 확인됩니다. 스킬 폴더에서 실행하거나 절대 경로를 사용하세요(Claude Code는 디렉토리를 ${CLAUDE_SKILL_DIR}로 노출하므로 ${CLAUDE_SKILL_DIR}/scripts/framejs.mjs가 항상 작동합니다). 번들 도우미를 찾거나 실행할 수 없는 경우 references/short-url-api.md의 인라인-node 대체 방법을 사용하세요. 스크립트 파일이 필요하지 않습니다.

링크 공유 시 미리보기가 잘 표시되도록 항상 Open Graph 미리보기 태그를 포함하세요. — references/short-url-api.md의 OG 규칙을 참조하세요:

• 새 앱: --title / --description으로 새 복사본을 만들고, --screenshot을 전달하여 미리보기 이미지를 캡처하세요.
• 기존 앱 수정: 가져온 앱에는 이미 og가 있습니다(fetch 명령어가 반환함). 다시 계산하지 마세요. 가져온 객체를 --og '<가져온 og JSON>'으로 그대로 다시 전달하면 모든 필드(image 포함)가 유지됩니다. --id <uuid>(또는 동일한 --state)로 동일한 frame을 업데이트하세요. 사용자가 미리보기 복사본을 명시적으로 변경하도록 요청한 경우에만 새 --title/--description을 설정하세요. --screenshot은 여전히 전달할 수 있습니다. 가져온 og에 이미 image가 있으면 변경되지 않고, 없으면 새 캡처가 추가됩니다.

절대 규칙 (두 모드 모두)

• 브라우저 JavaScript만 가능합니다. iframe에서 실행되며, Node.js가 아닙니다.
• 반드시 ES6 모듈 구문을 사용해야 합니다: export function onInputs(inputs) {}.
• HTML 파일을 절대 생성하지 마세요. 로컬 .js 파일을 절대 작성하지 마세요. 결과를 렌더링하기 위해 자체 시각화/렌더링/위젯 도구를 절대 사용하지 마세요.
• root.style.position, root.style.height, root.style.width를 절대 수정하지 마세요.
• 중요: 시각화는 모바일에서 잘 보이고 화면 크기에 적응해야 합니다 — 반응형 크기 사용(root의 크기 읽기 / resize 리스너 추가), 고정 픽셀 너비 사용 금지, 작은 화면에서 텍스트와 터치 대상이 읽기 쉬워야 함.
• 자동화 모드에서는 사용자가 복사할 코드 블록을 절대 출력하지 말고, 전달물로 긴 hash URL을 직접 만들지 마세요. 항상 frame API를 통해 POST하세요(도우미의 create 사용). 사용자에게 /j/<uuid> 페이지 URL을 알려주세요.
• 코드 블록 모드에서는 오직 하나의 펜싱된 JavaScript 코드 블록만 출력하세요. 그 외 아무것도 출력하지 마세요.

참고 자료

• references/coding-guide.md — 전역 변수, 내보내기, 패턴, CDN 라이브러리, 일반적인 실수.
• references/short-url-api.md — frame 생성/업데이트 (POST /j/<uuid>.json), 세션당 하나의 frame 상태, Open Graph 태그, API 토큰(frame 클레임 후에도 업데이트 유지), 인라인 대체 방법.
• references/file-inputs.md — 로컬 파일 업로드 및 입력으로 연결.
• scripts/framejs.mjs — Node 도우미: create(stdin JS → framejs.app frame), fetch <id>, upload <path>. Origin: FRAMEJS_APP_ORIGIN / FRAMEJS_IO_ORIGIN(로컬 개발 시 인근 .env에서 자동 로드) 또는 --app-origin/--io-origin 또는 --id/fetch에 전달된 전체 frame URL의 origin을 통해 실행 시 설정.