@squadbase/vantage 0.5.3-dev.71d2349 → 0.6.0-dev.3cc6138

package/docs/ja/pages-and-metadata.md

@@ -43,6 +43,23 @@ export default function MonthlyAnalysis() {
 > `export const page = definePage({...})` の**エクスポート名は `page` 固定**です。別名にすると
 > メタデータが読まれません。
 
+## データファイルページのタイトル
+
+`.csv` / `.xlsx` の[ファイルページ](routing#tsx-以外もページになる)に `definePage` は書けないので、
+タイトルは**ファイル名から導かれます**。
+
+| ファイル | `title` |
+|---|---|
+| `june.xlsx` | `June` |
+| `sales_by_region.csv` | `Sales By Region` |
+| `salesByRegion.csv` | `Sales By Region` |
+| `kpi/index.csv` | `KPI`（`index` はディレクトリ名を借りる。全大文字は略語とみなして保つ） |
+| ルート直下の `index.csv` | なし（`definePage` の無いルート `index.tsx` と同じ） |
+
+`navLabel` は設定されないので、ナビの表示名も同じ値になります。名前を変えたいときは
+**ファイルをリネーム**するか、`_` を前置してルート化を止め、tsx から `FilePageView` で描いて
+そこに `definePage` を書きます。
+
 ## Fast Refresh との関係
 
 `page` のような非コンポーネントのエクスポートがあっても、Vantage はそれを内部で扱うため

package/docs/ja/routing.md

@@ -1,6 +1,6 @@
 # ファイルベースルーティング
 
-> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約。
+> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約と、tsx 以外のページ（csv / xlsx / スライド）。
 
 Vantage のルーティングは **ファイルの配置がそのまま URL** になります。ルーターの設定は書きません。
 
@@ -35,11 +35,75 @@ Vantage のルーティングは **ファイルの配置がそのまま URL**
 | `_layout.tsx` | そのディレクトリ配下のレイアウト（入れ子可） |
 | `_404.tsx` | not-found の UI（**ルートのみ**） |
 | `_error.tsx` | error の UI（**ルートのみ**） |
+| `monthly-report.slide.tsx` | `/monthly-report`（スライドデッキ） |
+| `sales-export.csv` | `/sales-export`（表として描かれる） |
+| `data/june.xlsx` | `/data/june`（同上） |
 
 - `[name]` → 動的パラメータ、`[...name]` → catchall。
 - `index` は自身のディレクトリにマップ（名前は URL から落ちる）。
 - `_` で始まるファイルは予約（`_layout`/`_404`/`_error`）またはプライベート（ルーティングされない）。
 
+## tsx 以外もページになる
+
+ルートになるのは `.tsx` / `.jsx` だけではありません。**`.csv` と `.xlsx`** はそのまま表として
+読めるページになり、**`<name>.slide.tsx`** はスライドデッキになります。どちらも URL の作り方は
+tsx と同じで、`vantage routes` にも `useRoutes()` のナビにも同格で並びます。
+
+### データファイル（`.csv` / `.xlsx`）
+
+`src/data/june.xlsx` を置いて `/data/june` を開くと、ダウンロードせずブラウザ上で表として
+読めます。xlsx は複数シートを切り替えられ、元ファイルをダウンロードする導線も付きます。
+
+描かれるのは**表計算ソフトそのものの見た目**です —— 列は A / B / C、左に行番号、ファイルの
+1 行目はヘッダとして固定され、罫線はデータの外まで続きます。シートのタブは下端に並びます。
+読み取り専用なので編集もソートもできません(セルを選んで `Cmd/Ctrl+C` でコピーはできます)。
+並べ替えや絞り込みが要るデータは、`server/api/` から配って `DataTable` で描いてください。
+
+- **タイトルはファイル名から導かれます**（`june.xlsx` → 「June」、`index.csv` はディレクトリ名）。
+  データファイルに `definePage` は書けないので、名前を変えたいときはファイルをリネームします。
+- **パースはブラウザで行われます。** dev・ビルド後・デプロイ後で同じコードが同じバイトを読むので、
+  同じ URL が同じものを返します。25MB を超えるファイルはそのページにエラーが出ます
+  （`vantage check` が `FILE_PAGE_TOO_LARGE` で先に警告します）。
+- 数式・グラフ・セル書式は再現されません。**値として読めれば十分**という設計です。
+- ページにしたくないファイルは `_` を前置します（`_june.xlsx`）。tsx から自分で描きたいときは
+  こうしてルート化を止め、`@squadbase/vantage/table` の `FilePageView` を使います。
+
+> [!WARNING]
+> **ビューアの無い拡張子はルートになりません。** `.xls` / `.ods` / `.tsv` などを置いても
+> 404 にすらならず、ナビにも `vantage routes` にも出ません。`vantage check` の
+> `UNSUPPORTED_PAGE_FILE` 警告が唯一の告知点です。
+
+### スライド（`.slide.tsx`）
+
+`.slide` は**ページ種別サフィックス**で、URL には出ません（`src/june.slide.tsx` → `/june`）。
+中身は `<SlideDeck>` を返す普通の React コンポーネントなので、`definePage` もナビも
+通常のページと同じように効きます。
+
+```tsx
+import { definePage } from "@squadbase/vantage";
+import { Slide, SlideDeck } from "@squadbase/vantage/slide";
+
+export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" });
+
+export default function Deck() {
+  return (
+    <SlideDeck>
+      <Slide>…</Slide>
+      <Slide>…</Slide>
+    </SlideDeck>
+  );
+}
+```
+
+1920×1080 の固定キャンバスに書き、画面サイズに合わせて縮小されます。キーボードとクリックで
+送れ、左のスライド一覧は `L` で開閉、`F` で全画面、ツールバーから pptx を書き出せます。詳しくは
+[UI とテーマ](ui-and-theming)。
+
+> [!WARNING]
+> `.slide` を付けられるのは**ルートになるページモジュールだけ**です。`_layout.slide.tsx` や
+> `deck.slide.ts` は `INVALID_PAGE_VARIANT` エラーになります。また `june.slide.tsx` と
+> `june.tsx`、`sales.csv` と `sales.tsx` はいずれも同じ URL に解決するので `ROUTE_CONFLICT` です。
+
 ## ルーティングされないディレクトリ
 
 次のディレクトリは（どの階層でも）決して走査されません。ここには自由にコードを置けます。
@@ -149,6 +213,8 @@ export default function RootLayout() {
 | `index` | `boolean` | ディレクトリの index ルートか |
 | `label` | `string` | `navLabel` → `title` → `path` の順で決まる表示名 |
 | `title` / `description` / `navLabel` | `string \| undefined` | [`definePage`](pages-and-metadata) の値 |
+| `kind` | `"module" \| "file"` | 何から描かれるか。`"file"` は `.csv` / `.xlsx` |
+| `variant` | `"slide" \| undefined` | ページ種別サフィックス |
 
 `useCurrentRoute()` は今表示中のルートを返します（404 のときは `undefined`）。
 上の例のような「現在地」判定のほか、パンくずやページ見出しに使えます。
@@ -188,8 +254,10 @@ setSegments((prev) => [...prev, "enterprise"]);
 
 ## HMR とルート再生成
 
-`.tsx` ページや `server/api` ファイルを追加・削除すると、開発サーバーがルートを再生成して
-フルリロードします。ページ本体を編集した場合は React Fast Refresh がその場で反映します。
+`.tsx` ページ・データファイル・`server/api` ファイルを追加・削除すると、開発サーバーがルートを
+再生成してフルリロードします。ページ本体を編集した場合は React Fast Refresh がその場で反映します。
+`.csv` / `.xlsx` は**中身を書き換えたときもフルリロード**します（実行時に固定 URL から取得される
+ので、モジュールグラフは変化しないためです）。
 
 ## 次に読む
 

package/docs/ja/ui-and-theming.md

@@ -40,6 +40,80 @@ export default function Overview() {
 
 各コンポーネントの props と使い方は [コンポーネント](components) タブにまとめてあります。
 
+## 専用サブパスの UI
+
+重い依存を持つ 3 つは、使うアプリだけが取り込むよう別サブパスに隔離してあります。
+
+| サブパス | 何が入っているか |
+|---|---|
+| `@squadbase/vantage/markdown` | `MarkdownRenderer`（Shiki の全言語文法を引き込むため隔離） |
+| `@squadbase/vantage/table` | `TableViewer` / `FilePageView`（csv・xlsx のパーサを動的 import） |
+| `@squadbase/vantage/slide` | スライドのプリミティブ（pptx 書き出しを動的 import） |
+
+`/components` の barrel に混ぜると、`DataTable` を使うだけのアプリにも import の辺ができて
+バンドラが落とせなくなるためです。
+
+### 表ビューア（`/table`）
+
+`.csv` / `.xlsx` を `src/` に置けば[自動でページになります](routing)。自分でタイトルを付けたい、
+ダッシュボードの一部として表を埋めたい、といったときだけ直接使います。
+
+```tsx
+import { FilePageView, TableViewer, SheetGrid, loadWorkbook } from "@squadbase/vantage/table";
+```
+
+| 名前 | 役割 |
+|---|---|
+| `FilePageView` | ファイルページそのもの。URL を渡すと取得・パース・表示まで面倒を見る |
+| `TableViewer` | 1 シートを枠付きで描く（ビューポートの残りを埋め、下端にシートタブと行数） |
+| `SheetGrid` | 表計算ソフトのグリッド本体。高さの決まった親の中に置く |
+| `loadWorkbook` | URL → パース済みのシート配列 |
+
+見た目は**表計算ソフトそのもの**です —— 列は A / B / C、左に行番号、ファイルの 1 行目は
+ヘッダとして固定、罫線はデータの外まで続きます。読み取り専用で、ツールバーもソートも
+ページネーションもありません（セルを選んで `Cmd/Ctrl+C` でコピーはできます）。並べ替えや
+絞り込みが要るなら、それは表ビューアではなく [`DataTable`](parts/data-table) の
+仕事です。配色はアプリのテーマトークンで塗られるので、ダークモードにも追従します。
+
+### スライド（`/slide`）
+
+`<name>.slide.tsx` を[置くとスライドデッキのページになります](routing)。
+
+```tsx
+import {
+  MorphElement, Slide, SlideDeck, Step, Steps, useSlideNumber,
+} from "@squadbase/vantage/slide";
+```
+
+| 名前 | 役割 |
+|---|---|
+| `SlideDeck` | デッキの器。`theme` でトークンを上書き、`embedded` でページ内に埋め込む、`rail={false}` で一覧を閉じた状態から始める |
+| `Slide` | 1 枚。`transition` で enter / exit を宣言する |
+| `Steps` / `Step` | 段階表示。`→` で 1 つずつ開く |
+| `MorphElement` | 2 枚にまたがる同一要素を連続して動かす（同じ `id` を両方に付ける） |
+| `useSlideNumber` | `{ current, total }`。ページ番号のフッター用 |
+| `useIsActiveSlide` | 聴衆が見ているインスタンスかどうか。入場アニメーションの門番に使う |
+
+読み手は見え方を 3 通りに切り替えられます — **一覧 + スライド**（既定。左にサムネイル列）、
+**スライドのみ**（`L` で一覧を閉じ、表示領域いっぱいに描く）、**全画面**（`F`。一覧は退く）。
+どれもコードでは決めず、開閉の状態は `?rail=` に入るのでその状態のリンクを共有できます。
+閉じた状態から始めたいデッキだけ `<SlideDeck rail={false}>` と書きます（`embedded` は既定で閉）。
+サムネイル列はデッキ自身の `--slide-bg` / `--slide-fg` の混色だけで塗られるので、色味を持たず
+デッキのテーマにそのまま馴染みます。
+
+スライドは **1920×1080 の固定キャンバス**に絶対 px で書き、画面サイズに合わせて縮小されます。
+配色と書体は `--slide-*` トークン（下の「テーマトークン」と同じ仕組みで、既定はアプリのトークンへの
+別名なので**ダークモードにも自動で追従します**）。
+
+書き方の作法 — キャンバスの縦方向の予算、タイプスケール、トランジションの設計原則、モーフの規則、
+pptx 書き出しが壊れる条件 — は同梱の **`vantage-slide` スキル**にあります
+（[エージェント Skill](agent-skills)）。
+
+> [!NOTE]
+> スライドの中で `@squadbase/vantage/ui` のプリミティブを使わないでください。UI キットは rem と
+> Tailwind でダッシュボード向けに組まれているので、1920×1080 を縮小投影すると `text-sm` のボタンは
+> 実効 8px 程度になって読めません。
+
 ## Tailwind はそのまま使える
 
 `className` に Tailwind ユーティリティを書くだけで効きます。`tailwind.config` も `postcss.config`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.5.3-dev.71d2349",
+  "version": "0.6.0-dev.3cc6138",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",
@@ -59,6 +59,14 @@
       "types": "./dist/markdown/index.d.ts",
       "default": "./dist/markdown/index.js"
     },
+    "./table": {
+      "types": "./dist/table/index.d.ts",
+      "default": "./dist/table/index.js"
+    },
+    "./slide": {
+      "types": "./dist/slide/index.d.ts",
+      "default": "./dist/slide/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"
@@ -84,7 +92,8 @@
     "theme.css",
     "registry",
     "skills",
-    "templates"
+    "templates",
+    "NOTICE"
   ],
   "scripts": {
     "build": "node scripts/build-docs.mjs && node scripts/build.mjs",
@@ -116,10 +125,14 @@
     "date-fns": "^4.1.0",
     "echarts": "^6.0.0",
     "esbuild": "^0.28.1",
-    "hono": "^4.12.30",
+    "fflate": "^0.8.3",
+    "hono": "^4.13.5",
+    "html-to-image": "^1.11.13",
     "lucide-react": "^0.468.0",
+    "papaparse": "^5.7.0",
     "picocolors": "^1.1.1",
     "react-day-picker": "^10.0.1",
+    "read-excel-file": "^9.3.10",
     "streamdown": "^2.5.0",
     "tailwind-merge": "^3.0.0",
     "tailwindcss": "^4.3.2",
@@ -132,6 +145,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/papaparse": "^5.5.2",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
     "react": "^19.2.7",

package/skills/vantage-app/SKILL.md

@@ -75,6 +75,10 @@ vantage add skill  # 配置済みの skill(このファイルの仲間)と、そ
 - 共通の枠(ヘッダ・サイドバー)は `_layout.tsx`、Not Found と例外は `_404.tsx` / `_error.tsx`。
 - 一覧 → 詳細を作るなら、**動的パラメータの「3 つの綴り」を先に決めてから**両方のファイルを
   書く。後から変えると静かにマッチしなくなる。
+- **ページになるのは tsx だけではない。** `.csv` / `.xlsx` を `src/` に置けば表として読めるページに
+  なり、`<name>.slide.tsx` はスライドデッキになる(どちらもナビに同格で並ぶ)。ダッシュボード・
+  スライド・データを 1 つのアプリに並べたいときは、まずこの 2 つで足りないか考える —— 表を出すために
+  ページを書く必要は無い。スライドの書き方は `vantage-slide` スキル。
 
 ## Step 3 — データを繋ぐ
 

package/skills/vantage-pitfalls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vantage-pitfalls
-description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、Select の value/label、クライアントから server/ を import しない、EChart の配色と高さ、動的パラメータの3綴り同期、PUBLIC_ env、HttpError など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
+description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、Select の value/label、クライアントから server/ を import しない、EChart の配色と高さ、動的パラメータの3綴り同期、PUBLIC_ env、HttpError、csv/xlsx ページの URL 衝突とサイズ上限、スライドの data-waitfor など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
 ---
 
 # Vantage アプリの落とし穴リファレンス
@@ -153,6 +153,46 @@ import { type ColumnDef } from "@squadbase/vantage/components"
 const columns: ColumnDef<Row>[] = [ … ]   // 注釈しないと accessorKey が string に広がり弾かれる
 ```
 
+## データファイルページ:同名の tsx と衝突する / ブラウザでパースされる
+
+`src/` に置いた `.csv` / `.xlsx` はページになる。ここで静かに壊れるのは 3 つ。
+
+- **`sales.csv` と `sales.tsx` はどちらも `/sales`** に解決するので `ROUTE_CONFLICT` エラー。
+  `.slide.tsx` も同じ(`june.slide.tsx` と `june.tsx`)。
+- **パースはブラウザで走る。** 25MB を超えるファイルはそのページがエラー表示になる
+  (`vantage check` が `FILE_PAGE_TOO_LARGE` で先に警告する)。大きいデータは `server/api/` から
+  配って `DataTable` で描く。
+- **ビューアの無い拡張子(`.xls`・`.ods`・`.tsv` など)はルートにならない。** 404 ですらなく、
+  ナビにも `vantage routes` にも出ない。`vantage check` の `UNSUPPORTED_PAGE_FILE` 警告が
+  唯一の告知点なので、「置いたのに出てこない」ときはまず `check` を見る。
+
+ビューアは**表計算ソフトの見た目の読み取り専用グリッド**(列は A / B / C、左に行番号、1 行目は
+固定、シートのタブは下端)。**ソート・フィルタ・ページネーションは持たない** —— 並べ替えや
+絞り込みが要るなら `server/api/` から配って `DataTable` で描く。数式・グラフ・セル書式は
+再現されない(値として読めれば十分、という設計)。
+
+## スライド:`data-waitfor` を忘れるとチャートが白紙で書き出される
+
+`.slide.tsx` の pptx 書き出しはスライドを画像として焼く。**canvas に描くもの(`EChart`)は
+描き終わりを待たせないと、描画前に撮られてそのスライドだけ白紙になる**:
+
+```tsx
+<div data-waitfor="canvas">
+  <EChart option={option} style={{ width: 1400, height: 600 }} />
+</div>
+```
+
+ほかに 2 つ。
+
+- **`@squadbase/vantage/ui` のプリミティブをスライドに置かない。** UI キットは rem と Tailwind で
+  組まれているので、1920×1080 を縮小投影すると `text-sm` のボタンが実効 8px 程度になって読めない。
+  スライドは絶対 px のインラインスタイルで書く。
+- **dev サーバーを起動したあとに最初の `.slide.tsx` を新規作成した場合、初回の pptx 書き出しで
+  1 回だけリロードが入る。** 書き出し用の依存はプロジェクトがデッキを持つときだけ宣言される仕組みで、
+  その判定は dev の起動時に 1 度しか走らないため。`vantage dev` を再起動すれば解消する。
+
+書き方の作法(キャンバスの縦方向の予算、段階表示、トランジション、モーフ)は `vantage-slide` スキル。
+
 ## 生成物:`.vantage/` と `dist/` は触らない
 
 どちらも gitignore 済みの生成物。編集しても次のコマンドで上書きされる。`.vantage/` は任意の CLI

package/skills/vantage-slide/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: vantage-slide
+description: Vantage(@squadbase/vantage)で `.slide.tsx` のスライドデッキを書く / 直すときの技術リファレンス。ファイル契約、1920×1080 固定キャンバスと縦方向の予算、タイプスケールとレイアウト、デザイントークン、段階表示(Steps/Step)、ページ間トランジションとモーフ、pptx 書き出しの前提条件を扱う。`src/**/*.slide.tsx` を書く・触る前に読む。「スライドを作って」「デッキを1本」「この頁のレイアウトを直して」「1つずつ出したい」「pptx で出したい」で起動。
+---
+
+# `.slide.tsx` でスライドを書く
+
+このスキルは**技術リファレンス**です。Vantage アプリの一般規約（ページの置き場所・import サブパス・
+禁止ファイル）は `AGENTS.md` が正本で、ここでは繰り返しません。スライド固有のことだけを扱います。
+
+関連: 新しいページ / API / UI を 1 つ足す定型は `vantage-add-feature`、静かに壊れる落とし穴の
+一覧は `vantage-pitfalls`。
+
+## プリミティブのリファレンス
+
+各プリミティブには `references/` に個別のファイルがあります。**使う前にそのファイルを読むこと。**
+
+| プリミティブ | 読むべき場面 | ファイル |
+| --- | --- | --- |
+| `<Steps>` / `<Step>` | 段階表示を作るとき | `references/steps.md` |
+| `SlideTransition` | enter / exit のアニメーションを書くとき | `references/transitions.md` |
+| `MorphElement` + `morph` | 2 枚にまたがる同一要素を動かすとき | `references/morph.md` |
+| `<SlideDeck theme>` / `var(--slide-*)` / webfont | 配色・書体を決めるとき、pptx を出すとき | `references/tokens.md` |
+
+## ファイル契約
+
+```tsx
+// src/june.slide.tsx  →  /june（`.slide` は URL に出ない）
+import { definePage } from "@squadbase/vantage"
+import { Slide, SlideDeck, Step, Steps, useSlideNumber } from "@squadbase/vantage/slide"
+
+export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" })
+
+export default function JuneDeck() {
+  return (
+    <SlideDeck theme={{ bg: "#0f172a", fg: "#f8fafc", accent: "#fbbf24" }}>
+      <Slide>…</Slide>
+      <Slide transition={RISE}>…</Slide>
+    </SlideDeck>
+  )
+}
+```
+
+- **1 ファイル = 1 デッキ = 1 ルート。** `export default` は `<SlideDeck>` を返す React コンポーネント
+  （通常のページと同じ契約なので、`vantage check` も `vantage routes` も特別扱いをしません）。
+- **スライドは `<SlideDeck>` の直下の `<Slide>`。** 深くネストした `<Slide>` は拾われません。
+- `definePage` の `title` / `navLabel` はビルド時に静的抽出されるので**リテラルで書く**（変数・
+  テンプレート補間は不可）。ナビの表示名はこれで決まります。
+- **`.slide` を付けられるのはルートになるページモジュールだけ。** `_layout.slide.tsx` や
+  `deck.slide.ts` は `INVALID_PAGE_VARIANT` エラーになります。
+- **`june.slide.tsx` と `june.tsx` は同じ URL** になるので `ROUTE_CONFLICT` です。どちらかを消すこと。
+- **デッキファイル以外を作らない。** ヘルパーコンポーネントも定数も同じ `.slide.tsx` の中に書く。
+  スライド専用のコンポーネントを `components/` に切り出すと、デッキ 1 本を読むのに 2 ファイル
+  追わせることになります。
+
+## import してよいもの
+
+- `@squadbase/vantage/slide` — `SlideDeck` `Slide` `Steps` `Step` `MorphElement` `useSlideNumber`
+  `useIsActiveSlide` `SlideCanvas` と、その型
+- `@squadbase/vantage` — `definePage`
+- `@squadbase/vantage/components` の `EChart` — **チャートを載せるときはこれ**（→「チャート」）
+- `lucide-react` のアイコン
+
+**`@squadbase/vantage/ui` のプリミティブはスライドに使わない。** UI キットは rem と Tailwind で
+ダッシュボード向けに組まれているので、1920×1080 を縮小投影すると `text-sm` のボタンは実効 8px 程度に
+なって読めません。スライドは**絶対 px のインラインスタイル**で書きます。
+
+## キャンバス
+
+各スライドは **1920 × 1080** の固定キャンバスに描かれ、フレームワークが画面に合わせて縮小します。
+ビューポートが文字どおり 1920×1080 だと思って設計してください。
+
+- `font-size`・padding・位置は**絶対 px**。`rem`・`vw`/`vh`・文字サイズの `%` は使わない
+- 各スライドのルート要素はキャンバスを埋める（`width: "100%"; height: "100%"`）
+- インライン `style={{ … }}` を使う。読み込んだ CSS はグローバルです
+
+### タイプスケール（ここから始めて調整する）
+
+| 要素 | サイズ |
+| --- | --- |
+| ヒーロータイトル | 140–200px |
+| セクション見出し | 80–120px |
+| ページ見出し | 56–80px |
+| 本文 | 32–44px |
+| キャプション / ラベル | 22–28px |
+
+### 余白
+
+- コンテンツの padding: キャンバス端から **100–160px**。文字を端に触れさせない
+- line-height: 見出し 1.2、本文 1.5–1.7
+- 要素間: 32–64px
+
+### 縦方向の予算 — 中身は 1080px に収まらなければならない
+
+キャンバスは**スクロールしません**。1080px の下端を越えたものは黙って切れます。JSX を書く前に
+計算して収まることを確かめること。**これがスライドが壊れる原因の第 1 位**で、確かめない限り
+溢れていると思ってください。
+
+**使える高さ** = `1080 − 上 padding − 下 padding`。上下 120px なら **840px**、160px なら **760px**。
+先に padding を決めて、その予算の中で設計します。
+
+**要素の高さ** = `文字サイズ × line-height × 行数`。2 行に折り返す箇条書きは 2 行と数えます。
+次の要素を足す前に、その下の gap（32–64px）を加算してください。
+
+**計算例 — 本文 1 枚、padding 120px（予算 840px）:**
+
+| 要素 | 高さ |
+| --- | --- |
+| 見出し: 80px × 1.2 × 1 行 | 96px |
+| gap | 64px |
+| 本文: 40px × 1.6 × 3 行 | 192px |
+| gap | 48px |
+| 箇条書き 5 行: 40px × 1.6 × 1 行 | 320px（5 × 64px） |
+| 箇条書き間の gap 4 つ: 24px | 96px |
+| **合計** | **816px ✅ 840 に収まる** |
+
+見出しを 120px にするか箇条書きを 6 つにすると溢れます。**書く前に毎ページこの検算をすること。**
+
+**ページ単位の規則:**
+
+- 「見出し + 本文」か「見出し + 5 つ以内の短い箇条書き」のどちらか。両方は載せない
+- 箇条書きは選んだ文字サイズで 1 行に収まること。折り返すなら短くするか別ページに割る
+- ヒーロータイトル（140–200px）はタイトル + サブタイトル 1 行 + アイブロウまで。それ以外は載せない
+- セクション見出し（80–120px）のページにはほとんど何も足さない
+- 収めるために padding を上げる・スケールの下限より小さい文字にする・本文の line-height を 1.4 未満に
+  詰める、をやりたくなったら**ページを 2 枚に割る**。予算が厳しいときは分割が常に正解
+
+**`overflow: auto/scroll`・負のマージン・transform で溢れを隠さないこと。** キャンバスは固定で、
+切れた中身は消えています。
+
+## ビジュアルの方向
+
+一貫した見た目を選び、全ページで保つこと。
+
+- **配色** — 背景 1・本文 1・アクセント 1・ミュート 1。前の 3 つは `<SlideDeck theme>` に入れ、
+  それ以外はプレーンな const にする（→ `references/tokens.md`）
+- **書体** — ディスプレイ 1 + 本文 1。指定がなければシステムスタック。見出しは太く（800–900）、
+  本文は通常（400–500）
+- **レイアウトグリッド** — padding を 1 つ決めて（例: 120px）貫く。左揃えは編集的、中央揃えは儀礼的
+- **美学のコミットメント** — 1 つ選ぶ: ミニマル / マキシマル / エディトリアル / レトロ /
+  ブルータリスト / ソフト・パステル / ネオン / 紙・印刷。混ぜない
+
+## 繰り返す要素は `map` ではなくコンポーネント
+
+カード・ロゴの列・タイル・行など**視覚的に繰り返す**要素は、小さなコンポーネントを定義して
+**1 件につき 1 回インスタンス化**します。データ配列を `map` して 1 つのテンプレートから描かない。
+
+```tsx
+// ✅ 各カードが独自の JSX ノードを持つ
+const Card = ({ label, value }: { label: string; value: string }) => (
+  <div style={{ flex: 1 }}>
+    <div style={{ fontSize: 28, opacity: 0.6 }}>{label}</div>
+    <div style={{ fontSize: 120, fontWeight: 800 }}>{value}</div>
+  </div>
+)
+
+<div style={{ display: "flex", gap: 96 }}>
+  <Card label="売上" value="¥5.2億" />
+  <Card label="解約率" value="1.4%" />
+</div>
+```
+
+`map` の本体は**ソース上 1 箇所**なので、あとから 1 枚だけ文言や色を変えたいときに全部が一緒に
+変わります。コンポーネント定義がレイアウトの単一の正本のまま、インスタンスごとの値だけが
+呼び出し側に出る形が正しい。
+
+これは**視覚要素が繰り返すとき**の話で、データが繰り返すときの話ではありません。純粋な
+テキストの箇条書き（`<ul><li>`）は各 `<li>` が既に独立した JSX ノードなので、そのままで正しい。
+
+## ページ番号
+
+フッターに現在位置を出すなら `useSlideNumber()` から読む。**ハードコードしない。**
+
+```tsx
+const { current, total } = useSlideNumber()  // current は 1 始まり
+```
+
+スライドを差し込む・並べ替える・消すたびに全フッターを直す羽目になるのを避けられます。
+
+## チャート
+
+チャートは `@squadbase/vantage/components` の `EChart` を使います。**canvas に描かれるので、
+pptx 書き出しのために描き終わりを待たせる必要があります**:
+
+```tsx
+<div data-waitfor="canvas">
+  <EChart option={option} style={{ width: 1400, height: 600 }} />
+</div>
+```
+
+`data-waitfor` を付けないと、書き出しがチャートの描画前にスクリーンショットを撮り、
+**そのスライドだけチャートが白紙**で出ます。
+
+チャートに色をハードコードしないこと（`option.color` / `itemStyle.color` / `theme`）。
+`EChart` はテーマトークンに追従します。
+
+## 実行時に無料で付いてくるもの
+
+- `src/june.slide.tsx` → `/june`。ナビ（`useRoutes()`）に通常のページと同格で並ぶ
+- `→ ↓ Space PageDown` で次、`← ↑ PageUp` で前、`Home` / `End` で端へ
+- 画面の左右 30% のクリックでも送れる（中央は不活性。リンク・ボタンの上は素通し）
+- `F` で全画面、`Escape` で全画面を抜ける / デッキから戻る
+- `L` でスライド一覧（左のサムネイル列）を開閉。クリックでその枚へ飛ぶ
+- 現在位置は URL の `?p=` に入る（履歴は汚れない）。`?p=4` のリンクをそのまま共有できる
+- ツールバーから **pptx 書き出し**
+- 画面サイズを変えても縮尺が変わるだけでレイアウトは崩れない
+
+見え方は 3 通りで、切り替えはすべて実行時（コードでは決めない）:
+
+| 見え方 | 出し方 |
+|---|---|
+| 全画面 | `F` / ツールバー。スライドだけになり、一覧は退く |
+| 一覧 + スライド（既定） | 左にサムネイル、右にスライド |
+| スライドのみ | `L` / ツールバー で一覧を閉じる。表示領域いっぱいに 16:9 を描く |
+
+一覧の開閉は `?rail=` にも入るので、閉じた状態のリンクも共有できます。
+閉じた状態から始めたいデッキだけ `<SlideDeck rail={false}>` と書きます
+（`embedded` のデッキは幅が無いので既定で閉じています）。サムネイルの配色はデッキ自身の
+`--slide-bg` / `--slide-fg` の混色だけで作られていて、色味は持ちません。
+
+## pptx 書き出しの前提
+
+デッキは**画像として**書き出されます。1 スライド = 1 枚の PNG（3840×2160）。文字は入らないので
+受け取り側にフォントが要らず、日本語も欠けません。代わりに**書き出した pptx の文字は検索・編集
+できません**（ブラウザで見ている間は DOM なので選択できます）。
+
+書き出しが壊れる典型は 2 つ:
+
+1. **`data-waitfor` を付けないチャート**（→「チャート」）
+2. **サブセットしていない日本語 webfont**（→ `references/tokens.md`）
+
+段階表示は**全部開いた状態**で書き出されます（`<Steps>` はホストが無いと全開）。
+
+## 仕上げ前のセルフレビュー
+
+- [ ] `export default` が `<SlideDeck>` を返している
+- [ ] `<Slide>` が `<SlideDeck>` の直下にある
+- [ ] 各スライドのルート要素が `100% × 100%` を埋めている
+- [ ] 文字が padding の内側にある（端に触れていない）
+- [ ] **全ページで（文字サイズ × line-height × 行数）+ gap + padding×2 ≤ 1080px。** 際どいなら分割
+- [ ] 箇条書きが 2 行目に折り返していない
+- [ ] 配色とタイプスケールが全ページで一貫している
+- [ ] 1 ページ 1 メッセージ
+- [ ] 繰り返す視覚要素が `array.map` ではなく明示的な `<Component />` になっている
+- [ ] ページ番号が `useSlideNumber()` から来ている（ハードコードしていない）
+- [ ] チャートが `data-waitfor="canvas"` で包まれている
+- [ ] `<Steps>` を使ったページが、`?p=` で直接開いても完成した絵として読める
+- [ ] トランジションを宣言したなら、全ページが 1 つの family に収まっている（→ `references/transitions.md`）
+- [ ] `definePage` の値がリテラルである
+- [ ] `.slide.tsx` 以外のファイルを作っていない
+
+## アンチパターン
+
+- ❌ 文字の壁。1 ページ 40 語を超えたら分割する
+- ❌ キャンバス全面を本文で使う。padding 100–160px を守る
+- ❌ 縦に 1080px を溢れさせる。切れた中身は見えない — 分割する
+- ❌ `overflow: auto` / `scroll` / `hidden` で溢れを「隠す」。バグを隠しただけ
+- ❌ 詰め込むためにスケールの下限より小さい文字にする・padding を 100px 未満にする
+- ❌ 本文 28px 未満。プロジェクタで読めない
+- ❌ `@squadbase/vantage/ui` のプリミティブをスライドに置く（縮小されて読めなくなる）
+- ❌ 依存を追加する。使えるのは `@squadbase/vantage/*` と `lucide-react` と標準 Web API だけ
+- ❌ スライド用のコンポーネントを別ファイルに切り出す
+- ❌ チャートに `data-waitfor="canvas"` を付け忘れる（pptx が白紙になる）
+- ❌ プリミティブを `references/*.md` を読まずに使う