@squadbase/vantage-template 0.1.0 → 0.1.1-dev1.3f269fd

package/README.md

@@ -19,20 +19,20 @@ Initialize a new Vantage project in the current directory. Copies the base templ
 ```bash
 npx @squadbase/vantage-template init
 npx @squadbase/vantage-template init --force                  # Overwrite existing files
-npx @squadbase/vantage-template init --skip-install           # Skip npm install
+npx @squadbase/vantage-template init --skip-install           # Skip dependency install (bun, or npm if bun is absent)
 npx @squadbase/vantage-template init --chart sunset           # Apply a chart preset during init
 ```
 
-After initialization:
+After initialization (the template ships `bun.lock` and declares `package_manager: bun` in `squadbase.yml`; `npm run` works too once dependencies are installed):
 
 ```bash
-npm run dev      # vantage dev --no-overlay — dev server + API on :5173
-npm run build    # vantage build → dist/
-npm run check    # vantage check — static diagnostics
-npm run routes   # vantage routes — page/API route map
+bun run dev      # vantage dev --no-overlay — dev server + API on :5173
+bun run build    # vantage build → dist/
+bun run check    # vantage check — static diagnostics
+bun run routes   # vantage routes — page/API route map
 ```
 
-There is no `vite.config.ts`, no `main.tsx`, and no route table: adding a file under `src/` adds a route (`src/index.tsx` → `/`, `src/sales/[id].tsx` → `/sales/:id`), and `src/_layout.tsx` builds the nav from `useRoutes()`.
+There is no `vite.config.ts`, no `main.tsx`, and no route table: adding a file under `src/` adds a route (`src/index.tsx` → `/`, `src/sales/[id].tsx` → `/sales/:id`), and `src/_layout.tsx` builds the nav from `useRoutes()`. The layout passes Vantage's `useNavigate()` to the header page selector so selecting a page updates the route without reloading the app.
 
 Since `@squadbase/vantage` v0.3.0, `src/` is the page-scan root and does not appear in URLs. `server/` and `public/` stay at the project root — `src/server/` is never scanned.
 

package/base-template/.squadbase/skills/vantage-app/SKILL.md

@@ -14,7 +14,7 @@ description: Vantage(@squadbase/vantage)ダッシュボードアプリを一か
 
 ## 全体の流れ
 
-1. **骨組み** — `pnpm dev` が上がるところまで
+1. **骨組み** — `bun run dev` が上がるところまで
 2. **ルートを決める** — ページファイルを置き、`vantage routes` で URL を確認
 3. **データを繋ぐ** — 外部 API か、自前の `server/api` か
 4. **仕上げ** — `check` → `build` → `preview`
@@ -52,7 +52,7 @@ exit 1 になる。
 ```
 
 `index.tsx` はデフォルトエクスポートの React コンポーネント 1 つ(これが `/` になる)。あとは
-`pnpm install && pnpm dev` で http://localhost:5173 が上がる。
+`bun install && bun run dev` で http://localhost:5173 が上がる(このプロジェクトの package manager は bun。`bun.lock` を持つ)。
 
 **既存アプリに合流したときは、作る前に現状を読む:**
 
@@ -105,10 +105,10 @@ vantage add skill  # 配置済みの skill(このファイルの仲間)と、そ
 ## Step 4 — 仕上げ
 
 ```bash
-pnpm check     # エラーが残っていないか(exit 1 なら残っている)
-pnpm routes    # 公開される URL の最終確認
-pnpm build     # dist/ に client(+ server)+ vantage-manifest.json
-pnpm preview   # 本番ビルドをローカルで動かす
+bun run check     # エラーが残っていないか(exit 1 なら残っている)
+bun run routes    # 公開される URL の最終確認
+bun run build     # dist/ に client(+ server)+ vantage-manifest.json
+bun run preview   # 本番ビルドをローカルで動かす
 ```
 
 `vantage-manifest.json` の `mode` は `server/` の有無から自動で決まる(手で書かない)。

package/base-template/.squadbase/skills/vantage-design/SKILL.md

@@ -77,7 +77,7 @@ Vantage アプリの見た目は 2 つのファイルで決まる。
 
      ```css
      body {
-       font-family: "<Font>", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+       font-family: "<Font>", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Noto Sans JP", "Yu Gothic UI", Meiryo, sans-serif;
      }
      :root {
        --slide-font-display: "<Font>", system-ui, -apple-system, "Hiragino Kaku Gothic ProN", "Hiragino Sans", "Yu Gothic", Meiryo, sans-serif;
@@ -85,6 +85,8 @@ Vantage アプリの見た目は 2 つのファイルで決まる。
      }
      ```
 
+  欧文の Web フォントだけを先頭に足すときも、日本語の system face(`"Hiragino Sans"` 〜 `Meiryo`)は
+  必ず残す。消すとカナ・漢字がブラウザ任せのフォールバックになり、細く表示される。
   日本語の Web フォントは face が 100 を超えるので原則使わない(pptx 書き出しも壊れる。
   `vantage-slide` の `references/tokens.md` 参照)。
 

package/base-template/.squadbase/skills/vantage-design/references/format.md

@@ -119,7 +119,7 @@ DESIGN.md — このアプリの「見た目の意図」を書くファイルで
 
 | 用途 | 指定 | 備考 |
 | --- | --- | --- |
-| 見出し・本文 | システムフォント(`body` の `font-family`) | Web フォントは使わない |
+| 見出し・本文 | 日本語を含むシステムフォント(`body` の `font-family`) | Web フォントは使わない |
 | 数字 | 同上 + `tabular-nums` | 桁がそろうように必ず付ける |
 | スライドの見出し | `--slide-font-display` | 既定は日本語を含むシステムフォント |
 | スライドの本文 | `--slide-font-body` | 既定は見出しと同じ |

package/base-template/AGENTS.md

@@ -302,6 +302,34 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
 })
 ```
 
+### 生の応答から行を取り出す(`noUncheckedIndexedAccess`)
+
+テンプレートの `tsconfig.json` は `noUncheckedIndexedAccess: true`。**配列の添字はすべて
+`T | undefined`** なので、HTTP Query が通す上流の生の応答(GA4 の `rows[].metricValues[]` など)を
+`row.metricValues[0].value` と書くと `Object is possibly 'undefined'.` で落ちる。書く前に添字
+アクセスを頭の中で型検査し、応答の型と行の変換関数を先に決めて `?.` と `??` で取り出す:
+
+```ts
+type Ga4Row = {
+  dimensionValues?: { value?: string }[]
+  metricValues?: { value?: string }[]
+}
+type SessionsDaily = { date: string; sessions: number; pageViews: number }
+
+const toSessionsDaily = (row: Ga4Row): SessionsDaily => ({
+  date: row.dimensionValues?.[0]?.value ?? "",
+  sessions: Number(row.metricValues?.[0]?.value ?? "0"),
+  pageViews: Number(row.metricValues?.[1]?.value ?? "0"),
+})
+
+const report = (await res.json()) as { rows?: Ga4Row[] }
+return Response.json((report.rows ?? []).map(toSessionsDaily))
+```
+
+- 値が欠けた行を落としたいときは `if (!date) throw new HttpError(502, …)` ではなく、変換後に
+  `.filter((r) => r.date !== "")` で除く。`date!` のような非 null 断言で黙らせない。
+- SQL Query の `rows` も同じ。`rows[0]` を使うなら `const first = rows[0]; if (!first) …` で先に絞る。
+
 ## 構築中の一時的なエラーを「進行中」に見せる(`components/build-recovery.tsx`)
 
 ページを書いている途中は、ファイルが書き終わる順番の都合で一瞬だけページが throw する
@@ -331,3 +359,82 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
 - **データ取得の失敗は各ページが `ErrorState` で出す。** `BuildRecovery` が拾うのは
   「レンダリングが throw した」場合だけで、`useApiQuery` の `isError` はページの責任
   (→ `agents/page.md` の「データ取得」)。
+
+## 依存の追加とスクリプトの実行は bun で
+
+このプロジェクトの package manager は **bun** です(`squadbase.yml` の `package_manager: bun`、
+lockfile は `bun.lock`)。Squadbase のサンドボックスは bun と依存のキャッシュを持っており、
+`bun install` はキャッシュだけで終わります。上のフレームワーク規約に出てくる
+`pnpm install` / `pnpm dev` / `pnpm check` は、そのまま `bun install` / `bun run dev` /
+`bun run check` に読み替えてください。
+
+### 追加の不変条件
+
+- **依存を足すときは `bun add <pkg>`(開発用は `bun add -d <pkg>`)。** `npm install` や
+  `pnpm add` を使わない — `package-lock.json` / `pnpm-lock.yaml` が生えて `bun.lock` と別の断面に
+  なり、次回起動時の install が lockfile を作り直す。
+- **`bun.lock` を消さない・手で編集しない。** `package.json` の依存を直接書き換えたときは
+  `bun install` を一度走らせて `bun.lock` を追従させ、両方を同じコミットに入れる。
+- スクリプトは `bun run <script>`(`bun run dev` / `bun run build` / `bun run check` /
+  `bun run routes`)。`npm run <script>` でも動くが、install に npm を使わないこと。
+
+## このアプリで作れるもの
+
+ユーザーの目的に合わせて、どの形にするかを選ぶ。ここに書かれていない形は約束しない。
+
+- **ダッシュボード** — 数字を繰り返し見に来て、変化に気づきたいとき。指標と推移・内訳を 1 画面に
+  置き、`server/api/` で実データを取る。
+  - 書き込む場所: `src/<slug>.tsx`, `server/api/<slug>/**`
+  - ページ: あり
+  - 作り方: `src/` にページ(`.tsx`)を置く。書く前に `agents/page.md`(API は `agents/api.md`)を読む。
+- **スライド** — 分析の示唆をまとめて誰かに伝えるとき(調査結果の報告、会議資料、施策の提案)。
+  結論 → 根拠 → 次の一手の順にまとめる。
+  - 書き込む場所: `src/<slug>.slide.tsx`, `vantage-slide/**`
+  - ページ: あり
+  - 作り方: `src/<slug>.slide.tsx` に `<SlideDeck>` を返すページを置く(`@squadbase/vantage/slide`)。
+    書く前に `agents/slide.md` を読み、`vantage-slide` Skill が未配置なら
+    `vantage add skill vantage-slide` で置いてから読む。
+- **ドキュメント** — 報告書・調査のまとめ・説明資料のように、文章と図表を上から読む形で残し
+  共有したいとき。
+  - 書き込む場所: `src/<slug>.doc.tsx`
+  - ページ: あり
+  - 作り方: `src/<slug>.doc.tsx` に `<Document>` を返すページを置く(`@squadbase/vantage/doc`。
+    ルートは `.doc` を除いた `/<slug>`)。数値はコードに直接書き、チャートは `EChart` を文中に置く。
+    書く前に `agents/doc.md` を読む。
+- **オートメーション** — 決まった時刻に集計・通知・定期レポートを回したいとき、しきい値で
+  アラートしたいとき。
+  - 書き込む場所: `automations/<slug>/**`, `pipelines/**`
+  - ページ: なし
+  - 作り方: `automations/<名前>/automation.yml` に定義し、処理のコードは `pipelines/` に置く。
+    書く前に Automation のガイド(`readAutomationGuide`)を読む。
+
+## 表示領域に安定 ID を付ける(`data-sq-ref`)
+
+Squadbase のチャットは、回答の根拠になったグラフ・表・KPI カードを
+`squadbase://page/<path>#<ref>`(スライド内なら `?p=<N>#<ref>`)のリンクで指し、その領域を開く。
+`<ref>` はページのソースに書かれた `data-sq-ref` の値で、過去の回答のリンクもこの値で今の画面を開く。
+
+```tsx
+<DashboardCardPreset data-sq-ref="revenue-trend" title="売上の推移">
+  <EChart option={trendOption(data)} height="320px" />
+</DashboardCardPreset>
+
+{kpis.map((kpi) => (
+  <DashboardCard key={kpi.id} data-sq-ref={kpi.id}>...</DashboardCard>
+))}
+```
+
+### 追加の不変条件
+
+- **意味のまとまった表示領域(グラフ・表・KPI カードなど)のルート要素に付ける。** 通常は
+  `DashboardCard` / `DashboardCardPreset` のように props を DOM に流す部品。`EChart` / `DataTable` /
+  `SectionHeader` は付けた属性を DOM に流さないので、それらを包むカード(または `div`)に付ける。
+- **値の形式は `^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$`**(ASCII の英数字・ハイフン・アンダースコア、先頭は英数字、
+  100 文字以内)。これ以外の値はリンクから開けない。推奨は意味を表す小文字 kebab-case の名前
+  (例: `revenue-trend`, `churn-by-segment`)。表示順・ソース上の位置・index・連番から作らない。
+- **`.map` で描く領域は、データの安定したキー(`kpi.id` など)がこの形式を満たすときだけ `data-sq-ref={kpi.id}`
+  のように使う。** 日本語や空白を含むキーはそのまま使わず、変換もしない(変換規則が変わると値が変わる)。
+  その場合は静的な意味名を付けるか、付けない。
+- **ページ内で一意にする。**
+- **新しく作った・直した画面では付ける。更新では既存の値を変えない** — 領域の意味が変わったときだけ変える
+  (値を変えると、それを指していた過去のリンクが開けなくなる)。触っていない画面へ遡って付けることはしない。

package/base-template/DESIGN.md

@@ -56,7 +56,7 @@ DESIGN.md — このアプリの「見た目の意図」を書くファイルで
 
 | 用途 | 指定 | 備考 |
 | --- | --- | --- |
-| 見出し・本文 | システムフォント(`body` の `font-family`) | Web フォントは使わない |
+| 見出し・本文 | 日本語を含むシステムフォント(`body` の `font-family`) | Web フォントは使わない |
 | 数字 | 同上 + `tabular-nums` | 桁がそろうように必ず付ける |
 | スライドの見出し | `--slide-font-display` | 既定は日本語を含むシステムフォント |
 | スライドの本文 | `--slide-font-body` | 既定は見出しと同じ |

package/base-template/agents/api.md

@@ -25,6 +25,11 @@ export async function GET({ params, env }: ApiContext) {
   エクスポートする。それ以外の名前は `INVALID_API_EXPORT` エラー。
 - 動的 API も `[id].ts` 記法: `server/api/customers/[id].ts` → `GET /api/customers/:id`。
   `params.id` で取り出す(`noUncheckedIndexedAccess` が効くので narrowing が要る)。
+- **`noUncheckedIndexedAccess` は配列・レコードの添字すべてに効く。** `arr[0]` も `obj[key]` も
+  `T | undefined` になる。最初に書く前に、添字アクセスと `useApiQuery` の `data` が
+  undefined を扱っているかを頭の中で型検査してから書く。上流の生の応答の値は
+  `Number(row.metricValues?.[0]?.value ?? "0")` のように `?.` と `??` で取り出す
+  (`!` で黙らせない)。
 - **クライアントに見せたいエラーは `HttpError(status, msg)` を throw する。** それ以外の throw は
   ログに記録され汎用の 500 に丸められる。
 - **シークレットは `ApiContext.env` にだけ届く**(クライアントには決して届かない)。
@@ -34,9 +39,12 @@ export async function GET({ params, env }: ApiContext) {
 
 ```tsx
 import { useApiQuery, useApiMutation } from "@squadbase/vantage/query"
+import { Loading, ErrorState } from "@squadbase/vantage/ui"
 
 const q = useApiQuery<Customer>(`/api/customers/${customerId}`)
+if (q.isPending) return <Loading />
 if (q.isError) return <ErrorState message={q.error.message} />  // HttpError のメッセージ
+q.data  // ここで初めて Customer(undefined ではない)
 
 // クエリ文字列は search で。undefined の項目は落ちる
 const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
@@ -45,5 +53,26 @@ const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
 const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST" })
 ```
 
+**`data` は、同じ結果オブジェクトで `isPending` と `isError` を判定したあとでしか
+narrowing されない。** 判定前や、配列の `.find` などでまとめた判定のあとでは `T | undefined` のまま。
+複数のクエリは 1 本ずつ判定してから `data` を使う(`data!` で黙らせない):
+
+```tsx
+const sessions = useApiQuery<SessionsDaily[]>("/api/sessions-daily")
+const metrics = useApiQuery<MetricsDaily[]>("/api/metrics-daily")
+
+if (sessions.isPending || metrics.isPending) return <Loading />
+if (sessions.isError) return <ErrorState message={sessions.error.message} />
+if (metrics.isError) return <ErrorState message={metrics.error.message} />
+// ここから sessions.data: SessionsDaily[] / metrics.data: MetricsDaily[]
+return <Chart sessions={sessions.data} metrics={metrics.data} />
+
+// NG: const failed = [sessions, metrics].find((q) => q.isError) のように配列でまとめて判定すると
+// 各 q.data は narrowing されず、`T[] | undefined` を T[] の props に渡して型エラーになる
+```
+
+カードごとに別々に読み込み中・エラーを出すなら、`data` を渡す側で `q.data ?? []` にするか、
+カードのコンポーネントの中で上と同じ判定をする。
+
 `ApiError` は `message`・`status`・`body`・`requestId` を持つ。hook が使えない場所では
 `apiJson(path, init)`、生の `Response` が要るときは `apiFetch`。

package/base-template/agents/doc.md

@@ -44,6 +44,8 @@ export default function JuneSummary() {
   `useApiQuery` などで読み込むと、開くたびに値が変わります。
 - **チャートは `EChart`(`@squadbase/vantage/components`)を文中に置く。** `figure` で囲めば
   `figcaption` がキャプションになります。
+- **PDF の保存ボタンは作らない。** `<Document>` が右下に PDF 保存のボタンを出し、印刷時は
+  本文だけをライトの配色で出します。
 - **ページ全体を包むのは `<Document>` だけ。** `PageShell` などのダッシュボード用の枠で包まない
   (本文の幅と余白は `<Document>` が決めます)。
 

package/base-template/agents/page.md

@@ -26,8 +26,8 @@
   },
   "dependencies": {
     "@squadbase/vantage": "^0.5.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
   }
 }
 ```

package/base-template/agents/slide.md

@@ -11,6 +11,13 @@
 `src/monthly-report.slide.tsx` → `/monthly-report`。中身は `<SlideDeck>` を返す普通の React
 コンポーネントで、`definePage` もナビも通常のページと同じように効きます。
 
+**ファイル名の決め方:**
+
+- **ルート `/` がすでに他のページ（`index.tsx`など）で使われている場合は、スライドのタイトルから slug を作ってファイル名にする。** `index.slide.tsx` は `index.tsx` と同じ `/` に解決するので `ROUTE_CONFLICT` になる。
+  - 例: "Label check" というスライド → `src/label-check.slide.tsx` → `/label-check`
+  - 例: "Monthly Report" というスライド → `src/monthly-report.slide.tsx` → `/monthly-report`
+- 新規プロジェクトでまだ `/` が空いている場合のみ、`index.slide.tsx` を使ってよい。
+
 ```tsx
 import { Slide, SlideDeck } from "@squadbase/vantage/slide"
 
@@ -34,7 +41,12 @@ export default function Deck() {
 送れ、左のスライド一覧(サムネイル列)は `L` で開閉、`F` で全画面、ツールバーから pptx を
 書き出せます。**書き方の作法は同梱 Skill の
 `vantage-slide`** にあります(キャンバスの縦方向の予算、段階表示、トランジション、モーフ、
-pptx が壊れる条件)。
+pptx が壊れる条件、説明と図表のデータ時点の揃え方)。
+
+**分析を共有するデッキでは、本文・数値・図表を同じ対象期間と同じ取得時点の結果に揃え、その期間と
+時点を短く表示する。** 説明文を固定したまま図表だけが最新値へ変わる構成にしない(ライブ更新を
+意図するなら本文も同じ取得結果から導く)。同一時点の結果を保持できない場合は、スナップショットとして
+保存できたとは報告せず、必要な保持の仕組みと保証できない範囲を伝える。
 
 `.slide` を付けられるのはルートになるページモジュールだけで、`_layout.slide.tsx` などは
 `INVALID_PAGE_VARIANT` エラーになります。`june.slide.tsx` と `june.tsx` は同じ URL に解決するので