@squadbase/vantage 0.5.3 → 0.6.1-dev.2d25e94

package/templates/agents/csv.md

@@ -0,0 +1,32 @@
+# csv ページ
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`.csv` を
+ページとして置くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
+先に読んでいる想定です。
+
+## `.csv` を置くだけでページになる
+
+**`.csv` を `src/` に置くだけで、他のページと同格のルートになります。** URL の作り方は
+`.tsx` と同じ(`src/sales-export.csv` → `/sales-export`、`index.csv` はそのディレクトリ)で、
+ナビにも `vantage routes` にも並びます。開くとフレームワーク同梱の表ビューアが描き、
+元ファイルをダウンロードできます。ビューアは**表計算ソフトの見た目**です —— 列は A / B / C、
+左に行番号、ファイルの 1 行目はヘッダとして固定。読み取り専用で、編集もソートもできません
+(セルを選んで `Cmd/Ctrl+C` でコピーは可)。
+
+- **タイトルはファイル名から導かれる**(`sales-export.csv` → 「Sales Export」)。データファイルに
+  `definePage` は書けません。名前を変えたいときはファイルをリネームします
+- **ページにしたくないファイルは `_` を前置する**(`_sales-export.csv`)。`components/`・`hooks/`・
+  `lib/` に置いたものも同じくページになりません
+- **既定はファイルをそのまま置く(tsx を書かない)。** 自分でタイトルや説明を付けたいときだけ、`_` を
+  前置してルート化を止め、tsx から描きます:
+  ```tsx
+  import { FilePageView } from "@squadbase/vantage/table"
+  import src from "./_sales-export.csv?url&no-inline"
+  export const page = definePage({ title: "売上エクスポート" })
+  export default () => <FilePageView src={src} kind="csv" fileName="sales-export.csv" />
+  ```
+- 数式・グラフ・セル書式といった概念は csv には無いので、値がそのまま読めます。ブラウザで
+  パースするので 25MB を超えるファイルはそのページにエラーが出ます —— 大きいデータは
+  `server/api/` から配って `DataTable` で描いてください
+- **ビューアの無い拡張子(`.tsv` など)はルートになりません。** `vantage check` の
+  `UNSUPPORTED_PAGE_FILE` 警告が知らせます

package/templates/agents/doc.md

@@ -0,0 +1,73 @@
+# ドキュメント(.doc.tsx)
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`.doc.tsx` で
+ドキュメントを書くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
+先に読んでいる想定です。
+
+## ドキュメントは `.doc.tsx` で書く
+
+`src/june-summary.doc.tsx` → `/june-summary`。上から下へ読む文章のページで、表やチャートを
+文中に置けます。中身は `<Document>` を返す普通の React コンポーネントで、`definePage` もナビも
+通常のページと同じように効きます。
+
+```tsx
+import { definePage } from "@squadbase/vantage"
+import { EChart } from "@squadbase/vantage/components"
+import { Document } from "@squadbase/vantage/doc"
+
+export const page = definePage({ title: "6月度サマリー", navLabel: "6月度サマリー" })
+export default function JuneSummary() {
+  return (
+    <Document>
+      <h1>6月度サマリー</h1>
+      <p>6月の売上は <strong>5,250 万円</strong>で、目標を 5% 上回りました。</p>
+      <h2>週次の売上</h2>
+      <figure>
+        <EChart option={option} height={280} ariaLabel="6月の週次売上" />
+        <figcaption>第4週はキャンペーン初週</figcaption>
+      </figure>
+      <table>…</table>
+    </Document>
+  )
+}
+```
+
+## 書き方
+
+- **素の HTML 要素で書く。** `<Document>` の中の `h1`〜`h4`・`p`・`ul`/`ol`/`li`・`table`・
+  `blockquote`・`pre`/`code`・`hr`・`a`・`figure`/`figcaption`・`img` には、見出しの大きさ・余白・
+  罫線などが最初から当たっています。クラスは要りません。
+- **Tailwind のユーティリティは、その要素だけ見た目を変えたいときに使う。** 要素の既定の
+  スタイルはユーティリティより弱いので、`className` を付ければそちらが勝ちます。ドキュメント全体の
+  見た目を変えたいときはユーティリティを並べず、下の `--doc-*` を変えます。
+- **数値はコードに直接書く。** ドキュメントは書いた時点の内容を残すページです。
+  `useApiQuery` などで読み込むと、開くたびに値が変わります。
+- **チャートは `EChart`(`@squadbase/vantage/components`)を文中に置く。** `figure` で囲めば
+  `figcaption` がキャプションになります。
+- **ページ全体を包むのは `<Document>` だけ。** `PageShell` などのダッシュボード用の枠で包まない
+  (本文の幅と余白は `<Document>` が決めます)。
+
+## 見た目を変える
+
+配色・書体・本文の幅は `--doc-*` の CSS 変数です。既定値はアプリのトークンへの別名なので、
+ダークモードにもそのまま追従します。
+
+| 変数 | 既定値 | 何に効くか |
+| --- | --- | --- |
+| `--doc-fg` | `var(--foreground)` | 本文の文字色 |
+| `--doc-muted` | `var(--muted-foreground)` | 引用・キャプション |
+| `--doc-accent` | `var(--primary)` | リンク |
+| `--doc-border` | `var(--border)` | 表・`h2` の下線・引用・`hr` |
+| `--doc-subtle` | `var(--muted)` | コード・表の見出し行の背景 |
+| `--doc-font-body` / `--doc-font-heading` / `--doc-font-mono` | アプリの書体 | 本文 / 見出し / コード |
+| `--doc-size-body` | `1rem` | 本文の文字サイズ(見出しはこれに比例) |
+| `--doc-line-height` | `1.8` | 本文の行間 |
+| `--doc-max-width` | `48rem` | 本文の幅 |
+
+アプリのすべてのドキュメントに効かせるなら `styles.css` の `:root` で定義し直します。1 つの
+ドキュメントだけなら `<Document theme={{ accent: "#2563eb", maxWidth: "56rem" }}>` のように
+`theme` で渡します(`theme` のキーは変数名から `--doc-` を外してキャメルケースにしたもの)。
+
+`.doc` を付けられるのはルートになるページモジュールだけで、`_layout.doc.tsx` などは
+`INVALID_PAGE_VARIANT` エラーになります。`june.doc.tsx` と `june.tsx` は同じ URL に解決するので
+`ROUTE_CONFLICT` です。

package/templates/agents/page.md

@@ -0,0 +1,187 @@
+# ダッシュボード / 通常ページ(.tsx)
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`.tsx` の通常ページ
+(ダッシュボード)を書くときに読んでください。前提となる不変条件・ディレクトリ構造は
+`AGENTS.md` を先に読んでいる想定です。
+
+プロジェクトルートに `DESIGN.md` があれば、書き始める前に読んで配色・書体・レイアウトの規則に従う。
+
+## 最小アプリ(2 ファイル)
+
+`package.json` と `index.tsx` の 2 ファイルだけで動く。
+
+`package.json`:
+
+```json
+{
+  "name": "my-dashboard",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vantage dev",
+    "build": "vantage build",
+    "preview": "vantage preview",
+    "check": "vantage check",
+    "routes": "vantage routes"
+  },
+  "dependencies": {
+    "@squadbase/vantage": "^0.5.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  }
+}
+```
+
+`index.tsx`(ルートのデフォルトエクスポートが `/` ページになる):
+
+```tsx
+export default function Dashboard() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-semibold">Dashboard</h1>
+    </main>
+  )
+}
+```
+
+```bash
+pnpm install
+pnpm dev      # → http://localhost:5173(HMR)
+pnpm check    # 静的診断(エラーがあれば exit 1)
+pnpm routes   # ページ/API の URL マップ
+```
+
+`server/` ディレクトリが無いので、この構成は **SPA モード**。ページを直下に置く形だが、
+`src/` を作ってその中に集めてもよい(テンプレートから始めた場合は最初から `src/` がある)。
+どちらか一方に寄せること(→ `AGENTS.md` の「ディレクトリ構造」)。
+
+## ルーティング規約(ファイル名 → ルート)
+
+ページルート(`src/` があればその中、無ければプロジェクトルート)からの相対パスが、そのまま
+URL になる。各ページは**デフォルトエクスポートの React コンポーネントが必須**(無いと
+`MISSING_DEFAULT_EXPORT`)。以下の「ファイル」列はページルートからの相対パス。
+
+| ファイル | ルート |
+| --- | --- |
+| `index.tsx` | `/` |
+| `monthly-analysis.tsx` | `/monthly-analysis` |
+| `sales/index.tsx` | `/sales` |
+| `sales/[customerId].tsx` | `/sales/:customerId`(動的パラメータ) |
+| `_layout.tsx` | そのディレクトリ配下を包むネストレイアウト(`Outlet` で子を描く) |
+| `_404.tsx` | Not Found ページ |
+| `_error.tsx` | ルートが throw したときのエラーページ |
+| `monthly-report.slide.tsx` | `/monthly-report`(スライドデッキ。詳しくは `agents/slide.md`) |
+| `sales-export.csv` | `/sales-export`(詳しくは `agents/csv.md`) |
+| `data/june.xlsx` | `/data/june`(詳しくは `agents/xlsx.md`) |
+
+`components/`・`hooks/`・`lib/`・`server/`・`public/` はどの階層でもルート走査の対象外
+(ページにならない)。それ以外のディレクトリ名は URL のセグメントになる(→ `AGENTS.md` の
+「ディレクトリ構造」)。
+
+```tsx
+import { definePage } from "@squadbase/vantage"
+
+// title は document.title、navLabel は useRoutes() で組むナビの表示名(既定は title)
+export const page = definePage({ title: "Monthly Analysis · Acme", navLabel: "Monthly" })
+
+export default function MonthlyAnalysis() {
+  return <main className="p-6">…</main>
+}
+```
+
+### ナビはルート一覧から組む
+
+`useRoutes()` がページルート一覧(スキャン順)を返すので、リンク配列を手で持たない。
+`useCurrentRoute()` は現在のルート(404 なら `undefined`)。
+
+```tsx
+import { Link, useCurrentRoute, useRoutes } from "@squadbase/vantage/router"
+
+// 動的ルートは URL が定まらないので外す。label は navLabel → title → path の順
+const routes = useRoutes().filter((r) => !r.dynamic)
+const current = useCurrentRoute()
+
+routes.map((r) => (
+  <Link key={r.path} to={r.to} activeClassName="font-semibold">
+    {r.label}
+  </Link>
+))
+```
+
+`RouteInfo`: `path`(`/sales/:id`)・`to`(`/sales/$id`)・`params`・`dynamic`・`index`・`label`・
+`title`・`description`・`navLabel`・`kind`(`"module"` | `"file"`)・`variant`(`"slide"`)。
+後ろの 2 つで、ナビをダッシュボード / スライド / データに分けたりアイコンを変えたりできます。
+
+### フィルタ状態は URL に置く
+
+リロードで消えず、URL をそのまま共有できる。`useState` と同じ形。
+
+```tsx
+import { useSearchParam, useSearchState } from "@squadbase/vantage/router"
+
+const [region, setRegion] = useSearchParam("region", "all")   // 常に string
+const [segments, setSegments] = useSearchState<string[]>("segments", []) // JSON になる値
+```
+
+デフォルト値(または `null`)を書くとキーは URL から消える。履歴は既定で `replace`
+(`{ replace: false }` で push)。
+
+### 動的パラメータの「3 つの綴り」を同期させる
+
+崩すと静かにマッチしなくなる不変条件:
+
+- ファイル名 `sales/[customerId].tsx`
+- 表示ルート `/sales/:customerId`
+- リンクトークン `to="/sales/$customerId"` + `params={{ customerId }}`
+
+```tsx
+import { Link, useParams } from "@squadbase/vantage/router"
+
+<Link to="/sales/$customerId" params={{ customerId: row.id }}>{row.name}</Link>
+
+// 詳細ページ側で取り出す
+const { customerId } = useParams()
+```
+
+## データ取得(server を持たない fetch)
+
+外部 API を叩くだけなら `server/` は不要。`@squadbase/vantage/query` の `useQuery` を使う:
+
+```tsx
+import { useQuery } from "@squadbase/vantage/query"
+import { Loading, ErrorState } from "@squadbase/vantage/ui"
+
+const q = useQuery({ queryKey: ["stats"], queryFn: () => fetch("/…").then((r) => r.json()) })
+if (q.isPending) return <Loading />
+if (q.isError) return <ErrorState message={(q.error as Error).message} />
+```
+
+`QueryClient` は Vantage が 1 つだけ管理する(staleTime 30s・retry 1・
+refetchOnWindowFocus false・networkMode "always")。挙動を変えたいときはクエリ側のオプションで
+上書きする。
+自分の `server/api` を叩くときは `useQuery` ではなく `useApiQuery`(→ `agents/api.md`)。
+
+## 組み込み UI / コンポーネントの入口
+
+- **プリミティブ**は `@squadbase/vantage/ui` から import する(`Button`・`Loading`・
+  `ErrorState`・`Empty`・`Select`・`Checkbox` ほか)。
+- **複合パーツ**は `@squadbase/vantage/components` から(`PageShell`・`DashboardCardPreset`・
+  `DataTablePreset`・`EChart` ほか)。
+- **どの名前が import 可能か / props の詳細は `vantage docs` で引く。** ガイドとコンポーネント
+  リファレンスはパッケージに同梱されていて、オフラインでも読める(→ `AGENTS.md` の
+  「ドキュメントを引く」)。**名前が分からないとき**はやりたいことで `vantage search` する
+  (→ 同節)。
+- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui|block` は
+  ソースを手元にコピーして**改造したいとき専用**のコマンドで、取り出せるのは
+  `ui: data-table` と `block: sales-overview` の 2 つだけ。それ以外の名前は import 専用で
+  `add` の対象ではない(未知名で実行すると候補が一覧表示される)。
+
+### ダークモードは opt-in
+
+ダークのトークンが効くのは、祖先に `.dark` か `[data-theme="dark"]` が付いているときだけ。
+**OS / ブラウザの設定(`prefers-color-scheme`)は見ない。** `dark:` ユーティリティも同じ
+スイッチに繋いであるので(`theme.css` の `@custom-variant dark`)、自分でクラスを付けない限り
+アプリは常にライトで描かれる ― `dark:` を書いてもそこだけダークになることはない。
+
+明暗を切り替えたいときは、レイアウトのルート要素などに `.dark` / `data-theme="dark"` を
+自分で付ける。

package/templates/agents/slide.md

@@ -0,0 +1,41 @@
+# スライド(.slide.tsx)
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`.slide.tsx` で
+スライドデッキを書くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
+先に読んでいる想定です。
+
+プロジェクトルートに `DESIGN.md` があれば、書き始める前に読んで「スライド」の節と配色・書体の規則に従う。
+
+## スライドは `.slide.tsx` で書く
+
+`src/monthly-report.slide.tsx` → `/monthly-report`。中身は `<SlideDeck>` を返す普通の React
+コンポーネントで、`definePage` もナビも通常のページと同じように効きます。
+
+```tsx
+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>
+  )
+}
+```
+
+**`<Slide>` は `<SlideDeck>` の直接の子に書く。** `SlideDeck` は直下の `<Slide>` 要素だけを数えるので、
+`<Slide>` を自作コンポーネント(`<Slide1 />` など)や Fragment で包むと 1 枚も数えられず「1 / 0」に
+なります(`{items.map((x) => <Slide key={x.id}>…</Slide>)}` のような配列は可)。共通の部品は
+`<Slide>` の**中**に置くコンポーネントとして切り出します(`<Slide><CoverPage /></Slide>`)。
+
+1920×1080 の固定キャンバスに絶対 px で書き、画面サイズに合わせて縮小されます。キー / クリックで
+送れ、左のスライド一覧(サムネイル列)は `L` で開閉、`F` で全画面、ツールバーから pptx を
+書き出せます。**書き方の作法は同梱 Skill の
+`vantage-slide`** にあります(キャンバスの縦方向の予算、段階表示、トランジション、モーフ、
+pptx が壊れる条件)。
+
+`.slide` を付けられるのはルートになるページモジュールだけで、`_layout.slide.tsx` などは
+`INVALID_PAGE_VARIANT` エラーになります。`june.slide.tsx` と `june.tsx` は同じ URL に解決するので
+`ROUTE_CONFLICT` です。

package/templates/agents/xlsx.md

@@ -0,0 +1,33 @@
+# xlsx ページ
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`.xlsx` を
+ページとして置くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
+先に読んでいる想定です。
+
+## `.xlsx` を置くだけでページになる
+
+**`.xlsx` を `src/` に置くだけで、他のページと同格のルートになります。** URL の作り方は
+`.tsx` と同じ(`src/data/june.xlsx` → `/data/june`、`index.xlsx` はそのディレクトリ)で、
+ナビにも `vantage routes` にも並びます。開くとフレームワーク同梱の表ビューアが描き、複数シートを
+切り替えられ、元ファイルをダウンロードできます。ビューアは**表計算ソフトの見た目**です ——
+列は A / B / C、左に行番号、ファイルの 1 行目はヘッダとして固定、シートのタブは下端。
+読み取り専用で、編集もソートもできません(セルを選んで `Cmd/Ctrl+C` でコピーは可)。
+
+- **タイトルはファイル名から導かれる**(`june.xlsx` → 「June」)。データファイルに `definePage` は
+  書けません。名前を変えたいときはファイルをリネームします
+- **ページにしたくないファイルは `_` を前置する**(`_june.xlsx`)。`components/`・`hooks/`・`lib/` に
+  置いたものも同じくページになりません
+- **既定はファイルをそのまま置く(tsx を書かない)。** 自分でタイトルや説明を付けたいときだけ、`_` を
+  前置してルート化を止め、tsx から描きます:
+  ```tsx
+  import { FilePageView } from "@squadbase/vantage/table"
+  import src from "./_june.xlsx?url&no-inline"
+  export const page = definePage({ title: "6月度 売上レポート" })
+  export default () => <FilePageView src={src} kind="xlsx" fileName="june.xlsx" />
+  ```
+- **複数シートに対応**しています。シートのタブは下端に並び、切り替えて閲覧できます。
+- 数式・グラフ・セル書式は再現されません(値として読めれば十分、という設計)。ブラウザでパースするので
+  25MB を超えるファイルはそのページにエラーが出ます —— 大きいデータは `server/api/` から配って
+  `DataTable` で描いてください
+- **ビューアの無い拡張子(`.xls`・`.ods` など)はルートになりません。** `vantage check` の
+  `UNSUPPORTED_PAGE_FILE` 警告が知らせます

package/theme.css

@@ -53,6 +53,46 @@
   --sidebar-accent-foreground: oklch(0.205 0 0);
   --sidebar-border: oklch(0.922 0 0);
   --sidebar-ring: oklch(0.708 0 0);
+
+  /* Slides (@squadbase/vantage/slide).
+     These are aliases, not values. Custom properties resolve lazily, so
+     pointing them at the tokens above is enough for a deck to follow `.dark`
+     and `[data-theme="dark"]` on its own — restating them in the dark block
+     below would create two places to keep in step for no gain. A deck
+     overrides any of them inline through `<SlideDeck theme>`. */
+  --slide-bg: var(--background);
+  --slide-fg: var(--foreground);
+  --slide-accent: var(--primary);
+  --slide-muted: var(--muted-foreground);
+  --slide-radius: var(--radius);
+  /* A system stack that includes Japanese. The pptx export rasterises through
+     an SVG `foreignObject`, where locally installed families resolve by name
+     but webfonts must be inlined — so a system default is what makes the
+     common path export correctly with nothing embedded. */
+  --slide-font-display:
+    system-ui, -apple-system, "Hiragino Kaku Gothic ProN", "Hiragino Sans", "Yu Gothic", Meiryo,
+    sans-serif;
+  --slide-font-body: var(--slide-font-display);
+  /* Canvas pixels, on the 1920x1080 canvas — not rem: a slide is scaled as a
+     whole, so its type must not also follow the browser's root font size. */
+  --slide-size-hero: 168px;
+  --slide-size-body: 36px;
+
+  /* Documents (@squadbase/vantage/doc). Aliases, like --slide-*: they follow
+     `.dark` through the tokens they point at, so they are not restated in the
+     dark block. A document overrides any of them inline through
+     `<Document theme>`, an app through its styles.css. */
+  --doc-fg: var(--foreground);
+  --doc-muted: var(--muted-foreground);
+  --doc-accent: var(--primary);
+  --doc-border: var(--border);
+  --doc-subtle: var(--muted);
+  --doc-font-body: inherit;
+  --doc-font-heading: var(--doc-font-body);
+  --doc-font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --doc-size-body: 1rem;
+  --doc-line-height: 1.8;
+  --doc-max-width: 48rem;
 }
 
 .dark,
@@ -128,6 +168,10 @@
   --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-ring: var(--sidebar-ring);
+  --color-slide-bg: var(--slide-bg);
+  --color-slide-fg: var(--slide-fg);
+  --color-slide-accent: var(--slide-accent);
+  --color-slide-muted: var(--slide-muted);
   --radius-sm: calc(var(--radius) - 4px);
   --radius-md: calc(var(--radius) - 2px);
   --radius-lg: var(--radius);
@@ -228,6 +272,131 @@
   }
 }
 
+/* ------------------------------------------------------------ documents */
+
+/* Typesetting for `<Document>`. Plain elements inside it need no classes.
+   The rules sit in the components layer and select through `:where()`, so any
+   Tailwind utility on an element inside a document still wins. */
+@layer components {
+  :where([data-slot="document"]) {
+    max-width: var(--doc-max-width);
+    margin-inline: auto;
+    color: var(--doc-fg);
+    font-family: var(--doc-font-body);
+    font-size: var(--doc-size-body);
+    line-height: var(--doc-line-height);
+    overflow-wrap: break-word;
+  }
+  :where([data-slot="document"]) :where(h1, h2, h3, h4) {
+    font-family: var(--doc-font-heading);
+    font-weight: 700;
+    line-height: 1.35;
+    letter-spacing: -0.01em;
+  }
+  :where([data-slot="document"]) :where(h1) {
+    font-size: 2em;
+    margin-block: 0 0.8em;
+  }
+  :where([data-slot="document"]) :where(h2) {
+    font-size: 1.5em;
+    margin-block: 2em 0.75em;
+    padding-bottom: 0.3em;
+    border-bottom: 1px solid var(--doc-border);
+  }
+  :where([data-slot="document"]) :where(h3) {
+    font-size: 1.25em;
+    margin-block: 1.6em 0.6em;
+  }
+  :where([data-slot="document"]) :where(h4) {
+    font-size: 1em;
+    margin-block: 1.4em 0.5em;
+  }
+  :where([data-slot="document"]) :where(p, ul, ol, blockquote, pre, table, figure) {
+    margin-block: 0 1.25em;
+  }
+  :where([data-slot="document"]) :where(ul, ol) {
+    padding-left: 1.5em;
+  }
+  :where([data-slot="document"]) :where(ul) {
+    list-style: disc;
+  }
+  :where([data-slot="document"]) :where(ol) {
+    list-style: decimal;
+  }
+  :where([data-slot="document"]) :where(li) {
+    margin-block: 0.25em;
+  }
+  :where([data-slot="document"]) :where(li > ul, li > ol) {
+    margin-block: 0.25em 0;
+  }
+  :where([data-slot="document"]) :where(a) {
+    color: var(--doc-accent);
+    text-decoration: underline;
+    text-underline-offset: 0.2em;
+  }
+  :where([data-slot="document"]) :where(strong) {
+    font-weight: 700;
+  }
+  :where([data-slot="document"]) :where(blockquote) {
+    padding-left: 1em;
+    border-left: 3px solid var(--doc-border);
+    color: var(--doc-muted);
+  }
+  :where([data-slot="document"]) :where(hr) {
+    margin-block: 2em;
+    border: 0;
+    border-top: 1px solid var(--doc-border);
+  }
+  :where([data-slot="document"]) :where(code) {
+    font-family: var(--doc-font-mono);
+    font-size: 0.875em;
+    padding: 0.15em 0.35em;
+    border-radius: calc(var(--radius) - 4px);
+    background: var(--doc-subtle);
+  }
+  :where([data-slot="document"]) :where(pre) {
+    padding: 1em;
+    overflow-x: auto;
+    border-radius: var(--radius);
+    background: var(--doc-subtle);
+    line-height: 1.6;
+  }
+  :where([data-slot="document"]) :where(pre code) {
+    padding: 0;
+    background: none;
+  }
+  :where([data-slot="document"]) :where(table) {
+    display: block;
+    max-width: 100%;
+    overflow-x: auto;
+    border-collapse: collapse;
+    font-size: 0.9375em;
+    font-variant-numeric: tabular-nums;
+  }
+  :where([data-slot="document"]) :where(th, td) {
+    padding: 0.5em 0.9em;
+    border: 1px solid var(--doc-border);
+    text-align: left;
+  }
+  :where([data-slot="document"]) :where(th) {
+    font-weight: 600;
+    background: var(--doc-subtle);
+  }
+  :where([data-slot="document"]) :where(img, video) {
+    max-width: 100%;
+    height: auto;
+  }
+  :where([data-slot="document"]) :where(figcaption) {
+    margin-top: 0.5em;
+    color: var(--doc-muted);
+    font-size: 0.875em;
+    text-align: center;
+  }
+  :where([data-slot="document"]) > :where(:first-child) {
+    margin-top: 0;
+  }
+}
+
 /* ------------------------------------------------------------ utilities */
 
 @utility no-scrollbar {

package/dist/add-PPCBMWEN.js

@@ -1,6 +0,0 @@
-export { add, syncAgentsFile } from './chunk-X44ZTKID.js';
-import './chunk-D4Y5RWJA.js';
-import './chunk-HQDEYCDP.js';
-import './chunk-C4MQRWXS.js';
-//# sourceMappingURL=add-PPCBMWEN.js.map
-//# sourceMappingURL=add-PPCBMWEN.js.map

package/dist/add-PPCBMWEN.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"add-PPCBMWEN.js"}

package/dist/chunk-BAM33YZ6.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/source.ts","../src/core/route-spec.ts"],"names":[],"mappings":"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","file":"chunk-BAM33YZ6.js","sourcesContent":["/**\n * Low-level source scanning helpers shared by the static analyzers\n * (`diagnostics.ts`, `route-spec.ts`). Everything here is text-only — user code\n * is never imported or executed.\n */\n\n/**\n * Strip block and line comments so commented-out code doesn't produce false\n * positives (or hide real issues). Naive but adequate for presence checks:\n * URLs (`http://`) are preserved via the `[^:]` guard before `//`.\n */\nexport function stripComments(src: string): string {\n  return src.replace(/\\/\\*[\\s\\S]*?\\*\\//g, \"\").replace(/(^|[^:\"'`\\\\])\\/\\/[^\\n]*/g, \"$1\")\n}\n\nconst OPENERS: Record<string, string> = { \"(\": \")\", \"[\": \"]\", \"{\": \"}\" }\n\n/**\n * Read a balanced bracketed region starting at `openIndex` (which must hold\n * `(`, `[` or `{`), returning the raw text *between* the brackets. Quote- and\n * nesting-aware so brackets inside string literals don't unbalance the scan.\n * Returns null when the region is never closed.\n */\nexport function readBracketBody(src: string, openIndex: number): string | null {\n  const open = src[openIndex]\n  if (!open || !OPENERS[open]) return null\n  let depth = 0\n  let quote: string | null = null\n  for (let i = openIndex; i < src.length; i++) {\n    const c = src[i]!\n    if (quote) {\n      if (c === \"\\\\\") i++\n      else if (c === quote) quote = null\n      continue\n    }\n    if (c === '\"' || c === \"'\" || c === \"`\") {\n      quote = c\n      continue\n    }\n    if (OPENERS[c]) depth++\n    else if (c === \")\" || c === \"]\" || c === \"}\") {\n      if (--depth === 0) return src.slice(openIndex + 1, i)\n    }\n  }\n  return null\n}\n\n/**\n * Split an argument list or object body on top-level commas, ignoring commas\n * nested inside brackets or string literals. Empty parts are dropped.\n */\nexport function splitTopLevel(body: string): string[] {\n  const parts: string[] = []\n  let depth = 0\n  let quote: string | null = null\n  let start = 0\n  for (let i = 0; i < body.length; i++) {\n    const c = body[i]!\n    if (quote) {\n      if (c === \"\\\\\") i++\n      else if (c === quote) quote = null\n      continue\n    }\n    if (c === '\"' || c === \"'\" || c === \"`\") {\n      quote = c\n      continue\n    }\n    if (OPENERS[c]) depth++\n    else if (c === \")\" || c === \"]\" || c === \"}\") depth--\n    else if (c === \",\" && depth === 0) {\n      parts.push(body.slice(start, i))\n      start = i + 1\n    }\n  }\n  parts.push(body.slice(start))\n  return parts.map((p) => p.trim()).filter(Boolean)\n}\n","import fs from \"node:fs\"\nimport { API_METHODS, type ApiMethod } from \"./constants\"\nimport { extractPageMeta } from \"./route-tree\"\nimport { readBracketBody, splitTopLevel, stripComments } from \"./source\"\nimport type { ApiRoute, PageRoute, Segment } from \"./types\"\n\n/**\n * Best-effort *static* specs for the routes `vantage routes --detail` prints:\n * what a page takes in its path, and what an API route accepts and answers\n * with. Like `diagnostics.ts` this only reads text — user modules are never\n * imported or executed — so every field is a hint derived from the source, not\n * a guarantee. Callers pass sources through {@link stripComments} first.\n */\n\n/** A dynamic segment of a route path. */\nexport interface RouteParam {\n  name: string\n  kind: \"param\" | \"catchall\"\n}\n\n/** Static spec of a page route. */\nexport interface PageSpec {\n  params: RouteParam[]\n  title?: string\n  description?: string\n  navLabel?: string\n}\n\n/** The request body an API handler reads, when detectable. */\nexport interface ApiBodySpec {\n  format: \"json\" | \"formData\" | \"text\" | \"binary\"\n  /** Top-level keys, when the handler destructures them. */\n  keys?: string[]\n}\n\n/** A response an API handler returns. */\nexport interface ApiResponseSpec {\n  status: number\n  /** Response content type, omitted when it can't be derived. */\n  contentType?: string\n  /** Top-level keys, when the payload is an object literal. */\n  keys?: string[]\n}\n\n/** An `HttpError` an API handler throws. */\nexport interface ApiErrorSpec {\n  status: number\n  message?: string\n}\n\n/** Static spec of one HTTP method handler. */\nexport interface ApiMethodSpec {\n  method: ApiMethod\n  /** Query string keys read via `searchParams`. */\n  query: string[]\n  body?: ApiBodySpec\n  responses: ApiResponseSpec[]\n  errors: ApiErrorSpec[]\n}\n\n/** Static spec of an API route module. */\nexport interface ApiSpec {\n  params: RouteParam[]\n  methods: ApiMethodSpec[]\n}\n\n/**\n * HTTP method handlers a module exports (direct declaration or export list).\n * `src` must be comment-stripped. Shared with the `INVALID_API_EXPORT`\n * diagnostic so both agree on what counts as a handler.\n */\nexport function detectApiMethods(src: string): ApiMethod[] {\n  return API_METHODS.filter(\n    (m) =>\n      new RegExp(`export\\\\s+(async\\\\s+)?(function|const|let|var)\\\\s+${m}\\\\b`).test(src) ||\n      new RegExp(`export\\\\s*\\\\{[^}]*\\\\b${m}\\\\b[^}]*\\\\}`).test(src),\n  )\n}\n\n/**\n * Slice the module into one source region per handler: from a handler's export\n * declaration to the next one (or EOF). Coarse on purpose — matching a function\n * body would have to cope with arrow bodies, overloads and trailing helpers —\n * and good enough because handlers are written one after another. A method\n * exported only through an export list gets the whole module as its region.\n */\nfunction methodRegions(src: string): Map<ApiMethod, string> {\n  const re = new RegExp(\n    `export\\\\s+(?:async\\\\s+)?(?:function|const|let|var)\\\\s+(${API_METHODS.join(\"|\")})\\\\b`,\n    \"g\",\n  )\n  const decls: { method: ApiMethod; index: number }[] = []\n  let m: RegExpExecArray | null\n  while ((m = re.exec(src))) decls.push({ method: m[1] as ApiMethod, index: m.index })\n\n  const regions = new Map<ApiMethod, string>()\n  decls.forEach((d, i) => {\n    regions.set(d.method, src.slice(d.index, decls[i + 1]?.index ?? src.length))\n  })\n  for (const method of detectApiMethods(src)) {\n    if (!regions.has(method)) regions.set(method, src)\n  }\n  return regions\n}\n\n/** Top-level keys of an object literal expression, `…` standing in for spreads. */\nfunction objectKeys(expr: string): string[] | undefined {\n  const trimmed = expr.trim()\n  if (!trimmed.startsWith(\"{\")) return undefined\n  const body = readBracketBody(trimmed, 0)\n  if (body == null) return undefined\n  const keys: string[] = []\n  for (const part of splitTopLevel(body)) {\n    if (part.startsWith(\"...\")) {\n      keys.push(\"…\")\n      continue\n    }\n    const name = part.match(/^[\"'`]?([A-Za-z0-9_$]+)/)\n    if (name) keys.push(name[1]!)\n  }\n  return keys.length ? keys : undefined\n}\n\n/** Read `status: 201` out of a `ResponseInit` literal. */\nfunction initStatus(init: string | undefined): number | undefined {\n  const m = init?.match(/\\bstatus\\s*:\\s*(\\d{3})\\b/)\n  return m ? Number(m[1]) : undefined\n}\n\n/** Read a content-type header out of a `ResponseInit` literal. */\nfunction initContentType(init: string | undefined): string | undefined {\n  const m = init?.match(/[\"']?content-type[\"']?\\s*:\\s*[\"']([^\"';]+)/i)\n  return m ? m[1]!.trim() : undefined\n}\n\n/** Every `Response.json(…)` / `json(…)` / `new Response(…)` in a handler region. */\nfunction extractResponses(region: string): ApiResponseSpec[] {\n  const re = /\\bnew\\s+Response\\s*\\(|\\bResponse\\s*\\.\\s*json\\s*\\(|(?<![.\\w$])json\\s*\\(/g\n  const out: ApiResponseSpec[] = []\n  const seen = new Set<string>()\n  let m: RegExpExecArray | null\n  while ((m = re.exec(region))) {\n    const isJson = !m[0].startsWith(\"new\")\n    const args = readBracketBody(region, m.index + m[0].length - 1)\n    if (args == null) continue\n    const [payload, init] = splitTopLevel(args)\n    const contentType = isJson\n      ? \"application/json\"\n      : (initContentType(init) ??\n        (payload?.startsWith(\"JSON.stringify\") ? \"application/json\" : undefined))\n    const keys = isJson && payload ? objectKeys(payload) : undefined\n    const spec: ApiResponseSpec = {\n      status: initStatus(init) ?? 200,\n      ...(contentType ? { contentType } : {}),\n      ...(keys ? { keys } : {}),\n    }\n    const key = JSON.stringify(spec)\n    if (seen.has(key)) continue\n    seen.add(key)\n    out.push(spec)\n  }\n  return out\n}\n\n/** Every `new HttpError(status, \"message\")` in a handler region. */\nfunction extractErrors(region: string): ApiErrorSpec[] {\n  const re = /\\bHttpError\\s*\\(\\s*(\\d{3})\\s*(?:,\\s*(?:([\"'`])((?:\\\\.|(?!\\2)[\\s\\S])*)\\2))?/g\n  const out: ApiErrorSpec[] = []\n  const seen = new Set<string>()\n  let m: RegExpExecArray | null\n  while ((m = re.exec(region))) {\n    const message = m[3]?.replace(/\\\\(.)/g, \"$1\")\n    const spec: ApiErrorSpec = { status: Number(m[1]), ...(message ? { message } : {}) }\n    const key = JSON.stringify(spec)\n    if (seen.has(key)) continue\n    seen.add(key)\n    out.push(spec)\n  }\n  return out\n}\n\n/** Query keys read through `searchParams.get/getAll/has(\"x\")`. */\nfunction extractQuery(region: string): string[] {\n  const re = /searchParams\\s*\\.\\s*(?:get|getAll|has)\\s*\\(\\s*[\"'`]([^\"'`]+)[\"'`]/g\n  const out = new Set<string>()\n  let m: RegExpExecArray | null\n  while ((m = re.exec(region))) out.add(m[1]!)\n  return [...out]\n}\n\n/** The request body a handler reads, plus destructured keys when present. */\nfunction extractBody(region: string): ApiBodySpec | undefined {\n  const read = region.match(/\\b(?:request|req)\\s*\\.\\s*(json|formData|text|arrayBuffer|blob)\\s*\\(/)\n  if (!read) return undefined\n  const method = read[1]!\n  const format: ApiBodySpec[\"format\"] =\n    method === \"json\" || method === \"formData\" || method === \"text\" ? method : \"binary\"\n\n  const destructured = region.match(\n    /(?:const|let|var)\\s*(\\{[\\s\\S]*?\\})\\s*=\\s*(?:await\\s+)?[\\w.]*\\.json\\s*\\(/,\n  )\n  const keys = format === \"json\" && destructured ? objectKeys(destructured[1]!) : undefined\n  return { format, ...(keys ? { keys } : {}) }\n}\n\nfunction toParams(segments: Segment[]): RouteParam[] {\n  const out: RouteParam[] = []\n  for (const s of segments) {\n    if (s.kind === \"static\") continue\n    out.push({ name: s.name, kind: s.kind })\n  }\n  return out\n}\n\n/** Static spec of a page: its path params and its `definePage` metadata. */\nexport function extractPageSpec(page: PageRoute): PageSpec {\n  return { params: toParams(page.segments), ...extractPageMeta(page.absFile) }\n}\n\n/** Static spec of an API route: path params and a per-method request/response sketch. */\nexport function extractApiSpec(api: ApiRoute): ApiSpec {\n  const params = toParams(api.segments)\n  let src: string\n  try {\n    src = stripComments(fs.readFileSync(api.absFile, \"utf8\"))\n  } catch {\n    return { params, methods: [] }\n  }\n  const regions = methodRegions(src)\n  const methods = API_METHODS.filter((m) => regions.has(m)).map((method) => {\n    const region = regions.get(method)!\n    const body = extractBody(region)\n    return {\n      method,\n      query: extractQuery(region),\n      ...(body ? { body } : {}),\n      responses: extractResponses(region),\n      errors: extractErrors(region),\n    }\n  })\n  return { params, methods }\n}\n"]}

package/dist/chunk-C4MQRWXS.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/constants.ts"],"names":[],"mappings":";;;AAMO,IAAM,WAAA,GAAc;AASpB,IAAM,OAAA,GAAU;AAGhB,IAAM,cAAA,uBAAqB,GAAA,CAAI;AAAA,EACpC,YAAA;AAAA,EACA,OAAA;AAAA,EACA,KAAA;AAAA,EACA,QAAA;AAAA,EACA,QAAA;AAAA,EACA,cAAA;AAAA,EACA,WAAA;AAAA,EACA;AACF,CAAC;AASM,IAAM,qBAAA,uBAA4B,GAAA,CAAI;AAAA,EAC3C,OAAA;AAAA,EACA,KAAA;AAAA,EACA,OAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,YAAA;AAAA,EACA,SAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA,QAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA,QAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,WAAA;AAAA,EACA,KAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAC;AAGM,IAAM,eAAA,GAAkB,CAAC,MAAA,EAAQ,MAAM;AAGvC,IAAM,cAAA,GAAiB,CAAC,KAAA,EAAO,MAAA,EAAQ,KAAK;AAG5C,IAAM,mBAAA,GAAsB;AAAA,EACjC,MAAA,EAAQ,SAAA;AAAA,EACR,QAAA,EAAU,MAAA;AAAA,EACV,KAAA,EAAO;AACT;AAGO,IAAM,cAAc,CAAC,KAAA,EAAO,QAAQ,KAAA,EAAO,OAAA,EAAS,UAAU,SAAS;AAOvE,IAAM,eAAA,GAAwE;AAAA,EACnF;AAAA,IACE,OAAA,EAAS,yCAAA;AAAA,IACT,KAAA,EAAO,aAAA;AAAA,IACP,MAAA,EAAQ;AAAA,GACV;AAAA,EACA;AAAA,IACE,OAAA,EAAS,qCAAA;AAAA,IACT,KAAA,EAAO,iBAAA;AAAA,IACP,MAAA,EAAQ;AAAA,GACV;AAAA,EACA;AAAA,IACE,OAAA,EAAS,oCAAA;AAAA,IACT,KAAA,EAAO,gBAAA;AAAA,IACP,MAAA,EAAQ;AAAA,GACV;AAAA,EACA;AAAA,IACE,OAAA,EAAS,oBAAA;AAAA,IACT,KAAA,EAAO,wBAAA;AAAA,IACP,MAAA,EAAQ;AAAA,GACV;AAAA,EACA;AAAA,IACE,OAAA,EAAS,oCAAA;AAAA,IACT,KAAA,EAAO,gBAAA;AAAA,IACP,MAAA,EAAQ;AAAA;AAEZ;AAGO,IAAM,iBAAA,GAAoB;AAG1B,IAAM,uBAAA,GAA0B","file":"chunk-C4MQRWXS.js","sourcesContent":["/**\n * Framework-wide constants: naming conventions and reserved paths.\n * These encode the \"convention over configuration\" contract from the design.\n */\n\n/** Directory that holds all generated, hidden artifacts. */\nexport const VANTAGE_DIR = \".vantage\"\n\n/**\n * Optional directory holding the app's client source. When it exists, it is the\n * one and only page-scan root; when it does not, pages live at the project root.\n * Both layouts are supported so a single-file app stays a single file, while an\n * app (or a coding agent) that reaches for the near-universal `src/` convention\n * gets routes that make sense instead of a `/src/...` prefix on every page.\n */\nexport const SRC_DIR = \"src\"\n\n/** Directories that are never scanned for pages. */\nexport const NON_ROUTE_DIRS = new Set([\n  \"components\",\n  \"hooks\",\n  \"lib\",\n  \"server\",\n  \"public\",\n  \"node_modules\",\n  VANTAGE_DIR,\n  \"dist\",\n])\n\n/**\n * Directory names that almost always mean \"framework scaffolding\", not \"a URL\n * segment\". Page scanning is a denylist (`NON_ROUTE_DIRS`), so any directory\n * not on it becomes part of the route path — `pages/sales.tsx` silently serves\n * `/pages/sales`. These names are still scanned (they may be deliberate), but\n * routes coming out of them raise `SUSPICIOUS_ROUTE_DIR`.\n */\nexport const SUSPICIOUS_ROUTE_DIRS = new Set([\n  SRC_DIR,\n  \"app\",\n  \"pages\",\n  \"routes\",\n  \"views\",\n  \"screens\",\n  \"features\",\n  \"containers\",\n  \"modules\",\n  \"layouts\",\n  \"utils\",\n  \"types\",\n  \"styles\",\n  \"assets\",\n  \"store\",\n  \"stores\",\n  \"context\",\n  \"contexts\",\n  \"providers\",\n  \"api\",\n  \"test\",\n  \"tests\",\n  \"__tests__\",\n])\n\n/** File extensions treated as page modules. */\nexport const PAGE_EXTENSIONS = [\".tsx\", \".jsx\"]\n\n/** File extensions treated as server API modules. */\nexport const API_EXTENSIONS = [\".ts\", \".tsx\", \".js\"]\n\n/** Reserved page filenames (without extension). */\nexport const RESERVED_PAGE_NAMES = {\n  layout: \"_layout\",\n  notFound: \"_404\",\n  error: \"_error\",\n} as const\n\n/** HTTP methods that an API module may export. */\nexport const API_METHODS = [\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\", \"OPTIONS\"] as const\nexport type ApiMethod = (typeof API_METHODS)[number]\n\n/**\n * Files that must not exist in a Vantage project. Their presence means the\n * user is trying to escape the managed stack, which v1 forbids.\n */\nexport const FORBIDDEN_FILES: { pattern: RegExp; label: string; remedy: string }[] = [\n  {\n    pattern: /^vite\\.config\\.(ts|js|mjs|cjs|mts|cts)$/,\n    label: \"Vite config\",\n    remedy: \"Vantage owns the Vite configuration. Remove this file.\",\n  },\n  {\n    pattern: /^tailwind\\.config\\.(ts|js|mjs|cjs)$/,\n    label: \"Tailwind config\",\n    remedy: \"Customize theme tokens in styles.css instead.\",\n  },\n  {\n    pattern: /^postcss\\.config\\.(ts|js|mjs|cjs)$/,\n    label: \"PostCSS config\",\n    remedy: \"Vantage manages PostCSS/Tailwind. Remove this file.\",\n  },\n  {\n    pattern: /^components\\.json$/,\n    label: \"shadcn components.json\",\n    remedy: \"Use `vantage add ui <name>` to copy UI source instead.\",\n  },\n  {\n    pattern: /^vantage\\.config\\.(ts|js|mjs|cjs)$/,\n    label: \"Vantage config\",\n    remedy: \"v1 has no vantage.config. Configuration lives in file conventions.\",\n  },\n]\n\n/** Public env var prefix exposed to the client bundle. */\nexport const PUBLIC_ENV_PREFIX = \"PUBLIC_\"\n\n/** Manifest schema version emitted into build output. */\nexport const MANIFEST_SCHEMA_VERSION = 1\n"]}