joyco-lab

JOYCO Lab — 実験の分離と公開

あらゆるコードベースから自己完結型の実験を抽出し、適切な JOYCO テンプレートでひな形を作成して、依存関係をインストールし、Vercel にデプロイして、JOYCO Lab レジストリに公開するまでのワークフローを自動化します。

---

前提条件のチェックリスト

開始する前に、ユーザーの環境で以下が利用可能であることを確認してください。

• joyco CLI がインストールされている（joyco --version）
• vercel CLI がインストールされている（vercel --version）
• GitHub 認証が設定されている（joyco lab が PR を作成する際に使用します）
• ユーザーが Vercel にログインしている（vercel whoami）

1 つでも不足している場合は、ユーザーに伝えて作業を中止してください。ワークフローを実行するには、すべてが必要です。

---

Step 1 — 実験を理解する

ユーザーが指定したコードを読みます。次の項目を特定してください。

1. 何をするものか — 1 文で説明します（Lab エントリーに使用します）
2. どの種類か — 以下の表を使ってテンプレートを選びます
3. 必要な依存関係 — インポートを確認し、テンプレートの標準構成に含まれていないものがあれば記録します

テンプレート選択ガイド

コード内のシグナル	使用するテンプレート
three、@react-three/fiber、@react-three/drei、WebGLRenderer、OrbitControls、キャンバス上の 3D	3d
gsap、ScrollTrigger、@studio-freight/lenis、framer-motion、CSS キーフレーム、SVG アニメーション、キャンバス上の 2D 描画	motion

実験に両方が含まれる場合（例：GSAP で Three.js のシーンをアニメーション化する場合）は、3d を優先し、GSAP の依存関係があることを記録します。

本当に判断が難しい場合は、作業を進める前にユーザーに確認してください。

---

Step 2 — 実験に名前を付ける

実験の内容に基づいて、わかりやすい名前を考えます。ルール：

• 自然なタイトルケースにします。スラッグ化する必要はありません（CLI が処理します）
• 短くします（最大 2〜4 語）
• 具体的な名前にし、汎用的な名前は避けます（❌ Cool Animation ✅ Magnetic Cursor Trail）

名前を提案し、コマンドを実行する前にユーザーの確認を得てください。

---

Step 3 — JOYCO CLI でひな形を作成する

joyco create --template <template-value> <experiment-name>

例：

joyco create --template motion "Magnetic Cursor Trail"

これにより、テンプレートをひな形として含む新しいディレクトリ <experiment-name>/ が作成されます。次の手順に進む前に、そのディレクトリに cd してください。

---

Step 4 — 実験コードを移植する

1. エントリーポイント、シェーダー、ヘルパー、アセットなど、必要最小限のファイルを特定します
2. テンプレートのファイル構成（通常は src/ または app/）に従って、ファイルをひな形プロジェクトにコピーします
3. 実験をテンプレートのエントリーポイントに組み込みます（通常は src/main.ts、src/index.tsx、または app/page.tsx ですが、テンプレートを確認してください）
4. 無関係なコード、グローバル状態、ルーティング、バックエンド依存関係は持ち込まないでください

---

Step 5 — 不足している依存関係をインストールする

実験のインポートを、テンプレートにすでに含まれているものと照合します。

パッケージマネージャーを特定する

ひな形テンプレートに含まれているロックファイルを確認し、対応するパッケージマネージャーを使用します。

見つかったロックファイル	パッケージマネージャー
bun.lockb または bun.lock	bun
pnpm-lock.yaml	pnpm
yarn.lock	yarn
package-lock.json	npm

複数のロックファイルがある場合は、上の表で最初に一致するものを優先します。ロックファイルがない場合は、npm を既定で使用します。

インストールと検証

不足しているパッケージごとに、特定したパッケージマネージャーでインストールします。

cd <experiment-name> && <pm> install <package>
# e.g. bun add three, pnpm add three, yarn add three, npm install three

次に、開発サーバーを実行してインポートエラーがないことを確認します。

<pm> run dev

先に進む前に問題を修正してください。よくある問題：

• 型パッケージの不足（@types/three など）
• ピア依存関係の不一致
• テンプレートが、実験とは異なる方法で使われるバンドラー機能を想定している

---

Step 6 — Vercel にデプロイする

今すぐ Vercel にデプロイするか、ユーザーに確認してください。 断られた場合は Step 7 に進んでください。後からデプロイし、joyco lab の実行時に URL を手動で指定できます。

確認が取れた場合は、実験ディレクトリ内で実行します。

vercel --prod

初回デプロイの場合は、プロンプトに従ってください（組織へのリンク、プロジェクト名を実験のスラッグに設定）。本番 URL をコピーします。Lab エントリーで必要になります。

---

ステップ 7 — JOYCO Lab に公開する

公開コマンドを実行し、対話形式のプロンプトに従います。

joyco lab

CLI で次の項目を尋ねられます。

項目	入力内容
名前	人が読みやすいタイトル（例：「磁力で追従するカーソルトレイル」）
説明	内容と技術的に興味深い点を説明する 1、2 文
タグ	カンマ区切り（例：gsap, cursor, magnetic, interaction）。下記のタグガイドを参照
プレビューリンク	ステップ 6 の Vercel 本番 URL
プレビュー画像	任意 — 生成した OG 画像またはスクリーンショット画像の URL

CLI は joyco-studio/lab に PR を作成し、experiments.json にエントリを追加します。出力された PR の URL を確認し、ユーザーに共有します。

タグガイド

次の分類に沿って、一貫性のあるタグを使用してください。

• 種類別： 3d、animation、interaction、shader、canvas、scroll、physics、generative
• ライブラリ別： three、gsap、r3f、framer-motion、lenis、matter-js
• ビジュアルスタイル別： typography、cursor、particles、geometry、noise、fluid

タグは 3～6 個選びます。タグを付けすぎないでください。

---

ステップ 8 — 仕上げる

ユーザーに次の内容を伝えます。

1. 実験ディレクトリの場所
2. 公開中の Vercel URL
3. Lab レジストリのエントリに対する GitHub PR の URL
4. 追加で行えること（PR のマージ、プレビュー画像の追加、SNS での紹介など）

---

例外ケース

実験で非公開／内部向けパッケージを使用している場合： いったん作業を止めてユーザーに伝えます。実験を独立した公開リポジトリにできるよう、依存関係を公開するか、コードにインライン化するか、置き換える必要があります。

実験でバックエンド／API が必要な場合： フロントエンドのみのビジュアル部分に範囲を絞るか、データをモックするかユーザーに尋ねます。Lab の実験は完全に静的／クライアントサイドである必要があります。

ユーザーが Vercel へのデプロイを省略したい場合： joyco lab に別の href を指定できます。Hub はその URL を iframe で表示するため、一般公開されている URL が必要であることだけ伝えてください。

適切なテンプレートが見つからない場合： ユーザーに尋ねてください。本当に判断が難しい場合は推測しないでください。誤ったテンプレートを選ぶと、セットアップに時間がかかります。