@squadbase/vantage 0.2.3 → 0.3.1

package/docs/ja/components.md

@@ -208,8 +208,9 @@ export default function Overview() {
 
 ## テーマ
 
-見た目は CSS 変数（デザイントークン）で決まります。色や角丸を変えたいときは、プロジェクトルートの
-`styles.css` で変数だけを上書きします — 詳しくは [UI とテーマ](ui-and-theming) を参照してください。
+見た目は CSS 変数（デザイントークン）で決まります。色や角丸を変えたいときは、ページと同じ側に置いた
+`styles.css`（`src/` があれば `src/styles.css`）で変数だけを上書きします — 詳しくは
+[UI とテーマ](ui-and-theming) を参照してください。
 
 ## ソースを編集したいとき
 

package/docs/ja/getting-started.md

@@ -20,7 +20,9 @@ pnpm add @squadbase/vantage
 ### index.tsx を書く
 
 プロジェクトルートに `index.tsx` を 1 つ置きます。**default export されたコンポーネント**が
-ルート `/` になります。
+ルート `/` になります。ページを `src/` にまとめたい場合は `src/index.tsx` にします ―
+**`src/` があるとページ走査はその中だけ**になり、`src/` は URL に現れません
+（→ [ページを置く場所](routing)）。
 
 ```tsx
 // index.tsx
@@ -67,8 +69,9 @@ React Fast Refresh がその場で反映します。
 エントリファイルをそのまま指すだけで `dev` が立ち上がります。
 
 ```bash
-vantage ./demo             # フォルダ → その中で dev を起動
-vantage ./demo/index.tsx   # ページファイル → 親フォルダを root にして dev
+vantage ./demo                 # フォルダ → その中で dev を起動
+vantage ./demo/index.tsx       # ページファイル → その `package.json` があるフォルダで dev
+vantage ./demo/src/index.tsx   # src/ レイアウトでも同じ（root は ./demo）
 ```
 
 第 1 引数が既知コマンドでなくパスを指すとき、Vantage はそれを root として `dev` を起動します

package/docs/ja/routing.md

@@ -4,8 +4,27 @@
 
 Vantage のルーティングは **ファイルの配置がそのまま URL** になります。ルーターの設定は書きません。
 
+## ページを置く場所
+
+置き場所は 2 通りあり、**`src/` があるかどうか**だけで決まります。設定ではなく検出です。
+
+| プロジェクト | ページ走査のルート | `/` になるファイル |
+|---|---|---|
+| `src/` がある | `src/` の中だけ | `src/index.tsx` |
+| `src/` が無い | プロジェクトルート直下 | `index.tsx` |
+
+`src/` 自体は URL に現れません（`src/sales/index.tsx` → `/sales`）。1 ファイルのアプリはそのまま
+直下に置け、育ったら `src/` を作ってまとめて移せます。
+
+> [!WARNING]
+> **2 つを混ぜることはできません。** `src/` があるとルート直下の `.tsx` は走査されず、
+> `vantage check` が `SRC_DIR_SPLIT` エラーで指摘します。`server/` と `public/` は常にプロジェクト
+> ルート直下（`src/server/` はスキャンされません）、`styles.css` はページと同じ側に置きます。
+
 ## ページの規約
 
+以下の「ファイル」列は、上のページ走査ルートからの相対パスです。
+
 | ファイル | ルート |
 |---|---|
 | `index.tsx` | `/` |
@@ -23,7 +42,7 @@ Vantage のルーティングは **ファイルの配置がそのまま URL**
 
 ## ルーティングされないディレクトリ
 
-次のディレクトリは決して走査されません。ここには自由にコードを置けます。
+次のディレクトリは（どの階層でも）決して走査されません。ここには自由にコードを置けます。
 
 ```text
 components/   再利用する React コンポーネント
@@ -33,6 +52,12 @@ server/       API（存在するとサーバーが有効になる）
 public/       静的アセット
 ```
 
+> [!WARNING]
+> **それ以外のディレクトリ名は URL のセグメントになります。** `pages/report.tsx` は
+> `/pages/report` に、`utils/format.tsx` は `/utils/format` になります。`pages/`・`app/`・
+> `utils/` のような足場ディレクトリからルートが生まれると `vantage check` が
+> `SUSPICIOUS_ROUTE_DIR` 警告を出すので、ページでないモジュールは上の 3 つに移してください。
+
 ## 動的パラメータの 3 つの綴り
 
 同じパラメータが、場所によって 3 つの綴りで現れます。**必ず一致させます。**

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

@@ -53,8 +53,10 @@ import { cn } from "@squadbase/vantage/ui";
 
 ## テーマトークンを上書きする
 
-色や角丸などのデザイントークンは CSS 変数です。上書きしたいときは、プロジェクトルートに
-`styles.css` を置き、**CSS 変数だけ**を上書きします。このファイルはテーマの後に自動 import されます。
+色や角丸などのデザイントークンは CSS 変数です。上書きしたいときは、**ページと同じ側**に
+`styles.css` を置き、**CSS 変数だけ**を上書きします ― `src/` があれば `src/styles.css`、
+無ければプロジェクトルート直下（→ [ページを置く場所](routing)）。このファイルはテーマの後に
+自動 import されます。
 
 ```css
 /* styles.css — CSS 変数の上書きのみ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",
@@ -86,11 +86,14 @@
     "templates"
   ],
   "scripts": {
-    "build": "node scripts/build-docs.mjs && tsup",
+    "build": "node scripts/build-docs.mjs && node scripts/build.mjs",
+    "build:js": "tsup --no-dts",
+    "build:types": "tsup --dts-only",
     "build:docs": "node scripts/build-docs.mjs",
-    "dev": "tsup --watch",
+    "dev": "tsup --watch --no-dts",
+    "dev:types": "tsc --noEmit --watch",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "node scripts/build-docs.mjs && tsup"
+    "prepublishOnly": "node scripts/build-docs.mjs && node scripts/build.mjs"
   },
   "dependencies": {
     "@base-ui/react": "^1.6.0",

package/skills/vantage-add-feature/SKILL.md

@@ -16,8 +16,8 @@ CLI は雛形を出すだけで、規約の遵守はこちらの責任。**追
 ```bash
 vantage add page  <name>    # ルートページ(.tsx)
 vantage add api   <name>    # server/api/**.ts の API モジュール
-vantage add ui    <name>    # registry から UI ソースを components/ui/ にコピー
-vantage add block <name>    # registry からブロックを components/blocks/ にコピー
+vantage add ui    <name>    # registry から UI ソースを components/ui/ にコピー(src/ があればその中)
+vantage add block <name>    # registry からブロックを components/blocks/ にコピー(同上)
 ```
 
 `--force` で既存ファイルを上書き。`add` の雛形は import に `@squadbase/vantage` を焼き込む。
@@ -25,12 +25,18 @@ vantage add block <name>    # registry からブロックを components/blocks/
 ## ページを追加する
 
 ```bash
-vantage add page monthly-analysis        # → ./monthly-analysis.tsx  → ルート /monthly-analysis
-vantage add page sales/index             # → ./sales/index.tsx       → ルート /sales
+vantage add page monthly-analysis        # → monthly-analysis.tsx  → ルート /monthly-analysis
+vantage add page sales/index             # → sales/index.tsx       → ルート /sales
 vantage add page "sales/[customerId]"    # → 動的ルート /sales/:customerId
 ```
 
-出力される雛形は `definePage` + デフォルトエクスポートのコンポーネント。ファイル名の規約:
+**引数はページルートからの相対パス**(= ルートそのもの)。`add` は置き場所を自分で判断する ―
+プロジェクトに `src/` があれば `src/monthly-analysis.tsx`、無ければ直下に書く。手でファイルを
+作るときも同じ規則で、**混ぜてはならない**(`src/` があるのに直下に置くと `SRC_DIR_SPLIT`
+エラー。詳細は AGENTS.md の「ディレクトリ構造」)。
+
+出力される雛形は `definePage` + デフォルトエクスポートのコンポーネント。ファイル名の規約
+(ページルートからの相対パス):
 
 | ファイル | ルート | 用途 |
 | --- | --- | --- |
@@ -51,6 +57,9 @@ vantage add page "sales/[customerId]"    # → 動的ルート /sales/:customerI
    - 表示ルート `/foo/:id`
    - リンク `to="/foo/$id"` + `params={{ id }}`、取り出しは `const { id } = useParams()`
 4. `components/`・`hooks/`・`lib/`・`server/`・`public/` はページにならない(ルート走査対象外)。
+   **それ以外のディレクトリ名はそのまま URL のセグメントになる** ― `pages/`・`app/`・`utils/`
+   のような足場ディレクトリを切ると `/pages/report` のような URL ができる
+   (`SUSPICIOUS_ROUTE_DIR` 警告)。ページでないモジュールは上の 3 つに置く。
 
 ## API を追加する(fullstack)
 

package/skills/vantage-app/SKILL.md

@@ -19,14 +19,17 @@ description: Vantage(@squadbase/vantage)ダッシュボードアプリを一か
 3. **データを繋ぐ** — 外部 API か、自前の `server/api` か
 4. **仕上げ** — `check` → `build` → `preview`
 
-**各段階の終わりに `vantage check` を通す。** 静的診断(禁止ファイル・ルート衝突・境界違反・
-API export・env 誤用)はユーザーコードを実行しないので速く、エラーがあれば exit 1 になる。
+**各段階の終わりに `vantage check` を通す。** 静的診断(禁止ファイル・`src/` の分裂・ルート
+衝突・境界違反・API export・env 誤用)はユーザーコードを実行しないので速く、エラーがあれば
+exit 1 になる。
 まとめて最後に回すと、原因の切り分けが難しくなる。
 
 ## Step 1 — 骨組み
 
 新規なら `package.json` と `index.tsx` の 2 ファイルだけ。設定ファイルは**作らない**
-(`vite.config.*` 等は `vantage check` がエラーにする)。
+(`vite.config.*` 等は `vantage check` がエラーにする)。ページを `src/` にまとめたいなら
+`src/index.tsx` にする ― **`src/` があればページ走査はその中だけ**になり、直下に残した `.tsx`
+は無視される(`SRC_DIR_SPLIT` エラー)。どちらか一方に寄せること。
 
 ```json
 {
@@ -41,7 +44,7 @@ API export・env 誤用)はユーザーコードを実行しないので速く
     "routes": "vantage routes"
   },
   "dependencies": {
-    "@squadbase/vantage": "^0.2.0",
+    "@squadbase/vantage": "^0.3.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   }
@@ -54,8 +57,9 @@ API export・env 誤用)はユーザーコードを実行しないので速く
 **既存アプリに合流したときは、作る前に現状を読む:**
 
 ```bash
-vantage routes     # 既にあるページと API の URL マップ
+vantage routes     # 既にあるページと API の URL マップ(file 列がページの置き場所)
 vantage check      # いま壊れていないか(これから出すエラーと切り分ける)
+ls src/            # あればページは src/ の中だけ。無ければプロジェクトルート直下
 ls server/         # あれば fullstack モード。無ければ SPA
 vantage add skill  # 配置済みの skill(このファイルの仲間)と、その場所
 ```

package/templates/AGENTS.md

@@ -22,6 +22,9 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 
 ## 不変条件(破ると静かに壊れる)
 
+- **ページは `src/` の中か、プロジェクトルート直下か、どちらか一方。** `src/` があれば走査は
+  `src/` だけになり、ルート直下に残した `.tsx` は無視される(`SRC_DIR_SPLIT` エラー)。
+  新しいファイルは既にある側に置く(→「ディレクトリ構造」)。
 - **設定ファイルを作らない。** `vite.config.*`・`tailwind.config.*`・`postcss.config.*`・
   `components.json`・`vantage.config.*` はすべて禁止。存在すると `vantage check` がエラーにする
   (`FORBIDDEN_FILE`)。テーマ調整は `styles.css` のトークンで行う。
@@ -39,6 +42,43 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
   ため、変数・関数呼び出し・テンプレート補間は使わない。`page` エクスポートはランタイムでは
   読まれない。
 
+## ディレクトリ構造(ページをどこに置くか)
+
+**ページの置き場所は 2 通りあり、`src/` があるかどうかだけで決まる。混ぜてはならない。**
+
+- `src/` が**ある** → ページは `src/` の中だけ。ルート直下に置いた `.tsx` はルートにならず、
+  `SRC_DIR_SPLIT` エラーになる。
+- `src/` が**無い** → ページはプロジェクトルート直下。
+
+**ファイルを足す前に `src/` の有無を確認し、既にある側に置く**(`ls` するだけでよい)。URL は
+どちらでも同じで、`src/` は URL に現れない(`src/sales/index.tsx` → `/sales`)。
+
+```text
+root/
+├── src/                    # ある場合、ページはこの中だけ(無ければ以下が root 直下)
+│   ├── index.tsx           # /
+│   ├── monthly-analysis.tsx  # /monthly-analysis
+│   ├── sales/index.tsx     # /sales
+│   ├── _layout.tsx         # ルートレイアウト
+│   ├── components/         # ページ走査の対象外(URL にならない)
+│   ├── hooks/  lib/        # 同上
+│   └── styles.css          # 任意のグローバル CSS
+├── server/                 # 常にプロジェクトルート直下。src/ の中ではない
+│   ├── api/…               # /api/*
+│   └── utils.ts
+├── public/                 # 静的ファイル。常にプロジェクトルート直下
+├── package.json            # managed
+└── tsconfig.json           # managed
+```
+
+- **`server/` と `public/` は常にプロジェクトルート直下。** `src/server/` は決してスキャン
+  されない(`SRC_DIR_SPLIT` エラー)。
+- **`styles.css` はページと同じ側**に置く(`src/` があれば `src/styles.css`)。
+- **ディレクトリ名はそのまま URL のセグメントになる。** `pages/`・`app/`・`utils/` のような
+  足場ディレクトリを切ると、その名前が URL に出る(`pages/report.tsx` → `/pages/report`)。
+  `SUSPICIOUS_ROUTE_DIR` 警告で知らされる。ページでないモジュールは `components/`・`hooks/`・
+  `lib/` に置く ― この 3 つ(と `server/`・`public/`)はどの階層でも走査されない。
+
 ## import サブパスの地図
 
 | import 元 | 提供するもの |
@@ -82,7 +122,7 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
     "routes": "vantage routes"
   },
   "dependencies": {
-    "@squadbase/vantage": "^0.2.0",
+    "@squadbase/vantage": "^0.3.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   }
@@ -108,12 +148,15 @@ pnpm check    # 静的診断(エラーがあれば exit 1)
 pnpm routes   # ページ/API の URL マップ
 ```
 
-`server/` ディレクトリが無いので、この構成は **SPA モード**。
+`server/` ディレクトリが無いので、この構成は **SPA モード**。ページを直下に置く形だが、
+`src/` を作ってその中に集めてもよい(テンプレートから始めた場合は最初から `src/` がある)。
+どちらか一方に寄せること(→「ディレクトリ構造」)。
 
 ## ルーティング規約(ファイル名 → ルート)
 
-ルートディレクトリ直下の `.tsx`/`.jsx` がそのままページになる。各ページは**デフォルト
-エクスポートの React コンポーネントが必須**(無いと `MISSING_DEFAULT_EXPORT`)。
+ページルート(`src/` があればその中、無ければプロジェクトルート)からの相対パスが、そのまま
+URL になる。各ページは**デフォルトエクスポートの React コンポーネントが必須**(無いと
+`MISSING_DEFAULT_EXPORT`)。以下の「ファイル」列はページルートからの相対パス。
 
 | ファイル | ルート |
 | --- | --- |
@@ -125,7 +168,8 @@ pnpm routes   # ページ/API の URL マップ
 | `_404.tsx` | Not Found ページ |
 | `_error.tsx` | ルートが throw したときのエラーページ |
 
-`components/`・`hooks/`・`lib/`・`server/`・`public/` はルート走査の対象外(ページにならない)。
+`components/`・`hooks/`・`lib/`・`server/`・`public/` はどの階層でもルート走査の対象外
+(ページにならない)。それ以外のディレクトリ名は URL のセグメントになる(→「ディレクトリ構造」)。
 
 ```tsx
 import { definePage } from "@squadbase/vantage"
@@ -302,7 +346,7 @@ vantage search テーブル --limit 5 --json    # 機械可読(slug + score + sn
 ## 検証・ビルド・プレビュー
 
 ```bash
-pnpm check     # 静的診断(禁止ファイル・ルート衝突・境界・API export・env 誤用)
+pnpm check     # 静的診断(禁止ファイル・src/ の分裂・ルート衝突・境界・API export・env 誤用)
 pnpm routes    # ページ + API の URL マップ
 pnpm build     # dist/ に client(+ server)+ vantage-manifest.json
 pnpm preview   # 本番ビルドをローカル実行