九九バトル

小学 2 年生が、学校で九九が始まる前に全部言える状態になることを目的とした PWA。

報酬をアプリの中に置かない。教室で「これ知ってる」となる体験を報酬とする。 設計の方針と判断の根拠は docs/design-notes.md を参照。 ストーリーモードの設計と判断の根拠は docs/story-mode-design.md。 ランクと見た目の判断は docs/rank-design.md。 子どもが話を注文する仕組みの判断は docs/story-authoring-design.md。 話の追加手順は docs/story-prompt.md（親が LLM に投げる雛形）。

現在の実装範囲（第 1 版）

項目	状態
モードの切り替え（たたかう / ぼうけん）	実装済み
九九のタイムアタック（10 問）	実装済み
段ごとの解放（順序は設定で変更可能）	実装済み
問題の音声読み上げ	実装済み
親子で同じ問題セット。親の記録が常に表示	実装済み
段ごとの遅さ・誤答の可視化（親のみ）	実装済み
問題文・世界観の差し替え	実装済み（JSON 4 テーマ）
親子で端末が分かれた場合の記録・設定の同期	実装済み・実プロジェクトで動作確認ずみ
ストーリーモード（街・散策・道の選択・戦い）	実装済み（2 エリア同梱・各 720 通り）
タイムに応じたランク（段ごとに目標が違う）	実装済み
習熟度による段の解放	未実装（設計のみ）
子どもが話を注文して作ってもらう仕組み	実装済み（要 Supabase。生成は親の Claude）
プッシュ通知	未実装

起動

npm install
npm run dev        # http://localhost:3000
npm run build      # 本番ビルド
npm run typecheck  # 型チェック
npm test           # 単体テスト
npm run layout-check  # ホームが端末の高さに収まっているかを 6 サイズで確認
npm run stories    # 注文された話を作る道具（手順は docs/story-task.md）
npm run icons      # アイコン PNG の再生成

iPhone への設置

ブラウザのブックマークでは開かれない。ホーム画面に置くこと。

1. デプロイ先の URL を子どもの iPhone の Safari で開く
2. 共有メニューから「ホーム画面に追加」
3. YouTube や Roblox と同じ列に配置する

親画面の QR から開く

親の端末で、デプロイ先の URL から親画面を開き、「べつの端末とつなぐ」の 「子どもの端末で開く QR を出す」を押す。子どもの端末のカメラで読み取ると、アプリが開く。

• 合言葉が入っている場合、QR には合言葉が含まれる。読み取った端末で「つなぐ」を押すと、 その合言葉で「子どもの端末」として設定される
• 合言葉は URL のフラグメント（# 以降）に入れており、サーバへは送られない。 読み取った側では、読み込み直後にアドレスバーから消す
• QR は合言葉と同等に扱うこと。写真に撮らない、他人に見せない
• iPhone では、ホーム画面に追加したアプリと Safari とで保存領域が別になる場合がある。 ホーム画面のアプリで合言葉が入っていなければ、そちらの親画面から入れ直す

アイコンと名称は意図的にゲーム側へ振っている。 「勉強」「ドリル」「学習」という語は画面のどこにも出していない。

構成

src/
  app/
    page.tsx          ホーム。相手の選択と、親の記録の常時表示
    play/             タイムアタック本体
    story/            ストーリーモード
    parent/           親専用画面（段の解放、弱点、着せ替え）
    join/             親画面の QR から開く入口。合言葉を受け取る
    manifest.ts       PWA マニフェスト
  components/
    PlayScreen.tsx    出題・判定・計測
    Result.tsx        結果。答えをタップで聞き返せる
    StoryScreen.tsx   街・散策・道の選択の進行
    StoryBattle.tsx   ストーリー中の戦い
    StageInsights.tsx 子どもの状態（親のみ）
    RankBadge.tsx     ランクの表示
    ParentGate.tsx    親画面の入口
  lib/
    kuku.ts           出題の組み立てと重み付け、入力判定
    rank.ts           段ごとのランクのしきい値と判定
    yomi.ts           九九の唱え方テーブル
    speech.ts         Web Speech API のラッパ
    themes.ts         着せ替えの読み込み
    story.ts          ストーリーの型と検証
    stories.ts        散策の組み立てと読み込み
    storage/          保存層（local / supabase）
  data/themes/*.json   テーマ定義
  data/stories/*.json  ストーリー

設計上、意図的にそうしている点

実装を変更する際は以下を壊さないこと。いずれも設計メモ上の判断に対応する。

• 間違いで減点しない。 ライフ、連続正解、赤い×は持たない。 誤答は出題の重み（lib/kuku.ts の weightOf）にのみ反映する。
• タイマーは考えている時間だけを測る。 誤答時の解説中は計測を止める。 間違いが記録を悪化させると、減点しない方針と矛盾するため。
• 連続日数とプレイ時間を記録も表示もしない。 途切れた日に開かなくなる理由を作らない。
• 苦手を子どもに見せない。 段ごとの遅さと誤答率は親画面にのみ表示する。
• 解放は 1 段ずつ。 未習の段を出すと「わからない」だけが残る。 既定の順序は 1 から 9 の数字順だが、学校の進度に合わせて親が並べ替える。
• 1 回 10 問。 物足りないくらいの長さに保つ。
• ポイント・コイン・ガチャを置かない。 見た目の解放を追加する場合も、 達成と無関係な配布にはしないこと。
• 付かないランクを作らない。 10 問終えれば必ず「クリア」が付く。 「ランクなし」は不合格の別名であり、減点しない方針と衝突する。
• ホームの「はじめる」を画面の外に出さない。 外枠は画面の高さに固定し、 あふれるのは中身だけにしてある（.app[data-fit] と .scrollArea）。

外装について

角を斜めに落とした HUD（アーケード筐体の読み方）で統一している。 判断の根拠は docs/rank-design.md の判断 7。

• ゲーム感はフォントで出さない。 ドット絵フォントは使わない。 形（clip-path による切り欠き）・発光・地の質感・量の刻み方で出す
• 色はすべてテーマ変数から導出する。 外装は全テーマ共通で、色だけが テーマから来る。既定は arcade（シアン）だが、緑・紫・青でも成立する
• 量は刻む。 体力と進度は 1 本の帯ではなく枡に割る。 帯の長さは「どれくらい」しか伝えないが、枡は「あと何個」を伝える

触るときに踏みやすい点が 3 つある。

• clip-path は box-shadow を切り落とす。 角を落とした要素の外側の光は filter: drop-shadow() で出すこと
• 地の層（body::before / body::after）は z-index: 0、中身は 1。 body に不透明な背景を戻すと地の格子が隠れる（描画順の問題）
• 小さい箱に大きな切り欠きを使わない。 .panel の切り欠きは 14px ある。 答えの札のような小さい箱には .factCell のように専用の値を持たせる

ランクについて

タイムでゴールド・シルバー・ブロンズが付く。判断の根拠は docs/rank-design.md。

• 目標は段ごとに違う。 全段を同じ秒数で測ると、1 の段は必ずゴールド、 9 の段は一生ゴールドなしになる。1 問あたりの目標を 固定費・桁数・積の大きさから組み、10 問ぶんを合計している（src/lib/rank.ts）
• ゴールドは全問正解のときだけ届く。 速いだけで取れると、 覚えずに連打した方が速くなる。落とした数だけ上限が下がる
• 10 問終えれば必ずランクが付く。 最低は「クリア」
• 見せるのは 1 つ上までの差だけ。 下位の子にゴールドまでの距離を出すと、 それは苦手の通知になる
• 厳しさは親が 1 段ずらせる。 実際の速さは遊ばせるまで分からない

ブロンズの境目が 1 分を超えないことは単体テストで固定してある。 「1 回 1 分で終わる長さ」をランクの境目が壊さないため。

画面の高さについて

ホームは外枠を画面の高さに固定し（.app[data-fit='true']）、 あふれる可能性があるのは中身（.scrollArea）だけにしてある。 開いて最初に押す「はじめる」が画面の外に出ないことを構造で保証するため。

画面の高さに応じた圧縮を 3 段（790px / 620px / 580px 以下）置いている。 レイアウトを変えたら 1 つの画面サイズで確かめて終わりにしないこと。 320×568 から 430×932 までで、次が崩れていないことを確認する。

• 文書がスクロールしない
• 「はじめる」が全体見えている
• 段カードが全部見えている
• きろくの 2 行とも見えている
• 見切れている要素が無い

目視では分からないので npm run layout-check で測る。

npm run build && npm start -- -p 3210 &
npm run layout-check

崩れていたら終了コード 1 と、どのサイズでどの条件が落ちたかを出す。 Chromium の場所が違う場合は CHROMIUM_PATH で指定する。

子どもが話を注文する仕組み

このアプリで刺さったのは「話を読むこと」ではなく「話を作らせること」だった。 実機で確認したところ、同梱の話は使われていなかった。元々 AI に話を作らせて遊んでいた子なので、 楽しんでいたのは注文する側であって、出来上がったものを読む側ではなかった。

設計メモは最初からそう書いていた。

報酬は「話の続きが読めること」ではなく「自分の考えた世界が動いていること」。

判断の根拠は docs/story-authoring-design.md。

流れ

子どもが注文する  →  Supabase に残る  →  親の Claude が作る  →「ぼうけん」に並ぶ
   （アプリ）        （status: ordered）   （スケジュールタスク）  （status: ready）

LLM を API として呼ばない。 話を書くのは、スケジュールタスクを実行している Claude 自身である。Anthropic の API は従量課金で、claude.ai のサブスクリプションとは 別請求になる。子どもが注文するたびに課金される構造は、家庭用のアプリには重い。

アプリ側は注文を置くだけで、生成には一切関わらない。生成を叩ける URL も存在しない。

設計上そうしている点

• 検査は両側でかける。 書き手の側は publish が検査に通らなければ書き込まない。 読む側（アプリ）も読み込んだ話を毎回検査し、通らないものは遊べる一覧に出さない。 Supabase は手でも触れる以上、壊れた話が子どもの画面に出る経路を残さない
• id・段・作者はモデルに決めさせない。 こちらが知っている事実であって、創作の対象ではない
• 親の確認は事後。 即時性がこの仕組みの核。親画面から一覧を見て消せる
• 未習の段の話は注文できない。 自分で選んだ分、分からなかったときの落差が大きい
• 1 日の本数に上限（3 本）。 クライアントと処理側の両方で効かせる
• プロンプトは docs/story-prompt.md から実行時に読む。 親が手で LLM に投げるときと 同じ文面を使う。二重に持つと必ず片方が古くなる
• 失敗を黙って消さない。 作れなかった注文は failed として残し、 子どもの画面に「うまく できなかったみたい」と出す。 注文が消えたように見えると、次を注文しなくなる

This is the beginning of the README. Read the rest at the original. Read the full README ↗