[smalruby3-editor-bot]

Summary

「さあ、始めましょう」（CATEGORIES.gettingStarted）に、優先度 A の単機能チュートリアル 2 本を追加しました。あわせて、このカテゴリの単機能チュートリアルの規約を確定しています（後続 leaf はこれに従う）。

deck id	名前	ステップ	学ぶこと
getting-started-costume	コスチュームをかえてみよう	4	コスチュームタブ / next_costume（見た目の切り替え）
getting-started-sprites	スプライトを2つ使ってみよう	4	スプライトの追加・選択・スプライトごとのプログラム

どちらも 1 本完結・順番に依存しない（deckIds で他 deck に繋がない）ので、ワークシートから「好きなものを 3 つやってみよう」と指示できます。

確定した規約（getting-started.jsx 冒頭コメントに記載）

• deck id: getting-started-<機能スラッグ> — Lv 番号も通し番号も付けない（順序を示唆しないため）
• locale キー: gui.howtos.getting-started-<スラッグ>.{name,stepN.title}
• step 画像: getting-started-<スラッグ>-<N>-<説明>.<ext>、複数 deck 共有は getting-started-shared-<説明>.<ext>
• 画像キー: gettingStarted<スラッグPascal>StepN（ja-steps.js / en-steps.js）
• urlId: gettingStarted<スラッグPascal>

Changes Made

• decks/categories/getting-started.jsx — 2 deck 追加（setup でコスチューム/コードタブを開き、allowedBlocks でパレットを絞る。コード挿入は codeType: 'blocks' でブロックとして入る）
• decks/categories/getting-started.locale.js — ja / jaHira / en の文言を追加（ja と ja-Hira は対）
• decks/ja-steps.js / en-steps.js — 画像キーを登録
• 画像: 既存素材の流用が原則（chat3-mesh1-4-costume.gif / chat2-sprites1-5-add-penguin.gif / chat2-sprites1-6-settings.gif / chat2-sprites1-1-intro.gif）。静止画 2 枚と thumbnail 2 枚は既存 GIF のフレームから生成した派生画像で、新規撮影はしていません
• docs/tutorial/improvement-plan.md — 「方針分岐: gettingStarted は単機能・Lv 分けなし」を追記（ドキュメント内の「各軸は Lv 別」方針との食い違いを明文化して解消）

Test Coverage

• 追加: test/unit/lib/libraries/decks/getting-started-decks.test.js（12 tests）
  • category / urlId / 3〜6 ステップ、deckIds を持たない（順序非依存）
  • message id が ja / ja-Hira / en すべてで解決する
  • thumbnail と各 step の画像キーが jaImages / enImages 双方に存在する（欠けリンク検出）
  • 各 code が実際にブロックへ変換できる（codeType: 'blocks' であることも検証）
• 更新: tutorial-categories-refactor.test.js の deck 順序ガードに 2 deck を追加
• packages/scratch-gui: 上記 + ruby-basics-decks / cards / deck-setup — 81 tests all pass
• npm run lint（root / scratch-gui）: 0 エラー・0 警告、prettier も pass

補足（フォローアップ候補）

step 画像は既存素材の流用・派生のため、コスチューム deck の実行ステップはイントロ GIF の再利用です（.claude/rules/scratch-gui/tutorial.md「画像の流用ルール」に沿った運用）。専用 GIF の撮り直しは後続の磨き込みで対応できます。

Related Issues

Closes #1179
Part of #1177

[smalruby3-editor-bot]

🤖 autopilot status

field	value
Status	Review
AI Status	—
HITL	Yes
Size	middle

Linked issue #1179. Maintained by autopilot (single writer); do not edit.

[github-actions]

🚀 Preview deployed: https://smalruby.jp/smalruby3-editor/topic/autopilot-1179/

[smalruby3-editor-bot]

[Must] docs/tutorial/screenshots/0201-tips-library-1280x800.png が古いままでした（対応済み）。

この PR で「さあ、始めましょう」カテゴリの見た目が 1 枚 → 3 枚に変わるので、.claude/rules/documentation.md の
スクリーンショット DoD（「既存画面のレイアウト・色・テキストを変えた → 既存スクリーンショットを撮り直し
（ファイル名は変更しない）」）に該当します。既存ファイルは deck 1 枚の頃のもので、mesh 再カテゴリ化以前の
並びのままでもありました。

対応: 同じファイル名・同じ viewport（1280x800・ja ロケール・チュートリアル一覧を開いた状態）で撮り直して
差し替えました（4b1f371）。撮影は headless chromium（tools/autopilot/bin/pw-check と同じ bundled chromium）で、
一時ファイルは tmp/ 配下に出しています。

[smalruby3-editor-bot]

[Question] getting-started-costume の setup: {tab: 'costumes'} は、step1 の「チュートリアルをはじめる」で打ち消されます（コメントの意図が成立していない）。

実機（headless chromium・ローカル dev server）で確認した挙動:

操作	選択中のタブ
一覧から「コスチュームをかえてみよう」を選択	コスチューム ✅（applyDeckSetup が効いている）
step1 の「チュートリアルをはじめる」を押す	コード ⬅️ requestNewProject でプロジェクトが作り直され、タブが戻る

つまり「コスチュームタブを開いた状態から始める（この deck の主題がそこにある）」というコメントの状態は、
学習者が step1 のボタンを押した瞬間に失われます。step2 で「「コスチューム」タブで〜」と改めて誘導しているので
動作としては破綻していませんが、この PR は後続 leaf が従う規約を確定する位置づけなので、
setup の効き方を誤解したままコピーされると困ります。

対応: setup はそのまま（deck を開き直したときには有効なので）にして、実挙動をコメントに明記しました（4b1f371）。
setup.tab を start-tutorial 後にも効かせたい場合は deck-setup.js 側の話になるので、必要なら別 Issue が良いと思います。

[smalruby3-editor-bot]

[Question] 共有画像 getting-started-shared-code-tab.png が、貼られている 2 つの step のどちらの説明とも噛み合っていません。

この PNG は「コードタブ・動きカテゴリのパレット・ワークスペースは空・マウスカーソルはコスチュームタブの上」という絵です。

• getting-started-costume step3 「「コード」タブにもどって、「見た目」のブロックを入れてみよう」
  → 写っているのは動きのパレット。しかもこの deck は allowedBlocks で motion: [] にしているので、
  学習者の画面には動きカテゴリ自体が存在しません（実機で確認: パレットは 見た目 / イベント / 制御 のみ）。
  「画面と違うものが手本として出る」ことになります。
• getting-started-sprites step3 「ネコ（スプライト1）をえらんで、このプログラムを入れよう」
  → スプライトの選択も、入れるプログラムも写っていません。

「コード挿入」ボタンがある step なので手順自体は進められますが、初学者向けの手本としては弱いです。
既存素材の流用方針（.claude/rules/scratch-gui/tutorial.md）は理解していますが、流用元が説明と一致していないのは
流用ルールの想定外だと思います。差し替え候補が既存素材に無ければ、この 2 step 分だけ撮り直すのが素直です
（撮り直しは PR 本文でも「フォローアップ候補」とされているので、人間の判断に委ねます）。

[smalruby3-editor-bot]

[Question] getting-started-sprites step2 の画像が、説明と別の操作を見せています。

gettingStartedSpritesStep2: chat2Sprites1Step6 = chat2-sprites1-6-settings.gif で、これは元の
chat-2-sprites-1 では 「ペンギンの位置と向きを調整します」 の step 画像です。

一方この deck の step2 は「スプライトをえらぶと、そのスプライトのプログラムになるよ」で、伝えたいのは
スプライトペインで選択を切り替えるとコードエリアが入れ替わることです。位置・向きの調整 GIF では、
この deck で一番教えたい概念（この deck の主題そのもの）が映りません。

既存素材にちょうど良いものが無さそうなので、ここは撮り下ろし 1 本の価値が高いと思います（要判断）。

[smalruby3-editor-bot]

[Question] getting-started-sprites に「ペンギンを追加する」ステップが無く、step4 で手詰まりになり得ます。

4 step の内訳は intro / 選択の説明 / ネコにコード / ペンギンにコード ですが、
「スプライトを追加する」ことを指示している step がありません（step1 のタイトル
「スプライトをふやして、2つのキャラクターを動かそう！」はゴール提示、追加操作は GIF に写っているだけ）。

step1 の「チュートリアルをはじめる」で新規プロジェクトになるため、学習者の手元はネコ 1 匹だけの状態から始まります。
GIF を見落とした子が step4 に着くと「ペンギンをえらんで」と言われても選ぶ相手が居ません。
また step4 で誤ってネコを選んだまま挿入すると、step3 で入れたネコのコードが上書きされます
（updateRubyCode は選択中のターゲットに入る）。

3〜6 step の枠内なので、ペンギンのスプライトを追加しよう（画像は既に import 済みの
chat2Sprites1Step5 = chat2-sprites1-5-add-penguin.gif）を 1 step 足すのが素直だと思います。
step 構成は content の設計判断なので、こちらでは変更せず判断を委ねます。

[smalruby3-editor-bot]

[Question] getting-started-costume.jpg のサムネイルが一覧サイズ（200x100 相当）で判読できません。

チュートリアル一覧を実際に開いて確認したところ、エディタ全景の縮小なので UI が潰れて何の
チュートリアルか読み取れません（getting-started-sprites.jpg はスプライト選択画面の寄りなので、まだ判別できます）。
既存サムネイルは「さあ、始めましょう」「Rubyのきほん」「メッセージを送ってみよう」いずれもイラスト調 or 大きな文字で、
並べたときに 1 枚だけ質感が浮きます。

寸法（590x369）は既存と揃っていて、リンク切れなどの実害はありません。イラスト作成は設計判断＋素材作業なので
こちらでは触っていません。最低限、コスチュームリスト周辺に寄せてトリミングするだけでも一覧での可読性は上がります。

[smalruby3-editor-bot]

[FYI] allowedBlocks.looks の 'looks_costume' は no-op です。

looks_costume はツールボックス XML では looks_switchcostumeto の中の <shadow type="looks_costume">
（make-toolbox-xml.js）としてしか現れず、shouldIncludeBlock が判定するのは <block type=...> だけです。
block-utils.js の CATEGORY_BLOCKS.looks にも含まれていません。

実機でパレットを確認したところ「コスチュームを [コスチューム1▼] にする」はドロップダウンごと正しく出ており、
この 1 行があってもなくても結果は同じです。他の deck（ruby-basics.jsx）は実ブロック id だけを列挙しているので、
揃えるなら削っても良い、という程度の話です。

[smalruby3-editor-bot]

[FYI] tags: ['ブロック', 'はじめて'] の 'ブロック' はフィルタボタンには出ません。

tutorial-tags.js の default export（フィルタボタンの定義）は ruby / mesh の 2 つだけなので、
'ブロック' は検索文字列としてのみ効きます（library.jsx の getFilteredData は「すべて」選択時に
tags と name を対象に部分一致検索する）。'はじめて' は既存の intro-getting-started にも付いているので前例通りです。

意図どおり（検索でヒットさせたいだけ）なら問題ありません。フィルタボタンを増やす意図があるなら
tutorial-tags.js 側の対応が要ります。

[smalruby3-editor-bot]

🤖 敵対的レビュー完了。指摘 8 件（Must 1 / Question 5 / FYI 2）。Must は修正済み。

確認したこと（合格した観点）

• lint / prettier: npm run test:lint・prettier --check ともに 0 エラー 0 警告
• unit test: test/unit/lib/libraries/decks/ 4 suites / 58 tests pass
• 挿入コードが意図どおりのブロックになるか（テストは「エラーが出ない」までしか見ていないので opcode を実際に dump）
  • costume step3 → event_whenflagclicked / control_repeat / looks_nextcostume / control_wait ✅
  • sprites step3・step4 → event_whenflagclicked / looks_sayforsecs（+ control_wait）✅
  • 実機（headless chromium + ローカル dev server）でも「コード挿入」→ 同じ 4 ブロックが生成されることを確認
• allowedBlocks が挿入コードを賄えているか: 生成される全 opcode がパレット許可リストに含まれる（挿入後に学習者が
  自分で組み直せる）。実機のパレットも 見た目 / イベント / 制御 のみに絞られていた ✅
• 一覧表示: 「始めましょう」に intro + 新規 2 本が期待順で並び、サムネイル・step 画像とも読み込み成功
  （naturalWidth > 0）✅
• i18n: ja / ja-Hira / en が対で揃い、{greenFlag} プレースホルダも一致 ✅
• urlId の重複なし、intro-getting-started は先頭のまま（menu-bar-hoc.jsx の直接参照も無傷）✅

指摘の内訳

分類	内容	対応
Must	docs/tutorial/screenshots/0201-tips-library-1280x800.png が古い（DoD）	修正済み（撮り直して差し替え）
Question	setup: {tab:'costumes'} が start-tutorial で打ち消される	コメントを実挙動に修正（setup は据え置き）
Question	共有画像 getting-started-shared-code-tab.png が 2 step のどちらとも噛み合わない	撮り直し要否は人間判断
Question	sprites step2 の GIF が「位置と向きの調整」で主題と別	同上
Question	sprites に「ペンギンを追加する」step が無く step4 で手詰まりになり得る	step 構成の設計判断のため委ねる
Question	costume サムネイルが一覧サイズで判読不能・既存の質感と不揃い	素材作業のため委ねる
FYI	allowedBlocks の looks_costume は no-op	対応なし
FYI	tag 'ブロック' はフィルタボタンには出ない（検索のみ）	対応なし

Question 5 件はいずれも動作は破綻していない（コンテンツの質・撮り直しコストの判断）ため、コメントのみ残しています。

[takaokouji]

敵対的レビューのQuestionに対応して。

また、コスチュームをかえるチュートリアルの2ページ目の画像は静止画で、最後のページの画像はアニメーションしてコスチュームを変更していたので、最後のページのアニメーションが2ページ目にあるべき。
また、3ページめは実際のプログラム（コスチュームを繰り返しかえるもの）を画面に表示すると良い。

それと、CI failed: Summary of all failing tests
FAIL test/unit/containers/use-teacher-notifications.test.js
● useTeacherNotifications (EPIC #1111 / 日次取得) › email 不明（空キー）ならキャッシュを使わず毎回取得する（共有PC取り違え防止）

expect(received).toBe(expected) // Object.is equality

Expected: 1
Received: 0

  109 |         const { result } = renderHook(() => useTeacherNotifications({ idToken: TOKEN, handleTeacher401 }));
  110 |         await waitFor(() => expect(mockListNotifications).toHaveBeenCalledTimes(1));
> 111 |         expect(result.current.unreadCount).toBe(1);
      |                                            ^
  112 |         // 空キーではキャッシュを書かない（他の空キー先生と共有されないように）。
  113 |         const cache = JSON.parse(window.localStorage.getItem(STORAGE_KEY));
  114 |         expect(cache.notifications[0].notificationId).toBe('x');

  at Object.toBe (test/unit/containers/use-teacher-notifications.test.js:111:44)

Test Suites: 1 failed, 392 passed, 393 total
Tests: 1 failed, 1 skipped, 4356 passed, 4358 total
Snapshots: 13 passed, 13 total
Time: 134.412 s

[smalruby3-editor-bot]

🤖 レビュー対応。指摘 8 件（Must 1 / Question 5 / FYI 2）+ 人間レビュー 3 件 → 対応 7 件 / 返信のみ 2 件 / 対応不要 2 件（7e0f708）。

人間レビューへの対応

指摘	対応
コスチューム deck の 2 ページ目が静止画で、最後のページがコスチューム変更のアニメーション → アニメーションを 2 ページ目に	step2 を chat3-mesh1-4-costume.gif（コスチュームタブでコスチュームを追加する操作）に差し替え。静止画（コスチューム一覧）は step1 のイントロへ移動
3 ページ目は実際のプログラム（コスチュームを繰り返しかえるもの）を表示	挿入されるブロックそのものを「命令ブロックを画像として保存」で書き出して step3 の画像にした（旗→3回繰り返す→次のコスチュームにする→1秒待つ）
CI failed: use-teacher-notifications.test.js	この PR とは無関係の flaky（お知らせセンター #1111 の hook テスト）。waitFor が「API 呼び出し回数」で待っており、state 反映前に unreadCount を assert していた。同ファイルの他テストと同じく state を待つ形に修正（ローカルでは修正前も通るが CI の遅い環境で落ちる）

これに伴いコスチューム deck は 4 step → 3 step（イントロ / コスチュームをふやす / プログラムを入れて実行）になりました。実行ステップは step3 に統合しています（同じ GIF を step1・step4 で使い回すのをやめたため）。

敵対的レビュー Question 5 件

Question	対応
setup: {tab:'costumes'} が start-tutorial で打ち消される	削除。押した瞬間にコードタブへ戻るので、一瞬タブが切り替わるだけの無意味な指定でした。コスチュームタブへは step2 の文言で誘導。規約を確定する PR なので、後続 leaf に誤ってコピーされないよう理由をコメントに残しています
共有画像 getting-started-shared-code-tab.png が 2 step のどちらとも噛み合わない	画像を削除し、両 deck とも「挿入されるプログラムのブロック画像」に差し替え
sprites step2 の GIF が「位置と向きの調整」で主題と別	流用をやめた。step2 は「ペンギンをふやす」= chat2-sprites1-5-add-penguin.gif になり、説明と絵が一致します
sprites に「ペンギンを追加する」step が無く step4 で手詰まり	step を追加。構成は intro / ペンギンをふやす / ネコをえらんでプログラム / ペンギンをえらんでプログラム+実行 の 4 step。「スプライトをえらぶと切りかわる」は step3・step4 の文言に織り込みました（ネコ…をえらんでから／ペンギンをえらぶとプログラムが切りかわるよ）
コスチュームのサムネイルが一覧サイズで判読できない	トリミングし直し。コスチュームリスト（1: ネコ / 2: Penguin-b）に寄せたので、200x100 でも「コスチュームが2つある画面」と分かります

FYI 2 件（looks_costume は no-op / タグ 'ブロック' は検索のみ）は方針どおり対応なしです。

確認

• npm run lint（root / scratch-gui）: 0 エラー・0 警告、prettier も pass
• test/unit/lib/libraries/decks/ + use-teacher-notifications: 70 tests pass
• deck テストに「同じ画像キーを 2 つの step で使い回さない」ガードを追加（今回の指摘の再発防止）
• 画像は headless chromium（bundled）でローカル dev server から書き出し。ブロック画像は実際に生成されるブロックそのもの

残っているもの（判断をお願いします）

docs/tutorial/screenshots/0201-tips-library-1280x800.png はコスチュームのサムネイル差し替え前の状態です（一覧の並び・deck 数は変わっていません）。撮り直しにはこのブランチの dev server 起動が要るので、今回は入れていません。必要なら次で撮り直します。