asobi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d85221ad8a10d1484ffcde0c42fd47a55c0035e7e876a0f614df340b5a50bb19
+  data.tar.gz: fee1f511342cf1eec4eaed1120fbd2be148dfee92fd54c22d7d988f6d2024835
+SHA512:
+  metadata.gz: 6d4597d181770c36aa9ba52c2288b0e997082472e6fee69268f69cb8857f664d38b44c5e7f1cc516fd011ed780f7a976ec26c7dc70e1526d769ba2b696df81a5
+  data.tar.gz: 687f8f4aeb6daa466c1d3dbe4ae4e322fe11928ef6f3140db7c983f03420c6ecc7694482e0594d3dd31130e6ea7b4679a4c2009f584fa6eea7c38bf3aa3b360a

data/DESIGN.md

@@ -0,0 +1,388 @@
+# asobi 設計書
+
+Ruby のメディアアート用ライブラリ。gem 名は `asobi`(遊び)、モジュール名は `Asobi`。
+この文書が実装の唯一の基準。コードと食い違ったら、この文書を正とする。
+
+## 1. 哲学
+
+1. **オブジェクトを絵として扱い、絵をオブジェクトとして扱う。**
+   - どの Ruby オブジェクトにも「絵になって」(`to_art`)と頼める。
+   - 絵は変数に入れられる値で、メソッドを呼ぶと新しい絵が返る。画面に命令して描くのではない。
+2. **書く人が楽しく、わかりやすく、すぐに遊べる。**
+   - 3つがぶつかったら **すぐ遊べる** を一番に守る。次に わかりやすい、その次に 楽しい。
+
+p5.js / Processing の `setup` / `draw` とは別物。グローバルな描画状態は持たない。
+
+対象は「作品を作る人」。ただし Ruby を学び始めた人が読めること。
+
+### 哲学から出る決まり
+
+- **省略しても動く。** どの数字も省略でき、いい感じの値で絵が出る。必須の引数で止めない。
+- **言葉で読める。** メソッド名は英語の単語。数字にはキーワード引数で名前を付けられる。
+- **記号は2つだけ。** `*`(増やす)と `+`(重ねる)。
+- **絵は不変。** どのメソッドも新しい絵を返し、元の絵は変わらない。同じ値の絵は `==` で等しい。
+- **エラーは先生。** 何が足りないかと、直し方の例を必ず書く。パソコンの言語が日本語なら日本語、それ以外は英語。
+- **外部ソフトに頼らない。** 実行時の依存は Ruby 標準ライブラリだけ。ブラウザ内(ruby.wasm)でもコアが動くこと。
+
+## 2. 使い方の全体像
+
+```ruby
+require "asobi"
+
+petal  = ellipse(width: 12, height: 32).move(up: 22)
+flower = petal.repeat(8).in_fan.colored(:crimson, :navy)
+
+show flower.spin(every: 4)
+```
+
+```
+$ ruby flower.rb      # ブラウザが開いて絵が出る。保存するたびに差し替わる
+$ asobi               # 見本 play.rb を作って、同じように開く
+```
+
+`require "asobi"` だけで、形の言葉(`circle` など)と `show` がどこでも使え、
+数字・配列・文字などに `to_art` が付く。
+Ruby 本体に手を入れたくない人は `require "asobi/pure"`(`Asobi.circle(...)`、`Asobi.art(8)` と書く)。
+
+## 3. 単位
+
+- **長さ**:単位なしの数字。絵の中での比率として効く。画面には自動で収める。
+- **角度**:度。`rotate(45)` は時計回りに45度。`0.25.turn` は 90.0(`Numeric#turn` / `turns`)。
+- **時間**:秒。
+- **座標**:原点は絵の中心。x は右、y は下が正。ただし利用者には `up:` `down:` `left:` `right:` で書かせ、y の向きを意識させない。
+
+## 4. 形(どれも原点が中心。引数はすべて省略可)
+
+最初の位置引数は「主な大きさ」の短縮形として受け付ける(`circle(12)` は `circle(radius: 12)`)。
+
+| 言葉 | 引数と既定値 |
+|---|---|
+| `circle` | `radius: 10` |
+| `ellipse` | `width: 30, height: 20` |
+| `rect` | `width: 30, height: 20` |
+| `square` | `size: 20` |
+| `triangle` | `size: 20`(正三角形、上向き) |
+| `polygon` | `sides: 6, radius: 10`(頂点が上) |
+| `star` | `points: 5, radius: 10, inner: radius * 0.45` |
+| `line` | `length: 20`(横向きの線。塗りなし・黒い線) |
+| `text` | `text("ruby", size: 16, font: nil)` |
+| `path` | `path([0, 0], [40, -30], [80, 0], closed: false, smooth: false)` 点を順につなぐ。`smooth: true` で滑らかな曲線 |
+| `arc` | `radius: 20, from: 0, to: 180`(角度は真上が0、時計回り。線) |
+| `wave` | `length: 100, height: 10, waves: 3`(線) |
+| `ring` | `radius: 20, thickness: 4`(ドーナツ型。穴は透ける) |
+| `heart` | `size: 20` |
+| `petal` | `length: 20, width: 10`(根元が原点、上に伸びる) |
+| `moon` | `size: 20`(三日月) |
+| `drop` | `size: 20`(しずく) |
+| `cloud` | `size: 30` |
+| `space` | `width: 10, height: width`(見えないが場所を取る) |
+| `nothing` | 何もない絵 |
+
+色の助け:`hsl(hue, saturation = 70, lightness = 50)`(hue は度 0〜360、他は 0〜100)、`gray(0..100)`。
+
+## 5. 絵にできること(`Asobi::Art`)
+
+### 合わせる
+
+| 言葉 | 意味 |
+|---|---|
+| `a.on(b)` | b の上に a を置く(a が手前) |
+| `a.under(b)` | a の上に b を置く(b が手前) |
+| `a + b` | `a.under(b)` と同じ。あとに書いたほうが手前 |
+| `a.repeat(12)` / `a * 12` | 12個に増やす(並べるまでは同じ場所に重なっている) |
+| `a.beside(b, gap: 0)` | 横に並べる(a が左) |
+| `a.above(b, gap: 0)` | 縦に並べる(a が上) |
+
+`with` `|` `/` は用意しない。
+
+### 変える
+
+| 言葉 | 意味 |
+|---|---|
+| `move(right: 0, left: 0, up: 0, down: 0)` | 動かす |
+| `rotate(45)` | 時計回りに回す(度) |
+| `scale(2)` / `scale(width: 2, height: 1)` | 拡大・縮小 |
+| `grow(to: 2)` / `shrink(to: 0.5)` | `scale` の読みやすい別名 |
+| `mirror` | 左右を反転 |
+| `flip` | 上下を反転 |
+
+### 色
+
+| 言葉 | 意味 |
+|---|---|
+| `colored(:crimson)` | 塗る色 |
+| `colored(:crimson, :navy, ...)` | 並んだ絵(Many)なら、直下の要素に順番に繰り返して塗る。単独の絵なら最初の色 |
+| `outlined(:black, width: 1)` | 塗りなしで線だけ |
+| `stroke(:black, width: 1)` | 塗りはそのままで線を足す |
+| `opacity(0.5)` | 透明度 |
+
+色は CSS の色名のシンボル(`:crimson`)か文字列(`"#ff0066"`、`hsl(...)` の戻り値)。
+既定は黒で塗り、線なし。背景は白(「白い紙に黒」)。
+同じ絵に2回色を付けたら、あとのほうが勝つ。まとまりに付けた色は、中で個別に付けた色を上書きしない(SVG と同じ)。
+
+### 効果
+
+平らな塗りから先へ進むための言葉。絵にも動きにも使える。数字はすべて省略でき、大きさは絵の長さと同じ単位。
+
+| 言葉 | 意味と既定値 |
+|---|---|
+| `glowing(size: 4, color: nil)` | 縁がにじんで光る。`color` を省くと絵自身の色で光る |
+| `blurred(amount: 2)` | ぼかす |
+| `blended(:screen)` | 下の絵との混ざり方。`:screen`(重なると明るく)、`:multiply`(暗く)、`:overlay`、`:lighten`、`:darken`、`:difference`、`:normal` |
+| `shadowed(down: 2, right: 0, blur: 3, color: :black, opacity: 0.4)` | 影を落とす |
+| `clipped_by(shape)` | `shape` の形の窓から覗いたように切り抜く。`shape` は置かれた位置のまま使う |
+| `colored(from: :crimson, to: :navy)` | グラデーション。上から下へ色が変わる。`angle: 90` で向きを変え(度、時計回り)、`around: true` で中心から外へ。並んだ絵(Many)では全体にまたがって1回流れる |
+
+- 最初の位置引数は主な数字の短縮形(`glowing(8)`、`blurred(4)`)。
+- 光・ぼかし・影は絵の外側にはみ出す。`bounds` や画面への収め方は、はみ出しぶんを含める。
+- 同じ絵は、効果を付けても `==` で等しく、SVG も同じ文字列になる(定義の id は中身から決め、乱数や連番を使わない)。
+  1つのページに複数の絵を埋め込んでも id がぶつかって壊れないこと。
+- 効果は Ruby 標準ライブラリだけで SVG として書き出す(フィルター、グラデーション、クリップパス、`mix-blend-mode`)。
+
+画面全体のざらつきは絵ではなく出し方の指定:
+
+```ruby
+show flower, grain: true        # 紙やフィルムのような細かい粒を全体に乗せる
+show flower, grain: 0.3         # 強さ(0 から 1。true は 0.12)
+flower.save("flower.svg", grain: true)
+```
+
+### 測る・出す
+
+`width` `height` `bounds`、`to_svg`、`save("flower.svg")`。
+
+## 6. 並べる(`Asobi::Many`)
+
+`repeat` や配列の `to_art` が返す「絵の集まり」。それ自体が1枚の絵で、`Enumerable` でもある。
+
+| 言葉 | 省略時 |
+|---|---|
+| `in_row(gap: 0)` | すき間なし |
+| `in_column(gap: 0)` | すき間なし |
+| `in_grid(columns: nil, gap: 0)` | 列数は個数の平方根を切り上げ |
+| `in_ring(radius: nil, facing_out: false)` | 隣どうしが重ならない半径を自動計算 |
+| `in_fan(over: 360)` | 中心のまわりに少しずつ回す(花びら向け) |
+| `in_spiral(spacing: nil)` | 絵の大きさから自動 |
+| `scattered(over: nil, seed: nil)` | 広さは個数と大きさから自動。`over: 200` は正方形、`over: [300, 100]` は横×縦 |
+| `change_each { \|one, t, i\| ... }` | 1つずつ変える。`t` は 0.0 から 1.0 未満、`i` は番号 |
+
+どれも位置引数の短縮形を受け付ける(`in_ring(60)`、`in_grid(4)`)。
+
+### ランダム
+
+- `seed:` を書かなければ、**実行のたびに違う絵**になる。
+- ただし1回の起動の中では変わらない。ライブ表示中にファイルを保存し直しても、ばらまき方は保たれる。
+- 仕組み:起動時に「その回の種」を1つ決める。スケッチを評価するたびに呼び出しカウンタを0に戻し、
+  `seed:` のない `scattered` は「その回の種 + 何番目の呼び出しか」から乱数を作る。
+- `seed: 7` と書けば、いつ誰が実行しても同じ絵。
+
+## 7. to_art(オブジェクトを絵にする)
+
+| 頼む相手 | なる絵 |
+|---|---|
+| 数字 `8` | 大きさ8の丸。`8.to_art(as: star)` で形を渡せる(その形を、半分の大きさが8になるよう拡大縮小) |
+| マイナスの数字 | 同じ大きさで、塗りなしの線だけ |
+| `0` | 何もない絵 |
+| 配列・範囲 | 中身をそれぞれ絵にして横に並べる(すき間4)。`as:` は中身すべてに伝わる |
+| 配列の配列 | 行を縦に積む(表になる) |
+| 文字列・シンボル | その文字そのままの絵(`text` と同じ) |
+| ハッシュ | 1組ずつ「キーの絵 beside 値の絵」を作り、縦に積む |
+| `nil` | 何もない絵 |
+| 動き(Motion)を含む配列 | 全体が動きになる |
+| `to_art` を持つオブジェクト | その `to_art` の結果 |
+
+自作クラスは **`to_art` を書くだけ** で、`show`、配列の `to_art`、`on` / `under` / `beside` などの相手として渡せる。
+`planet.rotate(20)` のように直接メソッドを呼びたいときだけ、クラスに `include Asobi::Art` を足す
+(`Enumerable` が `each` だけを求めるのと同じ)。
+
+`Asobi.art(object, as: nil)` が変換の入口。変換できないときは、`to_art` を書けばよいことを伝えるエラーにする。
+
+## 8. 動き(`Asobi::Motion`)
+
+動きは「時刻(秒)→ 絵」の関数。フレーム番号や内部状態は持たない。
+だから途中で差し替えても続きから再生でき、同じ時刻は必ず同じ絵になる。
+
+| 言葉 | 意味と既定値 |
+|---|---|
+| `spin(every: 4, clockwise: true)` | 回り続ける |
+| `pulse(every: 1, to: 1.2)` | 膨らんで戻る |
+| `sway(every: 2, by: 10)` | 左右に揺れる(度) |
+| `orbit(radius: nil, every: 4)` | 円周を回る。半径は省略時、絵の大きさの2倍 |
+| `fade(every: 2, to: 0.2)` | 薄くなって戻る |
+| `bounce(height: 20, every: 1)` | 弾む |
+| `drift(right: 0, left: 0, up: 0, down: 0, every: 4)` | 行って戻る。全部省略なら右に絵の幅ぶん |
+| `shift_color(from: nil, to: :crimson, every: 4)` | 色が移り変わって戻る。`from` 省略時は黒 |
+| `one_by_one` | 並んだ絵の動きを、1つずつ時間差にする(波になる)。動きの言葉の直後に書く |
+| `trail(count: 5, gap: nil)` | 残像。`gap` 秒ずつ前の時刻の絵を、だんだん薄くして下に重ねる。`gap` を省くと見た目のよい短い間隔。止まった絵に付けても何も変わらない |
+| `animate(4) { \|picture, t\| ... }` | 自作。`t` は 0.0 から 1.0 未満を繰り返す |
+
+- 動きにも、絵と同じ言葉(第5・6節)がすべて使える。その場合はどの時刻の絵にも同じことをする。
+  例:`flower.spin(every: 8).pulse(every: 1).colored(:crimson)`
+- 絵と動きを合わせると動きになる(`ring.on(dot.pulse)`)。
+- `at(seconds)` でその時刻の絵、`frames(fps: 30)` で1周ぶんの絵の遅延列(Enumerator::Lazy)。
+- `every` は「元に戻るまでの秒数」。合成したときは最小公倍数(60秒を超えるなら長いほう)。
+- `save("flower.html")` で、単体で再生できるページを書き出す。
+
+マウス・音・拍などの外からの入力は、最初の版では扱わない。
+
+## 9. 画面に出す
+
+```ruby
+show flower                          # 自動で画面にぴったり収める
+show flower, on: :black              # 背景色
+show flower, paper: [800, 800]       # 800×800 の紙の中央に置く(はみ出たら切れる)
+```
+
+- `show` を複数回呼んだら、最後のものが出る。
+- **`ruby flower.rb` で実行したとき**:スクリプトの終わりに(`at_exit`)ライブ表示を始める。
+  ブラウザを開き、そのファイルを見張り、保存のたびに評価し直して差し替える。Ctrl-C で終了。
+- **irb で `show` したとき**:裏でライブ表示を始め、`show` のたびに差し替える。
+- 書き間違いがあるときは、最後に出せた絵を残したまま、エラーを画面の下に出す。
+- ポートは 4567。使用中なら次の番号を試す。
+- 環境変数 `ASOBI_LIVE=0` のときはライブ表示を始めない(テストや CI 用)。
+
+### ブラウザの画面
+
+- ふだんは絵だけ。
+- マウスを動かしたときだけ、端に小さく操作(録画、コード表示)が出て、数秒で消える。
+- `c` キーで、いまのコードを絵に半透明で重ねる。`r` キーで録画の開始・停止。
+- 録画はブラウザの機能だけで行い、動画ファイルをダウンロードさせる。
+
+### 絵をブラウザに渡す形(Reel)
+
+Ruby 側と再生画面の間の取り決め。ライブ表示、`save("x.html")`、Web の遊び場が同じ再生プログラムを使う。
+
+```json
+{
+  "frames": ["<g>...</g>", "..."],
+  "fps": 30,
+  "view": [-76.0, -76.0, 152.0, 152.0],
+  "background": "white",
+  "code": "require \"asobi\"\n...",
+  "error": null
+}
+```
+
+- `frames`:SVG の中身(`<svg>` タグは含まない)。止まった絵は1枚で `fps` は 1。
+- `view`:viewBox `[x, y, 幅, 高さ]`。動きのときは全フレームを含む範囲。`paper:` 指定時は紙の範囲。
+- `error`:文字列なら、`frames` などは省かれていてよい。画面は前の絵を残してエラーを出す。
+- フレーム数の上限は 900。超えるときは fps を下げる。
+- 再生は「ページを開いてからの経過秒 × fps」を frames の数で割った余り。差し替えても時計は進み続ける。
+
+## 10. コマンド
+
+```
+asobi              play.rb がなければ見本を作り、ライブ表示する
+asobi FILE.rb      そのスケッチをライブ表示する
+asobi version
+```
+
+## 11. サイト(`site/`):説明書と遊び場
+
+説明書と遊び場を1つの静的サイトにまとめ、互いにつなげる(p5js.org がリファレンス・見本・エディタをつないでいるのと同じ考え方)。
+インストールなしで読めて、その場で試せる。ruby.wasm でコアをブラウザ内で動かす。
+
+### ページ
+
+| ページ | 中身 |
+|---|---|
+| トップ | 哲学を2行で。動いている見本。「遊んでみる」ボタン |
+| はじめかた | インストールから最初の絵まで。形 → 増やす → 並べる → 色 → 動かす の順に読める手引き |
+| リファレンス | すべての言葉の一覧。言葉ごとに、短い説明・引数と既定値・コード例・その結果の絵 |
+| 見本集 | 完成した作品のコードと絵 |
+| 遊び場 | 左にコード、右に絵。書き換えると絵が変わる |
+
+### つなぎ方
+
+- **どのコード例も、その場で動く。** 説明書の中のコード例はすべて、隣に実際の絵(動きなら動いている絵)が出る。
+- **どのコード例からも遊び場へ行ける。** 各例に「遊び場で開く」ボタンがあり、そのコードが入った状態で遊び場が開く(コードは URL の `#` 以降に入れる。サーバーには送らない)。
+- **遊び場から説明書へ戻れる。** 遊び場に言葉の一覧を置き、選ぶとその言葉のリファレンスが開く。
+- **遊び場のコードは URL で共有できる。**
+
+### 決まり
+
+- 英語と日本語の両方(`/` と `/ja/`)。
+- 外部サービスに頼らない静的ファイルだけ。`rake site` で `site/` 以下から `_site/` に書き出す。
+  作るための道具は Ruby 標準ライブラリ(ERB、YAML など)だけ。
+- 言葉の説明とコード例は1か所のデータ(YAML)に持ち、リファレンスのページと遊び場の言葉一覧の両方をそこから作る。
+- **コード例はビルド時に実際に実行する。** 動かない例があればビルドを失敗させる(説明書とコードの食い違いを防ぐ)。
+  そのとき最初の絵を SVG としてページに埋め込み、ruby.wasm の読み込みを待たずに絵が見えるようにする。
+- 再生プログラムは第9節と共通(`lib/asobi/web/player.js`)。
+- ソケットやファイル監視など、ブラウザで動かないものはコアに混ぜない。
+
+## 12. エラーメッセージ
+
+`Asobi::Messages` に英語と日本語を並べて持つ。`LC_ALL` → `LC_MESSAGES` → `LANG` の順に見て、`ja` で始まれば日本語。
+`Asobi.language = :ja` で切り替えられる。どのメッセージにも直し方の例を入れる。
+
+```
+in_grid の columns には 1 以上の整数を渡してください。例：in_grid(columns: 3)
+in_grid needs a whole number of columns, like in_grid(columns: 3)
+```
+
+## 13. 作り
+
+- Ruby 3.2 以上。実行時の依存は標準ライブラリだけ。テストは minitest(`rake test`)。
+- 絵の実体は不変の値(`Data`)。`Asobi::Art` は `to_art` だけを頼りにするミックスイン。
+- ファイル構成:
+
+```
+lib/asobi.rb              全部入り(pure + core_ext + top_level + sketch)
+lib/asobi/pure.rb         Ruby 本体に手を入れないコアだけ
+lib/asobi/version.rb
+lib/asobi/geometry.rb     アフィン変換、外接箱
+lib/asobi/art.rb          Asobi::Art、Asobi.art
+lib/asobi/nodes.rb        形の実体(Circle、Rect、Path、Text、Styled、Transformed ...)
+lib/asobi/many.rb         Asobi::Many と並べ方
+lib/asobi/shapes.rb       形の言葉(第4節)
+lib/asobi/color.rb        色名の表、補間、hsl
+lib/asobi/svg.rb          SVG への書き出し
+lib/asobi/messages.rb     エラーメッセージ(英語・日本語)
+lib/asobi/random.rb       その回の種と呼び出しカウンタ
+lib/asobi/motion.rb       Asobi::Motion と動きの言葉
+lib/asobi/reel.rb         Reel(第9節)
+lib/asobi/core_ext.rb     to_art と turn を Ruby 本体に付ける
+lib/asobi/top_level.rb    circle などと show をどこでも使えるようにする
+lib/asobi/sketch.rb       show、スケッチの評価
+lib/asobi/live.rb         ライブ表示のサーバー(ソケットを使うのはここだけ)
+lib/asobi/web/player.js   再生プログラム(ライブ・書き出し・遊び場で共通)
+lib/asobi/web/live.html   ライブ表示のページ
+exe/asobi
+site/                     説明書と遊び場の元(第11節)。rake site で _site/ に書き出す
+test/
+examples/
+README.md / README.ja.md
+```
+
+## 14. 実装で決まった細部
+
+設計の時点で決めていなかったが、実装で決めたこと。上の節と食い違う場合はこちらが正。
+
+- **省略時の値**:`repeat` は2個、`rotate` は45度、`scale` は2倍、`opacity` は0.5、`colored` は `:crimson`、`text` は "asobi"。
+- **名前なしの短縮形**:動きの言葉も最初の値は名前なしで書ける(`spin(8)`、`shift_color(:navy, :gold)`)。
+- **`orbit` の半径**:省略時は絵の長いほうの辺の長さ。
+- **並べ方の言葉は1つの絵にも使える**:1つだけの集まりとして扱う(`circle.in_ring`)。
+- **`one_by_one`**:並んだ絵の1つ1つが、自分の中心のまわりで順番に動く(輪の形は崩れない)。動きの言葉の直後に書く。
+  `one_by_one` を付けないときは、まとまり全体が原点のまわりで動く。
+- **変える言葉は原点のまわりで働く**:`mirror` `flip` `rotate` `scale` は絵自身の中心ではなく原点が基準。
+- **`colored` と線**:線だけの絵(`line`、`arc` など)に `colored` すると線の色が変わる。
+- **スケッチの評価**:`Asobi::Sketch.run(source, name:)` が文字列から、`evaluate(path)` がファイルから Reel を返す。
+  スケッチのエラーでは例外を投げず、エラーの Reel を返す。
+- **Reel の fps**:1周を等間隔に切るので、fps は小数になることがある(`fps = コマ数 / every`)。
+- **サイト**:ページは `guide.html`、`ja/guide.html` のような平らなファイル。動く例の Reel は1つ 1.5MB まで。
+  超えるとコマを間引いて警告する。遊び場は ruby.wasm(`@ruby/3.4-wasm-wasi`、jsDelivr から読み込む)で動く。
+- **効果の細部**:
+  - `colored` は `from:` `to:` `angle:` `around:` のどれかがあればグラデーションになる。省いた色は crimson → navy。
+    向きは 0 が上から下、90 が右から左。絵を回すとグラデーションも一緒に回る。
+  - 並んだ絵(Many)へのグラデーションは全体に1回流れ、中の絵が個別に持っていた色は消える。
+  - 同じ効果をもう一度書くと置き換わる。効果は書いた順に外側へ重なり、`blended` だけは常に一番外側になる。
+  - `clipped_by` を形なしで書くと、絵の中央の丸い窓で切り抜く。
+  - `trail` の間隔は省略時 0.05 秒。重ねる絵は 0.5 から 0.1 へ薄くなる。残像の枚数ぶん、1コマのデータが増える。
+  - ざらつきは各コマの末尾に同じ小さな定義を足して実現する(再生プログラムは変更なし)。
+    画面の形が絵と違うときの左右・上下の余白にもかかるよう、絵の範囲の3倍に敷く。
+- **まだない安全装置**:ライブ表示には、終わらないスケッチ(無限ループ)を打ち切る仕組みがない。遊び場は15秒で打ち切る。
+
+## 15. 最初の版に入れないもの
+
+マウス・音・拍への反応、画像ファイルの読み込み、別の絵への変身、PNG 書き出し、
+実行そのものを絵にする機能(別の哲学なので入れない)。

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hayato1031
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.ja.md

@@ -0,0 +1,154 @@
+# asobi
+
+[English](README.md)
+
+asobi（遊び）は、Ruby で図形を組み合わせて、SVG の静止画やループアニメーションを作るライブラリです。たとえば花びらを8枚並べると、ひとつの花ができます。花も Ruby のオブジェクトなので、`spin` を呼ぶと花ごと回ります。
+
+```ruby
+require "asobi"
+
+flower = petal.repeat(8).in_fan.colored(:crimson, :navy)
+show flower.spin(every: 8)
+```
+
+<img src="docs/first-sketch.svg" width="240" alt="深紅と紺の花びらが交互に8枚並んだ花。">
+
+## 最初のスケッチを動かす
+
+用意するのは Ruby 3.2 以上とブラウザです。リポジトリのルートで次のコマンドを実行します。ライブラリの実行に追加の gem は要りません。
+
+```sh
+ruby exe/asobi
+```
+
+初回は、上の花を描く `play.rb` が作られ、ブラウザで花が回り始めます。すでに同名のファイルがある場合は、そのスケッチが開きます。
+
+`repeat(8)` を `repeat(12)` に変えて保存すると、花びらが12枚に増えます。`spin(every: 8)` の `8` を `2` に変えると、今度は2秒で1回転します。ファイルを保存するたびに表示が更新されます。終了するには、コマンドを実行したターミナルで Ctrl+C を押します。
+
+ほかの作品を開くには、`ruby exe/asobi examples/flower.rb` のようにファイルを指定します。ブラウザを自分で開く場合は `--no-open` を付けて、ターミナルに表示された URL にアクセスしてください。`--port 5000` を付けると、5000 番から空いているポートを探します（既定は 4567 番）。
+
+別のディレクトリでも `asobi` コマンドを使いたいときは、リポジトリのルートで gem を作ってインストールします。その後は、作品を置きたいディレクトリで `asobi` を実行できます。既存のスケッチは `asobi sketch.rb` や `ruby sketch.rb` で開けます。
+
+```sh
+gem build asobi.gemspec --output asobi.gem
+gem install --local ./asobi.gem
+```
+
+## スケッチの書き方
+
+この節の例を試すときは、`play.rb` の先頭にある `require "asobi"` を残し、その下を例のコードに置き換えてください。
+
+### 図形を重ねる、並べる
+
+`petal(40, 16)` は長さ40、幅16の花びらです。`in_fan` で根元を中心に放射状に並べ、`+` で金色の円を手前に重ねます。`scale(0.6)` は元の60%の大きさの花を返します。`beside` で元の花と並べると、大きな花と小さな花がひとつの絵になります。
+
+```ruby
+petals = petal(40, 16).repeat(8).in_fan.colored(:crimson, :navy)
+flower = petals + circle(5).colored(:gold)
+show flower.beside(flower.scale(0.6), gap: 12)
+```
+
+長さは絵の中での大きさを表します。表示するときは絵全体が画面に収まるように拡大・縮小されます。回転角は度で指定し、`rotate(90)` なら時計回りに4分の1回転します。
+
+### 数列を絵にする
+
+`to_art` は Ruby の値を絵に変換します。この例ではフィボナッチ数列の各項が星の大きさになり、小さな星から順に横一列に並びます。`as:` を省くと、各項を半径とする円になります。
+
+```ruby
+fib = [1, 1, 2, 3, 5, 8, 13, 21]
+show fib.to_art(as: star).colored(:gold, :orange), on: :black
+```
+
+### 自分のクラスで絵を作る
+
+自作クラスに絵を返す `to_art` を定義すると、そのインスタンスを `show` に渡せます。さらに `Asobi::Art` をインクルードすると、インスタンスに対して直接 `spin` や `beside` を呼べます。
+
+```ruby
+class Flower
+  include Asobi::Art
+
+  def initialize(count, color)
+    @count = count
+    @color = color
+  end
+
+  def to_art
+    petal.repeat(@count).in_fan.colored(@color)
+  end
+end
+
+show Flower.new(7, :coral).spin(every: 4)
+```
+
+### 動きに時間差をつける
+
+輪に並べた点を `pulse` で2倍まで膨らませ、元の大きさに戻します。直後に `one_by_one` を付けると、それぞれの点が少しずつ遅れて膨らみ、波が輪を一周します。
+
+```ruby
+dots = circle(5).repeat(24).in_ring.colored(:gold, :orange)
+show dots.pulse(every: 2, to: 2).one_by_one, on: :black
+```
+
+| やりたいこと | 主なメソッドとオプション |
+| --- | --- |
+| 形を作る | `circle`、`rect`、`star`、`text`、`path`、`wave`、`heart`、`petal` |
+| 図形を配置する | `in_row` で横一列、`in_grid` で格子状、`in_ring` で円周上、`in_spiral` でらせん状に並べる |
+| 色や質感を変える | `colored(from: :gold, to: :crimson)` でグラデーション、`glowing` で発光、`shadowed` で影、`clipped_by` で切り抜き |
+| 動きを作る | `spin` で回転、`sway` で揺れ、`orbit` で公転、`trail` で残像を付ける。独自の動きは `animate` で定義する |
+| 表示を整える | `show` の `on:` で背景色、`paper:` で用紙の寸法、`grain: true` で粒子感を指定する |
+
+## 作品の保存と録画
+
+静止画は SVG、アニメーションはブラウザでそのまま再生できる HTML に保存できます。次の例は、スケッチを実行したディレクトリに2つのファイルを書き出し、同じアニメーションをライブ表示します。
+
+```ruby
+flower = petal.repeat(8).in_fan.colored(:crimson, :navy)
+motion = flower.spin(every: 4)
+
+flower.save("flower.svg")
+motion.save("flower.html")
+show motion
+```
+
+アニメーションの途中を静止画にするには、`motion.at(1).save("frame.svg")` のように秒数を指定します。
+
+ライブ表示中にポインターを動かすと操作ボタンが現れます。`c` キーでソースコードの表示を切り替えられます。録画に対応しているブラウザでは、`r` キーで録画を開始し、もう一度押すと動画をダウンロードできます。形式はブラウザによって MP4 または WebM です。編集中にエラーが起きたときは、直前に描けた絵とエラーメッセージが表示されます。
+
+## 既存の Ruby プログラムに組み込む
+
+`require "asobi"` を使うと、`circle` などをトップレベルで呼べるようになり、数値や配列に `to_art` が加わります。既存のプログラムで Ruby の標準クラスを拡張せずに使うには、`asobi/pure` を読み込みます。次のコードをリポジトリのルートに `export.rb` として保存し、`ruby -Ilib export.rb` を実行すると、紺色の星を3つ並べた `stars.svg` ができます。
+
+```ruby
+require "asobi/pure"
+
+stars = Asobi.art([3, 1, 4], as: Asobi.star)
+stars.colored(:navy).save("stars.svg")
+```
+
+## 作例とドキュメント
+
+リポジトリには、1ファイルで動くスケッチが入っています。
+
+- 数列を形にする仕組みを試すなら [数列の星](examples/sequence.rb)
+- 発光、色の合成、残像を重ねるなら [ネオンの花](examples/neon_flower.rb)
+- 自作クラスで複数の軌道を描くなら [惑星](examples/planets.rb)
+- ほかの作品を探すなら [作例一覧](examples/README.md)
+
+日本語のドキュメントには、入門ガイド、引数や既定値を調べるリファレンス、作例を編集して動かせる「遊び場」があります。リポジトリのルートで次のコマンドを実行して、ドキュメントを生成します。
+
+```sh
+bundle install
+bundle exec rake site
+```
+
+生成された `_site/ja/index.html` をブラウザで開くと、日本語版を読めます。「遊び場」でコードを編集して実行するには、CDN から ruby.wasm を読み込むためのインターネット接続が必要です。
+
+テストは `bundle exec rake test` で実行できます。ライブラリ本体に加え、ドキュメントや作例のスケッチも検証します。ライブラリの設計については[設計書](DESIGN.md)を参照してください。
+
+## 不具合報告・機能提案
+
+日本語・英語どちらでも歓迎です。不具合の場合は、問題が起きる短いスケッチがあると再現しやすくなります。機能のアイデアは「こんな絵を描きたい」「こんな動きを作りたい」から気軽にどうぞ。[Issue を作成する](https://github.com/Hayato1031/asobi/issues/new/choose)
+
+## ライセンス
+
+[MIT ライセンス](LICENSE)