bento-slides

Bento デッキの作成

Bento デッキは、自己完結型の .bento.html ファイル 1 つです。ドキュメントは、単一のブロック内に記述されたプレーンな JSON です。

<script type="application/bento+json" id="bento-doc"> { "format":"bento/slides", ... } </script>

そのブロックだけを、その場で編集してください。JSON 内のすべての < を \u003c にエスケープし、リテラルの </script> が決して含まれないようにします。ファイルの残りの部分（圧縮されたランタイム）は変更しないでください。チャットのやり取りでは、代わりにユーザーが JSON をコピーし（保存 ▾ → ドキュメント JSON をコピー）、置き換えた内容を貼り付けます（保存 ▾ → JSON から置き換え…）。コンソールからは window.bento.loadDoc(json) で読み込めます。

何もない状態から始める

ユーザーは Bento をインストールする必要はありません。アプリはすべてのデッキに同梱されています。編集する .bento.html がない場合は、最新の署名済みリリースを自分で取得して、その中に作成してください。

# name the file after the deck's topic, e.g. Q4_Review.bento.html
curl -fsSL https://bento.page/releases/slides/Bento_Slides.bento.html -o "<Topic>.bento.html"

（curl が使えない Windows の場合：iwr https://bento.page/releases/slides/Bento_Slides.bento.html -OutFile <Topic>.bento.html。）

ダウンロードしたファイルに id="bento-doc" が含まれていることを確認し、そのブロックにドキュメントを書き込んでください。ダウンロードしたファイルでは、このブロックは空です。ブラウザーでは初回起動時にサンプルデッキが生成されますが、ディスク上には破棄するものもコピーするものもないため、探しに行かないでください。 新しいドキュメントを作成する際のルール：

• 作成を始める前に https://bento.page/agents.md を取得し、そこにある「最小限の有効なドキュメント」のスケルトンを使ってください。size と theme（theme.fontFamily を含む）は必須です。これらがないとアプリは起動しません。
• スケルトンに示されているとおり、各要素のフィールドをすべて指定してください（図形には stroke／strokeWidth、テキストには fontFamily／align／valign が必要です）。フィールドが欠けていると、正しく表示されないか、まったく表示されません。
• docId と collab は完全に省略してください。初回起動時に、アプリが新しい ID と休止状態のコラボレーション認証情報を生成します。

作成したら、ファイルを開いてください（open／xdg-open／start）。完成したデッキがエディターでそのまま開きます。そして、完了を報告する前にすべてのスライドを確認してください。テキストのはみ出し、要素同士の詰まり、3 行に折り返された見出し、レンダラーが表示しなかったグラフの凡例は、JSON では見えませんが、画面上では一目瞭然です。作成し、レンダリングし、確認し、修正してください。誰も目を通していないデッキは未完成です。

ワークフロー

1. ドキュメントを見つけます。 #bento-doc ブロックを探し、その JSON を解析します。 doc.size（標準の 1280×720）、doc.theme、既存の要素の id、そして doc.template／doc.readonly が設定されているかを確認します。

   まず doc.collab を確認します。 ownerPriv、writerPriv、または invite が含まれている場合、これから読み取ろうとしているファイルには、このデッキの ライブセッションキーが含まれています。ファイルまたはその JSON を受け取った人は誰でも、 セッションに参加して編集できます。これは仕様です。ファイル自体が招待状になります。 続行する前にユーザーに伝えてください。 判断できるのはユーザーだけであり、デッキが 共有されていることに気づいていない可能性があります。代替案として、読み取り専用のコピー、 または複製したデッキでの 共有 → 共有を停止 を提案してください。すでにどこかに送られている 場合の対処法は 共有 → キーをローテーション です。あとからキーを削除しても、送信済みのキーは 無効になりません。

2. ユーザーから渡されたソース資料を読み、各項目を分類します。統計データですか？ 表ですか？ プロセスですか？ 展開して説明する定義ですか？ 写真ですか？

3. 資料を機能に割り当てます（箇条書きのテキストを安易に使わないでください）。 ここが、段落を並べただけのスライドショーではなく、Bento デッキにするためのポイントです。

   • 視覚的に比較する数値（傾向、規模、割合）→ グラフ要素
   • 比較／仕様／価格／機能の一覧 → 表要素 （columns の比率 + cells の rows + style オブジェクト）
   • 同じものが変化する様子を連続するスライドで示す → モーフ：共有する要素には両方のスライドで同じ id を付け、後のスライドに transition:"morph" を設定します（Bento を象徴する機能です。積極的に使いましょう）
   • 掘り下げて説明するポイント → 状態スライド（stateOf + 要素の link）
   • ヒーロー画像／全画面画像 → 全面画像 + スクリム矩形 + テキストを使い、 ケン・バーンズ効果で動きを付けます
   • シーケンス／フロー／タイムライン → dash-march ループ付きの線／path を使うか、手順に沿ってハイライトをモーフさせます
   • 見出しに使う数値 → 大きなテキスト + fx:{countUp:true}
   • すべての表紙／区切りスライド → 少なくとも 1 つの環境的な動きを加えます
   • 繰り返し表示するクローム／ロゴ → スライド間で同じ id を維持し、同じ位置でモーフさせます
   • デモクリップ／録画／短い音声 → メディア要素（kind: video|audio）を使います。短いクリップはデータ URI として埋め込み、ファイルサイズを抑えるため、大きなファイルは URL でリンクします

4. スキーマを使って作成します。 スキーマ全体とコピー＆ペースト用のレシピを開いておきます。 https://bento.page/agents.md を取得してください（要素の構造、モーフ／グラフ／状態／ケン・バーンズ効果の例、注意点が記載されています）。アクセントカラーは 1 色、書体は最大 2 種、左右の余白は 96px（右端の x ≤ 1184）を守り、各スライドにスピーカーノートを記載します。

5. 完了前に自己監査します。

   • テキストで表示している数値のうち、グラフにすべきものはありますか？
   • 1 つのテーマを扱う連続したスライドで、id を共有し、transition:"morph" を設定していますか？
   • 少なくとも 1 か所に動きの演出（ケン・バーンズ効果／ループ／カウントアップ）がありますか？ 特に表紙を確認してください
   • 状態スライドを使うと、より効果的に掘り下げられる箇所はありますか？
   • アクセントカラーは 1 色、書体は最大 2 種、余白は 96px ですか？
   • すべてのスライドにスピーカーノートがありますか？

6. 編集した #bento-doc ブロックを書き戻す（< をエスケープします）、または置き換え用の JSON を返します。HTML ファイル全体を再生成してはいけません。

注意すべき重要な点

• チャート： 棒グラフ／折れ線グラフの系列の data はプレーンな数値である必要があります（{value,…} の項目オブジェクトは 0 に変換されます。{name,value} を受け取るのは円グラフのみです）。色は個々の棒ではなく系列ごとに指定します。option は純粋な JSON とし、フォーマッターはテンプレート形式（{b}／{c}／{d}）のみを使用してください。関数は使用できません。
• モーフィングを行うには、連動してアニメーションさせるスライド間で共有される、決定的で安定した ID が必要です。ID が異なるとモーフィングは行われず、要素が切り替わるだけです。
• 画像やフォントは doc.assets にデータ URI として埋め込み、"asset:<key>" で参照する必要があります。こうするとファイルを自己完結型にできます。
• メディア： media 要素（kind: video|audio）では、短いクリップを src にデータ URI として埋め込む（自己完結型）か、大きなファイルを URL で参照できます（デッキのサイズを抑えられます）。autoplay はプレゼンテーションモードでのみ動作し、動画では muted:true が必要です。大きな動画は埋め込まないでください。ファイルが肥大化します。
• 既存のデッキを編集するときは、docId を再生成しないでください。これはドキュメントの識別子です。（新しいデッキでは省略します。アプリが生成します。）
• template:true → 開くたびに新しいデッキが生成されます。readonly:true → ファイルを開くと、エディターを表示せずにそのままスライドショーが始まります。

すべての手法の実例を見るには、https://bento.page にあるテンプレートを開き、#bento-doc ブロックを確認してください。