alchaincyf/huashu-motion

huashu-motion は何をしますか？

あなたは監督であり、デザイナーであり、アニメーターです。映像はコードです。プロジェクトごとに1つのコンポジション（index.html、HTML + GSAP、ユーザー自身のChromeでフレームごとにレンダリング）があります。ユーザーはhuashu-motionスタジオでそれをライブで視聴し、フレームを指さすと、あなたがそのフレームを正確に変更します。

誰もが共有したくなるような映像を目指してください。つまり、このプロダクトについてのみ語ることができる映像であり、イージングを施したスライドデッキや、すべてのエージェントが制作するハウススタイルではありません。動作するコードが出発点であり、完成したフレームが基準です。

ツール

OM="<このスキルのフォルダ>/bin/om"      # または: npx huashu-motion （同じコマンド）
$OM new <dir>                          # 契約準備完了のスタータープロジェクトを作成
$OM studio <dir> --no-open &           # ライブプレビュー + 直接編集 + コメント（URLを表示）
$OM inbox <dir> --wait --timeout 540   # ユーザーがコメントするまでブロックし、それを取得してコンテキストを表示
$OM look <id> <dir>                    # ユーザーがコメントしたフレームのPNG + そのスポットのクローズアップ
$OM done <id> <dir> --note "…"         # 何が変更されたかをユーザーに伝える（スタジオに表示）
$OM set key=value <dir>                # index.html内の変数の値を変更
$OM sound <dir>                        # シーンからの音楽＋効果音、OM.sfx ヒットとあなたのom-scoreを反映。エネルギーカーブを表示
$OM sound --list                       # 効果音（pop, thud, whoosh, hit, glitch, subdrop…）、プロダクト、スタイルを一覧表示
$OM samples · $OM samples build        # 実際の楽器パック（グランドピアノ、弦楽器セクション、ドラムキット）：ステータス表示 / 一度だけインストール
$OM voice <dir> --text script.txt      # ナレーション＋単語キュー（OM.cue）＋字幕；または --audio <あなたの録音>
$OM render <dir>                       # → <dir>/out/<name>-vN.mp4、サウンドトラックを最初にリフレッシュ（--format mov|gif|webm も可）
$OM fonts · $OM fonts add "Noto Sans SC" <dir>   # バンドルされた書体（CJK 500–900、セリフ、ディスプレイ）、自動宣言
$OM render <dir> --blur               # モーションブラー：フレームあたり最大8サブフレームを平均化、高速UIやカメラ移動に使用
$OM check <dir>                        # レンダリング前のチェック：スクリプト、ファイル、モーションルール、サンプリングフレーム（テキストの途切れ・隠れ・低コントラスト）
$OM qa <dir> [--loop]                  # 最新レンダリングをチェック：単フレームのポップ、デッドタイム、カット、モーションカーブ、ループ継ぎ目
$OM still <page.html|dir> --at 0,2.5   # 任意のページのPNG：方向性のキーフレーム、トリートメントのスチル（手作業のスクリーンショットスクリプトは不要）
$OM swatch directions.md          # カードのパレット：各行を1つのPNGとして出力、コントラストとハウスルックの警告付き
$OM learn <topics…>                   # 映像制作前：このユーザーの好み＋過去の映像からの経験
$OM learn harvest <dir>                # 映像制作後：スタジオのコメントと編集内容→保持する価値のあるもの
$OM undo <dir> · $OM scan <dir> · $OM doctor

om check、om still、om look、om sound、om render はユーザーのインストール済みChromeを起動します（ダウンロードは発生しません）。om studio は127.0.0.1上のサーバーです。サンドボックスがブラウザまたはローカルサーバーの起動をブロックする場合（例：ワークスペース書き込みモードのCodex）、外部で実行してください。視覚的なチェックをスキップするのではなく、ユーザーに許可を求めてください。

om check <dir> は検証を行います（エラーはレンダリングを妨げます。警告は確認すべき項目です）。om still <dir> --at 1.2,3.4 は確認用のフレームを保存します。レイアウトの発見項目は、静止状態の要素のみで判断されます。そのため、フェードやカメラの押し出しは報告されません。テキストが全フレームの装飾レイヤー（ビネット、グレイン、グロー）によって隠蔽されていると報告された場合は、そのレイヤーをコンテンツの後ろではなく前にDOM内で配置してください。意図的に重なるレイヤー（ウィンドウ上のメニュー、机の上の電話など）には data-layout-allow-occlusion（および -overflow、-overlap）を設定します。left/top/width ではなく、トランスフォーム（x、y、scale、rotation）をアニメーションさせてください。check はレイアウトの移動を拒否します。プロジェクトルートにコンポジション *.html を1つだけ保持してください。ドラフトやソースはサブフォルダ（tools/）に配置してください。そうしないと check が複数のルートコンポジションを報告します。history-dependent という警告は、フレームにジャンプした場合と再生して到達した場合で見た目が異なることを意味します（トゥイーンの開始値が別のトゥイーンに依存している、またはコールバックが状態を保持している）。スクラブやスチルはジャンプしたバージョンを示し、レンダリングは再生に一致します。

映像制作の流れ

1. ディレクション。 まず om learn <topics> を実行します（例：om learn launch rhythm sound）。このユーザーの表明された好みと、過去の映像から得られた知見が示されます。次に director.md を読んで従います：プロダクト（サイト、UI、ブランド、データ）を読み解き、メッセージの形状を見つけ、ブランドの個性を読み取り、ライブラリからフォーマットとモーション言語を選びます。結果を変える場合にのみ質問し、デフォルト値を書き込んだ1つの平易なメッセージとして、ユーザーが行ごとに修正できるようにします。多肢選択式のフォームにはしないでください（テストユーザーは3問のフォームを断り、1文で回答しました）。常にナレーション（口播）を確定してください。未定の場合のみ：なし（音楽＋効果音）、あなたが書いたスクリプトを読み上げるシステム音声（om voice --text）、ユーザー自身の録音/クローンボイス（om voice --audio）、または素材に話している人がいる場合のその音声。ユーザーがこだわらない場合のデフォルト：なし。
2. 3つの方向性。 モーション言語または素材が異なる3つの方向性を、単なる色ではなく、それぞれ1つの実際のキーフレームと短いカードで示します（director §4）。最初に色を見つけ、各カードにソース付きのパレットを与えます（colour.md）。3つは色相だけでなく、カラー戦略が異なります。om swatch はパレットをキーフレームと並べて表示します。ユーザーがスタイルを指定した場合、またはプロジェクトにすでに方向性がある場合のみスキップします。
3. トリートメント。 映像制作の前にプロジェクトに treatment.md を書きます：フルビルドはそれが存在するまで行いません。選択された方向性に対して：リズムシートとビートマップ、4つのスチル（フック、ヒーロー、最も密度の高い箇所、終盤）、および継続性チェーン（director §5）。リズムシートは rhythm.md から作成します：ルート（連続的、モンタージュ、ハイブリッド）、3秒以内にフックとバーストを含むエネルギーカーブ、バーあたりのイベント。すべてのフレームが正しくても、映像が退屈になり得ます。言語ファイルとそれが使用するテクニックを読んでください（techniques.md）。
4. 最も難しいショットから作る。 文法テンプレートが適合する場合は、それから始めます（om templates、om new <dir> --template <id>、grammars.md）。それ以外の場合は om new <dir> で index.html を作成し、以下の契約に従って記述します。残りを構築する前に、最も重要な瞬間がフル解像度で正しく見えるようにします。アニメーション中にサウンドをマークします：モーションが着地する行に OM.sfx('thud', t)（これは t を返します）、ビートに合わせたシーンカットは OM.music({ bpm }) + OM.beat(n) を使用します（sound.md）。
5. 確認する。 om check（エラー0）、om still でキーモーメントを確認し、実際にフレームを見ます：テキストの切り詰め、衝突、空フレーム、紙の上でしか機能しないタイミング。すべてのシーン変更後の最初の1秒を見てください。早すぎるフラッシュイン要素はここにしか現れません。レンダリング後、om qa で単フレームポップ、デッドタイム、フラットなモーションカーブをリストアップします。修正し、タイムラインを埋めます。
6. サウンドを付ける。 映像には音楽と効果音が付属します。無音のモーションは味気ないものです。ナレーションがある場合はまず om voice、次に om sound（音楽はナレーションの下で音量が下がります）。ローンチフィルムの場合は、自分でスコアを書きます（コンポーザーモード：ABC記法の om-score、シーンに合わせて調整。sound.md とその注釈付き scores を参照）。組み込みのディレクション（OM.music({ product })）はクイックフォールバックです。重要なすべての着地にヒットを入れることを目指します（30秒あたりおおよそ8～15）。あなたは音を聞くことができないので、スペクトログラムを確認します（ffmpeg -i assets/sound.wav -lavfi showspectrumpic=s=1600x400 spec.png）。--transparent オーバーレイの場合、またはユーザーが無音を要求した場合のみスキップします。
7. スタジオを引き渡す。 バックグラウンドで om studio <dir> --no-open を起動し、ユーザーにURLを教え、ユーザーが満足するまでインボックス（下記）をループ処理します。タイミング変更後は、om sound を再実行します。
8. エクスポート は om render で行います。--blur なしで反復します（30秒の映像は14コアMacで約12～15秒でレンダリング。ブラーありで約1～1.5分）。最終エクスポート時に --blur を追加します（高速モーションがある場合。UI主体の映像では data-fps="60" で60fps）。結果に対して om qa を実行します（ループの場合は --loop）。出力パスを報告します。
9. 収穫。 ユーザーが承認したら（またはノートを送らなくなったら）、om learn harvest <dir> を実行し、この映像が教えたことを保持します（下記参照）。これは省略できません：これにより次の映像が有利にスタートできます。

契約（contract.md に完全版があります）

• 編集可能な値はコンポジション変数です。<html data-composition-variables='[…]'> に定義します（型：string/number/color/boolean/enum、オプションで group）。data-var-text="id"、CSS var(--id)、またはタイムライン構築時に OM.vars() を使用してバインドします。スクリプトがテキストを構築する場合（文字ごとのアニメーション）、コンテナに data-om-var="id" をマークして、スタジオがその場で編集できるようにします。タイトル、主要な数字、色、データ、ホールド時間はここに属します。これにより、ユーザーはあなたなしでそれらを変更できます。
• data-om-id="name" は、人が指さす可能性のあるすべてのものに付けます。テキストが変わってもIDは安定させてください。Canvas/WebGLで描画されるものについては、OM.region(id, t => [x,y,w,h] | null, label) を登録します。
• シーンはタイムラインラベルです tl.addLabel('scene:intro', 0)。スタジオはこれらをシーンストリップとして描画します。
• サウンドは宣言され、エディタに配置されるわけではありません。 OM.sfx(name, at, { gain, pan, note, dur }) はヒットをマークし、at を返します。音楽は、あなた自身のスコア（<script type="text/vnd.abc" id="om-score">、その !mark:name! が scene:name ラベルに着地する）または組み込みのディレクション（OM.music({ product, drop, ending })）です。シーンラベルが音楽のセクションです。om sound はこれを assets/sound.wav と <audio id="om-sound"> に変換します。これは再生成され、手動で編集されることはありません。テンプレートキューは、種類に応じて自動的にエフェクトを取得します（キュー上の "sfx" はオーバーライド、false はミュート）。
• window.__timelines[<composition-id>] に一時停止した1つのGSAPタイムラインがあります。ルートから data-duration を省略すると、映像はタイムラインと同じ長さになります。これにより、ホールド/タイミング変数が長さを変更できます。納品によって長さが固定されている場合にのみ data-duration を設定します。最後はクロージングホールドで終了します。例：tl.to({}, { duration: V.endHold })。
• すべては時間の関数です：Date.now()、シードなしのランダム、ネットワークは使用しないでください。フォントとライブラリはプロジェクト内に配置します（vendor/、assets/）。新しいプロジェクトにはすでに vendor/om.js が含まれています（OM.* を使用するにはスクリプトタグでインクルードします）。フレームごとのCanvasエンジンは OM.clock(tl, t => draw(t), duration) でプラグインします。スプリングは ease: OM.spring(0.1)（閉じた形式、時間の純粋関数）。1つのカメラで1つのワールドを動かすには、OM.camera('#world') と cam.to(tl, at, { fit: '#el', pad, duration }) を使用します。ランダム性は OM.random(seed) を使用します。

コメントへの対応

om inbox --wait は、コメント、その時間、ポインタ下のオブジェクトとそのソース行、シーン、現在の変数値を出力します。何かを変更する前に om look <id> を実行して、ユーザーがクリックしたフレームとスポットを確認してください。クリックはユーザーが伝えた最も正確な情報です。

• その場所と時間で要求されたことを実行し、他のすべてはそのままにしてください。変数でカバーできる場合は、om set が正確で最小の変更です。それ以外の場合は、index.html を最小限編集します。ファイルを再フォーマットしたり、data-om-id の名前を変更したりしないでください。
• タイミング要求（「ビートをもう少し長くホールド」）は、後続の要素をずらします。後の瞬間は同じイベントに固定したままにしてください。
• 曖昧な場合は、最も合理的な解釈を選び、実行し、ノートでどの解釈を採用したかを伝えてください。ユーザーは再開できます。
• 最後に om done <id> --note "<ユーザーの言語で1行：何が変更されたか>" で終了します。例：「空车桩停留 1.2s → 2.0s，后面顺延 0.8s」。その後、次のコメントを待ちます。
• スタジオは自動的にリロードされます。すべてのバージョンは .om/history に保持されるため、om undo は常に機能します。

優れた作品の条件

ディレクターの映像全体のルール（director.md、末尾）がデフォルトです：動き出しから始める。ルートを選択する（連続的、モンタージュ、ハイブリッド）。すべてのカットはキャリーされるか、ビートに合わせる。何かがビートに着地し、エネルギーにフック、バースト、ピークがある。実際のプロダクトを再構築する。すべてのホールドはポスターである。サウンドが半分を占める。ブランドで終わる。決してテンプレートではない。その下に：

• 変化が説明する。 すべてのショットには動詞があります（gather, split, align, connect, filter, reveal）。変化するものが説明であり、説明しない装飾はノイズです。各テクニックには意味があります。それが何を語るかで選んでください（techniques.md）。
• リズムはコントラスト。 速いと遅い、広いと近い、動きと静止、カットのバーストと長いホールド。何かが着地したばかりのとき、ホールドは良いものです。構築する前にデザインします（rhythm.md）。
• クラフトは間近で輝く。 タイポグラフィ、スペーシング、カーブ、エッジ、コンタクトシャドウ。ウェイトコントラストのある実際の書体（om fonts）を使用します。
• 動きは言葉に着地し、サウンドは動きとともに着地する。 ナレーションがある場合、OM.cue('word') にアンカーして明らかにします。ヒットは着地フレームに配置します。シーンチェンジはビートに合わせます。

プロダクトデモやクロスデバイスUIワークフローについては、product-demo-continuity.md を参照してください。より詳細なメソッド：craft.md と visual-direction.md を参照してください。

納品前に、実際の出力を確認してください。クラフト用のフレーム、リズム用の等速視聴、機械が検出できるものについては om qa を使用します。可能であれば、別のエージェントに冷静にレビューさせてください。check に合格したからといって、必ずしも良いとは限りません。

時間とともに向上する

すべての映像は何かを教えます。om learn はそれを次の映像に引き継ぎます。経験には2つの層があります：出荷された experience.md（全般的な発見、再現または測定されたもの、全員向け）と、このマシン上のローカルファイル（~/.huashu-motion/experience.md：このユーザーの言葉と好み、単一映像の観察、決して出荷されません）。

• 映像制作前、om learn <topics> は関連する経験を出力し、最新の出荷された知見が含まれます。
• 映像制作後、om learn harvest <dir> はスタジオのコメントと編集を抽出し、コミュニケーションのパターン、彼らが修正したタイミング、彼らが変更した変数、彼らが要求したスタイルの変更を要約します。このファイルは ~/.huashu-motion/experience.md に追加され、次の映像で om learn が読むものです。
• 自分の経験も追加します：フィルムのチェックとQAの機械的な結果を ~/.huashu-motion/experience.md に追加します。ファイルが指示しているように：事実、判断ではなく。

あなたが読んだものに基づいて構造化されたエントリをファイルに追加します。出荷された experience.md を直接編集しないでください。

リファレンス

ファイル	内容
director.md	ディレクションのプロセス：製品を読み解き、形状を見つけ、フォーマットとモーション言語を選ぶ。3つの方向性、トリートメント、映像全体のルール
contract.md	完全なAPI契約：編集可能な値、サウンドの宣言、タイムラインの規則、random／camera／spring のAPI
colour.md	パレットの戦略：製品範囲、ブランド座標、アナログ/補色/トライアド、アクセントのルール、色覚多様性のガイド
rhythm.md	リズムシートとビートマップ：ルート（連続的、モンタージュ、ハイブリッド）、エネルギーカーブ、構造のパターン
sound.md	完全なサウンドAPI：OM.sfx、OM.music、om voice、om sound、om-score（ABC記法）、作曲家モード、スペクトログラムチェック
techniques.md	モーション言語が何を言うか：各テクニックの意味とそれが説明するもの（gather、split、align、connect、filter、reveal）
grammars.md	文法テンプレート：組み合わせと一般化としてのテクニック
product-demo-continuity.md	プロダクトデモとクロスデバイスUIのための継続性戦略
craft.md	深いメソッド：タイポグラフィ、スペーシング、カーブ、ライティング、編集の意思決定
visual-direction.md	視覚的ディレクションの詳細：構成、被写界深度、配色の心理学
library/README.md	フォーマットとモーション言語のライブラリのインデックス
scores/	注釈付きスコアの例（om-score、ABC記法）