ray-so-code-snippet

ray.so コードスニペット画像ジェネレーター

ray.so を使用して美しいコードスニペット画像を生成し、ローカルに保存します。

要件

• ユーザーはコードスニペットを直接提示するか、コンテキスト内のファイル／選択範囲を指定する必要があります
• 生成前に、利用可能なすべての選択肢を提示して、すべてのスタイル設定をユーザーに必ず確認してください
• スクリーンショットのキャプチャには必ず agent-browser を使用してください（最初に利用可能か確認します）

ワークフロー

ステップ 1：agent-browser の利用可否を確認する

続行する前に、agent-browser が利用可能であることを確認してください。

which agent-browser

agent-browser が PATH に見つからない場合は、このスキルには agent-browser が必要であり、これなしでは続行できないことをユーザーに伝えてください。

ステップ 2：利用可能な選択肢を取得する

curl を使用して、ray.so の GitHub リポジトリから現在のテーマと言語を取得してください。

# Fetch and parse available themes
curl -s "https://raw.githubusercontent.com/raycast/ray-so/main/app/(navigation)/(code)/store/themes.ts" | grep -oE 'id:\s*"[^"]+"' | sed 's/id:\s*"//;s/"//' | sort -u

# Fetch and parse available languages
curl -s "https://raw.githubusercontent.com/raycast/ray-so/main/app/(navigation)/(code)/util/languages.ts" | grep -oE '^[[:space:]]*"?[a-zA-Z0-9+#-]+"?\s*:\s*\{' | sed 's/[[:space:]]*"//g;s/".*//;s/:.*//' | sort -u

ステップ 3：すべてのパラメーターをユーザーに確認する

すべてのパラメーターについて、利用可能な選択肢をすべて提示して AskUserQuestion で必ず質問してください。次の順序で質問します。

3.1 テーマの選択

利用可能なテーマをすべて提示してください。質問には、ステップ 2 で取得したテーマをすべて列挙します。例：

Question: "Which theme would you like?"
Description: "Available themes: [list ALL themes from curl output]"
Options (pick 4 popular ones for quick select):
- breeze (default, purple gradient)
- midnight (cyan-blue)
- vercel (minimalist dark)
- sunset (warm orange)
Note: User can select "Other" to type any theme from the full list

3.2 言語の選択

可能な場合は言語を推定してください。 次の場合は、この質問を省略してください。

• ユーザーが言語を明示している
• コードが明確な拡張子のファイルに由来する（例：.py → python、.js → javascript、.ts → typescript、.rs → rust、.go → go など）
• 構文から言語を明確に特定できる（例：def／import → python、func／package → go、fn／let mut → rust）

言語を確信を持って推定できない場合に限り、この質問をしてください。

Question: "Which language for syntax highlighting?"
Description: "Available languages: [list ALL languages from curl output]"
Options:
- auto (auto-detect)
- javascript
- python
- typescript
Note: User can select "Other" to type any language from the full list

3.3 ダークモード／ライトモード

Question: "Dark or light mode?"
Options:
- Dark mode (default)
- Light mode

3.4 背景

Question: "Show the gradient background?"
Options:
- Yes, show background (default)
- No, transparent/minimal background

3.5 パディング

Question: "How much padding around the code?"
Options:
- 16 (compact)
- 32 (small)
- 64 (medium, default)
- 128 (large)

3.6 行番号

Question: "Show line numbers?"
Options:
- No (default)
- Yes

3.7 タイトル

Question: "Add a title above the code? (e.g., filename)"
Options:
- No title (default)
- Yes, add title
If yes, ask for the title text.

注：出力先のパス／ファイル名は質問しないでください。現在の作業ディレクトリに、適切なファイル名（例：rayso-snippet.png、タイトルが指定されている場合は fibonacci.png など）で保存します。ユーザーが元のリクエストで明示的に別のパスを指定した場合に限り、異なるパスを使用してください。

ステップ 4：ray.so の URL を作成する

重要：すべてのパラメーターはクエリ文字列ではなく、URL ハッシュ（# の後）に含めてください。

シェルコマンドを使用して URL を作成してください。

# 1. Base64 encode the code
CODE_BASE64=$(echo -n 'YOUR_CODE_HERE' | base64)

# 2. URL encode the base64 string
CODE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$CODE_BASE64'))")

# 3. Build the URL with ALL parameters in the hash
# Format: https://ray.so/#param1=value1&param2=value2&code=ENCODED_CODE
# Do NOT include width parameter - let ray.so auto-size to fit content
URL="https://ray.so/#theme=THEME&padding=PADDING&background=BACKGROUND&darkMode=DARKMODE&language=LANGUAGE&code=${CODE_ENCODED}"

# Add optional parameters if needed:
# If lineNumbers: add "&lineNumbers=true" before &code=
# If title: add "&title=URL_ENCODED_TITLE" before &code=

URL ハッシュパラメーター：

パラメーター	値	デフォルト
theme	リスト内の任意のテーマ	breeze
padding	16、32、64、128	64
background	true、false	true
darkMode	true、false	true
language	リスト内の任意の言語、または "auto"	auto
lineNumbers	true、false	false
title	URL エンコードされた文字列	（なし）
width	数値（ピクセル）	auto
code	Base64 エンコード後、URL エンコードされた文字列	（必須）

width に関する注記： 固定幅が特に必要な場合を除き、width パラメーターは含めないでください。指定しない場合、ray.so はコードの内容に合わせてフレームを自動調整し、不要な余白を避けます。

URL 作成例：

# For code: for i in range(23):\n    print(i)
# Theme: midnight, Padding: 64, Dark mode: true, Background: true, Language: python, Title: test.py

CODE='for i in range(23):
    print(i)'
CODE_BASE64=$(echo -n "$CODE" | base64)
CODE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$CODE_BASE64'))")
TITLE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('test.py'))")
URL="https://ray.so/#theme=midnight&padding=64&background=true&darkMode=true&language=python&title=${TITLE_ENCODED}&code=${CODE_ENCODED}"
echo "$URL"

ステップ 5：agent-browser で高品質な画像をキャプチャする

ステップ 1 で確認した agent-browser を必ず使用してください。この方法では html-to-image ライブラリ（ray.so 内部のエクスポート機能と同じ）を使用し、高い pixelRatio で鮮明なテキストをレンダリングします。

重要： セッションの古い状態による問題を避けるため、必ず --session に一意のセッション名を指定してください。

# Generate unique session name
SESSION="rayso-$(date +%s)"

# 1. Set viewport
agent-browser --session $SESSION set viewport 1400 900

# 2. Open the URL
agent-browser --session $SESSION open "$URL"

# 3. Wait for the page to fully render
agent-browser --session $SESSION wait --load networkidle
agent-browser --session $SESSION wait 3000

# 4. Load html-to-image library (same library ray.so uses internally)
agent-browser --session $SESSION eval 'new Promise((r,e)=>{const s=document.createElement("script");s.src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html-to-image.js";s.onload=r;s.onerror=e;document.head.appendChild(s)})'

# 5. Capture at 4x resolution using html-to-image (produces crisp text)
agent-browser --session $SESSION eval 'htmlToImage.toPng(document.querySelector("#frame > div"),{pixelRatio:4,skipAutoScale:true})' > /tmp/rayso-dataurl-$SESSION.txt

# 6. Close the browser
agent-browser --session $SESSION close

# 7. Convert data URL to PNG file
DATAURL=$(cat /tmp/rayso-dataurl-$SESSION.txt | tr -d '"' | tr -d '\n')
echo "$DATAURL" | sed 's/data:image\/png;base64,//' | base64 -d > /path/to/output.png

# 8. Clean up temp file
rm /tmp/rayso-dataurl-$SESSION.txt

重要な注意事項：

• ray.so のエクスポート機能でも使用されている html-to-image ライブラリを使用します
• pixelRatio: 4 にすると、高 DPI の画像が生成され、テキストが鮮明になります（ネイティブ解像度の 4 倍）
• データ URL はスクリーンショットではなく、ライブラリから直接取得します
• ImageMagick は不要です。ブラウザー上で高解像度のレンダリングを行います
• 余分な余白のない適切なサイズで出力されます

ステップ 6：出力を報告して終了する

保存したファイルの場所をユーザーに伝えてください。タスクは完了です。スクリーンショットの保存後に、追加の確認、調査、検証を行わないでください。

完全な例

ユーザー：「この Python 関数のコードスニペット画像を作成してください」

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

1. which agent-browser を確認します — 利用可能であることを確認済みです

2. テーマと言語を取得します：

curl -s "https://raw.githubusercontent.com/raycast/ray-so/main/app/(navigation)/(code)/store/themes.ts" | grep -oE 'id:\s*"[^"]+"' | sed 's/id:\s*"//;s/"//' | sort -u

3. AskUserQuestion でユーザーにパラメーターを尋ねます：

   • テーマ：ユーザーが「midnight」を選択
   • 言語：def 構文から python と推測 — 質問しません
   • ダークモード：ユーザーが「Dark mode」を選択
   • 背景：ユーザーが「Yes」を選択
   • パディング：ユーザーが「64」を選択
   • 行番号：ユーザーが「No」を選択
   • タイトル：ユーザーが「No title」を選択

4. URL を作成します（すべてのパラメーターをハッシュに含め、自動サイズ調整のため width は指定しません）：

CODE='def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)'
CODE_BASE64=$(echo -n "$CODE" | base64)
CODE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$CODE_BASE64'))")
URL="https://ray.so/#theme=midnight&padding=64&background=true&darkMode=true&language=python&code=${CODE_ENCODED}"

5. 高品質な画像をキャプチャします：

SESSION="rayso-$(date +%s)"

agent-browser --session $SESSION set viewport 1400 900
agent-browser --session $SESSION open "$URL"
agent-browser --session $SESSION wait --load networkidle
agent-browser --session $SESSION wait 3000

# Load html-to-image library
agent-browser --session $SESSION eval 'new Promise((r,e)=>{const s=document.createElement("script");s.src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html-to-image.js";s.onload=r;s.onerror=e;document.head.appendChild(s)})'

# Capture at 4x resolution
agent-browser --session $SESSION eval 'htmlToImage.toPng(document.querySelector("#frame > div"),{pixelRatio:4,skipAutoScale:true})' > /tmp/rayso-dataurl-$SESSION.txt
agent-browser --session $SESSION close

# Save as PNG
DATAURL=$(cat /tmp/rayso-dataurl-$SESSION.txt | tr -d '"' | tr -d '\n')
echo "$DATAURL" | sed 's/data:image\/png;base64,//' | base64 -d > ./fibonacci.png
rm /tmp/rayso-dataurl-$SESSION.txt

6. 報告します：「コードスニペット画像を ./fibonacci.png に保存しました」

画像の解像度と品質

このスキルでは、pixelRatio: 4 を指定して html-to-image ライブラリを使用し、テキストが鮮明でくっきりとした高品質な画像を生成します。これは ray.so が組み込みのエクスポート機能で使用しているものと同じレンダリング方式です。

出力品質：

• デフォルト：ネイティブ解像度の 4 倍（フレームをコンテンツに合わせて自動調整し、その後 4 倍でレンダリング）
• 低解像度の画像を拡大するのではなく、高 DPI でテキストをレンダリング
• グラデーション背景とすべての CSS スタイルを維持
• 不要な余白なし（コードに合わせてフレームを自動調整）

解像度の調整：

• ファイルサイズを小さくする場合：eval コマンドの pixelRatio:4 を pixelRatio:2 に変更します
• 最高品質にする場合：pixelRatio:6 を使用します（ray.so の「6x」エクスポートオプションと同じです）

幅の指定：

• 固定幅が必要な場合（複数の画像でサイズを統一する場合など）に限り、URL に &width=NUMBER を追加します

トラブルシューティング

• agent-browser が利用できない場合： ユーザーに伝え、処理を続行しないでください
• curl でテーマや言語を取得できない場合は、次の一般的なデフォルトを使用します：
  • テーマ：breeze, midnight, candy, crimson, falcon, meadow, raindrop, sunset, vercel, supabase, tailwind
  • 言語：auto, javascript, typescript, python, rust, go, java, ruby, swift, kotlin, css, html, json, yaml, bash
• パラメーターが適用されない場合： すべてのパラメーターがクエリ文字列ではなく URL ハッシュ（# の後）に含まれていることを確認します
• タイトルが表示されない場合： タイトルパラメーターはハッシュに含める必要があります：#title=filename.py&code=...
• html-to-image の読み込みに失敗する場合： ネットワーク接続を確認します。ライブラリは jsdelivr CDN から読み込まれます
• キャプチャ結果が空の場合： フレームセレクター #frame > div が変更された可能性があります。ページ構造を調べてください
• 非常に長いコードスニペットは ray.so で切り詰められる場合があります。複数の画像に分けることを検討してください
• ページが正しく読み込まれない場合は、待機時間を延長します（4000ms 以上を試してください）
• 空白のページが表示される場合： --session フラグを使って、新しい一意のセッション名を指定します
• データ URL の形式が正しくない場合： base64 デコードの前に、引用符と改行を削除してください